pi-lens 4.2.1 → 4.4.0

package/dist/mcp/worker.js

@@ -1,46 +1,105 @@
 #!/usr/bin/env node
-/**
- * pi-lens MCP `fresh`-mode worker.
- *
- * The review-loop honesty guarantee: the MCP server is long-lived, so after a
- * commit + rebuild it still holds the OLD code in memory. This worker is a
- * short-lived child the server forks per `fresh` analysis — a brand-new `node`
- * process loads the *freshly built* `analyze.js` (and its dispatch graph) from
- * disk, so the measurement reflects the latest commit, not the server's stale
- * image. stdout carries exactly one JSON `McpAnalyzeResult`; diagnostics go to
- * stderr.
- */
-import { analyzeFile } from "../clients/mcp/analyze.js";
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  analyzeFile
+} from "../chunk-TLGFBM3F.js";
+import "../chunk-C2AUYXQH.js";
+import "../chunk-I3R7GKDR.js";
+import "../chunk-FC4RP4I2.js";
+import "../chunk-DFVMIKMQ.js";
+import "../chunk-TO6WL3GM.js";
+import "../chunk-7F72PXY2.js";
+import "../chunk-RPD5K5NC.js";
+import "../chunk-ZMOL6RQC.js";
+import "../chunk-I7SPGOWI.js";
+import "../chunk-AS44CFQ4.js";
+import "../chunk-7FBF7NPR.js";
+import "../chunk-HHYAELLJ.js";
+import "../chunk-V5PXFSZK.js";
+import "../chunk-YLF3PPT5.js";
+import "../chunk-JOLITGCC.js";
+import "../chunk-E2WFBRHM.js";
+import "../chunk-6VCD4VKZ.js";
+import "../chunk-F3P7VQ7H.js";
+import "../chunk-LSMJ6KBE.js";
+import "../chunk-3MED75HT.js";
+import "../chunk-3I5QFT3N.js";
+import "../chunk-TVN5N6GY.js";
+import "../chunk-ARFCXG7S.js";
+import "../chunk-OAXNDZJ7.js";
+import "../chunk-XIMYZ3JA.js";
+import "../chunk-B3I2UUT4.js";
+import "../chunk-DIULIWKU.js";
+import "../chunk-VDBPVIKD.js";
+import "../chunk-5W3R6LFT.js";
+import "../chunk-LW6XKDZQ.js";
+import "../chunk-Z54ZSOBZ.js";
+import "../chunk-TGPXLY2J.js";
+import "../chunk-QOZXJ4NA.js";
+import "../chunk-V7R425XG.js";
+import "../chunk-PAK6IDME.js";
+import "../chunk-GUOGVTCQ.js";
+import "../chunk-AJVLWNFN.js";
+import "../chunk-YGVYKNSN.js";
+import "../chunk-LNAKEO63.js";
+import "../chunk-Z3CCVDUB.js";
+import "../chunk-PWFHBTSF.js";
+import "../chunk-2BEMIWEW.js";
+import "../chunk-OQGFCZJ4.js";
+import "../chunk-RUOG5D2C.js";
+import "../chunk-U3VGR4VU.js";
+import "../chunk-NTUJEGDZ.js";
+import "../chunk-EOKRQ3SA.js";
+import "../chunk-WONERJTP.js";
+import "../chunk-22AVIGXS.js";
+import "../chunk-GVXA6CCE.js";
+import "../chunk-6QIUX4EP.js";
+import "../chunk-VHQLPIRJ.js";
+import "../chunk-VN2AXLEX.js";
+import "../chunk-BW5KFIQC.js";
+import "../chunk-QYF5S6P6.js";
+import "../chunk-5ZEJHV35.js";
+import "../chunk-DQ2NZ7C4.js";
+import "../chunk-VNMT7C64.js";
+import "../chunk-2EECBNC5.js";
+import "../chunk-N3YQJI6O.js";
+import "../chunk-O6TQT6RI.js";
+import "../chunk-5THXD6X5.js";
+import "../chunk-UK3CMEAL.js";
+import "../chunk-LJDODBBZ.js";
+import "../chunk-NMABWBZN.js";
+import "../chunk-ABBOA7UD.js";
+import "../chunk-Q5U6FMDI.js";
+import "../chunk-NXL4FFQQ.js";
+
+// dist/mcp/worker.js
 function arg(name) {
-    const prefix = `--${name}=`;
-    const found = process.argv.find((value) => value.startsWith(prefix));
-    return found ? found.slice(prefix.length) : undefined;
+  const prefix = `--${name}=`;
+  const found = process.argv.find((value) => value.startsWith(prefix));
+  return found ? found.slice(prefix.length) : void 0;
 }
 async function main() {
-    const file = arg("file");
-    const cwd = arg("cwd") ?? process.cwd();
-    if (!file) {
-        process.stderr.write("worker: --file is required\n");
-        process.exit(2);
+  const file = arg("file");
+  const cwd = arg("cwd") ?? process.cwd();
+  if (!file) {
+    process.stderr.write("worker: --file is required\n");
+    process.exit(2);
+  }
+  let flags;
+  const flagsRaw = arg("flags");
+  if (flagsRaw) {
+    try {
+      flags = JSON.parse(flagsRaw);
+    } catch {
+      process.stderr.write("worker: --flags must be valid JSON\n");
+      process.exit(2);
     }
-    let flags;
-    const flagsRaw = arg("flags");
-    if (flagsRaw) {
-        try {
-            flags = JSON.parse(flagsRaw);
-        }
-        catch {
-            process.stderr.write("worker: --flags must be valid JSON\n");
-            process.exit(2);
-        }
-    }
-    const result = await analyzeFile(file, cwd, { flags });
-    // Flush before exiting — a bare process.exit can truncate a piped write. The
-    // explicit exit is needed because spawned LSP/runner handles would otherwise
-    // keep the event loop alive.
-    process.stdout.write(JSON.stringify(result), () => process.exit(0));
+  }
+  const result = await analyzeFile(file, cwd, { flags });
+  process.stdout.write(JSON.stringify(result), () => process.exit(0));
 }
 main().catch((err) => {
-    process.stderr.write(`worker failed: ${err.message}\n`);
-    process.exit(1);
+  process.stderr.write(`worker failed: ${err.message}
+`);
+  process.exit(1);
 });

package/dist/probes/installer.js

@@ -0,0 +1,135 @@
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  GITHUB_TOOLS,
+  TOOLS,
+  _peekEnsureInFlightForTesting,
+  acquireManagedInstallGate,
+  checkAllTools,
+  checkProbeCache,
+  ensureTool,
+  findManagedToolBinary,
+  flushProbeCache,
+  getAllToolStatuses,
+  getInstallAttempt,
+  getInstallFailureReason,
+  getLastEnsureResolutionSource,
+  getManagedToolsDir,
+  getRefreshableManagedNpmTools,
+  getRefreshableManagedTools,
+  getToolEnvironment,
+  getToolInstallStrategy,
+  getToolPath,
+  getToolVerificationTimeout,
+  installTool,
+  invalidateManagedToolResolution,
+  isCommandAvailable,
+  isKnownToolId,
+  isLspTransportRequiredError,
+  isManagedToolPresent,
+  isSpawnableCommand,
+  isToolInstalled,
+  npmToolNeedsPostinstall,
+  packageEntryVerification,
+  parsePinnedVersion,
+  pickReleaseAsset,
+  pipCommandCandidates,
+  pipScriptsDir,
+  refreshManagedTool,
+  resetPathWalkMemo,
+  resetProbeCacheStateForTesting,
+  resetResolvedPathCache,
+  resolveArchiveKind,
+  resolveArchiveUrl,
+  resolveDerivedHashiCorpReleaseAsset,
+  resolveGitHubArchiveBinaryCandidates,
+  resolveGitHubAsset,
+  resolveGitHubAssetLauncher,
+  resolveGitHubInstalledBinaryName,
+  resolveManagedNpmBinPath,
+  resolvePlatformPackageBinary,
+  swapExtractedDir,
+  updateProbeCache,
+  userBaseProbeResult,
+  verifyNpmPackageEntry,
+  verifyToolBinary,
+  wasLastResolveTransient
+} from "../chunk-OQGFCZJ4.js";
+import "../chunk-RUOG5D2C.js";
+import "../chunk-U3VGR4VU.js";
+import "../chunk-NTUJEGDZ.js";
+import "../chunk-EOKRQ3SA.js";
+import "../chunk-WONERJTP.js";
+import "../chunk-22AVIGXS.js";
+import "../chunk-GVXA6CCE.js";
+import "../chunk-6QIUX4EP.js";
+import "../chunk-VHQLPIRJ.js";
+import "../chunk-VN2AXLEX.js";
+import "../chunk-BW5KFIQC.js";
+import "../chunk-QYF5S6P6.js";
+import "../chunk-5ZEJHV35.js";
+import "../chunk-DQ2NZ7C4.js";
+import "../chunk-VNMT7C64.js";
+import "../chunk-2EECBNC5.js";
+import "../chunk-N3YQJI6O.js";
+import "../chunk-O6TQT6RI.js";
+import "../chunk-5THXD6X5.js";
+import "../chunk-UK3CMEAL.js";
+import "../chunk-LJDODBBZ.js";
+import "../chunk-ABBOA7UD.js";
+import "../chunk-Q5U6FMDI.js";
+import "../chunk-NXL4FFQQ.js";
+export {
+  GITHUB_TOOLS,
+  TOOLS,
+  _peekEnsureInFlightForTesting,
+  acquireManagedInstallGate,
+  checkAllTools,
+  checkProbeCache,
+  ensureTool,
+  findManagedToolBinary,
+  flushProbeCache,
+  getAllToolStatuses,
+  getInstallAttempt,
+  getInstallFailureReason,
+  getLastEnsureResolutionSource,
+  getManagedToolsDir,
+  getRefreshableManagedNpmTools,
+  getRefreshableManagedTools,
+  getToolEnvironment,
+  getToolInstallStrategy,
+  getToolPath,
+  getToolVerificationTimeout,
+  installTool,
+  invalidateManagedToolResolution,
+  isCommandAvailable,
+  isKnownToolId,
+  isLspTransportRequiredError,
+  isManagedToolPresent,
+  isSpawnableCommand,
+  isToolInstalled,
+  npmToolNeedsPostinstall,
+  packageEntryVerification,
+  parsePinnedVersion,
+  pickReleaseAsset,
+  pipCommandCandidates,
+  pipScriptsDir,
+  refreshManagedTool,
+  resetPathWalkMemo,
+  resetProbeCacheStateForTesting,
+  resetResolvedPathCache,
+  resolveArchiveKind,
+  resolveArchiveUrl,
+  resolveDerivedHashiCorpReleaseAsset,
+  resolveGitHubArchiveBinaryCandidates,
+  resolveGitHubAsset,
+  resolveGitHubAssetLauncher,
+  resolveGitHubInstalledBinaryName,
+  resolveManagedNpmBinPath,
+  resolvePlatformPackageBinary,
+  swapExtractedDir,
+  updateProbeCache,
+  userBaseProbeResult,
+  verifyNpmPackageEntry,
+  verifyToolBinary,
+  wasLastResolveTransient
+};

