Autopilot

Autopilot is a standalone Pi extension package for dependency-cleared child-agent orchestration. It provides /autopilot, session binding/handoff, coordination diagnostics, scheduler configuration, deterministic close/abort, the parent context_budget gate, Quality vNext contracts, perfect-quality doctrine, scope/protected-path adjudication, work-item lifecycle, terminal closure, runtime close/merge/abort, forced-output/status, state-store, isolated per-unit worktrees, and execution audits, the autopilot-agent-run child runner, and the compiled autopilot-coordinator transactional local broker. Durable run supervisors and session fencing through explicit generations preserve run and child ownership across Pi session replacement.

Install

pi install npm:pi-autopilot
# or during local development
pi install .

Commands

• /autopilot <workstream> [task intro/current focus] starts or resumes an Autopilot parent session. The rendered parent prompt requires context_budget before reading project files, runtime state, or launching child work. A successful activation records the current workstream for later /autopilot-handoff in the same session.
• /autopilot-inject <workstream> refreshes the current Pi session's Autopilot binding for an existing or newly prepared workstream without queueing the parent prompt. Use it after resuming a Pi session when /autopilot-handoff needs the active workstream restored. It activates context_budget and records the active workstream/run, but does not launch children, mutate source files, run tests, call providers, or write handoff artifacts.
• /autopilot-onboard <workstream> [handoff refs/notes] is the read-only onboard prompt command and generates a paste-ready /autopilot <workstream> onboarding block from supplied handoff refs or notes. It is read-only and must not launch children, mutate files, run tests, or call providers.
• /autopilot-handoff [optional comments] renders the handoff prompt and asks the active Autopilot parent to stop launching new work, write/update compact handoff artifacts under the current workstream runtime root, and finish with a full /autopilot <workstream> resume block. The workstream is taken from the active /autopilot or /autopilot-inject session; operators do not pass it to the handoff command.
• /autopilot-config show prints the active workstream scheduler config; /autopilot-config parallel-cap <n> persists parallel_cap in the range 1..32 under .pi/autopilot/<workstream>/scheduler-config.json (default 8).
• /autopilot-close <workstream> [--run <workstream_run>] [--dry-run] runs the package-owned close/merge lifecycle. It validates closure evidence, Phase 2 unit merge evidence, execution commit evidence, target-branch cleanliness, foreign/manual target changes, validation staleness, and source/worktree cleanliness before locally fast-forwarding the captured target branch. It releases retained claims, writes merge/ack/close evidence, archives runtime artifacts, removes only the run-owned terminal unit worktrees/main worktree/active task directory, repairs or verifies only exact run-owned stale Git worktree metadata without a global prune, verifies no run-owned path remains, and retires the branch only after a successful local merge. It does not fetch, push, create PRs, call providers, or let the parent/model mutate the operator source checkout or remotes.
• /autopilot-abort <workstream> [--run <workstream_run>] [--dry-run] archives an abandoned clean workstream without merging. It refuses dirty source paths, releases retained claims, archives runtime artifacts, performs the same run-owned worktree/task-directory/Git-metadata cleanup without landing changes, and retires the branch to an aborted archive ref so stale runs do not keep path ownership forever.
• /autopilot-claim-gc --dry-run|--apply is limited to evidence-backed diagnosis/repair of legacy JSON migration inputs. Normal Fabric leases reconcile automatically; this command is not the contention or terminal-release path.
• /autopilot-coordination status|doctor queries the authenticated local coordinator without starting an LLM turn. Status reports durable runs, session/child leases, acquisition groups, commit/blob/tree-bound observations, edit leases, change reservations, reservation obligations, fenced terminal intents, claim requests, mailbox cursors/counts, and accepted reconciliation evidence; doctor additionally reports pending integration obligations and prepared terminal intents without releasing WRITE authority from age alone.

All commands use package-owned prompt sources and Autopilot names only.

Coordination Fabric Phases 27–35

The package ships strict Fabric contracts plus a real local transactional coordinator. autopilot-coordinator is a single-writer, authenticated, versioned, length-delimited IPC broker backed by package-owned SQLite in WAL mode. It enforces foreign keys, bounded contention, optimistic versions, idempotency keys, monotonic per-repository event sequences, startup/post-migration integrity checks, verified pre-migration backups, deterministic export, user-private capability/socket/database paths, crash restart, and loud protocol/schema/store failures with no JSON fallback.

