@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/dist/clients/installer/managed-tool-refresh.js

@@ -0,0 +1,715 @@
+/**
+ * Periodic version refresh for pi-lens's managed tools (#1730, #1747).
+ *
+ * #1730 covered the npm strategy. #1747 extends the SAME cadence, stamp file,
+ * session budget and degradation kind to the other five rather than building a
+ * second mechanism: github (27 entries), pip (6), archive (4), maven (1) and
+ * gem (1) were all frozen at whatever the installer resolved on day one,
+ * because `installTool` only runs when the tool is ABSENT. The only per-
+ * strategy difference is the re-resolution step, which lives in
+ * `installer/index.ts`'s `refreshManagedTool`.
+ *
+ * `~/.pi-lens/tools/package.json` records ranges, not versions — `npm install
+ * knip` writes `"knip": "^6.4.1"` and a lockfile pinning 6.4.1. Nothing ever
+ * re-resolved that range, so the managed copy stayed on the version present at
+ * first install for the life of the machine. A managed knip 28 minors behind
+ * produced 62 unused-export findings on a tree the same project's own knip
+ * reported clean, and acting on those findings deletes live code. Every managed
+ * npm tool drifts the same way; a stale pyright or biome is the same wrong
+ * verdict, quieter.
+ *
+ * The policy, and the constraints each part answers:
+ *
+ * - Bounded. At most `maxPerSession` tools (default 1) are refreshed per
+ *   session, and each tool is eligible again only once per `intervalMs`
+ *   (default 7 days). A managed tools tree with 22 entries therefore costs at
+ *   most one `npm update` spawn per session, never one per run and never a
+ *   22-package burst.
+ * - Off the hot path. `runManagedToolRefresh` is never awaited by a caller
+ *   that serves a user request; `runtime-session.ts` schedules it on an
+ *   unref'd background timer after `session_start` has already returned.
+ * - Non-blocking for availability. A refresh failure never removes or hides
+ *   the installed copy. `npm update` leaves the existing tree in place, and
+ *   this module never touches `node_modules` itself, so the current version
+ *   keeps serving.
+ * - Re-armed per session, not per process. The per-session budget is keyed to
+ *   the degradation ledger's session generation, so a long-lived process that
+ *   serves many `/new` sessions re-checks eligibility each time — and the
+ *   REAL cooldown lives in the persisted stamp, not in process memory, so a
+ *   restart loop cannot turn a 7-day cadence into an every-launch one.
+ * - Empty is not the same as errored. A missing stamp file means "never
+ *   refreshed" and makes every tool eligible. An UNREADABLE stamp file means
+ *   the cadence is unknown; the session degrades once and refreshes nothing,
+ *   rather than treating unknown as fresh (drift forever) or as stale (a
+ *   22-package burst on every session).
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { recordDegradationOnce } from "../degradation-ledger.js";
+import { commitDurableStoreAsync } from "../durable-store.js";
+import { pmBinary, resolveNodePackageManager, updateArgs, } from "../package-manager.js";
+import { safeSpawnAsync } from "../safe-spawn.js";
+import { logSessionStart } from "../sessionstart-logger.js";
+import { acquireManagedInstallGate, getManagedToolsDir, getRefreshableManagedTools, invalidateManagedToolResolution, isManagedToolPresent, npmToolNeedsPostinstall, refreshManagedTool, resolveManagedNpmBinPath, verifyToolBinary, } from "./index.js";
+import { releaseManagedToolRefreshSlot, reserveManagedToolRefreshSlot, } from "./managed-tool-refresh-session.js";
+const STATE_FILENAME = ".refresh-state.json";
+const STATE_VERSION = 1;
+/** Default per-tool refresh cadence: once a week. */
+const DEFAULT_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Cooldown after a FAILED refresh. Shorter than the success cadence — a failure
+ * is usually a transient network or registry problem worth retrying sooner —
+ * but still a real cooldown, so a permanently offline machine spawns at most
+ * one `npm update` per tool per day rather than one per session.
+ */
+const DEFAULT_RETRY_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_MAX_PER_SESSION = 1;
+const DEFAULT_TIMEOUT_MS = 120_000;
+function numericEnv(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+function refreshIntervalMs() {
+    return numericEnv("PI_LENS_TOOL_REFRESH_INTERVAL_MS", DEFAULT_INTERVAL_MS);
+}
+function retryIntervalMs() {
+    return numericEnv("PI_LENS_TOOL_REFRESH_RETRY_MS", DEFAULT_RETRY_INTERVAL_MS);
+}
+function maxPerSession() {
+    return numericEnv("PI_LENS_TOOL_REFRESH_MAX_PER_SESSION", DEFAULT_MAX_PER_SESSION);
+}
+function refreshTimeoutMs() {
+    return numericEnv("PI_LENS_INSTALL_TIMEOUT_MS", DEFAULT_TIMEOUT_MS);
+}
+function emptyState() {
+    return { version: STATE_VERSION, tools: {} };
+}
+export function getManagedToolRefreshStatePath() {
+    return path.join(getManagedToolsDir(), STATE_FILENAME);
+}
+/** Coerce one parsed entry, dropping anything whose shape we cannot trust. */
+function parseEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const candidate = value;
+    if (typeof candidate.checkedAt !== "number")
+        return undefined;
+    if (!Number.isFinite(candidate.checkedAt))
+        return undefined;
+    return {
+        checkedAt: candidate.checkedAt,
+        ...(typeof candidate.version === "string" && {
+            version: candidate.version,
+        }),
+        ...(typeof candidate.resolutionId === "string" && {
+            resolutionId: candidate.resolutionId,
+        }),
+        ...(typeof candidate.etag === "string" && { etag: candidate.etag }),
+        ...(candidate.failed === true && { failed: true }),
+    };
+}
+function parseState(contents) {
+    const parsed = JSON.parse(contents);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("refresh-state root is not an object");
+    }
+    const rawTools = parsed.tools;
+    if (!rawTools || typeof rawTools !== "object" || Array.isArray(rawTools)) {
+        throw new Error("refresh-state.tools is not an object");
+    }
+    const tools = {};
+    for (const [toolId, value] of Object.entries(rawTools)) {
+        const entry = parseEntry(value);
+        if (entry)
+            tools[toolId] = entry;
+    }
+    return { version: STATE_VERSION, tools };
+}
+export async function readManagedToolRefreshState() {
+    let contents;
+    try {
+        contents = await fs.readFile(getManagedToolRefreshStatePath(), "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        // ENOENT is the honest "never refreshed" answer. A permission error or a
+        // directory in the file's place is NOT — that is unknown cadence.
+        if (code === "ENOENT")
+            return { status: "empty", state: emptyState() };
+        return { status: "unreadable", reason: code ?? "read error" };
+    }
+    try {
+        return { status: "ok", state: parseState(contents) };
+    }
+    catch (err) {
+        return { status: "unreadable", reason: err.message };
+    }
+}
+/**
+ * Commit one tool's stamp under the durable-store lock, merging against
+ * whatever a sibling pi-lens process wrote since this process read.
+ *
+ * A torn or corrupt file is recovered as empty HERE (rather than thrown) so a
+ * later commit can replace it. The read path above still reports `unreadable`,
+ * which is what suppresses the refresh; this side only has to make sure the
+ * file becomes valid again instead of staying corrupt forever.
+ */
+async function writeRefreshStamp(toolId, entry) {
+    try {
+        await fs.mkdir(getManagedToolsDir(), { recursive: true });
+        await commitDurableStoreAsync({
+            path: getManagedToolRefreshStatePath(),
+            deserialize: (contents) => {
+                if (contents === undefined)
+                    return emptyState();
+                try {
+                    return parseState(contents);
+                }
+                catch {
+                    return emptyState();
+                }
+            },
+            merge: (disk) => {
+                disk.tools[toolId] = entry;
+                return disk;
+            },
+            serialize: (disk) => JSON.stringify(disk, null, 2),
+            waitMs: 2000,
+            retryMs: 25,
+            staleMs: 60_000,
+            timeoutMessage: "Timed out waiting for managed-tool refresh-state lock",
+            onContention: "skip-log",
+            logContention: () => {
+                logSessionStart(`managed-tool-refresh ${toolId}: stamp deferred because another process owns the lock`);
+            },
+        });
+    }
+    catch (err) {
+        // A stamp that cannot be written means this tool is eligible again next
+        // session. That is noisier than intended but never wrong, so it degrades
+        // rather than throwing into the background timer.
+        recordDegradationOnce({
+            kind: "managed-tool-refresh",
+            subject: toolId,
+            reason: `stamp write failed: ${err.message}`,
+        });
+        logSessionStart(`managed-tool-refresh ${toolId}: stamp write failed (${err.message})`);
+    }
+}
+/**
+ * Record that a tool was just INSTALLED, so the cadence starts from the install
+ * (#1747).
+ *
+ * An install has performed the freshest possible resolution, so leaving the
+ * stamp absent would make the refresh treat a brand-new tool as never checked
+ * and re-resolve it the moment the timer next fired. Recording the resolution
+ * identity here is also what spares the archive and maven entries a redundant
+ * re-download: their refresh compares the recorded pin against the registry's,
+ * and an install writes exactly the pin it used.
+ *
+ * Called from `installer/index.ts`'s `finishInstallAttempt` for every strategy
+ * EXCEPT npm — npm stamps itself via `stampManagedToolInstalled` below, which
+ * also captures the installed version; this funnel would otherwise overwrite
+ * that version-bearing stamp with a version-less one milliseconds later.
+ */
+export async function stampManagedToolInstall(toolId, resolutionId, now = Date.now()) {
+    await writeRefreshStamp(toolId, {
+        checkedAt: now,
+        ...(resolutionId !== undefined && { resolutionId }),
+    });
+}
+/**
+ * Stamp a tool as freshly resolved, without refreshing it.
+ *
+ * Called right after a successful managed npm install (#1746 review F4). An
+ * install already resolved the range against the registry seconds ago, so the
+ * tool is by definition current. Without this stamp a fresh machine that
+ * installs 22 tools on day one has 22 tools with no stamp, and then burns the
+ * next 22 sessions running `npm update` on packages installed minutes earlier.
+ *
+ * Best-effort by design: a missing stamp costs one wasted update, never a
+ * wrong version, so it must not fail an install.
+ */
+export async function stampManagedToolInstalled(toolId, packageName, now = Date.now()) {
+    const version = await readInstalledVersion(packageName);
+    await writeRefreshStamp(toolId, {
+        checkedAt: now,
+        ...(version !== undefined && { version }),
+    });
+}
+/**
+ * Registry entries that are BOTH refreshable and actually installed where
+ * pi-lens installs. An entry pi-lens has never installed has no version to
+ * move, and `npm update`, `pip install -U` or a release download on one would
+ * turn a refresh into an unrequested install.
+ *
+ * The presence check is filesystem-only for every strategy (#1747), so scanning
+ * all 60-odd registry entries on a background timer costs no spawn and no
+ * network.
+ */
+async function installedRefreshCandidates() {
+    const candidates = [];
+    for (const tool of getRefreshableManagedTools()) {
+        if (!(await isManagedToolPresent(tool.toolId)))
+            continue;
+        candidates.push({
+            toolId: tool.toolId,
+            strategy: tool.strategy,
+            ...(tool.packageName !== undefined && { packageName: tool.packageName }),
+            ...(tool.binaryName !== undefined && { binaryName: tool.binaryName }),
+        });
+    }
+    return candidates;
+}
+/**
+ * Which candidates are due, oldest stamp first. A tool with no stamp sorts
+ * first (it has never been refreshed); ties break on toolId so the selection
+ * is deterministic and a starved tool eventually reaches the front.
+ */
+export function selectStaleTools(candidates, state, now) {
+    const interval = refreshIntervalMs();
+    const retry = retryIntervalMs();
+    const due = candidates.filter((candidate) => {
+        const entry = state.tools[candidate.toolId];
+        if (!entry)
+            return true;
+        const cooldown = entry.failed ? retry : interval;
+        return now - entry.checkedAt >= cooldown;
+    });
+    return due.sort((a, b) => {
+        const aAt = state.tools[a.toolId]?.checkedAt ?? 0;
+        const bAt = state.tools[b.toolId]?.checkedAt ?? 0;
+        return aAt !== bAt ? aAt - bAt : a.toolId.localeCompare(b.toolId);
+    });
+}
+// --- Refresh ---
+/** Version recorded in an installed package's own `package.json`, if readable. */
+async function readInstalledVersion(packageName) {
+    try {
+        const raw = await fs.readFile(path.join(getManagedToolsDir(), "node_modules", packageName, "package.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        const version = parsed?.version;
+        return typeof version === "string" ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Refresh one tool, choosing the mechanism its install strategy needs (#1747).
+ *
+ * npm stays here because it needs the package-manager resolver; every other
+ * strategy delegates to `refreshManagedTool` in the installer, which owns the
+ * GitHub release query, the `pip install -U` ladder, `gem install`, and the
+ * pinned-coordinate comparison for maven/archive. Both halves share ONE budget,
+ * ONE stamp file and ONE degradation kind, so adding five strategies does not
+ * turn one spawn per session into six.
+ */
+async function refreshOne(candidate, entry, now) {
+    return candidate.strategy === "npm"
+        ? refreshNpmOne(candidate, now)
+        : refreshNonNpmOne(candidate, entry, now);
+}
+async function refreshNonNpmOne(candidate, entry, now) {
+    const previousVersion = entry?.version;
+    const startedAt = Date.now();
+    const attempt = await refreshManagedTool(candidate.toolId, {
+        ...(entry?.resolutionId !== undefined && {
+            resolutionId: entry.resolutionId,
+        }),
+        ...(entry?.etag !== undefined && { etag: entry.etag }),
+        ...(previousVersion !== undefined && { version: previousVersion }),
+    });
+    const elapsedMs = Date.now() - startedAt;
+    if (!attempt.ok) {
+        if (attempt.declined) {
+            // #1759 review F2: the kill switch or the project-trust gate refused
+            // BEFORE any strategy ran — nothing was touched, so this is not a
+            // failure. No degradation, and deliberately NO stamp: writing one would
+            // apply the 24h retry cooldown to a refusal that has nothing to do with
+            // the tool, delaying its next real attempt after the block lifts.
+            logSessionStart(`managed-tool-refresh ${candidate.toolId}: ${candidate.strategy} refresh declined after ${elapsedMs}ms (${attempt.reason ?? "unknown"}) — no stamp written, retried next session`);
+            return {
+                toolId: candidate.toolId,
+                strategy: candidate.strategy,
+                ...(candidate.packageName !== undefined && {
+                    packageName: candidate.packageName,
+                }),
+                previousVersion,
+                currentVersion: previousVersion,
+                changed: false,
+                verified: false,
+                ok: false,
+            };
+        }
+        // A real failure may have left a stale cached path or probe entry behind
+        // (e.g. a partially-cleared install), so the next resolution has to
+        // re-probe rather than trust what it had before this attempt (#1759
+        // review F1 — the npm path already does this on its own failure branch).
+        invalidateManagedToolResolution(candidate.toolId);
+        recordDegradationOnce({
+            kind: "managed-tool-refresh",
+            subject: candidate.toolId,
+            reason: `${candidate.strategy} refresh failed: ${attempt.reason ?? "unknown"}`,
+        });
+        logSessionStart(`managed-tool-refresh ${candidate.toolId}: ${candidate.strategy} refresh failed after ${elapsedMs}ms — keeping ${previousVersion ?? "installed"} (${attempt.reason ?? "unknown"})`);
+        await writeRefreshStamp(candidate.toolId, {
+            checkedAt: now,
+            failed: true,
+            ...(previousVersion !== undefined && { version: previousVersion }),
+            ...(entry?.resolutionId !== undefined && {
+                resolutionId: entry.resolutionId,
+            }),
+            // Deliberately NOT carrying `entry.etag` forward: a stamp that replays
+            // the validator of a run whose download failed would get a 304 next
+            // time and skip the install that never happened.
+        });
+        return {
+            toolId: candidate.toolId,
+            strategy: candidate.strategy,
+            ...(candidate.packageName !== undefined && {
+                packageName: candidate.packageName,
+            }),
+            previousVersion,
+            currentVersion: previousVersion,
+            changed: false,
+            // No spawn to verify for the non-npm strategies — a failed refresh never
+            // touched the installed copy, so there is nothing new to check.
+            verified: false,
+            ok: false,
+        };
+    }
+    const currentVersion = attempt.version;
+    const changed = !attempt.unchanged;
+    await writeRefreshStamp(candidate.toolId, {
+        checkedAt: now,
+        ...(currentVersion !== undefined && { version: currentVersion }),
+        ...(attempt.resolutionId !== undefined && {
+            resolutionId: attempt.resolutionId,
+        }),
+        ...(attempt.etag !== undefined && { etag: attempt.etag }),
+    });
+    logSessionStart(changed
+        ? `managed-tool-refresh ${candidate.toolId}: ${previousVersion ?? "unknown"} → ${currentVersion ?? "unknown"} via ${candidate.strategy} (${elapsedMs}ms)`
+        : `managed-tool-refresh ${candidate.toolId}: unchanged at ${currentVersion ?? previousVersion ?? "unknown"} via ${candidate.strategy} (${elapsedMs}ms)`);
+    return {
+        toolId: candidate.toolId,
+        strategy: candidate.strategy,
+        ...(candidate.packageName !== undefined && {
+            packageName: candidate.packageName,
+        }),
+        previousVersion,
+        currentVersion,
+        changed,
+        // `refreshManagedTool` already verifies the artifact it just wrote
+        // (`verifyRefreshedArtifact` for github/archive/maven, the `--version`
+        // probe for pip/gem) — `ok: true` here already means "and it runs".
+        verified: true,
+        ok: true,
+    };
+}
+async function refreshNpmOne(candidate, now) {
+    // Every npm candidate carries a packageName; `getRefreshableManagedTools`
+    // drops the ones that do not.
+    const packageName = candidate.packageName;
+    // #1759 review R2: npm used to spawn `npm update` directly, with none of
+    // the kill-switch/trust-gate/lock checks the five other strategies pass
+    // through `refreshManagedTool`. Same primitive, same declined-no-op
+    // semantics as `refreshNonNpmOne`'s `attempt.declined` branch below: a
+    // refusal writes no stamp and records no degradation, so it does not burn
+    // the tool's retry cooldown on a block that has nothing to do with it.
+    const gateStartedAt = Date.now();
+    const gate = await acquireManagedInstallGate(`managed tool refresh: ${candidate.toolId}`);
+    if (!gate.ok) {
+        logSessionStart(`managed-tool-refresh ${candidate.toolId}: npm refresh declined after ${Date.now() - gateStartedAt}ms (${gate.reason ?? "unknown"}) — no stamp written, retried next session`);
+        return {
+            toolId: candidate.toolId,
+            strategy: "npm",
+            packageName,
+            changed: false,
+            verified: false,
+            ok: false,
+        };
+    }
+    try {
+        return await performNpmRefresh(candidate, packageName, now);
+    }
+    finally {
+        await gate.release?.();
+    }
+}
+async function performNpmRefresh(candidate, packageName, now) {
+    const toolsDir = getManagedToolsDir();
+    const previousVersion = await readInstalledVersion(packageName);
+    const pm = await resolveNodePackageManager(toolsDir);
+    const testNpmScript = process.env.PI_LENS_TEST_MODE === "1"
+        ? process.env.PI_LENS_TEST_NPM_SCRIPT
+        : undefined;
+    const command = testNpmScript ? process.execPath : pmBinary(pm);
+    const args = [
+        ...(testNpmScript ? [testNpmScript] : []),
+        ...updateArgs(pm, packageName, {
+            ignoreScripts: !npmToolNeedsPostinstall(packageName),
+        }),
+    ];
+    const startedAt = Date.now();
+    const spawned = await safeSpawnAsync(command, args, {
+        cwd: toolsDir,
+        timeout: refreshTimeoutMs(),
+        ignoreAmbientSignal: true,
+        lifetimeCoupled: true,
+    });
+    const elapsedMs = Date.now() - startedAt;
+    if (spawned.status !== 0 || spawned.error) {
+        const reason = (spawned.error?.message ?? spawned.stderr ?? "").slice(0, 200);
+        // "Keeping <old version>" would be an unchecked assertion (#1746 review
+        // F2). The spawn budget kills the package manager where it stands, which
+        // can be mid-write: the tree may hold a new version, a half-written one,
+        // or the old one. So report the version that is actually on disk now, and
+        // drop the cached resolution either way — a killed package manager can
+        // rewrite `.bin` shims without moving the version in `package.json`.
+        const onDisk = await readInstalledVersion(packageName);
+        invalidateManagedToolResolution(candidate.toolId);
+        recordDegradationOnce({
+            kind: "managed-tool-refresh",
+            subject: candidate.toolId,
+            reason: `${pm} update failed: ${reason || "non-zero exit"}`,
+        });
+        logSessionStart(`managed-tool-refresh ${candidate.toolId}: ${pm} update failed after ${elapsedMs}ms — on disk now ${onDisk ?? "unreadable"} (was ${previousVersion ?? "unknown"}); resolution cache cleared for re-probe (${reason || "non-zero exit"})`);
+        await writeRefreshStamp(candidate.toolId, {
+            checkedAt: now,
+            failed: true,
+            ...(onDisk !== undefined && { version: onDisk }),
+        });
+        return {
+            toolId: candidate.toolId,
+            strategy: "npm",
+            packageName,
+            previousVersion,
+            currentVersion: onDisk,
+            changed: onDisk !== undefined && onDisk !== previousVersion,
+            verified: false,
+            ok: false,
+        };
+    }
+    const currentVersion = await readInstalledVersion(packageName);
+    const changed = currentVersion !== undefined && currentVersion !== previousVersion;
+    // The update rewrote `node_modules`, so every cached claim about where this
+    // tool resolves — the in-memory path cache and the 24h probe cache — is now
+    // an assertion about a tree that no longer exists. Drop it BEFORE verifying,
+    // so a caller arriving mid-verify re-probes rather than reading the stale
+    // entry (#1746 review F2).
+    invalidateManagedToolResolution(candidate.toolId);
+    // `installNpmTool` treats verification as mandatory: an install that cannot
+    // run its own binary is not an install. An UPDATE that leaves an unrunnable
+    // binary is the same failure, and it used to pass silently — the version row
+    // was written from `package.json` alone, which a half-written tree still
+    // answers.
+    // Every npm candidate carries a binaryName; `getRefreshableManagedTools`
+    // drops npm entries that do not.
+    const binaryName = candidate.binaryName;
+    const binPath = resolveManagedNpmBinPath(binaryName);
+    const verified = await verifyToolBinary(binPath);
+    if (!verified) {
+        recordDegradationOnce({
+            kind: "managed-tool-refresh",
+            subject: candidate.toolId,
+            reason: `binary failed verification after ${pm} update (${previousVersion ?? "unknown"} → ${currentVersion ?? "unknown"})`,
+        });
+        // Deliberately NOT removed. `installNpmTool` deletes a freshly installed
+        // package that fails verification because nothing was working before it;
+        // here a working tool existed a moment ago, and deleting the tree takes it
+        // offline for certain rather than probably. The cache invalidation above is
+        // what lets `ensureTool`'s own probe-and-repair path see the breakage and
+        // reinstall. Stamped as failed so the shorter retry cooldown applies.
+        logSessionStart(`managed-tool-refresh ${candidate.toolId}: ${pm} update ran but ${binPath} failed verification — resolution cache cleared for re-probe (${elapsedMs}ms)`);
+        await writeRefreshStamp(candidate.toolId, {
+            checkedAt: now,
+            failed: true,
+            ...(currentVersion !== undefined && { version: currentVersion }),
+        });
+        return {
+            toolId: candidate.toolId,
+            strategy: "npm",
+            packageName: candidate.packageName,
+            previousVersion,
+            currentVersion,
+            changed,
+            verified: false,
+            ok: false,
+        };
+    }
+    await writeRefreshStamp(candidate.toolId, {
+        checkedAt: now,
+        ...(currentVersion !== undefined && { version: currentVersion }),
+    });
+    // The observability row #1730 asks for: a wrong verdict from a managed tool
+    // can be traced to the version that produced it, and to the moment it moved.
+    logSessionStart(changed
+        ? `managed-tool-refresh ${candidate.toolId}: ${previousVersion ?? "unknown"} → ${currentVersion} via ${pm} update, verified (${elapsedMs}ms)`
+        : `managed-tool-refresh ${candidate.toolId}: unchanged at ${currentVersion ?? previousVersion ?? "unknown"} (${elapsedMs}ms)`);
+    return {
+        toolId: candidate.toolId,
+        strategy: "npm",
+        packageName,
+        previousVersion,
+        currentVersion,
+        changed,
+        verified: true,
+        ok: true,
+    };
+}
+/**
+ * The refresh currently running in this process, so a second caller joins it
+ * instead of starting a rival one.
+ *
+ * #1746 review F1: `scheduleManagedToolRefresh` arms on EVERY
+ * `handleSessionStart`, and an `npm update` can easily outlive the 30s gap to
+ * the next session. Without this, two runs raced through the budget check and
+ * both spawned a package manager into the same unlocked managed
+ * `node_modules`. The join is the same shape `ensureTool` uses for its own
+ * duplicate startup requests (`clients/installer/index.ts:4175-4182`, cleared
+ * at `:4314-4318`).
+ *
+ * This is the local form of the single-flight primitive #1753 proposes. When
+ * that lands, this is one of its callers.
+ */
+let refreshInFlight = null;
+const noopTap = () => { };
+/**
+ * Run one session's worth of managed-tool refresh. Never throws: the caller is
+ * a background timer with no one to report to.
+ *
+ * Concurrent callers share one run. The guard is only process-wide; two pi
+ * processes can still refresh at the same time, which the per-tool stamp
+ * narrows but does not close. See the PR body for that limit stated plainly.
+ */
+export function runManagedToolRefresh(now = Date.now()) {
+    const joined = refreshInFlight;
+    if (joined) {
+        logSessionStart("managed-tool-refresh: joining the refresh already in flight");
+        return joined;
+    }
+    // No `await` between starting the run and publishing it, so no third caller
+    // can slip through and start a second one.
+    //
+    // The clear is unconditional. An identity check (`if (refreshInFlight ===
+    // run)`) is the usual companion to this pattern — `package-manager.ts:225`
+    // needs one because its map entry can be replaced by a later caller while an
+    // older probe is still settling. This slot cannot: the line below is its only
+    // writer, and every other caller returns early while it is non-null, so when
+    // this `finally` runs the slot still holds `run`. #1746 review round 2 proved
+    // that branch unreachable (mutating it to an unconditional clear failed no
+    // test), and a branch no input can take is not a guard.
+    const run = executeManagedToolRefresh(now, noopTap).finally(() => {
+        refreshInFlight = null;
+    });
+    refreshInFlight = run;
+    return run;
+}
+/**
+ * Test-only entry point for `tests/support/reset-explorer.ts`. Calls
+ * `executeManagedToolRefresh` directly, bypassing the `refreshInFlight`
+ * singleton above — the explorer runs one walk per await point and each must
+ * be independent, not coalesced into the previous one. Never call this from
+ * production code; production always goes through `runManagedToolRefresh`.
+ */
+export function runManagedToolRefreshForExploration(now, tap) {
+    return executeManagedToolRefresh(now, tap);
+}
+async function executeManagedToolRefresh(now, tap = noopTap) {
+    if (process.env.PI_LENS_DISABLE_TOOL_REFRESH === "1") {
+        return { skipped: "disabled", refreshed: [] };
+    }
+    // Reserve BEFORE any await. Reading the budget here and spending it after
+    // the two reads below is the F1 race; `reserveManagedToolRefreshSlot`
+    // checks and takes in one synchronous step, and a run that turns out to
+    // have nothing to do hands the slot straight back.
+    if (!reserveManagedToolRefreshSlot(maxPerSession())) {
+        return { skipped: "session-budget", refreshed: [] };
+    }
+    // Slots this run HOLDS and has not yet spent. Held slots are given back on
+    // every exit that never reached a spawn; a spent slot is gone for good.
+    let held = 1;
+    const releaseReservation = () => {
+        while (held > 0) {
+            releaseManagedToolRefreshSlot();
+            held -= 1;
+        }
+    };
+    try {
+        const candidates = await installedRefreshCandidates();
+        await tap();
+        if (candidates.length === 0) {
+            releaseReservation();
+            return { skipped: "no-candidates", refreshed: [] };
+        }
+        const read = await readManagedToolRefreshState();
+        await tap();
+        if (read.status === "unreadable") {
+            // Unknown cadence. Refreshing nothing is the only answer that neither
+            // drifts forever nor bursts every session; the ledger row is what makes
+            // the suppressed cadence visible instead of silent.
+            releaseReservation();
+            recordDegradationOnce({
+                kind: "managed-tool-refresh",
+                subject: "refresh-state",
+                reason: `refresh state unreadable (${read.reason}); skipping refresh this session`,
+            });
+            logSessionStart(`managed-tool-refresh: state unreadable (${read.reason}) — no tool refreshed this session`);
+            return { skipped: "state-unreadable", refreshed: [] };
+        }
+        const stale = selectStaleTools(candidates, read.state, now);
+        if (stale.length === 0) {
+            releaseReservation();
+            return { skipped: "nothing-due", refreshed: [] };
+        }
+        // Top the reservation up to cover this run's whole walk, in ONE
+        // synchronous block, and capture the total LOCALLY.
+        //
+        // #1746 review round 2 (R2-F1): the loop used to call
+        // `reserveManagedToolRefreshSlot` again for each tool after the previous
+        // tool's awaited refresh. `handleSessionStart` zeroes the global counter,
+        // and a session start landing inside a 120s `npm update` therefore re-armed
+        // the budget the running loop was still spending. Each further session
+        // start bought the same loop another tool, so a long update plus a few
+        // `/new` calls walked the entire 22-tool stale list. A local allowance
+        // cannot be re-armed by anyone: a mid-run reset restores the SESSION's
+        // right to start a new run, which is correct, without extending this one.
+        const want = Math.min(maxPerSession(), stale.length);
+        while (held < want && reserveManagedToolRefreshSlot(maxPerSession())) {
+            held += 1;
+        }
+        let allowance = held;
+        const refreshed = [];
+        for (const candidate of stale) {
+            // Once a spawn happens the slot is spent for good — a failing tool must
+            // not hand its slot to the next candidate and turn a budget of one into
+            // 22 spawns.
+            if (allowance <= 0)
+                break;
+            allowance -= 1;
+            held -= 1;
+            try {
+                refreshed.push(await refreshOne(candidate, read.state.tools[candidate.toolId], now));
+                await tap();
+            }
+            catch (err) {
+                recordDegradationOnce({
+                    kind: "managed-tool-refresh",
+                    subject: candidate.toolId,
+                    reason: `refresh threw: ${err.message}`,
+                });
+            }
+        }
+        return { refreshed };
+    }
+    finally {
+        // A throw before any spawn must not leak the reservation.
+        releaseReservation();
+    }
+}