@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/generation-guard.js

@@ -0,0 +1,216 @@
+/**
+ * Capture-generation-before-await, check-after — as one primitive (#1754).
+ *
+ * The shape: a write that follows an `await` must prove the world it captured
+ * still exists. A session reset, a cache refresh, or a newer request for the
+ * same key can land while the write's producer is in flight, and the late
+ * write then publishes an answer the caller no longer wants — or, in the
+ * eviction direction, deletes an entry a SUCCESSOR already installed.
+ *
+ * This module was extracted after the pattern was hand-rolled four times and
+ * its absence was a review finding twice:
+ *
+ * - `clients/dispatch/runners/utils/runner-helpers.ts` held the guarded form
+ *   at one site and the unguarded form at another IN THE SAME FILE; #1674's
+ *   F5 round copied the guard by hand to three more write sites.
+ * - `clients/lsp/client.ts`'s per-(path, identifier) pull sequences (#1682),
+ *   whose first guard was vacuous until a review round bound it.
+ * - `clients/lsp/workspace-diagnostics-cache.ts`'s per-cwd epochs (#1669),
+ *   where the epoch guarded `persist()` but not `lookup()`.
+ * - `clients/review-graph/builder.ts`'s workspace-cache epoch, the shape the
+ *   one above was modelled on.
+ *
+ * Two things every one of those needed and at least one got wrong:
+ *
+ * 1. The check must run at WRITE time, not only at capture time.
+ * 2. The stale branch must be OBSERVABLE. A silently dropped write looks
+ *    exactly like a write that never happened, which is why the vacuous
+ *    guards survived review. `guardedWrite` emits one bounded degradation
+ *    record per (source, subject) with the count of repeats, so a dogfood
+ *    session can tell "the guard is working" from "the guard never fires".
+ *
+ * ## Scope and lifetime
+ *
+ * A `GenerationSource` is a plain counter owned by the RESETTING SEAM — the
+ * function that already clears the state the generation protects. This module
+ * holds no session state of its own: sources live in the modules that create
+ * them, and their reset policy is that module's declaration in
+ * `tests/support/session-state-registry.ts`. The only module-level state here
+ * is the name registry below, which exists so the #1754 sweep can ask "which
+ * stores declare a generation" instead of guessing from identifier names.
+ *
+ * ## Cost
+ *
+ * `isCurrent()` on an unkeyed source is a field read and a compare. On a
+ * keyed map it is a compare while nothing has been invalidated, and a
+ * normalize plus one `Map.get` once something has. The hand-rolled form it
+ * replaces normalized on EVERY call, and this repo's normalizer runs
+ * `realpathSync.native` on Windows, so an uninterrupted sweep pays that
+ * syscall once rather than once per file. See
+ * `GenerationMapOptions.normalizeKey` for the correctness reason the slow
+ * path exists at all.
+ */
+import { incrementDegradationCount } from "./degradation-ledger.js";
+/**
+ * Names of every generation-carrying store created through this module.
+ *
+ * Registration is by CONSTRUCTION: you cannot make a `GenerationSource`
+ * without appearing here. `tests/clients/generation-guard-sweep.test.ts`
+ * reads this to enforce the ratchet — a file that hand-rolls the pattern
+ * instead of declaring it here must carry an explicit exemption reason.
+ *
+ * Process-lifetime and bounded: names are compile-time literals from module
+ * initialization, so this cannot grow with workload.
+ */
+const declaredSources = new Set();
+const MAX_DECLARED_SOURCES = 128;
+function declare(name) {
+    if (!name.trim()) {
+        throw new Error("generation source needs a non-empty name");
+    }
+    if (declaredSources.size < MAX_DECLARED_SOURCES)
+        declaredSources.add(name);
+    return name;
+}
+/** Every generation-carrying store name declared this process. */
+export function listDeclaredGenerationSources() {
+    return [...declaredSources].sort((a, b) => a.localeCompare(b));
+}
+function recordStaleWrite(sourceName, subject, captured, observed) {
+    incrementDegradationCount({
+        kind: "generation-guard-stale-write",
+        subject: `${sourceName}:${subject}`,
+        reason: `write dropped: captured generation ${captured}, current ${observed}`,
+    });
+}
+function makeHandle(sourceName, generation, read) {
+    return {
+        generation,
+        isCurrent() {
+            return read() === generation;
+        },
+        guardedWrite(subject, write) {
+            const observed = read();
+            if (observed !== generation) {
+                recordStaleWrite(sourceName, subject, generation, observed);
+                return undefined;
+            }
+            return write();
+        },
+    };
+}
+/**
+ * Create a counter for a store invalidated as a whole.
+ *
+ * `name` appears in the stale-write ledger subject and in the sweep's
+ * declaration list, so it must name the STORE, not the module.
+ */
+export function createGenerationSource(name) {
+    declare(name);
+    let generation = 0;
+    const read = () => generation;
+    return {
+        name,
+        current: read,
+        bump() {
+            generation += 1;
+            return generation;
+        },
+        capture() {
+            return makeHandle(name, generation, read);
+        },
+    };
+}
+const DEFAULT_MAX_KEYS = 512;
+/**
+ * Create a per-key family of counters.
+ *
+ * Use this when invalidation is scoped: a cache refresh for ONE cwd must not
+ * drop an in-flight write for another, and a newer pull request for one
+ * (path, source) pair must not invalidate a different pair's.
+ */
+export function createGenerationMap(name, options = {}) {
+    declare(name);
+    const normalize = options.normalizeKey ?? ((key) => key);
+    const maxKeys = Math.max(1, options.maxKeys ?? DEFAULT_MAX_KEYS);
+    // Insertion-ordered: the oldest key is evicted first. Re-stamping a key
+    // refreshes its position so a hot cwd is not evicted by a burst of
+    // one-shot ones.
+    const stamps = new Map();
+    // ONE ticket counter for the whole map. See GenerationMap's doc comment:
+    // per-key counters starting at 0 make eviction and forget() fail OPEN.
+    // 0 is reserved for "this key holds no stamp" and is never issued.
+    let nextTicket = 0;
+    // Counts every mutation that can change what a key's stamp reads: a bump,
+    // a forget, an eviction. A handle records this at capture and re-derives
+    // its key only when it has moved. See normalizeKey's doc comment.
+    let invalidations = 0;
+    const read = (key) => stamps.get(key) ?? 0;
+    function issue(key) {
+        nextTicket += 1;
+        stamps.delete(key);
+        stamps.set(key, nextTicket);
+        while (stamps.size > maxKeys) {
+            const oldest = stamps.keys().next().value;
+            if (oldest === undefined)
+                break;
+            stamps.delete(oldest);
+            invalidations += 1;
+        }
+        return nextTicket;
+    }
+    return {
+        name,
+        current(key) {
+            return read(normalize(key));
+        },
+        bump(key) {
+            invalidations += 1;
+            return issue(normalize(key));
+        },
+        capture(key) {
+            const normalized = normalize(key);
+            // A first-use capture ISSUES a stamp rather than reading 0. A handle
+            // holding 0 would be indistinguishable from one whose key was later
+            // forgotten or evicted, which is the fail-open hole this closes.
+            const stamp = read(normalized) || issue(normalized);
+            const capturedInvalidations = invalidations;
+            return makeHandle(`${name}[${normalized}]`, stamp, () => {
+                // Fast path: nothing has been invalidated since capture, so no key
+                // can have changed stamps and the normalizer need not run again.
+                if (invalidations === capturedInvalidations)
+                    return stamp;
+                // Something moved. Re-derive the key from the ORIGINAL string: a
+                // normalizer that consults the filesystem can resolve the same
+                // input to a different key once the path exists, and a stamp read
+                // under the stale spelling would falsely read current.
+                return read(normalize(key));
+            });
+        },
+        forget(key) {
+            invalidations += 1;
+            stamps.delete(normalize(key));
+        },
+        size() {
+            return stamps.size;
+        },
+    };
+}
+/**
+ * Capture the generation, run `fn`, and hand it the handle.
+ *
+ * Sugar for the common `const handle = source.capture(); ... await ...;
+ * handle.guardedWrite(...)` sequence. Use `capture()` directly when the
+ * handle must outlive the function that made it — an eviction guard in a
+ * `.finally()` is the usual case, and it is what both #1754 migrations do.
+ *
+ * This ships ahead of its first production caller. Both migrated sites need
+ * the handle to outlive its producer, so neither uses this form; it exists
+ * because the issue specifies it and because the sites still to migrate
+ * (`runtime-coordinator.ts`, `runtime-turn.ts`) write inside the async
+ * function that captured. Said plainly rather than left for a reader to
+ * discover by grep.
+ */
+export async function withGeneration(source, fn) {
+    return fn(source.capture());
+}

