agents-can-communicate 0.4.3 → 0.5.0

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

@@ -0,0 +1,140 @@
+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";
+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: 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() }) {
+  // 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 (servingVersionIsContrary(adapter, snapshot)
+      || blockers.some(b => b.pid === snapshot.pid && b.kinds.includes("native"))) {
+      services.push({ adapterId: adapter.id, snapshot });
+    }
+  }
+  return services;
+}
+
+export async function spawnMaintenance({ root, job, packageRoot, env }) {
+  packageRoot = job.workerRoot ?? packageRoot;
+  const manifest = await readManagedJson(path.join(packageRoot, "package.json"));
+  if (manifest?.name !== "agents-can-communicate" || manifest.accManagedUpdateProtocol !== 2) {
+    throw new Error("maintenance worker implementation is unavailable");
+  }
+  const child = spawn(process.execPath, [path.join(packageRoot, "bin", "acc-maintenance-worker.mjs"), root, job.id],
+    { env, cwd: root, detached: true, stdio: "ignore" });
+  await new Promise((resolve, reject) => { child.once("spawn", resolve); child.once("error", reject); });
+  child.unref();
+  return child.pid;
+}
+
+const response = job => ({ data: { reason: "maintenance_pending", maintenance: maintenanceReport(job) }, text: maintenanceNotice(job) });
+
+async function launch(root, job, runtime) {
+  if (job.workerPid !== null && !await confirmedDead(job.workerPid)) return job;
+  try {
+    // The child reads after publication; a separate lifetime lock prevents a
+    // second command from creating two workers or overwriting its checkpoint.
+    const workerPid = await (runtime.spawnMaintenance ?? spawnMaintenance)({ root, job,
+      packageRoot: runtime.packageRoot, env: runtime.env ?? process.env });
+    return writeMaintenance(root, { ...job, workerPid });
+  } catch {
+    return writeMaintenance(root, { ...job, status: job.attempted.length ? "recovery" : "failed",
+      reasonCode: "maintenance_worker_start_failed" });
+  }
+}
+
+/** Explicit command only. Background inspection never grants restart consent. */
+export async function requestMaintenance({ root, control, options, runtime, services }) {
+  const existing = await readMaintenance(root);
+  if (existing && MAINTENANCE_ACTIVE.includes(existing.status)) {
+    return withManagerLock(root, async () => {
+      const latest = await readMaintenance(root);
+      if (!latest || !MAINTENANCE_ACTIVE.includes(latest.status)) return latest ? response(latest) : null;
+      return response(await launch(root, latest, runtime));
+    });
+  }
+  services ??= await inspectMaintenanceServices({ root, control, env: runtime.env, adapters: runtime.adapters });
+  if (services.length !== 1) return null; // More than one service needs a separate captured contract.
+  const names = services.map(s => s.snapshot.serviceId).join(", ");
+  if (!options.yes) {
+    if (options.json || runtime.isInteractive?.() !== true) return {
+      data: { reason: "confirmation_required", services: services.map(s => ({ adapterId: s.adapterId, serviceId: s.snapshot.serviceId })) },
+      text: `Finishing the update requires restarting ${names}, disconnecting open clients. Run acc update in a terminal to confirm, or acc update --yes to consent explicitly.` };
+    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 the holds blocking it clear." };
+  }
+  return withManagerLock(root, async () => {
+    const current = await readControl(root), previous = await readMaintenance(root);
+    if (previous && MAINTENANCE_ACTIVE.includes(previous.status)) return response(previous);
+    if (maintenanceRecipe(current) !== maintenanceRecipe(control)) return {
+      data: { reason: "state_changed" }, text: "Update settings changed before confirmation; run acc update again." };
+    const job = await writeMaintenance(root, { schemaVersion: 1, id: randomUUID(), status: "waiting",
+      target: current.pending ?? current.active, recipe: maintenanceRecipe(current), services,
+      workerRoot: runtime.packageRoot,
+      approvedAt: new Date().toISOString(), deadline: Date.now() + 15 * 60_000,
+      callerPid: process.pid, workerPid: null, attempted: [], reasonCode: null });
+    return response(await launch(root, job, runtime));
+  });
+}

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