S1 compatibility separates the truthful implementation build 1.2.0-s1, wire lineage protocol-1.6-api-schema-12, API schema 12, private store schema 13, and legacy façade build 1.1.8-cf50. Every socket begins with the exact cf50 empty handshake. An unchanged cf50 peer remains legacy-anonymous-protocol-1.6 and receives only cf50 actions and response grammar. An S1 peer follows handshake → negotiate-admission → operation on one socket and becomes negotiated-s1 only after verifying a domain-separated HMAC-SHA256 over canonical JSON. The attestation uses the raw 32-byte capability key and binds both actual builds, requested/granted vocabulary, nonce, lifecycle identity, exact legacy-lock/runtime-sidecar byte digests, and store generation. When the offer is absent, the S1 client accepts only the exact digest-pinned known-cf50-predecessor path; it never infers compatibility from semver or protocol alone and never falls back after an offered negotiation fails. cf50 preserves every historical operation and child while accepting a superseded preflight rollback only after an exact later committed recreate→materialize→quarantine→archive chain, immutable operation evidence, current quarantined attempt/child authority, and exact clean Git HEAD/ref/common-dir proof. It also retires a history-free terminal migration shadow only when the removed deterministic projection owns one exact committed remove, no child or attempt ever used that shadow, and the physical path, registration, and branch are absent; both transitions publish immutable bounded audit evidence and repeat as no-ops. cf49 resolves both source-manifest and compiled client contexts through one verified package root to the same contained compiled JavaScript bootstrap and coordinator. Package identity drift, symlinks, path escape, or a missing compiled payload fail before spawn; production never falls back to TypeScript, PATH, cwd, another installation, or a repository checkout. Its built-ins-only bootstrap publishes private bounded atomic bootstrap/import evidence before dynamically importing the compiled coordinator, so pre-CLI module failures retain the spawned PID, exact selected entrypoint, exit outcome, sanitized cause, and explicit truncation fields without gaining coordination authority. cf48 keeps waiting after a clean exit only when the durable exact-current lock (including its secret token) and exact process-birth identity prove the same stable winner; it revalidates that identity until the original readiness deadline and accepts only the endpoint that attests it. The bounded atomic startup report is diagnostics only and never grants, transfers, or revokes authority. Startup failures now retain PID, exit code/signal, phase, lifecycle candidate, last transport failure, bounded redacted cause, and explicit truncation evidence through the worktree-preparation notification. cf47 forward-recovers committed pre-spend rollback projections only when the deterministic unit worktree and branch are absent and no child ever launched for that attempt; partial index/branch/attempt cleanup resumes idempotently under the cleanup lock. The heartbeat continues renewing and draining mailbox evidence while a typed owned-recovery blocker closes source-changing dispatch, then announces readiness after recovery. The archived cf47 boundary certified real-cf45 replacement, but S1 deliberately closes that path: after real-cf45 socket loss, concurrent S1 clients preserve the exact pre-cf50 process and lock without signaling or replacement. cf46 makes startup readiness endpoint-first: an election-loser child may exit only after the client attests the winner’s exact build and lifecycle identity, while genuine child death without an exact endpoint fails quickly. A known exact process whose socket remains unavailable after lifecycle-election-serialized repeated probes is retired only through its immutable lock/token/instance plus OS process-birth identity; endpoint recovery always wins, identity drift fails closed, and the replacement reopens the same durable sessions, children, operations, and leases. Every operation still handshakes and executes on one socket. Owned worktree sagas now preserve the durable operation ID and exact action/report/verification phase across response loss, probe before retry, and never describe an unacknowledged applied effect as an external-action failure. Unsafe attachment probes retain their typed cause and bounded, provenance-labelled proof through server IPC and the extension notification; reconciling-report failure evidence is reported separately, with explicit truncation and credential redaction, while mutation remains closed. Migration and runtime share one deterministic worktree identity; exact schema-12 duplicate projections are transactionally and audibly retired before registration/observation, while authority or history drift fails closed. No lease or operation history is deleted. Build 1.1.0-cf42/protocol-1.5/schema-11 remains a losslessly migrated predecessor; schema-10 and schema-9 builds remain migration-only inputs. Migration/freeze/rollback and the 0.13.0-cf34 schema-6 upgrade choreography retain exact-build boundaries; 1.1.8-cf50 is the locked upgrade target.

Protocol 1.6 makes encoded bytes—not row counts—the wire invariant. Activation-time reconciliation mutations commit compact count/digest receipts and expose the exact ordered IDs through authenticated, scope/revision-bound pages. Mailbox drains freeze durable membership and immutable message projections, enforce a monotonic durable next ordinal, and page below a 786,432-byte target while stable message IDs preserve at-least-once UI delivery without duplicate coordinator effects. Run catalog, migration recovery, status, and doctor are byte-paged; doctor pins one observation timestamp for the scan. Every page is capped at 1,024 entities, every single entity is capped at 524,288 encoded bytes, and the exact outbound response parser plus the 1 MiB frame check run before mutation event/idempotency insertion. Oversized single entities and cursor drift fail loudly; no row is truncated, dropped, or fabricated. Schema 12 migrates cf42 reconciliation arrays in resumable 128-result transactions, preserving request digests and exact array order in durable receipts/details.

/autopilot and /autopilot-inject attach one durable run supervisor per workstream_run, then attach a Pi session at a new fencing generation, reconcile its owned durable state, and drain its durable mailbox before prompt dispatch. The bridge starts only from activation, heartbeats while active, writes a private session-authority context, and detaches on session shutdown. Every attached session has an unguessable lease capability in addition to its generation, so PID reuse or possession of stale identity fields cannot impersonate current authority. /autopilot-handoff defers fencing until the handoff artifacts have been written and the session shuts down; the old generation then becomes handoff-pending, and the replacement attachment consumes that transition while preserving run/unit ownership. autopilot-agent-run must register a fenced child lease before model spend. The parent session capability is consumed only by the runner preflight and is scrubbed before Pi child spawn. That child receives independent, process-bound derived authority, so it can heartbeat and commit terminal or recovery-required state after a legitimate parent handoff without granting the old parent session any mutation authority. Heartbeat expiry is recovery evidence only and never releases WRITE authority.

Phase 30 adds the package-owned ClaimNegotiationClient and complete end-to-end peer claim negotiation loop. One live requester submits its entire initial observation/WRITE/EXCLUSIVE authority group. READ entries become non-blocking observations only after their exact Git commit plus blob/tree identity is revalidated. WRITE entries are speculative edit intentions in isolated worktrees and may overlap; only bounded package-declared EXCLUSIVE critical sections create blocking-owner requests. Owner delivery and acknowledgement are durable. Active parent sessions expose the typed autopilot_respond_claim_request tool only after authenticated run-supervisor attachment; it resolves the current version by exact request id, proves the attached run is the durable owner, and submits either release-now or a bounded defer to a package-observable terminal condition. Release, release evidence, and requester notification commit atomically; the coordinator then re-evaluates complete groups in deterministic order and issues one incompatible 30-second grant-ready offer at a time. Only a live current-generation requester preflight can acknowledge that offer and receive the complete lease set. Offer expiry is driven by a package coordinator timer, requeues without losing durable age, and allows the next waiter to advance. Cancellation and attempt supersession are durable and idempotent. The Pi session bridge polls the mailbox on heartbeats, so online owners/requesters receive request, release, and offer messages without an operator repair command. Scheduler skips use the explicit waiting-for-peer-release state and retain exact request refs.

