@ian-pascoe/pi-advisor 0.5.0 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 `@ian-pascoe/pi-advisor` reviews a Pi agent's completed work and surfaces concise, attributed findings for material problems and worthwhile low-risk cleanup.
 
-Requires Node `>=22.19.0` and Pi `>=0.99.0`.
+Requires Node `>=22.19.0` and Pi `>=1.1.0`.
 
 ## Install
 
@@ -26,13 +26,17 @@ Advisor is **disabled by default**. Configuration precedence is session, trusted
 /advisor set includeSubagents true
 /advisor set model "provider/model-id"
 /advisor set maxFindingsPerReview 4
+/advisor set maxNitsPerRequest 3
+/advisor set seedBudgetTokens 40000
+/advisor set reviewEvery "request"
+/advisor set maxSessionTokens 150000
 ```
 
 Argument autocomplete suggests command names, settings keys, and valid trailing scope flags.
 
 In the interactive TUI, `/advisor` alone opens a settings menu built from Pi's native settings list, like `/settings`. A Scope row chooses where edits are written (session, trusted project, or global), and each setting shows its effective value with any non-default source. `enabled`, `includeSubagents`, and `thinkingLevel` cycle the selected scope's own value in place (`inherit → on → off`, or through each thinking level); while that scope has none, the row shows what it inherits, such as `inherit (on · project)`, and a value overridden by a higher-precedence scope is marked. Model, tools, numbers, and the prompt open submenus, and the prompt uses Pi's own editor component. Every edit is validated and applied immediately; a paused Advisor shows its reason and a Resume row. Closing the menu records one status entry listing the changes it applied, or nothing if none were. Without the TUI, `/advisor` records the status entry instead.
 
-`/advisor status` and the other subcommands each record a status entry in the transcript. Collapsed, it shows state, model, backlog, usage and cost, unavailable tools, and the last error; expanded, it lists every setting with its source and each watched Child Agent. A mutating command's entry starts with the changes it applied. While enabled, the footer shows `advisor` when idle, `advisor: reviewing`/`consulting` with any `backlog N`, or `advisor: paused`, plus Child Agents that are reviewing or paused. `advisor_ask` renders its question and a Markdown answer preview, and Child Agent findings carry a `↳ <agentId>` label.
+`/advisor status` and the other subcommands each record a status entry in the transcript. Collapsed, it shows state, model, backlog, usage and cost, the number of Reviews with their running cost and the last Review's cost, unavailable tools, and the last error; expanded, it lists every setting with its source and each watched Child Agent. A mutating command's entry starts with the changes it applied. While enabled, the footer shows `● advisor on` when idle, `● advisor reviewing`/`consulting` with any `backlog N`, or `! advisor paused`, plus Child Agents that are reviewing or paused. Interventions and status entries use Pi's custom-message box with a bold `Advisor` label; an Intervention's severity is a coloured word (`nit`, `concern`, `blocker`), and Child Agent findings add the agent ID. `advisor_ask` renders as Pi's built-in tools do: a lowercase `advisor_ask` header with the question, a Markdown answer collapsed to ten lines with Pi's expand hint, and Pi's `Elapsed`/`Took` footer. Warnings and errors read `Advisor: ...`.
 
 Interventions render with their severity and Advisor attribution. Long Nits collapse until expanded; Concerns and Blockers always show in full.
 
@@ -46,22 +50,26 @@ The tool is absent while Advisor is disabled. A paused Advisor keeps it visible
 
 Consultation authorizes analysis and investigation, not implementation or other side effects. The configured Advisor Prompt remains authoritative. Tool Grants still expose each granted tool's full native interface, so exclude mutating tools when a prompt-level boundary is insufficient.
 
-`prompt` opens Pi's native editor and replaces the whole Advisor Prompt. `inherit` removes an override at the selected scope. Invalid keys and values are rejected. Lists, including `allowedTools`, replace the inherited list rather than merge. `catchUpThreshold` accepts any positive safe integer or `"off"`; `reviewTimeoutMs` accepts 1–2,147,483,647 milliseconds (the native timer range); `maxFindingsPerReview` accepts an integer from 1 through 32.
+`prompt` opens Pi's native editor and replaces the whole Advisor Prompt. `inherit` removes an override at the selected scope. Invalid keys and values are rejected. Lists, including `allowedTools`, replace the inherited list rather than merge. `catchUpThreshold` accepts any positive safe integer or `"off"`; `reviewTimeoutMs` accepts 1–2,147,483,647 milliseconds (the native timer range); `maxFindingsPerReview` accepts an integer from 1 through 32; `maxNitsPerRequest` accepts any non-negative safe integer, where `0` delivers no Nits; `seedBudgetTokens` and `maxSessionTokens` accept any positive safe integer or `"auto"`; `reviewEvery` accepts `"turn"`, `"request"`, or any positive safe integer number of turns.
 
 `advisor_ask` declares MCP-style `annotations` (read-only, non-destructive, idempotent, closed-world) that Pi reports through `pi.getAllTools()` for permission extensions; Pi does not send them to model providers. They describe the consultation itself, not the tools granted to the Advisor. The Advisor Session's internal `advisor_report` tool, which extensions inherited by that session can see, declares non-destructive, closed-world annotations and is not read-only, because it records the Review's findings.
 
 ## Defaults and access
 
-| Option                         | Default                      |
-| ------------------------------ | ---------------------------- |
-| Enabled                        | `false`                      |
-| Watched sessions               | Main only                    |
-| Allowed tools                  | `read`, `grep`, `find`, `ls` |
-| Catch-up threshold             | `3`                          |
-| Review deadline                | 120 seconds                  |
-| Investigative calls per Review | 8                            |
-| Findings per Review            | 4                            |
-| Automatic Corrective Turns     | 1 per request/task           |
+| Option                         | Default                                                        |
+| ------------------------------ | -------------------------------------------------------------- |
+| Enabled                        | `false`                                                        |
+| Watched sessions               | Main only                                                      |
+| Allowed tools                  | `read`, `grep`, `find`, `ls`                                   |
+| Catch-up threshold             | `3`                                                            |
+| Review deadline                | 120 seconds                                                    |
+| Investigative calls per Review | 8                                                              |
+| Findings per Review            | 4                                                              |
+| Nits per request               | 3                                                              |
+| Context Seed budget            | `auto` (¼ of the Advisor model's context window, at most 100k) |
+| Review Cadence (`reviewEvery`) | `turn`                                                         |
+| Advisor Session size           | `auto` (½ of the Advisor model's context window, at most 200k) |
+| Automatic Corrective Turns     | 1 per request/task                                             |
 
 A Tool Grant names tools; it does not sandbox their full native interfaces. Explicitly granting `bash`, for example, permits any command, including mutations. Unavailable names are ignored and reported; status reflects the Advisor Session at that moment, so a granted tool that registers later, such as an MCP tool after its server connects, is reported until it does. Advisor never autogrants missing tools. Granted tools with `codemode` or `deferred` exposure (such as tools from Pi's built-in MCP) are not declared to the Advisor model; they stay callable from granted `codemode` scripts, and a granted `tool_search` can declare them, as in the observed agent. Granting `codemode` lets the Advisor script its other granted tools; it inherits the observed `codemode.mode`, so under `"only"` the Advisor calls `advisor_report` from a script. It also inherits whether scripts get the `models` API: Minimal Subagents Child Agents have none, so neither do their Advisors.
 
@@ -69,16 +77,44 @@ The Advisor inherits each observed agent's model and thinking level independentl
 
 ## Sessions and Context Management
 
-Each watched agent has a private, persisted native Advisor Session with fresh, session-bound extension resources. Reviews reuse that session until context or configuration changes require rebuilding. Pi's enabled `builtin:<name>` extensions are recreated in their observed order: `codemode`, `tool-search`, and `mcp` from Pi's exported factories, and `llama.cpp` from the installed Pi package's shipped extension file, retaining their metadata and fresh provider state. Built-ins disabled with `-builtin:<name>` stay absent. This is a built-in recreation recipe, not general inline-factory support; a host factory registered under a built-in name is rejected. Other opaque inline or custom extension resources that cannot be safely recreated are reported as unsupported and pause the Advisor; they are not silently reused or omitted. The Advisor's session state remains separate from the observed agent's state.
+Each watched agent has a private, persisted native Advisor Session with fresh, session-bound extension resources. Reviews reuse that session until context or configuration changes require rebuilding. Pi's enabled `builtin:<name>` extensions are recreated in their observed order: `codemode`, `tool-search`, and `mcp` from Pi's exported factories, and `llama.cpp` from the installed Pi package's shipped extension file, retaining their metadata and fresh provider state. Built-ins disabled with `-builtin:<name>` stay absent. This is a built-in recreation recipe, not general inline-factory support; a host factory registered under a built-in name is rejected. Other opaque inline or custom extension resources that cannot be safely recreated are reported as unsupported and pause the Advisor; they are not silently reused or omitted. The Advisor's session state remains separate from the observed agent's state. The Advisor's own system prompt carries no skills catalogue, so skill changes in the Observed Agent's session no longer churn it.
+
+Reviews and Consultations receive Review Evidence: what the observed model saw, not Pi's stored records. Messages keep their role, text, reasoning text, tool calls with arguments, tool-result text with error status, and image attachments; replay signatures, display-only tool `details`, provider metadata, and native IDs are omitted. Each tool call and its result share a short reference. Redacted reasoning and responses that errored, aborted, or hit the output limit are marked. The first Review or Consultation in an Advisor Session carries a Context Seed: the observed system prompt and each observed tool's name and one-line summary (not its full description or schema), plus the current conversation. Later Reviews and Consultations add only new messages.
+
+The current conversation is already bounded by the observed session's native compaction, but can still be very large, so the Context Seed is fitted to `seedBudgetTokens`: Pi's chars/4 estimate of the seed JSON the Advisor receives, plus Pi's per-image estimate. The first Review or Consultation always sees the Observed Setup; the original request; and the newest turn with the request that prompted it. The original request is the first message the user typed into the current context; after compaction it is the compaction summary, which records the earlier goal, plus the first message the user typed after it. Compaction summaries, delivered Advisor findings, other extension messages, and `!` command output are never taken for a request. The rest of the budget holds the newest turns that fit, oldest first. A turn is one message, or an assistant message with all of its tool results, so a tool call is never separated from its result. Text that alone exceeds the remaining budget is shortened with a marker. When messages are omitted or shortened, the seed lists the positions, in the observed context, of the messages it keeps and names the observed session file, so granted tools such as `read` or `grep` can inspect the full messages. The Advisor's own `context_history` covers only its private session. Later Reviews still add only messages newer than the seed; omitted messages are not sent later. `auto`, the default, uses a quarter of the Advisor model's context window (Pi's 128k fallback when a model declares none), at most 100k tokens: the seed is resent with every inference of the first Review and stays in the Advisor Session, so the rest is left for the Advisor Prompt, investigation, and later Reviews, and an `auto` seed always fits within half the `auto` `maxSessionTokens`. Models with windows above 400k tokens get the 100k ceiling rather than a quarter of their window. An explicit budget is capped at the Advisor model's context window.
 
 Context Management is optional. If loaded and its tools are granted, `context_notes`, `context_history`, and `context_rollover` operate on the Advisor's private context. If any of those three tools is excluded, the Advisor pauses before reviewing. There is no autogrant or hook bypass.
 
+## Review Cadence and cost
+
+Each Review is a new prompt in the same private Advisor Session, so its input is the whole Advisor Session so far: mostly prompt-cache reads, but billed on every Review. Two settings bound that cost.
+
+`reviewEvery` sets the Review Cadence: when Reviews run. Whatever the cadence, a Review covers every turn not yet reviewed, and only messages the Advisor has not yet seen are added. When those messages would exceed `seedBudgetTokens`, as a coarse cadence can gather or, under any cadence, a single very large turn, Advisor instead rebuilds the Advisor Session from a Context Seed within that budget. Like any rebuild, this withdraws earlier Concerns and Blockers that were queued to steer the observed agent but not yet consumed; findings already in its context stay.
+
+- `"turn"`, the default, reviews after every turn (one model response and its tool batch). Findings arrive soonest, and Concerns and Blockers can steer the agent while it still runs; cost grows with the number of turns.
+- `N` reviews after every `N` turns and again when the request completes, for any turns left over.
+- `"request"` reviews once when the request completes: the agent's run has ended, including its steering and follow-up messages, and Pi will not retry it automatically. This is the cheapest cadence, but findings arrive only after the agent has finished, so a Concern waits for the next continuation and a Blocker can only prompt a Corrective Turn.
+
+Under `N` or `"request"`, a turn whose tool call failed still starts a Review at once. A Catch-up Wait waits only for a running Review: turns waiting for the next cadence point count toward the backlog but never start a Catch-up Wait themselves, and the wait ends when that Review finishes. Headless final drains and Minimal Subagents task completion review whatever turns remain, waiting up to one Review deadline (`reviewTimeoutMs`, 120 seconds by default) rather than the 30-second Catch-up Wait ceiling, so a Review covering a whole request can finish. A Review already running when the observed session compacts still finishes and delivers its findings; the next Review rebuilds the Advisor Session from the compacted context.
+
+`maxSessionTokens` bounds the Advisor Session itself. After a Review, when the Advisor Session's context exceeds the cap, Advisor compacts it with Pi's native compaction (`compact()`, as `/compact` does), which summarizes older Advisor history with the Advisor model and keeps Pi's `compaction.keepRecentTokens` of recent history; a cap below `keepRecentTokens` acts as `keepRecentTokens`. The summary is asked to keep the observed request, findings already reported, open concerns, and what the Advisor verified. Observed evidence continues incrementally afterwards, and delivered and deferred findings are kept by Advisor itself. Compaction is one extra Advisor model call that re-reads the history it summarizes without cache hits, counted in that Review's cost. It runs after the Review's findings are delivered, under its own deadline of `reviewTimeoutMs`. If it fails or times out, for example because an inherited extension cancels it, Advisor does not pause: it discards the Advisor Session, and the next Review starts a new one from a Context Seed. Pi declining because the whole Advisor Session is recent history it keeps is not a failure. `auto` takes half the Advisor model's context window (Pi's 128k fallback when a model declares none), at most 200k tokens: room for an `auto` Context Seed plus as much again for later Reviews, so a full seed alone never forces compaction, and far below Pi's own threshold (the window less `compaction.reserveTokens`), where each Review would re-read almost a full window. The 200k ceiling exists because the per-Review cost follows the Advisor Session's size, not the model's window: with a 1M-token window, half the window is about 500k tokens, where an Advisor Session was measured costing at least $0.12 for each Review that found nothing, and $0.20–0.34 for typical ones, from cache reads alone, more than the observed agent cost over the same period. At 200k, the same prices bound that floor at about 40% of it (about $0.05). A lower cap makes each Review cheaper at the price of more frequent compaction; a higher one, up to the window, compacts less often. When Context Management is loaded in the Advisor Session, its Rollover manages that context instead, and `maxSessionTokens` is not applied.
+
+`/advisor status` shows the cost of the last Review, including any compaction it ran, and the running total of Reviews since the session started or Advisor was reloaded, from the native usage the Advisor Session records. Reviews that failed or were cancelled after prompting the Advisor count, since they were billed; Consultations do not. Its `tokens` and `cost` instead cover the current Advisor Session, including Consultations, and restart when that session is rebuilt. Unknown cost, such as for a model without prices, is shown as unknown; a Review that reported no usage on a priced model costs $0. Expanded, status also shows each Child Agent's Review cost.
+
 ## Scheduling and safety
 
-Reviews combine completed observed turns (one model response plus its tool batches) and use bounded catch-up waits of at most 30 seconds. Each Review has its own deadline, investigative-call budget, and configurable finding limit. One terminating report returns findings in severity order. Formatting-equivalent findings retain their highest severity within a Review; later escalation from Nit to Concern to Blocker remains deliverable. Distinct Concerns are delivered together when eligible or retained together for re-evaluation during the three-turn cooldown.
+Reviews combine completed observed turns (one model response plus its tool batches), as often as `reviewEvery` allows, and use bounded catch-up waits of at most 30 seconds. Each Review has its own deadline, investigative-call budget, and configurable finding limit. One terminating report returns findings in severity order. Formatting-equivalent findings retain their highest severity within a Review; later escalation from Nit to Concern to Blocker remains deliverable. Distinct Concerns are delivered together when eligible or retained together for re-evaluation during the three-turn cooldown.
+
+## Finding quality
+
+Each finding must name a concrete defect in work the observed agent has already done and cite its evidence: the short `ref` that Review Evidence gives each tool call and its result, or a short verbatim quote. Advice about what to do, test, or say next belongs in a consultation (`advisor_ask`), not in an Intervention. The default Advisor Prompt asks for this, and `advisor_report` requires an `evidence` object with `refs`, a `quote`, or both on every finding, so a replaced Advisor Prompt keeps the requirement. Advisor drops a finding that cites no evidence, or cites a `ref` it never supplied to that Advisor Session, and tells the Advisor which findings it dropped; quotes are not checked against the evidence. A report in the older single-finding form cites no evidence, so its finding is dropped too. An `advisor_report` call that does not match the report schema, such as a finding without `evidence`, is rejected with the reason so the Advisor can correct it; after two rejected calls the Review ends without findings rather than retrying until its deadline, and Advisor is not paused. Delivered Interventions keep their evidence in the journaled message details; the observed agent sees only the severity and message.
+
+A Review judges the turns completed when it started. If the observed agent completes more turns before the Review's findings are delivered, those findings are superseded: they may already be fixed or explained, so none of them is delivered. Instead, the next Review receives them alongside the newer turns, re-validates them, and reports again only those that still apply; this adds no model call. Under `reviewEvery: "turn"` that Review is already due. Under `N` or `"request"` it waits for the next cadence point, at the latest the Review when the request completes, which normally has no newer turns to supersede it (unless a new request has already started). Findings are withheld this way at most once. If the agent also outruns a Review that was given withheld findings, all of that Review's Concerns and Blockers are delivered anyway, including ones it reports for the first time, since it judged them against newer turns, and all its Nits are dropped. This is a deliberate starvation guard: it is applied per Review, so it holds even when the re-validating Review rewords a finding or cites newer references. A withheld Concern that the next Review defers for the Concern cooldown keeps that mark. So findings are never held back for more than one extra Review, however fast turns arrive. Superseded findings still waiting when Advisor is disabled, reconfigured, resumed after a pause, or moved to another branch or session are dropped with the rest of its invalidated review state, and so are those whose re-validating Review does not finish within a headless or Child Agent final drain.
+
+`maxNitsPerRequest` (default 3) limits the Nits delivered per request; further Nits are dropped. Concerns and Blockers are never capped. A request runs from a user prompt (or a Minimal Subagents task) through its completion, including the Review at its completion and any Corrective Turn; the count restarts with the next request. Superseded Nits are kept for re-validation only while the request has room for them. `/advisor status` shows how many findings await re-validation and how many were dropped since the session started or Advisor was reloaded: Nits over the cap, findings with missing or unknown evidence, Nits from a re-validating Review that was superseded again, and Reviews ended by invalid reports. The Nit count follows the selected branch, so it survives a configuration change within a request.
 
 Nits are non-interrupting and enter context at the next natural step boundary without starting a Corrective Turn. Running work receives native steering for eligible Concerns and Blockers. A Blocker after normal interactive completion may receive a tracked corrective continuation within the configured budget; aborted, uncertain, deliberately interrupted, and headless-completed work is preserved without a hidden restart. Child corrections stay inside Minimal's owned operation. Headless root shutdown allows only a bounded final drain and never starts hidden corrective work.
 
-Status reports effective settings, sources, review or consultation state, backlog, usage/cost, and the last error. Unknown cost is shown as unknown, never zero. Review failure pauses Advisor while leaving the observed agent running; changing configuration, branch, or session identity invalidates stale in-flight work.
+Status reports effective settings, sources, review or consultation state, backlog, usage/cost of the current Advisor Session, Review cost, and the last error. Unknown cost is shown as unknown, never zero. Review failure pauses Advisor while leaving the observed agent running; changing configuration, branch, or session identity invalidates stale in-flight work.
 
 Advisor is privileged extension code. Review inherited extensions and granted tools before installing it in a session with access to local files, credentials, or mutating APIs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-advisor",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "description": "Background review and attributed corrective advice for Pi agent sessions.",
   "keywords": [
@@ -32,13 +32,13 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.3.1"
+    "@ian-pascoe/pi-utils": "^0.5.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.99.0",
-    "@earendil-works/pi-ai": ">=0.99.0",
-    "@earendil-works/pi-coding-agent": ">=0.99.0",
-    "@earendil-works/pi-tui": ">=0.99.0",
+    "@earendil-works/pi-agent-core": ">=1.1.0",
+    "@earendil-works/pi-ai": ">=1.1.0",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0",
     "typebox": "*"
   },
   "engines": {
@@ -53,7 +53,7 @@
     ]
   },
   "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   }
 }

package/skills/pi-advisor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pi-advisor
-description: Diagnose Pi Advisor when reviews or advisor_ask are missing, consultation fails, the Advisor is paused, settings are ineffective, backlog waits do not release, or corrective advice is not delivered safely.
+description: Diagnose Pi Advisor when reviews or advisor_ask are missing, consultation fails, the Advisor is paused, settings are ineffective, backlog waits do not release, corrective advice is not delivered safely, or Reviews cost too much.
 license: MIT
 disable-model-invocation: true
 ---
@@ -13,10 +13,14 @@ Use this sequence for a live Advisor problem:
 2. If the state is disabled, check the selected session override, trusted-project settings, and global settings in that order. Advisor defaults to disabled. Use `/advisor on`, `/advisor off`, `/advisor inherit`, or `/advisor set <key> <JSON>` at the intended scope; use `/advisor prompt` for the native prompt editor. Confirm the selected branch after resume, fork, or tree navigation.
 3. If the state is paused, read the reported capability, Review, or Consultation error. Correct the setting or unavailable runtime capability, then explicitly re-enable or reload as the diagnostic instructs. A pause leaves the observed agent running.
 4. If `advisor_ask` is missing, confirm Advisor is enabled; disabled Advisors intentionally hide it. A paused Advisor keeps the tool visible for its diagnostic. Under `codemode.mode: "only"` it stays active but undeclared, reachable only through `codemode` scripts. Consultations wait for the active Review, return plain advice, and leave Review Backlog accounting unchanged. User cancellation does not pause Advisor; runtime failures do.
-5. For missing reviews, inspect backlog and catch-up configuration. Backlog counts completed model responses with their tool batches, including work under review. `off` never waits; a positive threshold waits only while backlog is at least that threshold, and each wait is capped at 30 seconds. A Review has its own deadline, investigative-call limit, and `maxFindingsPerReview` limit of 1–32.
+5. For missing reviews, inspect backlog and catch-up configuration. Backlog counts completed model responses with their tool batches, including work under review. `off` never waits; a positive threshold waits only while backlog is at least that threshold, and each wait is capped at 30 seconds. A Review has its own deadline, investigative-call limit, and `maxFindingsPerReview` limit of 1–32. Check `reviewEvery`: under `"request"` a Review runs only when the request completes, and under `N` after every N turns and at completion; a turn with a failed tool call is reviewed at once. A Catch-up Wait waits only for a running Review, so turns waiting for their cadence never block the observed agent.
 6. If Context Management is loaded, verify that all three private tools—`context_notes`, `context_history`, and `context_rollover`—are explicitly granted. Any missing grant pauses Advisor before review. These tools operate on the Advisor Session's private Notes, History, and Checkpoints; they never grant access to the observed session. Confirm native settlement and checkpoint completion rather than treating an early response or `agent_end` report as completion.
 7. For tool failures, compare the effective `allowedTools` list with the loaded registry. Missing names are reported and ignored; Advisor does not autogrant tools. Grant `codemode` explicitly for scripts. An inactive advice tool after extension binding pauses the Advisor. A Tool Grant covers the tool's full native interface and is not a filesystem or operation sandbox.
 8. For stale, duplicated, or unsafe advice, check branch/session identity and configuration-generation changes. Advisor Sessions are separate persisted native sessions with fresh extension resources. Unsupported opaque inline/custom resources pause rather than being reused. Nits use non-interrupting context delivery and never start Corrective Turns. Running Concerns and Blockers use Pi's native steering boundary; Blockers after normal interactive completion use only tracked, budgeted Corrective Turns. Deliberately interrupted, aborted, uncertain, and headless-completed work is preserved without restart. Child correction must finish inside Minimal's owned operation.
-9. On shutdown, allow only the bounded headless final drain. Verify that no hidden corrective turn starts after root completion and that native Advisor resources are aborted before disposal.
+   - If a finding never arrived, check `/advisor status` for findings awaiting re-validation: a Superseded Finding is withheld when the agent completed more turns before delivery, and the next Review reports it again only if it still applies. Findings are withheld at most once: if that Review is superseded too, its Concerns and Blockers are delivered and its Nits dropped. Status also counts Nits dropped over `maxNitsPerRequest`, findings dropped for citing no evidence or an unknown Tool-Call Reference (the Advisor Session's `advisor_report` result names them), Nits from a superseded re-validating Review, and Reviews ended after two invalid `advisor_report` calls; frequent invalid reports suggest an Advisor model that cannot follow the report schema.
+   - If findings are directives rather than defects, or lack evidence, check whether a replaced Advisor Prompt dropped the default's evidence and completed-work wording; `advisor_report` still requires evidence on every finding.
+9. If a finding seems to miss tool output or schemas, remember that Review Evidence carries tool-result text but not display-only `details`, and the Context Seed's Observed Setup lists observed tools by name and one-line summary only. Grant read tools or use `advisor_ask` when the Advisor must inspect more than the observed model received. If an early finding misses older history, check `seedBudgetTokens`: the Context Seed keeps the Observed Setup, the original request, the newest turn, and the newest turns that fit, lists the observed messages it keeps, and names the observed session file for the rest.
+10. If Advisor costs too much, compare the last Review's cost and the running total in `/advisor status` with the observed agent's cost. Each Review re-reads the whole Advisor Session: lower `maxSessionTokens` so Pi's native compaction keeps it smaller, or use a coarser `reviewEvery`, which delays findings. A compaction that fails or times out does not pause Advisor; the next Review instead starts a new Advisor Session from a Context Seed (`Current context seed.` in its prompt). Context Management's Rollover replaces this compaction where it is loaded.
+11. On shutdown, allow only the bounded headless final drain, which waits up to one `reviewTimeoutMs` Review deadline. Verify that no hidden corrective turn starts after root completion and that native Advisor resources are aborted before disposal.
 
 Finish when `/advisor status` shows the intended settings and the failing Review or Consultation now settles without error: a Consultation returns advice, or a Review produces an attributed finding or zero backlog. If a capability remains unsupported, report the exact diagnostic instead of bypassing native lifecycle or permission policy.

package/src/advisor-command.ts

@@ -1,64 +1,43 @@
+import {
+  completeSettingsCommandArguments,
+  parseSettingsCommand,
+  type SettingsCommand,
+} from "@ian-pascoe/pi-utils/settings-command";
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import {
   advisorOptionKey,
   advisorOptionKeys,
   parseAdvisorOptions,
   type AdvisorOptions,
+  type AdvisorSettingScope,
 } from "./advisor-settings.js";
 
 /** Native command completion values replace the entire argument prefix. */
 export function completeAdvisorCommandArguments(prefix: string): AutocompleteItem[] {
-  const candidates = ["on", "off", "status", "prompt", "inherit", "set"];
-  const keyPrefix = /^((?:set|inherit)\s+)\S*$/.exec(prefix)?.[1];
-  if (keyPrefix) candidates.push(...advisorOptionKeys.map((key) => `${keyPrefix}${key}`));
-  const scopePrefix = /^(.*\s+)(--\S*)?$/s.exec(prefix)?.[1];
-  if (scopePrefix) {
-    try {
-      const command = parseAdvisorCommand(scopePrefix);
-      if ("scope" in command && command.scope === "session")
-        candidates.push(`${scopePrefix}--global`, `${scopePrefix}--project`);
-    } catch {
-      // Incomplete commands and JSON values cannot accept a scope yet.
-    }
-  }
-  return candidates
-    .filter((value) => value.startsWith(prefix))
-    .map((value) => ({ value, label: value }));
+  return completeSettingsCommandArguments(prefix, {
+    words: ["on", "off", "status", "prompt", "inherit", "set"],
+    optionKeys: advisorOptionKeys,
+    parse: parseAdvisorCommand,
+  });
 }
 
 const usage =
   "Usage: /advisor [on|off|status|prompt|inherit [key]|set <key> <JSON>] [--global|--project]; /advisor alone opens settings";
 
+/** One parsed `/advisor` command. */
+export type AdvisorCommand = SettingsCommand<
+  AdvisorOptions,
+  keyof AdvisorOptions,
+  { action: "prompt"; scope: AdvisorSettingScope }
+>;
+
 /** Parse one configuration change; validated patches cannot invent option keys. */
-export function parseAdvisorCommand(input: string) {
-  const flag = /\s+--(global|project)$/.exec(input.trim());
-  const scope =
-    flag?.[1] === "global"
-      ? ("global" as const)
-      : flag?.[1] === "project"
-        ? ("project" as const)
-        : ("session" as const);
-  const text = flag ? input.trim().slice(0, flag.index) : input.trim();
-  if (text === "" || text === "status") {
-    if (flag) throw new Error(usage);
-    return text === "" ? { action: "menu" as const } : { action: "status" as const };
-  }
-  if (text === "prompt") return { action: "prompt" as const, scope };
-  if (text === "on" || text === "off") {
-    return {
-      action: "set" as const,
-      scope,
-      key: "enabled" as const,
-      patch: { enabled: text === "on" },
-    };
-  }
-  const inherit = /^inherit(?:\s+(\S+))?$/.exec(text);
-  if (inherit) {
-    return { action: "inherit" as const, scope, key: advisorOptionKey(inherit[1] ?? "enabled") };
-  }
-  const set = /^set\s+(\S+)\s+([\s\S]+)$/.exec(text);
-  if (!set?.[1] || !set[2]) throw new Error(usage);
-  const key = advisorOptionKey(set[1]);
-  const patch: AdvisorOptions = parseAdvisorOptions({ [key]: JSON.parse(set[2]) }, scope);
-  return { action: "set" as const, scope, key, patch };
+export function parseAdvisorCommand(input: string): AdvisorCommand {
+  return parseSettingsCommand(input, {
+    usage,
+    optionKey: advisorOptionKey,
+    parseOptions: parseAdvisorOptions,
+    toggle: (enabled) => ({ key: "enabled", patch: { enabled } }),
+    parseExtra: (text, scope) => (text === "prompt" ? { action: "prompt", scope } : undefined),
+  });
 }

package/src/advisor-contract.ts

@@ -8,16 +8,82 @@ export const advisorSeveritySchema = Type.Union([
 ]);
 export type AdvisorSeverity = Static<typeof advisorSeveritySchema>;
 
-/** One reported finding; also the journaled details of an Intervention message. */
-export const advisorFindingSchema = Type.Object(
+/** What a finding cites from the Review Evidence it was judged against. */
+export const advisorEvidenceSchema = Type.Object(
   {
-    severity: advisorSeveritySchema,
-    message: Type.String({ minLength: 1, maxLength: 4000 }),
+    refs: Type.Optional(
+      Type.Array(Type.String({ minLength: 1, maxLength: 64 }), {
+        maxItems: 8,
+        description:
+          "Tool-Call References (the `ref` of a tool call or its result in the supplied evidence) that show the defect",
+      }),
+    ),
+    quote: Type.Optional(
+      Type.String({
+        minLength: 1,
+        maxLength: 1000,
+        description: "A short verbatim quote from the supplied evidence that shows the defect",
+      }),
+    ),
   },
   { additionalProperties: false },
 );
+export type AdvisorEvidence = Static<typeof advisorEvidenceSchema>;
+
+const findingFields = {
+  severity: advisorSeveritySchema,
+  message: Type.String({ minLength: 1, maxLength: 4000 }),
+};
+
+/**
+ * One finding; also the journaled details of an Intervention message. `evidence` is absent from
+ * Interventions recorded before findings cited evidence, and from legacy single-finding reports.
+ */
+export const advisorFindingSchema = Type.Object(
+  { ...findingFields, evidence: Type.Optional(advisorEvidenceSchema) },
+  { additionalProperties: false },
+);
 export type AdvisorFinding = Static<typeof advisorFindingSchema>;
 
+const knownCost = Type.Union([Type.Number(), Type.Null()]);
+/**
+ * Native usage cost of Reviews since the Advisor was loaded, across Advisor Session rebuilds:
+ * the number of Reviews, the last one's cost, and their total. A cost is null when unknown;
+ * the total stays null once any Review's cost was unknown.
+ */
+export const advisorReviewCostSchema = Type.Object({
+  reviews: Type.Number(),
+  last: knownCost,
+  total: knownCost,
+});
+export type AdvisorReviewCost = Static<typeof advisorReviewCostSchema>;
+
+/** A finding as `advisor_report` accepts it: every finding cites its evidence. */
+export const advisorReportFindingSchema = Type.Object(
+  {
+    ...findingFields,
+    evidence: Type.Object(advisorEvidenceSchema.properties, {
+      additionalProperties: false,
+      description:
+        "Evidence for a concrete defect in completed work: at least one Tool-Call Reference or a verbatim quote",
+    }),
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * Findings an Advisor dropped since it started, by reason: Nits over `maxNitsPerRequest`,
+ * findings citing no or unknown evidence, Nits of a re-validating Review that was superseded
+ * again, and Reviews ended without findings by invalid reports.
+ */
+export const advisorDroppedFindingsSchema = Type.Object({
+  overNitCap: Type.Number(),
+  unsupported: Type.Number(),
+  superseded: Type.Number(),
+  invalidReviews: Type.Number(),
+});
+export type AdvisorDroppedFindings = Static<typeof advisorDroppedFindingsSchema>;
+
 /** Observer lifecycle state reported by its `status`. */
 export const advisorObserverStateSchema = Type.Union([
   Type.Literal("disabled"),

package/src/advisor-evidence.ts

@@ -0,0 +1,157 @@
+import type { Context, Tool } from "@earendil-works/pi-ai";
+import {
+  combineEvidence,
+  evidenceItemsCost,
+  fitEvidence,
+  projectEvidenceItem,
+  shortenEvidence,
+  type Evidence,
+  type EvidenceItem,
+} from "@ian-pascoe/pi-utils/evidence";
+
+export {
+  evidenceRefs,
+  evidenceTokens,
+  messageOrigins,
+  projectEvidence,
+  toolCallRef,
+  type Evidence,
+  type EvidenceBlock,
+  type EvidenceMessage,
+} from "@ian-pascoe/pi-utils/evidence";
+
+/** Marks text shortened to fit the Context Seed budget. */
+const omissionMarker = (omitted: number) =>
+  `[… ${omitted} characters omitted from the Context Seed]`;
+
+/** Observed Setup: the observed system prompt and tool summaries that open a Context Seed. */
+export interface ObservedSetup {
+  systemPrompt: string | undefined;
+  tools: { name: string; summary: string }[];
+}
+
+const summaryLimit = 160;
+
+/** First sentence of a tool description's first line, bounded for the Observed Setup. */
+function toolSummary(description: string): string {
+  const line = description.trim().split("\n", 1)[0]?.trim() ?? "";
+  const sentence = /^(.+?[.!?])(?:\s|$)/.exec(line)?.[1] ?? line;
+  return sentence.length > summaryLimit
+    ? `${sentence.slice(0, summaryLimit - 1).trimEnd()}…`
+    : sentence;
+}
+
+export function projectObservedSetup(
+  context: Pick<Context, "systemPrompt" | "tools">,
+): ObservedSetup {
+  return {
+    systemPrompt: context.systemPrompt,
+    tools: (context.tools ?? []).map((tool: Tool) => ({
+      name: tool.name,
+      summary: toolSummary(tool.description),
+    })),
+  };
+}
+
+/** A Context Seed: the Observed Setup and the observed messages that fit its token budget. */
+export interface ContextSeed extends Evidence {
+  observedSetup: ObservedSetup;
+  /** Zero-based positions of the kept observed messages, ascending. */
+  kept: number[];
+  /** Long texts shortened, with a marker, so the newest messages fit. */
+  shortened: number;
+}
+
+/**
+ * Fit a Context Seed to a token budget, measured as Pi's chars/4 estimate of the seed JSON with
+ * Pi's per-image estimate. Always kept: the Observed Setup; the original request (the first
+ * user request, or after compaction the summary, which carries the earlier goal, and the first
+ * request after it); and the newest turn with the request that prompted it, shortened if they
+ * alone exceed the budget. The rest takes the newest turns that fit, shortening only the oldest
+ * one included. A turn (an assistant message with its tool results) is never split.
+ */
+export function selectContextSeed(
+  context: Pick<Context, "systemPrompt" | "tools" | "messages">,
+  options: { budgetTokens: number; origins?: readonly string[] },
+): ContextSeed {
+  const { messages } = context;
+  const observedSetup = projectObservedSetup(context);
+  const projected = messages.map((message): EvidenceItem[] => {
+    const item = projectEvidenceItem(message);
+    return item ? [item] : [];
+  });
+  // Fall back to the converted role only when no converted user message has a known origin.
+  const origins = options.origins?.some(
+    (origin, index) => messages[index]?.role === "user" && origin !== "unknown",
+  )
+    ? options.origins
+    : undefined;
+  const isRequest = (index: number) =>
+    origins ? origins[index] === "user" : messages[index]?.role === "user";
+  // Units: a message, with any tool results that follow it.
+  const starts = messages.flatMap((message, index) =>
+    index === 0 || message.role !== "toolResult" ? [index] : [],
+  );
+  const units = starts.map((start, index) => ({
+    start,
+    end: starts[index + 1] ?? messages.length,
+  }));
+  const unitAt = (position: number) => units.findLastIndex((unit) => unit.start <= position);
+  const content = (unit: number) => {
+    const { start, end } = units[unit] ?? { start: 0, end: 0 };
+    return projected.slice(start, end).flat();
+  };
+  const summary = options.origins?.indexOf("compactionSummary") ?? -1;
+  const request = messages.findIndex((_message, index) => index > summary && isRequest(index));
+  const newest = units.length - 1;
+  const prompt = messages.findLastIndex(
+    (_message, index) => index <= (units[newest]?.start ?? -1) && isRequest(index),
+  );
+  const anchors = new Set([summary, request].filter((index) => index >= 0).map(unitAt));
+  const recent = new Set([prompt, messages.length - 1].filter((index) => index >= 0).map(unitAt));
+  for (const unit of anchors) recent.delete(unit);
+
+  const chosen = new Map<number, EvidenceItem[]>();
+  let remaining =
+    options.budgetTokens - Math.ceil(JSON.stringify({ observedSetup, messages: [] }).length / 4);
+  const anchorItems = [...anchors].flatMap(content);
+  const recentItems = [...recent].flatMap(content);
+  // Shorten the newest turn first, then the original request too, so both always appear.
+  const required =
+    fitEvidence(recentItems, remaining - evidenceItemsCost(anchorItems), omissionMarker)?.concat(
+      anchorItems,
+    ) ??
+    fitEvidence([...recentItems, ...anchorItems], remaining, omissionMarker) ??
+    shortenEvidence([...recentItems, ...anchorItems], 0, omissionMarker);
+  remaining -= evidenceItemsCost(required);
+  const shortenedRequired = new Map(
+    [...recentItems, ...anchorItems].map((item, index) => [item, required[index]] as const),
+  );
+  for (const unit of [...anchors, ...recent])
+    chosen.set(
+      unit,
+      content(unit).map((item) => shortenedRequired.get(item) ?? item),
+    );
+  for (let unit = newest; unit >= 0; unit--) {
+    if (chosen.has(unit)) continue;
+    const items = fitEvidence(content(unit), remaining, omissionMarker);
+    if (!items) break;
+    chosen.set(unit, items);
+    remaining -= evidenceItemsCost(items);
+    if (items.some((item, index) => item !== content(unit)[index])) break;
+  }
+
+  const ordered = [...chosen.keys()].toSorted((left, right) => left - right);
+  const kept = ordered.flatMap((unit) => {
+    const { start, end } = units[unit] ?? { start: 0, end: 0 };
+    return Array.from({ length: end - start }, (_value, offset) => start + offset);
+  });
+  const items = ordered.flatMap((unit) => chosen.get(unit) ?? []);
+  const original = ordered.flatMap(content);
+  return {
+    observedSetup,
+    ...combineEvidence(items),
+    kept,
+    shortened: items.filter((item, index) => item.message !== original[index]?.message).length,
+  };
+}