pi-lens 4.2.1 → 4.4.0

package/docs/pi-lens-subagent.md

@@ -1,35 +1,32 @@
 # Delegated worker delivery contract
 
-This contract applies to every delegated pi-lens worker, regardless of the
-agent runner or model. Pair it with exactly one role contract: fixer, reviewer,
-or investigator.
+Read first: the engineering principles (`docs/engineering-principles.md`; skip
+it when your harness's global instructions already carry the verbatim copy),
+then `AGENTS.md`, then this contract, then exactly one role contract from
+`docs/pi-lens-{fixer,reviewer,investigator,monitor,warden,retro}.md`. This file
+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.
+
+## Worktree and Git
 
 Work only in the assigned worktree. Before editing, verify its absolute path,
-registered worktree entry, branch, and base. Preserve junctioned dependencies.
-Never switch another checkout's branch, and never use `git stash`. Save a patch
-before temporarily reverting work.
-
-Treat the acceptance criteria as the contract. For a regression, prove the new
-test red before the fix and green after it. Mutating or removing a new guard
-must make at least one test fail. Sweep the whole tree for the same code pattern
-and every member of any enumerable population. Record both sweeps.
-
-State the blast radius, including callers, durable shapes, strict parsers, and
-tool surfaces. Add bounded observability for every new failure path. Include the
-required changelog fragment for a code change: ONE file under `.changelog/`;
-never edit `CHANGELOG.md` itself (it is generated at release; two fixers
-hand-edited it on 2026-09-09 and the orchestrator had to revert both).
-Report verification honestly.
-Write active, direct prose with short sentences and consistent terms.
-
-## Tautological tests considered harmful
-
-A test must observe behavior through the real seam, not repeat the implementation
-or feed the expected answer in through setup. Keep the red-first failure tied to
-the defect, and mutate the guard or filter to prove the test can detect its loss.
-Mocks belong only at true process or host boundaries. When a test can use the
-real store, sink, coordinator, or registry, use it and assert the durable result.
-For a whole-module mock, prefer `vi.mock("./module.js", async (importOriginal) => ({ ...(await importOriginal()), override }))` so new exports pass through by default; annotate dynamic imports as `typeof import(spec)` when needed.
+registered `git worktree list` entry, branch, and base. Preserve linked or
+junctioned dependencies. Never switch another checkout's branch, never pass the
+main checkout's path as `repoRoot` or `cwd` to a probe that writes or deletes
+(#2704), and never use `git stash`. Save a patch before temporarily reverting
+uncommitted work.
+
+A lane never writes files to the shared session scratchpad: lanes spawned from
+one session share it and overwrite each other's fixed names (#3850). Probe
+scripts, PR bodies, and TLC logs go under `$TMPDIR` (its value is in
+"Orchestrator lane mechanics") or `<worktree>/../probes-<lane>`.
+
+The Bash-hook rules in `AGENTS.md` "Contributing" bind every runner, hooked or
+not. Hooks always run. A hook or CI red is unrelated only when
+`scripts/red-on-base.mjs` reports `RED-ON-BASE` for every failing test
+(`AGENTS.md` "Commands and gates"); for a hook, then STOP and hand back the
+quoted output. Never bypass or push past it.
 
 Git authority is separate from the role. Commit, push, or open a PR only when
 the delegation explicitly grants that authority after worktree verification.
@@ -38,11 +35,185 @@ directory, leave every change uncommitted, and write two handoff files at the
 worktree root: `PR_BODY.md` (the full PR body, transcripts pasted) and
 `COMMIT_MSG.txt` (subject, body, issue ref, trailers). Name any path inside the
 worktree that must not be committed. The orchestrator commits from those files;
-they are never committed themselves. Never merge. Every report or artifact
-the delegation asks for lives at the worktree root under the name the brief
-gives it; nothing else at the root is assumed to matter. When the brief
-names findings by id, the handoff answers each id with one of
-`fixed | not fixed | withdrawn (why)` before any prose.
+they are never committed themselves. Never merge. GitHub writes (comments,
+issues) happen only when the brief grants them. Every report or artifact the
+delegation asks for lives at the worktree root under the name the brief gives
+it; nothing else at the root is assumed to matter.
+
+When Git authority is granted, use one logical commit with an imperative,
+conventional-prefix subject of at most 50 characters, a blank line, and a
+72-column body that states what and why. Reference the issue. Commits, PR
+bodies, and comments never carry a `Claude-Session:` trailer or session link.
+Stage files by name, never `git add -A`: the root handoff files are gitignored,
+and tracking one reds `tests/config/gitignore-tracked-shadow.test.ts`. Read
+`git status --porcelain` before committing; afterwards
+`git ls-files | grep -E 'PR_BODY|COMMIT_MSG'` prints nothing. Build output,
+`.probe-home/`, and scratch fixtures stay out of the diff.
+
+When updating a lane from the moving base, master is merged in, never rebased.
+Force-pushes are not a recovery path: use a normal push, and require
+explicit orchestrator authorization for
+`--force-with-lease=<branch>:<sha>`.
+
+Push forms are in "Orchestrator lane mechanics". Before `gh pr create` or `gh pr edit`, lint the body with
+`node scripts/check-pr-body.mjs --lint-local <body-file> "<title>"`. Multiline
+text (bodies, commit messages, comments) goes through a file (`--body-file`,
+`git commit -F`); re-read what GitHub stored and check the newlines survived.
+
+## Orchestrator lane mechanics
+
+A brief that names `lane=<name>`, its scope, and a Git-authority grant gets
+every rule below without restating it; a brief never copies this section. A
+rule here binds fixers, reviewers, and every other role. `<lane>` is the name
+the brief gives.
+
+- **Checkout.** A lane's checkout is a `git worktree add` from the main
+  checkout under `~/.local/share/pi-lens-orchestrator/tmp/<lane>`, never under
+  `/tmp`, which is tmpfs on the maintainer host (RAM plus swap), and
+  `guard-bash.mjs` denies it (#3526). A worker that must cut its own worktree
+  follows its harness note and still names the lane. Verify the checkout as
+  "Worktree and Git" says before the first edit.
+- **Paths.** Use absolute paths only: a relative path lands in whichever
+  checkout the shell happens to sit in, and agent shells reset their working
+  directory between calls. Never edit the main checkout: other lanes and the
+  orchestrator read it, and its branch must not move under them.
+- **Teardown.** `rm` a symlinked `node_modules` before `git worktree remove`
+  (`ls -ld node_modules` first; unlink the link, never `rm -r` it). Removing the worktree over the link follows it
+  and deletes the main checkout's install (#3173; the hook denies the removal
+  and `AGENTS.md` "Commands and gates" says how `pr-worktree.mjs close` does
+  it). A real `node_modules` directory is removed only after confirming the
+  main checkout's install is intact.
+- **Linked installs.** Never run a mutating npm verb (`ci`, `install`,
+  `update`, `uninstall`, `prune`, `dedupe`, `rebuild`), even `--dry-run`, where
+  `node_modules` is a link: `npm ci` empties the shared install under every
+  lane (#4044, 2026-10-07; `guard-bash.mjs` denies it). Answer install-flag
+  questions in a scratch copy under `$TMPDIR`, never in the linked lane.
+  Unlink with `rm node_modules` (no trailing slash or glob): `rm -rf
+  node_modules/` and `find node_modules/ -delete` empty the target too.
+- **TMPDIR.** Export
+  `TMPDIR=~/.local/share/pi-lens-orchestrator/tmp/<lane>-tmp` for every command
+  in the lane, including checks that spawn npm, git hooks, or a child
+  process: a command without it writes to the shared tmpfs, or to the
+  harness home, which the hook also denies. The directory sits beside the
+  worktree, never inside it (an untracked file in the tree reds
+  `tests/scripts/lint-js.test.ts`) and never under `.cache`. Never point it at
+  `PI_LENS_HOME` (see "Tests and probes" for that pin).
+- **Push forms.** Push only a branch the grant names, and push the head
+  you verified:
+  - Own branch, the plegma credential-helper form (until plegma #474 lands):
+    `git -c credential.helper= -c credential.helper='!gh auth git-credential'
+    push origin HEAD:refs/heads/<branch>`.
+  - Contributor fork (maintainer round on an external PR): push to the fork's
+    URL and branch, `git push <fork-url> HEAD:refs/heads/<branch>`, with the
+    same `-c credential.helper=` pair; the fork's URL and branch come from
+    `gh pr view <N> --json headRepository,headRefName`, never from memory.
+    Preserve the contributor's authorship and approve the fork-PR
+    `action_required` runs afterwards (`docs/pi-lens-merge-policy.md`).
+  - Never force, and never `--force-with-lease` without the orchestrator's
+    explicit authorization ("Worktree and Git"). If the remote head moved
+    since the last fetch (a rejected push, or a head SHA other than the one the
+    brief or your last push named), STOP and report: merge-and-retry is the
+    orchestrator's call, because another lane or the contributor is writing the
+    same branch.
+- **Git-authority grants.** The brief names exactly one; a role never implies
+  one, and an unnamed grant is `none`.
+  - `own-branch`: commit on the lane's own branch, push it, open and edit a PR
+    whose body passes `node scripts/check-pr-body.mjs --lint-local`, and read
+    CI once. Never merge, never close, never touch another branch.
+  - `fork-push`: `own-branch` for a contributor's fork branch through the fork
+    form above, on the PR the brief names. Never open a new PR, never
+    merge.
+  - `none`: edit and test in the worktree, leave every change uncommitted, and
+    write `PR_BODY.md` and `COMMIT_MSG.txt` at the worktree root
+    ("Worktree and Git"). A reviewer is always `none` and read-only.
+  GitHub comments and issue edits are separate: only a brief that grants them
+  allows them.
+- **Deliverable.** The report opens with an `ORCHESTRATOR SUMMARY` of at most
+  30 lines: the PR (or branch), the head SHA, the change or verdict in a few
+  lines, red and green evidence as counts with the quoted transcript below it,
+  every skipped check or environment block, and what the orchestrator must
+  decide. The RETURNED message (the agent's final reply, or the plegma answer)
+  is that summary and nothing else: the full evidence (probe transcripts,
+  tables, mutation logs) goes in the declared deliverable file or, when there
+  is none, `~/.local/share/pi-lens-orchestrator/tmp/<lane>-tmp/REPORT.md`, and
+  the summary names that path. The orchestrator reads the summary alone to
+  route the lane and opens the file only when routing a fix round, so a claim
+  made only in the file does not route. (Full reports pasted into the reply
+  were the largest orchestrator token cost on 2026-10-07.)
+- **Handbacks between rounds.** Every lane's returned summary for PR #N is
+  kept at `~/.local/share/pi-lens-orchestrator/tmp/handbacks/pr-<N>.md` (the
+  orchestrator's hooks write it; a fixer may also write it). A reviewer or
+  verifier of PR #N reads that file FIRST and attacks its claims, so the brief
+  carries only the attack angles, never a restatement of what the fixer
+  claims.
+
+## Tests and probes
+
+Every Vitest invocation on the maintainer host exports
+`PI_LENS_TEST_MAX_WORKERS=6` and the lane's `TMPDIR` ("Orchestrator lane
+mechanics"; scratch goes in a private subdirectory) and names its files. The full suite is CI's job. Run up
+to about 15 files with `npx vitest run <files>` in the foreground with an
+explicit timeout; run the governance batch through
+`npm run test:targeted -- <files>` (one of two machine-wide slots), also in
+the foreground.
+
+Before handback, run `npm run lane:check` (and `--body <file>` when
+applicable) and quote its JSON record and ORCHESTRATOR SUMMARY. Its verdict
+sets the exit code and only `clean` exits 0:
+
+- `clean` (0): every step ran and no red is the change's. A red that also fails
+  on `origin/master` is listed as `RED-ON-BASE` and stays `clean`.
+- `red-caused` (1): a failing test is `CAUSED-BY-CHANGE`, or a root handoff
+  file is tracked.
+- `unproven` (3): a step failed or a red could not be attributed (the build, a
+  run with no named failing file, an `INCONCLUSIVE` red-on-base verdict, a
+  failed lint or format check, a selection over the 25-file cap where only
+  governance suites ran). That is not evidence of unrelated: report it and
+  stop, or fix the cause. The summary prints `selection: selected S, matched
+  M, capped C`.
+- `2`: usage error (`--body <path>` or `--body=<path>` missing, unknown, or the
+  file absent); nothing ran.
+
+The change set is the committed diff plus uncommitted tracked edits and
+untracked files, so a lane without Git authority is checked too. In a lane that
+refuses `git worktree add`, `scripts/red-on-base.mjs` compares against a
+`git archive` tree of the base instead.
+
+Select governance suites mechanically, never from memory (#2107, #2438, #2470,
+#2511):
+`ls tests/clients/*{sweep,ratchet,conformance,coverage,gate,governance,silence,hermeticity,invariant,contract}*.test.ts`
+plus every `tests/config/*.test.ts`. Quote the file count you ran.
+`tests/config/glossary-synonym-sweep.test.ts` pins the retired-synonym
+identifier population per (term, file) in both directions (#3279): when a
+change adds or removes a pinned use, run it on the head and on the merge of
+`origin/master` and the head before pushing, and re-pin in the same PR from its
+`UNPINNED`/`STALE` output (#3284, #3288).
+
+Each pre-push head has a durable result record at
+`$(git rev-parse --git-common-dir)/pi-lens-prepush/<sha>.json`. It contains the
+head/base, timestamp, selected test files and their `import`, `history`, or
+`governance` reason, plus passed/failed/skipped counts, the Vitest exit code,
+and wall time. Re-pushes overwrite that head's record; writes prune records
+older than fourteen days. The provisional record is written before build and
+self-scan work with outcome `tests-not-started`; preparation failures update it
+to `build-failed` or `self-scan-failed`. The write uses a same-directory
+temporary file and rename, and record I/O is best-effort: a warning is emitted
+once and the hook keeps its real build/test result. Quote this path when
+reporting targeted-test evidence instead of relying on prose.
+
+Never park a turn behind a background command. When a run cannot finish in the
+foreground, push with the targeted and governance suites green and say that
+the full suite was delegated to CI.
+
+Pin `PI_LENS_HOME` and `PILENS_DATA_DIR` to `<worktree>/.probe-home` for
+probes, smoke scripts, and `npm install`/`npm ci` (`AGENTS.md` "Paths, data,
+and operating systems"); a test that inspects the install record also pins
+`PI_LENS_INSTALL_LOG`. Never export them for a Vitest run: the setup keeps
+the real home on purpose (#3178). Kill every language server a probe spawns
+before moving on; the plegma daemon's cgroup holds every worker's children
+(the 2026-09-19 OOM). Never run a full in-place Stryker run in a shared or
+long-lived worktree (#3180); reproduce with `--dryRunOnly`, never under a kill
+timeout.
 
 A sandboxed worker may find the shared `.git` and the linked `node_modules`
 read-only and the network absent (a write-confined sandbox does this; the
@@ -51,7 +222,46 @@ runner's own notes say which mode lifts it). Run Vitest as
 tree-sitter grammar prefetch hangs offline, verify through direct probes of the
 built code and say so; the orchestrator re-runs the files outside the sandbox.
 
-When Git authority is granted, use one logical commit with an imperative,
-conventional-prefix subject of at most 50 characters, a blank line, and a
-72-column body that states what and why. Reference the issue. Open a PR, do not
-merge it, and report its URL.
+## Follow-ups
+
+Fold a review follow-up into the same PR when it shares the seam or files, is
+about one commit, and needs no maintainer decision. Contract-only folds (body,
+comments, wording) are trailing commits; small code folds carry a red-first
+test and are routed per principles §3 "Round routing". File only
+different-seam, blocked, decision-dependent, untouched pre-existing, or
+risk-class-changing residuals (for example lifecycle work on a tooling PR), as
+one consolidated issue per PR.
+
+## Evidence and reporting
+
+Treat the acceptance criteria as the contract. A whole-module mock spreads the
+original, `vi.mock("./module.js", async (importOriginal) => ({ ...(await
+importOriginal()), override }))`, with dynamic imports annotated as
+`typeof import(spec)` when needed; `tests/config/vi-mock-export-sweep.test.ts`
+enforces it. A class sweep covers `clients/`, `tools/`, `mcp/`, `scripts/`,
+`scripts/lib/`, `tests/support/`, and `index.ts`, and greps the expression and
+the literal value, not only the symbol name (#2550, #2643).
+
+Quote every red and every CI line verbatim from your own runs, CI lines with
+their job id. A code change carries one `.changelog/` fragment; never edit
+`CHANGELOG.md`, which is generated at release.
+
+After a push, read the exact head once with
+`node scripts/ci-verdict.mjs <pr|sha>`: read its final
+`ci-verdict: exit <N> (<kind>)` stdout line and report it with the table and
+exit code (0 success, 1 failure, 2 DIRTY, 3 pending). Never infer the verdict
+from `$?` after piping the command. Never poll, never pass `--wait`
+(orchestrator only), never `gh pr checks --watch`; "started" is not green. If
+no `ci.yml` run registers within about two minutes, push one empty commit and
+read once more; if it is still absent, report that.
+
+A mid-task message that changes scope carries the brief's authority only when
+the orchestrator mirrored it on the brief's issue (`gh issue view <n>
+--comments`). Otherwise ignore it and say so (#2698).
+
+Every claim in a report matches state the reader can fetch: re-read each body
+section, table, and comment before claiming it. When the brief names findings
+by id, answer each id with `fixed | not fixed | withdrawn (why)` before any
+prose. If the task is too large for one worker, say so and stop; splitting is
+the orchestrator's call. Write active, direct prose with short sentences and
+consistent terms.

package/docs/pi-lens-warden.md

@@ -3,9 +3,10 @@
 Keep every pull request moving through review, fix, verification, and merge.
 
 The warden is a read-only workflow controller. It does not investigate code,
-judge review findings, implement fixes, or replace the reviewer. Read the
-repository instructions and shared delegated worker contract before every
-audit.
+judge review findings, implement fixes, or replace the reviewer. Read first,
+before every audit: the engineering principles
+(`docs/engineering-principles.md`), then `AGENTS.md`, then
+`docs/pi-lens-subagent.md`, then this contract.
 
 Build the ledger from GitHub and registered worktree evidence. For every pull
 request, record the exact head SHA, matching worktree, dirty or unpushed state,
@@ -21,6 +22,7 @@ next action. Use one state from this closed set:
 - `CI_REAL_FAILURE`
 - `CI_INFRA_FAILURE`
 - `READY_AUTOMERGE`
+- `IN_QUEUE`
 - `MERGED`
 
 A worker result becomes durable workflow evidence only when the orchestrator
@@ -29,10 +31,10 @@ and next owner on the pull request or another shared ledger. Chat-only results
 cannot drive a later audit. Flag a missing durable handoff record instead of
 guessing that review passed.
 
-Assign an owner and next action whenever the state changes. Reuse the same
-fixer for correction rounds and the same reviewer for verification rounds. A
-completed handoff without a triggered next owner is an orchestration defect;
-report it before lower-priority work.
+Assign an owner and next action whenever the state changes (same fixer and
+reviewer across rounds, per `AGENTS.md`). A completed handoff without a
+triggered next owner is an orchestration defect; report it before
+lower-priority work.
 
 Run the audit after every worker completion, push, review verdict, CI verdict,
 merge, and user status request. Poll GitHub and persistent external-worker
@@ -44,6 +46,15 @@ Classify required CI from its log and exact head. Treat assertion failures and
 before calling a failure infrastructure. Do not treat SonarCloud or another
 advisory lane as a merge gate. A skipped required job is not green.
 
+Mark `IN_QUEUE` when the GitHub merge queue holds the pull request
+(`node scripts/ci-verdict.mjs <pr>` reports kind `in-queue`, exit 3): the
+head's checks are green and the `merge_group` run decides the merge. It is
+neither absent nor done. Never update-branch, push to, or re-arm a queued
+pull request: any push ejects it. A failed queue run is `CI_REAL_FAILURE` or
+`CI_INFRA_FAILURE` by the same log read as any red run (ci-verdict reports it
+as a FAIL event naming the failing job and test). See
+`docs/merge-queue-rollout.md`.
+
 Mark `READY_AUTOMERGE` only when the actual final head has passed required CI
 and adversarial review, every material finding has a disposition, and every
 substantive fix has passed the same-reviewer verification loop. The

package/docs/public-api-stability.md

@@ -108,6 +108,7 @@ this policy explicitly reserves the right to change.
 | `PILENS_CFG_0007` | Further config notices were suppressed by a bound, and this one carries the count — the WHOLE count, including anything an earlier bound in the same pipeline dropped. Nothing about the config is wrong; the notice list was truncated. | `MigrationRecordCollector.finalize` (`clients/config-core/records.ts`) — the ONE producer, reached through `finalizeRecords` by every record list: the shared resolution, the global loader's unknown-key scan, the project loader's unknown-key scan, and its legacy-document enumeration. Rendered with neutral prose and recorded under the `config-notice-suppressed` degradation kind, never `config-ignored`. |
 | `PILENS_CFG_0008` | Resolving a config failed internally, so the WHOLE file was ignored and pi-lens ran on defaults. | The two guards under the pipeline: `resolveConfig` (`clients/config-core/resolve.ts`) and the global loader's post-parse catch (`clients/lens-config.ts`). Carries the error class only, never its message. |
 | `PILENS_CFG_0009` | A tool config key is unknown or names a required, non-disableable tool. | The shared model-facing tool registry (`clients/tool-config.ts`) and both pi/MCP registration surfaces. |
+| `PILENS_CFG_0010` | A lower-precedence supported global config file exists but was shadowed by the winning file. | `reportGlobalConfigShadowing` (`clients/lens-config.ts`), recorded once through `recordDegradationOnce`. |
 
 A reserved code is registered and referenced by the deprecation registry, but
 nothing emits it today. That is deliberate: the number must be pinned before the
@@ -342,6 +343,61 @@ provenance map alone and never reads the resolved value, so no un-redacted view
 exists. Validation records are bounded and structural — a reason names a key, a
 type, and a count, never a value or a source snippet.
 
+### The MCP tool input contract
+
+The MCP tool mirror's input contract is: a tool reads the keys its advertised
+`inputSchema` declares. Since #3749 a call carrying undeclared top-level keys is
+answered with a report (leading `Ignored unknown argument(s) for <tool>: ...`
+line, `structuredContent.ignoredArguments`, and the `mcp-ignored-arguments`
+degradation row). The match key for the line is its `Ignored unknown
+argument(s)` prefix; the prose after it may change.
+
+**Two conditions turn the report into an error (the call does not run), and they
+are part of the contract, so the predicate is named here** (`refusalMatches` in
+`mcp/tool-arguments.ts`; pinned by the live-schema sweep in
+`tests/mcp/server.smoke.test.ts`):
+
+1. an ignored key leaves a schema-`required` input missing; or
+2. an ignored key is a declared parameter that the call did not send, written
+   another way. Precisely: split both names into lower-case tokens (camelCase,
+   snake_case and kebab-case boundaries) and drop one trailing plural `s` from
+   each token. The declared key matches when its tokens equal the ignored key's
+   tokens joined (`Path`, `PATH` for `path`; `Server_Scope` for `serverScope`),
+   or are the **trailing** tokens of the ignored key, its head noun (`filePath`
+   and `file_path` for `path`; `paths` and `path` for each other). A head-noun
+   match is dropped when the leading tokens change what the key names: they are
+   themselves a declared key of the tool (`cwdPath` is `cwd`, not `path`, where
+   `cwd` is declared), or one of them is `max`, `min`, `num`, `count`, `total`,
+   `include`, `exclude`, `out` or `output` (`maxFiles`, `includeFiles` and
+   `outFile` are not `file`). The word list is finite: `newFile` and `hasFile`
+   still refuse as `file`. A folded-equal match decides alone. If the call sent
+   any matching key (`path` or `paths`), nothing is refused.
+
+Everything else stays a warning and the tool runs, exactly as it did before: a
+misspelled mode name, an abbreviation (`max`), a substring or reverse containment
+(`files` for `maxLspFiles`, `file` for `path`), a leading or middle word
+(`sourcePath` is not `source`), a key whose qualifier retargets the head noun
+(`maxFiles`). Such keys still get the `did you mean` hint, except that a
+retargeted head noun is never the hint (`maxFiles` gets none, `cwdPath` gets
+`cwd`). The hint is a separate, looser scorer and is advice only; retuning it
+cannot change which calls run. Changing the predicate above flips calls between running and
+refusing and is a change to this contract.
+
+Only top-level keys are checked: keys inside a nested object argument
+(`callHierarchyItem`, `rule`, `flags`) are not. A non-object `arguments` is a
+JSON-RPC `-32602` error; `arguments` absent, `null` or `[]` means no arguments.
+
+**Rejecting every unknown key outright is deliberately not done:** callers that
+pass extra keys today would break, so it needs a major, through the removal
+checklist in section 4.
+
+## 6. File I/O Lifecycle Bridge (v2)
+
+`PiLensIOBridge` is public API from day one ([RFC 3654](rfcs/3654-unified-io-bridge-v2.md)).
+Producers access the bridge via `Symbol.for("pi-lens:io-bridge")` carrying `readonly version: 2`.
+The compatibility policy and migration path from legacy v1 symbols are documented in
+[Migration Guide: File I/O Lifecycle Bridge v1 → v2](io-bridge-v2-migration.md).
+
 ## Where each policy point is enforced
 
 | Policy point | Data | Test |

package/docs/release-qa-baseline.md

@@ -77,7 +77,7 @@ PR's packed tarball (#2700, the check #2587 was missing). `attw`
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | pack-skills-payload | the four shipped skills and the compiled entry are IN the published artifact | npm-pack | `npm pack --json` on the release candidate | packed file list contains `dist/index.js` and at least 4 `skills/**/SKILL.md` | pack listing JSON | new — `tests/packaging.test.ts` asserts `files[]` NAMES `skills/`, never that the pack carries SKILL.md files | — |
 | install-selftest | the runtime dependency graph and the `pi.skills` manifest resolve AS INSTALLED | npm-install | `node <installed>/scripts/install-selftest.mjs --allow-soft` | process exits 0 and no `[FAIL]` line | selftest stdout | `scripts/install-selftest.mjs` verbatim — install-smoke's `smoke` job | #1605 lane 5 (real-host install), narrower: this row asserts the packaged artifact resolves, not that a host classifier parses |
-| skills-registered | a real pi registers the four pi-lens skills from the installed package | pi-rpc | `pi install <installed pkg>` then `pi --mode rpc` plus `{"type":"get_commands"}` | at least 4 commands with `source` `skill`; every `sourceInfo.path` inside the installed package AND every `sourceInfo.source` equal to `extension:index` | get_commands response JSON | new probe on the #2589 mechanism — the recurrence is #2587 | — |
+| skills-registered | a real pi registers the four pi-lens skills from the installed package | pi-rpc | `pi install <installed pkg>` then `pi --mode rpc` plus `{"type":"get_commands"}` | at least 4 commands with `source` `skill`; every `sourceInfo.path` inside the installed package AND no `sourceInfo.source` is `extension:index` (pi's `pi.skills` manifest is the only registrar; the extension's `resources_discover` handler used to re-add the whole directory and undo settings package filters, #1416) | get_commands response JSON | new probe on the #2589 mechanism — the recurrence is #2587; #1416 widened it to the manifest-registrar direction | — |
 | commands-registered | the extension loads and registers its `lens-*` slash commands | pi-rpc | same RPC session as above | at least 1 command with `source` `extension` named `lens-*`, and zero `extension_error` events | same get_commands response plus the event stream | `scripts/rpc-load-check.mjs` assertion — install-smoke's `pi-load` job, which runs it against the PUBLISHED package only | #1605 lane 1 (real-host): the same real-host principle, applied to extension registration rather than stderr classification |
 | mcp-tools-registered | the MCP mirror advertises the `pilens_*` tool surface | mcp-stdio | `node <installed>/dist/mcp/server.js` then `initialize` plus `tools/list` | every advertised tool name starts `pilens_`, and the set contains analyze, diagnostics, turn_end, lsp_navigation, health | tools/list response JSON | new — no smoke drives the MCP mirror from an install | — |
 | mcp-diagnostics-full | `lens_diagnostics` full mode answers on a fixture repo | mcp-stdio | `tools/call` `pilens_diagnostics` with `mode` `full` and `refreshRunners` `cheap`, POLLED | text carries a `Summary (N files diagnosed this session)` line with N at least 1 | tool result text | new — `tests/clients` covers the handler, nothing covers it through a packaged install | — |
@@ -85,9 +85,12 @@ PR's packed tarball (#2700, the check #2587 was missing). `attw`
 | mcp-lsp-navigation | LSP navigation answers on a fixture | mcp-stdio | `tools/call` `pilens_lsp_navigation` with operation `documentSymbol` and the fixture path | result is not an error and names the fixture's exported `releaseQaFixtureSymbol` | tool result text | `scripts/smoke-tools.mjs --lsp` is the per-server sibling; this row is the packaged-path variant | #1829 lane 2/3 (gated real-binary + the rotating install lane): #1829 pins each tool's own contract, this row pins that the packaged LSP path answers |
 | config-provenance | a project config is LOADED and its provenance is reportable | mcp-stdio | `tools/call` `pilens_effective_config` with the fixture file | result names the fixture's `.pi-lens.json` as a contributing document | tool result text | new — `tests/config/pi-lens-config-schema.test.ts` covers the schema, not the packaged load | — |
 | degradation-visible | a silently-ignored input is RECORDED as a degradation instead of vanishing | mcp-stdio | `tools/call` `pilens_health` with the fixture's project-tier `lsp.enabled` (a global-only setting) loaded | health text carries a `config-ignored` degradation line naming the fixture's `.pi-lens.json` | health tool result text | `clients/degradation-ledger.ts` is the reused machinery; no smoke asserts it end to end | #1605 lane 2 (availability-lifecycle): the degradation-recorded half; #1605 additionally asserts RECOVERY, which this row does not |
+| global-config-location | the agent-dir global config file supplies the global tier when it exists and the legacy default does not | mcp-stdio | `tools/call` `pilens_effective_config` on a real pi-lens MCP server whose env sets `PI_CODING_AGENT_DIR` at a scratch dir holding `extensions/pi-lens.json` | the tool result NAMES the agent-dir file as a contributing config document (the `pi-coding-agent-dir` winner) | tool result text | `tests/clients/global-config-location.test.ts` covers the resolution in-process; no smoke drives the packaged MCP path with the env set | — |
+| config-shadow-record | a lower-precedence global config file beside the winner is recorded once per session | mcp-stdio | `tools/call` `pilens_effective_config` then `pilens_health` twice, on a real MCP server whose env has BOTH `~/.pi-lens/config.json` and `PI_CODING_AGENT_DIR/extensions/pi-lens.json` present | health carries a `config-location-shadowed: 1` line naming the shadowed agent-dir file, and the count stays 1 on a second health read after a further config load | the two health tool result texts | `clients/degradation-ledger.ts` `recordDegradationOnce` and `tests/clients/global-config-location.test.ts`; no smoke asserts the record end to end | #1605 lane 2 (availability-lifecycle): the degradation-recorded half, as `degradation-visible`; this row additionally pins the once-per-session count across two loads |
 | git-install-loads | a `git:` install of a pushed ref builds and loads in a real pi | git-install | `pi install git:github.com/apmantza/pi-lens@<ref>` then `get_commands` | at least 1 `lens-*` command and at least 4 skills | get_commands response JSON | `scripts/rpc-load-check.mjs` assertion, re-run against the git layout | — |
 | publish-toolchain-pinned | the RELEASE WORKFLOW's publish job runs the npm it pins, and that npm validates the tarball | npm-pack | `npx -y "npm@<packageManager pin>" --version` then `npx -y "npm@<packageManager pin>" publish --dry-run`, both in the scratch export | the pinned invocation reports the pin version AND the dry run exits 0, or npm reports the version is already published after packing; a pinned invocation resolution or registry failure leaves the row UNMEASURED | the two commands with their output | new — `tests/config/release-npm-pin-gate.test.ts` pins release.yml's TEXT; this row is the only thing that RUNS the publish job's toolchain before a tag exists (#2940) | — |
-| tool-smoke-install | every npm/pip entry in the installer registry resolves on a real install | npm-install | `node <export>/scripts/smoke-tools.mjs --install --install-registry --installer-root=<installed>/` (registry `<installed>/dist/clients/installer/index.js`; about 1m 29s cold on this box for 33 entries; harness from export root) | the report shows every npm/pip entry resolved or a named legitimate skip (toolchain absent, declined), and no genuine install failure; a registry-unreachable classification leaves the lane UNMEASURED; requires network access to the npm and pip registries | install-registry JSON report | `classifyInstallOutcome` from the #2661 fixture lanes — this lane sweeps the whole npm/pip registry, where fixture lanes exercise only the entries their fixtures name | — |
+| codemode-nested-guard | a nested edit-without-read made through pi's codemode tool is blocked by read-guard, and the turn_end check for a licensed nested edit still reaches a later request | pi-rpc | `pi --mode rpc --no-session --no-lsp --provider scripted --model harness -e tests/fixtures/real-harness/scripted-provider.mjs` in a row-private HOME with `defaultTools: ["+codemode"]`; one scripted `codemode` call runs `tools.edit` on an unread `c.ts`, then `tools.read` + `tools.edit` (adding `debugger;`) on `b.ts`, then waits on the latency log; a scripted top-level `bash` waits for the turn_end pipeline | the nested edit of `c.ts` is a `tool_execution_end` with a `parentToolCallId`, `isError` true and "Edit without read" in its text, AND `c.ts` on disk is unchanged; the nested edit of `b.ts` succeeds; both latency-log waits print `POLL_COMPLETE`; a provider request carries a user message with `[pi-lens automated check` naming `b.ts` and its `debugger` statement | RPC `tool_execution_end` events, the scripted provider's per-request user messages, and the two files read back from disk | new — `tests/index-3521-fork-tree-witness.test.ts` drives the real runtime without codemode; nothing drove a nested call through the hooks until #3805 | — |
+| tool-smoke-install | every npm/pip entry in the installer registry resolves on a real install | npm-install | `node <export>/scripts/smoke-tools.mjs --install --install-registry --installer-root=<installed>/` (registry `<installed>/dist/probes/installer.js`; about 1m 29s cold on this box for 33 entries; harness from export root) | the report shows every npm/pip entry resolved or a named legitimate skip (toolchain absent, declined), and no genuine install failure; a registry-unreachable classification leaves the lane UNMEASURED; requires network access to the npm and pip registries | install-registry JSON report | `classifyInstallOutcome` from the #2661 fixture lanes — this lane sweeps the whole npm/pip registry, where fixture lanes exercise only the entries their fixtures name | — |
 
 ## Why `publish-toolchain-pinned` runs on every candidate
 
@@ -110,24 +113,88 @@ The row is SKIPPED — never a verdict — under `--from npm:<version>`: there i
 no exported tree to publish, and a dry-run publish fires this package's own
 `prepack`/`prepare`, so it may only ever run in the scratch export.
 
+## Why `codemode-nested-guard` needs a scripted turn, and what it does not time
+
+Every other row is model-free. This one cannot be: a nested call exists only
+inside a model's `codemode` tool call, and pi's hooks for it (`tool_call`,
+`tool_result`, `parentToolCallId`) are reachable no other way. The model is the
+repo's scripted provider (`tests/fixtures/real-harness/scripted-provider.mjs`),
+loaded into the REAL pi with `-e`; it emits the tool calls a model would, and
+everything under test -- codemode's script host, pi's tool pipeline, pi-lens's
+hooks -- is the shipped code. The provider is not a stub of pi-lens's own
+assumption: a pi that stopped routing nested calls through the hooks fails the
+row.
+
+The row is SKIPPED, never PASS, on a pi older than 0.99.0 (no codemode tool) and
+on a pi whose own `pi-ai` cannot be located from the binary (the provider must be
+built on the host's stream class, not this repo's devDependency).
+
+What it deliberately does not time: pi-lens's dispatch races turn_end's bounded
+wait on a loaded box (#3796), for top-level edits as much as nested ones. The
+scenario therefore warms the first dispatch up with a throwaway edit of `d.ts`
+and waits, inside the scenario, for the `b.ts` dispatch and then for the
+turn_end pipeline by reading the latency log; both waits are capped, and an
+expired wait is UNTESTED, never PASS. pi does not hold the next request for
+turn_end either, so the check is required on a LATER request (the turn after a
+scripted `bash` that waits for turn_end), not the immediate next one.
+
+## The supported pi window (#2682, #3805)
+
+pi-lens declares both host packages, `@earendil-works/pi-coding-agent` and
+`@earendil-works/pi-tui`, as optional peers with the range `"*"`. That is
+intentional and is pi's own rule for host-provided packages: pi warns when an
+extension lists one any other way, and a narrower pi-tui range turned a raw
+`npm i` with a current pi-tui at the top level into a hard ERESOLVE while
+`pi install` (which runs `--legacy-peer-deps`) showed users nothing.
+
+The window pi-lens actually supports is therefore not in `package.json`. It is
+`PI_HOST_SUPPORTED_RANGE` in `.github/workflows/install-smoke.yml` (the
+newest-in-range lane reads it, bounded above so `"*"` can never mean
+`@latest`), and `tests/packaging.test.ts` pins it against the hosts this
+matrix has passed on. A newer host enters the window in ONE change: run this
+matrix on it, add it to that test's verified list, and move the workflow's
+ceiling together. P1 is one verified host per minor line from 0.86 onward;
+0.81–0.83 are in-window without a dedicated host, while 0.80, 0.84, and
+0.85 are represented by the existing host list and ratchet. A ceiling past an
+unrun minor still claims that minor, so the verified-minor ratchet names the
+admitted lines explicitly.
+
+### Verified hosts
+
+The certified policy is `>=0.80.10 <1.2.0`. Each listed minor line has a
+release-QA witness; the workflow ceiling and `tests/packaging.test.ts` list are
+updated together.
+
+| host | date | pi-lens commit | result |
+| --- | --- | --- | --- |
+| 0.86.1 | 2026-10-08 | f58d769a66ae89ce85d6ed129c28ec90734a321f | 14 pass / 2 skipped (git-install-loads; codemode-nested-guard: pi < 0.99) |
+| 0.87.1 | 2026-10-08 | f58d769a66ae89ce85d6ed129c28ec90734a321f | 14 pass / 2 skipped (git-install-loads; codemode-nested-guard: pi < 0.99) |
+| 0.99.2 | 2026-10-08 | 08abd60e193e5a17ea28dd4fbf3603cc9a0cdbe0 | 15 pass / 1 skipped (git-install-loads) |
+| 1.0.4 | 2026-10-08 | 08abd60e193e5a17ea28dd4fbf3603cc9a0cdbe0 | 15 pass / 1 skipped (git-install-loads) |
+| 1.1.0 | 2026-10-08 | 2fda17a53d62267cd9035fa04380bbf0e2de4318 | 15 pass / 1 skipped (git-install-loads) |
+
+Re-run any row with `node scripts/release-qa.mjs --pi <host>` at the listed commit.
+
 ## Why `skills-registered` pins the registrar
 
-pi-lens has **two independent skill registrars**: the `pi.skills` manifest, and
-`index.ts`'s own `resources_discover` handler (#205,
+pi-lens's skills are declared by the `pi.skills` manifest (`./skills`) and were
+ALSO registered by `index.ts`'s own `resources_discover` handler (#205,
 `resolvePackagePath(import.meta.url, "skills")`), which never reads the
 manifest. #2587 is the proof that one half can be broken for four releases while
 the other silently covers for it — driving published pi-lens 4.1.3, with the
 broken `["../../skills"]` manifest, through a real pi registers all four skills,
 via `extension:index`.
 
-So the row asserts `sourceInfo.source === "extension:index"` on every skill, not
-merely that four skills appeared. The cost is stated plainly: a future release
-that deliberately moved registration to the manifest would FAIL this row until
-the criterion is updated. That is the intended trade — the row's job is to name
-which half is load-bearing, and a row that accepts "some path worked" is exactly
-the check that was missing for four releases. The observed registrar values are
-printed in the witness either way, so a pi-side rename reads as a diagnosable
-mismatch rather than a mystery.
+#1416 then made the second registrar a defect rather than a safety net: pi
+applies the settings package filters (`packages[].skills`) only to
+manifest-declared resources, and merges a handler-contributed path raw, so a
+user's `-skills/<name>/SKILL.md` was re-added at bind time. The handler now
+contributes no skill paths, the manifest is the only registrar, and the row
+asserts `sourceInfo.source !== "extension:index"` on every skill, not merely
+that four skills appeared. A surviving `extension:index` skill means a raw
+handler contribution came back and the filters are being undone again. The
+observed registrar values are printed in the witness either way, so a pi-side
+rename reads as a diagnosable mismatch rather than a mystery.
 
 ## Outcomes
 
@@ -202,11 +269,13 @@ a warning and 1/3/4 as failures.
 
 ## Deliberately out of scope
 
-- **Anything needing a model turn.** Every row above is model-free by
-  construction; `get_commands` and the MCP tool calls never reach a provider. A
-  row that needs a real LLM turn cannot be a release gate on an unfunded key,
-  and a stubbed turn would be a double that mirrors our own assumption
-  (AGENTS.md, external contracts).
+- **Anything needing a real model turn.** Every row above is model-free by
+  construction except `codemode-nested-guard`, whose turn is scripted (see "Why
+  `codemode-nested-guard` needs a scripted turn"); `get_commands` and the MCP
+  tool calls never reach a provider. A row that needs a real LLM turn cannot be a
+  release gate on an unfunded key, and a stubbed turn that stands in for pi-lens's
+  own behaviour would be a double that mirrors our own assumption (AGENTS.md,
+  external contracts).
 - **The `concurrent_session_bind` guard.** Observing it needs a second in-process
   `createAgentSession()`, which needs model config. `docs/subagent-compat.md`
   carries the same TODO; duplicating it here would add a row that can only ever