pi-warden 1.11.0 → 1.14.0

package/CHANGELOG.md

@@ -8,6 +8,100 @@ How to keep this current: add the entry in the same pull request as the change,
 
 <!-- Empty. Next release starts here. -->
 
+## 1.14.0
+
+### Added
+
+- **The agent's writes to pi-warden's own config are held.** A `write`, `edit`, or `bash` call that writes `.pi/pi-warden.json`, or a file in `<agent dir>/pi-warden/`, is held by a new built-in floor rule, `warden-config-write`, so a cloned repository cannot switch a check off by having the agent edit its own config. The command reader finds the write in a redirect, `tee`, a heredoc, a `-c` string, a wrapper, or a script the command runs; in the destination of `cp`, `mv`, `ln`, `install`, `rsync`, `truncate`, `touch`, `dd of=`, `sed -i`, `perl -i`, `curl -o`, or `wget -O`; and in the source of `rm`, `unlink`, `mv`, or `ln`. It follows a literal `cd` or `pushd` and resolves `~`, `$HOME`, `..`, a relative path, and symlinks. The capability index stays writable, reads stay free, and `action.exemptRules: ["warden-config-write"]` (user file only) silences the rule like any built-in.
+- **One line at session start names every check the project file loosens**, and from which file. The record of the last loosened set is kept per project beside the user config; a further loosening of an already-named check shows the line again, and the same set stays quiet.
+- **One line when either config file changes during a session** without pi-warden's own write. It names `.pi/pi-warden.json` or `your pi-warden config`, never a full path, shows once per new content, and says the change applies at the next session.
+
+### Changed
+
+- Both config files are read once at session start, and those snapshots serve every call of the session; a mid-session edit applies from the next session, so a write shape the floor misses cannot change a check mid-run. `/warden enable`, `/warden disable`, `/warden mode`, `/warden config set`, and the config panel update the snapshot in the same step, so they still apply at once.
+- The loosening direction is named correctly for `cause.windowDays` (lowered), `action.intentTraceOnly` (moved to a quieter mode), and `judge.failuresBeforeCooldown`.
+
+### Fixed
+
+- A scratch project's `pi-warden.json` stays free at any depth under a temp root; the session's own project file is never exempt.
+- An empty loosened set is recorded as a set of its own, so a set that goes away and comes back shows its line again.
+- Every config path and file name is compared case-folded and in one Unicode form, because APFS treats `.pi/PI-WARDEN.JSON` and `.pi/pi-warden.json` as one file.
+
+### Docs
+
+- `configuration.md`: when the config files are read, and the loosening notice with its per-project record. `guards.md`: the `warden-config-write` hold. `deterministic-floor-spec.md`: the config hold and its write shapes.
+
+## 1.13.1
+
+### Changed
+
+- The done-check UI nudge says what counts as looking at the result: seeing the changed page after the change — a page snapshot, a passing browser or device test, or a screenshot of the page that is then read; a screenshot saved to a file counts only once it is read. The detection is unchanged — a scripted review that sends screenshots to a vision model over HTTP still leaves no session evidence (`#187`). `docs/configuration.md` now says a custom `done.visualTools` list replaces its defaults and that a `commands` entry matches the command head the way the agent runs it.
+
+## 1.13.0
+
+### Added
+
+- `/warden improve` hands the judgement to the session's own model: the code prints the measured counts, the session files behind them and the rules text, and the model reads the sessions and edits this project's `pi-warden.md`. Each change carries a `Measured` line naming the count and the session file it came from, at most three changes are made, and a second run replaces an existing `Measured` line rather than adding one. The pass takes a timestamped backup before the turn, then prints each rule added, changed or removed with the count it cited, and the diff. The quiet window is armed before the turn, so the rules judge does not grade the rewrite; the destructive floor stays on.
+
+### Fixed
+
+- `/warden improve` called zero rule judgments "the rules held". It now says the guard judged nothing for this project in the window, so nothing is known about the rules, and gives the counts that do exist.
+- `/warden improve` printed "repeated calls" beside "repeated requests" as if they were the same number. They are now "calls flagged as repeats" and "requests typed twice".
+- `/warden improve` printed a 250 ms scan budget it missed. It now reports what it measured: files read, bytes, and time.
+
+## 1.12.1
+
+### Docs
+
+- README: the improve pass and its quiet window, the rules report, standing lessons and the capability index; how the offline floor reads a script a command runs, and which delete text it skips; the test and development scripts.
+
+## 1.12.0
+
+### Added
+
+- `/warden improve [days]` reads the last N days (default 7, 1 to 90) of this project's own sessions, rules log and hold logs, prints the counts — reading cost, calls a waste detector flags as repeats, rule judgments, fires and clears, holds by kind — and proposes at most three edits to this project's `pi-warden.md`, each naming the count it came from and the files it read. A cited number that is not on the printed list refuses the whole set; with no support it writes nothing and says the rules held. A confirmed run writes a timestamped backup and then the file atomically, and refuses a file that changed under it. Nothing is sent and no judge request is made.
+- While the pass runs it arms its own session's quiet window (`improve.quietMs`, default `600000`, capped at `900000`): the rules judge, the turn-start rule reminder and the text guards stay quiet in that session only, other Pi sessions keep judging, the window expires by the clock, and the destructive-action floor, path rules, deny list and arming rules stay on. `/warden status` shows it while it is live.
+
+## 1.11.3
+
+### Fixed
+
+- The floor finds a script run where bash runs it. It read a command by cutting it at every separator and taking the first word of each part, so it missed a script run inside `( )`, `{ }`, `$( )`, backticks, `<( )`, `if`/`elif`/`else`, a loop, a `case` arm, a function body, or an array assignment (`arr=($(sh a.sh))`); after `!` or a wrapper with options (`timeout 5`, `nice -n 5`, `env -i`, `xargs`); with a quoted path (`sh "a.sh"`); and inside a `-c` string, an `eval`, an `env -S` string, or the command of `find -exec`, `-execdir`, `-ok`, or `-okdir`. One reader of the simple commands that bash runs now feeds the floor, the `script_lines` of the judge request, and the ask gate, so the ask gate also asks about a push in a script run in these shapes. A quoted `~` stays literal, as in bash. A command the reader cannot read whole (an unclosed quote, a stray `fi`), or one nested more than 64 levels deep or with more than 50,000 constructs, is cut at every separator as before, so it reads more, never less. The floor does not evaluate conditions: a script in a branch that bash skips, or in a function that nobody calls, is read too.
+- A script fed to a shell on its input is read: `sh < a.sh`, `cat a.sh | sh`, `cat < a.sh | sh`, `sh /dev/stdin < a.sh`, `bash -s x < a.sh`, and `bash <(cat a.sh)`. So is a file's text run as code: `sh -c "$(cat a.sh)"`, `eval "$(< a.sh)"`, and `sh <<< "$(cat a.sh)"`. `/dev/stdin` itself is never opened. A heredoc fed to a shell inside `$( )` ends at its delimiter followed by `)`, as in bash, so the delete in `x=$(sh <<EOF` … `EOF)` is held.
+- A literal `cd` moves the script runs after it, inside its own subshell only. `(cd sub && sh a.sh)` reads `sub/a.sh`, so a harmless script is no longer held for a deleting namesake in the start folder, and a `cd sub &` moves nothing after it. After a `cd` that may be skipped (after `&&` or `||`, or in a branch, a loop, or a function), both folders are read; after a `cd` to a folder that does not exist, the old one is.
+- A delete is read by the command word bash runs: `\rm`, `"rm"`, `r''m`, `/bin/rm`, and `${x}rm` (an empty `x`) are `rm`, also after a `case` pattern's `)` and inside a `-c` or `eval` string. User `commandRules` still match the command as typed.
+- A script path with `..` is resolved before the roots check. `sh /tmp/../net/x/a.sh` passed the check on its literal text and reached the file system outside the roots, where a lookup can start an automount.
+
+### Tests
+
+- The differential test adds rows for the new shapes, typed and in script bodies, and runs each through `bash -c` with a `touch "$MARK"` twin: the floor holds an input exactly when bash creates the marker. Unit tests hold a delete nested 10,000 deep in each construct with no error, and check that a stray `fi` or `done` throws nowhere, that a quoted `~` reads no file in the home folder, that a `..` path asks the file system about nothing outside the roots, that stdin feeds are read, and that a `cd` before `&` does not move the commands after it.
+
+### Docs
+
+- The Script bodies paragraph in `docs/guards.md` lists the new ways the floor finds a script run, how it follows `cd`, and the nesting limit.
+
+## 1.11.2
+
+### Fixed
+
+- The action guard's floor no longer holds a bash call for text the shell never runs. Every pattern check (the built-in rules, the SQL and git state checks, user `commandRules`, and path rules on the command surface) reads a command and a script body without shell comments, the same comment scan the judge request uses. A `#!/bin/sh` first line no longer keeps every quoted `echo`/`printf` message in scope (the data scan read it as a call to `sh`), and a message that holds `;`, `|`, or `&&` inside its quotes is no longer cut into commands. The hit lines of a script body leave out its comment lines.
+- A `grep`, `sed`, or `rtk grep` of a file, with `\|` in its quoted pattern, no longer reads that file as a script that runs. Script detection cut the command at every `|`, also inside quotes, so `down=" scripts/x.py` read as an assignment and the file as the command; it now cuts only where the shell does. A command with a substitution, an unclosed quote, `eval`, or `sh -c` keeps the old cut, so every script read before is still read. ([#190](https://github.com/DevMortimer/pi-warden/issues/190))
+- The floor reads line continuations as bash does. A delete split by a backslash-newline (`r\<newline>m -rf ~`, `rm \<newline>-rf ~`) was not held, and neither was a script run as `sh \<newline>a.sh`. The comment scan now joins each backslash-newline that bash removes: outside quotes, in double quotes and `${...}`, and in a heredoc body with an unquoted delimiter, but not in single quotes, `$'...'`, a quoted heredoc body, or a comment. A backslash-newline before a script run (`cd . && \<newline>  sh a.sh`, also `npm run` and `make`) no longer hides the script from the floor or the ask gate.
+- A delete after a here-string or a partly quoted heredoc delimiter is held again. The data scan found heredocs with a line regex that read `<<<` and a `<<` inside quotes as the start of a heredoc, and took `E` as the delimiter of `<<E"O"F`, so every later line was blanked as heredoc data. It now takes heredocs from the comment scan, which skips here-strings, quotes, and comments, removes quotes from the delimiter, and joins a backslash-newline in an unquoted body before it matches the delimiter; a command that scan cannot read keeps every line in scope.
+- The ask gate reads the command the way the floor does, without shell comments and with quoted messages and heredoc data blanked. A push or a delete that appears only in a comment or in a quoted `echo` message no longer sends a judge request.
+
+### Tests
+
+- A differential test runs each input through `bash -c` with a `touch "$MARK"` twin in place of the delete: the floor holds an input exactly when bash creates the marker (13 inputs it stops holding, 16 it keeps holding, among them a delete inside `$(...)` on a heredoc line that starts with `#`, and a delete on the line after a comment that holds an apostrophe). Unit tests pin the issue 190 command with its user rule, and every way of running a script (`sh`, `bash`, `./`, `.`, `source`, `npm run`), also next to a read of the same file.
+- The differential test adds 28 inputs with backslash-newlines, here-strings, and quoted or split heredoc delimiters, typed and in script bodies with `#!/bin/sh`, `#!/bin/bash`, `#!/usr/bin/env bash`, or no first line; the comment-scan output test adds 8 inputs whose output bash must print unchanged. Unit tests hold each of them through `matchPatterns`, check that the ask gate still asks for a script named after a backslash-newline, and check that the comment, echo message, and `sed` shapes still run.
+- A judge-call count through `evaluateAction` pins that a push only in a comment sends no request, and that the same push as a second command sends one.
+
+## 1.11.1
+
+### Fixed
+
+- `/warden index` now finalizes the entries-only files its own prompt asks the model to write. The entries-only fallback ran only when the strict read had already found a complete file, so an `{ "entries": [...] }` file never got its metadata, its rejections were never reported, and every later session loaded the index as missing and repeated the "run /warden index" nudge. The fallback now runs whenever the strict read finds no file, and rejected entries are reported. ([#185](https://github.com/DevMortimer/pi-warden/issues/185))
+
 ## 1.11.0
 
 ### Added

package/README.md

@@ -44,11 +44,22 @@ Most guardrails stop and ask you. pi-warden tells **the agent** what it got wron
 | 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 |
 | writes stubs, restating comments, hardcoded secrets | names them on the spot |
+| repeats the same mistake across sessions | counts it, and offers the rule that would have stopped it (`/warden improve`) |
 | floods its context with a huge log | keeps the lines that matter, stores the rest |
 | starts repeating itself forever | stops the reply |
 
 [Every guard, with its thresholds and calibration →](docs/guards.md)
 
+## It reads your sessions back
+
+`/warden improve` looks at the last seven days of this project's own sessions, rules log and hold log, and prints what actually cost you: whole-file reads and calls per turn, tool calls the waste detectors flag as repeats, requests typed twice, and the same refusal, rule by rule.
+
+Then it hands the judging to the model already running in this session. The model reads the sessions behind those numbers and edits `pi-warden.md`: at most three changes, each with a `Measured` line naming the count it came from and the session file. With nothing supported it changes nothing and says the rules held, with the counts that show it; when no rule was judged in the window it says that instead, because nothing is known about the rules then.
+
+A run writes a timestamped backup before the model's turn, then prints every rule added, changed or removed with the count it cited, and the diff. The counts, the backup and the checks are local: no extra key, no TypeSafe request, and the only cost is that one turn of the session model. `/warden improve 4` reads four days; the range is 1 to 90.
+
+While the pass runs, the rules judge goes quiet in that one session, so the rewrite is not graded against the rules it is rewriting. The window expires by the clock, another Pi session keeps judging, and the destructive floor stays on.
+
 ## Features
 
 Every guard and feature, its default, and its status. Defaults are `defaultConfig()` in `src/config.ts`; Beta and Experimental are the labels in [the guard docs](docs/guards.md). Guards that ask Jev need a key and `/warden enable`; without one, their offline parts still run.
@@ -57,7 +68,7 @@ Every guard and feature, its default, and its status. Defaults are `defaultConfi
 | --- | --- | --- | --- |
 | Jev judgments | Sends redacted samples to Jev for the judged checks below | Off until `/warden enable` | Stable |
 | [Action guard](docs/guards.md#action-guard) | Checks each command, write, and edit before it runs: offline patterns plus one Jev request | On | Stable |
-| ↳ Offline floor | Holds destructive patterns (force push, `reset --hard`, `rm -rf` on a path outside scratch, `DROP`) with no key and no request; with Jev on, a pattern hit goes to Jev as evidence | On | Stable |
+| ↳ Offline floor | Holds destructive patterns (force push, `reset --hard`, `rm -rf` on a path outside scratch, `DROP`) with no key and no request. It reads a script that a command runs, one level deep, the way bash runs it (`( )`, `if`, a loop, `bash -c`, a pipe into a shell, a quoted path), and holds a delete spelled `\rm`, `"rm"`, `r''m` or `${x}rm`; delete text the shell never runs — a comment, an `echo` message, a file `grep` only reads — is skipped. With Jev on, a pattern hit goes to Jev as evidence | On | Stable |
 | ↳ Irreversible hold | Jev adds holds: a call scored 0.9 or more as irreversible is held; 0.5 to 0.9 warns | On | Stable |
 | ↳ Scratch deletes | A recursive `rm` of temp scratch the agent made warns instead of holding; data moved in keeps the hold | On | Stable |
 | ↳ Ask gate | Code decides offline when no Jev answer could change what the agent sees, so the call sends no request: 48.9% fewer requests, 327 of the 338 changed outcomes still asked | On. `action.ask` | Stable |
@@ -84,6 +95,11 @@ Every guard and feature, its default, and its status. Defaults are `defaultConfi
 | [Call-waste notes](docs/guards.md#call-waste) | One advisory line on polling, paging, repeated searches, and re-filtered checks | On | Stable |
 | ↳ Session tip | Adds one paragraph about call cost to the system prompt | Off. `waste.tip` | Stable |
 | [Open loops and recall](docs/guards.md#open-loops-and-recall) | `warden_loops` keeps the agent's promises; `warden_recall` lists what it already tried | On, no switch | Stable |
+| [Standing lessons](docs/guards.md#open-loops-and-recall) | `warden_remember` keeps one standing instruction for this project, so a later session starts with the correction you already made | On, no switch | Stable |
+| [Improve pass](docs/commands.md) | Reads the last 7 days of this project's sessions and proposes at most three count-backed edits to `pi-warden.md`; nothing supported means nothing written | On, no switch (`/warden improve`) | Stable |
+| ↳ Quiet window | The rules judge and the text guards go quiet in the arming session only, so the rules file can be rewritten; the floor stays on and the window expires by the clock | On. `improve.quietMs` | Stable |
+| [Rules report](docs/commands.md) | Per rule: judged, fired, cleared after a fire, and the flags `never fires`, `fires on everything`, `undecided` | On, local only (`/warden report`) | Stable |
+| [Capability index](docs/configuration.md) | `/warden index` builds a local index of your skills and tools so the conscience ranks candidates on your machine before it sends anything | On, local only | Stable |
 | [Subagent triage](docs/guards.md#subagent-triage) | Wakes the agent only for a subagent report that needs it | On | Stable |
 | [Token Guardian observer](docs/guards.md#token-guardian-observer) | Records Jev's answers to redacted supervision triggers in the trace; never answers Guardian or acts on them | On with Jev consent | Record-only |
 | [Judge cooldown](docs/guards.md#judge-cooldown) | Pauses Jev requests after repeated failures, so a dead backend costs no timeouts | On, no switch | Stable |
@@ -111,7 +127,7 @@ Jev requests cost money, so each 1.0 change was measured by what it saves. Each
 | Approval on demand ([#160](https://github.com/DevMortimer/pi-warden/pull/160), [#161](https://github.com/DevMortimer/pi-warden/pull/161)) | Approval questions per 1,000 judged calls 90.0 → 0.7; wrong releases 45 → 1 in the measured runs | [Approval on demand](docs/guards.md#approval-on-demand-2026-10-01-three-designs-three-sets) |
 | Hold database ([#149](https://github.com/DevMortimer/pi-warden/pull/149)) | A copy of 52,362 rows shrinks from 285.9 MiB to 41.6 MiB | [Data handling](docs/data-handling.md#what-stays-on-this-machine) |
 
-Features that did not earn their cost did not ship: the working-memory pruning, the stale-result stubs, and a hybrid compaction failed their gates, and the off-task and should-proceed steers stay trace-only. The numbers are in the [Calibration](docs/guards.md#calibration) section.
+Features that did not earn their cost did not ship: the working-memory pruning, the stale-result stubs, and a hybrid compaction failed their gates, and the off-task and should-proceed steers stay trace-only. The numbers are in the [Calibration](docs/guards.md#calibration) section. `/warden report` sends no request at all; `/warden improve` spends one turn of the session model and no TypeSafe request.
 
 ## Rules no linter can check
 
@@ -169,6 +185,8 @@ From 1.0, pi-warden follows semver for: the documented config keys and their def
 ```bash
 npm install
 npm run check        # typecheck + offline tests + build
+npm test             # offline tests only
+npm run dev:pi       # start Pi with this working tree
 ```
 
 MIT licensed.

package/dist/ask-gate.js

@@ -264,7 +264,7 @@ 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));
+    const sources = scripts ?? (cwd === undefined ? [] : scriptSources(raw, cwd));
     for (const source of sources) {
         const decision = gateText(source.body, source.body);
         if (decision.ask)

package/dist/config.d.ts

@@ -352,6 +352,16 @@ export interface PrefsConfig {
     /** At session start, send the standing preferences that pass every injection rule to the agent as one context message. */
     inject: boolean;
 }
+/**
+ * `/warden improve`: the window the pass reads and the quiet window it arms. Both are the user's own settings: a
+ * project file cannot arm a quiet window, because a quieter rules judge is a weaker guard.
+ */
+export interface ImproveConfig {
+    /** Days a pass looks back when no number is typed: `/warden improve 4` overrides it. 1 to 90. */
+    days: number;
+    /** How long the rules judge and the text guards stay quiet in the arming session: ten minutes by default, never more than fifteen. */
+    quietMs: number;
+}
 /** The silent-half field trial (trial.ts): a random half of sessions records what it would have told the agent. */
 export interface TrialConfig {
     /**
@@ -478,6 +488,8 @@ export interface WardenConfig {
     conscience: ConscienceConfig;
     /** Standing preferences: corrections the user repeated in earlier sessions of this project. */
     prefs: PrefsConfig;
+    /** The `/warden improve` pass: its default window and its quiet window. */
+    improve: ImproveConfig;
     /** Silent-half field trial: off by default, user file only. */
     trial: TrialConfig;
     /** Call-waste notes: advisory sentences attached to the tool result that triggers them. */
@@ -489,7 +501,7 @@ export interface WardenConfig {
 }
 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 = 14;
+export declare const CONFIG_SCHEMA = 15;
 export declare const PROJECT_CONFIG_FILE = "pi-warden.json";
 export declare function defaultConfig(): WardenConfig;
 /** The user file is in the host's agent directory: `~/.pi/agent` on Pi, `~/.omp/agent` on oh-my-pi. `PI_CODING_AGENT_DIR` overrides it. */
@@ -516,7 +528,67 @@ export interface LoadOptions {
     projectTrusted?: boolean;
     /** Host directories; defaults to `defaultHostDirs()`. */
     dirs?: HostDirs;
+    /**
+     * The project file as the session read it once at its start. A session that passes one never re-reads the file, so a
+     * mid-run edit lands at the next session. Omitted, the file is read on every call, as a library caller expects.
+     */
+    projectRaw?: {
+        value: unknown;
+    } | undefined;
+    /** The user file, read once at session start the same way: an outside edit lands at the next session. */
+    userRaw?: {
+        value: unknown;
+    } | undefined;
+}
+/** The user file's content, read without applying anything: the session snapshot is taken from here. */
+export declare function readUserConfigFile(dirs?: HostDirs): unknown;
+/** The project file's content, read without applying anything: the session snapshot is taken from here. */
+export declare function readProjectConfig(cwd: string, dirs?: HostDirs): unknown;
+/**
+ * The checks a project file loosens compared with the user's own config. The project file cannot weaken the action guard
+ * or security (those values are refused with a warning at load), so what is compared here is every other check it can
+ * switch off, move a threshold on, or take a file out of.
+ */
+export interface LoosenedCheck {
+    /** The check, named as `/warden status` names it. */
+    name: string;
+    /** How it loosens; absent when the project file simply switches the check off. */
+    detail?: string;
+}
+/** How a project value loosens the check it tunes. */
+export type ProjectKeyKind = "off" | "high" | "low" | "fewer" | "more" | "scale" | "none";
+/** One key a project file can set: the check it loosens, and how; or why it is not a check. */
+export interface ProjectKeyClass {
+    kind: ProjectKeyKind;
+    /** The check, named as `/warden status` names it; absent only when the key is not a check. */
+    check?: string;
+    /** What moves, as the line's detail names it (`threshold`, `UI files`). */
+    label?: string;
+    /** Loosest first, for a named option list. */
+    order?: readonly string[];
+    /** Why this key is not a check; required when kind is "none". */
+    why?: string;
 }
+/**
+ * Every key a project file can set, classified: a direction that loosens a check, or "none" with the reason it is not
+ * one. A test walks every leaf of `defaultConfig()` in a project section and fails when a key has no row here, so a
+ * config key added later cannot quietly loosen a check without being named in the session-start line.
+ * The action guard and security rows that a project can only tighten (`projectProbability`, `projectSwitch`) are "none":
+ * the loader refuses the looser value, so the notice has nothing to say about it.
+ */
+export declare const PROJECT_KEYS: Readonly<Record<string, ProjectKeyClass>>;
+/** Every check `layered` loosens compared with `user`, in a stable order. Empty when the project file loosens nothing. */
+export declare function loosenedChecks(user: WardenConfig, layered: WardenConfig): LoosenedCheck[];
+/** The one line a session start shows for a loosened set: what the project file takes away, and from which file. */
+export declare function loosenNotice(checks: readonly LoosenedCheck[], dirs?: HostDirs): string;
+/** Where the last loosened set for a project is kept: beside the user config, keyed by the project path. */
+export declare function loosenRecordPath(cwd: string, dirs?: HostDirs): string;
+/** The checks last recorded for this project; undefined when no record exists, it cannot be read, or it predates
+ *  details (a names-only record is a different set, so the line shows once more after the upgrade). */
+export declare function readLoosenRecord(cwd: string, dirs?: HostDirs): LoosenedCheck[] | undefined;
+/** Records the loosened set now shown for this project, so the same set stays quiet until it changes. A read-only
+ *  agent directory must not stop a session: the record is an optimisation, and an unwritable one shows the line again. */
+export declare function writeLoosenRecord(cwd: string, checks: readonly LoosenedCheck[], dirs?: HostDirs): void;
 export declare function loadConfig(options?: LoadOptions): WardenConfig;
 /** Reads only the user file, for editing and persisting consent. */
 export declare function readUserConfig(dirs?: HostDirs): Json;

package/dist/config.js

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { dirname, join } from "node:path";
 import { writeFileAtomicSync } from "./atomic.js";
 import { resolveJudgmentBackend } from "./backend.js";
@@ -32,7 +33,7 @@ export const WARDEN_MODES = ["steer", "confirm", "advise"];
 export const CONSCIENCE_SKILL_MODES = ["off", "recommend", "load"];
 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 = 14;
+export const CONFIG_SCHEMA = 15;
 export const PROJECT_CONFIG_FILE = `${PACKAGE_NAME}.json`;
 export function defaultConfig() {
     return {
@@ -102,6 +103,7 @@ export function defaultConfig() {
             localFloor: 0.5,
         },
         prefs: { enabled: true, inject: true },
+        improve: { days: 7, quietMs: 600000 },
         trial: { silentHalf: false },
         waste: { enabled: true, tip: false, every: 20, sleep: true, paging: true, search: true, recheck: true },
         // pi-claude-bridge compacts its own models and cancels on failure; its summary must not be replaced.
@@ -647,11 +649,15 @@ export function applyUserOverrides(base, raw) {
         learning: applyLearning(base.learning, raw.learning),
         conscience: applyConscience(base.conscience, raw.conscience),
         prefs: applyPrefs(base.prefs, raw.prefs),
+        improve: applyImprove(base.improve, raw.improve, warnings),
         trial: applyTrial(base.trial, raw.trial),
         warnings: [...(base.warnings ?? []), ...warnings],
     };
 }
-/** A project cannot turn the trial on: applyProjectOverrides never copies this section, so the user file is the only source. */
+/**
+ * A project cannot turn the trial on, and cannot arm an improve quiet window: applyProjectOverrides never copies either
+ * section, so the user file is the only source.
+ */
 function applyTrial(base, raw) {
     if (!isObject(raw))
         return base;
@@ -701,6 +707,24 @@ function applyPrefs(base, raw) {
         return base;
     return { enabled: boolean(raw.enabled, base.enabled), inject: boolean(raw.inject, base.inject) };
 }
+/** The 1..90 and 0..900000 ranges are the caps of improve.ts; a value past either is refused here, not silently kept. */
+function applyImprove(base, raw, warnings) {
+    if (!isObject(raw))
+        return base;
+    const days = raw.days;
+    const quietMs = raw.quietMs;
+    const keptDays = typeof days === "number" && Number.isSafeInteger(days) && days >= 1 && days <= 90
+        ? days
+        : base.days;
+    if (days !== undefined && keptDays !== days)
+        warnings.push(`improve.days ${String(days)} is not a whole number of days from 1 to 90; ${base.days} is used`);
+    const keptQuiet = typeof quietMs === "number" && Number.isFinite(quietMs) && quietMs >= 0 && quietMs <= 900000
+        ? Math.trunc(quietMs)
+        : base.quietMs;
+    if (quietMs !== undefined && keptQuiet !== quietMs)
+        warnings.push(`improve.quietMs ${String(quietMs)} is not a number of milliseconds from 0 to 900000; ${base.quietMs} is used`);
+    return { days: keptDays, quietMs: keptQuiet };
+}
 function applySteers(base, raw) {
     if (!isObject(raw))
         return base;
@@ -763,12 +787,235 @@ export function applyProjectOverrides(base, raw) {
     const guards = applyGuards(base, raw, base.timeoutMs, "project", warnings);
     return { ...base, enabled, ...guards, prefs: applyPrefs(base.prefs, raw.prefs), warnings: [...(base.warnings ?? []), ...warnings] };
 }
+/** The user file's content, read without applying anything: the session snapshot is taken from here. */
+export function readUserConfigFile(dirs = defaultHostDirs()) {
+    return readJson(userConfigPath(dirs));
+}
+/** The project file's content, read without applying anything: the session snapshot is taken from here. */
+export function readProjectConfig(cwd, dirs = defaultHostDirs()) {
+    return readJson(projectConfigPath(cwd, dirs));
+}
+/**
+ * Every key a project file can set, classified: a direction that loosens a check, or "none" with the reason it is not
+ * one. A test walks every leaf of `defaultConfig()` in a project section and fails when a key has no row here, so a
+ * config key added later cannot quietly loosen a check without being named in the session-start line.
+ * The action guard and security rows that a project can only tighten (`projectProbability`, `projectSwitch`) are "none":
+ * the loader refuses the looser value, so the notice has nothing to say about it.
+ */
+export const PROJECT_KEYS = {
+    "stuck.enabled": { kind: "off", check: "stuck-check" },
+    "stuck.minFailures": { kind: "high", check: "stuck-check", label: "failures needed" },
+    "stuck.sameStrategy": { kind: "high", check: "stuck-check", label: "same-strategy threshold" },
+    "stuck.churnThreshold": { kind: "high", check: "stuck-check", label: "churn threshold" },
+    "stuck.cooldown": { kind: "high", check: "stuck-check", label: "cooldown" },
+    "stuck.nudge": { kind: "off", check: "stuck-check", label: "nudge" },
+    "stuck.repeatSteer": { kind: "off", check: "stuck-check", label: "repeat steer" },
+    "stuck.evidence": { kind: "off", check: "stuck-check", label: "evidence" },
+    "stuck.diffLimit": { kind: "low", check: "stuck-check", label: "diff limit" },
+    "stuck.tailLimit": { kind: "low", check: "stuck-check", label: "tail limit" },
+    "stuck.window": { kind: "none", why: "a cap on minFailures, which decides on its own" },
+    "done.enabled": { kind: "off", check: "done-check" },
+    "done.claimsDone": { kind: "high", check: "done-check", label: "claims-done threshold" },
+    "done.nudge": { kind: "off", check: "done-check", label: "nudge" },
+    "done.uiProof": { kind: "off", check: "done-check", label: "UI proof" },
+    "done.uiFiles": { kind: "fewer", check: "done-check", label: "UI files" },
+    "done.visualTools.commands": { kind: "more", check: "done-check", label: "visual commands" },
+    "done.visualTools.commandWords": { kind: "more", check: "done-check", label: "visual command words" },
+    "done.visualTools.tools": { kind: "more", check: "done-check", label: "visual tools" },
+    "done.visualTools.images": { kind: "more", check: "done-check", label: "visual image types" },
+    "cause.enabled": { kind: "off", check: "cause-check" },
+    "cause.claimsCause": { kind: "high", check: "cause-check", label: "claims-cause threshold" },
+    "cause.nudge": { kind: "off", check: "cause-check", label: "nudge" },
+    "cause.windowDays": { kind: "low", check: "cause-check", label: "window days" },
+    "slop.enabled": { kind: "off", check: "slop-check" },
+    "slop.threshold": { kind: "high", check: "slop-check", label: "threshold" },
+    "slop.prose.enabled": { kind: "off", check: "slop-check", label: "prose" },
+    "slop.prose.threshold": { kind: "high", check: "slop-check", label: "prose threshold" },
+    "slop.prose.trend": { kind: "high", check: "slop-check", label: "prose trend" },
+    "slop.prose.minChars": { kind: "high", check: "slop-check", label: "prose minimum chars" },
+    "slop.prose.audience": { kind: "none", why: "who the prose is written for, not a threshold" },
+    "rules.enabled": { kind: "off", check: "rules-check" },
+    "rules.threshold": { kind: "high", check: "rules-check", label: "threshold" },
+    "rules.softThreshold": { kind: "high", check: "rules-check", label: "soft threshold" },
+    "rules.fallback": { kind: "off", check: "rules-check", label: "fallback" },
+    "rules.maxChars": { kind: "low", check: "rules-check", label: "rules text limit" },
+    "rules.files": { kind: "fewer", check: "rules-check", label: "files" },
+    "rules.exclude": { kind: "more", check: "rules-check", label: "excluded paths" },
+    "rules.skip": { kind: "more", check: "rules-check", label: "skipped paths" },
+    "rules.sensitivePaths": { kind: "fewer", check: "rules-check", label: "sensitive-path notes" },
+    "rulesAtTurnStart.enabled": { kind: "none", why: "a project can only switch it on; switching it off is refused at load" },
+    "rulesAtTurnStart.threshold": { kind: "none", why: "a project can only lower it, which names more rules" },
+    "security.enabled": { kind: "none", why: "a project cannot switch security off; the value is refused at load" },
+    "security.threshold": { kind: "none", why: "a project cannot raise the threshold; the value is refused at load" },
+    "security.maskOutput": { kind: "none", why: "user file only: a repository must not unmask credentials" },
+    "security.shareLinkParams": { kind: "none", why: "user file only: it excuses a share-link token" },
+    "action.enabled": { kind: "none", why: "a project can only switch the guard on; switching it off is refused" },
+    "action.tools": { kind: "none", why: "a project can only add guarded tools, which guards more" },
+    "action.failOpen": { kind: "none", why: "a project cannot turn fail-open on; the value is refused" },
+    "action.ask.enabled": { kind: "none", why: "a project can only switch the ask gate on" },
+    "action.traceSample": { kind: "none", why: "how much trace-only signal is sampled, not a call decision" },
+    "action.timeoutMs": { kind: "none", why: "user file only" },
+    "action.irreversible.warn": { kind: "none", why: "a project cannot raise the warn threshold; the value is refused" },
+    "action.irreversible.confirm": { kind: "none", why: "a project cannot raise the hold threshold; the value is refused" },
+    "action.offTask.warn": { kind: "high", check: "off-task steer", label: "warn threshold" },
+    "action.offTask.steer": { kind: "high", check: "off-task steer", label: "steer threshold" },
+    "action.intentMismatch": { kind: "high", check: "intent-mismatch steer", label: "threshold" },
+    "action.visibleMismatch": { kind: "high", check: "intent-mismatch steer", label: "visible-action threshold" },
+    "action.intentTraceOnly": { kind: "scale", check: "intent-mismatch steer", label: "trace-only mode", order: ["all", "invisible", "none"] },
+    "action.shouldProceed.threshold": { kind: "high", check: "should-proceed steer", label: "threshold" },
+    "action.shouldProceed.steer": { kind: "off", check: "should-proceed steer" },
+    "action.feedbackLog": { kind: "none", why: "the hold record, not a check" },
+    "action.commandRules": { kind: "none", why: "user file only" },
+    "action.commandDenyRules": { kind: "none", why: "user file only" },
+    "action.exemptRules": { kind: "none", why: "user file only" },
+    "action.pathRules": { kind: "none", why: "user file only" },
+    "action.armingRules": { kind: "none", why: "user file only" },
+    "action.escalationThreshold": { kind: "high", check: "escalation", label: "threshold" },
+    "action.floor": { kind: "none", why: "user file only" },
+    "context.enabled": { kind: "off", check: "context-check" },
+    "context.tailMinChars": { kind: "none", why: "how output is trimmed, not a check" },
+    "context.confidence": { kind: "none", why: "how a retention answer is trusted" },
+    "context.duplicateMinChars": { kind: "none", why: "when an output counts as a repeat" },
+    "context.recallTool": { kind: "none", why: "which tool recalls a stored output" },
+    "context.formatConfidence": { kind: "none", why: "how a named output format is trusted" },
+    "context.compactAppendix": { kind: "none", why: "an appendix after compaction" },
+    "context.dedupeRuns": { kind: "none", why: "repeated outputs in one run" },
+    "context.dedupeMessages": { kind: "none", why: "repeated outputs across messages" },
+    "context.largeOutput.enabled": { kind: "off", check: "large-output notice" },
+    "context.largeOutput.threshold": { kind: "high", check: "large-output notice", label: "threshold" },
+    "context.filter.enabled": { kind: "none", why: "user file only: it sends whole outputs to the judge" },
+    "context.filter.chunkChars": { kind: "none", why: "how a filtered output is chunked" },
+    "context.filter.minScore": { kind: "none", why: "how a filtered chunk is scored" },
+    "context.filter.maxKeptChars": { kind: "none", why: "how much of a filtered output is kept" },
+    "context.filter.timeoutMs": { kind: "none", why: "the filter's own deadline" },
+    "runaway.enabled": { kind: "off", check: "runaway stop" },
+    "runaway.repeats": { kind: "high", check: "runaway stop", label: "text repeats" },
+    "runaway.thinkingRepeats": { kind: "high", check: "runaway stop", label: "thinking repeats" },
+    "runaway.minChars": { kind: "high", check: "runaway stop", label: "minimum chars" },
+    "runaway.recover": { kind: "none", why: "what happens after a runaway stop, not the stop" },
+    "notify.enabled": { kind: "off", check: "notify" },
+    "notify.cooldownMs": { kind: "high", check: "notify", label: "cooldown" },
+    "notify.command": { kind: "none", why: "user file only: a project never names a command" },
+    "judge.cooldownMs": { kind: "high", check: "judge", label: "cooldown" },
+    "judge.failuresBeforeCooldown": { kind: "low", check: "judge", label: "failures before cooldown" },
+    "subagent.enabled": { kind: "off", check: "subagent triage" },
+    "subagent.wake": { kind: "off", check: "subagent wake" },
+    "subagent.observer": { kind: "off", check: "subagent observer" },
+    "subagent.threshold": { kind: "high", check: "subagent wake", label: "threshold" },
+    "subagent.cooldownMs": { kind: "high", check: "subagent wake", label: "cooldown" },
+    "waste.enabled": { kind: "off", check: "waste note" },
+    "waste.tip": { kind: "off", check: "waste tip" },
+    "waste.every": { kind: "high", check: "waste note", label: "calls between notes" },
+    "waste.sleep": { kind: "off", check: "waste sleep note" },
+    "waste.paging": { kind: "off", check: "waste paging note" },
+    "waste.search": { kind: "off", check: "waste search note" },
+    "waste.recheck": { kind: "off", check: "waste recheck note" },
+    "compaction.enabled": { kind: "none", why: "user file only: turning it on spends requests" },
+    "compaction.keepThreshold": { kind: "none", why: "how much context is kept" },
+    "compaction.maxSummaryTokens": { kind: "none", why: "the summary's size" },
+    "compaction.timeoutMs": { kind: "none", why: "the compaction deadline" },
+    "compaction.maxRequests": { kind: "none", why: "the compaction budget" },
+    "compaction.skipProviders": { kind: "none", why: "which providers keep their own summary" },
+    "prefs.enabled": { kind: "none", why: "standing preferences are context, not a check" },
+    "prefs.inject": { kind: "none", why: "standing preferences are context, not a check" },
+    enabled: { kind: "none", why: "a project can only switch pi-warden on; switching it off is refused" },
+};
+/** A config value by its dotted path. */
+function valueAt(config, path) {
+    let current = config;
+    for (const part of path.split(".")) {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/** A list value as the items a project file adds or leaves out; a map counts by its keys. */
+function itemsOf(value) {
+    if (Array.isArray(value))
+        return value.map(String);
+    if (value !== null && typeof value === "object")
+        return Object.keys(value);
+    return [];
+}
+/** Every check `layered` loosens compared with `user`, in a stable order. Empty when the project file loosens nothing. */
+export function loosenedChecks(user, layered) {
+    const checks = [];
+    for (const [path, entry] of Object.entries(PROJECT_KEYS)) {
+        if (entry.kind === "none")
+            continue;
+        const before = valueAt(user, path);
+        const after = valueAt(layered, path);
+        const name = entry.check;
+        if (entry.kind === "off") {
+            if (before === true && after === false)
+                checks.push({ name, ...(entry.label === undefined ? {} : { detail: entry.label }) });
+            continue;
+        }
+        if (entry.kind === "high" || entry.kind === "low") {
+            if (typeof before !== "number" || typeof after !== "number")
+                continue;
+            if (entry.kind === "high" ? after > before : after < before)
+                checks.push({ name, detail: `${entry.label ?? "value"} ${before} → ${after}` });
+            continue;
+        }
+        if (entry.kind === "scale") {
+            const order = entry.order ?? [];
+            const moved = order.indexOf(String(before)) > order.indexOf(String(after)) && order.includes(String(before)) && order.includes(String(after));
+            if (moved)
+                checks.push({ name, detail: `${entry.label ?? "mode"} ${String(before)} → ${String(after)}` });
+            continue;
+        }
+        const lost = entry.kind === "fewer" ? itemsOf(before).filter(item => !itemsOf(after).includes(item)) : itemsOf(after).filter(item => !itemsOf(before).includes(item));
+        if (lost.length)
+            checks.push({ name, detail: `${entry.label ?? "entries"} ${entry.kind === "fewer" ? "left out" : "added"}: ${lost.join(", ")}` });
+    }
+    return checks;
+}
+/** The one line a session start shows for a loosened set: what the project file takes away, and from which file. */
+export function loosenNotice(checks, dirs = defaultHostDirs()) {
+    const items = checks.map(check => (check.detail === undefined ? check.name : `${check.name} (${check.detail})`));
+    const verb = checks.every(check => check.detail === undefined) ? "switches off" : "loosens";
+    return `This project's ${join(dirs.configDirName, PROJECT_CONFIG_FILE)} ${verb}: ${items.join(", ")}.`;
+}
+/** Where the last loosened set for a project is kept: beside the user config, keyed by the project path. */
+export function loosenRecordPath(cwd, dirs = defaultHostDirs()) {
+    const project = createHash("sha256").update(cwd).digest("hex").slice(0, 12);
+    return join(dirname(userConfigPath(dirs)), "project-config", `${project}.json`);
+}
+/** The checks last recorded for this project; undefined when no record exists, it cannot be read, or it predates
+ *  details (a names-only record is a different set, so the line shows once more after the upgrade). */
+export function readLoosenRecord(cwd, dirs = defaultHostDirs()) {
+    const raw = readJson(loosenRecordPath(cwd, dirs));
+    if (raw?.version !== 2 || !Array.isArray(raw.loosened))
+        return undefined;
+    const checks = [];
+    for (const item of raw.loosened) {
+        if (!isObject(item) || typeof item.name !== "string")
+            return undefined;
+        if (item.detail !== undefined && typeof item.detail !== "string")
+            return undefined;
+        checks.push({ name: item.name, ...(typeof item.detail === "string" ? { detail: item.detail } : {}) });
+    }
+    return checks;
+}
+/** Records the loosened set now shown for this project, so the same set stays quiet until it changes. A read-only
+ *  agent directory must not stop a session: the record is an optimisation, and an unwritable one shows the line again. */
+export function writeLoosenRecord(cwd, checks, dirs = defaultHostDirs()) {
+    try {
+        writeFileAtomicSync(loosenRecordPath(cwd, dirs), `${JSON.stringify({ version: 2, loosened: checks.map(check => (check.detail === undefined ? { name: check.name } : { name: check.name, detail: check.detail })) }, null, 2)}\n`);
+    }
+    catch (error) {
+        console.warn("pi-warden: could not record the loosened project checks:", error instanceof Error ? error.stack ?? error.message : String(error));
+    }
+}
 export function loadConfig(options = {}) {
     const dirs = options.dirs ?? defaultHostDirs();
-    let config = applyUserOverrides(defaultConfig(), readJson(userConfigPath(dirs)));
-    if (options.cwd && options.projectTrusted)
-        config = applyProjectOverrides(config, readJson(projectConfigPath(options.cwd, dirs)));
-    return config;
+    let config = applyUserOverrides(defaultConfig(), options.userRaw ? options.userRaw.value : readJson(userConfigPath(dirs)));
+    if (!options.cwd || !options.projectTrusted)
+        return config;
+    const project = options.projectRaw ? options.projectRaw.value : readProjectConfig(options.cwd, dirs);
+    return applyProjectOverrides(config, project);
 }
 /** Reads only the user file, for editing and persisting consent. */
 export function readUserConfig(dirs = defaultHostDirs()) {

package/dist/done.js

@@ -600,7 +600,7 @@ export function doneNudge(verdict, hint = {}) {
             : "Run the project's tests, build, or lint (whatever exists) on what you changed.";
     const code = codeUnverified ? ` ${detail} Then report the actual result. If no check exists or can run, say so explicitly instead of presenting the work as done.` : "";
     const open = hint.localUrl !== undefined ? `Open ${redact(hint.localUrl)} in a browser` : "Open it in a browser";
-    const ui = verdict.unseenUi !== undefined ? ` You changed \`${redact(verdict.unseenUi)}\` but did not look at the result. ${open} or take a screenshot before calling it done, or say it is unverified.` : "";
+    const ui = verdict.unseenUi !== undefined ? ` You changed \`${redact(verdict.unseenUi)}\` but did not look at the result. ${open} or take a screenshot before calling it done, or say it is unverified. It counts when you see the changed page after the change: a page snapshot, a passing browser or device test, or a screenshot of the page that you then read (a screenshot saved to a file counts only once you read it).` : "";
     return `pi-warden: ${verdict.reasons.join("; ")}.${code}${ui}`;
 }
 export function formatDone(verdict, template = DEFAULT_TEMPLATES.done) {