agents-can-communicate 0.9.0 → 0.10.0

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.0",
+  "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 };

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

@@ -2,7 +2,7 @@ import { AccError, EXIT, assertDecisionChange } from "@agents-can-communicate/pr
 
 // Resolve inherited recipients before retry comparison. Target messages and
 // their recipient sets are immutable, so receipt advancement cannot alter a retry.
-export function prepareDecisionChange(tx, input, session) {
+export async function prepareDecisionChange(tx, input, session) {
   if (input.decisionChange !== undefined) {
     throw new AccError(EXIT.USAGE, "send a decision change using supersedes or withdraws");
   }
@@ -15,22 +15,27 @@ export function prepareDecisionChange(tx, input, session) {
     messageIds: input.supersedes ?? input.withdraws,
   });
   decisionChange.messageIds = [...decisionChange.messageIds].sort();
-  const targets = decisionChange.messageIds.map(messageId => {
-    const message = tx.get("message", messageId);
+  const targets = [];
+  for (const messageId of decisionChange.messageIds) {
+    const message = await tx.load("message", messageId);
     if (message?.kind !== "decision" || message.workspaceId !== session.workspaceId) {
       throw new AccError(EXIT.DATA, "a decision change must reference existing decisions in this workspace",
         { messageId });
     }
-    return message;
-  });
+    targets.push(message);
+  }
   if (new Set(input.toParticipantIds).size !== input.toParticipantIds.length) {
     throw new AccError(EXIT.USAGE, "a participant may be addressed only once");
   }
-  const targetIds = new Set(decisionChange.messageIds);
-  const inherited = [...targets.map(message => message.fromParticipantId),
-    ...tx.list("receipt", receipt => targetIds.has(receipt.messageId))
-      .map(receipt => receipt.recipientParticipantId)]
-    .filter(participantId => participantId !== session.participantId);
+  const inherited = targets.map(message => message.fromParticipantId);
+  for (const message of targets) {
+    for (const id of await tx.lookup("receiptsByMessage", [session.workspaceId, message.messageId])) {
+      const receipt = await tx.load("receipt", id);
+      if (receipt !== null && receipt.workspaceId === session.workspaceId
+        && receipt.messageId === message.messageId) inherited.push(receipt.recipientParticipantId);
+    }
+  }
   return { ...input, decisionChange,
-    toParticipantIds: [...new Set([...input.toParticipantIds, ...inherited])].sort() };
+    toParticipantIds: [...new Set([...input.toParticipantIds,
+      ...inherited.filter(id => id !== session.participantId)])].sort() };
 }

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

@@ -2,6 +2,7 @@ import { AccError, EXIT, SCHEMA_VERSION, advanceReceipt }
   from "@agents-can-communicate/protocol";
 
 import { receiptId, recordMessageInTransaction } from "./conversations.mjs";
+import { assertExactTransaction } from "./ports.mjs";
 import { messagePage, messageSummary } from "./message-pages.mjs";
 import { decisionView, isCurrentDecision } from "./decision-state.mjs";
 
