claude-code-cache-fix 3.6.1 → 3.7.0

package/README.md

@@ -208,6 +208,63 @@ Options (all optional; all fall back to the same env vars used by the CLI):
 
 *The embeddable factory was contributed by [@bilby91](https://github.com/bilby91) at [Crunchloop DAP](https://dap.crunchloop.ai) — see [PR #123](https://github.com/cnighswonger/claude-code-cache-fix/pull/123).*
 
+## What this proxy defends against
+
+**Cache-economics regressions.** The original purpose of cache-fix is to absorb the cache-handling behaviors in Claude Code that cost users real money and quota — TTL downgrades, cache-breaking header churn, identity-latching issues, and the rest of the regression catalog documented across our issue history. The proxy sits between CC and the Anthropic API, normalizes the request and response stream, and emits enough observability (via statusline integration and the quota-status files) that users can see what their session is actually doing. This is the load-bearing feature for almost every user today.
+
+**Bootstrap-channel observability.** Claude Code v2.1.150 introduced a prompt-section consumer that fetches a server-supplied string from `/api/claude_cli/bootstrap` and merges it into the agent's behavioral-instructions prompt path. We filed this behavior with Anthropic's security team in May 2026; Anthropic closed the report as *Informative*, treating TLS as the transport-integrity boundary and declining to add application-layer authenticity checks. Cache-fix v3.7.0 adds explicit handling for this path. Default mode is `audit` — bootstrap responses proxy through to CC and are logged to `~/.claude/cache-fix-bootstrap-log.jsonl` so users can inspect them locally. To opt into block mode instead, set `CACHE_FIX_BOOTSTRAP_MODE=block` in the proxy environment; block mode short-circuits the upstream call and returns a 200 with an empty JSON body, dropping bootstrap content before it reaches CC. (Note: cache-fix v3.6.2 and earlier returned 404 for this path because the proxy router did not include it — the practical effect was that bootstrap content was not previously reaching CC for cache-fix users. v3.7.0's default `audit` changes that behavior; explicit `CACHE_FIX_BOOTSTRAP_MODE=block` preserves it.) The full disclosure record, including Anthropic's verbatim close text, is in [`docs/disclosure/heron-brook-2026-05.md`](docs/disclosure/heron-brook-2026-05.md).
+
+**Reference material:**
+- [`docs/disclosure/heron-brook-2026-05.md`](docs/disclosure/heron-brook-2026-05.md) — full disclosure record
+- [`CHANGELOG.md`](CHANGELOG.md#370---2026-05-26) — v3.7.0 release entry (includes the behavior-change note for prior users)
+- [`cnighswonger/heron-brook-poc`](https://github.com/cnighswonger/heron-brook-poc) — reproducer for the bootstrap-channel behavior
+
+## Recommended CC operational config
+
+The proxy fixes what it can fix at the request layer. A handful of CC client-side env vars and `~/.claude/settings.json` knobs solve adjacent problems the proxy can't reach — silent model swaps on CC update, ambiguous model fallback, schema-strip side effects. Surfacing these here as a recommendation; users decide their own config.
+
+These findings come from [@fgrosswig](https://github.com/fgrosswig)'s binary analysis of CC v2.1.91. Methodology is public PowerShell + ASCII string extraction; he shared the resulting punch list privately as a courtesy.
+
+### Suggested `~/.claude/settings.json` env block
+
+The model IDs below are illustrative — replace with your preferred main and small-fast models. The point is that pinning *something* explicit beats relying on CC's defaults.
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP": "1",
+    "ANTHROPIC_MODEL": "claude-opus-4-7",
+    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5-20251001"
+  }
+}
+```
+
+**`CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP=1`** — single most impactful flag. CC has a legacy code path that silently remaps your pinned model to a different one after certain version updates. Setting this to `1` disables the remap; the model you pin is the model you get. (If you don't pin, CC's defaults apply as usual.)
+
+**`ANTHROPIC_MODEL`** — pins the primary model. Keeping this explicit means the cache prefix hash stays stable across CC version bumps that would otherwise swap your default. Adjust to whichever model you actually want.
+
+**`ANTHROPIC_SMALL_FAST_MODEL`** — pins the side-channel "fast" model CC uses for short auxiliary calls (e.g., title generation, classification). Without an explicit pin, this can silently fall back to a different family on update.
+
+### `autoCompactWindow=1000000` caveat
+
+If you've seen the `autoCompactWindow: 1000000` setting recommended elsewhere: it only takes effect when the active model qualifies for 1M-context (currently `claude-sonnet-4-6` or `claude-opus-4-6` with the appropriate beta header). Without those preconditions it caps at the hardcoded 200K regardless of what you set.
+
+### `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` schema-strip side effect
+
+If you set this flag, CC strips any tool field outside `["name", "description", "input_schema", "cache_control"]` from outgoing requests. Custom tools relying on `defer_loading` or `eager_input_streaming` will silently lose those fields and behave differently. Worth knowing before turning the flag on.
+
+## Known CC behaviors that affect cache cost
+
+These aren't bugs cache-fix patches — they're upstream CC behaviors users should be aware of when sizing their session cost.
+
+### Diagnostic slash commands inflate conversation history ([#49335](https://github.com/anthropics/claude-code/issues/49335))
+
+Running `/context`, `/release-notes` (and likely other state-inspection commands) appends the diagnostic output to conversation history rather than rendering terminal-only. Subsequent turns replay the inflated payload via prompt cache, compounding token cost on a state-inspection action that should be free. Empirically measured at +3,480 `cache_creation_input_tokens` for a single `/context` invocation on v2.1.148; another user reports ~5K on a separate session. `/release-notes` is worse — defaults to dumping the full changelog.
+
+Worse for diagnosis: the inflated payload that bills against your cache isn't written to the local JSONL transcript, so you can't audit the cost source locally — you can only infer it from `cache_creation_input_tokens` jumps in response usage metadata. (Proxy-mode users can inspect the deltas in `~/.claude/quota-status/` files, which the proxy writes directly from response headers.)
+
+**Workaround until upstream fix:** use these commands sparingly in long sessions. If you need them frequently in a session, consider `/compact` after a diagnostic run to reset the bleed.
+
 ## Quick Start: Preload (CC v2.1.112 and earlier)
 
 If you're on a Node.js-based CC version (v2.1.112 or earlier), the preload interceptor works without a proxy:
@@ -246,7 +303,7 @@ For manual VS Code wrapper setup (without the VSIX), see [docs/preload-setup.md]
 
 **What it does NOT do:** No network calls from the proxy or interceptor. All telemetry is written to local files under `~/.claude/`. No data leaves your machine.
 
-**Supply chain:** Proxy mode: 7 small extension modules in `proxy/extensions/` (each under 200 lines). Preload mode: single unminified file (`preload.mjs`, ~1,700 lines). One dev dependency (`zod` for schema validation in tests only). Review before installing. npm provenance links each published version to its source commit.
+**Supply chain:** Proxy mode: 7 small extension modules in `proxy/extensions/` (each under 200 lines). Preload mode: single unminified file (`preload.mjs`, ~1,700 lines). One dev dependency (`zod` for schema validation in tests only). Review before installing. Published builds carry npm's default registry signatures; sigstore provenance attestation is not currently published — tracked as a follow-up.
 
 **Independent audit:** [Assessed as "LEGITIMATE TOOL"](https://github.com/anthropics/claude-code/issues/38335#issuecomment-4244413605) by @TheAuditorTool (2026-04-14).
 
@@ -323,13 +380,23 @@ The interceptor can only *help* or *do nothing*. It cannot make things worse.
 
 Both modes write quota state on every API call. Proxy mode (v3.5.0+) splits into `~/.claude/quota-status/account.json` (account-global fields: Q5h/Q7d, status, overage) plus `~/.claude/quota-status/sessions/<id>.json` (per-session cache fields: TTL tier, hit rate). Preload mode keeps the legacy `~/.claude/quota-status.json` (single-session by construction). The included `tools/quota-statusline.sh` script displays a live status line showing:
 
-- **Q5h %** with burn rate (%/min)
-- **Q7d %** with burn rate (%/hr)
+- **Q5h** quota bar `[███░┃░░░░░]` + percent + `(exhaust X, reset Y)`. Filled cells are consumed quota; the heavy-vertical tick is wall-clock elapsed position in the window. Tick to the right of the fill = under pace; tick inside the fill = burning faster than time (over pace). `exhaust` is the projected time-to-100% at the current burn rate; `reset` is the wall-clock time until the window rolls over. When `exhaust < reset`, you will hit 100% before the window resets — back off.
+- **Q7d** same shape with day-scale durations (e.g. `(exhaust 3d13h, reset 3d0h)`). Below a day, the suffix auto-switches to `h/m` format (e.g. `(exhaust 1h41m, reset 0h30m)`).
 - **TTL tier** — `TTL:1h` when healthy, **`TTL:5m` in red when the server has downgraded you** (typically at Q5h ≥ 100%)
 - **PEAK** in yellow during weekday peak hours (13:00–19:00 UTC)
 - **Cache hit rate %**
 - **OVERAGE** flag when active
 
+Example line (mid-window, healthy state):
+
+```
+Q5h [███░┃░░░░░] 30% (exhaust 4h40m, reset 3h00m) | Q7d [█████┃░░░░] 53% (exhaust 3d13h, reset 3d0h) | TTL:1h 98.3%
+```
+
+The `(exhaust …, reset …)` suffix is dropped piecewise when projection isn't meaningful: at 0% (fresh window) and 100% (already exhausted) only `reset` is shown; in the first 5 minutes after window start the burn rate isn't stable enough to project (a single early call dominates the rate), so `exhaust` is held back until then on both Q5h and Q7d; a stale `resets_at` (the server-reported value sits in the past, before the next API call refreshes it) drops both.
+
+The bar uses Unicode block characters (`█┃░`) — most modern terminals render these correctly. If your terminal substitutes boxes or replacement glyphs, configure a Unicode-capable font (any DejaVu, Fira, Iosevka, JetBrains Mono, etc.).
+
 ### Setup
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.6.1",
+  "version": "3.7.0",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": {

package/proxy/config.mjs

@@ -10,14 +10,15 @@ function envInt(name, fallback) {
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Existing fields are read once at module init (preserving prior behavior).
-// New corp-proxy/CA fields are getters so they reflect live env — important
-// for test isolation (see test/proxy-upstream-corp-proxy.test.mjs) and for
-// callers that legitimately want to flip env at runtime.
+// Most fields are read once at module init (preserving prior behavior).
+// Corp-proxy/CA fields and `upstream` are getters so they reflect live env —
+// important for test isolation (see test/proxy-upstream-corp-proxy.test.mjs
+// and test/proxy-server-bootstrap.test.mjs) and for callers that legitimately
+// want to flip env at runtime.
 const config = {
   port: envInt("CACHE_FIX_PROXY_PORT", 9801),
   bind: process.env.CACHE_FIX_PROXY_BIND || "127.0.0.1",
-  upstream: process.env.CACHE_FIX_PROXY_UPSTREAM || "https://api.anthropic.com",
+  get upstream() { return process.env.CACHE_FIX_PROXY_UPSTREAM || "https://api.anthropic.com"; },
   timeout: envInt("CACHE_FIX_PROXY_TIMEOUT", 600_000),
   extensionsDir: process.env.CACHE_FIX_EXTENSIONS_DIR || join(__dirname, "extensions"),
   extensionsConfig: process.env.CACHE_FIX_EXTENSIONS_CONFIG || join(__dirname, "extensions.json"),

package/proxy/extensions/bootstrap-defense.mjs

@@ -0,0 +1,161 @@
+import { appendFileSync, statSync, renameSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
+const SCHEMA_VERSION = 1;
+const EXTENSION_VERSION = "v3.6.3";
+
+function logPath() {
+  return process.env.CACHE_FIX_BOOTSTRAP_LOG_PATH || join(homedir(), ".claude", "cache-fix-bootstrap-log.jsonl");
+}
+
+// Single-tier rotation by design: any previous .1 gets overwritten. The audit
+// log is a forward-looking signal feed, not an archival record — if v3.7.0
+// anomaly detection wants long-term retention it can subscribe to the stream
+// directly. Keeping rotation to one tier bounds disk usage at 2×5MB = 10MB.
+function rotateIfNeeded(path) {
+  let size = 0;
+  try { size = statSync(path).size; } catch { return; }
+  if (size < LOG_ROTATE_BYTES) return;
+  try { renameSync(path, `${path}.1`); } catch {}
+}
+
+// Single-writer invariant: cache-fix-proxy is one Node process per host, and
+// every bootstrap response that needs logging flows through this extension.
+// All writes are appendFileSync from a single event loop, so no inter-process
+// or inter-extension locking is required. If that invariant ever changes
+// (e.g. multi-process proxy, sibling extension writing to the same file),
+// this writer needs to gain a lock.
+function appendRecord(record) {
+  const path = logPath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    rotateIfNeeded(path);
+    appendFileSync(path, JSON.stringify(record) + "\n");
+  } catch (err) {
+    process.stderr.write(`[bootstrap-defense] log write failed: ${err.message}\n`);
+  }
+}
+
+function modeFromEnv(fallback) {
+  const raw = process.env.CACHE_FIX_BOOTSTRAP_MODE;
+  if (raw === "audit" || raw === "block") return raw;
+  return fallback;
+}
+
+// PII discipline: the audit log MUST NOT include client headers (Authorization,
+// x-api-key, cookies, etc.) or request/response bodies. Callers pass only the
+// extracted scalar fields below — the full headers object is never threaded
+// through this function, so a future maintainer can't accidentally widen the
+// log surface by spreading the parameter object.
+//
+// v3.7.0 extension fields are emitted as null/defaulted so log readers don't
+// break when v3.7.0 starts populating baseline_hash, anomaly_status, etc.
+function recordShape({ phase, mode, status, body_bytes, upstream_host, request_id, error }) {
+  return {
+    schema_version: SCHEMA_VERSION,
+    extension_version: EXTENSION_VERSION,
+    timestamp: new Date().toISOString(),
+    phase,
+    mode,
+    status: status ?? null,
+    body_bytes: body_bytes ?? null,
+    upstream_host: upstream_host ?? null,
+    request_id: request_id ?? null,
+    baseline_hash: null,
+    anomaly_status: null,
+    error: error ?? null,
+  };
+}
+
+// Extract audit-record scalars from the request context. Meta wins over
+// headers so that the canonical request-side fields stashed by the server
+// (handleBootstrap stashes `_bootstrapUpstreamHost` and `_bootstrapRequestId`
+// before the upstream call) are authoritative on the onResponse path, where
+// ctx.headers carries the upstream RESPONSE headers (no Host, no request-id).
+// On the onRequest block path, meta hasn't been populated yet — the helper
+// falls back to ctx.headers (the client request headers) so request_id is
+// still captured. Upstream_host falls back to null on the request path
+// because the resolved upstream isn't known until handleBootstrap runs.
+//
+// Signature is scalar-only by design: callers MUST NOT spread a headers
+// object into recordShape, so a future maintainer can't accidentally widen
+// the log surface to carry Authorization / x-api-key / cookies.
+function extractAuditFields(meta, headers) {
+  const requestId =
+    meta?._bootstrapRequestId ??
+    headers?.["request-id"] ??
+    headers?.["x-request-id"] ??
+    null;
+  return {
+    upstream_host: meta?._bootstrapUpstreamHost ?? null,
+    request_id: requestId,
+  };
+}
+
+export default {
+  name: "bootstrap-defense",
+  description:
+    "Audit (default) or block /api/claude_cli/bootstrap traffic. Audit mode proxies the response through to CC and logs metadata to ~/.claude/cache-fix-bootstrap-log.jsonl. Block mode returns empty 200, preserving v3.6.2's de-facto behavior in explicit form.",
+  // Pipeline route scoping (pipeline.mjs:appliesToRoute) gates this extension
+  // to the bootstrap path. The internal route guard below is belt-and-suspenders
+  // in case a caller invokes the hook directly.
+  routes: ["bootstrap"],
+  order: 45,
+
+  async onRequest(ctx) {
+    if (ctx.meta?.route !== "bootstrap") return;
+
+    const mode = modeFromEnv("audit");
+    ctx.meta._bootstrapDefenseMode = mode;
+
+    if (mode === "block") {
+      appendRecord(
+        recordShape({
+          phase: "request_blocked",
+          mode,
+          ...extractAuditFields(ctx.meta, ctx.headers),
+        }),
+      );
+      return {
+        skip: true,
+        status: 200,
+        headers: { "content-type": "application/json" },
+        body: {},
+      };
+    }
+  },
+
+  async onResponse(ctx) {
+    if (ctx.meta?.route !== "bootstrap") return;
+    const mode = ctx.meta._bootstrapDefenseMode || "audit";
+    if (mode !== "audit") return;
+
+    // Prefer raw on-wire byte count from server.mjs (accurate even for
+    // non-JSON / unparseable upstream responses). The fallback stringify path
+    // exists only for direct unit-test invocation of onResponse without going
+    // through handleBootstrap — production traffic always sets the meta field.
+    let bodyBytes = ctx.meta?._bootstrapBodyBytes ?? null;
+    if (bodyBytes === null) {
+      try { bodyBytes = Buffer.byteLength(JSON.stringify(ctx.body ?? {})); } catch {}
+    }
+
+    const upstreamError = ctx.meta?._bootstrapUpstreamError ?? null;
+    // Request-side context (request_id, upstream_host) is captured at
+    // forward time and stashed on ctx.meta — we read from meta here rather
+    // than ctx.headers (which on onResponse contains the upstream RESPONSE
+    // headers, not the client request).
+    appendRecord(
+      recordShape({
+        phase: upstreamError ? "upstream_error_audited" : "response_audited",
+        mode,
+        status: ctx.status,
+        body_bytes: bodyBytes,
+        upstream_host: ctx.meta?._bootstrapUpstreamHost ?? null,
+        request_id: ctx.meta?._bootstrapRequestId ?? null,
+        error: upstreamError,
+      }),
+    );
+  },
+};

package/proxy/extensions.json

@@ -1,4 +1,5 @@
 {
+  "bootstrap-defense": { "enabled": true, "order": 45 },
   "ttl-tier-detect": { "enabled": true, "order": 75 },
   "fingerprint-strip": { "enabled": true, "order": 100 },
   "image-strip": { "enabled": true, "order": 150 },

package/proxy/pipeline.mjs

@@ -46,10 +46,27 @@ export function snapshotRegistry() {
   return [...registry];
 }
 
+// Route scoping: extensions default to messages-only so that adding a new
+// route (e.g. /api/claude_cli/bootstrap) doesn't drag every existing
+// message-mutating extension onto it — most throw on a null body because
+// they were never designed for non-messages traffic. Cross-cutting
+// extensions (cache-telemetry, usage-log, …) opt into additional routes
+// by declaring an explicit `routes` array on their default export.
+//
+// If ctx.meta.route is undefined we skip filtering entirely — preserves
+// back-compat for callers that don't tag routes (legacy tests, embedders).
+function appliesToRoute(ext, route) {
+  if (!route) return true;
+  const routes = ext.routes || ["messages"];
+  return routes.includes(route);
+}
+
 export async function runOnRequest(ctx, snapshot) {
   const exts = snapshot || registry;
+  const route = ctx.meta?.route;
   for (const ext of exts) {
     if (!ext.onRequest) continue;
+    if (!appliesToRoute(ext, route)) continue;
     try {
       const result = await ext.onRequest(ctx);
       if (result && result.skip) return result;
@@ -62,8 +79,10 @@ export async function runOnRequest(ctx, snapshot) {
 
 export async function runOnResponseStart(ctx, snapshot) {
   const exts = snapshot || registry;
+  const route = ctx.meta?.route;
   for (const ext of exts) {
     if (!ext.onResponseStart) continue;
+    if (!appliesToRoute(ext, route)) continue;
     try {
       await ext.onResponseStart(ctx);
     } catch (err) {
@@ -74,8 +93,10 @@ export async function runOnResponseStart(ctx, snapshot) {
 
 export async function runOnStreamEvent(ctx, snapshot) {
   const exts = snapshot || registry;
+  const route = ctx.meta?.route;
   for (const ext of exts) {
     if (!ext.onStreamEvent) continue;
+    if (!appliesToRoute(ext, route)) continue;
     try {
       await ext.onStreamEvent(ctx);
     } catch (err) {
@@ -86,8 +107,10 @@ export async function runOnStreamEvent(ctx, snapshot) {
 
 export async function runOnResponse(ctx, snapshot) {
   const exts = snapshot || registry;
+  const route = ctx.meta?.route;
   for (const ext of exts) {
     if (!ext.onResponse) continue;
+    if (!appliesToRoute(ext, route)) continue;
     try {
       await ext.onResponse(ctx);
     } catch (err) {

package/proxy/server.mjs

@@ -1,5 +1,5 @@
 import http from "node:http";
-import { pathToFileURL } from "node:url";
+import { pathToFileURL, URL } from "node:url";
 import config from "./config.mjs";
 import { forwardRequest } from "./upstream.mjs";
 import { streamResponse, createTelemetryRecord } from "./stream.mjs";
@@ -15,16 +15,15 @@ function collectBody(req) {
   });
 }
 
-async function handleMessages(clientReq, clientRes) {
-  const abortController = new AbortController();
-  const extSnapshot = snapshotRegistry();
-
-  clientReq.on("close", () => {
-    if (!clientRes.writableEnded) {
-      abortController.abort();
-    }
-  });
-
+// Run the pre-forward pipeline stages (collect body, parse, runOnRequest)
+// and either short-circuit with an extension-supplied response (block mode,
+// auth-failure synth, etc.) or return the inputs the caller needs to drive
+// forwarding and the post-response stages.
+//
+// `routeName` is stashed on ctx.meta.route so route-aware extensions
+// (bootstrap-defense, env-flag-detector) can discriminate without each
+// route needing its own pipeline hook.
+async function preForward(clientReq, clientRes, _abortController, extSnapshot, routeName, baseMeta = {}) {
   const rawBody = await collectBody(clientReq);
 
   let parsed;
@@ -35,23 +34,49 @@ async function handleMessages(clientReq, clientRes) {
   }
 
   let forwardBody = rawBody;
-  const meta = {};
+  // baseMeta lets routes pre-populate audit scalars (e.g. resolved upstream
+  // hostname, request_id) so they're available to onRequest hooks BEFORE the
+  // upstream call — block-mode short-circuits in onRequest, so a post-call
+  // stash would miss the block-path audit record.
+  const meta = { ...baseMeta, route: routeName };
 
-  if (parsed && extSnapshot.length > 0) {
+  if (extSnapshot.length > 0) {
     const reqCtx = { body: parsed, headers: { ...clientReq.headers }, meta };
     const skipResult = await runOnRequest(reqCtx, extSnapshot);
 
     if (skipResult && skipResult.skip) {
       const status = skipResult.status || 400;
-      const body = skipResult.body || { error: "blocked_by_extension" };
-      clientRes.writeHead(status, { "content-type": "application/json" });
-      clientRes.end(JSON.stringify(body));
-      return;
+      const headers = skipResult.headers || { "content-type": "application/json" };
+      const body = skipResult.body ?? { error: "blocked_by_extension" };
+      clientRes.writeHead(status, headers);
+      clientRes.end(typeof body === "string" ? body : JSON.stringify(body));
+      return { handled: true };
     }
 
-    forwardBody = Buffer.from(JSON.stringify(reqCtx.body));
+    if (parsed) {
+      forwardBody = Buffer.from(JSON.stringify(reqCtx.body));
+    }
   }
 
+  return { handled: false, parsed, forwardBody, meta };
+}
+
+async function handleMessages(clientReq, clientRes) {
+  const abortController = new AbortController();
+  const extSnapshot = snapshotRegistry();
+
+  // Streaming SSE: if the client gives up mid-stream, free the upstream.
+  // Bootstrap (handleBootstrap) doesn't install this because its response is
+  // a single non-SSE JSON payload — aborting on clientReq close prematurely
+  // would race the response write on fast-failure paths (e.g. ECONNREFUSED).
+  clientReq.on("close", () => {
+    if (!clientRes.writableEnded) abortController.abort();
+  });
+
+  const pre = await preForward(clientReq, clientRes, abortController, extSnapshot, "messages");
+  if (pre.handled) return;
+  const { parsed, forwardBody, meta } = pre;
+
   const requestedModel = parsed?.model || null;
 
   let upstreamRes, responseHeaders, statusCode, upstreamConnectionId;
@@ -129,6 +154,89 @@ async function handleMessages(clientReq, clientRes) {
   }
 }
 
+// Route handler for `/api/claude_cli/bootstrap` (CC v2.1.150+ system-prompt
+// injection channel). Same pipeline shape as handleMessages but without
+// the streaming branch — bootstrap is a single non-SSE JSON response.
+// The bootstrap-defense extension binds to onRequest/onResponse with
+// `ctx.meta.route === "bootstrap"` to drive audit/block behavior.
+async function handleBootstrap(clientReq, clientRes) {
+  const abortController = new AbortController();
+  const extSnapshot = snapshotRegistry();
+
+  // Resolve audit-record scalars BEFORE preForward so they're visible to
+  // onRequest hooks (block-mode short-circuits there). HTTP responses don't
+  // carry a Host header, so the audit log derives upstream_host from
+  // config.upstream — the actual destination requests were forwarded to.
+  let upstreamHost = null;
+  try {
+    upstreamHost = new URL(config.upstream).hostname;
+  } catch {}
+  const baseMeta = {
+    _bootstrapUpstreamHost: upstreamHost,
+    _bootstrapRequestId:
+      clientReq.headers["request-id"] ?? clientReq.headers["x-request-id"] ?? null,
+  };
+
+  const pre = await preForward(clientReq, clientRes, abortController, extSnapshot, "bootstrap", baseMeta);
+  if (pre.handled) return;
+  const { forwardBody, meta } = pre;
+
+  let upstreamRes, responseHeaders, statusCode, upstreamConnectionId;
+
+  try {
+    ({ upstreamRes, responseHeaders, statusCode, upstreamConnectionId } = await forwardRequest(
+      clientReq,
+      forwardBody,
+      abortController.signal,
+    ));
+  } catch (err) {
+    // Anomaly audit: bootstrap upstream errors are exactly the kind of event
+    // an attacker triggering DNS shenanigans or an outage would produce, so
+    // route them through the extension pipeline before responding 502.
+    if (extSnapshot.length > 0) {
+      meta._bootstrapUpstreamError = err.message;
+      meta._bootstrapBodyBytes = 0;
+      const errCtx = { status: 502, headers: {}, body: null, meta };
+      await runOnResponse(errCtx, extSnapshot);
+    }
+    clientRes.writeHead(502, { "content-type": "application/json" });
+    clientRes.end(JSON.stringify({ error: "upstream_error", message: err.message }));
+    return;
+  }
+
+  meta._upstreamConnectionId = upstreamConnectionId ?? null;
+
+  if (extSnapshot.length > 0) {
+    const resCtx = { status: statusCode, headers: responseHeaders, meta };
+    await runOnResponseStart(resCtx, extSnapshot);
+  }
+
+  const chunks = [];
+  for await (const chunk of upstreamRes) chunks.push(chunk);
+  const rawResponse = Buffer.concat(chunks);
+
+  if (extSnapshot.length > 0) {
+    let responseBody = null;
+    try {
+      responseBody = JSON.parse(rawResponse.toString());
+    } catch {}
+    // Stash raw byte count so bootstrap-defense (and future audit extensions)
+    // can record the on-wire payload size even when the body fails to parse.
+    // Non-JSON responses are exactly the anomaly audit mode needs to capture.
+    meta._bootstrapBodyBytes = rawResponse.length;
+    const resCtx = { status: statusCode, headers: responseHeaders, body: responseBody, meta };
+    await runOnResponse(resCtx, extSnapshot);
+    if (responseBody !== null) {
+      clientRes.writeHead(statusCode, resCtx.headers);
+      clientRes.end(JSON.stringify(resCtx.body));
+      return;
+    }
+  }
+
+  clientRes.writeHead(statusCode, responseHeaders);
+  clientRes.end(rawResponse);
+}
+
 function handleHealth(_req, res) {
   res.writeHead(200, { "content-type": "application/json" });
   res.end(JSON.stringify({ status: "ok" }));
@@ -157,6 +265,9 @@ export function createProxyServer() {
     if (req.method === "POST" && req.url?.startsWith("/v1/messages")) {
       return handleMessages(req, res);
     }
+    if (req.url?.startsWith("/api/claude_cli/bootstrap")) {
+      return handleBootstrap(req, res);
+    }
     handleNotFound(req, res);
   });
 }

package/tools/quota-statusline.sh

@@ -41,7 +41,7 @@ fi
 # through os.environ, never via a shell-substituted string.
 result=$(python3 <<'PYEOF' 2>/dev/null
 import sys, json, os, re, hashlib
-from datetime import datetime, timezone, timedelta
+from datetime import datetime, timezone
 
 home = os.path.expanduser('~')
 account_path = os.path.join(home, '.claude', 'quota-status', 'account.json')
@@ -98,28 +98,87 @@ ts = sess.get('timestamp') or acc.get('timestamp', '')
 
 now = datetime.fromisoformat(ts.replace('Z', '+00:00')) if ts else datetime.now(timezone.utc)
 
-# Q5h burn rate
-rate5 = ''
-if q5h_reset > 0 and q5h > 0:
-    window_start = datetime.fromtimestamp(q5h_reset, tz=timezone.utc) - timedelta(hours=5)
-    elapsed_min = (now - window_start).total_seconds() / 60
-    if elapsed_min > 1:
-        rate5 = '{:+.1f}'.format(q5h / elapsed_min)
-
-# Q7d burn rate
-rate7 = ''
-if q7d_reset > 0 and q7d > 0:
-    window_start_7d = datetime.fromtimestamp(q7d_reset, tz=timezone.utc) - timedelta(days=7)
-    elapsed_hr = (now - window_start_7d).total_seconds() / 3600
-    if elapsed_hr > 0.1:
-        rate7 = '{:+.1f}'.format(q7d / elapsed_hr)
-
-label = 'Q5h: {}%'.format(q5h)
-if rate5:
-    label += ' ({}%/m)'.format(rate5)
-label += ' | Q7d: {}%'.format(q7d)
-if rate7:
-    label += ' ({}%/hr)'.format(rate7)
+SECS_PER_MIN = 60
+MINS_PER_HR = 60
+HRS_PER_DAY = 24
+SECS_PER_HR = SECS_PER_MIN * MINS_PER_HR
+SECS_PER_DAY = SECS_PER_HR * HRS_PER_DAY
+
+# Minimum elapsed time in a window before we'll project an exhaust ETA from
+# its burn rate. Below this the rate is dominated by a single early call and
+# the projection is noise.
+BURN_WARMUP_SEC = 5 * SECS_PER_MIN
+
+BAR_WIDTH = 10
+
+def draw_bar(consumed_pct, elapsed_pct, width=BAR_WIDTH):
+    # Tick overlays a fill cell when consumed > elapsed, keeping bar width
+    # constant — that's what makes the over-pace state legible (┃ inside the
+    # filled run) rather than just pushing fill cells around.
+    fill = int(round(max(0, min(100, consumed_pct)) / 100 * width))
+    if elapsed_pct is None:
+        tick = -1
+    else:
+        tick = min(int(max(0, min(100, elapsed_pct)) / 100 * width), width - 1)
+    cells = []
+    remaining = fill
+    for i in range(width):
+        if i == tick:
+            cells.append('┃')
+        elif remaining > 0:
+            cells.append('█')
+            remaining -= 1
+        else:
+            cells.append('░')
+    return '[' + ''.join(cells) + ']'
+
+def fmt_time(secs):
+    # Autoselect scale: `{D}d{H}h` for >=1 day, `{H}h{MM}m` below that.
+    # One formatter so the Q5h (always h/m) and Q7d (h/m or d/h depending on
+    # how close to reset) callers don't need to pick.
+    if secs is None or secs <= 0:
+        return ''
+    if secs >= SECS_PER_DAY:
+        return '{}d{}h'.format(int(secs // SECS_PER_DAY), int((secs % SECS_PER_DAY) // SECS_PER_HR))
+    return '{}h{:02d}m'.format(int(secs // SECS_PER_HR), int((secs % SECS_PER_HR) // SECS_PER_MIN))
+
+def window_view(reset_ts, window_secs):
+    # Returns (elapsed_sec, secs_left). elapsed_sec may be negative (server
+    # gave us a reset_at past the window head — invalid) or exceed window_secs
+    # (stale reset_at not yet refreshed by the next API call). Callers handle
+    # both; downstream rendering clamps the tick to the bar edges.
+    if reset_ts <= 0:
+        return None, None
+    window_start = datetime.fromtimestamp(reset_ts - window_secs, tz=timezone.utc)
+    return (now - window_start).total_seconds(), reset_ts - now.timestamp()
+
+def time_to_exhaust_sec(pct, elapsed_sec, min_elapsed_sec):
+    # (100 - pct) divided by current burn rate (pct / elapsed_sec). Gated on
+    # min_elapsed_sec so very-fresh windows don't project off noise.
+    if elapsed_sec is None or elapsed_sec <= min_elapsed_sec:
+        return None
+    if pct <= 0 or pct >= 100:
+        return None
+    return (100 - pct) * elapsed_sec / pct
+
+def format_window(name, pct, elapsed_sec, window_secs, secs_left, min_elapsed_sec):
+    ep = None if elapsed_sec is None or elapsed_sec < 0 else elapsed_sec / window_secs * 100
+    extras = []
+    stale = secs_left is not None and secs_left <= 0
+    if not stale:
+        exhaust = time_to_exhaust_sec(pct, elapsed_sec, min_elapsed_sec)
+        if exhaust is not None:
+            extras.append('exhaust ' + fmt_time(exhaust))
+        if secs_left is not None and secs_left > 0:
+            extras.append('reset ' + fmt_time(secs_left))
+    tail = ' (' + ', '.join(extras) + ')' if extras else ''
+    return '{} {} {}%{}'.format(name, draw_bar(pct, ep), pct, tail)
+
+elapsed_5h, left_5h = window_view(q5h_reset, 5 * SECS_PER_HR)
+elapsed_7d, left_7d = window_view(q7d_reset, 7 * SECS_PER_DAY)
+
+label = format_window('Q5h', q5h, elapsed_5h, 5 * SECS_PER_HR, left_5h, BURN_WARMUP_SEC)
+label += ' | ' + format_window('Q7d', q7d, elapsed_7d, 7 * SECS_PER_DAY, left_7d, BURN_WARMUP_SEC)
 if overage == 'active':
     label += ' | OVERAGE'