agents-can-communicate 0.4.4 → 0.5.0

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

@@ -3,6 +3,8 @@ import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm }
   from "node:fs/promises";
 import path from "node:path";
 
+import { attachStagingTemp, holdStagedGeneration, releaseStagingHold } from "./staging.mjs";
+
 const NAME = "agents-can-communicate";
 const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 
@@ -134,34 +136,51 @@ export async function stageOwnGeneration({ packageRoot, managerRoot }) {
   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-"));
+  // Held before the check that may return `target` unchanged (it can already
+  // be sitting on disk unprotected from an earlier run) and, on the staging
+  // path below, before the rename that makes a freshly built `target`
+  // visible at all: reclaim must never observe the directory without also
+  // observing why it exists. The caller now owns this hold - see its own
+  // `hold` on the returned value - and must release it on every exit from
+  // its own attempt, once the generation is either published or abandoned.
+  // A hold this function itself never hands off (because it throws instead
+  // of returning) is released here, in its own catch, rather than left for
+  // a confirmed-dead reap to eventually find.
+  const hold = await holdStagedGeneration({ root, generationRoot: target });
   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);
+    if (await existingMatches(target, files)) return { ...result, hold };
+    const staging = await mkdtemp(path.join(generations, ".staging-"));
+    try {
+      await attachStagingTemp(hold, staging);
+      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 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");
+        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, hold };
+    } finally {
+      await rm(staging, { recursive: true, force: true });
     }
-    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 });
+  } catch (error) {
+    await releaseStagingHold(hold);
+    throw error;
   }
 }

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

@@ -3,12 +3,15 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { declaredStoreVersion } from "./activation.mjs";
 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 { releaseStagingHold } from "./staging.mjs";
 import { withManagerLock } from "./mutex.mjs";
+import { retireManagedHolds } from "./retire.mjs";
 
 const exec = promisify(execFile);
 export async function verifyGeneration(runtime, { env = process.env } = {}) {
@@ -27,35 +30,44 @@ export async function verifyGeneration(runtime, { env = process.env } = {}) {
 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 autoPreference = previous?.autoPreference ?? previous?.auto ?? true;
-    // Full removal pauses workers without revoking the user's choice. Keep a
-    // partial-removal pause until explicit opt-in; this install may omit its failed target.
-    const auto = previous?.targets.length ? previous.auto : autoPreference;
-    const control = { schemaVersion: 1, active: runtime, pending: runtime, phase: "activating",
-      auto, autoPreference, 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;
-  });
+  // The hold candidate.hold carries survives verification and publication;
+  // release it on every exit from this attempt, once the generation is
+  // either published (independently protected by the control pointer this
+  // writes below) or abandoned (any throw between here and there).
+  try {
+    await verifyGeneration(candidate, { env });
+    return await 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,
+        storeVersion: await declaredStoreVersion(candidate.root) };
+      const autoPreference = previous?.autoPreference ?? previous?.auto ?? true;
+      // Full removal pauses workers without revoking the user's choice. Keep a
+      // partial-removal pause until explicit opt-in; this install may omit its failed target.
+      const auto = previous?.targets.length ? previous.auto : autoPreference;
+      const control = { schemaVersion: 1, active: runtime, pending: runtime, phase: "activating",
+        auto, autoPreference, 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;
+    });
+  } finally {
+    await releaseStagingHold(candidate.hold);
+  }
 }
 
 /** Removal updates enrollment under the same fence, so an updater cannot reinstall it. */
