agent-dag 1.48.0 → 3.1.0

package/src/server/cswap-admin.mjs

@@ -18,6 +18,7 @@
 // goes through one mutex.
 import { AsyncLocalStorage } from "node:async_hooks";
 import { existsSync } from "node:fs";
+import { brotliCompressSync, brotliDecompressSync, constants as zlibConstants } from "node:zlib";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -39,7 +40,46 @@ const CODE_VERDICT_MS = 60_000;
 export const SHARE_TTL_MS = 10 * 60_000;
 // How many accounts one bundle may carry. See shareAccounts.
 const MAX_SHARE_ACCOUNTS = 50;
-const SHARE_PREFIX = "ccdeck1:";
+
+/**
+ * The prefix a share is written with, and the one it used to be written with.
+ *
+ * `ccdeck1:` is base64 of the envelope JSON. `ccdeck2:` is base64 of the same
+ * JSON compressed, and the difference is not cosmetic — it was reported from
+ * the panel as "the text is very large", and on a real store it is:
+ *
+ *     1 account    2200 characters  ->  1024
+ *     3 accounts   6168 characters  ->  1816
+ *
+ * Because what a bundle mostly contains is not credentials. An account's two
+ * OAuth tokens are 216 characters between them; the envelope around them is
+ * two thousand, and every one of its key names — `refreshTokenExpiresAt`,
+ * `organizationRateLimitTier`, `claudeCodeTrialDurationDays` — repeats
+ * verbatim for every account added. That is exactly what a compressor is for,
+ * which is why the saving grows with the number of accounts rather than
+ * shrinking.
+ *
+ * Brotli rather than gzip: 10% smaller here, in node:zlib since v11, no
+ * dependency either way.
+ *
+ * BOTH prefixes are read, so a blob copied before this change still imports.
+ * Only `ccdeck2:` is written, which does mean a deck older than this cannot
+ * read a new share — it will say the text does not look like a shared account.
+ * That cost is paid once and it is smallest now: the feature shipped in
+ * 1.48.0 and the format has had no time to spread.
+ */
+const SHARE_PREFIX = "ccdeck2:";
+const SHARE_PREFIX_V1 = "ccdeck1:";
+
+/**
+ * The most an imported blob may decompress to.
+ *
+ * A few hundred bytes of brotli can name gigabytes of output, and this input
+ * arrives by paste from wherever the user found it. 50 accounts at ~1.6 KB of
+ * envelope each is under 100 KB, so 2 MB is twenty times the largest bundle
+ * this deck will ever produce and still nothing to allocate by accident.
+ */
+const SHARE_MAX_BYTES = 2 << 20;
 
 // ── serialization ────────────────────────────────────────────────────────────
 
@@ -724,16 +764,37 @@ async function restoreActive(num) {
  */
 export function wrapShare(payload, now = Date.now(), ttlMs = SHARE_TTL_MS) {
   const body = JSON.stringify({ v: 1, exp: now + ttlMs, payload });
-  return SHARE_PREFIX + Buffer.from(body, "utf8").toString("base64");
+  const packed = brotliCompressSync(Buffer.from(body, "utf8"), {
+    params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 11 },
+  });
+  return SHARE_PREFIX + packed.toString("base64");
 }
 
