agents-can-communicate 0.4.3 → 0.5.0

package/node_modules/@agents-can-communicate/adapter-sdk/src/native-delivery.mjs

@@ -102,19 +102,45 @@ function knownBadHit(contract, version) {
     : compareStableVersions(version, entry.from) >= 0 && compareStableVersions(version, entry.to) <= 0));
 }
 
-// The static half of the rule: platform, minimum, prerelease, and denylist.
-function evaluateStatic(adapter, { clientVersion, platform }) {
+// Judges one reported client version against an adapter's captured
+// native-delivery contract: is the platform captured, is the version at or
+// above the captured minimum, and is it not on the denylist. Returns
+// { reasonCode, minimumVersion, protocolContract }; reasonCode is null when
+// the version satisfies the contract, otherwise one of
+// "native_delivery_unsupported", "platform_not_captured",
+// "version_unavailable", "prerelease_not_captured", "below_minimum_version",
+// or "known_bad_version".
+//
+// This is the static half of the rule only: it never contacts the client, so
+// passing here proves nothing about whether a live probe or handshake
+// actually confirms the protocol or delivery modes. A caller that needs that
+// layers a probe or handshake check on top (see evaluateNativeEligibility,
+// validateNativeHandshake below, and the delivery router's own offer check,
+// which uses this function alone because a response already carries no probe
+// or handshake shape to check further).
+export function evaluateVersionContract(adapter, { clientVersion, platform }) {
   const contract = adapter?.nativeDelivery;
-  if (contract === undefined) {
+  // `== null` rather than `=== undefined`: a null declaration is as much "no
+  // contract" as a missing one, and reading `contract.minimumByPlatform` off it
+  // threw the very TypeError the guard below exists to prevent. defineAdapter
+  // cannot produce that shape; a hand-built registry entry can.
+  if (contract == null) {
     return { reasonCode: "native_delivery_unsupported", minimumVersion: null, protocolContract: null };
   }
-  const minimumVersion = typeof platform === "string"
-    ? (contract.minimumByPlatform[platform] ?? null) : null;
-  if (minimumVersion === null) {
-    return { reasonCode: "platform_not_captured", minimumVersion: null, protocolContract: null };
-  }
-  const anchor = contract.anchors.find(item => item.platform === platform
-    && item.version === minimumVersion);
+  const uncaptured = { reasonCode: "platform_not_captured", minimumVersion: null,
+    protocolContract: null };
+  // validateNativeDeliveryContract guarantees a minimum map and a matching
+  // anchor, but this function is also handed adapter objects that never went
+  // through it. A declaration missing either half has captured nothing for
+  // this platform, which is a closed answer - not a TypeError raised deep
+  // inside a delivery offer, far from the declaration that caused it. Every
+  // other entry point below already answers malformed input this way.
+  if (typeof platform !== "string" || !isPlainObject(contract.minimumByPlatform)) return uncaptured;
+  const minimumVersion = contract.minimumByPlatform[platform] ?? null;
+  if (minimumVersion === null) return uncaptured;
+  const anchor = (Array.isArray(contract.anchors) ? contract.anchors : [])
+    .find(item => item.platform === platform && item.version === minimumVersion);
+  if (anchor === undefined) return uncaptured;
   const facts = { minimumVersion, protocolContract: anchor.protocolContract };
   if (!isText(clientVersion)) return { ...facts, reasonCode: "version_unavailable" };
   if (parseStableVersion(clientVersion) === null) {
@@ -147,7 +173,12 @@ function validateNativeProbe(probe) {
 }
 
 export function evaluateNativeEligibility(adapter, { clientVersion, platform, probe }) {
-  const rule = evaluateStatic(adapter, { clientVersion, platform });
+  // The probe names the process that will serve the delivery. Judging the
+  // detected binary instead refuses a service that satisfies the contract.
+  // Only the version is read here; the shape is validated where it always was,
+  // so a malformed probe still returns a closed result rather than throwing.
+  const serving = isText(probe?.clientVersion) ? probe.clientVersion : clientVersion;
+  const rule = evaluateVersionContract(adapter, { clientVersion: serving, platform });
   const base = { eligible: false, reasonCode: null, minimumVersion: rule.minimumVersion,
     protocolContract: rule.protocolContract, modes: [] };
   const closedResult = reasonCode => deepFreeze({ ...base, reasonCode });
@@ -155,7 +186,6 @@ export function evaluateNativeEligibility(adapter, { clientVersion, platform, pr
   if (probe === null || probe === undefined) return closedResult("feature_probe_failed");
   const facts = validateNativeProbe(probe);
   if (facts.supported !== true) return closedResult(facts.reasonCode ?? "feature_probe_failed");
-  if (facts.clientVersion !== clientVersion) return closedResult("probe_version_mismatch");
   if (facts.protocolContract !== rule.protocolContract) return closedResult("protocol_mismatch");
   const modes = orderedModes(facts.modes);
   if (!modes.includes("livePush")) return closedResult("feature_probe_failed");
@@ -191,19 +221,36 @@ function validateNativeHandshakeShape(handshake) {
 
 // The per-session half: the same static rule again, then the adapter's live
 // handshake facts. The launch-time executable fingerprint stays probe-only.
+//
+// An admitted verdict reports the version it admitted as `clientVersion`. That
+// is the whole point of returning it: the caller publishes a binding, and the
+// binding must record the version the admission actually rests on - the one
+// that will serve - rather than the caller's own detected-CLI claim. 0.5.0
+// judged the serving version here and left the caller publishing its claim, so
+// the two records disagreed on every machine where a daemon had updated under
+// its CLI, which is exactly the case the release exists to support. A refused
+// verdict admits nothing and carries null.
 export function validateNativeHandshake(adapter, { clientVersion, platform, handshake }) {
-  const rule = evaluateStatic(adapter, { clientVersion, platform });
-  const base = { ok: false, reasonCode: null, protocolContract: rule.protocolContract, modes: [],
+  // Same rationale as the probe: the handshake names the session that will
+  // actually serve, so the static rule is judged against that version. Only
+  // the version is read here; the shape is validated where it always was, so
+  // a malformed handshake still returns a closed result rather than throwing.
+  const serving = isText(handshake?.clientVersion) ? handshake.clientVersion : clientVersion;
+  const rule = evaluateVersionContract(adapter, { clientVersion: serving, platform });
+  const base = { ok: false, reasonCode: null, clientVersion: null,
+    protocolContract: rule.protocolContract, modes: [],
     opaqueEndpointRef: null, leaseUntil: null };
   const closedResult = reasonCode => deepFreeze({ ...base, reasonCode });
   if (rule.reasonCode !== null) return closedResult(rule.reasonCode);
   if (handshake === null || handshake === undefined) return closedResult("handshake_failed");
   const facts = validateNativeHandshakeShape(handshake);
   if (facts.supported !== true) return closedResult(facts.reasonCode ?? "handshake_failed");
-  if (facts.clientVersion !== clientVersion) return closedResult("handshake_version_mismatch");
   if (facts.protocolContract !== rule.protocolContract) return closedResult("protocol_mismatch");
   const modes = orderedModes(facts.modes);
   if (!modes.includes("livePush")) return closedResult("handshake_failed");
-  return deepFreeze({ ok: true, reasonCode: null, protocolContract: rule.protocolContract, modes,
+  // `serving` is a text version whenever the rule admitted it: every other
+  // shape leaves evaluateVersionContract at "version_unavailable" above.
+  return deepFreeze({ ok: true, reasonCode: null, clientVersion: serving,
+    protocolContract: rule.protocolContract, modes,
     opaqueEndpointRef: facts.opaqueEndpointRef, leaseUntil: facts.leaseUntil });
 }

package/node_modules/@agents-can-communicate/adapter-sdk/src/session-binding.mjs

@@ -43,7 +43,7 @@ function assertBindingDeadline(deadlineAt) {
 }
 
 export async function storeSessionBinding({ runtimeDir, harnessSessionId, accSessionId,
-  generation, clientVersion, platform, clientPid, deadlineAt }) {
+  generation, clientVersion, platform, clientPid, deadlineAt, storeVersion, runtimeRoot }) {
   assertBindingDeadline(deadlineAt);
   const file = fileFor(runtimeDir, harnessSessionId);
   const record = { schemaVersion: SCHEMA_VERSION, harnessSessionId, accSessionId, generation };
@@ -62,6 +62,21 @@ export async function storeSessionBinding({ runtimeDir, harnessSessionId, accSes
     }
     record.clientPid = clientPid;
   }
+  // Runtime facts, kept separate from `generation`, which names the ACC session
+  // generation and must not be overloaded with a runtime identity.
+  if (storeVersion !== undefined && storeVersion !== null) {
+    if (!Number.isSafeInteger(storeVersion) || storeVersion <= 0) {
+      throw new AccError(EXIT.USAGE, "session binding storeVersion must be a positive integer",
+        { storeVersion });
+    }
+    record.storeVersion = storeVersion;
+  }
+  if (runtimeRoot !== undefined && runtimeRoot !== null) {
+    if (typeof runtimeRoot !== "string" || runtimeRoot === "") {
+      throw new AccError(EXIT.USAGE, "session binding runtimeRoot must be a non-empty string", {});
+    }
+    record.runtimeRoot = runtimeRoot;
+  }
   const temporary = `${file}.${process.pid}.tmp`;
   await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, "utf8");
   // Replace rather than append: re-attaching supersedes the old generation, and

package/node_modules/@agents-can-communicate/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/cli",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -58,7 +58,7 @@ export const COMMANDS = Object.freeze({
   uninstall: { required: [], optional: ["home"], repeated: ["adapter"], flags: ["dry-run"] },
   // Asking npm whether there is a newer ACC. The one command that touches the
   // network, and never on the hook path.
-  update: { required: [], optional: ["auto", "pin"], flags: ["check", "apply"] },
+  update: { required: [], optional: ["auto", "pin"], flags: ["check", "apply", "yes"] },
   // The two things a person types first after installing from a registry. The
   // CLI answered neither: `acc --version` and `acc --help` were both "unknown
   // command", and `acc` on its own asked for a command without naming one.

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

@@ -15,6 +15,7 @@ import { ALL_ADAPTERS, clientContext, probeTimeout } from "./install-command.mjs
 import { describePresence } from "./main.mjs";
 import { platformPaths } from "./platform-paths.mjs";
 import { noticeUpdate } from "./update-check.mjs";
+import { managedUpdateDiagnostic } from "./managed-runtime/diagnostics.mjs";
 import { readControl } from "./managed-runtime/state.mjs";
 import { diagnoseFilesystemStore, repairFilesystemStore }
   from "@agents-can-communicate/storage-filesystem";
@@ -207,9 +208,7 @@ export async function runDoctor({ options, context, runtime }) {
   const update = manager === null
     ? await noticeUpdate({ dataHome, running, env: runtime?.env ?? {},
       now: Date.parse(clock.now()), get: runtime?.fetch, io: { readFile, writeFile, mkdir } })
-    : { checked: false, running, latest: manager.pending?.version ?? null,
-      newer: manager.pending !== null, auto: manager.auto, pin: manager.pin,
-      pending: manager.pending?.version ?? null, phase: manager.phase, notice: manager.notice };
+    : await managedUpdateDiagnostic(runtime.managerRoot, manager, running);
 
   // Before the store is read for anything else. `collectStatus` reads every
   // record, so on the store this command exists to describe it threw first and
@@ -233,7 +232,13 @@ export async function runDoctor({ options, context, runtime }) {
   const service = context.service ?? await context.openService();
   const status = await service.collectStatus({});
   updateNativeRuntime(adapters, status.deliveryBindings);
-  await updateNativeSessions(adapters, { service, status, root, now: clock.now() });
+  // The runtime state above is read from the binding records alone. The
+  // session pass then asks each adapter whether the receiver those records
+  // name can still take a push, and downgrades anything that only looked
+  // active. It needs the adapter objects to ask, which the diagnostic entries
+  // do not carry.
+  await updateNativeSessions(adapters, { service, status, root, now: clock.now(),
+    registry: ALL_ADAPTERS() });
   for (const adapter of adapters) {
     adapter.remediation.push(...nativeRemediation(adapter));
   }
@@ -276,7 +281,7 @@ export async function runDoctor({ options, context, runtime }) {
   ...adapters.filter(adapter => adapter.present && adapter.outgoingDelivery)
     .map(adapter => `  ${adapter.displayName} ${adapter.outgoingDelivery.diagnostic}`),
   ...(manager === null ? [] : [`  automatic updates ${manager.auto ? "on" : "off"}; ACC ${manager.active.version}`
-    + (manager.pin ? `; pinned to ${manager.pin}` : ""), ...(manager.notice ? [`  ${manager.notice}`] : [])]),
+    + (manager.pin ? `; pinned to ${manager.pin}` : ""), ...(update.notice ? [`  ${update.notice}`] : [])]),
   ...data.remediation.map(line => `  ${line}`),
   // `0 of 4` is a true line that reads as a broken machine, and on an
   // MCP-only one it would read that way on every run forever. The server needs

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

@@ -106,6 +106,8 @@ const NOTES = Object.freeze({
     "Use acc update --check to only report whether a newer release exists.",
     "An initial acc install enables automatic updates; reinstalling preserves your choice. Activation waits for active clients and ACC processes.",
     "--auto on|off changes automatic updates; --pin VERSION holds an exact stable version; --pin none follows stable releases.",
+    "An eligible Codex service restart asks once; a detached worker waits for idle work and verifies completion. Open clients disconnect; acc doctor reports progress.",
+    "--yes explicitly consents to that restart without a prompt; --check never schedules maintenance.",
     "--apply remains accepted as a compatibility alias for acc update."],
 });
 

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

@@ -9,3 +9,8 @@ export { discoverWorkspace } from "./workspace-discovery.mjs";
 export { createGitProbe, hermeticEnv } from "./git-probe.mjs";
 export { platformDataHome, runtimePaths } from "./runtime-paths.mjs";
 export { platformPaths } from "./platform-paths.mjs";
+// A pin names the generation a session started with, kept beside its binding
+// so a hook can be made to keep loading that generation once a newer one
+// activates.
+export { clearPin, hookEntrypointFor, readPin, reapPins, resolvePinnedGeneration, writePin }
+  from "./managed-runtime/pins.mjs";

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

@@ -18,6 +18,7 @@ import { runUpdateCommand } from "./update-command.mjs";
 import { runConfigCommand } from "./config-command.mjs";
 import { runInstallCommand } from "./install-command.mjs";
 import { runDoctor } from "./doctor-command.mjs";
+import { runManagementDoctor } from "./managed-runtime/diagnostics.mjs";
 import { createGitProbe } from "./git-probe.mjs";
 import { canonicalClaim } from "./claim-spelling.mjs";
 import { platformDataHome, runtimePaths } from "./runtime-paths.mjs";
@@ -412,7 +413,8 @@ export async function main(argv, runtime) {
   let parsed;
   try {
     parsed = parseArgs(argv);
-    if (runtime.managementOnly && !["help", "version", "update"].includes(parsed.command)) {
+    const managementDoctor = runtime.managementOnly && parsed.command === "doctor" && !parsed.options.repair;
+    if (runtime.managementOnly && !managementDoctor && !["help", "version", "update"].includes(parsed.command)) {
       throw new AccError(EXIT.DATA, "runtime unavailable; retry after the update or run acc update to recover");
     }
     // `config` is the one command that must work on a workspace ACC cannot
@@ -423,7 +425,7 @@ export async function main(argv, runtime) {
     // discovery cannot open the workspace - that is what a user is trying to
     // find out - install touches client configuration rather than ACC state,
     // and `help` has to answer in a directory that is no workspace at all.
-    const context = NO_WORKSPACE.includes(parsed.command)
+    const context = managementDoctor || NO_WORKSPACE.includes(parsed.command)
       ? null
       : parsed.command === "doctor"
         ? await openDiagnosticContext(parsed.options, runtime)
@@ -434,7 +436,7 @@ export async function main(argv, runtime) {
     const options = context === null ? parsed.options
       : await resolveOwner({ command: parsed.command, options: parsed.options,
         context, env: runtime.env });
-    const { data, text, error: outcome } = await HANDLERS[parsed.command](
+    const { data, text, error: outcome } = await (managementDoctor ? runManagementDoctor : HANDLERS[parsed.command])(
       { options, context, runtime });
     // A handler may have done real work and still failed: `acc install` writes
     // for the clients it could and reports the one it could not. The data is

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

@@ -1,12 +1,22 @@
 import { createHash } from "node:crypto";
-import { readdir } from "node:fs/promises";
+import { readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { assertPortableId } from "@agents-can-communicate/protocol";
 import { readSessionRecord } from "@agents-can-communicate/storage-filesystem";
 import { listRuntimeHolds } from "./leases.mjs";
 import { confirmedDead, defaultPidIsAlive, withManagerLock } from "./mutex.mjs";
-import { canonicalManagerRoot, managedDirectory, readControl, readManagedJson, writeControl } from "./state.mjs";
+import { reapPins } from "./pins.mjs";
+import { reapStagingHolds } from "./staging.mjs";
+import { canonicalManagerRoot, managedDirectory, readControl, readManagedJson, syncDirectory, writeControl } from "./state.mjs";
+
+/** The staged generation states its own contract in its manifest, so the
+ * manager never imports code from a generation it has not activated. */
+export async function declaredStoreVersion(generationRoot) {
+  const manifest = await readManagedJson(path.join(generationRoot, "package.json")).catch(() => null);
+  return Number.isSafeInteger(manifest?.accStoreVersion) && manifest.accStoreVersion > 0
+    ? manifest.accStoreVersion : null;
+}
 
 // Both 0.3.1 and current MCP write this exact continuity record, without
 // native client facts. A foreign harness id may look like an MCP key: require
@@ -47,17 +57,208 @@ export async function listNativeHolds(root, { pidIsAlive = defaultPidIsAlive } =
       const pid = record?.schemaVersion === 1 && Number.isSafeInteger(record.clientPid)
         && record.clientPid > 0 ? record.clientPid : null;
       if (pid !== null && await confirmedDead(pid, pidIsAlive)) continue;
-      holds.push({ kind: "native", pid, reason: pid === null ? "unknown_client_pid" : "client_running" });
+      holds.push({ kind: "native", pid, reason: pid === null ? "unknown_client_pid" : "client_running",
+        storeVersion: Number.isSafeInteger(record?.storeVersion) ? record.storeVersion : null });
     }
   }
   return holds;
 }
 
+/** Unknown on either side cannot be compared, and an uncomparable contract
+ * stays a hold. Equal contracts coexist by the store's own rule. */
+export const blocksActivation = (hold, incomingStoreVersion) =>
+  !Number.isSafeInteger(incomingStoreVersion) || !Number.isSafeInteger(hold.storeVersion)
+    || hold.storeVersion !== incomingStoreVersion;
+
+/** Activation calls this under the admission mutex; diagnostics are a snapshot.
+ * The updater may ignore its own leases, never a native client's lifetime.
+ * Project only process facts: leases and bindings carry private owner tokens.
+ * A hold blocks only when its declared contract differs from the incoming
+ * generation's, or when either side declares none.
+ */
+export async function listActivationBlockers(root, { pidIsAlive = defaultPidIsAlive,
+  ignorePid = null, incomingStoreVersion = null } = {}) {
+  const leases = (await listRuntimeHolds(root, { pidIsAlive })).filter(lease => lease.pid !== ignorePid);
+  const native = await listNativeHolds(root, { pidIsAlive });
+  const holds = [
+    ...leases.map(({ pid, kind, runtime }) => ({ pid, kind, nativeBindings: 0,
+      storeVersion: runtime?.storeVersion ?? null })),
+    ...native.map(hold => ({ ...hold, nativeBindings: hold.reason === "unknown_workspace" ? 0 : 1,
+      storeVersion: hold.storeVersion ?? null })),
+  ];
+  const byPid = new Map(), unidentified = [];
+  for (const hold of holds) {
+    const pid = hold.pid ?? null;
+    const nativeBindings = hold.nativeBindings;
+    if (pid === null) {
+      unidentified.push({ pid, kinds: [hold.kind], reason: hold.reason, nativeBindings,
+        storeVersion: hold.storeVersion });
+      continue;
+    }
+    const blocker = byPid.get(pid) ?? { pid, kinds: [], reason: "process_running",
+      nativeBindings: 0, storeVersion: hold.storeVersion };
+    if (!blocker.kinds.includes(hold.kind)) blocker.kinds.push(hold.kind);
+    blocker.nativeBindings += nativeBindings;
+    // One process can publish several holds. Only an unbroken run of holds
+    // declaring the same contract may keep it for the whole process; an
+    // unknown contract, or one that differs from what has already
+    // accumulated, collapses the process to uncomparable for good.
+    if (!Number.isSafeInteger(hold.storeVersion) || hold.storeVersion !== blocker.storeVersion) {
+      blocker.storeVersion = null;
+    }
+    byPid.set(pid, blocker);
+  }
+  return [...byPid.values()].sort((a, b) => a.pid - b.pid)
+    .map(blocker => ({ ...blocker, kinds: blocker.kinds.sort() })).concat(unidentified)
+    .filter(blocker => blocksActivation(blocker, incomingStoreVersion));
+}
+
+export function activationBlockerNotice(version, blockers) {
+  if (!blockers.length) return `ACC ${version} is ready; no active or unidentified processes are blocking activation.`;
+  const details = blockers.slice(0, 10).map(blocker => {
+    const facts = [blocker.kinds.map(safeText).join(", ")];
+    if (blocker.nativeBindings) facts.push(`${blocker.nativeBindings} native binding${blocker.nativeBindings === 1 ? "" : "s"}`);
+    facts.push(Number.isSafeInteger(blocker.storeVersion)
+      ? `store contract ${blocker.storeVersion}` : "contract unknown");
+    if (blocker.pid === null) facts.push(blocker.reason.replaceAll("_", " "));
+    return `${blocker.pid === null ? "unidentified process" : `PID ${blocker.pid}`} (${facts.join("; ")})`;
+  });
+  return `ACC ${version} is ready; waiting for ${blockers.length} active or unidentified process(es): `
+    + details.join("; ") + (blockers.length > 10 ? `; and ${blockers.length - 10} more` : "") + ".";
+}
+
+/** A candidate reference that is simply absent (no pending update, no
+ * explicit active override) is normal. One that is present but cannot be
+ * resolved to a real filesystem path is unknown - possibly corrupt data -
+ * and must postpone the whole pass rather than be silently ignored. Every
+ * candidate is resolved the same way a `generations/<name>` entry is, so a
+ * symlinked data home can never make a live reference look unrelated to the
+ * directory it actually names.
+ */
+async function resolveCandidate(value) {
+  if (value === null || value === undefined) return { ok: true, root: null };
+  if (typeof value !== "string" || value === "") return { ok: false };
+  try { return { ok: true, root: await canonicalManagerRoot(value) }; }
+  catch { return { ok: false }; }
+}
+
+/** A generation is reclaimable only when nothing can still import from it:
+ * not the active or pending control pointer, not a live runtime lease, not a
+ * live session pin, and not a live staging hold for a generation still being
+ * verified before publication. An unidentified holder - an unreadable lease,
+ * a pin or staging hold that is missing, corrupt, or declares an
+ * unresolvable root, or the absence of control.json itself - postpones the
+ * whole pass rather than being assumed dead, matching the rule admission
+ * already applies to its own bookkeeping.
+ *
+ * Takes its own manager lock, so a caller already holding one (activation)
+ * must call this only after releasing it.
+ */
+export async function reclaimGenerations({ root, active = null, pidIsAlive = defaultPidIsAlive } = {}) {
+  root = await canonicalManagerRoot(root);
+  return withManagerLock(root, async () => {
+    const generations = path.join(root, "generations");
+    if (!await managedDirectory(generations)) return { removed: [] };
+    // Candidates are captured before any holder is read, not after. A hold
+    // (or a control pointer) that lands later either names a directory this
+    // snapshot never saw - so it was never a deletion candidate regardless -
+    // or was already durable before this snapshot was taken, which, since
+    // every writer here writes its hold before the rename that *creates*
+    // the directory, guarantees it is already visible to every holder read
+    // below. Reading candidates last is exactly the window that left a
+    // staged-but-unpublished generation deletable; reading them first closes
+    // it for good, not just for the writer order this codebase happens to use.
+    //
+    // That guarantee is specifically about a directory the rename path
+    // creates. stageOwnGeneration's fast path (existingMatches) instead
+    // *adopts* a directory that already existed - from an earlier run,
+    // possibly one whose own hold is long gone - and only then writes this
+    // attempt's own hold for it. Such a directory can already be in this
+    // snapshot with no hold covering it yet, so a reclaim pass whose staging
+    // read happens to run before that adopting hold lands can still remove
+    // it. This is bounded, not open-ended: it can only affect a generation
+    // that is at that moment unreferenced by control, lease, and pin alike -
+    // the same shape as any other orphan - and it predates this reordering
+    // fix rather than being introduced by it.
+    const candidates = await readdir(generations, { withFileTypes: true });
+    const control = await readControl(root);
+    // No control at all is exactly as unknown as a corrupt one - which
+    // readControl already throws on, and every real caller of this function
+    // treats that throw as reason to postpone. Match that here explicitly:
+    // an absent control.json is not proof there is nothing to protect.
+    if (control === null) return { removed: [] };
+    const referenced = new Set();
+    for (const candidate of [active, control.active.root, control.pending?.root]) {
+      const resolved = await resolveCandidate(candidate);
+      if (!resolved.ok) return { removed: [] };
+      if (resolved.root) referenced.add(resolved.root);
+    }
+    let holds;
+    try { holds = await listRuntimeHolds(root, { pidIsAlive }); }
+    catch { return { removed: [] }; } // An unreadable lease is an unknown holder.
+    for (const lease of holds) {
+      const resolved = await resolveCandidate(lease.runtime?.root);
+      if (!resolved.ok) return { removed: [] };
+      if (resolved.root) referenced.add(resolved.root);
+    }
+    // A client that exits without a clean session end leaves its pin behind;
+    // reap confirmed-dead ones before treating every remaining pin as live,
+    // the same way admission already reaps confirmed-dead leases.
+    await reapPins({ root, pidIsAlive });
+    const pins = path.join(root, "pins");
+    if (await managedDirectory(pins)) {
+      for (const name of await readdir(pins)) {
+        if (!name.endsWith(".json")) continue;
+        const record = await readManagedJson(path.join(pins, name)).catch(() => null);
+        if (record === undefined) continue; // Concurrent pin removal, not a holder.
+        if (!record || record.schemaVersion !== 1 || typeof record.runtimeRoot !== "string"
+          || record.runtimeRoot === "") return { removed: [] }; // Malformed pin: unknown holder.
+        const resolved = await resolveCandidate(record.runtimeRoot);
+        if (!resolved.ok) return { removed: [] };
+        referenced.add(resolved.root);
+      }
+    }
+    // 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. A live hold names exactly the generation that step
+    // is building; a staging process that exited without publishing leaves
+    // its hold behind, reaped the same way an abandoned pin is.
+    await reapStagingHolds({ root, pidIsAlive });
+    const staging = path.join(root, "staging");
+    if (await managedDirectory(staging)) {
+      for (const name of await readdir(staging)) {
+        if (!name.endsWith(".json")) continue;
+        const record = await readManagedJson(path.join(staging, name)).catch(() => null);
+        if (record === undefined) continue; // Concurrent hold release, not a holder.
+        if (!record || record.schemaVersion !== 1 || typeof record.generationRoot !== "string"
+          || record.generationRoot === "") return { removed: [] }; // Malformed hold: unknown holder.
+        const resolved = await resolveCandidate(record.generationRoot);
+        if (!resolved.ok) return { removed: [] };
+        referenced.add(resolved.root);
+      }
+    }
+    const removed = [];
+    for (const entry of candidates) {
+      // A dot-prefixed entry is always an in-flight staging temp (mkdtemp's
+      // own naming), never a published generation. Its own creator cleans it
+      // up; guessing whether it is still being written into is not this
+      // function's job, and deleting one mid-write would corrupt that write.
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      const directory = path.join(generations, entry.name);
+      if (referenced.has(directory)) continue;
+      await rm(directory, { recursive: true, force: true });
+      removed.push(entry.name);
+    }
+    if (removed.length) await syncDirectory(generations);
+    return { removed };
+  }, { pidIsAlive });
+}
+
 async function prepareCandidate(control, root, env) {
   const file = path.join(control.pending.root, "node_modules", "@agents-can-communicate", "cli",
     "src", "managed-runtime", "refresh.mjs");
   const { prepareRefresh } = await import(pathToFileURL(file).href);
-  return prepareRefresh({ control, root, env });
+  return prepareRefresh({ control, root, env, callerProtocol: 2 });
 }
 // JSON parser diagnostics may quote private config bytes. Keep the cause and
 // known artifact paths, never the offending input or terminal control bytes.
@@ -71,20 +272,22 @@ const recipe = c => JSON.stringify([c.active, c.pending, c.home, c.targets, c.au
 
 /** Detection is outside the fence; every integration write and commit stays inside it. */
 export async function activatePending(root, { prepare = prepareCandidate, env = process.env,
-  pidIsAlive = defaultPidIsAlive, ignorePid = null } = {}) {
+  pidIsAlive = defaultPidIsAlive, ignorePid = null, beforeActivation = null } = {}) {
   root = await canonicalManagerRoot(root);
   const before = await readControl(root);
   if (!before?.pending) return { activated: false, reason: "no_pending_update" };
   const apply = await prepare(before, root, env);
-  return withManagerLock(root, async () => {
+  let activatedRoot = null;
+  const outcome = await withManagerLock(root, async () => {
     const current = await readControl(root);
     if (!current || recipe(current) !== recipe(before)) return { activated: false, reason: "state_changed" };
-    const holds = (await listRuntimeHolds(root, { pidIsAlive })).filter(lease => lease.pid !== ignorePid);
-    holds.push(...await listNativeHolds(root, { pidIsAlive }));
-    if (holds.length) {
-      const notice = `ACC ${current.pending.version} is ready; waiting for ${holds.length} active or unidentified process(es).`;
+    if (beforeActivation) await beforeActivation(current);
+    const blockers = await listActivationBlockers(root, { pidIsAlive, ignorePid,
+      incomingStoreVersion: current.pending.storeVersion });
+    if (blockers.length) {
+      const notice = activationBlockerNotice(current.pending.version, blockers);
       await writeControl(root, { ...current, notice });
-      return { activated: false, reason: "processes_active", holds: holds.length, notice };
+      return { activated: false, reason: "processes_active", holds: blockers.length, blockers, notice };
     }
     const activating = { ...current, phase: "activating", notice: "Finishing integration refresh." };
     await writeControl(root, activating);
@@ -105,6 +308,17 @@ export async function activatePending(root, { prepare = prepareCandidate, env =
     }
     await writeControl(root, { ...activating, active: current.pending, pending: null,
       phase: "ready", notice: `ACC ${current.pending.version} is active.` });
+    activatedRoot = current.pending.root;
     return { activated: true, version: current.pending.version, installation: result };
   });
+  // Reclaim only after the fence has released and the new pointer is durable:
+  // reclaimGenerations takes its own manager lock, so calling it while still
+  // inside this one would deadlock, and a reclaim failure here must never
+  // turn an already-completed activation into a reported failure - it can
+  // always run again on the next activation.
+  if (outcome.activated) {
+    try { await reclaimGenerations({ root, active: activatedRoot, pidIsAlive }); }
+    catch { /* Best effort; never fails an activation that already succeeded. */ }
+  }
+  return outcome;
 }

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

@@ -4,8 +4,13 @@ import { withManagerLock } from "./mutex.mjs";
 import { scheduleWorker } from "./schedule.mjs";
 import { readControl, writeControl } from "./state.mjs";
 import { performUpdate, runWorker } from "./worker.mjs";
+import { requestMaintenance } from "./maintenance.mjs";
+import { retireLegacyUpdateWorker, stageNewerManagementRuntime } from "./management-recovery.mjs";
 
 export function validateUpdateOptions(options) {
+  if (options.yes && (options.check || options.auto !== undefined || options.pin !== undefined)) {
+    throw new AccError(EXIT.USAGE, "--yes only consents to client maintenance during acc update");
+  }
   if (options.auto !== undefined && !["on", "off"].includes(options.auto)) {
     throw new AccError(EXIT.USAGE, "--auto expects on or off");
   }
@@ -40,9 +45,15 @@ export async function runManagedUpdate({ options, runtime }) {
       return { data: { auto: control.auto, pin: control.pin, running: control.active.version },
         text: `Automatic updates ${control.auto ? "on" : "off"}. ${control.pin ? `Pinned to ${control.pin}.` : "Following stable releases."}` };
     }
+    if (!options.check) await stageNewerManagementRuntime(root, runtime);
     const result = options.check
       ? await performUpdate(root, { check: true, env })
       : await runWorker(root, { force: true, env, ignorePid: process.pid });
+    if (!options.check && (result.reason === "processes_active" || result.reason === "maintenance_pending"
+      || result.activated || result.checked && !result.newer)) {
+      const maintenance = await requestMaintenance({ root, control: await readControl(root), options, runtime });
+      if (maintenance) return maintenance;
+    }
     const text = result.activated ? `Updated ACC to ${result.version}; integrations refreshed.`
       : result.notice && result.reason === "processes_active" ? result.notice
         : result.reason === "refresh_failed" ? [result.notice,
@@ -57,6 +68,10 @@ export async function runManagedUpdate({ options, runtime }) {
       ...(result.reason === "refresh_failed" ? { error: new AccError(EXIT.DATA, text) } : {}) };
   } catch (error) {
     if (/manager lock held/.test(error.message)) {
+      if (!options.check && options.auto === undefined && options.pin === undefined && !runtime.legacyWorkerRetried
+        && await retireLegacyUpdateWorker(root).catch(() => false)) {
+        return runManagedUpdate({ options, runtime: { ...runtime, legacyWorkerRetried: true } });
+      }
       return { data: { inProgress: true }, text: "An update is already in progress; ACC will activate it when running clients exit." };
     }
     throw error instanceof AccError ? error : new AccError(EXIT.DATA, error.message);

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

@@ -0,0 +1,36 @@
+import { activationBlockerNotice, listActivationBlockers } from "./activation.mjs";
+import { MAINTENANCE_ACTIVE, maintenanceNotice, maintenanceReport, readMaintenance } from "./maintenance-state.mjs";
+import { readControl } from "./state.mjs";
+
+/** Available when workspace admission is fenced, and from a newer management
+ * implementation before activation. Never opens a workspace or probes clients.
+ */
+export async function runManagementDoctor({ runtime }) {
+  const manager = await readControl(runtime.managerRoot);
+  if (!manager) throw new Error("managed update state is unavailable; run acc update to recover");
+  const update = await managedUpdateDiagnostic(runtime.managerRoot, manager, manager.active.version);
+  return { data: { scope: "update", workspaceInspection: "unavailable_during_update", update,
+    remediation: ["acc update"] },
+  text: ["Update diagnostics only; workspace and integrations were not inspected.",
+    update.notice ?? `ACC ${manager.active.version}; update phase ${manager.phase}.`,
+    "Run acc update to finish, then acc doctor for the full workspace report."].join("\n") };
+}
+
+export async function managedUpdateDiagnostic(root, manager, running) {
+  const blockers = manager.pending ? await listActivationBlockers(root, { ignorePid: process.pid,
+    incomingStoreVersion: manager.pending.storeVersion }) : null;
+  const update = { checked: false, running, latest: manager.pending?.version ?? null,
+    newer: manager.pending !== null, auto: manager.auto, pin: manager.pin,
+    pending: manager.pending?.version ?? null, phase: manager.phase,
+    notice: blockers === null ? manager.notice : manager.phase === "activating" && !blockers.length
+      ? "Integration refresh is incomplete; run acc update to recover."
+      : activationBlockerNotice(manager.pending.version, blockers),
+    ...(blockers === null ? {} : { holds: blockers.length, blockers }) };
+  const maintenance = await readMaintenance(root);
+  if (maintenance && (maintenance.target.root === (manager.pending ?? manager.active).root
+    || MAINTENANCE_ACTIVE.includes(maintenance.status))) {
+    update.maintenance = maintenanceReport(maintenance);
+    update.notice = maintenanceNotice(maintenance);
+  }
+  return update;
+}