@herbertgao/pi-extensions 2026.8.5 → 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

@@ -1,24 +1,17 @@
-import { createHash } from "node:crypto";
 import * as nodeFs from "node:fs";
 import * as path from "node:path";
 import { isPathIgnoredByProject } from "./file-utils.js";
 import { tokenizeShellCommand } from "./bash-file-access.js";
-import { normalizeMapKey } from "./path-utils.js";
 import { logLatency } from "./latency-logger.js";
-const MAX_AFFECTED_FILES = 256;
+import { advisoryFileHash, advisoryPathKey, MAX_ADVISORY_AFFECTED_FILES, snapshotAdvisoryProvenance, } from "./advisory-provenance.js";
 function resolveGuardPath(filePath, cwd) {
     return path.resolve(cwd, filePath);
 }
 function guardPathKey(filePath, cwd) {
-    return normalizeMapKey(resolveGuardPath(filePath, cwd));
+    return advisoryPathKey(filePath, cwd);
 }
 function fileFingerprint(filePath) {
-    try {
-        return createHash("sha256").update(nodeFs.readFileSync(filePath)).digest("hex");
-    }
-    catch (err) {
-        return `unreadable:${err.code ?? "unknown"}`;
-    }
+    return advisoryFileHash(filePath);
 }
 function currentFileFingerprint(filePath) {
     try {
@@ -31,19 +24,11 @@ function currentFileFingerprint(filePath) {
             : `unreadable:${err.code ?? "unknown"}`;
     }
 }
-function snapshotFileHashes(files, cwd) {
-    const hashes = {};
-    for (const file of files) {
-        const resolved = resolveGuardPath(file, cwd);
-        hashes[guardPathKey(resolved, cwd)] = currentFileFingerprint(resolved);
-    }
-    return hashes;
-}
 function capAffectedFiles(files, cwd) {
     const unique = [...new Set(files.map((file) => resolveGuardPath(file, cwd)))];
     return {
-        files: unique.slice(0, MAX_AFFECTED_FILES),
-        truncated: unique.length > MAX_AFFECTED_FILES,
+        files: unique.slice(0, MAX_ADVISORY_AFFECTED_FILES),
+        truncated: unique.length > MAX_ADVISORY_AFFECTED_FILES,
     };
 }
 /** Recovery is safe only when blocker content and its file provenance agree. */
@@ -424,6 +409,17 @@ export function writeGitGuardRecord(cacheManager, runtime, cwd, record) {
             fileSeqByPath[key] = runtime.getFileSeq(resolveGuardPath(file, cwd));
         }
     }
+    const currentProvenance = snapshotAdvisoryProvenance({
+        cwd,
+        runtime,
+        generation: 0,
+        files: capped.files.map((file) => ({ path: file, role: "affected" })),
+        truncated: capped.truncated,
+    });
+    const fileContentHashes = Object.fromEntries(currentProvenance.files.map((file) => [
+        guardPathKey(file.path, cwd),
+        file.sha256,
+    ]));
     const data = {
         ...record,
         affectedFiles: capped.files,
@@ -432,7 +428,8 @@ export function writeGitGuardRecord(cacheManager, runtime, cwd, record) {
         blockingFiles: Array.isArray(record.blockingFiles)
             ? capAffectedFiles(record.blockingFiles, cwd).files
             : undefined,
-        fileContentHashes: snapshotFileHashes(capped.files, cwd),
+        fileContentHashes,
+        provenance: record.provenance ?? currentProvenance,
     };
     try {
         cacheManager.writeCache("turn-end-findings", data, cwd);
@@ -468,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/go-client.js

@@ -7,15 +7,16 @@
  * Docs: https://pkg.go.dev/golang.org/x/tools/gopls
  */
 import { createSubsystemLogger } from "./extension-log.js";
-import * as fs from "node:fs";
 import * as path from "node:path";
-import { safeSpawnAsync } from "./safe-spawn.js";
+import { createToolchainAvailability, } from "./dispatch/runners/utils/toolchain-availability.js";
 // --- Common install paths ---
 const GO_WINDOWS_PATHS = [
     "C:\\Program Files\\Go\\bin\\go.exe",
     "C:\\Go\\bin\\go.exe",
     "go.exe", // PATH
 ];
+/** Budget for the PATH candidate's `go version` probe, ms. */
+const PROBE_TIMEOUT_MS = 3_000;
 const GO_UNIX_PATHS = [
     "/usr/local/go/bin/go",
     "/usr/bin/go",
@@ -23,58 +24,39 @@ const GO_UNIX_PATHS = [
 ];
 // --- Client ---
 export class GoClient {
-    goAvailable = null;
-    goPath = null;
+    /**
+     * Availability lifecycle, behind the shared transient-aware latch (#1476).
+     * The PATH candidate is resolved by spawning `go version` with a 3 s budget,
+     * so a host stall could latch "no Go toolchain" for the whole session and
+     * silently disable every Go diagnostic until restart.
+     */
+    availability;
     log;
     constructor(verbose = false) {
         this.log = verbose
             ? createSubsystemLogger("go")
             : () => { };
+        this.availability = createToolchainAvailability({
+            tool: "go",
+            label: "Go",
+            windowsPaths: GO_WINDOWS_PATHS,
+            unixPaths: GO_UNIX_PATHS,
+            probeArgs: ["version"],
+            budgetMs: PROBE_TIMEOUT_MS,
+            log: (msg) => this.log(msg),
+        });
     }
     /**
      * Find go executable path (async — probes PATH candidates off the event loop).
      */
     async findGoPathAsync() {
-        if (this.goPath)
-            return this.goPath;
-        const paths = process.platform === "win32" ? GO_WINDOWS_PATHS : GO_UNIX_PATHS;
-        for (const p of paths) {
-            try {
-                if (p.includes("\\") || p.includes("/")) {
-                    // Absolute path - check if exists
-                    if (fs.existsSync(p)) {
-                        this.goPath = p;
-                        return p;
-                    }
-                }
-                else {
-                    // Relative (PATH) - try running it
-                    const result = await safeSpawnAsync(p, ["version"], {
-                        timeout: 3000,
-                    });
-                    if (!result.error && result.status === 0) {
-                        this.goPath = p;
-                        return p;
-                    }
-                }
-            }
-            catch (err) {
-                void err;
-            }
-        }
-        return null;
+        return this.availability.findPath();
     }
     /**
      * Check if Go is installed (cached)
      */
     async isGoAvailableAsync() {
-        if (this.goAvailable !== null)
-            return this.goAvailable;
-        this.goAvailable = (await this.findGoPathAsync()) !== null;
-        if (this.goAvailable) {
-            this.log(`Go found: ${this.goPath}`);
-        }
-        return this.goAvailable;
+        return this.availability.isAvailable();
     }
     /**
      * Check if a file is a Go file