pi-jar 0.2.2 → 0.2.4

package/README.md

@@ -19,13 +19,13 @@ The showcase is captured from a real pi-jar terminal session: the torch-style `
 | **Plan mode** | Read-only exploration; the agent must write a structured plan file and submit it. You review it in a split view (headings on the left, section on the right) and approve, compact-and-approve, refine or stop. |
 | **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` for risky decisions or when stuck, `/advisor [focus]` asks on demand, and 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. |
+| **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; `/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. |
 | **Background shells** | `jar_shell` runs dev servers, watchers and long tests in the background; watch/exit events wake an idle agent or reach it at the next safe turn boundary. Completion status appears immediately in the UI even during model reasoning. Running shells get a footer row; click it (or <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>A</kbd>) to tail or kill them. |
-| **Subagents** | The main agent becomes a moderator over a configurable retained pool (2, 4, 6, 8 or 16; default 4). `jar_delegate` starts `scout`, `fork` or sandboxed `worktree` agents and returns immediately, so the main agent can keep responding to user steering; Pi RPC event-bus messages deliver initial and resumed turn completions without polling. `jar_subagent` peeks, steers, asks BTW questions, pauses, resumes and stops them. Workers can exchange bounded structured Q/A through `jar_discuss`; worktree changes stay isolated until stop, then safely enter `/diff`. |
+| **Subagents** | The main agent becomes a moderator over a configurable retained pool (2, 4, 6, 8 or 16; default 2, or 4 in an opt-in Swarm profile). It delegates only when there are at least two independent chunks that each need about ten or more tool calls. `jar_delegate` starts `scout`, `fork` or sandboxed `worktree` agents and returns immediately, so the main agent can keep responding to user steering; Pi RPC event-bus messages deliver initial and resumed turn completions without polling. `jar_subagent` peeks, steers, asks BTW questions, pauses, resumes and stops them. Workers can exchange bounded structured Q/A through `jar_discuss`; worktree changes reach `/diff` only when the moderator stops a worker. |
 | **Sessions & history** | Recent sessions (with their goal and plan) on the welcome card, one click from resuming; <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>H</kbd> searches earlier prompts; pasted images show as chips under the composer. |
 | **Footer & themes** | Responsive footer (model, effort, session, cwd, context, RAM, cost, quota, goal, roles, branch, live subagents and shells) with unicode, [Nerd Font](https://www.nerdfonts.com) or ascii icons, and seven dark themes. |
 
@@ -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. |
@@ -73,7 +74,7 @@ Pi only delivers mouse events in its **fullscreen** TUI mode. In regular mode th
 | `/jar ask [question]` | Answer a question in a dialog and insert the answer into the editor. |
 | `/jar accent [preset]` · `/jar footer` · `/jar icons [unicode\|nerd\|ascii]` | Switch a loaded accent theme; toggle footer fields; pick the icon set. |
 | `/jar composer on\|off` · `/jar animations on\|off` · `/jar ui on\|off` | Toggle the composer, motion, or all pi-jar UI. |
-| `/jar quota on\|off` | Session-only, read-only quota lookups for supported OAuth providers. Lookups start on session boundaries (startup, prompts, model changes), never from a render: at most one per provider every 5 minutes, and failures back off up to 30 minutes. |
+| `/jar quota on\|off` | Session-only, read-only quota lookups for supported OAuth providers. Lookups start on session boundaries (startup, prompts, model changes) and when `/usage` opens, never from a render: at most one per provider every 5 minutes, and failures back off up to 30 minutes. |
 | `/jar hub` | Open an installed task or subagent manager command. |
 | `/jar demo` · `/jar reset` | Labeled sample roles in the footer / back to live data. |
 
@@ -225,7 +226,7 @@ The advisor is a second model (the `advisor` role; the current model if unassign
 
 - **`jar_advisor({ question?, draft? })`** — starts a background second opinion and immediately returns a request ID. Use `action: "status"`, `"get"`, bounded `"wait"` (at most 30 seconds), or `"cancel"` with that ID; a pending receipt is **not** reviewed approval. Advice arrives at a safe model boundary or wakes an idle agent, with immediate UI completion feedback. Requests have a 60-second deadline and bounded context; `/advisor` and automatic stuck-work gates are non-blocking too. Get completed advice before consequential decisions. Available in plan mode too.
 - **`/advisor [focus]`** — ask on demand; the answer is added to the conversation (visible) for the agent's next turn.
-- **Gates** — when the agent makes the same tool call three times within its last eight calls, the call is blocked and the advisor's review is returned instead; after three failing tool results in a row, the advice is steered into the running turn. At most two automatic consultations per prompt.
+- **Gates** (opt-in, off by default) — when the agent makes the same tool call four times within its last eight calls, the call is blocked and the advisor reviews in the background. Re-reads, `jar_shell` `output`/`wait`/`peek` polls and test-runner reruns (`npm test`, `node --test`, `pytest`, `go test`, …) never count as a loop. After three failing tool results in a row, the advice is steered into the running turn. At most two automatic consultations per prompt.
 - Settings → Pi toggles the advisor and the gates. Advisor calls are counted in `/usage`. The footer and welcome show it as a working teammate while it thinks.
 
 ### Role fallback models
@@ -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`).
+- **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
 
