pi-lens 4.4.0 → 4.4.2

package/docs/lsp-idle-eviction.md

@@ -15,7 +15,7 @@ respawned server reports every finding it reported before eviction; the
 content-bound coverage check the auxiliary freeze depends on. A server that
 cannot demonstrate it is never proposed for eviction on perf grounds alone.
 
-_Last generated: 2026-10-07 on linux; 48 registry servers: 32 eligible, 0 vetoed, 2 inconclusive, 14 unavailable (0 not reached: budget)._
+_Last generated: 2026-10-10 on linux; 48 registry servers: 8 eligible, 0 vetoed, 16 inconclusive, 24 unavailable (0 not reached: budget)._
 
 ## Per-server rows
 
@@ -35,54 +35,54 @@ step log only, because it flaps.
 
 | server | role | declared | result | reason | respawn | coverage |
 |---|---|---|---|---|---|---|
-| ast-grep | auxiliary | unmeasured | eligible | · | ok | preserved |
-| bash | primary | transparent | eligible | · | ok | preserved |
+| ast-grep | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
+| bash | primary | transparent | unavailable | server-not-started | n/a | n/a |
 | clojure | primary | transparent | eligible | · | ok | preserved |
 | cmake | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
 | cpp | primary | transparent | eligible | · | ok | preserved |
 | csharp | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
-| css | primary | transparent | eligible | · | ok | preserved |
-| cue | primary | unmeasured | eligible | · | ok | preserved |
+| css | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| cue | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | dart | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | deno | primary | transparent | eligible | · | ok | preserved |
-| docker | primary | unmeasured | eligible | · | ok | preserved |
-| docker-official | primary | unmeasured | unavailable | no-fixture | n/a | n/a |
+| docker | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| docker-official | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | elixir | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
-| expert | primary | unmeasured | eligible | · | ok | preserved |
-| fish | primary | transparent | eligible | · | ok | preserved |
+| expert | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
+| fish | primary | transparent | unavailable | server-not-started | n/a | n/a |
 | fsharp | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
-| gleam | primary | unmeasured | eligible | · | ok | preserved |
+| gleam | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | go | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | haskell | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
-| html | primary | transparent | eligible | · | ok | preserved |
+| html | primary | transparent | unavailable | server-not-started | n/a | n/a |
 | java | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
-| json | primary | unmeasured | eligible | · | ok | preserved |
-| kotlin | primary | unmeasured | eligible | · | ok | preserved |
-| lua | primary | unmeasured | eligible | · | ok | preserved |
+| json | primary | transparent | eligible | · | ok | preserved |
+| kotlin | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
+| lua | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | marksman | primary | transparent | eligible | · | ok | preserved |
 | nix | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | ocaml | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
 | omnisharp | primary | unmeasured | unavailable | no-fixture | n/a | n/a |
 | opengrep | auxiliary | transparent | eligible | · | ok | preserved |
-| php | primary | transparent | eligible | · | ok | preserved |
-| powershell | primary | unmeasured | eligible | · | ok | preserved |
-| prisma | primary | transparent | eligible | · | ok | preserved |
-| python | primary | transparent | eligible | · | ok | preserved |
-| python-jedi | primary | unmeasured | eligible | · | ok | preserved |
+| php | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| powershell | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
+| prisma | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| python | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| python-jedi | primary | transparent | eligible | · | ok | preserved |
 | ruby | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
-| rust | primary | unmeasured | eligible | · | ok | preserved |
+| rust | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | shuck | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
-| svelte | primary | unmeasured | eligible | · | ok | preserved |
+| svelte | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
 | swift | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
-| terraform | primary | unmeasured | eligible | · | ok | preserved |
-| tinymist | primary | unmeasured | eligible | · | ok | preserved |
-| toml | primary | unmeasured | eligible | · | ok | preserved |
+| terraform | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
+| tinymist | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
+| toml | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 | typescript | primary | transparent | eligible | · | ok | preserved |
-| typos | auxiliary | unmeasured | eligible | · | ok | preserved |
-| vue | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
-| yaml | primary | transparent | eligible | · | ok | preserved |
-| zig | primary | unmeasured | eligible | · | ok | preserved |
-| zizmor | auxiliary | unmeasured | eligible | · | ok | preserved |
+| typos | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
+| vue | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
+| yaml | primary | transparent | unavailable | server-not-started | n/a | n/a |
+| zig | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
+| zizmor | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
 
 ## Declared versus measured
 
