agents-can-communicate 0.9.1 → 0.10.1

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

@@ -39,7 +39,7 @@ export const COMMANDS = Object.freeze({
     "client-message-id"],
     repeated: ["completed", "remaining", "blocker"] },
   status: { required: [], optional: ["session", "generation", "participant"], flags: ["all"] },
-  doctor: { required: [], optional: ["home"], flags: ["repair"] },
+  doctor: { required: [], optional: ["home"], flags: ["repair", "migrate-store"] },
   // `--apply` rather than `--dry-run`: this is the one command that takes
   // records out of the store, so the reporting run is what happens by
   // default and meaning it is what has to be said out loud.
@@ -188,6 +188,9 @@ export function parseArgs(argv) {
       usage(`${command} requires --${name}`, { command, option: name });
     }
   }
+  if (command === "doctor" && options.repair && options.migrateStore) {
+    usage("doctor --repair and --migrate-store are separate operations");
+  }
   return { command, options: subcommand === undefined ? options : { ...options, subcommand } };
 }
 

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

@@ -1,4 +1,7 @@
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+// Kept above 300 lines so store, installation and native-session findings feed
+// one report before service reads. Splitting the diagnostic assembly risks
+// opening an unreadable store before its failure has been reported.
 import { homedir } from "node:os";
 import path from "node:path";
 
