@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/installer/index.js

@@ -45,7 +45,6 @@
  * - pip packages
  * - GitHub releases (platform-specific binaries → ~/.pi-lens/bin/)
  */
-import { logExtension } from "../extension-log.js";
 import { spawn } from "node:child_process";
 import { existsSync, statSync, unlinkSync } from "node:fs";
 import fs from "node:fs/promises";
@@ -53,16 +52,20 @@ import https from "node:https";
 import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
+import { writeFileAtomicAsync } from "../atomic-write.js";
 import { BoundedLruCache } from "../bounded-cache.js";
+import { logExtension } from "../extension-log.js";
 import { isFullyQualified } from "../path-utils.js";
 import { assertInstallAllowed, projectTrustDenialReason, } from "../project-trust.js";
 const _installerRequire = createRequire(import.meta.url);
 import { createGunzip } from "node:zlib";
-import { logSessionStart } from "../sessionstart-logger.js";
+import { TRANSIENT_MAX_COOLDOWN_MS } from "../dispatch/runners/utils/availability-policy.js";
+import { recordDegradationOnce } from "../degradation-ledger.js";
 import { commitDurableStoreAsync } from "../durable-store.js";
 import { getGlobalPiLensDir } from "../file-utils.js";
 import { allAvailableGlobalBinDirs, installArgs, pmBinary, resolveNodePackageManager, } from "../package-manager.js";
 import { resetSafeSpawnWindowsCommandCache, safeSpawnAsync, } from "../safe-spawn.js";
+import { logSessionStart } from "../sessionstart-logger.js";
 // Global installation directory for pi-lens tools
 const TOOLS_DIR = path.join(getGlobalPiLensDir(), "tools");
 const INSTALL_LOCK_PATH = path.join(TOOLS_DIR, ".install.lock");
