pi-jar 0.2.3 → 0.2.4

package/README.md

@@ -20,7 +20,7 @@ The showcase is captured from a real pi-jar terminal session: the torch-style `
 | **Goal mode** | Set an outcome; the agent must break it into tracked tasks and keeps working until they are done, then an **auditor** pass verifies the goal before it can be marked complete. |
 | **Roles** | Named model roles (`default`, `smol`, `slow`, `plan`, `implement`, `advisor`, `moderator`, `scout`, `worker`, `reviewer`, `task`, `commit`, plus your own) with aliases, effort, per-role fallback models and project overrides. |
 | **Advisor** | A second-opinion model: the agent calls `jar_advisor` when you ask or after two failed attempts, `/advisor [focus]` asks on demand, and opt-in automatic gates consult it when the agent repeats the same tool call or keeps failing. |
-| **Usage & context** | `/usage` shows session cost and tokens per model (advisor and commit calls included) and plan-limit bars with reset times; `/context` draws a grid of what fills the context window, with a per-file, per-skill and per-tool breakdown. |
+| **Usage & context** | `/usage` shows session cost and tokens per model (advisor and commit calls included) and plan-limit bars with reset times; `/context` draws a grid of what fills the context window, with a per-file, per-skill and per-tool breakdown; `/cache-breaks` names the tool, system section or message whose change forced a costly prompt-cache rewrite. |
 | **Commit** | `/jar commit [note]` drafts a message for the staged changes with the `commit` role, lets you edit it, then commits (never pushes). |
 | **Tasks & questions** | A Claude/omp-style `jar_todo` checklist with subtasks and per-task progress that the agent maintains itself, and `jar_ask` structured questions with options, multi-select and free-form answers. |
 | **Change review** | Every file the agent or its editing subagents change is remembered as it was; `/diff` (<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>D</kbd>) shows changed files (each counted once) next to a colored diff, with accept or revert per file or all at once. |
@@ -59,6 +59,7 @@ Pi only delivers mouse events in its **fullscreen** TUI mode. In regular mode th
 | `/profiles` | Create or switch profiles. `/profiles new` creates (name and theme, then roles), `/profiles <name>` switches. |
 | `/advisor [focus]` | Ask the advisor for a second opinion on the current work; the answer joins the conversation. |
 | `/usage` · `/context` | Usage (cost, tokens per model, plan limits) and context-window breakdown in one tabbed panel. |
+| `/cache-breaks` | The panel's **Cache** tab: costly prompt-cache breaks in this session, what changed, tokens rewritten and the estimated extra cost. See [Cache break diagnostics](#cache-break-diagnostics). |
 | `/jar commit [note]` | Draft a commit message for the staged changes with the `commit` role, edit it, and commit. Offers `git add -A` when nothing is staged. |
 | `/jar` · `/jar settings` | Visual and workflow preferences. |
 | `/jar status` | One-line status summary. |
@@ -250,10 +251,37 @@ This is a pi-jar enhancement: [pi-advisor](https://github.com/philipbrembeck/pi-
 
 ## Usage and context
 
-`/usage` and `/context` open one tabbed panel (<kbd>Tab</kbd> switches, <kbd>Esc</kbd> closes):
+`/usage`, `/context` and `/cache-breaks` open one tabbed panel (<kbd>Tab</kbd> switches, <kbd>Esc</kbd> closes):
 
 - **Usage** — total cost, duration, prompts and responses, tokens (input, output, cache read/write); a per-model breakdown including advisor and commit calls; and, for Anthropic and OpenAI Codex subscriptions, 5-hour and weekly limit bars with reset times (lookups follow `/jar quota on|off`). A failed lookup shows its reason (for example the provider's HTTP 429 rate limit) and when it retries, instead of loading indefinitely.
 - **Context** — a 10×10 grid (each cell ≈ 1% of the window) beside a legend: system prompt, tools, context files, skills, compaction summary, user and assistant messages, tool results, extension messages, free space and the autocompact buffer. Parts are estimated at ~4 characters per token and scaled to the provider-reported total when one is known; context files, skills and tools are listed individually below.
+- **Cache** — the costly prompt-cache breaks of this session with totals by cause; see below.
+
+### Cache break diagnostics
+
+Providers cache a prompt as an ordered prefix: tools, then the system prompt, then the messages. Change anything early in a request and the provider re-processes, and bills again, everything after it. Pi tells you *that* a call missed the cache; pi-jar tells you *what changed*. It is on by default (**`/jar settings` → Pi → Cache diagnostics**, saved per profile) and only observes: it never modifies a request or a message.
+
+- **How it finds the change.** For every provider request pi-jar reduces the final payload (Anthropic Messages, OpenAI Responses and Chat Completions; other shapes are skipped) to an ordered list of segments: the model, each tool, each system-prompt section (`<tools>`, `<skills>`, … or markdown headings and paragraphs) and each message, labelled by role or tool name. A segment keeps only a hash and a size, never content, and the cache markers that move with every call are ignored. The first segment where the previous request is no longer a prefix of this one is the change.
+- **When it matters.** The call's own usage decides. A *costly break* is a call whose cache read fell more than 4,096 tokens short of the previous prompt, or that read nothing from a prompt over 8,192 tokens. Appending messages never is one. The first call of a session, and the first after compaction or tree navigation (which rewrite the history on purpose), have nothing to compare with, and providers that never report cache reads are skipped.
+- **What you see.** One warning per costly break, with the extra cost estimated from the call's own prices, and the **Cache** tab (`/cache-breaks`) with totals by cause:
+
+  ```text
+  cache break: tools changed (+jendral_build_get, +17 more) — rewrote 235k tokens (~$1.89)
+  ```
+
+  | Cause | Reading it |
+  | --- | --- |
+  | `tools changed (+a, -b, ~c)` | Tools were added, removed or redefined, or `reordered`. Activating tools mid-session (an MCP server, a tool package) rewrites the whole prompt. |
+  | `system prompt changed (~<skills>)` | The named sections changed (`~`), appeared (`+`) or went (`-`). |
+  | `message 14/87 shrank (tool result: read, 52k → 98 chars, 73 from the end)` | An earlier message was rewritten, for example by an extension that replaces old tool results with placeholders; everything after it is re-processed. `first change` in the tab gives its position in the ordered prompt. |
+  | `history shortened (87 → 40 messages)` | Messages were dropped from the end of the history. |
+  | `model changed (a → b)` | A different model or provider has its own cache. |
+  | `cache expired after 12m idle` | The prompt is unchanged, but more than about 5 minutes passed since the cache was last warm (Pi's cache warming counts). |
+  | `no prompt change found` | The prefix is identical, so the content of the prompt does not explain the miss: provider-side eviction, or a request setting outside the fingerprint such as the thinking level or `tool_choice`. |
+
+  A change is followed by `, after 12m idle` when the cache had also lapsed.
+- **Where it is kept.** Each costly break is appended as one JSON line to `pi-jar-cache-breaks/<session id>.jsonl` in Pi's agent directory, so it survives `/reload` and resuming the session: `timestamp`, `request` (provider calls pi-jar has seen for the session), `kind`, `summary`, `segment` and `first` (the first changed segment), `model`, `promptTokens`, `cacheReadTokens`, `rewrittenTokens`, `costUsd` and `idleMs`. Hashes and prompt text are never written.
+- **Limits.** pi-jar fingerprints the payload as it sees it; a `before_provider_request` handler of an extension loaded after pi-jar can still change it. Subagent processes do not run the diagnostic.
 
 ## Tasks, questions and history
 
@@ -286,7 +314,7 @@ This is a pi-jar enhancement: [pi-advisor](https://github.com/philipbrembeck/pi-
 
 - **Appearance** — accent, motion, rounded composer, Ember mascot, next-prompt suggestions, pi-jar UI, icons (`unicode` default, `nerd` for a [Nerd Font](https://www.nerdfonts.com) terminal like omp's nerd preset, `ascii` for plain labels).
 - **Footer** — field visibility. In fullscreen mode the session name (or `sessions` for an unnamed session) opens the session picker and each subagent/shell row opens the activity view. SoL-Pi's savings status is not repeated in the footer (it already notifies).
-- **Pi** — mouse clicks (Pi fullscreen mode), copy on select, goal auto rounds, **Max subagents** (explicit choice then Save; default 2, existing saved values are kept), advisor, advisor gates (default off), context diet, context budget and its limit, repeated-read stub.
+- **Pi** — mouse clicks (Pi fullscreen mode), copy on select, goal auto rounds, **Max subagents** (explicit choice then Save; default 2, existing saved values are kept), advisor, advisor gates (default off), context diet, cache diagnostics (default on), context budget and its limit, repeated-read stub.
 
 pi-jar preferences are saved in `pi-jar-settings.json` in Pi's agent directory; the Pi tab writes Pi's own settings.
 
@@ -301,6 +329,7 @@ pi-jar/
 ├── extensions/index.ts   extension entry: wiring, welcome, footer, commands
 ├── src/
 │   ├── context-budget.ts context budget, per-call cost average, topic and cold-cache hints
+│   ├── cache-breaks.ts   prompt-cache break diagnostics: payload fingerprints, diff, usage correlation, JSONL log; cache-breaks-view.ts is its tab
 │   ├── flame.ts          pixel fire simulation
 │   ├── mascot.ts         Ember's moods and sprites
 │   ├── composer.ts       rounded composer, ghost text, mouse mapping

package/docs/DEVELOPMENT.md

@@ -43,7 +43,7 @@ npm run check      # tsc --noEmit
 npm test           # node:test suites in tests/
 ```
 
