agents-can-communicate 0.4.3 → 0.4.4

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

@@ -0,0 +1,108 @@
+import path from "node:path";
+import { openCodexAppServer, parseStableVersion } from "./app-server-client.mjs";
+import { socketIsReady } from "./native-endpoint.mjs";
+import { absolute, approvedProcessIsDead, failMaintenance, maintenanceContext,
+  managedExecutablePaths, metadataExists, probeMaintenanceInstall, readMaintenancePid, runMaintenanceCommand,
+  startTimeValid, verifyMaintenanceProcess } from "./maintenance-host.mjs";
+import { maintenanceWorkload } from "./maintenance-threads.mjs";
+
+const identityKeys = ["serviceId", "pid", "processStartTime", "codexHome", "cliPath", "cliVersion",
+  "serverVersion", "managedPath", "managedVersion", "socketPath"];
+const installationKeys = ["codexHome", "cliPath", "cliVersion", "managedPath", "managedVersion", "socketPath"];
+const refused = (reasonCode, snapshot) => ({ ok: false, reasonCode, ...(snapshot ? { snapshot } : {}) });
+const sameFields = (left, right, fields) => fields.every(key => left?.[key] === right?.[key]);
+
+function validApproval(value) {
+  return value?.serviceId === "codex-app-server" && ["ready", "busy"].includes(value.state)
+    && Number.isSafeInteger(value.pid) && value.pid > 1 && startTimeValid(value.processStartTime)
+    && ["codexHome", "cliPath", "managedPath", "socketPath"].every(key => absolute(value[key]))
+    && ["cliVersion", "serverVersion", "managedVersion"].every(key => parseStableVersion(value[key]))
+    && value.managedVersion === value.cliVersion
+    && managedExecutablePaths(value.codexHome).includes(value.managedPath)
+    && value.socketPath === path.join(value.codexHome, "app-server-control/app-server-control.sock");
+}
+
+export function sameMaintenanceIdentity(expected, current) {
+  return validApproval(expected) && validApproval(current) && sameFields(expected, current, identityKeys);
+}
+
+export function createCodexMaintenance({ run = runMaintenanceCommand, open = openCodexAppServer } = {}) {
+  async function inspectMaintenance(context) {
+    let snapshot = { serviceId: "codex-app-server", state: "unsupported", reasonCode: null,
+      pid: null, processStartTime: null, codexHome: null, cliPath: null, cliVersion: null,
+      serverVersion: null, managedPath: null, managedVersion: null, socketPath: null,
+      busyThreads: 0, queuedRequests: 0 };
+    try {
+      const paths = await maintenanceContext(context);
+      Object.assign(snapshot, { codexHome: paths.codexHome, socketPath: paths.socketPath, managedPath: paths.managedPath });
+      if (!await metadataExists(paths.socketPath) && !await metadataExists(paths.pidPath)) return null;
+      if (paths.platform !== "darwin-arm64") failMaintenance("maintenance_platform_unsupported");
+      if (!await socketIsReady(paths.socketPath)) failMaintenance("daemon_socket_unproven");
+      Object.assign(snapshot, await probeMaintenanceInstall(paths, run));
+      const version = await run(snapshot.cliPath, ["app-server", "daemon", "version"], paths.options);
+      if (version.status !== 0) failMaintenance("daemon_version_unavailable");
+      const observed = JSON.parse(version.stdout);
+      if (observed.status !== "running" || observed.backend !== "pid") failMaintenance("maintenance_backend_unsupported");
+      if (observed.managedCodexPath !== snapshot.managedPath || observed.socketPath !== snapshot.socketPath
+        || observed.cliVersion !== snapshot.cliVersion || observed.managedCodexVersion !== snapshot.managedVersion
+        || !parseStableVersion(observed.appServerVersion)) failMaintenance("daemon_identity_unavailable");
+      snapshot.serverVersion = observed.appServerVersion;
+      Object.assign(snapshot, await readMaintenancePid(paths.pidPath));
+      await verifyMaintenanceProcess(snapshot, paths, run);
+      Object.assign(snapshot, await maintenanceWorkload(snapshot, open));
+      const finalPid = await readMaintenancePid(paths.pidPath);
+      if (!sameFields(snapshot, finalPid, ["pid", "processStartTime"])) failMaintenance("service_identity_changed");
+      await verifyMaintenanceProcess(snapshot, paths, run);
+      snapshot.state = snapshot.busyThreads || snapshot.queuedRequests ? "busy" : "ready";
+      snapshot.reasonCode = snapshot.state === "busy" ? "service_busy" : null;
+    } catch (error) { snapshot.reasonCode = error.reasonCode ?? "maintenance_inspection_failed"; }
+    return snapshot;
+  }
+
+  async function stopForMaintenance({ context, expected } = {}) {
+    let stopAttempted = false;
+    const refuseStop = (reasonCode, snapshot) => ({ ...refused(reasonCode, snapshot), stopAttempted });
+    if (!validApproval(expected)) return refuseStop("invalid_maintenance_approval");
+    try {
+      const current = await inspectMaintenance(context);
+      if (!sameMaintenanceIdentity(expected, current)) return refuseStop("service_identity_changed", current);
+      if (current.state !== "ready" || current.busyThreads !== 0 || current.queuedRequests !== 0) {
+        return refuseStop("service_busy", current);
+      }
+      const paths = await maintenanceContext(context);
+      stopAttempted = true;
+      const stopped = await run(current.cliPath, ["app-server", "daemon", "stop"], paths.options);
+      if (stopped.status !== 0) return refuseStop("daemon_stop_failed");
+      if (!await approvedProcessIsDead(expected, paths, run)) return refuseStop("daemon_death_unverified");
+      return { ok: true, reasonCode: null, stopAttempted };
+    } catch { return refuseStop("daemon_stop_failed"); }
+  }
+
+  async function startAfterMaintenance({ context, expected } = {}) {
+    if (!validApproval(expected)) return refused("invalid_maintenance_approval");
+    try {
+      const pinned = { ...context, env: { ...(context?.env ?? process.env), CODEX_HOME: expected.codexHome } };
+      const paths = await maintenanceContext(pinned);
+      if (paths.platform !== "darwin-arm64") return refused("maintenance_platform_unsupported");
+      const install = { ...paths, ...await probeMaintenanceInstall(paths, run) };
+      if (!sameFields(expected, install, installationKeys)) return refused("service_identity_changed");
+      const existing = await inspectMaintenance(pinned);
+      if (existing) {
+        if (["ready", "busy"].includes(existing.state) && sameFields(expected, existing, installationKeys)
+          && existing.serverVersion === expected.cliVersion) return { ok: true, reasonCode: null, snapshot: existing };
+        return refused("service_identity_changed", existing);
+      }
+      if (!await approvedProcessIsDead(expected, paths, run)) return refused("daemon_death_unverified");
+      const started = await run(install.cliPath, ["app-server", "daemon", "start"], paths.options);
+      if (started.status !== 0) return refused("daemon_start_failed");
+      const current = await inspectMaintenance(pinned);
+      if (!current || !["ready", "busy"].includes(current.state)
+        || !sameFields(expected, current, installationKeys) || current.serverVersion !== expected.cliVersion) {
+        return refused("daemon_start_unverified", current);
+      }
+      return { ok: true, reasonCode: null, snapshot: current };
+    } catch { return refused("daemon_start_failed"); }
+  }
+
+  return { inspectMaintenance, stopForMaintenance, startAfterMaintenance };
+}