Phase 31 adds durable per-run delivery and contiguous acknowledgement cursors, at-least-once mailbox replay across owner/requester shutdown, handoff, and coordinator restart, plus automatic terminal-evidence reconciliation through a release-condition watcher. Accepted child-terminal, unit-merge, attempt-reset, quarantine-capture, run-close, and run-abort evidence is source-specifically parsed, identity-checked, hash-verified, and stored transactionally. New child terminal evidence is a parent-owned autopilot.child_terminal_acceptance.v1 artifact that binds the exact spec, status, receipt, execution audit, forced-output carrier, verdict, and child lease; DONE, PASS, NEEDS_FIX, and BLOCKED are transport-terminal once that chain is accepted. It releases only the exact run-owned leases whose typed condition is satisfied. Lease release, request transition, requester notification, complete-group re-evaluation, and bounded offer creation occur in the same coordinator transaction. Child completion remains authorized by its process-bound capability while both parents are offline. Coordinator startup replays durable terminal facts to repair a transition interrupted by an older process. Lifecycle consumers also persist a run-owned reconciliation intent beside authoritative runtime evidence before IPC; a resumed activation replays any such intent idempotently, then reconciles and drains the mailbox before parent prompt dispatch. Duplicate delivery is identified by stable message IDs and cannot duplicate coordinator effects; acknowledgement cursors survive session replacement. Dirty quarantine/preserve transitions first inspect tracked, untracked, ignored, nested-repository, and submodule state, then commit an immutable run-owned capture and archive ref with exact branch/common-dir proof; only that capture may satisfy quarantine-captured. Expired heartbeats remain classification evidence only and never satisfy a terminal condition or release ambiguous WRITE/EXCLUSIVE authority.

Phase 32 puts package-owned worktree and Git lifecycle mutations behind owner-scoped durable sagas. The coordinator stores immutable v2 worktree resources and operation intents, enforces exact run/unit/path/branch/common-dir ownership, one incomplete operation per worktree, monotonic probe→action→verification steps, optimistic resource versions, immutable verification evidence, and terminal state rules. Main/unit registration, sparse materialization, execution commits, unit mergeback, reset/abort, dirty quarantine capture, archive refs, branch retirement, worktree removal, exact metadata reconciliation, and close/abort cleanup use the saga runtime. A per-worktree process lock prevents old/new session executors from acting concurrently; every retry probes before acting, so response loss cannot duplicate an already-satisfied effect. Coordinator restart durably queues owner recovery messages, and activation, supervisor heartbeat, and runner preflight advance incomplete owned operations before dispatch. Dirty destructive transitions first create an immutable capture commit/ref; cleanup refuses dirty, unregistered, common-dir-mismatched, branch-moved, recreated, or foreign-run paths. Close and abort reject pre-existing incomplete sagas.

Phase 33 separates observations, speculative edit authority, bounded exclusives, and unlanded integration risk. autopilot.active_parent.v2 and autopilot.task_info.v2 persist exactly one per-run coordination authority (legacy-path-claims-v1 or coordinator-edit-leases-v1); old v1 rows migrate explicitly to legacy mode, and missing coordinator state never authorizes fallback. Coordinator-backed runner preflight acquires the complete initial lease set without writing legacy claim truth. Accepted autopilot.unit_merge.v1 evidence is hash/identity checked and, in one transaction, converted into exact changed-path reservations while all attempt observations and WRITE/EXCLUSIVE edit leases are released and waiting peers are notified. Reset, quarantine, abort, and prelaunch cancellation release authority without inventing reservations. Overlapping foreign reservations remain legal and do not block speculative launch. They create deterministic predecessor obligations and durable overlap/landing messages classified from actual changed paths, merge-tree, base-relative hunks, delete/modify facts, protected surfaces, and JSON semantic keys. Same-file disjoint hunks are integrated automatically in predecessor order and invalidate overlapping prior validation; mechanically major conflicts create bounded repair-routing evidence. The dependent run must supply hash-bound integration evidence plus a current independent validation PASS before close. Close proves the exact reservation-to-unit-merge path union, refuses active unit leases or unresolved obligations, prepares a reservation-set terminal intent that fences new dispatch, and atomically marks reservations landed or aborted with run terminal evidence.

Phase 34 persists a transactional wait-for edge for every live blocking request, resolves strongly connected cycles to a same-transaction fixed point, and records durable deadlock resolutions. Each attempt has one immutable initial acquisition group; later WRITE/EXCLUSIVE expansion is rejected, while materialization expansion is explicitly typed and observation-only; READ creates no ordinary edit wait edge and participates only when an overlapping bounded EXCLUSIVE critical section is active. Safe victims are selected mechanically by victim class, durable child checkpoint, starvation protection, live-cycle grant order, and stable identity; merge/reset/quarantine/archive/remove critical sections, dirty preflight worktrees, and non-preemptible running work are never cancelled as clean victims. Child registration/checkpoint transitions make running preemption reachable, heartbeat delivers a durable stop request, and edit authority remains until reset or immutable quarantine evidence. Cycles with no safe victim remain explicitly deferred-no-safe-victim at the earliest declared release condition and never become operator questions. Scheduling snapshots increment bypass_count exactly once per otherwise-eligible losing decision and give groups at MAX_GRANT_BYPASSES = 8 priority over newer groups whenever their complete set is free. The contradiction arbiter accepts only one hash-bound autopilot.planning_contradiction.v1 packet: each schema-valid mission/master-plan/task artifact must first be registered by its source run from exact Git HEAD, the coordinator assigns a non-participating adjudication attempt and delivers its bounded immutable source bundle through that run's authenticated claim, and only assignment-bound terminal child evidence from its durable unit worktree can complete adjudication. Evidence is read once with no-follow/identity/size checks and retained as an immutable coordinator BLOB; exact clauses must demand different final outcomes, all five alternatives must be exhausted, and every operational reason is rejected. Protocol 1.6 and database schema 12 expose observations, closed bounded EXCLUSIVE-operation contracts, reconciliation receipts/details, and mailbox delivery snapshots in addition to wait edges, resolutions, artifact registrations, adjudication assignments, contradiction packets, reservations, obligations, and terminal intents through status, doctor, and deterministic export.

