agents-can-communicate 0.1.16 → 0.1.18

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

@@ -0,0 +1,41 @@
+// A note is fire-and-forget: shown to the recipient once, no acknowledgement
+// owed, no standing reminder. Agents put decisions and warnings in notes anyway
+// - in one measured session a note carrying a merge decision was lost for three
+// hours - so this is the send-time tell that a note is waiting on a reply and
+// should have gone out as a question (`--requires-ack`) or a decision.
+//
+// A nudge, never a block, and deliberately not a keyword list: keyword lists
+// only fire in the language they were written in, and the agents here write in
+// several. A question mark marks a question in every script, and the warning
+// sign is the one glyph a peer reaches for when something must not be missed.
+const QUESTION = /[?？]/u;
+const WARNING = /⚠/u;
+
+/**
+ * Does this note read like it needs a response from the recipient?
+ *
+ * Pure and total: a missing subject or body is empty text, not an error, so the
+ * caller can hand it a message record without pre-checking its shape.
+ */
+export function looksConsequential({ subject = "", body = "" } = {}) {
+  const text = `${subject}\n${body}`;
+  return QUESTION.test(text) || WARNING.test(text);
+}
+
+const NUDGE = "this note reads like it needs a reply, but a note is fire-and-forget: "
+  + "the recipient sees it once and owes no response. Re-send with --requires-ack "
+  + "for an answer, or record it with `acc decide`.";
+
+/**
+ * The send-time advisory for a note that looks like it is waiting on a reply,
+ * or null when there is nothing to say.
+ *
+ * Only notes, and only ones the sender did not already mark `requiresAck`: a
+ * question already keeps a standing reminder, and nudging it would be noise.
+ * A nudge, never a block - the send has already happened; this only tells the
+ * sender the shape it chose does not carry the weight the words do.
+ */
+export function noteNudge(message) {
+  return message?.type === "note" && message?.requiresAck !== true
+    && looksConsequential(message ?? {}) ? NUDGE : null;
+}

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

