agent-dag 3.2.1 → 3.4.0

package/src/server/browser-history.mjs

@@ -46,7 +46,8 @@
 // ── 3. THERE MAY BE NO SQLITE READER AT ALL ─────────────────────────────────
 //
 // `node:sqlite` exists only from Node 22.5, and this package declares
-// `engines: { node: ">=18" }` — CI itself runs Node 20. A top-level
+// `engines: { node: ">=18" }` — CI runs Node 22 on all three OSes and
+// Node 18 on one Linux leg, which is the version the package advertises. A top-level
 // `import "node:sqlite"` is therefore not an option: it throws
 // ERR_UNKNOWN_BUILTIN_MODULE at module load, before any of this file's own error
 // handling exists, and takes the server's import graph with it. It is loaded
@@ -63,6 +64,9 @@ import { copyFile, mkdir, rm } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+const { COPYFILE_EXCL } = fsConstants;
 import { pathLookup, run } from "./exec.mjs";
 
 /**
@@ -230,7 +234,7 @@ const loadSqlite = async () => {
  * CLI is the fallback rather than the default because every call to it costs a
  * process, and this runs on a poll.
  *
- * The dynamic import is inside a try/catch and covers more than "Node 20 has no
+ * The dynamic import is inside a try/catch and covers more than "Node 18 has no
  * such module". Between 22.5 and 22.12 node:sqlite existed but required
  * `--experimental-sqlite`, which the deck is not started with, and the import
  * fails there too — the same catch, the same fallback, no version arithmetic
@@ -333,9 +337,31 @@ export async function readVisitsSince(historyPath, sinceChromeTime, opts = {}) {
 
   let copyPath = null;
   try {
-    await makeDir(copyDir, { recursive: true });
-    copyPath = join(copyDir, `history-${process.pid}-${++copySeq}.sqlite`);
-    await copy(historyPath, copyPath);
+    // MODE 0700, AND A NAME NOBODY ELSE CAN PREDICT.
+    //
+    // `os.tmpdir()` is per-user on macOS (/var/folders/…, 0700) and on Windows,
+    // and on Linux it is the shared, world-writable /tmp. A fixed directory
+    // name and `history-<pid>-<n>.sqlite` inside it meant three things there,
+    // all of them avoidable:
+    //
+    //   * a complete, unencrypted copy of the user's browsing history, mode
+    //     0644, under a predictable path, readable by every other account on
+    //     the machine for the life of the poll;
+    //   * another UID can create the directory first — `mkdir` with `recursive`
+    //     swallows EEXIST and keeps THEIR mode — and then read every copy, or
+    //     plant a symlink at the name and have this overwrite a file the user
+    //     owns, because `copyFile` was called without COPYFILE_EXCL;
+    //   * a second user on the same box then fails EACCES on a directory they
+    //     cannot write, and their deck is degraded for good.
+    //
+    // The mode is set on creation AND after, because the directory may already
+    // exist from an earlier run of this same deck.
+    await makeDir(copyDir, { recursive: true, mode: 0o700 });
+    copyPath = join(copyDir, `history-${process.pid}-${++copySeq}-${randomUUID().slice(0, 8)}.sqlite`);
+    // COPYFILE_EXCL: refuse rather than write through a symlink or over a file
+    // that is already there. A refusal is one degraded poll; the alternative is
+    // clobbering whatever the name pointed at.
+    await copy(historyPath, copyPath, COPYFILE_EXCL);
   } catch (err) {
     // The browser is not installed, the profile moved, the disk is full. All of
     // them are "no rows this poll", none of them is a reason to stop polling.

package/src/server/browser-presence.mjs

@@ -30,20 +30,65 @@ import { basename } from "node:path";
 import { browserRoots, hasExtension, profileDirs } from "./browser-profiles.mjs";
 import { run } from "./exec.mjs";
 
-/** The application name each browser's processes carry, for the probes below.
- *  Only the ones whose name is knowable; a root with no entry here is still
- *  reported as installed, just never as running. */
+/**
+ * The name each browser's processes carry — PER PLATFORM, because they do not
+ * agree.
+ *
+ * This used to be one table of macOS bundle display names, sent to all three
+ * probes. `tasklist /FI "IMAGENAME eq Google Chrome.exe"` matches nothing and
+ * exits **0** printing `INFO: No tasks are running…`, so the probe read
+ * `ok: true` and returned a confident `false`; `pgrep -x "Google Chrome"`
+ * matches against `comm`, which on Linux is `chrome`. Every browser on Windows
+ * and Linux therefore reported "not running", `relayLink` was never called, and
+ * the relay half of this panel was dead on two of the three platforms — while
+ * the module's own header forbids exactly that: a state that means "definitely
+ * not connected" when nothing established it.
+ *
+ * Arc is macOS-only and has no entry elsewhere, which is the honest answer: a
+ * root with no name here is reported as installed and never as running.
+ */
 const APP_NAME = {
-  chrome: "Google Chrome",
-  "chrome-beta": "Google Chrome Beta",
-  "chrome-canary": "Google Chrome Canary",
-  chromium: "Chromium",
-  brave: "Brave Browser",
-  edge: "Microsoft Edge",
-  vivaldi: "Vivaldi",
-  arc: "Arc",
+  darwin: {
+    chrome: "Google Chrome",
+    "chrome-beta": "Google Chrome Beta",
+    "chrome-canary": "Google Chrome Canary",
+    chromium: "Chromium",
+    brave: "Brave Browser",
+    edge: "Microsoft Edge",
+    vivaldi: "Vivaldi",
+    arc: "Arc",
+  },
+  // Image names, which is what tasklist's IMAGENAME filter compares against.
+  // The probe appends `.exe`, so these are spelled without it, exactly as the
+  // POSIX ones are.
+  win32: {
+    chrome: "chrome",
+    "chrome-beta": "chrome",
+    "chrome-canary": "chrome",
+    chromium: "chrome",
+    brave: "brave",
+    edge: "msedge",
+    vivaldi: "vivaldi",
+  },
+  // `comm`, which is what `pgrep -x` matches and what the packages install as.
+  linux: {
+    chrome: "chrome",
+    "chrome-beta": "chrome",
+    "chrome-canary": "chrome",
+    chromium: "chromium",
+    brave: "brave",
+    edge: "msedge",
+    vivaldi: "vivaldi-bin",
+  },
 };
 
