@ccmsg/cli 0.12.0 → 0.14.0

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,16 +1,11 @@
-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,
+  type InboxRemovedReason,
   type Sid,
   type Timestamp,
 } from "@ccmsg/protocol";
@@ -44,8 +39,24 @@ 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
+   * reading of its own per way (DESIGN §6.7). Absent until somebody asks: a
+   * replay at startup reaches conclusions about a file, with nobody yet
+   * subscribed for them to be news to. */
+  #onRemoved?: (mid: string, reason: InboxRemovedReason) => void;
+
   constructor(private readonly file: string) {}
 
+  /** Hear about messages leaving. */
+  onRemoved(told: (mid: string, reason: InboxRemovedReason) => void): void {
+    this.#onRemoved = told;
+  }
+
   /** Replay the file, drop what has expired, and write back what is left.
    *
    * The rewrite is the only whole-file write, and it happens before anything
@@ -87,28 +98,53 @@ 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();
-    if (oldest !== undefined) this.#append({ v: "dropped", sid, mid: oldest.mid });
+    // 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) {
+      await this.#append({ v: "dropped", sid, mid: oldest.mid });
+      this.#onRemoved?.(oldest.mid, "dropped");
+    }
     return { evicted: true };
   }
 
   /** 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);
-    for (const mid of mids) this.#append({ v: "delivered", sid, mid });
+    const written: Promise<void>[] = [];
+    for (const mid of mids) {
+      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
@@ -154,14 +190,32 @@ export class Inbox {
       if (only !== undefined && sid !== only) continue;
       const left = held.filter((message) => now - message.sent_at <= INBOX_RETENTION_MS);
       if (left.length === held.length) continue;
+      const gone = new Set(left.map((message) => message.mid));
       if (left.length === 0) this.#held.delete(sid);
       else this.#held.set(sid, left);
+      for (const message of held) {
+        if (!gone.has(message.mid)) this.#onRemoved?.(message.mid, "expired");
+      }
     }
   }
 
-  #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/messaging/notify.ts

@@ -1,5 +1,6 @@
 import type {
   InstanceId,
+  Mid,
   Notification,
   NotifySendArgs,
   NotifySendResult,
@@ -48,7 +49,10 @@ export class Notify implements UpstreamResource {
    * caller otherwise, so a session notifying about itself says only the text. */
   send = (input: HandlerInput): NotifySendResult => {
     const args = input.args as unknown as NotifySendArgs;
-    this.#announce(args.sid ?? this.#caller(input), args.text);
+    // What it answers travels with it: a notification is shown while the
+    // session's own account of the same answer is still being written, and the
+    // `mid` is what tells a reader holding both that they are one thing.
+    this.#announce(args.sid ?? this.#caller(input), args.text, Date.now(), args.reply_to);
     return {};
   };
 
@@ -92,11 +96,12 @@ export class Notify implements UpstreamResource {
     return [];
   }
 
-  #announce(sid: Sid, text: string, now: Timestamp = Date.now()): Timestamp {
+  #announce(sid: Sid, text: string, now: Timestamp = Date.now(), reply_to?: Mid): Timestamp {
     const notification: Notification = {
       sid,
       sid_label: this.deps.label(sid),
       text,
+      ...(reply_to === undefined ? {} : { reply_to }),
       sent_at: now,
     };
     // A notification is an occurrence, so nothing folds it away and a watcher

package/src/sessions/dump.ts

@@ -1,23 +1,26 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type {
   DumpPreset,
   InstanceId,
   SessionDumpFile,
+  SessionDumpFormat,
   SessionDumpWriteArgs,
   SessionDumpWriteResult,
+  Timestamp,
 } from "@ccmsg/protocol";
 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
@@ -50,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`);
   }
@@ -76,11 +82,12 @@ 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);
   const written_at = Date.now();
+  const format = args.format ?? "items";
   // The file repeats what it was asked for. A dump outlives the request that
   // made it and is read by whoever was handed the path, so it has to say on
   // its own what it is a dump of and what was left out — which is why the
@@ -93,12 +100,27 @@ export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDu
     items,
     ids,
   };
+  const body =
+    format === "items"
+      ? `${JSON.stringify(document, undefined, 2)}\n`
+      : format === "records"
+        ? sourceLines(text, items)
+        : render(document, {
+            instance: deps.self,
+            ...(args.since_at === undefined ? {} : { since: moment(args.since_at) }),
+            ...(args.until_at === undefined ? {} : { until: moment(args.until_at) }),
+            ...(args.since_uuid === undefined ? {} : { since: args.since_uuid }),
+            ...(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}${DUMP_SUFFIX}`);
-  const body = `${JSON.stringify(document, undefined, 2)}\n`;
-  writeFileSync(path, body);
+  const path = join(dir, `${named}-${written_at}${suffix(format)}`);
+  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
+  // time (contract, `SessionDumpWriteResult`).
   return { path, instance: deps.self, entries, ids, bytes: Buffer.byteLength(body) };
 }
 
@@ -116,3 +138,43 @@ function presetFor(
   if (found === undefined) throw new OpError("invalid_args", `no preset is configured as ${name}`);
   return found;
 }
+
+/** The records the selected items were read from, as the file holds them.
+ *
+ * Taken out of the bytes by each item's own address rather than re-serialized,
+ * so what a tool reading the harness's format gets is the harness's own lines
+ * — nothing is added around them and nothing inside them is changed. Several
+ * items out of one record share that address, so the record is written once
+ * and the line count is not the item count (contract, `SessionDumpFormat`).
+ *
+ * One dump is one transcript — the session's, or one agent's when the request
+ * names one — so no line here has to say which file it came from. */
+function sourceLines(text: string, items: readonly Item[]): string {
+  const bytes = Buffer.from(text, "utf8");
+  const seen = new Set<number>();
+  const lines: string[] = [];
+  for (const item of items) {
+    const at = item.source.offset;
+    if (seen.has(at)) continue;
+    seen.add(at);
+    lines.push(
+      bytes
+        .subarray(at, at + item.source.bytes)
+        .toString("utf8")
+        .trimEnd(),
+    );
+  }
+  return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}
+
+/** What a file of this format is called. Whoever is handed the path opens it
+ * in whatever reads that kind of file, and a name saying `.json` for prose
+ * would send them to the wrong one. */
+function suffix(format: SessionDumpFormat): string {
+  return format === "items" ? DUMP_SUFFIX : format === "records" ? ".jsonl" : ".md";
+}
+
+/** A bound as the heading states it. */
+function moment(at: Timestamp): string {
+  return new Date(at).toISOString();
+}