pi-warden 0.34.1 → 0.36.0

package/CHANGELOG.md

@@ -8,6 +8,19 @@ How to keep this current: add the entry in the same pull request as the change,
 
 <!-- Empty. Next release starts here. -->
 
+## 0.36.0
+
+### Changed
+- The resolved rules file content no longer rides the action request when the rules guard is off. `rules.enabled: false` now means no rules file content leaves the machine at all; with the guard on, the request is unchanged. `EvaluateOptions.rules` and `InspectOptions.rules` carry the switch, and a library caller that omits it keeps the earlier behaviour. The disclosure and `docs/data-handling.md` say so.
+
+### Docs
+- `docs/configuration.md`: `Recipe: security work` — what each guard sends off the machine and what `/warden disable` leaves behind, a local-only user profile, a lab/CTF project profile with the exemptions security work needs, and an out-of-scope deny rule. README privacy paragraph points to it.
+
+## 0.35.0
+
+### Added
+- Stuck-loop diff: when the stuck detector marks a repeated failed attempt, the agent sees a short unified line diff against the previous output instead of the full repeated output again. Byte-identical outputs get a one-line note. The diff note never grows the result. Config keys `stuck.diffLimit` (3000) and `stuck.tailLimit` (1000) control the diff and tail caps.
+
 ## 0.34.1
 
 ### Fixed

package/README.md

@@ -82,7 +82,7 @@ These are project-maintained benchmarks, not universal claims. Raw reports and r
 
 ## Privacy
 
-Depending on the configured judgment backend, Warden sends to your provider: a redacted summary of each guarded call, the agent's plan, up to eight redacted prior messages, and redacted tool-output samples. Secrets are stripped before anything leaves the machine. [Full details.](docs/data-handling.md)
+Depending on the configured judgment backend, Warden sends to your provider: a redacted summary of each guarded call, the agent's plan, up to eight redacted prior messages, and redacted tool-output samples. Secrets are stripped before anything leaves the machine. [Full details.](docs/data-handling.md) Security work — pentesting, incident response, CTF — has its own configuration recipe for keeping samples local and for the friction that credentials and lab setups cause: [Recipe: security work](docs/configuration.md#recipe-security-work).
 
 ## Documentation
 

package/dist/action-guard.d.ts

