npm - agent-dag - Versions diffs - 1.43.0 → 1.45.0 - Mend

agent-dag 1.43.0 → 1.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/README.md +13 -7
package/bin/agent-dag.js +87 -9
package/bin/deck.js +133 -22
package/dist/web/assets/index-Bdl1LX0-.css +1 -0
package/dist/web/assets/index-jXBjwwZC.js +89 -0
package/dist/web/index.html +2 -2
package/hook/hook.js +120 -31
package/package.json +2 -2
package/src/server/args.mjs +113 -15
package/src/server/ccusage.mjs +105 -1
package/src/server/claude-accounts.mjs +145 -1
package/src/server/codex-auth.mjs +9 -4
package/src/server/codex-quota.mjs +95 -3
package/src/server/codex-usage.mjs +163 -9
package/src/server/cswap-admin.mjs +346 -40
package/src/server/cswap-auto.mjs +365 -12
package/src/server/cswap-install.mjs +238 -17
package/src/server/exec.mjs +233 -26
package/src/server/index.mjs +1994 -157
package/src/server/installer.mjs +173 -11
package/src/server/invoked-as.mjs +16 -14
package/src/server/quota.mjs +131 -34
package/src/server/retire-sound-hook.mjs +315 -0
package/src/server/self-update.mjs +262 -21
package/src/server/supervisor.mjs +103 -0
package/src/server/system-metrics.mjs +105 -7
package/src/server/uv-bootstrap.mjs +43 -11
package/dist/web/assets/index-BxAZQc7O.css +0 -1
package/dist/web/assets/index-DRgZVqF-.js +0 -78
package/hook/notify.js +0 -60
package/src/server/sound-hook.mjs +0 -390

package/dist/web/index.html CHANGED Viewed

@@ -40,8 +40,8 @@
         document.documentElement.setAttribute("data-theme", stored === "light" ? "light" : "dark");
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-DRgZVqF-.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BxAZQc7O.css">
+    <script type="module" crossorigin src="/assets/index-jXBjwwZC.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Bdl1LX0-.css">
   </head>
   <body>
     <div id="root"></div>

package/hook/hook.js CHANGED Viewed

@@ -34,9 +34,38 @@ function parseProvider(argv) {
 }
 const PROVIDER = parseProvider(process.argv.slice(2));
+/**
+ * The one spelling of a directory, so that a path this process reports and a
+ * path bin/deck.js published can be compared as strings.
+ *
+ * Resolving symlinks is the half that is easy to think you can skip, because on
+ * POSIX a cwd comes from getcwd(3) and has none left in it. Windows has no such
+ * guarantee — GetCurrentDirectoryW returns the string the directory was set
+ * with, junction, `subst` drive and all — so a workspace reached that way only
+ * matches if BOTH sides go through here. The server's rollout watcher keeps its
+ * own copy of this rule under the name canonicalCwd, for the Codex sessions that
+ * never reach this file; a test walks one path through both. A path that does
+ * not resolve keeps its resolved form, which is also what canonicalWorkspace
+ * does with a directory the user has not created yet.
+ *
+ * `.native` IS THE RULE, not a detail. fs.realpathSync is a JavaScript
+ * lstat-and-readlink walk that resolves symlinks and junctions and nothing else;
+ * fs.realpathSync.native is GetFinalPathNameByHandleW, which also expands a DOS
+ * 8.3 short component to its long form. This used to call the plain one while
+ * the server's canonicalCwd went through the native one, so the moment a path
+ * arrived short — `%TEMP%` under a shortened profile directory, which is what
+ * every GitHub Windows runner has — the two canonicalisers that exist to agree
+ * disagreed by a whole path: C:\Users\RUNNER~1\… against C:\Users\runneradmin\….
+ * canonicalWorkspace in src/server/index.mjs says the rest of it, including why
+ * the long form is the canonical one; all three sites name `.native` out loud.
+ *
+ * Exported for that test: it is half of what `--workspace` means, and a
+ * predicate handed an already-canonical path cannot show that the caller
+ * canonicalises.
+ */
 function normPath(p) {
   let r = path.resolve(p);
-  try { r = fs.realpathSync(r); } catch {}
+  try { r = fs.realpathSync.native(r); } catch {}
   return r;
 }
