@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/domains/toolchain/registry.ts

@@ -0,0 +1,265 @@
+import type { PinnedTool, ToolPlatform } from "./types.js";
+
+/**
+ * The pinned table.
+ *
+ * Every checksum here was computed from the asset as downloaded from the URL
+ * beside it, not copied from a release note. Where upstream publishes its own
+ * checksum file the two were compared and agree; where upstream publishes no
+ * checksums, only the platform whose asset was actually fetched and hashed is
+ * listed, because a hash nobody verified is worse than a missing platform: it
+ * turns an honest "no asset for your platform" into a failed install that
+ * looks like tampering.
+ *
+ * Bumping a version means re-downloading each listed asset and re-computing
+ * each hash. The registry-shape contract test refuses an entry that carries a
+ * platform without a checksum. A bump also supersedes whatever version the
+ * machine already has, and the installer prunes it, so a tool holds exactly one
+ * version directory.
+ *
+ * `minimumVersion` is the floor a copy already on PATH has to clear. A floor
+ * moves on evidence and on nothing else: name the older release, say which of
+ * its surfaces you exercised and how, and put that in the comment beside the
+ * number. A rejection that felt noisy is not evidence. Where no such
+ * measurement exists the floor sits at the pin, because a release Clio was
+ * never run against is not something to discover through a failure that reads
+ * as a bug in the feature.
+ *
+ * The cost of a floor lands on an operator whose own copy is a release or two
+ * behind, so `describeResolution` in `resolve.ts` is required to name what it
+ * found, the floor it missed, and the command that fixes it.
+ */
+export const PINNED_TOOLS: ReadonlyArray<PinnedTool> = [
+	{
+		id: "herdr",
+		version: "0.8.2",
+		summary: "terminal multiplexer with an agent-aware socket API; powers Clio panes",
+		homepage: "https://herdr.dev",
+		license: "Apache-2.0",
+		binaries: ["herdr"],
+		primaryBinary: "herdr",
+		// Lowered from the pin on evidence, which is the bar this file sets for
+		// moving a floor. `herdr api schema --json` was read from 0.7.5
+		// (protocol 17) and 0.8.2 (protocol 20): every method the mux domain
+		// sends exists in both, and the only two 0.8.2 adds, `workspace.move_block`
+		// and `workspace.reordered`, are ones Clio never sends. The two methods
+		// that are not universal are already gated at runtime by protocol number
+		// in `src/domains/mux/protocol.ts`, whose own floor is 17, so an operator's
+		// 0.7.5 takes the documented fallback rather than failing. 0.7.5 is the
+		// oldest release actually checked, not the oldest that might work.
+		minimumVersion: "0.7.5",
+		versionArgs: ["--version"],
+		downloads: {
+			"linux-x64": {
+				url: "https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64",
+				sha256: "976150a14d490c94b243ea2e1a7eb2dfb67f12e36b182db90936f6728e6aecf4",
+				archive: "raw",
+				binaryMembers: { herdr: "" },
+				documentMembers: [],
+			},
+			"linux-arm64": {
+				url: "https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-aarch64",
+				sha256: "f55610658e1c2e0d2aaef730b4b2ab885f7f8ba00285ab372bfb14f2e3d5b40d",
+				archive: "raw",
+				binaryMembers: { herdr: "" },
+				documentMembers: [],
+			},
+			"darwin-x64": {
+				url: "https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-macos-x86_64",
+				sha256: "ab50262c8190cd7aa9056d249d255c08c328c3e8716de9cfa29db4f131b8e2c1",
+				archive: "raw",
+				binaryMembers: { herdr: "" },
+				documentMembers: [],
+			},
+			"darwin-arm64": {
+				url: "https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-macos-aarch64",
+				sha256: "a5d4f4d504d8b309c91f811050559300faba31258425f53c50852fc96f6ae574",
+				archive: "raw",
+				binaryMembers: { herdr: "" },
+				documentMembers: [],
+			},
+		},
+		// No `win32-x64` entry, and not for want of an asset. herdr publishes
+		// `herdr-windows-x86_64.zip` for this tag and it was downloaded and read:
+		// alongside `herdr.exe` it carries a ConPTY runtime, `conpty/conpty.dll`
+		// and `conpty/x64/OpenConsole.exe`, that has to sit in a subdirectory
+		// beside the executable. The installer places every declared member flat
+		// under its basename, so declaring this asset would install a `herdr.exe`
+		// with its runtime scattered next to it, which is a broken install that
+		// checksums and unpacks cleanly. Windows herdr waits on the installer
+		// learning to preserve a member's relative path.
+		//
+		// The release asset is a bare executable, so the Apache-2.0 text comes
+		// from the repository at the pinned tag.
+		documents: [
+			{
+				name: "LICENSE",
+				url: "https://raw.githubusercontent.com/herdrdev/herdr/v0.8.2/LICENSE",
+				sha256: "c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4",
+			},
+		],
+	},
+	{
+		id: "yazi",
+		version: "26.8.15",
+		summary: "terminal file manager; the file-picker pane preset",
+		homepage: "https://yazi-rs.github.io",
+		license: "MIT",
+		binaries: ["yazi", "ya"],
+		primaryBinary: "yazi",
+		// Stays at the pin, now for a measured reason rather than caution. On
+		// 26.1.22 the one command Clio sends, `ya emit-to <receiver> cd <path>`,
+		// has the same signature it has at the pin. What was never exercised
+		// there is the rest of the surface: the managed profile Clio generates
+		// (`yazi.toml`, `keymap.toml`, `init.lua`) and the DDS payload shapes a
+		// pick comes back in. A profile schema mismatch degrades quietly into a
+		// file manager that opens and does the wrong thing, which is worse than
+		// vendoring a second copy. Lower this once a pick round trip has been
+		// driven end to end on the older release.
+		minimumVersion: "26.8.15",
+		versionArgs: ["--version"],
+		downloads: {
+			"linux-x64": {
+				url: "https://github.com/sxyazi/yazi/releases/download/v26.8.15/yazi-x86_64-unknown-linux-gnu.zip",
+				sha256: "cc67eb7991550c2f9407cda52d3f5af0937627aa6884e7de99a04fcf059807e0",
+				archive: "zip",
+				binaryMembers: {
+					yazi: "yazi-x86_64-unknown-linux-gnu/yazi",
+					ya: "yazi-x86_64-unknown-linux-gnu/ya",
+				},
+				documentMembers: ["yazi-x86_64-unknown-linux-gnu/LICENSE"],
+			},
+			"linux-arm64": {
+				url: "https://github.com/sxyazi/yazi/releases/download/v26.8.15/yazi-aarch64-unknown-linux-gnu.zip",
+				sha256: "f5a85771f06bb0e8c488136ae0aedaec8d341a7cee995549df391d7d852fe8d1",
+				archive: "zip",
+				binaryMembers: {
+					yazi: "yazi-aarch64-unknown-linux-gnu/yazi",
+					ya: "yazi-aarch64-unknown-linux-gnu/ya",
+				},
+				documentMembers: ["yazi-aarch64-unknown-linux-gnu/LICENSE"],
+			},
+			"darwin-x64": {
+				url: "https://github.com/sxyazi/yazi/releases/download/v26.8.15/yazi-x86_64-apple-darwin.zip",
+				sha256: "70bb2bcf57d8af862a54e2d12f2fddceefb9aa4ba3783e9a4dcbf2a8e64aacb3",
+				archive: "zip",
+				binaryMembers: {
+					yazi: "yazi-x86_64-apple-darwin/yazi",
+					ya: "yazi-x86_64-apple-darwin/ya",
+				},
+				documentMembers: ["yazi-x86_64-apple-darwin/LICENSE"],
+			},
+			"darwin-arm64": {
+				url: "https://github.com/sxyazi/yazi/releases/download/v26.8.15/yazi-aarch64-apple-darwin.zip",
+				sha256: "3f54907ea08abe96506f4b22239340ed8923a6aeaeae78f33d59bce57daca4cd",
+				archive: "zip",
+				binaryMembers: {
+					yazi: "yazi-aarch64-apple-darwin/yazi",
+					ya: "yazi-aarch64-apple-darwin/ya",
+				},
+				documentMembers: ["yazi-aarch64-apple-darwin/LICENSE"],
+			},
+			// Same shape as the other three: two executables and a LICENSE at
+			// known member paths, so the installer needs nothing new to place it.
+			"win32-x64": {
+				url: "https://github.com/sxyazi/yazi/releases/download/v26.8.15/yazi-x86_64-pc-windows-msvc.zip",
+				sha256: "451f6770999fa8f9b08e6c9f94a688c263b6d3007b0944c4407f1ae335eace30",
+				archive: "zip",
+				binaryMembers: {
+					yazi: "yazi-x86_64-pc-windows-msvc/yazi.exe",
+					ya: "yazi-x86_64-pc-windows-msvc/ya.exe",
+				},
+				documentMembers: ["yazi-x86_64-pc-windows-msvc/LICENSE"],
+			},
+		},
+		documents: [],
+	},
+	{
+		id: "croc",
+		version: "11.3.6",
+		summary: "relay file transfer between machines; the transfer primitive's first backend",
+		homepage: "https://schollz.com/software/croc6",
+		license: "MIT",
+		binaries: ["croc"],
+		primaryBinary: "croc",
+		// Croc negotiates its relay protocol by major version, so any 11.x on
+		// PATH speaks to a pinned 11.x relay.
+		minimumVersion: "11.0.0",
+		versionArgs: ["--version"],
+		downloads: {
+			"linux-x64": {
+				url: "https://github.com/schollz/croc/releases/download/v11.3.6/croc_v11.3.6_Linux-64bit.tar.gz",
+				sha256: "bd18e01024f5ccc8e101c08c8233d4cffbfda4ff59acad80eaa1fc2963efc0b2",
+				archive: "tar.gz",
+				binaryMembers: { croc: "croc" },
+				documentMembers: ["LICENSE", "THIRD_PARTY_NOTICES.md"],
+			},
+			"linux-arm64": {
+				url: "https://github.com/schollz/croc/releases/download/v11.3.6/croc_v11.3.6_Linux-ARM64.tar.gz",
+				sha256: "c26ac67207301ed75ae0ece63796ec8a2a002b1cf64f4e3d3d8e7bcee508b5b3",
+				archive: "tar.gz",
+				binaryMembers: { croc: "croc" },
+				documentMembers: ["LICENSE", "THIRD_PARTY_NOTICES.md"],
+			},
+			"darwin-x64": {
+				url: "https://github.com/schollz/croc/releases/download/v11.3.6/croc_v11.3.6_macOS-64bit.tar.gz",
+				sha256: "701817a20f4d2bb4312f3234e6d328e0bdd68d6d1311db3a4ab4daf10906c5b2",
+				archive: "tar.gz",
+				binaryMembers: { croc: "croc" },
+				documentMembers: ["LICENSE", "THIRD_PARTY_NOTICES.md"],
+			},
+			"darwin-arm64": {
+				url: "https://github.com/schollz/croc/releases/download/v11.3.6/croc_v11.3.6_macOS-ARM64.tar.gz",
+				sha256: "96c4ef67751b4387e3d44a7a559aafe54094f0089f34a6c71dfb5361bd48d368",
+				archive: "tar.gz",
+				binaryMembers: { croc: "croc" },
+				documentMembers: ["LICENSE", "THIRD_PARTY_NOTICES.md"],
+			},
+			// A zip rather than a tarball on Windows, and the only entry in the
+			// table whose hash is confirmed by upstream's own checksums file
+			// rather than only by the download this repository made.
+			"win32-x64": {
+				url: "https://github.com/schollz/croc/releases/download/v11.3.6/croc_v11.3.6_Windows-64bit.zip",
+				sha256: "ed22552d371d55a9e3c3b612b982484fa00adaff8fb32c3f19f36dbf8e248bbf",
+				archive: "zip",
+				binaryMembers: { croc: "croc.exe" },
+				documentMembers: ["LICENSE", "THIRD_PARTY_NOTICES.md"],
+			},
+		},
+		documents: [],
+	},
+];
+
+/** The registry's platform key for the running process, or null when unmapped. */
+export function currentToolPlatform(): ToolPlatform | null {
+	const platform = process.platform;
+	const arch = process.arch;
+	if (platform === "linux") {
+		if (arch === "x64") return "linux-x64";
+		if (arch === "arm64") return "linux-arm64";
+		return null;
+	}
+	if (platform === "darwin") {
+		if (arch === "x64") return "darwin-x64";
+		if (arch === "arm64") return "darwin-arm64";
+		return null;
+	}
+	if (platform === "win32" && arch === "x64") return "win32-x64";
+	return null;
+}
+
+/** The row with this id. */
+export function findPinnedTool(id: string): PinnedTool | null {
+	return PINNED_TOOLS.find((entry) => entry.id === id) ?? null;
+}
+
+/**
+ * The row that owns this executable name.
+ *
+ * Resolution is asked for by binary name (`ya` belongs to yazi), so the lookup
+ * has to cover every name an entry installs, not just the tool id.
+ */
+export function findPinnedToolByBinary(name: string): PinnedTool | null {
+	const bare = name.endsWith(".exe") ? name.slice(0, -4) : name;
+	return PINNED_TOOLS.find((entry) => entry.binaries.includes(bare)) ?? null;
+}

