@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/dist/clients/pipeline.js

@@ -13,7 +13,7 @@
  */
 import * as nodeFs from "node:fs";
 import * as path from "node:path";
-import { findNearestContaining } from "./path-utils.js";
+import { findNearestContaining, normalizeEphemeralMapKey } from "./path-utils.js";
 import { recordFromDispatchDiagnostic, } from "./actionable-warnings.js";
 import { recordFromCodeQualityDiagnostic, } from "./code-quality-warnings.js";
 import { recordDiagnostics } from "./widget-state.js";
@@ -21,7 +21,7 @@ import { getDiagnosticLogger } from "./diagnostic-logger.js";
 import { getDiagnosticTracker } from "./diagnostic-tracker.js";
 import { loadDispatchIntegration } from "./dispatch/lazy.js";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
-import { createAvailabilityChecker, resolveAvailableOrInstall, resolveCommandArgsWithInstallFallback, resolveToolCommand, resolveToolCommandWithInstallFallback, } from "./dispatch/runners/utils/runner-helpers.js";
+import { classifyProbeFailure, createAvailabilityChecker, createAvailabilityLatch, describeProbeEvidence, logAvailabilityDecision, startHostStallSampler, resolveAvailableOrInstall, resolveCommandArgsWithInstallFallback, resolveToolCommand, resolveToolCommandWithInstallFallback, } from "./dispatch/runners/utils/runner-helpers.js";
 import { findDetektConfig } from "./dispatch/runners/detekt.js";
 import { detectFileKind, getFileKindLabel } from "./file-kinds.js";
 import { detectFileChangedAfterCommand, getProjectIgnoreMatcher, isExcludedDirName, } from "./file-utils.js";
@@ -178,6 +178,13 @@ function createPhaseTracker(toolName, filePath) {
 }
 // --- ESLint autofix helpers ---
 export { hasEslintConfig, hasRubocopConfig, hasSqlfluffConfig, hasStylelintConfig, };
