agent-dealer 1.2.14 → 1.2.15

package/bundle/server/dist/capacity/claude-events.js

@@ -319,6 +319,15 @@ export function extractClaudeCapacityFromEvents(events, nowMs = Date.now(), fall
         return null;
     return { runtime: CLAUDE_RUNTIME, windows: [...byKey.values()], unavailable: [] };
 }
+let claudeCriticalReadingSeq = 0;
+/**
+ * Monotonic count of successful Claude 5H/1W writes from any source (probe,
+ * local cache, live session). The probe's in-memory failure streak compares
+ * against it so a non-probe success breaks the streak too (NOT-366).
+ */
+export function claudeCriticalReadingWriteSeq() {
+    return claudeCriticalReadingSeq;
+}
 /**
  * Persist Claude window readings as normalized capacity snapshots
  * (per-window upserts — siblings not in this observation are left untouched,
@@ -338,21 +347,32 @@ export function recordClaudeWindowReadings(readings, runtime, nowMs = Date.now()
     const persistable = normalized.filter((n) => n.unavailableReason === null && n.remainingPercent !== null);
     if (persistable.length === 0)
         return null;
-    const storedObservedAt = new Map(listCapacitySnapshots(runtime).map((row) => [row.windowKey, row.observedAt]));
+    const stored = new Map(listCapacitySnapshots(runtime).map((row) => [row.windowKey, row]));
     const fresh = persistable.filter((w) => {
-        const prev = storedObservedAt.get(w.windowKey);
-        if (!prev)
+        const prevRow = stored.get(w.windowKey);
+        if (!prevRow)
             return true;
-        const prevMs = Date.parse(prev);
+        // NOT-366: an unavailable row (probe failure recorded over a stale
+        // reading) keeps the last-good value and its `observedAt` only for this
+        // arbitration. With no last-good value any reading wins; otherwise only
+        // a strictly newer one does — re-ingesting the same stale cache sample
+        // every poll must not wipe the recorded failure reason.
+        const unavailable = prevRow.source === "unavailable" || prevRow.unavailableReason !== null;
+        if (unavailable && prevRow.remainingPercent === null)
+            return true;
+        const prevMs = Date.parse(prevRow.observedAt);
         const nextMs = Date.parse(w.observedAt);
         if (!Number.isFinite(prevMs))
             return true;
         if (!Number.isFinite(nextMs))
             return false;
-        return nextMs >= prevMs;
+        return unavailable ? nextMs > prevMs : nextMs >= prevMs;
     });
     if (fresh.length === 0)
         return 0;
+    if (fresh.some((w) => w.criticalRole === "five_hour" || w.criticalRole === "weekly")) {
+        claudeCriticalReadingSeq += 1;
+    }
     recordCapacitySnapshots(runtime, fresh.map((w) => ({
         windowKey: w.windowKey,
         providerBucket: w.providerBucket,

package/bundle/server/dist/capacity/claude-local-cache.js

@@ -73,7 +73,11 @@
 //   probe's `usage_report.rate_limits.limits[]` is this exact same shape and
 //   shares the same role mapping (`limitEntryRole`).
 //
-// Probe argv (verified live at 2.1.283):
+// Probe argv (first verified at 2.1.283; re-validated live at 2.1.292 on
+// 2026-10-07 — NOT-366: stream-json still carries `usage_report` on the
+// synthetic assistant event; `--output-format json` prints only the result
+// event and so never shows it; a non-subscription auth source yields a cost
+// summary with no report at all. See docs/RUNTIME_CAPACITY.md):
 // - `-p "/usage"` — the fixed local slash-command; never interpolated, never
 //   a natural-language prompt. Resolved entirely locally: no model call, no
 //   tokens, no cost.
@@ -107,9 +111,10 @@ import path from "node:path";
 import { getDataDir } from "../db/index.js";
 import { resolveClaudeBin } from "../cli-env.js";
 import { parseNdjson } from "../runners/stream-json.js";
-import { listCapacitySnapshots } from "../repository/runtime-capacity.js";
+import { listCapacitySnapshots, recordCapacitySnapshots } from "../repository/runtime-capacity.js";
+import { deriveWindowLabel, isWindowKnown, } from "@agent-dealer/shared";
 import { configuredCapacityRuntimes } from "./service.js";
-import { CLAUDE_RUNTIME, extractClaudeCapacityFromEvents, normalizeClaudeResetsAt, recordClaudeCapacityFromEvents, recordClaudeWindowReadings, } from "./claude-events.js";
+import { CLAUDE_RUNTIME, claudeCriticalReadingWriteSeq, extractClaudeCapacityFromEvents, normalizeClaudeResetsAt, recordClaudeCapacityFromEvents, recordClaudeWindowReadings, } from "./claude-events.js";
 /** Override for the Claude cache file (tests, smoke). */
 export const CLAUDE_CACHE_FILE_ENV = "AGENT_DEALER_CLAUDE_CACHE_FILE";
 /**
@@ -545,6 +550,17 @@ export function defaultProbeRunner(bin, argv, opts) {
         });
     });
 }
+function probeAuthSource(events) {
+    for (const e of events) {
+        if (e.type !== "system" || e.subtype !== "init")
+            continue;
+        const src = e.apiKeySource;
+        // Allow-list the shape so only a source *name* can ever be recorded.
+        if (typeof src === "string" && /^[A-Za-z0-9_.-]{1,64}$/.test(src))
+            return src;
+    }
+    return null;
+}
 function probeCostFromEvents(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const e = events[i];
@@ -735,6 +751,7 @@ export async function runClaudeCapacityProbe(nowMs = Date.now(), opts = {}) {
         events = [];
     }
     const costUsd = probeCostFromEvents(events);
+    const authSource = probeAuthSource(events);
     // Fail-closed structural checks (reviewer-requested, 2026-09-27, PR #165):
     // the whole design rests on `/usage` resolving as a local command that
     // never reaches the model. If either assumption is violated — no local-
@@ -748,9 +765,9 @@ export async function runClaudeCapacityProbe(nowMs = Date.now(), opts = {}) {
     // logged as a distinct failure kind) instead of silently becoming a
     // recurring paid probe again.
     if (!hasLocalUsageCommandMarker(events))
-        return fail("not_local_command", { costUsd });
+        return fail("not_local_command", { costUsd, authSource });
     if (costUsd !== 0)
-        return fail("unexpected_cost", { costUsd });
+        return fail("unexpected_cost", { costUsd, authSource });
     // Primary signal: the `/usage` local command's own structured result.
     // Present on every successful run (verified live) — most reliable source.
     let usageReportRoles = new Set();
@@ -801,14 +818,16 @@ export async function runClaudeCapacityProbe(nowMs = Date.now(), opts = {}) {
         // Advisory — stream coverage below still counts.
     }
     const covered = new Set([...usageReportRoles, ...streamRoles, ...cacheRoles]);
-    if (spawnResult.exitCode !== 0 && covered.size === 0)
-        return fail("nonzero_exit", { costUsd });
+    if (spawnResult.exitCode !== 0 && covered.size === 0) {
+        return fail("nonzero_exit", { costUsd, authSource });
+    }
     if (!covered.has("five_hour") || !covered.has("weekly")) {
-        // A `/usage` run should always carry both roles directly in
-        // `usage_report.rate_limits.limits[]` (verified live) — a `no_windows`
-        // streak here means something changed upstream and is worth revisiting,
-        // but since the refresh is free it is not itself a cost problem.
-        return fail("no_windows", { costUsd });
+        // A subscription-authenticated `/usage` run carries both roles directly
+        // in `usage_report.rate_limits.limits[]` (re-verified live at 2.1.292).
+        // `no_windows` means the report was absent — e.g. an API-key auth source
+        // (see `authSource`), or the CLI's own plan-limits fetch failing — and
+        // is persisted as the window's unavailable reason (NOT-366).
+        return fail("no_windows", { costUsd, authSource });
     }
     const out = {
         ok: true,
@@ -818,6 +837,7 @@ export async function runClaudeCapacityProbe(nowMs = Date.now(), opts = {}) {
         timedOut: false,
         durationMs,
         failureKind: null,
+        authSource,
     };
     logProbeOutcome(out);
     appendProbeDiagnostic({
@@ -830,6 +850,104 @@ export async function runClaudeCapacityProbe(nowMs = Date.now(), opts = {}) {
     });
     return out;
 }
+// ---------------------------------------------------------------------------
+// Unavailable-reason persistence (NOT-366)
+// ---------------------------------------------------------------------------
+/**
+ * Operator-readable cause for a failed refresh. Deliberately prose: the
+ * internal `ProbeFailureKind` identifiers stay in the diagnostic log and
+ * never reach the stored row, the API, or the header (NOT-266).
+ */
+export function claudeProbeFailureMessage(kind, authSource = null) {
+    switch (kind) {
+        case "spawn":
+            return "the Claude CLI could not be started for the /usage refresh";
+        case "timeout":
+            return "the Claude /usage refresh timed out";
+        case "nonzero_exit":
+            return "the Claude /usage refresh exited with an error";
+        case "no_windows":
+            if (authSource !== null && authSource !== "none") {
+                return (`Claude /usage reported no plan limits: the CLI is authenticated via ${authSource}, ` +
+                    "which has no 5H/1W subscription windows");
+            }
+            return "Claude /usage reported no 5H/1W plan limits";
+        case "not_local_command":
+            return "Claude /usage did not run as a local command, so its result was not trusted";
+        case "unexpected_cost":
+            return "the Claude /usage refresh could not be verified as free, so its result was rejected";
+    }
+}
+function failureUnavailableReason(kind) {
+    // A payload arrived but yielded no trusted windows vs. no payload at all.
+    return kind === "no_windows" || kind === "not_local_command" || kind === "unexpected_cost"
+        ? "unparsable"
+        : "missing";
+}
+/**
+ * Record a failed refresh on every critical window that has no current
+ * reading, so absence of data is stored with its cause instead of inferred
+ * from an empty header. A window still carrying a current reading is left
+ * alone (a fresh reading always wins). An existing stale row keeps its
+ * last-good value and `observedAt` — only so newer-wins arbitration in
+ * `recordClaudeWindowReadings` still works — and is flagged
+ * `source: unavailable`, so read-time classification never shows it as a
+ * number. The streak (count + first failure) continues from whatever is
+ * already stored, so it survives a server restart; any successful reading
+ * rewrites the row with no detail, clearing it.
+ */
+export function recordClaudeAcquisitionFailure(result, nowMs = Date.now(), inMemoryStreak = { count: 1, firstFailureMs: nowMs }) {
+    const kind = result.failureKind;
+    if (!kind)
+        return 0;
+    const rows = new Map(listCapacitySnapshots(CLAUDE_RUNTIME).map((r) => [r.windowKey, r]));
+    let prevCount = 0;
+    let firstMs = inMemoryStreak.firstFailureMs ?? nowMs;
+    for (const identity of Object.values(CACHE_WINDOW_IDENTITIES)) {
+        const detail = rows.get(identity.windowKey)?.unavailableDetail;
+        if (!detail)
+            continue;
+        prevCount = Math.max(prevCount, detail.consecutiveFailures);
+        const ms = Date.parse(detail.firstFailureAt);
+        if (Number.isFinite(ms))
+            firstMs = Math.min(firstMs, ms);
+    }
+    const nowIso = new Date(nowMs).toISOString();
+    const unavailableDetail = {
+        message: claudeProbeFailureMessage(kind, result.authSource ?? null),
+        consecutiveFailures: Math.max(prevCount + 1, inMemoryStreak.count, 1),
+        firstFailureAt: new Date(Math.min(firstMs, nowMs)).toISOString(),
+        lastFailureAt: nowIso,
+    };
+    const writes = Object.values(CACHE_WINDOW_IDENTITIES).flatMap((identity) => {
+        const row = rows.get(identity.windowKey);
+        if (row && isWindowKnown(row, nowMs))
+            return [];
+        return [
+            {
+                windowKey: identity.windowKey,
+                providerBucket: identity.providerBucket,
+                durationMinutes: identity.durationMinutes,
+                displayLabel: row?.displayLabel ?? deriveWindowLabel(identity.durationMinutes, identity.providerBucket),
+                usedValue: row?.usedValue ?? null,
+                usedUnit: row?.usedUnit ?? null,
+                remainingPercent: row?.remainingPercent ?? null,
+                resetAt: row?.resetAt ?? null,
+                observedAt: row?.observedAt ?? nowIso,
+                freshUntil: row?.freshUntil ?? null,
+                expiresAt: row?.expiresAt ?? null,
+                source: "unavailable",
+                unavailableReason: failureUnavailableReason(kind),
+                evidenceRef: CLAUDE_PROBE_EVIDENCE_REF,
+                criticalRole: identity.criticalRole,
+                unavailableDetail,
+            },
+        ];
+    });
+    if (writes.length > 0)
+        recordCapacitySnapshots(CLAUDE_RUNTIME, writes);
+    return writes.length;
+}
 /**
  * Newest valid account-wide observation per critical window (event or cache
  * — both share window keys and critical roles). A row counts when it
@@ -877,11 +995,15 @@ export function newestValidClaudeObservationMs(nowMs = Date.now()) {
 let claudeProbeInFlight = null;
 let lastClaudeProbeAttemptMs = 0;
 let consecutiveClaudeProbeFailures = 0;
+let firstClaudeProbeFailureMs = null;
+/** Success-write sequence seen when the current failure streak began. */
+let claudeProbeStreakReadingSeq = 0;
 /** Test helper — clear single-flight, attempt, and backoff state. */
 export function resetClaudeCapacityRefreshState() {
     claudeProbeInFlight = null;
     lastClaudeProbeAttemptMs = 0;
     consecutiveClaudeProbeFailures = 0;
+    firstClaudeProbeFailureMs = null;
 }
 /** Test helper — observe backoff/attempt state without spawning. */
 export function claudeProbeRefreshStateForTests() {
@@ -939,7 +1061,31 @@ export async function maybeProbeClaudeCapacity(nowMs = Date.now(), opts = {}) {
         claudeProbeInFlight = run;
         try {
             const result = await run;
-            consecutiveClaudeProbeFailures = result.ok ? 0 : consecutiveClaudeProbeFailures + 1;
+            if (result.ok) {
+                consecutiveClaudeProbeFailures = 0;
+                firstClaudeProbeFailureMs = null;
+            }
+            else {
+                // Any successful 5H/1W reading since the streak began (local cache
+                // or a live session, not just this probe) ends it: start fresh.
+                const seq = claudeCriticalReadingWriteSeq();
+                if (consecutiveClaudeProbeFailures === 0 || seq !== claudeProbeStreakReadingSeq) {
+                    consecutiveClaudeProbeFailures = 0;
+                    firstClaudeProbeFailureMs = null;
+                    claudeProbeStreakReadingSeq = seq;
+                }
+                consecutiveClaudeProbeFailures += 1;
+                firstClaudeProbeFailureMs ??= nowMs;
+                try {
+                    recordClaudeAcquisitionFailure(result, nowMs, {
+                        count: consecutiveClaudeProbeFailures,
+                        firstFailureMs: firstClaudeProbeFailureMs,
+                    });
+                }
+                catch {
+                    // Advisory — the failure is still in the diagnostic log.
+                }
+            }
             return {
                 probed: true,
                 reason: "completed",

package/bundle/server/dist/capacity/claude-local-cache.test.js

@@ -17,7 +17,7 @@ const { listCapacitySnapshots, clearAllCapacitySnapshots, } = await import("../r
 const { parseNdjson } = await import("../runners/stream-json.js");
 const { getRuntimeCapacitySnapshot } = await import("./service.js");
 const { recordClaudeCapacityFromEvents, recordClaudeWindowReadings } = await import("./claude-events.js");
-const { CLAUDE_CACHE_FILE_ENV, CLAUDE_CAPACITY_REFRESH_ENV, CLAUDE_PROBE_STALE_AFTER_MS, buildClaudeProbeArgv, claudeCacheFilePath, extractClaudeCacheSubtree, ingestClaudeLocalCache, isClaudePaidFallbackEnabled, maybeProbeClaudeCapacity, newestValidClaudeObservationMs, newestValidClaudeObservationMsByRole, parseClaudeCachedUtilization, probeDiagnosticLogPath, readClaudeLocalCache, refreshClaudeCapacityIfStale, resetClaudeCapacityRefreshState, runClaudeCapacityProbe, } = await import("./claude-local-cache.js");
+const { CLAUDE_CACHE_FILE_ENV, CLAUDE_CAPACITY_REFRESH_ENV, CLAUDE_PROBE_STALE_AFTER_MS, buildClaudeProbeArgv, claudeCacheFilePath, extractClaudeCacheSubtree, ingestClaudeLocalCache, isClaudePaidFallbackEnabled, maybeProbeClaudeCapacity, newestValidClaudeObservationMs, newestValidClaudeObservationMsByRole, parseClaudeCachedUtilization, probeDiagnosticLogPath, readClaudeLocalCache, recordClaudeAcquisitionFailure, refreshClaudeCapacityIfStale, resetClaudeCapacityRefreshState, runClaudeCapacityProbe, } = await import("./claude-local-cache.js");
 const NOW_MS = Date.parse("2026-09-20T12:00:00.000Z");
 const FIVE_HOUR_RESET_SEC = Math.floor(NOW_MS / 1000) + 2 * 3600;
 const SEVEN_DAY_RESET_SEC = Math.floor(NOW_MS / 1000) + 3 * 24 * 3600;
@@ -96,7 +96,7 @@ const throwingRunner = () => {
  * need direct per-role rows. Resets stay in the future so rows count as
  * valid observations at NOW_MS.
  */
-function seedWindowAges(fiveHourAgeMs, weeklyAgeMs, nowMs = NOW_MS) {
+function seedWindowAges(fiveHourAgeMs, weeklyAgeMs, nowMs = NOW_MS, expectedPersisted) {
     const readings = [];
     const role = (five, ageMs) => ({
         windowKey: five ? "claude_unified_five_hour" : "claude_unified_seven_day",
@@ -116,7 +116,7 @@ function seedWindowAges(fiveHourAgeMs, weeklyAgeMs, nowMs = NOW_MS) {
         readings.push(role(true, fiveHourAgeMs));
     if (weeklyAgeMs !== null)
         readings.push(role(false, weeklyAgeMs));
-    assert.equal(recordClaudeWindowReadings(readings, "claude_code", nowMs), readings.length);
+    assert.equal(recordClaudeWindowReadings(readings, "claude_code", nowMs), expectedPersisted ?? readings.length);
 }
 function successRunner(atMs = NOW_MS) {
     return async () => ({
@@ -821,3 +821,191 @@ test("a full ~/.claude.json-shaped file yields 5H/1W from the subtree only", ()
     assert.equal(claude.windows.find((w) => w.displayLabel === "5H").remainingPercent, 91);
     assert.equal(claude.windows.find((w) => w.displayLabel === "1W").remainingPercent, 77);
 });
+// ---------------------------------------------------------------------------
+// NOT-366: the re-validated `/usage` contract and unavailable-reason rows
+// ---------------------------------------------------------------------------
+/**
+ * Sanitized shape of a real `claude -p "/usage"` stream-json run at 2.1.292
+ * (Dealer's exact probe argv, re-validated 2026-10-07): `system/init`, then
+ * the synthetic assistant event carrying `local_command_run` and
+ * `usage_report.rate_limits.limits[]`, then a `result` event with
+ * `local_command: "usage"`, `num_turns: 0`, `total_cost_usd: 0` — and no
+ * `usage_report` of its own (which is why `--output-format json`, printing
+ * only the result, never shows it). `apiKeySource` other than `none` yields
+ * the cost-summary-only variant: no `usage_report` at all.
+ */
+function liveUsageStream(observedMs, opts = {}) {
+    const withReport = opts.withReport ?? true;
+    const events = [
+        { type: "system", subtype: "init", apiKeySource: opts.apiKeySource ?? "none", claude_code_version: "2.1.292" },
+        {
+            type: "assistant",
+            message: { model: "<synthetic>", role: "assistant", content: [{ type: "text", text: "<omitted>" }] },
+            local_command_source: "<omitted>",
+            timestamp: new Date(observedMs).toISOString(),
+            local_command_run: { command: "usage", args: "" },
+            ...(withReport
+                ? {
+                    usage_report: {
+                        session: { total_cost_usd: 0, total_api_duration_ms: 0 },
+                        rate_limits: {
+                            limits: [
+                                {
+                                    kind: "session",
+                                    group: "session",
+                                    percent: 6,
+                                    resets_at: new Date(observedMs + 4 * 3600_000).toISOString().replace("Z", "535018+00:00"),
+                                    scope: null,
+                                    severity: "normal",
+                                    is_active: true,
+                                },
+                                {
+                                    kind: "weekly_all",
+                                    group: "weekly",
+                                    percent: 5,
+                                    resets_at: new Date(observedMs + 5 * 86_400_000).toISOString().replace("Z", "535047+00:00"),
+                                    scope: null,
+                                    severity: "normal",
+                                    is_active: false,
+                                },
+                            ],
+                            extra_usage: { is_enabled: false },
+                        },
+                    },
+                }
+                : {}),
+        },
+        { type: "result", subtype: "success", is_error: false, num_turns: 0, total_cost_usd: 0, local_command: "usage" },
+    ];
+    return events.map((e) => JSON.stringify(e)).join("\n");
+}
+function streamRunner(stdout, atMs) {
+    return async () => ({ stdout: stdout(atMs()), exitCode: 0, timedOut: false, spawnError: null });
+}
+test("re-validated 2.1.292 /usage stream yields both five_hour and weekly", async () => {
+    const { extractClaudeUsageReportLimits } = await import("./claude-local-cache.js");
+    const readings = extractClaudeUsageReportLimits(parseNdjson(liveUsageStream(NOW_MS)), NOW_MS);
+    assert.ok(readings);
+    assert.deepEqual(readings.map((w) => w.criticalRole).sort(), ["five_hour", "weekly"]);
+    // The full probe accepts it: marker present, exactly $0, both roles.
+    const result = await runClaudeCapacityProbe(NOW_MS, {
+        runner: streamRunner((ms) => liveUsageStream(ms), () => NOW_MS),
+        bin: "/fake/claude",
+    });
+    assert.equal(result.ok, true);
+    assert.equal(result.authSource, "none");
+    const snap = getRuntimeCapacitySnapshot(NOW_MS + 1000);
+    const claude = snap.runtimes.find((r) => r.runtime === "claude_code");
+    assert.equal(claude.windows.find((w) => w.criticalRole === "five_hour").remainingPercent, 94);
+    assert.equal(claude.windows.find((w) => w.criticalRole === "weekly").remainingPercent, 95);
+});
+test("no_windows failure persists an unavailable row; streak rises to 3 then a success clears it", async () => {
+    const failing = streamRunner((ms) => liveUsageStream(ms, { withReport: false }), () => clock);
+    let clock = NOW_MS;
+    const firstIso = new Date(NOW_MS).toISOString();
+    // Backoff after n failures: 14m · 2^n → attempts at +0, +29m, +86m, +199m.
+    const attemptAt = [NOW_MS, NOW_MS + 29 * 60_000, NOW_MS + 86 * 60_000];
+    for (const [i, at] of attemptAt.entries()) {
+        clock = at;
+        const outcome = await maybeProbeClaudeCapacity(at, { runner: failing, bin: "/fake/claude" });
+        assert.equal(outcome.probed, true);
+        assert.equal(outcome.failureKind, "no_windows");
+        const rows = listCapacitySnapshots("claude_code");
+        assert.equal(rows.length, 2, "one stored row per critical window");
+        for (const row of rows) {
+            assert.ok(row.unavailableReason, "unavailable_reason is populated");
+            assert.equal(row.source, "unavailable");
+            assert.ok(row.unavailableDetail);
+            assert.equal(row.unavailableDetail.consecutiveFailures, i + 1);
+            assert.equal(row.unavailableDetail.firstFailureAt, firstIso);
+            assert.equal(row.unavailableDetail.lastFailureAt, new Date(at).toISOString());
+            assert.match(row.unavailableDetail.message, /no 5H\/1W plan limits/);
+        }
+    }
+    // Read model: N/A with the operator text, never the internal identifier.
+    const failedSnap = getRuntimeCapacitySnapshot(clock);
+    const failedClaude = failedSnap.runtimes.find((r) => r.runtime === "claude_code");
+    assert.ok(failedClaude.windows.every((w) => w.remainingPercent === null && w.unavailableDetail));
+    assert.ok(!JSON.stringify(failedSnap).includes("no_windows"));
+    clock = NOW_MS + 199 * 60_000;
+    const ok = await maybeProbeClaudeCapacity(clock, {
+        runner: streamRunner((ms) => liveUsageStream(ms), () => clock),
+        bin: "/fake/claude",
+    });
+    assert.equal(ok.ok, true);
+    for (const row of listCapacitySnapshots("claude_code")) {
+        assert.equal(row.unavailableReason, null);
+        assert.equal(row.unavailableDetail, null);
+        assert.equal(row.source, "observed_event");
+    }
+    // The next failure starts a new streak at 1.
+    clock = NOW_MS + 260 * 60_000;
+    await maybeProbeClaudeCapacity(clock, { runner: failing, bin: "/fake/claude" });
+    for (const row of listCapacitySnapshots("claude_code")) {
+        assert.equal(row.unavailableDetail.consecutiveFailures, 1);
+        assert.equal(row.unavailableDetail.firstFailureAt, new Date(clock).toISOString());
+    }
+});
+test("a live-session reading between failures restarts the streak instead of inflating it", async () => {
+    let clock = NOW_MS;
+    const failing = streamRunner((ms) => liveUsageStream(ms, { withReport: false }), () => clock);
+    for (const at of [NOW_MS, NOW_MS + 29 * 60_000, NOW_MS + 86 * 60_000]) {
+        clock = at;
+        await maybeProbeClaudeCapacity(at, { runner: failing, bin: "/fake/claude" });
+    }
+    assert.equal(listCapacitySnapshots("claude_code")[0].unavailableDetail.consecutiveFailures, 3);
+    // A live session (not the probe) lands both windows and clears the stored detail.
+    seedWindowAges(0, 0, NOW_MS + 100 * 60_000);
+    for (const row of listCapacitySnapshots("claude_code"))
+        assert.equal(row.unavailableDetail, null);
+    // Once that reading lapses (5H reset passed, 1W expired), the next failure is #1.
+    clock = NOW_MS + 200 * 60_000;
+    const outcome = await maybeProbeClaudeCapacity(clock, { runner: failing, bin: "/fake/claude" });
+    assert.equal(outcome.failureKind, "no_windows");
+    const rows = listCapacitySnapshots("claude_code");
+    assert.equal(rows.length, 2);
+    for (const row of rows) {
+        assert.equal(row.unavailableDetail.consecutiveFailures, 1);
+        assert.equal(row.unavailableDetail.firstFailureAt, new Date(clock).toISOString());
+    }
+});
+test("an API-key auth source is named in the stored reason", async () => {
+    const outcome = await maybeProbeClaudeCapacity(NOW_MS, {
+        runner: streamRunner((ms) => liveUsageStream(ms, { withReport: false, apiKeySource: "ANTHROPIC_API_KEY" }), () => NOW_MS),
+        bin: "/fake/claude",
+    });
+    assert.equal(outcome.failureKind, "no_windows");
+    const row = listCapacitySnapshots("claude_code")[0];
+    assert.match(row.unavailableDetail.message, /authenticated via ANTHROPIC_API_KEY/);
+});
+test("a failure leaves a current reading alone and keeps a stale one's value for arbitration", async () => {
+    // 5H current (10m old), 1W stale (20m old — past the 15m freshness).
+    seedWindowAges(10 * 60_000, 20 * 60_000);
+    assert.equal(recordClaudeAcquisitionFailure({ failureKind: "timeout", authSource: null }, NOW_MS), 1);
+    const rows = listCapacitySnapshots("claude_code");
+    const five = rows.find((r) => r.criticalRole === "five_hour");
+    const weekly = rows.find((r) => r.criticalRole === "weekly");
+    assert.equal(five.unavailableReason, null);
+    assert.equal(five.source, "observed_event");
+    assert.equal(weekly.unavailableReason, "missing");
+    assert.equal(weekly.unavailableDetail.message, "the Claude /usage refresh timed out");
+    assert.equal(weekly.observedAt, new Date(NOW_MS - 20 * 60_000).toISOString());
+    // Re-ingesting the same stale sample (every poll does) must not wipe the reason.
+    seedWindowAges(null, 20 * 60_000, NOW_MS, 0);
+    assert.equal(listCapacitySnapshots("claude_code").find((r) => r.criticalRole === "weekly").unavailableReason, "missing");
+});
+test("a fresh observed_event reading wins over a stored unavailable row and leaves no reason", () => {
+    // Failure recorded at NOW with no prior reading at all.
+    assert.equal(recordClaudeAcquisitionFailure({ failureKind: "no_windows", authSource: null }, NOW_MS), 2);
+    // A live session's reading observed 2 minutes before the failure stamp.
+    seedWindowAges(2 * 60_000, 2 * 60_000);
+    const snap = getRuntimeCapacitySnapshot(NOW_MS + 60_000);
+    const claude = snap.runtimes.find((r) => r.runtime === "claude_code");
+    for (const w of claude.windows) {
+        assert.ok(w.remainingPercent !== null, "the rendered window shows the value");
+        assert.equal(w.unavailableReason, null);
+        assert.equal(w.unavailableDetail ?? null, null);
+        assert.equal(w.source, "observed_event");
+    }
+    assert.equal(claude.unavailableReason, null);
+});