@kill-switch/agent-guard 0.1.4 → 0.1.6

package/README.md

@@ -136,18 +136,24 @@ your alert channels:
 ```
 
 `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):
+(it reads the snapshot the proxy persisted).
+
+**Without the proxy, real percentages are unknowable** — Claude Code fetches them from Anthropic
+and never writes them to disk, and local cost does *not* map to Anthropic's internal rate-limit
+units (so we don't fake a "% of limit"). Instead, hook-only mode shows what's honestly knowable:
+your **auto-detected plan tier** (read from `~/.claude.json`) plus **absolute rolling cost** —
+and points you at the proxy for the real numbers. Your tier needs no flag; `--plan` only
+overrides the auto-detection.
 
 ```sh
-ks guard config --plan max5        # auto | pro | max5 | max20
+ks guard config --plan max5        # auto (detect) | pro | max5 | max20
 ```
 
-Tune the thresholds (0–1 utilization) if the defaults are too eager:
+Tune the thresholds (0–1 utilization) if the proxy's pacing is too eager:
 
 | Setting | Meaning | Default |
 |---|---|---|
-| `--plan` (`AGENT_GUARD_PLAN`) | `auto` (headers only) or a tier for estimation | `auto` |
+| `--plan` (`AGENT_GUARD_PLAN`) | `auto` (detect from ~/.claude.json) or pin a tier | `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 |

package/dist/claude-code.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Read what Claude Code persists locally about the account.
+ *
+ * Claude Code stores the user's plan tier in `~/.claude.json` under
+ * `oauthAccount` — so we can auto-detect it instead of making the user pass
+ * `--plan`. Note: Claude Code does NOT persist the live `/usage` rate-limit
+ * percentages anywhere readable (they're fetched from Anthropic and rendered in
+ * the TUI only) — the proxy's `unified-*` response headers remain the single
+ * source of truth for real utilization. This module is best-effort and never
+ * throws; a missing/unreadable file just means "unknown".
+ */
+/** The subscription tiers agent-guard knows about (a subset of LimitsConfig.plan). */
+export type SubscriptionTier = "pro" | "max5" | "max20";
+/** Map a Claude Code rate-limit-tier string (e.g. "default_claude_max_20x") to our tier. */
+export declare function mapRateLimitTier(raw: string | null | undefined): SubscriptionTier | null;
+/**
+ * Best-effort read of the user's plan tier from `~/.claude.json`. Prefers the
+ * per-user tier over the org default when present. Returns null if absent.
+ */
+export declare function detectPlanTier(claudeJsonPath?: string): SubscriptionTier | null;
+/** Human label for a tier. */
+export declare function tierLabel(tier: SubscriptionTier): string;

package/dist/claude-code.js

@@ -0,0 +1,48 @@
+/**
+ * Read what Claude Code persists locally about the account.
+ *
+ * Claude Code stores the user's plan tier in `~/.claude.json` under
+ * `oauthAccount` — so we can auto-detect it instead of making the user pass
+ * `--plan`. Note: Claude Code does NOT persist the live `/usage` rate-limit
+ * percentages anywhere readable (they're fetched from Anthropic and rendered in
+ * the TUI only) — the proxy's `unified-*` response headers remain the single
+ * source of truth for real utilization. This module is best-effort and never
+ * throws; a missing/unreadable file just means "unknown".
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Map a Claude Code rate-limit-tier string (e.g. "default_claude_max_20x") to our tier. */
+export function mapRateLimitTier(raw) {
+    if (!raw)
+        return null;
+    const s = raw.toLowerCase();
+    if (/max[_-]?20x/.test(s))
+        return "max20";
+    if (/max[_-]?5x/.test(s))
+        return "max5";
+    if (s.includes("pro"))
+        return "pro";
+    // Anything else (free, team, enterprise, unknown) → no estimate-tier mapping.
+    return null;
+}
+/**
+ * Best-effort read of the user's plan tier from `~/.claude.json`. Prefers the
+ * per-user tier over the org default when present. Returns null if absent.
+ */
+export function detectPlanTier(claudeJsonPath = join(homedir(), ".claude.json")) {
+    try {
+        const j = JSON.parse(readFileSync(claudeJsonPath, "utf8"));
+        const acct = j.oauthAccount;
+        if (!acct)
+            return null;
+        return mapRateLimitTier(acct.userRateLimitTier) ?? mapRateLimitTier(acct.organizationRateLimitTier);
+    }
+    catch {
+        return null;
+    }
+}
+/** Human label for a tier. */
+export function tierLabel(tier) {
+    return tier === "max20" ? "Max 20x" : tier === "max5" ? "Max 5x" : "Pro";
+}

package/dist/estimate.d.ts

@@ -4,40 +4,46 @@
  * 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.
+ * they've told us their plan tier, we *estimate* where they stand.
  *
- * 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.
+ * We estimate from the ledger's **cost** (`costUSD`), not its token counts. That
+ * matters: a coding agent's volume is dominated by cache reads/writes, and the
+ * ledger only stores non-cache input/output token counts — so a token-based
+ * estimate undercounts real throughput (and thus rate-limit consumption) by a
+ * large factor. `costUSD` is priced from the *full* usage including cache, so it
+ * tracks actual consumption far better. We compare it against a rough per-tier
+ * **API-equivalent** dollar ceiling for each window.
  *
- * 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.
+ * This is still deliberately approximate and always labelled as such:
+ *   - Anthropic meters opaque "prompts" / "active hours", and the dollar ceilings
+ *     below are rough API-equivalent calibrations, not contractual.
+ *   - The ledger stores a session's cumulative cost 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* directional signal and to nudge them
+ * toward `ks guard proxy` for exact numbers — never to block (subscription mode
+ * is alert-only).
  */
 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.
+ * Rough per-tier **API-equivalent USD** ceilings per window — what the plan's
+ * rate limit lets you consume before lock-out, expressed in the same list-price
+ * dollars the ledger meters. Scaled by plan: Pro is the baseline, Max 5x/20x lift
+ * the burst (5h) roughly with the multiplier and the weekly cap more
+ * conservatively. These are estimates; the proxy's real headers override them.
  */
 export interface TierBudget {
-    fiveHourTokens: number;
-    weeklyTokens: number;
+    fiveHourUSD: number;
+    weeklyUSD: 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).
+ * `resetAt` is null (the true rolling reset is unknowable without a per-event
+ * time series), so pacing reports utilization only — no fabricated reset/lockout.
  */
 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. */

package/dist/estimate.js

@@ -4,57 +4,57 @@
  * 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.
+ * they've told us their plan tier, we *estimate* where they stand.
  *
- * 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.
+ * We estimate from the ledger's **cost** (`costUSD`), not its token counts. That
+ * matters: a coding agent's volume is dominated by cache reads/writes, and the
+ * ledger only stores non-cache input/output token counts — so a token-based
+ * estimate undercounts real throughput (and thus rate-limit consumption) by a
+ * large factor. `costUSD` is priced from the *full* usage including cache, so it
+ * tracks actual consumption far better. We compare it against a rough per-tier
+ * **API-equivalent** dollar ceiling for each window.
  *
- * 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.
+ * This is still deliberately approximate and always labelled as such:
+ *   - Anthropic meters opaque "prompts" / "active hours", and the dollar ceilings
+ *     below are rough API-equivalent calibrations, not contractual.
+ *   - The ledger stores a session's cumulative cost 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* directional signal and to nudge them
+ * toward `ks guard proxy` for exact numbers — never to block (subscription mode
+ * is alert-only).
  */
 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 },
+    pro: { fiveHourUSD: 16, weeklyUSD: 100 },
+    max5: { fiveHourUSD: 80, weeklyUSD: 500 },
+    max20: { fiveHourUSD: 300, weeklyUSD: 2000 },
 };
 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) {
+/** Sum metered cost across sessions whose last activity is within `windowMs`. */
+function costInWindow(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);
+            total += s.costUSD || 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).
+ * `resetAt` is null (the true rolling reset is unknowable without a per-event
+ * time series), so pacing reports utilization only — no fabricated reset/lockout.
  */
 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 fiveUSD = costInWindow(ledger, now, FIVE_HOUR_MS);
+    const weekUSD = costInWindow(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), resetAt: null, status: "estimated" },
-        weekly: { utilization: clamp(weekTokens / b.weeklyTokens), resetAt: null, status: "estimated" },
+        fiveHour: { utilization: clamp(fiveUSD / b.fiveHourUSD), resetAt: null, status: "estimated" },
+        weekly: { utilization: clamp(weekUSD / b.weeklyUSD), resetAt: null, status: "estimated" },
         status: "estimated",
         observedAt: now,
     };

package/dist/index.d.ts

@@ -16,8 +16,8 @@ export { loadConfig, DEFAULT_BUDGET, DEFAULT_LIMITS, guardDir, ensureGuardDir, c
 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 { buildStatusReport, buildLimitsReport, formatLimitsLines, type StatusReport, type LimitsReport } from "./report.js";
+export { detectPlanTier, mapRateLimitTier, tierLabel, type SubscriptionTier } from "./claude-code.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

@@ -16,8 +16,8 @@ export { loadConfig, DEFAULT_BUDGET, DEFAULT_LIMITS, guardDir, ensureGuardDir, c
 export { dispatchAlert } from "./alert.js";
 export { startProxy, resolveUpstream } from "./proxy.js";
 export { runHook } from "./hook.js";
-export { buildStatusReport, formatLimitsLines } from "./report.js";
+export { buildStatusReport, buildLimitsReport, formatLimitsLines } from "./report.js";
+export { detectPlanTier, mapRateLimitTier, tierLabel } from "./claude-code.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/report.d.ts

@@ -4,24 +4,39 @@
  *
  * 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.
+ *   - the subscription rate-limit standing. Real 5-hour/weekly utilization is
+ *     only knowable from Anthropic's `unified-*` headers, which the proxy
+ *     captures — so when we have a fresh snapshot we show real percentages, and
+ *     otherwise we show what's honestly knowable locally: the auto-detected plan
+ *     tier plus absolute rolling cost (NOT a fabricated "% of limit" — local cost
+ *     does not map to Anthropic's internal rate-limit units). Alert-only.
  */
-import { type SessionRecord } from "./ledger.js";
+import { type GuardConfig } from "./config.js";
+import { type SessionRecord, type Ledger } 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";
+import { type SubscriptionTier } from "./claude-code.js";
 export interface LimitsReport {
-    /** Where the numbers came from. "none" = no data and no pinned plan to estimate from. */
-    source: "headers" | "estimated" | "none";
+    /** "headers" = real proxy data; "none" = no live data (show tier + cost only). */
+    source: "headers" | "none";
+    /** Configured plan ("auto" | tier). */
     plan: string;
+    /** Resolved subscription tier (from config or auto-detected from ~/.claude.json). */
+    tier: SubscriptionTier | null;
+    /** True when the tier came from ~/.claude.json rather than an explicit --plan. */
+    tierDetected: boolean;
     subscriptionDetected: boolean;
-    /** Epoch ms the snapshot was observed (headers) or computed (estimated). */
+    /** Epoch ms the headers snapshot was observed, or null. */
     observedAt: number | null;
+    /** Real per-window pacing (only when source === "headers"). */
     windows: PacingAssessment[];
     level: PacingLevel;
+    /** Absolute rolling cost (API-equivalent USD) — honest local signal, not a limit %. */
+    cost: {
+        fiveHourUSD: number;
+        dailyUSD: number;
+        weeklyUSD: number;
+    };
 }
 export interface StatusReport {
     budget: Budget;
@@ -29,12 +44,10 @@ export interface StatusReport {
     verdict: VerdictLevel;
     reasons: string[];
     paused: boolean;
-    /** Epoch ms the pause auto-expires, or null (indefinite / not paused). */
     pauseUntil: number | null;
     sessions: Array<{
         id: string;
     } & SessionRecord>;
-    /** Subscription rate-limit pacing — present whenever we have data to show. */
     limits: LimitsReport;
 }
 /**
@@ -45,8 +58,7 @@ export interface StatusReport {
 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
- * empty array when there's nothing useful to show.
+ * both the `agent-guard` and `ks guard` status views stay identical.
  */
 export declare function formatLimitsLines(limits: LimitsReport, now?: number): string[];
 /** Build the current status report from the on-disk config + ledger. */

package/dist/report.js

@@ -4,18 +4,30 @@
  *
  * 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.
+ *   - the subscription rate-limit standing. Real 5-hour/weekly utilization is
+ *     only knowable from Anthropic's `unified-*` headers, which the proxy
+ *     captures — so when we have a fresh snapshot we show real percentages, and
+ *     otherwise we show what's honestly knowable locally: the auto-detected plan
+ *     tier plus absolute rolling cost (NOT a fabricated "% of limit" — local cost
+ *     does not map to Anthropic's internal rate-limit units). Alert-only.
  */
-import { loadConfig } from "./config.js";
-import { isPaused, pauseExpiry } from "./config.js";
+import { loadConfig, isPaused, pauseExpiry } from "./config.js";
 import { loadLedger, rollingDailyCost } from "./ledger.js";
 import { evaluate } from "./budget.js";
+import { fmtUSD } from "./cost.js";
 import { loadLimitsState, WINDOW_MS } from "./limits.js";
 import { assessSnapshot, worstLevel } from "./pacing.js";
-import { estimateSnapshot } from "./estimate.js";
+import { detectPlanTier, tierLabel } from "./claude-code.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
+/** Sum metered cost across sessions whose last activity is within `windowMs`. */
+function costInWindow(ledger, now, windowMs) {
+    let total = 0;
+    for (const s of Object.values(ledger.sessions)) {
+        if (now - s.lastAt < windowMs)
+            total += s.costUSD || 0;
+    }
+    return total;
+}
 /**
  * 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
@@ -23,48 +35,52 @@ const DAY_MS = 24 * 60 * 60 * 1000;
  */
 export function buildLimitsReport(cfg, ledger, now) {
     const state = loadLimitsState();
-    const thresholds = cfg.limits;
     const plan = cfg.limits.plan;
-    // 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").
+    // Resolve the effective tier: an explicit --plan wins; otherwise auto-detect
+    // from ~/.claude.json (oauthAccount.organizationRateLimitTier).
+    let tier = plan === "pro" || plan === "max5" || plan === "max20" ? plan : null;
+    let tierDetected = false;
+    if (!tier) {
+        const detected = detectPlanTier();
+        if (detected) {
+            tier = detected;
+            tierDetected = true;
+        }
+    }
+    const cost = {
+        fiveHourUSD: costInWindow(ledger, now, WINDOW_MS["5h"]),
+        dailyUSD: costInWindow(ledger, now, DAY_MS),
+        weeklyUSD: costInWindow(ledger, now, WINDOW_MS.weekly),
+    };
+    // Real data: a fresh snapshot, with any already-reset window dropped (stale).
     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));
+        const windows = assessSnapshot(snap, cfg.limits, now).filter((w) => !(w.resetAt != null && w.resetAt <= now));
         if (windows.length) {
             return {
                 source: "headers",
                 plan,
+                tier,
+                tierDetected,
                 subscriptionDetected: state.subscriptionDetected,
                 observedAt: snap.observedAt,
                 windows,
                 level: worstLevel(windows),
+                cost,
             };
         }
     }
-    // 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),
-        };
-    }
+    // No live data — honest local signal only (tier + absolute cost, never a fake %).
     return {
         source: "none",
         plan,
+        tier,
+        tierDetected,
         subscriptionDetected: state.subscriptionDetected,
         observedAt: null,
         windows: [],
         level: "ok",
+        cost,
     };
 }
 function bar(frac) {
@@ -84,30 +100,28 @@ function ageString(observedAt, now) {
 }
 /**
  * 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.
+ * both the `agent-guard` and `ks guard` status views stay identical.
  */
 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}`);
