@alvin0/ai-agent-sdk-sandbox 0.1.3

package/dist/index.js

@@ -0,0 +1,1310 @@
+//#region src/errors.ts
+/** Fail-closed error surface. Silent unconfined passthrough is never legal. */
+/** Thrown when no backend on this host can enforce a confining policy. */
+var SandboxUnavailableError = class extends Error {
+	platform;
+	code = "SANDBOX_UNAVAILABLE";
+	/** Runner ids that were considered for this platform, in chain order. */
+	attempted;
+	constructor(platform, attempted = [], detail) {
+		const options = attempted.length === 0 ? "no runner is available" : `tried ${attempted.join(", ")}`;
+		super(`No sandbox backend can confine this execution on ${platform}: ${options}${detail === void 0 ? "" : ` (${detail})`}`);
+		this.platform = platform;
+		this.name = "SandboxUnavailableError";
+		this.attempted = Object.freeze([...attempted]);
+	}
+};
+/** Thrown by the in-process fence when a mutation leaves the permitted roots. */
+var SandboxDeniedError = class extends Error {
+	path;
+	mode;
+	writableRoots;
+	code = "SANDBOX_DENIED";
+	constructor(path, mode, writableRoots) {
+		const permitted = writableRoots.length === 0 ? "nothing is writable" : `writable roots: ${writableRoots.join(", ")}`;
+		super(`Sandbox mode '${mode}' denies writing ${path} (${permitted})`);
+		this.path = path;
+		this.mode = mode;
+		this.writableRoots = writableRoots;
+		this.name = "SandboxDeniedError";
+	}
+};
+/** Thrown when a policy is structurally unusable before any backend is asked. */
+var SandboxPolicyError = class extends Error {
+	code = "SANDBOX_POLICY_INVALID";
+	constructor(message) {
+		super(message);
+		this.name = "SandboxPolicyError";
+	}
+};
+
+//#endregion
+//#region src/approval.ts
+/**
+* The minted set. A `WeakSet` is the whole mechanism: membership cannot be
+* forged, serialized, or reached from inside a tool payload.
+*/
+const MINTED = /* @__PURE__ */ new WeakSet();
+/** Approvals already consumed. Separate from minting, so the refusal differs. */
+const SPENT = /* @__PURE__ */ new WeakSet();
+/**
+* Mint an approval. Call this only after the host has actually authorized the
+* escalation; the SDK cannot tell an approved grant from a requested one, which
+* is precisely why this call has to be the place the distinction is made.
+*/
+function approveSandboxEscalation(grant) {
+	const approval = Object.freeze({
+		...grant,
+		approved: true
+	});
+	MINTED.add(approval);
+	return approval;
+}
+/** Whether a value is an approval this module minted. */
+function isSandboxApproval(value) {
+	return typeof value === "object" && value !== null && MINTED.has(value);
+}
+/** Whether a minted approval has already been used up. */
+function isSandboxApprovalSpent(approval) {
+	return SPENT.has(approval);
+}
+/**
+* Accept an approval, or refuse it loudly.
+* @throws SandboxPolicyError when the value was not minted here — which is what
+*   a forged approval arriving through a tool payload looks like.
+*/
+function requireSandboxApproval(value, now = Date.now()) {
+	if (!isSandboxApproval(value)) throw new SandboxPolicyError("Sandbox escalation requires an approval minted by approveSandboxEscalation(); a plain object cannot widen a policy, because a tool payload can contain one");
+	if (value.expiresAt !== void 0 && now > value.expiresAt) throw new SandboxPolicyError("This sandbox approval has expired; an escalation outliving the moment it was granted is an escalation nobody is still watching");
+	if (SPENT.has(value)) throw new SandboxPolicyError("This sandbox approval was already used; a grant given for one operation cannot be replayed for the next");
+	if ((value.scope ?? "single-call") === "single-call") SPENT.add(value);
+	return value;
+}
+
+//#endregion
+//#region src/exec.ts
+/** The outcome each capability maps to, before a deployment adjusts it. */
+const DEFAULT_EXEC_OUTCOMES = Object.freeze({
+	observe: "allow",
+	use: "allow-scoped",
+	modify: "ask-approval",
+	"service-control": "ask-approval",
+	"package-install": "ask-approval",
+	privilege: "ask-approval",
+	credential: "deny",
+	critical: "deny",
+	unknown: "ask-approval"
+});
+/** Commands that only report state. */
+const OBSERVE = /* @__PURE__ */ new Set([
+	"uname",
+	"uptime",
+	"hostname",
+	"date",
+	"whoami",
+	"id",
+	"df",
+	"du",
+	"free",
+	"vmstat",
+	"top",
+	"ps",
+	"pgrep",
+	"lsof",
+	"ss",
+	"netstat",
+	"ifconfig",
+	"ip",
+	"arch",
+	"sw_vers",
+	"sysctl",
+	"lscpu",
+	"lsblk",
+	"nproc",
+	"env",
+	"printenv",
+	"pwd",
+	"which",
+	"whereis",
+	"cat",
+	"head",
+	"tail",
+	"less",
+	"more",
+	"wc",
+	"stat",
+	"file",
+	"ls",
+	"find",
+	"grep",
+	"rg",
+	"awk",
+	"sed",
+	"sort",
+	"uniq",
+	"cut",
+	"diff",
+	"md5sum",
+	"sha256sum",
+	"journalctl",
+	"dmesg",
+	"log",
+	"tree",
+	"readlink",
+	"realpath",
+	"basename",
+	"dirname",
+	"echo",
+	"vm_stat",
+	"iostat",
+	"mpstat",
+	"sar",
+	"pmap",
+	"swapon",
+	"getconf",
+	"sysctl",
+	"launchctl",
+	"pgrep",
+	"pidof",
+	"w",
+	"last",
+	"lsattr",
+	"mount",
+	"blkid"
+]);
+/** Project tooling: runs inside a workspace and is scoped by the file policy. */
+const USE = /* @__PURE__ */ new Set([
+	"node",
+	"npm",
+	"npx",
+	"pnpm",
+	"yarn",
+	"bun",
+	"deno",
+	"tsc",
+	"vitest",
+	"jest",
+	"python",
+	"python3",
+	"pip",
+	"pip3",
+	"pytest",
+	"ruby",
+	"bundle",
+	"go",
+	"cargo",
+	"rustc",
+	"java",
+	"mvn",
+	"gradle",
+	"make",
+	"cmake",
+	"git",
+	"docker",
+	"kubectl",
+	"terraform",
+	"gh",
+	"curl",
+	"wget",
+	"jq"
+]);
+/** Commands that change files. */
+const MODIFY = /* @__PURE__ */ new Set([
+	"cp",
+	"mv",
+	"rm",
+	"mkdir",
+	"rmdir",
+	"touch",
+	"ln",
+	"chmod",
+	"chown",
+	"chgrp",
+	"truncate",
+	"dd",
+	"tee",
+	"install",
+	"patch",
+	"tar",
+	"unzip",
+	"zip"
+]);
+/** Commands that start, stop or signal running services. */
+const SERVICE_CONTROL = /* @__PURE__ */ new Set([
+	"systemctl",
+	"service",
+	"launchctl",
+	"initctl",
+	"kill",
+	"killall",
+	"pkill",
+	"supervisorctl",
+	"brew",
+	"nginx",
+	"apachectl",
+	"pm2"
+]);
+/** Commands that install software. */
+const PACKAGE_INSTALL = /* @__PURE__ */ new Set([
+	"apt",
+	"apt-get",
+	"dpkg",
+	"yum",
+	"dnf",
+	"rpm",
+	"pacman",
+	"apk",
+	"snap",
+	"port"
+]);
+/** Commands that run as another, more powerful, identity. */
+const PRIVILEGE = /* @__PURE__ */ new Set([
+	"sudo",
+	"su",
+	"doas",
+	"pkexec",
+	"runas"
+]);
+/** Commands whose effect cannot be undone from inside a session. */
+const CRITICAL = /* @__PURE__ */ new Set([
+	"reboot",
+	"shutdown",
+	"halt",
+	"poweroff",
+	"mkfs",
+	"fdisk",
+	"parted",
+	"iptables",
+	"nft",
+	"ufw",
+	"pfctl",
+	"usermod",
+	"useradd",
+	"userdel",
+	"passwd",
+	"visudo",
+	"csrutil",
+	"spctl"
+]);
+/**
+* Programs that read a credential without naming where it lives.
+*
+* Found by running real model output through this classifier: asked to show
+* AWS credentials, a model proposed `aws configure list` and `aws sts
+* get-caller-identity`. Neither names `~/.aws/credentials`, so a rule that
+* matches credential PATHS sees nothing — the secret is read inside the tool.
+* The program is the signal here, not its arguments.
+*/
+const CREDENTIAL_TOOLS = /* @__PURE__ */ new Set([
+	"aws",
+	"gcloud",
+	"az",
+	"doctl",
+	"heroku",
+	"op",
+	"vault",
+	"pass",
+	"keyring",
+	"security",
+	"gpg",
+	"ssh-add",
+	"ssh-agent",
+	"kubelogin",
+	"aws-vault"
+]);
+/** Subcommands of those tools that only report non-secret state. */
+const CREDENTIAL_TOOL_SAFE_VERBS = Object.freeze({});
+/** Shell keywords that lead a segment without being the command. */
+const SHELL_KEYWORDS = /* @__PURE__ */ new Set([
+	"if",
+	"then",
+	"else",
+	"elif",
+	"fi",
+	"do",
+	"done",
+	"while",
+	"until",
+	"for",
+	"case",
+	"esac",
+	"in",
+	"{",
+	"}",
+	"(",
+	")",
+	"!",
+	"time",
+	"exec"
+]);
+/** Paths whose contents authorize something, wherever they are read from. */
+const CREDENTIAL_PATTERN = /(^|\/)(\.ssh|\.aws|\.gnupg|\.kube|\.docker\/config\.json|\.npmrc|\.netrc|\.git-credentials|credentials|id_[a-z0-9]+|.*\.pem|.*\.key|\.env(\.[a-z]+)?)(\/|$)/i;
+/** Paths whose modification changes who may do what on the machine. */
+const CRITICAL_PATH_PATTERN = /(^|\/)(etc\/(sudoers|shadow|passwd|ssh\/sshd_config|pam\.d)|boot|sys\/kernel|proc\/sys)(\/|$)/i;
+/** Shells whose `-c` argument is another command entirely. */
+const SHELLS = /* @__PURE__ */ new Set([
+	"sh",
+	"bash",
+	"zsh",
+	"dash",
+	"ksh",
+	"fish",
+	"pwsh",
+	"powershell"
+]);
+/** Wrappers that run another command without changing what it does. */
+const TRANSPARENT = /* @__PURE__ */ new Set([
+	"env",
+	"nice",
+	"ionice",
+	"nohup",
+	"stdbuf",
+	"time",
+	"timeout",
+	"command"
+]);
+/**
+* Classify one command.
+* @param argv - the exact argv, program first. A shell string is read through.
+* @param outcomes - the capability-to-outcome mapping a deployment uses.
+*/
+function classifyExec(argv, outcomes = DEFAULT_EXEC_OUTCOMES) {
+	const parts = splitCommands(argv).map((part) => classifySingle(part, outcomes)).filter((part) => part.program !== "(empty)");
+	if (parts.length === 0) return decide("unknown", "(empty)", "no command to classify", [], outcomes);
+	if (parts.length === 1) return parts[0];
+	const worst = parts.reduce((left, right) => CAPABILITY_RANK[right.capability] > CAPABILITY_RANK[left.capability] ? right : left);
+	return decide(worst.capability, worst.program, `a chain of ${String(parts.length)} commands, decided by its riskiest: ${worst.reason}`, parts, outcomes);
+}
+/** Consequence order, used to pick the decisive command in a chain. */
+const CAPABILITY_RANK = Object.freeze({
+	observe: 0,
+	use: 1,
+	unknown: 2,
+	modify: 3,
+	"service-control": 4,
+	"package-install": 5,
+	privilege: 6,
+	credential: 7,
+	critical: 8
+});
+/** Build a classification with its outcome resolved. */
+function decide(capability, program, reason, parts, outcomes) {
+	return Object.freeze({
+		capability,
+		outcome: outcomes[capability],
+		program,
+		reason,
+		parts: Object.freeze(parts)
+	});
+}
+/** Classify a single command that contains no further commands. */
+function classifySingle(argv, outcomes) {
+	const redirect = argv.findIndex((token) => token === ">" || token === ">>");
+	if (redirect >= 0) {
+		const target = argv[redirect + 1] ?? "";
+		const inner = classifySingle(argv.slice(0, redirect), outcomes);
+		const written = classifySingle(["tee", target], outcomes);
+		return CAPABILITY_RANK[written.capability] > CAPABILITY_RANK[inner.capability] ? decide(written.capability, inner.program, `redirects output into ${target}`, [], outcomes) : decide(inner.capability, inner.program, inner.reason, [], outcomes);
+	}
+	const stripped = stripWrappers(argv);
+	const program = basename(stripped[0] ?? "");
+	const args = stripped.slice(1);
+	if (program === "") return decide("unknown", "(empty)", "no program named", [], outcomes);
+	const touched = args.filter((argument) => !argument.startsWith("-"));
+	const credential = touched.find((argument) => CREDENTIAL_PATTERN.test(argument));
+	if (credential !== void 0) return decide("credential", program, `names a credential path: ${credential}`, [], outcomes);
+	const critical = touched.find((argument) => CRITICAL_PATH_PATTERN.test(argument));
+	if (critical !== void 0) return decide("critical", program, `names a path that governs access: ${critical}`, [], outcomes);
+	const inPlace = IN_PLACE_FLAGS[program];
+	if (inPlace !== void 0 && args.some((argument) => inPlace.some((flag) => argument === flag || argument.startsWith(`${flag}`) && flag === "-i"))) return decide("modify", program, "edits its input in place", [], outcomes);
+	if (program === "find" && args.some((argument) => argument === "-delete" || argument === "-exec" || argument === "-execdir" || argument === "-ok" || argument === "-okdir")) return decide("modify", program, "runs an action that may change files", [], outcomes);
+	if (program === "awk" && args.some((argument) => /(^|[^A-Za-z_])system\s*\(/.test(argument))) return decide("unknown", program, "evaluates another command dynamically", [], outcomes);
+	if (program === "rm" && touched.some((argument) => ROOTISH.has(argument.replace(/\/+$/, "") || "/"))) return decide("critical", program, `removes a system root: ${touched.join(" ")}`, [], outcomes);
+	if (CREDENTIAL_TOOLS.has(program)) {
+		const verb = touched[0] ?? "";
+		if (!(CREDENTIAL_TOOL_SAFE_VERBS[program]?.has(verb) ?? false)) return decide("credential", program, `reads a credential the command never names${verb === "" ? "" : ` (${verb})`}`, [], outcomes);
+	}
+	if (PRIVILEGE.has(program)) return decide("privilege", program, "runs as another identity", [], outcomes);
+	if (CRITICAL.has(program)) return decide("critical", program, "changes the machine in a way a session cannot undo", [], outcomes);
+	if (PACKAGE_INSTALL.has(program)) return decide("package-install", program, "installs software", [], outcomes);
+	if (SERVICE_CONTROL.has(program)) return classifyServiceCommand(program, args, outcomes);
+	if (MODIFY.has(program)) return decide("modify", program, "changes files", [], outcomes);
+	if (USE.has(program)) return classifyToolCommand(program, args, outcomes);
+	if (program === "command" || program === "[" || program === "test" || program === "[[") return decide("observe", program, "tests for something without running it", [], outcomes);
+	if (OBSERVE.has(program)) return decide("observe", program, "reports state without changing it", [], outcomes);
+	return decide("unknown", program, "not a command this policy recognises", [], outcomes);
+}
+/**
+* Where a program puts the verb. `systemctl restart nginx` names the action
+* first; `service nginx restart` names the unit first, and reading position 0
+* for both makes every `service` invocation look like a control action.
+*/
+const VERB_POSITION = Object.freeze({
+	service: 1,
+	systemctl: 0,
+	launchctl: 0,
+	initctl: 0,
+	supervisorctl: 0,
+	brew: 0,
+	pm2: 0
+});
+/** Flags that turn a reading tool into a writing one. */
+const IN_PLACE_FLAGS = Object.freeze({
+	sed: ["-i", "--in-place"],
+	perl: ["-i"],
+	awk: ["-i", "--in-place"],
+	ruby: ["-i"]
+});
+/** Paths whose wholesale removal is not something a session can undo. */
+const ROOTISH = /* @__PURE__ */ new Set([
+	"/",
+	"/*",
+	"/etc",
+	"/usr",
+	"/bin",
+	"/sbin",
+	"/var",
+	"/boot",
+	"/System",
+	"/Library"
+]);
+/** Verbs that only report a service's state. */
+const SERVICE_READ_VERBS = /* @__PURE__ */ new Set([
+	"status",
+	"show",
+	"list",
+	"list-units",
+	"is-active",
+	"is-enabled",
+	"cat",
+	"get",
+	"services",
+	"print",
+	"info",
+	"ls",
+	"config",
+	"list-unit-files"
+]);
+/**
+* Separate observing a service from controlling one — the distinction the file
+* seam cannot make, and the reason this module exists.
+*/
+function classifyServiceCommand(program, args, outcomes) {
+	const verb = args.filter((argument) => !argument.startsWith("-"))[VERB_POSITION[program] ?? 0];
+	if (verb === void 0) return decide("observe", program, "lists services without naming an action", [], outcomes);
+	if (SERVICE_READ_VERBS.has(verb)) return decide("observe", program, `reports service state (${verb})`, [], outcomes);
+	if (program === "nginx" && args.includes("-t")) return decide("observe", program, "checks configuration without applying it", [], outcomes);
+	return decide("service-control", program, `changes a running service (${verb})`, [], outcomes);
+}
+/** Tool subcommands that install outside the workspace or raise privilege. */
+function classifyToolCommand(program, args, outcomes) {
+	if ((args.includes("-g") || args.includes("--global") || args.includes("--location=global")) && (program === "npm" || program === "pnpm" || program === "yarn")) return decide("package-install", program, "installs outside the workspace", [], outcomes);
+	if (program === "docker" && args.some((argument) => argument === "run" || argument === "exec")) return decide("service-control", program, "starts or enters a container", [], outcomes);
+	return decide("use", program, "project tooling, scoped by the file policy", [], outcomes);
+}
+/** Remove wrappers, shell keywords and leading assignments without losing meaning. */
+function stripWrappers(argv) {
+	let current = [...argv];
+	for (let guard = 0; guard < 8; guard++) {
+		while (current.length > 0 && SHELL_KEYWORDS.has(current[0] ?? "")) current.shift();
+		while (current.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(current[0] ?? "")) current.shift();
+		const program = basename(current[0] ?? "");
+		if (!TRANSPARENT.has(program)) break;
+		current = current.slice(1);
+		while (current.length > 0 && (current[0] ?? "").startsWith("-")) current.shift();
+		if (program === "timeout" && current.length > 0 && /^[0-9]/.test(current[0] ?? "")) current.shift();
+	}
+	return current;
+}
+/**
+* Every command an argv actually runs.
+*
+* A shell invocation carries its real command in a string, and that string can
+* hold several. Splitting it with a pattern cannot work: `grep -E 'a|b'` puts a
+* separator inside a quoted word, and a pattern either splits there — inventing
+* commands out of a regex — or refuses to split anywhere a quote appears. The
+* script is therefore walked one character at a time, so a separator only
+* separates when nothing is quoting it.
+*/
+function splitCommands(argv) {
+	const stripped = stripWrappers(argv);
+	const program = basename(stripped[0] ?? "");
+	const flagIndex = stripped.findIndex((argument) => argument === "-c" || argument === "-Command");
+	let script;
+	if (SHELLS.has(program) && flagIndex >= 0) script = stripped[flagIndex + 1];
+	else if (stripped.some((token) => UNQUOTED_SEPARATOR.test(token))) script = stripped.join(" ");
+	if (script === void 0) return [stripped];
+	const commands = tokenizeScript(script);
+	if (hasDynamicShellSyntax(script)) return Object.freeze([...commands, Object.freeze(["(dynamic-shell-syntax)"])]);
+	return commands.length === 0 ? [stripped] : commands;
+}
+/** Syntax that can execute code our deliberately small tokenizer cannot see. */
+function hasDynamicShellSyntax(script) {
+	let quote;
+	for (let index = 0; index < script.length; index++) {
+		const character = script[index] ?? "";
+		if (character === "\\" && quote !== "'") {
+			index += 1;
+			continue;
+		}
+		if (character === "'") {
+			if (quote === void 0) quote = "'";
+			else if (quote === "'") quote = void 0;
+			continue;
+		}
+		if (character === "\"") {
+			if (quote === void 0) quote = "\"";
+			else if (quote === "\"") quote = void 0;
+			continue;
+		}
+		if (quote === "'") continue;
+		if (character === "`") return true;
+		const pair = script.slice(index, index + 2);
+		if (pair === "$(" || pair === "<(" || pair === ">(") return true;
+	}
+	return quote !== void 0;
+}
+/** A separator that is not inside quotes, used only to decide whether to walk. */
+const UNQUOTED_SEPARATOR = /^(&&|\|\||;|\|)$|[;|&]/;
+/**
+* Split a shell script into commands, respecting quotes and escapes.
+*
+* Deliberately not a shell parser: it does not expand, substitute, or
+* understand control flow. It answers one question — which words belong to
+* which command — and leaves the rest to the classifier, which treats anything
+* it cannot read as something to ask about.
+*/
+function tokenizeScript(script) {
+	const commands = [];
+	let command = [];
+	let word = "";
+	let quote;
+	let index = 0;
+	const endWord = () => {
+		if (word !== "") {
+			command.push(word);
+			word = "";
+		}
+	};
+	const endCommand = () => {
+		endWord();
+		if (command.length > 0) commands.push(command);
+		command = [];
+	};
+	while (index < script.length) {
+		const character = script[index] ?? "";
+		if (quote !== void 0) {
+			if (character === "\\" && quote === "\"" && index + 1 < script.length) {
+				word += script[index + 1] ?? "";
+				index += 2;
+				continue;
+			}
+			if (character === quote) quote = void 0;
+			else word += character;
+			index += 1;
+			continue;
+		}
+		if (character === "\"" || character === "'") {
+			quote = character;
+			index += 1;
+			continue;
+		}
+		if (character === "\\" && index + 1 < script.length) {
+			word += script[index + 1] ?? "";
+			index += 2;
+			continue;
+		}
+		if (character === " " || character === "	") {
+			endWord();
+			index += 1;
+			continue;
+		}
+		if (character === "\n") {
+			endCommand();
+			index += 1;
+			continue;
+		}
+		const pair = script.slice(index, index + 2);
+		if (pair === "&&" || pair === "||") {
+			endCommand();
+			index += 2;
+			continue;
+		}
+		if (pair === ">>") {
+			endWord();
+			command.push(">>");
+			index += 2;
+			continue;
+		}
+		if (character === ";" || character === "|" || character === "&") {
+			endCommand();
+			index += 1;
+			continue;
+		}
+		if (character === ">") {
+			endWord();
+			command.push(">");
+			index += 1;
+			continue;
+		}
+		if (character === "(" || character === ")" || character === "{" || character === "}") {
+			endWord();
+			index += 1;
+			continue;
+		}
+		word += character;
+		index += 1;
+	}
+	endCommand();
+	return commands;
+}
+/** The final path segment, so `/usr/bin/systemctl` decides like `systemctl`. */
+function basename(value) {
+	const cleaned = value.replaceAll("\\", "/");
+	return cleaned.slice(cleaned.lastIndexOf("/") + 1);
+}
+
+//#endregion
+//#region src/path.ts
+const WIN32_DRIVE = /^[A-Za-z]:[\\/]/;
+const WIN32_UNC = /^\\\\[^\\/]+[\\/][^\\/]+/;
+/** Detect the dialect of an absolute path from its own shape. */
+function detectFlavor(path) {
+	return WIN32_DRIVE.test(path) || WIN32_UNC.test(path) ? "win32" : "posix";
+}
+/** Whether the path is absolute in either dialect. */
+function isAbsolutePath(path) {
+	return path.startsWith("/") || WIN32_DRIVE.test(path) || WIN32_UNC.test(path);
+}
+/**
+* Collapse separators and resolve `.` / `..` lexically, without touching the
+* filesystem. A `..` that would escape the root is dropped, matching how both
+* bwrap and Seatbelt treat an over-popped absolute path.
+*/
+function normalizePath(path) {
+	if (path === "") return path;
+	const flavor = detectFlavor(path);
+	const unified = flavor === "win32" ? path.replaceAll("\\", "/") : path;
+	const prefix = rootPrefix(unified, flavor);
+	const body = unified.slice(prefix.length);
+	const resolved = [];
+	for (const segment of body.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			if (resolved.length > 0) resolved.pop();
+			else if (prefix === "") resolved.push("..");
+			continue;
+		}
+		resolved.push(segment);
+	}
+	const joined = resolved.join("/");
+	if (prefix === "") return joined === "" ? "." : joined;
+	return joined === "" ? prefix : `${prefix}${joined}`;
+}
+/** The absolute-root prefix of a path (`/`, `C:/`, `//server/share/`), or `''`. */
+function rootPrefix(unified, flavor) {
+	if (flavor === "win32") {
+		if (WIN32_DRIVE.test(unified)) return `${unified.slice(0, 2).toUpperCase()}/`;
+		const unc = /^\/\/[^/]+\/[^/]+/.exec(unified);
+		if (unc?.[0] !== void 0) return `${unc[0]}/`;
+	}
+	return unified.startsWith("/") ? "/" : "";
+}
+/** Normalized segments below the root prefix; the root itself has none. */
+function pathSegments(path) {
+	const normalized = normalizePath(path);
+	const prefix = rootPrefix(normalized, detectFlavor(normalized));
+	const body = normalized.slice(prefix.length);
+	return body === "" ? [] : body.split("/");
+}
+/**
+* Specificity rank used to order overlapping policy entries. A deeper path is
+* more specific, so it is applied later and wins over a broader ancestor.
+*/
+function pathDepth(path) {
+	return pathSegments(path).length;
+}
+/** Case-fold a normalized path for comparison under its own dialect. */
+function foldCase(path) {
+	return detectFlavor(path) === "win32" ? path.toLowerCase() : path;
+}
+/** Whether two paths identify the same location lexically. */
+function samePath(left, right) {
+	return foldCase(normalizePath(left)) === foldCase(normalizePath(right));
+}
+/**
+* Whether `candidate` is `root` itself or lies beneath it. Comparison is
+* segment-wise, so `/repo-secrets` is never treated as inside `/repo`.
+*/
+function containsPath(root, candidate) {
+	const base = foldCase(normalizePath(root));
+	const target = foldCase(normalizePath(candidate));
+	if (base === target) return true;
+	const prefix = base.endsWith("/") ? base : `${base}/`;
+	return target.startsWith(prefix);
+}
+/** Append relative segments to an absolute base, normalizing the result. */
+function joinPath(base, ...parts) {
+	const separator = base.endsWith("/") ? "" : "/";
+	return normalizePath(parts.length === 0 ? base : `${base}${separator}${parts.join("/")}`);
+}
+/** The parent of a normalized path, or `undefined` at a filesystem root. */
+function parentPath(path) {
+	const normalized = normalizePath(path);
+	const prefix = rootPrefix(normalized, detectFlavor(normalized));
+	if (normalized === prefix) return void 0;
+	const cut = normalized.lastIndexOf("/");
+	if (cut < 0) return void 0;
+	const parent = normalized.slice(0, cut);
+	return parent.length < prefix.length ? prefix : parent === "" ? prefix : parent;
+}
+/** Every ancestor of `path` from the filesystem root down to `path` itself. */
+function ancestorPaths(path) {
+	const chain = [];
+	let current = normalizePath(path);
+	while (current !== void 0) {
+		chain.unshift(current);
+		current = parentPath(current);
+	}
+	return chain;
+}
+/** Drop paths already covered by a broader entry in the same list. */
+function dedupeRoots(roots) {
+	const normalized = [...new Set(roots.map((root) => normalizePath(root)))];
+	normalized.sort((left, right) => pathDepth(left) - pathDepth(right) || left.localeCompare(right));
+	const kept = [];
+	for (const root of normalized) if (!kept.some((existing) => containsPath(existing, root))) kept.push(root);
+	return Object.freeze(kept);
+}
+
+//#endregion
+//#region src/entries.ts
+/**
+* Nested filesystem carve-outs.
+*
+* A single writable root is not enough: an agent that may write in a repository
+* must still be kept out of `.git`, and an operator must be able to reopen one
+* directory beneath a denied parent. Entries express that as an overlapping
+* list resolved by path specificity — the deepest matching entry wins, so
+* `/repo = write`, `/repo/a = deny`, `/repo/a/b = write` behaves as written.
+*/
+/**
+* Order entries from broadest to narrowest so a consumer can apply them in
+* sequence and let the most specific one win. Equal-depth entries keep a stable
+* lexical order so a policy always produces the same backend profile.
+*/
+function orderEntries(entries) {
+	return Object.freeze([...entries].map((entry) => Object.freeze({
+		path: normalizePath(entry.path),
+		access: entry.access
+	})).sort((left, right) => pathDepth(left.path) - pathDepth(right.path) || left.path.localeCompare(right.path)));
+}
+/**
+* Resolve the effective access for one target against an ordered entry list.
+* @param target - absolute path being evaluated.
+* @param entries - carve-outs, in any order.
+* @param fallback - access to use when no entry covers the target.
+*/
+function accessFor(target, entries, fallback) {
+	let effective = fallback;
+	for (const entry of orderEntries(entries)) if (containsPath(entry.path, target)) effective = entry.access;
+	return effective;
+}
+/**
+* Entries that carve a narrower rule *inside* `root`. A backend that grants
+* `root` wholesale must re-apply these afterwards or the grant is too wide.
+*/
+function entriesWithin(root, entries) {
+	return Object.freeze(orderEntries(entries).filter((entry) => containsPath(root, entry.path) && !containsPath(entry.path, root)));
+}
+
+//#endregion
+//#region src/roots.ts
+/**
+* Directory names never writable inside a granted root. Writing `.git` lets a
+* command install a hook that runs arbitrary code on the next git invocation,
+* which defeats the point of confining the command; the credential files are
+* there so a confined command cannot rewrite the caller's own authentication.
+* They stay readable — this is a write boundary, not a read boundary.
+*/
+const PROTECTED_SUBPATHS = Object.freeze([
+	".git",
+	".hg",
+	".svn",
+	".ssh",
+	".aws",
+	".npmrc",
+	".netrc"
+]);
+/**
+* The baseline every policy starts from: the host is readable and nothing is
+* writable. Layers only ever move a subtree away from this.
+*/
+const BASELINE_ACCESS = "read";
+const ORIGIN_RANK = Object.freeze({
+	mode: 0,
+	protected: 1,
+	entry: 2,
+	restriction: 3,
+	approval: 4
+});
+const ACCESS_RANK = Object.freeze({
+	deny: 0,
+	read: 1,
+	write: 2
+});
+function narrower(left, right) {
+	return ACCESS_RANK[left] <= ACCESS_RANK[right] ? left : right;
+}
+function collapseLayers(proposed, baseline) {
+	const sorted = [...proposed].sort((left, right) => pathDepth(left.path) - pathDepth(right.path) || ORIGIN_RANK[left.origin] - ORIGIN_RANK[right.origin] || left.path.localeCompare(right.path));
+	const lastAtPath = /* @__PURE__ */ new Map();
+	sorted.forEach((layer, index) => lastAtPath.set(layer.path, index));
+	const kept = [];
+	sorted.forEach((layer, index) => {
+		if (lastAtPath.get(layer.path) === index && accessInLayers(layer.path, kept, baseline) !== layer.access) kept.push(Object.freeze(layer));
+	});
+	return kept;
+}
+/**
+* Resolve a policy into the ordered layers that express it.
+*
+* Layers are sorted broadest to narrowest, and an explicit entry wins a tie at
+* equal depth so a deployment can deliberately reopen a protected subpath. A
+* layer that would not change the access already in force is dropped, so the
+* result carries no mount or profile rule that does nothing.
+*/
+function grantLayers(policy, options = {}) {
+	const proposed = [];
+	if (policy.mode === "workspace-write") for (const root of [policy.workspaceRoot, ...options.tempRoots ?? []]) proposed.push({
+		path: normalizePath(root),
+		access: "write",
+		origin: "mode"
+	});
+	for (const denied of options.deniedPaths ?? []) proposed.push({
+		path: normalizePath(denied),
+		access: "deny",
+		origin: "protected"
+	});
+	if (options.protectSubpaths !== false) for (const layer of proposed.filter((candidate) => candidate.access === "write")) for (const name of PROTECTED_SUBPATHS) proposed.push({
+		path: joinPath(layer.path, name),
+		access: "read",
+		origin: "protected"
+	});
+	for (const entry of orderEntries(policy.entries ?? [])) proposed.push({
+		path: entry.path,
+		access: entry.access,
+		origin: "entry"
+	});
+	const baseline = policy.baseline ?? "read";
+	let kept = collapseLayers(proposed, baseline);
+	const restrictions = orderEntries(policy.restrictions ?? []);
+	if (restrictions.length > 0) {
+		const boundaries = orderEntries([...kept.map((layer) => ({
+			path: layer.path,
+			access: layer.access
+		})), ...restrictions]).map((entry) => entry.path);
+		const distinctBoundaries = [...new Set(boundaries)];
+		const intersected = [];
+		for (const path of distinctBoundaries) {
+			const access = narrower(accessInLayers(path, kept, baseline), accessFor(path, restrictions, "write"));
+			if (accessInLayers(path, intersected, baseline) !== access) intersected.push(Object.freeze({
+				path,
+				access,
+				origin: "restriction"
+			}));
+		}
+		kept = intersected;
+	}
+	kept = collapseLayers([...kept, ...orderEntries(policy.approvedEntries ?? []).map((entry) => ({
+		...entry,
+		origin: "approval"
+	}))], baseline);
+	return Object.freeze(kept);
+}
+/**
+* The access in force at one path, given layers already applied in order.
+* The last layer whose subtree contains the path wins, which is what makes a
+* narrower grant reopen a denied parent.
+*/
+function accessInLayers(target, layers, baseline = BASELINE_ACCESS) {
+	let effective = baseline;
+	for (const layer of layers) if (containsPath(layer.path, target)) effective = layer.access;
+	return effective;
+}
+/**
+* The writable subtrees and their re-denials, flattened from {@link grantLayers}
+* for callers that only need the two lists. Order is preserved; a narrower grant
+* beneath a denial appears in `roots` after the denial it reopens.
+*/
+function writableRoots(policy, options = {}) {
+	const layers = grantLayers(policy, options);
+	return Object.freeze({
+		roots: Object.freeze(layers.filter((layer) => layer.access === "write").map((layer) => layer.path)),
+		denied: Object.freeze(layers.filter((layer) => layer.access !== "write").map((layer) => layer.path))
+	});
+}
+/** Subtrees whose contents must not be readable, for backends that can mask. */
+function unreadablePaths(policy, options = {}) {
+	return Object.freeze(grantLayers(policy, options).filter((layer) => layer.access === "deny").map((layer) => layer.path));
+}
+
+//#endregion
+//#region src/fence.ts
+/**
+* The in-process path fence.
+*
+* A process sandbox only governs what a *child process* does. Tools that read,
+* write, or edit files inside the agent host bypass it entirely, so those calls
+* are fenced here against the same {@link grantLayers} the kernel profiles are
+* built from. The logic is pure; the filesystem facts it needs arrive through an
+* injected {@link PathResolver}.
+*/
+/**
+* Build the fence for one policy.
+* @param policy - the same policy the process backends receive.
+* @param resolver - filesystem facts used to defeat symlinked paths.
+* @param options - platform temp roots and protected-subpath behaviour.
+*/
+function createFsFence(policy, resolver, options = {}) {
+	const layers = grantLayers(policy, options);
+	/**
+	* Layer paths are canonicalized too, not just the target.
+	*
+	* A workspace root is routinely reached through a symlink — `/tmp` IS
+	* `/private/tmp` on macOS, and `/home` is often a link. Canonicalizing only
+	* the target would then compare a resolved path against an unresolved layer
+	* and refuse writes inside the very workspace that was granted. Resolved once
+	* and reused, because a fence is built per call.
+	*/
+	let canonical;
+	function layersOnce() {
+		canonical ??= Promise.all(layers.map(async (layer) => Object.freeze({
+			...layer,
+			path: await canonicalize(layer.path, resolver)
+		})));
+		return canonical;
+	}
+	async function permits(path, want) {
+		const [target, resolved] = await Promise.all([canonicalize(path, resolver), layersOnce()]);
+		const access = accessInLayers(target, resolved, policy.baseline ?? "read");
+		if (want === "read") return access !== "deny";
+		if (access !== "write") return false;
+		return options.allowAliasedWrites === true || !await aliased(target);
+	}
+	/**
+	* Whether the target is reachable under a name this policy never saw.
+	*
+	* A hard link gives one inode two names. Judging the name inside the
+	* workspace says nothing about the other one, which may sit anywhere,
+	* so a write through the inside name escapes a boundary made of paths. The
+	* count is the only signal available without walking the whole filesystem;
+	* when the host cannot report it, the check does not fire.
+	*/
+	async function aliased(target) {
+		if (resolver.hardLinkCount === void 0) return false;
+		try {
+			return await resolver.hardLinkCount(target) > 1;
+		} catch {
+			return false;
+		}
+	}
+	return Object.freeze({
+		writableRoots: Object.freeze(layers.filter((layer) => layer.access === "write").map((layer) => layer.path)),
+		isWritable: (path) => permits(path, "write"),
+		isReadable: (path) => permits(path, "read"),
+		async assertWritable(path) {
+			if (await permits(path, "write")) return;
+			const writable = layers.filter((layer) => layer.access === "write").map((layer) => layer.path);
+			throw new SandboxDeniedError(normalizePath(path), policy.mode, writable);
+		},
+		isAliased: (path) => canonicalize(path, resolver).then(aliased)
+	});
+}
+/** Bound on link chasing, so a self-referential link cannot loop forever. */
+const SYMLINK_DEPTH_LIMIT = 32;
+/**
+* Resolve a path through its deepest existing ancestor.
+*
+* A path is checked before it exists (a file about to be created) and may pass
+* through a symlink that points outside the workspace. Canonicalizing the
+* deepest ancestor that does exist and re-appending the missing tail closes
+* both cases: a symlinked parent resolves to its real location, and a target
+* that does not exist yet is still judged where it would actually be created.
+*/
+async function canonicalize(path, resolver, depth = 0) {
+	const normalized = normalizePath(path);
+	if (depth >= SYMLINK_DEPTH_LIMIT) return normalized;
+	const chain = ancestorPaths(normalized);
+	for (let index = chain.length - 1; index >= 0; index--) {
+		const candidate = chain[index];
+		if (candidate === void 0) continue;
+		if (!await resolver.exists(candidate)) continue;
+		const link = await resolver.readLink?.(candidate);
+		if (link !== void 0) {
+			const parent = parentPath(candidate) ?? candidate;
+			const target = isAbsolutePath(link) ? link : `${parent}/${link}`;
+			const tail = normalized.slice(candidate.length).replace(/^[\\/]+/, "");
+			const resolved = await canonicalize(target, resolver, depth + 1);
+			return tail === "" ? resolved : normalizePath(`${resolved}/${tail}`);
+		}
+		const real = await resolver.realpath(candidate);
+		const tail = normalized.slice(candidate.length).replace(/^[\\/]+/, "");
+		return tail === "" ? normalizePath(real) : normalizePath(`${real}/${tail}`);
+	}
+	return normalized;
+}
+
+//#endregion
+//#region src/mode.ts
+/** Every mode, in widening order of authority. */
+const SANDBOX_MODES = Object.freeze([
+	"read-only",
+	"workspace-write",
+	"danger-full-access"
+]);
+/** Whether an arbitrary value is one of the known modes. */
+function isSandboxMode(value) {
+	return typeof value === "string" && SANDBOX_MODES.includes(value);
+}
+/** Whether a mode still asks a provider to confine the execution. */
+function isConfinedMode(mode) {
+	return mode !== "danger-full-access";
+}
+/** Rank used when a narrower mode must not be widened by a weaker source. */
+function modeAuthority(mode) {
+	return SANDBOX_MODES.indexOf(mode);
+}
+
+//#endregion
+//#region src/network.ts
+/**
+* Network reachability — a seam of its own, deliberately not a file-effect mode.
+*
+* `SandboxMode` governs file effects and says so. Folding network reachability
+* into it would make the mode claim something it does not decide, and a mode
+* that lies about its scope is worse than one with a narrow one. So network is
+* a second, independent axis carried on the same policy: a call can be
+* `read-only` on the filesystem and still reach the internet, or writable in
+* its workspace and reach nothing.
+*
+* The distinction matters because the two are enforced by different mechanisms
+* — mount bindings versus a network namespace — and a host can provide one
+* without the other.
+*/
+/** Every network mode, in widening order of reach. */
+const NETWORK_MODES = Object.freeze([
+	"deny",
+	"loopback",
+	"allow-all"
+]);
+/** Whether an arbitrary value is one of the known network modes. */
+function isNetworkMode(value) {
+	return typeof value === "string" && NETWORK_MODES.includes(value);
+}
+/** Rank used so an untrusted request can narrow reach but never widen it. */
+function networkAuthority(mode) {
+	return NETWORK_MODES.indexOf(mode);
+}
+/**
+* Narrow a network mode toward a stricter one, refusing to widen.
+* @param ceiling - the reach already permitted.
+* @param requested - the reach being asked for.
+* @returns the stricter of the two.
+*/
+function narrowNetwork(ceiling, requested) {
+	if (requested === void 0) return ceiling;
+	if (!isNetworkMode(requested)) throw new SandboxPolicyError(`Unknown network mode '${String(requested)}'`);
+	return networkAuthority(requested) < networkAuthority(ceiling) ? requested : ceiling;
+}
+
+//#endregion
+//#region src/classify.ts
+/**
+* Exit codes that are ordinary shell failures and never sandbox evidence:
+* 2 misuse of a builtin, 126 not executable, 127 command not found.
+*/
+const SHELL_FAILURE_EXIT_CODES = Object.freeze([
+	2,
+	126,
+	127
+]);
+/** POSIX `SIGSYS`, raised when a seccomp filter kills the process. */
+const SIGSYS_EXIT_CODE = 159;
+/**
+* Classify one confined command's outcome.
+*
+* Runner failure is tested first, then a seccomp kill (deterministic, no text
+* matching needed), then the backend's own denial dialect. A cross-backend
+* union of denial strings is deliberately not used: it would claim denials a
+* given backend never produces.
+*/
+function classifyOutcome(outcome, input) {
+	if (outcome.exitCode === 0) return Object.freeze({ kind: "success" });
+	const lines = outcome.stderr.split(/\r?\n/);
+	if (outcome.childStarted !== true) for (const rule of input.runnerFailureRules) {
+		const evidence = matchRunnerFailure(outcome.exitCode, lines, rule);
+		if (evidence !== void 0) return Object.freeze({
+			kind: "runner-failure",
+			evidence
+		});
+	}
+	if (outcome.signal === "SIGSYS" || outcome.exitCode === SIGSYS_EXIT_CODE) return Object.freeze({
+		kind: "denied",
+		evidence: "process killed by SIGSYS (seccomp)"
+	});
+	if (SHELL_FAILURE_EXIT_CODES.includes(outcome.exitCode)) return Object.freeze({ kind: "command-failure" });
+	const denial = matchSignature(lines, input.denialSignatures);
+	return denial === void 0 ? Object.freeze({ kind: "command-failure" }) : Object.freeze({
+		kind: "denied",
+		evidence: denial
+	});
+}
+/** Apply one runner-failure rule to a finished process. */
+function matchRunnerFailure(exitCode, lines, rule) {
+	if (rule.allowedExitCodes !== void 0 && !rule.allowedExitCodes.includes(exitCode)) return void 0;
+	const informational = new Set((rule.informationalLines ?? []).map((line) => line.trim().toLowerCase()));
+	const excluded = (rule.excludedSignatures ?? []).map((signature) => signature.toLowerCase());
+	return matchSignature(lines.filter((line) => {
+		const normalized = line.trim().toLowerCase();
+		if (informational.has(normalized)) return false;
+		return !excluded.some((signature) => signature !== "" && normalized.includes(signature));
+	}), rule.fatalSignatures);
+}
+/** The first line containing any signature, matched case-insensitively. */
+function matchSignature(lines, signatures) {
+	if (signatures.length === 0) return void 0;
+	for (const line of lines) {
+		const haystack = line.toLowerCase();
+		if (signatures.some((signature) => signature !== "" && haystack.includes(signature.toLowerCase()))) return line;
+	}
+}
+/**
+* Append a short, factual note to stderr explaining a sandbox outcome, so a
+* reader never has to infer confinement from a bare error string.
+*/
+function annotateStderr(stderr, classification, mode) {
+	if (classification.kind === "success" || classification.kind === "command-failure") return stderr;
+	const note = classification.kind === "runner-failure" ? `[sandbox] The sandbox runner failed before the command ran; the command did not execute. ${classification.evidence ?? ""}`.trim() : `[sandbox] Blocked by sandbox mode '${mode}'. ${classification.evidence ?? ""}`.trim();
+	return stderr.endsWith("\n") || stderr === "" ? `${stderr}${note}\n` : `${stderr}\n${note}\n`;
+}
+
+//#endregion
+//#region src/policy.ts
+/**
+* Resolve the complete policy for one capability call.
+*
+* Authority only ever decreases across untrusted inputs: the deployment default
+* and the session's mode set a ceiling, a request may narrow beneath it, and a
+* minted approval is the single path that raises it. A session cwd is its
+* `workspace-write` boundary; the configured root is the fallback for agentless
+* calls and sessions without a cwd.
+* @param request - the calling session's untrusted ask, plus any approval.
+* @param defaults - deployment mode, workspace root, and standing carve-outs.
+* @throws SandboxPolicyError when a request tries to widen without an approval.
+*/
+function resolveSandboxPolicy(request, defaults) {
+	const approval = request.approval === void 0 ? void 0 : requireSandboxApproval(request.approval);
+	const ceiling = request.sessionMode ?? defaults.mode;
+	if (!isSandboxMode(ceiling)) throw new SandboxPolicyError(`Unknown sandbox mode '${String(ceiling)}'`);
+	const requested = request.mode;
+	if (requested !== void 0 && !isSandboxMode(requested)) throw new SandboxPolicyError(`Unknown sandbox mode '${String(requested)}'`);
+	const narrowed = requested !== void 0 && modeAuthority(requested) < modeAuthority(ceiling) ? requested : ceiling;
+	const mode = approval?.mode ?? narrowed;
+	const workspaceRoot = normalizePath(request.cwd ?? defaults.workspaceRoot);
+	if (!isAbsolutePath(workspaceRoot)) throw new SandboxPolicyError(`Sandbox workspace root must be absolute, received '${workspaceRoot}'`);
+	for (const entry of request.entries ?? []) if (entry.access === "write") throw new SandboxPolicyError(`A requested entry may not grant write access to '${entry.path}'; widening a policy requires an approval minted by approveSandboxEscalation()`);
+	const entries = orderEntries(defaults.entries ?? []);
+	const restrictions = orderEntries(request.entries ?? []);
+	const approvedEntries = orderEntries(approval?.entries ?? []);
+	const network = approval?.network ?? narrowNetwork(defaults.network ?? "allow-all", request.network);
+	return Object.freeze({
+		mode,
+		workspaceRoot,
+		network,
+		...defaults.baseline === void 0 ? {} : { baseline: defaults.baseline },
+		...entries.length === 0 ? {} : { entries },
+		...restrictions.length === 0 ? {} : { restrictions },
+		...approvedEntries.length === 0 ? {} : { approvedEntries },
+		...request.sessionId === void 0 ? {} : { sessionId: request.sessionId }
+	});
+}
+/**
+* Narrow a resolved policy to the confining shape a provider accepts.
+* @returns the confining policy, or `undefined` under `danger-full-access`,
+*   whose consumer spawns its original argv and never calls the provider.
+*/
+function confiningPolicy(policy) {
+	return isConfinedMode(policy.mode) ? policy : void 0;
+}
+/**
+* Narrow a policy toward a stricter mode without widening it. Used where a
+* consumer may tighten a caller's policy but must never loosen it.
+*/
+function narrowPolicy(policy, mode) {
+	return modeAuthority(mode) < modeAuthority(policy.mode) ? Object.freeze({
+		...policy,
+		mode
+	}) : policy;
+}
+
+//#endregion
+//#region src/resources.ts
+/** Whether any limit is set at all, so a caller can skip supervision entirely. */
+function hasResourceLimits(limits) {
+	return limits.wallClockMs !== void 0 || limits.memoryBytes !== void 0 || limits.processes !== void 0 || limits.cpuMs !== void 0;
+}
+/**
+* The first limit the usage exceeds, or `undefined` while it is within them.
+* Checked in the order a runaway usually announces itself.
+*/
+function breachedLimit(usage, limits) {
+	if (limits.wallClockMs !== void 0 && usage.wallClockMs > limits.wallClockMs) return "wall-clock";
+	if (limits.processes !== void 0 && usage.peakProcesses > limits.processes) return "processes";
+	if (limits.memoryBytes !== void 0 && usage.peakMemoryBytes > limits.memoryBytes) return "memory";
+	if (limits.cpuMs !== void 0 && usage.cpuMs > limits.cpuMs) return "cpu";
+}
+
+//#endregion
+//#region src/violation.ts
+/** Upper bound on retained evidence, so a violation never carries a log dump. */
+const SNIPPET_MAX_LENGTH = 512;
+const REASON_SIGNATURES = Object.freeze([
+	["operation-not-permitted", "operation not permitted"],
+	["permission-denied", "permission denied"],
+	["read-only-filesystem", "read-only file system"],
+	["read-only-filesystem", "erofs"],
+	["policy-denied", "seccomp"],
+	["policy-denied", "landlock"]
+]);
+/**
+* Build a violation record from a classified outcome.
+* @returns the record, or `undefined` when the outcome was not a violation.
+*/
+function sandboxViolation(classification, backend, mode) {
+	if (classification.kind !== "denied" && classification.kind !== "runner-failure") return void 0;
+	const evidence = classification.evidence ?? "";
+	const reason = classification.kind === "runner-failure" ? "runner-failure" : reasonFor(evidence);
+	const path = pathIn(evidence);
+	return Object.freeze({
+		backend,
+		reason,
+		mode,
+		...path === void 0 ? {} : { path },
+		snippet: evidence.slice(0, SNIPPET_MAX_LENGTH)
+	});
+}
+/** Map one evidence line to a normalized reason. */
+function reasonFor(evidence) {
+	const haystack = evidence.toLowerCase();
+	for (const [reason, signature] of REASON_SIGNATURES) if (haystack.includes(signature)) return reason;
+	return "policy-denied";
+}
+/** Extract the first absolute path a denial message mentions, if any. */
+function pathIn(evidence) {
+	return /(\/[^\s:'"]+|[A-Za-z]:[\\/][^\s:'"]*)/.exec(evidence)?.[0];
+}
+
+//#endregion
+export { BASELINE_ACCESS, DEFAULT_EXEC_OUTCOMES, NETWORK_MODES, PROTECTED_SUBPATHS, SANDBOX_MODES, SandboxDeniedError, SandboxPolicyError, SandboxUnavailableError, accessFor, accessInLayers, ancestorPaths, annotateStderr, approveSandboxEscalation, breachedLimit, classifyExec, classifyOutcome, confiningPolicy, containsPath, createFsFence, dedupeRoots, detectFlavor, entriesWithin, grantLayers, hasResourceLimits, isAbsolutePath, isConfinedMode, isNetworkMode, isSandboxApproval, isSandboxApprovalSpent, isSandboxMode, joinPath, modeAuthority, narrowNetwork, narrowPolicy, networkAuthority, normalizePath, orderEntries, parentPath, pathDepth, pathSegments, requireSandboxApproval, resolveSandboxPolicy, samePath, sandboxViolation, splitCommands, tokenizeScript, unreadablePaths, writableRoots };
+//# sourceMappingURL=index.js.map