agents-can-communicate 0.4.2 → 0.4.4

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

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { scanConfig, unsafe } from "./toml-scan.mjs";
+
+const BEGIN = "# ACC native permissions begin ";
+const END = "# ACC native permissions end ";
+const META = "# ACC native permissions restore ";
+const hash = (body, record) => createHash("sha256")
+  .update(JSON.stringify({ body, id: record.id, before: record.before, table: record.table })).digest("hex");
+const marker = (source, prefix) => source.startsWith(prefix) ? source.slice(prefix.length) : null;
+
+// Permission selection, proxy and network grants form one ownership unit. If
+// any component changes, none can be removed independently: enabled networking
+// without its proxy has a different security meaning to Codex.
+export function inspectPermissions(source) {
+  const blocks = [];
+  let open = null, metadata = null;
+  for (const entry of scanConfig(source)) {
+    const comment = entry.code ? "" : entry.raw.trim();
+    const start = marker(comment, BEGIN), end = marker(comment, END);
+    if (start !== null) {
+      if (open || !/^[a-z]+$/.test(start) || blocks.some(block => block.id === start)) {
+        unsafe("duplicate or nested native permission marker");
+      }
+      open = { id: start, start: entry.start, table: entry.table, contentStart: entry.end };
+    } else if (comment.startsWith(META)) {
+      if (!open || open.id !== "selection" || metadata !== null || entry.start !== open.contentStart) {
+        unsafe("misplaced permission metadata");
+      }
+      try { metadata = JSON.parse(comment.slice(META.length)); }
+      catch { unsafe("invalid permission metadata"); }
+      open.contentStart = entry.end;
+    } else if (end !== null) {
+      if (!open || open.id !== end) unsafe("unmatched native permission marker");
+      blocks.push({ ...open, end: entry.end, body: source.slice(open.contentStart, entry.start) });
+      open = null;
+    }
+  }
+  if (open) return { source, state: "customized" };
+  if (!blocks.length && !metadata) return { source, state: "absent" };
+  if (!Array.isArray(metadata) || metadata.length !== blocks.length
+    || metadata.some(item => !item || typeof item !== "object" || Array.isArray(item))
+    || new Set(metadata.map(item => item.id)).size !== metadata.length) return { source, state: "customized" };
+  for (const block of blocks) {
+    const record = metadata.find(item => item.id === block.id);
+    if (!record || Object.keys(record).sort().join() !== "before,hash,id,table"
+      || typeof record.before !== "string" || record.hash !== hash(block.body, record)
+      || (block.id === "selection" && block.table.length !== 0)
+      || JSON.stringify(block.table) !== JSON.stringify(record.table)) {
+      return { source, state: "customized" };
+    }
+  }
+  // A retained reference or declaration must not be left pointing at a deleted
+  // profile. Ignore peer-looking text inside strings/comments as markers.
+  const entries = scanConfig(source);
+  const inside = entry => blocks.some(block => entry.start >= block.start && entry.end <= block.end);
+  const generatedTables = entries.filter(entry => entry.header && inside(entry)).map(entry => JSON.stringify(entry.keys));
+  const outside = entries.filter(entry => !inside(entry));
+  // New profile declarations and selectors are custom policy, regardless of
+  // how TOML spells their values (including escaped or multiline references).
+  if (outside.some(entry => entry.code && (entry.keys.includes("default_permissions")
+    || entry.keys[0] === "permissions"
+    || (!entry.header && generatedTables.includes(JSON.stringify(entry.table)))))) {
+    return { source, state: "customized" };
+  }
+  let restored = source;
+  for (const block of blocks.toSorted((a, b) => b.start - a.start)) {
+    restored = restored.slice(0, block.start) + metadata.find(item => item.id === block.id).before
+      + restored.slice(block.end);
+  }
+  // Inserting restored headers can reparent foreign assignments added after
+  // a removal marker. Verify the candidate's scopes before restoring any byte.
+  let restoredEntries;
+  try { restoredEntries = new Map(scanConfig(restored).map(entry => [entry.start, entry])); }
+  catch { return { source, state: "customized" }; }
+  for (const entry of outside.filter(item => item.code)) {
+    const delta = blocks.filter(block => block.end <= entry.start).reduce((total, block) =>
+      total + metadata.find(item => item.id === block.id).before.length - (block.end - block.start), 0);
+    const candidate = restoredEntries.get(entry.start + delta);
+    if (!candidate || JSON.stringify(candidate.keys) !== JSON.stringify(entry.keys)) {
+      return { source, state: "customized" };
+    }
+  }
+  return { source: restored, state: "owned" };
+}
+
+export function addPermissions(source, edits) {
+  const metadata = edits.map(({ id, start, end, body, table = [] }) => {
+    const record = { id, before: source.slice(start, end), table };
+    return { ...record, hash: hash(body, record) };
+  });
+  const initialMetadata = JSON.stringify(metadata);
+  // Insertions at the same offset retain caller order (selection always first).
+  for (const edit of edits.map((item, index) => ({ ...item, index }))
+    .sort((a, b) => b.start - a.start || b.index - a.index)) {
+    const block = `${BEGIN}${edit.id}\n`
+      + (edit.id === "selection" ? `${META}${JSON.stringify(metadata)}\n` : "")
+      + edit.body + `${END}${edit.id}\n`;
+    source = source.slice(0, edit.start) + block + source.slice(edit.end);
+  }
+  // Record the installed scope, which can differ after removing a legacy table.
+  for (const entry of scanConfig(source)) {
+    const id = !entry.code ? marker(entry.raw.trim(), BEGIN) : null;
+    const record = metadata.find(item => item.id === id);
+    if (!record) continue;
+    record.table = entry.table;
+    record.hash = hash(edits.find(item => item.id === id).body, record);
+  }
+  return source.replace(`${META}${initialMetadata}`, `${META}${JSON.stringify(metadata)}`);
+}

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