@@ -266,14 +294,16 @@ This is a pi-jar enhancement: [pi-advisor](https://github.com/philipbrembeck/pi-
   Use `parent` with `append` to add a genuinely new subtask to active work; `start`, `done`, `open`, `edit`, `list`, `add` and `delete` remain available.
 - **`jar_ask`** — structured questions: numbered options with descriptions, single or multi-select, *Type your own answer* (multi-line, paste-friendly) and *Chat about this* to discuss before choosing.
 - **`/diff`** — review what the agent (and its editing subagents) changed since the first edit to each file: files with `+/−` counts on the left, a full-path header and numbered, colored diff on the right. Changed lines get a colored rail and tinted background, replaced lines highlight the changed words, code is syntax-highlighted for known languages, and collapsed regions are labeled `┄ N unchanged lines ┄`. `/` filters files; `t` switches unified and aligned side-by-side views (unified below 70 columns), `←`/`→` (or `[`/`]`) change the context from 0 lines to the whole file, `w` wraps long lines, and `n`/`p`, `Home`/`End` navigate. Large changes offer summary or explicit windowed review (`v`), with clearly labeled coarse fallback and existing safety limits—not arbitrary-file streaming. See [diff review](docs/DIFF-REVIEW.md). `a` accept (keep, stop tracking), `r` then `y` revert (restore the original, or remove a file it created), `A`/`R` for all. The footer shows `± N files · /diff` while anything is unreviewed; each file counts once no matter who edited it. Only `edit`/`write` changes inside the project are tracked; shell-made changes are not.
-- **Context diet (opt-in)** — `/jar settings` → **Pi** → **Context diet (prior-turn reasoning)**. Saved independently per profile; OFF by default. Removes eligible thinking blocks from completed earlier user turns only in outgoing context, never from stored history. Current reasoning signatures, user requests, tool arguments/results, and workflow state remain intact; ambiguous tool chains are left unchanged. Opaque signature character counts are diagnostics, not token savings. Existing SoL-Pi observation packing remains responsible for tool-result projection.
-- **`jar_shell`** — `start` (optional `name`, `watch` regex, `notify`, task/service `purpose`), `list`, `peek`, bounded `wait`, `output`, `kill`. ANSI-stripped logs have per-job caps and a 4 MiB aggregate budget; surfaced finished jobs compact to a 32 KiB tail. Live jobs retain useful tails and are never killed to reclaim logs. Watch/exit notifications are compact and coalesced; reads acknowledge observed events. Active model responses cannot be interrupted by a completion event: the UI previews status without consuming it, and model delivery waits for a safe boundary. When no useful work remains, use bounded `wait` for the relevant finite jobs rather than waiting for an automatic wake-up. Each running shell gets a footer row and an activity view (`/jar shells`) with `x` kill and `f` follow. All shells stop when the session ends.
-- **`jar_delegate`** — spawns retained, session-scoped subagents up to **Max subagents** in `/jar settings` (2, 4, 6, 8 or 16; default 4). Idle, paused and hibernated agents count toward this pool; over-cap batches are rejected. `scout` is fresh/read-only, `fork` inherits conversation read-only, and `worktree` forks context into a path-guarded Git worktree. Settled retained agents close their Pi process after 30 seconds of quiet while keeping their private session and workspace; `resume`/`ask` relaunch that same session. Launch returns before startup or the first turn completes, including legacy one-shot `write: true` mode.
+- **Context diet (opt-in)** — `/jar settings` → **Pi** → **Context diet (prior-turn reasoning)**. Saved independently per profile; OFF by default. Removes eligible thinking blocks from completed earlier user turns only in outgoing context, never from stored history. In the same completed turn, a `read` result that a later read of the same range or a successful edit/write of the same file superseded becomes a one-line stub; each turn is rewritten only once, when it completes, so later prefix-cache hits are kept. Current reasoning signatures, user requests, tool call/result pairing and workflow state remain intact; ambiguous tool chains are left unchanged. Opaque signature character counts are diagnostics, not token savings.
+- **Context budget** — `/jar settings` → **Pi** → **Context budget** (`off`, `suggest` default, `compact`) and **Context budget limit** (80k–200k, default 120k). When the last call's prompt (input plus cache) passes the limit, the footer's context metric turns amber and `suggest` shows one notice per crossing (`/compact`, or `/new` for the next task). `compact` compacts once at the next safe point: right after a `jar_todo` item completes while work remains (the run stops after that turn, compacts, then continues with a hidden note), or when the run settles; it never cuts a tool chain. The footer shows the average cost per call over the last ten calls next to the total. A prompt after a finished task list in a large context suggests `/new`; a prompt after more than five idle minutes with over 100k context warns that the provider cache has probably expired. No keep-warm requests are sent.
+- **Read hygiene** — a whole-file `read` (no offset/limit) of a file over 50 KB returns its first 400 lines with a note on how to continue. Opt-in **Repeated-read stub** (`/jar settings` → **Pi**): re-reading the same range of an unchanged file returns `[unchanged since read #N (312 lines); pass force: true to re-read]`. Any edit/write of the file, a changed file revision, compaction, branch navigation or a new session clears it.
+- **`jar_shell`** — `start` (optional `name`, `watch` regex, `notify`, task/service `purpose`, `waitMs` up to 30 s), `list`, `peek`, bounded `wait`, `output`, `kill`. Use plain `bash` for finite commands expected to finish in about two minutes; `jar_shell` is for services, watchers and long jobs. `start` with `waitMs` returns the exit code and output tail in one call when the job finishes in time (acknowledged, so no later notification), otherwise the output so far; Esc cancels only the wait. `output` returns only lines new since your last read (with counts of trimmed or skipped lines); `all: true` repeats the trailing window. ANSI-stripped logs have per-job caps and a 4 MiB aggregate budget; surfaced finished jobs compact to a 32 KiB tail. Live jobs retain useful tails and are never killed to reclaim logs. Watch/exit notifications are compact and coalesced; reads acknowledge observed events. Active model responses cannot be interrupted by a completion event: the UI previews status without consuming it, and model delivery waits for a safe boundary. When no useful work remains, use bounded `wait` for the relevant finite jobs rather than waiting for an automatic wake-up. Each running shell gets a footer row and an activity view (`/jar shells`) with `x` kill and `f` follow. All shells stop when the session ends.
+- **`jar_delegate`** — spawns retained, session-scoped subagents up to **Max subagents** in `/jar settings` (2, 4, 6, 8 or 16; default 2). Idle, paused and hibernated agents count toward this pool; over-cap batches are rejected. `/profiles` → **Create Swarm profile** copies the current settings with a pool of 4. `scout` is fresh/read-only, `fork` inherits conversation read-only, and `worktree` forks context into a path-guarded Git worktree. Settled retained agents close their Pi process after 30 seconds of quiet while keeping their private session and workspace; `resume`/`ask` relaunch that same session. Launch returns before startup or the first turn completes, including legacy one-shot `write: true` mode. Turn and stop events carry a summary of at most 400 characters plus changed files; all events pending at one boundary arrive as one `pi-jar.subagent` message, together with the moderator's unread discussion mail. `/roles` warns when the `scout` or `reviewer` role would run on the main model while a cheaper model is available.
 - **`jar_subagent`** — `peek` reports progress, including the workspace path and changed files for recovery records; `steer` redirects a running worker; `resume` relaunches an idle/paused/hibernated agent; `report` returns an agent's latest full report (a synchronous `jar_delegate` result shares a 16k-character report budget across its runs and points here when it truncates). `ask`, `pause` and `stop` return accepted receipts immediately; answers and final handoffs arrive as `pi-jar.subagent` events. `stop` reconciles safe worktree changes; conflicts remain private and can be retried with `stop` after resolving parent drift. `discard` removes an unresolved recovery worktree without applying it. At most four active/recovery worktrees are admitted; resolve or discard one before starting another. Session shutdown reports paths of any preserved worktrees. Controls do not poll the child.
 - **Subagent capabilities** — each task can set `tools` or `inheritTools: true`; known-tool mode filters and child guards remain in force. See [tool capabilities](docs/SUBAGENT-TOOLS.md).
 - **Worktree finalization** — edits do not touch the parent merely because a worker settles or hibernates. On `jar_subagent stop`, pi-jar checks parent drift and reviewability, applies safe changes and adds them to `/diff`; conflicts remain isolated for retry or explicit discard. Failed worktree transcripts are compacted independently of finished history. Process closure is awaited before finalization, and failed multi-file application rolls back rather than leaving a partial result.
-- **`jar_democracy`** — **exceptional only**, for a persistent super-complex issue with several evidence-backed options after at least two distinct failed approaches. The moderator opens 2–8 options, resumes relevant idle/paused/hibernated fresh-context read-only scouts or spawns new scouts within the pool, and collects one private ballot per voter. A strict majority of invited voters wins; ties, plurality or missing/invalid ballots require user choice. Voting never implements its recommendation. A round has a 10-minute deadline and bounded rationales.
-- **`jar_discuss`** — session-local, parent-owned discussion broker over authenticated local IPC; no shared paper, lock or polling. `ask`/`answer` return stable IDs without echoing your text. `list` reads only relevant unread questions/answers and advances your cursor; `thread` (or `list` with `questionId`) reads one thread; `pending` shows counts without message bodies. `since: "d0"` rereads relevant mail. At most 128 messages, 1600 characters each and 128 KiB are retained; unread/unanswered questions block new posts instead of being silently lost. Messages do not wake idle agents; the next natural turn gets an unread notice.
+- **`jar_council`** — **exceptional only**, for a persistent super-complex issue with several evidence-backed options after at least two distinct failed approaches. The moderator opens 2–8 options, resumes relevant idle/paused/hibernated fresh-context read-only scouts or spawns new scouts within the pool, and collects one private ballot per voter. A strict majority of invited voters wins; ties, plurality or missing/invalid ballots require user choice. Voting never implements its recommendation. A round has a 10-minute deadline and bounded rationales.
+- **`jar_discuss`** — session-local, parent-owned discussion broker over authenticated local IPC; no shared paper, lock or polling. `ask`/`answer` return stable IDs without echoing your text. `list` reads only relevant unread questions/answers and advances your cursor; `thread` (or `list` with `questionId`) reads one thread; `pending` shows counts without message bodies. `since: "d0"` rereads relevant mail. At most 128 messages, 1600 characters each and 128 KiB are retained; unread/unanswered questions block new posts instead of being silently lost. Messages do not wake idle agents. Unread mail (never your own messages) arrives once, inline, at your next natural turn start, so no `list` call is needed; the moderator's also rides along with subagent events.
 - **Activity view** — one split view (<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>A</kbd>, `/jar activity`, or a click on a footer row) for subagents, background shells and other extensions' teammates: list on the left, live details on the right (auto-follows; scroll up to pause, `f` to follow again). For a subagent the details show its task, its own checklist with subtasks, and a transcript like omp's: each tool call and message is one collapsed line that expands on demand (`Tab` into it, `↑↓`, `Enter`, or click) to show arguments and output, while streaming text shows live. `s` opens a steering input: type a message and press `Enter` to redirect the running subagent. `x` stops just that one. Finished runs stay listed for review.
 - **`/jar history`** — separate, read-only timeline of the active branch (paging, search, expandable details). Pi's native transcript is untouched.
 - Pi's built-in read/shell/edit/write tool cards render compactly: collapsed, each is one padded, state-colored card with its call line and a one-line summary (edit included), and partially streamed arguments never flicker to a fallback; the full output or diff stays one click or <kbd>Ctrl</kbd>+<kbd>O</kbd> away. Every requested frame re-renders the whole transcript, so background sources (subagent streams, shell changes, context and cost updates) share one adaptive repaint budget: at most every 250 ms below 300 branch entries, 500 ms below 800, 1 s below 2,000, and only on visible state changes beyond that; a frame Pi draws on its own satisfies pending updates. User actions and state changes (a subagent or shell starting, settling or failing) still repaint at once. The open activity view repaints live updates every 100 ms, slowing to 500 ms in very large sessions. Context usage is cached: session start, tree navigation, compaction, model changes, renames and the end of a run refresh it at once, while message ends recompute it at most every 750 ms, widening up to 5 s when the measured computation is slow so sampling stays near a 1% duty cycle. `/jar perf` shows the counters. The sliding bar some terminals show in the tab while the agent works is Pi's own `OSC 9;4` progress (`terminal.showTerminalProgress` in Pi settings), not pi-jar.
@@ -284,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 4), advisor, advisor gates.
+- **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.
 