+/** The process name for a browser on a platform, or null when this platform
+ *  has no name for it — which is a different answer from "not running". */
+export function processName(key, platform = process.platform) {
+  const table = APP_NAME[platform] ?? APP_NAME.linux;
+  return table[key] ?? null;
+}
+
 /** Every address the relay currently resolves to.
  *
  *  Empty is not an error — a machine with no `dig`, or one where the name is
@@ -139,7 +184,7 @@ export async function browserSurvey({
   for (const root of roots) {
     const installed = exists(root.root);
     const profiles = installed ? profileDirs(root.root, deps.fs) : [];
-    const app = APP_NAME[root.key] ?? null;
+    const app = processName(root.key, platform);
     const running = installed && app ? await isRunning(app, platform, deps) : false;
     out.push({
       key: root.key,

package/src/server/browser-react.mjs

@@ -20,6 +20,9 @@
 // The session that opened it is still attached and can still read every other
 // tab. Only quitting takes anything back.
 import { run } from "./exec.mjs";
+// The one table of process names, shared with the presence probe so the reaction
+// and the "is it running" answer can never disagree about what to look for.
+import { processName } from "./browser-presence.mjs";
 
 /** Reactions this platform can actually carry out, in the order the panel
  *  should offer them. Never a list the caller has to filter again. */
