agents-can-communicate 0.9.0 → 0.10.0

package/node_modules/@agents-can-communicate/storage-filesystem/src/index-reclaim.mjs

@@ -0,0 +1,142 @@
+import path from "node:path";
+import { idleJournal, readActiveJournal } from "./active-journal.mjs";
+import { listDirectoryEntries, nameCommittedLater } from "./atomic-json.mjs";
+import { condemn, detachDoomed, discard, expired } from "./doomed-directory.mjs";
+import { createIndexIO } from "./index-io.mjs";
+import { IndexCacheUnavailable } from "./index-pages.mjs";
+import { readReclaimProgress, writeReclaimProgress } from "./index-reclaim-progress.mjs";
+import { readStoreIdentity } from "./identity.mjs";
+import { journalEntry, writeJournalEntry } from "./journal.mjs";
+import { syncPruneDirectories } from "./prune-durability.mjs";
+import { assertManagedDirectory } from "./safe-directory.mjs";
+
+const children = page => page.type === "branch" ? page.children.map(([, hash]) => hash)
+  : page.type === "leaf" ? [...page.entries.map(entry => entry.ids), page.next].filter(Boolean)
+    : [page.next].filter(Boolean);
+
+// The caller holds the writer mutex. Persist both mark and sweep progress: a
+// live graph or a directory larger than one pass must eventually finish. Roots
+// added by intervening writers are marked before sweeping resumes. Previously
+// marked roots stay in the conservative live superset until the next cycle.
+export async function reclaimIndexPages(paths, { root, roots, limit = 512, deadlineAt } = {}) {
+  let spent = 0, reclaimed = 0;
+  const result = (remaining, deferred = false) => ({ reclaimed, remaining, spent, deferred });
+  if (expired(deadlineAt)) return result(true, true);
+  const directory = path.join(root, "indexes", "v1", "pages");
+  try { await assertManagedDirectory(root, directory); }
+  catch (error) { return result(error.code !== "ENOENT", error.code !== "ENOENT"); }
+  if (limit < 4) return result(true);
+  const io = createIndexIO({ paths, root, publishOptions: {} });
+  if (roots === undefined) {
+    let manifest;
+    try { manifest = await io.readManifest(); }
+    catch (error) { if (error instanceof IndexCacheUnavailable) return result(true, true); throw error; }
+    if (manifest === null) return result(true, true);
+    // Primary authority faults stay outside cache-error handling.
+    const active = await readActiveJournal(paths, root), identity = await readStoreIdentity(paths);
+    if (active.state !== "idle" || manifest.journalGeneration !== active.generation
+      || manifest.workspaceId !== identity?.workspaceId) return result(true, true);
+    roots = manifest.roots;
+  }
+  const progress = await readReclaimProgress(root);
+  spent += 1;
+  // Reserve the checkpoint publication within the same budget as page work.
+  const budget = limit - 1;
+  const reachable = new Set(progress.visited), pending = progress.pending;
+  for (const hash of Object.values(roots).filter(Boolean)) {
+    if (!reachable.has(hash) && !pending.includes(hash)) pending.push(hash);
+  }
+  const checkpoint = async (remaining) => {
+    progress.visited = [...reachable];
+    progress.done = !remaining;
+    try {
+      await writeReclaimProgress(paths, root, progress, deadlineAt);
+      spent += 1;
+      return result(remaining);
+    } catch { return result(true, true); }
+  };
+  try {
+    while (pending.length > 0) {
+      const hash = pending.pop();
+      if (reachable.has(hash)) continue;
+      if (spent >= budget || expired(deadlineAt)) {
+        pending.push(hash);
+        return checkpoint(true);
+      }
+      spent += 1;
+      pending.push(...children(await io.readPage(hash)));
+      reachable.add(hash);
+    }
+  } catch (error) {
+    if (error instanceof IndexCacheUnavailable) {
+      // A former root can disappear while the cache rebuilds. Do not let an
+      // unreadable old stack poison every later pass; restart from authority.
+      pending.length = 0;
+      reachable.clear();
+      progress.cursor = null;
+      await checkpoint(false);
+      return result(true, true);
+    }
+    throw error;
+  }
+  let entries;
+  try { entries = await listDirectoryEntries(directory, { root }); }
+  catch { return result(true, true); } // Cache paths alone are optional maintenance.
+  let doomed, reserved = 0, remaining = false;
+  entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  for (const entry of entries) {
+    if (!/^[a-f0-9]{64}\.json$/.test(entry.name) || (progress.cursor !== null && entry.name <= progress.cursor)) continue;
+    if (spent + reserved >= budget || expired(deadlineAt)) { remaining = true; break; }
+    spent += 1;
+    if (!entry.isFile() || reachable.has(entry.name.slice(0, -5))) { progress.cursor = entry.name; continue; }
+    if (spent + reserved + 2 > budget) { remaining = true; break; }
+    doomed ??= await detachDoomed(root);
+    await assertManagedDirectory(root, directory);
+    await condemn(path.join(directory, entry.name), doomed);
+    spent += 1; reserved += 1;
+    progress.cursor = entry.name;
+  }
+  if (doomed !== undefined) {
+    const removed = await discard(doomed, root, budget - spent, deadlineAt);
+    reclaimed += removed.spent; spent += removed.spent;
+    remaining ||= !removed.drained;
+  }
+  return checkpoint(remaining);
+}
+
+async function discardCache(root, collect) {
+  const directory = path.join(root, "indexes", "v1");
+  // Only a validated cache directory may move. Damage/unsafe cache paths stay
+  // untouched, and the changed durable epoch already makes their roots stale.
+  try {
+    await assertManagedDirectory(root, directory);
+    const doomed = await detachDoomed(root);
+    await condemn(directory, doomed);
+    collect(directory, doomed);
+  } catch { /* Cache loss or refusal cannot fail a completed primary prune. */ }
+}
+
+// Existing empty-publication journals fence physical retirement without
+// introducing a new authoritative marker or a per-message flush.
+export async function withIndexedPrune(paths, options, operation) {
+  const { ids, firstSequence, root, deadlineAt, ...publish } = options;
+  const entry = journalEntry(ids.next("transaction"), firstSequence, [], options.clock.now());
+  await writeJournalEntry(paths, { ...publish, root, deadlineAt }, entry);
+  const directories = new Set([root]);
+  const collect = (file, doomed) => { directories.add(path.dirname(file)); directories.add(doomed); };
+  try {
+    await options.failAt?.("after-indexed-prune-activated");
+    await discardCache(root, collect);
+    return await operation(async (file, doomed) => {
+      collect(file, doomed);
+      await options.failAt?.("after-indexed-prune-move");
+    });
+  } finally {
+    // A decided/applied prefix must finish its durability even after its
+    // caller's deadline. POSIX flushes names; the final Windows journal flush
+    // commits every earlier NTFS metadata rename.
+    await syncPruneDirectories(root, directories, options);
+    await options.failAt?.("before-indexed-prune-idle");
+    await idleJournal(paths, { ...publish, root, durability: nameCommittedLater(options.platform) }, entry.transactionId);
+  }
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/index-tree.mjs

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { assertPortableId } from "@agents-can-communicate/protocol";
+import { assertPageHash, canonicalTuple, IndexCacheUnavailable } from "./index-pages.mjs";
+
+const compare = (a, b) => a.localeCompare(b);
+const keyOf = entry => canonicalTuple(entry.tuple);
+const digest = tuple => createHash("sha256").update(canonicalTuple(tuple)).digest("hex");
+const fault = reason => { throw new IndexCacheUnavailable(reason); };
+export function createIndexTree({ readPage, writePage, digestTuple = digest }) {
+  async function read(hash, seen) {
+    assertPageHash(hash);
+    if (seen.has(hash)) fault("page_cycle");
+    seen.add(hash);
+    return readPage(hash);
+  }
+  async function groupLookup(root) {
+    const ids = [], seen = new Set();
+    while (root !== null) {
+      const page = await read(root, seen);
+      if (page.type !== "group") fault("invalid_group_reference");
+      for (const id of page.ids) {
+        if (ids.length && compare(ids.at(-1), id) >= 0) fault("duplicate_or_unordered_group");
+        ids.push(id);
+      }
+      root = page.next;
+    }
+    return ids;
+  }
+  async function groupUpdate(root, id, operation, seen = new Set()) {
+    if (root === null) return operation === "remove" ? null : writePage({ type: "group", ids: [id], next: null });
+    const page = await read(root, seen);
+    if (page.type !== "group") fault("invalid_group_reference");
+    const position = page.ids.findIndex(found => compare(found, id) >= 0);
+    if (position === -1 && page.next !== null) {
+      const next = await groupUpdate(page.next, id, operation, seen);
+      return next === page.next ? root : writePage({ ...page, next });
+    }
+    const ids = [...page.ids], at = position === -1 ? ids.length : position;
+    if (ids[at] === id) {
+      if (operation === "put") return root;
+      ids.splice(at, 1);
+    } else {
+      if (operation === "remove") return root;
+      ids.splice(at, 0, id);
+    }
+    if (ids.length === 0) return page.next;
+    if (ids.length <= 32) return writePage({ ...page, ids });
+    const next = await writePage({ type: "group", ids: ids.slice(16), next: page.next });
+    return writePage({ type: "group", ids: ids.slice(0, 16), next });
+  }
+  function checkNode(page, depth, prefix) {
+    if (page.type === "branch") {
+      if (depth >= 64) fault("radix_depth_exceeded");
+    } else if (page.type === "leaf") {
+      if (page.next !== null && depth !== 64) fault("unexpected_collision_page");
+      for (const entry of page.entries) {
+        if (!entry.digest.startsWith(prefix) || entry.digest !== digestTuple(entry.tuple)) fault("misrouted_tuple");
+      }
+    } else fault("invalid_tree_reference");
+  }
+  async function lookup(root, tuple) {
+    const key = canonicalTuple(tuple), hash = assertPageHash(digestTuple(tuple)), seen = new Set();
+    let depth = 0, prefix = "", idsRoot = null;
+    while (root !== null) {
+      const page = await read(root, seen); checkNode(page, depth, prefix);
+      if (page.type === "branch") {
+        const route = hash[depth++]; prefix += route;
+        root = page.children.find(([digit]) => digit === route)?.[1] ?? null;
+      } else {
+        const found = page.entries.find(entry => keyOf(entry) === key);
+        if (found) {
+          if (idsRoot !== null) fault("duplicate_collision_key");
+          idsRoot = found.ids;
+        }
+        root = page.next;
+      }
+    }
+    return idsRoot === null ? [] : groupLookup(idsRoot);
+  }
+  const leaf = (entries, next = null) => writePage({ type: "leaf",
+    entries: [...entries].sort((a, b) => compare(keyOf(a), keyOf(b))), next });
+  async function split(entries, depth) {
+    if (entries.length <= 32) return leaf(entries);
+    if (depth === 64) {
+      let next = null;
+      for (let end = entries.length; end > 0; end -= 32) {
+        next = await leaf(entries.slice(Math.max(0, end - 32), end), next);
+      }
+      return next;
+    }
+    const routes = new Map();
+    for (const entry of entries) {
+      const route = entry.digest[depth];
+      if (!routes.has(route)) routes.set(route, []);
+      routes.get(route).push(entry);
+    }
+    const children = [];
+    for (const route of [...routes.keys()].sort()) children.push([route, await split(routes.get(route), depth + 1)]);
+    return writePage({ type: "branch", children });
+  }
+  async function update(root, tuple, id, operation, depth = 0, prefix = "", seen = new Set()) {
+    const hash = assertPageHash(digestTuple(tuple)), key = canonicalTuple(tuple);
+    if (root === null) {
+      if (operation === "remove") return null;
+      return leaf([{ digest: hash, tuple, ids: await groupUpdate(null, id, operation) }]);
+    }
+    const page = await read(root, seen); checkNode(page, depth, prefix);
+    if (page.type === "branch") {
+      const route = hash[depth], old = page.children.find(([digit]) => digit === route)?.[1] ?? null;
+      const next = await update(old, tuple, id, operation, depth + 1, prefix + route, seen);
+      if (old === next) return root;
+      const children = page.children.filter(([digit]) => digit !== route);
+      if (next !== null) children.push([route, next]);
+      children.sort(([a], [b]) => compare(a, b));
+      return children.length === 0 ? null : writePage({ type: "branch", children });
+    }
+    const entries = [...page.entries], at = entries.findIndex(entry => keyOf(entry) === key);
+    if (at !== -1) {
+      const ids = await groupUpdate(entries[at].ids, id, operation);
+      if (ids === entries[at].ids) return root;
+      if (ids === null) entries.splice(at, 1);
+      else entries[at] = { ...entries[at], ids };
+      return entries.length === 0 ? page.next : leaf(entries, page.next);
+    }
+    if (page.next !== null) {
+      const next = await update(page.next, tuple, id, operation, depth, prefix, seen);
+      return next === page.next ? root : leaf(entries, next);
+    }
+    if (operation === "remove") return root;
+    entries.push({ digest: hash, tuple, ids: await groupUpdate(null, id, operation) });
+    return split(entries, depth);
+  }
+  async function apply(root, deltas) {
+    for (const { tuple, id, operation } of deltas) {
+      assertPortableId(id, "index record ID");
+      if (!["put", "remove"].includes(operation)) fault("invalid_delta");
+      root = await update(root, tuple, id, operation);
+    }
+    return root;
+  }
+  return Object.freeze({ lookup, apply });
+}

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

@@ -5,3 +5,4 @@ export { readStoreIdentity, requireStoreIdentity, STORE_VERSION } from "./identi
 export { withWriterMutex } from "./writer-mutex.mjs";
 export { readSessionRecord } from "./session-read.mjs";
 export { openNoFollow } from "./portable-fs.mjs";
+export { migrateFilesystemStore } from "./store-migration.mjs";

package/node_modules/@agents-can-communicate/storage-filesystem/src/journal.mjs

@@ -5,6 +5,7 @@ import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protoc
 import { activateJournal, idleJournal, readActiveJournal } from "./active-journal.mjs";
 import { encode, nameCommittedLater, publishAtomic, readJsonIfPresent, retainFile }
   from "./atomic-json.mjs";
+import { recoverPruneDurability } from "./prune-durability.mjs";
 
 export const JOURNAL_VERSION = 2;
 
@@ -133,6 +134,7 @@ export async function readJournalCeiling(paths, root) {
 // twice changes nothing and a genuine conflict is never papered over.
 export async function rollForward(paths, options, entry) {
   const published = [];
+  if (entry.publications.length === 0) await recoverPruneDurability(paths, options);
   for (const publication of entry.publications) {
     const destination = publicationDestination(options.root, publication.path);
     if (publication.retainedPath !== null) {

package/node_modules/@agents-can-communicate/storage-filesystem/src/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/storage-filesystem/src/prune-durability.mjs

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { doomedDirectories } from "./doomed-directory.mjs";
+import { isWindows, syncEntry } from "./portable-fs.mjs";
+import { assertManagedDirectory } from "./safe-directory.mjs";
+
+// A decided prune finishes its applied prefix even after its deadline. On
+// Windows the final idle-journal file flush commits earlier NTFS renames.
+export async function syncPruneDirectories(root, directories, { platform } = {}) {
+  if (isWindows(platform)) return;
+  for (const directory of directories) {
+    try { await assertManagedDirectory(root, directory); }
+    catch (error) { if (error.code === "ENOENT") continue; throw error; }
+    await syncEntry(directory, directory, { platform });
+  }
+}
+
+// Empty-publication journals are physical indexed prunes. Process death loses
+// their in-memory affected-directory set; conservatively fence every possible
+// primary/marker parent before idle permits a current negative cache. No new
+// journal format or per-record publication is needed.
+export async function recoverPruneDurability(paths, { root, platform } = {}) {
+  if (isWindows(platform)) return;
+  const directories = [
+    ...["message", "receipt"].flatMap(kind => [path.join(paths.state, kind),
+      path.join(paths.retained, "state", kind)]),
+    ...await doomedDirectories(root), root,
+  ];
+  await syncPruneDirectories(root, directories, { platform });
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/reclaim.mjs

@@ -7,6 +7,7 @@ import { listDirectoryEntries, readJsonIfPresent } from "./atomic-json.mjs";
 import { condemn, detachDoomed, discard, discardLeftovers, expired } from "./doomed-directory.mjs";
 import { assertSequence, raiseEventFloor, readEventFloor } from "./event-floor.mjs";
 import { statePath } from "./record-id.mjs";
+import { reclaimIndexPages } from "./index-reclaim.mjs";
 
 // Shared with the stage sweep that calls this, so one pass cannot spend two
 // budgets. Exported for the caller that wants to reclaim without a bound.
@@ -148,8 +149,14 @@ export async function reclaimRetired(paths,
 
   const removed = await discard(doomed, root, limit - spent, deadlineAt);
   reclaimed += removed.spent;
+  spent += removed.spent;
+  const indexes = journals.drained && markers.drained && removed.drained
+    ? await reclaimIndexPages(paths, { root, limit: limit - spent, deadlineAt })
+    : { reclaimed: 0, remaining: false };
+  reclaimed += indexes.reclaimed;
   return { reclaimed,
-    remaining: !journals.drained || !markers.drained || !removed.drained };
+    remaining: !journals.drained || !markers.drained || !removed.drained
+      || (indexes.remaining && !indexes.deferred) };
 }
 
 /**
@@ -172,7 +179,7 @@ export async function reclaimRetired(paths,
  * @returns {Promise<{ reclaimed: number, skipped: number, remaining: boolean }>}
  */
 export async function reclaimStateRecords(paths, entries,
-  { root, limit = RECLAIM_BUDGET, deadlineAt } = {}) {
+  { root, limit = RECLAIM_BUDGET, deadlineAt, onCondemned } = {}) {
   if (expired(deadlineAt)) return { reclaimed: 0, skipped: 0, remaining: entries.length > 0 };
   let spent = 0;
   let skipped = 0;
@@ -202,10 +209,13 @@ export async function reclaimStateRecords(paths, entries,
       continue;
     }
     await condemn(filePath, doomed);
+    await onCondemned?.(filePath, doomed);
     spent += 1;
     condemned += 1;
     try {
-      await condemn(path.join(paths.retained, "state", entry.kind, entry.id), doomed);
+      const markers = path.join(paths.retained, "state", entry.kind, entry.id);
+      await condemn(markers, doomed);
+      await onCondemned?.(markers, doomed);
       spent += 1;
       // Counted only when it moved. Most records own no marker directory at
       // all, and counting one anyway made `remaining` compare what was

package/node_modules/@agents-can-communicate/storage-filesystem/src/recovery.mjs

@@ -18,8 +18,11 @@ import { withWriterMutex } from "./writer-mutex.mjs";
  * trimmedThrough: string|null }} RepairReport */
 
 const report = ({ repaired = [], blocked = [], corrupt = [], swept = 0, staged = 0,
-  partials = 0, retired = 0, trimmedThrough = null }) => ({
+  partials = 0, retired = 0, trimmedThrough = null, migrationRequired = false }) => ({
   healthy: blocked.length === 0 && corrupt.length === 0,
+  // An older contract, not an unreadable file: the identity read and named its
+  // version. The reader names the migration rather than calling it ambiguous.
+  ...(migrationRequired ? { migrationRequired: true } : {}),
   repaired: [...repaired].sort(),
   blocked: [...blocked].sort(),
   corrupt: [...corrupt].sort(),
@@ -75,7 +78,8 @@ async function inspect(root) {
     identity = await readStoreIdentity(paths);
   } catch (error) {
     blocked.push(path.join(root, "protocol.json"));
-    return { paths, identity: null, pending, blocked, corrupt, reason: error.message };
+    return { paths, identity: null, pending, blocked, corrupt, reason: error.message,
+      migrationRequired: error?.details?.reasonCode === "store_migration_required" };
   }
   if (identity === null) blocked.push(path.join(root, "protocol.json"));
 
@@ -123,6 +127,7 @@ export async function diagnoseFilesystemStore({ root }) {
   return report({
     blocked: state.blocked,
     corrupt: state.corrupt,
+    migrationRequired: state.migrationRequired === true,
     repaired: state.pending.map(entry => entry.transactionId),
     ...await countStaging(state.paths, root),
   });
@@ -133,7 +138,8 @@ export async function repairFilesystemStore({ root, clock }) {
   if (state.blocked.length > 0 || state.corrupt.length > 0) {
     // Fail closed. Completing a journal on top of state we cannot even read
     // would turn an ambiguous store into a confidently wrong one.
-    return report({ blocked: state.blocked, corrupt: state.corrupt });
+    return report({ blocked: state.blocked, corrupt: state.corrupt,
+      migrationRequired: state.migrationRequired === true });
   }
   // No early return for an empty journal any more: a store with nothing to roll
   // forward is exactly the store whose staging directory needs reclaiming.

package/node_modules/@agents-can-communicate/storage-filesystem/src/session-read.mjs

@@ -1,16 +1,18 @@
 import path from "node:path";
 import { assertPortableId, validateRecord } from "@agents-can-communicate/protocol";
 import { readJsonIfPresent } from "./atomic-json.mjs";
-import { requireStoreIdentity } from "./identity.mjs";
+import { readMigrationIdentity, requireStoreIdentity } from "./identity.mjs";
 import { assertStateBinding, statePath } from "./record-id.mjs";
 import { ephemeralIsDeleted, stateGenerationIsDeleted } from "./retention.mjs";
 import { storePaths } from "./store.mjs";
 
-/** Inspect ownership without opening, creating, recovering, or locking the store. */
-export async function readSessionRecord({ root, workspaceId, sessionId }) {
+/** Inspect ownership without opening, creating, recovering, or locking the store.
+ * Legacy identity inspection is read-only metadata for runtime hold classification. */
+export async function readSessionRecord({ root, workspaceId, sessionId, allowLegacyIdentity = false }) {
   assertPortableId(sessionId, "session id");
   const paths = storePaths(root);
-  await requireStoreIdentity(paths, { workspaceId, create: false });
+  if (allowLegacyIdentity === true) await readMigrationIdentity(paths, workspaceId);
+  else await requireStoreIdentity(paths, { workspaceId, create: false });
   const file = statePath(paths, "session", sessionId);
   const durable = await readJsonIfPresent(file, root);
   if (durable !== null) {

package/node_modules/@agents-can-communicate/storage-filesystem/src/state-reads.mjs

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { AccError, EXIT, validateRecord } from "@agents-can-communicate/protocol";
+import { listDirectoryEntries, listJsonFiles, readJsonIfPresent } from "./atomic-json.mjs";
+import { assertStateBinding, statePath } from "./record-id.mjs";
+import { stateGenerationIsDeleted } from "./retention.mjs";
+import { assertPublicationDeadline } from "./deadline.mjs";
+
+export async function readStateEnvelope(paths, { root, workspaceId }, kind, id) {
+  const filePath = statePath(paths, kind, id);
+  const found = await readJsonIfPresent(filePath, root);
+  if (found === null) return null;
+  const envelope = assertStateBinding(found.value, kind, id, filePath);
+  if (await stateGenerationIsDeleted(paths, root, kind, id, envelope.generation)) return null;
+  validateRecord(kind, envelope.record);
+  if (workspaceId !== undefined && envelope.record.workspaceId !== workspaceId) {
+    throw new AccError(EXIT.DATA, "state record belongs to a different workspace",
+      { filePath, expected: workspaceId, actual: envelope.record.workspaceId });
+  }
+  return envelope;
+}
+
+export async function listState(paths, root, kind, deadlineAt) {
+  const envelopes = [];
+  for (const filePath of await listJsonFiles(path.join(paths.state, kind), { root })) {
+    assertPublicationDeadline(deadlineAt);
+    const envelope = await readStateEnvelope(paths, { root }, kind, path.basename(filePath, ".json"));
+    if (envelope !== null) envelopes.push(envelope);
+  }
+  return envelopes;
+}
+
+export async function loadStateEnvelopes(paths, { root, deadlineAt }, wanted = null) {
+  const loaded = new Map();
+  const kinds = (await listDirectoryEntries(paths.state, { root }))
+    .filter(entry => entry.isDirectory()).map(entry => entry.name)
+    .filter(kind => wanted === null || wanted.has(kind));
+  for (const kind of kinds) {
+    for (const envelope of await listState(paths, root, kind, deadlineAt)) {
+      loaded.set(`${envelope.kind}:${envelope.id}`, envelope);
+    }
+  }
+  return loaded;
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/store-migration.mjs

@@ -0,0 +1,56 @@
+import { AccError, EXIT, validateRecord } from "@agents-can-communicate/protocol";
+import { encode, listJsonFiles, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
+import { initialiseActiveJournal, readActiveJournal } from "./active-journal.mjs";
+import { assertPublicationDeadline } from "./deadline.mjs";
+import { identityPath, readMigrationIdentity, STORE_VERSION } from "./identity.mjs";
+import { createIndexCache } from "./index-cache.mjs";
+import { IndexCacheUnavailable } from "./index-pages.mjs";
+import { readOpenJournals, rollForward } from "./journal.mjs";
+import { assertEventBinding } from "./record-id.mjs";
+import { ensureManagedDirectory } from "./safe-directory.mjs";
+import { loadStateEnvelopes } from "./state-reads.mjs";
+import { storePaths } from "./store.mjs";
+import { withWriterMutex } from "./writer-mutex.mjs";
+
+/** Explicit library migration; the operator must quiesce unmanaged users first. */
+export async function migrateFilesystemStore({ root, workspaceId, clock, ids,
+  allowMigration = false, platform = process.platform, deadlineAt, failAt }) {
+  if (allowMigration !== true) {
+    throw new AccError(EXIT.USAGE, "store migration requires explicit opt-in after quiescing other users");
+  }
+  assertPublicationDeadline(deadlineAt);
+  const paths = storePaths(root), publishOptions = { root, tmpDir: paths.tmp, clock, platform, failAt };
+  await readMigrationIdentity(paths, workspaceId);
+  return withWriterMutex(paths, { ...publishOptions, deadlineAt }, async () => {
+    const identity = await readMigrationIdentity(paths, workspaceId), fromVersion = identity.storeVersion;
+    for (const directory of Object.values(paths)) await ensureManagedDirectory(root, directory);
+    await initialiseActiveJournal(paths, { ...publishOptions, deadlineAt });
+    for (const entry of await readOpenJournals(paths, root)) {
+      // A decided journal finishes even if the migration's pre-switch budget lapses.
+      await rollForward(paths, publishOptions, entry);
+    }
+    assertPublicationDeadline(deadlineAt);
+    const primaries = await loadStateEnvelopes(paths, { root, deadlineAt });
+    for (const file of await listJsonFiles(paths.events, { root })) {
+      assertPublicationDeadline(deadlineAt);
+      const found = await readJsonIfPresent(file, root);
+      if (found === null) continue;
+      const event = validateRecord("event", assertEventBinding(found.value, file));
+      if (event.workspaceId !== workspaceId) throw new AccError(EXIT.DATA, "event belongs to a different workspace");
+    }
+    const cache = createIndexCache({ paths, root, workspaceId, publishOptions, loadPrimary: async () => primaries });
+    try { await cache.rebuild(await readActiveJournal(paths, root), deadlineAt, { required: true }); }
+    catch (error) {
+      if (!(error instanceof IndexCacheUnavailable)) throw error;
+      throw new AccError(EXIT.DATA, "store migration could not publish its complete index", { reason: error.reason });
+    }
+    if (fromVersion !== STORE_VERSION) {
+      await failAt?.("before-store-version-switch");
+      assertPublicationDeadline(deadlineAt);
+      await publishAtomic(identityPath(paths), encode({ ...identity, storeVersion: STORE_VERSION }),
+        { ...publishOptions, deadlineAt, replace: true, durability: "full" });
+      await failAt?.("after-store-version-switch");
+    }
+    return { fromVersion, toVersion: STORE_VERSION, migrated: fromVersion !== STORE_VERSION };
+  });
+}