package/node_modules/@agents-can-communicate/adapter-gemini-cli/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Coordinate this Gemini CLI session with other AI agent sessions working in the same workspace.",
   "contextFileName": "skills/acc/SKILL.md"
 }

package/node_modules/@agents-can-communicate/adapter-gemini-cli/package.json

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

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

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

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

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

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

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

package/node_modules/@agents-can-communicate/cli/package.json

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

package/node_modules/@agents-can-communicate/cli/src/args.mjs

@@ -58,7 +58,7 @@ export const COMMANDS = Object.freeze({
   uninstall: { required: [], optional: ["home"], repeated: ["adapter"], flags: ["dry-run"] },
   // Asking npm whether there is a newer ACC. The one command that touches the
   // network, and never on the hook path.
-  update: { required: [], optional: ["auto", "pin"], flags: ["check", "apply"] },
+  update: { required: [], optional: ["auto", "pin"], flags: ["check", "apply", "yes"] },
   // The two things a person types first after installing from a registry. The
   // CLI answered neither: `acc --version` and `acc --help` were both "unknown
   // command", and `acc` on its own asked for a command without naming one.

package/node_modules/@agents-can-communicate/cli/src/doctor-command.mjs

@@ -15,6 +15,7 @@ import { ALL_ADAPTERS, clientContext, probeTimeout } from "./install-command.mjs
 import { describePresence } from "./main.mjs";
 import { platformPaths } from "./platform-paths.mjs";
 import { noticeUpdate } from "./update-check.mjs";
+import { managedUpdateDiagnostic } from "./managed-runtime/diagnostics.mjs";
 import { readControl } from "./managed-runtime/state.mjs";
 import { diagnoseFilesystemStore, repairFilesystemStore }
   from "@agents-can-communicate/storage-filesystem";
@@ -207,9 +208,7 @@ export async function runDoctor({ options, context, runtime }) {
   const update = manager === null
     ? await noticeUpdate({ dataHome, running, env: runtime?.env ?? {},
       now: Date.parse(clock.now()), get: runtime?.fetch, io: { readFile, writeFile, mkdir } })
-    : { checked: false, running, latest: manager.pending?.version ?? null,
-      newer: manager.pending !== null, auto: manager.auto, pin: manager.pin,
-      pending: manager.pending?.version ?? null, phase: manager.phase, notice: manager.notice };
+    : await managedUpdateDiagnostic(runtime.managerRoot, manager, running);
 
   // Before the store is read for anything else. `collectStatus` reads every
   // record, so on the store this command exists to describe it threw first and
@@ -276,7 +275,7 @@ export async function runDoctor({ options, context, runtime }) {
   ...adapters.filter(adapter => adapter.present && adapter.outgoingDelivery)
     .map(adapter => `  ${adapter.displayName} ${adapter.outgoingDelivery.diagnostic}`),
   ...(manager === null ? [] : [`  automatic updates ${manager.auto ? "on" : "off"}; ACC ${manager.active.version}`
-    + (manager.pin ? `; pinned to ${manager.pin}` : ""), ...(manager.notice ? [`  ${manager.notice}`] : [])]),
+    + (manager.pin ? `; pinned to ${manager.pin}` : ""), ...(update.notice ? [`  ${update.notice}`] : [])]),
   ...data.remediation.map(line => `  ${line}`),
   // `0 of 4` is a true line that reads as a broken machine, and on an
   // MCP-only one it would read that way on every run forever. The server needs

package/node_modules/@agents-can-communicate/cli/src/help.mjs

@@ -106,6 +106,8 @@ const NOTES = Object.freeze({
     "Use acc update --check to only report whether a newer release exists.",
     "An initial acc install enables automatic updates; reinstalling preserves your choice. Activation waits for active clients and ACC processes.",
     "--auto on|off changes automatic updates; --pin VERSION holds an exact stable version; --pin none follows stable releases.",
+    "An eligible Codex service restart asks once; a detached worker waits for idle work and verifies completion. Open clients disconnect; acc doctor reports progress.",
+    "--yes explicitly consents to that restart without a prompt; --check never schedules maintenance.",
     "--apply remains accepted as a compatibility alias for acc update."],
 });
 

package/node_modules/@agents-can-communicate/cli/src/main.mjs

@@ -18,6 +18,7 @@ import { runUpdateCommand } from "./update-command.mjs";
 import { runConfigCommand } from "./config-command.mjs";
 import { runInstallCommand } from "./install-command.mjs";
 import { runDoctor } from "./doctor-command.mjs";
+import { runManagementDoctor } from "./managed-runtime/diagnostics.mjs";
 import { createGitProbe } from "./git-probe.mjs";
 import { canonicalClaim } from "./claim-spelling.mjs";
 import { platformDataHome, runtimePaths } from "./runtime-paths.mjs";
@@ -412,7 +413,8 @@ export async function main(argv, runtime) {
   let parsed;
   try {
     parsed = parseArgs(argv);
-    if (runtime.managementOnly && !["help", "version", "update"].includes(parsed.command)) {
+    const managementDoctor = runtime.managementOnly && parsed.command === "doctor" && !parsed.options.repair;
+    if (runtime.managementOnly && !managementDoctor && !["help", "version", "update"].includes(parsed.command)) {
       throw new AccError(EXIT.DATA, "runtime unavailable; retry after the update or run acc update to recover");
     }
     // `config` is the one command that must work on a workspace ACC cannot
@@ -423,7 +425,7 @@ export async function main(argv, runtime) {
     // discovery cannot open the workspace - that is what a user is trying to
     // find out - install touches client configuration rather than ACC state,
     // and `help` has to answer in a directory that is no workspace at all.
-    const context = NO_WORKSPACE.includes(parsed.command)
+    const context = managementDoctor || NO_WORKSPACE.includes(parsed.command)
       ? null
       : parsed.command === "doctor"
         ? await openDiagnosticContext(parsed.options, runtime)
@@ -434,7 +436,7 @@ export async function main(argv, runtime) {
     const options = context === null ? parsed.options
       : await resolveOwner({ command: parsed.command, options: parsed.options,
         context, env: runtime.env });
-    const { data, text, error: outcome } = await HANDLERS[parsed.command](
+    const { data, text, error: outcome } = await (managementDoctor ? runManagementDoctor : HANDLERS[parsed.command])(
       { options, context, runtime });
     // A handler may have done real work and still failed: `acc install` writes
     // for the clients it could and reports the one it could not. The data is

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/activation.mjs

@@ -53,11 +53,49 @@ export async function listNativeHolds(root, { pidIsAlive = defaultPidIsAlive } =
   return holds;
 }
 
+/** Activation calls this under the admission mutex; diagnostics are a snapshot.
+ * The updater may ignore its own leases, never a native client's lifetime.
+ * Project only process facts: leases and bindings carry private owner tokens.
+ */
+export async function listActivationBlockers(root, { pidIsAlive = defaultPidIsAlive, ignorePid = null } = {}) {
+  const leases = (await listRuntimeHolds(root, { pidIsAlive })).filter(lease => lease.pid !== ignorePid);
+  const native = await listNativeHolds(root, { pidIsAlive });
+  const holds = [...leases.map(({ pid, kind }) => ({ pid, kind, nativeBindings: 0 })),
+    ...native.map(hold => ({ ...hold, nativeBindings: hold.reason === "unknown_workspace" ? 0 : 1 }))];
+  const byPid = new Map(), unidentified = [];
+  for (const hold of holds) {
+    const pid = hold.pid ?? null;
+    const nativeBindings = hold.nativeBindings;
+    if (pid === null) {
+      unidentified.push({ pid, kinds: [hold.kind], reason: hold.reason, nativeBindings });
+      continue;
+    }
+    const blocker = byPid.get(pid) ?? { pid, kinds: [], reason: "process_running", nativeBindings: 0 };
+    if (!blocker.kinds.includes(hold.kind)) blocker.kinds.push(hold.kind);
+    blocker.nativeBindings += nativeBindings;
+    byPid.set(pid, blocker);
+  }
+  return [...byPid.values()].sort((a, b) => a.pid - b.pid)
+    .map(blocker => ({ ...blocker, kinds: blocker.kinds.sort() })).concat(unidentified);
+}
+
+export function activationBlockerNotice(version, blockers) {
+  if (!blockers.length) return `ACC ${version} is ready; no active or unidentified processes are blocking activation.`;
+  const details = blockers.slice(0, 10).map(blocker => {
+    const facts = [blocker.kinds.map(safeText).join(", ")];
+    if (blocker.nativeBindings) facts.push(`${blocker.nativeBindings} native binding${blocker.nativeBindings === 1 ? "" : "s"}`);
+    if (blocker.pid === null) facts.push(blocker.reason.replaceAll("_", " "));
+    return `${blocker.pid === null ? "unidentified process" : `PID ${blocker.pid}`} (${facts.join("; ")})`;
+  });
+  return `ACC ${version} is ready; waiting for ${blockers.length} active or unidentified process(es): `
+    + details.join("; ") + (blockers.length > 10 ? `; and ${blockers.length - 10} more` : "") + ".";
+}
+
 async function prepareCandidate(control, root, env) {
   const file = path.join(control.pending.root, "node_modules", "@agents-can-communicate", "cli",
     "src", "managed-runtime", "refresh.mjs");
   const { prepareRefresh } = await import(pathToFileURL(file).href);
-  return prepareRefresh({ control, root, env });
+  return prepareRefresh({ control, root, env, callerProtocol: 2 });
 }
 // JSON parser diagnostics may quote private config bytes. Keep the cause and
 // known artifact paths, never the offending input or terminal control bytes.
@@ -71,7 +109,7 @@ const recipe = c => JSON.stringify([c.active, c.pending, c.home, c.targets, c.au
 
 /** Detection is outside the fence; every integration write and commit stays inside it. */
 export async function activatePending(root, { prepare = prepareCandidate, env = process.env,
-  pidIsAlive = defaultPidIsAlive, ignorePid = null } = {}) {
+  pidIsAlive = defaultPidIsAlive, ignorePid = null, beforeActivation = null } = {}) {
   root = await canonicalManagerRoot(root);
   const before = await readControl(root);
   if (!before?.pending) return { activated: false, reason: "no_pending_update" };
@@ -79,12 +117,12 @@ export async function activatePending(root, { prepare = prepareCandidate, env =
   return withManagerLock(root, async () => {
     const current = await readControl(root);
     if (!current || recipe(current) !== recipe(before)) return { activated: false, reason: "state_changed" };
-    const holds = (await listRuntimeHolds(root, { pidIsAlive })).filter(lease => lease.pid !== ignorePid);
-    holds.push(...await listNativeHolds(root, { pidIsAlive }));
-    if (holds.length) {
-      const notice = `ACC ${current.pending.version} is ready; waiting for ${holds.length} active or unidentified process(es).`;
+    if (beforeActivation) await beforeActivation(current);
+    const blockers = await listActivationBlockers(root, { pidIsAlive, ignorePid });
+    if (blockers.length) {
+      const notice = activationBlockerNotice(current.pending.version, blockers);
       await writeControl(root, { ...current, notice });
-      return { activated: false, reason: "processes_active", holds: holds.length, notice };
+      return { activated: false, reason: "processes_active", holds: blockers.length, blockers, notice };
     }
     const activating = { ...current, phase: "activating", notice: "Finishing integration refresh." };
     await writeControl(root, activating);

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/command.mjs

@@ -4,8 +4,13 @@ import { withManagerLock } from "./mutex.mjs";
 import { scheduleWorker } from "./schedule.mjs";
 import { readControl, writeControl } from "./state.mjs";
 import { performUpdate, runWorker } from "./worker.mjs";
+import { requestMaintenance } from "./maintenance.mjs";
+import { retireLegacyUpdateWorker, stageNewerManagementRuntime } from "./management-recovery.mjs";
 
 export function validateUpdateOptions(options) {
+  if (options.yes && (options.check || options.auto !== undefined || options.pin !== undefined)) {
+    throw new AccError(EXIT.USAGE, "--yes only consents to client maintenance during acc update");
+  }
   if (options.auto !== undefined && !["on", "off"].includes(options.auto)) {
     throw new AccError(EXIT.USAGE, "--auto expects on or off");
   }
@@ -40,9 +45,15 @@ export async function runManagedUpdate({ options, runtime }) {
       return { data: { auto: control.auto, pin: control.pin, running: control.active.version },
         text: `Automatic updates ${control.auto ? "on" : "off"}. ${control.pin ? `Pinned to ${control.pin}.` : "Following stable releases."}` };
     }
+    if (!options.check) await stageNewerManagementRuntime(root, runtime);
     const result = options.check
       ? await performUpdate(root, { check: true, env })
       : await runWorker(root, { force: true, env, ignorePid: process.pid });
+    if (!options.check && (result.reason === "processes_active" || result.reason === "maintenance_pending"
+      || result.activated || result.checked && !result.newer)) {
+      const maintenance = await requestMaintenance({ root, control: await readControl(root), options, runtime });
+      if (maintenance) return maintenance;
+    }
     const text = result.activated ? `Updated ACC to ${result.version}; integrations refreshed.`
       : result.notice && result.reason === "processes_active" ? result.notice
         : result.reason === "refresh_failed" ? [result.notice,
@@ -57,6 +68,10 @@ export async function runManagedUpdate({ options, runtime }) {
       ...(result.reason === "refresh_failed" ? { error: new AccError(EXIT.DATA, text) } : {}) };
   } catch (error) {
     if (/manager lock held/.test(error.message)) {
+      if (!options.check && options.auto === undefined && options.pin === undefined && !runtime.legacyWorkerRetried
+        && await retireLegacyUpdateWorker(root).catch(() => false)) {
+        return runManagedUpdate({ options, runtime: { ...runtime, legacyWorkerRetried: true } });
+      }
       return { data: { inProgress: true }, text: "An update is already in progress; ACC will activate it when running clients exit." };
     }
     throw error instanceof AccError ? error : new AccError(EXIT.DATA, error.message);

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/diagnostics.mjs

@@ -0,0 +1,35 @@
+import { activationBlockerNotice, listActivationBlockers } from "./activation.mjs";
+import { MAINTENANCE_ACTIVE, maintenanceNotice, maintenanceReport, readMaintenance } from "./maintenance-state.mjs";
+import { readControl } from "./state.mjs";
+
+/** Available when workspace admission is fenced, and from a newer management
+ * implementation before activation. Never opens a workspace or probes clients.
+ */
+export async function runManagementDoctor({ runtime }) {
+  const manager = await readControl(runtime.managerRoot);
+  if (!manager) throw new Error("managed update state is unavailable; run acc update to recover");
+  const update = await managedUpdateDiagnostic(runtime.managerRoot, manager, manager.active.version);
+  return { data: { scope: "update", workspaceInspection: "unavailable_during_update", update,
+    remediation: ["acc update"] },
+  text: ["Update diagnostics only; workspace and integrations were not inspected.",
+    update.notice ?? `ACC ${manager.active.version}; update phase ${manager.phase}.`,
+    "Run acc update to finish, then acc doctor for the full workspace report."].join("\n") };
+}
+
+export async function managedUpdateDiagnostic(root, manager, running) {
+  const blockers = manager.pending ? await listActivationBlockers(root, { ignorePid: process.pid }) : null;
+  const update = { checked: false, running, latest: manager.pending?.version ?? null,
+    newer: manager.pending !== null, auto: manager.auto, pin: manager.pin,
+    pending: manager.pending?.version ?? null, phase: manager.phase,
+    notice: blockers === null ? manager.notice : manager.phase === "activating" && !blockers.length
+      ? "Integration refresh is incomplete; run acc update to recover."
+      : activationBlockerNotice(manager.pending.version, blockers),
+    ...(blockers === null ? {} : { holds: blockers.length, blockers }) };
+  const maintenance = await readMaintenance(root);
+  if (maintenance && (maintenance.target.root === (manager.pending ?? manager.active).root
+    || MAINTENANCE_ACTIVE.includes(maintenance.status))) {
+    update.maintenance = maintenanceReport(maintenance);
+    update.notice = maintenanceNotice(maintenance);
+  }
+  return update;
+}

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/entry.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { scheduleWorker } from "./schedule.mjs";
 import { acquireRuntime } from "./leases.mjs";
-import { canonicalManagerRoot, readControl } from "./state.mjs";
+import { canonicalManagerRoot, readControl, readManagedJson } from "./state.mjs";
 
 export const ENTRY_KINDS = Object.freeze([
   "acc", "acc-hook", "acc-mcp", "acc-bootstrap", "acc-claude-channel",
@@ -53,6 +53,31 @@ function unavailable(kind) {
   }
 }
 
+const stableVersion = value => typeof value === "string" && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(value);
+function newerVersion(left, right) {
+  if (!stableVersion(left) || !stableVersion(right)) return false;
+  const a = left.split(".").map(BigInt), b = right.split(".").map(BigInt);
+  for (let index = 0; index < 3; index++) if (a[index] !== b[index]) return a[index] > b[index];
+  return false;
+}
+
+/** Pending means downloaded and verified. Older packages do not advertise this
+ * management-only protocol; never load them speculatively for workspace work.
+ */
+async function updateImplementation(packageRoot, control) {
+  let selected = null;
+  for (const candidate of [{ root: packageRoot }, control.pending].filter(candidate => candidate?.root)) {
+    try {
+      const manifest = await readManagedJson(path.join(candidate.root, "package.json"));
+      if (manifest?.name !== "agents-can-communicate" || manifest.accManagedUpdateProtocol !== 2
+        || candidate.version !== undefined && manifest.version !== candidate.version
+        || !newerVersion(manifest.version, selected?.version ?? control.active.version)) continue;
+      selected = { root: candidate.root, version: manifest.version };
+    } catch { /* Unreadable alternatives leave the active implementation available. */ }
+  }
+  return selected?.root ?? null;
+}
+
 /** The lease lasts until OS process death, including callbacks after main returns. */
 export async function runEntry({ kind, packageRoot, managerRoot, managedRequired = false }) {
   if (!ENTRY_KINDS.includes(kind)) throw new Error("unknown ACC entry point");
@@ -66,6 +91,7 @@ export async function runEntry({ kind, packageRoot, managerRoot, managedRequired
   }
   let selected = packageRoot;
   let managed = null;
+  let managementOnly = false;
   let root;
   try {
     const requestedDataHome = bootstrapOptions === null ? null : await canonicalManagerRoot(bootstrapOptions.dataHome);
@@ -81,12 +107,18 @@ export async function runEntry({ kind, packageRoot, managerRoot, managedRequired
     if (control !== null) {
       selected = control.active.root;
       managed = root;
-      const lease = await acquireRuntime(root, { pid: process.pid, kind });
-      selected = lease.runtime.root;
-      managed = root;
-      const quiet = kind === "acc" && ["update", "install", "uninstall", "help", "version",
-        "--help", "-h", "--version", "-v", "-V"].includes(process.argv[2]);
-      if (!quiet) await scheduleWorker(root, control);
+      const update = kind === "acc" && ["update", "doctor"].includes(process.argv[2])
+        ? await updateImplementation(packageRoot, control) : null;
+      if (update !== null) {
+        selected = update;
+        managementOnly = true;
+      } else {
+        const lease = await acquireRuntime(root, { pid: process.pid, kind });
+        selected = lease.runtime.root;
+        const quiet = kind === "acc" && ["update", "install", "uninstall", "help", "version",
+          "--help", "-h", "--version", "-v", "-V"].includes(process.argv[2]);
+        if (!quiet) await scheduleWorker(root, control);
+      }
     } else if (managedRequired) throw new Error("managed runtime is not initialized");
   } catch {
     // Help and update recovery must remain reachable when state cannot admit a
@@ -106,5 +138,5 @@ export async function runEntry({ kind, packageRoot, managerRoot, managedRequired
     return;
   }
   const runtime = await import(pathToFileURL(path.join(selected, "bin", "entrypoints", `${kind}.mjs`)).href);
-  await runtime.main({ managerRoot: managed, packageRoot: selected });
+  await runtime.main({ managerRoot: managed, packageRoot: selected, ...(managementOnly ? { managementOnly } : {}) });
 }

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/legacy-maintenance.mjs

@@ -0,0 +1,47 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { askConfirmation } from "../confirm.mjs";
+import { ALL_ADAPTERS } from "../install-command.mjs";
+import { MAINTENANCE_ACTIVE, readMaintenance } from "./maintenance-state.mjs";
+
+const inspectServices = async options => (await import("./maintenance.mjs")).inspectMaintenanceServices(options);
+const request = async options => (await import("./maintenance.mjs")).requestMaintenance(options);
+const handoff = () => Object.assign(new Error("ACC maintenance needs confirmation or recovery; run acc update."),
+  { code: "ACC_LEGACY_MAINTENANCE_HANDOFF" });
+
+async function isLegacyWorker(argv, control, root) {
+  if (argv.length !== 3) return false;
+  try {
+    return await realpath(argv[1]) === await realpath(path.join(control.active.root, "bin", "acc-update-worker.mjs"))
+      && await realpath(argv[2]) === await realpath(root);
+  } catch { return false; }
+}
+
+/** Old activation imports this candidate before taking its admission fence.
+ * Only request/schedule here: the detached job waits for this process to exit.
+ * Throwing in the old background worker unwinds its idle-loop lock normally.
+ */
+export async function bridgeLegacyMaintenance({ control, root, env = process.env, callerProtocol = 1 }, {
+  argv = process.argv, input = process.stdin, output = process.stdout,
+  inspect = inspectServices, requestMaintenance = request,
+} = {}) {
+  if (callerProtocol >= 2) return null;
+  const worker = await isLegacyWorker(argv, control, root);
+  const interactive = argv[2] === "update" && !argv.includes("--json")
+    && input.isTTY === true && output.isTTY === true;
+  if (!worker && !interactive) return null;
+  const existing = await readMaintenance(root);
+  let services;
+  if (!MAINTENANCE_ACTIVE.includes(existing?.status)) {
+    if (!control.pending) return null;
+    services = await inspect({ root, control, env, adapters: ALL_ADAPTERS() });
+    if (!services.length) return null;
+    if (worker) throw handoff();
+  }
+  const result = await requestMaintenance({ root, control, options: { json: false }, services,
+    runtime: { env, input, output, confirm: askConfirmation,
+      isInteractive: () => interactive, packageRoot: control.pending?.root ?? control.active.root } });
+  if (worker) throw handoff();
+  if (result?.text) output.write(`${result.text}\n`);
+  return result;
+}

package/node_modules/@agents-can-communicate/cli/src/managed-runtime/maintenance-state.mjs

@@ -0,0 +1,57 @@
+import path from "node:path";
+import { managedDirectory, readManagedJson, validateRuntime, writeManagedJson } from "./state.mjs";
+
+export const MAINTENANCE_ACTIVE = ["waiting", "stopping", "refreshing", "restarting", "recovery"];
+const statuses = [...MAINTENANCE_ACTIVE, "completed", "failed", "cancelled"];
+export const maintenanceRecipe = c => JSON.stringify([c.active, c.pending, c.home, c.targets, c.auto, c.pin]);
+
+export async function readMaintenance(root) {
+  if (!await managedDirectory(root)) return null;
+  const value = await readManagedJson(path.join(root, "maintenance.json"));
+  if (value === undefined) return null;
+  if (value.schemaVersion !== 1 || typeof value.id !== "string" || !/^[a-f0-9-]{36}$/.test(value.id)
+    || !statuses.includes(value.status) || typeof value.recipe !== "string"
+    || typeof value.workerRoot !== "string" || !path.isAbsolute(value.workerRoot)
+    || !Number.isFinite(value.deadline) || !Number.isSafeInteger(value.callerPid) || value.callerPid < 1
+    || !(value.workerPid === null || Number.isSafeInteger(value.workerPid) && value.workerPid > 0)
+    || !Array.isArray(value.services) || value.services.length !== 1
+    || !value.services.every(s => typeof s.adapterId === "string" && s.snapshot
+      && Number.isSafeInteger(s.snapshot.pid) && s.snapshot.pid > 0)
+    || !Array.isArray(value.attempted) || !value.attempted.every(id => value.services.some(s => s.adapterId === id))) {
+    throw new Error("invalid update maintenance record");
+  }
+  await validateRuntime(root, value.target);
+  return value;
+}
+
+/** Caller holds the admission mutex or the exclusive maintenance-worker lock. */
+export async function writeMaintenance(root, job) {
+  await writeManagedJson(path.join(root, "maintenance.json"), job);
+  return job;
+}
+
+export function maintenanceReport(job) {
+  return { id: job.id, status: job.status, version: job.target.version,
+    reasonCode: job.reasonCode ?? null, workerPid: job.workerPid,
+    ...(job.status === "waiting" && job.waiting ? { waiting: job.waiting } : {}),
+    services: job.services.map(({ adapterId, snapshot }) => ({ adapterId,
+      serviceId: snapshot.serviceId, pid: snapshot.pid, clientVersion: snapshot.cliVersion,
+      serverVersion: snapshot.serverVersion })) };
+}
+
+export function maintenanceNotice(job) {
+  const version = job.target.version;
+  if (job.status === "completed") return `ACC ${version} update maintenance completed; the client service was restarted and verified.`;
+  if (job.status === "cancelled") return `Update maintenance cancelled (${job.reasonCode}); no client service was stopped.`;
+  if (job.status === "failed") return `Update maintenance failed (${job.reasonCode}); run acc update to retry.`;
+  if (job.status === "recovery") return `Client service recovery is pending (${job.reasonCode}); run acc update to retry recovery.`;
+  if (job.status === "waiting") {
+    const waiting = job.waiting?.reason === "service_busy" ? `idle client work (${job.waiting.busyThreads ?? "unknown"} active turns, ${job.waiting.queuedRequests ?? "unknown"} queued requests)`
+      : job.waiting?.reason === "other_processes" ? `${job.waiting.processes} other or unidentified process(es) to exit`
+        : job.waiting?.reason === "caller_exit" ? "the requesting command to exit"
+          : job.waiting?.reason === "update_worker" ? "another ACC updater"
+            : "idle clients and other ACC processes to exit";
+    return `ACC ${version} update maintenance is scheduled; waiting for ${waiting}. Open clients will disconnect during restart. Check acc doctor for progress.`;
+  }
+  return `ACC ${version} update maintenance: ${job.status}. Check acc doctor for the result.`;
+}