agent-dag 1.44.1 → 1.45.0

package/src/server/index.mjs

@@ -1,19 +1,23 @@
 // agent-dag server: HTTP ingest + SSE broadcast + static file serving.
 // Single-file pure Node HTTP server, zero deps.
-import { createServer } from "node:http";
+// `request` is the client half, and it has exactly one caller: challengeDeck,
+// which asks another deck's port to prove it is the deck its discovery record
+// 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, realpathSync } from "node:fs";
+import { createReadStream, 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 { extname, join, resolve, dirname as pdirname } from "node:path";
 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";
 import { CODEX_HOME, CODEX_SESSIONS_DIR, STOP, walkRolloutDays } from "./codex-dir.mjs";
 import { PRODUCT } from "./brand.mjs";
 import { invokedName, renameNotice } from "./invoked-as.mjs";
-import { appendLogLine, codexCwdInWorkspace, writesCodexLog } from "./log-writer.mjs";
+import { appendLogLine, codexCwdInWorkspace, electWriters, foldsCase, writesCodexLog } from "./log-writer.mjs";
 import { readProcesses, startSystemMetrics, systemSnapshot } from "./system-metrics.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -41,8 +45,221 @@ const MIME = {
   ".map":  "application/json",
 };
 
-const MAX_BUFFER = 2000;            // recent events kept for late SSE subscribers
+// ─── The event ring buffer, and the two bounds it keeps ───────────────────
+// MAX_BUFFER is how many events a late SSE subscriber can be replayed.
+// MAX_BUFFER_CHARS is how much they are allowed to weigh, and until #625 there
+// was no such thing — which is the whole defect, because a count is not a bound
+// on memory when the thing being counted has no size of its own. `POST
+// /api/event` admits a body of 5,000,000 characters and nothing between that
+// door and this array shrinks it: hook/hook.js forwards the payload whole, and
+// log-writer.mjs already says in as many words that a PostToolUse carrying a
+// large Read or Bash response is routinely a good fraction of that. So the real
+// ceiling was MAX_BUFFER multiplied by the largest event ingest accepts.
+//
+// Measured on Node 22.14 / macOS, posting 4,900,000-character bodies to a real
+// server on loopback and reading process.memoryUsage() after a forced GC:
+//
+//   after  20 events: heapUsed  107MB rss  292MB   per-event 4.94MB
+//   after 100 events: heapUsed  481MB rss  739MB   per-event 4.73MB
+//   after 200 events: heapUsed  947MB rss 1231MB   per-event 4.69MB
+//
+// 4.69 MB retained per buffered event, flat as the ring fills. A full ring of
+// 2000 of those is 9.4 GB against the 4144 MB heap limit V8 picks on a 32 GB
+// machine, so the count cap was not reachable on any developer machine — and
+// what happened instead of reaching it was not degradation. The same harness
+// under `--max-old-space-size=2048`, roughly the heap an 8 GB laptop gives
+// itself:
+//
+//   after 420 events: heapUsed 1975MB rss 2247MB
+//   FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
+//
+// 429 events in, 1571 short of the cap. That abort is not catchable, so the SSE
+// stream, the hook ingest and the log all stop together — and `/api/event` is a
+// deliberate OPEN_MUTATION, so about 430 posts from a local process holding no
+// credential at all end the deck. The comment at OPEN_MUTATIONS says the worst
+// a caller does with that route is draw a session that is not there; this is
+// the sentence that made it false.
+//
+// Both bounds are now enforced on every push, evicting oldest-first until each
+// holds. See the eviction in pushEvent for why it is one splice and why the
+// newest event is never the one evicted.
+export const MAX_BUFFER = 2000;     // recent events kept for late SSE subscribers
+
+// The byte budget, counted in CHARACTERS — the unit this file already measures
+// payloads in, and the unit MAX_CLIENT_BUFFER_BYTES is really written in
+// despite its name (there is a long note there about why, which applies here
+// unchanged: a character is one byte of heap while the string stays one-byte
+// and two once it does not).
+//
+// 128 MiB, and the three readings that pick it:
+//
+//   - It is 26 times the largest single event ingest can admit (5,000,000
+//     characters plus this deck's envelope), so a burst of maximum-size tool
+//     responses — eight subagents each returning a big Read — is held whole
+//     rather than collapsing the ring to nothing.
+//   - It is thirteen times a completely FULL 2000-event ring of ordinary
+//     traffic. The mean serialized event is about 5 KB, measured over 4.7k real
+//     payloads in a 21 MB events.jsonl (the same sample redactDeckToken's note
+//     quotes), so 2000 of them are 10 MB. Ordinary traffic therefore never
+//     meets this bound at all and keeps the full count-based replay depth; only
+//     the traffic that used to kill the process ever sees it.
+//   - Its worst case is a bounded fraction of the heap rather than a multiple
+//     of it. 128 MiB of charged characters is at most about 320 MiB of retained
+//     heap — the charge below tracks real retention within 2.5x across every
+//     payload shape measured — which is 16% of the 2 GB heap an 8 GB laptop
+//     picks, against the 9.4 GB the count alone permitted.
+//
+// Exported for the same reason MAX_CLIENT_BUFFER_BYTES is: a bound whose only
+// observable failure is the process running out of memory is a bound no test
+// can assert. See event-ring-byte-cap.test.ts, which pins all three readings.
+export const MAX_BUFFER_CHARS = 128 * 1024 * 1024;
+
+// What one envelope costs on top of its payload — seq, epoch, receivedAt,
+// source and the JSON around them. Measured at 127 characters, the same figure
+// MAX_CLIENT_BUFFER_BYTES is sized against; 128 here so that an event with an
+// empty payload still costs something and a flood of them cannot be free.
+const ENVELOPE_CHARS = 128;
+
 const events = [];                  // ring buffer
+// The running sum of what `events` holds, in the units payloadChars charges.
+// Kept beside the array rather than recomputed, because the alternative is
+// walking every buffered payload on every push. It and `events` have to move
+// together and nothing outside this section may touch either — see
+// clearEventBuffer for the one place that empties both, and what went wrong the
+// day only one of them was emptied.
+let bufferedChars = 0;
+
+/**
+ * What this payload will cost the ring, charged in characters.
+ *
+ * Not `JSON.stringify(raw).length`, which is the obvious answer and is wrong
+ * here twice over. It allocates a full copy of a payload that can be five
+ * megabytes, on the hottest path in the process; and it would defeat the
+ * deliberate optimization in pushEvent that skips serializing ENTIRELY when
+ * nothing is subscribed and nothing is being logged — a headless deck, and the
+ * boot replay of a log that only rotates at 50 MB. That optimization is pinned
+ * by sse-serialize-once.test.ts, so serializing here would fail the suite as
+ * well as the machine.
+ *
+ * So it is a walk, allocating nothing, in the same iterative shape and for the
+ * same stack-overflow reason as redactDeckToken below: a body from JSON.parse
+ * is free to nest as deeply as it likes and a recursive scan would be a new way
+ * to blow the stack inside the request listener, where nothing catches it.
+ *
+ * WHAT IT CHARGES, and why it is not just the string lengths. Measured on
+ * Node 22.14 by parsing twenty copies of a 4.9M-character body of each shape
+ * and reading heapUsed after a forced GC — retained per copy, against what
+ * string characters alone would have charged:
+ *
+ *   one long string             4.67MB retained   4.67M charged   1.0x
+ *   array of 8-char strings     3.91MB retained   3.40M charged   1.2x
+ *   array of small numbers      4.67MB retained   0.00M charged   ∞
+ *   array of tiny objects      10.20MB retained   0.85M charged  12.0x
+ *   object of distinct keys    12.38MB retained   2.86M charged   4.3x
+ *
+ * A payload of numbers is INVISIBLE to a string-length charge while retaining
+ * 4.67 MB, and an array of small objects is under-charged twelvefold — so a
+ * ring bounded that way would have been the same OOM behind a different
+ * payload shape. Adding 8 characters per value (V8 spends a tagged slot on
+ * each, and small objects and packed arrays measured at 8–46 bytes an entry)
+ * and the length of every key brings the same five shapes to 1.0x, 0.6x, 1.0x,
+ * 1.7x and 2.5x — i.e. never blind, and never more than 2.5x under the truth.
+ * That 2.5x is what MAX_BUFFER_CHARS is sized against. The one direction it
+ * over-charges is arrays of short strings, which shortens replay depth and
+ * never the other way.
+ *
+ * Two-byte strings cost twice what they are charged, exactly as they do for
+ * MAX_CLIENT_BUFFER_BYTES: a 4.8M-character CJK payload retains 9.35 MB and is
+ * charged 4.67M. Folded into the same 2.5x.
+ *
+ * Cost, measured against the JSON.parse the same event already pays for:
+ * 0.21 µs for a realistic 5 KB hook payload, 0.04 µs for a 4.9M-character
+ * single string (it is one node), and 22.6 ms for the pathological 222k-tiny-
+ * object body — against 96.4 ms to JSON.parse that same body. So the walk is a
+ * fifth of a parse the ingest path is paying anyway, and cheaper than
+ * redactDeckToken's walk, which does substring searches this one does not.
+ *
+ * Exported so the charge itself can be asserted rather than inferred from the
+ * ring's behaviour.
+ */
+export function payloadChars(raw) {
+  if (typeof raw === "string") return raw.length;
+  // A top-level primitive is a legal body for `POST /api/event`, same as it is
+  // for redactDeckToken. One slot's worth.
+  if (raw === null || typeof raw !== "object") return 8;
+
+  let n = 0;
+  const stack = [raw];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    // Arrays and objects walked separately for the reason redactDeckToken gives:
+    // an indexed loop is markedly cheaper than `for…in`, and a single
+    // PostToolUse response can be an array of thousands.
+    if (Array.isArray(node)) {
+      n += 8 * node.length;
+      for (let i = 0; i < node.length; i++) {
+        const v = node[i];
+        if (typeof v === "string") n += v.length;
+        else if (v !== null && typeof v === "object") stack.push(v);
+      }
+    } else {
+      for (const k in node) {
+        const v = node[k];
+        n += 8 + k.length;
+        if (typeof v === "string") n += v.length;
+        else if (v !== null && typeof v === "object") stack.push(v);
+      }
+    }
+  }
+  return n;
+}
+
+// Where the charge rides. A Symbol key rather than an ordinary field, because
+// the envelope is JSON.stringify'd on the hot path into both the SSE frame and
+// the events.jsonl line, and JSON.stringify ignores symbol-keyed properties
+// entirely. So the number stays welded to the envelope it describes — which is
+// what makes it impossible for `bufferedChars` and `events` to drift apart —
+// without reaching the wire, the log, the client's HookEnvelope type, or the
+// 127-character envelope measurement MAX_CLIENT_BUFFER_BYTES is sized against.
+const CHARS = Symbol("ring charge");
+
+/**
+ * Empty the ring and the total measuring it, together.
+ *
+ * `/api/clear` used to be a bare `events.length = 0`, and with a running total
+ * beside the array that is a permanent debt: the total would still name events
+ * the array no longer holds, and every push after the first clear would evict
+ * against a budget already spent — a deck that answers one clear and then keeps
+ * a ring of one event for the rest of its life. The two variables move here and
+ * nowhere else.
+ */
+function clearEventBuffer() {
+  events.length = 0;
+  bufferedChars = 0;
+}
+
+/**
+ * What the ring holds right now — its length, what it is charged, and the seq
+ * range it spans.
+ *
+ * Exported alongside MAX_BUFFER and MAX_BUFFER_CHARS so a test can watch the
+ * bound hold through a real server instead of watching a process die, which is
+ * the only other way this bound is observable. The seq range is here for the
+ * property eviction has to keep and nothing else checks: what leaves is always a
+ * PREFIX, so `newest - oldest + 1` equals the count. An eviction that ever took
+ * from the middle would leave a hole no resuming client could ask for again,
+ * and that is exactly what `GET /api/events` and the replay loop would then
+ * hand out without noticing.
+ */
+export function eventBufferStats() {
+  return {
+    events: events.length,
+    chars: bufferedChars,
+    oldestSeq: events.length > 0 ? events[0].seq : 0,
+    newestSeq: events.length > 0 ? events[events.length - 1].seq : 0,
+  };
+}
+
 let nextSeq = 1;
 // Identity of *this* process's seq numbering. nextSeq restarts at 1 on every
 // boot and is re-derived by replaying events.jsonl, so it is monotonic only
@@ -104,11 +321,74 @@ export function writesLogFor(payload) {
   return typeof sid !== "string" || sid === "" || !foreignSessions.has(sid);
 }
 
+/**
+ * Who else is holding the log this deck would empty, and whose it is to empty.
+ *
+ * `events.jsonl` is one file several decks share — that is the whole reason the
+ * election above exists — and `POST /api/clear` truncated it from whichever deck
+ * happened to be asked. So Clear on a deck scoped to one tree deleted the
+ * machine-wide deck's weeks of history, and told nobody: the other deck goes on
+ * serving what is still in its ring, so the damage only shows up the next time
+ * it boots and replays a file that is now empty (#698). Measured on macOS 15 /
+ * Node 22.14: 1407 bytes and five lines before, 134 bytes after — and the 134
+ * were the clearing deck's own `__clear` marker, appended to a log it writes
+ * nothing else to.
+ *
+ * The rule this establishes is the one the rest of the file already runs on: a
+ * deck may empty the log it WRITES. Ownership is electWriters — the same
+ * election, over the same discovery records, that decides which deck appends a
+ * line — so the process that truncates the file is the process that fills it,
+ * which is also the only way the two operations are ordered on any platform. A
+ * deck that is not the elected writer clears its own canvas and leaves the file
+ * to the deck that owns it; the confirmation says so before the user presses
+ * anything, and says how many decks share the file when the answer is "yours to
+ * empty". Nothing here decides the copy — `GET /api/clear` hands these facts to
+ * the dialog, which is the half that keeps the user from destroying history they
+ * were never told about.
+ *
+ * Deliberately NOT a scope test. Whether this deck was started with
+ * `--workspace` has nothing to do with who owns a file: two machine-wide decks
+ * share one log exactly as a scoped one shares it with a machine-wide one, and
+ * the harm is the same in both directions.
+ *
+ * Fail-safe matches writesCodexLog's, for the same reason: with no discovery
+ * record of our own — the window before the first heartbeat writes it, or a deck
+ * that cannot write one at all — nobody can elect us and we keep what a lone
+ * deck does. The COUNT is still every deck sharing the file, so even inside that
+ * window the confirmation warns rather than guessing quietly.
+ */
+export async function logSharing() {
+  if (!persistPath) return { path: null, decks: 1, mine: true, owner: null };
+  const fold = s => (foldsCase() ? s.toLowerCase() : s);
+  const here = fold(persistPath);
+  const sameLog = d => typeof d.persist === "string" && d.persist !== "" && fold(d.persist) === here;
+
+  let live = [];
+  try { live = await readLiveDecks(); } catch { /* unreadable dir — treated as "alone" below */ }
+  const group = live.filter(sameLog);
+  const self = group.find(d => d.pid === process.pid) ?? null;
+  if (!self) return { path: persistPath, decks: Math.max(group.length + 1, 1), mine: true, owner: null };
+
+  const writers = electWriters(group);
+  const mine = writers.has(self);
+  // One log path, so the election normally returns exactly one deck. It can
+  // return more only when two decks spell the same file differently on a
+  // case-sensitive platform, which `sameLog` folded together and electWriters
+  // did not — the lowest port of them is the one to name, and `mine` above is
+  // the election's own answer either way.
+  const owner = mine
+    ? self
+    : [...writers].sort((a, b) => a.port - b.port || a.pid - b.pid)[0] ?? null;
+  return { path: persistPath, decks: group.length, mine, owner };
+}
+
 // ─── Persistence rotation ─────────────────────────────────────────────────
 // 24/7 dev servers used to grow events.jsonl unbounded — saw it hit GBs
 // across weeks. We rotate when the file passes ROTATE_AT_BYTES, archiving
 // the previous file to .1 and starting fresh. Last-event-id replay still
