@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/cli/docs-server.ts

@@ -0,0 +1,290 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { pathToFileURL } from "node:url";
+import { BIRTH_TOKEN_SOURCE_AVAILABLE, processAlive, processBirthToken } from "../core/process-identity.js";
+import { withStateFileLock } from "../core/state-file-lock.js";
+import { resolveClioDirs } from "../core/xdg.js";
+
+/** A page that stays open holds the server through its event stream; this only bounds the gap after the last one closes. */
+export const DOCS_IDLE_EXIT_MS = 15 * 60_000;
+const START_TIMEOUT_MS = 20_000;
+const STOP_TIMEOUT_MS = 10_000;
+const LAUNCH_LINK = /\[clio-coder:gui\] http:\/\/127\.0\.0\.1:(\d+)\/\S*#token=([\w-]{32,256})/u;
+
+/** What a later `clio-coder docs` needs to find, verify and stop the server this one started. */
+interface DocsServerRecord {
+	v: 1;
+	pid: number;
+	birth: string;
+	port: number;
+	token: string;
+	packageRoot: string;
+}
+
+export interface DocsServer {
+	origin: string;
+	token: string;
+	pid: number;
+	reused: boolean;
+}
+
+const registryPath = () => join(resolveClioDirs().state, "gui", "docs-server.json");
+
+/** The installed background app owns docs when it exists; the docs server never competes with it. */
+export function backgroundAppInstalled(): boolean {
+	const directory = join(resolveClioDirs().state, "gui", "background");
+	return ["server.json", "owner.json"].some((name) => existsSync(join(directory, name)));
+}
+
+function readRecord(): DocsServerRecord | undefined {
+	try {
+		const value = JSON.parse(readFileSync(registryPath(), "utf8")) as Partial<DocsServerRecord>;
+		if (
+			value.v === 1 &&
+			Number.isSafeInteger(value.pid) &&
+			(value.pid ?? 0) > 0 &&
+			typeof value.birth === "string" &&
+			Number.isInteger(value.port) &&
+			(value.port ?? 0) >= 1 &&
+			(value.port ?? 0) <= 65535 &&
+			typeof value.token === "string" &&
+			/^[\w-]{32,256}$/u.test(value.token) &&
+			typeof value.packageRoot === "string"
+		)
+			return value as DocsServerRecord;
+	} catch {
+		// Absent or damaged records mean there is nothing to reuse.
+	}
+	return undefined;
+}
+
+function writeRecord(record: DocsServerRecord): void {
+	const path = registryPath();
+	mkdirSync(dirname(path), { recursive: true });
+	const staging = `${path}.${process.pid}.tmp`;
+	writeFileSync(staging, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+	renameSync(staging, path);
+}
+
+const removeRecord = () => rmSync(registryPath(), { force: true });
+
+/**
+ * Whether the recorded pid is still the server this command started. Where the OS exposes process
+ * start times (Linux), the birth token proves it even for a server that no longer answers. Elsewhere
+ * the token is only `pid-<n>`, which a reused pid satisfies, so ownership needs the server itself to
+ * answer with the launch token that only it holds. A server that is alive but silent cannot be
+ * proven ours there, and is never signalled.
+ */
+async function owned(record: DocsServerRecord, birthVerified: boolean): Promise<boolean> {
+	if (!processAlive(record.pid)) return false;
+	if (birthVerified) return processBirthToken(record.pid) === record.birth;
+	return authenticated(record.port, record.token);
+}
+
+async function waitForExit(pid: number, ms: number): Promise<boolean> {
+	const deadline = Date.now() + ms;
+	while (processAlive(pid)) {
+		if (Date.now() > deadline) return false;
+		await sleep(50);
+	}
+	return true;
+}
+
+/** A signal that races the process exiting is not a failure: the target is gone either way. */
+function signal(pid: number, name: NodeJS.Signals): void {
+	try {
+		process.kill(pid, name);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+	}
+}
+
+type Termination = "exited" | "survived" | "not-owned";
+
+/** What happened to the process, observed rather than assumed. Anything not proven to be this server is left running. */
+async function terminate(record: DocsServerRecord, birthVerified: boolean): Promise<Termination> {
+	if (!(await owned(record, birthVerified))) return "not-owned";
+	signal(record.pid, "SIGTERM");
+	if (await waitForExit(record.pid, STOP_TIMEOUT_MS)) return "exited";
+	// Without verified birth tokens a silent survivor might no longer be ours, so only escalate on proof.
+	if (!(await owned(record, birthVerified))) return processAlive(record.pid) ? "not-owned" : "exited";
+	signal(record.pid, "SIGKILL");
+	return (await waitForExit(record.pid, 2000)) ? "exited" : "survived";
+}
+
+export interface DocsServerOptions {
+	/** How long the server may sit with no page open before it exits. */
+	idleMs?: number;
+	/** How long to wait for the server to report its address and answer. */
+	startTimeoutMs?: number;
+	/** Whether pid reuse is detectable on this platform. Defaults to what the OS provides; tests set it. */
+	birthVerified?: boolean;
+}
+
+const logPath = () => join(dirname(registryPath()), "docs-server.log");
+
+/** The token is authenticated, so a server that answers it is this one and not another program on the port. */
+async function authenticated(port: number, token: string): Promise<boolean> {
+	try {
+		const response = await fetch(`http://127.0.0.1:${port}/api/meta`, {
+			headers: { Authorization: `Bearer ${token}` },
+			redirect: "error",
+			signal: AbortSignal.timeout(1500),
+		});
+		return response.status === 200 && ((await response.json()) as { apiVersion?: number }).apiVersion === 1;
+	} catch {
+		return false;
+	}
+}
+
+/** Signal the whole group: the server is its own session leader and may have started children of its own. */
+function killGroup(child: ChildProcess, signal: NodeJS.Signals): void {
+	try {
+		if (child.pid && process.platform !== "win32") process.kill(-child.pid, signal);
+		else child.kill(signal);
+	} catch {
+		// Already gone.
+	}
+}
+
+async function start(packageRoot: string, options: DocsServerOptions): Promise<DocsServer> {
+	const entry = join(packageRoot, "dist/gui/server.js");
+	if (!existsSync(entry))
+		throw new Error("The graphical application has not been built here. Run `pnpm run build` in this checkout.");
+	const idleMs = options.idleMs ?? DOCS_IDLE_EXIT_MS;
+	const timeoutMs = options.startTimeoutMs ?? START_TIMEOUT_MS;
+	const log = logPath();
+	mkdirSync(dirname(log), { recursive: true });
+	// A file, not a pipe: the server outlives this command, and a closed pipe would break its later logging.
+	const fd = openSync(log, "w", 0o600);
+	let child: ChildProcess;
+	try {
+		child = spawn(process.execPath, [entry, "--idle-exit", String(idleMs), "--no-open"], {
+			cwd: packageRoot,
+			detached: true,
+			env: { ...process.env, CLIO_CODER_PACKAGE_ROOT: packageRoot },
+			stdio: ["ignore", fd, fd],
+		});
+	} finally {
+		closeSync(fd);
+	}
+	let exited = false;
+	let spawnError: Error | undefined;
+	child.once("exit", () => {
+		exited = true;
+	});
+	child.once("error", (error) => {
+		exited = true;
+		spawnError = error;
+	});
+	const output = () => {
+		try {
+			return readFileSync(log, "utf8");
+		} catch {
+			return "";
+		}
+	};
+	try {
+		const deadline = Date.now() + timeoutMs;
+		let link: RegExpExecArray | null = null;
+		while (!link && !exited && Date.now() < deadline) {
+			await sleep(40);
+			link = LAUNCH_LINK.exec(output());
+		}
+		const [, port, token] = link ?? [];
+		if (!port || !token || !child.pid) {
+			const reason =
+				spawnError?.message ??
+				output()
+					.trim()
+					.split("\n")
+					.pop()
+					?.replace(/^\[clio-coder:gui\]\s*/u, "");
+			throw new Error(`The documentation server did not start${reason ? `: ${reason}` : "."}`);
+		}
+		let ready = false;
+		while (!ready && !exited && Date.now() < deadline) {
+			ready = await authenticated(Number(port), token);
+			if (!ready) await sleep(100);
+		}
+		if (!ready) throw new Error("The documentation server started but did not answer its launch token.");
+		const birth = processBirthToken(child.pid);
+		if (!birth) throw new Error("The documentation server exited while starting.");
+		writeRecord({ v: 1, pid: child.pid, birth, port: Number(port), token, packageRoot });
+		child.unref();
+		return { origin: `http://127.0.0.1:${port}`, token, pid: child.pid, reused: false };
+	} catch (error) {
+		// No record was published for a server that is not fully up, so nothing else can find it to stop it.
+		if (!exited) killGroup(child, "SIGKILL");
+		removeRecord();
+		throw error;
+	}
+}
+
+/** Reuse the running docs server for this installation, or replace whatever the registry left behind. */
+export function ensureDocsServer(packageRoot: string, options: DocsServerOptions = {}): Promise<DocsServer> {
+	return withStateFileLock(
+		registryPath(),
+		async () => {
+			const record = readRecord();
+			if (record) {
+				const birthVerified = options.birthVerified ?? BIRTH_TOKEN_SOURCE_AVAILABLE;
+				if (
+					record.packageRoot === packageRoot &&
+					(await owned(record, birthVerified)) &&
+					(await authenticated(record.port, record.token))
+				)
+					return { origin: `http://127.0.0.1:${record.port}`, token: record.token, pid: record.pid, reused: true };
+				if ((await terminate(record, birthVerified)) === "survived")
+					throw new Error(
+						`The previous documentation server (pid ${record.pid}) did not stop. Run clio-coder docs --stop again.`,
+					);
+				removeRecord();
+			}
+			return start(packageRoot, options);
+		},
+		{ timeoutMs: (options.startTimeoutMs ?? START_TIMEOUT_MS) + STOP_TIMEOUT_MS + 5000 },
+	);
+}
+
+export interface StopResult {
+	stopped: boolean;
+	pid?: number;
+	/** A process holds the recorded pid but could not be shown to be the documentation server, so it was left alone. */
+	unverified?: boolean;
+	/** The server was signalled, including SIGKILL, and is still running. Its record is kept so `--stop` can be retried. */
+	survived?: boolean;
+}
+
+/** Stop the docs server this command started, if one is still running. */
+export function stopDocsServer(options: Pick<DocsServerOptions, "birthVerified"> = {}): Promise<StopResult> {
+	return withStateFileLock(registryPath(), async () => {
+		const record = readRecord();
+		if (!record) return { stopped: false };
+		const outcome = await terminate(record, options.birthVerified ?? BIRTH_TOKEN_SOURCE_AVAILABLE);
+		if (outcome === "survived") return { stopped: false, pid: record.pid, survived: true };
+		removeRecord();
+		if (outcome === "exited") return { stopped: true, pid: record.pid };
+		return processAlive(record.pid) ? { stopped: false, pid: record.pid, unverified: true } : { stopped: false };
+	});
+}
+
+/**
+ * Opens a page through the application's own opener, which accepts only its loopback URL and
+ * refuses platforms it cannot open safely. A build without the export has no opener, and the
+ * printed link is the fallback.
+ */
+export async function openInBrowser(url: string, packageRoot: string): Promise<boolean> {
+	const entry = join(packageRoot, "dist/gui/server.js");
+	if (!existsSync(entry)) return false;
+	try {
+		const server = (await import(pathToFileURL(entry).href)) as { openBrowser?: (url: string) => Promise<void> };
+		if (!server.openBrowser) return false;
+		await server.openBrowser(url);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/cli/docs.ts

@@ -2,25 +2,37 @@ import { readdirSync } from "node:fs";
 import { basename, join } from "node:path";
 import { resolvePackageRoot } from "../core/package-root.js";
 import { printError } from "./argv.js";
-import { runWebCommand } from "./web.js";
+import {
+	backgroundAppInstalled,
+	DOCS_IDLE_EXIT_MS,
+	ensureDocsServer,
+	openInBrowser,
+	stopDocsServer,
+} from "./docs-server.js";
+import { runGuiCommand } from "./gui.js";
 
-const HELP = `clio-coder docs [topic] [--no-open]
+const HELP = `clio-coder docs [topic] [--no-open] [--foreground]
+clio-coder docs --stop
 
-Open the documentation in the Clio Coder web app. Pages, navigation and outlines
-are rendered from the same Markdown reference shipped with Clio.
+Open the documentation in your browser. Pages, navigation and outlines are
+rendered from the same Markdown reference shipped with Clio.
 
 Arguments:
-  [topic]      a topic such as safety, configuration, or fleet_dispatch, or a
-               document path such as architecture/safety-model.md.
-               Omit to open the documentation map.
+  [topic]        a topic such as safety, configuration, or fleet_dispatch, or a
+                 document path such as architecture/safety-model.md.
+                 Omit to open the documentation map.
 
 Flags:
-  --no-open    print the private launch link without opening a browser.
-  --help, -h   this message.
+  --no-open      print the private launch link without opening a browser.
+  --foreground   serve privately in this terminal until Ctrl+C. It neither starts nor
+                 reuses the background app or the shared documentation server.
+  --stop         stop the documentation server this command started.
+  --help, -h     this message.
 
-Reuses your installed background app when available. Otherwise starts a local
-foreground web server on 127.0.0.1; press Ctrl+C to stop it. No background service
-is installed by this command. Your current directory does not affect the docs.
+Your installed background app is used when you have one. Otherwise a local server
+starts on 127.0.0.1 in the background, so this terminal stays free, and later
+calls reuse it. It stops by itself 15 minutes after the last page closes, or with
+--stop. No login service is installed. Your current directory does not affect the docs.
 `;
 
 const key = (value: string) => value.toLowerCase().replace(/_/g, "-");
@@ -68,14 +80,35 @@ export async function runDocsCommand(args: readonly string[] = []): Promise<numb
 		process.stdout.write(HELP);
 		return 0;
 	}
-	const positionals = args.filter((arg) => arg !== "--no-open");
+	const flags = new Set(["--no-open", "--foreground", "--stop"]);
+	const positionals = args.filter((arg) => !flags.has(arg));
 	const unknownFlag = positionals.find((arg) => arg.startsWith("-"));
 	if (unknownFlag || positionals.length > 1) {
 		printError(unknownFlag ? `unknown flag: ${unknownFlag}` : "docs accepts at most one [topic]");
 		return 2;
 	}
+	const stop = args.includes("--stop");
+	if (stop && args.length > 1) {
+		printError("--stop takes no topic or other flags");
+		return 2;
+	}
+	const noOpen = args.includes("--no-open");
 	try {
-		const pages = catalog(join(resolvePackageRoot(), "docs"));
+		if (stop) {
+			const result = await stopDocsServer();
+			process.stdout.write(
+				result.stopped
+					? `Stopped the documentation server (pid ${result.pid}).\n`
+					: result.survived
+						? `The documentation server (pid ${result.pid}) is still running after SIGTERM and SIGKILL. Its record is kept; run clio-coder docs --stop again.\n`
+						: result.unverified
+							? `Process ${result.pid} did not answer as the documentation server and this platform cannot prove it is one, so it was not signalled. Its record was cleared; a stale documentation server exits by itself when idle.\n`
+							: "No documentation server is running.\n",
+			);
+			return result.survived ? 1 : 0;
+		}
+		const root = resolvePackageRoot();
+		const pages = catalog(join(root, "docs"));
 		const path = docsTopicRoute(positionals[0], pages);
 		if (!path) {
 			printError(
@@ -83,7 +116,19 @@ export async function runDocsCommand(args: readonly string[] = []): Promise<numb
 			);
 			return 2;
 		}
-		return runWebCommand(["--path", path, "--reuse-background", args.includes("--no-open") ? "--no-open" : "--open"]);
+		// A foreground request is a private server for this terminal; it never adopts the background app.
+		if (args.includes("--foreground")) return runGuiCommand(["--path", path, noOpen ? "--no-open" : "--open"]);
+		if (backgroundAppInstalled())
+			return runGuiCommand(["--path", path, "--reuse-background", noOpen ? "--no-open" : "--open"]);
+		const server = await ensureDocsServer(root);
+		const link = `${server.origin}${path}#token=${server.token}`;
+		process.stdout.write(`${link}\n`);
+		const opened = noOpen ? false : await openInBrowser(link, root);
+		if (!noOpen && !opened) process.stderr.write("Could not open a browser here. Open the link above in your browser.\n");
+		process.stderr.write(
+			`Documentation server ${server.reused ? "already running" : "started"} (pid ${server.pid}). It stops ${DOCS_IDLE_EXIT_MS / 60_000} minutes after the last page closes, or run: clio-coder docs --stop\n`,
+		);
+		return 0;
 	} catch (error) {
 		printError(error instanceof Error ? error.message : "Could not open the documentation.");
 		return 1;

package/src/cli/doctor-deep.ts

@@ -0,0 +1,126 @@
+import { accessSync, constants, statSync } from "node:fs";
+import path from "node:path";
+import { ToolNames } from "../core/tool-names.js";
+import { resolveOnPath } from "../domains/interop/detect.js";
+import type { DoctorFinding } from "../domains/lifecycle/doctor.js";
+import type { ProvidersContract, TargetStatus } from "../domains/providers/contract.js";
+import { type AutonomyLevel, mapAutonomy } from "../domains/safety/autonomy.js";
+import { createSafetyPolicyEngine } from "../domains/safety/policy-engine.js";
+import { loadValidationContract } from "../domains/safety/validation-contract.js";
+
+export interface DeepToolProbeOptions {
+	/** Tool-probe generation timeout in ms; the provider default applies when absent. */
+	toolsTimeoutMs?: number;
+}
+
+function toolProbeFinding(status: TargetStatus): DoctorFinding {
+	const name = `tools ${status.target.id}`;
+	const probe = status.toolProbe;
+	if (!probe) {
+		// The tool probe runs only once the target answered its health probe.
+		const reason = status.reason || status.health.lastError || "the target did not answer";
+		return { ok: true, name, level: "warn", detail: `not probed: ${reason}` };
+	}
+	const model = probe.modelId ?? "no model";
+	if (probe.status === "verified") {
+		return { ok: true, name, level: "ok", detail: `${model} streamed a valid tool call in ${probe.latencyMs}ms` };
+	}
+	if (probe.status === "skipped") {
+		return { ok: true, name, level: "info", detail: `skipped (${model}): ${probe.error ?? "no reason given"}` };
+	}
+	return { ok: true, name, level: "warn", detail: `failed (${model}): ${probe.error ?? "unknown error"}` };
+}
+
+/**
+ * The live tool-call probe on every configured target, one row each. The
+ * probe loads a cold local model when it has to and releases only the model it
+ * loaded, so it is safe in a process that is also running chat turns.
+ */
+export async function deepToolProbeFindings(
+	providers: ProvidersContract,
+	options: DeepToolProbeOptions = {},
+): Promise<DoctorFinding[]> {
+	await providers.probeAllLive({
+		tools: true,
+		...(options.toolsTimeoutMs !== undefined ? { toolsTimeoutMs: options.toolsTimeoutMs } : {}),
+	});
+	return providers.list().map(toolProbeFinding);
+}
+
+/** The program a validator command runs: its first word after any `NAME=value` assignments. */
+function commandProgram(command: string): string | null {
+	for (const word of command.trim().split(/\s+/)) {
+		if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) continue;
+		return word.length > 0 ? word : null;
+	}
+	return null;
+}
+
+function resolveProgram(program: string, workspaceRoot: string): string | null {
+	if (!program.includes("/")) {
+		const found = resolveOnPath([program]);
+		return found.presence === "present" ? (found.binary ?? null) : null;
+	}
+	const candidate = path.resolve(workspaceRoot, program);
+	try {
+		accessSync(candidate, constants.X_OK);
+		return statSync(candidate).isFile() ? candidate : null;
+	} catch {
+		return null;
+	}
+}
+
+export interface ContractDryRunOptions {
+	workspaceRoot?: string;
+	autonomy: AutonomyLevel;
+}
+
+/**
+ * Dry run of the workspace validation contract. Each declared validator
+ * command is resolved on PATH and handed to the same two stages tool
+ * admission applies to a bash call: the policy engine's verdict, then the
+ * autonomy mapping at the configured level. Nothing is executed. A row warns
+ * when the program is missing or when the command would stop for approval or
+ * be refused, because either one stalls an unattended validation.
+ */
+export function contractDryRunFindings(options: ContractDryRunOptions): DoctorFinding[] {
+	const workspaceRoot = options.workspaceRoot ?? process.cwd();
+	const loaded = loadValidationContract(workspaceRoot);
+	if (!loaded.ok || loaded.contract === null) return [];
+	const validators = loaded.contract.validators ?? [];
+	if (validators.length === 0) return [];
+	const engine = createSafetyPolicyEngine({ cwd: workspaceRoot });
+	const level = options.autonomy;
+	return validators.map((command, index): DoctorFinding => {
+		const name = `validator ${index + 1}`;
+		const program = commandProgram(command);
+		const resolved = program === null ? null : resolveProgram(program, workspaceRoot);
+		const where =
+			program === null ? "no program" : resolved === null ? `${program} not found` : `${program} is ${resolved}`;
+		const decision = engine.evaluate({ tool: ToolNames.Bash, args: { command } });
+		let verdict: string;
+		let runs = false;
+		if (decision.kind === "block") {
+			verdict = `blocked by the safety policy (${decision.reasonCode})`;
+		} else if (decision.kind === "ask") {
+			verdict = `asks for approval at every autonomy level (${decision.reasonCode})`;
+		} else {
+			const disposition = mapAutonomy(level, decision.actionClass, {
+				executeRecognized: decision.execRecognition !== "unrecognized",
+			});
+			runs = disposition === "allow";
+			verdict =
+				disposition === "allow"
+					? `runs without approval at ${level}`
+					: disposition === "ask"
+						? `asks for approval at ${level}; declare it in .clio-coder/safety.yaml to run it unattended`
+						: `denied at ${level}`;
+		}
+		return {
+			ok: true,
+			name,
+			level: runs && resolved !== null ? "ok" : "warn",
+			detail: `\`${command}\`: ${where}; ${verdict}`,
+		};
+	});
+}

package/src/cli/doctor-hpc.ts

@@ -0,0 +1,122 @@
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { runCommandVector } from "../core/safe-exec.js";
+import { resolveOnPath } from "../domains/interop/detect.js";
+import type { DoctorFinding } from "../domains/lifecycle/doctor.js";
+import { loadValidationContract, type ValidationContract } from "../domains/safety/validation-contract.js";
+
+/** Each `--version` spawn gets this long before it is killed and reported as silent. */
+export const HPC_VERSION_TIMEOUT_MS = 2_000;
+const HPC_VERSION_MAX_OUTPUT_BYTES = 4096;
+
+export interface HpcToolSpec {
+	/** Row name and the name a validation contract uses for the tool. */
+	name: string;
+	/** Binaries tried in order on PATH; the first found answers for the row. */
+	binaries: ReadonlyArray<string>;
+}
+
+/** The compilers, MPI launchers, build systems, and schedulers doctor looks for. */
+export const HPC_TOOLS: ReadonlyArray<HpcToolSpec> = [
+	{ name: "cc", binaries: ["cc", "gcc"] },
+	{ name: "c++", binaries: ["c++", "g++"] },
+	{ name: "clang", binaries: ["clang"] },
+	{ name: "gfortran", binaries: ["gfortran"] },
+	{ name: "mpicc", binaries: ["mpicc"] },
+	{ name: "mpicxx", binaries: ["mpicxx"] },
+	{ name: "mpirun", binaries: ["mpirun"] },
+	{ name: "nvcc", binaries: ["nvcc"] },
+	{ name: "cmake", binaries: ["cmake"] },
+	{ name: "make", binaries: ["make"] },
+	{ name: "ninja", binaries: ["ninja"] },
+	{ name: "meson", binaries: ["meson"] },
+	{ name: "python3", binaries: ["python3"] },
+	{ name: "sbatch", binaries: ["sbatch"] },
+];
+
+export interface HpcToolchainOptions {
+	workspaceRoot?: string;
+	timeoutMs?: number;
+}
+
+/**
+ * Why the workspace needs a tool, or null when nothing asks for it. The
+ * contract names a tool when one of its validator commands has a word whose
+ * basename is one of the tool's binaries; `runtime.kind: slurm` needs sbatch.
+ */
+function requiredBy(contract: ValidationContract | null, tool: HpcToolSpec): string | null {
+	if (contract === null) return null;
+	if (tool.name === "sbatch" && contract.runtime?.kind === "slurm") return "runtime.kind slurm needs it";
+	for (const command of contract.validators ?? []) {
+		const words = command.split(/[\s;&|()<>`"']+/).filter((word) => word.length > 0);
+		if (words.some((word) => tool.binaries.includes(path.basename(word)))) {
+			return "the validation contract names it";
+		}
+	}
+	return null;
+}
+
+function lines(text: string): string[] {
+	return text
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0);
+}
+
+interface VersionProbe {
+	/** The first output line carrying a dotted version number, else the first line. */
+	line: string;
+	/** Set when `--version` failed, which marks an installed tool that does not work. */
+	fault?: string;
+}
+
+async function versionLine(binary: string, timeoutMs: number): Promise<VersionProbe> {
+	// A scratch cwd, as interop's version probe uses: a tool that reads config
+	// from its working directory must not pick up the workspace's.
+	const cwd = tmpdir();
+	const result = await runCommandVector(binary, ["--version"], {
+		cwd,
+		workspaceRoot: cwd,
+		timeoutMs,
+		maxOutputBytes: HPC_VERSION_MAX_OUTPUT_BYTES,
+	});
+	if (result.timedOut) return { line: `no version line (--version did not answer within ${timeoutMs}ms)` };
+	const output = lines(`${result.stdout}\n${result.stderr}`);
+	const line = output.find((entry) => /\d+\.\d+/.test(entry)) ?? output[0] ?? "no version line";
+	if (result.exitCode !== 0) return { line, fault: `--version exited ${result.exitCode ?? "on a signal"}` };
+	return { line };
+}
+
+async function probeTool(
+	tool: HpcToolSpec,
+	contract: ValidationContract | null,
+	timeoutMs: number,
+): Promise<DoctorFinding> {
+	const name = `toolchain ${tool.name}`;
+	const resolved = resolveOnPath(tool.binaries);
+	if (resolved.presence === "present" && resolved.binary !== undefined) {
+		const version = await versionLine(resolved.binary, timeoutMs);
+		if (version.fault !== undefined) {
+			return { ok: true, name, level: "warn", detail: `${resolved.binary}: ${version.fault}: ${version.line}` };
+		}
+		return { ok: true, name, level: "ok", detail: `${resolved.binary}: ${version.line}` };
+	}
+	const where = resolved.presence === "unknown" ? "PATH could not be read" : "not on PATH";
+	const reason = requiredBy(contract, tool);
+	if (reason !== null) return { ok: true, name, level: "warn", detail: `${where}; ${reason}` };
+	return { ok: true, name, level: "info", detail: where };
+}
+
+/**
+ * One row per HPC tool: where it resolves on PATH and the first line its
+ * `--version` prints. Every spawn is bounded and all of them run at once. An
+ * absent tool is information, not a fault, because most workspaces need none
+ * of these; it becomes a warning only when the workspace's validation
+ * contract asks for it. No row ever fails doctor.
+ */
+export async function hpcToolchainFindings(options: HpcToolchainOptions = {}): Promise<DoctorFinding[]> {
+	const loaded = loadValidationContract(options.workspaceRoot ?? process.cwd());
+	const contract = loaded.ok ? loaded.contract : null;
+	const timeoutMs = options.timeoutMs ?? HPC_VERSION_TIMEOUT_MS;
+	return Promise.all(HPC_TOOLS.map((tool) => probeTool(tool, contract, timeoutMs)));
+}