@@ -235,29 +264,33 @@ function sameProof(got, want) {
   return a.length === b.length && crypto.timingSafeEqual(a, b);
 }
-// Two round trips now happen per target, and main()'s hard cap is 1500ms, so
-// the pair has to fit inside it with room to spare. The challenge is a bodyless
-// GET to a loopback port — sub-millisecond when a deck is there, and instant
+// Two round trips happen per target, and main()'s hard cap is 1500ms, so the
+// pair has to fit inside it with room to spare. The challenge is a bodyless GET
+// to a loopback port — sub-millisecond when a deck is there, and instant
 // ECONNREFUSED when nothing is.
+//
+// They are now separated by a barrier: every target is challenged, then the
+// election is decided, then the payload goes out (#695). The worst case is
+// unchanged — the challenges run in parallel, so it is still one 400ms deadline
+// followed by one 1000ms deadline. What the barrier does cost is that an honest
+// deck's POST waits for the slowest challenge in the set, which only matters
+// when some OTHER record's port accepts a connection and then says nothing. A
+// ghost port with nothing behind it refuses instantly and delays no one.
 const CHALLENGE_TIMEOUT_MS = 400;
 const POST_TIMEOUT_MS = 1000;
 /**
- * Ask the listener to prove it is the deck that wrote `d`, and POST the payload
- * only once it has. `done` runs exactly once, whatever the outcome — a refused
- * connection, a silent port, a wrong answer and a delivered event all just mean
- * this target is finished.
+ * Ask the listener to prove it is the deck that wrote `d`. `cb` is called
+ * exactly once with true or false — a refused connection, a silent port and a
+ * wrong answer are all just "not the deck this record describes".
  *
- * A deck that advertised no token is posted to directly: see requiresProof.
- *
- * `persists` is this deck's answer from electWriters: true for the one deck
- * that logs the event, false for every other one it is also drawn on.
+ * A deck that advertised no token cannot be asked and passes: see requiresProof.
  */
-function deliver(d, body, persists, done) {
+function prove(d, cb) {
   let settled = false;
-  const finish = () => { if (settled) return; settled = true; done(); };
+  const finish = ok => { if (settled) return; settled = true; cb(ok); };
-  if (!requiresProof(d)) return post(d, body, persists, finish);
+  if (!requiresProof(d)) return finish(true);
   const nonce = crypto.randomBytes(16).toString("hex");
   const want = challengeProof(d.token, nonce);
@@ -269,31 +302,79 @@ function deliver(d, body, persists, done) {
     method: "GET",
     timeout: CHALLENGE_TIMEOUT_MS,
   }, res => {
-    if (res.statusCode !== 200) { res.resume(); return res.on("end", finish); }
+    if (res.statusCode !== 200) { res.resume(); return res.on("end", () => finish(false)); }
     let answer = "";
     res.setEncoding("utf8");
     res.on("data", c => {
       answer += c;
       // A deck answers in ~100 bytes. Anything pouring data at us is not one,
       // and must not be allowed to grow this buffer without bound.
-      if (answer.length > 4096) { req.destroy(); finish(); }
+      if (answer.length > 4096) { req.destroy(); finish(false); }
     });
     res.on("end", () => {
       // Already given up on this target — a flood we cut off above. Whatever
       // arrived before that is not an answer we are going to act on.
       if (settled) return;
       let proof;
-      try { proof = JSON.parse(answer).proof; } catch { return finish(); }
-      if (!sameProof(proof, want)) return finish();
-      post(d, body, persists, finish);
+      try { proof = JSON.parse(answer).proof; } catch { return finish(false); }
+      finish(sameProof(proof, want));
     });
   });
-  req.on("error", finish);
+  req.on("error", () => finish(false));
   req.on("timeout", () => req.destroy());
   req.end();
 }
