pi-warden 0.6.0 → 0.8.0

package/dist/recall.d.ts

@@ -0,0 +1,13 @@
+import type { RecallTool } from "./config.js";
+/**
+ * A recall is the agent going back to a stored full output. A whole-file read undoes the saving; a scoped search or a
+ * ranged read keeps it. The footer under every excerpt names a search command that exists on this machine, detected
+ * once at load. Detection never runs inside a tool_result handler.
+ */
+export type SearchTool = Exclude<RecallTool, "auto">;
+/** First working tool in the chain, or `none`. A configured tool other than `auto` is trusted without a probe. */
+export declare function detectSearchTool(configured?: RecallTool, timeoutMs?: number): Promise<SearchTool>;
+/** Footer under an excerpt or duplicate note. Tells the agent how to get a part back without re-reading everything. */
+export declare function recallInstruction(tool: SearchTool, path: string): string;
+/** `full` when the call loads the entire stored file into context; `scoped` for searches, ranged reads, and sandboxed processing. */
+export declare function classifyRecall(toolName: string, input: unknown, path: string): "full" | "scoped";

package/dist/recall.js

@@ -0,0 +1,68 @@
+import { execFile } from "node:child_process";
+/** Fastest first; the last entries cover Windows shells. */
+const CHAIN = [
+    { tool: "rg", command: "rg", args: ["--version"] },
+    { tool: "ag", command: "ag", args: ["--version"] },
+    { tool: "ugrep", command: "ugrep", args: ["--version"] },
+    { tool: "git-grep", command: "git", args: ["--version"] },
+    { tool: "grep", command: "grep", args: ["--version"] },
+    { tool: "select-string", command: process.platform === "win32" ? "powershell" : "pwsh", args: ["-NoProfile", "-NonInteractive", "-Command", "exit 0"] },
+    { tool: "findstr", command: "where.exe", args: ["findstr"] },
+];
+function available(command, args, timeoutMs) {
+    return new Promise(resolve => {
+        try {
+            execFile(command, [...args], { timeout: timeoutMs, windowsHide: true, maxBuffer: 64 * 1024 }, error => resolve(!error));
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/** First working tool in the chain, or `none`. A configured tool other than `auto` is trusted without a probe. */
+export async function detectSearchTool(configured = "auto", timeoutMs = 1500) {
+    if (configured !== "auto")
+        return configured;
+    for (const entry of CHAIN) {
+        if (entry.tool === "findstr" && process.platform !== "win32")
+            continue;
+        if (await available(entry.command, entry.args, timeoutMs))
+            return entry.tool;
+    }
+    return "none";
+}
+function searchExample(tool, path) {
+    switch (tool) {
+        case "rg": return `rg -n -C 3 '<pattern>' '${path}'`;
+        case "ag": return `ag -C 3 '<pattern>' '${path}'`;
+        case "ugrep": return `ugrep -n -C 3 '<pattern>' '${path}'`;
+        case "git-grep": return `git grep --no-index -n -C 3 '<pattern>' -- '${path}'`;
+        case "grep": return `grep -n -C 3 -E '<pattern>' '${path}'`;
+        case "select-string": return `Select-String -Path '${path}' -Pattern '<pattern>' -Context 3`;
+        case "findstr": return `findstr /n /c:"<pattern>" "${path}"`;
+        case "none": return undefined;
+    }
+}
+/** Footer under an excerpt or duplicate note. Tells the agent how to get a part back without re-reading everything. */
+export function recallInstruction(tool, path) {
+    const example = searchExample(tool, path);
+    const how = example ? `search it (${example}) or read a known region with offset and limit` : "read a known region with offset and limit";
+    return `Full output: ${path}\nTo recall a part, ${how}. Do not read the whole file.`;
+}
+/** `full` when the call loads the entire stored file into context; `scoped` for searches, ranged reads, and sandboxed processing. */
+export function classifyRecall(toolName, input, path) {
+    const record = typeof input === "object" && input !== null ? input : {};
+    if (toolName === "read")
+        return typeof record.offset === "number" || typeof record.limit === "number" ? "scoped" : "full";
+    const command = typeof record.command === "string" ? record.command : typeof record.code === "string" ? record.code : undefined;
+    if (!command)
+        return "scoped";
+    // The pipeline segment that names the path decides: a bare cat/type/Get-Content dumps everything; anything else scopes it.
+    for (const segment of command.split(/&&|\|\||[;|]|\n/)) {
+        if (!segment.includes(path))
+            continue;
+        if (/^\s*(?:cat|type|Get-Content|gc)\b/.test(segment) && !/\s-(?:TotalCount|Head|Tail)\b/i.test(segment))
+            return "full";
+    }
+    return "scoped";
+}

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/saver.d.ts

@@ -1,35 +1,52 @@
 /**
  * Session accounting for the context saver, so its value can be measured instead of assumed:
- * how often large outputs appear, how many were compressed, how much was removed, how many turns that removal was
- * spared from (token-turns), and how often the agent went back for the full text (a recall means the excerpt was
- * not enough). Deterministic; no requests.
+ * how often large outputs appear, how many were compressed or dropped as duplicates, how much was removed, how many
+ * turns that removal was spared from (token-turns), and how often the agent went back for the full text. A recall means
+ * the excerpt was not enough; a whole-file recall also undoes the saving, a scoped one keeps it. Deterministic; no requests.
  */
 export interface ContextLedgerSnapshot {
     /** Single-text-block outputs at or above tailMinChars, i.e. candidates for compression. */
     large: number;
     compressed: number;
+    /** Results replaced by a duplicate note because an identical result already exists in this session. */
+    duplicates: number;
     bytesSaved: number;
     /** Assistant turns completed since the session started. */
     turns: number;
     /** Sum over turns of the bytes that were no longer in context on that turn, in rough tokens (bytes / 4). */
     tokenTurnsSaved: number;
-    /** Times the agent read a stored full output after compression. */
+    /** Times the agent went back to a stored full output after compression, by kind of access. */
     recalls: number;
+    recallsFull: number;
 }
+export type RecallKind = "full" | "scoped";
 export declare class ContextLedger {
     private large;
     private compressed;
+    private duplicates;
     private bytesSaved;
     private turns;
     private tokenTurnsSaved;
     private recalls;
+    private recallsFull;
     private readonly stored;
+    /** Every sizeable text result seen this session, by content key, with the tool that produced it and its stored copy if any. */
+    private readonly seen;
     candidate(): void;
     record(path: string, bytesSaved: number): void;
+    /** Remember a result's identity so a later identical result can be dropped. `path` is set when a full copy exists. */
+    remember(key: string, tool: string, path?: string): void;
+    duplicateOf(key: string): {
+        tool: string;
+        path?: string;
+    } | undefined;
+    duplicate(bytesSaved: number): void;
     /** One LLM turn finished: everything removed so far was absent from this turn's prompt. */
     turnEnd(): void;
-    /** True when `text` (a path, command, or serialized input) mentions a stored full output for the first time. */
-    noteAccess(text: string): string | undefined;
+    /** The stored path that `text` (a path, command, or serialized input) mentions, if any. */
+    storedPathIn(text: string): string | undefined;
+    /** Counts the first access to a compressed output; later accesses and duplicate-only copies are not new recalls. */
+    noteAccess(text: string, kind?: RecallKind): string | undefined;
     snapshot(): ContextLedgerSnapshot;
     reset(): void;
 }

package/dist/saver.js

@@ -1,11 +1,19 @@
+/** Serialized tool input escapes backslashes, so a Windows path must also match in its JSON form. */
+function mentions(text, path) {
+    return text.includes(path) || text.includes(JSON.stringify(path).slice(1, -1));
+}
 export class ContextLedger {
     large = 0;
     compressed = 0;
+    duplicates = 0;
     bytesSaved = 0;
     turns = 0;
     tokenTurnsSaved = 0;
     recalls = 0;
+    recallsFull = 0;
     stored = new Map();
+    /** Every sizeable text result seen this session, by content key, with the tool that produced it and its stored copy if any. */
+    seen = new Map();
     candidate() {
         this.large++;
     }
@@ -14,42 +22,72 @@ export class ContextLedger {
         this.bytesSaved += bytesSaved;
         this.stored.set(path, { recalled: false });
     }
+    /** Remember a result's identity so a later identical result can be dropped. `path` is set when a full copy exists. */
+    remember(key, tool, path) {
+        const existing = this.seen.get(key);
+        if (existing && existing.path && !path)
+            return;
+        this.seen.set(key, path ? { tool, path } : { tool });
+    }
+    duplicateOf(key) {
+        return this.seen.get(key);
+    }
+    duplicate(bytesSaved) {
+        this.duplicates++;
+        this.bytesSaved += bytesSaved;
+    }
     /** One LLM turn finished: everything removed so far was absent from this turn's prompt. */
     turnEnd() {
         this.turns++;
         this.tokenTurnsSaved += Math.round(this.bytesSaved / 4);
     }
-    /** True when `text` (a path, command, or serialized input) mentions a stored full output for the first time. */
-    noteAccess(text) {
+    /** The stored path that `text` (a path, command, or serialized input) mentions, if any. */
+    storedPathIn(text) {
+        for (const path of this.stored.keys())
+            if (mentions(text, path))
+                return path;
+        for (const entry of this.seen.values())
+            if (entry.path && mentions(text, entry.path))
+                return entry.path;
+        return undefined;
+    }
+    /** Counts the first access to a compressed output; later accesses and duplicate-only copies are not new recalls. */
+    noteAccess(text, kind = "full") {
         for (const [path, state] of this.stored) {
-            if (!text.includes(path))
+            if (!mentions(text, path))
                 continue;
             if (!state.recalled) {
                 state.recalled = true;
                 this.recalls++;
+                if (kind === "full")
+                    this.recallsFull++;
             }
             return path;
         }
         return undefined;
     }
     snapshot() {
-        return { large: this.large, compressed: this.compressed, bytesSaved: this.bytesSaved, turns: this.turns, tokenTurnsSaved: this.tokenTurnsSaved, recalls: this.recalls };
+        return { large: this.large, compressed: this.compressed, duplicates: this.duplicates, bytesSaved: this.bytesSaved, turns: this.turns, tokenTurnsSaved: this.tokenTurnsSaved, recalls: this.recalls, recallsFull: this.recallsFull };
     }
     reset() {
         this.large = 0;
         this.compressed = 0;
+        this.duplicates = 0;
         this.bytesSaved = 0;
         this.turns = 0;
         this.tokenTurnsSaved = 0;
         this.recalls = 0;
+        this.recallsFull = 0;
         this.stored.clear();
+        this.seen.clear();
     }
 }
 /** One line for /warden status. Says when there is nothing to report instead of printing zeros. */
 export function formatLedger(snapshot) {
-    if (snapshot.large === 0)
+    if (snapshot.large === 0 && snapshot.duplicates === 0)
         return "Context saver: no tool output large enough to consider this session.";
     const kb = (snapshot.bytesSaved / 1024).toFixed(1);
     const recallRate = snapshot.compressed ? Math.round((snapshot.recalls / snapshot.compressed) * 100) : 0;
-    return `Context saver: ${snapshot.large} large outputs, ${snapshot.compressed} compressed, ${kb} KB removed (~${Math.round(snapshot.bytesSaved / 4)} tokens), ~${snapshot.tokenTurnsSaved} token-turns spared over ${snapshot.turns} turns, ${snapshot.recalls} recall${snapshot.recalls === 1 ? "" : "s"} of the full output (${recallRate}%).`;
+    const scoped = snapshot.recalls - snapshot.recallsFull;
+    return `Context saver: ${snapshot.large} large outputs, ${snapshot.compressed} compressed, ${snapshot.duplicates} duplicate${snapshot.duplicates === 1 ? "" : "s"} dropped, ${kb} KB removed (~${Math.round(snapshot.bytesSaved / 4)} tokens), ~${snapshot.tokenTurnsSaved} token-turns spared over ${snapshot.turns} turns, ${snapshot.recalls} recall${snapshot.recalls === 1 ? "" : "s"} of the full output (${recallRate}%; ${snapshot.recallsFull} whole-file, ${scoped} scoped).`;
 }

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 });
 /**
@@ -30,15 +31,25 @@ export function completeConfig(loaded) {
         done: section("done", { ...off, claimsDone: 1, nudge: false }),
         slop: section("slop", { ...off, threshold: 1, prose: proseOff() }),
         security: section("security", { ...off, threshold: 1 }),
-        context: section("context", { ...off, tailMinChars: 1, confidence: 1 }),
-        widget: section("widget", { ...off, placement: "aboveEditor", shortcut: "", panelWidth: "40%", action: "", stuck: "", done: "", prose: "", security: "", context: "" }),
+        context: section("context", { ...off, tailMinChars: 1, confidence: 1, duplicateMinChars: Number.MAX_SAFE_INTEGER, recallTool: "none", formatConfidence: 1 }),
+        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");
         config.slop = { ...config.slop, prose: proseOff() };
     }
+    // 0.7 added fields inside the context section; an older config module leaves them undefined.
+    if (typeof config.context.duplicateMinChars !== "number" || typeof config.context.formatConfidence !== "number" || typeof config.context.recallTool !== "string") {
+        missing.push("context.saver");
+        config.context = { ...config.context, duplicateMinChars: Number.MAX_SAFE_INTEGER, recallTool: "none", formatConfidence: 1 };
+    }
     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.6.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",