apex-code 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/core/sandbox/network-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-refusal.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/network-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAwBH;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK7F;AASD;;;;;GAKG;AACH,wBAAgB,oCAAoC,IAAI,IAAI,CAW3D","sourcesContent":["/**\n * Turn a sandbox allowlist refusal into a message the user can act on.\n *\n * The child reaches the network only through the supervisor's CONNECT proxy, which\n * answers 403 for any host absent from `network.allowedHosts`. undici reports that as\n * `Proxy response (403) !== 200 when HTTP Tunneling`, but fetch surfaces only the\n * generic `fetch failed` at the top of the cause chain — so the caller sees a network\n * error with no host, no reason, and no remedy. Recovering the detail here is what\n * separates \"something is broken\" from \"this host is not on the allowlist\".\n */\n\n/** undici's own wording for a tunnel the proxy declined to open. */\nconst TUNNEL_REFUSAL = /Proxy response \\((\\d+)\\) !== 200 when HTTP Tunneling/;\n\nconst MAXIMUM_CAUSE_DEPTH = 8;\n\nfunction findTunnelRefusal(error: unknown): boolean {\n\tlet current: unknown = error;\n\tfor (let depth = 0; depth < MAXIMUM_CAUSE_DEPTH && current instanceof Error; depth++) {\n\t\tif (TUNNEL_REFUSAL.test(current.message)) return true;\n\t\tcurrent = current.cause;\n\t}\n\treturn false;\n}\n\nfunction hostFromUrl(url: string): string | undefined {\n\ttry {\n\t\treturn new URL(url).host;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/**\n * Describe a refused request, or return undefined when the failure was something else.\n * Only the sandboxed child installs this, so attributing the refusal to the sandbox\n * allowlist is accurate rather than a guess about whose proxy answered.\n */\nexport function describeSandboxNetworkRefusal(error: unknown, url: string): string | undefined {\n\tif (!findTunnelRefusal(error)) return undefined;\n\tconst host = hostFromUrl(url);\n\tconst subject = host ? `Host ${host} is` : \"That host is\";\n\treturn `${subject} not on the sandbox network allowlist, so the request was refused. Add it to \"network.allowedHosts\" in your global Apex Code settings to permit it.`;\n}\n\nfunction requestUrl(input: unknown): string {\n\tif (typeof input === \"string\") return input;\n\tif (input instanceof URL) return input.href;\n\tif (input instanceof Request) return input.url;\n\treturn \"\";\n}\n\n/**\n * Wrap global fetch so every caller — model providers, the version check, catalogs —\n * reports a refusal in the same actionable terms without each having to know the\n * sandbox exists. The original error is preserved as `cause`, and anything that is not\n * a refusal is rethrown untouched so retry and abort handling behave exactly as before.\n */\nexport function installSandboxNetworkRefusalMessages(): void {\n\tconst wrapped = globalThis.fetch;\n\tglobalThis.fetch = async function fetchWithRefusalDetail(input, init) {\n\t\ttry {\n\t\t\treturn await wrapped(input, init);\n\t\t} catch (error) {\n\t\t\tconst description = describeSandboxNetworkRefusal(error, requestUrl(input));\n\t\t\tif (!description) throw error;\n\t\t\tthrow new Error(description, { cause: error });\n\t\t}\n\t} as typeof globalThis.fetch;\n}\n"]}

package/dist/core/sandbox/network-refusal.js

@@ -0,0 +1,72 @@
+/**
+ * Turn a sandbox allowlist refusal into a message the user can act on.
+ *
+ * The child reaches the network only through the supervisor's CONNECT proxy, which
+ * answers 403 for any host absent from `network.allowedHosts`. undici reports that as
+ * `Proxy response (403) !== 200 when HTTP Tunneling`, but fetch surfaces only the
+ * generic `fetch failed` at the top of the cause chain — so the caller sees a network
+ * error with no host, no reason, and no remedy. Recovering the detail here is what
+ * separates "something is broken" from "this host is not on the allowlist".
+ */
+/** undici's own wording for a tunnel the proxy declined to open. */
+const TUNNEL_REFUSAL = /Proxy response \((\d+)\) !== 200 when HTTP Tunneling/;
+const MAXIMUM_CAUSE_DEPTH = 8;
+function findTunnelRefusal(error) {
+    let current = error;
+    for (let depth = 0; depth < MAXIMUM_CAUSE_DEPTH && current instanceof Error; depth++) {
+        if (TUNNEL_REFUSAL.test(current.message))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+function hostFromUrl(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Describe a refused request, or return undefined when the failure was something else.
+ * Only the sandboxed child installs this, so attributing the refusal to the sandbox
+ * allowlist is accurate rather than a guess about whose proxy answered.
+ */
+export function describeSandboxNetworkRefusal(error, url) {
+    if (!findTunnelRefusal(error))
+        return undefined;
+    const host = hostFromUrl(url);
+    const subject = host ? `Host ${host} is` : "That host is";
+    return `${subject} not on the sandbox network allowlist, so the request was refused. Add it to "network.allowedHosts" in your global Apex Code settings to permit it.`;
+}
+function requestUrl(input) {
+    if (typeof input === "string")
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    if (input instanceof Request)
+        return input.url;
+    return "";
+}
+/**
+ * Wrap global fetch so every caller — model providers, the version check, catalogs —
+ * reports a refusal in the same actionable terms without each having to know the
+ * sandbox exists. The original error is preserved as `cause`, and anything that is not
+ * a refusal is rethrown untouched so retry and abort handling behave exactly as before.
+ */
+export function installSandboxNetworkRefusalMessages() {
+    const wrapped = globalThis.fetch;
+    globalThis.fetch = async function fetchWithRefusalDetail(input, init) {
+        try {
+            return await wrapped(input, init);
+        }
+        catch (error) {
+            const description = describeSandboxNetworkRefusal(error, requestUrl(input));
+            if (!description)
+                throw error;
+            throw new Error(description, { cause: error });
+        }
+    };
+}
+//# sourceMappingURL=network-refusal.js.map

package/dist/core/sandbox/network-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-refusal.js","sourceRoot":"","sources":["../../../src/core/sandbox/network-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,oEAAoE;AACpE,MAAM,cAAc,GAAG,sDAAsD,CAAC;AAE9E,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B,SAAS,iBAAiB,CAAC,KAAc,EAAW;IACnD,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,mBAAmB,IAAI,OAAO,YAAY,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;QACtF,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QACtD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;IACzB,CAAC;IACD,OAAO,KAAK,CAAC;AAAA,CACb;AAED,SAAS,WAAW,CAAC,GAAW,EAAsB;IACrD,IAAI,CAAC;QACJ,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,SAAS,CAAC;IAClB,CAAC;AAAA,CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAAC,KAAc,EAAE,GAAW,EAAsB;IAC9F,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC;IAC1D,OAAO,GAAG,OAAO,qJAAqJ,CAAC;AAAA,CACvK;AAED,SAAS,UAAU,CAAC,KAAc,EAAU;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,YAAY,GAAG;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC;IAC5C,IAAI,KAAK,YAAY,OAAO;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC;IAC/C,OAAO,EAAE,CAAC;AAAA,CACV;AAED;;;;;GAKG;AACH,MAAM,UAAU,oCAAoC,GAAS;IAC5D,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC;IACjC,UAAU,CAAC,KAAK,GAAG,KAAK,UAAU,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE;QACrE,IAAI,CAAC;YACJ,OAAO,MAAM,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,WAAW,GAAG,6BAA6B,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;YAC5E,IAAI,CAAC,WAAW;gBAAE,MAAM,KAAK,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAChD,CAAC;IAAA,CAC0B,CAAC;AAAA,CAC7B","sourcesContent":["/**\n * Turn a sandbox allowlist refusal into a message the user can act on.\n *\n * The child reaches the network only through the supervisor's CONNECT proxy, which\n * answers 403 for any host absent from `network.allowedHosts`. undici reports that as\n * `Proxy response (403) !== 200 when HTTP Tunneling`, but fetch surfaces only the\n * generic `fetch failed` at the top of the cause chain — so the caller sees a network\n * error with no host, no reason, and no remedy. Recovering the detail here is what\n * separates \"something is broken\" from \"this host is not on the allowlist\".\n */\n\n/** undici's own wording for a tunnel the proxy declined to open. */\nconst TUNNEL_REFUSAL = /Proxy response \\((\\d+)\\) !== 200 when HTTP Tunneling/;\n\nconst MAXIMUM_CAUSE_DEPTH = 8;\n\nfunction findTunnelRefusal(error: unknown): boolean {\n\tlet current: unknown = error;\n\tfor (let depth = 0; depth < MAXIMUM_CAUSE_DEPTH && current instanceof Error; depth++) {\n\t\tif (TUNNEL_REFUSAL.test(current.message)) return true;\n\t\tcurrent = current.cause;\n\t}\n\treturn false;\n}\n\nfunction hostFromUrl(url: string): string | undefined {\n\ttry {\n\t\treturn new URL(url).host;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/**\n * Describe a refused request, or return undefined when the failure was something else.\n * Only the sandboxed child installs this, so attributing the refusal to the sandbox\n * allowlist is accurate rather than a guess about whose proxy answered.\n */\nexport function describeSandboxNetworkRefusal(error: unknown, url: string): string | undefined {\n\tif (!findTunnelRefusal(error)) return undefined;\n\tconst host = hostFromUrl(url);\n\tconst subject = host ? `Host ${host} is` : \"That host is\";\n\treturn `${subject} not on the sandbox network allowlist, so the request was refused. Add it to \"network.allowedHosts\" in your global Apex Code settings to permit it.`;\n}\n\nfunction requestUrl(input: unknown): string {\n\tif (typeof input === \"string\") return input;\n\tif (input instanceof URL) return input.href;\n\tif (input instanceof Request) return input.url;\n\treturn \"\";\n}\n\n/**\n * Wrap global fetch so every caller — model providers, the version check, catalogs —\n * reports a refusal in the same actionable terms without each having to know the\n * sandbox exists. The original error is preserved as `cause`, and anything that is not\n * a refusal is rethrown untouched so retry and abort handling behave exactly as before.\n */\nexport function installSandboxNetworkRefusalMessages(): void {\n\tconst wrapped = globalThis.fetch;\n\tglobalThis.fetch = async function fetchWithRefusalDetail(input, init) {\n\t\ttry {\n\t\t\treturn await wrapped(input, init);\n\t\t} catch (error) {\n\t\t\tconst description = describeSandboxNetworkRefusal(error, requestUrl(input));\n\t\t\tif (!description) throw error;\n\t\t\tthrow new Error(description, { cause: error });\n\t\t}\n\t} as typeof globalThis.fetch;\n}\n"]}

package/dist/core/sandbox/policy.d.ts

@@ -0,0 +1,40 @@
+export interface SandboxPolicy {
+    /**
+     * The one directory the session is anchored to. State, sessions, and the concurrency
+     * lease all live under it, and the child starts here, so it stays singular even when
+     * more roots are writable.
+     */
+    readonly workspace: string;
+    readonly allowedHosts: readonly string[];
+    /** Further writable directories, named on the command line and validated the same way. */
+    readonly additionalWritableRoots: readonly string[];
+}
+export type SandboxPolicyResult = {
+    readonly kind: "valid";
+    readonly policy: SandboxPolicy;
+} | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+export type SandboxStatus = {
+    readonly kind: "enforced";
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+export declare class SandboxUnavailableError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Validate the single writable boundary before any platform backend runs. We accept
+ * no relative, missing, or non-directory workspace because a backend must never
+ * silently broaden an ambiguous path into host authority.
+ */
+export declare function createSandboxPolicy(options: {
+    workspace: string;
+    allowedHosts?: readonly string[];
+    additionalWritableRoots?: readonly string[];
+}): SandboxPolicyResult;
+/** Throws rather than returning an executable fallback when OS enforcement is absent. */
+export declare function requireSandboxEnforcement(status: SandboxStatus): void;
+//# sourceMappingURL=policy.d.ts.map

package/dist/core/sandbox/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,0FAA0F;IAC1F,QAAQ,CAAC,uBAAuB,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAED,MAAM,MAAM,mBAAmB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtH,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,YAAY,MAAM,EAAE,MAAM,EAGzB;CACD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C,GAAG,mBAAmB,CAetB;AAsBD,yFAAyF;AACzF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAGrE","sourcesContent":["import { existsSync, realpathSync, statSync } from \"node:fs\";\nimport { isAbsolute } from \"node:path\";\n\nexport interface SandboxPolicy {\n\t/**\n\t * The one directory the session is anchored to. State, sessions, and the concurrency\n\t * lease all live under it, and the child starts here, so it stays singular even when\n\t * more roots are writable.\n\t */\n\treadonly workspace: string;\n\treadonly allowedHosts: readonly string[];\n\t/** Further writable directories, named on the command line and validated the same way. */\n\treadonly additionalWritableRoots: readonly string[];\n}\n\nexport type SandboxPolicyResult =\n\t| { readonly kind: \"valid\"; readonly policy: SandboxPolicy }\n\t| { readonly kind: \"invalid\"; readonly reason: string };\n\nexport type SandboxStatus = { readonly kind: \"enforced\" } | { readonly kind: \"unavailable\"; readonly reason: string };\n\nexport class SandboxUnavailableError extends Error {\n\tconstructor(reason: string) {\n\t\tsuper(`OS sandbox is not enforcing this agent session: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\n/**\n * Validate the single writable boundary before any platform backend runs. We accept\n * no relative, missing, or non-directory workspace because a backend must never\n * silently broaden an ambiguous path into host authority.\n */\nexport function createSandboxPolicy(options: {\n\tworkspace: string;\n\tallowedHosts?: readonly string[];\n\tadditionalWritableRoots?: readonly string[];\n}): SandboxPolicyResult {\n\tconst workspace = validateRoot(options.workspace, \"workspace\");\n\tif (typeof workspace !== \"string\") return workspace;\n\n\tconst additionalWritableRoots: string[] = [];\n\tfor (const candidate of options.additionalWritableRoots ?? []) {\n\t\tconst resolved = validateRoot(candidate, \"writable root\");\n\t\tif (typeof resolved !== \"string\") return resolved;\n\t\tadditionalWritableRoots.push(resolved);\n\t}\n\n\treturn {\n\t\tkind: \"valid\",\n\t\tpolicy: { workspace, allowedHosts: options.allowedHosts ?? [], additionalWritableRoots },\n\t};\n}\n\n/**\n * Resolve one writable root, or explain why it cannot be one.\n *\n * Every root goes through the same check for the same reason the workspace always did: a\n * backend must never silently broaden an ambiguous path into host authority, and an extra\n * root named on the command line is no less capable of doing that than the first one.\n */\nfunction validateRoot(candidate: string, label: string): string | { kind: \"invalid\"; reason: string } {\n\tif (!isAbsolute(candidate)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} must be an absolute path: ${candidate}` };\n\t}\n\tif (!existsSync(candidate)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} does not exist: ${candidate}` };\n\t}\n\tif (!statSync(candidate).isDirectory()) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} is not a directory: ${candidate}` };\n\t}\n\treturn realpathSync(candidate);\n}\n\n/** Throws rather than returning an executable fallback when OS enforcement is absent. */\nexport function requireSandboxEnforcement(status: SandboxStatus): void {\n\tif (status.kind === \"enforced\") return;\n\tthrow new SandboxUnavailableError(status.reason);\n}\n"]}

package/dist/core/sandbox/policy.js

@@ -0,0 +1,55 @@
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+export class SandboxUnavailableError extends Error {
+    constructor(reason) {
+        super(`OS sandbox is not enforcing this agent session: ${reason}`);
+        this.name = "SandboxUnavailableError";
+    }
+}
+/**
+ * Validate the single writable boundary before any platform backend runs. We accept
+ * no relative, missing, or non-directory workspace because a backend must never
+ * silently broaden an ambiguous path into host authority.
+ */
+export function createSandboxPolicy(options) {
+    const workspace = validateRoot(options.workspace, "workspace");
+    if (typeof workspace !== "string")
+        return workspace;
+    const additionalWritableRoots = [];
+    for (const candidate of options.additionalWritableRoots ?? []) {
+        const resolved = validateRoot(candidate, "writable root");
+        if (typeof resolved !== "string")
+            return resolved;
+        additionalWritableRoots.push(resolved);
+    }
+    return {
+        kind: "valid",
+        policy: { workspace, allowedHosts: options.allowedHosts ?? [], additionalWritableRoots },
+    };
+}
+/**
+ * Resolve one writable root, or explain why it cannot be one.
+ *
+ * Every root goes through the same check for the same reason the workspace always did: a
+ * backend must never silently broaden an ambiguous path into host authority, and an extra
+ * root named on the command line is no less capable of doing that than the first one.
+ */
+function validateRoot(candidate, label) {
+    if (!isAbsolute(candidate)) {
+        return { kind: "invalid", reason: `Sandbox ${label} must be an absolute path: ${candidate}` };
+    }
+    if (!existsSync(candidate)) {
+        return { kind: "invalid", reason: `Sandbox ${label} does not exist: ${candidate}` };
+    }
+    if (!statSync(candidate).isDirectory()) {
+        return { kind: "invalid", reason: `Sandbox ${label} is not a directory: ${candidate}` };
+    }
+    return realpathSync(candidate);
+}
+/** Throws rather than returning an executable fallback when OS enforcement is absent. */
+export function requireSandboxEnforcement(status) {
+    if (status.kind === "enforced")
+        return;
+    throw new SandboxUnavailableError(status.reason);
+}
+//# sourceMappingURL=policy.js.map

package/dist/core/sandbox/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAoBvC,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACjD,YAAY,MAAc,EAAE;QAC3B,KAAK,CAAC,mDAAmD,MAAM,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IAAA,CACtC;CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAInC,EAAuB;IACvB,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC/D,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAEpD,MAAM,uBAAuB,GAAa,EAAE,CAAC;IAC7C,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,uBAAuB,IAAI,EAAE,EAAE,CAAC;QAC/D,MAAM,QAAQ,GAAG,YAAY,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;QAC1D,IAAI,OAAO,QAAQ,KAAK,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAClD,uBAAuB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,OAAO;QACN,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE,EAAE,uBAAuB,EAAE;KACxF,CAAC;AAAA,CACF;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,SAAiB,EAAE,KAAa,EAAgD;IACrG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,KAAK,8BAA8B,SAAS,EAAE,EAAE,CAAC;IAC/F,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,KAAK,oBAAoB,SAAS,EAAE,EAAE,CAAC;IACrF,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,KAAK,wBAAwB,SAAS,EAAE,EAAE,CAAC;IACzF,CAAC;IACD,OAAO,YAAY,CAAC,SAAS,CAAC,CAAC;AAAA,CAC/B;AAED,yFAAyF;AACzF,MAAM,UAAU,yBAAyB,CAAC,MAAqB,EAAQ;IACtE,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO;IACvC,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAAA,CACjD","sourcesContent":["import { existsSync, realpathSync, statSync } from \"node:fs\";\nimport { isAbsolute } from \"node:path\";\n\nexport interface SandboxPolicy {\n\t/**\n\t * The one directory the session is anchored to. State, sessions, and the concurrency\n\t * lease all live under it, and the child starts here, so it stays singular even when\n\t * more roots are writable.\n\t */\n\treadonly workspace: string;\n\treadonly allowedHosts: readonly string[];\n\t/** Further writable directories, named on the command line and validated the same way. */\n\treadonly additionalWritableRoots: readonly string[];\n}\n\nexport type SandboxPolicyResult =\n\t| { readonly kind: \"valid\"; readonly policy: SandboxPolicy }\n\t| { readonly kind: \"invalid\"; readonly reason: string };\n\nexport type SandboxStatus = { readonly kind: \"enforced\" } | { readonly kind: \"unavailable\"; readonly reason: string };\n\nexport class SandboxUnavailableError extends Error {\n\tconstructor(reason: string) {\n\t\tsuper(`OS sandbox is not enforcing this agent session: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t}\n}\n\n/**\n * Validate the single writable boundary before any platform backend runs. We accept\n * no relative, missing, or non-directory workspace because a backend must never\n * silently broaden an ambiguous path into host authority.\n */\nexport function createSandboxPolicy(options: {\n\tworkspace: string;\n\tallowedHosts?: readonly string[];\n\tadditionalWritableRoots?: readonly string[];\n}): SandboxPolicyResult {\n\tconst workspace = validateRoot(options.workspace, \"workspace\");\n\tif (typeof workspace !== \"string\") return workspace;\n\n\tconst additionalWritableRoots: string[] = [];\n\tfor (const candidate of options.additionalWritableRoots ?? []) {\n\t\tconst resolved = validateRoot(candidate, \"writable root\");\n\t\tif (typeof resolved !== \"string\") return resolved;\n\t\tadditionalWritableRoots.push(resolved);\n\t}\n\n\treturn {\n\t\tkind: \"valid\",\n\t\tpolicy: { workspace, allowedHosts: options.allowedHosts ?? [], additionalWritableRoots },\n\t};\n}\n\n/**\n * Resolve one writable root, or explain why it cannot be one.\n *\n * Every root goes through the same check for the same reason the workspace always did: a\n * backend must never silently broaden an ambiguous path into host authority, and an extra\n * root named on the command line is no less capable of doing that than the first one.\n */\nfunction validateRoot(candidate: string, label: string): string | { kind: \"invalid\"; reason: string } {\n\tif (!isAbsolute(candidate)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} must be an absolute path: ${candidate}` };\n\t}\n\tif (!existsSync(candidate)) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} does not exist: ${candidate}` };\n\t}\n\tif (!statSync(candidate).isDirectory()) {\n\t\treturn { kind: \"invalid\", reason: `Sandbox ${label} is not a directory: ${candidate}` };\n\t}\n\treturn realpathSync(candidate);\n}\n\n/** Throws rather than returning an executable fallback when OS enforcement is absent. */\nexport function requireSandboxEnforcement(status: SandboxStatus): void {\n\tif (status.kind === \"enforced\") return;\n\tthrow new SandboxUnavailableError(status.reason);\n}\n"]}

package/dist/core/sandbox/profiles.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A named, saved combination of what the OS boundary permits.
+ *
+ * Apex already has a permission rule model with five modes and eight-source precedence
+ * (ADR 0004). That governs the tool gate at `beforeToolCall`, inside the child. This
+ * governs the supervisor's launch contract, outside it. They are deliberately separate
+ * surfaces, and conflating them is exactly the misreading that makes `bypassPermissions`
+ * look like a sandbox escape -- so a profile here carries only boundary inputs and has no
+ * way to express a tool-gate mode.
+ *
+ * It also has no way to express "no boundary". That decision stays on the command line
+ * where a human has to type it, per ADR 0005's 2026-08-28 amendment; a profile can widen
+ * what is reachable and writable, never remove the boundary that constrains them.
+ *
+ * Resolved from global settings only, with `projectTrusted: false`, for the reason ADR
+ * 0016 gives for every supervisor policy input: a repository that could define the
+ * boundary it runs under would be granting itself authority.
+ */
+export interface SandboxProfile {
+    readonly allowedHosts: readonly string[];
+    readonly additionalWritableRoots: readonly string[];
+}
+/** Resolve one named profile, or undefined when the name is absent or was never given. */
+export declare function resolveSandboxProfile(name: string | undefined, cwd: string, agentDir: string): SandboxProfile | undefined;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/core/sandbox/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/profiles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,uBAAuB,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAMD,0FAA0F;AAC1F,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACd,cAAc,GAAG,SAAS,CAc5B","sourcesContent":["import { SettingsManager } from \"../settings-manager.ts\";\n\n/**\n * A named, saved combination of what the OS boundary permits.\n *\n * Apex already has a permission rule model with five modes and eight-source precedence\n * (ADR 0004). That governs the tool gate at `beforeToolCall`, inside the child. This\n * governs the supervisor's launch contract, outside it. They are deliberately separate\n * surfaces, and conflating them is exactly the misreading that makes `bypassPermissions`\n * look like a sandbox escape -- so a profile here carries only boundary inputs and has no\n * way to express a tool-gate mode.\n *\n * It also has no way to express \"no boundary\". That decision stays on the command line\n * where a human has to type it, per ADR 0005's 2026-08-28 amendment; a profile can widen\n * what is reachable and writable, never remove the boundary that constrains them.\n *\n * Resolved from global settings only, with `projectTrusted: false`, for the reason ADR\n * 0016 gives for every supervisor policy input: a repository that could define the\n * boundary it runs under would be granting itself authority.\n */\nexport interface SandboxProfile {\n\treadonly allowedHosts: readonly string[];\n\treadonly additionalWritableRoots: readonly string[];\n}\n\nfunction stringArray(value: unknown): string[] {\n\treturn Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === \"string\") : [];\n}\n\n/** Resolve one named profile, or undefined when the name is absent or was never given. */\nexport function resolveSandboxProfile(\n\tname: string | undefined,\n\tcwd: string,\n\tagentDir: string,\n): SandboxProfile | undefined {\n\tif (!name) return undefined;\n\tconst settings = SettingsManager.create(cwd, agentDir, { projectTrusted: false });\n\tconst profiles = settings.getSandboxProfiles();\n\tconst profile = profiles?.[name];\n\tif (!profile || typeof profile !== \"object\") return undefined;\n\tconst record = profile as Record<string, unknown>;\n\t// Only these two keys are read. An unknown key in a profile is ignored rather than\n\t// rejected, so a profile written for a later version does not break this one, and a\n\t// key this version does not understand can never take effect by accident.\n\treturn {\n\t\tallowedHosts: stringArray(record.allowedHosts),\n\t\tadditionalWritableRoots: stringArray(record.additionalWritableRoots),\n\t};\n}\n"]}

