@dsh-electron/dsh-plugin-multi-root-workspace 0.1.0

package/lib/roots-DyT2jgEP.js

@@ -0,0 +1,345 @@
+import { canonicalPath } from "@deepseek-ai/dsh-sandbox";
+import { isAbsolute, join, sep } from "node:path";
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+//#region src/roots.ts
+/**
+* The root vocabulary: identities, the durable record shape, the status a
+* stored record is reported with, and the validation rules every write and
+* every startup re-read passes through.
+*
+* This module is the single home of "what makes a directory a legal additional
+* root" (requirement §15). Both the registry (which persists) and the command
+* and panel surfaces (which report) speak these types, so a rule can never be
+* enforced on one path and forgotten on another.
+*
+* Rules, applied in this order — the first failure names the reason:
+*
+* 1. `not-absolute` — a relative input (after `~` expansion) is a
+*    misconfiguration, not a path to guess at.
+* 2. `missing` — the directory does not exist.
+* 3. `not-a-directory` — it exists but is not a directory.
+* 4. `equals-primary` — the canonical candidate IS the session's workspace
+*    root, which is already granted by the upstream policy.
+* 5. `primary-overlap` — the candidate lies under the workspace root, or
+*    contains it. The union grants nothing new, and the displayed list would
+*    stop matching the enforced root set.
+* 6. `duplicate` — another registered root canonicalizes to the same path.
+* 7. `nested` — the candidate lies under a registered root, or contains one.
+*    Same reasoning as rule 5, applied to the additional roots.
+*
+* The stored side of the same rules lives in {@link classifyStoredRoots}, which
+* must never throw: a registration that stopped being usable is REPORTED, not
+* deleted, so the operator can see it and remove it deliberately.
+*
+* @module @dsh-electron/dsh-plugin-multi-root-workspace/roots
+*/
+/**
+* Brand one generated uuid as an {@link AdditionalRootId}.
+* @param value - the raw uuid.
+* @returns the branded id.
+*/
+function additionalRootId(value) {
+	return value;
+}
+/** A rejected root operation; `code` is the stable contract, `message` the fallback prose. */
+var RootValidationError = class extends Error {
+	code;
+	detail;
+	/**
+	* @param code - stable failure code.
+	* @param message - human-readable fallback text (English; the panel localizes by code).
+	* @param detail - structured context, e.g. the conflicting root.
+	*/
+	constructor(code, message, detail) {
+		super(message);
+		this.code = code;
+		this.detail = detail;
+		this.name = "RootValidationError";
+	}
+};
+/**
+* Expand the one shell shorthand an operator may reasonably type, and nothing
+* else: a leading `~` (alone or as `~/…`). Every other relative spelling is
+* left intact so validation can reject it as `not-absolute` instead of
+* silently resolving it against some unrelated process cwd.
+* @param raw - the raw operator input.
+* @param home - the home directory to expand against; defaults to `os.homedir()`.
+* @returns the expanded path (still unvalidated).
+*/
+function expandRootInput(raw, home = homedir()) {
+	const trimmed = raw.trim();
+	if (trimmed === "~") return home;
+	if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) return join(home, trimmed.slice(2));
+	return trimmed;
+}
+/** Whether lexical comparison preserves case on this platform. */
+const CASE_SENSITIVE = process.platform !== "win32";
+/** Compare two canonical path spellings under the platform's case convention. */
+function comparable(path) {
+	return CASE_SENSITIVE ? path : path.toLowerCase();
+}
+/** Whether two canonical paths name the same directory on this platform. */
+function samePath(left, right) {
+	return comparable(left) === comparable(right);
+}
+/**
+* Whether `candidate` is `root` itself or lies beneath it. Both sides must
+* already be canonical: symlinks are resolved by then, so the lexical test is
+* exact for the alias cases (8.3 names, casing) the fence handles separately.
+* @param candidate - canonical path to test.
+* @param root - canonical root to test against.
+* @returns whether the candidate is contained by the root.
+*/
+function isCanonicallyUnder(candidate, root) {
+	const target = comparable(candidate);
+	const base = comparable(root);
+	if (target === base) return true;
+	return target.startsWith(base.endsWith(sep) ? base : base + sep);
+}
+/**
+* Canonicalize a directory path the way the enforcement layers do (`realpath`),
+* leaving an unreachable path untouched so the caller can report it as missing.
+* @param path - the path to canonicalize.
+* @returns the canonical path.
+*/
+function canonicalRoot(path) {
+	return canonicalPath(path);
+}
+/**
+* Judge one candidate root and return its canonical spelling.
+* @param raw - the raw operator input (a path, possibly `~`-prefixed).
+* @param context - the primary root and the currently granted roots.
+* @returns the canonical path the caller must store (and record as `recordedPath`).
+* @throws {RootValidationError} with the first rule that failed.
+*/
+function validateRootCandidate(raw, context) {
+	const expanded = expandRootInput(raw, context.home);
+	if (expanded === "") throw new RootValidationError("not-absolute", "a root path is required");
+	if (!isAbsolute(expanded)) throw new RootValidationError("not-absolute", `"${expanded}" is not an absolute path; give an absolute directory or one starting with "~/"`, { reference: expanded });
+	const canonical = canonicalRoot(expanded);
+	assertDirectory(canonical, expanded);
+	const primaryRoot = canonicalRoot(context.primaryRoot);
+	if (samePath(canonical, primaryRoot)) throw new RootValidationError("equals-primary", `"${canonical}" is this session's workspace root and is already writable`, {
+		conflict: primaryRoot,
+		reference: canonical
+	});
+	if (isCanonicallyUnder(canonical, primaryRoot) || isCanonicallyUnder(primaryRoot, canonical)) throw new RootValidationError("primary-overlap", `"${canonical}" overlaps this session's workspace root "${primaryRoot}"`, {
+		conflict: primaryRoot,
+		reference: canonical
+	});
+	for (const existing of context.existing) if (samePath(canonical, existing)) throw new RootValidationError("duplicate", `"${canonical}" is already registered`, {
+		conflict: existing,
+		reference: canonical
+	});
+	for (const existing of context.existing) {
+		if (isCanonicallyUnder(canonical, existing)) throw new RootValidationError("nested", `"${canonical}" is already covered by the registered root "${existing}"`, {
+			conflict: existing,
+			reference: canonical
+		});
+		if (isCanonicallyUnder(existing, canonical)) throw new RootValidationError("nested", `"${canonical}" contains the registered root "${existing}"; remove that root first`, {
+			conflict: existing,
+			reference: canonical
+		});
+	}
+	return canonical;
+}
+/** Assert that a canonical path is an existing directory. */
+function assertDirectory(canonical, asTyped) {
+	let stats;
+	try {
+		stats = statSync(canonical);
+	} catch {
+		throw new RootValidationError("missing", `"${asTyped}" does not exist`, { reference: asTyped });
+	}
+	if (!stats.isDirectory()) throw new RootValidationError("not-a-directory", `"${asTyped}" is not a directory`, { reference: asTyped });
+}
+/**
+* Re-judge every stored record of one primary root — the startup and refresh
+* path, which must never throw: a registration that stopped being usable is
+* REPORTED, not deleted, so the operator can see it and remove it deliberately.
+*
+* Existence and reachability are the only rules a record may recover from on
+* its own, hence `missing` and `redirected` (kept, withheld) rather than
+* `invalid` (kept, unusable).
+* @param primaryRoot - the session workspace root the records belong to.
+* @param records - the stored records, in registry order.
+* @returns one status per record, in the same order.
+*/
+function classifyStoredRoots(primaryRoot, records) {
+	const primary = canonicalRoot(primaryRoot);
+	const claimed = [];
+	const duplicated = duplicatedIds(records);
+	const statuses = [];
+	for (const [index, record] of records.entries()) {
+		const status = classifyStoredRoot(record, primary, claimed, duplicated.has(record.id), index);
+		statuses.push(status);
+		if (status.state === "available") claimed.push(status.path);
+	}
+	return statuses;
+}
+/**
+* The ids that more than one record claims. Computed for the whole list up
+* front, because "this id is duplicated" is a property of the SET: deciding it
+* while walking would make the first occurrence look fine and only the later
+* ones broken, and the first match is precisely the ambiguity being reported.
+*/
+function duplicatedIds(records) {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicated = /* @__PURE__ */ new Set();
+	for (const record of records) if (seen.has(record.id)) duplicated.add(record.id);
+	else seen.add(record.id);
+	return duplicated;
+}
+/**
+* Judge one stored record against the primary root and the roots claimed before
+* it.
+*
+* Identity and the recorded directory are checked BEFORE the current
+* resolution is used for anything: a record whose path now resolves elsewhere
+* must not have its new (attacker-influenced) target participate in the
+* overlap rules.
+*/
+function classifyStoredRoot(record, primary, claimed, duplicatedId, position) {
+	const invalid = (detail) => ({
+		...record,
+		state: "invalid",
+		detail
+	});
+	if (typeof record.path !== "string" || record.path === "") return invalid("the record has no path");
+	if (typeof record.id !== "string" || record.id === "") return invalid("the record has no id");
+	if (duplicatedId) return invalid(`the id "${record.id}" is used by more than one record (entry ${position + 1})`);
+	if (!isAbsolute(record.path)) return invalid(`"${record.path}" is not an absolute path`);
+	const recorded = record.recordedPath;
+	if (typeof recorded !== "string" || recorded === "") return invalid("the record does not say which directory it was granted for");
+	const canonical = canonicalRoot(record.path);
+	if (!samePath(canonical, recorded)) return {
+		...record,
+		state: "redirected",
+		detail: `the path now resolves to "${canonical}" instead of the registered "${recorded}"`
+	};
+	if (samePath(canonical, primary)) return invalid(`"${canonical}" is this session's workspace root`);
+	if (isCanonicallyUnder(canonical, primary) || isCanonicallyUnder(primary, canonical)) return invalid(`"${canonical}" overlaps this session's workspace root`);
+	if (claimed.some((existing) => samePath(existing, canonical))) return invalid(`"${canonical}" is registered twice`);
+	for (const existing of claimed) if (isCanonicallyUnder(canonical, existing) || isCanonicallyUnder(existing, canonical)) return invalid(`"${canonical}" overlaps the registered root "${existing}"`);
+	let isDirectory = false;
+	try {
+		isDirectory = statSync(canonical).isDirectory();
+	} catch {
+		isDirectory = false;
+	}
+	if (!isDirectory) return {
+		...record,
+		path: canonical,
+		state: "missing",
+		detail: "the directory is not present right now"
+	};
+	return {
+		...record,
+		path: canonical,
+		state: "available"
+	};
+}
+/**
+* The canonical roots a status list grants, in registry order.
+* @param statuses - the statuses to project.
+* @returns the canonical paths of every `available` root.
+*/
+function availableRoots(statuses) {
+	return statuses.filter((status) => status.state === "available").map((status) => status.path);
+}
+/**
+* Pair every status with the 1-based ordinal the surfaces accept for it. The
+* ordinal belongs to the POSITION, so it stays correct even for records whose
+* id is duplicated or missing — which is exactly the case where a positional
+* removal is the only unambiguous way to delete one of them.
+* @param statuses - the statuses to index.
+* @returns one entry per status, in the same order.
+*/
+function indexedStatuses(statuses) {
+	return statuses.map((status, index) => ({
+		ordinal: index + 1,
+		status
+	}));
+}
+/**
+* Resolve one operator-supplied reference against a status list.
+* @param statuses - the statuses to search, in registry order.
+* @param ref - the reference to resolve.
+* @returns the matched status.
+* @throws {RootValidationError} `not-found` when nothing matches.
+*/
+function resolveRootRef(statuses, ref) {
+	return statuses[resolveRootIndex(statuses, ref)];
+}
+/**
+* Resolve one reference to its exact position.
+*
+* Id/path references are accepted only when unique. An `entry` reference also
+* verifies the row identity captured by the surface, so a concurrent reorder
+* cannot turn a click into an operation on a different record.
+*/
+function resolveRootIndex(statuses, ref) {
+	const reference = describeRef(ref);
+	const matches = (predicate) => {
+		const result = [];
+		for (const [index, status] of statuses.entries()) if (predicate(status)) result.push(index);
+		return result;
+	};
+	const indices = (() => {
+		switch (ref.kind) {
+			case "id": return matches((status) => status.id === ref.id);
+			case "ordinal": return ref.ordinal >= 1 && ref.ordinal <= statuses.length ? [ref.ordinal - 1] : [];
+			case "path": {
+				const canonical = canonicalRoot(expandRootInput(ref.path));
+				return matches((status) => samePath(status.path, canonical));
+			}
+			case "entry": {
+				const sameEntry = (status) => status.id === ref.id && samePath(status.path, ref.path) && status.addedAt === ref.addedAt;
+				const found = matches(sameEntry);
+				if (found.length !== 1) return found;
+				const expected = ref.ordinal - 1;
+				return expected === found[0] ? [expected] : found;
+			}
+		}
+	})();
+	if (indices.length === 0) throw new RootValidationError("not-found", `no registered root matches ${reference}`, { reference });
+	if (indices.length > 1) throw new RootValidationError("invalid-ref", `${reference} matches more than one registered root; use its displayed number`, { reference });
+	return indices[0];
+}
+/** Capture a list row as a mutation-safe reference. */
+function entryRootRef(status, ordinal) {
+	return {
+		kind: "entry",
+		ordinal,
+		id: status.id,
+		path: status.path,
+		addedAt: status.addedAt
+	};
+}
+/**
+* Remove exactly ONE record — the one the reference names — from a status list.
+*
+* Removing by id is rejected when it is ambiguous. Exact entry or ordinal
+* references address one record, so a duplicate-id pair can be cleaned up one
+* entry at a time without turning one operation into several.
+* @param statuses - the statuses to remove from.
+* @param ref - which record to remove.
+* @returns a new list without that record, order preserved.
+* @throws {RootValidationError} `not-found` when the reference matches nothing.
+*/
+function removeStatusAt(statuses, ref) {
+	const index = resolveRootIndex(statuses, ref);
+	return statuses.filter((_status, position) => position !== index);
+}
+/** Render one reference for messages. */
+function describeRef(ref) {
+	switch (ref.kind) {
+		case "id": return `id "${ref.id}"`;
+		case "ordinal": return `#${ref.ordinal}`;
+		case "path": return `"${ref.path}"`;
+		case "entry": return `entry #${ref.ordinal} (${ref.path})`;
+	}
+}
+//#endregion
+export { classifyStoredRoots as a, indexedStatuses as c, resolveRootIndex as d, resolveRootRef as f, canonicalRoot as i, isCanonicallyUnder as l, additionalRootId as n, entryRootRef as o, validateRootCandidate as p, availableRoots as r, expandRootInput as s, RootValidationError as t, removeStatusAt as u };