@@ -90,24 +90,15 @@ step log only, because it flaps.
 or `info` line is for a maintainer to act on in a follow-up; this run changed
 nothing.
 
-- **ast-grep** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **cue** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **docker** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **expert** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **gleam** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **json** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **kotlin** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **lua** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **powershell** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **python-jedi** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **rust** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **svelte** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **terraform** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **tinymist** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **toml** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **typos** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **zig** [proposal] declared unmeasured but eviction and respawn preserved its findings
-- **zizmor** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **bash** [info] declared transparent with no evidence this run: unavailable (server-not-started)
+- **css** [info] declared transparent with no evidence this run: unavailable (server-not-started)
+- **docker** [info] declared transparent with no evidence this run: unavailable (server-not-started)
+- **fish** [info] declared transparent with no evidence this run: unavailable (server-not-started)
+- **html** [info] declared transparent with no evidence this run: unavailable (server-not-started)
+- **php** [info] declared transparent with no evidence this run: unavailable (server-not-started)
+- **prisma** [info] declared transparent with no evidence this run: unavailable (server-not-started)
+- **python** [info] declared transparent with no evidence this run: unavailable (server-not-started)
+- **yaml** [info] declared transparent with no evidence this run: unavailable (server-not-started)
 
 ## Reasons
 

package/docs/pi-lens-fixer.md

@@ -10,6 +10,10 @@ mechanics"; a brief supplies only `lane=<name>`, scope, and the grant.
 
 ## Before code
 
+Before mocking a `clients/` module, look for its test seam (`set*`, `adopt*`, or
+`reset*`). The pre-flight must list the mock dependents of any module whose
+exports change.
+
 - Trace the production entry point and reproduce the defect through it
   (principles §1, "Premise first"). Name no seam before the reproduction; the
   red reproduction is your feedback loop, built before any theory of the fix.
