ccdeck 3.29.11 → 3.31.0

package/src/server/provider-status.mjs

@@ -0,0 +1,307 @@
+// Whether Anthropic or OpenAI say something is wrong on their side (#1311).
+//
+// When Claude or Codex has an incident, everything this deck can see of it is
+// a local symptom — a quota read that fails, an agent that errors and retries,
+// a number that stops moving — and nothing here said the cause might be
+// upstream. So an outage looked like the user's machine, network, login or
+// this deck. Both providers publish their health on a page that serves the
+// Atlassian Statuspage API (OpenAI's page is incident.io, which answers the
+// same /api/v2/summary.json), and this module asks that page and boils the
+// answer down to one line per provider.
+//
+// SCOPED TO THE COMPONENTS A DECK USES. OpenAI's page covers ChatGPT, the ads
+// products, image generation and twenty more, and its page-wide indicator goes
+// amber for a ChatGPT outage no Codex session will ever feel. So the state is
+// the worst of the NAMED components — Claude Code and the Claude API on
+// Anthropic's page, the Codex ones on OpenAI's — and the page-wide indicator is
+// a fallback only, for the day a page renames every one of them.
+//
+// ON DEMAND, NOT ON A TIMER. Nothing in this file polls. A read goes out when
+// the page or the desktop tray asks and the last answer is older than
+// FRESH_MS, so a deck with nobody looking at it asks nobody anything, and the
+// page stops asking while its tab is hidden (use-provider-status.ts).
+//
+// A FAILED READ IS NOT AN INCIDENT. An unreachable status page says nothing
+// about the provider — far more often it is the user's own network — so a
+// failure keeps the last answer and marks it stale, and past EXPIRE_MS drops it
+// to "unknown", which draws nothing. It never becomes an outage, and nothing
+// here throws: this is context for a diagnosis, and no other part of the deck
+// waits on it.
+
+/** The two pages, what each page is linked as, and which of its components
+ *  are the ones this deck's sessions depend on. */
+export const PROVIDERS = {
+  claude: {
+    summaryUrl: "https://status.claude.com/api/v2/summary.json",
+    pageUrl: "https://status.claude.com",
+    // claude.ai, the Console and the government and Cowork products are left
+    // out: an incident that reaches Claude Code lists Claude Code, and one that
+    // only reaches the web app does not stop a session.
+    components: [/^Claude Code$/i, /^Claude API\b/i],
+    // Every product on this page is Claude, so its overall status is still
+    // about the sessions if the components above are ever renamed.
+    pageFallback: true,
+  },
+  codex: {
+    summaryUrl: "https://status.openai.com/api/v2/summary.json",
+    pageUrl: "https://status.openai.com",
+    // Codex Web and Codex API by name; the CLI and the editor extension are
+    // listed on that page without the word.
+    components: [/\bCodex\b/i, /^CLI$/i, /^VS Code extension$/i],
+    // Not this page's overall status: it is mostly ChatGPT, and a ChatGPT
+    // outage drawn as "Codex · partial outage" is the false alarm this module
+    // exists to avoid. Components renamed away is "unknown" here.
+    pageFallback: false,
+  },
+};
+
+/** How long an answer is the answer. Status pages are served from a CDN that
+ *  caches for about a minute, so asking more often buys nothing. A little
+ *  UNDER the page's three-minute poll, and that is deliberate: an answer is
+ *  stamped when it arrives, so the next poll lands a few seconds short of
+ *  three minutes after it, and a cache of exactly three minutes handed every
+ *  other poll the previous answer — an incident took six minutes to show. */
+export const FRESH_MS = 150_000;
+
+/** How long a failed read waits before the next one may go out, so a page
+ *  that asks on every poll cannot turn an offline machine into a retry loop. */
+export const RETRY_MS = 60_000;
+
+/** How old the last answer may be before it is no answer at all. Past this a
+ *  stale incident stops being drawn: it may well be over, and "Claude · major
+ *  outage" from an hour ago is not a fact about now. */
+export const EXPIRE_MS = 30 * 60_000;
+
+const FETCH_TIMEOUT_MS = 8_000;
+// A summary is 2-6 KB. Anything a thousand times that is not a status page.
+const MAX_BODY_BYTES = 1 << 20;
+// Page-supplied words go on screen; they are cut, never trusted to be short.
+const MAX_WORDS = 160;
+
+/** A component's status, in this deck's words. */
+const COMPONENT_STATES = {
+  operational: "operational",
+  degraded_performance: "degraded",
+  partial_outage: "partial_outage",
+  major_outage: "major_outage",
+  under_maintenance: "maintenance",
+};
+
+/** The page-wide indicator, in the same words — the fallback only. */
+const PAGE_INDICATORS = {
+  none: "operational",
+  minor: "degraded",
+  major: "partial_outage",
+  critical: "major_outage",
+  maintenance: "maintenance",
+};
+
+/** Worst last. Maintenance is below degraded: it was planned, and it said so. */
+const SEVERITY = ["operational", "maintenance", "degraded", "partial_outage", "major_outage"];
+
+/** The incident and maintenance statuses that are over. */
+const FINISHED = new Set(["resolved", "postmortem", "completed", "scheduled"]);
+
+const own = (map, key) => typeof key === "string" && Object.hasOwn(map, key);
+const words = (s) => (typeof s === "string" && s.trim() ? s.trim().replace(/\s+/g, " ").slice(0, MAX_WORDS) : null);
+
+/** Whether this deck asks the status pages at all. AGENTS_DECK_NO_INSTALL is
+ *  the switch the README says turns off everything but the quota reads, so it
+ *  turns this off too. */
+export function statusChecksOff(env = process.env) {
+  return env.AGENTS_DECK_NO_STATUS === "1" || env.AGENTS_DECK_NO_INSTALL === "1";
+}
+
+/**
+ * One provider's page, read. Null when the body is not a summary this module
+ * can read — which the caller files as a failed read, not as "operational".
+ *
+ * @returns {{ state: string, summary: string | null, components: string[], scope: "components" | "page", updatedAt: number | null } | null}
+ */
+export function readSummary(provider, body) {
+  const spec = PROVIDERS[provider];
+  if (!spec || !body || typeof body !== "object") return null;
+  const updatedAt = Date.parse(body.page?.updated_at) || null;
+  const listed = Array.isArray(body.components) ? body.components : [];
+  const ours = listed.filter(c =>
+    c && typeof c.name === "string" && c.group !== true && own(COMPONENT_STATES, c.status)
+    && spec.components.some(re => re.test(c.name.trim())));
+
+  if (ours.length > 0) {
+    let state = "operational";
+    for (const c of ours) {
+      const s = COMPONENT_STATES[c.status];
+      if (SEVERITY.indexOf(s) > SEVERITY.indexOf(state)) state = s;
+    }
+    const hit = ours.filter(c => c.status !== "operational");
+    // The title is looked for among the components at the WORST state only: a
+    // maintenance window on one component is not the name of an outage on
+    // another.
+    const worst = hit.filter(c => COMPONENT_STATES[c.status] === state);
+    return {
+      state,
+      summary: state === "operational" ? null : incidentName(body, new Set(worst.map(c => c.id))),
+      // Names, deduplicated — OpenAI's page lists two components as "Login",
+      // and a page may list one twice in a group and out of it.
+      components: [...new Set(hit.map(c => words(c.name)).filter(Boolean))],
+      scope: "components",
+      updatedAt,
+    };
+  }
+
+  const indicator = body.status?.indicator;
+  if (!own(PAGE_INDICATORS, indicator)) return null;
+  // A page that answered, whose overall status is not about this provider's
+  // sessions: a reading, and the honest one is that the deck cannot say.
+  if (!spec.pageFallback) {
+    return { state: "unknown", summary: null, components: [], scope: "page", updatedAt };
+  }
+  const state = PAGE_INDICATORS[indicator];
+  return {
+    state,
+    summary: state === "operational" ? null : words(body.status.description),
+    components: [],
+    scope: "page",
+    updatedAt,
+  };
+}
+
+/**
+ * The title of the unfinished incident — or maintenance — that names one of
+ * the affected components, when the page says which.
+ *
+ * Anthropic's page lists each incident's components; OpenAI's summary carries
+ * no incidents at all, so its answer is the component names on their own.
+ * An incident that names none of ours is not borrowed: a claude.ai outage's
+ * title over a Claude Code line would be a diagnosis of the wrong thing.
+ */
+function incidentName(body, affected) {
+  const open = [
+    ...(Array.isArray(body.incidents) ? body.incidents : []),
+    ...(Array.isArray(body.scheduled_maintenances) ? body.scheduled_maintenances : []),
+  ].filter(i => i && !FINISHED.has(i.status));
+  for (const i of open) {
+    const named = Array.isArray(i.components) ? i.components : [];
+    if (named.some(c => affected.has(c?.id))) return words(i.name);
+  }
+  return null;
+}
+
+/** GET a page's summary: a parsed body, or a thrown reason. */
+async function fetchSummary(fetchImpl, url) {
+  const res = await fetchImpl(url, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`http ${res.status}`);
+  if (Number(res.headers?.get?.("content-length")) > MAX_BODY_BYTES) throw new Error("body too large");
+  return JSON.parse(await cappedText(res, MAX_BODY_BYTES));
+}
+
+/**
+ * The body as text, refused past `max` BYTES while it is still arriving. A
+ * page that sends no Content-Length would otherwise be read whole before its
+ * size could be checked, and `text.length` counts UTF-16 units, not bytes.
+ */
+export async function cappedText(res, max) {
+  const reader = res.body?.getReader?.();
+  if (!reader) {
+    const text = await res.text();
+    if (Buffer.byteLength(text, "utf8") > max) throw new Error("body too large");
+    return text;
+  }
+  const chunks = [];
+  let bytes = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytes += value.byteLength;
+    if (bytes > max) {
+      reader.cancel().catch(() => {});
+      throw new Error("body too large");
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks.map(c => Buffer.from(c.buffer, c.byteOffset, c.byteLength))).toString("utf8");
+}
+
+/**
+ * The cache and the reads behind GET /api/provider-status. A factory so a test
+ * can hand in its own fetch and clock; the route uses the one instance below.
+ */
+export function createProviderStatus({ fetchImpl = (...a) => fetch(...a), now = () => Date.now() } = {}) {
+  /** provider → { reading, checkedAt, failedAt, inflight } */
+  const held = new Map();
+
+  function slot(provider) {
+    let h = held.get(provider);
+    if (!h) held.set(provider, h = { reading: null, checkedAt: 0, failedAt: 0, inflight: null });
+    return h;
+  }
+
+  async function refresh(provider, h) {
+    try {
+      const reading = readSummary(provider, await fetchSummary(fetchImpl, PROVIDERS[provider].summaryUrl));
+      if (!reading) throw new Error("not a status summary");
+      h.reading = reading;
+      h.checkedAt = now();
+      h.failedAt = 0;
+    } catch {
+      h.failedAt = now();
+    }
+  }
+
+  /** One provider's line, reading the page first when the answer is due. */
+  async function read(provider) {
+    const h = slot(provider);
+    const t = now();
+    const due = t - h.checkedAt >= FRESH_MS && t - h.failedAt >= RETRY_MS;
+    if (due) {
+      // Deduplicated: the page and the tray asking in the same second is one
+      // request, not two.
+      h.inflight ??= refresh(provider, h).finally(() => { h.inflight = null; });
+      await h.inflight;
+    }
+    return view(provider, h, now());
+  }
+
+  return { read };
+}
+
+/**
+ * What the route says about one provider.
+ *
+ * `checkedAt` is when the page last ANSWERED, never when it was last asked, so
+ * an answer cannot look fresher than it is; `stale` says the latest ask got no
+ * answer. Past EXPIRE_MS the reading is dropped rather than shown stale.
+ */
+export function view(provider, h, t) {
+  const base = { provider, statusPageUrl: PROVIDERS[provider].pageUrl };
+  const r = h?.reading;
+  if (!r || t - h.checkedAt > EXPIRE_MS) {
+    return { ...base, state: "unknown", summary: null, components: [], updatedAt: null, checkedAt: null, stale: false };
+  }
+  return {
+    ...base,
+    state: r.state,
+    summary: r.summary,
+    components: r.components,
+    scope: r.scope,
+    updatedAt: r.updatedAt,
+    checkedAt: h.checkedAt,
+    stale: h.failedAt > h.checkedAt,
+  };
+}
+
+const shared = createProviderStatus();
+
+/**
+ * The answer for GET /api/provider-status: one line for each CLI the deck
+ * watches, and none for the one it does not (#402) — a Codex-less deck has no
+ * reason to ask OpenAI anything.
+ */
+export async function providerStatusReport({ providers, env = process.env, instance = shared } = {}) {
+  if (statusChecksOff(env)) return { ok: true, disabled: true, providers: [] };
+  const asked = Object.keys(PROVIDERS).filter(p => providers?.[p] !== false);
+  return { ok: true, disabled: false, providers: await Promise.all(asked.map(p => instance.read(p))) };
+}

