agents-can-communicate 0.3.1 → 0.4.0

package/bin/entrypoints/acc-claude-channel.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// The ACC Channel binary Claude Code spawns as a stdio MCP child. It composes
+// the same workspace discovery, session binding, core service, and local
+// data-home rules as acc-hook, opens a session-scoped endpoint for the delivery
+// router, and turns the model's explicit acc_reply / acc_ack into real ACC
+// records. It never collects a transcript or runs a model, and it fails open:
+// any composition error leaves Claude a plain MCP server that simply offers no
+// tools rather than crashing the session.
+import { randomBytes } from "node:crypto";
+
+import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
+import { listSessionBindings } from "@agents-can-communicate/adapter-sdk";
+import { createCoordinationService } from "@agents-can-communicate/core";
+import { resolveClientPid } from "@agents-can-communicate/hook-runner/client-pid";
+import { readProcessTable } from "@agents-can-communicate/hook-runner/process-table";
+import { createId } from "@agents-can-communicate/protocol";
+import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
+import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
+  from "@agents-can-communicate/cli";
+
+import { createAccChannel, endpointDir, routeAck, routeReply }
+  from "@agents-can-communicate/adapter-claude-code/channel";
+
+import { pump, startInertChannel } from "./claude-channel-stdio.mjs";
+
+const clock = { now: () => new Date().toISOString() };
+const ids = { next: kind => createId(kind, randomBytes) };
+
+/**
+ * The ACC session this Claude process opened - decided by which client process
+ * this Channel is running under, never by how many sessions happen to be
+ * visible.
+ *
+ * There used to be a fallback here: if exactly one session was live, it was
+ * taken to be this one. On a single-session machine that looked safe, and with
+ * two sessions it silently handed one client the other's identity. The Channel
+ * starts while its own SessionStart hook is still writing its binding, so the
+ * only binding a second client can see at that moment is the *first* client's -
+ * and the wait that was added to survive that race then locks the wrong answer
+ * in on the first attempt, because it is a complete, live, plausible binding.
+ *
+ * Measured on two real 2.1.259 sessions: both Channels registered an endpoint
+ * under the first client's pid. `bindNativeSession` refuses two registrations
+ * for one pid, so the session that had been receiving live messages dropped
+ * back to the durable inbox - and an `acc_reply` from the second window would
+ * have been recorded as the first session's answer, which is a false record
+ * rather than a lost message.
+ *
+ * This process was spawned by its client, so its own ancestry names that
+ * client, and no race can change that. Ownership is decided by it.
+ */
+export async function resolveSession({ runtimeDir, service, env, ownClientPid,
+  listBindings = listSessionBindings }) {
+  if (!Number.isInteger(ownClientPid)) return null;
+  const bindings = await listBindings({ runtimeDir });
+  if (bindings.length === 0) return null;
+  const status = await service.collectStatus({});
+  const live = new Set(status.participants
+    .filter(participant => participant.presence !== "offline")
+    .map(participant => participant.sessionId));
+  const mine = bindings.filter(binding => live.has(binding.accSessionId)
+    && binding.clientPid === ownClientPid);
+  // One client process can outlive a session and open another, so the pid alone
+  // can still name two. The harness session id the client exports separates
+  // them; with nothing to separate them the answer is nobody, as before.
+  const exported = new Set(Object.values(env ?? {}).filter(value => typeof value === "string"));
+  const matched = mine.filter(binding => exported.has(binding.harnessSessionId));
+  const chosen = mine.length === 1 ? mine[0] : matched.length === 1 ? matched[0] : null;
+  return chosen === null ? null
+    : { sessionId: chosen.accSessionId, generation: chosen.generation, clientPid: chosen.clientPid };
+}
+
+/** The client process this Channel was spawned by, or null when nobody knows. */
+export async function ownClient({ table = null, from = process.pid,
+  command = createClaudeCodeAdapter().client.command } = {}) {
+  return resolveClientPid({ table: table ?? await readProcessTable(), from, command });
+}
+
+// How long the Channel will wait for the hook to publish this session's
+// binding. Claude spawns this child while SessionStart is still running - both
+// landed in the same second on a real 2.1.259 launch - and a single lookup
+// loses that race often enough to make native delivery activate or not per
+// launch. Bounded, because a session with no ACC binding must still be answered.
+const BINDING_WAIT_MS = 5_000;
+const BINDING_POLL_MS = 100;
+
+/**
+ * The session binding, once it exists - or null when the wait runs out.
+ *
+ * A binding with no `clientPid` names no process, and the Channel binds an
+ * exact one, so it does not count as resolved: the hook writes the identity
+ * first and the certified facts after, and reading in between must keep waiting
+ * rather than settle for the half-written answer.
+ */
+export async function resolveWithin({ resolve, deadline, intervalMs = BINDING_POLL_MS,
+  now = () => Date.now(), sleep = ms => new Promise(resolve_ => setTimeout(resolve_, ms)) }) {
+  for (;;) {
+    const session = await resolve();
+    if (session !== null && Number.isInteger(session?.clientPid)) return session;
+    if (now() >= deadline) return null;
+    await sleep(intervalMs);
+  }
+}
+
+async function compose() {
+  const descriptor = await discoverWorkspace({ cwd: process.cwd(), env: process.env,
+    gitProbe: createGitProbe() });
+  const paths = runtimePaths({ dataHome: platformDataHome({ platform: process.platform,
+    env: process.env }), workspaceId: descriptor.id, workspaceRoots: descriptor.roots });
+  const store = await openFilesystemStore({ root: paths.root, clock, ids,
+    workspaceId: descriptor.id });
+  const service = createCoordinationService({ store, clock, ids });
+  const write = payload => process.stdout.write(`${JSON.stringify(payload)}\n`);
+  // Read once: the ancestry that decides ownership cannot change while this
+  // process runs, and re-reading it on every poll would spawn `ps` in a loop.
+  const clientPid = await ownClient();
+  const session = await resolveWithin({
+    resolve: () => resolveSession({ runtimeDir: paths.root, service, env: process.env,
+      ownClientPid: clientPid }),
+    deadline: Date.now() + BINDING_WAIT_MS });
+  // No binding to serve - but Claude is already speaking MCP to this child, and
+  // returning here left the event loop empty: the process exited in 75ms
+  // without answering `initialize`, and Claude reported the server as failed to
+  // connect on every session that enables the plugin without ACC's shim.
+  if (session === null || !Number.isInteger(session.clientPid)) {
+    return startInertChannel({ write });
+  }
+
+  const channel = createAccChannel({
+    endpointDir: endpointDir(paths.root),
+    clientPid: session.clientPid,
+    write,
+    routeReply: ({ messageId, body }) => routeReply({ service, session, messageId, body }),
+    routeAck: ({ messageId }) => routeAck({ service, session, messageId }),
+    // This process is the only party that knows the endpoint is still being
+    // served, and Claude publishes no heartbeat, so nothing else would move
+    // ACC's lease while the session sits idle - which is when live delivery is
+    // worth having.
+    refreshBinding: leaseUntil => service.refreshDeliveryBinding({
+      sessionId: session.sessionId, generation: session.generation, leaseUntil }),
+  });
+  await channel.listen();
+  pump(channel.handleLine, () => { channel.close(); process.exit(0); });
+  return channel;
+}
+
+export async function main() {
+  await compose().catch(() => startInertChannel());
+}

