pi-warden 0.7.0 → 0.9.0

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 = 5;
 export const PROJECT_CONFIG_FILE = `${PACKAGE_NAME}.json`;
 export function defaultConfig() {
     return {
@@ -30,7 +30,10 @@ export function defaultConfig() {
         done: { enabled: true, claimsDone: 0.7, nudge: true },
         slop: { enabled: true, threshold: 0.7, prose: { enabled: true, audience: "technical", threshold: 0.7, trend: 2, minChars: 200 } },
         security: { enabled: true, threshold: 0.7 },
+        rules: { enabled: true, threshold: 0.7, files: [], fallback: true, maxChars: 8000, exclude: [], skip: [], sensitivePaths: {} },
         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 +107,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;
@@ -126,6 +149,26 @@ function applySlop(base, raw) {
     // 0.2.x used `placeholder` for the stub threshold; it still sets the shared threshold.
     return { enabled: boolean(raw.enabled, base.enabled), threshold: probability(raw.threshold ?? raw.placeholder, base.threshold), prose: applyProse(base.prose, raw.prose) };
 }
+function globList(value, fallback) {
+    return Array.isArray(value) ? value.filter((glob) => typeof glob === "string" && glob.trim().length > 0).map(glob => glob.trim()) : fallback;
+}
+function applyRules(base, raw) {
+    if (!isObject(raw))
+        return base;
+    const notes = isObject(raw.sensitivePaths)
+        ? Object.fromEntries(Object.entries(raw.sensitivePaths).filter((entry) => entry[0].trim().length > 0 && typeof entry[1] === "string" && entry[1].trim().length > 0))
+        : base.sensitivePaths;
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        threshold: probability(raw.threshold, base.threshold),
+        files: globList(raw.files, base.files),
+        fallback: boolean(raw.fallback, base.fallback),
+        maxChars: Math.max(500, positiveInteger(raw.maxChars, base.maxChars)),
+        exclude: globList(raw.exclude, base.exclude),
+        skip: globList(raw.skip, base.skip),
+        sensitivePaths: notes,
+    };
+}
 function applyWidget(base, raw) {
     if (!isObject(raw))
         return base;
@@ -142,6 +185,8 @@ 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),
+        rules: template(raw.rules, base.rules),
     };
 }
 /** Shared request settings; `action.timeoutMs`/`action.maxRequests` from 0.1.x files are still honoured. */
@@ -152,8 +197,12 @@ function applyShared(base, raw) {
         maxRequests: positiveInteger(raw.maxRequests ?? legacy.maxRequests, base.maxRequests),
     };
 }
