agents-can-communicate 0.6.3 → 0.7.1

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

@@ -4,6 +4,7 @@ import { computeAttention } from "./attention.mjs";
 import { classifySessionPresence } from "./sessions.mjs";
 import { assertMessageId, messagePage } from "./message-pages.mjs";
 import { decisionView, isCurrentDecision } from "./decision-state.mjs";
+import { offerFacts } from "./receipts.mjs";
 
 const DEFAULT_LIMIT = 100;
 const CURSOR = /^[0-9]{16}$/;
@@ -38,7 +39,7 @@ export function createSyncService(ports, sessions) {
     }
     if (exact) assertMessageId(input.messageId);
     const snapshot = await store.snapshot(input.workspaceId ?? store.workspaceId,
-      { kinds: ["message"] });
+      { kinds: exact ? ["message", "receipt"] : ["message"] });
     const messages = snapshot.messages.map(decisionView(snapshot.messages));
     if (!exact) return messagePage(messages, input,
       { include: message => input.current !== true || isCurrentDecision(message),
@@ -47,7 +48,15 @@ export function createSyncService(ports, sessions) {
     if (message === undefined) {
       throw new AccError(EXIT.DATA, "message is not in this workspace's history");
     }
-    return { scope: "history", view: "message", items: [message], nextCursor: null };
+    // Beside the message rather than inside it: the router offers `items[0]`
+    // to a transport, and a sender asking "did they get it" wants every
+    // recipient's answer. `sync --scope full` already shows all of it.
+    const receipts = snapshot.receipts
+      .filter(receipt => receipt.messageId === message.messageId)
+      .sort((left, right) => left.recipientParticipantId.localeCompare(right.recipientParticipantId))
+      .map(receipt => ({ recipientParticipantId: receipt.recipientParticipantId,
+        state: receipt.state, updatedAt: receipt.updatedAt, offer: offerFacts(receipt) }));
+    return { scope: "history", view: "message", items: [message], receipts, nextCursor: null };
   }
 
   async function sync(input = {}) {
@@ -86,6 +95,10 @@ export function createSyncService(ports, sessions) {
       && snapshot.claims.length === 0;
     return {
       cursor: page.cursor,
+      // Where the log starts, when it no longer starts at the beginning. A
+      // caller whose cursor precedes this was served a short page, and saying
+      // so is the difference between a trim and a silent gap.
+      trimmedThrough: page.trimmedThrough ?? null,
       scope: input.scope === "full" ? "full" : "delta",
       solo,
       attention,

package/node_modules/@agents-can-communicate/delivery-router/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/delivery-router",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "private": true,
   "type": "module",
   "exports": {

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

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

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

@@ -3,10 +3,20 @@ import { readInstalledLivePolicyState } from "@agents-can-communicate/installer"
 
 import { establishNativeBinding, LIVE_POLICIES, livePolicyFrom } from "./native-binding.mjs";
 
-// Reserve time for turn projection, status and output before optional disk I/O.
+// A cold worker plus the write has to finish inside this window. 250 ms was
+// not enough on a busy CI runner, so the attempt file never appeared and
+// doctor reported no attempt. 1.5 s still abandons a stuck disk, and the
+// extra 500 ms stays available for turn projection, status and output.
+const DIAGNOSTIC_BUDGET_MS = 1_500;
+const DIAGNOSTIC_FLOOR_MS = 250;
+const AFTER_DIAGNOSTIC_MS = 500;
+
 export function nativeDiagnosticDeadline(hookDeadline) {
   const now = Date.now();
-  return hookDeadline - now >= 750 ? now + 250 : null;
+  const remaining = hookDeadline - now;
+  // Below this, even the old quarter-second write would crowd out projection.
+  if (remaining < DIAGNOSTIC_FLOOR_MS + AFTER_DIAGNOSTIC_MS) return null;
+  return now + Math.min(DIAGNOSTIC_BUDGET_MS, remaining - AFTER_DIAGNOSTIC_MS);
 }
 
 // The diagnostic has its own bounded writer; it never rewrites hook ownership.
@@ -45,12 +55,44 @@ export async function bindNative({ adapter, event, hookBinding, clientVersion, p
 const HINT_MAX_BYTES = 512;
 const HINT_MAX_MS = 250;
 
+function asHint(value) {
+  if (typeof value === "string") return { line: value, release: async () => {} };
+  if (value !== null && typeof value === "object" && typeof value.line === "string") {
+    return { line: value.line,
+      release: typeof value.release === "function" ? value.release : async () => {} };
+  }
+  if (value !== null && typeof value === "object" && typeof value.release === "function") {
+    return { line: "", release: value.release };
+  }
+  return null;
+}
+
+function usableHint(line) {
+  return line !== "" && !/[\r\n]/.test(line) && Buffer.byteLength(line, "utf8") <= HINT_MAX_BYTES;
+}
+
+// An adapter may release with a synchronous function. Calling `.catch` on its
+// return value throws when that return value is undefined, and a throw from
+// the function itself must not become a failed hook.
+export function callRelease(release) {
+  if (typeof release !== "function") return Promise.resolve();
+  try {
+    return Promise.resolve(release()).catch(() => {});
+  } catch {
+    return Promise.resolve();
+  }
+}
+
 /**
  * One line an adapter asks the agent to act on, when the agent itself can fix
  * a degraded native binding - Antigravity's relay is started from the agent's
  * own shell, and nothing else can start it. Bounded and fail-open: a slow or
  * failing adapter costs the turn nothing, and anything but one short line is
  * dropped rather than trusted into model context.
+ *
+ * A string has nothing reserved. `{ line, release }` has reserved an ask; this
+ * function calls `release` when it drops the line, including when the adapter
+ * answers after the budget. The caller releases a line it does not deliver.
  */
 export async function nativeActivationHintFor({ adapter, event, nativeBinding, binding, context,
   paths, deadline }) {
@@ -58,17 +100,28 @@ export async function nativeActivationHintFor({ adapter, event, nativeBinding, b
   const budget = Math.min(HINT_MAX_MS, deadline - Date.now() - HINT_MAX_MS);
   if (budget <= 0) return null;
   let timer = null;
+  let keep = false;
+  // The call sits inside then so a synchronous throw becomes a rejection.
+  // Promise.resolve(adapter.nativeActivationHint()) evaluates the call first
+  // and lets that throw escape the hook.
+  const pending = Promise.resolve().then(() => adapter.nativeActivationHint({ event, nativeBinding,
+    runtimeDir: paths.root, clientPid: binding?.clientPid, env: context.env })).then(asHint, () => null);
   try {
-    const line = await Promise.race([
-      Promise.resolve(adapter.nativeActivationHint({ event, nativeBinding, runtimeDir: paths.root,
-        clientPid: binding?.clientPid, env: context.env })),
+    const taken = await Promise.race([
+      pending,
       new Promise(resolve => { timer = setTimeout(resolve, budget, null); }),
     ]);
-    return typeof line === "string" && line !== "" && !/[\r\n]/.test(line)
-      && Buffer.byteLength(line, "utf8") <= HINT_MAX_BYTES ? line : null;
+    if (taken !== null && usableHint(taken.line)) {
+      keep = true;
+      return taken;
+    }
+    return null;
   } catch {
     return null;
   } finally {
     if (timer !== null) clearTimeout(timer);
+    // A late or rejected answer still holds its reservation. Do not wait for
+    // it: an adapter that never settles must not hold the hook.
+    if (!keep) pending.then(taken => callRelease(taken?.release)).catch(() => {});
   }
 }

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

@@ -15,7 +15,8 @@ import { clearPin, createGitProbe, resolveHookWorkspace, platformDataHome, runti
 
 import { resolveClientPid } from "./client-pid.mjs";
 import { probeClientVersion as defaultProbeClientVersion } from "./client-version.mjs";
-import { bindNative, nativeActivationHintFor, nativeDiagnosticDeadline } from "./native-attempt.mjs";
+import { bindNative, callRelease, nativeActivationHintFor, nativeDiagnosticDeadline }
+  from "./native-attempt.mjs";
 import { readProcessTable as defaultReadProcessTable } from "./process-table.mjs";
 import { withSessionLifecycle } from "./session-lifecycle.mjs";
 import { appendStartOwner, appendToolOwner, ownerHeader, ownerOnlyOutcome } from "./owner-context.mjs";
@@ -236,7 +237,7 @@ async function openContext({ event, adapterId, dataHome, runtime, env, deadline
 // `render` is how the projected text reaches this client: before a turn it is
 // the adapter's context envelope, at the end of one it is a continuation.
 async function projectTurn({ binding, context, adapter, adapterId,
-  render = text => adapter.injectOutcome?.(text), activationHint = null }) {
+  render = text => adapter.injectOutcome?.(text), activationHint = null, repeats = true }) {
   const sync = await context.service.sync({ sessionId: binding.accSessionId,
     cursor: null, scope: "delta" });
 
@@ -250,11 +251,22 @@ async function projectTurn({ binding, context, adapter, adapterId,
   // Without this the projector's peer block never runs in production: an
   // agent sees only the obligation attention line, not the durable body that
   // may be offered after the stdout transport succeeds.
+  // Decided before selection: a repeat is taken out of the reminder lists, so
+  // asking for one this turn cannot show is how a message would go quiet.
+  // 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 effective = effectiveCapabilities(adapter, binding);
+  const hasStructuredRenderer = typeof adapter.renderContextResult === "function";
+  const canOfferNextTurn = effective.delivery.nextTurn === true && hasStructuredRenderer;
   const delivery = await context.service.nextTurnDelivery({
     workspaceId: context.descriptor.id,
     participantId: mine?.participantId,
-    exceptSessionId: binding.accSessionId });
-  const messages = delivery.queuedMessages;
+    exceptSessionId: binding.accSessionId,
+    repeats: repeats && canOfferNextTurn });
+  // New bodies first, so a repeat is what the byte budget drops.
+  const messages = [...delivery.queuedMessages, ...delivery.repeatMessages];
+  const repeating = new Set(delivery.repeatMessages.map(message => message.messageId));
 
   // Only this hook's payload selected the binding. Supply its own pair as
   // trusted context, outside peer bodies, rather than exporting inheritable
@@ -264,26 +276,24 @@ async function projectTurn({ binding, context, adapter, adapterId,
   // turn carries - and only when both fit in half the budget, so peer bodies
   // always keep the rest.
   const header = ownerHeader(binding, context.workspaceCwd, context.workspaceRef);
-  const owner = activationHint === null
-    || byteLength(header) + 1 + byteLength(activationHint) > totalBudget / 2
-    ? header : `${header}\n${activationHint}`;
+  const hintFits = activationHint !== null
+    && byteLength(header) + 1 + byteLength(activationHint) <= totalBudget / 2;
+  const owner = hintFits ? `${header}\n${activationHint}` : header;
+  const withHint = (outcome, attached) => ({ ...outcome,
+    activationHintIncluded: attached === true && outcome.stdout !== "" });
   // A peer can join after this prompt has begun. The current turn must already
   // have its own arguments when it needs inbox/reply, without reattaching or
   // waiting for another user prompt. Solo emits identity, not a peer notice.
   if (sync.solo && messages.length === 0) {
-    return ownerOnlyOutcome(text => adapter.injectOutcome?.(text), owner, totalBudget);
+    return withHint(ownerOnlyOutcome(text => adapter.injectOutcome?.(text), owner, totalBudget),
+      hintFits);
   }
 
-  // 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 effective = effectiveCapabilities(adapter, binding);
-  const hasStructuredRenderer = typeof adapter.renderContextResult === "function";
-  const canOfferNextTurn = effective.delivery.nextTurn === true && hasStructuredRenderer;
   const projectionInput = { ...sync, messages: canOfferNextTurn ? messages : [],
     liveOfferedMessageIds: delivery.liveOfferedMessageIds,
     reminderMessageIds: delivery.reminderMessageIds,
     roomMessageIds: delivery.roomMessageIds,
+    repeatOffers: delivery.repeatOffers,
     currentParticipantId: mine?.participantId };
   // Credentials alone cannot replace the command that reaches a queued body.
   // If both cannot fit, preserve recovery and explain the missing owner pair.
@@ -324,12 +334,13 @@ async function projectTurn({ binding, context, adapter, adapterId,
   // Own claims make sync non-solo but produce no peer context. They cannot
   // remove this turn's identity or consume a nonexistent body separator.
   if (body === "" && messages.length === 0) {
-    return ownerOnlyOutcome(text => adapter.injectOutcome?.(text), owner, totalBudget);
+    return withHint(ownerOnlyOutcome(text => adapter.injectOutcome?.(text), owner, totalBudget),
+      hintFits);
   }
   const projected = body === "" ? "" : ownerFits ? `${owner}\n${body}` : body;
   if (projected === "") {
-    return { stdout: "", stderr: messages.length === 0 ? ""
-      : [ownerWarning, degradation].filter(Boolean).join("\n") };
+    return withHint({ stdout: "", stderr: messages.length === 0 ? ""
+      : [ownerWarning, degradation].filter(Boolean).join("\n") }, false);
   }
 
   // The renderer returns ids as metadata, never as text to parse. A peer body
@@ -341,7 +352,8 @@ async function projectTurn({ binding, context, adapter, adapterId,
       recipientParticipantId: mine.participantId,
       targetSessionId: binding.accSessionId, targetGeneration: binding.generation,
       transport: "next-turn", adapterId,
-      clientVersion: binding.clientVersion }));
+      clientVersion: binding.clientVersion,
+      ...(repeating.has(message.messageId) ? { repeat: true } : {}) }));
   // 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.
   // The entry point owns the transport boundary. This handler only prepares
@@ -349,9 +361,30 @@ async function projectTurn({ binding, context, adapter, adapterId,
   // callback proves that the bytes crossed.
   const outcome = { stdout: "", ...render(projected) };
   const writableOffers = outcome.stdout === "" ? [] : offerInputs;
-  return { ...outcome,
+  return withHint({ ...outcome,
     stderr: [outcome.stderr, ownerWarning, degradation].filter(Boolean).join("\n"),
-    offerInputs: writableOffers };
+    offerInputs: writableOffers }, hintFits && ownerFits);
+}
+
+// The adapter may already have reserved an ask. That reservation is an ask
+// only when this turn's stdout carries the line. A throw discards the turn,
+// so the reservation goes with it.
+async function projectActivation(input, offered) {
+  try {
+    const turn = await projectTurn({ ...input, activationHint: offered?.line ?? null });
+    const included = turn.activationHintIncluded === true;
+    delete turn.activationHintIncluded;
+    if (!offered) return turn;
+    if (!included) await callRelease(offered.release);
+    else if (typeof offered.release === "function") {
+      const release = offered.release;
+      turn.releaseActivationAsk = () => callRelease(release);
+    }
+    return turn;
+  } catch (error) {
+    await callRelease(offered?.release);
+    throw error;
+  }
 }
 
 const HANDLERS = {
@@ -500,9 +533,9 @@ const HANDLERS = {
       const started = await HANDLERS.sessionStart(input);
       const fresh = await loadSessionBinding({ runtimeDir: paths.root,
         harnessSessionId: event.sessionId });
-      const activationHint = await nativeActivationHintFor({ adapter, event,
+      const offered = await nativeActivationHintFor({ adapter, event,
         nativeBinding: started.nativeBinding, binding: fresh, context, paths, deadline });
-      const turn = await projectTurn({ ...input, binding: fresh, activationHint });
+      const turn = await projectActivation({ ...input, binding: fresh }, offered);
       return { ...turn, nativeBinding: started.nativeBinding };
     }
     const current = await context.service.locateSession(binding.accSessionId);
@@ -516,9 +549,9 @@ const HANDLERS = {
       const started = await HANDLERS.sessionStart(input);
       const fresh = await loadSessionBinding({ runtimeDir: paths.root,
         harnessSessionId: event.sessionId });
-      const activationHint = await nativeActivationHintFor({ adapter, event,
+      const offered = await nativeActivationHintFor({ adapter, event,
         nativeBinding: started.nativeBinding, binding: fresh, context, paths, deadline });
-      const turn = await projectTurn({ ...input, binding: fresh, activationHint });
+      const turn = await projectActivation({ ...input, binding: fresh }, offered);
       return { ...turn, nativeBinding: started.nativeBinding };
     }
     // A turn is the clearest sign a session is alive. Never a reason to fail:
@@ -530,9 +563,9 @@ const HANDLERS = {
     const nativeBinding = await bindNative({ adapter, event, hookBinding: binding,
       clientVersion: binding.clientVersion, platform: binding.platform, context, paths,
       deadline });
-    const activationHint = await nativeActivationHintFor({ adapter, event, nativeBinding,
+    const offered = await nativeActivationHintFor({ adapter, event, nativeBinding,
       binding, context, paths, deadline });
-    const turn = await projectTurn({ ...input, activationHint });
+    const turn = await projectActivation(input, offered);
     return nativeBinding === undefined ? turn : { ...turn, nativeBinding };
   },
 
@@ -557,7 +590,9 @@ const HANDLERS = {
     const current = await context.service.locateSession(binding.accSessionId);
     if (current === null || current.record.state !== "open"
       || current.record.generation !== binding.generation) return {};
-    const turn = await projectTurn({ ...input,
+    // A repeat is a body the model may already have. It rides on the next
+    // turn that happens anyway and never buys a model call of its own.
+    const turn = await projectTurn({ ...input, repeats: false,
       render: text => adapter.continueTurnOutcome({ reason: text, payload }) });
     return (turn.offerInputs ?? []).length === 0 ? {} : turn;
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "private": true,
   "type": "module",
   "exports": {

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

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

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

@@ -23,15 +23,17 @@ const stringList = description => ({ type: "array", items: { type: "string" }, d
 export const PUBLIC_TOOLS = Object.freeze([
   {
     name: "acc_status",
-    description: `Read who is here, current intents and claims, and the workspace's real `
-      + `protection level. ${POLLED}`,
+    description: `Read who is here, current intents and claims, the workspace's real `
+      + `protection level, and how many messages each participant has not fetched `
+      + `(offered is not read). ${POLLED}`,
     inputSchema: object({}),
   },
   {
     name: "acc_sync",
     description: `Read coordination state for this workspace: roster, attention items, and `
       + `events since a cursor. Use scope "history" for bounded message summaries, then `
-      + `messageId to read one complete historical message without changing receipts. `
+      + `messageId to read one complete historical message, with every recipient's `
+      + `receipt state, without changing receipts. `
       + `Scope "full" is an unbounded forensic workspace snapshot. Use acc_inbox for `
       + `your addressed messages. ${POLLED}`,
     inputSchema: object({

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/protocol",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "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.6.3",
+  "version": "0.7.1",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -34,11 +34,11 @@ async function bytesIfPresent(filePath, root, openFile) {
   }
 }
 
-function retainedStage(destination, root, tmpDir) {
+function retainedStage(destination, root, stageDir) {
   const identity = createHash("sha256")
     .update(path.relative(root, destination))
     .digest("hex");
-  return path.join(tmpDir, `${identity}.published`);
+  return path.join(stageDir, `${identity}.published`);
 }
 
 async function replaceHandleBytes(handle, bytes) {
@@ -63,11 +63,18 @@ async function replaceHandleBytes(handle, bytes) {
  *
  * @returns {Promise<"published" | "already_published">}
  */
-export async function publishAtomic(destination, bytes, { root, tmpDir, replace = false, deadlineAt }) {
+export async function publishAtomic(destination, bytes,
+  { root, tmpDir, stageDir, replace = false, deadlineAt, afterAccepted }) {
   assertPublicationDeadline(deadlineAt);
+  // The accepted stage lives apart from the partial a failed publication
+  // leaves, so what a file is follows from the directory it was created in
+  // rather than from how its name ends. Defaulted from the root the way
+  // active-journal.mjs defaults tmpDir, so every caller keeps working.
+  stageDir = stageDir ?? path.join(root, "stage");
   const destinationDir = path.dirname(destination);
   await Promise.all([
     ensureManagedDirectory(root, tmpDir),
+    ensureManagedDirectory(root, stageDir),
     ensureManagedDirectory(root, destinationDir),
   ]);
   if (!replace) {
@@ -79,8 +86,11 @@ export async function publishAtomic(destination, bytes, { root, tmpDir, replace
     }
   }
 
-  const stage = retainedStage(destination, root, tmpDir);
-  const temporary = `${stage}.${process.pid}.${randomUUID()}.tmp`;
+  const stage = retainedStage(destination, root, stageDir);
+  // The temporary stays in tmpDir: until the bytes are accepted it is a
+  // partial, and a partial is exactly what tmp holds.
+  const temporary = path.join(tmpDir,
+    `${path.basename(stage)}.${process.pid}.${randomUUID()}.tmp`);
   let handle = await open(temporary, "wx");
   let stageAcceptedBytes = false;
   try {
@@ -121,9 +131,18 @@ export async function publishAtomic(destination, bytes, { root, tmpDir, replace
   } finally {
     await handle?.close();
     if (stageAcceptedBytes) {
-      await assertManagedDirectory(root, tmpDir);
+      // `ensure`, not `assert`: the sweep empties this directory by renaming it
+      // aside and recreating it, and a publication that began before that swap
+      // arrives here to find the name gone. Both apply the same managed-root
+      // checks - the only difference is that this one recreates what the sweep
+      // has already taken away, instead of failing a write whose bytes are
+      // already published.
+      // The seam the race test uses, in the manner retainFile already
+      // establishes: the window this closes is invisible without one.
+      await afterAccepted?.();
+      await ensureManagedDirectory(root, stageDir);
       await rename(temporary, stage);
-      await syncDirectory(tmpDir);
+      await syncDirectory(stageDir);
     } else {
       // A crash/error before immutable acceptance keeps its unique partial.
       // Retention avoids the unsafe parent-check/unlink pathname window, while

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

@@ -0,0 +1,98 @@
+import { randomUUID } from "node:crypto";
+import { open, rename, rm, rmdir } from "node:fs/promises";
+import path from "node:path";
+
+import { listDirectoryEntries } from "./atomic-json.mjs";
+import { assertManagedDirectory, ensureManagedDirectory } from "./safe-directory.mjs";
+
+// The store never unlinks a live name: Node exposes unlink only by pathname, so
+// a checked parent can be replaced between the check and the call. What it does
+// instead is move a doomed entry into a directory this process named with a
+// value no other process knows, and then remove that directory whole. Every
+// reclaimer in the store shares the primitive, so the rule is stated once.
+//
+// The prefix still reads "stage" because a store written by 0.6.3 leaves
+// directories under this exact name when a pass is interrupted, and the resume
+// below finds them by prefix. Renaming it would orphan them.
+const DOOMED = "stage.sweeping-";
+
+// Not assertPublicationDeadline: that one throws, and a maintenance pass on the
+// path that opens the store must stop rather than fail the open. What is left
+// is reported as remaining, and the next pass adopts it.
+export const expired = deadlineAt => deadlineAt !== undefined && Date.now() >= deadlineAt;
+
+export async function syncDirectory(directory) {
+  const handle = await open(directory, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function doomedDirectories(root) {
+  return (await listDirectoryEntries(root, { root }))
+    .filter(entry => entry.isDirectory() && entry.name.startsWith(DOOMED))
+    .map(entry => path.join(root, entry.name))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+export function doomedName(root) {
+  return path.join(root, `${DOOMED}${randomUUID()}`);
+}
+
+export async function detachDoomed(root) {
+  const directory = doomedName(root);
+  await ensureManagedDirectory(root, directory);
+  return directory;
+}
+
+/**
+ * Move one doomed entry out of the store's live names.
+ *
+ * The destination name is unique because the sources are not: two records of
+ * one kind each keep a marker named for its own sequence, and a journal entry
+ * and a stage file can collide on nothing at all. The doomed directory is
+ * discarded whole, so the names inside it carry no meaning.
+ */
+export async function condemn(filePath, doomed) {
+  await rename(filePath, path.join(doomed, `${randomUUID()}.doomed`));
+}
+
+/**
+ * Remove a doomed directory, one entry at a time, within a budget.
+ *
+ * @returns {Promise<{ spent: number, drained: boolean }>}
+ */
+export async function discard(directory, root, budget, deadlineAt) {
+  let spent = 0;
+  await assertManagedDirectory(root, directory);
+  for (const entry of await listDirectoryEntries(directory, { root })) {
+    if (spent >= budget || expired(deadlineAt)) return { spent, drained: false };
+    await rm(path.join(directory, entry.name), { recursive: true, force: true });
+    spent += 1;
+  }
+  await rmdir(directory).catch(error => {
+    if (error.code !== "ENOENT" && error.code !== "ENOTEMPTY") throw error;
+  });
+  return { spent, drained: true };
+}
+
+/**
+ * Finish what an interrupted pass left behind, within a budget.
+ *
+ * Every pass runs this first, and for a second reason: a pass that stops here
+ * never detaches a further directory, so an exhausted budget cannot make them
+ * accumulate.
+ *
+ * @returns {Promise<{ spent: number, drained: boolean }>}
+ */
+export async function discardLeftovers(root, budget, deadlineAt) {
+  let spent = 0;
+  for (const directory of await doomedDirectories(root)) {
+    const removed = await discard(directory, root, budget - spent, deadlineAt);
+    spent += removed.spent;
+    if (!removed.drained) return { spent, drained: false };
+  }
+  return { spent, drained: true };
+}

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

@@ -0,0 +1,52 @@
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { encode, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
+
+const SEQUENCE = /^[0-9]{16}$/;
+
+/**
+ * The highest event sequence this store has trimmed away.
+ *
+ * Trimming the oldest events is safe on its own, because `nextSequence` reads
+ * the newest file. An emptied directory is what needs a floor: without one the
+ * sequence would restart at 1 and collide with a cursor a peer still holds,
+ * and a reader whose cursor precedes the boundary would be served a short page
+ * with no way to tell it was short.
+ */
+const floorPath = paths => path.join(paths.locks, "retention.json");
+
+export function assertSequence(value, field) {
+  if (typeof value !== "string" || !SEQUENCE.test(value)) {
+    throw new AccError(EXIT.USAGE,
+      `${field} is the 16-digit sequence a previous sync returned`, { [field]: value });
+  }
+  return value;
+}
+
+// An unreadable floor is treated as none. The alternative - refusing to serve
+// events because the bookkeeping about their removal is damaged - would take a
+// workspace offline over a file that only ever adds information.
+export async function readEventFloor(paths, root) {
+  const found = await readJsonIfPresent(floorPath(paths), root).catch(() => null);
+  const value = found?.value?.trimmedThrough;
+  return typeof value === "string" && SEQUENCE.test(value) ? value : null;
+}
+
+/**
+ * Raise the floor, never lower it.
+ *
+ * Written before a single event file moves. A floor ahead of the trim only
+ * reports a boundary for events still present, which costs a reader nothing;
+ * a trim ahead of the floor is a silent gap, which is the failure this exists
+ * to prevent.
+ */
+export async function raiseEventFloor(paths, options, trimmedThrough) {
+  assertSequence(trimmedThrough, "trimmedThrough");
+  const current = await readEventFloor(paths, options.root);
+  if (current !== null && current >= trimmedThrough) return current;
+  await publishAtomic(floorPath(paths), encode({ trimmedThrough }),
+    { ...options, replace: true });
+  return trimmedThrough;
+}