@@ -274,6 +277,16 @@ export async function runDoctor({ options, context, runtime }) {
   // took the diagnosis with it: one truncated file and `acc doctor` answered
   // "invalid JSON record", naming nothing, while `inspect` had already found
   // the file and put it in a list nobody ever saw.
+  // A contract-6 store is not ambiguous: its identity read and named its
+  // version. Before this, doctor called `protocol.json` unreadable and named no
+  // migration, on the one store a user just updated into (2026-10-06).
+  if (report.migrationRequired === true) {
+    throw new AccError(EXIT.DATA, "this workspace's store uses an older contract; ACC migrates it "
+      + "by itself once no older ACC client runs. To migrate it now, stop older ACC clients and run "
+      + "acc doctor --migrate-store", { workspaceId: context.descriptor.id, source: context.descriptor.source,
+      runtimeRoot: root, reasonCode: "store_migration_required", adapters,
+      remediation: ["acc doctor --migrate-store"] });
+  }
   if (!report.healthy) {
     const broken = [...report.blocked, ...report.corrupt];
     throw new AccError(EXIT.DATA,
@@ -311,6 +324,7 @@ export async function runDoctor({ options, context, runtime }) {
     materialised: status.materialised,
     protection: status.protection,
     store: report,
+    indexDiagnostics: service.store?.indexDiagnostics?.() ?? [],
     // Capabilities are reported from what is actually installed, never assumed.
     adapters,
     update,

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

@@ -77,6 +77,8 @@ const CHOICES = Object.freeze({
 });
 
 const NOTES = Object.freeze({
+  doctor: ["--repair completes recoverable writes without changing the store contract.",
+    "--migrate-store explicitly changes contract 6 to 7 after old clients and unmanaged store users stop; it cannot be combined with --repair."],
   install: ["Without --delivery, one default-No question covers all selected clients that need a decision.",
     "--delivery actionable|all gives explicit complete-setup consent; --delivery off disables incoming automatic requests.",
     "A dry run does not prompt, write configuration, or start a service. Service readiness does not establish a session binding."],

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

@@ -20,6 +20,7 @@ import { runConfigCommand } from "./config-command.mjs";
 import { ALL_ADAPTERS, runInstallCommand } from "./install-command.mjs";
 import { runDoctor } from "./doctor-command.mjs";
 import { runManagementDoctor } from "./managed-runtime/diagnostics.mjs";
+import { runStoreMigration } from "./store-migration-command.mjs";
 import { createGitProbe } from "./git-probe.mjs";
 import { canonicalClaim } from "./claim-spelling.mjs";
 import { platformDataHome, runtimePaths } from "./runtime-paths.mjs";
@@ -480,7 +481,7 @@ const HANDLERS = Object.freeze({
     return { data: result, text };
   },
 
-  doctor: async ({ options, context, runtime }) => runDoctor({ options, context, runtime }),
+  doctor: async input => input.options.migrateStore ? runStoreMigration(input) : runDoctor(input),
 
   update: async ({ options, runtime }) => runUpdateCommand({ options, runtime }),
 
@@ -518,8 +519,11 @@ export async function main(argv, runtime) {
   let parsed;
   try {
     parsed = parseArgs(argv);
-    const managementDoctor = runtime.managementOnly && parsed.command === "doctor" && !parsed.options.repair;
-    if (runtime.managementOnly && !managementDoctor && !["help", "version", "update"].includes(parsed.command)) {
+    const managementMigration = runtime.managementOnly && parsed.command === "doctor" && parsed.options.migrateStore;
+    const managementDoctor = runtime.managementOnly && parsed.command === "doctor"
+      && !parsed.options.repair && !parsed.options.migrateStore;
+    if (runtime.managementOnly && !managementDoctor && !managementMigration
+      && !["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
@@ -547,6 +551,11 @@ export async function main(argv, runtime) {
     // for the clients it could and reports the one it could not. The data is
     // printed either way, and the command still fails.
     if (outcome != null) throw Object.assign(outcome, { details: { ...outcome.details, ...data } });
+    for (const diagnostic of context?.service?.store?.indexDiagnostics?.() ?? []) {
+      if (diagnostic.code === "index_unavailable") {
+        await write(runtime.stderr, `acc: transaction index unavailable (${diagnostic.reason}); the next indexed read will rebuild it\n`);
+      }
+    }
     // Machine mode writes exactly one JSON object to stdout and nothing else.
     if (parsed.options.json === true) await write(runtime.stdout, `${JSON.stringify(ok(data))}\n`);
     else if (text !== "") await write(runtime.stdout, `${human(text)}\n`);

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

@@ -1,9 +1,13 @@
 import { createHash } from "node:crypto";
-import { readdir } from "node:fs/promises";
+// Kept above 300 lines because activation and generation retirement must use
+// the same validated runtime/native hold definitions under the admission mutex.
+// Splitting their safety rules risks disagreeing about which users are live.
+import { readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { classifySessionPresence } from "@agents-can-communicate/core";
 import { assertPortableId } from "@agents-can-communicate/protocol";
-import { readSessionRecord } from "@agents-can-communicate/storage-filesystem";
+import { readSessionRecord, withWriterMutex } from "@agents-can-communicate/storage-filesystem";
 import { listRuntimeHolds } from "./leases.mjs";
 import { confirmedDead, defaultPidIsAlive, withManagerLock } from "./mutex.mjs";
 import { reapPins } from "./pins.mjs";
@@ -31,33 +35,67 @@ async function isMcpContinuity(record, name, workspaceRoot, workspaceId) {
     for (const id of [parts[1], parts[2], record.accSessionId, record.generation]) assertPortableId(id, "MCP continuity id");
     const expected = createHash("sha256").update(record.harnessSessionId).digest("hex").slice(0, 32) + ".json";
     if (name !== expected) return false;
-    const owner = await readSessionRecord({ root: workspaceRoot, workspaceId, sessionId: record.accSessionId });
+    // This is ownership metadata, never a service open or a write. Supported
+    // v6 continuity must remain classifiable before/after migrating another
+    // workspace; its actual process lifetime is still fenced by its lease.
+    const owner = await readSessionRecord({ root: workspaceRoot, workspaceId,
+      sessionId: record.accSessionId, allowLegacyIdentity: true });
     return owner?.harness === "mcp" && owner.participantId === parts[1]
       && owner.workspaceId === workspaceId && owner.sessionId === record.accSessionId
       && owner.generation === record.generation;
   } catch { return false; } // Ambiguous or corrupt ownership remains a safety hold.
 }
 
+const clientPidOf = record => record?.schemaVersion === 1 && Number.isSafeInteger(record.clientPid)
+  && record.clientPid > 0 ? record.clientPid : null;
+
+/** A binding that names no client process cannot be judged by its own facts;
+ * its session record can. It is stale when the record is gone, when the record
+ * names a process that has exited, or, with no process recorded, when ACC's own
+ * presence rule calls the session offline - closed, or quiet past the floor for
+ * an unknown process - the rule retention removes sessions by. A live recorded
+ * process, or a record or store that cannot be read, keeps the binding a hold.
+ * On 2026-10-06 the maintainer's 0.10.0 waited behind 32 such bindings from
+ * 0.5.10 to 0.9.0 that no client could clear (#273). */
+async function staleWithoutPid(workspaceRoot, workspaceId, record, pidIsAlive) {
+  if (record?.schemaVersion !== 1) return false;
+  let session;
+  try {
+    session = await readSessionRecord({ root: workspaceRoot, workspaceId,
+      sessionId: record.accSessionId, allowLegacyIdentity: true });
+  } catch { return false; }
+  if (session === null) return true;
+  if (Number.isSafeInteger(session.pid) && session.pid > 0) return confirmedDead(session.pid, pidIsAlive);
+  // No process to ask, so the probe is never called.
+  return classifySessionPresence(session, new Date().toISOString(), () => true) === "offline";
+}
+
 /** Native bindings outlive finish/TTL; MCP process lifetime is covered by its runtime lease. */
-export async function listNativeHolds(root, { pidIsAlive = defaultPidIsAlive } = {}) {
+export async function listNativeHolds(root, { pidIsAlive = defaultPidIsAlive, strict = false } = {}) {
   const workspaces = path.join(path.dirname(await canonicalManagerRoot(root)), "workspaces");
   if (!await managedDirectory(workspaces)) return [];
   const holds = [];
   for (const entry of await readdir(workspaces, { withFileTypes: true })) {
     if (!entry.isDirectory()) {
-      if (entry.isSymbolicLink()) holds.push({ kind: "native", reason: "unknown_workspace" });
+      if (entry.isSymbolicLink()) {
+        if (strict) throw new Error("unsafe native workspace directory");
+        holds.push({ kind: "native", reason: "unknown_workspace" });
+      }
       continue;
     }
     const bindings = path.join(workspaces, entry.name, "bindings");
     if (!await managedDirectory(bindings)) continue;
     for (const name of await readdir(bindings)) {
       if (!name.endsWith(".json")) continue;
-      const record = await readManagedJson(path.join(bindings, name)).catch(() => null);
+      const record = await readManagedJson(path.join(bindings, name)).catch(error => {
+        if (strict) throw error;
+        return null;
+      });
       if (record === undefined) continue; // Concurrent lifecycle removal, before fencing.
       if (await isMcpContinuity(record, name, path.dirname(bindings), entry.name)) continue;
-      const pid = record?.schemaVersion === 1 && Number.isSafeInteger(record.clientPid)
-        && record.clientPid > 0 ? record.clientPid : null;
+      const pid = clientPidOf(record);
       if (pid !== null && await confirmedDead(pid, pidIsAlive)) continue;
+      if (pid === null && await staleWithoutPid(path.dirname(bindings), entry.name, record, pidIsAlive)) continue;
       holds.push({ kind: "native", pid, reason: pid === null ? "unknown_client_pid" : "client_running",
         storeVersion: Number.isSafeInteger(record?.storeVersion) ? record.storeVersion : null });
     }
@@ -65,6 +103,55 @@ export async function listNativeHolds(root, { pidIsAlive = defaultPidIsAlive } =
   return holds;
 }
 
+// The lock a hook holds while it loads, renews and publishes a binding: the
+// hook runner's session lifecycle mutex, keyed by the harness session id.
+const LIFECYCLE_LOCK_MS = 2_000;
+const lifecycleLocks = (workspaceRoot, harnessSessionId) => ({ locks: path.join(workspaceRoot,
+  "lifecycle-locks", createHash("sha256").update(String(harnessSessionId)).digest("hex")) });
+
+/** Remove the bindings without a client pid that listNativeHolds no longer
+ * counts. An older generation activates its successor with its own rule, which
+ * counts every one of them as a live client; it loads the pending generation's
+ * refresh before it lists blockers, so that refresh calls this (#273). Each one
+ * is judged again and removed under its session's lifecycle lock, so a hook that
+ * renews it is either seen or comes after (AI review of #274); a lock that stays
+ * busy leaves the binding as it is. */
+export async function sweepStaleBindings(root, { pidIsAlive = defaultPidIsAlive } = {}) {
+  const workspaces = path.join(path.dirname(await canonicalManagerRoot(root)), "workspaces");
+  if (!await managedDirectory(workspaces)) return 0;
+  const clock = { now: () => new Date().toISOString() };
+  let removed = 0;
+  for (const entry of await readdir(workspaces, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const workspaceRoot = path.join(workspaces, entry.name);
+    const bindings = path.join(workspaceRoot, "bindings");
+    if (!await managedDirectory(bindings)) continue;
+    let changed = false;
+    for (const name of await readdir(bindings)) {
+      if (!name.endsWith(".json")) continue;
+      const file = path.join(bindings, name);
+      const stale = async record => record !== undefined && record !== null
+        && clientPidOf(record) === null && typeof record.harnessSessionId === "string"
+        && !await isMcpContinuity(record, name, workspaceRoot, entry.name)
+        && staleWithoutPid(workspaceRoot, entry.name, record, pidIsAlive);
+      const judged = await readManagedJson(file).catch(() => undefined);
+      if (!await stale(judged)) continue;
+      const gone = await withWriterMutex(lifecycleLocks(workspaceRoot, judged.harnessSessionId),
+        { root: workspaceRoot, clock, deadlineAt: Date.now() + LIFECYCLE_LOCK_MS }, async () => {
+          const current = await readManagedJson(file).catch(() => undefined);
+          if (current?.harnessSessionId !== judged.harnessSessionId || !await stale(current)) return false;
+          await rm(file, { force: true });
+          return true;
+        }).catch(() => false);
+      if (!gone) continue;
+      removed += 1;
+      changed = true;
+    }
+    if (changed) await syncDirectory(bindings);
+  }
+  return removed;
+}
+
 /** 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) =>
@@ -78,9 +165,9 @@ export const blocksActivation = (hold, incomingStoreVersion) =>
  * generation's, or when either side declares none.
  */
 export async function listActivationBlockers(root, { pidIsAlive = defaultPidIsAlive,
-  ignorePid = null, incomingStoreVersion = null } = {}) {
+  ignorePid = null, incomingStoreVersion = null, strictNative = false } = {}) {
   const leases = (await listRuntimeHolds(root, { pidIsAlive })).filter(lease => lease.pid !== ignorePid);
-  const native = await listNativeHolds(root, { pidIsAlive });
+  const native = await listNativeHolds(root, { pidIsAlive, strict: strictNative });
   const holds = [
     ...leases.map(({ pid, kind, runtime }) => ({ pid, kind, nativeBindings: 0,
       storeVersion: runtime?.storeVersion ?? null })),

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

@@ -5,7 +5,7 @@ import { ENTRY_KINDS, RETIRED_ENTRY_KINDS } from "./entry.mjs";
 import { removeTree, renameEntry, renameReplacing } from "./portable-fs.mjs";
 import { managedDirectory, syncDirectory } from "./state.mjs";
 
-const MODULES = ["entry.mjs", "command-prefix.mjs", "state.mjs", "generation-files.mjs",
+export const MODULES = ["entry.mjs", "command-prefix.mjs", "state.mjs", "generation-files.mjs",
   "mutex.mjs", "leases.mjs", "schedule.mjs", "policy.mjs", "portable-fs.mjs"];
 async function durableFile(file, bytes, mode = 0o600) {
   const handle = await open(file, "wx", mode);

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

@@ -74,8 +74,22 @@ export async function renameEntry(from, to, { platform = process.platform,
   }, error => BUSY.has(error.code), { deadlineAt, sleep });
 }
 
-const gone = (file, lstat) => lstat(file).then(() => false,
-  error => error.code === "ENOENT");
+// A name inside a directory another process is deleting - a waiting writer's
+// rmdir of a lock its owner emptied - answers lstat with EPERM until the
+// deletion is done (measured on windows-latest: lstat of writer.lock\owner.json
+// while eight writers elected one, 2026-10-06, and the waiting writer failed
+// instead of looking again). The name is asked again within the caller's
+// deadline: what it settles to is the answer, and an EPERM that outlasts the
+// deadline is kept.
+async function lstatSettled(file, lstat, { deadlineAt, sleep }) {
+  try {
+    return await retrying(() => lstat(file, { bigint: true }), error => error.code === "EPERM",
+      { deadlineAt, sleep });
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
 
 const refusedLink = file => Object.assign(
   new Error(`ELOOP: too many symbolic links encountered, open '${file}'`),
@@ -99,32 +113,39 @@ export async function openNoFollow(file, flags, { mode, platform = process.platf
   open = fs.open, lstat = fs.lstat, deadlineAt, sleep } = {}) {
   if (!isWindows(platform)) return open(file, flags | constants.O_NOFOLLOW, mode);
   for (let attempt = 1; ; attempt += 1) {
-    const before = await lstat(file, { bigint: true }).catch(error => {
-      if (error.code === "ENOENT") return null;
-      throw error;
-    });
+    const before = await lstatSettled(file, lstat, { deadlineAt, sleep });
     if (before?.isSymbolicLink()) throw refusedLink(file);
-    // A scanner that opened the file without read sharing refuses every reader
-    // with EBUSY until it lets go.
-    const handle = await retrying(() => open(file, flags, mode), error => error.code === "EBUSY",
-      { deadlineAt, sleep }).catch(async error => {
+    let handle;
+    try {
+      // A scanner that opened the file without read sharing refuses every
+      // reader with EBUSY until it lets go.
+      handle = await retrying(() => open(file, flags, mode), error => error.code === "EBUSY",
+        { deadlineAt, sleep });
+    } catch (error) {
       // A name another process is deleting, or a lock changing hands around
       // it, refuses the open with EPERM, and the name is gone right after
       // (measured on windows-latest, for a name present before the open and
       // for one absent before it): that is ENOENT, as Linux says it. A name
-      // that is still there keeps its EPERM, and so does a create on a name
-      // that was free, which is a refused create.
+      // that names another file by then changed hands - a lock released and
+      // taken again while the open was refused (measured on windows-latest,
+      // 2026-10-06) - and is opened afresh, as a swap after the open is. A
+      // name still naming what it named keeps its EPERM, and so does a create
+      // on a name that was free, which is a refused create.
       const refusedCreate = before === null && (flags & constants.O_CREAT) !== 0;
-      if (error.code !== "EPERM" || refusedCreate || !await gone(file, lstat)) throw error;
-      throw Object.assign(new Error(`ENOENT: no such file or directory, open '${file}'`,
-        { cause: error }), { code: "ENOENT", syscall: "open", path: file });
-    });
+      if (error.code !== "EPERM" || refusedCreate) throw error;
+      const now = await lstatSettled(file, lstat, { deadlineAt, sleep }).catch(() => undefined);
+      if (now === null) {
+        throw Object.assign(new Error(`ENOENT: no such file or directory, open '${file}'`,
+          { cause: error }), { code: "ENOENT", syscall: "open", path: file });
+      }
+      const changedHands = now !== undefined
+        && (before === null || now.dev !== before.dev || now.ino !== before.ino);
+      if (changedHands && attempt < SWAPS) continue;
+      throw error;
+    }
     try {
       const opened = await handle.stat({ bigint: true });
-      const named = await lstat(file, { bigint: true }).catch(error => {
-        if (error.code === "ENOENT") return null;
-        throw error;
-      });
+      const named = await lstatSettled(file, lstat, { deadlineAt, sleep });
       if (named?.isSymbolicLink()) throw refusedLink(file);
       if (named !== null && named.dev === opened.dev && named.ino === opened.ino) return handle;
       if (attempt >= SWAPS) throw refusedLink(file);

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

@@ -2,12 +2,16 @@ import path from "node:path";
 import { applyPlan, detectInstallation, livePolicyOf, loadOwnership, planInstallation }
   from "@agents-can-communicate/installer";
 import { ALL_ADAPTERS, clientContext, probeTimeout } from "../install-command.mjs";
+import { sweepStaleBindings } from "./activation.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, callerProtocol = 1 }) {
   await bridgeLegacyMaintenance({ control, root, env, callerProtocol });
+  // An older generation lists its blockers right after this returns, by a rule
+  // that counts a binding without a client pid as a live client forever (#273).
+  await sweepStaleBindings(root).catch(() => {});
   const dataHome = path.dirname(path.dirname(root));
   const wanted = new Set(control.targets);
   const adapters = ALL_ADAPTERS().filter(adapter => wanted.has(adapter.id));

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

@@ -20,11 +20,27 @@ async function reclaimDue(root, control) {
   return !Number.isFinite(attempted) || Date.now() - attempted >= RECLAIM_RETRY_MS;
 }
 
+// The active generation has not yet moved this data home's older stores to its
+// contract (#263; `store-upgrade.json`, which its worker writes on every pass),
+// or a pass left a store behind a minute or more ago. Until it succeeds that
+// workspace has no coordination, so the retry is soon. This module is copied
+// into every launcher and imports only launcher modules; an import of the
+// migration itself failed every hook with ERR_MODULE_NOT_FOUND (2026-10-06).
+export const STORE_UPGRADE_RETRY_MS = 60_000;
+export async function storeUpgradeDue(root, control, { now = Date.now() } = {}) {
+  let marker;
+  try { marker = await readManagedJson(path.join(root, "store-upgrade.json")); } catch { return false; }
+  if (marker?.activeRoot !== control.active.root) return true;
+  if (marker.complete !== false) return false;
+  const attempted = Date.parse(marker.attemptedAt);
+  return !Number.isFinite(attempted) || now - attempted >= STORE_UPGRADE_RETRY_MS;
+}
+
 /** No network waits here: this only starts an independent background process. */
 export async function scheduleWorker(root, control, { env = process.env } = {}) {
   if (!control?.active) return false;
   const update = control.auto && !networkDisabled(env) && (control.pending || checkDue(control));
-  if (!update && !await reclaimDue(root, control)) return false;
+  if (!update && !await reclaimDue(root, control) && !await storeUpgradeDue(root, control)) return false;
   try {
     for (const directory of [path.join(root, "worker"), path.join(root, "worker", "poller")]) {
       const owner = await readManagedJson(path.join(directory, "manager.lock", "owner.json"));

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

@@ -0,0 +1,105 @@
+import { randomBytes } from "node:crypto";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { assertPortableId, createId } from "@agents-can-communicate/protocol";
+import { migrateFilesystemStore, STORE_VERSION } from "@agents-can-communicate/storage-filesystem";
+
+import { listActivationBlockers } from "./activation.mjs";
+import { withManagerLock } from "./mutex.mjs";
+import { readControl, writeManagedJson } from "./state.mjs";
+
+/**
+ * Move this data home's older stores to the contract this generation speaks.
+ *
+ * #263 made contract 6 to 7 an explicit `acc doctor --migrate-store` in each
+ * workspace. With automatic updates on, a user who ran nothing found every
+ * workspace without coordination after the update, its remedy on a stderr line
+ * Claude Code does not show (2026-10-06). The activation of a contract-7
+ * runtime already waits until no live process holds contract 6, so right after
+ * it - and on every later worker pass - the same check guards each store's
+ * migration, under the same admission mutex as the explicit command. The mutex
+ * is taken per store, so an entry waits at most one store's migration.
+ */
+export const STORE_UPGRADE_MARKER = "store-upgrade.json";
+
+const workspacesOf = root => path.join(path.dirname(root), "workspaces");
+const systemClock = { now: () => new Date().toISOString() };
+const systemIds = { next: kind => createId(kind, randomBytes) };
+
+/**
+ * The stores in this data home whose contract is older than this code's, and
+ * how many entries could not be read now. An entry that is not a store (no
+ * identity, not a directory, a link, a name that is no workspace id, another
+ * workspace's identity) is skipped; one whose identity or listing failed to
+ * read is counted, so the pass stays open and a later one retries it (AI review
+ * of #264: such a store was dropped and the pass recorded itself complete).
+ */
+export async function olderStores(root) {
+  const workspaces = workspacesOf(root);
+  let names;
+  try {
+    names = await readdir(workspaces);
+  } catch (error) {
+    return { stores: [], unreadable: error?.code === "ENOENT" ? 0 : 1 };
+  }
+  const stores = [];
+  let unreadable = 0;
+  for (const name of names) {
+    const dir = path.join(workspaces, name);
+    try { assertPortableId(name); } catch { continue; }
+    let identity;
+    try {
+      const info = await lstat(dir);
+      if (!info.isDirectory() || info.isSymbolicLink()) continue;
+      identity = JSON.parse(await readFile(path.join(dir, "protocol.json"), "utf8"));
+    } catch (error) {
+      if (error?.code !== "ENOENT") unreadable += 1;
+      continue;
+    }
+    if (identity?.workspaceId === name && Number.isSafeInteger(identity.storeVersion)
+      && identity.storeVersion < STORE_VERSION) {
+      stores.push({ workspaceId: name, dir, storeVersion: identity.storeVersion });
+    }
+  }
+  return { stores, unreadable };
+}
+
+/**
+ * Migrate every older store that no live older client holds. Records the pass
+ * in STORE_UPGRADE_MARKER and returns one outcome per store.
+ */
+export async function migrateOlderStores(root, { ignorePid = process.pid, clock = systemClock,
+  ids = systemIds, platform = process.platform, migrate = migrateFilesystemStore } = {}) {
+  const control = await readControl(root);
+  if (!control?.active) return [];
+  const outcomes = [];
+  // Recorded even when this generation migrates nothing, so the launcher's
+  // scheduler, which knows no contract, stops asking for a pass.
+  const { stores, unreadable } = control.active.storeVersion === STORE_VERSION
+    ? await olderStores(root) : { stores: [], unreadable: 0 };
+  for (const store of stores) {
+    let state;
+    try {
+      state = await withManagerLock(root, async () => {
+        const current = await readControl(root);
+        if (current?.phase !== "ready" || current.active?.storeVersion !== STORE_VERSION) return "not_ready";
+        const blockers = await listActivationBlockers(root, { incomingStoreVersion: STORE_VERSION,
+          ignorePid, strictNative: true });
+        if (blockers.length > 0) return "blocked";
+        await migrate({ root: store.dir, workspaceId: store.workspaceId, clock, ids, platform,
+          allowMigration: true });
+        return "migrated";
+      });
+    } catch {
+      state = "failed";
+    }
+    outcomes.push({ workspaceId: store.workspaceId, state });
+  }
+  await writeManagedJson(path.join(root, STORE_UPGRADE_MARKER), { schemaVersion: 1,
+    activeRoot: control.active.root,
+    complete: unreadable === 0 && outcomes.every(item => item.state === "migrated"),
+    pending: unreadable + outcomes.filter(item => item.state !== "migrated").length,
+    attemptedAt: new Date().toISOString() });
+  return outcomes;
+}

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

@@ -7,6 +7,7 @@ import { downloadRelease, fetchRelease, newerVersion } from "./download.mjs";
 import { withManagerLock } from "./mutex.mjs";
 import { readControl, writeControl, writeManagedJson } from "./state.mjs";
 import { releaseStagingHold } from "./staging.mjs";
+import { migrateOlderStores } from "./store-upgrade.mjs";
 import { MAINTENANCE_ACTIVE, maintenanceNotice, maintenanceReport, readMaintenance } from "./maintenance-state.mjs";
 import { requestMaintenance } from "./maintenance.mjs";
 
@@ -103,6 +104,10 @@ export async function reclaimAsActive(root, generationRoot) {
       activeRoot: control.active.root, complete: result?.postponed !== true && !own,
       attemptedAt: new Date().toISOString() });
   } catch { /* Best effort; the next pass reclaims again. */ }
+  // This generation's stores, moved to its contract once no older client holds
+  // one. In the activating process its own older lease is not a holder.
+  try { await migrateOlderStores(root, { ignorePid: process.pid }); }
+  catch { /* Best effort; the scheduler retries an incomplete pass. */ }
 }
 
 /** One poller may wait; the update lock stays available between its passes. */

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

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+import { migrateFilesystemStore, STORE_VERSION } from "@agents-can-communicate/storage-filesystem";
+import { listActivationBlockers } from "./managed-runtime/activation.mjs";
+import { withManagerLock } from "./managed-runtime/mutex.mjs";
+import { readControl } from "./managed-runtime/state.mjs";
+
+export async function runStoreMigration({ options, context, runtime }) {
+  const manager = runtime.managerRoot ?? path.join(context.dataHome, "acc", "runtime");
+  let result;
+  try {
+    result = await withManagerLock(manager, async () => {
+      const control = await readControl(manager);
+      if (control !== null && control.phase !== "ready") {
+        throw new AccError(EXIT.CONFLICT, "runtime admission is not ready; finish the update before store migration");
+      }
+      const blockers = await listActivationBlockers(manager, { incomingStoreVersion: STORE_VERSION,
+        ignorePid: process.pid, strictNative: true });
+      if (blockers.length > 0) {
+        throw new AccError(EXIT.CONFLICT, "store migration is blocked by live users of an old or unknown contract; stop them and retry",
+          { blockers });
+      }
+      return migrateFilesystemStore({ root: context.paths.root, workspaceId: context.descriptor.id,
+        clock: runtime.clock, ids: runtime.ids, platform: runtime.platform, allowMigration: true,
+        failAt: runtime.storeMigrationFailAt });
+    });
+  } catch (error) {
+    if (error instanceof AccError) throw error;
+    if (error.message === "manager lock held; acquisition timeout") {
+      throw new AccError(EXIT.CONFLICT, "runtime admission is busy; retry store migration");
+    }
+    // Management parser errors can quote private bytes; expose no raw cause.
+    throw new AccError(EXIT.DATA, "runtime admission state is unsafe or unreadable; store migration refused");
+  }
+  const data = { workspaceId: context.descriptor.id, ...result };
+  return { data, text: result.migrated
+    ? `store migrated from contract ${result.fromVersion} to ${result.toVersion}`
+    : `store already uses contract ${result.toVersion}; index verified` };
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "private": true,
   "type": "module",
   "exports": {