package/bin/entrypoints/acc-hook.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Hook entry point: `acc-hook <adapter-id> <kind>`, payload on stdin.
+//
+// Every harness runs this as a short-lived child process in front of the user's
+// turn. The one rule that overrides all others here: never be the reason
+// someone's session stops working. Unknown adapter, malformed payload, broken
+// store, missing binding - all of them end in "allow, exit 0".
+import { randomBytes } from "node:crypto";
+
+import { createId } from "@agents-can-communicate/protocol";
+import { runHook } from "@agents-can-communicate/hook-runner";
+
+import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
+import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
+import { createGeminiCliAdapter } from "@agents-can-communicate/adapter-gemini-cli";
+import { createGrokAdapter } from "@agents-can-communicate/adapter-grok";
+import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
+
+const adapters = {
+  claude_code: createClaudeCodeAdapter(),
+  codex: createCodexAdapter(),
+  gemini_cli: createGeminiCliAdapter(),
+  grok: createGrokAdapter(),
+  kimi: createKimiAdapter(),
+};
+
+const readStdin = () => new Promise(resolve => {
+  // A hook is always given its payload on stdin, but a client that closes it
+  // without writing must not leave this process hanging in front of a turn.
+  if (process.stdin.isTTY) return resolve("");
+  let raw = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", chunk => { raw += chunk; });
+  process.stdin.on("end", () => resolve(raw));
+  process.stdin.on("error", () => resolve(""));
+  return undefined;
+});
+
+import { completeHookOutput } from "./hook-output.mjs";
+
+export async function main() {
+  const [adapterId] = process.argv.slice(2);
+
+  let payload = null;
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    payload = null;
+  }
+
+  const result = await runHook({ adapterId, payload, adapters,
+    runtime: { clock: { now: () => new Date().toISOString() },
+      ids: { next: kind => createId(kind, randomBytes) } },
+    env: process.env });
+
+  const completed = await completeHookOutput(result);
+  process.exitCode = result.exitCode ?? completed.exitCode;
+}

