claude-code-cache-fix 3.8.0 → 4.0.0

package/proxy/extensions/thinking-block-sanitize.mjs

@@ -1,12 +1,27 @@
 // thinking-block-sanitize — request-path mitigation for the CC thinking-desync
-// wedge (anthropics/claude-code#63147). On replay paths (resume / --continue /
+// wedge (anthropics/claude-code#63147).
+//
+// v1 (default since v4.0.0; CACHE_FIX_THINKING_SANITIZE unset or =on): On replay paths (resume / --continue /
 // auto-compaction / parallel-tool-cancel), CC re-sends prior assistant turns'
 // thinking in the OMITTED shape `{ type:"thinking", thinking:"", signature }`.
 // The API rejects modified thinking in the *latest* assistant message with a
-// permanent 400, which wedges the session. This extension drops the omitted
-// thinking blocks the API treats as optional, before the request is forwarded.
+// permanent 400, which wedges the session. v1 drops these omitted blocks
+// before forwarding. Never touches non-empty thinking; never touches
+// redacted_thinking (v1's empirical exclusion — zero observed in worst-case
+// wedged transcripts).
+//
+// v2 (CACHE_FIX_THINKING_SANITIZE=v2): Additionally handles yurukusa's "13E"
+// pattern — when ToolSearch dynamically loads a tool mid-conversation, the
+// prior assistant turn's thinking signature is invalidated because it was
+// computed over the now-stale tools surface. The API rejects + CC's harness
+// strips-and-retries, paying a 400 + retry tax every turn. v2 detects
+// cross-request tools-surface change via a per-session tools-hash baseline,
+// and strips ALL prior-turn signed thinking (both `thinking` blocks with
+// non-empty text AND `redacted_thinking` blocks — v2's scope is structural,
+// not empirical) on hash mismatch. Same active-tool-continuation latest-turn
+// guard as v1.
 //
-// Resolved turn-selection rule (directive Open Question 1, empirical capture):
+// Resolved turn-selection rule (v1 directive Open Question 1, empirical capture):
 //   - drop omitted thinking from ALL prior assistant turns, AND
 //   - from the LATEST assistant turn UNLESS it is an active tool-continuation
 //     (last block is a tool_use with a following tool_result) — that case is
@@ -16,15 +31,47 @@
 //     / MAX_THINKING_TOKENS=0 stop it only by disabling thinking entirely
 //     (lossy); DISABLE_INTERLEAVED_THINKING=1 does NOT stop the 400 — so the
 //     answer for that case is don't-resume + heal/retire.
-// Never touches non-empty thinking, and never touches redacted_thinking (v1).
 //
-// OPT-IN for v1: only runs when CACHE_FIX_THINKING_SANITIZE=on (default off) —
-// it mutates request bodies and its coverage is not yet live-validated.
+// v2 state pattern (per directive proxy-thinking-block-sanitize-v2.md):
+//   - In-memory per-session map keyed by canonical session filename, seeded
+//     once from sessions/<sid>.json on first request that session. Mirrors
+//     session-health's pattern. Lives at module scope.
+//   - Baseline updates ONLY on response success (HTTP 2xx). 4xx/5xx leave
+//     the baseline unchanged so a failed request's hash doesn't become the
+//     new ground truth.
+//   - First request observes-and-establishes (no strip; baseline is set
+//     after the response succeeds).
+//   - When canonical session id is "unknown" (raw id null/empty/whitespace),
+//     v2 no-ops entirely. The shared sessions/unknown.json would cross-
+//     contaminate baselines across unrelated agents otherwise.
+//
+// Modes via CACHE_FIX_THINKING_SANITIZE (as of v4.0.0 — v1 default-on flip):
+//   unset (or "on")                       — v1 only (omitted-text drop). DEFAULT.
+//   "off"                                 — extension no-ops (explicit disable)
+//   "v2"                                  — v1 + v2 (omitted-text drop AND
+//                                           tools-hash-mismatch drop). v2 is
+//                                           strict superset of v1.
+//   any other value                       — treated as v1 (the default), not off.
+//                                           Matches the precedent of being
+//                                           permissive about the on-path.
+//
+// v1 default-on rationale: 7-day prod dogfood across 37 sessions (2026-05-29
+// → 2026-06-05) on `=on`: zero `cannot be modified` 400s, cache hit-rate
+// aggregate 94.66% vs 92.44% baseline (no prefix degradation), sanitize fired
+// on ~35% of sessions, ~800 blocks dropped per day, max 938K context healthy.
+// v2 stays opt-in via `=v2` because the dogfood only ran v1.
 //
 // Order 550: after the request-body mutators (ttl-management 500) and before
 // session-health (590), so #160's thinking_block_count reflects the forwarded