-Tests isolate `PI_CODING_AGENT_DIR`, so they never touch your real preferences. Suites cover the flame simulation, welcome layout and hit-testing, composer framing/expansion/ghost text/mouse mapping, the mascot, plan mode (guards, submission, reminders, restore), the plan view, plan parsing, the goal loop, roles v2, suggestions and settings.
+Tests isolate `PI_CODING_AGENT_DIR`, so they never touch your real preferences. Suites cover the flame simulation, welcome layout and hit-testing, composer framing/expansion/ghost text/mouse mapping, the mascot, plan mode (guards, submission, reminders, restore), the plan view, plan parsing, the goal loop, roles v2, suggestions, settings and the cache-break diagnostic (payload fingerprints for Anthropic and OpenAI shapes, diff classification, usage correlation, the `/cache-breaks` tab). `tests/cache-payloads.ts` builds the provider payloads those suites share.
 
 Manual smoke test (offline, throwaway agent directory, nothing sent to a model):
 
@@ -61,6 +61,7 @@ Then check:
 - `/jar activity`: select a subagent or background shell, scroll its live transcript/output, pause and resume follow, `Tab` into a subagent's transcript and expand/collapse entries, steer it with `s`, and stop/kill only the selected run;
 - `/roles`: the split manager, `n` new role, `a` alias, `s` scope;
 - `/plan`: the status shows `◆ PLAN · read-only` and a directory appears under `$TMPDIR/pi-jar/plans/`.
+- `/cache-breaks`: a fresh session reports no breaks and `/usage` has a **Cache** tab; with a logged-in model, activate an extra tool (or edit an earlier message through an extension) mid-session and expect `cache break: …` after the next call, plus a line in `pi-jar-cache-breaks/<session id>.jsonl` under the temporary agent directory; **Pi → Cache diagnostics** off silences both.
 
 For pointer interaction start with `--tui-mode fullscreen` (or enable **Pi → Mouse clicks** and restart). Check that welcome actions fire once per press, that footer activity rows open their matching details, that the footer session indicator opens search, that clicking composer text moves the cursor, that clicking Ember pokes it, that plan-view headings and actions respond to clicks and the wheel, and that selecting text anywhere still copies it. In regular mode use `/jar activity` and `/jar sessions` instead.
 

package/docs/EFFICIENCY_PLAN.md

