ccdeck 3.22.14 → 3.23.0

package/src/server/index.mjs

@@ -4,9 +4,9 @@
 // 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 { readFile, stat, mkdir, open, readdir, unlink } from "node:fs/promises";
 import { existsSync, readFileSync, realpath as realpathCb, realpathSync } from "node:fs";
-import { extname, join, resolve, sep, dirname as pdirname } from "node:path";
+import { basename, extname, join, resolve, sep, dirname as pdirname } from "node:path";
 import { homedir, networkInterfaces } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname } from "node:path";
@@ -30,16 +30,18 @@ import { createActivity } from "./activity.mjs";
 // What a session is producing between its tool calls — the 16.5% of measured
 // time the hooks cannot see. See output-watch.mjs.
 import { createOutputWatch } from "./output-watch.mjs";
+// Claude Code's "※ recap:" line — see session-recap.mjs.
+import { RECAP_MARK, foldRecapLine } from "./session-recap.mjs";
 import { AWAY_BOOT_GRACE_MS, AWAY_RECHECK_MS, AWAY_TICK_MS, awayGate, awayUpdateStep } from "./auto-update.mjs";
 import { createPresence } from "./presence.mjs";
-import { DEFAULTS as PREF_DEFAULTS, cleanAlias, isAliasKey, lanEnabled, notificationsOn, notificationsVetoed, publicPrefs, readPrefs, writePrefs } from "./deck-prefs.mjs";
+import { DEFAULTS as PREF_DEFAULTS, cleanAlias, isAliasKey, lanEnabled, notificationsOn, notificationsVetoed, publicPrefs, readPrefs, updatePrefs, writePrefs } from "./deck-prefs.mjs";
 import { createEngine, defaultName } from "./lan-engine.mjs";
 import { aboutThisDeck } from "./lan-about.mjs";
 import { PROBE_PS, localAliases, reachability, readProbe } from "./lan-reach.mjs";
 import { run } from "./exec.mjs";
 import { notify as osNotify } from "./browser-react.mjs";
 import { invokedName, renameNotice } from "./invoked-as.mjs";
-import { appendLogLine, codexCwdInWorkspace, electWriters, foldsCase, writesCodexLog } from "./log-writer.mjs";
+import { appendFailureStats, appendLogLine, appendsLanded, codexCwdInWorkspace, electWriters, emptyLog, flushAppends, foldsCase, writesCodexLog } from "./log-writer.mjs";
 import { historySnapshot, readProcesses, startSystemMetrics, systemSnapshot } from "./system-metrics.mjs";
 import { linesFromEnd, linesFromStart } from "./log-tail.mjs";
 
