agents-can-communicate 0.3.0 → 0.4.0

package/docs/PROTOCOL.md

@@ -1,8 +1,9 @@
 # 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.
+Use this page when implementing or checking a boundary shared by core, CLI, MCP, storage,
+and adapters. Protocol 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
 
@@ -24,7 +25,9 @@ Workspace
 ```
 
 - A workspace is one local coordination room.
-- A participant is the stable recipient of a message.
+- A participant is the recipient address for a message. A hooked session gets a default
+  address derived from its client session id; only an explicitly supplied participant id
+  is stable across unrelated client conversations.
 - A session is one client conversation. Its unguessable generation token proves that a
   later mutation still belongs to the current opening.
 
@@ -71,11 +74,57 @@ 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
+that arrive later can inspect room records through history 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.
 
+## Decision lifecycle
+
+A decision may additionally carry `decisionChange` with exactly two fields:
+`action` (`replace` or `withdraw`) and `messageIds` (1..16 unique portable IDs of
+existing decisions in the same workspace). Generic send inputs use `supersedes`
+or `withdraws`; the durable payload is built after transactional validation.
+The sorted target set participates in idempotency. The author may be any owned
+participant; attribution does not confer system authority.
+
+Targets and their receipts are immutable. Changes inherit target receipt recipients
+and target authors, excluding the changing author from inherited recipients. Extra
+explicit recipients are merged, sorted, and persisted in `toParticipantIds` before
+recording. This also notifies offline readers and makes live routing use the same set.
+No old receipt is acknowledged, deleted, or advanced by a lifecycle change.
+
+Explicit links form a graph. Within a connected group, terminal records are heads;
+multiple heads mean a conflict, even if their prose looks similar. A change may target
+an already replaced decision, creating a competing branch. Resolve branches by
+explicitly linking a new change to all their current heads. A withdrawal is itself
+a terminal record; superseding it explicitly records a new decision.
+
+Decision summaries and exact read copies expose `decisionStatus`:
+
+| Field | Meaning |
+|---|---|
+| `state` | `current` for a terminal choice; `withdrawn` for a terminal cancellation or history with only cancelled heads; otherwise `superseded` |
+| `isHead` | no recorded successor links to this record |
+| `conflicted` / `headCount` | whether the group has multiple terminal positions and their count |
+| `currentMessageId` | sole current head, or null if there is no unique head |
+| `groupId` | derived representative root ID for finding related heads; may change when groups are joined |
+
+This metadata is never persisted. `history` + kind `decision` + `current: true`
+lists heads, including withdrawals and conflicts, using the same summary budget.
+Ordinary inbox, bulk reads, automatic delivery and attention omit non-head decisions;
+exact inbox/history retain them. Timestamps and acknowledgements never choose a winner.
+A decision without an explicit successor may still be factually stale.
+
+Next-turn context and each native offer use a lifecycle snapshot; text already shown
+or in flight cannot be recalled. Changes get their own delivery receipts. Native
+transport carries the change/status inside its existing untrusted text envelope.
+
+The optional field preserves reading of existing schema-3 records by this build.
+Older ACC builds cannot interpret these semantics and may reject new records with
+unknown fields. Upgrade participating ACC installations together; this is not a
+forward-compatible promise or an automatic state migration.
+
 ## Kinds and obligations
 
 | Kind | Valid obligation | Addressing |
@@ -152,13 +201,19 @@ 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.
+Without an id, public `inbox` lists bounded summary pages for unresolved messages owned
+by the calling participant, without changing receipts. An exact read returns the complete
+message and advances only that participant's receipt to `retrieved`. It is the narrow
+recovery and inspection path, including after compaction or acknowledgement. Reading an
+acknowledged message preserves its receipt, timestamp, and event history; it does not put
+the message back into the unresolved inbox. Ownership and current-generation checks still
+apply to every read.
 
 `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.
+CLI and MCP reply results expose both facts: `message` and `delivery` describe the outgoing
+answer, while `receipt` describes the caller's acknowledgement of the original message.
 
 `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.
@@ -185,15 +240,22 @@ The recipient owns `livePolicy` because native push may start a model turn:
 - `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.
+Default is `off`. Policy never creates a capability. The router requires one
+current eligible recipient generation, supported client evidence, a verified
+binding and adapter acceptance. Claude Code Channel uses a captured 2.1.258
+minimum, confirmed on 2.1.260. Codex LocalDaemon uses a 0.152.1 minimum, confirmed
+through installed-product captures on 0.152.1 and 0.153.4; recorded consent and
+exact thread, cwd, process, version and protocol verification govern every session.
+Unavailable or refused routes fall back durably. Codex replies use the ACC CLI;
+its native reply route remains false.
 
 ## 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
