pi-warden 0.5.0 → 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`.
@@ -112,11 +112,15 @@ The action guard receives the latest user message plus up to eight previous user
 | `/warden mode steer\|confirm\|advise` | Choose how holds are handled; without an argument, show the current mode |
 | `/warden config` | Edit the user config JSON in Pi's editor and save it |
 | `/warden test` | Evaluate one synthetic destructive action and show the verdict and what the agent would be told |
-| `/warden trace` | Open the trace panel (or print the last 20 events without a UI) |
+| `/warden trace` | Toggle the trace sidebar (or print the last 20 events without a UI) |
 
-## Status line and trace panel
+## Status line and trace sidebar
 
-The line above the editor shows the latest verdict per guard, for example `warden · bash · irreversible 0.84 · off-task 0.86 · unrelated · confirm`. Every verdict is also kept in a session trace with what was inspected (redacted command or path), the pattern hits, Jev's scores with model and latency, the reasons, and the exact text the agent was told. Open the panel with `/warden trace`, `ctrl+shift+w`, or by clicking the status line (clicks need Pi's fullscreen mode: `tuiMode: "fullscreen"` in settings, because regular mode leaves the mouse to the terminal). The panel is a right-hand overlay, newest first, live-updating while the agent works; ↑↓/PgUp/PgDn scroll, `c` clears, Esc closes.
+The line above the editor shows the latest verdict per guard, for example `warden · bash · irreversible 0.84 · off-task 0.86 · unrelated · confirm`. Every verdict is also kept in a session trace with what was inspected (redacted command or path), the pattern hits, Jev's scores with model and latency, the reasons, and the exact text the agent was told.
+
+`/warden trace`, `ctrl+shift+w`, and a click on the status line each **toggle a right-hand sidebar** with that trace, newest first, live-updating while the agent works. The sidebar does not take the keyboard: you keep typing in the editor while it is open. Click inside it to give it the keys (↑↓/PgUp/PgDn scroll, `c` clears, Esc hands input back to the editor, `q` closes); the wheel scrolls it without focus. `widget.panelWidth` sets its width (`"40%"` or a column count).
+
+Clicks and the wheel need Pi's fullscreen mode (`tuiMode: "fullscreen"` in `/settings`); regular mode leaves the mouse to the terminal for scrollback. If the mouse does nothing in fullscreen, the terminal is not reporting it: in macOS Terminal.app enable View → Allow Mouse Reporting (⌘R). Pi's extension API offers floating overlays but no side dock that narrows the transcript, so the sidebar covers the right part of the screen instead of pushing the transcript aside.
 
 Templates in `config.widget` control the text. Segments are separated by ` · `; a segment whose token has no value for that verdict is dropped, so optional information disappears together with its label:
 
@@ -125,6 +129,7 @@ Templates in `config.widget` control the text. Segments are separated by ` · `;
   "enabled": true,
   "placement": "aboveEditor",
   "shortcut": "ctrl+shift+w",
+  "panelWidth": "40%",
   "action": "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop: {slop} · patterns: {patterns} · {flags} · {level}",
   "stuck": "warden · stuck · {failures} failures · same strategy {sameStrategy} · change {approachChange} · progress {progress} · {flags} · {status}",
   "done": "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}",
@@ -163,7 +168,7 @@ User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use the
     "threshold": 0.7,
     "prose": { "enabled": true, "audience": "technical", "threshold": 0.7, "trend": 2, "minChars": 200 }
   },
-  "widget": { "enabled": true, "placement": "aboveEditor", "shortcut": "ctrl+shift+w" },
+  "widget": { "enabled": true, "placement": "aboveEditor", "shortcut": "ctrl+shift+w", "panelWidth": "40%" },
   "steerVisible": false
 }
 ```