@@ -48,10 +48,13 @@ Baseline: a 309-call, $6.34 session (`node scripts/session-cost.mjs 01a101ba-…
 | Events: ≤400-char summary + changed files, one message per boundary, discussion mail inlined | `src/delegate.ts`, `src/discussion.ts` | Events shrink from ~1.9 KB to ~0.5 KB; no `list` call to read mail; no echoes of own messages |
 | `/roles` warns when `scout`/`reviewer` run on the main model while a cheaper one is available | `src/model-roles.ts` | Subagent calls move to a cheaper model |
 | Advisor gates off by default; loop threshold 4; re-reads, shell polls and test reruns are never loops | `src/advisor.ts` | No side calls from normal fix loops |
+| Cache-break diagnostics: one notice per costly prompt-cache break, `/cache-breaks`, a per-session JSONL log | `src/cache-breaks.ts`, `src/cache-breaks-view.ts` | The tool list, system section or message that forced a rewrite is named instead of guessed |
 | Rules moved into tool descriptions; `jar_plan_submit`/`jar_goal` active only in their mode | all tool modules, `src/tool-activation.ts` | Smaller fixed prompt (below) |
 
 Fixed prompt that pi-jar contributes, measured from Pi's built system message in RPC mode (same project, same Pi 1.0.4): the `rules` section went from 7,584 to 1,675 characters and `tools` from 1,773 to 1,476; two schemas (~900 characters) are no longer sent outside their mode. Tool descriptions and schemas grew by ~1.1k characters because the guidance moved there. Net: ~5k characters (~1.3k tokens) less on every call. That is modest next to context growth, so the context budget and shell/read changes carry most of the saving.
 
+Cache breaks: an audit of a $30 session found ~68% of the cost was cache rewrites caused by prompt-prefix changes: tools activated mid-session (the cache read fell to 0 and ~230k tokens were rewritten per call), an extension replacing old tool results with placeholders (the read stuck at a mid-history offset), and one unexplained break at a user-turn boundary. Pi reports *that* a call missed the cache, not why. `src/cache-breaks.ts` fingerprints each provider payload (model, tools, system-prompt sections, messages; hashes and sizes only), finds the first segment where the previous request stopped being a prefix of this one, and joins that with the call's usage; a call whose cache read falls more than 4,096 tokens short of the previous prompt is a costly break. It only observes, and is on by default (`cacheDiagnostics`).
+
 Not done: Pi's compaction thresholds and the user's own settings are left alone; recommendations are in [INTEGRATIONS.md](./INTEGRATIONS.md#keeping-sessions-cheap-recommendations). The ≤ $3 field target needs a real re-run of a similar task with the new defaults.
 
 ## Already covered — dropped

package/docs/INTEGRATIONS.md

@@ -74,7 +74,7 @@ Mode-specific tools are deactivated when their mode is off, so their schema and
 
 ## Commands that overlap other packages
 
-pi-jar registers `/usage`, `/context` and `/advisor`. Pi keeps both commands when two extensions register the same name and suffixes the later one (for example `/usage:2`), so remove packages whose commands you no longer need (such as a separate usage, context or advisor extension) to keep the plain names on pi-jar.
+pi-jar registers `/usage`, `/context`, `/cache-breaks` and `/advisor`. Pi keeps both commands when two extensions register the same name and suffixes the later one (for example `/usage:2`), so remove packages whose commands you no longer need (such as a separate usage, context or advisor extension) to keep the plain names on pi-jar.
 
 ## Keeping sessions cheap (recommendations)
 
@@ -83,6 +83,7 @@ Every model call re-sends the whole context, so cost grows with session length f
 - **Compact earlier.** In `~/.pi/agent/settings.json` set `"compaction": { "reserveTokens": 140000, "keepRecentTokens": 20000 }`. With a 272k-window model this compacts around 130k instead of near the limit. pi-jar's context budget (`/jar settings` → Context budget) suggests `/compact` or `/new` at the same point, or compacts at the next finished task when set to `compact`.
 - **Enable heavy tool packages per project.** A package such as `pi-mono-figma` (~20 tools) sends every schema on every call; enable it only in projects that use it.
 - **Load each MCP server once.** Use codebase-memory either through the lazy `mcp` proxy **or** as direct tools, not both.
+- **Activate tools at startup, not mid-session.** Changing the tool list, the system prompt or an earlier message makes the provider re-process the whole prefix after it: an MCP server or tool package switched on halfway through a long session rewrote ~230k tokens on every call until the cache caught up. pi-jar announces costly cache breaks and `/cache-breaks` lists what changed (see [Cache break diagnostics](../README.md#cache-break-diagnostics)).
 - **Review rarely used packages** (for example `i-have-adhd`, `pi-mono-loop`, `pi-mono-btw`) and enable them per project.
 - **One task per session.** Start `/new` when the next request is unrelated; pi-jar suggests it when a finished checklist is followed by a new prompt in a large context.
 - **Measure.** `node scripts/session-cost.mjs <session.jsonl | id>` (in a pi-jar checkout) reports calls, the cost split, context buckets, repeated reads, tool counts and cache misses for one session.

package/extensions/index.ts

@@ -26,6 +26,7 @@ import { ModelRoleManager } from "../src/model-roles.ts";
 import { jarCommit } from "../src/commit.ts";
 import { registerAdvisor } from "../src/advisor.ts";
 import { registerContextDiet } from "../src/context-diet.ts";
+import { registerCacheBreaks } from "../src/cache-breaks.ts";
 import { registerInfoPanels } from "../src/info-panels.ts";
 import { SideUsage } from "../src/side-model.ts";
 import { PlanMode } from "../src/plan.ts";
@@ -320,10 +321,13 @@ export default function piJar(pi: ExtensionAPI): void {
   const modelRoles = new ModelRoleManager(pi);
   const sideUsage = new SideUsage();
   registerContextDiet(pi, () => visualSettings.contextDiet === true);
+  // Observe-only: explains costly prompt-cache breaks; subagent processes have no UI to tell.
+  const cacheBreaks = registerCacheBreaks(pi, { enabled: () => !delegatedChild && visualSettings.cacheDiagnostics !== false });
   const advisor = registerAdvisor(pi, modelRoles, { enabled: () => !delegatedChild && visualSettings.advisor, gates: () => !delegatedChild && visualSettings.advisorGates, usage: sideUsage });
   registerInfoPanels(pi, { side: sideUsage, quotaEnabled: () => quotaCache?.enabled ?? false,
     quota: (ctx) => quotaCache?.get(ctx.model?.provider, welcomeStatuses(), Date.now()),
     quotaFailure: (ctx) => quotaCache?.failure(ctx.model?.provider, Date.now()),
+    cacheBreaks: (ctx) => cacheBreaks.state(ctx),
     refreshQuota: (ctx) => { quotaCache?.refresh(ctx.model?.provider, welcomeStatuses(), Date.now()); } });
   let followingTheme: string | undefined;
   const profileEntries = (ctx: ExtensionContext): readonly unknown[] => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jar",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "A warm, role-aware Pi terminal workspace with switchable profiles, animated UI, plan and goal workflows, tasks, change review, model roles, background shells and subagents.",
   "type": "module",
   "license": "MIT",

package/src/cache-breaks-view.ts

@@ -0,0 +1,56 @@
+import { homedir } from "node:os";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { BREAK_SHORTFALL_TOKENS, summarizeBreaks, type BreakKind, type CacheBreakState } from "./cache-breaks.ts";
+import { money, row, tokens, type Paint } from "./panel.ts";
+
+const CAUSES: Record<BreakKind, string> = {
+  model: "model switch", tools: "tool list changed", system: "system prompt changed", message: "message changed",
+  truncated: "history shortened", idle: "cache expired (idle)", unknown: "no prompt change found"
+};
+const HOW = `A break is a call whose cache read fell more than ${BREAK_SHORTFALL_TOKENS.toLocaleString("en-US")} tokens short of the previous prompt.`;
+
+const pad = (value: number) => String(value).padStart(2, "0");
+
+/** `10:42:03` today, `10-07 10:42` on an earlier day, in local time. */
+function when(timestamp: string, now: number): string {
+  const date = new Date(timestamp);
+  if (Number.isNaN(date.getTime())) return "?";
+  const clock = `${pad(date.getHours())}:${pad(date.getMinutes())}`;
+  return new Date(now).toDateString() === date.toDateString() ? `${clock}:${pad(date.getSeconds())}` : `${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${clock}`;
+}
+
+/** The Cache tab of /usage and /context, and `/cache-breaks`: costly prompt-cache breaks of the session, totals first. */
+export function cacheBreakLines(view: CacheBreakState & { now: number }, width: number, fg: Paint): string[] {
+  const inner = Math.max(20, width - 2);
+  const heading = (text: string) => fg("accent", text);
+  const extra = (amount: number) => fg("warning", "~" + money(amount));
+  const wrap = (text: string, color: string | undefined, indent = ""): string[] =>
+    wrapTextWithAnsi(text, Math.max(10, inner - indent.length)).map((line) => indent + (color ? fg(color, line) : line));
+  const totals = summarizeBreaks(view.breaks);
+  const lines: string[] = [];
+  if (!view.enabled) lines.push(...wrap("Cache diagnostics are off. Turn them on in /jar settings → Pi.", "warning"), "");
+  lines.push(heading("Session"), "  " + row("Calls checked", String(view.calls), inner - 2), "  " + row("Costly cache breaks", String(totals.count), inner - 2));
+  if (!totals.count) {
+    const none = view.calls ? "None so far." : "No call checked yet (Anthropic and OpenAI requests are read).";
+    return [...lines, ...wrap(none, "dim", "  "), "", ...wrap(HOW, "dim")];
+  }
+  lines.push("  " + row("Tokens rewritten", tokens(totals.rewritten), inner - 2));
+  if (totals.cost > 0) lines.push("  " + row("Estimated extra cost", extra(totals.cost), inner - 2));
+
+  lines.push("", heading("By cause"));
+  for (const [kind, sum] of [...totals.kinds].sort((a, b) => b[1].cost - a[1].cost || b[1].rewritten - a[1].rewritten)) {
+    lines.push("  " + row(CAUSES[kind], `${sum.count} · ${tokens(sum.rewritten)}${sum.cost > 0 ? " · " + extra(sum.cost) : ""}`, inner - 2));
+  }
+
+  lines.push("", heading("Breaks (oldest first)"));
+  for (const entry of view.breaks) {
+    lines.push(`  #${entry.request}  ${when(entry.timestamp, view.now)}  ${fg("warning", tokens(entry.rewrittenTokens) + " tokens")}${entry.costUsd !== undefined ? " · " + extra(entry.costUsd) : ""}`);
+    lines.push(...wrap(entry.summary, undefined, "       "));
+    if (entry.first !== undefined) lines.push(...wrap(`first change: ${entry.first} (segment ${entry.segment})`, "dim", "       "));
+  }
+
+  const home = homedir();
+  if (view.file) lines.push("", ...wrap("Log: " + (home && view.file.startsWith(home) ? "~" + view.file.slice(home.length) : view.file), "dim"));
+  lines.push(...wrap(HOW, "dim"));
+  return lines;
+}

package/src/cache-breaks.ts