Phase 35 supplies a durable, resumable, one-way migration and cutover while retaining the read-only canonical preflight as an explicit diagnostic consumer. migrate --dry-run strictly parses and hashes bounded legacy active rows, claims, JSONL audit inputs, worktree indexes, run/unit metadata, and exact Git HEAD/branch state without mutation. Coordinator inspection never opens the live source SQLite database: it copies a bounded db/WAL/SHM generation to a disposable directory outside the state root, verifies source inode/metadata/byte hashes before and after copy and query, inspects only that copy, and removes it. Schema 6, 7, 8, and 9 are accepted only with their exact package migration checksums; schema 10 adds non-blocking observations, and schema 11 conservatively classifies historical free-form EXCLUSIVE rows as legacy authority while requiring closed operation contracts for every new EXCLUSIVE. migrate --apply writes a globally enforced freeze token, refuses reachable undrained legacy or coordinator processes, snapshots every input, verifies a database backup, cross-checks and merges matching Phase 27–34 coordinator state, and rebinds legitimate old-session claims to durable run/unit/attempt ownership. Historical READ claims are excluded from active import only when a bounded no-follow snapshot proves either a later canonical attempt or an exact completed state/status/receipt/execution-audit chain with clean scope attribution; every proof artifact and digest is retained. WRITE/EXCLUSIVE release remains limited to stronger Git-backed terminal evidence. Ambiguous authority is imported and queued as typed supervisor recovery work. For schema-9 databases, READ records carrying genuine acquisition-time Git identity become observations. Unbound historical READ authority is retired with its original payload and associated recovery work preserved in immutable migration audit; no current checkout identity is retroactively assigned. WRITE/EXCLUSIVE authority remains untouched unless exact terminal Git evidence authorizes its existing recovery path. verify rechecks every source/Git hash, database invariant, filesystem path, Git root/common-dir/branch, immutable run resource, and import record; drift restores the exact pre-import boundary and requires a fresh snapshot. The per-repository migration lock resumes identity-fenced candidate, reclaim, release, and stale .reclaim residues after hard death; a live owner is never silently reclaimed. Recovery evidence is bounded, no-follow/ancestor-contained, file- and directory-fsynced where the platform supports it, published from a synced temporary inode, and safely resumed after death or a partial legacy final file. Pre-cutover rollback restores that boundary, preserves a history generation, and permits a fresh migration. cutover rechecks hashes again, commits one client-visible marker, promotes non-authoritative runtime projections, archives legacy mutable files with a read-only manifest, verifies coordinator/client health over IPC, and only then removes the freeze. Rollback is forbidden after the marker; repair is forward-only.

Slice 5 closes EXCLUSIVE as a package-owned critical-operation contract: at most one exact tracked owned file, a closed operation kind/id, a maximum five-minute expected interval, an exact paired WRITE attribution layer, a non-preemptible matching attempt checkpoint, and automatic EXCLUSIVE-only release at critical-section exit or trusted terminal recovery. Ordinary WRITE remains until merge/reset/quarantine. Doctor reports every retained operation, elapsed/overdue state, and explicitly records that age never authorizes release. Routine unit specs cannot create EXCLUSIVE authority, and malformed or broad runtime locks fail closed rather than being reclaimed from age.

Schema-changing package/coordinator replacement is separately locked to the executable aa3e377 / 0.13.0-cf34 protocol-1.2/schema-6 predecessor. Protocol 1.2 has no upgrade-control verb, so the target does not invent quiesce/resume acknowledgements. It authenticates exact status, drains to reported safe checkpoints, verifies a live preflight backup/migration rehearsal, and then—while that authenticated predecessor is still alive—takes BEGIN EXCLUSIVE, rechecks database readiness, creates/fsyncs the deterministic byte-exact final rollback copy, and commits an old-incompatible barrier bound to its digest. The barrier raises ABORT from durable INSERT/UPDATE/DELETE triggers on every schema-6 user table, invalidating already-prepared statements on open aa3e377 connections. Only after that journal boundary does the target identity-check and retire the exact predecessor (never suspension), migrate a private verified copy, and atomically publish schema 12 before startup/reconnect. A crash before barrier commit rolls back with the predecessor alive; a crash after commit leaves it alive but mechanically denied. Resume reconstructs the barrier intent from the upgrade-id-addressed backup, retires the exact old process if it remains alive, and publishes schema 12—no guardian or wall-clock freshness assumption is authority. Current lifecycle socket/lock/startup paths are generation-separated from 1.2. While schema 12 runs, the target maintains an exact old-format live-PID fence at the predecessor lock path; stale 1.2 can neither unlink the current socket/lock nor reopen the shared upgraded database. Fence handoff and every migration/restore/WAL/SHM replacement are serialized under lifecycle election. A failed target startup restores the final backup byte-for-byte and reports manual recovery: this package cannot truthfully restart an unavailable old binary. Unknown builds, ambiguous live identities, and incomplete cleanup fail closed. Prior protocols can only replay an exact existing idempotency result—never execute a new effect.

