Amistio guides

`npm install -g @amistio/cli` installs both `amistio` and `amistio-host-helper`. Normal runner use still works without the helper.

Set `AMISTIO_HOST_HELPER_PATH=$(command -v amistio-host-helper)` on runner machines where the reviewed helper is intended.

Run `amistio host-helper status` to see protocol version, helper path, implementation, process supervision, PTY, sandbox, and secret-boundary status.

Run `amistio host-helper conformance` before claiming support. It checks handshake, command execution, request IDs, output bounds, and fail-closed unsupported PTY/sandbox behavior.

Run `corepack pnpm --config.verify-deps-before-run=false --filter @amistio/cli release:check` before npm publish. Root `verify` includes this gate for Amistio development.

The npm helper advertises Level 1 supervision only. PTY and sandbox requests remain unsupported until a native helper build enforces them.

Compatible helpers must implement `amistio.hostExecution.v1`, preserve request IDs, bound UTF-8 output, fail closed for unsupported capabilities, and keep provider credentials out of helper ownership.

Open the status page from the same origin and confirm the web app, server routes, and local port checks are healthy.

Create a pairing code in the active personal or organization project, then run `amistio import <code>` from an existing checkout, or use bootstrap for first-time clone setup.

Confirm local Git can clone the repository with your SSH key, credential helper, provider CLI, or keychain.

Set a supported provider token locally on the runner, then run `amistio tools` or refresh the Runner panel.

Install Git or restart the foreground, background, or startup-service runner from an environment where `git --version` works. On macOS, background services and GUI-launched terminals can have a different PATH than your interactive shell, so restart or reinstall the service after changing PATH.

Confirm the repository link is active, the work item is approved, and `amistio run --watch` is running from the paired repository.

The runner did not claim work, but a retryable project-status read failed. Keep the runner running so it retries on the next poll. If it repeats after a web/API deploy, update and restart the runner and check the status page.

Run `amistio runner repair` from the paired checkout to rotate the local runner ID, then start `amistio run --watch` again. Use `--clear-credential` only when the Runner panel tells you to create a fresh pairing code.

Amistio starts fresh when a tool session is one-shot, active elsewhere, failed, closed, or idle past six hours. This protects approved work from stale local AI context.

Check Runner panel policy details and the Task replay timeline. Disabled, paused, incompatible runner, duplicate in-flight work, unsafe paths, exhausted budgets, stale revisions, failed verification, protected surfaces, or review-required findings stop autopilot before claim.

Check the Runner panel capacity and lane details. A lane waits when its slot is busy, runner capacity is full, local resources are intentionally lowered, or equivalent implementation scope is already active in another worktree.

Update and restart the runner. Current runners use server-side atomic claim checks plus a local active-claim/worktree ledger before tool execution, so duplicate lane claims are skipped instead of continuing into renewal noise.

Current runners recover abandoned claims only after the API proves the previous owner is forgotten, missing, stale, offline, or lease-expired, then retry pending finalization with active lane capacity. Large recovery backlogs are budgeted per poll and adopted finalization claims use short replay leases, so fresh lanes can still claim eligible work. If you know an offline runner is dead, use Forget runner to remove it and release its non-terminal claims for normal compatible-runner selection. If no compatible runner exists, start or pair one; fresh live claims keep rejecting non-owner updates.

Generate a new code with Add runner and use the suggested `--runner-id` in the foreground, background, or startup-service command. Same-machine defaults otherwise resolve to one stable runner identity.

If a runner produces generated brain artifacts but the API is temporarily unavailable, the CLI stores a safe local finalization envelope in user-level Amistio state and replays it before claiming more work.

Older runners that do not advertise supported work kinds can keep claiming legacy work, but they will skip source-aware assistant and impact-preview work until updated.

Update and restart the local runner so its heartbeat advertises project-context refresh support before using the Context panel.

The runner keeps source local and fails the refresh when submitted context contains unsafe evidence, unsafe paths, or a map too large to store safely. Known failures such as `unsafe_context_path` appear as attention-needed guidance; deploy the latest web/API fix, update and restart the runner when applicable, then retry with bounded non-secret output.