@@ -298,6 +328,8 @@ Other extensions can publish teammate roles and quota windows through Pi's publi
 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
@@ -318,7 +350,7 @@ pi-jar/
 │   ├── async-process.ts    cancellable async subprocess runner with deadlines and tree cleanup
 │   ├── discussion.ts     session-local discussion broker and tool
 │   ├── discussion-hub.ts bounded in-memory discussion mailboxes
-│   ├── democracy.ts      exceptional scout ballots, strict majority and user tie-break
+│   ├── council.ts        exceptional scout ballots, strict majority and user tie-break
 │   ├── activity-view.ts  subagent/shell details view
 │   ├── perf.ts           long-session render budget, context sampling and /jar perf
 │   ├── icons.ts          unicode / nerd / ascii glyph sets

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

@@ -34,6 +34,29 @@ A synchronous `jar_delegate` result shares a 16k-character report budget across
 
 The footer's per-tick registry listener reads `DelegateRegistry.stateSignature()` straight from the map instead of `records()` (a second sweep, a sort and two arrays per 50 ms tick).
 
+## Session cost reduction
+
+Baseline: a 309-call, $6.34 session (`node scripts/session-cost.mjs 01a101ba-…`): 60% of cost was cache reads, average context 125k, 138 calls above 125k context costing $3.87; 109 reads (12 of one file, 7 of a `/tmp` plan), 65 `jar_shell` calls (33 start, 22 output, 8 wait), 19 subagent events (36 KB). Cost scales with calls × context, so every change cuts calls, context per call, or the fixed prompt.
+
+| Change | Where | Effect |
+| --- | --- | --- |
+| Context budget (`suggest` by default at 120k; opt-in `compact` at a safe point) and average cost per call in the footer | `src/context-budget.ts` | Long sessions are compacted or split before every call re-sends 200k+ |
+| Topic-switch and cold-cache hints | `src/context-budget.ts` | `/new` for unrelated work; `/compact` before re-sending a large expired context |
+| `bash` for finite commands; `jar_shell start` `waitMs`; incremental `output` | `src/shells.ts` | Short jobs take one call instead of start → output → wait, and repeated reads don't resend old output |
+| 400-line cap on whole reads of files over 50 KB; opt-in repeated-read stub; diet stubs superseded reads | `src/compact-tools.ts`, `src/context-diet.ts` | Smaller tool results and fewer duplicate reads in the context |
+| Pool default 2 (opt-in Swarm profile: 4); delegate only for ≥2 chunks of ≥10 tool calls | `src/settings.ts`, `src/delegate.ts`, `src/profile-ui.ts` | Fewer moderation round-trips |
+| 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
 
 | Item | Why |