package/dist/core/sandbox/profiles.js

@@ -0,0 +1,23 @@
+import { SettingsManager } from "../settings-manager.js";
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+/** Resolve one named profile, or undefined when the name is absent or was never given. */
+export function resolveSandboxProfile(name, cwd, agentDir) {
+    if (!name)
+        return undefined;
+    const settings = SettingsManager.create(cwd, agentDir, { projectTrusted: false });
+    const profiles = settings.getSandboxProfiles();
+    const profile = profiles?.[name];
+    if (!profile || typeof profile !== "object")
+        return undefined;
+    const record = profile;
+    // Only these two keys are read. An unknown key in a profile is ignored rather than
+    // rejected, so a profile written for a later version does not break this one, and a
+    // key this version does not understand can never take effect by accident.
+    return {
+        allowedHosts: stringArray(record.allowedHosts),
+        additionalWritableRoots: stringArray(record.additionalWritableRoots),
+    };
+}
+//# sourceMappingURL=profiles.js.map

package/dist/core/sandbox/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../../src/core/sandbox/profiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAyBzD,SAAS,WAAW,CAAC,KAAc,EAAY;IAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAAA,CACvG;AAED,0FAA0F;AAC1F,MAAM,UAAU,qBAAqB,CACpC,IAAwB,EACxB,GAAW,EACX,QAAgB,EACa;IAC7B,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;IAClF,MAAM,QAAQ,GAAG,QAAQ,CAAC,kBAAkB,EAAE,CAAC;IAC/C,MAAM,OAAO,GAAG,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9D,MAAM,MAAM,GAAG,OAAkC,CAAC;IAClD,mFAAmF;IACnF,oFAAoF;IACpF,0EAA0E;IAC1E,OAAO;QACN,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,YAAY,CAAC;QAC9C,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAAC,uBAAuB,CAAC;KACpE,CAAC;AAAA,CACF","sourcesContent":["import { SettingsManager } from \"../settings-manager.ts\";\n\n/**\n * A named, saved combination of what the OS boundary permits.\n *\n * Apex already has a permission rule model with five modes and eight-source precedence\n * (ADR 0004). That governs the tool gate at `beforeToolCall`, inside the child. This\n * governs the supervisor's launch contract, outside it. They are deliberately separate\n * surfaces, and conflating them is exactly the misreading that makes `bypassPermissions`\n * look like a sandbox escape -- so a profile here carries only boundary inputs and has no\n * way to express a tool-gate mode.\n *\n * It also has no way to express \"no boundary\". That decision stays on the command line\n * where a human has to type it, per ADR 0005's 2026-08-28 amendment; a profile can widen\n * what is reachable and writable, never remove the boundary that constrains them.\n *\n * Resolved from global settings only, with `projectTrusted: false`, for the reason ADR\n * 0016 gives for every supervisor policy input: a repository that could define the\n * boundary it runs under would be granting itself authority.\n */\nexport interface SandboxProfile {\n\treadonly allowedHosts: readonly string[];\n\treadonly additionalWritableRoots: readonly string[];\n}\n\nfunction stringArray(value: unknown): string[] {\n\treturn Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === \"string\") : [];\n}\n\n/** Resolve one named profile, or undefined when the name is absent or was never given. */\nexport function resolveSandboxProfile(\n\tname: string | undefined,\n\tcwd: string,\n\tagentDir: string,\n): SandboxProfile | undefined {\n\tif (!name) return undefined;\n\tconst settings = SettingsManager.create(cwd, agentDir, { projectTrusted: false });\n\tconst profiles = settings.getSandboxProfiles();\n\tconst profile = profiles?.[name];\n\tif (!profile || typeof profile !== \"object\") return undefined;\n\tconst record = profile as Record<string, unknown>;\n\t// Only these two keys are read. An unknown key in a profile is ignored rather than\n\t// rejected, so a profile written for a later version does not break this one, and a\n\t// key this version does not understand can never take effect by accident.\n\treturn {\n\t\tallowedHosts: stringArray(record.allowedHosts),\n\t\tadditionalWritableRoots: stringArray(record.additionalWritableRoots),\n\t};\n}\n"]}

