harnery 0.5.0 → 0.7.0

package/src/lib/devtools.ts

@@ -0,0 +1,1653 @@
+import { createHash } from "node:crypto";
+import {
+  closeSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * `devtools`: read locally-stored state of the AI coding agents harnery
+ * supports — Claude Code (`~/.claude`), Codex (`~/.codex`), and Cursor
+ * (`~/.cursor`) — into one uniform status shape: login state, plan/tier,
+ * auth expiry, session counts, and (where the tool stores them locally)
+ * rate-limit / quota windows.
+ *
+ * Everything here reads files on disk — no network, no vendor API, no
+ * credentials leave the machine (auth tokens are inspected for their
+ * non-secret claims only; the token strings themselves are never returned).
+ * The signals a tool keeps server-side (Cursor usage + billing, Claude's live
+ * rate-limit windows) surface as `null` with a note rather than a guess.
+ *
+ * Pure toolkit tier: depends only on `node:*`, never on `src/core/`.
+ */
+
+export type DevtoolName = "claude-code" | "codex" | "cursor";
+
+export interface QuotaWindow {
+  /** Human label for the reset window (e.g. "5h", "weekly", "45m"). */
+  window: string;
+  /** Percent of the window's allowance consumed, 0-100, or null if unknown. */
+  usedPercent: number | null;
+  /** ISO timestamp when the window resets, or null if unknown. */
+  resetsAt: string | null;
+}
+
+export interface ApiEnrichment {
+  /** The configured API key authenticated successfully. */
+  ok: boolean;
+  /** Human name the vendor reports for the key (e.g. Cursor's apiKeyName). */
+  keyName: string | null;
+  /** Cloud-agent activity (Cursor Cloud Agent API), when available. */
+  cloudAgents: { total: number; active: number } | null;
+  /** Error message when the key is configured but a call failed. */
+  error: string | null;
+}
+
+/**
+ * Cursor billing-cycle + usage snapshot, fetched from cursor.com's own dashboard
+ * API using the IDE's locally-stored session token — the same call Cursor's UI
+ * makes for the Spending page. No API key to mint; it reads what's already on
+ * disk. Percentages are 0-100; cent amounts are raw (divide by 100 for dollars).
+ */
+export interface CursorUsage {
+  /** ISO start of the current billing cycle. */
+  cycleStart: string | null;
+  /** ISO end of the current billing cycle (the "resets on …" date). */
+  cycleEnd: string | null;
+  /** Percent of included total usage consumed this cycle (Cursor's "Total"). */
+  totalPercentUsed: number | null;
+  /** Percent of included API usage consumed (named-model / "API"). */
+  apiPercentUsed: number | null;
+  /** Percent of included first-party ("Auto") model usage consumed. */
+  firstPartyPercentUsed: number | null;
+  /** Included usage allowance in cents (e.g. 7000 = $70). */
+  includedLimitCents: number | null;
+}
+
+/**
+ * Overage / on-demand dollar spend against a cap — Cursor's on-demand usage and
+ * Claude's extra-usage credits are the same idea. Cents are raw (÷100 for USD).
+ */
+export interface SpendStatus {
+  /** Human label for what this spend covers (e.g. "On-demand", "Extra usage"). */
+  label: string;
+  /** Amount spent this cycle in cents. */
+  usedCents: number | null;
+  /** Spend cap in cents, or null when unset/unlimited. */
+  limitCents: number | null;
+}
+
+export interface ToolStatus {
+  tool: DevtoolName;
+  /** The tool's config directory exists on this machine. */
+  installed: boolean;
+  /** A credential is present and not obviously expired. null when undeterminable. */
+  loggedIn: boolean | null;
+  /** Account identifier (email where the tool exposes one), else null. */
+  account: string | null;
+  /** Plan / seat tier as the tool records it locally (e.g. "team", "team_tier_1"). */
+  plan: string | null;
+  /** Rate-limit tier string where the tool records one, else null. */
+  rateLimitTier: string | null;
+  /** ISO expiry of the active access credential, else null. */
+  authExpiresAt: string | null;
+  /** Count of local session transcripts, else null. */
+  sessions: number | null;
+  /** ISO timestamp of the most recent local session activity, else null. */
+  lastActivity: string | null;
+  /** Locally-known quota/rate-limit windows, or null when the tool keeps them server-side. */
+  quota: QuotaWindow[] | null;
+  /**
+   * Total tokens observed in local transcripts within the scan window
+   * (`windowDays`). Codex always reports it — its per-session cumulative total
+   * is one tail-read per rollout, cheap enough for every render. Claude Code's
+   * is `--usage`-gated (a full transcript scan, potentially gigabytes) and null
+   * otherwise. Cursor keeps token counts server-side, so it stays null.
+   */
+  tokensUsed: number | null;
+  /**
+   * Result of the optional API enrichment (network), populated by
+   * `enrichFromApi` when a key is configured. `null` when no enrichment ran.
+   */
+  api: ApiEnrichment | null;
+  /**
+   * Cursor billing-cycle + usage, populated by `enrichFromApi` from the IDE's
+   * own session token (no API key needed). `null` when no enrichment ran, the
+   * token is stale, or the tool isn't Cursor.
+   */
+  usage: CursorUsage | null;
+  /**
+   * Overage / on-demand dollar spend, populated by `enrichFromApi` (Cursor's
+   * on-demand, Claude's extra-usage credits). `null` when no enrichment ran or
+   * the plan has no overage concept.
+   */
+  spend: SpendStatus | null;
+  /** Caveats about what is and isn't derivable locally for this tool. */
+  notes: string[];
+}
+
+export interface DevtoolsReport {
+  generatedAt: string;
+  windowDays: number | null;
+  tools: ToolStatus[];
+}
+
+/** One endpoint's health, from `probeEndpoints` (the `devtools doctor` check). */
+export interface ProbeResult {
+  tool: DevtoolName;
+  endpoint: string;
+  /** Client version we put in the request's User-Agent, else null. */
+  clientVersion: string | null;
+  /** HTTP status, or null when no call was made / the request threw. */
+  status: number | null;
+  outcome:
+    | "ok" // 200 with the expected shape
+    | "rate_limited" // 429 — back off, not a defect
+    | "auth_rejected" // 401/403 — our auth or required headers may have changed
+    | "shape_changed" // 200 but the expected fields are gone
+    | "unreachable" // network error / other non-2xx
+    | "no_credential"; // nothing to authenticate with locally
+  detail: string;
+}
+
+export interface ReadDevtoolsOpts {
+  /** Home directory to resolve tool config against. Defaults to os.homedir(). */
+  home?: string;
+  /** Scan transcripts for token totals (opt-in; can be slow). Default false. */
+  usage?: boolean;
+  /** When scanning usage, only include transcripts modified within N days. Default 7. */
+  windowDays?: number;
+  /** Clock injection for tests. Default Date.now(). */
+  now?: number;
+  /** Restrict to a subset of tools. Default all three. */
+  only?: readonly DevtoolName[];
+}
+
+const ALL_TOOLS: readonly DevtoolName[] = ["claude-code", "codex", "cursor"];
+
+// ---------------------------------------------------------------------------
+// Network enrichment (opt-in)
+//
+// `readDevtools` stays pure-local. `enrichFromApi` adds live signals over the
+// network, each authenticating with the credential the tool already stores on
+// disk — the user's own token reading the user's own data:
+//
+//   • Claude Code — reads the OAuth token from ~/.claude/.credentials.json and
+//     calls api.anthropic.com/api/oauth/usage (the endpoint `/usage` uses) for
+//     the 5h + weekly rate-limit windows and extra-usage spend.
+//   • Cursor usage + billing (NO key needed) — reads the IDE's session token
+//     from state.vscdb and calls cursor.com's dashboard API (the Spending page
+//     request) for the billing cycle + total/API/first-party percent-used.
+//   • Cursor Cloud Agents (needs an API key) — the public /v0 API. Individual
+//     Cursor plans expose no usage/billing there (Team-only), so the key path
+//     only adds Cloud Agent runs.
+// ---------------------------------------------------------------------------
+
+/** Path of the machine-local Cursor API key file (honors XDG_CONFIG_HOME). */
+export function cursorApiKeyPath(): string {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? homedir();
+  const configHome = process.env.XDG_CONFIG_HOME?.trim() || join(home, ".config");
+  return join(configHome, "harnery", "cursor-api-key");
+}
+
+/** Resolve a Cursor API key: env `CURSOR_API_KEY` first, then the key file. */
+export function resolveCursorApiKey(): string | null {
+  const fromEnv = process.env.CURSOR_API_KEY?.trim();
+  if (fromEnv) return fromEnv;
+  try {
+    const v = readFileSync(cursorApiKeyPath(), "utf8").trim();
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Statuses that mean a cloud agent is still doing work (everything else is done/gone). */
+const CURSOR_AGENT_INACTIVE = new Set(["EXPIRED", "FINISHED", "DELETED", "FAILED", "CANCELLED"]);
+
+// So our requests blend in with the tool's own traffic rather than looking like
+// a scraper (a bare fetch would carry a "Bun/…" or "node" User-Agent, which is
+// the anomaly). We send the same first-party client identity the tool sends for
+// the same call — the user's own machine reaching the user's own account. Claude
+// uses a claude-cli UA (built below); Cursor uses its Electron UA (see
+// cursorUserAgent), both embedding the live local version.
+
+/** Last-resort Claude Code version when no live source is readable. */
+const CLAUDE_CLI_FALLBACK_VERSION = "2.1.0";
+
+/**
+ * The Claude Code version actually running, most-authoritative source first:
+ *   1. the `version` field the running client stamps into its newest session
+ *      transcript (reflects auto-updates immediately),
+ *   2. the updater's last-result marker,
+ *   3. a constant.
+ * Claude Code auto-updates into a versioned install, so the transcript can be
+ * ahead of both the bootstrap `package.json` and the updater marker — which is
+ * why we read what the client itself reports, not what's on the install path.
+ */
+function claudeCodeVersion(home: string): string {
+  const fromTranscript = newestTranscriptVersion(home);
+  if (fromTranscript) return fromTranscript;
+  const marker = readJson<{ version_to?: string }>(
+    join(home, ".claude", ".last-update-result.json"),
+  );
+  return strOr(marker?.version_to) ?? CLAUDE_CLI_FALLBACK_VERSION;
+}
+
+/** Pull the `version` field from the head of the newest session transcript. */
+function newestTranscriptVersion(home: string): string | null {
+  const newest = newestFile(listFilesRecursive(join(home, ".claude", "projects"), ".jsonl"));
+  if (!newest) return null;
+  // The version rides every event, so the head of the file is plenty — avoids
+  // reading a multi-MB transcript in full just to read one field.
+  for (const line of readHead(newest, 65_536).split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const v = strOr((JSON.parse(line) as { version?: unknown }).version);
+      if (v) return v;
+    } catch {
+      // partial line at the buffer edge — skip
+    }
+  }
+  return null;
+}
+
+/** Read up to `maxBytes` from the start of a file as UTF-8, "" on any error. */
+function readHead(path: string, maxBytes: number): string {
+  try {
+    const fd = openSync(path, "r");
+    try {
+      const buf = Buffer.alloc(maxBytes);
+      const n = readSync(fd, buf, 0, maxBytes, 0);
+      return buf.toString("utf8", 0, n);
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return "";
+  }
+}
+
+/** Read up to the last `maxBytes` of a file (for a bounded tail scan). */
+function readTail(path: string, maxBytes: number): string {
+  try {
+    const size = statSync(path).size;
+    const start = Math.max(0, size - maxBytes);
+    const len = size - start;
+    const fd = openSync(path, "r");
+    try {
+      const buf = Buffer.alloc(len);
+      const n = readSync(fd, buf, 0, len, start);
+      return buf.toString("utf8", 0, n);
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Outcome of a usage fetch. `cooldown` (a 429) tells the cache to back off for
+ * `retryAfterMs` so a rate limit can never cascade into repeated hits — the
+ * failure mode that starves the tool's own client.
+ */
+type FetchOutcome<T> =
+  | { kind: "ok"; data: T }
+  | { kind: "cooldown"; retryAfterMs: number }
+  | { kind: "fail" };
+
+/** Short, non-reversible fingerprint of a token, for per-account cache keys. */
+function tokenFingerprint(token: string): string {
+  return createHash("sha256").update(token).digest("hex").slice(0, 12);
+}
+
+/**
+ * Enrich a report's entries over the network with live usage each tool keeps
+ * server-side, authenticating with the credential already on disk. Best-effort
+ * and network-guarded: every failure degrades to a note, never throws. No-op
+ * for a tool that isn't installed / present in the report.
+ */
+export async function enrichFromApi(
+  report: DevtoolsReport,
+  opts: {
+    cursorKey?: string | null;
+    timeoutMs?: number;
+    home?: string;
+    /** Cache TTL for the usage endpoints (ms). 0 disables caching. Default 120s. */
+    cacheTtlMs?: number;
+  } = {},
+): Promise<DevtoolsReport> {
+  const home = opts.home ?? homedir();
+  const timeoutMs = opts.timeoutMs ?? 12_000;
+  // 5-minute cache. The usage windows move slowly, and this is the hard cap on
+  // how often we touch a rate-limited endpoint no matter how often the dashboard
+  // re-renders — the page can refresh every couple seconds and still hit the
+  // network at most once per tool per 5 minutes.
+  const cacheTtlMs = opts.cacheTtlMs ?? 300_000;
+
+  // Claude Code — 5h + weekly windows and extra-usage spend from oauth/usage.
+  // Cached per-account, because that endpoint is aggressively rate-limited and
+  // Claude Code's OWN "Account & Usage" panel hits it too — a chatty dashboard
+  // would starve it. Keying by token fingerprint means switching accounts shows
+  // the new account's numbers at once instead of the previous account's cache.
+  const claude = report.tools.find((t) => t.tool === "claude-code");
+  if (claude?.installed) {
+    const token = readClaudeOauthToken(home);
+    if (token) {
+      const live = await cachedUsage(
+        home,
+        `claude-usage-${tokenFingerprint(token)}`,
+        cacheTtlMs,
+        () => fetchClaudeUsage(token, claudeCodeVersion(home), timeoutMs),
+      );
+      if (live) {
+        claude.quota = live.quota;
+        claude.spend = live.spend;
+        // Drop the pure-local "quota is server-side" caveat now that it's filled.
+        claude.notes = claude.notes.filter((n) => !n.includes("server-side via /usage"));
+      } else {
+        claude.notes.push("live usage unavailable (rate-limited or token stale; retries shortly)");
+      }
+    }
+  }
+
+  const cursor = report.tools.find((t) => t.tool === "cursor");
+  if (!cursor?.installed) return report;
+
+  // Cursor usage + billing from the IDE's own session token (no API key needed).
+  const auth = readCursorSessionAuth(home);
+  if (auth) {
+    const usage = await cachedUsage(
+      home,
+      `cursor-usage-${tokenFingerprint(auth.token)}`,
+      cacheTtlMs,
+      () => fetchCursorUsage(auth, timeoutMs),
+    );
+    if (usage) {
+      cursor.usage = usage.usage;
+      cursor.spend = usage.spend;
+    } else {
+      cursor.notes.push("Cursor usage unavailable (session token may be stale — reopen Cursor)");
+    }
+  }
+
+  // Cursor Cloud Agent activity from a configured API key (optional, separate auth).
+  const key = opts.cursorKey !== undefined ? opts.cursorKey : resolveCursorApiKey();
+  if (key) {
+    cursor.api = await fetchCursorApi(key, cursorUserAgent(auth?.version ?? null), timeoutMs);
+    // On success the structured `api` fields carry the signal; only note a break.
+    if (!cursor.api.ok) {
+      cursor.notes.unshift(`API key configured but not usable: ${cursor.api.error ?? "unknown"}`);
+    }
+  }
+  return report;
+}
+
+/**
+ * One live call per usage endpoint (cache-bypassing) to check the integration
+ * still works — the occasional "did a client change its headers?" test. It
+ * exercises the EXACT request builders production uses, so an `auth_rejected`
+ * result means our headers/token stopped being accepted, and `shape_changed`
+ * means the response schema drifted. Rate-limited results are reported as such,
+ * not as failures. Makes at most one request per tool; run it by hand (it is not
+ * scheduled) so it can't itself cause a rate limit.
+ */
+export async function probeEndpoints(
+  opts: { home?: string; timeoutMs?: number; only?: readonly DevtoolName[] } = {},
+): Promise<ProbeResult[]> {
+  const home = opts.home ?? homedir();
+  const timeoutMs = opts.timeoutMs ?? 12_000;
+  const only = new Set(opts.only ?? ALL_TOOLS);
+  const out: ProbeResult[] = [];
+
+  if (only.has("claude-code")) {
+    const version = claudeCodeVersion(home);
+    const token = readClaudeOauthToken(home);
+    if (!token) {
+      out.push(
+        noCred("claude-code", CLAUDE_USAGE_URL, version, "no usable OAuth token in ~/.claude"),
+      );
+    } else {
+      const { url, headers } = claudeUsageRequest(token, version);
+      out.push(
+        await probeOne("claude-code", url, { headers }, version, timeoutMs, (j) => {
+          const o = j as { limits?: unknown; five_hour?: unknown };
+          return Array.isArray(o.limits) || o.five_hour != null;
+        }),
+      );
+    }
+  }
+
+  if (only.has("cursor")) {
+    const auth = readCursorSessionAuth(home);
+    if (!auth) {
+      out.push(noCred("cursor", CURSOR_USAGE_URL, null, "no usable session token in state.vscdb"));
+    } else {
+      const { url, init } = cursorUsageRequest(auth);
+      out.push(
+        await probeOne("cursor", url, init, auth.version, timeoutMs, (j) => {
+          const o = j as { planUsage?: unknown; billingCycleEnd?: unknown };
+          return o.planUsage != null || o.billingCycleEnd != null;
+        }),
+      );
+    }
+  }
+
+  // Codex is read from local files only (no endpoint to probe), so it's omitted.
+  return out;
+}
+
+function noCred(
+  tool: DevtoolName,
+  endpoint: string,
+  clientVersion: string | null,
+  detail: string,
+): ProbeResult {
+  return { tool, endpoint, clientVersion, status: null, outcome: "no_credential", detail };
+}
+
+async function probeOne(
+  tool: DevtoolName,
+  url: string,
+  init: RequestInit,
+  clientVersion: string | null,
+  timeoutMs: number,
+  shapeOk: (json: unknown) => boolean,
+): Promise<ProbeResult> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const base = { tool, endpoint: url, clientVersion };
+  try {
+    const res = await fetch(url, { ...init, signal: controller.signal });
+    const status = res.status;
+    if (status === 429) {
+      return {
+        ...base,
+        status,
+        outcome: "rate_limited",
+        detail: `429; retry after ${Math.round(retryAfterMs(res) / 1000)}s`,
+      };
+    }
+    if (status === 401 || status === 403) {
+      return {
+        ...base,
+        status,
+        outcome: "auth_rejected",
+        detail: `HTTP ${status} — auth or required headers may have changed`,
+      };
+    }
+    if (!res.ok) return { ...base, status, outcome: "unreachable", detail: `HTTP ${status}` };
+    let json: unknown;
+    try {
+      json = await res.json();
+    } catch {
+      return { ...base, status, outcome: "shape_changed", detail: "200 but body was not JSON" };
+    }
+    if (!shapeOk(json)) {
+      return {
+        ...base,
+        status,
+        outcome: "shape_changed",
+        detail: "200 but expected fields absent — schema may have changed",
+      };
+    }
+    return { ...base, status, outcome: "ok", detail: "200, expected shape present" };
+  } catch (err) {
+    return {
+      ...base,
+      status: null,
+      outcome: "unreachable",
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+interface UsageCacheEntry<T> {
+  /** When `data` was last fetched (ms epoch). */
+  at: number;
+  /** Last-known-good result, or null if a fetch never succeeded. */
+  data: T | null;
+  /** If set and still in the future, do not call the endpoint (rate-limit backoff). */
+  cooldownUntil?: number;
+}
+
+/**
+ * Wrap a usage fetch in an on-disk cache under `<home>/.cache/harnery/devtools/
+ * <name>.json`, protecting rate-limited endpoints on three fronts:
+ *
+ *   • Fresh success (`< ttlMs` old) short-circuits the network entirely.
+ *   • A 429 records a `cooldownUntil` from the server's retry-after, and no call
+ *     is made until it passes — so a rate limit can't cascade into a hammer loop
+ *     (the failure mode that starved Claude Code's own usage panel). During the
+ *     cooldown the last-known-good value is served, so the card stays populated.
+ *   • Any other failure serves last-known-good and retries next time.
+ *
+ * Best-effort: read/write errors fall back to a live fetch. `ttlMs <= 0` fetches
+ * every call (still honoring a cooldown) and skips writes.
+ */
+async function cachedUsage<T>(
+  home: string,
+  name: string,
+  ttlMs: number,
+  fetcher: () => Promise<FetchOutcome<T>>,
+): Promise<T | null> {
+  const now = Date.now();
+  const dir = join(home, ".cache", "harnery", "devtools");
+  const file = join(dir, `${name}.json`);
+
+  let entry: UsageCacheEntry<T> | null = null;
+  try {
+    entry = JSON.parse(readFileSync(file, "utf8")) as UsageCacheEntry<T>;
+  } catch {
+    // no cache / unreadable
+  }
+  // Fresh cached success.
+  if (entry?.data != null && ttlMs > 0 && now - entry.at < ttlMs) return entry.data;
+  // In a rate-limit cooldown — do not call; serve last-known-good (may be null).
+  if (entry?.cooldownUntil != null && now < entry.cooldownUntil) return entry.data ?? null;
+
+  const outcome = await fetcher();
+  const write = (e: UsageCacheEntry<T>) => {
+    try {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(file, JSON.stringify(e));
+    } catch {
+      // cache write is best-effort
+    }
+  };
+
+  if (outcome.kind === "ok") {
+    if (ttlMs > 0) write({ at: now, data: outcome.data });
+    return outcome.data;
+  }
+  if (outcome.kind === "cooldown") {
+    // Record the backoff, preserving any last-known-good data to keep serving it.
+    write({
+      at: entry?.at ?? now,
+      data: entry?.data ?? null,
+      cooldownUntil: now + outcome.retryAfterMs,
+    });
+    return entry?.data ?? null;
+  }
+  // Plain failure: leave the cache as-is (retry next call), serve any stale data.
+  return entry?.data ?? null;
+}
+
+/**
+ * Read Claude Code's OAuth access token from ~/.claude/.credentials.json.
+ * Returns null when absent or expired (both the access and refresh windows are
+ * past, so a call would 401). The token is used only to build the request and
+ * is never stored on the report.
+ */
+function readClaudeOauthToken(home: string): string | null {
+  const oauth = readJson<Record<string, unknown>>(join(home, ".claude", ".credentials.json"))
+    ?.claudeAiOauth as Record<string, unknown> | undefined;
+  const token = strOr(oauth?.accessToken);
+  if (!token) return null;
+  const accessExp = numOr(oauth?.expiresAt);
+  const refreshExp = numOr(oauth?.refreshTokenExpiresAt);
+  // If both windows are past, the token is dead — skip the doomed call.
+  if ((refreshExp ?? accessExp ?? Number.POSITIVE_INFINITY) < Date.now()) return null;
+  return token;
+}
+
+/** Statuses in the oauth/usage `limits[]` array, mapped to quota-window labels. */
+const CLAUDE_LIMIT_LABELS: Record<string, string> = {
+  session: "5h",
+  weekly_all: "weekly",
+  weekly_scoped: "weekly",
+};
+
+const CLAUDE_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+
+/**
+ * The request we send to Claude's usage endpoint — the same URL + headers the
+ * `/usage` command sends, so the call is indistinguishable from Claude Code's
+ * own (Bearer token, the oauth beta, and the `claude-cli/<version> (external,
+ * cli)` UA + `x-app: cli`). Extracted so the doctor probe exercises the exact
+ * headers we use in production.
+ */
+function claudeUsageRequest(token: string, version: string): { url: string; headers: HeadersInit } {
+  return {
+    url: CLAUDE_USAGE_URL,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "anthropic-beta": "oauth-2025-04-20",
+      "anthropic-version": "2023-06-01",
+      "User-Agent": `claude-cli/${version} (external, cli)`,
+      "x-app": "cli",
+    },
+  };
+}
+
+/**
+ * Fetch Claude Code's live usage from api.anthropic.com/api/oauth/usage with the
+ * local OAuth token. Returns a `FetchOutcome`: `ok` with quota + spend,
+ * `cooldown` on a 429 (with the server's retry-after), or `fail`.
+ */
+async function fetchClaudeUsage(
+  token: string,
+  version: string,
+  timeoutMs: number,
+): Promise<FetchOutcome<{ quota: QuotaWindow[]; spend: SpendStatus | null }>> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const { url, headers } = claudeUsageRequest(token, version);
+    const res = await fetch(url, { headers, signal: controller.signal });
+    if (res.status === 429) return { kind: "cooldown", retryAfterMs: retryAfterMs(res) };
+    if (!res.ok) return { kind: "fail" };
+    const raw = (await res.json()) as {
+      limits?: Array<{
+        kind?: string;
+        percent?: number;
+        resets_at?: string;
+        scope?: { model?: { display_name?: string } } | null;
+      }>;
+      five_hour?: { utilization?: number; resets_at?: string };
+      seven_day?: { utilization?: number; resets_at?: string };
+      spend?: {
+        used?: { amount_minor?: number; exponent?: number };
+        limit?: { amount_minor?: number; exponent?: number };
+        enabled?: boolean;
+      };
+    };
+
+    // Prefer the structured limits[] array (carries model-scoped windows); fall
+    // back to the flat five_hour / seven_day pair.
+    let quota: QuotaWindow[] = [];
+    if (Array.isArray(raw.limits) && raw.limits.length) {
+      quota = raw.limits.map((l) => {
+        const model = strOr(l.scope?.model?.display_name);
+        const base = l.kind ? (CLAUDE_LIMIT_LABELS[l.kind] ?? l.kind) : "quota";
+        return {
+          window: model ? `${base} · ${model}` : base,
+          usedPercent: roundPct(l.percent),
+          resetsAt: isoOrNull(l.resets_at),
+        };
+      });
+    } else {
+      const flat: Array<[string, { utilization?: number; resets_at?: string } | undefined]> = [
+        ["5h", raw.five_hour],
+        ["weekly", raw.seven_day],
+      ];
+      quota = flat
+        .filter(([, w]) => w?.utilization != null)
+        .map(([label, w]) => ({
+          window: label,
+          usedPercent: roundPct(w?.utilization),
+          resetsAt: isoOrNull(w?.resets_at),
+        }));
+    }
+
+    let spend: SpendStatus | null = null;
+    const sp = raw.spend;
+    if (sp?.enabled && (minorToCents(sp.used) != null || minorToCents(sp.limit) != null)) {
+      spend = {
+        label: "Extra usage",
+        usedCents: minorToCents(sp.used),
+        limitCents: minorToCents(sp.limit),
+      };
+    }
+    return { kind: "ok", data: { quota, spend } };
+  } catch {
+    return { kind: "fail" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Parse a `Retry-After` header (seconds) to ms; default 60s when absent/unparseable. */
+function retryAfterMs(res: Response): number {
+  const raw = res.headers.get("retry-after");
+  const secs = raw != null ? Number.parseInt(raw, 10) : Number.NaN;
+  return (Number.isFinite(secs) && secs > 0 ? secs : 60) * 1000;
+}
+
+/** Convert an {amount_minor, exponent} money value to cents (exponent 2 = already cents). */
+function minorToCents(m: { amount_minor?: number; exponent?: number } | undefined): number | null {
+  const minor = numOr(m?.amount_minor);
+  if (minor == null) return null;
+  const exp = numOr(m?.exponent) ?? 2;
+  return Math.round(minor * 10 ** (2 - exp));
+}
+
+/** Normalize an ISO-ish timestamp (may carry a +00:00 offset) to a Z-suffixed ISO, or null. */
+function isoOrNull(s: string | undefined): string | null {
+  if (!s) return null;
+  const t = Date.parse(s);
+  return Number.isNaN(t) ? null : new Date(t).toISOString();
+}
+
+interface CursorSessionAuth {
+  token: string;
+  userId: string;
+  /** Local Cursor app version (for the client User-Agent), else null. */
+  version: string | null;
+}
+
+/**
+ * Read Cursor's locally-stored session token from state.vscdb and derive the
+ * WorkOS user id from its JWT `sub` claim, plus the local Cursor version for the
+ * client User-Agent. Returns null when the DB is unreadable, no token is
+ * present, or the token has expired (so we skip a doomed call). The token
+ * string is used only to build the request and is never stored on the report.
+ */
+function readCursorSessionAuth(home: string): CursorSessionAuth | null {
+  const vscdb = cursorGlobalVscdb(home);
+  if (!vscdb) return null;
+  const items = readVscdbItems(vscdb, [
+    "cursorAuth/accessToken",
+    "cursor.startupMetrics.lastVersion",
+  ]);
+  const token = strOr(items?.["cursorAuth/accessToken"]);
+  if (!token) return null;
+  const claims = decodeJwtClaims(token);
+  const sub = strOr(claims?.sub);
+  if (!sub) return null;
+  // Skip an obviously-expired token (exp is seconds since epoch).
+  const exp = numOr(claims?.exp);
+  if (exp != null && exp * 1000 < Date.now()) return null;
+  // sub looks like "auth0|user_01J…"; the WorkOS cookie wants the id after the "|".
+  const userId = sub.includes("|") ? (sub.split("|").pop() ?? sub) : sub;
+  return { token, userId, version: strOr(items?.["cursor.startupMetrics.lastVersion"]) };
+}
+
+// Cursor is an Electron app; its embedded browser presents a VS Code-style UA
+// (`… <App>/<ver> Chrome/<chromium> Electron/<electron> Safari/537.36`). We
+// mirror that, injecting the LIVE Cursor version read from state.vscdb. The
+// Chromium/Electron pair is cosmetic (tracks Cursor's VS Code base) — bump when
+// Cursor's base does; the identifying `Cursor/<version>` part is always live.
+const CURSOR_CHROMIUM = "132.0.6834.210";
+const CURSOR_ELECTRON = "34.5.8";
+
+/** Cursor Electron client User-Agent, embedding the live app version. */
+function cursorUserAgent(version: string | null): string {
+  const ver = version ?? "0.0.0";
+  return `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Cursor/${ver} Chrome/${CURSOR_CHROMIUM} Electron/${CURSOR_ELECTRON} Safari/537.36`;
+}
+
+const CURSOR_USAGE_URL = "https://cursor.com/api/dashboard/get-current-period-usage";
+
+/**
+ * The request we send to Cursor's usage endpoint — the WorkOS session cookie
+ * (`<userId>::<token>`) plus the browser-consistent Origin/Referer cursor.com
+ * requires, and Cursor's own Electron client UA. Extracted so the doctor probe
+ * exercises the exact request we use in production.
+ */
+function cursorUsageRequest(auth: CursorSessionAuth): { url: string; init: RequestInit } {
+  const cookie = `WorkosCursorSessionToken=${encodeURIComponent(`${auth.userId}::${auth.token}`)}`;
+  return {
+    url: CURSOR_USAGE_URL,
+    init: {
+      method: "POST",
+      headers: {
+        Cookie: cookie,
+        "Content-Type": "application/json",
+        Origin: "https://cursor.com",
+        Referer: "https://cursor.com/dashboard/spending",
+        "User-Agent": cursorUserAgent(auth.version),
+      },
+      body: "{}",
+    },
+  };
+}
+
+/**
+ * Fetch the current-period usage the Cursor UI shows on its Spending page.
+ * Returns a `FetchOutcome`: `ok`, `cooldown` on a 429, or `fail`.
+ */
+async function fetchCursorUsage(
+  auth: CursorSessionAuth,
+  timeoutMs: number,
+): Promise<FetchOutcome<{ usage: CursorUsage; spend: SpendStatus | null }>> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const { url, init } = cursorUsageRequest(auth);
+    const res = await fetch(url, { ...init, signal: controller.signal });
+    if (res.status === 429) return { kind: "cooldown", retryAfterMs: retryAfterMs(res) };
+    if (!res.ok) return { kind: "fail" };
+    const raw = (await res.json()) as {
+      billingCycleStart?: string | number;
+      billingCycleEnd?: string | number;
+      planUsage?: {
+        totalPercentUsed?: number;
+        apiPercentUsed?: number;
+        autoPercentUsed?: number;
+        limit?: number;
+      };
+      spendLimitUsage?: { individualLimit?: number; individualRemaining?: number };
+    };
+    const pu = raw.planUsage ?? {};
+    const sl = raw.spendLimitUsage ?? {};
+    const spendLimit = numOr(sl.individualLimit);
+    const spendRemaining = numOr(sl.individualRemaining);
+    const usage: CursorUsage = {
+      cycleStart: msToIso(raw.billingCycleStart),
+      cycleEnd: msToIso(raw.billingCycleEnd),
+      totalPercentUsed: roundPct(pu.totalPercentUsed),
+      apiPercentUsed: roundPct(pu.apiPercentUsed),
+      firstPartyPercentUsed: roundPct(pu.autoPercentUsed),
+      includedLimitCents: numOr(pu.limit),
+    };
+    const spend: SpendStatus | null =
+      spendLimit != null
+        ? {
+            label: "On-demand",
+            usedCents: spendRemaining != null ? spendLimit - spendRemaining : null,
+            limitCents: spendLimit,
+          }
+        : null;
+    return { kind: "ok", data: { usage, spend } };
+  } catch {
+    return { kind: "fail" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Parse a ms-epoch value (string or number) to ISO, or null. */
+function msToIso(v: string | number | undefined): string | null {
+  const n = typeof v === "string" ? Number.parseInt(v, 10) : v;
+  if (n == null || !Number.isFinite(n) || n <= 0) return null;
+  return new Date(n).toISOString();
+}
+
+/** Clamp a percentage to one decimal place, or null. */
+function roundPct(v: number | undefined): number | null {
+  if (v == null || !Number.isFinite(v)) return null;
+  return Math.round(v * 10) / 10;
+}
+
+async function fetchCursorApi(
+  key: string,
+  userAgent: string,
+  timeoutMs: number,
+): Promise<ApiEnrichment> {
+  const out: ApiEnrichment = { ok: false, keyName: null, cloudAgents: null, error: null };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const get = async (path: string): Promise<unknown> => {
+    const res = await fetch(`https://api.cursor.com${path}`, {
+      headers: { Authorization: `Bearer ${key}`, "User-Agent": userAgent },
+      signal: controller.signal,
+    });
+    if (!res.ok) throw new Error(`${path} → HTTP ${res.status}`);
+    return res.json();
+  };
+  try {
+    const me = (await get("/v0/me")) as { apiKeyName?: string; userEmail?: string };
+    out.ok = true;
+    out.keyName = strOr(me.apiKeyName);
+    try {
+      const data = (await get("/v0/agents")) as { agents?: Array<{ status?: string }> };
+      const list = Array.isArray(data.agents) ? data.agents : [];
+      out.cloudAgents = {
+        total: list.length,
+        active: list.filter((a) => a.status && !CURSOR_AGENT_INACTIVE.has(a.status)).length,
+      };
+    } catch {
+      // /v0/me worked but agents listing failed; key is still valid
+    }
+  } catch (err) {
+    out.ok = false;
+    out.error = err instanceof Error ? err.message : String(err);
+  } finally {
+    clearTimeout(timer);
+  }
+  return out;
+}
+
+export function readDevtools(opts: ReadDevtoolsOpts = {}): DevtoolsReport {
+  const home = opts.home ?? homedir();
+  const now = opts.now ?? Date.now();
+  const usage = opts.usage ?? false;
+  const windowDays = opts.windowDays ?? 7;
+  const only = new Set(opts.only ?? ALL_TOOLS);
+
+  const tools: ToolStatus[] = [];
+  if (only.has("claude-code")) tools.push(readClaudeCode(home, now, usage, windowDays));
+  if (only.has("codex")) tools.push(readCodex(home, now, windowDays));
+  if (only.has("cursor")) tools.push(readCursor(home));
+
+  return {
+    generatedAt: new Date(now).toISOString(),
+    // The window that any shown token total is measured over. Codex always
+    // reports a windowed total; Claude's transcript scan is `--usage`-gated.
+    windowDays,
+    tools,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Claude Code (~/.claude)
+// ---------------------------------------------------------------------------
+
+function readClaudeCode(home: string, now: number, usage: boolean, windowDays: number): ToolStatus {
+  const dir = join(home, ".claude");
+  const status: ToolStatus = base("claude-code");
+  status.installed = existsSync(dir);
+  if (!status.installed) {
+    status.notes.push("~/.claude not found");
+    return status;
+  }
+
+  // Auth: ~/.claude/.credentials.json -> claudeAiOauth (non-secret fields only).
+  const oauth = readJson<Record<string, unknown>>(join(dir, ".credentials.json"))?.claudeAiOauth as
+    | Record<string, unknown>
+    | undefined;
+  if (oauth) {
+    const accessExp = numOr(oauth.expiresAt);
+    const refreshExp = numOr(oauth.refreshTokenExpiresAt);
+    status.loggedIn = (refreshExp ?? accessExp ?? 0) > now;
+    status.authExpiresAt = accessExp ? new Date(accessExp).toISOString() : null;
+    status.plan = strOr(oauth.subscriptionType);
+    status.rateLimitTier = strOr(oauth.rateLimitTier);
+    if (accessExp && accessExp <= now && refreshExp && refreshExp > now) {
+      status.notes.push("access token expired; refreshes on next use");
+    }
+  } else {
+    status.loggedIn = false;
+    status.notes.push("no credential found (not logged in)");
+  }
+
+  // Richer account/plan metadata lives in ~/.claude.json (sibling of the dir).
+  const cfg = readJson<Record<string, unknown>>(join(home, ".claude.json"));
+  const acct = cfg?.oauthAccount as Record<string, unknown> | undefined;
+  if (acct) {
+    status.account = strOr(acct.emailAddress);
+    // Prefer the seat tier as the human "plan" when present.
+    status.plan = strOr(acct.seatTier) ?? status.plan;
+    status.rateLimitTier = strOr(acct.userRateLimitTier) ?? status.rateLimitTier;
+  }
+
+  // Sessions: one .jsonl transcript per session under projects/<slug>/.
+  const projects = join(dir, "projects");
+  const files = listFilesRecursive(projects, ".jsonl");
+  status.sessions = files.length || null;
+  status.lastActivity = latestMtimeIso(files);
+
+  // Claude Code does not persist its rate-limit windows locally; the live
+  // 5-hour / weekly figures come from the `/usage` server call, which the
+  // enrichment step fetches with the local OAuth token. Without it (--no-api),
+  // quota stays blank.
+  status.quota = null;
+  status.notes.push("live quota (5h/weekly resets) is server-side via /usage");
+
+  // Windowed token total, memoized per transcript so it's card-cheap after the
+  // first scan. `--usage` (fresh=true) forces an exact, cache-bypassing recount.
+  status.tokensUsed = sumClaudeTokensCached(home, files, now, windowDays, usage);
+
+  return status;
+}
+
+/** Sum the four token fields across every assistant message in one transcript. */
+function sumFileTokens(file: string): number {
+  let total = 0;
+  for (const line of readJsonlSync(file)) {
+    const usage = (line as { message?: { usage?: Record<string, number> } }).message?.usage;
+    if (!usage) continue;
+    total +=
+      (usage.input_tokens ?? 0) +
+      (usage.output_tokens ?? 0) +
+      (usage.cache_creation_input_tokens ?? 0) +
+      (usage.cache_read_input_tokens ?? 0);
+  }
+  return total;
+}
+
+interface TokenCacheEntry {
+  mtime: number;
+  size: number;
+  tokens: number;
+}
+
+/**
+ * Windowed Claude token total, memoized per transcript. Unlike Codex, a Claude
+ * transcript has no per-session cumulative field, so the total is the sum of
+ * every message — a full read of each in-window file (hundreds of MB in a busy
+ * week). To keep that off the hot render path, each file's sum is cached by
+ * (path, mtime, size) at `~/.cache/harnery/devtools/claude-tokens.json`: an
+ * unchanged transcript is never re-read, so after warm-up only the live session
+ * (whose size/mtime moved) is rescanned. `fresh` (from `--usage`) bypasses the
+ * cache for an exact recompute. The cache holds only in-window files, so mixing
+ * a larger `--window-days` re-reads the older span once.
+ */
+function sumClaudeTokensCached(
+  home: string,
+  files: string[],
+  now: number,
+  windowDays: number,
+  fresh: boolean,
+): number {
+  const cutoff = now - windowDays * 86_400_000;
+  const inWindow = files.filter((f) => safeMtime(f) >= cutoff);
+  const cacheFile = join(home, ".cache", "harnery", "devtools", "claude-tokens.json");
+
+  let cache: Record<string, TokenCacheEntry> = {};
+  if (!fresh) {
+    try {
+      cache = JSON.parse(readFileSync(cacheFile, "utf8")) as Record<string, TokenCacheEntry>;
+    } catch {
+      // no cache / unreadable — cold start
+    }
+  }
+
+  const next: Record<string, TokenCacheEntry> = {};
+  let total = 0;
+  let changed = false;
+  for (const f of inWindow) {
+    let mtime: number;
+    let size: number;
+    try {
+      const st = statSync(f);
+      mtime = st.mtimeMs;
+      size = st.size;
+    } catch {
+      continue; // vanished mid-scan
+    }
+    const hit = cache[f];
+    const tokens = hit && hit.mtime === mtime && hit.size === size ? hit.tokens : sumFileTokens(f);
+    if (!hit || hit.mtime !== mtime || hit.size !== size) changed = true;
+    next[f] = { mtime, size, tokens };
+    total += tokens;
+  }
+
+  // Persist when anything moved (new/changed file) or entries aged out of window.
+  if (!fresh && (changed || Object.keys(next).length !== Object.keys(cache).length)) {
+    try {
+      mkdirSync(dirname(cacheFile), { recursive: true });
+      const tmp = `${cacheFile}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify(next));
+      renameSync(tmp, cacheFile); // atomic swap — no torn reads for a concurrent reader
+    } catch {
+      // cache write is best-effort
+    }
+  }
+  return total;
+}
+
+// ---------------------------------------------------------------------------
+// Codex (~/.codex)
+// ---------------------------------------------------------------------------
+
+function readCodex(home: string, now: number, windowDays: number): ToolStatus {
+  const dir = join(home, ".codex");
+  const status: ToolStatus = base("codex");
+  const globbed = codexRollouts(home);
+  status.installed = existsSync(dir) || globbed.length > 0;
+  if (!status.installed) {
+    status.notes.push("~/.codex not found");
+    return status;
+  }
+
+  // Codex can have more than one install on a machine (e.g. a WSL CLI and the
+  // Windows desktop app, each its own account). They must not be mixed: read
+  // auth AND rate limits from the SAME install — the one actually in use, which
+  // is whichever owns the most-recently-written rollout.
+  const newestRollout = newestFile(globbed);
+  const activeRoot = newestRollout ? codexRootOf(newestRollout) : dir;
+
+  // Auth: <activeRoot>/auth.json. The id_token carries the non-secret account +
+  // plan claims; the access_token carries the meaningful expiry (it outlives the
+  // id_token and is what refreshes), so we report that, not the id_token's.
+  const auth = readJson<Record<string, unknown>>(join(activeRoot, "auth.json"));
+  if (auth) {
+    const tokens = auth.tokens as Record<string, unknown> | undefined;
+    const idToken = strOr(tokens?.id_token);
+    const accessToken = strOr(tokens?.access_token);
+    const idClaims = idToken ? decodeJwtClaims(idToken) : null;
+    const accessExp = numOr(accessToken ? decodeJwtClaims(accessToken)?.exp : undefined);
+    if (idClaims) {
+      status.account = strOr(idClaims.email);
+      const authClaim = idClaims["https://api.openai.com/auth"] as
+        | Record<string, unknown>
+        | undefined;
+      status.plan = strOr(authClaim?.chatgpt_plan_type);
+    }
+    // Prefer the access token's expiry; fall back to the id_token's.
+    const exp = accessExp ?? numOr(idClaims?.exp);
+    status.authExpiresAt = exp ? new Date(exp * 1000).toISOString() : null;
+    status.loggedIn = Boolean(accessToken || idToken) && (exp == null || exp * 1000 > now);
+    if (exp && exp * 1000 <= now) {
+      status.notes.push("token expired; refreshes via stored refresh token");
+    }
+  } else {
+    status.loggedIn = false;
+    status.notes.push("no auth.json found (not logged in)");
+  }
+
+  // Activity: prefer the active install's state_5.sqlite (`threads`) for exact
+  // counts, but only when it's actually the active install's DB — otherwise the
+  // rollouts are the cross-install-consistent source.
+  const state = readCodexState(join(activeRoot, "sqlite", "state_5.sqlite"));
+  const activeRollouts = globbed.filter((f) => codexRootOf(f) === activeRoot);
+  if (state) {
+    status.sessions = state.sessions;
+    if (state.lastMs) status.lastActivity = new Date(state.lastMs).toISOString();
+  } else {
+    // No DB for the active install (e.g. the Windows desktop app uses a
+    // different store): fall back to that install's rollout files.
+    status.sessions = activeRollouts.length || null;
+    status.lastActivity = latestMtimeIso(activeRollouts);
+  }
+
+  // Windowed token total: always shown (the tail scan is card-cheap), summed
+  // from the rollouts since they're the fresh cross-install source — the state
+  // DB can lag the live sessions.
+  status.tokensUsed = sumCodexTokens(activeRollouts, now, windowDays);
+
+  // Freshest rollout → current rate-limit windows + live plan_type.
+  if (newestRollout) {
+    const rl = lastRateLimits(newestRollout);
+    if (rl) {
+      status.quota = [rl.primary, rl.secondary].filter((q): q is QuotaWindow => q !== null);
+      if (rl.planType) status.plan = rl.planType; // live plan wins over the id_token
+      if (rl.reachedType) status.notes.push(`rate limit reached (${rl.reachedType} window)`);
+    }
+  }
+  if (!status.quota?.length) status.notes.push("no local rate-limit snapshot in latest session");
+
+  return status;
+}
+
+/** The Codex install root that owns a rollout path (the part before `/sessions/`). */
+function codexRootOf(rolloutPath: string): string {
+  const parts = rolloutPath.split(/[/\\]sessions[/\\]/);
+  return parts.length > 1 ? parts[0] : rolloutPath;
+}
+
+interface CodexState {
+  sessions: number;
+  lastMs: number | null;
+  newestRollout: string | null;
+}
+
+/** Read Codex's `state_5.sqlite` threads table for session count, recency, newest rollout.
+ * (Token totals come from the rollouts, not here — the DB can lag live sessions.) */
+function readCodexState(dbPath: string): CodexState | null {
+  if (!existsSync(dbPath)) return null;
+  return withSqlite(dbPath, (db) => {
+    const agg = db.query("SELECT count(*) c, max(updated_at_ms) mx FROM threads").get() as
+      | { c: number; mx: number | null }
+      | undefined;
+    const newest = db
+      .query("SELECT rollout_path FROM threads ORDER BY updated_at_ms DESC LIMIT 1")
+      .get() as { rollout_path: string | null } | undefined;
+    return {
+      sessions: agg?.c ?? 0,
+      lastMs: numOr(agg?.mx),
+      newestRollout: strOr(newest?.rollout_path),
+    };
+  });
+}
+
+/** All Codex rollout files across the WSL home and (real-home only) the Windows-side home. */
+function codexRollouts(home: string): string[] {
+  const roots = [join(home, ".codex", "sessions")];
+  if (home === homedir()) {
+    try {
+      if (existsSync("/mnt/c/Users")) {
+        for (const u of readdirSync("/mnt/c/Users"))
+          roots.push(`/mnt/c/Users/${u}/.codex/sessions`);
+      }
+    } catch {
+      // not WSL
+    }
+  }
+  return roots
+    .flatMap((r) => listFilesRecursive(r, ".jsonl"))
+    .filter((f) => f.includes("rollout-"));
+}
+
+interface RateLimitsSnapshot {
+  primary: QuotaWindow | null;
+  secondary: QuotaWindow | null;
+  planType: string | null;
+  /** Non-null only when a limit was actually hit (e.g. "primary"/"secondary"). */
+  reachedType: string | null;
+}
+
+function lastRateLimits(file: string): RateLimitsSnapshot | null {
+  let found: RateLimitsSnapshot | null = null;
+  for (const line of readJsonlSync(file)) {
+    const payload = (line as { type?: string; payload?: Record<string, unknown> }).payload;
+    if (!payload) continue;
+    if (payload.type !== "token_count") continue;
+    const rl = payload.rate_limits as Record<string, unknown> | undefined;
+    if (!rl) continue;
+    found = {
+      primary: quotaFromWindow(rl.primary as Record<string, unknown> | undefined),
+      secondary: quotaFromWindow(rl.secondary as Record<string, unknown> | undefined),
+      planType: strOr(rl.plan_type),
+      reachedType: strOr(rl.rate_limit_reached_type),
+    };
+  }
+  return found;
+}
+
+function quotaFromWindow(w: Record<string, unknown> | undefined): QuotaWindow | null {
+  if (!w) return null;
+  const resets = numOr(w.resets_at);
+  return {
+    window: windowLabel(numOr(w.window_minutes)),
+    usedPercent: numOr(w.used_percent),
+    resetsAt: resets ? new Date(resets * 1000).toISOString() : null,
+  };
+}
+
+function windowLabel(minutes: number | null): string {
+  if (minutes == null) return "unknown";
+  if (minutes === 300) return "5h";
+  if (minutes === 10080) return "weekly";
+  if (minutes % 1440 === 0) return `${minutes / 1440}d`;
+  if (minutes % 60 === 0) return `${minutes / 60}h`;
+  return `${minutes}m`;
+}
+
+/** Bytes tail-read per rollout when summing tokens — enough to hold the last
+ * `token_count` event of any real session while staying cheap on a networked
+ * (WSL → /mnt/c) filesystem. */
+const CODEX_TAIL_BYTES = 131_072;
+
+/**
+ * Windowed token total across the in-window rollouts, light enough to run on
+ * every card render. Each `token_count` event carries a *cumulative*
+ * `info.total_token_usage`, so the session total is the last such event — found
+ * by scanning only the file's tail rather than every line. A session whose final
+ * `token_count` sits beyond the tail (rare: a huge trailing non-token event) is
+ * undercounted; acceptable for a card estimate.
+ */
+function sumCodexTokens(files: string[], now: number, windowDays: number): number {
+  const cutoff = now - windowDays * 86_400_000;
+  let total = 0;
+  for (const f of files) {
+    if (safeMtime(f) < cutoff) continue;
+    total += lastCumulativeTokens(readTail(f, CODEX_TAIL_BYTES));
+  }
+  return total;
+}
+
+/** Last cumulative `total_token_usage.total_tokens` in a rollout tail, or 0. */
+function lastCumulativeTokens(tail: string): number {
+  let last = 0;
+  for (const line of tail.split("\n")) {
+    if (!line.includes('"token_count"')) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue; // a partial first line from the tail cut — skip it
+    }
+    const payload = (parsed as { payload?: Record<string, unknown> }).payload;
+    if (!payload) continue;
+    if (payload.type !== "token_count") continue;
+    const info = payload.info as Record<string, unknown> | undefined;
+    const totals = info?.total_token_usage as Record<string, unknown> | undefined;
+    const t = numOr(totals?.total_tokens);
+    if (t) last = t; // cumulative — the last reading wins
+  }
+  return last;
+}
+
+// ---------------------------------------------------------------------------
+// Cursor (~/.cursor) — most usage/billing is server-side.
+// ---------------------------------------------------------------------------
+
+function readCursor(home: string): ToolStatus {
+  const dir = join(home, ".cursor");
+  // Cursor's IDE state DB (state.vscdb) holds the account email, Stripe
+  // membership + subscription status, and per-chat activity — all token-free
+  // and the richest local signal. It lives under the OS app-support dir
+  // (Linux ~/.config, macOS ~/Library, WSL the Windows-side path), separate
+  // from ~/.cursor (the agent-CLI config). Treat Cursor as installed if either
+  // exists, so a macOS GUI user who never ran the CLI still resolves.
+  const vscdb = cursorGlobalVscdb(home);
+  const status: ToolStatus = base("cursor");
+  status.installed = existsSync(dir) || vscdb != null;
+  if (!status.installed) {
+    status.notes.push("Cursor not found (no ~/.cursor and no state.vscdb)");
+    return status;
+  }
+
+  // Read the state DB when a SQLite engine is available (bun:sqlite); otherwise
+  // fall back to login-presence signals from the remote-server tokens / statsig id.
+  const items = vscdb
+    ? readVscdbItems(vscdb, [
+        "cursorAuth/cachedEmail",
+        "cursorAuth/stripeMembershipType",
+        "cursorAuth/stripeSubscriptionStatus",
+        "composer.composerHeaders",
+      ])
+    : null;
+
+  if (items) {
+    const email = strOr(items["cursorAuth/cachedEmail"]);
+    const membership = strOr(items["cursorAuth/stripeMembershipType"]);
+    const subStatus = strOr(items["cursorAuth/stripeSubscriptionStatus"]);
+    status.account = email;
+    status.plan = membership;
+    status.loggedIn = Boolean(email) || subStatus === "active";
+    if (subStatus) status.notes.push(`subscription ${subStatus}`);
+
+    // Per-chat activity from composer headers (session count + last active).
+    const headers = safeJson(items["composer.composerHeaders"]) as {
+      allComposers?: Array<{ lastUpdatedAt?: number; createdAt?: number }>;
+    } | null;
+    const composers = headers?.allComposers ?? [];
+    if (composers.length) {
+      status.sessions = composers.length;
+      let last = 0;
+      for (const c of composers) last = Math.max(last, c.lastUpdatedAt ?? c.createdAt ?? 0);
+      if (last > 0) status.lastActivity = new Date(last).toISOString();
+    }
+  } else {
+    // Fallback: remote-server tokens + statsig id only prove a login exists.
+    const serverDir = join(home, ".cursor-server");
+    const tokenFiles = existsSync(serverDir)
+      ? readdirSync(serverDir).filter((f) => f.endsWith(".token"))
+      : [];
+    const statsig = readJson<Record<string, unknown>>(join(dir, "statsig-cache.json"));
+    status.account = strOr(statsig?.userID); // opaque statsig id, not an email
+    status.loggedIn = tokenFiles.length > 0 || status.account ? true : null;
+    status.notes.push("state.vscdb unreadable (needs a SQLite engine); login-presence only");
+  }
+
+  // Session count fallback: per-project workspace dirs.
+  if (status.sessions == null) {
+    const projects = join(dir, "projects");
+    const entries = existsSync(projects)
+      ? readdirSync(projects, { withFileTypes: true }).filter((d) => d.isDirectory())
+      : [];
+    status.sessions = entries.length || null;
+    if (!status.lastActivity)
+      status.lastActivity = latestMtimeIso(entries.map((d) => join(projects, d.name)));
+  }
+
+  // Usage + billing live on cursor.com, not on disk. The enrichment step fetches
+  // them with the IDE's session token; without it (--no-api / non-Bun), the card
+  // shows local signals only.
+  status.quota = null;
+  status.tokensUsed = null;
+  status.notes.push("usage + billing come from cursor.com (fetched during the enrichment step)");
+
+  return status;
+}
+
+/** First existing Cursor global `state.vscdb` across native / macOS / WSL-Windows roots. */
+function cursorGlobalVscdb(home: string): string | null {
+  const candidates = [
+    join(home, ".config", "Cursor", "User", "globalStorage", "state.vscdb"),
+    join(home, "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb"),
+  ];
+  // WSL: Cursor's GUI runs on Windows, so the live DB is under /mnt/c/Users/<u>/.
+  // Gated on the real home so a test with a synthetic `home` never reaches out
+  // to the host's actual Windows-side Cursor install.
+  if (home === homedir()) {
+    try {
+      if (existsSync("/mnt/c/Users")) {
+        for (const u of readdirSync("/mnt/c/Users")) {
+          candidates.push(
+            `/mnt/c/Users/${u}/AppData/Roaming/Cursor/User/globalStorage/state.vscdb`,
+          );
+        }
+      }
+    } catch {
+      // no /mnt/c — not WSL
+    }
+  }
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+
+/** vscdb copy fallback is skipped above this size (bytes). Cursor's global DB can be 3GB+. */
+const VSCDB_COPY_MAX_BYTES = 256 * 1024 * 1024;
+
+/**
+ * Open a SQLite DB read-only and run `fn` against it, returning fn's result or
+ * null. Uses `bun:sqlite`, lazily required so non-Bun runtimes degrade to null
+ * rather than crashing at import.
+ *
+ * These DBs (Cursor's `state.vscdb`, Codex's `state_5.sqlite`) are usually
+ * WAL-locked because their app is running, and over the WSL 9p mount a plain
+ * open throws "disk I/O error". The fast path is SQLite immutable mode
+ * (`file:...?immutable=1` with the URI open flag): it ignores the lock and the
+ * WAL and reads only the btree pages the query touches, so lookups cost ~10ms
+ * even on a multi-GB file. The tradeoff is it reads the committed main DB and
+ * skips the newest uncommitted WAL frames, which is fine for a status snapshot.
+ * Only if immutable fails AND the file is small do we snapshot-copy it (copying
+ * a 3GB DB is never worth it).
+ */
+function withSqlite<T>(dbPath: string, fn: (db: VscdbHandle) => T): T | null {
+  let Database: unknown;
+  let constants: { SQLITE_OPEN_READONLY: number; SQLITE_OPEN_URI: number } | undefined;
+  try {
+    const mod = require("bun:sqlite");
+    Database = mod.Database;
+    constants = mod.constants;
+  } catch {
+    return null; // no SQLite engine (plain Node runtime)
+  }
+
+  // Fast path: open immutable + read-only, no copy. Encode the path into a file:
+  // URI (leaves "/" intact, escapes spaces in Windows paths).
+  if (constants) {
+    try {
+      const flags = constants.SQLITE_OPEN_READONLY | constants.SQLITE_OPEN_URI;
+      const uri = `file:${encodeURI(dbPath)}?immutable=1`;
+      const db = new (Database as new (path: string, flags: number) => VscdbHandle)(uri, flags);
+      const out = fn(db);
+      db.close();
+      return out;
+    } catch {
+      // fall through to the size-guarded snapshot fallback
+    }
+  }
+
+  // Fallback: snapshot the DB (+ sidecars) and read the copy, only when small.
+  let size = Number.POSITIVE_INFINITY;
+  try {
+    size = statSync(dbPath).size;
+  } catch {
+    // stat failed; treat as too-large and skip the copy
+  }
+  if (size > VSCDB_COPY_MAX_BYTES) return null;
+
+  let tmp: string | null = null;
+  try {
+    tmp = mkdtempSync(join(tmpdir(), "harn-sqlite-"));
+    const dst = join(tmp, "copy.sqlite");
+    copyFileSync(dbPath, dst);
+    for (const ext of ["-wal", "-shm"]) {
+      if (existsSync(dbPath + ext)) {
+        try {
+          copyFileSync(dbPath + ext, dst + ext);
+        } catch {
+          // sidecar missing/locked — main file alone is still queryable
+        }
+      }
+    }
+    const db = new (Database as new (path: string, opts: { readonly: boolean }) => VscdbHandle)(
+      dst,
+      { readonly: true },
+    );
+    const out = fn(db);
+    db.close();
+    return out;
+  } catch {
+    return null;
+  } finally {
+    if (tmp) {
+      try {
+        rmSync(tmp, { recursive: true, force: true });
+      } catch {
+        // best-effort cleanup
+      }
+    }
+  }
+}
+
+/** Read specific keys from a Cursor `state.vscdb` (VS Code ItemTable). */
+function readVscdbItems(dbPath: string, keys: string[]): Record<string, string> | null {
+  return withSqlite(dbPath, (db) => {
+    const out: Record<string, string> = {};
+    for (const k of keys) {
+      const row = db.query("SELECT value FROM ItemTable WHERE key = ?").get(k) as
+        | { value: string | Uint8Array }
+        | undefined;
+      if (row?.value != null)
+        out[k] =
+          typeof row.value === "string" ? row.value : Buffer.from(row.value).toString("utf8");
+    }
+    return out;
+  });
+}
+
+interface VscdbHandle {
+  query(sql: string): { get(...params: unknown[]): unknown; all(...params: unknown[]): unknown[] };
+  close(): void;
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function base(tool: DevtoolName): ToolStatus {
+  return {
+    tool,
+    installed: false,
+    loggedIn: null,
+    account: null,
+    plan: null,
+    rateLimitTier: null,
+    authExpiresAt: null,
+    sessions: null,
+    lastActivity: null,
+    quota: null,
+    tokensUsed: null,
+    api: null,
+    usage: null,
+    spend: null,
+    notes: [],
+  };
+}
+
+function readJson<T>(path: string): T | null {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Parse a JSON string that may be undefined; null on absence or parse error. */
+function safeJson(s: string | undefined): unknown {
+  if (!s) return null;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+
+/** Yield parsed JSON objects from a .jsonl file, skipping unparseable lines. */
+function* readJsonlSync(path: string): Generator<unknown> {
+  let content: string;
+  try {
+    content = readFileSync(path, "utf8");
+  } catch {
+    return;
+  }
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      yield JSON.parse(line);
+    } catch {
+      // partial/corrupt line — skip
+    }
+  }
+}
+
+/** Decode the (non-secret) claims payload of a JWT. Never returns the token. */
+function decodeJwtClaims(jwt: string): Record<string, unknown> | null {
+  try {
+    const part = jwt.split(".")[1];
+    if (!part) return null;
+    const padded = part + "=".repeat((4 - (part.length % 4)) % 4);
+    const json = Buffer.from(padded, "base64url").toString("utf8");
+    return JSON.parse(json) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+function listFilesRecursive(root: string, ext: string): string[] {
+  if (!existsSync(root)) return [];
+  const out: string[] = [];
+  const stack = [root];
+  while (stack.length) {
+    const cur = stack.pop() as string;
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const p = join(cur, e.name);
+      if (e.isDirectory()) stack.push(p);
+      else if (e.isFile() && e.name.endsWith(ext)) out.push(p);
+    }
+  }
+  return out;
+}
+
+function safeMtime(path: string): number {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function newestFile(paths: string[]): string | null {
+  let best: string | null = null;
+  let bestM = -1;
+  for (const p of paths) {
+    const m = safeMtime(p);
+    if (m > bestM) {
+      bestM = m;
+      best = p;
+    }
+  }
+  return best;
+}
+
+function latestMtimeIso(paths: string[]): string | null {
+  let m = 0;
+  for (const p of paths) m = Math.max(m, safeMtime(p));
+  return m > 0 ? new Date(m).toISOString() : null;
+}
+
+function strOr(v: unknown): string | null {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+function numOr(v: unknown): number | null {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}