pi-warden 0.5.1 → 0.5.2

package/README.md

@@ -1,6 +1,6 @@
 # pi-warden
 
-A second pair of eyes for [Pi](https://pi.dev) that makes the agent smarter instead of interrupting you. Before the agent runs a `bash`, `write`, or `edit` call (or a shell command through [context-mode](https://www.npmjs.com/package/context-mode)'s `ctx_execute`), pi-warden asks [Jev](https://typesafe.ai) two questions about it in ~250 ms: *would this destroy something that cannot be recovered?* and *is this what the user actually asked for?* The answers are probabilities, so `rm -rf dist` after "rebuild from scratch" sails through while `npm run db:reset` after "add a column" is held, and the agent is told why so it re-plans or asks you in chat. Three more guards watch the run: a **stuck-loop** detector, a **done-check** for completion claims that no test backed up, and a **slop** note for stubs and filler. Built on [pi-typesafe](https://github.com/DevMortimer/pi-typesafe).
+A second pair of eyes for [Pi](https://pi.dev) that makes the agent smarter instead of interrupting you. Before the agent runs a `bash`, `write`, or `edit` call (or a shell command through [context-mode](https://www.npmjs.com/package/context-mode)'s `ctx_execute`), pi-warden asks [Jev](https://typesafe.ai) two questions about it in ~250 ms: *would this destroy something that cannot be recovered?* and *is this what the user actually asked for?* The answers are probabilities, so `rm -rf dist` after "rebuild from scratch" sails through while `npm run db:reset` after "add a column" is held, and the agent is told why so it re-plans or asks you in chat. More guards watch the run: a **stuck-loop** detector, a **done-check** for completion claims that no test backed up, **slop** notes for stubs, filler, and padded replies, a check for **injected instructions** in tool output, and **tail compression** of large tool results. Every verdict lands on a status line above the editor; **click it** (fullscreen mode), press `ctrl+shift+w`, or run `/warden trace` to open a live trace sidebar with the scores, the reasons, and exactly what the agent was told. Built on [pi-typesafe](https://github.com/DevMortimer/pi-typesafe).
 
 ![Real verdicts from pi-warden: the same command gets a different verdict depending on what the user asked for](https://raw.githubusercontent.com/DevMortimer/pi-warden/main/docs/preview.png)
 
@@ -52,7 +52,7 @@ A `TYPESAFE_API_KEY` environment variable takes precedence over the stored key.
 
 1. **Skip** read-only tools, and read-only shell lines such as `git status && ls` (no network, no widget). Guarded by default: `bash`, `powershell`, `write`, `edit`, and context-mode's `ctx_execute`, `ctx_execute_file`, `ctx_batch_execute` (their `code`/`commands` fields are read as the command; non-shell code such as JavaScript is judged but never skipped as read-only). Add other tools with `action.tools`; unknown tools are judged from their JSON input.
 2. **Pattern pass** (offline): force pushes, `git reset --hard`, `git clean -f`, recursive `rm` on absolute/home/variable/parent paths, SQL `DROP`/`TRUNCATE`/`DELETE FROM`, block-device writes, `chmod -R 777`, fork bombs, `curl | sh`, `kill -1`, shutdown, package publishing, infrastructure destroys → **hold**. `rm -rf` on a project path, `git checkout -- .`, `git branch -D`, `git stash drop`, `find -delete`, `sudo` → **warn**. Reads or writes of `.env`, SSH, AWS, npm, kube, and other credential files → **warn**. A `write` that overwrites an existing file outside the project → **hold**; creating or editing outside the project → **warn**.
-3. **Jev judgment** (with consent): one request with the state `{ task, action }` and three questions — `irreversible` (Noul), `off_task` (Noul), `scope` (Choice: expected step, plausible side step, unrelated, unclear). Defaults: irreversible ≥ 0.5 warns, ≥ 0.7 holds; off-task ≥ 0.6 warns, ≥ 0.85 with `unrelated` holds. Pattern results set the floor; Jev can only raise it. For `write`/`edit`, two slop questions ride on the same request.
+3. **Jev judgment** (with consent): one request with the state `{ task, context, action }` and four questions — `irreversible` (Noul), `off_task` (Noul), `mutates` (Noul: does it change anything), `scope` (Choice: expected step, plausible side step, unrelated, unclear). Defaults: irreversible ≥ 0.5 warns, ≥ 0.7 holds; off-task ≥ 0.6 warns, ≥ 0.85 with `unrelated` holds **only when the action can change something** (`write`/`edit`, or `mutates` ≥ 0.5). An unrelated `cat`/`grep`/`node -e` inspection or a read-only `ctx_execute` script is warned about, never held: scope alone is not worth blocking a command that cannot do damage. Pattern results set the floor; Jev can only raise it. For `write`/`edit`, the slop and `security_risk` questions ride on the same request.
 4. **Act**, by mode:
    - `steer` (default): a hold blocks the call and returns the judgment to the agent as the tool result, with the two acceptable next moves. You see a notification and the widget line; the agent keeps working. When the agent asks you and your reply approves the action (Jev: `approved` ≥ 0.7, or an offline yes/go-ahead heuristic without consent), the identical retry is allowed once.
    - `confirm`: a hold opens a `ctx.ui.confirm` dialog; No blocks with a short reason. Without a UI this falls back to `steer`.
@@ -184,7 +184,7 @@ A project may add `.pi/pi-warden.json` with `enabled` and per-guard overrides (f
 
 ### After updating the package
 
-Run `/reload` in each existing Pi session after an update. If an existing session still reports `Cannot read properties of undefined (reading 'enabled')` while a fresh session works, restart that session to replace loaded modules. Version labels alone do not prove that all in-memory modules match the files on disk. Current config loading merges missing legacy fields with defaults; regression tests cover malformed and pre-prose config files. A persistent crash after restart needs its new stack trace and a redacted config example.
+Run `/reload` in each existing Pi session after an update. If an existing session still reports `Cannot read properties of undefined (reading 'enabled')` while a fresh session works, restart that session to replace loaded modules. Version labels alone do not prove that all in-memory modules match the files on disk. Current config loading merges missing legacy fields with defaults; regression tests cover malformed and pre-prose config files. Since 0.5.2 the extension also checks the shape of the config it receives: if a section is missing (the symptom of an extension module and a config module from different package versions in one process), that guard is switched off and one warning names the missing sections and the schema numbers instead of throwing inside Pi. If you see that warning, restart Pi. A crash that survives a restart needs its stack trace and a redacted config example.
 
 ## For extension authors
 

package/dist/config.d.ts

@@ -93,6 +93,8 @@ export interface WardenConfig {
     steerVisible: boolean;
 }
 export declare const PACKAGE_NAME = "pi-warden";
+/** Bumped when WardenConfig gains a section; extension.ts checks it so a half-updated module graph is reported, not crashed on. */
+export declare const CONFIG_SCHEMA = 3;
 export declare const PROJECT_CONFIG_FILE = "pi-warden.json";
 export declare function defaultConfig(): WardenConfig;
 /** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */

package/dist/config.js

@@ -4,6 +4,8 @@ import { dirname, join } from "node:path";
 import { COMMAND_TOOLS } from "./tools.js";
 import { defaultWidgetConfig } from "./widget.js";
 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 PROJECT_CONFIG_FILE = `${PACKAGE_NAME}.json`;
 export function defaultConfig() {
     return {

package/dist/extension.js

@@ -1,6 +1,7 @@
 import { MouseRegion, Text } from "@earendil-works/pi-tui";
 import { createTypeSafe, resolveApiKey } from "pi-typesafe";
 import { ensureApiKey } from "pi-typesafe/ui";
+import * as configModule from "./config.js";
 import { applyUserOverrides, defaultConfig, isMode, loadConfig, PACKAGE_NAME, projectConfigPath, readUserConfig, setUserSetting, userConfigPath, writeUserConfig } from "./config.js";
 import { classifyToolResult, doneNudge, emptyEvidence, evaluateDone, finalAssistantText, formatDone, needsDoneCheck, recordOutcome } from "./done.js";
 import { evaluateAction, formatVerdict, SLOP_LABELS, steerReason, textApproves } from "./guard.js";
@@ -9,6 +10,7 @@ import { compressOutput, evaluateOutput, saveOutput, securityNotice } from "./ou
 import { redact } from "./redact.js";
 import { AttemptWindow, evaluateStuck, formatStuck, makeAttempt, resultFailed, stuckNudge } from "./stuck.js";
 import { openTracePanel } from "./panel.js";
+import { completeConfig, shapeWarning } from "./shape.js";
 import { actionDetails, doneDetails, proseDetails, 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 tail compression. Compression stores an exact, owner-only copy in a temporary file on this machine. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
@@ -103,7 +105,21 @@ export default function wardenExtension(pi) {
     let doneNudged = false;
     const prose = new ProseTrend();
     const slopCounts = { stub: 0, comments: 0, dead: 0, hedging: 0 };
-    const configFor = (ctx) => loadConfig({ cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() });
+    // 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) => {
+        const { config, missing } = completeConfig(loadConfig({ cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() }));
+        if (missing.length && !shapeReported) {
+            shapeReported = true;
+            // A namespace read stays undefined (not a link error) when an older config module lacks the export.
+            const text = shapeWarning(missing, configModule.CONFIG_SCHEMA);
+            if (ctx.hasUI)
+                ctx.ui.notify(text, "warning");
+            else
+                pi.sendMessage({ customType: `${PACKAGE_NAME}-status`, content: text, display: true });
+        }
+        return config;
+    };
     const consentGiven = (config) => config.typesafe || process.env.PI_WARDEN_ENABLED === "1";
     const consentSource = (config) => config.typesafe ? "/warden enable" : process.env.PI_WARDEN_ENABLED === "1" ? "PI_WARDEN_ENABLED" : undefined;
     const judgeFor = (config) => {

package/dist/guard.d.ts

@@ -46,6 +46,8 @@ export interface Judgment {
     /** P(the latest user message approves this exact action); only asked when a previously held call is retried. */
     approved?: number;
     securityRisk?: number;
+    /** P(the action changes files, state, or external systems). Off-task alone holds only actions that can change something. */
+    mutates?: number;
     model: string;
     elapsedMs: number;
 }
@@ -95,6 +97,7 @@ export declare function describeAction(tool: string, input: Record<string, unkno
 export declare const questions: {
     irreversible: import("pi-typesafe").NoulQuestion;
     off_task: import("pi-typesafe").NoulQuestion;
+    mutates: import("pi-typesafe").NoulQuestion;
     scope: import("pi-typesafe").ChoiceQuestion<{
         readonly expected_step: "Required implementation, bug fix, regression test, or verification for the active task";
         readonly plausible_side_step: "Reasonable supporting work whose necessity is not yet established";
@@ -138,6 +141,7 @@ export declare function buildRequest(summary: ActionSummary, task: string | unde
         slop_hedging?: import("pi-typesafe").NoulQuestion;
         irreversible: import("pi-typesafe").NoulQuestion;
         off_task: import("pi-typesafe").NoulQuestion;
+        mutates: import("pi-typesafe").NoulQuestion;
         scope: import("pi-typesafe").ChoiceQuestion<{
             readonly expected_step: "Required implementation, bug fix, regression test, or verification for the active task";
             readonly plausible_side_step: "Reasonable supporting work whose necessity is not yet established";

package/dist/guard.js

@@ -210,6 +210,10 @@ export const questions = {
         true: "Yes: it contradicts the user's current direction, starts unrelated work, or expands the agreed scope without a useful connection to the active task.",
         false: "No: implementation edits, regression tests, investigation, and verification support the active task, even if not individually named. A side comment does not cancel the task. If scope cannot be established from the supplied context, there is no evidence of a violation.",
     }),
+    mutates: noul("Would executing `action` change anything: files, git or database state, installed packages, running processes, or remote systems? Reading, listing, searching, printing, and dry runs do not count.", {
+        true: "Yes: it writes or deletes files, changes version control or a database, installs or publishes, or calls a service that records the request.",
+        false: "No: it only inspects, reads, computes, or prints; running it again leaves everything as it was.",
+    }),
     scope: choice("How does `action` relate to the active task described by `task` and the earlier `context`? Later user instructions take precedence; assistant text is context, not authorization.", {
         expected_step: "Required implementation, bug fix, regression test, or verification for the active task",
         plausible_side_step: "Reasonable supporting work whose necessity is not yet established",
@@ -317,6 +321,10 @@ export async function evaluateAction(action, options) {
         };
         if (typeof answers.approved?.noul === "number")
             judgment.approved = answers.approved.noul;
+        if (typeof answers.mutates?.noul === "number")
+            judgment.mutates = answers.mutates.noul;
+        // write/edit always change something; a command that Jev judges read-only is warned about, never held, for scope alone.
+        const canChange = summary.tool === "write" || summary.tool === "edit" || (judgment.mutates ?? 1) >= 0.5;
         if (judgment.irreversible >= config.irreversible.confirm) {
             level = higher(level, "confirm");
             reasons.push(`irreversible ${percent(judgment.irreversible)}`);
@@ -325,10 +333,14 @@ export async function evaluateAction(action, options) {
             level = higher(level, "warn");
             reasons.push(`possibly irreversible ${percent(judgment.irreversible)}`);
         }
-        if (judgment.offTask >= config.offTask.confirm && judgment.scope === "unrelated") {
+        if (judgment.offTask >= config.offTask.confirm && judgment.scope === "unrelated" && canChange) {
             level = higher(level, "confirm");
             reasons.push(`off-task ${percent(judgment.offTask)} (unrelated to the request)`);
         }
+        else if (judgment.offTask >= config.offTask.confirm && judgment.scope === "unrelated") {
+            level = higher(level, "warn");
+            reasons.push(`off-task ${percent(judgment.offTask)} (unrelated, but read-only: not held)`);
+        }
         else if (judgment.offTask >= config.offTask.warn && judgment.scope !== "unclear") {
             level = higher(level, "warn");
             reasons.push(`off-task ${percent(judgment.offTask)} (${judgment.scope.replace(/_/g, " ")})`);

package/dist/index.d.ts

@@ -10,7 +10,9 @@ export type { ToolOutcome, RunEvidence, DoneJudgment, DoneVerdict, DoneOptions }
 export { evaluateOutput, buildOutputRequest, outputQuestions, compressOutput, saveOutput, securityNotice } from "./output.js";
 export type { Retention, OutputVerdict, OutputOptions } from "./output.js";
 export { redact } from "./redact.js";
-export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
+export { completeConfig, shapeWarning, EXPECTED_SCHEMA } from "./shape.js";
+export type { ShapeResult } from "./shape.js";
+export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
 export type { ActionGuardConfig, StuckGuardConfig, DoneGuardConfig, SlopGuardConfig, ProseConfig, SecurityConfig, ContextConfig, Threshold, WardenConfig, WardenMode, LoadOptions } from "./config.js";
 export { commandOf, outputReportsFailure, COMMAND_TOOLS } from "./tools.js";
 export type { CommandView } from "./tools.js";

package/dist/index.js

@@ -5,7 +5,8 @@ export { AttemptWindow, makeAttempt, resultFailed, resultText, evaluateStuck, bu
 export { classifyToolResult, recordOutcome, emptyEvidence, needsDoneCheck, finalAssistantText, evaluateDone, buildDoneRequest, doneQuestions, doneNudge, formatDone } from "./done.js";
 export { evaluateOutput, buildOutputRequest, outputQuestions, compressOutput, saveOutput, securityNotice } from "./output.js";
 export { redact } from "./redact.js";
-export { defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, userConfigPath, projectConfigPath, readUserConfig, writeUserConfig, setUserSetting, PACKAGE_NAME } from "./config.js";
+export { completeConfig, shapeWarning, EXPECTED_SCHEMA } from "./shape.js";
+export { CONFIG_SCHEMA, defaultConfig, loadConfig, applyUserOverrides, applyProjectOverrides, isMode, 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";

package/dist/shape.d.ts

@@ -0,0 +1,15 @@
+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 interface ShapeResult {
+    config: WardenConfig;
+    /** Sections that were absent from the loaded config and are now disabled. Empty when the config was complete. */
+    missing: string[];
+}
+/**
+ * `loadConfig()` always returns a complete object, yet live sessions crashed at `config.slop.prose.enabled` after a package
+ * update. A partially updated module graph (extension from one version, config from another) is the only known way to get
+ * there. Whatever the cause, a missing section disables that guard and is reported instead of throwing inside Pi's event loop.
+ */
+export declare function completeConfig(loaded: Partial<WardenConfig> | undefined): ShapeResult;
+export declare function shapeWarning(missing: readonly string[], loadedSchema: number | undefined): string;

package/dist/shape.js

@@ -0,0 +1,46 @@
+import { isMode } from "./config.js";
+/** The config layout this extension build expects; compared with the loaded config module's CONFIG_SCHEMA. */
+export const EXPECTED_SCHEMA = 3;
+const off = { enabled: false };
+const proseOff = () => ({ ...off, audience: "technical", threshold: 1, trend: 3, minChars: 1 });
+/**
+ * `loadConfig()` always returns a complete object, yet live sessions crashed at `config.slop.prose.enabled` after a package
+ * update. A partially updated module graph (extension from one version, config from another) is the only known way to get
+ * there. Whatever the cause, a missing section disables that guard and is reported instead of throwing inside Pi's event loop.
+ */
+export function completeConfig(loaded) {
+    const source = (loaded ?? {});
+    const missing = [];
+    const section = (key, fallback) => {
+        const value = source[key];
+        if (value !== undefined && value !== null && typeof value === "object")
+            return value;
+        missing.push(key);
+        return fallback;
+    };
+    const config = {
+        enabled: source.enabled ?? true,
+        typesafe: source.typesafe ?? false,
+        mode: isMode(source.mode) ? source.mode : "steer",
+        timeoutMs: source.timeoutMs ?? 5000,
+        maxRequests: source.maxRequests ?? 500,
+        steerVisible: source.steerVisible ?? false,
+        action: section("action", { ...off, tools: [], failOpen: true, timeoutMs: 5000, irreversible: { warn: 1, confirm: 1 }, offTask: { warn: 1, confirm: 1 } }),
+        stuck: section("stuck", { ...off, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 1, nudge: false }),
+        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: "" }),
+    };
+    if (typeof config.slop.prose !== "object" || config.slop.prose === null) {
+        missing.push("slop.prose");
+        config.slop = { ...config.slop, prose: proseOff() };
+    }
+    if (typeof config.widget.panelWidth !== "string" && typeof config.widget.panelWidth !== "number")
+        config.widget = { ...config.widget, panelWidth: "40%" };
+    return { config, missing };
+}
+export function shapeWarning(missing, loadedSchema) {
+    return `warden: config sections ${missing.join(", ")} are missing (config module schema ${loadedSchema ?? "pre-3"}, extension expects ${EXPECTED_SCHEMA}); those guards are off. This happens when pi-warden was updated while Pi was running: restart Pi (a /reload is not enough).`;
+}

package/dist/trace.js

@@ -40,7 +40,7 @@ export function actionDetails(verdict, extra = {}) {
     if (verdict.patterns.length)
         lines.push(`patterns: ${verdict.patterns.map(hit => `${hit.id} (${hit.severity})`).join(", ")}`);
     if (judgment) {
-        lines.push(`jev: irreversible ${percent(judgment.irreversible)} · off-task ${percent(judgment.offTask)} · ${judgment.scope.replace(/_/g, " ")} (${percent(judgment.scopeConfidence)})${judgment.approved !== undefined ? ` · approved ${percent(judgment.approved)}` : ""} · ${judgment.model} · ${judgment.elapsedMs} ms`);
+        lines.push(`jev: irreversible ${percent(judgment.irreversible)} · off-task ${percent(judgment.offTask)} · ${judgment.scope.replace(/_/g, " ")} (${percent(judgment.scopeConfidence)})${judgment.approved !== undefined ? ` · approved ${percent(judgment.approved)}` : ""}${judgment.mutates !== undefined ? ` · mutates ${percent(judgment.mutates)}` : ""} · ${judgment.model} · ${judgment.elapsedMs} ms`);
     }
     if (judgment?.securityRisk !== undefined)
         lines.push(`security risk: ${percent(judgment.securityRisk)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-warden",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "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",