@ccmsg/cli 0.1.0

package/src/service/service.ts

@@ -0,0 +1,359 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { CommandError } from "../daemon/link.ts";
+import { ENTRY } from "../daemon/registry.ts";
+import { type Env, resolveStateRoot } from "../instance/paths.ts";
+
+/** What the host's init system was asked, and what it said.
+ *
+ * A function rather than a call to `Bun.spawn` in place, so a test drives
+ * register and unregister without `launchctl` or `systemctl` on the real host
+ * ever hearing about it. */
+export type Run = (command: readonly string[]) => Promise<RunResult>;
+
+export interface RunResult {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export const runCommand: Run = async (command) => {
+  const proc = Bun.spawn([...command], { stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, stdout, stderr };
+};
+
+/** What `service status` answers about the supervisor itself. The instances are
+ * added by the caller, which is the one that can ask them. */
+export interface ServiceState {
+  readonly registered: boolean;
+  readonly running: boolean;
+  readonly pid?: number;
+  /** What the init system itself says, or `null` when it could not be asked.
+   *
+   * Beside the two fields above rather than folded into them: those are ccmsg's
+   * reading, and this is the host's — a supervisor the file registers but
+   * launchd never loaded is a disagreement worth being able to see. */
+  readonly service: ServiceReport | null;
+}
+
+/** The init system's own account of the supervisor, at the few points that say
+ * whether it is up and why it last was not. Every field is `null` when the
+ * answer did not carry it. */
+export interface ServiceReport {
+  /** The init system's own word for the state, unread: `running`,
+   * `not running`, `active`, `failed`. */
+  readonly state: string | null;
+  readonly loaded: boolean | null;
+  readonly running: boolean | null;
+  readonly pid: number | null;
+  /** What the last run exited with. The reason a supervisor that is not there
+   * is not there. */
+  readonly last_exit: number | null;
+}
+
+const UNKNOWN: ServiceReport = {
+  state: null,
+  loaded: null,
+  running: null,
+  pid: null,
+  last_exit: null,
+};
+
+/** One host's way of being told to keep a program running.
+ *
+ * The two implementations differ in every detail and agree on the shape: a file
+ * that describes the program, a command that puts it in front of the init
+ * system, and a way to ask what became of it. */
+export interface Service {
+  readonly kind: "launchd" | "systemd";
+  /** The file that describes the supervisor to the init system. */
+  readonly unitFile: string;
+  /** What that file says. Exposed so a test reads what would be written. */
+  unitText(): string;
+  register(run: Run): Promise<ServiceState>;
+  unregister(run: Run): Promise<{ unregistered: boolean }>;
+  /** Where this host keeps what the supervisor said: a file on one, a command
+   * on the other. Two shapes rather than one because they are two different
+   * things — launchd is told a path to redirect to, and systemd hands its
+   * units' output to the journal, which is read by asking for it. */
+  logSource(): LogSource;
+  start(run: Run): Promise<ServiceState>;
+  stop(run: Run): Promise<ServiceState>;
+  state(run: Run): Promise<ServiceState>;
+}
+
+export type LogSource =
+  | { readonly kind: "file"; readonly file: string }
+  | { readonly kind: "command"; readonly show: string[]; readonly follow: string[] };
+
+/** The program the init system is asked to keep running, and the environment it
+ * has to be given.
+ *
+ * The interpreter and script are this process's own (`ENTRY`'s reasoning), and
+ * the environment carries the variables that decide which files ccmsg uses: an
+ * init system starts a program with almost nothing set, so a supervisor
+ * registered from a shell where these were exported and started without them
+ * would quietly manage a different set of instances. */
+function supervisorCommand(): string[] {
+  return [process.execPath, ENTRY, "daemon", "supervise"];
+}
+
+const CARRIED = [
+  "PATH",
+  "HOME",
+  "CCMSG_CONFIG_DIR",
+  "CCMSG_STATE_DIR",
+  "XDG_CONFIG_HOME",
+  "XDG_STATE_HOME",
+] as const;
+
+function carriedEnv(env: Env): Record<string, string> {
+  const carried: Record<string, string> = {};
+  for (const name of CARRIED) {
+    const value = env[name];
+    if (value !== undefined && value !== "") carried[name] = value;
+  }
+  return carried;
+}
+
+/** Where the supervisor's own output goes.
+ *
+ * Beside the instances' state rather than in a per-instance directory: the
+ * supervisor belongs to no single config home, and `service log` is the one
+ * reader of it. On systemd the unit's output goes to the journal instead,
+ * which is where a user unit's output is read from and what `service log`
+ * asks there. */
+export function serviceLogFile(env: Env = process.env): string {
+  return join(resolveStateRoot(env), "service.log");
+}
+
+export const LAUNCHD_LABEL = "com.github.kawaz.ccmsg";
+export const SYSTEMD_UNIT = "ccmsg.service";
+
+/** The service for this host, or a refusal on a host that has neither. */
+export function serviceFor(env: Env = process.env, platform = process.platform): Service {
+  if (platform === "darwin") return new LaunchdService(env);
+  if (platform === "linux") return new SystemdService(env);
+  throw new CommandError("capability_unavailable", `${platform} には登録先がありません`);
+}
+
+class LaunchdService implements Service {
+  readonly kind = "launchd" as const;
+  readonly unitFile: string;
+  readonly #env: Env;
+  readonly #domain: string;
+
+  constructor(env: Env) {
+    this.#env = env;
+    const home = env["HOME"] ?? homedir();
+    this.unitFile = join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+    this.#domain = `gui/${String(process.getuid?.() ?? 0)}`;
+  }
+
+  /** `KeepAlive` rather than `RunAtLoad` alone: launchd restarting the
+   * supervisor is the outer half of the same job the supervisor does for its
+   * instances, and it is what makes a login survive the supervisor crashing. */
+  unitText(): string {
+    const log = serviceLogFile(this.#env);
+    return [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+      '<plist version="1.0">',
+      "<dict>",
+      `  <key>Label</key><string>${LAUNCHD_LABEL}</string>`,
+      "  <key>ProgramArguments</key>",
+      "  <array>",
+      ...supervisorCommand().map((arg) => `    <string>${escapeXml(arg)}</string>`),
+      "  </array>",
+      "  <key>EnvironmentVariables</key>",
+      "  <dict>",
+      ...Object.entries(carriedEnv(this.#env)).map(
+        ([name, value]) => `    <key>${name}</key><string>${escapeXml(value)}</string>`,
+      ),
+      "  </dict>",
+      "  <key>RunAtLoad</key><true/>",
+      "  <key>KeepAlive</key><true/>",
+      `  <key>StandardOutPath</key><string>${escapeXml(log)}</string>`,
+      `  <key>StandardErrorPath</key><string>${escapeXml(log)}</string>`,
+      "</dict>",
+      "</plist>",
+      "",
+    ].join("\n");
+  }
+
+  async register(run: Run): Promise<ServiceState> {
+    write(this.unitFile, this.unitText(), serviceLogFile(this.#env));
+    await run(["launchctl", "bootstrap", this.#domain, this.unitFile]);
+    return await this.state(run);
+  }
+
+  async unregister(run: Run): Promise<{ unregistered: boolean }> {
+    await run(["launchctl", "bootout", `${this.#domain}/${LAUNCHD_LABEL}`]);
+    const existed = existsSync(this.unitFile);
+    rmSync(this.unitFile, { force: true });
+    return { unregistered: existed };
+  }
+
+  async start(run: Run): Promise<ServiceState> {
+    await run(["launchctl", "kickstart", `${this.#domain}/${LAUNCHD_LABEL}`]);
+    return await this.state(run);
+  }
+
+  async stop(run: Run): Promise<ServiceState> {
+    await run(["launchctl", "kill", "SIGTERM", `${this.#domain}/${LAUNCHD_LABEL}`]);
+    return await this.state(run);
+  }
+
+  async state(run: Run): Promise<ServiceState> {
+    const registered = existsSync(this.unitFile);
+    const printed = await run(["launchctl", "print", `${this.#domain}/${LAUNCHD_LABEL}`]);
+    // A non-zero exit is launchd saying it has no such service, which is not
+    // the same as having nothing to say: the report stays `null` only when the
+    // question could not be put, and here it was and the answer was "no".
+    if (printed.code !== 0) {
+      return { registered, running: false, service: { ...UNKNOWN, loaded: false } };
+    }
+    // `launchctl print` states the pid only while there is a process; a service
+    // that is loaded and not running prints its state without one.
+    const pid = field(/^\s*pid = (\d+)$/m, printed.stdout);
+    const service: ServiceReport = {
+      state: /^\s*state = (.+)$/m.exec(printed.stdout)?.[1]?.trim() ?? null,
+      loaded: true,
+      running: pid !== null,
+      pid,
+      last_exit: field(/^\s*last exit (?:code|status) = (-?\d+)$/m, printed.stdout),
+    };
+    if (pid === null) return { registered, running: false, service };
+    return { registered, running: true, pid, service };
+  }
+
+  /** Where launchd was told to put the supervisor's output. */
+  logSource(): LogSource {
+    return { kind: "file", file: serviceLogFile(this.#env) };
+  }
+}
+
+class SystemdService implements Service {
+  readonly kind = "systemd" as const;
+  readonly unitFile: string;
+  readonly #env: Env;
+
+  constructor(env: Env) {
+    this.#env = env;
+    const home = env["HOME"] ?? homedir();
+    const config = env["XDG_CONFIG_HOME"] ?? join(home, ".config");
+    this.unitFile = join(config, "systemd", "user", SYSTEMD_UNIT);
+  }
+
+  /** `Restart=always` for `KeepAlive`'s reason, and `default.target` because a
+   * user service belongs to the user's session rather than to the boot. */
+  unitText(): string {
+    const environment = Object.entries(carriedEnv(this.#env)).map(
+      ([name, value]) => `Environment=${name}=${value}`,
+    );
+    return [
+      "[Unit]",
+      "Description=ccmsg instance supervisor",
+      "",
+      "[Service]",
+      `ExecStart=${supervisorCommand().join(" ")}`,
+      ...environment,
+      "Restart=always",
+      "RestartSec=1",
+      "",
+      "[Install]",
+      "WantedBy=default.target",
+      "",
+    ].join("\n");
+  }
+
+  /** The journal, which is where a user unit's output goes: systemd is not told
+   * a path, so there is no file to tail and the log is asked for instead. */
+  logSource(): LogSource {
+    const unit = ["journalctl", "--user", "-u", SYSTEMD_UNIT];
+    return { kind: "command", show: [...unit, "--no-pager"], follow: [...unit, "-f"] };
+  }
+
+  async register(run: Run): Promise<ServiceState> {
+    write(this.unitFile, this.unitText(), serviceLogFile(this.#env));
+    await run(["systemctl", "--user", "daemon-reload"]);
+    await run(["systemctl", "--user", "enable", "--now", SYSTEMD_UNIT]);
+    return await this.state(run);
+  }
+
+  async unregister(run: Run): Promise<{ unregistered: boolean }> {
+    await run(["systemctl", "--user", "disable", "--now", SYSTEMD_UNIT]);
+    const existed = existsSync(this.unitFile);
+    rmSync(this.unitFile, { force: true });
+    await run(["systemctl", "--user", "daemon-reload"]);
+    return { unregistered: existed };
+  }
+
+  async start(run: Run): Promise<ServiceState> {
+    await run(["systemctl", "--user", "start", SYSTEMD_UNIT]);
+    return await this.state(run);
+  }
+
+  async stop(run: Run): Promise<ServiceState> {
+    await run(["systemctl", "--user", "stop", SYSTEMD_UNIT]);
+    return await this.state(run);
+  }
+
+  async state(run: Run): Promise<ServiceState> {
+    const registered = existsSync(this.unitFile);
+    const shown = await run([
+      "systemctl",
+      "--user",
+      "show",
+      SYSTEMD_UNIT,
+      "--property=MainPID",
+      "--property=ActiveState",
+      "--property=LoadState",
+      "--property=ExecMainStatus",
+    ]);
+    if (shown.code !== 0) return { registered, running: false, service: null };
+    const fields = new Map(
+      shown.stdout
+        .split("\n")
+        .map((line) => line.split("="))
+        .filter((pair): pair is [string, string] => pair.length === 2)
+        .map(([name, value]) => [name as string, value as string]),
+    );
+    const pid = Number(fields.get("MainPID") ?? "0");
+    const running = fields.get("ActiveState") === "active" && pid > 0;
+    const exit = fields.get("ExecMainStatus");
+    const service: ServiceReport = {
+      state: fields.get("ActiveState") ?? null,
+      loaded: fields.get("LoadState") === "loaded",
+      running,
+      pid: pid > 0 ? pid : null,
+      last_exit: exit === undefined || exit === "" ? null : Number(exit),
+    };
+    return { registered, running, ...(running ? { pid } : {}), service };
+  }
+}
+
+/** Lay the unit down, and make sure the log it names has a directory. */
+function write(file: string, text: string, log: string): void {
+  mkdirSync(dirname(file), { recursive: true });
+  mkdirSync(dirname(log), { recursive: true });
+  writeFileSync(file, text);
+}
+
+/** One number a report names, or `null` when the answer did not name it. */
+function field(pattern: RegExp, text: string): number | null {
+  const found = pattern.exec(text)?.[1];
+  return found === undefined ? null : Number(found);
+}
+
+function escapeXml(text: string): string {
+  return text.replace(/[&<>]/g, (char) =>
+    char === "&" ? "&amp;" : char === "<" ? "&lt;" : "&gt;",
+  );
+}

package/src/sessions/classify.ts

@@ -0,0 +1,66 @@
+import type { SessionState, Timestamp } from "@ccmsg/protocol";
+
+/** What the harness's own row says, for a session that has one. */
+export interface HarnessPresence {
+  /** Its status is `waiting`, so a dialog is open (§5.1). */
+  waiting: boolean;
+  /** The terminal it runs in, when one could be read. Absent means unknown,
+   * which is what makes a live session unmanaged. */
+  terminal_id?: string;
+}
+
+/** Everything the classification reads, and nothing else (§5.1). */
+export interface SessionInputs {
+  /** A connection of this session is open to us right now. */
+  connected: boolean;
+  /** Present when the harness's `sessions/` has a row for it. */
+  harness?: HarnessPresence;
+  /** The last time the gateway saw inference for it (§5.1). Absent on an
+   * instance with no gateway configured, and for a session it has not seen. */
+  gateway_active_at?: Timestamp;
+  /** Its transcript's last turn ended on an API error (§5.1, from the fold).
+   * Absent for a session whose transcript nothing is following. */
+  api_error_stopped?: boolean;
+  /** Present when it is in `last_live`. */
+  last_live?: { stopped_at?: Timestamp };
+}
+
+/** How recently the gateway must have seen a session for that alone to count
+ * as being alive. */
+export const GATEWAY_LIVE_WINDOW_MS = 5 * 60 * 1000;
+
+/** The classification is the contract's `SessionState`, derived here rather
+ * than by whoever displays it (§5.2): a client combining raw values of its own
+ * would read two instances' lists by two rules.
+ *
+ * Pinned is not one of them. A person pins a row and the instance holds the
+ * mark beside the classification, but the mark never decides which state the
+ * row is in (§5.2).
+ *
+ * Busy and idle are not among them either, and not by omission: a live session
+ * carries how busy it is as an attribute of its row, so an instance with no
+ * gateway configured loses that attribute and none of these sections.
+ *
+ * Undefined is the session no section holds: never seen live and not in
+ * `last_live`, which is what a sid nobody has heard of looks like. */
+export function classify(
+  inputs: SessionInputs,
+  now: Timestamp = Date.now(),
+): SessionState | undefined {
+  const live =
+    inputs.connected ||
+    inputs.harness !== undefined ||
+    (inputs.gateway_active_at !== undefined &&
+      now - inputs.gateway_active_at <= GATEWAY_LIVE_WINDOW_MS);
+  // Waiting only says something about a session that is there to wait: an
+  // entry in last_live cannot be holding a dialog open.
+  if (live && (inputs.harness?.waiting === true || inputs.api_error_stopped === true)) {
+    return "waiting";
+  }
+  if (live) {
+    const reachable = inputs.connected || inputs.harness?.terminal_id !== undefined;
+    return reachable ? "live" : "live_unmanaged";
+  }
+  if (inputs.last_live === undefined) return undefined;
+  return inputs.last_live.stopped_at === undefined ? "disappeared" : "paused";
+}

package/src/sessions/dump.ts

@@ -0,0 +1,105 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { InstanceId, SessionDumpWriteArgs, SessionDumpWriteResult } from "@ccmsg/protocol";
+import { OpError } from "../dispatch/index.ts";
+import { readRecord, type TranscriptFiles, type TranscriptRecord } from "../transcript/index.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
+ * (§8.1). The caller never supplies a path, so there is none to contain. */
+export const DUMPS = "dumps";
+
+export interface DumpDeps {
+  readonly self: InstanceId;
+  readonly stateDir: string;
+  readonly files: TranscriptFiles;
+}
+
+/** Write a session's dump and answer with where it went.
+ *
+ * What this adds over reading the transcript is a durable artifact whose path
+ * can be handed to a successor session, rather than a payload that would
+ * travel out through a client and back in again. */
+export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDumpWriteResult {
+  if (args.since_at !== undefined && args.since_uuid !== undefined) {
+    throw new OpError("invalid_args", "a lower bound is a time or a record, not both");
+  }
+  if (args.until_at !== undefined && args.until_uuid !== undefined) {
+    throw new OpError("invalid_args", "an upper bound is a time or a record, not both");
+  }
+  const file = deps.files.session(args.sid);
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    throw new OpError("not_found", `the transcript of ${args.sid} could not be read`);
+  }
+  const entries = collect(text, args);
+  const document = {
+    sid: args.sid,
+    instance: deps.self,
+    source: file,
+    generated_at: Date.now(),
+    entries,
+  };
+  const dir = join(deps.stateDir, DUMPS);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${args.sid}-${document.generated_at}.json`);
+  const body = `${JSON.stringify(document, undefined, 2)}\n`;
+  writeFileSync(path, body);
+  return {
+    path,
+    instance: deps.self,
+    entries: entries.length,
+    bytes: Buffer.byteLength(body),
+  };
+}
+
+/** One record of a dump: what was said, by whom, when.
+ *
+ * The fields are the record's own, taken from the type that reads a transcript
+ * line rather than restated here — a dump reports what was read, and a second
+ * spelling of those fields would be a second interpretation of the file. */
+type DumpEntry = Pick<TranscriptRecord, "uuid" | "said_at" | "said_by" | "text" | "thinking">;
+
+/** The records within the bounds, in the order the transcript holds them.
+ *
+ * A record bound cuts at that record's position rather than at its clock, so
+ * records sharing an instant stay on their own side of the cut — which is the
+ * whole reason the contract offers both kinds of bound. */
+function collect(text: string, args: SessionDumpWriteArgs): DumpEntry[] {
+  const entries: DumpEntry[] = [];
+  // A lower bound by record starts the dump closed: it opens at the record it
+  // names, which is included.
+  let open = args.since_uuid === undefined;
+  for (const line of text.split("\n")) {
+    if (line === "") continue;
+    const record = readRecord(line);
+    if (record === undefined) continue;
+    if (!open) {
+      if (record.uuid !== args.since_uuid) continue;
+      open = true;
+    }
+    if (args.since_at !== undefined && (record.said_at ?? 0) < args.since_at) continue;
+    if (args.until_at !== undefined && (record.said_at ?? 0) > args.until_at) break;
+    // The machinery of in-process agents: their turns interleave into the
+    // session's own file, and a successor resuming the session is resuming the
+    // session rather than them.
+    if (args.no_agent === true && record.sidechain) {
+      if (record.uuid !== undefined && record.uuid === args.until_uuid) break;
+      continue;
+    }
+    entries.push({
+      ...(record.uuid === undefined ? {} : { uuid: record.uuid }),
+      ...(record.said_at === undefined ? {} : { said_at: record.said_at }),
+      ...(record.said_by === undefined ? {} : { said_by: record.said_by }),
+      ...(record.text === undefined ? {} : { text: record.text }),
+      ...(args.no_thinking === true || record.thinking === undefined
+        ? {}
+        : { thinking: record.thinking }),
+    });
+    // An upper bound by record is inclusive, so the cut is after it.
+    if (record.uuid !== undefined && record.uuid === args.until_uuid) break;
+  }
+  return entries;
+}

package/src/sessions/fork.ts

@@ -0,0 +1,127 @@
+import { readFileSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import type { ForkOrigin, Sid } from "@ccmsg/protocol";
+import { readRecord, type TranscriptFiles } from "../transcript/index.ts";
+
+/** How large a transcript may be and still be swept.
+ *
+ * Finding a seam means reading two files whole, and the answer decorates a
+ * divider. A transcript past this size simply yields no seam, which is the same
+ * answer the op already gives for a session that is no fork. */
+const SWEEP_MAX_BYTES = 64 * 1024 * 1024;
+
+/** Where a forked session stopped being a copy of its ancestor.
+ *
+ * Forking duplicates the ancestor's records keeping each record id, and
+ * rewrites the session id on every copy — so nothing inside the file marks a
+ * copied record, and the seam can only be found by comparing against the
+ * sibling transcripts beside it.
+ *
+ * Sharing a first record id means two files begin with the same record, which
+ * happens only by duplication. Which of the pair is the copy is then read out
+ * of the records themselves, by walking each file's ids against the other's as
+ * a set rather than position by position: the ancestor holds records the fork
+ * did not copy — a subagent's turns interleave into the parent and not into
+ * what was copied — so the fork's run into the ancestor reaches past where the
+ * ancestor's run into the fork stops. The longer run is the copy.
+ *
+ * Only when the two runs are equal does the copying leave no trace of its
+ * direction, and only then is creation order asked for. A filesystem that
+ * states no creation time answers nothing there rather than falling back to a
+ * time that means something else: a transcript is appended to for as long as
+ * its session runs, so every other timestamp a file carries orders the two by
+ * when they were last written, which is unrelated to which was copied from
+ * which — and on a live ancestor points the wrong way.
+ *
+ * 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 {
+  const file = files.session(sid);
+  const ours = 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()) {
+    if (candidate.file === file || dirname(candidate.file) !== dir) continue;
+    const theirs = recordIds(candidate.file);
+    if (theirs === undefined || theirs[0] !== head) continue;
+    const copied = run(ours, new Set(theirs));
+    const back = run(theirs, mine);
+    // A run that reaches no further than theirs makes us their ancestor rather
+    // 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;
+    // 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 };
+  }
+  if (best === undefined) return undefined;
+  // The whole file being copied means no forked turns exist yet, and there is
+  // no seam to draw below the last record.
+  if (best.copied >= ours.length) return undefined;
+  const boundary = ours[best.copied - 1];
+  if (boundary === undefined) return undefined;
+  return { sid: best.sid, boundary_uuid: boundary, copied: best.copied };
+}
+
+/** How far into a file's records every id is one the other file also holds. */
+function run(ids: readonly string[], other: ReadonlySet<string>): number {
+  let reached = 0;
+  while (reached < ids.length && other.has(ids[reached] ?? "")) reached += 1;
+  return reached;
+}
+
+/** Whether one file was created before the other, when the filesystem says.
+ *
+ * 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);
+  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 {
+  let text: string;
+  try {
+    if (statSync(file).size > SWEEP_MAX_BYTES) return undefined;
+    text = readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+  const ids: string[] = [];
+  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;
+    const uuid = readRecord(line)?.uuid;
+    if (uuid !== undefined) ids.push(uuid);
+  }
+  return ids;
+}
+
+/** When a file came into being, for the one pair the records cannot order.
+ *
+ * Only the creation time, and only when the filesystem states one: everything
+ * else a file carries says when it was last written, which for a transcript is
+ * how long its session ran rather than when it began. Not rounded to the
+ * 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 {
+  try {
+    const born = statSync(file).birthtimeMs;
+    return born > 0 ? born : undefined;
+  } catch {
+    return undefined;
+  }
+}