agents-can-communicate 0.3.1 → 0.4.0

package/docs/GETTING_STARTED.md

@@ -4,10 +4,17 @@ Install ACC, open the AI sessions you already use, and give them related work. S
 integrations make peers visible and teach each agent how to communicate. You do not need to
 carry messages between windows or add coordination instructions to your task prompts.
 
+Active hooks supply each agent's own CLI arguments in coordination context; the installed
+skill tells the agent to use them. This path was observed in Claude Code 2.1.263 and
+Codex 0.153.4. Hooks must be enabled and trusted by the client. Without hook context, owner
+operations require an explicit pair or session-bound ACC MCP tools. See [CLI ownership](CLI.md#coordinate-from-a-session).
+
 ## 1. Install once on this machine
 
 ACC requires macOS or Linux and Node.js 24 or newer.
 
+Already using 0.3.1? Follow the [upgrade guide](UPGRADING.md) before mixing versions.
+
 ```bash
 npm install -g agents-can-communicate
 ```
@@ -17,9 +24,21 @@ npm install -g agents-can-communicate
 acc install
 ```
 
+Installation also enables automatic updates. ACC downloads releases in the background and
+refreshes its runtime and skills when active clients have left. Use `acc update` for an
+immediate update, or `acc update --auto off` to disable background updates. See
+[update controls](UPGRADING.md#automatic-updates-after-installation).
+
 The installer connects only the supported clients it finds. Open a new terminal and
-restart any running clients so they load their integrations. Codex asks you to trust its
-plugin once.
+restart any running clients so they load their integrations. Follow the activation steps
+printed by the installer. In Codex, use `/plugins` to check ACC is enabled, then `/hooks`
+to review each ACC hook and enable/trust its current definition if needed. Restart the
+session after that review; changed hook definitions may require trust again.
+
+If the installer preserved your existing Codex sandbox settings, verify the named ACC
+state directory is in `sandbox_workspace_write.writable_roots` in the config it identifies.
+ACC keeps those user settings unchanged. Installed files alone do not establish that hooks
+are active; `acc doctor` leaves current readiness unverified and directs you to Codex.
 
 If you opt into Claude Code's experimental idle delivery, Claude also shows its own
 development-channel warning at every startup. The feature is off by default, can spend
@@ -46,6 +65,16 @@ Same-client addresses can be ambiguous when several instances are live; agents u
 exact participant ids in the roster when needed. See [Concepts](CONCEPTS.md) for participant
 and session identity.
 
+A second repeatable pattern is review and handoff. Ask the implementing agent to request
+review of an identified revision (a commit when Git is available, or named files and
+version otherwise) and wait for the verdict. Ask the reviewer to return blocking defects
+or approval. If either session must stop, it can leave a durable handoff naming completed
+work, remaining work, and blockers. A later session can recover it from history. The
+underlying commands are [`acc request`](CLI.md#messages-and-requests), exact
+[`acc inbox --message`](CLI.md#inbox-reply-and-acknowledgement),
+[`acc reply`](CLI.md#inbox-reply-and-acknowledgement), and
+[`acc finish`](CLI.md#handoff).
+
 ## 3. Watch for useful coordination
 
 Look for an agent discovering a peer, publishing the files it expects to change, noticing a
@@ -71,11 +100,12 @@ CLI, and Kimi Code can receive a message at the next normal turn. That does not
 session. Grok, generic MCP clients, unknown versions, and unsupported platforms use the
 durable inbox instead.
 
-Claude Code's optional native channel is the only shipped idle-delivery path. It is
-experimental, never interrupts a turn already in progress, and remains subject to current
-reachability and recipient policy. Codex native live delivery is withdrawn; Codex uses its
-certified next-turn path or inbox. Read [Capabilities](CAPABILITIES.md) for exact versions,
-platforms, and limitations.
+Codex LocalDaemon and Claude Code Channel offer optional native delivery on
+Apple Silicon macOS. They are experimental, can spend tokens, and queue messages
+until a running turn finishes. Codex requires 0.152.1 or newer, an already-running
+LocalDaemon, recorded opt-in and a verified session; start it with your normal
+command. A loaded daemon thread can receive messages after its terminal exits.
+[Capabilities](CAPABILITIES.md) explains policy, versions and fallback.
 
 Delivery evidence is deliberately narrow: `queued -> offered -> retrieved -> acknowledged`.
 An offer is not proof that the model read anything, retrieval is not proof of attention, and

package/docs/GLOSSARY.md

@@ -7,7 +7,7 @@
 - **Presence** — `online`, `stale`, or `offline`, based only on observed heartbeat and pid facts.
 - **Intent** — a session's current summary and resource hints; awareness, not permission.
 - **Claim** — a leased reservation for a canonical resource such as `file:src/**`.
-- **Advisory / guarded** — a claim peers must respect versus one ACC can stop on measured client write paths; neither stops unrelated local processes.
+- **Advisory / guarded** — CLI claims default to advisory. Explicit guarded enforcement also requires certified guards from every live participant; neither mode stops unrelated local processes.
 - **Message** — an attributed untrusted `note`, `question`, `request`, `answer`, `decision`, or `handoff`.
 - **Thread** — a root message plus linked answers sharing one immutable `threadId`.
 - **Obligation** — `none`, `reply`, or `acknowledge`; what communication the recipient owes.
@@ -16,11 +16,17 @@
 - **Retrieved** — the participant received the body; not proof of model attention.
 - **Acknowledged** — that participant explicitly acknowledged or replied; a reply is not proof requested work finished.
 - **Next-turn delivery** — certified projection at the client's next normal turn; it never interrupts an active turn.
-- **Live push** — optional delivery to an already-running session through an official certified client API. Claude Code 2.1.258+ on macOS arm64 qualifies, behind an opt-in; it waits for a turn in progress rather than interrupting it.
+- **Live push** — optional delivery through Claude Code Channel or Codex LocalDaemon to an already-running session, behind recipient opt-in. Both wait for an active turn to finish; [Capabilities](CAPABILITIES.md) gives the measured eligibility and limits.
 - **Recipient policy** — `off`, `actionable`, or `all`; opt-in permission to spend a turn, not a capability.
 - **Delivery binding** — ephemeral, generation-bound reachability data owned by an adapter.
 - **Fallback** — durable inbox or exact-certified next-turn recovery when live delivery is unavailable.
 - **Managed / manual lifecycle** — whether hooks report ACC presence automatically; never ownership of the external client process.
-- **MCP participation** — polling access to durable communication without native lifecycle, context, guards, or push.
+- **MCP participation** — manual incoming polling without native lifecycle, context, guards, or receive wake; outgoing messages can use an eligible recipient's opted-in native route.
+- **Bounded discovery** — inbox/history summary pages with limits and cursors; bodies require selection.
+- **Exact recovery** — read one addressed inbox body, or one history record; history reads do not advance receipts.
+- **Decision change** — an immutable decision explicitly supersedes or withdraws prior decisions; old records remain.
+- **Current decision** — a terminal recorded position or withdrawal, not proven truth; competing branches stay visible.
+- **Managed runtime** — ACC's staged installation generations and automatic-update controls, distinct from managed/manual session presence.
+- **Activation hold** — an ACC process lease or native binding that postpones runtime refresh; observed lifecycle cleanup can release a native hold without stopping a vendor daemon.
 
 See [Concepts](CONCEPTS.md) for relationships and [Protocol](PROTOCOL.md) for exact rules.

package/docs/HOW_IT_WORKS.md

@@ -32,7 +32,8 @@ ACC workspace. The native integration also gives the agent a small skill describ
 discovery, messages, replies, claims, and handoffs.
 
 A generic MCP client instead joins through `acc-mcp`, which resolves its configured
-participant and workspace when tools or resources are called. It exposes the coordination
+participant and workspace on tool calls or inbox resource reads. Snapshot and roster
+resource reads do not need that owner resolution. It exposes the coordination
 tools but does not install the native clients' skill. See its
 [manual MCP boundary](MCP.md#account-for-the-manual-boundary).
 
@@ -95,8 +96,9 @@ receipts. [Protocol](PROTOCOL.md) defines these rules precisely.
 
 All recipients have the same durable record, but adapters expose different acceleration:
 
-- **Durable inbox:** universal recovery. An agent can retrieve the complete addressed
-  message with `acc inbox`, including by exact message id after compaction.
+- **Durable inbox:** universal recovery. `acc inbox` discovers bounded message headers;
+  `acc inbox --message <id>` retrieves one complete addressed message after selection
+  or compaction.
 - **Next normal turn:** exact captured versions of Codex, Claude Code, Gemini CLI, and Kimi
   Code can receive complete attributed peer context when the user next prompts that client.
   This does not wake an idle session.
@@ -105,9 +107,15 @@ All recipients have the same durable record, but adapters expose different accel
   default, can spend tokens, never interrupts a running turn, and requires the vendor's
   visible development-channel warning.
 
-Codex native live delivery is withdrawn because the required remote mode hides the
-session's real workspace. Grok, generic MCP, unknown versions, and uncaptured platforms use
-inbox polling. [Capabilities](CAPABILITIES.md) lists the evidence and exact fallbacks.
+- **Optional Codex LocalDaemon delivery:** on Apple Silicon macOS, a captured
+  minimum of 0.152.1 plus a current probe and exact session checks allow delivery
+  to an independently opened thread. It is experimental, off by default, and can
+  spend tokens. Messages wait for a running turn to finish; a daemon-retained
+  thread can receive them after its terminal exits. ACC adds no launch arguments
+  and does not manage the vendor daemon.
+
+Grok, generic MCP, unsupported versions and uncaptured platforms use inbox polling.
+[Capabilities](CAPABILITIES.md) lists evidence and fallback.
 
 When a complete projected body cannot fit the configured byte budget, ACC keeps the message
 id and exact inbox recovery command rather than silently truncating the peer's words.
@@ -141,13 +149,26 @@ Before changing files, an agent can publish intent and claim a narrow resource s
 `file:packages/api/**`. Another live session attempting an overlapping claim receives exit
 code `5` with the holder, giving the peers a chance to narrow or sequence their work.
 
-Claims are not operating-system locks. A claim is `guarded` only when every relevant live
-client exposes a captured pre-write guard for the path ACC can recognize. Otherwise it is
-`advisory`. Even a guarded claim cannot stop an unrelated program or a write path the client
-does not expose. [Concepts](CONCEPTS.md#intent-is-awareness-a-claim-commits) explains the
+Claims are not operating-system locks. CLI claims default to `advisory`. Explicit
+`--enforcement guarded` also requires every relevant live client to expose a captured
+pre-write guard for the path ACC can recognize; otherwise workspace protection is advisory.
+Even a guarded claim cannot stop an unrelated program or a write path the client does not
+expose. [Concepts](CONCEPTS.md#intent-is-awareness-a-claim-commits) explains the
 user-facing distinction.
 
-## 8. The boundaries remain visible
+## 8. Peers recover history and explicit decision changes
+
+Inbox and history listings expose bounded summaries. After compaction or a new conversation,
+a peer selects exact records to recover full decisions or handoffs; a new participant does
+not inherit an old participant's inbox. History reads preserve receipt state.
+
+A peer can explicitly supersede or withdraw an earlier decision. Prior records remain,
+and current-decision discovery shows terminal positions, withdrawals, and competing
+branches. This reports peers' recorded positions, not verified current truth. See
+[historical recovery](CLI.md#historical-recovery) and
+[decision lifecycle](PROTOCOL.md#decision-lifecycle). No full history is automatically injected.
+
+## 9. The boundaries remain visible
 
 ACC stores only coordination data an agent explicitly publishes: identity, presence,
 one-line intent, claims, messages, replies, handoffs, receipts, and events. It never collects

package/docs/MCP.md

@@ -1,9 +1,11 @@
 # MCP
 
 Use `acc-mcp` when a client can call MCP tools but has no native ACC adapter. The server
-exposes durable messages, threads, receipts, intent, claims, and handoffs over stdio. It is
-a manual polling integration: it cannot infer the client's lifecycle, intercept writes,
-inject a normal turn, or push a message.
+exposes durable messages, threads, receipts, intent, claims, and handoffs over stdio.
+Receiving through MCP requires manual polling: it cannot infer the client's lifecycle,
+intercept writes, inject a normal turn, or wake the MCP client for incoming messages.
+Outgoing messages commit first and may then be offered through an eligible recipient's
+native adapter when that recipient's delivery policy permits it.
 
 ```mermaid
 graph LR
@@ -29,22 +31,30 @@ identity for this server. It comes from user-owned launch configuration, never f
 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.
+The server supports initialized MCP clients using `2025-06-18` or `2025-11-25`, and
+the per-request metadata interface in `2026-07-28`, over newline-delimited JSON-RPC stdio.
+Initialized clients send `initialize`, accept the negotiated revision, then send
+`notifications/initialized` before calling tools. Unknown initialization revisions receive
+`2025-11-25`; the client decides whether it supports that revision. Transport initialization
+does not create an ACC participant: a tool call or inbox resource read resolves it.
+
+Tool input schemas are closed: unknown fields and invalid conditional shapes are
+rejected before a session is resolved. Approve the ACC tools through your client's normal
+permission controls. A headless client configured to reject approval requests can connect
+successfully yet refuse tool calls; that is distinct from a protocol handshake failure.
 
 ## Call the durable tools
 
 | Tool | Required input | Optional input |
 |---|---|---|
 | `acc_status` | — | — |
-| `acc_sync` | — | `cursor`, `scope: delta|full`, `limit: 1..500` |
+| `acc_sync` | — | `cursor`, `scope: delta|full|history`, `limit: 1..500`, `kind`, `messageId`, `current` |
 | `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_message` | `to`, `subject`, `body` | `kind`, `obligation`, `clientMessageId`, `supersedes`, `withdraws` |
 | `acc_request` | `toParticipantId`, `title` | `detail`, `clientMessageId` |
-| `acc_inbox` | — | `messageId` |
+| `acc_inbox` | — | `messageId`, `cursor`, `limit: 1..500` |
 | `acc_reply` | `messageId`, `body` | `subject`, `clientMessageId` |
 | `acc_ack` | `messageId` | — |
 | `acc_finish` | `goal` | `status`, `completed`, `remaining`, `blockers`, `toParticipantId`, `clientMessageId` |
@@ -53,15 +63,46 @@ All tool names above are the complete model-facing surface. There are no executi
 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.
+content is the JSON serialization of the same value. Default `acc_inbox` returns
+`{items, nextCursor}`: read-only pending message summaries paired with receipts, newest
+first. It never retrieves bodies. Pages default to 20 items, at most 12,000 bytes of
+formatted page JSON before MCP framing. `cursor` is the complete message id from
+`nextCursor`; omit it on a new poll to see arrivals. Reading or acknowledging the anchor
+between pages does not shift continuation. The summary field allowlist, byte limit,
+and live-page semantics are described in [CLI](CLI.md#inbox-reply-and-acknowledgement).
+
+With an exact `messageId`, `acc_inbox` returns a one-item array with the complete
+message/receipt pair and advances only that participant's receipt to `retrieved` when
+needed. Exact acknowledged inspection preserves receipt state, timestamp, and event
+history. Do not combine `messageId` with cursor or limit. Resolved mail stays out of lists.
+`acc_reply` writes an `answer` and acknowledges the original atomically. It additionally
+returns `receipt` for that original message; `message` and `delivery` describe the outgoing
+answer. `acc_ack` exposes no receipt-state parameter.
+
+For initialized 2025 clients, array results such as exact `acc_inbox` reads are JSON in text content,
+with `structuredContent` omitted because those revisions require an object there.
+Object results retain both representations. The 2026 interface also returns raw arrays
+in `structuredContent` and uses the `resultType: "complete"` envelope.
 
 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.
+resolves the configured MCP participant and returns the same read-only summary page as
+`acc_inbox {}`. Continue via the tool using `cursor`; retrieve a body with `messageId`.
+Snapshot and roster reads do not advance receipts either. `acc://snapshot` and sync with
+`scope: "full"` remain unbounded, for explicit workspace forensics.
+
+`acc_sync {scope: "history", kind: "handoff"}` returns
+`{scope: "history", view: "summary", items, nextCursor}` using the same message summary
+fields and page limits. The optional kind filter applies before paging. Continue with
+the complete `nextCursor` message id and the same filter. Then use
+`acc_sync {scope: "history", messageId: "message_x"}` to receive one complete historical
+message in `items`, with `view: "message"` and no receipt change. Exact reads reject
+cursor, limit, and kind. `kind` and `messageId` require history scope; delta/full retain
+16-digit event cursors. History exposes recorded peer claims, not their current validity.
+
+An addressed handoff requires a participant already known to the workspace. For a future
+session that has not joined, omit `toParticipantId` to leave a workspace handoff. A later
+session can recover that historical handoff through the history list and exact read;
+its addressed inbox will not contain past workspace broadcasts.
 
 ## Account for the manual boundary
 
@@ -79,16 +120,42 @@ An MCP participant therefore reports `advisory` enforcement and `manual` lifecyc
 workspace protection is the weakest live participant's real guarantee, one MCP session
 makes guarded claims advisory for the room.
 
-## Poll without overstating delivery
+## Decision changes
+
+`acc_message` with `kind: "decision"` accepts either `supersedes: ["message_x"]`
+or `withdraws: ["message_x"]`: 1..16 unique existing decision IDs. Supply `to: []`
+to inherit target authors and recipients, including offline participants, or add
+recipients explicitly. Body states the new position or reason for withdrawal.
+Any owned peer may record a change; competing branches are visible, not resolved by time.
 
-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`.
+`acc_sync {scope: "history", kind: "decision", current: true}` lists terminal
+positions and withdrawals with bounded `decisionStatus` metadata. Exact history
+reads include the same status and preserve receipts. `current` cannot accompany
+an exact ID or other scopes/kinds. Replaced decisions leave ordinary inbox/attention;
+they remain available by exact ID without an automatic acknowledgement.
+See [decision lifecycle](PROTOCOL.md#decision-lifecycle).
+
+## Poll without overstating delivery
 
-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.
+`acc_message`, `acc_request`, `acc_reply`, and `acc_finish` record their outgoing message
+before attempting delivery. The installed server uses the delivery router and recipient
+policy to offer addressed messages through eligible, opted-in native adapters. If no
+eligible route accepts a pending message, it remains queued for durable retrieval.
+Inspect the returned `delivery` outcomes; sending through MCP does not guarantee a native
+offer, model attention, or a reply. These outgoing routes add no receiving capability to MCP.
+
+Poll `acc_inbox`, `acc_status`, or `acc_sync` to observe changes. Never repeat a mutation
+merely to poll. For an intentional send retry, reuse the same `clientMessageId` and payload.
+Supply the key on the first call if you need it available after a lost response; an omitted
+key is generated and returned in `message`.
+
+An MCP recipient retrieves a body with `acc_inbox` and its exact `messageId`. That read
+advances the receipt to `retrieved` when needed, without proving model attention. A reply
+or explicit ack records `acknowledged`; that state alone proves neither a separate retrieval
+nor a native reply. Inspect the answer message separately when a response is required.
+
+Use MCP when a client can call tools but exposes no measured hook boundary, and allow for
+the polling latency of incoming messages.
 
 Next: [Protocol](PROTOCOL.md) · [Capabilities](CAPABILITIES.md) ·
 [Security model](SECURITY_MODEL.md)

package/docs/PROTOCOL.md

@@ -74,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 |
@@ -155,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.
@@ -188,17 +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, supported client evidence, and
-adapter acceptance. Claude Code live delivery on macOS arm64 uses a captured 2.1.258
-minimum plus a current feature probe and per-session protocol handshake; it was confirmed
-again on 2.1.260. Codex's queue transport was captured but withdrawn because its required
-mode hides the session workspace. Every unavailable or refused route falls 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,7 +1,7 @@
 # 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.3.1`;
+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
@@ -18,8 +18,9 @@ graph LR
 
 ## Prepare candidate commit A
 
-Commit A must contain every file npm will pack and every release gate. Start from a clean,
-dedicated release worktree, update the version and candidate files, then run:
+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
 release_cache="$(mktemp -d "${TMPDIR:-/tmp}/acc-npm-cache.XXXXXX")"
@@ -62,7 +63,23 @@ env npm_config_cache="$release_cache" node scripts/verify-package.mjs "$tarball"
 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.
+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 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:
+
+```bash
+env npm_config_cache="$release_cache" node --test tests/acceptance/managed-*-packed.test.mjs
+```
+
+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.
 
 When passed an existing tarball, the verifier intentionally prints `revision unknown`:
 the current checkout cannot prove which commit produced arbitrary supplied bytes. Record
@@ -100,12 +117,13 @@ work belongs under `Unreleased` and gets a new candidate record.
 
 ## Capture only capabilities you observed
 
-Run native real-client checks only on the versions and platforms where retained fixtures
-prove that boundary. Exact-version evidence governs normal-turn and guard behavior. Claude
-Code live delivery instead uses its captured macOS arm64 minimum plus a current feature
-probe and per-session handshake, and its vendor development-channel warning remains part
-of startup. Codex's queue capture passed but live delivery was withdrawn because the
-required mode hides session workspace identity.
+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

package/docs/SECURITY_MODEL.md

@@ -42,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.
@@ -66,18 +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 live adapter must match its declared evidence contract, one unexpired generation-bound
-binding, and the recipient's opt-in policy. Opaque endpoint references remain inside the
-adapter and outside repositories. Claude Code live delivery is currently supported on
-macOS arm64 from the captured 2.1.258 minimum when a current feature probe and per-session
-handshake pass; it remains experimental and off by default. Codex's queue capture passed,
-but the capability was withdrawn because the required mode hides session workspace
-identity.
+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.
 
@@ -93,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