After cutover, activation, runner preflight, materialization, worktree sagas, close, and abort reconstruct runtime identity from coordinator-owned immutable run resources; _task-info.json remains a rebuildable local projection rather than coordination authority. They do not read or recreate archived coordination JSON. Every legacy writer has a freeze/cutover fence and fails loudly instead of falling back. Status, doctor, and deterministic export expose migration records and pending recovery work. Package source, packed payload, fixtures, broker, migrations, and tests are standalone production surfaces that reject closed-repository dependencies. Default offline SDK/RPC/package gates plus crash/chaos/scale lanes use isolated temporary state roots and no provider or network call.

Fixed model roster

Autopilot enforces one package-owned model/thinking assignment for every parent and child role:

Role	Model	Thinking
Parent/orchestrator	openai-codex/gpt-5.6-sol	xhigh
Strategy	openai-codex/gpt-5.6-sol	xhigh
Implement	openai-codex/gpt-5.6-terra	high
Validate	openai-codex/gpt-5.6-sol	xhigh
Fix	openai-codex/gpt-5.6-terra	high
Adjudicate	openai-codex/gpt-5.6-sol	xhigh
Bughunt	openai-codex/gpt-5.6-sol	xhigh
Extract	openai-codex/gpt-5.6-luna	high

/autopilot and /autopilot-inject select the parent assignment before preparing a worktree and fail loudly if the model, subscription authentication, or exact thinking level is unavailable. The spec-quality gate and prompt renderer reject child unit specs that deviate from the role assignment before model spend. Completed historical specs and their bound receipts/audits remain immutable; retries must use a new roster-compliant attempt.

Tools and runtime surfaces

• context_budget is the parent-session tool activated by /autopilot; it reports ok, halt, or unknown using the default 85% halt threshold unless configured otherwise.
• autopilot_emit_status is an internal child-only status tool made available by autopilot-agent-run; it is not registered as a parent-session command or normal parent tool.
• autopilot_materialize_context is an internal child-only sparse checkout helper. It grants READ materialization only, records claims/materialization evidence, enforces byte/path/conflict caps, and never grants WRITE authority.

Autopilot activation creates an isolated package-owned git main worktree per workstream under:

~/.pi/agent/autopilot/worktrees/<repo-key>/active/<workstream-run>/main/

New Autopilot worktrees are sparse by default. The package creates them with git worktree add --no-checkout, applies package-owned non-cone sparse checkout patterns, runs a disk gate before runtime/index mutation, snapshots the exact checkout profile in _checkout-profile.json, and refuses loudly instead of silently falling back to full checkout. Tracked-tree sizing streams and incrementally parses NUL-delimited git ls-tree records, so activation does not depend on Node's fixed child-output buffer and remains valid for repositories whose tracked-tree listing is many megabytes. The scan is pinned to the resolved HEAD commit so profile evidence cannot mix two revisions if the source branch moves concurrently. The default profile is claim-minimal: baseline package/project files plus the source paths a unit declares or safely materializes. Projects may opt into .autopilot/checkout-profile.json, or AUTOPILOT_CHECKOUT_PROFILE=/absolute/path, with explicit full mode only when the operator wants full checkouts and still passes the disk gate.

Runtime files live inside that main worktree under:

.pi/autopilot/<workstream>/

Source-changing implement/fix units run in deterministic sparse per-unit worktrees under ~/.pi/agent/autopilot/worktrees/<repo-key>/active/<workstream-run>/units/<unit-id>/attempt-<n>/worktree/; their authoritative status, receipt, evidence, audit, execution-commit, unit-merge, validation-staleness, and scheduler artifacts still live under the main runtime root above. Before cutover, cleanup evidence is also appended to the legacy repo worktree _ledger.jsonl; after cutover the coordinator saga/event store is the only mutable coordination truth and that legacy ledger remains archived read-only. Before child launch, scheduler and runner use one persisted autopilot.authority.v1 artifact derived from the exact worktree commit. It records WRITE edit intentions for owned_paths, exact commit/blob/tree observations for tracked read_only_paths plus source context/inspection refs, and any package-declared bounded EXCLUSIVE operation. Prose/untracked observations and ungrounded future-owned edits are rejected; tracked directory scope records file/byte counts and is capped. Explicit pre-cutover legacy runs consume the same derivation before writing validated legacy claim truth. Autopilot materializes that exact artifact into the unit and main worktrees, writes _materialization-ledger.jsonl and _materialized-paths.json, and creates parent directories for grounded future-owned files. Legacy-mode children may request capped tracked READ context through child-only autopilot_materialize_context. Coordinator-backed runs fail a missing READ path loudly so the run supervisor amends and reacquires a complete initial set; they never silently dual-write legacy claims. WRITE scope never expands silently: a child needing new edit authority must emit a blocker so the parent/spec can amend scope or create a new attempt. Shared run/session/child authority lives under ~/.pi/agent/autopilot/coordinator/ (coordinator.db plus WAL/SHM, generation-specific lifecycle/startup locks and socket/named pipe, the old-format compatibility fence, private capability, backups, exports, and session contexts). Unix modes are enforced; on Windows the package removes inherited broad ACLs and grants the current account full control on state/capability paths, uses a per-user generation-specific pipe name, and still requires the timing-safe capability proof on every frame because Node exposes no stronger portable named-pipe ACL API. Pre-cutover claim/worktree JSON under coordination/<repo-key>/ remains validated migration input, not a fallback for coordinator failure. Migration journals, freeze tokens, immutable snapshots, verified backup refs, and read-only archives live under migrations/<repo-key>/; one-way markers live under cutovers/<repo-key>.json. Autopilot validates and writes package-owned artifact paths for mission.md, master-plan.json, decision-log.jsonl, unit-specs/, authority/, statuses/, receipts/, execution-audits/, execution-commits/, unit-merges/, integration-analyses/, reservation-integration/, reservation-repairs/, validation-staleness/, rendered-prompts/, evidence/, state.json, events.jsonl, scheduler-config.json, close evidence, and handoff files. Unit specs require status, receipt, and evidence outputs to stay inside the matching workstream runtime root, and non-strategy child specs must reference durable mission/master-plan context before launch. Handoff prompts target handoff.json, handoff.md, and handoff-event-tail.jsonl in the active workstream root. The strict autopilot.handoff.v1 shape carries mission, master-plan, decision-tail/latest-decision, state/event-tail, status, and execution-audit refs so next sessions recover purpose before queues.

