agents-can-communicate 0.1.18 → 0.3.0

package/docs/HOW_IT_WORKS.md

@@ -0,0 +1,277 @@
+# How ACC works
+
+ACC is a local communication layer around AI sessions that the user opened independently.
+It gives those sessions a shared set of coordination facts without giving ACC ownership of
+their prompts, permissions, processes, or work.
+
+This page follows one interaction from client startup to an acknowledged answer. It is the
+engineering tour; [Protocol](PROTOCOL.md) is the normative record contract and
+[Architecture](ARCHITECTURE.md) is the package-level reference.
+
+## The whole system in one picture
+
+```mermaid
+flowchart LR
+  U["human direction and authority"] --> A["independent session A"]
+  U --> B["independent session B"]
+  A --> X["CLI, MCP, or adapter hook"]
+  X --> C["vendor-neutral core"]
+  C <--> S[("filesystem store outside the repository")]
+  C --> Y["B adapter hook or acc inbox"]
+  Y --> B
+  C --> R["optional live-delivery router"]
+  R -.-> B
+  B --> Z["CLI, MCP, or adapter hook"]
+  Z --> C
+```
+
+There is no required ACC daemon and no coordinator model. CLI commands and native hooks
+are short-lived local processes that open the same workspace store when needed. An MCP
+client may keep its own `acc-mcp` stdio child running, but that child is a tool boundary for
+one participant, not a scheduler or owner of the room.
+
+## 1. A client session joins a workspace
+
+For a native client, an installed startup hook sends the client event to `acc-hook`. The
+vendor adapter normalizes that event, then the hook runner:
+
+1. discovers the workspace;
+2. opens its filesystem store;
+3. resolves the exact client version and its certified capabilities;
+4. opens or resumes one ACC session generation; and
+5. stores a small binding from the client's session id to that ACC generation.
+
+Workspace discovery uses an explicit `acc.workspace.json` first, the Git common directory
+second, and the canonical plain directory otherwise. Git worktrees therefore share one
+room but keep separate checkout and branch facts. Git itself is optional.
+
+A participant is the address messages target. A session is one current opening of that
+participant, and its unguessable generation token prevents an old process from mutating a
+replacement session. The default participant name is derived from the client session. Set
+`ACC_PARTICIPANT` in the client launch environment when an address must survive a client
+restart and recover messages sent while it was away.
+
+Attaching one session does not create durable workspace history. Its presence and intent
+can remain ephemeral until a second live session appears or someone creates the first
+claim, message, or handoff. This is how ACC stays silent when a session is alone without
+making discovery unreliable when a peer arrives.
+
+## 2. Sessions publish awareness, not assignments
+
+An intent records a short summary, mode, and resource hints. A claim adds a leased
+reservation for a canonical resource such as `file:src/item.mjs` or `file:src/**`.
+Neither creates a task or grants one session authority over another.
+
+A claim is `guarded` only when every live client path involved has a captured pre-write
+guard. Otherwise it is `advisory`: visible coordination that peers should respect, but not
+an operating-system lock. Even a guarded claim cannot stop unrelated programs or a write
+path the client never exposes to its adapter.
+
+## 3. Sending commits the durable truth first
+
+When session A sends an addressed question, the CLI or MCP boundary validates the closed
+protocol shape and resolves A's current session generation. Core then performs one
+filesystem transaction that creates:
+
+- the immutable logical message, including sender, recipients, kind, obligation, thread,
+  and explicit body;
+- one `queued` receipt for each recipient; and
+- a `message.recorded` event.
+
+The first message in a thread uses its own `messageId` as `threadId`. A caller-supplied
+`clientMessageId` is a retry key: identical retries return the original message, while the
+same key with different content is rejected.
+
+For a room message, recipients are the known peer participants with open sessions at
+commit time. Participants arriving later can find the room record through full forensic
+sync, but they do not receive retroactive receipts.
+
+Only after the transaction commits may ACC try to make the message arrive sooner. Thus a
+crashed, unsupported, or unreachable adapter cannot erase a successfully recorded
+question.
+
+## 4. Delivery has three paths
+
+The paths share one durable record but prove different facts.
+
+### Durable inbox
+
+`acc inbox` is the universal recovery path. It returns only messages addressed to the
+calling participant and atomically advances that participant's receipt to `retrieved`.
+An exact `acc inbox --message message_x` remains usable after context compaction or when a
+message was too large to project safely.
+
+### Certified next-turn projection
+
+On an exact client version and platform with passing evidence, a before-turn hook asks core
+for queued messages just before the client's next normal turn. The adapter projects each
+complete body inside an attributed `untrusted peer message` frame. If the complete frame
+does not fit the configured byte budget, the hook keeps the message id and the exact inbox
+recovery command instead of silently truncating peer text.
+
+The hook entry point records `offered` only after its stdout transport reports that the
+bytes crossed the boundary. The state is not `retrieved`: ACC still has no observation
+that the model attended to those bytes.
+
+### Native live push
+
+The delivery router offers an actionable message to an already-running session when all of
+these hold at once:
+
+- exactly one live generation for the recipient;
+- an unexpired generation-bound delivery binding published by that session's own start;
+- a recorded policy permitting this message kind (`actionable` covers question, request,
+  answer, decision, and handoff; `all` adds note; room messages are never live);
+- an adapter that declares `delivery.livePush` and a native contract; and
+- adapter acceptance of the bytes.
+
+Any missing condition leaves the receipt `queued` and returns a safe fallback reason. Two
+adapters ship a native transport, both experimental and off until a per-client opt-in:
+
+```text
+sender -> durable ACC record -> exact live binding -> vendor transport -> receiver
+                             \-> queued inbox on every failure
+```
+
+- **Claude Code 2.1.258** uses a vendor Channel: an ACC-owned MCP child, started only when
+  the user's ordinary `claude` launch carries the captured development-channel flag, offers
+  the message as a native notification and routes the model's explicit `acc_reply` back as a
+  real ACC answer. Claude's development-channel warning is vendor-owned and stays visible.
+- **Codex 0.152.1** adds the message to the App Server thread queue over the vendor daemon's
+  control socket; it is presented on the idle thread or after the current turn. Codex answers
+  through the ordinary `acc reply` command, so its reply route is not native.
+
+Compatibility is decided at the launch-time bootstrap and again by a per-session handshake
+bound to the exact client process; there is no maximum client version, but a newer stable
+release must pass a current probe and handshake for the captured protocol, and an older,
+prerelease, known-bad, or uncaptured client stays durable-only. ACC is never the parent of
+a model session after the shell `exec`, and `ACC_BYPASS=1` starts the unmodified client.
+
+## 5. Reply closes the communication obligation
+
+The complete question-and-answer path is:
+
+```mermaid
+sequenceDiagram
+  participant A as Session A
+  participant Core
+  participant Store
+  participant B as Session B
+  A->>Core: addressed question for B
+  Core->>Store: message + queued receipt + event
+  Store-->>Core: transaction committed
+  Core-->>A: recorded with delivery outcome
+  alt certified next-turn
+    B->>Core: normal turn hook
+    Core-->>B: attributed untrusted envelope
+    Core->>Store: receipt offered after transport accepts bytes
+  else durable inbox
+    B->>Core: acc inbox for the message
+    Core->>Store: advance B receipt to retrieved
+    Core-->>B: attributed message and receipt
+  end
+  B->>Core: reply to the question id
+  Core->>Store: answer + A receipt + acknowledge B receipt
+  Core-->>A: answer through next-turn or inbox
+```
+
+`reply` verifies that B owns the original receipt, writes an `answer` in the same thread,
+creates the answer's receipt for A, and advances B's original receipt to `acknowledged` in
+one transaction. A transport failure after that cannot undo the reply. `ack` performs the
+last transition without creating an answer when the obligation only asks for
+acknowledgement.
+
+Receipts are per recipient and monotonic:
+
+```text
+queued -> offered -> retrieved -> acknowledged
+```
+
+`recorded` is the successful send boundary, not a receipt state. `offered` does not mean
+read, `retrieved` does not prove model attention, and `acknowledged` resolves communication
+only. A reply saying “I will do it” is not evidence that the requested work finished; ACC
+does not have accepted, running, or done task states.
+
+## 6. The filesystem is the control plane
+
+Each workspace lives below the platform data home, conceptually:
+
+```text
+<platform data home>/acc/workspaces/workspace_x/
+├── protocol.json          store version and workspace identity
+├── state/<kind>/<id>.json materialised current records
+├── events/<sequence>.json immutable semantic history
+├── journal/               crash-recovery authority
+├── locks/                 one cross-process writer mutex
+├── ephemeral/             non-durable presence, intent, and delivery bindings
+├── bindings/              client-session to ACC-generation mappings
+├── retained/              logical deletion and retired evidence
+└── tmp/                   staged atomic publications
+```
+
+This layout is diagnostic, not a public mutation API. Clients write through the protocol
+and core rather than editing these files.
+
+On macOS the platform data home is `~/Library/Application Support`; on Linux it is
+`$XDG_DATA_HOME` or `~/.local/share`. `ACC_DATA_HOME` replaces that base. Runtime paths are
+checked against workspace roots so ACC state cannot be placed inside the project.
+
+Every durable mutation holds the same writer mutex, loads only its declared record kinds,
+checks state generations, stages the full result, and writes a recovery journal before
+publishing. Events are immutable no-replace files; current state is a materialised view
+replaced atomically. While publication is incomplete, the active journal bounds event
+cursors below the transaction's first sequence; the next store opener rolls a decided
+transaction forward before serving a read. The store prefers a recoverable duplicate offer
+after a crash to an unearned delivery claim.
+
+Paths are opened with containment and no-follow checks. Corrupt records, a foreign
+workspace identity, and unknown store versions fail before mutation rather than being
+guessed into a compatible shape.
+
+## 7. Adapters translate evidence, not product semantics
+
+The vendor-neutral layers know nothing about Codex, Claude Code, Gemini CLI, Grok, or Kimi
+Code. `protocol` owns record shapes and state transitions; `core` owns coordination rules;
+`storage-filesystem` owns persistence. Vendor adapters own hook payloads, installation,
+client-specific response shapes, and captured capability evidence. `hook-runner` applies
+the common bounded fail-open lifecycle, while `delivery-router` evaluates optional live
+delivery.
+
+Unknown client versions and platforms inherit no capability. A method in an adapter or a
+vendor documentation example is not enough: every `true` capability needs a retained
+real-client fixture. This is why the same product can degrade visibly from next-turn
+projection to inbox polling without changing its message or receipt semantics.
+
+## 8. What crosses the trust boundary
+
+ACC stores only explicit coordination data: identity, presence, one-line intent, claims,
+messages the sender chose to send, structured handoffs, receipts, artifacts, and events.
+It does not collect raw prompts, assistant responses, transcripts, environment variables,
+credentials, or permission approvals.
+
+Peer bodies remain untrusted data. The projector attributes the sender, escapes framing
+and terminal control sequences, and never promotes peer text to system authority. The
+receiving session still evaluates it under its own instructions and permissions.
+
+Every native hook has a five-second ceiling and fails open: if ACC cannot read the store or
+decide safely, the client's action continues. Coordination may become less effective, but
+ACC itself must not stop a session from working.
+
+## Trace the implementation
+
+The shortest source-code path is:
+
+1. `packages/hook-runner/src/runner.mjs` — attach, before-turn projection, guards, and the
+   fail-open boundary;
+2. `packages/core/src/conversations.mjs` — record-first messages, threads, receipts, and
+   handoffs;
+3. `packages/core/src/inbox.mjs` — recipient-owned retrieval, reply, and acknowledgement;
+4. `packages/delivery-router/src/router.mjs` — policy, reachability, certification, and live
+   fallback;
+5. `packages/storage-filesystem/src/store.mjs` — transactions, snapshots, ephemeral state,
+   and recovery; and
+6. `packages/adapter-sdk/src/context-projector.mjs` — bounded untrusted peer framing.
+
+Continue with [Capabilities](CAPABILITIES.md) for what each shipped client actually proves,
+[Security model](SECURITY_MODEL.md) for trust boundaries and attack tests, and
+[Adapter authoring](ADAPTER_AUTHORING.md) for the integration contract.

