agents-can-communicate 0.3.1 → 0.4.1

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,64 @@
+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,
+          autoPreference: options.auto === undefined ? current.autoPreference ?? current.auto : options.auto === "on",
+          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 });
+}

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

@@ -0,0 +1,167 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm }
+  from "node:fs/promises";
+import path from "node:path";
+
+const NAME = "agents-can-communicate";
+const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+async function canonicalFuturePath(file) {
+  let current = path.resolve(file);
+  const trailing = [];
+  for (;;) {
+    try { return path.join(await realpath(current), ...trailing); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = path.dirname(current);
+      if (parent === current) throw error;
+      trailing.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+async function directory(file) {
+  await mkdir(file, { recursive: true, mode: 0o700 });
+  const stat = await lstat(file);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("managed runtime directory is not a regular directory");
+}
+
+function declaredPath(value) {
+  if (typeof value !== "string" || value === "" || /[\\*?\[\]{}\0]/.test(value)
+    || path.isAbsolute(value) || value.split("/").includes("..")) {
+    throw new Error("invalid declared runtime path");
+  }
+  return value.replace(/\/+$/, "");
+}
+
+async function collectFile(source, relative, collected) {
+  const stat = await lstat(source);
+  if (stat.isSymbolicLink()) throw new Error(`symbolic link inside runtime files: ${relative}`);
+  if (stat.isDirectory()) {
+    for (const entry of (await readdir(source)).sort()) {
+      await collectFile(path.join(source, entry), path.posix.join(relative, entry), collected);
+    }
+  } else if (stat.isFile()) {
+    collected.set(relative, { bytes: await readFile(source), mode: stat.mode & 0o777 });
+  } else throw new Error(`unsupported runtime file: ${relative}`);
+}
+
+async function checkDeclaredComponents(source, relative) {
+  let current = source;
+  for (const component of relative.split("/")) {
+    current = path.join(current, component);
+    if ((await lstat(current)).isSymbolicLink()) {
+      throw new Error(`symbolic link inside declared runtime path: ${relative}`);
+    }
+  }
+}
+
+function requireOutside(source, root) {
+  const relative = path.relative(source, root);
+  if (relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))) {
+    throw new Error("managed runtime must live outside its source package");
+  }
+}
+
+async function collectPackage(source, prefix, collected, expectedName, version) {
+  await checkDeclaredComponents(source, "package.json");
+  const manifestFile = path.join(source, "package.json");
+  const manifest = JSON.parse(await readFile(manifestFile, "utf8"));
+  if (manifest.name !== expectedName || manifest.version !== version
+    || !Array.isArray(manifest.files)) throw new Error("runtime package identity or declared files are invalid");
+  const declared = new Set(["package.json", ...manifest.files.map(declaredPath)]);
+  // npm includes these public package files regardless of the files whitelist.
+  for (const file of await readdir(source)) {
+    if (/^(readme|licen[cs]e)(\..*)?$/i.test(file)) declared.add(file);
+  }
+  for (const relative of declared) {
+    await checkDeclaredComponents(source, relative);
+    await collectFile(path.join(source, relative), path.posix.join(prefix, relative), collected);
+  }
+  return manifest;
+}
+
+function fingerprint(files) {
+  const hash = createHash("sha256");
+  for (const [name, file] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+    hash.update(JSON.stringify([name, file.mode, file.bytes.length]));
+    hash.update(file.bytes);
+  }
+  return hash.digest("hex");
+}
+
+async function existingMatches(target, files) {
+  try {
+    const actual = new Map();
+    await collectFile(target, "", actual);
+    if (fingerprint(actual) !== fingerprint(files)) throw new Error("managed runtime generation integrity changed");
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      // Only an absent generation is new. A damaged existing tree is not a
+      // staging directory we are entitled to overwrite.
+      const exists = await lstat(target).then(() => true, e => {
+        if (e.code === "ENOENT") return false;
+        throw e;
+      });
+      if (!exists) return false;
+    }
+    throw error;
+  }
+}
+
+/** Materialize the package's shipped files; never copy a checkout or workspace symlink. */
+export async function stageOwnGeneration({ packageRoot, managerRoot }) {
+  const source = await realpath(packageRoot);
+  const root = await canonicalFuturePath(managerRoot);
+  requireOutside(source, root);
+  await checkDeclaredComponents(source, "package.json");
+  const manifest = JSON.parse(await readFile(path.join(source, "package.json"), "utf8"));
+  if (manifest.name !== NAME || !STABLE.test(manifest.version)) throw new Error("invalid ACC runtime version");
+  const files = new Map();
+  await collectPackage(source, "", files, NAME, manifest.version);
+  if (!Array.isArray(manifest.bundleDependencies)) throw new Error("runtime must declare its bundled workspaces");
+  for (const name of manifest.bundleDependencies) {
+    if (!/^@agents-can-communicate\/[a-z0-9-]+$/.test(name)) throw new Error("invalid bundled runtime package");
+    const location = await realpath(path.join(source, "node_modules", name));
+    requireOutside(location, root);
+    await collectPackage(location, `node_modules/${name}`, files, name, manifest.version);
+  }
+  const digest = fingerprint(files);
+  await directory(root);
+  const generations = path.join(root, "generations");
+  await directory(generations);
+  const target = path.join(generations, `${manifest.version}-${digest.slice(0, 24)}`);
+  const result = { version: manifest.version, root: target, digest };
+  if (await existingMatches(target, files)) return result;
+  const staging = await mkdtemp(path.join(generations, ".staging-"));
+  try {
+    const directories = new Set([staging]);
+    for (const [name, file] of files) {
+      const destination = path.join(staging, name);
+      await mkdir(path.dirname(destination), { recursive: true });
+      for (let parent = path.dirname(destination); parent !== staging; parent = path.dirname(parent)) directories.add(parent);
+      const handle = await open(destination, "wx", file.mode);
+      try {
+        await handle.writeFile(file.bytes);
+        await handle.chmod(file.mode);
+        await handle.sync();
+      } finally { await handle.close(); }
+    }
+    for (const directory of [...directories].sort((a, b) => b.length - a.length)) {
+      const handle = await open(directory, "r");
+      try { await handle.sync(); } finally { await handle.close(); }
+    }
+    try {
+      await rename(staging, target);
+    } catch (error) {
+      if (!["EEXIST", "ENOTEMPTY"].includes(error.code) || !await existingMatches(target, files)) throw error;
+    }
+    const handle = await open(generations, "r");
+    try { await handle.sync(); } finally { await handle.close(); }
+    return result;
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}