pi-jar 0.2.1 → 0.2.3

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. |
+| **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. |
 | **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. |
 
@@ -73,7 +73,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 +225,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
@@ -252,7 +252,7 @@ This is a pi-jar enhancement: [pi-advisor](https://github.com/philipbrembeck/pi-
 
 `/usage` and `/context` 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.
 
 ## Tasks, questions and history
@@ -266,17 +266,19 @@ 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.
-- **`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. `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.
+- **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. `/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.
+- 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.
 
 ## Settings
 
@@ -284,7 +286,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, 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 +300,7 @@ 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
 │   ├── flame.ts          pixel fire simulation
 │   ├── mascot.ts         Ember's moods and sprites
 │   ├── composer.ts       rounded composer, ghost text, mouse mapping
@@ -318,7 +321,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/EFFICIENCY_PLAN.md

@@ -0,0 +1,79 @@
+# Efficiency Plan
+
+## Status
+
+Triaged against the 0.2.1 codebase and partly implemented in v0.2.2. Most of the original proposal was either already shipped by the long-session work ([LONG_SESSION_PERFORMANCE_PLAN.md](./LONG_SESSION_PERFORMANCE_PLAN.md), 0.1.9–0.2.1) or costs more in complexity and risk than it saves. Only items with a measurable win and no behavior change were taken.
+
+## Goal
+
+Keep long sessions fast and cheap without losing stored history or changing what the model sees unless the user opted in.
+
+## Implemented in 0.2.2
+
+### Adaptive context sampling (was item 8)
+
+`ContextSampler` (`src/perf.ts`) now widens its mid-turn throttle from the measured cost of `getContextUsage()` instead of a fixed 750 ms: the window is `max(750 ms, 100 × median sample time)`, capped at 5 s. Mid-turn sampling therefore stays near a 1% duty cycle whatever the session size; cheap sessions keep the 750 ms cadence, and lifecycle boundaries (start, tree, compact, model, rename, settle) still refresh immediately. Measured cost is used rather than entry-count tiers because it is the quantity being bounded and needs no extra wiring. `/jar perf` shows the current window.
+
+### Profile pin lookup without a copy (part of item 9)
+
+`pinnedProfileId` walks the branch backwards in place instead of allocating `[...entries].reverse()`. `conversationStarted` already exits at the first user message, so it needed no change; neither runs per frame, so no incremental cache was added.
+
+### Cache-stable workflow prompts (follow-up)
+
+Plan and goal prompts used to be pruned to the newest copy on every call. Removing an earlier copy changes the conversation prefix, so each new turn (or goal round) re-sent the whole previous run uncached. `src/workflow-context.ts` now projects them so that every keep/drop decision depends only on earlier messages: identical plan/goal context is sent once, sent reminders and continuations stay in place, and leaving the mode drops them all once. It runs on Pi's message list before provider conversion, so it helps every provider that caches by prefix (Anthropic explicit breakpoints, OpenAI/DeepSeek/Gemini automatic prefix caching, Bedrock). Appending the context at the tail was rejected: pi-ai places the Anthropic cache breakpoint on the last message, so a moving tail would defeat the cache entirely.
+
+### Unset side roles are visible (follow-up)
+
+`askRole` notifies once per role when an unassigned role (advisor, commit, …) ran on the current main model, with the `/roles set` command to fix it. Behaviour is unchanged.
+
+### Bounded synchronous subagent results (follow-up)
+
+A synchronous `jar_delegate` result shares a 16k-character report budget across its runs (at least 2k each) instead of up to 12k per run. Truncated reports name `jar_subagent report <key>`, a new read-only action returning the full stored report. Event messages were already capped at 1.2k.
+
+### Cheaper subagent subscriber (follow-up)
+
+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 |
+| 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.
+
+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 |
+| --- | --- |
+| 5. Tier subagent events | Already tiered: tool `onUpdate` ≤ 1 s, footer status only on state change, key/state changes are `transition` and everything else `background` in `RenderScheduler` (250 ms–1 s by session size, transitions-only beyond), Activity view coalesces at 100–500 ms. The 50 ms stream tick only feeds that scheduler. |
+| 6. Footer snapshot | `renderFooterLayout` already memoizes on a key of width/theme/view; repaints between changes are cache hits. A versioned snapshot would need change notifications from every source for a microsecond saving. |
+| 7. Bounded advisor fingerprints | `callKey` already keeps a 200-char prefix plus a SHA-1 of large inputs, so the loop window never pins large payloads. Prefix/suffix-only hashing would let distinct writes collide and trigger false loop alerts. |
+
+## Deferred
+
+| Item | Why |
+| --- | --- |
+| 1. Single Context Projector | The four `context` hooks (child automation filter, diet, plan, goal) are each one `customType` scan that allocates only when something is stale — negligible next to request serialization. Merging them couples independent modules for no measurable gain. Revisit only if `/jar perf` shows context hooks in a profile. |
+| 2. Context Diet v2 (`stripper` model, `DietSnapshot`) | A model-written summary replaces exact history with a lossy one, adds a side call per compression and duplicates Pi's own compaction. Needs its own design (fidelity, resumability, cache-hit impact) before code. |
+| 3. Diet-aware delegation | Depends on item 2. Today `scout` already starts fresh and `fork` is an explicit mode; changing the defaults alters subagent results. |
+| 4. Strict utility roles | Side calls without a role use the current model by design (`askRole`); making them fail or go deterministic breaks advisor and commit messages for users without roles. Addressed instead by the one-time notice above. |
+| 10. Compact workflow history | Rewriting persisted session history is ruled out; provider context is handled by the cache-stable projection above. |
+
+## Success criteria
+
+- Mid-turn context sampling cost stays bounded (~1% duty cycle) as sessions grow; visible in `/jar perf`.
+- Plan/goal sessions keep prefix-cache hits across turns and rounds on every provider.
+- Stored session history is unchanged.

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,19 +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.
 
+## 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.
+- **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
 
 Working wording, icon colors and Ember's moods use only Pi's public agent, turn, UI-prompt and tool-execution events. "Thinking" means active generation, not access to hidden reasoning. Motion stops when animations are off, the run settles, the UI is disabled or the session shuts down.

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

@@ -68,7 +68,7 @@ State (`pi-jar.plan` entries, v2: `enabled`, `steps`, `text`, `path`, `title`) f
 - **Task gate:** with no open task, `write`/`edit` are blocked, and so are shell commands that are not on the read-only allowlist during the implement phase. During the audit, edits are blocked but verification commands are allowed.
 - **Roles per round:** implement rounds run on the `implement` role and the audit round on `advisor` (each only if assigned). The previous model and effort are restored when the run settles.
 - **Completion:** `jar_goal complete` requires the audit phase, no open tasks, and non-empty evidence. It ends the turn, records the evidence, and Ember shows `(★ᴗ★)`.
-- **Context hygiene:** only the newest goal context and continuation messages are kept in the prompt.
+- **Context hygiene:** repeated identical goal context is sent once, and goal prompts already sent are never removed from the middle of the prompt while the goal runs, so any provider's prefix cache (Anthropic, OpenAI, Gemini, Bedrock, …) keeps hitting. A completed goal drops them all.
 
 Goal events (`pi-jar.goal`, v2: `set`, `status`, `round`) are append-only session entries; v1 `set`/`clear` still replay.
 
@@ -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";
@@ -37,6 +37,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 +62,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 +72,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 +98,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 +131,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 +151,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;
@@ -231,7 +243,7 @@ export default function piJar(pi: ExtensionAPI): void {
   let subagentSignature = "";
   subagents.subscribe(() => {
     if (!footerTui) return;
-    const signature = subagents.records().map(({ key, run }) => `${key}:${run.state}`).join(" ");
+    const signature = subagents.stateSignature();
     repaint("subagents", signature === subagentSignature ? "background" : "transition");
     subagentSignature = signature;
   });
@@ -310,7 +322,9 @@ export default function piJar(pi: ExtensionAPI): void {
   registerContextDiet(pi, () => visualSettings.contextDiet === true);
   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()),
+    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 +372,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 +651,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 +823,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 +884,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 +918,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 +951,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 +973,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 +1021,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 +1031,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 +1054,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.1",
+  "version": "0.2.3",
   "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",