package/node_modules/pi-lens/dist/clients/git-guard.js

@@ -465,6 +465,37 @@ function unknown(cwd, reasonCategory, metadata = {}) {
  * on tool_result, never tool_call, and therefore does not add disk I/O to the
  * edit preflight path.
  */
+/**
+ * Retire one file's inline blocker on a confirmed-clean verdict, then bring the
+ * commit gate back in line with the map (#1561 F2).
+ *
+ * Retiring the map entry alone is not enough and claiming otherwise was wrong:
+ * the gate reads a LATCH (`gitGuardHasBlockers`) and a PERSISTED record, and
+ * `evaluateGitGuard` short-circuits on the latch before it ever looks at the
+ * record. A retire that touched neither left the commit blocked and quoted the
+ * retired blocker back as the reason.
+ *
+ * Both are recomputed exactly the way a clean dispatch recomputes them:
+ * `updateGitGuardStatus(false, "")` re-derives the latch from the blocker map
+ * — it cannot clear a latch another file's live blocker still justifies,
+ * because that file's entry is still in the map — and `syncGitGuardRecord`
+ * rewrites the persisted record from the same source of truth.
+ *
+ * Colocated with the gate rather than inlined at the wiring site so the claim
+ * is testable without booting the extension.
+ *
+ * @returns true when an entry was retired (the caller logs it — #1432 Gap 1).
+ */
+export function retireInlineBlockerAndResyncGuard(args) {
+    const retired = args.runtime.retireInlineBlockerOnConfirmedClean(args.filePath, args.writeIndex, args.coveredSources);
+    if (!retired)
+        return false;
+    args.runtime.updateGitGuardStatus(false, "");
+    if (args.lensGuardEnabled) {
+        syncGitGuardRecord(args.runtime, args.cacheManager, args.cwd, args.filePath);
+    }
+    return true;
+}
 export function syncGitGuardRecord(runtime, cacheManager, cwd, editedFilePath) {
     const entries = runtime.getInlineBlockersSnapshot?.() ?? [];
     const inspection = cacheManager.inspectCache("turn-end-findings", cwd);

package/node_modules/pi-lens/dist/clients/gitleaks-client.js

@@ -28,19 +28,133 @@
  * (installer entry registered in clients/installer/index.ts) and runs
  * `gitleaks detect --no-git --report-format json` against the analysis root.
  *
- * Refs: #130
+ * Scope policy (#1562): gitleaks is handed a `--config` generated per scan
+ * (`writeScopedGitleaksConfig`) that EXTENDS the project's own `.gitleaks.toml`
+ * (or gitleaks's built-in defaults, if none) with two additions — an
+ * `[allowlist] paths` entry per NARROW secrets-lane scratch tree
+ * (`scratch-tree-policy.ts`'s `SECRETS_LANE_SCRATCH_DIR_NAMES` — pi-ecosystem/
+ * agent data dirs, `node_modules`, `.git`, generic build caches; deliberately
+ * NOT the broader walker-parity `EXCLUDED_DIRS` list knip/jscpd use, which
+ * also drops real leak surfaces like `dist/`, `vendor/`, `.vscode/` — see that
+ * module's doc for the review-round probe that caught the too-broad first
+ * cut) and an `[allowlist] regexes` entry per known placeholder-secret shape
+ * (`YOUR_API_KEY`, `<your-key>`, `xxxxxxxx`, …). An allowlist entry is a
+ * POST-DETECTION filter, not a walk exclusion — gitleaks still visits every
+ * file; the allowlist only decides which raw hits get suppressed from the
+ * report. Deliberately NOT `.gitignore`-based — see `scratch-tree-policy.ts`'s
+ * module doc for why blanket gitignore-respect is wrong for a secrets scanner
+ * (an untracked `.env` with a real credential is exactly the case gitleaks
+ * exists to catch, and `.env` is commonly gitignored). `classifyAndFilterFindings`
+ * backstops the config with a TS-side re-classification: a finding under the
+ * secrets-lane scratch tier is DEMOTED (not deleted) to `severity: "info"`,
+ * `semantic: "none"`, `pathStatus: "scratch"` — visible for an audit read,
+ * but it can never surface as a blocking "leaked secret" alarm. Every other
+ * finding gets `pathStatus` from git's tracked/ignored view.
+ *
+ * Refs: #130, #1562
  */
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { mkdtempSync } from "node:fs";
+import { collectTrackedFiles, collectUntrackedIgnoredIds, } from "./git-tracked-ignore.js";
+import { normalizeEphemeralMapKey, normalizeMapKey } from "./path-utils.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
 import { SecurityScanClient } from "./security-scan-client.js";
+import { getSecretsLaneAllowlistPaths, isUnderSecretsLaneScratchTree, } from "./scratch-tree-policy.js";
 const EMPTY_RESULT = {
     success: false,
     findings: [],
 };
 const SCAN_TIMEOUT_MS = 120_000;
+// gitleaks discovers its own config at `<source>/.gitleaks.toml` (or `.yaml`/
+// `.yml`) when no `--config` is passed. Kept as a named constant so the
+// generated scoped config (below) can EXTEND whichever of these the project
+// already has, instead of silently replacing the project's own rules.
+const LOCAL_GITLEAKS_CONFIG_NAMES = [
+    ".gitleaks.toml",
+    ".gitleaks.yaml",
+    ".gitleaks.yml",
+];
+function findLocalGitleaksConfig(cwd) {
+    for (const name of LOCAL_GITLEAKS_CONFIG_NAMES) {
+        const candidate = path.join(cwd, name);
+        try {
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        catch {
+            // non-fatal
+        }
+    }
+    return undefined;
+}
+// The #1562 incident: a curl doc example's `-H "Authorization: Bearer
+// YOUR_API_KEY"` (cached under gitignored scratch, see the secrets-lane
+// exclusion below) read as a leaked secret. These match gitleaks's own
+// `Secret`/`Match` value case-insensitively, catching the canonical
+// placeholder shapes: `YOUR_API_KEY`-style tokens, `<your-key>`-style angle
+// brackets, run-of-`x` filler, and the common changeme/example/dummy family.
+// Scoped to the whole matched value (`^...$`) so a REAL secret that merely
+// contains the substring "key" is never caught by accident.
+//
+// #1562 review-round F3: regex 2's alternation required "key" to be prefixed
+// (`api[-_ ]?key`) — the issue's own literal acceptance example, `<your-key>`
+// (bare "key", no "api" prefix), didn't match. Added a bare `key` alternative;
+// still safe because the match is scoped to the WHOLE bracketed value
+// (`^<...>$`), so a real secret that happens to be wrapped in angle brackets
+// AND merely contain the substring "key" still wouldn't collide with this —
+// only a value that is ENTIRELY `<...key...>`-shaped does.
+export const PLACEHOLDER_SECRET_REGEXES = [
+    String.raw `(?i)^(your|my|insert|replace|enter|add)[-_ ]?(the[-_ ]?)?(api[-_ ]?)?(key|token|secret|password|credential)s?$`,
+    String.raw `(?i)^<[^<>]*(api[-_ ]?key|token|secret|password|credential|key)[^<>]*>$`,
+    String.raw `(?i)^x{3,}$`,
+    String.raw `(?i)^(changeme|change[-_]me|example|placeholder|dummy|fake|redacted|xxxxxxxx)$`,
+];
+/**
+ * Build a temp gitleaks config that EXTENDS the project's own config (if any,
+ * else gitleaks's built-in defaults) with two additions:
+ *   1. `[allowlist] paths` — the NARROW secrets-lane scratch exclusion
+ *      (`scratch-tree-policy.ts`'s `getSecretsLaneAllowlistPaths`, NOT the
+ *      broader walker-parity `EXCLUDED_DIRS` list — #1562 review-round F1).
+ *   2. `[allowlist] regexes` — the placeholder-secret class above.
+ *
+ * An `[allowlist]` entry is a POST-DETECTION filter (#1562 review-round F4):
+ * gitleaks still visits every file under `--source`; the allowlist decides
+ * which of the raw hits it reports, it does not shrink the walk itself.
+ *
+ * gitleaks's `[extend]` allowlist merge is additive (append, not replace —
+ * see gitleaks/config/config.go), so a project's own curated allowlist keeps
+ * working unchanged; this only ever ADDS exclusions, never removes one the
+ * project opted into.
+ *
+ * Returns the generated file's path; caller owns cleanup (same temp dir as
+ * the report, removed together in `runScan`'s `finally`).
+ */
+export function writeScopedGitleaksConfig(outDir, cwd) {
+    const localConfig = findLocalGitleaksConfig(cwd);
+    const extendLine = localConfig
+        ? `path = ${JSON.stringify(localConfig)}`
+        : "useDefault = true";
+    const pathPatterns = getSecretsLaneAllowlistPaths()
+        .map((p) => `    ${JSON.stringify(p)},`)
+        .join("\n");
+    const regexPatterns = PLACEHOLDER_SECRET_REGEXES.map((r) => `    ${JSON.stringify(r)},`).join("\n");
+    const toml = `[extend]
+${extendLine}
+
+[allowlist]
+paths = [
+${pathPatterns}
+]
+regexes = [
+${regexPatterns}
+]
+`;
+    const configPath = path.join(outDir, "gitleaks-scoped-config.toml");
+    fs.writeFileSync(configPath, toml, "utf-8");
+    return configPath;
+}
 // --- Detection ---
 /**
  * Detect whether the project root has opted in to gitleaks via any of the
@@ -51,12 +165,7 @@ const SCAN_TIMEOUT_MS = 120_000;
  * the client.
  */
 export function hasGitleaksSignal(cwd) {
-    const candidates = [
-        ".gitleaks.toml",
-        ".gitleaks.yaml",
-        ".gitleaks.yml",
-        ".gitleaksignore",
-    ];
+    const candidates = [...LOCAL_GITLEAKS_CONFIG_NAMES, ".gitleaksignore"];
     for (const candidate of candidates) {
         try {
             if (fs.existsSync(path.join(cwd, candidate)))
@@ -187,11 +296,14 @@ export class GitleaksClient extends SecurityScanClient {
         const outDir = mkdtempSync(path.join(os.tmpdir(), "pi-lens-gitleaks-"));
         const reportPath = path.join(outDir, "gitleaks-report.json");
         try {
+            const configPath = writeScopedGitleaksConfig(outDir, cwd);
             const result = await safeSpawnAsync(bin, [
                 "detect",
                 "--no-git",
                 "--source",
                 cwd,
+                "--config",
+                configPath,
                 "--report-format",
                 "json",
                 "--report-path",
@@ -219,7 +331,8 @@ export class GitleaksClient extends SecurityScanClient {
                     summary: (result.stderr ?? "").trim().split("\n")[0] || "no report produced",
                 };
             }
-            const findings = parseGitleaksReport(fs.readFileSync(reportPath, "utf-8"));
+            const rawFindings = parseGitleaksReport(fs.readFileSync(reportPath, "utf-8"));
+            const findings = await classifyAndFilterFindings(rawFindings, cwd);
             return {
                 success: true,
                 findings,
@@ -243,6 +356,66 @@ export class GitleaksClient extends SecurityScanClient {
         }
     }
 }
+// --- Post-scan classification / filter ---
+/**
+ * Backstop for the scoped-config secrets-lane exclusion above, plus the
+ * `pathStatus` observability field (#1562).
+ *
+ * Two things happen here, both defense-in-depth relative to the generated
+ * gitleaks config:
+ *   1. Any finding still under the NARROW secrets-lane scratch tier
+ *      (`isUnderSecretsLaneScratchTree` — NOT the broader walker-parity
+ *      `EXCLUDED_DIRS` list) is DEMOTED, never DROPPED (#1562 review-round
+ *      F2: the observability criterion requires this value to actually be
+ *      reachable, so a scratch finding survives with `pathStatus: "scratch"`
+ *      and the adapter (`gitleaksFindingToProjectDiagnostic`) reports it as
+ *      `severity: "info"`/`semantic: "none"` — visible for an audit read,
+ *      but it can never surface as a blocking "leaked secret" alarm). We
+ *      can't exercise gitleaks's own TOML-regex engine in unit tests, only
+ *      assert the config we hand it, so this backstop guarantees the demotion
+ *      even if the generated regex ever mismatches gitleaks's own path
+ *      normalization.
+ *   2. Every OTHER finding gets `pathStatus` set from git's tracked/ignored
+ *      view, so a future false-positive triage is a log read.
+ *
+ * `collectTrackedFiles`/`collectUntrackedIgnoredIds` degrade to `undefined`
+ * when git itself is unavailable (no repo, spawn failure) — findings just
+ * keep `pathStatus: undefined` rather than a guessed value (fail-open,
+ * matching `git-tracked-ignore.ts`'s own contract). Exported for unit tests.
+ */
+export async function classifyAndFilterFindings(findings, cwd) {
+    if (findings.length === 0)
+        return findings;
+    const [trackedIds, untrackedIgnoredIds] = await Promise.all([
+        collectTrackedFiles(cwd),
+        collectUntrackedIgnoredIds(cwd),
+    ]);
+    const classified = [];
+    for (const finding of findings) {
+        if (isUnderSecretsLaneScratchTree(finding.file)) {
+            classified.push({ ...finding, pathStatus: "scratch" });
+            continue;
+        }
+        const absPath = path.isAbsolute(finding.file)
+            ? finding.file
+            : path.resolve(cwd, finding.file);
+        let pathStatus;
+        if (trackedIds?.has(normalizeEphemeralMapKey(absPath))) {
+            pathStatus = "tracked";
+        }
+        else if (untrackedIgnoredIds?.has(normalizeMapKey(absPath))) {
+            pathStatus = "ignored";
+        }
+        else if (trackedIds !== undefined || untrackedIgnoredIds !== undefined) {
+            // At least one of the two git-backed sets resolved, so the absence
+            // from both is a real answer ("untracked, not gitignored") rather
+            // than an unresolved probe.
+            pathStatus = "untracked";
+        }
+        classified.push(pathStatus ? { ...finding, pathStatus } : finding);
+    }
+    return classified;
+}
 // --- Parser ---
 /**
  * Map gitleaks's JSON report (a flat array of finding objects) to our

package/node_modules/pi-lens/dist/clients/govulncheck-client.js

@@ -22,7 +22,8 @@ import * as path from "node:path";
 import { safeSpawnAsync } from "./safe-spawn.js";
 import { assertInstallAllowed } from "./project-trust.js";
 import { SecurityScanClient } from "./security-scan-client.js";
-import { classifyProbeFailure, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
+import { classifyProbeFailure, describeProbeEvidence, INSTALL_TRANSIENT_MAX_ATTEMPTS, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
+import { recordDegradationOnce } from "./degradation-ledger.js";
 const EMPTY_RESULT = {
     success: false,
     findings: [],
@@ -61,9 +62,10 @@ export class GovulncheckClient extends SecurityScanClient {
             // #1467: a timed-out/killed probe says nothing about whether
             // govulncheck is on PATH. Latching `false` here disabled it for the
             // life of the process; a `go install` here would be a heavyweight
-            // reaction to a host hiccup. Record an expiring verdict, retry later.
+            // reaction to a host hiccup. probeVersion has already recorded the
+            // expiring verdict and its retry schedule (#1501) — re-marking it
+            // here would double-escalate the cooldown. Retry later.
             this.log("govulncheck probe timed out; retrying later (not installing)");
-            this.markTransientlyUnavailable(this.lastProbeCause ?? "probe-timeout");
             return false;
         }
         if (!assertInstallAllowed("govulncheck go install")) {
@@ -112,7 +114,15 @@ export class GovulncheckClient extends SecurityScanClient {
                 return false;
             }
             this.log("go binary not on PATH — cannot auto-install govulncheck");
-            this.available = false;
+            // Derived from the `go version` probe above, and recorded with it: a
+            // reader can see WHY govulncheck went quiet without re-running it (#1500).
+            // The evidence names `go`, because that is what was spawned — a row that
+            // carried go's errno unlabelled under `tool: "govulncheck"` invited the
+            // exact misreading the field exists to prevent.
+            this.noteDurableAbsence({
+                ...describeProbeEvidence(goOnPath, "go"),
+                install: "not-attempted",
+            });
             return false;
         }
         this.log("govulncheck not found, attempting auto-install via go install");
@@ -139,23 +149,63 @@ export class GovulncheckClient extends SecurityScanClient {
                 hostStallMs: installHostStallMs,
             });
             if (outcome === "transient") {
-                const retryAfterMs = this.markTransientlyUnavailable(cause);
+                // #1497: the retried operation here is a ≤60s network compile,
+                // not a cheap probe, so it escalates on the install-class
+                // schedule and latches at the attempt ceiling instead of
+                // re-compiling every few minutes forever.
+                const retryAfterMs = this.markTransientlyUnavailable(cause, {
+                    operationClass: "install",
+                });
+                const exhausted = retryAfterMs === 0;
+                const ceilingReason = `go install timed out ${INSTALL_TRANSIENT_MAX_ATTEMPTS} times; install retries disabled until the next session`;
+                if (exhausted) {
+                    // The symptom a user notices is an unexplained busy core, not a
+                    // missing tool — so the terminal verdict gets the louder record.
+                    // Once per session, matching the latch's own lifetime: both re-arm
+                    // at `session_start` (review F3).
+                    recordDegradationOnce({
+                        kind: "install-retry-exhausted",
+                        subject: "govulncheck",
+                        reason: ceilingReason,
+                    });
+                }
                 // One record per decision, so an install that keeps timing out is
                 // readable in latency.log the same day (#1467's forensic trail).
                 logAvailabilityDecision({
                     tool: "govulncheck",
                     verdict: "unavailable",
                     outcome,
-                    cause,
+                    // At the ceiling the latch rewrote the cause; a row still saying
+                    // `probe-timeout` would read as "cooling down" (#1497 review F5).
+                    cause: exhausted ? (this.latchedCause() ?? cause) : cause,
                     elapsedMs: Date.now() - installStartedAt,
-                    latched: false,
+                    latched: exhausted,
                     hostStallMs: installHostStallMs,
                     ...(retryAfterMs > 0 && { retryAfterMs }),
                     budgetMs: INSTALL_TIMEOUT_MS,
+                    // The ceiling verdict is an ASSERTION by this call site, not a
+                    // classification of one spawn, and #1534's convention is that such a
+                    // row says so and carries the install facts behind it. Every retry
+                    // DID run a `go install` that failed, so `install: "failed"` is
+                    // earned, and the reason names the ceiling rather than the spawn.
+                    ...(exhausted && {
+                        classifiedBy: "caller",
+                        evidence: {
+                            ...describeProbeEvidence(install, "go install"),
+                            install: "failed",
+                            installReason: ceilingReason,
+                        },
+                    }),
                 });
                 return false;
             }
-            this.available = false;
+            // A non-transient install failure (module not found, compile error) IS
+            // evidence about this machine, so it latches — but the row says the
+            // install was tried and failed, which a plain absence never does (#1500).
+            this.noteDurableAbsence({
+                ...describeProbeEvidence(install, "go install"),
+                install: "failed",
+            }, { elapsedMs: Date.now() - installStartedAt });
             return false;
         }
         // `go install` writes to `$GOBIN` or `$GOPATH/bin`. The user may not
@@ -176,6 +226,27 @@ export class GovulncheckClient extends SecurityScanClient {
         if (!reprobe.error && reprobe.status === 0) {
             this.log("govulncheck auto-installed and found on PATH");
             this.available = true;
+            // The initial PATH probe already wrote a latched `unavailable` row
+            // (#1500's own assertion doesn't fire here — the reprobe SUCCEEDED —
+            // but that first probe's verdict still logged, before `go install`
+            // ever ran). Without a compensating row here, the durable record says
+            // govulncheck is off when `go install` just put it on PATH (#1606).
+            logAvailabilityDecision({
+                tool: "govulncheck",
+                verdict: "available",
+                outcome: "success",
+                cause: "ok",
+                elapsedMs: Date.now() - reprobeStartedAt,
+                latched: true,
+                hostStallMs: reprobeHostStallMs,
+                budgetMs: 5000,
+                classifiedBy: "caller",
+                evidence: {
+                    install: "succeeded",
+                    binary: "govulncheck",
+                    source: "go-install",
+                },
+            });
             return true;
         }
         // Look in the canonical install locations and remember the absolute
@@ -196,6 +267,24 @@ export class GovulncheckClient extends SecurityScanClient {
                     this.binaryPath = candidate;
                     this.available = true;
                     this.log(`govulncheck auto-installed at ${candidate}`);
+                    // Same compensating row as the on-PATH reprobe arm above (#1606):
+                    // the initial probe already latched `unavailable`, and this arm
+                    // is the OTHER way to recover — the canonical $GOBIN/$GOPATH walk
+                    // found it after the on-PATH reprobe missed.
+                    logAvailabilityDecision({
+                        tool: "govulncheck",
+                        verdict: "available",
+                        outcome: "success",
+                        cause: "ok",
+                        elapsedMs: Date.now() - installStartedAt,
+                        latched: true,
+                        classifiedBy: "caller",
+                        evidence: {
+                            install: "succeeded",
+                            binary: path.basename(candidate),
+                            source: "go-install",
+                        },
+                    });
                     return true;
                 }
             }
@@ -227,8 +316,19 @@ export class GovulncheckClient extends SecurityScanClient {
             });
             return false;
         }
+        // The third silent arm (#1500 review): the install SUCCEEDED and the binary
+        // is nowhere the re-probe or the canonical bin dirs could find it. That is a
+        // durable, actionable fact — and until now it latched with no record at all,
+        // so a $GOBIN misconfiguration was indistinguishable from govulncheck simply
+        // not being installed. `install: "succeeded"` also appears on the two success
+        // arms above (#1606's compensating `available` rows) — this is the durable
+        // FAILURE counterpart, an install that worked but left nothing locatable.
         this.log("govulncheck auto-install succeeded but binary not locatable — check $GOBIN / $GOPATH");
-        this.available = false;
+        this.noteDurableAbsence({
+            ...describeProbeEvidence(reprobe, "govulncheck"),
+            install: "succeeded",
+            installReason: "installed binary not found on PATH, $GOBIN or $GOPATH/bin",
+        }, { elapsedMs: Date.now() - reprobeStartedAt });
         return false;
     }
     /**