@ccmsg/cli 0.13.0 → 0.14.1

package/src/messaging/direct.ts

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
-import { chmodSync, unlinkSync } from "node:fs";
-import { readdir, readFile } from "node:fs/promises";
+import { unlinkSync } from "node:fs";
+import { chmod, readdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { type InboxMessage, renderDirectDelivery, type Sid } from "@ccmsg/protocol";
 import { HARNESS, HARNESSES } from "../harness/index.ts";
@@ -39,7 +39,7 @@ export class DisabledDirectRoute implements DirectRoute {
 
 /** The `peerProtocol` generation this speaks. One value, because one is what
  * has been read off a running harness (2.1.263); any other generation is a
- * protocol nobody here has seen, which is condition 1 of DESIGN §6.5. */
+ * protocol nobody here has seen, which is condition 2 of DESIGN §6.5. */
 export const PEER_PROTOCOL = 1;
 
 /** How long one attempt has to reach the point where the harness holds our
@@ -52,7 +52,7 @@ export const PEER_PROTOCOL = 1;
 export const DIRECT_ACK_MS = 2_000;
 
 /** How long the status inbox is watched for word about this message before the
- * send is taken to have landed (DESIGN §6.5 condition 3).
+ * send is taken to have landed (DESIGN §6.5 condition 4).
  *
  * Provisional. What is known from the harness (2.1.263) is where the receipt
  * is raised, not how long it takes to arrive: the receiving session decides a
@@ -63,6 +63,16 @@ export const DIRECT_ACK_MS = 2_000;
  * answer. Nothing measured stands behind the number itself. */
 export const DIRECT_STATUS_MS = 250;
 
+/** How long reading `sessions/` has to answer which file names this session
+ * (DESIGN §6.5 condition 1).
+ *
+ * The other two budgets cover what the route does after the target is found,
+ * and none of them covers the finding: a directory of small JSON files on the
+ * local disk answers in a moment, and a read that has not come back by now is
+ * one route (a) is better off not waiting for. Route (b) carries the message
+ * either way (DESIGN §6.5). */
+export const DIRECT_SCAN_MS = 1_000;
+
 /** What the receiving session says about a message it did not simply take
  * (harness 2.1.263, `peer_message_status`).
  *
@@ -78,7 +88,7 @@ export const DIRECT_STATUS_MS = 250;
 const REFUSING = new Set(["refused", "denied", "dropped", "expired", "held"]);
 
 /** The socket this daemon offers so the receiving session can say what became
- * of a message (DESIGN §6.5 condition 3).
+ * of a message (DESIGN §6.5 condition 4).
  *
  * It lives in the directory the target's own socket is in, and not in this
  * instance's state directory, because the receiving harness vets the address it
@@ -105,7 +115,7 @@ class StatusInbox {
    * bound. Binding fails on a directory we cannot write, which costs the
    * route its status channel and nothing else: the message still goes, and
    * what the session says about it is simply not heard. */
-  address(): string | undefined {
+  async address(): Promise<string | undefined> {
     if (this.#server !== undefined) return `uds:${this.#path}`;
     try {
       this.#server = Bun.listen({
@@ -125,7 +135,7 @@ class StatusInbox {
     // Same-uid by construction (A2 / A4), and stated rather than left to the
     // umask: what can be written here is what a session is told about.
     try {
-      chmodSync(this.#path, 0o600);
+      await chmod(this.#path, 0o600);
     } catch {
       // The socket is bound and usable; a mode we could not set is not a
       // reason to give up the channel.
@@ -211,12 +221,14 @@ export interface SocketRouteOptions {
   readonly ackMs?: number;
   /** How long a receipt has to arrive before the message counts as taken. */
   readonly statusMs?: number;
+  /** How long reading `sessions/` has to name the target. */
+  readonly scanMs?: number;
 }
 
 /** Route (a) against the harness's messaging socket (DESIGN §6.5).
  *
  * The path is `sessions/<pid>.json` of this instance's own config home, which
- * is also the answer to condition 2: a key beside it that this uid can read is
+ * is also the answer to condition 3: a key beside it that this uid can read is
  * exactly the same-uid, same-config-home boundary the instance already stands
  * on (A2 / A4). Nothing here searches another config home, and a session this
  * instance cannot see a state file for is simply not reachable this way.
@@ -228,15 +240,30 @@ export class ClaudeCodeSocketRoute implements DirectRoute {
   readonly #sessionsDir: string;
   readonly #ackMs: number;
   readonly #statusMs: number;
+  readonly #scanMs: number;
   /** One status inbox per directory sessions' sockets live in. A host has one
    * such directory in practice; the map is what keeps that from being an
-   * assumption. */
-  readonly #inboxes = new Map<string, StatusInbox>();
+   * assumption.
+   *
+   * The binding rather than the bound socket, because binding waits: two sends
+   * to sessions of the same directory run side by side, and a map holding only
+   * finished inboxes would have both of them bind one, with the loser left
+   * listening on a socket nothing can close. */
+  readonly #inboxes = new Map<string, Promise<StatusInbox | undefined>>();
+
+  /** The channels that finished binding, so letting the route go takes their
+   * sockets down in the same turn rather than one after it. */
+  readonly #bound = new Set<StatusInbox>();
+
+  /** Whether the route has been let go. A binding that finishes after that has
+   * nobody to close it later, so it closes itself. */
+  #closed = false;
 
   constructor(options: SocketRouteOptions) {
     this.#sessionsDir = join(options.configHome, "sessions");
     this.#ackMs = options.ackMs ?? DIRECT_ACK_MS;
     this.#statusMs = options.statusMs ?? DIRECT_STATUS_MS;
+    this.#scanMs = options.scanMs ?? DIRECT_SCAN_MS;
   }
 
   /** One send, and what the session made of it.
@@ -253,8 +280,8 @@ export class ClaudeCodeSocketRoute implements DirectRoute {
     if (target === undefined) return "unavailable";
     const token = await this.#token(target.pid);
     if (token === undefined) return "unavailable";
-    const inbox = this.#inbox(target.socketPath);
-    const from = inbox?.address();
+    const inbox = await this.#inbox(target.socketPath);
+    const from = await inbox?.address();
     const watching = inbox === undefined ? undefined : inbox.status(message.mid, this.#statusMs);
     const written = await write(target.socketPath, frames(sid, token, message, from), this.#ackMs);
     if (written !== "delivered") return written;
@@ -263,35 +290,49 @@ export class ClaudeCodeSocketRoute implements DirectRoute {
   }
 
   close(): void {
-    for (const inbox of this.#inboxes.values()) inbox.close();
+    // A binding still in flight closes itself when it lands, which is what
+    // `#closed` is read for; what is already bound goes now, so the sockets are
+    // gone by the time this returns.
+    this.#closed = true;
+    for (const inbox of this.#bound) inbox.close();
+    this.#bound.clear();
     this.#inboxes.clear();
   }
 
   /** The receipt channel for a target, bound beside its own socket. Absent
    * when nothing could be bound there, which leaves the route working and its
    * refusals unheard. */
-  #inbox(socketPath: string): StatusInbox | undefined {
+  async #inbox(socketPath: string): Promise<StatusInbox | undefined> {
     const directory = dirname(socketPath);
     const held = this.#inboxes.get(directory);
-    if (held !== undefined) return held;
-    const inbox = new StatusInbox(directory);
-    if (inbox.address() === undefined) return undefined;
-    this.#inboxes.set(directory, inbox);
+    if (held !== undefined) return await held;
+    const opening = (async (): Promise<StatusInbox | undefined> => {
+      const inbox = new StatusInbox(directory);
+      if ((await inbox.address()) === undefined) return undefined;
+      if (this.#closed) {
+        inbox.close();
+        return undefined;
+      }
+      this.#bound.add(inbox);
+      return inbox;
+    })();
+    this.#inboxes.set(directory, opening);
+    const inbox = await opening;
+    // Nothing bound is not remembered: the directory may be writable by the
+    // time the next message goes that way, and a failure kept here would be
+    // the route without its receipts for the life of the instance.
+    if (inbox === undefined && this.#inboxes.get(directory) === opening) {
+      this.#inboxes.delete(directory);
+    }
     return inbox;
   }
 
   /** The state file naming this session, if it names a socket of a generation
-   * we speak (DESIGN §6.5 conditions 1). */
+   * we speak (DESIGN §6.5 condition 2). */
   async #target(sid: Sid): Promise<HarnessTarget | undefined> {
-    let names: string[];
-    try {
-      names = await readdir(this.#sessionsDir);
-    } catch {
-      return undefined;
-    }
-    for (const name of names) {
-      if (!/^\d+\.json$/.test(name)) continue;
-      const row = await readJson(join(this.#sessionsDir, name));
+    const rows = await this.#rows(/^\d+\.json$/);
+    if (rows === undefined) return undefined;
+    for (const row of rows) {
       if (row === undefined || row["sessionId"] !== sid) continue;
       const pid = row["pid"];
       const socketPath = row["messagingSocketPath"];
@@ -303,7 +344,7 @@ export class ClaudeCodeSocketRoute implements DirectRoute {
     return undefined;
   }
 
-  /** The `peerToken` the harness wrote for this session (DESIGN §6.5 condition 2).
+  /** The `peerToken` the harness wrote for this session (DESIGN §6.5 condition 3).
    *
    * Found by the pid the key is named after rather than by rebuilding the rest
    * of the name: the digest in `<pid>.<digest>.key` is stated to be over the
@@ -311,20 +352,45 @@ export class ClaudeCodeSocketRoute implements DirectRoute {
    * against a running harness, and a name we cannot rebuild is still a name we
    * can recognise. */
   async #token(pid: number): Promise<string | undefined> {
-    const key = new RegExp(`^${pid}\\.[0-9a-f]+\\.key$`);
+    const rows = await this.#rows(new RegExp(`^${pid}\\.[0-9a-f]+\\.key$`));
+    if (rows === undefined) return undefined;
+    for (const document of rows) {
+      const token = document?.["peerToken"];
+      if (typeof token === "string" && token !== "") return token;
+    }
+    return undefined;
+  }
+
+  /** The files of `sessions/` whose names this pattern admits, read at once and
+   * answered in the order the directory listed them.
+   *
+   * At once because the files are independent and what is being looked for is
+   * one of them: read in turn, the search costs the sum of every file and
+   * grows with the number of sessions on the host, and a `message.send` waits
+   * out the lot (DR-0015). The order is kept because it is what decides the
+   * answer — the first name that matches is the one the caller takes.
+   *
+   * Nothing when the directory cannot be read, and nothing when the reads have
+   * not finished inside `DIRECT_SCAN_MS`: both are route (a) not applying, and
+   * route (b) carries the message. */
+  async #rows(pattern: RegExp): Promise<(Record<string, unknown> | undefined)[] | undefined> {
     let names: string[];
     try {
       names = await readdir(this.#sessionsDir);
     } catch {
       return undefined;
     }
-    for (const name of names) {
-      if (!key.test(name)) continue;
-      const document = await readJson(join(this.#sessionsDir, name));
-      const token = document?.["peerToken"];
-      if (typeof token === "string" && token !== "") return token;
+    const wanted = names.filter((name) => pattern.test(name));
+    const late = Promise.withResolvers<undefined>();
+    const deadline = setTimeout(() => late.resolve(undefined), this.#scanMs);
+    try {
+      return await Promise.race([
+        Promise.all(wanted.map((name) => readJson(join(this.#sessionsDir, name)))),
+        late.promise,
+      ]);
+    } finally {
+      clearTimeout(deadline);
     }
-    return undefined;
   }
 }
 
@@ -477,7 +543,7 @@ function frames(sid: Sid, token: string, message: InboxMessage, from?: string):
 }
 
 /** Connect and write, and answer whether the harness holds our bytes (DESIGN §6.5
- * condition 3).
+ * condition 4).
  *
  * That is the whole of what this can decide. The connection carries nothing
  * back — a real send measured zero bytes on it — so waiting here for an answer
@@ -520,7 +586,7 @@ async function write(path: string, payload: string, ackMs: number): Promise<Dire
     });
   } catch {
     // No socket at the path, or nothing listening on it: the session ended and
-    // took its socket with it, or never had one (DESIGN §6.5 condition 1).
+    // took its socket with it, or never had one (DESIGN §6.5 condition 2).
     return "unavailable";
   }
 
@@ -543,7 +609,7 @@ async function readJson(path: string): Promise<Record<string, unknown> | undefin
     return document as Record<string, unknown>;
   } catch {
     // Missing, unreadable by this uid, or half written — all of them are
-    // "route (a) does not apply here" (DESIGN §6.5 conditions 1 and 2).
+    // "route (a) does not apply here" (DESIGN §6.5 conditions 2 and 3).
     return undefined;
   }
 }

package/src/messaging/inbox.ts

@@ -1,19 +1,15 @@
-import {
-  appendFileSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { appendFile, mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import {
   INBOX_MAX_PER_SID,
   INBOX_RETENTION_MS,
-  type InboxMessage,
+  InboxMessage,
   type InboxRemovedReason,
-  type Sid,
+  isValid,
+  Sid,
   type Timestamp,
+  validationErrors,
 } from "@ccmsg/protocol";
 
 export const INBOX_FILE = "inbox.jsonl";
@@ -45,6 +41,9 @@ type Record_ =
 export class Inbox {
   readonly #held = new Map<Sid, InboxMessage[]>();
 
+  /** The appends already asked for, as one chain. */
+  #written: Promise<void> = Promise.resolve();
+
   /** Told whenever a message leaves, and why. Every way out passes through
    * here — handed over, timed out, dropped for a newer one — so whoever states
    * removals on the topic has one place to hear about them rather than a
@@ -53,7 +52,12 @@ export class Inbox {
    * subscribed for them to be news to. */
   #onRemoved?: (mid: string, reason: InboxRemovedReason) => void;
 
-  constructor(private readonly file: string) {}
+  constructor(
+    private readonly file: string,
+    /** Where a line the replay could not keep is named. Absent in the tests
+     * that are about the holding rather than about what is said of it. */
+    private readonly log: (message: string, fields: Record<string, unknown>) => void = () => {},
+  ) {}
 
   /** Hear about messages leaving. */
   onRemoved(told: (mid: string, reason: InboxRemovedReason) => void): void {
@@ -82,6 +86,7 @@ export class Inbox {
         // The last line of a file the daemon was killed while writing.
         continue;
       }
+      if (record.v === "add" && !this.#stateable(record.sid, record.message)) continue;
       this.#replay(record);
     }
     this.#expire(now);
@@ -101,16 +106,28 @@ export class Inbox {
    * Answers whether the oldest was dropped to make room, which is the whole of
    * `inbox_full`: the message is held either way, and what the sender is told
    * differs because something of theirs is now gone. */
-  hold(sid: Sid, message: InboxMessage, now: Timestamp = Date.now()): { evicted: boolean } {
+  async hold(
+    sid: Sid,
+    message: InboxMessage,
+    now: Timestamp = Date.now(),
+  ): Promise<{ evicted: boolean }> {
     this.#expire(now, sid);
     const held = this.#held.get(sid) ?? [];
     this.#held.set(sid, held);
     held.push(message);
-    this.#append({ v: "add", sid, message });
-    if (held.length <= INBOX_MAX_PER_SID) return { evicted: false };
-    const oldest = held.shift();
+    // Awaited rather than left to land: what the sender is told is that the
+    // message is held, and it is not held until the line is on disk.
+    await this.#append({ v: "add", sid, message });
+    // What is over the limit is what the session holds now, not what it held
+    // when the line was written: a delivery or an expiry for this session
+    // leaves a different list in its place while the append is in flight, and
+    // deciding against the list from before would drop a message out of one
+    // nobody is holding and tell a watcher a delivered message was dropped.
+    const standing = this.#held.get(sid) ?? [];
+    if (standing.length <= INBOX_MAX_PER_SID) return { evicted: false };
+    const oldest = standing.shift();
     if (oldest !== undefined) {
-      this.#append({ v: "dropped", sid, mid: oldest.mid });
+      await this.#append({ v: "dropped", sid, mid: oldest.mid });
       this.#onRemoved?.(oldest.mid, "dropped");
     }
     return { evicted: true };
@@ -118,17 +135,24 @@ export class Inbox {
 
   /** Note that messages reached their session, which is what takes them out of
    * the inbox (DESIGN §6.7). */
-  delivered(sid: Sid, mids: readonly string[]): void {
+  async delivered(sid: Sid, mids: readonly string[]): Promise<void> {
     const held = this.#held.get(sid);
     if (held === undefined || mids.length === 0) return;
     const gone = new Set(mids);
     const left = held.filter((message) => !gone.has(message.mid));
     if (left.length === 0) this.#held.delete(sid);
     else this.#held.set(sid, left);
+    const written: Promise<void>[] = [];
     for (const mid of mids) {
-      this.#append({ v: "delivered", sid, mid });
+      written.push(this.#append({ v: "delivered", sid, mid }));
       this.#onRemoved?.(mid, "delivered");
     }
+    await Promise.all(written);
+  }
+
+  /** Settle once every line asked for so far is on disk. */
+  async flush(): Promise<void> {
+    await this.#written;
   }
 
   /** Every session something is waiting for. What reads it is the offer of
@@ -152,6 +176,30 @@ export class Inbox {
     return highest;
   }
 
+  /** Whether a line read back is a message the contract can state.
+   *
+   * The file outlives the contract that wrote it, and what is held is answered
+   * to a person as rows of the `inbox` topic — so a single line the contract
+   * has since outgrown, replayed as if it were current, is a frame the reader
+   * refuses and a whole view lost for it. An instance states only what the
+   * contract can say, about its own file as much as about anything else.
+   *
+   * Dropped rather than mended: the message is the sender's words and the
+   * contract is what says how they are spelled, so there is nothing here that
+   * could write a spelling the contract would accept without inventing it. It
+   * leaves through the compaction that follows the replay, which writes back
+   * only what is held; nothing is appended and no removal is stated, since a
+   * replay has nobody subscribed to hear one and no `mid` the contract would
+   * take to name it by. */
+  #stateable(sid: unknown, message: unknown): boolean {
+    const why = isValid(Sid, sid)
+      ? validationErrors(InboxMessage, message)
+      : [`sid: ${JSON.stringify(sid)} is no session id`];
+    if (why.length === 0) return true;
+    this.log("dropped an inbox record the contract cannot state", { sid, why });
+    return false;
+  }
+
   #replay(record: Record_): void {
     if (record.v === "add") {
       const held = this.#held.get(record.sid) ?? [];
@@ -183,9 +231,23 @@ export class Inbox {
     }
   }
 
-  #append(record: Record_): void {
-    mkdirSync(dirname(this.file), { recursive: true });
-    appendFileSync(this.file, `${JSON.stringify(record)}\n`);
+  /** One line, behind the lines asked for before it.
+   *
+   * A message arriving is an ordinary event of a running instance, so the
+   * append does not hold the instance still while it lands (DR-0015). The
+   * chain is what keeps the file in the order the verbs happened: a delivery
+   * written before the add it answers would replay as a message nobody was
+   * ever holding. */
+  #append(record: Record_): Promise<void> {
+    const written = this.#written.then(async () => {
+      await mkdir(dirname(this.file), { recursive: true });
+      await appendFile(this.file, `${JSON.stringify(record)}\n`);
+    });
+    // The chain carries the order, not the outcome: a line that could not be
+    // written is answered to whoever asked for it, and the ones behind it still
+    // go.
+    this.#written = written.catch(() => {});
+    return written;
   }
 
   #compact(): void {

package/src/sessions/dump.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type {
   DumpPreset,
@@ -12,16 +12,15 @@ import type {
 import { OpError } from "../dispatch/index.ts";
 import {
   bounded,
-  classify,
   document as render,
   type Item,
   ledger,
-  located,
   select,
   selection,
   within,
 } from "../transcript/items/index.ts";
 import type { TranscriptFiles } from "../transcript/index.ts";
+import { classified } from "../transcript/scan.ts";
 
 /** Where dumps land: one directory under this instance's own state, named
  * after the config home it answers for like every other per-instance path
@@ -54,16 +53,19 @@ export interface DumpDeps {
  * `message.user.in` is the brief its parent gave it — so one selection carries
  * unchanged down a chain of agents, which is what makes the ledger's agent ids
  * a way to descend rather than just a list. */
-export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDumpWriteResult {
+export async function dumpWrite(
+  args: SessionDumpWriteArgs,
+  deps: DumpDeps,
+): Promise<SessionDumpWriteResult> {
   bounded(args);
   const preset = presetFor(args.preset, deps.presets);
-  const file = deps.files.locate(
+  const file = await deps.files.locate(
     args.sid,
     args.agent_id === undefined ? {} : { agent_id: args.agent_id },
   );
   let text: string;
   try {
-    text = readFileSync(file, "utf8");
+    text = await readFile(file, "utf8");
   } catch {
     throw new OpError("not_found", `the transcript of ${args.sid} could not be read`);
   }
@@ -80,7 +82,7 @@ export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDu
     deps.presets,
   );
   const { items, entries } = select(
-    within(classify(located(text), deps.files.subjectOf(file)), args),
+    within(await classified(text, await deps.files.subjectOf(file)), args),
     keep,
   );
   const ids = ledger(items);
@@ -111,10 +113,10 @@ export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDu
             ...(args.until_uuid === undefined ? {} : { until: args.until_uuid }),
           });
   const dir = join(deps.stateDir, DUMPS);
-  mkdirSync(dir, { recursive: true });
+  await mkdir(dir, { recursive: true });
   const named = args.agent_id === undefined ? args.sid : `${args.sid}-agent-${args.agent_id}`;
   const path = join(dir, `${named}-${written_at}${suffix(format)}`);
-  writeFileSync(path, body);
+  await writeFile(path, body);
   // What is counted is the selection, whatever the file ended up holding: that
   // is what the caller asked for and what it reads the answer against, and a
   // count that moved with the rendering would answer a different question each

package/src/sessions/fork.ts

@@ -1,7 +1,8 @@
-import { readFileSync, statSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
 import { dirname } from "node:path";
 import type { ForkOrigin, Sid } from "@ccmsg/protocol";
 import { readRecord, type TranscriptFiles } from "../transcript/index.ts";
+import { breathe, due } from "../transcript/scan.ts";
 
 /** How large a transcript may be and still be swept.
  *
@@ -36,18 +37,21 @@ const SWEEP_MAX_BYTES = 64 * 1024 * 1024;
  * Absent covers a session that is no fork, one whose ancestor file is gone,
  * and that undecidable pair. Nothing left on disk tells them apart, and none
  * of them has a seam to place. */
-export function forkOrigin(sid: Sid, files: TranscriptFiles): ForkOrigin | undefined {
+export async function forkOrigin(
+  sid: Sid,
+  files: TranscriptFiles,
+): Promise<ForkOrigin | undefined> {
   const file = files.session(sid);
-  const ours = recordIds(file);
+  const ours = await recordIds(file);
   const head = ours?.[0];
   if (ours === undefined || head === undefined) return undefined;
   const mine = new Set(ours);
 
   const dir = dirname(file);
   let best: { sid: Sid; copied: number } | undefined;
-  for (const candidate of files.all()) {
+  for (const candidate of await files.all()) {
     if (candidate.file === file || dirname(candidate.file) !== dir) continue;
-    const theirs = recordIds(candidate.file);
+    const theirs = await recordIds(candidate.file);
     if (theirs === undefined || theirs[0] !== head) continue;
     const copied = run(ours, new Set(theirs));
     const back = run(theirs, mine);
@@ -55,7 +59,7 @@ export function forkOrigin(sid: Sid, files: TranscriptFiles): ForkOrigin | undef
     // than their copy; an equal one says the records cannot tell, and creation
     // order is what is left.
     if (copied === 0 || back > copied) continue;
-    if (back === copied && !older(candidate.file, file)) continue;
+    if (back === copied && !(await older(candidate.file, file))) continue;
     // Sibling forks of one ancestor share a prefix too, so several files can
     // match; the longest run is the nearest ancestor and the true seam.
     if (best === undefined || copied > best.copied) best = { sid: candidate.sid, copied };
@@ -81,28 +85,31 @@ function run(ids: readonly string[], other: ReadonlySet<string>): number {
  * A creation time of zero is a filesystem that does not record one, which is
  * not an ancient file: two of those are simply not ordered, and the pair they
  * belong to gets no answer. */
-function older(candidate: string, file: string): boolean {
-  const theirs = bornAt(candidate);
-  const ours = bornAt(file);
+async function older(candidate: string, file: string): Promise<boolean> {
+  const theirs = await bornAt(candidate);
+  const ours = await bornAt(file);
   if (theirs === undefined || ours === undefined) return false;
   return theirs < ours;
 }
 
 /** Every record id in a file, in order. Undefined for a file too large to
  * sweep or one that could not be read. */
-function recordIds(file: string): string[] | undefined {
+async function recordIds(file: string): Promise<string[] | undefined> {
   let text: string;
   try {
-    if (statSync(file).size > SWEEP_MAX_BYTES) return undefined;
-    text = readFileSync(file, "utf8");
+    if ((await stat(file)).size > SWEEP_MAX_BYTES) return undefined;
+    text = await readFile(file, "utf8");
   } catch {
     return undefined;
   }
   const ids: string[] = [];
+  let read = 0;
   for (const line of text.split("\n")) {
     // Most of a transcript's bytes sit in a handful of very large records, and
     // parsing one to learn it carries no id is the cost this avoids.
     if (line === "" || !line.includes('"uuid"')) continue;
+    read += 1;
+    if (due(read)) await breathe();
     const uuid = readRecord(line)?.uuid;
     if (uuid !== undefined) ids.push(uuid);
   }
@@ -117,9 +124,9 @@ function recordIds(file: string): string[] | undefined {
  * millisecond the contract states instants in either — two transcripts written
  * moments apart share one, and the whole use of this value is telling which
  * came first. */
-function bornAt(file: string): number | undefined {
+async function bornAt(file: string): Promise<number | undefined> {
   try {
-    const born = statSync(file).birthtimeMs;
+    const born = (await stat(file)).birthtimeMs;
     return born > 0 ? born : undefined;
   } catch {
     return undefined;

package/src/sessions/handlers.ts

@@ -122,9 +122,11 @@ export function sessionHandlers(deps: SessionOpsDeps) {
      * cycle, happen where the config is read. */
     "dump.presets.read": (): DumpPresetsReadResult => ({ presets: [...deps.presets] }),
 
-    "session.fork.origin.read": (input: HandlerInput): SessionForkOriginReadResult => {
+    "session.fork.origin.read": async (
+      input: HandlerInput,
+    ): Promise<SessionForkOriginReadResult> => {
       const args = input.args as unknown as SessionForkOriginReadArgs;
-      const origin = forkOrigin(args.sid, deps.files);
+      const origin = await forkOrigin(args.sid, deps.files);
       return origin === undefined ? {} : { origin };
     },
 
@@ -135,7 +137,7 @@ export function sessionHandlers(deps: SessionOpsDeps) {
       return { removed: deps.forget(args.sid) };
     },
 
-    "transcript.read": (input: HandlerInput): TranscriptReadResult => {
+    "transcript.read": async (input: HandlerInput): Promise<TranscriptReadResult> => {
       const args = input.args as unknown as TranscriptReadArgs;
       if (!sees(args.sid, viewer(input))) {
         // The role sets the visible range, not the permission (DESIGN §2.2): outside
@@ -144,8 +146,8 @@ export function sessionHandlers(deps: SessionOpsDeps) {
         // the caller was not entitled to ask.
         throw new OpError("not_found", `no transcript is known for ${args.sid}`);
       }
-      const file = deps.files.locate(args.sid, args);
-      return readSlice(args.sid, file, args.before, args.max_bytes);
+      const file = await deps.files.locate(args.sid, args);
+      return await readSlice(args.sid, file, args.before, args.max_bytes);
     },
 
     /** The same transcript, as the items it was read into.
@@ -153,12 +155,12 @@ export function sessionHandlers(deps: SessionOpsDeps) {
      * The role narrows it the way it narrows the raw read: what a role may see
      * is one rule whatever is being read, and a caller that cannot see a
      * session cannot see it in either vocabulary. */
-    "transcript.items.read": (input: HandlerInput): TranscriptItemsReadResult => {
+    "transcript.items.read": async (input: HandlerInput): Promise<TranscriptItemsReadResult> => {
       const args = input.args as unknown as TranscriptItemsReadArgs;
       if (!sees(args.sid, viewer(input))) {
         throw new OpError("not_found", `no transcript is known for ${args.sid}`);
       }
-      return itemsRead(args, { files: deps.files, presets: deps.presets });
+      return await itemsRead(args, { files: deps.files, presets: deps.presets });
     },
   };
 }