Contracts, templates, and state-store

The package ships schema-backed Autopilot contracts for unit specs, status entries, events, state, receipts, handoffs, autopilot.master_plan.v1, autopilot.decision.v1, autopilot.execution_audit.v1, and autopilot.execution_commit.v1. Unit specs also carry Quality vNext fields for quality profile, risk level, acceptance criteria, verification plan, closure criteria, and upstream refs. Semantic validation covers role/verdict coherence, owned-path status changes, fake-green command rejection, declared-command and witness coverage, evidence metadata, receipt hashes, provider identity, output freshness, runtime-root placement, durable planning refs, purpose-state coherence, and execution-audit fact/classification coherence.

Role templates and deterministic render helpers cover strategy, implement, validate, fix, adjudicate, bughunt, and extract units. Parent and child prompts include the package-owned perfect-quality contract: no band-aids, hacks, silent fallbacks, fake-green tests, fixture tampering, deferred consumers, or source-changing self-certification. State/lifecycle helpers keep source-changing work in transport-complete, audit-review, or validation-ready until execution audits are clean/adjudicated and each source-changing work item has its own referenced independent validation PASS; closure gates reject unresolved scope/protected-path exceptions, missing per-work-item validation, and missing final bughunt proof for high-risk or multi-lane work. The state-store helpers write state.json atomically, append events.jsonl monotonically, validate runtime references, and resume from bounded event tails under .pi/autopilot/<workstream>/.

Runner and CLI

autopilot-agent-run is the child runner CLI:

autopilot-agent-run [--dry-run] [--json] [--pi-executable <path>] <unit-spec.json>

The published bin launches compiled JavaScript under dist/src/cli/autopilot-agent-run.js; it does not execute TypeScript source from node_modules or rely on Node type stripping. Live runs also require the current private coordinator session context and register a child lease before model spend; a fenced old session, missing authority, PID/boot mismatch transition, or coordinator failure is loud.

The second compiled CLI is:

autopilot-coordinator status|doctor|export
autopilot-coordinator serve
autopilot-coordinator replay --replay-id <stable-id> --input <absolute-request-jsonl>
autopilot-coordinator upgrade-schema11 [--state-root <absolute-path>]
autopilot-coordinator migrate --dry-run|--apply --repo-key <key>
autopilot-coordinator verify|rollback|cutover --repo-key <key>
autopilot-coordinator recovery list|show|doctor|drain-stale-sessions --repo-root <absolute-path>
autopilot-coordinator recovery retain-authority --repo-root <absolute-path> --run <run> (--recovery-id <id>|--all)
autopilot-coordinator recovery release-with-evidence --repo-root <absolute-path> --run <run> --recovery-id <id> --source <source> --target-id <id> --evidence <absolute-json-path>

A bounded handshake, byte-paginated run-catalog, reconciliation details, generalized mutation-result details, migration recovery, durable mailbox delivery, status, and doctor keep every wire response below the IPC frame ceiling even when a repository has hundreds of durable runs or a migrated run owns tens of thousands of reconciliation identities. Run-catalog continuations read a bounded file-backed temporary snapshot, so concurrent new runs cannot drift into or invalidate an active scan. Nonempty reconciliation/result receipts and compact mailbox membership rows remain append-only audit truth; empty reconciliation is represented by absence rather than redundant receipt rows in every heartbeat/idempotency result; mailbox items reference immutable message content instead of duplicating full payload JSON. upgrade-schema11 is the explicit cf42→cf43 process boundary: it refuses active sessions, children, critical sections, or incomplete worktree operations; verifies a private schema-11 backup; rechecks the exact lifecycle/process identity; and signals only that exact drained cf42 process. It never edits the database, lock, socket, claims, messages, or worktrees; ordinary elected startup then takes the schema-11 backup and transactionally migrates to schema 12.

Wire-compatible package installation never drains, signals, or replaces a healthy coordinator. The obsolete activate-patch and patch-readiness commands and their signaling implementation are not shipped. A live actual cf50 coordinator remains authoritative and serves both cf50 and S1 clients until it exits naturally. Ordinary elected startup may publish S1 only after that exact predecessor has retired and the schema-changing writer/migration authority checks succeed. upgrade-schema11 remains a separate, exact schema-changing migration boundary; natural wire-compatible continuity does not weaken its drain, backup, process-identity, or writer fencing.

The historical unit-failure evidence ingress adapter (BUG-177) admits only the two exact pre-schema-10 reset/abort autopilot.unit_failure.v1 generations behind a trusted pre-schema-10 coordinator acceptance fence, normalizes the absent capture pair to null, and returns canonical facts without rewriting the original immutable bytes/digest. Quarantine/preserve historical evidence and any unproven/forged/oversized/extra-field evidence route to loud owned recovery and never release WRITE/EXCLUSIVE authority; the current producer/parser contract remains strict and requires explicit capture fields for all new evidence.