+/**
+ * eslint autofix availability, per cwd + PATH. The verdict is owned by the
+ * shared availability latch (#1494): a `missing` / `non-installable` outcome
+ * sticks for the session, a timeout expires on a cooldown and is re-probed, so
+ * one stalled probe cannot silently stop autofixing a project's JS/TS.
+ */
+const ESLINT_FIX_PROBE_BUDGET_MS = 5000;
 const _eslintCache = new BoundedLruCache(32);
 /**
  * Run eslint --fix on a file. Runs a single spawn and diffs the file before/after,
@@ -196,18 +203,70 @@ async function tryEslintFix(filePath, cwd) {
     const cacheKey = `${path.resolve(cwd)}|${process.env.PATH ?? ""}`;
     let cached = _eslintCache.get(cacheKey);
     if (!cached) {
-        const candidate = resolveToolCommand(cwd, "eslint") ?? "eslint";
-        const check = await safeSpawnAsync(candidate, ["--version"], {
-            timeout: 5000,
-            cwd,
-        });
-        cached = {
-            available: !check.error && check.status === 0,
-            bin: !check.error && check.status === 0 ? candidate : null,
-        };
+        cached = { latch: createAvailabilityLatch(), bin: null };
         _eslintCache.set(cacheKey, cached);
     }
-    if (!cached.available || !cached.bin)
+    if (cached.latch.read() === null) {
+        const candidate = resolveToolCommand(cwd, "eslint") ?? "eslint";
+        // The budget is enforced by a HOST-side timer, so a stalled event loop
+        // expires it while eslint is still healthy. Measure the overlapping stall
+        // and hand it to the classifier, exactly like the runner path: without it a
+        // host-stall timeout is re-caused as `probe-timeout` and gets the escalating
+        // 30s→300s cooldown instead of the 5s host-stall one (#1467).
+        const stallSampler = startHostStallSampler();
+        const startedAt = Date.now();
+        let check;
+        let hostStallMs;
+        try {
+            check = await safeSpawnAsync(candidate, ["--version"], {
+                timeout: ESLINT_FIX_PROBE_BUDGET_MS,
+                cwd,
+            });
+        }
+        finally {
+            hostStallMs = stallSampler.stop();
+        }
+        const elapsedMs = Date.now() - startedAt;
+        const decisionCwd = path.resolve(cwd);
+        if (!check.error && check.status === 0) {
+            cached.bin = candidate;
+            cached.latch.noteAvailable();
+            logAvailabilityDecision({
+                tool: "eslint",
+                verdict: "available",
+                outcome: "success",
+                cause: "ok",
+                elapsedMs,
+                latched: true,
+                hostStallMs,
+                budgetMs: ESLINT_FIX_PROBE_BUDGET_MS,
+                classifiedBy: "probe",
+                evidence: describeProbeEvidence(check, "eslint"),
+            }, decisionCwd);
+        }
+        else {
+            cached.bin = null;
+            const { outcome, cause, evidence } = classifyProbeFailure(check, {
+                hostStallMs,
+                command: "eslint",
+            });
+            const retryAfterMs = cached.latch.noteUnavailable(outcome, cause);
+            logAvailabilityDecision({
+                tool: "eslint",
+                verdict: "unavailable",
+                outcome,
+                cause,
+                elapsedMs,
+                latched: retryAfterMs === 0,
+                hostStallMs,
+                ...(retryAfterMs > 0 && { retryAfterMs }),
+                budgetMs: ESLINT_FIX_PROBE_BUDGET_MS,
+                classifiedBy: "probe",
+                evidence,
+            }, decisionCwd);
+        }
+    }
+    if (cached.latch.read() !== true || !cached.bin)
         return 0;
     const cmd = cached.bin;
     return detectFileChangedAfterCommand(filePath, cmd, ["--fix", "--no-error-on-unmatched-pattern", filePath], cwd, [1]);
@@ -650,6 +709,24 @@ export async function resyncLspFile(filePath, fileContent, needsContentRefresh,
             if (outcome === "bailed") {
                 // Abandon the still-pending write; the edit continues. Log it so this
                 // stall — previously an invisible hang — is queryable in latency.log.
+                //
+                // #1766: a resync deadline can expire while the target server's FIRST
+                // spawn is still in flight (cold spawn > budget). That is not the same
+                // state as a running server that stalled on a write — the server the
+                // old wording blamed as "slow/wedged" did not exist yet. Distinguish
+                // the two via a fresh, synchronous inFlight lookup so the record keeps
+                // the discriminating identity (which server, which lifecycle state).
+                // Guarded: a test double or future service shape lacking the method
+                // must degrade to the old "timeout"/slow-wedged wording, not throw
+                // into the catch below and suppress this record entirely (#1766 F3).
+                const spawnInFlight = !abort?.aborted &&
+                    typeof lspService.isSpawnInFlight === "function" &&
+                    lspService.isSpawnInFlight(filePath);
+                const reason = abort?.aborted
+                    ? "aborted"
+                    : spawnInFlight
+                        ? "spawn-in-flight"
+                        : "timeout";
                 logLatency({
                     type: "phase",
                     phase: "lsp_sync_abandoned",
@@ -657,11 +734,16 @@ export async function resyncLspFile(filePath, fileContent, needsContentRefresh,
                     durationMs: Date.now() - startedAt,
                     metadata: {
                         source: "lsp_sync",
-                        reason: abort?.aborted ? "aborted" : "timeout",
+                        reason,
                         budgetMs,
                     },
                 });
-                dbg(`LSP resync ${abort?.aborted ? "aborted (Escape)" : `timed out after ${budgetMs}ms`}; server slow/wedged for ${filePath}`);
+                const cause = abort?.aborted
+                    ? "aborted (Escape)"
+                    : spawnInFlight
+                        ? `timed out after ${budgetMs}ms; reason: spawn-in-flight (server still cold-spawning)`
+                        : `timed out after ${budgetMs}ms; server slow/wedged`;
+                dbg(`LSP resync ${cause} for ${filePath}`);
             }
         }
     }
@@ -1007,24 +1089,16 @@ export async function runPipeline(ctx, deps) {
             : "";
         output += `\n\n⚠️ Auto-format failed: ${details}${suffix}`;
     }
-    if (formatChanged || fixedCount > 0) {
-        const changedList = [...piChangedFiles].map((changedFile) => toRunnerDisplayPath(cwd, changedFile));
-        const topFiles = changedList
-            .slice(0, 8)
-            .map((f) => "  - " + f)
-            .join("\n");
-        const overflow = changedList.length > 8
-            ? "\n  - ... and " + (changedList.length - 8) + " more"
-            : "";
-        const fileList = changedList.length
-            ? "\nModified files:\n" + topFiles + overflow
-            : "";
-        const targetHasAuthoritativeAttachment = ctx.autofixMode !== "deferred" &&
-            autofixChangedFiles.some((changedFile) => path.resolve(changedFile) === path.resolve(filePath));
-        output += targetHasAuthoritativeAttachment
-            ? `\n\n⚠️ **The attached full content for ${toRunnerDisplayPath(cwd, filePath)} is authoritative after autofix. You MUST re-read any other modified side-effect files before editing them.**${fileList}`
-            : `\n\n⚠️ **File was modified by auto-format/fix. You MUST re-read modified file(s) before making any further edits — the content on disk has changed (whitespace, indentation, quotes, or code). Editing from memory will produce mismatches.**${fileList}`;
-    }
+    // #1590: the notice sentence itself is NOT rendered here. This layer cannot
+    // see the attachment cap or the aggregate budget, so it hands the display
+    // paths to `handleToolResult`, which owns the decision and renders the one
+    // sentence with `renderPostAutofixNotice`.
+    const postAutofixNotice = formatChanged || fixedCount > 0
+        ? {
+            targetPath: toRunnerDisplayPath(cwd, filePath),
+            changedFiles: [...piChangedFiles].map((changedFile) => toRunnerDisplayPath(cwd, changedFile)),
+        }
+        : undefined;
     phase.end("dispatch_lint", {
         hasOutput: !!dispatchResult.output,
         diagnosticCount: dispatchResult.diagnostics.length,
@@ -1048,6 +1122,7 @@ export async function runPipeline(ctx, deps) {
             turnSeq: ctx.telemetry?.turnIndex,
             writeSeq: ctx.telemetry?.writeIndex,
             seqState: ctx.seqState,
+            turnEndCascadeSettleStart: ctx.turnEndCascadeSettleStart,
             fileContent,
             wordIndex: ctx.wordIndex,
             onWordIndexUpdated: ctx.onWordIndexUpdated,
@@ -1072,7 +1147,10 @@ export async function runPipeline(ctx, deps) {
         });
     // --- Final timing + all-clear ---
     const elapsed = Date.now() - pipelineStart;
-    if (!output) {
+    // #1590: `postAutofixNotice` is output this run produces, just rendered a
+    // layer up. Treat it as output here, or a format-only change would newly
+    // gain an "all clear" line it never had while the sentence lived inline.
+    if (!output && !postAutofixNotice) {
         output = buildAllClearOutput(dispatchResult, elapsed, filePath);
     }
     phase.end("total", { hasOutput: !!output });
@@ -1106,12 +1184,55 @@ export async function runPipeline(ctx, deps) {
         inlineBlockerSummary: dispatchResult.hasBlockers
             ? dispatchResult.blockerOutput.trim() || undefined
             : undefined,
+        // #1561 F1: taken from the very diagnostics `blockerOutput` was rendered
+        // from, so the provenance can never disagree with the text it guards. An
+        // untagged diagnostic contributes the literal "unknown", which no verdict
+        // claims coverage for — it pins the entry rather than silently widening
+        // what an LSP check is allowed to clear.
+        inlineBlockerSources: dispatchResult.hasBlockers
+            ? [
+                ...new Set(dispatchResult.blockers.map((d) => d.tool?.trim() || "unknown")),
+            ]
+            : undefined,
+        inlineBlockerLines: dispatchResult.hasBlockers
+            ? dispatchResult.blockers
+                // #1641 review F2: `dispatchResult.blockers` is NOT guaranteed to be
+                // scoped to THIS file — a chart-wide runner (helm-lint, helm-render)
+                // reports blocking diagnostics against other files in the chart
+                // (e.g. `values.yaml`) alongside `ctx.filePath`. The precedent every
+                // per-file runner already follows (dotnet-build.ts, javac.ts) is to
+                // drop cross-file rows before they reach a per-file record; this is
+                // that same filter applied at the aggregation point instead, since
+                // `blockers` is pooled across every runner dispatched for this file.
+                // Without it, a cross-file line count gets attributed to THIS
+                // file's past-EOF check and can demote an in-bounds, fully valid
+                // blocker for content the diagnostic never described.
+                //
+                // #1641 review round 2 (LOW): `path.resolve` equality doesn't fold
+                // case, and an LSP-sourced diagnostic's `filePath` is stamped with
+                // realpath canonical casing (dispatch/runners/lsp.ts ->
+                // normalizeMapKey) while `ctx.filePath` can arrive lowercase-drive
+                // on Windows — the drive-letter class from #1139/#1150. A bare
+                // `path.resolve` equality then drops EVERY LSP blocker line and
+                // this record silently skips the past-EOF gate (fail-open, but
+                // exactly the pre-fix behavior on the surface #1641 targets).
+                // `normalizeEphemeralMapKey` slash-folds and (on win32)
+                // lowercase-folds both sides with no filesystem I/O — cheap enough
+                // for this per-blocker hot-path filter. `pathsEqual` was
+                // deliberately NOT used here: it calls `realpathSync` per
+                // comparison, which this filter cannot afford per blocker.
+                .filter((d) => normalizeEphemeralMapKey(d.filePath) ===
+                normalizeEphemeralMapKey(filePath))
+                .map((d) => d.line)
+                .filter((line) => typeof line === "number")
+            : undefined,
         actionableWarnings,
         codeQualityWarnings,
         diagnostics: dispatchResult.diagnostics,
         formattersUsed,
         fixedCount,
         autofixTools,
+        postAutofixNotice,
         postMutation: ctx.autofixMode !== "deferred" && autofixChangedFiles.some((f) => path.resolve(f) === path.resolve(filePath)) && fileContent !== undefined
             ? { filePath: path.resolve(filePath), content: fileContent, source: "autofix" }
             : undefined,

package/node_modules/pi-lens/dist/clients/post-autofix-notice.js

@@ -0,0 +1,37 @@
+/**
+ * The single post-autofix instruction about a written file (#1590).
+ *
+ * Two layers used to phrase this. `clients/pipeline.ts` claimed "the attached
+ * full content is authoritative" from changed-file membership alone, and
+ * `clients/runtime-tool-result.ts` — the only layer that sees the per-file
+ * attachment cap and the per-command aggregate budget — appended "too large to
+ * attach" for the same file. On a size-capped write the agent got both.
+ *
+ * The wording now lives here, and `handleToolResult` is the only caller: the
+ * pipeline supplies the data (display paths it already resolved) and the layer
+ * that made the attachment decision picks the sentence. Keeping the renderer
+ * out of `pipeline.ts` also keeps it real in tests that mock the pipeline away.
+ */
+/** Render the ONE post-autofix instruction for `decision`. */
+export function renderPostAutofixNotice(notice, decision) {
+    const topFiles = notice.changedFiles
+        .slice(0, 8)
+        .map((f) => "  - " + f)
+        .join("\n");
+    const overflow = notice.changedFiles.length > 8
+        ? "\n  - ... and " + (notice.changedFiles.length - 8) + " more"
+        : "";
+    const fileList = notice.changedFiles.length
+        ? "\nModified files:\n" + topFiles + overflow
+        : "";
+    switch (decision) {
+        case "attached":
+            return `⚠️ **The attached full content for ${notice.targetPath} is authoritative after autofix. You MUST re-read any other modified side-effect files before editing them.**${fileList}`;
+        case "size-capped":
+            return `⚠️ **File was modified by auto-format/fix. You MUST re-read ${notice.targetPath} before making any further edits — the authoritative content is too large to attach.**${fileList}`;
+        case "aggregate-budget-degraded":
+            return `⚠️ **File was modified by auto-format/fix. You MUST re-read ${notice.targetPath} before making any further edits — the aggregate authoritative content for this command is too large to attach.**${fileList}`;
+        default:
+            return `⚠️ **File was modified by auto-format/fix. You MUST re-read modified file(s) before making any further edits — the content on disk has changed (whitespace, indentation, quotes, or code). Editing from memory will produce mismatches.**${fileList}`;
+    }
+}