@@ -0,0 +1,80 @@
+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.
+ */
+export async function stageNewerManagementRuntime(root, { packageRoot, env }) {
+  if (!packageRoot) return false;
+  const before = await readControl(root);
+  const manifest = await readManagedJson(path.join(packageRoot, "package.json"));
+  if (before?.phase !== "ready" || manifest?.name !== "agents-can-communicate"
+    || 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 });
+  // 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) {
+  try {
+    const { stdout } = await promisify(execFile)("/bin/ps", ["-p", String(pid), "-o", "uid=,lstart=,command="],
+      { timeout: 2000, maxBuffer: 16384 });
+    const match = /^\s*(\d+)\s+(.{24})\s+(.+)\s*$/.exec(stdout);
+    return match ? { uid: Number(match[1]), start: match[2], command: match[3] } : null;
+  } catch { return null; }
+}
+
+/** 0.4.2/0.4.3 kept this ACC-owned worker lock while sleeping indefinitely.
+ * Retire only an exactly identified old helper, under the admission mutex in
+ * ready phase. Never interrupt integration writes, a client, or an unknown PID.
+ */
+export async function retireLegacyUpdateWorker(root, { inspect = inspectWorker,
+  signal = pid => process.kill(pid, "SIGTERM"), pause = ms => new Promise(resolve => setTimeout(resolve, ms)) } = {}) {
+  return withManagerLock(root, async () => {
+    const control = await readControl(root);
+    if (control?.phase !== "ready") return false;
+    const manifest = await readManagedJson(path.join(control.active.root, "package.json"));
+    if (manifest?.accManagedUpdateProtocol === 2) return false;
+    const ownerFile = path.join(root, "worker", "manager.lock", "owner.json");
+    const owner = await readManagedJson(ownerFile);
+    if (!Number.isSafeInteger(owner?.pid) || owner.pid < 2 || owner.pid === process.pid
+      || typeof owner.token !== "string" || !Number.isFinite(Date.parse(owner.acquiredAt))) return false;
+    const observed = await inspect(owner.pid);
+    const suffix = ` ${path.join(control.active.root, "bin", "acc-update-worker.mjs")} ${root}`;
+    const executable = observed?.command.endsWith(suffix) ? observed.command.slice(0, -suffix.length) : null;
+    const elapsed = Date.parse(owner.acquiredAt) - Date.parse(observed?.start);
+    if (!executable || !path.isAbsolute(executable) || path.basename(executable) !== "node"
+      || observed.uid !== process.getuid?.() || !Number.isFinite(elapsed) || elapsed < 0 || elapsed > 60_000) return false;
+    if (JSON.stringify(await readManagedJson(ownerFile)) !== JSON.stringify(owner)
+      || JSON.stringify(await inspect(owner.pid)) !== JSON.stringify(observed)) return false;
+    signal(owner.pid);
+    for (let attempt = 0; attempt < 40; attempt++) {
+      if (await confirmedDead(owner.pid)) return true;
+      await pause(50);
+    }
+    return false; // Normal mutex reclamation still requires confirmed death.
+  });
+}

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/refresh.mjs

