ccdeck 3.29.10 → 3.30.0

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) };
+}

package/src/server/quota-oauth.mjs

@@ -0,0 +1,190 @@
+// Claude Code's OAuth token, as quota.mjs borrows it: where it is kept, whether
+// this machine has one at all, how a request made with it introduces itself,
+// and the two limits every such request is under — the floor between two the
+// deck pays for, and the 429 cooldown they all share.
+//
+// Source 2 of the chain lives here too — one GET of the usage endpoint, mapped
+// by quota-shape.mjs — because it is nothing more than a request with this
+// token. Whether to make it is quota.mjs's decision, taken against the
+// self-poll floor; this module knows only how, and when a 429 says to stop.
+import { claudeConfigDir } from "./claude-dir.mjs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { mapOAuthUsage } from "./quota-shape.mjs";
+
+export const USAGE_URL   = "https://api.anthropic.com/api/oauth/usage";
+const BETA_HEADER = "oauth-2025-04-20";
+
+// Source 2's request, asking for the reset inventory as well as the windows.
+const USAGE_WITH_RESETS_URL = `${USAGE_URL}?cedar_ember=1`;
+
+/**
+ * How these requests introduce themselves, in the format Claude Code uses for
+ * its own.
+ *
+ * The endpoint decides whether to send the reset inventory by client surface:
+ * a User-Agent it does not recognise as Claude Code's CLI gets `eligible:
+ * false, ineligible_reason: "surface"` and no grants, and a CLI version it
+ * considers too old gets `"cli_version"`. This deck used to send
+ * `claude-code/2.1.0`: written to look like Claude Code, in a format the
+ * endpoint does not take for it. The windows do not depend on any of this —
+ * claude-swap reads the same ones as `claude-swap/1.0`.
+ *
+ * Pinned rather than read off the installed binary: the version lives in a
+ * different place under every install method, and a pin that ages out fails
+ * closed — the endpoint stops sending grants, the row disappears, and no number
+ * on the panel is wrong. Raising it is the fix when that happens.
+ */
+const USER_AGENT  = "claude-cli/2.1.283 (external, cli)";
+
+// Floor between two polls WE pay for. Twelve an hour against a budget of
+// ~28-30 leaves claude-swap room to collect for every account, which is what
+// the accounts panel is made of. Only reached when the store cannot answer.
+export const SELF_POLL_MS = 5 * 60_000;
+
+// 429 cooldown gate — after a rate-limit, skip the API until this passes.
+let _rateLimitedUntil = 0;
+
+/** When the cooldown ends, or 0 when there is none. For the budget rules,
+ *  which take it as an argument so they stay pure. */
+export function cooldownUntil() { return _rateLimitedUntil; }
+
+/** Whether a 429 is still being waited out at `now`. */
+export function coolingDown(now) { return now < _rateLimitedUntil; }
+
+/** A 429 arrived: hold every request this token makes off for as long as its
+ *  `retry-after` says, within the limits cooldownFromHeader keeps. One token,
+ *  one budget, so both requests that can be refused back off the same way. */
+export function startCooldown(res) {
+  _rateLimitedUntil = Date.now() + cooldownFromHeader(res.headers.get("retry-after"), 5 * 60_000);
+}
+
+/** The cooldown, forgotten — for resetQuotaPollFloor. */
+export function clearCooldown() { _rateLimitedUntil = 0; }
+
+/**
+ * Where Claude Code keeps the OAuth credentials this module borrows a token
+ * from.
+ *
+ * It is `.credentials.json` inside the Claude config dir, and that dir moves:
+ * CLAUDE_CONFIG_DIR replaces ~/.claude wholesale rather than overlaying it, so
+ * on a machine where it is set there is no ~/.claude to read at all. Hardcoding
+ * ~/.claude here did not fail loudly — it made readOAuthToken() return null
+ * forever, which reads exactly like "this machine keeps its credentials in the
+ * Keychain", and the quota chain quietly fell through to source 3 on every poll
+ * it was allowed to make. See src/server/claude-dir.mjs, which owns the rule
+ * and is the only place it is spelled.
+ *
+ * Resolved per call rather than frozen into a module-level constant, for the
+ * same reason claudeConfigDir() is a function: a constant captured at import
+ * time is a value nothing can observe or correct afterwards, and this module is
+ * imported lazily by the /api/quota route rather than at a point in startup
+ * anyone here controls.
+ *
+ * Exported for tests — it is the whole of the bug, and it is pure.
+ */
+export function credentialsPath() {
+  return join(claudeConfigDir(), ".credentials.json");
+}
+
+export async function readOAuthToken() {
+  try {
+    const raw  = await readFile(credentialsPath(), "utf8");
+    const auth = JSON.parse(raw)?.claudeAiOauth;
+    if (!auth?.accessToken) return null;
+    // expiresAt is epoch milliseconds. If expired, the CLI fallback handles it.
+    if (auth.expiresAt && Date.now() >= auth.expiresAt) return null;
+    return auth.accessToken;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A cooldown from a `retry-after`, kept inside limits the deck can live with.
+ *
+ * Unclamped, the header decided the poller's fate in both directions: `0` (or a
+ * value the server rounds down to it) defeats the cooldown entirely and the
+ * next tick asks again immediately, which is the loop a 429 exists to stop; a
+ * large one — a day is a legal value — freezes the reader for the life of the
+ * process, and nothing here re-reads it. Both are the remote side deciding how
+ * this deck behaves, which a header is not entitled to do.
+ *
+ * The floor is the deck's own minimum backoff and the ceiling is an hour: long
+ * enough to be a real retreat, short enough that a quota panel is not dead for
+ * the rest of the day because one reply said so.
+ */
+export function cooldownFromHeader(raw, fallbackMs, minMs = 30_000, maxMs = 3600_000) {
+  const seconds = parseInt(String(raw ?? ""), 10);
+  if (!Number.isFinite(seconds)) return fallbackMs;
+  return Math.min(Math.max(seconds * 1000, minMs), maxMs);
+}
+
+/**
+ * WHETHER THIS MACHINE HAS A SUBSCRIPTION TO REPORT ON AT ALL.
+ *
+ * Every source here needs a Claude.ai OAuth credential: the claude-swap store
+ * holds one, `claudeAiOauth` in the credentials file is one, and
+ * `claude --print /usage` prints windows only for a session signed in with one.
+ * An API-key, Bedrock or Vertex install has none — and there is no quota to
+ * read, because those are billed per token rather than in five-hour windows.
+ *
+ * That mattered because of what the CLI does on such a machine: it RUNS, prints
+ * no quota lines, and the no-numbers branch of quota.mjs's _doFetch used to
+ * read that as "genuine <1%" and publish `ok: true` with two zeroes. The panel
+ * then drew empty bars, which is a measurement nobody took. Codex already
+ * answers this properly, with `api_key_mode` as its own reason and its own
+ * sentence.
+ *
+ * Cheap and synchronous: environment first, because a machine configured for
+ * Bedrock or Vertex says so there, then the presence of the OAuth block in the
+ * credentials file. `readOAuthToken` above answers a different question — it
+ * also rejects an EXPIRED token, and an expired subscription is still a
+ * subscription.
+ */
+export async function hasSubscriptionCredential(env = process.env) {
+  if (env.CLAUDE_CODE_USE_BEDROCK === "1" || env.CLAUDE_CODE_USE_VERTEX === "1") return false;
+  try {
+    const raw = await readFile(credentialsPath(), "utf8");
+    if (JSON.parse(raw)?.claudeAiOauth?.accessToken) return true;
+  } catch { /* absent or unreadable, decided below */ }
+  // A key in the environment and no OAuth block beside it is the API-key
+  // install. Without either, this deck simply has not been signed in yet, and
+  // "sign in" is the right thing to say — which is the `waiting` branch, not
+  // this one.
+  return !(env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN);
+}
+
+/** The headers every request made with the Claude Code token sends. */
+export function oauthHeaders(token) {
+  return {
+    "Authorization":  `Bearer ${token}`,
+    "anthropic-beta": BETA_HEADER,
+    "Accept":         "application/json",
+    "Content-Type":   "application/json",
+    "User-Agent":     USER_AGENT,
+  };
+}
+
+export async function fetchOAuthUsage() {
+  if (coolingDown(Date.now())) return null;
+  const token = await readOAuthToken();
+  if (!token) return null;
+
+  try {
+    const res = await fetch(USAGE_WITH_RESETS_URL, {
+      headers: oauthHeaders(token),
+      signal: AbortSignal.timeout(15_000),
+    });
+
+    if (res.status === 429) {
+      startCooldown(res);
+      return null;
+    }
+    if (!res.ok) return null;
+
+    return mapOAuthUsage(await res.json());
+  } catch {
+    return null;
+  }
+}