@@ -23,7 +23,7 @@ const REQUIRED = Object.freeze({
 // are storage too, so they hang off the store rather than becoming a fourth
 // port. They are deliberately outside transactions: they append no events and
 // vanish with their session.
-const EPHEMERAL = ["get", "put", "delete", "list"];
+const EPHEMERAL = ["get", "put", "update", "delete", "list"];
 
 // 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

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

@@ -1,6 +1,7 @@
 import { createClaimService } from "./claims.mjs";
 import { createCommunicationService } from "./communication.mjs";
 import { createIntentService } from "./intents.mjs";
+import { createInboxService } from "./inbox.mjs";
 import { defaultPidIsAlive } from "./pid.mjs";
 import { assertPorts } from "./ports.mjs";
 import { createSessionService } from "./sessions.mjs";
@@ -32,6 +33,7 @@ export function createCoordinationService({ store, clock, ids,
   const tasks = createTaskService(ports, workstreams);
   const claims = createClaimService(ports, sessions);
   const communication = createCommunicationService(ports, sessions, claims);
+  const inbox = createInboxService(ports, sessions);
   const sync = createSyncService(ports, sessions);
   const status = createStatusService(ports, sessions);
   const guardState = createGuardStateService(ports);
@@ -46,6 +48,7 @@ export function createCoordinationService({ store, clock, ids,
     ...tasks,
     ...claims,
     ...communication,
+    ...inbox,
     ...sync,
     ...status,
     guardState,

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

@@ -179,6 +179,53 @@ export function createSessionService(ports) {
     return beaten;
   }
 
+  /**
+   * Continue the exact session named by a harness binding.
+   *
+   * Some clients emit SessionStart again after compacting their model context.
+   * The binding is already the continuation token: it names both the session
+   * and its generation. Refreshing that record preserves one identity without
+   * pretending an unrelated or closed generation is still ours.
+   *
+   * Returns null when the binding can no longer be resumed, so the hook may
+   * open a genuinely new session. No semantic event is appended: compaction is
+   * not a second agent arriving.
+   */
+  async function resumeSession({ sessionId, workspaceId, generation, ...metadata }) {
+    const resume = current => {
+      if (current === null || current.state !== "open"
+        || current.generation !== generation) return null;
+      return { ...current,
+      pid: metadata.pid ?? null,
+      checkoutRoot: metadata.checkoutRoot ?? current.checkoutRoot,
+      branch: metadata.branch ?? current.branch,
+      enforcement: metadata.enforcement ?? current.enforcement,
+      lifecycle: metadata.lifecycle ?? current.lifecycle,
+      heartbeatCadenceMs: metadata.heartbeatCadenceMs ?? current.heartbeatCadenceMs,
+      heartbeatAt: clock.now(),
+      };
+    };
+
+    // The compare and replacement happen under the ephemeral store's writer
+    // lock. A close or a replacement generation can win before this update or
+    // after it, but can never be overwritten from a record read beforehand.
+    const ephemeral = await store.ephemeral.update("session", sessionId, resume);
+    if (ephemeral !== null) return ephemeral;
+
+    // Re-read and validate inside the durable transaction for the same reason.
+    // Using generationOf only as the put token is insufficient: it protects
+    // the envelope write, not the semantic generation carried by the record.
+    const resolvedWorkspace = workspaceId ?? store.workspaceId;
+    if (resolvedWorkspace === undefined) return null;
+    return store.transaction(async tx => {
+      const current = tx.get("session", sessionId);
+      const resumed = resume(current);
+      if (resumed === null) return null;
+      tx.put("session", sessionId, resumed, tx.generationOf("session", sessionId));
+      return resumed;
+    }, { kinds: ["session"] });
+  }
+
   async function closeSession({ sessionId, workspaceId, generation }) {
     const existing = await locate(sessionId, workspaceId);
     if (existing === null) throw new AccError(EXIT.CONFLICT, "session is not open", { sessionId });
@@ -222,6 +269,7 @@ export function createSessionService(ports) {
 
   return {
     openSession,
+    resumeSession,
     heartbeatSession,
     closeSession,
     locateSession: locate,

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

@@ -46,6 +46,7 @@ export const ATTENTION_PRIORITY = Object.freeze({
   request_stalled: 5,
   claim_expired: 6,
   claim_contended: 7,
+  unread_note: 8,
 });
 
 function directRequests(snapshot, participantId) {
@@ -61,6 +62,40 @@ function directRequests(snapshot, participantId) {
   return items;
 }
 
+/**
+ * A note that was delivered once and then left unanswered.
+ *
+ * A `note` carries no acknowledgement obligation, so unlike a `requiresAck`
+ * message it raises no direct_request and, once injected, drops out of the
+ * inbox for good. Agents put decisions in notes anyway, and one delivered that
+ * way was missed for three hours because nothing stood behind it. This is the
+ * single low-priority breadcrumb that keeps a delivered-but-unacknowledged note
+ * recoverable: it fires only while the receipt reads `injected`, so the runner
+ * advancing it to `seen` after one showing makes it one-shot rather than a
+ * standing nag - the very noise a reader learns to skip. A `queued` note is
+ * about to be shown in full this turn and needs no breadcrumb yet.
+ *
+ * Only the recipient's, and named by message id so `acc inbox --message` or
+ * `acc ack --message` can act on it without a workspace-wide lookup.
+ */
+function unreadNotes(snapshot, participantId) {
+  const items = [];
+  for (const receipt of snapshot.receipts ?? []) {
+    if (receipt.recipientParticipantId !== participantId) continue;
+    if (receipt.state !== "injected") continue;
+    const message = (snapshot.messages ?? [])
+      .find(item => item.messageId === receipt.messageId);
+    // A requiresAck message already carries a standing direct_request; a second
+    // line here would be two reminders for one obligation.
+    if (message === undefined || message.requiresAck) continue;
+    items.push({ kind: "unread_note", priority: ATTENTION_PRIORITY.unread_note,
+      sourceId: message.messageId,
+      summary: `a note you have not acknowledged - \`acc inbox --message `
+        + `${message.messageId}\` to read it` });
+  }
+  return items;
+}
+
 /**
  * A claim of yours that has run out.
  *
@@ -245,6 +280,7 @@ export function computeAttention(snapshot, { session, participantId, now, pidIsA
   }
   return [
     ...directRequests(snapshot, participantId),
+    ...unreadNotes(snapshot, participantId),
     ...claimConflicts(snapshot, session, now),
     ...claimContended(snapshot, session, now),
     ...expiredClaims(snapshot, session, now),

package/node_modules/@agents-can-communicate/hook-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/hook-runner/src/runner.mjs

@@ -13,6 +13,11 @@ import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
 import { resolveClientPid } from "./client-pid.mjs";
 import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
 
+// Kept cohesive above 300 lines because every handler shares one fail-open
+// hook boundary, binding lifecycle, and client-specific outcome contract.
+// Splitting handlers would duplicate that safety boundary and make delivery or
+// guard failures behave differently by event kind.
+
 // A hook runs in front of the user's turn, so it gets a hard ceiling. Better to
 // let a call through than to make someone's session sit waiting on us.
 const DEFAULT_BUDGET_MS = 5_000;
@@ -157,7 +162,8 @@ async function openContext({ cwd, dataHome, runtime, env }) {
 }
 
 const HANDLERS = {
-  async sessionStart({ event, context, adapter, adapterId, paths, readProcessTable }) {
+  async sessionStart({ event, context, adapter, adapterId, binding, paths,
+    readProcessTable }) {
     const capabilities = adapter.capabilities ?? {};
     // Once per session, never per turn. A client that cannot be found yields
     // null, and the session is then judged by age alone - which is exactly the
@@ -165,6 +171,24 @@ const HANDLERS = {
     const command = adapter.client?.command ?? null;
     const pid = command === null ? null
       : resolveClientPid({ table: await readProcessTable(), from: process.pid, command });
+    const metadata = {
+      pid,
+      enforcement: capabilities.guards?.beforeWrite === true ? "guarded" : "advisory",
+      lifecycle: capabilities.lifecycle?.sessionEnd === true ? "managed" : "manual",
+      heartbeatCadenceMs: CADENCE_MS,
+      checkoutRoot: context.descriptor.git?.worktreeRoot ?? context.descriptor.roots[0],
+      branch: context.descriptor.git?.branch ?? null,
+    };
+    if (binding !== null) {
+      const resumed = await context.service.resumeSession({
+        sessionId: binding.accSessionId,
+        generation: binding.generation,
+        ...metadata,
+      });
+      if (resumed !== null) {
+        return { accSessionId: resumed.sessionId, generation: resumed.generation };
+      }
+    }
     const session = await context.service.openSession({
       workspaceId: context.descriptor.id,
       participantId: participantFor(adapterId, event.sessionId, context.env),
@@ -174,14 +198,9 @@ const HANDLERS = {
       // Declared from what this adapter proved, not from the fact that it is an
       // adapter at all. A peer reading the roster can then tell a session whose
       // writes can be stopped from one whose cannot.
-      enforcement: capabilities.guards?.beforeWrite === true ? "guarded" : "advisory",
-      lifecycle: capabilities.lifecycle?.sessionEnd === true ? "managed" : "manual",
-      heartbeatCadenceMs: CADENCE_MS,
       // Which checkout this agent is in. One workspace spans every worktree of
       // a repository, so this is the only thing that distinguishes them.
-      checkoutRoot: context.descriptor.git?.worktreeRoot ?? context.descriptor.roots[0],
-      pid,
-      branch: context.descriptor.git?.branch ?? null,
+      ...metadata,
       descriptor: context.descriptor,
     });
     await storeSessionBinding({ runtimeDir: paths.root, harnessSessionId: event.sessionId,
@@ -213,27 +232,11 @@ const HANDLERS = {
     const sync = await context.service.sync({ sessionId: binding.accSessionId,
       cursor: null, scope: "delta" });
 
-    // Claims held by others, and whether this session can actually be stopped
-    // from breaking them. For a harness that guards writes this is useful
-    // warning; for one that cannot - a Codex model editing through the shell,
-    // an MCP client - it is the only protection there is, so it has to say
-    // plainly that the responsibility has moved to the session itself.
-    const status = await context.service.collectStatus({
-      workspaceId: context.descriptor.id });
-    const mine = status.participants
+    // Sync already carries the roster. Calling collectStatus here used to read
+    // the entire materialised store a second time on every prompt merely to
+    // rediscover this session's participant id.
+    const mine = sync.roster
       .find(participant => participant.sessionId === binding.accSessionId);
-    // Two independent facts, and both are needed. `enforceable` is whether ACC
-    // could stop *this* session at all; `enforcement` is what the claim's owner
-    // asked for. A guarded session facing an advisory claim is not blocked from
-    // anything, so reporting either one alone mislabels the other case.
-    const enforceable = mine?.enforcement === "guarded";
-    const claims = status.claims
-      .filter(claim => claim.ownerSessionId !== binding.accSessionId)
-      .map(claim => ({ resource: claim.resource, enforcement: claim.enforcement,
-        enforceable,
-        ownerParticipantId: status.participants
-          .find(p => p.sessionId === claim.ownerSessionId)?.participantId
-          ?? claim.ownerSessionId }));
 
     // What peers have said to this participant and no model has been shown yet.
     // Without this the projector's peer block never ran in production: an agent
@@ -254,31 +257,72 @@ const HANDLERS = {
     // The ceiling a team agreed on in `acc.workspace.json`, or the default when
     // there is no config. Validated by the protocol and, until now, never read:
     // the projector was always called with its own default.
-    const projected = await adapter.renderContext?.({ ...sync, claims, messages },
-      { budgetBytes: context.descriptor.policy?.contextBudgetBytes }) ?? "";
-    if (projected === "") return { stdout: "" };
+    const tracksDelivery = typeof adapter.renderContextResult === "function";
+    const projectionInput = { ...sync, messages: tracksDelivery ? messages : [],
+      currentParticipantId: mine?.participantId };
+    const projectionOptions = {
+      budgetBytes: context.descriptor.policy?.contextBudgetBytes };
+    // Delivery is state, not text parsing. Peer-controlled bodies can imitate
+    // another message's visible header, so only projector metadata proves
+    // which complete groups survived the byte budget. A custom adapter without
+    // metadata may still inject text, but cannot advance a receipt from it.
+    const projection = !tracksDelivery
+      ? { text: await adapter.renderContext?.(projectionInput, projectionOptions) ?? "",
+        includedMessageIds: [], includedAttentionIds: [] }
+      : await adapter.renderContextResult(projectionInput, projectionOptions);
+    const degradation = !tracksDelivery && messages.length > 0
+      ? `acc: ${messages.length} pending message(s) withheld because this adapter lacks `
+        + `structured delivery metadata; read ${messages[0].messageId} with `
+        + `acc inbox --message ${messages[0].messageId}`
+      : null;
+    const visibleDegradation = degradation === null ? "" : `ACC: ${degradation.slice(5)}`;
+    const candidate = [projection.text, visibleDegradation].filter(Boolean).join("\n");
+    const projected = Buffer.byteLength(candidate, "utf8")
+      <= (projectionOptions.budgetBytes ?? 6_000) ? candidate : projection.text;
+    if (projected === "") {
+      return degradation === null ? { stdout: "" } : { stdout: "", stderr: degradation };
+    }
 
     // Only what the model was actually shown is recorded as delivered. The
     // budget can leave a message out, and a receipt reading `injected` for text
     // nobody saw is worse than one still reading `queued` - the sender would be
     // told it landed. A message left behind stays queued and goes out next turn.
     const failures = [];
+    const includedMessages = new Set(projection.includedMessageIds ?? []);
     for (const message of messages) {
-      if (!projected.includes(message.messageId)) continue;
+      if (!includedMessages.has(message.messageId)) continue;
       await context.service.markDelivery({ sessionId: binding.accSessionId,
         generation: binding.generation, messageId: message.messageId,
         recipientParticipantId: mine.participantId, state: "injected" })
         .catch(error => failures.push(`${message.messageId}: ${error.message}`));
     }
+    // A note carries no ack obligation, so after its one full showing it leaves
+    // a single low-priority `unread_note` breadcrumb. Advancing that receipt
+    // injected -> seen the turn the breadcrumb is shown is what makes it
+    // one-shot: next turn the note reads `seen`, the breadcrumb stays quiet, and
+    // a delivered decision is recoverable without becoming a standing nag - the
+    // noise a reader learns to skip. Only what was actually shown is advanced,
+    // for the same reason the loop above only records what fit.
+    const includedAttention = new Set(projection.includedAttentionIds ?? []);
+    for (const item of sync.attention ?? []) {
+      if (item.kind !== "unread_note") continue;
+      if (!includedAttention.has(item.sourceId)) continue;
+      await context.service.markDelivery({ sessionId: binding.accSessionId,
+        generation: binding.generation, messageId: item.sourceId,
+        recipientParticipantId: mine.participantId, state: "seen" })
+        .catch(error => failures.push(`${item.sourceId}: ${error.message}`));
+    }
     // Same again: Kimi Code shows the model a hook's raw stdout, while Gemini
     // and Claude Code want an envelope and drop a bare string.
     // Reported rather than swallowed. The context still goes out - losing it
     // over bookkeeping would be the worse trade - but a receipt that failed to
     // advance has to be visible somewhere, and stdout belongs to the model.
     const outcome = { stdout: "", ...adapter.injectOutcome?.(projected) };
-    if (failures.length === 0) return outcome;
+    if (failures.length === 0 && degradation === null) return outcome;
     return { ...outcome,
-      stderr: [outcome.stderr, `acc: delivery not recorded for ${failures.join(", ")}`]
+      stderr: [outcome.stderr, degradation,
+        failures.length === 0 ? null
+          : `acc: delivery not recorded for ${failures.join(", ")}`]
         .filter(Boolean).join("\n") };
   },
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "private": true,
   "type": "module",
   "exports": { ".": "./src/index.mjs" },

package/node_modules/@agents-can-communicate/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/mcp-server",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/mcp-server/src/server.mjs

@@ -1,4 +1,5 @@
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
+import { noteNudge } from "@agents-can-communicate/core";
 import { clearSessionBinding, loadSessionBinding, storeSessionBinding }
   from "@agents-can-communicate/adapter-sdk";
 
@@ -71,6 +72,22 @@ async function resolveSession(context) {
   return session;
 }
 
+// Kept for clients released before acc_inbox existed. New clients should use
+// the narrow inbox tool, but removing mail from acc_sync would strand deployed
+// clients that only know this response field. Returning a body is delivery, so
+// only those returned messages advance to injected.
+async function syncWithMail(service, owner, context, args) {
+  const sync = await service.sync({ ...owner, cursor: args.cursor ?? null,
+    scope: args.scope, limit: args.limit });
+  const messages = await service.pendingMessages({ workspaceId: context.workspaceId,
+    participantId: context.participantId, exceptSessionId: owner.sessionId });
+  for (const message of messages) {
+    await service.markDelivery({ ...owner, messageId: message.messageId,
+      state: "injected" }).catch(() => null);
+  }
+  return messages.length === 0 ? sync : { ...sync, messages };
+}
+
 /**
  * A poll is this client's turn.
  *
@@ -89,25 +106,6 @@ async function resolveSession(context) {
  * Acknowledgement stays a separate act, because being shown something is not
  * agreeing to it.
  */
-async function syncWithMail(service, owner, context, args) {
-  const sync = await service.sync({ ...owner, cursor: args.cursor ?? null,
-    scope: args.scope, limit: args.limit });
-  const messages = await service.pendingMessages({
-    workspaceId: context.workspaceId,
-    participantId: context.participantId,
-    exceptSessionId: owner.sessionId });
-  if (messages.length === 0) return sync;
-
-  for (const message of messages) {
-    // One failure must not swallow the rest: the client is holding the message
-    // either way, and a receipt that cannot be written is not a reason to hide
-    // what a peer said.
-    await service.markDelivery({ ...owner, messageId: message.messageId,
-      state: "injected" }).catch(() => null);
-  }
-  return { ...sync, messages };
-}
-
 async function callTool(name, args, context) {
   const session = await resolveSession(context);
   const owner = { sessionId: session.sessionId, generation: session.generation,
@@ -130,11 +128,21 @@ async function callTool(name, args, context) {
       return service.acquireClaim({ ...owner, resource: args.resource,
         mode: args.mode ?? "exclusive", enforcement: "advisory",
         reason: args.reason ?? "unspecified", leaseSeconds: args.leaseSeconds });
-    case "acc_message":
-      return service.sendMessage({ ...owner, toParticipantIds: args.to ?? [],
+    case "acc_message": {
+      const message = await service.sendMessage({ ...owner, toParticipantIds: args.to ?? [],
         subject: args.subject, body: args.body, type: args.type ?? "note",
         priority: args.priority, requiresAck: args.requiresAck === true,
         workstreamId: args.workstreamId ?? null });
+      // A note that reads like it wants a reply was sent fire-and-forget; hand
+      // the nudge back with the message so the model that sent it can reconsider.
+      const advice = noteNudge(message);
+      return advice ? { ...message, advice } : message;
+    }
+    case "acc_inbox":
+      return service.readInbox({ ...owner, messageId: args.messageId });
+    case "acc_reply":
+      return service.replyToMessage({ ...owner, messageId: args.messageId,
+        body: args.body, subject: args.subject, type: args.type, priority: args.priority });
     case "acc_task":
       if (args.action === "claim") return service.claimTask({ ...owner,
         taskId: args.taskId, force: args.force === true });

package/node_modules/@agents-can-communicate/mcp-server/src/tools.mjs

@@ -24,7 +24,8 @@ export const PUBLIC_TOOLS = Object.freeze([
     name: "acc_sync",
     description: `Read coordination state for this workspace: roster, attention items, and `
       + `events since a cursor. Use scope "full" to answer questions about the whole `
-      + `workspace, including other participants' collapsed child sessions. ${POLLED}`,
+      + `workspace, including other participants' collapsed child sessions. Pending mail is `
+      + `also returned for compatibility; prefer acc_inbox for targeted reads. ${POLLED}`,
     inputSchema: object({
       cursor: string("Resume from this cursor; omit to start from the beginning."),
       scope: { type: "string", enum: ["delta", "full"],
@@ -81,6 +82,29 @@ export const PUBLIC_TOOLS = Object.freeze([
       workstreamId: string("Optional workstream context."),
     }, ["to", "subject", "body"]),
   },
+  {
+    name: "acc_inbox",
+    description: `Read unresolved messages addressed to this participant without loading `
+      + `the roster, event log, claims, or workspace snapshot. Optionally select one id. `
+      + `${POLLED}`,
+    inputSchema: object({
+      messageId: string("Read exactly this addressed message; omit for all unresolved mail."),
+    }),
+  },
+  {
+    name: "acc_reply",
+    description: `Reply to one addressed message and acknowledge the original in the same `
+      + `operation. The reply is attributed, linked with inReplyTo, and delivered by polling. `
+      + `${POLLED}`,
+    inputSchema: object({
+      messageId: string("The addressed message being answered."),
+      body: string("Concise answer; peer content is treated as data."),
+      subject: string("Optional subject; defaults to Re: the original subject."),
+      type: { type: "string", enum: ["answer", "contract_response", "decision_result",
+        "review_result", "work_response"] },
+      priority: { type: "string", enum: ["low", "normal", "high", "urgent"] },
+    }, ["messageId", "body"]),
+  },
   {
     name: "acc_request",
     description: `Ask another agent to do something. Creates the work addressed to them `

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/protocol",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/storage-filesystem/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -12,6 +12,10 @@ import { assertEventBinding, assertStateBinding, eventPath, stateEnvelope, state
 import { ensureManagedDirectory } from "./safe-directory.mjs";
 import { withWriterMutex } from "./writer-mutex.mjs";
 
+// Kept cohesive above 300 lines because durable transactions and ephemeral
+// mutations must share this exact writer mutex. Splitting the two stores would
+// make it easy to reintroduce separate locks and resurrect replaced sessions.
+
 const SEQUENCE_WIDTH = 16;
 export const ZERO_CURSOR = "0".repeat(SEQUENCE_WIDTH);
 // No quarantine area. One was created in every workspace, named in the path
@@ -260,22 +264,34 @@ export async function openFilesystemStore({ root, clock, ids, workspaceId, failA
       handoffs: await of("handoff"),
     };
   }
-
   // Ephemeral records are published by replace and never journalled: they carry
   // no history, append no events, and are expected to disappear.
   const ephemeralPath = (kind, id) => path.join(paths.ephemeral, kind, `${id}.json`);
   const ephemeral = Object.freeze({
     async get(kind, id) {
-      const found = await readJsonIfPresent(ephemeralPath(kind, id), root);
-      return found?.value ?? null;
+      return (await readJsonIfPresent(ephemeralPath(kind, id), root))?.value ?? null;
     },
     async put(kind, id, record) {
-      await publishAtomic(ephemeralPath(kind, id), encode(record),
-        { root, tmpDir: paths.tmp, replace: true });
-      return record;
+      return withWriterMutex(paths, publishOptions, async () => {
+        await publishAtomic(ephemeralPath(kind, id), encode(record),
+          { root, tmpDir: paths.tmp, replace: true });
+        return record;
+      });
+    },
+    async update(kind, id, updater) {
+      return withWriterMutex(paths, publishOptions, async () => {
+        const found = await readJsonIfPresent(ephemeralPath(kind, id), root);
+        const next = await updater(found?.value ?? null);
+        if (next === null) return null;
+        validateRecord(kind, next);
+        await publishAtomic(ephemeralPath(kind, id), encode(next),
+          { root, tmpDir: paths.tmp, replace: true });
+        return next;
+      });
     },
     async delete(kind, id) {
-      await removeIfPresent(ephemeralPath(kind, id));
+      return withWriterMutex(paths, publishOptions,
+        async () => removeIfPresent(ephemeralPath(kind, id)));
     },
     async list(kind) {
       const records = [];

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

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
+import { performance } from "node:perf_hooks";
 
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
@@ -8,7 +9,9 @@ import { encode, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
 import { ensureManagedDirectory } from "./safe-directory.mjs";
 
 const STALE_MS = 60_000;
+const ACQUIRE_TIMEOUT_MS = 2_500;
 const OWNER = "owner.json";
+const sleepFor = duration => new Promise(resolve => { setTimeout(resolve, duration); });
 
 // Directory creation is the atomic primitive: mkdir either creates or fails
 // with EEXIST, with no window in between. Ported from the reconciled
@@ -85,22 +88,35 @@ async function takeStaleOwnership(directory, root, owner, now, pidIsAlive) {
 
 export async function withWriterMutex(paths, options, operation) {
   const { root, clock, pidIsAlive = defaultPidIsAlive, uuid = randomUUID,
-    attempts = 50, waitMs = 20, openFile } = options;
+    attempts = Number.POSITIVE_INFINITY, waitMs = 20, openFile,
+    acquireTimeoutMs = ACQUIRE_TIMEOUT_MS, monotonicNow = () => performance.now(),
+    sleep = sleepFor } = options;
   const directory = path.join(paths.locks, "writer.lock");
+  // Wall time can jump while a process waits. A monotonic absolute deadline
+  // bounds all owner reads and retries, leaving half the hook's five-second
+  // budget for publishing the owner, doing the write, and rendering a result.
+  const deadline = monotonicNow() + acquireTimeoutMs;
   await ensureManagedDirectory(root, paths.locks);
   const token = uuid();
 
   for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (monotonicNow() >= deadline) break;
     try {
       await mkdir(directory);
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       const owner = await readOwner(directory, root, openFile);
       if (!await takeStaleOwnership(directory, root, owner, clock.now(), pidIsAlive)) {
-        await new Promise(resolve => { setTimeout(resolve, waitMs); });
+        const remaining = deadline - monotonicNow();
+        if (remaining <= 0) break;
+        await sleep(Math.min(waitMs, remaining));
       }
       continue;
     }
+    if (monotonicNow() >= deadline) {
+      await rm(directory, { recursive: true, force: true });
+      break;
+    }
     const owner = { pid: process.pid, token, acquiredAt: clock.now() };
     await publishAtomic(path.join(directory, OWNER), encode(owner), { root, tmpDir: paths.tmp });
     try {