@@ -1,4 +1,4 @@
-import type { ActionGuardConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
+import type { ActionGuardConfig, RulesConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
 import type { PreviousAction, TaskMessage, Verdict } from "./guard.js";
 import type { Judge } from "pi-typesafe";
 /** One tool call as the agent proposed it. `id` is Pi's tool call id, stable across hooks and retries. */
@@ -25,6 +25,8 @@ export interface InspectOptions {
     signal?: AbortSignal | undefined;
     slop?: SlopGuardConfig | undefined;
     security?: SecurityConfig | undefined;
+    /** The rules guard's switch; off keeps the rules file content out of the action request. Omitted, it is sent as before. */
+    rules?: Pick<RulesConfig, "enabled"> | undefined;
     /** Calls allowed in the previous turn; the regret question about them rides this call's request, never a sibling's. */
     previousActions?: readonly PreviousAction[] | undefined;
 }

package/dist/action-guard.js

@@ -20,7 +20,7 @@ export class ActionGuard {
         const { task } = conversation;
         // A hold happened under an earlier prompt and the user has since replied: ask whether the reply approves this action.
         const retryAfterHold = this.holdPending && this.lastHoldPrompt !== task;
-        const judgeCall = (tool, input, previousActions) => evaluateAction({ tool, input, cwd: options.cwd, task, context: conversation.context, plan: conversation.plan }, { config: options.config, judge: options.judge, signal: options.signal, slop: options.slop, security: options.security, retryAfterHold, previousActions });
+        const judgeCall = (tool, input, previousActions) => evaluateAction({ tool, input, cwd: options.cwd, task, context: conversation.context, plan: conversation.plan }, { config: options.config, judge: options.judge, signal: options.signal, slop: options.slop, security: options.security, rules: options.rules, retryAfterHold, previousActions });
         // A retry after a hold stays sequential because an approval consumed by one sibling changes the question for the next.
         if (options.judge && !retryAfterHold) {
             for (const sibling of conversation.siblings ?? []) {

package/dist/config.d.ts

@@ -127,6 +127,10 @@ export interface StuckGuardConfig {
     churnThreshold: number;
     /** Also steer the agent with a short message, not only the user. */
     nudge: boolean;
+    /** Maximum characters of the unified line diff in a stuck-loop diff note. */
+    diffLimit: number;
+    /** Characters of the current output tail shown after the diff in a stuck-loop diff note. */
+    tailLimit: number;
 }
 export interface DoneGuardConfig {
     enabled: boolean;

package/dist/config.js

@@ -39,7 +39,7 @@ export function defaultConfig() {
             escalationThreshold: 0.85,
             floor: "evidence",
         },
-        stuck: { enabled: true, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 0.7, churnThreshold: 5, nudge: true },
+        stuck: { enabled: true, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 0.7, churnThreshold: 5, nudge: true, diffLimit: 3000, tailLimit: 1000 },
         done: { enabled: true, claimsDone: 0.7, nudge: true },
         slop: { enabled: true, threshold: 0.7, prose: { enabled: true, audience: "technical", threshold: 0.7, trend: 2, minChars: 200 } },
         security: { enabled: true, threshold: 0.7 },
@@ -284,6 +284,8 @@ function applyStuck(base, raw) {
         sameStrategy: probability(raw.sameStrategy, base.sameStrategy),
         churnThreshold: Math.min(window, positiveInteger(raw.churnThreshold, base.churnThreshold)),
         nudge: boolean(raw.nudge, base.nudge),
+        diffLimit: positiveInteger(raw.diffLimit, base.diffLimit),
+        tailLimit: positiveInteger(raw.tailLimit, base.tailLimit),
     };
 }
 function applyRunaway(base, raw) {

package/dist/extension.d.ts

@@ -2,7 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import type { ToolCallRef } from "./action-guard.js";
 import type { SlopSymptom, Verdict } from "./guard.js";
 import type { ShapeResult } from "./shape.js";
-export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs, with the agent's own words from the message that makes the call (its stated plan); the resolved active rules file content (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback, token-aware truncated at ~4000 tokens) sent with every action request, including calls where the rules guard is disabled; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; 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; redacted tool-output samples for security and context saving (retention and output format); a redacted sample of an async subagent report that names a failure, a stop, or a question, with your latest request, when warden decides whether that report should wake the agent; and, on the first guarded call after your reply, the redacted summaries of the calls allowed in the previous turn, so Jev can say whether your reply regrets one of them. Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine; the hold feedback log stores tool names, pattern ids, scores, and outcomes (never commands) in an owner-only file under Pi's agent directory; an owner-only SQLite database under Pi's agent directory stores redacted hold context (plan, summary, redacted command preview, outcomes) for held and judged-allowed calls, for learning and retention (configurable, default 365 days). Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
+export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs, with the agent's own words from the message that makes the call (its stated plan); the resolved active rules file content (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback, token-aware truncated at ~4000 tokens) sent with every action request unless the rules guard is off (`rules.enabled: false`), which keeps that content on this machine; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; 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; redacted tool-output samples for security and context saving (retention and output format); a redacted sample of an async subagent report that names a failure, a stop, or a question, with your latest request, when warden decides whether that report should wake the agent; and, on the first guarded call after your reply, the redacted summaries of the calls allowed in the previous turn, so Jev can say whether your reply regrets one of them. Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine; the hold feedback log stores tool names, pattern ids, scores, and outcomes (never commands) in an owner-only file under Pi's agent directory; an owner-only SQLite database under Pi's agent directory stores redacted hold context (plan, summary, redacted command preview, outcomes) for held and judged-allowed calls, for learning and retention (configurable, default 365 days). Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 /** Which guard spent the user's attention. The status line reports one count per guard. */
 export type SteerGuard = "action" | "rules" | "security" | "stuck" | "done" | "prose" | "runaway" | "subagent";
 /**

package/dist/extension.js

@@ -25,14 +25,14 @@ import { writeStarterRules, buildInitPrompt } from "./init.js";
 import { buildAuditPrompt, findProjects, snapshotReport, reportOutcome } from "./audit.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 { AttemptWindow, evaluateStuck, formatStuck, makeAttempt, resultFailed, stuckDiff, stuckNudge } from "./stuck.js";
 import { openConfigPanel, openTracePanel } from "./panel.js";
 import { completeConfig, shapeWarning } from "./shape.js";
 import { ContextLedger, formatLedger } from "./saver.js";
 import { formatWake, newReports, reportLabel, triageReport, WakePolicy } from "./subagent.js";
 import { actionDetails, doneDetails, proseDetails, rulesDetails, runawayDetails, stuckDetails, Trace } from "./trace.js";
 import { actionTokens, DEFAULT_TEMPLATES, LEVEL_COLOR, pickSentenceTemplate, proseTokens, renderTemplate, SENTENCE_TEMPLATES, statusWidget, 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, with the agent's own words from the message that makes the call (its stated plan); the resolved active rules file content (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback, token-aware truncated at ~4000 tokens) sent with every action request, including calls where the rules guard is disabled; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; 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; redacted tool-output samples for security and context saving (retention and output format); a redacted sample of an async subagent report that names a failure, a stop, or a question, with your latest request, when warden decides whether that report should wake the agent; and, on the first guarded call after your reply, the redacted summaries of the calls allowed in the previous turn, so Jev can say whether your reply regrets one of them. Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine; the hold feedback log stores tool names, pattern ids, scores, and outcomes (never commands) in an owner-only file under Pi's agent directory; an owner-only SQLite database under Pi's agent directory stores redacted hold context (plan, summary, redacted command preview, outcomes) for held and judged-allowed calls, for learning and retention (configurable, default 365 days). Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
+export 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, with the agent's own words from the message that makes the call (its stated plan); the resolved active rules file content (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback, token-aware truncated at ~4000 tokens) sent with every action request unless the rules guard is off (`rules.enabled: false`), which keeps that content on this machine; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; 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; redacted tool-output samples for security and context saving (retention and output format); a redacted sample of an async subagent report that names a failure, a stop, or a question, with your latest request, when warden decides whether that report should wake the agent; and, on the first guarded call after your reply, the redacted summaries of the calls allowed in the previous turn, so Jev can say whether your reply regrets one of them. Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine; the hold feedback log stores tool names, pattern ids, scores, and outcomes (never commands) in an owner-only file under Pi's agent directory; an owner-only SQLite database under Pi's agent directory stores redacted hold context (plan, summary, redacted command preview, outcomes) for held and judged-allowed calls, for learning and retention (configurable, default 365 days). 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, offPlan: 0, offTask: 0, slop: 0, ruleChecks: 0, ruleViolations: 0, pathNotes: 0, stuckChecks: 0, stuck: 0, doneChecks: 0, unverified: 0, proseChecks: 0, proseNudges: 0, runaway: 0, errors: 0, steers: 0, steersSkipped: 0, steerGuards: {}, subagentReports: 0, subagentWoken: 0, restatements: 0 });
@@ -250,6 +250,8 @@ export default function wardenExtension(pi) {
     // Allowed calls of the turn the user just replied to; the regret question about them rides the next action request.
     let regretCandidates = [];
     let attempts = new AttemptWindow(defaultConfig().stuck.window);
+    /** Full output text and saved path keyed by attempt call key, for stuck-loop diffs. */
+    let fullOutputs = new Map();
     let evidence = emptyEvidence();
     let doneNudged = false;
     let warnedFallback = false;
@@ -595,6 +597,7 @@ export default function wardenExtension(pi) {
             lastUi = ctx.ui;
         const config = configFor(ctx);
         attempts = new AttemptWindow(config.stuck.window);
+        fullOutputs = new Map();
         doneNudged = false;
         steersThisRun = 0;
         finals.reset();
@@ -698,7 +701,7 @@ export default function wardenExtension(pi) {
             ? rulesGuard.inspect(call, siblings, { cwd: ctx.cwd, config: config.rules, judge, timeoutMs: config.timeoutMs, signal: ctx.signal })
             : undefined;
         rulesCheck?.catch(() => undefined);
-        const verdict = await actionGuard.inspect(call, { task, context: recentTaskContext(ctx), siblings, plan: assistantPlan(ctx) }, { config: config.action, cwd: ctx.cwd, judge, signal: ctx.signal, slop: config.slop, security: config.security, previousActions: regretCandidates.length ? regretCandidates : undefined });
+        const verdict = await actionGuard.inspect(call, { task, context: recentTaskContext(ctx), siblings, plan: assistantPlan(ctx) }, { config: config.action, cwd: ctx.cwd, judge, signal: ctx.signal, slop: config.slop, security: config.security, rules: config.rules, previousActions: regretCandidates.length ? regretCandidates : undefined });
         if (verdict.source === "skipped")
             return;
         // Arming check: if any armed rule's command regex matches this call, inject a hit into the verdict.
@@ -1129,11 +1132,53 @@ export default function wardenExtension(pi) {
                 `output sample: ${redact(text).slice(0, 300)}`, delivered ? `agent told: ${notice}` : `steer recorded, not delivered (a repeat or the per-run budget): ${notice}`,
             ]);
         }
+        // Stuck-loop diff: when the verdict is stuck on a failed result and a previous failed output
+        // for the same call is available, replace the tool result with a short diff note. Compute
+        // bytesSaved against the current content (after duplicate detection and compression), so the
+        // diff never grows the result.
+        const verdict = await stuckCheck;
+        if (verdict && verdict.stuck && failed && !verdict.successRepeat && !verdict.churn && text.length > 0) {
+            const currentKey = attempts.attempts.at(-1)?.key;
+            const prevEntry = currentKey ? fullOutputs.get(currentKey) : undefined;
+            if (currentKey && prevEntry && prevEntry.text !== text) {
+                // Differing outputs: save the current output and diff against the previous one.
+                try {
+                    const saved = await saveOutput(text);
+                    const diffNote = stuckDiff(prevEntry.text, text, { diffLimit: config.stuck.diffLimit, tailLimit: config.stuck.tailLimit, fullPath: saved });
+                    const currentLen = Buffer.byteLength(content.map(part => part.type === "text" ? part.text : "").join("\n"));
+                    if (Buffer.byteLength(diffNote) < currentLen) {
+                        content = [{ type: "text", text: diffNote }, ...content.filter(part => part.type !== "text")];
+                    }
+                    fullOutputs.set(currentKey, { text, path: saved });
+                }
+                catch {
+                    noteError(ctx, "Could not store full output for stuck diff; keeping it unchanged.", undefined);
+                    fullOutputs.set(currentKey, { text });
+                }
+            }
+            else if (currentKey && prevEntry && prevEntry.text === text && prevEntry.path) {
+                // Byte-identical outputs: one-line note reusing the existing saved path.
+                const diffNote = stuckDiff(text, text, { diffLimit: config.stuck.diffLimit, tailLimit: config.stuck.tailLimit, fullPath: prevEntry.path });
+                const currentLen = Buffer.byteLength(content.map(part => part.type === "text" ? part.text : "").join("\n"));
+                if (Buffer.byteLength(diffNote) < currentLen) {
+                    content = [{ type: "text", text: diffNote }, ...content.filter(part => part.type !== "text")];
+                }
+            }
+            else if (currentKey) {
+                // First failed output for this call, or no previous entry yet: store for future diffs.
+                fullOutputs.set(currentKey, { text });
+            }
+        }
+        else if (failed && text.length > 0) {
+            // Not stuck (or no verdict yet): store the output so a future repeat can diff against it.
+            const currentKey = attempts.attempts.at(-1)?.key;
+            if (currentKey)
+                fullOutputs.set(currentKey, { text });
+        }
         const patch = content === event.content ? undefined : { content };
         // Checks use the original result, not the excerpts or security banner.
         if (config.done.enabled)
             recordDoneOutcome(evidence, classifyToolResult(event.toolName, event.input, failed, text), event.input, event.toolName);
-        const verdict = await stuckCheck;
         if (!verdict)
             return patch;
         if (verdict.error)
@@ -1146,7 +1191,7 @@ export default function wardenExtension(pi) {
             return patch;
         stats.stuck++;
         if (ctx.hasUI && config.notices)
-            ctx.ui.notify(`warden · stuck: ${verdict.reasons.join("; ")}${nudge ? " (agent nudged)" : ""}`, "warning");
+            ctx.ui.notify(`warden \u00b7 stuck: ${verdict.reasons.join("; ")}${nudge ? " (agent nudged)" : ""}`, "warning");
         if (nudge)
             steer(config, "stuck", nudge);
         return patch;
@@ -1513,7 +1558,7 @@ export default function wardenExtension(pi) {
                     const judge = judgeFor(config);
                     if (judge && ctx.hasUI && !await ctx.ui.confirm("Send one synthetic pi-warden test request?", `A synthetic action ("rm -rf /tmp/pi-warden-demo" for the task "Prepare the demo environment") goes to ${backendHost(config.typesafeBackend)} and may incur charges. ${disclosureFor(config.typesafeBackend, disclosure)}`))
                         return;
-                    const verdict = await evaluateAction({ tool: "bash", input: { command: "rm -rf /tmp/pi-warden-demo" }, cwd: ctx.cwd, task: "Prepare the demo environment" }, { config: { ...config.action, enabled: true, tools: ["bash"] }, judge });
+                    const verdict = await evaluateAction({ tool: "bash", input: { command: "rm -rf /tmp/pi-warden-demo" }, cwd: ctx.cwd, task: "Prepare the demo environment" }, { config: { ...config.action, enabled: true, tools: ["bash"] }, judge, rules: config.rules });
                     const deliveryVerdict = ctx.hasUI ? verdict : agentDeliveryVerdict(verdict);
                     const deliveryReasons = deliveryVerdict.reasons;
                     const fmt = formatVerdictTokens(verdict, config.widget.action);

package/dist/guard.d.ts

@@ -1,5 +1,5 @@
 import type { IntegrationErrorCode, Judge, Questions } from "pi-typesafe";
-import type { ActionGuardConfig, ArmingRule, CommandRule, PathRule, SecurityConfig, SlopGuardConfig } from "./config.js";
+import type { ActionGuardConfig, ArmingRule, CommandRule, PathRule, RulesConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
 export type Level = "allow" | "warn" | "confirm" | "deny";
 export type Severity = "destructive" | "risky" | "sensitive" | "deny";
 export type ViolationSource = "pattern" | "rules-guard" | "security-guard" | "slop-guard";
@@ -170,6 +170,12 @@ export interface EvaluateOptions {
     /** Adds quality questions for write/edit content to the same request. */
     slop?: SlopGuardConfig | undefined;
     security?: SecurityConfig | undefined;
+    /**
+     * The rules guard's switch. The active rules file rides every judged action request, so `enabled: false` is what keeps
+     * that content on this machine. Omitted, the file is sent as before, so a library caller that passes no rules config
+     * keeps today's behaviour.
+     */
+    rules?: Pick<RulesConfig, "enabled"> | undefined;
     /** This exact call was held earlier and the user has replied since: ask whether the reply approves it. */
     retryAfterHold?: boolean | undefined;
     /** Calls allowed in the previous turn: ask whether the user's latest message regrets one of them (rides this request). */

package/dist/guard.js

@@ -876,8 +876,9 @@ export async function evaluateAction(action, options) {
     }
     if (!judge)
         return withPlan({ level, source: "pattern", summary, patterns, reasons });
-    // Resolve the rules file once per call for the Jev request state.
-    const resolved = resolveRulesFile(action.cwd);
+    // Resolve the rules file once per call for the Jev request state. With the rules guard off, no rules content leaves
+    // the machine at all: no question names the field, so an absent one costs nothing.
+    const resolved = options.rules?.enabled === false ? null : resolveRulesFile(action.cwd);
     const floorHits = builtInHits.length ? builtInHits.join("; ") : "none";
     const request = buildRequest(summary, action.task, { slop: options.slop?.enabled ?? false, approval: options.retryAfterHold ?? false, security: options.security?.enabled ?? false, context: action.context, previousActions: options.previousActions, plan, questions: options.questions, rules: resolved?.content, rulesSource: resolved?.source, violations: remainingViolations, floorHits });
     const result = await ask(judge, request, { timeoutMs: config.timeoutMs, ...(options.signal ? { signal: options.signal } : {}) });

package/dist/shape.js

@@ -31,7 +31,7 @@ export function completeConfig(loaded) {
         notices: source.notices ?? false,
         steerBudget: typeof source.steerBudget === "number" && source.steerBudget >= 0 ? source.steerBudget : 3,
         action: section("action", { ...off, tools: [], failOpen: true, timeoutMs: 5000, irreversible: { warn: 1, confirm: 1 }, offTask: { warn: 1, steer: 1 }, intentMismatch: 1, visibleMismatch: 1, shouldProceed: { hold: 0.6, steer: false }, feedbackLog: false, commandRules: [], commandDenyRules: [], exemptRules: [], pathRules: [], armingRules: [], escalationThreshold: 0.85, floor: "evidence" }),
-        stuck: section("stuck", { ...off, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 1, churnThreshold: 5, nudge: false }),
+        stuck: section("stuck", { ...off, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 1, churnThreshold: 5, nudge: false, diffLimit: 3000, tailLimit: 1000 }),
         done: section("done", { ...off, claimsDone: 1, nudge: false }),
         slop: section("slop", { ...off, threshold: 1, prose: proseOff() }),
         security: section("security", { ...off, threshold: 1 }),

package/dist/stuck.d.ts

@@ -102,4 +102,13 @@ export declare function evaluateStuck(window: AttemptWindow, task: string | unde
 /** Steering text for the agent. Names the pattern and asks for a change of method, not another retry. A successful
  * repeat is a different disease than a failure loop: the model already has the answer, so it should use it. */
 export declare function stuckNudge(verdict: StuckVerdict): string;
+/**
+ * Short note for a stuck-loop repeated failure: header, capped unified diff against the previous output,
+ * tail of the current output, and the path of the full copy. All inputs must be pre-redacted.
+ */
+export declare function stuckDiff(previous: string, current: string, options: {
+    diffLimit: number;
+    tailLimit: number;
+    fullPath: string;
+}): string;
 export declare function formatStuck(verdict: StuckVerdict, template?: string): string;

package/dist/stuck.js

@@ -177,6 +177,107 @@ export function stuckNudge(verdict) {
     }
     return `pi-warden: ${verdict.reasons.join("; ")}. Stop retrying. Re-read the last error output carefully, state a new hypothesis about the cause, and either gather the missing information (read the relevant file, check versions or paths) or try a different method. If two different methods have failed, report the blocker to the user with the exact error instead of trying again.`;
 }
+/** LCS-based line diff between two outputs, capped at diffLimit characters. Both inputs must be pre-redacted. */
+function lineDiff(previous, current, diffLimit) {
+    const prevLines = previous.split("\n");
+    const currLines = current.split("\n");
+    const m = prevLines.length;
+    const n = currLines.length;
+    // Longest common subsequence.
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = prevLines[i - 1] === currLines[j - 1] ? dp[i - 1][j - 1] + 1 : Math.max(dp[i - 1][j], dp[i][j - 1]);
+        }
+    }
+    // Backtrack to build unified diff.
+    let i = m;
+    let j = n;
+    const ops = [];
+    while (i > 0 || j > 0) {
+        if (i > 0 && j > 0 && prevLines[i - 1] === currLines[j - 1]) {
+            ops.push([" ", prevLines[i - 1]]);
+            i--;
+            j--;
+        }
+        else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+            ops.push(["+", currLines[j - 1]]);
+            j--;
+        }
+        else {
+            ops.push(["-", prevLines[i - 1]]);
+            i--;
+        }
+    }
+    ops.reverse();
+    // Identify indices of changed ops (+ or -).
+    const changedIndices = [];
+    for (let k = 0; k < ops.length; k++) {
+        if (ops[k][0] !== " ")
+            changedIndices.push(k);
+    }
+    if (changedIndices.length === 0)
+        return "";
+    // Merge nearby changes: expand each changed index by 3 lines of context on each side,
+    // then merge overlapping ranges.
+    const CONTEXT = 3;
+    const ranges = [];
+    for (const idx of changedIndices) {
+        const start = Math.max(0, idx - CONTEXT);
+        const end = Math.min(ops.length - 1, idx + CONTEXT);
+        if (ranges.length > 0 && start <= ranges[ranges.length - 1][1] + 1) {
+            ranges[ranges.length - 1][1] = end;
+        }
+        else {
+            ranges.push([start, end]);
+        }
+    }
+    // Emit hunks.
+    const hunks = [];
+    for (const [rangeStart, rangeEnd] of ranges) {
+        let prevPos = 0;
+        for (let k = 0; k < rangeStart; k++) {
+            const op = ops[k][0];
+            if (op === " " || op === "-")
+                prevPos++;
+        }
+        // Count lines in the range for each file.
+        let prevCount = 0;
+        let currCount = 0;
+        const lines = [];
+        for (let k = rangeStart; k <= rangeEnd; k++) {
+            const [op, line] = ops[k];
+            lines.push(`${op} ${line}`);
+            if (op === " ") {
+                prevCount++;
+                currCount++;
+            }
+            else if (op === "-") {
+                prevCount++;
+            }
+            else {
+                currCount++;
+            }
+        }
+        hunks.push(`@@ -${prevPos + 1},${prevCount} +${prevPos + 1},${currCount} @@`);
+        hunks.push(...lines);
+    }
+    const text = hunks.join("\n");
+    return text.length <= diffLimit ? text : `${text.slice(0, diffLimit)}\n… [diff truncated]`;
+}
+/**
+ * Short note for a stuck-loop repeated failure: header, capped unified diff against the previous output,
+ * tail of the current output, and the path of the full copy. All inputs must be pre-redacted.
+ */
+export function stuckDiff(previous, current, options) {
+    const header = `pi-warden: stuck-loop diff; this output repeated a failure (previous: ${previous.length} chars, current: ${current.length} chars).`;
+    if (previous === current) {
+        return `${header}\nOutputs are byte-identical; see the full output at ${options.fullPath}.`;
+    }
+    const diff = lineDiff(previous, current, options.diffLimit);
+    const tail = current.length <= options.tailLimit ? current : `… [${current.length - options.tailLimit} earlier chars omitted]\n${current.slice(-options.tailLimit)}`;
+    return `${header}\n${diff}\n${tail}\n\nFull output: ${options.fullPath}`;
+}
 export function formatStuck(verdict, template = DEFAULT_TEMPLATES.stuck) {
     return renderTemplate(template, stuckTokens(verdict));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-warden",
-  "version": "0.34.1",
+  "version": "0.36.0",
   "description": "Makes the Pi agent follow your project's rules. Jev judges every write against your pi-warden.md and quotes the broken rule back to the agent, names slop, breaks stuck loops, calls out unverified done claims, compresses large tool output, and holds the rare destructive command. Built on pi-typesafe.",
   "type": "module",
   "license": "MIT",