+Default sync returns a bounded event page after a 16-digit cursor plus explicit attention.
+History sync returns read-only message summaries (20 items by default, at most 12,000
+formatted JSON bytes) and complete-message-id cursors, or one exact full message. Neither
+history mode changes receipts. Full sync adds an unbounded forensic workspace snapshot.
+Message discovery and exact-read contracts are in [CLI](CLI.md) and [MCP](MCP.md). Attention is
 limited to six explicit rules: `reply_required`, `acknowledgement_required`,
 `recipient_unavailable`, `claim_conflict`, `claim_contended`, and `claim_expired`.
 

package/docs/RELEASING.md

@@ -1,115 +1,157 @@
 # Releasing
 
+Use this procedure to build one auditable npm artifact, verify that exact tarball, and keep
+its evidence tied to the commit that supplied its bytes. The package is currently `0.4.0`;
+the commands derive the version from `package.json` so the filename cannot drift.
+
 ```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?}
+  A[syntax · diff · staged-set review] --> B[candidate commit A]
+  B --> C[pack exact tarball]
+  C --> D[verify installed artifact]
+  D --> E[evidence commit B]
+  E --> F[full suite]
+  F --> G{maintainer approval}
   G -->|yes| H[tag · publish · release]
   G -->|no| I[stop]
 ```
 
-## Build the candidate
+## Prepare candidate commit A
+
+Commit A must contain every file npm will pack and every release gate. Use a clean,
+dedicated release worktree; an existing clean isolated worktree is fine. Update the version
+and candidate files, then run:
 
 ```bash
-npm ci
+release_cache="$(mktemp -d "${TMPDIR:-/tmp}/acc-npm-cache.XXXXXX")"
+candidate_dir="$(mktemp -d "${TMPDIR:-/tmp}/acc-candidate.XXXXXX")"
+package_version="$(node -p "require('./package.json').version")"
+
+env npm_config_cache="$release_cache" 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
+git status --short
+git diff --name-only
+# Repeat with every reviewed candidate path; never use `.` or `-A` here.
+git add -- path/to/reviewed-file
+git diff --cached --name-status
+git diff --cached --check
+git commit -m "release: prepare ACC v$package_version"
+candidate_commit="$(git rev-parse HEAD)"
+test -z "$(git status --short)"
 ```
 
-`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
+Replace `path/to/reviewed-file` with each explicit path you just reviewed. Never use
+`git add .` or `git add -A` in this procedure: an unrelated file does not become release
+content merely because it shares a worktree. Check `git diff --cached --name-status` before
+committing and stop if `git status --short` after the commit is not empty.
+
+Never bypass the pre-push hook. The full suite belongs after commit B because the
+recorded-candidate gate deliberately includes working-tree and committed packed changes;
+before refreshed evidence exists, that one check is expected to fail.
+
+## Pack and verify the exact artifact
+
+```bash
+env npm_config_cache="$release_cache" npm pack --pack-destination "$candidate_dir"
+tarball="$candidate_dir/agents-can-communicate-$package_version.tgz"
+shasum -a 256 "$tarball"
+env npm_config_cache="$release_cache" node scripts/verify-package.mjs "$tarball"
 ```
 
-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.
+`verify-package.mjs` installs the supplied tarball into a clean directory with no workspace
+symlinks, then exercises doctor, a non-Git workspace, client install/uninstall, bundled
+workspaces, certification evidence, and packed documentation links. It rejects tests,
+development probes, sockets, transcript-shaped data, runtime state, and unreferenced
+fixtures. Keep `ACC_NO_UPDATE_CHECK=1` set for release checks so installing an integration
+cannot schedule a real registry update. The managed-update acceptance tests explicitly
+enable networking only against their isolated local registry and npm cache.
 
-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.
+The managed-update checks exercise actual installed archives: automatic enrollment and
+activation, a persistent MCP process holding the old version, integrity rejection, recovery
+from a failed integration refresh, and stable launchers after the initial package is gone.
+Run them before recording the candidate:
 
-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.
+```bash
+env npm_config_cache="$release_cache" node --test tests/acceptance/managed-*-packed.test.mjs
+```
 
-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.
+Repeat the published-version upgrade preflight with this exact tarball and isolated home,
+data, and project directories. Retain the source/archive/installed file comparison with the
+preflight evidence. Local-registry checks and direct process checks do not establish native
+client activation; capture that separately on supported real clients.
 
-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.
+When passed an existing tarball, the verifier intentionally prints `revision unknown`:
+the current checkout cannot prove which commit produced arbitrary supplied bytes. Record
+`$candidate_commit`, captured while the tree was clean immediately before packing, as the
+artifact's source. Running the verifier without a tarball makes it pack the current tree
+itself and can report that tree's revision, but it does not verify a separately saved
+release artifact.
 
-## Then stop
+## Record evidence in commit B
 
-Publishing, tagging, and cutting a GitHub release are **external mutations**.
-They need explicit approval from the maintainer, every time.
+Write the tarball name, SHA-256, `$candidate_commit`, platform and client facts, fallback
+result, and known limitations to `docs/release-evidence/v$package_version.md` and the
+matching `CHANGELOG.md` section. Do not record an unverifiable test count.
 
-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:
+Commit B contains only evidence files that npm does not pack. If a packed file changes,
+discard the candidate artifact, make a new commit A, and repeat the pack and verification.
 
 ```bash