-/** The inverse. Returns `{ok:true, payload}` or `{ok:false, reason}`. */
+/**
+ * The inverse, for either prefix. Returns `{ok:true, payload}` or
+ * `{ok:false, reason}`.
+ *
+ * `v` inside the envelope is unchanged at 1 and deliberately so: it versions
+ * the SHAPE of the envelope, and that shape did not change. The prefix versions
+ * the encoding. Folding the two would have made an old blob unreadable for no
+ * reason, since its contents are exactly what this still expects.
+ */
 export function unwrapShare(blob, now = Date.now()) {
   const text = String(blob ?? "").trim();
-  if (!text.startsWith(SHARE_PREFIX)) return { ok: false, reason: "not_a_share" };
+  const v2 = text.startsWith(SHARE_PREFIX);
+  if (!v2 && !text.startsWith(SHARE_PREFIX_V1)) return { ok: false, reason: "not_a_share" };
   let env;
   try {
-    env = JSON.parse(Buffer.from(text.slice(SHARE_PREFIX.length), "base64").toString("utf8"));
+    // Sliced by the prefix that actually matched. The two are the same length
+    // today and writing it this way is what keeps that from being load-bearing.
+    const bytes = Buffer.from(text.slice((v2 ? SHARE_PREFIX : SHARE_PREFIX_V1).length), "base64");
+    // maxOutputLength is the whole reason a bounded decompress is safe to point
+    // at pasted text; without it a short blob can name an allocation that ends
+    // the process.
+    const body = v2
+      ? brotliDecompressSync(bytes, { maxOutputLength: SHARE_MAX_BYTES })
+      : bytes;
+    env = JSON.parse(body.toString("utf8"));
   } catch {
     return { ok: false, reason: "corrupt" };
   }

package/src/server/cswap-install.mjs

@@ -266,15 +266,50 @@ export function cswapOwner(bin, platform = process.platform, env = process.env,
 }
 
 let _bin = null;
+
+/**
+ * What the probe that resolved `_bin` printed, and when.
+ *
+ * #742: resolving the binary means running `cswap --version`, and reading the
+ * version means running `cswap --version`. Those were two separate spawns of a
+ * Python CLI a moment apart, and on this Mac each one costs between one and two
+ * and a half seconds — which made a probe of an ALREADY INSTALLED claude-swap
+ * the single largest thing in an ordinary boot.
+ *
+ * The second spawn is what this retires, and only the second: anything asking
+ * later gets a fresh answer, because a version read once at boot is not a
+ * version for the life of a deck that runs for days and may upgrade the tool
+ * underneath itself. Five seconds is long enough to cover cswapBin handing
+ * straight over to cswapVersion and far too short to be a cache.
+ */
+let _probe = null;
+const PROBE_FRESH_MS = 5_000;
+
+/** "claude-swap 0.25.0" → "0.25.0", and "installed" for a copy that answered
+ *  without a number in it. Shared so the memo and the spawn cannot disagree. */
+function versionIn(r) {
+  const m = (r.stdout || r.stderr).trim().match(/(\d+\.\d+\.\d+\S*)/);
+  return m ? m[1] : "installed";
+}
+
 export async function cswapBin() {
   // An explicit path wins over everything and is never cached away — someone
   // debugging a bad resolution needs it to take effect immediately.
   if (process.env.AGENTS_DECK_CSWAP) return process.env.AGENTS_DECK_CSWAP;
   if (_bin) return _bin;
-  if ((await run("cswap", ["--version"], { timeout: 8_000 })).ok) return (_bin = "cswap");
+
+  const take = (spelling, r) => {
+    _probe = { version: versionIn(r), at: Date.now() };
+    return (_bin = spelling);
+  };
+
+  const bare = await run("cswap", ["--version"], { timeout: 8_000 });
+  if (bare.ok) return take("cswap", bare);
 
   for (const c of cswapCandidates()) {
-    if (existsSync(c) && (await run(c, ["--version"], { timeout: 8_000 })).ok) return (_bin = c);
+    if (!existsSync(c)) continue;
+    const r = await run(c, ["--version"], { timeout: 8_000 });
+    if (r.ok) return take(c, r);
   }
   return "cswap";   // not found; leave the bare name so errors read sensibly
 }
@@ -299,15 +334,18 @@ export async function cswapBin() {
  * ensureCswap below, whose return value says nothing about which binary the
  * following twenty account operations will be sent to. See cswap-bin-memo.test.ts.
  */
-export function resetCswapBin() { _bin = null; }
+export function resetCswapBin() { _bin = null; _probe = null; }
 
 /** Installed version string, or null when cswap cannot be found. */
 export async function cswapVersion() {
-  const r = await run(await cswapBin(), ["--version"]);
+  const bin = await cswapBin();
+  // The call above may have just asked this very question — see _probe. Nothing
+  // is remembered past PROBE_FRESH_MS, so this is the second half of one
+  // lookup rather than a cache of the answer.
+  if (_probe && Date.now() - _probe.at < PROBE_FRESH_MS) return _probe.version;
+  const r = await run(bin, ["--version"]);
   if (!r.ok) return null;
-  // "claude-swap 0.25.0" → "0.25.0"
-  const m = (r.stdout || r.stderr).trim().match(/(\d+\.\d+\.\d+\S*)/);
-  return m ? m[1] : "installed";
+  return versionIn(r);
 }
 
 /**
@@ -536,8 +574,19 @@ async function findUpgrader(owner) {
  *
  * Returns a small status the CLI prints verbatim:
  *   { state: "present" | "installed" | "upgrading" | "skipped" | "unavailable", ... }
+ *
+ * `onInstalling` is called at most once, at the moment this stops asking
+ * questions and commits to an install — which is the moment the answer stops
+ * being seconds away and starts being minutes away. #742: the boot used to have
+ * no way to tell those two apart, so it waited out its whole deadline on a
+ * machine whose answer was already decided. Everything before that call is
+ * probes; everything after it is a uv download and an environment build.
+ *
+ * Deliberately a callback and not a state on the return value: what the caller
+ * needs is the news, not the outcome, and the outcome is the thing that takes
+ * three minutes to arrive.
  */
-export async function ensureCswap() {
+export async function ensureCswap({ onInstalling = null } = {}) {
   if (process.env.AGENTS_DECK_NO_INSTALL === "1") {
     const version = await cswapVersion();
     return version ? { state: "present", version } : { state: "skipped" };
@@ -565,6 +614,10 @@ export async function ensureCswap() {
     return { state: "present", version: existing };
   }
 
+  // Said before the install starts rather than after it, because after it is
+  // three minutes later and the whole point is not to be waited for.
+  try { onInstalling?.(); } catch { /* a caller's notification is not our problem */ }
+
   const result = await installCswap();
   if (!result.ok) return { state: "unavailable", ...result };
   // Something was just installed, so any path resolved before it is a guess made

package/src/server/index.mjs

@@ -5,12 +5,11 @@
 // describes. Nothing else in this file talks to anything but 127.0.0.1 clients.
 import { createServer, request as httpRequest } from "node:http";
 import { readFile, stat, mkdir, open, truncate, readdir, unlink } from "node:fs/promises";
-import { createReadStream, existsSync, readFileSync, realpath as realpathCb, realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpath as realpathCb, realpathSync } from "node:fs";
 import { extname, join, resolve, sep, dirname as pdirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname } from "node:path";
-import { createInterface } from "node:readline";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { promisify } from "node:util";
 import { claudeConfigDir } from "./claude-dir.mjs";
@@ -18,7 +17,8 @@ import { CODEX_HOME, CODEX_SESSIONS_DIR, STOP, walkRolloutDays } from "./codex-d
 import { PRODUCT } from "./brand.mjs";
 import { invokedName, renameNotice } from "./invoked-as.mjs";
 import { appendLogLine, codexCwdInWorkspace, electWriters, foldsCase, writesCodexLog } from "./log-writer.mjs";
-import { readProcesses, startSystemMetrics, systemSnapshot } from "./system-metrics.mjs";
+import { historySnapshot, readProcesses, startSystemMetrics, systemSnapshot } from "./system-metrics.mjs";
+import { linesFromEnd, linesFromStart } from "./log-tail.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, "..", "..");
@@ -3360,9 +3360,34 @@ function pushEvent(raw, source, opts = {}) {
  *   two replays.
  */
 export function replayScope(workspace, platform = process.platform) {
-  if (!workspace || typeof workspace !== "string") return () => true;
+  if (!workspace || typeof workspace !== "string") {
+    const all = () => true;
+    // Every caller gets the same answer for the same payload, forever. That is
+    // what lets replayLog read the log from its end — see `orderDependent` on
+    // the scoped predicate below for the half that cannot.
+    all.orderDependent = false;
+    return all;
+  }
   const bySession = new Map();
-  return function admits(payload) {
+  /**
+   * THE ANSWER DEPENDS ON WHAT CAME BEFORE, and #742 is why that is now stated
+   * out loud rather than left as an implementation detail.
+   *
+   * The synthetic enrichment events — ModelObserved, UsageObserved,
+   * SessionNamed, ContextObserved — carry a session_id and no cwd, so the only
+   * thing that can decide them is a cwd-bearing event for the same session,
+   * and that event is EARLIER in the log. Fed the log backwards, this predicate
+   * meets the enrichment first, has nothing in `bySession`, and drops it: the
+   * session lands on the canvas with no model and no tokens.
+   *
+   * So the flag is not advice. replayLog reads it, and reads the file forwards
+   * whenever it is set. Making a scoped replay cheap needs an index of where a
+   * workspace's lines are, which is a different change from this one.
+   */
+  admits.orderDependent = true;
+  return admits;
+
+  function admits(payload) {
     if (!payload || typeof payload !== "object") return false;
     if (payload.hook_event_name === "__clear") return true;
     const sid = typeof payload.session_id === "string" ? payload.session_id : null;
@@ -3408,38 +3433,92 @@ export function replayScope(workspace, platform = process.platform) {
  * declining a session it was told not to capture is the flag doing its job. They
  * are two different things and only the first is ever printed.
  *
- * WHAT THE FILTER COSTS AT BOOT, honestly: nothing is saved on the read. Every
- * line is still streamed off disk and still JSON.parsed, because the cwd being
- * judged is inside the JSON — a 30 MB log is 30 MB of reading and parsing on a
- * scoped deck exactly as on an unscoped one. What it saves is everything after
- * the parse: no redaction pass, no envelope, no ring insert, no character
- * accounting and no eviction pressure for a line this deck should never have
- * held. The ring is bounded by MAX_BUFFER events AND MAX_BUFFER_CHARS, so on a
- * busy machine the out-of-scope traffic was not merely extra — it was evicting
- * the in-scope sessions the user started the deck to watch.
+ * WHAT THE FILTER COSTS AT BOOT, honestly: nothing is saved on the read of any
+ * line this reaches, because the cwd being judged is inside the JSON. What it
+ * saves is everything after the parse: no redaction pass, no envelope, no ring
+ * insert, no character accounting and no eviction pressure for a line this deck
+ * should never have held. The ring is bounded by MAX_BUFFER events AND
+ * MAX_BUFFER_CHARS, so on a busy machine the out-of-scope traffic was not
+ * merely extra — it was evicting the in-scope sessions the user started the
+ * deck to watch.
+ *
+ * READ BACKWARDS, AND ONLY AS FAR AS THE RING (#742). This used to stream the
+ * whole file from the front, and the whole file is where the boot's time went:
+ * 12,079 lines and 31 MB on the machine it was measured on, 690ms of
+ * JSON.parse, growing with every session until rotation cuts it at 50 MB — to
+ * fill a ring that holds two thousand events. Five sixths of that parse was
+ * feeding the eviction loop, on the critical path of a boot, every time.
+ *
+ * So the lines arrive newest-first and the loop stops the moment the ring is
+ * full, which makes the cost a property of MAX_BUFFER rather than of how long
+ * the user has been running the deck. Nothing is lost by it: what a forward
+ * replay left in the ring was always the NEWEST admitted events that fit, and
+ * that is exactly the set this collects. A young log — too few events to fill
+ * the ring — is read to its start, and costs what it always did.
+ *
+ * The order of the pushes is still oldest-first. `seq` is assigned by pushEvent
+ * in the order it is called, and a ring numbered backwards would hand every
+ * resuming client a Last-Event-ID that means the opposite of what it says.
+ *
+ * A SCOPED DECK STILL READS FORWARDS, and that is not an oversight. Its
+ * predicate decides the cwd-less enrichment events — ModelObserved,
+ * UsageObserved, SessionNamed, ContextObserved — from the cwd-bearing event
+ * earlier in the log, so backwards it meets the answer after the question and
+ * drops them: the session arrives on the canvas with no model and no tokens.
+ * `replayScope` says which kind of predicate it handed over rather than this
+ * inferring it from the workspace string, so the two cannot drift apart. Making
+ * that case cheap needs an index of where a workspace's lines are, which is a
+ * different change from this one.
  */
 async function replayLog(filePath, workspace = "") {
   if (!existsSync(filePath)) return 0;
-  let count = 0;
   let skipped = 0;
   let skippedBytes = 0;
   const admits = replayScope(workspace);
-  const rl = createInterface({ input: createReadStream(filePath, { encoding: "utf8" }) });
-  for await (const line of rl) {
-    if (!line) continue;
+  const replay = (evt) =>
+    pushEvent(evt.payload, evt.source ?? "replay", { receivedAt: evt.receivedAt, replay: true });
+  const parse = (line) => {
     try {
-      const evt = JSON.parse(line);
-      if (evt && typeof evt === "object" && evt.payload) {
-        if (!admits(evt.payload)) continue;
-        pushEvent(evt.payload, evt.source ?? "replay", { receivedAt: evt.receivedAt, replay: true });
-        count++;
-      }
+      return JSON.parse(line);
     } catch {
       skipped++;
       skippedBytes += Buffer.byteLength(line, "utf8");
+      return null;
     }
+  };
+  const usable = (evt) => evt && typeof evt === "object" && evt.payload;
+
+  let count = 0;
+  if (admits.orderDependent) {
+    for await (const line of linesFromStart(filePath)) {
+      if (!line) continue;
+      const evt = parse(line);
+      if (!usable(evt) || !admits(evt.payload)) continue;
+      replay(evt);
+      count++;
+    }
+  } else {
+    // Newest first, so this is filled back to front and then walked in reverse
+    // to push. Bounded by MAX_BUFFER, which is what makes the memory here a
+    // property of the ring rather than of the file.
+    const newestFirst = [];
+    for await (const line of linesFromEnd(filePath)) {
+      if (!line) continue;
+      const evt = parse(line);
+      if (!usable(evt) || !admits(evt.payload)) continue;
+      newestFirst.push(evt);
+      // Everything older than this would be evicted by the events already held,
+      // so reading further is work whose only result is throwing it away.
+      if (newestFirst.length >= MAX_BUFFER) break;
+    }
+    for (let i = newestFirst.length - 1; i >= 0; i--) replay(newestFirst[i]);
+    count = newestFirst.length;
   }
   if (skipped > 0) {
+    // "in the part of the log it read", because that is now a part rather than
+    // the whole: a damaged line older than the ring is never reached, and
+    // claiming to have counted every unreadable line in the file would be a
+    // number this no longer has.
     const kb = (skippedBytes / 1024).toFixed(0);
     console.warn(`${PRODUCT}: skipped ${skipped} unreadable line(s) (${kb}KB) while replaying the event log`);
   }
@@ -5138,7 +5217,25 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     // On demand only — the process list costs a subprocess on every platform,
     // so it is fetched while the detail panel is open and never on the timer.
     if (req.method === "GET"  && url.pathname === "/api/system/processes") {
-      return guard(readProcesses().then(procs => send(res, 200, { ok: true, procs })), res);
+      // `total` is how many the machine is running, against the candidates
+      // actually sent. The modal says both, so a reader can see this is a
+      // selection rather than a task manager pretending to be complete.
+      return guard(readProcesses().then(r => send(res, 200, { ok: true, ...r })), res);
+    }
+    // A day of minute buckets, which is far too much to ride along on
+    // /api/system's three-second poll for a chart that is usually closed. Its
+    // own route, fetched only while a modal is open — the same arrangement the
+    // process list has for the same reason. One section per request, because
+    // four sections of a day would be four times too much again.
+    if (req.method === "GET"  && url.pathname === "/api/system/history") {
+      const group = url.searchParams.get("group") ?? "";
+      // An allowlist, not a pass-through: the parameter names a section of this
+      // panel and nothing else, so an unknown one is a 400 rather than an empty
+      // chart that looks like a machine with nothing to report.
+      if (!["thermal", "cores", "memory", "load"].includes(group)) {
+        return send(res, 400, { ok: false, error: "unknown_group" });
+      }
+      return send(res, 200, historySnapshot(group));
     }
     if (req.method === "GET"  && url.pathname === "/api/codex-quota") return guard(handleCodexQuota(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/ccusage")     return guard(handleCcusage(req, res), res);

package/src/server/log-tail.mjs

@@ -0,0 +1,139 @@
+// Reading a log backwards, because only its end is ever kept.
+//
+// #742. The event log is replayed before the port opens, and the replay parsed
+// every line in it from the beginning — 12,079 lines and 31 MB on the machine
+// this was measured on, 690ms of JSON.parse, growing with every session until
+// rotation cuts it at 50 MB. The ring it fills holds MAX_BUFFER = 2000 events.
+// So roughly five sixths of that work was parsing events that were evicted by
+// the ones parsed after them, on the critical path of a boot, every time.
+//
+// Reading from the end fixes the asymmetry rather than the constant: the loop
+// stops as soon as the ring is full, so the cost becomes a property of the ring
+// instead of a property of how long the user has been running the deck. When
+// the ring cannot be filled — a young log, or a workspace-scoped deck whose
+// events are a thin slice of a shared one — it reads all the way back to the
+// start and costs exactly what the forward read did. There is no case where
+// this is slower and no case where it sees less.
+//
+// Bytes, not characters. Lines are split on 0x0A and decoded one at a time,
+// which is safe in UTF-8 because no byte of a multi-byte sequence can be 0x0A —
+// a chunk boundary landing inside a three-byte character joins back together
+// before anything is decoded. Decoding the chunk first and splitting the string
+// is what would corrupt it, and it is the obvious way to write this.
+import { open } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+
+/** One line out of a buffer, minus the carriage return a CRLF file leaves on
+ *  the end of it. Sliced before decoding — see the note about 0x0A above. */
+function line(buf, from, to) {
+  const end = to > from && buf[to - 1] === 0x0D ? to - 1 : to;
+  return buf.subarray(from, end).toString("utf8");
+}
+
+/** How much is read at a time. One megabyte holds about 400 events at the size
+ *  this log's lines actually run to, so a full ring is usually five reads. */
+export const CHUNK_BYTES = 1 << 20;
+
+/**
+ * The file's lines, newest first, as an async iterable.
+ *
+ * Stops reading the moment the consumer stops asking — that is the whole point,
+ * and it is why this is a generator rather than a function returning an array.
+ * A `break` in the caller closes the handle through the generator's `finally`.
+ *
+ * Lines are yielded WITHOUT their newline, and the sequence is exactly the
+ * reverse of what `readline` yields reading the same file forwards — empty
+ * lines included, and a trailing newline at EOF is a line terminator rather
+ * than an empty line after it. A CRLF file reads the same as it does forwards,
+ * because the carriage return is stripped here too. That equivalence is the
+ * contract, and it is what the round-trip case in the test file checks against
+ * readline itself rather than against a hand-written expectation.
+ *
+ * The ONE difference: `readline` also breaks on a lone carriage return, for the
+ * sake of files written by software that predates OS X. Walking those backwards
+ * would mean scanning every byte of every chunk instead of asking Buffer for
+ * the next 0x0A, and nothing that writes a line into this deck's log has
+ * produced one since 2001. A file full of lone carriage returns reads here as a
+ * single very long line, which JSON.parse then declines — one skipped line,
+ * counted and reported, rather than a wrong answer.
+ */
+export async function* linesFromEnd(filePath, { chunkBytes = CHUNK_BYTES, openFile = open } = {}) {
+  const fh = await openFile(filePath, "r");
+  try {
+    const { size } = await fh.stat();
+    let pos = size;
+    // The bytes at the front of what has been read that have no newline before
+    // them yet: the first line of the chunk, which may continue into the chunk
+    // that comes before it. Carried, never yielded, until a newline turns up or
+    // the start of the file does.
+    let carry = Buffer.alloc(0);
+    // The newline that ends the last line is a terminator, not the start of an
+    // empty line after it. Trimmed once, on the chunk that holds EOF.
+    let atEof = true;
+
+    while (pos > 0) {
+      const len = Math.min(chunkBytes, pos);
+      pos -= len;
+      const buf = Buffer.alloc(len);
+      // Node reads short at the end of a file and at a pipe; a regular file
+      // opened for reading at a known offset does not, but the loop is written
+      // to survive it rather than to assume it.
+      let got = 0;
+      while (got < len) {
+        const { bytesRead } = await fh.read(buf, got, len - got, pos + got);
+        if (bytesRead === 0) break;
+        got += bytesRead;
+      }
+      const hay = carry.length ? Buffer.concat([buf.subarray(0, got), carry]) : buf.subarray(0, got);
+
+      // Walk the newlines from the end. `end` is one past the last byte of the
+      // line being cut; every cut is a complete line, because everything to its
+      // right has already been yielded.
+      let end = hay.length;
+      if (atEof && end > 0 && hay[end - 1] === 0x0A) end--;
+      atEof = false;
+      while (end > 0) {
+        const nl = hay.lastIndexOf(0x0A, end - 1);
+        if (nl === -1) break;
+        yield line(hay, nl + 1, end);
+        end = nl;
+      }
+      carry = hay.subarray(0, end);
+    }
+
+    // Whatever is left has the start of the file in front of it, so it is a
+    // whole line — and an EMPTY one is still a line, which is why this is not
+    // conditional on `carry.length`. A file that opens with a newline opens
+    // with an empty line, and reading it forwards says so.
+    if (size > 0) yield line(carry, 0, carry.length);
+  } finally {
+    await fh.close().catch(() => {});
+  }
+}
+
+/**
+ * The same file, the ordinary way round.
+ *
+ * Here rather than at the one call site so the two readers sit together and a
+ * reader of either finds the other: replayLog picks between them per boot, on
+ * whether its scope predicate can be fed a log backwards, and a pair of
+ * functions in one file is what makes that choice legible.
+ *
+ * Streams, so a scoped deck on a 50 MB log holds one line at a time exactly as
+ * it did before any of this.
+ */
+export async function* linesFromStart(filePath) {
+  const input = createReadStream(filePath, { encoding: "utf8" });
+  const rl = createInterface({ input });
+  try {
+    for await (const line of rl) yield line;
+  } finally {
+    // Both, and the stream second. `rl.close()` stops the interface and leaves
+    // the descriptor under it open, which is fine for the one caller here
+    // because it reads to the end — and is a leak the day somebody breaks out
+    // of this loop the way the backwards reader is designed to be broken out of.
+    rl.close();
+    input.destroy();
+  }
+}