@kill-switch/agent-guard 0.1.1 → 0.1.3

package/README.md

@@ -107,6 +107,59 @@ AGENT_GUARD_SESSION_HARD=10 claude          # one-off $10 ceiling
 
 A cap of `0` disables that check.
 
+## Subscription limits (Claude Code Pro / Max)
+
+Dollar caps are the wrong currency for a **Pro/Max subscription**: you pay a flat fee, so the
+scarce resource isn't dollars — it's your plan's rate-limit quota, in two rolling windows:
+
+- a **5-hour** window (burst protection), and
+- a **weekly** (7-day) window — the real lockout risk, "resets a couple times a month".
+
+Anthropic reports exactly where you stand on every response via `anthropic-ratelimit-unified-*`
+headers. Run Claude Code **through the proxy** and agent-guard reads them — no estimation:
+
+```sh
+agent-guard proxy                                    # meters Anthropic + reads limit headers
+ANTHROPIC_BASE_URL=http://localhost:8787 claude
+```
+
+Once those headers are seen, the session is in **subscription mode**: alert-only. agent-guard
+**never blocks** a flat-fee plan (you already paid; Anthropic's own limit is the real wall) —
+instead it *paces* you. For each window it computes burn-rate vs. a sustainable pace and
+projects whether you'll exhaust the window **before it resets**, then warns in-session and via
+your alert channels:
+
+```
+🟥 Claude Code plan limits  ·  observed just now
+  [████████████░░░░░░░░]  weekly limit 62% used, resets Sat 6:00 PM, burning 3.1× pace,
+                          → lockout in ~14h (5.1d before reset)
+```
+
+`status` shows it; the hook injects it into the session even when only the hook is running
+(it reads the snapshot the proxy persisted). No proxy and want a rough read? Pin your tier and
+agent-guard *estimates* from the ledger (clearly labelled, never blocks):
+
+```sh
+ks guard config --plan max5        # auto | pro | max5 | max20
+```
+
+Tune the thresholds (0–1 utilization) if the defaults are too eager:
+
+| Setting | Meaning | Default |
+|---|---|---|
+| `--plan` (`AGENT_GUARD_PLAN`) | `auto` (headers only) or a tier for estimation | `auto` |
+| `--weekly-soft` / `--weekly-danger` | weekly warn / danger utilization | 0.6 / 0.85 |
+| `--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`.
+
+> 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.
+
 ## Alerts
 
 On the first soft/hard trip per scope, agent-guard:
@@ -132,8 +185,9 @@ rates so the guard never *under*-counts. Override any model in
 ```
 agent-guard install [--global] [--command <cmd>]   wire the Claude Code hook
 agent-guard proxy   [--port 8787] [--flavor anthropic|openai] [--upstream URL]
-agent-guard status  [--json]                        spend vs budget
+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 hook                                    (internal) Claude Code entrypoint
 ```

package/dist/alert.d.ts

@@ -11,17 +11,27 @@
  * delay (or crash) the agent's tool call.
  */
 import { type GuardConfig } from "./config.js";
-import type { Verdict } from "./budget.js";
+/** Spend verdicts are ok/warn/block; pacing assessments are ok/warn/danger. */
+export type AlertLevel = "ok" | "warn" | "block" | "danger";
 export interface AlertEvent {
     ts: number;
     source: "hook" | "proxy";
+    /** "spend" = dollar budget trip (default); "limit" = subscription pacing alert. */
+    kind?: "spend" | "limit";
     sessionId: string;
-    level: Verdict["level"];
+    level: AlertLevel;
     sessionUSD: number;
     dailyUSD: number;
     reasons: string[];
     action: string;
     cwd?: string;
+    /** For kind:"limit" — per-window utilization summary (0–1) for the payload. */
+    limits?: Array<{
+        window: string;
+        utilization: number;
+        resetAt: number | null;
+        level: string;
+    }>;
 }
 /** Dispatch an alert across all configured channels. Resolves once all attempts settle. */
 export declare function dispatchAlert(cfg: GuardConfig, evt: AlertEvent): Promise<void>;

package/dist/alert.js

@@ -43,6 +43,17 @@ function writeLocal(evt) {
     }
 }
 function slackText(evt) {
+    if (evt.kind === "limit") {
+        const icon = evt.level === "danger" ? "🟥" : "🟡";
+        return [
+            `${icon} *Kill Switch — Claude Code subscription pacing*`,
+            `• Status: ${evt.action}`,
+            evt.cwd ? `• Project: \`${evt.cwd}\`` : "",
+            ...evt.reasons.map((r) => `• ${r}`),
+        ]
+            .filter(Boolean)
+            .join("\n");
+    }
     const icon = evt.level === "block" ? "🛑" : "⚠️";
     const verb = evt.level === "block" ? "BLOCKED a coding agent" : "warning on a coding agent";
     return [

package/dist/cli.js

@@ -17,7 +17,8 @@ import { loadConfig, configPath, isPaused, pauseExpiry, writePause, clearPause,
 import { loadLedger, rollingDailyCost } from "./ledger.js";
 import { evaluate } from "./budget.js";
 import { fmtUSD } from "./cost.js";
-import { installHook, setBudget, resetLedger } from "./ops.js";
+import { installHook, setBudget, setLimits, resetLedger } from "./ops.js";
+import { buildStatusReport, formatLimitsLines } from "./report.js";
 const program = new Command();
 program
     .name("agent-guard")
@@ -77,6 +78,7 @@ program
             verdict: verdict.level,
             reasons: verdict.reasons,
             sessions: sessions.map(([id, s]) => ({ id, ...s })),
+            limits: buildStatusReport(now).limits,
         }, null, 2));
         return;
     }
