@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

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

@@ -0,0 +1,488 @@
+/**
+ * Shared availability policy for tool probes (#1467).
+ *
+ * A `--version` probe answers one question — "can I run this tool right now?" —
+ * and it can fail for two very different reasons:
+ *
+ *   * the tool is **missing**: a durable fact about the machine, worth caching
+ *     for the session and worth an "install it" message;
+ *   * the probe was **transient**: a timeout, an abort, an EAGAIN. That is
+ *     evidence about *this moment*, not about the tool. Caching it as a
+ *     permanent `false` disables a healthy tool for the life of the process,
+ *     and wording it as "not installed" sends the user to reinstall something
+ *     that is already on disk.
+ *
+ * knip hit exactly that: a 5 s host-side probe budget, an event-loop stall that
+ * ate most of it, a latched `false`, and three days of "Knip not available.
+ * Install with: npm install -D knip" over a knip that answered `--version` in
+ * 0.8 s outside the host. This module owns the policy so every client — the
+ * `createAvailabilityChecker` seam, knip, madge, govulncheck, vulture — shares
+ * one taxonomy, one retry rule, and one message split.
+ *
+ * Kept dependency-light on purpose (only the latency logger) so client modules
+ * 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
+ * cooldown: 30 s, 60 s, 120 s … capped at 5 min.
+ */
+export const TRANSIENT_BASE_COOLDOWN_MS = 30_000;
+export const TRANSIENT_MAX_COOLDOWN_MS = 300_000;
+/**
+ * A timeout the host itself caused is not evidence about the tool at all, so it
+ * gets a short fixed cooldown (just enough to avoid a probe storm while the
+ * loop is still stalling) and never escalates.
+ */
+export const HOST_STALL_COOLDOWN_MS = 5_000;
+/**
+ * Host stall, in ms, that has to overlap a probe window before we stop counting
+ * a timeout as evidence about the tool. Well under the smallest probe budget
+ * (1.5 s) so a stall can only ever *soften* a verdict we would otherwise latch.
+ */
+export const HOST_STALL_EVIDENCE_MS = 500;
+/** Never mistake a transient verdict for a durable one. */
+export function isLatchingOutcome(outcome) {
+    return outcome !== "transient";
+}
+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(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.
+ *
+ * The stall arm is the #1467 fix for the measurement itself: the probe budget
+ * is enforced by a HOST-side `setTimeout`, so a stalled event loop expires the
+ * budget while the child is still healthy and mid-startup. When a stall
+ * overlapped the window we keep the outcome transient but re-cause it as
+ * `host-stall`, which shortens the cooldown and — critically — says so in the
+ * 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", evidence };
+    }
+    if (result.failure === "timeout" ||
+        result.failure === "aborted" ||
+        result.failure === "signal" ||
+        result.spawnFailure?.kind === "killed" ||
+        result.spawnFailure?.kind === "timeout" ||
+        errorCode === "EAGAIN" ||
+        errorCode === "EBUSY") {
+        const stalled = (options.hostStallMs ?? 0) >= HOST_STALL_EVIDENCE_MS;
+        return {
+            outcome: "transient",
+            cause: stalled ? "host-stall" : "probe-timeout",
+            evidence,
+        };
+    }
+    // A present command that rejects its version probe (or an EACCES/EINVAL/
+    // UNKNOWN failure) is not repaired by reinstalling it.
+    const outcome = options.unclassifiedFailureOutcome ?? "non-installable";
+    return {
+        outcome,
+        cause: outcome === "missing" ? "not-found" : "probe-rejected",
+        evidence,
+    };
+}
+/**
+ * Accumulate how long the host event loop was blocked while something else was
+ * in flight. A timer scheduled every `intervalMs` that fires late by L ms means
+ * the loop was unavailable for L ms of the window — exactly the time the probe
+ * budget was being spent on the host rather than on the child.
+ *
+ * `unref`'d and cleared on the single settle path, so it can never hold a
+ * print-mode process open (recurring defect shape 4).
+ */
+export function startHostStallSampler(intervalMs = 100) {
+    let stallMs = 0;
+    let last = Date.now();
+    let stopped = false;
+    const timer = setInterval(() => {
+        const now = Date.now();
+        const lateness = now - last - intervalMs;
+        if (lateness > 0)
+            stallMs += lateness;
+        last = now;
+    }, intervalMs);
+    timer?.unref?.();
+    return {
+        stop: () => {
+            if (stopped)
+                return Math.round(stallMs);
+            stopped = true;
+            clearInterval(timer);
+            // A stall in progress when the probe settles is still stall inside the
+            // window; count the tail the interval never got to observe.
+            const tail = Date.now() - last - intervalMs;
+            if (tail > 0)
+                stallMs += tail;
+            return Math.round(stallMs);
+        },
+    };
+}
+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() >= 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;
+        },
+        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, maxCooldownMs);
+            retryAtMs = Date.now() + delay;
+            return delay;
+        },
+        reset() {
+            installGeneration = installRetryGeneration;
+            clearVerdict();
+        },
+        getOutcome: () => outcome,
+        getCause: () => cause,
+        getRetryAtMs: () => effectiveRetryAtMs(),
+        isProvisional: () => provisional,
+        isInstallExhausted: () => {
+            syncInstallGeneration();
+            return installExhausted;
+        },
+    };
+}
+/** True when the verdict came from a probe that never got a fair hearing. */
+export function isTransientDecision(decision) {
+    return decision?.outcome === "transient";
+}
+/**
+ * THE message split. Every "tool X is unavailable" string a user or agent sees
+ * is produced here, so "the probe timed out" can never be worded as "install
+ * it" again. `installHint` is the command that would actually fix a genuinely
+ * missing tool.
+ */
+export function describeUnavailability(options) {
+    const { tool, installHint } = 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)"
+        : "";
+    const retry = options.retryAfterMs
+        ? ` Retrying in ${Math.round(options.retryAfterMs / 1000)}s.`
+        : " It will be retried.";
+    return `${tool} availability probe timed out${elapsed}${stalled}. ${tool} is not reported missing — this is a probe timeout, not a missing install.${retry}`;
+}
+/**
+ * One record per availability DECISION (not per cache hit), so a probe that is
+ * failing is visible in latency.log the same day instead of being inferred from
+ * three days of silence.
+ *
+ * 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({
+        type: "phase",
+        phase: "availability_decision",
+        filePath,
+        durationMs: Math.round(decision.elapsedMs),
+        metadata: {
+            tool: decision.tool,
+            verdict: decision.verdict,
+            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,
+            }),
+            ...(decision.retryAfterMs !== undefined && {
+                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

@@ -0,0 +1,84 @@
+/**
+ * Shared PATH-candidate availability sweep (#1476 Sonar follow-up, S3776).
+ *
+ * `go-client.ts` and `rust-client.ts` resolve their toolchain the same way:
+ * walk a platform candidate list, treat a candidate with a path separator as
+ * an existence check, and probe a bare command with a version flag on a
+ * fixed host-side budget, classifying any failure through the shared policy
+ * so a host stall cannot be mistaken for "the tool is not installed". The
+ * migration to `availability-policy.ts` wrote that sweep out twice, and the
+ * duplication was also what pushed both call sites over the Cognitive
+ * Complexity limit. This is that sweep, written once.
+ */
+import * as fs from "node:fs";
+import { safeSpawnAsync } from "../../../safe-spawn.js";
+import { classifyProbeFailure, startHostStallSampler, } from "./availability-policy.js";
+/**
+ * Walk `candidates` in order. A candidate containing a path separator is
+ * resolved with `fs.existsSync`; a bare command is probed by spawning it with
+ * `probeArgs` on a `timeoutMs` host-side budget. Returns on the first
+ * candidate that answers; a candidate that throws is skipped, matching the
+ * original per-client sweeps.
+ */
+export async function probeAvailabilityCandidates(candidates, probeArgs, timeoutMs) {
+    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,
+                        evidence,
+                    };
+                }
+                continue;
+            }
+            // Host-side budget: measure the loop stall that overlapped the probe so
+            // the shared policy can tell "no toolchain" from "the host was busy".
+            const sampler = startHostStallSampler();
+            let result;
+            let stallMs;
+            try {
+                result = await safeSpawnAsync(candidate, [...probeArgs], {
+                    timeout: timeoutMs,
+                });
+            }
+            finally {
+                stallMs = sampler.stop();
+                hostStallMs += stallMs;
+            }
+            if (!result.error && result.status === 0) {
+                return {
+                    foundPath: candidate,
+                    sawTransient,
+                    transientCause,
+                    hostStallMs,
+                    evidence,
+                };
+            }
+            const classified = classifyProbeFailure(result, {
+                hostStallMs: stallMs,
+                command: candidate,
+            });
+            evidence = classified.evidence;
+            if (classified.outcome === "transient") {
+                sawTransient = true;
+                transientCause = classified.cause;
+            }
+        }
+        catch {
+            // A candidate that throws is one this host does not have — the sweep's
+            // normal case, not an error worth surfacing. The verdict comes from
+            // whether any LATER candidate answers, and a genuine host problem
+            // still reaches the caller as a transient through `classifyProbeFailure`
+            // above rather than through a thrown spawn.
+        }
+    }
+    return { foundPath: null, sawTransient, transientCause, hostStallMs, evidence };
+}