ccdeck 3.29.11 → 3.31.0

package/src/server/load-average.mjs

@@ -0,0 +1,32 @@
+// The load average, and the one rule for when it is a reading at all.
+//
+// Two things in system-metrics.mjs ask for it: the `load:1m` series the sampler
+// records on every CPU tick, and the `loadavg` that /api/system answers. Each
+// used to carry its own copy of the platform test and its own copy of the
+// comment defending it, the second pointing at the first. #1028 was a bug in
+// BOTH copies at once — the same extra clause on each — so this file is the rule
+// spelled once, with both callers asking it.
+import os from "node:os";
+
+/**
+ * The one-, five- and fifteen-minute load averages, to two places, or null on a
+ * platform that publishes none.
+ *
+ * `os.loadavg()` reads a kernel value — no syscall worth the name — which is why
+ * the sampler can afford it on every CPU tick. Windows returns [0,0,0], which is
+ * not a reading and is not reported as one.
+ *
+ * THE PLATFORM TEST IS THE WHOLE TEST. It used to be joined by
+ * `load.some(n => n > 0)`, which reads as belt and braces and is not: Node
+ * documents `os.loadavg()` as always [0,0,0] on Windows, so the platform test
+ * alone already excludes every non-reading — and the extra clause could only
+ * ever reject a reading that was REAL. `/proc/loadavg` on a genuinely quiet
+ * Linux box says `0.00 0.00 0.00`, so "Queued work" recorded no points at all
+ * for every quiet minute, and after the machine woke the chart read as though
+ * the deck had been switched off through them. And MachinePanel gates the whole
+ * section on `{loadavg && …}`, so an idle Linux box had the section disappear
+ * from under it (#1028).
+ */
+export function loadReading(platform = process.platform, load = os.loadavg()) {
+  return platform !== "win32" ? load.map(n => Math.round(n * 100) / 100) : null;
+}

package/src/server/log-election.mjs