The separate opaque tool_call_id blocker is also resolved in cf46 through one shared receipt/terminal-acceptance contract: provider text is never split or normalized, arbitrary pipe placement round-trips exactly, runtime and JSON Schema both count a maximum of 200 Unicode code points, and both reject NUL. The parent session bridge heartbeat retries transient coordinator connection outages (coordinator-unavailable/contention/timeout) while the durable session lease remains valid instead of halting on a single socket blip, so a momentarily-unavailable coordinator socket no longer leaves the session attached-but-heartbeat-expired with authority unreleased; owned-recovery failures retain and retry a visible dispatch blocker without stopping lease renewal; only fenced/invalid authority, incompatible contracts, system-fatal failures, or genuine lease expiry halt loudly. The operation-authority-version invariant fences committed operations monotonically (worktree version >= authority_version) so a worktree that advanced through several committed operations no longer flags every earlier operation as a version mismatch, while in-flight operations remain strictly fenced to the exact current worktree version. Coordinator auto-start is certified through Pi’s declared installed manifest route (extensions/autopilot.ts), not by importing dist/src/extension.js directly; direct dist imports are not valid proof of the published extension boundary. Auto-start measures the readiness window from spawn (readinessTimeoutMs, default 30s) independently of the startup-lock window. It probes and validates exact lifecycle identity before consulting its own child PID. A clean child exit continues waiting only when the child’s bounded atomic report identifies an exact competing owner and the durable lock, full lock identity (including its non-disclosed token), and OS process-birth identity remain unchanged; exit code zero alone is never authority. Nonzero exit, signal death, absent/unknown/drifting candidates, or deadline expiry fail with structured bounded evidence. For an unavailable live actual cf50 endpoint, ordinary S1 startup fails closed and never signals, drains, replaces, or deletes the façade lock; only natural cf50 exit permits elected S1 startup. Recovery of an unavailable exact S1 endpoint remains identity- and lifecycle-fenced and cannot be reinterpreted as wire-compatible package activation. Startup never treats PID, timestamps, or lock age as authority, releases durable authority to make progress, or replaces an endpoint that recovered.

The recovery commands are the only public mutation consumer for imported ambiguous authority. They start or reuse a coordinator under an active migration freeze only through an explicit recovery client, attach a fenced recovery-only session, preserve authority by default, publish immutable bounded evidence before any release, reject cross-run work, and detach exactly. Recovery commands never signal the shared coordinator: apply, verify, rollback, or cutover retires it only while holding the global migration operation lock and only after proving every durable session and child across the shared database is drained. The same lock serializes recovery attachments against retirement; after writer authority is acquired, every non-target repository mutation is fenced so whole-database rollback cannot discard concurrent authority. --all is restricted to explicit authority retention for one reviewed run; evidence-backed release always targets one exact recovery row.

It uses the same absolute AUTOPILOT_STATE_ROOT override as tests and defaults to ~/.pi/agent/autopilot/. replay is the shipped operator producer for recovery corpora: it accepts only bounded canonical current-protocol idempotent mutation JSONL from a regular file, stages a digest-bound private inbox, and startup validates the complete corpus into SQLite before applying all effects and the schema-12 completion row in one transaction. The database completion is authoritative after restore; the symlink-safe filesystem receipt is only a derived projection, and inbox removal occurs last. The runner reads and validates an Autopilot unit spec, applies the deterministic Quality vNext spec gate before model spend, creates/resumes the deterministic per-unit worktree for source-changing implement/fix specs, rolls that worktree/branch back if later preflight fails before child launch, verifies that cwd is inside the registered Autopilot unit worktree, verifies a clean source baseline, derives/persists the canonical repository-grounded authority artifact and acquires only its exact observations/edit intentions/exclusives, builds the forced-output/status context against the authoritative main runtime root, renders the child prompt, optionally snapshots it, preflights stale status/receipt paths, and either dry-runs or launches Pi in RPC mode with the internal compiled status tool and worktree guard. Parent and child sessions may use local git inside registered Autopilot worktrees, including staging, commits, resets, restores, checkouts, cleanups, and rebases, but the guard rejects git whose effective cwd/work-tree is outside the active worktree plus explicit git remapping, remote/external subcommands, and shared branch/tag mutation. On completion the runner accepts matching status artifacts, receipt artifacts, and receipt-matching structured tool carriers, then writes an autopilot.execution_audit.v1 record under execution-audits/ and revalidates success statuses against the audit before transport acceptance; assistant text alone is rejected. Execution audits include committed-path deltas when a child creates in-worktree commits, and autopilot.execution_commit.v1 evidence captures either runtime-created commits, child-created commits, or mixed child+runtime ranges on the unit branch. Stable failure classes distinguish invalid specs, durable waiting-for-peer-release, Pi launch/runtime failures, missing structured output, invalid structured output, and non-success status verdicts, while runner output includes audit path/classification for parent semantic routing. Dirty baselines are attribution blockers only when they overlap unit-owned or protected surfaces; unrelated dirty paths are recorded as audit caveats instead of forcing a globally clean tree.

Autopilot's forced-output identity layer recognizes subscription Pi provider routes under openai-codex/*, anthropic/*, opencode-go/*, kimi-coding/*, and zai/*, but the fixed launch roster is stricter: parent and child execution uses only the three documented openai-codex/gpt-5.6-* assignments. Any role/model/thinking mismatch is rejected before child launch; OpenRouter and other metered frontier routes remain forbidden.

Close / merge lifecycle

