agents-can-communicate 0.4.4 → 0.5.1

package/node_modules/@agents-can-communicate/adapter-codex/src/permission-ownership.mjs

@@ -11,6 +11,19 @@ const marker = (source, prefix) => source.startsWith(prefix) ? source.slice(pref
 // Permission selection, proxy and network grants form one ownership unit. If
 // any component changes, none can be removed independently: enabled networking
 // without its proxy has a different security meaning to Codex.
+//
+// A block records the table it was written inside, but that table only carries
+// meaning for a block whose first declaration is a bare assignment: such an
+// assignment belongs to whatever table precedes it, so a moved block would
+// silently mean something else. A block that opens with its own header states
+// its full path and is unaffected by what sits above it.
+//
+// The distinction is not theoretical. ACC appends the profile block at end of
+// file and then tells the user to trust ACC's hooks in Codex - and Codex writes
+// those trust entries as new `hooks.state` tables above the block. Comparing
+// the enclosing table unconditionally turned ACC's own documented setup step
+// into `customized`: doctor then reported working permissions as unverified,
+// install refused to repair them, and uninstall would not remove them.
 export function inspectPermissions(source) {
   const blocks = [];
   let open = null, metadata = null;
@@ -21,7 +34,8 @@ export function inspectPermissions(source) {
       if (open || !/^[a-z]+$/.test(start) || blocks.some(block => block.id === start)) {
         unsafe("duplicate or nested native permission marker");
       }
-      open = { id: start, start: entry.start, table: entry.table, contentStart: entry.end };
+      open = { id: start, start: entry.start, table: entry.table, contentStart: entry.end,
+        opens: null };
     } else if (comment.startsWith(META)) {
       if (!open || open.id !== "selection" || metadata !== null || entry.start !== open.contentStart) {
         unsafe("misplaced permission metadata");
@@ -29,6 +43,8 @@ export function inspectPermissions(source) {
       try { metadata = JSON.parse(comment.slice(META.length)); }
       catch { unsafe("invalid permission metadata"); }
       open.contentStart = entry.end;
+    } else if (open && entry.code && open.opens === null) {
+      open.opens = entry.header ? "table" : "assignment";
     } else if (end !== null) {
       if (!open || open.id !== end) unsafe("unmatched native permission marker");
       blocks.push({ ...open, end: entry.end, body: source.slice(open.contentStart, entry.start) });
@@ -45,7 +61,8 @@ export function inspectPermissions(source) {
     if (!record || Object.keys(record).sort().join() !== "before,hash,id,table"
       || typeof record.before !== "string" || record.hash !== hash(block.body, record)
       || (block.id === "selection" && block.table.length !== 0)
-      || JSON.stringify(block.table) !== JSON.stringify(record.table)) {
+      || (block.opens === "assignment"
+        && JSON.stringify(block.table) !== JSON.stringify(record.table))) {
       return { source, state: "customized" };
     }
   }

package/node_modules/@agents-can-communicate/adapter-gemini-cli/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "description": "Coordinate this Gemini CLI session with other AI agent sessions working in the same workspace.",
   "contextFileName": "skills/acc/SKILL.md"
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-gemini-cli",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-grok/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-grok",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-kimi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-kimi",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-sdk",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -3,7 +3,7 @@
 export { CAPABILITY_SHAPE, assertCapabilities, defineAdapter } from "./capabilities.mjs";
 export { effectiveCapabilities, validateCertification } from "./certification.mjs";
 export { NATIVE_ACTIVATION_KINDS, NATIVE_BINDING_MODES, NATIVE_PLATFORMS, NATIVE_REASON_CODES,
-  compareStableVersions, evaluateNativeEligibility, parseStableVersion,
+  compareStableVersions, evaluateNativeEligibility, evaluateVersionContract, parseStableVersion,
   validateNativeActivationPlan, validateNativeDeliveryContract, validateNativeHandshake }
   from "./native-delivery.mjs";
 export { EVENT_KINDS, NORMALIZED_EVENT_KEYS, normalizedEvent } from "./events.mjs";

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.4",
+  "version": "0.5.1",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -232,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));
   }

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/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,36 +57,60 @@ 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 } = {}) {
+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 }) => ({ pid, kind, nativeBindings: 0 })),
-    ...native.map(hold => ({ ...hold, nativeBindings: hold.reason === "unknown_workspace" ? 0 : 1 }))];
+  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 });
+      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 };
+    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);
+    .map(blocker => ({ ...blocker, kinds: blocker.kinds.sort() })).concat(unidentified)
+    .filter(blocker => blocksActivation(blocker, incomingStoreVersion));
 }
 
 export function activationBlockerNotice(version, blockers) {
@@ -84,6 +118,8 @@ export function activationBlockerNotice(version, blockers) {
   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("; ")})`;
   });
@@ -91,6 +127,133 @@ export function activationBlockerNotice(version, blockers) {
     + 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");
@@ -114,11 +277,13 @@ export async function activatePending(root, { prepare = prepareCandidate, env =
   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" };
     if (beforeActivation) await beforeActivation(current);
-    const blockers = await listActivationBlockers(root, { pidIsAlive, ignorePid });
+    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 });
@@ -143,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/diagnostics.mjs

@@ -17,7 +17,8 @@ export async function runManagementDoctor({ runtime }) {
 }
 
 export async function managedUpdateDiagnostic(root, manager, running) {
-  const blockers = manager.pending ? await listActivationBlockers(root, { ignorePid: process.pid }) : null;
+  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,

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

@@ -2,9 +2,11 @@ import { execFile } from "node:child_process";
 import { access, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
+import { declaredStoreVersion } from "./activation.mjs";
 import { stageOwnGeneration } from "./generation.mjs";
 import { verifyGeneration } from "./install.mjs";
 import { managedDirectory } from "./state.mjs";
+import { releaseStagingHold } from "./staging.mjs";
 import { ENTRY_KINDS } from "./entry.mjs";
 
 const NAME = "agents-can-communicate";
@@ -65,7 +67,20 @@ export async function downloadRelease(root, release, { env = process.env } = {})
     for (const name of ENTRY_KINDS) await access(path.join(packageRoot, "bin", "entrypoints", `${name}.mjs`));
     await access(path.join(packageRoot, "bin", "acc-update-worker.mjs"));
     const generation = await stageOwnGeneration({ packageRoot, managerRoot: root });
-    await verifyGeneration(generation, { env });
-    return { version: generation.version, root: generation.root };
+    // A failed verify, or any other failure before this function actually
+    // returns, means this candidate is abandoned here, so release its hold
+    // now - declaredStoreVersion included, so a future change to it (or any
+    // other exception in this region) cannot silently leak the hold instead
+    // of releasing it. Only a clean return hands the hold on to the caller
+    // (worker.mjs), since publication happens later there, and it is
+    // responsible for releasing it once that publish attempt resolves.
+    try {
+      await verifyGeneration(generation, { env });
+      return { version: generation.version, root: generation.root,
+        storeVersion: await declaredStoreVersion(generation.root), hold: generation.hold };
+    } catch (error) {
+      await releaseStagingHold(generation.hold);
+      throw error;
+    }
   } finally { await rm(temporary, { recursive: true, force: true }); }
 }