agents-can-communicate 0.4.3 → 0.5.0

package/README.md

@@ -80,7 +80,7 @@ state, commonly your home directory, cannot be used as a workspace; start the cl
 project directory. See [Troubleshooting](docs/TROUBLESHOOTING.md).
 
 Already using ACC? Follow the [upgrade guide](docs/UPGRADING.md), including the 0.4.x →
-0.4.3 update and the data-format boundary when moving from 0.3.1.
+0.5.0 update and the data-format boundary when moving from 0.3.1.
 
 ## When messages arrive
 
@@ -141,9 +141,13 @@ One npm package. ACC needs no separate account, model API key, or hosted service
 ## Update or remove ACC
 
 Initial installation enables automatic updates. ACC downloads stable releases in the
-background and waits for active clients and ACC processes to exit before switching the
-runtime and refreshing integrations. Restart clients afterward and complete any requested
-hook or plugin trust review.
+background, then switches the runtime and refreshes integrations once nothing blocks. A
+live client or ACC process blocks only while the store contract it declares differs from
+the incoming version's or is unknown; one declaring a matching contract keeps running
+through the switch. When a verified Codex service needs a restart,
+`acc update` asks once, then completes maintenance in a separate process. Open clients
+disconnect; `acc doctor` reports progress and the result. See [update and recovery details](docs/UPGRADING.md#confirmed-client-service-maintenance).
+Restart or resume clients afterward and complete any requested hook or plugin trust review.
 
 For an immediate update:
 

package/bin/acc-maintenance-worker.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runMaintenance } from "../node_modules/@agents-can-communicate/cli/src/managed-runtime/maintenance-worker.mjs";
+
+// This private entry has no workspace admission/lease and no inherited stdio.
+// Durable checkpoints remain available to the next acc update after a crash.
+await runMaintenance(process.argv[2], { jobId: process.argv[3] }).catch(() => { process.exitCode = 1; });

package/bin/entrypoints/acc-hook.mjs

@@ -6,9 +6,11 @@
 // 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 { pathToFileURL } from "node:url";
 
 import { createId } from "@agents-can-communicate/protocol";
 import { runHook } from "@agents-can-communicate/hook-runner";
+import { hookEntrypointFor, resolvePinnedGeneration } from "@agents-can-communicate/cli";
 
 import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
 import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
