agents-can-communicate 0.4.3 → 0.4.4

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.4.4 update and the data-format boundary when moving from 0.3.1.
 
 ## When messages arrive
 
@@ -142,8 +142,10 @@ One npm package. ACC needs no separate account, model API key, or hosted service
 
 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.
+runtime and refreshing integrations. 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/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
@@ -184,7 +186,12 @@ remains fenced and repairs forward, with the old active pointer retained but nor
 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.
@@ -281,8 +281,13 @@ holds. `finish`, presence TTL, and delivery off are not observed native end. Hoo
 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 blocks activation
+or runs an older version than the installed CLI, it asks once to restart that service.
+After confirmation, a detached worker waits for idle work and other ACC processes, 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 +295,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.4.4
 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/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.4.4`;
 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
 
@@ -122,8 +123,14 @@ author as a software-supply trust boundary; they do not establish that package c
 
 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 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

@@ -240,8 +240,11 @@ Run `acc doctor` to see the update policy and pending notice. ACC process leases
 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.
+ACC processes; `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.4.4
 
-## From 0.4.2, 0.4.1 or 0.4.0
+## From 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.
+This patch keeps the existing workspace data format. It adds confirmed service maintenance
+to the updater, preserves native delivery setup when readiness probes are unavailable,
+and names the actual processes blocking activation. It includes the previous 0.4.x
+outgoing sandbox permissions, delivery diagnostics, session recovery and integration fixes.
 
-Close participating clients and persistent ACC MCP processes, then run:
+Run the update command; it can offer a confirmed restart for an eligible Codex service.
+Other active clients and persistent ACC MCP processes still need to finish before activation:
 
 ```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.4.4. If a pin keeps an older version,
+select 0.4.4 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,52 @@ 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.
 
+## Confirmed client service maintenance
+
+On macOS arm64, `acc update` can ask once to restart a verified Codex service that blocks
+activation or runs a different version from the installed CLI. 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 and other ACC processes to exit. 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.4.4`, 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 +104,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.4.4
    acc version
    acc install
    ```
@@ -104,7 +144,8 @@ confirmed process exit. Native bindings hold until observed client SessionEnd cl
 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.
+persistent ACC processes to release holds, 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 +155,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.4.4        # stay on this exact stable version
 acc update --pin none         # follow stable releases again
 ```
 

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.4.4",
   "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.4.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-codex/src/adapter.mjs

@@ -2,6 +2,8 @@ import { defineAdapter, projectContext, projectContextResult }
   from "@agents-can-communicate/adapter-sdk";
 import { probeNativeDelivery, planNativeActivation, bindNativeSession, refreshNativeSession, retireNativeSession, offerMessage } from "./native-delivery.mjs";
 import certification from "../certification.json" with { type: "json" };
+import { createCodexMaintenance } from "./maintenance.mjs";
+export { sameMaintenanceIdentity } from "./maintenance.mjs";
 
 import { PROTOCOL_CONTRACT } from "./app-server-client.mjs";
 import { allowOutcome, denyOutcome, injectOutcome, normalizeCodexHook }