Update and restart the local runner so its heartbeat advertises issue-diagnosis support before submitting a bug or operational issue.

Update and restart the local runner so its heartbeat advertises semantic brain-consolidation support before relying on automatic semantic cleanup or using Consolidate for AI duplicate review.

Update and restart the local runner so its heartbeat advertises app-evaluation scan support before using the Evaluate panel or hourly runner checks.

A newer manual or adaptive evaluation supersedes older queued or running scans for the same repository. Historical scans remain visible for audit, and current findings are updated only from successful scan ingestion.

App Evaluation scans are read-only. If a whole-app verification command would install dependencies, regenerate framework files, or create build artifacts, the scan records stale or missing evidence and asks for a separate Test-gate or implementation verification run instead of dirtying the checkout.

Normal runner polling can update bounded self-maintenance findings in Evaluate and run the blocker-elimination loop. Autopilot-disabled projects get reviewable unblock plans; autopilot-enabled projects may requeue safe rows or approve low-risk repair work under policy. Records include counts, trend, root-cause categories, and IDs instead of raw source, full document bodies, secrets, commands, or local paths.

Update and restart the local runner so its heartbeat advertises security-posture scan support before using the Security panel or daily runner checks.

Update and restart the local runner so its heartbeat advertises Test-quality and implementation-Test-gate support before using the Test panel or completing implementation work.

Update and restart the local runner if a structured app-evaluation result is rejected. The runner and workspace show safe validation paths for contract mismatches without exposing raw source or secrets.

Update and restart the local runner if a structured impact-preview result is rejected. The API returns safe validation paths for contract mismatches, and accepted results that cannot be stored safely are marked failed with a bounded reason instead of uploading raw source or secrets.

Keep a compatible paired runner running. The source-work finalization remains in the local outbox, queued implementation Test gates claim before unrelated work, and abandoned source claims recover with active lane capacity, bounded replay budgets, and short replay leases before replaying finalization.

Open the Test panel for the structured blocked finding and next verification steps. For Amistio's own monorepo, use `corepack pnpm --config.verify-deps-before-run=false verify` if plain Corepack pnpm fails before repository scripts with `spawnSync pnpm ENOENT`, then rerun the gate or record an audited override.

Open Test and Work for the dependency-remediation item. Amistio stores only bounded package/path evidence, keeps the work drafted until approved or audited by autopilot, and requires `corepack pnpm --config.verify-deps-before-run=false verify` before release resumes.

Check the Work and Runner panels for the sanitized environment profile and readiness summary. Missing Git, Node, Corepack, package managers, required scripts, dependencies, setup failures, Docker availability, invalid Docker envelopes, or unsupported profiles block the work before local tool execution.

Restart the foreground/background runner or reinstall the startup service with `--execution-profile hostWorktreeWithSetup --setup-package-manager-install` only when running the repository's fixed package-manager install step is acceptable for that checkout.

`dockerWorkspace` validates Docker availability and the safe worktree-only envelope, but current runners still mark the work blocked until containerized harness execution is implemented.

The runner repairs safe stale Git registrations when the target worktree directory is missing and Git marks the registration prunable. Other preflight setup failures retry up to `--max-preflight-attempts`, then fail the work item with the last safe error summary.

Put required local test config in an ignored root dotenv file such as `.env.test.local`. The runner copies eligible ignored dotenv files locally, but dependencies and local services remain your machine setup.

Confirm the paired checkout has a GitHub remote, Git commit identity, fetch/push permission, an authenticated local `gh` CLI, and no dirty or conflicting approved artifact target paths. New implementation work blocks before local AI/tool execution when these prerequisites are missing. Retry handoff can publish a clean preserved local-only commit without rerunning the implementation prompt; rebase conflicts capture safe repo-relative conflict files and try to abort the failed rebase, while dirty or ambiguous worktrees stay preserved.

Resolve the conflict intentionally before syncing over either the web record or the repo copy.