package/src/server/pulse-line.mjs

@@ -0,0 +1,132 @@
+// The pulse line — the one line that stays on screen for hours under the boot
+// report — and the "not registered" sentence printed above it when this deck's
+// discovery file could not be written.
+//
+// Lifted out of term.mjs, whose glyph tier it takes its dash and bullet from:
+// term.mjs keeps the rules about the terminal, and this is what the deck says
+// on it. bin/cli/pulse.js paints the line and bin/deck.js prints the sentence,
+// and both are decided here, where every input is a parameter and nothing
+// writes.
+import { glyphs } from "./term.mjs";
+
+/**
+ * The one line that stays on screen for hours, sized to the terminal it is on.
+ *
+ * It is redrawn over itself with `\r`, so both messages are padded to one width
+ * — the shorter has to cover the longer — and that width is clamped to the real
+ * terminal: at 40 columns the old 58-character message wrapped, after which the
+ * `\r` only ever reached the second row and every repaint left the first one
+ * behind. A deck no hook can find is not listening in any sense the user cares
+ * about, which is why that state has a message here at all.
+ *
+ * `claude` is what makes that last sentence conditional. A deck watching only
+ * Codex is not waiting on a hook: startCodexWatcher is started by startServer
+ * and never consults the discovery file, and writesCodexLog keeps a deck with no
+ * record on disk writing its log. Capture and persistence both work perfectly
+ * there, while this line used to repaint "hooks cannot find this deck" every
+ * 800ms, forever (#404) — a permanent alarm about a mechanism that deck does not
+ * use. The one-time report at boot still says what IS lost; see
+ * unregisteredDetail.
+ */
+export function pulseText({
+  registered = true, claude = true, columns = 80, unicode = true, indent = 2, busy = null,
+} = {}) {
+  const g = glyphs(unicode);
+  const room = Math.max(4, columns - indent - 3 - 1);
+  const pick = (options) => options.find((o) => o.length <= room) ?? options[options.length - 1].slice(0, room);
+
+  const rest = pick([`listening ${g.dash} Ctrl+C to stop`, "listening"]);
+  const bad = pick([
+    `listening, but not registered ${g.dash} hooks cannot find this deck`,
+    `not registered ${g.dash} hooks cannot find this deck`,
+    "not registered",
+  ]);
+  // Both branches are still measured, registered or not, because the line is
+  // redrawn over itself and the shorter message has to cover the longer one on
+  // the beat after a deck loses its registration.
+  //
+  // The width is deliberately computed from the two FIXED messages only. `busy`
+  // comes and goes on a single boot — an install starts, the line names it, the
+  // install ends and the line goes back to Ctrl+C — so a width that grew to fit
+  // the label would have to shrink again afterwards, and the shorter line would
+  // leave the tail of the longer one on screen. Instead the label is shown only
+  // where it already fits — 60 columns and wider, measured — and below that the
+  // line says the true thing it has always said.
+  const width = Math.min(room, Math.max(rest.length, bad.length));
+  // What is still happening, rather than what is always true. `Ctrl+C to stop`
+  // is the right thing to say to somebody with nothing left to wait for, and
+  // the wrong thing to say to somebody watching an install.
+  const label = typeof busy === "string" && busy.trim() ? busy.trim() : null;
+  const working = label ? `listening ${g.bullet} ${label}` : null;
+  const ok = working && working.length <= width ? working : rest;
+  return (registered || !claude ? ok : bad).padEnd(width);
+}
+
+/**
+ * Whether the line has anything left to say by moving.
+ *
+ * #742. The dot alternated green and grey every 800ms for as long as the deck
+ * ran, and a blinking indicator beside a status line is the vocabulary of
+ * "working on it" — so a boot that had finished in a second read as one that
+ * never finished, and people said so. The deck's own web UI already retired
+ * this once: the pill goes quiet at rest (#720). The terminal did not.
+ *
+ * Motion is now spent on the two states where something is genuinely
+ * outstanding — a deck no hook can find, and a background job still running —
+ * and nowhere else. At rest the dot is painted once, in the healthy colour, and
+ * left alone. Movement then means something changed, which is the only thing
+ * movement should ever mean on a line somebody leaves open for hours.
+ */
+export function pulseMoves({ registered = true, claude = true, busy = null } = {}) {
+  if (!registered && claude) return true;
+  return typeof busy === "string" && busy.trim() !== "";
+}
+
+/**
+ * Whether the dot is lit on this beat.
+ *
+ * `"on"` on every beat of a deck at rest, which is what makes the line still:
+ * bin/cli/pulse.js paints a beat only when the frame differs from the one
+ * already on screen, so a dot that is always lit is a line written once and
+ * then left alone. Alternating is reserved for the states pulseMoves admits.
+ *
+ * The beat is a parameter rather than counted here so this is a function of its
+ * inputs and nothing else — and so a test can ask what the twentieth beat of an
+ * idle deck looks like without waiting sixteen seconds for it.
+ */
+export function pulseDot(beat, { registered = true, claude = true, busy = null } = {}) {
+  if (!pulseMoves({ registered, claude, busy })) return "on";
+  return beat % 2 === 0 ? "on" : "off";
+}
+
+/**
+ * The second line of the "not registered" report, which bin/deck.js prints once
+ * per change of state rather than every beat.
+ *
+ * What a missing discovery file costs is not the same on the two capture paths,
+ * and the old sentence — "hooks find this deck through <file>, so until that
+ * file exists no events arrive" — stated the Claude Code answer as if it were
+ * both. On a Codex-only deck it is false twice over: no hook is looking for this
+ * deck, and events do keep arriving, because the rollout watcher reads the files
+ * directly. What that deck really loses is the writer election in
+ * log-election.mjs, which is how several decks tailing one rollout agree on
+ * which of them appends it to a shared events log. A deck with no record on
+ * disk is assumed to be writing, so nothing is dropped — the log can gain the
+ * same line twice instead.
+ *
+ * @param file the discovery file that could not be written.
+ * @param claude whether this deck is watching Claude Code at all.
+ * @param dash the em dash, or the ASCII stand-in on a console that cannot draw
+ *   one (#797). A parameter for the same reason `renameNotice` takes one:
+ *   term.mjs says, above its glyphs, "every glyph the deck prints — punctuation
+ *   included, since an em dash is as absent from CP437 as a check mark — comes
+ *   from one of them", and this sentence had it hardcoded. On a legacy cmd.exe
+ *   or the Linux virtual console the reader got a box in the middle of the one
+ *   line explaining why no events are arriving.
+ */
+export function unregisteredDetail({ file, claude = true, dash = "—" }) {
+  if (claude) {
+    return `Claude Code hooks find this deck through ${file}, so until that file exists no Claude Code events arrive.`;
+  }
+  return `Codex capture does not use ${file} ${dash} the deck tails the rollout files itself ${dash} so events still arrive. Only decks sharing one events log need it, to agree on which of them records.`;
+}