@@ -0,0 +1,521 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { CACHE_IDLE_MS, contextTokens, formatTokens } from "./context-budget.ts";
+import { duration, money } from "./panel.ts";
+
+/**
+ * Prompt-cache break diagnostics. Providers cache a prompt as an ordered prefix (tools, then system
+ * prompt, then messages), so changing anything early in a request makes the provider re-process, and
+ * bill again, everything after it. Pi tells you that a call missed the cache; this module says what changed.
+ *
+ * - before_provider_request: the final payload is reduced to an ordered list of {@link Segment}s (model,
+ *   each tool, each system-prompt section, each message), each a hash and a size: no content is kept. The
+ *   payload is only read, never replaced.
+ * - Comparing a request with the previous completed one finds the first segment where the earlier
+ *   sequence is no longer a prefix ({@link diffSegments}).
+ * - message_end: the call's usage says whether the provider actually missed ({@link judgeCall}). Only a
+ *   costly miss is a break: it is classified, logged to JSONL and announced once.
+ * Decisions here are pure; {@link registerCacheBreaks} feeds Pi events in.
+ */
+
+/** A call is a costly break when its cache read falls short of the previous prompt by more than this... */
+export const BREAK_SHORTFALL_TOKENS = 4096;
+/** ...or reads nothing from the cache although its prompt is larger than this. */
+export const BREAK_COLD_TOKENS = 8192;
+/** Breaks kept in memory for /cache-breaks; the JSONL log keeps every one. */
+const MAX_BREAKS = 200;
+/** A system prompt is split into at most this many sections; the remainder becomes one `rest` section. */
+const MAX_SECTIONS = 128;
+
+export type SegmentKind = "model" | "tool" | "system" | "message";
+/** Providers read the prompt in this order, so an earlier region changing invalidates every later one. */
+const KIND_ORDER: Record<SegmentKind, number> = { model: 0, tool: 1, system: 2, message: 3 };
+
+/** One ordered part of a provider prompt: what it is, a hash of its content, and its size in characters. */
+export interface Segment { kind: SegmentKind; label: string; hash: string; size: number }
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+const count = (value: unknown): number => typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+/** Provider cache breakpoints move to the newest block on every call: markers, not prompt content. */
+const dropMarkers = (key: string, value: unknown): unknown => key === "cache_control" ? undefined : value;
+
+/** Plain text of a string or of an array of text blocks; other blocks count by their JSON. */
+function textOf(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return "";
+  return value.map((part) => {
+    if (typeof part === "string") return part;
+    const block = record(part);
+    return typeof block?.text === "string" ? block.text : JSON.stringify(part, dropMarkers) ?? "";
+  }).join("\n\n");
+}
+
+const TAG_OPEN = /^<([A-Za-z][\w.-]*)(?:\s[^>]*)?>\s*$/;
+const HEADING = /^#{1,3}\s+(\S.*?)\s*$/;
+
+/**
+ * A system prompt as named sections, so a change can be located: top-level `<tag>…</tag>` blocks (how Pi
+ * assembles its prompt), markdown headings, and paragraphs for the text in between. Blank lines belong to
+ * the section after them, so appending a section leaves the earlier ones unchanged; trailing blank lines
+ * are ignored. Apart from those, sections tile the text, so any edit changes at least one section's hash.
+ */
+export function systemSections(text: string): { label: string; text: string }[] {
+  const lines = text.split("\n");
+  const spans: { label: string | undefined; from: number; to: number }[] = [];
+  let from = 0;
+  let label: string | undefined;
+  let closing: string | undefined;
+  const end = (to: number) => {
+    if (to > from) spans.push({ label, from, to });
+    from = to;
+  };
+  lines.forEach((line, index) => {
+    if (closing !== undefined) {
+      if (line.trim() !== closing) return;
+      end(index + 1);
+      label = closing = undefined;
+      return;
+    }
+    const tag = TAG_OPEN.exec(line);
+    const heading = tag ? null : HEADING.exec(line);
+    if (!tag && !heading) return;
+    end(index);
+    label = tag ? `<${tag[1]}>` : `# ${heading![1]!.slice(0, 48)}`;
+    if (tag) closing = `</${tag[1]}>`;
+  });
+  end(lines.length);
+
+  const sections: { label: string; text: string }[] = [];
+  const blanks: string[] = [];
+  let paragraph = 0;
+  const add = (label: string, body: string[]) => sections.push({ label, text: [...blanks.splice(0), ...body].join("\n") });
+  for (const span of spans) {
+    const body = lines.slice(span.from, span.to);
+    if (span.label !== undefined) {
+      let keep = body.length;
+      while (keep > 1 && body[keep - 1]!.trim() === "") keep--;
+      add(span.label, body.slice(0, keep));
+      blanks.push(...body.slice(keep));
+      continue;
+    }
+    // Loose text: a block is one paragraph together with the blank lines before it.
+    const blocks: string[][] = [[]];
+    let words = false;
+    for (const line of body) {
+      const blank = line.trim() === "";
+      if (blank && words) { blocks.push([]); words = false; }
+      blocks[blocks.length - 1]!.push(line);
+      if (!blank) words = true;
+    }
+    for (const block of blocks) {
+      if (block.every((line) => line.trim() === "")) blanks.push(...block);
+      else add(sections.length === 0 ? "preamble" : `text ${++paragraph}`, block);
+    }
+  }
+  if (sections.length > MAX_SECTIONS) {
+    const rest = sections.splice(MAX_SECTIONS - 1);
+    sections.push({ label: "rest", text: rest.map((section) => section.text).join("\n") });
+  }
+  const seen = new Map<string, number>();
+  return sections.map((section) => {
+    const times = (seen.get(section.label) ?? 0) + 1;
+    seen.set(section.label, times);
+    return times === 1 ? section : { ...section, label: `${section.label} #${times}` };
+  });
+}
+
+/** Remember which tool each call id belongs to, so a result can be labelled with its tool's name. */
+function rememberCalls(message: Record<string, unknown>, calls: Map<string, string>): void {
+  const remember = (id: unknown, name: unknown) => { if (typeof id === "string" && typeof name === "string") calls.set(id, name); };
+  remember(message.call_id, message.name); // Responses: function_call / custom_tool_call items
+  if (Array.isArray(message.content)) {
+    for (const block of message.content) {
+      const part = record(block);
+      if (part?.type === "tool_use") remember(part.id, part.name); // Anthropic
+    }
+  }
+  if (Array.isArray(message.tool_calls)) {
+    for (const call of message.tool_calls) {
+      const entry = record(call);
+      remember(entry?.id, record(entry?.function)?.name ?? entry?.name); // Chat Completions
+    }
+  }
+}
+
+/** `user`, `assistant`, `tool result: bash`, `tool call: bash`, `reasoning`, … for one message or input item. */
+function messageLabel(message: Record<string, unknown>, calls: ReadonlyMap<string, string>): string {
+  const type = message.type;
+  if (type === "function_call" || type === "custom_tool_call") return `tool call: ${typeof message.name === "string" ? message.name : "?"}`;
+  if (type === "function_call_output" || type === "custom_tool_call_output") return `tool result: ${calls.get(String(message.call_id)) ?? "?"}`;
+  if (message.role === "tool") return `tool result: ${calls.get(String(message.tool_call_id)) ?? (typeof message.name === "string" ? message.name : "?")}`;
+  if (Array.isArray(message.content)) {
+    const names = new Set<string>();
+    for (const block of message.content) {
+      const part = record(block);
+      if (part?.type === "tool_result") names.add(calls.get(String(part.tool_use_id)) ?? "?");
+    }
+    if (names.size) return `tool result: ${[...names].slice(0, 3).join(", ")}${names.size > 3 ? ` +${names.size - 3}` : ""}`;
+  }
+  return typeof message.role === "string" ? message.role : typeof type === "string" ? type : "message";
+}
+
+/**
+ * The ordered segments of a provider payload: the model, each tool, each system-prompt section, then each
+ * message. Understands Anthropic Messages (`system`, `messages`) and OpenAI Responses and Chat Completions
+ * (`instructions`, `input` / `messages`, with the system prompt as the leading system or developer item);
+ * any other shape is `undefined`. Cache markers are ignored. The payload is never modified.
+ */
+export function fingerprintPayload(payload: unknown, provider?: string): Segment[] | undefined {
+  const body = record(payload);
+  if (!body || typeof body.model !== "string") return undefined;
+  const input: unknown[] | undefined = Array.isArray(body.messages) ? body.messages : Array.isArray(body.input) ? body.input
+    : typeof body.input === "string" ? [{ role: "user", content: body.input }] : undefined;
+  if (!input) return undefined;
+
+  const segments: Segment[] = [];
+  const add = (kind: SegmentKind, label: string, value: unknown) => {
+    const text = typeof value === "string" ? value : JSON.stringify(value, dropMarkers) ?? "";
+    segments.push({ kind, label, hash: createHash("sha1").update(text).digest("base64url").slice(0, 12), size: text.length });
+  };
+  const model = provider ? `${provider}/${body.model}` : body.model;
+  add("model", model, model);
+
+  if (Array.isArray(body.tools)) {
+    body.tools.forEach((tool: unknown, index) => {
+      const definition = record(tool);
+      const inner = record(definition?.function);
+      const name = typeof definition?.name === "string" ? definition.name : typeof inner?.name === "string" ? inner.name
+        : typeof definition?.type === "string" ? definition.type : `tool ${index + 1}`;
+      add("tool", name, tool);
+    });
+  }
+
+  // The system prompt travels as `system` (Anthropic), `instructions` (Responses) or leading system/developer items.
+  const prompts = [textOf(body.system), textOf(body.instructions)];
+  let leading = 0;
+  for (; leading < input.length; leading++) {
+    const item = record(input[leading]);
+    if (!item || (item.role !== "system" && item.role !== "developer") || (item.type !== undefined && item.type !== "message")) break;
+    prompts.push(textOf(item.content));
+  }
+  const texts = prompts.filter((text) => text !== "");
+  texts.forEach((text, index) => {
+    for (const section of systemSections(text)) add("system", texts.length > 1 ? `#${index + 1} ${section.label}` : section.label, section.text);
+  });
+
+  const calls = new Map<string, string>();
+  for (const item of input.slice(leading)) {
+    const message = record(item);
+    if (message) rememberCalls(message, calls);
+    // A provider turns the newest message's string content into a text block to carry its cache marker.
+    const content = message && typeof message.content === "string" ? { ...message, content: [{ type: "text", text: message.content }] } : item;
+    add("message", message ? messageLabel(message, calls) : "message", content);
+  }
+  return segments;
+}
+
+/** Names that differ between two sections of a prompt (tools, or system sections). */
+interface Named { added: string[]; removed: string[]; changed: string[]; reordered: boolean }
+
+export type PromptChange = { segment: number; first: string } & (
+  | { kind: "model"; from: string; to: string }
+  | ({ kind: "tools" } & Named)
+  | ({ kind: "system" } & Named)
+  | { kind: "message"; index: number; total: number; label: string; before: number; after: number; dropped: number }
+  | { kind: "truncated"; from: number; to: number });
+
+function diffNamed(before: readonly Segment[], after: readonly Segment[]): Named {
+  const was = new Map(before.map((segment) => [segment.label, segment.hash]));
+  const now = new Map(after.map((segment) => [segment.label, segment.hash]));
+  const added = [...now.keys()].filter((label) => !was.has(label));
+  const removed = [...was.keys()].filter((label) => !now.has(label));
+  const changed = [...now].filter(([label, hash]) => was.has(label) && was.get(label) !== hash).map(([label]) => label);
+  return { added, removed, changed, reordered: !added.length && !removed.length && !changed.length };
+}
+
+/**
+ * Where `current` stops extending `previous`: the first segment that differs, classified by the earliest
+ * prompt region it falls in. `undefined` when `previous` is a prefix of `current` (an identical prompt, or
+ * only messages appended), the normal case in which the provider cache is read up to the old end.
+ */
+export function diffSegments(previous: readonly Segment[], current: readonly Segment[]): PromptChange | undefined {
+  const shared = Math.min(previous.length, current.length);
+  let at = 0;
+  while (at < shared && previous[at]!.kind === current[at]!.kind && previous[at]!.hash === current[at]!.hash) at++;
+  if (at === previous.length) return undefined;
+  const old = previous[at]!;
+  const now = current[at];
+  const kind = now && KIND_ORDER[now.kind] < KIND_ORDER[old.kind] ? now.kind : old.kind;
+  // Name the segment of the changed region itself: a removed tool is `old`, an added one is `now`.
+  const first = `${kind} ${(now?.kind === kind ? now : old).label}`;
+  const region = (segments: readonly Segment[]) => segments.filter((segment) => segment.kind === kind);
+  if (kind === "model") return { kind, segment: at, first, from: old.label, to: now?.label ?? "" };
+  if (kind === "tool") return { kind: "tools", segment: at, first, ...diffNamed(region(previous), region(current)) };
+  if (kind === "system") return { kind, segment: at, first, ...diffNamed(region(previous), region(current)) };
+  const before = region(previous).length;
+  const total = region(current).length;
+  if (!now) return { kind: "truncated", segment: at, first, from: before, to: total };
+  return { kind: "message", segment: at, first, index: at - previous.findIndex((segment) => segment.kind === "message"), total,
+    label: now.label, before: old.size, after: now.size, dropped: Math.max(0, before - total) };
+}
+
+/** `+added, -removed, ~changed`, at most three entries before `+N more`. */
+function nameList(change: Named): string {
+  const entries = [...change.added.map((name) => `+${name}`), ...change.removed.map((name) => `-${name}`), ...change.changed.map((name) => `~${name}`)];
+  if (!entries.length) return "reordered";
+  return (entries.length > 3 ? [...entries.slice(0, 2), `+${entries.length - 2} more`] : entries).join(", ");
+}
+
+/** One clause naming what changed: `tools changed (+jendral_build_get, +17 more)`. */
+function describeChange(change: PromptChange): string {
+  switch (change.kind) {
+    case "model": return `model changed (${change.from} → ${change.to})`;
+    case "tools": return `tools changed (${nameList(change)})`;
+    case "system": return `system prompt changed (${nameList(change)})`;
+    case "truncated": return `history shortened (${change.from} → ${change.to} messages)`;
+    case "message": {
+      const size = change.after < change.before ? `, ${formatTokens(change.before)} → ${formatTokens(change.after)} chars` : "";
+      const dropped = change.dropped ? `; ${change.dropped} message${change.dropped === 1 ? "" : "s"} dropped` : "";
+      return `message ${change.index + 1}/${change.total} ${change.after < change.before ? "shrank" : "changed"} (${change.label}${size}, ${change.total - 1 - change.index} from the end)${dropped}`;
+    }
+  }
+}
+
+/** The usage a provider reported for one call. */
+export interface CallUsage {
+  input?: unknown; cacheRead?: unknown; cacheWrite?: unknown;
+  cost?: { input?: unknown; cacheRead?: unknown; cacheWrite?: unknown; total?: unknown };
+}
+
+/**
+ * Whether a call's cache read fits the previous prompt. `rewritten` is the part of the previous prompt (or
+ * of this one, when smaller) that was billed again instead of read from the cache; a call is costly when
+ * that exceeds {@link BREAK_SHORTFALL_TOKENS}, or when nothing was read from a prompt over {@link BREAK_COLD_TOKENS}.
+ */
+export function judgeCall(previousPrompt: number, usage: CallUsage | undefined): { rewritten: number; costly: boolean } {
+  const prompt = contextTokens(usage);
+  const cacheRead = count(usage?.cacheRead);
+  const rewritten = Math.max(0, Math.min(previousPrompt, prompt) - cacheRead);
+  return { rewritten, costly: rewritten > BREAK_SHORTFALL_TOKENS || (cacheRead === 0 && prompt > BREAK_COLD_TOKENS) };
+}
+
+/**
+ * Extra dollars the rewritten tokens cost over reading them from the cache, from the call's own cost split:
+ * its average price per fresh token (input plus cache write), minus its cache-read price (taken from the
+ * call, else `readPerMTok`, the model's price per million tokens, else free). Undefined without a cost.
+ */
+export function rewriteCost(usage: CallUsage | undefined, rewritten: number, readPerMTok?: number): number | undefined {
+  const fresh = count(usage?.input) + count(usage?.cacheWrite);
+  const freshRate = fresh > 0 ? (count(usage?.cost?.input) + count(usage?.cost?.cacheWrite)) / fresh : 0;
+  if (!(freshRate > 0) || rewritten <= 0) return undefined;
+  const read = count(usage?.cacheRead);
+  const readRate = read > 0 && count(usage?.cost?.cacheRead) > 0 ? count(usage?.cost?.cacheRead) / read : count(readPerMTok) / 1_000_000;
+  return Math.round(rewritten * Math.max(0, freshRate - readRate) * 10_000) / 10_000;
+}
+
+export type BreakKind = PromptChange["kind"] | "idle" | "unknown";
+
+/** One costly break, as listed by /cache-breaks and appended to the session's JSONL log. */
+export interface CacheBreakRecord {
+  version: 1;
+  /** When the call was sent (ISO 8601). */
+  timestamp: string;
+  /** Provider calls observed for this session, counted from the first one pi-jar saw. */
+  request: number;
+  /** What changed: a prompt region, an expired cache (`idle`) or `unknown` when nothing in the prompt changed. */
+  kind: BreakKind;
+  summary: string;
+  /** Index of the first changed segment in the ordered prompt (model, tools, system sections, messages), and what it is. */
+  segment?: number;
+  first?: string;
+  model: string;
+  promptTokens: number;
+  cacheReadTokens: number;
+  /** Tokens of the previous prompt that were billed again instead of read from the cache. */
+  rewrittenTokens: number;
+  /** Estimated extra cost in USD, when the call reported its cost. */
+  costUsd?: number;
+  /** Time since the cache was last known warm. */
+  idleMs: number;
+}
+
+interface Baseline { segments: readonly Segment[]; prompt: number; at: number }
+interface Pending { segments: readonly Segment[]; change: PromptChange | undefined }
+
+/**
+ * Correlates provider requests with the calls' usage. Feed it `request` for every provider payload and
+ * `complete` for every assistant message; the baseline is the last completed call, so a failed or aborted
+ * request neither moves it nor can be mistaken for a break.
+ */
+export class CacheBreakTracker {
+  private baseline: Baseline | undefined;
+  private pending: Pending | undefined;
+  private warmAt = 0;
+  private cacheSeen = false;
+  private calls = 0;
+  private offset = 0;
+  private log: CacheBreakRecord[] = [];
+
+  /** Calls checked since this session was loaded. */
+  get checked(): number { return this.calls; }
+  get breaks(): readonly CacheBreakRecord[] { return this.log; }
+
+  /** The prompt about to be sent; `undefined` when the payload could not be fingerprinted. */
+  request(segments: readonly Segment[] | undefined): void {
+    this.pending = segments ? { segments, change: this.baseline ? diffSegments(this.baseline.segments, segments) : undefined } : undefined;
+  }
+
+  /** A deliberate change of history (compaction, tree navigation, disabling): the next call has nothing to compare with. */
+  rebase(): void {
+    this.baseline = undefined;
+    this.pending = undefined;
+  }
+
+  /** Pi refreshed the provider cache while idle, which restarts its lifetime. */
+  warmed(at: number): void { this.warmAt = Math.max(this.warmAt, at); }
+
+  /** A new session: forget everything, then continue from the breaks an earlier run of it logged. */
+  reset(earlier: readonly CacheBreakRecord[] = []): void {
+    this.rebase();
+    this.warmAt = this.calls = 0;
+    this.cacheSeen = false;
+    this.log = earlier.slice(-MAX_BREAKS);
+    this.offset = earlier.reduce((last, entry) => Math.max(last, entry.request), 0);
+  }
+
+  /** An assistant message ended; the record when its call was a costly break. */
+  complete(call: { usage: CallUsage | undefined; at: number; model: string; readPerMTok?: number }): CacheBreakRecord | undefined {
+    const { pending, baseline } = this;
+    this.pending = undefined;
+    const prompt = contextTokens(call.usage);
+    if (!prompt) return undefined; // Nothing reached the provider: keep the last good baseline.
+    if (pending) this.calls++; // Only calls whose prompt was fingerprinted can be checked.
+    this.cacheSeen ||= count(call.usage?.cacheRead) + count(call.usage?.cacheWrite) > 0;
+    this.baseline = pending ? { segments: pending.segments, prompt, at: call.at } : undefined;
+    // Providers that never report caching make every call look cold, so wait for the first sign of it.
+    if (!pending || !baseline || !this.cacheSeen) return undefined;
+    const { rewritten, costly } = judgeCall(baseline.prompt, call.usage);
+    if (!costly) return undefined;
+    const idleMs = Math.max(0, call.at - Math.max(baseline.at, this.warmAt));
+    const idle = idleMs >= CACHE_IDLE_MS;
+    const { change } = pending;
+    const cost = rewriteCost(call.usage, rewritten, call.readPerMTok);
+    const entry: CacheBreakRecord = {
+      version: 1, timestamp: new Date(call.at).toISOString(), request: this.offset + this.calls,
+      kind: change?.kind ?? (idle ? "idle" : "unknown"),
+      summary: change ? describeChange(change) + (idle ? `, after ${duration(idleMs)} idle` : "")
+        : idle ? `cache expired after ${duration(idleMs)} idle` : "no prompt change found",
+      ...(change ? { segment: change.segment, first: change.first } : {}),
+      model: call.model, promptTokens: prompt, cacheReadTokens: count(call.usage?.cacheRead), rewrittenTokens: rewritten,
+      ...(cost !== undefined ? { costUsd: cost } : {}), idleMs
+    };
+    this.log = [...this.log, entry].slice(-MAX_BREAKS);
+    return entry;
+  }
+}
+
+export interface BreakTotals { count: number; rewritten: number; cost: number }
+
+/** Totals over breaks, overall and per cause. */
+export function summarizeBreaks(breaks: readonly CacheBreakRecord[]): BreakTotals & { kinds: Map<BreakKind, BreakTotals> } {
+  const total: BreakTotals = { count: 0, rewritten: 0, cost: 0 };
+  const kinds = new Map<BreakKind, BreakTotals>();
+  for (const entry of breaks) {
+    const bucket = kinds.get(entry.kind) ?? { count: 0, rewritten: 0, cost: 0 };
+    kinds.set(entry.kind, bucket);
+    for (const sum of [total, bucket]) { sum.count++; sum.rewritten += entry.rewrittenTokens; sum.cost += entry.costUsd ?? 0; }
+  }
+  return { ...total, kinds };
+}
+
+/** Per-session JSONL log: `<agent dir>/pi-jar-cache-breaks/<session id>.jsonl`. */
+export function cacheBreakFile(sessionId: string | undefined, directory = join(getAgentDir(), "pi-jar-cache-breaks")): string {
+  return join(directory, `${(sessionId ?? "").replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 64) || "session"}.jsonl`);
+}
+
+/** Breaks logged for a session so far; unreadable files and malformed lines are skipped. */
+export function readCacheBreaks(file: string): CacheBreakRecord[] {
+  let text: string;
+  try { text = readFileSync(file, "utf8"); } catch { return []; }
+  const breaks: CacheBreakRecord[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let parsed: Record<string, unknown> | undefined;
+    try { parsed = record(JSON.parse(line)); } catch { continue; }
+    if (parsed?.version === 1 && typeof parsed.kind === "string" && typeof parsed.summary === "string" && typeof parsed.timestamp === "string"
+      && Number.isFinite(parsed.request) && Number.isFinite(parsed.rewrittenTokens) && Number.isFinite(parsed.promptTokens)) breaks.push(parsed as unknown as CacheBreakRecord);
+  }
+  return breaks.slice(-MAX_BREAKS);
+}
+
+/** What the /cache-breaks tab shows. */
+export interface CacheBreakState { enabled: boolean; calls: number; breaks: readonly CacheBreakRecord[]; file: string | undefined }
+
+/** The one thing needed from Pi's context to find a session's log. */
+export interface SessionRef { sessionManager: { getSessionId(): string } }
+
+export interface CacheBreakOptions {
+  /** Runtime-toggleable setting; the caller owns its persisted value. */
+  enabled(): boolean;
+  /** Directory of the per-session logs; `pi-jar-cache-breaks` in Pi's agent directory by default (tests pass their own). */
+  directory?: string;
+}
+
+/**
+ * Watch provider requests and calls for costly cache breaks, announce each one and log it. Observes only:
+ * the payload and the messages are never modified. A fingerprint of a payload that another extension
+ * rewrites afterwards is of the payload as this extension saw it.
+ */
+export function registerCacheBreaks(pi: ExtensionAPI, options: CacheBreakOptions): { state(ctx: SessionRef): CacheBreakState } {
+  const tracker = new CacheBreakTracker();
+  const logFile = (ctx: SessionRef) => cacheBreakFile(ctx.sessionManager.getSessionId(), options.directory);
+
+  pi.on("session_start", (_event, ctx) => {
+    let earlier: CacheBreakRecord[] = [];
+    try { earlier = readCacheBreaks(logFile(ctx)); } catch { /* The log is optional. */ }
+    tracker.reset(earlier);
+  });
+  // Compaction and navigating the tree rewrite the history on purpose; the next call starts a new baseline.
+  pi.on("session_compact", () => tracker.rebase());
+  pi.on("session_tree", () => tracker.rebase());
+  pi.on("cache_warming_decision", (event) => { if (event.action === "warm") tracker.warmed(Date.now()); });
+
+  pi.on("before_provider_request", (event, ctx) => {
+    if (!options.enabled()) { tracker.rebase(); return; }
+    let segments: Segment[] | undefined;
+    try { segments = fingerprintPayload(event.payload, ctx.model?.provider); } catch { /* Not a JSON-shaped payload. */ }
+    tracker.request(segments);
+    // No return value: Pi keeps the payload as it is.
+  });
+
+  pi.on("message_end", (event, ctx) => {
+    const message = event.message;
+    if (message.role !== "assistant" || !options.enabled()) return;
+    try {
+      const model = ctx.model?.provider === message.provider && ctx.model.id === message.model ? ctx.model : ctx.modelRegistry?.find?.(message.provider, message.model);
+      const found = tracker.complete({
+        usage: message.usage, model: `${message.provider}/${message.model}`, readPerMTok: model?.cost?.cacheRead,
+        at: Number.isFinite(message.timestamp) && message.timestamp > 0 ? message.timestamp : Date.now()
+      });
+      if (!found) return;
+      try {
+        const file = logFile(ctx);
+        mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+        appendFileSync(file, JSON.stringify(found) + "\n", { mode: 0o600 });
+      } catch { /* The notice and the tab still report it. */ }
+      const cost = found.costUsd !== undefined ? ` (~${money(found.costUsd)})` : "";
+      ctx.ui.notify(`cache break: ${found.summary} — rewrote ${formatTokens(found.rewrittenTokens)} tokens${cost}`, "warning");
+    } catch { /* Diagnostics must never disturb a run. */ }
+  });
+
+  return {
+    state(ctx) {
+      let file: string | undefined;
+      try { file = logFile(ctx); } catch { /* No session id yet. */ }
+      return { enabled: options.enabled(), calls: tracker.checked, breaks: tracker.breaks, file };
+    }
+  };
+}