@@ -107,17 +110,29 @@ export async function notify(title, body, platform = process.platform, deps = {}
     return r?.ok === true;
   }
   if (platform === "win32") {
-    // PowerShell's own toast, through the same argv discipline: the strings go
-    // in as parameters rather than as script text.
+    // THE STRINGS GO THROUGH THE ENVIRONMENT, and the previous spelling could
+    // not have worked at all. PowerShell documents that a string `-Command`
+    // must be the LAST parameter: everything after it is appended to the
+    // command text. So `… -t <title> -b <body>` was not two parameters, it was
+    // more script — pasted after `…Show($x)`, where it failed to parse — and
+    // `param($t,$b)` cannot receive arguments through `-Command` in any case.
+    // The toast therefore never appeared on Windows, for the reaction that is
+    // the default.
+    //
+    // That mistake also put attacker-chosen text into a script. `body` carries
+    // `episode.host`, which is `new URL(row.url).host` out of the browser's own
+    // history — the whole premise of this feature is that somebody else may
+    // have opened that page. `$env:` reads it as data at runtime, which is the
+    // same discipline the argv paths above keep.
     const r = await exec("powershell.exe", [
       "-NoProfile", "-NonInteractive", "-Command",
-      "param($t,$b); [void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime];"
+      "[void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime];"
       + "$x = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent(0);"
-      + "$n = $x.GetElementsByTagName('text'); $n.Item(0).AppendChild($x.CreateTextNode($t)) > $null;"
-      + "$n.Item(1).AppendChild($x.CreateTextNode($b)) > $null;"
+      + "$n = $x.GetElementsByTagName('text');"
+      + "$n.Item(0).AppendChild($x.CreateTextNode($env:CCDECK_TOAST_TITLE)) > $null;"
+      + "$n.Item(1).AppendChild($x.CreateTextNode($env:CCDECK_TOAST_BODY)) > $null;"
       + "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('ccdeck').Show($x)",
-      "-t", title, "-b", body,
-    ]).catch(() => null);
+    ], { env: { ...process.env, CCDECK_TOAST_TITLE: title, CCDECK_TOAST_BODY: body } }).catch(() => null);
     return r?.ok === true;
   }
   const r = await exec("notify-send", [title, body]).catch(() => null);
@@ -151,11 +166,18 @@ export async function quitBrowser(browserKey, platform = process.platform, deps
     ]).catch(() => null);
     return { ok: r?.ok === true, reason: r?.ok ? "quit" : "script_failed" };
   }
+  // NOT THE DISPLAY NAME WITH ITS SPACES REMOVED. `"Google Chrome"` became
+  // `GoogleChrome.exe` and `google-chrome`, and neither is a process on either
+  // platform — so this reaction was offered on Windows and Linux and could
+  // never once have worked. The names live in browser-presence, which is where
+  // the other probe reads them from, so the two cannot drift apart.
+  const proc = processName(browserKey, platform);
+  if (!proc) return { ok: false, reason: "unknown_browser" };
   if (platform === "win32") {
-    const r = await exec("taskkill", ["/IM", `${app.replace(/ /g, "")}.exe`, "/F"]).catch(() => null);
+    const r = await exec("taskkill", ["/IM", `${proc}.exe`, "/F"]).catch(() => null);
     return { ok: r?.ok === true, reason: r?.ok ? "quit" : "taskkill_failed" };
   }
-  const r = await exec("pkill", ["-x", app.toLowerCase().replace(/ /g, "-")]).catch(() => null);
+  const r = await exec("pkill", ["-x", proc]).catch(() => null);
   return { ok: r?.ok === true, reason: r?.ok ? "quit" : "pkill_failed" };
 }
 

package/src/server/browser-watch-store.mjs

@@ -48,7 +48,7 @@ const STORE_VERSION = 2;
  *  person could open and read. Trimmed oldest-first. */
 const KEEP = 500;
 
-export const storeDir = (home = claudeConfigDir()) => join(home, "agent-dag", "browser-watch");
+const storeDir = (home = claudeConfigDir()) => join(home, "agent-dag", "browser-watch");
 export const storePath = (home = claudeConfigDir()) => join(storeDir(home), "state.json");
 
 /** The plain-text log, which is the one file here a person opens themselves.
@@ -223,6 +223,22 @@ export async function readStore(home = claudeConfigDir(), deps = {}) {
  * driven — the one file whose loss this feature cannot absorb. installer.mjs
  * makes the same argument about settings.json, for the same reason.
  */
