@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/security-scan-client.js

@@ -12,11 +12,73 @@
  *
  * Refs: #130, #131, #132
  */
+import * as path from "node:path";
 import { createSubsystemLogger } from "./extension-log.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { classifyProbeFailure, createAvailabilityLatch, describeInstallAttempt, describeProbeEvidence, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 export class SecurityScanClient {
     toolName;
-    available = null;
+    /**
+     * Availability memo, backed by the shared transient-aware latch (#1467).
+     *
+     * Assigning `false` still means "durable: this machine does not have the
+     * tool" — every existing subclass write keeps its meaning. A transient
+     * failure must expire instead: `probeVersion` latches its own transient
+     * verdicts (#1501), and any other transient failure (a scan or install
+     * timeout) goes through `markTransientlyUnavailable`, so the tool can come
+     * back without a host restart.
+     */
+    availabilityLatch = createAvailabilityLatch();
+    get available() {
+        return this.availabilityLatch.read();
+    }
+    set available(value) {
+        if (value === true) {
+            this.availabilityLatch.noteAvailable();
+            return;
+        }
+        if (value !== false) {
+            this.availabilityLatch.reset();
+            return;
+        }
+        this.availabilityLatch.noteUnavailable("missing", "not-found");
+        this.logDurableAbsence();
+    }
+    /**
+     * Latch a durable absence WITH the facts behind it. Prefer this over
+     * `available = false` wherever the call site knows what actually failed — a
+     * `missing` row carrying `install: "failed"` is a retry candidate, one
+     * carrying `install: "not-attempted"` is a policy decision, and a bare one is
+     * a plain absence. Only the record can tell them apart.
+     */
+    noteDurableAbsence(evidence, options = {}) {
+        this.availabilityLatch.noteUnavailable("missing", "not-found");
+        this.logDurableAbsence(evidence, options.elapsedMs);
+    }
+    /**
+     * One record per durable-absence ASSERTION, whether or not the call site had
+     * evidence. Before this, `available = false` after a failed install was a
+     * silent latch: the tool went quiet for the session with nothing in
+     * latency.log to audit (#1500). Bounded — the verdict latches, so at most one
+     * row per client per session.
+     *
+     * `elapsedMs` is whatever the caller measured (an install attempt's duration);
+     * there is no probe here, so it is 0 unless the caller has something real.
+     */
+    logDurableAbsence(evidence, elapsedMs = 0) {
+        logAvailabilityDecision({
+            tool: this.toolName,
+            verdict: "unavailable",
+            outcome: "missing",
+            cause: "not-found",
+            elapsedMs,
+            latched: true,
+            classifiedBy: "caller",
+            ...(evidence !== undefined && { evidence }),
+        });
+    }
+    /** Outcome of the most recent `probeVersion` call. */
+    lastProbeOutcome = null;
     ensureInFlight = null;
     inFlight = new Map();
     binaryPath = null;
