agents-can-communicate 0.3.1 → 0.4.1

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.1`;
 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,42 @@ 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
+
+An initial managed installation enables automatic updates; later installs preserve an
+explicit opt-out. Full uninstall pauses updates while retaining the setting for a later
+reinstall. 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
 

package/docs/TROUBLESHOOTING.md

@@ -24,6 +24,45 @@ requires plugin trust.
 ACC does not launch a missing session. Open it normally after fixing the installation or
 workspace path.
 
+## A hook says `workspace contains ACC runtime state`
+
+The current directory contains ACC's own state, so ACC cannot use it as a workspace.
+This commonly happens when a client starts in your home directory (`~`). The client
+continues normally, but ACC provides no coordination context there.
+
+Open a project directory and restart the client from it. A project inside your home
+works normally; Git is optional. If you intentionally need the broader directory as
+a workspace, configure `ACC_DATA_HOME` outside it for all participating clients.
+This changes the state location; it does not migrate existing history or integrations.
+
+For a generic `coordination unavailable` warning, run `acc status --json` from the
+same directory to see the detailed workspace error, and `acc doctor` to check the
+installation. Hook warnings deliberately omit arbitrary paths and error details.
+
+## CLI says `caller_identity_unresolved`
+
+ACC cannot prove which session owns this shell command. A hook-created presence record
+and the client's native session ID are not shell credentials. Restarting hooks alone does
+not fix this CLI limitation.
+
+In Grok, run public `acc status --json` through the terminal tool first. With the
+updated integration, the ACC hook reminder arrives after that result and supplies
+the session's own CLI arguments. Restart Grok after refreshing its integration;
+a header returned with `finish` belongs to the session that just closed.
+
+Use this session's ACC MCP tools if available. For a manual CLI workflow, open your own
+session with `acc attach --participant my-session --json`, retain the returned `sessionId`
+and `generation`, and pass both as `--session` and `--generation` on subsequent mutations
+and inbox reads. This creates separate manual presence; finish it with the same pair.
+An operator may explicitly configure `ACC_SESSION` and `ACC_GENERATION` instead.
+Neither a new manual session nor a generic MCP connection inherits the hook participant's
+inbox. Pending messages must be handled through the identity they address; if that
+identity is unavailable, report the limitation.
+
+Do not copy another session from `status`, read its binding, or guess a generation. Public
+`status` and `sync` still work. If ownership is unavailable, report the coordination
+limitation and continue the user's actual work.
+
 ## A message stays queued
 
 Queued means the durable message is safe; it does not mean the recipient model saw it. The
@@ -39,28 +78,45 @@ idle session. Grok, generic MCP, unknown client versions, and other platforms po
 reply acknowledges the original automatically; `acc ack` is for acknowledgement-only
 messages.
 
+A background inbox command is not evidence that the model will resume. If a reviewer
+ends its turn or exits before the request arrives, the review is still incomplete. For
+an agreed review in the current session, keep the turn active through bounded foreground
+waits and inbox checks; if the wait must end, report the pending review and leave a partial
+handoff. ACC does not restart an exited client.
+
 ## I enabled live delivery but got fallback
 
-`--delivery actionable|all` is recipient policy, not a capability switch. Only Claude Code
-2.1.258 and newer on macOS arm64 can take the live path; everything else is next-turn or
-inbox by design. When Claude does fall back, it is almost always one of these:
+`--delivery actionable|all` records recipient intent; delivery also needs a
+supported platform, current probe and exact session binding. Under `actionable`,
+a `note` stays queued with `delivery_disabled`.
 
-- **An old terminal.** The launcher is put on `PATH` by a line in `.zshrc`, which only new
-  interactive shells read. `which claude` must point into `…/acc/bin`.
-- **A failure from the last quarter hour.** Claude caches a failed channel connection in
-  `~/.claude/mcp-needs-auth-cache.json` and skips reconnecting for about fifteen minutes.
-  Remove the `acc` entry there and start the session again.
-- **A note.** Under `actionable`, only messages that need acting on are pushed; a `note`
-  reports `delivery_disabled` on purpose.
-- **Codex.** Its live capability was withdrawn, and `acc doctor` says why.
+For Codex, use your ordinary launch command with 0.152.1 or newer on Apple Silicon
+macOS. Its LocalDaemon must already be running, and trusted hooks must establish
+the receiver's exact thread and workspace. Embedded sessions, an absent socket,
+ambiguous recipients or failed identity checks retain durable inbox access.
+`acc doctor` reports current eligibility. ACC preserves requested consent through
+a temporary daemon outage and does not start the daemon for you.
 
-The installer therefore keeps effective policy off and reports exact-certified next-turn
-or inbox fallback. This is expected, not a partially working live route.
+For Claude Code, open a fresh interactive zsh after installation so its launcher
+is on PATH, and accept its visible development-channel warning. A failed channel
+connection may remain in Claude's `~/.claude/mcp-needs-auth-cache.json` for about
+fifteen minutes; remove only the `acc` entry and restart if that is the cause.
+
+Closing a Codex terminal can leave its daemon thread loaded and eligible. Use
+`acc install --adapter codex --delivery off` to stop new ACC native offers.
+Already accepted queue entries remain with the vendor. Actual thread archive
+requires Codex's confirmation and produces `SessionEnd`.
 
 ## Codex plugin is listed but inactive
 
-Trust the plugin in Codex, then restart it. Until the client accepts that trust step, hooks
-do not run. `acc doctor` reports the installed cache copy and missing activation separately.
+Open `/plugins` in Codex and check ACC is enabled. Open `/hooks`, review each ACC hook,
+and enable/trust its current definition if needed; then restart the session. New or changed
+definitions need review, and a trusted hook can still be disabled.
+
+`acc doctor` reports installed files separately from hook readiness, which it leaves
+unverified. A saved trust record cannot prove current activation. If installation preserved
+your own sandbox configuration, doctor also names the ACC state directory whose access
+you should check in `sandbox_workspace_write.writable_roots`.
 
 ## Gemini does not guard a write
 
@@ -76,8 +132,12 @@ or start the session somewhere trusted.
 
 ## Grok shows no injected message
 
-Grok 1.0.13 discarded UserPromptSubmit context in the real capture. Its next-turn and guard
-capabilities remain false. Use `acc status` and `acc inbox`; do not wait for a banner.
+Grok discards UserPromptSubmit context. On the observed 1.0.24 client, run public
+`acc status --json` in its terminal first: the ACC hook reminder after the result
+supplies your own `--session` and `--generation` pair for subsequent inbox reads and
+mutations. Restart Grok after refreshing its installed hooks and skill. Its next-turn,
+live delivery, and guard capabilities remain false; peer messages require explicit inbox
+reads. If the header never arrives, report missing ownership rather than adopting a peer.
 
 ## Kimi sessions remain in history
 
@@ -92,8 +152,8 @@ Exit code `5` names the overlapping claim and owner. Ask the owner or wait for r
 an explicit authority has decided to replace it:
 
 ```bash
