agents-can-communicate 0.9.1 → 0.10.0

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,4 +1,7 @@
 import { createHash } from "node:crypto";
+// 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 } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -31,7 +34,11 @@ 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;
@@ -39,20 +46,26 @@ async function isMcpContinuity(record, name, workspaceRoot, workspaceId) {
 }
 
 /** 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)
@@ -78,9 +91,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/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.0",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/core/src/conversations.mjs

@@ -1,54 +1,17 @@
 import { createHash } from "node:crypto";
-import { isDeepStrictEqual } from "node:util";
 import { AccError, EXIT, SCHEMA_VERSION, validateRecord }
   from "@agents-can-communicate/protocol";
 
 import { projectReleasedClaim, reconstructFinishRetry } from "./finish-retries.mjs";
 import { ensureMaterialised } from "./materialisation.mjs";
 import { nextTurnDelivery as selectNextTurnDelivery } from "./next-turn-delivery.mjs";
+import { assertExactTransaction } from "./ports.mjs";
+import { findMessageRetry } from "./message-retry.mjs";
 import { prepareDecisionChange } from "./decision-changes.mjs";
 
 export const receiptId = (messageId, participantId) => `receipt_${createHash("sha256")
   .update(JSON.stringify([messageId, participantId])).digest("base64url")}`;
 
-const logicalContent = message => ({
-  toParticipantIds: message.toParticipantIds,
-  kind: message.kind,
-  obligation: message.obligation,
-  subject: message.subject,
-  body: message.body,
-  inReplyTo: message.inReplyTo,
-  artifacts: message.artifacts,
-  handoff: message.handoff,
-  decisionChange: message.decisionChange ?? null,
-});
-
-const normalizedContent = input => logicalContent({
-  toParticipantIds: input.toParticipantIds ?? [],
-  kind: input.kind,
-  obligation: input.obligation,
-  subject: input.subject,
-  body: input.body,
-  inReplyTo: input.inReplyTo ?? null,
-  artifacts: input.artifacts ?? [],
-  handoff: input.handoff ?? null,
-  decisionChange: input.decisionChange,
-});
-
-function existingMessage(tx, session, input) {
-  const existing = tx.list("message", message =>
-    message.workspaceId === session.workspaceId
-    && message.fromParticipantId === session.participantId
-    && message.clientMessageId === input.clientMessageId).at(0);
-  if (existing !== undefined
-    && !isDeepStrictEqual(logicalContent(existing), normalizedContent(input))) {
-    throw new AccError(EXIT.CONFLICT,
-      "clientMessageId was already used with different message content",
-      { clientMessageId: input.clientMessageId, messageId: existing.messageId });
-  }
-  return existing;
-}
-
 function assertCurrentSession(tx, session, action) {
   const current = tx.get("session", session.sessionId);
   if (current === null || current.state !== "open"
@@ -114,9 +77,9 @@ function addressedRecipients(tx, message, session) {
   return unique;
 }
 
-function threadFor(tx, messageId, inReplyTo) {
+async function threadFor(tx, messageId, inReplyTo) {
   if (inReplyTo === null) return messageId;
-  const parent = tx.get("message", inReplyTo);
+  const parent = await tx.load("message", inReplyTo);
   if (parent === null) {
     throw new AccError(EXIT.DATA, "the message being replied to does not exist",
       { inReplyTo });
@@ -124,15 +87,16 @@ function threadFor(tx, messageId, inReplyTo) {
   return parent.threadId;
 }
 
-export function recordMessageInTransaction({ tx, session, input: raw, now, messageId, ids,
+export async function recordMessageInTransaction({ tx, session, input: raw, now, messageId, ids,
   action = "send a message" }) {
+  assertExactTransaction(tx);
   assertCurrentSession(tx, session, action);
   // Resolved before anything else reads the recipients, so the stored message
   // names real participants and a retry compares against the same content. A
   // record that kept the client name would address nobody when it is read back.
-  const input = prepareDecisionChange(tx, { ...raw,
+  const input = await prepareDecisionChange(tx, { ...raw,
     toParticipantIds: resolveAddressees(tx, raw.toParticipantIds ?? [], session) }, session);
-  const existing = existingMessage(tx, session, input);
+  const existing = await findMessageRetry(tx, session, input);
   if (existing !== undefined) {
     return { message: existing, recipientParticipantIds: [], created: false };
   }
@@ -141,7 +105,7 @@ export function recordMessageInTransaction({ tx, session, input: raw, now, messa
   const message = validateRecord("message", {
     schemaVersion: SCHEMA_VERSION,
     messageId,
-    threadId: threadFor(tx, messageId, inReplyTo),
+    threadId: await threadFor(tx, messageId, inReplyTo),
     clientMessageId: input.clientMessageId,
     workspaceId: session.workspaceId,
     fromParticipantId: session.participantId,
@@ -158,8 +122,10 @@ export function recordMessageInTransaction({ tx, session, input: raw, now, messa
     sentAt: now,
   });
   const recipientParticipantIds = addressedRecipients(tx, message, session);
+  await tx.load("message", messageId);
   tx.put("message", messageId, message);
   for (const participantId of recipientParticipantIds) {
+    await tx.load("receipt", receiptId(messageId, participantId));
     tx.put("receipt", receiptId(messageId, participantId), validateRecord("receipt", {
       schemaVersion: SCHEMA_VERSION,
       messageId,
@@ -202,9 +168,9 @@ export function createConversationService(ports, sessions) {
     const session = await requireSession(input, "send a message");
     await ensureMaterialised(ports, { workspaceId: session.workspaceId,
       descriptor: input.descriptor, reason: "durable_object" });
-    return store.transaction(tx => recordMessageInTransaction({ tx, session, input,
-      now: clock.now(), messageId: ids.next("message"), ids }).message,
-    { kinds: ["participant", "session", "message", "receipt"] });
+    return store.transaction(async tx => (await recordMessageInTransaction({ tx, session, input,
+      now: clock.now(), messageId: ids.next("message"), ids })).message,
+    { kinds: ["participant", "session", "message", "receipt"], exactKinds: ["message", "receipt"] });
   }
 
   async function finishSession(input) {
@@ -235,13 +201,15 @@ export function createConversationService(ports, sessions) {
       handoff,
     };
     const now = clock.now();
-    const outcome = await store.transaction(tx => {
+    const outcome = await store.transaction(async tx => {
+      assertExactTransaction(tx);
       const current = tx.get("session", session.sessionId);
       if (current === null || current.generation !== session.generation) {
         throw new AccError(EXIT.CONFLICT, "cannot finish from this session generation",
           { sessionId: session.sessionId });
       }
-      const existing = existingMessage(tx, session, messageInput);
+      const existing = await findMessageRetry(tx, session, { ...messageInput,
+        toParticipantIds: resolveAddressees(tx, messageInput.toParticipantIds, session) });
       if (existing !== undefined) {
         if (existing.fromSessionId !== session.sessionId) {
           throw new AccError(EXIT.CONFLICT,
@@ -256,7 +224,7 @@ export function createConversationService(ports, sessions) {
       }
       const releasedClaims = tx.list("claim",
         claim => claim.ownerSessionId === session.sessionId);
-      const recorded = recordMessageInTransaction({ tx, session, now,
+      const recorded = await recordMessageInTransaction({ tx, session, now,
         messageId: ids.next("message"), ids, action: "finish",
         input: messageInput });
       for (const claim of releasedClaims) {
@@ -278,7 +246,8 @@ export function createConversationService(ports, sessions) {
           releasedClaimIds: releasedClaims.map(claim => claim.claimId) } });
       return { retry: false, message: recorded.message,
         releasedClaims: releasedClaims.map(projectReleasedClaim), session: closed };
-    }, { kinds: ["participant", "session", "claim", "message", "receipt"] });
+    }, { kinds: ["participant", "session", "claim", "message", "receipt"],
+      exactKinds: ["message", "receipt"] });
     if (!outcome.retry) {
       return { message: outcome.message, releasedClaims: outcome.releasedClaims,
         session: outcome.session };