@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/docs/release-qa-baseline.md

@@ -0,0 +1,182 @@
+# Release-QA baseline matrix
+
+The feature × modality matrix a release candidate is witnessed against before a
+tag is cut. `scripts/release-qa.mjs` reads THIS FILE — the table below is the
+runner's row list, not a copy of one — exports the committed tree, packs and
+installs the candidate into a scratch `HOME`, drives each row's entry point
+against a real `pi`, and writes `release-qa-report.md` plus one witness file per
+row under `release-qa-evidence/`.
+
+Every child process the runner spawns — `pi`, the MCP server, `node`, `npm` —
+runs under a pinned environment: `HOME`, `USERPROFILE`, `PI_LENS_HOME`,
+`PILENS_DATA_DIR`, `PI_LENS_INSTALL_LOG` and `npm_config_cache` all inside the
+scratch root. `PI_LENS_INSTALL_LOG` is on that list by hard experience: it is
+what `scripts/warm-loader-cache.mjs` keys its install log on, `PI_LENS_HOME`
+does NOT redirect it, and the runner's first six runs — which pinned the pi-lens
+home but passed no environment to `npm` at all — put 41 records into the
+maintainer's real `~/.pi-lens/install.log` (#2619 review F1). The pack runs in a
+`git archive HEAD` export, never the live checkout, because `npm pack` fires our
+own `prepack` (rewrites `package.json` + `package-lock.json`) and `prepare`
+(rebuilds `dist/`, downloads grammars, reinstalls git hooks).
+
+Why it exists: #2587. The four shipped skills were suspected of never
+registering for four releases because **no check ever asked a real pi what it
+loaded**. The unit suite (~10.8k tests) and the nightly smokes (install, compat,
+tool, lifecycle, parser) are per-seam; nothing composed them into a release
+verdict with counted coverage, so a missing row read as absence rather than
+arithmetic.
+
+## Reading the table
+
+- **row id** — the runner's key. Every id here must have a probe in
+  `scripts/release-qa.mjs`, and every probe there must appear here; the tie is
+  enforced by `tests/scripts/release-qa.test.ts`, so neither list can drift into
+  a hand-maintained mirror of the other.
+- **entry point** — the command or RPC a **user path** actually takes. Never a
+  raw internal function: a row whose entry point is an internal call proves the
+  function works, not the product.
+- **pass criterion** — the concrete thing the witness must SHOW (a status, a
+  count, a named record). "It ran without throwing" is not a criterion.
+- **witness** — the artifact captured under `release-qa-evidence/`. A witness
+  that merely exists is not a witness; the report quotes the line that shows the
+  asserted result.
+- **reuse** — the existing script that already produces this witness, or the
+  smoke that would have caught this row's regression. `new` means nothing in the
+  repo covers it, and the cell says so rather than leaving the gap implicit.
+- **umbrella** — the open smoke-umbrella issue whose scope this row overlaps
+  (#1605 lifecycle/real-host lanes, #1829 tool-contract lanes), with one line on
+  where the two differ. `—` means neither umbrella claims this ground. This
+  column exists so a reader can tell at a glance which rows are a down-payment
+  on an already-filed umbrella and which are genuinely uncovered — and so the
+  umbrella issues are not re-litigated row by row when they are eventually
+  built.
+
+## Modalities
+
+| modality | what it stands for |
+| --- | --- |
+| `npm-pack` | the published artifact itself — what `npm publish` uploads |
+| `npm-install` | a user installing the tarball into a project's `node_modules` |
+| `pi-rpc` | pi loading the installed package, driven headless via `pi --mode rpc` |
+| `mcp-stdio` | an MCP client speaking JSON-RPC to `dist/mcp/server.js` |
+| `git-install` | `pi install git:...` against a pushed ref |
+
+## The matrix
+
+| row id | feature | modality | entry point | pass criterion | witness | reuse | umbrella |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 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 | — |
+| 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 | — |
+| mcp-turn-end | the turn-end pipeline runs over the turn's files and returns an advisory | mcp-stdio | `tools/call` `pilens_turn_end` with the fixture file | text carries `Turn-end over N file(s).` with N at least 1 | tool result text | new — `scripts/smoke-availability-lifecycle.mjs` covers lifecycle availability, not the packaged turn-end path | #1605 lane 2 (availability-lifecycle): overlaps the turn-end half; #1605 asserts latch recovery, this row asserts the packaged turn-end path answers at all |
+| 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 |
+| 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 | — |
+
+## 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,
+`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.
+
+## Outcomes
+
+Every row ends in exactly one of four states, and the four partition the
+discovered set — the report asserts the identity
+`discovered = pass + fail + untested + skipped` and says ARITHMETIC MISMATCH if
+it does not hold.
+
+The printed arithmetic is `discovered / rows / untested`, and the three words
+mean different things:
+
+- **`discovered`** — rows in the matrix above. The denominator.
+- **`rows`** — of those, the ones this run actually DROVE a probe for. A row the
+  runner has no probe for is not counted; a BLOCKED run drives none, so `rows`
+  reads 0. A SKIPPED row IS counted: its probe ran and decided the row
+  unreachable.
+- **`untested`** — rows that produced no witness.
+
+- **PASS** — the witness shows the pass criterion.
+- **FAIL(cause)** — the witness shows something else. The cause is the observed
+  value, not a category.
+- **UNTESTED(reason)** — no witness was produced. An async row that did not
+  reach a terminal state before its polling cap expires **UNTESTED, never PASS**;
+  a row with no probe implementation is UNTESTED too, so an unimplemented row is
+  arithmetic rather than silence.
+- **SKIPPED(reason)** — the row is unreachable in this run by construction (a
+  `git:` install with no ref given, for instance). Reachability is decided in
+  planning, not discovered mid-run.
+
+**BLOCKED is about the HOST, not the candidate.** The runner probes
+`pi --mode rpc` **before anything is installed**; only a pi that cannot start a
+bare session makes the run BLOCKED, because then nothing about the candidate
+was measured. A candidate that will not pack, will not install, or stops a
+working pi from booting is a **result** — DO-NOT-SHIP — not an untestable
+state. A blocked run is not a failed run and must never be reported as one.
+
+**A run that witnessed nothing is INCONCLUSIVE, never ship-with-caveats.** If pi
+booted and no row reached PASS, "no row disagreed" is not evidence; the run gets
+no ship verdict either.
+
+Ship line, from the outcomes:
+
+| condition | verdict | exit | rows |
+| --- | --- | --- | --- |
+| pi did not boot with NO candidate installed | BLOCKED — no verdict | 3 | 0 |
+| pi booted, the candidate would not install or activate | do not ship, cause named on the verdict | 1 | 0 |
+| any row FAILED | do not ship | 1 | N |
+| pi booted but zero rows PASSED | INCONCLUSIVE — no verdict | 3 | N |
+| any UNTESTED or SKIPPED, at least one PASS | ship with caveats, each named | 2 | N |
+| all PASS | ship | 0 | N |
+
+A candidate that never activated leaves **every row UNTESTED, none FAILED, and
+`rows` at 0** — no probe ran, so nothing was witnessed and nothing can honestly
+be called a failure of that row. The activation failure is the verdict's own
+cause. (An earlier revision copied it onto all eleven rows as FAILs and wrote an
+empty evidence dir — a verdict with no witness, against the first hard rule.)
+
+**A row is PASS only if its witness has something in it.** A probe that reports
+success and produces no artifact — or an EMPTY one — is recorded UNTESTED, not
+PASS, and the report's excerpt column carries the downgrade reason rather than
+the pass line. The empty case is the reachable one: every probe attaches a
+witness object on its pass path, but `install-selftest` passes on "exit 0 with
+no `[FAIL]` line", which a packaged selftest that printed nothing satisfies
+vacuously, and its witness is that same empty stdout. The check is on CONTENT,
+not on the presence of a file.
+
+A usage or self-check error (bad option, unparseable matrix, arithmetic
+mismatch) exits **4**. **Exit 2 is the EXPECTED verdict for a working-tree run**:
+`git-install-loads` is SKIPPED without `--git-ref`. A CI lane should treat 2 as
+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).
+- **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
+  be UNTESTED.
+- **Per-language tool and LSP coverage.** `scripts/smoke-tools.mjs` sweeps the
+  whole registry nightly. This matrix asserts the packaged path answers at all,
+  not that every server answers well.

package/node_modules/pi-lens/docs/subagent-compat.md

@@ -17,7 +17,7 @@ every run.
 
 | # | Contract | Depended on by | Third-party file (as of the versions below) | Verified against |
 |---|----------|-----------------|-------------------------------------------------|-------------------|
-| 1 | `PI_SUBAGENT_CHILD` is set to the literal string `"1"` in every spawned child's env; `PI_SUBAGENT_RUN_ID` / `PI_SUBAGENT_CHILD_AGENT` are set alongside it for best-effort identity. | `clients/subagent-mode.ts` (`isSubagentSession()`, `getSubagentIdentity()`) | `pi-subagents@0.34.0` — `src/runs/shared/pi-args.ts` (`SUBAGENT_CHILD_ENV`/`SUBAGENT_RUN_ID_ENV`/`SUBAGENT_CHILD_AGENT_ENV` consts + the `env[SUBAGENT_CHILD_ENV] = "1"` assignment) | `checkNicobailonChildEnv` |
+| 1 | `PI_SUBAGENT_CHILD` is set to the literal string `"1"` on every process that hosts a child session. | `clients/subagent-mode.ts` (`isSubagentSession()`, `getSubagentIdentity()`) | `pi-subagents@0.34.0` — co-located in `src/runs/shared/pi-args.ts` (`SUBAGENT_CHILD_ENV` const + the `env[SUBAGENT_CHILD_ENV] = "1"` assignment); as of `pi-subagents@0.66.0` the const moved to `src/runs/shared/child-runtime-config.ts` and the assignment to `src/runs/background/subagent-runner.ts` (#2581) — `compat-contract-locator.mjs`'s `locateContractSources` tries both layouts and concatenates whichever resolves. | `checkNicobailonChildEnv` |
 | 1b | avtc-pi-subagent sets `PI_SUBAGENT_CHILD_AGENT` + `PI_SUBAGENT_PARENT_PID` (never `PI_SUBAGENT_CHILD`) on the per-spawn subagent env; `isSubagentSession()` treats the PAIR (both non-empty) as an additional subagent signal (#507). | `clients/subagent-mode.ts` (`isSubagentSession()`, `getSubagentIdentity()`) | `avtc-pi-subagent@1.0.3` — `src/process-runner.ts` (`subagentEnv.PI_SUBAGENT_CHILD_AGENT = agent.name` + `subagentEnv.PI_SUBAGENT_PARENT_PID = String(process.pid)`) | `checkAvtcChildEnv` |
 | 2a | The pi SDK's extension loader keeps a **process-global** cache (`extensionCache = new Map()`). This is what makes an in-process `bindExtensions()` reuse pi-lens's own module-scope singletons instead of a fresh isolated instance. | `clients/session-lifecycle.ts` (the whole premise of the concurrent-session guard) | `@earendil-works/pi-coding-agent@0.80.6` — `dist/core/extensions/loader.js` | `checkSdkExtensionCache` |
 | 2b | `AgentSession.bindExtensions()` **unconditionally** emits a `session_start`-typed event (`this._extensionRunner.emit(this._sessionStartEvent)`). | Same as 2a — this is why an in-process subagent bind re-triggers pi-lens's `session_start` handler at all. | `@earendil-works/pi-coding-agent@0.80.6` — `dist/core/agent-session.js` (`bindExtensions()`, ~line 1717) | `checkSdkBindExtensionsEmitsSessionStart` |
@@ -30,7 +30,24 @@ unit-tested regex matchers against RESILIENT semantic shapes (never a line
 number — those drift on every third-party release). `scripts/compat-contracts.mjs`
 is the orchestration script: it `npm install`s the four packages (SDK,
 `pi-subagents`, `avtc-pi-subagent`, `@tintinweb/pi-subagents`) into a scratch
-directory, reads the specific files above, and runs every check.
+directory, resolves each contract's source file(s) independently (see
+"Layer A" below) and runs every check.
+
+**Contract 1's identity vars were removed upstream, not relocated (#2581).**
+The doc used to also pin `PI_SUBAGENT_RUN_ID` / `PI_SUBAGENT_CHILD_AGENT` as
+part of contract 1 — nicobailon/pi-subagents set them alongside
+`PI_SUBAGENT_CHILD=1` for best-effort child identity. `pi-subagents@0.65.0`'s
+rewrite to run subagents as native, in-process `AgentSession`s (instead of
+spawning a separate `pi` CLI process per child) deleted both vars from the
+package entirely — grep-verified absent from the whole 0.66.0 source tree;
+child identity now travels through an in-process `ChildRuntimeConfig` object
+that never touches `process.env`. This is real, permanent upstream drift, but
+it needed no pi-lens code change: `getSubagentIdentity()` was already
+documented and tested as best-effort, returning `runId`/`agentName: undefined`
+when the vars are absent (`tests/clients/subagent-mode.test.ts`) — exactly the
+degraded state this vocabulary is now always in. `checkNicobailonChildEnv`
+no longer requires them; only the `PI_SUBAGENT_CHILD='1'` flag pi-lens's
+light-mode detection actually depends on behaviorally still gates the check.
 
 ## The three env levers
 
@@ -45,10 +62,46 @@ directory, reads the specific files above, and runs every check.
 ### Layer A — pinned-contract verification (`scripts/compat-contracts.mjs`)
 
 No `pi` process, no LLM turn. Installs the real packages (table above) and
-mechanically re-checks all six contracts against the installed source. Exit
-0 = all pass; exit 1 = at least one contract check failed (real drift); exit
-2 = infrastructure failure (npm install of the third-party packages itself
-failed — usually a registry/network issue, not a contract regression).
+mechanically re-checks all seven contracts against the installed source.
+
+Each contract resolves independently to one of **three outcomes**, printed
+per-contract and rolled up into a run-level `outcome` (also exposed as a
+GITHUB_OUTPUT for the workflow's alert step, distinct from the GH step's own
+success/failure) and exit code:
+
+- **verified** (exit 0 when every contract is this) — the contract's source
+  file(s) were found and their content matches the pinned shape.
+- **drift** (exit 1) — the source file(s) were found, but the content no
+  longer matches. This is an actual upstream behavioral change worth
+  investigating (see "What to do when the nightly alerts" below).
+- **infra** (exit 2, when nothing drifted but at least one contract hit
+  this) — the contract's source file could not be located at ANY of its
+  known candidate paths (each `CONTRACTS` entry's `parts` field in
+  `scripts/lib/compat-contracts.mjs`, resolved via
+  `compat-contract-locator.mjs` and `compat-contract-resolution.mjs`), or
+  the `npm install` of the four packages itself failed. This means Layer A
+  has NOT actually re-checked that contract's content at all — it is
+  distinct from drift and must never be reported as one. #2581: before this
+  three-way split, a single relocated file (`pi-subagents@0.65.0` moving
+  `src/runs/shared/pi-args.ts`) threw inside one shared try/catch, aborted
+  the whole run, and got reported — both in the run log and the tracking
+  issue's body — as generic "failure" alongside the other six contracts that
+  were never actually re-checked that run either. A contract's own outcome
+  only becomes "infra" when ITS candidate paths are all missing; every other
+  contract is still resolved and checked independently in the same run.
+
+Candidate paths are walked NEWEST-observed-layout first, not oldest (#2680
+F1) — a stale leftover file at an old path (left behind by a partial
+publish, or an npm install that added files without pruning ones the
+package's current `files` list no longer references) must never outrank the
+package's actual current layout. When a candidate path list needs a NEW
+entry (the package relocated the file again), APPEND it to that contract's
+`parts` in the `CONTRACTS` list (`scripts/lib/compat-contracts.mjs`) —
+oldest-observed-layout first in how the list reads, rather than replacing
+the old entry — the locator resolves the newest EXISTING one regardless of
+authored order, so older installs stay covered too. `parts` and `package`
+live directly on each `CONTRACTS` entry, not a second table keyed by a
+string id (#2680 F2) — there is nowhere else to update.
 
 ### Layer B — real-pi behavioral smoke (`scripts/compat-smoke-behavioral.mjs`)
 
@@ -71,7 +124,7 @@ first session.
 Assertions:
 
 1. **Subagent light mode engages** — with `PI_SUBAGENT_CHILD=1` set,
-   `subagent_light_mode` is logged to `~/.pi-lens/latency.log` (a `type:
+   `subagent_light_mode` is logged to `$PI_LENS_HOME/latency.log` (a `type:
    "phase"` entry) and none of the seven heavyweight-scan phases
    (`knip`/`jscpd`/`madge`/`dead-code`/`govulncheck`/`gitleaks`/`trivy`) are
    logged for that run.
@@ -99,22 +152,32 @@ Assertions:
    `PI_SUBAGENT_PARENT_PID`), no `subagent_light_mode` phase is logged.
    `subagent-mode.ts`'s doc comment requires the PAIR — a lone var set by
    some unrelated tool must not trigger light mode.
