pi-lens 4.2.0 → 4.3.0

package/dist/tools/lsp-diagnostics.js

@@ -23,10 +23,12 @@ import { classifyCascadeWaitTier } from "../clients/lsp/wait-policy/index.js";
 import { attemptTsserverSyncDiagnostics } from "../clients/lsp/tsserver-sync.js";
 import { convertLspDiagnostics } from "../clients/dispatch/utils/lsp-diagnostics.js";
 import { demoteInferredProjectDiagnostics } from "../clients/lsp/inferred-project.js";
-import { isBlocking, reconcileScanDiagnostics, } from "../clients/widget-state.js";
+import { normalizeMapKey } from "../clients/path-utils.js";
+import { countRetainedSuppressedRows, isBlocking, reconcileScanDiagnostics, } from "../clients/widget-state.js";
 import { makeProgressReporter } from "./scan-progress.js";
 import { isWarmAttached, tryWarmAttachedDiagnostics, } from "../clients/warm-attach.js";
 import { extensionsForLanguage, SCAN_LANGUAGE_PRIORITY, } from "../clients/language-registry.js";
+import { exceedsLspSyncLimits } from "../clients/lsp/content-limits.js";
 const MAX_FILES = 100;
 export const MAX_BATCH_FILES = 100;
 const MAX_DIAGNOSTICS = 200;
@@ -44,6 +46,30 @@ export const LSP_SEVERITY_FILTERS = [
     ...Object.values(SEVERITY_NAMES),
     "all",
 ];
