@kill-switch/agent-guard 0.1.2 → 0.1.4

package/README.md

@@ -152,6 +152,13 @@ Tune the thresholds (0–1 utilization) if the defaults are too eager:
 | `--5h-soft` / `--5h-danger` | 5-hour warn / danger utilization | 0.7 / 0.9 |
 | `--burn-ratio` | pace multiplier that triggers a warning | 1.5 |
 
+The first time the proxy sees the `unified-*` headers it writes the raw values once to
+`~/.kill-switch/agent-guard/events.jsonl` (`kind: "unified-headers-observed"`) — so you can
+confirm Anthropic's exact value formats with a single `cat`. Only `unified-*` headers are
+captured (an explicit allowlist — never `Authorization` / `x-api-key` / cookies), values are
+length-capped, and the dump stays local. In `auto` mode the dollar-wall suppression trusts the
+upstream's headers; pin `--plan` if you'd rather it not depend on what the upstream reports.
+
 > Because subscription mode is alert-only, the "don't run both hook *and* proxy" caveat below
 > doesn't bite here — running Claude Code through the proxy is exactly what feeds the limit
 > headers, and dollars no longer gate anything.
@@ -184,7 +191,7 @@ agent-guard proxy   [--port 8787] [--flavor anthropic|openai] [--upstream URL]
 agent-guard status  [--json]                        spend vs budget + plan limits
 agent-guard config  [--session-hard N ...]          view/set caps
 agent-guard config  [--plan max5 --weekly-soft 0.6 ...]   view/set plan limits