package/src/server/purge-key.mjs

@@ -32,6 +32,7 @@ import { readFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { deckDataDir, legacyDeckDir } from "./deck-home.mjs";
+import { stripBom } from "./atomic-write.mjs";
 
 /** The file. Named once, because it is spelled in deck-prefs.mjs too and the
  *  two must not drift — see `prefsPath`, which is the same join. */
@@ -88,13 +89,12 @@ export async function findKeyFiles(dirs = keyDirs(), deps = {}) {
       continue;
     }
     try {
-      // The BOM, stripped the way installer.mjs strips it off settings.json:
-      // `JSON.parse` throws on one and a file Notepad saved is not damaged.
-      // Spelled out rather than imported because installer.mjs's `stripBom` is
-      // private to that module today — #1056 exports it, and this call should
-      // become that import once it lands, so the rule has one spelling.
-      const text = String(raw);
-      const parsed = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+      // The BOM, stripped by the rule settings.json, prefs.json and the
+      // browser-watch state are all read with: `JSON.parse` throws on one and
+      // a file Notepad saved is not damaged. This was a copy of it, spelled out
+      // while stripBom was private; it is exported now (atomic-write.mjs), so
+      // the rule has one spelling.
+      const parsed = JSON.parse(stripBom(String(raw)));
       const secret = parsed?.lan?.secret;
       out.push({ path, holds: typeof secret === "string" && secret !== "" ? "key" : "no-key", why: "" });
     } catch (err) {

package/src/server/quota-cli.mjs

@@ -0,0 +1,174 @@
+// Source 3 of quota.mjs's chain: `claude --print /usage`, and the `claude` it
+// runs.
+//
+// The most expensive of the three sources — a whole Claude Code process per
+// attempt — and the only self-service one on a Mac, where the token is in the
+// Keychain and there is no credentials file to read. What lives here is the
+// part that is about the CLI itself: which binary to run, one run of it, and
+// the one line said when that run fails. How many attempts, how far apart, and
+// what to publish when none of them prints a window stay in quota.mjs, beside
+// the floors and the cache those answers are decided against.
+import { claudeCliCandidates } from "./claude-dir.mjs";
+import { pathLookup, run } from "./exec.mjs";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { PRODUCT } from "./brand.mjs";
+import { stripAnsi } from "./term.mjs";
+import { parseUsageText } from "./quota-shape.mjs";
+
+// Where the `claude` CLI can be. The list moved to claude-dir.mjs, which is the
+// module that owns every "where does Claude Code live" answer the deck has —
+// the config dir was already there, and the boot-time presence check that reads
+// this same list had no business importing a quota poller to get at it.
+
+/** Which `claude` to run for `--print /usage`: the first candidate that exists.
+ *
+ *  This used to hand back a whole shell command line — `"<bin>" --print /usage
+ *  < /dev/null` — for `exec()` to parse. Double quotes are not escaping on
+ *  POSIX: `$(…)`, backticks and `\` all still work inside them, and every
+ *  ingredient of that line came from the environment (`%APPDATA%`, `homedir()`),
+ *  so a home directory named `/home/a$(id)b` was shell code the quota poll ran
+ *  every minute. A bare `$` was the duller half of the same bug — it expanded
+ *  to nothing and the probe looked for a binary at a path that did not exist.
+ *
+ *  There is nothing left to escape once there is no shell: exec.mjs's `run`
+ *  spawns the argument vector as given, resolves the Windows `.cmd`/`.exe`
+ *  spelling itself, and closes the child's stdin — which is what `< /dev/null`
+ *  was for, since `claude --print` waits three seconds on a stdin pipe nobody
+ *  is writing to.
+ *
+ *  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" ? "\\" : "/";
+  // 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";
+}
+
+/**
+ * The failure this last said out loud, so a standing one is said once.
+ *
+ * #742. A Windows user with no Claude Code installed sent a screenshot of three
+ * identical lines — `ccdeck quota: claude CLI failed: claude exited ENOENT` —
+ * interleaved with the deck's pulse line, and they keep coming for as long as
+ * the deck runs. Every poll ran the retry loop in quota.mjs's _doFetch three
+ * times, and every attempt printed. A CLI that is not installed is not news
+ * three times a minute; it is a condition, and a condition is worth exactly
+ * one line.
+ *
+ * Cleared on the first run that works, so a `claude` installed while the deck
+ * is up can still report its next genuine failure.
+ */
+let _saidFailure = null;
+
+/** Exported for its test, and for the same reason resetCswapBin is: a module
+ *  that remembers something across calls needs a way to be asked twice.
+ *
+ *  Deliberately NOT folded into invalidateQuotaCache, which production calls
+ *  after an account switch — forgetting the notice there would put the same
+ *  sentence back on the terminal every time somebody changed accounts. */
+export function forgetQuotaFailureNotice() { _saidFailure = null; }
+
+// Run `claude --print /usage` once. Returns { cliOk, ran, missing, parsed }.
+//   cliOk   — we recognized its output (preamble present), whatever the exit
+//   ran     — the run itself succeeded, which cliOk does not say
+//   missing — there is no `claude` to run at all
+//   parsed  — quota percentages object, or null if the "Current session/week"
+//             lines were absent (CLI cold-start, or genuinely <1% usage)
+export async function runUsageOnce(bin) {
+  const r = await run(bin, ["--print", "/usage"], {
+    timeout: 15_000,
+    maxBuffer: 1024 * 1024,
+    // Marks this Claude Code run as the deck's own. `claude --print /usage`
+    // is a full invocation, so it fires the hooks we installed, and every
+    // quota poll was drawing itself onto the canvas as a fresh session with
+    // no prompt and no tools. Hooks inherit the environment, so hook.js
+    // sees this and stays quiet.
+    env: { ...process.env, NO_COLOR: "1", TERM: "dumb", AGENTS_DECK_INTERNAL: "1" },
+  });
+  // `run` never rejects, so there is one path rather than two — and the output
+  // is kept either way, which matters because the CLI writes the quota lines to
+  // stdout and can still exit non-zero afterwards.
+  const combined = r.stdout + "\n" + r.stderr;
+  // `run` normalises a binary that is not there to this, on every platform —
+  // see exec.mjs. It is the difference between "Claude Code answered badly",
+  // which is worth retrying and worth saying, and "there is no Claude Code on
+  // this machine", which is neither.
+  const missing = r.code === "ENOENT";
+  if (!r.ok) {
+    const msg = stripAnsi(r.stderr).trim() || `claude exited ${r.code}`;
+    if (msg !== _saidFailure) {
+      _saidFailure = msg;
+      console.error(`${PRODUCT} quota: claude CLI failed:`, msg);
+    }
+  } else {
+    _saidFailure = null;
+  }
+  const cliOk = /subscription/i.test(combined) || /claude code usage/i.test(combined);
+  // WHETHER THE RUN ITSELF SUCCEEDED, which `cliOk` does not answer. `cliOk` is
+  // a test of the OUTPUT — it means "we recognised what came back" — and a CLI
+  // that printed its banner and then failed satisfies it. That is the right
+  // rule for the parse above (see the note there: the quota lines can be on
+  // stdout and the exit non-zero), and the wrong one for the no-numbers
+  // fallback in _doFetch, which was publishing 0% for a run that errored.
+  return { cliOk, ran: r.ok, missing, parsed: parseUsageText(combined) };
+}