package/bin/entrypoints/acc-mcp.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { randomBytes } from "node:crypto";
+
+import { EXIT, createId } from "@agents-can-communicate/protocol";
+import { createCoordinationService } from "@agents-can-communicate/core";
+import { readInstalledLivePolicy } from "@agents-can-communicate/installer";
+import { createDeliveryRouter } from "@agents-can-communicate/delivery-router";
+import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
+import { ALL_ADAPTERS, createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
+  from "@agents-can-communicate/cli";
+import { serve } from "@agents-can-communicate/mcp-server";
+
+export async function main({ managerRoot = null, packageRoot } = {}) {
+// The composition root is the only place allowed to reach for ambient time and
+// randomness. The participant name comes from configuration, never from the
+// client: the protocol says clientInfo is self-reported and must not drive
+// behaviour, and the session is derived from this configuration alone.
+// Nothing is read from the command line, so nothing may be passed on it. It
+// used to accept and ignore anything: writing `acc-mcp --cwd <project>` - the
+// habit `acc` teaches - started a server rooted wherever the client happened to
+// launch it, alone in a workspace nobody else was in, with no warning at all.
+if (process.argv.length > 2) {
+  process.stderr.write("acc-mcp takes no arguments. It is configured by environment:\n"
+    + "  ACC_MCP_PARTICIPANT   who this server takes part as (default: mcp)\n"
+    + "  ACC_MCP_WORKSPACE     the project it joins (default: the working directory)\n"
+    + `refusing: ${process.argv.slice(2).join(" ")}\n`);
+  process.exit(EXIT.USAGE);
+}
+
+const participantId = process.env.ACC_MCP_PARTICIPANT ?? "mcp";
+const clock = { now: () => new Date().toISOString() };
+const ids = { next: kind => createId(kind, randomBytes) };
+
+const descriptor = await discoverWorkspace({
+  cwd: process.env.ACC_MCP_WORKSPACE ?? process.cwd(),
+  env: process.env,
+  gitProbe: createGitProbe(),
+});
+const dataHome = platformDataHome({ platform: process.platform, env: process.env });
+const paths = runtimePaths({
+  dataHome,
+  workspaceId: descriptor.id,
+  workspaceRoots: descriptor.roots,
+});
+const store = await openFilesystemStore({ root: paths.root, clock, ids,
+  workspaceId: descriptor.id });
+const service = createCoordinationService({ store, clock, ids });
+const adapters = Object.fromEntries(ALL_ADAPTERS().map(adapter => [adapter.id, adapter]));
+
+await serve({
+  input: process.stdin,
+  output: process.stdout,
+  log: message => process.stderr.write(`acc-mcp: ${message}\n`),
+  context: {
+    service,
+    deliveryRouter: createDeliveryRouter({ service, adapters, clock,
+      platform: `${process.platform}-${process.arch}`,
+      readLivePolicy: ({ adapter }) => readInstalledLivePolicy({ dataHome,
+        adapterId: adapter.id }) }),
+    workspaceId: descriptor.id,
+    participantId,
+    descriptor,
+    runtimeDir: paths.root,
+  },
+});
+
+// Exiting on stdin EOF is the only portable graceful shutdown in this binding.
+process.exitCode = 0;
+
+}

package/bin/entrypoints/acc.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+import { createId } from "@agents-can-communicate/protocol";
+import { readInstalledLivePolicy } from "@agents-can-communicate/installer";
+import { createDeliveryRouter } from "@agents-can-communicate/delivery-router";
+import { ALL_ADAPTERS, askConfirmation, main as runCli } from "@agents-can-communicate/cli";
+
+export async function main({ managerRoot = null, packageRoot, managementOnly = false } = {}) {
+const adapters = Object.fromEntries(ALL_ADAPTERS().map(adapter => [adapter.id, adapter]));
+
+// The composition root is the only place allowed to reach for ambient time and
+// randomness; everything below it receives them as ports.
+const runtime = {
+  cwd: process.cwd(),
+  managerRoot,
+  managementOnly,
+  packageRoot,
+  env: process.env,
+  platform: process.platform,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  clock: { now: () => new Date().toISOString() },
+  ids: { next: kind => createId(kind, randomBytes) },
+  createDeliveryRouter: ({ service, clock, dataHome }) =>
+    createDeliveryRouter({ service, adapters, clock,
+      platform: `${process.platform}-${process.arch}`,
+      readLivePolicy: ({ adapter }) => readInstalledLivePolicy({ dataHome,
+        adapterId: adapter.id }) }),
+  // Asked only by `acc config init`, and only when stdout is a terminal. There
+  // was no port here at all, so the question went to the fallback that always
+  // answers no: in a real terminal the command printed "not written" and never
+  // said why, and `--yes` - the flag documented for runs with nobody to ask -
+  // was the only way to write the file.
+  confirm: (question, io = { input: process.stdin, output: process.stdout }) =>
+    askConfirmation(question, io),
+  // The two streams and the fact that a person is at both ends, for the
+  // per-client native delivery question `acc install` asks only interactively.
+  input: process.stdin,
+  output: process.stdout,
+  isInteractive: () => process.stdin.isTTY === true && process.stdout.isTTY === true,
+  // Asked for only by `acc version`, so a package missing its own manifest
+  // fails that one command rather than every command.
+  version: async () => JSON.parse(
+    await readFile(new URL("../../package.json", import.meta.url), "utf8")).version,
+};
+
+process.exitCode = await runCli(process.argv.slice(2), runtime);
+
+}

package/bin/entrypoints/claude-channel-stdio.mjs

@@ -0,0 +1,29 @@
+// Workspace-free MCP fallback shared by composition and managed admission failure.
+import { createInertChannel } from "@agents-can-communicate/adapter-claude-code/channel";
+
+export function startInertChannel({ write = payload => process.stdout.write(JSON.stringify(payload) + "\n") } = {}) {
+  const inert = createInertChannel({ write });
+  pump(inert.handleLine, () => process.exit(0));
+  return inert;
+}
+
+/** One line-delimited JSON pump, for the bound server and the unbound one alike. */
+export function pump(handleLine, shutdown) {
+  let buffer = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", async chunk => {
+    buffer += chunk;
+    let newline = buffer.indexOf("\n");
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      newline = buffer.indexOf("\n");
+      if (line !== "") await handleLine(line);
+    }
+  });
+  process.stdin.on("end", shutdown);
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+  // Keeps the child answerable for as long as Claude holds the transport open.
+  process.stdin.resume();
+}