package/dist/workers/project-snapshot-persist-worker.js

@@ -0,0 +1,22 @@
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  fingerprintProjectSnapshotJson
+} from "../chunk-2BEMIWEW.js";
+import {
+  serveGzipStageWorker
+} from "../chunk-UOPVJQ4N.js";
+import "../chunk-LJDODBBZ.js";
+import "../chunk-NXL4FFQQ.js";
+
+// dist/clients/project-snapshot-persist-worker.js
+function semanticSnapshotFingerprint(request, body) {
+  return fingerprintProjectSnapshotJson(body, request.generatedAt);
+}
+serveGzipStageWorker((request) => ({
+  id: request.id,
+  generation: request.generation,
+  stagePath: request.stagePath
+}), {
+  semanticFingerprint: semanticSnapshotFingerprint,
+  skipIfFingerprints: (request) => request.priorFingerprints
+});

package/dist/workers/review-graph-persist-worker.js

@@ -0,0 +1,15 @@
+import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
+import {
+  serveGzipStageWorker
+} from "../chunk-UOPVJQ4N.js";
+import "../chunk-LJDODBBZ.js";
+import "../chunk-NXL4FFQQ.js";
+
+// dist/clients/review-graph/persist-worker.js
+serveGzipStageWorker((request) => ({
+  id: request.id,
+  cwd: request.cwd,
+  generation: request.generation,
+  stagePath: request.stagePath,
+  elements: request.elements
+}));

