pi-warden 0.9.0 → 0.9.1

package/README.md

@@ -6,6 +6,8 @@ A second pair of eyes for [Pi](https://pi.dev). It watches what the agent does,
 
 The verdicts above are real output from `npm run test:live`. Independent project; not affiliated with TypeSafe AI or the Pi authors. Built on [pi-typesafe](https://github.com/DevMortimer/pi-typesafe).
 
+Default configs and a starter rules file are in [`examples/`](examples/).
+
 ## What it does
 
 | Guard | Watches | Does |
@@ -42,6 +44,8 @@ Requires Pi 0.85 or newer and Node.js 22.19 or newer. Pattern checks work with n
 
 `TYPESAFE_API_KEY` in the environment takes precedence over the stored key. Headless runs give consent with `PI_WARDEN_ENABLED=1`.
 
+The [examples README](examples/README.md) walks through the starter `pi-warden.md`, the project `.pi/pi-warden.json`, and the user `config.json`.
+
 ## Philosophy
 
 pi-warden is a harness for the agent, not a gate for you. Three jobs:
@@ -72,7 +76,7 @@ The action guard receives your latest message plus up to eight earlier user and
 
 ### Rules
 
-Write your project's rules as Markdown headings in `pi-warden.md` at the project root:
+Write your project's rules as Markdown headings in `pi-warden.md` at the project root (a starter file with a dozen rules is in [`examples/pi-warden.md`](examples/pi-warden.md)):
 
 ```markdown
 # No console statements
@@ -226,7 +230,7 @@ User file `~/.pi/agent/pi-warden/config.json` (owner-only). Missing keys use the
 
 A project may add `.pi/pi-warden.json` with `enabled` and per-guard overrides: stricter thresholds, extra guarded tools, `rules.files`, `rules.skip`, `rules.sensitivePaths`, or `"done": { "enabled": false }`. Project files are read only when Pi trusts the project. They can never grant `typesafe` consent, change `mode`, raise `timeoutMs` or `maxRequests`, or set `notify.command`. Environment: `PI_WARDEN_ENABLED=1` (consent), `PI_WARDEN_MODE=steer|confirm|advise`.
 
-A wince-style setup for a backend repo:
+A wince-style setup for a backend repo (the full version is [`examples/pi-warden.json`](examples/pi-warden.json)):
 
 ```json
 {
@@ -256,7 +260,7 @@ Obvious credentials (`Authorization` headers, `TOKEN=` and `SECRET=` assignments
 
 ## After updating the package
 
-Run `/reload` in each open Pi session after an update. If a session reports `Cannot read properties of undefined (reading 'enabled')` while a fresh session works, restart it: the loaded modules do not match the files on disk. Since 0.5.2 the extension checks the shape of the config it receives; a missing section (an extension module and a config module from different versions in one process) switches that guard off and prints one warning naming the sections and the schema numbers. If you see it, restart Pi.
+Restart Pi after an update; `/reload` re-imports the entry module but can leave older modules of the same package in memory. Since 0.5.2 the extension checks the shape of the config it receives; a section that an older module does not know (the symptom of two package versions in one process) switches that guard off and prints one warning naming the sections and the schema numbers. 0.9.0 crashed instead when the shape-check module itself was the stale one; since 0.9.1 the extension guards the sections it reads in its own module, so the warning appears and everything else keeps working. If you see the warning, restart Pi.
 
 ## For extension authors
 

package/dist/extension.d.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ToolCallRef } from "./action-guard.js";
 import type { SlopSymptom, Verdict } from "./guard.js";
+import type { ShapeResult } from "./shape.js";
 export declare const disclosure = "With TypeSafe judgments enabled, pi-warden sends to api.typesafe.ai: your latest request and up to eight redacted prior user/assistant text messages for task context, plus a redacted, truncated summary of each guarded bash, write, or edit call before it runs; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; and redacted tool-output samples for security and context saving (retention and output format). Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 /**
  * Tool calls of the assistant message being preflighted. Pi runs `tool_call` hooks for sibling calls one after another,
@@ -10,5 +11,11 @@ export declare function siblingToolCalls(ctx: ExtensionContext): ToolCallRef[];
 export declare function confirmMessage(verdict: Verdict): string;
 /** Names each symptom and its fix; repeats in the session turn the note into a standing rule. */
 export declare function slopSteer(where: string, symptoms: readonly SlopSymptom[], counts: Record<SlopSymptom, number>): string;
+/**
+ * `completeConfig` in shape.ts fills sections an older config module lacks, but shape.ts can be the stale module too: the
+ * 0.8 version knew nothing of `rules`, so a 0.9 extension read `config.rules.enabled` on undefined and every tool call
+ * failed until Pi was restarted. The sections this build reads are therefore checked here as well, in the module that reads them.
+ */
+export declare function guardCurrentSections(result: ShapeResult): ShapeResult;
 /** Native Pi registration; importing the root library does not load this module. */
 export default function wardenExtension(pi: ExtensionAPI): void;

package/dist/extension.js

@@ -18,7 +18,7 @@ import { openTracePanel } from "./panel.js";
 import { completeConfig, shapeWarning } from "./shape.js";
 import { ContextLedger, formatLedger } from "./saver.js";
 import { actionDetails, doneDetails, proseDetails, rulesDetails, runawayDetails, stuckDetails, Trace } from "./trace.js";
-import { proseTokens, renderTemplate, TOKEN_NAMES } from "./widget.js";
+import { DEFAULT_TEMPLATES, 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; for a write or edit in a project with a rules file (pi-warden.md, the configured files, or README/CLAUDE/AGENTS as fallback), a larger redacted sample of the written content with the current file around each edit and the rule text; the last few tool calls and output tails when the agent keeps failing; the agent's final message when it reports completion without running checks; and redacted tool-output samples for security and context saving (retention and output format). Compression and duplicate notes store an exact, owner-only copy in a temporary file on this machine. Requests may incur charges. Secret redaction is best-effort. Results are model judgments, not proof or authorization; offline pattern checks stay active either way.";
 const WIDGET = PACKAGE_NAME;
 const CONFIRM_TEXT_LIMIT = 500;
@@ -115,6 +115,28 @@ export function slopSteer(where, symptoms, counts) {
     const standing = symptoms.some(symptom => counts[symptom] >= 3) ? " Treat this as a standing rule for the rest of the session." : "";
     return `pi-warden: the content just written to ${where} has ${named}. Fix it in your next edit: ${fixes}.${standing}`;
 }
+/**
+ * `completeConfig` in shape.ts fills sections an older config module lacks, but shape.ts can be the stale module too: the
+ * 0.8 version knew nothing of `rules`, so a 0.9 extension read `config.rules.enabled` on undefined and every tool call
+ * failed until Pi was restarted. The sections this build reads are therefore checked here as well, in the module that reads them.
+ */
+export function guardCurrentSections(result) {
+    const { config } = result;
+    const missing = [...result.missing];
+    if (typeof config.rules !== "object" || config.rules === null || !Array.isArray(config.rules.exclude)) {
+        if (!missing.includes("rules"))
+            missing.push("rules");
+        config.rules = { enabled: false, threshold: 1, files: [], fallback: false, maxChars: 500, exclude: [], skip: [], sensitivePaths: {} };
+    }
+    if (typeof config.widget !== "object" || config.widget === null) {
+        if (!missing.includes("widget"))
+            missing.push("widget");
+        config.widget = { ...defaultConfig().widget, enabled: false };
+    }
+    if (typeof config.widget.rules !== "string")
+        config.widget = { ...config.widget, rules: DEFAULT_TEMPLATES.rules };
+    return { config, missing };
+}
 /** Native Pi registration; importing the root library does not load this module. */
 export default function wardenExtension(pi) {
     let client;
@@ -144,7 +166,7 @@ export default function wardenExtension(pi) {
     // 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() }));
+        const { config, missing } = guardCurrentSections(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.

package/dist/guard.js

@@ -64,7 +64,8 @@ const GIT_MESSAGE_SUBCOMMANDS = new Set(["commit", "tag", "notes", "merge", "sta
 /** Interpreters whose stdin script can still run shell commands; their heredoc bodies stay in scope when they do. */
 const INTERPRETERS = /^(?:python[\d.]*|node|ruby|perl|php|deno|bun|tsx|Rscript|lua[\d.]*)$/;
 const EXEC_CALLS = /\b(?:os\.system|os\.popen|os\.exec\w*|subprocess|child_process|execSync|spawnSync|execFileSync|spawn\(|exec\(|system\(|popen\(|shell_exec|passthru|proc_open|Open3|IO\.popen|Deno\.run|Deno\.Command|Bun\.spawn|Bun\.\$|%x[\[{(]|`[^`\n]*\b(?:rm|git|dd|mkfs|kubectl|terraform)\b)/;
-const HEREDOC = /<<-?\s*(?:"(\w+)"|'(\w+)'|\\?(\w+))/;
+const HEREDOC = /<<-?\s*(?:"(\w+)"|'(\w+)'|(\\)?(\w+))/;
+const SUBSTITUTION = /\$\(|`/;
 function headOf(segment) {
     const tokens = segment.trim().split(/\s+/);
     let index = 0;
@@ -73,7 +74,10 @@ function headOf(segment) {
     const head = tokens[index];
     return head ? head.replace(/^.*\//, "") : undefined;
 }
-/** Quoted strings replaced by a placeholder; escapes inside double quotes are honoured, single quotes take everything. */
+/**
+ * Quoted strings replaced by a placeholder; escapes inside double quotes are honoured, single quotes take everything.
+ * A double-quoted string that substitutes a command (`"$(...)"`, backticks) executes it, so that string stays visible.
+ */
 function blankQuotes(segment) {
     let out = "";
     for (let index = 0; index < segment.length; index++) {
@@ -89,7 +93,8 @@ function blankQuotes(segment) {
             out += segment.slice(index);
             break;
         }
-        out += `${char}[text]${char}`;
+        const inner = segment.slice(index + 1, end);
+        out += char === "\"" && SUBSTITUTION.test(inner) ? `${char}${inner}${char}` : `${char}[text]${char}`;
         index = end;
     }
     return out;
@@ -111,8 +116,6 @@ function isDataSegment(segment) {
  * (`python3 - <<EOF`) are kept when the script calls out to a shell or process API.
  */
 export function stripDataText(command) {
-    if (/\$\(|`/.test(command))
-        return { text: command, stripped: false };
     const lines = command.split("\n");
     const out = [];
     let stripped = false;
@@ -123,14 +126,18 @@ export function stripDataText(command) {
             out.push(line);
             continue;
         }
-        const delimiter = heredoc[1] ?? heredoc[2] ?? heredoc[3];
-        const consumer = headOf(line.slice(0, heredoc.index)) ?? "";
+        const delimiter = heredoc[1] ?? heredoc[2] ?? heredoc[4];
+        // 'EOF', "EOF", and \EOF make the body literal; a bare EOF body is expanded, so a substitution inside it runs.
+        const literal = heredoc[4] === undefined || heredoc[3] !== undefined;
         const body = [];
         let close = index + 1;
         while (close < lines.length && lines[close].replace(/^\t+/, "") !== delimiter)
             body.push(lines[close]), close++;
         const bodyText = body.join("\n");
-        const executed = SHELL_SINKS.has(consumer) || (INTERPRETERS.test(consumer) && EXEC_CALLS.test(bodyText));
+        // The whole pipeline on the heredoc line counts: `cat <<EOF | bash` executes the body as much as `bash <<EOF` does.
+        const heads = splitShell(line).map(segment => headOf(segment) ?? "");
+        const consumer = headOf(line.slice(0, heredoc.index)) ?? "";
+        const executed = heads.some(head => SHELL_SINKS.has(head)) || (INTERPRETERS.test(consumer) && EXEC_CALLS.test(bodyText)) || (!literal && SUBSTITUTION.test(bodyText));
         out.push(line);
         if (executed)
             out.push(...body);
@@ -144,10 +151,11 @@ export function stripDataText(command) {
     }
     const joined = out.join("\n");
     const segments = splitShell(joined);
+    // A shell sink anywhere may run text written earlier in the same command (`cat <<EOF > run.sh` then `bash run.sh`), so nothing is treated as data.
     if (segments.some(segment => { const head = headOf(segment); return head !== undefined && SHELL_SINKS.has(head); }))
-        return { text: joined, stripped };
+        return { text: command, stripped: false };
     if (/\b(?:ba|z|da|k)?sh\s+-[a-zA-Z]*c\b/.test(joined))
-        return { text: joined, stripped };
+        return { text: command, stripped: false };
     let text = joined;
     for (const segment of segments) {
         if (!isDataSegment(segment) || !/["']/.test(segment))
@@ -162,13 +170,13 @@ export function stripDataText(command) {
 }
 /**
  * rm with both recursive and force flags. Absolute, home, variable, or wildcard targets are destructive; relative ones are
- * risky. A quote before `rm` is allowed so `bash -c "rm -rf /"` is read; data quotes were blanked before this runs.
+ * risky. A quote or parenthesis before `rm` is allowed so a quoted or substituted command is read; data quotes were blanked before this runs.
  */
 function classifyRm(segment, cwd) {
-    const match = /(?:^|[\s"'])rm\s+(.*)$/.exec(segment);
+    const match = /(?:^|[\s"'(])rm\s+(.*)$/.exec(segment);
     if (!match)
         return undefined;
-    const tokens = match[1].split(/\s+/).filter(Boolean).map(token => token.replace(/["']$/, ""));
+    const tokens = match[1].split(/\s+/).filter(Boolean).map(token => token.replace(/["')]+$/, ""));
     const flags = tokens.filter(token => token.startsWith("-"));
     const targets = tokens.filter(token => !token.startsWith("-"));
     const recursive = flags.some(flag => flag === "--recursive" || (/^-[a-zA-Z]+$/.test(flag) && /[rR]/.test(flag)));

package/examples/README.md

@@ -0,0 +1,45 @@
+# Get started with pi-warden
+
+Three files, each optional. Copy what you need and edit it.
+
+| File in this folder | Copy it to | What it does |
+| --- | --- | --- |
+| `pi-warden.md` | `<your project>/pi-warden.md` | Your project's rules. Each `#` heading is one rule; Jev judges every write and edit against them and tells the agent which rule it broke. |
+| `pi-warden.json` | `<your project>/.pi/pi-warden.json` | Project settings: which files the rules skip, which are never sent to Jev, sensitive paths that give the agent a note, tuned thresholds. Read only when Pi trusts the project. |
+| `config.json` | `~/.pi/agent/pi-warden/config.json` | Your personal settings: consent, mode, whether steers show in the transcript, the audience for reply checks, notifications. `/warden config` opens it in Pi's editor. |
+
+## Step by step
+
+1. Install and enable:
+
+   ```bash
+   pi install npm:pi-warden
+   ```
+
+   Then in Pi run `/warden enable`, read the notice, and paste a key from [console.typesafe.ai](https://console.typesafe.ai) if you have none stored. Without a key pi-warden still runs its offline pattern checks; the rules guard needs Jev.
+
+2. Copy `pi-warden.md` to your project root. Delete the rules you do not want, write your own. Run `/warden status`; the `Rules:` line should say `pi-warden.md (N rules)`.
+
+3. Ask the agent to write something that breaks a rule, for example "add a console.log to src/index.ts". The write goes through, the status line shows `warden · rules · write src/index.ts · N rules · No console output in library code 0.9x · violation`, and the agent gets the rule text as a steer. Open the trace (`ctrl+shift+w`) to read exactly what it was told.
+
+4. Optional: copy `pi-warden.json` to `.pi/pi-warden.json` for path scoping and sensitive-path notes, and `config.json` to `~/.pi/agent/pi-warden/config.json` for your own defaults.
+
+## Writing rules that work
+
+- One heading, one rule. Jev answers one question per rule, so a heading that bundles three things gets one blurry answer.
+- Say what a violation looks like. "A bare `TODO` without a ticket" beats "TODOs should be tidy".
+- Scope with `paths:` when a rule is language-specific or does not apply to tests. Globs: `**` any depth, `*` within one segment, a pattern without a slash matches at any depth.
+- Code fences inside a rule are fine; a `#` inside a fence is not read as a heading.
+- Rules cost tokens: one request per write or edit, roughly 600 tokens plus about 150 per rule plus the content sample. At most 31 rules are asked per request.
+- No `pi-warden.md`? pi-warden falls back to `README.md`, `CLAUDE.md`, or `AGENTS.md` and asks one question about the whole document (cut to `rules.maxChars`, headings kept). It works, but a dedicated rules file gives sharper answers and names the rule. Set `"rules": { "fallback": false }` to turn the fallback off.
+
+## Checking the rules from the command line
+
+```bash
+node -e '
+import("pi-warden").then(({ RuleStore, defaultConfig }) => {
+  const set = new RuleStore().load(process.cwd(), defaultConfig().rules);
+  for (const rule of set?.rules ?? []) console.log(rule.id, rule.paths.length ? rule.paths.join(",") : "(all files)");
+  if (set?.dropped) console.log(`${set.dropped} rules beyond the cap are ignored`);
+});'
+```

package/examples/config.json

@@ -0,0 +1,26 @@
+{
+  "typesafe": true,
+  "mode": "steer",
+  "steerVisible": false,
+  "rules": {
+    "fallback": true,
+    "maxChars": 8000
+  },
+  "slop": {
+    "prose": { "audience": "a founder without a programming background" }
+  },
+  "context": {
+    "confidence": 0.8,
+    "recallTool": "auto"
+  },
+  "notify": {
+    "enabled": true,
+    "cooldownMs": 10000,
+    "command": []
+  },
+  "widget": {
+    "placement": "aboveEditor",
+    "shortcut": "ctrl+shift+w",
+    "panelWidth": "40%"
+  }
+}

package/examples/pi-warden.json

@@ -0,0 +1,22 @@
+{
+  "rules": {
+    "threshold": 0.7,
+    "skip": ["tests/**", "test/**", "**/*.test.*", "**/*.spec.*", "docs/**", "**/*.md"],
+    "exclude": ["secrets/**", "**/*.pem", "**/*.key", "fixtures/**"],
+    "sensitivePaths": {
+      "**/migrations/**": "This touches a database migration: tell the user in your reply and make sure there is a rollback path",
+      "**/permissions*": "Access control changed: tell the user and ask for a security review before this is merged",
+      "**/auth/**": "Authentication code changed: tell the user; do not weaken any check without saying so",
+      ".github/workflows/**": "CI configuration changed: tell the user what the pipeline will now do differently"
+    }
+  },
+  "action": {
+    "tools": ["bash", "powershell", "ctx_execute", "ctx_batch_execute", "ctx_execute_file", "write", "edit"],
+    "irreversible": { "warn": 0.5, "confirm": 0.7 },
+    "offTask": { "warn": 0.6, "confirm": 0.85 }
+  },
+  "slop": {
+    "prose": { "audience": "technical" }
+  },
+  "done": { "enabled": true }
+}

package/examples/pi-warden.md

@@ -0,0 +1,53 @@
+Copy this file to the root of your project as `pi-warden.md` and edit it. Every `#` heading below is one rule. The text
+under a heading is what Jev reads when it judges a write or an edit. A `paths:` line right under a heading limits that rule
+to matching files. Text above the first heading, like this paragraph, is ignored, so keep the intro heading-free.
+
+Keep rules short and concrete. Say what a violation looks like. Jev is good at "must not contain X" and "every X needs a Y";
+it is worse at taste ("code should be clean").
+
+# No console output in library code
+paths: src/**
+Code under `src/` must not call `console.log`, `console.debug`, or `console.info`. Use the project logger or remove the
+call before committing. Tests and scripts may print.
+
+# TODO comments need a reference
+A `TODO` or `FIXME` comment must name a ticket or issue, for example `TODO(APP-123): ...`. A bare `TODO` is a violation.
+
+# No explicit any
+paths: **/*.ts, **/*.tsx
+Do not use the `any` type. Use a precise type, `unknown` with a runtime check, or a generic parameter.
+
+# Exported functions declare their return type
+paths: src/**/*.ts
+Every exported function or method declares its return type instead of relying on inference.
+
+# Errors are not swallowed
+A `catch` block must handle the error, log it with context, or rethrow it. An empty `catch`, or one that only has a comment
+such as `// ignore`, is a violation.
+
+# Switch statements have a default case
+Every `switch` has a `default` branch, even if it only throws on an unexpected value.
+
+# No hardcoded secrets
+Source code must not contain passwords, API keys, or tokens. They come from configuration or a secrets manager. A test fixture
+with an obviously fake value such as `test-key` is fine.
+
+# Boolean names read as a question
+A boolean variable or property starts with `is`, `has`, `should`, `can`, or a similar predicate prefix, for example
+`isEnabled`, not `enabled`.
+
+# New exported functions get a test
+paths: src/**
+A newly added exported function or class comes with at least one test that exercises its main behaviour. Changing an
+existing function does not require a new test by itself.
+
+# Comments explain why, not what
+A comment states a reason, a constraint, a workaround, or a non-obvious invariant. A comment that restates what the next line
+plainly does is a violation.
+
+# No commented-out code
+Delete code that is no longer used. Do not leave it behind as comments.
+
+# Migrations are reversible
+paths: **/migrations/**
+Every migration has a down step (or an explicit note in the file that the change cannot be reversed and why).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-warden",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "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, checks written code against your project rules, detects stuck loops, checks unverified done claims, and flags slop.",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,7 @@
   "files": [
     "dist",
     "extensions",
+    "examples",
     "README.md",
     "LICENSE"
   ],