package/dist/core/sandbox/rpc/command-client.d.ts

@@ -0,0 +1,28 @@
+/** The absolute path a sandbox filesystem refusal named, if the output named one. */
+export declare function extractRefusedPath(output: string): string | undefined;
+/** True when the output looks like the boundary refused a write rather than the command failing. */
+export declare function looksLikeSandboxRefusal(output: string): boolean;
+/**
+ * The directory an escalation should make writable for a refused path.
+ *
+ * The parent, not the file: the command was creating something that does not exist, and a
+ * bind of a non-existent path is not a mount bwrap can make.
+ */
+export declare function escalationRootFor(refusedPath: string): string;
+export interface EscalationOutcome {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Ask the supervisor to run one command with one extra writable root.
+ *
+ * Resolves undefined for every refusal and every failure alike, because the caller's
+ * behaviour is identical in both cases: report the original error. Only a command that
+ * actually ran returns anything.
+ */
+export declare function requestCommandEscalation(request: {
+    command: string;
+    writableRoot: string;
+}, socketPath?: string | undefined): Promise<EscalationOutcome | undefined>;
+//# sourceMappingURL=command-client.d.ts.map

package/dist/core/sandbox/rpc/command-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-client.d.ts","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/command-client.ts"],"names":[],"mappings":"AAsBA,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOrE;AAED,oGAAoG;AACpG,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAClD,UAAU,qBAAkD,GAC1D,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAgCxC","sourcesContent":["import * as net from \"node:net\";\nimport { dirname, isAbsolute } from \"node:path\";\nimport { COMMAND_ESCALATION_SOCKET_VARIABLE } from \"./command-proxy.ts\";\n\n/**\n * The child's side of per-command escalation.\n *\n * The path this extracts is a guess, and it is allowed to be, because nothing safe rests\n * on it. The supervisor shows the human the exact command and the exact root before\n * anything runs, so a bad guess is refused by someone reading it rather than silently\n * granted. What the guess buys is not having to make the user work out which directory to\n * name; when it finds nothing, no escalation is offered and the command fails as it did\n * before.\n */\n\n/** The wordings the kernel and the shell actually produce for a mount refusal. */\nconst REFUSAL_PATTERNS: readonly RegExp[] = [\n\t/cannot (?:create|touch|remove|open) ['\"]?([^'\":]+)['\"]?: (?:Read-only file system|Permission denied)/i,\n\t/^[^:]*: ?([/][^\\s:]+): (?:Operation not permitted|Permission denied|Read-only file system)/im,\n\t/(?:EROFS|EACCES|EPERM)[^'\"]*['\"]([/][^'\"]+)['\"]/,\n];\n\n/** The absolute path a sandbox filesystem refusal named, if the output named one. */\nexport function extractRefusedPath(output: string): string | undefined {\n\tfor (const pattern of REFUSAL_PATTERNS) {\n\t\tconst match = pattern.exec(output);\n\t\tconst candidate = match?.[1]?.trim();\n\t\tif (candidate && isAbsolute(candidate)) return candidate;\n\t}\n\treturn undefined;\n}\n\n/** True when the output looks like the boundary refused a write rather than the command failing. */\nexport function looksLikeSandboxRefusal(output: string): boolean {\n\treturn /Read-only file system|Operation not permitted|Permission denied/i.test(output);\n}\n\n/**\n * The directory an escalation should make writable for a refused path.\n *\n * The parent, not the file: the command was creating something that does not exist, and a\n * bind of a non-existent path is not a mount bwrap can make.\n */\nexport function escalationRootFor(refusedPath: string): string {\n\treturn dirname(refusedPath);\n}\n\nexport interface EscalationOutcome {\n\treadonly code: number;\n\treadonly stdout: string;\n\treadonly stderr: string;\n}\n\n/**\n * Ask the supervisor to run one command with one extra writable root.\n *\n * Resolves undefined for every refusal and every failure alike, because the caller's\n * behaviour is identical in both cases: report the original error. Only a command that\n * actually ran returns anything.\n */\nexport function requestCommandEscalation(\n\trequest: { command: string; writableRoot: string },\n\tsocketPath = process.env[COMMAND_ESCALATION_SOCKET_VARIABLE],\n): Promise<EscalationOutcome | undefined> {\n\tif (!socketPath) return Promise.resolve(undefined);\n\treturn new Promise((resolve) => {\n\t\tconst socket = net.connect(socketPath);\n\t\tlet buffer = \"\";\n\t\tconst giveUp = () => {\n\t\t\tsocket.destroy();\n\t\t\tresolve(undefined);\n\t\t};\n\t\tsocket.on(\"connect\", () => socket.write(`${JSON.stringify({ op: \"run\", ...request })}\\n`));\n\t\tsocket.on(\"data\", (chunk) => {\n\t\t\tbuffer += chunk.toString();\n\t\t\tconst newline = buffer.indexOf(\"\\n\");\n\t\t\tif (newline < 0) return;\n\t\t\tsocket.destroy();\n\t\t\ttry {\n\t\t\t\tconst response = JSON.parse(buffer.slice(0, newline)) as Record<string, unknown>;\n\t\t\t\tif (response.ok === true && typeof response.code === \"number\") {\n\t\t\t\t\tresolve({\n\t\t\t\t\t\tcode: response.code,\n\t\t\t\t\t\tstdout: typeof response.stdout === \"string\" ? response.stdout : \"\",\n\t\t\t\t\t\tstderr: typeof response.stderr === \"string\" ? response.stderr : \"\",\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Fall through to the same undefined a refusal produces.\n\t\t\t}\n\t\t\tresolve(undefined);\n\t\t});\n\t\tsocket.on(\"error\", giveUp);\n\t});\n}\n"]}

