@dsh-electron/dsh-plugin-multi-root-workspace 0.1.6 → 0.1.7

package/lib/command-CESuwlVt.js

@@ -0,0 +1,1306 @@
+import { t as effectiveDirectory } from "./session-directory-BLOstut1.js";
+import { r as canonicalPath$1 } from "./windows-runner-contract-CEfmZzu0.js";
+import { i as canonicalRoot, o as entryRootRef, p as resolveRootRef, r as availableRoots, t as RootValidationError } from "./roots-B-0l8mNG.js";
+import { i as parsePanelCall, r as effectiveRootAccess, t as PANEL_CHANNEL } from "./contract-DZ4zczDT.js";
+import "@deepseek-ai/cordis";
+import { closeSync, lstatSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { canonicalPath } from "@deepseek-ai/dsh-sandbox";
+//#region src/profile-isolation.ts
+/**
+* Profile pnpm import isolation — the host-side maintenance behind
+* `/workspace-folders isolate-profiles` (branch review Phase C2, finding R4).
+*
+* Why it exists: a Windows deny ACE applies to the file OBJECT, not to one
+* hardlink name. The pnpm profile defaults upstream writes (`initProfile` in
+* dsh-app-boot) never set `packageImportMethod`, so `dsh plugin add` imports
+* the store into `<home>/profiles/<name>/node_modules` BY HARDLINK. Denying
+* `$DSH_HOME` then rewrites security descriptors shared with every other name
+* of the same objects — including the global pnpm store and other projects
+* linking it. The C1 preflight therefore refuses such a home before any ACL
+* write; this module is the remediation it points at: it detects the confirmed
+* profiles, writes `packageImportMethod: copy` conservatively, and scans the
+* whole home for the multi-link files that still need a reinstall.
+*
+* Boundaries of the subset it touches:
+* - profile identification is conservative — only a directory under
+*   `profiles/` whose `package.json` parses to an object carrying
+*   `dsh.profile` as an object counts; everything else is enumerated but
+*   never written;
+* - the YAML handling is a strict SUBSET scanner, not a parser substitute —
+*   the runtime cannot depend on a YAML package, so anything ambiguous is
+*   reported as a conflict and refused instead of guessed;
+* - every write is atomic (temp sibling + rename) and never crosses a reparse
+*   point;
+* - the whole-home scan never descends a reparse point: with plain `lstat` a
+*   symlink/junction reports as a link, and other reparse flavours still fall
+*   under the runner's own Win32-attribute preflight, which remains the
+*   authoritative gate;
+* - the command sets configuration — it never deletes `node_modules`, never
+*   runs pnpm, and never repairs ACLs or ownership written in the past.
+*
+* @module profile-isolation
+*/
+/** `pnpm-workspace.yaml` — the only file the maintenance verb ever writes. */
+const WORKSPACE_YAML = "pnpm-workspace.yaml";
+/** How many example paths a report keeps before it only counts the rest. */
+const SAMPLE_CAP = 20;
+/**
+* A top-level key line the subset scanner accepts. The value is deliberately
+* not validated here — its shape decides the entry kind.
+*/
+const TOP_LEVEL_KEY = /^([A-Za-z0-9][A-Za-z0-9._-]*|'(?:[^']|'')+'|"(?:[^"\\]|\\.)*")\s*:/;
+/** YAML double-quoted single-character escapes (the multi-hex forms follow). */
+const DOUBLE_QUOTED_ESCAPES = {
+	"0": "\0",
+	a: "\x07",
+	b: "\b",
+	t: "	",
+	"	": "	",
+	n: "\n",
+	v: "\v",
+	f: "\f",
+	r: "\r",
+	e: "\x1B",
+	"\"": "\"",
+	"'": "'",
+	"\\": "\\",
+	"/": "/",
+	N: "…",
+	_: "\xA0",
+	L: "\u2028",
+	P: "\u2029",
+	" ": " "
+};
+/**
+* Unquote a single-quoted or double-quoted YAML token.
+* @param token - the token including its quotes.
+* @param fail - the rejection callback for escapes outside the subset.
+* @returns the unquoted text.
+*/
+function unquoteYamlToken(token, fail) {
+	if (token.startsWith("'")) return token.slice(1, -1).replaceAll("''", "'");
+	const inner = token.slice(1, -1);
+	let out = "";
+	for (let i = 0; i < inner.length; i += 1) {
+		const char = inner[i];
+		if (char !== "\\") {
+			out += char;
+			continue;
+		}
+		const escape = inner[i + 1];
+		if (escape === void 0) fail("a backslash ends the quoted token");
+		if (escape === "x" || escape === "u" || escape === "U") {
+			const digits = escape === "x" ? 2 : escape === "u" ? 4 : 8;
+			const hex = inner.slice(i + 2, i + 2 + digits);
+			if (!new RegExp(`^[0-9a-fA-F]{${digits}}$`).test(hex)) fail(`\\${escape} wants ${digits} hex digits, got ${JSON.stringify(hex)}`);
+			out += String.fromCodePoint(Number.parseInt(hex, 16));
+			i += 1 + digits;
+			continue;
+		}
+		const mapped = DOUBLE_QUOTED_ESCAPES[escape];
+		if (mapped === void 0) fail(`unsupported escape \\${escape}`);
+		out += mapped;
+		i += 1;
+	}
+	return out;
+}
+/**
+* Locate the first `#` starting a comment in a plain (unquoted) value: the
+* marker must be preceded by separation whitespace per YAML's comment rule.
+* @param value - the value text after `key:`.
+* @returns the comment offset inside `value`, or `-1`.
+*/
+function plainCommentStart(value) {
+	for (let i = 0; i < value.length; i += 1) if (value[i] === "#" && i > 0 && (value[i - 1] === " " || value[i - 1] === "	")) return i;
+	return -1;
+}
+/**
+* Read the top-level `key: value` lines of a `pnpm-workspace.yaml` text.
+*
+* This is a strict subset scanner, deliberately NOT a YAML parser: it accepts
+* only top-level `key:` lines (plain or quoted keys) plus indented nested
+* content it never interprets, and throws — naming the file and the 1-based
+* line — on an indented first entry, tabs in indentation, `%` / `---` / `...` directives, duplicate
+* top-level keys, or any other non-indented content line outside the key
+* form. A `#` preceded by whitespace ends a plain scalar; quoted scalars are
+* unquoted for the reported value. `valueStart`/`valueEnd` are the UTF-16
+* offsets of the value token itself, so a caller can replace exactly the
+* scalar while comments and line endings survive untouched.
+*
+* @param text - the yaml text to scan.
+* @param path - the file name used in rejection messages.
+* @returns the top-level entries keyed by their unquoted names.
+*/
+function parseWorkspaceYamlKeys(text, path = WORKSPACE_YAML) {
+	const fail = (line, what) => {
+		throw new Error(`${path}:${line}: ${what}`);
+	};
+	const entries = /* @__PURE__ */ new Map();
+	let cursor = 0;
+	let line = 0;
+	while (cursor <= text.length) {
+		line += 1;
+		const lineStart = cursor;
+		const newline = text.indexOf("\n", cursor);
+		const lineEnd = newline < 0 ? text.length : newline;
+		const raw = lineEnd > lineStart && text[lineEnd - 1] === "\r" ? text.slice(lineStart, lineEnd - 1) : text.slice(lineStart, lineEnd);
+		cursor = newline < 0 ? text.length + 1 : lineEnd + 1;
+		const indentation = /^[ \t]*/.exec(raw)[0];
+		const content = raw.slice(indentation.length);
+		if (content === "") continue;
+		if (indentation.includes("	")) fail(line, "tab in indentation");
+		if (content.startsWith("#")) continue;
+		if (indentation.length > 0) {
+			if (entries.size === 0) fail(line, "indented top-level mappings are outside the supported subset");
+			continue;
+		}
+		if (content.startsWith("%")) fail(line, "a `%` directive is outside the supported subset");
+		if (/^-{3}(?:\s|$)/.test(content)) fail(line, "a `---` document marker is outside the supported subset");
+		if (/^\.{3}(?:\s|$)/.test(content)) fail(line, "a `...` document end is outside the supported subset");
+		const keyToken = (TOP_LEVEL_KEY.exec(content) ?? fail(line, "a top-level line must read `key: value`, `key:`, or a comment"))[1];
+		const key = keyToken.startsWith("'") || keyToken.startsWith("\"") ? unquoteYamlToken(keyToken, (what) => fail(line, what)) : keyToken;
+		if (entries.has(key)) fail(line, `duplicate top-level key ${JSON.stringify(key)}`);
+		const colon = content.indexOf(":", keyToken.length);
+		const separation = /^[ \t]*/.exec(content.slice(colon + 1))[0].length;
+		const valueStart = lineStart + colon + 1 + separation;
+		const value = content.slice(colon + 1 + separation);
+		if (value === "" || value.startsWith("#")) {
+			entries.set(key, {
+				value: void 0,
+				kind: "block",
+				line,
+				valueStart,
+				valueEnd: valueStart
+			});
+			continue;
+		}
+		const head = value[0];
+		if ("&*!|>{[".includes(head)) {
+			const tokenLength = /^[^\s]+/.exec(value)[0].length;
+			entries.set(key, {
+				value: void 0,
+				kind: "complex",
+				line,
+				valueStart,
+				valueEnd: valueStart + tokenLength
+			});
+			continue;
+		}
+		if (head === "'" || head === "\"") {
+			let close = -1;
+			for (let i = 1; i < value.length; i += 1) {
+				if (head === "'" && value[i] === "'" && value[i + 1] === "'") {
+					i += 1;
+					continue;
+				}
+				if (head === "\"" && value[i] === "\\") {
+					i += 1;
+					continue;
+				}
+				if (value[i] === head) {
+					close = i;
+					break;
+				}
+			}
+			if (close < 0) {
+				entries.set(key, {
+					value: void 0,
+					kind: "complex",
+					line,
+					valueStart,
+					valueEnd: valueStart + value.length
+				});
+				continue;
+			}
+			const trailing = value.slice(close + 1);
+			let scalar;
+			try {
+				scalar = unquoteYamlToken(value.slice(0, close + 1), (what) => {
+					throw new Error(what);
+				});
+			} catch {
+				scalar = void 0;
+			}
+			if (!/^\s*(#|$)/.test(trailing)) entries.set(key, {
+				value: void 0,
+				kind: "complex",
+				line,
+				valueStart,
+				valueEnd: valueStart + close + 1
+			});
+			else if (scalar === void 0) entries.set(key, {
+				value: void 0,
+				kind: "complex",
+				line,
+				valueStart,
+				valueEnd: valueStart + close + 1
+			});
+			else entries.set(key, {
+				value: scalar,
+				kind: "scalar",
+				line,
+				valueStart,
+				valueEnd: valueStart + close + 1
+			});
+			continue;
+		}
+		const commentAt = plainCommentStart(value);
+		const scalarText = (commentAt < 0 ? value : value.slice(0, commentAt)).replace(/[ \t]+$/, "");
+		entries.set(key, {
+			value: scalarText,
+			kind: "scalar",
+			line,
+			valueStart,
+			valueEnd: valueStart + scalarText.length
+		});
+	}
+	return entries;
+}
+const describeError = (error) => error instanceof Error ? error.message : String(error);
+/**
+* Judge whether one directory is a confirmed DSH profile: a `package.json`
+* that parses to an object whose `dsh.profile` is itself an object.
+*/
+function isConfirmedProfile(dir) {
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+	} catch {
+		return false;
+	}
+	if (manifest === null || typeof manifest !== "object" || Array.isArray(manifest)) return false;
+	const dsh = manifest.dsh;
+	if (dsh === null || typeof dsh !== "object" || Array.isArray(dsh)) return false;
+	const profile = dsh.profile;
+	return profile !== null && typeof profile === "object" && !Array.isArray(profile);
+}
+/** Classify one confirmed profile's `pnpm-workspace.yaml`. */
+function inspectYaml(dir) {
+	const yamlPath = join(dir, WORKSPACE_YAML);
+	let stat;
+	try {
+		stat = lstatSync(yamlPath);
+	} catch {
+		stat = void 0;
+	}
+	if (stat !== void 0 && stat.isSymbolicLink()) return {
+		yamlPath,
+		yamlText: void 0,
+		entry: void 0,
+		yaml: {
+			state: "conflict",
+			detail: `${WORKSPACE_YAML} is a reparse point — refusing to follow it`
+		}
+	};
+	if (stat !== void 0 && !stat.isFile()) return {
+		yamlPath,
+		yamlText: void 0,
+		entry: void 0,
+		yaml: {
+			state: "conflict",
+			detail: `${WORKSPACE_YAML} exists but is not a plain file`
+		}
+	};
+	if (stat === void 0) return {
+		yamlPath,
+		yamlText: void 0,
+		entry: void 0,
+		yaml: { state: "absent" }
+	};
+	let text;
+	try {
+		text = readFileSync(yamlPath, "utf8");
+	} catch (error) {
+		return {
+			yamlPath,
+			yamlText: void 0,
+			entry: void 0,
+			yaml: {
+				state: "unreadable",
+				detail: describeError(error)
+			}
+		};
+	}
+	let keys;
+	try {
+		keys = parseWorkspaceYamlKeys(text, yamlPath);
+	} catch (error) {
+		return {
+			yamlPath,
+			yamlText: text,
+			entry: void 0,
+			yaml: {
+				state: "unreadable",
+				detail: describeError(error)
+			}
+		};
+	}
+	const entry = keys.get("packageImportMethod");
+	if (entry === void 0) return {
+		yamlPath,
+		yamlText: text,
+		entry,
+		yaml: { state: "absent" }
+	};
+	if (entry.kind === "scalar" && entry.value === "copy") return {
+		yamlPath,
+		yamlText: text,
+		entry,
+		yaml: { state: "copy" }
+	};
+	const detail = entry.kind === "scalar" ? `packageImportMethod is ${JSON.stringify(entry.value)}` : "packageImportMethod has a block or complex value";
+	return {
+		yamlPath,
+		yamlText: text,
+		entry,
+		yaml: {
+			state: "conflict",
+			detail
+		}
+	};
+}
+/**
+* Discover the confirmed profiles and scan the whole home. Shared by the
+* read-only report and `--apply` so both look at exactly the same world.
+* @param home - the DSH home (canonicalized inside).
+* @returns the inspected home, profiles, skipped entries, and scan counts.
+*/
+function inspectHome(home) {
+	let stat;
+	try {
+		stat = lstatSync(home);
+	} catch (error) {
+		throw new Error(`the DSH home ${home} cannot be inspected: ${describeError(error)}`);
+	}
+	if (stat.isSymbolicLink()) throw new Error(`the DSH home ${home} is a reparse point — refusing to work through it`);
+	const canonical = canonicalPath$1(home);
+	if (!stat.isDirectory()) throw new Error(`the DSH home ${canonical} is not a directory`);
+	const scan = {
+		directories: 0,
+		files: 0,
+		multiLinkTotal: 0,
+		multiLinkPaths: [],
+		uninspectable: [],
+		uninspectableTotal: 0
+	};
+	const uninspectable = (path, error) => {
+		scan.uninspectableTotal += 1;
+		if (scan.uninspectable.length < SAMPLE_CAP) scan.uninspectable.push({
+			path,
+			reason: describeError(error)
+		});
+	};
+	const walk = (dir) => {
+		scan.directories += 1;
+		let names;
+		try {
+			names = readdirSync(dir);
+		} catch (error) {
+			uninspectable(dir, error);
+			return;
+		}
+		for (const name of names) {
+			const entryPath = join(dir, name);
+			let entry;
+			try {
+				entry = lstatSync(entryPath);
+			} catch (error) {
+				uninspectable(entryPath, error);
+				continue;
+			}
+			if (entry.isSymbolicLink()) {
+				scan.files += 1;
+				continue;
+			}
+			if (entry.isDirectory()) {
+				walk(entryPath);
+				continue;
+			}
+			scan.files += 1;
+			if (entry.nlink > 1) {
+				scan.multiLinkTotal += 1;
+				if (scan.multiLinkPaths.length < SAMPLE_CAP) scan.multiLinkPaths.push(entryPath);
+			}
+		}
+	};
+	walk(canonical);
+	const profilesDir = join(canonical, "profiles");
+	const profiles = [];
+	const nonProfileEntries = [];
+	let listing = [];
+	try {
+		const profilesStat = lstatSync(profilesDir);
+		if (profilesStat.isSymbolicLink()) throw new Error(`${profilesDir} is a reparse point — refusing to work through it`);
+		if (profilesStat.isDirectory()) listing = readdirSync(profilesDir);
+		else nonProfileEntries.push(profilesDir);
+	} catch (error) {
+		const code = error.code;
+		if (code === "ENOENT" || code === "ENOTDIR") {} else if (error instanceof Error && error.message.includes("reparse point")) throw error;
+		else uninspectable(profilesDir, error);
+	}
+	for (const name of listing) {
+		const dir = join(profilesDir, name);
+		let entry;
+		try {
+			entry = lstatSync(dir);
+		} catch (error) {
+			uninspectable(dir, error);
+			continue;
+		}
+		if (entry.isSymbolicLink() || !entry.isDirectory() || !isConfirmedProfile(dir)) {
+			nonProfileEntries.push(dir);
+			continue;
+		}
+		profiles.push({
+			name,
+			path: dir,
+			...inspectYaml(dir)
+		});
+	}
+	return {
+		home: canonical,
+		profiles,
+		nonProfileEntries,
+		scan
+	};
+}
+const toReport = (inspected) => ({
+	home: inspected.home,
+	profiles: inspected.profiles.map(({ name, path, yaml }) => ({
+		name,
+		path,
+		yaml
+	})),
+	nonProfileEntries: inspected.nonProfileEntries,
+	scan: { ...inspected.scan },
+	incomplete: inspected.scan.uninspectableTotal > 0
+});
+/**
+* Read-only inspection of a DSH home: confirmed profiles under `profiles/`,
+* each one's `packageImportMethod` verdict, and a whole-home `lstat` scan
+* counting directories, files, multi-link files, and uninspectable entries.
+* Nothing is written. The report is `incomplete` — never clean — whenever any
+* entry could not be inspected.
+* @param home - the DSH home to inspect (canonicalized).
+* @returns the isolation report.
+*/
+function isolateReport(home) {
+	return toReport(inspectHome(home));
+}
+/**
+* Write `packageImportMethod: copy` into every fixable confirmed profile.
+* A missing file receives the upstream profile template plus the copy line;
+* a missing key is appended; a same-line non-`copy` scalar is replaced by
+* byte range so comments and CRLF survive; a block/complex/duplicate-key or
+* unreadable file is refused untouched. Every write lands atomically through
+* a sibling temp file + rename, and the command never descends or writes
+* through a reparse point.
+* @param home - the DSH home to migrate (canonicalized).
+* @returns the read verdict plus one action per confirmed profile.
+*/
+function applyIsolateConfig(home) {
+	const inspected = inspectHome(home);
+	const actions = [];
+	for (const profile of inspected.profiles) {
+		const yaml = profile.yaml;
+		if (yaml.state === "copy") {
+			actions.push({
+				name: profile.name,
+				action: "noop",
+				detail: "packageImportMethod: copy is already set"
+			});
+			continue;
+		}
+		if (yaml.state === "unreadable" || yaml.state === "conflict" && profile.entry?.kind !== "scalar") {
+			actions.push({
+				name: profile.name,
+				action: "refused",
+				...yaml.detail === void 0 ? {} : { detail: yaml.detail }
+			});
+			continue;
+		}
+		const next = yaml.state === "conflict" ? profile.yamlText.slice(0, profile.entry.valueStart) + "copy" + profile.yamlText.slice(profile.entry.valueEnd) : profile.yamlText === void 0 ? "packages:\n  - .\n\nnodeLinker: hoisted\nautoInstallPeers: false\npackageImportMethod: copy\n" : `${profile.yamlText.endsWith("\n") ? profile.yamlText : `${profile.yamlText}\n`}packageImportMethod: copy\n`;
+		try {
+			writeAtomically(profile.yamlPath, next);
+			actions.push({
+				name: profile.name,
+				action: yaml.state === "conflict" ? "replaced" : "written",
+				detail: "packageImportMethod: copy"
+			});
+		} catch (error) {
+			actions.push({
+				name: profile.name,
+				action: "refused",
+				detail: `write failed: ${describeError(error)}`
+			});
+		}
+	}
+	return {
+		...toReport(inspected),
+		actions
+	};
+}
+/**
+* Atomically replace (or create) a `pnpm-workspace.yaml`: the new text lands
+* in a sibling temp file which is renamed into place, so a failure leaves the
+* original untouched. A reparse point or non-file at the target is refused —
+* the write never crosses it.
+*/
+function writeAtomically(path, text) {
+	let target;
+	try {
+		target = lstatSync(path);
+	} catch {
+		target = void 0;
+	}
+	if (target !== void 0 && (target.isSymbolicLink() || !target.isFile())) throw new Error(`refusing to write through ${path}: not a plain file`);
+	const temp = `${path}.mrw-${process.pid}.tmp`;
+	const descriptor = openSync(temp, "wx");
+	try {
+		try {
+			writeFileSync(descriptor, text);
+		} finally {
+			closeSync(descriptor);
+		}
+		renameSync(temp, path);
+	} catch (error) {
+		try {
+			rmSync(temp, { force: true });
+		} catch {}
+		throw error;
+	}
+}
+const isInside = (path, dir) => path === dir || path.startsWith(dir.endsWith("/") ? dir : `${dir}/`) || path.startsWith(dir.endsWith("\\") ? dir : `${dir}\\`);
+const isPlainDir = (path) => {
+	try {
+		return lstatSync(path).isDirectory() && !lstatSync(path).isSymbolicLink();
+	} catch {
+		return false;
+	}
+};
+const powershellQuote = (value) => `'${value.replaceAll("'", "''")}'`;
+/**
+* The remediation steps the user must run by hand — this command writes
+* configuration only. For every confirmed profile whose dependencies still
+* need re-installing as copies (config changed under it, or links were seen
+* inside it), the steps say: quit the hosts using it, remove its
+* `node_modules` yourself, reinstall from its lockfile. Refused profiles get
+* a manual-resolution line instead of automated steps.
+* @param report - the {@link ApplyReport} (or a check report) to explain.
+* @returns the guidance lines, in English.
+*/
+function remediationSteps(report) {
+	const actions = "actions" in report ? report.actions : void 0;
+	const actionOf = (name) => actions?.find((action) => action.name === name)?.action;
+	const needsWork = [];
+	const manual = [];
+	for (const profile of report.profiles) {
+		const action = actionOf(profile.name);
+		if (action === "refused" || action === void 0 && profile.yaml.state === "unreadable" || action === void 0 && profile.yaml.state === "conflict") {
+			manual.push(profile);
+			continue;
+		}
+		const nodeModules = join(profile.path, "node_modules");
+		const hasModules = isPlainDir(nodeModules);
+		const linksSeen = report.scan.multiLinkPaths.some((path) => isInside(path, nodeModules)) || hasModules && report.scan.multiLinkTotal > report.scan.multiLinkPaths.length;
+		if (!hasModules && !linksSeen) continue;
+		needsWork.push(profile);
+	}
+	const lines = [];
+	if (needsWork.length > 0) {
+		lines.push("Profiles that still carry hardlinked dependencies — configuration is set, the objects on disk are not yet copies:");
+		for (const profile of needsWork) {
+			lines.push(`  profile ${JSON.stringify(profile.name)} — quit every DSH host using it, then in PowerShell:`);
+			lines.push(`    Remove-Item -Recurse -Force ${powershellQuote(join(profile.path, "node_modules"))}`);
+			lines.push(`    pnpm --dir ${powershellQuote(profile.path)} install`);
+		}
+		lines.push("  The command never deletes node_modules and never runs pnpm — the reinstall is yours, per the profile lockfile, while no host is running.");
+	}
+	for (const profile of manual) lines.push(`  profile ${JSON.stringify(profile.name)} was refused — resolve its ${WORKSPACE_YAML} by hand, then apply the same reinstall steps.`);
+	lines.push("Setting the config does not isolate existing dependencies: hardlinks stay hardlinks until the reinstall replaces them.");
+	lines.push("Copy import does not repair Administrators ownership or deny ACEs already written onto the pnpm store or other projects; review those separately — no automatic reset exists.");
+	lines.push("Profiles created later need the same configuration — re-run this check after adding one.");
+	return lines;
+}
+//#endregion
+//#region src/command.ts
+/**
+* The user-facing surface: the `/workspace-folders` command and the panel's
+* RPC channel.
+*
+* They share one module because they are one thing — the operator-facing edge
+* over `ctx.multiRootRegistry`. The command serves the text surfaces (the
+* composer, headless diagnostics) and the channel serves the browser panel;
+* both resolve the same canonical workspace root, call the same registry, and
+* report the same `RootValidationCode` values.
+*
+* Both are also the two places a READ happens, so both go through the same
+* revalidation entry point: `registry.refresh()` re-stats every registered
+* directory, re-resolves it against the directory it was granted for, and
+* republishes the scope BEFORE the list is rendered. Listing is therefore
+* enough to notice that a directory disappeared (and enough to bring a
+* restored one back) — which is what the panel's "Retry" button and the
+* command's `list` both promise.
+*
+* Both halves are SOFT: the command registers only where a command registry is
+* composed, and the channel only where a host Connection and web server exist
+* (web), so a headless profile mounts this row with zero effect on the
+* providers.
+*
+* The command's own text is English: a host-side command handler has no active
+* locale to consult (the browser owns locale state). The panel is bilingual.
+* That split is recorded in the M3 plan and the requirements as a known limit.
+*
+* @module @dsh-electron/dsh-plugin-multi-root-workspace/command
+*/
+/** Services this row needs before it may activate. */
+const inject = [
+	"commands",
+	"sandboxPolicy",
+	"multiRootRegistry"
+];
+/** The command name, without the leading slash. */
+const COMMAND_NAME = "workspace-folders";
+/**
+* Parse the text that follows `/workspace-folders`.
+* @param rawInput - the verbatim `rawInput` of the command invocation.
+* @returns the subcommand and its remaining text.
+* @throws {RootValidationError} `invalid-ref` for an unknown subcommand.
+*/
+function parseFoldersCommand(rawInput) {
+	const trimmed = rawInput.trim();
+	if (trimmed === "") return {
+		verb: "list",
+		rest: ""
+	};
+	const match = /^(\S+)(?:\s+([\s\S]*))?$/.exec(trimmed);
+	const verb = match?.[1] ?? "";
+	const rest = (match?.[2] ?? "").trim();
+	switch (verb) {
+		case "list":
+		case "add":
+		case "remove":
+		case "alias":
+		case "access":
+		case "reveal":
+		case "isolate-profiles":
+		case "help": return {
+			verb,
+			rest
+		};
+		default: throw new RootValidationError("invalid-ref", `unknown subcommand "${verb}"; try /${COMMAND_NAME} help`);
+	}
+}
+/** Strip one layer of matching quotes from an operator-supplied path. */
+function unquote(text) {
+	if (text.length >= 2) {
+		const first = text[0];
+		const last = text[text.length - 1];
+		if (first === "\"" && last === "\"" || first === "'" && last === "'") return text.slice(1, -1);
+	}
+	return text;
+}
+/**
+* Render the roots report the command returns. Additional roots are numbered
+* from 1, which is the numbering every other subcommand accepts; the workspace
+* root is never numbered because it cannot be removed.
+* @param primaryRoot - the canonical workspace root.
+* @param statuses - the registry's status list.
+* @param unavailable - the store failure, when the registry could not read it.
+* @returns the report text.
+*/
+function renderRootsReport(primaryRoot, statuses, unavailable, limit, mode) {
+	const lines = [`Workspace root (primary; access follows the current sandbox mode): ${primaryRoot}`];
+	if (unavailable !== void 0) {
+		lines.push(`Root registry unavailable: ${unavailable}`);
+		return lines.join("\n");
+	}
+	if (statuses.length === 0) {
+		lines.push(`No additional roots. Add one with /${COMMAND_NAME} add <absolute path>.`);
+		return lines.join("\n");
+	}
+	for (const [index, status] of statuses.entries()) {
+		const alias = status.alias === void 0 ? "" : ` [${status.alias}]`;
+		const state = status.state === "available" ? "" : ` (${status.state}: ${status.detail ?? "unavailable"})`;
+		lines.push(`  ${index + 1} ${status.path}${alias} (${status.access})${state}`);
+	}
+	const withheld = statuses.length - availableRoots(statuses).length;
+	if (withheld > 0) lines.push(`${withheld} root(s) are registered but not writable right now; restore the directory and run /${COMMAND_NAME} list, or remove the entry.`);
+	if (limit !== void 0) {
+		lines.push(`${statuses.length} of ${limit} additional roots.`);
+		if (statuses.length > limit) lines.push(`Warning: the store exceeds the configured limit of ${limit}; every stored root stays granted, only new adds are refused.`);
+	}
+	const writable = statuses.filter((status) => status.state === "available" && status.access !== "read-only" && (mode !== "read-only" || status.access === "read-write")).length;
+	lines.push(`Writable additional roots${mode === void 0 ? "" : " under the current mode"}: ${writable} of ${statuses.length}.`);
+	return lines.join("\n");
+}
+/**
+* Register the command and, where a host Connection exists, the panel channel.
+* @param ctx - the host context carrying `commands`, `sandboxPolicy`, and the registry.
+* @param config - the row's config; `dshHome` feeds `isolate-profiles` only.
+*/
+function apply(ctx, config = {}) {
+	ctx.commands.register({
+		name: COMMAND_NAME,
+		description: "List, add, remove, alias, or reveal the additional workspace roots of this session, or isolate DSH profile imports",
+		input: { hint: "[list|add [path] [--inherit|--read-only|--read-write]|remove <n|path>|alias <n|path> [name]|access <n|path> <level>|reveal <n|path>|isolate-profiles [--apply]|help]" },
+		handler: async (invocation) => await runCommand(ctx, invocation, config)
+	});
+	ctx.inject(["connection", "webServer"], (connectionCtx) => {
+		const connection = connectionCtx.root.get("connection");
+		if (connection === void 0) {
+			ctx.logger.warn("multi-root: connection resolved without the service; the panel channel is not mounted");
+			return;
+		}
+		const dispose = connection.rpc.handle(PANEL_CHANNEL, async (endpoint, payload) => await dispatchPanelRequest(ctx, endpoint, payload));
+		return () => {
+			dispose();
+		};
+	});
+}
+/** Execute one `/workspace-folders` invocation. */
+async function runCommand(ctx, invocation, config) {
+	let parsed;
+	try {
+		parsed = parseFoldersCommand(invocation.rawInput);
+	} catch (error) {
+		return {
+			kind: "error",
+			text: failureText(error)
+		};
+	}
+	const policy = ctx.sandboxPolicy.resolve({ session: invocation.agent.session });
+	const primaryRoot = policy.workspaceRoot;
+	const registry = ctx.multiRootRegistry;
+	try {
+		switch (parsed.verb) {
+			case "help": return {
+				kind: "success",
+				text: helpText()
+			};
+			case "list": return {
+				kind: "success",
+				text: await report(registry, primaryRoot, policy.mode)
+			};
+			case "add": {
+				const { text: rest, access } = splitAddAccess(parsed.rest);
+				const typed = unquote(rest);
+				const path = typed === "" ? await pickRootPath(ctx, invocation.signal) : typed;
+				if (path === void 0) return {
+					kind: "error",
+					text: `/${COMMAND_NAME}: no directory was selected; pass an absolute path or use the Workspace Folders panel`
+				};
+				await registry.add(primaryRoot, {
+					path,
+					...access === void 0 ? {} : { access }
+				});
+				return {
+					kind: "success",
+					text: await report(registry, primaryRoot, policy.mode)
+				};
+			}
+			case "remove": {
+				const { ref } = await targetOf(registry, primaryRoot, parsed.rest);
+				await registry.removeAt(primaryRoot, ref);
+				return {
+					kind: "success",
+					text: await report(registry, primaryRoot, policy.mode)
+				};
+			}
+			case "alias": {
+				const { text: reference, rest: alias } = splitReference(parsed.rest);
+				const { ref } = await targetOf(registry, primaryRoot, reference);
+				await registry.setAlias(primaryRoot, ref, alias === "" ? void 0 : unquote(alias));
+				return {
+					kind: "success",
+					text: await report(registry, primaryRoot, policy.mode)
+				};
+			}
+			case "access": {
+				const { text: reference, rest: level } = splitReference(parsed.rest);
+				const access = parseAccessLevel(level);
+				const { ref } = await targetOf(registry, primaryRoot, reference);
+				await registry.setAccess(primaryRoot, ref, access);
+				return {
+					kind: "success",
+					text: await report(registry, primaryRoot, policy.mode)
+				};
+			}
+			case "reveal": {
+				const { status: target } = await targetOf(registry, primaryRoot, parsed.rest);
+				await revealRoot(ctx, target.path);
+				return {
+					kind: "success",
+					text: `revealed ${target.path}`
+				};
+			}
+			case "isolate-profiles": {
+				if (parsed.rest !== "" && parsed.rest !== "--apply") throw new RootValidationError("invalid-ref", `isolate-profiles accepts only --apply or nothing, got "${parsed.rest}"`);
+				const home = isolateHome(config);
+				return {
+					kind: "success",
+					text: renderIsolateReport(parsed.rest === "--apply" ? applyIsolateConfig(home) : isolateReport(home))
+				};
+			}
+		}
+	} catch (error) {
+		return {
+			kind: "error",
+			text: failureText(error)
+		};
+	}
+}
+/**
+* The current report for one primary root, after re-checking every registered
+* directory. The refresh is what makes the report describe the present rather
+* than the moment the process started.
+*/
+async function report(registry, primaryRoot, mode) {
+	const statuses = await registry.refresh(primaryRoot);
+	return renderRootsReport(canonicalRoot(primaryRoot), statuses, registry.unavailable, registry.limit, mode);
+}
+/** Render a failure the way the composer displays it. */
+function failureText(error) {
+	if (error instanceof RootValidationError) return `/${COMMAND_NAME}: ${error.code}: ${error.message}`;
+	return `/${COMMAND_NAME}: ${error instanceof Error ? error.message : String(error)}`;
+}
+/**
+* The DSH home `isolate-profiles` inspects — the row config's `dshHome`,
+* an absolute path. Missing or invalid is a verb failure, not a guess: the
+* home is the protected root the deny writer scans, and a wrong guess would
+* either read the wrong tree or pretend a home was checked when none was.
+*/
+function isolateHome(config) {
+	const home = config.dshHome;
+	if (typeof home !== "string" || !isAbsolute(home)) throw new RootValidationError("config-invalid", `isolate-profiles needs this row's dshHome config to be an absolute path, got ${JSON.stringify(home)}`);
+	return home;
+}
+/**
+* Render the `isolate-profiles` report: one line per confirmed profile, the
+* whole-home scan counts, then — on `--apply` — the per-profile action and
+* the remediation steps. An incomplete scan is always called out, because an
+* uninspectable entry is not evidence the home is clean.
+*/
+function renderIsolateReport(report) {
+	const lines = [`/${COMMAND_NAME} isolate-profiles — pnpm import isolation for the DSH home`, `DSH home: ${report.home}`];
+	if (report.profiles.length === 0) lines.push("No confirmed profiles under profiles/ (a profile is a directory whose package.json has dsh.profile as an object).");
+	for (const profile of report.profiles) {
+		const yaml = profile.yaml;
+		const state = yaml.state === "copy" ? "packageImportMethod: copy — isolated on the next install" : yaml.state === "absent" ? "packageImportMethod is unset — pnpm defaults to hardlinks" : yaml.state === "conflict" ? `conflict: ${yaml.detail ?? "needs a manual fix"}` : `unreadable: ${yaml.detail ?? "cannot be read"}`;
+		lines.push(`  ${profile.name}: ${state}`);
+	}
+	if (report.nonProfileEntries.length > 0) {
+		lines.push(`${report.nonProfileEntries.length} entr(ies) under profiles/ are not confirmed profiles and were left untouched:`);
+		for (const entry of report.nonProfileEntries) lines.push(`    ${entry}`);
+	}
+	const scan = report.scan;
+	lines.push(`Home scan: scanned ${scan.directories} dirs/${scan.files} files, ${scan.multiLinkTotal} multi-link files, ${scan.uninspectableTotal} uninspectable`);
+	for (const path of scan.multiLinkPaths) lines.push(`    multi-link: ${path}`);
+	if (scan.multiLinkTotal > scan.multiLinkPaths.length) lines.push(`    … and ${scan.multiLinkTotal - scan.multiLinkPaths.length} more multi-link file(s)`);
+	for (const entry of scan.uninspectable) lines.push(`    uninspectable: ${entry.path} (${entry.reason})`);
+	if (report.scan.uninspectableTotal > scan.uninspectable.length) lines.push(`    … and ${scan.uninspectableTotal - scan.uninspectable.length} more uninspectable entr(ies)`);
+	if (report.incomplete) lines.push(`INCOMPLETE: ${scan.uninspectableTotal} entr(ies) could not be inspected — this report must not be read as clean.`);
+	if (report.profiles.filter((profile) => profile.yaml.state === "unreadable" || profile.yaml.state === "conflict").length > 0) lines.push("Profiles listed as conflict/unreadable are refused by --apply: fix or remove their pnpm-workspace.yaml by hand, then re-run.");
+	if ("actions" in report) {
+		lines.push("Apply results:");
+		for (const action of report.actions) lines.push(`  ${action.name}: ${action.action}${action.detail === void 0 ? "" : ` — ${action.detail}`}`);
+		lines.push(...remediationSteps(report));
+	} else {
+		lines.push(`This was a read-only check; run /${COMMAND_NAME} isolate-profiles --apply to write packageImportMethod: copy into every fixable profile.`);
+		lines.push("A configured profile still needs its dependencies reinstalled to become copies — the check reports, --apply configures, the reinstall is yours.");
+	}
+	return lines.join("\n");
+}
+/** The command's own help text. */
+function helpText() {
+	return [
+		`/${COMMAND_NAME} — additional workspace roots of this session`,
+		`  /${COMMAND_NAME} list`,
+		`  /${COMMAND_NAME} add [absolute path] [--inherit|--read-only|--read-write]   (no path opens the directory picker when one is composed)`,
+		`  /${COMMAND_NAME} remove <n|path>`,
+		`  /${COMMAND_NAME} alias <n|path> [name]  (no name clears the alias)`,
+		`  /${COMMAND_NAME} access <n|path> inherit|read-only|read-write`,
+		`  /${COMMAND_NAME} reveal <n|path>`,
+		`  /${COMMAND_NAME} isolate-profiles [--apply]   (report or set packageImportMethod: copy for every profile under $DSH_HOME)`,
+		"Roots are canonicalized before they are stored: `~` expands, and a duplicate, a nested directory,",
+		"or this session's own workspace root is rejected.",
+		"Access levels: `inherit` follows the session mode; `read-only` refuses writes under every mode;",
+		"`read-write` stays writable even in a read-only session.",
+		"`isolate-profiles` exists because a Windows deny ACE applies to the file object, not one hardlink name:",
+		"profiles whose dependencies are hardlinked into the pnpm store make `$DSH_HOME` unsafe to deny;",
+		"the check scans the whole home (links > 1, uninspectable entries) and --apply rewrites the yaml atomically,",
+		"but the existing hardlinks are replaced only by the reinstall the report prints."
+	].join("\n");
+}
+/**
+* Split `add`'s argument into the path text and the access flag. Either flag
+* is accepted as the first or the last token, so a path containing the flag
+* spelling (quoted or unquoted) is never mistaken for the flag.
+*
+* The access is TRI-STATE on purpose: it stays `undefined` when the operator
+* named no level. `registry.add` revives a withheld record with its stored
+* access unless a level is given explicitly, so forwarding a default here
+* would silently change the registration's authority.
+*/
+function splitAddAccess(text) {
+	const trimmed = text.trim();
+	for (const access of [
+		"read-only",
+		"read-write",
+		"inherit"
+	]) {
+		const flag = `--${access}`;
+		if (trimmed === flag) return {
+			text: "",
+			access
+		};
+		if (trimmed.startsWith(`${flag} `) || trimmed.startsWith(`${flag}\t`)) return {
+			text: trimmed.slice(flag.length).trim(),
+			access
+		};
+		if (new RegExp(`\\s${flag}$`).test(trimmed)) return {
+			text: trimmed.slice(0, -flag.length).trim(),
+			access
+		};
+	}
+	return {
+		text: trimmed,
+		access: void 0
+	};
+}
+/** Parse the access level an `access` subcommand must end with. */
+function parseAccessLevel(text) {
+	const trimmed = text.trim();
+	if (trimmed === "read-only" || trimmed === "read-write" || trimmed === "inherit") return trimmed;
+	throw new RootValidationError("invalid-ref", `the access level must be inherit, read-only, or read-write, got "${trimmed || "nothing"}"`);
+}
+/**
+* Split `alias`'s argument into a reference and the alias text.
+*
+* The reference is the first whitespace-delimited token, except when it opens
+* with a quote: a quoted path may contain spaces, so the whole quoted span is
+* the reference and the remainder is the alias.
+*/
+function splitReference(text) {
+	const trimmed = text.trim();
+	if (trimmed === "") throw new RootValidationError("invalid-ref", "a root reference is required");
+	if (trimmed.startsWith("\"") || trimmed.startsWith("'")) {
+		const quote = trimmed[0] ?? "";
+		const end = trimmed.indexOf(quote, 1);
+		if (end > 0) return {
+			text: trimmed.slice(0, end + 1),
+			rest: trimmed.slice(end + 1).trim()
+		};
+	}
+	const match = /^(\S+)(?:\s+([\s\S]*))?$/.exec(trimmed);
+	return {
+		text: match?.[1] ?? "",
+		rest: (match?.[2] ?? "").trim()
+	};
+}
+/**
+* Resolve an operator reference — a 1-based number, a path, or an id — to the
+* registered root it names.
+* @param registry - the registry to read.
+* @param primaryRoot - the workspace root the registrations belong to.
+* @param text - the operator's text.
+* @returns the matched status, after re-checking the registered directories.
+* @throws {RootValidationError} `invalid-ref` for empty text, `not-found` when nothing matches.
+*/
+async function targetOf(registry, primaryRoot, text) {
+	const trimmed = text.trim();
+	if (trimmed === "") throw new RootValidationError("invalid-ref", "a root reference is required");
+	const statuses = await registry.refresh(primaryRoot);
+	let status;
+	if (/^\d+$/.test(trimmed)) {
+		const ordinal = Number(trimmed);
+		status = resolveRootRef(statuses, {
+			kind: "ordinal",
+			ordinal
+		});
+		return {
+			status,
+			ref: entryRootRef(status, ordinal)
+		};
+	}
+	const asPath = unquote(trimmed);
+	if (asPath === "~" || asPath.startsWith("~") || asPath.startsWith("/") || /^[A-Za-z]:[\\/]/.test(asPath)) status = resolveRootRef(statuses, {
+		kind: "path",
+		path: asPath
+	});
+	else status = resolveRootRef(statuses, {
+		kind: "id",
+		id: trimmed
+	});
+	const ordinal = statuses.indexOf(status) + 1;
+	return {
+		status,
+		ref: entryRootRef(status, ordinal)
+	};
+}
+/**
+* Derive the primary root a panel request may act on.
+*
+* The browser names a live session; the host looks that session up and uses
+* its immutable cwd. There is no client-supplied path and no deployment-default
+* fallback: a panel call without a real host session has no workspace to
+* manage. Property access would demand an injected `sessions` dependency this
+* row does not name, so the lookup stays an explicit sibling `get` (the same
+* pattern as `directoryPicker` / `subprocess`).
+*
+* @param ctx - the host context that may carry `sessions`.
+* @param sessionId - the id the panel sent; already required by the wire schema.
+* @returns the canonical cwd of that session.
+* @throws {RootValidationError} `session-not-found` when the service is absent,
+*   the id does not name a live session, or that session has no cwd.
+*/
+function resolvePanelPrimaryRoot(ctx, sessionId) {
+	const session = ctx.get("sessions")?.get(sessionId);
+	const cwd = session?.header.cwd;
+	if (session === void 0 || cwd === void 0 || cwd === "") throw new RootValidationError("session-not-found", `session "${sessionId}" is not an active host session`, { reference: sessionId });
+	return canonicalPath(cwd);
+}
+/** Project one status into the panel's view. */
+function toRootView(status, index) {
+	return {
+		ordinal: index + 1,
+		id: status.id,
+		path: status.path,
+		...status.alias === void 0 ? {} : { alias: status.alias },
+		addedAt: status.addedAt,
+		state: status.state,
+		access: status.access,
+		...status.detail === void 0 ? {} : { detail: status.detail }
+	};
+}
+/**
+* Resolve the display name of the primary root from the host's workspace
+* registry — the title the operator set in the workspace browser, falling back
+* to nothing (the panel then shows the path's basename).
+*
+* The registry is an optional sibling service, read through the explicit
+* lookup like `sessions`/`subprocess`: property access would demand an
+* injected dependency this row does not name. Membership wins over cwd, which
+* mirrors the host's own session→workspace resolution.
+*/
+async function primaryNameOf(ctx, primaryRoot, request) {
+	const registry = ctx.get("workspaceRegistry");
+	if (registry === void 0) return void 0;
+	try {
+		const sessionId = request.sessionId;
+		if (sessionId !== void 0 && sessionId !== "") {
+			const member = registry.list().find((workspace) => workspace.sessionIds.includes(sessionId));
+			if (member !== void 0) return member.title;
+		}
+		return (await registry.resolveByPath(primaryRoot))?.title;
+	} catch (error) {
+		ctx.logger.warn("multi-root: workspace title lookup failed; the panel falls back to the path basename", error);
+		return;
+	}
+}
+/**
+* Build the panel's view of one primary root, after re-checking every
+* registered directory — the panel's read path is the same revalidation the
+* command uses, so "the list the operator sees" is always the list the scope
+* currently enforces.
+*/
+async function rootsViewOf(ctx, registry, primaryRoot, request) {
+	const statuses = await registry.refresh(primaryRoot);
+	const unavailable = registry.unavailable;
+	const primaryName = await primaryNameOf(ctx, primaryRoot, request);
+	const session = ctx.get("sessions")?.get(request.sessionId);
+	const effectiveCwd = session === void 0 ? void 0 : effectiveDirectory(ctx, session);
+	if (session === void 0) throw new RootValidationError("session-not-found", "the panel session closed during the request");
+	const policy = ctx.sandboxPolicy.resolve({ session });
+	const scope = ctx.get("multiRootScope");
+	return {
+		primaryRoot: canonicalRoot(primaryRoot),
+		...primaryName === void 0 ? {} : { primaryName },
+		...effectiveCwd === void 0 ? {} : { effectiveCwd },
+		mode: policy.mode,
+		cappedTools: scope?.toolCaps() ?? [],
+		toolAccessInvalid: scope?.toolAccessInvalid ?? false,
+		roots: statuses.map((status, index) => ({
+			...toRootView(status, index),
+			effectiveAccess: status.state === "available" ? effectiveRootAccess(status.access, policy.mode) : "unavailable"
+		})),
+		limit: registry.limit,
+		count: statuses.length,
+		...unavailable === void 0 ? {} : { unavailable }
+	};
+}
+/**
+* Serve one panel endpoint.
+*
+* The payload is validated before anything acts on it: it arrived from a
+* browser, and the host is the side that must not be surprised by a shape it
+* did not expect (see `contract.ts`, which owns the schema both halves share).
+* A malformed request is reported as `panel/bad-request` rather than throwing
+* through the channel.
+*/
+async function dispatchPanelRequest(ctx, endpoint, payload) {
+	try {
+		const parsed = parsePanelCall(endpoint, payload);
+		if (!parsed.ok) return {
+			ok: false,
+			error: {
+				code: "panel/bad-request",
+				message: parsed.message,
+				details: {}
+			}
+		};
+		const request = parsed.value;
+		const registry = ctx.multiRootRegistry;
+		const primaryRoot = resolvePanelPrimaryRoot(ctx, request.sessionId);
+		switch (request.endpoint) {
+			case "list": return {
+				ok: true,
+				value: await rootsViewOf(ctx, registry, primaryRoot, request)
+			};
+			case "add":
+				if (request.path === void 0 || request.path === "") throw new RootValidationError("missing", "a directory path is required");
+				await registry.add(primaryRoot, {
+					path: request.path,
+					...request.alias === void 0 ? {} : { alias: request.alias },
+					...request.access === void 0 ? {} : { access: request.access }
+				});
+				return {
+					ok: true,
+					value: await rootsViewOf(ctx, registry, primaryRoot, request)
+				};
+			case "setAccess":
+				if (request.access === void 0) throw new RootValidationError("invalid-ref", "an access level is required");
+				await registry.setAccess(primaryRoot, requireEntry(request), request.access);
+				return {
+					ok: true,
+					value: await rootsViewOf(ctx, registry, primaryRoot, request)
+				};
+			case "remove":
+				await registry.removeAt(primaryRoot, requireEntry(request));
+				return {
+					ok: true,
+					value: await rootsViewOf(ctx, registry, primaryRoot, request)
+				};
+			case "alias":
+				await registry.setAlias(primaryRoot, requireEntry(request), request.alias);
+				return {
+					ok: true,
+					value: await rootsViewOf(ctx, registry, primaryRoot, request)
+				};
+			case "move":
+				await registry.move(primaryRoot, requireEntry(request), request.beforeEntry !== void 0 ? entryRefOf(request.beforeEntry) : request.beforeId === void 0 ? void 0 : {
+					kind: "id",
+					id: request.beforeId
+				});
+				return {
+					ok: true,
+					value: await rootsViewOf(ctx, registry, primaryRoot, request)
+				};
+			case "reveal": {
+				const ref = requireEntry(request);
+				const target = resolveRootRef(await registry.refresh(primaryRoot), ref);
+				await revealRoot(ctx, target.path);
+				return {
+					ok: true,
+					value: { revealed: target.path }
+				};
+			}
+		}
+	} catch (error) {
+		if (error instanceof RootValidationError) return {
+			ok: false,
+			error: {
+				code: error.code,
+				message: error.message,
+				details: {}
+			}
+		};
+		return {
+			ok: false,
+			error: {
+				code: "panel/internal",
+				message: error instanceof Error ? error.message : String(error),
+				details: {}
+			}
+		};
+	}
+}
+/** Convert a validated wire snapshot to the registry's exact-entry reference. */
+function entryRefOf(entry) {
+	return {
+		kind: "entry",
+		...entry
+	};
+}
+/** Require the exact list row a mutating panel request must carry. */
+function requireEntry(request) {
+	if (request.entry !== void 0) return entryRefOf(request.entry);
+	if (request.id !== void 0 && request.id !== "") return {
+		kind: "id",
+		id: request.id
+	};
+	throw new RootValidationError("invalid-ref", "an exact root entry is required");
+}
+/**
+* Open the composed directory picker when one exists, and answer `undefined`
+* otherwise (the command then reports the missing affordance).
+*
+* Only the `native` capability can answer a host-side command: the `browse`
+* capability is an in-app dialog that only the browser panel can render.
+*/
+async function pickRootPath(ctx, signal) {
+	const picker = ctx.get("directoryPicker");
+	if (picker === void 0) return void 0;
+	const capability = picker.capability();
+	if (capability.kind !== "native") return void 0;
+	return await capability.pick(signal) ?? void 0;
+}
+/** The per-platform argv that reveals one directory in the OS file manager. */
+function revealArgv(platform, path) {
+	switch (platform) {
+		case "darwin": return [
+			"open",
+			"-R",
+			path
+		];
+		case "win32": return ["explorer", `/select,${path}`];
+		default: return ["xdg-open", path];
+	}
+}
+/**
+* Whether the file manager's exit code means the reveal was accepted.
+* `explorer.exe` answers 1 even when it successfully selected the item, so on
+* Windows both 0 and 1 are success; the other managers honor the usual 0.
+*/
+function revealAccepted(platform, exitCode) {
+	return exitCode === 0 || platform === "win32" && exitCode === 1;
+}
+/**
+* Reveal one directory in the OS file manager through `ctx.subprocess`.
+*
+* This runs no confined command and grants the agent nothing: it is an
+* operator action taken from the panel or the command line, and the process is
+* the platform's own file manager. Failures are reported to the caller.
+*/
+async function revealRoot(ctx, path) {
+	const subprocess = ctx.get("subprocess");
+	if (subprocess === void 0) throw new RootValidationError("reveal-unavailable", "revealing a root needs a process runtime, which this composition does not mount");
+	const [program = "", ...args] = revealArgv(process.platform, path);
+	const executable = await subprocess.resolveExecutable(program);
+	const handle = subprocess.spawn({
+		argv: [executable, ...args],
+		cwd: path,
+		stdio: {
+			stdin: "ignore",
+			stdout: { maxBytes: 4096 },
+			stderr: { maxBytes: 4096 }
+		},
+		graceMs: 3e3
+	});
+	const outcome = await handle.done;
+	await handle.waitForExit();
+	if (!revealAccepted(process.platform, outcome.exitCode)) throw new RootValidationError("reveal-unavailable", `the file manager exited with ${String(outcome.exitCode)}`);
+}
+//#endregion
+export { renderRootsReport as a, revealArgv as c, parseFoldersCommand as i, apply as n, resolvePanelPrimaryRoot as o, inject as r, revealAccepted as s, COMMAND_NAME as t };