@@ -179,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 {
@@ -128,6 +130,8 @@ function applyWidget(base, raw) {
         enabled: boolean(raw.enabled, base.enabled),
         placement: raw.placement === "belowEditor" || raw.placement === "aboveEditor" ? raw.placement : base.placement,
         shortcut: typeof raw.shortcut === "string" ? raw.shortcut.trim() : base.shortcut,
+        panelWidth: typeof raw.panelWidth === "number" && Number.isSafeInteger(raw.panelWidth) && raw.panelWidth >= 20 ? raw.panelWidth
+            : typeof raw.panelWidth === "string" && /^[1-9]\d?%$/.test(raw.panelWidth.trim()) ? raw.panelWidth.trim() : base.panelWidth,
         action: template(raw.action, base.action),
         stuck: template(raw.stuck, base.stuck),
         done: template(raw.done, base.done),

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.";
@@ -94,7 +96,7 @@ export default function wardenExtension(pi) {
     let stats = freshStats();
     const widget = new Map();
     const trace = new Trace();
-    let panelOpen = false;
+    let panel;
     let lastUi;
     /** Calls held in steer mode, with the user prompt current at that time; a retry after the user replies asks Jev about approval. */
     const held = new Map();
@@ -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) => {
@@ -118,11 +134,18 @@ export default function wardenExtension(pi) {
         if (ctx.hasUI)
             ctx.ui.notify(`warden: ${message}${budgetExhausted ? " Pattern checks continue without TypeSafe for the rest of this session." : ""}`, "warning");
     };
-    const openPanel = (ui) => {
-        if (!ui || panelOpen)
+    /** Click, shortcut, and /warden trace all toggle the same sidebar. */
+    const togglePanel = (ui, config) => {
+        if (!ui)
+            return;
+        if (panel) {
+            panel.close();
             return;
-        panelOpen = true;
-        openTracePanel(ui, trace).catch(() => undefined).finally(() => { panelOpen = false; });
+        }
+        const opened = openTracePanel(ui, trace, { width: config.widget.panelWidth });
+        panel = opened;
+        opened.closed.catch(() => undefined).finally(() => { if (panel === opened)
+            panel = undefined; });
     };
     const paint = (ctx, config) => {
         if (!ctx.hasUI)
@@ -137,7 +160,7 @@ export default function wardenExtension(pi) {
         ctx.ui.setWidget(WIDGET, (_tui, theme) => new MouseRegion(new Text(lines.map(line => theme.fg("muted", line)).join("\n"), 0, 0), event => {
             if (event.type !== "click" || event.button !== "left")
                 return undefined;
-            openPanel(lastUi);
+            togglePanel(lastUi, config);
             return { handled: true };
         }), { placement: config.widget.placement });
     };
@@ -153,6 +176,7 @@ export default function wardenExtension(pi) {
         stats = freshStats();
         widget.clear();
         trace.clear();
+        panel?.close();
         held.clear();
         attempts.reset();
         evidence = emptyEvidence();
@@ -372,9 +396,9 @@ export default function wardenExtension(pi) {
     const shortcut = loadConfig().widget.shortcut;
     if (/^(?:(?:ctrl|shift|alt|super)\+)+[a-z0-9]+$|^f\d{1,2}$/i.test(shortcut)) {
         pi.registerShortcut(shortcut, {
-            description: "Open the pi-warden trace panel",
+            description: "Toggle the pi-warden trace sidebar",
             handler: async (ctx) => { if (ctx.hasUI)
-                openPanel(ctx.ui); },
+                togglePanel(ctx.ui, configFor(ctx)); },
         });
     }
     const actions = ["status", "enable", "disable", "mode", "config", "test", "trace"];
@@ -405,7 +429,7 @@ export default function wardenExtension(pi) {
                         `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}.`,
                         `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). Widget templates in config.widget: action tokens ${TOKEN_NAMES.action.map(name => `{${name}}`).join(" ")}.`,
+                        `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(" ")}.`,
                     ].join(" "));
                     return;
                 }
@@ -415,7 +439,7 @@ export default function wardenExtension(pi) {
                         report(entries.length ? entries.slice(-20).map(entry => `${new Date(entry.at).toTimeString().slice(0, 8)} ${entry.guard}: ${entry.line}${entry.details.length ? `\n  ${entry.details.join("\n  ")}` : ""}`).join("\n") : "No guarded activity yet this session.");
                         return;
                     }
-                    openPanel(ctx.ui);
+                    togglePanel(ctx.ui, config);
                     return;
                 }
                 if (action === "enable") {

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

@@ -4,25 +4,35 @@ interface ThemeLike {
     fg(color: string, text: string): string;
     bold(text: string): string;
 }
+export interface PanelActions {
+    /** Remove the sidebar. */
+    close(): void;
+    /** Keep the sidebar visible but give keyboard input back to the editor. */
+    unfocus(): void;
+}
 /**
- * Side panel listing the trace newest-first, live-updating while open. Keys: ↑/↓/j/k scroll a line, PgUp/PgDn a page,
- * Home/End jump, c clears the trace, Esc or q closes. Wheel scrolling works in fullscreen mode.
+ * Sidebar listing the trace newest-first, live-updating while open. It opens without taking keyboard input: the editor
+ * keeps working while it is visible. A click inside it (fullscreen mode) focuses it; then ↑/↓/j/k scroll a line,
+ * PgUp/PgDn a page, Home/End jump, c clears the trace, Esc returns input to the editor, and q closes. Wheel scrolling
+ * works without focus.
  */
 export declare class TracePanel implements Component {
     private readonly trace;
     private readonly theme;
-    private readonly close;
+    private readonly actions;
     private readonly requestRender;
     private readonly title;
+    /** Set by the TUI when keyboard focus changes. */
     focused: boolean;
     private scroll;
     private viewport;
     private readonly unsubscribe;
-    constructor(trace: Trace, theme: ThemeLike, close: () => void, requestRender: () => void, title?: string);
+    constructor(trace: Trace, theme: ThemeLike, actions: PanelActions, requestRender: () => void, title?: string);
     dispose(): void;
     /** Rendering is cheap and derived from the trace each time; nothing is cached. */
     invalidate(): void;
     private lines;
+    /** A left border makes the overlay read as a pane; the content column is two cells narrower. */
     render(width: number): string[];
     /** The overlay tells us how tall we may be through the layout; fall back to a fixed viewport otherwise. */
     setViewport(rows: number): void;
@@ -39,6 +49,16 @@ export interface PanelUi {
         dispose?(): void;
     }, options?: Record<string, unknown>): Promise<T>;
 }
-/** Open the trace as a right-hand overlay. Resolves when the user closes it. */
-export declare function openTracePanel(ui: PanelUi, trace: Trace): Promise<void>;
+export interface PanelController {
+    /** Resolves when the sidebar has been removed, by the user or by close(). */
+    closed: Promise<void>;
+    close(): void;
+}
+/**
+ * Open the trace as a right-hand sidebar. Pi's public UI API offers floating overlays but no side dock that narrows the
+ * transcript, so the sidebar covers the right part of the screen; `nonCapturing` keeps the editor focused.
+ */
+export declare function openTracePanel(ui: PanelUi, trace: Trace, options?: {
+    width?: string | number;
+}): PanelController;
 export {};

package/dist/panel.js

@@ -1,23 +1,26 @@
 import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 const LEVEL_COLOR = { allow: "success", ok: "success", warn: "warning", unverified: "warning", nudged: "warning", confirm: "error", stuck: "error", "false claim": "error" };
 /**
- * Side panel listing the trace newest-first, live-updating while open. Keys: ↑/↓/j/k scroll a line, PgUp/PgDn a page,
- * Home/End jump, c clears the trace, Esc or q closes. Wheel scrolling works in fullscreen mode.
+ * Sidebar listing the trace newest-first, live-updating while open. It opens without taking keyboard input: the editor
+ * keeps working while it is visible. A click inside it (fullscreen mode) focuses it; then ↑/↓/j/k scroll a line,
+ * PgUp/PgDn a page, Home/End jump, c clears the trace, Esc returns input to the editor, and q closes. Wheel scrolling
+ * works without focus.
  */
 export class TracePanel {
     trace;
     theme;
-    close;
+    actions;
     requestRender;
     title;
-    focused = true;
+    /** Set by the TUI when keyboard focus changes. */
+    focused = false;
     scroll = 0;
     viewport = 20;
     unsubscribe;
-    constructor(trace, theme, close, requestRender, title = "pi-warden trace") {
+    constructor(trace, theme, actions, requestRender, title = "pi-warden trace") {
         this.trace = trace;
         this.theme = theme;
-        this.close = close;
+        this.actions = actions;
         this.requestRender = requestRender;
         this.title = title;
         this.unsubscribe = trace.subscribe(() => this.requestRender());
@@ -31,10 +34,13 @@ export class TracePanel {
         const { theme } = this;
         const entries = this.trace.entries();
         const out = [];
-        out.push(theme.bold(theme.fg("accent", ` ${this.title}`)) + theme.fg("muted", ` · ${entries.length} event${entries.length === 1 ? "" : "s"} · ↑↓ PgUp PgDn scroll · c clear · esc close`));
+        const keys = this.focused ? "↑↓ PgUp PgDn scroll · c clear · esc back to editor · q close" : "click for keys · wheel scrolls · /warden trace closes";
+        out.push(theme.bold(theme.fg("accent", `${this.title}`)) + theme.fg("muted", ` · ${entries.length} event${entries.length === 1 ? "" : "s"}`));
+        out.push(theme.fg("muted", keys));
         out.push(theme.fg("muted", "─".repeat(Math.max(0, width))));
         if (!entries.length) {
-            out.push(theme.fg("muted", " No guarded activity yet this session. Verdicts, Jev scores, and what the agent was told will appear here."));
+            for (const line of wrapTextWithAnsi(theme.fg("muted", "No guarded activity yet this session. Verdicts, Jev scores, and what the agent was told will appear here."), Math.max(10, width)))
+                out.push(line);
             return out.map(line => truncateToWidth(line, width, ""));
         }
         for (let index = entries.length - 1; index >= 0; index--) {
@@ -56,25 +62,35 @@ export class TracePanel {
         }
         return out.map(line => truncateToWidth(line, width, ""));
     }
+    /** A left border makes the overlay read as a pane; the content column is two cells narrower. */
     render(width) {
-        const all = this.lines(width);
+        const border = theme_fg(this.theme, "muted", "│ ");
+        const inner = Math.max(10, width - 2);
+        const all = this.lines(inner);
         const maxScroll = Math.max(0, all.length - this.viewport);
         if (this.scroll > maxScroll)
             this.scroll = maxScroll;
         const visible = all.slice(this.scroll, this.scroll + this.viewport);
         if (all.length > this.viewport) {
             const last = visible.length - 1;
-            visible[last] = truncateToWidth(theme_fg(this.theme, "muted", ` … ${all.length - this.scroll - this.viewport > 0 ? `${all.length - this.scroll - this.viewport} more lines below` : "end"} · ${this.scroll} above`), width, "");
+            visible[last] = truncateToWidth(theme_fg(this.theme, "muted", `… ${all.length - this.scroll - this.viewport > 0 ? `${all.length - this.scroll - this.viewport} more lines below` : "end"} · ${this.scroll} above`), inner, "");
         }
-        return visible;
+        while (visible.length < this.viewport)
+            visible.push("");
+        return visible.map(line => border + line);
     }
     /** The overlay tells us how tall we may be through the layout; fall back to a fixed viewport otherwise. */
     setViewport(rows) {
         this.viewport = Math.max(5, rows);
     }
     handleInput(data) {
-        if (matchesKey(data, Key.escape) || data === "q" || matchesKey(data, Key.ctrl("c"))) {
-            this.close();
+        if (data === "q" || matchesKey(data, Key.ctrl("c"))) {
+            this.actions.close();
+            return;
+        }
+        if (matchesKey(data, Key.escape)) {
+            this.actions.unfocus();
+            this.requestRender();
             return;
         }
         if (matchesKey(data, Key.up) || data === "k")
@@ -100,22 +116,32 @@ export class TracePanel {
             this.scroll = Math.max(0, this.scroll + (event.wheelDelta ?? 0) * 3);
             return { handled: true, render: true };
         }
+        if (event.type === "press" && event.button === "left")
+            return { handled: true, focus: true, render: true };
         return undefined;
     }
 }
 function theme_fg(theme, color, text) {
     return theme.fg(color, text);
 }
-/** Open the trace as a right-hand overlay. Resolves when the user closes it. */
-export function openTracePanel(ui, trace) {
-    return ui.custom((tui, theme, _keybindings, done) => {
-        const panel = new TracePanel(trace, theme, () => done(), () => tui.requestRender());
+/**
+ * Open the trace as a right-hand sidebar. Pi's public UI API offers floating overlays but no side dock that narrows the
+ * transcript, so the sidebar covers the right part of the screen; `nonCapturing` keeps the editor focused.
+ */
+export function openTracePanel(ui, trace, options = {}) {
+    let close = () => { };
+    let unfocus = () => { };
+    const closed = ui.custom((tui, theme, _keybindings, done) => {
+        close = () => done();
+        const panel = new TracePanel(trace, theme, { close, unfocus: () => unfocus() }, () => tui.requestRender());
         const rows = tui.terminal?.rows;
         if (typeof rows === "number")
-            panel.setViewport(Math.floor(rows * 0.9) - 2);
+            panel.setViewport(rows - 2);
         return panel;
     }, {
         overlay: true,
-        overlayOptions: { anchor: "right-center", width: "48%", minWidth: 56, maxHeight: "90%", margin: { right: 1 } },
+        overlayOptions: { anchor: "right-center", width: options.width ?? "40%", minWidth: 44, maxHeight: "100%", nonCapturing: true },
+        onHandle: (handle) => { unfocus = () => handle.unfocus(); },
     });
+    return { closed, close: () => close() };
 }

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

@@ -6,8 +6,10 @@ export type WidgetPlacement = "aboveEditor" | "belowEditor";
 export interface WidgetConfig {
     enabled: boolean;
     placement: WidgetPlacement;
-    /** Keyboard shortcut that opens the trace panel; empty string disables it. */
+    /** Keyboard shortcut that toggles the trace sidebar; empty string disables it. */
     shortcut: string;
+    /** Sidebar width: a percentage string such as "40%" or a column count. */
+    panelWidth: string | number;
     /** Templates per guard. Segments are separated by " · "; a segment whose token has no value is dropped. */
     action: string;
     stuck: string;

package/dist/widget.js

@@ -7,7 +7,7 @@ export const DEFAULT_TEMPLATES = {
     context: "warden · context · {tool} · {retention} · saved {bytesSaved} bytes",
 };
 export function defaultWidgetConfig() {
-    return { enabled: true, placement: "aboveEditor", shortcut: "ctrl+shift+w", ...DEFAULT_TEMPLATES };
+    return { enabled: true, placement: "aboveEditor", shortcut: "ctrl+shift+w", panelWidth: "40%", ...DEFAULT_TEMPLATES };
 }
 const SEPARATOR = " · ";
 const TOKEN = /\{([a-zA-Z]+)\}/g;

package/package.json

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