package/dist/core/sandbox/rpc/command-client.js

@@ -0,0 +1,86 @@
+import * as net from "node:net";
+import { dirname, isAbsolute } from "node:path";
+import { COMMAND_ESCALATION_SOCKET_VARIABLE } from "./command-proxy.js";
+/**
+ * The child's side of per-command escalation.
+ *
+ * The path this extracts is a guess, and it is allowed to be, because nothing safe rests
+ * on it. The supervisor shows the human the exact command and the exact root before
+ * anything runs, so a bad guess is refused by someone reading it rather than silently
+ * granted. What the guess buys is not having to make the user work out which directory to
+ * name; when it finds nothing, no escalation is offered and the command fails as it did
+ * before.
+ */
+/** The wordings the kernel and the shell actually produce for a mount refusal. */
+const REFUSAL_PATTERNS = [
+    /cannot (?:create|touch|remove|open) ['"]?([^'":]+)['"]?: (?:Read-only file system|Permission denied)/i,
+    /^[^:]*: ?([/][^\s:]+): (?:Operation not permitted|Permission denied|Read-only file system)/im,
+    /(?:EROFS|EACCES|EPERM)[^'"]*['"]([/][^'"]+)['"]/,
+];
+/** The absolute path a sandbox filesystem refusal named, if the output named one. */
+export function extractRefusedPath(output) {
+    for (const pattern of REFUSAL_PATTERNS) {
+        const match = pattern.exec(output);
+        const candidate = match?.[1]?.trim();
+        if (candidate && isAbsolute(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** True when the output looks like the boundary refused a write rather than the command failing. */
+export function looksLikeSandboxRefusal(output) {
+    return /Read-only file system|Operation not permitted|Permission denied/i.test(output);
+}
+/**
+ * The directory an escalation should make writable for a refused path.
+ *
+ * The parent, not the file: the command was creating something that does not exist, and a
+ * bind of a non-existent path is not a mount bwrap can make.
+ */
+export function escalationRootFor(refusedPath) {
+    return dirname(refusedPath);
+}
+/**
+ * Ask the supervisor to run one command with one extra writable root.
+ *
+ * Resolves undefined for every refusal and every failure alike, because the caller's
+ * behaviour is identical in both cases: report the original error. Only a command that
+ * actually ran returns anything.
+ */
+export function requestCommandEscalation(request, socketPath = process.env[COMMAND_ESCALATION_SOCKET_VARIABLE]) {
+    if (!socketPath)
+        return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        const socket = net.connect(socketPath);
+        let buffer = "";
+        const giveUp = () => {
+            socket.destroy();
+            resolve(undefined);
+        };
+        socket.on("connect", () => socket.write(`${JSON.stringify({ op: "run", ...request })}\n`));
+        socket.on("data", (chunk) => {
+            buffer += chunk.toString();
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            socket.destroy();
+            try {
+                const response = JSON.parse(buffer.slice(0, newline));
+                if (response.ok === true && typeof response.code === "number") {
+                    resolve({
+                        code: response.code,
+                        stdout: typeof response.stdout === "string" ? response.stdout : "",
+                        stderr: typeof response.stderr === "string" ? response.stderr : "",
+                    });
+                    return;
+                }
+            }
+            catch {
+                // Fall through to the same undefined a refusal produces.
+            }
+            resolve(undefined);
+        });
+        socket.on("error", giveUp);
+    });
+}
+//# sourceMappingURL=command-client.js.map

package/dist/core/sandbox/rpc/command-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-client.js","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/command-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,kCAAkC,EAAE,MAAM,oBAAoB,CAAC;AAExE;;;;;;;;;GASG;AAEH,kFAAkF;AAClF,MAAM,gBAAgB,GAAsB;IAC3C,uGAAuG;IACvG,8FAA8F;IAC9F,iDAAiD;CACjD,CAAC;AAEF,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAsB;IACtE,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACrC,IAAI,SAAS,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAC1D,CAAC;IACD,OAAO,SAAS,CAAC;AAAA,CACjB;AAED,oGAAoG;AACpG,MAAM,UAAU,uBAAuB,CAAC,MAAc,EAAW;IAChE,OAAO,kEAAkE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAAA,CACvF;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB,EAAU;IAC9D,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC;AAAA,CAC5B;AAQD;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACvC,OAAkD,EAClD,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,EACnB;IACzC,IAAI,CAAC,UAAU;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACnD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC;YACpB,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO,CAAC,SAAS,CAAC,CAAC;QAAA,CACnB,CAAC;QACF,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3F,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,OAAO,GAAG,CAAC;gBAAE,OAAO;YACxB,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC;gBACJ,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAA4B,CAAC;gBACjF,IAAI,QAAQ,CAAC,EAAE,KAAK,IAAI,IAAI,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC/D,OAAO,CAAC;wBACP,IAAI,EAAE,QAAQ,CAAC,IAAI;wBACnB,MAAM,EAAE,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;wBAClE,MAAM,EAAE,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;qBAClE,CAAC,CAAC;oBACH,OAAO;gBACR,CAAC;YACF,CAAC;YAAC,MAAM,CAAC;gBACR,yDAAyD;YAC1D,CAAC;YACD,OAAO,CAAC,SAAS,CAAC,CAAC;QAAA,CACnB,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAAA,CAC3B,CAAC,CAAC;AAAA,CACH","sourcesContent":["import * as net from \"node:net\";\nimport { dirname, isAbsolute } from \"node:path\";\nimport { COMMAND_ESCALATION_SOCKET_VARIABLE } from \"./command-proxy.ts\";\n\n/**\n * The child's side of per-command escalation.\n *\n * The path this extracts is a guess, and it is allowed to be, because nothing safe rests\n * on it. The supervisor shows the human the exact command and the exact root before\n * anything runs, so a bad guess is refused by someone reading it rather than silently\n * granted. What the guess buys is not having to make the user work out which directory to\n * name; when it finds nothing, no escalation is offered and the command fails as it did\n * before.\n */\n\n/** The wordings the kernel and the shell actually produce for a mount refusal. */\nconst REFUSAL_PATTERNS: readonly RegExp[] = [\n\t/cannot (?:create|touch|remove|open) ['\"]?([^'\":]+)['\"]?: (?:Read-only file system|Permission denied)/i,\n\t/^[^:]*: ?([/][^\\s:]+): (?:Operation not permitted|Permission denied|Read-only file system)/im,\n\t/(?:EROFS|EACCES|EPERM)[^'\"]*['\"]([/][^'\"]+)['\"]/,\n];\n\n/** The absolute path a sandbox filesystem refusal named, if the output named one. */\nexport function extractRefusedPath(output: string): string | undefined {\n\tfor (const pattern of REFUSAL_PATTERNS) {\n\t\tconst match = pattern.exec(output);\n\t\tconst candidate = match?.[1]?.trim();\n\t\tif (candidate && isAbsolute(candidate)) return candidate;\n\t}\n\treturn undefined;\n}\n\n/** True when the output looks like the boundary refused a write rather than the command failing. */\nexport function looksLikeSandboxRefusal(output: string): boolean {\n\treturn /Read-only file system|Operation not permitted|Permission denied/i.test(output);\n}\n\n/**\n * The directory an escalation should make writable for a refused path.\n *\n * The parent, not the file: the command was creating something that does not exist, and a\n * bind of a non-existent path is not a mount bwrap can make.\n */\nexport function escalationRootFor(refusedPath: string): string {\n\treturn dirname(refusedPath);\n}\n\nexport interface EscalationOutcome {\n\treadonly code: number;\n\treadonly stdout: string;\n\treadonly stderr: string;\n}\n\n/**\n * Ask the supervisor to run one command with one extra writable root.\n *\n * Resolves undefined for every refusal and every failure alike, because the caller's\n * behaviour is identical in both cases: report the original error. Only a command that\n * actually ran returns anything.\n */\nexport function requestCommandEscalation(\n\trequest: { command: string; writableRoot: string },\n\tsocketPath = process.env[COMMAND_ESCALATION_SOCKET_VARIABLE],\n): Promise<EscalationOutcome | undefined> {\n\tif (!socketPath) return Promise.resolve(undefined);\n\treturn new Promise((resolve) => {\n\t\tconst socket = net.connect(socketPath);\n\t\tlet buffer = \"\";\n\t\tconst giveUp = () => {\n\t\t\tsocket.destroy();\n\t\t\tresolve(undefined);\n\t\t};\n\t\tsocket.on(\"connect\", () => socket.write(`${JSON.stringify({ op: \"run\", ...request })}\\n`));\n\t\tsocket.on(\"data\", (chunk) => {\n\t\t\tbuffer += chunk.toString();\n\t\t\tconst newline = buffer.indexOf(\"\\n\");\n\t\t\tif (newline < 0) return;\n\t\t\tsocket.destroy();\n\t\t\ttry {\n\t\t\t\tconst response = JSON.parse(buffer.slice(0, newline)) as Record<string, unknown>;\n\t\t\t\tif (response.ok === true && typeof response.code === \"number\") {\n\t\t\t\t\tresolve({\n\t\t\t\t\t\tcode: response.code,\n\t\t\t\t\t\tstdout: typeof response.stdout === \"string\" ? response.stdout : \"\",\n\t\t\t\t\t\tstderr: typeof response.stderr === \"string\" ? response.stderr : \"\",\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Fall through to the same undefined a refusal produces.\n\t\t\t}\n\t\t\tresolve(undefined);\n\t\t});\n\t\tsocket.on(\"error\", giveUp);\n\t});\n}\n"]}