package/node_modules/pi-lens/dist/clients/project-diagnostics/cache.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { getProjectDataDir } from "../file-utils.js";
 import { writeFileAtomic } from "../atomic-write.js";
 import { readJsonCache } from "../json-cache-read.js";
+import { MTIME_DRIFT_TOLERANCE_MS } from "../blocker-freshness.js";
 // v2: cheap-tier scan now also runs ast-grep-napi (#308); invalidate older
 // snapshots so a pre-ast-grep cache isn't served as complete via refreshRunners=cached.
 export const PROJECT_DIAGNOSTICS_CACHE_VERSION = 2;
@@ -47,7 +48,8 @@ export function writeProjectDiagnosticsDeltaReport(cwd, report) {
 }
 /**
  * Drop diagnostics whose underlying file changed on disk after the snapshot was
- * taken (`mtimeMs > scannedAt`) or no longer exists. The persisted snapshot is a
+ * taken (`mtimeMs > scannedAt + MTIME_DRIFT_TOLERANCE_MS`) or no longer
+ * exists. The persisted snapshot is a
  * cross-session cache served by `lens_diagnostics mode=full refreshRunners=cached`;
  * without this it replays diagnostics the agent has since fixed or for files that
  * were deleted (#298 — "the cache needs to be cleaned before running diagnostics
@@ -56,6 +58,15 @@ export function writeProjectDiagnosticsDeltaReport(cwd, report) {
  * stays a pure reader. Synchronous (a `statSync` per *distinct* file, memoised),
  * since the cached full-mode path is already off the typing hot loop.
  *
+ * The boundary is `mtime > scannedAt + MTIME_DRIFT_TOLERANCE_MS`
+ * (`blocker-freshness.ts`), not a bare `mtime > scannedAt`: #1711 found this
+ * consumer's old +1ms slack did not cover the measured Windows host skew
+ * between a file's mtime and the `Date.now()` read that produces `scannedAt`
+ * (up to ~11.4ms, #1491/#1498) — a same-tick write-then-scan silently
+ * dropped a live finding here, worse than `findingPathFreshness`'s sibling
+ * gate (#1708) since this arm DROPS rather than demotes. Reusing the shared
+ * constant keeps one source of truth for the measured skew.
+ *
  * Fail-safe on an unparseable `scannedAt`: return the snapshot untouched rather
  * than risk dropping live findings on a clock/format anomaly.
  */