-agent-guard reset   [--all|--today|--session <id>]  clear the ledger
+agent-guard reset   [--all|--limits|--today|--session <id>]  clear the ledger / subscription-limit state
 agent-guard hook                                    (internal) Claude Code entrypoint
 ```
 

package/dist/cli.js

@@ -213,11 +213,12 @@ program
 // ── reset ────────────────────────────────────────────────────────────────────
 program
     .command("reset")
-    .description("Clear the spend ledger")
-    .option("--all", "Wipe all sessions")
+    .description("Clear the spend ledger and/or subscription-limit state")
+    .option("--all", "Wipe all sessions + subscription-limit state")
+    .option("--limits", "Clear subscription detection latch + snapshot only")
     .option("--session <id>", "Clear a single session")
     .option("--today", "Clear sessions active today")
     .action((opts) => {
-    console.log(`✅ ${resetLedger({ all: opts.all, session: opts.session, today: opts.today })}`);
+    console.log(`✅ ${resetLedger({ all: opts.all, limits: opts.limits, session: opts.session, today: opts.today })}`);
 });
 program.parseAsync();

package/dist/estimate.js

@@ -48,19 +48,13 @@ export function estimateSnapshot(ledger, tier, now, budgets = TIER_BUDGETS) {
     const fiveTokens = tokensInWindow(ledger, now, FIVE_HOUR_MS);
     const weekTokens = tokensInWindow(ledger, now, WEEK_MS);
     const clamp = (n) => Math.max(0, Math.min(1, n));
+    // resetAt is null, not fabricated: we have no per-event time series, so the
+    // true rolling reset is unknowable. A null reset means pacing reports
+    // utilization only (no burn-rate, no lockout projection, no bogus reset time) —
+    // the honest behaviour for an estimate.
     return {
-        fiveHour: {
-            utilization: clamp(fiveTokens / b.fiveHourTokens),
-            // Without a per-event time series we can't know the true rolling reset;
-            // report a full window from now as a conservative (latest-possible) reset.
-            resetAt: now + FIVE_HOUR_MS,
-            status: "estimated",
-        },
-        weekly: {
-            utilization: clamp(weekTokens / b.weeklyTokens),
-            resetAt: now + WEEK_MS,
-            status: "estimated",
-        },
+        fiveHour: { utilization: clamp(fiveTokens / b.fiveHourTokens), resetAt: null, status: "estimated" },
+        weekly: { utilization: clamp(weekTokens / b.weeklyTokens), resetAt: null, status: "estimated" },
         status: "estimated",
         observedAt: now,
     };

package/dist/hook.js

@@ -24,7 +24,7 @@ import { parseTranscript } from "./transcript.js";
 import { loadLedger, saveLedger, setSessionCost, rollingDailyCost, prune, } from "./ledger.js";
 import { evaluate, warnKey } from "./budget.js";
 import { dispatchAlert } from "./alert.js";
-import { buildStatusReport } from "./report.js";
+import { buildLimitsReport } from "./report.js";
 function readStdin() {
     return new Promise((resolve) => {
         let data = "";
@@ -151,7 +151,7 @@ export async function runHook() {
         // snapshot the proxy persisted from Anthropic's headers (or a tier estimate),
         // so even a hook-only session learns when it's about to lock out. Deduped per
         // window+level so it doesn't repeat every tool call.
-        const limitMsg = limitNudge(rec, ledger, now);
+        const limitMsg = limitNudge(cfg, rec, ledger, now);
         // Surface the warn nudge only on the first trip per scope (shouldAlert), not
         // on every subsequent tool call — otherwise the agent's context fills with
         // duplicate notices. After that, warnings stay silent until the hard cap.
@@ -175,9 +175,9 @@ export async function runHook() {
  * session's notified map (and persists it) so the same warning doesn't repeat on
  * every tool call. Returns null when there's nothing to surface.
  */
-function limitNudge(rec, ledger, now) {
+function limitNudge(cfg, rec, ledger, now) {
     try {
-        const limits = buildStatusReport(now).limits;
+        const limits = buildLimitsReport(cfg, ledger, now);
         if (!limits.windows.length)
             return null;
         const urgent = limits.windows.find((w) => w.level === "danger") ?? limits.windows.find((w) => w.level === "warn");

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export { dispatchAlert, type AlertEvent, type AlertLevel } from "./alert.js";
 export { startProxy, resolveUpstream, type ProxyOptions } from "./proxy.js";
 export { runHook } from "./hook.js";
 export { buildStatusReport, formatLimitsLines, type StatusReport, type LimitsReport } from "./report.js";
-export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, WINDOW_MS, type LimitSnapshot, type WindowState, type LimitsState, type LimitWindow, type HeaderGetter, } from "./limits.js";
+export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, unifiedHeaderDump, logUnifiedHeaders, WINDOW_MS, type LimitSnapshot, type WindowState, type LimitsState, type LimitWindow, type HeaderGetter, } from "./limits.js";
 export { assessWindow, assessSnapshot, worstLevel, type PacingAssessment, type PacingLevel, type PacingThresholds, } from "./pacing.js";
 export { estimateSnapshot, isEstimated, TIER_BUDGETS, type PlanTier, type TierBudget, } from "./estimate.js";
 export { installHook, setBudget, setLimits, resetLedger, type InstallOptions, type InstallResult, type BudgetPatch, type LimitsPatch, } from "./ops.js";

package/dist/index.js

@@ -17,7 +17,7 @@ export { dispatchAlert } from "./alert.js";
 export { startProxy, resolveUpstream } from "./proxy.js";
 export { runHook } from "./hook.js";
 export { buildStatusReport, formatLimitsLines } from "./report.js";
-export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, WINDOW_MS, } from "./limits.js";
+export { parseUnifiedHeaders, parseUtilization, parseReset, recordHeaders, loadLimitsState, saveLimitsState, emptyLimitsState, limitNotifyKey, unifiedHeaderDump, logUnifiedHeaders, WINDOW_MS, } from "./limits.js";
 export { assessWindow, assessSnapshot, worstLevel, } from "./pacing.js";
 export { estimateSnapshot, isEstimated, TIER_BUDGETS, } from "./estimate.js";
 export { installHook, setBudget, setLimits, resetLedger, } from "./ops.js";

package/dist/limits.d.ts

@@ -49,6 +49,8 @@ export interface LimitsState {
     snapshot: LimitSnapshot | null;
     /** Dedup flags so a given window/level/reset only alerts once. */
     notified: Record<string, boolean>;
+    /** Epoch ms we first logged the raw unified-* headers (write-once diagnostic). */
+    headersLoggedAt?: number;
 }
 /** Nominal window durations, used for pacing math when a reset time is unknown. */
 export declare const WINDOW_MS: Record<LimitWindow, number>;
@@ -81,3 +83,6 @@ export declare function parseReset(raw: string | null | undefined, now: number):
 export declare function parseUnifiedHeaders(h: HeaderGetter, now: number): LimitSnapshot | null;
 /** Stable dedup key for a pacing alert: re-alerts when the window resets. */
 export declare function limitNotifyKey(window: LimitWindow, level: string, resetAt: number | null): string;
+export declare function unifiedHeaderDump(rec: Record<string, string | string[] | undefined>): Record<string, string>;
+/** Append a one-time raw-header diagnostic to events.jsonl. Best-effort, never throws. */
+export declare function logUnifiedHeaders(dump: Record<string, string>, now: number): void;

package/dist/limits.js

@@ -22,8 +22,8 @@
  * either a 0–1 fraction or a 0–100 percent; reset is accepted as an ISO 8601
  * timestamp, an epoch (s or ms), or a relative seconds-until-reset.
  */
-import { readFileSync, writeFileSync, renameSync } from "node:fs";
-import { limitsPath, ensureGuardDir } from "./config.js";
+import { readFileSync, writeFileSync, renameSync, appendFileSync } from "node:fs";
+import { limitsPath, eventsPath, ensureGuardDir } from "./config.js";
 /** Nominal window durations, used for pacing math when a reset time is unknown. */
 export const WINDOW_MS = {
     "5h": 5 * 60 * 60 * 1000,
@@ -41,6 +41,7 @@ export function loadLimitsState() {
                 subscriptionDetected: data.subscriptionDetected ?? false,
                 snapshot: data.snapshot ?? null,
                 notified: data.notified ?? {},
+                headersLoggedAt: data.headersLoggedAt,
             };
         }
     }
@@ -131,3 +132,38 @@ export function parseUnifiedHeaders(h, now) {
 export function limitNotifyKey(window, level, resetAt) {
     return `${window}:${level}:${resetAt ?? 0}`;
 }
+/**
+ * Pull every `anthropic-ratelimit-unified-*` header out of a raw record, verbatim.
+ * Used for the write-once diagnostic — Anthropic's value *formats* (fraction vs.
+ * percent, ISO vs. epoch reset) aren't fully documented, so capturing the raw
+ * strings the first time we see them makes verification a single `cat` away.
+ *
+ * Security: this is an explicit **allowlist** by the `anthropic-ratelimit-unified`
+ * prefix — credential headers (Authorization, x-api-key, cookies) are never
+ * captured, even though the caller hands us the full response header set. Values
+ * are length-capped so a hostile/compromised upstream can't bloat the log.
+ */
+const MAX_DUMP_VALUE = 256;
+export function unifiedHeaderDump(rec) {
+    const out = {};
+    for (const [k, v] of Object.entries(rec)) {
+        if (v == null)
+            continue;
+        const key = k.toLowerCase();
+        if (!key.startsWith("anthropic-ratelimit-unified"))
+            continue;
+        const val = Array.isArray(v) ? v.join(", ") : v;
+        out[key] = val.length > MAX_DUMP_VALUE ? val.slice(0, MAX_DUMP_VALUE) + "…[truncated]" : val;
+    }
+    return out;
+}
+/** Append a one-time raw-header diagnostic to events.jsonl. Best-effort, never throws. */
+export function logUnifiedHeaders(dump, now) {
+    try {
+        ensureGuardDir();
+        appendFileSync(eventsPath(), JSON.stringify({ ts: now, kind: "unified-headers-observed", headers: dump }) + "\n");
+    }
+    catch {
+        /* diagnostic only */
+    }
+}

package/dist/ops.d.ts

@@ -45,9 +45,15 @@ export interface LimitsPatch {
 }
 /** Write subscription-limit overrides to the config file. Returns the saved limits. */
 export declare function setLimits(patch: LimitsPatch): LimitsConfig;
-/** Clear the spend ledger. Scope: all | a single session | today's sessions. */
+/**
+ * Clear guard state. Scope: all (ledger + limits) | limits only | a single
+ * session | today's sessions. The `limits` scope clears the subscription
+ * detection latch + last snapshot — useful when you stop using a Pro/Max plan
+ * and want the dollar wall fully re-armed.
+ */
 export declare function resetLedger(opts: {
     all?: boolean;
+    limits?: boolean;
     session?: string;
     today?: boolean;
 }): string;

package/dist/ops.js

@@ -8,6 +8,7 @@ import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { configPath, ensureGuardDir, DEFAULT_BUDGET, DEFAULT_LIMITS } from "./config.js";
 import { loadLedger, saveLedger, emptyLedger } from "./ledger.js";
+import { saveLimitsState, emptyLimitsState } from "./limits.js";
 /**
  * Wire the agent-guard hook into Claude Code settings for PreToolUse,
  * UserPromptSubmit, and Stop. Idempotent: re-running adds nothing if the hook
@@ -99,11 +100,21 @@ export function setLimits(patch) {
     writeFileSync(configPath(), JSON.stringify(file, null, 2) + "\n");
     return limits;
 }
-/** Clear the spend ledger. Scope: all | a single session | today's sessions. */
+/**
+ * Clear guard state. Scope: all (ledger + limits) | limits only | a single
+ * session | today's sessions. The `limits` scope clears the subscription
+ * detection latch + last snapshot — useful when you stop using a Pro/Max plan
+ * and want the dollar wall fully re-armed.
+ */
 export function resetLedger(opts) {
     if (opts.all) {
         saveLedger(emptyLedger());
-        return "Ledger wiped.";
+        saveLimitsState(emptyLimitsState());
+        return "Ledger + subscription-limit state wiped.";
+    }
+    if (opts.limits) {
+        saveLimitsState(emptyLimitsState());
+        return "Subscription-limit state cleared (detection latch + snapshot).";
     }
     const ledger = loadLedger();
     if (opts.session) {
@@ -120,5 +131,5 @@ export function resetLedger(opts) {
         saveLedger(ledger);
         return "Cleared today's sessions.";
     }
-    return "Specify all, session <id>, or today.";
+    return "Specify all, limits, session <id>, or today.";
 }

package/dist/proxy.js

@@ -24,7 +24,7 @@ import { loadLedger, saveLedger, addSessionCost, rollingDailyCost, prune, } from
 import { evaluate } from "./budget.js";
 import { dispatchAlert } from "./alert.js";
 import { assertSafeEndpoint, warnIfUnexpectedHost } from "./net.js";
-import { parseUnifiedHeaders, loadLimitsState, saveLimitsState, limitNotifyKey, } from "./limits.js";
+import { parseUnifiedHeaders, recordHeaders, unifiedHeaderDump, logUnifiedHeaders, loadLimitsState, saveLimitsState, limitNotifyKey, WINDOW_MS, } from "./limits.js";
 import { assessSnapshot, worstLevel } from "./pacing.js";
 const UPSTREAMS = {
     anthropic: "https://api.anthropic.com",
@@ -145,23 +145,48 @@ function meter(cfg, ledger, sessionId, parsed, now) {
  * the real wall).
  */
 function captureLimits(cfg, headers, sessionId, now) {
-    const snap = parseUnifiedHeaders(headers, now);
+    // Flatten to a lowercased record so we can both parse and dump the raw values.
+    const rec = {};
+    headers.forEach((v, k) => {
+        rec[k.toLowerCase()] = v;
+    });
+    const snap = parseUnifiedHeaders(recordHeaders(rec), now);
     if (!snap)
         return false;
     const state = loadLimitsState();
-    state.subscriptionDetected = true;
-    state.snapshot = snap;
+    // Write-once raw-header diagnostic for format verification (`cat events.jsonl`).
+    if (!state.headersLoggedAt) {
+        logUnifiedHeaders(unifiedHeaderDump(rec), now);
+        state.headersLoggedAt = now;
+    }
+    // Which windows newly cross into warn/danger (dedup vs. what we've alerted).
     const assessments = assessSnapshot(snap, cfg.limits, now);
+    const newlyNotified = [];
     const fresh = assessments.filter((a) => {
         if (a.level === "ok")
             return false;
         const key = limitNotifyKey(a.window, a.level, a.resetAt);
         if (state.notified[key])
             return false;
-        state.notified[key] = true;
+        newlyNotified.push(key);
         return true;
     });
-    saveLimitsState(state);
+    // Re-read at write time to mitigate read-modify-write races: the file write is
+    // atomic (no corruption), but a concurrent response could otherwise clobber a
+    // newer snapshot or a just-set notified flag. Keep the newest snapshot by
+    // observedAt; union the notified flags.
+    const onDisk = loadLimitsState();
+    const keepNewer = onDisk.snapshot && onDisk.snapshot.observedAt > snap.observedAt;
+    const merged = {
+        version: 1,
+        subscriptionDetected: true,
+        snapshot: keepNewer ? onDisk.snapshot : snap,
+        notified: { ...onDisk.notified, ...state.notified },
+        headersLoggedAt: onDisk.headersLoggedAt ?? state.headersLoggedAt,
+    };
+    for (const key of newlyNotified)
+        merged.notified[key] = true;
+    saveLimitsState(merged);
     if (fresh.length) {
         const level = worstLevel(fresh);
         dispatchAlert(cfg, {
@@ -179,6 +204,40 @@ function captureLimits(cfg, headers, sessionId, now) {
     }
     return true;
 }
+function planIsSubscription(plan) {
+    return plan === "pro" || plan === "max5" || plan === "max20";
+}
+/**
+ * Should the dollar hard-cap 402 be suppressed for THIS proxy/request?
+ *
+ * Only for the **Anthropic** flavor — an OpenAI / other-API agent is billed per
+ * token and must keep its wall, even if a *different* (Claude Code) session once
+ * latched subscription mode on the shared `limits.json`. And only when we have a
+ * live reason to believe this is a flat-fee plan: either the operator pinned a
+ * subscription tier (`--plan`), or we saw real `unified-*` headers **recently**
+ * (within the 5-hour window). A stale, months-old detection must never disarm
+ * the wall — that's the bug this replaces (a permanent global latch).
+ *
+ * Residual edge: an Anthropic-flavor *API-key* agent run within 5h of a Claude
+ * Code subscription session (or under a pinned `--plan`) would also be
+ * suppressed. That's a narrow, opt-in-ish overlap; the common dual-use case
+ * (Claude Code + an OpenAI-flavor agent) is fully covered by the flavor gate.
+ *
+ * Trust model: in `auto` mode this trusts the upstream's `unified-*` headers, so
+ * a malicious/compromised Anthropic-compatible gateway could disarm the dollar
+ * wall by emitting fake subscription headers. That upstream already holds your
+ * API key (you pointed the proxy at it), and `net.ts` enforces https + warns on
+ * an unexpected host — so this isn't a new trust boundary. Pin `--plan` if you
+ * want suppression to be an explicit, upstream-independent choice.
+ */
+function dollarWallSuppressed(cfg, flavor, state, now) {
+    if (flavor !== "anthropic")
+        return false;
+    if (planIsSubscription(cfg.limits.plan))
+        return true;
+    const snap = state.snapshot;
+    return !!snap && now - snap.observedAt < WINDOW_MS["5h"] && !!(snap.fiveHour || snap.weekly);
+}
 export function startProxy(opts) {
     const cfg = loadConfig();
     const upstreamOrigin = assertSafeEndpoint(opts.upstream, "upstream").replace(/\/$/, "");
@@ -188,10 +247,10 @@ export function startProxy(opts) {
         const sessionId = req.headers["x-agent-guard-session"] || `proxy:${todayKey(now)}`;
         // 1) Pre-flight budget check — block before spending anything.
         // Escape hatch: while a human has paused enforcement, never block (but still meter).
-        // Subscription mode is ALERT-ONLY: once we've seen Anthropic's unified
-        // rate-limit headers, the session is on a flat-fee plan where dollars are
-        // meaningless, so we never 402 it — we only pace + warn.
-        const subscriptionMode = loadLimitsState().subscriptionDetected;
+        // Subscription mode is ALERT-ONLY: a flat-fee Pro/Max session is paced, not
+        // dollar-gated. Scope that suppression tightly (flavor + pinned plan / fresh
+        // headers) so it never disarms the wall for a genuinely-billed agent.
+        let subscriptionMode = dollarWallSuppressed(cfg, opts.flavor, loadLimitsState(), now);
         const ledger = loadLedger();
         const sessionUSD = ledger.sessions[sessionId]?.costUSD ?? 0;
         const dailyUSD = rollingDailyCost(ledger, now);
@@ -239,10 +298,13 @@ export function startProxy(opts) {
             res.end(JSON.stringify({ error: "kill-switch proxy: upstream fetch failed", detail: String(err) }));
             return;
         }
-        // 2.5) Read Anthropic's subscription rate-limit headers (alert-only).
+        // 2.5) Read Anthropic's subscription rate-limit headers (alert-only). If this
+        // response carried them, treat the session as subscription for alert purposes
+        // too — even if the pre-flight check (run before we'd seen any headers) didn't.
         if (opts.flavor === "anthropic") {
             try {
-                captureLimits(cfg, upstream.headers, sessionId, Date.now());
+                if (captureLimits(cfg, upstream.headers, sessionId, Date.now()))
+                    subscriptionMode = true;
             }
             catch {
                 /* limit capture must never break the proxied response */
@@ -284,11 +346,12 @@ export function startProxy(opts) {
                 // Re-load ledger (the request may have been concurrent) and meter.
                 const fresh = loadLedger();
                 meter(cfg, fresh, sessionId, parsed, Date.now());
-                // Post-meter soft-cap alert (once).
+                // Post-meter soft-cap alert (once). Skipped in subscription mode — the
+                // dollars are meaningless on a flat-fee plan, so a USD warn is just noise.
                 const after = fresh.sessions[sessionId]?.costUSD ?? 0;
                 const afterDaily = rollingDailyCost(fresh, Date.now());
                 const v2 = evaluate({ sessionUSD: after, dailyUSD: afterDaily }, cfg.budget);
-                if (v2.level === "warn" && !blockedNotified[`warn:${sessionId}`]) {
+                if (v2.level === "warn" && !subscriptionMode && !blockedNotified[`warn:${sessionId}`]) {
                     blockedNotified[`warn:${sessionId}`] = true;
                     dispatchAlert(cfg, {
                         ts: Date.now(), source: "proxy", sessionId, level: "warn",

package/dist/report.d.ts

@@ -11,6 +11,8 @@
 import { type SessionRecord } from "./ledger.js";
 import { type Budget, type VerdictLevel } from "./budget.js";
 import { type PacingAssessment, type PacingLevel } from "./pacing.js";
+import type { GuardConfig } from "./config.js";
+import type { Ledger } from "./ledger.js";
 export interface LimitsReport {
     /** Where the numbers came from. "none" = no data and no pinned plan to estimate from. */
     source: "headers" | "estimated" | "none";
@@ -35,6 +37,12 @@ export interface StatusReport {
     /** Subscription rate-limit pacing — present whenever we have data to show. */
     limits: LimitsReport;
 }
+/**
+ * Compute the subscription rate-limit section. Exported so the Claude Code hook
+ * can reuse its already-loaded cfg + ledger instead of paying for a second
+ * loadConfig/loadLedger on every tool call.
+ */
+export declare function buildLimitsReport(cfg: GuardConfig, ledger: Ledger, now: number): LimitsReport;
 /**
  * Render the subscription rate-limit section as plain text lines (no color), so
  * both the `agent-guard` and `ks guard` status views stay identical. Returns an

package/dist/report.js

@@ -12,25 +12,38 @@ import { loadConfig } from "./config.js";
 import { isPaused, pauseExpiry } from "./config.js";
 import { loadLedger, rollingDailyCost } from "./ledger.js";
 import { evaluate } from "./budget.js";
-import { loadLimitsState } from "./limits.js";
+import { loadLimitsState, WINDOW_MS } from "./limits.js";
 import { assessSnapshot, worstLevel } from "./pacing.js";
 import { estimateSnapshot } from "./estimate.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
-function buildLimitsReport(cfg, ledger, now) {
+/**
+ * Compute the subscription rate-limit section. Exported so the Claude Code hook
+ * can reuse its already-loaded cfg + ledger instead of paying for a second
+ * loadConfig/loadLedger on every tool call.
+ */
+export function buildLimitsReport(cfg, ledger, now) {
     const state = loadLimitsState();
     const thresholds = cfg.limits;
     const plan = cfg.limits.plan;
-    // Prefer real header data when we have it.
-    if (state.snapshot) {
-        const windows = assessSnapshot(state.snapshot, thresholds, now);
-        return {
-            source: "headers",
-            plan,
-            subscriptionDetected: state.subscriptionDetected,
-            observedAt: state.snapshot.observedAt,
-            windows,
-            level: worstLevel(windows),
-        };
+    // Prefer real header data — but only while it's still usable. A snapshot older
+    // than the weekly window is too stale to trust at all; and any single window
+    // whose reset time has already passed has since rolled over (its utilization is
+    // from a prior window), so we drop it rather than present expired numbers — and
+    // a reset time in the past — as if they were live. If nothing usable remains we
+    // fall through to the estimate (or "none").
+    const snap = state.snapshot;
+    if (snap && now - snap.observedAt < WINDOW_MS.weekly) {
+        const windows = assessSnapshot(snap, thresholds, now).filter((w) => !(w.resetAt != null && w.resetAt <= now));
+        if (windows.length) {
+            return {
+                source: "headers",
+                plan,
+                subscriptionDetected: state.subscriptionDetected,
+                observedAt: snap.observedAt,
+                windows,
+                level: worstLevel(windows),
+            };
+        }
     }
     // Otherwise estimate, but only when the user pinned a tier (opt-in, fuzzy).
     if (plan === "pro" || plan === "max5" || plan === "max20") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kill-switch/agent-guard",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Kill Switch for coding agents — stop runaway Claude Code / Cursor / Aider sessions from racking up an LLM bill. Native hook + token-metering proxy with per-session and daily-rolling budgets.",
   "type": "module",
   "bin": {