agents-can-communicate 0.2.0 → 0.3.1

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.
 
@@ -182,13 +185,15 @@ livePolicy · opaqueEndpointRef · leaseUntil
 The recipient owns `livePolicy` because native push may start a model turn:
 
 - `off`: inbox and normal next-turn paths only;
-- `actionable`: questions, requests, and addressed handoffs may use live push;
+- `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.
+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.
 
 ## Attention and sync
 

package/docs/RELEASING.md

@@ -1,109 +1,139 @@
 # 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`;
+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. Start from a clean,
+dedicated release worktree, 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.2.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.
 
-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.
+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.
 
-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.
+## Pack and verify the exact artifact
 
-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" 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"
+```
+
+`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.
 
-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 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.
+
+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
 
@@ -64,10 +66,13 @@ 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
+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. Current Codex and Claude native captures failed, so no
-live transport is enabled.
+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.
 
 ## Claims
 

package/docs/TROUBLESHOOTING.md

@@ -9,9 +9,14 @@ acc doctor
 It reports detected clients, exact versions, installation ownership, capability downgrade,
 and the next action. Restart a client after installation because hooks load at startup.
 
+You should not need to tell an agent to use ACC as part of a normal task. If coordination
+is not visible, first check integration and capability facts here. Remember that a working
+integration provides awareness; it cannot guarantee that a model will find a peer relevant
+or coordinate on every task.
+
 ## The second session does not appear
 
-Run `acc status --json` in both windows and compare `workspaceId`. Common causes are an
+As a diagnostic, run `acc status --json` in both windows and compare `workspaceId`. Common causes are an
 already-running client that never loaded the hook, a generic MCP server launched without
 `ACC_MCP_WORKSPACE`, or two plain directories that are not the same workspace. Codex also
 requires plugin trust.
@@ -21,26 +26,33 @@ workspace path.
 
 ## A message stays queued
 
-Queued means the durable message is safe; it does not mean the recipient model saw it.
-Have the recipient run:
+Queued means the durable message is safe; it does not mean the recipient model saw it. The
+receiving agent can recover it with:
 
 ```bash
 acc inbox
 acc inbox --message message_x
 ```
 
-Certified next-turn delivery waits for that client's next normal prompt. Grok, generic MCP,
-unknown client versions, and other platforms poll inbox. A reply acknowledges the original
-automatically; `acc ack` is for acknowledgement-only messages.
+Certified next-turn delivery waits for that client's next normal prompt; it never wakes an
+idle session. Grok, generic MCP, unknown client versions, and other platforms poll inbox. A
+reply acknowledges the original automatically; `acc ack` is for acknowledgement-only
+messages.
 
 ## I enabled live delivery but got fallback
 
-`--delivery actionable|all` is recipient policy, not a capability switch. No current
-adapter has passing native live-push certification:
+`--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:
 
-- Codex 0.152.0: the existing app-server control socket was absent; ACC did not start one.
-- Claude Code 2.1.252: the capture stopped at the development-channel warning before the
-  ACC child process started.
+- **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.
 
 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.
@@ -53,9 +65,15 @@ do not run. `acc doctor` reports the installed cache copy and missing activation
 ## Gemini does not guard a write
 
 Default and `plan` modes expose no write tool to the model. `auto_edit` exposes edit tools;
-shell availability depends on approval mode. Only Gemini CLI 0.37.0 on `darwin-arm64` has
+shell availability depends on approval mode. Only Gemini CLI 0.57.0 on `darwin-arm64` has
 package-shipped delivery certification; other versions still use inbox.
 
+From 0.55 onwards there is a quieter cause with the same symptom: an untrusted folder. The
+client prints `Approval mode overridden to "default" because the current folder is not
+trusted` and keeps going, and the default mode has no write or shell tool to guard - so the
+guard never fires and the mode you passed appears to have been ignored. Trust the folder,
+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

package/docs/WHY_ACC.md

@@ -1,14 +1,15 @@
 # Why ACC
 
-ACC exists for a narrow situation: you already have several AI sessions open, each with
-its own client, context, permissions, checkout, and human direction, and they need to
-communicate without becoming workers owned by one controller.
-
-That boundary matters. Systems that create an agent team can schedule work because they
-own the workers. ACC deliberately does not. It gives independent sessions a local durable
+ACC fits a familiar workflow: you open several AI sessions, give each one a task, and keep
+their contexts, permissions, checkouts, and models independent. The missing piece is peer
+awareness. When their work overlaps, they need to ask and answer each other without making
+you carry every sentence between windows.
+
+Supported integrations provide that awareness and teach agents the coordination interface.
+The agents decide whether a dependency or peer is relevant. ACC does not assign tasks or
+promise that every model will coordinate; it gives independent sessions a local, durable
 place to discover peers, ask questions, answer in threads, acknowledge messages, reserve
-resources, and hand off context. If every session closes, the durable records still tell
-the truth.
+resources, and hand off context.
 
 ## Does it fit?
 
@@ -22,16 +23,16 @@ flowchart TD
   C -->|no| N
 ```
 
