@kill-switch/agent-guard 0.1.1 → 0.1.3

package/dist/limits.js

@@ -0,0 +1,161 @@
+/**
+ * Subscription rate-limit awareness — the "how much of my Claude Code plan have
+ * I burned" half of the guard, complementary to the dollar ledger.
+ *
+ * Claude Code on a Pro/Max subscription is NOT billed per token — the scarce
+ * resource is the plan's rate-limit quota, measured in two rolling windows:
+ *   - a 5-hour window (burst protection), and
+ *   - a 7-day window (the real lockout risk, "resets a couple times a month").
+ *
+ * Anthropic reports exactly where you stand in both windows on every API
+ * response, via `anthropic-ratelimit-unified-*` headers. The proxy already sees
+ * every response, so it can read these and know the *real* remaining quota and
+ * the *real* reset times — no estimation, no guessing when limits reset.
+ *
+ * This module owns: parsing those headers into a {@link LimitSnapshot}, and the
+ * small global state file (`limits.json`) that persists the latest snapshot plus
+ * whether we've ever seen subscription headers (so the rest of the guard can
+ * switch into alert-only subscription mode).
+ *
+ * Header formats are owned by Anthropic, not us, and aren't fully contract-
+ * documented, so parsing is deliberately defensive: utilization is accepted as
+ * 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, 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,
+    weekly: 7 * 24 * 60 * 60 * 1000,
+};
+export function emptyLimitsState() {
+    return { version: 1, subscriptionDetected: false, snapshot: null, notified: {} };
+}
+export function loadLimitsState() {
+    try {
+        const data = JSON.parse(readFileSync(limitsPath(), "utf8"));
+        if (data && data.version === 1) {
+            return {
+                version: 1,
+                subscriptionDetected: data.subscriptionDetected ?? false,
+                snapshot: data.snapshot ?? null,
+                notified: data.notified ?? {},
+                headersLoggedAt: data.headersLoggedAt,
+            };
+        }
+    }
+    catch {
+        /* fall through to empty */
+    }
+    return emptyLimitsState();
+}
+export function saveLimitsState(state) {
+    ensureGuardDir();
+    const path = limitsPath();
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2));
+    renameSync(tmp, path);
+}
+/** Wrap a plain `Record<string,string>` so it satisfies {@link HeaderGetter}. */
+export function recordHeaders(rec) {
+    const lower = {};
+    for (const [k, v] of Object.entries(rec)) {
+        if (v === undefined)
+            continue;
+        lower[k.toLowerCase()] = Array.isArray(v) ? v.join(", ") : v;
+    }
+    return { get: (name) => lower[name.toLowerCase()] ?? null };
+}
+/**
+ * Parse a utilization header value into a 0–1 fraction.
+ * Accepts "0.62", "62", "62%". Values >1.5 are treated as percentages.
+ */
+export function parseUtilization(raw) {
+    if (raw == null)
+        return null;
+    const n = Number(String(raw).replace(/%$/, "").trim());
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    const frac = n > 1.5 ? n / 100 : n;
+    return Math.max(0, Math.min(1, frac));
+}
+/**
+ * Parse a reset header value into an absolute epoch-ms timestamp.
+ * Accepts ISO 8601 ("2026-06-13T18:00:00Z"), epoch seconds, epoch ms, or a
+ * relative seconds-until-reset (small numbers). `now` anchors the relative case.
+ */
+export function parseReset(raw, now) {
+    if (raw == null)
+        return null;
+    const s = String(raw).trim();
+    if (!s)
+        return null;
+    // Numeric: disambiguate ms / seconds / relative-seconds by magnitude.
+    if (/^\d+(\.\d+)?$/.test(s)) {
+        const n = Number(s);
+        if (!Number.isFinite(n))
+            return null;
+        if (n > 1e12)
+            return Math.round(n); // epoch ms
+        if (n > 1e9)
+            return Math.round(n * 1000); // epoch seconds
+        return Math.round(now + n * 1000); // relative seconds-until-reset
+    }
+    const t = Date.parse(s);
+    return Number.isNaN(t) ? null : t;
+}
+function parseWindow(h, prefix, key, now) {
+    const util = parseUtilization(h.get(`${prefix}-${key === "5h" ? "5h" : "7d"}-utilization`));
+    const reset = parseReset(h.get(`${prefix}-${key === "5h" ? "5h" : "7d"}-reset`), now);
+    const status = h.get(`${prefix}-${key === "5h" ? "5h" : "7d"}-status`) || undefined;
+    if (util == null && reset == null && !status)
+        return null;
+    return { utilization: util ?? 0, resetAt: reset, status };
+}
+/**
+ * Read the `anthropic-ratelimit-unified-*` family into a {@link LimitSnapshot}.
+ * Returns null when no unified headers are present (i.e. not a subscription
+ * session, or an endpoint that doesn't emit them) — callers use that null to
+ * mean "stay in dollar mode for this response".
+ */
+export function parseUnifiedHeaders(h, now) {
+    const prefix = "anthropic-ratelimit-unified";
+    const fiveHour = parseWindow(h, prefix, "5h", now);
+    const weekly = parseWindow(h, prefix, "weekly", now);
+    const status = h.get(`${prefix}-status`) || null;
+    if (!fiveHour && !weekly && !status)
+        return null;
+    return { fiveHour, weekly, status, observedAt: now };
+}
+/** Stable dedup key for a pacing alert: re-alerts when the window resets. */
+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.
+ */
+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"))
+            out[key] = Array.isArray(v) ? v.join(", ") : v;
+    }
+    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

