ccdeck 3.32.1 → 3.33.0

package/src/server/codex-usage.mjs

@@ -11,7 +11,7 @@ import { createReadStream } from "node:fs";
 // single line of this module runs and takes the whole deck down with it. Caught
 // by the timezone probe, which spawns a child that imports this file.
 import zlib from "node:zlib";
-import { STOP, walkRolloutDays } from "./codex-dir.mjs";
+import { walkRolloutDays } from "./codex-dir.mjs";
 import { PRODUCT } from "./brand.mjs";
 // The shape of a token_count record, read where the translation reads it — see
 // codex-translate.mjs.
@@ -46,6 +46,10 @@ const CACHE_MS = 60_000;
 // silent undercount rather than an error. Unbounded calls let that EMFILE back
 // in through the door the pool does not cover.
 //
+// The route is a guarded read now (GUARDED_READS in request-gates.mjs), so a
+// page on another site is refused before it gets here. The bounds stay: the
+// deck's own page and any client holding the token still reach this.
+//
 // The two things between a caller and a scan are the ones quota.mjs established
 // and codex-quota.mjs adopted in #597, spelled the same way in all three:
 //
@@ -401,7 +405,14 @@ function parseRolloutTime(filename) {
   return dt.getTime();
 }
 
-// List rollout files whose start times fall within the given window.
+// How many rollouts named before the window are statted at once, to learn
+// whether one of them was written to inside it. A stat holds no descriptor
+// past its own call, so this can sit well above MAX_PARALLEL_READS; it is a
+// bound on the fan-out over a history that grows by a file per session.
+const MAX_PARALLEL_STATS = 16;
+
+// List rollout files whose sessions started within the given window — and the
+// ones that started before it but were written to inside it.
 //
 // The walk over $CODEX_HOME/sessions is shared with the rollout lookup in
 // codex-enrichment.mjs and the watcher in codex-watch.mjs (codex-dir.mjs) rather