package/dist/core/sandbox/rpc/command-proxy.d.ts

@@ -0,0 +1,48 @@
+import type { SandboxViolationStore } from "../violations.ts";
+/** Env var naming the child-side socket. */
+export declare const COMMAND_ESCALATION_SOCKET_VARIABLE = "APEX_COMMAND_ESCALATION_PATH";
+export interface CommandEscalationRequest {
+    readonly command: string;
+    /** The one directory the command needs writable that it does not already have. */
+    readonly writableRoot: string;
+}
+export interface CommandEscalationResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface CommandEscalationChannelPaths {
+    readonly hostSocketDirectory: string;
+    readonly hostSocketPath: string;
+    readonly childSocketPath: string;
+}
+export declare function resolveCommandEscalationChannelPaths(): CommandEscalationChannelPaths;
+/**
+ * Run one approved command in a second, differently-mounted child.
+ *
+ * A refused write is refused by the kernel inside a namespace whose mounts are fixed for
+ * its lifetime. There is no in-place equivalent of holding a CONNECT open while a human
+ * decides: the syscall has already failed, and nothing inside the namespace can widen it.
+ * So the escalation happens where the authority is, outside the boundary, by starting a
+ * separate child for that one command.
+ *
+ * The original child's namespace is never modified, which is what makes this sound rather
+ * than a hole. Approving one command grants nothing to the session it came from; the
+ * session's own next attempt at the same operation is refused exactly as before.
+ *
+ * Approval is the supervisor's, per ADR 0023, for the reason that ADR gives: this socket
+ * has no peer authentication, so a request arriving on it may have come from anything
+ * inside the boundary. Without an approver the channel refuses, which is what keeps
+ * headless, print, JSON, and RPC modes at ADR 0005's deny.
+ */
+export declare function createCommandEscalationProxy(options: {
+    socketPath: string;
+    /** Ask a human. Absent means refuse without asking. */
+    requestApproval?: (request: CommandEscalationRequest) => Promise<boolean>;
+    /** Start the second child. Supplied by the platform backend, which owns mount shape. */
+    runEscalated: (request: CommandEscalationRequest) => Promise<CommandEscalationResult>;
+    violationStore?: SandboxViolationStore;
+}): Promise<{
+    close(): Promise<void>;
+}>;
+//# sourceMappingURL=command-proxy.d.ts.map