-// covers the in-memory ring buffer of MAX_BUFFER events.
+// covers the in-memory ring buffer, which is bounded by MAX_BUFFER events AND
+// by MAX_BUFFER_CHARS — so how far back a replay reaches depends on how large
+// the traffic has been, not on the count alone.
 const ROTATE_AT_BYTES = 50 * 1024 * 1024;
 let lastRotateCheckAt = 0;
 let rotateInProgress = false;
@@ -151,7 +431,33 @@ async function maybeRotatePersistFile() {
 // the offset tailing the Codex rollout watcher already does further down.
 const transcriptScans = new Map();        // path -> scan state
 const transcriptScanInFlight = new Map(); // path -> in-progress scan promise
-const MAX_TRANSCRIPT_SCANS = 256;         // bound the per-path state
+const transcriptScanSessions = new Map(); // session key -> Set<path>, LRU order
+
+// What the cap protects is unbounded growth across the sessions a long-lived
+// deck has seen and will never hear from again — so a SESSION is the unit it
+// has to be counted in. It used to count paths, which is not the same thing:
+// a session occupies one entry for its own JSONL plus one for every
+// `subagents/agent-*.jsonl` beside it, and that count is set by how heavily
+// the session delegates, not by anything the deck controls. Measured on this
+// machine, the two live sessions that produced #611 hold 198 and 133 subagent
+// files — 333 entries between them against a cap of 256, so each session's
+// throttled pass evicted the other's cursors and re-read from byte 0. One of
+// those directories alone is 130.8 MB and takes 6456 ms to fold cold against
+// 18 ms warm, inside a 2500 ms throttle: the pass could not finish before the
+// next one was due.
+//
+// So eviction drops a whole session at a time and never splits one. That is
+// also the answer to a session whose subagent count exceeds any fixed number
+// of entries: it is never evicted for being big, because the only thing a cap
+// can take is some OTHER, older session. A session's cursors live and die
+// together, which is the only grouping that makes the next pass cheap.
+const MAX_TRANSCRIPT_SCAN_SESSIONS = 256;
+// A session cap alone bounds identities, not bytes, so a second ceiling bounds
+// the memory — again by dropping whole sessions, never part of one. A scan
+// state retains 477 bytes measured, so 8192 entries is under 4 MB; it is also
+// ten times every agent-*.jsonl that exists on this machine across its whole
+// history (803), and 24x the 333 the two heaviest live sessions need.
+const MAX_TRANSCRIPT_SCAN_ENTRIES = 8192;
 
 // The transcript's `message.model`, and the only filter standing between it and
 // every model the deck shows. Bedrock and Mantle put a provider namespace in
@@ -192,12 +498,81 @@ const USAGE_FIELD_RE = {
 // `server_tool_use`, several fields earlier. Match the sub-object on the raw
 // line instead of on the extracted blob.
 const CACHE_CREATION_BLOCK_RE = /"cache_creation"\s*:\s*\{([^}]*)\}/g;
+// A finished `Task`/`Agent` call is written into the PARENT's transcript as a
+// top-level `toolUseResult`, and that object carries a `usage` block of its own
+// — the subagent's LAST API turn, restated on the parent's line. Those same
+// tokens are already in the subagent's own `subagents/agent-<id>.jsonl`, which
+// #685 folds into the session's totals, so counting the restated copy here
+// would charge them twice. Measured on a real transcript: the restated block
+// reports 181,387 cache-read tokens and the last usage block inside that
+// subagent's file reports 181,387 — the same tokens, written twice.
+//
+// Matched as a TOP-LEVEL key: a `{` or `,` and then the name unescaped. The
+// same text quoted inside a message — an assistant writing about this very
+// field, as this comment does — reaches the line as `\"toolUseResult\"`, whose
+// preceding character is a backslash, so a transcript that talks about the key
+// is not mistaken for one that carries it.
+const TOOL_USE_RESULT_KEY_RE = /[{,]"toolUseResult"\s*:/;
+
+/** The stretch of a transcript line whose `usage` blocks are the model's own
+ *  billing records — everything before a top-level `toolUseResult`. See
+ *  TOOL_USE_RESULT_KEY_RE. A line without one is billed whole, which is every
+ *  assistant line and therefore every line that legitimately has usage. */
+function billedUsageText(line) {
+  const m = TOOL_USE_RESULT_KEY_RE.exec(line);
+  return m ? line.slice(0, m.index) : line;
+}
 
 function grabUsageField(blob, key) {
   const m = blob.match(USAGE_FIELD_RE[key]);
   return m ? Number(m[1]) : 0;
 }
 
+// How many DISTINCT models one transcript may keep a usage bucket for.
+//
+// A session reaches two or three: `/model` mid-run, CC dropping to Sonnet when
+// the weekly Opus allowance runs low, a subagent turn on a different tier. The
+// cap is not about those. `MODEL_ID_RE` accepts anything beginning `claude-`,
+// and every line of a transcript is bytes this process was handed rather than
+// bytes it wrote — so a file naming a fresh `claude-<n>` on every line would
+// otherwise grow one bucket per line, inside the same scanner #674 put a
+// ceiling on for exactly this shape of reason. Past the cap the extra models'
+// tokens still reach `state.usage`, which is what every token count on screen
+// reads; they simply stop being attributed, and `usageByModelEntries` on the
+// client prices whatever the map does not explain at the session's current
+// model — the behaviour the whole deck had before #686.
+const MAX_TRANSCRIPT_USAGE_MODELS = 32;
+
+/** The per-model usage bucket for `model`, created on first sight. Null for a
+ *  line whose tokens we cannot attribute — no model seen yet in this file, or
+ *  the cap above already reached. */
+function usageBucketFor(state, model) {
+  if (!model) return null;
+  const existing = state.usageByModel[model];
+  if (existing) return existing;
+  if (Object.keys(state.usageByModel).length >= MAX_TRANSCRIPT_USAGE_MODELS) return null;
+  const fresh = newUsageTotals();
+  state.usageByModel[model] = fresh;
+  return fresh;
+}
+
+/** Add `src`'s per-model buckets into `dst`, key for key, and return `dst`.
+ *  Under the same cap as the per-file map, so a session that delegates to
+ *  hundreds of files cannot assemble an unbounded one out of bounded parts. */
+function mergeUsageByModel(dst, src) {
+  if (!src) return dst;
+  for (const [model, u] of Object.entries(src)) {
+    let bucket = dst[model];
+    if (!bucket) {
+      if (Object.keys(dst).length >= MAX_TRANSCRIPT_USAGE_MODELS) continue;
+      bucket = newUsageTotals();
+      dst[model] = bucket;
+    }
+    for (const k of Object.keys(bucket)) bucket[k] += u[k] ?? 0;
+  }
+  return dst;
+}
+
 function newContextBreakdown() {
   return {
     msgsUser: 0,
@@ -209,36 +584,180 @@ function newContextBreakdown() {
   };
 }
 
+/** A zeroed set of the six token counters a transcript reports. One shape, so
+ *  the per-file totals and the per-session sum of them add key for key. */
+function newUsageTotals() {
+  return {
+    input_tokens: 0, output_tokens: 0,
+    cache_read_input_tokens: 0, cache_creation_input_tokens: 0,
+    ephemeral_1h_input_tokens: 0, ephemeral_5m_input_tokens: 0,
+  };
+}
+
 function newTranscriptState() {
   return {
     offset: 0,          // bytes already folded in
+    midLine: false,     // the cursor sits inside a line longer than MAX_SCAN_CHUNK
     rootModel: null,
     lastModel: null,    // last claude-* model on any line, sidechain included
     subagentModels: {},
     aiTitle: null,      // newest "ai-title" entry, the session's sentence title
     agentName: null,    // newest "agent-name" entry, the session's short name
-    usage: {
-      input_tokens: 0, output_tokens: 0,
-      cache_read_input_tokens: 0, cache_creation_input_tokens: 0,
-      ephemeral_1h_input_tokens: 0, ephemeral_5m_input_tokens: 0,
-    },
+    usage: newUsageTotals(),
+    // The same totals, split by the model that produced them (#686). The flat
+    // bucket above stays the whole-transcript sum and is what every token count
+    // reads; this is what the DOLLARS are built from, because a session that
+    // switched model has tokens from two rate cards in one file and one rate
+    // applied to the lot is wrong by the ratio between them — measured at 60%
+    // under on a mostly-Opus session that ended on Sonnet, and 150% over on the
+    // mirror of it. Costs no extra read: `message.model` and the `"usage"` block
+    // are on the same line, and this pass already parses both.
+    usageByModel: {},
     ctx: newContextBreakdown(),
   };
 }
 
-async function readByteRange(path, from, to) {
+// ─── Following an append-only JSONL, one bounded chunk at a time ─────────
+// The most bytes ONE read of a transcript may allocate, and the ceiling that
+// makes the size of the file irrelevant to the size of the allocation.
+//
+// #674 is what its absence cost. `readByteRange` was called with `to` set to
+// `stat().size` on a path that arrives, unvalidated, in the body of a
+// credential-free `POST /api/event`, and it answered by allocating the whole of
+// it — once as a zero-filled Buffer and again as the string `toString` builds
+// from it. Measured here on Node 22.14 / macOS against a real deck on loopback,
+// sampling `process.memoryUsage.rss()` every 5 ms:
+//
+//   400 MB file, one POST:   51MB -> 848MB   (2x: the Buffer and the string)
+//   700 MB file, one POST:   52MB -> 753MB   (1x: 700 MB is past V8's ~512 MB
+//                                             max string, so `toString` threw
+//                                             into the catch below and only the
+//                                             Buffer was paid for)
+//
+// Both answered 200. Neither is a one-off: see `readAppendedLines` for the
+// second half of that defect, the cursor that could not advance.
+//
+// 8 MiB is picked against the only measurement that bears on it — the longest
+// single line in a real transcript. The note above `maybeResolveSessionName`
+// measures that at 710 KB in the 46.4 MB session on this machine, one big tool
+// result on one line, so the ceiling is about eleven times the worst line seen
+// and no real transcript line is ever split by it. Its worst case is 8 MiB of
+// Buffer plus up to 8 MiB of string per in-flight scan, which is an eighth of
+// the 128 MiB the ring buffer is already allowed to hold.
+export const MAX_SCAN_CHUNK = 8 * 1024 * 1024;
+
+// How far ONE pass will walk a file that is behind by more than a chunk.
+//
+// The cursor makes catching up cheap in steady state, but the FIRST pass over
+// an existing transcript has the whole file to fold, and a fix that made that
+// take one throttle window (2500 ms) per 8 MiB would have turned a 130.8 MB
+// transcript's first attach into forty seconds of a deck showing no model, no
+// name and no cost — the reintroduction, by a different route, of exactly the
+// stall #611 removed. So a pass loops over chunks until it is caught up, and
+// this bounds what one hook event can be made to walk.
+//
+// 256 MiB is twice the heaviest transcript this repo has ever measured (130.8
+// MB, #611), so an honest first attach never meets it and pays nothing for it.
+// What it stops is a caller who has got past `isClaudeTranscriptPath` below
+// pointing one POST at something arbitrarily large: the read still terminates,
+// the cursor keeps whatever it reached, and the next throttled pass continues
+// from there.
+export const MAX_SCAN_BYTES_PER_PASS = 256 * 1024 * 1024;
+
+const NEWLINE = 0x0a;
+
+/** Up to MAX_SCAN_CHUNK bytes of `path` from `from`, as a Buffer of exactly the
+ *  bytes that were read. The cap is here rather than at the call sites so that
+ *  no caller — including one added later — can name a range that allocates more
+ *  than the ceiling above. */
+async function readByteChunk(path, from, to) {
+  const len = Math.min(to - from, MAX_SCAN_CHUNK);
+  if (len <= 0) return Buffer.alloc(0);
   const fh = await open(path, "r");
   try {
-    const len = to - from;
-    if (len <= 0) return "";
     const buf = Buffer.alloc(len);
-    await fh.read(buf, 0, len, from);
-    return buf.toString("utf8");
+    const { bytesRead } = await fh.read(buf, 0, len, from);
+    return bytesRead === len ? buf : buf.subarray(0, bytesRead);
   } finally {
     await fh.close();
   }
 }
 
+async function readByteRange(path, from, to) {
+  return (await readByteChunk(path, from, to)).toString("utf8");
+}
+
+/**
+ * The next batch of COMPLETE lines appended to a JSONL file, and the cursor
+ * moved past exactly the bytes they occupy.
+ *
+ * `cursor` is `{ offset, midLine }` and is written in place; `size` is the
+ * caller's `stat()` reading. Returns `{ text, advanced }` where `advanced` is
+ * the number of bytes the cursor moved — zero means "nothing complete to fold
+ * yet", which is the caller's signal to stop.
+ *
+ * THE THREE THINGS THIS HAS TO GET RIGHT, and the one it used to get wrong:
+ *
+ *  1. A partial last line is not an error. A transcript is being appended to
+ *     while it is read, so the tail of any chunk that ends at EOF is routinely
+ *     half a line. Those bytes stay unread and the cursor does not move —
+ *     the next pass sees the whole line once its newline lands.
+ *
+ *  2. A chunk with no newline in it that DOES NOT end at EOF is a different
+ *     thing entirely, and the old code could not tell the two apart: it
+ *     returned without advancing in both cases. For any file with no newline in
+ *     it — any binary, a sparse file a caller makes for the purpose — that made
+ *     the early return permanent, so every later POST re-read the whole file
+ *     from byte 0. Measured before the fix, the same 400 MB file: 797 MB on the
+ *     first post, 400 MB on the second, 400 MB on the third. Here that case is
+ *     what `midLine` names: a full chunk with no line boundary anywhere in it
+ *     is a line longer than the ceiling, there is no line there to wait for, so
+ *     the cursor walks past it and the fragment that follows is dropped when
+ *     the next boundary arrives.
+ *
+ *  3. The cursor is moved by BYTES, taken from the buffer, never by
+ *     `Buffer.byteLength` of the decoded text. Chunking can split a multi-byte
+ *     character at the ceiling, and `toString` turns a split character into a
+ *     replacement character of a different width — so measuring the advance on
+ *     the string would drift the cursor on any transcript containing non-ASCII,
+ *     which is most of them. Slicing at the last newline (a byte that cannot be
+ *     part of a multi-byte sequence) and advancing by its index is exact.
+ */
+export async function readAppendedLines(path, cursor, size, chunkMax = MAX_SCAN_CHUNK) {
+  const from = cursor.offset;
+  const want = Math.min(size - from, chunkMax);
+  if (want <= 0) return { text: "", advanced: 0 };
+  const buf = await readByteChunk(path, from, from + want);
+  if (buf.length === 0) return { text: "", advanced: 0 };
+
+  const lastNl = buf.lastIndexOf(NEWLINE);
+  if (lastNl < 0) {
+    // Reaching the end of the file with no newline in hand is the ordinary
+    // partial last line: wait for its newline. (1) above. The test is where the
+    // read STOPPED, not how much was asked for, because `readByteChunk` clamps
+    // to MAX_SCAN_CHUNK and a short read is normally that clamp rather than the
+    // end of anything.
+    if (from + buf.length >= size) return { text: "", advanced: 0 };
+    // A chunk with no line boundary in it, and more file after it. (2).
+    cursor.offset = from + buf.length;
+    cursor.midLine = true;
+    return { text: "", advanced: buf.length };
+  }
+
+  const advanced = lastNl + 1;            // (3): bytes, up to and including the \n
+  let text = buf.toString("utf8", 0, lastNl);
+  if (cursor.midLine) {
+    // This chunk opens in the middle of a line we already walked past, so
+    // everything up to the first boundary is the tail of it and folding it
+    // would fold a fragment. Only the lines after it are whole.
+    const nl = text.indexOf("\n");
+    text = nl < 0 ? "" : text.slice(nl + 1);
+    cursor.midLine = false;
+  }
+  cursor.offset = from + advanced;
+  return { text, advanced };
+}
+
 // ─── Session naming ──────────────────────────────────────────────────────
 // CC writes two whole-line records that name the session, and nothing else in
 // the transcript carries either fact:
@@ -326,17 +845,53 @@ function foldTranscriptLine(state, line) {
     }
   }
 
-  // Usage totals sum every block in the file, resets included.
-  for (const m of line.matchAll(USAGE_BLOCK_RE)) {
+  // Usage totals sum every block in the file, resets included — every block the
+  // model was actually billed for, which is why the `toolUseResult` tail is cut
+  // off first (see billedUsageText) — and are summed a second time into the
+  // bucket of the model that produced them (#686).
+  //
+  // `state.lastModel` is the attribution, and it is the LINE's model whenever
+  // the line has one: the block above has already run and assigned it. That is
+  // the whole trick — CC writes `message.model` and `message.usage` into the
+  // same JSON object, so by the time this loop reads the tokens the model that
+  // produced them is the most recent thing the scanner saw. A usage block on a
+  // line naming no model falls back to the last model seen, which is the turn it
+  // belongs to; a usage block before ANY model line gets no bucket at all and
+  // stays in the flat total alone, where the client prices it at the session's
+  // current model exactly as it did before.
+  //
+  // The bucket takes exactly what the flat total takes, off the same `billed`
+  // text: a split that read a wider stretch of the line than the total it splits
+  // would re-introduce #685's double count on one side of the arithmetic only,
+  // and the two would stop summing to each other.
+  const billed = billedUsageText(line);
+  const bucket = usageBucketFor(state, state.lastModel);
+  for (const m of billed.matchAll(USAGE_BLOCK_RE)) {
     const blob = m[1];
-    state.usage.input_tokens += grabUsageField(blob, "input_tokens");
-    state.usage.output_tokens += grabUsageField(blob, "output_tokens");
-    state.usage.cache_read_input_tokens += grabUsageField(blob, "cache_read_input_tokens");
-    state.usage.cache_creation_input_tokens += grabUsageField(blob, "cache_creation_input_tokens");
+    const inTok    = grabUsageField(blob, "input_tokens");
+    const outTok   = grabUsageField(blob, "output_tokens");
+    const cacheR   = grabUsageField(blob, "cache_read_input_tokens");
+    const cacheC   = grabUsageField(blob, "cache_creation_input_tokens");
+    state.usage.input_tokens += inTok;
+    state.usage.output_tokens += outTok;
+    state.usage.cache_read_input_tokens += cacheR;
+    state.usage.cache_creation_input_tokens += cacheC;
+    if (bucket) {
+      bucket.input_tokens += inTok;
+      bucket.output_tokens += outTok;
+      bucket.cache_read_input_tokens += cacheR;
+      bucket.cache_creation_input_tokens += cacheC;
+    }
   }
-  for (const m of line.matchAll(CACHE_CREATION_BLOCK_RE)) {
-    state.usage.ephemeral_1h_input_tokens += grabUsageField(m[1], "ephemeral_1h_input_tokens");
-    state.usage.ephemeral_5m_input_tokens += grabUsageField(m[1], "ephemeral_5m_input_tokens");
+  for (const m of billed.matchAll(CACHE_CREATION_BLOCK_RE)) {
+    const h1 = grabUsageField(m[1], "ephemeral_1h_input_tokens");
+    const m5 = grabUsageField(m[1], "ephemeral_5m_input_tokens");
+    state.usage.ephemeral_1h_input_tokens += h1;
+    state.usage.ephemeral_5m_input_tokens += m5;
+    if (bucket) {
+      bucket.ephemeral_1h_input_tokens += h1;
+      bucket.ephemeral_5m_input_tokens += m5;
+    }
   }
 
   // Context counts only what follows the most recent /clear or /compact.
@@ -365,24 +920,58 @@ function foldTranscriptLine(state, line) {
   }
 }
 
-/** Record a use of `path` and keep the map under the cap. Re-inserting on
- *  every touch makes the Map's own insertion order the LRU order, so eviction
- *  reads one key instead of scanning for the smallest timestamp. Scanning a
- *  timestamp is also what broke the cache: a state is created with no stamp
- *  yet, so the entry the scan had just inserted was the smallest of all and
- *  the one deleted, every time. Past 256 distinct transcripts the map froze on
- *  the first 256 paths and every later transcript re-read its whole JSONL from
- *  byte 0 on every throttled pass — the O(n)-per-pass stall the cursor exists
+/** The session a transcript path belongs to, and the unit eviction works in.
+ *  CC's two layouts collapse onto the same key: the main transcript
+ *  `<slug>/<sessionId>.jsonl` loses its extension, and a subagent's
+ *  `<slug>/<sessionId>/subagents/agent-<id>.jsonl` loses everything below the
+ *  session directory, so both land on `<slug>/<sessionId>`. Anything else — a
+ *  Codex rollout, a shape we do not recognise — is a session of its own,
+ *  which is the old one-entry-per-path accounting and the safe default.
+ *
+ *  `resolve` first so the two halves agree on Windows. The main path arrives
+ *  from the hook payload as CC wrote it while the subagent path is built with
+ *  `join`, so `C:/x/y.jsonl` and `C:\x\y\subagents\agent-1.jsonl` would
+ *  otherwise be two sessions instead of one; `resolve` settles the separator
+ *  on all three platforms, and leaves a backslash inside a POSIX filename
+ *  alone rather than reading it as a directory break. */
+export function transcriptSessionKey(path) {
+  const full = resolve(path);
+  const sub = /^(.*)[\\/]subagents[\\/]agent-[0-9a-f]+\.jsonl$/i.exec(full);
+  return sub ? sub[1] : full.replace(/\.jsonl$/i, "");
+}
+
+/** Record a use of `path` and keep the cache under both caps. Re-inserting the
+ *  session on every touch makes the Map's own insertion order the LRU order,
+ *  so eviction reads one key instead of scanning for the smallest timestamp.
+ *  Scanning a timestamp is also what broke the cache once: a state is created
+ *  with no stamp yet, so the entry the scan had just inserted was the smallest
+ *  of all and the one deleted, every time. Whatever the cache freezes on, the
+ *  symptom is the same — every later transcript re-reads its whole JSONL from
+ *  byte 0 on every throttled pass, the O(n)-per-pass stall the cursor exists
  *  to remove. */
 function touchTranscriptScan(path, state) {
-  transcriptScans.delete(path);
   transcriptScans.set(path, state);
+  const key = transcriptSessionKey(path);
+  const paths = transcriptScanSessions.get(key) ?? new Set();
+  transcriptScanSessions.delete(key);   // re-insert = move to the back of the LRU
+  paths.add(path);
+  transcriptScanSessions.set(key, paths);
   pruneTranscriptScans();
 }
 
 function pruneTranscriptScans() {
-  while (transcriptScans.size > MAX_TRANSCRIPT_SCANS) {
-    transcriptScans.delete(transcriptScans.keys().next().value);
+  // The last session standing is never evicted, however many files it holds:
+  // dropping the cursors of the session currently being scanned is precisely
+  // the re-read this cache exists to avoid, and no cap can make its file
+  // count smaller.
+  while (
+    transcriptScanSessions.size > 1 &&
+    (transcriptScanSessions.size > MAX_TRANSCRIPT_SCAN_SESSIONS ||
+     transcriptScans.size > MAX_TRANSCRIPT_SCAN_ENTRIES)
+  ) {
+    const oldest = transcriptScanSessions.keys().next().value;
+    for (const p of transcriptScanSessions.get(oldest)) transcriptScans.delete(p);
+    transcriptScanSessions.delete(oldest);
   }
 }
 
@@ -409,14 +998,20 @@ function scanTranscript(path) {
         touchTranscriptScan(path, state);
       }
       if (s.size <= state.offset) return state;
-      const text = await readByteRange(path, state.offset, s.size);
-      const lastNl = text.lastIndexOf("\n");
-      if (lastNl < 0) return state;   // no complete line appended yet
-      const consumed = text.slice(0, lastNl);
-      // Advance before folding: a fold that throws half-way must not leave
-      // the cursor where the next pass would count those lines again.
-      state.offset += Buffer.byteLength(consumed, "utf8") + 1; // +1 for the \n
-      for (const line of consumed.split("\n")) foldTranscriptLine(state, line);
+      // Chunk by chunk rather than in one allocation, and loop rather than
+      // leave the rest for the next throttle window — see MAX_SCAN_CHUNK and
+      // MAX_SCAN_BYTES_PER_PASS for why it is both of those and not either one
+      // alone. `readAppendedLines` advances the cursor BEFORE this folds, which
+      // is the same rule the single-shot read kept: a fold that throws half-way
+      // must not leave the cursor where the next pass would count those lines
+      // again. `advanced === 0` is "nothing complete to fold yet".
+      let budget = MAX_SCAN_BYTES_PER_PASS;
+      while (budget > 0 && state.offset < s.size) {
+        const { text, advanced } = await readAppendedLines(path, state, s.size);
+        if (advanced === 0) break;
+        budget -= advanced;
+        for (const line of text.split("\n")) foldTranscriptLine(state, line);
+      }
     } catch { /* keep whatever we already folded */ }
     return state;
   })();
@@ -426,6 +1021,92 @@ function scanTranscript(path) {
   });
 }
 