@@ -109,6 +111,13 @@ program
         for (const r of verdict.reasons)
             console.log(`  • ${r}`);
     }
+    // Subscription rate-limit pacing (Claude Code Pro/Max).
+    const limitLines = formatLimitsLines(buildStatusReport(now).limits, now);
+    if (limitLines.length) {
+        console.log("");
+        for (const line of limitLines)
+            console.log(line);
+    }
 });
 // ── pause / resume (escape hatch) ────────────────────────────────────────────
 program
@@ -153,31 +162,53 @@ program
 // ── config ───────────────────────────────────────────────────────────────────
 program
     .command("config")
-    .description("View or set budget caps (written to ~/.kill-switch/agent-guard/config.json)")
+    .description("View or set budget caps + Claude Code plan limits (written to ~/.kill-switch/agent-guard/config.json)")
     .option("--session-soft <usd>", "Per-session soft cap (warn)")
     .option("--session-hard <usd>", "Per-session hard cap (block)")
     .option("--daily-soft <usd>", "Daily rolling soft cap (warn)")
     .option("--daily-hard <usd>", "Daily rolling hard cap (block)")
     .option("--slack-webhook <url>", "Slack incoming-webhook for breach alerts")
+    .option("--plan <tier>", "Claude Code plan: auto | pro | max5 | max20 (subscription limit awareness)")
+    .option("--weekly-soft <pct>", "Weekly limit soft threshold, 0–1 (warn)")
+    .option("--weekly-danger <pct>", "Weekly limit danger threshold, 0–1")
+    .option("--5h-soft <pct>", "5-hour limit soft threshold, 0–1 (warn)")
+    .option("--5h-danger <pct>", "5-hour limit danger threshold, 0–1")
+    .option("--burn-ratio <n>", "Burn-rate multiplier that triggers a pacing warning")
     .action((opts) => {
-    const anySet = ["sessionSoft", "sessionHard", "dailySoft", "dailyHard", "slackWebhook"]
-        .some((k) => opts[k] !== undefined);
-    if (!anySet) {
+    const budgetKeys = ["sessionSoft", "sessionHard", "dailySoft", "dailyHard", "slackWebhook"];
+    const limitKeys = ["plan", "weeklySoft", "weeklyDanger", "5hSoft", "5hDanger", "burnRatio"];
+    const anyBudget = budgetKeys.some((k) => opts[k] !== undefined);
+    const anyLimit = limitKeys.some((k) => opts[k] !== undefined);
+    if (!anyBudget && !anyLimit) {
         const cfg = loadConfig();
-        console.log(JSON.stringify({ budget: cfg.budget, slackWebhook: cfg.slackWebhook ? "(set)" : undefined }, null, 2));
+        console.log(JSON.stringify({ budget: cfg.budget, limits: cfg.limits, slackWebhook: cfg.slackWebhook ? "(set)" : undefined }, null, 2));
         console.log(`\nConfig file: ${configPath()}`);
         return;
     }
     const num = (v) => (v !== undefined ? Number(v) : undefined);
-    const budget = setBudget({
-        sessionSoftUSD: num(opts.sessionSoft),
-        sessionHardUSD: num(opts.sessionHard),
-        dailySoftUSD: num(opts.dailySoft),
-        dailyHardUSD: num(opts.dailyHard),
-        slackWebhook: opts.slackWebhook,
-    });
-    console.log(`✅ Saved → ${configPath()}`);
-    console.log(JSON.stringify(budget, null, 2));
+    if (anyBudget) {
+        const budget = setBudget({
+            sessionSoftUSD: num(opts.sessionSoft),
+            sessionHardUSD: num(opts.sessionHard),
+            dailySoftUSD: num(opts.dailySoft),
+            dailyHardUSD: num(opts.dailyHard),
+            slackWebhook: opts.slackWebhook,
+        });
+        console.log(`✅ Budget saved → ${configPath()}`);
+        console.log(JSON.stringify(budget, null, 2));
+    }
+    if (anyLimit) {
+        const limits = setLimits({
+            plan: opts.plan,
+            weeklySoftPct: num(opts.weeklySoft),
+            weeklyDangerPct: num(opts.weeklyDanger),
+            fiveHourSoftPct: num(opts["5hSoft"]),
+            fiveHourDangerPct: num(opts["5hDanger"]),
+            burnRatioWarn: num(opts.burnRatio),
+        });
+        console.log(`✅ Plan limits saved → ${configPath()}`);
+        console.log(JSON.stringify(limits, null, 2));
+    }
 });
 // ── reset ────────────────────────────────────────────────────────────────────
 program

package/dist/config.d.ts

@@ -8,8 +8,30 @@
  */
 import type { Budget } from "./budget.js";
 import type { ModelPricing } from "./pricing.js";
+/**
+ * Subscription rate-limit config. Separate from the dollar {@link Budget}
+ * because a Claude Code Pro/Max session pays a flat fee — the scarce resource is
+ * the plan's 5-hour and weekly quota, not dollars. This is alert-only: the guard
+ * never blocks on these (you already paid), it just warns before you lock out.
+ */
+export interface LimitsConfig {
+    /**
+     * Plan tier. "auto" = derive everything from observed `unified-*` headers
+     * (proxy path); a pinned tier additionally enables hook-only estimation when
+     * no fresh header snapshot exists. See estimate.ts.
+     */
+    plan: "auto" | "pro" | "max5" | "max20";
+    /** Per-window soft (warn) / danger thresholds, as 0–1 utilization fractions. */
+    fiveHourSoftPct: number;
+    fiveHourDangerPct: number;
+    weeklySoftPct: number;
+    weeklyDangerPct: number;
+    /** Burn ratio (actual/expected pace) above which we escalate on pacing alone. */
+    burnRatioWarn: number;
+}
 export interface GuardConfig {
     budget: Budget;
+    limits: LimitsConfig;
     /** Optional pricing overrides merged onto the built-in table. */
     pricingOverrides?: Record<string, ModelPricing>;
     /** Kill Switch API key (ks_live_…) for reporting kill events to Guardian. */
@@ -20,6 +42,7 @@ export interface GuardConfig {
     slackWebhook?: string;
 }
 export declare const DEFAULT_BUDGET: Budget;
+export declare const DEFAULT_LIMITS: LimitsConfig;
 /** ~/.kill-switch/agent-guard — created on demand. */
 export declare function guardDir(): string;
 export declare function ensureGuardDir(): string;
@@ -27,6 +50,8 @@ export declare const ledgerPath: () => string;
 export declare const configPath: () => string;
 export declare const pricingPath: () => string;
 export declare const eventsPath: () => string;
+/** Subscription rate-limit state (latest unified-header snapshot + dedup). */
+export declare const limitsPath: () => string;
 /**
  * Escape hatch. The hook/proxy fail OPEN while this sentinel exists, so a human
  * can always disable enforcement from outside the agent loop — even with zero

package/dist/config.js

@@ -15,6 +15,14 @@ export const DEFAULT_BUDGET = {
     dailySoftUSD: 25,
     dailyHardUSD: 100,
 };
+export const DEFAULT_LIMITS = {
+    plan: "auto",
+    fiveHourSoftPct: 0.7,
+    fiveHourDangerPct: 0.9,
+    weeklySoftPct: 0.6,
+    weeklyDangerPct: 0.85,
+    burnRatioWarn: 1.5,
+};
 /** ~/.kill-switch/agent-guard — created on demand. */
 export function guardDir() {
     return join(homedir(), ".kill-switch", "agent-guard");
@@ -28,6 +36,8 @@ export const ledgerPath = () => join(guardDir(), "ledger.json");
 export const configPath = () => join(guardDir(), "config.json");
 export const pricingPath = () => join(guardDir(), "pricing.json");
 export const eventsPath = () => join(guardDir(), "events.jsonl");
+/** Subscription rate-limit state (latest unified-header snapshot + dedup). */
+export const limitsPath = () => join(guardDir(), "limits.json");
 /**
  * Escape hatch. The hook/proxy fail OPEN while this sentinel exists, so a human
  * can always disable enforcement from outside the agent loop — even with zero
@@ -95,8 +105,20 @@ export function loadConfig() {
         dailySoftUSD: num(process.env.AGENT_GUARD_DAILY_SOFT, fileBudget.dailySoftUSD ?? DEFAULT_BUDGET.dailySoftUSD),
         dailyHardUSD: num(process.env.AGENT_GUARD_DAILY_HARD, fileBudget.dailyHardUSD ?? DEFAULT_BUDGET.dailyHardUSD),
     };
+    const fileLimits = fileCfg.limits ?? {};
+    const envPlan = process.env.AGENT_GUARD_PLAN;
+    const validPlan = (p) => p === "auto" || p === "pro" || p === "max5" || p === "max20";
+    const limits = {
+        plan: validPlan(envPlan) ? envPlan : validPlan(fileLimits.plan) ? fileLimits.plan : DEFAULT_LIMITS.plan,
+        fiveHourSoftPct: fileLimits.fiveHourSoftPct ?? DEFAULT_LIMITS.fiveHourSoftPct,
+        fiveHourDangerPct: fileLimits.fiveHourDangerPct ?? DEFAULT_LIMITS.fiveHourDangerPct,
+        weeklySoftPct: fileLimits.weeklySoftPct ?? DEFAULT_LIMITS.weeklySoftPct,
+        weeklyDangerPct: fileLimits.weeklyDangerPct ?? DEFAULT_LIMITS.weeklyDangerPct,
+        burnRatioWarn: fileLimits.burnRatioWarn ?? DEFAULT_LIMITS.burnRatioWarn,
+    };
     return {
         budget,
+        limits,
         pricingOverrides: { ...(fileCfg.pricingOverrides ?? {}), ...(filePricing ?? {}) },
         apiKey: process.env.KILL_SWITCH_API_KEY ?? fileCfg.apiKey,
         apiUrl: process.env.KILL_SWITCH_API_URL ?? fileCfg.apiUrl ?? "https://api.kill-switch.net",

package/dist/estimate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Hook-only fallback estimate of subscription utilization.
+ *
+ * Ground truth for plan limits lives in the `anthropic-ratelimit-unified-*`
+ * response headers, which only the proxy sees. A user running just the Claude
+ * Code hook (the common, zero-config setup) never sees those headers — so when
+ * they've told us their plan tier, we *estimate* where they stand by summing the
+ * tokens the ledger recorded inside each rolling window and dividing by a
+ * per-tier token budget.
+ *
+ * This is deliberately approximate and always labelled as such:
+ *   - Anthropic meters opaque "prompts" / "active hours", not tokens, so the
+ *     token budgets below are calibrated rough equivalents, not contractual.
+ *   - The ledger stores a session's cumulative tokens against a single
+ *     `lastAt`, not a time series, so a long session is counted wholesale into
+ *     whichever window its last activity falls in.
+ *
+ * It exists to give hook-only users *a* signal and to nudge them toward
+ * `ks guard proxy` for exact numbers — never to block (subscription mode is
+ * alert-only). When in doubt it under-claims utilization so it won't cry wolf.
+ */
+import { type LimitSnapshot } from "./limits.js";
+import type { Ledger } from "./ledger.js";
+export type PlanTier = "pro" | "max5" | "max20";
+/**
+ * Rough per-tier token-equivalent budgets per window. Pro is the published
+ * baseline; Max 5x / 20x scale the 5-hour burst ~linearly with the multiplier,
+ * while the weekly cap scales more conservatively (Anthropic's weekly multiplier
+ * is smaller than the per-session one). Tune via config if your mileage differs.
+ */
+export interface TierBudget {
+    fiveHourTokens: number;
+    weeklyTokens: number;
+}
+export declare const TIER_BUDGETS: Record<PlanTier, TierBudget>;
+/**
+ * Build an estimated {@link LimitSnapshot} from the ledger for a known tier.
+ * Reset times are derived from the rolling window assumption (oldest in-window
+ * activity + window length is unknowable here, so we report the window end from
+ * `now` as a conservative upper bound on time remaining).
+ */
+export declare function estimateSnapshot(ledger: Ledger, tier: PlanTier, now: number, budgets?: Record<PlanTier, TierBudget>): LimitSnapshot;
+/** True when a snapshot came from {@link estimateSnapshot} rather than real headers. */
+export declare function isEstimated(snap: LimitSnapshot | null): boolean;

package/dist/estimate.js

@@ -0,0 +1,71 @@
+/**
+ * Hook-only fallback estimate of subscription utilization.
+ *
+ * Ground truth for plan limits lives in the `anthropic-ratelimit-unified-*`
+ * response headers, which only the proxy sees. A user running just the Claude
+ * Code hook (the common, zero-config setup) never sees those headers — so when
+ * they've told us their plan tier, we *estimate* where they stand by summing the
+ * tokens the ledger recorded inside each rolling window and dividing by a
+ * per-tier token budget.
+ *
+ * This is deliberately approximate and always labelled as such:
+ *   - Anthropic meters opaque "prompts" / "active hours", not tokens, so the
+ *     token budgets below are calibrated rough equivalents, not contractual.
+ *   - The ledger stores a session's cumulative tokens against a single
+ *     `lastAt`, not a time series, so a long session is counted wholesale into
+ *     whichever window its last activity falls in.
+ *
+ * It exists to give hook-only users *a* signal and to nudge them toward
+ * `ks guard proxy` for exact numbers — never to block (subscription mode is
+ * alert-only). When in doubt it under-claims utilization so it won't cry wolf.
+ */
+import { WINDOW_MS } from "./limits.js";
+export const TIER_BUDGETS = {
+    // Calibrated rough equivalents — Pro ≈ 45 prompts / 5h, modest weekly cap.
+    pro: { fiveHourTokens: 8_000_000, weeklyTokens: 120_000_000 },
+    max5: { fiveHourTokens: 40_000_000, weeklyTokens: 480_000_000 },
+    max20: { fiveHourTokens: 160_000_000, weeklyTokens: 1_400_000_000 },
+};
+const FIVE_HOUR_MS = WINDOW_MS["5h"];
+const WEEK_MS = WINDOW_MS.weekly;
+/** Sum tokens (input+output) across sessions whose last activity is within `windowMs`. */
+function tokensInWindow(ledger, now, windowMs) {
+    let total = 0;
+    for (const s of Object.values(ledger.sessions)) {
+        if (now - s.lastAt < windowMs)
+            total += (s.inputTokens || 0) + (s.outputTokens || 0);
+    }
+    return total;
+}
+/**
+ * Build an estimated {@link LimitSnapshot} from the ledger for a known tier.
+ * Reset times are derived from the rolling window assumption (oldest in-window
+ * activity + window length is unknowable here, so we report the window end from
+ * `now` as a conservative upper bound on time remaining).
+ */
+export function estimateSnapshot(ledger, tier, now, budgets = TIER_BUDGETS) {
+    const b = budgets[tier];
+    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));
+    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",
+        },
+        status: "estimated",
+        observedAt: now,
+    };
+}
+/** True when a snapshot came from {@link estimateSnapshot} rather than real headers. */
+export function isEstimated(snap) {
+    return !!snap && snap.status === "estimated";
+}

