magus-cli 7.8.0 → 7.9.0

package/src/services/toolchain.ts

@@ -1,16 +1,28 @@
 /**
- * Toolchain detection + bootstrap for the package managers a profile's binary
- * deps need (bun, brew, npm, pip, go).
+ * The commands that install, upgrade, pin and remove a version-managed tool
+ * (bun, brew, npm, pip, go), and the bridge between a requirement and that
+ * version-managed view.
  *
- * `magus install` requires whatever installers the resolved closure uses. In
- * source form bun is already guaranteed (bin/magus.js hard-exits without it),
- * but once magus ships as a compiled binary an end user may lack bun — so bun
- * is treated as a bootstrappable toolchain exactly like brew.
+ * Installing a requirement goes through requires-probe's `renderInstall` and
+ * the deps executor (`services/deps-plan.ts`); this module builds only what
+ * `magus update` and the CLI Tools screen run beyond a first install.
  */
 
-import type { BinInstaller, ResolvedBin } from "../types/index.js";
+import {
+	type InstallOption,
+	assertNever,
+	currentPlatform,
+	renderInstall,
+} from "../shared/plugin/hooks/lib/requires-probe.js";
+import type {
+	BinInstaller,
+	ManagedBin,
+	ManagedTool,
+	ResolvedBin,
+	SelectedBin,
+} from "../types/index.js";
 import type { Command } from "../utils/command-utils.js";
-import { which, whichSync } from "../utils/command-utils.js";
+import { whichSync } from "../utils/command-utils.js";
 
 // -- Python CLI applications -------------------------------------------------
 
@@ -160,125 +172,119 @@ export function resetPythonCliInstallerMemo(): void {
 }
 
 // ----------------------------------------------------------------------------
+//
+// The version-managed view of a requirement.
+//
+// A requirement (plugin `requires`, or a profile cliTool mapped onto the
+// profile-only kinds) is installed by requires-probe's `renderInstall` and the
+// deps executor. `magus update` and the CLI Tools screen additionally track
+// the installed VERSION of the kinds that have one — bun, brew, npm, pip, go —
+// and they work in the {@link ManagedTool} shape. These functions are the one
+// bridge between the two, in both directions.
 
-/**
- * The executable that proves a toolchain is installed.
- *
- * `pip` is deliberately absent: which executable proves it depends on the
- * machine, so it is resolved by {@link resolvePythonCliInstaller} instead.
- */
-const TOOLCHAIN_PROBE: Record<Exclude<BinInstaller, "pip">, string> = {
-	bun: "bun",
-	brew: "brew",
-	npm: "npm",
-	go: "go",
-};
-
-/** The executable whose presence proves `name` is usable. */
-function toolchainProbe(name: BinInstaller): string {
-	return name === "pip"
-		? resolvePythonCliInstaller().probe
-		: TOOLCHAIN_PROBE[name];
-}
-
-/** Official one-line bootstrap for the toolchains magus will install. */
-export const TOOLCHAIN_BOOTSTRAP: Partial<Record<BinInstaller, string>> = {
-	bun: "curl -fsSL https://bun.sh/install | bash",
-	brew: '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
-};
-
-export interface ToolchainStatus {
-	name: BinInstaller;
-	present: boolean;
-	/** Binary names in the closure that need this toolchain. */
-	requiredBy: string[];
-	/** Bootstrap command, when magus can install this toolchain itself. */
-	bootstrap?: string;
-}
-
-/** Is a given toolchain available on PATH? */
-export async function isToolchainPresent(name: BinInstaller): Promise<boolean> {
-	return (await which(toolchainProbe(name))) !== null;
-}
+const pinned = (version: string | undefined) => (version ? { version } : {});
 
 /**
- * Determine which toolchains a resolved closure's binary deps require, and
- * whether each is present. Only toolchains actually needed are returned.
+ * The version-managed view of a selected requirement, or null when its chosen
+ * option is not one of the {@link BinInstaller} kinds (apt, release,
+ * bootstrap, uv-script, uv-module: their version is the declaration's, and
+ * `magus doctor --fix` installs them).
  */