package/src/domains/toolchain/remove.ts

@@ -0,0 +1,218 @@
+import { readdirSync, rmdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { toolchainRoot } from "./paths.js";
+import { findPinnedTool } from "./registry.js";
+
+/**
+ * Deleting vendored installs, and pruning the versions a pin bump superseded.
+ *
+ * Everything here only ever unlinks inside `<data>/tools/<id>/`, a directory
+ * Clio created by downloading it, so nothing an operator wrote is reachable
+ * from this file. That is what makes removal safe without a confirmation
+ * prompt: the worst outcome is a re-download of bytes the registry pins by
+ * checksum anyway.
+ *
+ * Version directories are the only thing considered. A name starting with `.`
+ * is an installer's staging or retired directory (`.<version>.incomplete-`,
+ * `.<version>.replaced-`), and a prune that raced an install and deleted one
+ * would corrupt that install. A full remove is different: it takes the whole
+ * `<id>` tree because no install of that tool is meant to survive it.
+ *
+ * A staging directory old enough to be dead is swept anyway. A killed install
+ * used to leave one behind permanently, invisible to every verb and reachable
+ * only by an operator who went reading under the data root.
+ */
+
+export interface ToolRemoveOptions {
+	/** Vendor root override. Defaults to the data root's `tools` directory. */
+	root?: string;
+	/**
+	 * How old a staging directory must be before it counts as abandoned.
+	 * Defaults to `STALE_STAGING_MS`. Tests set it; nothing else should need to.
+	 */
+	staleStagingMs?: number;
+}
+
+/**
+ * How long a staging directory may sit before a sweep treats it as dead.
+ *
+ * The window is far shorter than it looks. `installPinnedTool` downloads every
+ * asset and verifies every checksum *before* it creates the staging directory,
+ * so that directory's whole life is a handful of local file writes and two
+ * renames: sub-second normally, seconds on a struggling disk. An hour is twelve
+ * times the installer's own per-asset download timeout and orders of magnitude
+ * past the writes, which leaves no plausible live install inside it.
+ *
+ * The pid in the name is deliberately not consulted. Pids are reused, a pid
+ * belonging to another user answers a liveness probe with EPERM rather than an
+ * honest yes or no, and a data root shared over a network filesystem makes the
+ * number meaningless. Age is the one signal that means the same thing
+ * everywhere.
+ */
+export const STALE_STAGING_MS = 3_600_000;
+
+/** What one sweep of a tool's directory deleted, and what it could not. */
+export interface ToolRemoveResult {
+	ok: boolean;
+	id: string;
+	/** `<root>/<id>`, whether or not it exists. */
+	dir: string;
+	/** Version directories this sweep deleted, oldest name first. */
+	removed: string[];
+	/** Version directories that survived a delete attempt, with the reason. */
+	failed: ReadonlyArray<{ version: string; error: string }>;
+	/** Abandoned staging directories this sweep collected, by name. */
+	staleStaging: string[];
+	message: string;
+}
+
+/** Version directories currently installed for a tool, sorted. */
+export function installedToolVersions(id: string, options: ToolRemoveOptions = {}): string[] {
+	const dir = join(options.root ?? toolchainRoot(), id);
+	let names: string[];
+	try {
+		names = readdirSync(dir);
+	} catch {
+		// A tool nobody ever installed has no directory, which is not an error:
+		// the answer to "which versions are installed" is none.
+		return [];
+	}
+	return names
+		.filter((name) => !name.startsWith(".") && isDirectory(join(dir, name)))
+		.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Delete every vendored version of a tool, then the tool's own directory.
+ *
+ * A tool with nothing installed is a no-op that reports success: the operator
+ * asked for a state ("this tool is not vendored") that already holds, and
+ * failing them for it would make the verb unusable in a script.
+ */
+export function removeTool(id: string, options: ToolRemoveOptions = {}): ToolRemoveResult {
+	if (findPinnedTool(id) === null) {
+		const dir = join(options.root ?? toolchainRoot(), id);
+		return { ok: false, id, dir, removed: [], failed: [], staleStaging: [], message: `unknown tool: ${id}` };
+	}
+	return removeVersions(id, null, options);
+}
+
+/**
+ * Delete every vendored version of a tool except `keep`.
+ *
+ * Called by the installer once a version is in place, so a pin bump leaves one
+ * version directory behind rather than one per version the machine ever ran.
+ * The kept version is not required to exist: pruning to a version that is not
+ * installed empties the tool, which is what `--force` recovery wants.
+ */
+export function pruneSupersededVersions(id: string, keep: string, options: ToolRemoveOptions = {}): ToolRemoveResult {
+	return removeVersions(id, keep, options);
+}
+
+function removeVersions(id: string, keep: string | null, options: ToolRemoveOptions): ToolRemoveResult {
+	const root = options.root ?? toolchainRoot();
+	const dir = join(root, id);
+	const versions = installedToolVersions(id, { root }).filter((version) => version !== keep);
+	const removed: string[] = [];
+	const failed: { version: string; error: string }[] = [];
+	for (const version of versions) {
+		try {
+			rmSync(join(dir, version), { recursive: true, force: true });
+			removed.push(version);
+		} catch (error) {
+			failed.push({ version, error: error instanceof Error ? error.message : String(error) });
+		}
+	}
+	// Before the rmdir below, so an install killed weeks ago cannot keep the tool
+	// directory alive after every version of it is gone.
+	const staleStaging = sweepStaleStaging(dir, options.staleStagingMs ?? STALE_STAGING_MS);
+	if (keep === null && failed.length === 0) {
+		// The tool is gone, so its directory is litter. `rmdir` takes it only when
+		// it is empty, so a staging directory young enough to belong to a running
+		// installer makes this fail instead of destroying that install.
+		try {
+			rmdirSync(dir);
+		} catch {
+			// Either it was never there or something still lives in it. Neither
+			// changes what this call promised: no version of the tool remains.
+		}
+	}
+	return {
+		ok: failed.length === 0,
+		id,
+		dir,
+		removed,
+		failed,
+		staleStaging,
+		message: describeRemoval(id, dir, keep, removed, failed, staleStaging),
+	};
+}
+
+/**
+ * Delete the abandoned staging directories under one tool.
+ *
+ * Only names the installer produces are considered, so an operator who parked
+ * something of their own under `<data>/tools/<id>` with a leading dot keeps it.
+ * A directory whose age cannot be read is left alone: an unreadable stat is not
+ * evidence of death.
+ */
+function sweepStaleStaging(dir: string, staleMs: number): string[] {
+	let names: string[];
+	try {
+		names = readdirSync(dir);
+	} catch {
+		return [];
+	}
+	const cutoff = Date.now() - staleMs;
+	const swept: string[] = [];
+	for (const name of names.sort((a, b) => a.localeCompare(b))) {
+		if (!STAGING_NAME.test(name)) continue;
+		const stat = statSync(join(dir, name), { throwIfNoEntry: false });
+		if (stat === undefined || !stat.isDirectory() || stat.mtimeMs > cutoff) continue;
+		try {
+			rmSync(join(dir, name), { recursive: true, force: true });
+			swept.push(name);
+		} catch {
+			// A staging directory that resists deletion is litter, not a failure:
+			// nothing resolves it, and reporting it would turn a successful install
+			// into a failed one over a directory the ladder never looks at.
+		}
+	}
+	return swept;
+}
+
+/** `.<version>.incomplete-<pid>-<t>` and `.<version>.replaced-<pid>-<t>`. */
+const STAGING_NAME = /^\.[^/]+\.(?:incomplete|replaced)-\d+-[a-z0-9]+$/;
+
+function describeRemoval(
+	id: string,
+	dir: string,
+	keep: string | null,
+	removed: ReadonlyArray<string>,
+	failed: ReadonlyArray<{ version: string; error: string }>,
+	staleStaging: ReadonlyArray<string>,
+): string {
+	// Reported as a suffix rather than as the headline: an abandoned staging
+	// directory is housekeeping, and the operator asked about versions.
+	const swept =
+		staleStaging.length === 0
+			? ""
+			: `; swept ${staleStaging.length} abandoned install ${staleStaging.length === 1 ? "directory" : "directories"}`;
+	const trouble = failed.map((entry) => `${entry.version} (${entry.error})`).join(", ");
+	if (failed.length > 0) {
+		const done = removed.length > 0 ? `removed ${removed.join(", ")}; ` : "";
+		return `${done}could not remove ${id} ${trouble} under ${dir}${swept}`;
+	}
+	if (removed.length === 0) {
+		return keep === null
+			? `${id} is not installed under ${dir}; nothing to remove${swept}`
+			: `${id} has no superseded versions under ${dir}${swept}`;
+	}
+	const what = `${id} ${removed.join(", ")}`;
+	const headline = keep === null ? `removed ${what} from ${dir}` : `pruned ${what} from ${dir}, keeping ${keep}`;
+	return `${headline}${swept}`;
+}
+
+function isDirectory(path: string): boolean {
+	return statSync(path, { throwIfNoEntry: false })?.isDirectory() === true;
+}

package/src/domains/toolchain/resolve.ts

@@ -0,0 +1,182 @@
+import { statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { toolVersionDir, vendoredBinaryPath } from "./paths.js";
+import { currentToolPlatform, findPinnedTool, findPinnedToolByBinary, PINNED_TOOLS } from "./registry.js";
+import type { PinnedTool, ToolPathCandidate, ToolResolution, ToolStatus } from "./types.js";
+import { probeBinaryVersion, satisfiesMinimum } from "./version.js";
+
+/**
+ * The shared resolution ladder: PATH, then the vendored pin, then nothing.
+ *
+ * PATH comes first because a tool the operator installed themselves is the one
+ * they maintain, and Clio downloading a second copy of a program already on the
+ * machine is a surprise. It only wins when its version clears the registry's
+ * floor, because the alternative is Clio driving a surface that release does not
+ * have and reporting the resulting failure as a bug in the feature.
+ *
+ * Nothing here downloads, spawns a server, or writes to disk. It is safe on the
+ * interactive startup path and inside doctor, both of which promise to create
+ * nothing.
+ */
+
+/** First executable named `name` on PATH, or null. */
+export function findExecutableOnPath(name: string): string | null {
+	const pathEnv = process.env.PATH;
+	if (!pathEnv) return null;
+	const candidates = process.platform === "win32" ? [`${name}.exe`, name] : [name];
+	for (const dir of pathEnv.split(delimiter)) {
+		if (!dir) continue;
+		for (const candidate of candidates) {
+			const full = join(dir, candidate);
+			const stat = statSync(full, { throwIfNoEntry: false });
+			if (stat?.isFile() && (process.platform === "win32" || (stat.mode & 0o111) !== 0)) return full;
+		}
+	}
+	return null;
+}
+
+/**
+ * Resolve one executable name through the ladder.
+ *
+ * A name that is not in the registry gets a plain PATH lookup: there is no pin
+ * to compare against and nothing vendored to fall back to, so the answer is
+ * whatever PATH says.
+ */
+export function resolveToolBinary(name: string): ToolResolution {
+	const entry = findPinnedToolByBinary(name) ?? findPinnedTool(name);
+	if (entry === null) {
+		const found = findExecutableOnPath(name);
+		return {
+			source: found === null ? "none" : "path",
+			binaryPath: found,
+			version: null,
+			entry: null,
+			pathCandidate: found === null ? null : { path: found, version: null, satisfiesMinimum: true },
+			vendoredPath: null,
+		};
+	}
+	// An entry asked for by tool id resolves its primary binary; asked for by
+	// binary name it resolves that binary, so `ya` does not silently become `yazi`.
+	const binary = entry.binaries.includes(name) ? name : entry.primaryBinary;
+	return resolveEntryBinary(entry, binary);
+}
+
+/** The ladder for a known registry row and one of its binaries. */
+export function resolveEntryBinary(entry: PinnedTool, binary: string): ToolResolution {
+	const pathCandidate = probePathCandidate(entry, binary);
+	const vendored = vendoredBinaryPath(entry.id, entry.version, binary);
+	const vendoredStat = statSync(vendored, { throwIfNoEntry: false });
+	const vendoredPath = vendoredStat?.isFile() ? vendored : null;
+
+	if (pathCandidate?.satisfiesMinimum) {
+		return {
+			source: "path",
+			binaryPath: pathCandidate.path,
+			version: pathCandidate.version,
+			entry,
+			pathCandidate,
+			vendoredPath,
+		};
+	}
+	if (vendoredPath !== null) {
+		return {
+			source: "vendored",
+			binaryPath: vendoredPath,
+			version: entry.version,
+			entry,
+			pathCandidate,
+			vendoredPath,
+		};
+	}
+	return { source: "none", binaryPath: null, version: null, entry, pathCandidate, vendoredPath: null };
+}
+
+/** Per-entry state for the CLI and doctor. */
+export function toolStatus(entry: PinnedTool): ToolStatus {
+	const platform = currentToolPlatform();
+	const supported = platform !== null && entry.downloads[platform] !== undefined;
+	const resolution = resolveEntryBinary(entry, entry.primaryBinary);
+	return {
+		id: entry.id,
+		version: entry.version,
+		license: entry.license,
+		platform,
+		supported,
+		installed: resolution.vendoredPath !== null,
+		installDir: toolVersionDir(entry.id, entry.version),
+		resolution,
+	};
+}
+
+/** Per-entry state for every row, in registry order. */
+export function toolStatuses(): ToolStatus[] {
+	return PINNED_TOOLS.map((entry) => toolStatus(entry));
+}
+
+/** The one command that fixes a tool Clio cannot resolve. */
+export function installRemedy(id: string): string {
+	return `clio-coder tools install ${id}`;
+}
+
+/**
+ * What a rejected PATH copy was, and which floor it failed. Null when there is
+ * no PATH copy or when the one there was accepted.
+ *
+ * The floors are deliberately conservative: they sit at the pin for herdr and
+ * yazi because Clio drives socket and plugin surfaces verified against only
+ * that release. That is a defensible choice and a costly one, since it rejects
+ * binaries an operator installed themselves and that mostly work. The cost is
+ * only payable if the rejection is legible, so every renderer of a rejection
+ * names the path, the version found, and the floor it missed, and never reports
+ * a rejected copy as an absent one.
+ */
+export function describeFloorRejection(status: ToolStatus): string | null {
+	const candidate = status.resolution.pathCandidate;
+	if (candidate === null || candidate.satisfiesMinimum) return null;
+	const floor = status.resolution.entry?.minimumVersion ?? status.version;
+	const found = candidate.version === null ? "an unreadable version" : candidate.version;
+	return `PATH copy ${candidate.path} is ${found}, below the ${floor} floor`;
+}
+
+/**
+ * One sentence describing where a tool resolved and how its version compares to
+ * the pin. Shared by `clio-coder tools status` and the doctor rows so the two
+ * cannot drift into describing the same machine differently.
+ */
+export function describeResolution(status: ToolStatus): string {
+	const { resolution } = status;
+	const rejection = describeFloorRejection(status);
+	if (resolution.source === "path") {
+		const version = resolution.version ?? "unreadable version";
+		return `PATH ${resolution.binaryPath} (${version}, pin ${status.version})`;
+	}
+	if (resolution.source === "vendored") {
+		// The remedy is deliberately absent here. The rejection cost the operator
+		// nothing: Clio has a copy at the pin and is running it, and printing an
+		// install command that would change nothing is its own kind of dishonesty.
+		const rejected = rejection === null ? "" : `; ${rejection}, so Clio runs the vendored copy`;
+		return `vendored ${resolution.binaryPath} (${status.version})${rejected}`;
+	}
+	if (!status.supported) {
+		const platform = status.platform ?? `${process.platform}-${process.arch}`;
+		// No remedy either: there is no asset to install on this machine, so the
+		// rejection is the whole story and naming a command would be a dead end.
+		const rejected = rejection === null ? "" : `; ${rejection}`;
+		return `not installed and no pinned asset for this platform (${platform})${rejected}`;
+	}
+	if (rejection !== null) {
+		return `${rejection}, and nothing is vendored (install with \`${installRemedy(status.id)}\`)`;
+	}
+	return `not found (install with \`${installRemedy(status.id)}\`)`;
+}
+
+function probePathCandidate(entry: PinnedTool, binary: string): ToolPathCandidate | null {
+	const found = findExecutableOnPath(binary);
+	if (found === null) return null;
+	// The floor is a property of the tool, and only the primary binary is asked
+	// for its version, so a secondary binary inherits the primary's verdict from
+	// the same install root rather than being probed with flags it may not have.
+	const probeTarget = binary === entry.primaryBinary ? found : (findExecutableOnPath(entry.primaryBinary) ?? found);
+	const version = probeBinaryVersion(probeTarget, entry.versionArgs);
+	return { path: found, version, satisfiesMinimum: satisfiesMinimum(version, entry.minimumVersion) };
+}