magus-cli 7.10.4 → 7.11.0

package/src/cli/deps-view.ts

@@ -18,7 +18,7 @@ import {
 	requiredByOf,
 } from "../services/deps-plan.js";
 import type { DepsState } from "../services/deps-report.js";
-import { installText } from "../services/doctor-bins.js";
+import { installReason, installText } from "../services/doctor-bins.js";
 import {
 	type Os,
 	type Presence,
@@ -33,6 +33,8 @@ function presenceLine(name: string, p: Presence, by: string): string | null {
 			return null;
 		case "missing":
 			return `  ✗ ${name} — missing${p.blockedBy ? ` (needs ${p.blockedBy} first)` : ""}  (${by})`;
+		case "outdated":
+			return `  ✗ ${name} — outdated: ${p.found}, needs ${p.minVersion} or later  (${by})`;
 		case "off-path":
 			return `  ⚠ ${name} — installed in ${p.prefix}, which is not on the PATH Claude Code starts with  (${by})`;
 		case "unknown":
@@ -57,8 +59,8 @@ export function depsSectionLines(
 		const line = presenceLine(bin.name, p, requiredByOf(bin).join(", "));
 		if (!line) return;
 		lines.push(line);
-		if (p.status === "missing")
-			lines.push(`      fix: ${installText(bin, env)}`);
+		if (p.status === "missing" || p.status === "outdated")
+			lines.push(`      fix: ${installText(bin, env, installReason(p))}`);
 		if (p.status === "off-path") unfixable++;
 	});
 	for (const problem of collected.problems) {

package/src/services/deps-plan.ts

@@ -1,7 +1,8 @@
 /**
  * The one installer executor: plan what is missing, then install it.
  *
- * `planDeps` turns the requirements a probe found missing into ordered steps,
+ * `planDeps` turns the requirements a probe found missing or outdated 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`),
@@ -42,6 +43,7 @@ import {
 	BUN_PREFIX,
 	type Bootstrap,
 	type BootstrapTool,
+	type InstallReason,
 	type InstallStep,
 	LOCAL_PREFIX,
 	type Os,
@@ -240,10 +242,11 @@ function fromMagusMarketplace(bin: ResolvedBin): boolean {
 }
 
 /**
- * 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.
+ * The steps that install every `missing` requirement and replace every
+ * `outdated` one, 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, or one that printed no version) is left alone.
  */
 export function planDeps(
 	bins: ResolvedBin[],
@@ -253,10 +256,11 @@ export function planDeps(
 	const unfixable: DepsPlan["unfixable"] = [];
 	/** The prefixes off the PATH, in the order they came up. */
 	const offPathPrefixes = new Set<UserPrefix>();
-	const missing: ResolvedBin[] = [];
+	const missing: { bin: ResolvedBin; reason: InstallReason }[] = [];
 	bins.forEach((bin, i) => {
 		const p = presence[i];
-		if (p?.status === "missing") missing.push(bin);
+		if (p?.status === "missing") missing.push({ bin, reason: "missing" });
+		if (p?.status === "outdated") missing.push({ bin, reason: "outdated" });
 		if (p?.status === "off-path") offPathPrefixes.add(p.prefix);
 	});
 
@@ -285,7 +289,7 @@ export function planDeps(
 		pluginRoot: bin.root ?? "",
 	});
 
-	for (const bin of missing) {
+	for (const { bin, reason } of missing) {
 		const option = bin.chosen;
 		if (!option) {
 			unfixable.push({
@@ -294,11 +298,12 @@ export function planDeps(
 			});
 			continue;
 		}
-		const step = renderInstall(bin, option, {
-			os: env.os,
-			arch: env.arch,
-			pluginRoot: bin.root ?? "",
-		});
+		const step = renderInstall(
+			bin,
+			option,
+			{ os: env.os, arch: env.arch, pluginRoot: bin.root ?? "" },
+			reason,
+		);
 		if (
 			step.kind === "uv-module" &&
 			step.escalation === "sudo" &&
@@ -895,7 +900,9 @@ async function landingDir(
  * 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.
+ * the directory and the rc line. Not found at all: failed. Still below its
+ * `minVersion`: failed, naming the version found, the floor and the file the
+ * PATH resolves to — usually an older copy ahead of the one just installed.
  */
 async function verifyInstalled(
 	p: PlannedStep,
@@ -904,6 +911,7 @@ async function verifyInstalled(
 	const { env } = ctx;
 	const offPath: Verified[] = [];
 	const missing: string[] = [];
+	const outdated: string[] = [];
 	for (const target of p.installs) {
 		const presence = await ctx.io.verify(target, env);
 		if (presence.status === "present") continue;
@@ -911,6 +919,18 @@ async function verifyInstalled(
 			offPath.push({ status: "off-path", dir: presence.prefix });
 			continue;
 		}
+		if (presence.status === "outdated") {
+			const tool = target.requirement.check[0] ?? target.requirement.name;
+			const resolved = onPath(tool, env.path);
+			outdated.push(
+				`${target.requirement.name} is still ${presence.found}, below the ${presence.minVersion} it needs: ${
+					resolved
+						? `the PATH Claude Code starts with runs ${resolved}`
+						: `${tool} is not on the PATH Claude Code starts with`
+				} — remove that older copy or put the new one ahead of it, then restart Claude Code from a new terminal`,
+			);
+			continue;
+		}
 		const tool = target.requirement.check[0] ?? target.requirement.name;
 		const landed = await landingDir(p.step, ctx);
 		if (landed && onPath(tool, landed)) {
@@ -924,6 +944,10 @@ async function verifyInstalled(
 	if (missing.length > 0) {
 		return { status: "failed", why: missing.join("\n") };
 	}
+	if (outdated.length > 0) {
+		const why = outdated.join("\n");
+		return { status: "failed", why, remedy: why };
+	}
 	const first = offPath[0];
 	if (first?.dir) {
 		return {

package/src/services/deps-report.ts

@@ -33,13 +33,20 @@ import {
 	prefixOnPath,
 	requiredByOf,
 } from "./deps-plan.js";
-import { DOCTOR_CHECK_CAP_MS, probeBins } from "./doctor-bins.js";
+import {
+	DOCTOR_CHECK_CAP_MS,
+	installReason,
+	probeBins,
+} from "./doctor-bins.js";
 import { readManifest } from "./manifest.js";
 import { resolvePluginRequires, selectBins } from "./plugin-requires.js";
 import { binKey, cliToolBins, mergeBins } from "./resolver.js";
 
-/** The `--json` document's shape version. */
-export const DEPS_REPORT_SCHEMA = 1;
+/**
+ * The `--json` document's shape version. 2 added the `outdated` status and a
+ * dep's `found` and `minVersion`.
+ */
+export const DEPS_REPORT_SCHEMA = 2;
 
 export interface PluginParseProblem {
 	plugin: string;
@@ -187,6 +194,10 @@ export interface DepJson {
 	blockedBy?: string;
 	prefix?: string;
 	reason?: string;
+	/** Only when `status` is "outdated": the version the check reported. */
+	found?: string;
+	/** Only when `status` is "outdated": the lowest version that will do. */
+	minVersion?: string;
 	fix?: {
 		via: string;
 		escalation: "none" | "sudo";
@@ -227,11 +238,17 @@ export function depsReportJson(
 		if (p.status === "missing" && p.blockedBy) entry.blockedBy = p.blockedBy;
 		if (p.status === "off-path") entry.prefix = p.prefix;
 		if (p.status === "unknown") entry.reason = p.reason;
+		if (p.status === "outdated") {
+			entry.found = p.found;
+			entry.minVersion = p.minVersion;
+		}
 		if (p.status !== "present" && bin.chosen) {
-			const step = renderInstall(bin, bin.chosen, {
-				...env,
-				pluginRoot: bin.root ?? "",
-			});
+			const step = renderInstall(
+				bin,
+				bin.chosen,
+				{ ...env, pluginRoot: bin.root ?? "" },
+				installReason(p),
+			);
 			const prefix = prefixOf(step);
 			entry.fix = {
 				via: bin.chosen.via,

package/src/services/doctor-bins.ts

@@ -9,6 +9,7 @@
  */
 
 import {
+	type InstallReason,
 	type Presence,
 	type ProbeDepth,
 	type Requirement,
@@ -68,6 +69,7 @@ export async function probeBins(
 		const reqs: Requirement[] = batch.map(({ bin }) => ({
 			name: bin.name,
 			check: expandCheck(bin, bin.root ?? ""),
+			...(bin.minVersion !== undefined ? { minVersion: bin.minVersion } : {}),
 			install: bin.install,
 		}));
 		const answers = await probe(reqs, {
@@ -93,13 +95,25 @@ export async function probeBins(
 	return out;
 }
 
-/** The line a person runs to install `bin` here, or why nothing can. */
-export function installText(bin: ResolvedBin, env: PlanEnv): string {
+/**
+ * The line a person runs to install `bin` here — or, `outdated`, to replace
+ * the copy that is too old — or why nothing can.
+ */
+export function installText(
+	bin: ResolvedBin,
+	env: PlanEnv,
+	reason: InstallReason = "missing",
+): string {
 	if (!bin.chosen) {
 		return whyUnselectable(bin, env, (t) => onPath(t, env.path) !== null);
 	}
 	return describeStep(
-		renderInstall(bin, bin.chosen, { ...env, pluginRoot: bin.root ?? "" }),
+		renderInstall(
+			bin,
+			bin.chosen,
+			{ ...env, pluginRoot: bin.root ?? "" },
+			reason,
+		),
 		env.os,
 	);
 }
@@ -107,7 +121,10 @@ export function installText(bin: ResolvedBin, env: PlanEnv): string {
 export interface BinCheckResult {
 	name: string;
 	presence: Presence;
-	/** Advisory text after "run:" for a human to copy. Never executed. */
+	/**
+	 * Advisory text after "run:" for a human to copy, an upgrade when the
+	 * presence is `outdated`. Never executed.
+	 */
 	installCommand: string;
 	/** Where the requirement came from (profile cliTools / plugin ids). */
 	sources: string[];
@@ -119,17 +136,28 @@ export async function checkBinaries(
 	opts: ProbeBinsOptions,
 ): Promise<BinCheckResult[]> {
 	const presences = await probeBins(bins, opts);
-	return bins.map((bin, i) => ({
-		name: bin.name,
-		presence: presences[i] as Presence,
-		installCommand: installText(bin, opts.env),
-		sources: bin.sources,
-	}));
+	return bins.map((bin, i) => {
+		const presence = presences[i] as Presence;
+		return {
+			name: bin.name,
+			presence,
+			installCommand: installText(bin, opts.env, installReason(presence)),
+			sources: bin.sources,
+		};
+	});
+}
+
+/** Why a requirement with this presence would be installed. */
+export function installReason(presence: Presence): InstallReason {
+	return presence.status === "outdated" ? "outdated" : "missing";
 }
 
-/** The actionable subset: missing, or installed but not on PATH. */
+/** The actionable subset: missing, outdated, or installed but not on PATH. */
 export function missingBinaries(results: BinCheckResult[]): BinCheckResult[] {
 	return results.filter(
-		(r) => r.presence.status === "missing" || r.presence.status === "off-path",
+		(r) =>
+			r.presence.status === "missing" ||
+			r.presence.status === "outdated" ||
+			r.presence.status === "off-path",
 	);
 }

package/src/services/profile-activate.ts

@@ -42,6 +42,8 @@ import {
 	OBSOLETE_GITIGNORE_ENTRIES,
 	PROFILE_GITIGNORE_COMMENT,
 	PROFILE_GITIGNORE_ENTRIES,
+	PROFILE_WORKTREE_INCLUDE_COMMENT,
+	PROFILE_WORKTREE_INCLUDE_ENTRIES,
 	assertLiveFilesParse,
 	backupRoot,
 	backupStamp,
@@ -324,6 +326,13 @@ export async function activateProfile(
 			remove: conversion.converted ? OBSOLETE_GITIGNORE_ENTRIES : [],
 		},
 	);
+	// Claude Code copies git-ignored files into a worktree it creates only when
+	// `.worktreeinclude` lists them — see PROFILE_WORKTREE_INCLUDE_ENTRIES.
+	await updateManagedGitignoreBlock(
+		path.join(projectPath, ".worktreeinclude"),
+		PROFILE_WORKTREE_INCLUDE_COMMENT,
+		{ add: PROFILE_WORKTREE_INCLUDE_ENTRIES },
+	);
 
 	const backupDir = path.join(backupRoot(projectPath), backupStamp());
 	const displaced: DisplacedArtifact[] = [];

package/src/services/profile-live.ts

@@ -72,6 +72,32 @@ export const PROFILE_GITIGNORE_ENTRIES = [
 export const PROFILE_GITIGNORE_COMMENT =
 	"# magus: generated profile config (source of truth: .claude/profiles.json)";
 
+/**
+ * Paths magus lists in a project's `.worktreeinclude`. Claude Code copies a
+ * file into a worktree it creates (`claude -w`, EnterWorktree, agent
+ * isolation) only when that file is both git-ignored and listed there, at
+ * creation time. magus git-ignores the set-up state above, so without this
+ * list every new worktree gets `.claude/profiles.json` from the commit and none
+ * of the project's plugins.
+ *
+ * The marker FILE is listed, not `.claude/profiles/`: the directory would also
+ * copy a crash-orphaned temp file. It holds only hashes and ids, so a
+ * byte-for-byte copy reconciles as unchanged in the worktree. Backups are never
+ * listed — they are this checkout's hand-written files, possibly credentials,
+ * and nothing in a worktree uses them. Each magus-installed skill folder gets
+ * its own line (see `profile-skills.ts`).
+ */
+export const PROFILE_WORKTREE_INCLUDE_ENTRIES = [
+	".claude/settings.json",
+	".mcp.json",
+	".claude/models.json",
+	".claude/profiles/active.json",
+];
+
+/** The comment heading magus's lines in a project's `.worktreeinclude`. */
+export const PROFILE_WORKTREE_INCLUDE_COMMENT =
+	"# magus: copied into new worktrees so they start with this project's plugins (source of truth: .claude/profiles.json)";
+
 /**
  * Lines older releases wrote into magus's managed `.gitignore` block that must
  * go when an older layout is converted: the blanket skills ignore hid committed

package/src/services/profile-skills.ts

@@ -28,6 +28,7 @@ import type {
 import { updateManagedGitignoreBlock } from "./conventions-manager.js";
 import {
 	PROFILE_GITIGNORE_COMMENT,
+	PROFILE_WORKTREE_INCLUDE_COMMENT,
 	backupRoot,
 	backupStamp,
 	folderHash,
@@ -251,6 +252,9 @@ export async function inspectManagedSkills(
  * `.gitignore` block: `before` are the folders the marker listed, `after` the
  * ones it lists now. Lines are taken out of magus's block only — the same
  * pattern a person wrote elsewhere in the file stays.
+ *
+ * The same lines go into magus's `.worktreeinclude` block, so a worktree
+ * Claude Code creates gets the folders the copied marker records.
  */
 export async function updateSkillIgnoreLines(
 	projectPath: string,
@@ -258,13 +262,19 @@ export async function updateSkillIgnoreLines(
 	after: readonly string[],
 ): Promise<void> {
 	const keep = new Set(after);
+	const edits = {
+		add: [...keep].map(skillIgnoreLine),
+		remove: before.filter((f) => !keep.has(f)).map(skillIgnoreLine),
+	};
 	await updateManagedGitignoreBlock(
 		path.join(projectPath, ".gitignore"),
 		PROFILE_GITIGNORE_COMMENT,
-		{
-			add: [...keep].map(skillIgnoreLine),
-			remove: before.filter((f) => !keep.has(f)).map(skillIgnoreLine),
-		},
+		edits,
+	);
+	await updateManagedGitignoreBlock(
+		path.join(projectPath, ".worktreeinclude"),
+		PROFILE_WORKTREE_INCLUDE_COMMENT,
+		edits,
 	);
 }
 

package/src/services/profile-state.ts

@@ -28,6 +28,7 @@
 import path from "node:path";
 import type { ProfileManifest, ProfileManifestEntry } from "../types/index.js";
 import { selectProfileId } from "./active-closure.js";
+import { updateManagedGitignoreBlock } from "./conventions-manager.js";
 import { readManifest, updateProfileEntry, writeManifest } from "./manifest.js";
 import {
 	type ReconcileResult,
@@ -48,6 +49,8 @@ import {
 	type ActiveMarker,
 	LIVE_FILE_KEYS,
 	MACHINE_LOCAL_SETTINGS_KEYS,
+	PROFILE_WORKTREE_INCLUDE_COMMENT,
+	PROFILE_WORKTREE_INCLUDE_ENTRIES,
 	activeProfile,
 	folderHash,
 	hasCurrentMarker,
@@ -69,6 +72,7 @@ import {
 	SkillClashError,
 	inspectManagedSkills,
 	skillFolder,
+	skillIgnoreLine,
 } from "./profile-skills.js";
 import { resolveExtends } from "./resolver.js";
 import type { SettingsParseError } from "./settings-file.js";
@@ -371,6 +375,20 @@ export async function prepareProfileState(
 			out.lines.push(...activationNotes(result, { tracked: false }));
 			out.activations.push(result);
 		}
+		// A project set up by a release that never wrote `.worktreeinclude`
+		// re-activates rarely, so the gate lists the set-up state here. A no-op
+		// when every line is already there.
+		const marker = await readActiveMarker(projectPath);
+		await updateManagedGitignoreBlock(
+			path.join(projectPath, ".worktreeinclude"),
+			PROFILE_WORKTREE_INCLUDE_COMMENT,
+			{
+				add: [
+					...PROFILE_WORKTREE_INCLUDE_ENTRIES,
+					...Object.keys(marker?.skills ?? {}).map(skillIgnoreLine),
+				],
+			},
+		);
 		out.check = { state: "active", profile, restored: false };
 	}
 	return out;

package/src/services/resolver.ts

@@ -314,6 +314,7 @@ export function requirementOf(bin: Requirement): Requirement {
 		name: bin.name,
 		check: bin.check,
 		...(bin.os ? { os: bin.os } : {}),
+		...(bin.minVersion !== undefined ? { minVersion: bin.minVersion } : {}),
 		install: bin.install,
 	};
 }

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

@@ -6,8 +6,9 @@
  * 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
+ * for every other, and for any requirement with a `minVersion`), and prints a
+ * `systemMessage` carrying the `magus-deps` marker when something is missing,
+ * outdated 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.
@@ -200,8 +201,11 @@ async function main(): Promise<void> {
 		userShell: process.env.SHELL ?? "",
 	};
 	const presences = await probe(reqs, env);
+	// Outdated is a finding like missing: claimed once, reported once.
 	const reportable = (p: Presence) =>
-		p.status === "missing" || p.status === "off-path";
+		p.status === "missing" ||
+		p.status === "outdated" ||
+		p.status === "off-path";
 	if (!presences.some(reportable)) return;
 
 	const byName = new Map(reqs.map((r) => [r.name, r]));