package/src/info-panels.ts

@@ -1,6 +1,8 @@
 import { getAgentDir, SettingsManager, type ExtensionAPI, type ExtensionContext, type Skill } from "@earendil-works/pi-coding-agent";
+import { cacheBreakLines } from "./cache-breaks-view.ts";
+import type { CacheBreakState } from "./cache-breaks.ts";
 import { contextBreakdown, contextLines } from "./context-view.ts";
-import { openPanel, type PanelTab } from "./panel.ts";
+import { openPanel, type Paint, type PanelTab } from "./panel.ts";
 import type { Quota } from "./quota.ts";
 import type { SideUsage } from "./side-model.ts";
 import { collectUsage, usageLines } from "./usage-view.ts";
@@ -16,6 +18,8 @@ export interface InfoPanelDeps {
   quotaEnabled(): boolean;
   /** Start a limit lookup when nothing fresh is cached: opening `/usage` is an explicit request. */
   refreshQuota(ctx: ExtensionContext): void;
+  /** Costly prompt-cache breaks of this session for the Cache tab and `/cache-breaks`; omitted when unavailable. */
+  cacheBreaks?(ctx: ExtensionContext): CacheBreakState;
 }
 
 function reserveTokens(ctx: ExtensionContext): number {
@@ -48,7 +52,7 @@ export function contextFor(pi: ExtensionAPI, ctx: ExtensionContext, options?: Pr
   });
 }
 