package/bin/entrypoints/hook-output.mjs

@@ -0,0 +1,73 @@
+export const writeOutput = (stream, output, { deadlineAt } = {}) => {
+  if (output === "") return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer;
+    const finish = error => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      if (error === undefined || error === null) resolve();
+      else reject(error);
+    };
+    if (deadlineAt !== undefined) {
+      const remaining = deadlineAt - Date.now();
+      if (remaining <= 0) {
+        finish(new Error("hook budget exhausted before stdout write"));
+        return;
+      }
+      timer = setTimeout(() => finish(
+        new Error("hook budget exhausted waiting for stdout callback")), remaining);
+    }
+    try {
+      stream.write(output, finish);
+    } catch (error) {
+      finish(error);
+    }
+  });
+};
+
+const DIAGNOSTIC_BYTES = 512;
+
+function boundedDiagnostic(label, error) {
+  const detail = String(error?.message ?? error).replace(/[\u0000-\u001f\u007f]/g, " ");
+  let line = `acc: ${label}: ${detail}`;
+  while (Buffer.byteLength(`${line}\n`, "utf8") > DIAGNOSTIC_BYTES && line.length > 0) {
+    line = line.slice(0, -1);
+  }
+  return `${line}\n`;
+}
+
+function tryWrite(stream, output) {
+  if (output === "") return;
+  try {
+    stream.write(output, () => {});
+  } catch {
+    // A broken diagnostic stream must not turn a failed-open hook into a crash.
+  }
+}
+
+export async function completeHookOutput(result,
+  { stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (result.failed || result.timedOut) {
+    // Hook failures can include arbitrary payload or filesystem text. Report
+    // degradation without reflecting those details into the client's output.
+    tryWrite(stderr, "acc: coordination unavailable; hook continued without context\n");
+  }
+  try {
+    await writeOutput(stdout, result.stdout ?? "", { deadlineAt: result.deadlineAt });
+  } catch (error) {
+    tryWrite(stderr, boundedDiagnostic("stdout write failed", error));
+    return { exitCode: 0, wroteStdout: false, committedOffers: false };
+  }
+
+  let committedOffers = true;
+  try {
+    await result.commitOffers?.();
+  } catch (error) {
+    committedOffers = false;
+    tryWrite(stderr, boundedDiagnostic("offer commit failed", error));
+  }
+  if (result.stderr) tryWrite(stderr, `${result.stderr}\n`);
+  return { exitCode: 0, wroteStdout: true, committedOffers };
+}

package/docs/ADAPTER_AUTHORING.md

@@ -28,6 +28,7 @@ export function createExampleAdapter() {
 
     detect, install, uninstall, doctor,
     planInstall,                      // what install would write
+    preflightUninstall,               // optional read-only removal validation
     normalizeHook,                    // client payload -> normalised event
     renderContext,                    // SyncResult -> text
     renderContextResult,              // text + ids of complete rendered groups
@@ -36,6 +37,11 @@ export function createExampleAdapter() {
 }
 ```
 
+`preflightUninstall(context)` is optional and read-only. Throw to refuse unsafe
+removal before the installer deactivates native integration or deletes recorded
+artifacts. `uninstall` should retain its own validation for direct adapter callers;
+recorded artifact fingerprint checks still determine the `keep` paths it receives.
+
 `renderContextResult` is required wherever an adapter renders peer messages. It returns
 `{ text, offeredMessageIds, includedAttentionIds }`, and the [receipt
 lifecycle](PROTOCOL.md#receipt-lifecycle) advances only from those ids — never by searching
@@ -46,6 +52,12 @@ convenience API for adapters that don't need it. An adapter with only the older
 instead: repeating an untracked body every turn would be quieter in code and dishonest about
 what was actually delivered.
 
+The hook also supplies `reminderMessageIds`, derived from this participant's `offered` or
+`retrieved` receipts with unresolved obligations. The standard projector combines those
+reply/acknowledgement attention items into counts after new bodies. A missing body alone
+is not evidence for compaction. Counts add no ids to `offeredMessageIds` or
+`includedAttentionIds`; complete inbox and status results remain available.
+
 `client.command` does double duty. `detect.mjs` uses it as the version-probe binary, and
 presence liveness separately walks the hook's process ancestry for the first ancestor whose
 executable basename matches it, to learn the client's own pid. Declare the binary the client
@@ -119,9 +131,30 @@ The rules `defineAdapter` enforces, and the ones the runtime applies:
   when numerically newer. `knownBad` names exact versions or inclusive intervals.
 - Exact-version certification still governs every non-native capability;
   `effectiveCapabilities()` is unchanged. The native rule is used for live delivery alone.
-- The three native methods return closed facts (`validateNativeActivationPlan()` closes the
+- Native methods return closed facts (`validateNativeActivationPlan()` closes the
   activation plan) and never put vendor data - endpoints, sockets, raw errors - into core.
 
+`nativeDelivery.policySource` defaults to the session environment. An adapter may
+declare `"installation-record"` when hooks and senders must read current recorded
+recipient consent independently of the vendor process environment. Installation
+records the requested policy even when current activation is unavailable. An absent
+or invalid record means `off`; a previously published binding cannot override it.
+
+The optional `refreshNativeSession()` method may revalidate an expired lease before
+an offer. It returns the same closed handshake shape as `bindNativeSession()` and
+must preserve the exact endpoint and protocol identity. The router rechecks the
+current session, generation, retirement, uniqueness and policy before publishing
+the refreshed lease. Refresh is not a heartbeat and cannot extend presence beyond
+its own expiry. Optional `retireNativeSession()` cleans adapter-owned endpoint state
+after confirmed core retirement; it must remain bounded and fail open for hooks.
+
+A package-shipped passing Codex installed-hook capture additionally references its
+complete real product matrix through the selected provenance record's
+`productEvidence: { fixture, sha256 }`. Package verification checks the actual file,
+raw digest and client/version/platform/package identity. A transport-only capture
+cannot certify the installed product route. `historicalFixtures` may retain hashed
+earlier failures without duplicating a certification tuple.
+
 ## Choose the integration depth
 
 | Tier | You register | You get | You do not get |
@@ -131,12 +164,13 @@ The rules `defineAdapter` enforces, and the ones the runtime applies:
 | 2 | hooks + skill | only the lifecycle, context, guard, and next-turn behaviors separately captured for this client | uncaptured hook behaviors |
 | 3 | + native delivery surface | only captured live-push and reply-route modes | safe-point injection or child sessions unless separately captured |
 
-Installed hook wiring may reach tier 2, but the effective capability is still limited to
-an exact certified client/version/platform. Tier 3 ships for one client: Claude Code, from
-2.1.258 on macOS arm64, behind the native delivery contract above. Codex reached a passing
-queue capture and was withdrawn anyway - the mode its transport needs reports the daemon's
-workspace as the session's - which is the standard: a capture that works is not the same
-claim as a capability that is safe to ship.
+Installed hook wiring may reach tier 2, but each effective hook capability still
+requires exact client/version/platform evidence. Tier 3 has separate native
+contracts: Claude Code Channel from 2.1.258 and Codex LocalDaemon from 0.152.1 on
+macOS arm64, with current probes and exact session handshakes. Codex's earlier
+remote-wrapper failure remains historical evidence. Ordinary launch now preserves
+workspace identity; the full installed product matrix, including negative controls
+and fallback, backs its native claim.
 
 ## Normalize hook input
 

package/docs/ARCHITECTURE.md

@@ -81,12 +81,12 @@ a third exact-version certification check. A binding says what that current gene
 exposes and whether its lease is current, while recipient policy says whether it may spend a
 turn.
 
-Claude Code is the one client that proved the live seam: a Channel capture on 2.1.258,
-confirmed on 2.1.260 through the installed package, admitted by minimum-plus-probe rather
-than an exact version. Codex's queue transport passed its capture and the capability was
-withdrawn, because the mode it needs hides the session's workspace. Gemini CLI and Kimi
-Code have exact-version next-turn evidence only; Grok and generic MCP use inbox polling.
-The seam exists for every adapter; only one has earned it.
+Claude Code Channel has installed-client evidence on 2.1.258 and 2.1.260; Codex
+LocalDaemon has it on 0.152.1 and 0.153.4. Both use a captured platform minimum,
+current probe and exact session handshake. Codex preserves the ordinary client
+launch and verifies its registered thread and workspace; ACC owns no vendor daemon
+lifecycle. Gemini CLI and Kimi Code have exact-version next-turn evidence only;
+Grok and generic MCP use inbox polling.
 
 ## Storage and workspace identity
 
@@ -101,17 +101,29 @@ file ACC writes is an optional `acc.workspace.json` explicitly requested through
 `acc config init`.
 
 A lone session can remain ephemeral. Durable state materialises when a second live session
-appears or the first claim, message, or handoff is committed. This makes “silent when
-alone” an architectural behavior, not a UI preference.
+appears or the first claim, message, or handoff is committed. Solo presence therefore
+does not require durable workspace history. Native turn hooks still supply the session's
+own CLI arguments, so a peer joining later in the same turn does not require reattachment.
+Without relevant coordination context, that identity header is the only projected content.
 
 ## Inbox, attention, and projection
 
-Inbox reads only messages addressed to the calling participant and advances that
-participant's receipt to `retrieved`. Reply validates ownership, creates an `answer` in the
+Public inbox discovery uses core `listInbox`: bounded, read-only message summaries
+addressed to the current participant. Exact body reads use `readInbox` and advance only
+that participant's receipt to `retrieved`; the embedded core API still supports bulk
+retrieval. History sync reads message records without receipt changes, using the same
+summary pager or one exact id. Reply validates ownership, creates an `answer` in the
 same thread, and acknowledges the original atomically. No participant can advance another
 participant's receipt.
 
-Attention is computed from six explicit rules:
+Decision lifecycle is derived from immutable message links, without a new record kind
+or mutable decision store. Read copies carry bounded status; raw forensic snapshots stay
+unchanged. Non-head decisions leave pending inbox, bulk delivery, and attention while
+exact reads retain them. Replacement/withdrawal records inherit recipients before commit,
+so offline readers receive the change without a forged acknowledgement. See
+[the protocol contract](PROTOCOL.md#decision-lifecycle).
+
+Attention is computed from six explicit rules for current obligations:
 
 | Priority | Kind | Observable trigger |
 |---|---|---|
@@ -129,6 +141,14 @@ Adapters project peer bodies in an attributed untrusted frame. If a complete bod
 fit, the projection keeps the message id and points to `acc inbox --message <id>` instead
 of silently truncating it.
 
+For this participant's unresolved messages already `offered` or `retrieved`, the standard
+projector combines reply and acknowledgement reminders into a compact count after new
+message bodies. Queued obligations and claim conflicts remain individual attention items.
+All pending headers stay discoverable through `acc inbox` pages; owned `acc status` retains
+its complete attention list. Full bodies require an exact inbox read; projection
+does not acknowledge or delete records. Explicit decision links, rather than the
+projector or message age, retire old decision obligations.
+
 ## Hooks fail open
 
 Hook execution is bounded. If coordination state cannot be read or a decision cannot be
@@ -137,3 +157,34 @@ it, but a coordination tool must not be the reason a session stops working.
 
 Next: [Protocol](PROTOCOL.md) · [Capabilities](CAPABILITIES.md) ·
 [Security model](SECURITY_MODEL.md)
+
+## Managed runtime activation
+
+The CLI owns installation generations under `<dataHome>/acc/runtime`, outside workspaces.
+All five launch paths select a generation and publish an actual-process lease under one
+admission mutex before loading workspace-capable code. Immutable launcher modules and
+runtime directories preserve in-progress imports. Leases survive `main()` returning and
+are removed only after confirmed process death. Parsed help, version, and update recovery
+remain available when workspace admission is unavailable.
+
+An independent worker downloads npm packages with lifecycle scripts disabled, checks exact
+stable package identity and the discovered integrity, and health-checks the staged runtime.
+Installer detection and planning happen before exclusive admission. The worker then checks
+ACC process leases and native binding PIDs, records `activating`, applies every integration,
+and only publishes the new active pointer after all applications succeed. Partial refresh
+remains fenced and repairs forward, with the old active pointer retained but normal
+workspace admission unavailable until recovery completes. Native bindings cease holding
+after observed SessionEnd cleanup or confirmed process death; the vendor daemon may remain
+running. Unknown PIDs remain holds until lifecycle cleanup. Presence TTL, `acc finish`,
+and delivery off alone do not prove native lifecycle end. ACC never manages the daemon.
+
+Lock ownership never expires by age. Retained nonempty tombstones prevent delayed observers
+from reclaiming a successor. Under an acquired lock, maintenance removes historical
+bookkeeping only when no live or unknown contender could still reference it; a stopped
+contender postpones cleanup. Admission also removes confirmed-dead process leases. None of
+this metadata is agent conversation history or injected context.
+
+The first upgrade from an unmanaged binary still requires a restart. ACC cannot fence old
+direct binaries or external applications importing core. Native trust and client-side cache
+activation remain vendor responsibilities; refreshed files do not establish observed
+capabilities.