@@ -16,8 +18,9 @@ export const CODEX_DELIVERY_FALLBACK = Object.freeze({
   diagnostic: "Codex native delivery requires codex-cli 0.152.1 or newer on darwin-arm64, "
     + "recorded recipient consent and a reachable LocalDaemon session with exact thread, cwd, "
     + "process, version and protocol verification. Embedded or unreachable sessions retain "
-    + "durable messages. ACC does not start, restart or stop the vendor daemon and adds no "
-    + "launch arguments; fallback is exact-certified next-turn delivery or acc inbox",
+    + "durable messages. Native delivery does not start, restart or stop the vendor daemon and adds no "
+    + "launch arguments; fallback is exact-certified next-turn delivery or acc inbox. "
+    + "Explicitly confirmed acc update maintenance has a separate daemon restart check",
 });
 
 /**
@@ -61,6 +64,7 @@ export function createCodexAdapter() {
     },
     probeNativeDelivery, planNativeActivation, bindNativeSession,
     refreshNativeSession, retireNativeSession, offerMessage,
+    ...createCodexMaintenance(),
     startSession: async () => ({ ok: true, changes: [], diagnostics: [] }),
     endSession: async () => ({ ok: true, changes: [], diagnostics: [] }),
     guardWrite: async () => ({ ok: true, changes: [], diagnostics: [] }),

package/node_modules/@agents-can-communicate/adapter-codex/src/maintenance-host.mjs

@@ -0,0 +1,120 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access, lstat, open, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { compareStableVersions, parseStableVersion } from "./app-server-client.mjs";
+
+export const MINIMUM_MAINTENANCE_CLI = "0.154.0";
+export const absolute = value => typeof value === "string" && path.isAbsolute(value)
+  && !/[\0\r\n]/.test(value);
+export const failMaintenance = reasonCode => { throw Object.assign(new Error(reasonCode), { reasonCode }); };
+const own = info => typeof process.getuid !== "function" || info.uid === process.getuid();
+export const startTimeValid = value => typeof value === "string"
+  && /^[A-Z][a-z]{2} [A-Z][a-z]{2} [ \d]\d \d\d:\d\d:\d\d \d{4}$/.test(value);
+export const managedExecutablePaths = codexHome => ["bin/codex", "codex"].map(name =>
+  path.join(codexHome, "packages/standalone/current", name));
+
+export function runMaintenanceCommand(command, args, options) {
+  return new Promise(resolve => execFile(command, args,
+    { ...options, timeout: 20_000, maxBuffer: 131_072, windowsHide: true },
+    (error, stdout, stderr) => resolve({ status: error ?
+      (typeof error.code === "number" ? error.code : null) : 0, stdout, stderr })));
+}
+
+export async function maintenanceContext(context = {}) {
+  const env = context.env ?? process.env;
+  const home = context.home ?? env.HOME ?? os.homedir();
+  let codexHome = env.CODEX_HOME ?? path.join(home, ".codex");
+  if (!absolute(home) || !absolute(codexHome)) failMaintenance("invalid_service_home");
+  try { codexHome = await realpath(codexHome); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  const [binPath, legacyPath] = managedExecutablePaths(codexHome);
+  const managedPath = await metadataExists(binPath) ? binPath : legacyPath;
+  return { codexHome, socketPath: path.join(codexHome, "app-server-control/app-server-control.sock"),
+    pidPath: path.join(codexHome, "app-server-daemon/app-server.pid"),
+    managedPath,
+    platform: context.platform ?? `${process.platform}-${process.arch}`,
+    options: { cwd: codexHome, env: { ...env, HOME: home, CODEX_HOME: codexHome } } };
+}
+
+export async function metadataExists(file) {
+  try { await lstat(file); return true; }
+  catch (error) { if (error.code === "ENOENT") return false; throw error; }
+}
+
+async function resolveCli(pathEnv) {
+  for (const directory of String(pathEnv ?? "").split(path.delimiter)) {
+    if (!absolute(directory)) continue;
+    const candidate = path.join(directory, "codex");
+    try {
+      await access(candidate, constants.X_OK);
+      const resolved = await realpath(candidate);
+      if ((await lstat(resolved)).isFile()) return resolved;
+    } catch { /* another PATH entry may be usable */ }
+  }
+  failMaintenance("maintenance_cli_unavailable");
+}
+
+const cliVersion = response => response.status === 0
+  ? /^codex-cli (\d+\.\d+\.\d+)\s*$/.exec(response.stdout)?.[1] ?? null : null;
+
+export async function probeMaintenanceInstall(paths, run) {
+  const cliPath = await resolveCli(paths.options.env.PATH);
+  const version = cliVersion(await run(cliPath, ["--version"], paths.options));
+  if (!parseStableVersion(version) || compareStableVersions(version, MINIMUM_MAINTENANCE_CLI) < 0) {
+    failMaintenance("maintenance_cli_unsupported");
+  }
+  const help = await run(cliPath, ["app-server", "daemon", "--help"], paths.options);
+  if (help.status !== 0 || ["start", "stop", "version"].some(command =>
+    !new RegExp(`^\\s+${command}\\s+`, "m").test(help.stdout))) failMaintenance("maintenance_cli_unsupported");
+  const managedVersion = cliVersion(await run(paths.managedPath, ["--version"], paths.options));
+  if (managedVersion !== version) failMaintenance("managed_binary_mismatch");
+  return { cliPath, cliVersion: version, managedVersion };
+}
+
+export async function readMaintenancePid(file) {
+  let handle;
+  try {
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = await handle.stat();
+    if (!info.isFile() || !own(info) || info.size > 4_096 || (info.mode & 0o022) !== 0) {
+      failMaintenance("daemon_identity_unavailable");
+    }
+    const value = JSON.parse(await handle.readFile("utf8"));
+    if (!Number.isSafeInteger(value.pid) || value.pid < 2 || !startTimeValid(value.processStartTime)) {
+      failMaintenance("daemon_identity_unavailable");
+    }
+    return { pid: value.pid, processStartTime: value.processStartTime };
+  } finally { await handle?.close(); }
+}
+
+export async function observeMaintenanceProcess(pid, paths, run) {
+  const response = await run("/bin/ps", ["-p", String(pid), "-o", "lstart=,command="], paths.options);
+  if (response.status === 1 && response.stdout === "" && response.stderr === "") return { state: "dead" };
+  if (response.status !== 0) return { state: "unknown" };
+  const match = /^(.{24})\s+(.+)$/.exec(response.stdout.trim());
+  if (!match || !startTimeValid(match[1])) return { state: "unknown" };
+  return { state: "alive", processStartTime: match[1], command: match[2] };
+}
+
+export async function verifyMaintenanceProcess(snapshot, paths, run) {
+  const process = await observeMaintenanceProcess(snapshot.pid, paths, run);
+  const suffix = " app-server --listen unix://";
+  const executable = process.command?.endsWith(suffix) ? process.command.slice(0, -suffix.length) : null;
+  if (process.state !== "alive" || process.processStartTime !== snapshot.processStartTime
+    || !managedExecutablePaths(paths.codexHome).includes(executable)
+    || await realpath(executable) !== await realpath(paths.managedPath)) {
+    failMaintenance("daemon_identity_unavailable");
+  }
+  const sockets = await run("/usr/sbin/lsof", ["-n", "-a", "-p", String(snapshot.pid), "-U", "-Fn"], paths.options);
+  if (sockets.status !== 0 || !sockets.stdout.split("\n").includes(`n${paths.socketPath}`)) {
+    failMaintenance("daemon_socket_unproven");
+  }
+}
+
+export async function approvedProcessIsDead(expected, paths, run) {
+  const observed = await observeMaintenanceProcess(expected.pid, paths, run);
+  return observed.state === "dead" || (observed.state === "alive"
+    && observed.processStartTime !== expected.processStartTime);
+}