-function applyGuards(base, raw, timeoutMs) {
+function applyGuards(base, raw, timeoutMs, source) {
     return {
+        rules: applyRules(base.rules, raw.rules),
+        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 +231,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 +240,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.d.ts

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

package/dist/extension.js

@@ -10,16 +10,19 @@ 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 { formatRules, pathNoteSteer, RulesGuard, rulesSteer } from "./rules.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, rulesDetails, 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.";
+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; 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; 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, ruleChecks: 0, ruleViolations: 0, pathNotes: 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--) {
@@ -122,14 +125,22 @@ export default function wardenExtension(pi) {
     let panel;
     let lastUi;
     const actionGuard = new ActionGuard();
+    const rulesGuard = new RulesGuard();
     let attempts = new AttemptWindow(defaultConfig().stuck.window);
     let evidence = emptyEvidence();
     let doneNudged = false;
     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 +206,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;
@@ -203,12 +232,18 @@ export default function wardenExtension(pi) {
         trace.clear();
         panel?.close();
         actionGuard.reset();
+        rulesGuard.reset();
         attempts.reset();
         evidence = emptyEvidence();
         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,7 +253,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();
+        rulesGuard.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 () => {
@@ -228,6 +295,7 @@ export default function wardenExtension(pi) {
     pi.on("turn_end", async () => {
         ledger.turnEnd();
         actionGuard.turnEnd();
+        rulesGuard.turnEnd();
     });
     pi.on("tool_call", async (event, ctx) => {
         const config = configFor(ctx);
@@ -248,9 +316,18 @@ export default function wardenExtension(pi) {
         stats.inspected++;
         const task = latestUserPrompt(ctx);
         const judge = judgeFor(config);
-        const verdict = await actionGuard.inspect({ id: event.toolCallId, tool: event.toolName, input: event.input }, { task, context: recentTaskContext(ctx), siblings: siblingToolCalls(ctx) }, { config: config.action, cwd: ctx.cwd, judge, signal: ctx.signal, slop: config.slop, security: config.security });
+        const siblings = siblingToolCalls(ctx);
+        const call = { id: event.toolCallId, tool: event.toolName, input: event.input };
+        // The rules request carries the written content and the rule text, so it goes out beside the action request, not inside it.
+        const rulesCheck = config.rules.enabled && (event.toolName === "write" || event.toolName === "edit")
+            ? 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 }, { config: config.action, cwd: ctx.cwd, judge, signal: ctx.signal, slop: config.slop, security: config.security });
         if (verdict.source === "skipped")
             return;
+        // Notes for the agent about the content it just wrote: slop, rule violations, and sensitive paths arrive as one message.
+        const notes = [];
         if (verdict.judgment?.securityRisk !== undefined && verdict.judgment.securityRisk >= config.security.threshold) {
             steer(config, "pi-warden: the proposed write may introduce a security weakness. Check for embedded credentials, disabled TLS, unsafe command/SQL interpolation, broad permissions, or bypassed verification; use a safe implementation instead.");
         }
@@ -271,8 +348,35 @@ export default function wardenExtension(pi) {
             const where = verdict.summary.path ?? event.toolName;
             if (ctx.hasUI)
                 ctx.ui.notify(`warden · slop · ${where}: ${verdict.slopReasons.join("; ")}`, "warning");
-            steer(config, slopSteer(where, verdict.slopSymptoms, slopCounts));
+            notes.push(slopSteer(where, verdict.slopSymptoms, slopCounts));
         }
+        if (rulesCheck) {
+            const rules = await rulesCheck;
+            if (rules.source !== "skipped") {
+                stats.ruleChecks++;
+                if (rules.error)
+                    noteError(ctx, rules.error, rules.errorCode);
+                const told = rules.findings.length ? rulesSteer(rules, rulesGuard.count(rules)) : undefined;
+                record(ctx, config, "rules", formatRules(rules, config.widget.rules), rulesDetails(rules, told));
+                if (told) {
+                    stats.ruleViolations++;
+                    if (ctx.hasUI)
+                        ctx.ui.notify(`warden · rules · ${rules.path}: ${rules.findings.map(finding => `${finding.name} (${finding.violation.toFixed(2)})`).join("; ")}`, "warning");
+                    notes.push(told);
+                }
+            }
+            const hits = rulesGuard.notesFor(verdict.summary.location === "inside_project" ? verdict.summary.path : undefined, config.rules.sensitivePaths);
+            if (hits.length && verdict.summary.path) {
+                stats.pathNotes++;
+                const told = pathNoteSteer(verdict.summary.path, hits);
+                record(ctx, config, "rules", renderTemplate(config.widget.rules, { tool: event.toolName, path: verdict.summary.path, violations: `sensitive path ${hits.map(hit => hit.glob).join(", ")}`, status: "note" }), [`${event.toolName} ${verdict.summary.path} matches ${hits.map(hit => hit.glob).join(", ")} in rules.sensitivePaths`, `agent told: ${told}`]);
+                if (ctx.hasUI)
+                    ctx.ui.notify(`warden · sensitive path · ${verdict.summary.path} (${hits.map(hit => hit.glob).join(", ")}); the agent was given the note`, "warning");
+                notes.push(told);
+            }
+        }
+        if (notes.length)
+            steer(config, notes.join("\n\n"));
         if (verdict.level === "warn") {
             stats.warned++;
             if (ctx.hasUI)
@@ -289,6 +393,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 +404,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 +528,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 +619,14 @@ 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.rules.enabled && "rules", 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.ruleViolations}/${stats.ruleChecks} rule violations, ${stats.pathNotes} sensitive-path 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}, rules ${config.rules.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()),
+                        `Rules: ${config.rules.enabled ? `${rulesGuard.describe(ctx.cwd, config.rules)}${Object.keys(config.rules.sensitivePaths).length ? `; ${Object.keys(config.rules.sensitivePaths).length} sensitive path${Object.keys(config.rules.sensitivePaths).length === 1 ? "" : "s"}` : ""}` : "off"}.`,
+                        `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/guard.d.ts

@@ -37,6 +37,8 @@ export interface ActionSummary {
         newText: string;
     }>;
     input?: string;
+    /** Present when part of the command is data (a heredoc body, a quoted message), so a destructive string inside it is payload. */
+    dataText?: string;
 }
 export type ScopeLabel = "expected_step" | "plausible_side_step" | "unrelated" | "unclear";
 export interface Judgment {
@@ -91,6 +93,17 @@ export interface EvaluateOptions {
     /** This exact call was held earlier and the user has replied since: ask whether the reply approves it. */
     retryAfterHold?: boolean | undefined;
 }
+export interface ScannedCommand {
+    /** The command with data text blanked; what the pattern rules read. */
+    text: string;
+    /** True when a heredoc body or quoted data was removed. */
+    stripped: boolean;
+}
+/**
+ * Removes heredoc bodies that are not fed to a shell and quoted arguments of data commands. Interpreter heredocs
+ * (`python3 - <<EOF`) are kept when the script calls out to a shell or process API.
+ */
+export declare function stripDataText(command: string): ScannedCommand;
 export declare function matchPatterns(tool: string, input: Record<string, unknown>, cwd?: string): PatternHit[];
 export declare function isReadOnlyCommand(command: string): boolean;
 export declare function describeAction(tool: string, input: Record<string, unknown>, cwd: string): ActionSummary;

package/dist/guard.js

@@ -52,12 +52,123 @@ const SENSITIVE_PATH = /(?:^|[\s/"'=:(])\.env(?:\.(?!example\b|sample\b|template
 function splitShell(command) {
     return command.split(/\n|;|&&|\|\||\||&/).map(part => part.trim()).filter(Boolean);
 }
-/** rm with both recursive and force flags. Absolute, home, variable, or wildcard targets are destructive; relative ones are risky. */
+// ---------------------------------------------------------------------------
+// Data text: a heredoc body written to a file, a quoted message, or a search pattern is not a command. Pattern rules skip
+// it so a test fixture or a commit message that mentions `git push --force` is not held. A shell sink anywhere in the
+// command (sh, eval, bash -c, command substitution) keeps every byte in scope, because the payload is executed.
+const WRAPPERS = new Set(["sudo", "nohup", "time", "env", "command", "builtin", "exec", "nice", "timeout", "doas"]);
+const SHELL_SINKS = new Set(["sh", "bash", "zsh", "dash", "ksh", "fish", "eval", "source", ".", "xargs", "su"]);
+/** Commands whose quoted arguments are text they print, search, or record. */
+const DATA_HEADS = new Set(["echo", "printf", "grep", "egrep", "fgrep", "rg", "ag", "ugrep", "jq", "cat", "tee", "head", "tail", "wc", "sort", "uniq", "cut", "tr", "less", "more", "test", "["]);
+const GIT_MESSAGE_SUBCOMMANDS = new Set(["commit", "tag", "notes", "merge", "stash"]);
+/** Interpreters whose stdin script can still run shell commands; their heredoc bodies stay in scope when they do. */
+const INTERPRETERS = /^(?:python[\d.]*|node|ruby|perl|php|deno|bun|tsx|Rscript|lua[\d.]*)$/;
+const EXEC_CALLS = /\b(?:os\.system|os\.popen|os\.exec\w*|subprocess|child_process|execSync|spawnSync|execFileSync|spawn\(|exec\(|system\(|popen\(|shell_exec|passthru|proc_open|Open3|IO\.popen|Deno\.run|Deno\.Command|Bun\.spawn|Bun\.\$|%x[\[{(]|`[^`\n]*\b(?:rm|git|dd|mkfs|kubectl|terraform)\b)/;
+const HEREDOC = /<<-?\s*(?:"(\w+)"|'(\w+)'|\\?(\w+))/;
+function headOf(segment) {
+    const tokens = segment.trim().split(/\s+/);
+    let index = 0;
+    while (index < tokens.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[index]) || WRAPPERS.has(tokens[index])))
+        index++;
+    const head = tokens[index];
+    return head ? head.replace(/^.*\//, "") : undefined;
+}
+/** Quoted strings replaced by a placeholder; escapes inside double quotes are honoured, single quotes take everything. */
+function blankQuotes(segment) {
+    let out = "";
+    for (let index = 0; index < segment.length; index++) {
+        const char = segment[index];
+        if (char !== "'" && char !== "\"") {
+            out += char;
+            continue;
+        }
+        let end = index + 1;
+        while (end < segment.length && segment[end] !== char)
+            end += char === "\"" && segment[end] === "\\" ? 2 : 1;
+        if (end >= segment.length) {
+            out += segment.slice(index);
+            break;
+        }
+        out += `${char}[text]${char}`;
+        index = end;
+    }
+    return out;
+}
+function isDataSegment(segment) {
+    const head = headOf(segment);
+    if (!head)
+        return false;
+    if (head === "git") {
+        const sub = segment.trim().split(/\s+/).find(token => !token.startsWith("-") && token !== "git" && !WRAPPERS.has(token));
+        return sub !== undefined && GIT_MESSAGE_SUBCOMMANDS.has(sub) && !/\s-c\s|--config/.test(segment);
+    }
+    if (head === "gh")
+        return /\s--(?:body|title|notes)\b/.test(segment) || /\s-[bt]\s/.test(segment);
+    return DATA_HEADS.has(head);
+}
+/**
+ * Removes heredoc bodies that are not fed to a shell and quoted arguments of data commands. Interpreter heredocs
+ * (`python3 - <<EOF`) are kept when the script calls out to a shell or process API.
+ */
+export function stripDataText(command) {
+    if (/\$\(|`/.test(command))
+        return { text: command, stripped: false };
+    const lines = command.split("\n");
+    const out = [];
+    let stripped = false;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const heredoc = HEREDOC.exec(line);
+        if (!heredoc) {
+            out.push(line);
+            continue;
+        }
+        const delimiter = heredoc[1] ?? heredoc[2] ?? heredoc[3];
+        const consumer = headOf(line.slice(0, heredoc.index)) ?? "";
+        const body = [];
+        let close = index + 1;
+        while (close < lines.length && lines[close].replace(/^\t+/, "") !== delimiter)
+            body.push(lines[close]), close++;
+        const bodyText = body.join("\n");
+        const executed = SHELL_SINKS.has(consumer) || (INTERPRETERS.test(consumer) && EXEC_CALLS.test(bodyText));
+        out.push(line);
+        if (executed)
+            out.push(...body);
+        else if (body.length) {
+            out.push(`[heredoc body: ${body.length} lines of data]`);
+            stripped = true;
+        }
+        if (close < lines.length)
+            out.push(lines[close]);
+        index = close;
+    }
+    const joined = out.join("\n");
+    const segments = splitShell(joined);
+    if (segments.some(segment => { const head = headOf(segment); return head !== undefined && SHELL_SINKS.has(head); }))
+        return { text: joined, stripped };
+    if (/\b(?:ba|z|da|k)?sh\s+-[a-zA-Z]*c\b/.test(joined))
+        return { text: joined, stripped };
+    let text = joined;
+    for (const segment of segments) {
+        if (!isDataSegment(segment) || !/["']/.test(segment))
+            continue;
+        const blanked = blankQuotes(segment);
+        if (blanked === segment)
+            continue;
+        text = text.replace(segment, blanked);
+        stripped = true;
+    }
+    return { text, stripped };
+}
+/**
+ * rm with both recursive and force flags. Absolute, home, variable, or wildcard targets are destructive; relative ones are
+ * risky. A quote before `rm` is allowed so `bash -c "rm -rf /"` is read; data quotes were blanked before this runs.
+ */
 function classifyRm(segment, cwd) {
-    const match = /(?:^|\s)rm\s+(.*)$/.exec(segment);
+    const match = /(?:^|[\s"'])rm\s+(.*)$/.exec(segment);
     if (!match)
         return undefined;
-    const tokens = match[1].split(/\s+/).filter(Boolean);
+    const tokens = match[1].split(/\s+/).filter(Boolean).map(token => token.replace(/["']$/, ""));
     const flags = tokens.filter(token => token.startsWith("-"));
     const targets = tokens.filter(token => !token.startsWith("-"));
     const recursive = flags.some(flag => flag === "--recursive" || (/^-[a-zA-Z]+$/.test(flag) && /[rR]/.test(flag)));
@@ -86,8 +197,9 @@ export function matchPatterns(tool, input, cwd) {
     const hits = new Map();
     const add = (hit) => { if (hit && !hits.has(hit.id))
         hits.set(hit.id, hit); };
-    const command = commandOf(tool, input)?.command;
-    if (command) {
+    const raw = commandOf(tool, input)?.command;
+    if (raw) {
+        const command = stripDataText(raw).text;
         for (const rule of SHELL_RULES)
             if (rule.test.test(command))
                 add({ id: rule.id, severity: rule.severity, label: rule.label });
@@ -174,8 +286,12 @@ function displayPath(target, cwd) {
 export function describeAction(tool, input, cwd) {
     const summary = { tool };
     const view = commandOf(tool, input);
-    if (view)
+    if (view) {
         summary.command = redact(truncate(view.command, COMMAND_LIMIT));
+        // Jev sees the full text; this names the part of it that is written or printed rather than executed.
+        if (stripDataText(view.command).stripped)
+            summary.dataText = "heredoc bodies and quoted arguments of echo/printf/grep/git commit in this command are text that is written, printed, searched, or recorded, not executed";
+    }
     if (typeof input.path === "string" && input.path.trim() && tool !== "ctx_execute_file") {
         const shown = displayPath(input.path, cwd);
         summary.path = shown.path;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
-export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, ScopeLabel, Severity, Verdict } from "./guard.js";
+export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
+export type { ActionInput, ActionSummary, EvaluateOptions, Judge, Judgment, SlopJudgment, SlopSymptom, Level, PatternHit, ScannedCommand, ScopeLabel, Severity, Verdict } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
 export { ActionGuard } from "./action-guard.js";
 export type { Conversation, InspectOptions, ToolCallRef } from "./action-guard.js";
@@ -16,15 +16,21 @@ 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, RulesConfig, 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, rulesTokens, 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, rulesDetails } from "./trace.js";
 export type { TraceEntry, GuardName } from "./trace.js";
+export { parseRules, condense, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";
+export type { Rule, RuleSet, RuleOutcome, RuleScore, RuleFinding, RulesVerdict, RulesOptions, RulesTarget, EditView, PathNote, RulesCallRef } from "./rules.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
+export { evaluateAction, describeAction, matchPatterns, isReadOnlyCommand, stripDataText, buildRequest, formatVerdict, steerReason, questions, slopQuestions, approvalQuestion, securityQuestion } from "./guard.js";
 export { SLOP_SYMPTOMS, SLOP_LABELS } from "./guard.js";
 export { ActionGuard } from "./action-guard.js";
 export { evaluateProse, buildProseRequest, proseQuestions, proseNudge, describeAudience, ProseTrend, PROSE_SYMPTOMS, PROSE_LABELS } from "./prose.js";
@@ -8,9 +8,12 @@ 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, rulesTokens, defaultWidgetConfig, DEFAULT_TEMPLATES, TOKEN_NAMES } from "./widget.js";
+export { Trace, actionDetails, stuckDetails, doneDetails, proseDetails, runawayDetails, rulesDetails } from "./trace.js";
+export { parseRules, condense, globToRegExp, matchGlob, projectPath, RuleStore, rulesFor, describeRuleSet, describeTarget, buildRulesRequest, ruleQuestion, evaluateRules, skipReason, rulesSteer, formatRules, pathNotes, pathNoteSteer, RulesGuard, RULES_FILE, FALLBACK_FILES, MAX_RULES, AGGREGATE_QUESTION, LOCATOR_QUESTION } from "./rules.js";