package/docs/MCP.md

@@ -0,0 +1,94 @@
+# MCP
+
+`acc-mcp` lets a client with no native ACC adapter participate over stdio. It exposes the
+same durable messages, threads, receipts, intent, claims, and handoffs, but it cannot infer
+the client's lifecycle, intercept writes, inject a normal turn, or push a message. The
+client polls tools under its own control.
+
+```mermaid
+graph LR
+  C["independently opened MCP client"] -->|"stdio JSON-RPC"| M["acc-mcp"]
+  M --> S[("ACC durable store")]
+```
+
+## Register
+
+```json
+{
+  "command": "acc-mcp",
+  "env": {
+    "ACC_MCP_PARTICIPANT": "research",
+    "ACC_MCP_WORKSPACE": "/absolute/path/to/project"
+  }
+}
+```
+
+`acc-mcp` accepts no command-line arguments. `ACC_MCP_PARTICIPANT` is the stable recipient
+identity for this server. It comes from user-owned launch configuration, never from MCP
+`initialize` or `clientInfo`. `ACC_MCP_WORKSPACE` should be absolute; without it, the
+server uses its launch directory, which may be a different workspace from the other
+sessions.
+
+The server implements MCP protocol revision `2026-07-28` over newline-delimited JSON-RPC
+stdio. Tool input schemas are closed: unknown fields and invalid conditional shapes are
+rejected before a session is resolved.
+
+## Tools
+
+| Tool | Required input | Optional input |
+|---|---|---|
+| `acc_status` | — | — |
+| `acc_sync` | — | `cursor`, `scope: delta|full`, `limit: 1..500` |
+| `acc_work` | `summary` and `mode`, or `clear: true` | `state`, `resourceHints` |
+| `acc_claim` | `action`; `resource` for acquire, `claimId` for renew | `mode`, `reason`, `leaseSeconds` where valid |
+| `acc_release` | `claimId` | — |
+| `acc_message` | `to`, `subject`, `body` | `kind`, `obligation`, `clientMessageId` |
+| `acc_request` | `toParticipantId`, `title` | `detail`, `clientMessageId` |
+| `acc_inbox` | — | `messageId` |
+| `acc_reply` | `messageId`, `body` | `subject`, `clientMessageId` |
+| `acc_ack` | `messageId` | — |
+| `acc_finish` | `goal` | `status`, `completed`, `remaining`, `blockers`, `toParticipantId`, `clientMessageId` |
+
+All tool names above are the complete model-facing surface. There are no execution or
+client-control tools.
+
+Send-like tools return a raw structured object with `{ message, delivery }`; their text
+content is the JSON serialization of the same value. `acc_inbox` returns message/receipt
+pairs and advances only this participant's receipts to `retrieved`. `acc_reply` writes an
+`answer` and acknowledges the original atomically. `acc_ack` exposes no receipt-state
+parameter.
+
+Resources are `acc://snapshot`, `acc://roster`, and `acc://inbox`. Reading `acc://inbox`
+resolves the configured MCP participant and advances only the returned receipts to
+`retrieved`, just like the inbox tool. Snapshot and roster reads do not advance receipts.
+A full snapshot is for explicit workspace forensics.
+
+## Capability floor
+
+The generic MCP capability declaration is all false:
+
+| Group | Effective behavior |
+|---|---|
+| lifecycle | no automatic session-start, resume, or end signal |
+| context | no startup, before-turn, or safe-point injection |
+| guards | no before-read, before-write, or before-shell interception |
+| delivery | no `nextTurn`, `livePush`, or native `replyRoute` |
+
+An MCP participant therefore reports `advisory` enforcement and `manual` lifecycle.
+`manual` describes ACC presence reporting, not ownership of the external client. Because
+workspace protection is the weakest live participant's real guarantee, one MCP session
+makes guarded claims advisory for the room.
+
+## Durable polling semantics
+
+Every outgoing message commits first. `acc_message`, `acc_request`, `acc_reply`, and
+`acc_finish` cannot promise push; delivery results remain queued with a durable diagnostic.
+The recipient calls `acc_inbox` to retrieve the body. Being returned by a tool is
+`retrieved`, not proof that a model attended to or obeyed it. A reply or explicit ack is
+`acknowledged`.
+
+MCP is therefore a complete communication participant with higher latency, not a fake
+native adapter. Use it when a client can call tools but exposes no measured hook boundary.
+
+Next: [Protocol](PROTOCOL.md) · [Capabilities](CAPABILITIES.md) ·
+[Security model](SECURITY_MODEL.md)