-export async function detectToolchains(
-	bins: ResolvedBin[],
-): Promise<ToolchainStatus[]> {
-	const requiredBy = new Map<BinInstaller, string[]>();
-	for (const bin of bins) {
-		const list = requiredBy.get(bin.via) ?? [];
-		list.push(bin.name);
-		requiredBy.set(bin.via, list);
+export function managedTool(bin: SelectedBin): ManagedTool | null {
+	const option = bin.chosen;
+	if (!option) return null;
+	const check = bin.check.join(" ");
+	switch (option.via) {
+		case "bun":
+		case "npm":
+		case "pip":
+			return {
+				name: bin.name,
+				via: option.via,
+				package: option.package,
+				check,
+				...pinned(option.version),
+			};
+		case "go":
+			return {
+				name: bin.name,
+				via: "go",
+				module: option.package,
+				check,
+				...pinned(option.version),
+			};
+		case "brew":
+			// A cask is installed, upgraded and removed with `--cask`, which the
+			// version-managed view does not speak: its declaration manages it.
+			return option.cask !== undefined
+				? null
+				: { name: bin.name, via: "brew", formula: option.formula, check };
+		case "apt":
+		case "release":
+		case "bootstrap":
+		case "uv-script":
+		case "uv-module":
+			return null;
+		default:
+			return assertNever(option);
 	}
+}
 
-	const statuses: ToolchainStatus[] = [];
-	for (const [name, names] of requiredBy) {
-		statuses.push({
-			name,
-			present: await isToolchainPresent(name),
-			requiredBy: names,
-			bootstrap: TOOLCHAIN_BOOTSTRAP[name],
-		});
+/** {@link managedTool} over a closure's bins, keeping each one's provenance. */
+export function managedBins(bins: readonly ResolvedBin[]): ManagedBin[] {
+	const out: ManagedBin[] = [];
+	for (const bin of bins) {
+		const tool = managedTool(bin);
+		if (tool) out.push({ ...tool, sources: [...bin.sources] });
 	}
-	// Stable order: bun, brew, npm, pip, go.
-	const order: BinInstaller[] = ["bun", "brew", "npm", "pip", "go"];
-	statuses.sort((a, b) => order.indexOf(a.name) - order.indexOf(b.name));
-	return statuses;
+	return out;
 }
 
-/**
- * The install command for a single binary requirement.
- *
- * `python` is injectable so tests can pin one and stay machine-independent —
- * the default depends on what is on PATH, so an assertion against a literal
- * `uv tool …` would pass here and fail on a runner without uv.
- *
- * `pkg@version` and `pkg==version` are each ONE argv token. That join is
- * precisely where a string was dangerous: `bin.package` is hand-authored
- * profile/marketplace data, and under a shell a space or a `;` in it would have
- * become extra words. Here it cannot.
- */
-export function binInstallCommand(
-	bin: {
-		name: string;
-		via: BinInstaller;
-		package?: string;
-		formula?: string;
-		module?: string;
-		version?: string;
-	},
-	python: PythonCliInstaller = resolvePythonCliInstaller(),
-): Command {
-	const pkg = bin.package ?? bin.name;
-	const at = bin.version ? `@${bin.version}` : "";
-	switch (bin.via) {
+/** The install option a {@link ManagedTool} stands for. */
+export function managedOption(t: ManagedTool): InstallOption {
+	switch (t.via) {
+		case "brew":
+			return { via: "brew", formula: t.formula ?? t.name };
+		case "go":
+			return { via: "go", package: t.module ?? t.name, ...pinned(t.version) };
 		case "bun":
-			return { cmd: "bun", args: ["install", "-g", `${pkg}${at}`] };
 		case "npm":
-			return { cmd: "npm", args: ["install", "-g", `${pkg}${at}`] };
 		case "pip":
-			return python.install(pkg, bin.version);
-		case "brew":
-			return { cmd: "brew", args: ["install", bin.formula ?? bin.name] };
-		case "go":
 			return {
-				cmd: "go",
-				args: [
-					"install",
-					`${bin.module ?? bin.name}@${bin.version ?? "latest"}`,
-				],
+				via: t.via,
+				package: t.package ?? t.name,
+				...pinned(t.version),
 			};
+		default:
+			return assertNever(t.via);
+	}
+}
+
+/**
+ * The command that installs a {@link ManagedTool}, rendered by requires-probe's
+ * `renderInstall` — the one renderer every install goes through — so the pin
+ * travels in the same token (`pkg@version`, `pkg==version`) it does there.
+ */
+export function managedInstallCommand(t: ManagedTool): Command {
+	const step = renderInstall(
+		{ name: t.name, check: [], install: [] },
+		managedOption(t),
+		{
+			...(currentPlatform() ?? { os: "linux", arch: "amd64" }),
+			pluginRoot: "",
+		},
+	);
+	if (step.kind !== "argv") {
+		throw new Error(`${t.via} renders a ${step.kind} step, not a command`);
 	}
+	const [cmd = "", ...args] = step.argv;
+	return { cmd, args };
 }
 
 /**
  * The command that advances an ALREADY-INSTALLED binary to the newest version.
  *
- * Distinct from {@link binInstallCommand} because two of the five installers
+ * Distinct from {@link managedInstallCommand} because two of the five installers
  * treat "install" as a no-op once the package is present: `brew install` on an
  * installed formula prints "already installed" and changes nothing, and `pip
  * install` without `--upgrade` does the same. Reusing the install command for
@@ -363,7 +369,7 @@ export function claudeNativeUpgradeCommand(pin?: string): Command {
  * {@link binUpgradeCommand} goes to the newest version, past the pin, and a
  * plain `uv tool install pkg==v` is a no-op once any version is installed.
  *
- * bun, npm and go take the version in the same token `binInstallCommand` builds
+ * bun, npm and go take the version in the same token `managedInstallCommand` builds
  * (`pkg@v`), and each replaces an installed version with it. pip goes through
  * the resolved installer's own `pin`. brew installs only its newest version, so
  * there is nothing to return — the planner never asks for it (a brew pin below
@@ -387,7 +393,7 @@ export function binPinCommand(
 		case "bun":
 		case "npm":
 		case "go":
-			return binInstallCommand(bin, python);
+			return managedInstallCommand(bin);
 		case "pip":
 			return python.pin(bin.package ?? bin.name, bin.version);
 		case "brew":
@@ -405,7 +411,7 @@ export function binPinCommand(
  * `bun install -g pkg@latest` and left the tool permanently ahead of its pin,
  * a state magus cannot leave. Both now come through here.
  *
- * `install` → {@link binInstallCommand} (which appends the pin, when there is
+ * `install` → {@link managedInstallCommand} (which appends the pin, when there is
  * one). An upgrade whose target IS the pin → {@link binPinCommand}, because
  * {@link binUpgradeCommand} would overshoot it. Any other upgrade → the newest
  * version.
@@ -426,7 +432,7 @@ export function binCommandForState(
 	},
 	python: PythonCliInstaller = resolvePythonCliInstaller(),
 ): Command | null {
-	if (state === "install") return binInstallCommand(bin, python);
+	if (state === "install") return managedInstallCommand(bin);
 	if (bin.version && target === bin.version) return binPinCommand(bin, python);
 	return binUpgradeCommand(bin, python);
 }

package/src/services/update-engine.ts

@@ -20,7 +20,7 @@
  * So the engine lives here, in `services/`, and both front ends drive it.
  * `cli/` and `ui/` are sibling presentation layers: they own how progress looks
  * and nothing else. Everything IO-shaped is injected — `PluginApplyDeps` for
- * the five Claude Code calls, `ApplyReporter` for progress, `runCommand` for
+ * the five Claude Code calls, `ApplyReporter` for progress, `runArgv` for
  * installers — so the same code drives an animated terminal meter, a TUI modal,
  * and a test that wants silence.
  *
@@ -32,13 +32,13 @@
 import path from "node:path";
 import type {
 	InstalledPluginEntry,
+	ManagedBin,
 	ProfileSkillRef,
-	ResolvedBin,
 	SkillInfo,
 } from "../types/index.js";
 import type { Command } from "../utils/command-utils.js";
 import { formatCommand } from "../utils/command-utils.js";
-import { runCommand } from "../utils/run.js";
+import { runArgv, succeeded } from "../utils/run.js";
 import type { PluginScope } from "./claude-cli.js";
 import {
 	installPlugin,
@@ -158,10 +158,10 @@ export interface ApplyReporter {
 	/**
 	 * Run `work` with the terminal released.
 	 *
-	 * A binary upgrade spawns `brew`/`uv` with inherited stdio: it writes and
-	 * moves the cursor itself, so any animated block must be erased first or the
-	 * two interleave into garbage. A TUI implementation suspends its renderer;
-	 * a silent one just awaits.
+	 * The installer's output is captured (`runArgv`), so nothing a child
+	 * prints reaches the terminal; an implementation pauses its animation for
+	 * the duration only so the meter does not tick over a step that has no
+	 * progress of its own to show. A silent one just awaits.
 	 */
 	detach<T>(work: () => Promise<T>): Promise<T>;
 }
@@ -1128,7 +1128,7 @@ export async function updatePluginInScope(
  */
 export function binCommandFor(
 	item: BinUpdateItem,
-	spec: ResolvedBin,
+	spec: ManagedBin,
 ): Command | null {
 	if (!binNeedsWork(item)) return null;
 	if (item.action === "upgrade" && item.upgradeCommand)
@@ -1185,7 +1185,14 @@ function binNoMove(item: BinUpdateItem, after: ToolFacts): string | null {
  * which R6 counts as changed — the safe answer, but never "no change — still
  * 3.7c", the one the user needs.
  */
-const REAL_READ_BACK = (spec: ResolvedBin): Promise<ToolFacts> =>
+/** How long one `magus update` installer may run before it is stopped. */
+const INSTALLER_TIMEOUT_MS = 15 * 60_000;
+
+/** The default installer runner: argv, output captured, true on success. */
+const runInstaller = async (command: Command): Promise<boolean> =>
+	succeeded(await runArgv(command, { timeoutMs: INSTALLER_TIMEOUT_MS }));
+
+const REAL_READ_BACK = (spec: ManagedBin): Promise<ToolFacts> =>
 	probeTool(spec, undefined, { allowCheckCommand: true });
 
 export async function applyBins(
@@ -1195,9 +1202,9 @@ export async function applyBins(
 	// profile-supplied package name reach `/bin/sh`: a seam called "shell" reads
 	// as an invitation to hand it a string. It takes argv, and nothing here
 	// builds a shell line.
-	run: (command: Command) => Promise<boolean> = runCommand,
+	run: (command: Command) => Promise<boolean> = runInstaller,
 	/** Read-back seam: re-probe ONE tool after its installer ran. */
-	probe: (spec: ResolvedBin) => Promise<ToolFacts> = REAL_READ_BACK,
+	probe: (spec: ManagedBin) => Promise<ToolFacts> = REAL_READ_BACK,
 ): Promise<ApplyResult> {
 	const result: ApplyResult = { ok: 0, failed: [], unchanged: [] };
 	for (const item of plan.bins) {
@@ -1222,8 +1229,6 @@ export async function applyBins(
 			result.failed.push(item.name);
 			continue;
 		}
-		// The installer owns the terminal for the duration: it streams its own
-		// output through inherited stdio.
 		const succeeded = await report.detach(() => run(cmd));
 		if (!succeeded) {
 			report.finish(
@@ -1315,7 +1320,7 @@ export interface ApplyPlanOptions {
 	/** Installer execution seam — see the note on {@link applyBins}. */
 	run?: (command: Command) => Promise<boolean>;
 	/** Read-back seam — see {@link applyBins}. Default: `probeTool(spec)`. */
-	probe?: (spec: ResolvedBin) => Promise<ToolFacts>;
+	probe?: (spec: ManagedBin) => Promise<ToolFacts>;
 }
 
 /**

package/src/services/update-plan.ts

@@ -28,7 +28,7 @@
  * (`unknown`) rather than folding into `current`.
  */
 
-import type { ProfileSkillRef, ResolvedBin } from "../types/index.js";
+import type { ManagedBin, ProfileSkillRef } from "../types/index.js";
 import type { Command } from "../utils/command-utils.js";
 import type { PluginScope } from "./claude-cli.js";
 import {
@@ -1061,7 +1061,7 @@ export interface BinUpdateItem {
  * that is `unknown` too — "not checked" is not "fine".
  */
 export function planBinUpdates(
-	bins: ResolvedBin[],
+	bins: ManagedBin[],
 	facts: readonly ToolFacts[],
 ): BinUpdateItem[] {
 	const byName = new Map(facts.map((f) => [f.name, f]));
@@ -1147,7 +1147,7 @@ export interface UpdatePlan {
 	 * only the decision; the installer command needs `via`/`package`/`formula`,
 	 * and re-deriving those from a name would guess.
 	 */
-	binSpecs: Map<string, ResolvedBin>;
+	binSpecs: Map<string, ManagedBin>;
 }
 
 /**

package/src/shared/plugin/hooks/bun-missing.sh

@@ -0,0 +1,39 @@
+#!/bin/sh
+# SessionStart (matcher `startup`) fallback for deps-check.ts. The registration
+# runs this only when Bun is not on the PATH Claude Code started with, which is
+# the one dependency the TypeScript check cannot report itself. $1 is the label.
+#
+# Writes the same ledger as deps-check.ts: seen/<label> = sh, then claims the
+# Bun requirement's dedupe key, so a session prints one Bun line however many
+# plugins carry this file. scripts/check-hook-copies.ts recomputes that key, the
+# install line and the PATH lines from lib/requires-probe.ts and fails when this
+# file disagrees. Exit 0 always.
+
+label=$1
+case $label in
+'' | *[!a-z0-9._-]*) exit 0 ;;
+esac
+key=bun-3182ab42b0f1
+
+sid=$(cat 2>/dev/null | tr -d '\n' | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([A-Za-z0-9_-]*\)".*/\1/p')
+if [ -n "$sid" ]; then
+	base=${TMPDIR:-/tmp}
+	dir=$base/magus-deps-$sid
+	if mkdir -p "$dir/seen" "$dir/claimed" 2>/dev/null; then
+		printf sh >"$dir/seen/$label" 2>/dev/null
+		find "$base" -maxdepth 1 -type d -name 'magus-deps-*' -mtime +0 -exec rm -rf {} + 2>/dev/null
+		mkdir "$dir/claimed/$key" 2>/dev/null || exit 0
+	fi
+fi
+
+if [ -x "$HOME/.bun/bin/bun" ]; then
+	case ${SHELL:-} in
+	*zsh) rc='~/.zshrc' line='export PATH=\"$HOME/.bun/bin:$PATH\"' ;;
+	*fish) rc='~/.config/fish/config.fish' line='fish_add_path $HOME/.bun/bin' ;;
+	*) rc='~/.bashrc' line='export PATH=\"$HOME/.bun/bin:$PATH\"' ;;
+	esac
+	printf '{"systemMessage":"magus-deps: Bun is installed at ~/.bun/bin but is not on the PATH Claude Code started with, so magus hooks and MCP servers cannot run (noticed by %s).\\n  Add %s to %s, then restart Claude Code from a new terminal."}\n' "$label" "$line" "$rc"
+else
+	printf '{"systemMessage":"magus-deps: Bun is missing — magus hooks and MCP servers need it (noticed by %s).\\n  Install: curl -fsSL https://bun.sh/install | bash, then restart Claude Code from a new terminal."}\n' "$label"
+fi
+exit 0

package/src/shared/plugin/hooks/deps-check.ts

@@ -0,0 +1,224 @@
+#!/usr/bin/env bun
+/**
+ * SessionStart (matcher `startup`) — say loudly what this plugin needs and does
+ * not have. `argv[2]` is the plugin's label; the registration passes it.
+ *
+ * Reads the plugin's own `.claude-plugin/plugin.json` through
+ * lib/requires-probe.ts, probes each requirement at presence depth (a PATH
+ * lookup for a check that runs the requirement's own binary, the declared check
+ * for every other), and prints a `systemMessage` carrying the `magus-deps` marker when something is
+ * missing or off PATH. Prints nothing when healthy. Its "Fix all" line runs
+ * doctor with `--project <cwd>`, the session's directory from the hook input:
+ * doctor reads the plugins enabled in the project it checks, and the banner is
+ * read in a terminal that may be anywhere.
+ *
+ * THE LEDGER. Every copy writes `$TMPDIR/magus-deps-<session_id>/seen/<label>`
+ * (`ts` here, `sh` from bun-missing.sh), then claims each dep it reports with an
+ * atomic `mkdir claimed/<dedupeKey>`. A failed mkdir means another plugin's copy
+ * reports that dep this session, so one dep is one banner line however many
+ * plugins need it. An unreadable session id means no ledger and no claims:
+ * more banners, never fewer. Ledgers older than a day are pruned on write.
+ *
+ * Exit 0 always. A watchdog keeps the hook inside its registration timeout.
+ */
+
+import {
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	type Presence,
+	applicable,
+	currentPlatform,
+	dedupeKey,
+	onPath,
+	parseRequires,
+	probe,
+	renderFix,
+} from "./lib/requires-probe.js";
+
+const WATCHDOG_MS = 8_000;
+const CHECK_CAP_MS = 3_000;
+const STDIN_MS = 1_000;
+const LEDGER_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const SESSION_RE = /^[A-Za-z0-9_-]+$/;
+
+const hasControlChar = (s: string): boolean =>
+	[...s].some((c) => {
+		const code = c.charCodeAt(0);
+		return code < 0x20 || code === 0x7f;
+	});
+
+const quiet = (): never => process.exit(0);
+setTimeout(quiet, WATCHDOG_MS).unref();
+process.on("uncaughtException", quiet);
+process.on("unhandledRejection", quiet);
+
+interface HookInput {
+	/** Null when unreadable: no ledger, so more banners, never fewer. */
+	session: string | null;
+	/** The directory the session runs in; null leaves `--project` off the fix. */
+	cwd: string | null;
+}
+
+async function readHookInput(): Promise<HookInput> {
+	const chunks: Buffer[] = [];
+	const read = (async () => {
+		for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+	})();
+	await Promise.race([read, new Promise((r) => setTimeout(r, STDIN_MS))]);
+	try {
+		const input = JSON.parse(Buffer.concat(chunks).toString("utf8")) as {
+			session_id?: unknown;
+			cwd?: unknown;
+		};
+		const id = input.session_id;
+		const cwd = input.cwd;
+		return {
+			session: typeof id === "string" && SESSION_RE.test(id) ? id : null,
+			// A control character would break the banner line it is printed in.
+			cwd:
+				typeof cwd === "string" && isAbsolute(cwd) && !hasControlChar(cwd)
+					? cwd
+					: null,
+		};
+	} catch {
+		return { session: null, cwd: null };
+	}
+}
+
+function pruneOldLedgers(base: string): void {
+	try {
+		for (const entry of readdirSync(base)) {
+			if (!entry.startsWith("magus-deps-")) continue;
+			const dir = join(base, entry);
+			if (Date.now() - statSync(dir).mtimeMs > LEDGER_MAX_AGE_MS) {
+				rmSync(dir, { recursive: true, force: true });
+			}
+		}
+	} catch {
+		// Pruning is housekeeping; a failure costs nothing now.
+	}
+}
+
+/** The ledger directory, with `seen/<label>` written, or null without a session. */
+function openLedger(hookSession: string | null, label: string): string | null {
+	if (!hookSession) return null;
+	const base = process.env.TMPDIR || tmpdir();
+	const dir = join(base, `magus-deps-${hookSession}`);
+	try {
+		mkdirSync(join(dir, "seen"), { recursive: true });
+		mkdirSync(join(dir, "claimed"), { recursive: true });
+		writeFileSync(join(dir, "seen", label), "ts");
+	} catch {
+		return null;
+	}
+	pruneOldLedgers(base);
+	return dir;
+}
+
+/** True when this copy is the one to report `key` this session. */
+function claim(ledger: string | null, key: string): boolean {
+	if (!ledger) return true;
+	try {
+		mkdirSync(join(ledger, "claimed", key));
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== "EEXIST";
+	}
+}
+
+function emit(systemMessage: string, additionalContext: string): void {
+	process.stdout.write(
+		`${JSON.stringify({
+			systemMessage,
+			hookSpecificOutput: {
+				hookEventName: "SessionStart",
+				additionalContext,
+			},
+		})}\n`,
+	);
+}
+
+async function main(): Promise<void> {
+	const label = process.argv[2] ?? "";
+	if (!/^[a-z0-9][a-z0-9._-]*$/.test(label)) return;
+	const pluginRoot =
+		process.env.CLAUDE_PLUGIN_ROOT ||
+		dirname(dirname(fileURLToPath(import.meta.url)));
+	const input = await readHookInput();
+	const ledger = openLedger(input.session, label);
+
+	const manifest = JSON.parse(
+		readFileSync(join(pluginRoot, ".claude-plugin", "plugin.json"), "utf8"),
+	) as unknown;
+	const parsed = parseRequires(manifest);
+	if (!parsed.ok) {
+		if (claim(ledger, `invalid-${label}`)) {
+			emit(
+				`magus-deps · ${label}: requires is invalid (${parsed.errors.join("; ")}) — please report`,
+				`${label}'s dependency declaration is invalid`,
+			);
+		}
+		return;
+	}
+	const platform = currentPlatform();
+	if (!platform) return;
+	const reqs = applicable(parsed.requirements, platform.os);
+	if (reqs.length === 0) return;
+
+	const env = {
+		pluginRoot,
+		...platform,
+		home: process.env.HOME || homedir(),
+		path: process.env.PATH ?? "",
+		capMs: CHECK_CAP_MS,
+		depth: "presence" as const,
+		userShell: process.env.SHELL ?? "",
+	};
+	const presences = await probe(reqs, env);
+	const reportable = (p: Presence) =>
+		p.status === "missing" || p.status === "off-path";
+	if (!presences.some(reportable)) return;
+
+	const byName = new Map(reqs.map((r) => [r.name, r]));
+	const claimed = (p: Presence) => {
+		const r = byName.get(p.name);
+		return r !== undefined && claim(ledger, dedupeKey(r));
+	};
+	const findings = presences.filter((p) => reportable(p) && claimed(p));
+	if (findings.length === 0) return;
+	const slow = presences.filter((p) => p.status === "unknown" && claimed(p));
+	const mine = [...findings, ...slow];
+	const message = renderFix(
+		label,
+		mine,
+		reqs,
+		env,
+		onPath("magus", env.path) !== null,
+		input.cwd,
+	);
+	if (message === null) return;
+	const failing = findings
+		.map((p) => p.name)
+		.sort()
+		.join(", ");
+	emit(
+		message,
+		`${label}'s MCP servers and hooks will fail until these are installed: ${failing}`,
+	);
+}
+
+try {
+	await main();
+} catch {
+	// A hook that cannot tell has nothing useful to print.
+}
+process.exit(0);