-/** `/usage` and `/context`: one tabbed panel, like Claude's usage and context views. */
+/** `/usage`, `/context` and `/cache-breaks`: one tabbed panel, like Claude's usage and context views. */
 export function registerInfoPanels(pi: ExtensionAPI, deps: InfoPanelDeps): void {
   let parts: PromptParts | undefined;
   pi.on("before_agent_start", (event) => {
@@ -76,7 +80,8 @@ export function registerInfoPanels(pi: ExtensionAPI, deps: InfoPanelDeps): void
       { name: "Context", render: (width, fg) => {
         context ??= contextFor(pi, ctx, parts);
         return contextLines(context, width, fg);
-      } }
+      } },
+      ...(deps.cacheBreaks ? [{ name: "Cache", render: (width: number, fg: Paint) => cacheBreakLines({ ...deps.cacheBreaks!(ctx), now: Date.now() }, width, fg) }] : [])
     ];
   };
   const plain = (_color: string, text: string) => text;
@@ -90,4 +95,5 @@ export function registerInfoPanels(pi: ExtensionAPI, deps: InfoPanelDeps): void
   };
   pi.registerCommand("usage", { description: "Session cost, tokens per model and plan limits (pi-jar)", handler: async (_args, ctx) => open(ctx, 0) });
   pi.registerCommand("context", { description: "Breakdown of what fills the context window (pi-jar)", handler: async (_args, ctx) => open(ctx, 1) });