package/docs/INTEGRATIONS.md

@@ -39,7 +39,7 @@ ctx.ui.setStatus("pi-jar.quota.openai-codex", JSON.stringify({
 - `used` is a percentage from 0 to 100. Either window may be omitted, and each can carry an optional `resetsAt` (epoch milliseconds).
 - `expiresAt` is required and may be at most five minutes ahead. A valid published status always wins.
 - `/jar quota on` (the default each session) lets pi-jar resolve the current Anthropic or OpenAI Codex OAuth credentials through Pi's model registry and make a **read-only** request to the provider's quota endpoint when nothing is published.
-- Requests have a 5 s timeout; successful results are cached for 5 minutes, while consecutive failures back off for 5, 10, 20, then 30 minutes. `/jar quota off` cancels pending requests and clears the cache. Renders only read cached values.
+- Requests have a 5 s timeout; successful results are cached for 5 minutes, while consecutive failures back off for 5, 10, 20, then 30 minutes and `/usage` shows the failure reason until the next retry. `/jar quota off` cancels pending requests and clears the cache. Renders only read cached values.
 - These provider endpoints are not stable public APIs.
 
 ## Session entries owned by pi-jar
@@ -58,18 +58,35 @@ Hidden context messages (`pi-jar.plan-context`, `pi-jar.plan-reminder`, `pi-jar.
 | --- | --- |
 | `jar_todo` | branch-aware checklist: `todos` full-list writes (`content`, `status` pending/in_progress/completed, `activeForm`), plus `list`, `add`, `start`, `done`, `open`, `edit`, `delete` |
 | `jar_ask` | structured questions answered in the TUI |
-| `jar_plan_submit` | submit a plan file for review (plan mode only) |
-| `jar_goal` | `get`, `complete` (with evidence, audit phase only), `block` |
-| `jar_suggest` | one next-prompt suggestion shown as composer ghost text |
-| `jar_shell` | background shells: `start` (`command`, `name`, `watch`, `notify`), `list`, `output`, `kill` |
-| `jar_delegate` | up to four parallel subagents (`tasks: [{task, name?, role?}]`, `write?`) |
+| `jar_plan_submit` | submit a plan file for review; active only in plan mode |
+| `jar_goal` | `get`, `complete` (with evidence, audit phase only), `block`; active only while a goal runs |
+| `jar_suggest` | one next-prompt suggestion shown as composer ghost text; active only when suggestions are enabled |
+| `jar_shell` | background shells: `start` (`command`, `name`, `watch`, `notify`, `purpose`, `waitMs`), `list`, `peek`, `wait`, `output` (new lines; `all`), `kill` |
+| `jar_delegate` | retained subagents within the configured pool (`tasks: [{task, name?, role?, mode?, tools?, inheritTools?}]`) |
+| `jar_subagent` | moderator control: `peek`, `report`, `steer`, `ask`, `pause`, `resume`, `stop`, `discard` |
+| `jar_council` | exceptional scout vote with strict majority; never implements |
+| `jar_discuss` | parent-brokered Q/A between moderator and subagents |
 | `jar_advisor` | second opinion from the `advisor` role (`question?`, `draft?`) |
 
+Mode-specific tools are deactivated when their mode is off, so their schema and rules are not sent with every request.
+
 `jar_shell` events arrive as a visible `pi-jar.shell` custom message that triggers (or queues) an agent turn; subagent turn ends and `jar_subagent` control completions arrive as one coalesced, visible `pi-jar.subagent` message at the moderator's next turn boundary, or as a wake-up when it is idle. `jar_delegate` runs child processes with `PI_JAR_CHILD=1`, which keeps pi-jar in the child from registering `jar_delegate` again, and publishes each running subagent through the role contract above as `pi-jar.role.delegate-<batch>-<n>`. The advisor publishes `pi-jar.role.advisor` while it is consulting, and its `/advisor` and gate answers arrive as visible `pi-jar.advisor` custom messages.
 
 ## 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)
+
+Every model call re-sends the whole context, so cost grows with session length far more than with the work done (see [EFFICIENCY_PLAN.md](./EFFICIENCY_PLAN.md#session-cost-reduction)). pi-jar never edits these files; apply them yourself if they fit:
+
+- **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.
 
 ## Working signals and other managers
 

package/docs/SUBAGENT-TOOLS.md

@@ -18,7 +18,7 @@ Subagents use Pi's standard `--tools` allowlist. Each `jar_delegate` task can cu
 - `worktree` accepts known path-guarded file tools and named web tools. Shell and arbitrary extension tools are rejected. `multi_file_edit` is included in defaults only when active in the parent; each effective edit target, default path and recognized alternate path field is validated, including traversal and existing symlink escapes.
 - Named web capabilities are `web_enable`, `web_search`, `fetch_content`, `get_search_content` and `source_check`. Newly enabled tools must still be in the child's original capability list.
 - These are tool-call restrictions, not an OS sandbox. Extensions execute trusted code; named web tools can access external services, and legacy direct-write mode is not workspace-confined.
-- `jar_delegate`, `jar_subagent`, and `jar_democracy` are always removed from inherited tools and rejected in explicit lists. A child cannot recursively spawn more subagents.
+- `jar_delegate`, `jar_subagent`, and `jar_council` are always removed from inherited tools and rejected in explicit lists. A child cannot recursively spawn more subagents.
 - Tool capabilities are per task; a batch can mix modes and allowlists. A fork still inherits the parent's conversation context, independently of its tool list.
 
 Retained scout/fork/worktree children hibernate after 30 seconds idle: their Pi process exits, but the private child session and worktree remain for `jar_subagent resume` or `ask`. Hibernated records count against Max subagents. Unresolved worktree recovery records do not occupy a pool slot, but at most four active/recovery worktrees are admitted. `jar_subagent stop` retries reconciliation; `discard` explicitly removes an unresolved recovery workspace without applying it. On session shutdown pi-jar reports paths for worktrees it preserves on disk, including still-active worktrees that might contain edits.

package/docs/WORKFLOWS.md

@@ -151,9 +151,9 @@ watch matches  or  process exits  →  pi-jar.shell message  →  agent wakes (o
 - Progress (current tool, streaming text, tools used, turns, cost) stays in the activity view. Retained `idle` and `paused` agents remain visible in the footer/activity fleet; the newest eight ordinary retired reports remain for review, while unresolved private workspaces remain recoverable until explicit finalization/session cleanup. `s` in the activity view still steers a working subagent and `x` stops the selected agent through the same registry.
 - The deprecated `write: true` mode remains a one-shot shared-workspace compatibility path. New delegated implementation should use `mode: "worktree"`.
 
-### Exceptional agentic democracy
+### Exceptional agent council
 
-`jar_democracy` is **not** a default decomposition or decision tool. The moderator must supply `complexity: "super-complex"`, a concrete complexity justification, the persistent issue, at least two distinct failed approaches with evidence, and 2–8 uniquely identified options with tradeoffs. These gates are runtime-validated in addition to prompt guidance; the moderator is responsible for truthful evidence.
+`jar_council` is **not** a default decomposition or decision tool. The moderator must supply `complexity: "super-complex"`, a concrete complexity justification, the persistent issue, at least two distinct failed approaches with evidence, and 2–8 uniquely identified options with tradeoffs. These gates are runtime-validated in addition to prompt guidance; the moderator is responsible for truthful evidence.
 
 - Nominate relevant idle/paused **scouts** with `agents`, and set the total electorate with `voters` (default 4, or 2 at a cap of 2; always bounded by the configured cap). Forks, writable workers, busy agents and duplicate nominations are rejected. Reuse preserves context; prefer fresh scouts if discussion history could bias a ballot.
 - Unfilled seats spawn fresh read-only scouts through the normal delegate controller. The same session-wide capacity applies; the moderator must explicitly stop unneeded agents if there is no room. Voting never silently kills existing workers. Scouts spawned for the round are retired once it ends, so they never keep holding pool slots; nominated scouts stay retained.

package/extensions/index.ts

@@ -5,7 +5,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { Key, truncateToWidth, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { ACCENT_NAMES, loadedAccents, selectAccent } from "../src/accent.ts";
 import { registerAskTool } from "../src/ask-tool.ts";
-import { registerDemocracy } from "../src/democracy.ts";
+import { registerCouncil } from "../src/council.ts";
 import type { DelegateController } from "../src/delegate.ts";
 import { ComposerStyle } from "../src/composer.ts";
 import { installCompactBuiltinTools } from "../src/compact-tools.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";
@@ -37,6 +38,7 @@ import { manageTasks } from "../src/tasks-ui.ts";
 import { registerTaskTool, todoRow } from "../src/task-tool.ts";
 import { TASK_ENTRY, TodoStore, todoProgress, todoTotals } from "../src/tasks.ts";
 import { formatCost, sessionCost } from "../src/usage.ts";
+import { branchCalls, compactForBudget, CONTEXT_CONTINUATION, ContextBudgetGuard, providerCall, resumeAfterBudget } from "../src/context-budget.ts";
 import { WorkingState } from "../src/working.ts";
 import { ChangeTracker } from "../src/changes.ts";
 import { CHILD_ENV, DelegateRegistry, registerDelegate, SUBAGENT_MESSAGE, type DelegateRun } from "../src/delegate.ts";
@@ -61,8 +63,8 @@ const VERSION = (() => {
 })();
 /** Ignore the click Pi may synthesize right after a press we already acted on. */
 const WELCOME_CLICK_DEDUPE_MS = 400;
-/** Entries Pi writes when a fresh session starts; a branch holding only these has no transcript yet. */
-const SESSION_SETUP_ENTRIES = new Set(["thinking_level_change", "model_change", "session_info"]);
+/** Conversation content, unlike startup metadata or extension bookkeeping. */
+const SESSION_TRANSCRIPT_ENTRIES = new Set(["message", "custom_message", "compaction", "branch_summary"]);
 export default function piJar(pi: ExtensionAPI): void {
   const delegatedChild = process.env[CHILD_ENV] === "1";
   const delegatedWorktree = delegatedChild ? process.env[CHILD_WORKTREE_ENV] : undefined;
@@ -71,7 +73,7 @@ export default function piJar(pi: ExtensionAPI): void {
     // and handlers are disabled. Remove only parent automation, not task/user context.
     const parentAutomation = new Set([
       "pi-jar.goal-context", "pi-jar.goal-continuation",
-      "pi-jar.plan-context", "pi-jar.plan-reminder", "pi-jar.moderator-context", SUBAGENT_MESSAGE, DISCUSSION_NOTICE
+      "pi-jar.plan-context", "pi-jar.plan-reminder", "pi-jar.moderator-context", SUBAGENT_MESSAGE, DISCUSSION_NOTICE, CONTEXT_CONTINUATION
     ]);
     pi.on("context", (event) => {
       const messages = event.messages.filter((message) => !parentAutomation.has((message as { customType?: string }).customType ?? ""));
@@ -97,7 +99,7 @@ export default function piJar(pi: ExtensionAPI): void {
       pi.setActiveTools([...allowed].filter(name => available.has(name)));
     });
   }
-  installCompactBuiltinTools(pi);
+  installCompactBuiltinTools(pi, { readCache: () => visualSettings.readCache === true });
   let demo = false;
   let visualSettings = defaultVisualSettings();
   let profileStore: ProfileStore | undefined;
@@ -130,6 +132,15 @@ export default function piJar(pi: ExtensionAPI): void {
     if (footerTui && footerSettings.quota) quotaCache?.refresh(ctx.model?.provider, welcomeStatuses(), Date.now());
   };
   let cost = 0;
+  /**
+   * Context budget: footer chip, average cost per call, prompt hints and safe-point compaction.
+   * Delegated children never run it; the parent session owns the budget.
+   */
+  const contextGuard = new ContextBudgetGuard(() => delegatedChild ? { ...visualSettings.contextBudget, action: "off" } : visualSettings.contextBudget);
+  /** jar_todo calls in flight → completed count before each ran; a raised count marks a safe point. */
+  const todoCalls = new Map<string, number>();
+  /** Bumped per session: a compaction finishing after a session change resumes nothing. */
+  let budgetGeneration = 0;
   let welcomeInterval: ReturnType<typeof setInterval> | undefined;
   let welcomeFrame = 0;
   let welcomeDismiss = 0;
@@ -141,6 +152,8 @@ export default function piJar(pi: ExtensionAPI): void {
   let welcomeBranch = (): string | null => null;
   let refreshWelcome: (() => void) | undefined;
   let todos: TodoStore | undefined;
+  /** Leaf completion: jar_todo safe points, the stop decision and the topic hint. */
+  const todoCounts = () => todoTotals(todos?.all() ?? []);
   let goals: GoalStore | undefined;
   const composer = new ComposerStyle();
   let footerSettings = visualSettings.footer;
@@ -308,9 +321,14 @@ 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()) });
+    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[] => {
     try { return ctx.sessionManager.getEntries?.() ?? sessionBranch(ctx); } catch { return sessionBranch(ctx); }
@@ -358,8 +376,9 @@ export default function piJar(pi: ExtensionAPI): void {
     discussionEnv: (key, name) => discussion?.childEnv(key, name),
     discussionRetire: (key) => discussion?.retire(key),
     discussionUnread: (key) => discussion?.unreadFor(key) ?? 0,
+    discussionDigest: () => discussion?.digest(),
     getMaxSubagents: () => visualSettings.maxSubagents, onController: (controller) => { delegateController = controller; } });
-  if (!delegatedChild) registerDemocracy(pi, () => delegateController, () => visualSettings.maxSubagents);
+  if (!delegatedChild) registerCouncil(pi, () => delegateController, () => visualSettings.maxSubagents);
   const planMode = new PlanMode(pi, () => todos, modelRoles, updateTaskWidget);
   if (!delegatedChild) planMode.register();
   const goalLoop = new GoalLoop(pi, {
@@ -636,7 +655,7 @@ export default function piJar(pi: ExtensionAPI): void {
                 sessionName: footerSessionName,
                 cwd: ctx.cwd, settings: footerSettings, branch: footerData.getGitBranch(),
                 context: contextUsage?.label ?? "ctx ?", goal: goalLoop.progress(), chips: footerChips(), activity: footerActivity(now),
-                memory, cost: formatCost(cost), quota, roles, extras: live.extras,
+                memory, cost: formatCost(cost, contextGuard.perCall), overBudget: contextGuard.over, quota, roles, extras: live.extras,
                 demo, animations, frame, motionBudget: ctx.isIdle() ? 2 : 1
               }, width, ctx.ui.theme ?? theme);
               hits = layout.hits;
@@ -808,7 +827,17 @@ export default function piJar(pi: ExtensionAPI): void {
   const restoreGoal = (ctx: ExtensionContext, branch?: readonly unknown[]) => {
     try { goals?.restore(branch ?? sessionBranch(ctx)); } catch { goals?.restore([]); }
   };
-  pi.on("session_start", (_event, ctx) => {
+  /** Awaited by agent_settled (see compactForBudget), whose handler is the last pi-jar settle handler. */
+  const settleBudget = async (ctx: ExtensionContext) => {
+    const job = contextGuard.settle({ idle: ctx.isIdle(), blocked: planMode.isEnabled() });
+    if (!job) return;
+    const open = (todos?.all() ?? []).filter((item) => !item.done).map((item) => item.title);
+    if (!job.compact) { resumeAfterBudget(pi, ctx, open); return; }
+    const generation = budgetGeneration;
+    await compactForBudget(pi, ctx, { resume: job.resume, tokens: contextGuard.lastTokens, softTokens: visualSettings.contextBudget.softTokens, open },
+      () => generation === budgetGeneration);
+  };
+  pi.on("session_start", (event, ctx) => {
     sideUsage.clear();
     if (!profileStore) initializeProfiles(ctx);
     composer.setProfile(profileStore?.activeName ?? "Default");
@@ -859,6 +888,9 @@ export default function piJar(pi: ExtensionAPI): void {
       restoreTodos(ctx, branch);
       restoreGoal(ctx, branch);
     }
+    contextGuard.reset(branchCalls(branch, Date.now()));
+    todoCalls.clear();
+    budgetGeneration++;
     // Quota is enabled per session; no credentials or consent are persisted.
     quotaCache = new QuotaCache(
       (provider: QuotaProvider, signal) => fetchQuota(provider, (id) => ctx.modelRegistry.getProviderAuth(id), signal),
@@ -890,9 +922,12 @@ export default function piJar(pi: ExtensionAPI): void {
     }
     // Resumed sessions already have a transcript to paint. Rebuilding the animated welcome and
     // scanning other session files competes with that expensive initial render for no real benefit.
-    // A fresh session is not empty: Pi records the startup thinking level/model as entries.
-    const resumed = branch.some((entry) => !(typeof entry === "object" && entry !== null && "type" in entry
-      && typeof entry.type === "string" && SESSION_SETUP_ENTRIES.has(entry.type)));
+    // Fresh sessions can already contain model settings and other extensions' custom metadata.
+    // Those entries are not a transcript; only conversation content or an explicit resume/fork
+    // should suppress the welcome (including resumes of sessions containing only saved state).
+    const resumed = event.reason === "resume" || event.reason === "fork" || branch.some((entry) =>
+      typeof entry === "object" && entry !== null && "type" in entry
+      && typeof entry.type === "string" && SESSION_TRANSCRIPT_ENTRIES.has(entry.type));
     if (!delegatedChild && !resumed) showWelcome(ctx);
     if (discussion) {
       const current = discussion;
@@ -920,6 +955,11 @@ export default function piJar(pi: ExtensionAPI): void {
     }
     if (event.source !== "interactive") return;
     dismissWelcome(ctx);
+    // Hints read a finished list before this prompt acknowledges (hides) it.
+    if (!event.streamingBehavior) {
+      const hint = contextGuard.prompt(Date.now(), todoCounts());
+      if (hint) ctx.ui.notify(hint, "info");
+    }
     if (!todosAcknowledged && todos?.all().every((item) => item.done)) { todosAcknowledged = true; updateTaskWidget(ctx); }
   });
   pi.on("agent_start", (_event, ctx) => {
@@ -937,20 +977,46 @@ export default function piJar(pi: ExtensionAPI): void {
     if (event.message.role === "assistant") {
       working.reportOutputTokens(event.message.usage?.output ?? 0);
       addMessageCost(event.message);
+      // Each provider call moves the per-call average and the budget; a crossing turns the context chip amber.
+      const notice = contextGuard.call(providerCall(event.message, Date.now()));
+      if (notice) ctx.ui.notify(notice, "warning");
       applyWorking(ctx);
       repaint("cost", "background");
     }
   });
-  pi.on("tool_execution_start", (event, ctx) => { working.toolStart(event.toolCallId, event.toolName); applyWorking(ctx); });
-  pi.on("tool_execution_end", (event, ctx) => { working.toolEnd(event.toolCallId); applyWorking(ctx); });
+  pi.on("tool_execution_start", (event, ctx) => {
+    if (event.toolName === "jar_todo") todoCalls.set(event.toolCallId, todoCounts().done);
+    working.toolStart(event.toolCallId, event.toolName); applyWorking(ctx);
+  });
+  pi.on("tool_execution_end", (event, ctx) => {
+    const before = todoCalls.get(event.toolCallId);
+    if (before !== undefined) {
+      todoCalls.delete(event.toolCallId);
+      if (todoCounts().done > before) contextGuard.todoCompleted();
+    }
+    working.toolEnd(event.toolCallId); applyWorking(ctx);
+  });
   pi.on("ui_prompt_start", (_event, ctx) => { working.prompt(true); applyWorking(ctx); });
   pi.on("ui_prompt_end", (_event, ctx) => { working.prompt(false); applyWorking(ctx); });
   // A request may span several tool turns; keep its elapsed time and reported tokens until agent_end.
-  pi.on("turn_end", (_event, ctx) => { applyWorking(ctx); refreshQuota(ctx); });
+  pi.on("turn_end", (event, ctx) => {
+    applyWorking(ctx); refreshQuota(ctx);
+    todoCalls.clear();
+    // Safe point: every tool result of this turn is in. Stop before the next request; agent_settled compacts and resumes.
+    const stop = event.message?.role === "assistant" ? event.message.stopReason : undefined;
+    if (contextGuard.turnEnd({ open: () => { const { done, total } = todoCounts(); return total - done; },
+      interrupted: stop === "error" || stop === "aborted" || ctx.signal?.aborted === true || ctx.hasPendingMessages?.() === true,
+      blocked: planMode.isEnabled() })) ctx.abort();
+  });
   pi.on("agent_end", (_event, ctx) => { working.end(); applyWorking(ctx); sampleFooter(ctx); });
   pi.on("agent_before_settle", (event) => { if (event.outcome === "error") composer.flash("error"); });
   // Retries or compaction after agent_end may have added messages; otherwise the agent_end sample stands.
-  pi.on("agent_settled", (_event, ctx) => { working.end(); applyWorking(ctx); if (contextUsage?.dirty) sampleFooter(ctx); refreshQuota(ctx); });
+  pi.on("agent_settled", (_event, ctx) => {
+    working.end(); applyWorking(ctx); if (contextUsage?.dirty) sampleFooter(ctx); refreshQuota(ctx);
+    if (contextGuard.busy) return settleBudget(ctx);
+  });
+  // Pi's idle cache warming keeps the prompt cache alive; the cold-cache hint counts from its last refresh.
+  pi.on("cache_warming_decision", (event) => { if (event.action === "warm") contextGuard.warmed(Date.now()); });
   pi.on("session_tree", (_event, ctx) => {
     let branch: readonly unknown[] = [];
     try { branch = sessionBranch(ctx); } catch { /* keep empty */ }
@@ -959,6 +1025,7 @@ export default function piJar(pi: ExtensionAPI): void {
       restoreTodos(ctx, branch);
       restoreGoal(ctx, branch);
     }
+    contextGuard.reset(branchCalls(branch, Date.now()));
     updateCost(ctx);
     composer.refreshSession(ctx);
     sampleFooter(ctx);
@@ -968,6 +1035,7 @@ export default function piJar(pi: ExtensionAPI): void {
     try { branch = sessionBranch(ctx); } catch { /* keep empty */ }
     renders?.setEntries(branch.length);
     if (!delegatedChild) { restoreTodos(ctx, branch); restoreGoal(ctx, branch); }
+    contextGuard.compacted();
     updateCost(ctx);
     sampleFooter(ctx);
   });
@@ -990,6 +1058,9 @@ export default function piJar(pi: ExtensionAPI): void {
     renders = undefined;
     contextUsage?.dispose();
     contextUsage = undefined;
+    contextGuard.reset();
+    todoCalls.clear();
+    budgetGeneration++;
     todos = undefined;
     changes = undefined;
     changeCount = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jar",
-  "version": "0.2.2",
+  "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",