@@ -0,0 +1,99 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+export const unsafe = (reason = "unrecognized TOML declaration") => {
+  throw new AccError(EXIT.CONFLICT, `cannot safely edit Codex config: ${reason}; `
+    + "repair ambiguous TOML or ACC markers before retrying", { reason });
+};
+// A bounded lexical scan, not a TOML value parser. Newlines inside strings,
+// arrays and inline tables cannot introduce a header or a managed marker.
+export function* statements(source) {
+  let start = 0, code = "", quote = null;
+  const stack = [];
+  for (let i = 0; i < source.length;) {
+    const char = source[i];
+    if (quote) {
+      if (quote[0] === '"' && char === "\\") {
+        code += source.slice(i, i + 2); i += 2; continue;
+      }
+      if (source.startsWith(quote, i)) {
+        let count = quote.length;
+        if (quote.length === 3) {
+          while (source[i + count] === quote[0]) count++;
+          if (count > 5) unsafe("unsupported string quote delimiter");
+        }
+        code += source.slice(i, i + count); i += count; quote = null; continue;
+      }
+      if (quote.length === 1 && /[\r\n]/.test(char)) unsafe("newline in single-line string");
+      code += char; i++; continue;
+    }
+    if (char === "#") {
+      while (i < source.length && source[i] !== "\n") i++;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = source.startsWith(char.repeat(3), i) ? char.repeat(3) : char;
+      code += quote; i += quote.length; continue;
+    }
+    if (char === "[" || char === "{") stack.push(char);
+    if (char === "]" || char === "}") {
+      if (stack.pop() !== (char === "]" ? "[" : "{")) unsafe("mismatched collection delimiter");
+    }
+    code += char; i++;
+    if (char === "\n" && stack.length === 0) {
+      yield { raw: source.slice(start, i), code: code.trim(), start, end: i };
+      start = i; code = "";
+    }
+  }
+  if (quote || stack.length) unsafe(quote ? "unclosed string" : "unclosed collection");
+  if (start < source.length) yield { raw: source.slice(start), code: code.trim(), start, end: source.length };
+}
+
+function decodeKey(key) {
+  if (key[0] === "'") return key.slice(1, -1);
+  if (key[0] !== '"') return key;
+  return key.slice(1, -1).replace(/\\(U[\da-fA-F]{8}|u[\da-fA-F]{4}|[btnfr"\\])|\\./g,
+    (match, escape) => {
+      if (!escape) unsafe("unsupported quoted-key escape");
+      if (/^[uU]/.test(escape)) {
+        const point = Number.parseInt(escape.slice(1), 16);
+        if (point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff)) {
+          unsafe("invalid quoted-key Unicode escape");
+        }
+        return String.fromCodePoint(point);
+      }
+      return ({ b: "\b", t: "\t", n: "\n", f: "\f", r: "\r", '"': '"', "\\": "\\" })[escape];
+    });
+}
+
+function keyPath(code) {
+  const keys = [];
+  let rest = code.trimStart();
+  for (;;) {
+    const match = /^(?:[A-Za-z0-9_-]+|'[^'\r\n]*'|"(?:[^"\\\r\n]|\\[^\r\n])*")/.exec(rest);
+    if (!match) unsafe("unrecognized TOML key");
+    keys.push(decodeKey(match[0]));
+    rest = rest.slice(match[0].length).trimStart();
+    if (!rest.startsWith(".")) return { keys, rest };
+    rest = rest.slice(1).trimStart();
+  }
+}
+
+export function declaration(code) {
+  const header = code.startsWith("[");
+  const array = header && code.startsWith("[[");
+  const { keys, rest } = keyPath(header ? code.slice(array ? 2 : 1) : code);
+  if (header ? rest !== (array ? "]]" : "]") : !rest.startsWith("=")) unsafe();
+  return { keys, header, array, value: header ? null : rest.slice(1).trim() };
+}
+
+// Resolved declaration paths are only structural facts, never parsed user values.
+export function scanConfig(source) {
+  let table = [];
+  return [...statements(source)].map(item => {
+    if (!item.code) return { ...item, table: [...table], keys: [] };
+    const entry = declaration(item.code);
+    if (entry.header) table = entry.keys;
+    return { ...item, ...entry, table: [...table],
+      keys: entry.header ? entry.keys : [...table, ...entry.keys] };
+  });
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.4.2",
+  "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.2",
+  "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.2",
+  "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.2",
+  "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.2",
+  "version": "0.4.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-sdk/src/channel-directory.mjs

@@ -0,0 +1,8 @@
+import os from "node:os";
+import path from "node:path";
+
+// macOS Unix paths are capped at 104 bytes. A stable, short per-user namespace
+// also lets a sandbox grant access regardless of each client's TMPDIR value.
+export const channelSocketDirectory = () => path.join(
+  process.platform === "darwin" ? "/tmp" : os.tmpdir(),
+  `acc-ch-${typeof process.getuid === "function" ? process.getuid() : "u"}`);

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

@@ -25,3 +25,4 @@ export { clearSessionBinding, listSessionBindings, loadSessionBinding,
   from "./session-binding.mjs";
 
 export { clearNativeAttempt, loadNativeAttempt, storeNativeAttempt } from "./native-attempt.mjs";
+export { channelSocketDirectory } from "./channel-directory.mjs";

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/cli",
-  "version": "0.4.2",
+  "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
@@ -273,8 +272,10 @@ export async function runDoctor({ options, context, runtime }) {
       + `${describeNative(adapter.nativeDelivery, { clientVersion: adapter.version })}; `
       + `fallback: ${describeDeliveryFallback(adapter)}`),
   ...nativeSessionLines(adapters),
+  ...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/install-command.mjs

@@ -153,6 +153,8 @@ export function describeOutcome({ action, acted, failed = [], skipped = [],
   ...operations.filter(operation => operation.applied)
     .flatMap(operation => (operation.needsAction ?? [])
       .map(step => `  ${operation.adapterId}: ${step}`)),
+  ...operations.filter(operation => operation.applied)
+    .flatMap(operation => (operation.setupNotes ?? []).map(note => `  ${note}`)),
   ...skipped.map(entry => `  skip ${entry.adapterId}: ${entry.reason}`),
   ...failed.map(entry => `  ${entry.adapterId}: ${entry.error}`),
   // Said once, where it is needed: the reader has just been shown a list of
@@ -212,6 +214,7 @@ function questionFor(entry) {
   return [
     `Let ${entry.displayName} answer peer requests while idle? (experimental)`,
     "  Yes: automatic turns can spend tokens without waiting for you.",
+    ...(entry.outgoingDelivery?.setup ? [`       ${entry.outgoingDelivery.setup}`] : []),
     ...(warns ? ["       Allow development channels when prompted; check the client's startup notice."] : []),
     ...(entry.nativeDelivery.state !== "eligible"
       ? ["       Save consent now; delivery waits for an available client service."] : []),

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";
@@ -137,7 +138,9 @@ function recordedText(message, delivery) {
   const diagnostics = delivery.map(item => item.outcome === "offered"
     ? `live offered to ${item.recipientParticipantId} via ${item.transport}`
     : item.outcome === "queued"
-      ? `live offer unavailable (${item.errorCode ?? "durable_fallback"})`
+      ? item.errorCode === "transport_permission_denied"
+        ? "live offer blocked by sender permissions; message remains queued; run acc doctor in the sending session"
+        : `live offer unavailable (${item.errorCode ?? "durable_fallback"})`
       : `delivery already ${item.outcome}`);
   return [`recorded ${message.messageId}`, ...diagnostics].join("; ");
 }
@@ -410,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
@@ -421,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)
@@ -432,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 } : {}) });
 }