@@ -51,18 +113,128 @@ export class SecurityScanClient {
     }
     /**
      * Spawn `toolName <versionArgs>` and report whether it answered cleanly.
-     * Does NOT mutate `this.available` — callers decide what a hit/miss means.
+     * Classifies the failure (`lastProbeOutcome`) and emits one
+     * availability-decision record, so a probe that keeps timing out is visible
+     * in latency.log rather than inferred from silence (#1467).
+     *
+     * Latch ownership is split by outcome: success and durable failures leave
+     * `this.available` to the caller (a missing binary may still be
+     * auto-installed), while a TRANSIENT failure is latched by the seam itself
+     * with its cooldown — the retry schedule only exists once the latch owns
+     * the verdict, and the record is incomplete without it (#1501). Callers
+     * must not re-mark a probe transient (a second noteUnavailable would
+     * double-escalate the cooldown).
      */
     async probeVersion(versionArgs) {
-        const probe = await safeSpawnAsync(this.toolName, versionArgs, {
-            timeout: 5000,
-        });
+        const sampler = startHostStallSampler();
+        const startedAt = Date.now();
+        let probe;
+        let hostStallMs;
+        try {
+            probe = await safeSpawnAsync(this.toolName, versionArgs, {
+                timeout: 5000,
+            });
+        }
+        finally {
+            hostStallMs = sampler.stop();
+        }
+        const elapsedMs = Date.now() - startedAt;
         if (!probe.error && probe.status === 0) {
+            this.lastProbeOutcome = "success";
             this.log(`${this.toolName} found: ${probe.stdout.trim().split("\n")[0]}`);
+            logAvailabilityDecision({
+                tool: this.toolName,
+                verdict: "available",
+                outcome: "success",
+                cause: "ok",
+                elapsedMs,
+                latched: true,
+                hostStallMs,
+                budgetMs: 5000,
+                classifiedBy: "probe",
+                evidence: describeProbeEvidence(probe),
+            });
             return true;
         }
+        const { outcome, cause, evidence } = classifyProbeFailure(probe, {
+            hostStallMs,
+        });
+        this.lastProbeOutcome = outcome;
+        // A transient verdict's record is incomplete without the retry schedule,
+        // and the schedule only exists once the latch owns the verdict — so the
+        // seam writes the expiring verdict itself, at log time (#1501). Durable
+        // outcomes stay caller-owned (a missing binary may still be installed).
+        const retryAfterMs = outcome === "transient"
+            ? this.availabilityLatch.noteUnavailable("transient", cause)
+            : 0;
+        logAvailabilityDecision({
+            tool: this.toolName,
+            verdict: "unavailable",
+            outcome,
+            cause,
+            elapsedMs,
+            latched: outcome !== "transient",
+            hostStallMs,
+            ...(retryAfterMs > 0 && { retryAfterMs }),
+            budgetMs: 5000,
+            classifiedBy: "probe",
+            evidence,
+        });
         return false;
     }
