magus-cli 7.8.0 → 7.9.0

package/src/__tests__/deps-plan.test.ts

@@ -0,0 +1,896 @@
+/**
+ * The deps executor: what `planDeps` plans and in what order, and what
+ * `applyDepsPlan` runs — root decided once, never a prompt, releases verified
+ * against the pinned digest, the uv-module guard, blocked steps, consent and
+ * the single-apply lock. Every side effect goes through an injected `ApplyIO`
+ * except where a real `tar` is the point; HOME and PATH are temp dirs.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	readdirSync,
+	rmSync,
+	statSync,
+	symlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { renderApplyText } from "../cli/deps-view.js";
+import {
+	type ApplyIO,
+	type ApplyOptions,
+	DepsLockBusy,
+	type DepsPlan,
+	type PlanEnv,
+	REAL_APPLY_IO,
+	applyDepsPlan,
+	planDeps,
+	planLines,
+} from "../services/deps-plan.js";
+import { cliToolToBin } from "../services/resolver.js";
+import {
+	type InstallOption,
+	type Presence,
+	parseRequires,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
+import type { ResolvedBin } from "../types/index.js";
+import type { RunOptions, RunResult } from "../utils/run.js";
+
+let root: string;
+let bin: string;
+let env: PlanEnv;
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "deps-plan-"));
+	bin = join(root, "bin");
+	mkdirSync(bin);
+	mkdirSync(join(root, "home"));
+	env = {
+		os: "linux",
+		arch: "amd64",
+		home: join(root, "home"),
+		path: bin,
+		userShell: "/bin/zsh",
+	};
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+function tool(dir: string, name: string): void {
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(join(dir, name), "#!/bin/sh\nexit 0\n");
+	chmodSync(join(dir, name), 0o755);
+}
+
+function dep(
+	name: string,
+	option: InstallOption,
+	plugin = "terminal@magus",
+	extra: Partial<ResolvedBin> = {},
+): ResolvedBin {
+	return {
+		name,
+		check: [name, "--version"],
+		install: [option],
+		chosen: option,
+		sources: [`plugin:${plugin}`],
+		...extra,
+	};
+}
+
+const missing = (name: string): Presence => ({ name, status: "missing" });
+const present = (name: string): Presence => ({ name, status: "present" });
+
+const UV = dep("uv", { via: "bootstrap", tool: "uv" }, "browser-use@magus");
+const LIBS = dep(
+	"chromium-libs",
+	{
+		via: "uv-module",
+		script: "scripts/mcp-server.py",
+		module: "playwright",
+		args: ["install-deps", "chromium"],
+		root: true,
+	},
+	"browser-use@magus",
+	{ root: "/plugins/browser-use" },
+);
+const CHROMIUM = dep(
+	"chromium",
+	{
+		via: "uv-module",
+		script: "scripts/mcp-server.py",
+		module: "playwright",
+		args: ["install", "chromium"],
+	},
+	"browser-use@magus",
+	{ root: "/plugins/browser-use" },
+);
+const TMUX = dep("tmux", { via: "apt", packages: ["tmux"] });
+const ZSH = dep("zsh", { via: "apt", packages: ["zsh"] });
+const CLAUDISH = dep(
+	"claudish",
+	{ via: "bun", package: "claudish" },
+	"claudish@magus",
+);
+const BUN = dep("bun", { via: "bootstrap", tool: "bun" }, "claudish@magus");
+
+const names = (plan: DepsPlan) => plan.steps.map((p) => p.step.name);
+
+// ─── planning ─────────────────────────────────────────────────────────────────
+
+describe("planDeps", () => {
+	test("toolchains first, then the root batch (apt merged, then root uv-module), then declaration order", () => {
+		for (const t of ["curl", "unzip", "apt-get"]) tool(bin, t);
+		const bins = [CLAUDISH, CHROMIUM, TMUX, LIBS, ZSH, BUN, UV];
+		const plan = planDeps(
+			bins,
+			bins.map((b) => missing(b.name)),
+			env,
+		);
+		expect(names(plan)).toEqual([
+			"bun",
+			"uv",
+			"tmux, zsh",
+			"chromium-libs",
+			"claudish",
+			"chromium",
+		]);
+		const apt = plan.steps[2]?.step;
+		expect(apt).toEqual({
+			kind: "argv",
+			name: "tmux, zsh",
+			escalation: "sudo",
+			argv: [
+				"apt-get",
+				"install",
+				"-y",
+				"--no-install-recommends",
+				"tmux",
+				"zsh",
+			],
+		});
+		// Each step that runs a tool installed earlier in the plan names it.
+		const needs = Object.fromEntries(
+			plan.steps.map((p) => [p.step.name, p.needs]),
+		);
+		expect(needs.claudish).toEqual(["bun"]);
+		expect(needs.chromium).toEqual(["uv"]);
+		expect(needs["chromium-libs"]).toEqual(["uv"]);
+		expect(plan.unfixable).toEqual([]);
+	});
+
+	test("consent lines mark root steps and name who needs each", () => {
+		for (const t of ["apt-get", "uv"]) tool(bin, t);
+		const plan = planDeps(
+			[TMUX, LIBS],
+			[missing("tmux"), missing("chromium-libs")],
+			env,
+		);
+		const lines = planLines(plan, "linux");
+		expect(lines[0]).toBe(
+			"[sudo] tmux: sudo apt-get install -y --no-install-recommends tmux   (terminal@magus)",
+		);
+		expect(lines[1]).toStartWith(
+			"[sudo] chromium-libs: uv sync --no-config --script",
+		);
+		expect(lines[1]).toContain("(browser-use@magus)");
+	});
+
+	test("resumable: only what is still missing is planned", () => {
+		for (const t of ["apt-get", "bun"]) tool(bin, t);
+		const plan = planDeps(
+			[TMUX, ZSH, CLAUDISH],
+			[present("tmux"), missing("zsh"), present("claudish")],
+			env,
+		);
+		expect(names(plan)).toEqual(["zsh"]);
+	});
+
+	test("off PATH is not reinstalled: it gets the rc line", () => {
+		const plan = planDeps(
+			[CLAUDISH],
+			[{ name: "claudish", status: "off-path", prefix: "~/.bun/bin" }],
+			env,
+		);
+		expect(plan.steps).toEqual([]);
+		expect(plan.pathAdvice).toEqual([
+			{
+				prefix: "~/.bun/bin",
+				rcFile: "~/.zshrc",
+				rcLine: 'export PATH="$HOME/.bun/bin:$PATH"',
+			},
+		]);
+	});
+
+	test("an install into a prefix that is not on PATH says so before it runs", () => {
+		const release = dep("tmux-mcp", {
+			via: "release",
+			repo: "MadAppGang/tmux-mcp",
+			tag: "v2.0.0",
+			asset: "tmux-mcp_{os}_{arch}.tar.gz",
+			binary: "tmux-mcp",
+			sha256: { linux_amd64: "a".repeat(64) },
+		});
+		const plan = planDeps([release], [missing("tmux-mcp")], env);
+		expect(plan.pathAdvice.map((a) => a.prefix)).toEqual(["~/.local/bin"]);
+		const onPath = planDeps([release], [missing("tmux-mcp")], {
+			...env,
+			path: `${bin}:${join(env.home, ".local", "bin")}`,
+		});
+		expect(onPath.pathAdvice).toEqual([]);
+	});
+
+	test("no usable option is unfixable, with the reason", () => {
+		const brewOnly = dep(
+			"tmux",
+			{ via: "brew", formula: "tmux" },
+			"terminal@magus",
+			{
+				chosen: null,
+			},
+		);
+		const plan = planDeps([brewOnly], [missing("tmux")], {
+			...env,
+			os: "darwin",
+		});
+		expect(plan.steps).toEqual([]);
+		expect(plan.unfixable).toEqual([
+			{
+				name: "tmux",
+				why: "cannot be installed here: Homebrew is missing — install it from https://brew.sh first",
+			},
+		]);
+	});
+
+	test("a root uv-module from outside the magus marketplace is never planned", () => {
+		tool(bin, "uv");
+		const foreign = { ...LIBS, sources: ["plugin:browser-use@someone-else"] };
+		const plan = planDeps([foreign], [missing("chromium-libs")], env);
+		expect(plan.steps).toEqual([]);
+		expect(plan.unfixable[0]?.why).toContain("outside the magus marketplace");
+		expect(plan.unfixable[0]?.why).toContain(
+			"-B -m playwright install-deps chromium",
+		);
+	});
+
+	test("profile-only kinds: refused in a manifest, planned from a profile's cliTools", () => {
+		for (const via of ["npm", "pip", "go"]) {
+			const parsed = parseRequires({
+				requires: {
+					schema: 1,
+					bin: [{ name: "x", check: ["x"], install: [{ via, package: "x" }] }],
+				},
+			});
+			expect(parsed.ok).toBe(false);
+			expect(parsed.ok ? [] : parsed.errors).toContain(
+				`requires.bin[0] (x).install[0]: via ${via} is not allowed in plugin.json`,
+			);
+		}
+		tool(bin, "npm");
+		const codex = cliToolToBin("codex", "0.41.0");
+		// Selected against this process's PATH; plan against the pinned one.
+		const pinned = {
+			...codex,
+			chosen: codex.install[0] ?? null,
+			sources: ["profile:p.cliTools"],
+		};
+		const plan = planDeps([pinned], [missing("codex")], env);
+		expect(plan.steps.map((p) => p.step)).toEqual([
+			{
+				kind: "argv",
+				name: "codex",
+				escalation: "none",
+				argv: ["npm", "install", "-g", "@openai/codex@0.41.0"],
+			},
+		]);
+	});
+
+	test("a profile pin the owning plugin's option cannot carry is unfixable, present or not", () => {
+		const owned: ResolvedBin = {
+			...CLAUDISH,
+			chosen: { via: "brew", formula: "madappgang/tap/claudish" },
+			sources: ["profile:p.cliTools", "plugin:claudish@magus"],
+			refusedPins: ["6.1.0"],
+		};
+		for (const presence of [missing("claudish"), present("claudish")]) {
+			const plan = planDeps([owned], [presence], { ...env, os: "darwin" });
+			expect(plan.unfixable).toContainEqual({
+				name: "claudish",
+				why: 'the profile pins 6.1.0, but claudish@magus installs it from Homebrew (madappgang/tap/claudish), which takes no version — the pin is not applied; remove it or set it to "latest"',
+			});
+		}
+	});
+
+	test("a step whose tool is neither here nor planned is unfixable", () => {
+		const plan = planDeps([CLAUDISH], [missing("claudish")], env);
+		expect(plan.steps).toEqual([]);
+		expect(plan.unfixable[0]).toMatchObject({ name: "claudish" });
+		expect(plan.unfixable[0]?.why).toContain("needs bun");
+	});
+});
+
+// ─── applying ─────────────────────────────────────────────────────────────────
+
+interface Call {
+	argv: string[];
+	opts: RunOptions;
+}
+
+/** A runner that records every argv and answers by the first matching rule. */
+function fakeRun(
+	rules: Array<[(argv: string[]) => boolean, Partial<RunResult>]> = [],
+) {
+	const calls: Call[] = [];
+	const run = async (argv: string[], opts: RunOptions): Promise<RunResult> => {
+		calls.push({ argv, opts });
+		const hit = rules.find(([match]) => match(argv));
+		return {
+			exitCode: 0,
+			signal: null,
+			timedOut: false,
+			outputTail: "",
+			durationMs: 1,
+			...(hit?.[1] ?? {}),
+		};
+	};
+	return { calls, run };
+}
+
+function options(
+	io: Partial<ApplyIO>,
+	over: Partial<ApplyOptions> = {},
+): ApplyOptions {
+	return {
+		yes: true,
+		confirm: async () => {
+			throw new Error("asked under --yes");
+		},
+		env,
+		lockPath: join(root, "cache", "doctor-fix.lock"),
+		// The re-probe answers "present" unless a test is about it: these tests
+		// fake the installers, so nothing they "install" exists on disk.
+		io: {
+			uid: () => 1000,
+			alive: () => false,
+			verify: async ({ requirement }) => present(requirement.name),
+			...io,
+		},
+		...over,
+	};
+}
+
+describe("applyDepsPlan — root", () => {
+	const aptPlan = () => {
+		tool(bin, "apt-get");
+		return planDeps([TMUX, ZSH], [missing("tmux"), missing("zsh")], env);
+	};
+
+	test("sudo -n works: the exact argv, asked once before any step", async () => {
+		tool(bin, "sudo");
+		const { calls, run } = fakeRun();
+		const outcomes = await applyDepsPlan(aptPlan(), options({ run }));
+		const SUDO = ["sudo", "-n", "env", "DEBIAN_FRONTEND=noninteractive"];
+		expect(calls.map((c) => c.argv)).toEqual([
+			["sudo", "-n", "true"],
+			[...SUDO, "dpkg", "--configure", "-a"],
+			[...SUDO, "apt-get", "-o", "DPkg::Lock::Timeout=120", "update"],
+			[
+				...SUDO,
+				"apt-get",
+				"-o",
+				"DPkg::Lock::Timeout=120",
+				"install",
+				"-y",
+				"--no-install-recommends",
+				"tmux",
+				"zsh",
+			],
+		]);
+		// SIGKILL cannot be relayed through sudo: an escalated step gets longer.
+		expect(calls[1]?.opts.killGraceMs).toBe(30_000);
+		expect(outcomes).toMatchObject([
+			{ name: "tmux, zsh", status: "installed" },
+		]);
+	});
+
+	test("uid 0 runs the argv directly, keeping the non-interactive env", async () => {
+		const { calls, run } = fakeRun();
+		await applyDepsPlan(aptPlan(), options({ run, uid: () => 0 }));
+		expect(calls[0]?.argv).toEqual([
+			"env",
+			"DEBIAN_FRONTEND=noninteractive",
+			"dpkg",
+			"--configure",
+			"-a",
+		]);
+	});
+
+	test("no sudo: needs-root, nothing runs, the as-root command is given", async () => {
+		const { calls, run } = fakeRun();
+		const [outcome] = await applyDepsPlan(aptPlan(), options({ run }));
+		expect(calls).toEqual([]);
+		expect(outcome).toMatchObject({
+			status: "needs-root",
+			remedy:
+				"as root: apt-get update && apt-get install -y --no-install-recommends tmux zsh",
+		});
+	});
+
+	test("sudo needs a password: needs-password for every root step, and none ran", async () => {
+		for (const t of ["sudo", "uv", "apt-get"]) tool(bin, t);
+		const plan = planDeps(
+			[TMUX, LIBS],
+			[missing("tmux"), missing("chromium-libs")],
+			env,
+		);
+		const { calls, run } = fakeRun([
+			[(a) => a.join(" ") === "sudo -n true", { exitCode: 1 }],
+		]);
+		const outcomes = await applyDepsPlan(plan, options({ run }));
+		expect(calls.map((c) => c.argv)).toEqual([["sudo", "-n", "true"]]);
+		expect(outcomes.map((o) => o.status)).toEqual([
+			"needs-password",
+			"needs-password",
+		]);
+		expect(outcomes[0]?.remedy).toStartWith(
+			"run: sudo -v   then: magus doctor --fix",
+		);
+		expect(outcomes[0]?.remedy).toContain(
+			"or run yourself: sudo apt-get install -y --no-install-recommends tmux",
+		);
+		expect(outcomes[0]?.remedy).toContain(
+			"not in sudoers? as root: apt-get update &&",
+		);
+		// Run for another directory, the remedy's re-run names it.
+		const [elsewhere] = await applyDepsPlan(
+			planDeps([TMUX], [missing("tmux")], env),
+			options({ run }, { projectDir: "/srv/app" }),
+		);
+		expect(elsewhere?.remedy).toStartWith(
+			"run: sudo -v   then: magus doctor --fix --project /srv/app   ",
+		);
+	});
+});
+
+describe("applyDepsPlan — uv-module", () => {
+	const PY = "/envs/mcp-server-abc/bin/python3";
+
+	test("the script env's interpreter runs the module; root gets the sudo argv after the apt batch", async () => {
+		for (const t of ["sudo", "uv", "apt-get"]) tool(bin, t);
+		const plan = planDeps(
+			[TMUX, LIBS, CHROMIUM],
+			[missing("tmux"), missing("chromium-libs"), missing("chromium")],
+			env,
+		);
+		const { calls, run } = fakeRun([
+			[(a) => a[1] === "python" && a[2] === "find", { outputTail: `${PY}\n` }],
+		]);
+		const outcomes = await applyDepsPlan(plan, options({ run }));
+		expect(outcomes.map((o) => [o.name, o.status])).toEqual([
+			["tmux", "installed"],
+			["chromium-libs", "installed"],
+			["chromium", "installed"],
+		]);
+		const uv = join(bin, "uv");
+		const script = "/plugins/browser-use/scripts/mcp-server.py";
+		const argvs = calls.map((c) => c.argv);
+		const libs = argvs.findIndex((a) => a.includes("install-deps"));
+		expect(argvs.slice(libs - 3, libs + 1)).toEqual([
+			[uv, "sync", "--no-config", "--script", script],
+			[uv, "python", "find", "--no-config", "--script", script],
+			[
+				PY,
+				"-c",
+				"import importlib.util,sys; sys.exit(importlib.util.find_spec(sys.argv[1]) is None)",
+				"playwright",
+			],
+			[
+				"sudo",
+				"-n",
+				"env",
+				"DEBIAN_FRONTEND=noninteractive",
+				PY,
+				"-B",
+				"-m",
+				"playwright",
+				"install-deps",
+				"chromium",
+			],
+		]);
+		// The apt batch ran before it; the browser download, as the user, after.
+		expect(argvs.findIndex((a) => a.includes("dpkg"))).toBeLessThan(libs);
+		expect(argvs.at(-1)).toEqual([
+			PY,
+			"-B",
+			"-m",
+			"playwright",
+			"install",
+			"chromium",
+		]);
+	});
+
+	test("find falling back to the base interpreter fails the guard; nothing runs as root", async () => {
+		for (const t of ["sudo", "uv"]) tool(bin, t);
+		const plan = planDeps([LIBS], [missing("chromium-libs")], env);
+		const { calls, run } = fakeRun([
+			[(a) => a[1] === "python", { outputTail: "/usr/bin/python3.12\n" }],
+			[(a) => a[1] === "-c", { exitCode: 1 }],
+		]);
+		const [outcome] = await applyDepsPlan(plan, options({ run }));
+		expect(outcome?.status).toBe("failed");
+		expect(outcome?.outputTail).toBe(
+			"interpreter /usr/bin/python3.12 cannot import playwright: the script env was not built",
+		);
+		expect(calls.some((c) => c.argv.includes("-m"))).toBe(false);
+	});
+});
+
+describe("applyDepsPlan — release", () => {
+	/** A real .tar.gz holding `entry` as `name` (a file, or a symlink to /bin/sh). */
+	function archive(name: string, entry: "file" | "symlink"): Uint8Array {
+		const src = join(root, "src");
+		mkdirSync(src, { recursive: true });
+		if (entry === "file") {
+			writeFileSync(join(src, name), "#!/bin/sh\necho 2.0.0\n");
+		} else {
+			symlinkSync("/bin/sh", join(src, name));
+		}
+		const out = join(root, "a.tar.gz");
+		const r = Bun.spawnSync(["tar", "-czf", out, "-C", src, name]);
+		if (r.exitCode !== 0) throw new Error("tar failed");
+		return readFileSync(out);
+	}
+	const sha = (b: Uint8Array) => createHash("sha256").update(b).digest("hex");
+	const release = (digest: string) =>
+		dep("tmux-mcp", {
+			via: "release",
+			repo: "MadAppGang/tmux-mcp",
+			tag: "v2.0.0",
+			asset: "tmux-mcp_{os}_{arch}.tar.gz",
+			binary: "tmux-mcp",
+			sha256: { linux_amd64: digest },
+		});
+	const dest = () => join(env.home, ".local", "bin");
+	// The real tar runs: the extraction is part of what is being tested.
+	const realRun = REAL_APPLY_IO.run;
+	const withTar = (): PlanEnv => ({ ...env, path: process.env.PATH ?? "" });
+
+	test("a verified archive installs one executable, by rename, into ~/.local/bin", async () => {
+		const body = archive("tmux-mcp", "file");
+		const plan = planDeps(
+			[release(sha(body))],
+			[missing("tmux-mcp")],
+			withTar(),
+		);
+		const urls: string[] = [];
+		const [outcome] = await applyDepsPlan(
+			plan,
+			options(
+				{
+					run: realRun,
+					download: async (u) => {
+						urls.push(u);
+						return body;
+					},
+				},
+				{ env: withTar() },
+			),
+		);
+		expect(outcome?.status).toBe("installed");
+		expect(urls).toEqual([
+			"https://github.com/MadAppGang/tmux-mcp/releases/download/v2.0.0/tmux-mcp_linux_amd64.tar.gz",
+		]);
+		expect(readdirSync(dest())).toEqual(["tmux-mcp"]);
+		expect(statSync(join(dest(), "tmux-mcp")).mode & 0o777).toBe(0o755);
+	});
+
+	test("a digest mismatch fails closed and writes nothing", async () => {
+		const body = archive("tmux-mcp", "file");
+		const plan = planDeps(
+			[release("b".repeat(64))],
+			[missing("tmux-mcp")],
+			withTar(),
+		);
+		const [outcome] = await applyDepsPlan(
+			plan,
+			options({ run: realRun, download: async () => body }, { env: withTar() }),
+		);
+		expect(outcome?.status).toBe("failed");
+		expect(outcome?.outputTail).toContain("sha256 mismatch");
+		expect(existsSync(dest())).toBe(false);
+	});
+
+	test("a symlink in place of the binary is refused, and nothing is left behind", async () => {
+		const body = archive("tmux-mcp", "symlink");
+		const plan = planDeps(
+			[release(sha(body))],
+			[missing("tmux-mcp")],
+			withTar(),
+		);
+		const [outcome] = await applyDepsPlan(
+			plan,
+			options({ run: realRun, download: async () => body }, { env: withTar() }),
+		);
+		expect(outcome?.status).toBe("failed");
+		expect(outcome?.outputTail).toContain("not a regular file");
+		expect(readdirSync(dest())).toEqual([]);
+	});
+
+	test("a step with no pinned digest for this platform is refused, unrun", async () => {
+		// Selection never picks such an option; a plan carried to another
+		// platform renders it without a digest, and the executor refuses it.
+		const arm = { ...withTar(), arch: "arm64" as const };
+		const plan = planDeps(
+			[release("c".repeat(64))],
+			[missing("tmux-mcp")],
+			arm,
+		);
+		expect(plan.steps[0]?.step).toMatchObject({ kind: "release", sha256: "" });
+		const downloads: string[] = [];
+		const [outcome] = await applyDepsPlan(
+			plan,
+			options(
+				{
+					run: realRun,
+					download: async (u) => {
+						downloads.push(u);
+						return new Uint8Array();
+					},
+				},
+				{ env: arm },
+			),
+		);
+		expect(outcome?.status).toBe("failed");
+		expect(outcome?.outputTail).toBe("no pinned sha256 for this platform");
+		expect(downloads).toEqual([]);
+	});
+});
+
+describe("applyDepsPlan — order, consent, lock", () => {
+	test("a step whose prerequisite did not install is blocked, with the command", async () => {
+		for (const t of ["curl", "unzip", "bash"]) tool(bin, t);
+		const plan = planDeps(
+			[BUN, CLAUDISH],
+			[missing("bun"), missing("claudish")],
+			env,
+		);
+		const outcomes = await applyDepsPlan(
+			plan,
+			options({
+				run: fakeRun([[() => true, { exitCode: 1, outputTail: "boom" }]]).run,
+				download: async () => new TextEncoder().encode("exit 1\n"),
+			}),
+		);
+		expect(outcomes.map((o) => [o.name, o.status])).toEqual([
+			["bun", "failed"],
+			["claudish", "blocked"],
+		]);
+		expect(outcomes[1]?.remedy).toBe(
+			"after bun is installed: bun add -g claudish",
+		);
+	});
+
+	test("without --yes the whole plan is asked once; no means nothing runs", async () => {
+		tool(bin, "bun");
+		const plan = planDeps([CLAUDISH], [missing("claudish")], env);
+		const asked: DepsPlan[] = [];
+		const { calls, run } = fakeRun();
+		const outcomes = await applyDepsPlan(
+			plan,
+			options(
+				{ run },
+				{
+					yes: false,
+					confirm: async (p) => {
+						asked.push(p);
+						return false;
+					},
+				},
+			),
+		);
+		expect(asked).toEqual([plan]);
+		expect(outcomes).toEqual([]);
+		expect(calls).toEqual([]);
+	});
+
+	test("a held lock refuses a second apply; a stale one is taken over and released", async () => {
+		tool(bin, "bun");
+		const plan = planDeps([CLAUDISH], [missing("claudish")], env);
+		const lock = join(root, "cache", "doctor-fix.lock");
+		mkdirSync(join(root, "cache"));
+		writeFileSync(lock, "4242");
+		await expect(
+			applyDepsPlan(
+				plan,
+				options({ run: fakeRun().run, alive: (pid) => pid === 4242 }),
+			),
+		).rejects.toBeInstanceOf(DepsLockBusy);
+		expect(readFileSync(lock, "utf8")).toBe("4242");
+
+		const outcomes = await applyDepsPlan(
+			plan,
+			options({ run: fakeRun().run, alive: () => false }),
+		);
+		expect(outcomes[0]?.status).toBe("installed");
+		expect(existsSync(lock)).toBe(false);
+	});
+
+	test("events: start, output, end — and the runner's output never reaches the terminal", async () => {
+		tool(bin, "bun");
+		const plan = planDeps([CLAUDISH], [missing("claudish")], env);
+		const events: string[] = [];
+		await applyDepsPlan(
+			plan,
+			options(
+				{
+					run: async (_argv, opts) => {
+						opts.onOutput?.("installing…\n");
+						return {
+							exitCode: 0,
+							signal: null,
+							timedOut: false,
+							outputTail: "installing…",
+							durationMs: 1,
+						};
+					},
+				},
+				{ onEvent: (e) => events.push(e.type) },
+			),
+		);
+		expect(events).toEqual(["step-start", "output", "step-end"]);
+	});
+});
+
+describe("applyDepsPlan — installed means the re-probe found it", () => {
+	const realVerify = REAL_APPLY_IO.verify;
+	const dest = () => join(env.home, ".local", "bin");
+	const body = new TextEncoder().encode("#!/bin/sh\necho 10.3.0\n");
+	const sha = (b: Uint8Array) => createHash("sha256").update(b).digest("hex");
+	/** claudish's shape: a bare binary per platform, x64 spelled its own way. */
+	const bare = dep(
+		"claudish",
+		{
+			via: "release",
+			repo: "MadAppGang/claudish",
+			tag: "v10.3.0",
+			asset: "claudish-{os}-{arch}",
+			binary: "claudish",
+			arch: { amd64: "x64" },
+			sha256: { linux_amd64: sha(body) },
+		},
+		"claudish@magus",
+	);
+
+	test("a bare-binary release lands as the binary itself, and the probe then finds it", async () => {
+		const onPathEnv: PlanEnv = { ...env, path: `${dest()}:${bin}` };
+		const plan = planDeps([bare], [missing("claudish")], onPathEnv);
+		expect(plan.steps[0]?.step).toMatchObject({
+			kind: "release",
+			format: "binary",
+		});
+		const urls: string[] = [];
+		const [outcome] = await applyDepsPlan(
+			plan,
+			options(
+				{
+					verify: realVerify,
+					download: async (u) => {
+						urls.push(u);
+						return body;
+					},
+				},
+				{ env: onPathEnv },
+			),
+		);
+		expect(urls).toEqual([
+			"https://github.com/MadAppGang/claudish/releases/download/v10.3.0/claudish-linux-x64",
+		]);
+		expect(outcome?.status).toBe("installed");
+		expect(readdirSync(dest())).toEqual(["claudish"]);
+		expect(readFileSync(join(dest(), "claudish"), "utf8")).toBe(
+			new TextDecoder().decode(body),
+		);
+		expect(statSync(join(dest(), "claudish")).mode & 0o777).toBe(0o755);
+	});
+
+	test("landed in ~/.local/bin, which is off PATH: off-path, with the directory and the rc line — never installed", async () => {
+		const plan = planDeps([bare], [missing("claudish")], env);
+		const outcomes = await applyDepsPlan(
+			plan,
+			options({ verify: realVerify, download: async () => body }),
+		);
+		expect(outcomes[0]).toMatchObject({
+			name: "claudish",
+			status: "off-path",
+			dir: "~/.local/bin",
+			remedy:
+				'add  export PATH="$HOME/.local/bin:$PATH"  to ~/.zshrc, then restart Claude Code from a new terminal',
+		});
+		const text = renderApplyText(outcomes).join("\n");
+		expect(text).not.toContain("✓");
+		expect(text).toContain("⚠ claudish");
+		expect(text).toContain("NEEDS YOU");
+	});
+
+	test("bun add -g that followed XDG_CACHE_HOME off PATH: off-path names bun's own global bin dir", async () => {
+		tool(bin, "bun");
+		const xdgBin = join(root, "xdg-cache", ".bun", "bin");
+		const viaBun = dep(
+			"claudish",
+			{ via: "bun", package: "claudish" },
+			"claudish@magus",
+		);
+		const plan = planDeps([viaBun], [missing("claudish")], env);
+		const calls: string[][] = [];
+		const run = async (argv: string[]): Promise<RunResult> => {
+			calls.push(argv.slice(1));
+			if (argv[1] === "add") tool(xdgBin, "claudish");
+			return {
+				exitCode: 0,
+				signal: null,
+				timedOut: false,
+				outputTail: argv[1] === "pm" ? `${xdgBin}\n` : "installed claudish",
+				durationMs: 1,
+			};
+		};
+		const [outcome] = await applyDepsPlan(
+			plan,
+			options({ run, verify: realVerify }),
+		);
+		expect(calls).toEqual([
+			["add", "-g", "claudish"],
+			["pm", "bin", "-g"],
+		]);
+		expect(outcome).toMatchObject({
+			status: "off-path",
+			dir: xdgBin,
+			remedy: `add  export PATH="${xdgBin}:$PATH"  to ~/.zshrc, then restart Claude Code from a new terminal`,
+		});
+	});
+
+	test("an installer that exits 0 and leaves nothing behind is failed, saying so", async () => {
+		tool(bin, "bun");
+		const viaBun = dep(
+			"claudish",
+			{ via: "bun", package: "claudish" },
+			"claudish@magus",
+		);
+		const plan = planDeps([viaBun], [missing("claudish")], env);
+		const [outcome] = await applyDepsPlan(
+			plan,
+			options({ run: fakeRun().run, verify: realVerify }),
+		);
+		expect(outcome?.status).toBe("failed");
+		expect(outcome?.outputTail).toContain(
+			"claudish: the installer exited 0, but `claudish --version` still fails",
+		);
+		expect(outcome?.remedy).toBe("bun add -g claudish");
+	});
+
+	test("the merged apt step re-probes every requirement it installs", async () => {
+		tool(bin, "apt-get");
+		const plan = planDeps([TMUX, ZSH], [missing("tmux"), missing("zsh")], env);
+		const probed: string[] = [];
+		const [outcome] = await applyDepsPlan(
+			plan,
+			options({
+				run: fakeRun().run,
+				uid: () => 0,
+				verify: async ({ requirement }) => {
+					probed.push(requirement.name);
+					return requirement.name === "zsh"
+						? missing("zsh")
+						: present(requirement.name);
+				},
+			}),
+		);
+		expect(probed).toEqual(["tmux", "zsh"]);
+		expect(outcome?.status).toBe("failed");
+		expect(outcome?.outputTail).toContain("zsh: the installer exited 0");
+	});
+});