package/docs/adr/0001-stale-advisory-live-arm.md

@@ -0,0 +1,29 @@
+# ADR 0001: stale advisory skips disposition policy
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+The #3247 review found an asymmetry: the live turn-end arm applies disposition
+policy, but the freshness arm that demotes dependency-drift records does not.
+The stale arm drives delivery-count commits and bounded retirement, so changing
+it would change the freshness gate's accounting rather than merely filter text.
+
+## Decision
+
+Apply disposition policy on the live arm only. Keep the stale advisory visible
+with its stale marker and its existing bounded delivery accounting.
+
+## Consequences
+
+Marked findings in a stale record may remain in the bounded stale advisory.
+This is deliberate and does not recreate the unbounded replay fixed by #3247.
+
+## Links
+
+- Catalog shape: `AGENTS.md` shape 10.
+- Issue: #3246.
+- PR: #3247, section “Known asymmetry: the stale arm does not run the policy”.
+

package/docs/adr/0002-workspace-hash-rendezvous.md

@@ -0,0 +1,30 @@
+# ADR 0002: workspace hash is a rendezvous derivation
+
+## Status
+
+Accepted — 2026-09-23
+
+## Context
+
+`workspaceHash` names the warm IPC endpoint and turn-end status file. Separate
+processes derive it at different times and must reproduce identical bytes.
+Path-map normalizers can consult filesystem state, so they cannot be used for
+this cross-process rendezvous.
+
+## Decision
+
+Keep `workspaceHash` as pure string math. Neither the long-lived canonical path
+key nor the process-local ephemeral path-key seam applies.
+
+## Consequences
+
+The derivation remains independently reproducible and avoids filesystem-state
+staleness. Its deliberate lowercase fold can collide for case-distinct POSIX
+directories; changing those bytes requires a separate invalidation decision.
+
+## Links
+
+- Catalog shapes: `AGENTS.md` shapes 1 and 2.
+- Issue: #3255.
+- PR: #3256; source record: `clients/mcp/ipc.ts:44-77`.
+

package/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/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/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.
+