@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/auth-health.js

@@ -1,21 +1,3 @@
-/**
- * Live auth-health: does an agent account's stored credential actually complete
- * an authenticated request right now?
- *
- * The rest of the CLI reports "signed in" from a local heuristic — a credential
- * file is present and its email decodes — which cannot distinguish a good token
- * from a revoked-but-unexpired one. This module completes a real request per
- * (agent, account) and records the verdict in a small cache that `agents view`
- * (per-version chip), `agents fleet status` (the per-host Auth column, via
- * {@link summarizeHostAuth}), and the run rotation all read. The writers are
- * the daemon (a periodic local refresh) and `agents fleet ping` (which also
- * fans out to write remote hosts' rows into the local cache); everyone else
- * reads.
- *
- * The network probes themselves live in lib/usage.ts (where the per-provider
- * token loaders + endpoints already are); this module classifies their result,
- * covers the best-effort (non-networked) providers, and owns the cache.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { ALL_AGENT_IDS, getAccountInfo } from './agents.js';
@@ -28,43 +10,28 @@ import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic
 import { selfConfiguredDeviceRole } from './device-config.js';
 import { mayIssueUsageEndpointProbe, trySpendUsageApiCall } from './usage-refresh.js';
 import { machineId } from './machine-id.js';
-/** Maximum age of an auth verdict used for automatic routing decisions. */
 export const AUTH_PROBE_MAX_AGE_MS = 20 * 60_000;
-/** Agents with a live network probe wired up today. The rest are best-effort. */
 export const LIVE_PROBE_AGENTS = new Set(['claude', 'kimi', 'droid']);
-// ---------------------------------------------------------------------------
-// Pure classifiers / render (unit-tested; no network, no fs)
-// ---------------------------------------------------------------------------
-/** Map an HTTP status from a live probe to a verdict. Probe 429 never yields `rate_limited` (PHNX-4051). */
 export function classifyHttpStatus(status) {
     if (status >= 200 && status < 300)
         return 'live';
     if (status === 401 || status === 403)
         return 'revoked';
-    // 429 is probe throttling, not an account throttle — the account's real
-    // throttle state comes from the usage snapshot (deriveUsageStatusFromSnapshot).
-    // Treating it as `rate_limited` let a burst-throttled endpoint mark every
-    // account LIMITED. See mergeAuthHealthEntries for the keep-or-unverified path.
     if (status === 429)
         return 'error';
     return 'error';
 }
-/** Turn a raw provider probe (from usage.ts) into a verdict. */
 export function verdictFromProbe(probe) {
     if (probe.token === 'missing')
         return 'unconfigured';
     if (probe.token === 'expired')
         return 'expired';
-    // Setup-token can run inference but cannot read usage (RUSH-2392). That 403
-    // is NOT a revocation — classifying it as revoked made the best-provisioned
-    // headless accounts look the least healthy on `agents view` / fleet ping.
     if (probe.reason === 'usage_scope')
         return 'unverified';
     if (probe.status == null)
         return 'error';
     return classifyHttpStatus(probe.status);
 }