+/**
+ * One writer at a time, in this process.
+ *
+ * Three call sites write this file — the poll's snapshot, the settings route
+ * and the dismiss route — and none of them knew about the others. The queue is
+ * the same shape `log-writer.mjs` uses for its appends: a promise chain that
+ * survives a rejection, so one failed write cannot wedge every later one.
+ */
+let _chain = Promise.resolve();
+let _writeSeq = 0;
+function serialized(job) {
+  const started = _chain.then(job, job);
+  _chain = started.then(() => {}, () => {});
+  return started;
+}
+
 /**
  * Write the whole store, atomically.
  *
@@ -235,6 +251,11 @@ export async function readStore(home = claudeConfigDir(), deps = {}) {
  * test that greps this file's callers for the field.
  */
 export async function writeStore(state, home = claudeConfigDir(), deps = {}) {
+  return serialized(() => writeNow(state, home, deps));
+}
+
+/** The write itself, already inside the queue. */
+async function writeNow(state, home, deps) {
   const mk = deps.mkdir ?? mkdir;
   const write = deps.writeFile ?? writeFile;
   const mv = deps.rename ?? rename;
@@ -245,11 +266,44 @@ export async function writeStore(state, home = claudeConfigDir(), deps = {}) {
     episodes: (state.episodes ?? []).map(archivable),
     dismissed: [...new Set(state.dismissed ?? [])].slice(-DISMISS_KEEP),
   }, null, 2) + "\n";
-  const tmp = `${storePath(home)}.${process.pid}.tmp`;
+  // A NAME NO SECOND WRITE CAN BE USING. The pid distinguishes decks and not
+  // the calls inside one, and there are three writers in this process — the
+  // poll's snapshot, the settings route and the dismiss route — with nothing
+  // between them. Measured with a full 500-episode archive (~2.5 MB, past the
+  // 512 KiB writeFile chunk): eight concurrent runs left state.json unparseable
+  // in six of them and failed one call with ENOENT, renaming a temp file the
+  // other writer had already renamed away. readStore swallows a corrupt file,
+  // so the next poll reported an empty archive and no dismissals at all — total
+  // loss of the one file this feature exists to keep.
+  const tmp = `${storePath(home)}.${process.pid}.${++_writeSeq}.tmp`;
   await write(tmp, body, "utf8");
   await mv(tmp, storePath(home));
 }
 
+/**
+ * Read, change, write — with nothing else writing in between.
+ *
+ * `writeStore` writes what it is handed and merges nothing, which is right for
+ * a whole-state write and wrong for a caller that owns one field. The snapshot
+ * takes about 400ms — a 21 MB History copy plus the sqlite read — and used to
+ * write back the `dismissed` and `settings` it had read at the start, so a
+ * dismissal made while it ran was reverted by the next poll ten seconds later.
+ * The settings route and the dismiss route had the same shape against each
+ * other.
+ *
+ * So a caller that owns one field passes a function instead: it runs inside the
+ * same queue the write does, against the state on disk at that moment, and no
+ * other writer can slip between the read and the write.
+ */
+export async function updateStore(mutate, home = claudeConfigDir(), deps = {}) {
+  return serialized(async () => {
+    const current = await readStore(home, deps);
+    const next = (await mutate(current)) ?? current;
+    await writeNow(next, home, deps);
+    return next;
+  });
+}
+
 /**
  * The archive with `seen` folded into it, newest first and capped.
  *

package/src/server/browser-watch.mjs

@@ -27,14 +27,14 @@
 // is running, so a deck that was closed all weekend still answers Monday's
 // question completely — which is why there is no process to keep alive and no
 // gap to apologise for.
-import { readFileSync, statSync } from "node:fs";
+import { statSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { claudeConfigDir } from "./claude-dir.mjs";
 import { discoverProfiles } from "./browser-profiles.mjs";
-import { readVisitsSince } from "./browser-history.mjs";
+import { msToChromeTime, readVisitsSince } from "./browser-history.mjs";
 import { classify, toEpisodes, defaultExclusions, isProgramNavigation } from "./agent-activity.mjs";
-import { appendLog, logPath, mergeEpisodes, readStore, undismissed, writeStore } from "./browser-watch-store.mjs";
+import { appendLog, logPath, mergeEpisodes, readStore, undismissed, updateStore, writeStore } from "./browser-watch-store.mjs";
 import { browserSurvey } from "./browser-presence.mjs";
 import { available, performable, react } from "./browser-react.mjs";
 import { RELAY_HOST } from "./relay-guard.mjs";
@@ -86,6 +86,22 @@ function mtimeMs(file, deps) {
  * schedule. `stale` is reported so the panel can say when it last actually
  * looked rather than implying the answer is a live one.
  */
