@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/bash-file-access.js

@@ -4,7 +4,8 @@
  *
  *   - VIEW commands (cat/head/tail/sed -n) → reads, recorded with the exact line
  *     range shown (like the Read tool's delivered range).
- *   - WRITE commands (redirects, tee, sed -i, cp/mv dest, touch) → the agent
+ *   - WRITE commands (redirects, tee, sed -i, cp/mv dest, touch, and explicit
+ *     in-place formatter/fixer targets) → the agent
  *     authored/owns the resulting file, exactly like the Write tool — these are
  *     registered via noteCreatedFile + recordWritten so a follow-up edit is not
  *     blocked.
@@ -90,7 +91,7 @@ export function tokenizeShellCommand(command) {
             // Windows routinely contain native paths (C:\\src\\file.ts). Preserve
             // backslashes before ordinary path characters while still honoring
             // shell escapes and line continuations.
-            if (next === "\n" || /[\s\\'\";$|&<>]/.test(next ?? "")) {
+            if (next === "\n" || /[\s\\'";$|&<>]/.test(next ?? "")) {
                 escaped = true;
             }
             else {
@@ -162,6 +163,37 @@ function parseCountFlag(token) {
 function commandSegments(command) {
     return tokenizeShellCommand(command).map((segment) => segment.tokens);
 }
+/** Unwrap the common agent-authored `npx <tool>` launcher form. */
+function unwrapCommand(tokens) {
+    let verb = path.basename(tokens[0] ?? "");
+    let args = tokens.slice(1);
+    if (verb === "npx") {
+        while (args[0] === "-y" || args[0] === "--yes")
+            args = args.slice(1);
+        verb = path.basename(args[0] ?? "");
+        args = args.slice(1);
+    }
+    return { verb, args };
+}
+/**
+ * Return source-file operands while excluding values consumed by known options.
+ * This stays deliberately narrower than a general CLI parser: only formatter
+ * options whose values can themselves look like source files belong here.
+ */
+function formatterFileArgs(args, start = 0, valueOptions = new Set()) {
+    const files = [];
+    for (let i = start; i < args.length; i += 1) {
+        const arg = args[i] ?? "";
+        if (valueOptions.has(arg)) {
+            i += 1;
+            continue;
+        }
+        if (arg === "--" || arg.startsWith("-"))
+            continue;
+        files.push(arg);
+    }
+    return files;
+}
 /** Find redirect targets without treating quoted `>` characters as syntax. */
 function extractRedirectTargets(command) {
     const targets = [];
@@ -344,6 +376,80 @@ const GREP_OPTIONS_WITH_VALUE = new Set([
     "--before-context",
     "--context",
 ]);
+function parseContextValue(inline, next) {
+    const raw = inline !== "" ? inline : next;
+    if (raw === undefined)
+        return undefined;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    // Bound the credit: a huge -C would credit a whole file from one hit.
+    return Math.min(n, 100);
+}
+/**
+ * Read the context lines a `grep` invocation actually PRINTS around each hit
+ * (#1904 item 2). Only these lines were delivered to the model, so only these
+ * may be credited as read. Handles `-A N`, `-A3`, clustered short flags such as
+ * `-rnA3`, `--after-context=N`, the `-B`/`--before-context` mirror, `-C`
+ * (both sides), and the bare `-NUM` form.
+ */
+export function parseGrepContextLines(args) {
+    let before = 0;
+    let after = 0;
+    for (let i = 0; i < args.length; i++) {
+        const token = stripQuotes(args[i]);
+        if (token === "--")
+            break;
+        const nextToken = args[i + 1] === undefined ? undefined : stripQuotes(args[i + 1]);
+        const long = /^--(after|before)-context(?:=(\d+))?$/.exec(token);
+        if (long) {
+            const value = parseContextValue(long[2] ?? "", nextToken);
+            if (value === undefined)
+                continue;
+            if (long[1] === "after")
+                after = Math.max(after, value);
+            else
+                before = Math.max(before, value);
+            continue;
+        }
+        const longBoth = /^--context(?:=(\d+))?$/.exec(token);
+        if (longBoth) {
+            const value = parseContextValue(longBoth[1] ?? "", nextToken);
+            if (value === undefined)
+                continue;
+            before = Math.max(before, value);
+            after = Math.max(after, value);
+            continue;
+        }
+        // Bare numeric context form: `grep -3 pattern file`.
+        const bare = /^-(\d+)$/.exec(token);
+        if (bare) {
+            const value = parseContextValue(bare[1], undefined);
+            if (value === undefined)
+                continue;
+            before = Math.max(before, value);
+            after = Math.max(after, value);
+            continue;
+        }
+        // Short flags, possibly clustered: the context flag must be LAST in the
+        // cluster because it consumes the remaining characters as its value.
+        const short = /^-[A-Za-z]*([ABC])(\d*)$/.exec(token);
+        if (!short)
+            continue;
+        const value = parseContextValue(short[2], nextToken);
+        if (value === undefined)
+            continue;
+        if (short[1] === "A")
+            after = Math.max(after, value);
+        else if (short[1] === "B")
+            before = Math.max(before, value);
+        else {
+            before = Math.max(before, value);
+            after = Math.max(after, value);
+        }
+    }
+    return { before, after };
+}
 function extractGrepSearchFiles(args, cwd) {
     const files = [];
     let patternSeen = false;
@@ -411,6 +517,11 @@ function parseGrepLineWithoutFile(line, file) {
 function collectGrepCommandFiles(command, cwd) {
     const files = new Set();
     let hasLineNumberGrep = false;
+    // A command can chain several greps whose output all reaches the model, but
+    // the parsed hits carry no segment identity. Credit the SMALLEST context any
+    // contributing grep printed, so no line is credited that a hit from the
+    // narrowest grep never delivered.
+    let context;
     for (const tokens of commandSegments(command)) {
         const verb = path.basename(stripQuotes(tokens[0] ?? ""));
         if (verb !== "grep" && verb !== "egrep" && verb !== "fgrep")
@@ -419,10 +530,21 @@ function collectGrepCommandFiles(command, cwd) {
         if (!grepHasLineNumbers(args))
             continue;
         hasLineNumberGrep = true;
+        const segmentContext = parseGrepContextLines(args);
+        context = context
+            ? {
+                before: Math.min(context.before, segmentContext.before),
+                after: Math.min(context.after, segmentContext.after),
+            }
+            : segmentContext;
         for (const file of extractGrepSearchFiles(args, cwd))
             files.add(file);
     }
-    return { hasLineNumberGrep, files };
+    return {
+        hasLineNumberGrep,
+        files,
+        context: context ?? { before: 0, after: 0 },
+    };
 }
 function dedupePushSearchRead(out, seen, loc) {
     if (!loc)
@@ -452,17 +574,25 @@ function parseGrepOutputSearchReads(output, cwd, singleFile) {
  * so the latter is only accepted when the command names exactly one source file.
  */
 export function extractGrepSearchReadsFromOutput(command, cwd, output) {
-    const { hasLineNumberGrep, files } = collectGrepCommandFiles(command, cwd);
+    const { hasLineNumberGrep, files, context } = collectGrepCommandFiles(command, cwd);
     if (!hasLineNumberGrep)
         return [];
     const singleFile = files.size === 1 ? [...files][0] : undefined;
-    return parseGrepOutputSearchReads(output, cwd, singleFile);
+    const locations = parseGrepOutputSearchReads(output, cwd, singleFile);
+    // Only the printed context lines were delivered to the model, so only they
+    // are credited. A bare grep credits its match line alone (#1904 item 2).
+    for (const loc of locations) {
+        loc.contextBefore = context.before;
+        loc.contextAfter = context.after;
+    }
+    return locations;
 }
 /**
  * Extract files a bash command WROTE/created, so the read-guard can treat them
  * as authored by the agent (mirrors the Write tool). Handles:
  *   redirects: `> FILE`, `>> FILE`, `N> FILE`, `&> FILE` (with or without space)
- *   tee [-a] FILE...,  sed -i ... FILE,  cp/mv/install ... DEST,  touch FILE...
+ *   tee [-a] FILE..., sed -i ... FILE, cp/mv/install ... DEST, touch FILE...,
+ *   and common in-place formatter/fixer invocations with explicit file targets.
  *
  * Returns absolute paths. The file need not exist yet (it may be created) —
  * existence is confirmed later by recordWritten at tool_result time.
@@ -490,8 +620,7 @@ export function extractWrittenPathsFromCommand(command, cwd) {
     for (const tokens of commandSegments(command)) {
         if (tokens.length === 0)
             continue;
-        const verb = path.basename(tokens[0] ?? "");
-        const args = tokens.slice(1);
+        const { verb, args } = unwrapCommand(tokens);
         if (verb === "tee" || verb === "touch") {
             for (const a of args)
                 if (!a.startsWith("-"))
@@ -502,10 +631,89 @@ export function extractWrittenPathsFromCommand(command, cwd) {
                 add(a);
         }
         else if (verb === "cp" || verb === "mv" || verb === "install") {
+            // Known miss (#1668 review F3): the GNU `-t DEST`/`--target-directory`
+            // form puts the destination BEFORE the sources — this always treats
+            // the LAST non-flag argument as the destination, so `-t DEST SRC` and
+            // multi-source `-t DEST SRC1 SRC2...` are misread. Rare in agent-
+            // authored bash (source-before-dest is the common form); documented
+            // rather than fixed, since correctly parsing `-t` means recognizing it
+            // takes a value while telling it apart from every other single-letter
+            // flag this same branch already ignores.
             const files = args.filter((a) => !a.startsWith("-"));
             if (files.length >= 1)
                 add(files[files.length - 1]); // destination
         }
+        else if (verb === "biome") {
+            const sub = args[0];
+            if ((sub === "format" || sub === "check") && args.includes("--write")) {
+                for (const file of formatterFileArgs(args, 1, new Set(["--config-path"])))
+                    add(file);
+            }
+        }
+        else if (verb === "prettier" && args.includes("--write")) {
+            for (const file of formatterFileArgs(args, 0, new Set(["--config", "--ignore-path", "--parser", "--plugin"])))
+                add(file);
+        }
+        else if (verb === "eslint" && args.includes("--fix")) {
+            for (const file of formatterFileArgs(args, 0, new Set(["--config", "--ignore-path", "--parser", "--plugin"])))
+                add(file);
+        }
+        else if (verb === "ruff") {
+            const sub = args[0];
+            if (sub === "format" || args.includes("--fix")) {
+                const start = sub === "format" || sub === "check" ? 1 : 0;
+                for (const file of formatterFileArgs(args, start, new Set(["--config"])))
+                    add(file);
+            }
+        }
+        else if (verb === "gofmt" && args.includes("-w")) {
+            for (const file of formatterFileArgs(args))
+                add(file);
+        }
+        else if (verb === "cargo" && args[0] === "fmt") {
+            // Bare cargo fmt is project-scoped and cannot be enumerated without a
+            // filesystem walk. Only explicit rustfmt operands after `--` are safe.
+            const separator = args.indexOf("--");
+            if (separator >= 0) {
+                for (const file of formatterFileArgs(args, separator + 1, new Set(["--edition", "--config-path"])))
+                    add(file);
+            }
+        }
+        else if (verb === "rustfmt") {
+            for (const file of formatterFileArgs(args, 0, new Set(["--edition", "--config-path"])))
+                add(file);
+        }
+        else if (verb === "black") {
+            for (const file of formatterFileArgs(args, 0, new Set([
+                "--config",
+                "--exclude",
+                "--include",
+                "--line-length",
+                "--target-version",
+            ])))
+                add(file);
+        }
+        else if (verb === "clang-format" && args.includes("-i")) {
+            for (const file of formatterFileArgs(args, 0, new Set(["--style", "--fallback-style", "--assume-filename"])))
+                add(file);
+        }
+        else if (verb === "dotnet" && args[0] === "format") {
+            // dotnet format is normally solution-scoped. `--include` is the one
+            // invocation form that provides attributable source paths.
+            for (let i = 1; i < args.length; i += 1) {
+                if (args[i] === "--include" && args[i + 1]) {
+                    for (const file of (args[i + 1] ?? "").split(","))
+                        add(file);
+                    i += 1;
+                }
+                else if (args[i]?.startsWith("--include=")) {
+                    for (const file of (args[i] ?? "")
+                        .slice("--include=".length)
+                        .split(","))
+                        add(file);
+                }
+            }
+        }
         else if (verb === "git") {
             // git ops that REWRITE working-tree files with explicit paths:
             //   git checkout [<ref>] -- <files>   git restore [opts] <files>
@@ -524,6 +732,75 @@ export function extractWrittenPathsFromCommand(command, cwd) {
                 for (const a of fileArgs)
                     add(a);
             }
+            else if (sub === "mv") {
+                // git mv SRC... DEST — the destination is a write, exactly like
+                // plain `mv` above (#1668 review F2). The source side is a delete,
+                // handled by extractDeletedPathsFromCommand.
+                const files = args.slice(1).filter((a) => !a.startsWith("-"));
+                if (files.length >= 1)
+                    add(files[files.length - 1]);
+            }
+        }
+    }
+    return Array.from(out);
+}
+/**
+ * Extract files a bash command likely DELETED, for the type-3 (Deleted)
+ * watched-files gap (#1668): `rm FILE...`, `git rm FILE...`, and the SOURCE
+ * side of `mv SRC DEST` / `git mv SRC DEST` (the destination is a write,
+ * covered by `extractWrittenPathsFromCommand` — including for `git mv`,
+ * #1668 review F2).
+ *
+ * Deliberately narrow: only commands naming an explicit file target are
+ * handled. A bare directory op (`rm -rf dir/`, `git clean`) is skipped —
+ * resolving what vanished inside a directory would mean listing it before
+ * and after, the "stat the world" cost this module exists to avoid. The
+ * caller confirms each candidate by checking it no longer exists on disk;
+ * this function only proposes what the command named.
+ */
+export function extractDeletedPathsFromCommand(command, cwd) {
+    const out = new Set();
+    const add = (token) => {
+        const abs = resolveCandidate(token, cwd);
+        if (abs)
+            out.add(abs);
+    };
+    // mv SRC... DEST / git mv SRC... DEST — every argument except the last is
+    // a source that vanishes from its original path once the move lands.
+    // Known miss (#1668 review F3): the same `-t DEST`/`--target-directory`
+    // form documented in `extractWrittenPathsFromCommand` misreads here too —
+    // this assumes source-before-destination order.
+    const addMoveSources = (args) => {
+        const files = args.filter((a) => !a.startsWith("-"));
+        if (files.length >= 2) {
+            for (const src of files.slice(0, -1))
+                add(src);
+        }
+    };
+    for (const tokens of commandSegments(command)) {
+        if (tokens.length === 0)
+            continue;
+        const verb = path.basename(tokens[0] ?? "");
+        const args = tokens.slice(1);
+        if (verb === "rm") {
+            for (const a of args)
+                if (!a.startsWith("-"))
+                    add(a);
+        }
+        else if (verb === "git" && args[0] === "rm") {
+            const rmArgs = args.slice(1);
+            const dashDash = rmArgs.indexOf("--");
+            const fileArgs = dashDash >= 0
+                ? rmArgs.slice(dashDash + 1)
+                : rmArgs.filter((a) => !a.startsWith("-"));
+            for (const a of fileArgs)
+                add(a);
+        }
+        else if (verb === "git" && args[0] === "mv") {
+            addMoveSources(args.slice(1));
+        }
+        else if (verb === "mv") {
+            addMoveSources(args);
         }
     }
     return Array.from(out);

package/node_modules/pi-lens/dist/clients/biome-client.js

@@ -14,11 +14,34 @@ import { isFileKind } from "./file-kinds.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { createSingleFlight } from "./single-flight.js";
 import { biomeConfigArgs } from "./tool-policy.js";
-import { resolveManagedToolClient } from "./dispatch/runners/utils/runner-helpers.js";
+import { resolveManagedToolClient, } from "./dispatch/runners/utils/runner-helpers.js";
+import { classifyProbeFailure, describeInstallAttempt, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 // --- Client ---
+const PROBE_TIMEOUT_MS = 10_000;
 export class BiomeClient {
-    biomeAvailable = null;
+    /**
+     * Availability memo, backed by the shared transient-aware latch (#1476).
+     *
+     * Biome is the hot-path formatter: before this, ANY probe failure — a
+     * timeout included — collapsed to `{ outcome: "missing" }`, which both
+     * triggered an install and latched `false` for the life of the process. One
+     * slow first format then disabled formatting until restart.
+     */
+    availabilityLatch = createAvailabilityLatch();
+    /** Cause of the last probe, read when the resolution comes back. */
+    lastProbeCause = null;
+    /**
+     * Measurements of the last failed probe, held until the latch decides how
+     * long the verdict lasts. The decision record is emitted after that, so it
+     * can carry `retryAfterMs` — a latch you can see is worth little if the
+     * retry schedule is not greppable beside it (#1474).
+     */
+    lastProbeElapsedMs = 0;
+    lastProbeHostStallMs = 0;
+    /** Raw facts from the last probe, carried into the decision record (#1500). */
+    lastProbeEvidence;
     // Per-cwd cache of the resolved biome binary. Keying by cwd matters in
     // monorepos where different sub-packages each ship their own biome
     // installation; sharing one slot across the whole client would cause
@@ -28,7 +51,11 @@ export class BiomeClient {
     // (lives under ~/.pi-lens/tools), so it's stored separately from the
     // per-cwd cache and used as a final fallback before npx.
     autoInstalledBinaryPath = null;
-    ensureInFlight = null;
+    /**
+     * At-most-one probe/auto-install in flight, via the shared primitive
+     * (#1753). One instance owns one question, so the key is a constant.
+     */
+    ensureFlight = createSingleFlight();
     log;
     constructor(verbose = false) {
         this.log = verbose
@@ -50,13 +77,14 @@ export class BiomeClient {
         const cached = this.localBinaryByCwd.get(resolveCwd);
         if (cached)
             return { cmd: cached, args: [] };
-        if (this.autoInstalledBinaryPath) {
-            return { cmd: this.autoInstalledBinaryPath, args: [] };
-        }
-        // Walk up from cwd looking for node_modules/.bin/biome.
-        // Also check ~/.pi-lens/tools (where ensureTool("biome") auto-installs),
-        // so we avoid the ~1.5s `npx @biomejs/biome --version` fallback when
-        // the tool is already installed but not in the project's node_modules.
+        // Walk up from cwd looking for node_modules/.bin/biome BEFORE trusting
+        // `autoInstalledBinaryPath` (#1731). That field is set once, the first
+        // time `ensureAvailable()` auto-installs for ANY cwd this session, and
+        // every later call for every OTHER cwd short-circuited on it — so a
+        // project that ships its own biome never won once the session's first
+        // managed install had already happened. Project-local-first (discipline
+        // B, #1721) means the project's pinned version and config resolution
+        // always outrank a managed copy, autoinstalled or not.
         // On Windows prefer .cmd (native batch) over the sh wrapper — 2x faster.
         const isWin = process.platform === "win32";
         const piLensBin = path.join(getGlobalPiLensDir(), "tools", "node_modules", ".bin");
@@ -64,20 +92,29 @@ export class BiomeClient {
             ? [
                 path.join(resolveCwd, "node_modules", ".bin", "biome.cmd"),
                 path.join(resolveCwd, "node_modules", ".bin", "biome"),
-                path.join(piLensBin, "biome.cmd"),
-                path.join(piLensBin, "biome"),
             ]
-            : [
-                path.join(resolveCwd, "node_modules", ".bin", "biome"),
-                path.join(resolveCwd, "node_modules", ".bin", "biome.cmd"),
-                path.join(piLensBin, "biome"),
-            ];
+            : [path.join(resolveCwd, "node_modules", ".bin", "biome")];
         for (const p of candidates) {
             if (fs.existsSync(p)) {
                 this.localBinaryByCwd.set(resolveCwd, p);
                 return { cmd: p, args: [] };
             }
         }
+        if (this.autoInstalledBinaryPath) {
+            return { cmd: this.autoInstalledBinaryPath, args: [] };
+        }
+        // Also check ~/.pi-lens/tools (where ensureTool("biome") auto-installs),
+        // so we avoid the ~1.5s `npx @biomejs/biome --version` fallback when the
+        // tool is already installed but not in the project's node_modules.
+        const managedCandidates = isWin
+            ? [path.join(piLensBin, "biome.cmd"), path.join(piLensBin, "biome")]
+            : [path.join(piLensBin, "biome")];
+        for (const p of managedCandidates) {
+            if (fs.existsSync(p)) {
+                this.localBinaryByCwd.set(resolveCwd, p);
+                return { cmd: p, args: [] };
+            }
+        }
         // Any package manager's global bin dir (npm/pnpm/yarn/bun) before npx —
         // catches `pnpm add -g @biomejs/biome` installs that PATH misses (#375).
         const global = await findGlobalBinary("biome");
@@ -96,41 +133,143 @@ export class BiomeClient {
      * Ensure Biome is available, auto-installing if necessary.
      * Prefer this over isAvailable() for auto-install behavior.
      *
-     * Re-entrancy safe: concurrent first-time callers share a single
-     * `ensureInFlight` promise so probing/auto-install isn't duplicated.
-     * Mirrors the dedupe pattern in `SgRunner` / `KnipClient` /
-     * `DependencyChecker`.
+     * Re-entrancy safe: concurrent first-time callers share one flight, so
+     * probing/auto-install isn't duplicated. The share and the clear-in-finally
+     * belong to `singleFlight` (#1753); this method owns only the latch
+     * short-circuit above it. #1690 exists because the hand-rolled clear here
+     * was never exercised by a test.
+     *
+     * The memo returns `null` when the last verdict was transient and its
+     * cooldown expired, which re-enters the probe: "biome is not installed" is a
+     * fact worth caching, "the probe timed out" is a moment worth retrying.
      */
     async ensureAvailable() {
-        if (this.biomeAvailable !== null)
-            return this.biomeAvailable;
-        if (this.ensureInFlight)
-            return this.ensureInFlight;
-        this.ensureInFlight = this.doEnsureAvailable();
+        const memo = this.availabilityLatch.read();
+        if (memo !== null)
+            return memo;
+        return this.ensureFlight.run("biome", () => this.doEnsureAvailable());
+    }
+    /**
+     * Probe `biome --version` and classify the failure through the shared
+     * policy. Only a durable verdict (`missing` / `non-installable`) may reach
+     * the install branch of `resolveManagedToolClient`; a transient one returns
+     * as `transient`, which that seam passes straight back without installing.
+     */
+    async probeBiome() {
+        // The probe budget is enforced by a HOST-side timer, so a stalled event
+        // loop expires it while the child is still healthy. Measure the stall
+        // that overlapped the window and let the classifier see it (#1467).
+        const sampler = startHostStallSampler();
+        const startedAt = Date.now();
+        let result;
+        let hostStallMs;
         try {
-            return await this.ensureInFlight;
+            result = await this.spawnBiomeAsync(["--version"], PROBE_TIMEOUT_MS);
         }
         finally {
-            this.ensureInFlight = null;
+            hostStallMs = sampler.stop();
         }
+        const elapsedMs = Date.now() - startedAt;
+        if (!result.error && result.status === 0) {
+            this.lastProbeCause = "ok";
+            logAvailabilityDecision({
+                tool: "biome",
+                verdict: "available",
+                outcome: "success",
+                cause: "ok",
+                elapsedMs,
+                latched: true,
+                hostStallMs,
+                budgetMs: PROBE_TIMEOUT_MS,
+            });
+            return { outcome: "success", value: true };
+        }
+        // `unclassifiedFailureOutcome: "missing"` preserves the pre-#1476
+        // meaning of a plain non-zero exit (npx reporting no biome package):
+        // still "missing", still installable. Only the timeout/abort arm changes.
+        const { outcome, cause, evidence } = classifyProbeFailure(result, {
+            hostStallMs,
+            unclassifiedFailureOutcome: "missing",
+        });
+        // `classifyProbeFailure` is typed over the full outcome union but never
+        // returns "success" for a failed probe; narrow it for the seam's type.
+        const failureOutcome = outcome === "success" ? "non-installable" : outcome;
+        this.lastProbeCause = cause;
+        this.lastProbeElapsedMs = elapsedMs;
+        this.lastProbeHostStallMs = hostStallMs;
+        this.lastProbeEvidence = evidence;
+        // The record is emitted by `doEnsureAvailable`, once the latch has said how
+        // long this verdict holds.
+        return { outcome: failureOutcome };
     }
     async doEnsureAvailable() {
-        const outcome = await resolveManagedToolClient({
+        const resolved = await resolveManagedToolClient({
             toolId: "biome",
             cwd: process.cwd(),
-            probe: async () => {
-                const result = await this.spawnBiomeAsync(["--version"], 10000);
-                return !result.error && result.status === 0
-                    ? { outcome: "success", value: true }
-                    : { outcome: "missing" };
-            },
+            probe: () => this.probeBiome(),
             acceptInstalled: (installedPath) => {
                 this.autoInstalledBinaryPath = installedPath;
                 return true;
             },
         });
-        this.biomeAvailable = outcome.outcome === "success";
-        return this.biomeAvailable;
+        if (resolved.outcome === "success") {
+            this.availabilityLatch.noteAvailable();
+            // The probe itself logs a clean hit. This arm is the other way to
+            // succeed — the install repaired a durable miss — and it needs its own
+            // record, or "biome went missing and came back" reads as silence.
+            if (this.lastProbeCause !== null && this.lastProbeCause !== "ok") {
+                logAvailabilityDecision({
+                    tool: "biome",
+                    verdict: "available",
+                    outcome: "success",
+                    cause: "ok",
+                    elapsedMs: this.lastProbeElapsedMs,
+                    latched: true,
+                    hostStallMs: this.lastProbeHostStallMs,
+                    budgetMs: PROBE_TIMEOUT_MS,
+                });
+            }
+            return true;
+        }
+        // A transient probe expires; a durable verdict is remembered for the
+        // session exactly as before.
+        const cause = this.lastProbeCause ?? "not-found";
+        const retryAfterMs = this.availabilityLatch.noteUnavailable(resolved.outcome, cause);
+        // `missing` IS the install-failure arm (#1500 review). `resolveManagedToolClient`
+        // only reaches the installer when the probe said `missing`, so every `missing`
+        // verdict here has already been through it — declined, suppressed, or tried
+        // and failed, which is what `describeInstallAttempt` separates. The earlier
+        // marker sat on the `non-installable` arm instead, and that arm cannot happen
+        // for biome at all: its `acceptInstalled` always accepts. So the one row that
+        // needed the fact was the one shipping without it.
+        let installEvidence;
+        if (resolved.outcome === "missing") {
+            const { getInstallAttempt } = await import("./installer/index.js");
+            installEvidence = describeInstallAttempt(getInstallAttempt("biome"));
+        }
+        const evidence = { ...this.lastProbeEvidence, ...installEvidence };
+        logAvailabilityDecision({
+            tool: "biome",
+            verdict: "unavailable",
+            outcome: resolved.outcome,
+            cause,
+            elapsedMs: this.lastProbeElapsedMs,
+            latched: resolved.outcome !== "transient",
+            hostStallMs: this.lastProbeHostStallMs,
+            ...(retryAfterMs > 0 && { retryAfterMs }),
+            budgetMs: PROBE_TIMEOUT_MS,
+            // Per arm: a probe-derived verdict says `probe`, while a verdict asserted
+            // by the install seam — or a cause that fell back because no probe ran —
+            // says `caller`.
+            classifiedBy: this.lastProbeCause === null || resolved.outcome === "non-installable"
+                ? "caller"
+                : "probe",
+            ...(Object.keys(evidence).length > 0 && { evidence }),
+        });
+        if (resolved.outcome === "transient") {
+            this.log("biome availability probe timed out; will retry (not installing)");
+        }
+        return false;
     }
     /**
      * Check if a file is supported by Biome