@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/availability-policy.js

@@ -23,6 +23,65 @@
  * can import the policy without pulling in the dispatch/installer graph.
  */
 import { logLatency } from "../../../latency-logger.js";
+/**
+ * Read the evidence off a spawn result, dropping keys it does not carry.
+ *
+ * `command` is worth passing whenever the spawn is NOT the tool the decision is
+ * about — a preflight, a fallback candidate, an interpreter.
+ */
+export function describeProbeEvidence(result, command) {
+    const errno = result.error?.code;
+    return {
+        ...(command !== undefined && { command }),
+        ...(result.status !== undefined && { status: result.status }),
+        ...(result.failure !== undefined && { failure: result.failure }),
+        ...(result.spawnFailure?.kind !== undefined && {
+            spawnFailureKind: result.spawnFailure.kind,
+        }),
+        ...(errno !== undefined && { errno }),
+    };
+}
+/**
+ * Evidence for an install attempt, from what the installer EXPLICITLY recorded.
+ *
+ * The first version of this inferred attempt-ness from the installer's failure
+ * REASON map, and a review proved that inverts the answer in both directions:
+ * that map is written by the kill-switch and install-lock branches and by
+ * nothing on the genuine-failure or success paths, so a policy decline read as a
+ * failed download and every real download failure — the retry candidate this
+ * evidence exists to surface — read as a policy decision. `getInstallAttempt`
+ * now records the outcome at each branch that knows it, and this maps it.
+ *
+ * `declined` and `skipped` both collapse to `not-attempted`, because that is the
+ * distinction a reader acts on; which of the two it was survives in `reason`.
+ *
+ * The fact is passed in rather than fetched here, so the policy module stays
+ * free of the installer graph.
+ */
+export function describeInstallAttempt(attempt, options = {}) {
+    const reason = attempt?.reason?.slice(0, 200);
+    if (options.installedButRejected) {
+        // The install ran and produced a binary the caller then refused. Claiming
+        // `failed` would blame the download for a validation verdict.
+        return {
+            install: "succeeded",
+            installReason: reason ?? "installed binary failed validation",
+        };
+    }
+    if (attempt === undefined)
+        return { install: "not-attempted" };
+    switch (attempt.outcome) {
+        case "succeeded":
+            return { install: "succeeded", ...(reason && { installReason: reason }) };
+        case "failed":
+            return { install: "failed", ...(reason && { installReason: reason }) };
+        default:
+            return {
+                install: "not-attempted",
+                ...(reason && { installReason: reason }),
+            };
+    }
+}
 /**
  * Cooldown after a transient failure. Bounded exponential so a genuinely sick
  * machine is not re-probed every call, while a one-off stall costs at most one
@@ -46,11 +105,78 @@ export const HOST_STALL_EVIDENCE_MS = 500;
 export function isLatchingOutcome(outcome) {
     return outcome !== "transient";
 }
-export function transientRetryDelayMs(attempts, cause) {
+export function transientRetryDelayMs(attempts, cause, 
+/**
+ * Override for `TRANSIENT_MAX_COOLDOWN_MS`. A caller whose own respawn
+ * cadence is shorter than the shared 5-minute ceiling (e.g. an LSP auxiliary
+ * whose idle reset recycles the process well before the ladder maxes out)
+ * must cap its own ladder below that cadence — otherwise a respawn can land
+ * inside a still-cooling-down cache window and start silently offline
+ * (#1535).
+ */
+maxCooldownMs = TRANSIENT_MAX_COOLDOWN_MS) {
     if (cause === "host-stall")
         return HOST_STALL_COOLDOWN_MS;
     const exponent = Math.max(0, attempts - 1);
-    return Math.min(TRANSIENT_MAX_COOLDOWN_MS, TRANSIENT_BASE_COOLDOWN_MS * 2 ** Math.min(exponent, 10));
+    return Math.min(maxCooldownMs, TRANSIENT_BASE_COOLDOWN_MS * 2 ** Math.min(exponent, 10));
+}
+/**
+ * Install-class transient policy (#1497): the operation being retried is a
+ * network install/compile with a ~60 s budget (govulncheck's `go install`),
+ * not a 1.5–5 s version probe. The probe schedule above would re-run that
+ * compile every 5 minutes indefinitely — a ~20% duty cycle on one core with
+ * nothing that ever gives up.
+ *
+ * The cost, stated: the ladder IS `INSTALL_TRANSIENT_COOLDOWNS_MS` — 5 min,
+ * then 10 min, then give up. Three ≤60 s compiles across ~15 minutes, and then
+ * the verdict is terminal FOR THE SESSION: `resetInstallRetryLatches()` at the
+ * next `session_start` (or a successful run) re-arms it, so a genuinely
+ * repaired network still recovers without a host restart. What ends is the
+ * *indefinite* retry, not the recovery #1489 fixed.
+ *
+ * The ceiling is DERIVED from the ladder rather than written beside it: an
+ * earlier revision paired a doubling formula with a 30-minute cap that a
+ * 3-attempt ceiling could never reach, so the stated cost and the real one
+ * disagreed. One list, no arithmetic, nothing unreachable.
+ *
+ * There is no host-stall shortcut here, and install-class failures keep their
+ * own cooldown slot: the retry itself is the expensive part no matter who ate
+ * the budget, so a cheap probe failure must not be able to shorten it.
+ */
+export const INSTALL_TRANSIENT_BASE_COOLDOWN_MS = 300_000;
+/** Cooldown before install retry N, in order. Its length sets the ceiling. */
+export const INSTALL_TRANSIENT_COOLDOWNS_MS = [
+    INSTALL_TRANSIENT_BASE_COOLDOWN_MS,
+    INSTALL_TRANSIENT_BASE_COOLDOWN_MS * 2,
+];
+/** Install attempts allowed per session, including the one that gives up. */
+export const INSTALL_TRANSIENT_MAX_ATTEMPTS = INSTALL_TRANSIENT_COOLDOWNS_MS.length + 1;
+/**
+ * Cooldown owed after `attempts` install-class failures, or **0** when the
+ * ladder is spent — the same "no retry, the verdict is latched" signal
+ * `noteUnavailable` returns.
+ */
+export function installRetryDelayMs(attempts) {
+    return INSTALL_TRANSIENT_COOLDOWNS_MS[Math.max(0, attempts - 1)] ?? 0;
+}
+/**
+ * Session generation for install-class retry state (#1497 review F1).
+ *
+ * The exhausted verdict is durable for a SESSION, but the latches holding it
+ * belong to process-lived client instances (`SecurityScanClient` and friends
+ * are built once in `bootstrap.ts`). Without this, "terminal for the session"
+ * silently became terminal for the process: a repaired network plus a full
+ * `session_start` reset still read exhausted, which is the #1266/#1490/#1535
+ * shape. A counter rather than a latch registry, so nothing has to be
+ * hand-maintained and no latch is retained for the sake of resetting it.
+ */
+let installRetryGeneration = 0;
+/**
+ * Re-arm install-class retries in every latch. Called from `session_start`'s
+ * per-session reset block beside `resetDispatchAvailabilityState()`.
+ */
+export function resetInstallRetryLatches() {
+    installRetryGeneration += 1;
 }
 /**
  * Classify a failed probe into an outcome + cause.
@@ -63,9 +189,10 @@ export function transientRetryDelayMs(attempts, cause) {
  * telemetry, instead of silently blaming the tool.
  */
 export function classifyProbeFailure(result, options = {}) {
+    const evidence = describeProbeEvidence(result, options.command);
     const errorCode = result.error?.code;
     if (result.spawnFailure?.kind === "tool-not-found") {
-        return { outcome: "missing", cause: "not-found" };
+        return { outcome: "missing", cause: "not-found", evidence };
     }
     if (result.failure === "timeout" ||
         result.failure === "aborted" ||
@@ -78,6 +205,7 @@ export function classifyProbeFailure(result, options = {}) {
         return {
             outcome: "transient",
             cause: stalled ? "host-stall" : "probe-timeout",
+            evidence,
         };
     }
     // A present command that rejects its version probe (or an EACCES/EINVAL/
@@ -86,6 +214,7 @@ export function classifyProbeFailure(result, options = {}) {
     return {
         outcome,
         cause: outcome === "missing" ? "not-found" : "probe-rejected",
+        evidence,
     };
 }
 /**
@@ -124,50 +253,159 @@ export function startHostStallSampler(intervalMs = 100) {
         },
     };
 }
-export function createAvailabilityLatch() {
+export function createAvailabilityLatch(options = {}) {
     let available = null;
     let outcome = null;
     let cause = null;
     let retryAtMs = 0;
     let transientAttempts = 0;
+    let installAttempts = 0;
+    let installExhausted = false;
+    // Install-class failures own their own cooldown slot (#1497 review F2). A
+    // cheap probe failure that lands mid-install-cooldown must not be able to
+    // shorten it — the 5 s host-stall shortcut on the probe ladder would
+    // otherwise collapse 5 minutes of install spacing into seconds.
+    let installRetryAtMs = 0;
+    /**
+     * The current `available` verdict is a degraded selection (#1568), held only
+     * until `retryAtMs`. Separate from `available` because it does not change
+     * what the caller is told — the tool IS usable — only how long the answer
+     * may be reused.
+     */
+    let provisional = false;
+    const maxCooldownMs = options.maxCooldownMs ?? TRANSIENT_MAX_COOLDOWN_MS;
+    let installGeneration = installRetryGeneration;
+    function clearVerdict() {
+        available = null;
+        outcome = null;
+        cause = null;
+        retryAtMs = 0;
+        transientAttempts = 0;
+        installAttempts = 0;
+        installExhausted = false;
+        installRetryAtMs = 0;
+        provisional = false;
+    }
+    /**
+     * Fold in any `resetInstallRetryLatches()` that happened since the last
+     * touch. Install-class state is per-session, so a new generation drops the
+     * attempt count and the cooldown; when the exhausted verdict IS the state,
+     * the whole verdict goes with it and the next `read()` returns `null` so the
+     * caller re-probes.
+     */
+    function syncInstallGeneration() {
+        if (installGeneration === installRetryGeneration)
+            return;
+        installGeneration = installRetryGeneration;
+        if (installExhausted) {
+            clearVerdict();
+            return;
+        }
+        installAttempts = 0;
+        installRetryAtMs = 0;
+    }
+    /** The later of the two class cooldowns — the gate `read()` enforces. */
+    function effectiveRetryAtMs() {
+        return Math.max(retryAtMs, installRetryAtMs);
+    }
     return {
         read() {
+            syncInstallGeneration();
+            // A provisional `true` expires exactly like a transient `false`: the
+            // answer was served, the sweep is still owed (#1568).
+            if (available === true) {
+                if (provisional && Date.now() >= effectiveRetryAtMs())
+                    return null;
+                return true;
+            }
             if (available !== false)
                 return available;
+            if (installExhausted)
+                return false;
             if (outcome !== "transient")
                 return false;
-            return Date.now() >= retryAtMs ? null : false;
+            return Date.now() >= effectiveRetryAtMs() ? null : false;
         },
         noteAvailable(nextCause = "ok") {
+            installGeneration = installRetryGeneration;
             available = true;
             outcome = "success";
             cause = nextCause;
             retryAtMs = 0;
             transientAttempts = 0;
+            installAttempts = 0;
+            installExhausted = false;
+            installRetryAtMs = 0;
+            provisional = false;
         },
-        noteUnavailable(nextOutcome, nextCause) {
+        noteProvisionallyAvailable(transientCause) {
+            syncInstallGeneration();
+            available = true;
+            outcome = "success";
+            // The cause names why the verdict is PROVISIONAL, which is the only
+            // thing about it worth recording: `ok` would describe a clean win.
+            cause = transientCause;
+            provisional = true;
+            installAttempts = 0;
+            installExhausted = false;
+            installRetryAtMs = 0;
+            // Same ladder as a transient failure, and the same counter: a preferred
+            // tier that stalls on every sweep must back off rather than buy a fresh
+            // 30 s window each time.
+            transientAttempts += 1;
+            const delay = transientRetryDelayMs(transientAttempts, transientCause, maxCooldownMs);
+            retryAtMs = Date.now() + delay;
+            return delay;
+        },
+        noteUnavailable(nextOutcome, nextCause, opts) {
+            syncInstallGeneration();
             available = false;
             outcome = nextOutcome;
             cause = nextCause;
+            provisional = false;
             if (isLatchingOutcome(nextOutcome)) {
                 retryAtMs = 0;
+                installRetryAtMs = 0;
                 return 0;
             }
+            if (opts?.operationClass === "install") {
+                installAttempts += 1;
+                const installDelay = installRetryDelayMs(installAttempts);
+                if (installDelay === 0) {
+                    // Terminal for the session (#1497): the caller reads the 0 as
+                    // "latched" and must surface it, because the user-visible symptom
+                    // of an unbounded install retry is a busy core, not a missing tool.
+                    // The cause carries that, so no describe path can promise a retry
+                    // that will not happen before the next session (review F5).
+                    installExhausted = true;
+                    cause = "install-retry-exhausted";
+                    retryAtMs = 0;
+                    installRetryAtMs = 0;
+                    return 0;
+                }
+                // Install-class keeps its OWN slot: a cheap probe failure landing
+                // inside this window (host-stall's 5 s shortcut, say) must not be
+                // able to pull the next 60 s compile forward (review F2).
+                installRetryAtMs = Date.now() + installDelay;
+                return installDelay;
+            }
             transientAttempts += 1;
-            const delay = transientRetryDelayMs(transientAttempts, nextCause);
+            const delay = transientRetryDelayMs(transientAttempts, nextCause, maxCooldownMs);
             retryAtMs = Date.now() + delay;
             return delay;
         },
         reset() {
-            available = null;
-            outcome = null;
-            cause = null;
-            retryAtMs = 0;
-            transientAttempts = 0;
+            installGeneration = installRetryGeneration;
+            clearVerdict();
         },
         getOutcome: () => outcome,
         getCause: () => cause,
-        getRetryAtMs: () => retryAtMs,
+        getRetryAtMs: () => effectiveRetryAtMs(),
+        isProvisional: () => provisional,
+        isInstallExhausted: () => {
+            syncInstallGeneration();
+            return installExhausted;
+        },
     };
 }
 /** True when the verdict came from a probe that never got a fair hearing. */
@@ -185,6 +423,12 @@ export function describeUnavailability(options) {
     if (options.outcome !== "transient") {
         return `${tool} not available. Install with: ${installHint}`;
     }
+    if (options.cause === "install-retry-exhausted") {
+        // A transient outcome whose retries are spent. The generic transient arm
+        // below ends in "It will be retried", which nothing will do before the
+        // next session — so this case describes itself instead (#1497 review F5).
+        return `${tool} install kept timing out and reached its retry ceiling (${INSTALL_TRANSIENT_MAX_ATTEMPTS} attempts). ${tool} is not reported missing — the install is not being retried again this session, and recovers at the next session. To install it now: ${installHint}`;
+    }
     const elapsed = options.elapsedMs ? ` after ${options.elapsedMs}ms` : "";
     const stalled = options.cause === "host-stall"
         ? " (the pi host event loop stalled during the probe window, so the budget expired on the host side)"
@@ -201,6 +445,12 @@ export function describeUnavailability(options) {
  *
  * Bounded by construction: the seam probes each tool at most once per cwd per
  * session generation, plus once per expired transient cooldown.
+ *
+ * Exception: a consumer whose own respawn cadence can be shorter than its
+ * cooldown ladder may deliberately ALSO log on a still-cooling cache hit, so
+ * a respawn landing inside that window isn't silently unobservable — see
+ * `clients/zizmor-config.ts`'s `resolveZizmorGitHubToken` (#1535). That is an
+ * opt-in per caller, not a change to this function's own bound.
  */
 export function logAvailabilityDecision(decision, filePath = "<pi-lens>") {
     logLatency({
@@ -214,6 +464,12 @@ export function logAvailabilityDecision(decision, filePath = "<pi-lens>") {
             outcome: decision.outcome,
             cause: decision.cause,
             latched: decision.latched,
+            ...(decision.classifiedBy !== undefined && {
+                classifiedBy: decision.classifiedBy,
+            }),
+            // The raw facts sit beside the verdict they produced, so a `missing` row
+            // can be read as justified or not without re-running anything (#1500).
+            ...(decision.evidence !== undefined && { evidence: decision.evidence }),
             ...(decision.hostStallMs !== undefined && {
                 hostStallMs: decision.hostStallMs,
             }),
@@ -221,6 +477,12 @@ export function logAvailabilityDecision(decision, filePath = "<pi-lens>") {
                 retryAfterMs: decision.retryAfterMs,
             }),
             ...(decision.budgetMs !== undefined && { budgetMs: decision.budgetMs }),
+            ...(decision.provisional === true && { provisional: true }),
+            ...(decision.unreachablePreferred !== undefined && {
+                unreachablePreferred: decision.unreachablePreferred,
+            }),
+            ...(decision.retained === true && { retained: true }),
+            ...(decision.servedFromCooldown === true && { servedFromCooldown: true }),
         },
     });
 }

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/candidate-probe.js

@@ -24,11 +24,18 @@ export async function probeAvailabilityCandidates(candidates, probeArgs, timeout
     let sawTransient = false;
     let transientCause = "probe-timeout";
     let hostStallMs = 0;
+    let evidence;
     for (const candidate of candidates) {
         try {
             if (candidate.includes("\\") || candidate.includes("/")) {
                 if (fs.existsSync(candidate)) {
-                    return { foundPath: candidate, sawTransient, transientCause, hostStallMs };
+                    return {
+                        foundPath: candidate,
+                        sawTransient,
+                        transientCause,
+                        hostStallMs,
+                        evidence,
+                    };
                 }
                 continue;
             }
@@ -47,14 +54,22 @@ export async function probeAvailabilityCandidates(candidates, probeArgs, timeout
                 hostStallMs += stallMs;
             }
             if (!result.error && result.status === 0) {
-                return { foundPath: candidate, sawTransient, transientCause, hostStallMs };
+                return {
+                    foundPath: candidate,
+                    sawTransient,
+                    transientCause,
+                    hostStallMs,
+                    evidence,
+                };
             }
-            const { outcome, cause } = classifyProbeFailure(result, {
+            const classified = classifyProbeFailure(result, {
                 hostStallMs: stallMs,
+                command: candidate,
             });
-            if (outcome === "transient") {
+            evidence = classified.evidence;
+            if (classified.outcome === "transient") {
                 sawTransient = true;
-                transientCause = cause;
+                transientCause = classified.cause;
             }
         }
         catch {
@@ -65,5 +80,5 @@ export async function probeAvailabilityCandidates(candidates, probeArgs, timeout
             // above rather than through a thrown spawn.
         }
     }
-    return { foundPath: null, sawTransient, transientCause, hostStallMs };
+    return { foundPath: null, sawTransient, transientCause, hostStallMs, evidence };
 }