agent-dag 3.0.0 → 3.1.0

package/src/server/macmon.mjs

@@ -0,0 +1,299 @@
+// The one thermal reading a Mac will not give up on its own.
+//
+// #747. On Apple Silicon there is no command shipped with macOS that prints a
+// CPU or GPU temperature. `powermetrics` needs root. `pmset -g therm` records
+// nothing on M-series and answers "No CPU power status has been recorded", so
+// there is no throttle row either. The AGX driver does not publish the
+// `"Temperature(C)"` that ioreg reads on Intel GPUs. And the SMC keys changed
+// with M1 and are inconsistent between models sharing one chip — an M1 Mac mini
+// uses different FourCCs from an M1 MacBook Pro, with no public mapping — so
+// there is nothing to hard-code either.
+//
+// The sensors are reachable, and without root: they come through a HID sensor
+// hub, which is a private C API. Every tool that shows a temperature on Apple
+// Silicon calls it, and every one of them is native code. A Node process cannot,
+// and this package has zero runtime dependencies, which is worth more than a
+// number.
+//
+// So it asks a tool the user already has, exactly the way the deck already asks
+// `cswap` about accounts and `ccusage` about spend. `macmon` is in
+// homebrew-core — `brew install macmon`, no third-party tap — runs without
+// sudo, supports M1 through M5, and prints JSON.
+//
+// COSTS INTEL NOTHING. This is reached only when ioreg has already answered
+// with nothing, which on an Intel Mac it never does. Deliberately not gated on
+// `process.arch`: a Node built for x64 running under Rosetta on an Apple
+// Silicon Mac reports "x64", and gating on that would skip the one machine this
+// exists for.
+import { run } from "./exec.mjs";
+import { renameWithRetry } from "./installer.mjs";
+import { existsSync } from "node:fs";
+import { chmod, copyFile, mkdir, mkdtemp, open, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const TOOL_DIR   = join(homedir(), ".agents-deck", "tools");
+const MACMON_DIR = join(TOOL_DIR, "macmon");
+
+/** Where the deck puts its own copy, and where brew puts one on both prefixes —
+ *  because ~/.local/bin's lesson applies here too: a tool the user installed is
+ *  not always on the PATH of the shell that launched the deck. Ours first, so a
+ *  machine that has both uses the one whose version this code was written
+ *  against. Apple Silicon's brew prefix before Intel's; that is the only
+ *  machine that reaches this file. */
+export const MACMON_CANDIDATES = [
+  join(MACMON_DIR, "macmon"),
+  "/opt/homebrew/bin/macmon",
+  "/usr/local/bin/macmon",
+];
+
+/** One sample, then exit. `-i` is the sampling window and its default is a full
+ *  second; 200ms is long enough for an average the tool is willing to publish
+ *  and short enough that a poll every ten seconds costs nothing anybody can
+ *  feel. */
+export const MACMON_ARGS = ["pipe", "-s", "1", "-i", "200"];
+
+/**
+ * The resolution, remembered — including the failure.
+ *
+ * `null` means "not looked yet" and `false` means "looked, not there", which is
+ * the distinction that keeps a machine without macmon from paying a lookup
+ * every ten seconds forever. cswapBin memoizes only success and re-probes on
+ * failure; that is right for a tool the deck installs and wrong for one it
+ * never will.
+ */
+let _bin = null;
+
+/** Forget it. For the test, and for the day something installs macmon while the
+ *  deck is up — nothing calls this on that path yet, and it is one line. */
+export function resetMacmonBin() { _bin = null; }
+
+export async function macmonBin({
+  exists = existsSync, probe = defaultProbe, candidates = MACMON_CANDIDATES,
+} = {}) {
+  if (_bin !== null) return _bin || null;
+  // The bare name first, because PATH is the cheap answer and the one a user
+  // who installed it themselves will usually have.
+  if (await probe("macmon")) return (_bin = "macmon");
+  for (const c of candidates) {
+    if (exists(c) && await probe(c)) return (_bin = c);
+  }
+  _bin = false;
+  return null;
+}
+
+async function defaultProbe(bin) {
+  return (await run(bin, ["--version"], { timeout: 4_000 })).ok;
+}
+
+/**
+ * CPU and GPU degrees out of one `macmon pipe` sample.
+ *
+ * The shape is `{ temp: { cpu_temp_avg, gpu_temp_avg } }`, both in Celsius —
+ * read off macmon's own `TempMetrics` struct rather than guessed from an
+ * example, because a field renamed upstream should read as "no sensor" and not
+ * as zero.
+ *
+ * A zero is dropped rather than shown. macmon defaults both fields to 0.0 and
+ * fills what it read, so a machine that answered for the CPU and not the GPU
+ * arrives as `{ cpu_temp_avg: 47.3, gpu_temp_avg: 0 }` — and 0 °C is not a
+ * reading, it is the absence of one wearing a number.
+ */
+export function tempsFromMacmonJson(json) {
+  let d;
+  try { d = typeof json === "string" ? JSON.parse(json) : json; }
+  catch { return {}; }
+  const t = d?.temp;
+  if (!t || typeof t !== "object") return {};
+  const out = {};
+  for (const [key, field] of [["cpu", "cpu_temp_avg"], ["gpu", "gpu_temp_avg"]]) {
+    const v = Number(t[field]);
+    // The same plausibility floor the rest of the thermal code uses, stated
+    // here rather than imported so this module has no opinion to disagree with.
+    if (Number.isFinite(v) && v > 0 && v < 150) out[key] = Math.round(v);
+  }
+  return out;
+}
+
+/**
+ * Ask macmon, or answer nothing.
+ *
+ * Never throws and never waits long: `run` does not reject, the sample is
+ * capped, and a machine without macmon returns before it spawns anything at
+ * all after the first lookup.
+ */
+export async function readMacmonTemps(deps = {}) {
+  const bin = await macmonBin(deps);
+  if (!bin) return {};
+  const r = await run(bin, MACMON_ARGS, { timeout: 6_000 });
+  if (!r.ok) return {};
+  // `pipe` prints one JSON object per sample and `-s 1` asks for one, but a
+  // build that ever printed a banner first would put it on the same stream.
+  const line = r.stdout.split("\n").find(l => l.trim().startsWith("{"));
+  return line ? tempsFromMacmonJson(line) : {};
+}
+
+// ── fetching it, so the user does not have to ────────────────────────────────
+//
+// `npx ccdeck` should work, and on Apple Silicon "work" includes the two rows
+// this file exists for. Telling somebody to run a brew command first is a step,
+// and a step is a thing most people will not take.
+//
+// So the deck fetches macmon the same way it already fetches uv — see
+// uv-bootstrap.mjs, whose shape this follows including the parts that were
+// learned the hard way. NOT through Homebrew: a machine without brew would then
+// need brew installed first, which is a very large thing to do to somebody who
+// asked for a dashboard.
+//
+// WHAT MAKES THIS SAFE TO RUN ON SOMEBODY'S MACHINE, each verified against the
+// real release rather than assumed:
+//
+//   * There is a prebuilt binary. `macmon-v0.8.2.tar.gz`, 746 KB, containing a
+//     `Mach-O 64-bit executable arm64`. No compiler, no toolchain, no Rust.
+//   * There is a checksum. The release publishes no `.sha256` file, but the
+//     GitHub releases API carries a `digest` field per asset, and it matched
+//     the bytes actually downloaded. An unverified binary is not something to
+//     run on someone's machine, which is uv-bootstrap's rule and is kept here.
+//   * It will execute. Apple Silicon refuses an unsigned binary; this one is
+//     `adhoc, linker-signed`, which is what the Rust toolchain emits and what
+//     macOS accepts. And a programmatic download carries no
+//     com.apple.quarantine — only com.apple.provenance, which blocks nothing —
+//     so there is no Gatekeeper prompt and nothing for the user to click.
+//
+// NEVER ON THE BOOT'S CRITICAL PATH. It is started by the thermal sampler, on
+// the tick where it found no reading, and nothing waits for it. The boot was
+// just taught not to wait for an install (#742) and this does not undo that.
+
+const RELEASE_API = "https://api.github.com/repos/vladkens/macmon/releases/latest";
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+
+/** One attempt per process. A machine that is offline, or behind a proxy that
+ *  refuses GitHub, must not re-download every ten seconds for as long as the
+ *  deck runs — and a success does not need a second attempt either. */
+let _fetched = false;
+
+/** Cleared with the resolution, so a test can run the whole thing twice. */
+export function resetMacmonFetch() { _fetched = false; }
+
+/**
+ * The asset to download, out of what the release actually published.
+ *
+ * Pure and exported: this is the part that has to keep working when the project
+ * changes its file names, and the only way to check that from here is to feed
+ * it a release document. `digest` is `sha256:<hex>` — the prefix is part of the
+ * field and dropping it silently would make every download fail verification.
+ */
+export function macmonAsset(release) {
+  const tag = release?.tag_name;
+  const a = (release?.assets ?? []).find(x => typeof x?.name === "string" && x.name.endsWith(".tar.gz"));
+  if (!a?.browser_download_url) return null;
+  const m = /^sha256:([0-9a-f]{64})$/.exec(String(a.digest ?? ""));
+  if (!m) return null;
+  return { version: typeof tag === "string" ? tag : "unknown", url: a.browser_download_url, sha256: m[1] };
+}
+
+/** A macmon this function installed earlier, or null. */
+export function existingBootstrappedMacmon() {
+  const bin = join(MACMON_DIR, "macmon");
+  return existsSync(bin) ? bin : null;
+}
+
+/**
+ * Download macmon into ~/.agents-deck/tools/macmon.
+ *
+ * Returns `{ ok: true, bin, version }` or `{ ok: false, reason }`, and never
+ * throws: every caller treats a missing macmon as an ordinary state.
+ *
+ * Apple Silicon only, because that is the only build published and the only
+ * machine that has anything to gain — an Intel Mac already answers through
+ * ioreg and never reaches this file at all.
+ */
+export async function bootstrapMacmon({
+  platform = process.platform, env = process.env, fetchFn = fetch, dir = MACMON_DIR,
+} = {}) {
+  if (platform !== "darwin") return { ok: false, reason: "unsupported_platform" };
+  // Both switches, for the reason uv-bootstrap has both: downloading an
+  // executable is a bigger step than installing a package with a tool the user
+  // already chose, so somebody may want the managed installs and not this.
+  if (env.AGENTS_DECK_NO_INSTALL === "1") return { ok: false, reason: "installs_disabled" };
+  if (env.AGENTS_DECK_NO_DOWNLOAD === "1") return { ok: false, reason: "download_disabled" };
+  if (_fetched) return { ok: false, reason: "already_tried" };
+  _fetched = true;
+
+  let staging = null;
+  let partial = null;
+  try {
+    const res = await fetchFn(RELEASE_API, {
+      headers: { accept: "application/vnd.github+json", "user-agent": "agents-deck" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return { ok: false, reason: "release_lookup_failed" };
+    const asset = macmonAsset(await res.json());
+    // No published digest means no way to know what was downloaded. There is no
+    // fallback version here on purpose: uv can have one because any recent uv
+    // installs claude-swap, while a hard-coded macmon URL would be a checksum
+    // this file invented for bytes it has never seen.
+    if (!asset) return { ok: false, reason: "no_verifiable_asset" };
+
+    const dl = await fetchFn(asset.url, {
+      redirect: "follow",
+      headers: { "user-agent": "agents-deck" },
+      signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+    });
+    if (!dl.ok) return { ok: false, reason: "download_failed" };
+    const archive = Buffer.from(await dl.arrayBuffer());
+    if (createHash("sha256").update(archive).digest("hex") !== asset.sha256) {
+      return { ok: false, reason: "checksum_mismatch" };
+    }
+
+    // mkdtemp under a directory the user already owns, for every reason
+    // uv-bootstrap gives: the name cannot be guessed, and mkdtemp CREATES
+    // rather than accepting a directory somebody else made.
+    // Staged beside the destination rather than in the system temp directory,
+    // so the rename below is same-filesystem and therefore atomic.
+    await mkdir(dir, { recursive: true });
+    staging = await mkdtemp(join(dir, "macmon-staging-"));
+    const archivePath = join(staging, "macmon.tar.gz");
+    await writeFile(archivePath, archive);
+    if (!(await run("tar", ["-xzf", archivePath, "-C", staging], { timeout: 60_000 })).ok) {
+      return { ok: false, reason: "extract_failed" };
+    }
+
+    // The archive is flat — readme.md, LICENSE, macmon — so this is a name
+    // rather than a search. It is checked instead of assumed because a layout
+    // change upstream should read as "not in the archive", not as a crash.
+    const found = join(staging, "macmon");
+    if (!existsSync(found)) return { ok: false, reason: "not_in_archive" };
+
+    // Copied to a name of its own inside the destination — same filesystem, so
+    // the rename below is the atomic kind — and only becomes `macmon` once it
+    // is whole, flushed, executable, and has answered `--version`. Interrupt
+    // this and all that is left is an inert temp file.
+    partial = join(dir, `.macmon-${process.pid}-${Date.now().toString(36)}`);
+    await copyFile(found, partial);
+    const handle = await open(partial, "r+");
+    try { await handle.sync(); } finally { await handle.close(); }
+    await chmod(partial, 0o755);
+
+    // The binary is adhoc/linker-signed and carries no quarantine, so this
+    // should simply run — and if some future build does not, the deck finds out
+    // here rather than by leaving a file every later boot trusts.
+    if (!(await run(partial, ["--version"], { timeout: 20_000 })).ok) {
+      return { ok: false, reason: "does_not_run" };
+    }
+
+    const dest = join(dir, "macmon");
+    await renameWithRetry(partial, dest);
+    partial = null;
+    // The resolution memo remembers a failure, and the failure it remembers is
+    // "there is no macmon". There is one now.
+    resetMacmonBin();
+    return { ok: true, bin: dest, version: asset.version };
+  } catch (err) {
+    return { ok: false, reason: "error", detail: String(err?.message ?? err).slice(0, 200) };
+  } finally {
+    if (staging) await rm(staging, { recursive: true, force: true, maxRetries: 10, retryDelay: 25 }).catch(() => {});
+    if (partial) await rm(partial, { force: true }).catch(() => {});
+  }
+}

package/src/server/open-url.mjs

@@ -0,0 +1,226 @@
+// Opening the browser, without the ten packages it used to cost.
+//
+// `open@10` was this package's ONLY runtime dependency, and it brought nine
+// more with it — bundle-name, default-browser, default-browser-id,
+// define-lazy-prop, is-docker, is-inside-container, is-wsl, run-applescript,
+// wsl-utils. Ten tarballs to fetch, extract and link on a machine whose npm
+// cache is empty, for one call, made once, whose whole job is to hand a
+// localhost URL to whatever the desktop already uses. On a fast link that is a
+// second; on the links the people who reported a hung `npx ccdeck` are on, it
+// is ten more round trips before the deck's own tarball is even unpacked.
+//
+// What it did that is worth keeping is the platform knowledge, and that is
+// small enough to hold here: three commands, plus the WSL case where
+// `process.platform` says linux and the browser is on the Windows side.
+//
+// DELIBERATELY FIRE AND FORGET. `open` returned a promise the boot awaited;
+// nothing downstream of that await needed the child, and a launcher that takes
+// its time — xdg-open on a machine with no desktop session hunting through
+// every handler it knows — held the boot behind it. Here the candidates are
+// tried in order, the failures move to the next one on their own, and the boot
+// never waits for any of it.
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+/** How long a launcher gets to prove it worked before the next one is tried.
+ *  A launcher that is still running is a launcher that found something: macOS
+ *  `open` and cmd's `start` both exit at once, and xdg-open stays up as the
+ *  browser's parent. So only an EARLY non-zero exit moves on. */
+export const LAUNCH_GRACE_MS = 1_500;
+
+/**
+ * Is this a Linux that is really Windows?
+ *
+ * WSL reports `process.platform === "linux"`, has no desktop session of its
+ * own on a default install, and its browser lives on the Windows side — so
+ * xdg-open there either is not installed or opens nothing anybody can see.
+ * Both signals are read because either can be absent: the env var is set by
+ * the WSL launcher and lost by anything that scrubs the environment, and
+ * /proc/version is the kernel's own answer and cannot be.
+ */
+export function isWsl(platform = process.platform, env = process.env, readProcVersion = defaultProcVersion) {
+  if (platform !== "linux") return false;
+  if (env.WSL_DISTRO_NAME || env.WSL_INTEROP) return true;
+  return /microsoft/i.test(readProcVersion());
+}
+
+function defaultProcVersion() {
+  try {
+    return readFileSync("/proc/version", "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The launchers to try for `url`, best first.
+ *
+ * A list rather than one answer, because every platform below has a case where
+ * the first choice is missing: a Linux without xdg-utils, a WSL without
+ * wslview, a Windows whose comspec has been moved. Each entry is exactly what
+ * `spawn` is given, so the test can read the command line rather than infer it.
+ *
+ * Exported with platform and env as parameters for the reason exec.mjs exports
+ * its own that way: the Windows and Linux answers have to be checkable from the
+ * Mac this is written on.
+ */
+export function launchers(url, { platform = process.platform, env = process.env, wsl } = {}) {
+  const inWsl = wsl === undefined ? isWsl(platform, env) : wsl;
+
+  if (platform === "darwin") {
+    // The absolute path first: `open` is also a shell builtin in a few setups
+    // and a user's own script called `open` on the PATH is not unheard of, and
+    // /usr/bin/open has been on every macOS this package supports.
+    return [
+      { file: "/usr/bin/open", args: [url] },
+      { file: "open", args: [url] },
+    ];
+  }
+
+  if (platform === "win32") {
+    // PowerShell FIRST, and this order is the one thing here that was decided by
+    // evidence rather than by taste.
+    //
+    // `open@10` — the dependency this file replaces — launches a Windows URL
+    // through `powershell -EncodedCommand` running `Start "<url>"`. That is what
+    // every ccdeck install on Windows has been using, so it is the path with a
+    // year of field evidence behind it and `cmd /c start` has none.
+    //
+    // And the fallback below cannot rescue a wrong first choice. `start` exits 0
+    // whether or not anything opened — measured on a real Windows 10 box, exit
+    // code 0 with no browser process created — so a candidate list that led with
+    // it would never reach a second candidate, however badly the first had done.
+    // Leading with the one whose failure is visible is the only ordering where
+    // having a fallback means anything.
+    //
+    // The cost is PowerShell's startup, a few hundred milliseconds, and it is
+    // paid by nobody: openUrl does not wait for the launcher and the boot does
+    // not wait for openUrl.
+    const tries = [{
+      file: "powershell.exe",
+      // The URL as its own argv entry rather than inside a script string, where
+      // `;` and `&` are PowerShell's own operators.
+      args: ["-NoProfile", "-NonInteractive", "-Command", "Start-Process", url],
+    }];
+    const viaCmd = startCommand(url, env);
+    tries.push(viaCmd);
+    // comspec is read by startCommand, and a comspec pointing somewhere that is
+    // no longer there is the one way that line fails on a machine which is
+    // otherwise fine. The bare name is what the PATH would have answered.
+    if (viaCmd.file.toLowerCase() !== "cmd.exe") tries.push(startCommand(url, env, "cmd.exe"));
+    return tries;
+  }
+
+  if (inWsl) {
+    return [
+      // Ships with wslu and is what a WSL user's own `xdg-open` is usually
+      // symlinked to anyway. It knows how to hand a URL across the boundary.
+      { file: "wslview", args: [url] },
+      // No wslu: go to Windows directly. cmd.exe is reachable from WSL through
+      // the interop path and needs no PATH entry of its own.
+      startCommand(url, env, "/mnt/c/Windows/System32/cmd.exe"),
+      startCommand(url, env, "cmd.exe"),
+      // Last, and only useful on a WSL that really does run a desktop.
+      { file: "xdg-open", args: [url] },
+    ];
+  }
+
+  // Plain Linux, and every other Unix. xdg-open is the standard answer; the
+  // rest are the ones that exist on machines that never installed xdg-utils,
+  // in the order of how likely they are to be configured rather than merely
+  // present.
+  return [
+    { file: "xdg-open", args: [url] },
+    { file: "gio", args: ["open", url] },
+    { file: "x-www-browser", args: [url] },
+    { file: "sensible-browser", args: [url] },
+    { file: "wslview", args: [url] },
+  ];
+}
+
+/**
+ * `start` the way cmd.exe needs to be given it.
+ *
+ * Three details, each of which is a bug if it is missing. The empty `""` is the
+ * window TITLE — `start "http://…"` opens a console window titled with the URL
+ * and nothing else happens. The URL is quoted so an `&` in a query string ends
+ * the argument instead of the command. And `windowsVerbatimArguments` stops
+ * Node quoting the line a second time, which is exactly what exec.mjs's
+ * `viaCmd` does for the same reason.
+ */
+export function startCommand(url, env = process.env, comspec) {
+  const shell = comspec || env.comspec || env.ComSpec || "cmd.exe";
+  return {
+    file: shell,
+    args: ["/d", "/s", "/c", `start "" "${url}"`],
+    opts: { windowsVerbatimArguments: true },
+  };
+}
+
+/**
+ * Refuse anything that is not an http(s) URL.
+ *
+ * The one caller passes a localhost address it built itself, so this is not
+ * guarding against a hostile input today — it is guarding against the day a
+ * second caller passes a path, because every launcher above would happily open
+ * it and `start` would run it.
+ */
+export function isOpenable(url) {
+  try {
+    const u = new URL(String(url));
+    return u.protocol === "http:" || u.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Hand `url` to the desktop. Returns nothing, waits for nothing, throws never.
+ *
+ * The boot calls this between binding the port and starting the pulse line, and
+ * neither of those has anything to learn from how it went — a browser that does
+ * not open leaves a URL on screen that the user can click or paste, which is
+ * the same recovery an error row would have offered.
+ */
+export function openUrl(url, { platform = process.platform, env = process.env, spawnFn = spawn } = {}) {
+  if (!isOpenable(url)) return;
+  const tries = launchers(url, { platform, env });
+
+  const attempt = (i) => {
+    if (i >= tries.length) return;
+    const { file, args, opts } = tries[i];
+    let child;
+    try {
+      child = spawnFn(file, args, {
+        stdio: "ignore",
+        // The launcher outlives us on purpose: xdg-open is the browser's parent
+        // process on a cold start, and a deck stopped with Ctrl+C two seconds
+        // later should not take the window with it. Not on Windows, where a
+        // detached child is a child with its own console — the thing
+        // windowsHide exists to prevent.
+        detached: platform !== "win32",
+        windowsHide: true,
+        ...opts,
+      });
+    } catch {
+      attempt(i + 1);
+      return;
+    }
+    // ENOENT and EACCES both land here rather than throwing, because the failure
+    // happens after spawn returns.
+    child.on("error", () => attempt(i + 1));
+    // An early non-zero exit is xdg-open saying it found no handler (exit 3) or
+    // cmd saying it could not find `start`. A launcher still alive after the
+    // grace period is one that worked, so the timer is what closes the question.
+    let open = true;
+    const settled = setTimeout(() => { open = false; }, LAUNCH_GRACE_MS);
+    settled.unref?.();
+    child.on("exit", (code) => {
+      clearTimeout(settled);
+      if (open && code !== 0) attempt(i + 1);
+    });
+    child.unref?.();
+  };
+
+  attempt(0);
+}

package/src/server/quota.mjs

@@ -528,6 +528,37 @@ async function nudgeAndReread(previous) {
 //   cliOk  — the CLI ran and we recognized its output (preamble present)
 //   parsed — quota percentages object, or null if the "Current session/week"
 //            lines were absent (CLI cold-start, or genuinely <1% usage)
+/**
+ * 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 loop below 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; }
+
+/** The rate floor, cleared. `maySelfPoll` keeps a self-poll to one a minute
+ *  even under `force`, which is correct for a user's budget and is a test
+ *  asking the same question three times running into a wall. */
+export function resetQuotaPollFloor() {
+  _lastSelfPollAt = 0;
+  _rateLimitedUntil = 0;
+}
+
 async function _execOnce(bin) {
   const r = await run(bin, ["--print", "/usage"], {
     timeout: 15_000,
@@ -543,12 +574,22 @@ async function _execOnce(bin) {
   // 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}`;
-    console.error(`${PRODUCT} quota: claude CLI failed:`, msg);
+    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);
-  return { cliOk, parsed: parseUsageText(combined) };
+  return { cliOk, missing, parsed: parseUsageText(combined) };
 }
 
 async function _doFetch(now, force = false, gen = _generation) {
@@ -607,6 +648,11 @@ async function _doFetch(now, force = false, gen = _generation) {
     const r = await _execOnce(bin);
     cliOk = r.cliOk || cliOk;
     if (r.parsed) { parsed = r.parsed; break; }
+    // The retry exists for a CLI that RAN and left the quota lines out of a cold
+    // invocation. A CLI that is not installed will not be installed 1.2 seconds
+    // from now, and asking twice more spends two spawns and 2.4 seconds of the
+    // caller's wait to print the same sentence three times. See _execOnce.
+    if (r.missing) break;
   }
 
   // Got real quota lines — cache normally and remember as last-known-good.