magus-cli 7.8.0 → 7.9.0

package/src/services/deps-plan.ts

@@ -0,0 +1,962 @@
+/**
+ * The one installer executor: plan what is missing, then install it.
+ *
+ * `planDeps` turns the requirements a probe found missing into ordered steps,
+ * each rendered by requires-probe's `renderInstall` (the only renderer).
+ * `applyDepsPlan` runs them through `runArgv` and returns one `ApplyOutcome`
+ * per step. Nothing here prints: `magus doctor` (text and `--json`),
+ * `magus install` and the TUI each render the same outcomes their own way.
+ *
+ * Every step is an argv run, a verified download, or both. Nothing from a
+ * manifest reaches a shell. Root is only ever `sudo -n`, only for `apt` and a
+ * `root` uv-module step, and decided once before any step runs: a password
+ * or a missing sudo is a loud outcome carrying the exact command, never a
+ * prompt.
+ *
+ * Re-running is the recovery: a plan is always built from a fresh probe, so a
+ * step whose effect is already present is not planned again; every step is
+ * idempotent or writes its result last (a release renames into place); the apt
+ * batch starts with `dpkg --configure -a` and waits on the dpkg lock; and only
+ * one apply runs at a time per user (`DepsLockBusy`).
+ */
+
+import { createHash } from "node:crypto";
+import {
+	chmodSync,
+	closeSync,
+	lstatSync,
+	mkdirSync,
+	mkdtempSync,
+	openSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	unlinkSync,
+	writeFileSync,
+	writeSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import {
+	type Arch,
+	BUN_PREFIX,
+	type InstallStep,
+	LOCAL_PREFIX,
+	type Os,
+	type Presence,
+	type Requirement,
+	TOOLCHAIN_BOOTSTRAP,
+	USER_PREFIXES,
+	type UserPrefix,
+	assertNever,
+	describeStep,
+	doctorFixCommand,
+	expandHome,
+	onPath,
+	pathRcLine,
+	probe,
+	rcFile,
+	renderInstall,
+	uvScriptArgv,
+	whyUnselectable,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
+import type { ResolvedBin } from "../types/index.js";
+import { type RunOptions, type RunResult, runArgv } from "../utils/run.js";
+import { parsePluginId } from "../utils/string-utils.js";
+
+// ─── planning ─────────────────────────────────────────────────────────────────
+
+/** What planning and applying need to know about this machine. */
+export interface PlanEnv {
+	os: Os;
+	arch: Arch;
+	home: string;
+	/** The PATH Claude Code and its MCP servers inherit. */
+	path: string;
+	/** `$SHELL`, to name the rc file for a PATH line. */
+	userShell: string;
+}
+
+/** A requirement a step installs, and the plugin root its check expands against. */
+export interface InstallTarget {
+	requirement: Requirement;
+	pluginRoot: string;
+}
+
+export interface PlannedStep {
+	step: InstallStep;
+	/** Plugin ids (or a profile's cliTools) that need it. */
+	requiredBy: string[];
+	/** Earlier steps (by name) whose tool this step runs. */
+	needs: string[];
+	/**
+	 * What the step installs: re-probed after it runs, because an installer that
+	 * exits 0 has not shown the requirement is now found.
+	 */
+	installs: InstallTarget[];
+}
+
+export interface PathAdvice {
+	prefix: UserPrefix;
+	rcFile: string;
+	rcLine: string;
+}
+
+export interface DepsPlan {
+	/** Toolchains, then the root batch (apt, root uv-module), then declaration order. */
+	steps: PlannedStep[];
+	/** What `--fix` cannot do; each `why` reads whole after "<name> — ". */
+	unfixable: { name: string; why: string }[];
+	pathAdvice: PathAdvice[];
+}
+
+/** The plugin ids among a requirement's sources, for display. */
+export function requiredByOf(bin: ResolvedBin): string[] {
+	return bin.sources.map((s) =>
+		s.startsWith("plugin:") ? s.slice("plugin:".length) : s,
+	);
+}
+
+/**
+ * Why a profile's pin on `bin` is not applied: the plugin that owns the tool
+ * installs it with an option that takes no version. The one wording, for
+ * doctor, install, the TUI and `magus update`.
+ */
+export function refusedPinWhy(bin: ResolvedBin, pin: string): string {
+	const owners = requiredByOf(bin).filter((s) => !s.startsWith("profile:"));
+	const option = bin.chosen;
+	const how = !option
+		? "no option usable here"
+		: option.via === "release"
+			? `its ${option.tag} release`
+			: option.via === "brew"
+				? `Homebrew (${option.cask ?? option.formula})`
+				: option.via;
+	return `the profile pins ${pin}, but ${owners.join(", ") || "its plugin"} installs it from ${how}, which takes no version — the pin is not applied; remove it or set it to "latest"`;
+}
+
+/** The tool a step needs on the machine before it can run, if any. */
+function toolOf(step: InstallStep): string | null {
+	switch (step.kind) {
+		case "argv":
+			return step.argv[0] ?? null;
+		case "uv-module":
+			return "uv";
+		case "bootstrap":
+		case "release":
+			return null;
+		default:
+			return assertNever(step);
+	}
+}
+
+/** Where a step leaves its binary, when that is a user prefix. */
+export function prefixOf(step: InstallStep): UserPrefix | null {
+	switch (step.kind) {
+		case "bootstrap":
+			return step.prefix;
+		case "release":
+			return step.dest;
+		case "argv":
+			if (step.argv[0] === "bun" && step.argv[1] === "add") return BUN_PREFIX;
+			if (step.argv[0] === "uv" && step.argv[1] === "tool") return LOCAL_PREFIX;
+			return null;
+		case "uv-module":
+			return null;
+		default:
+			return assertNever(step);
+	}
+}
+
+/** `tool` in a user prefix, when it is there but maybe not on PATH. */
+function inUserPrefix(tool: string, home: string): string | null {
+	for (const prefix of USER_PREFIXES) {
+		const found = onPath(tool, expandHome(prefix.dir, home));
+		if (found) return found;
+	}
+	return null;
+}
+
+/** Is `prefix` on the PATH Claude Code starts with? */
+export function prefixOnPath(prefix: UserPrefix, env: PlanEnv): boolean {
+	const dir = expandHome(prefix, env.home);
+	return env.path.split(delimiter).some((d) => d === dir || d === `${dir}/`);
+}
+
+/** The PATH line for a prefix, in the user's rc file. */
+export function pathAdviceFor(prefix: UserPrefix, env: PlanEnv): PathAdvice {
+	const info = USER_PREFIXES.find((u) => u.dir === prefix);
+	return {
+		prefix,
+		rcFile: rcFile(env.userShell),
+		rcLine: info ? info.rcLine(env.userShell) : "",
+	};
+}
+
+/** A root uv-module step may only come from a plugin of the magus marketplace. */
+function fromMagusMarketplace(bin: ResolvedBin): boolean {
+	return bin.sources.some(
+		(s) =>
+			s.startsWith("plugin:") &&
+			parsePluginId(s.slice("plugin:".length))?.marketplace === "magus",
+	);
+}
+
+/**
+ * The steps that install every `missing` requirement, in the order they must
+ * run. `presence[i]` is the probe's answer for `bins[i]`. An `off-path`
+ * requirement is not reinstalled: it needs a PATH line, which `pathAdvice`
+ * carries. An `unknown` one (a check too slow to answer) is left alone.
+ */
+export function planDeps(
+	bins: ResolvedBin[],
+	presence: Presence[],
+	env: PlanEnv,
+): DepsPlan {
+	const unfixable: DepsPlan["unfixable"] = [];
+	const advice = new Map<UserPrefix, PathAdvice>();
+	const missing: ResolvedBin[] = [];
+	bins.forEach((bin, i) => {
+		const p = presence[i];
+		if (p?.status === "missing") missing.push(bin);
+		if (p?.status === "off-path") {
+			advice.set(p.prefix, pathAdviceFor(p.prefix, env));
+		}
+	});
+
+	// A pin the owning plugin's option cannot carry: unfixable whatever the
+	// tool's presence, because no install here would honour it.
+	for (const bin of bins) {
+		for (const pin of bin.refusedPins ?? []) {
+			unfixable.push({ name: bin.name, why: refusedPinWhy(bin, pin) });
+		}
+	}
+
+	const declared = new Set(bins.map((b) => b.name));
+	const available = (tool: string) =>
+		onPath(tool, env.path) !== null || inUserPrefix(tool, env.home) !== null;
+	const has = (tool: string) => declared.has(tool) || available(tool);
+
+	const toolchains: PlannedStep[] = [];
+	const rootBatch: PlannedStep[] = [];
+	const rest: PlannedStep[] = [];
+	const aptPackages: string[] = [];
+	const aptNames: string[] = [];
+	const aptRequiredBy = new Set<string>();
+	const aptInstalls: InstallTarget[] = [];
+	const target = (bin: ResolvedBin): InstallTarget => ({
+		requirement: bin,
+		pluginRoot: bin.root ?? "",
+	});
+
+	for (const bin of missing) {
+		const option = bin.chosen;
+		if (!option) {
+			unfixable.push({
+				name: bin.name,
+				why: `cannot be installed here: ${whyUnselectable(bin, env, has)}`,
+			});
+			continue;
+		}
+		const step = renderInstall(bin, option, {
+			os: env.os,
+			arch: env.arch,
+			pluginRoot: bin.root ?? "",
+		});
+		if (
+			step.kind === "uv-module" &&
+			step.escalation === "sudo" &&
+			!fromMagusMarketplace(bin)
+		) {
+			unfixable.push({
+				name: bin.name,
+				why: `a root step from a plugin outside the magus marketplace is never run by magus — run it yourself if you trust it: ${describeStep(step, env.os)}`,
+			});
+			continue;
+		}
+		const requiredBy = requiredByOf(bin);
+		if (option.via === "apt") {
+			aptPackages.push(...option.packages);
+			aptNames.push(bin.name);
+			aptInstalls.push(target(bin));
+			for (const r of requiredBy) aptRequiredBy.add(r);
+			continue;
+		}
+		const planned: PlannedStep = {
+			step,
+			requiredBy,
+			needs: [],
+			installs: [target(bin)],
+		};
+		if (bin.name in TOOLCHAIN_BOOTSTRAP) toolchains.push(planned);
+		else if (step.kind === "uv-module" && step.escalation === "sudo")
+			rootBatch.push(planned);
+		else rest.push(planned);
+	}
+	if (aptPackages.length > 0) {
+		const step = renderInstall(
+			{ name: aptNames.join(", "), check: [], install: [] },
+			{ via: "apt", packages: [...new Set(aptPackages)] },
+			{ os: env.os, arch: env.arch, pluginRoot: "" },
+		);
+		rootBatch.unshift({
+			step,
+			requiredBy: [...aptRequiredBy],
+			needs: [],
+			installs: aptInstalls,
+		});
+	}
+
+	const ordered = [...toolchains, ...rootBatch, ...rest];
+	const plannedNames = new Set(ordered.map((p) => p.step.name));
+	const steps: PlannedStep[] = [];
+	for (const p of ordered) {
+		const tool = toolOf(p.step);
+		if (tool && !available(tool)) {
+			if (!plannedNames.has(tool)) {
+				unfixable.push({
+					name: p.step.name,
+					why: `needs ${tool}, which is not installed and cannot be installed here`,
+				});
+				plannedNames.delete(p.step.name);
+				continue;
+			}
+			p.needs.push(tool);
+		}
+		steps.push(p);
+		const prefix = prefixOf(p.step);
+		if (prefix && !prefixOnPath(prefix, env)) {
+			advice.set(prefix, pathAdviceFor(prefix, env));
+		}
+	}
+	return { steps, unfixable, pathAdvice: [...advice.values()] };
+}
+
+/**
+ * One consent line per step: its paste-able form, who needs it, `[sudo]` when
+ * it runs as root. Shown before anything runs, by every front end.
+ */
+export function planLines(plan: DepsPlan, os: Os): string[] {
+	return plan.steps.map((p) => {
+		const sudo =
+			"escalation" in p.step && p.step.escalation === "sudo" ? "[sudo] " : "";
+		const by = p.requiredBy.length > 0 ? `   (${p.requiredBy.join(", ")})` : "";
+		return `${sudo}${p.step.name}: ${describeStep(p.step, os)}${by}`;
+	});
+}
+
+// ─── applying ─────────────────────────────────────────────────────────────────
+
+/**
+ * "installed" means the re-probe after the step found the requirement — never
+ * only that the installer exited 0. "off-path": it landed in `dir`, which is
+ * not on the PATH Claude Code starts with.
+ */
+export type ApplyStatus =
+	| "installed"
+	| "off-path"
+	| "failed"
+	| "needs-password"
+	| "needs-root"
+	| "blocked";
+
+export interface ApplyOutcome {
+	name: string;
+	status: ApplyStatus;
+	requiredBy: string[];
+	/** Exactly what ran last for this step (or would have). */
+	argv?: string[];
+	exitCode: number | null;
+	outputTail: string;
+	durationMs: number;
+	/** "off-path": the directory the binary landed in. */
+	dir?: string;
+	/** For every status except "installed": the exact command for the user. */
+	remedy?: string;
+}
+
+export type ApplyEvent =
+	| { type: "step-start"; name: string; describe: string }
+	| { type: "output"; name: string; chunk: string }
+	| { type: "step-end"; outcome: ApplyOutcome };
+
+/** The side effects an apply makes, injectable so tests run none of them. */
+export interface ApplyIO {
+	run(argv: string[], opts: RunOptions): Promise<RunResult>;
+	/** The body at `url`, or throws. */
+	download(url: string): Promise<Uint8Array>;
+	/** This process's uid; null where the platform has none. */
+	uid(): number | null;
+	/** Is a process with this pid alive? */
+	alive(pid: number): boolean;
+	/**
+	 * The probe's answer for one requirement now, on the PATH Claude Code starts
+	 * with — the same `probe` doctor and the hook run, at full depth.
+	 */
+	verify(target: InstallTarget, env: PlanEnv): Promise<Presence>;
+}
+
+const DOWNLOAD_TIMEOUT_MS = 10 * 60_000;
+/** The per-check cap a post-install re-probe runs under: doctor's. */
+const VERIFY_CAP_MS = 60_000;
+
+export const REAL_APPLY_IO: ApplyIO = {
+	run: (argv, opts) =>
+		runArgv({ cmd: argv[0] ?? "", args: argv.slice(1) }, opts),
+	download: async (url) => {
+		const res = await fetch(url, {
+			signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+		});
+		if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+		// Every URL here is https; a redirect off it is refused, not read.
+		if (new URL(res.url).protocol !== "https:") {
+			throw new Error(`${url} redirected off https, to ${res.url}`);
+		}
+		return new Uint8Array(await res.arrayBuffer());
+	},
+	uid: () => (typeof process.getuid === "function" ? process.getuid() : null),
+	alive: (pid) => {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch (error) {
+			return (error as NodeJS.ErrnoException).code === "EPERM";
+		}
+	},
+	verify: async ({ requirement, pluginRoot }, env) => {
+		const [presence] = await probe([requirement], {
+			pluginRoot,
+			os: env.os,
+			arch: env.arch,
+			home: env.home,
+			path: env.path,
+			capMs: VERIFY_CAP_MS,
+			depth: "full",
+			userShell: env.userShell,
+		});
+		return presence ?? { name: requirement.name, status: "present" };
+	},
+};
+
+export interface ApplyOptions {
+	/** Skip the consent question. */
+	yes: boolean;
+	/** Asked once with the whole plan, unless `yes`. False installs nothing. */
+	confirm(plan: DepsPlan): Promise<boolean>;
+	onEvent?: (e: ApplyEvent) => void;
+	env: PlanEnv;
+	/** The single-apply lock. */
+	lockPath: string;
+	/** The project a remedy's `magus doctor --fix` names; null for "here". */
+	projectDir?: string | null;
+	io?: Partial<ApplyIO>;
+}
+
+/** Another apply holds the lock. */
+export class DepsLockBusy extends Error {
+	constructor(readonly pid: number) {
+		super(
+			`another magus dependency install (pid ${pid}) is running — wait for it, then re-run`,
+		);
+		this.name = "DepsLockBusy";
+	}
+}
+
+/** `${XDG_CACHE_HOME:-~/.cache}/magus/doctor-fix.lock` */
+export function defaultLockPath(home: string, xdgCacheHome?: string): string {
+	return join(xdgCacheHome || join(home, ".cache"), "magus", "doctor-fix.lock");
+}
+
+/** Take the lock (O_EXCL, holding our pid), taking over one whose pid is gone. */
+function acquireLock(path: string, io: ApplyIO): () => void {
+	mkdirSync(dirname(path), { recursive: true });
+	for (let attempt = 0; attempt < 2; attempt++) {
+		try {
+			const fd = openSync(path, "wx", 0o600);
+			writeSync(fd, String(process.pid));
+			closeSync(fd);
+			return () => {
+				try {
+					if (readFileSync(path, "utf8").trim() === String(process.pid)) {
+						unlinkSync(path);
+					}
+				} catch {
+					// Already gone.
+				}
+			};
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			const pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
+			if (Number.isInteger(pid) && pid > 0 && io.alive(pid)) {
+				throw new DepsLockBusy(pid);
+			}
+			unlinkSync(path); // stale: its holder is gone
+		}
+	}
+	throw new Error(`could not take ${path}`);
+}
+
+const STEP_TIMEOUT_MS = 15 * 60_000;
+const SUDO_KILL_GRACE_MS = 30_000;
+/** A root step as uid 0: the same environment `sudo` would be given. */
+const AS_ROOT = ["env", "DEBIAN_FRONTEND=noninteractive"];
+/** A root step through sudo: never a prompt, and the env survives env_reset. */
+const SUDO = ["sudo", "-n", ...AS_ROOT];
+const APT_LOCK = ["-o", "DPkg::Lock::Timeout=120"];
+const IMPORT_GUARD =
+	"import importlib.util,sys; sys.exit(importlib.util.find_spec(sys.argv[1]) is None)";
+
+type RootMode = "direct" | "sudo" | "needs-root" | "needs-password";
+
+/** The paste-able form of a root step, without its `sudo`. */
+function asRootLine(step: InstallStep, os: Os): string {
+	if (step.kind === "argv" && step.argv[0] === "apt-get") {
+		const install = describeStep({ ...step, escalation: "none" }, os);
+		return `apt-get update && ${install}`;
+	}
+	return describeStep(
+		"escalation" in step ? { ...step, escalation: "none" } : step,
+		os,
+	).replace(/^sudo /, "");
+}
+
+function rootRemedy(
+	mode: RootMode,
+	step: InstallStep,
+	os: Os,
+	projectDir: string | null,
+): string {
+	const asRoot = asRootLine(step, os);
+	if (mode === "needs-root") return `as root: ${asRoot}`;
+	return `run: sudo -v   then: ${doctorFixCommand(projectDir)}   (or run yourself: ${describeStep(step, os)};   not in sudoers? as root: ${asRoot})`;
+}
+
+/**
+ * Run the plan. Asks once (unless `yes`), takes the single-apply lock, decides
+ * root once, then runs each step in order. A step whose prerequisite step did
+ * not install is `blocked`. Returns one outcome per step; prints nothing.
+ * Throws {@link DepsLockBusy} when another apply is running.
+ */
+export async function applyDepsPlan(
+	plan: DepsPlan,
+	opts: ApplyOptions,
+): Promise<ApplyOutcome[]> {
+	if (plan.steps.length === 0) return [];
+	if (!opts.yes && !(await opts.confirm(plan))) return [];
+	const io: ApplyIO = { ...REAL_APPLY_IO, ...opts.io };
+	const release = acquireLock(opts.lockPath, io);
+	try {
+		return await applySteps(plan, opts, io);
+	} finally {
+		release();
+	}
+}
+
+async function applySteps(
+	plan: DepsPlan,
+	opts: ApplyOptions,
+	io: ApplyIO,
+): Promise<ApplyOutcome[]> {
+	const { env } = opts;
+	const userPrefixDirs = USER_PREFIXES.map((u) => expandHome(u.dir, env.home));
+	// Children see the user prefixes too: a tool installed a step ago is there.
+	const childPath = [env.path, ...userPrefixDirs]
+		.filter(Boolean)
+		.join(delimiter);
+	const childEnv = { ...process.env, PATH: childPath, HOME: env.home };
+	const resolve = (tool: string) =>
+		onPath(tool, env.path) ?? inUserPrefix(tool, env.home) ?? tool;
+
+	const anyRoot = plan.steps.some(
+		(p) => "escalation" in p.step && p.step.escalation === "sudo",
+	);
+	let mode: RootMode = "direct";
+	if (anyRoot && io.uid() !== 0) {
+		if (onPath("sudo", env.path) === null) mode = "needs-root";
+		else {
+			const probe = await io.run(["sudo", "-n", "true"], {
+				timeoutMs: 10_000,
+				env: childEnv,
+			});
+			mode = probe.exitCode === 0 ? "sudo" : "needs-password";
+		}
+	}
+
+	const outcomes: ApplyOutcome[] = [];
+	const done = new Set<string>();
+	for (const p of plan.steps) {
+		const { step } = p;
+		const describe = describeStep(step, env.os);
+		const base = { name: step.name, requiredBy: p.requiredBy };
+		const blocker = p.needs.find((n) => !done.has(n));
+		if (blocker) {
+			const outcome: ApplyOutcome = {
+				...base,
+				status: "blocked",
+				exitCode: null,
+				outputTail: "",
+				durationMs: 0,
+				remedy: `after ${blocker} is installed: ${describe}`,
+			};
+			outcomes.push(outcome);
+			opts.onEvent?.({ type: "step-end", outcome });
+			continue;
+		}
+		const root = "escalation" in step && step.escalation === "sudo";
+		if (root && (mode === "needs-root" || mode === "needs-password")) {
+			const outcome: ApplyOutcome = {
+				...base,
+				status: mode,
+				exitCode: null,
+				outputTail: "",
+				durationMs: 0,
+				remedy: rootRemedy(mode, step, env.os, opts.projectDir ?? null),
+			};
+			outcomes.push(outcome);
+			opts.onEvent?.({ type: "step-end", outcome });
+			continue;
+		}
+		opts.onEvent?.({ type: "step-start", name: step.name, describe });
+		const started = Date.now();
+		const run = (argv: string[], escalated = false) =>
+			io.run(argv, {
+				timeoutMs: STEP_TIMEOUT_MS,
+				env: childEnv,
+				...(escalated ? { killGraceMs: SUDO_KILL_GRACE_MS } : {}),
+				onOutput: (chunk) =>
+					opts.onEvent?.({ type: "output", name: step.name, chunk }),
+			});
+		const escalate = (argv: string[]) =>
+			!root
+				? argv
+				: mode === "sudo"
+					? [...SUDO, ...argv]
+					: [...AS_ROOT, ...argv];
+		let result: StepResult;
+		try {
+			result = await runStep(step, {
+				env,
+				io,
+				run,
+				escalate,
+				root,
+				resolve,
+			});
+		} catch (error) {
+			result = {
+				ok: false,
+				exitCode: null,
+				outputTail: error instanceof Error ? error.message : String(error),
+			};
+		}
+		const found = result.ok
+			? await verifyInstalled(p, { env, io, run, resolve })
+			: null;
+		const outcome: ApplyOutcome = {
+			...base,
+			status: found?.status ?? "failed",
+			...(result.argv ? { argv: result.argv } : {}),
+			exitCode: result.exitCode,
+			outputTail: found?.why
+				? [result.outputTail, found.why].filter(Boolean).join("\n")
+				: result.outputTail,
+			durationMs: Date.now() - started,
+			...(found?.dir ? { dir: found.dir } : {}),
+			...(found?.status === "installed"
+				? {}
+				: {
+						remedy:
+							found?.remedy ?? (root ? `run yourself: ${describe}` : describe),
+					}),
+		};
+		// Off PATH still exists on disk: a later step reaches it by full path.
+		if (found?.status === "installed" || found?.status === "off-path") {
+			done.add(step.name);
+		}
+		outcomes.push(outcome);
+		opts.onEvent?.({ type: "step-end", outcome });
+	}
+	return outcomes;
+}
+
+interface Verified {
+	status: "installed" | "off-path" | "failed";
+	dir?: string;
+	why?: string;
+	remedy?: string;
+}
+
+/** `~/…` for a directory under `home`, else the directory as given. */
+function homeRelative(dir: string, home: string): string {
+	return dir === home || dir.startsWith(`${home}/`)
+		? `~${dir.slice(home.length)}`
+		: dir;
+}
+
+/**
+ * Where a step put its binary when that is not a fixed user prefix: for
+ * `bun add -g`, bun's own global bin directory (`bun pm bin -g`), which
+ * follows BUN_INSTALL and XDG_CACHE_HOME. Null when the step names no such
+ * place.
+ */
+async function landingDir(
+	step: InstallStep,
+	ctx: Pick<StepContext, "run" | "resolve">,
+): Promise<string | null> {
+	if (
+		step.kind === "argv" &&
+		step.argv[0] === "bun" &&
+		step.argv[1] === "add"
+	) {
+		const r = await ctx.run([ctx.resolve("bun"), "pm", "bin", "-g"]);
+		const dir = r.exitCode === 0 ? r.outputTail.trim().split("\n").pop() : "";
+		return dir?.trim() || null;
+	}
+	return null;
+}
+
+/**
+ * After a step's installer exited 0, re-probe everything it installs with the
+ * same probe doctor runs. Installed only when the probe now finds each one.
+ * Found in a directory off the PATH Claude Code starts with: off-path, naming
+ * the directory and the rc line. Not found at all: failed.
+ */
+async function verifyInstalled(
+	p: PlannedStep,
+	ctx: Pick<StepContext, "env" | "io" | "run" | "resolve">,
+): Promise<Verified> {
+	const { env } = ctx;
+	const offPath: Verified[] = [];
+	const missing: string[] = [];
+	for (const target of p.installs) {
+		const presence = await ctx.io.verify(target, env);
+		if (presence.status === "present") continue;
+		if (presence.status === "off-path") {
+			offPath.push({ status: "off-path", dir: presence.prefix });
+			continue;
+		}
+		const tool = target.requirement.check[0] ?? target.requirement.name;
+		const landed = await landingDir(p.step, ctx);
+		if (landed && onPath(tool, landed)) {
+			offPath.push({ status: "off-path", dir: homeRelative(landed, env.home) });
+			continue;
+		}
+		missing.push(
+			`${target.requirement.name}: the installer exited 0, but \`${target.requirement.check.join(" ")}\` still fails`,
+		);
+	}
+	if (missing.length > 0) {
+		return { status: "failed", why: missing.join("\n") };
+	}
+	const first = offPath[0];
+	if (first?.dir) {
+		const line = pathRcLine(first.dir, env.userShell);
+		return {
+			status: "off-path",
+			dir: first.dir,
+			why: `installed in ${first.dir}, which is not on the PATH Claude Code starts with`,
+			remedy: `add  ${line}  to ${rcFile(env.userShell)}, then restart Claude Code from a new terminal`,
+		};
+	}
+	return { status: "installed" };
+}
+
+interface StepResult {
+	ok: boolean;
+	argv?: string[];
+	exitCode: number | null;
+	outputTail: string;
+}
+
+interface StepContext {
+	env: PlanEnv;
+	io: ApplyIO;
+	run(argv: string[], escalated?: boolean): Promise<RunResult>;
+	escalate(argv: string[]): string[];
+	root: boolean;
+	resolve(tool: string): string;
+}
+
+const fromRun = (argv: string[], r: RunResult): StepResult => ({
+	ok: r.exitCode === 0 && !r.timedOut && r.spawnError === undefined,
+	argv,
+	exitCode: r.exitCode,
+	outputTail: r.spawnError ?? r.outputTail,
+});
+
+/** Run argvs in order, stopping at the first that fails. */
+async function sequence(
+	ctx: StepContext,
+	argvs: string[][],
+	escalated: boolean,
+): Promise<StepResult> {
+	let last: StepResult = { ok: true, exitCode: 0, outputTail: "" };
+	for (const argv of argvs) {
+		last = fromRun(argv, await ctx.run(argv, escalated));
+		if (!last.ok) return last;
+	}
+	return last;
+}
+
+async function runStep(
+	step: InstallStep,
+	ctx: StepContext,
+): Promise<StepResult> {
+	switch (step.kind) {
+		case "argv": {
+			const [tool = "", ...args] = step.argv;
+			if (tool === "apt-get") {
+				const install = ctx.escalate(["apt-get", ...APT_LOCK, ...args]);
+				return sequence(
+					ctx,
+					[
+						ctx.escalate(["dpkg", "--configure", "-a"]),
+						ctx.escalate(["apt-get", ...APT_LOCK, "update"]),
+						install,
+					],
+					ctx.root,
+				);
+			}
+			return sequence(
+				ctx,
+				[ctx.escalate([ctx.resolve(tool), ...args])],
+				ctx.root,
+			);
+		}
+		case "uv-module":
+			return runUvModule(step, ctx);
+		case "bootstrap":
+			return runBootstrap(step, ctx);
+		case "release":
+			return runRelease(step, ctx);
+		default:
+			return assertNever(step);
+	}
+}
+
+async function runUvModule(
+	step: Extract<InstallStep, { kind: "uv-module" }>,
+	ctx: StepContext,
+): Promise<StepResult> {
+	const uv = ctx.resolve("uv");
+	const sync = await sequence(
+		ctx,
+		[uvScriptArgv(["sync"], step.script, uv)],
+		false,
+	);
+	if (!sync.ok) return sync;
+	const findArgv = uvScriptArgv(["python", "find"], step.script, uv);
+	const found = await ctx.run(findArgv);
+	const findResult = fromRun(findArgv, found);
+	if (!findResult.ok) return findResult;
+	const py = found.outputTail.trim().split("\n").pop()?.trim() ?? "";
+	if (!py) {
+		return {
+			...findResult,
+			ok: false,
+			outputTail: "uv python find printed no interpreter",
+		};
+	}
+	const guardArgv = [py, "-c", IMPORT_GUARD, step.module];
+	const guard = fromRun(guardArgv, await ctx.run(guardArgv));
+	if (!guard.ok) {
+		return {
+			...guard,
+			ok: false,
+			outputTail: `interpreter ${py} cannot import ${step.module}: the script env was not built`,
+		};
+	}
+	return sequence(
+		ctx,
+		[ctx.escalate([py, "-B", "-m", step.module, ...step.args])],
+		ctx.root,
+	);
+}
+
+async function runBootstrap(
+	step: Extract<InstallStep, { kind: "bootstrap" }>,
+	ctx: StepContext,
+): Promise<StepResult> {
+	const body = await ctx.io.download(step.url);
+	const dir = mkdtempSync(join(tmpdir(), "magus-bootstrap-"));
+	try {
+		const file = join(dir, "install.sh");
+		writeFileSync(file, body, { mode: 0o600 });
+		return await sequence(ctx, [[ctx.resolve(step.interpreter), file]], false);
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+const sha256 = (bytes: Uint8Array): string =>
+	createHash("sha256").update(bytes).digest("hex");
+
+/**
+ * Download, verify against the pinned digest, extract the one binary into a
+ * temp dir inside the destination (so the final rename stays on one
+ * filesystem), refuse anything but a regular file, then rename into place.
+ * Nothing is written to the destination unless every check passed.
+ */
+async function runRelease(
+	step: Extract<InstallStep, { kind: "release" }>,
+	ctx: StepContext,
+): Promise<StepResult> {
+	if (!step.sha256) {
+		return {
+			ok: false,
+			exitCode: null,
+			outputTail: "no pinned sha256 for this platform",
+		};
+	}
+	const body = await ctx.io.download(step.url);
+	const actual = sha256(body);
+	if (actual !== step.sha256) {
+		return {
+			ok: false,
+			exitCode: null,
+			outputTail: `sha256 mismatch for ${step.url}: expected ${step.sha256}, got ${actual} — nothing was installed`,
+		};
+	}
+	const dest = expandHome(step.dest, ctx.env.home);
+	mkdirSync(dest, { recursive: true });
+	const tmp = mkdtempSync(join(dest, ".magus-tmp-"));
+	try {
+		if (step.format === "binary") {
+			// The asset is the binary: the verified bytes are the file.
+			const file = join(tmp, step.binary);
+			writeFileSync(file, body, { mode: 0o755 });
+			chmodSync(file, 0o755);
+			renameSync(file, join(dest, step.binary));
+			return { ok: true, exitCode: 0, outputTail: `verified sha256 ${actual}` };
+		}
+		const archive = join(tmp, step.url.slice(step.url.lastIndexOf("/") + 1));
+		writeFileSync(archive, body, { mode: 0o600 });
+		const out = join(tmp, "out");
+		mkdirSync(out);
+		const tarArgv = [
+			ctx.resolve("tar"),
+			"-xzf",
+			archive,
+			"-C",
+			out,
+			"--",
+			step.binary,
+		];
+		const extracted = fromRun(tarArgv, await ctx.run(tarArgv));
+		if (!extracted.ok) return extracted;
+		const file = join(out, step.binary);
+		const stat = lstatSync(file);
+		if (!stat.isFile()) {
+			return {
+				...extracted,
+				ok: false,
+				outputTail: `${step.binary} in the archive is not a regular file — refused`,
+			};
+		}
+		chmodSync(file, 0o755);
+		renameSync(file, join(dest, step.binary));
+		return { ...extracted, outputTail: `verified sha256 ${actual}` };
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+}