@@ -34,10 +38,11 @@ mechanics"; a brief supplies only `lane=<name>`, scope, and the grant.
   preserves or tightens, and show the violating config red on the pre-fix model
   and green after, or carry `TLA+ unaffected: <family> — <reason>` in the PR
   body. A row is any-of (one listed family's model move or declaration
-  satisfies it); a row of 4+ families only prints a note until hunk-level
-  matching exists (#3878). The map owner is the lane that adds a
-  `formal/<family>/`: it adds the family and its map row in the same PR, and
-  `validateCoverageMap` reds the Unit tests lane otherwise.
+  satisfies it); a row of 4+ families only prints a note, except `index.ts`,
+  whose row gates on the lifecycle hook handler a hunk lands in (#3878). The
+  map owner is the lane that adds a `formal/<family>/`: it adds the family and
+  its map row in the same PR, and `validateCoverageMap` reds the Unit tests lane
+  otherwise.
 - Seams are named in the brief before the round. A fixer that needs an
   unconfirmed seam stops and reports it as a finding, not as a test.
 
@@ -158,7 +163,10 @@ rigor (#2599).
   must pass, and the hand-back quotes them. A red `PR body (advisory)` check is
   a fix-before-review item. A changelog fragment is `---` /
   `section: <Added|Changed|Deprecated|Removed|Fixed|Security>` /
-  `audience: <user|internal>` / `---` / blank / one `- ` bullet. `audience` is
+  `audience: <user|internal>` / `---` / blank / one `- ` bullet. New
+  `audience: user` fragments must begin with a bold lead of at most 100
+  characters, excluding issue references; internal fragments are exempt.
+  `audience` is
   required: `user` is anything a pi-lens user or agent can observe (tools,
   diagnostics, messages, config, install, performance, a fixed bug they could
   hit); `internal` is CI, tests, `formal/`, contributor docs, orchestration, and

package/docs/pi-lens-merge-policy.md

@@ -267,7 +267,7 @@ operator's private notes, so a different orchestrator can run the same train.
   | a new fixture under `tests/fixtures/` | the fixture-contract sweeps for that directory (style-preserving, population guards) — #2782 r2 |
   | a change that touches identifier uses of a glossary-retired synonym | run `tests/config/glossary-synonym-sweep.test.ts` on the head AND on the merge with `origin/master`, then re-pin in the PR from the sweep's own `UNPINNED`/`STALE` output — #3279, #3283, #3284, #3288 |
   | a new `vi.mock` in a test file | run `tests/config/vi-mock-export-sweep.test.ts`; whole-module mocks of a production module must spread `importOriginal` — PR #3268's CI red, fixed by trailing commit `621d61c5c` |
-  | a changelog fragment | front matter `section: <Section>` plus `audience: user` or `audience: internal` and exactly one top-level `- **Title (refs #N)** —` entry, never `CHANGELOG.md`, validated by `node scripts/check-changelog-fragments.mjs` — PR #3268 r1 shipped `category:` and a paragraph |
+  | a changelog fragment | front matter `section: <Section>` plus `audience: user` or `audience: internal` and exactly one top-level entry; new user entries open with a bold lead of at most 100 characters (refs excluded), never `CHANGELOG.md`, validated by `node scripts/check-changelog-fragments.mjs` — PR #3268 r1 shipped `category:` and a paragraph |
   | a PR body | the header gate: exactly one-sentence `## Why`, `## Notes for the reviewer`, `## Change outline`, plus Summary / Tests with `### Test assessment` / Blast radius / Class sweep / Observability; run `node scripts/check-pr-body.mjs --lint-local` before pushing — three PRs this week needed orchestrator body edits |
   | a whole-tree docs restructure of `AGENTS.md` | every governance test that reads `AGENTS.md`, with markers on their own lines — PR #3265 r1 |
   | a raw poll in a test | the flake-shape ratchet; the fix is the governed wait, never a header admission — #2781 r1 |
@@ -611,6 +611,11 @@ Each row cost a lane at least once; the prose above carries the record.
 
 | Mistake | Fix |
 |---------|-----|
+| Writing incident numbers and examples into an `AGENTS.md` rule | AGENTS.md stays lean; issues, PRs and examples go to `HISTORY.md` (maintainer, 2026-10-10). `tests/config/agents-governance.test.ts` ratchets the reference count down only |
+| Routing a review finding as one PR's bug when it is a member of a class | Name the shape, grep for members, and record the verdict before the fix round; `plegma-delegate-guard` refuses a fix brief with a HIGH/MEDIUM finding and no `Shape:` line |
+| Taking a causal premise ("a later merge dropped X") from a hand-back into a PR body or brief | Bisect before writing it: `git show <sha>:<file>` along the path from the fix commit to master. A lane round can revert its own earlier round, and that is not a merge drop |
+| Trusting a wrapper script's exit status when it echoes a check's result | `pr-body.sh lint` printed `lint-exit=1` and exited 0, so a failing body went live; the wrapper now exits with the check's status. Read the check's own result line |
+| Hand-rolling the governance suite in a fresh worktree | `npm run build` alone left `dist/` missing and three census suites red; use the orchestrator's `gov-check.sh <tree>`, which builds both outputs and keeps the `node_modules` link for the commit hook |
 | Reading a CI verdict without checking the SHA it judged | `ci-verdict --wait` returned exit 0 for the PREVIOUS head seconds after a push (#2878 trailing, 2026-09-10); compare the verdict's SHA with `gh pr view --json headRefOid` before merging |
 | Reporting "pushed" before `git log -1` shows the commit | Two trailing commits failed the pre-commit hook (changelog one-entry rule, unused vars) and the ledger/body already said pushed; verify the head, then write the row |
 | Folding a worker's extra changelog fragment into an existing one | One fragment = one top-level entry (`rollup-changelog --check`); keep a second fragment separate or drop it |
@@ -692,3 +697,45 @@ Each row cost a lane at least once; the prose above carries the record.
 | Enabling auto-merge before local HEAD equals the pushed SHA | Verify the pushed SHA before enabling auto-merge (#3671) |
 | Waiting for CI after retargeting a base without a push | Push after a base retarget to re-arm CI (#3679) |
 | Leaving fork-PR `action_required` runs unapproved | Approve the runs after pushing to a fork PR (#3656) |
+| Writing a closing keyword on a partial delivery | #4021's title said "closes #1513" while its notes said the global-bin walk remained; the merge auto-closed #1513 and it was reopened by hand (2026-10-07). Close only when every acceptance criterion is met; otherwise write `Refs #N` and post the remainder before merging. Title and body must agree |
+| Two writers doing read-modify-write on one shared record without a lock | The orchestrator ledger lost a freshly written row: a sync script read the file, a row was appended, the sync wrote back its stale copy (2026-10-07). Every writer of a shared record holds one lock across the whole read-modify-write (principles §1, "Design shared state once") |
+| Paraphrasing an acceptance criterion into a review brief | A combination-review brief for #3997 said substituted labels "must reject" where they must be accepted when they form an identifier (2026-10-06). Quote the criterion from the PR body or issue; never restate its polarity from memory |
+| Treating a `completed` settlement as delivered when its declared report is missing | Two codex settlements in one batch wrote `REVIEW.md` instead of the declared `REVIEW_4024.md`, or only a GitHub comment (plegma #689; 2026-10-07). Check the declared file exists; else read the file the worker's final line links, and release by hand |
+| Assuming a hook added mid-session is live | A `SubagentStop` hook added to `.claude/settings.local.json` mid-session never fired and did not show under `/hooks` (2026-10-07). Hooks load at session start: confirm under `/hooks` after adding one, or restart before relying on it |
+| Leaving a lane's report inside the checkout that gets torn down | Closing a reviewer's worktree deleted its `REVIEW_4028.md`; the fix round worked from a relayed list (2026-10-07). Reports go outside worktrees (the handbacks directory), and teardown copies any root report out first |
+| Relying on a declared deliverable name the worker never sees | plegma does not pass `deliverables:` into the delivered task; 4 of 4 briefs that omitted the file name got `REVIEW.md` or no file, 2 of 2 that named it were followed (plegma #689; 2026-10-07). Name every declared file in the brief text |
+| Telling a worker to dispatch a workflow without checking what it publishes | A brief asked a fixer to `gh workflow run` its branch; the job publishes `data/test-history` with no ref guard, and the queued run would have pushed unreviewed rollup output with an oldest-row eviction (#4037, cancelled; 2026-10-07). Read the workflow's push and publish steps and their `if:` guards before asking for a branch dispatch |
+| Trusting a `completed` fix round without checking the PR head moved | The #3997 maintainer round settled `completed` while its lease push to the base repo was rejected; the commit sat in the worker tree (plegma #692; 2026-10-07). After each fix round, compare `gh pr view --json headRefOid` with the worker's commit |
+| Raising a timing budget without proving the guard still reds | A request to widen a 300 ms occupancy budget to 500 ms; the yield-removal mutation measured 220 ms locally while healthy CI measured 324–520 ms, so the guard was vacuous at either value (2026-10-07). Mutate the regression the budget exists for before moving the number |
+| Re-running a broad suite after a one-file conflict resolution | A census-conflict merge on #4013 re-ran `tests/scripts` plus governance (~240 files) the reviewer had just run green on the prior head; the 4 affected files already passed (2026-10-07). Run the files the resolution touches; CI runs the rest |
+| Claiming a measured fact from a partial grep | The orchestrator told the maintainer the merge-train warden's last 20 runs "took zero actions"; the grep had counted only update-branch, rerun and cancel calls, and the runs had posted 24 PR comments and 37 label changes (#4105, 2026-10-07). The maintainer decided on the wrong number and had to re-confirm. Count every effect a component can have before calling it inert |
+| Letting one transient backend error re-route a whole day | A single Luna `Selected model is at capacity` failure moved about 15 later fix lanes to Claude Sonnet while codex had 80% weekly budget and 4 free slots; Claude's weekly budget reached 50% (2026-10-07/08). Treat a capacity error as transient, retry on the next dispatch, and check `plegma_quota` before every Claude fixer |
+| Reading CI in a chain whose push silently did nothing | A background chain gated its push on `&&` after a build that never ran, then read the unchanged head's red Windows job as the "fixed head" result and wrote it into #4111's body (2026-10-07). After every push, compare `gh pr view --json headRefOid` with the pushed commit before reading any CI |
+| Diagnosing a red from the first `##[error]` line | #4054's shard-5 red was called "npm registry unreachable"; that line came from a passing stubbed test, and the real failure was a 5 s timeout in check-pr-body.test.ts (#4088, 2026-10-07). Read the FAIL lines; treat annotation lines from stubbed tests as noise |
+| Triggering CI on a bot PR before checking whether a run already exists | land.sh closed and reopened #4084 30 s after an update-branch, before the new run registered, which cancelled the run, and the cancelled aggregate read red (2026-10-07). Reopen only when no run exists for the head after a real wait |
+| Writing a closing keyword where GitHub does not honour it, or by accident | #4121's title said `closes #3873`, which fails the close-keyword check (titles are never honoured); #4094's body said "then fixed #4080", an accidental closing keyword (2026-10-07). Put closing keywords in the body only, and reread the body for `fix(es\|ed) #N` prose |
+| Seeding a group list from the active queue instead of the tracker | The orchestrator's session group held 3 issues while `area:session` had 8 more open p2s, so "is the session group done?" was answered from an incomplete list (2026-10-08). Build a group from the label and the tracker, then subtract what is out of scope |
+| Filing every LOW review finding as an issue | Each review spawned about one follow-up, so the CI group stayed at about 36 open after 16 closures (2026-10-07). Fold or drop LOW findings; file only MEDIUM and above or a reproduced sibling, and give each group a "done when" |
+| No cleanup when lanes end | 78 GB of finished lane trees and a 22 GB leaking test TMPDIR filled the root disk twice; two reviewers lost probe runs and one fixer's test file was truncated (2026-10-07). Remove a lane's trees and TMPDIR when its PR merges, and keep a disk alarm |
+| Deriving the next round from a stale brief or a stale premise | #3871's brief asked for a selection fix #3903 had already shipped, and #3813's assumed every producer was unfixed; both fixers correctly refused to rebuild merged work (2026-10-07). Re-check the premise on current master when a lane starts, not when the issue was filed |
+| Calling a PR-owned hygiene leak pre-existing because the same files fail on a later run | The PR's own CI run exposed the leak, but the reviewer classified it as a flake and fixed an unreachable injected path; the PR review and red-on-base comparison should have owned the finding. The hygiene check now treats a new leak on a green-master PR as CAUSED-BY-PR until red-on-base proves otherwise, and harness children receive a private `TMPDIR` (#4133, #4128). |
+| Passing a commit SHA where a command expected wait seconds | The shell invocation was caught by the command's outcome review; argument-shape validation should have caught it before execution. `land.sh` now validates the wait argument and prints its outcome line. |
+| Losing executable mode in an atomic `.new` to `mv` replacement | The next invocation caught the non-executable script; the file-install check should have compared mode as well as bytes. The replacement now preserves the executable bit. |
+| Reusing a finished PR row for `lane-set --new` | The lane ledger exposed the wrong PR identity; the row allocator should have rejected terminal rows before allocation. New rows now require an unused active identity. |
+| Matching a flake on text that CI never prints | The unmatched CI output was noticed during review; the matcher test should have used a captured CI transcript. The flake matcher now keys on the classifier's actual output. |
+| Letting keyword-title lint contradict the repository convention | The title gate review found the contradiction; the title-convention test should have pinned the accepted form. The lint rule now follows the repository's title convention. |
+| Relaying a shard failure to a fixer without mirroring it on the PR | The fixer noticed the missing scope record; the scope-mirror hook should have rejected the handoff. The handoff path now records the scope on the PR before dispatch. |
+| Treating a repeatedly red advisory lane as harmless | The maintainer's retrospective found the 21% flake after a misleading PR draw; the advisory policy and newest-master comparison should have held the PR. `land.sh` now holds a PR-red/master-green advisory unless `ADVISORY_OK=1`. |
+| Forgetting to arm the landing chain after a trailing fix | A later PR-GREEN event exposed that the fix was waiting unarmed; the trailing-fix command should have verified arming. Rule: after a trailing fix, arm `land.sh` in the same step (not yet mechanised). |
+| Accepting an identity trade-off without a complete timing-cell table | Cloud verification found primary-item loss after the trade-off was accepted from prose; the fixer's state table and review should have enumerated every timing cell. The brief now requires the complete state table before accepting the trade-off. |
+| Letting a scoped test exceed Vitest's default timeout | A repeated cloud review caught the timeout; the local targeted run should have exercised the test under its default timeout. Rule: a scoped review runs new tests under the default Vitest timeout before passing them (not yet mechanised). |
+| Specifying a truncation mechanism instead of an output acceptance criterion | The orchestrator's output read found cut lines after the worker followed the brief; the brief should have stated the required output (complete first sentence, no ellipsis). Rule: acceptance names the required output, not only the mechanism. |
+| Adding a second idle timer without naming the probe consumer | The nightly eviction probe caught the missing configuration coverage; the change's call-tree diff should have listed every idle-timer environment setter. The configuration test now requires every client-read idle timer to be armed by the probe. |
+| Reproducing only one step of a multi-step release-body producer | A user noticed the missing Thanks section; the release-body test should have run the complete producer chain. `bin/relnotes-regen.sh` now runs both steps and refuses to lose the section. |
+| Basing a real-pi premise on an unavailable maintainer-machine probe | The fixer could not rerun the stale probe and the recurrence was found in review; the premise check should have required a repository witness. Fix briefs now require a `tests/real-harness` witness using `withRealPi` and a scripted provider. |
+| Sending a sandboxed verifier a brief path instead of its contents | The verifier reported that the brief was unreadable; the dispatch smoke test should have inspected the delivered argument. Verification now inlines file arguments. |
+| Allowing a mocked handler to throw so every assertion passes vacuously | Verify found the non-blocking degradation; the test double should have failed explicitly when the handler throws. Rule: a test asserting a handler verdict must also assert that no handler-throw degradation was recorded; a shared helper is a candidate, not yet built. |
+| Trusting a worker hand-back that omitted exact test summaries and misreported fixes | Review found nine CAUSED-BY-CHANGE failures and unsupported “fixed” and TLA+ claims; the hand-back check should have required exact summary lines and reviewer red-on-base reruns. Fix lanes now paste the named Vitest summaries and verify identity claims. |
+| Adapting repository fixtures to a Plegma guard failure | Verify caught the harness-specific workaround; the fixture lane should have reported the environment block without changing repository tests. Plegma-guard fixture failures are now reported as environmental. |
+| Reading a piped command's exit status instead of its outcome record | A pending chain was reported as successful because `tail` returned zero; the landing check should have read the chain's own result. `land.sh` now prints `LAND-RESULT #N: <state> (rc=N)`, which callers must read. |
+| Routing a same-seam new defect to a weaker fixer after a prior round | The next verify found the same-seam defect after a Luna-high assignment; round routing should have selected Opus from the seam and round count. Rule: a new same-seam defect after two rounds goes to Opus (cloud fixer when the subscription is short) with the state table and model step first. |

package/docs/pi-lens-monitor.md

@@ -29,7 +29,9 @@ memory growth:
   process.externalNonBufferBytes; no tree-count estimate is emitted.
 - subsystems.wordIndex.wireBytes is the UTF-8 length of the word index's JSON,
   taken natively while the snapshot persist encodes the body, and is null
-  until that index's current serialized form is persisted.
+  until that index's current serialized form is persisted, and again once the
+  serialized form is released at `agent_settled` (the `word_index_memo_released`
+  row in latency.log records the release and its trigger).
 - samplerDurationMs measures the sampler's own record-assembly wall time,
   excluding the surrounding turn.
 

package/docs/pi-lens-retro.md

@@ -61,7 +61,8 @@ is involved. Every finding cites the source it came from.
    exactly as a regression test would; a check without a red is a proposal and
    is filed as an issue naming the incident as its recurrence, not merged.
 4. **Judgement candidates become one line in the right place.** A defect shape
-   goes into the `AGENTS.md` catalog with the reference; a reviewer duty goes
+   goes into the `AGENTS.md` catalog as a lean screen, and its issues, PRs and
+   examples go to `HISTORY.md`; a reviewer duty goes
    into `docs/pi-lens-reviewer.md`; a fixer duty goes into `docs/pi-lens-fixer.md`
    only when the fixer is the sole actor who can honour it. Standards are
    enforced by the reviewer, whose context pressure is lowest; fixers get

package/docs/pi-lens-reviewer.md

@@ -52,6 +52,11 @@ a brief supplies only `lane=<name>`, scope, and the grant.
 
 ## Verification
 
+For each new or changed `vi.mock` or hand-built double of a `clients/` module,
+check whether a real test seam exists (`set*`, `adopt*`, or `reset*`). If it
+does, treat the double as a finding and require the behavior to run through the
+real seam. Check that every gate the diff adds is exercised through that path.
+
 - **Name the behaviour population.** When a change replaces, moves, or widens
   a lifecycle, dispatch, or ownership seam, run EVERY suite that exercises the
   behaviour the seam governs and name the list; a curated file set cannot
@@ -73,6 +78,8 @@ a brief supplies only `lane=<name>`, scope, and the grant.
   a review input.
 - Repeat the pattern and population sweeps. Check blast radius, bounded
   observability, changelog, commit, and PR-body requirements.
+- Re-run the PR's `## Class sweep` search yourself and widen it when the
+  named shape is broader than the touched seam (#4273, #4268).
 - For LSP, dispatch, cache, runner, or tool changes, test one non-TypeScript
   registry entry through the same seam.
 - On a net-count fold, mutate every predicate the deleted sibling used to
@@ -100,9 +107,10 @@ Run every probe the diff can trip and say which ran and what each returned.
 - **Model covers the change, not only TLC green (#3802).** When the diff
   touches a file mapped in `formal/coverage-map.json`, require a `.tla`/`.cfg`
   change under any one of the row's families or a `TLA+ unaffected: <family> —
-  <reason>` line for any one of them; rows of 4+ families only print a note. A
-  green `TLA+ models` run over an unchanged model proves nothing about the new
-  code.
+  <reason>` line for any one of them; rows of 4+ families only print a note,
+  except `index.ts`, which gates on the lifecycle hook handler a hunk lands in.
+  A green `TLA+ models` run over an unchanged model proves nothing about the
+  new code.
 - **Red-proof audit.** A claimed red without its quoted transcript is a finding
   of its own; reproduce it (step 3).
 - **Quoted-evidence audit.** Diff every CI line the body quotes against the job
@@ -209,3 +217,11 @@ merge-order interactions with other open PRs, plus:
 - Cleared categories (one compact list) and exact-head identity.
 
 Use short, active, plain prose.
+
+## Documentation and prose standard
+
+Apply this standard to PR and issue bodies, review comments, commit messages, documentation, and changelog entries. Lead with the outcome. Remove words that do no work. Use active voice and present tense. Use second person for instructions, and use the imperative for steps. Keep one idea per sentence, with about 20–25 words and no more than 30 words. Use consistent terminology and sentence-case headings. Define acronyms on first use. Prefer plain words over jargon. Avoid `please`, filler, noun piles, nested parentheticals, and em-dash chains. Use the Oxford comma.
+
+The mechanical rules are checked by `scripts/check-prose.mjs`. The checker ignores fenced code, inline code, URLs, quoted log lines, blockquotes, and tables. It blocks long sentences, filler, and title-case headings. It warns on passive voice. The CLI accepts a body file or standard input and supports `--json`.
+
+Reviewers judge clarity, terminology, active voice, sentence structure, and whether each list uses parallel grammar. Treat a mechanically clean result as necessary, not sufficient. Report prose that obscures the outcome or makes a user infer the action.

package/docs/pi-lens-subagent.md

@@ -8,6 +8,8 @@ holds the pi-lens rules every role shares, for every runner and model. The
 principles apply throughout and are not restated; project files win on
 conflict.
 
+User-facing prose follows the live standard in `docs/pi-lens-reviewer.md`.
+
 ## Worktree and Git
 
 Work only in the assigned worktree. Before editing, verify its absolute path,

package/docs/real-harness.md

@@ -12,6 +12,23 @@ process boundary that an in-process test cannot observe.
 4. Call `awaitToolResult("<tool>")` for every expected tool result.
 5. Add the test to `realHarnessInclude` and the real-process-spawn ratchet.
 
+## Persisted-session restart
+
+Pass `persistedSession: true` when a scenario must cross a process boundary.
+The harness creates `--session-dir <home>/sessions` and exposes `pi.resume()`;
+that operation closes stdin on the first child and starts a second child with
+the installed pi CLI's `--continue` flag. The RPC documentation defines
+`new_session` and `clone`, but no resume RPC; `--continue` is therefore the
+authoritative resume operation for this lane. `pi.quit()` closes stdin without
+removing the probe home, so final shutdown records can be read before the
+`withRealPi` cleanup.
+
+Before either orderly stdin close, the harness waits for `latency.log` to keep
+the same size and mtime for 250 ms, bounded by 5 seconds. This protects the
+logger's intentional exit-flush replay trade (#935): closing while its last
+async append is in flight can duplicate that final lifecycle row. A timeout is
+an explicit harness failure, not a reason to proceed with an unstable log.
+
 Scripts contain turns. Each turn contains text or typed tool-call actions.
 Malformed scripts fail validation before the child starts.