# Operations contract map

`docs/design.md` is the authoritative contract for every operator surface named here. This file
is a navigation map: it adds no rule, defines no term, and repeats no clause. Where anything here
disagrees with `docs/design.md`, `docs/design.md` wins and this map is wrong. `docs/operator-guide.md`
is the installed, version-matched excerpt surface; it is downstream of `docs/design.md` too.

## Operator commands

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| `/amq status`, `/amq inbox`, `/amq pause`, `/amq resume`, `/amq ingest`, `/amq trace`, `/amq dlq`, `/amq doctor` | [§12.1](../design.md#121-operator-commands) | `PiAmqRuntime` command registration | `extension/runtime.ts` | `test/extension-registration.test.ts`, `test/runtime-status.test.ts` |
| `/amq bind` and `/amq takeover` | [§12.1](../design.md#121-operator-commands), [§6.3](../design.md#63-dormant-to-confirmed-bind) | `ConfirmedBindOnboarding`, `ReceiverLeaseManager` | `integration/confirmed-bind-onboarding.ts`, `transport/receiver-lease.ts` | `test/confirmed-bind-onboarding.test.ts`, `test/receiver-lease.test.ts` |
| `/pi-amq-guide [topic]` and the `guide` tool | [§12.1](../design.md#121-operator-commands) | `InstalledPackageGuide`, `registerGuideTool` | `extension/guide.ts`, `docs/operator-guide.md` | `test/guide.test.ts`, `test/package/packaged-artifact-smoke.test.ts` |
| `/amq-new-task <id>` kickoff dispatch | [§8.3](../design.md#83-fresh-session-dispatch) | `PiFreshSessionReplacementPort`, `FreshSessionDispatcher` | `extension/runtime.ts`, `integration/fresh-session-dispatcher.ts` | `test/fresh-session-port.test.ts`, `test/fresh-session-dispatcher.test.ts` |
| `/pi-amq-cleanup` and the `cleanup_runs` tool | [§A.9](../design.md#a9-w3-primitive-and-gate-amendment) | `WorkflowRunCleanup`, `parseCleanupCommand` | `workflow/run-cleanup.ts`, `extension/runtime.ts` | `test/run-cleanup.test.ts`, `test/extension-registration.test.ts` — "cleanup command is dry-run by default and requires explicit delete syntax" |
| `/pi-amq-doctor` and the `workflow_doctor` tool | [§A.9](../design.md#a9-w3-primitive-and-gate-amendment) | `WorkflowDoctor` | `workflow/workflow-doctor.ts` | `test/workflow-doctor.test.ts` |
| Below-editor FleetView and its inspection ladder | [§A.6.2](../design.md#a62-worker-inspection-ladder-and-below-editor-fleetview) | `FleetListModel`, `handleFleetInput` | `integration/fleet-view.ts` | `test/fleet-view.test.ts` |
| UI-capability rules for prompts and dialogs | [§12.1](../design.md#121-operator-commands) | `PiAmqRuntime` | `extension/runtime.ts` | `test/extension-lifecycle-integration.test.ts` |

## Failure handling and recovery

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| Failure modes and required behavior | [§15](../design.md#15-failure-modes-and-required-behavior) | `InboxPump`, `BridgeJournal`, `InboxStatusStore` | `transport/inbox-pump.ts`, `transport/bridge-journal.ts`, `transport/runtime-status.ts` | `test/inbox-pump.test.ts`, `test/bridge-journal.test.ts`, `test/runtime-status.test.ts` |
| Lifecycle and recovery rules for runs and workers | [§A.5.3](../design.md#a53-lifecycle-and-recovery-rules) | `evaluateRunTransition`, `evaluateWorkerAttemptTransition` | `workflow/run-gate.ts`, `workflow/worker-gate.ts` | `test/run-gate.test.ts`, `test/worker-gate.test.ts` |
| Security and trust boundary for launched children | [§16](../design.md#16-security-and-trust) | `resolveWorkerLaunch`, `validateWorkerChildContext` | `workflow/worker-launch.ts` | `test/worker-launch-contract.test.ts` |

## Verification and release

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| Implementation sequence and verification | [§18](../design.md#18-implementation-sequence-and-verification) | repository suite (`npm test`) | `package.json`, `test/*.test.ts` | the suite is the evidence |
| Required fault-sensitive tests | [§Required fault-sensitive tests](../design.md#required-fault-sensitive-tests) | transport suite | `test/*.test.ts` | numbered `[doc N]` test titles |
| Addendum-specific fault-sensitive tests | [§A.8](../design.md#a8-addendum-specific-fault-sensitive-tests) | worker-runtime suite | `test/*.test.ts` | numbered `[appendix N]` test titles |
| Versioning and compatibility | [§17](../design.md#17-versioning-and-compatibility), [§17.1](../design.md#171-fresh-session-automation-compatibility-amendment) | `package.json#peerDependencies`, `CommandContextFreshSessionCapability` | `package.json`, `integration/fresh-session-dispatcher.ts` | `test/fresh-session-port.test.ts`, `test/package/packaged-artifact-smoke.test.ts` |
| Live two-terminal AMQ flow | [§18](../design.md#18-implementation-sequence-and-verification) | `scripts/demo-two-terminal.sh` | `scripts/`, `docs/demo-transcript.md` | `test/stock-amq-integration.test.ts` |

### Two suites, one boundary

`npm test` is the repository suite. It compiles `test/**/*.ts` and runs `.test-dist/test/*.test.js`
against the source tree in this checkout.

`npm run test:package` is the consumer-artifact gate. It runs `.test-dist/test/package/*.test.js`,
which packs the real npm tarball, extracts it into a staged `node_modules/pi-amq` tree, and loads
that extracted copy through the stock pi `--extension` seam.

Exact provenance matters here:

- the pi-amq extension under test is loaded only from the extracted tarball, so a path missing
  from `package.json#files` fails the gate;
- the repository still supplies the test-only probe extension and the already-resolved dependency
  tree the staged package links against;
- staging extracts the tarball, it does not run npm's installer, so npm's own resolution,
  lifecycle scripts, and peer-dependency handling are out of scope;
- every probe runs with `HOME` and `PI_CODING_AGENT_DIR` inside its staged workspace, so the gate
  never reads or writes the caller's `~/.pi` runtime state.

The gate is fail-closed. It needs a stock `pi` binary on `PATH` or at `PI_AMQ_TEST_PI_BINARY`;
without one it fails with a missing-binary diagnostic rather than reporting success on skipped
cases. The manifest case does not need `pi` and stays independently runnable.

Neither suite ships. `package.json#files` omits `test` and `tsconfig.test.json` on purpose: a
consumer installs the runtime surface, not the harness that verifies it. `test:package` is the
check that keeps that omission honest, because it only ever sees what a consumer receives.