-6. **`concurrent_session_bind` (#473) — NOT asserted, documented TODO.**
+6. **`concurrent_session_bind` (#473) and its `concurrent_session_bind_rollup`
+   session-end summary (#2249) — NOT asserted, documented TODO.**
    The guard is fully wired on master (PR #477): `index.ts`'s `session_start`
    handler calls `decideSessionStart()` and logs a `concurrent_session_bind`
    latency phase for a concurrent-secondary bind — so the phase exists to
-   observe. The blocker is DRIVING it keylessly: reproducing tintinweb's
-   in-process model for real (mirroring `agent-runner.ts`'s
-   `createAgentSession()` + `DefaultResourceLoader` + `bindExtensions()`
-   sequence) requires full session construction, which in turn needs
-   model/provider config — not cheaply stubbable without a real model key,
-   and #476 explicitly asks not to ship something flaky here. The unit +
-   behavioral coverage in `tests/clients/session-lifecycle.test.ts` guards
-   the classifier and the no-reset contract in-repo; what Layer B cannot yet
-   add is the end-to-end SDK-driven variant. **Revisit if the pi SDK grows a
-   model-free session constructor or stub provider** — at that point add a
-   Layer B assertion analogous to 1-3 checking the `concurrent_session_bind`
-   phase and the absence of a second LSP fleet teardown.
+   observe. `clients/session-start-observability.ts` also keeps a bounded,
+   process-singleton-backed tally of declined binds by classification
+   (`concurrent-secondary` / `secondary-root`), which `index.ts`'s
+   `session_shutdown` handler logs as one `concurrent_session_bind_rollup`
+   row (primary sessions only) and clears — same primary-only placement as
+   `session_end_bus_rollup`/`path_attribution_verified_rollup`. The blocker is
+   DRIVING either keylessly: reproducing tintinweb's in-process model for real
+   (mirroring `agent-runner.ts`'s `createAgentSession()` +
+   `DefaultResourceLoader` + `bindExtensions()` sequence) requires full
+   session construction, which in turn needs model/provider config — not
+   cheaply stubbable without a real model key, and #476 explicitly asks not
+   to ship something flaky here. The unit + behavioral coverage in
+   `tests/clients/session-lifecycle.test.ts` guards the classifier and the
+   no-reset contract, and `tests/clients/session-start-observability.test.ts`
+   plus `tests/index-integration.test.ts` guard the rollup's counting,
+   process-singleton survival, and primary-only reset/emit wiring, all
+   in-repo; what Layer B cannot yet add is the end-to-end SDK-driven variant.
+   **Revisit if the pi SDK grows a model-free session constructor or stub
+   provider** — at that point add a Layer B assertion analogous to 1-3
+   checking the `concurrent_session_bind`/`concurrent_session_bind_rollup`
+   phases and the absence of a second LSP fleet teardown.
 
 ## What to do when the nightly alerts
 
@@ -125,18 +188,35 @@ third-party contract drift detected"** — search for it by title before
 assuming a NEW investigation is needed; the workflow already
 create-or-updates it, never duplicates.
 
-1. Read the linked run log — both layers print a `[PASS]`/`[FAIL]` line per
-   check with a one-line detail on exactly what didn't match.
-2. Find the failed check's row in the pinned-contracts table above and go
-   read the current third-party source at the referenced file — a Layer A
-   failure means the semantic shape genuinely changed upstream (a renamed
-   env var, a moved `emit()` call, a reworded error message, ...).
-3. Update the corresponding matcher in `scripts/lib/compat-contracts.mjs`
+1. Read the linked run log — the alert issue body now says which of Layer
+   A's three outcomes fired (**verified** / **drift** / **infra**, #2581 —
+   never just a generic "failure"); Layer A/B each print a `[PASS]`/`[FAIL]`
+   or `[INFRA]` line per check with a one-line detail on exactly what didn't
+   match or couldn't be found.
+2. **If Layer A says infra**: the run log's `INFRA` line names every
+   candidate path tried for that contract. Read the installed package at the
+   printed version and find where the file actually lives now, then append
+   it to that contract's `parts` in the `CONTRACTS` list
+   (`scripts/lib/compat-contracts.mjs`) — don't replace the old candidate,
+   the locator resolves whichever existing one is newest regardless of
+   authored order (#2680 F1), so older installs stay covered too. This is a
+   relocation, not a confirmed content change; only move to step 3 once the
+   check actually runs against the relocated file.
+3. **If Layer A says drift**: find the failed check's row in the
+   pinned-contracts table above and read the current third-party source at
+   the referenced file — the semantic shape genuinely changed upstream (a
+   renamed env var, a moved `emit()` call, a reworded error message, ...).
+   Update the corresponding matcher in `scripts/lib/compat-contracts.mjs`
    (and its test in `tests/scripts/compat-contracts.test.ts`) to match the
-   new shape, update the pinned-contracts table's version/line reference
-   above, and fix whichever pi-lens module (`subagent-mode.ts` /
+   new shape, update the pinned-contracts table's version/reference above,
+   and fix whichever pi-lens module (`subagent-mode.ts` /
    `session-lifecycle.ts` / `instance-reaper.ts`) actually depended on the
-   old shape if the drift broke real behavior — not just the check.
+   old shape if the drift broke real behavior — not just the check. If
+   pi-lens's own dependent code already tolerates the drift gracefully (as
+   with contract 1's now-removed identity vars, #2581), relaxing the check
+   to stop requiring what upstream removed IS the fix — don't keep a check
+   that can only ever report drift forever for something pi-lens never
+   needed to work.
 4. A Layer B failure (an assertion, not an infra error) means real pi-lens
    behavior regressed under a real `pi` — treat it like any other bug: write
    a fixture-level test if the gap wasn't otherwise covered, then fix.

package/node_modules/pi-lens/docs/tree-sitter_rules_catalog.md

@@ -135,10 +135,10 @@ Rule source: `rules/tree-sitter-queries/<language>/`.
 | `open-invalid-mode` | error | reliability | open() called with invalid mode '{{MODE}}' |
 | `python-assert-production` | warning | correctness | assert statement stripped by Python -O flag — use explicit checks with exceptions in production code |
 | `python-command-injection` | error | security | Potential command injection sink — avoid shell execution with dynamic input |
-| `python-cross-language-method` | warning | correctness | '{METHOD}' is not a Python method — likely a {LANG} idiom leaking in |
+| `python-cross-language-method` | warning | correctness | '{{METHOD}}' is not a Python method — likely a cross-language idiom leaking in |
 | `python-debugger` | warning | debugging | Debugger call '{{FUNC}}' — remove before committing |
 | `python-empty-except` | warning | reliability | Except block only contains 'pass' — handle or re-raise the exception |
-| `python-hallucinated-import` | warning | correctness | Hallucinated import — '{NAME}' does not exist in '{MODULE}' |
+| `python-hallucinated-import` | warning | correctness | Hallucinated import — '{{NAME}}' does not exist in '{{MODULE}}' |
 | `python-hardcoded-secrets` | warning | security | Hardcoded {{VARNAME}} — use environment variables or a secrets manager |
 | `python-insecure-deserialization` | error | security | Potential insecure deserialization sink — avoid unsafe loaders |
 | `python-insecure-random` | warning | security | Insecure randomness source detected — use secrets or os.urandom for security-sensitive values |

package/node_modules/pi-lens/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lens",
-	"version": "4.1.3",
+	"version": "4.1.4",
 	"type": "module",
 	"description": "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo",
 	"repository": {
@@ -15,10 +15,13 @@
 	},
 	"scripts": {
 		"build": "tsc --project tsconfig.build.json",
-		"build:dist": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && npx --yes -p typescript@7.0.2 tsc --project tsconfig.dist.json --noCheck && npm run bundle:dist",
+		"build:dist": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && node scripts/build-dist-tsc.mjs tsconfig.dist.json && npm run bundle:dist",
 		"bundle:dist": "node scripts/bundle-dist.mjs",
 		"prepare": "npm run build:dist && node scripts/download-grammars.js --core --dest grammars && node scripts/setup-git-hooks.mjs && node scripts/warm-loader-cache.mjs",
-		"lint": "tsc --project tsconfig.json",
+		"prepack": "node scripts/strip-dev-deps-for-pack.mjs --strip",
+		"postpack": "node scripts/strip-dev-deps-for-pack.mjs --restore",
+		"lint": "tsc --project tsconfig.json && npm run lint:js",
+		"lint:js": "oxlint --deny-warnings --ignore-pattern \"tests/**/*.ts\" --ignore-pattern \"tests/**/*.tsx\" --ignore-pattern \"**/*.d.mts\" --ignore-pattern \"tests/fixtures/autofix-smoke/**\" --ignore-pattern \"tests/fixtures/format-smoke/**\" --ignore-pattern \"tests/fixtures/tool-smoke/**\" --ignore-pattern \"tests/fixtures/call-graph/javascript/**\" --ignore-pattern \"tests/fixtures/function-facts/javascript-parameter.js\" .",
 		"depcruise:check": "depcruise --validate --config .dependency-cruiser.cjs --ignore-known .dependency-cruiser-known-violations.json --output-type err index.ts \"clients/**/*.ts\"",
 		"fmt": "oxfmt",
 		"fmt:check": "oxfmt --check",
@@ -26,7 +29,9 @@
 		"test": "node scripts/with-test-lock.mjs -- vitest run",
 		"test:unit": "node scripts/with-test-lock.mjs -- vitest run",
 		"test:integration": "node scripts/with-test-lock.mjs -- vitest run tests/index-integration.test.ts tests/clients/lsp/integration.test.ts",
+		"test:targeted": "node scripts/with-test-lock.mjs --shared -- vitest run",
 		"test:watch": "vitest",
+		"hygiene": "node scripts/prune-agent-worktrees.mjs",
 		"check": "node scripts/check-extensions.mjs",
 		"selftest:install": "node scripts/install-selftest.mjs",
 		"check:lockfile": "node scripts/check-lockfile-sync.mjs",
@@ -72,6 +77,9 @@
 	],
 	"author": "Apostolos Mantzaris",
 	"license": "MIT",
+	"engines": {
+		"node": ">=22.19.0"
+	},
 	"files": [
 		"dist/",
 		"docs/",
@@ -85,6 +93,7 @@
 		"scripts/analyze-pi-lens-logs.mjs",
 		"scripts/install-selftest.mjs",
 		"scripts/lib/host-provided-deps.mjs",
+		"scripts/lib/skills-predicate.mjs",
 		"scripts/lib/warm-loader-cache.mjs",
 		"scripts/warm-loader-cache.mjs",
 		"scripts/rpc-load-check.mjs",
@@ -103,7 +112,7 @@
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "^0.84.1",
+		"@earendil-works/pi-tui": "^0.84.1 || ^0.85.0",
 		"typebox": "^1.0.0"
 	},
 	"peerDependenciesMeta": {
@@ -121,29 +130,12 @@
 		"jiti": "^2.7.0",
 		"web-tree-sitter": "0.25.10"
 	},
-	"devDependencies": {
-		"@biomejs/biome": "^2.4.10",
-		"@earendil-works/pi-coding-agent": "^0.84.1",
-		"@earendil-works/pi-tui": "^0.84.1",
-		"@types/node": "^26.0.0",
-		"@types/pidusage": "^2.0.5",
-		"@vitest/coverage-v8": "^4.1.5",
-		"dependency-cruiser": "^18.2.0",
-		"husky": "^9.1.7",
-		"json5": "^2.2.3",
-		"oxfmt": "0.64.0",
-		"oxlint": "1.79.0",
-		"typebox": "^1.0.0",
-		"typescript": "^7.0.2",
-		"typescript-language-server": "^6.0.0",
-		"vitest": "^4.1.1"
-	},
 	"pi": {
 		"extensions": [
 			"./dist/index.js"
 		],
 		"skills": [
-			"../../skills"
+			"./skills"
 		]
 	},
 	"knip": {
@@ -159,7 +151,7 @@
 		]
 	},
 	"allowScripts": {
-		"@ast-grep/cli@0.45.1": true,
+		"@ast-grep/cli@0.45.2": true,
 		"@google/genai@1.52.0": true,
 		"protobufjs@7.6.5": true
 	}

package/node_modules/pi-lens/rules/tree-sitter-queries/python/python-cross-language-method.yml

@@ -9,7 +9,7 @@ defect_class: hallucination
 inline_tier: warning
 language: python
 
-message: "'{METHOD}' is not a Python method — likely a {LANG} idiom leaking in"
+message: "'{{METHOD}}' is not a Python method — likely a cross-language idiom leaking in"
 
 description: |
   A method name from another language is being called on a Python object.
@@ -27,7 +27,7 @@ query: |
     function: (attribute
       object: (_) @OBJ
       attribute: (identifier) @METHOD)
-    (#match? @METHOD "^(push|forEach|indexOf|charAt|substring|hasOwnProperty|unshift|flatMap|padStart|padEnd|trimStart|trimEnd|equals|isEmpty|println|printf|getClass|hashCode|toCharArray|getBytes|compareTo|equalsIgnoreCase|startsWith|endsWith|each|collect|select|reject|detect|inject|chomp|chop|gsub|upcase|downcase|present|blank|Add|Contains|ToLower|ToUpper|Trim|Substring|WriteLine|ReadLine|TryParse|forEach|includes|assign|freeze|splice|unshift|shift|flatMap)$"))
+    (#match? @METHOD "^(push|forEach|indexOf|charAt|substring|hasOwnProperty|unshift|flatMap|padStart|padEnd|trimStart|trimEnd|equals|isEmpty|println|printf|getClass|hashCode|toCharArray|getBytes|compareTo|equalsIgnoreCase|startsWith|endsWith|each|collect|reject|detect|inject|chomp|chop|gsub|upcase|downcase|present|blank|Add|Contains|ToLower|ToUpper|Trim|Substring|WriteLine|ReadLine|TryParse|forEach|includes|assign|freeze|splice|unshift|shift|flatMap)$"))
 
 metavars:
   - OBJ
@@ -35,7 +35,7 @@ metavars:
 
 post_filter: match_captures
 post_filter_params:
-  METHOD: "^(push|forEach|indexOf|charAt|substring|hasOwnProperty|unshift|flatMap|padStart|padEnd|trimStart|trimEnd|equals|isEmpty|println|printf|getClass|hashCode|toCharArray|getBytes|compareTo|equalsIgnoreCase|startsWith|endsWith|each|collect|select|reject|detect|inject|chomp|chop|gsub|upcase|downcase|present|blank|Add|Contains|ToLower|ToUpper|Trim|Substring|WriteLine|ReadLine|TryParse|forEach|includes|assign|freeze|splice|unshift|shift|flatMap)$"
+  METHOD: "^(push|forEach|indexOf|charAt|substring|hasOwnProperty|unshift|flatMap|padStart|padEnd|trimStart|trimEnd|equals|isEmpty|println|printf|getClass|hashCode|toCharArray|getBytes|compareTo|equalsIgnoreCase|startsWith|endsWith|each|collect|reject|detect|inject|chomp|chop|gsub|upcase|downcase|present|blank|Add|Contains|ToLower|ToUpper|Trim|Substring|WriteLine|ReadLine|TryParse|forEach|includes|assign|freeze|splice|unshift|shift|flatMap)$"
 
 has_fix: false
 

package/node_modules/pi-lens/rules/tree-sitter-queries/python/python-hallucinated-import.yml

@@ -9,7 +9,7 @@ defect_class: hallucination
 inline_tier: blocking
 language: python
 
-message: "Hallucinated import — '{NAME}' does not exist in '{MODULE}'"
+message: "Hallucinated import — '{{NAME}}' does not exist in '{{MODULE}}'"
 
 description: |
   This import is from the wrong package. A name from one framework is being
@@ -32,7 +32,7 @@ metavars:
 
 post_filter: match_captures
 post_filter_params:
-  MODULE: "^(requests|flask|django|typing|collections|asyncio|json|unittest|pytest|urllib|sqlalchemy)$"
+  MODULE: "^(requests|flask|django|typing|collections|asyncio|json|unittest|pytest|urllib)$"
   NAME: "^(JSONResponse|HTMLResponse|RedirectResponse|StreamingResponse|Depends|Query|Path|Body|Header|Cookie|Form|File|UploadFile|FastAPI|APIRouter|HTTPException|BackgroundTasks|dataclass|fields|BaseModel|Field|validator|aiohttp|parse|stringify|fixture|TestCase|get|post|put|delete|Model|Session|Column|Integer|String)$"
 
 has_fix: false

package/node_modules/pi-lens/rules/tree-sitter-queries/python/python-sql-injection.yml

@@ -18,8 +18,18 @@ description: |
   
   Suppressed:
   - cursor.execute(query, params) — parameterized query (safe)
-  - session.execute(select(...)) — SQLAlchemy ORM (safe by construction)
-  - cursor.execute(f"...") — f-string with literal-only interpolation (rare false positive)
+  - session.execute(...) — receiver conventionally named for a SQLAlchemy session
+  - x.execute(select(...)) — statement builder in argument position (safe by
+    construction)
+  - db.query(...) / db.execute(stmt) where `db: Session` and `Session` is proven
+    from a same-file `sqlalchemy.orm` / `sqlalchemy.ext.asyncio` import, and
+    `stmt` is bound exactly once to a builder call
+  - cursor.execute(sql.SQL("...").format(sql.Identifier(...))) where `sql` is
+    an unshadowed same-file psycopg or psycopg2 import and every format argument
+    is an Identifier
+
+  Other raw, dynamic, or ambiguous SQL remains diagnostic so this rule fails
+  closed when it cannot prove the safe API provenance.
   
   ✅ FIX: use placeholders and parameter binding instead of string composition.