@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/lazy-installer.js

@@ -1,41 +1,274 @@
+/**
+ * The one lazy-install seam (#1537).
+ *
+ * Best-effort installs of language-specific tools, triggered when a runner or a
+ * formatter finds its tool absent. There were two copies of this — the
+ * `attempted` Set here and `formatters.ts`'s `_lazyInstallAttempts` — and both
+ * carried the same defect: the key went in BEFORE the install ran and never came
+ * out. A `gem install rubocop` that died on a network blip was therefore never
+ * retried for the rest of the session, and the tool stayed skipped.
+ *
+ * The guard itself is right, and it stays: an install storm is worse than a
+ * missed install, and these spawns are up to 3 minutes each. What was wrong is
+ * that a transient failure and a genuine refusal were recorded identically, with
+ * no expiry on either. So the record is now written AFTER the install, and it
+ * carries the outcome:
+ *
+ *   * `succeeded` — nothing more to do this session.
+ *   * `failed`, transient (timed out, killed, EAGAIN) — retried after a
+ *     cooldown, at most LAZY_INSTALL_MAX_TRANSIENT_ATTEMPTS times, then held.
+ *   * `failed`, durable (the package MANAGER is not on this machine) — held for
+ *     the session. No cooldown can conjure a `gem`.
+ *
+ * The vocabulary is #1534's `InstallAttemptFact`, so `describeInstallAttempt`
+ * turns this record straight into the `availability_decision` install evidence
+ * (#1500) — which is what makes "we tried and the network failed" tellable from
+ * "this tool cannot be installed here".
+ *
+ * A trust denial is deliberately NOT recorded: `assertInstallAllowed` is
+ * re-evaluated per call and a later grant must retry (#1350).
+ */
 import { safeSpawnAsync } from "../../../safe-spawn.js";
 import { assertInstallAllowed } from "../../../project-trust.js";
-const attempted = new Set();
+import { logExtension } from "../../../extension-log.js";
+import { classifyProbeFailure, installRetryDelayMs, } from "./availability-policy.js";
+/**
+ * What each install actually runs. Every one of these is a MACHINE-GLOBAL
+ * mutation — `gem install rubocop` and `rustup component add` write to the
+ * user's gem/toolchain root, not into `cwd` — which is why the hold is shared
+ * across seams rather than being per caller (#1537 review F4). A runner and a
+ * formatter asking for the same `gem install rubocop` are asking for the same
+ * one thing; the second must be suppressed, not run again.
+ */
+// golangci-lint deliberately has no entry here: it auto-installs through the
+// shared TOOL_EXECUTION_POLICY seam instead (`resolveAvailableOrInstall` +
+// `ensureTool` in clients/dispatch/runners/utils/runner-helpers.ts, wired in
+// golangci-lint.ts). A "golangci-lint" arm briefly lived in this map with no
+// caller reaching it through EITHER `tryLazyInstall` or
+// `tryLazyInstallForFormatter` — dead since introduction (#1572 sweep).
+const LAZY_INSTALL_SPECS = {
+    rubocop: { command: "gem", args: ["install", "rubocop", "--no-document"] },
+    "rust-clippy": { command: "rustup", args: ["component", "add", "clippy"] },
+    rustfmt: { command: "rustup", args: ["component", "add", "rustfmt"] },
+};
+/**
+ * Every lazy install ignores an ambient cancellation.
+ *
+ * The two merged copies disagreed — the formatter one opted in, the runner one
+ * did not — and keeping that difference per CALLER while the two share a hold
+ * made the cancellation semantics first-caller-wins: whether a `gem install`
+ * could be killed mid-write depended on which seam happened to reach it first
+ * (#1537 review F4). Nondeterminism is the worse of the two options, so the
+ * property belongs to the tool.
+ *
+ * `true` is the safe direction and the one the newer copy already chose: a
+ * half-finished `gem install` or `rustup component add` leaves a broken
+ * toolchain, whereas letting it finish costs at most the spawn's own budget
+ * below. This is a deliberate behaviour change for the runner seam.
+ */
+const LAZY_INSTALL_IGNORES_AMBIENT_SIGNAL = true;
+const LAZY_INSTALL_TIMEOUT_MS = 180_000;
+const attempts = new Map();
 function key(cwd, tool) {
     return `${cwd}:${tool}`;
 }
 /**
- * Best-effort lazy install for language-specific linters.
+ * What the last lazy install for this tool+cwd did, in #1534's vocabulary.
  *
- * Installs are attempted once per cwd+tool per session to avoid repeated churn.
+ * Feed it to `describeInstallAttempt` to put the install evidence beside the
+ * availability verdict it produced. `undefined` means nothing was attempted,
+ * which `describeInstallAttempt` renders as `not-attempted` rather than
+ * inventing a failure.
  */