@@ -109,6 +110,10 @@ export function createInboxService(ports, sessions) {
     const session = await requireOpen(input, "acknowledge a message");
     const now = clock.now();
     return store.transaction(async tx => {
+      assertExactTransaction(tx);
+      await tx.load("session", input.sessionId);
+      await tx.load("message", input.messageId);
+      await tx.load("receipt", receiptId(input.messageId, session.participantId));
       await requireOpen(input, "acknowledge a message", tx);
       const { message, receipt } = requireOwnedReceipt(tx, session, input.messageId);
       if (message.obligation === "reply" && receipt.state !== "acknowledged") {
@@ -117,18 +122,21 @@ export function createInboxService(ports, sessions) {
           { messageId: input.messageId, obligation: message.obligation });
       }
       return advanceOwned(tx, session, input.messageId, "acknowledged", now).receipt;
-    }, { kinds: ["session", "message", "receipt"] });
+    }, { kinds: ["session", "message", "receipt"], exactKinds: ["session", "message", "receipt"] });
   }
 
   async function replyToMessage(input) {
     const session = await requireOpen(input, "reply to a message");
     const now = clock.now();
     const replyId = ids.next("message");
-    return store.transaction(tx => {
+    return store.transaction(async tx => {
+      assertExactTransaction(tx);
+      await tx.load("message", input.messageId);
+      await tx.load("receipt", receiptId(input.messageId, session.participantId));
       const original = requireOwnedReceipt(tx, session, input.messageId);
       // A receipt settles delivery, not the conversation. Distinct replies may
       // follow an ack or an earlier answer; recording still enforces retry keys.
-      const recorded = recordMessageInTransaction({ tx, session, now, messageId: replyId, ids,
+      const recorded = await recordMessageInTransaction({ tx, session, now, messageId: replyId, ids,
         action: "reply to a message", input: {
           clientMessageId: input.clientMessageId,
           toParticipantIds: [original.message.fromParticipantId],
@@ -142,7 +150,7 @@ export function createInboxService(ports, sessions) {
         } });
       const receipt = advanceOwned(tx, session, input.messageId, "acknowledged", now).receipt;
       return { reply: recorded.message, receipt };
-    }, { kinds: ["participant", "session", "message", "receipt"] });
+    }, { kinds: ["participant", "session", "message", "receipt"], exactKinds: ["message", "receipt"] });
   }
 
   return { listInbox, readInbox, replyToMessage, acknowledgeMessage };

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

@@ -0,0 +1,43 @@
+import { isDeepStrictEqual } from "node:util";
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+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,
+});
+
+export async function findMessageRetry(tx, session, input) {
+  const candidates = await tx.lookup("messageByClientKey",
+    [session.workspaceId, session.participantId, input.clientMessageId]);
+  for (const id of candidates) {
+    const existing = await tx.load("message", id);
+    if (existing === null || existing.workspaceId !== session.workspaceId
+      || existing.fromParticipantId !== session.participantId
+      || existing.clientMessageId !== input.clientMessageId) continue;
+    if (!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;
+  }
+}

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

@@ -4,12 +4,14 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
  * @typedef {{ now(): string }} Clock
  * @typedef {{ next(kind: string): string }} IdSource
  * @typedef {{ get(kind: string, id: string): object | null,
+ *   load(kind: string, id: string): Promise<object | null>,
+ *   lookup(index: string, tuple: string[]): Promise<string[]>,
  *   generationOf(kind: string, id: string): string | null,
  *   list(kind: string, predicate?: (record: object) => boolean): object[],
  *   put(kind: string, id: string, record: object, expectedGeneration?: string | null): string,
  *   append(event: object): object }} CoordinationTransaction
  * @typedef {{ transaction(callback: (tx: CoordinationTransaction) => unknown,
- *   options?: { kinds?: string[], deadlineAt?: number }): Promise<unknown>,
+ *   options?: { kinds?: string[], exactKinds?: string[], deadlineAt?: number }): Promise<unknown>,
  *   eventsSince(workspaceId: string, cursor: string | null, limit: number): Promise<object>,
  *   snapshot(workspaceId: string): Promise<object> }} CoordinationStore
  */
@@ -26,6 +28,15 @@ const REQUIRED = Object.freeze({
 // vanish with their session.
 const EPHEMERAL = ["get", "put", "update", "delete", "list"];
 
+export function assertExactTransaction(tx) {
+  for (const method of ["load", "lookup"]) {
+    if (typeof tx?.[method] !== "function") {
+      throw new AccError(EXIT.USAGE, `the exact transaction port must implement ${method}()`,
+        { port: "store.transaction", method });
+    }
+  }
+}
+
 // Ports are validated at construction rather than at first use. A core that
 // silently falls back to ambient time or randomness produces tests that pass
 // for the wrong reason and races that only appear on someone else's machine.