-/** A short human detail line for a probe result (rendered under --verbose). */
 export function probeDetail(probe) {
     if (probe.reason === 'usage_scope') {
         return probe.error ?? USAGE_HEADLESS_SCOPE_MARKER;
@@ -78,20 +45,18 @@ export function probeDetail(probe) {
     return undefined;
 }
 const VERDICT_GLYPHS = {
-    live: '●', // ●
-    revoked: '○', // ○
-    expired: '○', // ○
-    rate_limited: '◐', // ◐
-    unverified: '◐', // ◐
-    no_evidence: '◌', // ◌ — credential present, no evidence either way
-    unconfigured: '·', // ·
-    error: '·', // ·
+    live: '●',
+    revoked: '○',
+    expired: '○',
+    rate_limited: '◐',
+    unverified: '◐',
+    no_evidence: '◌',
+    unconfigured: '·',
+    error: '·',
 };
-/** Uncolored glyph for a verdict (color is applied by the caller). */
 export function verdictGlyph(verdict) {
     return VERDICT_GLYPHS[verdict] ?? '·';
 }
-/** One-word label for matrices/verbose output. */
 export function verdictLabel(verdict) {
     switch (verdict) {
         case 'live': return 'live';
@@ -121,15 +86,6 @@ export function summarizeVerdicts(verdicts) {
     }
     return { live, present, bad, warn, total: verdicts.length };
 }
-/**
- * Color for a single verdict in the per-account (`--verbose`) breakdown. This is
- * the one source of truth shared with {@link authCellColor} so the matrix and the
- * account list can never drift — they did: the matrix painted `expired` yellow
- * while the verbose list painted it *red* (lumped with revoked), directly against
- * the {@link VerdictSummary} contract. Red is reserved for `revoked` (the only
- * "re-login now"); `unverified` is a neutral signed-in state (gray);
- * `expired`/`rate_limited`/`error` are soft (yellow).
- */
 export function verdictColor(verdict) {
     switch (verdict) {
         case 'live': return 'green';
@@ -137,16 +93,9 @@ export function verdictColor(verdict) {
         case 'unverified': return 'gray';
         case 'no_evidence': return 'gray';
         case 'unconfigured': return 'dim';
-        default: return 'yellow'; // expired / rate_limited / error — soft, self-healing/indeterminate
+        default: return 'yellow';
     }
 }
-/**
- * Color for a matrix cell that rolls up several accounts. Red only when a token
- * was genuinely rejected (`revoked`); yellow for soft/expired; green when at least
- * one account is live-verified and none are soft/revoked; gray when accounts are
- * present but unverifiable (codex/grok) — never the alarming yellow the old
- * renderer used, which made a fully-logged-in fleet read as half-broken.
- */
 export function authCellColor(summary) {
     if (summary.total === 0)
         return 'dim';
@@ -156,22 +105,11 @@ export function authCellColor(summary) {
         return 'yellow';
     if (summary.live > 0)
         return 'green';
-    return 'gray'; // all present/unverifiable — signed in, neutral
+    return 'gray';
 }
-/** Verdicts that mean "this token was rejected by the server — re-login required". */
 export function isDeadVerdict(verdict) {
     return verdict === 'revoked';
 }
-/**
- * Roll every cached (agent, version) row for one host into a {@link HostAuthSummary}
- * plus the age of its stalest entry. Pure — reads the map the caller already
- * loaded via {@link readAuthHealthCache}, so `fleet status` renders the Auth
- * column without any network probe. A host with no cached rows yields an empty
- * summary (total 0), which the renderer shows as "—".
- *
- * Keys are `host:agent:version` ({@link authCacheKey}); we match on the `host:`
- * prefix so agent/version segments can never be mistaken for a host.
- */
 export function summarizeHostAuth(cache, host) {
     const prefix = `${host}:`;
     let live = 0, present = 0, degraded = 0, revoked = 0, total = 0;
@@ -179,9 +117,6 @@ export function summarizeHostAuth(cache, host) {
     for (const [key, health] of Object.entries(cache)) {
         if (!key.startsWith(prefix))
             continue;
-        // `unconfigured` = no credential at all — not a probed account. Writers
-        // already drop these before they reach the cache; skip here too so a stray
-        // one never counts toward total or the freshness age (belt-and-suspenders).
         if (health.verdict === 'unconfigured')
             continue;
         total++;
@@ -191,23 +126,22 @@ export function summarizeHostAuth(cache, host) {
                 break;
             case 'unverified':
                 present++;
-                break; // signed in, no probe — benign
+                break;
             case 'no_evidence':
                 present++;
-                break; // credential present, no evidence — benign
+                break;
             case 'revoked':
                 revoked++;
-                break; // server said no — re-login
+                break;
             default:
                 degraded++;
-                break; // expired / rate_limited / error — soft
+                break;
         }
         if (oldest === null || health.checkedAt < oldest)
             oldest = health.checkedAt;
     }
     return { live, present, degraded, revoked, total, oldestCheckedAt: oldest };
 }
-/** Human "3m ago" style age for a checkedAt timestamp. */
 export function formatCheckedAge(checkedAt, now = Date.now()) {
     const secs = Math.max(0, Math.round((now - checkedAt) / 1000));
     if (secs < 60)
@@ -220,47 +154,18 @@ export function formatCheckedAge(checkedAt, now = Date.now()) {
         return `${hours}h ago`;
     return `${Math.round(hours / 24)}d ago`;
 }
-// ---------------------------------------------------------------------------
-// Cache identity + IO (single source of truth read by view/fleet/rotation)
-// ---------------------------------------------------------------------------
-/**
- * Human account label for display (email, else id). NOT used in the cache key —
- * two installs on one host can hold the same account with independently valid
- * tokens, so the key is keyed by version (below), not account.
- */
 export function authAccountLabel(info) {
     return info?.email || info?.accountId || info?.userId || undefined;
 }
-/** Cache key: one entry per install — (host, agent, version). Unique per token. */
 export function authCacheKey(host, agent, version) {
     return `${host}:${agent}:${version}`;
 }
-/**
- * Host-independent identity of one probe target — the (agent, version) pair
- * {@link authCacheKey} is keyed by. The separator cannot appear in either half,
- * so an agent id can never run into a version the way a `:` join allows.
- */
 export function authTargetKey(agent, version) {
     return `${agent}@${version}`;
 }
-/**
- * The `version` slot an account SLOT occupies in the auth cache and the probe
- * rows: `slot:<accountId>`. A slot is a HOME-shaped dir, not an installed
- * version, so it needs its own key or its verdict would collide with (or be
- * silently dropped in favor of) whichever version home the account's label
- * happened to match.
- */
 export function slotAuthVersionKey(accountId) {
     return `slot:${accountId}`;
 }
-/**
- * Every registered account's slot on this device (PHNX-3940 T1), as probe
- * targets. Before this the probe walked `listInstalledVersions` only, so a
- * slot's verdict was never re-derived after `accounts add/login` wrote it —
- * a slot re-materialized as `unconfigured` while the device doc was unreadable
- * stayed MISSING forever even though its login was live. A slot whose dir is
- * gone is skipped: there is nothing to probe and the row would only say so.
- */
 export function enumerateSlotInstalls(meta, agentIds) {
     const byId = new Map(listNativeAccounts(meta).map((account) => [account.id, account]));
     const out = [];
@@ -274,12 +179,6 @@ export function enumerateSlotInstalls(meta, agentIds) {
     }
     return out;
 }
-/**
- * Every (agent, version) home the local auth probe covers on this device —
- * installed version homes plus account slots. {@link probeLocalFleetAuth} probes
- * exactly this set, so it is also the answer to "which cached rows are still
- * backed by something on disk" (PHNX-4051).
- */
 function enumerateLocalAuthInstalls(meta, agentIds) {
     const installs = [];
     for (const agent of agentIds) {
@@ -291,19 +190,12 @@ function enumerateLocalAuthInstalls(meta, agentIds) {
         installs.push(slot);
     return installs;
 }
-/**
- * {@link authTargetKey} for every local probe target — what a cached row must
- * match to still be about this device. A row outside it is an ORPHAN: its home
- * was uninstalled, so nothing will ever re-probe it and its `checkedAt` is
- * frozen at whatever the last probe left (PHNX-4051).
- */
 export function localAuthTargetKeys(agentIds = ALL_AGENT_IDS) {
     return new Set(enumerateLocalAuthInstalls(readMeta(), agentIds).map((i) => authTargetKey(i.agent, i.version)));
 }
 function cacheFilePath() {
     return path.join(getCacheDir(), '.auth-health.json');
 }
-/** Read the whole cache (best-effort; a corrupt/missing file yields an empty map). */
 export function readAuthHealthCache() {
     try {
         const parsed = JSON.parse(fs.readFileSync(cacheFilePath(), 'utf-8'));
@@ -311,19 +203,12 @@ export function readAuthHealthCache() {
             return parsed.entries;
     }
     catch {
-        // missing or corrupt — treat as empty
     }
     return {};
 }
-/** Read one entry, or null. */
 export function readAuthHealth(host, agent, version) {
     return readAuthHealthCache()[authCacheKey(host, agent, version)] ?? null;
 }
-/**
- * Split a cache key back into the install it names, for one host. Returns null
- * for a key that belongs to another host or does not name a known agent — the
- * one place the `host:agent:version` join is undone.
- */
 function parseAuthCacheKey(key, host) {
     const prefix = `${host}:`;
     if (!key.startsWith(prefix))
@@ -337,7 +222,6 @@ function parseAuthCacheKey(key, host) {
         return null;
     return { agent: agent, version: identity.slice(separator + 1) };
 }
-/** Reconstruct one host's published probe rows for a lease waiter/CLI reader. */
 export function readFleetAuthRows(host) {
     const rows = [];
     for (const [key, health] of Object.entries(readAuthHealthCache())) {
@@ -354,15 +238,6 @@ export function readFleetAuthRows(host) {
     }
     return rows;
 }
-/**
- * Merge entries into the cache. An incoming `error` verdict (a network blip,
- * not a server rejection) is indeterminate, so it must NOT clobber a prior
- * known verdict — otherwise one 8s timeout flips a `live` chip to `error`,
- * exactly the "cry wolf" the verdict model avoids for `expired`. This is the
- * behaviour promised by the `error` doc on AuthVerdict ("keep the last known
- * one"). A probe-throttled 429 (detail `probe throttled (HTTP 429)`) keeps the
- * previous real verdict when one exists within {@link AUTH_PROBE_MAX_AGE_MS},
- * otherwise becomes `unverified` (PHNX-4051). Pure, so it's unit-tested directly. */
 export function mergeAuthHealthEntries(current, incoming) {
     const merged = { ...current };
     for (const [key, health] of Object.entries(incoming)) {
@@ -372,24 +247,16 @@ export function mergeAuthHealthEntries(current, incoming) {
             const fresh = !!prev && prev.verdict !== 'error' && prev.verdict !== 'unconfigured'
                 && (health.checkedAt - prev.checkedAt < AUTH_PROBE_MAX_AGE_MS);
             if (fresh)
-                continue; // keep previous real verdict
+                continue;
             merged[key] = { ...health, verdict: 'unverified' };
             continue;
         }
         if (health.verdict === 'error' && merged[key])
-            continue; // keep last known
+            continue;
         merged[key] = health;
     }
     return merged;
 }
-/**
- * Merge one or more entries into the cache (best-effort write).
- *
- * `drop` removes entries the writer knows are gone — it runs on the PRE-merge
- * cache, so an incoming row always wins over a drop of the same key and the two
- * can never fight. Only a writer that knows the full truth for the keys it drops
- * may pass one (see {@link writeFleetAuthRows}).
- */
 export function writeAuthHealthEntries(entries, drop) {
     try {
         const target = cacheFilePath();
@@ -407,19 +274,8 @@ export function writeAuthHealthEntries(entries, drop) {
         });
     }
     catch {
-        // best-effort; a failed write just means the next reader falls back to heuristics
     }
 }
-// ---------------------------------------------------------------------------
-// The probe (writer side)
-// ---------------------------------------------------------------------------
-/**
- * A usage snapshot this recent is live proof the account's shared setup-token
- * works: the snapshot only exists because an authenticated `/oauth/usage`
- * request succeeded. Matches the periodic tick's own probe window
- * (AUTH_PROBE_MAX_AGE_MS in daemon-ticks.ts — not imported to avoid a cycle;
- * a drift here only widens/narrows evidence freshness, never correctness).
- */
 const FRESH_USAGE_VERDICT_MAX_AGE_MS = 20 * 60_000;
 /**
  * A `live` verdict derived from the account's usage cache instead of a second
@@ -444,12 +300,6 @@ function verdictFromFreshUsage(usageKey, signedIn, now) {
     const capturedAt = snapshot?.capturedAt?.getTime();
     if (!capturedAt || now - capturedAt >= FRESH_USAGE_VERDICT_MAX_AGE_MS)
         return null;
-    // A `sync`-sourced snapshot arrived from ANOTHER box's poller over the fleet
-    // store — it proves the shared setup-token works SOMEWHERE, not that THIS box
-    // can authenticate (PHNX-4116). Deriving `live` from it is exactly the false
-    // "we did not look here, but a synced file is fresh, so call it live" the
-    // ticket removes. Only a reading THIS box captured itself (statusline/poll)
-    // is admissible live evidence.
     if (snapshot?.freshness?.source === 'sync')
         return null;
     const ageMin = Math.max(1, Math.round((now - capturedAt) / 60_000));
@@ -476,12 +326,6 @@ export async function probeAuthHealth(agent, home, opts) {
             role: selfConfiguredDeviceRole(),
             forceLive: opts?.forceLive,
         })) {
-            // A worker's setup-token cannot read the usage endpoint (RUSH-2392), so this
-            // box has no probe evidence for the account. This is NOT `unverified` (which
-            // conflated it with codex/grok's permanent no-probe-endpoint state): it is
-            // "we did not look here". A worker never publishes it — probeLocalFleetAuth
-            // drops `no_evidence` like `unconfigured` — so the account's facts come from
-            // token presence + recorded run outcomes instead (PHNX-4116).
             return {
                 verdict: 'no_evidence',
                 checkedAt,
@@ -507,36 +351,10 @@ export async function probeAuthHealth(agent, home, opts) {
     const info = opts?.info !== undefined ? opts.info : await getAccountInfo(agent, home).catch(() => null);
     return { verdict: info?.signedIn ? 'unverified' : 'unconfigured', checkedAt };
 }
-/**
- * Collapse installs so a live auth probe fires ONCE per (agent, account) rather
- * than once per version home.
- *
- * Several version homes signed into the same provider account share one OAuth
- * rate limit, so probing each of them concurrently — which the daemon did every
- * three minutes across every installed home (RUSH-2111) — raced that limit into
- * a 429 storm that then parked the whole box behind a `Retry-After` penalty (the
- * incident {@link file:./usage-backoff.ts} was written to survive; this removes
- * its cause). Grouping by account means N homes on one account issue ONE request.
- *
- * `isMergeable` scopes the dedup to the installs it actually helps: only agents
- * that make a network probe ({@link LIVE_PROBE_AGENTS}) can 429, so only they are
- * merged. A best-effort agent (its verdict is a cheap local file read, no rate
- * limit) is left per-install — collapsing it would gain nothing and could
- * silently override one home's local `signedIn` verdict with another's. Installs
- * with no resolvable account label, or that `isMergeable` rejects, are never
- * merged: each becomes its own group keyed by version, preserving the old
- * per-install probe (also the `unconfigured` case dropped downstream). Pure: no
- * fs, no network, so the dedup decision is unit-tested directly.
- */
-/** Small fixed delay between live probes so one box no longer fires 16 requests in 4s (PHNX-4051). */
 const AUTH_PROBE_SPACING_MS = 150;
 export function groupFleetAuthInstalls(installs, isMergeable = () => true) {
     const groups = new Map();
     for (const inst of installs) {
-        // Prefer stable accountId (identity) — a version home and its slot share the
-        // same id, so they collapse to ONE probe per identity (PHNX-4051). Fallback
-        // to the display label when no id is known. The `id:`/`acct:`/`ver:` tokens
-        // keep the three branches disjoint.
         const mergeKey = inst.accountId
             ? `id:${inst.accountId}`
             : inst.account
@@ -553,23 +371,8 @@ export function groupFleetAuthInstalls(installs, isMergeable = () => true) {
     }
     return [...groups.values()];
 }
-/**
- * Enumerate every installed (agent, version) on THIS host and return one row per
- * install (installs with no credential at all are dropped). Shared by
- * `agents fleet ping --local` and the daemon refresh.
- *
- * The live network probe is deduped by account: homes sharing one provider
- * account are probed ONCE and the verdict is fanned out to each home's row, so
- * the daemon's every-3-minute refresh can no longer fire concurrent same-account
- * requests and self-inflict a 429 (RUSH-2111). Each home still gets its own cache
- * row (the cache key is per-version by design — see {@link authCacheKey}).
- */
 export async function probeLocalFleetAuth(opts) {
     const agentIds = opts?.agents ?? ALL_AGENT_IDS;
-    // Enumerate every install AND every account slot on this device, then resolve
-    // each one's account label. getAccountInfo is a local credential-file read
-    // (no network), so this fan-out is cheap and cannot contribute to the rate
-    // limit the probe grouping below exists to avoid.
     const { findNativeAccountByIdentity } = await import('./account-registry.js');
     const meta = readMeta();
     const installs = enumerateLocalAuthInstalls(meta, agentIds).map((inst) => ({ ...inst, info: null }));
@@ -578,14 +381,8 @@ export async function probeLocalFleetAuth(opts) {
         inst.account = authAccountLabel(inst.info);
     }));
     for (const inst of installs) {
-        // A slot already knows its account; a version home is joined by identity.
         inst.accountId ??= findNativeAccountByIdentity(meta, inst.agent, inst.info)?.id;
     }
-    // Probe once per (agent, identity) — but only for the network-probing agents
-    // that can actually 429; best-effort agents stay per-install (see
-    // groupFleetAuthInstalls). Groups are probed SEQUENTIALLY with a small fixed
-    // delay between them (PHNX-4051) so one box no longer fires 16 requests in
-    // 4s; they target distinct identities, so no same-account concurrency remains.
     const groups = groupFleetAuthInstalls(installs, (inst) => LIVE_PROBE_AGENTS.has(inst.agent));
     const perGroup = [];
     for (let idx = 0; idx < groups.length; idx++) {
@@ -595,10 +392,6 @@ export async function probeLocalFleetAuth(opts) {
         health.account = authAccountLabel(rep.info);
         health.accountId = rep.accountId;
         health.source = 'probe';
-        // `unconfigured` (no credential) and `no_evidence` (a worker that cannot probe)
-        // both write NO row: the first has nothing to say, the second says only "we
-        // did not look", which is not a fleet-publishable verdict — the account's
-        // facts come from token presence + recorded run outcomes instead (PHNX-4116).
         if (health.verdict === 'unconfigured' || health.verdict === 'no_evidence') {
             perGroup.push([]);
         }
@@ -608,29 +401,15 @@ export async function probeLocalFleetAuth(opts) {
                 version: inst.version,
                 account: health.account,
                 accountId: inst.accountId ?? health.accountId,
-                // A distinct object per row so a later mutation of one can't bleed across.
                 health: { ...health },
             })));
         }
-        // Space probes; not after the last group and not if the tick is being aborted.
         if (idx < groups.length - 1 && !opts?.signal?.aborted) {
             await new Promise((resolve) => setTimeout(resolve, AUTH_PROBE_SPACING_MS));
         }
     }
     return perGroup.flat();
 }
-/**
- * Persist a host's probed rows into the cache (keyed by host+agent+version).
- *
- * `installed` — the {@link authTargetKey} set of homes that still exist on
- * `host` ({@link localAuthTargetKeys}) — prunes this host's ORPHAN entries: rows
- * for a version that has since been uninstalled. Nothing re-probes those, so
- * they never age out on their own; they froze the reuse window permanently false
- * and kept surfacing in `agents view` / fleet status (PHNX-4051). Only a caller
- * that enumerated `host`'s real installs may pass it — the `fleet ping` fan-out
- * writes a PEER's rows and cannot enumerate that box's homes, so it omits it and
- * merges as before.
- */
 export function writeFleetAuthRows(host, rows, installed) {
     const entries = {};
     for (const row of rows) {
@@ -644,21 +423,6 @@ export function writeFleetAuthRows(host, rows, installed) {
         : undefined;
     writeAuthHealthEntries(entries, drop);
 }
-// ---------------------------------------------------------------------------
-// Run-outcome recording + auth-fact rendering (PHNX-4116)
-//
-// A worker never probes, so the honest evidence that its token authenticates is
-// a REAL run: a successful inference (`live`) or an auth failure. These rows are
-// written with `source: 'run'` and read back as a FACT — `last used ok 12m ago`
-// / `last auth failure 401 Sep 20 14:02` / `not used on this box yet` — instead
-// of the misleading verdict word the ticket removes.
-// ---------------------------------------------------------------------------
-/**
- * The installed-version label a run outcome falls back to when the account has no
- * slot on this box: the explicit `version`, else the label derived from `home` (a
- * version home is `<versionDir>/home`, so the label is its parent dir's basename).
- * Null when neither resolves. Pure (no fs) so it is unit-tested directly.
- */
 export function runOutcomeVersionKey(opts) {
     if (opts.version)
         return opts.version;
@@ -669,19 +433,7 @@ export function runOutcomeVersionKey(opts) {
     }
     return null;
 }
-/**
- * Record a REAL run's auth outcome into the auth-health cache with
- * `source: 'run'`. Best-effort and never throws: an unattributable run (no
- * accountId/version/home) writes nothing, and the underlying write already
- * swallows IO errors. Keyed exactly as the catalog reads, so the recorded fact
- * surfaces on the same account row.
- */
 export function recordRunAuthOutcome(opts) {
-    // Key exactly as the account catalog READS (slot key first, then the version
-    // label) so the fact lands on the row: the slot key ONLY when a slot dir
-    // actually exists for this account on this box (workers), else the installed
-    // version label (headed native logins have no slot). A last-resort slot key
-    // keeps an attributable-by-id run recorded even with no version hint.
     const slotKey = opts.accountId && readSlots(readMeta())[opts.accountId]
         ? slotAuthVersionKey(opts.accountId)
         : null;
@@ -713,12 +465,10 @@ export function recordRunAuthOutcome(opts) {
     writeAuthHealthEntries({ [authCacheKey(host, opts.agent, versionKey)]: health });
 }
 const FACT_MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
-/** `HH:MM` local clock — used for a throttle reset time. */
 function factClock(ms) {
     const d = new Date(ms);
     return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
 }
-/** `Sep 20 14:02` — the fact timestamp for an auth failure. */
 export function factTimestamp(ms) {
     const d = new Date(ms);
     return `${FACT_MONTHS[d.getMonth()]} ${d.getDate()} ${factClock(ms)}`;