+function assertNeverBatchFileOutcome(value) {
+    throw new Error(`Unhandled batch file outcome: ${String(value)}`);
+}
+/** Render the bounded per-file outcomes shared by batch, directory, and fold surfaces. */
+export function renderBatchOutcomeLines(outcomes, formatFile = (file) => file) {
+    const lines = [];
+    for (const outcome of outcomes) {
+        switch (outcome.outcome) {
+            case "too_large":
+                lines.push(`${formatFile(outcome.file)}: ${outcome.reason ?? "file too large for LSP diagnostics"}`);
+                break;
+            case "clean":
+            case "findings":
+            case "unsupported":
+            case "unavailable":
+            case "failed":
+            case "inconclusive":
+                break;
+            default:
+                assertNeverBatchFileOutcome(outcome.outcome);
+        }
+    }
+    return lines;
+}
 function batchFileDeadlineMs() {
     const raw = Number(process.env.PI_LENS_LSP_BATCH_FILE_MS);
     return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_BATCH_FILE_DEADLINE_MS;
@@ -239,7 +265,18 @@ onConfirmedNoBlockers, getService = getLSPService) {
                 // Preserve input order (including duplicate entries); normalize each
                 // path before grouping so Windows separators and dot segments cannot
                 // change cache/group identity. Explicit lists never enter the walker.
-                const absPaths = rawPaths.map((entry) => path.normalize(path.isAbsolute(entry) ? entry : path.resolve(cwd, entry)));
+                // #3160/#3182: `path.resolve(cwd, entry)` folds dot segments (and
+                // separators) structurally — it ignores `cwd` whenever `entry` is
+                // already absolute, so the old `path.isAbsolute` ternary is
+                // redundant. `normalizeMapKey` then adopts on-disk CASING where the
+                // path exists — an agent-typed, possibly mis-cased `paths` entry
+                // must key `reconcileScanDiagnostics`'s widget-state write the same
+                // way a canonical writer (clients/pipeline.ts's ctx.filePath) or the
+                // #3160-fixed lens_diagnostic_mark reader would. `path.resolve`
+                // stays required for the relative→absolute step: `normalizeMapKey`
+                // folds dot segments itself since #3184, but never resolves against
+                // `cwd` (a cwd fold there broke every monorepo, #2490).
+                const absPaths = rawPaths.map((entry) => normalizeMapKey(path.resolve(cwd, entry)));
                 return runBatchFileDiagnostics(absPaths, severity, lspService, {
                     concurrency,
                     waitMs,
@@ -264,9 +301,12 @@ onConfirmedNoBlockers, getService = getLSPService) {
                     details: {},
                 };
             }
-            const absPath = path.isAbsolute(rawPath)
-                ? rawPath
-                : path.resolve(cwd, rawPath);
+            // #3184: the single-`path` sibling of the `paths` batch above, and
+            // keyed the same way — `runFileDiagnostics` hands this straight to
+            // `reconcileScanDiagnostics`, whose `normalizeEphemeralMapKey` key
+            // derivation folds neither dot segments nor casing. Same expression as
+            // :444 so both modes of this tool write under ONE key per file.
+            const absPath = normalizeMapKey(path.resolve(cwd, rawPath));
             let stat;
             try {
                 stat = fs.statSync(absPath);
@@ -325,6 +365,24 @@ scanRoot, waitMs, serverScope = "all") {
     let touched;
     try {
         content = fs.readFileSync(absPath, "utf-8");
+        const contentLimit = exceedsLspSyncLimits(content);
+        if (contentLimit.tooLarge) {
+            const reason = `file too large for LSP diagnostics (${contentLimit.reason})`;
+            recordDegradationOnce({
+                kind: "lsp-diagnostics-file-too-large",
+                subject: absPath,
+                reason,
+            });
+            return {
+                diagnostics: [],
+                timedOut: false,
+                confirmedByTouch: false,
+                unconfirmedServerIds: [],
+                diagnosticsUnsupportedServerIds: [],
+                content,
+                tooLargeReason: reason,
+            };
+        }
         if (isWarmAttached()) {
             // The local sweep's default service wait is bounded to the same
             // 15-second per-file envelope used by the workspace sweep. An explicit
@@ -372,6 +430,12 @@ scanRoot, waitMs, serverScope = "all") {
             maxClientWaitMs: waitMs,
             source: "lsp_diagnostics",
             clientScope: serverScope,
+            // #3405: the caller asked whether THIS file is clean right now, and the
+            // content above was just read from disk — so it is the file's saved
+            // state. Without the save a save-triggered server answers zero
+            // diagnostics for every file in the query, which this path would report
+            // as clean.
+            saved: true,
         });
         timedOut = touched?.inconclusive === true;
     }
@@ -616,6 +680,17 @@ severity) {
             // otherwise have SEEN, never one per finding (AGENTS.md "bounded
             // observability"). `total` is the in-scope population for the same
             // reason the count is, so the record and the rendered line agree.
+            //
+            // #3158 round 2 F4: `retainedSuppressed` is the widget store's
+            // SUCCESS-path number — how many suppressed rows the store is carrying
+            // INTO this scan, written by the scans before it. Until this, retention
+            // was observable only when its per-file cap truncated
+            // (`widget-suppressed-retention-capped`), so a healthy footer chip had no
+            // record behind it at all. Folded into the record this lane already emits
+            // rather than added as a second one: same cardinality (one per filtered
+            // file per scan, never one per row), no new sink, and the two numbers are
+            // read together — `suppressed` is what THIS scan dropped,
+            // `retainedSuppressed` is what the footer chip is still counting.
             logLatency({
                 type: "phase",
                 toolName: "lsp_diagnostics",
@@ -625,6 +700,7 @@ severity) {
                 metadata: {
                     suppressed,
                     total: inScopeBefore,
+                    retainedSuppressed: countRetainedSuppressedRows(file),
                 },
             });
         }
@@ -775,7 +851,10 @@ onConfirmedNoBlockers) {
             };
         }
     }
-    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, diagnosticsUnsupportedServerIds, content: collectedContent, binding, skipReason, } = await collectDiagnosticsForFile(file, lspService, cwd, waitMs, serverScope);
+    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, diagnosticsUnsupportedServerIds, content: collectedContent, binding, tooLargeReason, skipReason, } = await collectDiagnosticsForFile(file, lspService, cwd, waitMs, serverScope);
+    if (tooLargeReason !== undefined) {
+        return { file, diagnostics: [], outcome: "too_large", tooLargeReason };
+    }
     const health = lspService.getDiagnosticsHealth?.(file);
     // #570: a timed-out priming check is never a confirmed "clean" — treat it
     // as unconfirmed without consulting the (unrelated) silent-tier