@@ -3,6 +3,7 @@
  * subcommands, so both drive the same logic instead of duplicating it (or
  * shelling out). Pure side-effecting helpers over config + Claude Code settings.
  */
+import { type LimitsConfig } from "./config.js";
 import type { Budget } from "./budget.js";
 export interface InstallOptions {
     /** Install into ~/.claude/settings.json instead of ./.claude/settings.json */
@@ -33,6 +34,17 @@ export interface BudgetPatch {
 }
 /** Write budget/webhook overrides to the config file. Returns the saved budget. */
 export declare function setBudget(patch: BudgetPatch): Budget;
+/** Partial subscription-limits update. Merges onto the existing config file. */
+export interface LimitsPatch {
+    plan?: LimitsConfig["plan"];
+    fiveHourSoftPct?: number;
+    fiveHourDangerPct?: number;
+    weeklySoftPct?: number;
+    weeklyDangerPct?: number;
+    burnRatioWarn?: number;
+}
+/** 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. */
 export declare function resetLedger(opts: {
     all?: boolean;

package/dist/ops.js

@@ -6,7 +6,7 @@
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
-import { configPath, ensureGuardDir, DEFAULT_BUDGET } from "./config.js";
+import { configPath, ensureGuardDir, DEFAULT_BUDGET, DEFAULT_LIMITS } from "./config.js";
 import { loadLedger, saveLedger, emptyLedger } from "./ledger.js";
 /**
  * Wire the agent-guard hook into Claude Code settings for PreToolUse,
@@ -73,6 +73,32 @@ export function setBudget(patch) {
     writeFileSync(configPath(), JSON.stringify(file, null, 2) + "\n");
     return budget;
 }
+/** Write subscription-limit overrides to the config file. Returns the saved limits. */
+export function setLimits(patch) {
+    let file = {};
+    try {
+        file = JSON.parse(readFileSync(configPath(), "utf8"));
+    }
+    catch {
+        /* new */
+    }
+    const limits = { ...DEFAULT_LIMITS, ...(file.limits ?? {}) };
+    if (patch.plan && ["auto", "pro", "max5", "max20"].includes(patch.plan))
+        limits.plan = patch.plan;
+    const setPct = (k, v) => {
+        if (v !== undefined && Number.isFinite(v))
+            limits[k] = v;
+    };
+    setPct("fiveHourSoftPct", patch.fiveHourSoftPct);
+    setPct("fiveHourDangerPct", patch.fiveHourDangerPct);
+    setPct("weeklySoftPct", patch.weeklySoftPct);
+    setPct("weeklyDangerPct", patch.weeklyDangerPct);
+    setPct("burnRatioWarn", patch.burnRatioWarn);
+    file.limits = limits;
+    ensureGuardDir();
+    writeFileSync(configPath(), JSON.stringify(file, null, 2) + "\n");
+    return limits;
+}
 /** Clear the spend ledger. Scope: all | a single session | today's sessions. */
 export function resetLedger(opts) {
     if (opts.all) {

package/dist/pacing.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pacing engine — the "intelligent" half the user asked for.
+ *
+ * Blocking at "90% of weekly" is dumb: 90% on day 6 is fine, but 60% on day 2
+ * means you'll be locked out mid-week. The resource you're spending is a budget
+ * that should last until the window resets, so the real question isn't "how much
+ * is left" — it's "at this burn rate, will I run out before the window resets?".
+ *
+ * For each window we compute:
+ *   - expected utilization = fraction of the window already elapsed
+ *   - burn ratio           = actual / expected   (1.0 = perfectly on pace)
+ *   - projected exhaustion  = when utilization hits 1.0 at the current rate
+ *   - will-lock-out-before-reset = exhaustion lands before the reset
+ *
+ * The level (ok / warn / danger) is the worse of two signals: absolute
+ * utilization against soft/danger thresholds, and pacing (burning fast enough to
+ * lock out before reset). In subscription mode the guard never blocks on this —
+ * it surfaces the assessment as a warning so the human can ease off or switch to
+ * a cheaper model before Anthropic's own limit stops them mid-task.
+ */
+import { type LimitSnapshot, type LimitWindow, type WindowState } from "./limits.js";
+export interface PacingThresholds {
+    /** Per-window soft / danger utilization thresholds (0–1). */
+    fiveHourSoftPct: number;
+    fiveHourDangerPct: number;
+    weeklySoftPct: number;
+    weeklyDangerPct: number;
+    /** Burn ratio above which pacing alone escalates (with meaningful utilization). */
+    burnRatioWarn: number;
+}
+export type PacingLevel = "ok" | "warn" | "danger";
+export interface PacingAssessment {
+    window: LimitWindow;
+    /** 0–1 fraction of the window consumed. */
+    utilization: number;
+    /** Epoch ms the window resets, or null if unknown. */
+    resetAt: number | null;
+    /** actual / expected utilization; null when elapsed is unknown (no reset time). */
+    burnRatio: number | null;
+    /** Epoch ms we project utilization hits 100% at the current rate, or null. */
+    projectedExhaustionAt: number | null;
+    /** True when projected exhaustion lands before the window resets. */
+    willLockOutBeforeReset: boolean;
+    level: PacingLevel;
+    /** One-line human summary. */
+    message: string;
+}
+/** Assess a single window's pacing. `now` is epoch ms. */
+export declare function assessWindow(window: LimitWindow, state: WindowState, thresholds: PacingThresholds, now: number): PacingAssessment;
+/** Assess every window present in a snapshot. */
+export declare function assessSnapshot(snap: LimitSnapshot, thresholds: PacingThresholds, now: number): PacingAssessment[];
+/** Worst level across a set of assessments. */
+export declare function worstLevel(assessments: PacingAssessment[]): PacingLevel;

package/dist/pacing.js

@@ -0,0 +1,127 @@
+/**
+ * Pacing engine — the "intelligent" half the user asked for.
+ *
+ * Blocking at "90% of weekly" is dumb: 90% on day 6 is fine, but 60% on day 2
+ * means you'll be locked out mid-week. The resource you're spending is a budget
+ * that should last until the window resets, so the real question isn't "how much
+ * is left" — it's "at this burn rate, will I run out before the window resets?".
+ *
+ * For each window we compute:
+ *   - expected utilization = fraction of the window already elapsed
+ *   - burn ratio           = actual / expected   (1.0 = perfectly on pace)
+ *   - projected exhaustion  = when utilization hits 1.0 at the current rate
+ *   - will-lock-out-before-reset = exhaustion lands before the reset
+ *
+ * The level (ok / warn / danger) is the worse of two signals: absolute
+ * utilization against soft/danger thresholds, and pacing (burning fast enough to
+ * lock out before reset). In subscription mode the guard never blocks on this —
+ * it surfaces the assessment as a warning so the human can ease off or switch to
+ * a cheaper model before Anthropic's own limit stops them mid-task.
+ */
+import { WINDOW_MS } from "./limits.js";
+function windowLabel(w) {
+    return w === "5h" ? "5-hour" : "weekly";
+}
+function fmtClock(epochMs, now) {
+    const dt = new Date(epochMs);
+    const sameDay = new Date(now).toDateString() === dt.toDateString();
+    // Day-of-week + time reads naturally for a multi-day weekly window.
+    return sameDay
+        ? dt.toLocaleTimeString([], { hour: "numeric", minute: "2-digit" })
+        : dt.toLocaleString([], { weekday: "short", hour: "numeric", minute: "2-digit" });
+}
+function fmtDuration(ms) {
+    if (ms <= 0)
+        return "now";
+    const h = ms / (60 * 60 * 1000);
+    if (h < 1)
+        return `${Math.round(ms / 60000)}m`;
+    if (h < 24)
+        return `${h.toFixed(h < 10 ? 1 : 0)}h`;
+    return `${(h / 24).toFixed(1)}d`;
+}
+/** Assess a single window's pacing. `now` is epoch ms. */
+export function assessWindow(window, state, thresholds, now) {
+    const util = Math.max(0, Math.min(1, state.utilization));
+    const soft = window === "5h" ? thresholds.fiveHourSoftPct : thresholds.weeklySoftPct;
+    const danger = window === "5h" ? thresholds.fiveHourDangerPct : thresholds.weeklyDangerPct;
+    const duration = WINDOW_MS[window];
+    // elapsed = duration - timeUntilReset; only known when we have a reset time.
+    let elapsed = null;
+    if (state.resetAt != null) {
+        const untilReset = state.resetAt - now;
+        elapsed = Math.max(0, Math.min(duration, duration - untilReset));
+    }
+    let burnRatio = null;
+    let projectedExhaustionAt = null;
+    let willLockOut = false;
+    if (elapsed != null && elapsed > 0) {
+        const expected = elapsed / duration;
+        burnRatio = expected > 0 ? util / expected : null;
+        if (util > 0 && util < 1) {
+            const ratePerMs = util / elapsed; // utilization per ms so far
+            const msToFull = (1 - util) / ratePerMs;
+            projectedExhaustionAt = now + msToFull;
+            if (state.resetAt != null)
+                willLockOut = projectedExhaustionAt < state.resetAt;
+        }
+        else if (util >= 1) {
+            projectedExhaustionAt = now;
+            willLockOut = true;
+        }
+    }
+    // Level: worse of absolute-utilization and pacing signals. A projected lockout
+    // only escalates once you've used a meaningful slice of the window — otherwise
+    // tiny noise near a linear burn (e.g. 15% used, exhaustion landing a few hours
+    // before a reset days away) would scream danger far too early. We gate it at
+    // half the soft threshold.
+    const lockoutFloor = soft * 0.5;
+    const lockoutMatters = willLockOut && util >= lockoutFloor;
+    let level = "ok";
+    if (util >= danger || (lockoutMatters && util >= soft))
+        level = "danger";
+    else if (util >= soft ||
+        lockoutMatters ||
+        (burnRatio != null && burnRatio >= thresholds.burnRatioWarn && util >= lockoutFloor))
+        level = "warn";
+    const pct = Math.round(util * 100);
+    const label = windowLabel(window);
+    const parts = [`${label} limit ${pct}% used`];
+    if (state.resetAt != null)
+        parts.push(`resets ${fmtClock(state.resetAt, now)}`);
+    if (burnRatio != null && burnRatio >= 1.2 && level !== "ok")
+        parts.push(`burning ${burnRatio.toFixed(1)}× pace`);
+    // Only surface the lockout projection once it actually drives the level —
+    // keeps low-utilization projection noise out of the message.
+    if (lockoutMatters && projectedExhaustionAt != null && state.resetAt != null) {
+        const before = state.resetAt - projectedExhaustionAt;
+        parts.push(`→ lockout in ~${fmtDuration(projectedExhaustionAt - now)} (${fmtDuration(before)} before reset)`);
+    }
+    return {
+        window,
+        utilization: util,
+        resetAt: state.resetAt,
+        burnRatio,
+        projectedExhaustionAt,
+        willLockOutBeforeReset: willLockOut,
+        level,
+        message: parts.join(", "),
+    };
+}
+/** Assess every window present in a snapshot. */
+export function assessSnapshot(snap, thresholds, now) {
+    const out = [];
+    if (snap.fiveHour)
+        out.push(assessWindow("5h", snap.fiveHour, thresholds, now));
+    if (snap.weekly)
+        out.push(assessWindow("weekly", snap.weekly, thresholds, now));
+    return out;
+}
+/** Worst level across a set of assessments. */
+export function worstLevel(assessments) {
+    if (assessments.some((a) => a.level === "danger"))
+        return "danger";
+    if (assessments.some((a) => a.level === "warn"))
+        return "warn";
+    return "ok";
+}

package/dist/proxy.js

@@ -24,6 +24,8 @@ 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, recordHeaders, unifiedHeaderDump, logUnifiedHeaders, loadLimitsState, saveLimitsState, limitNotifyKey, } from "./limits.js";
+import { assessSnapshot, worstLevel } from "./pacing.js";
 const UPSTREAMS = {
     anthropic: "https://api.anthropic.com",
     openai: "https://api.openai.com",
@@ -134,6 +136,59 @@ function meter(cfg, ledger, sessionId, parsed, now) {
     prune(ledger, now);
     saveLedger(ledger);
 }
+/**
+ * Read Anthropic's `unified-*` rate-limit headers off a response, persist the
+ * snapshot, latch subscription mode on, and fire a deduped pacing alert when a
+ * window crosses into warn/danger. Returns true if subscription headers were
+ * seen. Alert-only by design — this never blocks (a subscription session already
+ * paid a flat fee; the scarce resource is quota, and Anthropic's own limit is
+ * the real wall).
+ */
+function captureLimits(cfg, headers, sessionId, 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();
+    // Write-once raw-header diagnostic for format verification (`cat events.jsonl`).
+    if (!state.headersLoggedAt) {
+        logUnifiedHeaders(unifiedHeaderDump(rec), now);
+        state.headersLoggedAt = now;
+    }
+    state.subscriptionDetected = true;
+    state.snapshot = snap;
+    const assessments = assessSnapshot(snap, cfg.limits, now);
+    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;
+        return true;
+    });
+    saveLimitsState(state);
+    if (fresh.length) {
+        const level = worstLevel(fresh);
+        dispatchAlert(cfg, {
+            ts: now,
+            source: "proxy",
+            kind: "limit",
+            sessionId,
+            level: level === "danger" ? "danger" : "warn",
+            sessionUSD: 0,
+            dailyUSD: 0,
+            reasons: fresh.map((a) => a.message),
+            action: level === "danger" ? "on pace to lock out before reset" : "approaching plan limit",
+            limits: fresh.map((a) => ({ window: a.window, utilization: a.utilization, resetAt: a.resetAt, level: a.level })),
+        }).catch(() => { });
+    }
+    return true;
+}
 export function startProxy(opts) {
     const cfg = loadConfig();
     const upstreamOrigin = assertSafeEndpoint(opts.upstream, "upstream").replace(/\/$/, "");
@@ -143,11 +198,15 @@ 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;
         const ledger = loadLedger();
         const sessionUSD = ledger.sessions[sessionId]?.costUSD ?? 0;
         const dailyUSD = rollingDailyCost(ledger, now);
         const verdict = evaluate({ sessionUSD, dailyUSD }, cfg.budget);
-        if (verdict.level === "block" && !isPaused(now)) {
+        if (verdict.level === "block" && !isPaused(now) && !subscriptionMode) {
             if (!blockedNotified[sessionId]) {
                 blockedNotified[sessionId] = true;
                 dispatchAlert(cfg, {
@@ -190,6 +249,15 @@ 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).
+        if (opts.flavor === "anthropic") {
+            try {
+                captureLimits(cfg, upstream.headers, sessionId, Date.now());
+            }
+            catch {
+                /* limit capture must never break the proxied response */
+            }
+        }
         // 3) Relay status + headers.
         const respHeaders = {};
         upstream.headers.forEach((v, k) => {
@@ -248,6 +316,9 @@ export function startProxy(opts) {
     server.listen(opts.port, "127.0.0.1", () => {
         process.stdout.write(`🛡  agent-guard proxy on http://localhost:${opts.port} → ${upstreamOrigin} (${opts.flavor})\n` +
             `   Caps: session hard ${fmtUSD(cfg.budget.sessionHardUSD)}, daily hard ${fmtUSD(cfg.budget.dailyHardUSD)}\n` +
+            (opts.flavor === "anthropic"
+                ? `   Subscription mode: reads Anthropic rate-limit headers → paces your Pro/Max plan (alert-only)\n`
+                : "") +
             `   Point your agent at it, e.g.:\n` +
             (opts.flavor === "anthropic"
                 ? `     ANTHROPIC_BASE_URL=http://localhost:${opts.port} claude\n`

package/dist/report.d.ts

@@ -1,9 +1,26 @@
 /**
  * Shared status report — the single computation behind `agent-guard status` and
  * `ks guard status`, so both emit an identical JSON shape and never drift.
+ *
+ * Two halves:
+ *   - the dollar budget (session + daily-rolling), always present; and
+ *   - the subscription rate-limit standing (5-hour + weekly pacing), present
+ *     once we've seen Anthropic's unified headers via the proxy, or estimated
+ *     when the user has pinned a plan tier. Alert-only — never blocks.
  */
 import { type SessionRecord } from "./ledger.js";
 import { type Budget, type VerdictLevel } from "./budget.js";
+import { type PacingAssessment, type PacingLevel } from "./pacing.js";
+export interface LimitsReport {
+    /** Where the numbers came from. "none" = no data and no pinned plan to estimate from. */
+    source: "headers" | "estimated" | "none";
+    plan: string;
+    subscriptionDetected: boolean;
+    /** Epoch ms the snapshot was observed (headers) or computed (estimated). */
+    observedAt: number | null;
+    windows: PacingAssessment[];
+    level: PacingLevel;
+}
 export interface StatusReport {
     budget: Budget;
     dailyUSD: number;
@@ -15,6 +32,14 @@ export interface StatusReport {
     sessions: Array<{
         id: string;
     } & SessionRecord>;
+    /** Subscription rate-limit pacing — present whenever we have data to show. */
+    limits: 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
+ * empty array when there's nothing useful to show.
+ */
+export declare function formatLimitsLines(limits: LimitsReport, now?: number): string[];
 /** Build the current status report from the on-disk config + ledger. */
 export declare function buildStatusReport(now?: number): StatusReport;

package/dist/report.js

@@ -1,12 +1,101 @@
 /**
  * Shared status report — the single computation behind `agent-guard status` and
  * `ks guard status`, so both emit an identical JSON shape and never drift.
+ *
+ * Two halves:
+ *   - the dollar budget (session + daily-rolling), always present; and
+ *   - the subscription rate-limit standing (5-hour + weekly pacing), present
+ *     once we've seen Anthropic's unified headers via the proxy, or estimated
+ *     when the user has pinned a plan tier. Alert-only — never blocks.
  */
 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 { assessSnapshot, worstLevel } from "./pacing.js";
+import { estimateSnapshot } from "./estimate.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
+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),
+        };
+    }
+    // Otherwise estimate, but only when the user pinned a tier (opt-in, fuzzy).
+    if (plan === "pro" || plan === "max5" || plan === "max20") {
+        const snap = estimateSnapshot(ledger, plan, now);
+        const windows = assessSnapshot(snap, thresholds, now);
+        return {
+            source: "estimated",
+            plan,
+            subscriptionDetected: state.subscriptionDetected,
+            observedAt: snap.observedAt,
+            windows,
+            level: worstLevel(windows),
+        };
+    }
+    return {
+        source: "none",
+        plan,
+        subscriptionDetected: state.subscriptionDetected,
+        observedAt: null,
+        windows: [],
+        level: "ok",
+    };
+}
+function bar(frac) {
+    const pct = Math.max(0, Math.min(100, Math.round(frac * 100)));
+    const filled = Math.round(pct / 5);
+    return `[${"█".repeat(filled)}${"░".repeat(20 - filled)}]`;
+}
+function ageString(observedAt, now) {
+    const ms = now - observedAt;
+    if (ms < 60_000)
+        return "just now";
+    if (ms < 3_600_000)
+        return `${Math.round(ms / 60_000)}m ago`;
+    if (ms < 86_400_000)
+        return `${Math.round(ms / 3_600_000)}h ago`;
+    return `${Math.round(ms / 86_400_000)}d ago`;
+}
+/**
+ * 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
+ * empty array when there's nothing useful to show.
+ */
+export function formatLimitsLines(limits, now = Date.now()) {
+    if (limits.source === "none") {
+        // Only nudge if they haven't opted into either path.
+        if (!limits.subscriptionDetected) {
+            return [
+                "Claude Code plan limits: unknown.",
+                "  Run `ks guard proxy` and point Claude Code at it for exact 5-hour + weekly usage,",
+                "  or set your tier (`ks guard config --plan max5`) for an estimate.",
+            ];
+        }
+        return [];
+    }
+    const icon = limits.level === "danger" ? "🟥" : limits.level === "warn" ? "🟡" : "🟢";
+    const tag = limits.source === "estimated" ? " (estimated — run the proxy for exact)" : "";
+    const lines = [`${icon} Claude Code plan limits${tag}  ·  observed ${limits.observedAt ? ageString(limits.observedAt, now) : "—"}`];
+    for (const w of limits.windows) {
+        // w.message already leads with "<window> limit NN% used, …", so the bar
+        // carries the visual and the message carries the numbers + pacing.
+        lines.push(`  ${bar(w.utilization)}  ${w.message}`);
+    }
+    return lines;
+}
 /** Build the current status report from the on-disk config + ledger. */
 export function buildStatusReport(now = Date.now()) {
     const cfg = loadConfig();
@@ -26,5 +115,6 @@ export function buildStatusReport(now = Date.now()) {
         paused: isPaused(now),
         pauseUntil: pauseExpiry(),
         sessions,
+        limits: buildLimitsReport(cfg, ledger, now),
     };
 }