package/node_modules/@agents-can-communicate/adapter-codex/src/maintenance-threads.mjs

@@ -0,0 +1,49 @@
+import { initializeCodex } from "./app-server-client.mjs";
+import { failMaintenance } from "./maintenance-host.mjs";
+
+async function loadedThreads(peer) {
+  const ids = [], cursors = new Set();
+  let cursor = null;
+  for (let page = 0; page < 20; page += 1) {
+    const response = await peer.request("thread/loaded/list", { limit: 100, ...(cursor ? { cursor } : {}) });
+    if (!Array.isArray(response?.data) || response.data.some(id => typeof id !== "string" || !id)) {
+      failMaintenance("maintenance_protocol_unavailable");
+    }
+    ids.push(...response.data);
+    cursor = response.nextCursor ?? null;
+    if (cursor === null) {
+      if (new Set(ids).size !== ids.length) failMaintenance("maintenance_protocol_unavailable");
+      return ids.sort();
+    }
+    if (typeof cursor !== "string" || !cursor || cursors.has(cursor)) failMaintenance("maintenance_protocol_unavailable");
+    cursors.add(cursor);
+  }
+  failMaintenance("maintenance_protocol_unavailable");
+}
+
+// The caller receives counts only. No thread/list previews, turns, queue bodies,
+// notification history, or vendor errors are retained in maintenance snapshots.
+export async function maintenanceWorkload(snapshot, open) {
+  let peer;
+  try {
+    peer = await open({ socketPath: snapshot.socketPath });
+    if (await initializeCodex(peer) !== snapshot.serverVersion) failMaintenance("daemon_version_changed");
+    const ids = await loadedThreads(peer);
+    let busyThreads = 0, queuedRequests = 0;
+    for (const threadId of ids) {
+      const response = await peer.request("thread/read", { threadId, includeTurns: false });
+      const thread = response?.thread;
+      if (thread?.id !== threadId || !Array.isArray(thread.turns) || thread.turns.length !== 0
+        || !["idle", "active"].includes(thread.status?.type)) failMaintenance("maintenance_protocol_unavailable");
+      if (thread.status.type === "active") busyThreads += 1;
+      const queue = await peer.request("thread/queue/list", { threadId });
+      if (!Array.isArray(queue?.data) || queue.nextCursor != null
+        || queue.data.some(entry => typeof entry?.id !== "string" || !entry.id)) {
+        failMaintenance("maintenance_protocol_unavailable");
+      }
+      queuedRequests += queue.data.length;
+    }
+    if (JSON.stringify(await loadedThreads(peer)) !== JSON.stringify(ids)) failMaintenance("loaded_threads_changed");
+    return { busyThreads, queuedRequests };
+  } finally { await peer?.close(); }
+}