@herbertgao/pi-extensions 2026.8.5 → 2026.8.6

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

@@ -14,9 +14,32 @@
  */
 import { createSubsystemLogger } from "./extension-log.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { classifyProbeFailure, createAvailabilityLatch, 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 probe that
+     * merely timed out must go through `markTransientlyUnavailable` instead, so
+     * it expires and 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();
+        else if (value === false)
+            this.availabilityLatch.noteUnavailable("missing", "not-found");
+        else
+            this.availabilityLatch.reset();
+    }
+    /** Outcome/cause of the most recent `probeVersion` call. */
+    lastProbeOutcome = null;
+    lastProbeCause = null;
     ensureInFlight = null;
     inFlight = new Map();
     binaryPath = null;
@@ -51,18 +74,71 @@ export class SecurityScanClient {
     }
     /**
      * Spawn `toolName <versionArgs>` and report whether it answered cleanly.
-     * Does NOT mutate `this.available` — callers decide what a hit/miss means.
+     * Does NOT mutate `this.available` — callers decide what a hit/miss means —
+     * but it does classify the failure (`lastProbeOutcome`/`lastProbeCause`) and
+     * emit one availability-decision record, so a probe that keeps timing out is
+     * visible in latency.log rather than inferred from silence (#1467).
      */
     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.lastProbeCause = "ok";
             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,
+            });
             return true;
         }
+        const { outcome, cause } = classifyProbeFailure(probe, { hostStallMs });
+        this.lastProbeOutcome = outcome;
+        this.lastProbeCause = cause;
+        logAvailabilityDecision({
+            tool: this.toolName,
+            verdict: "unavailable",
+            outcome,
+            cause,
+            elapsedMs,
+            latched: outcome !== "transient",
+            hostStallMs,
+            budgetMs: 5000,
+        });
         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.
+     */
+    markTransientlyUnavailable(cause = "probe-timeout") {
+        return this.availabilityLatch.noteUnavailable("transient", cause);
+    }
     /**
      * Standard availability path for the GitHub-release tools (gitleaks, trivy):
      * PATH probe first, then fall back to the pi-lens installer's `ensureTool`.
@@ -73,6 +149,13 @@ 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`.
+            this.log(`${this.toolName} availability probe timed out; not installing, will retry`);
+            this.markTransientlyUnavailable(this.lastProbeCause ?? "probe-timeout");
+            return false;
+        }
         this.log(`${this.toolName} not found, attempting auto-install`);
         const { ensureTool } = await import("./installer/index.js");
         const installed = await ensureTool(this.toolName);

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

@@ -12,6 +12,7 @@ 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 { classifyProbeFailure, 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 +34,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 +97,31 @@ export class SgRunner {
     log;
     sgPath = null;
     sgArgsPrefix = [];
-    available = 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();
     ensureInFlight = null;
+    /**
+     * 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";
+    /** 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;
     constructor(verbose = false) {
         this.log = verbose
             ? createSubsystemLogger("sg-runner")
@@ -110,9 +136,11 @@ export class SgRunner {
      * `KnipClient.ensureAvailable` and `DependencyChecker.ensureAvailable`.
      */
     async ensureAvailable() {
-        // Fast path: already checked.
-        if (this.available !== null)
-            return this.available;
+        // 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;
         if (this.ensureInFlight)
             return this.ensureInFlight;
         this.ensureInFlight = this.doEnsureAvailable();
@@ -124,18 +152,26 @@ export class SgRunner {
         }
     }
     async doEnsureAvailable() {
+        const startedAt = Date.now();
+        this.sweepSawTransient = false;
+        this.sweepTransientCause = "probe-timeout";
+        this.sweepFallbackTransient = false;
+        this.sweepFallbackCause = "probe-timeout";
+        this.sweepHostStallMs = 0;
         // 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 +183,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 +194,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,11 +203,24 @@ 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) {
+            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.
         const installed = await resolveManagedToolClient({
@@ -185,11 +232,51 @@ 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);
+        }
+        return this.noteUnavailable(startedAt, "missing", "not-found");
+    }
+    /** Record a successful sweep: available, latched, one decision record. */
+    noteAvailable(startedAt, message) {
+        this.availabilityLatch.noteAvailable();
+        this.log(message);
+        logAvailabilityDecision({
+            tool: "ast-grep",
+            verdict: "available",
+            outcome: "success",
+            cause: "ok",
+            elapsedMs: Date.now() - startedAt,
+            latched: true,
+            hostStallMs: this.sweepHostStallMs,
+            budgetMs: PROBE_TIMEOUT_MS,
+        });
+    }
+    /**
+     * 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) {
+        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,
+        });
         return false;
     }
     /**
@@ -270,17 +357,48 @@ 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;
+            }
+        }
+        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;
             }
         }

package/node_modules/pi-lens/dist/clients/smells-rollup.js

@@ -24,14 +24,19 @@
  * alongside.
  *
  * The tail scan is bounded, but the tail can contain prior-session rows. The
- * session-start caller supplies the session boundary, and rows are admitted
- * only when their own UTC timestamp is at or after that boundary. This keeps
- * the same bounded read without reporting historical failures as current, so
- * this module does not additionally instrument the write call sites
- * (`bus-publish.ts`, `clients/lsp/index.ts`'s respawn path) with parallel
- * live counters. That keeps the change contained to one new module + three
- * small call sites (session_start, `/lens-health`, `turn_end`) instead of
- * touching every producer of the two source logs.
+ * `session_start` and `turn_end` callers supply the in-process session
+ * boundary (`runtime.sessionStartedAt`), and rows are admitted only when
+ * their own UTC timestamp is at or after that boundary. `/lens-health` has
+ * no per-session caller to anchor to (it can run at any point, including
+ * outside a turn) so it omits `sessionStartMs` and falls back to
+ * `SMELLS_ROLLING_WINDOW_MS` (24h) — its rendered line is labeled "last 24h
+ * tail-scan" to say so explicitly rather than implying a session-scoped
+ * count it isn't. This keeps the same bounded read without reporting
+ * historical failures as current, so this module does not additionally
+ * instrument the write call sites (`bus-publish.ts`, `clients/lsp/index.ts`'s
+ * respawn path) with parallel live counters. That keeps the change contained
+ * to one new module + three small call sites (session_start, `/lens-health`,
+ * `turn_end`) instead of touching every producer of the two source logs.
  *
  * Smells covered (deliberately a SUBSET — the two the issue named as having
  * gone unnoticed; the full catalogue stays in the manual analyzer):
@@ -53,6 +58,7 @@ import * as path from "node:path";
 import { getGlobalPiLensDir } from "./file-utils.js";
 /** Bounded tail-read budget PER source log file — never a full-file scan. */
 export const SMELLS_TAIL_BYTES_PER_FILE = 64 * 1024;