+// ─── Which paths the deck will follow at all ─────────────────────────────
+// `payload.transcript_path` is a string in the body of `POST /api/event`, and
+// that route is a deliberate OPEN_MUTATION: no token, no Origin, nothing. Until
+// #674 the deck took whatever it said and opened it. The bounds above make that
+// survivable; this makes it uninteresting, and the two are worth having
+// together for different reasons.
+//
+// WHY VALIDATE AT ALL WHEN THE READ IS ALREADY BOUNDED. Because the caller here
+// is not a web page — `isTrustedMutation` refuses `Sec-Fetch-Site: cross-site`
+// before any of this — it is a local process: the sandboxed subprocess with
+// loopback egress that the comment above `isAuthorizedMutation` already names,
+// or another UID on a shared box. Against that caller a ceiling only sets the
+// price per request; it does not take the lever away. What takes it away is
+// that there is no file it can name. Claude Code writes transcripts in exactly
+// one place, `<config dir>/projects/…`, and every legitimate `transcript_path`
+// the deck has ever seen is one of those — so the set of things worth opening
+// is knowable in advance, and checking membership costs one string comparison
+// against a syscall that used to cost the size of the file.
+//
+// WHAT IS LEFT AFTERWARDS, stated plainly: a caller who can WRITE inside that
+// directory can still point the deck at a file of its choosing. That caller is
+// this user's own processes — and this user's own processes can read
+// `<config dir>/agent-dag/*.json`, which is where HOOK_TOKEN lives at mode
+// 0600, so they hold the credential already. The gate reduces the
+// credential-free adversary to the one who was never credential-free. That is
+// the whole of what it claims, and the ceilings above are what carries the
+// rest.
+//
+// WHY NOT realpath. A symlink planted inside the projects directory would
+// defeat the containment test — but planting one needs write access to that
+// directory, which is the case above where the caller already holds the token.
+// It would also cost a syscall on every hook event, on a path that runs for
+// every event of every live session.
+//
+// WHY TWO ROOTS. CLAUDE_CONFIG_DIR replaces ~/.claude wholesale, and the deck
+// reads the variable from its OWN environment while the path is written by
+// whatever `claude` process the hook fired in. Those normally agree — the deck
+// installs its hook into the directory it resolves, so a session whose events
+// arrive here is a session reading that same directory — but a deck launched
+// from a desktop shortcut that never sourced the shell rc is a real way for
+// them to disagree in one direction. Accepting the default location as well
+// costs nothing (it is a directory only this user writes either way) and
+// removes half of that failure mode. The other half is why the refusal is
+// logged rather than silent.
+function claudeTranscriptRoots() {
+  // Resolved per call, like every other claudeConfigDir() reader in this file,
+  // so nothing captures the answer from an environment that has moved.
+  const roots = [resolve(claudeConfigDir(), "projects")];
+  const byDefault = resolve(homedir(), ".claude", "projects");
+  if (!roots.includes(byDefault)) roots.push(byDefault);
+  return roots;
+}
+
+/** Is `p` a Claude Code transcript, in a directory Claude Code writes them?
+ *
+ *  Containment is compared on the RESOLVED path with a trailing separator, so
+ *  `…/projects-of-mine/x.jsonl` is not inside `…/projects` and `..` cannot
+ *  climb out of it. The comparison is case-insensitive on Windows and macOS,
+ *  whose default filesystems are, because the two halves come from two
+ *  processes and only one of them chose the casing. */
+export function isClaudeTranscriptPath(p, roots = claudeTranscriptRoots()) {
+  if (!p || typeof p !== "string") return false;
+  if (!/\.jsonl$/i.test(p)) return false;      // the only extension CC writes
+  const fold = process.platform === "win32" || process.platform === "darwin";
+  const full = fold ? resolve(p).toLowerCase() : resolve(p);
+  for (const root of roots) {
+    const prefix = (fold ? root.toLowerCase() : root) + sep;
+    if (full.startsWith(prefix) && full.length > prefix.length) return true;
+  }
+  return false;
+}
+
+// Refusals are logged once per path and the set is capped, because the point of
+// the log is a misconfigured deck saying so on stderr — one line naming the
+// path and where transcripts are expected — and a caller posting a fresh path
+// per request must not turn that into a second unbounded accumulation.
+const refusedTranscriptPaths = new Set();
+const MAX_REFUSED_TRANSCRIPT_PATHS = 64;
+
+function noteRefusedTranscript(p) {
+  if (refusedTranscriptPaths.has(p)) return;
+  if (refusedTranscriptPaths.size >= MAX_REFUSED_TRANSCRIPT_PATHS) return;
+  refusedTranscriptPaths.add(p);
+  console.warn(`${PRODUCT}: not reading transcript_path outside ${claudeTranscriptRoots().join(" or ")}: ${p}`);
+}
+
 // ─── Model enrichment ────────────────────────────────────────────────────
 // CC's hook payloads never carry the `model` field — but every hook
 // references a `transcript_path` JSONL that contains lines like
