pi-warden 0.5.1 → 0.5.3

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`.
@@ -96,6 +96,8 @@ Written code gets a `security_risk` question in the existing action request: har
 
 For a single text block of at least `context.tailMinChars`, the same output request asks Jev to choose `all`, `errors_and_summary`, or `summary_only`. The full result stays when P(keep all) exceeds `1 - context.confidence` (default: keep when Jev gives `all` more than 0.2), when the probability is missing, or on any request error. Code—not Jev—keeps bounded diagnostic/head/tail excerpts. An exact copy is written to an owner-only temporary directory before replacement; the excerpt links to it. If storage fails, the original stays. Multiple text blocks keep their layout and are not compressed. Trace and widget show the actual bytes saved. No extra steer is persisted for compression alone.
 
+**Measuring it.** `/warden status` keeps a session ledger so the saver's value is a number, not a claim: how many outputs were large enough to consider, how many Jev compressed, the bytes removed (≈ tokens at 4 bytes each), the *token-turns spared* (removed tokens × every later turn, which is what a prompt cache would otherwise have re-read), and **recalls** — how often the agent went back and read the stored full output. A recall means the excerpt was not enough; a recall rate above about 10% says `context.confidence` is too low for your work, near 0% says it could go lower. Every compression and recall also appears in the trace with the running ledger. The quality effect (less context rot) does not show in a counter; compare a scripted task with `context.enabled` on and off if you want that number.
+
 This MVP is always tail-only: set `context.enabled: false` to stop compression. It never prunes a warm prefix, changes the system prompt, or edits historical session entries. Full-output files can contain secrets; they remain in the OS temporary directory until you or the OS remove them. Excerpts can omit relevant evidence; read the linked file before making a decision that needs it.
 
 ### Task continuity
@@ -184,7 +186,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,8 @@ 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 { ContextLedger, formatLedger } from "./saver.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 +106,22 @@ 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() });
+    const ledger = new ContextLedger();
+    // 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) => {
@@ -166,6 +184,7 @@ export default function wardenExtension(pi) {
         evidence = emptyEvidence();
         doneNudged = false;
         prose.reset();
+        ledger.reset();
         for (const symptom of Object.keys(slopCounts))
             slopCounts[symptom] = 0;
         if (ctx.hasUI)
@@ -180,9 +199,19 @@ export default function wardenExtension(pi) {
     pi.on("agent_start", async () => {
         evidence = emptyEvidence();
     });
+    // Every turn that runs after a compression is a turn that did not carry the removed text.
+    pi.on("turn_end", async () => {
+        ledger.turnEnd();
+    });
     pi.on("tool_call", async (event, ctx) => {
         const config = configFor(ctx);
-        if (!config.enabled || !config.action.enabled || !config.action.tools.includes(event.toolName))
+        if (!config.enabled)
+            return;
+        // A read of a stored full output means the excerpt was not enough; that is the number that tunes context.confidence.
+        const recalled = ledger.noteAccess(JSON.stringify(event.input));
+        if (recalled)
+            record(ctx, config, "context", renderTemplate(config.widget.context, { tool: event.toolName, retention: "full output recalled" }), [`the agent went back to ${recalled}`, formatLedger(ledger.snapshot())]);
+        if (!config.action.enabled || !config.action.tools.includes(event.toolName))
             return;
         stats.inspected++;
         const task = latestUserPrompt(ctx);
@@ -267,6 +296,8 @@ export default function wardenExtension(pi) {
             noteError(ctx, output.error, output.errorCode);
         let content = event.content;
         const notice = securityNotice(output);
+        if (config.context.enabled && textBlocks.length === 1 && text.length >= config.context.tailMinChars)
+            ledger.candidate();
         const excerpt = compressOutput(text, output.retention);
         if (excerpt && !ctx.signal?.aborted) {
             try {
@@ -275,9 +306,11 @@ export default function wardenExtension(pi) {
                 const bytesSaved = Buffer.byteLength(text) - Buffer.byteLength(replacement) - (notice ? Buffer.byteLength(notice) * 2 + 4 : 0);
                 if (bytesSaved > 0) {
                     content = content.map(part => part.type === "text" ? { ...part, text: replacement } : part);
+                    ledger.record(path, bytesSaved);
                     record(ctx, config, "context", renderTemplate(config.widget.context, { tool: event.toolName, retention: output.retention, bytesSaved: String(bytesSaved) }), [
                         `retention: ${output.retention}; confidence ${output.confidence?.toFixed(2)}; ${output.model}; ${output.elapsedMs} ms`,
                         `saved ${bytesSaved} bytes; full output: ${path}`,
+                        formatLedger(ledger.snapshot()),
                     ]);
                 }
             }
@@ -411,6 +444,7 @@ export default function wardenExtension(pi) {
                         `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}.`,
+                        formatLedger(ledger.snapshot()),
                         `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

