ccdeck 3.29.11 → 3.31.0

package/src/server/claude-collector.mjs

@@ -0,0 +1,189 @@
+// Keeping claude-swap's store moving while the deck is looking at it.
+//
+// The accounts panel reads what claude-swap has already collected and fetches
+// nothing itself (claude-accounts.mjs). Left at that, the panel is only as live
+// as whatever else happens to be running, so each roster read — and the Usage
+// panel's refresh button, through requestCollection — asks claude-swap to
+// collect when its own plan says something is due, or when the active account's
+// numbers have aged past the point where the engine path would refresh them.
+// This module decides whether to ask, throttles the asking, and says when each
+// account will next be read.
+import { cswapBin } from "./cswap-install.mjs";
+import { runDetached } from "./exec.mjs";
+import { verdictQueue, verdictsNow } from "./claude-verdicts.mjs";
+
+// Nudging the collector.
+//
+// Two throttles, because the cost of asking is not the cost of fetching. When
+// claude-swap's plan says nothing is due, `cswap list` fetches nothing — the
+// spawn rate is bounded by the plan (one per 180-600s), not by how often we
+// ask. So asking often is cheap in requests and only costs a subprocess, and
+// asking often is exactly how `cswap watch` stays current: it re-asks every
+// three seconds and therefore collects the moment a plan comes due.
+//
+// The exception is an ask that changes nothing — a claim held by another
+// collector, a backoff, a plan that stays overdue. Repeating that every few
+// seconds is pure spawn churn, so a second, slower throttle applies until the
+// store actually moves.
+const NUDGE_EVERY_MS = 15_000;         // when the last ask produced new data
+const NUDGE_QUIET_MS = 60_000;         // when it did not
+let _lastNudge = 0;
+let _lastSeenFetch = 0;                // newest fetchedAt observed, in seconds
+
+// claude-swap's SERVE_TTL_S (180s) plus slack: below this age it serves from
+// the store and fetches nothing, so asking earlier only costs a subprocess.
+const FRESH_MIN_AGE_MS = 190_000;
+
+// claude-swap's RECENT_429_WINDOW_S. While a 429 is this recent, its own
+// congestion control is deliberately holding back, and so do we.
+const RECENT_429_MS = 3_600_000;
+
+/**
+ * Whether anything is waiting to be collected.
+ *
+ * Judged per account that actually exists, and an account counts as waiting in
+ * three cases:
+ *
+ *   - it has no usage row at all;
+ *   - it has a row whose fetchedAt is not a number. claude-swap writes a row
+ *     when an account is added and fills in the numbers when it first polls,
+ *     so "row exists" is not the same as "has been fetched" — and that is the
+ *     state a freshly added account sits in. Treating the row's existence as
+ *     proof of a fetch left a new account reading "never fetched" forever;
+ *   - its own schedule says the next poll is due.
+ *
+ * Rows are consulted only for accounts in the store. A removed account leaves
+ * its row behind, permanently overdue and impossible to collect because the
+ * account is gone — counting those meant something was always due and the
+ * collector was asked every minute for the rest of the session.
+ */
+export function collectionDue(rows, slots, now) {
+  for (const slot of slots) {
+    const r = rows[slot];
+    if (!r) return true;                                                  // never seen
+    if (typeof r.fetchedAt !== "number") return true;                     // seen, never fetched
+    if (typeof r.nextPollAt === "number" && r.nextPollAt * 1000 <= now) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether the engine path may be used to refresh this row now.
+ *
+ * claude-swap gates fetches two different ways (usage_store._row_eligible).
+ * On-demand surfaces — `cswap list`, status, switch — need the row to be BOTH
+ * stale and past its planned poll time. The auto engine needs it to be stale
+ * OR due, and stale means older than SERVE_TTL_S, which is 180 seconds. That
+ * OR is the whole difference: it is why a plan stretched out to 30 minutes
+ * still yields three-minute-old numbers to the engine, and why `cswap list`
+ * cannot do the same however often it is called.
+ *
+ * The plan is stretched for a reason, though, and one of those reasons must be
+ * respected rather than routed around: claude-swap runs AIMD congestion
+ * control on a budget it shares with every other machine holding the same
+ * account (POST_429_BACKOFF_MULT, RECENT_429_WINDOW_S). While an account is
+ * recovering from a 429, backing off IS the correct behaviour, and polling
+ * every 180 seconds through it would re-saturate exactly the window that needs
+ * to drain. So the engine path is used only for a healthy row: no live
+ * backoff, no failures, and no 429 seen within claude-swap's own recovery
+ * window.
+ *
+ * Exported for tests.
+ */
+export function freshenAllowed(row, now, recent429Ms = RECENT_429_MS) {
+  if (!row || typeof row.fetchedAt !== "number") return false;   // the list path owns this case
+  if (process.env.AGENTS_DECK_NO_FRESHEN === "1") return false;
+  if (typeof row.backoffUntil === "number" && row.backoffUntil * 1000 > now) return false;
+  if ((row.consecutiveFailures ?? 0) > 0) return false;
+  if (typeof row.last429At === "number" && now - row.last429At * 1000 < recent429Ms) return false;
+  return true;
+}
+
+/** freshenAllowed, plus old enough that asking would actually fetch. */
+export function freshenDue(row, now, { minAgeMs = FRESH_MIN_AGE_MS, recent429Ms = RECENT_429_MS } = {}) {
+  if (!freshenAllowed(row, now, recent429Ms)) return false;
+  // Younger than the serve TTL: claude-swap would answer from the store
+  // without fetching, so asking achieves nothing but a subprocess.
+  return now - row.fetchedAt * 1000 >= minAgeMs;
+}
+
+/**
+ * When this account's numbers will next be refreshed, in epoch ms.
+ *
+ * claude-swap's plan, except for a healthy active account, where the deck's
+ * own freshen tick gets there first. Exported for tests.
+ */
+export function nextReadAt(row, matches, fetchedAtMs, isActive, now) {
+  const planned = matches && typeof row?.nextPollAt === "number"
+    ? Math.round(row.nextPollAt * 1000)
+    : null;
+  const freshenAt = (isActive && fetchedAtMs != null && freshenAllowed(row, now))
+    ? fetchedAtMs + FRESH_MIN_AGE_MS
+    : null;
+  if (planned == null) return freshenAt;
+  if (freshenAt == null) return planned;
+  return Math.min(planned, freshenAt);
+}
+
+/**
+ * Keep the store moving while someone is looking at it.
+ *
+ * Without this the panel is only as live as whatever else is running: with no
+ * `cswap watch`/`auto`/TUI open, nothing ever writes the store and the panel
+ * shows frozen numbers while looking current.
+ *
+ * Two ways to ask, and the cheaper one is preferred:
+ *   - something is due by claude-swap's own plan → `cswap list`, the ordinary
+ *     on-demand pass every surface uses;
+ *   - nothing is due but the active account's numbers have aged past the serve
+ *     TTL → one `cswap auto --once --dry-run`, which is the engine path and so
+ *     is judged on staleness rather than on the plan.
+ *
+ * What dry run guarantees is narrower than the name suggests, and worth stating
+ * exactly: it never switches accounts and never writes autoswitch state — the
+ * switch call is unreachable behind its dry-run return. Its collect pass, on
+ * the other hand, runs unconditionally, which is the point: it fetches, writes
+ * usage rows, and can rotate and persist an OAuth token exactly as `cswap list`
+ * does. So this is not a read-only call; it is the same collection every other
+ * surface performs, minus the switch.
+ *
+ * Either way claude-swap decides whether a network call actually happens, and
+ * this is throttled on top of that.
+ *
+ * Answers whether it asked — true from the moment the throttle is spent, even
+ * when the ask joins a collection already running — which is what
+ * requestCollection reports to the refresh button.
+ */
+export function nudgeCollector(rows, slots, now, activeNum) {
+  // Did the last ask accomplish anything? Cheap proxy: the newest collection
+  // timestamp in the store.
+  let newest = 0;
+  for (const slot of slots) {
+    const f = rows[slot]?.fetchedAt;
+    if (typeof f === "number" && f > newest) newest = f;
+  }
+  const moved = newest > _lastSeenFetch;
+  _lastSeenFetch = Math.max(_lastSeenFetch, newest);
+
+  if (now - _lastNudge < (moved ? NUDGE_EVERY_MS : NUDGE_QUIET_MS)) return false;
+
+  const due = collectionDue(rows, slots, now);
+  const freshen = !due && freshenDue(rows[String(activeNum)], now);
+  if (!due && !freshen) return false;
+
+  _lastNudge = now;
+  // The due path asks for JSON and KEEPS it — see _verdicts, in
+  // claude-verdicts.mjs. The dry-run path stays detached: it is the engine's own
+  // collect pass, its JSON is a different shape, and nothing here reads it.
+  if (!due) {
+    cswapBin().then(bin => runDetached(bin, ["auto", "--once", "--dry-run", "--json"])).catch(() => {});
+    return true;
+  }
+  if (verdictQueue.busy()) return true;
+  // Fire-and-forget: this function is deliberately synchronous so callers never
+  // wait on it, and resolving the binary is the only async part. `run` rather
+  // than `runDetached` only so the output can be read; the caller is no more
+  // aware of it than before.
+  void verdictsNow();
+  return true;
+}

package/src/server/claude-dir.mjs

@@ -29,8 +29,12 @@ import { join, resolve, posix as posixPath, win32 as winPath } from "node:path";
  * The environment and the home directory are parameters purely so callers that
  * are already working from an injected environment can stay consistent with it;
  * every caller in the deck passes nothing and gets the real machine's answer.
+ * `platform` is the same kind of parameter: the answer for another platform's
+ * paths, joined with that platform's separator, which is what legacyDeckDir
+ * needs to be checked for a Mac on a Windows runner (#1711).
  */
-export function claudeConfigDir(env = process.env, home = homedir()) {
+export function claudeConfigDir(env = process.env, home = homedir(), platform = process.platform) {
+  const { join, resolve } = platform === "win32" ? winPath : posixPath;
   const override = env.CLAUDE_CONFIG_DIR?.trim();
   return override ? resolve(override) : join(home, ".claude");
 }
@@ -227,8 +231,8 @@ function ccPathHash(s) {
 
 /** Encode an absolute path the way CC stores it under
  *  ~/.claude/projects/<slug>/, so a scan looks in the directory CC actually
- *  wrote — index.mjs's auto-memory scan, and the Projects rollup reading a
- *  transcript's folder back out of it (account-projects.mjs).
+ *  wrote — memory-files.mjs's auto-memory scan, and the Projects rollup
+ *  reading a transcript's folder back out of it (account-projects.mjs).
  *
  *  CC flattens *every* non-alphanumeric character to "-", not just the path
  *  separators and the Windows drive colon this used to replace. Dots are the

package/src/server/claude-identity.mjs

@@ -16,10 +16,11 @@
 // boot-module-graph.test.ts, which now asserts that src/server has no cycles at
 // all rather than trying to police the call sites of one.
 //
-// This file imports only leaves — exec.mjs and claude-dir.mjs have no relative
-// imports of their own — so it can be reached from either side without closing
-// anything. Both functions are re-exported from cswap-admin.mjs, which is where
-// their callers and their tests already look for them.
+// Nothing this file imports can lead back to it — claude-dir.mjs has no
+// relative imports of its own, and exec.mjs has only the leaves lifted out of
+// it — so it can be reached from either side without closing anything. Both
+// functions are re-exported from cswap-admin.mjs, which is where their callers
+// and their tests already look for them.
 import { pathLookup, run } from "./exec.mjs";
 import { claudeCliCandidates } from "./claude-dir.mjs";
 import { existsSync } from "node:fs";

package/src/server/claude-reset-credits.mjs

@@ -0,0 +1,130 @@
+// Claude's saved limit resets — "Reset for free" in Claude's Settings → Usage —
+// read out of the `cedar_ember` block of Anthropic's usage response.
+//
+// WHAT THEY ARE, AND WHAT THEY ARE NOT. A grant is a coupon Anthropic hands out
+// (a model launch, a promotion) that clears a rate-limit window on demand. It
+// has nothing to do with the `resets_at` timestamps on `five_hour` and
+// `seven_day`: those say when a window rolls over by itself, and a panel that
+// read one as the other would promise a reset the account does not have.
+//
+// THE DECK ONLY COUNTS THEM. Redeeming one is a POST to a different endpoint,
+// and nothing in ccdeck makes it — spending a one-off reset is the user's
+// decision, taken in Claude itself. So nothing here reads a grant's `id`, its
+// `label`, `next_grant_id` or `event_props`: an id is a redemption handle, and
+// a value that is never read cannot end up in a response, a log line or a test
+// fixture. What survives the parse is a count and two instants per grant.
+//
+// FAIL CLOSED. The shape below is Claude Code's own (its zod schema for this
+// block, read out of the 2.1.283 binary), and it can change without notice. A
+// block that does not look like it is not evidence of zero resets, and a grant
+// that does not look like one is not evidence of a reset, so either is dropped
+// rather than guessed at: a missing row is a small loss, a count the account
+// cannot actually spend is the confidently wrong number this panel exists not
+// to show. CodexBar, which shipped this first, draws the same lines.
+//
+// Pure, and a leaf: quota.mjs is the only caller, and the tests reach every
+// rule here without a network, a credential or a clock of their own.
+
+/**
+ * More grants than this in one block is not an inventory, it is a payload
+ * nobody has seen. Every grant observed so far holds one reset.
+ */
+export const MAX_GRANT_RECORDS = 200;
+
+/**
+ * More resets than this available at once reads as a malformed block rather
+ * than a generous one, and the row would print it with a straight face.
+ */
+export const MAX_AVAILABLE_RESETS = 50;
+
+const isCount = (v) => Number.isInteger(v) && v >= 0;
+
+/**
+ * A grant's start or end as epoch milliseconds: `null` when it has none, and
+ * `undefined` when it has one nobody can read. The difference matters — an
+ * absent bound is an open one, an unreadable bound is a malformed grant, and
+ * treating the second as the first would count a reset that may have lapsed.
+ */
+function bound(v) {
+  if (v === undefined || v === null) return null;
+  if (typeof v !== "string") return undefined;
+  const t = Date.parse(v);
+  return Number.isFinite(t) ? t : undefined;
+}
+
+/** One grant, reduced to what counting needs, or null when it is malformed. */
+function readGrant(g) {
+  if (!g || typeof g !== "object" || Array.isArray(g)) return null;
+  if (!isCount(g.resets_left)) return null;
+  // `resets_total` is optional, but when it is sent it has to be able to
+  // contain `resets_left`. A grant that has more left than it ever held is
+  // saying something false about at least one of the two.
+  if (g.resets_total !== undefined && g.resets_total !== null
+      && (!isCount(g.resets_total) || g.resets_total < g.resets_left)) return null;
+  // Required, although Claude Code defaults it to false: a grant whose pause
+  // state is unknown might be paused, and a paused reset cannot be used.
+  if (typeof g.paused !== "boolean") return null;
+  const startsAt = bound(g.starts_at);
+  const endsAt = bound(g.ends_at);
+  if (startsAt === undefined || endsAt === undefined) return null;
+  return { resetsLeft: g.resets_left, paused: g.paused, startsAt, endsAt };
+}
+
+/**
+ * The grants in a `cedar_ember` block, or null when the block says nothing
+ * this deck can trust.
+ *
+ * Null covers every "we do not know": no block at all (a response to a request
+ * that did not ask, or from a server that stopped sending it), `eligible` not
+ * exactly `true` — which is also how the endpoint answers a client it does not
+ * recognise, with `ineligible_reason: "surface"` — and a grant list that is not
+ * a list or is implausibly long. An eligible block with no grants is an empty
+ * list, which is a real answer: zero.
+ *
+ * A single malformed grant is dropped without hiding the others, the way both
+ * Claude Code and CodexBar treat one.
+ */
+export function readResetGrants(block) {
+  if (!block || typeof block !== "object" || Array.isArray(block)) return null;
+  if (block.eligible !== true) return null;
+  const raw = block.grants ?? [];
+  if (!Array.isArray(raw) || raw.length > MAX_GRANT_RECORDS) return null;
+  return raw.map(readGrant).filter(Boolean);
+}
+
+/**
+ * What the Usage panel shows, from grants readResetGrants accepted: how many
+ * resets can be spent at `now`, and when the first of them lapses.
+ *
+ * A grant counts when it is not paused, has resets left, has started and has
+ * not ended. `usable_now` is deliberately not consulted: Claude sets it false
+ * while the account is under its limit, because a reset only redeems against a
+ * window that is full, and a reset saved for later is still a reset the user
+ * owns.
+ *
+ * `nextExpiryAt` is epoch milliseconds, like the Codex row's, and null when no
+ * counted grant has an end.
+ *
+ * Recomputed at every read rather than frozen at fetch time, because the
+ * inventory is held between fetches: a grant that ends while it is held has to
+ * stop being counted when it ends, not when the next fetch happens to land.
+ */
+export function availableResetCredits(grants, now) {
+  if (!Array.isArray(grants)) return null;
+  let availableCount = 0;
+  let nextExpiryAt = null;
+  for (const g of grants) {
+    if (g.paused || g.resetsLeft <= 0) continue;
+    if (g.startsAt !== null && g.startsAt > now) continue;
+    if (g.endsAt !== null && g.endsAt <= now) continue;
+    availableCount += g.resetsLeft;
+    if (g.endsAt !== null && (nextExpiryAt === null || g.endsAt < nextExpiryAt)) nextExpiryAt = g.endsAt;
+  }
+  if (availableCount > MAX_AVAILABLE_RESETS) return null;
+  return { availableCount, nextExpiryAt };
+}
+
+/** Both of the above, for a response read once and shown straight away. */
+export function resetCreditsFrom(block, now) {
+  return availableResetCredits(readResetGrants(block), now);
+}

package/src/server/claude-verdicts.mjs

@@ -0,0 +1,174 @@
+// claude-swap's own verdict on each account, asked for rather than read.
+//
+// Everything else the accounts panel shows is read straight out of the store
+// claude-swap writes (claude-accounts.mjs). The verdict is the one thing that
+// is not in a file: it is what `cswap list --json` answers when asked, so it
+// comes with a subprocess, a queue that keeps that to one child at a time, and a
+// cache with its own clock. claude-accounts.mjs puts the cached verdict on each
+// roster row and asks for a new one when its collector nudge finds a
+// collection due.
+import { cswapBin } from "./cswap-install.mjs";
+import { run } from "./exec.mjs";
+// The identity of one account, spelled once. claude-swap keys on `(email,
+// organizationUuid)`; the verdict cache files each verdict under the pair it was
+// collected for, and lan-copies.mjs (which lan-sync.mjs re-exports) matches
+// accounts across two stores on the same pair. Nothing either of them imports
+// reaches this file, so the edge closes no cycle.
+import { accountKey } from "./lan-sync.mjs";
+
+/**
+ * What claude-swap says about each slot, in its own words.
+ *
+ * `usage.json` records numbers and a failure COUNTER; `cswap list --json`
+ * records a per-slot VERDICT, and the two answer different questions. Measured
+ * on the machine this was written for, at one instant, for the same account:
+ *
+ *   usage.json  ->  consecutiveFailures: 0, lastError: null
+ *   cswap list  ->  usageStatus: "no_credentials"
+ *
+ * Three verdicts, three different things for a person to do — `no_credentials`
+ * is an account to receive or re-add, `relogin_required` is one to sign into,
+ * `keychain_unavailable` is not about the account at all but about the process
+ * asking. The counter can tell none of them apart, and for two of the three it
+ * reads zero.
+ *
+ * WHERE IT COMES FROM COSTS NOTHING EXTRA. nudgeCollector already spawns
+ * `cswap list` when a collection is due, and threw the output away. It now asks
+ * for `--json` and keeps the verdicts. Still not awaited by anyone — the nudge
+ * stays synchronous for its callers — and still one child at a time.
+ */
+let _verdicts = { at: 0, byNum: {}, identities: {} };
+/** Stale after this, because a verdict that outlives its cause is worse than no
+ *  verdict: "no credentials" under an account somebody has since signed into is
+ *  a sentence that sends them to fix what is already fixed. */
+const VERDICT_TTL_MS = 10 * 60_000;
+/** Long enough for a cold collection over a slow network, short enough that a
+ *  wedged claude-swap does not hold a child for the rest of the day. */
+const VERDICT_TIMEOUT_MS = 90_000;
+/** Run one `cswap list --json` at a time. A post-write question must start
+ * after any older collection has finished; routine readers can share the
+ * latest pending answer without starting another slow collection. */
+export function createVerdictQueue(collect) {
+  let pending = null;
+  return {
+    ask({ fresh = false } = {}) {
+      if (pending && !fresh) return pending;
+      const previous = pending;
+      // Start the first poll immediately: requestCollection promises the UI that
+      // its refresh has started before it returns. Only subsequent fresh polls
+      // wait for the earlier snapshot to finish.
+      let next;
+      if (previous) next = previous.then(collect, collect);
+      else {
+        try { next = Promise.resolve(collect()); }
+        catch (error) { next = Promise.reject(error); }
+      }
+      pending = next;
+      void next.then(
+        () => { if (pending === next) pending = null; },
+        () => { if (pending === next) pending = null; },
+      );
+      return next;
+    },
+    busy() { return pending !== null; },
+  };
+}
+
+/**
+ * Ask claude-swap about one account RIGHT NOW, rather than reading the cache.
+ *
+ * The cached verdicts are ten minutes old at worst, which is right for a label
+ * and wrong for a decision that writes a credential: somebody who signed in two
+ * minutes ago still reads as `no_credentials` there, and acting on that would
+ * replace the login they just created with a peer's.
+ *
+ * Matched on IDENTITY rather than on the slot number, because a number is a
+ * position in one machine's store and the caller is holding an account.
+ *
+ * Returns null when the question cannot be answered — no claude-swap, a refusal,
+ * an account it does not know. Null is not `no_credentials`, and the one caller
+ * treats it as "do not act".
+ */
+export async function verdictNow(email, org, { runner = run, bin = cswapBin } = {}) {
+  const want = String(email ?? "").trim().toLowerCase();
+  if (!want) return null;
+  const all = await verdictsNow({ runner, bin, fresh: true });
+  return all?.find(a => a.email === want && a.org === (org ?? ""))?.status ?? null;
+}
+
+/**
+ * Every account's verdict from ONE `cswap list --json`, as `{ email, org,
+ * status, active }` rows (email lower-cased, status null when claude-swap gave none),
+ * or null when the question could not be asked at all.
+ *
+ * For a caller holding several identities at once — a round that imported
+ * three logins asks once, not three times, since each ask is a full usage
+ * collection that can take a minute on a cold network.
+ */
+async function collectVerdicts({ runner, bin }) {
+  try {
+    const out = await runner(await bin(), ["list", "--json"], { timeout: VERDICT_TIMEOUT_MS });
+    if (!out?.ok) return null;
+    const d = JSON.parse(out.stdout);
+    // The same freshly-read answer feeds the cache the panel draws from, since
+    // it cost a subprocess either way.
+    const byNum = readVerdicts(out.stdout);
+    const identities = {};
+    for (const a of Array.isArray(d?.accounts) ? d.accounts : []) {
+      if (Number.isInteger(a?.number) && typeof a?.email === "string" && a.email.trim()) {
+        identities[String(a.number)] = accountKey(a.email, a.organizationUuid);
+      }
+    }
+    _verdicts = { at: Date.now(), byNum, identities };
+    return (Array.isArray(d?.accounts) ? d.accounts : []).map(a => ({
+      number: a?.number,
+      email: String(a?.email ?? "").trim().toLowerCase(),
+      org: a?.organizationUuid ?? "",
+      status: typeof a?.usageStatus === "string" ? a.usageStatus : null,
+      // For the account Claude Code is signed in as, claude-swap reads the
+      // LIVE credential, not the stored copy — so its verdict there is about
+      // the live login. See checkImports.
+      active: a?.active === true,
+    }));
+  } catch { return null; }
+}
+
+export const verdictQueue = createVerdictQueue(() => collectVerdicts({ runner: run, bin: cswapBin }));
+
+/** Routine readers share a collection; post-write callers wait for any older
+ * collection and start a new one, so they never inspect the pre-write store. */
+export function verdictsNow({ runner = run, bin = cswapBin, fresh = false } = {}) {
+  // Tests and callers supplying their own runner must receive their own answer.
+  if (runner !== run || bin !== cswapBin) return collectVerdicts({ runner, bin });
+  return verdictQueue.ask({ fresh });
+}
+
+/** claude-swap's verdict for a slot, or null when there is none fresh enough. */
+export function verdictFor(num, now, email, org) {
+  return cachedVerdictFor(_verdicts, num, now, email, org);
+}
+
+/** Only attach a cached slot verdict to the identity it was collected for. */
+export function cachedVerdictFor(cache, num, now, email, org) {
+  if (now - cache.at > VERDICT_TTL_MS) return null;
+  const identity = accountKey(email, org);
+  if (cache.identities[String(num)] !== identity) return null;
+  const v = cache.byNum[String(num)];
+  return typeof v === "string" && v !== "" ? v : null;
+}
+
+/** Read the verdicts out of a `cswap list --json` payload. Tolerant by
+ *  construction: this is another tool's output, and a shape we do not recognise
+ *  means no verdicts rather than a thrown boot. */
+export function readVerdicts(stdout) {
+  try {
+    const d = JSON.parse(stdout);
+    const out = {};
+    for (const a of Array.isArray(d?.accounts) ? d.accounts : []) {
+      if (typeof a?.number === "number" && typeof a?.usageStatus === "string") {
+        out[String(a.number)] = a.usageStatus;
+      }
+    }
+    return out;
+  } catch { return {}; }
+}