package/docs/PROTOCOL.md

@@ -0,0 +1,200 @@
+# Protocol
+
+The protocol is the vendor-neutral contract shared by core, CLI, MCP, storage, and every
+adapter. Version 0.2 uses store schema version `3` and deliberately rejects v0.1 state.
+There is no compatibility reader, conversion, archive path, or automatic deletion.
+
+## Durable records
+
+The store accepts only these durable kinds:
+
+```text
+workspace · participant · session · intent · claim · message · receipt · event
+```
+
+`deliveryBinding` is validated but ephemeral. It is tied to one open session generation
+and never written inside a repository.
+
+## Identity
+
+```text
+Workspace
+└── Participant
+    └── Session generation
+```
+
+- A workspace is one local coordination room.
+- A participant is the stable recipient of a message.
+- A session is one client conversation. Its unguessable generation token proves that a
+  later mutation still belongs to the current opening.
+
+Sessions carry harness, checkout, branch, optional pid, enforcement, and lifecycle facts.
+The `managed` lifecycle value means ACC hooks can report presence changes; it does not mean
+ACC owns or controls the external client.
+
+## Intent and claims
+
+Intent contains `summary`, `mode`, `resourceHints`, `state`, and `updatedAt`. It is
+awareness only.
+
+Claims contain the owner session and generation, canonical resource URI, shared or
+exclusive mode, advisory or guarded enforcement, reason, and lease timestamps. Claim
+acquisition and conflict detection are atomic. Presence becoming stale never releases a
+claim; expiry or an explicit release does.
+
+## Message envelope
+
+Every message contains:
+
+```text
+messageId
+threadId
+clientMessageId
+workspaceId
+fromParticipantId
+fromSessionId
+toParticipantIds
+kind
+obligation
+subject
+body
+inReplyTo
+artifacts
+handoff
+sentAt
+```
+
+`clientMessageId` is an idempotency key scoped to workspace plus sender participant. A
+retry with the same logical content returns the original message. Reusing the key with
+different content is a data error. CLI and MCP generate a key when omitted and return it
+inside the message so an uncertain caller can retry explicitly.
+
+An empty `toParticipantIds` creates a room record. At commit time, core resolves every
+known peer participant with an open session and creates a receipt for each. Participants
+that arrive later can inspect room history through a full sync but do not receive
+retroactive receipts. Those already-present recipients get the normal inbox and certified
+next-turn path; a successful next-turn write advances their room receipt to `offered`.
+Room records are never eligible for native live push.
+
+## Kinds and obligations
+
+| Kind | Valid obligation | Addressing |
+|---|---|---|
+| `note` | `none` | addressed or room |
+| `question` | `reply` | addressed only |
+| `request` | `reply` | addressed only |
+| `answer` | `none` | addressed reply only |
+| `decision` | `none`, or `acknowledge` | addressed or room; room must use `none` |
+| `handoff` | `acknowledge`, or `none` | addressed must acknowledge; room must use `none` |
+
+The generic `message` boundary accepts only `note`, `question`, `request`, and `decision`.
+An `answer` must be made through `reply`, which supplies the thread link. A `handoff` must
+be made through `finish`, which supplies the structured payload.
+
+A request has no accepted, running, or done state. The reply resolves its communication
+obligation; execution evidence belongs in the answer or handoff.
+
+## Threads
+
+The root message uses its own id as the thread id:
+
+```text
+threadId = messageId
+inReplyTo = null
+```
+
+An answer carries the same `threadId` and the original message id in `inReplyTo`. There is
+no mutable thread record or hidden thread status.
+
+## Receipt lifecycle
+
+Every resolved recipient gets an independent receipt:
+
+```text
+queued -> offered -> retrieved -> acknowledged
+```
+
+`recorded` is the send boundary's success result: the message is durable. It is not a
+receipt state. `queued` is the distinct per-recipient fact created in the same transaction,
+so one recorded room or multi-recipient message can have zero or several queued receipts.
+
+- `queued` proves the durable message and receipt committed.
+- `offered` proves bytes crossed ACC's transport boundary or the target client accepted a
+  certified native call.
+- `retrieved` proves the participant explicitly received the body through inbox or an
+  equally strong certified adapter signal.
+- `acknowledged` proves that participant acknowledged or replied.
+
+Offered is not read. Retrieved is not model attention. Reply is not task completion.
+
+Forward skips are allowed when the stronger observation implies the weaker ones. Repeating
+a state is idempotent; moving backward is rejected. There is no `seen` state because ACC
+cannot inspect model attention, and no terminal delivery `failed` state because the
+durable path remains available.
+
+## Offer attempts
+
+Delivery attempts are immutable events, not receipt states:
+
+```text
+message.offer_succeeded
+message.offer_failed
+```
+
+Every attempt identifies `messageId`, `recipientParticipantId`, `targetSessionId`, and
+`targetGeneration`, followed by the transport name, adapter, client version, and timestamp.
+A failed attempt additionally carries a safe closed error code. Core validates the target
+as that recipient's recorded session generation and derives event attribution from it; the
+router cannot substitute the sender or omit the selected binding. Attempts never copy the
+peer body into diagnostics.
+Receipt `offered` is committed only after the transport accepts bytes. A failed attempt
+leaves the receipt queued.
+
+## Inbox, reply, and acknowledgement
+
+`inbox` returns unresolved messages owned by the calling participant and advances only
+that participant's receipt to `retrieved`. An exact message id is the recovery path after
+compaction or an over-budget projection.
+
+`reply` verifies that ownership, records an `answer` in the original thread, and advances
+the original receipt to `acknowledged` in one transaction. Only after that durable commit
+may the answer be offered to the original author. A transport error cannot roll back it.
+
+`ack` advances the caller's receipt without creating a reply. It exposes no state override;
+callers cannot claim that a transport offered or a participant retrieved a message.
+
+## Handoff
+
+`finish` creates a `handoff` with structured `status`, `completed`, `remaining`,
+`blockers`, and `verification`, releases the sender session's claims, and ends its ACC
+presence. An addressed handoff requires acknowledgement. A room handoff does not. Neither
+form closes or otherwise controls the external AI client.
+
+## Delivery binding and recipient policy
+
+A live-capable adapter may publish one ephemeral binding for its exact session generation:
+
+```text
+sessionId · generation · adapterId · clientVersion · availableModes
+livePolicy · opaqueEndpointRef · leaseUntil
+```
+
+The recipient owns `livePolicy` because native push may start a model turn:
+
+- `off`: inbox and normal next-turn paths only;
+- `actionable`: questions, requests, answers, decisions, and addressed handoffs may use live push;
+- `all`: every addressed kind may use live push.
+
+Default is `off`. Policy never creates a capability. The router still requires a current
+reachable binding, one unambiguous recipient generation, a passing exact-version
+certification, and adapter acceptance. The current Codex and Claude captures do not meet
+those requirements; all shipped native live routes therefore fall back durably.
+
+## Attention and sync
+
+Bounded sync returns events after a cursor plus explicit attention. Full sync is a
+forensic workspace snapshot, not the normal way to recover one message. Attention is
+limited to six explicit rules: `reply_required`, `acknowledgement_required`,
+`recipient_unavailable`, `claim_conflict`, `claim_contended`, and `claim_expired`.
+
+Next: [CLI](CLI.md) · [MCP](MCP.md) · [Architecture](ARCHITECTURE.md)