package/lib/sandbox-BhuMTDgH.js

@@ -0,0 +1,243 @@
+import { SandboxUnavailableError } from "@deepseek-ai/dsh-sandbox";
+import { LocalSandboxProvider } from "@deepseek-ai/dsh-sandbox-local";
+//#region src/dialects.ts
+/**
+* Raised when a confined argv cannot be recognized or widened. The provider
+* converts this into the fail-closed `SandboxUnavailableError`: an unrecognized
+* dialect must never degrade into "the primary root was granted after all".
+*/
+var DialectUnrecognizedError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DialectUnrecognizedError";
+	}
+};
+/** The one SBPL form that carries the writable subpath grants. */
+const SBPL_SUBPATH_FORM = /\(allow file-write\*\s*(?:\(subpath\s+"(?:[^"\\]|\\.)*"\)\s*)+\)/;
+/** One SBPL `(subpath "…")` token inside that form. */
+const SBPL_SUBPATH_TOKEN = /\(subpath\s+("(?:[^"\\]|\\.)*")\)/g;
+/**
+* Split a `confine()` result at the separator by arithmetic, then VERIFY the
+* split: `confine` builds `[...profileArgs, '--', ...argv]`, so the separator
+* sits exactly one element before the caller's argv. A mismatch means the
+* provider no longer wraps argv the way this module assumes.
+* @param confinedArgv - the argv `confine` returned.
+* @param commandArgv - the argv the caller passed to `confine`.
+* @returns the recognized dialect and the split parts.
+*/
+function splitConfined(confinedArgv, commandArgv) {
+	const separator = confinedArgv.length - commandArgv.length - 1;
+	if (separator < 1 || confinedArgv[separator] !== "--") throw new DialectUnrecognizedError(`confined argv is not "[...profile, --, ...argv]" (separator expected at ${separator}, got ${JSON.stringify(confinedArgv[separator])})`);
+	const commandArgs = confinedArgv.slice(separator + 1);
+	if (commandArgs.length !== commandArgv.length || commandArgs.some((argument, index) => argument !== commandArgv[index])) throw new DialectUnrecognizedError("confined argv does not end with the caller's argv verbatim");
+	const profileArgs = confinedArgv.slice(0, separator);
+	return {
+		dialect: detectDialect(profileArgs),
+		profileArgs,
+		separator,
+		commandArgs
+	};
+}
+/**
+* Recognize the runner dialect from the profile arguments alone. Exactly one
+* marker must match; zero or several are both unrecognized.
+* @param profileArgs - everything before the separator.
+* @returns the dialect.
+*/
+function detectDialect(profileArgs) {
+	const matches = [];
+	if (profileArgs.length >= 2 && profileArgs[profileArgs.length - 2] === "-p") matches.push("seatbelt");
+	if (profileArgs.includes("--mode")) matches.push("windows-acl");
+	if (profileArgs.includes("--rw")) matches.push("landlock");
+	if (profileArgs.includes("--ro-bind")) matches.push("bwrap");
+	const [first, ...rest] = matches;
+	if (first === void 0) throw new DialectUnrecognizedError(`unrecognized sandbox profile arguments: ${JSON.stringify(profileArgs)}`);
+	if (rest.length > 0) throw new DialectUnrecognizedError(`ambiguous sandbox profile arguments (${matches.join(", ")}): ${JSON.stringify(profileArgs)}`);
+	return first;
+}
+/**
+* Widen one dialect's profile arguments with the additional roots.
+*
+* Only `workspace-write` grants roots, mirroring the upstream mode meaning and
+* the filesystem fence: `read-only` grants nothing, and `danger-full-access`
+* never confines at all (bash and the PTY backend skip `confine` in that mode).
+*
+* A root the dialect ALREADY grants is not granted twice — that keeps this
+* function aligned with the fence's own deduplication and, on bwrap, avoids
+* binding the real `/tmp` over the ephemeral `--tmpfs /tmp` mount.
+* @param dialect - the recognized dialect.
+* @param profileArgs - the profile arguments to widen.
+* @param policy - the per-call policy (its root is the policy root, never a new grant).
+* @param additionalRoots - canonical additional roots, in scope order.
+* @returns the widened profile arguments.
+*/
+function widenProfileArgs(dialect, profileArgs, policy, additionalRoots) {
+	if (policy.mode !== "workspace-write") throw new DialectUnrecognizedError(`dialect "${dialect}" grants write roots only under workspace-write, got mode "${policy.mode}"`);
+	if (additionalRoots.length === 0) return [...profileArgs];
+	switch (dialect) {
+		case "seatbelt": return widenSeatbelt(profileArgs, additionalRoots);
+		case "bwrap": return widenBwrap(profileArgs, policy.workspaceRoot, additionalRoots);
+		case "landlock": return widenLandlock(profileArgs, policy.workspaceRoot, additionalRoots);
+		case "windows-acl": return [...profileArgs];
+	}
+}
+/** Quote one path exactly the way the upstream Seatbelt profile builder does. */
+function sbplString(path) {
+	return `"${path.replaceAll("\\", String.raw`\\`).replaceAll("\"", String.raw`\"`)}"`;
+}
+/** Unquote one SBPL string literal (including its surrounding quotes). */
+function sbplValue(literal) {
+	return literal.slice(1, -1).replaceAll(String.raw`\"`, "\"").replaceAll(String.raw`\\`, "\\");
+}
+/** Append the additional roots to the SBPL form that carries the subpath grants. */
+function widenSeatbelt(profileArgs, additionalRoots) {
+	const profile = profileArgs[profileArgs.length - 1];
+	if (profile === void 0 || profileArgs[profileArgs.length - 2] !== "-p") throw new DialectUnrecognizedError(`seatbelt profile is not "[<sandbox-exec>, …, -p, <SBPL>]": ${JSON.stringify(profileArgs)}`);
+	const form = SBPL_SUBPATH_FORM.exec(profile);
+	if (form === null) throw new DialectUnrecognizedError(`seatbelt profile has no "(allow file-write* (subpath …))" form to extend: ${JSON.stringify(profile)}`);
+	const matched = form[0];
+	const granted = new Set([...matched.matchAll(SBPL_SUBPATH_TOKEN)].map((token) => sbplValue(token[1])));
+	const added = additionalRoots.filter((root) => !granted.has(root)).map((root) => `(subpath ${sbplString(root)})`);
+	if (added.length === 0) return [...profileArgs];
+	const widened = profile.slice(0, form.index) + matched.slice(0, -1) + ` ${added.join(" ")})` + profile.slice(form.index + matched.length);
+	return [...profileArgs.slice(0, -1), widened];
+}
+/**
+* The observed bwrap bind flag: the flag of the `[flag, <root>, <root>]` triple
+* upstream built for the policy root.
+*/
+function bwrapBindFlag(profileArgs, workspaceRoot) {
+	for (let index = 2; index < profileArgs.length; index += 1) {
+		if (profileArgs[index] !== workspaceRoot || profileArgs[index - 1] !== workspaceRoot) continue;
+		const flag = profileArgs[index - 2];
+		if (flag === void 0 || !flag.startsWith("--") || flag.startsWith("--ro")) continue;
+		return flag;
+	}
+	throw new DialectUnrecognizedError(`bwrap profile has no writable bind of the policy root ${JSON.stringify(workspaceRoot)}: ${JSON.stringify(profileArgs)}`);
+}
+/** Append the additional roots as binds, after upstream's own root bind. */
+function widenBwrap(profileArgs, workspaceRoot, additionalRoots) {
+	const flag = bwrapBindFlag(profileArgs, workspaceRoot);
+	const granted = /* @__PURE__ */ new Set();
+	for (let index = 0; index + 2 < profileArgs.length; index += 1) if (profileArgs[index] === flag && profileArgs[index + 1] === profileArgs[index + 2]) granted.add(profileArgs[index + 2]);
+	for (let index = 0; index + 1 < profileArgs.length; index += 1) if (profileArgs[index] === "--tmpfs") granted.add(profileArgs[index + 1]);
+	const added = additionalRoots.filter((root) => !granted.has(root)).flatMap((root) => [
+		flag,
+		root,
+		root
+	]);
+	return [...profileArgs, ...added];
+}
+/**
+* The observed Landlock read-write flag: the flag preceding the policy root in
+* the launcher's grant arguments.
+*/
+function landlockReadWriteFlag(profileArgs, workspaceRoot) {
+	for (let index = 1; index < profileArgs.length; index += 1) {
+		if (profileArgs[index] !== workspaceRoot) continue;
+		const flag = profileArgs[index - 1];
+		if (flag === void 0 || !flag.startsWith("--") || flag.startsWith("--ro")) continue;
+		return flag;
+	}
+	throw new DialectUnrecognizedError(`landlock profile has no read-write grant of the policy root ${JSON.stringify(workspaceRoot)}: ${JSON.stringify(profileArgs)}`);
+}
+/** Append the additional roots as read-write grants, after upstream's own root grant. */
+function widenLandlock(profileArgs, workspaceRoot, additionalRoots) {
+	const flag = landlockReadWriteFlag(profileArgs, workspaceRoot);
+	const granted = /* @__PURE__ */ new Set();
+	for (let index = 0; index + 1 < profileArgs.length; index += 1) if (profileArgs[index] === flag) granted.add(profileArgs[index + 1]);
+	const added = additionalRoots.filter((root) => !granted.has(root)).flatMap((root) => [flag, root]);
+	return [...profileArgs, ...added];
+}
+//#endregion
+//#region src/sandbox.ts
+/**
+* `MultiRootSandboxProvider`: the kernel-sandbox dialect provider mounted as
+* `ctx.sandbox`.
+*
+* Every confined execution in this composition funnels through `confine()` —
+* the bash executor wraps `['bash','-c',command]`, and the terminal backend
+* wraps its PTY spawn argv — so widening the grant here is what gives bash, PTY,
+* and the fs fence one and the same root set (requirement §13). The bash
+* executor itself is therefore left upstream: it never computes roots.
+*
+* The widening itself lives in `./dialects.ts`: the upstream profile builders
+* are unreachable in the published package, so the additional roots are grafted
+* onto the profile `super.confine` actually produced (recognize the dialect
+* structurally, clone its grant spelling, fail loudly when the shape is not
+* known). This class owns only the policy that decides WHEN to graft:
+*
+* 1. with no additional roots, or under any mode other than `workspace-write`,
+*    the upstream result is returned ELEMENT FOR ELEMENT — same argv, same
+*    `enforcement`, same `denialSignatures`, same `runnerFailureRules`;
+* 2. `enforcement`, `denialSignatures`, and `runnerFailureRules` are NEVER
+*    recomputed here, even when the argv is widened — the bash executor derives
+*    its denial and enforcement reporting from them;
+* 3. only `argv` may differ, and a dialect whose shape cannot be extended fails
+*    loudly (`SandboxUnavailableError`) instead of silently confining to the
+*    primary root alone.
+*
+* @module @dsh-electron/dsh-plugin-multi-root-workspace/sandbox
+*/
+/**
+* Local process-sandbox provider over the multi-root scope. Registers as
+* `ctx.sandbox`; the runner chain, probing, denial dialects, and Windows ACL
+* grant mechanics stay the upstream implementation's.
+*/
+var MultiRootSandboxProvider = class extends LocalSandboxProvider {
+	static inject = ["sandboxPolicy", "multiRootScope"];
+	/** Whether the Windows ACL limitation has already been reported (once per provider). */
+	warnedAboutWindowsAcl = false;
+	/**
+	* Wrap `argv` so it executes confined under `policy` on this host, granting
+	* the scope's additional roots inside the SAME dialect profile.
+	*
+	* Under `read-only` nothing is added (the mode denies every write, additional
+	* roots included), and `danger-full-access` never reaches here at all: the
+	* bash executor and the PTY backend both hand their argv straight to the local
+	* runtime in that mode. Widening therefore only ever ADDS the scope's
+	* additional roots to an upstream `workspace-write` profile.
+	* @param argv - the exact argv the caller is about to spawn.
+	* @param policy - the file-effect policy this execution runs under.
+	* @returns the argv to spawn instead, plus the selected backend's facts.
+	*/
+	confine(argv, policy) {
+		const confined = super.confine(argv, policy);
+		if (policy.mode !== "workspace-write") return confined;
+		const scope = this.ctx.multiRootScope.resolve(policy);
+		if (scope.additionalRoots.length === 0) return confined;
+		try {
+			const shape = splitConfined(confined.argv, argv);
+			if (shape.dialect === "windows-acl") {
+				this.warnAboutWindowsAcl(scope.additionalRoots.length);
+				return confined;
+			}
+			const profileArgs = widenProfileArgs(shape.dialect, shape.profileArgs, policy, scope.additionalRoots);
+			return {
+				...confined,
+				argv: [
+					...profileArgs,
+					"--",
+					...argv
+				]
+			};
+		} catch (error) {
+			if (!(error instanceof DialectUnrecognizedError)) throw error;
+			throw new SandboxUnavailableError(policy.mode, `multi-root workspace: cannot grant the additional workspace roots [${scope.additionalRoots.join(", ")}] under the primary root ${scope.primaryRoot} — ${error.message}`);
+		}
+	}
+	/**
+	* Report the documented first-release limitation exactly once: the Windows ACL
+	* rung grants through per-workspace write SIDs rather than argv paths, so
+	* additional roots stay unenforced for confined commands there while the
+	* in-process filesystem fence still allows them.
+	* @param rootCount - how many additional roots the scope carries.
+	*/
+	warnAboutWindowsAcl(rootCount) {
+		if (this.warnedAboutWindowsAcl) return;
+		this.warnedAboutWindowsAcl = true;
+		this.ctx.logger.warn(`multi-root workspace: this scope carries ${rootCount} additional workspace root(s), but the Windows ACL runner grants write access per workspace SID and cannot express them; confined bash/PTY runs will not be able to write them, while ctx.fs still can. Kernel-level multi-root on Windows is out of scope for the first release.`);
+	}
+};
+//#endregion
+export { MultiRootSandboxProvider as t };

package/lib/sandbox.js

@@ -0,0 +1,2 @@
+import { t as MultiRootSandboxProvider } from "./sandbox-BhuMTDgH.js";
+export { MultiRootSandboxProvider, MultiRootSandboxProvider as default };