pi-warden 0.7.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 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).
+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)
 
@@ -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,6 +92,10 @@ 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.
 
+### 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.
@@ -141,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
 
@@ -169,6 +178,8 @@ User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use the
   "done": { "enabled": true, "claimsDone": 0.7, "nudge": true },
   "security": { "enabled": true, "threshold": 0.7 },
   "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,
@@ -179,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, line counts, and tool name; the format question uses that same sample. Duplicate detection sends nothing. 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.
@@ -212,7 +223,7 @@ 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
 

package/dist/config.d.ts

@@ -71,6 +71,28 @@ export interface ContextConfig {
     /** 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";
@@ -95,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. */
@@ -102,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

@@ -9,7 +9,7 @@ export function isRecallTool(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 {
@@ -31,6 +31,8 @@ export function defaultConfig() {
         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, 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,
     };
@@ -104,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;
@@ -142,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. */
@@ -152,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),
@@ -182,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),
     };
@@ -191,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/extension.js

@@ -10,16 +10,18 @@ import { evaluateProse, proseNudge, ProseTrend } from "./prose.js";
 import { compressOutput, duplicateNote, evaluateOutput, outputKey, saveOutput, securityNotice } from "./output.js";
 import { classifyRecall, detectSearchTool, recallInstruction } from "./recall.js";
 import { redact } from "./redact.js";
+import { detectNotifier, sendNotification } from "./notify.js";
+import { formatRunaway, RunawayMonitor, runawayNudge } from "./runaway.js";
 import { AttemptWindow, evaluateStuck, formatStuck, makeAttempt, resultFailed, stuckNudge } from "./stuck.js";
 import { openTracePanel } from "./panel.js";
 import { completeConfig, shapeWarning } from "./shape.js";
 import { ContextLedger, formatLedger } from "./saver.js";
-import { actionDetails, doneDetails, proseDetails, stuckDetails, Trace } from "./trace.js";
+import { actionDetails, doneDetails, proseDetails, runawayDetails, stuckDetails, Trace } from "./trace.js";
 import { proseTokens, renderTemplate, TOKEN_NAMES } from "./widget.js";
 export 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.";
 const WIDGET = PACKAGE_NAME;
 const CONFIRM_TEXT_LIMIT = 500;