package/docs/RELEASING.md

@@ -0,0 +1,115 @@
+# Releasing
+
+```mermaid
+graph LR
+  A[npm ci] --> B[npm run check] --> C[npm test] --> D[clean candidate commit] --> E[npm pack] --> F[verify-package] --> G{approved?}
+  G -->|yes| H[tag · publish · release]
+  G -->|no| I[stop]
+```
+
+## Build the candidate
+
+```bash
+npm ci
+npm run check
+env npm_config_cache=/private/tmp/acc-npm-cache-v02 npm test
+git status --short
+git commit -m "release: prepare ACC v0.2.0"
+candidate_dir="$(mktemp -d /private/tmp/acc-v0.2.XXXXXX)"
+env npm_config_cache=/private/tmp/acc-npm-cache-v02 npm pack --pack-destination "$candidate_dir"
+env npm_config_cache=/private/tmp/acc-npm-cache-v02 node scripts/verify-package.mjs \
+  "$candidate_dir/agents-can-communicate-0.2.0.tgz"
+git diff --check
+```
+
+`verify-package.mjs` is the gate that matters. It installs the tarball into a
+clean directory with **no workspace anywhere** and then drives the product. The
+acceptance suite additionally opens independent Claude/Codex hook sessions from
+the installed artifact, completes both message directions, proves downgrade and
+restart behavior, exercises the installed MCP binary, and removes client wiring twice.
+
+Development cannot catch what this catches. Workspace symlinks are always
+present there, so an unbundled package imports fine right up until somebody
+else installs it.
+
+## What it refuses
+
+| Refused | Why |
+|---|---|
+| `tests/`, `test/` | test suite |
+| unreferenced `fixtures/` | material that is not exact redacted certification evidence |
+| `scripts/spikes/`, `*.sock` | development probes and local endpoints |
+| runtime, transcript, or secret directories | machine state and private material |
+| `.github/`, `.githooks/`, `.agents/` | local configuration |
+| `*.jsonl` | looks like a transcript |
+| Workspaces missing from `node_modules/` | every internal import would fail |
+
+## Record the evidence
+
+Put the tarball name, sha256, **the commit it was built from**, exact platform/client
+facts, fallback result, and known limitations in `docs/release-evidence/v0.3.0.md` and
+the current `CHANGELOG.md` release table. A release without them is a release nobody can
+audit later. Test count is deliberately left out: nothing verifies it, so it only
+decorates or, when it drifts, misleads.
+
+The commit matters because every workspace travels inside the tarball, so any
+change to shipped code changes the digest. A digest recorded alone goes stale
+on the next merge and then reads as a false claim about the current tree
+rather than a true one about an older commit. `verify-package.mjs` prints
+both on one line for exactly this reason, and refuses to imply
+reproducibility when the working tree is dirty:
+
+```text
+PASS  agents-can-communicate-0.0.0.tgz  sha256 a5c8bb1d…  built from 39d0dcf
+```
+
+It went stale four times in a row anyway, each caught by hand and only
+because someone happened to run the script. So `npm test` now checks it:
+`tests/acceptance/recorded-candidate.test.mjs` fails when shipped code has
+changed since the recorded commit, and names the files. A shallow clone that
+does not have the commit reports that instead of failing — the check is of
+the record, not of the checkout depth.
+
+The candidate therefore uses two commits. Commit A contains every packed file and every
+release gate. Pack and verify clean commit A, then commit B records its digest and evidence
+only in files that are not packed. Never record a dirty-tree digest: changing a packed file
+after commit A means making a new candidate commit and packing again.
+
+Native real-client tests run only where the retained capture proved that native boundary.
+For v0.2.0 neither Codex 0.152.0 nor Claude Code 2.1.252 did: the Codex control socket was
+absent and Claude stopped at the development-channel warning. Record those exact failed
+captures and run the packed inbox/next-turn fallback instead of promoting an unobserved
+native path. Windows is an explicit unsupported-platform skip, not a passing capture.
+
+By v0.3.0 that had gone both ways, which is the point of doing it per release rather than
+once. Claude Code passed and ships a live Channel; Codex's queue capture passed and the
+capability was **withdrawn anyway**, because the mode it needs hides which workspace the
+session belongs to, and a session that cannot be placed must not be addressed. A capture
+that works is not the same claim as a capability that is safe to ship.
+
+A published version's record is history and is not rewritten; later changes
+get a new `## Unreleased` entry at the top, checked the same way against the
+current tree.
+
+## Then stop
+
+Publishing, tagging, and cutting a GitHub release are **external mutations**.
+They need explicit approval from the maintainer, every time.
+
+With two-factor authentication set to `auth-and-writes` — which is what `npm
+profile get` reports for this account — every publish needs a code, and npm
+does not prompt for one:
+
+```bash
+npm publish --otp=123456
+```
+
+An npm *Automation* token, or a granular token with write access, publishes
+without a code. A granular token scoped to selected packages cannot create a
+package that does not exist yet, which is the case exactly once per package.
+The `Release` workflow builds and verifies a candidate and uploads it as an
+artifact; it does not publish.
+
+---
+
+See also: [README](index.md) for navigation and [Glossary](GLOSSARY.md) for terms.