@@ -113,7 +115,51 @@ const MIME = {
 // 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
+export const MAX_BUFFER = 2000;     // recent HOOK events kept for late SSE subscribers
+
+/**
+ * The enrichment this deck derives rather than receives, where only the newest
+ * one per session has ever been worth anything.
+ *
+ * These four are last-value-wins STATE, not history: a session's model, its
+ * token usage, its context fill and its name. Replaying an older UsageObserved
+ * on top of a newer one changes nothing a reader can see, which is precisely
+ * why they do not deserve a slot in a window measured in events.
+ *
+ * MEASURED, at one hook event per session every 3s — an ordinary tool-call
+ * cadence, well under every documented cap. Four scanners fire per hook event,
+ * throttled at 2.5s, 2.5s and 4s:
+ *
+ *   sessions=10   posted=60    seq_delta=160    amplification=2.67
+ *   sessions=200  posted=2000  seq_delta=5190   amplification=2.60
+ *
+ * Flat, near enough: every hook event costs about 2.6 ring slots. At 200
+ * sessions the 2000-entry ring held
+ * {"PostToolUse":800,"UsageObserved":800,"ContextObserved":400} and spanned
+ * 9.5 SECONDS — 60% of the resume window spent on state that is superseded
+ * moments later. Close the lid, switch networks, or let a tab sleep for fifteen
+ * seconds, and the Last-Event-ID is older than the ring's head: handleSse
+ * replays what is left and the client steps lastSeq over the gap, so the tool
+ * calls made in those seconds are never drawn and nothing reports the hole.
+ *
+ * `OutputObserved` is deliberately NOT here. It says something landed at a
+ * given moment, which is history — two of them are two events, not one value
+ * twice.
+ */
+const LAST_VALUE_WINS = new Set(["ModelObserved", "UsageObserved", "ContextObserved", "SessionNamed"]);
+
+/**
+ * The ring's array-length backstop, distinct from its event budget.
+ *
+ * MAX_BUFFER now counts hook events only, so the array holds those plus
+ * whatever enrichment is interleaved among them — about 2.6x the budget at the
+ * amplification measured above. This is the ceiling for a ratio nobody has
+ * measured yet: a future scanner, or a cadence that makes enrichment denser
+ * still, must not be able to grow the array without bound. It is not the
+ * working limit and should never be the binding one; MAX_BUFFER_CHARS remains
+ * the memory bound.
+ */
+export const MAX_RING_ENTRIES = MAX_BUFFER * 4;
 
 // 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
@@ -159,6 +205,21 @@ const events = [];                  // ring buffer
 // day only one of them was emptied.
 let bufferedChars = 0;
 
+/**
+ * How many of the ring's entries are HOOK events — what MAX_BUFFER budgets.
+ *
+ * Third of the trio that has to move with `events`, for the same reason
+ * `bufferedChars` does and with the same consequence if it drifts: a count that
+ * names events the array no longer holds evicts against a budget already spent.
+ * See LAST_VALUE_WINS for what it excludes and why, and clearEventBuffer for
+ * the one place all three are emptied.
+ */
+let bufferedHookEvents = 0;
+
+/** Set on the envelopes MAX_BUFFER does not count, so eviction can decrement
+ *  the right total without re-reading a payload it already charged. */
+const ENRICHMENT = Symbol("ring enrichment");
+
 /**
  * What this payload will cost the ring, charged in characters.
  *
@@ -266,6 +327,7 @@ const CHARS = Symbol("ring charge");
 function clearEventBuffer() {
   events.length = 0;
   bufferedChars = 0;
+  bufferedHookEvents = 0;
 }
 
 /**
@@ -284,6 +346,11 @@ function clearEventBuffer() {
 export function eventBufferStats() {
   return {
     events: events.length,
+    // What MAX_BUFFER budgets since #1032, and the only number a resuming
+    // client's window is actually measured in. `events` minus this is the
+    // enrichment riding along; the ratio between them is the amplification that
+    // used to spend the window — 2.6 measured at every session count tried.
+    hookEvents: bufferedHookEvents,
     chars: bufferedChars,
     oldestSeq: events.length > 0 ? events[0].seq : 0,
     newestSeq: events.length > 0 ? events[events.length - 1].seq : 0,
@@ -422,19 +489,82 @@ export async function logSharing() {
 const ROTATE_AT_BYTES = 50 * 1024 * 1024;
 let lastRotateCheckAt = 0;
 let rotateInProgress = false;
-async function maybeRotatePersistFile() {
+/** Bytes handed to appendLogLine since the last time we looked at the file.
+ *
+ *  THE 30-SECOND CLOCK MADE THE THRESHOLD ADVISORY. The stat was throttled to
+ *  once per 30s and this function has one caller — the push path — so the
+ *  overshoot was exactly `30s x the ingest byte rate`, which is unbounded in
+ *  throughput rather than merely loose. Measured, on a log doing 10.5 MB/s:
+ *
+ *    t=6s  log=51393249      <- 50 MB crossed
+ *    t=30s log=306262048
+ *    t=31s log=0  log1=316750478   <- rotation fires, 302 MB, 25s late
+ *
+ *  and at higher rates 1,199 MB and 2,579 MB with ZERO rotations — 51x the
+ *  cap, 604 MB on disk across the two generations for a documented 50 MB.
+ *
+ *  Counting what we hand the appender costs one addition per event and removes
+ *  the dependency on throughput: the check now happens when enough has been
+ *  written to be worth a stat, whatever the clock says. The clock stays as a
+ *  FLOOR for the idle case, where nothing is being written and a periodic look
+ *  is the only way to notice a file that grew by some other route.
+ *
+ *  Deliberately a lower bound on the real file: it counts bytes queued, not
+ *  bytes landed, and it is reset on every look rather than on a successful
+ *  rotation — so a stat that finds the file still under the threshold has
+ *  already paid for itself and does not need to re-count what it just saw. */
+let bytesSinceRotateCheck = 0;
+/** Enough written to be worth a stat, whatever the clock says. A fifth of the
+ *  threshold, so the worst overshoot is bounded at ~20% rather than by rate. */
+const ROTATE_CHECK_EVERY_BYTES = Math.floor(ROTATE_AT_BYTES / 5);
+/** And a floor for the idle case, where nothing is being written and a
+ *  periodic look is the only way to notice a file that grew by some other
+ *  route — another deck appending to a log they share, say. */
+const ROTATE_CHECK_EVERY_MS = 30_000;
+/**
+ * Whether it is worth asking the filesystem how big the log is.
+ *
+ * Pure, and exported, for the reason mayReadAccounts and maySelfPoll are: this
+ * is the rule, and a rule whose only observable failure is a file quietly
+ * reaching gigabytes belongs somewhere a test can point at it. Rotation had no
+ * test of any kind.
+ */
+export function rotateCheckDue({ now, lastCheckAt, bytesSince }) {
+  return now - lastCheckAt >= ROTATE_CHECK_EVERY_MS
+    || bytesSince >= ROTATE_CHECK_EVERY_BYTES;
+}
+
+async function maybeRotatePersistFile(wroteBytes = 0) {
   if (!persistPath) return;
+  bytesSinceRotateCheck += wroteBytes;
   const now = Date.now();
-  // Throttle disk-stat checks to once per 30s.
-  if (now - lastRotateCheckAt < 30_000) return;
+  if (!rotateCheckDue({ now, lastCheckAt: lastRotateCheckAt, bytesSince: bytesSinceRotateCheck })) return;
   lastRotateCheckAt = now;
+  bytesSinceRotateCheck = 0;
   if (rotateInProgress) return;
   rotateInProgress = true;
   try {
     const s = await stat(persistPath).catch(() => null);
     if (!s || s.size < ROTATE_AT_BYTES) return;
+    // ONLY THE DECK THAT WRITES THIS LOG MAY MOVE IT, the same gate `/api/clear`
+    // already keeps and for the same reason. Two decks appending to one log is
+    // explicitly permitted as the fail-safe — log-writer.mjs says "a line
+    // written twice is recoverable" — so both cross 50 MB and both rotate. If
+    // B's stat lands before A's rename, B's `unlink` deletes the archive A has
+    // just made and B's `rename` moves the new, near-empty live file into its
+    // place: one generation of history destroyed by a deck that was only
+    // housekeeping. The append path was made multi-writer safe; this one was
+    // not. Ownership is electWriters, so nothing new gets to disagree with it.
+    const sharing = await logSharing();
+    if (!sharing.mine) return;
     // Roll events.jsonl → events.jsonl.1 (replacing any previous .1).
     const oldPath = persistPath + ".1";
+    // LET THE QUEUE DRAIN FIRST. Appends are ordered behind a promise chain
+    // inside log-writer.mjs and a descriptor opened before the rename completes
+    // into the RENAMED inode, so the line being appended at the moment of a
+    // rotation lands in the archive rather than the live log — measured, a
+    // 24 MB line in events.jsonl.1 and a 65-byte live file. See flushAppends.
+    await flushAppends(persistPath);
     try { await unlink(oldPath); } catch {}
     const { rename } = await import("node:fs/promises");
     await rename(persistPath, oldPath);
@@ -633,6 +763,7 @@ function newTranscriptState() {
     subagentModels: {},
     aiTitle: null,      // newest "ai-title" entry, the session's sentence title
     agentName: null,    // newest "agent-name" entry, the session's short name
+    recap: null,        // newest "away_summary" no later turn retired — session-recap.mjs
     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
@@ -840,6 +971,9 @@ function foldTranscriptLine(state, line) {
   // totals and the context counts, so naming costs no read of its own — see the
   // block above `maybeResolveSessionName` for why that beat a tail read.
   foldSessionNamingLine(state, line);
+  // The recap rides the same pass for the same reason, and costs the ordinary
+  // line two substring tests. See session-recap.mjs.
+  foldRecapLine(state, line);
 
   // Model. Only a line that mentions a model can change it, and parsing the
   // rest is what made the full rescan expensive.
@@ -1476,12 +1610,18 @@ const pendingNameReads = new Set();     // sid currently being read
  *  through a live server" — which stated a test contract no test had (#798).
  *  What is worth pinning is the parsing, and that is `foldSessionNamingLine`,
  *  which IS exported and which session-name.test.ts drives line at a time the
- *  way `foldTranscriptLine` does. This wrapper is a scan and two null checks. */
+ *  way `foldTranscriptLine` does. This wrapper is a scan and two null checks.
+ *
+ *  The recap comes back beside the naming because it comes off the same scan:
+ *  `naming` is null when the transcript has no naming record, `recap` when no
+ *  recap is standing. See session-recap.mjs, and `noteRecap` below. */
 async function readSessionNamingFromTranscript(path) {
   const state = await scanTranscript(path);
   if (!state) return null;
-  if (!state.agentName && !state.aiTitle) return null;
-  return { agentName: state.agentName, aiTitle: state.aiTitle };
+  const naming = (state.agentName || state.aiTitle)
+    ? { agentName: state.agentName, aiTitle: state.aiTitle }
+    : null;
+  return { naming, recap: state.recap ?? null };
 }
 
 function maybeResolveSessionName(payload) {
@@ -1496,7 +1636,10 @@ function maybeResolveSessionName(payload) {
   lastNameReadAt.set(sid, now);
   pendingNameReads.add(sid);
   readSessionNamingFromTranscript(tp)
-    .then(naming => {
+    .then(read => {
+      if (!read) return;
+      noteRecap(sid, read.recap);
+      const naming = read.naming;
       if (!naming) return;
       const sig = `${naming.agentName ?? ""}\u0000${naming.aiTitle ?? ""}`;
       if (nameBySession.get(sid) === sig) return;
@@ -1512,6 +1655,43 @@ function maybeResolveSessionName(payload) {
     .finally(() => pendingNameReads.delete(sid));
 }
 
+// ─── Session recap ───────────────────────────────────────────────────────
+// Claude Code's "※ recap:" line (see session-recap.mjs). It comes off the
+// transcript cursor like the naming above, and its emit is gated the same way:
+// on a CHANGE, keyed by the recap's own timestamp, so a pass that re-reads a
+// recap already sent says nothing. A session that never had one emits nothing
+// at all — the first word about a session's recap is always a recap.
+//
+// TWO ROADS IN, BECAUSE NO HOOK FIRES WHEN IT LANDS. The cursor runs off hook
+// events, and a recap is written three minutes into a silence that has none.
+// So the output watch, which already stats these files between events, hands
+// every tail it reads to `onRecapTail`, and a tail carrying a recap asks the
+// cursor to fold the file. The cursor stays the one place the rule lives: a
+// recap a later turn retired is retired whichever road found it.
+const recapBySession = new Map();       // sid -> `${at}` last sent, "" once retired
+
+function noteRecap(sid, recap) {
+  const sig = recap ? String(recap.at) : "";
+  const prev = recapBySession.get(sid);
+  if (prev === sig) return;
+  if (prev === undefined && !recap) return;
+  recapBySession.set(sid, sig);
+  pushEvent({
+    hook_event_name: "SessionRecapped",
+    session_id: sid,
+    recap: recap ? { text: recap.text, at: recap.at } : null,
+  }, "internal");
+}
+
+/** The output watch's tap. Only a tail carrying the recap mark costs a scan,
+ *  and the scan is the cursor's own: it folds the bytes it has not seen yet. */
+function onRecapTail(sid, text, path) {
+  if (!path || !text.includes(RECAP_MARK)) return;
+  scanTranscript(path)
+    .then(state => { if (state) noteRecap(sid, state.recap ?? null); })
+    .catch(() => {});
+}
+
 // ─── Context enrichment ──────────────────────────────────────────────────
 // Approximation of `/context` since CC doesn't expose its breakdown via
 // hooks. We scan the transcript JSONL for message counts (user / assistant
@@ -1844,26 +2024,125 @@ function maybeResolveCodexMemory(sid, cwd, persist) {
 // than a second computation of the same rule, is what makes the printed path and
 // the tailed path unable to disagree.
 export { CODEX_SESSIONS_DIR };
+// sid -> the rollout's path, or, once a walk of the whole tree came back without
+// one, the moment that walk began. See findCodexRolloutPath for why a miss is
+// kept (#992), and why only for CODEX_MISS_TTL_MS (#1134).
 const codexRolloutPathBySid = new Map();
 const lastCodexUsageReadAt = new Map();
 const pendingCodexUsageReads = new Set();
 const CODEX_READ_THROTTLE_MS = 2500;
+// How many of the newest day directories a lookup reads when it is not owed
+// the whole tree: the bound listRecentCodexRollouts keeps for the watcher.
+const CODEX_RECENT_DAY_DIRS = 2;
+// How long a miss from the whole tree is believed before its id is owed one
+// more walk of it. See findCodexRolloutPath for why ten minutes.
+const CODEX_MISS_TTL_MS = 10 * 60 * 1000;
+// True while one lookup is walking the whole tree. One at a time; see below.
+let codexWholeTreeWalk = false;
 
+/**
+ * Where is this session's rollout, if it is anywhere under this tree?
+ *
+ * WHAT WAS WRONG (#992). A hit was kept and a miss was not, and the walk that
+ * answers a miss is the whole tree: one readdir per year, per month and per day
+ * under $CODEX_HOME/sessions, which only a hit ends early. So an id with no
+ * rollout here paid for that walk again on every pass maybeResolveCodex's
+ * 2.5-second throttle let through, for as long as its hooks kept firing. A Codex
+ * hook left over from an older install, for a session whose rollout lives
+ * under another CODEX_HOME, is enough. The id also arrives on `/api/event`,
+ * which takes no credential and throttles per id, so a local process could post
+ * a few hundred fresh ids and have every one of them walk every directory at
+ * once. Both were measured in codex-unresolved-session-walk-992.test.ts, over a
+ * tree holding one year of history. The same unresolvable id, posted twice one
+ * throttle window apart, read all 37 of that year's directories both times, and
+ * six fresh ids posted together had six walks of it in flight at once.
+ *
+ * THE FIRST LOOKUP STILL WALKS THE WHOLE TREE, newest first, as it always did.
+ * A session resumed from last month appends to last month's rollout, and one
+ * that has been running for three days has dropped out of the newest two
+ * directories. Bounding the first walk the way the watcher's listing is bounded
+ * would find neither, and their usage would never show.
+ *
+ * A MISS FROM THE WHOLE TREE IS KEPT, as the moment that walk began, and every
+ * later lookup for that id reads only the newest two day directories. Those are
+ * the only place a rollout written after the walk can land, because Codex names
+ * a file for the moment it creates it, and they are the bound
+ * listRecentCodexRollouts already trusts for live sessions. So a hook that
+ * fires a moment before its rollout is on disk is still answered on a later
+ * pass, and an id nothing will ever carry costs about five readdirs a pass
+ * instead of the whole history. One caveat: walkRolloutDays swallows every
+ * error it meets, so a walk that could not read a directory still counts as
+ * having looked there. That is the one way a wrong miss gets kept.
+ *
+ * BUT NOT FOREVER (#1134). The newest two directories are where a rollout
+ * written after the walk lands, and they do not stay the newest two. A session
+ * whose first hook fired before its rollout existed, and whose next hook came
+ * after two newer day directories had appeared — a `codex resume` two days
+ * later — had its rollout in the third-newest directory, behind a miss that
+ * only forgetSession or a restart would ever clear. Its usage never showed,
+ * where the tree before #1111 found it; codex-kept-miss-expires-1134.test.ts
+ * has the measurement.
+ *
+ * So a kept miss is believed for CODEX_MISS_TTL_MS, and the first lookup after
+ * that is owed one more whole walk, on the same one-at-a-time terms as the
+ * first. Ten minutes closes the hole outright. A rollout drops out of the newest
+ * two directories only once two later calendar days have begun, which is never
+ * less than about a day after it was written (23 hours across a DST change), so
+ * by then every miss that could be hiding it has expired and the next lookup
+ * walks to it. It also keeps #992 fixed: an id nothing carries walks the whole
+ * tree once in ten minutes where it used to walk it every 2.5-second throttle
+ * window, 240 times as often, and reads its five directories in between. And
+ * the caveat above now costs a session ten minutes of usage rather than the
+ * rest of the process's life. It is the same ten minutes CODEX_STATE_TTL_MS
+ * keeps a rollout's cursor for, the other bound on this side that leans on the
+ * two-directory window. A clock that has gone backwards leaves a miss's age
+ * unknown, and such a miss is treated as expired: it costs one walk, where
+ * believing it would reopen the hole for however far the clock went back.
+ *
+ * AND ONE WHOLE-TREE WALK AT A TIME. Keeping the miss handles an id that comes
+ * back; it does nothing for a caller that sends a new one every time. So a
+ * lookup that is owed the whole tree while another lookup is walking it reads
+ * the newest two directories instead, keeps nothing, and gets its full walk on
+ * a later pass. A burst of fresh ids costs one walk of the history plus a few
+ * readdirs each, not one walk each, all at once.
+ *
+ * The map is bounded as it was: forgetSession evicts it with every other
+ * per-session cache, and a number is smaller than the path it stands in for.
+ */
 async function findCodexRolloutPath(sid) {
   const cached = codexRolloutPathBySid.get(sid);
-  if (cached) return cached;
+  if (typeof cached === "string") return cached;
+  // Owed the whole tree: never looked for yet, or the whole tree's last miss is
+  // no longer believed — and nobody else is walking it.
+  const startedAt = Date.now();
+  const age = typeof cached === "number" ? startedAt - cached : -1;
+  const missHolds = age >= 0 && age < CODEX_MISS_TTL_MS;
+  const whole = !missHolds && !codexWholeTreeWalk;
+  if (whole) codexWholeTreeWalk = true;
   // Walk year → month → day → files, newest first. Codex includes the sid in the
   // filename (rollout-...-<sid>.jsonl) so a directory-scoped match is enough.
   // The walk itself lives in codex-dir.mjs, shared with the watcher's listing
   // below and with codex-usage.mjs, so all three read one tree the same way.
   let found = null;
-  await walkRolloutDays((dayDir, files) => {
-    const hit = files.find(f => f.includes(sid) && f.endsWith(".jsonl"));
-    if (!hit) return;
-    found = join(dayDir, hit);
-    return STOP;
-  });
+  let dayDirs = 0;
+  try {
+    await walkRolloutDays((dayDir, files) => {
+      const hit = files.find(f => f.includes(sid) && f.endsWith(".jsonl"));
+      if (hit) {
+        found = join(dayDir, hit);
+        return STOP;
+      }
+      if (!whole && ++dayDirs >= CODEX_RECENT_DAY_DIRS) return STOP;
+    });
+  } finally {
+    if (whole) codexWholeTreeWalk = false;
+  }
+  // A hit is kept, as it always was. A miss is kept only when it is the whole
+  // tree's answer — a miss in the newest two directories says nothing about the
+  // rest of them — and it is kept as the moment that walk began, which is when
+  // it read the directories a rollout written since would be in.
   if (found) codexRolloutPathBySid.set(sid, found);
+  else if (whole) codexRolloutPathBySid.set(sid, startedAt);
   return found;
 }
 
@@ -2044,6 +2323,33 @@ const codexSessionApproval = new Map(); // sid -> last approval_policy string
 // listing. The listing covers two day-directories, so anything missing from it
 // is at least a day old and will never be appended to again.
 const CODEX_STATE_TTL_MS = 10 * 60 * 1000;
+// Every rollout path this PROCESS has ever held a cursor for, which the TTL
+// sweep deliberately does not clear — that is the whole of its job.
+//
+// A cursor dropped and then re-created is indistinguishable, to the code that
+// creates it, from a rollout nobody has ever read: both are "no entry in
+// codexFileState". The difference matters enormously, because a new file is
+// opened at byte 0 and told it has its own beginning, so a re-discovery
+// replayed the entire rollout as fresh events AND minted a `SessionStart` for a
+// session this deck joined late. This set is what lets the second case answer
+// "no, we have seen this one" and park at the end instead (#981).
+//
+// Capped, in insertion order, for the reason codexFileState is swept at all: a
+// long-lived deck on a busy machine would otherwise accumulate a path per
+// session for as long as it runs. A path is far cheaper than a cursor, so the
+// cap is generous — but it is a cap, and it is the same LRU shape
+// sessionTouchedAt uses.
+const codexSeenEver = new Set();
+const MAX_CODEX_SEEN_EVER = 512;
+function rememberCodexPath(path) {
+  // Delete-then-add so the Set's own insertion order IS the LRU order, and
+  // eviction is one key read rather than a scan.
+  codexSeenEver.delete(path);
+  codexSeenEver.add(path);
+  while (codexSeenEver.size > MAX_CODEX_SEEN_EVER) {
+    codexSeenEver.delete(codexSeenEver.values().next().value);
+  }
+}
 let codexScanRunning = false;
 let codexWatchTimer = null;
 let codexWorkspace = "";
@@ -2135,8 +2441,12 @@ async function provesDeck(d) {
  * 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. A
- * record that fails the challenge is likewise left alone: see the same argument
- * spelled out in proveTargets in hook/hook.js.
+ * record that fails the challenge is likewise left alone HERE. The hook is the one
+ * reader that does delete a record, and only one that stayed silent through both
+ * of its challenge deadlines and has not been restamped for a minute, which a
+ * live deck does every five seconds (proveTargets in hook/hook.js, #1119). One
+ * missed answer on this poll's timer is not that evidence, so nothing here acts
+ * on it.
  *
  * 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
@@ -2179,6 +2489,33 @@ async function listRecentCodexRollouts() {
   return out;
 }
 
+/**
+ * The session id a rollout's own file name carries, or null.
+ *
+ * Codex names every rollout `rollout-<YYYY-MM-DDTHH-MM-SS>-<uuid>.jsonl` —
+ * codex-usage.mjs reads the timestamp half as parseRolloutTime — and the uuid
+ * is the id `session_meta.payload.id` states. findCodexRolloutPath already leans
+ * on that, matching a session id against file names, so the name is the
+ * fallback when the header stops saying it (#996). A compressed `.jsonl.zst`
+ * is not matched: this reader never opens one.
+ */
+export function sidFromRolloutName(path) {
+  const m = /-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i.exec(basename(String(path ?? "")));
+  return m ? m[1] : null;
+}
+
+/** Which of the two ways a rollout can fail to say whose it is has been printed
+ *  already. Once per kind for the life of the process, not once per file: the
+ *  scan retries a rollout it cannot place on every tick, and a change to the
+ *  format would hit every rollout at once, so per file would be the same
+ *  sentence once for each of them. */
+const codexHeaderWarned = new Set();
+function warnUnplacedRollout(kind, path, why) {
+  if (codexHeaderWarned.has(kind)) return;
+  codexHeaderWarned.add(kind);
+  console.warn(`${PRODUCT}: cannot tell which Codex session ${path} belongs to: ${why}. If Codex has changed its rollout format, its sessions will not be drawn until the deck reads the new one.`);
+}
+
 // Read the first complete JSON line of a rollout (the session_meta header)
 // to learn sid + cwd before we start streaming. The header line can be large
 // (base_instructions text runs tens of KB), so we read in growing chunks until
@@ -2196,11 +2533,31 @@ async function readCodexHeader(path) {
       if (nl >= 0) {
         const obj = JSON.parse(text.slice(0, nl));
         if (obj && obj.type === "session_meta" && obj.payload) {
+          // THE ID, WITH THE FILE NAME BEHIND IT (#996). Every other field this
+          // file takes off a rollout goes through a type guard, and the event
+          // names are read in both spellings because OpenAI has renamed a record
+          // once already; this one went straight into `sid`. A renamed or
+          // dropped `payload.id` made every header answer undefined, and the
+          // scan `continue`s on that — so every rollout was retried on every
+          // tick, its first 64KB re-read each time, not one Codex session was
+          // drawn, and nothing said why. The file name carries the same id.
+          const id = obj.payload.id;
+          const sid = typeof id === "string" && id !== "" ? id : sidFromRolloutName(path);
+          if (!sid) warnUnplacedRollout("no-id", path, "its session_meta has no id, and its file name carries none");
           // 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 { sid, cwd: await canonicalCwd(obj.payload.cwd) };
+        }
+        // The other rename the scan would otherwise retry in silence: a first
+        // line that is whole but is not a session_meta will never become one.
+        // Said, not guessed around — which record a renamed header would be is
+        // not something to infer from one line. Only for a file named like a
+        // rollout, so some other `.jsonl` left in the tree is not reported as a
+        // format change.
+        if (obj && typeof obj === "object" && sidFromRolloutName(path)) {
+          warnUnplacedRollout("no-header", path, `its first line is a ${JSON.stringify(String(obj.type ?? "record with no type"))}, not a session_meta`);
         }
         return null;
       }
@@ -2265,9 +2622,14 @@ export function codexObjToPayload(obj, sid, cwd) {
     // "waiting" state derived from this plus a pending call would be a guess
     // wearing the clothes of a measurement.
     //
-    // Written on the record even when the value is missing or not a string, so
-    // a future Codex that renames or drops the field clears the stale answer
-    // rather than pinning the session to whatever it last said.
+    // Deleted from the record when the value is missing or not a string, so this
+    // server stops stamping a stale policy on the payloads it builds from here
+    // on. The page does not un-say it, though. `approval_policy: undefined` does
+    // not survive JSON.stringify, so the wire has no way to say "cleared", and
+    // the reducer applies the field only when it is a non-empty string — a card
+    // keeps the last policy it was told for as long as the session is on the
+    // board. This comment used to promise the stale answer was cleared; it is
+    // cleared here and nowhere else (#996).
     if (typeof pl.approval_policy === "string" && pl.approval_policy) {
       codexSessionApproval.set(sid, pl.approval_policy);
     } else {
@@ -2653,8 +3015,19 @@ async function codexScanOnce(firstRun) {
         // 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 };
+        //
+        // UNLESS THIS PROCESS HAS SEEN THE PATH BEFORE, in which case there is
+        // no beginning to claim and nothing to replay: the cursor was dropped
+        // by the TTL sweep and this is a RE-discovery. Parking at the current
+        // size costs whatever was appended while the tree was unreachable,
+        // which is the same trade `firstRun` already makes below — against
+        // re-emitting every prompt, every PreToolUse/PostToolUse and every
+        // UsageObserved in the file to every tab, and re-appending the lot to
+        // the shared events.jsonl if this deck is the elected writer (#981).
+        const fresh = !codexSeenEver.has(path);
+        state = { offset: fresh ? 0 : st.size, sid: header.sid, cwd: header.cwd, skip: false, sawBeginning: fresh, rootOpened: false, seenAt: now };
         codexFileState.set(path, state);
+        rememberCodexPath(path);
         if (firstRun) {
           // On startup, skip a pre-existing session's history entirely — no
           // replay. Only future appends (a live session that keeps going) will
@@ -2669,8 +3042,18 @@ async function codexScanOnce(firstRun) {
           // 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.
+          // unmarked, because nothing here emits a second one to disturb it.
+          //
+          // NOT because the reducer would refuse to listen. It used to say so
+          // here — "the reducer only honours `synthetic` on the call that
+          // CREATES the node" — and that is false: `reducer.ts` clears
+          // `root.synthetic` on EVERY `SessionStart`, deliberately, so that one
+          // arriving after the event that created the root retracts a marker
+          // the deck no longer deserves to be wearing (#677). Which makes the
+          // marker exactly as honest as the emitter above it, and is why the
+          // rule this branch states — do not emit a `SessionStart` for a
+          // beginning this process did not watch — is the whole guarantee
+          // rather than a belt beside a brace (#981).
           state.offset = st.size;
           state.sawBeginning = false;
           continue;
@@ -2678,6 +3061,14 @@ async function codexScanOnce(firstRun) {
       }
 
       if (state.skip) { state.offset = st.size; continue; }
+      // A cursor sitting PAST the end of the file is a different thing from
+      // "nothing new", and the two used to collapse into one `continue` — where
+      // the Claude scanner beside this one starts the file over (scanTranscript).
+      // Not reachable today: rollouts are append-only and uniquely named, and
+      // readAppendedLines cannot advance a cursor past `size`. It is resynced
+      // FORWARD rather than back to zero because re-reading a rollout from the
+      // beginning is precisely the full replay #981 is about.
+      if (st.size < state.offset) state.offset = st.size;
       if (st.size <= state.offset) continue;
 
       // Same bounded reader the Claude transcripts use. A rollout is not a
@@ -2732,8 +3123,24 @@ async function codexScanOnce(firstRun) {
     // "not seen for a while" rather than "absent from this listing": a single
     // unreadable directory mid-scan would otherwise drop a live file's cursor,
     // and re-adding it at offset 0 replays that entire rollout as fresh events.
-    for (const [p, s] of codexFileState) {
-      if (now - (s.seenAt ?? 0) > CODEX_STATE_TTL_MS) codexFileState.delete(p);
+    //
+    // AN EMPTY LISTING IS NOT EVIDENCE THAT ANYTHING WENT AWAY, and skipping
+    // the sweep on those ticks is the other half of the same argument. The
+    // "not seen for a while" clock was meant to ride out a directory that is
+    // unreadable for a moment, and it did — but it ran on ticks where `seenAt`
+    // had been refreshed for NOBODY, because walkRolloutDays swallows its
+    // readdir error at every level and answers `[]` rather than throwing. Ten
+    // minutes of an unreachable $CODEX_HOME — a network or removable volume, an
+    // encrypted home not yet unlocked, a permission change — and every cursor
+    // was gone, which is the whole window the clock was sized to survive (#981).
+    //
+    // Nothing is lost by waiting: an empty listing means no file can be read
+    // this tick anyway, and a tree that really is empty stays empty, so the
+    // first tick that lists anything at all sweeps what is genuinely stale.
+    if (files.length) {
+      for (const [p, s] of codexFileState) {
+        if (now - (s.seenAt ?? 0) > CODEX_STATE_TTL_MS) codexFileState.delete(p);
+      }
     }
   } catch {
     /* swallow — watcher must never crash the server */
@@ -2778,12 +3185,47 @@ export function eventsSince(seq) {
 // model of each. SessionEnd is not a usable eviction signal (a killed CLI
 // never sends one, and Codex has no such hook at all), so entries expire by
 // least-recent use against a cap instead — the same shape pruneTranscriptScans
-// already uses for its per-path state. The cap sits far above any plausible
-// number of concurrent sessions, so a live session is never evicted; and an
-// evicted one that speaks again simply re-reads its transcript.
+// already uses for its per-path state.
+//
+// AND A LIVE SESSION IS NEVER EVICTED, which this comment used to assert on the
+// strength of the cap sitting "far above any plausible number of concurrent
+// sessions". The cap held; the claim around it did not, and the 257th
+// concurrent session is where that showed. forgetSession clears the three
+// read-throttle stamps and pruneTranscriptScans drops the byte cursor, so an
+// evicted session that speaks again does not "simply re-read its transcript" —
+// it re-reads it on EVERY event, and those re-reads are themselves pushEvent
+// calls, so the degradation feeds itself. Measured here, fresh deck per row,
+// 16 events per session, 21 KB transcripts:
+//
+//   N=200  posted=3200  synthetic=600   rchar=6 MB   rps=5614  p50=17ms
+//   N=256  posted=4096  synthetic=768   rchar=7 MB   rps=6341  p50=16ms
+//   N=300  posted=4800  synthetic=9159  rchar=77 MB  rps=2308  p50=97ms
+//
+// A 17% increase in session count: 11.9x the derived events, 11x the transcript
+// reads, ingest down 2.7x, p50 up 6x. Three per SESSION became three per EVENT.
+// A cliff, not a slope, sitting exactly on the constant — and the server's cap
+// (256) sits above the client's AGENT_CAP (200), so the UI cannot warn about a
+// number it will not draw.
+//
+// So the cap reaps only what it was always described as reaping: sessions
+// nothing has been heard from. A session with an event inside
+// OUTPUT_WATCH_WINDOW_MS is live by the same definition outputWatchOnce already
+// uses, and keeping it costs four numbers and a string.
 const sessionTouchedAt = new Map();   // sid -> ms of the last event seen
 const MAX_TRACKED_SESSIONS = 256;
 
+/**
+ * The absolute ceiling, above which even a live session is dropped.
+ *
+ * The age rule alone is unbounded in principle — nothing stops a machine from
+ * having ten thousand sessions inside five minutes — and an unbounded map is
+ * the leak this whole mechanism exists to end. This is a backstop, not the
+ * working limit: reaching it means something is wrong in a way no cache policy
+ * fixes, and dropping the least-recently-seen entries is still the least bad
+ * answer. Eight times the cap, which is forty times the client's AGENT_CAP.
+ */
+export const HARD_TRACKED_SESSIONS = MAX_TRACKED_SESSIONS * 8;
+
 /** The transcript watch, and how far back a session stays worth polling.
  *
  *  A session is polled while its last HOOK event is recent — and the window has
@@ -2797,16 +3239,48 @@ const OUTPUT_WATCH_WINDOW_MS = 5 * 60_000;
 const OUTPUT_WATCH_MS = 1_500;
 let outputWatchTimer = null;
 
+/** How long a quiet session is still worth a `stat` for its recap, and how
+ *  often it gets one.
+ *
+ *  The five minutes above are sized to a session that is WORKING. A recap is
+ *  the opposite case: Claude Code writes it once a finished turn has sat three
+ *  minutes AND the terminal has lost focus, so it lands whenever the person
+ *  walks away — a median 3.1 minutes after the turn on this machine, and an
+ *  hour after it for somebody who stayed at the terminal first. A session that
+ *  quiet is producing nothing, so every fourth tick is plenty: a recap reaches
+ *  the deck within six seconds of being written, and a resting session costs a
+ *  `stat` every six seconds rather than every one and a half. */
+const RECAP_WATCH_WINDOW_MS = 12 * 60 * 60_000;
+const RECAP_WATCH_EVERY = 4;
+let outputWatchTicks = 0;
+
 /** One tick: stat the recent sessions' transcripts, read only what grew, and
  *  say what landed. Everything expensive about this is guarded inside the watch
- *  — a session that wrote nothing costs one `stat`. */
+ *  — a session that wrote nothing costs one `stat`.
+ *
+ *  Resting sessions ride along on every RECAP_WATCH_EVERY-th tick for their
+ *  recap alone, and their blocks are not reported: this answers for the
+ *  sessions it calls live, and a resting one that starts working again fires a
+ *  hook first, which makes it live the ordinary way.
+ *
+ *  A tick that starts while the last one is still reading gets nothing back:
+ *  the watch refuses the overlap itself, where the offset is — see `poll` in
+ *  output-watch.mjs for what two overlapping ticks used to report (#1089). */
 async function outputWatchOnce() {
-  const cutoff = Date.now() - OUTPUT_WATCH_WINDOW_MS;
-  const live = [];
-  for (const [sid, at] of sessionTouchedAt) if (at >= cutoff) live.push(sid);
-  if (!live.length) return;
-  const found = await outputWatch.poll(live);
+  const now = Date.now();
+  const cutoff = now - OUTPUT_WATCH_WINDOW_MS;
+  const restingCutoff = now - RECAP_WATCH_WINDOW_MS;
+  const withResting = outputWatchTicks++ % RECAP_WATCH_EVERY === 0;
+  const live = new Set();
+  const polled = [];
+  for (const [sid, at] of sessionTouchedAt) {
+    if (at >= cutoff) { live.add(sid); polled.push(sid); }
+    else if (withResting && at >= restingCutoff) polled.push(sid);
+  }
+  if (!polled.length) return;
+  const found = await outputWatch.poll(polled, onRecapTail);
   for (const f of found) {
+    if (!live.has(f.sid)) continue;
     pushEvent({
       hook_event_name: "OutputObserved",
       session_id: f.sid,
@@ -2839,6 +3313,8 @@ function forgetSession(sid) {
   // ring has rolled past the original SessionNamed shows that session unnamed
   // for the rest of its life.
   nameBySession.delete(sid);
+  // The recap's gate, for the same reason — see noteRecap.
+  recapBySession.delete(sid);
   lastNameReadAt.delete(sid);
   modelLastReadAt.delete(sid);
   lastUsageReadAt.delete(sid);
@@ -2855,9 +3331,17 @@ function touchSession(sid) {
   // Re-insert so the Map's own insertion order *is* the LRU order and eviction
   // below is one key read rather than a scan of every session ever seen.
   sessionTouchedAt.delete(sid);
-  sessionTouchedAt.set(sid, Date.now());
-  while (sessionTouchedAt.size > MAX_TRACKED_SESSIONS) {
-    const oldest = sessionTouchedAt.keys().next().value;
+  const now = Date.now();
+  sessionTouchedAt.set(sid, now);
+  if (sessionTouchedAt.size <= MAX_TRACKED_SESSIONS) return;
+  // Insertion order IS recency, so the first entry still inside the window
+  // proves every entry after it is too, and the loop stops there rather than
+  // scanning. That is what keeps this O(evicted) and not O(sessions) on the hot
+  // path — which matters most in exactly the case that used to be worst.
+  const idleBefore = now - OUTPUT_WATCH_WINDOW_MS;
+  for (const [oldest, at] of sessionTouchedAt) {
+    if (sessionTouchedAt.size <= MAX_TRACKED_SESSIONS) break;
+    if (at >= idleBefore && sessionTouchedAt.size <= HARD_TRACKED_SESSIONS) break;
     sessionTouchedAt.delete(oldest);
     forgetSession(oldest);
   }
@@ -3234,7 +3718,7 @@ function handlePrefsRead(req, res) {
 
 /** POST a patch. Fields nobody sent keep their value — see writePrefs. */
 async function handlePrefsWrite(req, res) {
-  const raw = await readBody(req).catch(() => null);
+  const raw = await readBody(req, res).catch(() => null);
   let body = null;
   try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
   if (!body || typeof body !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
@@ -3260,11 +3744,13 @@ let _awayNothingUntil = 0;
 /**
  * One tick of the away-update. Returns what it did, or null.
  *
- * Exported so a test can drive it without waiting out the boot grace — the one
- * input that is a policy rather than a fact, and so the only one it may pass.
- * Every clock is the real one: presence and activity are stamped with it.
+ * Every clock is the real one: presence and activity are stamped with it, and
+ * the boot grace is AWAY_BOOT_GRACE_MS. This used to be exported and take the
+ * grace as an argument, so a test could drive it without waiting that out; the
+ * tests drive awayGate and awayUpdateStep in auto-update.mjs instead, and the
+ * one caller left is the `_awayTimer` interval.
  */
-export async function awayUpdateTick({ graceMs = AWAY_BOOT_GRACE_MS } = {}) {
+async function awayUpdateTick() {
   const now = Date.now();
   if (!awayGate({
     enabled: _prefs?.autoUpdate !== false,
@@ -3274,7 +3760,7 @@ export async function awayUpdateTick({ graceMs = AWAY_BOOT_GRACE_MS } = {}) {
     looking: presence.looking(now),
     busy: activity.busy(now),
     quietMs: activity.quietMs(now),
-    graceMs,
+    graceMs: AWAY_BOOT_GRACE_MS,
   })) return null;
   // A standing "nothing newer", unless the clock has moved back past it.
   if (now < _awayNothingUntil && _awayNothingUntil - now <= AWAY_RECHECK_MS) return null;
@@ -3295,6 +3781,9 @@ export async function awayUpdateTick({ graceMs = AWAY_BOOT_GRACE_MS } = {}) {
   if (presence.looking(again) || activity.busy(again) || _restarting) return null;
   _awayTry = { target: step.target, at: again };
   if (step.act === "install") {
+    // Pinned before npm is spawned, never after it — see PINNED_MODULES. On a
+    // deck bin/deck.js has marked ready this is a promise that settled long ago.
+    await pinRunningBuild();
     su.startUpgrade({ pkgRoot: PKG_ROOT });
     return step.act;
   }
@@ -3309,7 +3798,7 @@ export async function awayUpdateTick({ graceMs = AWAY_BOOT_GRACE_MS } = {}) {
 /** POST {tab, looking} — a tab saying whether it is being looked at. See
  *  presence.mjs, and src/web/presence.ts for the sender. */
 async function handlePresence(req, res) {
-  const raw = await readBody(req).catch(() => null);
+  const raw = await readBody(req, res).catch(() => null);
   let body = null;
   try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
   if (!body || typeof body !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
@@ -3337,13 +3826,30 @@ const lanEngine = createEngine({
     return out?.ok ? out.blob : null;
   },
   importAccount: async (blob, step) => {
-    const { importAccount, landed } = await import("./cswap-admin.mjs");
+    // `landed` is not needed out here any more: the only call that read it was
+    // the forced import, which fillEmptySlot now owns along with it.
+    const { importAccount, fillEmptySlot } = await import("./cswap-admin.mjs");
+    const [want, wantOrg] = String(step?.key ?? "").split("@@");
     // NO `force`, ever, and this is the line where that promise is kept. A
     // plain import adds an account that is missing and replaces exactly one
     // claude-swap has quarantined; it SKIPS one that is present and healthy.
     // So a peer cannot overwrite a working credential of this deck's even by
     // lying about its own, because the flag that would allow it is not passed.
-    const out = await importAccount(blob);
+    //
+    // NARROWED TO THE ONE ACCOUNT ASKED FOR, for the same reason the forced
+    // import below is, and this line did not have it. The seal's AAD is
+    // `${peerFp}->${identity.fp}|${step.key}` — it binds the ENVELOPE to the
+    // key that was requested and says nothing about the contents, and a share
+    // payload is `{ accounts: [...] }`, a bundle rather than one credential.
+    // So a peer asked for A could seal, under A's AAD, a bundle carrying A
+    // plus B, C and D it never listed in its manifest, and every one of them
+    // landed: `syncAction` answers "add" for anything this deck lacks, and an
+    // add does not need the owner's tick. The panel drew A and the store
+    // gained four. `only` narrows without implying `force` — `overwrite` is
+    // `force === true && narrowing` — so the promise above survives word for
+    // word, and a bundle that does not carry what was asked for is refused
+    // rather than unpacked.
+    const out = await importAccount(blob, { only: { email: want, org: wantOrg ?? "" } });
     if (!out?.ok) return { ok: false, why: out?.reason ?? "import refused" };
     // A SKIP IS NOT A HEAL, and reading `ok` alone said it was. `cswap import`
     // exits ZERO when it declines an account it already holds — importAccount's
@@ -3374,29 +3880,30 @@ const lanEngine = createEngine({
     // and the account somebody most needed repaired was the one the feature
     // could not repair.
     //
-    // ASKED NOW, NOT READ FROM THE CACHE. The cached verdicts are up to ten
-    // minutes old, which is right for a label and wrong for a decision that
-    // writes a credential: somebody who signed in two minutes ago still reads
-    // as `no_credentials` there, and acting on that would replace the login
-    // they had just created.
-    const { verdictNow } = await import("./claude-accounts.mjs");
-    const [email, org] = String(step?.key ?? "").split("@@");
-    const now = await verdictNow(email, org ?? "");
-    if (now !== "no_credentials") return { ok: false, why: "claude-swap kept the slot it already has" };
-
     // FILLING AN EMPTY SLOT, WHICH IS NOT OVERWRITING A WORKING ONE — and the
-    // promise above survives word for word. A peer cannot reach this: the
-    // verdict comes from THIS machine's claude-swap, about THIS machine's
-    // store, and nothing a peer sends can make a slot report that it holds
-    // nothing. Narrowed to the one account with `only`, so a bundle carrying
-    // several cannot ride in behind it.
-    const forced = await importAccount(blob, { force: true, only: { email, org: org ?? "" } });
-    if (!forced?.ok) return { ok: false, why: forced?.reason ?? "import refused" };
-    // `added` counts `imported` alone, and a forced replace is `healed` — see
-    // landed, which is the difference between a repair and a repair reported as
-    // a failure.
-    if (!landed(forced.results)) return { ok: false, why: "claude-swap kept the slot it already has" };
-    return { ok: true, filled: true };
+    // promise above survives word for word. A peer cannot reach it: the verdict
+    // comes from THIS machine's claude-swap, about THIS machine's store, and
+    // nothing a peer sends can make a slot report that it holds nothing.
+    //
+    // THE VERDICT AND THE WRITE ARE ONE CRITICAL SECTION, which is why this is
+    // one call and not the pair it used to be (#1040).
+    //
+    // The verdict was already being asked for fresh rather than read from the
+    // ten-minute cache, under a comment naming the exact reason: "somebody who
+    // signed in two minutes ago still reads as `no_credentials` there, and
+    // acting on that would replace the login they had just created". That
+    // sentence is kept, and the read that served it moved rather than went —
+    // see fillEmptySlot, which opens with it.
+    //
+    // Freshness alone only SHORTENED the window. The asking happened out here
+    // while the writing took the store mutex inside importAccount, so the two
+    // were never one critical section: `registerSignedIn` holds that mutex for
+    // `cswap add` (60 s), `cswap list` (60 s) and `restoreActive`'s `cswap
+    // switch` (30 s), and a forced import queued behind one still acted on a
+    // verdict taken before any of it began. fillEmptySlot re-reads the verdict
+    // as its first statement INSIDE the lock, so the promise holds by
+    // construction rather than by how long the queue happened to be.
+    return fillEmptySlot(blob, { email: want, org: wantOrg ?? "" });
   },
   // The deck's own long-term key, kept so a restart is the same deck rather
   // than a stranger to everybody who has paired with it. Written once, on the
@@ -3421,9 +3928,22 @@ const lanEngine = createEngine({
   // is a pairing that goes one-way at the next restart.
   onDial: async entry => {
     try {
-      const manual = Array.isArray(_prefs?.lan?.manual) ? _prefs.lan.manual : [];
-      if (manual.includes(entry)) return;
-      _prefs = await writePrefs({ lan: { manual: [...manual, entry] } });
+      // COMPUTED INSIDE THE JOB, out of what the write is about to read, rather
+      // than out of `_prefs` — which is a module-level copy refreshed only when
+      // a previous write resolves, not "the one on disk". `writePrefs` merges
+      // field by field and cannot merge two writes of one field: the patch here
+      // is the WHOLE array, so a stale one wins. Pressing accept on a heard deck
+      // at the moment an invite round fires this dropped the dialled address out
+      // of `lan.manual`, which is the failure the comment above describes.
+      _prefs = await updatePrefs(prev => {
+        const manual = Array.isArray(prev?.lan?.manual) ? prev.lan.manual : [];
+        return manual.includes(entry) ? null : { lan: { manual: [...manual, entry] } };
+      });
+      // AND RECONCILE THE ENGINE'S DIAL LIST with what was just written. The
+      // disk is now right, but `setPeers` replaces the list wholesale from
+      // `_prefs` on every settings write — so a write that raced this one, and
+      // whose `_prefs` predates it, would still take the address away.
+      lanEngine.setPeers(_prefs.lan.manual);
     } catch { /* dialled this session; the next round re-adds it */ }
   },
   onIdentity: async secret => {
@@ -3434,7 +3954,12 @@ const lanEngine = createEngine({
       // one — so they stayed invisible to each other with a correct file on
       // disk. `apply` restarts only when the id it is holding differs from the
       // one it is given, so this settles after one pass rather than looping.
-      await applyLanPrefs();
+      //
+      // The key is handed over HERE rather than read back off `_prefs`, because
+      // `applyLanPrefs` no longer round-trips the three fields the engine
+      // authors — see what it does and does not pass. This is the one caller
+      // that legitimately changes one of them, and it is holding the new value.
+      await applyLanPrefs({ secret });
     } catch { /* the next start picks it up; a shared id is the cost until then */ }
   },
   onError: (what, err) => {
@@ -3445,27 +3970,81 @@ const lanEngine = createEngine({
   },
 });
 
+/**
+ * What prefs is entitled to tell the LAN engine, and what it is not.
+ *
+ * THREE FIELDS ARE THE ENGINE'S OWN AND ARE LOADED ONCE. `trusted`, `secret`
+ * and `port` are written BY the engine, through `onTrust`, `onIdentity` and
+ * `onPort` — prefs is where they are kept between runs, not where they are
+ * decided. Handing them back on every settings write round-trips the engine's
+ * live state through a module-level copy of a file, and that copy is stale for
+ * as long as one of those writes is queued.
+ *
+ * WHAT THAT COST, reproduced with two real engines and a real handshake: press
+ * accept on deck B, and `lanEngine.accept` adds it to `cfg.trusted`
+ * synchronously and queues `onTrust`. In the same second another tab flips
+ * notifications; that handler's `writePrefs` is queued BEHIND `onTrust`'s, but
+ * its `applyLanPrefs` runs on the `_prefs` it assigned — merged from a disk read
+ * taken before `onTrust` wrote. `apply` does `cfg = { ...cfg, ...next }`, so the
+ * whole array is replaced:
+ *
+ *     B trusted after accept                : old-deck-fp, 6ef-127-19e-79e
+ *     B trusted after a plain settings write: old-deck-fp
+ *
+ * `GET /api/lan` reads `lanEngine.status()`, so the panel then shows B unpaired
+ * while prefs.json says paired, and B's calls are refused. The next `onTrust`
+ * from any source writes `cfg.trusted` back to disk without B, making it
+ * permanent.
+ *
+ * So `load` is true exactly once per boot, where reading them off the file IS
+ * the right answer, and false thereafter. The one caller that legitimately
+ * changes one of them afterwards passes it in directly — see `onIdentity`.
+ *
+ * Exported because it is the rule rather than the plumbing, and the plumbing
+ * around it is a module-level engine no test can reach.
+ */
+export function lanApplyFields(prefs, { load = false, env = process.env } = {}) {
+  const lan = prefs?.lan ?? {};
+  const page = {
+    // The file's answer unless the machine said no: AGENTS_DECK_NO_LAN=1 is
+    // how a launch script — or this repo's own test suite — keeps a deck off
+    // the network now that the default is on.
+    enabled: lanEnabled(prefs, env),
+    name: lan.name || defaultName(),
+    shared: Array.isArray(lan.shared) ? lan.shared : [],
+    autoAsk: lan.autoAsk !== false,
+    autoAccept: lan.autoAccept !== false,
+    // Whether paired decks are told which shared account this one is on.
+    shareActive: lan.shareActive !== false,
+    // Names somebody here gave other decks. The engine only hands them to
+    // the page, so a change never restarts anything.
+    aliases: lan.aliases && typeof lan.aliases === "object" ? lan.aliases : {},
+  };
+  if (!load) return page;
+  return {
+    ...page,
+    secret: lan.secret || "",
+    trusted: Array.isArray(lan.trusted) ? lan.trusted : [],
+    port: lan.port || 0,
+  };
+}
+
+/** Whether the engine has already been handed the three fields it authors.
+ *  Reset by `startServer`, because a boot is what reads them off the file. */
+let _lanLoaded = false;
+
 /** Push whatever is in prefs at the engine. Called at boot and after every
- *  write, so there is one source of truth and it is the file. */
-async function applyLanPrefs() {
+ *  write, so there is one source of truth and it is the file — for the fields
+ *  the file is the source of truth FOR. See `lanApplyFields`.
+ *
+ *  `also` is for a caller holding a value the engine itself just produced and
+ *  that has to take effect now; nothing else may name one of the three. */
+async function applyLanPrefs(also = null) {
   const lan = _prefs?.lan ?? {};
+  const load = !_lanLoaded;
+  _lanLoaded = true;
   try {
-    await lanEngine.apply({
-      // The file's answer unless the machine said no: AGENTS_DECK_NO_LAN=1 is
-      // how a launch script — or this repo's own test suite — keeps a deck off
-      // the network now that the default is on.
-      enabled: lanEnabled(_prefs),
-      name: lan.name || defaultName(),
-      secret: lan.secret || "",
-      shared: Array.isArray(lan.shared) ? lan.shared : [],
-      trusted: Array.isArray(lan.trusted) ? lan.trusted : [],
-      port: lan.port || 0,
-      autoAsk: lan.autoAsk !== false,
-      autoAccept: lan.autoAccept !== false,
-      // Names somebody here gave other decks. The engine only hands them to
-      // the page, so a change never restarts anything.
-      aliases: lan.aliases && typeof lan.aliases === "object" ? lan.aliases : {},
-    });
+    await lanEngine.apply({ ...lanApplyFields(_prefs, { load }), ...(also ?? {}) });
     // Wholesale, so removing an address in the panel really stops it being
     // dialled rather than only taking the row away.
     lanEngine.setPeers(lan.manual);
@@ -3544,7 +4123,7 @@ function handleLanStatus(req, res) {
  * than offering something its owner has forgotten they sent.
  */
 async function handleLanInvite(req, res) {
-  const raw = await readBody(req).catch(() => null);
+  const raw = await readBody(req, res).catch(() => null);
   let body = null;
   try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
   switch (body?.action) {
@@ -3570,7 +4149,7 @@ async function handleLanInvite(req, res) {
 }
 
 async function handleLanPeer(req, res) {
-  const raw = await readBody(req).catch(() => null);
+  const raw = await readBody(req, res).catch(() => null);
   let body = null;
   try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
   const fp = body && typeof body.fp === "string" ? body.fp : null;
@@ -3586,11 +4165,16 @@ async function handleLanPeer(req, res) {
       // saved.
       if (added.dialled) {
         const entry = `${added.addr}:${added.port}`;
-        const manual = Array.isArray(_prefs?.lan?.manual) ? _prefs.lan.manual : [];
-        if (!manual.includes(entry)) {
-          try { _prefs = await writePrefs({ lan: { manual: [...manual, entry] } }); }
-          catch { /* it is dialled this session; the next accept re-adds it */ }
+        // Inside the job, like `onDial` — the same whole-array patch computed
+        // from the same stale copy, and the same address lost when two of them
+        // land in one turn.
+        try {
+          _prefs = await updatePrefs(prev => {
+            const manual = Array.isArray(prev?.lan?.manual) ? prev.lan.manual : [];
+            return manual.includes(entry) ? null : { lan: { manual: [...manual, entry] } };
+          });
         }
+        catch { /* it is dialled this session; the next accept re-adds it */ }
       }
       return send(res, 200, { ok: true, added, ...lanEngine.status() });
     }
@@ -3607,13 +4191,19 @@ async function handleLanPeer(req, res) {
     // name of its own choosing. An empty name takes the alias away.
     //
     // The whole map is rebuilt from the one on disk rather than sent by the
-    // page, so two tabs renaming two decks cannot undo each other.
+    // page, so two tabs renaming two decks cannot undo each other. It is
+    // rebuilt inside the write's own job for that to be true: `_prefs` is a
+    // module-level copy refreshed only when a previous write resolves, and the
+    // patch is the whole map — so two renames in one turn both read before
+    // either job ran, both answered 200, and the first name was never written.
     case "alias": {
       if (!isAliasKey(fp)) return send(res, 400, { ok: false, reason: "bad_request" });
       const name = cleanAlias(body.name);
-      const next = { ...(_prefs?.lan?.aliases ?? {}) };
-      if (name) next[fp] = name; else delete next[fp];
-      _prefs = await writePrefs({ lan: { aliases: next } });
+      _prefs = await updatePrefs(prev => {
+        const next = { ...(prev?.lan?.aliases ?? {}) };
+        if (name) next[fp] = name; else delete next[fp];
+        return { lan: { aliases: next } };
+      });
       await lanEngine.apply({ aliases: _prefs.lan.aliases });
       return send(res, 200, { ok: true, ...lanEngine.status() });
     }
@@ -3630,7 +4220,7 @@ async function handleLanPeer(req, res) {
  *  dialog. A deck that only calls in has no address here, and says so rather
  *  than reporting a round that asked nobody. */
 async function handleLanSync(req, res) {
-  const raw = await readBody(req).catch(() => null);
+  const raw = await readBody(req, res).catch(() => null);
   let body = null;
   try { body = JSON.parse(raw ?? ""); } catch { /* the whole-list press sends nothing to read */ }
   const fp = body && typeof body.fp === "string" ? body.fp : null;
@@ -3670,9 +4260,14 @@ function pushEvent(raw, source, opts = {}) {
     // 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),
+    // Decided once, here, beside the charge and for the same reason: eviction
+    // must never have to look at a payload again to know what it is giving
+    // back. See LAST_VALUE_WINS.
+    [ENRICHMENT]: raw != null && typeof raw === "object" && LAST_VALUE_WINS.has(raw.hook_event_name),
   };
   events.push(evt);
   bufferedChars += evt[CHARS];
+  if (!evt[ENRICHMENT]) bufferedHookEvents++;
 
   // 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.
@@ -3702,16 +4297,33 @@ function pushEvent(raw, source, opts = {}) {
   // 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.
+  //
+  // THE COUNT BOUND IS HOOK EVENTS, NOT ENTRIES (#1032). It was entries, and
+  // the deck pushes about 1.6 derived events per hook event — so the window
+  // this ring IS shrank with the session count, to 9.5 measured seconds at 200
+  // sessions. Counting only what a user actually did restores a 2,000-event
+  // window at any number of sessions, and costs the array room for the
+  // enrichment interleaved among them, which MAX_RING_ENTRIES and
+  // MAX_BUFFER_CHARS both still bound.
+  //
+  // Enrichment falls off the head exactly as it always did — no entry is
+  // skipped, held back or reordered, and the ring stays contiguous in seq.
+  // What changed is only which entries the budget is spent on.
   let drop = 0;
   let freed = 0;
+  let freedHookEvents = 0;
   while (drop < events.length - 1
-    && (events.length - drop > MAX_BUFFER || bufferedChars - freed > MAX_BUFFER_CHARS)) {
+    && (bufferedHookEvents - freedHookEvents > MAX_BUFFER
+      || events.length - drop > MAX_RING_ENTRIES
+      || bufferedChars - freed > MAX_BUFFER_CHARS)) {
     freed += events[drop][CHARS];
+    if (!events[drop][ENRICHMENT]) freedHookEvents++;
     drop++;
   }
   if (drop > 0) {
     events.splice(0, drop);
     bufferedChars -= freed;
+    bufferedHookEvents -= freedHookEvents;
   }
 
   // Does this event reach the log at all? Not on a replay (it came from
@@ -3807,9 +4419,12 @@ function pushEvent(raw, source, opts = {}) {
     // does: the string being written is the one serialization of the event the
     // SSE frame also used, and the token was taken out of the payload before
     // either existed.
-    appendLogLine(persistPath, json + "\n");
-    // Cheap throttled check (every 30s) — only rotates if file > 50MB.
-    maybeRotatePersistFile();
+    const line = json + "\n";
+    appendLogLine(persistPath, line);
+    // Throttled check — every 30s, or every fifth of the threshold written,
+    // whichever comes first. The byte arm is what keeps the 50 MB cap from
+    // being advisory at any real ingest rate; see maybeRotatePersistFile.
+    maybeRotatePersistFile(Buffer.byteLength(line));
   }
 
   // Note the session so the caches the scanners below fill can expire by
@@ -3891,10 +4506,12 @@ function pushEvent(raw, source, opts = {}) {
  *
  * 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.
+ *   * `__clear` — the control marker `/api/clear` pushes, with `cwd: ""`. It is
+ *     not a session event; it is the instruction that makes the reducer forget
+ *     everything before it. It has not been written to the log since #698, but
+ *     logs the decks before that wrote still carry it, and dropping it on a
+ *     scoped deck would replay the state a user had explicitly cleared, so it
+ *     is always admitted.
  *   * a payload with no cwd and no session the map has seen — refused on a
  *     scoped deck, which is exactly what `capturesSession` decides live for a
  *     session that never said where it runs.
@@ -3907,8 +4524,38 @@ function pushEvent(raw, source, opts = {}) {
  *   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") {
+export function replayScope(workspace, platform = process.platform, providers = null) {
+  // WHICH CLIS THIS DECK IS WATCHING, and the half of `--no-codex` that did not
+  // exist (#1004). Live capture is gated on the provider — `if (codex)
+  // startCodexWatcher(...)`, and the Claude hook is only installed when
+  // `_providers.claude` — and the boot replay was not, so a deck started with
+  // `--no-codex` printed
+  //
+  //     Codex sessions   skipped — no ~/.codex/, or --no-codex
+  //
+  // and then filled its canvas with Codex sessions out of the machine-wide
+  // events.jsonl, frozen mid-turn, which no live path could ever close because
+  // the watcher that would have is the one that was skipped. Measured on a log
+  // of two Claude lines and two Codex lines replayed with `codex: false`:
+  //
+  //     in the ring: [ 'claude:claude-1:SessionStart', 'claude:claude-1:PreToolUse',
+  //                    'codex:codex-1:SessionStart',  'codex:codex-1:PreToolUse' ]
+  //
+  // The mirror case is worse: a `--no-claude` deck replays Claude sessions while
+  // `providers.claude` is false, so App.tsx hides the accounts panel and the
+  // sound controls — sessions on screen the deck has deliberately taken the
+  // controls for away.
+  //
+  // It costs one comparison per line. `provider: "codex"` is stamped on every
+  // payload the Codex watcher emits, its cwd-less enrichment included, and the
+  // Claude side is the complement — which is what types.ts already says
+  // `provider` means ("defaults to claude for replay events written before
+  // multi-provider support"). So this needs no per-session memory of its own and
+  // leaves `orderDependent` alone.
+  const claudeOn = providers?.claude !== false;
+  const codexOn = providers?.codex !== false;
+  const scoped = !!workspace && typeof workspace === "string";
+  if (!scoped && claudeOn && codexOn) {
     const all = () => true;
     // Every caller gets the same answer for the same payload, forever. That is
     // what lets replayLog read the log from its end — see `orderDependent` on
@@ -3932,12 +4579,17 @@ export function replayScope(workspace, platform = process.platform) {
    * whenever it is set. Making a scoped replay cheap needs an index of where a
    * workspace's lines are, which is a different change from this one.
    */
-  admits.orderDependent = true;
+  admits.orderDependent = scoped;
   return admits;
 
   function admits(payload) {
     if (!payload || typeof payload !== "object") return false;
     if (payload.hook_event_name === "__clear") return true;
+    // The provider gate, ahead of the workspace one and exempting `__clear` for
+    // the same reason it does: the marker carries no provider, and a deck that
+    // dropped it would replay a canvas the user had explicitly cleared.
+    if (!(payload.provider === "codex" ? codexOn : claudeOn)) return false;
+    if (!scoped) return true;
     const sid = typeof payload.session_id === "string" ? payload.session_id : null;
     const cwd = typeof payload.cwd === "string" && payload.cwd !== "" ? payload.cwd : null;
     if (cwd) {
@@ -3950,6 +4602,32 @@ export function replayScope(workspace, platform = process.platform) {
   };
 }
 
+/**
+ * Can this log fill the ring on its own?
+ *
+ * Read from the END and bounded by the ring, so the answer costs at most one
+ * ring's worth of parsing however large the file is — and on a full log it
+ * stops within the first few hundred lines. Deliberately UNSCOPED: the number
+ * it returns is an upper bound on what any workspace predicate will admit, so
+ * `false` is a certainty that the archive is needed while `true` is only the
+ * absence of evidence that it is. See the order-dependent branch of replayLog
+ * for why that asymmetry is the right way round.
+ */
+async function fillsRing(filePath, maxEvents, maxChars) {
+  let n = 0;
+  let chars = 0;
+  for await (const line of linesFromEnd(filePath)) {
+    if (!line) continue;
+    let evt;
+    try { evt = JSON.parse(line); } catch { continue; }
+    if (!evt || typeof evt !== "object" || !evt.payload) continue;
+    n++;
+    chars += ENVELOPE_CHARS + payloadChars(evt.payload);
+    if (n >= maxEvents || chars >= maxChars) return true;
+  }
+  return false;
+}
+
 /**
  * Read the log back into the ring buffer at boot.
  *
@@ -4023,12 +4701,37 @@ export function replayScope(workspace, platform = process.platform) {
  * MiB — which is why the count bound was the only one anything pinned, and why
  * the byte bound was the one that broke. Production passes neither argument. */
 export async function replayLog(filePath, workspace = "", {
-  maxEvents = MAX_BUFFER, maxChars = MAX_BUFFER_CHARS,
+  maxEvents = MAX_BUFFER, maxChars = MAX_BUFFER_CHARS, providers = null,
 } = {}) {
-  if (!existsSync(filePath)) return 0;
+  // THE ARCHIVE IS PART OF THE HISTORY, and for two years nothing read it.
+  // `maybeRotatePersistFile` renames events.jsonl to events.jsonl.1 at 50 MB;
+  // a grep for `.1` across src/ and bin/ finds the write, the copy deck-home's
+  // migration makes, and two comments. replayLog is called once, with
+  // `persistPath` alone. So the boot immediately after a rotation replays a
+  // file holding a handful of lines while 50 MB of history sits beside it
+  // unread — and the next rotation's `unlink` deletes it outright. Measured:
+  // one rotation, then `replayLog(events.jsonl)` returning 1.
+  //
+  // The reader below already stops the moment EITHER of the ring's bounds is
+  // reached, so on a log that can fill the ring on its own this costs nothing
+  // at all: the archive is never opened. It is read only when the live log
+  // cannot fill the ring, which is exactly the window a rotation opens.
+  //
+  // A Clear opens the same window and means the opposite by it. It empties the
+  // live log, which can then fill nothing, so reading on into the archive put
+  // back precisely what the user had cleared (#1130) — which is why a Clear
+  // removes the archive as well as emptying the live log, rather than this
+  // learning to tell the two kinds of empty apart. See handleClear.
+  const archivePath = filePath + ".1";
+  const liveThere = existsSync(filePath);
+  const archiveThere = existsSync(archivePath);
+  if (!liveThere && !archiveThere) return 0;
   let skipped = 0;
   let skippedBytes = 0;
-  const admits = replayScope(workspace);
+  // `providers` is the second scope this deck has, and it goes the same way the
+  // first one does — into the predicate, so the replay rule stays pinned equal
+  // to the live rule rather than being a second notion of it. See replayScope.
+  const admits = replayScope(workspace, process.platform, providers);
   const replay = (evt) =>
     pushEvent(evt.payload, evt.source ?? "replay", { receivedAt: evt.receivedAt, replay: true });
   const parse = (line) => {
@@ -4044,12 +4747,31 @@ export async function replayLog(filePath, workspace = "", {
 
   let count = 0;
   if (admits.orderDependent) {
-    for await (const line of linesFromStart(filePath)) {
-      if (!line) continue;
-      const evt = parse(line);
-      if (!usable(evt) || !admits(evt.payload)) continue;
-      replay(evt);
-      count++;
+    // Oldest first, so the archive comes BEFORE the live log — `admits` is
+    // stateful and answers from what it has already seen, which is the whole
+    // reason this branch reads forwards at all.
+    //
+    // Whether the archive is worth reading is decided by a probe rather than by
+    // this branch's own reader, because this branch has no stopping rule: it
+    // pushes everything and lets the ring evict. The probe reads the LIVE log
+    // backwards, unscoped, and is bounded by the ring, so it costs at most one
+    // ring's worth of parsing from the end of the file and nothing more. An
+    // unscoped count is an upper bound on what scoping will admit, so "this
+    // cannot fill the ring" is certain when the probe says so — and when it
+    // says the opposite a scoped deck may still under-fill, which is precisely
+    // what it does today. Nothing regresses; the case a rotation creates, where
+    // the live log holds a handful of lines, is the one that is fixed.
+    const files = [];
+    if (archiveThere && !(liveThere && await fillsRing(filePath, maxEvents, maxChars))) files.push(archivePath);
+    if (liveThere) files.push(filePath);
+    for (const file of files) {
+      for await (const line of linesFromStart(file)) {
+        if (!line) continue;
+        const evt = parse(line);
+        if (!usable(evt) || !admits(evt.payload)) continue;
+        replay(evt);
+        count++;
+      }
     }
   } else {
     // Newest first, so this is filled back to front and then walked in reverse
@@ -4069,16 +4791,24 @@ export async function replayLog(filePath, workspace = "", {
     // records logs reaching gigabytes.
     const newestFirst = [];
     let stagedChars = 0;
-    for await (const line of linesFromEnd(filePath)) {
-      if (!line) continue;
-      const evt = parse(line);
-      if (!usable(evt) || !admits(evt.payload)) continue;
-      newestFirst.push(evt);
-      stagedChars += ENVELOPE_CHARS + payloadChars(evt.payload);
-      // Everything older than this would be evicted by the events already held,
-      // so reading further is work whose only result is throwing it away.
-      // Either limit reaching its ceiling means exactly that.
+    // Newest generation first. The second pass runs only if the first stopped
+    // because it ran out of FILE rather than because it reached a bound, which
+    // is the "cannot fill the ring" test stated exactly and for free — and it
+    // is also why a full live log never opens the archive at all.
+    for (const file of liveThere ? [filePath, archivePath] : [archivePath]) {
+      if (!existsSync(file)) continue;
       if (newestFirst.length >= maxEvents || stagedChars >= maxChars) break;
+      for await (const line of linesFromEnd(file)) {
+        if (!line) continue;
+        const evt = parse(line);
+        if (!usable(evt) || !admits(evt.payload)) continue;
+        newestFirst.push(evt);
+        stagedChars += ENVELOPE_CHARS + payloadChars(evt.payload);
+        // Everything older than this would be evicted by the events already held,
+        // so reading further is work whose only result is throwing it away.
+        // Either limit reaching its ceiling means exactly that.
+        if (newestFirst.length >= maxEvents || stagedChars >= maxChars) break;
+      }
     }
     for (let i = newestFirst.length - 1; i >= 0; i--) replay(newestFirst[i]);
     count = newestFirst.length;
@@ -4095,6 +4825,13 @@ export async function replayLog(filePath, workspace = "", {
 }
 
 function send(res, status, body, headers = {}) {
+  // ALREADY ANSWERED. A handler that replies after something upstream has
+  // already written a status would otherwise throw ERR_HTTP_HEADERS_SENT out
+  // of the route and become a 500 — or, on a streamed answer, corrupt it. The
+  // oversize path below relies on this: readBody answers 413 itself and then
+  // rejects into a caller whose own `send(res, 400, ...)` must be a no-op
+  // rather than a second reply.
+  if (res.headersSent) return;
   res.writeHead(status, {
     "Content-Type": "application/json; charset=utf-8",
     "Cache-Control": "no-store",
@@ -4206,6 +4943,8 @@ export async function writeJsonArray(res, items) {
   res.end(frame === "[" ? "[]" : "]");
 }
 
+import { cacheControlFor, encodedBody, pickEncoding } from "./static-cache.mjs";
+
 async function serveStatic(req, res, url) {
   // Strip leading slash, default to index.html
   let rel = url.pathname.replace(/^\/+/, "");
@@ -4217,11 +4956,21 @@ async function serveStatic(req, res, url) {
     const s = await stat(filePath);
     if (s.isDirectory()) return send(res, 404, { error: "not found" });
     const buf = await readFile(filePath);
+    const ext = extname(filePath).toLowerCase();
+    // Compressed when the browser takes it, and cached for good when the name
+    // is a content hash (#883) — see static-cache.mjs. `rel` is the URL's own
+    // spelling, forward slashes on every platform, which is what the hash
+    // pattern reads; `filePath` is only the cache key.
+    const encoding = pickEncoding(req.headers["accept-encoding"], ext);
+    const body = encoding ? encodedBody(filePath, s.mtimeMs, buf, encoding) : buf;
     res.writeHead(200, {
-      "Content-Type": MIME[extname(filePath).toLowerCase()] ?? "application/octet-stream",
-      "Cache-Control": "no-cache",
+      "Content-Type": MIME[ext] ?? "application/octet-stream",
+      "Cache-Control": cacheControlFor(rel),
+      "Vary": "Accept-Encoding",
+      "Content-Length": body.length,
+      ...(encoding ? { "Content-Encoding": encoding } : {}),
     });
-    res.end(buf);
+    res.end(body);
   } catch {
     // SPA fallback to index.html for client-side routes
     try {
@@ -4238,25 +4987,61 @@ async function serveStatic(req, res, url) {
   }
 }
 
-/** Collect a request body as a string, capped so a bad client can't fill memory. */
-function readBody(req, limit = 64_000) {
+// How long an oversized POST is drained after it has been refused, so the 413
+// reaches a poster that is still uploading. Generous next to hook.js's own
+// one-second budget, and finite so nothing can sit on the socket indefinitely.
+const OVERSIZE_DRAIN_MS = 10_000;
+
+/**
+ * Collect a request body as a string, capped so a bad client can't fill memory.
+ *
+ * IT ANSWERS BEFORE IT HANGS UP, which it did not. `req.destroy()` ran ahead of
+ * the reject, so the caller's own `send(res, 400, ...)` had no socket left to
+ * write to: every one of the eleven routes through here replied to an oversized
+ * body with a bare connection reset. Measured with a 70 KB body — `curl` exit
+ * 56, "failure receiving network data", no status line, and nothing in the log.
+ * `POST /api/lan/sync` is the one that matters, because its caller is another
+ * deck rather than a person: it saw a reset it could not tell from a deck that
+ * had died, and reported a network error rather than "too big".
+ *
+ * handleEventIngest was fixed for exactly this and its comment asserts this
+ * function already got it right. It did not; this is that fix, in the shape
+ * that one worked out and documents at length:
+ *
+ *   • answer 413 here, so there is a status on the wire;
+ *   • keep reading and throw it away, because the poster is still mid-upload
+ *     and hanging up now lands its next write on a dead socket — it aborts with
+ *     EPIPE and discards the answer already sitting in its receive buffer;
+ *   • bound the drain, because draining forever is its own denial of service.
+ *
+ * The reject still fires, so the callers' `.catch(() => null)` and their
+ * `send(res, 400, ...)` are unchanged — `send` is a no-op once the headers have
+ * gone out.
+ */
+function readBody(req, res = null, limit = 64_000) {
   return new Promise((resolve, reject) => {
     let body = "";
+    let refused = false;
     req.setEncoding("utf8");
     req.on("data", c => {
+      if (refused) return;
       body += c;
-      if (body.length > limit) { req.destroy(); reject(new Error("body too large")); }
+      if (body.length > limit) {
+        refused = true;
+        body = "";
+        if (res) send(res, 413, { error: "body too large" });
+        req.resume();
+        const grace = setTimeout(() => req.destroy(), OVERSIZE_DRAIN_MS);
+        grace.unref?.();
+        req.on("close", () => clearTimeout(grace));
+        reject(new Error("body too large"));
+      }
     });
-    req.on("end", () => resolve(body));
+    req.on("end", () => { if (!refused) resolve(body); });
     req.on("error", reject);
   });
 }
 
-// How long an oversized POST is drained after it has been refused, so the 413
-// reaches a poster that is still uploading. Generous next to hook.js's own
-// one-second budget, and finite so nothing can sit on the socket indefinitely.
-const OVERSIZE_DRAIN_MS = 10_000;
-
 // `persist` is false when the hook posted this event to another deck as well
 // and elected that one to write it to the log they share. The event is still
 // buffered and broadcast here — every matching deck draws it — it is only the
@@ -4279,8 +5064,10 @@ function handleEventIngest(req, res, persist = true) {
       // the connection had gone — indistinguishable from a deck that died or
       // was never there, and nothing in the exchange to tell those apart. `end`
       // never fires on a destroyed request either, so the handler below got no
-      // second chance to speak. readBody above gets this right already, by
-      // rejecting into a caller that replies.
+      // second chance to speak. readBody above was believed to get this right
+      // by rejecting into a caller that replies; it destroyed the socket first,
+      // so all eleven of its routes answered an oversized body with the same
+      // bare reset. It answers and drains now, in this shape.
       send(res, 413, { error: "event too large" });
       // Then keep reading, and throw it away. Answering is not enough on its
       // own, because the poster is still mid-upload when the answer goes out:
@@ -4412,13 +5199,15 @@ async function resumeSse(req, res, lastId) {
     for (const e of batch) {
       if (e.seq <= sentThrough) continue;
       if (closed || res.destroyed) return;
-      // Marked with `replay:true` on the envelope so the client can suppress
-      // turn-cleanup side effects (exitAt stamping, autofit churn) until the
-      // live stream takes over. Without this the reducer's UserPromptSubmit
-      // handler treats replayed events as a real new turn — hiding prior-turn
-      // subagents using the event's stale receivedAt, which collides with
-      // wall-clock visibility gates and yields the "nodes appear then vanish"
-      // symptom on refresh.
+      // Marked with `replay:true` on the envelope for the page, which reads it in
+      // two places: the SSE handler coalesces renders while it is set and draws
+      // once at `replay-end`, and `chimeFor` stays quiet for it, so a reconnect
+      // does not play every Stop in the ring. The reducer never reads it — its
+      // turn cleanup keys on each event's own time, which comes out right for
+      // replayed and live events alike (HookEnvelope.replay in types.ts, and
+      // dead-surface-993 pins it). This used to say the reducer's
+      // UserPromptSubmit handler depended on the tag to tell a replayed prompt
+      // from a new turn; nothing there reads it.
       const tagged = { ...e, replay: true };
       // Through envelopeJson for the reason writeJsonArray is: the ring may be
       // holding an envelope `JSON.stringify` cannot walk. pushEvent takes the
@@ -4471,6 +5260,82 @@ async function resumeSse(req, res, lastId) {
 // Without persistence a restart wipes the canvas irrecoverably — replayLog has
 // no file to read — so the deck must not offer to do it.
 let _canRestart = false;
+// And a log that cannot be written is the same thing wearing a different hat.
+// This was a test of CONFIGURATION — `_onRestart != null && persist != null` —
+// so a deck whose `--history` named a read-only volume, a full one, or a
+// removable drive that was later unmounted answered `canRestart: true` while
+// not one event reached disk. Measured: 10 of 10 posts acknowledged, no file on
+// disk, `canRestart: true`. The press then lands on replayLog's
+// `if (!existsSync(filePath)) return 0` and takes the whole session history
+// with it — which is precisely the loss the flag exists to prevent.
+let _persistWritable = false;
+// How many lines had landed on `persistPath` when the probe answered. Read by
+// logWritableNow and nothing else; see appendsLanded.
+let _landedAtProbe = 0;
+
+/**
+ * Is the log this deck was told to keep being written, on the newest evidence?
+ *
+ * `_persistWritable` answered this alone, and it is the boot probe's answer:
+ * nothing after the boot could change it. The gate it fed had a closing edge —
+ * a failing append opens an episode, and an episode shut the gate — and no
+ * opening one. MEASURED on a sandboxed deck (#1130), a log whose parent was a
+ * file at boot and a directory a moment later, which is what a mount that
+ * comes up late or a permission that is fixed leaves behind: a line on disk,
+ * the failure count at 0, and `canRestart` false for the life of the process.
+ *
+ * The appender is the evidence, and it already produces it: every line either
+ * lands or fails, and log-writer counts both. So the answer is whichever of the
+ * two sources spoke LAST. An open failure episode means the newest append
+ * failed, whatever came before it. Otherwise a line landed since the probe
+ * means the newest evidence is a write that worked, whatever the probe said;
+ * and with neither, the probe is still the newest thing anyone knows.
+ *
+ * No syscall is added anywhere for it. The probe stays the one at boot, the
+ * episode is the one #1062 keeps, and what an event pays is one counter
+ * increment in log-writer's landing handler, beside the episode lookup that
+ * handler already makes.
+ */
+function logWritableNow() {
+  if (!persistPath) return false;
+  if (appendFailureStats(persistPath).failing > 0) return false;
+  return _persistWritable || appendsLanded(persistPath) > _landedAtProbe;
+}
+
+/**
+ * Can this deck be restarted without losing the canvas?
+ *
+ * Asked at the moment of the press rather than read off a boot-time flag,
+ * because the writable half of it changes while the deck runs, and in both
+ * directions: a drive unmounted or a volume filled mid-session is discovered by
+ * the appender, not by the probe, and so is one that comes back. See
+ * logWritableNow.
+ */
+function canRestartNow() {
+  return _canRestart && logWritableNow();
+}
+
+/**
+ * Is the log this deck was told to keep actually writable?
+ *
+ * One `open(path, "a")` and one close — the same pair every append pays, asked
+ * once at boot so the answer is known before the first event rather than after
+ * the first silent loss. It CREATES the file, which is what an append would do
+ * anyway and what makes the probe honest about the directory as well as the
+ * file: EROFS, EACCES and ENOENT all surface here.
+ */
+async function probeLogWritable(path) {
+  let handle = null;
+  try {
+    handle = await open(path, "a");
+    return true;
+  } catch (err) {
+    console.error(`${PRODUCT}: the event log ${path} is not writable (${err && err.message ? err.message : err}) — Restart is disabled until an event reaches it, because it would replay a log this deck is not filling`);
+    return false;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
 
 async function handleVersion(req, res) {
   const { versionReport } = await import(
@@ -4513,7 +5378,7 @@ async function handleVersion(req, res) {
   // default em dash is what a browser should get.
   const rename = renameNotice({ invoked, pkgRoot: PKG_ROOT });
   send(res, 200, {
-    ...report, canRestart: _canRestart, invokedAs: invoked, renameFix: rename?.fix ?? null,
+    ...report, canRestart: canRestartNow(), invokedAs: invoked, renameFix: rename?.fix ?? null,
   });
 }
 
@@ -4525,6 +5390,11 @@ async function handleUpgrade(_req, res) {
   const { startUpgrade } = await import(
     pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href
   );
+  // Every module this process will ever load, loaded BEFORE npm starts
+  // rewriting the tree they come from — see PINNED_MODULES. On a deck that has
+  // finished booting this settled long ago; it only waits for a press that
+  // lands in the first moments of a boot, or on a server nothing marked ready.
+  await pinRunningBuild();
   const out = startUpgrade({ pkgRoot: PKG_ROOT });
   send(res, out.ok ? 200 : 409, out);
 }
@@ -4542,10 +5412,15 @@ async function handleRestart(req, res) {
   // the whole canvas — replayLog has no file to read — and a destructive act
   // must not be prevented by a hidden button alone.
   if (!_canRestart) return send(res, 409, { ok: false, reason: "no_persist" });
+  // A configured log that cannot be written is the same destruction by another
+  // route, and it deserves its own word: "no_persist" would tell a user who
+  // passed `--history` that they had not, which is the sort of answer that
+  // sends someone looking in the wrong place. See canRestartNow.
+  if (!canRestartNow()) return send(res, 409, { ok: false, reason: "log_unwritable" });
 
   let wantUpgrade = false;
   if (req.method === "POST") {
-    const body = await readBody(req).catch(() => null);
+    const body = await readBody(req, res).catch(() => null);
     try { wantUpgrade = JSON.parse(body ?? "")?.upgrade === true; } catch { /* a plain restart */ }
   }
   let mode = null;
@@ -4620,9 +5495,18 @@ export function releaseRestart() {
  *
  *  Only /api/restart reads it, and only to answer honestly. Nothing is refused
  *  on the strength of it: the restart is still handed to the launcher, which
- *  holds it until it can run it (#448). */
+ *  holds it until it can run it (#448).
+ *
+ *  IT IS ALSO WHERE THE BUILD IS PINNED (#1042) — see PINNED_MODULES. After the
+ *  boot, so the laziness still keeps that work off the path to the socket; and
+ *  before anything can replace the tree, because `npm i -g` typed in a terminal
+ *  rewrites it exactly as startUpgrade's does, and the drift path then leaves
+ *  this process serving until an idle moment just the same. The promise is
+ *  handed back for the test that has to know when the pin has landed;
+ *  bin/deck.js has no reason to wait for it, and it never rejects. */
 export function markDeckReady() {
   _deckReady = true;
+  return pinRunningBuild();
 }
 
 /**
@@ -4669,13 +5553,21 @@ async function handleStop(req, res) {
   send(res, 200, { ok: true, pid: process.pid });
 }
 
+/**
+ * WITH A DEADLINE OF ITS OWN (#1011). Source 3 is `claude --print /usage`, and
+ * its cost is the sum of three spawns under a 15-second timeout with two
+ * 1.2-second sleeps between them — 47.4 seconds, measured — which nothing here
+ * had ever added up. The budget is quota.mjs's, because the "not yet" answer it
+ * expires into is made of that module's own last-known-good reading; the read
+ * carries on behind it and publishes for the next poll.
+ */
 async function handleQuota(req, res) {
-  const { fetchClaudeQuota } = await import(
+  const { fetchClaudeQuota, QUOTA_DEADLINE_MS } = await import(
     pathToFileURL(join(PKG_ROOT, "src/server/quota.mjs")).href
   );
   const url = new URL(req.url, "http://localhost");
   const force = url.searchParams.get("refresh") === "1";
-  const quota = await fetchClaudeQuota({ force });
+  const quota = await fetchClaudeQuota({ force, deadlineMs: QUOTA_DEADLINE_MS });
   send(res, 200, quota);
 }
 
@@ -4734,7 +5626,7 @@ export const isCliDate = (v) => v === undefined || /^\d{8}$/.test(v);
  * reaches a handler, which is exactly the pair a GET deliberately skips.
  */
 async function handleBrowserWatchSettings(req, res) {
-  const raw = await readBody(req).catch(() => null);
+  const raw = await readBody(req, res).catch(() => null);
   let body = null;
   try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
   if (!body || typeof body !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
@@ -4788,7 +5680,7 @@ async function handleBrowserWatchDismiss(req, res) {
   // isAuthorizedMutation on every non-GET before a handler sees it, which is
   // the pair its GET twin deliberately skips. A second check here would be a
   // second thing to keep correct.
-  const raw = await readBody(req).catch(() => null);
+  const raw = await readBody(req, res).catch(() => null);
   let body = null;
   try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
   const host = typeof body?.host === "string" ? body.host : null;
@@ -4801,10 +5693,18 @@ async function handleBrowserWatchDismiss(req, res) {
   const { invalidateBrowserWatchCache, noteWatchSetting } = await import(
     pathToFileURL(join(PKG_ROOT, "src/server/browser-watch.mjs")).href
   );
-  const store = await readStore();
+  // COMPUTED INSIDE THE JOB, like the settings route four lines up, whose
+  // comment says why: "updateStore re-reads inside the write queue, so a poll
+  // that landed between the read above and this line cannot have its archive
+  // thrown away." This read the whole `dismissed` array before the queue, so
+  // two Dismiss presses in one turn both read before either job ran and the
+  // second wrote an array without the first key — both rows left the list,
+  // both answered 200, and the first came back on the next ten-second poll.
   const key = episodeKey(host, startMs);
-  const dismissed = [...new Set([...(store.dismissed ?? []), key])];
-  await updateStore(cur => ({ ...cur, dismissed }));
+  await updateStore(cur => ({
+    ...cur,
+    dismissed: [...new Set([...(cur.dismissed ?? []), key])],
+  }));
   // The reader acting on their own list, which is exactly the kind of line the
   // `act` level exists for.
   noteWatchSetting(`dismissed ${host}`);
@@ -4896,7 +5796,7 @@ async function handleClaudeAccountSwitch(req, res) {
   const { switchClaudeAccount, invalidateClaudeAccountsCache } = await import(
     pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href
   );
-  const body = await readBody(req).catch(() => null);
+  const body = await readBody(req, res).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" });
@@ -4944,7 +5844,7 @@ async function handleAccountLoginState(_req, res) {
  */
 async function handleClaudeAccountAdmin(req, res) {
   const admin = await cswapAdminModule();
-  const body = await readBody(req).catch(() => null);
+  const body = await readBody(req, res).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" });
@@ -4980,6 +5880,84 @@ function cswapAutoModule() {
   return import(pathToFileURL(join(PKG_ROOT, "src/server/cswap-auto.mjs")).href);
 }
 
+/**
+ * Every server module this process reaches only through `import()`, and so
+ * reads off disk the first time it is wanted rather than at boot.
+ *
+ * THAT IS WHAT A SELF-UPDATE BROKE (#1042). Node caches an evaluated module by
+ * its URL for the life of the process, so everything already loaded keeps the
+ * code it booted with — which is the whole of why startUpgrade can leave this
+ * process serving and let the drift path restart it at an idle moment. A module
+ * NOT yet loaded had no such protection: PKG_ROOT is a fixed path, and
+ * `npm i -g` rewrites the tree under it. So the first look at the accounts panel
+ * after an install evaluated the NEW cswap-admin.mjs beside the OLD
+ * claude-accounts.mjs and exec.mjs — a mixed build nobody has ever run — and
+ * while npm was mid-reify the same `import()` found no file at all, which
+ * lan-engine's roundWith catches and files as that PEER's failed round: a
+ * credential sync that did not happen, recorded against the other machine
+ * rather than against the install. The window is not short. The idle
+ * restart waits on presence and activity, and with autoUpdate off it never
+ * comes.
+ *
+ * Reproduced with the tree swap done in a temp copy of the package: after
+ * `POST /api/upgrade`, every one of /api/codex-usage, /api/codex-quota,
+ * /api/browser-watch and /api/claude-accounts/login answered 500, and each one
+ * had evaluated a module out of the tree npm had just written.
+ *
+ * So the build is pinned instead. Each module below is imported once, after
+ * the boot (markDeckReady) and before any install can start (handleUpgrade and
+ * awayUpdateTick both await it), and every lazy import in this file is a cache
+ * hit from then on; their own static imports come with them. Measured, the
+ * whole list costs about 10ms and 8MB of RSS, and none of it does any work at
+ * import — nothing is spawned, read or written — so the laziness still does
+ * what it was for, which is keeping all of this off the path between
+ * `npx ccdeck` and a listening socket.
+ *
+ * The list is every local module that an `import()` in src/server names, and
+ * self-update-pins-build.test.ts reads the directory to keep it that way: a lazy
+ * import added later without a line here is this bug again.
+ */
+const PINNED_MODULES = [
+  "self-update.mjs",
+  "claude-accounts.mjs",
+  "cswap-admin.mjs",
+  "cswap-auto.mjs",
+  "quota.mjs",
+  "codex-usage.mjs",
+  "codex-quota.mjs",
+  "ccusage.mjs",
+  "browser-watch.mjs",
+  "browser-watch-store.mjs",
+  // system-metrics.mjs's two, on the platforms that have them, and the one
+  // installer.mjs reaches for while it rewrites the hooks.
+  "macmon.mjs",
+  "hwmonitor.mjs",
+  "retire-sound-hook.mjs",
+];
+
+let _pinned = null;
+
+/**
+ * Load every module in PINNED_MODULES, once per process.
+ *
+ * One at a time rather than all together. It costs nothing measurable, and it
+ * means no two of them are ever evaluating at once — the shape that turned an
+ * import cycle into an empty namespace (see boot-module-graph.test.ts).
+ *
+ * A module that fails to load is passed over rather than allowed to stop the
+ * rest: waiting will not make it load, and one bad file must not leave the
+ * others to be read off whatever npm writes next. The promise never rejects.
+ */
+export function pinRunningBuild() {
+  _pinned ??= (async () => {
+    for (const name of PINNED_MODULES) {
+      try { await import(pathToFileURL(join(PKG_ROOT, "src/server", name)).href); }
+      catch { /* see above */ }
+    }
+  })();
+  return _pinned;
+}
+
 async function handleCswapAuto(req, res) {
   const { autoStatus } = await cswapAutoModule();
   send(res, 200, await autoStatus());
@@ -4992,7 +5970,7 @@ async function handleCswapAuto(req, res) {
  */
 async function handleCswapAutoAction(req, res) {
   const mod = await cswapAutoModule();
-  const body = await readBody(req).catch(() => null);
+  const body = await readBody(req, res).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" });
@@ -5179,8 +6157,9 @@ export async function canonicalCwd(raw) {
 }
 
 /**
- * The deck's one irreversible action: empty the ring, and empty the log — but
- * only the log this deck is the one writing.
+ * The deck's one irreversible action: empty the ring, and empty the log — both
+ * of its generations, the live file and the archive rotation leaves beside it —
+ * 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,
@@ -5206,11 +6185,72 @@ export async function canonicalCwd(raw) {
  */
 async function handleClear(res) {
   const sharing = await logSharing();
+  const mineToEmpty = Boolean(sharing.path && sharing.mine);
+  // THE PRESS IS ONE SYNCHRONOUS MOMENT, from the ring being emptied to the
+  // marker being pushed, and the log's turn on the append queue is taken
+  // inside it. Nothing from here awaits until the marker is out, so no event
+  // can be pushed in the middle: every event is on one side of the press, and
+  // it is the same side for the board, the ring and the file.
+  //
+  //   * Pushed before it: out of the ring by clearEventBuffer, numbered below
+  //     the marker so the reducer forgets it, and queued before the truncate —
+  //     written, then erased.
+  //   * Pushed after it: numbered above the marker so the board keeps it, and
+  //     queued AFTER the truncate, so its write cannot begin until the file has
+  //     been emptied. That is why a Clear cannot take an event posted after it
+  //     along with it: the chain in log-writer.mjs is the only way this process
+  //     writes the log, and it starts each step only when the one before it has
+  //     settled.
+  //
+  // Both halves were broken in turn. #1005: the truncate consulted the queue in
+  // neither direction, so the queue drained PRE-CLEAR lines into the freshly
+  // emptied file — 564 bytes and three events of a cleared session, 2.5s after
+  // a Clear that answered `{"log":"cleared"}`. Its fix waited for the queue and
+  // then truncated beside it, but the wait was for the queue as it stood when
+  // the wait began, and the session went on posting through it: MEASURED
+  // (#1130), five runs, 4, 5, 3, 3 and 2 events the Clear had taken off the
+  // board were in the file a restart replays. See emptyLog.
+  //
+  // This is #698's residue by a different route, and it survives the ownership
+  // gate that fixed #698 precisely because it happens on the deck that DOES own
+  // the file.
+  //
   // 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(() => {});
+  // THE ARCHIVE GOES WITH IT. Since #1062 the replay reads events.jsonl.1
+  // whenever the live log cannot fill the ring, and a live log a Clear has just
+  // emptied never can — so a Clear on a log that had rotated once came back,
+  // whole, at the next boot. MEASURED (#1130): three events in the archive and
+  // one in the live log, `/api/clear` answering `log: "cleared"` over a live
+  // file of 0 bytes, and replayLog on the same path returning the three
+  // archived sessions.
+  //
+  // Removed, rather than fenced off by a `__clear` line the replay stops at,
+  // and the confirmation is why: it tells the user the history is gone and
+  // cannot be undone, and a marker would leave a whole rotated generation of it
+  // on disk behind a line asking readers not to look — readable by anything
+  // else that opens the file. It would also put back on disk the line #698
+  // took off it on purpose, and it would need a stopping rule the forwards
+  // replay does not have: that branch reads the archive FIRST, so it would push
+  // the cleared generation into the ring before it ever met the line saying to
+  // discard it. The ownership gate is the truncate's, and it covers the archive
+  // exactly: only the deck that writes a log may rotate it (#1062), so only
+  // that deck ever made its archive.
+  //
+  // Nothing else of the log's bookkeeping is reset, deliberately.
+  // `failedLines` / `failedChars` count what the DISK refused since this deck
+  // started, which a Clear does not change — `/api/health` documents them that
+  // way, and zeroing them would hide a volume that is still failing — and an
+  // open failure episode ends only on a line that lands, the one evidence that
+  // the condition is over, which a Clear is not. The rotation's byte count is
+  // a trigger for a `stat`, not a size: over-counting after a truncate costs at
+  // most one early look, which finds a small file and resets it. And a
+  // rotation running at the same moment needs nothing from here; emptyLog says
+  // why the order inside the turn is enough.
+  const emptyOutcome = {};
+  const emptied = mineToEmpty ? emptyLog(sharing.path, [sharing.path + ".1"], undefined, emptyOutcome) : null;
   // 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
@@ -5229,6 +6269,7 @@ async function handleClear(res) {
   // longer has it — here, and in forgetSession.
   outputWatch.clear();
   nameBySession.clear();
+  recapBySession.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
@@ -5238,9 +6279,37 @@ async function handleClear(res) {
   lastNameReadAt.clear();
   modelLastReadAt.clear();
   pushEvent({ hook_event_name: "__clear", cwd: "" }, "internal", { persist: false });
+  // The end of the press. Awaited, where the truncate used to be fired and
+  // forgotten, so the answer does not go out before the file has actually
+  // reached zero — and bounded by emptyLog, so a disk that does not come back
+  // in time still gets an answer, with the turn left on the chain in order.
+  if (emptied) await emptied;
+  // WHAT THE FILE ACTUALLY DID (#1140). This answered "cleared" for any log this
+  // deck owns, whatever the truncate had done: emptyLog keeps the queue moving
+  // by swallowing its error, and nothing read it back, so on a read-only volume
+  // the page was told the history was gone and the next boot replayed all of
+  // it. The canvas IS clear either way — the ring was emptied above — so this
+  // stays `ok`, and says which half did not happen, here and in the terminal.
+  // A turn still on the chain at the deadline has no error yet and keeps the
+  // answer it always had.
+  //
+  // AND THE ARCHIVE, for the same reason: one that survives a Clear is the whole
+  // history again at the next boot, because the replay falls back to it once the
+  // live log is empty (#1130). Either half failing makes the answer "failed", and
+  // each says which it was.
+  const truncateFailed = mineToEmpty && emptyOutcome.error ? emptyOutcome.error : null;
+  const archiveFailed = mineToEmpty && emptyOutcome.archiveError ? emptyOutcome.archiveError : null;
+  const failed = truncateFailed ?? archiveFailed;
+  if (truncateFailed) {
+    console.error(`${PRODUCT}: Clear could not empty the event log ${sharing.path} (${truncateFailed.code ?? truncateFailed.message}) — the canvas is clear, but that history will come back at the next boot`);
+  }
+  if (archiveFailed) {
+    console.error(`${PRODUCT}: Clear could not remove the event log's archive ${sharing.path}.1 (${archiveFailed.code ?? archiveFailed.message}) — the canvas is clear, but that history will come back at the next boot`);
+  }
   return send(res, 200, {
     ok: true,
-    log: !sharing.path ? "none" : sharing.mine ? "cleared" : "kept",
+    log: !sharing.path ? "none" : sharing.mine ? (failed ? "failed" : "cleared") : "kept",
+    ...(failed ? { error: failed.code ?? "EIO" } : {}),
     path: sharing.path,
     decks: sharing.decks,
     mine: sharing.mine,
@@ -5248,6 +6317,73 @@ async function handleClear(res) {
   });
 }
 
+/** The most session ids one press of this may name. A board holding more than
+ *  the server tracks at all cannot be describing anything the server still
+ *  remembers, and a body is not a reason to walk an unbounded list. */
+const MAX_FORGET_IDS = MAX_TRACKED_SESSIONS;
+
+/**
+ * POST /api/forget — the client's own pruners, saying what left the board.
+ *
+ * THE THIRD PLACE THE RULE HAD TO REACH (#1024). `handleClear`'s comment states
+ * it: "anything answering 'has this changed' has to appear in BOTH places that
+ * mean the client no longer has it — here, and in forgetSession." There was a
+ * third, and the server never heard about it — `pruneDoneSessions` and
+ * `pruneOldAgents` in the page, which run every 250ms at cap 6 / grace 2
+ * minutes, and #445's own measurement says 7 of 20 evicted sessions went on to
+ * emit more events.
+ *
+ * Usage, context and the ROOT model all come back on their own: the first two
+ * are not change-gated, and `pushEvent` stamps `raw.model` on every payload.
+ * `sessionName`/`sessionTitle` and the per-subagent models do not, because
+ * `nameBySession` and `modelBySession` still hold the signature that gates the
+ * emit. Measured against a real deck over a real transcript, sandboxed HOME:
+ *
+ *     SessionNamed while the session was on the board: ["reducer-audit"]
+ *     --- the client prunes S5, and tells nobody ---
+ *     events for S5 after the resume: UserPromptSubmit, UsageObserved,
+ *       UserPromptSubmit, UsageObserved, ContextObserved, …
+ *     SessionNamed among them: false
+ *
+ * A session evicted while idle and then resumed showed as unnamed in the sidebar
+ * and on the card for the rest of the day, with no way to recover but reloading
+ * the tab.
+ *
+ * `forgetSession` is the whole of the answer and it already exists — this route
+ * is the client's half of a call the server has been making to itself since the
+ * LRU cap was added. It drops the read stamps along with the signatures, for the
+ * reason `handleClear` lists them: clearing only the signatures would leave the
+ * next hook event inside MODEL_READ_THROTTLE_MS, so nothing would be re-read and
+ * the name would still be missing.
+ *
+ * NOT DROPPING THE CHANGE GATE INSTEAD, which was the other option in the
+ * report. The gate is what keeps a per-pass emit from becoming ~683 events
+ * saying nothing out of 685 records, and the reducer absorbing repeats correctly
+ * is not a reason to send them.
+ *
+ * Costs nothing when it is wrong. A session named here that the deck is still
+ * hearing from re-reads its transcript once and re-emits what it finds, which
+ * the reducer's assign-don't-append handlers apply idempotently.
+ */
+async function handleForget(req, res) {
+  const raw = await readBody(req).catch(() => null);
+  let body = null;
+  try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
+  const ids = Array.isArray(body?.ids) ? body.ids : null;
+  if (!ids) return send(res, 400, { ok: false, reason: "bad_request" });
+  let forgotten = 0;
+  for (const sid of ids.slice(0, MAX_FORGET_IDS)) {
+    if (typeof sid !== "string" || sid === "") continue;
+    // Out of the LRU as well, so the cap is not spent on a session nothing is
+    // tracking any more. A session that speaks again is re-inserted by
+    // `touchSession` as what it now is: one the deck has just heard from.
+    sessionTouchedAt.delete(sid);
+    forgetSession(sid);
+    forgotten++;
+  }
+  return send(res, 200, { ok: true, forgotten });
+}
+
 function handleHealth(_req, res) {
   send(res, 200, {
     ok: true,
@@ -5257,6 +6393,20 @@ function handleHealth(_req, res) {
     uptimeMs: Math.round(process.uptime() * 1000),
     workspace: _workspace,
     providers: _providers,
+    // WHETHER THE EVENTS BEING DRAWN ARE BEING KEPT. `seq` above counts what
+    // the deck accepted, and it counted a deck whose every append was failing
+    // exactly the same as one whose every append landed. `log` is the other
+    // half of that sentence: `writable` is the newest evidence about the log —
+    // the boot probe's answer until a line lands after it and the appender's
+    // from then on, the same answer the Restart gate reads (#1130) — `failing`
+    // says the appender is inside a failure episode right now, and
+    // `failedLines` / `failedChars` are what has been attempted and lost since
+    // this deck started.
+    //
+    // No path. The health probe is a deliberately open route and this is the
+    // smallest set of facts that answers the question; the path is already in
+    // the banner for anyone standing at the terminal.
+    log: persistPath ? { writable: logWritableNow(), ...appendFailureStats(persistPath) } : null,
   });
 }
 
@@ -5504,6 +6654,17 @@ function originMatchesHost(origin, host) {
 // pointed at; MAX_SCAN_BYTES_PER_PASS means no single POST walks more than 256
 // MiB of a file.
 //
+// #992 is the same question asked of the Codex half of this route, which the
+// paragraph above never covered. A `provider: "codex"` event carries a
+// `session_id` and no path, and the deck looks that id up by walking
+// $CODEX_HOME/sessions. A miss was never kept, so every id no rollout carries
+// walked the whole history again on every throttled pass, and a burst of fresh
+// ids walked it once each, all at once. What bounds it now is
+// findCodexRolloutPath: at most one walk of the whole tree per id in any
+// CODEX_MISS_TTL_MS, never two in flight, and every other lookup reads the
+// newest two day directories. A caller with an endless supply of fresh ids can
+// keep that one walk busy; it cannot make it two.
+//
 // 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
@@ -5666,13 +6827,40 @@ function isAuthorizedDataRead(req) {
   return originMatchesHost(headers.referer, headers.host);
 }
 
-/** The reads that carry the user's own work, rather than the machine's. */
+/** The reads that carry the user's own work, rather than the machine's.
+ *
+ *  `/api/lan` and `/api/prefs` were missing, and they are the same class of
+ *  secret as the four that were here. Measured against a running deck with a
+ *  request carrying no headers at all — the sandboxed subprocess with loopback
+ *  egress that isAuthorizedDataRead names above, or another UID on a shared
+ *  box — `/api/claude-accounts` answered 401 and `/api/lan` answered 200 with:
+ *
+ *    • `shared`, one `<email>@@<organization uuid>` per account this deck
+ *      offers — the address of every Claude login on the machine;
+ *    • `peers[].offers.accounts[]`, the same for every paired deck, plus each
+ *      one's LAN address, port, hostname, OS and ccdeck version;
+ *    • `invite`, whenever the owner has one open — and that one is a bearer
+ *      credential, not a description. readInvite -> connectToPeer({code}) ->
+ *      onInviteUsed pins the caller as trusted with nobody pressing anything,
+ *      and a trusted deck may then send `manifest` and `want` and receive the
+ *      sealed OAuth credentials for every shared account.
+ *
+ *  `/api/prefs` carries the narrower half: publicPrefs already strips
+ *  `lan.secret` and every `trusted[].pub`, which was the part that had to be
+ *  right, but it keeps `lan.shared` — the same addresses — and every trusted
+ *  peer's name and fingerprint.
+ *
+ *  Neither route has a caller outside the deck's own page, so guarding them
+ *  costs nothing: every fetch of both is in src/web, and a page's own GET
+ *  carries Sec-Fetch-Site: same-origin. */
 const GUARDED_READS = new Set([
   "/events",
   "/api/events",
   "/api/claude-accounts",
   "/api/claude-accounts/login",
   "/api/browser-watch",
+  "/api/lan",
+  "/api/prefs",
 ]);
 
 function isAuthorizedMutation(req) {
@@ -5823,7 +7011,7 @@ let _restarting = false;
 // is reachable in and cannot answer for on its own.
 let _deckReady = false;
 
-export async function startServer({ port = 4317, host = "127.0.0.1", persist = null, portRange = [4318, 4400], workspace = "", codex = true, claude = true, onRestart = null, onStop = null } = {}) {
+export async function startServer({ port = 4317, host = "127.0.0.1", persist = null, portRange = [4318, 4400], workspace = "", codex = true, claude = true, onRestart = null, onStop = null, cswapQuiet = null } = {}) {
   _onRestart = typeof onRestart === "function" ? onRestart : null;
   _onStop = typeof onStop === "function" ? onStop : null;
   _stopping = false;
@@ -5836,6 +7024,9 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
   // `!== false` rather than a cast: a caller that omits the field means "yes",
   // which is how every embedder that predates this option keeps working.
   _providers = { claude: claude !== false, codex: codex !== false };
+  // A boot is the one moment the file, and not the engine, is the authority on
+  // the key, the pairings and the port. See lanApplyFields.
+  _lanLoaded = false;
   // The away-update's clock. The boot grace counts from here, and the timer is
   // unref'd so it never keeps a process alive on its own. It does nothing until
   // the launcher has handed down a restart — see awayGate's `supervised`.
@@ -5847,21 +7038,68 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
   // handed to the roster read here, by the server that is actually running,
   // rather than wired at import — see repairStaleCopyWith.
   if (_providers.claude) {
-    void Promise.all([
-      import(pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href),
-      cswapAdminModule(),
-    ]).then(([accounts, admin]) => accounts.repairStaleCopyWith(admin.autoRecapture), () => {});
+    // THIS WIRING IS WHERE AN IMPORT CYCLE SHOWED UP AS A SILENT NO-OP, and it
+    // is the cycle that has been fixed rather than this line — see
+    // claude-identity.mjs.
+    //
+    // claude-accounts.mjs used to take `currentIdentity` from cswap-admin.mjs
+    // while cswap-admin.mjs took `backupRoot`, `invalidateClaudeAccountsCache`
+    // and `verdictNow` back, which was the only static import cycle in
+    // src/server. Two dynamic imports entering a cycle concurrently are each
+    // handed the other module's HALF-BUILT namespace rather than waiting for
+    // it, and a half-built namespace has no exports on it at all: measured on
+    // CI, both came back with zero keys, so `accounts.repairStaleCopyWith` was
+    // a TypeError in a promise nothing awaits. The repair was never wired and
+    // nothing said so — every test passed, and the run exited 1 on an unhandled
+    // rejection alone.
+    //
+    // Several importers reach this pair within a few ticks at boot —
+    // `cswapAutoModule()` below imports claude-accounts.mjs too, and
+    // `startServer` can be called again before this has settled — so it was a
+    // timing defect that any change to those import lists could trip, and
+    // sequencing one call site was never going to be enough.
+    //
+    // Asked for one at a time anyway, which is now belt as well as braces: with
+    // no cycle left, a concurrent pair would simply wait for each other.
+    // boot-module-graph.test.ts asserts the braces — that src/server has no
+    // import cycles at all — rather than trying to police call sites.
+    void (async () => {
+      let accounts, admin;
+      // An import that genuinely fails stays tolerated, exactly as the
+      // `() => {}` this replaced tolerated it: the wiring is best-effort. A
+      // namespace that arrives WITHOUT the function is a different thing and
+      // must stay loud, because that is the failure described above.
+      try {
+        accounts = await import(pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href);
+        admin = await cswapAdminModule();
+      } catch { return; }
+      accounts.repairStaleCopyWith(admin.autoRecapture);
+    })();
   }
   const removed = await sweepStaleDiscovery();
   if (removed > 0) console.log(`  swept ${removed} stale discovery file(s)`);
+  _persistWritable = false;
   if (persist) {
     persistPath = resolve(persist);
     try { await mkdir(pdirname(persistPath), { recursive: true }); } catch {}
+    // Asked before the first event, so a log that cannot be written is a fact
+    // the deck states rather than one the user discovers by pressing Restart.
+    // The mkdir above is inside a bare try/catch, so its failure is already
+    // swallowed once by the time we get here — see _persistWritable.
+    _persistWritable = await probeLogWritable(persistPath);
+    // Taken the moment the probe answers, so that a line landing from here on
+    // is evidence newer than it. See logWritableNow.
+    _landedAtProbe = appendsLanded(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);
+    //
+    // `_providers` goes with it, and for the same reason: it gates the two live
+    // capture paths a few lines down (`if (codex) startCodexWatcher`, and the
+    // hook install above), and until #1004 it reached neither the replay nor
+    // anything else but the health payload.
+    const replayed = await replayLog(persistPath, _workspace, { providers: _providers });
     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.
@@ -6007,6 +7245,37 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     // POST /api/clear — wipe in-memory buffer + persistence file (UI reset)
     if (req.method === "POST" && url.pathname === "/api/clear") return guard(handleClear(res), res);
 
+    // POST /api/forget — the sessions the page's own pruners dropped. The same
+    // sentence as `__clear`, about part of the board rather than all of it.
+    // Above the 404 below, which is what every real route has to be.
+    if (req.method === "POST" && url.pathname === "/api/forget") return guard(handleForget(req, res), res);
+
+    // AN UNMATCHED /api/ PATH IS A 404, not the SPA shell.
+    //
+    // serveStatic falls back to index.html for a path it cannot find, which is
+    // right for a client-side route and wrong for this namespace: nothing under
+    // dist/web is served from /api/, so the fallback could only ever answer a
+    // route that does not exist — with 200 and text/html.
+    //
+    // That made every status-code probe against this server vacuous. The Node
+    // 18 floor job asks four endpoints for a 200, and one of them (/api/state)
+    // has never been a route: the string appears exactly once in the repo, in
+    // that loop. It reported 200 anyway, and so would the other three if the
+    // whole route table were deleted, as long as index.html was in the tarball.
+    // Measured before this line existed:
+    //
+    //   /api/state                200  text/html; charset=utf-8
+    //   /api/definitely-not-a-route  200  text/html; charset=utf-8
+    //   /api/health/bogus         200  text/html; charset=utf-8
+    //
+    // The repo already builds machinery against checks that cannot fail —
+    // skip-gate-inventory.test.ts exists because "a probe can start answering
+    // the other way and take its case off ALL THREE legs at once". A probe that
+    // cannot answer the other way is the limiting case of the same thing.
+    if (url.pathname === "/api" || url.pathname.startsWith("/api/")) {
+      return send(res, 404, { error: "not found" });
+    }
+
     if (req.method === "GET") return serveStatic(req, res, url);
     send(res, 405, { error: "method not allowed" });
   };
@@ -6059,8 +7328,11 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
       // asked the registry never binds a port it is about to walk away from.
       _prefsRead.then(() => applyLanPrefs()).catch(() => {});
       // Auto-switch resumes only if the user previously turned it on; the
-      // module reads its own persisted flag and does nothing otherwise.
-      cswapAutoModule().then(m => m.initCswapAuto()).catch(() => {});
+      // module reads its own persisted flag and does nothing otherwise. Its
+      // ticks wait for `cswapQuiet`, the launcher's word that claude-swap is not
+      // being installed or upgraded underneath them (#1043) — null from every
+      // caller with nothing to wait for.
+      cswapAutoModule().then(m => m.initCswapAuto({ after: cswapQuiet })).catch(() => {});
       return server;
     } catch (err) {
       lastErr = err;