agent-dag 1.43.0 → 1.45.0

package/src/server/installer.mjs

@@ -5,7 +5,7 @@
 // sessions reach the same server through the rollout watcher instead, so one
 // running server still sees both CLIs. Re-runs are safe; entries are tagged
 // with __agent-dag and de-duped.
-import { readFile, mkdir, unlink, rename, open, stat, chmod } from "node:fs/promises";
+import { readFile, mkdir, unlink, rename, open, stat, chmod, realpath, readlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
@@ -133,10 +133,6 @@ function stripBom(text) {
   return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
 }
 
-async function readJsonSafe(p) {
-  try { return JSON.parse(stripBom(await readFile(p, "utf8"))); } catch { return null; }
-}
-
 function unreadableSettings(p, why) {
   const err = new Error(
     `${p} could not be read as JSON (${why}). Refusing to overwrite it — ` +
@@ -144,6 +140,11 @@ function unreadableSettings(p, why) {
   );
   err.code = "SETTINGS_UNREADABLE";
   err.settingsPath = p;
+  // The bare reason, without the path and without the remedy sentence, so a
+  // caller that wants to phrase its own advice — `--uninstall` does; "run
+  // ccdeck again" is the wrong instruction there — does not have to take this
+  // message apart with a regex to get at the only part it cannot re-derive.
+  err.why = why;
   return err;
 }
 
@@ -264,6 +265,66 @@ async function createTemp(target, { mode = 0o666, attempts = 5 } = {}) {
   }
 }
 
+// A chain longer than this is a loop, or something no real setup has: stow and
+// chezmoi produce one hop, an encrypted volume two. The number is a bound on the
+// walk below, not a promise about how deep a legitimate link goes.
+const MAX_LINK_HOPS = 8;
+
+/**
+ * The file a name is really asking for — the one the links under it end at.
+ *
+ * A rename replaces the DIRECTORY ENTRY it is handed. Handed a symlink, it
+ * deletes the link and leaves an ordinary file where it was, and
+ * `~/.claude/settings.json` is a symlink on a great many machines: into a
+ * dotfiles repo, a stow or chezmoi target, an encrypted volume. The content
+ * survives — we write back what we read — so nothing looks wrong and nothing
+ * says anything. The repo copy keeps what it said before, never goes dirty, and
+ * from then on the user's edits there reach nobody while every launch rewrites
+ * the detached file and widens the gap. This is a file the deck did not create
+ * and does not own; quietly cutting it loose from the thing that manages it is
+ * worse than failing to write it at all.
+ *
+ * persistAuth in codex-auth.mjs has resolved for exactly this reason since it
+ * was written, on the file that is LESS often linked. This is the same rule at
+ * the helper every settings writer in the deck goes through — and the same
+ * function, so there is one of it rather than two that can drift.
+ *
+ * Resolving also decides which filesystem the temp file is staged on, and it has
+ * to be the target's. A rename is atomic within one filesystem and fails with
+ * EXDEV across two, so staging beside the LINK — a link into a dotfiles repo on
+ * a separate volume — is a write that cannot land at all.
+ *
+ * A DANGLING link is the case realpath alone cannot answer: the target not
+ * created yet, the encrypted volume not mounted. Answering it with the raw path
+ * is the bug again, because that is precisely when the link gets replaced — so
+ * the walk falls back to readlink, which reads a link without needing its target
+ * to exist, and follows it the way opening the name for writing would.
+ * `printf x > link` creates the target; it does not replace the link. If the
+ * target's directory is gone the write then fails, which is the honest answer:
+ * the bytes did not reach the file the user's setup points at.
+ *
+ * The ordinary case — a plain file, no link anywhere — is one realpath and the
+ * first return.
+ */
+async function resolveWriteTarget(raw) {
+  let at = raw;
+  for (let hop = 0; hop < MAX_LINK_HOPS; hop++) {
+    // Resolves every link on the path at once, when all of them lead somewhere.
+    const real = await realpath(at).catch(() => null);
+    if (real !== null) return real;
+    const to = await readlink(at).catch(() => null);
+    // Not a link, so nothing exists at this name yet and this name is the
+    // answer: a first install, or the far end of a chain we have just followed.
+    if (to === null) return at;
+    at = resolve(dirname(at), to);
+  }
+  // Only a cycle gets here. Say so rather than pick a link out of it and
+  // destroy that one — the OS answers a write through such a name the same way.
+  const err = new Error(`too many symbolic links resolving ${raw}`);
+  err.code = "ELOOP";
+  throw err;
+}
+
 /**
  * Replace a file in a single step readers cannot land inside.
  *
@@ -272,8 +333,13 @@ async function createTemp(target, { mode = 0o666, attempts = 5 } = {}) {
  * different ones. It is fsync'd before the rename so that a crash or power loss
  * just after a successful install cannot leave the new directory entry pointing
  * at blocks that were never flushed — the classic file-of-zero-bytes.
+ *
+ * "Beside the target" means beside the file the name resolves to, not beside the
+ * name: see resolveWriteTarget, which is what keeps a symlinked settings.json a
+ * symlink.
  */
-async function writeFileAtomic(target, text) {
+async function writeFileAtomic(rawTarget, text) {
+  const target = await resolveWriteTarget(rawTarget);
   const { tmp, handle } = await createTemp(target);
   try {
     try {
@@ -365,6 +431,49 @@ export async function installHooks({ provider = "claude" } = {}) {
     current.hooks[evt] = cleaned;
   }
 
+  // Retiring the finish-sound hook rides in here, on this read and this write,
+  // and this is the seam it needs rather than a convenient one. #704 moved the
+  // sound into the browser and deleted the script the old `Stop` entry ran, so
+  // an install that upgrades a machine which HAS that entry leaves a hook
+  // pointing at a file that is no longer in the package — an error at the end of
+  // every turn, on a machine that was working before the upgrade. It therefore
+  // has to happen without the user asking for it, and a normal boot is the only
+  // moment that qualifies.
+  //
+  // Riding along buys the two properties it would otherwise have to invent.
+  // There is ONE write of settings.json on the boot that retires, compared
+  // against the exact bytes read a few lines up — so a second deck doing the
+  // same work at the same time writes the same payload, and every later boot
+  // finds nothing to do and changes nothing. And the mutate-then-let-the-caller-
+  // write split is what keeps the script deletion after the write: until the new
+  // file has landed, a live Claude Code session's next turn still runs the old
+  // command.
+  //
+  // Imported here rather than at the top of the file because retire-sound-hook.mjs
+  // imports this module — writeFileAtomic and readSettingsForWrite live here —
+  // and a static import would close that into a cycle. Claude only: the entry
+  // was one line in Claude Code's settings.json and there was never a Codex one.
+  //
+  // The equality test is not ceremony. Retirement DELETES two files — the parked
+  // hooks and the installed script — at absolute paths it resolved for itself,
+  // from claudeConfigDir() and os.homedir(), at its own import. This function
+  // writes `cfg.settingsPath`. In the product those are the same settings.json
+  // and the paths belong together. When they are not the same file, the two
+  // modules are looking at different homes, and acting on that difference means
+  // deleting files belonging to a machine this install is not writing to. That
+  // is not hypothetical: it happened to the author's own ~/.agents-deck while
+  // this very change was being written, from a test whose environment teardown
+  // ran a describe too early. Disagreement is a reason to do nothing.
+  let retire = { pending: false, changed: false, removed: 0, restored: 0 };
+  let completeSoundHookRetirement = null;
+  if (provider === "claude") {
+    const retirement = await import("./retire-sound-hook.mjs");
+    if (retirement.SETTINGS_PATH === cfg.settingsPath) {
+      completeSoundHookRetirement = retirement.completeSoundHookRetirement;
+      retire = await retirement.retireSoundHookIn(current);
+    }
+  }
+
   // Every launch reinstalls, and on all but the first the entries are already
   // there and identical. Writing anyway is pure downside: it is one more chance
   // to be interrupted mid-write, and one more window in which a change Claude
@@ -373,14 +482,63 @@ export async function installHooks({ provider = "claude" } = {}) {
   const next = JSON.stringify(current, null, 2) + "\n";
   const changed = next !== before;
   if (changed) await writeFileAtomic(cfg.settingsPath, next);
-  return { settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider, changed };
+  // After the write, never before it: the notify script an older deck installed
+  // is what a live session's cached command still names until the new entry is
+  // on disk, and deleting it early turns a stale sound into a missing module.
+  if (retire.pending) await completeSoundHookRetirement(retire, current);
+  return { settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider, changed, retire };
 }
 
+/**
+ * Take our forwarders back out of one provider's settings file.
+ *
+ * Returns `{ok: true, changed}` when the file was read — `changed` says whether
+ * anything of ours was in it — and `{ok: false, reason: "settings_unreadable"}`
+ * when it was not. Callers must look at `ok` FIRST: `changed: false` on a
+ * refusal is the literal truth about the disk and a lie about the question
+ * being asked, because the hooks are still in there.
+ *
+ * That conflation is what this used to ship. The read was readJsonSafe, which
+ * turned every parse and IO failure into `null`, so a settings.json with one
+ * stray comma — the exact file readSettingsForWrite was written to protect —
+ * came back indistinguishable from a clean machine with none of our hooks in
+ * it. `--uninstall` printed "no Claude hooks to remove" and exited 0 while all
+ * ten `__agent-dag` entries sat in the file, spawning node on every tool call
+ * of every session, for a deck the user had been told was gone. The other half
+ * of the same command already knew better: the sound-hook half read through
+ * readSettingsForWrite and said so out loud, so one command gave two opposite
+ * verdicts about one file and the load-bearing one was the one that lied.
+ *
+ * So the read is the same read the install does, and for the same reason. A
+ * file we cannot parse is a file whose contents we cannot reproduce, and this
+ * function rewrites the whole thing — every permission, env var, model pin and
+ * hand-written hook in it. Refusing leaves it byte for byte as it was found and
+ * hands the user something they can act on; guessing would either destroy it or
+ * quietly do nothing. Only ENOENT is genuinely empty, and readSettingsForWrite
+ * already answers that with `{}`, which falls through to `changed: false`.
+ */
 export async function uninstallHooks({ provider = "claude" } = {}) {
   const cfg = PROVIDERS[provider];
   if (!cfg) throw new Error(`unknown provider: ${provider}`);
-  const current = await readJsonSafe(cfg.settingsPath);
-  if (!current?.hooks) return { changed: false, provider };
+  let current;
+  try {
+    ({ settings: current } = await readSettingsForWrite(cfg.settingsPath));
+  } catch (err) {
+    if (err?.code !== "SETTINGS_UNREADABLE") throw err;
+    // Same shape retireSoundHook answers with, so bin/deck.js reports both
+    // halves of `--uninstall` the same way instead of one of them inventing a
+    // second vocabulary for the identical condition on the identical file.
+    return {
+      ok: false,
+      reason: "settings_unreadable",
+      changed: false,
+      provider,
+      settingsPath: cfg.settingsPath,
+      why: err.why ?? err.message,
+      message: err.message,
+    };
+  }
+  if (!current?.hooks) return { ok: true, changed: false, provider, settingsPath: cfg.settingsPath };
   let changed = false;
   for (const evt of Object.keys(current.hooks)) {
     const cleaned = dedupeOurEntries(current.hooks[evt]);
@@ -389,7 +547,7 @@ export async function uninstallHooks({ provider = "claude" } = {}) {
     else current.hooks[evt] = cleaned;
   }
   if (changed) await writeFileAtomic(cfg.settingsPath, JSON.stringify(current, null, 2) + "\n");
-  return { changed, provider, settingsPath: cfg.settingsPath };
+  return { ok: true, changed, provider, settingsPath: cfg.settingsPath };
 }
 
 /** True when ~/.codex/ exists — the CLI's default answer to whether the Codex
@@ -598,4 +756,8 @@ export { AGENT_DAG_DIR, CLAUDE_DIR, CODEX_DIR };
 // the same reason one step lower: codex-auth.mjs needs the collision-free temp
 // name but not writeFileAtomic's mode handling, which carries over the target's
 // mode and so would leave a brand-new auth.json at whatever the umask allows.
-export { readSettingsForWrite, writeFileAtomic, installScript, renameWithRetry, createTemp };
+// resolveWriteTarget goes with them, because auth.json is linked into a dotfiles
+// repo for the same reasons settings.json is, and "never rename onto a link" is
+// one rule: codex-auth.mjs called a realpath of its own before this existed, and
+// two spellings of a rule are two things that can drift.
+export { readSettingsForWrite, writeFileAtomic, installScript, renameWithRetry, createTemp, resolveWriteTarget };

package/src/server/invoked-as.mjs

@@ -1,11 +1,11 @@
 // Which of the three published commands the user typed — and nothing else.
 //
-// The deck is on npm three times over: `agents-deck` (what this repo publishes),
-// `agent-dag` (the same tarball under the name it shipped as first) and
-// `ccdeck` (a stub that depends on agents-deck and spawns its bin). Every
-// surface a human reads says ccdeck now, and 95% of the downloads are still on
-// the other two, so nothing closes that split on its own. This file is the
-// evidence behind saying so — once in the terminal, once in the browser.
+// The deck is on npm three times over — `ccdeck`, `agents-deck` and `agent-dag`
+// — and since #340 all three are literally the same tarball, published with
+// `name` set to each in turn. Every surface a human reads says ccdeck now, and
+// most of the downloads are still on the other two, so nothing closes that split
+// on its own. This file is the evidence behind saying so — once in the terminal,
+// once in the browser.
 //
 // Two rules make that safe, and they are the whole of the file.
 //
@@ -15,13 +15,15 @@
 // dead on the one machine where the deck was the thing that would have
 // explained why.
 //
-// And it is never asked of the PACKAGE. `ccdeck/package.json` depends on
-// `agents-deck`, and `ccdeck/bin/ccdeck.js` spawns
-// `../../agents-deck/bin/agent-dag.js` — so "is this build agents-deck?" is
-// true inside every ccdeck run, and a notice keyed on it would scold exactly
-// the people who did what we asked. The question is which name the USER TYPED.
-// That is a different question, with a different answer, and on one platform
-// with no answer at all:
+// And it is never asked of the PACKAGE. That was unarguable while ccdeck was a
+// stub — it depended on `agents-deck` and spawned its bin, so "is this build
+// agents-deck?" was true inside every ccdeck run, and a notice keyed on it would
+// have scolded exactly the people who did what we asked. #340 removed the stub
+// and the rule outlived it, because the three names are now ONE tarball: asking
+// the package what it is gets you whichever name the publish step happened to
+// set last, which is not evidence about the user at all. The question is which
+// name the USER TYPED. That is a different question, with a different answer,
+// and on one platform with no answer at all:
 //
 //   npx, everywhere — npm writes the literal spec into
 //     `_npx/<hash>/package.json` as `_npx.packages`, which npxRestartSpec
@@ -37,7 +39,7 @@
 //
 //   a global install on Windows — nowhere. npm writes <name>.cmd, <name>.ps1
 //     and an extensionless sh shim, each of which runs
-//     `node "…\node_modules\agents-deck\bin\agent-dag.js" %*` (npm's cmd-shim).
+//     `node "…\node_modules\<pkg>\bin\agent-dag.js" %*` (npm's cmd-shim).
 //     The typed name is the shim's FILENAME and never becomes an argument, and
 //     there is no other carrier — npm_config_user_agent and friends are not set
 //     for a direct bin invocation. So Windows answers null.

package/src/server/quota.mjs

@@ -29,7 +29,7 @@
 // cooldown; 1 is not, because it is a local file read.
 import { activeAccountUsage, requestCollection } from "./claude-accounts.mjs";
 import { claudeCliCandidates, claudeConfigDir } from "./claude-dir.mjs";
-import { run } from "./exec.mjs";
+import { pathLookup, run } from "./exec.mjs";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -174,6 +174,11 @@ let _cacheAt  = 0;
 let _inflight = null;   // deduplicates concurrent CLI probes
 let _lastGood = null;   // last result that had real quota percentages
 let _lastSelfPollAt = 0;
+// Which account the readings below are about — as a counter, because the
+// account's identity is not something this module holds. invalidateQuotaCache
+// bumps it; every write in _doFetch is stamped with the value that was current
+// when that read STARTED. See publish().
+let _generation = 0;
 
 const CACHE_MS = 60_000;
 
@@ -356,15 +361,69 @@ function parseUsageText(raw) {
  *
  *  Exported, with everything it touches injectable, so the Windows branch is
  *  testable from the platforms this repo is actually developed on.
+ *
+ *  WHY THE BARE NAME HAS TO EARN ITS PLACE (#553). This used to be a `.find`
+ *  over `!c.includes(sep) || exists(c)`, which reads as "a bare name always
+ *  answers, a full path only when it is there". On Windows that is harmless —
+ *  the bare name is LAST in the list — but on POSIX it is FIRST, so the `||`
+ *  short-circuited on candidate one and `exists` was never called even once:
+ *  `~/.local/bin/claude`, `/usr/local/bin/claude` and `/opt/homebrew/bin/claude`
+ *  were in a list nothing ever read. The user this broke is the one
+ *  claude-dir.mjs names out loud: Claude Code installed by the official
+ *  installer, so the binary is at `~/.local/bin/claude`, and the deck launched
+ *  from something whose PATH never sourced a shell rc — a LaunchAgent, a
+ *  systemd user unit, pm2, a desktop shortcut. `hasClaudeInstalled()` stats the
+ *  absolute paths and says yes, so hooks install and the Claude surface turns
+ *  on; every `claude --print /usage` spawn is then a bare-name ENOENT logged as
+ *  `quota: claude CLI failed`. On macOS there is no `.credentials.json` to fall
+ *  back to (the token is in the Keychain, #360), so the quota panel simply stays
+ *  dark on a machine that plainly has Claude Code. The identical install on
+ *  Windows worked, because there the ordering already said what this now says.
+ *
+ *  WHICH WINS. The candidate list's own order decides, unchanged on both
+ *  platforms — PATH first on POSIX, the two known install directories first on
+ *  Windows — because the ordering question here is the one getRunner in
+ *  ccusage.mjs already answered: preferring a different copy would silently
+ *  change which binary runs on every machine that has two, and a deck that
+ *  works today must not start running a `claude` it has never run. A user with
+ *  a current claude on PATH via nvm/mise/volta and a stale one left in
+ *  `~/.local/bin` keeps getting the one their own shell gives them. All that
+ *  changes is that a bare name is now only ANSWERED WITH when PATH actually
+ *  holds it, which is the same rule claudeCliOnDisk in claude-dir.mjs has
+ *  always applied to this very list — the two readers of one list can no longer
+ *  disagree about whether the deck can run what it says is installed.
+ *
+ *  WHAT IT COSTS. One PATH walk, stopping at the first hit, and only for the
+ *  bare candidate; the absolute paths are stat'ed only once PATH has come up
+ *  empty. That is the trade ccusage.mjs already priced for the same shape of
+ *  question — "a handful of stats, once per uncached fetch, against a process
+ *  spawn that follows it" — and here the spawn that follows is a whole Claude
+ *  Code process measured at ~3s, behind the SELF_POLL_MS floor.
+ *
+ *  `pathLookup` is used as a yes/no gate rather than for the path it found, on
+ *  purpose: answering with the bare name keeps spawn's own resolution (and, on
+ *  Windows, exec.mjs's PATHEXT candidate walk) in charge of the PATH case
+ *  exactly as before, so a PATH entry that merely LOOKS like a hit — a
+ *  directory named `claude` — cannot become the answer.
  */
 export function quotaClaudeBin(platform = process.platform, env = process.env,
                                home = homedir(), exists = existsSync) {
   const sep = platform === "win32" ? "\\" : "/";
-  // A bare name is left to spawn's own PATH lookup (and, on Windows, to the
-  // PATHEXT walk exec.mjs does by hand); a full path is only worth naming when
-  // it is actually there.
-  return claudeCliCandidates(platform, env, home)
-    .find(c => !c.includes(sep) || exists(c)) ?? "claude";
+  // process.env is case-insensitive on Windows; an injected plain object in a
+  // test is not, and %Path% is how the variable is actually spelled there.
+  const pathEnv = env.PATH ?? env.Path ?? env.path ?? "";
+  for (const c of claudeCliCandidates(platform, env, home)) {
+    // A full path is worth a single stat; a bare name means "ask PATH", which
+    // is pathLookup's walk — PATHEXT included, since `claude` on Windows is
+    // spelled `claude.exe` or `claude.cmd` and never the bare word.
+    if (c.includes(sep)) { if (exists(c)) return c; }
+    else if (pathLookup(c, platform, { pathEnv, exists })) return c;
+  }
+  // Nothing on PATH and nothing at any known install directory. The bare name
+  // is still the right last resort — POSIX `execvp` and cmd.exe's own search
+  // both deserve their turn at a layout no list here knows — and the ENOENT it
+  // produces is what `quota: claude CLI failed` reports.
+  return "claude";
 }
 
 export async function fetchClaudeQuota({ force = false } = {}) {
@@ -376,8 +435,44 @@ export async function fetchClaudeQuota({ force = false } = {}) {
   // good result with 0%).
   if (_inflight) return _inflight;
 
-  _inflight = _doFetch(now, force).finally(() => { _inflight = null; });
-  return _inflight;
+  // `_inflight === mine` rather than a bare clear: invalidateQuotaCache drops
+  // `_inflight` so the next caller starts a read that knows the account moved,
+  // and that read installs its own promise here. A read from before the switch
+  // finishing afterwards would otherwise clear the NEW one on its way out,
+  // letting a third caller spawn a second concurrent probe — which is the very
+  // thing this slot exists to prevent.
+  const mine = _doFetch(now, force, _generation)
+    .finally(() => { if (_inflight === mine) _inflight = null; });
+  _inflight = mine;
+  return mine;
+}
+
+/**
+ * Write a reading into the caches, unless the account moved while it was being
+ * taken.
+ *
+ * Every one of _doFetch's writes happens after at least one await — a store
+ * read, a 15-second HTTPS call, up to three `claude --print /usage` spawns with
+ * 1.2s between them — and invalidateQuotaCache clears variables, which does
+ * nothing to a function that is already running and still holds the old
+ * account's answer in a local. So a switch landing mid-flight was followed,
+ * milliseconds later, by the pre-switch reading being written straight back over
+ * the cleared cache: the invalidation looked like it worked and was undone
+ * before anyone could observe it.
+ *
+ * The fetch is deliberately NOT cancelled. Whoever asked for it is still owed an
+ * answer, and the reading is not wrong — it is simply about an account that is
+ * no longer active, which makes it a fine return value and a bad cached one.
+ * `_lastGood` gets the same guard, and needs it more: it is the half that
+ * survives the result cache's minute and comes back under a "stale" label for as
+ * long as the store has nothing to say about the new account.
+ */
+function publish(gen, result, at, { good = false } = {}) {
+  if (gen !== _generation) return result;
+  _cache   = result;
+  _cacheAt = at;
+  if (good) _lastGood = result;
+  return result;
 }
 
 /**
@@ -456,7 +551,7 @@ async function _execOnce(bin) {
   return { cliOk, parsed: parseUsageText(combined) };
 }
 
-async function _doFetch(now, force = false) {
+async function _doFetch(now, force = false, gen = _generation) {
   // Source 1: claude-swap's store. Free, and already paid for.
   let store = await storeQuota();
 
@@ -473,9 +568,7 @@ async function _doFetch(now, force = false) {
     // throttle inside is shared with the accounts panel, so two open panels
     // ask no more often than one.
     if (!force) requestCollection().catch(() => {});
-    _cache = store; _cacheAt = now;
-    _lastGood = store;
-    return store;
+    return publish(gen, store, now, { good: true });
   }
 
   // Nothing usable in the store. Everything below spends the user's budget, so
@@ -488,24 +581,16 @@ async function _doFetch(now, force = false) {
     // and then reverted to 23% (from a 48-minute-old store row) on the very
     // next poll, because the store had not moved.
     const held = freshest(store, _lastGood);
-    if (held) {
-      const result = { ...held, stale: true };
-      _cache = result; _cacheAt = now;
-      return result;
-    }
+    if (held) return publish(gen, { ...held, stale: true }, now);
     const result = { ok: false, reason: now < _rateLimitedUntil ? "rate_limited" : "waiting", fetchedAt: now };
-    _cache = result; _cacheAt = now - (CACHE_MS - 5_000);
-    return result;
+    return publish(gen, result, now - (CACHE_MS - 5_000));
   }
   _lastSelfPollAt = now;
 
   // Source 2: OAuth usage API — instant, exact, no cold-start gap.
   const api = await fetchOAuthUsage();
   if (api) {
-    const result = { ok: true, ...api, source: "api", fetchedAt: now };
-    _cache = result; _cacheAt = now;
-    _lastGood = result;
-    return result;
+    return publish(gen, { ok: true, ...api, source: "api", fetchedAt: now }, now, { good: true });
   }
 
   // Source 3: parse `claude --print /usage` CLI output.
@@ -526,10 +611,7 @@ async function _doFetch(now, force = false) {
 
   // Got real quota lines — cache normally and remember as last-known-good.
   if (parsed) {
-    const result = { ok: true, ...parsed, source: "cli", fetchedAt: now };
-    _cache = result; _cacheAt = now;
-    _lastGood = result;
-    return result;
+    return publish(gen, { ok: true, ...parsed, source: "cli", fetchedAt: now }, now, { good: true });
   }
 
   // No quota lines after retries. If we've ever seen real values, keep showing
@@ -540,10 +622,7 @@ async function _doFetch(now, force = false) {
   // vouches for numbers this branch already knows are stale. Short-cache so we
   // retry the CLI again soon.
   if (_lastGood) {
-    const result = { ..._lastGood, stale: true };
-    _cache = result;
-    _cacheAt = now - (CACHE_MS - 5_000);
-    return result;
+    return publish(gen, { ..._lastGood, stale: true }, now - (CACHE_MS - 5_000));
   }
 
   // Never had good data. CLI ran but lines absent → treat as genuine <1%.
@@ -552,9 +631,7 @@ async function _doFetch(now, force = false) {
     ? { ok: true, session5hPct: 0, session5hWindowSec: 18000,
         week7dPct: 0, week7dWindowSec: 604800, fetchedAt: now }
     : { ok: false, fetchedAt: now };
-  _cache = result;
-  _cacheAt = now - (CACHE_MS - 5_000);
-  return result;
+  return publish(gen, result, now - (CACHE_MS - 5_000));
 }
 
 /**
@@ -579,9 +656,29 @@ async function _doFetch(now, force = false) {
  * the shared request budget, and one that reset it would make switching a way to
  * hammer it. Until the store answers for the new account, "no reading yet" is
  * the honest thing to serve.
+ *
+ * Clearing the three variables is not enough on its own, because a fetch that is
+ * already running is not a variable. `_doFetch` writes `_cache` and `_lastGood`
+ * AFTER its awaits, so one that read the store before the switch and resolves
+ * after it put the previous account's numbers back into both, undoing this call
+ * from the other side of an await — and callers arriving in that window were
+ * handed the same in-flight promise rather than a read that knows the account
+ * moved. The window is real: a forced fetch goes through nudgeAndReread, which
+ * sleeps REREAD_TRIES * REREAD_GAP_MS = 2.4 seconds by construction, comfortably
+ * longer than a `cswap switch`.
+ *
+ * So the generation counter moves too. Every write in `_doFetch` is stamped with
+ * the generation that was current when that read started, and publish() drops
+ * any write whose stamp is stale — the fetch still resolves, and whoever asked
+ * for it still gets its answer, but that answer no longer becomes this module's.
+ * `_inflight` is released for the same reason: the next caller must start a read
+ * of its own rather than join one that is describing the account the deck just
+ * left.
  */
 export function invalidateQuotaCache() {
   _cache = null;
   _cacheAt = 0;
   _lastGood = null;
+  _generation++;
+  _inflight = null;
 }