@@ -70,8 +81,11 @@ export function reconcileProjectDiagnosticsSnapshot(snapshot) {
             return cached;
         let stale;
         try {
-            // +1ms tolerance: a file scanned at scannedAt has mtime <= scannedAt.
-            stale = fs.statSync(filePath).mtimeMs > scannedAtMs + 1;
+            // MTIME_DRIFT_TOLERANCE_MS: a file scanned at scannedAt, or written
+            // within the tolerance window of the scan timestamp being captured,
+            // has mtime <= scannedAt + MTIME_DRIFT_TOLERANCE_MS.
+            stale =
+                fs.statSync(filePath).mtimeMs > scannedAtMs + MTIME_DRIFT_TOLERANCE_MS;
         }
         catch {
             stale = true; // deleted / unreadable → drop

package/node_modules/pi-lens/dist/clients/project-diagnostics/extractors.js

@@ -1,25 +1,3 @@
-/**
- * Provenance metadata for the heavyweight project analyzers surfaced in
- * `lens_diagnostics mode=full`.
- *
- * NOTE (#585 regression cleanup): this module USED to also own
- * `extractCachedProjectDiagnostics` — a CACHE-ONLY reader that adapted each
- * analyzer's cached result to `ProjectDiagnostic[]` via a parallel `EXTRACTORS`
- * registry. #585 replaced that reader in production with
- * `fetchFreshProjectDiagnostics` (./fresh-fetch.ts), which triggers-or-joins a
- * fresh run instead of settling for a possibly-hours-stale session_start
- * snapshot. The old reader lingered here wired only to a test — a SECOND,
- * dead surfacing path whose registry could (and did) silently diverge from
- * fresh-fetch's `ANALYZER_IDS`: opengrep was registered here but missing there,
- * so opengrep scanned+cached yet never reached the agent (the exact #585-class
- * regression this cleanup removes). The parallel registry is gone; fresh-fetch
- * is the single source of truth (#883).
- *
- * What survives is the honesty metadata (#533): given an analyzer id that
- * fresh-fetch reported `cold` (not applicable / unavailable this run),
- * `warmTriggerFor` names what WOULD warm it, so the rendered note is actionable
- * rather than a bare "not run".
- */
 /**
  * #533: which trigger warms each analyzer, surfaced in the "cold" honesty note
  * so the note is actionable (names what to do), matching the #511/#514 house
@@ -40,3 +18,92 @@ const WARM_TRIGGER = {
 export function warmTriggerFor(analyzerId) {
     return WARM_TRIGGER[analyzerId] ?? "runs at session-start";
 }
+/**
+ * #1623: single formatter for a "not run" lane entry — reused by every
+ * caller that renders `fetchFreshProjectDiagnostics`'s `cold` list (today,
+ * `tools/lens-diagnostics.ts`'s mode=full) so the wording can't drift
+ * per-caller. Prefers the SPECIFIC reason captured at the decision point
+ * (`coldReasons`, ./fresh-fetch.ts) over the generic `warmTriggerFor` guess —
+ * the latter only remains a fallback for a `cold` id this map doesn't cover.
+ */
+export function formatNotRunEntry(analyzerId, coldReasons) {
+    const reason = coldReasons?.[analyzerId];
+    return reason
+        ? `${analyzerId} — not run (${reason})`
+        : `${analyzerId} — not run (${warmTriggerFor(analyzerId)})`;
+}
+/**
+ * #1623: human-readable age, for a lane whose result was served from cache
+ * rather than executed fresh this call (see `cachedAgeMs`, ./fresh-fetch.ts).
+ * Mirrors the granularity an agent actually needs to judge staleness — exact
+ * seconds don't matter, "12m" vs "3h" does.
+ */
+export function formatCacheAge(ms) {
+    // #1623 fix-round F4: `CacheManager.readCache` accepts a missing/corrupt
+    // `meta.timestamp` as a HIT (the timestamp only gates staleness, not
+    // validity), so `Date.now() - new Date(badTimestamp).getTime()` reaches
+    // here as NaN. Rendering "NaNh old" is a worse honesty gap than the one
+    // this whole module exists to close — say the age is unknown instead of
+    // fabricating one. Mirrors the sibling `Number.isFinite` guard in
+    // `./cache.ts`'s `reconcileProjectDiagnosticsSnapshot` (fail-safe on an
+    // unparseable timestamp rather than propagate NaN).
+    if (!Number.isFinite(ms))
+        return "age unknown";
+    if (ms < 0)
+        return "0m";
+    const totalMinutes = Math.round(ms / 60_000);
+    if (totalMinutes < 1)
+        return "under 1m";
+    if (totalMinutes < 60)
+        return `${totalMinutes}m`;
+    const hours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes % 60;
+    return minutes > 0 ? `${hours}h${minutes}m` : `${hours}h`;
+}
+/**
+ * #1623 fix-round F5: the full "<age> old" phrase for a cache-read lane.
+ * Every render call site used to append the literal word " old" after
+ * `formatCacheAge` itself, so a corrupt/missing timestamp's "age unknown"
+ * came out as the ungrammatical "age unknown old" — the exact residual the
+ * issue's tracking comment named. "Old" only makes sense once an age is
+ * actually known, so this is the single place that decides whether to say
+ * it, instead of every caller repeating (and occasionally forgetting) the
+ * same guard.
+ */
+export function formatCacheAgeOld(ms) {
+    const age = formatCacheAge(ms);
+    return Number.isFinite(ms) ? `${age} old` : age;
+}
+/**
+ * #1623 fix-round F1: a "cold" reason for an analyzer whose `ensureAvailable()`
+ * returned false, built from the SAME `AvailabilityOutcome`/`AvailabilityCause`
+ * taxonomy every dispatch-side unavailability message already uses
+ * (`describeUnavailability`, availability-policy.ts) — not a re-guessed
+ * "binary unavailable" for every failure shape.
+ *
+ * `ensureAvailable() === false` collapses at least three distinct causes: a
+ * durable absence (`missing`), a transient probe under an active retry
+ * cooldown (`transient`), and — for govulncheck specifically — a project-trust
+ * install denial the latch never even records (`assertInstallAllowed` returns
+ * before touching it, project-trust.ts). fresh-fetch.ts's govulncheck task
+ * checks trust denial itself, via `projectTrustDenialReason()`, before
+ * falling back to this function. Wording a cooldown as "unavailable" would
+ * repeat, one layer up, exactly the dispatch-layer defect #1467 fixed.
+ */
+export function reasonFromAvailabilityVerdict(tool, verdict) {
+    if (!verdict || verdict.outcome === null)
+        return `${tool} binary unavailable`;
+    const { outcome, cause } = verdict;
+    if (outcome === "transient") {
+        if (cause === "install-retry-exhausted") {
+            return `${tool} install kept timing out and hit its retry ceiling this session (not reported missing)`;
+        }
+        const remainingMs = verdict.retryAtMs - Date.now();
+        const remainingS = remainingMs > 0 ? Math.round(remainingMs / 1000) : 0;
+        return `${tool} availability probe — retry cooldown (${remainingS}s), not a missing install`;
+    }
+    if (outcome === "non-installable") {
+        return `${tool} unavailable on this host (non-installable)`;
+    }
+    return `${tool} binary unavailable`;
+}