-npm publish --otp=123456
+git diff --check
+git status --short
+git add -- CHANGELOG.md "docs/release-evidence/v$package_version.md"
+git diff --cached --name-status
+git diff --cached --check
+git commit -m "release: record ACC v$package_version candidate"
+test -z "$(git status --short)"
+env npm_config_cache="$release_cache" npm test
 ```
 
-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.
+The staged-set review for commit B must name only those two evidence files. The final full
+suite now sees candidate A's packed bytes plus candidate B's matching record, so candidate
+freshness is a normal passing gate rather than an expected failure.
+
+Published evidence is history. Do not rewrite it into a current capability claim; later
+work belongs under `Unreleased` and gets a new candidate record.
+
+## Capture only capabilities you observed
+
+Run native real-client checks on the exact versions and platforms recorded in
+retained fixtures. Exact-version evidence governs normal-turn and guard behavior.
+Claude Code Channel uses its captured macOS arm64 minimum plus a current probe and
+per-session handshake; its vendor warning remains part of startup. Codex LocalDaemon
+uses a separate 0.152.1 minimum with installed-product captures on 0.152.1 and
+0.153.4. Its passing capture must ship the hashed complete product matrix and
+historical evidence references. Direct queue success alone cannot certify that route.
+
+Record failed and unavailable paths as such, then exercise the packed next-turn or inbox
+fallback. An unsupported platform is an explicit skip, never a passing capture. See
+[Capabilities](CAPABILITIES.md) and each adapter's `COMPATIBILITY.md` for current evidence.
+
+## Publish only after explicit approval
+
+Tagging, npm publication, and creating a GitHub release are external mutations. Stop after
+commit B until a maintainer explicitly approves them. The manual `Release` workflow builds
+and uploads a candidate; it does not publish.
+
+Authentication requirements depend on the credential and npm policy in effect at release
+time. Consult npm's current documentation and inspect the configured route instead of
+copying a historical command. For example, the v0.3.0 publication succeeded without an OTP
+while `npm profile get` returned `403`; that is a historical observation, not a universal
+claim about current npm authentication or credential type.
+
+After approval, publish the verified tarball by filename. Bare `npm publish` repacks the
+tree and would send different, unverified bytes.
+
+```bash
+npm publish "$tarball"
+npm view "agents-can-communicate@$package_version" dist.shasum
+shasum "$tarball"
+```
 
----
+Add `--otp` only when the current authenticated npm route requires it. Compare the registry
+SHA-1 with the local `shasum`, allowing for registry propagation delay, before creating the
+tag or release record.
 
-See also: [README](index.md) for navigation and [Glossary](GLOSSARY.md) for terms.
+See also: [documentation map](index.md) · [Security model](SECURITY_MODEL.md)

package/docs/SECURITY_MODEL.md

@@ -1,11 +1,13 @@
 # Security model
 
-ACC connects independently controlled sessions without merging their authority. A peer can
-send useful context, a question, or a request; its text never becomes system policy or a
-human instruction merely because ACC transported it.
+Use this model to decide which boundary owns a security claim and which failure belongs to
+the client or local account instead. ACC connects independently controlled sessions
+without merging their authority. A peer can send context, a question, or a request; its
+text never becomes system policy or a human instruction merely because ACC transported it.
 
-The first release coordinates processes under one local OS user. Same-user access protects
-local transport from the network; it does not make model output trustworthy.
+The current local boundary coordinates processes under one OS user on one machine.
+Same-user access protects local transport from the network; it does not make model output
+trustworthy.
 
 ## Trust boundaries
 
@@ -40,7 +42,11 @@ own instruction hierarchy are the mitigation; ACC is not a model sandbox.
 ## Identity and ownership
 
 - Participant identity is the address; session identity is one current client opening.
-- Mutating calls prove their owner with the session generation.
+- Mutating CLI calls and inbox reads require an explicitly supplied session/generation
+  pair. The CLI never obtains a generation from a public ID, checkout, sole peer binding,
+  or inherited native environment value.
+- `ACC_SESSION`/`ACC_GENERATION` are operator-supplied credentials. They do not authenticate
+  a process or protect against intentional sharing under the same local OS account.
 - A stale process cannot renew or release records owned by a newer generation.
 - Inbox, reply, and acknowledgement validate the recipient's participant id.
 - One participant cannot advance another participant's receipt.
@@ -64,15 +70,20 @@ There is no model-attention claim and no public state override. Failed accelerat
 the message queued and records only a closed safe error code. Diagnostics and offer events
 never copy the peer body.
 
-A future live adapter must match exact passing evidence, one unexpired generation-bound
-binding, and the recipient's opt-in policy. Opaque endpoint references remain inside the
-adapter and outside repositories. Current Codex and Claude native captures failed, so no
-live transport is enabled.
+A live adapter must match its declared evidence contract, one current
+generation-bound binding and recipient opt-in. Opaque endpoints remain private
+and outside repositories. Claude Code Channel and Codex LocalDaemon delivery are
+experimental and off by default. Codex verifies the exact receiver thread,
+canonical cwd, live process, stable version and protocol, and rereads recorded
+consent before offers. A loaded daemon thread can receive messages after its TUI
+exits. Delivery off and uninstall prevent new Codex submissions; a submission
+already accepted by the vendor queue cannot be withdrawn.
 
 ## Claims
 
-Claims are advisory unless every live participant exposes a certified guard for the
-relevant mutation path. Even guarded claims do not stop unrelated processes, runtime-built
+CLI claims default to advisory. Guarded enforcement must be requested explicitly and
+requires every live participant to expose a certified guard for the relevant mutation path.
+MCP claims remain advisory. Even guarded claims do not stop unrelated processes, runtime-built
 paths, or tool calls the client never presents to the hook. Force release requires explicit
 authority and records actor and reason.
 
@@ -88,14 +99,40 @@ from operating merely because its own state is unavailable.
 - Corrupt or incompatible store versions fail closed before mutation.
 - Client installers preserve unrelated settings and record content hashes.
 - Uninstall removes only bytes still matching what ACC wrote.
-- Tokens, credentials, and environment contents are never copied into ACC or project config.
+- Runtime credentials and private endpoints stay outside project config. Adapters do not
+  automatically collect client secrets or environment contents into peer messages.
+
+## Managed automatic updates
+
+A normal managed installation enables automatic updates. The latency-sensitive hook path
+does no network download; it may schedule a detached worker. That worker uses the configured
+npm registry/network and local npm executable, checks stable package identity/version and
+sha512 integrity against registry metadata, installs with lifecycle scripts disabled, and
+validates the staged runtime before activation. These checks retain the registry and package
+author as a software-supply trust boundary; they do not establish that package code is safe.
+
+ACC process leases hold activation until confirmed exit. Native bindings hold until observed
+SessionEnd cleanup or confirmed process death; unknown PIDs remain conservative holds.
+`acc finish`, presence TTL, and delivery off do not establish native lifecycle end. ACC does
+not manage the vendor daemon.
+
+A failed download leaves the active runtime available. A partial integration refresh retains
+the old active pointer but fences normal workspace admission in `activating`; it does not
+leave the previous runtime available for normal work. Fix the reported problem and run
+`acc update` to repair forward. Hooks continue to fail open while coordination is unavailable.
+
+`acc update --auto off` disables background updates; `--pin <version>` holds an exact stable
+version. `ACC_NO_UPDATE_CHECK=1` disables update networking and scheduling while allowing
+manual recovery of an already verified pending update. See [Upgrading](UPGRADING.md).
 
 ## Data collected
 
 ACC stores participant/session identity, presence, one-line intent, explicit claims,
 explicit messages and structured handoffs, per-recipient receipts, artifact references,
-and coordination events. It excludes complete prompts, assistant responses, raw
-transcripts, secrets, environment variables, and unrelated files.
+and coordination events. ACC does not automatically collect raw transcripts, full prompts
+or assistant responses, secrets, environment contents, or unrelated files. Explicit message
+bodies are caller-provided and preserved: ACC does not scan or scrub secrets from text a
+caller chooses to send. The sender remains responsible for that content.
 
 ## Threat scenarios