@@ -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,11 @@ 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 { ContextLedger, formatLedger } from "./saver.js";
+export type { ContextLedgerSnapshot } from "./saver.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,9 @@ 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 { ContextLedger, formatLedger } from "./saver.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/saver.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Session accounting for the context saver, so its value can be measured instead of assumed:
+ * how often large outputs appear, how many were compressed, how much was removed, how many turns that removal was
+ * spared from (token-turns), and how often the agent went back for the full text (a recall means the excerpt was
+ * not enough). Deterministic; no requests.
+ */
+export interface ContextLedgerSnapshot {
+    /** Single-text-block outputs at or above tailMinChars, i.e. candidates for compression. */
+    large: number;
+    compressed: number;
+    bytesSaved: number;
+    /** Assistant turns completed since the session started. */
+    turns: number;
+    /** Sum over turns of the bytes that were no longer in context on that turn, in rough tokens (bytes / 4). */
+    tokenTurnsSaved: number;
+    /** Times the agent read a stored full output after compression. */
+    recalls: number;
+}
+export declare class ContextLedger {
+    private large;
+    private compressed;
+    private bytesSaved;
+    private turns;
+    private tokenTurnsSaved;
+    private recalls;
+    private readonly stored;
+    candidate(): void;
+    record(path: string, bytesSaved: number): void;
+    /** One LLM turn finished: everything removed so far was absent from this turn's prompt. */
+    turnEnd(): void;
+    /** True when `text` (a path, command, or serialized input) mentions a stored full output for the first time. */
+    noteAccess(text: string): string | undefined;
+    snapshot(): ContextLedgerSnapshot;
+    reset(): void;
+}
+/** One line for /warden status. Says when there is nothing to report instead of printing zeros. */
+export declare function formatLedger(snapshot: ContextLedgerSnapshot): string;

package/dist/saver.js

@@ -0,0 +1,55 @@
+export class ContextLedger {
+    large = 0;
+    compressed = 0;
+    bytesSaved = 0;
+    turns = 0;
+    tokenTurnsSaved = 0;
+    recalls = 0;
+    stored = new Map();
+    candidate() {
+        this.large++;
+    }
+    record(path, bytesSaved) {
+        this.compressed++;
+        this.bytesSaved += bytesSaved;
+        this.stored.set(path, { recalled: false });
+    }
+    /** One LLM turn finished: everything removed so far was absent from this turn's prompt. */
+    turnEnd() {
+        this.turns++;
+        this.tokenTurnsSaved += Math.round(this.bytesSaved / 4);
+    }
+    /** True when `text` (a path, command, or serialized input) mentions a stored full output for the first time. */
+    noteAccess(text) {
+        for (const [path, state] of this.stored) {
+            if (!text.includes(path))
+                continue;
+            if (!state.recalled) {
+                state.recalled = true;
+                this.recalls++;
+            }
+            return path;
+        }
+        return undefined;
+    }
+    snapshot() {
+        return { large: this.large, compressed: this.compressed, bytesSaved: this.bytesSaved, turns: this.turns, tokenTurnsSaved: this.tokenTurnsSaved, recalls: this.recalls };
+    }
+    reset() {
+        this.large = 0;
+        this.compressed = 0;
+        this.bytesSaved = 0;
+        this.turns = 0;
+        this.tokenTurnsSaved = 0;
+        this.recalls = 0;
+        this.stored.clear();
+    }
+}
+/** One line for /warden status. Says when there is nothing to report instead of printing zeros. */
+export function formatLedger(snapshot) {
+    if (snapshot.large === 0)
+        return "Context saver: no tool output large enough to consider this session.";
+    const kb = (snapshot.bytesSaved / 1024).toFixed(1);
+    const recallRate = snapshot.compressed ? Math.round((snapshot.recalls / snapshot.compressed) * 100) : 0;
+    return `Context saver: ${snapshot.large} large outputs, ${snapshot.compressed} compressed, ${kb} KB removed (~${Math.round(snapshot.bytesSaved / 4)} tokens), ~${snapshot.tokenTurnsSaved} token-turns spared over ${snapshot.turns} turns, ${snapshot.recalls} recall${snapshot.recalls === 1 ? "" : "s"} of the full output (${recallRate}%).`;
+}

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.3",
   "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",