-const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, held: 0, approved: 0, slop: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, proseChecks: 0, proseNudges: 0, errors: 0 });
+const freshStats = () => ({ inspected: 0, judged: 0, warned: 0, held: 0, approved: 0, slop: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, proseChecks: 0, proseNudges: 0, runaway: 0, errors: 0 });
 function latestUserPrompt(ctx) {
     const entries = ctx.sessionManager.getBranch();
     for (let index = entries.length - 1; index >= 0; index--) {
@@ -128,8 +130,15 @@ export default function wardenExtension(pi) {
     const prose = new ProseTrend();
     const slopCounts = { stub: 0, comments: 0, dead: 0, hedging: 0 };
     const ledger = new ContextLedger();
+    const runaway = new RunawayMonitor();
+    // Runs stopped by the runaway guard for the current user prompt; the first one gets a recovery turn, later ones wait for the user.
+    let runawayStops = 0;
+    let pendingRunaway;
     // Probed once per session, outside any tool_result handler; the footer under excerpts names this command.
     let searchTool;
+    // Desktop notifier, probed on first use; undefined after the probe means this machine has no route to the desktop.
+    let notifier;
+    let lastNotifiedAt = 0;
     // A partially updated module graph can hand this build a config without the sections it expects; see shape.ts.
     let shapeReported = false;
     const configFor = (ctx) => {
@@ -195,6 +204,24 @@ export default function wardenExtension(pi) {
         paint(ctx, config);
     };
     const steer = (config, content, options = { deliverAs: "steer" }) => pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content, display: config.steerVisible }, options);
+    /**
+     * Desktop notification for a moment that needs the user back at the terminal. Interactive sessions only: a headless run
+     * or a subagent has nobody to call, and several of them would flood the desktop. Fire-and-forget; failures are silent.
+     */
+    const notifyDesktop = (ctx, config, body) => {
+        if (!ctx.hasUI || !config.notify.enabled)
+            return;
+        const now = Date.now();
+        if (now - lastNotifiedAt < config.notify.cooldownMs)
+            return;
+        lastNotifiedAt = now;
+        if (config.notify.command.length) {
+            void sendNotification(config.notify.command, { title: "pi-warden", body }).catch(() => false);
+            return;
+        }
+        notifier ??= detectNotifier();
+        void notifier.then(name => (name ? sendNotification(name, { title: "pi-warden", body }) : false)).catch(() => false);
+    };
     pi.on("session_start", async (_event, ctx) => {
         client = undefined;
         budgetExhausted = false;
@@ -208,7 +235,12 @@ export default function wardenExtension(pi) {
         doneNudged = false;
         prose.reset();
         ledger.reset();
+        runaway.reset();
+        runawayStops = 0;
+        pendingRunaway = undefined;
         searchTool = undefined;
+        notifier = undefined;
+        lastNotifiedAt = 0;
         for (const symptom of Object.keys(slopCounts))
             slopCounts[symptom] = 0;
         if (ctx.hasUI)
@@ -218,8 +250,39 @@ export default function wardenExtension(pi) {
     pi.on("before_agent_start", async (_event, ctx) => {
         attempts = new AttemptWindow(configFor(ctx).stuck.window);
         doneNudged = false;
+        runaway.reset();
+        runawayStops = 0;
+        pendingRunaway = undefined;
         actionGuard.turnEnd();
     });
+    // Each assistant message is judged on its own; Pi does not forward the stream's own "start" event, so this is the reset.
+    pi.on("message_start", async (event) => {
+        if (event.message.role === "assistant")
+            runaway.reset();
+    });
+    // Per token this only appends to a buffer; every 256 characters the buffer is checked for identical blocks, with code only.
+    pi.on("message_update", async (event, ctx) => {
+        const kind = runaway.feed(event.assistantMessageEvent);
+        if (!kind || runaway.stopped)
+            return;
+        const config = configFor(ctx);
+        if (!config.enabled || !config.runaway.enabled)
+            return;
+        const verdict = runaway.check(kind, config.runaway);
+        if (!verdict)
+            return;
+        stats.runaway++;
+        runawayStops++;
+        const recover = config.runaway.recover && runawayStops === 1;
+        const nudge = runawayNudge(verdict, recover);
+        pendingRunaway = { nudge, recover };
+        record(ctx, config, "runaway", formatRunaway(verdict, recover, config.widget.runaway), runawayDetails(verdict, nudge, recover));
+        if (ctx.hasUI)
+            ctx.ui.notify(`warden · runaway: the same ${verdict.kind} block repeated ${verdict.count} times in ${verdict.chars} chars; run stopped${recover ? " (agent gets one follow-up turn)" : " (not restarted: second time for this prompt)"}`, "error");
+        notifyDesktop(ctx, config, `Runaway stopped: the same ${verdict.kind} block repeated ${verdict.count} times. ${recover ? "The agent gets one recovery turn." : "Second time for this prompt; the agent is waiting for you."}`);
+        // Interactive Pi restores the user's queued messages to the editor before aborting; the follow-up is queued in agent_end, after that.
+        ctx.abort();
+    });
     // Each low-level run collects its own evidence of changes and checks.
     pi.on("agent_start", async () => {
         evidence = emptyEvidence();
@@ -289,6 +352,7 @@ export default function wardenExtension(pi) {
             return undefined;
         }
         if (mode === "confirm") {
+            notifyDesktop(ctx, config, `Waiting for you: allow this ${event.toolName} call? ${reasons}`);
             const allowed = await ctx.ui.confirm(`warden: allow this ${event.toolName} call?`, confirmMessage(verdict), ctx.signal ? { signal: ctx.signal } : {});
             if (allowed)
                 return undefined;
@@ -299,6 +363,7 @@ export default function wardenExtension(pi) {
         actionGuard.hold(task);
         if (ctx.hasUI)
             ctx.ui.notify(`warden · held ${event.toolName}: ${reasons}. The agent was told why and asked to re-plan or ask you.`, "warning");
+        notifyDesktop(ctx, config, `Held ${event.toolName}: ${reasons}. The agent will re-plan or ask you in chat.`);
         return { block: true, reason: told ?? steerReason(verdict, { canApprove: judge !== undefined }) };
     });
     pi.on("tool_result", async (event, ctx) => {
@@ -422,6 +487,16 @@ export default function wardenExtension(pi) {
         const config = configFor(ctx);
         if (!config.enabled)
             return;
+        if (pendingRunaway) {
+            const { nudge, recover } = pendingRunaway;
+            pendingRunaway = undefined;
+            // A follow-up queued here continues the run once the aborted message is in place; without recovery the note is appended only.
+            if (recover)
+                pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content: nudge, display: true }, { deliverAs: "followUp", triggerTurn: true });
+            else
+                pi.sendMessage({ customType: `${PACKAGE_NAME}-steer`, content: nudge, display: true }, { triggerTurn: false });
+            return;
+        }
         const finalMessage = finalAssistantText(event.messages);
         const judge = judgeFor(config);
         if (!finalMessage || !judge)
@@ -503,12 +578,13 @@ export default function wardenExtension(pi) {
                     const key = resolveApiKey();
                     const source = consentSource(config);
                     const usage = client?.getUsage();
-                    const guards = [config.action.enabled && "action", config.stuck.enabled && "stuck", config.done.enabled && "done-check", config.slop.enabled && "slop", config.slop.enabled && config.slop.prose.enabled && `prose (${config.slop.prose.audience})`, config.security.enabled && "security", config.context.enabled && "context"].filter(Boolean).join(", ");
+                    const guards = [config.action.enabled && "action", config.stuck.enabled && "stuck", config.done.enabled && "done-check", config.slop.enabled && "slop", config.slop.enabled && config.slop.prose.enabled && `prose (${config.slop.prose.audience})`, config.security.enabled && "security", config.context.enabled && "context", config.runaway.enabled && "runaway", config.notify.enabled && "desktop notifications"].filter(Boolean).join(", ");
                     report([
                         `pi-warden: ${config.enabled ? `guarding ${config.action.tools.join(", ")} (${guards})` : "off"}; mode ${activeMode(config, ctx.hasUI)}; TypeSafe judgments ${source ? `enabled via ${source}` : "disabled (run /warden enable)"}; key ${key ? key.source === "stored" ? "stored (shared with pi-typesafe)" : "from TYPESAFE_API_KEY" : "missing (run /warden enable)"}.`,
-                        `Session: ${stats.inspected} inspected, ${stats.judged} judged, ${stats.warned} warned, ${stats.held} held, ${stats.approved} approved on retry, ${stats.slop} slop notes, ${stats.stuck}/${stats.stuckChecks} stuck, ${stats.unverified}/${stats.doneChecks} unverified done, ${stats.proseNudges}/${stats.proseChecks} prose nudges, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests. Steers are ${config.steerVisible ? "shown in the transcript" : "hidden from the transcript (trace panel shows them)"}.`,
-                        `Thresholds: irreversible warn ${config.action.irreversible.warn} / hold ${config.action.irreversible.confirm}; off-task warn ${config.action.offTask.warn} / hold ${config.action.offTask.confirm}; stuck same-strategy ${config.stuck.sameStrategy} after ${config.stuck.minFailures} failures; done claims ${config.done.claimsDone}; slop ${config.slop.threshold}, prose ${config.slop.prose.threshold} in ${config.slop.prose.trend}/3 replies; failOpen ${config.action.failOpen}.`,
+                        `Session: ${stats.inspected} inspected, ${stats.judged} judged, ${stats.warned} warned, ${stats.held} held, ${stats.approved} approved on retry, ${stats.slop} slop notes, ${stats.stuck}/${stats.stuckChecks} stuck, ${stats.unverified}/${stats.doneChecks} unverified done, ${stats.proseNudges}/${stats.proseChecks} prose nudges, ${stats.runaway} runaway stops, ${stats.errors} TypeSafe errors; ${usage?.requestsStarted ?? 0}/${config.maxRequests} requests. Steers are ${config.steerVisible ? "shown in the transcript" : "hidden from the transcript (trace panel shows them)"}.`,
+                        `Thresholds: irreversible warn ${config.action.irreversible.warn} / hold ${config.action.irreversible.confirm}; off-task warn ${config.action.offTask.warn} / hold ${config.action.offTask.confirm}; stuck same-strategy ${config.stuck.sameStrategy} after ${config.stuck.minFailures} failures; done claims ${config.done.claimsDone}; slop ${config.slop.threshold}, prose ${config.slop.prose.threshold} in ${config.slop.prose.trend}/3 replies; runaway ${config.runaway.repeats} repeats (thinking ${config.runaway.thinkingRepeats}), recover ${config.runaway.recover}; failOpen ${config.action.failOpen}.`,
                         formatLedger(ledger.snapshot()),
+                        `Desktop notifications: ${config.notify.enabled ? `on (${config.notify.command.length ? `command ${config.notify.command[0]}` : (await (notifier ??= detectNotifier())) ?? "no notifier found on this machine"}; cooldown ${config.notify.cooldownMs} ms)` : "off"}.`,
                         `Config: ${userConfigPath()}${ctx.isProjectTrusted() ? ` and ${projectConfigPath(ctx.cwd)}` : ""}.`,
                         widget.size ? `Last: ${[...widget.values()].join(" | ")}` : "No guarded activity yet this session.",
                         `Trace: ${trace.entries().length} events (/warden trace${shortcut ? `, ${shortcut}` : ""}, or click the status line in fullscreen mode; each toggles the sidebar). Widget templates in config.widget: action tokens ${TOKEN_NAMES.action.map(name => `{${name}}`).join(" ")}.`,

package/dist/index.d.ts

@@ -16,15 +16,19 @@ export type { OutputFormat } from "./excerpt.js";
 export { detectSearchTool, recallInstruction, classifyRecall } from "./recall.js";
 export type { SearchTool } from "./recall.js";
 export { redact } from "./redact.js";
+export { detectNotifier, notifierCommand, sendNotification, candidates as notifierCandidates, clipBody } from "./notify.js";
+export type { NotifierName, NotifierTarget, Notification, NotifierCommand, Runner } from "./notify.js";
+export { RunawayMonitor, repeatedBlock, repeatedTail, findRepeats, runawayNudge, formatRunaway, BLOCK_MIN_CHARS, PHRASE_CHARS, CHECK_EVERY } from "./runaway.js";
+export type { RunawayVerdict, RepeatSignal, StreamKind } from "./runaway.js";
 export { completeConfig, shapeWarning, EXPECTED_SCHEMA } from "./shape.js";
 export { ContextLedger, formatLedger } from "./saver.js";
 export type { ContextLedgerSnapshot, RecallKind } from "./saver.js";
 export type { ShapeResult } from "./shape.js";
 export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
-export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, SecurityConfig, ContextConfig, RecallTool, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
+export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, SecurityConfig, ContextConfig, RunawayConfig, NotifyConfig, RecallTool, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
 export type { CommandView } from "./tools.js";
-export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
 export type { WidgetConfig, WidgetPlacement, Tokens } from "./widget.js";
-export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails } from "./trace.js";
+export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails } from "./trace.js";
 export type { TraceEntry, GuardName } from "./trace.js";

package/dist/index.js

@@ -8,9 +8,11 @@ export { evaluateOutput, buildOutputRequest, outputQuestions, compressOutput, sa
 export { formatExcerpt, formatQuestion } from "./excerpt.js";
 export { detectSearchTool, recallInstruction, classifyRecall } from "./recall.js";
 export { redact } from "./redact.js";
+export { detectNotifier, notifierCommand, sendNotification, candidates as notifierCandidates, clipBody } from "./notify.js";
+export { RunawayMonitor, repeatedBlock, repeatedTail, findRepeats, runawayNudge, formatRunaway, BLOCK_MIN_CHARS, PHRASE_CHARS, CHECK_EVERY } from "./runaway.js";
 export { completeConfig, shapeWarning, EXPECTED_SCHEMA } from "./shape.js";
 export { ContextLedger, formatLedger } from "./saver.js";
 export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, isRecallTool, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
-export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
-export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails } from "./trace.js";
+export { renderTemplate, actionTokens, stuckTokens, doneTokens, proseTokens, runawayTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails } from "./trace.js";

package/dist/notify.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Desktop notifications for the moments the user has to come back to the terminal: a held call the agent will ask
+ * about, a confirm dialog waiting for an answer, a stopped runaway. The notifier is detected once per session with a
+ * probe (never inside a tool_call handler); sending is fire-and-forget, and a failure is silent.
+ */
+export type NotifierName = "osascript" | "notify-send" | "dunstify" | "gdbus" | "kdialog" | "zenity" | "powershell" | "wsl-powershell";
+export interface Notification {
+    title: string;
+    body: string;
+}
+export interface NotifierCommand {
+    file: string;
+    args: string[];
+    /** Text travels in the environment where the shell needs no quoting (PowerShell). */
+    env?: Record<string, string>;
+}
+interface Candidate {
+    name: NotifierName;
+    /** Probe: the command exists and answers. */
+    probe: {
+        file: string;
+        args: readonly string[];
+    };
+}
+/** Platform order: the native route first, then the desktop-agnostic tools, then the shells that reach another desktop (WSL). */
+export declare function candidates(platform?: NodeJS.Platform): readonly Candidate[];
+/** A user-configured argv: `{title}` and `{body}` in any argument are replaced; the text is also in PI_WARDEN_TITLE / PI_WARDEN_BODY. */
+export type NotifierTarget = NotifierName | readonly string[];
+/** The command that shows one notification with the given tool. Text goes as arguments or environment, never through a shell. */
+export declare function notifierCommand(target: NotifierTarget, notification: Notification): NotifierCommand;
+export type Runner = (file: string, args: readonly string[], options: {
+    timeoutMs: number;
+    env?: Record<string, string>;
+}) => Promise<boolean>;
+/** Runs a command detached from the terminal; resolves to whether it exited cleanly. Never throws. */
+export declare const run: Runner;
+/** First notifier whose probe answers on this machine, or undefined when the desktop cannot be reached. */
+export declare function detectNotifier(platform?: NodeJS.Platform, runner?: Runner, timeoutMs?: number): Promise<NotifierName | undefined>;
+/** Notifications truncate around a hundred characters; keep the reason first. */
+export declare function clipBody(text: string, limit?: number): string;
+export declare function sendNotification(target: NotifierTarget, notification: Notification, runner?: Runner, timeoutMs?: number): Promise<boolean>;
+export {};

package/dist/notify.js

@@ -0,0 +1,99 @@
+import { execFile } from "node:child_process";
+/** Windows PowerShell's own AppUserModelId: a toast needs a registered application, and this one exists on every install. */
+const POWERSHELL_APP_ID = "{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe";
+const TOAST_SCRIPT = [
+    "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null",
+    "[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null",
+    "$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)",
+    "$text = $template.GetElementsByTagName('text')",
+    "$text.Item(0).AppendChild($template.CreateTextNode($env:PI_WARDEN_TITLE)) | Out-Null",
+    "$text.Item(1).AppendChild($template.CreateTextNode($env:PI_WARDEN_BODY)) | Out-Null",
+    "$toast = [Windows.UI.Notifications.ToastNotification]::new($template)",
+    `[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('${POWERSHELL_APP_ID}').Show($toast)`,
+].join("; ");
+/** Platform order: the native route first, then the desktop-agnostic tools, then the shells that reach another desktop (WSL). */
+export function candidates(platform = process.platform) {
+    const pwshProbe = ["-NoProfile", "-NonInteractive", "-Command", "exit 0"];
+    switch (platform) {
+        case "darwin":
+            return [{ name: "osascript", probe: { file: "osascript", args: ["-e", "return 0"] } }];
+        case "win32":
+            return [{ name: "powershell", probe: { file: "powershell", args: pwshProbe } }];
+        default:
+            return [
+                { name: "notify-send", probe: { file: "notify-send", args: ["--version"] } },
+                { name: "dunstify", probe: { file: "dunstify", args: ["--help"] } },
+                { name: "gdbus", probe: { file: "gdbus", args: ["help"] } },
+                { name: "kdialog", probe: { file: "kdialog", args: ["--version"] } },
+                { name: "zenity", probe: { file: "zenity", args: ["--version"] } },
+                // WSL: the Linux side has no notification daemon, but Windows PowerShell is on PATH and shows a toast.
+                { name: "wsl-powershell", probe: { file: "powershell.exe", args: pwshProbe } },
+            ];
+    }
+}
+/** AppleScript string literal: only backslash and double quote need escaping. */
+const appleScriptString = (text) => `"${text.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+/** GVariant string literal for gdbus: single quotes with backslash escapes. */
+const gvariantString = (text) => `'${text.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+/** The command that shows one notification with the given tool. Text goes as arguments or environment, never through a shell. */
+export function notifierCommand(target, notification) {
+    const { title, body } = notification;
+    if (typeof target !== "string") {
+        const [file = "", ...rest] = target;
+        return { file, args: rest.map(arg => arg.replaceAll("{title}", title).replaceAll("{body}", body)), env: { PI_WARDEN_TITLE: title, PI_WARDEN_BODY: body } };
+    }
+    switch (target) {
+        case "osascript":
+            return { file: "osascript", args: ["-e", `display notification ${appleScriptString(body)} with title ${appleScriptString(title)} sound name "Submarine"`] };
+        case "notify-send":
+            return { file: "notify-send", args: ["--app-name=pi-warden", "--urgency=critical", "--icon=dialog-warning", title, body] };
+        case "dunstify":
+            return { file: "dunstify", args: ["--appname=pi-warden", "--urgency=critical", title, body] };
+        case "gdbus":
+            return {
+                file: "gdbus",
+                args: ["call", "--session", "--dest", "org.freedesktop.Notifications", "--object-path", "/org/freedesktop/Notifications", "--method", "org.freedesktop.Notifications.Notify",
+                    "pi-warden", "0", "dialog-warning", gvariantString(title), gvariantString(body), "[]", "{'urgency': <byte 2>}", "-1"],
+            };
+        case "kdialog":
+            return { file: "kdialog", args: ["--title", title, "--passivepopup", body, "15"] };
+        case "zenity":
+            return { file: "zenity", args: ["--notification", `--text=${title}: ${body}`] };
+        case "powershell":
+        case "wsl-powershell":
+            return {
+                file: target === "powershell" ? "powershell" : "powershell.exe",
+                args: ["-NoProfile", "-NonInteractive", "-Command", TOAST_SCRIPT],
+                env: { PI_WARDEN_TITLE: title, PI_WARDEN_BODY: body },
+            };
+    }
+}
+/** Runs a command detached from the terminal; resolves to whether it exited cleanly. Never throws. */
+export const run = (file, args, options) => new Promise(resolve => {
+    try {
+        const env = options.env ? { ...process.env, ...options.env } : process.env;
+        execFile(file, [...args], { timeout: options.timeoutMs, windowsHide: true, maxBuffer: 64 * 1024, env }, error => resolve(!error));
+    }
+    catch {
+        resolve(false);
+    }
+});
+/** First notifier whose probe answers on this machine, or undefined when the desktop cannot be reached. */
+export async function detectNotifier(platform = process.platform, runner = run, timeoutMs = 3000) {
+    for (const candidate of candidates(platform)) {
+        if (await runner(candidate.probe.file, candidate.probe.args, { timeoutMs }))
+            return candidate.name;
+    }
+    return undefined;
+}
+/** Notifications truncate around a hundred characters; keep the reason first. */
+export function clipBody(text, limit = 180) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}…`;
+}
+export async function sendNotification(target, notification, runner = run, timeoutMs = 8000) {
+    const command = notifierCommand(target, { title: notification.title, body: clipBody(notification.body) });
+    if (!command.file)
+        return false;
+    return runner(command.file, command.args, { timeoutMs, ...(command.env ? { env: command.env } : {}) });
+}

package/dist/panel.js

@@ -1,5 +1,5 @@
 import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-const LEVEL_COLOR = { allow: "success", ok: "success", warn: "warning", unverified: "warning", nudged: "warning", confirm: "error", stuck: "error", "false claim": "error" };
+const LEVEL_COLOR = { allow: "success", ok: "success", warn: "warning", unverified: "warning", nudged: "warning", confirm: "error", stuck: "error", "false claim": "error", stopped: "error", "stopped, recovering": "error" };
 /**
  * Sidebar listing the trace newest-first, live-updating while open. It opens without taking keyboard input: the editor
  * keeps working while it is visible. A click inside it (fullscreen mode) focuses it; then ↑/↓/j/k scroll a line,

package/dist/runaway.d.ts

@@ -0,0 +1,66 @@
+import type { RunawayConfig } from "./config.js";
+/**
+ * Runaway guard: a model that degenerates mid-reply repeats the same block of text over and over without calling a tool,
+ * and nothing else stops it before the token limit. The guard reads the stream, counts identical blocks with code only,
+ * and stops the run when a block repeats past the threshold. No request leaves the machine.
+ *
+ * Calibration over 675 local sessions (2634 assistant text blocks of 300+ characters): the most repeated paragraph in an
+ * ordinary reply occurs twice at most; the one runaway repeated its block 28 times. Thinking drafts code and repeats
+ * paragraphs up to 7 times legitimately, so it has its own higher threshold.
+ */
+export type StreamKind = "text" | "thinking";
+export interface RepeatSignal {
+    count: number;
+    /** Normalised block that repeated; empty when nothing qualified. */
+    block: string;
+}
+export interface RunawayVerdict {
+    kind: StreamKind;
+    count: number;
+    block: string;
+    /** Characters streamed for this kind when the run was stopped. */
+    chars: number;
+    /** block: an identical paragraph; phrase: the text ends with one unit repeated back to back. */
+    signal: "block" | "phrase";
+}
+/** Paragraphs shorter than this (normalised) are ignored: code fences, list markers, and short labels repeat legitimately. */
+export declare const BLOCK_MIN_CHARS = 24;
+/** Length of the trailing phrase whose recurrence is counted. */
+export declare const PHRASE_CHARS = 60;
+/** Characters streamed between two checks; keeps the per-token cost to a string append. */
+export declare const CHECK_EVERY = 256;
+/** The paragraph (blank-line separated, normalised, at least `minChars`) that occurs most often. */
+export declare function repeatedBlock(text: string, minChars?: number): RepeatSignal;
+/**
+ * Run-on repetition without paragraph breaks: the text ends with one unit repeated back to back. The trailing `chars`
+ * locate the period (distance to their previous occurrence); the whole unit must match on every step back, so templated
+ * sentences that share only a suffix ("item 3 … see below.", "item 4 … see below.") count once. Units shorter than
+ * `minPeriod` (table separators, ellipses) are ignored.
+ */
+export declare function repeatedTail(text: string, chars?: number, minPeriod?: number): RepeatSignal;
+/** The stronger of the two signals for one stream. */
+export declare function findRepeats(text: string): RepeatSignal & {
+    signal: "block" | "phrase";
+};
+interface StreamEvent {
+    type: string;
+    delta?: string;
+}
+/** Follows one assistant message as it streams. `feed` is called per token and only appends; `check` runs every CHECK_EVERY characters. */
+export declare class RunawayMonitor {
+    private streams;
+    private stoppedKind;
+    reset(): void;
+    /** True once this message triggered a stop; later deltas from the same stream are ignored. */
+    get stopped(): boolean;
+    /** Text seen so far for one stream kind. */
+    streamed(kind: StreamKind): string;
+    /** Feeds one AssistantMessageEvent; returns the stream kind that has grown enough for a check, else undefined. */
+    feed(event: StreamEvent): StreamKind | undefined;
+    /** Judges one stream against the config; at most one verdict per message. */
+    check(kind: StreamKind, config: RunawayConfig): RunawayVerdict | undefined;
+}
+/** Follow-up for the agent after its run was stopped. `recover` true: this message starts the next turn. */
+export declare function runawayNudge(verdict: RunawayVerdict, recover: boolean): string;
+export declare function formatRunaway(verdict: RunawayVerdict, recovering: boolean, template?: string): string;
+export {};

package/dist/runaway.js

@@ -0,0 +1,115 @@
+import { DEFAULT_TEMPLATES, renderTemplate, runawayTokens } from "./widget.js";
+/** Paragraphs shorter than this (normalised) are ignored: code fences, list markers, and short labels repeat legitimately. */
+export const BLOCK_MIN_CHARS = 24;
+/** Length of the trailing phrase whose recurrence is counted. */
+export const PHRASE_CHARS = 60;
+/** Characters streamed between two checks; keeps the per-token cost to a string append. */
+export const CHECK_EVERY = 256;
+const normalise = (text) => text.replace(/\s+/g, " ").trim().toLowerCase();
+/** The paragraph (blank-line separated, normalised, at least `minChars`) that occurs most often. */
+export function repeatedBlock(text, minChars = BLOCK_MIN_CHARS) {
+    const counts = new Map();
+    let best = { count: 0, block: "" };
+    for (const raw of text.split(/\n\s*\n/)) {
+        const block = normalise(raw);
+        if (block.length < minChars)
+            continue;
+        const count = (counts.get(block) ?? 0) + 1;
+        counts.set(block, count);
+        if (count > best.count)
+            best = { count, block };
+    }
+    return best;
+}
+/**
+ * Run-on repetition without paragraph breaks: the text ends with one unit repeated back to back. The trailing `chars`
+ * locate the period (distance to their previous occurrence); the whole unit must match on every step back, so templated
+ * sentences that share only a suffix ("item 3 … see below.", "item 4 … see below.") count once. Units shorter than
+ * `minPeriod` (table separators, ellipses) are ignored.
+ */
+export function repeatedTail(text, chars = PHRASE_CHARS, minPeriod = BLOCK_MIN_CHARS) {
+    const normal = normalise(text);
+    if (normal.length < chars * 2)
+        return { count: 0, block: "" };
+    const start = normal.length - chars;
+    const phrase = normal.slice(start);
+    const previous = normal.lastIndexOf(phrase, start - 1);
+    if (previous === -1)
+        return { count: 1, block: phrase };
+    const period = start - previous;
+    if (period < minPeriod)
+        return { count: 1, block: phrase };
+    const unit = normal.slice(-period);
+    let count = 1;
+    for (let end = normal.length - period; end >= period && normal.slice(end - period, end) === unit; end -= period)
+        count++;
+    return { count, block: unit };
+}
+/** The stronger of the two signals for one stream. */
+export function findRepeats(text) {
+    const block = repeatedBlock(text);
+    const phrase = repeatedTail(text);
+    return block.count >= phrase.count ? { ...block, signal: "block" } : { ...phrase, signal: "phrase" };
+}
+const fresh = () => ({ text: { text: "", checkedAt: 0 }, thinking: { text: "", checkedAt: 0 } });
+/** Follows one assistant message as it streams. `feed` is called per token and only appends; `check` runs every CHECK_EVERY characters. */
+export class RunawayMonitor {
+    streams = fresh();
+    stoppedKind;
+    reset() {
+        this.streams = fresh();
+        this.stoppedKind = undefined;
+    }
+    /** True once this message triggered a stop; later deltas from the same stream are ignored. */
+    get stopped() {
+        return this.stoppedKind !== undefined;
+    }
+    /** Text seen so far for one stream kind. */
+    streamed(kind) {
+        return this.streams[kind].text;
+    }
+    /** Feeds one AssistantMessageEvent; returns the stream kind that has grown enough for a check, else undefined. */
+    feed(event) {
+        if (event.type === "start") {
+            this.reset();
+            return undefined;
+        }
+        const kind = event.type.startsWith("text_") ? "text" : event.type.startsWith("thinking_") ? "thinking" : undefined;
+        if (!kind)
+            return undefined;
+        const stream = this.streams[kind];
+        if (event.type.endsWith("_start")) {
+            if (stream.text)
+                stream.text += "\n\n";
+            return undefined;
+        }
+        if (!event.type.endsWith("_delta") || typeof event.delta !== "string")
+            return undefined;
+        stream.text += event.delta;
+        return stream.text.length - stream.checkedAt >= CHECK_EVERY ? kind : undefined;
+    }
+    /** Judges one stream against the config; at most one verdict per message. */
+    check(kind, config) {
+        const stream = this.streams[kind];
+        stream.checkedAt = stream.text.length;
+        if (this.stoppedKind || stream.text.length < config.minChars)
+            return undefined;
+        const limit = kind === "text" ? config.repeats : config.thinkingRepeats;
+        const found = findRepeats(stream.text);
+        if (found.count < limit)
+            return undefined;
+        this.stoppedKind = kind;
+        return { kind, count: found.count, block: found.block, chars: stream.text.length, signal: found.signal };
+    }
+}
+const clip = (text, limit) => (text.length <= limit ? text : `${text.slice(0, limit)}…`);
+/** Follow-up for the agent after its run was stopped. `recover` true: this message starts the next turn. */
+export function runawayNudge(verdict, recover) {
+    const what = `pi-warden stopped your reply: the same ${verdict.kind} block repeated ${verdict.count} times ("${clip(verdict.block, 80)}") and no tool was called.`;
+    if (!recover)
+        return `${what} The run was stopped again for this prompt and was not restarted. Wait for the user.`;
+    return `${what} Do not restate what you are about to do. If a command is the next step, call the tool with it now. Otherwise answer in at most three sentences: the current state and the one next action, or a question for the user.`;
+}
+export function formatRunaway(verdict, recovering, template = DEFAULT_TEMPLATES.runaway) {
+    return renderTemplate(template, runawayTokens(verdict, recovering));
+}

package/dist/shape.d.ts

@@ -1,6 +1,6 @@
 import type { WardenConfig } from "./config.js";
 /** The config layout this extension build expects; compared with the loaded config module's CONFIG_SCHEMA. */
-export declare const EXPECTED_SCHEMA = 3;
+export declare const EXPECTED_SCHEMA = 4;
 export interface ShapeResult {
     config: WardenConfig;
     /** Sections that were absent from the loaded config and are now disabled. Empty when the config was complete. */

package/dist/shape.js

@@ -1,6 +1,7 @@
 import { isMode } from "./config.js";
+import { DEFAULT_TEMPLATES } from "./widget.js";
 /** The config layout this extension build expects; compared with the loaded config module's CONFIG_SCHEMA. */
-export const EXPECTED_SCHEMA = 3;
+export const EXPECTED_SCHEMA = 4;
 const off = { enabled: false };
 const proseOff = () => ({ ...off, audience: "technical", threshold: 1, trend: 3, minChars: 1 });
 /**
@@ -31,7 +32,9 @@ export function completeConfig(loaded) {
         slop: section("slop", { ...off, threshold: 1, prose: proseOff() }),
         security: section("security", { ...off, threshold: 1 }),
         context: section("context", { ...off, tailMinChars: 1, confidence: 1, duplicateMinChars: Number.MAX_SAFE_INTEGER, recallTool: "none", formatConfidence: 1 }),
-        widget: section("widget", { ...off, placement: "aboveEditor", shortcut: "", panelWidth: "40%", action: "", stuck: "", done: "", prose: "", security: "", context: "" }),
+        runaway: section("runaway", { ...off, repeats: Number.MAX_SAFE_INTEGER, thinkingRepeats: Number.MAX_SAFE_INTEGER, minChars: Number.MAX_SAFE_INTEGER, recover: false }),
+        notify: section("notify", { ...off, cooldownMs: 0, command: [] }),
+        widget: section("widget", { ...off, placement: "aboveEditor", shortcut: "", panelWidth: "40%", action: "", stuck: "", done: "", prose: "", security: "", context: "", runaway: "" }),
     };
     if (typeof config.slop.prose !== "object" || config.slop.prose === null) {
         missing.push("slop.prose");
@@ -44,6 +47,9 @@ export function completeConfig(loaded) {
     }
     if (typeof config.widget.panelWidth !== "string" && typeof config.widget.panelWidth !== "number")
         config.widget = { ...config.widget, panelWidth: "40%" };
+    // The runaway guard added its template later than the other sections; an older widget section renders the default line.
+    if (typeof config.widget.runaway !== "string")
+        config.widget = { ...config.widget, runaway: DEFAULT_TEMPLATES.runaway };
     return { config, missing };
 }
 export function shapeWarning(missing, loadedSchema) {

package/dist/trace.d.ts

@@ -1,8 +1,9 @@
 import type { DoneVerdict } from "./done.js";
 import type { Verdict } from "./guard.js";
 import type { ProseVerdict } from "./prose.js";
+import type { RunawayVerdict } from "./runaway.js";
 import type { Attempt, StuckVerdict } from "./stuck.js";
-export type GuardName = "action" | "stuck" | "done" | "prose" | "security" | "context";
+export type GuardName = "action" | "stuck" | "done" | "prose" | "security" | "context" | "runaway";
 export interface TraceEntry {
     at: number;
     guard: GuardName;
@@ -28,4 +29,5 @@ export declare function actionDetails(verdict: Verdict, extra?: {
 }): string[];
 export declare function stuckDetails(verdict: StuckVerdict, attempts: readonly Attempt[], told?: string): string[];
 export declare function doneDetails(verdict: DoneVerdict, finalMessage: string, told?: string): string[];
+export declare function runawayDetails(verdict: RunawayVerdict, told: string | undefined, recovering: boolean): string[];
 export declare function proseDetails(verdict: ProseVerdict, reply: string, audience: string, told?: string): string[];

package/dist/trace.js

@@ -81,6 +81,16 @@ export function doneDetails(verdict, finalMessage, told) {
         lines.push(`agent told: ${clip(told, 400)}`);
     return lines;
 }
+export function runawayDetails(verdict, told, recovering) {
+    const lines = [
+        `repeated: ${clip(verdict.block, 200)}`,
+        `${verdict.count} times in ${verdict.chars} chars of ${verdict.kind}; signal: ${verdict.signal === "block" ? "identical paragraph" : "recurring trailing phrase"}`,
+        recovering ? "run stopped; one follow-up turn started" : "run stopped; not restarted",
+    ];
+    if (told)
+        lines.push(`agent told: ${clip(told, 400)}`);
+    return lines;
+}
 export function proseDetails(verdict, reply, audience, told) {
     const lines = [`reply: ${clip(reply.replace(/\s+/g, " "), 300)}`, `audience: ${audience}`];
     if (verdict.scores)

package/dist/widget.d.ts

@@ -1,6 +1,7 @@
 import type { DoneVerdict } from "./done.js";
 import type { Verdict } from "./guard.js";
 import type { ProseVerdict } from "./prose.js";
+import type { RunawayVerdict } from "./runaway.js";
 import type { StuckVerdict } from "./stuck.js";
 export type WidgetPlacement = "aboveEditor" | "belowEditor";
 export interface WidgetConfig {
@@ -17,6 +18,7 @@ export interface WidgetConfig {
     prose: string;
     security: string;
     context: string;
+    runaway: string;
 }
 export declare const DEFAULT_TEMPLATES: {
     readonly action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop: {slop} · patterns: {patterns} · {flags} · {level}";
@@ -25,6 +27,7 @@ export declare const DEFAULT_TEMPLATES: {
     readonly prose: "warden · prose · wordy {wordy} · clichés {cliches} · jargon {jargon} · {flags} · {status}";
     readonly security: "warden · security · {tool} · injection {injection} · exfiltration {exfiltration} · {status}";
     readonly context: "warden · context · {tool} · {retention} · saved {bytesSaved} bytes";
+    readonly runaway: "warden · runaway · {kind} · {count}× repeated · {chars} chars · {signal} · {status}";
 };
 export declare function defaultWidgetConfig(): WidgetConfig;
 export type Tokens = Record<string, string | undefined>;
@@ -35,12 +38,14 @@ export type Tokens = Record<string, string | undefined>;
 export declare function renderTemplate(template: string, tokens: Tokens): string;
 export declare function actionTokens(verdict: Verdict, at?: number): Tokens;
 export declare function stuckTokens(verdict: StuckVerdict, at?: number): Tokens;
+export declare function runawayTokens(verdict: RunawayVerdict, recovering: boolean, at?: number): Tokens;
 export declare function doneTokens(verdict: DoneVerdict, at?: number): Tokens;
 export declare function proseTokens(verdict: ProseVerdict, at?: number): Tokens;
 /** Token names users can put in templates, for /warden status and the README. */
 export declare const TOKEN_NAMES: {
     readonly security: readonly ["tool", "injection", "exfiltration", "status"];
     readonly context: readonly ["tool", "retention", "bytesSaved"];
+    readonly runaway: readonly ["kind", "count", "chars", "signal", "block", "status", "time", "guard"];
     readonly action: readonly ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slop", "slopStub", "slopComments", "slopDead", "slopHedging", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"];
     readonly prose: readonly ["wordy", "cliches", "jargon", "status", "reasons", "model", "ms", "flags", "time", "guard"];
     readonly stuck: readonly ["failures", "sameStrategy", "approachChange", "progress", "status", "source", "reasons", "model", "ms", "flags", "time", "guard"];

package/dist/widget.js

@@ -5,6 +5,7 @@ export const DEFAULT_TEMPLATES = {
     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",
+    runaway: "warden · runaway · {kind} · {count}× repeated · {chars} chars · {signal} · {status}",
 };
 export function defaultWidgetConfig() {
     return { enabled: true, placement: "aboveEditor", shortcut: "ctrl+shift+w", panelWidth: "40%", ...DEFAULT_TEMPLATES };
@@ -81,6 +82,18 @@ export function stuckTokens(verdict, at = Date.now()) {
         flags: flags || undefined,
     };
 }
+export function runawayTokens(verdict, recovering, at = Date.now()) {
+    return {
+        guard: "runaway",
+        time: time(at),
+        kind: verdict.kind,
+        count: String(verdict.count),
+        chars: String(verdict.chars),
+        signal: verdict.signal,
+        block: verdict.block,
+        status: recovering ? "stopped, recovering" : "stopped",
+    };
+}
 export function doneTokens(verdict, at = Date.now()) {
     return {
         guard: "done",
@@ -117,6 +130,7 @@ export function proseTokens(verdict, at = Date.now()) {
 export const TOKEN_NAMES = {
     security: ["tool", "injection", "exfiltration", "status"],
     context: ["tool", "retention", "bytesSaved"],
+    runaway: ["kind", "count", "chars", "signal", "block", "status", "time", "guard"],
     action: ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slop", "slopStub", "slopComments", "slopDead", "slopHedging", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"],
     prose: ["wordy", "cliches", "jargon", "status", "reasons", "model", "ms", "flags", "time", "guard"],
     stuck: ["failures", "sameStrategy", "approachChange", "progress", "status", "source", "reasons", "model", "ms", "flags", "time", "guard"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-warden",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Guardrails for Pi built on pi-typesafe that steer the agent instead of interrupting you: Jev judges irreversible and off-task tool calls before they run, detects stuck loops, checks unverified done claims, and flags slop.",
   "type": "module",
   "license": "MIT",