@@ -0,0 +1,235 @@
+// Which of the running decks writes an event to the log they share?
+//
+// The hook already answers that for the events it delivers: it groups the decks
+// it is about to post to by the log file each one names in its discovery record,
+// elects one per file, and marks the request to every other one `?persist=0`.
+// See electWriters in hook/hook.js.
+//
+// The Codex rollout watcher never goes through the hook — it builds its events
+// inside the server by tailing ~/.codex/sessions/**/rollout-*.jsonl — so nothing
+// suppressed the copies on that path: every deck tailing the same rollout
+// appended its own line to the one events.jsonl they all default to, so each
+// Codex tool call, prompt and session start landed there once per running deck.
+// That is the duplication the hook election was added to end, still open on the
+// path that is the only Codex capture there is on Windows, where Codex hooks
+// never fire at all.
+//
+// So the server runs the same election, over the same discovery records, with
+// the same tie-break. The rule is repeated here rather than imported from
+// hook/hook.js because that file is copied out of the package and run standalone
+// by the host CLI, with no path back to the module it came from — the same
+// reason it re-derives the Claude config dir inline. The two copies are pinned
+// equal by a test, as challengeProof's pair already is.
+//
+// These lived at the top of log-writer.mjs, above the appender they decide
+// for. They are pure rules over discovery records and paths and the appender
+// never called one, so they moved on their own: event-log.mjs asks the
+// election who owns the log, the rollout watcher and the boot replay ask it
+// whose rollout a cwd is, and discovery.mjs and the launcher spell the log's
+// path through it. The bodies are unchanged.
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve, win32, posix } from "node:path";
+
+/**
+ * The one spelling of an events log, so two decks pointed at one file land in
+ * one group (#793).
+ *
+ * `resolve` alone was what shipped, and it settles relative-vs-absolute and
+ * nothing else. The election below then only case-folds — so two spellings of
+ * one file read as two files, which is the exact thing `bin/deck.js`'s comment
+ * over this value says must not happen. On Windows it needs no odd user action:
+ * `claudeConfigDir()` derives from `homedir()`, and a shell whose `USERPROFILE`
+ * is 8.3-shortened yields a different default string than one with the long
+ * form. `subst` and mapped drives and junctions do it too, and on macOS so does
+ * `/tmp` against `/private/tmp`.
+ *
+ * What it cost was not merely a duplicate group. BOTH decks were then elected,
+ * so every hook event was appended twice — the duplicate-tools-after-restart
+ * symptom the election exists to end — and `logSharing()` compares the same
+ * string, so both answered `mine: true` and `POST /api/clear` truncated a file
+ * this deck does not own. That is the #698 history loss the ownership gate was
+ * added to prevent.
+ *
+ * THE DIRECTORY IS CANONICALISED EVEN WHEN THE FILE IS NOT THERE, which is the
+ * half a plain realpath misses. On a first run, or against a `--history` naming
+ * a file the deck will create, `realpath` throws ENOENT — and falling back to
+ * the resolved string would leave the two spellings different for exactly the
+ * run that creates the file. The parent exists (or is about to be created under
+ * one canonical name), so it is canonicalised and the basename rejoined.
+ *
+ * `canonicalWorkspace` in canonical-path.mjs is the same rule for the other
+ * path this deck publishes, with three comments naming 8.3 expansion as its
+ * reason. This is that rule reaching the value two lines away from it.
+ */
+export function canonicalLogPath(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return "";
+  const abs = resolve(raw);
+  try { return realpathSync.native(abs); } catch { /* not created yet */ }
+  try { return join(realpathSync.native(dirname(abs)), basename(abs)); } catch { return abs; }
+}
+
+/**
+ * Does this platform's filesystem treat two spellings that differ only in case
+ * as the same file? The platform is a parameter so both answers can be checked
+ * from either kind of machine.
+ *
+ * Windows always does, and macOS does by default (APFS and HFS+ are formatted
+ * case-insensitive unless the user deliberately chose otherwise). Linux does
+ * not, and folding case there would be a bug of its own: /srv/a/events.jsonl and
+ * /srv/A/events.jsonl are two real files, each of which needs a writer.
+ */
+export const foldsCase = (platform = process.platform) =>
+  platform === "win32" || platform === "darwin";
+
+/**
+ * Of these decks, which ones write to disk? Returns the subset that should;
+ * every other one is expected to draw the event and keep no record of it.
+ *
+ * Decks are grouped by the log file each one names in its discovery record and
+ * one deck per group is elected. Grouping by the file rather than counting decks
+ * is what keeps the overrides honest: a deck run with `--history` sits alone in
+ * its own group and always writes, a deck run with `--no-persist` reports no
+ * file and can never be elected to write for one that does, and a deck too old
+ * to report either keeps the behaviour it had before this rule existed. Within a
+ * group the lowest port wins — a fixed rule, so the same deck holds the file for
+ * as long as it is up and the next one inherits it as soon as that deck is gone.
+ *
+ * Kept byte-for-byte equivalent to electWriters in hook/hook.js: the two decide
+ * for the same decks over the same records, and a disagreement between them
+ * means one log line written twice or none at all.
+ */
+export function electWriters(decks, platform = process.platform) {
+  const byLog = new Map();
+  for (const d of decks) {
+    const log = typeof d.persist === "string" ? d.persist : "";
+    // Two namespaces, so a deck with no log to share — and a deck too old to
+    // report one — is alone in its group and cannot collide with a real path.
+    const key = log
+      ? `log:${foldsCase(platform) ? log.toLowerCase() : log}`
+      : `deck:${d.pid}:${d.port}`;
+    const held = byLog.get(key);
+    // Ports are unique among live decks; pid only breaks a tie a stale
+    // discovery file could invent, so the answer stays deterministic.
+    if (!held || d.port < held.port || (d.port === held.port && d.pid < held.pid)) {
+      byLog.set(key, d);
+    }
+  }
+  return new Set(byLog.values());
+}
+
+/**
+ * Would a deck scoped to `workspace` capture a rollout running in `cwd`? An
+ * empty workspace is unscoped and captures every session; a rollout that never
+ * said where it runs is inside no workspace, so only an unscoped deck draws it.
+ *
+ * This answers two questions with one function — whether THIS deck tails a
+ * rollout, and whether another deck tails it too — and that is only sound while
+ * the rule below is the rule every deck actually runs. Model another deck's
+ * capture with anything else and the election covers the wrong set: a deck that
+ * writes without being elected, or an elected deck that never opened the file.
+ *
+ * It is also the rule hook/hook.js runs for the sessions it delivers, under the
+ * name capturesSession — that script is copied out of the package and run
+ * standalone, so the two are written twice and pinned equal by a test walking
+ * one table of paths through both. They were not equal: case was folded here on
+ * every platform, so on Linux a deck scoped to /srv/proj captured Codex sessions
+ * from /srv/Proj and Claude sessions from neither. Those are two real
+ * directories there, and the hook's own comment says what folding them together
+ * costs — a deck handed the events of a tree it was not scoped to. So the fold
+ * is per-platform on both sides now, and `--workspace` means one thing.
+ *
+ * (The narrow window that opens: two decks on Linux whose workspaces differ only
+ * in case, one of them old enough to still fold, both containing one rollout's
+ * cwd. Each models the other as tailing the file; one of them is wrong, and the
+ * cost is a single log line written twice.)
+ *
+ * The platform is a parameter, following the hook's cwdInWorkspace and
+ * spawnSpec in src/server/exec.mjs, so the Windows separator is testable from a
+ * POSIX machine.
+ */
+export function codexCwdInWorkspace(cwd, workspace, platform = process.platform) {
+  if (!workspace || typeof workspace !== "string") return true;
+  if (!cwd || typeof cwd !== "string") return false;
+  const p = platform === "win32" ? win32 : posix;
+  const fold = s => (foldsCase(platform) ? s.toLowerCase() : s);
+  const a = fold(p.resolve(cwd));
+  const b = fold(p.resolve(workspace));
+  if (a === b) return true;
+  // A root ("C:\", "/") already ends in the separator; appending a second one
+  // would match nothing.
+  return a.startsWith(b.endsWith(p.sep) ? b : b + p.sep);
+}
+
+/**
+ * Do two discovery records name the same Codex tree? Each argument is a
+ * record's `codexHome`: the canonical path of the CODEX_HOME that deck tails.
+ *
+ * Anything that is not a non-empty string answers yes. That is a record written
+ * before the field existed — a machine halfway through an upgrade is the
+ * ordinary way to meet one — and guessing "a different tree" there would elect
+ * a second writer for one log on every machine with an older deck still up.
+ * Guessing "the same tree" is what every deck did before the field existed,
+ * which is the fail-safe writesCodexLog below already takes for a record too old
+ * to carry `codex` at all.
+ *
+ * Case is folded where the filesystem folds it, exactly as electWriters folds
+ * the log path: on Windows and macOS two spellings that differ only in case are
+ * one directory with one reader, and on Linux they are two directories, each
+ * read by its own deck. The other ways to spell one directory — a symlinked
+ * ~/.codex, an 8.3-shortened USERPROFILE, /tmp against /private/tmp — are
+ * settled before the value is published (writeDiscovery in discovery.mjs runs
+ * it through canonicalLogPath), so two records compared here already agree on
+ * everything but case.
+ */
+export function sameCodexTree(a, b, platform = process.platform) {
+  if (typeof a !== "string" || a === "" || typeof b !== "string" || b === "") return true;
+  return foldsCase(platform) ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+/**
+ * Does this deck append a rollout's events to its log, or is another deck doing
+ * it? `decks` is every deck registered right now, `pid` identifies this one
+ * among them, and `cwd` is the workspace the rollout is running in.
+ *
+ * The group is every deck that tails this same rollout: each deck decides for
+ * itself, so all of them whose workspace contains the cwd read the file and all
+ * of them would write it. The hook builds the same group the same way for the
+ * events it delivers — it used to narrow them to the longest workspace match
+ * first, which is the asymmetry the predicate above describes the end of. A deck
+ * started with `--no-codex` tails nothing and is left out; electing it would
+ * mean the rollout's events reach no log at all. A deck too old to say either
+ * way is assumed to be tailing, which is what it was doing before this field
+ * existed.
+ *
+ * A deck reading a different Codex tree is left out for the same reason (#982).
+ * CODEX_HOME moves the whole tree, so two decks on one machine can share one
+ * events.jsonl while reading two different sets of rollouts — and for an
+ * unscoped deck the workspace test above answers yes to every cwd, so it tells
+ * them apart not at all. The record's `codex: true` said a deck tails rollouts
+ * and never said whose. So the lower-port deck won the line for a rollout its
+ * own tree does not hold and appended nothing, the deck that was reading it
+ * stood down, and the shared log recorded none of the session while the canvas
+ * drew all of it: #695's symptom, from a deck that is alive, answers its
+ * challenge, and is simply looking somewhere else. The same deck launched with
+ * a stale CODEX_HOME is the duller version of it.
+ */
+export function writesCodexLog({ decks, pid, cwd, platform = process.platform }) {
+  const live = Array.isArray(decks) ? decks : [];
+  const self = live.find(d => d && d.pid === pid) ?? null;
+  // No record of our own on disk — the window before the first heartbeat writes
+  // it, or a deck that cannot write one at all. Nobody can elect us and we
+  // cannot see who else is here, so keep what this deck did before the election
+  // existed and write. A line written twice is recoverable; a deck that quietly
+  // stops recording anything is not.
+  if (!self || typeof self.persist !== "string" || self.persist === "") return true;
+
+  const group = [self];
+  for (const d of live) {
+    if (!d || d.pid === self.pid) continue;
+    if (d.codex === false) continue;
+    if (!sameCodexTree(self.codexHome, d.codexHome, platform)) continue;
+    if (!codexCwdInWorkspace(cwd, d.workspace ?? "", platform)) continue;
+    group.push(d);
+  }
+  return electWriters(group, platform).has(self);
+}

package/src/server/log-replay.mjs

@@ -0,0 +1,374 @@
+// The boot replay: what a starting deck reads back out of its log, and which of
+// those events belong on this deck's canvas.
+//
+// These lived in src/server/index.mjs, after pushEvent. They push through
+// event-sink.mjs as every other emitter outside index.mjs does, size their
+// read against the ring's own two bounds (ring-bounds.mjs), and judge scope by
+// the same predicate the Codex watcher runs (log-election.mjs) — nothing here
+// reads the ring. startServer calls replayLog once, with the log openEventLog
+// resolved. The bodies are unchanged.
+import { existsSync } from "node:fs";
+import { PRODUCT } from "./brand.mjs";
+import { codexCwdInWorkspace } from "./log-election.mjs";
+import { linesFromEnd, linesFromStart } from "./log-tail.mjs";
+import { ENVELOPE_CHARS, MAX_BUFFER, MAX_BUFFER_CHARS, payloadChars } from "./ring-bounds.mjs";
+// event-pipeline.mjs's pushEvent, reached without importing it — see
+// event-sink.mjs.
+import { pushEvent } from "./event-sink.mjs";
+
+/**
+ * Which of the log's events belong on THIS deck's canvas — the boot replay's
+ * half of `--workspace`, and the half that did not exist (#696).
+ *
+ * `--workspace` filtered the two LIVE capture paths and nothing else. The log is
+ * the machine-wide `<claude config dir>/agent-dag/events.jsonl` that every deck
+ * on the box shares by default, and `replayLog` pushed all of it, so a deck
+ * started with `--workspace ~/proj` came up with every session on the machine
+ * already drawn — including the ones it had just printed it would not capture,
+ * contradicting its own `workspace` row, README.md and the empty-state sentence
+ * in src/web/scope.ts that exists precisely so the canvas stops asserting things
+ * that are not true (#404).
+ *
+ * THE RULE IS NOT A NEW ONE. Per event it is `codexCwdInWorkspace`, the same
+ * predicate the Codex watcher runs and the twin of `capturesSession` in
+ * hook/hook.js — the two are pinned equal by a test walking one table of paths
+ * through both, so `--workspace` means one thing on every path a payload can
+ * reach the ring by, including this one. Nothing about case folding, separators
+ * or the sibling-prefix trap (`/srv/projX` is not inside `/srv/proj`) is decided
+ * here; it is decided there, once, per platform.
+ *
+ * WHAT THE MAP IS FOR. Not every line carries a cwd. The synthetic enrichment
+ * events the transcript scanners emit — `ModelObserved`, `UsageObserved`,
+ * `SessionNamed`, `ContextObserved` — carry `session_id` and nothing else, and
+ * they are persisted like any other event. Judging those by the live rule alone
+ * (no cwd, so inside no workspace) would keep an in-scope session on the canvas
+ * while stripping its model, its token columns and its name until the next live
+ * event arrived. So the answer for a session is learned from the events that DO
+ * say where they run and carried forward to the ones that do not.
+ *
+ * That is a reconstruction of the live behaviour rather than a second notion of
+ * scope: live, a deck only ever emits `ModelObserved` for a session whose hook
+ * event it already accepted, so "follows its session" is what those events
+ * already do — the map only re-derives it from a file. It costs one entry per
+ * distinct session id in the log (a few thousand at the very most, against a log
+ * measured in tens of megabytes) and one lookup per line.
+ *
+ * TWO CASES DECIDED EXPLICITLY:
+ *
+ *   * `__clear` — the control marker `/api/clear` pushes, with `cwd: ""`. It is
+ *     not a session event; it is the instruction that makes the reducer forget
+ *     everything before it. It has not been written to the log since #698, but
+ *     logs the decks before that wrote still carry it, and dropping it on a
+ *     scoped deck would replay the state a user had explicitly cleared, so it
+ *     is always admitted.
+ *   * a payload with no cwd and no session the map has seen — refused on a
+ *     scoped deck, which is exactly what `capturesSession` decides live for a
+ *     session that never said where it runs.
+ *
+ * An unscoped deck (`workspace === ""`, the default) admits everything, and
+ * takes the cheapest possible path to saying so.
+ *
+ * @param {string} workspace this deck's canonical workspace; "" for machine-wide
+ * @returns {(payload: unknown) => boolean} called once per replayed envelope, in
+ *   log order — it remembers, so the order matters and it is not reusable across
+ *   two replays.
+ */
+export function replayScope(workspace, platform = process.platform, providers = null) {
+  // WHICH CLIS THIS DECK IS WATCHING, and the half of `--no-codex` that did not
+  // exist (#1004). Live capture is gated on the provider — `if (codex)
+  // startCodexWatcher(...)`, and the Claude hook is only installed when
+  // `deckProviders().claude` — and the boot replay was not, so a deck started
+  // with `--no-codex` printed
+  //
+  //     Codex sessions   skipped — no ~/.codex/, or --no-codex
+  //
+  // and then filled its canvas with Codex sessions out of the machine-wide
+  // events.jsonl, frozen mid-turn, which no live path could ever close because
+  // the watcher that would have is the one that was skipped. Measured on a log
+  // of two Claude lines and two Codex lines replayed with `codex: false`:
+  //
+  //     in the ring: [ 'claude:claude-1:SessionStart', 'claude:claude-1:PreToolUse',
+  //                    'codex:codex-1:SessionStart',  'codex:codex-1:PreToolUse' ]
+  //
+  // The mirror case is worse: a `--no-claude` deck replays Claude sessions while
+  // `providers.claude` is false, so App.tsx hides the accounts panel and the
+  // sound controls — sessions on screen the deck has deliberately taken the
+  // controls for away.
+  //
+  // It costs one comparison per line. `provider: "codex"` is stamped on every
+  // payload the Codex watcher emits, its cwd-less enrichment included, and the
+  // Claude side is the complement — which is what types.ts already says
+  // `provider` means ("defaults to claude for replay events written before
+  // multi-provider support"). So this needs no per-session memory of its own and
+  // leaves `orderDependent` alone.
+  const claudeOn = providers?.claude !== false;
+  const codexOn = providers?.codex !== false;
+  const scoped = !!workspace && typeof workspace === "string";
+  if (!scoped && claudeOn && codexOn) {
+    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();
+  /**
+   * 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 = scoped;
+  return admits;
+
+  function admits(payload) {
+    if (!payload || typeof payload !== "object") return false;
+    if (payload.hook_event_name === "__clear") return true;
+    // The provider gate, ahead of the workspace one and exempting `__clear` for
+    // the same reason it does: the marker carries no provider, and a deck that
+    // dropped it would replay a canvas the user had explicitly cleared.
+    if (!(payload.provider === "codex" ? codexOn : claudeOn)) return false;
+    if (!scoped) return true;
+    const sid = typeof payload.session_id === "string" ? payload.session_id : null;
+    const cwd = typeof payload.cwd === "string" && payload.cwd !== "" ? payload.cwd : null;
+    if (cwd) {
+      const inside = codexCwdInWorkspace(cwd, workspace, platform);
+      if (sid) bySession.set(sid, inside);
+      return inside;
+    }
+    if (sid && bySession.has(sid)) return bySession.get(sid);
+    return false;
+  };
+}
+
+/**
+ * Can this log fill the ring on its own?
+ *
+ * Read from the END and bounded by the ring, so the answer costs at most one
+ * ring's worth of parsing however large the file is — and on a full log it
+ * stops within the first few hundred lines. Deliberately UNSCOPED: the number
+ * it returns is an upper bound on what any workspace predicate will admit, so
+ * `false` is a certainty that the archive is needed while `true` is only the
+ * absence of evidence that it is. See the order-dependent branch of replayLog
+ * for why that asymmetry is the right way round.
+ */
+async function fillsRing(filePath, maxEvents, maxChars) {
+  let n = 0;
+  let chars = 0;
+  for await (const line of linesFromEnd(filePath)) {
+    if (!line) continue;
+    let evt;
+    try { evt = JSON.parse(line); } catch { continue; }
+    if (!evt || typeof evt !== "object" || !evt.payload) continue;
+    n++;
+    chars += ENVELOPE_CHARS + payloadChars(evt.payload);
+    if (n >= maxEvents || chars >= maxChars) return true;
+  }
+  return false;
+}
+
+/**
+ * Read the log back into the ring buffer at boot.
+ *
+ * A line that will not parse is skipped rather than thrown on, and that is
+ * deliberate — it is what lets a log damaged by the pre-#446 writer still
+ * replay. Every line before the damage and every line after it is whole, so
+ * stopping at the first bad one would throw away the rest of the session for a
+ * fault that costs one event. Newline framing is what makes the recovery
+ * possible: a torn write leaves the reader resynchronised at the very next
+ * `\n`, with no length prefix to have been lost along with the bytes.
+ *
+ * What changed is that the skip is no longer silent. Before, a deck whose log
+ * had been shredded replayed "mostly" and said nothing anywhere: the largest
+ * tool responses and whatever ordinary event was spliced into them were gone,
+ * with no counter and no line on the terminal. The count below is the only
+ * signal that a log carries damage from a writer that has since been fixed, and
+ * the byte total is what tells the user whether it was one truncated tail from
+ * a kill -9 or a megabyte of shredded tool output.
+ *
+ * Deliberately one line, and deliberately without the path in it: this prints
+ * onto a terminal the deck is about to paint over (see oneLine in term.mjs for
+ * what a multi-line message does there), and the path was already printed at
+ * boot by the caller.
+ *
+ * `workspace` is what makes the replay agree with the two live capture paths —
+ * see replayScope. An out-of-scope line is NOT counted into `skipped` and is not
+ * warned about: `skipped` means "this log has bytes in it no reader can parse",
+ * which is damage and is worth a line on the terminal, while a scoped deck
+ * 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 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.
+ */
+/* Exported for the suite, with both ceilings as parameters. The byte budget is
+ * 128 MiB, so a test that wanted to reach it honestly would have to write 128
+ * MiB — which is why the count bound was the only one anything pinned, and why
+ * the byte bound was the one that broke. Production passes neither argument. */
+export async function replayLog(filePath, workspace = "", {
+  maxEvents = MAX_BUFFER, maxChars = MAX_BUFFER_CHARS, providers = null,
+} = {}) {
+  // THE ARCHIVE IS PART OF THE HISTORY, and for two years nothing read it.
+  // `maybeRotatePersistFile` renames events.jsonl to events.jsonl.1 at 50 MB;
+  // a grep for `.1` across src/ and bin/ finds the write, the copy deck-home's
+  // migration makes, and two comments. replayLog is called once, with
+  // `persistPath` alone. So the boot immediately after a rotation replays a
+  // file holding a handful of lines while 50 MB of history sits beside it
+  // unread — and the next rotation's `unlink` deletes it outright. Measured:
+  // one rotation, then `replayLog(events.jsonl)` returning 1.
+  //
+  // The reader below already stops the moment EITHER of the ring's bounds is
+  // reached, so on a log that can fill the ring on its own this costs nothing
+  // at all: the archive is never opened. It is read only when the live log
+  // cannot fill the ring, which is exactly the window a rotation opens.
+  //
+  // A Clear opens the same window and means the opposite by it. It empties the
+  // live log, which can then fill nothing, so reading on into the archive put
+  // back precisely what the user had cleared (#1130) — which is why a Clear
+  // removes the archive as well as emptying the live log, rather than this
+  // learning to tell the two kinds of empty apart. See handleClear.
+  const archivePath = filePath + ".1";
+  const liveThere = existsSync(filePath);
+  const archiveThere = existsSync(archivePath);
+  if (!liveThere && !archiveThere) return 0;
+  let skipped = 0;
+  let skippedBytes = 0;
+  // `providers` is the second scope this deck has, and it goes the same way the
+  // first one does — into the predicate, so the replay rule stays pinned equal
+  // to the live rule rather than being a second notion of it. See replayScope.
+  const admits = replayScope(workspace, process.platform, providers);
+  const replay = (evt) =>
+    pushEvent(evt.payload, evt.source ?? "replay", { receivedAt: evt.receivedAt, replay: true });
+  const parse = (line) => {
+    try {
+      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) {
+    // Oldest first, so the archive comes BEFORE the live log — `admits` is
+    // stateful and answers from what it has already seen, which is the whole
+    // reason this branch reads forwards at all.
+    //
+    // Whether the archive is worth reading is decided by a probe rather than by
+    // this branch's own reader, because this branch has no stopping rule: it
+    // pushes everything and lets the ring evict. The probe reads the LIVE log
+    // backwards, unscoped, and is bounded by the ring, so it costs at most one
+    // ring's worth of parsing from the end of the file and nothing more. An
+    // unscoped count is an upper bound on what scoping will admit, so "this
+    // cannot fill the ring" is certain when the probe says so — and when it
+    // says the opposite a scoped deck may still under-fill, which is precisely
+    // what it does today. Nothing regresses; the case a rotation creates, where
+    // the live log holds a handful of lines, is the one that is fixed.
+    const files = [];
+    if (archiveThere && !(liveThere && await fillsRing(filePath, maxEvents, maxChars))) files.push(archivePath);
+    if (liveThere) files.push(filePath);
+    for (const file of files) {
+      for await (const line of linesFromStart(file)) {
+        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 BOTH of the ring's limits, which is what makes the
+    // memory here a property of the ring rather than of the file.
+    //
+    // The count alone was not enough, and the comment that used to say it was
+    // predates #625. Eviction is the only thing that applies MAX_BUFFER_CHARS,
+    // and eviction happens inside pushEvent — which does not run until this
+    // array is already full. Measured on a 187 MB log of 40 events of 4.9M
+    // characters each, every one of them under the ingest cap: RSS went from
+    // 215 MB to a peak of 505 MB, and the ring that survived held 27 events and
+    // 126 MiB. About 290 MB staged for a ring capped at 128.
+    //
+    // Rotation at 50 MB normally keeps logs well under this, but rotation is
+    // best-effort and its failure is only logged, and the rotation's own note
+    // in event-log.mjs records logs reaching gigabytes.
+    const newestFirst = [];
+    let stagedChars = 0;
+    // Newest generation first. The second pass runs only if the first stopped
+    // because it ran out of FILE rather than because it reached a bound, which
+    // is the "cannot fill the ring" test stated exactly and for free — and it
+    // is also why a full live log never opens the archive at all.
+    for (const file of liveThere ? [filePath, archivePath] : [archivePath]) {
+      if (!existsSync(file)) continue;
+      if (newestFirst.length >= maxEvents || stagedChars >= maxChars) break;
+      for await (const line of linesFromEnd(file)) {
+        if (!line) continue;
+        const evt = parse(line);
+        if (!usable(evt) || !admits(evt.payload)) continue;
+        newestFirst.push(evt);
+        stagedChars += ENVELOPE_CHARS + payloadChars(evt.payload);
+        // Everything older than this would be evicted by the events already held,
+        // so reading further is work whose only result is throwing it away.
+        // Either limit reaching its ceiling means exactly that.
+        if (newestFirst.length >= maxEvents || stagedChars >= maxChars) 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`);
+  }
+  return count;
+}