@@ -135,8 +138,7 @@ async function acquireInstallLock() {
                 // every future install with a full-timeout wait. A lock older
                 // than any legitimate install (owner install bound + slack) is
                 // stale regardless of what the PID now points at.
-                const maxAgeMs = (Number(process.env.PI_LENS_INSTALL_TIMEOUT_MS) || 120_000) +
-                    60_000;
+                const maxAgeMs = (Number(process.env.PI_LENS_INSTALL_TIMEOUT_MS) || 120_000) + 60_000;
                 const expired = Number.isFinite(owner.createdAt) &&
                     Date.now() - owner.createdAt > maxAgeMs;
                 if (expired ||
@@ -241,7 +243,11 @@ export const TOOLS = [
         checkCommand: "tsc",
         checkArgs: ["--version"],
         installStrategy: "npm",
-        packageName: "typescript",
+        // The managed compiler serves the classic typescript-language-server
+        // fallback. TypeScript 7 removed lib/tsserver.js and is selected only from
+        // project-local installs through the native `tsc --lsp --stdio` path.
+        // Revisit when typescript-language-server supports TS 7 — refs #1436.
+        packageName: "typescript@5.9.3",
         binaryName: "tsc",
     },
     {
@@ -799,7 +805,11 @@ export const TOOLS = [
         id: "powershell-editor-services",
         name: "PowerShell Editor Services",
         checkCommand: "pwsh",
-        checkArgs: ["-NoProfile", "-Command", "$PSVersionTable.PSVersion.ToString()"],
+        checkArgs: [
+            "-NoProfile",
+            "-Command",
+            "$PSVersionTable.PSVersion.ToString()",
+        ],
         installStrategy: "archive",
         binaryName: "powershell-editor-services",
         archive: {
@@ -830,7 +840,9 @@ export const TOOLS = [
                 const version = "22.1.0";
                 const base = `https://github.com/clangd/clangd/releases/download/${version}`;
                 if (platform === "linux")
-                    return arch === "x64" ? `${base}/clangd-linux-${version}.zip` : undefined;
+                    return arch === "x64"
+                        ? `${base}/clangd-linux-${version}.zip`
+                        : undefined;
                 if (platform === "darwin")
                     return `${base}/clangd-mac-${version}.zip`;
                 if (platform === "win32")
@@ -1198,6 +1210,31 @@ export const TOOLS = [
             binaryInArchive: "clojure-lsp",
         },
     },
+    {
+        // CUE ships a single native binary per platform on GitHub releases;
+        // the LSP runs via `cue lsp serve`. Used as managedToolId by CueServer.
+        id: "cue",
+        name: "CUE",
+        checkCommand: "cue",
+        checkArgs: ["version"],
+        installStrategy: "github",
+        binaryName: "cue",
+        github: {
+            repo: "cue-lang/cue",
+            assetMatch: (platform, arch) => {
+                if (platform === "linux")
+                    return arch === "arm64" ? "linux_arm64.tar.gz" : "linux_amd64.tar.gz";
+                if (platform === "darwin")
+                    return arch === "arm64"
+                        ? "darwin_arm64.tar.gz"
+                        : "darwin_amd64.tar.gz";
+                if (platform === "win32")
+                    return arch === "arm64" ? "windows_arm64.zip" : "windows_amd64.zip";
+                return undefined;
+            },
+            binaryInArchive: "cue",
+        },
+    },
     {
         // gleam ships a single static binary per platform on GitHub releases; the
         // LSP runs via `gleam lsp`. Used as managedToolId by GleamServer. The linux
@@ -1274,9 +1311,7 @@ export const TOOLS = [
                 if (arch !== "x64" && arch !== "arm64")
                     return undefined;
                 if (platform === "linux")
-                    return arch === "arm64"
-                        ? "expert_linux_arm64"
-                        : "expert_linux_amd64";
+                    return arch === "arm64" ? "expert_linux_arm64" : "expert_linux_amd64";
                 if (platform === "darwin")
                     return arch === "arm64"
                         ? "expert_darwin_arm64"
@@ -1295,11 +1330,45 @@ const installFailureReasons = new Map();
 export function getInstallFailureReason(toolId) {
     return installFailureReasons.get(toolId);
 }
+const installAttempts = new Map();
+function noteInstallAttempt(toolId, outcome, reason) {
+    installAttempts.set(toolId, { outcome, reason, at: Date.now() });
+}
+/** Record an outcome only if this attempt has not already recorded its own. */
+function noteInstallAttemptIfUnrecorded(toolId, outcome, reason) {
+    if (installAttempts.has(toolId))
+        return;
+    noteInstallAttempt(toolId, outcome, reason);
+}
+/**
+ * What the last install attempt for `toolId` did, or `undefined` when no attempt
+ * has been recorded in this session. Consumers map this onto the
+ * `availability_decision` record's install evidence (#1500).
+ */
+export function getInstallAttempt(toolId) {
+    return installAttempts.get(toolId);
+}
+const lastEnsureResolutionSource = new Map();
+export function getLastEnsureResolutionSource(toolId) {
+    return lastEnsureResolutionSource.get(toolId);
+}
 // Session-lifetime cache: once a tool path is resolved, skip the process-spawn check on subsequent calls.
 const resolvedPathCache = new BoundedLruCache(256);
+/** Re-arm resolved tool paths when a new session may have changed PATH. */
+export function resetResolvedPathCache() {
+    resolvedPathCache.clear();
+}
 const PROBE_CACHE_PATH = path.join(getGlobalPiLensDir(), "probe-cache.json");
 const PROBE_CACHE_LOCK_STALE_MS = 180_000;
 const PROBE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * How long a transient-tainted entry (see `ProbeCacheEntry.transient`) is
+ * served before `getToolPath` is asked again, instead of the full 24h TTL
+ * (#1569). Shares the shared probe policy's transient ceiling rather than
+ * inventing a new number for the same "how long is a stall worth trusting"
+ * question.
+ */
+const PROBE_CACHE_TRANSIENT_COOLDOWN_MS = TRANSIENT_MAX_COOLDOWN_MS;
 const PROBE_CACHE_FLUSH_LOCK_WAIT_MS = 250;
 const PROBE_CACHE_FLUSH_RETRY_DELAY_MS = 300;
 const PROBE_CACHE_FLUSH_RETRY_MAX_DELAY_MS = 30_000;
@@ -1349,7 +1418,8 @@ function scheduleProbeFlush(delayMs = PROBE_CACHE_FLUSH_RETRY_DELAY_MS) {
     _probeCacheFlushTimer.unref?.();
 }
 function scheduleProbeFlushRetry() {
-    const delay = Math.min(PROBE_CACHE_FLUSH_RETRY_MAX_DELAY_MS, PROBE_CACHE_FLUSH_RETRY_DELAY_MS * 2 ** Math.min(_probeCacheRetryAttempt, 6));
+    const delay = Math.min(PROBE_CACHE_FLUSH_RETRY_MAX_DELAY_MS, PROBE_CACHE_FLUSH_RETRY_DELAY_MS *
+        2 ** Math.min(_probeCacheRetryAttempt, 6));
     _probeCacheRetryAttempt += 1;
     scheduleProbeFlush(delay);
 }
@@ -1359,14 +1429,32 @@ function snapshotProbeCacheChanges() {
         versions: new Map(_probeCacheChangeVersions),
     };
 }
+/**
+ * Deserialize the on-disk probe-cache for the LOCKED write-side merge
+ * (`writeProbeCache`'s `commitDurableStoreAsync` call). Unlike `readProbeCache`
+ * (the ordinary session-lookup path, which already degrades a parse/shape
+ * failure to `{}`), this used to THROW on a torn/corrupt file — which does
+ * not crash the caller (`writeProbeCache` wraps the whole commit in try/catch
+ * and retries), but it also means the corrupt file on disk is never repaired:
+ * every retry re-reads the same torn bytes, re-throws, and gives up again,
+ * forever (#1609 layer b). Degrading here too, exactly like `readProbeCache`,
+ * lets the next successful flush's `merge` step overwrite the torn file with
+ * a valid one instead of looping on it indefinitely.
+ */
 function deserializeProbeCache(contents) {
     if (contents === undefined)
         return {};
-    const parsed = JSON.parse(contents);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("probe-cache root is not an object");
+    try {
+        const parsed = JSON.parse(contents);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("probe-cache root is not an object");
+        }
+        return parsed;
+    }
+    catch (err) {
+        logSessionStart(`auto-install probe-cache: write-side read was corrupt (${err.message}); recovering as empty`);
+        return {};
     }
-    return parsed;
 }
 function applyProbeCacheChanges(disk, changes) {
     for (const [toolId, entry] of changes) {
@@ -1383,9 +1471,12 @@ function applyProbeCacheChanges(disk, changes) {
  * supplies the probe cache's former quarantine/stale-owner recovery.
  */
 function ageProbeCache(disk) {
-    const cutoff = Date.now() - PROBE_CACHE_TTL_MS;
+    const now = Date.now();
     for (const [toolId, entry] of Object.entries(disk)) {
-        if (!Number.isFinite(entry.cachedAt) || entry.cachedAt < cutoff) {
+        const ttl = entry.transient
+            ? PROBE_CACHE_TRANSIENT_COOLDOWN_MS
+            : PROBE_CACHE_TTL_MS;
+        if (!Number.isFinite(entry.cachedAt) || entry.cachedAt < now - ttl) {
             delete disk[toolId];
         }
     }
@@ -1514,8 +1605,15 @@ export async function checkProbeCache(toolId) {
     const entry = cache[toolId];
     if (!entry)
         return undefined;
-    if (Date.now() - entry.cachedAt > PROBE_CACHE_TTL_MS) {
-        logSessionStart(`auto-install probe-cache ${toolId}: miss (ttl expired)`);
+    // A transient-tainted entry (#1569) is not trusted past the shorter
+    // transient cooldown, even inside the 24h TTL — the selection it recorded
+    // may be a degraded fallback that a since-recovered preferred tier should
+    // now beat.
+    const ttl = entry.transient
+        ? PROBE_CACHE_TRANSIENT_COOLDOWN_MS
+        : PROBE_CACHE_TTL_MS;
+    if (Date.now() - entry.cachedAt > ttl) {
+        logSessionStart(`auto-install probe-cache ${toolId}: miss (${entry.transient ? "transient cooldown" : "ttl"} expired)`);
         delete cache[toolId];
         markProbeCacheChange(toolId, null);
         return undefined;
@@ -1545,7 +1643,7 @@ export async function checkProbeCache(toolId) {
     }
 }
 // Exported for testing only.
-export async function updateProbeCache(toolId, resolvedPath) {
+export async function updateProbeCache(toolId, resolvedPath, transient = false) {
     try {
         const stat = await fs.stat(resolvedPath);
         const cache = await readProbeCache();
@@ -1553,6 +1651,7 @@ export async function updateProbeCache(toolId, resolvedPath) {
             path: resolvedPath,
             mtimeMs: stat.mtimeMs,
             cachedAt: Date.now(),
+            ...(transient && { transient: true }),
         };
         cache[toolId] = entry;
         markProbeCacheChange(toolId, entry);
@@ -1569,10 +1668,13 @@ export function resetProbeCacheStateForTesting() {
     _probeCacheChangeVersions.clear();
     _probeCacheChangeGeneration = 0;
     _probeCacheRetryAttempt = 0;
-    resolvedPathCache.clear();
+    resetResolvedPathCache();
     ensureInFlight.clear();
     installFailureReasons.clear();
+    installAttempts.clear();
+    lastEnsureResolutionSource.clear();
     lastManagedInstallVersion.clear();
+    lastResolveTransient.clear();
     resetPathWalkMemo();
     if (_probeCacheFlushTimer !== null) {
         clearTimeout(_probeCacheFlushTimer);
@@ -1699,8 +1801,28 @@ const lastManagedInstallVersion = new Map();
  * `onVersionOutput`, when provided, receives the raw stdout on a successful
  * (exit 0) probe — used to piggyback version-pin drift detection onto this
  * already-happening spawn instead of adding a new one (#589).
+ *
+ * Exported so every managed-binary check runs THIS verification rather than a
+ * bare `existsSync` of its own: an on-disk shim that cannot run must not
+ * shadow a working PATH binary (#1657).
  */
-async function verifyToolBinary(binPath, onVersionOutput) {
+export async function verifyToolBinary(binPath, onVersionOutput, 
+/**
+ * Called when a `false` verdict came from a probe that never got a fair
+ * run — a spawn timeout/signal or a spawn-boundary EAGAIN/EBUSY/sync throw
+ * — rather than the binary actually rejecting `--version` (#1569). An
+ * unspawnable prober is never a durable verdict: a caller that falls
+ * through to a lower-priority candidate on one of these must not let the
+ * fallback's selection be trusted as if the preferred candidate were
+ * genuinely broken.
+ */
+onTransient, 
+/**
+ * Spawn budget, ms. Install paths keep the generous default; a latency-
+ * sensitive caller on the dispatch hot path passes a shorter one and treats
+ * the expiry as transient rather than as a verdict (#1657).
+ */
+timeoutMs = 10000) {
     return new Promise((resolve) => {
         const isWindows = installerPlatform() === "win32";
         const hasKnownWindowsExt = /\.(cmd|exe|ps1)$/i.test(binPath);
@@ -1726,7 +1848,7 @@ async function verifyToolBinary(binPath, onVersionOutput) {
         let proc;
         try {
             proc = spawn(spawnCmd, useShell ? [] : ["--version"], {
-                timeout: 10000,
+                timeout: timeoutMs,
                 stdio: ["ignore", "pipe", "pipe"],
                 shell: useShell,
             });
@@ -1734,7 +1856,9 @@ async function verifyToolBinary(binPath, onVersionOutput) {
         catch (err) {
             // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the pidusage
             // bug class, #533) — best-effort verify, resolve rather than reject.
+            // The prober itself never ran, so this says nothing about the binary.
             logSessionStart(`auto-install verify: spawn threw for ${binPath} (${err instanceof Error ? err.message : String(err)})`);
+            onTransient?.();
             resolve(false);
             return;
         }
@@ -1742,7 +1866,7 @@ async function verifyToolBinary(binPath, onVersionOutput) {
         let stderr = "";
         proc.stdout?.on("data", (data) => (stdout += data));
         proc.stderr?.on("data", (data) => (stderr += data));
-        proc.on("exit", (code) => {
+        proc.on("exit", (code, signal) => {
             if (code === 0) {
                 debugLog(`Verified: ${binPath} (version: ${stdout.trim()})`);
                 onVersionOutput?.(stdout);
@@ -1755,11 +1879,20 @@ async function verifyToolBinary(binPath, onVersionOutput) {
                 resolve(true);
             }
             else {
-                logSessionStart(`auto-install verify: failed for ${binPath} (exit=${code})`);
+                // `code === null` (usually paired with a `signal`) means the
+                // spawn timeout fired and the process was killed before it could
+                // exit on its own — a stall, not a verdict from the binary.
+                if (code === null || signal)
+                    onTransient?.();
+                logSessionStart(`auto-install verify: failed for ${binPath} (exit=${code}${signal ? `, signal=${signal}` : ""})`);
                 resolve(false);
             }
         });
         proc.on("error", (err) => {
+            const errno = err.code;
+            if (errno === "EAGAIN" || errno === "EBUSY" || errno === "ETIMEDOUT") {
+                onTransient?.();
+            }
             logSessionStart(`auto-install verify: error for ${binPath}: ${err.message}`);
             resolve(false);
         });
@@ -1958,7 +2091,47 @@ export function resolvePlatformPackageBinary(tool) {
     }
     return undefined;
 }
+/**
+ * Whether the most recent {@link getToolPath} resolution for a tool saw a
+ * transient probe failure on some candidate before landing on its answer
+ * (#1569). A side channel, in the same shape as `lastManagedInstallVersion`
+ * above: `getToolPath` keeps its `string | undefined` return so its many
+ * callers are untouched, and `ensureToolResolved` reads this immediately
+ * after awaiting it to decide how long the persisted probe-cache entry may
+ * be trusted for.
+ */
+const lastResolveTransient = new Map();
+/**
+ * The resolution identity the most recent install of each tool used — a GitHub
+ * release tag, a pinned archive URL, a Maven GAV (#1747).
+ *
+ * A side channel in the same shape as `lastManagedInstallVersion`: the install
+ * functions keep their `string | undefined` return, and `finishInstallAttempt`
+ * reads this to stamp the refresh state at install time. Without that stamp a
+ * freshly installed tool would look "never refreshed" and pay a redundant
+ * re-resolution the first time the cadence came round.
+ */
+const lastInstallResolutionId = new Map();
+/**
+ * True when the tool path `getToolPath` most recently returned for `toolId`
+ * was selected after a candidate tier failed transiently — a stalled or
+ * unspawnable probe, never a clean "not found". Such a selection may be a
+ * degraded fallback masking a preferred tier that is actually fine, so a
+ * caller persisting it must not trust it for the full 24h TTL (#1569).
+ */
+export function wasLastResolveTransient(toolId) {
+    return lastResolveTransient.get(toolId) ?? false;
+}
 export async function getToolPath(toolId) {
+    let sawTransient = false;
+    const markTransient = () => {
+        sawTransient = true;
+    };
+    const result = await getToolPathResolved(toolId, markTransient);
+    lastResolveTransient.set(toolId, sawTransient);
+    return result;
+}
+async function getToolPathResolved(toolId, onTransient) {
     const tool = TOOLS.find((t) => t.id === toolId);
     if (!tool)
         return undefined;
@@ -1995,7 +2168,7 @@ export async function getToolPath(toolId) {
         const cmdPath = `${localBase}.cmd`;
         try {
             await fs.access(cmdPath);
-            if (await verifyToolBinary(cmdPath, recordVersion)) {
+            if (await verifyToolBinary(cmdPath, recordVersion, onTransient)) {
                 return cmdPath;
             }
             logSessionStart(`auto-install verify: ${cmdPath} exists but is broken, will reinstall`);
@@ -2008,7 +2181,7 @@ export async function getToolPath(toolId) {
         const exePath = `${localBase}.exe`;
         try {
             await fs.access(exePath);
-            if (await verifyToolBinary(exePath, recordVersion)) {
+            if (await verifyToolBinary(exePath, recordVersion, onTransient)) {
                 return exePath;
             }
             logSessionStart(`auto-install verify: ${exePath} exists but is broken, will reinstall`);
@@ -2020,7 +2193,7 @@ export async function getToolPath(toolId) {
     if (installerPlatform() !== "win32") {
         try {
             await fs.access(localBase);
-            if (await verifyToolBinary(localBase, recordVersion)) {
+            if (await verifyToolBinary(localBase, recordVersion, onTransient)) {
                 return localBase;
             }
             logSessionStart(`auto-install verify: ${localBase} exists but is broken, will reinstall`);
@@ -2035,7 +2208,8 @@ export async function getToolPath(toolId) {
     // before falling back to PATH or a (re)install.
     if (tool.platformPackage) {
         const platformBin = resolvePlatformPackageBinary(tool);
-        if (platformBin && (await verifyToolBinary(platformBin))) {
+        if (platformBin &&
+            (await verifyToolBinary(platformBin, undefined, onTransient))) {
             logSessionStart(`auto-install ${toolId}: resolved platform-package binary at ${platformBin}`);
             return platformBin;
         }
@@ -2057,14 +2231,14 @@ export async function getToolPath(toolId) {
         return tool.checkCommand;
     }
     if (tool.installStrategy === "npm") {
-        const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id);
+        const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id, onTransient);
         if (npmPath) {
             return npmPath;
         }
     }
     // For pip tools, also probe user-level script locations
     if (tool.installStrategy === "pip") {
-        const pipPath = await findPipUserToolPath(tool.binaryName || tool.id);
+        const pipPath = await findPipUserToolPath(tool.binaryName || tool.id, onTransient);
         if (pipPath) {
             return pipPath;
         }
@@ -2122,9 +2296,9 @@ function getArchiveBinaryCandidates(binaryName, platform, assetName) {
     candidates.add(`${binaryName}.cmd`);
     return [...candidates];
 }
-async function findNpmGlobalToolPath(binaryName) {
+async function findNpmGlobalToolPath(binaryName, onTransient) {
     const isWindows = process.platform === "win32";
-    const binDirs = await getNpmGlobalBinCandidates();
+    const binDirs = await getNpmGlobalBinCandidates(onTransient);
     for (const dir of binDirs) {
         const candidates = isWindows
             ? [
@@ -2135,7 +2309,7 @@ async function findNpmGlobalToolPath(binaryName) {
         for (const candidate of candidates) {
             try {
                 await fs.access(candidate);
-                if (await verifyToolBinary(candidate)) {
+                if (await verifyToolBinary(candidate, undefined, onTransient)) {
                     return candidate;
                 }
             }
@@ -2146,7 +2320,7 @@ async function findNpmGlobalToolPath(binaryName) {
     }
     return undefined;
 }
-async function getNpmGlobalBinCandidates() {
+async function getNpmGlobalBinCandidates(onTransient) {
     const dirs = [];
     const seen = new Set();
     const add = (value) => {
@@ -2167,13 +2341,16 @@ async function getNpmGlobalBinCandidates() {
         add(path.join(os.homedir(), ".npm-global", "bin"));
     }
     // Global bin dirs for every installed manager (npm/pnpm/yarn/bun) — a tool
-    // may have been installed globally via any of them.
-    for (const dir of await allAvailableGlobalBinDirs()) {
+    // may have been installed globally via any of them. `onTransient` surfaces
+    // a manager whose availability probe stalled rather than genuinely failed,
+    // so its bin dir may be missing from `dirs` for a reason other than "not
+    // installed" (#1585).
+    for (const dir of await allAvailableGlobalBinDirs(onTransient)) {
         add(dir);
     }
     return dirs;
 }
-async function findPipUserToolPath(binaryName) {
+async function findPipUserToolPath(binaryName, onTransient) {
     const isWindows = process.platform === "win32";
     const userBaseCandidates = await getPythonUserBaseCandidates();
     for (const userBase of userBaseCandidates) {
@@ -2206,7 +2383,7 @@ async function findPipUserToolPath(binaryName) {
             for (const candidate of candidates) {
                 try {
                     await fs.access(candidate);
-                    if (await verifyToolBinary(candidate)) {
+                    if (await verifyToolBinary(candidate, undefined, onTransient)) {
                         return candidate;
                     }
                 }
@@ -2295,12 +2472,20 @@ function sameHost(a, b) {
     }
 }
 /**
- * Fetch a URL, following up to `maxRedirects` redirects.
- * Returns the raw Buffer of the response body. Any caller-supplied headers are
- * dropped when a redirect crosses to a different host, so an Authorization
- * header can never leak to a redirect target (e.g. a release CDN).
+ * Fetch a URL, following up to `maxRedirects` redirects, and surface the status
+ * line and `ETag` alongside the body.
+ *
+ * `304 Not Modified` resolves rather than rejects: the periodic GitHub
+ * re-resolution (#1747) sends `If-None-Match` and a 304 is its cheapest and
+ * most desirable answer — the release has not moved, no asset is downloaded,
+ * and GitHub does not charge the request against the caller's rate limit. Every
+ * other non-2xx status is still an error.
+ *
+ * Any caller-supplied headers are dropped when a redirect crosses to a
+ * different host, so an Authorization header can never leak to a redirect
+ * target (e.g. a release CDN).
  */
-function httpsGet(url, maxRedirects = 5, headers = {}) {
+function httpsGetWithMeta(url, maxRedirects = 5, headers = {}) {
     return new Promise((resolve, reject) => {
         https
             .get(url, { headers: { "User-Agent": "pi-lens/1.0", ...headers } }, (res) => {
@@ -2317,7 +2502,12 @@ function httpsGet(url, maxRedirects = 5, headers = {}) {
                         const { Authorization: _drop, ...rest } = headers;
                         return rest;
                     })();
-                return resolve(httpsGet(location, maxRedirects - 1, nextHeaders));
+                return resolve(httpsGetWithMeta(location, maxRedirects - 1, nextHeaders));
+            }
+            const etag = typeof res.headers.etag === "string" ? res.headers.etag : undefined;
+            if (res.statusCode === 304) {
+                res.resume();
+                return resolve({ statusCode: 304, body: Buffer.alloc(0), etag });
             }
             if (res.statusCode !== 200) {
                 res.resume();
@@ -2325,12 +2515,24 @@ function httpsGet(url, maxRedirects = 5, headers = {}) {
             }
             const chunks = [];
             res.on("data", (chunk) => chunks.push(chunk));
-            res.on("end", () => resolve(Buffer.concat(chunks)));
+            res.on("end", () => resolve({ statusCode: 200, body: Buffer.concat(chunks), etag }));
             res.on("error", reject);
         })
             .on("error", reject);
     });
 }
+/**
+ * Fetch a URL and return the raw Buffer of the response body. Rejects on any
+ * non-200 status (a 304 is impossible here — no caller of this form sends a
+ * validator header).
+ */
+async function httpsGet(url, maxRedirects = 5, headers = {}) {
+    const response = await httpsGetWithMeta(url, maxRedirects, headers);
+    if (response.statusCode !== 200) {
+        throw new Error(`HTTP ${response.statusCode} for ${url}`);
+    }
+    return response.body;
+}
 /**
  * Run a shell command and return true on exit code 0.
  */
@@ -2358,7 +2560,14 @@ function runCommand(command, args, cwd) {
  * Download and install a tool from a GitHub release.
  * Returns the path to the installed binary, or undefined on failure.
  */
-async function installGitHubTool(tool) {
+async function installGitHubTool(tool, 
+/**
+ * Release metadata the caller already fetched. The periodic refresh (#1747)
+ * resolves `releases/latest` to decide whether the tag moved at all, and
+ * hands the SAME response here rather than paying a second GitHub API call
+ * for an answer it already has.
+ */
+prefetchedRelease) {
     const spec = tool.github;
     if (!spec)
         return undefined;
@@ -2369,15 +2578,35 @@ async function installGitHubTool(tool) {
         logSessionStart(`github-install ${tool.id}: unsupported platform=${platform} arch=${arch}`);
         return undefined;
     }
-    // Fetch latest release metadata from GitHub API
-    logSessionStart(`github-install ${tool.id}: fetching release metadata from ${spec.repo}`);
+    // Fetch latest release metadata from GitHub API, unless the caller already did.
     let releaseJson;
-    try {
-        const body = await httpsGet(`https://api.github.com/repos/${spec.repo}/releases/latest`, 5, githubApiAuthHeaders());
-        releaseJson = JSON.parse(body.toString("utf8"));
+    if (prefetchedRelease) {
+        releaseJson = prefetchedRelease;
+        logSessionStart(`github-install ${tool.id}: using caller-supplied release metadata for ${spec.repo} (${prefetchedRelease.tag_name ?? "untagged"})`);
     }
-    catch (err) {
-        logSessionStart(`github-install ${tool.id}: release fetch failed: ${err.message}`);
+    else {
+        logSessionStart(`github-install ${tool.id}: fetching release metadata from ${spec.repo}`);
+        try {
+            const body = await httpsGet(`https://api.github.com/repos/${spec.repo}/releases/latest`, 5, githubApiAuthHeaders());
+            releaseJson = JSON.parse(body.toString("utf8"));
+        }
+        catch (err) {
+            logSessionStart(`github-install ${tool.id}: release fetch failed: ${err.message}`);
+            return undefined;
+        }
+    }
+    if (releaseJson.tag_name) {
+        lastInstallResolutionId.set(tool.id, releaseJson.tag_name);
+    }
+    // #1759 review F3: a 200 whose body has no `assets` array (an unexpected
+    // GitHub API shape, not a real release) used to reach `pickReleaseAsset`
+    // and throw inside `.find`, uncaught by anything in this function. For the
+    // REFRESH caller that throw skipped every stamp write, so the tool never
+    // got a failure stamp and re-took the one-per-session slot forever. Failing
+    // here, like a missing asset match, keeps this an ordinary "no install"
+    // outcome both callers already handle.
+    if (!Array.isArray(releaseJson.assets)) {
+        logSessionStart(`github-install ${tool.id}: release metadata has no assets array`);
         return undefined;
     }
     const asset = pickReleaseAsset(releaseJson.assets, assetSubstring) ??
@@ -2416,7 +2645,10 @@ async function installGitHubTool(tool) {
                 gunzip.on("error", reject);
                 gunzip.end(assetBuffer);
             });
-            await fs.writeFile(destPath, decompressed, { mode: 0o750 });
+            await writeFileAtomicAsync(destPath, decompressed, {
+                bestEffort: false,
+                mode: 0o750,
+            });
         }
         else if (assetName.endsWith(".tar.gz") || assetName.endsWith(".tar.xz")) {
             // Write archive to temp file, extract with system tar
@@ -2483,7 +2715,10 @@ async function installGitHubTool(tool) {
         }
         else {
             // Bare binary (e.g. shfmt_*_linux_amd64)
-            await fs.writeFile(destPath, assetBuffer, { mode: 0o750 });
+            await writeFileAtomicAsync(destPath, assetBuffer, {
+                bestEffort: false,
+                mode: 0o750,
+            });
         }
     }
     catch (err) {
@@ -2501,9 +2736,7 @@ async function installGitHubTool(tool) {
         }
         try {
             const extraBuffer = await httpsGet(extraAsset.browser_download_url);
-            await fs.writeFile(path.join(GITHUB_BIN_DIR, extraName), extraBuffer, {
-                mode: 0o750,
-            });
+            await writeFileAtomicAsync(path.join(GITHUB_BIN_DIR, extraName), extraBuffer, { bestEffort: false, mode: 0o750 });
             logSessionStart(`github-install ${tool.id}: installed extra asset ${extraName} (${extraBuffer.length} bytes)`);
         }
         catch (err) {
@@ -2546,6 +2779,581 @@ const NEEDS_POSTINSTALL = new Set([
     "esbuild",
     "intelephense", // postinstall fetches platform binary; --ignore-scripts breaks install
 ]);
+/**
+ * Does this npm package need its lifecycle scripts to install correctly?
+ *
+ * Exported so the periodic refresh (#1730) re-runs each package under the SAME
+ * script policy its original install used. A refresh that drops
+ * `--ignore-scripts` for biome or `@ast-grep/cli` leaves the JS launcher
+ * updated and its native binary on the old version.
+ */
+export function npmToolNeedsPostinstall(packageName) {
+    return NEEDS_POSTINSTALL.has(packageName);
+}
+/**
+ * The managed npm tools whose installed version is free to move — every
+ * registry entry with `installStrategy: "npm"` and an UNPINNED `packageName`.
+ *
+ * Derived from `TOOLS` on every call rather than listed by hand: a hand-kept
+ * copy of a registry is the single-source-of-truth defect this repo keeps
+ * finding, and a new npm tool added to `TOOLS` must be refreshed without anyone
+ * remembering a second list.
+ *
+ * Packages carrying an explicit `name@1.2.3` pin are excluded. The pin IS the
+ * intended version, and #589's drift check already reinstalls a managed copy
+ * that wanders off it.
+ */
+export function getRefreshableManagedNpmTools() {
+    return getRefreshableManagedTools()
+        .filter((candidate) => candidate.strategy === "npm")
+        .map((candidate) => ({
+        toolId: candidate.toolId,
+        // The npm branch of getRefreshableManagedTools only admits entries that
+        // have both, so these are total.
+        packageName: candidate.packageName,
+        binaryName: candidate.binaryName,
+    }));
+}
+/** The Maven GAV a `maven` entry pins, as a stable identity string. */
+function mavenCoordinate(spec) {
+    return [
+        spec.repoBaseUrl ?? MAVEN_CENTRAL_BASE,
+        spec.groupId,
+        spec.artifactId,
+        spec.version,
+        spec.classifier ?? "",
+    ].join(":");
+}
+/**
+ * Every managed tool whose installed copy is allowed to move, across ALL six
+ * install strategies — the single source of truth the periodic refresh selects
+ * from (#1730, #1747).
+ *
+ * Derived from `TOOLS` on every call rather than listed by hand. A hand-kept
+ * copy of a registry is the defect shape this repo keeps re-finding, and a tool
+ * added to `TOOLS` must become refreshable without anyone remembering a second
+ * list.
+ *
+ * Excluded: npm packages carrying an explicit `name@1.2.3` pin (the pin IS the
+ * intended version, and #589's drift check already repairs those), and any
+ * entry with no coordinate to re-resolve at all.
+ */
+export function getRefreshableManagedTools() {
+    const refreshable = [];
+    for (const tool of TOOLS) {
+        switch (tool.installStrategy) {
+            case "npm": {
+                if (!tool.packageName)
+                    continue;
+                if (parsePinnedVersion(tool.packageName) !== undefined)
+                    continue;
+                // `binaryName` is what `installNpmTool` verifies after an install, and
+                // the refresh has to verify the SAME path after an update. An npm
+                // entry without one cannot be verified, so it is not refreshed either.
+                if (!tool.binaryName)
+                    continue;
+                refreshable.push({
+                    toolId: tool.id,
+                    strategy: "npm",
+                    packageName: tool.packageName,
+                    binaryName: tool.binaryName,
+                });
+                break;
+            }
+            case "pip":
+            case "gem": {
+                if (!tool.packageName)
+                    continue;
+                refreshable.push({
+                    toolId: tool.id,
+                    strategy: tool.installStrategy,
+                    packageName: tool.packageName,
+                });
+                break;
+            }
+            case "github": {
+                if (!tool.github)
+                    continue;
+                refreshable.push({ toolId: tool.id, strategy: "github" });
+                break;
+            }
+            case "maven": {
+                if (!tool.maven)
+                    continue;
+                refreshable.push({
+                    toolId: tool.id,
+                    strategy: "maven",
+                    pinnedCoordinate: mavenCoordinate(tool.maven),
+                });
+                break;
+            }
+            case "archive": {
+                if (!tool.archive)
+                    continue;
+                const url = resolveArchiveUrl(tool.archive);
+                // No archive for this platform/arch: nothing is installed and nothing
+                // can be refreshed.
+                if (!url)
+                    continue;
+                refreshable.push({
+                    toolId: tool.id,
+                    strategy: "archive",
+                    pinnedCoordinate: url,
+                });
+                break;
+            }
+        }
+    }
+    return refreshable;
+}
+/**
+ * Is this tool present in a location pi-lens itself installs to?
+ *
+ * Deliberately filesystem-only — no spawn, no network. The refresh runs this
+ * over candidates on a background timer, and a presence check that spawned a
+ * probe per tool would cost more than the refresh it gates.
+ *
+ * A tool pi-lens has never installed is never refreshed: `pip install -U` or a
+ * release download on an absent tool would turn a refresh into an unrequested
+ * install.
+ */
+export async function isManagedToolPresent(toolId) {
+    const tool = TOOLS.find((t) => t.id === toolId);
+    if (!tool)
+        return false;
+    switch (tool.installStrategy) {
+        case "npm": {
+            if (!tool.packageName)
+                return false;
+            try {
+                await fs.access(path.join(TOOLS_DIR, "node_modules", tool.packageName, "package.json"));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        case "github":
+        case "maven":
+            return ((await findGitHubToolPath(tool.binaryName ?? tool.id)) !== undefined);
+        case "archive":
+            // A launcher archive leaves a shim in the managed bin; a TREE BUNDLE
+            // leaves only its extract dir, confirmed via the tree marker.
+            return ((await findGitHubToolPath(tool.binaryName ?? tool.id)) !== undefined ||
+                (await getArchiveTreeBundlePath(tool)) !== undefined);
+        case "pip":
+        case "gem": {
+            // pip/gem installs are not namespaced to pi-lens: they land in the
+            // user's site/gem dirs, so there is no pi-lens-owned directory to look
+            // in. The persisted probe cache is the record of where this tool last
+            // resolved, and it is written from the same discovery pass the install
+            // path uses. An entry whose file is gone is not presence.
+            const cached = (await readProbeCache())[toolId];
+            return cached?.path !== undefined && existsSync(cached.path);
+        }
+        default:
+            return false;
+    }
+}
+/**
+ * Version this tool reports today, read by running its own `--version` probe.
+ *
+ * Only used for `pip` and `gem`, the two strategies with no readable
+ * coordinate: their package managers install into user-owned directories with
+ * no manifest pi-lens can read, so the binary itself is the only source. Costs
+ * one spawn, bounded by the same one-tool-per-session budget as the refresh.
+ */
+async function probeManagedToolVersion(tool) {
+    const cached = (await readProbeCache())[tool.id];
+    if (!cached?.path || !existsSync(cached.path))
+        return undefined;
+    try {
+        const result = await safeSpawnAsync(cached.path, tool.checkArgs, {
+            timeout: 10_000,
+            ignoreAmbientSignal: true,
+            resourceLabel: `tool-refresh-version:${tool.id}`,
+        });
+        if (result.status !== 0)
+            return undefined;
+        return extractVersionToken(`${result.stdout}\n${result.stderr}`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The three checks every install-triggering path must clear before touching
+ * `TOOLS_DIR`: the `PI_LENS_DISABLE_TOOL_INSTALL` kill-switch, the
+ * `assertInstallAllowed` project-trust gate (the #1334 S5 boundary), and the
+ * shared install lock — acquired here, released by the caller when its
+ * strategy work finishes.
+ *
+ * Shared by `refreshManagedTool` below (the five non-npm strategies) and
+ * `refreshNpmOne` in `managed-tool-refresh.ts` (#1759 review R2), so a
+ * refusal means the same thing everywhere — a declined, unstamped skip, not
+ * a degradation — regardless of which of the six strategies asked. Before
+ * this was pulled out as its own function, npm's refresh spawned `npm
+ * update` directly with none of these three checks: the kill switch, the
+ * trust gate and the lock governed five strategies and silently exempted
+ * the sixth.
+ */
+export async function acquireManagedInstallGate(context) {
+    if (process.env.PI_LENS_DISABLE_TOOL_INSTALL === "1") {
+        return {
+            ok: false,
+            reason: "installation disabled by PI_LENS_DISABLE_TOOL_INSTALL=1",
+        };
+    }
+    if (!assertInstallAllowed(context)) {
+        return { ok: false, reason: `project trust: ${projectTrustDenialReason()}` };
+    }
+    // Held for the whole strategy call, not just the final write — a refresh
+    // can race a concurrent `ensureTool` install of the SAME tool into the SAME
+    // managed destination, and both write to `TOOLS_DIR` unlocked otherwise.
+    const lock = await acquireInstallLock();
+    if (!lock.release) {
+        return { ok: false, reason: lock.reason ?? "install lock held" };
+    }
+    return { ok: true, release: lock.release };
+}
+/**
+ * Re-resolve one non-npm managed tool and, only if its coordinate actually
+ * moved, reinstall it (#1747).
+ *
+ * Never throws and never removes the installed copy: on any failure the
+ * currently installed version keeps serving and the caller records a
+ * degradation. npm is NOT handled here — `managed-tool-refresh.ts` owns that
+ * path because it needs the package-manager resolver, and gates itself
+ * through `acquireManagedInstallGate` directly.
+ *
+ * #1759 review F2: this used to call the strategy functions directly, which
+ * bypassed every install guard `installTool`/`ensureTool` honor —
+ * `PI_LENS_DISABLE_TOOL_INSTALL`, the `assertInstallAllowed` project-trust
+ * gate (the #1334 S5 boundary), and `acquireInstallLock`. A refresh IS an
+ * install trigger, just an unattended one, so it now passes through the same
+ * three gates before any strategy runs. A refusal is `declined: true`, not a
+ * degradation — see `ManagedToolRefreshAttempt.declined`.
+ */
+export async function refreshManagedTool(toolId, known = {}) {
+    const tool = TOOLS.find((t) => t.id === toolId);
+    if (!tool) {
+        return { ok: false, unchanged: true, reason: "unknown tool id" };
+    }
+    if (tool.installStrategy !== "github" &&
+        tool.installStrategy !== "pip" &&
+        tool.installStrategy !== "gem" &&
+        tool.installStrategy !== "maven" &&
+        tool.installStrategy !== "archive") {
+        return {
+            ok: false,
+            unchanged: true,
+            reason: `strategy ${tool.installStrategy} is not refreshable here`,
+        };
+    }
+    // Captured into a local so the narrowing above survives the `await` below —
+    // TS drops property narrowing (`tool.installStrategy`) across an `await`,
+    // which would otherwise make the switch look non-exhaustive.
+    const strategy = tool.installStrategy;
+    const gate = await acquireManagedInstallGate(`managed tool refresh: ${toolId}`);
+    if (!gate.ok) {
+        return { ok: false, unchanged: true, declined: true, reason: gate.reason };
+    }
+    try {
+        switch (strategy) {
+            case "github":
+                return await refreshGitHubManagedTool(tool, known);
+            case "pip":
+            case "gem":
+                return await refreshPackageManagerManagedTool(tool);
+            case "maven":
+            case "archive":
+                return await refreshPinnedManagedTool(tool, known);
+            default:
+                return {
+                    ok: false,
+                    unchanged: true,
+                    reason: `strategy ${strategy} is not refreshable here`,
+                };
+        }
+    }
+    finally {
+        await gate.release?.();
+    }
+}
+/**
+ * `github`: ask `releases/latest` whether the tag moved, and download only if
+ * it did.
+ *
+ * Three things keep 27 GitHub-release tools off GitHub's rate limit. The
+ * per-tool weekly stamp means one query per tool per week; the one-refresh-per-
+ * session budget means at most one query per session; and the stored `ETag`
+ * replayed as `If-None-Match` makes the common answer a 304, which GitHub does
+ * not charge against the limit at all. A 304, or a tag equal to the recorded
+ * one, downloads nothing.
+ */
+async function refreshGitHubManagedTool(tool, known) {
+    const spec = tool.github;
+    if (!spec)
+        return { ok: false, unchanged: true, reason: "no github spec" };
+    let response;
+    try {
+        response = await httpsGetWithMeta(`https://api.github.com/repos/${spec.repo}/releases/latest`, 5, {
+            ...githubApiAuthHeaders(),
+            ...(known.etag ? { "If-None-Match": known.etag } : {}),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            unchanged: true,
+            reason: `release query failed: ${err.message}`,
+        };
+    }
+    if (response.statusCode === 304) {
+        return {
+            ok: true,
+            unchanged: true,
+            resolutionId: known.resolutionId,
+            etag: known.etag,
+            version: known.version,
+        };
+    }
+    let release;
+    try {
+        const parsed = JSON.parse(response.body.toString("utf8"));
+        // #1759 review F3: `JSON.parse` succeeds on `null`, an array, or a bare
+        // string just as happily as on an object — any of those would throw
+        // reading `.tag_name` below, uncaught, and skip every stamp write this
+        // candidate ever gets. Reject the shape here instead of downstream.
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("release metadata is not an object");
+        }
+        release = parsed;
+    }
+    catch (err) {
+        return {
+            ok: false,
+            unchanged: true,
+            reason: `release metadata unparseable: ${err.message}`,
+        };
+    }
+    const tag = release.tag_name;
+    if (!tag) {
+        return { ok: false, unchanged: true, reason: "release has no tag_name" };
+    }
+    if (known.resolutionId === tag) {
+        return {
+            ok: true,
+            unchanged: true,
+            resolutionId: tag,
+            etag: response.etag ?? known.etag,
+            version: known.version ?? tag,
+        };
+    }
+    const installed = await installGitHubTool(tool, release);
+    if (!installed) {
+        return {
+            ok: false,
+            unchanged: true,
+            // Keep the ETag off the failure stamp: replaying it would make the next
+            // attempt a 304 and skip the download this one never completed.
+            resolutionId: known.resolutionId,
+            version: known.version,
+            reason: `install from release ${tag} failed`,
+        };
+    }
+    const verified = await verifyRefreshedArtifact(tool, installed);
+    if (!verified) {
+        return {
+            ok: false,
+            unchanged: false,
+            resolutionId: known.resolutionId,
+            version: known.version,
+            reason: `release ${tag} installed but its binary does not run`,
+        };
+    }
+    return {
+        ok: true,
+        unchanged: false,
+        resolutionId: tag,
+        etag: response.etag,
+        version: tag,
+    };
+}
+/**
+ * Confirm a just-refreshed artifact still runs, and re-stamp the probe cache
+ * with its new mtime.
+ *
+ * A refresh REPLACES a working binary in place. Without this check a release
+ * that ships a broken or wrong-architecture asset would be written over a
+ * healthy copy and surface later as a dispatch failure with no obvious cause.
+ * The verdict goes back to the caller, which degrades and marks the stamp
+ * failed so the shorter retry cooldown applies.
+ *
+ * An archive TREE BUNDLE has no single binary to run; `installArchiveTool`
+ * already confirms its tree marker, so the install's own success is the check.
+ */
+async function verifyRefreshedArtifact(tool, installedPath) {
+    if (tool.installStrategy === "archive" && !tool.archive?.launcher) {
+        // A tree bundle has no single binary to run — `installArchiveTool` already
+        // confirmed its tree marker — but it still needs its NEW mtime recorded
+        // (#1759 review F7), or the persisted probe entry keeps the pre-refresh
+        // mtime and forces a full re-resolution on the next dispatch anyway.
+        await updateProbeCache(tool.id, installedPath);
+        return true;
+    }
+    if (!(await verifyToolBinary(installedPath))) {
+        logSessionStart(`managed-tool-refresh ${tool.id}: refreshed artifact at ${installedPath} failed its --version check`);
+        return false;
+    }
+    // Record the NEW mtime rather than leaving the persisted entry to miss its
+    // mtime check and force a full re-resolution on the next dispatch.
+    await updateProbeCache(tool.id, installedPath);
+    return true;
+}
+/**
+ * `pip` and `gem`: re-run pi-lens's own install command in upgrade form.
+ *
+ * There is no coordinate to compare first — the registry pins no version and
+ * the package managers install into user-owned directories with no manifest
+ * pi-lens can read — so the tool's own `--version` output before and after is
+ * what says whether anything moved.
+ */
+async function refreshPackageManagerManagedTool(tool) {
+    if (!tool.packageName) {
+        return { ok: false, unchanged: true, reason: "no package name" };
+    }
+    const previous = await probeManagedToolVersion(tool);
+    const installed = tool.installStrategy === "pip"
+        ? // `-U` is the whole fix: without it pip treats the installed copy as
+            // satisfying the requirement and the day-one version never moves.
+            await installPipTool(tool.packageName, { upgrade: true })
+        : // `gem install` always fetches the newest version that satisfies the
+            // requirement, so the install command IS the upgrade command.
+            await installGemTool(tool.packageName);
+    if (!installed) {
+        return {
+            ok: false,
+            unchanged: true,
+            version: previous,
+            reason: `${tool.installStrategy} upgrade failed`,
+        };
+    }
+    const current = await probeManagedToolVersion(tool);
+    if (previous !== undefined && current === undefined) {
+        // The tool answered `--version` before the upgrade and does not now: the
+        // upgrade replaced a working copy with a broken one. Say so rather than
+        // stamping success on a tool that no longer runs.
+        return {
+            ok: false,
+            unchanged: false,
+            version: previous,
+            reason: `${tool.installStrategy} upgrade left the binary unable to report a version`,
+        };
+    }
+    return {
+        ok: true,
+        // An unreadable version on both sides cannot prove a move, so it reads as
+        // unchanged rather than inventing one.
+        unchanged: previous === undefined || current === undefined || previous === current,
+        version: current ?? previous,
+    };
+}
+/**
+ * `maven` and `archive`: both pin an explicit version in THIS registry, so
+ * their coordinate cannot move upstream — it moves when pi-lens bumps it.
+ *
+ * The freeze for these two is therefore the mirror image of the npm one: the
+ * installer only installs when the tool is ABSENT, so a repo that bumps
+ * spotbugs from 4.10.2 to 4.11.0 leaves every existing machine on 4.10.2
+ * forever. Comparing the recorded coordinate against the registry's current one
+ * catches exactly that, and costs no network when they match.
+ *
+ * A tool with no recorded coordinate is reinstalled once. pi-lens cannot read
+ * which pin the installed artifact came from — an archive bundle carries no
+ * manifest it writes — so the only way to make the installed copy provably
+ * match the declared pin is to install it. That happens at most once per tool,
+ * ever, and the stamp it writes suppresses it from then on.
+ */
+async function refreshPinnedManagedTool(tool, known) {
+    const coordinate = tool.installStrategy === "maven"
+        ? tool.maven && mavenCoordinate(tool.maven)
+        : tool.archive && resolveArchiveUrl(tool.archive);
+    if (!coordinate) {
+        return {
+            ok: false,
+            unchanged: true,
+            reason: "no coordinate for this platform",
+        };
+    }
+    if (known.resolutionId === coordinate) {
+        return {
+            ok: true,
+            unchanged: true,
+            resolutionId: coordinate,
+            version: known.version,
+        };
+    }
+    const installed = tool.installStrategy === "maven"
+        ? await installMavenTool(tool)
+        : await installArchiveTool(tool);
+    if (!installed) {
+        return {
+            ok: false,
+            unchanged: true,
+            resolutionId: known.resolutionId,
+            version: known.version,
+            reason: `reinstall from ${coordinate} failed`,
+        };
+    }
+    if (!(await verifyRefreshedArtifact(tool, installed))) {
+        return {
+            ok: false,
+            unchanged: false,
+            resolutionId: known.resolutionId,
+            version: known.version,
+            reason: `reinstall from ${coordinate} produced an artifact that does not run`,
+        };
+    }
+    return {
+        ok: true,
+        // A first-ever stamp is an adoption, not a version move: the coordinate did
+        // not change, pi-lens simply had no record of it. Reporting it as a move
+        // would put a false "x → y" row in the log.
+        unchanged: known.resolutionId === undefined,
+        resolutionId: coordinate,
+        version: coordinate,
+    };
+}
+/**
+ * The managed `node_modules/.bin` path for a tool binary, spelled the way
+ * `installNpmTool` spells it (npm writes a `.cmd` shim on Windows, and that
+ * shim — not its extensionless POSIX sibling — is the executable).
+ *
+ * Exported so the periodic refresh (#1730) verifies the same path the install
+ * verified, instead of rebuilding the convention next to it.
+ */
+export function resolveManagedNpmBinPath(binaryName) {
+    const binBase = path.join(TOOLS_DIR, "node_modules", ".bin", binaryName);
+    return installerPlatform() === "win32" ? `${binBase}.cmd` : binBase;
+}
+/**
+ * Drop every cached claim about where a tool resolves: the in-memory
+ * resolved-path cache and the 24h on-disk probe cache.
+ *
+ * The probe cache keys on the binary's path and mtime, and a package-manager
+ * update rewrites the package while frequently leaving the `.bin` shim's mtime
+ * alone. Without this, a refresh that changed the version — or left a binary
+ * that no longer runs — kept serving the previous answer from cache for up to
+ * a day (#1746 review F2). Callers fall through to a fresh probe, which is the
+ * path that can repair a broken install.
+ */
+export function invalidateManagedToolResolution(toolId) {
+    resolvedPathCache.delete(toolId);
+    if (_probeCache !== null)
+        delete _probeCache[toolId];
+    markProbeCacheChange(toolId, null);
+}
 const MAVEN_CENTRAL_BASE = "https://repo1.maven.org/maven2";
 /**
  * Install a Maven-distributed runnable fat JAR: download it into the managed bin
@@ -2571,6 +3379,7 @@ async function installMavenTool(tool) {
     const groupPath = spec.groupId.replace(/\./g, "/");
     const jarFile = `${spec.artifactId}-${spec.version}${spec.classifier ? `-${spec.classifier}` : ""}.jar`;
     const url = `${base}/${groupPath}/${spec.artifactId}/${spec.version}/${jarFile}`;
+    lastInstallResolutionId.set(tool.id, mavenCoordinate(spec));
     logSessionStart(`maven-install ${tool.id}: downloading ${url}`);
     let jarBuffer;
     try {
@@ -2583,15 +3392,15 @@ async function installMavenTool(tool) {
     try {
         await fs.mkdir(GITHUB_BIN_DIR, { recursive: true });
         const jarPath = path.join(GITHUB_BIN_DIR, `${tool.id}.jar`);
-        await fs.writeFile(jarPath, jarBuffer);
+        await writeFileAtomicAsync(jarPath, jarBuffer, { bestEffort: false });
         // Launcher so the tool resolves as a normal command in the managed bin.
         const launcherName = isWindows ? `${binaryName}.bat` : binaryName;
         const launcherPath = path.join(GITHUB_BIN_DIR, launcherName);
         if (isWindows) {
-            await fs.writeFile(launcherPath, `@echo off\r\njava -jar "%~dp0${tool.id}.jar" %*\r\n`);
+            await writeFileAtomicAsync(launcherPath, `@echo off\r\njava -jar "%~dp0${tool.id}.jar" %*\r\n`, { bestEffort: false });
         }
         else {
-            await fs.writeFile(launcherPath, `#!/bin/sh\nexec java -jar "$(dirname "$0")/${tool.id}.jar" "$@"\n`, { mode: 0o750 });
+            await writeFileAtomicAsync(launcherPath, `#!/bin/sh\nexec java -jar "$(dirname "$0")/${tool.id}.jar" "$@"\n`, { bestEffort: false, mode: 0o750 });
         }
         logSessionStart(`maven-install ${tool.id}: installed → ${launcherPath} (${jarBuffer.length} bytes)`);
         debugLog(`[maven] installed ${tool.name} → ${launcherPath}`);
@@ -2619,6 +3428,76 @@ async function installMavenTool(tool) {
 export function resolveArchiveUrl(spec, platform = process.platform, arch = process.arch) {
     return typeof spec.url === "function" ? spec.url(platform, arch) : spec.url;
 }
+/**
+ * Move a verified-good extracted tree into its final, stable location without
+ * ever leaving `finalDir` empty or missing while a working copy was there
+ * (#1759 review F1).
+ *
+ * Both renames are same-volume directory renames (TOOLS_DIR never spans a
+ * filesystem boundary here), so each one individually is as close to atomic
+ * as the OS gives us. The gap between them — `finalDir` briefly absent — is
+ * unavoidable without OS-level directory-swap support, but it is now
+ * MICROSECONDS, not "however long the network download and tar extraction
+ * take", and a failure on the second rename restores the backup rather than
+ * leaving `finalDir` gone.
+ *
+ * Worst case (#1759 review R4): the second rename AND the rollback rename it
+ * triggers both fail (e.g. the volume went read-only mid-swap). `finalDir` is
+ * then genuinely empty and the only surviving copy sits at `finalDir.rollback`
+ * — this function still throws either way, so the caller's install/refresh
+ * reports failure rather than success, and `invalidateManagedToolResolution`
+ * on that failure path (#1759 review F1) is what actually recovers: it drops
+ * the cached resolved path, so the next `ensureTool` probe finds nothing at
+ * `finalDir`, treats the tool as absent, and reinstalls from scratch. The
+ * orphaned `.rollback` directory is NOT reclaimed by that reinstall — it is
+ * only cleaned up the next time `swapExtractedDir` runs a SUCCESSFUL swap for
+ * this same tool (the unconditional `fs.rm(backupDir, ...)` below), so it can
+ * sit on disk for a while. The degradation this records below is what makes
+ * that orphan discoverable rather than a silent leak.
+ */
+// Exported for the rollback-path unit test (#1759 review R3) — the failure
+// this guards is only reachable by making the SECOND rename throw, which a
+// full `installArchiveTool` run has no test-controlled pause point to force
+// without mocking `node:fs` wholesale.
+export async function swapExtractedDir(toolId, tmpDir, finalDir) {
+    const backupDir = `${finalDir}.rollback`;
+    await fs.rm(backupDir, { recursive: true, force: true });
+    let hadPrevious = false;
+    try {
+        await fs.rename(finalDir, backupDir);
+        hadPrevious = true;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    try {
+        await fs.rename(tmpDir, finalDir);
+    }
+    catch (err) {
+        if (hadPrevious) {
+            try {
+                await fs.rename(backupDir, finalDir);
+            }
+            catch (rollbackErr) {
+                // The double-failure worst case: `finalDir` is empty and the only
+                // surviving copy is the orphan at `backupDir`. Record it — this is
+                // the one path where a swallowed catch here would make that orphan
+                // invisible, not just inconvenient.
+                recordDegradationOnce({
+                    kind: "managed-tool-refresh",
+                    subject: toolId,
+                    reason: `swap rollback failed after a failed install: working copy orphaned at ${backupDir} (${rollbackErr.message})`,
+                });
+                logSessionStart(`archive-install ${toolId}: swap rollback failed — working copy orphaned at ${backupDir} (${rollbackErr.message})`);
+            }
+        }
+        throw err;
+    }
+    if (hadPrevious) {
+        await fs.rm(backupDir, { recursive: true, force: true }).catch(() => { });
+    }
+}
 async function installArchiveTool(tool) {
     const spec = tool.archive;
     if (!spec)
@@ -2630,6 +3509,7 @@ async function installArchiveTool(tool) {
         logSessionStart(`archive-install ${tool.id}: no archive for ${process.platform}/${process.arch} — unsupported, skipping`);
         return undefined;
     }
+    lastInstallResolutionId.set(tool.id, url);
     logSessionStart(`archive-install ${tool.id}: downloading ${url}`);
     let archiveBuffer;
     try {
@@ -2644,15 +3524,27 @@ async function installArchiveTool(tool) {
     // `host:path` ("Cannot connect to C:"). Relative paths work for both GNU tar
     // and Windows bsdtar, so we avoid the GNU-only `--force-local` (which bsdtar
     // rejects). fs.* calls still use the absolute paths.
+    //
+    // #1759 review F1: extraction and verification happen in a TMP dir, never
+    // in `extractDir` itself. `extractDir` is the location a refresh's caller
+    // (and every prior session) is currently serving from; the old code
+    // `fs.rm`'d it before extraction even started, so a corrupt download or a
+    // failed tar left the tool GONE rather than "kept the installed version" —
+    // exactly the outcome the failure log line claimed did not happen. The
+    // installed copy is now untouched until the replacement is proven good.
     const extractName = tool.id;
+    const tmpExtractName = `${extractName}.refresh-tmp`;
     const archiveName = `${tool.id}.download.${spec.kind === "zip" ? "zip" : "tgz"}`;
     const extractDir = path.join(TOOLS_DIR, extractName);
+    const tmpExtractDir = path.join(TOOLS_DIR, tmpExtractName);
     const tmpArchive = path.join(TOOLS_DIR, archiveName);
     try {
         await fs.mkdir(TOOLS_DIR, { recursive: true });
-        // Clear any prior extraction so a reinstall is clean.
-        await fs.rm(extractDir, { recursive: true, force: true });
-        await fs.mkdir(extractDir, { recursive: true });
+        // Clear any stale tmp dir from an interrupted prior attempt — this is the
+        // SCRATCH location, never the live install, so clearing it never risks the
+        // working copy.
+        await fs.rm(tmpExtractDir, { recursive: true, force: true });
+        await fs.mkdir(tmpExtractDir, { recursive: true });
         await fs.writeFile(tmpArchive, archiveBuffer);
         // `--strip-components=N` drops N leading path components. Default 1 drops a
         // versioned top-level dir so a launcher path stays stable (bin/… not
@@ -2664,10 +3556,8 @@ async function installArchiveTool(tool) {
             spec.kind === "tgz" ? "-xzf" : "-xf",
             archiveName,
             "-C",
-            extractName,
-            ...(stripComponents > 0
-                ? [`--strip-components=${stripComponents}`]
-                : []),
+            tmpExtractName,
+            ...(stripComponents > 0 ? [`--strip-components=${stripComponents}`] : []),
         ];
         // Resolve `tar` to an absolute path on Windows (System32\tar.exe is the
         // bsdtar shipped with Windows 10+) so extraction can't be hijacked via a
@@ -2689,39 +3579,54 @@ async function installArchiveTool(tool) {
         };
         await fs.rm(tmpArchive, { force: true });
         if (!extracted.ok) {
-            logSessionStart(`archive-install ${tool.id}: extraction failed: ${extracted.stderr}`);
+            logSessionStart(`archive-install ${tool.id}: extraction failed: ${extracted.stderr} — keeping installed version`);
+            await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => { });
             return undefined;
         }
         // Tree bundle (no launcher): the whole extracted tree IS the artifact. Verify
-        // the marker exists and resolve to the extract dir — the consuming server
-        // launches a runtime against a bootstrap inside it (e.g. PSES via pwsh).
+        // the marker exists — in the TMP dir, before it becomes the live one — the
+        // consuming server launches a runtime against a bootstrap inside it (e.g.
+        // PSES via pwsh).
         if (!spec.launcher) {
-            const marker = spec.treeMarker
-                ? path.join(extractDir, ...spec.treeMarker.split("/"))
-                : extractDir;
+            const tmpMarker = spec.treeMarker
+                ? path.join(tmpExtractDir, ...spec.treeMarker.split("/"))
+                : tmpExtractDir;
             try {
-                await fs.access(marker);
+                await fs.access(tmpMarker);
             }
             catch {
-                logSessionStart(`archive-install ${tool.id}: tree marker not found at ${marker} after extraction`);
+                logSessionStart(`archive-install ${tool.id}: tree marker not found at ${tmpMarker} after extraction — keeping installed version`);
+                await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => { });
                 return undefined;
             }
+            await swapExtractedDir(tool.id, tmpExtractDir, extractDir);
             logSessionStart(`archive-install ${tool.id}: installed tree bundle → ${extractDir} (extracted ${archiveBuffer.length} bytes)`);
             debugLog(`[archive] installed ${tool.name} bundle → ${extractDir}`);
             return extractDir;
         }
-        // The launcher inside the extracted tree (e.g. bin/spotbugs[.bat]).
-        const innerLauncher = path.join(extractDir, ...spec.launcher.split("/").map((p) => p));
-        const resolvedInner = isWindows ? `${innerLauncher}.bat` : innerLauncher;
+        // The launcher inside the TMP extracted tree (e.g. bin/spotbugs[.bat]),
+        // verified before the tree becomes the live one.
+        const launcherParts = spec.launcher.split("/").map((p) => p);
+        const tmpInnerLauncher = path.join(tmpExtractDir, ...launcherParts);
+        const tmpResolvedInner = isWindows
+            ? `${tmpInnerLauncher}.bat`
+            : tmpInnerLauncher;
         try {
-            await fs.access(resolvedInner);
+            await fs.access(tmpResolvedInner);
         }
         catch {
-            logSessionStart(`archive-install ${tool.id}: launcher not found at ${resolvedInner} after extraction`);
+            logSessionStart(`archive-install ${tool.id}: launcher not found at ${tmpResolvedInner} after extraction — keeping installed version`);
+            await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => { });
             return undefined;
         }
         if (!isWindows)
-            await fs.chmod(resolvedInner, 0o750).catch(() => { });
+            await fs.chmod(tmpResolvedInner, 0o750).catch(() => { });
+        await swapExtractedDir(tool.id, tmpExtractDir, extractDir);
+        // The launcher path inside `extractDir` — stable across every install and
+        // refresh, since `extractDir` itself never changes — computed fresh now
+        // that the swap has put the verified tree there.
+        const innerLauncher = path.join(extractDir, ...launcherParts);
+        const resolvedInner = isWindows ? `${innerLauncher}.bat` : innerLauncher;
         // Thin shim in the managed bin so discovery (findGitHubToolPath) resolves
         // it like any other managed tool. `call`/`exec` preserves the real
         // launcher's own %~dp0/$0 so it still finds its sibling lib/.
@@ -2729,10 +3634,10 @@ async function installArchiveTool(tool) {
         const launcherName = isWindows ? `${binaryName}.bat` : binaryName;
         const shimPath = path.join(GITHUB_BIN_DIR, launcherName);
         if (isWindows) {
-            await fs.writeFile(shimPath, `@echo off\r\ncall "${resolvedInner}" %*\r\n`);
+            await writeFileAtomicAsync(shimPath, `@echo off\r\ncall "${resolvedInner}" %*\r\n`, { bestEffort: false });
         }
         else {
-            await fs.writeFile(shimPath, `#!/bin/sh\nexec "${resolvedInner}" "$@"\n`, { mode: 0o750 });
+            await writeFileAtomicAsync(shimPath, `#!/bin/sh\nexec "${resolvedInner}" "$@"\n`, { bestEffort: false, mode: 0o750 });
         }
         logSessionStart(`archive-install ${tool.id}: installed → ${shimPath} (extracted ${archiveBuffer.length} bytes)`);
         debugLog(`[archive] installed ${tool.name} → ${shimPath}`);
@@ -2740,7 +3645,8 @@ async function installArchiveTool(tool) {
     }
     catch (err) {
         await fs.rm(tmpArchive, { force: true }).catch(() => { });
-        logSessionStart(`archive-install ${tool.id}: install failed: ${err.message}`);
+        await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => { });
+        logSessionStart(`archive-install ${tool.id}: install failed: ${err.message} — keeping installed version`);
         return undefined;
     }
 }
@@ -2754,7 +3660,7 @@ async function installNpmTool(packageName, binaryName) {
             await fs.access(packageJsonPath);
         }
         catch {
-            await fs.writeFile(packageJsonPath, JSON.stringify({ name: "pi-lens-tools", version: "1.0.0" }, null, 2));
+            await writeFileAtomicAsync(packageJsonPath, JSON.stringify({ name: "pi-lens-tools", version: "1.0.0" }, null, 2), { bestEffort: false });
         }
         // Resolve the package manager for the tools dir and build install args.
         const isWindows = installerPlatform() === "win32";
@@ -2859,31 +3765,43 @@ async function installNpmTool(packageName, binaryName) {
 /**
  * Install a pip package tool
  */
-async function installPipTool(packageName) {
+async function installPipTool(packageName, 
+/**
+ * Add `-U`, turning the install into an upgrade. Without it `pip install`
+ * treats an already-present package as satisfied and leaves the day-one
+ * version in place forever — the freeze #1747 is about. The flag is the ONLY
+ * difference between install and refresh: same command ladder, same
+ * `--user` target, so a refresh can never write somewhere the install would
+ * not have.
+ */
+options = {}) {
     try {
         const isWindows = process.platform === "win32";
+        const verb = options.upgrade
+            ? ["install", "-U", "--user"]
+            : ["install", "--user"];
         const pipCandidates = isWindows
             ? [
-                { command: "pip", args: ["install", "--user", packageName] },
+                { command: "pip", args: [...verb, packageName] },
                 {
                     command: "py",
-                    args: ["-m", "pip", "install", "--user", packageName],
+                    args: ["-m", "pip", ...verb, packageName],
                 },
                 {
                     command: "python",
-                    args: ["-m", "pip", "install", "--user", packageName],
+                    args: ["-m", "pip", ...verb, packageName],
                 },
             ]
             : [
-                { command: "pip3", args: ["install", "--user", packageName] },
-                { command: "pip", args: ["install", "--user", packageName] },
+                { command: "pip3", args: [...verb, packageName] },
+                { command: "pip", args: [...verb, packageName] },
                 {
                     command: "python3",
-                    args: ["-m", "pip", "install", "--user", packageName],
+                    args: ["-m", "pip", ...verb, packageName],
                 },
                 {
                     command: "python",
-                    args: ["-m", "pip", "install", "--user", packageName],
+                    args: ["-m", "pip", ...verb, packageName],
                 },
             ];
         let lastError = "";
@@ -3007,8 +3925,46 @@ async function installGemTool(packageName) {
         return undefined;
     }
 }
+/**
+ * Stamp the refresh state at INSTALL time (#1747).
+ *
+ * An install has just done, by definition, the freshest possible resolution.
+ * Recording it here means the periodic refresh starts its cadence from the
+ * install rather than treating a day-old tool as never checked — and it is what
+ * spares the archive/maven entries a redundant re-download the first time their
+ * coordinate comparison runs with no recorded pin.
+ *
+ * npm is skipped: its install case already calls `stampManagedToolInstalled`
+ * directly (#1746 review F4), which reads the installed version off disk. That
+ * call happens synchronously before this funnel runs, so stamping npm again
+ * here — with no version, since `lastInstallResolutionId` is never set for
+ * npm — would overwrite the version-bearing stamp with a version-less one.
+ *
+ * Lazily imported so `installer/index.ts` keeps no static dependency on the
+ * refresh module (which imports this one). Best-effort: a stamp that cannot be
+ * written only costs one extra re-resolution later, so it never fails an
+ * install.
+ */
+async function stampInstallResolution(toolId) {
+    const tool = TOOLS.find((t) => t.id === toolId);
+    if (tool?.installStrategy === "npm")
+        return;
+    try {
+        const resolutionId = lastInstallResolutionId.get(toolId);
+        const refresh = await import("./managed-tool-refresh.js");
+        await refresh.stampManagedToolInstall(toolId, resolutionId);
+    }
+    catch {
+        // best-effort
+    }
+}
 async function finishInstallAttempt(toolId, ok, startedAt) {
     logSessionStart(`auto-install ${toolId}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`);
+    if (ok)
+        await stampInstallResolution(toolId);
+    // Every install strategy funnels its outcome through here, so this one write
+    // records attempt-ness for all of them (#1500).
+    noteInstallAttempt(toolId, ok ? "succeeded" : "failed", ok ? undefined : (installFailureReasons.get(toolId) ?? "install failed"));
     if (ok) {
         // A prior availability probe may have cached ENOENT for this exact child
         // PATH. Make a successful mutation visible immediately rather than waiting
@@ -3040,11 +3996,13 @@ async function finishInstallAttempt(toolId, ok, startedAt) {
 export async function installTool(toolId) {
     if (process.env.PI_LENS_DISABLE_TOOL_INSTALL === "1") {
         installFailureReasons.set(toolId, "installation disabled by PI_LENS_DISABLE_TOOL_INSTALL=1");
+        noteInstallAttempt(toolId, "declined", "installation disabled by PI_LENS_DISABLE_TOOL_INSTALL=1");
         logSessionStart(`auto-install ${toolId}: refused — PI_LENS_DISABLE_TOOL_INSTALL=1`);
         return false;
     }
     const tool = TOOLS.find((t) => t.id === toolId);
     if (!tool) {
+        noteInstallAttempt(toolId, "declined", "unknown tool id");
         logSessionStart(`auto-install ${toolId}: unknown tool id`);
         return false;
     }
@@ -3056,6 +4014,26 @@ export async function installTool(toolId) {
                 if (!tool.packageName || !tool.binaryName)
                     return false;
                 const npmPath = await installNpmTool(tool.packageName, tool.binaryName);
+                if (npmPath !== undefined) {
+                    // #1746 review F4: an install just resolved this package's range
+                    // against the registry, so record it as freshly checked. Otherwise a
+                    // new machine that installs 22 tools today has 22 unstamped tools,
+                    // and spends the next 22 sessions running `npm update` on packages
+                    // it installed minutes ago.
+                    //
+                    // Dynamic import, not a static one: managed-tool-refresh.ts imports
+                    // THIS module for the tool registry, and a static import back would
+                    // be a cycle. By the time this line runs the module graph is long
+                    // since evaluated, so the lazy import is safe and also keeps the
+                    // refresh module off the startup path.
+                    await import("./managed-tool-refresh.js")
+                        .then((m) => m.stampManagedToolInstalled(tool.id, tool.packageName))
+                        .catch(() => {
+                        // Best-effort telemetry: a missing stamp costs one wasted
+                        // update later, never a wrong version, and must not fail the
+                        // install that just succeeded.
+                    });
+                }
                 return finishInstallAttempt(tool.id, npmPath !== undefined, startedAt);
             }
             case "pip": {
@@ -3112,16 +4090,27 @@ export async function ensureTool(toolId, opts) {
     if (opts?.allowInstall !== false &&
         !assertInstallAllowed(`managed tool ensure: ${toolId}`)) {
         logSessionStart(`auto-install ensure ${toolId}: install gated — ${projectTrustDenialReason()}; discovery only`);
-        return ensureToolResolved(toolId, { ...opts, allowInstall: false });
+        const denialReason = projectTrustDenialReason();
+        const discovered = await ensureToolResolved(toolId, {
+            ...opts,
+            allowInstall: false,
+        });
+        // AFTER the discovery pass, which clears the per-attempt record on entry.
+        noteInstallAttempt(toolId, "declined", `project trust: ${denialReason}`);
+        return discovered;
     }
     return ensureToolResolved(toolId, opts);
 }
 async function ensureToolResolved(toolId, opts) {
     installFailureReasons.delete(toolId);
+    // A fresh ensure supersedes whatever the last one recorded, and the trust-gate
+    // branch above deliberately keeps its `declined` record by never reaching here.
+    installAttempts.delete(toolId);
+    lastEnsureResolutionSource.delete(toolId);
     const cacheResolvedPath = (result) => {
         if (result) {
             resolvedPathCache.set(toolId, result);
-            void updateProbeCache(toolId, result);
+            void updateProbeCache(toolId, result, wasLastResolveTransient(toolId));
         }
         return result;
     };
@@ -3144,16 +4133,19 @@ async function ensureToolResolved(toolId, opts) {
             // best-effort
         }
         if (opts.allowInstall === false) {
+            noteInstallAttempt(toolId, "declined", "install disabled by caller");
             logSessionStart(`auto-install ensure ${toolId}: force reinstall blocked — install disabled, discovery only (${Date.now() - ensureStartMs}ms)`);
             return cacheResolvedPath(await getToolPath(toolId));
         }
         if (process.env.PI_LENS_DISABLE_TOOL_INSTALL === "1") {
             installFailureReasons.set(toolId, "installation disabled by PI_LENS_DISABLE_TOOL_INSTALL=1");
+            noteInstallAttempt(toolId, "declined", "installation disabled by PI_LENS_DISABLE_TOOL_INSTALL=1");
             logSessionStart(`auto-install ensure ${toolId}: refused — PI_LENS_DISABLE_TOOL_INSTALL=1`);
             return undefined;
         }
         const lock = await acquireInstallLock();
         if (!lock.release) {
+            noteInstallAttempt(toolId, "skipped", lock.reason ?? "install lock held");
             logSessionStart(`auto-install ensure ${toolId}: ${lock.reason}`);
             return undefined;
         }
@@ -3165,6 +4157,9 @@ async function ensureToolResolved(toolId, opts) {
             await lock.release();
         }
         if (!installed) {
+            // installTool RAN. Whatever it recorded stands; otherwise this is a
+            // genuine failure, which is what the caller needs to see (#1500).
+            noteInstallAttemptIfUnrecorded(toolId, "failed", "install failed");
             logSessionStart(`auto-install ensure ${toolId}: force reinstall failed (${Date.now() - ensureStartMs}ms)`);
             return undefined;
         }
@@ -3178,10 +4173,13 @@ async function ensureToolResolved(toolId, opts) {
     // Fast path 1: in-memory session cache — no I/O.
     const cached = resolvedPathCache.get(toolId);
     if (cached) {
-        if (!isFullyQualified(cached))
+        if (!isFullyQualified(cached)) {
+            lastEnsureResolutionSource.set(toolId, "session-cache");
             return cached;
+        }
         try {
             await fs.access(cached);
+            lastEnsureResolutionSource.set(toolId, "session-cache");
             return cached;
         }
         catch {
@@ -3198,6 +4196,7 @@ async function ensureToolResolved(toolId, opts) {
     const diskCached = await checkProbeCache(toolId);
     if (diskCached) {
         resolvedPathCache.set(toolId, diskCached);
+        lastEnsureResolutionSource.set(toolId, "probe-cache");
         logSessionStart(`auto-install ensure ${toolId}: probe cache hit → ${diskCached}`);
         return diskCached;
     }
@@ -3242,7 +4241,8 @@ async function ensureToolResolved(toolId, opts) {
                 }
             }
             resolvedPathCache.set(toolId, existingPath);
-            void updateProbeCache(toolId, existingPath);
+            void updateProbeCache(toolId, existingPath, wasLastResolveTransient(toolId));
+            lastEnsureResolutionSource.set(toolId, "path");
             logSessionStart(`auto-install ensure ${toolId}: already available at ${existingPath} (${Date.now() - ensureStartMs}ms)`);
             return existingPath;
         }
@@ -3251,17 +4251,20 @@ async function ensureToolResolved(toolId, opts) {
         // caller forbids installs (allowInstall:false, e.g. PI_LENS_DISABLE_LSP_INSTALL=1)
         // we must still return a discovered binary and only skip the actual install.
         if (opts?.allowInstall === false) {
+            noteInstallAttempt(toolId, "declined", "install disabled by caller");
             logSessionStart(`auto-install ensure ${toolId}: install disabled — discovery only, not found (${Date.now() - ensureStartMs}ms)`);
             return undefined;
         }
         if (process.env.PI_LENS_DISABLE_TOOL_INSTALL === "1") {
             installFailureReasons.set(toolId, "installation disabled by PI_LENS_DISABLE_TOOL_INSTALL=1");
+            noteInstallAttempt(toolId, "declined", "installation disabled by PI_LENS_DISABLE_TOOL_INSTALL=1");
             logSessionStart(`auto-install ensure ${toolId}: refused — PI_LENS_DISABLE_TOOL_INSTALL=1 (${Date.now() - ensureStartMs}ms)`);
             return undefined;
         }
         const lock = await acquireInstallLock();
         if (!lock.release) {
             installFailureReasons.set(toolId, lock.reason ?? "install lock failed");
+            noteInstallAttempt(toolId, "skipped", lock.reason ?? "install lock held");
             logSessionStart(`auto-install ensure ${toolId}: ${lock.reason}`);
             return undefined;
         }
@@ -3271,8 +4274,9 @@ async function ensureToolResolved(toolId, opts) {
             // installed by its predecessor and must not run a second package manager.
             const installedByPeer = await getToolPath(toolId);
             if (installedByPeer) {
+                noteInstallAttempt(toolId, "succeeded", "installed by a concurrent process");
                 resolvedPathCache.set(toolId, installedByPeer);
-                void updateProbeCache(toolId, installedByPeer);
+                void updateProbeCache(toolId, installedByPeer, wasLastResolveTransient(toolId));
                 return installedByPeer;
             }
             installed = await installTool(toolId);
@@ -3281,13 +4285,16 @@ async function ensureToolResolved(toolId, opts) {
             await lock.release();
         }
         if (!installed) {
+            // installTool RAN and did not succeed. A genuine failure unless it
+            // recorded a more specific outcome of its own (#1500).
+            noteInstallAttemptIfUnrecorded(toolId, "failed", "install failed");
             logSessionStart(`auto-install ensure ${toolId}: unavailable (${Date.now() - ensureStartMs}ms)`);
             return undefined;
         }
         const result = await getToolPath(toolId);
         if (result) {
             resolvedPathCache.set(toolId, result);
-            void updateProbeCache(toolId, result);
+            void updateProbeCache(toolId, result, wasLastResolveTransient(toolId));
             logSessionStart(`auto-install ensure ${toolId}: success at ${result} (${Date.now() - ensureStartMs}ms)`);
         }
         else {
@@ -3345,6 +4352,16 @@ export async function checkAllTools() {
 export function isKnownToolId(toolId) {
     return TOOLS.some((tool) => tool.id === toolId);
 }
+/**
+ * The registry's own install strategy for `toolId`, or `undefined` for an
+ * unknown id. Single source of truth for anything that needs to LABEL how a
+ * tool gets installed (e.g. the availability-decision evidence's `source`
+ * tag, #1612) — derived from the same `TOOLS` entry `ensureTool` dispatches
+ * on, so the label can never drift out of sync with the actual installer.
+ */
+export function getToolInstallStrategy(toolId) {
+    return TOOLS.find((tool) => tool.id === toolId)?.installStrategy;
+}
 /**
  * GitHub-release tools that ship an asset for **every** supported
  * platform/arch combo (linux/darwin/win32 × x64/arm64). This is the set the
@@ -3378,6 +4395,7 @@ export const GITHUB_TOOLS = [
     "opengrep",
     "deno",
     "clojure-lsp",
+    "cue",
     "gleam",
     "marksman",
     "expert",