-// body. The per-request drop count is exposed via ctx.meta._thinkingSanitize
-// for cache-telemetry (600) to merge into the per-session JSON.
+// body. The per-request drop counts are exposed via ctx.meta._thinkingSanitize
+// (v1 counter) and ctx.meta._thinkingSanitizeV2 (v2 counter + baseline) for
+// cache-telemetry (600) to merge into the per-session JSON.
+
+import { readFileSync } from "node:fs";
+import { resolveSessionId, sessionFilePath, sessionFilename } from "./cache-telemetry.mjs";
+import { computeSignatureSurfaceHash } from "./signature-surface-hash.mjs";
+
+// --- v1 predicates ---
 
 export function isOmittedThinking(block) {
   return (
@@ -70,14 +117,38 @@ function latestAssistantIndex(messages) {
   return -1;
 }
 
-// Pure planner: returns { messages, dropped }. Does not mutate the input.
-// `messages` is the new array (a message that loses all content is dropped).
-export function planSanitize(messages) {
-  if (!Array.isArray(messages)) return { messages, dropped: 0 };
+// --- v2 predicate ---
+
+// v2 strips signed `thinking` blocks (non-empty text) AND `redacted_thinking`
+// blocks. v1's `isOmittedThinking` filter handles the empty-text case
+// independently — when both flags are active, v1 drops the empty ones and v2
+// drops the signed ones; predicates are non-overlapping.
+export function isSignedThinkingForV2(block) {
+  if (!block) return false;
+  if (block.type === "redacted_thinking") return true;
+  // Non-empty thinking with a signature — v1 leaves these alone by design.
+  return (
+    block.type === "thinking" &&
+    typeof block.thinking === "string" &&
+    block.thinking.trim() !== "" &&
+    typeof block.signature === "string" &&
+    block.signature.length > 0
+  );
+}
+
+// --- Pure planner ---
+//
+// Returns { messages, dropped, droppedV2 }. Does not mutate input.
+// `v2StripSigned` is the externally-determined boolean: should v2's
+// signed-thinking drop fire this request? (Caller has already computed
+// hash mismatch + session-state checks.)
+export function planSanitize(messages, { v2StripSigned = false } = {}) {
+  if (!Array.isArray(messages)) return { messages, dropped: 0, droppedV2: 0 };
   const latestAsst = latestAssistantIndex(messages);
   const protectLatest = latestAsst >= 0 && isActiveToolContinuation(messages, latestAsst);
 
   let dropped = 0;
+  let droppedV2 = 0;
   let changed = false;
   const out = [];
   for (let i = 0; i < messages.length; i++) {
@@ -87,14 +158,24 @@ export function planSanitize(messages) {
       continue;
     }
     if (i === latestAsst && protectLatest) {
-      out.push(msg); // active continuation — leave its thinking intact
+      // Active continuation — leave thinking intact (both v1 and v2 respect
+      // this; the API needs the signed thinking for the pending tool call).
+      out.push(msg);
       continue;
     }
     const kept = msg.content.filter((b) => {
+      // v1 always-active drop predicate.
       if (isOmittedThinking(b)) {
         dropped++;
         return false;
       }
+      // v2-only drop predicate. Predicates are mutually exclusive on a single
+      // block: omitted thinking matches v1's predicate but not v2's, and
+      // signed/redacted thinking matches v2's predicate but not v1's.
+      if (v2StripSigned && isSignedThinkingForV2(b)) {
+        droppedV2++;
+        return false;
+      }
       return true;
     });
     if (kept.length === msg.content.length) {
@@ -106,25 +187,158 @@ export function planSanitize(messages) {
       changed = true;
     }
   }
-  return { messages: changed ? out : messages, dropped };
+  return { messages: changed ? out : messages, dropped, droppedV2 };
+}
+
+// --- v2 mode + state ---
+
+// "off" | "on" | "v2". As of v4.0.0 the default flipped from "off" to "on" —
+// v1 (omitted-text drop) is the new default behavior. Set
+// CACHE_FIX_THINKING_SANITIZE=off to explicitly disable; =v2 to additionally
+// enable the v2 tools-hash-mismatch drop (still opt-in pending its own
+// prod-dogfood window after #200 closes the silent-load failure mode).
+// Unknown values fall through to "on" — we are permissive about the on-path
+// and only treat the literal "off" as a disable.
+export function modeFromEnv(env = process.env) {
+  const v = env.CACHE_FIX_THINKING_SANITIZE;
+  if (v === "off") return "off";
+  if (v === "v2") return "v2";
+  return "on";
+}
+
+// Per-session state, in memory. Keyed by canonical session filename
+// (sessionFilename(rawId)). Each entry: { tools_hash_baseline }.
+// Mirrors session-health's pattern: seeded once from disk on first request
+// that session, then maintained in memory + persisted via cache-telemetry's
+// spread of ctx.meta._thinkingSanitizeV2.
+const v2SessionState = new Map();
+
+function seedV2FromFile(rawSid) {
+  let prev = null;
+  try {
+    prev = JSON.parse(readFileSync(sessionFilePath(rawSid), "utf8"));
+  } catch {}
+  return {
+    tools_hash_baseline:
+      typeof prev?.tools_hash_baseline === "string" ? prev.tools_hash_baseline : null,
+  };
+}
+
+// Test-only reset (also useful for proxy-restart simulation in unit tests).
+export function _resetV2State() {
+  v2SessionState.clear();
 }
 
+// --- Extension default-export ---
+
 export default {
   name: "thinking-block-sanitize",
   description:
-    "Drop omitted (empty-text) thinking blocks from prior assistant turns and the latest non-continuation turn, to head off the CC thinking-desync 400 (#63147). Opt-in via CACHE_FIX_THINKING_SANITIZE=on.",
+    "Drop omitted (empty-text) thinking blocks from prior assistant turns and the latest non-continuation turn, to head off the CC thinking-desync 400 (#63147). v1 mode: omitted-text drop only. v2 mode: also drop signed thinking + redacted_thinking on cross-request tools-hash mismatch (ToolSearch surface). v1 is now ON by default as of v4.0.0; set CACHE_FIX_THINKING_SANITIZE=off to disable, =v2 to additionally opt into v2.",
   order: 550,
 
   async onRequest(ctx) {
-    if (process.env.CACHE_FIX_THINKING_SANITIZE !== "on") return;
+    const mode = modeFromEnv();
+    if (mode === "off") return;
+
     const body = ctx.body;
     if (!body || !Array.isArray(body.messages)) return;
 
-    const { messages, dropped } = planSanitize(body.messages);
-    if (dropped > 0) body.messages = messages;
+    // v2 only fires when mode === "v2" AND we have a usable session id.
+    let v2StripSigned = false;
+    let stateKey = null;
+    let currentHash = null;
+
+    if (mode === "v2") {
+      // Resolve session id inline — cache-telemetry's onRequest runs at order
+      // 600, after us, so ctx.meta._sessionId is not yet set when we fire at
+      // order 550. We import resolveSessionId from cache-telemetry to keep
+      // canonicalization consistent.
+      const rawSid = resolveSessionId(ctx.headers);
+      stateKey = sessionFilename(rawSid);
+
+      // "unknown" canonical id → no-op for v2 (cross-contamination risk on
+      // the shared sessions/unknown.json baseline). v1's strip still runs
+      // below regardless.
+      if (stateKey !== "unknown") {
+        currentHash = computeSignatureSurfaceHash({ tools: body.tools });
+
+        // Seed in-memory state from disk on first encounter that session
+        // (covers proxy restart — re-reads persisted baseline).
+        let st = v2SessionState.get(stateKey);
+        if (!st) {
+          st = seedV2FromFile(rawSid);
+          v2SessionState.set(stateKey, st);
+        }
+
+        const baseline = st.tools_hash_baseline;
+        // Mismatch only fires when there IS a baseline AND it differs.
+        // First request (baseline === null) observes-and-establishes — no strip.
+        v2StripSigned = baseline !== null && baseline !== currentHash;
+
+        // Stash for the onResponseStart hook to advance the baseline iff the
+        // response succeeded. Stash BEFORE the plan + strip so the response
+        // path has access regardless of whether anything was dropped.
+        ctx.meta._thinkingSanitizeV2PendingHash = currentHash;
+        ctx.meta._thinkingSanitizeV2StateKey = stateKey;
+      }
+    }
+
+    const { messages, dropped, droppedV2 } = planSanitize(body.messages, {
+      v2StripSigned,
+    });
+    if (dropped > 0 || droppedV2 > 0) body.messages = messages;
 
     // Counts only — never content. Exposed for cache-telemetry to persist and
     // for the #160 session-health signal.
+    // v1 counter — unchanged, fires for both modes.
     ctx.meta._thinkingSanitize = { thinking_blocks_dropped: dropped };
+
+    // v2 counter — fires only in v2 mode. Includes the post-mismatch baseline
+    // value that cache-telemetry will persist (so consumers can see the
+    // current baseline in the session JSON even on requests that didn't
+    // strip). The actual advance only happens on response success below.
+    if (mode === "v2" && stateKey && stateKey !== "unknown") {
+      ctx.meta._thinkingSanitizeV2 = {
+        thinking_blocks_dropped_v2: droppedV2,
+        // Persist the SOON-TO-BE-NEW baseline (it'll be advanced on success).
+        // On 4xx/5xx, the cache-telemetry write still happens but the
+        // in-memory state isn't advanced — next request re-reads disk and
+        // sees the persisted value, which may now disagree with in-memory.
+        // We resolve that by NOT writing the new hash to disk on failure:
+        // see onResponseStart below, which is the only thing that advances
+        // both in-memory and (indirectly via cache-telemetry's spread) disk.
+        // For now, leave tools_hash_baseline at the CURRENT baseline value;
+        // onResponseStart will overwrite this in meta if the response is 2xx.
+        tools_hash_baseline: v2SessionState.get(stateKey)?.tools_hash_baseline ?? null,
+      };
+    }
+  },
+
+  // Advance the baseline only on HTTP 2xx response. 4xx/5xx leaves the
+  // in-memory state and the meta-stashed baseline untouched, so a failed
+  // request's hash never becomes the new ground truth.
+  async onResponseStart(ctx) {
+    const stateKey = ctx.meta._thinkingSanitizeV2StateKey;
+    const pendingHash = ctx.meta._thinkingSanitizeV2PendingHash;
+    if (!stateKey || !pendingHash) return;
+    if (typeof ctx.status !== "number") return;
+    if (ctx.status < 200 || ctx.status >= 300) return;
+
+    // Advance in-memory baseline.
+    let st = v2SessionState.get(stateKey);
+    if (!st) {
+      st = { tools_hash_baseline: null };
+      v2SessionState.set(stateKey, st);
+    }
+    st.tools_hash_baseline = pendingHash;
+
+    // Update the meta-stashed baseline so cache-telemetry's spread writes
+    // the new value to disk. If meta._thinkingSanitizeV2 wasn't stashed
+    // (e.g. mode flip mid-request), construct it now.
+    if (!ctx.meta._thinkingSanitizeV2) {
+      ctx.meta._thinkingSanitizeV2 = { thinking_blocks_dropped_v2: 0 };
+    }
+    ctx.meta._thinkingSanitizeV2.tools_hash_baseline = pendingHash;
   },
 };

package/proxy/pipeline.mjs

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 
 let registry = [];
+let failedExtensions = []; // [{ file, error, lastAttempt }]
 
 export async function loadExtensions(dir, configPath) {
   let config = {};
@@ -15,6 +16,7 @@ export async function loadExtensions(dir, configPath) {
   const mjsFiles = files.filter((f) => f.endsWith(".mjs")).sort();
 
   const extensions = [];
+  const newlyFailed = [];
   for (const file of mjsFiles) {
     try {
       const mod = await import(pathToFileURL(join(dir, file)).href + "?t=" + Date.now());
@@ -29,12 +31,24 @@ export async function loadExtensions(dir, configPath) {
         extensions.push({ ...ext, order, _file: file });
       }
     } catch (err) {
-      process.stderr.write(`[pipeline] failed to load ${file}: ${err.message}\n`);
+      // Load-bearing observability: this branch is the only signal that the
+      // proxy is running with a degraded extension graph. See #196: a Node
+      // ESM cache stale-import race silently broke thinking-block-sanitize
+      // v2 for 17 hours post-merge before AITL grepped the journal. The
+      // [CRITICAL] prefix is harder to miss than the prior [pipeline] one,
+      // and the explicit "restart proxy to recover" hint tells the operator
+      // what to do — the underlying Node ESM cache problem can't be fixed
+      // in-process (you can't evict cached transitive imports), so a full
+      // process restart is the only path to recover the extension graph.
+      const msg = `[CRITICAL] extension load failed: ${file}: ${err.message} — restart the proxy via your supervisor to recover (in-process reload cannot fix stale ESM cache; see #196)\n`;
+      process.stderr.write(msg);
+      newlyFailed.push({ file, error: String(err.message || err), lastAttempt: new Date().toISOString() });
     }
   }
 
   extensions.sort((a, b) => a.order - b.order);
   registry = extensions;
+  failedExtensions = newlyFailed;
   return extensions;
 }
 
@@ -46,6 +60,13 @@ export function snapshotRegistry() {
   return [...registry];
 }
 
+// Exposed for /health and any operator-facing tool that wants to surface
+// extension-load failures. Returns a fresh array per call so callers can't
+// mutate internal state.
+export function getFailedExtensions() {
+  return failedExtensions.map((f) => ({ ...f }));
+}
+
 // 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

package/proxy/server.mjs

@@ -3,7 +3,7 @@ import { pathToFileURL, URL } from "node:url";
 import config from "./config.mjs";
 import { forwardRequest } from "./upstream.mjs";
 import { streamResponse, createTelemetryRecord } from "./stream.mjs";
-import { loadExtensions, snapshotRegistry, runOnRequest, runOnResponseStart, runOnResponse } from "./pipeline.mjs";
+import { loadExtensions, snapshotRegistry, runOnRequest, runOnResponseStart, runOnResponse, getFailedExtensions } from "./pipeline.mjs";
 import { startWatcher } from "./watcher.mjs";
 
 function collectBody(req) {
@@ -238,6 +238,21 @@ async function handleBootstrap(clientReq, clientRes) {
 }
 
 function handleHealth(_req, res) {
+  // Surface extension-load failures so callers (operators, monitoring) see
+  // a degraded proxy state instead of a misleading "ok". See #196: a Node
+  // ESM cache stale-import race silently broke thinking-block-sanitize v2
+  // for 17 hours post-merge before anyone noticed. /health returning "ok"
+  // through that window was load-bearing in the silence.
+  const failed = getFailedExtensions();
+  if (failed.length > 0) {
+    res.writeHead(503, { "content-type": "application/json" });
+    res.end(JSON.stringify({
+      status: "degraded",
+      failed_extensions: failed,
+      hint: "restart the proxy via your supervisor to recover (in-process reload cannot fix stale ESM cache; #196)",
+    }));
+    return;
+  }
   res.writeHead(200, { "content-type": "application/json" });
   res.end(JSON.stringify({ status: "ok" }));
 }
@@ -290,7 +305,34 @@ export async function startProxy(options = {}) {
   const bind = options.bind ?? config.bind;
   const extensionsDir = options.extensionsDir ?? config.extensionsDir;
   const extensionsConfig = options.extensionsConfig ?? config.extensionsConfig;
-  const watch = options.watch !== false;
+  // Hot-reload is opt-in as of v4.0.0 (#196). The in-process watcher is the
+  // only code path that triggers the Node ESM stale-import race; cold starts
+  // have an empty module cache and load extensions cleanly. Strict `=== "on"`
+  // means any other value (including "true"/"1"/"yes") is treated as off —
+  // the safe default. Note this is the opposite stance from
+  // CACHE_FIX_THINKING_SANITIZE (default-on; only literal "off" disables):
+  // a hot-reload enable is a footgun, so we require the operator to type the
+  // exact opt-in token; a sanitize disable is also a footgun (loses the
+  // wedge mitigation), so we require the exact disable token there.
+  const hotReloadOptIn = process.env.CACHE_FIX_HOT_RELOAD === "on";
+  const watch = options.watch !== false && hotReloadOptIn;
+
+  // Boot banner on stderr so the EFFECTIVE hot-reload mode is visible in the
+  // supervisor's log (journalctl --user / ~/Library/Logs/) without being
+  // noisy for monitoring tools that line-grep stderr. Keyed off the effective
+  // `watch` value, not the raw envvar, so an embedder calling startProxy({
+  // watch: false }) with the envvar set sees "off" (which is the truth — the
+  // watcher is suppressed regardless of envvar in that case). Supervisor-
+  // neutral wording — no version pin (lives in CHANGELOG/README instead).
+  if (watch) {
+    process.stderr.write(
+      "[cache-fix] hot-reload: on (CACHE_FIX_HOT_RELOAD=on) — long-running processes can hit a Node ESM stale-import race; see #196. Restart the proxy via your supervisor to recover.\n",
+    );
+  } else {
+    process.stderr.write(
+      "[cache-fix] hot-reload: off (set CACHE_FIX_HOT_RELOAD=on to enable). Extension changes require a supervisor-level proxy restart.\n",
+    );
+  }
 
   let watcher = null;
   try {

package/templates/cache-fix-proxy.service.template

@@ -11,6 +11,7 @@ RestartSec=5
 Environment=CACHE_FIX_PROXY_PORT={{PORT}}
 {{UPSTREAM_LINE}}
 {{DEBUG_LINE}}
+{{HOT_RELOAD_LINE}}
 WorkingDirectory={{WORKING_DIR}}
 
 [Install]

package/templates/com.cnighswonger.cache-fix-proxy.plist.template

@@ -15,6 +15,7 @@
         <string>{{PORT}}</string>
 {{UPSTREAM_PLIST}}
 {{DEBUG_PLIST}}
+{{HOT_RELOAD_PLIST}}
     </dict>
     <key>WorkingDirectory</key>
     <string>{{WORKING_DIR}}</string>

package/tools/MANUAL-COMPACT.md

@@ -10,10 +10,10 @@ When using the 1M context window hack (`DISABLE_COMPACT=1` + `CLAUDE_CODE_MAX_CO
 
 1. Extracts conversation turns from the session JSONL transcript
 2. Splits turns into three weighted segments:
-   - **Foundational** (first 20%) — truncated to 200 chars each
-   - **Working** (middle 40%) — truncated to 400 chars each
-   - **Active** (last 40%) — preserved up to 2000 chars each
-3. Sends the weighted extract to Claude Sonnet for summarization
+   - **Foundational** (first 20%) — truncated to 300 chars each
+   - **Working** (middle 40%) — truncated to 1500 chars each
+   - **Active** (last 40%) — preserved up to 8000 chars each
+3. Sends the weighted extract to Claude Opus for summarization
 4. Produces a structured summary optimized for agent handoff
 
 The weighting ensures recent active work (the part you're most likely to need) gets full detail, while earlier completed work is compressed.
@@ -56,7 +56,7 @@ Always:
 ```
 
 ```
-Project directory: /home/manager/git_repos/kanfei_nowcast_e3b
+Project directory: ~/git_repos/your-project
 Auto-detected session: db11f377-4ca8-4fc3-9b6d-1069da58c1b2.jsonl
   Modified: 2026-04-19 13:26:42
   Size: 4.8M
@@ -142,7 +142,7 @@ Use the user context file to fill known gaps.
 
 Two costs to account for:
 
-1. **Summarization call** — the `claude --print` call through Sonnet. At ~50K extract tokens, expect ~1-2% Q5h.
+1. **Summarization call** — the `claude --print` call through Opus. With the relaxed recent-turn caps the extract is larger (and Opus costs more per token than Sonnet), so expect a few % Q5h rather than ~1-2%. The tradeoff buys markedly higher-fidelity summaries; override with `MANUAL_COMPACT_MODEL=claude-sonnet-4-6` if you need to minimize cost.
 2. **Cold start after /clear** — the first API call rebuilds the full cache from scratch. Real-world example from a 954K-token session:
 
 ```
@@ -153,11 +153,33 @@ Second call:    cache_read=957,253  cache_creation=5,569   (warm again)
 
 The cold rebuild consumed ~15% Q5h in one call on our Max 5x account. After that single rebuild, the session is warm again and cache hits resume at 99%+.
 
-**Total cost of a manual compact cycle:** ~17% Q5h (2% summarization + 15% cold rebuild). Compare to hitting the 1M wall and losing the session entirely.
+**Total cost of a manual compact cycle:** roughly ~15% cold rebuild plus a few % for the Opus summarization. Compare to hitting the 1M wall and losing the session entirely.
 
-### Requires Claude Sonnet access
+### Stale transcripts get swept (CC's `cleanupPeriodDays`)
 
-The tool uses `claude --print --model claude-sonnet-4-6` for summarization. Sonnet is used instead of Opus to minimize Q5h impact. If Sonnet is unavailable, change the model in the script.
+Heads up if you're treating the on-disk `.jsonl` as a "keep just in case" backup after `/clear`: it isn't durable. Claude Code maintains a transcript-retention setting `cleanupPeriodDays` in `~/.claude/settings.json` (default 30 days). CC runs a transcript cleanup at startup when its `~/.claude/.last-cleanup` sentinel is past the 24h freshness window — when that fires, CC walks every `.jsonl` under `~/.claude/projects/` and deletes any whose `mtime` is past the cutoff, along with the matching `<session-id>/` companion directory next to it. A session you compacted, `/clear`-ed, and stopped retaining ~31 days ago will be gone after the next launch that crosses the cleanup gate, even if you'd planned to grep it for context.
+
+Practical implications:
+
+- **If you need the post-compact JSONL preserved**, copy it out of `~/.claude/projects/` to a path that isn't subject to CC's cleanup — e.g. `~/snapshots/cc-jsonl-backups/`.
+- **A stopped session held in heal-and-await state is especially vulnerable** — it's idle by definition, so it crosses `cleanupPeriodDays` faster than an actively-used session whose appends keep mtime fresh. If you've stopped a session intending to resume later, either resume promptly, `touch` the `.jsonl` to refresh mtime, or copy it out of the tree.
+- Cleanup keys off `mtime`, and plain reads (`cat`/`grep`/`less`) don't refresh `mtime` — inspection doesn't extend retention.
+- **Raise the retention setting on every machine you use CC on.** Adding `"cleanupPeriodDays": 36500` (~100 years) to `~/.claude/settings.json` defangs the documented cleanup path entirely. There's no documented upper bound; the schema just wants a positive integer. The cleanup logic re-reads the setting at each sweep, so you can land this even on machines where prior sweeps already happened.
+
+**If a transcript was already swept** and you need to recover it, [`vsits/restore-claude-history-linux`](https://github.com/vsits/restore-claude-history-linux) (RCB) restores deleted `.jsonl` files from Linux filesystem snapshots — **ZFS**, **Btrfs**, or **Timeshift**. End-to-end-verified on Ubuntu 24.04; a real Btrfs dogfood confirmed a recovered transcript loads and resumes via `/resume` in a fresh CC session. macOS users have the same shape via the upstream [`garrettmoss/restore-claude-history`](https://github.com/garrettmoss/restore-claude-history) (Time Machine). Both tools also remind you to set `cleanupPeriodDays` afterward — otherwise the restored transcript gets re-swept on the next cleanup pass.
+
+Tracked upstream as [anthropics/claude-code#62272](https://github.com/anthropics/claude-code/issues/62272) — cache-fix doesn't touch this surface, but documenting it because manual-compact users are the population most likely to bank on the `.jsonl` sticking around.
+
+### Summarizer model
+
+The tool defaults to `claude --print --model claude-opus-4-7` for the highest-fidelity summary. Override with the `MANUAL_COMPACT_MODEL` env var — e.g. `MANUAL_COMPACT_MODEL=claude-sonnet-4-6` to minimize Q5h impact, or to point at a different model if Opus is rate-limited or retired.
+
+### Troubleshooting: empty summary output
+
+If `$OUTPUT` comes back empty, the most likely cause is that the extract exceeded the summarizer's context window — this tool runs near the 1M wall, and the relaxed recent-turn caps (active turns up to 8000 chars) make the extract large on exactly those big sessions. The summarizer call swallows stderr, so an oversized-input rejection surfaces as an empty file rather than a visible error. Fixes, in order of preference:
+
+- Use a 1M-window model for the summarization: `MANUAL_COMPACT_MODEL='claude-opus-4-7[1m]' manual-compact.sh ...`
+- Or lower the per-turn caps in the script's extraction block (the `text[:8000]` / `text[:1500]` / `text[:300]` slices).
 
 ## Why the 1M Hack Disables /compact
 

package/tools/manual-compact.sh

@@ -145,31 +145,33 @@ if total == 0:
     sys.exit(1)
 
 # Split into three segments with different detail levels:
-# - First 20%: truncate to 200 chars each (foundational context)
-# - Middle 40%: truncate to 400 chars each (working context)
-# - Last 40%: full text up to 2000 chars each (active work — most important)
+# - First 20%: truncate to 300 chars each (foundational context)
+# - Middle 40%: truncate to 1500 chars each (working context)
+# - Last 40%: full text up to 8000 chars each (active work — most important)
+# Recent-turn caps were relaxed (was 200/400/2000) so the summarizer sees the
+# active work in near-full detail; the stronger model (Opus, below) handles it.
 seg1_end = int(total * 0.2)
 seg2_end = int(total * 0.6)
 
 with open("$EXTRACT", 'w') as f:
     f.write("=== FOUNDATIONAL CONTEXT (early session) ===\n\n")
     for role, text in conversation[:seg1_end]:
-        f.write(f"[{role}]: {text[:200]}\n\n")
+        f.write(f"[{role}]: {text[:300]}\n\n")
 
     f.write("\n=== WORKING CONTEXT (mid session) ===\n\n")
     for role, text in conversation[seg1_end:seg2_end]:
-        f.write(f"[{role}]: {text[:400]}\n\n")
+        f.write(f"[{role}]: {text[:1500]}\n\n")
 
     f.write("\n=== ACTIVE WORK (recent — preserve in full detail) ===\n\n")
     for role, text in conversation[seg2_end:]:
-        f.write(f"[{role}]: {text[:2000]}\n\n")
+        f.write(f"[{role}]: {text[:8000]}\n\n")
 
 import os
 size = os.path.getsize("$EXTRACT")
 print(f"Extracted {total} turns ({size:,} bytes, ~{size//4:,} est. tokens)")
-print(f"  Foundational: {seg1_end} turns (truncated to 200 chars)")
-print(f"  Working: {seg2_end - seg1_end} turns (truncated to 400 chars)")
-print(f"  Active: {total - seg2_end} turns (up to 2000 chars)")
+print(f"  Foundational: {seg1_end} turns (truncated to 300 chars)")
+print(f"  Working: {seg2_end - seg1_end} turns (truncated to 1500 chars)")
+print(f"  Active: {total - seg2_end} turns (up to 8000 chars)")
 PYEOF
 
 # Build the summarization prompt
@@ -199,10 +201,14 @@ ADDITIONAL USER CONTEXT TO PRESERVE:
 $USER_CONTEXT"
 fi
 
+# Summarizer model. Defaults to Opus for highest-fidelity summaries; override
+# with MANUAL_COMPACT_MODEL (e.g. when Opus is rate-limited or retired).
+COMPACT_MODEL="${MANUAL_COMPACT_MODEL:-claude-opus-4-7}"
+
 echo ""
-echo "Sending to Claude for summarization..."
+echo "Sending to Claude ($COMPACT_MODEL) for summarization..."
 
-cat "$EXTRACT" | claude --print --model claude-sonnet-4-6 "$PROMPT" > "$OUTPUT" 2>/dev/null
+cat "$EXTRACT" | claude --print --model "$COMPACT_MODEL" "$PROMPT" > "$OUTPUT" 2>/dev/null
 
 SIZE=$(wc -c < "$OUTPUT")
 echo ""

package/tools/quota-statusline.sh

@@ -115,11 +115,13 @@ 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))
+    def to_cells(pct):
+        return int(round(max(0, min(100, pct)) / 100 * width))
+    fill = to_cells(consumed_pct)
     if elapsed_pct is None:
         tick = -1
     else:
-        tick = min(int(max(0, min(100, elapsed_pct)) / 100 * width), width - 1)
+        tick = min(to_cells(elapsed_pct), width - 1)
     cells = []
     remaining = fill
     for i in range(width):