package/dist/hook.js

@@ -24,6 +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";
 function readStdin() {
     return new Promise((resolve) => {
         let data = "";
@@ -146,20 +147,53 @@ export async function runHook() {
             emit(blockDecision(event, reason, `🛑 Kill Switch stopped this agent — ${verdict.reasons[0] ?? "budget exceeded"}.`));
             process.exit(0);
         }
+        // Subscription rate-limit pacing — alert-only, surfaced in-session. Reads the
+        // 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);
         // 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.
         if (verdict.level === "warn" && shouldAlert) {
-            const ctx = renderWarnContext(verdict);
+            const ctx = limitMsg ? `${renderWarnContext(verdict)} ${limitMsg}` : renderWarnContext(verdict);
             emit(warnDecision(event, ctx, `⚠️ Kill Switch: ${verdict.reasons[0] ?? "approaching budget"}.`));
             process.exit(0);
         }
+        if (limitMsg) {
+            emit(warnDecision(event, `Kill Switch — Claude Code plan pacing (informational, you may continue): ${limitMsg}`, `⚠️ Kill Switch: ${limitMsg}`));
+            process.exit(0);
+        }
         process.exit(0);
     }
     catch {
         process.exit(0); // fail open on any unexpected error
     }
 }
+/**
+ * Most-urgent subscription-window nudge, fired once per window+level. Mutates the
+ * 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) {
+    try {
+        const limits = buildStatusReport(now).limits;
+        if (!limits.windows.length)
+            return null;
+        const urgent = limits.windows.find((w) => w.level === "danger") ?? limits.windows.find((w) => w.level === "warn");
+        if (!urgent)
+            return null;
+        const key = `limit:${urgent.window}:${urgent.level}`;
+        if (rec.notified[key])
+            return null;
+        rec.notified[key] = true;
+        saveLedger(ledger);
+        return urgent.message;
+    }
+    catch {
+        return null;
+    }
+}
 /** Absolute path to this CLI, so recovery commands work without PATH / npm-link. */
 function selfCmd() {
     try {

package/dist/index.d.ts

@@ -12,9 +12,12 @@ export { costForUsage, totalTokens, fmtUSD, type TokenUsage } from "./cost.js";
 export { evaluate, warnKey, type Budget, type Verdict, type Spend, type VerdictLevel } from "./budget.js";
 export { loadLedger, saveLedger, setSessionCost, addSessionCost, rollingDailyCost, prune, emptyLedger, type Ledger, type SessionRecord, } from "./ledger.js";
 export { parseTranscript, type TranscriptTotals } from "./transcript.js";
-export { loadConfig, DEFAULT_BUDGET, guardDir, ensureGuardDir, configPath, pausePath, isPaused, pauseExpiry, writePause, clearPause, type GuardConfig, } from "./config.js";
-export { dispatchAlert, type AlertEvent } from "./alert.js";
+export { loadConfig, DEFAULT_BUDGET, DEFAULT_LIMITS, guardDir, ensureGuardDir, configPath, limitsPath, pausePath, isPaused, pauseExpiry, writePause, clearPause, type GuardConfig, type LimitsConfig, } from "./config.js";
+export { dispatchAlert, type AlertEvent, type AlertLevel } from "./alert.js";
 export { startProxy, resolveUpstream, type ProxyOptions } from "./proxy.js";
 export { runHook } from "./hook.js";
-export { buildStatusReport, type StatusReport } from "./report.js";
-export { installHook, setBudget, resetLedger, type InstallOptions, type InstallResult, type BudgetPatch, } from "./ops.js";
+export { buildStatusReport, formatLimitsLines, type StatusReport, type LimitsReport } from "./report.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

@@ -12,9 +12,12 @@ export { costForUsage, totalTokens, fmtUSD } from "./cost.js";
 export { evaluate, warnKey } from "./budget.js";
 export { loadLedger, saveLedger, setSessionCost, addSessionCost, rollingDailyCost, prune, emptyLedger, } from "./ledger.js";
 export { parseTranscript } from "./transcript.js";
-export { loadConfig, DEFAULT_BUDGET, guardDir, ensureGuardDir, configPath, pausePath, isPaused, pauseExpiry, writePause, clearPause, } from "./config.js";
+export { loadConfig, DEFAULT_BUDGET, DEFAULT_LIMITS, guardDir, ensureGuardDir, configPath, limitsPath, pausePath, isPaused, pauseExpiry, writePause, clearPause, } from "./config.js";
 export { dispatchAlert } from "./alert.js";
 export { startProxy, resolveUpstream } from "./proxy.js";
 export { runHook } from "./hook.js";
-export { buildStatusReport } from "./report.js";
-export { installHook, setBudget, resetLedger, } from "./ops.js";
+export { buildStatusReport, formatLimitsLines } from "./report.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

@@ -0,0 +1,94 @@
+/**
+ * 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.
+ */
+export type LimitWindow = "5h" | "weekly";
+/** State of one rolling rate-limit window. */
+export interface WindowState {
+    /** Fraction of the window consumed, 0–1. */
+    utilization: number;
+    /** Epoch ms when this window resets, or null if the header didn't say. */
+    resetAt: number | null;
+    /** Raw per-window status string from Anthropic (e.g. "allowed" / "warning"), if any. */
+    status?: string;
+}
+/** A point-in-time read of the account's subscription rate-limit standing. */
+export interface LimitSnapshot {
+    fiveHour: WindowState | null;
+    weekly: WindowState | null;
+    /** Raw overall `anthropic-ratelimit-unified-status`, if present. */
+    status: string | null;
+    /** Epoch ms when this snapshot was observed. */
+    observedAt: number;
+}
+/** Persisted global state (account-wide, not per-session). */
+export interface LimitsState {
+    version: 1;
+    /** True once we've ever observed unified subscription headers. Latches on. */
+    subscriptionDetected: boolean;
+    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>;
+export declare function emptyLimitsState(): LimitsState;
+export declare function loadLimitsState(): LimitsState;
+export declare function saveLimitsState(state: LimitsState): void;
+/** A header bag that works for both a fetch `Headers` and a plain record. */
+export interface HeaderGetter {
+    get(name: string): string | null | undefined;
+}
+/** Wrap a plain `Record<string,string>` so it satisfies {@link HeaderGetter}. */
+export declare function recordHeaders(rec: Record<string, string | string[] | undefined>): HeaderGetter;
+/**
+ * Parse a utilization header value into a 0–1 fraction.
+ * Accepts "0.62", "62", "62%". Values >1.5 are treated as percentages.
+ */
+export declare function parseUtilization(raw: string | null | undefined): number | null;
+/**
+ * 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 declare function parseReset(raw: string | null | undefined, now: number): number | null;
+/**
+ * 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 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;
+/**
+ * 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 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;