+export const SMELLS_ROLLING_WINDOW_MS = 24 * 60 * 60_000;
 /** Re-check cadence at `turn_end`, mirroring `memory-sampler.ts`'s pattern —
  *  cheap enough (bounded ~128KB I/O) not to need finer throttling, but a
  *  fixed interval keeps it from running on every single turn. */
@@ -154,11 +160,12 @@ function isOpengrepRespawn(entry) {
  * up to ~10MB) source files are. `root` is injectable for tests.
  */
 export function countRecentSmells(root = getGlobalPiLensDir(), sessionStartMs) {
+    const sinceMs = sessionStartMs ?? Date.now() - SMELLS_ROLLING_WINDOW_MS;
     const busTail = tailReadText(path.join(root, "bus-events.log"), SMELLS_TAIL_BYTES_PER_FILE);
     const latencyTail = tailReadText(path.join(root, "latency.log"), SMELLS_TAIL_BYTES_PER_FILE);
     return {
-        staleCtxEmitFailed: countMatchingLines(busTail, isStaleCtxEmitFailed, sessionStartMs),
-        opengrepRespawn: countMatchingLines(latencyTail, isOpengrepRespawn, sessionStartMs),
+        staleCtxEmitFailed: countMatchingLines(busTail, isStaleCtxEmitFailed, sinceMs),
+        opengrepRespawn: countMatchingLines(latencyTail, isOpengrepRespawn, sinceMs),
     };
 }
 /**
@@ -186,7 +193,7 @@ export function formatSmellsSessionStartLine(counts) {
  * everything is below threshold).
  */
 export function formatSmellsHealthLine(counts) {
-    return (`Smells (recent tail-scan): stale-ctx emit_failed=${counts.staleCtxEmitFailed}` +
+    return (`Smells (last 24h tail-scan): stale-ctx emit_failed=${counts.staleCtxEmitFailed}` +
         ` · opengrep respawn=${counts.opengrepRespawn}`);
 }
 /** `true` on turn 20, 40, 60, ... — never turn 0. Pure so the cadence is

package/node_modules/pi-lens/dist/clients/startup-timing.js

@@ -1,5 +1,11 @@
 import { performance } from "node:perf_hooks";
-import { PI_LENS_EVAL_STARTED_MS } from "./console-guard-install.js";
+// #1434 S3d: import the constant from the side-effect-free module, not from
+// `console-guard-install.ts` — that module installs the console guard as an
+// import side effect, so importing it here (for a single constant, from a
+// module measuring load time) would have silently installed the guard
+// wherever this file is imported, including test-only measurement code that
+// has no business flipping a global switch.
+import { PI_LENS_EVAL_STARTED_MS } from "./eval-timestamp.js";
 /**
  * Startup timing for pi-lens.
  *