@@ -455,7 +1136,7 @@ export function cachedModelId(cached) {
  *  legacy-schema subagent models (older CC versions kept subagent blocks
  *  inline with `isSidechain:true` + `parentToolUseID`). Current CC versions
  *  store subagents in `<sessionDir>/subagents/agent-<id>.jsonl` — those are
- *  handled by `readSubagentModelsFromDir` below. */
+ *  handled by `readSubagentsFromDir` below. */
 export async function readModelFromTranscript(path) {
   const state = await scanTranscript(path);
   if (!state) return null;
@@ -473,8 +1154,38 @@ export async function readModelFromTranscript(path) {
  *  but the reducer looks up `${sessionId}::${key}` and the subagent node id
  *  is built from `agent_id` — identical lookup either way).
  *
- *  Returns { [agentId]: model } scanning every agent-*.jsonl file in dir. */
-async function readSubagentModelsFromDir(transcriptPath) {
+ *  Returns `{ models: { [agentId]: model }, usage: <summed totals|null> }` over
+ *  every agent-*.jsonl in the directory, or null when there is no such
+ *  directory — which is every Codex session and every legacy-schema Claude one.
+ *
+ *  WHY IT RETURNS USAGE AND NOT ONLY MODELS (#685). `scanTranscript` folds a
+ *  file's usage totals whether or not anyone asks for them, so this walk has
+ *  been computing every subagent's spend and dropping it on the floor, while
+ *  the session's totals came from the main transcript alone — and the main
+ *  transcript does not restate a subagent's turns. Measured on one real
+ *  session on the reporter's machine: 40.4M cache-read tokens in the main
+ *  JSONL against 217.7M across its twenty subagent files, so the deck was
+ *  reporting about a sixth of what the session actually cost.
+ *
+ *  WHY THE TOTALS ARE SUMMED HERE RATHER THAN SHIPPED PER AGENT. The obvious
+ *  shape is a `{ [agentId]: totals }` map so each subagent card can price its
+ *  own spend, and the cost of that shape is set by CC and not by us: #611
+ *  measured live sessions holding 198 and 133 of these files, and this machine
+ *  has one holding 397. At ~200 bytes an entry on a 2.5 s cadence that is
+ *  ~80 KB per pass into the SSE fan-out, the event ring and events.jsonl —
+ *  ~115 MB an hour into a log that rotates at 50 MB. One summed object is
+ *  ~150 bytes whatever the session delegates, so the session total is exact
+ *  and constant-cost, and per-card attribution stays a separate question.
+ *
+ *  `usageByModel` is summed on the same terms and for the same reason (#686):
+ *  a subagent runs on whatever model its Task was given, which is routinely not
+ *  its parent's — the deck already reads a per-agent `models` map three lines
+ *  up precisely because of that — so folding delegated tokens into the session
+ *  total without their model would price a Haiku subagent's spend at the root's
+ *  Opus rate. It stays constant-cost the way the flat total does: the key count
+ *  is the number of MODELS a session touched, two or three, not the number of
+ *  files it delegated to. */
+async function readSubagentsFromDir(transcriptPath) {
   // Subagent dir sits next to the main jsonl: <dir>/<sessionId>/subagents/
   // Derive from transcript_path by stripping the .jsonl suffix.
   if (!transcriptPath || typeof transcriptPath !== "string") return null;
@@ -483,6 +1194,9 @@ async function readSubagentModelsFromDir(transcriptPath) {
   let entries;
   try { entries = await readdir(subDir); } catch { return null; }
   const models = {};
+  const usage = newUsageTotals();
+  const usageByModel = {};
+  let spent = false;
   for (const f of entries) {
     if (!/^agent-([0-9a-f]+)\.jsonl$/i.test(f)) continue;
     const agentId = f.replace(/^agent-/, "").replace(/\.jsonl$/i, "");
@@ -492,11 +1206,53 @@ async function readSubagentModelsFromDir(transcriptPath) {
       // model wins — subagents may switch model mid-turn (Sonnet → Haiku for
       // tool-call fallback etc.).
       const state = await scanTranscript(full);
-      const last = state ? state.lastModel : null;
-      if (last) models[agentId] = last;
+      if (!state) continue;
+      if (state.lastModel) models[agentId] = state.lastModel;
+      // The cursor makes this cumulative and idempotent: `state.usage` is the
+      // whole file's totals however many passes it took to fold them, so
+      // re-summing every pass restates the same number rather than growing it.
+      for (const k of Object.keys(usage)) usage[k] += state.usage[k];
+      // Idempotent on the same argument as the line above: each file's split is
+      // its own cumulative totals, so re-summing every pass restates the map
+      // rather than growing it.
+      mergeUsageByModel(usageByModel, state.usageByModel);
+      if (state.usage.input_tokens || state.usage.output_tokens
+          || state.usage.cache_read_input_tokens || state.usage.cache_creation_input_tokens) {
+        spent = true;
+      }
     } catch { /* skip unreadable file */ }
   }
-  return Object.keys(models).length ? models : null;
+  const hasModels = Object.keys(models).length > 0;
+  if (!hasModels && !spent) return null;
+  return {
+    models: hasModels ? models : null,
+    usage: spent ? usage : null,
+    usageByModel: spent ? usageByModel : null,
+  };
+}
+
+// One walk of `<sessionDir>/subagents/` serves both the model pass and the
+// usage pass. The two are throttled independently but fire from the same hook
+// events, so without this the directory — up to a few hundred files — would be
+// listed and stat-ed twice per window for the same answer. The TTL sits under
+// MODEL_READ_THROTTLE_MS so two callers inside one window share a walk and the
+// next window always gets a fresh one.
+const subagentDirScans = new Map();  // transcriptPath -> { at, promise }
+const SUBAGENT_DIR_TTL_MS = 2000;
+
+function scanSubagentDir(transcriptPath) {
+  if (!transcriptPath || typeof transcriptPath !== "string") return Promise.resolve(null);
+  const now = Date.now();
+  // Expiry is the eviction rule: an entry outlives its window by nothing, so
+  // the map holds at most one entry per session read in the last two seconds.
+  for (const [k, v] of subagentDirScans) {
+    if (now - v.at >= SUBAGENT_DIR_TTL_MS) subagentDirScans.delete(k);
+  }
+  const memo = subagentDirScans.get(transcriptPath);
+  if (memo) return memo.promise;
+  const promise = readSubagentsFromDir(transcriptPath).catch(() => null);
+  subagentDirScans.set(transcriptPath, { at: now, promise });
+  return promise;
 }
 
 function maybeResolveModel(payload) {
@@ -513,12 +1269,12 @@ function maybeResolveModel(payload) {
   if (now - last < MODEL_READ_THROTTLE_MS) return;
   modelLastReadAt.set(sid, now);
   pendingTranscriptReads.add(sid);
-  Promise.all([readModelFromTranscript(tp), readSubagentModelsFromDir(tp)])
-    .then(([result, dirSubs]) => {
+  Promise.all([readModelFromTranscript(tp), scanSubagentDir(tp)])
+    .then(([result, dir]) => {
       const rootModel = result?.rootModel ?? null;
       // Merge legacy (inline isSidechain) + new (subagents/ dir) maps. Dir
       // wins on conflict since current CC only writes to the dir.
-      const subagentModels = { ...(result?.subagentModels ?? {}), ...(dirSubs ?? {}) };
+      const subagentModels = { ...(result?.subagentModels ?? {}), ...(dir?.models ?? {}) };
       if (!rootModel && Object.keys(subagentModels).length === 0) return;
       const prev = modelBySession.get(sid);
       const subsSig = JSON.stringify(subagentModels);
@@ -549,6 +1305,12 @@ const USAGE_READ_THROTTLE_MS = 2500;
 // Every entry carries its own usage object and we sum every occurrence, so
 // the totals are cumulative over the whole transcript — the running state
 // keeps them across passes and each pass only adds the newly appended blocks.
+//
+// ONE FILE, which is the whole file and no more. This reads the path it is
+// given; the session's delegated spend lives in the sibling `subagents/`
+// directory and is added by `sessionUsageTotals` below. Kept separate because
+// the two are read on different cadences by different callers and the tests
+// that pin the cursor arithmetic pin it one file at a time.
 export async function readUsageFromTranscript(path) {
   const state = await scanTranscript(path);
   if (!state) return null;
@@ -558,6 +1320,80 @@ export async function readUsageFromTranscript(path) {
   return totals;
 }
 
+/** One transcript's totals broken out by the model that produced them, or null
+ *  when the scan attributed nothing.
+ *
+ *  A SECOND EXPORT rather than one more key on the object above, and the reason
+ *  is that object's contract: `readUsageFromTranscript` is asserted with
+ *  `toEqual` on its whole shape, so a key added to it is a key every caller and
+ *  every fixture has to learn about. This costs no extra read — `scanTranscript`
+ *  hands back the state it already folded and coalesces concurrent callers onto
+ *  one pass — so the pair reads the file exactly as often as the single call
+ *  did. */
+export async function readUsageByModelFromTranscript(path) {
+  const state = await scanTranscript(path);
+  if (!state) return null;
+  const out = {};
+  for (const [model, u] of Object.entries(state.usageByModel)) {
+    if (u.input_tokens === 0 && u.output_tokens === 0
+        && u.cache_read_input_tokens === 0 && u.cache_creation_input_tokens === 0) continue;
+    out[model] = { ...u };
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/** The session's whole spend split by model — its own turns plus every
+ *  subagent's, merged (#686).
+ *
+ *  The counterpart of `sessionUsageTotals` below and read from the same two
+ *  places, so the split and the total it splits are always a description of the
+ *  same bytes. A subagent runs on the model its Task was given, which is
+ *  routinely not its parent's, so a session sum that carried only the root's
+ *  models would price delegated tokens at whatever the root is on now — the
+ *  same mistake as the one being fixed, one level in. */
+export async function sessionUsageByModel(transcriptPath) {
+  const [own, dir] = await Promise.all([
+    readUsageByModelFromTranscript(transcriptPath),
+    scanSubagentDir(transcriptPath),
+  ]);
+  if (!own && !dir?.usageByModel) return null;
+  const out = mergeUsageByModel({}, own);
+  mergeUsageByModel(out, dir?.usageByModel);
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * Everything a Claude session has spent: its own turns plus every subagent it
+ * ran. Returns null when the session has spent nothing yet.
+ *
+ * WHAT THIS NUMBER MEANS, and why it is one number (#685). A session is a
+ * bill, and delegating work does not move any of it somewhere else — the
+ * subagent's tokens are charged to the same account on the same invoice. The
+ * two halves live in two places on disk because CC writes them there:
+ * `<sessionId>.jsonl` for the root's turns, `<sessionId>/subagents/agent-*.jsonl`
+ * for each delegated one, with no overlap between them (verified against real
+ * transcripts: a session holding 397 subagent files had zero `isSidechain`
+ * lines in its main JSONL). Summing the two therefore counts every token
+ * exactly once, and the reducer ASSIGNS the result rather than adding it, so a
+ * pass that lands twice restates the same total instead of doubling it.
+ *
+ * The one place the two files did overlap is the `toolUseResult` block a
+ * finished Task leaves on the parent's line, which restates the subagent's
+ * last turn; `billedUsageText` cuts that out of the scan so this sum stays a
+ * sum of distinct tokens.
+ */
+export async function sessionUsageTotals(transcriptPath) {
+  const [own, dir] = await Promise.all([
+    readUsageFromTranscript(transcriptPath),
+    scanSubagentDir(transcriptPath),
+  ]);
+  const delegated = dir?.usage ?? null;
+  if (!own && !delegated) return null;
+  const totals = own ? { ...own } : newUsageTotals();
+  if (delegated) for (const k of Object.keys(totals)) totals[k] += delegated[k] ?? 0;
+  return totals;
+}
+
 function maybeResolveUsage(payload) {
   if (!payload || typeof payload !== "object") return;
   const sid = payload.session_id;
@@ -569,10 +1405,16 @@ function maybeResolveUsage(payload) {
   if (now - last < USAGE_READ_THROTTLE_MS) return;
   lastUsageReadAt.set(sid, now);
   pendingUsageReads.add(sid);
-  readUsageFromTranscript(tp)
-    .then(usage => {
+  Promise.all([sessionUsageTotals(tp), sessionUsageByModel(tp)])
+    .then(([usage, usageByModel]) => {
       if (!usage) return;
-      pushEvent({ hook_event_name: "UsageObserved", session_id: sid, usage }, "internal");
+      // `usageByModel` rides on the same event because it is the same
+      // measurement, read from the same two places by the same walk — the main
+      // transcript and the `subagents/` directory — so the split and the total
+      // it splits cannot describe two different moments of the session. Sent
+      // even when null: an absent split has to CLEAR a stale one on the client,
+      // for the reason the flat totals are assigned rather than added.
+      pushEvent({ hook_event_name: "UsageObserved", session_id: sid, usage, usageByModel }, "internal");
     })
     .catch(() => {})
     .finally(() => pendingUsageReads.delete(sid));
@@ -771,9 +1613,23 @@ async function collectMemoryFiles(paths) {
  *  a test is how they would drift. */
 export async function scanClaudeMdFiles(cwd) {
   if (!cwd || typeof cwd !== "string") return [];
-  const home = homedir();
+  // The CONFIG dir, not the home directory. CLAUDE_CONFIG_DIR relocates it
+  // wholesale — it replaces ~/.claude rather than overlaying it — so on a
+  // machine where it is set, `homedir()/.claude` is a directory Claude Code
+  // does not read. Spelling it by hand here failed in both directions at once:
+  // the user-global memory file and every auto-memory file went missing from
+  // the modal and from the byte total beside it, while a stale ~/.claude left
+  // over from before the variable was set got listed as if it were in context.
+  // Resolved per call, like the two other claudeConfigDir() readers in this
+  // file, so nothing captures the answer from an environment that has moved.
+  const cfg = claudeConfigDir();
   // Walk up from cwd to filesystem root, checking the canonical CC memory
   // filenames plus CLAUDE.local.md (user-private) at each level.
+  //
+  // The `.claude/` prefix on the last two is NOT the config dir wearing a
+  // second spelling: it is CC's per-directory project convention, one such
+  // folder per level of the walk, and it stays literal however the config dir
+  // moves.
   const paths = memoryWalkPaths(cwd, [
     "CLAUDE.md",
     "CLAUDE.local.md",
@@ -781,14 +1637,15 @@ export async function scanClaudeMdFiles(cwd) {
     join(".claude", "CLAUDE.local.md"),
   ]);
   // User-global memory.
-  paths.push(join(home, ".claude", "CLAUDE.md"));
-  paths.push(join(home, ".claude", "CLAUDE.local.md"));
-  // Per-project auto-memory: ~/.claude/projects/<slug>/memory/*.md
-  // (plus MEMORY.md index). CC injects these into context for sessions
-  // whose cwd matches the slug.
+  paths.push(join(cfg, "CLAUDE.md"));
+  paths.push(join(cfg, "CLAUDE.local.md"));
+  // Per-project auto-memory: $CLAUDE_CONFIG_DIR/projects/<slug>/memory/*.md
+  // (plus MEMORY.md index). CC injects these into context for sessions whose
+  // cwd matches the slug. That directory sits beside the <sessionId>.jsonl
+  // transcripts, so it moves with the config dir by construction.
   const slug = ccProjectSlug(cwd);
   if (slug) {
-    const memDir = join(home, ".claude", "projects", slug, "memory");
+    const memDir = join(cfg, "projects", slug, "memory");
     try {
       const entries = await readdir(memDir);
       for (const f of entries) {
@@ -1092,7 +1949,9 @@ function maybeResolveCodex(payload) {
 // agent-dag event stream from them. Each rollout line is one append-only JSON
 // object {timestamp, type, payload}; we map the relevant ones to the same
 // synthetic hook payloads the reducer already understands:
-//   session_meta                       → SessionStart
+//   session_meta                       → SessionStart, but ONLY for a rollout
+//                                        this watcher read from byte 0 (#684).
+//                                        See ensureCodexRoot.
 //   event_msg/user_message             → UserPromptSubmit (Codex ≤ 0.144)
 //   event_msg/item_completed/UserMessage → UserPromptSubmit (Codex ≥ 0.147)
 //   response_item/function_call        → PreToolUse
@@ -1119,7 +1978,8 @@ function maybeResolveCodex(payload) {
 // broadcasts them exactly like a hook event, and persists them when this deck is
 // the one elected to log this rollout — see writesCodexLog. This path is
 // entirely additive — the Claude hook flow is untouched.
-const codexFileState = new Map();      // path -> { offset, sid, cwd, skip, seenAt }
+// path -> { offset, sid, cwd, skip, sawBeginning, rootOpened, seenAt }
+const codexFileState = new Map();
 const codexSessionModel = new Map();   // sid -> last model string
 // sid -> the `approval_policy` of the newest `turn_context` seen on this
 // session. See codexObjToPayload for why this is read and what it is NOT used
@@ -1133,20 +1993,160 @@ let codexScanRunning = false;
 let codexWatchTimer = null;
 let codexWorkspace = "";
 
+// How long one record's challenge verdict is trusted. The rollout scan runs
+// every 1.5s and would otherwise pay a round trip per record per tick for an
+// answer that changes about once per deck lifetime.
+//
+// Both answers are cached, and neither one delays a takeover, because the pid
+// probe runs first and is not cached at all: a deck killed with SIGTERM or
+// SIGKILL loses its pid immediately and its record is dropped on the very next
+// tick whatever this map says. What the TTL bounds is only the ghost case — a
+// record whose pid was recycled by an unrelated process — where five seconds of
+// believing a stale "yes" is at most a few unwritten lines, against a directory
+// listing plus an HTTP round trip on every tick of every deck forever.
+const DECK_PROOF_TTL_MS = 5000;
+// The same deadline hook.js gives a challenge, and for the same reason: a
+// bodyless GET to a loopback port is sub-millisecond when a deck is there and an
+// instant ECONNREFUSED when nothing is.
+const DECK_CHALLENGE_TIMEOUT_MS = 400;
+// `${pid}:${port}:${token}` -> { at, ok }. Keyed on the record's own identity so
+// a rewritten record — a deck that restarted onto the same port with a fresh
+// token — is a new question rather than an inherited answer.
+const deckProofs = new Map();
+
 /**
- * Every deck registered right now, as its own discovery record spells it.
+ * Is the process listening on this record's port the deck the record describes?
+ *
+ * WHY THE SERVER ASKS AT ALL (#695). readLiveDecks used to trust the pid and
+ * nothing else, and a pid is not evidence: a record left behind by a deck that
+ * is gone — SIGKILL, an OOM kill, a power cut, a console window closed on
+ * Windows, none of which run the shutdown that unlinks it — passes a signal-0
+ * probe forever once the OS hands that number to some other long-lived process.
+ * writesCodexLog then elected it, because it named a lower port than any real
+ * deck, and every deck tailing the rollout drew the events while none of them
+ * appended a line. The canvas looked perfectly normal and events.jsonl stopped
+ * growing, so nothing said so until a restart replayed a log that had stopped
+ * days earlier.
+ *
+ * hook.js has had the answer to this since the handshake landed and the Codex
+ * half never got it — this is that half. The record carries the deck's own token
+ * in plaintext (mode 0600, same user, and it is written there precisely so that
+ * another process can challenge with it), so we can ask its port to hash that
+ * token against a nonce it has never seen. A stranger cannot answer; the deck
+ * that wrote the file can.
+ *
+ * Two records pass without being asked:
+ *
+ *   • our own. We are the process the record describes, and challenging
+ *     ourselves over loopback inside our own scan is a question we already know
+ *     the answer to. It also must never fail: writesCodexLog looks itself up in
+ *     this list, and a deck that cannot find its own record falls back to
+ *     writing — so a self-challenge that timed out under load would turn one
+ *     unwritten line into a duplicated one.
+ *   • a record with no token, written by a deck older than the handshake. That
+ *     is exactly requiresProof's fallback in hook.js, kept in step with it on
+ *     purpose: refusing those would make every pre-1.33.71 deck invisible to the
+ *     election, which elects a writer for a log those decks are still appending
+ *     to.
+ *
+ * A timeout counts as a failure, like a refusal and a wrong answer. That is the
+ * same verdict hook.js reaches — a target that misses the deadline is not posted
+ * to either — and it errs the direction this file has always erred: the deck
+ * writes, and "a line written twice is recoverable; a deck that quietly stops
+ * recording anything is not" (writesCodexLog).
+ */
+async function provesDeck(d) {
+  if (d.pid === process.pid) return true;
+  if (typeof d.token !== "string" || d.token === "") return true;
+
+  const key = `${d.pid}:${d.port}:${d.token}`;
+  const cached = deckProofs.get(key);
+  const now = Date.now();
+  if (cached && now - cached.at < DECK_PROOF_TTL_MS) return cached.ok;
+
+  const ok = await challengeDeck(d.port, d.token);
+  deckProofs.set(key, { at: now, ok });
+  // Records come and go; without this the map would grow by one entry per deck
+  // that ever registered on this machine while the process is up.
+  for (const [k, v] of deckProofs) {
+    if (now - v.at >= DECK_PROOF_TTL_MS) deckProofs.delete(k);
+  }
+  return ok;
+}
+
+/**
+ * One challenge round trip, resolving true only on a correct proof.
+ *
+ * The compare is constant-time for the reason hook.js's sameProof is: whatever
+ * is on that port may not be a deck, and it must not be able to walk the
+ * expected proof out of us one byte at a time by timing how long we take to hang
+ * up. The nonce is fresh per call, so an answer overheard earlier is worth
+ * nothing, and the token itself never leaves this process.
+ */
+function challengeDeck(port, token) {
+  return new Promise(resolve => {
+    let settled = false;
+    const finish = ok => { if (settled) return; settled = true; resolve(ok); };
+    const nonce = randomBytes(16).toString("hex");
+    const want = challengeProof(token, nonce);
+    const req = httpRequest({
+      hostname: "127.0.0.1",
+      port,
+      path: `/api/hook-challenge?nonce=${nonce}`,
+      method: "GET",
+      timeout: DECK_CHALLENGE_TIMEOUT_MS,
+    }, res => {
+      if (res.statusCode !== 200) { res.resume(); return res.on("end", () => finish(false)); }
+      let answer = "";
+      res.setEncoding("utf8");
+      res.on("data", c => {
+        answer += c;
+        // A deck answers in ~100 bytes. Anything pouring data at us is not one,
+        // and must not be allowed to grow this buffer without bound.
+        if (answer.length > 4096) { req.destroy(); finish(false); }
+      });
+      res.on("end", () => {
+        if (settled) return;
+        let proof;
+        try { proof = JSON.parse(answer).proof; } catch { return finish(false); }
+        finish(sameProof(proof, want));
+      });
+    });
+    req.on("error", () => finish(false));
+    req.on("timeout", () => req.destroy());
+    req.end();
+  });
+}
+
+/** hook.js's sameProof, for the same reason it is constant-time there. */
+function sameProof(got, want) {
+  if (typeof got !== "string") return false;
+  const a = Buffer.from(got, "utf8");
+  const b = Buffer.from(want, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/**
+ * Every deck registered right now, as its own discovery record spells it — and
+ * only the ones that proved they are still the deck their record describes.
  *
  * These are the files hook.js enumerates; this is the server reading them for
  * itself, because the rollout watcher has no hook to do it and still has to know
  * which other decks are tailing the same file into the same log. Dead pids are
  * ignored rather than unlinked — sweepStaleDiscovery owns that, and a poll
- * running every 1.5s is no place to be deleting other decks' registrations.
+ * running every 1.5s is no place to be deleting other decks' registrations. A
+ * record that fails the challenge is likewise left alone: see the same argument
+ * spelled out in proveTargets in hook/hook.js.
+ *
+ * The pid probe stays, in front of the challenge, because it is free and it is
+ * the one test that answers instantly when a deck is killed — which is what
+ * keeps the takeover immediate rather than TTL-bound. See provesDeck.
  */
 async function readLiveDecks() {
   const dir = join(claudeConfigDir(), "agent-dag");
   let files;
   try { files = await readdir(dir); } catch { return []; }
-  const decks = [];
+  const candidates = [];
   for (const f of files) {
     if (!f.endsWith(".json")) continue;
     try {
@@ -1155,10 +2155,13 @@ async function readLiveDecks() {
       // record cannot take part in an election either way.
       if (!d || typeof d.pid !== "number" || typeof d.port !== "number") continue;
       if (!isProcessAlive(d.pid)) continue;
-      decks.push(d);
+      candidates.push(d);
     } catch { /* corrupt, or gone between listing and read */ }
   }
-  return decks;
+  // In parallel: with several decks up this is the difference between one 400ms
+  // deadline for the scan and one per record.
+  const proven = await Promise.all(candidates.map(provesDeck));
+  return candidates.filter((_, i) => proven[i]);
 }
 
 // List rollout files from the newest 2 day-directories. New sessions always
@@ -1193,7 +2196,11 @@ async function readCodexHeader(path) {
       if (nl >= 0) {
         const obj = JSON.parse(text.slice(0, nl));
         if (obj && obj.type === "session_meta" && obj.payload) {
-          return { sid: obj.payload.id, cwd: typeof obj.payload.cwd === "string" ? obj.payload.cwd : null };
+          // Canonicalised here and nowhere else: everything downstream — the
+          // workspace test below, the log election, the cwd on every event this
+          // rollout produces — reads state.cwd, and this is the one place it is
+          // read off disk. See canonicalCwd.
+          return { sid: obj.payload.id, cwd: await canonicalCwd(obj.payload.cwd) };
         }
         return null;
       }
@@ -1549,12 +2556,71 @@ function emitCodexEvent(payload, persist) {
   pushEvent(payload, "codex", { persist });
 }
 
-// Emit the SessionStart root exactly once per file, lazily — only when the
-// session actually produces an event. This keeps long-dead sessions that were
-// merely on disk at startup from cluttering the canvas with empty roots.
+/**
+ * Open this rollout's session on the canvas, once, lazily — only when it
+ * actually produces an event. Emitting eagerly for every file on disk at
+ * startup would fill the canvas with empty roots for sessions nobody will ever
+ * append to again.
+ *
+ * WHETHER A `SessionStart` IS EMITTED AT ALL IS THE WHOLE OF #684.
+ *
+ * This used to mint one unconditionally, and for a rollout the deck joined
+ * partway through that event is a false statement. #683 made the falsehood
+ * visible rather than merely wrong: a root created by anything OTHER than a
+ * `SessionStart` is marked `synthetic` in the reducer — "the deck joined this
+ * session after it had already begun, so the start time, the prompt history and
+ * the early tool calls on this card are incomplete rather than empty" — and a
+ * Codex session that carries a minted `SessionStart` clears that marker and
+ * asserts a beginning nobody watched. The Claude side never had the problem: a
+ * deck that starts mid-session simply never receives a `SessionStart` hook for
+ * it, which is exactly the case the marker was built for.
+ *
+ * `sawBeginning` is the one fact that separates the two, and it is not a
+ * filesystem question. It is set where the tail cursor is: TRUE when this
+ * watcher opened the rollout at byte 0 and therefore holds every line the
+ * session ever wrote, FALSE when codexScanOnce's `firstRun` skipped a
+ * pre-existing file's history by seeking to its current size. That is the same
+ * fact the event states, read off the only thing that actually knows it, and it
+ * is the same on Linux, macOS and Windows because no platform API is consulted.
+ *
+ * WHY NOT `fs.watch`, AND WHY NOT `birthtime` — both measured rather than
+ * assumed, on Node 22.14 / darwin, plus the documented behaviour elsewhere:
+ *
+ *   • `fs.watch` on a path that does not exist throws ENOENT, and
+ *     ~/.codex/sessions/YYYY/MM/DD does not exist until the day's first
+ *     session — the same reason startCodexWatcher polls instead of watching.
+ *   • a NON-recursive watch on ~/.codex/sessions reports only `rename:2026`
+ *     when a rollout appears three levels below it; the file's creation is
+ *     invisible to it.
+ *   • `recursive: true` works here and on Windows, and on Linux only from a
+ *     Node 20.x release — while this package declares `"node": ">=18"`, so on
+ *     the OS Codex users most often run servers on it may simply not be there.
+ *   • even where it works the event does not mean "created": writing the file
+ *     and then rewriting it produced `rename:rollout.jsonl` BOTH times, and
+ *     Node documents the event type as not guaranteed and `filename` as
+ *     possibly null.
+ *   • `stat().birthtimeMs` is real on APFS, but Node documents it as falling
+ *     back to ctime or to the Unix epoch on filesystems that do not carry it —
+ *     so on some Linux hosts every rollout would look newborn.
+ *
+ * WHAT ANOTHER DECK SEES. Nothing new: the fix REMOVES a line from
+ * events.jsonl, it does not add one or change a shape. A joined-late Codex
+ * session now reaches the shared log looking exactly like a joined-late Claude
+ * one — a root conjured by its first real event — which every deck, including
+ * one older than #683 that has no marker to light, has always been able to
+ * replay. The events that create the root instead (`UserPromptSubmit`,
+ * `PreToolUse`, `ModelObserved`, …) each carry `provider: "codex"`, `cwd` and
+ * `approval_policy` from `base` in codexObjToPayload, so nothing an older deck
+ * read off the `SessionStart` is lost with it.
+ *
+ * `rootOpened` still flips in both cases, and deliberately: it gates the
+ * per-batch AGENTS.md resolution in codexScanOnce, which asks "is this session
+ * being drawn", not "did we announce it".
+ */
 function ensureCodexRoot(state, persist) {
-  if (state.rootEmitted) return;
-  state.rootEmitted = true;
+  if (state.rootOpened) return;
+  state.rootOpened = true;
+  if (!state.sawBeginning) return;
   emitCodexEvent({ session_id: state.sid, cwd: state.cwd, provider: "codex", hook_event_name: "SessionStart" }, persist);
 }
 
@@ -1581,16 +2647,32 @@ async function codexScanOnce(firstRun) {
         const header = await readCodexHeader(path);
         if (!header || !header.sid) continue; // not ready yet — retry next tick
         if (!codexCwdInWorkspace(header.cwd, codexWorkspace)) {
-          codexFileState.set(path, { offset: st.size, sid: header.sid, cwd: header.cwd, skip: true, rootEmitted: false, seenAt: now });
+          codexFileState.set(path, { offset: st.size, sid: header.sid, cwd: header.cwd, skip: true, sawBeginning: false, rootOpened: false, seenAt: now });
           continue;
         }
-        state = { offset: 0, sid: header.sid, cwd: header.cwd, skip: false, rootEmitted: false, seenAt: now };
+        // Opened at byte 0, so every line this session ever wrote is about to
+        // be read: this watcher HAS its beginning, and ensureCodexRoot may say
+        // so. The `firstRun` branch below is the one case that takes it away.
+        state = { offset: 0, sid: header.sid, cwd: header.cwd, skip: false, sawBeginning: true, rootOpened: false, seenAt: now };
         codexFileState.set(path, state);
         if (firstRun) {
           // On startup, skip a pre-existing session's history entirely — no
-          // root, no replay. Only future appends (a live session that keeps
-          // going) will lazily create the root via ensureCodexRoot.
+          // replay. Only future appends (a live session that keeps going) will
+          // lazily open the root via ensureCodexRoot.
+          //
+          // And it opens WITHOUT a `SessionStart` (#684). Seeking to the
+          // current size is precisely the admission that this deck did not
+          // watch the session begin, so it must not go on to emit the event
+          // that says it did — that is the input #683's joined-late marker is
+          // entitled to trust. A deck RESTARTING over a session that is still
+          // running lands here too, and correctly: the new process holds none
+          // of the old one's history either. If the log it replays at boot
+          // already contains a `SessionStart` this deck minted honestly in an
+          // earlier life, the root is rebuilt unmarked from that line and stays
+          // unmarked — the reducer only honours `synthetic` on the call that
+          // CREATES the node, and nothing here contradicts it.
           state.offset = st.size;
+          state.sawBeginning = false;
           continue;
         }
       }
@@ -1598,11 +2680,12 @@ async function codexScanOnce(firstRun) {
       if (state.skip) { state.offset = st.size; continue; }
       if (st.size <= state.offset) continue;
 
-      const text = await readByteRange(path, state.offset, st.size);
-      const lastNl = text.lastIndexOf("\n");
-      if (lastNl < 0) continue; // no complete line yet
-      const consume = text.slice(0, lastNl);
-      state.offset += Buffer.byteLength(consume, "utf8") + 1; // +1 for the \n
+      // Same bounded reader the Claude transcripts use. A rollout is not a
+      // caller-chosen path, so this is not the #674 exposure — but the
+      // allocation was the size of the appended bytes here too, and one chunk
+      // per tick is more than any real rollout appends in a tick.
+      const { text: consume, advanced } = await readAppendedLines(path, state, st.size);
+      if (advanced === 0) continue; // no complete line yet
 
       // Decided per file rather than per line: which decks are up, and which of
       // them tail this rollout, cannot change inside one batch of appended
@@ -1641,7 +2724,7 @@ async function codexScanOnce(firstRun) {
       // lines, and a batch whose roots and tool calls went to one deck's log
       // while its memory list went to every deck's is the split the election
       // exists to prevent (#447).
-      if (state.rootEmitted) maybeResolveCodexMemory(state.sid, state.cwd, persist);
+      if (state.rootOpened) maybeResolveCodexMemory(state.sid, state.cwd, persist);
     }
 
     // Rollout files fall out of the newest-2-days listing and never come back,
@@ -1671,8 +2754,10 @@ export function startCodexWatcher(workspace) {
   // filesystem watch is no help: fs.watch on a missing path throws, and
   // watching the parent recursively is macOS/Windows-only.
   //
-  // Initial catalog: create roots for in-progress sessions, skip their
-  // history, then poll for new lines.
+  // Initial catalog: park a cursor at the end of every rollout already on disk,
+  // skipping its history, then poll for new lines. The `true` is what tells
+  // codexScanOnce that these files pre-date this deck, and so that the roots
+  // they eventually open must arrive without a `SessionStart` (#684).
   codexScanOnce(true).catch(() => {});
   codexWatchTimer = setInterval(() => { codexScanOnce(false).catch(() => {}); }, 1500);
   if (codexWatchTimer.unref) codexWatchTimer.unref();
@@ -2050,9 +3135,55 @@ function pushEvent(raw, source, opts = {}) {
     receivedAt: opts.receivedAt ?? Date.now(),
     source,
     payload: raw,
+    // Charged once, here, and carried on the envelope so eviction never has to
+    // walk a payload a second time. Symbol-keyed, so it is invisible to the two
+    // JSON.stringify calls below and to the `{ ...e }` the replay loop makes.
+    // Charged AFTER redactDeckToken, like everything else in this function: the
+    // payload being measured is the one that will be stored.
+    [CHARS]: ENVELOPE_CHARS + payloadChars(raw),
   };
   events.push(evt);
-  if (events.length > MAX_BUFFER) events.splice(0, events.length - MAX_BUFFER);
+  bufferedChars += evt[CHARS];
+
+  // Evict oldest-first until BOTH bounds hold — the count that has always been
+  // here, and the byte budget #625 added. See MAX_BUFFER_CHARS for the numbers.
+  //
+  // Counted first and spliced once, rather than shifting in a loop, because the
+  // two bounds evict at very different scales. The count bound drops exactly
+  // one entry per push; the byte bound can drop hundreds, since twenty-seven
+  // maximum-size events fill the whole budget on their own, and a shift per
+  // entry would memmove the array once for each of them.
+  //
+  // `drop < events.length - 1` is what keeps the event just pushed, whatever it
+  // weighs. A single event is allowed to be larger than the entire budget —
+  // ingest admits 5,000,000 characters, and a Codex rollout line read off disk
+  // has no length bound at all — and evicting it on arrival would leave
+  // pushEvent returning an envelope that `GET /api/events` never shows and no
+  // resuming client can ever be handed: a hole with no id to ask for it again,
+  // which is the exact failure the resume path below is written to avoid. So
+  // the true ceiling is MAX_BUFFER_CHARS plus one event, and that is stated
+  // here rather than pretended away.
+  //
+  // What this does to a resuming client is what the count bound has always done
+  // to one, only sooner: the head of the ring moves, and events that fell off
+  // it are gone for anybody who had not been sent them yet. That is the
+  // existing bargain for a too-old Last-Event-ID — handleSse replays whatever
+  // is still held and the client's `lastSeq` steps forward over the gap — and
+  // the byte bound deliberately reuses it rather than inventing a second answer.
+  // The difference worth knowing is that the head can now move in jumps rather
+  // than one entry at a time; resumeSse's per-pass snapshot is what makes that
+  // safe for a replay already in flight.
+  let drop = 0;
+  let freed = 0;
+  while (drop < events.length - 1
+    && (events.length - drop > MAX_BUFFER || bufferedChars - freed > MAX_BUFFER_CHARS)) {
+    freed += events[drop][CHARS];
+    drop++;
+  }
+  if (drop > 0) {
+    events.splice(0, drop);
+    bufferedChars -= freed;
+  }
 
   // Does this event reach the log at all? Not on a replay (it came from
   // there), not when the hook told us another deck owns this session's log,
@@ -2068,7 +3199,52 @@ function pushEvent(raw, source, opts = {}) {
   // — which runs before the listener exists and never broadcasts — paid one
   // for every line of a log that rotates at 50MB. An event this deck is not
   // logging is still broadcast, so a subscriber alone is reason enough.
-  const json = (sseClients.size > 0 || persisting) ? JSON.stringify(evt) : null;
+  //
+  // Contained, because this line was fatal. `JSON.stringify` walks a value
+  // recursively while `JSON.parse` does not, and the gap between the two is
+  // enormous: measured on Node 22.14, parse accepts a body nested 4,194,303
+  // deep and stringify gives up on the result at 4,021. So a payload in that
+  // window parses cleanly and then throws `RangeError: Maximum call stack size
+  // exceeded` out of here — and there is no promise on this path for the
+  // route's `guard` to catch, because pushEvent is reached from inside a raw
+  // `req.on("end")` listener. It was an uncaughtException, and Node's answer to
+  // those is to exit. Measured against the real server: one POST of 24,378
+  // bytes, nested 4,050 deep, to the credential-free `/api/event` — a
+  // two-hundredth of the 5,000,000-character ingest cap — and the deck was
+  // gone, with nothing on the socket to tell the poster why.
+  //
+  // The payload leaves the ring, not just this string, and that is the point.
+  // `events.push` above already took the envelope, and a value nothing can
+  // serialize is a value no reader can ever deliver: every `Last-Event-ID`
+  // resume that replays it and every `GET /api/events` that writes it would
+  // meet the same throw for as long as it stayed in the buffer, so one small
+  // POST would poison both routes for the life of the entry. The envelope
+  // therefore keeps its `seq` and loses its payload — the same replacement
+  // envelopeJson makes for a reader, made once at the write instead of on every
+  // read, and the same bargain about `seq`: a caller paging with `?since=`
+  // walks past the hole rather than asking forever for what it cannot be given.
+  //
+  // Admitted as a stub rather than refused at ingest with a 400, deliberately.
+  // Three of pushEvent's four callers have no HTTP peer to answer — Codex
+  // rollout lines read off disk, the boot replay of events.jsonl, the synthetic
+  // events the transcript scanners emit — so the containment has to live here
+  // whatever the ingest route does, and a 400 on top would be a second
+  // mechanism for a case this one already covers. It would also have to be paid
+  // for: knowing a payload will not serialize means serializing it, which is
+  // the second stringify per event on the hottest path in the process that the
+  // paragraph above exists to have removed. The reason goes to stderr and not
+  // to the wire, under the rule sendInternalError explains.
+  let json = null;
+  if (sseClients.size > 0 || persisting) {
+    try {
+      json = JSON.stringify(evt);
+    } catch (err) {
+      console.error(`${PRODUCT}: event ${seq} could not be serialized:`, err);
+      evt.payload = null;
+      evt.unserializable = true;
+      json = JSON.stringify(evt);
+    }
+  }
 
   if (sseClients.size > 0) {
     const line = `id: ${seq}\nevent: hook\ndata: ${json}\n\n`;
@@ -2109,17 +3285,98 @@ function pushEvent(raw, source, opts = {}) {
   if (source === "hook" && !opts.replay) {
     if (raw && raw.provider === "codex") {
       maybeResolveCodex(raw);
-    } else {
+    } else if (!raw?.transcript_path || isClaudeTranscriptPath(raw.transcript_path)) {
+      // The gate is here, once, rather than repeated in the four scanners
+      // below it: this is the single door a caller-chosen path comes through,
+      // and all four read the same field off the same payload. A payload with
+      // no transcript_path at all still goes through — every one of them
+      // early-returns without it, and Codex hooks never send one — so the
+      // ordinary event costs nothing but the absent-field test.
       maybeResolveModel(raw);
       maybeResolveUsage(raw);
       maybeResolveContext(raw);
       maybeResolveSessionName(raw);
+    } else {
+      noteRefusedTranscript(raw.transcript_path);
     }
   }
 
   return evt;
 }
 
+/**
+ * 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` writes after truncating, with
+ *     `cwd: ""`. It is not a session event; it is the instruction that makes the
+ *     reducer forget everything before it. 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) {
+  if (!workspace || typeof workspace !== "string") return () => true;
+  const bySession = new Map();
+  return 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;
+    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;
+  };
+}
+
 /**
  * Read the log back into the ring buffer at boot.
  *
@@ -2143,18 +3400,37 @@ function pushEvent(raw, source, opts = {}) {
  * 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. 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.
  */
-async function replayLog(filePath) {
+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;
     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++;
       }
@@ -2179,6 +3455,109 @@ function send(res, status, body, headers = {}) {
   res.end(typeof body === "string" ? body : JSON.stringify(body));
 }
 
+/**
+ * Serialize one envelope, or a stub standing in for it.
+ *
+ * `JSON.stringify` throws on more than size. V8 walks a value recursively, so a
+ * payload nested about five thousand deep overflows the C++ stack and comes
+ * back as `RangeError: Maximum call stack size exceeded` — and a 36 KB POST to
+ * the open ingest route is enough to put one of those in the ring, measured on
+ * Node 22.14. Letting that throw escape would truncate the array mid-write and
+ * leave every later read of that ring answering with invalid JSON for as long
+ * as the event survives, which is a 36 KB way to poison a route permanently.
+ *
+ * So the envelope is replaced rather than dropped, and it keeps its `seq`: a
+ * caller paging with `?since=` still walks past it, instead of asking again for
+ * a hole it can never be given — the same bargain resumeSse makes about the
+ * events it cannot deliver. The reason is written to stderr and not to the
+ * wire, under the rule sendInternalError explains: this body is readable by a
+ * DNS-rebound page and error detail is not.
+ */
+function envelopeJson(evt) {
+  try {
+    // `JSON.stringify(undefined)` is undefined, not a string, and inside an
+    // array literal that would be the text "undefined" — which is not JSON.
+    // `JSON.stringify([undefined])` says "null"; so does this.
+    return JSON.stringify(evt) ?? "null";
+  } catch (err) {
+    console.error(`${PRODUCT}: event ${evt?.seq} could not be serialized:`, err);
+    // Every field here is read defensively and typed to a primitive, because
+    // this is the path that must not throw twice: the status line has gone out
+    // and a second failure would leave the caller a truncated array.
+    return JSON.stringify({
+      seq: Number(evt?.seq) || 0,
+      epoch: typeof evt?.epoch === "string" ? evt.epoch : SEQ_EPOCH,
+      receivedAt: Number(evt?.receivedAt) || 0,
+      source: typeof evt?.source === "string" ? evt.source : "unknown",
+      payload: null,
+      unserializable: true,
+    });
+  }
+}
+
+/**
+ * Answer with a JSON array without ever holding it as one string.
+ *
+ * `send` finishes a response by handing the whole body to a single
+ * `JSON.stringify`, which for every other route is a few hundred bytes and for
+ * `GET /api/events` is the entire ring buffer. V8 will not build a string
+ * longer than `2^29 - 24` characters, so past 536,870,888 characters of
+ * serialised envelopes that call throws `RangeError: Invalid string length`
+ * straight out of the request listener — and there, as requestUrl and `guard`
+ * both say in their own words, nothing catches it and the worker exits.
+ * Measured on Node 22.14 / macOS: 112 posts of 4,900,061 characters, which
+ * `POST /api/event` accepts from anyone with no credential at all, then one
+ * plain unauthenticated GET, and the deck was gone — SSE stream, hook ingest
+ * and event log with it. 112 events is a twentieth of MAX_BUFFER, so this is
+ * not an exotic ring: a deck watching sessions whose Read and Bash responses
+ * are "routinely a good fraction of" the five-million-character ingest cap
+ * reaches it on its own at an average of 268 KB an event.
+ *
+ * Writing the array element by element removes the ceiling rather than raising
+ * it. One envelope's worth of string exists at a time, so the limit applies per
+ * envelope — and ingest caps an envelope at a hundredth of it — and the peak
+ * cost is the ring plus one event instead of the ring plus a contiguous copy of
+ * itself, which is the quieter half of the same bug: a 400 MB ring used to need
+ * 800 MB and a synchronous stall on a route that feels free on a quiet deck.
+ * This is the shape resumeSse already uses for the SSE replay, for the same
+ * reason, and it borrows the same writeResume, so a caller that stops reading
+ * is held at MAX_CLIENT_BUFFER_BYTES here too rather than having the whole ring
+ * queued in userland on its behalf.
+ *
+ * `items` must be a snapshot the caller owns — eventsSince returns one, `filter`
+ * always allocating — because each await lets pushEvent splice the head off the
+ * live ring, and iterating that while it is spliced skips entries.
+ *
+ * No Content-Length: it is not knowable without building the string this exists
+ * to avoid, so the answer is chunked. HTTP/1.1 requires nothing more and every
+ * consumer reads to EOF.
+ *
+ * Exported so the one property that matters can be asserted directly, on a stub
+ * rather than through a socket — the same reason queuedBytes is. "Never builds
+ * the whole array as one string" is invisible from outside a real response,
+ * which is how it went unnoticed here for as long as it did.
+ */
+export async function writeJsonArray(res, items) {
+  res.writeHead(200, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store",
+  });
+  let frame = "[";
+  for (const item of items) {
+    if (res.destroyed) return;
+    if (!await writeResume(res, frame + envelopeJson(item))) {
+      // Stalled past REPLAY_DRAIN_MS with the cap full. Nothing useful can be
+      // said in-band — the status line went out long ago and the array is half
+      // written — so hang up, exactly as the replay does.
+      try { res.destroy(); } catch {}
+      return;
+    }
+    frame = ",";
+  }
+  if (res.destroyed) return;
+  res.end(frame === "[" ? "[]" : "]");
+}
+
 async function serveStatic(req, res, url) {
   // Strip leading slash, default to index.html
   let rel = url.pathname.replace(/^\/+/, "");
@@ -2279,15 +3658,37 @@ function handleEventIngest(req, res, persist = true) {
     let parsed;
     try { parsed = JSON.parse(body); }
     catch { return send(res, 400, { error: "invalid json" }); }
-    noteLogWriter(parsed, persist);
-    const evt = pushEvent(parsed, "hook", { persist });
-    send(res, 200, { ok: true, seq: evt.seq });
+    // Everything past the parse is inside one net, because this listener is the
+    // one place in the route table `guard` cannot reach. The route does wrap the
+    // call — `guard(handleEventIngest(req, res, …), res)` — but this function
+    // returns undefined and hands its work to a listener the event loop calls
+    // later, so `guard` has nothing to attach to and a synchronous throw in here
+    // is an uncaughtException: the whole deck, for one POST. That is exactly
+    // what the serialization inside pushEvent was until it was contained at the
+    // line itself, and this catch is what stops the next thing added below from
+    // costing a process the same way. sendInternalError puts the reason on
+    // stderr and a bare 500 on the wire, and does nothing but end the response
+    // if the status line has already gone out.
+    try {
+      noteLogWriter(parsed, persist);
+      const evt = pushEvent(parsed, "hook", { persist });
+      send(res, 200, { ok: true, seq: evt.seq });
+    } catch (err) {
+      sendInternalError(res, err);
+    }
   });
   // Guarded for the same reason `end` is, and more sharply: destroying the
   // request above is itself what raises this, and answering a second time on a
   // response already sent throws ERR_HTTP_HEADERS_SENT out of an error handler,
-  // where nothing is waiting to catch it.
-  req.on("error", () => { if (!refused) send(res, 400, { error: "bad request" }); });
+  // where nothing is waiting to catch it. `refused` covers the 413 that
+  // destroyed the request; `headersSent` covers the other half of that
+  // sentence, an error arriving after `end` has already answered. That half
+  // resisted every attempt to drive it from a socket — once `end` has fired the
+  // message is complete and the failure goes to the socket rather than to the
+  // request — so it carries no test, and is guarded anyway on the strength of
+  // the hazard the sentence above already names: one condition against an
+  // uncaughtException, if it turns out to be reachable at all.
+  req.on("error", () => { if (!refused && !res.headersSent) send(res, 400, { error: "bad request" }); });
 }
 
 function handleSse(req, res) {
@@ -2302,6 +3703,16 @@ function handleSse(req, res) {
   // A stale or absent id replays the whole ring, and so does a malformed one:
   // Number("nonsense") is NaN, every `seq <= NaN` is false, and the catch-up
   // loop below would rather compare against a number.
+  //
+  // An id OLDER than the ring's oldest event is a stale id and takes exactly
+  // that path — nothing special-cases it, and #625 deliberately did not add a
+  // second answer when it gave the ring a byte budget. Every `e.seq <=
+  // sentThrough` test simply fails, so the client is handed everything still
+  // held, contiguously, and the sentinel behind it; the events that were
+  // evicted are missing from its HISTORY, never from its stream. The reducer's
+  // guard is `env.seq <= state.lastSeq`, so the gap costs it a step forward and
+  // nothing else. What the byte budget changed is how often and how far the
+  // head moves, not what happens to a client that lands behind it.
   const asked = Number(req.headers["last-event-id"] ?? 0);
   const lastId = Number.isFinite(asked) ? asked : 0;
 
@@ -2339,6 +3750,16 @@ async function resumeSse(req, res, lastId) {
     // `events` off, and iterating an array being spliced from the front skips
     // entries. Events evicted that way are gone for this client, which is the
     // same bargain every resume against a rotated ring already makes.
+    //
+    // The snapshot earns more since #625 gave the ring a byte budget as well as
+    // a count. Under the count alone the head moved one entry per push; under
+    // the budget a single 5 MB event can evict hundreds at once. A replay
+    // already walking this array would have skipped every one of them — but the
+    // snapshot holds its own references, so the pass in flight still delivers
+    // what it was given and only a LATER pass sees the shortened ring. It also
+    // means a slow resumer pins one ring's worth of envelopes for as long as its
+    // pass lasts, which the budget bounds too: that pin used to be unbounded for
+    // the same reason the ring was.
     const batch = events.slice();
     for (const e of batch) {
       if (e.seq <= sentThrough) continue;
@@ -2351,7 +3772,19 @@ async function resumeSse(req, res, lastId) {
       // wall-clock visibility gates and yields the "nodes appear then vanish"
       // symptom on refresh.
       const tagged = { ...e, replay: true };
-      if (!await writeResume(res, `id: ${e.seq}\nevent: hook\ndata: ${JSON.stringify(tagged)}\n\n`)) {
+      // Through envelopeJson for the reason writeJsonArray is: the ring may be
+      // holding an envelope `JSON.stringify` cannot walk. pushEvent takes the
+      // payload out of every envelope it serializes, but it serializes nothing
+      // when there is no subscriber and no log — which is precisely the deck a
+      // browser is about to connect to — so the first read of such an entry can
+      // still be this one. Uncontained it rejected into handleSse's `.catch`,
+      // which drops the client; the browser reconnects on its own 1.5s timer,
+      // replays the same entry, and is dropped again, so a single small POST
+      // kept the canvas from ever loading. The stub loses the `replay` tag and
+      // nothing turns on that: it carries no payload for the reducer to act on,
+      // and the client's own replay gate runs until the `replay-end` sentinel
+      // regardless of what any one envelope says.
+      if (!await writeResume(res, `id: ${e.seq}\nevent: hook\ndata: ${envelopeJson(tagged)}\n\n`)) {
         return dropSse(res);
       }
       sentThrough = e.seq;
@@ -2721,25 +4154,6 @@ async function handleCswapAutoAction(req, res) {
   send(res, result.ok ? 200 : 400, result);
 }
 
-async function handleSoundHook(req, res) {
-  const { soundHookStatus } = await import(
-    pathToFileURL(join(PKG_ROOT, "src/server/sound-hook.mjs")).href
-  );
-  send(res, 200, await soundHookStatus());
-}
-
-async function handleSoundHookSet(req, res) {
-  const { setSoundHook, restoreParkedSoundHooks } = await import(
-    pathToFileURL(join(PKG_ROOT, "src/server/sound-hook.mjs")).href
-  );
-  const body = await readBody(req).catch(() => null);
-  let parsed = null;
-  try { parsed = JSON.parse(body ?? ""); } catch { /* handled below */ }
-  if (!parsed || typeof parsed !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
-  if (parsed.action === "restore") return send(res, 200, await restoreParkedSoundHooks());
-  send(res, 200, await setSoundHook(parsed.enabled === true));
-}
-
 // The tree this deck was told to capture, "" when it captures the whole
 // machine. Set by startServer and never changed afterwards.
 //
@@ -2784,17 +4198,193 @@ let _providers = { claude: true, codex: true };
  * the events log before publishing it: what goes in the discovery file is read
  * by other processes that cannot reconstruct the context it was written in.
  *
- * Symlinks are resolved too, because a process's cwd — which is what both
- * providers report — comes from getcwd() and has none left in it. Without this,
- * `--workspace /tmp/proj` on a Mac is scoped to /tmp/proj while every session
- * inside it reports /private/tmp/proj, and the deck stays empty. A path that
- * does not exist yet keeps its resolved form rather than failing: scoping a deck
- * to a directory you are about to create is not an error.
+ * Symlinks are resolved too, so that `--workspace /tmp/proj` on a Mac is not
+ * scoped to /tmp/proj while every session inside it reports /private/tmp/proj,
+ * leaving the deck empty. A path that does not exist yet keeps its resolved form
+ * rather than failing: scoping a deck to a directory you are about to create is
+ * not an error.
+ *
+ * That resolution is only half the rule. Canonicalising the flag means nothing
+ * unless the cwd it is compared against is canonicalised the same way, and that
+ * is a separate job on each capture path: hook.js does it with normPath, and the
+ * rollout watcher does it with canonicalCwd below. This comment used to claim
+ * the second half came for free — that "a process's cwd comes from getcwd() and
+ * has none left in it" — which is true on POSIX and false on Windows. See
+ * canonicalCwd.
+ *
+ * WHICH REALPATH, AND WHY IT IS `.native` AT ALL THREE SITES. Node ships two
+ * implementations with different Windows behaviour, and picking one per site is
+ * how the flag and the two cwd paths end up meaning different things again:
+ *
+ *   fs.realpathSync / fs.realpath  a JavaScript lstat-and-readlink walk. It
+ *                                  resolves symlinks and junctions and NOTHING
+ *                                  else — a DOS 8.3 short component survives it
+ *                                  untouched.
+ *   …Sync.native / …native / the   uv_fs_realpath, which on Windows is
+ *   fs/promises realpath           GetFinalPathNameByHandleW: symlinks and
+ *                                  junctions, the UNC form of a mapped drive,
+ *                                  the LONG form of an 8.3 short name, and the
+ *                                  on-disk case of every component.
+ *
+ * The long form is the canonical one, and not by preference: it is the only
+ * spelling that is a fixed point. Short names are an alias for the same
+ * directory exactly as a junction is, they cannot be derived back from the long
+ * form (8.3 generation can be disabled per volume), and they are not a corner
+ * case a test invented — `%TEMP%` under a shortened profile directory answers
+ * with one, which is what every GitHub Windows runner has. It is also already
+ * this codebase's answer: persistAuth in src/server/codex-auth.mjs resolves
+ * through the fs/promises realpath, i.e. this one.
+ *
+ * So all three sites name `.native` explicitly rather than one of them reaching
+ * for whichever realpath came to hand. Being explicit is the point — the reason
+ * this had to be said twice is that fs/promises' realpath IS the native one
+ * while its sync namesake is not, an equivalence nothing documents and no reader
+ * should have to know.
  */
 export function canonicalWorkspace(raw) {
   if (typeof raw !== "string" || raw.trim() === "") return "";
   const abs = resolve(raw);
-  try { return realpathSync(abs); } catch { return abs; }
+  try { return realpathSync.native(abs); } catch { return abs; }
+}
+
+// The async half of the rule canonicalWorkspace states above, named the same way
+// it is: fs.realpath.native is the documented callback form of uv_fs_realpath,
+// and promisifying it says which realpath this is at the point of use. The
+// fs/promises realpath is the same call and would have read as if it were the
+// JavaScript one.
+const realpathNative = promisify(realpathCb.native);
+
+/**
+ * The one spelling of the directory a Codex session says it is running in —
+ * hook.js's normPath, for the capture path that never goes through the hook.
+ *
+ * `--workspace` is canonicalised above before anything compares against it, and
+ * the Claude side canonicalises the session's cwd to match: hook.js runs every
+ * incoming cwd through normPath (resolve + realpath) before asking
+ * capturesSession. The Codex side compared the rollout header's `cwd` raw, and
+ * the comment above said that was safe because a cwd comes from getcwd(), which
+ * has already resolved every link.
+ *
+ * That is true of getcwd(3) and not true of Windows. There the current directory
+ * is stored as the string it was set with, and GetCurrentDirectoryW — what
+ * Rust's std::env::current_dir() behind Codex calls — hands that string back
+ * without resolving a junction, a `subst` drive or a mapped network drive.
+ * realpath does resolve them, and on a mapped drive goes further and returns the
+ * UNC form, because libuv asks GetFinalPathNameByHandleW. So a deck started as
+ * `--workspace Z:\proj` scoped itself to `\\server\share\proj`, the Claude
+ * session in that tree reported `Z:\proj` and was realpath'd into the workspace
+ * and drawn, and the Codex session beside it reported `Z:\proj` in its rollout
+ * header, was compared raw, and silently never appeared — no error printed
+ * anywhere, the banner still claiming the rollout watcher was running. The same
+ * asymmetry runs in reverse for a user who passes the resolved path and works
+ * through the junction. The log election went wrong with it: writesCodexLog
+ * models the OTHER decks' capture with this same predicate against their
+ * published (canonical) workspaces, so it was picking the wrong group.
+ *
+ * Done here, at the one read of the header, rather than inside
+ * codexCwdInWorkspace: the result is cached in codexFileState for the life of
+ * the file, so it costs one realpath per rollout instead of one per tick, and it
+ * leaves the predicate the pure string function that lets it be pinned against
+ * hook.js's copy in a test.
+ *
+ * `.native`, for the reason canonicalWorkspace sets out at length: three sites
+ * canonicalise a path against each other and all three must fold the same way,
+ * 8.3 short names included. Case IS canonicalised as a side effect — that is
+ * what GetFinalPathNameByHandleW and realpath(3) on a case-insensitive volume
+ * return — but nothing here DEPENDS on it: the two predicates still fold case
+ * per-platform themselves, which is the only place that decision can stay
+ * correct on Linux, where /srv/Proj and /srv/proj are two real directories and
+ * realpath quite rightly keeps them apart.
+ *
+ * Async, unlike canonicalWorkspace, because of where each one runs.
+ * canonicalWorkspace runs once in bin/deck.js before the server exists, so
+ * blocking there costs nothing. This runs inside the watcher's 1.5s tick, in the
+ * live event loop, against a path a rollout recorded some time ago — which on
+ * the very platform this exists for is quite likely to name a mapped drive that
+ * is no longer connected, and a synchronous realpath on one of those blocks the
+ * whole dashboard until SMB times out.
+ *
+ * A cwd that no longer resolves keeps its resolved form, exactly as the flag
+ * does: a deleted directory or a disconnected drive is not a reason to drop a
+ * session the deck can still draw, and the resolved string is the best answer
+ * available — for a rollout recorded in the tree the deck is scoped to and never
+ * moved, it is also the right one. Anything that is not a non-empty string is
+ * null, which is what readCodexHeader returned before and what both copies of
+ * the predicate read as "this session never said where it runs".
+ */
+export async function canonicalCwd(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  const abs = resolve(raw);
+  try { return await realpathNative(abs); } catch { return abs; }
+}
+
+/**
+ * The deck's one irreversible action: empty the ring, and empty the log — but
+ * only the log this deck is the one writing.
+ *
+ * The gate is the whole of #698. `truncate(persistPath, 0)` ran from whichever
+ * deck was asked, and `persistPath` is one file several decks share by default,
+ * so Clear on a deck scoped to a single tree deleted the machine-wide deck's
+ * entire history while its canvas showed no change at all. Ownership is
+ * electWriters, the election that already decides which of those decks appends a
+ * line, so nothing new gets to disagree with it: the deck that fills the file is
+ * the deck that may empty it, and a deck that writes nothing to it cannot
+ * destroy it. See logSharing.
+ *
+ * A deck that does not own the log still clears its own canvas — that is what
+ * the user pressed, and the ring is this deck's alone — and says which deck's
+ * file it declined to touch, so the answer is a fact the UI can show rather than
+ * a silent partial success. The dialog asked `GET /api/clear` before the press
+ * and has already said the same thing in words.
+ *
+ * The `__clear` marker is broadcast and NOT persisted. It never belonged on
+ * disk: replaying an empty log and then a marker that empties it produces the
+ * same empty state, and appending it was how a deck that writes nothing else to
+ * the shared file still left 134 bytes in it — the reproduction's whole
+ * remainder. `{ persist: false }` is the same flag the hook sets on the decks it
+ * did not elect.
+ */
+async function handleClear(res) {
+  const sharing = await logSharing();
+  // Not `events.length = 0`: the ring is measured by a running total now, and
+  // emptying the array without the total leaves a debt that never clears. See
+  // clearEventBuffer.
+  clearEventBuffer();
+  if (sharing.path && sharing.mine) truncate(sharing.path, 0).catch(() => {});
+  // Drop the caches that gate an emit on "has this changed", because the
+  // client is about to forget what they are comparing against: __clear makes
+  // the reducer return a fresh state, so every session's name and every
+  // subagent's model label go with it. maybeResolveSessionName then computes
+  // the same signature, takes its early return, and emits nothing — so the
+  // card falls back to cwd/prompt for the rest of that session while the
+  // server is sitting on the name.
+  //
+  // The root model survives without help because pushEvent stamps
+  // `raw.model` on every payload; there is no equivalent stamp for the name
+  // or for a subagent's model, which is why those two are listed and the
+  // rest of the per-session state is not.
+  //
+  // The rule, for the next cache that gates an emit: anything answering
+  // "has this changed" has to appear in BOTH places that mean the client no
+  // longer has it — here, and in forgetSession.
+  nameBySession.clear();
+  modelBySession.clear();
+  // The read stamps go with them. Clearing only the signatures would leave
+  // the next hook event inside MODEL_READ_THROTTLE_MS, so the transcript
+  // would not be re-read at all and the name would stay missing until the
+  // throttle expired — a clear followed by a keystroke is exactly when a
+  // user is watching.
+  lastNameReadAt.clear();
+  modelLastReadAt.clear();
+  pushEvent({ hook_event_name: "__clear", cwd: "" }, "internal", { persist: false });
+  return send(res, 200, {
+    ok: true,
+    log: !sharing.path ? "none" : sharing.mine ? "cleared" : "kept",
+    path: sharing.path,
+    decks: sharing.decks,
+    mine: sharing.mine,
+    owner: sharing.owner ? { port: sharing.owner.port } : null,
+  });
 }
 
 function handleHealth(_req, res) {
@@ -2916,8 +4506,8 @@ export function requestUrl(rawUrl) {
 // secrets are. GET /api/events is the whole ring buffer: prompt text, the Bash
 // command lines the agent ran, the paths and contents it wrote, the contents of
 // every file it read back. /api/claude-accounts names the accounts,
-// /api/claude-accounts/login carries a live OAuth authorize URL, /api/sound-hook
-// the user's own hook command lines, /api/health the absolute workspace path.
+// /api/claude-accounts/login carries a live OAuth authorize URL, /api/health the
+// absolute workspace path.
 //
 // So the Host check runs for every method now. What it asks is only the
 // rebinding question — did this request arrive addressed to a name that can
@@ -3044,6 +4634,36 @@ function originMatchesHost(origin, host) {
 // worst a caller does with it is draw a session on the canvas that is not
 // there. See the handshake in hook/hook.js for the authentication that does
 // run on this path, which is the deck proving itself to the hook.
+//
+// That "destroys nothing" is a claim about the whole ingest path and not only
+// about this line, and #625 is what it cost the day it stopped being true: the
+// ring buffer bounded the events it kept by count and not by size, so about 430
+// posts of a maximum-size body — from a local process holding no credential,
+// which is exactly what this set permits — reached the heap limit and aborted
+// the process. Whatever else is added to this set, the same question has to be
+// asked of it: what does an unbounded number of these accumulate in? For this
+// one the answer is now MAX_BUFFER_CHARS.
+//
+// #674 is the same question asked a second time, and the answer was not in the
+// ring at all. The body of this POST carries `transcript_path`, and everything
+// the deck learns about a session's model, cost, name and context is read out
+// of the file it names — so the credential-free route does not stop at the ring
+// buffer, it reaches the filesystem, with a path the caller chose. It was read
+// by allocating the whole file: 700 MB named in one POST took a fresh deck from
+// 52 MB RSS to 753 MB and answered `200 {"ok":true,"seq":1}`, and because a
+// file with no newline in it could never advance the scan cursor, every later
+// POST paid it again. What bounds it now is three things, in the order they
+// were reached for: `isClaudeTranscriptPath` means an unrecognised path is not
+// opened at all, so the caller who holds no credential can name nothing;
+// MAX_SCAN_CHUNK means no single read allocates more than 8 MiB whatever it is
+// pointed at; MAX_SCAN_BYTES_PER_PASS means no single POST walks more than 256
+// MiB of a file.
+//
+// So the claim above holds again, with its scope written out: the worst a
+// caller does with this route is draw a session on the canvas that is not
+// there. It cannot make the deck open a file of its choosing, and it cannot
+// make the deck's memory a function of anything but the two constants named
+// here.
 const OPEN_MUTATIONS = new Set(["/api/event"]);
 
 // Constant-time comparison of two secrets, and a length test that is not.
@@ -3299,7 +4919,11 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
   if (persist) {
     persistPath = resolve(persist);
     try { await mkdir(pdirname(persistPath), { recursive: true }); } catch {}
-    const replayed = await replayLog(persistPath);
+    // `_workspace`, not `workspace`: the field has just been normalised on the
+    // line above, and the replay has to answer the same question the live paths
+    // answer with the same string. Passed rather than read off the module scope
+    // so replayLog states what it depends on. See replayScope.
+    const replayed = await replayLog(persistPath, _workspace);
     if (replayed > 0) {
       // Don't broadcast replays as live; SSE clients catch up via Last-Event-ID
       // already. Just keep the buffer + seq counter primed.
@@ -3311,7 +4935,7 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
   // background quota poll hit a network error. Answer the request instead.
   const guard = (p, res) => Promise.resolve(p).catch(err => sendInternalError(res, err));
 
-  const server = createServer((req, res) => {
+  const route = (req, res) => {
     const url = requestUrl(req.url);
     // Unparseable request target. Nothing below can route it, and throwing here
     // would be an uncaughtException inside the listener — i.e. the whole deck.
@@ -3375,50 +4999,56 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "POST" && url.pathname === "/api/claude-accounts/switch") return guard(handleClaudeAccountSwitch(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/claude-accounts/login")  return guard(handleAccountLoginState(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/claude-accounts/admin")  return guard(handleClaudeAccountAdmin(req, res), res);
-    if (req.method === "GET"  && url.pathname === "/api/sound-hook") return guard(handleSoundHook(req, res), res);
-    if (req.method === "POST" && url.pathname === "/api/sound-hook") return guard(handleSoundHookSet(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/cswap-auto")  return guard(handleCswapAuto(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/cswap-auto")  return guard(handleCswapAutoAction(req, res), res);
 
+    // Through writeJsonArray rather than `send`, and through `guard` like every
+    // route above it: this is the one answer whose size is the ring's size, and
+    // `send` would build all of it as a single string. See writeJsonArray.
     if (req.method === "GET" && url.pathname === "/api/events") {
-      return send(res, 200, eventsSince(url.searchParams.get("since") ?? 0));
+      return guard(writeJsonArray(res, eventsSince(url.searchParams.get("since") ?? 0)), res);
     }
 
-    // POST /api/clear — wipe in-memory buffer + persistence file (UI reset)
-    if (req.method === "POST" && url.pathname === "/api/clear") {
-      events.length = 0;
-      if (persistPath) truncate(persistPath, 0).catch(() => {});
-      // Drop the caches that gate an emit on "has this changed", because the
-      // client is about to forget what they are comparing against: __clear makes
-      // the reducer return a fresh state, so every session's name and every
-      // subagent's model label go with it. maybeResolveSessionName then computes
-      // the same signature, takes its early return, and emits nothing — so the
-      // card falls back to cwd/prompt for the rest of that session while the
-      // server is sitting on the name.
-      //
-      // The root model survives without help because pushEvent stamps
-      // `raw.model` on every payload; there is no equivalent stamp for the name
-      // or for a subagent's model, which is why those two are listed and the
-      // rest of the per-session state is not.
-      //
-      // The rule, for the next cache that gates an emit: anything answering
-      // "has this changed" has to appear in BOTH places that mean the client no
-      // longer has it — here, and in forgetSession.
-      nameBySession.clear();
-      modelBySession.clear();
-      // The read stamps go with them. Clearing only the signatures would leave
-      // the next hook event inside MODEL_READ_THROTTLE_MS, so the transcript
-      // would not be re-read at all and the name would stay missing until the
-      // throttle expired — a clear followed by a keystroke is exactly when a
-      // user is watching.
-      lastNameReadAt.clear();
-      modelLastReadAt.clear();
-      pushEvent({ hook_event_name: "__clear", cwd: "" }, "internal");
-      return send(res, 200, { ok: true });
+    // GET /api/clear — what a POST to this path would do, and to whose log.
+    // Asked by the confirmation dialog as it opens, on demand rather than on a
+    // timer, for the reason /api/system/processes is: the answer costs a
+    // directory read, changes only when a deck starts or stops, and matters at
+    // exactly one moment. See logSharing.
+    if (req.method === "GET" && url.pathname === "/api/clear") {
+      return guard(logSharing().then(s => send(res, 200, {
+        ok: true, path: s.path, decks: s.decks, mine: s.mine,
+        owner: s.owner ? { port: s.owner.port } : null,
+      })), res);
     }
 
+    // POST /api/clear — wipe in-memory buffer + persistence file (UI reset)
+    if (req.method === "POST" && url.pathname === "/api/clear") return guard(handleClear(res), res);
+
     if (req.method === "GET") return serveStatic(req, res, url);
     send(res, 405, { error: "method not allowed" });
+  };
+
+  // `guard` covers the routes dispatched as promises. This covers the rest of
+  // them — and, more to the point, covers a route added later by someone who
+  // did not think to reach for `guard` because their handler looked
+  // synchronous and cheap. That was the whole of #626: `GET /api/events` read
+  // as a one-liner, and it was a one-liner that ended the process, because a
+  // synchronous throw inside the listener is an uncaughtException and Node's
+  // answer to those is to exit. `/api/system` and `/api/clear` are called the
+  // same bare way and are covered here for free.
+  //
+  // Deliberately the last line of defence and not the first: a 500 with the
+  // detail on stderr is a worse answer than a handler that knew what went
+  // wrong, and much better than a dead deck. sendInternalError already knows
+  // to keep the detail off the wire and to do nothing but end the response
+  // when the headers have gone out — which is the case that matters for a
+  // streamed answer, where the throw can arrive after the status line.
+  const server = createServer((req, res) => {
+    try {
+      route(req, res);
+    } catch (err) {
+      sendInternalError(res, err);
+    }
   });
 
   // Try requested port first, then up to 10 random ports from portRange.