package/dist/core/sandbox/rpc/command-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-proxy.d.ts","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/command-proxy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAO9D,4CAA4C;AAC5C,eAAO,MAAM,kCAAkC,iCAAiC,CAAC;AAEjF,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,6BAA6B;IAC7C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,oCAAoC,IAAI,6BAA6B,CAWpF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1E,wFAAwF;IACxF,YAAY,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACtF,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACvC,GAAG,OAAO,CAAC;IAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CA2EtC","sourcesContent":["import { chmodSync, existsSync, mkdtempSync, unlinkSync } from \"node:fs\";\nimport * as net from \"node:net\";\nimport { join } from \"node:path\";\nimport { supervisorTempDirectory } from \"../supervisor-temp.ts\";\nimport type { SandboxViolationStore } from \"../violations.ts\";\nimport { FrameReader, isRequestObject, writeFrame } from \"./framing.ts\";\n\n/** AF_UNIX `sun_path` is 108 bytes on Linux, including the terminating NUL. */\nconst SUN_PATH_LIMIT = 108;\nconst MAX_CONNECTIONS = 8;\n\n/** Env var naming the child-side socket. */\nexport const COMMAND_ESCALATION_SOCKET_VARIABLE = \"APEX_COMMAND_ESCALATION_PATH\";\n\nexport interface CommandEscalationRequest {\n\treadonly command: string;\n\t/** The one directory the command needs writable that it does not already have. */\n\treadonly writableRoot: string;\n}\n\nexport interface CommandEscalationResult {\n\treadonly code: number;\n\treadonly stdout: string;\n\treadonly stderr: string;\n}\n\nexport interface CommandEscalationChannelPaths {\n\treadonly hostSocketDirectory: string;\n\treadonly hostSocketPath: string;\n\treadonly childSocketPath: string;\n}\n\nexport function resolveCommandEscalationChannelPaths(): CommandEscalationChannelPaths {\n\tconst hostSocketDirectory = mkdtempSync(join(supervisorTempDirectory(), `apex-escalate-${process.pid}-`), {\n\t\tencoding: \"utf8\",\n\t});\n\tchmodSync(hostSocketDirectory, 0o700);\n\tconst hostSocketPath = join(hostSocketDirectory, \"channel.sock\");\n\tif (Buffer.byteLength(hostSocketPath) + 1 > SUN_PATH_LIMIT) {\n\t\tthrow new Error(\"Command escalation channel path exceeds the Unix socket path limit.\");\n\t}\n\tconst childSocketPath = process.platform === \"linux\" ? \"/home/apex-command-escalation.sock\" : hostSocketPath;\n\treturn { hostSocketDirectory, hostSocketPath, childSocketPath };\n}\n\n/**\n * Run one approved command in a second, differently-mounted child.\n *\n * A refused write is refused by the kernel inside a namespace whose mounts are fixed for\n * its lifetime. There is no in-place equivalent of holding a CONNECT open while a human\n * decides: the syscall has already failed, and nothing inside the namespace can widen it.\n * So the escalation happens where the authority is, outside the boundary, by starting a\n * separate child for that one command.\n *\n * The original child's namespace is never modified, which is what makes this sound rather\n * than a hole. Approving one command grants nothing to the session it came from; the\n * session's own next attempt at the same operation is refused exactly as before.\n *\n * Approval is the supervisor's, per ADR 0023, for the reason that ADR gives: this socket\n * has no peer authentication, so a request arriving on it may have come from anything\n * inside the boundary. Without an approver the channel refuses, which is what keeps\n * headless, print, JSON, and RPC modes at ADR 0005's deny.\n */\nexport function createCommandEscalationProxy(options: {\n\tsocketPath: string;\n\t/** Ask a human. Absent means refuse without asking. */\n\trequestApproval?: (request: CommandEscalationRequest) => Promise<boolean>;\n\t/** Start the second child. Supplied by the platform backend, which owns mount shape. */\n\trunEscalated: (request: CommandEscalationRequest) => Promise<CommandEscalationResult>;\n\tviolationStore?: SandboxViolationStore;\n}): Promise<{ close(): Promise<void> }> {\n\tfunction audit(detail: string, command: string): void {\n\t\toptions.violationStore?.add({ kind: \"filesystem\", command, detail, timestamp: new Date() });\n\t}\n\n\tasync function answer(request: unknown): Promise<object> {\n\t\tif (!isRequestObject(request)) return { ok: false, error: \"Malformed request.\" };\n\t\tif (request.op !== \"run\") return { ok: false, error: \"Only command escalation is served here.\" };\n\t\tconst command = typeof request.command === \"string\" ? request.command : \"\";\n\t\tconst writableRoot = typeof request.writableRoot === \"string\" ? request.writableRoot : \"\";\n\t\tif (!command || !writableRoot) return { ok: false, error: \"Request named no command or no root.\" };\n\n\t\t// Every request is asked about individually. There is no session-scoped grant here,\n\t\t// unlike a host or a credential: a command is not a stable subject to remember, and\n\t\t// remembering one would silently cover the next command that named the same root.\n\t\tif (!options.requestApproval) {\n\t\t\taudit(`Refused an escalation with no way to ask: ${command}`, command);\n\t\t\treturn { ok: false, error: \"Escalation is unavailable without a terminal.\" };\n\t\t}\n\t\tlet approved = false;\n\t\ttry {\n\t\t\tapproved = await options.requestApproval({ command, writableRoot });\n\t\t} catch {\n\t\t\tapproved = false;\n\t\t}\n\t\tif (!approved) {\n\t\t\taudit(`Escalation refused for ${writableRoot}`, command);\n\t\t\treturn { ok: false, error: \"Escalation was refused.\" };\n\t\t}\n\t\tconst result = await options.runEscalated({ command, writableRoot });\n\t\taudit(`Escalated with ${writableRoot} writable, exit ${result.code}`, command);\n\t\treturn { ok: true, code: result.code, stdout: result.stdout, stderr: result.stderr };\n\t}\n\n\treturn new Promise((resolve, reject) => {\n\t\tif (existsSync(options.socketPath)) unlinkSync(options.socketPath);\n\t\tconst sockets = new Set<net.Socket>();\n\t\tconst server = net.createServer((socket) => {\n\t\t\tif (sockets.size >= MAX_CONNECTIONS) {\n\t\t\t\tsocket.destroy();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsockets.add(socket);\n\t\t\tsocket.on(\"close\", () => sockets.delete(socket));\n\t\t\tsocket.on(\"error\", () => socket.destroy());\n\t\t\tconst reader = new FrameReader(socket, \"Command escalation channel\", (detail) =>\n\t\t\t\taudit(`Refused: ${detail}`, \"(protocol)\"),\n\t\t\t);\n\t\t\tvoid (async () => {\n\t\t\t\ttry {\n\t\t\t\t\twriteFrame(socket, await answer(await reader.next()));\n\t\t\t\t} catch {\n\t\t\t\t\t// A disconnected or malformed client is the reader's business.\n\t\t\t\t} finally {\n\t\t\t\t\tsocket.end();\n\t\t\t\t}\n\t\t\t})();\n\t\t});\n\t\tserver.on(\"error\", reject);\n\t\tserver.listen(options.socketPath, () => {\n\t\t\tserver.off(\"error\", reject);\n\t\t\ttry {\n\t\t\t\tchmodSync(options.socketPath, 0o600);\n\t\t\t} catch {\n\t\t\t\t// The containing directory is already 0700; this is defence in depth.\n\t\t\t}\n\t\t\tresolve({\n\t\t\t\tclose: () =>\n\t\t\t\t\tnew Promise((closed) => {\n\t\t\t\t\t\tfor (const socket of sockets) socket.destroy();\n\t\t\t\t\t\tserver.close(() => closed());\n\t\t\t\t\t}),\n\t\t\t});\n\t\t});\n\t});\n}\n"]}