@@ -38,15 +40,66 @@ const readStdin = () => new Promise(resolve => {
 
 import { completeHookOutput } from "./hook-output.mjs";
 
-export async function main() {
-  const [adapterId] = process.argv.slice(2);
+// A pin is keyed by harness session id, which only an adapter's own
+// normalisation can find inside a payload. This runs the same normalisation
+// `runHook` will run a moment later - cheap, in-memory, no store touched - so
+// a hook that has no pin to look up pays nothing beyond it. Any adapter or
+// payload that will not yield a session id simply has no pin to find, same as
+// today's no-pin behaviour.
+async function harnessSessionIdFor(adapterId, payload) {
+  try {
+    const event = await adapters[adapterId]?.normalizeHook(payload);
+    return typeof event?.sessionId === "string" ? event.sessionId : null;
+  } catch {
+    return null;
+  }
+}
 
-  let payload = null;
+// A pinned generation is only ever another build of this same codebase, but
+// it can still be broken on disk - deleted mid-write, a corrupt install. This
+// tries it and reports failure rather than letting an import error or a
+// throwing `main` escape: the caller then runs the turn on the active
+// generation instead, exactly as if there had been no pin.
+//
+// `delegated` is the circuit breaker on chaining: a hook already running
+// because it was delegated to never looks for a pin of its own. Ordinary
+// resolution already stops itself after one hop - the generation a pin names
+// compares its own pin against the exact root it was just handed, so they
+// match and it returns null - but that self-termination leans on a single
+// pin record staying the value both reads saw. `delegated` does not: it
+// forbids a second hop outright, independent of anything a pin (rewritten
+// mid-resolution by another hook for the same session, or simply wrong)
+// could say. Unbounded delegation would be a hang, worse than any of the
+// failures this file already falls open from.
+async function delegateToPin({ managerRoot, packageRoot, adapterId, payload, delegated }) {
+  if (delegated || managerRoot === null || packageRoot === null) return false;
+  const harnessSessionId = await harnessSessionIdFor(adapterId, payload);
+  if (harnessSessionId === null) return false;
+  const pinned = await resolvePinnedGeneration({ root: managerRoot, harnessSessionId, active: packageRoot });
+  if (pinned === null) return false;
   try {
-    payload = JSON.parse(await readStdin());
+    const runtime = await import(pathToFileURL(hookEntrypointFor(pinned)).href);
+    await runtime.main({ managerRoot, packageRoot: pinned, payload, delegated: true });
+    return true;
   } catch {
-    payload = null;
+    return false;
   }
+}
+
+export async function main({ managerRoot = null, packageRoot = null, payload, delegated = false } = {}) {
+  const [adapterId] = process.argv.slice(2);
+
+  // A delegating caller already read stdin once for the whole process and
+  // hands its parsed payload down; only the outermost call reads it here.
+  if (payload === undefined) {
+    try {
+      payload = JSON.parse(await readStdin());
+    } catch {
+      payload = null;
+    }
+  }
+
+  if (await delegateToPin({ managerRoot, packageRoot, adapterId, payload, delegated })) return;
 
   const result = await runHook({ adapterId, payload, adapters,
     runtime: { clock: { now: () => new Date().toISOString() },

package/docs/ARCHITECTURE.md

@@ -15,8 +15,10 @@ flowchart LR
   T -->|reply or acknowledge| C
 ```
 
-ACC never starts, resumes, interrupts, supervises, or terminates the target client. A
-transport that requires owning that lifecycle is outside the product boundary.
+Message delivery never starts, resumes, interrupts, supervises, or terminates the target
+client. A transport that requires owning that lifecycle is outside the product boundary.
+Separately, explicit update maintenance can restart a verified client service after the
+user confirms the disconnection; it does not launch or assign agent tasks.
 
 ## Packages and dependency direction
 
@@ -90,8 +92,8 @@ turn.
 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;
+launch and verifies its registered thread and workspace; native delivery 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
@@ -172,19 +174,29 @@ The CLI owns installation generations under `<dataHome>/acc/runtime`, outside wo
 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.
+are removed only after confirmed process death. A session is also pinned to the generation
+it started with: its hooks delegate to that generation while the pin declares the same
+store contract this one does, and run the active generation otherwise. A generation
+directory is reclaimed once no control pointer, live lease, live pin or staging hold names
+it. 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
+ACC process leases and native binding PIDs and waits only for those whose declared store
+contract differs from the incoming generation's or is absent, 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.
+and delivery off alone do not prove native lifecycle end. Normal background updates never
+restart a vendor daemon. An explicitly approved maintenance job can do so through the
+adapter lifecycle port: it waits for idle work, validates exact process identity, stops
+the service under the admission fence, refreshes integrations, and restores and verifies
+the service even after a refresh failure. Checkpoints and the detached worker live outside
+repositories. Approved crash recovery never blindly repeats a stop.
 
 Lock ownership never expires by age. Retained nonempty tombstones prevent delayed observers
 from reclaiming a successor. Under an acquired lock, maintenance removes historical

package/docs/CLI.md

@@ -232,7 +232,7 @@ external AI client. An addressed handoff requires acknowledgement; a room handof
 | `acc doctor` | `--home`, `--repair` |
 | `acc config init` | `--yes`, `--force` |
 | `acc config validate` | — |
-| `acc update` | `--check`, `--auto on\|off`, `--pin VERSION\|none`, `--apply` (alias) |
+| `acc update` | `--check`, `--auto on\|off`, `--pin VERSION\|none`, `--yes`, `--apply` (alias) |
 | `acc help` | — |
 | `acc version` | — |
 
@@ -248,8 +248,8 @@ effective policy off and prints the reason. Claude Code shell activation writes
 zsh PATH block and a shim that `exec`s the real client; `ACC_BYPASS=1` bypasses that
 activation. Codex LocalDaemon delivery uses recorded installation consent without changing
 ordinary launch arguments. Its opt-in remains active when shim variables are absent or
-bypassed; `acc install --adapter codex --delivery off` disables new native offers. ACC never
-starts or stops the vendor daemon. The install summary names each client's requested policy,
+bypassed; `acc install --adapter codex --delivery off` disables new native offers. Installation
+and message delivery do not start or stop the vendor daemon. The install summary names each client's requested policy,
 activation state and verified fallback. `doctor` separates protocol readiness, recorded
 consent and a live channel in the current workspace, with a next step for missing activation.
 A supported version or an installed plugin alone is not an active delivery channel.
@@ -274,15 +274,24 @@ An initial `acc install` enables automatic updates. Reinstalling preserves an ex
 `acc update --auto off` choice. A full uninstall pauses updates; reinstalling restores
 the remembered setting. A background worker checks stable releases
 at most once a day, downloads and verifies a separate runtime, then refreshes installed
-integrations and skills after ACC process leases and native binding holds clear. ACC leases
-require confirmed process exit; a native binding can clear on observed SessionEnd even
-while its vendor daemon remains alive, or on confirmed process death. Unknown PIDs remain
-holds. `finish`, presence TTL, and delivery off are not observed native end. Hooks do not
+integrations and skills once no hold blocks. A runtime lease or native binding blocks only
+while the store contract it declares differs from the incoming version's, or while it
+declares none; records written before 0.5.0 declare none, so the first update after
+upgrading still waits for them. ACC leases end on confirmed process exit; a native binding
+can clear on observed SessionEnd even while its vendor daemon remains alive, or on
+confirmed process death. Unknown PIDs remain holds. `finish`, presence TTL, and delivery off are not observed native end. Hooks do not
 wait for network work. `ACC_NO_UPDATE_CHECK=1` disables update networking and background
 scheduling.
 
-`acc update` requests the update immediately; it reports a pending update when a running or
-unidentified client prevents activation. `--check` only checks and cannot be combined with
+`acc update` requests the update immediately. If a verified Codex service holds a native
+binding that blocks activation, or serves a version its captured native-delivery contract
+refuses, it asks once to restart that service.
+After confirmation, a detached worker waits for idle work and for any ACC process whose
+declared store contract still holds the update, refreshes integrations, restarts the
+service and verifies the result. Open clients disconnect; use
+`acc doctor` for progress and resume the clients afterward. `--yes` supplies explicit
+noninteractive restart consent. Without consent, or with unknown ownership, the update
+remains pending. See [maintenance limits and recovery](UPGRADING.md#confirmed-client-service-maintenance). `--check` only checks and cannot be combined with
 settings changes. `--auto off` disables background updates, and `--auto on` enables them.
 `--pin 0.4.0` holds an exact stable version; `--pin none` follows stable releases. A pin
 cannot downgrade the active runtime. The old `--apply` flag remains accepted.
@@ -290,7 +299,9 @@ cannot downgrade the active runtime. The old `--apply` flag remains accepted.
 Failed downloads keep the working runtime. A failed integration refresh exits with code
 `4`, names the failed adapter and configuration error, and keeps workspace admission closed.
 Fix the reported configuration problem, then run `acc update` to finish it. `acc doctor`
-reports the update policy and pending notice. Native clients may still require hook trust
+reports the update policy and pending notice. During blocked activation, a current launcher
+returns `scope: update` and `workspaceInspection: unavailable_during_update` without opening
+workspace state; `doctor --repair` remains blocked. Native clients may still require hook trust
 or activation review. See [Upgrading](UPGRADING.md) for the initial 0.3.1 transition and
 recovery details.
 

package/docs/CONCEPTS.md

@@ -14,7 +14,8 @@ settings, clients, and checkouts. Neither is automatically in charge. Claude can
 for the endpoint shape; Codex can answer or decline under its own instructions.
 
 This resembles coordination among subagents, but the sessions were opened independently by
-the user. ACC never launches, assigns, supervises, or closes them.
+the user. ACC does not launch, assign or supervise their work. Separately, an explicit
+update can ask to restart a client service; this disconnects clients and requires user consent.
 
 ## Workspace, participant, and session
 

package/docs/CONFIGURATION.md

@@ -139,7 +139,8 @@ reports degraded reachability; it does not rewrite the installed consent.
 
 Codex LocalDaemon delivery separately requires macOS arm64, Codex 0.152.1 or newer, a
 current feature probe, and exact thread, canonical cwd, process, version and protocol
-checks. Its daemon must already be running; ACC never starts or stops it. Codex reads
+checks. Its daemon must already be running; installation and delivery do not start or stop it.
+Explicit update maintenance can restart a verified service after separate confirmation. Codex reads
 consent from the installation record, not a shell-shim variable. Unavailable or ineligible
 sessions retain durable inbox fallback. Use `acc install --adapter codex --delivery off`
 to stop new native offers; bypassing a shim does not disable that recorded opt-in.

package/docs/GETTING_STARTED.md

@@ -15,7 +15,7 @@ pair or session-bound ACC MCP tools. See [CLI ownership](CLI.md#coordinate-from-
 
 ACC requires macOS or Linux and Node.js 24 or newer.
 
-Already using ACC? Follow the [upgrade guide](UPGRADING.md) for the 0.4.x → 0.4.3
+Already using ACC? Follow the [upgrade guide](UPGRADING.md) for the 0.4.x → 0.5.0
 update or the data-format boundary when upgrading from 0.3.1.
 
 ```bash
@@ -30,7 +30,9 @@ acc install
 Initial installation also enables automatic updates; reinstalling keeps an explicit opt-out.
 ACC downloads releases in the background and
 refreshes its runtime and skills when active clients have left. Use `acc update` for an
-immediate update, or `acc update --auto off` to disable background updates. See
+immediate update; an eligible Codex service restart asks for one confirmation. ACC then
+handles maintenance and reports progress in `acc doctor`; clients disconnect and can be
+resumed afterward. Use `acc update --auto off` to disable background updates. See
 [update controls](UPGRADING.md#automatic-updates-after-installation).
 
 The installer connects only the supported clients it finds. Open a new terminal and

package/docs/HOW_IT_WORKS.md

@@ -112,7 +112,8 @@ All recipients have the same durable record, but adapters expose different accel
   to an independently opened thread. It is experimental, off by default, and can
   spend tokens. Messages wait for a running turn to finish; a daemon-retained
   thread can receive them after its terminal exits. ACC adds no launch arguments
-  and does not manage the vendor daemon.
+  and does not manage the vendor daemon during message delivery. Separately,
+  [confirmed update maintenance](UPGRADING.md#confirmed-client-service-maintenance) can restart it.
 
 Grok, generic MCP, unsupported versions and uncaptured platforms use inbox polling.
 [Capabilities](CAPABILITIES.md) lists evidence and fallback.

package/docs/PROTOCOL.md

@@ -238,6 +238,13 @@ sessionId · generation · adapterId · clientVersion · availableModes
 livePolicy · opaqueEndpointRef · leaseUntil
 ```
 
+`clientVersion` is the version that answered the handshake and was admitted by the
+adapter's captured contract — the process that will serve this binding's live pushes,
+which is not always the version the client's own executable reports. A background
+service that updated under its CLI serves the updated build, and the binding names that
+build. The version the executable reported is recorded separately, beside the session's
+owner record.
+
 The recipient owns `livePolicy` because native push may start a model turn:
 
 - `off`: inbox and normal next-turn paths only;

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.4.3`;
+its evidence tied to the commit that supplied its bytes. The package is currently `0.5.0`;
 the commands derive the version from `package.json` so the filename cannot drift.
 
 ```mermaid

package/docs/SECURITY_MODEL.md

@@ -24,9 +24,10 @@ graph LR
   H["human authority"] --> C
 ```
 
-ACC does not read raw transcripts, relay permission approvals, or start target clients. A
-native delivery path may only offer an attributed peer envelope to an already-running,
-user-owned session.
+ACC does not read raw transcripts or relay permission approvals. A native delivery path
+may only offer an attributed peer envelope to an already-running, user-owned session.
+Confirmed update maintenance is a separate service restart operation; a peer message or
+live-delivery opt-in does not authorize it.
 
 ## Peer-content boundary
 
@@ -120,10 +121,18 @@ sha512 integrity against registry metadata, installs with lifecycle scripts disa
 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.
+ACC process leases and native bindings record the store contract they speak, and hold
+activation while that contract differs from the incoming version's or is absent. A lease
+ends on confirmed exit, a native binding on observed SessionEnd cleanup or confirmed process
+death; unknown PIDs and undeclared contracts remain conservative holds.
+`acc finish`, presence TTL, and delivery off do not establish native lifecycle end.
+Normal installation and message delivery do not manage vendor services. Explicit
+`acc update` maintenance requires one separate confirmation (or `--yes`) for the recorded
+candidate and verified service identity. The detached worker retains that approval for
+recovery, rechecks PID/start time, executable, socket, versions and idle state, and preserves
+unrelated or unidentified process holds. The vendor exposes no atomic turn-drain operation:
+a turn arriving between the final check and stop can be interrupted. See
+[confirmed maintenance](UPGRADING.md#confirmed-client-service-maintenance).
 
 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

package/docs/TROUBLESHOOTING.md

@@ -236,12 +236,19 @@ Next: [Getting started](GETTING_STARTED.md) · [Capabilities](CAPABILITIES.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.
+Run `acc doctor` to see the update policy and pending notice. A hold keeps an update
+pending only while the store contract it declares differs from the incoming version's or
+is unknown; records written before 0.5.0 declare none, so the first update after upgrading
+still waits for all of them. `acc update` names each remaining hold with its process and
+its declared contract. ACC process leases, including persistent MCP servers, end on
+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 client sessions and ACC processes the notice names;
+`finish`, presence TTL, and delivery off do not prove native end.
+`acc update` can offer a confirmed restart of an eligible Codex service. Unknown or
+unrelated holds still require lifecycle cleanup or confirmed process exit; safety holds
+do not expire merely by elapsed time. See
+[maintenance and recovery](UPGRADING.md#confirmed-client-service-maintenance).
 
 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

package/docs/UPGRADING.md

@@ -1,13 +1,14 @@
-# Upgrading to 0.4.3
+# Upgrading to 0.5.0
 
-## From 0.4.2, 0.4.1 or 0.4.0
+## From 0.4.4, 0.4.3, 0.4.2, 0.4.1 or 0.4.0
 
-This patch keeps the existing workspace data format. It fixes outgoing native delivery
-from Codex's sandbox, separates permission failures from unavailable recipients, and
-shows outgoing setup alongside receiving-channel state in doctor. It also includes the
-previous 0.4.x delivery diagnostics, session recovery and client integration fixes.
-
-Close participating clients and persistent ACC MCP processes, then run:
+This release keeps the existing workspace data format. It changes when an update is
+allowed to take effect: activation is gated on the store contract a running process
+declares rather than on which version it happens to be, sessions finish on the generation
+they started with, unreferenced generation directories are reclaimed, and `acc uninstall`
+retires the holds its own install published. It carries the previous 0.4.x confirmed
+service maintenance, outgoing sandbox permissions, delivery diagnostics, session recovery
+and integration fixes.
 
 ```bash
 acc update
@@ -15,8 +16,8 @@ acc version
 acc doctor
 ```
 
-After publication, `acc version` should report 0.4.3. If a pin keeps an older version,
-select 0.4.3 or clear it first. A managed update refreshes installed integrations and
+After publication, `acc version` should report 0.5.0. If a pin keeps an older version,
+select 0.5.0 or clear it first. A managed update refreshes installed integrations and
 skills; use the npm instructions below for unmanaged or pre-0.4 installations. Start
 clients again and complete any hook/trust review they request. With existing live consent,
 Codex 0.153.4 or newer on macOS arm64 receives local socket permissions when its workspace
@@ -36,13 +37,106 @@ Claude admitted inbound Channels messages. See [delivery troubleshooting](TROUBL
 Upgrading preserves delivery consent. If doctor reports native delivery off and you want
 automatic peer requests, use `acc install --adapter codex --delivery actionable` (or the
 relevant adapter); this can spend model tokens. Codex can save that consent before its
-local service/session becomes available. ACC does not start the vendor daemon, and it
+local service/session becomes available. Installation does not start the vendor daemon; ACC
 keeps durable inbox access when no verified live channel is bound.
 
 In Grok, public status supplies the session's own CLI arguments through the next tool
 hook. Grok still uses explicit inbox reads; this patch adds no external wake or guards.
 Start clients in a project directory, rather than a home directory containing ACC state.
 
+## What still waits for a process to exit, and what no longer does
+
+Earlier releases held a verified update until every live ACC process and every native
+client binding was gone. Each of those holds now states the store contract it speaks, and
+only two kinds keep an update pending:
+
+- A hold whose declared store contract differs from the incoming version's. This is the
+  case the gate exists for, and a release that changes the store contract still needs
+  every live process to exit.
+- A hold that declares no contract, which includes every record written by a release
+  before this one. Unknown cannot be compared, so it stays a conservative wait.
+
+A hold declaring the same store contract as the incoming version proceeds. Several open
+Claude Code sessions, a Codex daemon and an idle ACC MCP server no longer have to be
+closed together to move between releases that share a contract.
+
+The first update after installing this release still waits for every process, because the
+holds it has to judge were written before the contract field existed. Close the relevant
+clients and persistent ACC processes once, or accept the eligible Codex service
+maintenance offer described below. Updates after that do not need it.
+
+`acc update` names each remaining hold with its process and its declared contract, so a
+wait now states its reason rather than only the PID. `acc doctor` reports the same
+pending notice.
+
+A session that is open while an activation completes keeps running the generation it
+started with, including its hooks, until it ends; it does not get half of one version and
+half of another. A session whose pin names a generation with a different store contract
+runs the active generation instead, which is the same behaviour as having no pin.
+
+A restart offer for a client's background service is now made only when the version that
+service is actually running fails that client's captured contract, or when it still holds
+a native binding. A Codex CLI that updated while its daemon kept serving the previous
+build is an ordinary state, and it no longer produces a prompt to disconnect open clients.
+
+Generation directories that nothing references are removed after an activation instead of
+accumulating. A directory is kept while any control pointer, live runtime lease, live
+session pin or in-flight staging hold names it, and an unreadable holder postpones the
+whole sweep rather than being assumed dead.
+
+`acc uninstall` retires the binding records and session pins its own install published,
+so they stop holding a later activation, when the removal leaves no client installed. It
+never signals or terminates a client process. Removing one client while another stays
+installed retires nothing, because a binding record names the generation that published
+it and no client id. Runtime leases are left in place on purpose: a lease is also what
+protects the generation a running process is executing from, and clearing it would let
+that directory be reclaimed out from under the process. A live ACC process therefore
+keeps holding activation across an uninstall until it exits.
+
+## Confirmed client service maintenance
+
+On macOS arm64, `acc update` can ask once to restart a verified Codex service that holds a
+native binding blocking activation, or that is serving a version outside the captured
+native-delivery contract. A serving version that satisfies that contract is left alone,
+even when the installed CLI has moved to a newer build. The captured maintenance contract
+uses Codex CLI 0.154.0 and its `pid` backend, with compatible commands and protocol
+checked again at runtime. The installed CLI and managed executable must already match;
+ACC does not replace vendor binaries or install an operating-system service.
+
+After confirmation, a detached ACC worker waits up to 15 minutes for idle Codex turns,
+empty queues, the requesting command to exit, and any other ACC process still holding the
+update. It judges those holds by the same contract rule the activation path uses, so a
+process declaring the incoming version's store contract does not delay the restart, and
+one declaring a differing or unknown contract does. It rechecks the approved candidate, settings,
+PID/start time, executable, socket ownership and versions before stopping the service.
+It refreshes integrations, starts the service again and verifies the result. If refreshing
+integrations fails, it still restores the service and reports the incomplete update.
+A later update worker can resume an already approved recovery without another question.
+`acc doctor --json` exposes `update.maintenance`; ordinary `acc doctor` describes its state.
+A current launcher can use the newer management reader while the old runtime is active.
+When admission is blocked, doctor returns an update-only report without inspecting the
+workspace or repairing it. Older launchers gain this reader after activation, or through
+the one-time launcher bootstrap described below.
+
+Open clients disconnect. Resume them afterward and complete any client-owned hook trust
+review. Codex has no atomic idle-check-and-stop operation: a new turn arriving during the
+final check can be interrupted. ACC does not promise that client UIs reconnect themselves
+or that an interrupted turn continues automatically. Unknown ownership, incompatible
+service layouts and unrelated active processes remain visible blockers.
+
+For an unattended command, `acc update --yes` explicitly consents to the same restart.
+`acc update --check` stays read-only. Background discovery never grants restart consent.
+Changing the candidate or pin before the stop cancels that approval; idle-wait expiration
+also leaves the service untouched. Delivery consent and automatic-update opt-outs survive
+an update even when a native service or feature probe is temporarily unavailable.
+
+An old installation can already be stuck with both a pre-0.4.4 pending runtime and the
+old updater that waits indefinitely. That code cannot discover this fix. Bootstrap the
+new launcher once with `npm install --global agents-can-communicate@0.5.0`, then run
+`acc update`. The new launcher stages its verified runtime and retires only an exactly
+identified obsolete ACC background updater while no integrations are being written.
+This does not terminate an unrelated client or bypass its lifetime hold.
+
 ## From 0.3.1
 
 Upgrade all ACC installations participating in a workspace together, then restart their
@@ -64,7 +158,7 @@ restores access; deleting or editing the record is not a remedy.
 2. Install the released package, then refresh the client integrations:
 
    ```bash
-   npm install --global agents-can-communicate@0.4.3
+   npm install --global agents-can-communicate@0.5.0
    acc version
    acc install
    ```
@@ -99,12 +193,15 @@ an independent background process, normally at most once a day, downloads and ve
 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.
+Running ACC processes, including idle MCP servers, still publish a hold for as long as they
+live, and native bindings still hold until observed client SessionEnd cleanup or confirmed
+process death; the vendor daemon can remain running after that lifecycle event. What
+changed is which of those holds keeps an update pending: only one whose declared store
+contract differs from the incoming version's, or that declares none at all. Unknown PIDs
+remain conservative holds until lifecycle cleanup. `acc finish`, presence TTL, and delivery
+off alone still do not prove native end. When a hold does block, close the relevant client
+sessions and persistent ACC processes to release it, or accept the eligible Codex service
+maintenance offer in `acc update`. Background updates never request fresh restart consent.
 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.
@@ -114,7 +211,7 @@ acc update                    # download and apply, or report what is keeping it
 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.3        # stay on this exact stable version
+acc update --pin 0.5.0        # stay on this exact stable version
 acc update --pin none         # follow stable releases again
 ```
 
@@ -132,9 +229,11 @@ lifecycle scripts. `acc doctor` reports the automatic-update policy and pending
 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.
+and configuration problem to fix before retrying; a verified update waiting for a blocking
+hold remains pending. A previous runtime version is retained for as long as anything can
+still reach it — a control pointer, a live ACC process, or an open session pinned to it —
+so existing launch paths survive the change; once nothing references it, its directory is
+reclaimed after the next activation instead of accumulating.
 
 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

package/docs/WHY_ACC.md

@@ -46,7 +46,7 @@ actionable before two sessions collide.
 ## Choose another layer when
 
 Choose a managed runtime if you want the system to create agents, assign execution state,
-select models, spend token budgets, or control process lifecycle. Choose a tracker when
+select models, spend token budgets, or control ongoing agent execution. Choose a tracker when
 you need organizational planning. Choose a hosted service when participants must
 coordinate across machines.
 

package/node_modules/@agents-can-communicate/adapter-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-claude-code",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-codex",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "private": true,
   "type": "module",
   "exports": {