-export async function tryLazyInstall(tool, cwd) {
-    if (!assertInstallAllowed(`runner lazy install: ${tool}`))
-        return false;
+export function getLazyInstallAttempt(tool, cwd) {
+    return attempts.get(key(cwd, tool))?.fact;
+}
+/**
+ * Drop every lazy-install verdict, so the next call may try again.
+ *
+ * Called from `session_start`'s per-session reset block in `runtime-session.ts`,
+ * beside `resetInstallRetryLatches()` (#1497) — and from NOWHERE else.
+ *
+ * The boundary is the whole point (#1537 review F1). The first cut wired this
+ * into `clearFormatterRuntimeState()`, reasoning that it was "the session-reset
+ * path already wired". It is not: that runs from `resetFormatService()`, which
+ * `handleTurnEnd` calls every turn. So "held for the session" was held for a
+ * TURN — six turns against a missing `gem` meant six 180-second install spawns
+ * where the pre-fix bug managed one, the ladder never advanced, and the
+ * `InstallAttemptFact` was erased at the same moment. A hold too short is the
+ * #1497 storm; a hold too long is the #1494 permanent latch. Only the session
+ * boundary is correct, and only a test that drives the real `handleSessionStart`
+ * can prove this is wired to it (the #1266 lesson).
+ */
+export function resetLazyInstallAttempts() {
+    // Verdicts only. `inFlight` is concurrency bookkeeping, not session state:
+    // clearing it mid-install would let the next caller start a SECOND concurrent
+    // install of the same tool, which is the very thing it prevents. Its entries
+    // are removed by their own `finally`.
+    attempts.clear();
+}
+function suppressionFor(state) {
+    if (!state)
+        return null;
+    if (state.fact.outcome === "succeeded")
+        return "succeeded";
+    if (state.retryAtMs === 0)
+        return "held";
+    return Date.now() < state.retryAtMs ? "cooling" : null;
+}
+/**
+ * Installs currently running, so callers that arrive mid-install join the one in
+ * flight instead of starting another (#1537 review F3).
+ *
+ * The suppression check and the record write are separated by a spawn that can
+ * take three minutes, and the sequential storm-guard test could never see it:
+ * three concurrent callers each read "no record yet" and each spawned, the
+ * ladder counted a single failure for three installs, and whichever finished
+ * last overwrote the others' verdict — a stale success could bury a later
+ * failure. Keyed identically to `attempts`, and evicted in a `finally` so a
+ * rejection cannot leave a permanent phantom in-flight entry.
+ */
+const inFlight = new Map();
+async function runLazyInstall(tool, cwd, spec) {
     const k = key(cwd, tool);
-    if (attempted.has(k))
+    const running = inFlight.get(k);
+    // Joining, not re-answering: both callers get the outcome of the install they
+    // actually waited for.
+    if (running)
+        return running;
+    const previous = attempts.get(k);
+    const suppressed = suppressionFor(previous);
+    if (suppressed !== null) {
+        logExtension({
+            subsystem: "install",
+            message: `lazy-install ${tool} suppressed (${suppressed})`,
+            metadata: {
+                tool,
+                cwd,
+                suppressed,
+                outcome: previous?.fact.outcome,
+                ...(previous?.fact.reason && { reason: previous.fact.reason }),
+                ...(suppressed === "cooling" && {
+                    retryAfterMs: Math.max(0, (previous?.retryAtMs ?? 0) - Date.now()),
+                }),
+            },
+        });
         return false;
-    attempted.add(k);
+    }
+    const started = performInstall(k, tool, cwd, spec);
+    inFlight.set(k, started);
     try {
-        switch (tool) {
-            case "golangci-lint": {
-                const result = await safeSpawnAsync("go", [
-                    "install",
-                    "github.com/golangci/golangci-lint/cmd/golangci-lint@latest",
-                ], { timeout: 180000, cwd });
-                return !result.error && result.status === 0;
-            }
-            case "rubocop": {
-                const result = await safeSpawnAsync("gem", ["install", "rubocop", "--no-document"], { timeout: 180000, cwd });
-                return !result.error && result.status === 0;
-            }
-            case "rust-clippy": {
-                const result = await safeSpawnAsync("rustup", ["component", "add", "clippy"], { timeout: 180000, cwd });
-                return !result.error && result.status === 0;
-            }
-        }
+        return await started;
     }
-    catch {
-        return false;
+    finally {
+        inFlight.delete(k);
     }
 }
+async function performInstall(k, tool, cwd, spec) {
+    let result;
+    try {
+        result = await safeSpawnAsync(spec.command, spec.args, {
+            timeout: LAZY_INSTALL_TIMEOUT_MS,
+            cwd,
+            ...(LAZY_INSTALL_IGNORES_AMBIENT_SIGNAL && { ignoreAmbientSignal: true }),
+        });
+    }
+    catch (err) {
+        // A throw from the spawn boundary is not evidence that the tool cannot be
+        // installed, so it is transient like any other failure to get a fair run.
+        result = {
+            stdout: "",
+            stderr: err?.message ?? String(err),
+            status: null,
+            error: err,
+            failure: "spawn",
+        };
+    }
+    if (!result.error && result.status === 0) {
+        attempts.set(k, {
+            fact: { outcome: "succeeded" },
+            retryAtMs: 0,
+            transientAttempts: 0,
+        });
+        return true;
+    }
+    // `classifyProbeFailure` owns the transient taxonomy (timeout, kill, EAGAIN)
+    // and the one durable case that matters here: `tool-not-found` on the package
+    // MANAGER. Everything else RAN and exited nonzero, which for an install is
+    // the retry candidate — a network failure and a nonexistent package are
+    // indistinguishable from the exit code, so the attempt CEILING is what stops
+    // the second one from retrying forever, not a guess at the cause.
+    const classified = classifyProbeFailure(result, {
+        command: spec.command,
+        unclassifiedFailureOutcome: "transient",
+    });
+    const durable = classified.outcome === "missing";
+    const reason = (result.error?.message ??
+        result.stderr ??
+        `exit ${result.status}`)
+        .trim()
+        .slice(0, 200);
+    // Re-read the record rather than trusting one captured before the spawn
+    // (#1537 review P3). `resetLazyInstallAttempts` clears `attempts` but leaves
+    // `inFlight`, so an install can outlive the session that started it — and a
+    // captured counter let that survivor stamp the OLD session's attempt count
+    // onto the NEW session's empty map, opening a fresh session already HELD with
+    // no attempts of its own. Re-reading makes the settle count as attempt 1 of
+    // whatever session is current. Nothing else can write this key while the
+    // install is in flight (the in-flight map is what guarantees that), so in the
+    // ordinary case this reads exactly what was captured.
+    const settledPrevious = attempts.get(k);
+    const transientAttempts = durable
+        ? 0
+        : (settledPrevious?.transientAttempts ?? 0) + 1;
+    // The ceiling is READ OFF the ladder: `installRetryDelayMs` returns 0 once its
+    // list is spent, which is the same "no retry, the verdict is latched" signal
+    // `noteUnavailable` returns. No separate max-attempts comparison to disagree
+    // with the ladder's real length (#1537 review F2).
+    const cooldownMs = durable ? 0 : installRetryDelayMs(transientAttempts);
+    const retryAtMs = cooldownMs === 0 ? 0 : Date.now() + cooldownMs;
+    attempts.set(k, {
+        fact: { outcome: "failed", reason },
+        retryAtMs,
+        transientAttempts,
+    });
+    logExtension({
+        subsystem: "install",
+        message: `lazy-install ${tool} failed: ${reason}`,
+        metadata: {
+            tool,
+            cwd,
+            command: spec.command,
+            cause: classified.cause,
+            durable,
+            transientAttempts,
+            held: retryAtMs === 0,
+            ...(retryAtMs > 0 && { retryAfterMs: retryAtMs - Date.now() }),
+            evidence: classified.evidence,
+        },
+    });
+    return false;
+}
+/**
+ * Best-effort lazy install for language-specific linters.
+ *
+ * Returns true only when an install just ran and succeeded — a suppressed call
+ * returns false rather than repeating the previous answer, so a caller cannot
+ * mistake "already handled" for "just installed".
+ */
+export async function tryLazyInstall(tool, cwd) {
+    if (!assertInstallAllowed(`runner lazy install: ${tool}`))
+        return false;
+    return runLazyInstall(tool, cwd, LAZY_INSTALL_SPECS[tool]);
+}
+/**
+ * The formatter-facing entry point. Distinct only for the trust gate's audit
+ * label, which names the seam that asked; the state, the spawn options, the
+ * classification and the ladder are all shared, because this was a two-copy
+ * shape and a fix in one copy is not a fix (#1537).
+ */
+export async function tryLazyInstallForFormatter(tool, cwd) {
+    if (!assertInstallAllowed(`formatter lazy install: ${tool}`))
+        return false;
+    return runLazyInstall(tool, cwd, LAZY_INSTALL_SPECS[tool]);
+}