/autopilot-close is deterministic runtime code, not a model prompt. It is local-only: no fetch, push, network, or PR creation. The close runtime requires the operator source checkout to be clean and on the captured target branch, blocks child launches by moving the run to merging, verifies that source-changing work has schema-valid state/master-plan/status/audit evidence plus independent validation, verifies that the final integrated diff equals the union of accepted autopilot.unit_merge.v1 changed paths for Phase 2 work, rejects remaining validation-staleness artifacts, blocks on unresolved mechanically classified reservation repair, foreign/manual target path intersections, and dirty/running/quarantined unit worktrees; automatically integrates landed clean/disjoint reservation predecessors and records validation staleness before final validation; merges the target branch into the workstream branch, fast-forwards the target branch, records coordinator terminal/reservation evidence (and only pre-cutover appends legacy autopilot.merge_event.v1/autopilot.foreign_merge_ack.v1 rows), releases retained authority, archives runtime evidence under ~/.pi/agent/autopilot/worktrees/<repo-key>/_archive/<workstream-run>/, removes only paths derived from the active row (active/<workstream-run>/main/ and terminal unit worktree/ paths), removes the active task directory after archive when only known metadata residue remains, removes exact stale git worktree entries only after canonical path/branch/common-dir ownership proof, never performs a global prune that could affect another run, verifies filesystem and git worktree list --porcelain residue, and retires the branch to autopilot/archive/<workstream-run>/main. /autopilot-abort uses the same runtime-owned archival/claim-release/cleanup machinery without merging and retires the branch to autopilot/archive/<workstream-run>/aborted. Worktree-local git freedom does not bypass close: final changed paths still require unit-merge evidence, execution-audit evidence, execution-commit evidence, and independent validation.

Default automated coverage is offline and no-spend: unit tests cover transactional storage, backups/integrity/export, IPC framing/authentication, idempotency, fencing, handoff, child leases, durable mailbox cursors/replay, offline owner/requester/both-offline recovery, startup reconciliation, terminal evidence watchers, all-or-nothing acquisition, request dedupe, defer/release, atomic notification, bounded offers, cancellation, supersession, starvation aging, generated wait-for graphs, deterministic safe-victim selection, no-safe-victim deferral, contradiction arbitration, and full migration/rollback/cutover rehearsal; multiprocess tests prove single-writer election, overlapping WRITE grants to independent processes without claim negotiation, a real EXCLUSIVE request→release→reacquire loop, disjoint-EXCLUSIVE no-synthetic-deadlock behavior, committed-state recovery after a hard coordinator kill, and seeded 5/10/32-process cohorts whose persistent clients execute randomized acquire/defer/retry/handoff/cancel/release and coordinator-crash interleavings, including operations issued concurrently over independent live sockets. Every helper mutation is separately driven and the production doctor runs full coordination invariants immediately after each commit. Crash tests hard-kill real subprocesses at replay staging/batch application, database completion, receipt projection, and inbox cleanup as well as migration boundaries; chaos tests exercise byte/Git drift, duplicate keys, final-file and parent-directory symlink refusal; and the scale gate startup-replays exactly 100,000 real current-protocol mutation events containing exactly 10,000 contested requests across 32 logical clients, parses deterministic export counts, measures DB+WAL+SHM, and times real status and mailbox-drain queries under the published limits. Packed-install tests execute both compiled bins and migrations in a generic repository, and separately load the actual declared extension manifest through the offline Pi SDK to exercise coordinator auto-start from node_modules. Existing fake Pi processes for runner scenarios including worktree registration, per-unit worktrees, same-parent edit intentions, scheduler cap/skip logic, runtime-owned unit mergeback, validation staleness, claim GC, run-owned worktree cleanup/exact metadata reconciliation, worktree-scoped git guards, execution audits, child-created commits, and execution-commit evidence; e2e smoke tests exercise the fake-Pi status/receipt/state path in an isolated Autopilot worktree; SDK tests load the extension in isolated Pi sessions; RPC tests use offline pi --mode rpc; package tests inspect manifest/docs/bin/payload; and pack:dry-run verifies the published files.

Development gate

npm run build
npm run typecheck
npm run test:package
npm run test:version-skew
npm run test
npm run pack:dry-run

Release QA also runs cross-platform packed installs, docs and closed-repository scans, security:scan, registry security:audit, deterministic CycloneDX sbom, and payload:check from this standalone repo.

Known limitations

Autopilot currently supplies the package extension, commands, context_budget, scheduler/runtime quality gates, isolated worktrees, runner/close/abort flows, the complete Coordination Fabric through verified one-way migration/cutover, the transactional coordinator, durable run supervisors, session/child leases, generation fencing, durable mailbox cursors/replay, handoff continuity, peer claim negotiation, automatic terminal-evidence reconciliation, owner-scoped recoverable Git/worktree sagas, transactional wait-for/deadlock handling, starvation aging, contradiction-only escalation arbitration, endpoint-attested startup recovery, transactional duplicate-worktree reconciliation, diagnostics, deterministic streaming export, multiprocess/crash/chaos/scale proof, cross-platform release CI, security/SBOM artifacts, and standalone packed-install coverage. Automatic predecessor termination is not mathematically handle-bound: Node exposes no portable pidfd/process-handle signaling API, so a residual identity-read-to-signal PID race remains. The path fails closed when process birth identity is unavailable; macOS additionally requires the declared system /usr/bin/python3 bridge to libproc. It does not include a compiled scheduler UI, PTY/TUI coverage, default automated live-provider execution, network push/PR creation, or hosted PR automation. Provider-backed child runs require explicit operator approval, subscription Pi channels, and the autopilot-agent-run path; the default package gate remains deterministic, offline, network-free, and isolated from user/global Pi state.