@@ -410,42 +421,72 @@ function parseRolloutTime(filename) {
 // verbatim copies of the same four nested readdirs over two verbatim copies of
 // the same CODEX_SESSIONS_DIR — which is how one of them came to resolve a
 // relative CODEX_HOME differently from the other (#375).
+//
+// THE NAME IS WHEN A SESSION STARTED, NOT WHEN IT LAST SPENT (#1731). `codex
+// resume` appends to the rollout the session started in — codex-enrichment.mjs
+// leans on the same fact — so a session begun twenty days ago and resumed an
+// hour ago has all of this hour's tokens in a file whose name says twenty days.
+// This used to stop there, and to end the walk at the first year too old to
+// hold a name inside the window, so that file was never opened and those
+// tokens counted toward neither window. Now every plain rollout named before
+// the window is statted, and one whose mtime lies inside the window is read
+// with the rest; windowDelta, not the mtime, judges how much of it counts, so a
+// file whose mtime moved without a token being spent — a restore, a sync —
+// contributes nothing. The walk therefore reads the whole tree, one readdir per
+// day directory, which the minute-long floor in front of every scan rations.
+//
+// Plain `.jsonl` only, for that second test. A `.jsonl.zst` is one Codex has
+// already judged cold and rewritten, and the rewrite is itself what moves its
+// mtime: counting the compression as activity would reopen, and decompress,
+// every compressed rollout in the history on the scan after Codex compressed
+// them.
 async function listRolloutFiles(sinceMs) {
   const out = [];
+  const before = [];
   const nowMs = Date.now();
-  // Years arrive newest-first, so the first one that cannot hold a file in the
-  // window ends the walk: everything after it is older still. The extra day of
-  // slack covers a session that started just before the window.
-  //
-  // It used to also claim to cover "a filename timestamp that is UTC while the
-  // year directory is local time", which asserted the opposite of what the
-  // files say — see parseRolloutTime. Both are local now and `getFullYear()`
-  // here is local too, so the two sides of this comparison finally speak the
-  // same clock. What the day of slack still earns, beyond the session that
-  // started just before the window: an ambiguous local time on the day the
-  // clocks go back happens twice, V8 resolves it to the first of the two, and
-  // a session started during the second is dated an hour early. That is a
-  // one-hour error on one or two days a year against a seven-day window,
-  // where the old bug was an offset-wide error on every day of it.
-  const oldestYear = new Date(nowMs - sinceMs - 86400000).getFullYear();
-  await walkRolloutDays(
-    (dir, files) => {
-      for (const f of files) {
-        // Both spellings. A cold rollout is `rollout-….jsonl.zst` and its name
-        // still carries the timestamp parseRolloutTime reads, so nothing else
-        // in this function has to know.
-        if (!f.endsWith(".jsonl") && !f.endsWith(COMPRESSED)) continue;
-        const t = parseRolloutTime(f);
-        if (t != null && nowMs - t <= sinceMs) {
-          out.push({ path: join(dir, f), startMs: t });
-        }
-      }
-    },
-    { onYear: y => (parseInt(y, 10) < oldestYear ? STOP : undefined) },
-  );
+  await walkRolloutDays((dir, files) => {
+    for (const f of files) {
+      // Both spellings. A cold rollout is `rollout-….jsonl.zst` and its name
+      // still carries the timestamp parseRolloutTime reads, so nothing else
+      // in this function has to know.
+      if (!f.endsWith(".jsonl") && !f.endsWith(COMPRESSED)) continue;
+      const t = parseRolloutTime(f);
+      if (t == null) continue;
+      if (nowMs - t <= sinceMs) out.push({ path: join(dir, f), startMs: t });
+      else if (f.endsWith(".jsonl")) before.push({ path: join(dir, f), startMs: t });
+    }
+  });
+  await forEachLimited(before, MAX_PARALLEL_STATS, async (file) => {
+    let st;
+    try { st = await stat(file.path); } catch { return; }
+    if (nowMs - st.mtimeMs <= sinceMs) out.push({ ...file, mtimeMs: st.mtimeMs, size: st.size });
+  });
   return out;
 }
 
+// What was read out of each rollout named before the window and written to
+// inside it, the last time it was read, by path: the file's mtime and size then,
+// and the part of its series a later scan can still need. A scan re-reads such a file only when either has
+// moved. Without it, a restore or a sync that brushed every old rollout's mtime
+// would have every one of them read in full once a minute for a week; with it,
+// each is read once. Rebuilt on every scan from the files that scan kept, so a
+// file that is deleted or drifts out of the window leaves with it.
+let _beforeWindowReads = new Map();
+
+// The tail of `series` that windowDelta can still need for any window opening
+// at `startMs` or later: from the last snapshot before `startMs` onward. Every
+// snapshot ahead of that one is older still, and a later window's baseline is
+// that one or a snapshot after it — so what is dropped can never be the answer.
+function seriesSince(series, startMs) {
+  let from = 0;
+  for (let i = 0; i < series.length; i++) {
+    const ts = series[i].ts;
+    if (ts != null && ts < startMs) from = i;
+    else if (ts != null) break;
+  }
+  return series.slice(from);
+}
+
 function emptyWindow() {
   return { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreateTokens: 0, totalTokens: 0, sessionCount: 0 };
 }
@@ -484,22 +525,36 @@ async function scanCodexUsage(now) {
   };
 
   try {
-    // Files whose session *started* within 7d. A long session that started up
-    // to 7d ago but is still active is captured here too, and its share of the
-    // 5h window is recovered via the cumulative delta below — so bucketing no
-    // longer drops active-but-old sessions or over-counts the pre-window tail.
+    // Files whose session *started* within 7d, and files that started before
+    // it and were written to inside it (#1731). A long or resumed session is
+    // captured either way, and its share of each window is recovered via the
+    // cumulative delta below — so bucketing no longer drops active-but-old
+    // sessions or over-counts the pre-window tail.
     const files = await listRolloutFiles(WINDOW_7D_MS);
+    const kept = new Map();
 
     // Bounded fan-out: a week of rollouts is an open-ended list, and opening
     // every one of them at once also risked EMFILE, which readTokenSeries
     // swallows into a silent undercount.
-    await forEachLimited(files, MAX_PARALLEL_READS, async ({ path }) => {
-      const series = await readTokenSeries(path);
+    await forEachLimited(files, MAX_PARALLEL_READS, async ({ path, mtimeMs, size }) => {
+      let series;
+      if (mtimeMs == null) series = await readTokenSeries(path);
+      else {
+        const was = _beforeWindowReads.get(path);
+        series = was && was.mtimeMs === mtimeMs && was.size === size
+          ? was.series
+          : await readTokenSeries(path).then(s => (s ? seriesSince(s, start7d) : null));
+        // A null is not kept: readTokenSeries answers null for a read that
+        // failed as well as for a file with nothing in it, and keeping the first
+        // would carry one bad read forward for as long as the file sat still.
+        if (series) kept.set(path, { mtimeMs, size, series });
+      }
       if (!series) return;
       // Same series feeds both windows; baseline differs per window start.
       addTo(w5h, windowDelta(series, start5h));
       addTo(w7d, windowDelta(series, start7d));
     });
+    _beforeWindowReads = kept;
   } catch (err) {
     console.error(`${PRODUCT} codex-usage: scan failed:`, err?.message ?? err);
     const result = { ok: false, fetchedAt: now };

package/src/server/codex-watch.mjs

@@ -67,11 +67,16 @@ import { pushEvent } from "./event-sink.mjs";
 // broadcasts them exactly like a hook event, and persists them when this deck is
 // the one elected to log this rollout — see writesCodexLog. This path is
 // entirely additive — the Claude hook flow is untouched.
-// path -> { offset, sid, cwd, skip, sawBeginning, rootOpened, seenAt }
+// path -> { offset, sid, cwd, skip, sawBeginning, rootOpened, seenAt, mtimeMs }
 const codexFileState = new Map();
-// How long a rollout's tail cursor is kept after it stops showing up in the
-// 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.
+// How long a rollout's tail cursor is kept once nothing has moved it: not
+// listed, and its mtime not changing. Leaving the listing is NOT the end of a
+// rollout (#1730). `codex resume` appends to the file the session started in,
+// in whatever day folder that was, and a session that runs across two later
+// calendar days is still writing when its folder drops out of the newest two.
+// So a cursor outside the listing is statted every tick and kept while its
+// mtime moves, and one that is swept hands its offset to codexOlderRollouts
+// below, which is how a rollout that falls silent and then resumes is found.
 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.
@@ -100,6 +105,49 @@ function rememberCodexPath(path) {
     codexSeenEver.delete(codexSeenEver.values().next().value);
   }
 }
+// Every rollout outside the newest two day directories that holds no cursor,
+// by path, with the size it had when last looked at — null before the first
+// look. The listing below reads two day directories a tick and must stay that
+// cheap; this is how the rest of the tree is watched without walking it every
+// tick (#1730).
+//
+// The whole tree is walked for it once at boot and again once per
+// CODEX_STATE_TTL_MS, a readdir per day directory, which adds the paths it has
+// not got. Each tick then stats at most CODEX_OLDER_STATS_PER_TICK of them, in
+// turn, and a rollout that has GROWN since its last look is opened joined late
+// from the size it had then: no SessionStart, since the deck did not watch the
+// session begin, and nothing before that size, which the deck had either
+// already drawn or had never been going to. A path whose first look is still
+// to come has no size to grow from, so what is appended before that look is
+// skipped, the trade the boot catalog already makes. A directory's mtime would
+// be cheaper to watch and says nothing here: an append to a file leaves the
+// directory holding it as it was.
+//
+// A cursor the sweep drops outside the listing hands its offset over, so a
+// session that sat idle past the window resumes where the deck stopped reading.
+// A path that cannot be statted leaves; a path the listing shows is the
+// listing's.
+const codexOlderRollouts = new Map();
+let codexOlderTurn = null;
+let codexOlderWalkedAt = null;
+// About three seconds of stats per thousand old rollouts on a slow disk, spread
+// over ticks: a resumed session in a history of N rollouts is found within
+// ceil(N / 128) ticks, which is ~12s for a thousand and ~2 minutes for ten.
+const CODEX_OLDER_STATS_PER_TICK = 128;
+
+/** The next old rollout due a look, round-robin; null when there are none. The
+ *  Map's own iterator is the turn: it survives deletions and ends after the
+ *  newest key, and a fresh one starts the round again. */
+function nextOlderRollout() {
+  for (let pass = 0; pass < 2; pass++) {
+    codexOlderTurn ??= codexOlderRollouts.keys();
+    const next = codexOlderTurn.next();
+    if (!next.done) return next.value;
+    codexOlderTurn = null;
+  }
+  return null;
+}
+
 // The scan in flight, if any, as its promise. A tick that lands while one is
 // still reading joins it rather than starting a second over the same cursors,
 // and scanCodexNow can wait it out.
@@ -109,17 +157,21 @@ let codexWorkspace = "";
 
 // List rollout files from the newest 2 day-directories. New sessions always
 // land in today's dir, so this captures live activity without scanning years
-// of history every tick.
-async function listRecentCodexRollouts() {
+// of history every tick. With `all`, the rest of the tree is listed too, as
+// `older` — the walk codexOlderRollouts is filled from.
+async function listRecentCodexRollouts(all = false) {
   const out = [];
+  const older = [];
   let dayDirs = 0;
   await walkRolloutDays((dir, files) => {
-    for (const f of files) if (f.endsWith(".jsonl")) out.push(join(dir, f));
+    const into = dayDirs < 2 ? out : older;
+    for (const f of files) if (f.endsWith(".jsonl")) into.push(join(dir, f));
     // Two day-directories deep is the whole point of this listing: it runs every
-    // tick, and anything older than that is a session no process will append to.
-    if (++dayDirs >= 2) return STOP;
+    // tick. Anything older is still watched, by codexOlderRollouts, at a
+    // bounded number of stats a tick rather than a readdir of every day.
+    if (++dayDirs >= 2 && !all) return STOP;
   });
-  return out;
+  return { files: out, older };
 }
 
 /** Which of the two ways a rollout can fail to say whose it is has been printed
@@ -359,18 +411,70 @@ function emitCodexLines(state, consume, persist) {
 }
 
 /**
- * Rollout files fall out of the newest-2-days listing and never come back,
- * but their tail cursors used to live as long as the process did. Expire by
- * "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.
+ * Rollout files fall out of the newest-2-days listing, but their tail cursors
+ * used to live as long as the process did. Expire by "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. "Seen" is listed, or
+ * its mtime moved (#1730).
+ *
+ * What a swept cursor had read is not forgotten with it: its offset goes to
+ * codexOlderRollouts, so a rollout written to again — a `codex resume` of it,
+ * or a session that sat idle past the window — is read from where this deck
+ * stopped, joined late. The listing takes the entry back if the path is listed.
  */
 function sweepCodexCursors(now) {
   for (const [p, s] of codexFileState) {
-    if (now - (s.seenAt ?? 0) > CODEX_STATE_TTL_MS) codexFileState.delete(p);
+    if (now - (s.seenAt ?? 0) > CODEX_STATE_TTL_MS) {
+      codexFileState.delete(p);
+      codexOlderRollouts.set(p, s.offset);
+    }
   }
 }
 
+/**
+ * Take the old rollouts a whole-tree walk found into codexOlderRollouts, each
+ * without a size until its first look. A path already held keeps the size it
+ * has: that is the one fact about it the walk cannot supply. Nothing is removed
+ * here — a walk that could not read a directory answers as though it were
+ * empty — so a path leaves only when it cannot be statted.
+ */
+function catalogOlderRollouts(older) {
+  for (const p of older) {
+    if (!codexOlderRollouts.has(p) && !codexFileState.has(p)) codexOlderRollouts.set(p, null);
+  }
+}
+
+/**
+ * Look at up to CODEX_OLDER_STATS_PER_TICK old rollouts, and return a cursor
+ * for each that has grown since its last look, opened joined late from the
+ * size it had then. See codexOlderRollouts.
+ */
+async function openGrownOlderRollouts(now) {
+  const opened = [];
+  const due = Math.min(CODEX_OLDER_STATS_PER_TICK, codexOlderRollouts.size);
+  for (let i = 0; i < due; i++) {
+    const path = nextOlderRollout();
+    if (path == null) break;
+    const was = codexOlderRollouts.get(path);
+    let st;
+    try { st = await stat(path); } catch { codexOlderRollouts.delete(path); continue; }
+    if (was == null || st.size <= was) { codexOlderRollouts.set(path, st.size); continue; }
+    const header = await readCodexHeader(path);
+    if (!header || !header.sid) continue; // the size it grew from is kept; next round
+    codexOlderRollouts.delete(path);
+    const skip = !codexCwdInWorkspace(header.cwd, codexWorkspace);
+    // Never `sawBeginning`, whatever this process read of the file before: the
+    // lines before `was` are ones this deck has either drawn already or joined
+    // too late for, and either way a SessionStart now would be a false one.
+    const state = { offset: skip ? st.size : was, sid: header.sid, cwd: header.cwd, skip, sawBeginning: false, rootOpened: false, seenAt: now, mtimeMs: st.mtimeMs };
+    codexFileState.set(path, state);
+    rememberCodexPath(path);
+    opened.push({ path, st, state });
+  }
+  return opened;
+}
+
 function codexScanOnce(firstRun) {
   codexScan ??= scanRollouts(firstRun).finally(() => { codexScan = null; });
   return codexScan;
@@ -399,8 +503,20 @@ async function scanRollouts(firstRun) {
     // listing for the answer to a question nothing is asking.
     let decksRead = null;
     const liveDecks = () => (decksRead ??= readLiveDecks());
-    const files = await listRecentCodexRollouts();
+    // The whole tree at boot and once per CODEX_STATE_TTL_MS after, for
+    // codexOlderRollouts; the newest two day directories on every other tick.
+    // `null` rather than 0 for "never", so a clock that starts near the epoch,
+    // or a faked one, cannot make boot look recent.
+    const walkAll = codexOlderWalkedAt == null || Math.abs(now - codexOlderWalkedAt) >= CODEX_STATE_TTL_MS;
+    const { files, older } = await listRecentCodexRollouts(walkAll);
+    if (walkAll) { codexOlderWalkedAt = now; catalogOlderRollouts(older); }
+    const listed = new Set(files);
+    // Every rollout this tick has a reason to read, with its stat and cursor:
+    // the listed ones, then the cursors outside the listing, then the old
+    // rollouts found grown. One pass reads them all below.
+    const due = [];
     for (const path of files) {
+      codexOlderRollouts.delete(path); // listed, so the listing's
       let st;
       try { st = await stat(path); } catch { continue; }
       let state = codexFileState.get(path);
@@ -410,7 +526,23 @@ async function scanRollouts(firstRun) {
         state = await openCodexCursor(path, st, now, firstRun);
         if (!state) continue;
       }
+      state.mtimeMs = st.mtimeMs;
+      due.push({ path, st, state });
+    }
+    // A cursor whose file has left the listing is still read, and kept for as
+    // long as its mtime keeps moving (#1730). One that cannot be statted is left
+    // for the sweep, as a listed file that cannot be is.
+    for (const [path, state] of codexFileState) {
+      if (listed.has(path)) continue;
+      let st;
+      try { st = await stat(path); } catch { continue; }
+      if (st.mtimeMs !== state.mtimeMs) state.seenAt = now;
+      state.mtimeMs = st.mtimeMs;
+      due.push({ path, st, state });
+    }
+    due.push(...await openGrownOlderRollouts(now));
 
+    for (const { path, st, state } of due) {
       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
@@ -480,7 +612,7 @@ export function startCodexWatcher(workspace) {
   // starts — and rollout tailing is the only Codex capture path there is, so
   // bailing out here meant a fresh install had to restart the deck before any
   // Codex agent ever showed up, while the banner claimed to be watching.
-  // listRecentCodexRollouts returns [] while the directory is missing, so the
+  // listRecentCodexRollouts lists nothing while the directory is missing, so the
   // poll below is a cheap no-op that doubles as the existence re-check. A
   // filesystem watch is no help: fs.watch on a missing path throws, and
   // watching the parent recursively is macOS/Windows-only.

package/src/server/cswap-auto-loop.mjs

@@ -76,10 +76,23 @@ function summarise(stdout) {
  * says as much about its own guard: the next interval is at most fifteen
  * seconds away and the work is idempotent by design. Here it is not even
  * skipped, only queued.
+ *
+ * AND QUEUED IS A WAIT (#1797). The chain is first-in first-out with no
+ * timeout, so a tick can stand behind a sixty-second `cswap add` — and the
+ * switch runTick checked before joining the queue may have been turned off by
+ * the time the lock is its. Both of runTick's questions are asked again as the
+ * first thing the lock runs, before `cswapBin()` and before anything is
+ * spawned, and a tick that finds either answer changed comes back as the same
+ * skip runTick would have recorded. The external-engine reading is the shared
+ * ten-second one, so a tick that did not wait pays nothing for it here.
  */
 async function runAutoTick() {
-  const r = await withStoreLock(async () =>
-    run(await cswapBin(), ["auto", "--once", "--json"], { timeout: TICK_TIMEOUT_MS }));
+  const r = await withStoreLock(async () => {
+    if (!_enabled) return { skipped: "disabled" };
+    if (await externalAutoRunning()) return { skipped: "external-engine" };
+    return run(await cswapBin(), ["auto", "--once", "--json"], { timeout: TICK_TIMEOUT_MS });
+  });
+  if (r.skipped) return { event: "skipped", reason: r.skipped };
   // A KILLED RUN IS NOT A QUIET ONE. `run`'s timeout path deliberately keeps an
   // 8 KB tail of whatever the child managed to print, so `!r.ok && !r.stdout`
   // is false for a tick that emitted its `{"event":"poll"}` line and then

package/src/server/cswap-auto-readers.mjs

@@ -8,7 +8,7 @@
 // engine before every tick, and drops both readings when it writes a setting;
 // it re-exports all five names, which is where the suite reaches them.
 import { run } from "./exec.mjs";
-import { cswapBin } from "./cswap-install.mjs";
+import { cswapBin, cswapRefused } from "./cswap-install.mjs";
 
 // ── one reading at a time ──────────────────────────────────────────────────
 
@@ -34,9 +34,11 @@ import { cswapBin } from "./cswap-install.mjs";
  *
  * Two callers reach these without an attacker anywhere: AccountsPanel polls the
  * route every 15s per open tab, and runTick asks externalAutoRunning() again
- * before every tick. And it is a GET, so it passes isTrustedRead for any local
+ * before every tick. And it is a GET, so it passed isTrustedRead for any local
  * client that sends neither Origin nor Sec-Fetch-Site — curl, a shell script, a
- * sandboxed agent.
+ * sandboxed agent. It is a guarded read now (GUARDED_READS in
+ * request-gates.mjs), which refuses those callers unless they hold the token;
+ * the guard below still bounds the ones that pass.
  *
  * The fix is #544's, at the route that sweep did not reach: a minimum gap plus
  * one shared in-flight promise per reader. There is no MAX_OUTSTANDING beside it
@@ -165,7 +167,11 @@ export function readCswapConfig() {
 }
 
 async function readCswapConfigNow() {
-  const r = await run(await cswapBin(), ["config"]);
+  const bin = await cswapBin();
+  // Not a copy the deck refused (#1799): the panel's settings are no reason to
+  // run it, and null is what a tool that cannot be asked already answers.
+  if (cswapRefused()) return null;
+  const r = await run(bin, ["config"]);
   if (!r.ok) return null;
   const out = {};
   for (const line of r.stdout.split("\n")) {

package/src/server/cswap-auto.mjs

@@ -159,12 +159,12 @@ export async function autoStatus() {
  *  goes through one mutex.
  *
  *  And the missing invalidation is what made the press look like a no-op. The
- *  panel polls every 15s and each poll stamps `_lastReadAt`, so that stamp is
- *  never more than 15s old. The press then reloads with ?refresh=1, and a
- *  forced read needs `now - _lastReadAt >= FORCE_POLL_MS` (60s) — a quantity
- *  that can never be reached while the panel is open. The read was refused
- *  every time and `heldReading` handed back the pre-press roster: the chip did
- *  not move, the button still said "hold out", and nothing had failed.
+ *  press reloads with ?refresh=1 milliseconds after the read before it, and a
+ *  forced read needs `now - _lastReadAt` past its floor — then FORCE_POLL_MS
+ *  (60s), which the panel's 15s poll never let it reach; the cache's 5s since
+ *  #1798, which the reload after a press still cannot. The read was refused
+ *  and `heldReading` handed back the pre-press roster: the chip did not move,
+ *  the button still said "hold out", and nothing had failed.
  *  invalidateClaudeAccountsCache sets `_lastReadAt = 0`, which is what makes
  *  the following forced read real work — the invalidator's own docblock says
  *  so, and calls a floor that answers ?refresh=1 with the stale roster "the