@@ -891,7 +970,22 @@ onConfirmedNoBlockers) {
     // Reserve the token before awaiting this file's LSP result. The direct-file
     // path performs its own confirmation/reconciliation below (#1198).
     const writeIndex = nextWriteIndex?.();
-    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, diagnosticsUnsupportedServerIds, content: collectedContent, binding, skipReason, } = await collectDiagnosticsForFile(absPath, lspService, cwd, waitMs, serverScope);
+    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, diagnosticsUnsupportedServerIds, content: collectedContent, binding, tooLargeReason, skipReason, } = await collectDiagnosticsForFile(absPath, lspService, cwd, waitMs, serverScope);
+    if (tooLargeReason !== undefined) {
+        return {
+            content: [{ type: "text", text: tooLargeReason }],
+            details: {
+                filePath: absPath,
+                mode: "file",
+                severity,
+                serverScope,
+                outcome: "too_large",
+                tooLargeReason,
+                diagnostics: [],
+                totalDiagnostics: 0,
+            },
+        };
+    }
     const lspHealth = lspService.getDiagnosticsHealth?.(absPath);
     const unavailable = lspUnavailableMessage(absPath, lspHealth);
     // #533: an empty result needs a confirmed/unconfirmed verdict — a push-only,
@@ -1050,6 +1144,7 @@ onConfirmedNoBlockers) {
             mode: "file",
             severity,
             serverScope,
+            ...(unavailable ? { unavailable } : {}),
             primaryServerId: primaryId,
             primaryDiagnosticsCount: primaryDiags.length,
             auxiliaryDiagnosticsCount: auxiliaryDiags.length,
@@ -1093,7 +1188,12 @@ function tallyConfirmation(results) {
     let unconfirmed = 0;
     let timedOut = 0;
     let navigationOnly = 0;
+    let tooLarge = 0;
     for (const result of results) {
+        if (result.tooLargeReason) {
+            tooLarge += 1;
+            continue;
+        }
         if (result.diagnosticsUnsupported) {
             navigationOnly += 1;
             continue;
@@ -1111,11 +1211,13 @@ function tallyConfirmation(results) {
             clean += 1;
         }
     }
-    return { clean, unconfirmed, timedOut, navigationOnly };
+    return { clean, unconfirmed, timedOut, navigationOnly, tooLarge };
 }
 function classifyBatchFileOutcome(result) {
     if (result.error)
         return "failed";
+    if (result.tooLargeReason)
+        return "too_large";
     if (result.diagnosticsUnsupported)
         return "unsupported";
     // A timed-out/unconfirmed answer may contain partial findings, but it cannot
@@ -1271,6 +1373,7 @@ async function collectBatchDiagnostics(files, severity, lspService, options) {
         "unsupported",
         "unavailable",
         "failed",
+        "too_large",
         "inconclusive",
     ].map((outcome) => [
         outcome,
@@ -1326,6 +1429,7 @@ async function runBatchFileDiagnostics(absPaths, severity, lspService, options)
         outcomeCounts.unavailable +
         outcomeCounts.unsupported +
         outcomeCounts.failed +
+        outcomeCounts.too_large +
         incompleteFiles;
     if (notConfirmed > 0) {
         lines.push("", `Checks not confirmed: ${notConfirmed} (inconclusive/unavailable/unsupported/failed or not started).`);
@@ -1335,6 +1439,18 @@ async function runBatchFileDiagnostics(absPaths, severity, lspService, options)
     }
     if (fileErrors.length > 0)
         lines.push("", "File errors:", ...fileErrors);
+    const outcomeDetails = results.map((result) => ({
+        file: result.file,
+        outcome: result.outcome,
+        reason: result.tooLargeReason ??
+            result.inconclusiveReason ??
+            result.error ??
+            result.unavailable,
+    }));
+    const tooLargeLines = renderBatchOutcomeLines(outcomeDetails);
+    if (tooLargeLines.length > 0) {
+        lines.push("", "Files too large for LSP diagnostics:", ...tooLargeLines);
+    }
     if (lspHealthWarnings.length > 0) {
         lines.push("", "LSP health warnings:", ...lspHealthWarnings.slice(0, 10));
     }
@@ -1349,7 +1465,7 @@ async function runBatchFileDiagnostics(absPaths, severity, lspService, options)
             `${unconfirmedReasonClause(unconfirmed, timedOut)} NOT the same as 0 diagnostics.`);
     }
     if (display.length === 0) {
-        if (unconfirmed === 0) {
+        if (unconfirmed === 0 && outcomeCounts.clean === results.length) {
             lines.push("", "No diagnostics found.");
         }
     }
@@ -1391,7 +1507,10 @@ async function runBatchFileDiagnostics(absPaths, severity, lspService, options)
             outcomes: results.map((result) => ({
                 file: result.file,
                 outcome: result.outcome,
-                reason: result.inconclusiveReason ?? result.error ?? result.unavailable,
+                reason: result.tooLargeReason ??
+                    result.inconclusiveReason ??
+                    result.error ??
+                    result.unavailable,
                 primaryDiagnosticsCount: result.diagnostics.filter((diagnostic) => diagnostic.serverId === result.primaryServerId).length,
                 auxiliaryDiagnosticsCount: result.diagnostics.filter((diagnostic) => diagnostic.serverId !== result.primaryServerId).length,
             })),
@@ -1455,11 +1574,20 @@ async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
     }
     const wasCapped = collectedFiles.length > MAX_FILES;
     const filesToProcess = collectedFiles.slice(0, MAX_FILES);
-    const { results, fileErrors, lspHealthWarnings, total, truncated, display, primaryDisplay, auxiliaryDisplay, clean, unconfirmed, timedOut, } = await collectBatchDiagnostics(filesToProcess, severity, lspService, options);
+    const { results, fileErrors, lspHealthWarnings, total, truncated, display, primaryDisplay, auxiliaryDisplay, clean, unconfirmed, timedOut, outcomeCounts, } = await collectBatchDiagnostics(filesToProcess, severity, lspService, options);
     const navigationOnly = results.filter((result) => result.diagnosticsUnsupported).length;
     // #3088: the directory scan's own suppressed bucket — one summed line.
     const dispositionSuppressed = results.reduce((sum, result) => sum + (result.dispositionSuppressed ?? 0), 0);
     const suppressedLine = dispositionSuppressedLine(dispositionSuppressed);
+    const outcomeDetails = results.map((result) => ({
+        file: result.file,
+        outcome: result.outcome,
+        reason: result.tooLargeReason ??
+            result.inconclusiveReason ??
+            result.error ??
+            result.unavailable,
+    }));
+    const tooLargeLines = renderBatchOutcomeLines(outcomeDetails, (file) => path.relative(absPath, file));
     let text;
     if (total === 0) {
         // #533/#570: an unconfirmed-containing directory result must never
@@ -1477,7 +1605,12 @@ async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
                     "LSP unavailable for one or more files:",
                     ...lspHealthWarnings.slice(0, 10),
                 ]
-                : [cleanLine]),
+                : unconfirmed > 0 || outcomeCounts.clean === filesToProcess.length
+                    ? [cleanLine]
+                    : []),
+            ...(tooLargeLines.length > 0
+                ? ["", "Files too large for LSP diagnostics:", ...tooLargeLines]
+                : []),
             ...(suppressedLine ? ["", suppressedLine] : []),
         ].join("\n");
     }
@@ -1520,6 +1653,9 @@ async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
         }
         if (suppressedLine)
             lines.push("", suppressedLine);
+        if (tooLargeLines.length > 0) {
+            lines.push("", "Files too large for LSP diagnostics:", ...tooLargeLines);
+        }
         text = lines.join("\n");
     }
     return {
@@ -1547,6 +1683,8 @@ async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
             truncated,
             cleanFiles: clean,
             unconfirmedFiles: unconfirmed,
+            outcomes: outcomeDetails,
+            outcomeCounts,
             navigationOnlyFiles: navigationOnly > 0 ? navigationOnly : undefined,
             timedOutFiles: timedOut > 0 ? timedOut : undefined,
             fileErrors: fileErrors.length > 0 ? fileErrors : undefined,

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