+    /** True when the last probe failed for a reason that is not the tool's fault. */
+    probeWasTransient() {
+        return this.lastProbeOutcome === "transient";
+    }
+    /**
+     * Record a non-durable unavailability: the verdict expires after a cooldown
+     * and the next `ensureAvailable` re-probes.
+     *
+     * Returns that cooldown in ms so the caller can put it in its decision
+     * record. A latch you can read in `latency.log` without the retry schedule
+     * beside it only tells you the tool is off, not when it comes back.
+     *
+     * For NON-probe transient failures only (scan/install timeouts):
+     * `probeVersion` latches and logs its own transient verdicts (#1501), so
+     * re-marking one here would double-escalate the cooldown.
+     *
+     * Pass `opts.operationClass: "install"` when the failed operation was a
+     * network install/compile rather than a cheap probe (#1497): the retry
+     * escalates on the install-class schedule, on its OWN cooldown slot (a
+     * cheap probe failure can never shorten it), and latches for the session at
+     * the attempt ceiling, in which case the return is 0 (latched).
+     */
+    markTransientlyUnavailable(cause = "probe-timeout", opts) {
+        return this.availabilityLatch.noteUnavailable("transient", cause, opts);
+    }
+    /**
+     * The cause the LATCH settled on, which is not always the cause the caller
+     * passed in: at the install-class ceiling the latch rewrites it to
+     * `install-retry-exhausted` (#1497). A decision record built from the
+     * caller's own cause would say `probe-timeout` for a verdict that is no
+     * longer being retried, so the record reads it back from here.
+     */
+    latchedCause() {
+        return this.availabilityLatch.getCause();
+    }
+    /**
+     * #1623: public window onto the availability verdict for callers OUTSIDE
+     * the dispatch graph (mode=full's fresh-fetch) that need to say WHY
+     * `ensureAvailable()` most recently returned false — using the SAME
+     * `AvailabilityOutcome`/`AvailabilityCause` taxonomy every dispatch-side
+     * message is built from, rather than a re-guessed "binary unavailable"
+     * that can't tell a transient retry-cooldown probe from a durable absence.
+     * `latchedCause()`/`lastProbeOutcome` above stay `protected` for
+     * dispatch-internal callers; this is the one public seam for everyone
+     * else.
+     */
+    getAvailabilityVerdict() {
+        return {
+            outcome: this.availabilityLatch.getOutcome(),
+            cause: this.availabilityLatch.getCause(),
+            retryAtMs: this.availabilityLatch.getRetryAtMs(),
+        };
+    }
     /**
      * Standard availability path for the GitHub-release tools (gitleaks, trivy):
      * PATH probe first, then fall back to the pi-lens installer's `ensureTool`.
@@ -73,17 +245,61 @@ export class SecurityScanClient {
             this.available = true;
             return true;
         }
+        if (this.probeWasTransient()) {
+            // A timed-out probe is not evidence the tool is absent, so it must not
+            // trigger an install NOR latch a permanent `false`. probeVersion has
+            // already recorded the expiring verdict and its retry schedule
+            // (#1501) — re-marking it here would double-escalate the cooldown.
+            this.log(`${this.toolName} availability probe timed out; not installing, will retry`);
+            return false;
+        }
         this.log(`${this.toolName} not found, attempting auto-install`);
-        const { ensureTool } = await import("./installer/index.js");
+        const { ensureTool, getInstallAttempt } = await import("./installer/index.js");
+        const installStartedAt = Date.now();
         const installed = await ensureTool(this.toolName);
         if (!installed) {
-            this.log(`${this.toolName} auto-install failed`);
-            this.available = false;
+            // #1500: this classification is ASSERTED, not derived. It is justified —
+            // the probe already classified a genuine absence, and a failed repair
+            // leaves the tool absent — but the install failure has no taxonomy of
+            // its own, so a network blip and a permanently unavailable release look
+            // identical from here. Record what happened rather than only the verdict.
+            //
+            // `ensureTool` answers the same empty result whether it TRIED and failed
+            // or declined to try (auto-install off, project trust denied), so the
+            // attempt is read from the reason it records rather than assumed — the
+            // review found `install: "failed"` being written for attempts that never
+            // happened.
+            const attempt = getInstallAttempt(this.toolName);
+            this.log(attempt?.outcome === "failed"
+                ? `${this.toolName} auto-install failed: ${attempt.reason ?? "unknown reason"}`
+                : `${this.toolName} auto-install did not run: ${attempt?.reason ?? "no attempt recorded"}`);
+            this.noteDurableAbsence(describeInstallAttempt(attempt), {
+                elapsedMs: Date.now() - installStartedAt,
+            });
             return false;
         }
         this.binaryPath = installed;
         this.available = true;
         this.log(`${this.toolName} auto-installed at ${installed}`);
+        // The probe already wrote a latched `unavailable` row (#1500's durable
+        // assertion doesn't fire here — install SUCCEEDED — but probeVersion's
+        // verdict still did, before this call ever ran). Without a compensating
+        // row, the durable record says the lane is off when it just came back
+        // on: the exact defect #1606 was filed over.
+        logAvailabilityDecision({
+            tool: this.toolName,
+            verdict: "available",
+            outcome: "success",
+            cause: "ok",
+            elapsedMs: Date.now() - installStartedAt,
+            latched: true,
+            classifiedBy: "caller",
+            evidence: {
+                install: "succeeded",
+                binary: path.basename(installed),
+                source: "managed-dir",
+            },
+        });
         return true;
     }
     /**

package/node_modules/pi-lens/dist/clients/sg-runner.js

@@ -12,6 +12,8 @@ import { getSgCommand, resolveManagedToolClient, } from "./dispatch/runners/util
 import { getProjectIgnoreGlobs } from "./file-utils.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { createSingleFlight } from "./single-flight.js";
+import { classifyProbeFailure, describeInstallAttempt, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 /**
  * Build the `bash -c` argv that runs `cmd` with `allArgs` as POSITIONAL
  * parameters. The script is the constant `"$0" "$@"`, so bash re-emits the
@@ -33,6 +35,8 @@ function sgExcludeArgsForProject(rootDir) {
     ]);
 }
 const DEFAULT_EXEC_TIMEOUT_MS = 30_000;
+/** Budget for a single `--version` candidate probe, ms. */
+const PROBE_TIMEOUT_MS = 5_000;
 const MAX_SG_OUTPUT_BYTES = 8 * 1024 * 1024;
 /**
  * Format metavariable captures for display below a match line.
@@ -94,8 +98,58 @@ export class SgRunner {
     log;
     sgPath = null;
     sgArgsPrefix = [];
-    available = null;
-    ensureInFlight = null;
+    /**
+     * Availability memo, backed by the shared transient-aware latch (#1476).
+     *
+     * Before this, one failed sweep over every candidate — timeouts included —
+     * latched `false` for the life of the process AND ran a full auto-install
+     * first. A host stall during warm-up therefore both disabled ast-grep until
+     * restart and paid for an install nobody needed.
+     */
+    availabilityLatch = createAvailabilityLatch();
+    /**
+     * At-most-one sweep in flight, via the shared primitive (#1753). One
+     * instance owns one question, so the key is a constant.
+     */
+    ensureFlight = createSingleFlight();
+    /**
+     * Whether a DIRECT candidate — one that would have been ast-grep itself —
+     * failed for a transient reason in the current sweep. Only these block the
+     * install: a slow `npx` says nothing about whether ast-grep is on this
+     * machine, and letting it block turned "ast-grep is genuinely absent on a
+     * slow host" into "ast-grep is never installed and npx is re-spawned every
+     * sweep, forever".
+     */
+    sweepSawTransient = false;
+    sweepTransientCause = "probe-timeout";
+    /**
+     * The DIRECT candidates that were unreachable, in ask order (#1568).
+     *
+     * The sweep returns at the first candidate that answers, so at the moment of
+     * a win this is exactly the set of preferred tiers the winner did not beat on
+     * the merits. Fallbacks are excluded on purpose: `npx` is asked before the
+     * global-bin and platform-package tiers, and a slow `npx` says nothing about
+     * a winner that is a real binary.
+     *
+     * Basenames, because a candidate can be an absolute global-bin or
+     * platform-package path and this list is written to latency.log (#1568
+     * review F3).
+     */
+    sweepUnreachable = [];
+    /** A transient on the npx fallback: not evidence, but not nothing either. */
+    sweepFallbackTransient = false;
+    sweepFallbackCause = "probe-timeout";
+    /** Host stall summed over every probe of the current sweep, ms. */
+    sweepHostStallMs = 0;
+    /**
+     * Candidates — direct or fallback — that this sweep probed and found
+     * DURABLY missing (real ENOENT/non-installable, not a stall) (#1593). The
+     * retained-arm fallback below only sees whether SOME candidate stalled; this
+     * list lets it also check whether the memoized winner itself is one of the
+     * candidates this very sweep just disproved, rather than re-serving a
+     * command that ENOENTed a moment ago because an unrelated sibling stalled.
+     */
+    sweepDurablyMissing = [];
     constructor(verbose = false) {
         this.log = verbose
             ? createSubsystemLogger("sg-runner")
@@ -104,38 +158,44 @@ export class SgRunner {
     /**
      * Check if ast-grep CLI is available, auto-install if not.
      *
-     * Re-entrancy safe: concurrent first-time callers share a single
-     * `ensureInFlight` promise so probing/auto-install isn't duplicated
-     * across session-start tasks. Mirrors the dedupe pattern in
-     * `KnipClient.ensureAvailable` and `DependencyChecker.ensureAvailable`.
+     * Re-entrancy safe: concurrent first-time callers share one flight, so
+     * probing/auto-install isn't duplicated across session-start tasks. The
+     * share and the clear-in-finally belong to `singleFlight` (#1753); this
+     * method owns only the latch short-circuit above it. The sweep-local
+     * bookkeeping `doEnsureAvailable` resets on entry is untouched — it is
+     * per-sweep state, not concurrency state.
      */
     async ensureAvailable() {
-        // Fast path: already checked.
-        if (this.available !== null)
-            return this.available;
-        if (this.ensureInFlight)
-            return this.ensureInFlight;
-        this.ensureInFlight = this.doEnsureAvailable();
-        try {
-            return await this.ensureInFlight;
-        }
-        finally {
-            this.ensureInFlight = null;
-        }
+        // Fast path: already decided. `read()` returns null when the last verdict
+        // was transient and its cooldown expired, which re-enters the sweep.
+        const memo = this.availabilityLatch.read();
+        if (memo !== null)
+            return memo;
+        return this.ensureFlight.run("ast-grep", () => this.doEnsureAvailable());
     }
     async doEnsureAvailable() {
+        const startedAt = Date.now();
+        this.sweepSawTransient = false;
+        this.sweepTransientCause = "probe-timeout";
+        this.sweepUnreachable = [];
+        this.sweepFallbackTransient = false;
+        this.sweepFallbackCause = "probe-timeout";
+        this.sweepHostStallMs = 0;
+        this.sweepDurablyMissing = [];
         // Step 1: PATH — canonical binary names + npx fallback.
         // Prefer ast-grep over sg on Linux: /usr/bin/sg is util-linux, not ast-grep.
         const pathCommand = await this.probeCommandCandidates([
             { cmd: "ast-grep", argsPrefix: [] },
             { cmd: "sg", argsPrefix: [] },
-            { cmd: "npx", argsPrefix: ["--no", "--", "ast-grep"] },
+            // `npx --no -- ast-grep` starts a Node process before it can answer, so
+            // it is the candidate most likely to blow a 5 s budget on a cold or busy
+            // box. Marked a fallback so its timeout cannot veto the install.
+            { cmd: "npx", argsPrefix: ["--no", "--", "ast-grep"], fallback: true },
         ]);
         if (pathCommand) {
             this.sgPath = pathCommand.cmd;
             this.sgArgsPrefix = pathCommand.argsPrefix;
-            this.available = true;
-            this.log(`ast-grep found on PATH: ${pathCommand.cmd}`);
+            this.noteAvailable(startedAt, `ast-grep found on PATH: ${pathCommand.cmd}`);
             return true;
         }
         // Step 1b: any package manager's global bin dir (npm/pnpm/yarn/bun).
@@ -147,8 +207,7 @@ export class SgRunner {
             if (globalBin && (await this.probeCommand(globalBin, []))) {
                 this.sgPath = globalBin;
                 this.sgArgsPrefix = [];
-                this.available = true;
-                this.log(`ast-grep found in global bin: ${globalBin}`);
+                this.noteAvailable(startedAt, `ast-grep found in global bin: ${globalBin}`);
                 return true;
             }
         }
@@ -159,8 +218,7 @@ export class SgRunner {
         if (platformBinary) {
             this.sgPath = platformBinary;
             this.sgArgsPrefix = [];
-            this.available = true;
-            this.log(`ast-grep found via platform package: ${platformBinary}`);
+            this.noteAvailable(startedAt, `ast-grep found via platform package: ${platformBinary}`);
             return true;
         }
         // Step 3: Homebrew (macOS only).
@@ -169,10 +227,36 @@ export class SgRunner {
             if (brewBinary) {
                 this.sgPath = brewBinary;
                 this.sgArgsPrefix = [];
-                this.available = true;
-                this.log(`ast-grep found via Homebrew: ${brewBinary}`);
+                this.noteAvailable(startedAt, `ast-grep found via Homebrew: ${brewBinary}`);
+                return true;
+            }
+        }
+        // A timeout on a DIRECT candidate means the machine answered, not the tool
+        // (#1476). Installing ast-grep because the host event loop stalled is a
+        // heavyweight reaction to a hiccup, and latching the result disabled the
+        // tool until restart. Retry the sweep later instead.
+        //
+        // The npx fallback is deliberately NOT part of this test. Gating the
+        // install on it regressed the very host this change targets: a slow box
+        // with no ast-grep timed out `npx --no -- ast-grep` every sweep, so the
+        // install below was never reached and the slow npx was re-spawned on each
+        // escalating retry instead — worse than the latch it replaced.
+        if (this.sweepSawTransient) {
+            // Nothing answered, transiently, while we are still holding a command a
+            // previous provisional sweep proved working. Discarding it here would
+            // run #1476 backwards — a timeout erasing a positive result — and it
+            // would send the sweep on to Step 4 to install a tool that is already
+            // runnable. Keep the winner and re-arm the cooldown (#1568 review F1).
+            // #1593: a sibling tier stalling this sweep is not license to re-serve
+            // a winner that THIS SAME sweep just proved durably missing.
+            if (this.availabilityLatch.isProvisional() &&
+                this.sgPath &&
+                !this.sweepDurablyMissing.includes(this.sgPath)) {
+                this.noteAvailable(startedAt, `ast-grep re-probe stalled; keeping ${this.sgPath}`, { retained: true });
                 return true;
             }
+            this.log("ast-grep availability probe timed out; will retry (not installing)");
+            return this.noteUnavailable(startedAt, "transient", this.sweepTransientCause);
         }
         // Step 4: install via the typed shared seam, then validate the returned
         // absolute binary before publishing it.
@@ -185,11 +269,101 @@ export class SgRunner {
         if (installed.outcome === "success") {
             this.sgPath = installed.value;
             this.sgArgsPrefix = [];
-            this.available = true;
-            this.log(`ast-grep auto-installed: ${installed.value}`);
+            this.noteAvailable(startedAt, `ast-grep auto-installed: ${installed.value}`);
             return true;
         }
-        this.available = false;
+        // The install failed AND the npx fallback never got a fair hearing, so
+        // "ast-grep is not installed" is not a fact yet. Expire the verdict.
+        if (this.sweepFallbackTransient) {
+            return this.noteUnavailable(startedAt, "transient", this.sweepFallbackCause);
+        }
+        // #1500: ASSERTED, not derived — and justified, because every candidate
+        // probe answered "not found", so the absence is real. What the install did
+        // is recorded as evidence rather than folded into the verdict: it is the one
+        // fact separating "never installable here" from "the download failed", and
+        // from "no install was attempted at all" (auto-install off, trust denied,
+        // or an attempt already suppressed this session).
+        const { getInstallAttempt } = await import("./installer/index.js");
+        return this.noteUnavailable(startedAt, "missing", "not-found", describeInstallAttempt(getInstallAttempt("ast-grep"), {
+            installedButRejected: installed.outcome === "non-installable",
+        }), "caller");
+    }
+    /**
+     * Record a successful sweep, with one decision record.
+     *
+     * The win is latched for the session UNLESS a direct candidate ahead of it
+     * was unreachable (#1568). `sweepSawTransient` is set only by candidates the
+     * sweep already asked, and the sweep returns at the first one that answers,
+     * so at this point the flag means "a tier the winner is supposed to lose to
+     * never got a fair hearing". Latching that pinned the session to
+     * `npx --no -- ast-grep` — a Node start per invocation — over a healthy
+     * ast-grep on PATH, until the next restart. Provisional instead: served now,
+     * re-swept once the stalled tier's cooldown expires.
+     *
+     * The install arm cannot reach here provisionally: `doEnsureAvailable`
+     * returns before Step 4 whenever `sweepSawTransient` is set.
+     *
+     * `retained` marks the other provisional case (#1568 review F1): no candidate
+     * answered at all, and the winner being reported is the one the previous
+     * sweep found, kept rather than discarded on a timeout.
+     */
+    noteAvailable(startedAt, message, opts = {}) {
+        const provisional = this.sweepSawTransient;
+        let retryAfterMs = 0;
+        if (provisional) {
+            retryAfterMs = this.availabilityLatch.noteProvisionallyAvailable(this.sweepTransientCause);
+        }
+        else {
+            this.availabilityLatch.noteAvailable();
+        }
+        this.log(message);
+        logAvailabilityDecision({
+            tool: "ast-grep",
+            verdict: "available",
+            outcome: "success",
+            cause: provisional ? this.sweepTransientCause : "ok",
+            elapsedMs: Date.now() - startedAt,
+            latched: !provisional,
+            hostStallMs: this.sweepHostStallMs,
+            budgetMs: PROBE_TIMEOUT_MS,
+            ...(provisional && {
+                provisional: true,
+                unreachablePreferred: [...this.sweepUnreachable],
+                ...(opts.retained === true && { retained: true }),
+                ...(retryAfterMs > 0 && { retryAfterMs }),
+            }),
+        });
+    }
+    /**
+     * Record a failed sweep. A `transient` outcome expires after a bounded
+     * cooldown; anything else is remembered for the session, as before. The
+     * elapsed/stall numbers describe the WHOLE sweep, because the verdict is
+     * about the sweep rather than any single candidate — reporting zero here
+     * would erase the evidence that cracked #1467.
+     */
+    noteUnavailable(startedAt, outcome, cause, evidence, 
+    /**
+     * How this arm reached its verdict. Per arm on purpose (#1500 review): the
+     * sweep's own transient/missing conclusions ARE derived from candidate
+     * probes, but the post-install assertion is not, and hardcoding `"probe"`
+     * here labelled an assertion as a derivation — the exact confusion the
+     * field was added to remove.
+     */
+    classifiedBy = "probe") {
+        const retryAfterMs = this.availabilityLatch.noteUnavailable(outcome, cause);
+        logAvailabilityDecision({
+            tool: "ast-grep",
+            verdict: "unavailable",
+            outcome,
+            cause,
+            elapsedMs: Date.now() - startedAt,
+            latched: outcome !== "transient",
+            hostStallMs: this.sweepHostStallMs,
+            ...(retryAfterMs > 0 && { retryAfterMs }),
+            budgetMs: PROBE_TIMEOUT_MS,
+            classifiedBy,
+            ...(evidence !== undefined && { evidence }),
+        });
         return false;
     }
     /**
@@ -270,17 +444,55 @@ export class SgRunner {
     isAstGrepVersionOutput(output) {
         return /\bast[- ]grep\b/i.test(output);
     }
-    async probeCommand(cmd, argsPrefix) {
-        const result = await safeSpawnAsync(cmd, [...argsPrefix, "--version"], {
-            timeout: 5000,
-        });
-        return (!result.error &&
+    /**
+     * Probe one candidate. A failure is CLASSIFIED, not merely counted: a
+     * timeout/abort marks the whole sweep transient so the caller retries later
+     * instead of installing and latching. A command that answers but is not
+     * ast-grep (Linux `/usr/bin/sg` is util-linux) is a durable no.
+     */
+    async probeCommand(cmd, argsPrefix, fallback = false) {
+        // Host-side budget: measure the loop stall that overlapped the window so
+        // the classifier can tell "the tool is slow" from "the host was busy".
+        const sampler = startHostStallSampler();
+        let result;
+        let hostStallMs;
+        try {
+            result = await safeSpawnAsync(cmd, [...argsPrefix, "--version"], {
+                timeout: PROBE_TIMEOUT_MS,
+            });
+        }
+        finally {
+            hostStallMs = sampler.stop();
+            this.sweepHostStallMs += hostStallMs;
+        }
+        if (!result.error &&
             result.status === 0 &&
-            this.isAstGrepVersionOutput(`${result.stdout}\n${result.stderr}`));
+            this.isAstGrepVersionOutput(`${result.stdout}\n${result.stderr}`)) {
+            return true;
+        }
+        const { outcome, cause } = classifyProbeFailure(result, { hostStallMs });
+        if (outcome === "transient") {
+            if (fallback) {
+                this.sweepFallbackTransient = true;
+                this.sweepFallbackCause = cause;
+            }
+            else {
+                this.sweepSawTransient = true;
+                this.sweepTransientCause = cause;
+                const name = path.basename(cmd);
+                if (!this.sweepUnreachable.includes(name)) {
+                    this.sweepUnreachable.push(name);
+                }
+            }
+        }
+        else if (!this.sweepDurablyMissing.includes(cmd)) {
+            this.sweepDurablyMissing.push(cmd);
+        }
+        return false;
     }
     async probeCommandCandidates(candidates) {
         for (const candidate of candidates) {
-            if (await this.probeCommand(candidate.cmd, candidate.argsPrefix)) {
+            if (await this.probeCommand(candidate.cmd, candidate.argsPrefix, candidate.fallback ?? false)) {
                 return candidate;
             }
         }