-The strongest adoption signal is not installation or a large roster. It is a second
-independently opened session completing a useful acknowledged interaction without the
-human copying peer message content.
+The useful result is simple: related tasks proceed without the human acting as a message
+bus. One agent can ask for an interface, the other can answer in the same thread, and both
+retain their own authority and context.
 
 ## What is different
 
 | Need | ACC's boundary |
 |---|---|
 | Keep sessions you already opened | Hooks or MCP add participation; ACC never starts replacement workers. |
-| Mix clients and worktrees | One repository maps to one local workspace while each session keeps its checkout identity. Git is optional. |
+| 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. |
@@ -49,10 +50,11 @@ select models, spend token budgets, or control process lifecycle. Choose a track
 you need organizational planning. Choose a hosted service when participants must
 coordinate across machines.
 
-ACC also does not merge model memory, read raw conversations, approve tools, operate CI,
-or make guarded claims immune to unrelated local processes. Current native live push is
-uncertified, so workflows that require immediate interruption of an already-running model
-should not depend on ACC today.
+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.
 
 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

@@ -1,27 +1,31 @@
 # ACC documentation
 
-ACC connects independently opened AI sessions so they can discover peers and communicate
-without becoming one managed agent team. This map starts with the useful interaction, then
-separates protocol truth from adapter reach.
+ACC adds peer awareness and communication to AI sessions you open yourself. You continue
+to give each agent ordinary work; supported integrations tell agents about their peers and
+teach them how to coordinate when it is useful. The agents remain independent, and each
+decides what its task requires.
 
-## Evaluate
+## Start here
 
-1. [Why ACC](WHY_ACC.md) — the product boundary and when a managed runtime fits better.
-2. [Concepts](CONCEPTS.md) — peers, durable threads, receipts, intent, and claims.
-3. [Capabilities](CAPABILITIES.md) — certified support, current reachability, recipient
-   policy, fallback, and limitations beside each adapter.
+1. [Getting started](GETTING_STARTED.md) — install ACC, open two sessions, give them related
+   tasks, and know what coordination to look for.
+2. [Why ACC](WHY_ACC.md) — decide whether independent peer coordination fits your work.
+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.
 
-## Use it
+## See it in context
 
-1. [Getting started](GETTING_STARTED.md) — two user-opened sessions complete one useful
-   acknowledged question-and-answer interaction.
-2. [CLI](CLI.md) — exact commands, flags, result shapes, and exit codes.
-3. [MCP](MCP.md) — durable polling for clients without a native adapter.
-4. [Configuration](CONFIGURATION.md) — optional workspace identity and policy.
-5. [Troubleshooting](TROUBLESHOOTING.md) — symptoms, exact downgrades, and fixes.
+- [Three agents, one repository](https://github.com/automatis-tools/agents-can-communicate/blob/main/examples/three-workstreams.md)
+  — related implementation tasks with direct dependency questions and advisory claims.
+- [Research without Git](https://github.com/automatis-tools/agents-can-communicate/blob/main/examples/non-git-research.md)
+  — two local sessions sharing findings in a plain folder.
 
-## Understand and extend it
+## Understand the system
 
+- [Concepts](CONCEPTS.md) — peers, workspaces, durable threads, receipts, intent, and claims.
+- [How ACC works](HOW_IT_WORKS.md) — the path from integration awareness through durable
+  storage, delivery fallback, reply, and acknowledgement.
 - [Protocol](PROTOCOL.md) — message envelope, thread rules, receipt lifecycle, handoffs,
   bindings, and the clean v0.2 store break.
 - [Architecture](ARCHITECTURE.md) — record-first flow, package boundaries, router, storage,
@@ -32,6 +36,12 @@ separates protocol truth from adapter reach.
   installation ownership.
 - [Glossary](GLOSSARY.md) — each public term in one line.
 
+## Reference
+
+- [CLI](CLI.md) — exact commands, flags, result shapes, and exit codes.
+- [MCP](MCP.md) — durable polling for clients without a native adapter.
+- [Configuration](CONFIGURATION.md) — optional workspace identity and policy.
+
 ## Project work
 
 - [Contributing](https://github.com/automatis-tools/agents-can-communicate/blob/main/AGENTS.md) — invariants and the mutation-proof gate.