pi-warden 0.6.0 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-warden
 
-A second pair of eyes for [Pi](https://pi.dev) that makes the agent smarter instead of interrupting you. Before the agent runs a `bash`, `write`, or `edit` call (or a shell command through [context-mode](https://www.npmjs.com/package/context-mode)'s `ctx_execute`), pi-warden asks [Jev](https://typesafe.ai) two questions about it in ~250 ms: *would this destroy something that cannot be recovered?* and *is this what the user actually asked for?* The answers are probabilities, so `rm -rf dist` after "rebuild from scratch" sails through while `npm run db:reset` after "add a column" is held, and the agent is told why so it re-plans or asks you in chat. More guards watch the run: a **stuck-loop** detector, a **done-check** for completion claims that no test backed up, **slop** notes for stubs, filler, and padded replies, a check for **injected instructions** in tool output, and **tail compression** of large tool results. Every verdict lands on a status line above the editor; **click it** (fullscreen mode), press `ctrl+shift+w`, or run `/warden trace` to open a live trace sidebar with the scores, the reasons, and exactly what the agent was told. Built on [pi-typesafe](https://github.com/DevMortimer/pi-typesafe).
+A second pair of eyes for [Pi](https://pi.dev) that makes the agent smarter instead of interrupting you. Before the agent runs a `bash`, `write`, or `edit` call (or a shell command through [context-mode](https://www.npmjs.com/package/context-mode)'s `ctx_execute`), pi-warden asks [Jev](https://typesafe.ai) two questions about it in ~250 ms: *would this destroy something that cannot be recovered?* and *is this what the user actually asked for?* The answers are probabilities, so `rm -rf dist` after "rebuild from scratch" sails through while `npm run db:reset` after "add a column" is held, and the agent is told why so it re-plans or asks you in chat. More guards watch the run: a **stuck-loop** detector, a **runaway** guard that stops a reply repeating the same block over and over, **desktop notifications** when the agent needs you back, a **done-check** for completion claims that no test backed up, **slop** notes for stubs, filler, and padded replies, a check for **injected instructions** in tool output, and a **context saver** that replaces repeated tool results with a note, keeps exact failing tests and errors from large runner output, and points recalls at a search instead of a whole-file read. Every verdict lands on a status line above the editor; **click it** (fullscreen mode), press `ctrl+shift+w`, or run `/warden trace` to open a live trace sidebar with the scores, the reasons, and exactly what the agent was told. Built on [pi-typesafe](https://github.com/DevMortimer/pi-typesafe).
 
 ![Real verdicts from pi-warden: the same command gets a different verdict depending on what the user asked for](https://raw.githubusercontent.com/DevMortimer/pi-warden/main/docs/preview.png)
 
@@ -16,7 +16,7 @@ Three jobs, in order of maturity:
 | --- | --- | --- |
 | **Security** | Action holds and offline patterns protect risky operations. Tool-output checks flag possible injected instructions and credential shapes; insecure written code gets a targeted steer. Output notices are advisory, not a sandbox or a guarantee that an attack is contained. | built |
 | **Deslopify** | Written code is scored per symptom — stubs, restating comments, dead code, hedging — and the agent gets a nudge naming the symptom and its fix; repeats become a standing rule. Replies are scored for wordiness, assistant clichés, and jargon against an `audience` setting, and a trend across replies shapes the next one. | built |
-| **Context saving** | Jev selects a retention policy for large new tool results; code keeps deterministic excerpts and an exact local copy. Only tail compression is implemented. Cold-cache pruning and compaction integration remain planned. The system prompt and existing history are untouched. | tail MVP |
+| **Context saving** | Only the newest tool result is ever touched, so the prompt cache prefix stays byte-identical. An identical repeat of an earlier result becomes a short note (code only). For large new results Jev selects a retention policy and names the output format; code keeps exact lines through a format parser (failing tests, errors with file:line, changed files, package notices) or a deterministic head/diagnostic/tail excerpt, stores an exact copy, and tells the agent how to search it instead of re-reading it. Task-aware segment selection and compaction support remain planned. | built |
 
 ## Why a coding agent needs this
 
@@ -64,6 +64,10 @@ A `TYPESAFE_API_KEY` environment variable takes precedence over the stored key.
 
 Keeps the last 12 tool results for the current prompt. When the latest result failed and at least 3 failures have accumulated, it first checks for exact repeats offline (same call, same output with timings and addresses normalised). Otherwise one Jev request judges the sequence: `same_strategy` (Noul), `approach_change` (Score: identical / cosmetic / meaningfully different), `progress` (Noul). Same-strategy ≥ 0.7 counts as stuck: you get a notification, and with `nudge: true` (default) the agent gets a steer message asking for a new hypothesis or a blocker report. At most one Jev check per 3 results.
 
+### Runaway guard (`message_update`)
+
+A model that degenerates mid-reply repeats the same lines over and over — *"PR green. Merge. Executing:"* followed by the same command block, thirty times, and no tool call — until the token limit or you press Esc. Nothing else stops it, because no tool runs and no turn ends. pi-warden reads the stream as it arrives: per token it only appends to a buffer; every 256 characters it counts identical paragraphs (normalised, at least 24 characters) and checks whether the text ends with one unit repeated back to back. When a block repeats `repeats` times (4) in the reply, or `thinkingRepeats` times (10) in thinking, the run is aborted and you get an error-level notification. Code only: nothing is sent anywhere, so this works without TypeSafe consent. With `recover: true` (default) the agent then gets one follow-up turn, shown in the transcript, that names the repeat and asks for the one next step — call the tool, or answer in three sentences, or ask you; a second runaway for the same prompt is stopped and left for you. Calibrated on 43,000 local assistant messages: ordinary replies repeat a paragraph twice at most, thinking up to seven times while drafting code, and the one runaway repeated its block 28 times; the guard stopped only that one, at half its length.
+
 ### Done-check (`agent_end`)
 
 Tracks each run's evidence: code changes (`write`, `edit`) and check commands (`npm test`, `pytest`, `cargo test`, `tsc`, `eslint`, `go test`, `make test`, and similar, whether run through `bash` or `ctx_execute`) with pass/fail; context-mode's inline `Command exited with code N` counts as a failure. When a run ends with a normal assistant message after code changes and no passing check, one Jev request judges the message: `claims_done`, `claims_verified`, `verification_applies` (Noul), `outcome` (Choice: complete / partial / blocked / other). A completion claim ≥ 0.7 that is not a blocker or question, for a task where checks would mean something (≥ 0.5; prose and file housekeeping score ~0.05), is reported as unverified; a verification claim with no check run is reported as a false claim. With `nudge: true` (default) the agent receives one follow-up turn asking it to run the checks or say plainly that nothing was verified — once per user prompt.
@@ -88,17 +92,25 @@ Nudges from the stuck, done, slop, and prose guards are custom messages in the a
 
 If TypeSafe cannot answer (timeout after 5 s, outage, budget), an action-guard call is allowed with a warning (`failOpen: true`; set it to `false` to hold instead), and the other guards simply skip. When the per-session request budget is spent, pi-warden says so once and continues with offline checks. Consent in headless runs comes from `PI_WARDEN_ENABLED=1`; `PI_WARDEN_MODE` overrides the mode.
 
-### Tool-output security and tail compression
+### Desktop notifications
+
+You are rarely watching the terminal while the agent works, so the moments that need you reach the desktop: a held call the agent is about to ask you about, a confirm dialog waiting for an answer, and a runaway stop. macOS uses `osascript` (Notification Center, with a sound); Linux tries `notify-send`, `dunstify`, `gdbus`, `kdialog`, `zenity`, then `powershell.exe` for WSL; Windows shows a toast through PowerShell. The notifier is probed once per session; the text is the reason, never the command. Interactive sessions only — a headless run or a subagent has nobody to call — and one notification per `cooldownMs` (10 s), so sibling holds in one turn do not stack. `"notify": { "enabled": false }` turns it off; `"command": ["curl", "-d", "{body}", "https://ntfy.sh/your-topic"]` in the user file replaces the desktop tool with your own relay (no shell; `{title}`/`{body}` are replaced and also set as `PI_WARDEN_TITLE`/`PI_WARDEN_BODY`). A project file may switch notifications off but never names a command.
+
+### Tool-output security and context saving
 
 With consent, content-bearing tools (`read`, fetch/search tools and named MCP equivalents) are checked for instructions that redirect the assistant or request private data. Other tools, including shell/context-mode tools, are checked from 2048 characters. Jev receives a redacted 6000-character head/tail sample, so attacks in an unsampled middle can be missed. A score at or above `security.threshold` adds an untrusted-data notice around the text and a hidden steer. Local credential-shape checks work without network access and warn not to echo or commit possible secrets. Images, result details, error flags, and usage are preserved.
 
 Written code gets a `security_risk` question in the existing action request: hardcoded credentials, disabled TLS checks, unsafe shell/SQL interpolation, broad permissions, or bypassed verification. A threshold crossing warns and steers; it does not authorize an action or automatically block otherwise safe edits.
 
-For a single text block of at least `context.tailMinChars`, the same output request asks Jev to choose `all`, `errors_and_summary`, or `summary_only`. The full result stays when P(keep all) exceeds `1 - context.confidence` (default: keep when Jev gives `all` more than 0.2), when the probability is missing, or on any request error. Code—not Jev—keeps bounded diagnostic/head/tail excerpts. An exact copy is written to an owner-only temporary directory before replacement; the excerpt links to it. If storage fails, the original stays. Multiple text blocks keep their layout and are not compressed. Trace and widget show the actual bytes saved. No extra steer is persisted for compression alone.
+**Duplicates (code only).** A single-text-block result of at least `context.duplicateMinChars` (2000) whose content, ignoring colour codes and trailing whitespace, is identical to an earlier result of this session is replaced by a note naming the earlier tool and the size, plus a recall footer. The exact text is stored once; later copies reuse the file. No Jev request is made. Re-running the same failing test command is the typical case: nothing changed, and the note says so.
+
+**Retention and format (Jev decides, code applies).** For a single text block of at least `context.tailMinChars`, the same output request asks Jev to choose `all`, `errors_and_summary`, or `summary_only`, and which tool format produced the output: `vitest_jest`, `node_test`, `tsc`, `eslint`, `pytest`, `git_diff`, `git_log`, `npm_install`, or `other`. The full result stays when P(keep all) exceeds `1 - context.confidence` (default: keep when Jev gives `all` more than 0.2), when the probability is missing, or on any request error. When a format has at least `context.formatConfidence` (0.7) and its markers are present, a deterministic parser keeps the exact lines that matter for that format: failing tests with their assertion lines, compiler and linter errors with file and line, changed files with +/- counts, package manager notices, and the final summary line. Otherwise code keeps bounded head/diagnostic/tail excerpts. Nothing is paraphrased. An exact copy is written to an owner-only temporary directory before replacement; the excerpt links to it. If storage fails, the original stays. Multiple text blocks keep their layout and are not compressed. Trace and widget show the actual bytes saved. No extra steer is persisted for compression alone.
+
+**Recall through search.** The footer under every excerpt or duplicate note names the file and a search command that exists on this machine, probed once per session in this order: `rg`, `ag`, `ugrep`, `git grep --no-index`, `grep`, PowerShell `Select-String`, `findstr`. It asks for a scoped search or a ranged `read` and says not to read the whole file. `context.recallTool` pins one of those names or `none`; `auto` probes. Recalls are counted by kind: a whole-file read undoes the saving, a scoped access keeps it.
 
-**Measuring it.** `/warden status` keeps a session ledger so the saver's value is a number, not a claim: how many outputs were large enough to consider, how many Jev compressed, the bytes removed (≈ tokens at 4 bytes each), the *token-turns spared* (removed tokens × every later turn, which is what a prompt cache would otherwise have re-read), and **recalls** — how often the agent went back and read the stored full output. A recall means the excerpt was not enough; a recall rate above about 10% says `context.confidence` is too low for your work, near 0% says it could go lower. Every compression and recall also appears in the trace with the running ledger. The quality effect (less context rot) does not show in a counter; compare a scripted task with `context.enabled` on and off if you want that number.
+**Measuring it.** `/warden status` keeps a session ledger so the saver's value is a number, not a claim: how many outputs were large enough to consider, how many Jev compressed, how many duplicates were dropped, the bytes removed (≈ tokens at 4 bytes each), the *token-turns spared* (removed tokens × every later turn, which is what a prompt cache would otherwise have re-read), and **recalls** — how often the agent went back to a stored full output, split into whole-file reads and scoped accesses. A recall means the excerpt was not enough; a recall rate above about 10% says `context.confidence` is too low for your work, near 0% says it could go lower. Whole-file recalls also give back the saving; scoped ones do not. Every compression and recall also appears in the trace with the running ledger. The quality effect (less context rot) does not show in a counter; compare a scripted task with `context.enabled` on and off if you want that number.
 
-This MVP is always tail-only: set `context.enabled: false` to stop compression. It never prunes a warm prefix, changes the system prompt, or edits historical session entries. Full-output files can contain secrets; they remain in the OS temporary directory until you or the OS remove them. Excerpts can omit relevant evidence; read the linked file before making a decision that needs it.
+Set `context.enabled: false` to stop all of it. The saver never prunes a warm prefix, changes the system prompt, changes the tool list after load, or edits historical session entries: every change is to the newest tool result before it enters the session, so the prompt cache prefix is unaffected. Full-output files can contain secrets; they remain in the OS temporary directory until you or the OS remove them. Excerpts can omit relevant evidence; read the linked file before making a decision that needs it.
 
 ### Task continuity
 
@@ -137,11 +149,12 @@ Templates in `config.widget` control the text. Segments are separated by ` · `;
   "done": "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}",
   "prose": "warden · prose · wordy {wordy} · clichés {cliches} · jargon {jargon} · {flags} · {status}",
   "security": "warden · security · {tool} · injection {injection} · exfiltration {exfiltration} · {status}",
-  "context": "warden · context · {tool} · {retention} · saved {bytesSaved} bytes"
+  "context": "warden · context · {tool} · {retention} · saved {bytesSaved} bytes",
+  "runaway": "warden · runaway · {kind} · {count}× repeated · {chars} chars · {signal} · {status}"
 }
 ```
 
-Tokens — action: `tool level source irreversible offTask scope approved slop slopStub slopComments slopDead slopHedging patterns reasons path model ms flags time`; prose: `wordy cliches jargon status reasons model ms flags time`; stuck: `failures sameStrategy approachChange progress status source reasons model ms flags time`; done: `changes checks checksPassed claimsDone claimsVerified checksApply outcome status reasons model ms flags time`. Security tokens: `tool injection exfiltration status`; context tokens: `tool retention bytesSaved`. A minimal line: `"action": "⚔ {tool} {level} · {irreversible}/{offTask}"`. Set `"enabled": false` to hide the line (the trace and panel keep working); `"shortcut": ""` disables the keybinding.
+Tokens — action: `tool level source irreversible offTask scope approved slop slopStub slopComments slopDead slopHedging patterns reasons path model ms flags time`; prose: `wordy cliches jargon status reasons model ms flags time`; stuck: `failures sameStrategy approachChange progress status source reasons model ms flags time`; done: `changes checks checksPassed claimsDone claimsVerified checksApply outcome status reasons model ms flags time`. Security tokens: `tool injection exfiltration status`; context tokens: `tool retention bytesSaved`; runaway tokens: `kind count chars signal block status time`. A minimal line: `"action": "⚔ {tool} {level} · {irreversible}/{offTask}"`. Set `"enabled": false` to hide the line (the trace and panel keep working); `"shortcut": ""` disables the keybinding.
 
 ## Configuration
 
@@ -164,7 +177,9 @@ User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use the
   "stuck": { "enabled": true, "window": 12, "minFailures": 3, "cooldown": 3, "sameStrategy": 0.7, "nudge": true },
   "done": { "enabled": true, "claimsDone": 0.7, "nudge": true },
   "security": { "enabled": true, "threshold": 0.7 },
-  "context": { "enabled": true, "tailMinChars": 12000, "confidence": 0.8 },
+  "context": { "enabled": true, "tailMinChars": 12000, "confidence": 0.8, "duplicateMinChars": 2000, "recallTool": "auto", "formatConfidence": 0.7 },
+  "runaway": { "enabled": true, "repeats": 4, "thinkingRepeats": 10, "minChars": 400, "recover": true },
+  "notify": { "enabled": true, "cooldownMs": 10000, "command": [] },
   "slop": {
     "enabled": true,
     "threshold": 0.7,
@@ -175,11 +190,11 @@ User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use the
 }
 ```
 
-A project may add `.pi/pi-warden.json` with `enabled` and per-guard overrides (for example stricter thresholds, extra guarded tools, or `"done": { "enabled": false }`). Project files are read only when Pi trusts the project, and they can never grant `typesafe` consent, change `mode`, or raise `timeoutMs`/`maxRequests`. Environment: `PI_WARDEN_ENABLED=1` (consent), `PI_WARDEN_MODE=steer|confirm|advise`. Files from 0.1.x that set `action.timeoutMs`/`action.maxRequests` keep working.
+A project may add `.pi/pi-warden.json` with `enabled` and per-guard overrides (for example stricter thresholds, extra guarded tools, or `"done": { "enabled": false }`). Project files are read only when Pi trusts the project, and they can never grant `typesafe` consent, change `mode`, raise `timeoutMs`/`maxRequests`, or set `notify.command`. Environment: `PI_WARDEN_ENABLED=1` (consent), `PI_WARDEN_MODE=steer|confirm|advise`. Files from 0.1.x that set `action.timeoutMs`/`action.maxRequests` keep working.
 
 ## Data handling
 
-- With consent, each guarded call sends to `https://api.typesafe.ai`: your latest prompt (truncated to 1500 characters), the tool name, the command (truncated to 2000 characters) or the file path (relative inside the project, `~`-shortened outside), whether the file exists, a 1500-character head/middle/tail sample for `write`, and the first three edit pairs (400 characters each) for `edit`. The stuck detector sends the last 12 tool calls (300 characters each) with 400-character output tails; the done-check and the prose check send the agent's final message (2000 and 2500 characters) with the run's check commands and the audience description. Scope and retention requests also carry up to eight prior user/assistant text messages (750 redacted characters each). Output checks send a redacted head/tail sample up to 6000 characters plus size and tool name. No unrelated files or telemetry.
+- With consent, each guarded call sends to `https://api.typesafe.ai`: your latest prompt (truncated to 1500 characters), the tool name, the command (truncated to 2000 characters) or the file path (relative inside the project, `~`-shortened outside), whether the file exists, a 1500-character head/middle/tail sample for `write`, and the first three edit pairs (400 characters each) for `edit`. The stuck detector sends the last 12 tool calls (300 characters each) with 400-character output tails; the done-check and the prose check send the agent's final message (2000 and 2500 characters) with the run's check commands and the audience description. Scope and retention requests also carry up to eight prior user/assistant text messages (750 redacted characters each). Output checks send a redacted head/tail sample up to 6000 characters plus size, line counts, and tool name; the format question uses that same sample. Duplicate detection and the runaway guard send nothing. No unrelated files or telemetry.
 - Obvious credentials in the action (`Authorization` headers, `TOKEN=`/`SECRET=` assignments, `sk-`, `ghp_`, `AKIA`, JWTs, URL passwords, PEM blocks) are replaced with `[redacted]` before sending. This is best-effort; do not rely on it for prompts that contain secrets.
 - Text returned or steered to the agent names the tool, the reasons, and the scores, not the command text. UI errors never include upstream response bodies or keys.
 - Judgments are model output. Thresholds are yours to tune; a hold is information for the agent and for you, not a verdict on either.
@@ -208,15 +223,16 @@ steerReason(verdict, { canApprove: true });   // the text the agent receives for
 
 `evaluateAction` judges one call. What spans calls in a session, the hold → reply → retry approval and the batched judging of sibling tool calls, is `ActionGuard`: `inspect(call, conversation, options)` returns the same `Verdict`, `hold(task)` records a hold, `turnEnd()` and `reset()` follow Pi's turn and session.
 
-Also exported: `matchPatterns`, `isReadOnlyCommand`, `describeAction`, `redact`, `formatVerdict`, the question sets, the stuck detector (`AttemptWindow`, `makeAttempt`, `evaluateStuck`, `stuckNudge`), the done-check (`classifyToolResult`, `recordOutcome`, `needsDoneCheck`, `evaluateDone`, `doneNudge`), and the config helpers.
+Also exported: `matchPatterns`, `isReadOnlyCommand`, `describeAction`, `redact`, `formatVerdict`, the question sets, the stuck detector (`AttemptWindow`, `makeAttempt`, `evaluateStuck`, `stuckNudge`), the runaway guard (`RunawayMonitor`, `findRepeats`, `runawayNudge`), the notifier (`detectNotifier`, `notifierCommand`, `sendNotification`), the done-check (`classifyToolResult`, `recordOutcome`, `needsDoneCheck`, `evaluateDone`, `doneNudge`), and the config helpers.
 
 ## Development
 
 ```bash
 npm install
 npm run check        # typecheck, offline tests (mocked transport), build
-npm run test:live    # 43 billable synthetic judgments across all guards (key from .env or the stored login); pass action|slop|approval|stuck|done|security for one group
-node scripts/security-cases.mjs [context]   # the 12-case output-security, task-continuity, and retention set on its own
+npm run test:live    # 55 billable synthetic judgments across all guards (key from .env or the stored login); pass action|slop|approval|stuck|done|security|context for one group
+node scripts/security-cases.mjs   # the 9-case output-security and task-continuity set on its own
+node scripts/context-cases.mjs    # 15 labelled outputs that tune retention and format for the context saver
 npm run dev:pi       # start Pi with this working tree plus an installed pi-typesafe
 node scripts/slop-cases.mjs   # 22 billable cases that tune the slop and prose questions
 npm run preview      # re-render docs/preview.png from the recorded live verdicts (needs a Chrome binary)

package/dist/config.d.ts

@@ -64,7 +64,37 @@ export interface ContextConfig {
     tailMinChars: number;
     /** Minimum P(the full output is not needed), 1 - P(all), before code removes output. */
     confidence: number;
+    /** A text result at least this long that repeats an earlier result of this session is replaced by a short note (code only). */
+    duplicateMinChars: number;
+    /** Search command named in the recall footer; `auto` detects one at load. */
+    recallTool: RecallTool;
+    /** Minimum P(format) before a format-specific parser builds the excerpt instead of the generic head/tail one. */
+    formatConfidence: number;
 }
+export interface RunawayConfig {
+    enabled: boolean;
+    /** Identical text paragraphs in one streaming reply before the run is stopped. Ordinary replies repeat a paragraph twice at most. */
+    repeats: number;
+    /** The same limit for thinking, where code drafting repeats paragraphs legitimately. */
+    thinkingRepeats: number;
+    /** Characters streamed before the first check. */
+    minChars: number;
+    /** After stopping, start one follow-up turn that names the repeat and asks for the one next step; once per user prompt. */
+    recover: boolean;
+}
+export interface NotifyConfig {
+    /** Desktop notification when the agent needs you: a held call it will ask about, a confirm dialog, a stopped runaway. */
+    enabled: boolean;
+    /** Sibling holds in one turn produce one notification; a second within this many milliseconds is skipped. */
+    cooldownMs: number;
+    /**
+     * Your own notifier as an argv (no shell), for ssh sessions or a phone relay: `{title}` and `{body}` in an argument are
+     * replaced, and both are in PI_WARDEN_TITLE / PI_WARDEN_BODY. Empty: detect the desktop's own tool. User file only.
+     */
+    command: string[];
+}
+export type RecallTool = "auto" | "rg" | "ag" | "ugrep" | "git-grep" | "grep" | "select-string" | "findstr" | "none";
+export declare function isRecallTool(value: unknown): value is RecallTool;
 export type WardenMode = "steer" | "confirm" | "advise";
 export interface WardenConfig {
     /** Master switch. false disables every guard, including offline pattern checks. */
@@ -87,6 +117,8 @@ export interface WardenConfig {
     slop: SlopGuardConfig;
     security: SecurityConfig;
     context: ContextConfig;
+    runaway: RunawayConfig;
+    notify: NotifyConfig;
     /** The status line above the editor and the trace panel. */
     widget: WidgetConfig;
     /** Show steer messages in the transcript. They are always visible in the trace panel. */
@@ -94,7 +126,7 @@ export interface WardenConfig {
 }
 export declare const PACKAGE_NAME = "pi-warden";
 /** Bumped when WardenConfig gains a section; extension.ts checks it so a half-updated module graph is reported, not crashed on. */
-export declare const CONFIG_SCHEMA = 3;
+export declare const CONFIG_SCHEMA = 4;
 export declare const PROJECT_CONFIG_FILE = "pi-warden.json";
 export declare function defaultConfig(): WardenConfig;
 /** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */

package/dist/config.js

@@ -3,9 +3,13 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { COMMAND_TOOLS } from "./tools.js";
 import { defaultWidgetConfig } from "./widget.js";
+const RECALL_TOOLS = ["auto", "rg", "ag", "ugrep", "git-grep", "grep", "select-string", "findstr", "none"];
+export function isRecallTool(value) {
+    return typeof value === "string" && RECALL_TOOLS.includes(value);
+}
 export const PACKAGE_NAME = "pi-warden";
 /** Bumped when WardenConfig gains a section; extension.ts checks it so a half-updated module graph is reported, not crashed on. */
-export const CONFIG_SCHEMA = 3;
+export const CONFIG_SCHEMA = 4;
 export const PROJECT_CONFIG_FILE = `${PACKAGE_NAME}.json`;
 export function defaultConfig() {
     return {
@@ -26,7 +30,9 @@ export function defaultConfig() {
         done: { enabled: true, claimsDone: 0.7, nudge: true },
         slop: { enabled: true, threshold: 0.7, prose: { enabled: true, audience: "technical", threshold: 0.7, trend: 2, minChars: 200 } },
         security: { enabled: true, threshold: 0.7 },
-        context: { enabled: true, tailMinChars: 12000, confidence: 0.8 },
+        context: { enabled: true, tailMinChars: 12000, confidence: 0.8, duplicateMinChars: 2000, recallTool: "auto", formatConfidence: 0.7 },
+        runaway: { enabled: true, repeats: 4, thinkingRepeats: 10, minChars: 400, recover: true },
+        notify: { enabled: true, cooldownMs: 10000, command: [] },
         widget: defaultWidgetConfig(),
         steerVisible: false,
     };
@@ -100,6 +106,26 @@ function applyStuck(base, raw) {
         nudge: boolean(raw.nudge, base.nudge),
     };
 }
+function applyRunaway(base, raw) {
+    if (!isObject(raw))
+        return base;
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        // One occurrence is not a repeat, so the floor is 2.
+        repeats: Math.max(2, positiveInteger(raw.repeats, base.repeats)),
+        thinkingRepeats: Math.max(2, positiveInteger(raw.thinkingRepeats, base.thinkingRepeats)),
+        minChars: positiveInteger(raw.minChars, base.minChars),
+        recover: boolean(raw.recover, base.recover),
+    };
+}
+function applyNotify(base, raw, allowCommand) {
+    if (!isObject(raw))
+        return base;
+    const cooldown = typeof raw.cooldownMs === "number" && Number.isSafeInteger(raw.cooldownMs) && raw.cooldownMs >= 0 ? raw.cooldownMs : base.cooldownMs;
+    const command = allowCommand && Array.isArray(raw.command) && raw.command.every((arg) => typeof arg === "string") && (raw.command.length === 0 || raw.command[0].trim())
+        ? [...raw.command] : base.command;
+    return { enabled: boolean(raw.enabled, base.enabled), cooldownMs: cooldown, command };
+}
 function applyDone(base, raw) {
     if (!isObject(raw))
         return base;
@@ -138,6 +164,7 @@ function applyWidget(base, raw) {
         prose: template(raw.prose, base.prose),
         security: template(raw.security, base.security),
         context: template(raw.context, base.context),
+        runaway: template(raw.runaway, base.runaway),
     };
 }
 /** Shared request settings; `action.timeoutMs`/`action.maxRequests` from 0.1.x files are still honoured. */
@@ -148,8 +175,11 @@ function applyShared(base, raw) {
         maxRequests: positiveInteger(raw.maxRequests ?? legacy.maxRequests, base.maxRequests),
     };
 }
-function applyGuards(base, raw, timeoutMs) {
+function applyGuards(base, raw, timeoutMs, source) {
     return {
+        runaway: applyRunaway(base.runaway, raw.runaway),
+        // A project file may switch notifications off or on, but never names a command to run.
+        notify: applyNotify(base.notify, raw.notify, source === "user"),
         action: applyAction(base.action, raw.action, timeoutMs),
         stuck: applyStuck(base.stuck, raw.stuck),
         done: applyDone(base.done, raw.done),
@@ -162,6 +192,9 @@ function applyGuards(base, raw, timeoutMs) {
             enabled: boolean(raw.context.enabled, base.context.enabled),
             tailMinChars: positiveInteger(raw.context.tailMinChars, base.context.tailMinChars),
             confidence: probability(raw.context.confidence, base.context.confidence),
+            duplicateMinChars: positiveInteger(raw.context.duplicateMinChars, base.context.duplicateMinChars),
+            recallTool: isRecallTool(raw.context.recallTool) ? raw.context.recallTool : base.context.recallTool,
+            formatConfidence: probability(raw.context.formatConfidence, base.context.formatConfidence),
         } : base.context,
     };
 }
@@ -175,7 +208,7 @@ export function applyUserOverrides(base, raw) {
         typesafe: boolean(raw.typesafe, base.typesafe),
         mode: isMode(raw.mode) ? raw.mode : base.mode,
         ...shared,
-        ...applyGuards(base, raw, shared.timeoutMs),
+        ...applyGuards(base, raw, shared.timeoutMs, "user"),
         widget: applyWidget(base.widget, raw.widget),
         steerVisible: boolean(raw.steerVisible, base.steerVisible),
     };
@@ -184,7 +217,7 @@ export function applyUserOverrides(base, raw) {
 export function applyProjectOverrides(base, raw) {
     if (!isObject(raw))
         return base;
-    return { ...base, enabled: boolean(raw.enabled, base.enabled), ...applyGuards(base, raw, base.timeoutMs) };
+    return { ...base, enabled: boolean(raw.enabled, base.enabled), ...applyGuards(base, raw, base.timeoutMs, "project") };
 }
 export function loadConfig(options = {}) {
     let config = applyUserOverrides(defaultConfig(), readJson(userConfigPath()));

package/dist/excerpt.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Format-aware excerpts. Jev selects which tool produced the output; code keeps the exact lines that matter for that
+ * format: failing tests with their assertion lines, compiler and linter errors with file:line, changed files with
+ * counts, package manager warnings, and the final summary. Nothing is paraphrased. A parser returns undefined when
+ * it does not recognise its markers, and the caller falls back to the generic head/diagnostic/tail excerpt.
+ */
+export type OutputFormat = "vitest_jest" | "node_test" | "tsc" | "eslint" | "pytest" | "git_diff" | "git_log" | "npm_install" | "other";
+export declare const formatQuestion: {
+    format: import("pi-typesafe").ChoiceQuestion<{
+        readonly vitest_jest: "A Vitest or Jest run: ✓/✗/× or PASS/FAIL per test, a 'Test Files' or 'Tests:' summary.";
+        readonly node_test: "Node's built-in test runner: TAP lines 'ok'/'not ok' with '# tests', or the spec reporter with ✔/✖ and 'ℹ tests'.";
+        readonly tsc: "TypeScript compiler diagnostics: 'file(line,col): error TSnnnn:' lines, 'Found N errors'.";
+        readonly eslint: "ESLint report: a file path line followed by 'line:col  error|warning  message  rule', then '✖ N problems'.";
+        readonly pytest: "pytest: dots/F per test, '___ test_name ___' failure headers, 'E ' assertion lines, 'FAILED'/'PASSED' lines, '=== N passed/failed ===' summary.";
+        readonly git_diff: "A unified diff: 'diff --git', '---'/'+++', '@@' hunks with +/- lines.";
+        readonly git_log: "git log or git status output: 'commit <hash>' blocks or one-line hashes with subjects; 'modified:'/'new file:' status lines.";
+        readonly npm_install: "npm, pnpm, or yarn install: 'added N packages', 'npm warn', 'deprecated', 'vulnerabilities', 'up to date'.";
+        readonly other: "Anything else: source code, data, documentation, a shell listing, a mixed or unknown log.";
+    }>;
+};
+/**
+ * Exact lines selected by the parser for `format`, joined and capped, with the last non-empty lines as a tail so the
+ * final status is always present. Undefined when the format is `other` or its markers are absent.
+ */
+export declare function formatExcerpt(text: string, format: OutputFormat): string | undefined;

package/dist/excerpt.js

@@ -0,0 +1,171 @@
+import { choice } from "pi-typesafe";
+export const formatQuestion = {
+    format: choice("Which kind of tool produced `output`? Judge from the markers in the sample; `tool` names the calling tool, not the program. Select other when unsure or when the output is source code, data, or prose.", {
+        vitest_jest: "A Vitest or Jest run: ✓/✗/× or PASS/FAIL per test, a 'Test Files' or 'Tests:' summary.",
+        node_test: "Node's built-in test runner: TAP lines 'ok'/'not ok' with '# tests', or the spec reporter with ✔/✖ and 'ℹ tests'.",
+        tsc: "TypeScript compiler diagnostics: 'file(line,col): error TSnnnn:' lines, 'Found N errors'.",
+        eslint: "ESLint report: a file path line followed by 'line:col  error|warning  message  rule', then '✖ N problems'.",
+        pytest: "pytest: dots/F per test, '___ test_name ___' failure headers, 'E ' assertion lines, 'FAILED'/'PASSED' lines, '=== N passed/failed ===' summary.",
+        git_diff: "A unified diff: 'diff --git', '---'/'+++', '@@' hunks with +/- lines.",
+        git_log: "git log or git status output: 'commit <hash>' blocks or one-line hashes with subjects; 'modified:'/'new file:' status lines.",
+        npm_install: "npm, pnpm, or yarn install: 'added N packages', 'npm warn', 'deprecated', 'vulnerabilities', 'up to date'.",
+        other: "Anything else: source code, data, documentation, a shell listing, a mixed or unknown log.",
+    }),
+};
+const LIMIT = 6000;
+/** Header lines start a block; the following non-empty lines up to `depth` are kept with it. */
+function capture(lines, header, keep, depth, summary) {
+    const out = [];
+    let headers = 0;
+    let remaining = 0;
+    for (const line of lines) {
+        if (header.test(line)) {
+            headers++;
+            remaining = depth;
+            out.push(line);
+            continue;
+        }
+        if (summary.test(line)) {
+            out.push(line);
+            remaining = 0;
+            continue;
+        }
+        if (remaining > 0 && line.trim()) {
+            if (keep.test(line))
+                out.push(line);
+            remaining--;
+        }
+    }
+    return headers || out.length ? out : undefined;
+}
+function vitestJest(lines) {
+    const summary = /^\s*(?:Test Files|Tests|Test Suites|Snapshots|Duration|Time|Start at|Ran all test suites)\b|^\s*(?:FAIL|PASS)\s{2,}\S/;
+    const out = capture(lines, /^\s*(?:FAIL\s|[×✗✕]\s|●\s|❯\s.*\s\d+\s*$|AssertionError\b)/, /expected|received|actual|Error|assert|❯|›|\bat\b.*:\d+:\d+|[+-]\s|^\s*\d+\|/i, 8, summary);
+    return out && lines.some(line => summary.test(line) || /[✓✗×✔✖]/.test(line)) ? out : undefined;
+}
+function nodeTest(lines) {
+    const summary = /^(?:#|ℹ)\s*(?:tests|suites|pass|fail|cancelled|skipped|todo|duration_ms)\b/;
+    if (!lines.some(line => summary.test(line) || /^TAP version/.test(line) || /^\s*[✔✖]\s/.test(line)))
+        return undefined;
+    return capture(lines, /^\s*(?:not ok\b|✖\s)/, /error|expected|actual|Error|failureType|code|at\b.*:\d+:\d+|^\s*[+-]\s|^\s*\|/i, 10, summary) ?? [];
+}
+function tsc(lines) {
+    const header = /^(?:\S.*?)(?:\(\d+,\d+\)|:\d+:\d+)\s*[-:]\s*error TS\d+/;
+    if (!lines.some(line => header.test(line) || /^Found \d+ errors?/.test(line)))
+        return undefined;
+    return capture(lines, header, /^\s{2,}\S/, 3, /^Found \d+ errors?|^error TS\d+/);
+}
+function eslint(lines) {
+    const problem = /^\s+\d+:\d+\s+(?:error|warning)\s+/;
+    if (!lines.some(line => problem.test(line)) || !lines.some(line => /^✖ \d+ problems?|^\d+ problems? \(/.test(line) || /\S+\.[cm]?[jt]sx?$|\.vue$|\.svelte$/.test(line)))
+        return undefined;
+    const out = [];
+    let file;
+    for (const line of lines) {
+        if (/^\S.*\.(?:[cm]?[jt]sx?|vue|svelte|json|md)$/.test(line)) {
+            file = line;
+            continue;
+        }
+        if (problem.test(line)) {
+            if (file) {
+                out.push(file);
+                file = undefined;
+            }
+            out.push(line);
+            continue;
+        }
+        if (/^✖ \d+ problems?|^\d+ problems? \(|potentially fixable/.test(line))
+            out.push(line);
+    }
+    return out;
+}
+function pytest(lines) {
+    const summary = /^=+ .*(?:passed|failed|error|skipped|no tests ran).* =+$|^=+ short test summary info =+$|^(?:FAILED|ERROR) \S+/;
+    if (!lines.some(line => summary.test(line) || /^_{3,} .+ _{3,}$/.test(line)))
+        return undefined;
+    return capture(lines, /^_{3,} .+ _{3,}$/, /^E\s|^>\s|:\d+: |Error|assert/i, 12, summary) ?? [];
+}
+function gitDiff(lines) {
+    const files = [];
+    for (const line of lines) {
+        const match = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+        if (match) {
+            files.push({ name: match[2], added: 0, removed: 0 });
+            continue;
+        }
+        const current = files.at(-1);
+        if (!current)
+            continue;
+        if (/^(?:new file mode|deleted file mode|rename (?:from|to)|Binary files)/.test(line))
+            current.note = (current.note ? `${current.note}; ` : "") + line;
+        else if (line.startsWith("+") && !line.startsWith("+++"))
+            current.added++;
+        else if (line.startsWith("-") && !line.startsWith("---"))
+            current.removed++;
+    }
+    if (!files.length)
+        return undefined;
+    const added = files.reduce((sum, file) => sum + file.added, 0);
+    const removed = files.reduce((sum, file) => sum + file.removed, 0);
+    return [...files.map(file => `${file.name}  +${file.added} -${file.removed}${file.note ? `  (${file.note})` : ""}`), `${files.length} files changed, +${added} -${removed}`];
+}
+function gitLog(lines) {
+    const out = [];
+    let pendingSubject = false;
+    for (const line of lines) {
+        const commit = /^commit ([0-9a-f]{7,40})\b/.exec(line);
+        if (commit) {
+            out.push(commit[1].slice(0, 12));
+            pendingSubject = true;
+            continue;
+        }
+        if (pendingSubject && /^\s{4}\S/.test(line)) {
+            out[out.length - 1] += `  ${line.trim()}`;
+            pendingSubject = false;
+            continue;
+        }
+        if (/^[0-9a-f]{7,40} \S/.test(line) || /^\s*(?:modified|new file|deleted|renamed|both modified):|^\?\?\s|^[ MADRCU?!]{2}\s\S/.test(line) || /^(?:On branch|Your branch|Changes (?:to be committed|not staged)|Untracked files|nothing to commit)/.test(line))
+            out.push(line);
+    }
+    return out.length ? out : undefined;
+}
+function npmInstall(lines) {
+    const keep = /^(?:added|removed|changed|audited|found|up to date|up-to-date)\b|\bvulnerabilit(?:y|ies)\b|^npm (?:warn|WARN|error|ERR!|notice)\b|\bdeprecated\b|^(?:warning|error)\s|^\s*Progress: resolved|^Done in|^Packages: /i;
+    const out = lines.filter(line => keep.test(line));
+    return out.some(line => /^(?:added|removed|changed|audited|up to date|up-to-date|Done in|Packages:)/i.test(line)) ? out : undefined;
+}
+const PARSERS = {
+    vitest_jest: vitestJest, node_test: nodeTest, tsc, eslint, pytest, git_diff: gitDiff, git_log: gitLog, npm_install: npmInstall,
+};
+/**
+ * Exact lines selected by the parser for `format`, joined and capped, with the last non-empty lines as a tail so the
+ * final status is always present. Undefined when the format is `other` or its markers are absent.
+ */
+export function formatExcerpt(text, format) {
+    if (format === "other")
+        return undefined;
+    const lines = text.split("\n");
+    const selected = PARSERS[format](lines);
+    if (!selected)
+        return undefined;
+    const tail = lines.filter(line => line.trim()).slice(-3);
+    const body = [];
+    let size = 0;
+    let dropped = 0;
+    for (const line of selected) {
+        const clipped = line.length > 400 ? `${line.slice(0, 400)}…` : line;
+        if (size + clipped.length + 1 > LIMIT - 400) {
+            dropped++;
+            continue;
+        }
+        body.push(clipped);
+        size += clipped.length + 1;
+    }
+    const parts = [`[${format} excerpt: ${selected.length} selected lines${dropped ? `, ${dropped} omitted for size` : ""}]`, ...body];
+    // The final status line is the one the agent reads first; add the tail only when the parser did not already keep it.
+    // Diffs and logs have no status line; their last lines are hunk or body text.
+    const last = tail.at(-1);
+    if (format !== "git_diff" && format !== "git_log" && last !== undefined && !body.includes(last))
+        parts.push("[tail]", ...tail.map(line => line.length > 400 ? `${line.slice(0, 400)}…` : line));
+    return parts.join("\n");
+}

package/dist/extension.d.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ToolCallRef } from "./action-guard.js";
 import type { SlopSymptom, Verdict } from "./guard.js";
-export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; and redacted tool-output samples for security and tail compression. Compression stores an exact, owner-only copy in a temporary file on this machine. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
+export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; and redacted tool-output samples for security and context saving (retention and output format). Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 /**
  * Tool calls of the assistant message being preflighted. Pi runs `tool_call` hooks for sibling calls one after another,
  * so judging them one request at a time costs one round trip per call; judging them together costs one round trip.