+  if (deps.cacheBreaks) pi.registerCommand("cache-breaks", { description: "Costly prompt-cache breaks in this session and what changed (pi-jar)", handler: async (_args, ctx) => open(ctx, 2) });
 }

package/src/panel.ts

@@ -5,7 +5,7 @@ import { RowCache } from "./row-cache.ts";
 export type Paint = (color: string, text: string) => string;
 export interface PanelTab { name: string; render(width: number, fg: Paint): string[] }
 
-/** Tabbed, scrollable info panel (Usage / Context). Tab or click switches tabs; Esc closes. */
+/** Tabbed, scrollable info panel (Usage / Context / Cache). Tab or click switches tabs; Esc closes. */
 export async function openPanel(ctx: ExtensionContext, tabs: readonly PanelTab[], initial = 0): Promise<void> {
   if (!ctx.hasUI || ctx.mode !== "tui") return;
   await ctx.ui.custom<void>((tui, theme, _keys, done) => {

package/src/profiles.ts

@@ -42,6 +42,7 @@ function normalizeProfile(value: unknown): JarProfile | undefined {
     || typeof settings.composer !== "boolean" || typeof settings.mascot !== "boolean" || typeof settings.suggestions !== "boolean"
     || typeof settings.advisor !== "boolean" || typeof settings.advisorGates !== "boolean"
     || (settings.contextDiet !== undefined && typeof settings.contextDiet !== "boolean")
+    || (settings.cacheDiagnostics !== undefined && typeof settings.cacheDiagnostics !== "boolean")
     || (settings.contextBudget !== undefined && !parseContextBudget(settings.contextBudget))
     || (settings.readCache !== undefined && typeof settings.readCache !== "boolean") || !Number.isInteger(settings.goalRounds)
     || (settings.goalRounds as number) < 1 || (settings.goalRounds as number) > 50
@@ -54,7 +55,7 @@ function normalizeProfile(value: unknown): JarProfile | undefined {
   for (const [role, spec] of Object.entries(raw.roles.roles)) if (!isRoleName(role) || typeof spec !== "string" || !normalizeSpec(spec)) return undefined;
   const contextBudget = parseContextBudget(settings.contextBudget) ?? { ...DEFAULT_CONTEXT_BUDGET };
   return { id: raw.id as string, name: raw.name, theme: raw.theme, settings: { ...raw.settings, contextDiet: settings.contextDiet ?? false,
-    contextBudget, readCache: settings.readCache ?? false } as unknown as JarVisualSettings, roles: parseRoleConfig(raw.roles) };
+    cacheDiagnostics: settings.cacheDiagnostics ?? true, contextBudget, readCache: settings.readCache ?? false } as unknown as JarVisualSettings, roles: parseRoleConfig(raw.roles) };
 }
 function atomicSave(file: string, document: ProfileDocument): string {
   mkdirSync(join(file, ".."), { recursive: true });

package/src/settings-ui.ts

@@ -42,9 +42,9 @@ export async function openJarSettings(
       name === "default" || ["gray", "pink", "teal", "azure", "violet", "amber"].includes(name))];
     let choosing: "goalRounds" | "maxSubagents" | "contextBudget" | undefined;
     const choices = () => choosing === "maxSubagents" ? MAX_SUBAGENT_CHOICES : choosing === "contextBudget" ? CONTEXT_BUDGET_CHOICES : GOAL_ROUND_CHOICES;
-    const fields = () => choosing ? choices().length : page === "footer" ? FOOTER_FIELDS.length : page === "pi" ? 10 : page === "profiles" ? 2 : 7;
+    const fields = () => choosing ? choices().length : page === "footer" ? FOOTER_FIELDS.length : page === "pi" ? 11 : page === "profiles" ? 2 : 7;
     // Back on the row that opened the picker.
-    const finishChoice = () => { selected = choosing === "maxSubagents" ? 3 : choosing === "contextBudget" ? 8 : 2; choosing = undefined; };
+    const finishChoice = () => { selected = choosing === "maxSubagents" ? 3 : choosing === "contextBudget" ? 9 : 2; choosing = undefined; };
     const piError = (error: unknown) => ctx.ui.notify("Could not change Pi setting: " + (error as Error).message, "error");
     const explainPool = () => choosing === "maxSubagents" || (page === "pi" && !choosing && selected === 3);
     const pageSize = () => Math.min(fields(), Math.max(4, (process.stdout.rows ?? 24) - (explainPool() ? 10 : 9)));
@@ -78,15 +78,16 @@ export async function openJarSettings(
         else if (index === 4) update({ ...state, advisor: !state.advisor });
         else if (index === 5) update({ ...state, advisorGates: !state.advisorGates });
         else if (index === 6) update({ ...state, contextDiet: !state.contextDiet });
-        else if (index === 7) {
+        else if (index === 7) update({ ...state, cacheDiagnostics: !state.cacheDiagnostics });
+        else if (index === 8) {
           const at = CONTEXT_BUDGET_ACTIONS.indexOf(state.contextBudget.action);
           update({ ...state, contextBudget: { ...state.contextBudget, action: CONTEXT_BUDGET_ACTIONS[(at + 1) % CONTEXT_BUDGET_ACTIONS.length]! } });
         }
-        else if (index === 8) {
+        else if (index === 9) {
           choosing = "contextBudget";
           selected = Math.max(0, CONTEXT_BUDGET_CHOICES.indexOf(state.contextBudget.softTokens as never));
         }
-        else if (index === 9) update({ ...state, readCache: !state.readCache });
+        else if (index === 10) update({ ...state, readCache: !state.readCache });
       } else if (index === 0) {
         const at = Math.max(0, accents.indexOf(state.accent));
         update({ ...state, accent: accents[(at + 1) % accents.length]! });
@@ -176,9 +177,10 @@ export async function openJarSettings(
             row(4, "Advisor (jar_advisor, /advisor)", state.advisor ? "ON" : "OFF", state.advisor),
             row(5, "Advisor gates (loops, repeated failures)", state.advisorGates ? "ON" : "OFF", state.advisorGates),
           row(6, "Context diet (prior-turn reasoning)", state.contextDiet ? "ON" : "OFF", state.contextDiet),
-            row(7, "Context budget (past the limit)", state.contextBudget.action.toUpperCase(), budgetOn),
-            row(8, "Context budget limit", formatTokens(state.contextBudget.softTokens), budgetOn),
-            row(9, "Repeated-read stub (unchanged re-reads)", state.readCache ? "ON" : "OFF", state.readCache)
+            row(7, "Cache diagnostics (explain cache breaks)", state.cacheDiagnostics ? "ON" : "OFF", state.cacheDiagnostics),
+            row(8, "Context budget (past the limit)", state.contextBudget.action.toUpperCase(), budgetOn),
+            row(9, "Context budget limit", formatTokens(state.contextBudget.softTokens), budgetOn),
+            row(10, "Repeated-read stub (unchanged re-reads)", state.readCache ? "ON" : "OFF", state.readCache)
           ] : page === "profiles" ? [
             row(0, "Switch profile…", profiles!.activeName(), true),
             row(1, "Create profile…", "OPEN", true)
@@ -200,8 +202,9 @@ export async function openJarSettings(
           line(theme.fg("dim", explainPool() ? " Live pool includes idle/paused subagents"
             : choosing ? " Select a value; Enter/click to save, Esc to cancel"
             : page === "footer" ? ` Footer fields ${start + 1}–${start + rows.length}/${fields()}`
-            : page === "pi" ? (selected === 7 || selected === 8 ? " Past the limit: suggest /compact or /new, or compact at a safe point"
-              : selected === 9 ? " An unchanged re-read of the same range returns a short stub" : " Fullscreen mode enables clicks and copy-on-select")
+            : page === "pi" ? (selected === 7 ? " Names what changed when a call re-sent cached context (/cache-breaks)"
+              : selected === 8 || selected === 9 ? " Past the limit: suggest /compact or /new, or compact at a safe point"
+              : selected === 10 ? " An unchanged re-read of the same range returns a short stub" : " Fullscreen mode enables clicks and copy-on-select")
             : page === "profiles" ? " Switch only in a fresh, idle session; roles via /roles" : " Accent cycles through loaded themes")),
           ...rows,
           line(theme.fg("dim", choosing ? " ↑↓: choose · Enter/click: save · Esc: cancel"

package/src/settings.ts

@@ -25,6 +25,8 @@ export interface JarVisualSettings {
   advisorGates: boolean;
   /** Opt-in provider-context pruning of reasoning from completed earlier user turns. */
   contextDiet: boolean;
+  /** Explain prompt-cache breaks: which tool, system section or message changed when a call re-sent cached context. */
+  cacheDiagnostics: boolean;
   /** Context-size guard: past softTokens, suggest /compact or /new, or compact at the next safe point. */
   contextBudget: ContextBudget;
   /** Opt-in: an unchanged repeated `read` of the same range returns a short stub instead of the content. */
@@ -57,7 +59,7 @@ export function isMaxSubagents(value: unknown): value is MaxSubagents {
 
 export const SETTINGS_FILE = "pi-jar-settings.json";
 export function defaultVisualSettings(footer: FooterSettings = DEFAULT_FOOTER_SETTINGS): JarVisualSettings {
-  return { version: 1, accent: "follow", animations: true, ui: true, composer: true, mascot: true, suggestions: true, goalRounds: 8, maxSubagents: 2, advisor: true, advisorGates: false, contextDiet: false, contextBudget: { ...DEFAULT_CONTEXT_BUDGET }, readCache: false, icons: "unicode", footer: { ...footer } };
+  return { version: 1, accent: "follow", animations: true, ui: true, composer: true, mascot: true, suggestions: true, goalRounds: 8, maxSubagents: 2, advisor: true, advisorGates: false, contextDiet: false, cacheDiagnostics: true, contextBudget: { ...DEFAULT_CONTEXT_BUDGET }, readCache: false, icons: "unicode", footer: { ...footer } };
 }
 
 /** Legacy footer choices are imported only while the new file is absent. Never modify the old file. */
@@ -91,6 +93,7 @@ export function loadVisualSettings(directory: string): JarVisualSettings {
     advisor: typeof value.advisor === "boolean" ? value.advisor : fallback.advisor,
     advisorGates: typeof value.advisorGates === "boolean" ? value.advisorGates : fallback.advisorGates,
     contextDiet: typeof value.contextDiet === "boolean" ? value.contextDiet : fallback.contextDiet,
+    cacheDiagnostics: typeof value.cacheDiagnostics === "boolean" ? value.cacheDiagnostics : fallback.cacheDiagnostics,
     contextBudget: parseContextBudget(value.contextBudget) ?? fallback.contextBudget,
     readCache: typeof value.readCache === "boolean" ? value.readCache : fallback.readCache,
     icons: ICON_SETS.some((set) => set === value.icons) ? value.icons as IconSet : fallback.icons,