+/**
+ * Is that pid still running?
+ *
+ * A bare `catch { continue; }` used to stand where this is called, which threw
+ * away the one distinction that matters: a process this account may not signal
+ * answers EPERM on POSIX and EACCES on Windows (libuv maps
+ * ERROR_ACCESS_DENIED), and both mean ALIVE. Treating them as gone made an
+ * elevated deck invisible to the writer election below, which is how a machine
+ * ends up with two elected writers — duplicate log lines, duplicate reactions,
+ * and two writers racing the same rename.
+ */
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return !!e && (e.code === "EPERM" || e.code === "EACCES"); }
+}
+
 async function visitsFor(profile, { sinceChromeTime, copyDir, deps = {} }) {
   const stamp = mtimeMs(profile.historyPath, deps);
   if (stamp === null) return { rows: [], degraded: true, reason: "no-history-file", stamp: null };
@@ -227,7 +243,7 @@ export async function registeredDeckPorts(deps = {}) {
     try {
       const d = JSON.parse(await readFile(join(dir, f), "utf8"));
       if (typeof d?.pid !== "number" || typeof d?.port !== "number") continue;
-      try { process.kill(d.pid, 0); } catch { continue; }
+      if (!pidAlive(d.pid)) continue;
       ports.push(d.port);
     } catch { /* corrupt, or gone between listing and read */ }
   }
@@ -283,7 +299,7 @@ function note(level, text, atMs = Date.now(), parts = null) {
   if (logLines.length > LOG_MAX) logLines.length = LOG_MAX;
 }
 
-export function watchLog() {
+function watchLog() {
   return logLines.slice();
 }
 
@@ -341,7 +357,7 @@ async function isReactingDeck(deps = {}) {
       // than by a version comparison this would otherwise have to keep.
       if (d.watch !== true) continue;
       // A record whose process is gone is a leftover, not a rival.
-      try { process.kill(d.pid, 0); } catch { continue; }
+      if (!pidAlive(d.pid)) continue;
       if (!best || d.port < best.port || (d.port === best.port && d.pid < best.pid)) best = d;
     } catch { /* corrupt, or gone between listing and read */ }
   }
@@ -438,6 +454,24 @@ export async function browserWatchSnapshot({
   now = Date.now(),
   platform = process.platform,
   env = process.env,
+  // WHETHER TO READ THE BROWSERS AT ALL ON THIS CALL.
+  //
+  // The panel's badge polls this route every five minutes from the moment the
+  // page loads, and the read is not free or invisible: it copies each Chromium
+  // profile's whole History database into a temp file, queries it, and deletes
+  // the copy. That happened whether or not the watch was switched on, because
+  // `enabled` gates only what is KEPT and what is REACTED to.
+  //
+  // A switch that says off while the deck goes on copying the user's browsing
+  // history every five minutes is not a switch. So the background poll asks for
+  // `live=0`, and with the watch off that is honoured: the archive answers, and
+  // nothing touches a browser. Two things still read live — a watch that is ON,
+  // because recording in the background is the whole feature, and the panel
+  // itself, because that is the user looking.
+  //
+  // Named for what it does rather than `live`, which is already the local name
+  // for the episodes this poll built.
+  readBrowsers = true,
   deps = {},
 } = {}) {
   // The store answers first and the caller's arguments override it, so the
@@ -458,6 +492,36 @@ export async function browserWatchSnapshot({
   if (quietMs === undefined) quietMs = minutes(store.settings.quietMinutes);
   if (gapMs === undefined) gapMs = minutes(store.settings.gapMinutes);
 
+  // The archive alone, for a poll that has not asked to look and a watch that
+  // is not recording. Everything below this line reads browsers.
+  if (!readBrowsers && !enabled) {
+    const archived = undismissed(store.episodes, store.dismissed);
+    return {
+      ok: true,
+      settings: store.settings,
+      reactions: available(platform),
+      log: watchLog(),
+      profiles: [],
+      browsers: [],
+      episodes: archived,
+      coverage: {
+        startedMs: STARTED_MS,
+        oldestVisitMs: null,
+        lastHumanMs: null,
+        quietMs: quietMs ?? 15 * 60_000,
+        logPath: logPath(),
+        checkedMs: _checkedMs,
+        checks: _checks,
+        archived: archived.length,
+        now,
+        // Said rather than implied: a reader who wonders why the profile list
+        // is empty gets the reason, in the same word the switch uses.
+        why: "the watch is off, so no browser was read on this poll",
+      },
+      degraded: false,
+    };
+  }
+
   const profiles = (deps.discoverProfiles ?? discoverProfiles)(platform, env, undefined, deps.fs);
   // Fixed for the life of the process, which is also what keeps the mtime cache
   // working: a floor computed from `now` moves every millisecond and would land
@@ -465,9 +529,11 @@ export async function browserWatchSnapshot({
   // it re-read and re-copied every database on every request while looking
   // perfectly correct, because only the cost was wrong.
   const sinceMs = STARTED_MS;
-  // Chrome counts microseconds from 1601. Built here rather than imported so the
-  // window is one expression the reader can check against the reader's own.
-  const sinceChromeTime = String((BigInt(sinceMs) + 11644473600000n) * 1000n);
+  // Chrome counts microseconds from 1601, and `msToChromeTime` is where that
+  // conversion lives — its own doc names this caller. The inline copy that used
+  // to stand here duplicated both constants and, unlike the helper, had no
+  // guard for a non-finite input: it threw where the helper returns "0".
+  const sinceChromeTime = msToChromeTime(sinceMs);
 
   const exclude = defaultExclusions(deckOrigins);
   const opts = {};
@@ -632,7 +698,21 @@ export async function browserWatchSnapshot({
     if (fresh.length > 0) {
       note("find", `${fresh.length} new episode${fresh.length === 1 ? "" : "s"} · ${kept.length} kept`, now);
     }
-    await (deps.writeStore ?? writeStore)({ settings: store.settings, episodes: kept, dismissed: store.dismissed }, undefined, deps);
+    // THE ARCHIVE IS OURS TO WRITE; THE OTHER TWO FIELDS ARE NOT. This poll
+    // takes about 400ms — a 21 MB History copy plus the sqlite read — and it
+    // used to write back the `dismissed` and `settings` it had read at the
+    // start, so a dismissal or a watch-off toggle made while it ran was
+    // reverted ten seconds later by the next poll. Re-merging inside the update
+    // keeps this function's own answer and takes the other two from disk as
+    // they are at the moment of the write.
+    const merge = cur => ({
+      settings: cur.settings,
+      episodes: mergeEpisodes(cur.episodes, live, now),
+      dismissed: cur.dismissed,
+    });
+    if (deps.updateStore) await deps.updateStore(merge, undefined, deps);
+    else if (deps.writeStore) await deps.writeStore(merge(store), undefined, deps);
+    else await updateStore(merge, undefined, deps);
     await (deps.appendLog ?? appendLog)(fresh, undefined, deps);
 
     // REACT ONLY TO WHAT IS NEW, AND ONLY ONCE. `fresh` is the set that was not

package/src/server/ccusage.mjs

@@ -19,7 +19,11 @@ import { killTree, pathLookup, shimPath, spawnSpec } from "./exec.mjs";
 import { oneLine, termColumns } from "./term.mjs";
 import { PRODUCT } from "./brand.mjs";
 
-const CACHE_MS = 120_000; // 2 min — modal is manual-open; cheap to keep warm
+// 60s, and it is the panel's poll interval rather than a number of its own: the
+// Usage panel asks once a minute and expects a reading that has actually moved,
+// so a longer cache would hand the same figure back and make the interval a
+// lie. The modal is manual-open and unaffected either way.
+const CACHE_MS = 60_000;
 const TIMEOUT_MS = 90_000;
 const INSTALL_TIMEOUT_MS = 120_000; // first-run npm install can be slow
 const UPDATE_CHECK_MS = 24 * 3600_000; // check npm for a newer ccusage once/day
@@ -823,6 +827,34 @@ let _byAgentUnsupported = false;
  */
 const blamesByAgent = (text) => /by-agent/i.test(String(text ?? ""));
 
+/**
+ * BOTH REPORTS FROM ONE LOAD.
+ *
+ * `daily` answers "what did this range cost" and `session` answers "which
+ * session spent it". They used to be two commands and therefore two children —
+ * two npx resolutions, two Node starts, and two full walks of every transcript
+ * on the machine for the same set of files.
+ *
+ * `--sections` is ccusage's own answer to that: one load, several report
+ * sections in one JSON object. Measured against this machine's logs, asking for
+ * `daily,session` returns exactly what the two runs returned — `daily` (with
+ * its `agents` split when `--by-agent` rides along), `session`, and one
+ * `totals` — so the deck reads the same fields off one child.
+ *
+ * Not on `session` alone: the panel's totals and its per-model split come from
+ * `daily`, so `daily` is the command and the sessions are the extra section.
+ */
+const SECTIONS = ["--sections", "daily,session"];
+const blamesSections = (text) => /sections/i.test(String(text ?? ""));
+
+/**
+ * A ccusage too old for `--sections`, remembered for the life of the process —
+ * the same narrow memory `_byAgentUnsupported` keeps, for the same reason: the
+ * retry costs one process on a machine that is already failing, and the memory
+ * costs the extra section for as long as the deck runs.
+ */
+let _sectionsUnsupported = false;
+
 /**
  * Run `daily` for a range, asking for the per-agent split, and give up the
  * split rather than the whole answer when this ccusage will not produce one.
@@ -937,6 +969,38 @@ export async function fetchCcusageDaily({ since, until, force = false } = {}) {
  * waited its turn. With an empty queue that is the same instant the caller
  * asked, which is what this always did.
  */
+/**
+ * The same range, grouped by session rather than by day.
+ *
+ * Returns `[]` for every failure, including a ccusage too old to have the
+ * subcommand. The panel's totals and its per-model split come from `daily`, and
+ * losing the session names must not lose those — an empty list draws one
+ * section short, which is the same thing that happens on a machine with no
+ * ccusage at all and is already a state the panel knows.
+ *
+ * WHAT `period` IS HERE, and it is the whole reason this is worth a second
+ * child: on a session row ccusage puts the SESSION ID in `period` — the same
+ * uuid Claude Code writes into every hook payload, and therefore the same key
+ * the canvas already files its agents under. So these rows join to the board by
+ * id, which is what lets the panel show ccusage's money against the deck's own
+ * project names. Without that join a session row is a uuid and a number.
+ */
+async function readSessions(sinceArg, until) {
+  try {
+    const args = ["session", "--json", "--since", sinceArg];
+    if (until) args.push("--until", until);
+    const ran = await runCcusage(args);
+    const raw = extractJson(ran.out);
+    // `session`, singular — ccusage names the array after the command, not
+    // after its contents, and `sessions` reads as the obvious guess and is
+    // always undefined.
+    return Array.isArray(raw.session) ? raw.session : [];
+  } catch (err) {
+    note("session read failed", err);
+    return [];
+  }
+}
+
 async function readRange(sinceArg, until, key) {
   const now = Date.now();
   let result;
@@ -944,8 +1008,40 @@ async function readRange(sinceArg, until, key) {
   try {
     const args = ["daily", "--json", "--since", sinceArg];
     if (until) args.push("--until", until);
-    ran = await runDaily(args);
-    const raw = extractJson(ran.out);
+    let raw;
+    if (_sectionsUnsupported) {
+      ran = await runDaily(args);
+      raw = extractJson(ran.out);
+    } else {
+      try {
+        ran = await runDaily([...args, ...SECTIONS]);
+        raw = extractJson(ran.out);
+      } catch (err) {
+        // A ccusage that could not run at all fails the same way with or
+        // without the flag, so only a complaint naming the flag is worth a
+        // second child — and `reason` set means the run never started, which is
+        // not something a flag can fix.
+        if (err?.reason !== undefined || !blamesSections(err?.message)) throw err;
+        _sectionsUnsupported = true;
+        ran = await runDaily(args);
+        raw = extractJson(ran.out);
+      }
+    }
+    // Already here on any ccusage that knows `--sections`: one load answered
+    // both questions. The second child is the fallback for the older ones, and
+    // it stays deliberately after the first rather than beside it — a failure
+    // to name the sessions must not cost the totals, which are what the panel
+    // is mostly for, and two ccusage processes at once on a cold machine is the
+    // shape #476 spent a release removing from the boot path.
+    // The second child belongs to the OLD ccusage and to nothing else. A build
+    // that took `--sections` answered with the section — empty for a range with
+    // no sessions in it — so a missing `session` key there means this deck
+    // asked for something that build does not report, and asking again as a
+    // separate command would get the same silence for the price of a second
+    // walk of every transcript on the machine.
+    const sessions = Array.isArray(raw.session)
+      ? raw.session
+      : (_sectionsUnsupported ? await readSessions(sinceArg, until) : []);
     // Passed through whole, `agents` array and all. Every day ccusage returns
     // under `--by-agent` is a superset of the day it returns without one, so
     // there is nothing here to reshape: the browser reads the merged totals it
@@ -957,6 +1053,7 @@ async function readRange(sinceArg, until, key) {
     result = {
       ok: true,
       days,
+      sessions,
       totals: raw.totals ?? null,
       since: sinceArg,
       until: until ?? null,

package/src/server/codex-quota.mjs

@@ -8,6 +8,8 @@
 // optional, unknown values pass through verbatim, and a `partial` flag tells
 // the UI when something was dropped instead of silently showing less.
 import { readFile } from "node:fs/promises";
+// One clamp for both quota readers: see the note on cooldownFromHeader.
+import { cooldownFromHeader } from "./quota.mjs";
 import { join } from "node:path";
 import { CODEX_HOME } from "./codex-dir.mjs";
 import { getCodexAuth, forceCodexRefresh, isCredentialHost } from "./codex-auth.mjs";
@@ -335,8 +337,10 @@ async function doFetchCodexQuota() {
   // than the ordinary floor before asking again. `retry-after` is honoured when
   // the backend sends one, because it knows better than the constant does.
   const cooldown = (res) => {
-    const after = parseInt(res?.headers?.get?.("retry-after") ?? "", 10);
-    _rateLimitedUntil = Date.now() + (Number.isFinite(after) ? after * 1000 : COOLDOWN_MS);
+    // Clamped, for the reason quota.mjs states at cooldownFromHeader: a `0`
+    // defeats the cooldown a 429 exists to impose, and a day freezes this
+    // poller for the life of the process.
+    _rateLimitedUntil = Date.now() + cooldownFromHeader(res?.headers?.get?.("retry-after"), COOLDOWN_MS);
   };
 
   let auth, base, res;