pi-warden 1.0.0 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,96 @@ How to keep this current: add the entry in the same pull request as the change,
 
 ## Unreleased
 
+## 1.4.0
+
+### Added
+
+- When the session runs in a [herdr](https://herdr.dev) pane, a warden confirm dialog now reports through herdr's `herdr:blocked` channel while it waits, so the pane's sidebar shows blocked instead of working. Interactive sessions only; no emission on hold-steers or headless runs. ([Guards](docs/guards.md#herdr-pane-state))
+
+## 1.3.1
+
+### Fixed
+
+- The commands that send their own prompt to the agent (`/warden init`, `/warden rules tune`, `/warden audit`, `/warden index`) no longer swallow it. Each set its busy flag before `sendUserMessage`, and the busy-flag guard on the `input` event saw the command's own prompt (which arrives with `source: "extension"`) and answered "handled", so no run ever started and the command reported the file (or report, or index) was never created — every time, deterministically. The guard now waits only for operator input (`interactive`/`rpc`); warden's own prompt passes and, like any user prompt, invalidates in-flight conscience assessments.
+- Those commands also no longer report before the run they injected ends. Pi's extension-facing `sendUserMessage` is fire-and-forget, so the `await ctx.waitForIdle()` that followed it could return before the injected run even flipped the session busy — the command reported while the agent was still working, or its status message was steered into the next run instead of recorded. Each command now waits in two phases: first for `before_agent_start` carrying the prompt it sent (30 seconds; on a miss — a preflight failure or another extension handling the input — it clears its flag and reports right away instead of blocking operator input), then for `agent_end` of that run with no cap (pi emits it on an abort too, so Esc still ends the wait), and finally for the host to go idle so the status message is recorded rather than steered.
+
+### Tests
+
+- A real-session e2e runs `/warden init` the way Pi does (the shipped entry in a real agent session with a scripted model): the injected prompt reaches the model, the agent's write call lands, and "pi-warden.md created" is recorded only after the run ended. Two unit tests pin the guard (extension input passes while a flag is set, operator input waits) and the wait (the command does not report before the run starts or ends). The session-test `write` stub now really writes, relative to the session directory, so the e2e can prove the file on disk.
+## 1.3.0
+
+### Added
+
+- The cause-check guard (on by default, `cause.enabled`): when the final reply of a run states a likely cause, or asks a person to check something the agent could inspect itself, and no tool result in that run checked it, pi-warden sends the reply back with one follow-up turn: check the cause with its own tools (a query, a log, a file, or a command) and give the evidence, or say plainly that the cause is unverified and why it cannot check it. It is the sibling of the done-check. An offline pre-filter (`causePreFilter`) fires on causal and hand-off wording, so a reply about results or next steps spends no request; the guard asks Jev whether the reply states a cause or hands off a check, whether the run checked it, and, when the project has an earlier unchecked cause inside the window, which earlier cause the reply repeats. The request carries the task, the final message, the last 40 of the run's tool calls, and up to five earlier redacted cause sentences with their keys and dates. Each unchecked cause is stored per project for `cause.windowDays` (default 7) as the redacted sentence that states it; a later reply whose cause Jev matches to an earlier one gets a stronger steer that names the earlier date, and a reply that hands a check to a person gets a steer that says so. When the done-check steers the same reply, the cause-check records its decision in the trace and sends no steer, so one reply gets at most one end-of-run steer. The repeat history lives in a `causes` table in the same owner-only database as the hold log, and every request, stored summary, and trace line passes through `redact()`.
+
+### Docs
+
+- `docs/guards.md` describes the new cause-check; `docs/configuration.md` lists its keys, widget template, and tokens; `docs/data-handling.md` and the consent notice name the cause-check request and its stored repeat history; `README.md` lists the guard next to the done-check.
+- `eval/reports/2026-10-07-cause-check/` measures the offline pre-filter on recorded sessions: the totals, the flagged count, and how many of a 20-reply sample were real unchecked causes.
+
+## 1.2.0
+
+### Added
+
+- The action guard reads a script a command runs from disk and applies the same pattern floor and ask gate to its body: `bash FILE`, `./FILE`, `source FILE` and `. FILE`, `npm`/`pnpm`/`yarn`/`bun` scripts from `package.json` (with `preNAME` and `postNAME`), `make TARGET` or the default target, and `node`/`python`/`python3`/`ruby`/`perl`/`deno run FILE`. A body is read only when it resolves, after symlinks, inside the project root or a temp root, as a regular file of at most 64 KB, and one level deep. A body hit keeps the id and severity it has when typed directly and its label names the source (`(via cleanup.sh)`, `(via npm run clean)`); `action.exemptRules` and user `commandRules` apply to it; a body hit makes the ask gate ask with `runs a script with <shape>`; and the body lines that hit ride the request to Jev as `script_lines`, redacted and bounded to five lines and 600 characters.
+
+- `/warden status` shows the build that runs: the pi-warden version, the checkout commit when the package is a git tree, the `dist/extension.js` build time, and the loaded pi-typesafe version. Session start warns once when a `src/` file is newer than the build (`pi-warden runs an old build: run npm run build`) and once when the loaded pi-typesafe version is outside the range in `package.json`.
+
+### Changed
+
+- The done-check nudge names one check command instead of "whatever exists": the last check that passed earlier in this session in this project, else the `check` then `test` script of the project's `package.json` run with the package manager its lock file names (`pnpm-lock.yaml`, `yarn.lock`, `bun.lockb` or `bun.lock`, else npm), else the same `Makefile` targets; with none of those it keeps the generic ask. The UI nudge names the last local URL a tool result printed this session (`http://localhost:PORT`, `127.0.0.1`, `[::1]`) when there is one.
+- Done-check UI proof now counts only what shows the page to the agent: a successful tool result that contains an image, a page text snapshot (`agent-browser snapshot`, `agent-browser get text`, the MCP `take_snapshot` tool), a browser or device test run (`playwright test`, `flutter test` with `integration_test` or golden tests), or a `read` of an image file. A screenshot command that only writes a file (`agent-browser screenshot PATH`, `idb screenshot`, `xcrun simctl io … screenshot`, `chrome --headless --screenshot`), `agent-browser` `open`/`close`/`click`/`fill`/`set`/`wait`/`eval`, and MCP navigation tools no longer count; a saved screenshot counts once something reads it. The `done.visualTools` defaults match, and every config key still works.
+- pi-typesafe `^0.9.1` (was `^0.9.0`).
+- `npm run check` builds before it tests, so the offline suite exercises a fresh `dist/` (the entry Pi ships) instead of a stale one.
+
+### Fixed
+
+- The done-check counts a shell command as a check only when a check runner starts one of its shell segments, after `cd DIR`, environment assignments, and `timeout`/`time`/`env`/`npx`/`pnpm exec`/`bunx`/`yarn`/`uv run`/`poetry run`/`python -m` wrappers (a wrapper is stripped only when what follows does not start a runner, so `yarn test` and `yarn run lint` are checks). A runner name in an argument (`grep -n jest package.json`, `which eslint`, `npm view vitest version`) no longer counts as a check.
+- A check run counts as proof only when it really ran and its output agrees: a failure summary is a failed check even with exit code 0, and a visible failure stays a failed check also with a passing summary; a summary that reports zero tests (`Tests: 0 total`, `[no tests to run]`, and similar) is never a check, unless a line of the output shows tests did run (cargo doc-tests after real results, a package a `go test` filter skipped); and when the shell can hide the exit code of any runner segment (a pipe right after its segment without `set -o pipefail`, or a `||`, `;`, or newline with more commands anywhere after it) the exit code is no proof — with no runner summary the run is not a check at all. Each run that names a runner but does not count gets one trace-only detail with the reason and no command; the reason names the word after the hiding separator only when it is a bare command name.
+- The done-check reads more runner summaries as proof: vitest, pytest without the `===` frame (`-q`), mypy, ruff (check, format, and `--fix`), black, prettier, biome, tsc pretty output, eslint, bun, mocha, playwright, flutter, deno, and cargo build, check and clippy; and the generic wrapper failure lines (`make: *** … Error N`, `npm error Lifecycle script … failed`, `npm ERR! code ELIFECYCLE`, pnpm and yarn `Command failed with exit code N`). The generic lines decide only when a runner starts the command, so a failed `npm install` is not a failed check. A failure marker anywhere in the tail wins over a passing one (black and ruff format `N files would be reformatted` beside `N files would be left unchanged.`, any go `FAIL` line, any cargo `test result: FAILED.` after an `ok`, pytest `2 passed, 1 error`, an indented or `pkg:test:`-prefixed vitest summary), a generic failure line overrides a passing summary in the same output, and the `Finished` line proves a `cargo build`, `cargo check` or `cargo clippy` segment only.
+- The done-check recognises more runner forms and reports: a runner started by a path (`.venv/bin/pytest`, `node_modules/.bin/tsc`), `python3.12 -m` and `.venv/bin/python -m` followed by a runner or `unittest`, wrappers with options (`timeout -s KILL 60`, `uv run --with httpx`, `npx -y`), package-manager options (`pnpm -C web test`, `npm --prefix web test`, `yarn workspace api test`), `make -C web test`, and `bash -c "npm test"`; the last exit code the agent printed with `echo`/`printf` (`$?`, or `${PIPESTATUS[0]}` after a pipe); a silent runner (`tsc`, `eslint`, `flake8`, `go vet`, `go build`) named in its own segment whose output is empty behind a pipe to `tail`, `head`, `tee`, or `cat`; and a hidden runner is covered only by its own printed exit code, its own silent pass, or a summary verdict. A command is first stripped of data text and a backslash-newline continuation is joined, so a runner word in a commit message or heredoc body is not a check. A bare `npm ci` or `bun ci` installs and does not count, a runner sent to the background with `&` does not count, and a visible failure stays a failed check when another runner's exit code is hidden.
+- With pi-typesafe 0.9.1 the usage ledger no longer loses counts when several Pi sessions run at once, so the reported spend and the daily caps count every session.
+
+### Tests
+
+- A new offline session test loads pi-warden the way Pi does (`package.json` → `pi.extensions` → `extensions/index.js` → `dist/extension.js`) into a real agent session with a scripted model, and asserts on the session's messages: a held destructive bash call, a done-check nudge after an unverified completion, and the repeat note after the same failing read twice. It fails with `run npm run build first` when the shipped entry is missing.
+
+### Docs
+
+- `docs/commands.md` describes the `/warden status` build line; `docs/ci-cd.md` states the new `npm run check` order (typecheck, build, offline tests).
+
+
+
+
+## 1.1.2
+
+### Fixed
+
+- The build removes `dist/` outputs whose `src/` source is gone. `tsc` never deletes an output whose source was removed, so stale files from other branches shipped with `1.1.1`: 17 files (`conscience-config`, `conscience-loader`, `conscience-policy`, `conscience-privacy`, `jev`, `laya-download`, `laya-judge`, `tool-recommendation`, each as `.js` and `.d.ts`, plus `extension.js.bak`) that nothing imports. Users need to do nothing.
+
+## 1.1.1
+
+### Fixed
+
+- `scripts/live-smoke.mjs` and `scripts/security-cases.mjs` no longer crash when a verdict has no off-task answer, which is now the usual case: the acting request does not ask `off_task`, only the trace sample does. The missing value prints as `-`.
+- The three off-task cases in `scripts/security-cases.mjs` (side comment, take over previous work, new instruction overrides history) pass `traceSample: 1`, so every call asks the off-task question and the cases test its answer again.
+
+## 1.1.0
+
+### Added
+
+- `"typesafeBackend": "liquid"` sends judgments to Liquid AI (api.liquid.ai, key in `LIQUID_API_KEY`, default model `d1:free`) through pi-typesafe 0.9.0. `d1:free` is free but slow (median about 14 seconds a request against the 5-second default `timeoutMs`), and the paid `d1` counts the state once per question, so a 7-question action request costs several times what it costs on Jev; see [docs/configuration.md](docs/configuration.md#liquid-ai-backend).
+
+### Changed
+
+- pi-typesafe `^0.9.0` (was `^0.8.0`).
+
+## 1.0.1
+
+### Fixed
+
+- The run-end rules check no longer judges files that a `git pull` brought in when the pulled commit was made during the run, such as a squash commit from a pull request merged on the hosting service: a commit counts as brought by git when this worktree's HEAD reflog shows that the checkout did not create it, whatever its date. The commit-date rule stays as the fallback when the reflog is off.
+
 ## 1.0.0
 
 The first stable release. From 1.0, pi-warden follows semver for the surface the README's Versioning section lists. Coming from 0.74.1, the last release on npm: [docs/upgrading.md](docs/upgrading.md) lists the removed settings, the new defaults, and what project files may still change. The changes since 0.74.1 are in the sections 0.75.0 to 0.90.0 below, and the README's "What it costs" table gives the measured effect of each 1.0 change.

package/README.md

@@ -39,6 +39,7 @@ Most guardrails stop and ask you. pi-warden tells **the agent** what it got wron
 | Your agent… | pi-warden… |
 | --- | --- |
 | says "done" with no test, build, or lint behind it | sends it back to prove it |
+| names a likely cause ("probably", "ask the team") with nothing checked that run | sends it back to check it with its own tools, or state plainly that it is unverified |
 | breaks a rule in your `pi-warden.md` or `AGENTS.md` | quotes the exact rule it broke |
 | is about to `git push --force`, `reset --hard`, `rm -rf`, `DROP` | holds it before it runs. A built-in pattern holds the destructive ones with no key at all; with Jev on, a score of 0.9 or more for "cannot be undone" holds too |
 | retries the same failing fix for the third time | asks for a new hypothesis |
@@ -73,6 +74,7 @@ Every guard and feature, its default, and its status. Defaults are `defaultConfi
 | [Security](docs/guards.md#security) | Flags risky written code and prompt injection in tool output; masks credentials, but leaves code values such as a call or an index alone | On | Stable |
 | [Stuck](docs/guards.md#stuck) | Asks for a new hypothesis when the agent repeats a failing approach | On | Stable |
 | [Done-check](docs/guards.md#done-check) | Sends an unverified "done" back for a check; after a UI change, a visual check | On | Stable |
+| [Cause-check](docs/guards.md#cause-check) | Sends a final reply back to check a stated cause, or to say plainly that it is unverified; the same unchecked cause on a later day gets a stronger steer | On | Stable |
 | [Runaway](docs/guards.md#runaway) | Stops a reply that repeats itself, offline | On | Stable |
 | [Context saver](docs/guards.md#context-saver) | Replaces large or duplicate tool output with an excerpt and a saved full copy | On | Stable |
 | ↳ Repeated user messages | Cuts repeated runs in your own messages too | Off. `context.dedupeMessages` | Stable |
@@ -88,6 +90,7 @@ Every guard and feature, its default, and its status. Defaults are `defaultConfi
 | [Adaptive steers](docs/guards.md#adaptive-steers-per-model) | Makes a steer kind trace-only for a model that rarely follows or often disputes it | On | Stable |
 | Steers and notices in the transcript | Shows steers and per-call notices in the chat, not only in the trace | Off. `steerVisible`, `notices` | Stable |
 | [Desktop notifications](docs/guards.md#desktop-notifications) | Holds, confirm dialogs, and runaway stops reach the desktop or your relay | Off. `notify.enabled` | Stable |
+| [Herdr pane state](docs/guards.md#herdr-pane-state) | In a herdr pane, a waiting confirm dialog shows as blocked in the herdr sidebar instead of working | On, no switch | Stable |
 | [Conscience](docs/guards.md#conscience) | Recommends a skill or tool the agent is missing; ranks candidates on your machine first and sends one request, or none | Off. `conscience.enabled` | Beta |
 | Learning from holds | Keeps each judged call in a local database with its Pi session id and, for a hold, what happened next (`approved`, `declined`, `replanned`, `abandoned`); a call that was not held keeps only the judge data, and is pruned after 90 days (`learning.allowedRetentionDays`; holds after 365). `/warden recommend` suggests threshold changes from it. Nothing is sent | On | Stable |
 | Config surface | A project file can only make the action guard and security stricter, a value that cannot be applied as written is shown once as a warning, and `deny` and `block` mean the same in every rule kind | On, no switch | Stable |

package/dist/adaptive.d.ts

@@ -6,7 +6,7 @@ import type { SteersConfig } from "./config.js";
  * models dispute noise ("as I said …"). Holds and per-call judgments never change; only whether a note is sent.
  */
 /** One kind of note to the agent. Finer than the steer guard: the `action` guard sends several unrelated notes. */
-export type SteerKind = "intent-mismatch" | "off-task" | "should-proceed" | "warn-headless" | "large-output" | "slop" | "rules" | "sensitive-path" | "security-write" | "stuck" | "repeat" | "done" | "prose" | "conscience" | "loops" | "runaway" | "subagent" | "hold" | "confirm" | "deny" | "masking" | "credential-notice";
+export type SteerKind = "intent-mismatch" | "off-task" | "should-proceed" | "warn-headless" | "large-output" | "slop" | "rules" | "sensitive-path" | "security-write" | "stuck" | "repeat" | "done" | "cause" | "prose" | "conscience" | "loops" | "runaway" | "subagent" | "hold" | "confirm" | "deny" | "masking" | "credential-notice";
 export declare const STEER_KINDS: readonly SteerKind[];
 /**
  * Never trace-only, whatever a model does with them: holds, confirm and deny verdicts, security masking, the credential

package/dist/adaptive.js

@@ -5,7 +5,7 @@ import { userConfigPath } from "./config.js";
 import { defaultHostDirs } from "./host-dirs.js";
 export const STEER_KINDS = [
     "intent-mismatch", "off-task", "should-proceed", "warn-headless", "large-output", "slop", "rules", "sensitive-path",
-    "security-write", "stuck", "repeat", "done", "prose", "conscience", "loops", "runaway", "subagent",
+    "security-write", "stuck", "repeat", "done", "cause", "prose", "conscience", "loops", "runaway", "subagent",
     "hold", "confirm", "deny", "masking", "credential-notice",
 ];
 /**
@@ -26,7 +26,7 @@ const fresh = () => ({ ...zero(), muted: false, asked: 0, probe: zero() });
 /** Kinds whose "followed" can be read from the next calls or text; the rest are judged by disputes alone. */
 const FOLLOW_MEASURED = new Set([
     "intent-mismatch", "off-task", "should-proceed", "warn-headless", "large-output", "slop", "rules", "security-write",
-    "stuck", "repeat", "done", "conscience", "loops",
+    "stuck", "repeat", "done", "cause", "conscience", "loops",
 ]);
 /** True when the counts put the pair under the follow floor or over the dispute ceiling. */
 export function failing(kind, counts, config) {

package/dist/ask-gate.d.ts

@@ -1,3 +1,4 @@
+import { type ScriptSource } from "./script-bodies.js";
 export interface AskDecision {
     /** True when the call goes to Jev; false when the offline pass decides it alone. */
     ask: boolean;
@@ -8,6 +9,7 @@ export interface AskDecision {
  * Whether this call needs a Jev request, and the short reason when it does not.
  * `text` is the command with data text blanked (`stripDataText`), so a commit message that mentions a push is not a push.
  */
-export declare function actionAskGate(tool: string, input: Record<string, unknown>, text: string | undefined, cwd?: string): AskDecision;
-/** The decision for one shell command. Exported for the replay and for tests. */
-export declare function gateCommand(scanned: string, raw?: string): AskDecision;
+export declare function actionAskGate(tool: string, input: Record<string, unknown>, text: string | undefined, cwd?: string, scripts?: readonly ScriptSource[]): AskDecision;
+/** The decision for one shell command. Exported for the replay and for tests. A command that runs a body from disk
+ * also asks when that body holds a shape the gate would ask a typed command for. */
+export declare function gateCommand(scanned: string, raw?: string, cwd?: string, scripts?: readonly ScriptSource[]): AskDecision;

package/dist/ask-gate.js

@@ -15,6 +15,7 @@
  * whether a judge is worth a request.
  */
 import { commandOf } from "./tools.js";
+import { scriptSources } from "./script-bodies.js";
 /** Tools that always reach Jev: what a write or an edit leaves on disk is what every question is about. */
 const ALWAYS_ASK = new Set(["write", "edit"]);
 /** Heads that change version control or remote state, publish, deploy, or drive infrastructure. */
@@ -242,7 +243,7 @@ function ghAsks(sub, segment) {
  * Whether this call needs a Jev request, and the short reason when it does not.
  * `text` is the command with data text blanked (`stripDataText`), so a commit message that mentions a push is not a push.
  */
-export function actionAskGate(tool, input, text, cwd) {
+export function actionAskGate(tool, input, text, cwd, scripts) {
     if (ALWAYS_ASK.has(tool))
         return { ask: true, why: tool };
     const view = commandOf(tool, input);
@@ -255,10 +256,24 @@ export function actionAskGate(tool, input, text, cwd) {
     const httpTool = /^(?:ctx_execute|ctx_batch_execute|ctx_execute_file)$/.test(tool);
     if (!httpTool && !view?.shell)
         return { ask: true, why: `${tool} code` };
-    return gateCommand(scanned, command);
+    return gateCommand(scanned, command, cwd, scripts);
 }
-/** The decision for one shell command. Exported for the replay and for tests. */
-export function gateCommand(scanned, raw = scanned) {
+/** The decision for one shell command. Exported for the replay and for tests. A command that runs a body from disk
+ * also asks when that body holds a shape the gate would ask a typed command for. */
+export function gateCommand(scanned, raw = scanned, cwd, scripts) {
+    const direct = gateText(scanned, raw);
+    if (direct.ask)
+        return direct;
+    const sources = scripts ?? (cwd === undefined ? [] : scriptSources(scanned, cwd));
+    for (const source of sources) {
+        const decision = gateText(source.body, source.body);
+        if (decision.ask)
+            return { ask: true, why: `runs a script with ${decision.why}` };
+    }
+    return direct;
+}
+/** The gate for one text, before any body it runs is read. */
+function gateText(scanned, raw = scanned) {
     // A script given on the command line or on stdin is scanned as a command: `python3 -c "shutil.rmtree(...)"` asks.
     const sink = SCRIPT_SINK.test(raw);
     const texts = sink && scanned !== raw ? [scanned, raw] : [scanned];

package/dist/build-info.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What the running pi-warden was built from, read once when a session starts and shown by `/warden status`.
+ *
+ * Pi loads the extension from `extensions/index.js`, which re-exports `dist/extension.js`, so the module URL is the
+ * built file. The package root resolves from there; `dist/extension.js` is the shipped entry and `src/` is the source a
+ * checkout edits. A published package has no `src/`, so the stale check only speaks for a git checkout.
+ */
+export interface WardenBuild {
+    version: string;
+    /** Short HEAD commit when the package root is a git checkout; undefined otherwise. */
+    commit: string | undefined;
+    /** ISO build time of `dist/extension.js`; undefined when the shipped entry is missing. */
+    builtAt: string | undefined;
+    /** Version of the pi-typesafe that this process loaded. */
+    typesafeVersion: string | undefined;
+    /** The caret range pi-warden declares for pi-typesafe. */
+    typesafeRange: string | undefined;
+    /** True when a file under `src/` is newer than `dist/extension.js`. */
+    stale: boolean;
+}
+/**
+ * Whether `version` sits inside the caret range `range`. Only `^x.y.z` is read, the form pi-warden declares; an
+ * unreadable range or version returns true so a version string this code cannot parse never pages the user.
+ */
+export declare function satisfiesCaret(version: string, range: string): boolean;
+/** Read the build provenance of this checkout or install. Never throws: a missing or unreadable file reads as absent. */
+export declare function readWardenBuild(): WardenBuild;

package/dist/build-info.js

@@ -0,0 +1,104 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const packageRoot = dirname(fileURLToPath(new URL("../package.json", import.meta.url)));
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The short commit of the checkout that holds `root`, or undefined when `root` is not a git checkout. */
+function gitCommit(root) {
+    if (!existsSync(join(root, ".git")))
+        return undefined;
+    try {
+        const output = execFileSync("git", ["-C", root, "rev-parse", "--short", "HEAD"], { encoding: "utf8", timeout: 2000 });
+        const commit = output.trim();
+        return commit || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The newest mtime under `src/`, or 0 when the package has no source directory (a published install). */
+function newestSourceMtime(root) {
+    const source = join(root, "src");
+    if (!existsSync(source))
+        return 0;
+    let newest = 0;
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(path);
+            else if (entry.isFile()) {
+                // A file removed between the readdir and the stat cannot be the one that makes the build stale.
+                const info = statSync(path, { throwIfNoEntry: false });
+                if (info)
+                    newest = Math.max(newest, info.mtimeMs);
+            }
+        }
+    };
+    walk(source);
+    return newest;
+}
+/** The version of the pi-typesafe this process resolved, from its package manifest. */
+function loadedTypesafeVersion() {
+    try {
+        // pi-typesafe is ESM-only (its exports define `import`, not `require`), so resolve it the ESM way and walk up to
+        // the manifest; `require.resolve` fails with ERR_PACKAGE_PATH_NOT_EXPORTED on this package.
+        let dir = dirname(fileURLToPath(import.meta.resolve("pi-typesafe")));
+        while (!existsSync(join(dir, "package.json")) && dir !== dirname(dir))
+            dir = dirname(dir);
+        const manifest = readJson(join(dir, "package.json"));
+        return typeof manifest?.version === "string" ? manifest.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether `version` sits inside the caret range `range`. Only `^x.y.z` is read, the form pi-warden declares; an
+ * unreadable range or version returns true so a version string this code cannot parse never pages the user.
+ */
+export function satisfiesCaret(version, range) {
+    const wanted = /^\s*\^\s*(\d+)\.(\d+)\.(\d+)\s*$/.exec(range);
+    const got = /(\d+)\.(\d+)\.(\d+)/.exec(version);
+    if (!wanted || !got)
+        return true;
+    const [wantedMajor, wantedMinor, wantedPatch] = [Number(wanted[1]), Number(wanted[2]), Number(wanted[3])];
+    const [major, minor, patch] = [Number(got[1]), Number(got[2]), Number(got[3])];
+    if (major !== wantedMajor)
+        return false;
+    // A caret on 0.x is an exact minor line in npm (^0.9.1 := >=0.9.1 <0.10.0); above 0 it holds the major.
+    if (wantedMajor > 0)
+        return minor > wantedMinor || (minor === wantedMinor && patch >= wantedPatch);
+    return minor === wantedMinor && patch >= wantedPatch;
+}
+/** Read the build provenance of this checkout or install. Never throws: a missing or unreadable file reads as absent. */
+export function readWardenBuild() {
+    const manifest = readJson(join(packageRoot, "package.json")) ?? {};
+    const dependencies = (manifest.dependencies ?? {});
+    const dist = join(packageRoot, "dist", "extension.js");
+    let builtAt;
+    let builtMtime = 0;
+    try {
+        builtMtime = statSync(dist).mtimeMs;
+        builtAt = new Date(builtMtime).toISOString();
+    }
+    catch {
+        builtAt = undefined;
+    }
+    return {
+        version: typeof manifest.version === "string" ? manifest.version : "unknown",
+        commit: gitCommit(packageRoot),
+        builtAt,
+        typesafeVersion: loadedTypesafeVersion(),
+        typesafeRange: typeof dependencies["pi-typesafe"] === "string" ? dependencies["pi-typesafe"] : undefined,
+        stale: builtAt !== undefined && newestSourceMtime(packageRoot) > builtMtime,
+    };
+}

package/dist/cause.d.ts

@@ -0,0 +1,108 @@
+import type { IntegrationErrorCode, Judge } from "pi-typesafe";
+import type { CauseGuardConfig } from "./config.js";
+/** One tool call of the run, as the judge reads it: a redacted call and a short redacted output sample. */
+export interface CauseActivity {
+    calls: Array<{
+        call: string;
+        output: string;
+    }>;
+}
+export declare function emptyCauseActivity(): CauseActivity;
+/** Record one finished tool call: its redacted command or path, and a short redacted output sample. */
+export declare function recordCauseActivity(activity: CauseActivity, tool: string, input: Record<string, unknown>, output?: string): void;
+/**
+ * The offline pre-filter: true when the final reply carries causal or hand-off wording, so a reply about results or
+ * next steps sends no request. Deliberately broad: a Jev answer still decides, and a missed ask loses a real catch.
+ */
+export declare function causePreFilter(text: string): boolean;
+export declare const causeQuestions: {
+    states_cause: import("pi-typesafe").NoulQuestion;
+    hands_off: import("pi-typesafe").NoulQuestion;
+    checked: import("pi-typesafe").NoulQuestion;
+};
+/**
+ * One earlier unchecked cause as the judge reads it: a short key for the answer, its date, and the redacted sentence
+ * the agent gave. The key and the date alone cannot say whether two causes are the same.
+ */
+export interface EarlierCause {
+    key: string;
+    date: string;
+    summary: string;
+    at: number;
+}
+export interface CauseJudgment {
+    statesCause: number;
+    handsOff: number;
+    checked: number;
+    model: string;
+    elapsedMs: number;
+}
+/** One remembered unchecked cause. */
+export interface CauseStoreRecord {
+    summary: string;
+    at: number;
+}
+/** Project-level memory of unchecked causes. */
+export interface CauseStore {
+    /** The project's unchecked causes at or after `since`, newest first, at most `limit`. */
+    recall(projectRoot: string, since: number, limit: number): Promise<CauseStoreRecord[]>;
+    /** Remember one unchecked cause. */
+    record(projectRoot: string, record: {
+        summary: string;
+        at: number;
+    }): Promise<void>;
+}
+export interface CauseVerdict {
+    /** The reply states or hands off a cause and no tool result in the run checked it. */
+    unchecked: boolean;
+    /** The reply asks a person to check something the agent could check itself. */
+    handsOff: boolean;
+    /** Short redacted summary of the cause sentence, stored for repeats. */
+    summary: string;
+    /** An earlier cause the judge matched inside the window. */
+    previous?: CauseStoreRecord;
+    reasons: string[];
+    judgment?: CauseJudgment;
+    error?: string;
+    errorCode?: IntegrationErrorCode;
+}
+export interface CauseOptions {
+    config: CauseGuardConfig;
+    judge: Judge;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+    store?: CauseStore | undefined;
+    projectRoot?: string | undefined;
+    now?: number | undefined;
+}
+export declare function buildCauseRequest(task: string | undefined, finalMessage: string, activity: CauseActivity, earlier?: readonly EarlierCause[]): {
+    state: {
+        earlier_causes?: {
+            key: string;
+            date: string;
+            cause: string;
+        }[];
+        task: string;
+        final_message: string;
+        run: {
+            tool_calls: {
+                call: string;
+                output: string;
+            }[];
+        };
+    };
+    questions: {
+        states_cause: import("pi-typesafe").NoulQuestion;
+        hands_off: import("pi-typesafe").NoulQuestion;
+        checked: import("pi-typesafe").NoulQuestion;
+    } | {
+        same_cause: import("pi-typesafe").ChoiceQuestion<Record<string, string>>;
+        states_cause: import("pi-typesafe").NoulQuestion;
+        hands_off: import("pi-typesafe").NoulQuestion;
+        checked: import("pi-typesafe").NoulQuestion;
+    };
+};
+export declare function evaluateCause(task: string | undefined, finalMessage: string, activity: CauseActivity, options: CauseOptions): Promise<CauseVerdict>;
+/** The follow-up for the agent: check the cause with its own tools, or say plainly that it is unverified. */
+export declare function causeNudge(verdict: CauseVerdict): string;
+export declare function formatCause(verdict: CauseVerdict, template?: string): string;