-function post(d, body, persists, finish) {
+/**
+ * Challenge every target, then hand back the ones that answered — in the order
+ * they were given, so the election below is a function of the records alone.
+ *
+ * WHY THIS RUNS BEFORE THE ELECTION AND NOT AFTER IT (#695). The two round trips
+ * per target have always both happened; they used to happen in the wrong order.
+ * electWriters ran over every record whose pid was merely alive, and only then
+ * did deliver() challenge each target and drop the ones that could not answer.
+ * So a record left behind by a deck that is gone — SIGKILL, an OOM kill, a power
+ * cut, a console window closed on Windows, none of which run the shutdown that
+ * unlinks it — kept passing the one staleness test there is the moment the OS
+ * handed its pid to some other long-lived process. If it also named a port below
+ * every real deck's, it WON the election, was never posted to because it could
+ * not answer, and no other deck was posted to with the flag either: every deck
+ * drew the event, all of them were told `?persist=0`, and events.jsonl stopped
+ * growing. Silently, for as long as that file sat in the directory.
+ *
+ * The election has to be decided over the decks that are actually going to be
+ * handed the payload, and the only thing that establishes that is the handshake.
+ * So: prove, then elect, then post. It costs no extra round trip, only this
+ * ordering, and it is the same reordering src/server/index.mjs makes in
+ * readLiveDecks for the Codex rollouts no hook ever sees.
+ *
+ * The record is NOT unlinked when a target fails. A dead pid is proof the deck
+ * is gone and is swept above; a failed challenge is not — a deck restarting
+ * under its supervisor refuses connections for a moment while its record still
+ * stands, and a merely busy one can miss the 400ms deadline. Deleting another
+ * deck's registration on that evidence trades a bug that loses log lines for one
+ * that loses a whole deck's events, and it buys nothing now that the election no
+ * longer believes the record: a ghost that survives on disk costs one instant
+ * ECONNREFUSED per hook run and decides nothing.
+ */
+function proveTargets(targets, cb) {
+  const ok = new Array(targets.length).fill(false);
+  let pending = targets.length;
+  const settle = () => { if (--pending <= 0) cb(targets.filter((_, i) => ok[i])); };
+  targets.forEach((d, i) => prove(d, answered => { ok[i] = answered; settle(); }));
+}
+/**
+ * Hand this deck the payload. `done` runs exactly once, whatever the outcome —
+ * a delivered event, a refused connection and a socket that errors after the
+ * response are all just "this target is finished".
+ *
+ * `persists` is this deck's answer from electWriters: true for the one deck that
+ * logs the event, false for every other one it is also drawn on.
+ */
+function post(d, body, persists, done) {
+  let settled = false;
+  const finish = () => { if (settled) return; settled = true; done(); };
   const req = http.request({
     hostname: "127.0.0.1",
     port: d.port,
@@ -367,9 +448,9 @@ function main() {
       let d;
       try { d = JSON.parse(fs.readFileSync(path.join(DIR, file), "utf8")); } catch { continue; }
       if (typeof d.workspace !== "string" || !d.pid || !d.port) continue;
-      // A missing token is not a reason to drop the file here — deliver()
-      // decides what a target has to prove, and a deck older than the handshake
-      // can prove nothing. See requiresProof.
+      // A missing token is not a reason to drop the file here — prove() decides
+      // what a target has to prove, and a deck older than the handshake can
+      // prove nothing. See requiresProof.
       if (!isAlive(d.pid)) {
         try { fs.unlinkSync(path.join(DIR, file)); } catch {}
@@ -388,13 +469,21 @@ function main() {
     if (!targets.length) return process.exit(0);
-    // One deck per events log records this event; the others only draw it.
-    const writers = electWriters(targets);
+    // Prove, elect, post — in that order, and see proveTargets for what the
+    // other order cost. A record whose pid is merely alive has established
+    // nothing: it may be a deck that died and had its pid recycled, and electing
+    // one of those to write the log meant nobody wrote it (#695).
+    proveTargets(targets, proven => {
+      if (!proven.length) return process.exit(0);
-    let pending = targets.length;
-    const done = () => { if (--pending <= 0) process.exit(0); };
+      // One deck per events log records this event; the others only draw it.
+      const writers = electWriters(proven);
-    for (const d of targets) deliver(d, taggedInput, writers.has(d), done);
+      let pending = proven.length;
+      const done = () => { if (--pending <= 0) process.exit(0); };
+      for (const d of proven) post(d, taggedInput, writers.has(d), done);
+    });
   });
 }
@@ -403,5 +492,5 @@ function main() {
 // require() it exports the rules it decides by — matching, election, the
 // handshake — and starts nothing, which is what lets them be tested without a
 // 1.5s exit timer in the test runner.
-module.exports = { capturesSession, cwdInWorkspace, foldsCase, electWriters, challengeProof, requiresProof };
+module.exports = { capturesSession, cwdInWorkspace, foldsCase, normPath, electWriters, challengeProof, requiresProof };
 if (require.main === module) main();

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "agent-dag",
-  "version": "1.43.0",
-  "description": "Live deck of Claude Code and Codex agents — watch tool calls, token spend and every Claude Code subagent on one calm canvas. Also available as npx ccdeck and npx agent-dag.",
+  "version": "1.45.0",
+  "description": "Live deck of Claude Code and Codex agents — watch tool calls, token spend and every Claude Code subagent on one calm canvas. Run it with npx ccdeck.",
   "type": "module",
   "bin": {
     "agents-deck": "bin/agent-dag.js",

package/src/server/args.mjs CHANGED Viewed

@@ -10,21 +10,97 @@
 // bin/deck.js is the only caller. The parser is the whole of the module's
 // surface; the tables it matches against stay inside it.
+/**
+ * Is this token a flag rather than somebody's value?
+ *
+ * A leading `-` and nothing else, because the alternatives are worse. Matching
+ * the known flag list would refuse `--workspace --prot` — a typo eating the next
+ * token is the same accident as a real flag eating it, and the one shape that
+ * must be caught is the one nobody spelled right. Refusing every value that
+ * begins with `-` would refuse `--port -1`, which is a number the user meant and
+ * which deserves the port error below rather than a "missing value" one.
+ *
+ * So: a leading `-`, except a plain negative number. The negative-number carve
+ * is the only exception, and it is small on purpose.
+ *
+ * WHAT THIS DOES ON EACH PLATFORM. Nothing, is the intent, to any real path.
+ * POSIX absolute (`/srv/proj`), POSIX relative (`./sub`, `sub`), `~/proj`, a
+ * Windows drive letter (`C:\Users\u\proj`, `c:/users/u/proj`), a UNC share
+ * (`\\srv\share\proj`), a Windows long path (`\\?\C:\proj`) and a bare
+ * `events.jsonl` all begin with something other than `-`, so all of them are
+ * values. A drive letter is not a flag on any platform and is never read as one:
+ * `C:` starts with `C`. What IS refused is a directory whose name really begins
+ * with a dash, which the user can still pass as `./-weird` — a two-character
+ * price for catching `--workspace $UNSET --no-persist`.
+ */
+export function looksLikeFlag(token) {
+  return typeof token === "string" && token.startsWith("-") && !/^-\d+(?:\.\d+)?$/.test(token);
+}
+/**
+ * Is this a port the deck could bind? Digits only, inside the range Node's
+ * `listen` accepts.
+ *
+ * `Number()` alone is far too willing: it takes `" 4500 "`, `0x10e4`, `1e3` and
+ * `Infinity`, and turns everything else into the `NaN` that used to reach
+ * `listen` and die there. The whole point of asking here is to answer BEFORE the
+ * deck has installed hooks and probed for tools, and to answer about the string
+ * the user actually typed. See bin/deck.js, which prints the flag and the value
+ * back at them.
+ */
+export function isPortValue(raw) {
+  if (typeof raw !== "string" && typeof raw !== "number") return false;
+  const s = String(raw).trim();
+  if (!/^\d+$/.test(s)) return false;
+  const n = Number(s);
+  return n >= 0 && n <= 65535;
+}
 /**
  * Parse `process.argv.slice(2)`.
  *
- * Returns the flags that were set, plus `unknown` — every token the loop did
- * not recognise, in the order it met them. That list is the point of this
- * module: the loop used to have no `else`, so `ccdeck --prot 4500` booted on
- * 4317 and said nothing, and a typo was indistinguishable from a flag that
- * worked.
+ * Returns the flags that were set, plus two lists that are always present and
+ * always arrays:
+ *
+ *   `unknown`     — every token the loop did not recognise, in the order it met
+ *                   them. That list is the point of this module: the loop used
+ *                   to have no `else`, so `ccdeck --prot 4500` booted on 4317 and
+ *                   said nothing, and a typo was indistinguishable from a flag
+ *                   that worked.
+ *   `incomplete`  — every value-taking flag that was given no value it could
+ *                   use, as `{ flag, expects }`, `flag` spelled the way the user
+ *                   spelled it. bin/deck.js prints one row per entry.
+ *
+ * THE THREE FLAGS THAT TAKE A VALUE (`--port`/`-p`, `--workspace`, `--history`)
+ * used to consume the next token with `args[++i]` whatever it was. That is right
+ * for `--port 4500` — the value must never be re-examined as a token of its own,
+ * or every correct command line would report its own port as an unknown option,
+ * and a warning that fires on correct input is a warning everybody learns to
+ * ignore. It was wrong for a value that is itself a flag (#697): `ccdeck
+ * --workspace $PROJ --no-persist` with `PROJ` unset is, after word splitting,
+ * `ccdeck --workspace --no-persist`. The deck scoped itself to a directory
+ * called `--no-persist`, wrote to the shared events log anyway, and reported
+ * neither — `unknown` stayed empty, because the token that would have gone in it
+ * had been eaten.
+ *
+ * So the consume is conditional now, and it refuses three shapes:
+ *
+ *   * the next token looks like a flag — NOT consumed, so the loop meets it on
+ *     the next pass and it is parsed as the flag it is, or reported as unknown.
+ *     That is also what fixes the supervisor case in bin/agent-dag.js: a
+ *     respawn appends `--port <bound>` to the user's argv, and an argv ending in
+ *     a bare `--workspace` used to eat the `--port` and drop the deck back on
+ *     4317, out from under the tab the user was looking at.
+ *   * there is no next token at all — the trailing `--workspace`, which used to
+ *     set `undefined` and mean "the default", silently.
+ *   * the next token is empty or blank — consumed (it was quoted, so it was
+ *     meant as the value) but not used. `--workspace ""` is a variable that did
+ *     not expand, not a request for machine-wide capture, and answering it with
+ *     the widest possible scope is the one answer that cannot be recovered from.
  *
- * The three flags that TAKE a value (`--port`, `--workspace`, `--history`)
- * consume it with `args[++i]`, so the value is never re-examined as a token of
- * its own and cannot land in `unknown` — `--port 4500` says nothing about
- * `4500`, and `--workspace ~/some dir` nothing about the path. That is the way
- * an unknown-flag warning usually goes wrong, and it is asserted rather than
- * assumed; see src/web/__tests__/argv-480.test.ts.
+ * In all three the flag is left UNSET, so the deck falls back to its documented
+ * default, and the flag is named in `incomplete` so the fallback is said out
+ * loud rather than discovered later.
  *
  * A bare word is `unknown` too, and deliberately: the deck takes no positional
  * arguments at all, so `ccdeck ~/proj` is the same mistake as `ccdeck --workpace
@@ -35,19 +111,41 @@
  * one used to be dropped in silence (see launchNpx in bin/agent-dag.js).
  */
 export function parseArgs(args) {
-  const out = { unknown: [] };
+  const out = { unknown: [], incomplete: [] };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
+    // The value of the flag just matched, or `undefined` when there is nothing
+    // usable there. Closes over `i` so it can decline to advance it: not
+    // consuming is what hands the token back to the loop.
+    const value = (expects) => {
+      const next = args[i + 1];
+      if (next === undefined || looksLikeFlag(next)) {
+        out.incomplete.push({ flag: a, expects });
+        return undefined;
+      }
+      i++;
+      if (String(next).trim() === "") {
+        out.incomplete.push({ flag: a, expects });
+        return undefined;
+      }
+      return next;
+    };
+    // Assigned only when there is a value, so an unusable one leaves the key
+    // absent and the deck on its default — see the doc comment.
+    const set = (key, expects) => {
+      const v = value(expects);
+      if (v !== undefined) out[key] = v;
+    };
     if (a === "-h" || a === "--help") out.help = true;
     else if (a === "-v" || a === "--version") out.version = true;
-    else if (a === "-p" || a === "--port") out.port = args[++i];
+    else if (a === "-p" || a === "--port") set("port", "a port number");
     else if (a === "--no-open") out.noOpen = true;
     else if (a === "--uninstall") out.uninstall = true;
-    else if (a === "--workspace") out.workspace = args[++i];
+    else if (a === "--workspace") set("workspace", "a path");
     else if (a === "--scope") out.scope = true;
     else if (a === "--all") out.all = true; // legacy no-op (now default)
     else if (a === "--no-persist") out.noPersist = true;
-    else if (a === "--history") out.history = args[++i];
+    else if (a === "--history") set("history", "a path");
     else if (a === "--codex") out.codex = true;
     else if (a === "--no-codex") out.noCodex = true;
     else if (a === "--claude") out.claude = true;

package/src/server/ccusage.mjs CHANGED Viewed

@@ -30,6 +30,75 @@ const MARKER = path.join(CACHE_DIR, ".last-update-check");
 const _cache = new Map(); // key `${since}|${until}` → { result, at }
+// How much a read is allowed to cost. /api/ccusage is a GET, deliberately: a
+// cross-site read of the loopback port is an ordinary top-level navigation and
+// isTrustedRead is right not to refuse it. What was missing is a ceiling on
+// what one of those reads may start. Before #544, thirty distinct `since`
+// values were thirty concurrent `node <PKG_DIR>/src/cli.js daily --json`
+// children — each with a ninety-second deadline, each walking the whole
+// ~/.claude log tree, doubled again whenever runDaily retried flagless — and
+// thirty permanent Map entries. isCliDate admits all 10^8 eight-digit strings
+// on purpose (a date outside the logs is ccusage's question to answer, not the
+// deck's to guess at), so the map's key space was 10^8 and its eviction policy
+// was none.
+//
+// Both numbers are set against what the feature does rather than against the
+// attack. The usage-history modal asks for one range at a time and offers three
+// presets, so four ranges outstanding at once is already more than a human
+// clicking as fast as they can, and thirty-two remembered ranges is more than
+// one sitting will ever look at. Whatever exceeds either is not a reader.
+const CACHE_MAX = 32;
+const MAX_OUTSTANDING = 4;
+/** Ranges being fetched right now, keyed exactly as `_cache` is, so two callers
+ *  asking the same question wait on one child instead of starting a second. The
+ *  cache alone could never do this: it is written when a run finishes, and the
+ *  whole window this is about is the ninety seconds before that. */
+const _inflight = new Map();
+/** The tail of the run queue, and how many runs are alive behind it.
+ *
+ *  Serialised rather than merely counted, because two ccusage runs are two
+ *  walks of the same directory tree: running them at once is slower than
+ *  running them in sequence, so the queue costs a concurrent caller nothing it
+ *  was actually going to get. What it buys is that a flood is one child at a
+ *  time rather than a child per request. */
+let _chain = Promise.resolve();
+let _outstanding = 0;
+/** Run `job` after every run already queued, whatever became of them — a run
+ *  that threw must not take the queue down with it. */
+function queued(job) {
+  _outstanding += 1;
+  const started = _chain.then(job, job);
+  _chain = started.then(() => {}, () => {});
+  return started.finally(() => { _outstanding -= 1; });
+}
+/**
+ * Remember one range's answer, and keep the map from being somewhere a caller
+ * can grow without limit.
+ *
+ * Entries past CACHE_MS can never be served again, so they are the ones to drop
+ * first; only when dropping all of them is still not enough does the oldest
+ * surviving entry go, which Map's insertion order hands over for free.
+ * Re-writing a key moves it to the back, so the range someone is actually
+ * polling is the last one evicted rather than the first.
+ */
+function rememberRange(key, result, at) {
+  _cache.delete(key);
+  _cache.set(key, { result, at });
+  if (_cache.size <= CACHE_MAX) return;
+  for (const [k, v] of _cache) {
+    if (_cache.size <= CACHE_MAX) break;
+    if (at - v.at >= CACHE_MS) _cache.delete(k);
+  }
+  for (const k of _cache.keys()) {
+    if (_cache.size <= CACHE_MAX) break;
+    _cache.delete(k);
+  }
+}
 /**
  * The name to hand cmd.exe for one of npm's Windows shims: its full path when
  * one can be found, and the bare name only when none can.
@@ -835,6 +904,41 @@ export async function fetchCcusageDaily({ since, until, force = false } = {}) {
   const cached = _cache.get(key);
   if (!force && cached && now - cached.at < CACHE_MS) return cached.result;
+  // A run for this exact range is already going: join it. `force` joins too,
+  // rather than starting a competing child — what ?refresh=1 asks for is a
+  // reading newer than the cache, and a run still in progress is one.
+  const already = _inflight.get(key);
+  if (already) return already;
+  // Refused here, before anything is spawned or remembered. The caller that
+  // reaches this is the fifth distinct range in flight at once, which the modal
+  // cannot produce; queueing it would mean holding a request open behind up to
+  // four ninety-second deadlines, which is a worse answer than saying no.
+  if (_outstanding >= MAX_OUTSTANDING) {
+    return {
+      ok: false,
+      reason: "busy",
+      error: `${MAX_OUTSTANDING} usage ranges are already being read \u2014 try again in a moment`,
+      fetchedAt: now,
+    };
+  }
+  const run = queued(() => readRange(sinceArg, until, key))
+    .finally(() => { _inflight.delete(key); });
+  _inflight.set(key, run);
+  return run;
+}
+/**
+ * One ccusage run, once the queue has let it through.
+ *
+ * `now` is read here rather than carried in from the call, so `fetchedAt` and
+ * the cache stamp both mean "when this reading was taken" even for a run that
+ * waited its turn. With an empty queue that is the same instant the caller
+ * asked, which is what this always did.
+ */
+async function readRange(sinceArg, until, key) {
+  const now = Date.now();
   let result;
   let ran = null; // the runner that answered, for stamping a bad_output failure
   try {
@@ -892,7 +996,7 @@ export async function fetchCcusageDaily({ since, until, force = false } = {}) {
     };
   }
-  _cache.set(key, { result, at: now });
+  rememberRange(key, result, now);
   return result;
 }