@@ -69,6 +81,11 @@ export async function uninstallManaged({ managerRoot, apply }) {
     const removed = new Set(result.operations.filter(operation => operation.applied)
       .map(operation => operation.adapterId));
     const targets = control.targets.filter(id => !removed.has(id));
+    // Holds this install published must stop blocking a later activation. The
+    // client processes keep running; only the records ACC owns are retired.
+    if (targets.length === 0) {
+      await retireManagedHolds({ root, workspaces: path.join(path.dirname(root), "workspaces") });
+    }
     await writeControl(root, { ...control, targets,
       autoPreference: control.autoPreference ?? control.auto,
       auto: targets.length > 0 && result.failed.length === 0 && control.auto,

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

@@ -50,7 +50,7 @@ export function maintenanceNotice(job) {
       : job.waiting?.reason === "other_processes" ? `${job.waiting.processes} other or unidentified process(es) to exit`
         : job.waiting?.reason === "caller_exit" ? "the requesting command to exit"
           : job.waiting?.reason === "update_worker" ? "another ACC updater"
-            : "idle clients and other ACC processes to exit";
+            : "idle client work and any ACC process still holding this update";
     return `ACC ${version} update maintenance is scheduled; waiting for ${waiting}. Open clients will disconnect during restart. Check acc doctor for progress.`;
   }
   return `ACC ${version} update maintenance: ${job.status}. Check acc doctor for the result.`;

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

@@ -71,7 +71,15 @@ export async function runMaintenance(root, { jobId, env = process.env, adapters
         result = await withManagerLock(`${root}/worker`, async () => {
           const beforeActivation = async current => {
             if (maintenanceRecipe(current) !== job.recipe) throw refused("update_state_changed");
-            const blockers = await listActivationBlockers(root, { pidIsAlive });
+            // Same fallback as maintenance.mjs's own target: judge other
+            // holds against the pending generation's contract when one is
+            // being activated, otherwise against the generation already
+            // running, since there is no incoming generation to compare to.
+            // Pick the whole generation record, not a per-field fallback, so
+            // a pending generation declaring no contract of its own is
+            // judged as "none" rather than silently borrowing active's.
+            const blockers = await listActivationBlockers(root, { pidIsAlive,
+              incomingStoreVersion: (current.pending ?? current.active).storeVersion });
             const others = blockers.filter(b => b.pid !== expected.pid || b.kinds.some(kind => kind !== "native"));
             if (others.length) throw deferred({ reason: "other_processes", processes: others.length });
             const snapshot = await adapter.inspectMaintenance(context);

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

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
+import { evaluateVersionContract } from "@agents-can-communicate/adapter-sdk";
 import { ALL_ADAPTERS } from "../install-command.mjs";
 import { listActivationBlockers } from "./activation.mjs";
 import { confirmedDead, withManagerLock } from "./mutex.mjs";
@@ -8,17 +9,64 @@ import { readControl, readManagedJson } from "./state.mjs";
 import { MAINTENANCE_ACTIVE, maintenanceNotice, maintenanceRecipe, maintenanceReport,
   readMaintenance, writeMaintenance } from "./maintenance-state.mjs";
 
+const HOST_PLATFORM = `${process.platform}-${process.arch}`;
+
 export function maintenanceContext(control, env) {
-  return { home: control.home, env, platform: `${process.platform}-${process.arch}` };
+  return { home: control.home, env, platform: HOST_PLATFORM };
 }
 
+/** The fifth site that used to compare a service's serving version with the
+ * CLI's, and the only one that acts on the answer by interrupting the user.
+ * The other four now judge the serving version against the adapter's captured
+ * native-delivery contract, and this one has to say the same thing: a Codex
+ * daemon still running the previous build while its CLI has updated is the
+ * ordinary state this release stops treating as a fault, and telling that user
+ * a restart is required - disconnecting every open client - is the complaint
+ * the work began from.
+ *
+ * A restart is still offered whenever the serving version does *not* satisfy
+ * that contract: below the captured minimum, on the denylist, a prerelease, or
+ * unreadable. Only a version the contract actually accepts stops being a
+ * reason on its own - and the native-binding blocker it is OR-ed with is
+ * untouched, so a genuinely stale or unbound service is still selected.
+ *
+ * The contract answers two different questions with one field, and reading
+ * every non-null code as a refusal conflated them. "platform_not_captured" and
+ * "native_delivery_unsupported" are not verdicts on any version: the first is
+ * a complete, valid declaration that records nothing for the platform this
+ * process runs on, and the second is an adapter that declares no native
+ * delivery at all. Every shipped adapter captures darwin-arm64 alone, so on
+ * Linux and on an Intel Mac the first of those is the ordinary answer - and it
+ * made every ready daemon a restart candidate, including one already serving
+ * exactly the version its CLI is running. That is the complaint this work
+ * began from, reproduced on every machine but one. With no opinion to act on,
+ * the decision falls back to the comparison that governed before this branch:
+ * the served version against the CLI's. */
+const UNCAPTURED = new Set(["platform_not_captured", "native_delivery_unsupported"]);
+
+const servingVersionIsContrary = (adapter, snapshot) => {
+  const { reasonCode } = evaluateVersionContract(adapter,
+    { clientVersion: snapshot.serverVersion, platform: HOST_PLATFORM });
+  if (reasonCode === null) return false;
+  if (!UNCAPTURED.has(reasonCode)) return true;
+  return snapshot.serverVersion !== snapshot.cliVersion;
+};
+
 export async function inspectMaintenanceServices({ control, env = process.env, root, adapters = ALL_ADAPTERS() }) {
-  const blockers = await listActivationBlockers(root, { ignorePid: process.pid });
+  // Maintenance targets the pending generation when one exists (its contract
+  // is what activation will judge holds against), otherwise the active one:
+  // there is no incoming generation, only a stale daemon to bring in line
+  // with what is already running. Same fallback as this file's own `target`
+  // below: pick the whole generation record, not a per-field fallback, so a
+  // pending generation that declares no contract of its own is judged as
+  // "none" and not silently swapped for the active generation's.
+  const blockers = await listActivationBlockers(root, { ignorePid: process.pid,
+    incomingStoreVersion: (control.pending ?? control.active).storeVersion });
   const services = [];
   for (const adapter of adapters.filter(a => control.targets.includes(a.id) && a.inspectMaintenance)) {
     const snapshot = await adapter.inspectMaintenance(maintenanceContext(control, env));
     if (!snapshot || !["ready", "busy"].includes(snapshot.state)) continue;
-    if (snapshot.serverVersion !== snapshot.cliVersion
+    if (servingVersionIsContrary(adapter, snapshot)
       || blockers.some(b => b.pid === snapshot.pid && b.kinds.includes("native"))) {
       services.push({ adapterId: adapter.id, snapshot });
     }
@@ -75,7 +123,7 @@ export async function requestMaintenance({ root, control, options, runtime, serv
     const approved = await runtime.confirm?.(`Restart ${names} to finish updating ACC? Open clients will disconnect; ACC will wait for idle turns, refresh integrations, restart the service and verify it. A turn started during the final restart check can be interrupted.`,
       { input: runtime.input, output: runtime.output });
     if (approved !== true) return { data: { reason: "maintenance_declined" },
-      text: "Client restart declined; the update remains pending until running clients exit." };
+      text: "Client restart declined; the update remains pending until the holds blocking it clear." };
   }
   return withManagerLock(root, async () => {
     const current = await readControl(root), previous = await readMaintenance(root);

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

@@ -1,11 +1,13 @@
 import { execFile } from "node:child_process";
 import path from "node:path";
 import { promisify } from "node:util";
+import { declaredStoreVersion } from "./activation.mjs";
 import { newerVersion } from "./download.mjs";
 import { stageOwnGeneration } from "./generation.mjs";
 import { verifyGeneration } from "./install.mjs";
 import { confirmedDead, withManagerLock } from "./mutex.mjs";
 import { readControl, readManagedJson, writeControl } from "./state.mjs";
+import { releaseStagingHold } from "./staging.mjs";
 
 /** A newly installed global CLI can supersede an older pending release locally.
  * No workspace code or integration is admitted until normal activation passes.
@@ -18,15 +20,22 @@ export async function stageNewerManagementRuntime(root, { packageRoot, env }) {
     || manifest.accManagedUpdateProtocol !== 2 || before.pin && before.pin !== manifest.version
     || !newerVersion(manifest.version, before.pending?.version ?? before.active.version)) return false;
   const candidate = await stageOwnGeneration({ packageRoot, managerRoot: root });
-  await verifyGeneration(candidate, { env });
-  return withManagerLock(root, async () => {
-    const current = await readControl(root);
-    if (current.phase !== "ready" || current.pin !== before.pin
-      || JSON.stringify([current.active, current.pending]) !== JSON.stringify([before.active, before.pending])) return false;
-    await writeControl(root, { ...current, pending: { root: candidate.root, version: candidate.version },
-      notice: `ACC ${candidate.version} is verified and ready to activate.` });
-    return true;
-  });
+  // See installManaged for why this releases only after the publish attempt
+  // - success or not - has fully resolved.
+  try {
+    await verifyGeneration(candidate, { env });
+    return await withManagerLock(root, async () => {
+      const current = await readControl(root);
+      if (current.phase !== "ready" || current.pin !== before.pin
+        || JSON.stringify([current.active, current.pending]) !== JSON.stringify([before.active, before.pending])) return false;
+      await writeControl(root, { ...current, pending: { root: candidate.root,
+        version: candidate.version, storeVersion: await declaredStoreVersion(candidate.root) },
+        notice: `ACC ${candidate.version} is verified and ready to activate.` });
+      return true;
+    });
+  } finally {
+    await releaseStagingHold(candidate.hold);
+  }
 }
 
 async function inspectWorker(pid) {

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

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+import { access, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { STORE_VERSION } from "@agents-can-communicate/storage-filesystem";
+
+import { confirmedDead, defaultPidIsAlive } from "./mutex.mjs";
+import { canonicalManagerRoot, managedDirectory, readManagedJson, syncDirectory, validateRuntime,
+  writeManagedJson } from "./state.mjs";
+
+const SCHEMA_VERSION = 1;
+
+// Same hashing rule as session bindings: a foreign harness id never selects
+// which file is written.
+const fileFor = (root, harnessSessionId) => path.join(root, "pins",
+  `${createHash("sha256").update(String(harnessSessionId)).digest("hex").slice(0, 32)}.json`);
+
+// Where a generation's own hook lives, given its root. Computed once here and
+// reused by every caller that needs it - a hook resolving a pin and the hook
+// actually importing it - so the path checked and the path imported can never
+// drift apart.
+export const hookEntrypointFor = root => path.join(root, "bin", "entrypoints", "acc-hook.mjs");
+
+// Every function below takes whatever `root` its caller happens to have -
+// `entry.mjs` already canonicalises it before a hook ever sees it, but the
+// hook-runner writes a pin from a raw data-home path it built itself. If only
+// one side resolved symlinks, a symlinked data home would make the writer and
+// the reader agree on the file's *name* but not its *location*: delegation
+// would silently never fire, with no error anywhere. Canonicalising here,
+// once, on every entry point - matching every other managed-runtime module -
+// is what makes "the root the writer used" and "the root the reader used"
+// the same derivation instead of two that merely happen to agree today.
+export async function writePin({ root, harnessSessionId, runtimeRoot, version, storeVersion,
+  clientPid }) {
+  root = await canonicalManagerRoot(root);
+  await managedDirectory(path.join(root, "pins"), { create: true });
+  await writeManagedJson(fileFor(root, harnessSessionId), { schemaVersion: SCHEMA_VERSION,
+    harnessSessionId, runtimeRoot, version, storeVersion: storeVersion ?? null,
+    clientPid: clientPid ?? null, createdAt: new Date().toISOString() });
+}
+
+export async function readPin({ root, harnessSessionId }) {
+  root = await canonicalManagerRoot(root);
+  // Mirrors reapPins: an internal symlink swapped in for the pins directory
+  // must not be followed into silently, whether writing or reading.
+  if (!await managedDirectory(path.join(root, "pins"))) return null;
+  const record = await readManagedJson(fileFor(root, harnessSessionId)).catch(() => null);
+  if (!record || record.schemaVersion !== SCHEMA_VERSION
+    || typeof record.runtimeRoot !== "string" || record.runtimeRoot === "") return null;
+  return record;
+}
+
+export async function clearPin({ root, harnessSessionId }) {
+  root = await canonicalManagerRoot(root);
+  await rm(fileFor(root, harnessSessionId), { force: true });
+}
+
+/** Returns the pinned generation's root when a hook should delegate to it,
+ * and null when it should stay on the active generation. Resolution never
+ * throws: a hook that cannot resolve a pin must still let the client
+ * proceed, so every reason to say no - no pin, an already-active pin, a
+ * pinned generation outside the manager's own `generations` directory, one
+ * missing its own hook entrypoint, a pin declaring a store contract this
+ * generation does not speak, a store that will not read - collapses to the
+ * same null.
+ *
+ * Containment reuses `validateRuntime`, the same rule a control record's own
+ * generation pointer is held to, rather than trusting a pin's `runtimeRoot`
+ * on its word: a pin can be written by an unmanaged hook run sharing a data
+ * home (a development checkout is its own nearest `accStoreVersion`
+ * manifest), and importing whatever such a pin names would run this
+ * process's code from outside the runtime it was admitted into.
+ *
+ * The contract gate is the one check that is not about the pin being
+ * resolvable. A pin is deliberately not an activation hold, so a harness that
+ * lives only in hooks - no native binding, no long-lived channel process -
+ * holds nothing between turns and cannot keep an activation waiting. When
+ * that activation moves to a generation declaring a different
+ * `STORE_VERSION`, the pin survives it, and delegating to the generation it
+ * names would run code whose contract the store refuses by strict equality:
+ * the session would throw `unknown store version` on every hook and fall open
+ * for the rest of its life, silently uncoordinated, while its pin held the
+ * dead generation against reclamation. `STORE_VERSION` here is this
+ * generation's own declared contract - this module is loaded from the active
+ * generation, and its root manifest's `accStoreVersion` is asserted equal to
+ * this constant - so comparing against it compares the pin with the
+ * generation that would otherwise serve. Anything but proven equality (a
+ * differing contract, or a pin that declares none) falls back to the active
+ * generation, which is this function's answer to every other pin it cannot
+ * honour. That keeps the design's stated limit intact: a `STORE_VERSION`
+ * change still requires every live process to exit. */
+export async function resolvePinnedGeneration({ root, harnessSessionId, active }) {
+  try {
+    const canonicalRoot = await canonicalManagerRoot(root);
+    const pin = await readPin({ root: canonicalRoot, harnessSessionId });
+    if (pin === null) return null;
+    const { root: resolved, storeVersion } = await validateRuntime(canonicalRoot,
+      { version: pin.version, root: pin.runtimeRoot, storeVersion: pin.storeVersion });
+    if (storeVersion !== STORE_VERSION) return null;
+    const canonicalActive = typeof active === "string" ? await canonicalManagerRoot(active) : active;
+    if (resolved === canonicalActive) return null;
+    await access(hookEntrypointFor(resolved));
+    return resolved;
+  } catch { return null; }
+}
+
+/** A client that exits without SessionEnd leaves its pin behind. Admission
+ * already reaps dead leases; pins follow the same confirmed-death rule. */
+export async function reapPins({ root, pidIsAlive = defaultPidIsAlive } = {}) {
+  root = await canonicalManagerRoot(root);
+  const directory = path.join(root, "pins");
+  if (!await managedDirectory(directory)) return;
+  let removed = false;
+  for (const name of await readdir(directory)) {
+    if (!name.endsWith(".json")) continue;
+    const file = path.join(directory, name);
+    const record = await readManagedJson(file).catch(() => null);
+    const pid = Number.isSafeInteger(record?.clientPid) ? record.clientPid : null;
+    if (pid !== null && await confirmedDead(pid, pidIsAlive)) {
+      await rm(file, { force: true });
+      removed = true;
+    }
+  }
+  if (removed) await syncDirectory(directory);
+}

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

@@ -0,0 +1,56 @@
+import { readdir, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { managedDirectory, readManagedJson, syncDirectory } from "./state.mjs";
+
+// A relative runtimeRoot resolves against the caller's cwd, not this manager's
+// own root, so it can never be owned regardless of where acc uninstall runs
+// from. The generations directory itself is a container, not a generation, so
+// an exact match (empty relative) is foreign too. On Windows, path.relative
+// returns an absolute path when the two roots sit on different drives, which
+// is foreign by construction. This matches every case validateRuntime
+// (state.mjs) applies to a control pointer. pathImpl is injectable only so a
+// test can pin the cross-drive case through path.win32 without depending on
+// the host OS; production code always uses the real, platform-native path.
+export function isOwnedRuntimeRoot(generations, runtimeRoot, pathImpl = path) {
+  if (typeof runtimeRoot !== "string" || !pathImpl.isAbsolute(runtimeRoot)) return false;
+  const relative = pathImpl.relative(generations, runtimeRoot);
+  return relative !== "" && relative !== ".." && !relative.startsWith(`..${pathImpl.sep}`)
+    && !pathImpl.isAbsolute(relative);
+}
+
+/** Uninstall owns what it published. A binding naming a generation under this
+ * manager is ours; one naming a foreign root, or none at all, is not, and a
+ * client process is never signalled or terminated to clear a record. */
+export async function retireManagedHolds({ root, workspaces }) {
+  const generations = path.join(root, "generations");
+  const counts = { bindings: 0, pins: 0 };
+  if (await managedDirectory(workspaces)) {
+    for (const entry of await readdir(workspaces, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const directory = path.join(workspaces, entry.name, "bindings");
+      if (!await managedDirectory(directory)) continue;
+      let removed = false;
+      for (const name of await readdir(directory)) {
+        if (!name.endsWith(".json")) continue;
+        const file = path.join(directory, name);
+        const record = await readManagedJson(file).catch(() => null);
+        if (!isOwnedRuntimeRoot(generations, record?.runtimeRoot)) continue;
+        await rm(file, { force: true });
+        counts.bindings += 1;
+        removed = true;
+      }
+      if (removed) await syncDirectory(directory);
+    }
+  }
+  const pins = path.join(root, "pins");
+  if (await managedDirectory(pins)) {
+    for (const name of await readdir(pins)) {
+      if (!name.endsWith(".json")) continue;
+      await rm(path.join(pins, name), { force: true });
+      counts.pins += 1;
+    }
+    await syncDirectory(pins);
+  }
+  return counts;
+}

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

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import { readdir, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { confirmedDead, defaultPidIsAlive } from "./mutex.mjs";
+import { canonicalManagerRoot, managedDirectory, readManagedJson, syncDirectory, writeManagedJson } from "./state.mjs";
+
+const SCHEMA_VERSION = 1;
+
+/** Staging renames a fully-formed generation into place, then runs it as a
+ * spawned process to verify it, before any control pointer, lease, or pin
+ * can reference it - out of the manager lock, since verification can run for
+ * several seconds and holding the lock that long would stall every hook on
+ * the machine. This hold closes that window: the caller writes it for the
+ * generation's final path *before* either the check that may return that
+ * path unchanged, or the rename that makes a freshly staged one visible
+ * there - so the directory can never be observed without it.
+ *
+ * Returns the hold's own file path: an opaque handle for attachStagingTemp
+ * and releaseStagingHold. The caller owns its lifecycle end to end - this
+ * function never releases what it creates. */
+export async function holdStagedGeneration({ root, generationRoot, stagingRoot = null, pid = process.pid }) {
+  const directory = path.join(root, "staging");
+  await managedDirectory(directory, { create: true });
+  const file = path.join(directory, `${randomUUID()}.json`);
+  await writeManagedJson(file, { schemaVersion: SCHEMA_VERSION, generationRoot, stagingRoot, pid,
+    createdAt: new Date().toISOString() });
+  return file;
+}
+
+/** Once mkdtemp names the actual in-flight temp, attach it to the same
+ * record a live hold already protects: a dead owner's abandoned temp is
+ * only ever found by way of this link, since reclaim never otherwise looks
+ * at a dot-prefixed generations entry.
+ *
+ * If the hold has already vanished (readManagedJson returns undefined on
+ * ENOENT), do nothing rather than write `{ stagingRoot }` alone: spreading
+ * an `undefined` record silently produces exactly the schemaVersion-less,
+ * generationRoot-less, pid-less fragment reclaimGenerations reads as a
+ * malformed hold - and reapStagingHolds can never reap it either, since it
+ * has no valid pid to confirm dead. Manufacturing that record would be a
+ * self-inflicted, permanent block on reclamation, not a corruption that
+ * needed an external cause. */
+export async function attachStagingTemp(file, stagingRoot) {
+  const record = await readManagedJson(file);
+  if (record === undefined) return;
+  await writeManagedJson(file, { ...record, stagingRoot });
+}
+
+/** The caller must call this on every exit from its own staging attempt -
+ * success, a failed verify, a timeout, or a thrown error - once the
+ * generation is either published (and so independently protected by the
+ * control pointer) or abandoned. Confirmed-dead reaping is the backstop for
+ * a crash that skips this, never the release mechanism itself. */
+export async function releaseStagingHold(file) {
+  if (typeof file === "string" && file) await rm(file, { force: true });
+}
+
+const nonempty = value => typeof value === "string" && value.length > 0;
+
+/** A staging process that exits without releasing its hold (crash, kill, a
+ * SIGKILL mid-verify) leaves both the hold and, if it had gotten that far,
+ * its in-flight temp behind - the only sweeper either one ever gets. Same
+ * confirmed-death rule as reapPins. The temp is only ever removed alongside
+ * its owning record, and only after it is confirmed to sit directly inside
+ * this root's own `generations`, named the way mkdtemp names one: a corrupt
+ * or foreign path in the record must never turn a reap into an arbitrary
+ * delete. */
+export async function reapStagingHolds({ root, pidIsAlive = defaultPidIsAlive } = {}) {
+  root = await canonicalManagerRoot(root);
+  const directory = path.join(root, "staging");
+  if (!await managedDirectory(directory)) return;
+  const generations = path.join(root, "generations");
+  let removed = false;
+  for (const name of await readdir(directory)) {
+    if (!name.endsWith(".json")) continue;
+    const file = path.join(directory, name);
+    const record = await readManagedJson(file).catch(() => null);
+    const pid = Number.isSafeInteger(record?.pid) ? record.pid : null;
+    if (pid !== null && await confirmedDead(pid, pidIsAlive)) {
+      if (nonempty(record.stagingRoot)) {
+        // Resolved the same way every generations entry is (see
+        // resolveCandidate in activation.mjs): a symlinked data home must
+        // never make a real temp look foreign, or a foreign path look real.
+        const resolved = await canonicalManagerRoot(record.stagingRoot).catch(() => null);
+        if (resolved && path.dirname(resolved) === generations && path.basename(resolved).startsWith(".staging-")) {
+          await rm(resolved, { recursive: true, force: true });
+        }
+      }
+      await rm(file, { force: true });
+      removed = true;
+    }
+  }
+  if (removed) await syncDirectory(directory);
+}