@herbertgao/pi-extensions 2026.9.15 → 2026.9.17

package/node_modules/pi-lens/docs/adr/0003-git-guard-latch-writer.md

@@ -0,0 +1,203 @@
+# ADR 0003: git-guard latch is a separate writer
+
+## Status
+
+Accepted — 2026-09-23. Amended 2026-09-23 (#3248 remainder 2): the identity
+rule below is decided and implemented.
+
+## Context
+
+The turn-end disposition policy can change the survivor set while the
+git-guard latch is read first by the commit gate. Existing edit-time code writes
+the latch and synchronizes the `turn-end-findings` record; turn-end policy was a
+separate actor that did neither.
+
+### Writers by axis, re-verified against the tree at `5f5d847f9`
+
+| Actor | Axis / timing | Latch | Durable record | Site |
+|---|---|---|---|---|
+| `handleToolResult` | per edit, after each dispatch | `updateGitGuardStatus(result.hasBlockers, result.output)` | `syncGitGuardRecord(…, filePath)` | `clients/runtime-tool-result.ts:2546-2549` |
+| `retireInlineBlockerAndResyncGuard` | confirmed-clean verdict from `lsp_diagnostics` | `updateGitGuardStatus(false, "")` | `syncGitGuardRecord(…, filePath)` | `clients/git-guard.ts:864` |
+| `markGitGuardCacheUnknown` | cache/session mismatch, untrusted provenance, pipeline error | — | marks the record unreadable | `clients/git-guard.ts:749`, `clients/runtime-tool-result.ts:928` |
+| turn-end composer, blocker sections | per turn, after policy | — | `writeGitGuardRecord` (dedupe path `:4231`, main path `:4287`) | `clients/runtime-turn.ts` |
+| turn-end composer, clean session | per turn, when nothing survives | — | `clearCache("turn-end-findings")`, gated on the LATCH | `clients/runtime-turn.ts:829`, `:4379` |
+| turn-end disposition policy (#3246) | per turn, per finding | **nothing — the gap** | nothing | `clients/runtime-turn.ts:1068` |
+| `evaluateGitGuard` | read (commit gate) | reads the LATCH first and short-circuits | read second | `clients/git-guard.ts:1164` |
+
+PR #3254's table named five actors; re-verification adds the composer's own two
+record writers, which is what decides the rule below.
+
+### State table
+
+Axes: blockers on the file pre-policy / post-policy · record demoted by the
+freshness sweep · persisted record freshness · which reader the gate uses ·
+session identity.
+
+| # | State | Latch | Record | Gate |
+|---|---|---|---|---|
+| 1 | every blocker on the only file suppressed | clear | cleared by the composer's clean-session clear (now reachable) | allow |
+| 2 | 2 of 4 suppressed | set | blocker sections of the survivors | block |
+| 3 | file X fully suppressed, file Y still blocking | set (Y) | Y only; X's summary gone | block |
+| 4 | record demoted (`stale`) by the freshness sweep | set | untouched | block |
+| 5 | every blocker suppressed, test failures in the record | clear | `hasBlockers` stays true via `testFailures` | block |
+| 6 | suppressed, then an unrelated clean edit next turn | stays clear (the verdict rides the record the per-edit writer re-derives from) | not rewritten with the suppressed file | allow |
+| 7 | suppressed, then a NEW blocker dispatched on the same file | set again | lists the new blocker | block |
+| 8 | policy ran, suppressed nothing, changed no verdict | untouched | untouched | unchanged |
+| 9 | record for a file that no longer exists (snapshot drops it) | untouched | untouched | unchanged |
+
+## Decision
+
+The latch is an aggregate over the inline-blocker MAP, and the map carries the
+policy verdict. One identity rule, no second clause:
+
+> A record is in the gate's blocking set unless the LAST turn-end policy pass
+> found every blocker it carries suppressed.
+
+- One writer for the verdict: the turn-end composer, at the point where the
+  post-policy survivor set per file is final, calls
+  `resyncGitGuardAfterInlinePolicy`, which stamps
+  `InlineBlockerRecord.policySuppressed` on every live record (true for a fully
+  suppressed file, false for every other, so a verdict cannot outlive its pass)
+  and re-derives the latch through `updateGitGuardStatus(false, "")` — the same
+  re-derivation the retire path uses.
+- Two readers, both deriving from the map: the latch
+  (`RuntimeCoordinator.updateGitGuardStatus`) and the persisted record
+  (`syncGitGuardRecord`'s `blockerContent`). The per-edit writer therefore
+  honors the verdict too, without a second identity clause.
+- The record keeps the suppressed entry. The policy is content-bound and
+  re-derived every turn end, so retiring the entry would be silencing rather
+  than filtering (AGENTS.md shape 10), and a fresh dispatch replaces the record
+  wholesale, so a new blocker is never born pre-suppressed (#1198 ordering).
+- No third durable writer at turn end. The composer rewrites or clears the
+  record later in the SAME turn end from the same survivor set, and its clear is
+  gated on the latch this pass just recomputed.
+
+### Amendment, review round 2 (GG-3283-01): the verdict is content-bound
+
+Round 1's rule said a verdict "cannot outlive the pass that made it" because
+`applyInlineBlockerPolicyVerdicts` rewrites the whole axis each turn end. The
+review probe showed that is only true while every byte change enters pi-lens
+dispatch: `handleTurnEnd` returns before the policy loop when no file was
+touched, and a commit can arrive with no turn end after the change at all.
+
+Second state table, axes: did a turn end judge this record · how the bytes moved
+since the verdict · is the durable record present.
+
+| # | judged | bytes since verdict | record | gate | case |
+|---|---|---|---|---|---|
+| 1 | yes | unchanged | cleared | allow | `clears the latch and the record when every blocker on the file is marked` |
+| 2 | yes | unchanged | present | block | `keeps the gate closed when only two of four blockers are marked` |
+| 3 | yes, then an unrelated edit | unchanged | cleared | allow | `stays clear when the NEXT turn edits an unrelated clean file` |
+| 4 | yes, then a dispatch of the same file | changed by dispatch | rewritten | block | `re-latches when a NEW blocker is dispatched on the same file after the mark` |
+| 5 | no (no-file turn end) | unchanged | cleared | allow | `still allows the commit after an unjudged turn end that changed nothing` |
+| 6 | no (no-file turn end) | changed outside dispatch | cleared | **unknown** | `keeps the gate closed when the suppressed file's bytes moved outside dispatch` |
+| 7 | no turn end at all after the change | changed outside dispatch | cleared | **unknown** | same case, and `does not allow the commit after an external change to a marked file` (pi host) |
+| 8 | yes, after an outside change | changed outside dispatch | re-rendered | block | the freshness sweep demotes the record before the policy loop, so it is never a survivor and the verdict is cleared |
+| 9 | yes | unverifiable (no content baseline) | either | **unknown** | `keeps the gate closed for a suppressed record with no content baseline` |
+
+One clause, added to the rule above rather than replacing it: **a suppression
+verdict is a statement about BYTES, so it stands only while the file still
+matches the content baseline the record carries** (`recordedHash`, the #2982
+baseline the freshness sweep already compares against — and which the sweep
+guarantees matched at stamping time, since a self-drifted record is demoted
+before the policy loop can suppress it). The gate — the one reader that can let
+a verdict OPEN a commit — confirms that before allowing, and an unverifiable
+record (no baseline) fails closed. Rejected alternatives, from the table:
+
+- a TURN generation on the stamp: reds cell 3, which is the defect #3248 is
+  about (an unrelated edit must not re-block).
+- invalidating verdicts at every unjudged turn end (the review's suggestion):
+  leaves cells 7 and 9 open, because no turn end runs between the change and the
+  commit — and reds cell 5, re-blocking a commit after a read-only turn.
+  Mutation P1 in PR #3283 quotes both.
+- clearing the verdict in the freshness sweep only: covers cell 8, which the
+  existing rewrite already covers, and none of 6, 7 or 9.
+
+### Amendment 3 (#3282): the record's attribution contract
+
+Written before the first edit of #3282's fix. `blockerContent` is the rendered
+blocker text the gate may quote back; it is NOT the gate's source of truth about
+which files block — `blockingFiles` is (`clients/git-guard.ts:31`). The parse of
+that text exists for one consumer, `syncGitGuardRecord`'s
+`clearedLastKnownBlocker`, which drops `blockerContent` when the file that just
+dispatched clean owns everything left in it.
+
+Writers of `blockerContent`, re-verified at `f8fef5f72`:
+
+| Actor | Axis / timing | Shape it writes | Site |
+|---|---|---|---|
+| `syncGitGuardRecord` | per edit, after each dispatch | `<path>: <formatDiagnostics(…,"blocking").trim()>` per live entry, joined `"\n"` | `clients/git-guard.ts:1013` |
+| turn-end composer, main path | per turn, after the policy | `capTurnEndMessage(blockerParts.join("\n\n"))` | `clients/runtime-turn.ts:4291` |
+| turn-end composer, dedupe path | per turn, duplicate signature | the same expression | `clients/runtime-turn.ts:4234` |
+| `mergeGitGuardTestFailure` / `clearGitGuardTestFailure` | test-runner edges | pass `existing.blockerContent` through | `clients/git-guard.ts:1068`, `:1113` |
+| `resyncGitGuardAfterInlinePolicy` | per turn, before the composer | nothing durable — the latch only | `clients/git-guard.ts:919` |
+
+Neither of the two real writers emits one line per file, and `blockerParts` is
+multi-lane: only `Unresolved from this turn — <path>:` sections
+(`clients/runtime-turn.ts:1085`) name a file at all — knip (`:2147`), trivy
+CRITICAL (`:2141`), the secrets lane (`:2099`) and cascade (`:1340`) do not.
+
+> **Contract.** `blockerContent` is a sequence of per-file blocker SECTIONS. A
+> section is opened by an attribution line at column 0 — `<path>: <text>` or
+> `Unresolved from this turn — <path>[ (suppressed by disposition: N
+> finding(s))]:` — and every following line up to the next attribution line or
+> the next ZERO-LENGTH line is its rendered body, attributing nothing. The text
+> is attributable iff at least one line opens a section, no line precedes the
+> first section, and every section's file is named in `blockingFiles`. A clean
+> per-file dispatch may clear the text iff every section in it is that file's.
+>
+> Zero sections is UNATTRIBUTED, never clean (#3287 round 2, HIGH-3287-1): text
+> that is non-empty but all-blank opens nothing, and reading that as "nothing
+> left to attribute" let a clean dispatch of an unrelated file delete a record
+> whose `blockingFiles` named a different file. A record with no blocker text at
+> all never reaches the parse — `syncGitGuardRecord` gates on
+> `existing?.blockerContent` being truthy — so the genuine clean case is decided
+> before this contract applies.
+
+One-directional on purpose. A bijection between sections and `blockingFiles` was
+#3282's second cause: the composer persists `blockingFiles: affectedFiles`
+(`:4292`) — every file the turn touched plus every cascade neighbour with
+diagnostics — so any turn that edited a clean file alongside a blocking one was
+judged untrusted for the rest of the session. The extra direction guarded
+nothing either: the clear now asks about the sections themselves, so a
+`blockingFiles` entry with no section, a duplicate section and a duplicate
+`blockingFiles` entry cannot make it drop a blocker another file owns. Requiring
+`blockingFiles` to be NON-EMPTY is subsumed for the same reason once at least
+one section is required, so that clause is gone too: an empty provenance list
+cannot own a section.
+
+Fail direction (AGENTS.md shape 48): an unattributable line keeps `unknown`. The
+harm it prevents is a live CVE or leaked secret being cleared out of the gate by
+a clean dispatch of the file beside it; the harm it causes is a refused commit
+whose stated remedy ("re-run pi-lens checks or start a fresh session") does not
+clear it, which is why the reason must be reachable only for text no writer
+produces for a single file. `TurnEndFindingsCache` is unchanged by #3282 as
+well: parser-side only, no field added, no writer altered.
+
+## Consequences
+
+The latch cannot be treated as a read-only projection of the blocker map.
+Old-record parsing, the latch-first consumer, and the paired resynchronization
+remain strict consumers of the next fix. `TurnEndFindingsCache` is unchanged by
+this slice — the verdict is in-memory only, so a 4.2.1 commit hook reads records
+written after a policy pass with no new field.
+
+The gate now reads the blocker map itself, not only the latch memo: one content
+hash per suppressed record on a commit/push attempt, and nothing when no verdict
+is live. `logDecision`'s existing `git-guard` `decision` record carries the new
+`inline_policy_stale` reason category with the file and tier.
+
+Clearing the latch exposed the gate's SECOND reader, which had its own defect:
+`hasCompleteBlockingProvenance` parsed `blockerContent` line by line while both
+writers of that field render multi-line blocker text, so the gate answered
+`blocking_provenance_untrusted` once a session had recorded any blocker —
+measured on `origin/master`, independent of dispositions, filed as #3282 and
+fixed under amendment 3 above. The witness golden's turns 2 and 3 flip from that
+reason to `block: false`, as this slice committed them to do.
+
+## Links
+
+- Catalog shape: `AGENTS.md` shape 24.
+- Issue: #3248.
+- PR: #3254, “The git-guard latch” remainder and writers-by-axis table.
+- Follow-up: #3282 (record provenance parse) — amendment 3.

package/node_modules/pi-lens/docs/adr/0004-disposition-policy-seam.md

@@ -0,0 +1,38 @@
+# ADR 0004: fold dispositions onto the policy seam
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+The #1892 brief found freshness and disposition to be different gates with
+different failure directions. The #3247 and #3254 slices showed that missing
+turn-end disposition stages are existing-surface wiring gaps, not proof that a
+new findings store is required.
+
+## Decision
+
+Fold disposition application onto `applyFindingPolicy` and its existing pushed
+finding-policy seam. Do not introduce a new findings store until #1892 has a
+measured structured-store slice with a deletion sweep.
+
+## Consequences
+
+Existing producers keep their freshness, identity, and coverage contracts while
+delivery surfaces converge on the shared policy. A future store migration must
+measure the request and delete parallel identity/count logic in the same slice.
+The measured host-adapter population is two: the pi extension adapter activates
+through `activateExtension` and assembles `HostPorts` in `index.ts:725-767`, and
+the MCP server imports the host-neutral facade and serves requests in
+`mcp/server.ts:40-45,1881`. `LensEngine` (`clients/lens-engine.ts:2`) and
+`HostPorts` (`clients/host-ports.ts:10`) are the shared internal engine/ports
+seam, not additional adapters. Because the heuristic says two adapters are a
+real seam, #1358 (the ports layer) is **re-assess**, not held on a one-adapter
+claim.
+
+## Links
+
+- Catalog shapes: `AGENTS.md` shapes 10 and 26.
+- Issue/brief: #1892, 2026-09-22 brief.
+- PRs: #3247 and #3254.

package/node_modules/pi-lens/docs/adr/0005-tool-availability-enforcement-seam.md

@@ -0,0 +1,29 @@
+# ADR 0005: tool availability is one seam by enforcement
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+The availability policy and `createAvailabilityLatch` already define the shared
+taxonomy, but nine stores answer the same “can this tool run, at what path?”
+question. Migrating all stores at once is not justified by the evidence.
+
+## Decision
+
+Enforce one seam with a registry ratchet. A change touching a registered store
+migrates that store onto the shared policy in the same change and removes it
+from the registry; the registry never grows.
+
+## Consequences
+
+The population can shrink without speculative migration. The runner/formatter
+mid-session uninstall divergence remains the first red slice under #1894.
+
+## Links
+
+- Catalog shape: `AGENTS.md` shape 52.
+- Issue: #1894, rewritten 2026-09-22.
+- Catalog PR: #3253.
+

package/node_modules/pi-lens/docs/adr/0006-derived-state-benchmark-first.md

@@ -0,0 +1,31 @@
+# ADR 0006: benchmark before a derived-state cache
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+The staleness arc fixed caches whose invalidation keys could not express the
+truth. For signatures, line counts, hashes, and import graphs, a bounded
+request-local recompute can remove that invalidation surface. Tool-run caches
+are a separate class because the expensive operation is the tool run.
+
+## Decision
+
+Do not add a cross-request derived-state cache until a fresh-process benchmark
+shows that request-local recomputation is the cost. A justified cache carries
+the generation from which it was derived.
+
+## Consequences
+
+Cheap derived state has no stale cache to invalidate. Any future cache needs a
+benchmark with a control row, explicit freshness axes, and a measured reason
+that the request-local pass is insufficient.
+
+## Links
+
+- Catalog shape: `AGENTS.md` shape 51.
+- Issue: #1644 closure decision, 2026-09-22.
+- PR: #3253.
+

package/node_modules/pi-lens/docs/adr/0007-end-to-end-witness-per-seam-slice.md

@@ -0,0 +1,38 @@
+# ADR 0007: end-to-end witness per seam slice
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+Seam umbrellas #1892, #1816, #1193, #1894, and #1844 need evidence that
+survives adapter wiring and records both what the model receives and what the
+degradation ledger recorded. The #3247 round-2 adapter tests establish the
+shape through the pi and MCP turn-end surfaces.
+
+## Decision
+
+Every slice under those seam umbrellas adds one witness test through the real
+host entry: pi `index.ts` `turn_end` to the runtime-context message, or the MCP
+turn-end entry in `clients/mcp/session.ts`. The test commits the rendered
+context message and degradation-ledger rows as a golden fixture under
+`tests/fixtures/witness/<slice>/` and diffs it on every run. The witness is
+owned by the #1605 lane umbrella. Process boundaries, including LSP servers
+and tool binaries, use the real-wire fake server rather than a module mock.
+
+## Consequences
+
+Witnesses are the verifiable, repeatable artifact for each seam slice and
+expose adapter drift at the host boundary. A witness is not the sole mechanism
+at a process boundary: a module mock cannot prove argv, wire framing, process
+lifecycle, or tool output, so those boundaries require the real-wire fake
+server. In-process stores, sinks, coordinators, and dispatchers remain real.
+
+## Links
+
+- Umbrella: #1605.
+- Seam slices: #1892, #1816, #1193, #1894, #1844.
+- Shape: `tests/index-3246-turn-end-delivery.test.ts` and
+  `tests/clients/mcp/session-inline-blocker-dispositions.test.ts`.
+- Adapter evidence: #3247 round 2.

package/node_modules/pi-lens/docs/adr/0008-turn-end-lane-interface.md

@@ -0,0 +1,165 @@
+# ADR 0008: one `TurnEndLane` interface, and what stays in the composer
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+`clients/runtime-turn.ts` was 4,654 lines with fourteen delivery lanes written
+inline in `handleTurnEnd`. Each lane read its own store, applied its own
+freshness/disposition policy, and formatted its own section into
+`blockerParts`/`advisoryParts`, so the composer stated every lane's rules and no
+lane could be read, tested or changed on its own. #1892's third slice deepens
+the composer into a thin orchestrator over lane modules that share ONE
+interface, one lane per round, with no agent-facing change.
+
+The constraint that shapes the interface is #3264's fold: the turn-end scanner
+stores share ONE `gateFindingsByPathFreshness` call, so a path two stores cite
+is `stat`'d once, spends one stat budget, and writes one bounded decision
+record per delivery instead of up to six. A lane that gated itself would
+re-split that pass the moment a second lane existed.
+
+The second constraint is the delivery-surface registry
+(`clients/finding-delivery-gate.ts`): its `@delivery-surface:` seam scan reads
+exactly `clients/runtime-turn.ts` and `tools/lens-diagnostics.ts`. Code that
+renders an agent-facing section from a file that scan does not read would be an
+unregistered surface, invisible to the mechanism built to enumerate them.
+
+## Decision
+
+**The interface** (`clients/turn-end/lane.ts`) is three stages, and nothing else — no lane id, because nothing would read one:
+
+| Stage | Signature | Owns |
+|---|---|---|
+| collect | `collect(ctx) → Promise<S>` where `S` maps STORE name → `FindingFreshnessSource` | which caches to read, classification, the per-store `citedPath`/`scannedAt`/`onMissing` policy. Structured rows with source identity, never a rendered string. Calls no gate. |
+| gate | `gate(gates: TurnEndLaneGates<S>, ctx) → Kept` | the policy the shared pass cannot apply: dispositions through `filterFindingsByDisposition` (the seam in `clients/dispatch/finding-policy.ts`, ADR 0004), plus any per-store existence/lifecycle contract. `Kept` is lane-private. |
+| render | `render(kept, ctx) → TurnEndLaneParts` | the sections, the display cap, the tier each section belongs to, the per-store suppressed counts, and the location keys it delivered. Returns sections; never pushes. `TurnEndLaneParts` carries a field per tier the composer actually pushes and no others — an unread field is a side channel that drops a lane's output, so the advisory tier joins the type with the lane that renders one. |
+
+`TurnEndLaneContext` is the whole window a lane gets onto the turn: `cwd`, the
+hook's `signal`, `readScannerCache` (memoized per turn by the composer) and
+`peekActionableWarnings`.
+
+**Writers by axis** — what the composer keeps, and why it cannot be a lane's:
+
+| Axis | Owner | Why |
+|---|---|---|
+| Path-freshness pass (stat memo, stat budget, `finding_dead_path_drop` / `finding_stale_line_demote` rows) | composer | A cross-lane resource. Per-lane gating is #3264 undone: N stat passes, N budgets, N records for one filesystem fact. A lane only DECLARES sources. |
+| One read per scanner store per turn | composer (`readScannerCache` memo) | The trivy store is read by the secrets lane and by the CVE/license tiers. Two envelopes of one store in one delivery is the parallel-store shape, and the TTL boundary can fall between the reads. |
+| Disposition application | lane | Per-store anchor identity; only the lane knows which `ProjectDiagnostic` adapter anchors its rows. |
+| Tier order, `blockerParts`/`staleSecretParts`/`advisoryParts` accumulation, the `@delivery-surface:` tags | composer | The tags are what enumerates the surfaces; the scan reads the composer. |
+| Suppressed-by-disposition notice | composer, fed per lane | One bounded notice per turn (#1616), with per-lane attribution. |
+| Turn signature dedupe, `turn-end-findings` cache write, git-guard record, message cap, turn telemetry | composer | Delivery-event properties of the whole turn, not of one lane. |
+| Delivered location keys | lane produces, composer consumes | One secret is reported once across tiers (#131 Mode 3). |
+
+**Registry evidence.** A surface whose render moved into a lane keeps its
+registry `file` as `clients/runtime-turn.ts`, because that is where its tagged
+push seam and its gate call live. Its evidence literal is repinned from the
+partition it used to read (`gitleaksGate.live,`) to the gated store object the
+composer hands the lane (`gitleaksGate,`). That is a weaker pin — it no longer
+states which partition feeds which tier — and the loss is recorded rather than
+hidden: the live/stale split is a lane rule now, pinned behaviourally by
+`tests/clients/runtime-turn-finding-freshness.test.ts` and the witness goldens.
+What the pin still proves is what the registry exists for: the rows came out of
+a real gate call, not a hand-built object.
+
+**Lanes that do not fit, and are not being made to.** Test-runner findings
+(generation/retirement state, a verdict rather than diagnostics, its own
+provenance validation at read), the git-guard latch (a durable second
+writer/consumer with a commit-gate audience) and the agent nudge (session
+read/edit relevance, no findings and no freshness axis at all) stay outside
+this interface. So do the package-pinned trivy CVE/license tiers: they have no
+cited path, so their `collect` would declare no freshness source and their
+honesty mechanism is the age label, not the gate.
+
+**One lane is one delivery contract, not one store.** The secrets lane
+(`clients/turn-end/lanes/secrets.ts`) owns BOTH secret stores, because #131
+Mode 3 collapses gitleaks, trivy-secrets and ast-grep by LOCATION into one
+blocker section with combined provenance, and the demoted tier merges the same
+two stores. A "gitleaks-only" lane would leave every rendering rule in the
+composer and move only a cache read.
+
+## Amendment — 2026-09-23: the advisory tier joins `TurnEndLaneParts`
+
+`TurnEndLaneParts` gains ONE field, `advisoryParts?: readonly string[]`, with
+the govulncheck lane (`clients/turn-end/lanes/govulncheck.ts`). This is the
+amendment the Decision above anticipated ("the advisory tier joins the type
+with the lane that renders one"), not a widening of the rule.
+
+**Why it was withheld until now.** The rule is "a field per tier the composer
+PUSHES, and no others", because a field the composer does not read is a side
+channel that silently drops a lane's whole output (AGENTS.md shape 5). The
+secrets lane renders no advisory, so an `advisoryParts` shipped with the
+interface would have been exactly that: a slot a later lane could fill and lose.
+The field, the composer's push and the surface's registry id therefore move
+together, in one round, as one claim.
+
+**What the composer pushes it into.** `handleTurnEnd`'s `advisoryParts` array
+(`clients/runtime-turn.ts`), under the existing tag
+`// @delivery-surface: runtime-turn:govulncheck-advisory`, at the same position
+in the tier order the inline block occupied. The tag is what makes the tier a
+registered delivery surface rather than a string, and
+`tests/config/turn-end-lane-boundaries.test.ts` already listed `advisoryParts`
+in the tier-push rule it reds on — so a lane that pushes its own advisory was
+forbidden before the field existed, and still is.
+
+**What did NOT change.** Still three stages; still no lane id; still no fourth
+method. The `runtime-turn:govulncheck-advisory` registry entry keeps its `file`,
+its `gated` mode and its evidence literal `scannerGates.govulncheck` unchanged
+— the composer still binds that gate arm itself and hands it to the lane, so
+unlike the secrets repin nothing was weakened here.
+
+**The interface question this lane was asked and did not need to answer.** The
+brief asked how a lane declares "no freshness source" honestly, since a
+package-pinned row (trivy CVE/license) has no path to stat. The state table is:
+
+| Lane's store | has a cited path | honesty mechanism | fits the interface today |
+|---|---|---|---|
+| govulncheck | yes (first trace frame with a filename) | the shared gate, `onMissing: "demote"` | yes — this round |
+| gitleaks / trivy-secrets | yes (`finding.file`) | the shared gate, `onMissing: "drop"` | yes — #3269 |
+| trivy CVE / license | no — pinned by package, not by file | `formatCacheAgeLabel`, the registry's `labeled` mode | NO |
+| a finding whose `citedPath` returns `undefined` for SOME rows | mixed | the gate leaves the uncited row live and gates the rest | yes — already handled per row |
+
+The last row is the one that matters for "no freshness source": the gate already
+takes `citedPath` returning `undefined` as "leave live", per FINDING, so a lane
+with a partially-uncited store needs nothing new (the govulncheck witness pins
+it: `GO-2026-0103` has an empty trace and renders by module). A store where
+EVERY row is uncited is a different animal — it is not a gated lane at all, it
+is a `labeled` one, and giving it a `sources: {}` `collect` would let it pass
+the composer's gate with an empty declaration and look gated in the registry
+while nothing checked anything. That is the second exception the brief said not
+to bend the lane around, so it is not added: the labeled lanes need a `label`
+stage (an age string the composer renders into the header) before they can be
+extracted, and that is the design decision of the round that extracts one.
+
+## Consequences
+
+- The composer no longer states a govulncheck rule (2026-09-23): 4,438 →
+  4,403 lines, and the six rules the block held (the `demote`/first-frame
+  freshness declaration, the both-arm disposition anchor, the stale-line
+  withholding and marker, the module/package fallback, the fix hint and the
+  display cap) are stated once, in the lane.
+- The composer no longer states a secrets rule: 4,654 → 4,438 lines, and the
+  ten rules the block used to hold (cache key, classification budget and
+  fail-open, blocking filter, freshness declaration, two disposition anchors
+  over both arms, location dedupe, ast-grep enrichment, display cap, both
+  preambles, demoted-row identity) are stated once, in the lane.
+- Extracting a lane moves code out from under two mechanisms that read only
+  `clients/runtime-turn.ts`, so `tests/config/turn-end-lane-boundaries.test.ts`
+  walks `clients/turn-end/` and reds if a lane pushes into a tier or calls the
+  freshness gate itself. Both rules name the recurrence they prevent.
+- Registrations move with the code: the `bounded()` call-site registry entry,
+  the one-hop unbounded-await pin, and the delivery-surface marker exemption
+  all name the lane file now. A lane is a new file every directory-scanning
+  governance suite sees.
+- The next lanes are extracted one per round against this interface. A lane
+  that needs a stage this interface does not have is a finding to report, not a
+  fourth method to add quietly.
+
+## Links
+
+- Umbrella: #1892. Previous slices: #3264 (the shared freshness pass), #3269
+  (this interface and the secrets lane).
+- Witness convention: docs/adr/0007-end-to-end-witness-per-seam-slice.md.
+- Disposition seam: docs/adr/0004-disposition-policy-seam.md.
+- Registry and evidence rules: `clients/finding-delivery-gate.ts`.

package/node_modules/pi-lens/docs/adr/0009-reported-path-attribution.md

@@ -0,0 +1,114 @@
+# ADR 0009: reported-path attribution is one seam, based on the runner cwd
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+Every runner that parses a tool's textual or JSON output has to answer one
+question per reported line: *is this diagnostic about the file the dispatcher
+ran me for?* Twelve sites answered it with their own predicate — a bare `===` or
+`!==` over two `path.resolve` results, a `path.resolve` with NO base argument, a
+`path.posix.basename` compare, and two `endsWith` compares. #209 and #3277 are
+the shipped defects of the first two shapes: a spelling that differs only in
+case is the SAME file on Windows and on a case-folding POSIX mount, so the
+compare dropped every finding for the edited file and the run reported clean.
+#3278 measured the population at ~11 and #1193 recorded the fold verdict.
+
+The state space, written before the first edit. Left = the path the tool
+printed. Right = `path.resolve(ctx.filePath)`, which is
+`normalizeMapKey`-canonical and absolute by the #2016 invariant.
+
+| axis | value | consequence |
+|---|---|---|
+| host folds case | win32 always; POSIX only on a case-folding mount (APFS, `nocase` vfat/ntfs3/cifs) | a `process.platform === "win32"` test is wrong in both directions on APFS. Only the filesystem knows, so the predicate must ask it. |
+| reported spelling | absolute (the tool echoes our argv), relative to the tool's own cwd, relative to a package/base directory it chose, or basename-only | only the tool's OWN cwd is a base the caller can supply; `process.cwd()` is the extension's and is a different directory whenever `resolveRunnerCwd` returns a nested language root. |
+| separators after `path.resolve` | host-native on both sides; a foreign separator survives only embedded in the reported string | separator folding can only MERGE, never split. |
+| symlinked project dir | `pathsEqual` does NOT resolve symlinks on POSIX (`clients/path-utils.ts:181`, deliberate) | a project entered through a directory symlink can still mis-match; that is a property of the shared seam, unchanged by this decision (#3276's recorded output). |
+| purpose | identity test of ONE file, per reported line — not a stored key, not set membership | asks for an equality predicate, not a key derivation. |
+
+Candidate seams: `normalizeEphemeralMapKey` is rejected by its own contract
+(`clients/path-utils.ts:488-490` — "never … compared against externally-supplied
+paths where symlink / real-casing resolution actually matters"; the left side is
+literally an external process's output, and it folds case on
+`process.platform === "win32"` only). `normalizeFilePath`/`normalizeMapKey` are
+the right rule in the wrong shape: the caller would still hold the comparison
+and re-derive both keys. A NEW `reportedPathMatchesTarget(reported, { cwd,
+target })` helper fails the deletion test — removing it would put back the same
+single expression at each call site rather than concentrating anything — and it
+would hide the comparison from the #1193 sweep's call-site walk while raising
+the helper count.
+
+## Decision
+
+The predicate is `pathsEqual(path.resolve(<the cwd the tool ran in>, reported),
+absTarget)`, written INLINE at each call site. It is not a new helper: it is the
+call shape `clients/dispatch/runners/terragrunt.ts:90`,
+`elixir-check.ts:63` (#3276) and `go-vet.ts:107` (#3277) already use, so this
+decision migrates the remaining members onto an existing seam and adds nothing.
+A parse function that does not receive the runner cwd takes it as a parameter;
+no parse function resolves a reported path against `process.cwd()`.
+
+Absence is enforced by `tests/config/reported-path-attribution-sweep.test.ts`, a
+shrink-only census of runner sites that still hold their own predicate.
+`tests/config/path-key-fold-sweep.test.ts` counts folds that EXIST and therefore
+structurally cannot see a member with no fold at all — measured on #3277, where
+mutating `go-vet.ts` to a hand-rolled case fold left that sweep green.
+
+A member's fold is admitted only with its premise established: what spelling
+does this tool really emit under OUR invocation? Where the tool echoes the
+absolute path we hand it as argv, the fold is behaviour-preserving and its tests
+say so, rather than feeding a spelling the tool never emits.
+
+## Consequences
+
+The path-case rule exists once, in `clients/path-utils.ts`; no runner holds a
+`process.platform` test or a `toLowerCase` for this question. `pathsEqual` costs
+a `realpathSync.native`/`existsSync` per reported line, which is bounded by the
+tool's own output size on a parse path that already allocates per line.
+
+Two directions are now pinned per member: the tool's real spelling attaches, and
+a different file's finding does not. On a case-folding host the case-variant
+spelling attaches too, and on a case-sensitive host it must not — asserted from
+the filesystem's own answer, never from `process.platform`.
+
+The predicate still cannot see through a directory symlink on POSIX, and a
+runner that needs that must say so at its own call site rather than re-deriving
+a local rule. It also cannot SPLIT a separator: `pathsEqual` folds `\` to `/` on
+every platform (`clients/path-utils.ts:231`), so a POSIX file literally named
+`a\b.gleam` stays merged with `a/b.gleam` after a member's own hand-rolled fold
+is deleted. Deleting the local fold removes a second, divergent copy of the rule;
+it does not change that answer.
+
+Two amendments from #3285 / #3286, the two remainders:
+
+1. The CAPTURE is part of this decision, not a detail before it. A tool renders
+   its location line however it likes, and `gleam` renders through
+   `codespan_reporting`, whose locus line wraps the path in a `┌─` gutter. A
+   suffix compare tolerates that decoration and an equality predicate cannot, so
+   a member whose reported path arrives decorated moves the decoration out of the
+   captured group in the same change — and its premise is a vector generated by
+   the upstream RENDERER (`tests/fixtures/gleam-codespan/`), not a transcription
+   of it. The same rule covers colour: a tool that may emit SGR codes goes
+   through `stripAnsi` before an anchored capture.
+2. The population is runners AND tool clients (`clients/*-client.ts`). The autofix
+   half of a tool lives in its client, `ruff-client.ts` held the same bare `!==`,
+   and a detector scoped to `clients/dispatch/runners/**` structurally could not
+   see it. Widening cost exactly one non-member registration
+   (`clients/test-runner-client.ts`, two self-derived directories).
+
+## Links
+
+- Umbrella: #1193 (P3 fold), #3278 (the population).
+- Precedents: #3276 (`elixir-check`), #3277 / PR #3281 (`go-vet`).
+- Shipped defects: #209, #3277.
+- Detector: `tests/config/reported-path-attribution-sweep.test.ts`.
+- Cells: `tests/clients/dispatch/runners/reported-path-attribution.test.ts`.
+- Witness (ADR 0007): `tests/fixtures/witness/runner-outcome-eslint-golangci/golangci-lint-relative-path.txt`.
+- Remainders, both now closed: `gleam-check.ts` (#3285 — its `endsWith` was
+  load-bearing for `codespan_reporting`'s gutter) and `clients/ruff-client.ts`
+  (#3286 — outside the runner population).
+- Upstream vectors: `tests/fixtures/gleam-codespan/` (gleam v1.18.1 +
+  codespan-reporting 0.13.1), `tests/fixtures/ruff-json/` (ruff 0.16.8).
+- Cells for the client half: `tests/clients/ruff-client-reported-path.test.ts`.

package/node_modules/pi-lens/docs/adr/README.md

@@ -0,0 +1,26 @@
+# Architecture decision records
+
+Each record is `NNNN-title.md` and uses the same short shape: number/title,
+status, date, Context, Decision, Consequences, and Links. Records capture a
+settled design decision; observations without a decision remain in the defect
+catalog or issue history.
+
+The catalog is the index for defect shapes. A shape that records a decision
+links its ADR in `AGENTS.md`; ADR links point to the catalog shape, the issue
+that supplied the question, and the PR or brief that settled it. Use `refs`
+for work that remains open and `closes` only when its acceptance criteria are
+complete.
+
+## Seed catalog
+
+| ADR | Decision | Catalog shape | Status |
+|---|---|---:|---|
+| [0001](0001-stale-advisory-live-arm.md) | Stale advisory arm skips disposition policy; live arm applies it. | 10 | Accepted |
+| [0002](0002-workspace-hash-rendezvous.md) | `workspaceHash` is pure cross-process rendezvous derivation. | 1, 2 | Accepted |
+| [0003](0003-git-guard-latch-writer.md) | Git-guard latch is a separate writer on the durable record. | 24 | Accepted |
+| [0004](0004-disposition-policy-seam.md) | Dispositions fold onto `applyFindingPolicy`; no new store before measured #1892 work. | 10, 26 | Accepted |
+| [0005](0005-tool-availability-enforcement-seam.md) | Tool availability is one seam by enforcement, with migrate-on-touch. | 52 | Accepted |
+| [0006](0006-derived-state-benchmark-first.md) | No cross-request derived-state cache without a fresh-process benchmark. | 51 | Accepted |
+| [0007](0007-end-to-end-witness-per-seam-slice.md) | Every seam slice commits an end-to-end host witness and degradation ledger artifact. | #1605 umbrella; #1892, #1816, #1193, #1894, #1844 | Accepted |
+| [0009](0009-reported-path-attribution.md) | Reported-path attribution is `pathsEqual` against the runner cwd, inline at each call site. | 2, 34, 38; #1193, #3278 | Accepted |
+| [0008](0008-turn-end-lane-interface.md) | One `TurnEndLane` interface; `handleTurnEnd` stays a thin orchestrator over lane modules. | #1892 umbrella; #3264, #3269 | Accepted |