package/dist/core/sandbox/rpc/command-proxy.js

@@ -0,0 +1,120 @@
+import { chmodSync, existsSync, mkdtempSync, unlinkSync } from "node:fs";
+import * as net from "node:net";
+import { join } from "node:path";
+import { supervisorTempDirectory } from "../supervisor-temp.js";
+import { FrameReader, isRequestObject, writeFrame } from "./framing.js";
+/** AF_UNIX `sun_path` is 108 bytes on Linux, including the terminating NUL. */
+const SUN_PATH_LIMIT = 108;
+const MAX_CONNECTIONS = 8;
+/** Env var naming the child-side socket. */
+export const COMMAND_ESCALATION_SOCKET_VARIABLE = "APEX_COMMAND_ESCALATION_PATH";
+export function resolveCommandEscalationChannelPaths() {
+    const hostSocketDirectory = mkdtempSync(join(supervisorTempDirectory(), `apex-escalate-${process.pid}-`), {
+        encoding: "utf8",
+    });
+    chmodSync(hostSocketDirectory, 0o700);
+    const hostSocketPath = join(hostSocketDirectory, "channel.sock");
+    if (Buffer.byteLength(hostSocketPath) + 1 > SUN_PATH_LIMIT) {
+        throw new Error("Command escalation channel path exceeds the Unix socket path limit.");
+    }
+    const childSocketPath = process.platform === "linux" ? "/home/apex-command-escalation.sock" : hostSocketPath;
+    return { hostSocketDirectory, hostSocketPath, childSocketPath };
+}
+/**
+ * Run one approved command in a second, differently-mounted child.
+ *
+ * A refused write is refused by the kernel inside a namespace whose mounts are fixed for
+ * its lifetime. There is no in-place equivalent of holding a CONNECT open while a human
+ * decides: the syscall has already failed, and nothing inside the namespace can widen it.
+ * So the escalation happens where the authority is, outside the boundary, by starting a
+ * separate child for that one command.
+ *
+ * The original child's namespace is never modified, which is what makes this sound rather
+ * than a hole. Approving one command grants nothing to the session it came from; the
+ * session's own next attempt at the same operation is refused exactly as before.
+ *
+ * Approval is the supervisor's, per ADR 0023, for the reason that ADR gives: this socket
+ * has no peer authentication, so a request arriving on it may have come from anything
+ * inside the boundary. Without an approver the channel refuses, which is what keeps
+ * headless, print, JSON, and RPC modes at ADR 0005's deny.
+ */
+export function createCommandEscalationProxy(options) {
+    function audit(detail, command) {
+        options.violationStore?.add({ kind: "filesystem", command, detail, timestamp: new Date() });
+    }
+    async function answer(request) {
+        if (!isRequestObject(request))
+            return { ok: false, error: "Malformed request." };
+        if (request.op !== "run")
+            return { ok: false, error: "Only command escalation is served here." };
+        const command = typeof request.command === "string" ? request.command : "";
+        const writableRoot = typeof request.writableRoot === "string" ? request.writableRoot : "";
+        if (!command || !writableRoot)
+            return { ok: false, error: "Request named no command or no root." };
+        // Every request is asked about individually. There is no session-scoped grant here,
+        // unlike a host or a credential: a command is not a stable subject to remember, and
+        // remembering one would silently cover the next command that named the same root.
+        if (!options.requestApproval) {
+            audit(`Refused an escalation with no way to ask: ${command}`, command);
+            return { ok: false, error: "Escalation is unavailable without a terminal." };
+        }
+        let approved = false;
+        try {
+            approved = await options.requestApproval({ command, writableRoot });
+        }
+        catch {
+            approved = false;
+        }
+        if (!approved) {
+            audit(`Escalation refused for ${writableRoot}`, command);
+            return { ok: false, error: "Escalation was refused." };
+        }
+        const result = await options.runEscalated({ command, writableRoot });
+        audit(`Escalated with ${writableRoot} writable, exit ${result.code}`, command);
+        return { ok: true, code: result.code, stdout: result.stdout, stderr: result.stderr };
+    }
+    return new Promise((resolve, reject) => {
+        if (existsSync(options.socketPath))
+            unlinkSync(options.socketPath);
+        const sockets = new Set();
+        const server = net.createServer((socket) => {
+            if (sockets.size >= MAX_CONNECTIONS) {
+                socket.destroy();
+                return;
+            }
+            sockets.add(socket);
+            socket.on("close", () => sockets.delete(socket));
+            socket.on("error", () => socket.destroy());
+            const reader = new FrameReader(socket, "Command escalation channel", (detail) => audit(`Refused: ${detail}`, "(protocol)"));
+            void (async () => {
+                try {
+                    writeFrame(socket, await answer(await reader.next()));
+                }
+                catch {
+                    // A disconnected or malformed client is the reader's business.
+                }
+                finally {
+                    socket.end();
+                }
+            })();
+        });
+        server.on("error", reject);
+        server.listen(options.socketPath, () => {
+            server.off("error", reject);
+            try {
+                chmodSync(options.socketPath, 0o600);
+            }
+            catch {
+                // The containing directory is already 0700; this is defence in depth.
+            }
+            resolve({
+                close: () => new Promise((closed) => {
+                    for (const socket of sockets)
+                        socket.destroy();
+                    server.close(() => closed());
+                }),
+            });
+        });
+    });
+}
+//# sourceMappingURL=command-proxy.js.map