claudeup 6.5.1 → 6.7.1

package/src/services/tool-probe.ts

@@ -0,0 +1,1637 @@
+/**
+ * tool-probe.ts — the ONE place a CLI tool's state is read and decided.
+ *
+ * `claudeup update` planned every present, unpinned tool as an UPGRADE on every
+ * run, because nothing could tell it what version was installed or whether a
+ * newer one existed — only present/absent. The TUI's CLI Tools screen had its
+ * own private probe (a shell `which`, an `npm view` per tool, and a third
+ * version comparator that read "1.2.3-beta" as "1.2.3"). The two front ends
+ * disagreed, and the CLI never converged: the second run planned exactly what
+ * the first had just "done".
+ *
+ * Now both front ends read tools through here, in two halves:
+ *
+ *  - {@link probeTools} gathers FACTS through an injected {@link ToolProbeIO}.
+ *    Each tool is read through the installer that owns the binary PATH actually
+ *    runs, and `managed` says whether the upgrade command claudeup would run
+ *    replaces THAT file. brew and uv answer "is it behind?" themselves; bun, npm
+ *    and go fall back to a registry lookup.
+ *  - {@link classifyTool} turns facts into a state, purely. The rules are in
+ *    order and the vetoes that make an upgrade unsafe come before every rule
+ *    that can produce one.
+ *
+ * Asking the installer that will perform the upgrade, about the file that will
+ * run, is what makes plan, upgrade and PATH agree — which is what convergence
+ * means. A tool whose state cannot be established is `unknown`, and `unknown`
+ * is never applied.
+ *
+ * NOTHING HERE PRINTS, and every subprocess runs through `execFile` (argv, no
+ * shell) with its stdio CAPTURED: the probe runs under the CLI's animated live
+ * region and inside the TUI, and an inherited stdio would corrupt both.
+ */
+
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import {
+	access as fsAccess,
+	readlink as fsReadlink,
+	realpath as fsRealpath,
+	readFile,
+	stat,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import semver from "semver";
+import type { CliTool } from "../data/cli-tools.js";
+import type {
+	BinInstaller,
+	BinRequirement,
+	ResolvedBin,
+} from "../types/index.js";
+import type { Command } from "../utils/command-utils.js";
+import type { InstallMethod } from "./cli-tool-commands.js";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type ToolState = "install" | "current" | "upgrade" | "unknown";
+
+export type ToolReason =
+	| "absent"
+	| "up-to-date"
+	| "behind"
+	| "at-pin"
+	| "behind-pin"
+	| "ahead-of-pin"
+	| "pin-not-installable"
+	| "held-back"
+	| "not-managed"
+	| "version-unreadable"
+	| "latest-unavailable"
+	| "unorderable"
+	| "not-probed";
+
+export type ToolFactSource =
+	| "path"
+	| "brew"
+	| "uv"
+	| "uv-receipt"
+	/** managed only because uv's `--force` would overwrite a foreign file. */
+	| "uv-adopted"
+	| "pipx"
+	| "bun-global"
+	| "npm-global"
+	| "go-buildinfo"
+	| "pypi"
+	| "npm-registry"
+	| "go-proxy"
+	| "check-command";
+
+export interface ToolFacts {
+	name: string;
+	/**
+	 * Resolvable, executable, on PATH. Before PATH has been read (a probe that
+	 * was refused, or one that hit the deadline first) this is TRUE: an
+	 * unestablished presence must never be planned as an install.
+	 */
+	present: boolean;
+	/** realpath of the PATH binary; null when absent/unresolvable. */
+	resolvedPath: string | null;
+	/** Version of THAT file, from its owner's record; null = could not be read. */
+	installed: string | null;
+	/** null = not queried / unavailable. */
+	latest: string | null;
+	/** The owning installer's own verdict; null = it gave none. */
+	behind: boolean | null;
+	/**
+	 * The upgrade command for this spec replaces `resolvedPath` (containment in
+	 * the package's own directory, or pip adoption). false = another owner;
+	 * null = the owner directory could not be determined.
+	 */
+	managed: boolean | null;
+	/**
+	 * Where the installer keeps what it owns, for the human note — e.g.
+	 * "npm (root /Users/x/.local/lib/node_modules)". Diagnostic only.
+	 */
+	owner?: string;
+	/** e.g. "held by brew pin". */
+	heldBack?: string;
+	/**
+	 * Set when `managed` is true only because the upgrade command would
+	 * OVERWRITE a file another installer put there (today: a binary in uv's bin
+	 * dir). The adoption is deliberate — `uv tool install --force` replaces the
+	 * very file PATH runs, so the state converges — but it changes the tool's
+	 * owner, which a plain `upgrade` row does not say. This is that sentence,
+	 * carried to both front ends.
+	 */
+	adopted?: string;
+	/** e.g. "timed out after 8s", "registry returned 404". */
+	failure?: string;
+	/** Where each fact came from, for diagnostics. */
+	sources: ToolFactSource[];
+}
+
+export interface ToolStatus {
+	name: string;
+	state: ToolState;
+	reason: ToolReason;
+	/** Set for every state except plain current/install. */
+	note?: string;
+	/** {@link ToolFacts.adopted}, carried when this state plans work. */
+	adopted?: string;
+	installed: string | null;
+	latest: string | null;
+	target: string | null;
+	pin?: string;
+}
+
+// ── Version comparison ───────────────────────────────────────────────────────
+
+/** A strict semver string for `v`, padding a 1–2 part numeric version, or null. */
+function toSemver(v: string): string | null {
+	const s = v.trim().replace(/^v/i, "");
+	const m = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(.*)$/.exec(s);
+	if (!m) return null;
+	const candidate =
+		m[3] === undefined ? `${m[1]}.${m[2] ?? "0"}.0${m[4] ?? ""}` : s;
+	return semver.valid(candidate);
+}
+
+/**
+ * -1 | 0 | 1, or null when the pair has no shared ordering.
+ *
+ * Deliberately STRICTER than the plugin comparator `isBehind`. Plugin opaque
+ * ids are catalog-published shas, where "different" means "not what is
+ * published". Tool version strings are free-form, and treating two different
+ * opaque tool strings as "behind" is how an upgrade loop on a prerelease
+ * starts. So: semver when both sides are semver (after stripping a leading `v`
+ * and padding "1.2" to "1.2.0"), equal strings are equal, and anything else is
+ * unorderable.
+ */
+export function compareToolVersions(a: string, b: string): -1 | 0 | 1 | null {
+	const sa = toSemver(a);
+	const sb = toSemver(b);
+	if (sa && sb) return semver.compare(sa, sb);
+	const ra = a.trim().replace(/^v/i, "");
+	const rb = b.trim().replace(/^v/i, "");
+	return ra === rb ? 0 : null;
+}
+
+// ── The classifier ───────────────────────────────────────────────────────────
+
+/** The exact pin, or undefined for an unpinned (or "latest") requirement. */
+function pinOf(spec: BinRequirement): string | undefined {
+	const v = spec.version?.trim();
+	return v && v !== "latest" ? v : undefined;
+}
+
+function withFailure(text: string, failure: string | undefined): string {
+	return failure ? `${text} (${failure})` : text;
+}
+
+/**
+ * THE tool classifier. Pure. The first matching rule wins, and each branch
+ * returns, so reading top to bottom is reading the precedence.
+ *
+ * The vetoes (`not-managed`, `held-back`) come before every rule that can yield
+ * `upgrade`, pinned or not: an upgrade through an installer that does not own
+ * the running file installs a second copy PATH never runs, and one through a
+ * held formula is a no-op. Both would be replanned forever. The pin rules that
+ * plan no work (at-pin, unorderable, ahead-of-pin) come before the vetoes,
+ * because ownership cannot make a "nothing to do" answer wrong.
+ */
+export function classifyTool(
+	spec: BinRequirement,
+	facts: ToolFacts,
+): ToolStatus {
+	const pin = pinOf(spec);
+	const base = {
+		name: spec.name,
+		installed: facts.installed,
+		latest: facts.latest,
+		...(pin ? { pin } : {}),
+	};
+
+	// 1. Not on PATH.
+	if (!facts.present) {
+		return {
+			...base,
+			state: "install",
+			reason: "absent",
+			target: pin ?? facts.latest,
+		};
+	}
+
+	// 2. Present, but we could not read what version runs.
+	const installed = facts.installed;
+	if (installed === null) {
+		return {
+			...base,
+			state: "unknown",
+			reason: "version-unreadable",
+			target: null,
+			note: withFailure(
+				`on PATH${facts.resolvedPath ? ` at ${facts.resolvedPath}` : ""}, but its version could not be read`,
+				facts.failure,
+			),
+		};
+	}
+
+	// 3–5. Pin rules that plan no work.
+	const vsPin = pin ? compareToolVersions(installed, pin) : undefined;
+	if (pin && vsPin === 0) {
+		return { ...base, state: "current", reason: "at-pin", target: null };
+	}
+	if (pin && vsPin === null) {
+		return {
+			...base,
+			state: "unknown",
+			reason: "unorderable",
+			target: null,
+			note: `installed ${installed} cannot be compared with the pin ${pin}`,
+		};
+	}
+	if (pin && vsPin === 1) {
+		// Forward-only, the same rule as plugins.
+		return {
+			...base,
+			state: "unknown",
+			reason: "ahead-of-pin",
+			target: null,
+			note: `pinned ${pin}; installed ${installed} is newer and claudeup never downgrades`,
+		};
+	}
+
+	// 6. The veto: the upgrade would not replace the file PATH runs.
+	if (facts.managed !== true) {
+		return {
+			...base,
+			state: "unknown",
+			reason: "not-managed",
+			target: null,
+			note:
+				facts.managed === false
+					? `on PATH at ${facts.resolvedPath ?? "?"}, which ${facts.owner ?? spec.via} does not own — upgrading through ${spec.via} would install a second copy`
+					: withFailure(
+							`could not tell whether ${spec.via} owns ${facts.resolvedPath ?? spec.name}`,
+							facts.failure,
+						),
+		};
+	}
+
+	// 7. The veto: the installer will refuse to move it.
+	if (facts.heldBack) {
+		return {
+			...base,
+			state: "unknown",
+			reason: "held-back",
+			target: null,
+			note: facts.heldBack,
+		};
+	}
+
+	// 8–9. Pinned and behind the pin (every other pinned case returned above).
+	// From here on a row can plan work, so an adoption must travel with it.
+	const adopted = facts.adopted ? { adopted: facts.adopted } : {};
+	if (pin) {
+		if (spec.via === "brew") {
+			return {
+				...base,
+				state: "unknown",
+				reason: "pin-not-installable",
+				target: null,
+				note: `pinned ${pin}; installed ${installed} — brew installs only its newest version, so the pin cannot be installed`,
+			};
+		}
+		return {
+			...base,
+			...adopted,
+			state: "upgrade",
+			reason: "behind-pin",
+			target: pin,
+			note: `installed ${installed} is below the pin ${pin}`,
+		};
+	}
+
+	// 10–11. The owning installer's own verdict.
+	if (facts.behind === true) {
+		return {
+			...base,
+			...adopted,
+			state: "upgrade",
+			reason: "behind",
+			target: facts.latest,
+			note: facts.latest
+				? `${facts.latest} is available`
+				: "a newer version is available",
+		};
+	}
+	if (facts.behind === false) {
+		return { ...base, state: "current", reason: "up-to-date", target: null };
+	}
+
+	// 12. Nothing to compare against.
+	const latest = facts.latest;
+	if (latest === null) {
+		return {
+			...base,
+			state: "unknown",
+			reason: "latest-unavailable",
+			target: null,
+			note: withFailure("the latest version could not be read", facts.failure),
+		};
+	}
+
+	// 13. Our own comparison.
+	const cmp = compareToolVersions(installed, latest);
+	if (cmp === null) {
+		return {
+			...base,
+			state: "unknown",
+			reason: "unorderable",
+			target: null,
+			note: `installed ${installed} cannot be compared with the latest ${latest}`,
+		};
+	}
+	if (cmp < 0) {
+		return {
+			...base,
+			...adopted,
+			state: "upgrade",
+			reason: "behind",
+			target: latest,
+			note: `${latest} is available`,
+		};
+	}
+	return { ...base, state: "current", reason: "up-to-date", target: null };
+}
+
+// ── Parsers (pure; tested against captured real output) ──────────────────────
+
+/** `brew list --versions <f>` → the last version token ("tmux 3.7c" → "3.7c"). */
+export function parseBrewListVersions(stdout: string): string | null {
+	const line = stdout.split("\n").find((l) => l.trim().length > 0);
+	if (!line) return null;
+	const tokens = line.trim().split(/\s+/);
+	return tokens.length >= 2 ? (tokens[tokens.length - 1] ?? null) : null;
+}
+
+/**
+ * `brew outdated --json=v2 <formula>`. `formulae: []` means not behind. null =
+ * unparseable. A tap formula's `name` is its full name ("user/tap/f").
+ */
+export function parseBrewOutdatedJson(
+	stdout: string,
+	formula: string,
+): {
+	behind: boolean;
+	installed: string | null;
+	latest: string | null;
+	pinned: boolean;
+} | null {
+	let body: unknown;
+	try {
+		body = JSON.parse(stdout);
+	} catch {
+		return null;
+	}
+	const formulae = (body as { formulae?: unknown } | null)?.formulae;
+	if (!Array.isArray(formulae)) return null;
+	const entry = formulae.find((f: unknown) => {
+		const name = (f as { name?: unknown } | null)?.name;
+		return (
+			typeof name === "string" &&
+			(name === formula || name.endsWith(`/${formula}`))
+		);
+	}) as
+		| {
+				installed_versions?: unknown;
+				current_version?: unknown;
+				pinned?: unknown;
+		  }
+		| undefined;
+	if (!entry) {
+		return { behind: false, installed: null, latest: null, pinned: false };
+	}
+	const versions = Array.isArray(entry.installed_versions)
+		? entry.installed_versions.filter(
+				(v: unknown): v is string => typeof v === "string",
+			)
+		: [];
+	return {
+		behind: true,
+		installed: versions[versions.length - 1] ?? null,
+		latest:
+			typeof entry.current_version === "string" ? entry.current_version : null,
+		pinned: entry.pinned === true,
+	};
+}
+
+/**
+ * The keg version from a realpath under `<cellar>/<formula>/<version>/`
+ * (".../Cellar/tmux/3.7c/bin/tmux" → "3.7c"). This is the LINKED version, which
+ * `brew list --versions` cannot give when several kegs are kept.
+ */
+export function brewKegVersion(
+	realPath: string,
+	cellar: string,
+	formula: string,
+): string | null {
+	const prefix = `${path.join(cellar, formula)}${path.sep}`;
+	if (!realPath.startsWith(prefix)) return null;
+	const segment = realPath.slice(prefix.length).split(path.sep)[0];
+	return segment ? segment : null;
+}
+
+/** PEP 503 normalisation: lowercase, runs of `-_.` collapse to `-`. */
+export function normalizePythonPackageName(name: string): string {
+	return name.toLowerCase().replace(/[-_.]+/g, "-");
+}
+
+/**
+ * `uv tool list` / `uv tool list --outdated`. Package lines are `name vX.Y`,
+ * optionally followed by `[latest: Z]`; lines starting `- ` are executables.
+ * Keys are PEP 503-normalised. An unrecognised format yields an empty map,
+ * which degrades to PyPI, never to an upgrade.
+ */
+export function parseUvToolList(
+	stdout: string,
+): Map<string, { installed: string; latest: string | null }> {
+	const out = new Map<string, { installed: string; latest: string | null }>();
+	for (const raw of stdout.split("\n")) {
+		const line = raw.trimEnd();
+		if (!line || line.startsWith("-") || line.startsWith(" ")) continue;
+		const m = /^(\S+)\s+v(\S+)(.*)$/.exec(line);
+		if (!m?.[1] || !m[2]) continue;
+		const latest = /\[latest:\s*([^\]\s]+)\s*\]/.exec(m[3] ?? "")?.[1] ?? null;
+		out.set(normalizePythonPackageName(m[1]), { installed: m[2], latest });
+	}
+	return out;
+}
+
+export type UvRequirementSource =
+	| "index"
+	| "index-constrained"
+	| "git"
+	| "directory"
+	| "path"
+	| "url"
+	| "editable";
+
+function parseToml(text: string): unknown {
+	const toml = typeof Bun !== "undefined" ? Bun.TOML : undefined;
+	if (!toml || typeof toml.parse !== "function") return null;
+	try {
+		return toml.parse(text);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The package's requirement kind from `uv-receipt.toml`; null =
+ * unreadable/unparseable/absent.
+ *
+ * Only a requirement carrying nothing but `name` (and `extras`) is `index`: that
+ * is the one shape where uv's silence in `--outdated` may be read as "current".
+ */
+export function parseUvReceipt(
+	toml: string,
+	pkg: string,
+): UvRequirementSource | null {
+	const body = parseToml(toml) as {
+		tool?: { requirements?: unknown };
+	} | null;
+	const reqs = body?.tool?.requirements;
+	if (!Array.isArray(reqs)) return null;
+	const want = normalizePythonPackageName(pkg);
+	const req = reqs.find((r: unknown) => {
+		const name = (r as { name?: unknown } | null)?.name;
+		return (
+			typeof name === "string" && normalizePythonPackageName(name) === want
+		);
+	}) as Record<string, unknown> | undefined;
+	if (!req) return null;
+	for (const kind of ["git", "editable", "directory", "path", "url"] as const) {
+		if (kind in req) return kind;
+	}
+	const extra = Object.keys(req).filter((k) => k !== "name" && k !== "extras");
+	return extra.length === 0 ? "index" : "index-constrained";
+}
+
+/** `pipx list --json` → normalised package → version. */
+export function parsePipxListJson(body: unknown): Map<string, string> {
+	const out = new Map<string, string>();
+	const venvs = (body as { venvs?: unknown } | null)?.venvs;
+	if (!venvs || typeof venvs !== "object") return out;
+	for (const [venv, value] of Object.entries(
+		venvs as Record<string, unknown>,
+	)) {
+		const main = (
+			value as {
+				metadata?: {
+					main_package?: { package?: unknown; package_version?: unknown };
+				};
+			} | null
+		)?.metadata?.main_package;
+		if (typeof main?.package_version !== "string") continue;
+		const key = typeof main.package === "string" ? main.package : venv;
+		out.set(normalizePythonPackageName(key), main.package_version);
+	}
+	return out;
+}
+
+/**
+ * `go version -m <binary>` → its main module and version, plus the main
+ * package path when printed.
+ */
+export function parseGoVersionM(
+	stdout: string,
+): { module: string; version: string; path?: string } | null {
+	let pkgPath: string | undefined;
+	for (const line of stdout.split("\n")) {
+		const p = /^\s*path\s+(\S+)/.exec(line);
+		if (p?.[1]) pkgPath = p[1];
+		const m = /^\s*mod\s+(\S+)\s+(\S+)/.exec(line);
+		if (m?.[1] && m[2]) {
+			return {
+				module: m[1],
+				version: m[2],
+				...(pkgPath ? { path: pkgPath } : {}),
+			};
+		}
+	}
+	return null;
+}
+
+/**
+ * Pick the version out of a PyPI JSON API body.
+ *
+ * Split out from the fetch so it is testable without a network: the parsing is
+ * the part that can be wrong, and the part that must not throw.
+ */
+export function versionFromPypiJson(body: unknown): string | undefined {
+	const info = (body as { info?: { version?: unknown } } | null)?.info;
+	return typeof info?.version === "string" ? info.version : undefined;
+}
+
+/** An npm registry dist-tags body (`{ latest: "x", … }`) → "x". */
+export function versionFromNpmDistTags(body: unknown): string | undefined {
+	const latest = (body as { latest?: unknown } | null)?.latest;
+	return typeof latest === "string" ? latest : undefined;
+}
+
+/**
+ * The first version-like token in a `--version` output ("tmux 3.7c" → "3.7c",
+ * "2.1.268 (Claude Code)" → "2.1.268", "v2.0.0" → "2.0.0"). Needs at least one
+ * dot, so a bare number (a year, a count) is not mistaken for a version.
+ */
+export function parseVersionToken(output: string): string | null {
+	const m = /(?:^|[^\w.])v?(\d+(?:\.\d+)+[0-9A-Za-z.+-]*)/.exec(output);
+	if (!m?.[1]) return null;
+	return m[1].replace(/[.+-]+$/, "");
+}
+
+/** true when `resolved` lies inside `ownerDir` (compared with a trailing separator). */
+export function isInside(resolved: string, ownerDir: string): boolean {
+	const dir = path.resolve(ownerDir);
+	const file = path.resolve(resolved);
+	return file.startsWith(dir.endsWith(path.sep) ? dir : `${dir}${path.sep}`);
+}
+
+// ── IO seam ──────────────────────────────────────────────────────────────────
+
+export interface ExecResult {
+	/** null when killed. */
+	code: number | null;
+	stdout: string;
+	stderr: string;
+	timedOut: boolean;
+	/** Executable not found (ENOENT). */
+	missing: boolean;
+}
+
+export type FetchJsonResult =
+	| { ok: true; body: unknown }
+	| { ok: false; reason: string };
+
+export interface ToolProbeIO {
+	/** argv only, captured stdio, never a shell, never throws. */
+	exec(
+		command: Command,
+		opts: { timeoutMs: number; env?: Readonly<Record<string, string>> },
+	): Promise<ExecResult>;
+	fetchJson(url: string, opts: { timeoutMs: number }): Promise<FetchJsonResult>;
+	/** null when absent/unreadable. */
+	readJson(file: string): Promise<unknown | null>;
+	/** null when absent/unreadable (uv receipts). */
+	readText(file: string): Promise<string | null>;
+	readlink(file: string): Promise<string | null>;
+	realpath(file: string): Promise<string | null>;
+	/**
+	 * The first executable `name` on PATH, AS FOUND ON PATH (not resolved), or
+	 * null. A dangling symlink is not executable and does not count.
+	 */
+	resolveExecutable(name: string): Promise<string | null>;
+	env: Readonly<Record<string, string | undefined>>;
+	homedir: string;
+}
+
+async function isExecutable(file: string): Promise<boolean> {
+	try {
+		// Both follow symlinks, so a dangling link fails here.
+		if (!(await stat(file)).isFile()) return false;
+		await fsAccess(file, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export const REAL_TOOL_PROBE_IO: ToolProbeIO = {
+	exec: (command, opts) =>
+		new Promise((resolve) => {
+			execFile(
+				command.cmd,
+				[...command.args],
+				{
+					timeout: opts.timeoutMs,
+					env: opts.env ? { ...process.env, ...opts.env } : process.env,
+					maxBuffer: 16 * 1024 * 1024,
+					encoding: "utf8",
+					windowsHide: true,
+				},
+				(error, stdout, stderr) => {
+					if (!error) {
+						resolve({
+							code: 0,
+							stdout,
+							stderr,
+							timedOut: false,
+							missing: false,
+						});
+						return;
+					}
+					const e = error as NodeJS.ErrnoException & {
+						code?: unknown;
+						killed?: boolean;
+						signal?: string | null;
+					};
+					// A maxBuffer overflow also arrives killed, with a string code.
+					// Calling that "timed out" would put a wrong cause in the note
+					// of output that was merely too large.
+					const overflowed = e.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+					resolve({
+						code: typeof e.code === "number" ? e.code : null,
+						stdout: stdout ?? "",
+						stderr: overflowed
+							? `${command.cmd} printed more than 16MB`
+							: (stderr ?? ""),
+						timedOut: e.killed === true && !overflowed && e.code !== "ENOENT",
+						missing: e.code === "ENOENT",
+					});
+				},
+			);
+		}),
+	fetchJson: async (url, opts) => {
+		try {
+			// No credentials: a public registry GET, nothing else.
+			const res = await fetch(url, {
+				signal: AbortSignal.timeout(opts.timeoutMs),
+				headers: { accept: "application/json" },
+			});
+			if (!res.ok) return { ok: false, reason: `returned ${res.status}` };
+			return { ok: true, body: await res.json() };
+		} catch (error) {
+			const name = error instanceof Error ? error.name : "";
+			return {
+				ok: false,
+				reason:
+					name === "TimeoutError" || name === "AbortError"
+						? `timed out after ${Math.round(opts.timeoutMs / 1000)}s`
+						: error instanceof Error
+							? error.message
+							: String(error),
+			};
+		}
+	},
+	readJson: async (file) => {
+		try {
+			return JSON.parse(await readFile(file, "utf8"));
+		} catch {
+			return null;
+		}
+	},
+	readText: async (file) => {
+		try {
+			return await readFile(file, "utf8");
+		} catch {
+			return null;
+		}
+	},
+	readlink: async (file) => {
+		try {
+			return await fsReadlink(file);
+		} catch {
+			return null;
+		}
+	},
+	realpath: async (file) => {
+		try {
+			return await fsRealpath(file);
+		} catch {
+			return null;
+		}
+	},
+	resolveExecutable: async (name) => {
+		for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+			if (!dir) continue;
+			const candidate = path.join(dir, name);
+			if (await isExecutable(candidate)) return candidate;
+		}
+		return null;
+	},
+	env: process.env,
+	homedir: os.homedir(),
+};
+
+export const PROBE_TIMEOUT_MS = 8000 as const;
+export const PROBE_DEADLINE_MS = 20000 as const;
+export const PROBE_CONCURRENCY = 4 as const;
+
+export interface ProbeProgress {
+	index: number;
+	settled: number;
+	total: number;
+}
+
+export interface ProbeOptions {
+	timeoutMs?: number;
+	deadlineMs?: number;
+	concurrency?: number;
+	/**
+	 * Fires as each tool settles, in completion order. `index` is the spec's
+	 * index; `settled` is monotonic (1..total) and is what a progress meter
+	 * must use.
+	 */
+	onResult?: (facts: ToolFacts, progress: ProbeProgress) => void;
+	/**
+	 * Run a spec's `check` command when no installer record can give the
+	 * version. Default FALSE, and every planning caller leaves it so: `check`
+	 * is a string a third-party `plugin.json` supplied, and planning — which
+	 * includes `--dry-run` and `--check` — executes nothing a catalogue wrote.
+	 * See {@link versionFromCheck} for what is still bounded when it is on.
+	 */
+	allowCheckCommand?: boolean;
+}
+
+// ── Probe session: memoised batch and location queries ──────────────────────
+
+/** Extra env for brew: never mutate brew state, and keep output plain. */
+const BREW_ENV = {
+	HOMEBREW_NO_AUTO_UPDATE: "1",
+	HOMEBREW_NO_ENV_HINTS: "1",
+	NO_COLOR: "1",
+} as const;
+const PLAIN_ENV = { NO_COLOR: "1" } as const;
+
+type Located = { dir: string } | { failure: string };
+
+type UvOutdated =
+	| { ok: true; map: Map<string, { installed: string; latest: string | null }> }
+	| { ok: false; unsupported: boolean; failure: string };
+
+function firstLine(text: string): string {
+	return (
+		text
+			.split("\n")
+			.find((l) => l.trim())
+			?.trim() ?? ""
+	);
+}
+
+function execFailure(cmd: string, r: ExecResult, timeoutMs: number): string {
+	if (r.missing) return `${cmd} is not installed`;
+	if (r.timedOut)
+		return `${cmd} timed out after ${Math.round(timeoutMs / 1000)}s`;
+	return firstLine(r.stderr) || `${cmd} exited ${r.code ?? "abnormally"}`;
+}
+
+/**
+ * One per {@link probeTools} call. Each location or batch query is a memoised
+ * promise, run only if some spec needs it — N pip tools cost the same four uv
+ * subprocesses as one.
+ */
+class ProbeSession {
+	private readonly memo = new Map<string, Promise<unknown>>();
+
+	constructor(
+		readonly io: ToolProbeIO,
+		readonly timeoutMs: number,
+		/** See {@link versionFromCheck}. Off unless the caller opted in. */
+		readonly allowCheckCommand: boolean = false,
+	) {}
+
+	once<T>(key: string, work: () => Promise<T>): Promise<T> {
+		const hit = this.memo.get(key);
+		if (hit) return hit as Promise<T>;
+		const p = work();
+		this.memo.set(key, p);
+		return p;
+	}
+
+	run(
+		cmd: string,
+		args: string[],
+		env?: Readonly<Record<string, string>>,
+	): Promise<ExecResult> {
+		return this.io.exec(
+			{ cmd, args },
+			{ timeoutMs: this.timeoutMs, ...(env ? { env } : {}) },
+		);
+	}
+
+	/** stdout's first line of a location query. */
+	private locate(key: string, cmd: string, args: string[]): Promise<Located> {
+		return this.once(key, async () => {
+			const r = await this.run(cmd, args, PLAIN_ENV);
+			const dir = r.code === 0 ? firstLine(r.stdout) : "";
+			return dir ? { dir } : { failure: execFailure(cmd, r, this.timeoutMs) };
+		});
+	}
+
+	brewPrefix(): Promise<Located> {
+		const fromEnv = this.io.env.HOMEBREW_PREFIX;
+		if (fromEnv) return Promise.resolve({ dir: fromEnv });
+		return this.locate("brew --prefix", "brew", ["--prefix"]);
+	}
+
+	uvToolDir(): Promise<Located & { missing?: boolean }> {
+		return this.once("uv tool dir", async () => {
+			const r = await this.run("uv", ["tool", "dir"], PLAIN_ENV);
+			const dir = r.code === 0 ? firstLine(r.stdout) : "";
+			if (dir) return { dir };
+			return {
+				failure: execFailure("uv", r, this.timeoutMs),
+				missing: r.missing,
+			};
+		});
+	}
+
+	uvBinDir(): Promise<Located> {
+		return this.locate("uv tool dir --bin", "uv", ["tool", "dir", "--bin"]);
+	}
+
+	uvList(): Promise<Map<string, { installed: string; latest: string | null }>> {
+		return this.once("uv tool list", async () => {
+			const r = await this.run("uv", ["tool", "list"], PLAIN_ENV);
+			return r.code === 0 ? parseUvToolList(r.stdout) : new Map();
+		});
+	}
+
+	uvOutdated(): Promise<UvOutdated> {
+		return this.once("uv tool list --outdated", async () => {
+			const r = await this.run("uv", ["tool", "list", "--outdated"], PLAIN_ENV);
+			if (r.code === 0) return { ok: true, map: parseUvToolList(r.stdout) };
+			return {
+				ok: false,
+				// Older uv rejects the flag; that is "ask PyPI", not "index down".
+				unsupported: /unexpected argument/i.test(r.stderr),
+				failure: execFailure("uv", r, this.timeoutMs),
+			};
+		});
+	}
+
+	pipxList(): Promise<Map<string, string> | null> {
+		return this.once("pipx list --json", async () => {
+			const r = await this.run("pipx", ["list", "--json"], PLAIN_ENV);
+			if (r.code !== 0) return null;
+			try {
+				return parsePipxListJson(JSON.parse(r.stdout));
+			} catch {
+				return new Map<string, string>();
+			}
+		});
+	}
+
+	npmRoot(): Promise<Located> {
+		return this.locate("npm root -g", "npm", ["root", "-g"]);
+	}
+
+	goBin(): Promise<Located> {
+		return this.once("go env GOBIN GOPATH", async () => {
+			const r = await this.run("go", ["env", "GOBIN", "GOPATH"], PLAIN_ENV);
+			if (r.code !== 0)
+				return { failure: execFailure("go", r, this.timeoutMs) };
+			const [gobin = "", gopath = ""] = r.stdout
+				.split("\n")
+				.map((l) => l.trim());
+			if (gobin) return { dir: gobin };
+			const first = gopath.split(path.delimiter)[0];
+			return first
+				? { dir: path.join(first, "bin") }
+				: { failure: "go reported no GOBIN or GOPATH" };
+		});
+	}
+}
+
+// ── Probing one tool ─────────────────────────────────────────────────────────
+
+/** Characters that make a check command something only a shell could run. */
+const SHELL_META = /[|&;<>()$`\\"'*?{}[\]~!#\n\r]/;
+
+/**
+ * Refuse a name that could be read as an option, carries a NUL, or (for a
+ * value joined into a path) climbs out of its directory. Null when fine.
+ */
+function refusal(spec: BinRequirement): string | null {
+	const bad = (v: string | undefined, isPath: boolean): boolean =>
+		v !== undefined &&
+		(v.startsWith("-") ||
+			v.includes("\0") ||
+			(isPath && v.split("/").some((s) => s === ".." || s === ".")));
+	if (bad(spec.name, true) || spec.name.includes("/") || !spec.name)
+		return "refused: name is not a valid name";
+	if (bad(spec.package, true)) return "refused: package is not a valid name";
+	if (bad(spec.formula, false)) return "refused: formula is not a valid name";
+	if (bad(spec.module, false)) return "refused: module is not a valid name";
+	return null;
+}
+
+/** A mutable facts record: whatever is known when the deadline hits survives. */
+function blankFacts(name: string): ToolFacts {
+	return {
+		name,
+		present: true,
+		resolvedPath: null,
+		installed: null,
+		latest: null,
+		behind: null,
+		managed: null,
+		sources: [],
+	};
+}
+
+function addSource(f: ToolFacts, s: ToolFactSource): void {
+	if (!f.sources.includes(s)) f.sources.push(s);
+}
+
+function noteFailure(f: ToolFacts, failure: string): void {
+	if (!f.failure) f.failure = failure;
+}
+
+/** The version a real, resolved directory's package.json declares. */
+async function packageJsonVersion(
+	io: ToolProbeIO,
+	dir: string,
+): Promise<string | null> {
+	const pkg = (await io.readJson(path.join(dir, "package.json"))) as {
+		version?: unknown;
+	} | null;
+	return typeof pkg?.version === "string" ? pkg.version : null;
+}
+
+/**
+ * Last resort for the installed version: run the tool's own check command and
+ * take the first version token.
+ *
+ * NOT REACHED WHILE PLANNING. `spec.check` is copied verbatim out of a
+ * marketplace plugin's `plugin.json` (`plugin-requires.ts`), so it is a string
+ * a third party wrote. Before this probe existed nothing in claudeup ever ran
+ * it; running it to PLAN would have meant `claudeup update`, `--dry-run`,
+ * `--check` in CI and merely opening the TUI's Tools screen each executing a
+ * catalogue-supplied argv — and `--dry-run` is documented as writing nothing.
+ * So the planner does not opt in: a version that could only come from a check
+ * command stays null, which classifies as `unknown / version-unreadable`,
+ * never as an upgrade. The one caller that opts in is the post-install
+ * read-back (`update-engine.ts`), where the user has already consented to run
+ * that tool's installer.
+ *
+ * Where it does run it is bounded on every axis:
+ *  - argv only, split on whitespace, never a shell (a `SHELL_META` character
+ *    refuses the whole string);
+ *  - argv[0] must be the tool itself — its name, its path on PATH, or the
+ *    realpath behind it. The probe's purpose is "ask the running file its
+ *    version", so anything else is refused unrun, and the version reported can
+ *    only have come from the binary `resolvedPath` names;
+ *  - the session's `timeoutMs` (8s by default), through the injected IO seam,
+ *    which captures stdio rather than inheriting the terminal.
+ */
+async function versionFromCheck(
+	s: ProbeSession,
+	spec: BinRequirement,
+	f: ToolFacts,
+	onPath: string,
+): Promise<void> {
+	if (!s.allowCheckCommand) {
+		noteFailure(f, "no installer record, and check commands are not run here");
+		return;
+	}
+	const check = spec.check?.trim() || `${spec.name} --version`;
+	if (SHELL_META.test(check)) {
+		noteFailure(f, "check command needs a shell; not run");
+		return;
+	}
+	const [cmd, ...args] = check.split(/\s+/);
+	if (!cmd) return;
+	if (cmd !== spec.name && cmd !== onPath && cmd !== f.resolvedPath) {
+		noteFailure(f, `check command does not run ${spec.name}; not run`);
+		return;
+	}
+	const r = await s.run(cmd, args, PLAIN_ENV);
+	if (r.missing || r.timedOut) {
+		noteFailure(f, execFailure(cmd, r, s.timeoutMs));
+		return;
+	}
+	const v = parseVersionToken(`${r.stdout}\n${r.stderr}`);
+	if (v) {
+		f.installed = v;
+		addSource(f, "check-command");
+	}
+}
+
+/** The npm registry's `latest` dist-tag for a package. */
+async function npmLatest(
+	s: ProbeSession,
+	pkg: string,
+	f: ToolFacts,
+): Promise<void> {
+	const registry = (
+		s.io.env.npm_config_registry ?? "https://registry.npmjs.org"
+	).replace(/\/+$/, "");
+	// Keep a scope's `@`, encode its `/` as %2F (verified against the real
+	// registry for @openai/codex).
+	const encoded = encodeURIComponent(pkg).replace(/^%40/, "@");
+	const r = await s.io.fetchJson(`${registry}/-/package/${encoded}/dist-tags`, {
+		timeoutMs: s.timeoutMs,
+	});
+	if (!r.ok) {
+		noteFailure(f, `npm registry ${r.reason}`);
+		return;
+	}
+	const latest = versionFromNpmDistTags(r.body);
+	if (latest) {
+		f.latest = latest;
+		addSource(f, "npm-registry");
+	} else noteFailure(f, "npm registry published no latest tag");
+}
+
+async function pypiLatest(
+	s: ProbeSession,
+	pkg: string,
+	f: ToolFacts,
+): Promise<void> {
+	const r = await s.io.fetchJson(
+		`https://pypi.org/pypi/${encodeURIComponent(pkg)}/json`,
+		{ timeoutMs: s.timeoutMs },
+	);
+	if (!r.ok) {
+		noteFailure(f, `PyPI ${r.reason}`);
+		return;
+	}
+	const latest = versionFromPypiJson(r.body);
+	if (latest) {
+		f.latest = latest;
+		addSource(f, "pypi");
+	} else noteFailure(f, "PyPI published no version");
+}
+
+/** Ownership by realpath containment in `ownerDir` (itself realpath'd). */
+async function containedIn(
+	s: ProbeSession,
+	resolvedPath: string,
+	ownerDir: string,
+): Promise<{ inside: boolean; real: string | null }> {
+	const real = await s.io.realpath(ownerDir);
+	return { inside: real !== null && isInside(resolvedPath, real), real };
+}
+
+async function probeBrew(
+	s: ProbeSession,
+	spec: BinRequirement,
+	f: ToolFacts,
+	resolvedPath: string,
+): Promise<void> {
+	const formula = spec.formula ?? spec.name;
+	const prefix = await s.brewPrefix();
+	if ("failure" in prefix) {
+		f.managed = null;
+		noteFailure(f, prefix.failure);
+		return;
+	}
+	const cellar =
+		(await s.io.realpath(path.join(prefix.dir, "Cellar"))) ??
+		path.join(prefix.dir, "Cellar");
+	const ownerDir = path.join(cellar, formula);
+	f.owner = `brew (Cellar ${ownerDir})`;
+	f.managed = isInside(resolvedPath, ownerDir);
+	if (!f.managed) return;
+	f.installed = brewKegVersion(resolvedPath, cellar, formula);
+	if (f.installed) addSource(f, "brew");
+
+	const r = await s.run("brew", ["outdated", "--json=v2", formula], BREW_ENV);
+	if (r.code !== 0) {
+		noteFailure(f, execFailure("brew", r, s.timeoutMs));
+		return;
+	}
+	const parsed = parseBrewOutdatedJson(r.stdout, formula);
+	if (!parsed) {
+		noteFailure(f, "brew outdated printed something unreadable");
+		return;
+	}
+	addSource(f, "brew");
+	f.behind = parsed.behind;
+	if (parsed.latest) f.latest = parsed.latest;
+	if (parsed.pinned) f.heldBack = "held by brew pin";
+}
+
+async function probePip(
+	s: ProbeSession,
+	spec: BinRequirement,
+	f: ToolFacts,
+	onPath: string,
+	resolvedPath: string,
+	pinned: boolean,
+): Promise<void> {
+	const pkg = spec.package ?? spec.name;
+	const norm = normalizePythonPackageName(pkg);
+
+	const uvDir = await s.uvToolDir();
+	if ("dir" in uvDir) {
+		const ownerDir = path.join(uvDir.dir, norm);
+		f.owner = `uv (tool dir ${uvDir.dir})`;
+		const { inside, real } = await containedIn(s, resolvedPath, ownerDir);
+		// Adoption: `uv tool install --force` overwrites the very file PATH runs
+		// when it sits in uv's bin dir, whoever put it there.
+		const bin = await s.uvBinDir();
+		const adopted =
+			"dir" in bin &&
+			path.resolve(path.dirname(onPath)) === path.resolve(bin.dir);
+		f.managed = inside || adopted;
+		if (adopted && !inside) {
+			// uv did not install this file, but `--force` will overwrite it. The
+			// plan row is an ordinary upgrade, so without this it never says that
+			// the owning installer changes — and pipx, say, goes on claiming a
+			// venv nothing runs until its next `upgrade-all` writes back over it.
+			f.adopted = `installed by another tool in uv's bin dir (${bin.dir}); upgrading adopts it into uv`;
+			addSource(f, "uv-adopted");
+		}
+
+		if (inside) {
+			const listed = (await s.uvList()).get(norm);
+			if (listed) {
+				f.installed = listed.installed;
+				addSource(f, "uv");
+			}
+		}
+		if (!f.managed || pinned) return;
+
+		const outdated = await s.uvOutdated();
+		if (outdated.ok) {
+			const hit = outdated.map.get(norm);
+			if (hit) {
+				f.behind = true;
+				f.latest = hit.latest;
+				addSource(f, "uv");
+				return;
+			}
+			const receiptText = await s.io.readText(
+				path.join(real ?? ownerDir, "uv-receipt.toml"),
+			);
+			const kind =
+				inside && receiptText !== null
+					? parseUvReceipt(receiptText, pkg)
+					: null;
+			if (kind) addSource(f, "uv-receipt");
+			if (kind === "index") {
+				f.behind = false;
+				return;
+			}
+			if (
+				kind === "git" ||
+				kind === "directory" ||
+				kind === "path" ||
+				kind === "url" ||
+				kind === "editable"
+			) {
+				f.behind = null;
+				f.latest = null;
+				noteFailure(f, `installed from ${kind}, not a package index`);
+				return;
+			}
+			// Constrained, or a receipt we could not read: ask PyPI.
+			await pypiLatest(s, pkg, f);
+			return;
+		}
+		if (!outdated.unsupported) noteFailure(f, outdated.failure);
+		await pypiLatest(s, pkg, f);
+		return;
+	}
+
+	if (!uvDir.missing) {
+		// uv exists but would not say where it keeps tools.
+		f.managed = null;
+		noteFailure(f, uvDir.failure);
+		if (!pinned) await pypiLatest(s, pkg, f);
+		return;
+	}
+
+	const pipx = await s.pipxList();
+	if (pipx !== null) {
+		const home =
+			s.io.env.PIPX_HOME ?? path.join(s.io.homedir, ".local", "pipx");
+		const binDir =
+			s.io.env.PIPX_BIN_DIR ?? path.join(s.io.homedir, ".local", "bin");
+		const ownerDir = path.join(home, "venvs", norm);
+		f.owner = `pipx (venvs ${path.join(home, "venvs")})`;
+		const { inside } = await containedIn(s, resolvedPath, ownerDir);
+		f.managed =
+			inside || path.resolve(path.dirname(onPath)) === path.resolve(binDir);
+		const v = inside ? pipx.get(norm) : undefined;
+		if (v) {
+			f.installed = v;
+			addSource(f, "pipx");
+		}
+		if (f.managed && !pinned) await pypiLatest(s, pkg, f);
+		return;
+	}
+
+	// `python3 -m pip --user` only: its location is not queried.
+	f.managed = null;
+	noteFailure(f, "neither uv nor pipx is installed");
+	if (!pinned) await pypiLatest(s, pkg, f);
+}
+
+async function probeNodeGlobal(
+	s: ProbeSession,
+	spec: BinRequirement,
+	f: ToolFacts,
+	resolvedPath: string,
+	pinned: boolean,
+): Promise<void> {
+	const pkg = spec.package ?? spec.name;
+	let root: string;
+	if (spec.via === "bun") {
+		root = path.join(
+			s.io.env.BUN_INSTALL ?? path.join(s.io.homedir, ".bun"),
+			"install",
+			"global",
+			"node_modules",
+		);
+		f.owner = `bun (global ${root})`;
+	} else {
+		const npmRoot = await s.npmRoot();
+		if ("failure" in npmRoot) {
+			f.managed = null;
+			noteFailure(f, npmRoot.failure);
+			return;
+		}
+		root = npmRoot.dir;
+		f.owner = `npm (root ${root})`;
+	}
+	const { inside, real } = await containedIn(
+		s,
+		resolvedPath,
+		path.join(root, pkg),
+	);
+	f.managed = inside;
+	if (!inside || !real) return;
+	f.installed = await packageJsonVersion(s.io, real);
+	if (f.installed)
+		addSource(f, spec.via === "bun" ? "bun-global" : "npm-global");
+	if (!pinned) await npmLatest(s, pkg, f);
+}
+
+async function probeGo(
+	s: ProbeSession,
+	spec: BinRequirement,
+	f: ToolFacts,
+	resolvedPath: string,
+	pinned: boolean,
+): Promise<void> {
+	const want = spec.module ?? spec.name;
+	const r = await s.run("go", ["version", "-m", resolvedPath], PLAIN_ENV);
+	const info = r.code === 0 ? parseGoVersionM(r.stdout) : null;
+	if (!info) {
+		f.managed = null;
+		noteFailure(
+			f,
+			r.code === 0
+				? "no Go build info in the binary"
+				: execFailure("go", r, s.timeoutMs),
+		);
+		return;
+	}
+	f.installed = info.version;
+	addSource(f, "go-buildinfo");
+
+	const gobin = await s.goBin();
+	if ("failure" in gobin) {
+		f.managed = null;
+		noteFailure(f, gobin.failure);
+		return;
+	}
+	const realBin = (await s.io.realpath(gobin.dir)) ?? gobin.dir;
+	f.owner = `go (GOBIN ${realBin})`;
+	const sameModule =
+		want === info.module ||
+		want === info.path ||
+		want.startsWith(`${info.module}/`);
+	f.managed =
+		path.resolve(path.dirname(resolvedPath)) === path.resolve(realBin) &&
+		sameModule;
+	if (!f.managed || pinned) return;
+
+	const latest = await s.run(
+		"go",
+		["list", "-m", "-f", "{{.Version}}", `${info.module}@latest`],
+		PLAIN_ENV,
+	);
+	const v = latest.code === 0 ? firstLine(latest.stdout) : "";
+	if (v) {
+		f.latest = v;
+		addSource(f, "go-proxy");
+	} else noteFailure(f, execFailure("go", latest, s.timeoutMs));
+}
+
+/** Probe one tool into `f`, mutating it as facts arrive. Never throws. */
+async function probeInto(
+	s: ProbeSession,
+	spec: BinRequirement,
+	f: ToolFacts,
+): Promise<void> {
+	const refused = refusal(spec);
+	if (refused) {
+		f.failure = refused;
+		return;
+	}
+
+	const onPath = await s.io.resolveExecutable(spec.name);
+	const resolvedPath = onPath ? await s.io.realpath(onPath) : null;
+	addSource(f, "path");
+	if (!onPath || !resolvedPath) {
+		f.present = false;
+		return;
+	}
+	f.present = true;
+	f.resolvedPath = resolvedPath;
+
+	const pinned = pinOf(spec) !== undefined;
+	const via: BinInstaller = spec.via;
+	switch (via) {
+		case "brew":
+			await probeBrew(s, spec, f, resolvedPath);
+			break;
+		case "pip":
+			await probePip(s, spec, f, onPath, resolvedPath, pinned);
+			break;
+		case "bun":
+		case "npm":
+			await probeNodeGlobal(s, spec, f, resolvedPath, pinned);
+			break;
+		case "go":
+			await probeGo(s, spec, f, resolvedPath, pinned);
+			break;
+	}
+
+	// The method's own record was silent: read the running file itself — but
+	// only where the caller opted into running a check command (see there).
+	if (f.installed === null) await versionFromCheck(s, spec, f, onPath);
+}
+
+/** A copy, with the verdict fields cleared: a timed-out tool is never "behind". */
+function timedOut(f: ToolFacts, deadlineMs: number): ToolFacts {
+	return {
+		...f,
+		sources: [...f.sources],
+		latest: null,
+		behind: null,
+		failure: `timed out after ${Math.round(deadlineMs / 1000)}s`,
+	};
+}
+
+async function probeWithDeadline(
+	s: ProbeSession,
+	spec: BinRequirement,
+	deadlineAt: number,
+	deadlineMs: number,
+): Promise<ToolFacts> {
+	const f = blankFacts(spec.name);
+	const remaining = deadlineAt - Date.now();
+	if (remaining <= 0) return timedOut(f, deadlineMs);
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const deadline = new Promise<"deadline">((resolve) => {
+		timer = setTimeout(() => resolve("deadline"), remaining);
+	});
+	try {
+		const outcome = await Promise.race([
+			probeInto(s, spec, f).then(
+				() => "done" as const,
+				(error: unknown) => {
+					noteFailure(
+						f,
+						error instanceof Error ? error.message : String(error),
+					);
+					return "done" as const;
+				},
+			),
+			deadline,
+		]);
+		return outcome === "deadline"
+			? timedOut(f, deadlineMs)
+			: { ...f, sources: [...f.sources] };
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+/**
+ * Facts for every spec, in spec order. Never rejects: every failure becomes
+ * facts with `failure` set, which classify as `unknown`, never `upgrade`.
+ */
+export async function probeTools(
+	specs: readonly BinRequirement[],
+	io: ToolProbeIO = REAL_TOOL_PROBE_IO,
+	opts: ProbeOptions = {},
+): Promise<ToolFacts[]> {
+	const timeoutMs = opts.timeoutMs ?? PROBE_TIMEOUT_MS;
+	const deadlineMs = opts.deadlineMs ?? PROBE_DEADLINE_MS;
+	const concurrency = Math.max(1, opts.concurrency ?? PROBE_CONCURRENCY);
+	const session = new ProbeSession(
+		io,
+		timeoutMs,
+		opts.allowCheckCommand === true,
+	);
+	const deadlineAt = Date.now() + deadlineMs;
+	const results: ToolFacts[] = new Array(specs.length);
+	let next = 0;
+	let settled = 0;
+
+	const worker = async (): Promise<void> => {
+		while (next < specs.length) {
+			const index = next++;
+			const spec = specs[index];
+			if (!spec) {
+				// Unreachable from today's callers, and it must stay that way in
+				// the RESULT too: a hole in the array would make
+				// `planBinUpdates`' `new Map(facts.map(…))` throw, instead of
+				// degrading to the `unknown / not-probed` the contract promises.
+				results[index] = { ...blankFacts(""), failure: "not probed" };
+				continue;
+			}
+			const facts = await probeWithDeadline(
+				session,
+				spec,
+				deadlineAt,
+				deadlineMs,
+			);
+			results[index] = facts;
+			settled++;
+			try {
+				opts.onResult?.(facts, { index, settled, total: specs.length });
+			} catch {
+				// A progress callback must not turn a probe into a rejection.
+			}
+		}
+	};
+
+	await Promise.all(
+		Array.from({ length: Math.min(concurrency, specs.length) }, worker),
+	);
+	return results;
+}
+
+/** One tool, with its own probe session. */
+export async function probeTool(
+	spec: BinRequirement,
+	io: ToolProbeIO = REAL_TOOL_PROBE_IO,
+	opts: Omit<ProbeOptions, "concurrency" | "onResult"> = {},
+): Promise<ToolFacts> {
+	const [facts] = await probeTools([spec], io, { ...opts, concurrency: 1 });
+	return facts ?? { ...blankFacts(spec.name), failure: "not probed" };
+}
+
+// ── Catalogue bridge + install-method detection ──────────────────────────────
+
+export interface InstallInfo {
+	primary: InstallMethod;
+	all: InstallMethod[];
+	brewFormula?: string;
+}
+
+const BIN_INSTALLER_METHODS: ReadonlySet<InstallMethod> = new Set([
+	"npm",
+	"bun",
+	"brew",
+	"pip",
+]);
+
+function isBinInstaller(m: InstallMethod): m is BinInstaller & InstallMethod {
+	return BIN_INSTALLER_METHODS.has(m);
+}
+
+/**
+ * The spec a catalogue tool is probed through, in order:
+ *
+ *  1. the active profile's `ResolvedBin` of the same name — the same pin and
+ *     the same installer `claudeup update` uses, so the two agree;
+ *  2. the DETECTED installer, when it is one claudeup models — "how it IS
+ *     installed", the rule `cliToolUpdate` follows, so the row's state and the
+ *     command Enter offers name the same installer;
+ *  3. the catalogue's own mapping. For a pnpm/yarn install this probes a
+ *     manager that does not own the file, which is reported as `not-managed`.
+ */
+export function specForCatalogTool(
+	tool: CliTool,
+	closureBins: readonly ResolvedBin[] | null,
+	install: InstallInfo | undefined,
+): BinRequirement {
+	const declared = closureBins?.find((b) => b.name === tool.name);
+	if (declared) return declared;
+	if (install && isBinInstaller(install.primary)) {
+		return {
+			name: tool.name,
+			via: install.primary,
+			package: tool.packageName,
+			check: tool.checkCommand,
+			...(install.brewFormula ? { formula: install.brewFormula } : {}),
+		};
+	}
+	return {
+		name: tool.name,
+		via: tool.packageManager,
+		package: tool.packageName,
+		check: tool.checkCommand,
+	};
+}
+
+function methodFromPath(binPath: string): InstallMethod | null {
+	if (binPath.includes("/.bun/")) return "bun";
+	if (binPath.includes("/homebrew/") || binPath.includes("/Cellar/"))
+		return "brew";
+	if (
+		binPath.includes("/.local/share/claude") ||
+		binPath.includes("/.local/bin/claude")
+	)
+		return "npm";
+	if (binPath.includes("/.nvm/") || binPath.includes("/node_modules/"))
+		return "npm";
+	if (binPath.includes("/.local/share/pnpm") || binPath.includes("/pnpm/"))
+		return "pnpm";
+	if (binPath.includes("/.yarn/")) return "yarn";
+	return null;
+}
+
+/** The brew formula from a Cellar path like ../Cellar/gemini-cli/0.35.2/bin/gemini. */
+function extractBrewFormula(
+	binPath: string,
+	linkTarget: string,
+): string | undefined {
+	const cellarMatch = linkTarget.match(/Cellar\/([^/]+)\//);
+	if (cellarMatch) return cellarMatch[1];
+	const pathMatch = binPath.match(/Cellar\/([^/]+)\//);
+	if (pathMatch) return pathMatch[1];
+	return undefined;
+}
+
+/**
+ * How a catalogue tool IS installed, from every copy on PATH (`which -a`) and
+ * each one's symlink target. Moved from the CLI Tools screen unchanged in
+ * behaviour, except that `which` and `readlink` now run as argv through the IO
+ * seam instead of a `/bin/bash` pipeline.
+ */
+export async function detectInstallMethods(
+	tool: CliTool,
+	io: ToolProbeIO = REAL_TOOL_PROBE_IO,
+): Promise<InstallInfo> {
+	const fallback: InstallMethod =
+		tool.packageManager === "pip" ? "pip" : "unknown";
+	if (!tool.name || tool.name.startsWith("-") || tool.name.includes("/"))
+		return { primary: fallback, all: [] };
+	const r = await io.exec(
+		{ cmd: "which", args: ["-a", tool.name] },
+		{ timeoutMs: 3000 },
+	);
+	if (r.code !== 0) return { primary: fallback, all: [] };
+	const paths = r.stdout
+		.trim()
+		.split("\n")
+		.map((p) => p.trim())
+		.filter((p) => p && !p.includes("aliased"));
+	if (paths.length === 0) return { primary: fallback, all: [] };
+
+	const methods: InstallMethod[] = [];
+	let brewFormula: string | undefined;
+	for (const binPath of paths) {
+		let method = methodFromPath(binPath);
+		const linkTarget = (await io.readlink(binPath)) ?? "";
+		if (!method && linkTarget) method = methodFromPath(linkTarget);
+		if (method === "brew" && !brewFormula) {
+			brewFormula = extractBrewFormula(binPath, linkTarget);
+		}
+		if (method && !methods.includes(method)) methods.push(method);
+	}
+
+	const primary = methods[0];
+	if (primary === undefined) return { primary: fallback, all: [] };
+	return { primary, all: methods, ...(brewFormula ? { brewFormula } : {}) };
+}