agents-can-communicate 0.3.0 → 0.4.0

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

@@ -6,12 +6,17 @@ import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
 import { createGeminiCliAdapter } from "@agents-can-communicate/adapter-gemini-cli";
 import { createGrokAdapter } from "@agents-can-communicate/adapter-grok";
 import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
-import { LIVE_POLICIES, applyPlan, describeActivation, detectInstallation, livePolicyOf,
+import { LIVE_POLICIES, applyPlan, detectInstallation, livePolicyOf,
   loadOwnership, planInstallation, rcFileFor, shellOf, shimDirFor }
   from "@agents-can-communicate/installer";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
 import { platformPaths } from "./platform-paths.mjs";
+import { installManaged, uninstallManaged } from "./managed-runtime/install.mjs";
+
+// Kept cohesive above 300 lines because this is the install command boundary:
+// detection, consent, planning, application, and reporting share one context
+// and result contract that would otherwise be duplicated across modules.
 
 // Where each client keeps its own configuration. All of it derives from one
 // home, so a test - or an operator with a second account - can point the whole
@@ -19,11 +24,13 @@ import { platformPaths } from "./platform-paths.mjs";
 // Each client keeps its own directory under the user's home, and an adapter
 // pointed at the home itself writes beside them rather than inside them. That
 // install reports success and the client never reads a byte of it.
-export const clientContext = (home, stateRoot, { shell = null, env = {} } = {}) => ({
+export const clientContext = (home, stateRoot, { shell = null, env = {}, dataHome } = {}) => ({
   home,
+  ...(dataHome === undefined ? {} : { dataHome }),
   configDir: path.join(home, ".claude"),
   agentsHome: home,
-  codexHome: path.join(home, ".codex"),
+  codexHome: typeof env.CODEX_HOME === "string" && env.CODEX_HOME !== ""
+    ? env.CODEX_HOME : path.join(home, ".codex"),
   kimiHome: path.join(home, ".kimi-code"),
   grokHome: path.join(home, ".grok"),
   // The user's login shell and PATH, for the optional native shell bootstrap:
@@ -142,6 +149,9 @@ export function describeOutcome({ action, acted, failed = [], skipped = [],
   ...operations.filter(operation => operation.applied
     && typeof operation.deliveryDiagnostic === "string")
     .map(operation => `  ${operation.deliveryDiagnostic}`),
+  ...operations.filter(operation => operation.applied)
+    .flatMap(operation => (operation.needsAction ?? [])
+      .map(step => `  ${operation.adapterId}: ${step}`)),
   ...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
@@ -192,18 +202,43 @@ export function actedOn(result) {
 const isInteractive = runtime => typeof runtime.isInteractive === "function"
   && runtime.isInteractive() === true;
 
-// One default-No question per eligible client, asked only after detection has
-// finished and only when a person is at both ends of the terminal. It names
-// the client, the mechanism, and the files or service it would touch, and says
-// when the choice takes effect.
-function questionFor(entry, context) {
-  const activation = { livePolicy: "actionable", shell: context.shell,
-    rcFile: rcFileFor(context.home, context.shell), shimDir: shimDirFor(context.stateRoot),
-    mechanisms: entry.nativeDelivery.activationPlan.mechanisms };
-  return [`Enable native live delivery for ${entry.displayName} ${entry.version}?`,
-    ...describeActivation(activation).map(line => `  ${line}`),
-    "  applies to newly started sessions; a new PATH block needs a new or reloaded shell"]
-    .join("\n");
+/**
+ * One default-No question per eligible client, asked only after detection has
+ * finished and only when a person is at both ends of the terminal.
+ *
+ * Written for someone who has never heard of this project. It used to open with
+ * "Enable native live delivery" over a list of internal artefact names, which
+ * told a first-time reader neither what they would gain nor what it would cost -
+ * and left out the part that matters most: saying yes makes their own `claude`
+ * start with the vendor's `--dangerously-load-development-channels` flag. A
+ * consent prompt that hides the loudest consequence is not consent.
+ *
+ * So the order is the reader's, not the installer's: what changes for them,
+ * what it costs, what it touches, and that "no" costs them nothing.
+ */
+function questionFor(entry, context, { onlyEligible = false } = {}) {
+  const bootstrap = entry.nativeDelivery.activationPlan.mechanisms
+    .find(mechanism => mechanism.kind === "shell-bootstrap") ?? null;
+  // The presence of a flag is what makes this worth asking about at all: it is
+  // why the client will warn at every start from now on. Which flag it is, and
+  // that a shim adds it, are answers to a question nobody is asking here - the
+  // shim `exec`s and is gone, so nothing runs "through" acc afterwards either.
+  const flags = (bootstrap?.prefixArgs ?? []).filter(argument => argument.startsWith("--"));
+  void context;
+  // Why the default is No, and why only one client is being asked about, are
+  // the two questions the bare prompt provokes and never answered: a `[y/N]`
+  // reads as "not recommended" on its own, and a single question among four
+  // installed clients reads as an omission. Both have the same short answer.
+  const aside = ["experimental", ...(onlyEligible ? [`${entry.displayName} only`] : [])]
+    .join("; ");
+  return [
+    `Let idle agents answer each other while you are away?  (${aside})`,
+    ...(flags.length === 0 || bootstrap === null
+      ? ["  Yes: they reply without waiting for you."]
+      : [`  Yes: they reply without waiting for you, and ${entry.displayName} asks you`,
+        "       to allow development channels every time it starts."]),
+    "  No:  messages still arrive, at the session's next turn.",
+  ].join("\n");
 }
 
 /**
@@ -220,6 +255,11 @@ export async function decideDelivery({ options, detected, recorded, runtime, dry
     throw new AccError(EXIT.USAGE, `unknown delivery policy: ${explicit}`, { delivery: explicit });
   }
   const recordedById = new Map(recorded.map(install => [install.adapterId, install]));
+  // Whether this client is the only one that could be asked at all. When it is,
+  // the question says so, because otherwise being asked about one of four
+  // installed clients looks like the other three were forgotten.
+  const onlyEligible = detected
+    .filter(candidate => candidate.nativeDelivery?.state === "eligible").length === 1;
   const deliveryByAdapter = {};
   const asked = [];
   let withheld = 0;
@@ -234,7 +274,7 @@ export async function decideDelivery({ options, detected, recorded, runtime, dry
       deliveryByAdapter[entry.adapterId] = "off";
       if (eligible) withheld += 1;
     } else {
-      const yes = await runtime.confirm(questionFor(entry, context),
+      const yes = await runtime.confirm(questionFor(entry, context, { onlyEligible }),
         { input: runtime.input, output: runtime.output }) === true;
       deliveryByAdapter[entry.adapterId] = yes ? "actionable" : "off";
       asked.push(entry.adapterId);
@@ -263,7 +303,7 @@ export async function runInstallCommand({ options, runtime, action = "install" }
   const { data: dataHome } = platformPaths({ platform: runtime.platform,
     env: runtime.env ?? {} });
   const context = clientContext(home, path.join(dataHome, "acc"),
-    { shell: shellOf(runtime.env), env: runtime.env ?? {} });
+    { shell: shellOf(runtime.env), env: runtime.env ?? {}, dataHome });
 
   const detected = await detectInstallation({ adapters, context,
     probeTimeoutMs: probeTimeout(runtime.env) });
@@ -297,7 +337,15 @@ export async function runInstallCommand({ options, runtime, action = "install" }
   const plan = planInstallation({ adapters, detected, context, action, recorded,
     accVersion, allowDowngrade: options.downgrade === true, requested,
     deliveryByAdapter: decided.deliveryByAdapter });
-  const result = await applyPlan({ plan, adapters, context, dataHome, dryRun, accVersion });
+  const apply = (paths = {}) => applyPlan({ plan, adapters, context: { ...context, ...paths },
+    dataHome, dryRun, accVersion, activation: { bootstrap: paths.bootstrap } });
+  const result = action === "install" && !dryRun && runtime.packageRoot
+    ? await installManaged({ packageRoot: runtime.packageRoot,
+      managerRoot: path.join(dataHome, "acc", "runtime"), dataHome, home, cwd: options.cwd ?? runtime.cwd,
+      targets: plan.operations.map(operation => operation.adapterId), env: runtime.env, apply })
+    : action === "uninstall" && !dryRun && runtime.managerRoot
+      ? await uninstallManaged({ managerRoot: runtime.managerRoot, apply })
+      : await apply();
 
   const acted = actedOn(result);
   if (dryRun) {

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

@@ -13,7 +13,7 @@ import { parseArgs, positiveNumber } from "./args.mjs";
 // A usage error names what is missing rather than failing deeper in a service
 // with the argument already half-applied.
 const usage = message => new AccError(EXIT.USAGE, message);
-import { describeCommands, helpText } from "./help.mjs";
+import { commandHelpText, describeCommand, describeCommands, helpText } from "./help.mjs";
 import { runUpdateCommand } from "./update-command.mjs";
 import { runConfigCommand } from "./config-command.mjs";
 import { runInstallCommand } from "./install-command.mjs";
@@ -73,23 +73,24 @@ async function locateContext(options, runtime) {
     gitProbe: runtime.gitProbe ?? createGitProbe(),
     explicitConfig: options.workspace,
   });
+  const dataHome = runtime.dataHome ?? platformDataHome({ platform: runtime.platform,
+    env: runtime.env });
   const paths = runtimePaths({
-    dataHome: runtime.dataHome ?? platformDataHome({ platform: runtime.platform,
-      env: runtime.env }),
+    dataHome,
     workspaceId: descriptor.id,
     workspaceRoots: descriptor.roots,
   });
-  return { descriptor, paths };
+  return { descriptor, paths, dataHome };
 }
 
-async function withService({ descriptor, paths }, runtime) {
+async function withService({ descriptor, paths, dataHome }, runtime) {
   const store = await openFilesystemStore({ root: paths.root, clock: runtime.clock,
     ids: runtime.ids, workspaceId: descriptor.id });
   const service = createCoordinationService({ store, clock: runtime.clock, ids: runtime.ids });
-  return { descriptor, paths,
+  return { descriptor, paths, dataHome,
     service,
     deliveryRouter: typeof runtime.createDeliveryRouter === "function"
-      ? runtime.createDeliveryRouter({ service, clock: runtime.clock }) : null };
+      ? runtime.createDeliveryRouter({ service, clock: runtime.clock, dataHome }) : null };
 }
 
 async function openContext(options, runtime) {
@@ -200,7 +201,9 @@ const HANDLERS = Object.freeze({
   sync: async ({ options, context }) => {
     const result = await context.service.sync({ sessionId: options.session,
       cursor: options.cursor ?? null, scope: options.scope,
+      messageId: options.message, kind: options.type, current: options.current,
       limit: options.limit ? positiveNumber(options.limit, "limit") : undefined });
+    if (result.scope === "history") return { data: result, text: JSON.stringify(result, null, 2) };
     // Solo zero-overhead: nothing to say means nothing printed, not a banner.
     const text = result.solo ? "" : `${result.attention.length} attention; `
       + `${result.roster.length} session(s); cursor ${result.cursor}`;
@@ -250,7 +253,9 @@ const HANDLERS = Object.freeze({
       context.service.sendMessage({ sessionId: options.session,
       generation: options.generation, clientMessageId: clientMessageId(options, context),
       toParticipantIds, kind,
-      obligation: obligationFor(kind, options.obligation, toParticipantIds.length > 0),
+      supersedes: options.supersedes, withdraws: options.withdraws,
+      obligation: obligationFor(kind, options.obligation, toParticipantIds.length > 0
+        || options.supersedes !== undefined || options.withdraws !== undefined),
       subject: options.subject, body: options.body, descriptor: context.descriptor }) });
     const message = routed.recorded;
     return { data: { message, delivery: routed.delivery },
@@ -258,6 +263,15 @@ const HANDLERS = Object.freeze({
   },
 
   inbox: async ({ options, context }) => {
+    if (options.message === undefined) {
+      const page = await context.service.listInbox({ sessionId: options.session,
+        generation: options.generation, cursor: options.cursor,
+        limit: options.limit === undefined ? undefined : positiveNumber(options.limit, "limit") });
+      return { data: page, text: JSON.stringify(page, null, 2) };
+    }
+    if (options.cursor !== undefined || options.limit !== undefined) {
+      throw usage("an exact inbox read cannot use --cursor or --limit");
+    }
     const messages = await context.service.readInbox({ sessionId: options.session,
       generation: options.generation, messageId: options.message });
     return { data: messages, text: messages.length === 0
@@ -271,8 +285,8 @@ const HANDLERS = Object.freeze({
       generation: options.generation, messageId: options.message, body: options.body,
       subject: options.subject, clientMessageId: clientMessageId(options, context) }) });
     const result = routed.recorded;
-    return { data: { message: result.reply, delivery: routed.delivery },
-      text: recordedText(result.reply, routed.delivery) };
+    return { data: { message: result.reply, receipt: result.receipt, delivery: routed.delivery },
+      text: `${recordedText(result.reply, routed.delivery)}; acknowledged ${result.receipt.messageId}` };
   },
 
   request: async ({ options, context }) => {
@@ -346,7 +360,7 @@ const HANDLERS = Object.freeze({
       ids: runtime.ids });
     if (result.subcommand === "validate") {
       return { data: result, text: result.present
-        ? `${result.file} is valid` : `no ${CONFIG_FILENAME}; defaults apply` };
+        ? `${result.file} is valid` : `no ${CONFIG_FILENAME} in selected directory; ancestors not checked` };
     }
     return { data: result,
       text: result.written ? `wrote ${result.file}` : `not written: ${result.file}` };
@@ -362,7 +376,13 @@ const HANDLERS = Object.freeze({
 
   update: async ({ options, runtime }) => runUpdateCommand({ options, runtime }),
 
-  help: async () => ({ data: { commands: describeCommands() }, text: helpText() }),
+  help: async ({ options }) => {
+    if (options.helpCommand === undefined) {
+      return { data: { commands: describeCommands() }, text: helpText() };
+    }
+    const data = describeCommand(options.helpCommand, options.subcommand);
+    return { data, text: commandHelpText(data) };
+  },
 
   version: async ({ runtime }) => {
     // Read by the composition root from the package manifest: `bin/` sits at
@@ -390,6 +410,9 @@ export async function main(argv, runtime) {
   let parsed;
   try {
     parsed = parseArgs(argv);
+    if (runtime.managementOnly && !["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
     // open. Discovery validates the config too, so a broken one would fail
     // there first and `acc config validate` - the command a user runs to find

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

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { assertPortableId } from "@agents-can-communicate/protocol";
+import { readSessionRecord } from "@agents-can-communicate/storage-filesystem";
+import { listRuntimeHolds } from "./leases.mjs";
+import { confirmedDead, defaultPidIsAlive, withManagerLock } from "./mutex.mjs";
+import { canonicalManagerRoot, managedDirectory, readControl, readManagedJson, writeControl } from "./state.mjs";
+
+// Both 0.3.1 and current MCP write this exact continuity record, without
+// native client facts. A foreign harness id may look like an MCP key: require
+// its canonical file and a validated matching MCP owner before exempting it.
+async function isMcpContinuity(record, name, workspaceRoot, workspaceId) {
+  if (record?.schemaVersion !== 1 || Object.keys(record).sort().join(",")
+    !== "accSessionId,generation,harnessSessionId,schemaVersion") return false;
+  try {
+    const parts = record.harnessSessionId.split(":");
+    if (parts.length !== 3 || parts[0] !== "mcp" || parts[2] !== workspaceId) return false;
+    for (const id of [parts[1], parts[2], record.accSessionId, record.generation]) assertPortableId(id, "MCP continuity id");
+    const expected = createHash("sha256").update(record.harnessSessionId).digest("hex").slice(0, 32) + ".json";
+    if (name !== expected) return false;
+    const owner = await readSessionRecord({ root: workspaceRoot, workspaceId, sessionId: record.accSessionId });
+    return owner?.harness === "mcp" && owner.participantId === parts[1]
+      && owner.workspaceId === workspaceId && owner.sessionId === record.accSessionId
+      && owner.generation === record.generation;
+  } catch { return false; } // Ambiguous or corrupt ownership remains a safety hold.
+}
+
+/** Native bindings outlive finish/TTL; MCP process lifetime is covered by its runtime lease. */
+export async function listNativeHolds(root, { pidIsAlive = defaultPidIsAlive } = {}) {
+  const workspaces = path.join(path.dirname(await canonicalManagerRoot(root)), "workspaces");
+  if (!await managedDirectory(workspaces)) return [];
+  const holds = [];
+  for (const entry of await readdir(workspaces, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      if (entry.isSymbolicLink()) holds.push({ kind: "native", reason: "unknown_workspace" });
+      continue;
+    }
+    const bindings = path.join(workspaces, entry.name, "bindings");
+    if (!await managedDirectory(bindings)) continue;
+    for (const name of await readdir(bindings)) {
+      if (!name.endsWith(".json")) continue;
+      const record = await readManagedJson(path.join(bindings, name)).catch(() => null);
+      if (record === undefined) continue; // Concurrent lifecycle removal, before fencing.
+      if (await isMcpContinuity(record, name, path.dirname(bindings), entry.name)) continue;
+      const pid = record?.schemaVersion === 1 && Number.isSafeInteger(record.clientPid)
+        && record.clientPid > 0 ? record.clientPid : null;
+      if (pid !== null && await confirmedDead(pid, pidIsAlive)) continue;
+      holds.push({ kind: "native", pid, reason: pid === null ? "unknown_client_pid" : "client_running" });
+    }
+  }
+  return holds;
+}
+
+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 });
+}
+// JSON parser diagnostics may quote private config bytes. Keep the cause and
+// known artifact paths, never the offending input or terminal control bytes.
+const safeText = value => String(value).replace(/[\x00-\x1f\x7f-\x9f]/g, " ").slice(0, 1000);
+function safeFailure(error) {
+  const message = typeof error === "string" ? error : "integration refresh failed";
+  if (/(?:valid|parse|parsing) JSON|JSON (?:input|at position)|Unexpected token|Expected.*(?:property|comma|colon)/i.test(message)) return "configuration is not valid JSON";
+  return safeText(message);
+}
+const recipe = c => JSON.stringify([c.active, c.pending, c.home, c.targets, c.auto, c.pin]);
+
+/** 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 } = {}) {
+  root = await canonicalManagerRoot(root);
+  const before = await readControl(root);
+  if (!before?.pending) return { activated: false, reason: "no_pending_update" };
+  const apply = await prepare(before, root, 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).`;
+      await writeControl(root, { ...current, notice });
+      return { activated: false, reason: "processes_active", holds: holds.length, notice };
+    }
+    const activating = { ...current, phase: "activating", notice: "Finishing integration refresh." };
+    await writeControl(root, activating);
+    let result;
+    try {
+      result = await apply(); // Never release the fence with a mutating promise still running.
+      if (!result || !Array.isArray(result.failed) || result.failed.length) {
+        throw new Error("integration refresh is incomplete");
+      }
+    } catch (error) {
+      const notice = "Integration refresh is incomplete; run acc update to recover.";
+      await writeControl(root, { ...activating, notice });
+      const installation = result && Array.isArray(result.failed) ? { ...result,
+        failed: result.failed.map(failure => ({ ...failure, adapterId: safeText(failure.adapterId), error: safeFailure(failure.error),
+          paths: (failure.paths ?? []).map(file => safeText(file)) })) } : undefined;
+      return { activated: false, reason: "refresh_failed", notice, error: safeFailure(error.message),
+        ...(installation ? { installation } : {}) };
+    }
+    await writeControl(root, { ...activating, active: current.pending, pending: null,
+      phase: "ready", notice: `ACC ${current.pending.version} is active.` });
+    return { activated: true, version: current.pending.version, installation: result };
+  });
+}

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

@@ -0,0 +1,63 @@
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+import { stableVersion, newerVersion } from "./download.mjs";
+import { withManagerLock } from "./mutex.mjs";
+import { scheduleWorker } from "./schedule.mjs";
+import { readControl, writeControl } from "./state.mjs";
+import { performUpdate, runWorker } from "./worker.mjs";
+
+export function validateUpdateOptions(options) {
+  if (options.auto !== undefined && !["on", "off"].includes(options.auto)) {
+    throw new AccError(EXIT.USAGE, "--auto expects on or off");
+  }
+  if (options.pin !== undefined && options.pin !== "none" && !stableVersion(options.pin)) {
+    throw new AccError(EXIT.USAGE, "--pin expects an exact stable version or none");
+  }
+  if (options.check && (options.auto !== undefined || options.pin !== undefined)) {
+    throw new AccError(EXIT.USAGE, "--check cannot change update settings");
+  }
+}
+
+export async function runManagedUpdate({ options, runtime }) {
+  const root = runtime.managerRoot;
+  const env = runtime.env ?? {};
+  try {
+    if (options.auto !== undefined || options.pin !== undefined) {
+      const control = await withManagerLock(root, async () => {
+        const current = await readControl(root);
+        if (!current) throw new Error("run acc install before configuring automatic updates");
+        if (current.phase !== "ready" && options.pin !== undefined) throw new Error("finish the interrupted update before changing its version pin");
+        const pin = options.pin === undefined ? current.pin : options.pin === "none" ? null : options.pin;
+        if (pin !== null && newerVersion(current.active.version, pin)) {
+          throw new Error("pin cannot downgrade workspace data; choose the running version or a newer release");
+        }
+        return writeControl(root, { ...current,
+          auto: options.auto === undefined ? current.auto : options.auto === "on", pin,
+          pending: options.pin !== undefined && current.pending?.version !== pin ? null : current.pending,
+          notice: null });
+      });
+      await scheduleWorker(root, control, { env });
+      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."}` };
+    }
+    const result = options.check
+      ? await performUpdate(root, { check: true, env })
+      : await runWorker(root, { force: true, env, ignorePid: process.pid });
+    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,
+          ...(result.installation?.failed ?? []).map(failure =>
+            `${failure.adapterId}: ${failure.error}${failure.paths?.length ? ` (${failure.paths.join(", ")})` : ""}`),
+          ...(!result.installation?.failed?.length && result.error ? [result.error] : [])].join("\n")
+          : result.checked ? result.newer ? `ACC ${result.latest} is available; run acc update.`
+            : `ACC ${result.running} is current${result.pin ? ` for pin ${result.pin}` : ""}.`
+            : result.reason === "network_disabled" ? "Update networking is off (ACC_NO_UPDATE_CHECK)."
+              : result.notice ?? "Update is pending.";
+    return { data: result, text,
+      ...(result.reason === "refresh_failed" ? { error: new AccError(EXIT.DATA, text) } : {}) };
+  } catch (error) {
+    if (/manager lock held/.test(error.message)) {
+      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/download.mjs

@@ -0,0 +1,71 @@
+import { execFile } from "node:child_process";
+import { access, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { stageOwnGeneration } from "./generation.mjs";
+import { verifyGeneration } from "./install.mjs";
+import { managedDirectory } from "./state.mjs";
+import { ENTRY_KINDS } from "./entry.mjs";
+
+const NAME = "agents-can-communicate";
+const exec = promisify(execFile);
+export const stableVersion = version => typeof version === "string"
+  && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version);
+export function newerVersion(candidate, current) {
+  if (!stableVersion(candidate) || !stableVersion(current)) return false;
+  const left = candidate.split(".").map(BigInt), right = current.split(".").map(BigInt);
+  for (let i = 0; i < 3; i++) if (left[i] !== right[i]) return left[i] > right[i];
+  return false;
+}
+
+/** Metadata only. Downloading and npm run exclusively in the update worker. */
+export async function fetchRelease({ pin = null, env = process.env, get = fetch } = {}) {
+  if (pin !== null && !stableVersion(pin)) throw new Error("pin must be an exact stable version");
+  const registry = new URL(env.npm_config_registry || "https://registry.npmjs.org/");
+  if (!["https:", "http:"].includes(registry.protocol)) throw new Error("invalid npm registry");
+  registry.pathname = `${registry.pathname.replace(/\/$/, "")}/`;
+  const url = new URL(`${NAME}/${pin ?? "latest"}`, registry).href;
+  const response = await get(url, { signal: AbortSignal.timeout(5_000), headers: { accept: "application/json" } });
+  if (!response?.ok) throw new Error(`registry request failed (${response?.status ?? "no response"})`);
+  const body = await response.json();
+  if (body?.name !== NAME) throw new Error("release package identity mismatch");
+  if (!stableVersion(body.version) || pin !== null && body.version !== pin) throw new Error("release is not the requested stable version");
+  const integrity = body.dist?.integrity;
+  if (typeof integrity !== "string" || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(integrity)
+    || Buffer.from(integrity.slice(7), "base64").length !== 64) throw new Error("release integrity is missing or invalid");
+  return { version: body.version, integrity, registry: registry.href };
+}
+
+async function npmCli(env) {
+  const directories = [path.dirname(process.execPath), ...(env.PATH ?? "").split(path.delimiter)];
+  for (const directory of directories.filter(Boolean)) {
+    try { return await realpath(path.join(directory, "npm")); } catch { /* Try the next installed npm. */ }
+  }
+  throw new Error("npm is unavailable; the working ACC runtime was kept");
+}
+
+export async function downloadRelease(root, release, { env = process.env } = {}) {
+  const downloads = path.join(root, "downloads");
+  await managedDirectory(downloads, { create: true });
+  const temporary = await mkdtemp(path.join(downloads, ".download-"));
+  try {
+    await writeFile(path.join(temporary, "package.json"), JSON.stringify({ private: true, name: "acc-runtime-download", version: "1.0.0" }));
+    await exec(process.execPath, [await npmCli(env), "install", "--ignore-scripts", "--omit=dev",
+      "--global=false", "--prefix", temporary, "--package-lock=true",
+      "--package-lock-only=false", "--dry-run=false", "--workspaces=false",
+      "--include-workspace-root=false", "--no-audit", "--no-fund", "--save=true", "--save-exact", "--registry", release.registry,
+      `${NAME}@${release.version}`], { cwd: temporary, env, timeout: 90_000, maxBuffer: 1024 * 1024 });
+    const lock = JSON.parse(await readFile(path.join(temporary, "package-lock.json"), "utf8"));
+    if (lock.packages?.[`node_modules/${NAME}`]?.integrity !== release.integrity) {
+      throw new Error("downloaded release integrity differs from discovery");
+    }
+    const packageRoot = path.join(temporary, "node_modules", NAME);
+    const manifest = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+    if (manifest.name !== NAME || manifest.version !== release.version) throw new Error("downloaded package identity mismatch");
+    for (const name of ENTRY_KINDS) await access(path.join(packageRoot, "bin", "entrypoints", `${name}.mjs`));
+    await access(path.join(packageRoot, "bin", "acc-update-worker.mjs"));
+    const generation = await stageOwnGeneration({ packageRoot, managerRoot: root });
+    await verifyGeneration(generation, { env });
+    return { version: generation.version, root: generation.root };
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}

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

@@ -0,0 +1,110 @@
+import { realpathSync } from "node:fs";
+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";
+
+export const ENTRY_KINDS = Object.freeze([
+  "acc", "acc-hook", "acc-mcp", "acc-bootstrap", "acc-claude-channel",
+]);
+
+const BOOTSTRAP_FLAGS = new Map([["--adapter", "adapter"], ["--real-executable", "realExecutable"],
+  ["--data-home", "dataHome"]]);
+
+/** Shared with the runtime; parse before admission without importing installer code. */
+export function parseBootstrapOptions(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const key = BOOTSTRAP_FLAGS.get(args[index]);
+    const value = args[index + 1];
+    if (key === undefined || typeof value !== "string" || value === "" || key in options) return null;
+    options[key] = value;
+  }
+  return BOOTSTRAP_FLAGS.values().every(key => key in options) && path.isAbsolute(options.dataHome)
+    ? options : null;
+}
+
+// Bootstrap resolution deliberately needs only Node built-ins: no selected
+// generation is imported until admission and its actual PID lease are durable.
+export function managerLocation({ env = process.env, platform = process.platform } = {}) {
+  const data = env.ACC_DATA_HOME || (platform === "win32" ? env.APPDATA
+    : platform === "darwin" ? env.HOME && path.join(env.HOME, "Library", "Application Support")
+      : env.XDG_DATA_HOME || env.HOME && path.join(env.HOME, ".local", "share"));
+  if (typeof data !== "string" || !path.isAbsolute(data)) throw new Error("cannot resolve ACC data home");
+  return path.join(data, "acc", "runtime");
+}
+
+export function invokedDirectly(url) {
+  try { return !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(url)); }
+  catch { return false; }
+}
+
+function unavailable(kind) {
+  // Never reflect control file content or payloads into a client diagnostic.
+  if (kind === "acc-hook" || kind === "acc-claude-channel") {
+    process.stderr.write("acc: coordination unavailable during runtime update; session may continue\n");
+    process.exitCode = 0;
+  } else if (kind === "acc-bootstrap") {
+    process.exitCode = 1; // The vendor shell shim launches its original command.
+  } else {
+    process.stderr.write("acc: runtime unavailable; retry after the update or run acc update to recover\n");
+    process.exitCode = 4;
+  }
+}
+
+/** 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");
+  const bootstrapOptions = kind === "acc-bootstrap" ? parseBootstrapOptions(process.argv.slice(2)) : null;
+  if (kind === "acc-bootstrap" && bootstrapOptions === null) {
+    if (process.env.ACC_BOOTSTRAP_DEBUG === "1") {
+      process.stderr.write("acc-bootstrap: usage: --adapter <id> --real-executable <path> --data-home <path>\n");
+    }
+    process.exitCode = 2;
+    return;
+  }
+  let selected = packageRoot;
+  let managed = null;
+  let root;
+  try {
+    const requestedDataHome = bootstrapOptions === null ? null : await canonicalManagerRoot(bootstrapOptions.dataHome);
+    const requestedRoot = requestedDataHome === null ? null
+      : await canonicalManagerRoot(path.join(requestedDataHome, "acc", "runtime"));
+    if (managerRoot && requestedDataHome !== null
+      && requestedDataHome !== await canonicalManagerRoot(path.dirname(path.dirname(managerRoot)))) {
+      throw new Error("bootstrap cache home differs from its launcher");
+    }
+    root = await canonicalManagerRoot(managerRoot ?? requestedRoot ?? managerLocation());
+    if (requestedRoot !== null && root !== requestedRoot) throw new Error("bootstrap data home differs from its launcher");
+    const control = await readControl(root);
+    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);
+    } else if (managedRequired) throw new Error("managed runtime is not initialized");
+  } catch {
+    // Help and update recovery must remain reachable when state cannot admit a
+    // workspace command. The CLI parser enforces this restricted path; merely
+    // putting --help in a message value cannot bypass runtime admission.
+    if (kind === "acc" && selected) {
+      const runtime = await import(pathToFileURL(path.join(selected, "bin", "entrypoints", "acc.mjs")).href);
+      await runtime.main({ managerRoot: root ?? null, packageRoot: selected, managementOnly: true });
+      return;
+    }
+    unavailable(kind);
+    if (kind === "acc-claude-channel" && selected) {
+      const { startInertChannel } = await import(pathToFileURL(path.join(selected,
+        "bin", "entrypoints", "claude-channel-stdio.mjs")).href);
+      startInertChannel();
+    }
+    return;
+  }
+  const runtime = await import(pathToFileURL(path.join(selected, "bin", "entrypoints", `${kind}.mjs`)).href);
+  await runtime.main({ managerRoot: managed, packageRoot: selected });
+}