@@ -3,9 +3,11 @@ import { applyPlan, detectInstallation, livePolicyOf, loadOwnership, planInstall
   from "@agents-can-communicate/installer";
 import { ALL_ADAPTERS, clientContext, probeTimeout } from "../install-command.mjs";
 import { stablePaths, writeLaunchers } from "./launchers.mjs";
+import { bridgeLegacyMaintenance } from "./legacy-maintenance.mjs";
 
 /** Loaded from the candidate, so its own adapters supply its integration bytes. */
-export async function prepareRefresh({ control, root, env = process.env }) {
+export async function prepareRefresh({ control, root, env = process.env, callerProtocol = 1 }) {
+  await bridgeLegacyMaintenance({ control, root, env, callerProtocol });
   const dataHome = path.dirname(path.dirname(root));
   const wanted = new Set(control.targets);
   const adapters = ALL_ADAPTERS().filter(adapter => wanted.has(adapter.id));
@@ -16,12 +18,9 @@ export async function prepareRefresh({ control, root, env = process.env }) {
   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");
-    }
-  }
+  // Refresh configuration even when the client's service is temporarily absent.
+  // The installer preserves consent and existing activation; readiness stays a
+  // separate, current probe result rather than an update prerequisite.
   const plan = planInstallation({ adapters, detected, context, recorded,
     accVersion: control.pending.version, requested: control.targets, deliveryByAdapter });
   if (plan.skipped.length || plan.operations.length !== wanted.size) {

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/schedule.mjs

@@ -8,8 +8,10 @@ import { checkDue, networkDisabled } from "./policy.mjs";
 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;
+    for (const directory of [path.join(root, "worker"), path.join(root, "worker", "poller")]) {
+      const owner = await readManagedJson(path.join(directory, "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,

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

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

@@ -77,6 +77,13 @@ const nullableString = value => value === null || nonempty(value);
 export async function validateRuntime(root, runtime) {
   if (!runtime || !nonempty(runtime.version) || typeof runtime.root !== "string"
     || !path.isAbsolute(runtime.root)) throw new Error("invalid control generation");
+  // Absent means a pointer written before the contract field existed. Present
+  // but malformed is a corrupt record, and reading it as unknown would let an
+  // incompatible generation past the gate.
+  if (runtime.storeVersion !== undefined && runtime.storeVersion !== null
+    && (!Number.isSafeInteger(runtime.storeVersion) || runtime.storeVersion <= 0)) {
+    throw new Error("invalid control generation");
+  }
   const generations = path.join(root, "generations");
   const resolved = await canonicalManagerRoot(runtime.root);
   const relative = path.relative(generations, resolved);
@@ -88,7 +95,7 @@ export async function validateRuntime(root, runtime) {
   if (await managedDirectory(generations)) {
     if (await realpath(generations) !== generations) throw new Error("invalid control generations directory");
   }
-  return { version: runtime.version, root: resolved };
+  return { version: runtime.version, root: resolved, storeVersion: runtime.storeVersion ?? null };
 }
 
 async function validateControl(root, value) {

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

@@ -2,6 +2,9 @@ import { activatePending } from "./activation.mjs";
 import { downloadRelease, fetchRelease, newerVersion } from "./download.mjs";
 import { withManagerLock } from "./mutex.mjs";
 import { readControl, writeControl } from "./state.mjs";
+import { releaseStagingHold } from "./staging.mjs";
+import { MAINTENANCE_ACTIVE, maintenanceNotice, maintenanceReport, readMaintenance } from "./maintenance-state.mjs";
+import { requestMaintenance } from "./maintenance.mjs";
 
 import { checkDue, networkDisabled } from "./policy.mjs";
 export { CHECK_INTERVAL_MS, networkDisabled } from "./policy.mjs";
@@ -14,6 +17,14 @@ export async function performUpdate(root, { force = false, check = false, env =
   if (initial === null) throw new Error("ACC is not enrolled; run acc install first");
   const data = { running: initial.active.version, auto: initial.auto, pin: initial.pin,
     pending: initial.pending?.version ?? null, notice: initial.notice };
+  const maintenance = await readMaintenance(root);
+  if (MAINTENANCE_ACTIVE.includes(maintenance?.status)) {
+    if (check) return { ...data, checked: false, reason: "maintenance_pending",
+      maintenance: maintenanceReport(maintenance), notice: maintenanceNotice(maintenance) };
+    const response = await requestMaintenance({ root, control: initial, options: {},
+      runtime: { env, packageRoot: initial.pending?.root ?? initial.active.root, isInteractive: () => false } });
+    return { ...data, checked: false, ...response.data, notice: response.text };
+  }
   if (!force && !check && !initial.auto) return { ...data, checked: false, reason: "auto_off" };
   // Recovery is local; the hard no-network override must not strand a partial refresh.
   if (initial.pending && !check && (force || !networkDisabled(env))) {
@@ -30,28 +41,39 @@ export async function performUpdate(root, { force = false, check = false, env =
   const checked = { ...data, checked: true, latest: release.version, newer };
   if (check || !newer) return checked;
   const generation = await download(root, release, { env });
-  const published = await withManagerLock(root, async () => {
-    const current = await readControl(root);
-    if (current.phase !== "ready" || current.active.root !== initial.active.root
-      || current.pin !== initial.pin || !force && !current.auto) return false;
-    await writeControl(root, { ...current, pending: generation,
-      notice: `ACC ${generation.version} is downloaded and verified.` });
-    return true;
-  });
+  // generation.hold has protected this candidate since it was staged;
+  // release it once this publish attempt resolves either way - published,
+  // its own control pointer takes over protecting it, and abandoned
+  // (state_changed) it is no longer wanted at all.
+  let published;
+  try {
+    published = await withManagerLock(root, async () => {
+      const current = await readControl(root);
+      if (current.phase !== "ready" || current.active.root !== initial.active.root
+        || current.pin !== initial.pin || !force && !current.auto) return false;
+      await writeControl(root, { ...current, pending: generation,
+        notice: `ACC ${generation.version} is downloaded and verified.` });
+      return true;
+    });
+  } finally {
+    await releaseStagingHold(generation.hold);
+  }
   if (!published) return { ...checked, reason: "state_changed" };
   return { ...checked, pending: generation.version, ...await activate(root, { env, ignorePid }) };
 }
 
-/** A single detached worker may wait cheaply for native clients to exit. */
+/** One poller may wait; the update lock stays available between its passes. */
 export async function runWorker(root, { force = false, env = process.env, wait = false, ignorePid = null } = {}) {
-  return withManagerLock(`${root}/worker`, async () => {
+  const poll = async () => {
     for (;;) {
-      const result = await performUpdate(root, { force, env, ignorePid });
+      const result = await withManagerLock(`${root}/worker`,
+        () => performUpdate(root, { force, env, ignorePid }), { timeoutMs: 100 });
       if (!wait || result.reason !== "processes_active") return result;
       await new Promise(resolve => setTimeout(resolve, 60_000));
       if (!(await readControl(root))?.auto || networkDisabled(env)) return result;
     }
-  }, { timeoutMs: 100 });
+  };
+  return wait ? withManagerLock(`${root}/worker/poller`, poll, { timeoutMs: 100 }) : poll();
 }
 
 export async function recordWorkerFailure(root, error) {