omp-mobile 0.4.2 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-mobile",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "The computer side of OMP Mobile: runs oh-my-pi sessions and serves them to the phone app over Tailscale.",
   "keywords": [
     "mobile",

package/src/omp-extension.mjs

@@ -21,7 +21,7 @@ import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { renderQr } from "./qr.mjs";
-import { requestPath } from "./takeover.mjs";
+import { requestPath, shellWord } from "./takeover.mjs";
 
 const HOME = join(homedir(), ".omp-mobile");
 const STATE_FILE = join(HOME, "daemon.json");
@@ -229,7 +229,7 @@ export default function ompMobile(pi) {
       rmSync(requestPath(file), { force: true });
       // OMP closes once the session is idle; the daemon signals it if that does not come soon,
       // and tells the terminal where the session went once omp is gone.
-      ctx.ui.notify(`OMP Mobile: this session continues on ${request.device}. Closing omp here…`, "warning");
+      ctx.ui.notify(`OMP Mobile: this session continues on ${request.device}. Closing omp here; resume it later with: omp --resume ${shellWord(file)}`, "warning");
       if (!ctx.isIdle()) {
         ctx.abort();
         const deadline = Date.now() + TAKEOVER_IDLE_WAIT_MS;

package/src/omp-sessions.mjs

@@ -16,7 +16,7 @@ const TITLE_SCAN_BYTES = 512 * 1024;
 const CHUNK_BYTES = 64 * 1024;
 const LSOF_TIMEOUT_MS = 5_000;
 
-/** @typedef {{id: string, title: string, cwd: string, createdAt: number, updatedAt: number, sessionFile: string}} OmpSession */
+/** @typedef {{id: string, title: string, cwd: string, createdAt: number, updatedAt: number, size: number, sessionFile: string}} OmpSession */
 
 /** Text of an OMP message content field (string or content-part array). */
 function textOfContent(content) {
@@ -103,6 +103,8 @@ export async function readSessionFile(file) {
       cwd: header.cwd,
       createdAt: Number.isFinite(created) ? created : info.birthtimeMs,
       updatedAt: info.mtimeMs,
+      // With the time, what tells this daemon's own omp leaving the file from someone writing it.
+      size: info.size,
       sessionFile: file,
     };
   } finally {

package/src/server.mjs

@@ -20,6 +20,7 @@ import { Admission, Tailscale, isLoopbackHost } from "./admission.mjs";
 import { AttentionTracker, serveEvents } from "./attention.mjs";
 import { listOmpSessions, oneLine, promptTitle, sessionOwners } from "./omp-sessions.mjs";
 import { askOwnerToLeave, forksOf, isOmpCommand, processInfo, sessionBusy, takeoverFarewell, tellTerminal } from "./takeover.mjs";
+import { TranscriptStore, deltaBody, deltaQuery } from "./transcripts.mjs";
 
 const { version: VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const PROTOCOL = 1;
@@ -55,6 +56,8 @@ const HEARTBEAT_MS = 20_000;
 /** A live omp nobody has looked at for this long is closed; the next open resumes it. */
 const IDLE_SESSION_MS = 30 * 60_000;
 const REAP_INTERVAL_MS = 60_000;
+/** Messages a live session keeps in memory; older ones leave its front (its `base` counts them). */
+const MAX_LIVE_MESSAGES = 5_000;
 /**
  * The fields of a tool result's `details` the app reads: an edit's diff, a
  * read's line count, a command's run time, a screenshot's file. The rest
@@ -100,9 +103,11 @@ export function promptImages(value) {
  * the computer it talks to can do. `prompt-images`: `prompt` frames carry `images`;
  * `takeover`: `POST /sessions/:id/takeover` continues a session another omp process holds;
  * `heartbeat`: session sockets get a `ping` frame every 20 s, so the app can
- * treat a silent link as gone.
+ * treat a silent link as gone; `transcript-sync`: a session socket's `since`/`last`
+ * ask for a delta snapshot (`from`, `total`), and `GET /sessions/:id/transcript`
+ * answers the same without starting an omp.
  */
-const FEATURES = ["prompt-images", "takeover", "heartbeat"];
+const FEATURES = ["prompt-images", "takeover", "heartbeat", "transcript-sync"];
 /** Who a phone continues a session on, as the terminal it leaves is told. */
 const DEFAULT_DEVICE = "OMP Mobile";
 /** Close code after an `open_failed` frame: the session socket opened only to say why the session could not. */
@@ -376,6 +381,46 @@ export function pruneBlobCache(blobDir, now = Date.now()) {
   return dropped;
 }
 
+/**
+ * When the messages were last written: the newest timestamp OMP stamped on
+ * them, or undefined when none carries one.
+ * @param {readonly any[]} messages
+ */
+export function lastActivity(messages) {
+  let latest;
+  for (let i = messages.length - 1; i >= 0 && i >= messages.length - 50; i -= 1) {
+    const at = Number(messages[i]?.timestamp);
+    if (Number.isFinite(at) && at > 0 && (latest === undefined || at > latest)) latest = at;
+  }
+  return latest;
+}
+
+/**
+ * When a session the daemon knows but has no omp for was last used: what the
+ * registry says, or its file's time when something wrote the file since --
+ * unless the file is exactly as this daemon's own omp left it on exit (omp
+ * rewrites the whole file as it closes; that is not anyone using it).
+ * @param {{updatedAt?: number, closedFile?: {mtimeMs: number, size: number}} | undefined} stored
+ * @param {{updatedAt: number, size?: number} | undefined} scanned
+ */
+export function dormantActivity(stored, scanned) {
+  const known = Number(stored?.updatedAt) || 0;
+  if (scanned === undefined || !(scanned.updatedAt > known)) return known;
+  const closed = stored?.closedFile;
+  if (closed !== undefined && closed !== null && closed.mtimeMs === scanned.updatedAt && closed.size === scanned.size) return known;
+  return scanned.updatedAt;
+}
+
+/** A file's time and size, as `TranscriptStore` checks them; undefined when it cannot be read. */
+function fileState(path) {
+  try {
+    const info = statSync(path);
+    return info.isFile() ? { mtimeMs: info.mtimeMs, size: info.size } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function storedSummary(stored) {
   return {
     id: stored.id,
@@ -503,6 +548,10 @@ class SessionEntry {
     this.id = "";
     this.state = null;
     this.messages = [];
+    /** How many messages left the front of `messages` (the cap): `messages[0]` is the transcript's message `base`. */
+    this.base = 0;
+    /** The session file as this omp left it on exit, so its rewrite is not taken for activity. */
+    this.closedFile = undefined;
     this.createdAt = Date.now();
     this.updatedAt = this.createdAt;
     this.title = cwd.split("/").filter(Boolean).at(-1) ?? "session";
@@ -520,15 +569,26 @@ class SessionEntry {
     this.idleSince = undefined;
     /** Where inline images go (see `phoneMessage`); undefined keeps them inline. */
     this.blobDir = undefined;
+    /**
+     * Hears the omp process exit, once its session file is final (the daemon saves the transcript).
+     * @type {((entry: SessionEntry) => void) | undefined}
+     */
+    this.onClosed = undefined;
   }
 
-  async hydrate() {
+  /**
+   * @param {number} [knownActivity] when the session was last used, as the daemon knew it before this omp
+   */
+  async hydrate(knownActivity) {
     const [state, messages] = await Promise.all([this.rpc.getState(), this.rpc.getMessages()]);
     this.state = state;
     this.messages = Array.isArray(messages.messages) ? messages.messages.map((message) => phoneMessage(message, this.blobDir)) : [];
+    this.base = 0;
     this.id = state.sessionId ?? "";
     this.title = titleOf(this.messages, state, this.cwd);
-    this.updatedAt = Date.now();
+    // Opening a session is not using it: it is as recent as its last message (a new one: now).
+    const known = Math.max(lastActivity(this.messages) ?? 0, Number(knownActivity) || 0);
+    this.updatedAt = known > 0 ? known : Date.now();
     return this;
   }
 
@@ -548,12 +608,13 @@ class SessionEntry {
     };
   }
 
-  snapshot() {
-    return {
-      session: this.summary(),
-      state: this.state,
-      messages: this.messages,
-    };
+  /**
+   * What a phone is sent on open: everything, or only the messages after the
+   * ones it holds when its copy lines up (see `deltaBody`).
+   * @param {{since: number, last: string}} [held]
+   */
+  snapshot(held) {
+    return deltaBody({ session: this.summary(), state: this.state, messages: this.messages, base: this.base }, held);
   }
 
   broadcast(payload) {
@@ -567,7 +628,6 @@ class SessionEntry {
   async refreshState() {
     try {
       this.state = await this.rpc.getState();
-      this.updatedAt = Date.now();
       this.broadcast({ type: "state", state: this.state });
     } catch {
       // The process may be exiting; the close event tells clients.
@@ -576,10 +636,17 @@ class SessionEntry {
 
   bind() {
     this.rpc.on("event", (event) => {
-      this.updatedAt = Date.now();
       if (event.type === "message_end" && event.message) {
+        // A new message is what makes a session the most recent one; opening it,
+        // a lifecycle event from a resumed omp, or a state echo are not.
+        this.updatedAt = Date.now();
         this.messages.push(phoneMessage(event.message, this.blobDir));
-        if (this.messages.length > 5_000) this.messages.splice(0, this.messages.length - 5_000);
+        if (this.messages.length > MAX_LIVE_MESSAGES) {
+          // Indices stay the transcript's: a phone's `since` still lines up after the front is dropped.
+          const dropped = this.messages.length - MAX_LIVE_MESSAGES;
+          this.messages.splice(0, dropped);
+          this.base += dropped;
+        }
         // The first prompt names a session that was created untitled.
         const title = titleOf(this.messages, this.state, this.cwd);
         if (title !== this.title) {
@@ -606,6 +673,11 @@ class SessionEntry {
     this.rpc.on("closed", ({ reason, stderr }) => {
       this.closed = true;
       this.broadcast({ type: "closed", reason, stderr: stderr.slice(-2_000) });
+      try {
+        this.onClosed?.(this);
+      } catch {
+        // Saving the transcript is a shortcut; the session file has everything.
+      }
     });
     this.rpc.on("protocol-error", (payload) => this.broadcast({ type: "protocol-error", ...payload }));
   }
@@ -667,6 +739,8 @@ class Daemon {
     this.takingOver = new Map();
     /** Images stashed out of snapshots, served by `/blobs` next to OMP's own store. */
     this.blobDir = options.blobDir ?? join(dirname(options.registryFile ?? DEFAULT_REGISTRY_FILE), "blobs");
+    /** Transcripts of sessions whose omp exited, served by `/transcript` without starting one. */
+    this.transcripts = new TranscriptStore(options.transcriptDir ?? join(dirname(options.registryFile ?? DEFAULT_REGISTRY_FILE), "transcripts"));
     this.server = createServer((req, res) => void this.admitHttp(req, res));
     // Compressed frames: a snapshot is JSON text, several times smaller deflated, and
     // the phone's WebSocket client (OkHttp) asks for permessage-deflate on its own.
@@ -789,6 +863,11 @@ class Daemon {
         sendJson(res, 200, await this.takeOver(decodeURIComponent(takeover[1]), device));
         return;
       }
+      const transcript = /^\/sessions\/([^/]+)\/transcript$/.exec(url.pathname);
+      if (transcript !== null && req.method === "GET") {
+        sendJson(res, 200, this.transcript(decodeURIComponent(transcript[1]), deltaQuery(url.searchParams)));
+        return;
+      }
       const match = /^\/sessions\/([^/]+)$/.exec(url.pathname);
       if (match !== null) {
         const id = decodeURIComponent(match[1]);
@@ -799,8 +878,13 @@ class Daemon {
         }
         if (req.method === "DELETE") {
           const live = this.sessions.get(id);
-          if (live !== undefined) this.attention.forget(live);
+          if (live !== undefined) {
+            this.attention.forget(live);
+            // Closed for good: its exit must not save it, or bring it back into the registry.
+            live.onClosed = undefined;
+          }
           live?.close();
+          this.transcripts.remove(id);
           this.forgetOwners();
           this.sessions.delete(id);
           this.registry.delete(id);
@@ -835,6 +919,10 @@ class Daemon {
     const others = found
       .filter((session) => !known.has(session.id))
       .map((session) => ({ ...session, status: "idle", origin: "omp" }));
+    // A dormant session is as recent as its file when a terminal omp wrote it since, not when our own omp's exit did.
+    for (const session of dormant) {
+      session.updatedAt = dormantActivity(this.registry.get(session.id), this.ompSessions.get(session.id));
+    }
     const marked = await Promise.all(
       [...dormant, ...others].map(async (session) => {
         const pid = owners?.get(session.id);
@@ -891,6 +979,31 @@ class Daemon {
     this.ownerLookup = { at: 0, owners: undefined };
   }
 
+  /**
+   * A session's transcript without starting an omp: a live session's from
+   * memory, a closed one's from its saved copy while its session file is
+   * unchanged; otherwise a 404 the phone skips.
+   * @param {string} id
+   * @param {{since: number, last: string}} held
+   */
+  transcript(id, held) {
+    const live = this.sessions.get(id);
+    if (live !== undefined && !live.closed) return live.snapshot(held);
+    const known = this.registry.get(id)?.sessionFile ?? this.ompSessions.get(id)?.sessionFile;
+    const saved = this.transcripts.read(id, typeof known === "string" ? known : undefined);
+    if (saved === undefined) throw httpError(404, "not cached");
+    return deltaBody(saved, held);
+  }
+
+  /** The omp of a session exited: save its transcript and when it was last active. */
+  sessionClosed(entry) {
+    if (entry.id === "") return;
+    const sessionFile = entry.state?.sessionFile;
+    entry.closedFile = typeof sessionFile === "string" ? fileState(sessionFile) : undefined;
+    this.transcripts.write(entry.id, { sessionFile, messages: entry.messages, base: entry.base, state: entry.state, session: entry.summary() });
+    if (this.registry.has(entry.id)) this.remember(entry);
+  }
+
   remember(entry) {
     this.registry.set(entry.id, {
       id: entry.id,
@@ -900,6 +1013,8 @@ class Daemon {
       createdAt: entry.createdAt,
       updatedAt: entry.updatedAt,
       sessionFile: entry.state?.sessionFile,
+      // Set once its omp exited: the file as that omp left it (see `dormantActivity`).
+      ...(entry.closedFile !== undefined ? { closedFile: entry.closedFile } : {}),
     });
     saveRegistry(this.options.registryFile, this.registry);
   }
@@ -953,10 +1068,13 @@ class Daemon {
       await rpc.start();
       const entry = new SessionEntry(stored.cwd, rpc);
       entry.blobDir = this.blobDir;
-      await entry.hydrate();
+      await entry.hydrate(this.registry.has(id) ? dormantActivity(this.registry.get(id), this.ompSessions.get(id)) : stored.updatedAt);
       entry.id = id;
+      // Idle from now for the reaper, until a phone attaches: its last activity may be long ago.
+      entry.idleSince = Date.now();
       entry.onChange = (changed) => this.remember(changed);
       entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
+      entry.onClosed = (closed) => this.sessionClosed(closed);
       entry.bind();
       this.sessions.set(id, entry);
       this.remember(entry);
@@ -1007,7 +1125,7 @@ class Daemon {
       const deadline = Date.now() + 3_000;
       while ((await this.owners())?.get(id) === pid && Date.now() < deadline) await new Promise((wait) => setTimeout(wait, 100));
       // Whoever looks at the terminal sees why omp closed.
-      if (info?.tty !== undefined) tellTerminal(info.tty, takeoverFarewell(device));
+      if (info?.tty !== undefined) tellTerminal(info.tty, takeoverFarewell({ device, sessionFile: stored.sessionFile }));
       const forks = forksOf(dirname(stored.sessionFile), id, since);
       if (forks.length > 0) this.log(new Error(`taking over ${id} from pid ${pid} left forked session files: ${forks.join(", ")}`));
       outcome = { pid, via: left.via, waitedMs: left.waitedMs, busy, forks };
@@ -1032,8 +1150,10 @@ class Daemon {
       entry.blobDir = this.blobDir;
       await entry.hydrate();
       if (entry.id === "") throw new Error("omp returned no session id");
+      entry.idleSince = Date.now();
       entry.onChange = (changed) => this.remember(changed);
       entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
+      entry.onClosed = (closed) => this.sessionClosed(closed);
       entry.bind();
       this.sessions.set(entry.id, entry);
       this.remember(entry);
@@ -1059,6 +1179,8 @@ class Daemon {
     }
     this.noteClient(req);
     const id = decodeURIComponent(match[1]);
+    // What the phone already holds, read now: the snapshot is cut against it once the session is open.
+    const held = deltaQuery(url.searchParams);
     // Finish the handshake before the session is open: a slow omp can take
     // tens of seconds, and a phone's WebSocket client gives up after ~10 s --
     // then retries, starting another omp every time. The snapshot (or
@@ -1091,7 +1213,7 @@ class Daemon {
           if (ws.readyState !== 1) return;
           live.clients.add(ws);
           live.idleSince = undefined;
-          ws.send(JSON.stringify({ type: "snapshot", ...live.snapshot() }));
+          ws.send(JSON.stringify({ type: "snapshot", ...live.snapshot(held) }));
           // A dialog opened before this client connected (it may have come from a notification tap).
           for (const request of live.openRequests()) ws.send(JSON.stringify({ type: "approval", request }));
           for (const data of early) void this.handleClientMessage(live, ws, data);
@@ -1131,6 +1253,8 @@ class Daemon {
           const text = typeof message.text === "string" ? message.text : "";
           if (text.trim() === "" && images.length === 0) throw new Error("empty prompt");
           await entry.rpc.prompt(text, images);
+          entry.updatedAt = Date.now();
+          entry.onChange?.(entry);
           ws.send(JSON.stringify({ type: "accepted", command: "prompt" }));
           return;
         }
@@ -1162,7 +1286,6 @@ class Daemon {
           }
           const state = await entry.rpc.setModel(message.provider, message.modelId);
           entry.state = state;
-          entry.updatedAt = Date.now();
           entry.onChange?.(entry);
           entry.broadcast({ type: "state", state });
           ws.send(JSON.stringify({ type: "accepted", command: "set_model" }));
@@ -1179,7 +1302,6 @@ class Daemon {
           if (typeof message.level !== "string" || message.level === "") throw new Error("set_thinking_level needs a level");
           const state = await entry.rpc.setThinkingLevel(message.level);
           entry.state = state;
-          entry.updatedAt = Date.now();
           entry.broadcast({ type: "state", state });
           ws.send(JSON.stringify({ type: "accepted", command: "set_thinking_level" }));
           return;
@@ -1222,6 +1344,7 @@ class Daemon {
   /** Keepalive pings and the idle-session reaper, once the daemon listens; old stashed images go. */
   startTimers() {
     pruneBlobCache(this.blobDir);
+    this.transcripts.prune();
     this.heartbeat = setInterval(() => this.pingClients(), this.options.heartbeatMs ?? HEARTBEAT_MS);
     this.heartbeat.unref?.();
     this.reaper = setInterval(() => this.reapIdleSessions(), this.options.reapIntervalMs ?? REAP_INTERVAL_MS);
@@ -1395,4 +1518,4 @@ if (isMain) {
   });
 }
 
-export { Daemon, SessionEntry, VERSION, PROTOCOL, parseArgs, resolveIdentity };
+export { Daemon, SessionEntry, VERSION, PROTOCOL, FEATURES, parseArgs, resolveIdentity };

package/src/takeover.mjs

@@ -175,9 +175,21 @@ export function tellTerminal(tty, text) {
   }
 }
 
-/** What the terminal is told once omp left it. */
-export function takeoverFarewell(device) {
-  return `omp-mobile: this session continues on ${device}. omp closed here so the phone could take it over.`;
+/** A path as a shell word: quoted only when it has to be. */
+export function shellWord(value) {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * What the terminal is told once omp left it: where the session went, and the
+ * command that brings it back -- the hint leaving omp by hand also leaves.
+ * @param {{device: string, sessionFile: string}} leaving
+ */
+export function takeoverFarewell({ device, sessionFile }) {
+  const lines = [`This session continues on the phone (${device}).`, "omp closed here so the phone could take it over."];
+  const file = typeof sessionFile === "string" && sessionFile !== "" ? shellWord(sessionFile) : "";
+  if (file !== "") lines.push("", "Resume it in this terminal with:", `  omp --resume ${file}`);
+  return lines.join("\n");
 }
 
 const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));

package/src/transcripts.mjs

@@ -0,0 +1,227 @@
+/**
+ * The daemon's saved transcripts: the slim messages of each session it had
+ * open, written when the session's omp exits (the reaper, the daemon
+ * stopping, omp leaving on its own), so a phone can read a recent session
+ * without the daemon starting an omp for it.
+ *
+ * A record is valid while the session file it was read from has the same
+ * modification time and size: anything that wrote the session since (a
+ * terminal omp, a resume elsewhere) makes it stale, and it is not served.
+ * Records are kept while their session was active in the last
+ * {@link RECENT_MS}; nothing is evicted by count.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** How long after its last activity a session's transcript is kept, on the computer and on the phone. */
+export const RECENT_MS = 24 * 60 * 60_000;
+const VERSION = 1;
+const NAME = /^[A-Za-z0-9_-]{1,140}\.json$/;
+/** A temporary file left by a write that never finished (a crash) is dropped after this long. */
+const TEMP_MAX_AGE_MS = 60_000;
+let writes = 0;
+
+/**
+ * What identifies one message well enough to line a phone's copy up with the
+ * daemon's: OMP stamps every message, and tool results and replies carry ids.
+ * The app computes the same string (`app/src/cache.ts`).
+ * @param {any} message
+ */
+export function fingerprint(message) {
+  if (message === null || typeof message !== "object") return "";
+  const id = typeof message.toolCallId === "string" ? message.toolCallId : typeof message.responseId === "string" ? message.responseId : "";
+  return `${String(message.role ?? "")}:${String(message.timestamp ?? "")}:${id}`;
+}
+
+/**
+ * Where a phone that holds the first `since` messages (the last of them
+ * fingerprinted `last`) can continue: `since` when its copy lines up with
+ * `messages` there, else 0 (send everything). Indices are the transcript's:
+ * `messages` start at `base`, the count a long session dropped from its front.
+ * @param {readonly any[]} messages
+ * @param {number} since
+ * @param {string} last
+ * @param {number} [base]
+ */
+export function deltaFrom(messages, since, last, base = 0) {
+  if (!Array.isArray(messages) || !Number.isSafeInteger(since) || since <= base || since > base + messages.length) return 0;
+  if (typeof last !== "string" || last === "") return 0;
+  return fingerprint(messages[since - 1 - base]) === last ? since : 0;
+}
+
+/**
+ * The `since` and `last` query parameters, as a phone sends them; anything
+ * malformed reads as "nothing held" (a whole transcript).
+ * @param {URLSearchParams} searchParams
+ */
+export function deltaQuery(searchParams) {
+  const raw = searchParams.get("since") ?? "";
+  const since = /^\d{1,9}$/.test(raw) ? Number(raw) : 0;
+  return { since, last: searchParams.get("last") ?? "" };
+}
+
+/**
+ * The body of a snapshot frame or a `/transcript` answer: the messages after
+ * what the phone holds when its copy lines up, else all of them. `from` is the
+ * index of the first message sent (0: the whole transcript), `total` how many
+ * the transcript has. A session past the daemon's cap holds only its last
+ * messages, from index `base` on: a delta is still cut at the phone's `since`,
+ * and everything is sent as a whole transcript of what is held, with `base`
+ * saying where in the session it starts.
+ * @param {{session: any, state: any, messages: any[], base?: number}} transcript
+ * @param {{since: number, last: string}} [held]
+ */
+export function deltaBody({ session, state, messages, base = 0 }, held = { since: 0, last: "" }) {
+  const start = Number.isSafeInteger(base) && base > 0 ? base : 0;
+  const from = deltaFrom(messages, held.since, held.last, start);
+  if (from > 0) return { session, state, from, total: start + messages.length, messages: messages.slice(from - start) };
+  return { session, state, from: 0, total: messages.length, messages, ...(start > 0 ? { base: start } : {}) };
+}
+
+function fileState(path) {
+  try {
+    const info = statSync(path);
+    return info.isFile() ? { mtimeMs: info.mtimeMs, size: info.size } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** A record that still describes its session file as it is now. */
+function current(record) {
+  if (typeof record?.sessionFile !== "string") return false;
+  const now = fileState(record.sessionFile);
+  return now !== undefined && now.mtimeMs === record.file?.mtimeMs && now.size === record.file?.size;
+}
+
+export class TranscriptStore {
+  /** @param {string} dir */
+  constructor(dir) {
+    this.dir = dir;
+  }
+
+  /** @param {string} id */
+  path(id) {
+    const safe = id.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 120);
+    // Two ids that differ only in characters a file name cannot carry must not share a file.
+    const name = safe === id ? safe : `${safe}-${createHash("sha256").update(id).digest("hex").slice(0, 16)}`;
+    return join(this.dir, `${name}.json`);
+  }
+
+  /**
+   * Save a session's slim messages against the current state of its file:
+   * call it once omp has exited, when the file is final. Best effort: a full
+   * disk only loses the shortcut.
+   * @param {string} id
+   * @param {{sessionFile?: string, messages: any[], state: any, session: any, base?: number}} record
+   * @returns {boolean} whether it was saved
+   */
+  write(id, { sessionFile, messages, state, session, base = 0 }) {
+    if (typeof id !== "string" || id === "" || typeof sessionFile !== "string" || !Array.isArray(messages)) return false;
+    const file = fileState(sessionFile);
+    if (file === undefined) return false;
+    const path = this.path(id);
+    writes += 1;
+    const temporary = `${path}.${process.pid}-${writes}.tmp`;
+    // No omp runs for it any more: nothing streams and nothing waits for an answer.
+    const record = {
+      v: VERSION,
+      id,
+      sessionFile,
+      file,
+      savedAt: Date.now(),
+      // When the session was last used: omp rewrites its file as it exits, so the file's time is not that.
+      activeAt: Number(session?.updatedAt) || file.mtimeMs,
+      base: Number.isSafeInteger(base) && base > 0 ? base : 0,
+      messages,
+      state: state !== null && typeof state === "object" ? { ...state, isStreaming: false } : state,
+      session: { ...session, status: "idle", waiting: 0 },
+    };
+    try {
+      mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+      writeFileSync(temporary, JSON.stringify(record), { mode: 0o600 });
+      renameSync(temporary, path);
+      return true;
+    } catch {
+      try {
+        unlinkSync(temporary);
+      } catch {
+        // Never written.
+      }
+      return false;
+    }
+  }
+
+  /**
+   * A saved transcript that still matches its session file, else undefined.
+   * Its session is dated by its last activity, not by the file: the file was
+   * last written by the omp exiting.
+   * @param {string} id
+   * @param {string | undefined} sessionFile the file the session is known by now, when known
+   */
+  read(id, sessionFile) {
+    let record;
+    try {
+      record = JSON.parse(readFileSync(this.path(id), "utf8"));
+    } catch {
+      return undefined;
+    }
+    if (record?.v !== VERSION || record.id !== id || !Array.isArray(record.messages)) return undefined;
+    if (sessionFile !== undefined && record.sessionFile !== sessionFile) return undefined;
+    if (!current(record)) return undefined;
+    const session = record.session !== null && typeof record.session === "object" ? record.session : { id };
+    return { ...record, session: { ...session, updatedAt: Number(session.updatedAt) || record.file.mtimeMs } };
+  }
+
+  /** @param {string} id */
+  remove(id) {
+    try {
+      unlinkSync(this.path(id));
+    } catch {
+      // Never saved.
+    }
+  }
+
+  /**
+   * Drop transcripts whose session has been quiet longer than
+   * {@link RECENT_MS}, and those that can never be served again (their
+   * session file changed or is gone, or the record is unreadable).
+   */
+  prune(now = Date.now()) {
+    let names;
+    try {
+      names = readdirSync(this.dir);
+    } catch {
+      return 0;
+    }
+    let dropped = 0;
+    for (const name of names) {
+      const path = join(this.dir, name);
+      if (name.endsWith(".tmp")) {
+        try {
+          if (now - statSync(path).mtimeMs > TEMP_MAX_AGE_MS) unlinkSync(path);
+        } catch {
+          // Gone already.
+        }
+        continue;
+      }
+      if (!NAME.test(name)) continue;
+      let record;
+      try {
+        record = JSON.parse(readFileSync(path, "utf8"));
+      } catch {
+        record = undefined;
+      }
+      const activeAt = Number(record?.activeAt) || 0;
+      if (record?.v === VERSION && now - activeAt <= RECENT_MS && current(record)) continue;
+      try {
+        unlinkSync(path);
+        dropped += 1;
+      } catch {
+        // Gone already.
+      }
+    }
+    return dropped;
+  }
+}