agents-can-communicate 0.3.0 → 0.4.0

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 });
+  }
+}

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

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { validateManagedLocation } from "./location.mjs";
+import { stageOwnGeneration } from "./generation.mjs";
+import { writeLaunchers } from "./launchers.mjs";
+import { canonicalManagerRoot, readControl, writeControl } from "./state.mjs";
+import { scheduleWorker } from "./schedule.mjs";
+import { withManagerLock } from "./mutex.mjs";
+
+const exec = promisify(execFile);
+export async function verifyGeneration(runtime, { env = process.env } = {}) {
+  const temporary = await mkdtemp(path.join(tmpdir(), "acc-runtime-check-"));
+  try {
+    const { stdout } = await exec(process.execPath,
+      [path.join(runtime.root, "bin", "acc.mjs"), "version", "--json"], {
+        env: { ...env, ACC_DATA_HOME: path.join(temporary, "data"), ACC_NO_UPDATE_CHECK: "1" },
+        cwd: temporary, timeout: 10_000, maxBuffer: 64 * 1024,
+      });
+    if (JSON.parse(stdout)?.data?.version !== runtime.version) throw new Error("runtime version check failed");
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}
+
+/** Only the actual CLI composition supplies packageRoot; dry runs never enroll. */
+export async function installManaged({ packageRoot, managerRoot, dataHome, home, targets, env, apply, cwd }) {
+  const root = await validateManagedLocation({ managerRoot, dataHome, home, cwd, env });
+  const candidate = await stageOwnGeneration({ packageRoot, managerRoot: root });
+  await verifyGeneration(candidate, { env });
+  return withManagerLock(root, async () => {
+    const previous = await readControl(root);
+    if (previous !== null && previous.home !== home) {
+      throw new Error("this ACC data home manages another client home; use a separate ACC_DATA_HOME");
+    }
+    if (previous !== null && previous.active.root !== candidate.root) {
+      throw new Error("install from the active managed runtime; use acc update to switch versions");
+    }
+    const runtime = { version: candidate.version, root: candidate.root };
+    const control = { schemaVersion: 1, active: runtime, pending: runtime, phase: "activating",
+      auto: previous?.auto ?? true, pin: previous?.pin ?? null,
+      checkedAt: previous?.checkedAt ?? null, home,
+      targets: [...new Set([...(previous?.targets ?? []), ...targets])], notice: null };
+    await writeControl(root, control);
+    const paths = await writeLaunchers(root, runtime.root);
+    const result = await apply({ ...paths, preserveVersions: true });
+    if (result.failed.length === 0) {
+      const ready = await writeControl(root, { ...control, phase: "ready", pending: null });
+      await scheduleWorker(root, ready, { env });
+    } else {
+      await writeControl(root, { ...control, notice: "Integration refresh is incomplete; run acc update to recover." });
+    }
+    return result;
+  });
+}
+
+/** Removal updates enrollment under the same fence, so an updater cannot reinstall it. */
+export async function uninstallManaged({ managerRoot, apply }) {
+  const root = await canonicalManagerRoot(managerRoot);
+  return withManagerLock(root, async () => {
+    const control = await readControl(root);
+    if (!control) return apply();
+    if (control.phase !== "ready") throw new Error("finish the interrupted update with acc update before uninstalling");
+    const result = await apply();
+    const removed = new Set(result.operations.filter(operation => operation.applied)
+      .map(operation => operation.adapterId));
+    const targets = control.targets.filter(id => !removed.has(id));
+    await writeControl(root, { ...control, targets,
+      auto: targets.length > 0 && result.failed.length === 0 && control.auto,
+      pending: targets.length > 0 ? control.pending : null, notice: null });
+    return result;
+  });
+}

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

@@ -0,0 +1,60 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdtemp, open, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { ENTRY_KINDS } from "./entry.mjs";
+import { managedDirectory, syncDirectory } from "./state.mjs";
+
+const MODULES = ["entry.mjs", "state.mjs", "mutex.mjs", "leases.mjs", "schedule.mjs", "policy.mjs"];
+async function durableFile(file, bytes, mode = 0o600) {
+  const handle = await open(file, "wx", mode);
+  try { await handle.writeFile(bytes); await handle.sync(); }
+  finally { await handle.close(); }
+}
+
+export const stablePaths = root => ({
+  cli: path.join(root, "bin", "acc.mjs"), runner: path.join(root, "bin", "acc-hook.mjs"),
+  bootstrap: path.join(root, "bin", "acc-bootstrap.mjs"),
+  channel: path.join(root, "bin", "acc-claude-channel.mjs"),
+});
+
+/** Publish immutable launcher modules, then atomically replace each tiny entry.
+ * Call while admission is fenced. Old launchers are kept for already-loaded
+ * entry modules, whose dependency imports may still be pending.
+ */
+export async function writeLaunchers(root, packageRoot) {
+  const modules = await Promise.all(MODULES.map(async name => [name,
+    await readFile(new URL(name, import.meta.url))]));
+  const hash = createHash("sha256");
+  for (const [name, bytes] of modules) hash.update(name).update(bytes);
+  const id = hash.digest("hex");
+  const parent = path.join(root, "launchers");
+  await managedDirectory(parent, { create: true });
+  const directory = path.join(parent, id);
+  const staging = await mkdtemp(path.join(parent, ".staging-"));
+  try {
+    for (const [name, bytes] of modules) await durableFile(path.join(staging, name), bytes);
+    await syncDirectory(staging);
+    try { await rename(staging, directory); }
+    catch (error) { if (!["EEXIST", "ENOTEMPTY"].includes(error.code)) throw error; }
+    await managedDirectory(directory);
+    for (const [name, bytes] of modules) {
+      const file = path.join(directory, name);
+      if (!(await lstat(file)).isFile() || (await lstat(file)).isSymbolicLink()
+        || !(await readFile(file)).equals(bytes)) throw new Error("managed launcher integrity changed");
+    }
+    await syncDirectory(parent);
+  } finally { await rm(staging, { recursive: true, force: true }); }
+  const bin = path.join(root, "bin");
+  await managedDirectory(bin, { create: true });
+  for (const kind of ENTRY_KINDS) {
+    const bytes = `#!/usr/bin/env node\nimport { runEntry } from "../launchers/${id}/entry.mjs";\n`
+      + `await runEntry(${JSON.stringify({ kind, packageRoot, managerRoot: root, managedRequired: true })});\n`;
+    const temporary = path.join(bin, `.${randomUUID()}.tmp`);
+    try {
+      await durableFile(temporary, bytes, 0o700);
+      await rename(temporary, path.join(bin, `${kind}.mjs`));
+    } finally { await rm(temporary, { force: true }); }
+  }
+  await syncDirectory(bin);
+  return stablePaths(root);
+}

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

@@ -0,0 +1,60 @@
+import { randomUUID } from "node:crypto";
+import { readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { canonicalManagerRoot, managedDirectory, readControl, readManagedJson,
+  syncDirectory, validateRuntime, writeManagedJson } from "./state.mjs";
+import { confirmedDead, defaultPidIsAlive, withManagerLock } from "./mutex.mjs";
+
+/** Admission and lease publication must finish inside the pointer's mutex. */
+export async function acquireRuntime(root, { pid = process.pid, kind = "cli" } = {}) {
+  if (!Number.isSafeInteger(pid) || pid <= 0 || typeof kind !== "string" || !kind) {
+    throw new Error("invalid runtime lease identity");
+  }
+  root = await canonicalManagerRoot(root);
+  return withManagerLock(root, async () => {
+    const control = await readControl(root);
+    if (!control) throw new Error("managed runtime is not initialized");
+    if (control.phase !== "ready") throw new Error("managed runtime activation in progress");
+    // Ordinary admission also reaps dead processes when updates are off or no
+    // new version exists. Corrupt unrelated records remain a management hold,
+    // but must not introduce a new failure for ordinary runtime selection.
+    try { await listRuntimeHolds(root); } catch { /* Defer uncertain housekeeping. */ }
+    const lease = { schemaVersion: 1, token: randomUUID(), pid, kind,
+      runtime: control.active, createdAt: new Date().toISOString() };
+    const directory = path.join(root, "leases");
+    await managedDirectory(directory, { create: true });
+    await writeManagedJson(path.join(directory, `${lease.token}.json`), lease);
+    return lease;
+  });
+}
+
+/** Management decisions call this under withManagerLock to exclude admissions.
+ * Records are immutable and uniquely named; confirmed-dead cleanup also works
+ * outside a transaction. No release-on-return or timestamp expiry exists.
+ */
+export async function listRuntimeHolds(root, { pidIsAlive = defaultPidIsAlive } = {}) {
+  root = await canonicalManagerRoot(root);
+  if (!await managedDirectory(root)) return [];
+  const directory = path.join(root, "leases");
+  if (!await managedDirectory(directory)) return [];
+  const holds = [];
+  let removed = false;
+  for (const name of (await readdir(directory)).sort()) {
+    if (name.startsWith(".record-") && name.endsWith(".tmp")) continue;
+    if (!name.endsWith(".json")) throw new Error("invalid runtime lease file");
+    const file = path.join(directory, name);
+    const lease = await readManagedJson(file);
+    if (lease === undefined) continue;
+    if (!lease || lease.schemaVersion !== 1 || !Number.isSafeInteger(lease.pid) || lease.pid <= 0
+      || typeof lease.token !== "string" || name !== `${lease.token}.json`
+      || typeof lease.kind !== "string" || !lease.kind
+      || !Number.isFinite(Date.parse(lease.createdAt))) throw new Error("invalid runtime lease");
+    await validateRuntime(root, lease.runtime);
+    if (await confirmedDead(lease.pid, pidIsAlive)) {
+      await rm(file, { force: true });
+      removed = true;
+    } else holds.push(lease);
+  }
+  if (removed) await syncDirectory(directory);
+  return holds;
+}

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

@@ -0,0 +1,55 @@
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { canonicalManagerRoot } from "./state.mjs";
+
+const contains = (root, target) => {
+  const relative = path.relative(root, target);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+async function exists(file) {
+  try { await lstat(file); return true; }
+  catch (error) { if (error.code === "ENOENT") return false; throw error; }
+}
+async function markedRoots(start) {
+  const roots = new Set();
+  for (let directory = start;; directory = path.dirname(directory)) {
+    if (await exists(path.join(directory, ".git"))) roots.add(directory);
+    const config = path.join(directory, "acc.workspace.json");
+    if (await exists(config)) {
+      roots.add(directory);
+      // Installation does not consume workspace config. A malformed optional
+      // file cannot prevent an external install, but its marker still counts.
+      let declared;
+      try { declared = JSON.parse(await readFile(config, "utf8")); } catch { /* Marker only. */ }
+      for (const root of Array.isArray(declared?.roots) ? declared.roots : []) {
+        if (typeof root === "string") roots.add(await canonicalManagerRoot(path.resolve(directory, root)));
+      }
+    }
+    if (path.dirname(directory) === directory) return roots;
+  }
+}
+
+/** Read-only admission for installation, independent of Git or workspace stores. */
+export async function validateManagedLocation({ managerRoot, dataHome, cwd = process.cwd(), home, env = {} }) {
+  const root = await canonicalManagerRoot(managerRoot);
+  // The install ledger uses the configured data home, while runtime staging
+  // uses the resolved manager. A symlink can put either destination elsewhere.
+  dataHome = await canonicalManagerRoot(dataHome ?? path.dirname(path.dirname(managerRoot)));
+  const start = await canonicalManagerRoot(env.ACC_WORKSPACE_ROOT || path.resolve(cwd));
+  const roots = await markedRoots(dataHome);
+  for (const directory of [root, start]) {
+    for (const marked of await markedRoots(directory)) roots.add(marked);
+  }
+  const homes = await Promise.all([home, env.HOME].filter(value => typeof value === "string")
+    .map(value => canonicalManagerRoot(path.resolve(value))));
+  // HOME and filesystem root are installation launch locations, unless the
+  // user explicitly declares them as workspaces or a filesystem marker does.
+  if (env.ACC_WORKSPACE_ROOT || !homes.includes(start) && path.dirname(start) !== start) roots.add(start);
+  if ([...roots].some(workspace => contains(workspace, dataHome) || contains(workspace, root))) {
+    throw new Error("ACC data home must be outside every repository or workspace");
+  }
+  if (root !== path.join(dataHome, "acc", "runtime")) {
+    throw new Error("ACC cannot relocate only its runtime; relocate the entire data home with ACC_DATA_HOME");
+  }
+  return root;
+}

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

@@ -0,0 +1,145 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { canonicalManagerRoot, managedDirectory, readManagedJson, syncDirectory, writeManagedJson } from "./state.mjs";
+
+export function defaultPidIsAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code !== "ESRCH"; }
+}
+
+export async function confirmedDead(pid, pidIsAlive = defaultPidIsAlive) {
+  try { return await pidIsAlive(pid) === false; }
+  catch (error) { return error.code === "ESRCH"; }
+}
+
+const identity = owner => createHash("sha256")
+  .update(JSON.stringify([owner.pid, owner.token, owner.acquiredAt])).digest("hex");
+
+async function lockDirectoryIdentity(directory) {
+  try {
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("manager lock is not a regular directory");
+    return info;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function validOwner(owner) {
+  return owner && Number.isSafeInteger(owner.pid) && owner.pid > 0
+    && typeof owner.token === "string" && owner.token
+    && typeof owner.acquiredAt === "string" && Number.isFinite(Date.parse(owner.acquiredAt));
+}
+
+async function readOwner(directory) {
+  const before = await lockDirectoryIdentity(directory);
+  if (!before) return null;
+  const owner = await readManagedJson(path.join(directory, "owner.json"));
+  const after = await lockDirectoryIdentity(directory);
+  // Publication and retirement replace the entire directory. Missing owner
+  // bytes only prove corruption when both observations refer to the same lock.
+  if (!after || before.dev !== after.dev || before.ino !== after.ino) return null;
+  if (!validOwner(owner)) {
+    throw new Error("invalid manager lock owner; refusing to reclaim");
+  }
+  return owner;
+}
+
+async function retire(directory, target) {
+  try { await rename(directory, target); return true; }
+  catch (error) {
+    if (["ENOENT", "EEXIST", "ENOTEMPTY"].includes(error.code)) return false;
+    throw error;
+  }
+}
+
+/** Caller holds and has synced manager.lock. Every old-identity observer keeps
+ * its candidate through all awaited reads, probes and retirements. Validate the
+ * entire snapshot before deleting anything: a single unknown/live observer may
+ * still need any historical fence. Candidates published after admission can only
+ * observe this holder, whose future release tombstone is absent from the snapshot.
+ */
+async function compactQuiescentLocks(root, pidIsAlive) {
+  try {
+    const names = await readdir(root);
+    const dead = [];
+    for (const name of names.filter(name => name.startsWith("manager.candidate-"))) {
+      const match = /^manager\.candidate-([1-9]\d*)-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.lock$/.exec(name);
+      if (!match || !Number.isSafeInteger(Number(match[1]))) return;
+      const candidate = path.join(root, name);
+      if (!await lockDirectoryIdentity(candidate)) return;
+      const owner = await readManagedJson(path.join(candidate, "owner.json"));
+      if (owner !== undefined && (!validOwner(owner)
+        || owner.pid !== Number(match[1]) || owner.token !== match[2])) return;
+      if (!await confirmedDead(Number(match[1]), pidIsAlive)) return;
+      dead.push(candidate);
+    }
+    for (const name of names.filter(name => /^manager\.reclaimed-[0-9a-f]{64}\.lock$/.test(name))) {
+      const tombstone = path.join(root, name);
+      const owner = await readOwner(tombstone);
+      if (owner && name === `manager.reclaimed-${identity(owner)}.lock`) {
+        await rm(tombstone, { recursive: true, force: true });
+      }
+    }
+    for (const candidate of dead) await rm(candidate, { recursive: true, force: true });
+    await syncDirectory(root);
+  } catch {
+    // Maintenance is best effort. Unreadable/malformed preparation keeps the
+    // fences; housekeeping must never turn successful admission into failure.
+  }
+}
+
+/** Process death is the only expiry. Nonquiescent tombstones fence observers. */
+export async function withManagerLock(root, operation, { timeoutMs = 1000, pidIsAlive = defaultPidIsAlive } = {}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new Error("invalid manager lock timeout");
+  root = await canonicalManagerRoot(root);
+  await managedDirectory(root, { create: true });
+  const directory = path.join(root, "manager.lock");
+  const owner = { pid: process.pid, token: randomUUID(), acquiredAt: new Date().toISOString() };
+  const candidate = path.join(root, `manager.candidate-${owner.pid}-${owner.token}.lock`);
+  await mkdir(candidate, { mode: 0o700 });
+  let owned = false;
+  try {
+    await writeManagedJson(path.join(candidate, "owner.json"), owner);
+    await syncDirectory(candidate);
+    // Budget contention after durable preparation; slow fsync is not another worker.
+    const deadline = performance.now() + timeoutMs;
+    while (performance.now() < deadline) {
+      const current = await readOwner(directory);
+      if (current) {
+        if (await confirmedDead(current.pid, pidIsAlive)) {
+          // Every observer of this dead owner uses the same nonempty target;
+          // retain it until quiescence so a late observer cannot retire a successor.
+          const tombstone = path.join(root, `manager.reclaimed-${identity(current)}.lock`);
+          if (await retire(directory, tombstone)) await syncDirectory(root);
+        }
+      } else {
+        try {
+          await rename(candidate, directory);
+          owned = true;
+          await syncDirectory(root);
+          await compactQuiescentLocks(root, pidIsAlive);
+          return await operation();
+        } catch (error) {
+          if (owned || !["EEXIST", "ENOTEMPTY"].includes(error.code)) throw error;
+        }
+      }
+      const remaining = deadline - performance.now();
+      if (remaining > 0) await new Promise(resolve => setTimeout(resolve, Math.min(10, remaining)));
+    }
+    throw new Error("manager lock held; acquisition timeout");
+  } finally {
+    if (owned) {
+      const current = await readOwner(directory);
+      if (current?.token === owner.token) {
+        // A release tombstone also fences observers that inspected this owner
+        // before release and resume after a successor has been published.
+        const released = path.join(root, `manager.reclaimed-${identity(owner)}.lock`);
+        if (await retire(directory, released)) await syncDirectory(root);
+      }
+    } else await rm(candidate, { recursive: true, force: true });
+  }
+}

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

@@ -0,0 +1,4 @@
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const networkDisabled = env => !!env?.ACC_NO_UPDATE_CHECK && env.ACC_NO_UPDATE_CHECK !== "0";
+export const checkDue = control => !Number.isFinite(Date.parse(control.checkedAt))
+  || Date.now() - Date.parse(control.checkedAt) >= CHECK_INTERVAL_MS;

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

@@ -0,0 +1,40 @@
+import path from "node:path";
+import { applyPlan, detectInstallation, livePolicyOf, loadOwnership, planInstallation, shellOf }
+  from "@agents-can-communicate/installer";
+import { ALL_ADAPTERS, clientContext, probeTimeout } from "../install-command.mjs";
+import { stablePaths, writeLaunchers } from "./launchers.mjs";
+
+/** Loaded from the candidate, so its own adapters supply its integration bytes. */
+export async function prepareRefresh({ control, root, env = process.env }) {
+  const dataHome = path.dirname(path.dirname(root));
+  const wanted = new Set(control.targets);
+  const adapters = ALL_ADAPTERS().filter(adapter => wanted.has(adapter.id));
+  if (adapters.length !== wanted.size) throw new Error("candidate cannot refresh every installed integration");
+  const context = { ...clientContext(control.home, path.join(dataHome, "acc"),
+    { env, shell: shellOf(env), dataHome }), ...stablePaths(root), preserveVersions: true };
+  const recorded = (await loadOwnership({ dataHome })).installs;
+  const detected = await detectInstallation({ adapters, context, probeTimeoutMs: probeTimeout(env) });
+  const deliveryByAdapter = Object.fromEntries(adapters.map(adapter => [adapter.id,
+    livePolicyOf(recorded.find(record => record.adapterId === adapter.id))]));
+  // An unavailable probe cannot silently revoke an existing native opt-in.
+  for (const detection of detected) {
+    if (deliveryByAdapter[detection.adapterId] !== "off" && detection.nativeDelivery?.state !== "eligible") {
+      throw new Error("native integration could not be verified; update remains pending");
+    }
+  }
+  const plan = planInstallation({ adapters, detected, context, recorded,
+    accVersion: control.pending.version, requested: control.targets, deliveryByAdapter });
+  if (plan.skipped.length || plan.operations.length !== wanted.size) {
+    throw new Error("candidate did not plan every installed integration");
+  }
+  return async () => {
+    await writeLaunchers(root, control.pending.root);
+    const result = await applyPlan({ plan, adapters, context, dataHome, accVersion: control.pending.version,
+      activation: { bootstrap: context.bootstrap } });
+    return { ...result, failed: result.failed.map(failure => ({ ...failure,
+      paths: plan.operations.find(operation => operation.adapterId === failure.adapterId)
+        ?.artifacts?.map(artifact => artifact.path).filter(file => typeof file === "string") ?? [],
+    })) };
+
+  };
+}

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

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { confirmedDead } from "./mutex.mjs";
+import { readManagedJson } from "./state.mjs";
+import { checkDue, networkDisabled } from "./policy.mjs";
+
+/** No network waits here: this only starts an independent background process. */
+export async function scheduleWorker(root, control, { env = process.env } = {}) {
+  if (!control?.auto || networkDisabled(env) || !control.pending && !checkDue(control)) return false;
+  try {
+    const owner = await readManagedJson(path.join(root, "worker", "manager.lock", "owner.json"));
+    if (Number.isSafeInteger(owner?.pid) && !await confirmedDead(owner.pid)) return false;
+    const child = spawn(process.execPath,
+      [path.join(control.active.root, "bin", "acc-update-worker.mjs"), root], {
+        env, detached: true, stdio: "ignore", cwd: root,
+      });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch { return false; }
+}