+    // Real proxy data → real percentages.
+    if (limits.source === "headers") {
+        const icon = limits.level === "danger" ? "🟥" : limits.level === "warn" ? "🟡" : "🟢";
+        const lines = [`${icon} Claude Code plan limits  ·  observed ${limits.observedAt ? ageString(limits.observedAt, now) : "—"}`];
+        for (const w of limits.windows)
+            lines.push(`  ${bar(w.utilization)}  ${w.message}`);
+        return lines;
     }
-    return lines;
+    // No live data: show what's honestly knowable — the tier and absolute cost,
+    // and steer to the proxy for the real percentages. Never a fabricated % bar.
+    const planStr = limits.tier
+        ? `Claude Code plan: ${tierLabel(limits.tier)}${limits.tierDetected ? " (detected)" : ""}`
+        : "Claude Code plan: unknown";
+    const c = limits.cost;
+    return [
+        `📊 ${planStr} — real 5-hour/weekly limit % needs the proxy`,
+        `   local rolling cost (API-equivalent, NOT a limit %): 5h ${fmtUSD(c.fiveHourUSD)} · 24h ${fmtUSD(c.dailyUSD)} · 7d ${fmtUSD(c.weeklyUSD)}`,
+        `   for exact limits: \`ks guard proxy\` → ANTHROPIC_BASE_URL=http://localhost:8787 claude`,
+    ];
 }
 /** Build the current status report from the on-disk config + ledger. */
 export function buildStatusReport(now = Date.now()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kill-switch/agent-guard",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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": {