-acc release --claim claim_x --authority "agreed with models" \
-  --reason "handing over the file"
+acc release --claim claim_x --authority human \
+  --reason "human approved the handover after agreement with the models"
 ```
 
 ## Protection says advisory
@@ -114,7 +174,29 @@ ACC removes only bytes that still match its install record. Anything edited by t
 reported and retained. Remove those leftovers manually if desired.
 
 Runtime state is outside the repository by design. `ACC_DATA_HOME` can relocate it, but ACC
-refuses a path inside any workspace root.
+refuses a path inside any workspace root. Relocate the whole data directory; a symlink for
+that directory is supported. Install rejects a symlink that moves only the internal
+`acc/runtime` tree, because runtime admission and the bootstrap cache need the same data home.
 
 Next: [Getting started](GETTING_STARTED.md) · [Capabilities](CAPABILITIES.md) ·
 [Configuration](CONFIGURATION.md)
+
+## An automatic update is pending
+
+Run `acc doctor` to see the update policy and pending notice. ACC process leases, including
+persistent MCP servers, require confirmed process exit. Native bindings clear on observed
+SessionEnd or confirmed process death; a vendor daemon may remain alive after SessionEnd.
+Unknown PIDs remain holds until lifecycle cleanup. Close the relevant client sessions and
+ACC processes; `finish`, presence TTL, and delivery off do not prove native end. ACC never
+manages the daemon or expires safety holds merely by elapsed time.
+
+Use `acc update` to retry a failed download or finish an interrupted integration refresh.
+A download failure keeps the working version. A partial integration refresh blocks
+workspace commands until recovery completes, while hooks let the client continue without
+ACC context. `acc update` names the failed adapter, cause, and known configuration paths;
+fix that problem and rerun it. Help and update recovery remain available. `ACC_NO_UPDATE_CHECK=1` prevents
+new downloads but permits manual activation of an already verified pending update.
+
+To stop automatic downloads, use `acc update --auto off`. To stay on the current release,
+use `acc update --pin <version>`. Neither setting converts workspace data for an older
+runtime. See the [upgrade guide](UPGRADING.md).

package/docs/UPGRADING.md

@@ -0,0 +1,154 @@
+# Upgrading to 0.4.1
+
+## From 0.4.0
+
+This patch keeps the existing workspace data format. It fixes Grok CLI ownership,
+relocated Grok profiles, automatic-update preferences after reinstall, and the warning
+when a client starts in a directory containing ACC's own state.
+
+Close the participating clients and persistent ACC MCP processes, then run:
+
+```bash
+acc update
+acc version
+acc doctor
+```
+
+After publication, `acc version` should report 0.4.1. A managed update refreshes the
+installed integrations and skills. Restart the clients and complete any hook/trust
+review they request. Existing managed installations activate the selected runtime
+through `acc update`; use the npm install steps below for pre-0.4 or unmanaged
+installations. When pinned to 0.4.0, select 0.4.1 or clear the pin first.
+
+In Grok, the refreshed skill runs public status through the terminal before its first
+owned command. The hook reminder after that result supplies the session's own CLI
+arguments. Grok still reads peer messages explicitly through inbox; this patch does not
+add external wake or certify guards. Start clients in a project directory, rather than
+in a home directory containing ACC state.
+
+## From 0.3.1
+
+Upgrade all ACC installations participating in a workspace together, then restart their
+agent clients. The new runtime reads existing 0.3.1 messages, receipts, decisions, intent,
+and claims. Installing it does not migrate or clear that history.
+
+Mixed running versions are unsupported. Once a new session records an explicit decision
+replacement or withdrawal, the published 0.3.1 reader rejects its `decisionChange` field.
+Its doctor can label the valid new record as corrupt. Upgrading the remaining reader
+restores access; deleting or editing the record is not a remedy.
+
+## Update the runtime and client integrations
+
+1. Finish or pause ongoing work and close the participating clients, including persistent
+   ACC MCP processes. A running process can retain the old code after npm replaces its files.
+   If rollback matters, take a copy of the complete ACC data directory and client settings
+   while those processes are stopped. Keep the copy outside the repository; see
+   [runtime locations](CONFIGURATION.md#override-local-paths-and-identity).
+2. Install the released package, then refresh the client integrations:
+
+   ```bash
+   npm install --global agents-can-communicate@0.4.1
+   acc version
+   acc install
+   ```
+
+   Before publication, use the exact candidate `.tgz` supplied for testing instead of the
+   registry version. `acc version` must report the intended version. If it does not, fix
+   which `acc` your shell resolves before running the installer.
+3. Run `acc doctor` from each project you use. Check the runtime and installed bundle
+   diagnostics, and follow any activation instructions from `acc install`. In Codex,
+   check `/plugins`, review and enable/trust the current ACC definitions in `/hooks`, then
+   restart the session. Doctor cannot establish that the client has activated its hooks.
+   In the observed stock Codex 0.153.4 upgrade from 0.3.1 to 0.4, command quoting changed
+   all five ACC hook definitions and required a fresh review of the modified hooks. After
+   that review, a subsequent restart retained all five active. This is activation evidence
+   for that transition, not a promise of trust across arbitrary future upgrades.
+4. Resume the intended conversations and confirm peer presence with `acc status`. An
+   unrelated new conversation normally has a new participant id; it does not inherit the
+   previous conversation's addressed inbox. Historical decisions and handoffs remain
+   available through [history reads](CLI.md#historical-recovery).
+
+`npm install` alone updates the package but does not refresh the skills and plugin copies
+inside clients. `acc install` preserves user settings and the recorded delivery policy;
+it does not turn experimental delivery on for a previously opted-out client. Effective
+delivery still depends on the current client's capabilities.
+
+## Automatic updates after installation
+
+An initial `acc install` turns automatic updates on. Later installs preserve an explicit
+`acc update --auto off` choice. Full uninstall pauses updates and preserves the setting
+for the next install. ACC checks for stable releases in
+an independent background process, normally at most once a day, downloads and verifies a
+separate runtime copy, and refreshes the installed integrations and skills before switching.
+The global npm package provides a launcher; the active runtime lives under ACC's data home.
+
+Running ACC processes, including idle MCP servers, hold the current version until
+confirmed process exit. Native bindings hold until observed client SessionEnd cleanup or
+confirmed process death; the vendor daemon can remain running after that lifecycle event.
+Unknown PIDs remain conservative holds until lifecycle cleanup. `acc finish`, presence TTL,
+and delivery off alone do not prove native end. Close the relevant client sessions and
+persistent ACC processes to release holds; ACC does not manage the vendor daemon.
+Hooks never wait for a network download. If integration refresh temporarily prevents
+coordination, a hook lets the client continue; its next genuine user turn can restore a
+missing binding.
+
+```bash
+acc update                    # download and apply, or report what is keeping it pending
+acc update --check            # check without installing or changing update settings
+acc update --auto off         # disable background updates
+acc update --auto on          # enable them again
+acc update --pin 0.4.1        # stay on this exact stable version
+acc update --pin none         # follow stable releases again
+```
+
+ACC 0.4.0 lost the previous update setting during a full uninstall. If you already ran
+that version's `uninstall` and want updates enabled after reinstalling, run
+`acc update --auto on` once. A later installer cannot distinguish that old uninstall
+state from an explicit opt-out, so it keeps the recorded `off` value until you change it.
+
+`--apply` remains an alias for the plain update command. Pins cannot downgrade an active
+runtime. `ACC_NO_UPDATE_CHECK=1` disables update networking and background scheduling;
+manual recovery of an already downloaded update still works. Downloading needs npm, but
+does not require permission to replace a global installation and never runs package
+lifecycle scripts. `acc doctor` reports the automatic-update policy and pending notice.
+
+A failed download or verification keeps the active runtime. An interrupted integration
+refresh keeps workspace admission closed until `acc update` finishes the refresh. It does
+not roll workspace history back. A failed refresh exits with code `4` and reports the adapter
+and configuration problem to fix before retrying; a verified update waiting for live clients
+remains pending. Previous runtime and plugin cache versions are
+retained so existing launch paths survive the change.
+
+Client trust is still controlled by the client. Follow any reported activation or hook
+review steps; copied files do not prove the client has activated them. The initial
+published-0.3.1 transition above still requires a coordinated restart: old direct binaries
+and existing embedded core consumers cannot be enrolled retroactively.
+
+## Update scripts and MCP consumers
+
+Default CLI/MCP inbox reads and `acc://inbox` now return `{items, nextCursor}` summary
+pages. They omit bodies and do not mark messages retrieved. Code that expected a full
+array must list a page, select a message id, then make an exact inbox read to retrieve its
+body. Follow `nextCursor` until it is `null` when inspecting the whole pending inbox.
+Exact inbox reads retain the one-item full-message array and receipt transitions.
+See [CLI inbox](CLI.md#inbox-reply-and-acknowledgement) and [MCP](MCP.md).
+
+New decision links remove superseded records from ordinary inbox and automatic attention,
+while retaining their bodies and original receipts in history. A terminal withdrawal
+remains visible. These changes do not acknowledge old obligations on the recipient's
+behalf. Use `acc sync --scope history --type decision --current` to discover the current
+explicit choices, withdrawals, and conflicts.
+
+## Recovery and rollback
+
+An old reader reporting `message.decisionChange is not a known field`, or old doctor
+reporting an unreadable record immediately after a decision change, needs the new runtime.
+Run the new `acc version`, refresh integrations, restart clients, and use the new
+`acc doctor`. If that doctor still reports a fault, inspect its named paths as a separate
+problem. Do not erase history or use an old repair command to resolve version mismatch.
+
+There is no downgrade conversion for new decision records. Reinstalling 0.3.1, including
+using `acc install --downgrade`, does not make them readable by old clients. A rollback
+that restores a pre-upgrade data copy necessarily omits subsequent coordination records;
+retain the newer copy separately. Prefer completing the upgrade so all history remains
+available.

package/docs/WHY_ACC.md

@@ -35,7 +35,7 @@ retain their own authority and context.
 | Mix clients and worktrees | Worktrees of one repository map to one local workspace while each session keeps its checkout identity. Git is optional. |
 | Ask without granting authority | Messages are attributed untrusted data. A request expects a reply but is not an order. |
 | Recover after compaction or restart | Messages and receipts commit before delivery; participant addressing survives when the participant id is stable. |
-| Avoid overlapping edits | Intent warns; narrow claims may advise or guard, depending on every live client's measured capability. |
+| Avoid overlapping edits | Intent warns; CLI claims default to advisory. Explicit guarded enforcement also requires every live client's measured guard. |
 | Trust delivery language | Recorded, queued, offered, retrieved, and acknowledged are separate observable facts. |
 | Keep it private and removable | State is local and outside repositories; transcripts are excluded; uninstall preserves user edits. |
 
@@ -52,9 +52,10 @@ coordinate across machines.
 
 ACC also does not merge model memory, read raw conversations, guarantee agent choices,
 approve tools, operate CI,
-or make guarded claims immune to unrelated local processes. Live push exists for one client
-and never interrupts a turn in progress - a message that arrives mid-turn waits for the turn
-to finish - so workflows that require interrupting a running model should not depend on ACC.
+or make guarded claims immune to unrelated local processes. Experimental live delivery is
+available through Claude Code Channel and Codex LocalDaemon on supported versions and
+platforms, behind recipient opt-in and with possible token spend. Neither interrupts a
+turn in progress; messages wait for it to finish. See [Capabilities](CAPABILITIES.md).
 
 If the sessions should remain yours and simply stop working in isolation, that is the
 product ACC is designed to be.

package/docs/index.md

@@ -13,6 +13,8 @@ decides what its task requires.
 3. [Capabilities](CAPABILITIES.md) — check what your client and platform can actually do.
 4. [Troubleshooting](TROUBLESHOOTING.md) — diagnose missing peers, queued messages, and
    capability fallback.
+5. [Upgrading ACC](UPGRADING.md) — update from 0.4.0, preserve history, refresh integrations,
+   and account for the data-format and inbox-response changes from 0.3.1.
 
 ## See it in context
 
@@ -48,5 +50,11 @@ decides what its task requires.
 - [Design decisions](DESIGN_DECISIONS.md) — architectural decisions and reversals.
 - [Releasing](RELEASING.md) — packed-artifact verification.
 
+Dated planning/reference material under
+[`docs/internal/`](https://github.com/automatis-tools/agents-can-communicate/tree/main/docs/internal)
+and [`docs/superpowers/`](https://github.com/automatis-tools/agents-can-communicate/tree/main/docs/superpowers)
+is not current product documentation. Published release-evidence records retain their
+original source/artifact/capture provenance rather than certifying a later build.
+
 Runtime state and raw transcripts are not documentation artifacts and never belong in the
 repository.