@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/capability/index.ts

@@ -6,10 +6,15 @@
  * - Registering providers (where to find it)
  * - Loading items for a capability across all providers
  */
+
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import {
+	CONFIG_DIR_NAME,
 	getAgentDir,
 	getAgentProfileAuthority,
+	getConfigDirName,
+	getPluginsDir,
 	getProjectDir,
 	getTrustedHomeDir,
 	logger,
@@ -45,6 +50,157 @@ const providerMeta = new Map<string, { displayName: string; description: string
 /** Disabled providers (by ID) */
 const disabledProviders = new Set<string>();
 
+/** User/project roots used by providers that derive paths from LoadContext.home/cwd. */
+const EXPLICIT_HOME_PROVIDER_ROOTS = [
+	// `claude` and `codex` are import aliases for the registered hook providers.
+	{ providerIds: ["claude", "claude-hooks"], user: null, project: ".claude" },
+	{ providerIds: ["codex", "codex-hooks"], user: null, project: ".codex" },
+	{ providerIds: ["gemini"], user: ".gemini", project: ".gemini" },
+	{ providerIds: ["opencode"], user: path.join(".config", "opencode"), project: ".opencode" },
+	{ providerIds: ["opencode"], user: null, project: "opencode.json" },
+	{ providerIds: ["cursor"], user: ".cursor", project: ".cursor" },
+	{ providerIds: ["windsurf"], user: path.join(".codeium", "windsurf"), project: ".windsurf" },
+	{ providerIds: ["cline"], user: null, project: ".clinerules" },
+	{ providerIds: ["github"], user: null, project: ".github" },
+	{ providerIds: ["agents"], user: ".agent", project: ".agent" },
+	{ providerIds: ["agents"], user: ".agents", project: ".agents" },
+	{ providerIds: ["agents-md"], user: null, project: "AGENTS.md" },
+	{ providerIds: ["mcp-json"], user: null, project: "mcp.json" },
+	{ providerIds: ["mcp-json"], user: null, project: ".mcp.json" },
+	{ providerIds: ["ssh-json"], user: null, project: "ssh.json" },
+	{ providerIds: ["ssh-json"], user: null, project: ".ssh.json" },
+] as const;
+
+const ANCESTOR_SCOPED_PROJECT_PROVIDERS = new Set(["agents", "agents-md", "cline"]);
+
+function isWithinOrEqual(root: string, candidate: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+/**
+ * Resolve a path through the real path of its deepest existing ancestor,
+ * re-appending any not-yet-created suffix. Explicit-home discovery accepts
+ * fresh project paths, but must not let a symlinked existing ancestor alias a
+ * directory outside the supplied home.
+ */
+async function canonicalizeThroughExistingAncestor(target: string): Promise<string> {
+	const resolved = path.resolve(target);
+	const suffix: string[] = [];
+	let current = resolved;
+
+	while (true) {
+		try {
+			const real = await fs.realpath(current);
+			return suffix.length > 0 ? path.join(real, ...suffix.reverse()) : real;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+			const parent = path.dirname(current);
+			if (parent === current) return resolved;
+			suffix.push(path.basename(current));
+			current = parent;
+		}
+	}
+}
+
+async function canonicalizeContainedPath(root: string, target: string, label: string): Promise<string> {
+	const canonical = await canonicalizeThroughExistingAncestor(target);
+	if (!isWithinOrEqual(root, canonical)) {
+		throw new Error(
+			`loadCapabilityForHome ${label} escapes the supplied home through a symlink: "${target}" resolves to "${canonical}" outside "${root}".`,
+		);
+	}
+	return canonical;
+}
+
+/**
+ * Validate every config root that explicit-home discovery can use before any
+ * provider is invoked. A symlinked `.gjc`/`agent`/`plugins` directory would
+ * otherwise make a path that is lexically inside the supplied home read an
+ * unrelated profile.
+ */
+async function assertExplicitHomeRoots(
+	canonicalHome: string,
+	cwd: string,
+	explicitAgentDir: boolean,
+	providerIds: ReadonlySet<string>,
+	isolatedHome: boolean,
+): Promise<void> {
+	const userRoots = new Map<string, string>();
+	const projectRoots = new Map<string, { label: string; walksAncestors: boolean }>();
+	const addUserRoot = (root: string, label: string): void => {
+		if (!userRoots.has(root)) userRoots.set(root, label);
+	};
+	const addProjectRoot = (root: string, label: string, walksAncestors = false): void => {
+		if (!projectRoots.has(root)) projectRoots.set(root, { label, walksAncestors });
+	};
+
+	// Resolve aliases before selecting roots. For example, the registered
+	// `claude-hooks` provider uses the `.claude` root shared by the `claude`
+	// import convention, while only its project scope is actually loaded.
+	for (const source of EXPLICIT_HOME_PROVIDER_ROOTS) {
+		if (!source.providerIds.some(providerId => providerIds.has(providerId))) continue;
+		const label = source.providerIds.join("/");
+		if (source.user) addUserRoot(path.join(canonicalHome, source.user), `${label} user root`);
+		if (source.project)
+			addProjectRoot(
+				source.project,
+				`${label} project root`,
+				source.providerIds.some(providerId => ANCESTOR_SCOPED_PROJECT_PROVIDERS.has(providerId)),
+			);
+	}
+
+	// Native and SSH providers use the managed agent directory for user scope,
+	// while native, SSH, and project-scoped SSH config also read the project
+	// config root. An explicit agent directory is intentionally allowed outside
+	// the supplied home and is validated separately by the caller.
+	const usesNative = providerIds.has("native");
+	const usesSsh = providerIds.has("ssh-json");
+	if ((usesNative || usesSsh) && !explicitAgentDir)
+		addUserRoot(path.join(canonicalHome, getConfigDirName(), "agent"), "user agent directory");
+	if (usesNative || usesSsh) {
+		// Native and SSH project discovery are fixed to `.gjc`; configured project
+		// roots are validated only by adapters that actually consume them below.
+		addProjectRoot(".gjc", "native/SSH project registry root");
+	}
+
+	// The marketplace provider derives its user registry from the XDG-aware
+	// helper rather than a fixed `<home>/.gjc/plugins` path.
+	if (providerIds.has("claude-plugins")) {
+		addProjectRoot(path.join(CONFIG_DIR_NAME, "plugins"), "project plugin registry root", true);
+		addUserRoot(getPluginsDir(canonicalHome), "plugin registry root");
+	}
+
+	const trustedHome = await canonicalizeThroughExistingAncestor(getTrustedHomeDir());
+	const currentProfilePluginRoot =
+		canonicalHome === trustedHome ? await canonicalizeThroughExistingAncestor(getPluginsDir(canonicalHome)) : null;
+	await Promise.all(
+		[...userRoots.entries()].map(async ([root, label]) => {
+			const canonicalRoot = await canonicalizeThroughExistingAncestor(root);
+			if (label === "plugin registry root" && canonicalRoot === currentProfilePluginRoot) return;
+			await canonicalizeContainedPath(canonicalHome, root, label);
+		}),
+	);
+
+	// Validate only the roots at the boundaries their providers actually inspect.
+	// Cwd-only providers must not fail because an unrelated ancestor contains a
+	// symlinked config file; ancestor-scoped providers retain the full walk.
+	await Promise.all(
+		[...projectRoots.entries()].map(async ([relativeRoot, { label, walksAncestors }]) => {
+			if (!isolatedHome) return;
+			let current = cwd;
+			while (true) {
+				await canonicalizeContainedPath(canonicalHome, path.join(current, relativeRoot), label);
+				if (!walksAncestors || current === canonicalHome) break;
+				const parent = path.dirname(current);
+				if (parent === current) break;
+				current = parent;
+			}
+		}),
+	);
+}
+
 /** Settings manager for persistence (if set) */
 let settings: Settings | null = null;
 /** Session-local settings keyed by normalized working directory. */
@@ -120,7 +276,7 @@ async function loadImpl<T>(
 		: new Set<string>(
 				options.disabledExtensions ??
 					options.settings?.get("disabledExtensions") ??
-					settings?.get("disabledExtensions") ??
+					(options.isolatedHome ? undefined : settings?.get("disabledExtensions")) ??
 					[],
 			);
 
@@ -221,8 +377,12 @@ async function loadImpl<T>(
  * Filter providers based on options and disabled state.
  */
 function filterProviders<T>(capability: Capability<T>, options: LoadOptions): Provider<T>[] {
-	const activeSettings = options.settings ?? settingsByCwd.get(path.normalize(options.cwd ?? getProjectDir()));
-	const activeDisabledProviders = new Set(activeSettings?.get("disabledProviders") ?? disabledProviders);
+	const activeSettings = options.isolatedHome
+		? options.settings
+		: (options.settings ?? settingsByCwd.get(path.normalize(options.cwd ?? getProjectDir())));
+	const activeDisabledProviders = new Set(
+		activeSettings?.get("disabledProviders") ?? (options.isolatedHome ? [] : disabledProviders),
+	);
 	let providers = (capability.providers as Provider<T>[]).filter(
 		p => options.includeDisabledProviders === true || !activeDisabledProviders.has(p.id),
 	);
@@ -247,19 +407,122 @@ export async function loadCapability<T>(capabilityId: string, options: LoadOptio
 		throw new Error(`Unknown capability: "${capabilityId}"`);
 	}
 
-	const cwd = options.cwd ?? getProjectDir();
+	// `isolatedHome` is an internal option used only by loadCapabilityForHome.
+	// Public ordinary loads must always apply the active process settings and
+	// disabled-provider/extension policy, even if a caller supplies that field.
+	const ordinaryOptions: LoadOptions = options.isolatedHome ? { ...options, isolatedHome: false } : options;
+	const cwd = ordinaryOptions.cwd ?? getProjectDir();
 	const home = getTrustedHomeDir();
-	const userAgentDir = options.agentDir ? path.resolve(options.agentDir) : getAgentDir();
+	const userAgentDir = ordinaryOptions.agentDir ? path.resolve(ordinaryOptions.agentDir) : getAgentDir();
 	const profileAuthority =
-		options.profileAuthority ??
-		(options.agentDir && normalizePathForComparison(userAgentDir) !== normalizePathForComparison(getAgentDir())
+		ordinaryOptions.profileAuthority ??
+		(ordinaryOptions.agentDir &&
+		normalizePathForComparison(userAgentDir) !== normalizePathForComparison(getAgentDir())
 			? "custom"
 			: getAgentProfileAuthority());
 	const repoRoot = await findRepoRoot(cwd);
-	const ctx: LoadContext = { cwd, home, userAgentDir, profileAuthority, repoRoot, settings: options.settings };
-	const providers = filterProviders(capability, options);
+	const ctx: LoadContext = {
+		cwd,
+		home,
+		userAgentDir,
+		profileAuthority,
+		repoRoot,
+		isolatedHome: false,
+		settings: ordinaryOptions.settings,
+	};
+	const providers = filterProviders(capability, ordinaryOptions);
+
+	return await loadImpl(capability, providers, ctx, ordinaryOptions);
+}
+
+/**
+ * Load a capability against an explicitly supplied home directory.
+ *
+ * Cross-profile authority contract: when an explicit `home` is supplied, the
+ * load must resolve every user-scope surface from that home and NEVER fall
+ * back to the process-global `getAgentDir()`. The agent directory is derived
+ * from the supplied home (`<home>/<configDir>/agent`) unless the caller
+ * supplies an explicit `agentDir`; there is no implicit process-profile
+ * fallback. Consumers that cannot derive a user scope must fail closed.
+ */
+export async function loadCapabilityForHome<T>(
+	capabilityId: string,
+	home: string,
+	options: LoadOptions = {},
+): Promise<CapabilityResult<T>> {
+	const capability = capabilities.get(capabilityId) as Capability<T> | undefined;
+	if (!capability) {
+		throw new Error(`Unknown capability: "${capabilityId}"`);
+	}
+
+	const resolvedHome = path.resolve(home);
+	if (!path.isAbsolute(home)) {
+		throw new Error(
+			`loadCapabilityForHome requires an absolute home directory; received "${home}". Refusing to fall back to the process profile.`,
+		);
+	}
+	// Derive the user agent directory from the SUPPLIED home. An explicit
+	// options.agentDir is honored; otherwise `<home>/<configDirName>/agent`.
+	// getAgentDir() is deliberately not consulted: an explicit home must never
+	// read another profile's SYSTEM/RULES/AGENTS, skills, commands, hooks,
+	// settings, or executable descriptors.
+	const canonicalHome = await canonicalizeThroughExistingAncestor(resolvedHome);
+	const homeStats = await fs.stat(canonicalHome);
+	const homeIdentity = { dev: homeStats.dev, ino: homeStats.ino };
+	const trustedHome = await canonicalizeThroughExistingAncestor(getTrustedHomeDir());
+	const isolatedHome = canonicalHome !== trustedHome;
+	const lexicalCwd = options.cwd === undefined ? canonicalHome : path.resolve(options.cwd);
+	const cwd = await canonicalizeThroughExistingAncestor(lexicalCwd);
+	// Every explicit-home cwd must resolve inside the supplied physical home.
+	// Allowing an outside cwd would let repository and plugin-registry discovery
+	// walk unrelated ancestors before the isolated boundary can take effect.
+	if (isolatedHome && !isWithinOrEqual(canonicalHome, cwd)) {
+		throw new Error(
+			`loadCapabilityForHome cwd is outside the supplied home: "${lexicalCwd}" resolves to "${cwd}" outside "${canonicalHome}".`,
+		);
+	}
+
+	const isolatedOptions: LoadOptions = { ...options, isolatedHome };
+	const providers = filterProviders(capability, isolatedOptions);
+	const effectiveProviderIds = new Set(providers.map(provider => provider.id));
+	const usesAgentScope = effectiveProviderIds.has("native") || effectiveProviderIds.has("ssh-json");
+	const userAgentDir = options.agentDir
+		? await canonicalizeThroughExistingAncestor(path.resolve(options.agentDir))
+		: usesAgentScope
+			? await canonicalizeContainedPath(
+					canonicalHome,
+					path.join(canonicalHome, getConfigDirName(), "agent"),
+					"user agent directory",
+				)
+			: path.join(canonicalHome, getConfigDirName(), "agent");
+	const userAgentStats = await fs.stat(userAgentDir).catch(() => null);
+	const userAgentIdentity = userAgentStats ? { dev: userAgentStats.dev, ino: userAgentStats.ino } : null;
+	await assertExplicitHomeRoots(canonicalHome, cwd, Boolean(options.agentDir), effectiveProviderIds, isolatedHome);
+	const repoRootCandidate = await findRepoRoot(cwd, canonicalHome, {
+		isolatedHome,
+		homeIdentity,
+		home: canonicalHome,
+		bypassCache: true,
+	});
+	const canonicalRepoRoot = repoRootCandidate ? await canonicalizeThroughExistingAncestor(repoRootCandidate) : null;
+	const repoRoot =
+		canonicalRepoRoot &&
+		canonicalRepoRoot !== canonicalHome &&
+		(!isolatedHome || isWithinOrEqual(canonicalHome, canonicalRepoRoot))
+			? canonicalRepoRoot
+			: null;
+	const ctx: LoadContext = {
+		cwd,
+		home: canonicalHome,
+		userAgentDir,
+		userAgentIdentity,
+		repoRoot,
+		isolatedHome,
+		homeIdentity,
+		settings: isolatedOptions.settings,
+	};
 
-	return await loadImpl(capability, providers, ctx, options);
+	return await loadImpl(capability, providers, ctx, isolatedOptions);
 }
 
 // =============================================================================

package/src/capability/types.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Settings } from "../config/settings";
+import type { FileIdentity } from "./fs";
 /**
  * Context passed to every provider loader.
  */
@@ -31,8 +32,14 @@ export interface LoadContext {
 	userAgentDir?: string;
 	/** Resolver-owned classification for the selected user agent directory. */
 	profileAuthority?: "default" | "custom";
+	/** Device/inode identity captured for the explicit home root. */
+	homeIdentity?: FileIdentity;
+	/** Device/inode identity captured for the isolated native agent root. */
+	userAgentIdentity?: FileIdentity | null;
 	/** Git repository root (directory containing .git), or null if not in a repo */
 	repoRoot: string | null;
+	/** Whether discovery must remain isolated to the supplied home boundary. */
+	isolatedHome?: boolean;
 	/** Owning session settings for provider policy decisions. */
 	settings?: Settings;
 }
@@ -107,6 +114,8 @@ export interface LoadOptions {
 	disabledExtensions?: string[];
 	/** Session settings whose provider policy applies to this load. */
 	settings?: Settings;
+	/** Internal: prevent explicit-home loads from consulting process-global policy. */
+	isolatedHome?: boolean;
 }
 
 /**

package/src/cli/customize-doctor.ts

@@ -297,10 +297,11 @@ const TRUST_BY_KIND: Record<CustomizeSurfaceKind, string> = {
 };
 
 /** Whether a restart/new session is required for changes to take effect. */
-function restartRequiredFor(kind: CustomizeSurfaceKind): boolean {
-	// MCP servers are connectable on demand inside a running session
-	// (`/mcp connect`); every other surface is fixed at session startup.
-	return kind !== "mcp";
+function restartRequiredFor(_kind: CustomizeSurfaceKind): boolean {
+	// Every customization projection describes startup-owned state. MCP is not
+	// an in-session public reload surface, so it follows the same contract as
+	// every other customization kind.
+	return true;
 }
 
 function sourceClassFor(provider: string): CustomizeSourceClass {
@@ -556,7 +557,7 @@ async function collectMcps(cwd: string, activeSettings: SettingsInstance): Promi
 	const disabledExts = disabledExtensionIds(activeSettings);
 	const disabledProviders = new Set(activeSettings.get("disabledProviders"));
 	// The startup projection: `loadAllMCPConfigs` is what a session uses when
-	// connecting MCP servers (`/mcp connect` or `--mcp-config`). A single
+	// connecting MCP servers at startup (`--mcp-config` names one exact file). A single
 	// policy-violating endpoint (for example userinfo in a URL) fails the whole
 	// projection closed at startup, so catch it and report instead of losing
 	// the surface.
@@ -644,8 +645,10 @@ async function collectMcps(cwd: string, activeSettings: SettingsInstance): Promi
 			base,
 			"stored-only",
 			"storage-only",
-			"Discovered but never auto-connected by standalone sessions. Connect it explicitly when you need it.",
-			["Run /mcp connect inside a session", `gjc --mcp-config ${entry.path} to load one exact config file`],
+			"Discovered but never auto-connected by standalone sessions at startup. Enable it for startup loading when you need it.",
+			[
+				`gjc --mcp-config ${entry.path} to load one exact config file (autoload: false servers stay unloaded; flip autoload and start a new session)`,
+			],
 			{ mcp: safeMcpSummary(server, connectable) },
 		);
 	});
@@ -962,8 +965,11 @@ async function collectExtensions(cwd: string, activeSettings: SettingsInstance):
 		nameOf: ext => ext.name,
 		pathOf: ext => ext.path,
 		notExecutedDetail:
-			"Discovered and shown in the extension dashboard, but session startup does not load filesystem extension modules. Runtime extensions come from validated GJC plugin bundles.",
-		notExecutedRemediation: ["See `gjc plugin list` for plugin bundles that contribute extensions"],
+			"Trusted filesystem extension module discovered for session-start loading. Doctor does not execute the module, so its runtime input handlers, tools, commands, and flags remain opaque until a session loads it.",
+		notExecutedRemediation: [
+			"Review the trusted extension source before session startup",
+			"Disable one module with gjc config set disabledExtensions '[\"extension-module:<name>\"]', or set disableExtensionDiscovery in the SDK",
+		],
 	});
 }
 
@@ -1404,7 +1410,7 @@ function foreignMcpItem(
 		scope: "project",
 		path: server._source.path,
 		trust: TRUST_BY_KIND.mcp,
-		restartRequired: false,
+		restartRequired: restartRequiredFor("mcp"),
 		precedence: { priority: 0, shadowedBy },
 	};
 	return {
@@ -1414,7 +1420,7 @@ function foreignMcpItem(
 		detail: `${desc.providerName} project convention (${desc.dirName}/) is not part of the GJC load path; sessions never discover this MCP server.`,
 		remediation: [
 			`Move the server definition to .gjc/mcp.json to make it discoverable`,
-			"or connect it explicitly via /mcp connect with an exact config file",
+			"then enable it for startup loading (autoload: false servers stay unloaded; flip autoload and start a new session)",
 		],
 		mcp: safeMcpSummary(server, false),
 	};
@@ -1598,7 +1604,7 @@ export async function runCustomizeDoctor(
 			skillScopeNotes,
 			disabledProviders: settings.get("disabledProviders"),
 			mcpNote:
-				"Standalone sessions never auto-connect MCP servers. Discovered servers are connectable on demand via /mcp connect, or with gjc --mcp-config <path>.",
+				"Standalone sessions never auto-connect undiscoverable MCP servers at startup. Discoverable servers load from GJC's own config scopes, or name one exact file with gjc --mcp-config <path> (autoload: false servers stay unloaded; flip autoload and start a new session).",
 			conventionsNotLoaded: foreignPolicyNote ? [foreignPolicyNote] : [],
 			globalImportCandidateDirs,
 			sourceClasses: SOURCE_CLASS_DESCRIPTIONS,

package/src/cli/doctor/args.ts

@@ -0,0 +1,236 @@
+import { isDoctorTargetId } from "./ids";
+import type { DoctorMode, DoctorRepair, DoctorRiskClass, DoctorScope } from "./types";
+
+export type DoctorAction =
+	| "config.set-validated"
+	| "mcp.set-startup-policy"
+	| "permissions.restrict-owned-config"
+	| "install.restore-binary"
+	| "install.repair-managed-link"
+	| "plugin.restore-known-artifact"
+	| "plugin.quarantine-selected"
+	| "service.restart-owned"
+	| "service.detach-owned-stale-artifact";
+export interface DoctorCliOptions {
+	readonly mode: DoctorMode;
+	readonly json: boolean;
+	readonly help: boolean;
+	readonly checks: readonly string[];
+	readonly scope?: DoctorScope;
+	readonly timeoutMs?: number;
+	readonly repair?: DoctorAction;
+	readonly targetId?: string;
+	readonly setValue?: boolean;
+	readonly ref?: string;
+	readonly sha256?: string;
+	readonly allowRisks: readonly DoctorRiskClass[];
+	readonly yes: boolean;
+	readonly drainSeconds?: number;
+}
+export type DoctorConfirmationResult = "confirmed" | "confirmation_declined" | "confirmation_timeout" | "cancelled";
+export interface DoctorOptions extends DoctorCliOptions {
+	readonly cwd?: string;
+	readonly tty?: boolean;
+	readonly signal?: AbortSignal;
+	readonly runId?: string;
+	readonly deadline?: number;
+	/** Internal supervisor channel; never populated from CLI data. */
+	readonly confirmRepair?: (repair: DoctorRepair) => Promise<DoctorConfirmationResult>;
+	/** Synchronous notification before entering an effect-capable transaction. */
+	readonly onRepairAdmitted?: () => void;
+}
+export interface DoctorParseResult {
+	readonly options?: DoctorOptions;
+	readonly error?: string;
+}
+const ACTION_TARGET_KINDS = {
+	"config.set-validated": "config",
+	"mcp.set-startup-policy": "mcp",
+	"permissions.restrict-owned-config": "permission",
+	"install.restore-binary": "binary",
+	"install.repair-managed-link": "link",
+	"plugin.restore-known-artifact": "plugin",
+	"plugin.quarantine-selected": "plugin",
+	"service.restart-owned": "service",
+	"service.detach-owned-stale-artifact": "artifact",
+} as const satisfies Record<DoctorAction, string>;
+const ACTIONS = new Set(Object.keys(ACTION_TARGET_KINDS));
+export function isDoctorAction(value: unknown): value is DoctorAction {
+	return typeof value === "string" && ACTIONS.has(value);
+}
+const RISKS = new Set<DoctorRiskClass>([
+	"config-change",
+	"permission-change",
+	"install-replace",
+	"plugin-change",
+	"service-interruption",
+	"artifact-detach",
+	"network",
+	"external-execution",
+]);
+function value(argv: readonly string[], i: number, _flag: string): [string | undefined, number] {
+	const v = argv[i + 1];
+	return !v || v.startsWith("-") ? [undefined, i] : [v, i + 1];
+}
+export function parseDoctorArgs(argv: readonly string[]): DoctorParseResult {
+	let mode: DoctorMode = "diagnose",
+		json = false,
+		help = false,
+		scope: DoctorScope | undefined,
+		timeoutMs: number | undefined;
+	let repair: DoctorAction | undefined,
+		targetId: string | undefined,
+		setValue: boolean | undefined,
+		ref: string | undefined,
+		sha256: string | undefined,
+		drainSeconds: number | undefined,
+		yes = false;
+	const checks = new Set<string>(),
+		allowRisks = new Set<DoctorRiskClass>();
+	const singleton = new Set([
+		"--repair",
+		"--target",
+		"--set-value-json",
+		"--ref",
+		"--sha256",
+		"--scope",
+		"--timeout-ms",
+	]);
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--json") {
+			json = true;
+			continue;
+		}
+		if (arg === "--help" || arg === "-h") {
+			help = true;
+			continue;
+		}
+		if (arg === "--fix") {
+			if (mode === "dry-run") continue;
+			mode = "fix";
+			continue;
+		}
+		if (arg === "--dry-run") {
+			mode = "dry-run";
+			continue;
+		}
+		if (arg === "--yes") {
+			yes = true;
+			continue;
+		}
+		const equals = arg.indexOf("=");
+		const flag = equals < 0 ? arg : arg.slice(0, equals);
+		const raw = equals < 0 ? undefined : arg.slice(equals + 1);
+		const hasInline = raw !== undefined;
+		if (flag === "--check" || flag === "--allow-risk") {
+			const v = hasInline ? raw : value(argv, i, flag)[0];
+			if (!v) return { error: `${flag} requires a value` };
+			if (!hasInline) i++;
+			if (flag === "--check") checks.add(v);
+			else {
+				if (!RISKS.has(v as DoctorRiskClass)) return { error: "unknown risk class" };
+				allowRisks.add(v as DoctorRiskClass);
+			}
+			continue;
+		}
+		if (singleton.has(flag)) {
+			if (
+				(flag === "--repair" && repair) ||
+				(flag === "--target" && targetId) ||
+				(flag === "--set-value-json" && setValue !== undefined) ||
+				(flag === "--ref" && ref) ||
+				(flag === "--sha256" && sha256) ||
+				(flag === "--scope" && scope) ||
+				(flag === "--timeout-ms" && timeoutMs !== undefined)
+			)
+				return { error: `${flag} may be specified only once` };
+			const v = hasInline ? raw : value(argv, i, flag)[0];
+			if (!v) return { error: `${flag} requires a value` };
+			if (!hasInline) i++;
+			if (flag === "--repair") {
+				if (!isDoctorAction(v)) return { error: "unknown repair action" };
+				repair = v;
+			} else if (flag === "--target") targetId = v;
+			else if (flag === "--set-value-json") {
+				if (v !== "true" && v !== "false") return { error: "--set-value-json accepts only true or false" };
+				setValue = v === "true";
+			} else if (flag === "--ref") ref = v;
+			else if (flag === "--sha256") {
+				if (!/^[a-fA-F0-9]{64}$/.test(v)) return { error: "--sha256 must be 64 hexadecimal characters" };
+				sha256 = v.toLowerCase();
+			} else if (flag === "--scope") {
+				if (v !== "user" && v !== "project") return { error: "--scope must be user or project" };
+				scope = v;
+			} else {
+				const n = Number(v);
+				if (!Number.isInteger(n) || n < 1000 || n > 120000)
+					return { error: "--timeout-ms must be an integer from 1000 to 120000" };
+				timeoutMs = n;
+			}
+			continue;
+		}
+		if (arg === "--drain") {
+			if (drainSeconds !== undefined) return { error: "--drain may be specified only once" };
+			drainSeconds = 30;
+			continue;
+		}
+		if (arg.startsWith("--")) return { error: "unknown option" };
+		return { error: "unexpected argument" };
+	}
+	if (mode === "fix" && (!repair || !targetId)) return { error: "--fix requires --repair and --target" };
+	if (mode === "dry-run" && repair !== undefined && targetId === undefined)
+		return { error: "--repair requires --target" };
+	if (drainSeconds !== undefined && repair !== "service.restart-owned")
+		return { error: "--drain is only valid for service.restart-owned" };
+	if (targetId !== undefined && !isDoctorTargetId(targetId))
+		return { error: "target must be a stable doctor target ID" };
+	if (repair && targetId && targetId.split(":")[1] !== ACTION_TARGET_KINDS[repair])
+		return { error: "repair action does not match target kind" };
+	if (scope && targetId) {
+		const parts = targetId.split(":");
+		const targetScope = parts.includes("user") ? "user" : parts.includes("project") ? "project" : undefined;
+		if (!targetScope) return { error: "--scope is unsupported for this target" };
+		if (targetScope !== scope) return { error: "--scope does not match target scope" };
+	}
+	if (repair === "config.set-validated" || repair === "mcp.set-startup-policy") {
+		if (setValue === undefined) return { error: "this action requires --set-value-json true|false" };
+	}
+	if (repair !== "config.set-validated" && repair !== "mcp.set-startup-policy" && setValue !== undefined)
+		return { error: "--set-value-json is only valid for config or MCP repairs" };
+	if (repair !== "install.restore-binary" && repair !== "plugin.restore-known-artifact" && sha256 !== undefined)
+		return { error: "--sha256 is only valid for binary or plugin restore" };
+	if (
+		repair !== "install.restore-binary" &&
+		repair !== "plugin.restore-known-artifact" &&
+		ref !== undefined &&
+		repair !== "install.repair-managed-link"
+	)
+		return { error: "--ref is not valid for this repair" };
+	if (repair === "install.repair-managed-link" && mode === "fix" && !ref)
+		return { error: "install.repair-managed-link requires --ref" };
+	if (
+		repair === "install.repair-managed-link" &&
+		ref !== undefined &&
+		!/^c1:link:r[0-9a-f]{64}:(source|wrapper|binary):p[0-9a-f]{64}$/.test(ref)
+	)
+		return { error: "--ref must be a c1 link candidate ID" };
+	return {
+		options: {
+			mode,
+			json,
+			help,
+			checks: [...checks],
+			scope,
+			timeoutMs,
+			repair,
+			targetId,
+			setValue,
+			ref,
+			sha256,
+			allowRisks: [...allowRisks],
+			yes,
+			drainSeconds,
+		},
+	};
+}