apex-code 0.0.1-alpha.0 → 0.0.1-alpha.10

package/dist/core/sandbox/rpc/git-credential-proxy.js

@@ -0,0 +1,142 @@
+import { chmodSync, existsSync, unlinkSync } from "node:fs";
+import * as net from "node:net";
+import { FrameReader, isRequestObject, writeFrame } from "./framing.js";
+const MAX_CONNECTIONS = 32;
+/**
+ * Serve git credentials to the sandboxed child without ever putting one inside it.
+ *
+ * ADR 0015 keeps credentials host-owned and hands the child a read-only projection. A git
+ * credential cannot be projected the same way: it is not one file with a stable shape, it
+ * is whatever the host's own helper produces per host. So the credential stays on the host
+ * and only the answer to one question crosses, for one host, once it has been released.
+ *
+ * Two gates, and the first is the one that matters most.
+ *
+ * The host must be reachable by this session. git only asks for a credential after a
+ * server challenged it, so in the ordinary flow the host was already allowed or approved
+ * at the network layer. A request for a host the session cannot reach is therefore not git
+ * doing its job; it is something that went looking for a token. Refusing it costs nothing
+ * real and removes the case where this channel is more useful to an attacker than to git.
+ *
+ * The human must release it. Per ADR 0023 that decision is the supervisor's, because this
+ * socket has no peer authentication -- every descendant in the child's namespace can reach
+ * it, which is precisely the code the boundary exists to contain. Without a releaser the
+ * channel refuses outright, so a headless session cannot hand out a credential at all.
+ *
+ * A release covers one host for the session. It is never persisted and never widened to a
+ * second host, which is what keeps an approval for a push from also releasing a token to
+ * whatever else the session later contacts.
+ */
+export function createGitCredentialProxy(options) {
+    /** Hosts released this session. Never persisted, never widened. */
+    const released = new Set();
+    const pending = new Map();
+    function audit(host, detail) {
+        options.violationStore?.add({
+            kind: "network",
+            command: `git credential ${host}`,
+            detail,
+            timestamp: new Date(),
+        });
+    }
+    async function release(host) {
+        if (released.has(host))
+            return true;
+        if (!options.requestRelease)
+            return false;
+        const inFlight = pending.get(host);
+        if (inFlight)
+            return inFlight;
+        const question = (async () => {
+            try {
+                const approved = await options.requestRelease(host);
+                if (approved)
+                    released.add(host);
+                return approved;
+            }
+            catch {
+                return false;
+            }
+            finally {
+                pending.delete(host);
+            }
+        })();
+        pending.set(host, question);
+        return question;
+    }
+    async function answer(request) {
+        if (!isRequestObject(request))
+            return { ok: false, error: "Malformed request." };
+        if (request.op !== "get") {
+            // Only `get` crosses. `store` and `erase` would let the child rewrite the host's
+            // credential store, which ADR 0015 keeps as an explicit host operation.
+            return { ok: false, error: "Only credential reads are served over this channel." };
+        }
+        const host = typeof request.host === "string" ? request.host : "";
+        const protocol = typeof request.protocol === "string" ? request.protocol : "https";
+        if (!host)
+            return { ok: false, error: "Request named no host." };
+        if (!options.isHostAllowed(host)) {
+            audit(host, `Refused a credential for ${host}, which this session may not reach.`);
+            return { ok: false, error: "Host is not reachable by this session." };
+        }
+        if (!(await release(host))) {
+            audit(host, `Credential for ${host} was not released.`);
+            return { ok: false, error: "Credential was not released." };
+        }
+        const credential = await options.fillCredential({ host, protocol });
+        if (!credential) {
+            audit(host, `The host credential store had nothing for ${host}.`);
+            return { ok: false, error: "No credential is configured for that host." };
+        }
+        return { ok: true, username: credential.username, password: credential.password };
+    }
+    return new Promise((resolve, reject) => {
+        // A prior launch that never closed leaves a stale socket file that listen() refuses
+        // to bind over, exactly as the network proxy handles.
+        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, "Git credential channel", (detail) => audit("(protocol)", `Refused: ${detail}`));
+            void (async () => {
+                try {
+                    const response = await answer(await reader.next());
+                    writeFrame(socket, response);
+                }
+                catch {
+                    // A disconnected or malformed client is the reader's business; there is
+                    // nothing to answer and nothing to record beyond what it already did.
+                }
+                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; the mode here is defence in depth.
+            }
+            resolve({
+                close: () => new Promise((closed) => {
+                    for (const socket of sockets)
+                        socket.destroy();
+                    server.close(() => closed());
+                }),
+            });
+        });
+    });
+}
+//# sourceMappingURL=git-credential-proxy.js.map

package/dist/core/sandbox/rpc/git-credential-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-credential-proxy.js","sourceRoot":"","sources":["../../../../src/core/sandbox/rpc/git-credential-proxy.ts"],"names":[],"mappings":"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","sourcesContent":["import { chmodSync, existsSync, unlinkSync } from \"node:fs\";\nimport * as net from \"node:net\";\nimport type { SandboxViolationStore } from \"../violations.ts\";\nimport { FrameReader, isRequestObject, writeFrame } from \"./framing.ts\";\n\nconst MAX_CONNECTIONS = 32;\n\nexport interface GitCredentialRequest {\n\treadonly protocol: string;\n\treadonly host: string;\n}\n\nexport interface GitCredential {\n\treadonly username: string;\n\treadonly password: string;\n}\n\nexport interface GitCredentialProxy {\n\tclose(): Promise<void>;\n}\n\n/**\n * Serve git credentials to the sandboxed child without ever putting one inside it.\n *\n * ADR 0015 keeps credentials host-owned and hands the child a read-only projection. A git\n * credential cannot be projected the same way: it is not one file with a stable shape, it\n * is whatever the host's own helper produces per host. So the credential stays on the host\n * and only the answer to one question crosses, for one host, once it has been released.\n *\n * Two gates, and the first is the one that matters most.\n *\n * The host must be reachable by this session. git only asks for a credential after a\n * server challenged it, so in the ordinary flow the host was already allowed or approved\n * at the network layer. A request for a host the session cannot reach is therefore not git\n * doing its job; it is something that went looking for a token. Refusing it costs nothing\n * real and removes the case where this channel is more useful to an attacker than to git.\n *\n * The human must release it. Per ADR 0023 that decision is the supervisor's, because this\n * socket has no peer authentication -- every descendant in the child's namespace can reach\n * it, which is precisely the code the boundary exists to contain. Without a releaser the\n * channel refuses outright, so a headless session cannot hand out a credential at all.\n *\n * A release covers one host for the session. It is never persisted and never widened to a\n * second host, which is what keeps an approval for a push from also releasing a token to\n * whatever else the session later contacts.\n */\nexport function createGitCredentialProxy(options: {\n\tsocketPath: string;\n\t/** Whether this session may reach the host at all. */\n\tisHostAllowed: (host: string) => boolean;\n\t/** Ask a human to release the host's credential. Absent means refuse without asking. */\n\trequestRelease?: (host: string) => Promise<boolean>;\n\t/** Resolve the credential on the host, using the host's own configuration. */\n\tfillCredential: (request: GitCredentialRequest) => Promise<GitCredential | undefined>;\n\tviolationStore?: SandboxViolationStore;\n}): Promise<GitCredentialProxy> {\n\t/** Hosts released this session. Never persisted, never widened. */\n\tconst released = new Set<string>();\n\tconst pending = new Map<string, Promise<boolean>>();\n\n\tfunction audit(host: string, detail: string): void {\n\t\toptions.violationStore?.add({\n\t\t\tkind: \"network\",\n\t\t\tcommand: `git credential ${host}`,\n\t\t\tdetail,\n\t\t\ttimestamp: new Date(),\n\t\t});\n\t}\n\n\tasync function release(host: string): Promise<boolean> {\n\t\tif (released.has(host)) return true;\n\t\tif (!options.requestRelease) return false;\n\t\tconst inFlight = pending.get(host);\n\t\tif (inFlight) return inFlight;\n\t\tconst question = (async () => {\n\t\t\ttry {\n\t\t\t\tconst approved = await (options.requestRelease as (h: string) => Promise<boolean>)(host);\n\t\t\t\tif (approved) released.add(host);\n\t\t\t\treturn approved;\n\t\t\t} catch {\n\t\t\t\treturn false;\n\t\t\t} finally {\n\t\t\t\tpending.delete(host);\n\t\t\t}\n\t\t})();\n\t\tpending.set(host, question);\n\t\treturn question;\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 !== \"get\") {\n\t\t\t// Only `get` crosses. `store` and `erase` would let the child rewrite the host's\n\t\t\t// credential store, which ADR 0015 keeps as an explicit host operation.\n\t\t\treturn { ok: false, error: \"Only credential reads are served over this channel.\" };\n\t\t}\n\t\tconst host = typeof request.host === \"string\" ? request.host : \"\";\n\t\tconst protocol = typeof request.protocol === \"string\" ? request.protocol : \"https\";\n\t\tif (!host) return { ok: false, error: \"Request named no host.\" };\n\n\t\tif (!options.isHostAllowed(host)) {\n\t\t\taudit(host, `Refused a credential for ${host}, which this session may not reach.`);\n\t\t\treturn { ok: false, error: \"Host is not reachable by this session.\" };\n\t\t}\n\t\tif (!(await release(host))) {\n\t\t\taudit(host, `Credential for ${host} was not released.`);\n\t\t\treturn { ok: false, error: \"Credential was not released.\" };\n\t\t}\n\t\tconst credential = await options.fillCredential({ host, protocol });\n\t\tif (!credential) {\n\t\t\taudit(host, `The host credential store had nothing for ${host}.`);\n\t\t\treturn { ok: false, error: \"No credential is configured for that host.\" };\n\t\t}\n\t\treturn { ok: true, username: credential.username, password: credential.password };\n\t}\n\n\treturn new Promise((resolve, reject) => {\n\t\t// A prior launch that never closed leaves a stale socket file that listen() refuses\n\t\t// to bind over, exactly as the network proxy handles.\n\t\tif (existsSync(options.socketPath)) unlinkSync(options.socketPath);\n\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, \"Git credential channel\", (detail) =>\n\t\t\t\taudit(\"(protocol)\", `Refused: ${detail}`),\n\t\t\t);\n\t\t\tvoid (async () => {\n\t\t\t\ttry {\n\t\t\t\t\tconst response = await answer(await reader.next());\n\t\t\t\t\twriteFrame(socket, response);\n\t\t\t\t} catch {\n\t\t\t\t\t// A disconnected or malformed client is the reader's business; there is\n\t\t\t\t\t// nothing to answer and nothing to record beyond what it already did.\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\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; the mode here 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/supervisor-temp.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The directory the supervisor puts its own private state in.
+ *
+ * `/tmp` on POSIX rather than `TMPDIR`, deliberately, for two reasons the channel code
+ * depends on. `TMPDIR` can point inside the workspace on macOS, which the sandbox may
+ * write, and a socket has to fit inside `AF_UNIX`'s 108-byte `sun_path`, which an
+ * unusually long `TMPDIR` exhausts.
+ *
+ * Windows has neither `/tmp` nor Unix sockets. Nothing here is reachable in a Windows
+ * session, because ADR 0005 leaves that platform unsupported and both backends report
+ * `unavailable` before a launch gets this far. It still has to resolve to something real:
+ * these helpers are called before the backend's platform check in one path, and off-platform
+ * in the tests that exercise violation attribution without a macOS host. Returning
+ * `os.tmpdir()` there turns a confusing `ENOENT: mkdtemp '/tmp/...'` into the accurate
+ * "OS sandbox is supported on macOS only."
+ */
+export declare function supervisorTempDirectory(): string;
+//# sourceMappingURL=supervisor-temp.d.ts.map

package/dist/core/sandbox/supervisor-temp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-temp.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor-temp.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD","sourcesContent":["import { tmpdir } from \"node:os\";\n\n/**\n * The directory the supervisor puts its own private state in.\n *\n * `/tmp` on POSIX rather than `TMPDIR`, deliberately, for two reasons the channel code\n * depends on. `TMPDIR` can point inside the workspace on macOS, which the sandbox may\n * write, and a socket has to fit inside `AF_UNIX`'s 108-byte `sun_path`, which an\n * unusually long `TMPDIR` exhausts.\n *\n * Windows has neither `/tmp` nor Unix sockets. Nothing here is reachable in a Windows\n * session, because ADR 0005 leaves that platform unsupported and both backends report\n * `unavailable` before a launch gets this far. It still has to resolve to something real:\n * these helpers are called before the backend's platform check in one path, and off-platform\n * in the tests that exercise violation attribution without a macOS host. Returning\n * `os.tmpdir()` there turns a confusing `ENOENT: mkdtemp '/tmp/...'` into the accurate\n * \"OS sandbox is supported on macOS only.\"\n */\nexport function supervisorTempDirectory(): string {\n\treturn process.platform === \"win32\" ? tmpdir() : \"/tmp\";\n}\n"]}

package/dist/core/sandbox/supervisor-temp.js

@@ -0,0 +1,21 @@
+import { tmpdir } from "node:os";
+/**
+ * The directory the supervisor puts its own private state in.
+ *
+ * `/tmp` on POSIX rather than `TMPDIR`, deliberately, for two reasons the channel code
+ * depends on. `TMPDIR` can point inside the workspace on macOS, which the sandbox may
+ * write, and a socket has to fit inside `AF_UNIX`'s 108-byte `sun_path`, which an
+ * unusually long `TMPDIR` exhausts.
+ *
+ * Windows has neither `/tmp` nor Unix sockets. Nothing here is reachable in a Windows
+ * session, because ADR 0005 leaves that platform unsupported and both backends report
+ * `unavailable` before a launch gets this far. It still has to resolve to something real:
+ * these helpers are called before the backend's platform check in one path, and off-platform
+ * in the tests that exercise violation attribution without a macOS host. Returning
+ * `os.tmpdir()` there turns a confusing `ENOENT: mkdtemp '/tmp/...'` into the accurate
+ * "OS sandbox is supported on macOS only."
+ */
+export function supervisorTempDirectory() {
+    return process.platform === "win32" ? tmpdir() : "/tmp";
+}
+//# sourceMappingURL=supervisor-temp.js.map

package/dist/core/sandbox/supervisor-temp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-temp.js","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor-temp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,GAAW;IACjD,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAAA,CACxD","sourcesContent":["import { tmpdir } from \"node:os\";\n\n/**\n * The directory the supervisor puts its own private state in.\n *\n * `/tmp` on POSIX rather than `TMPDIR`, deliberately, for two reasons the channel code\n * depends on. `TMPDIR` can point inside the workspace on macOS, which the sandbox may\n * write, and a socket has to fit inside `AF_UNIX`'s 108-byte `sun_path`, which an\n * unusually long `TMPDIR` exhausts.\n *\n * Windows has neither `/tmp` nor Unix sockets. Nothing here is reachable in a Windows\n * session, because ADR 0005 leaves that platform unsupported and both backends report\n * `unavailable` before a launch gets this far. It still has to resolve to something real:\n * these helpers are called before the backend's platform check in one path, and off-platform\n * in the tests that exercise violation attribution without a macOS host. Returning\n * `os.tmpdir()` there turns a confusing `ENOENT: mkdtemp '/tmp/...'` into the accurate\n * \"OS sandbox is supported on macOS only.\"\n */\nexport function supervisorTempDirectory(): string {\n\treturn process.platform === \"win32\" ? tmpdir() : \"/tmp\";\n}\n"]}

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

@@ -0,0 +1,51 @@
+import { type SandboxPolicy, type SandboxStatus } from "./policy.ts";
+export interface SandboxLaunch {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly policy: SandboxPolicy;
+    readonly environment?: NodeJS.ProcessEnv;
+    /** Application/runtime directories needed by the child but never writable by it. */
+    readonly readOnlyPaths?: readonly string[];
+    /** Individual read-only files, such as a host-owned credential file. */
+    readonly readOnlyFiles?: readonly string[];
+    /**
+     * Host executables projected read-only at an exact path inside the child. The
+     * destination is chosen by the caller because only it knows where the child will
+     * look; the backend just places the file there without write access.
+     */
+    readonly readOnlyBinaries?: readonly {
+        readonly source: string;
+        readonly destination: string;
+    }[];
+    /**
+     * The supervisor-owned credential write channel, when one was opened for this
+     * launch. `hostSocketPath` is where the supervisor's writer listens; the backend
+     * projects it to `childSocketPath`, which is also what the child is told through
+     * `APEX_CREDENTIAL_PROXY_PATH`. Absent means the session has no credential write
+     * path at all -- the mount stays read-only with no exception.
+     */
+    readonly credentialChannel?: {
+        readonly hostSocketPath: string;
+        readonly childSocketPath: string;
+    };
+}
+/** A platform adapter. Its sole job is to launch a normal Apex child inside an OS boundary. */
+export interface SandboxBackend {
+    readonly status: SandboxStatus;
+    launch(launch: SandboxLaunch): Promise<number>;
+    close(): Promise<void>;
+}
+export interface SandboxSupervisor {
+    readonly status: SandboxStatus;
+    launch(options: Omit<SandboxLaunch, "policy">): Promise<number>;
+    close(): Promise<void>;
+}
+/**
+ * Owns fail-closed policy propagation and lifecycle; OS details remain behind the
+ * backend so all testable security semantics are Apex-owned.
+ */
+export declare function createSandboxSupervisor(options: {
+    backend: SandboxBackend;
+    policy: SandboxPolicy;
+}): SandboxSupervisor;
+//# sourceMappingURL=supervisor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhG,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjG;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE;QAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;KACjC,CAAC;CACF;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAChD,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;CACtB,GAAG,iBAAiB,CAWpB","sourcesContent":["import { requireSandboxEnforcement, type SandboxPolicy, type SandboxStatus } from \"./policy.ts\";\n\nexport interface SandboxLaunch {\n\treadonly command: string;\n\treadonly args: readonly string[];\n\treadonly policy: SandboxPolicy;\n\treadonly environment?: NodeJS.ProcessEnv;\n\t/** Application/runtime directories needed by the child but never writable by it. */\n\treadonly readOnlyPaths?: readonly string[];\n\t/** Individual read-only files, such as a host-owned credential file. */\n\treadonly readOnlyFiles?: readonly string[];\n\t/**\n\t * Host executables projected read-only at an exact path inside the child. The\n\t * destination is chosen by the caller because only it knows where the child will\n\t * look; the backend just places the file there without write access.\n\t */\n\treadonly readOnlyBinaries?: readonly { readonly source: string; readonly destination: string }[];\n\t/**\n\t * The supervisor-owned credential write channel, when one was opened for this\n\t * launch. `hostSocketPath` is where the supervisor's writer listens; the backend\n\t * projects it to `childSocketPath`, which is also what the child is told through\n\t * `APEX_CREDENTIAL_PROXY_PATH`. Absent means the session has no credential write\n\t * path at all -- the mount stays read-only with no exception.\n\t */\n\treadonly credentialChannel?: {\n\t\treadonly hostSocketPath: string;\n\t\treadonly childSocketPath: string;\n\t};\n}\n\n/** A platform adapter. Its sole job is to launch a normal Apex child inside an OS boundary. */\nexport interface SandboxBackend {\n\treadonly status: SandboxStatus;\n\tlaunch(launch: SandboxLaunch): Promise<number>;\n\tclose(): Promise<void>;\n}\n\nexport interface SandboxSupervisor {\n\treadonly status: SandboxStatus;\n\tlaunch(options: Omit<SandboxLaunch, \"policy\">): Promise<number>;\n\tclose(): Promise<void>;\n}\n\n/**\n * Owns fail-closed policy propagation and lifecycle; OS details remain behind the\n * backend so all testable security semantics are Apex-owned.\n */\nexport function createSandboxSupervisor(options: {\n\tbackend: SandboxBackend;\n\tpolicy: SandboxPolicy;\n}): SandboxSupervisor {\n\treturn {\n\t\tstatus: options.backend.status,\n\t\tasync launch(launch) {\n\t\t\trequireSandboxEnforcement(options.backend.status);\n\t\t\treturn options.backend.launch({ ...launch, policy: options.policy });\n\t\t},\n\t\tasync close() {\n\t\t\tawait options.backend.close();\n\t\t},\n\t};\n}\n"]}

package/dist/core/sandbox/supervisor.js

@@ -0,0 +1,18 @@
+import { requireSandboxEnforcement } from "./policy.js";
+/**
+ * Owns fail-closed policy propagation and lifecycle; OS details remain behind the
+ * backend so all testable security semantics are Apex-owned.
+ */
+export function createSandboxSupervisor(options) {
+    return {
+        status: options.backend.status,
+        async launch(launch) {
+            requireSandboxEnforcement(options.backend.status);
+            return options.backend.launch({ ...launch, policy: options.policy });
+        },
+        async close() {
+            await options.backend.close();
+        },
+    };
+}
+//# sourceMappingURL=supervisor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAA0C,MAAM,aAAa,CAAC;AA2ChG;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAGvC,EAAqB;IACrB,OAAO;QACN,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM;QAC9B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;YACpB,yBAAyB,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAClD,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAAA,CACrE;QACD,KAAK,CAAC,KAAK,GAAG;YACb,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAAA,CAC9B;KACD,CAAC;AAAA,CACF","sourcesContent":["import { requireSandboxEnforcement, type SandboxPolicy, type SandboxStatus } from \"./policy.ts\";\n\nexport interface SandboxLaunch {\n\treadonly command: string;\n\treadonly args: readonly string[];\n\treadonly policy: SandboxPolicy;\n\treadonly environment?: NodeJS.ProcessEnv;\n\t/** Application/runtime directories needed by the child but never writable by it. */\n\treadonly readOnlyPaths?: readonly string[];\n\t/** Individual read-only files, such as a host-owned credential file. */\n\treadonly readOnlyFiles?: readonly string[];\n\t/**\n\t * Host executables projected read-only at an exact path inside the child. The\n\t * destination is chosen by the caller because only it knows where the child will\n\t * look; the backend just places the file there without write access.\n\t */\n\treadonly readOnlyBinaries?: readonly { readonly source: string; readonly destination: string }[];\n\t/**\n\t * The supervisor-owned credential write channel, when one was opened for this\n\t * launch. `hostSocketPath` is where the supervisor's writer listens; the backend\n\t * projects it to `childSocketPath`, which is also what the child is told through\n\t * `APEX_CREDENTIAL_PROXY_PATH`. Absent means the session has no credential write\n\t * path at all -- the mount stays read-only with no exception.\n\t */\n\treadonly credentialChannel?: {\n\t\treadonly hostSocketPath: string;\n\t\treadonly childSocketPath: string;\n\t};\n}\n\n/** A platform adapter. Its sole job is to launch a normal Apex child inside an OS boundary. */\nexport interface SandboxBackend {\n\treadonly status: SandboxStatus;\n\tlaunch(launch: SandboxLaunch): Promise<number>;\n\tclose(): Promise<void>;\n}\n\nexport interface SandboxSupervisor {\n\treadonly status: SandboxStatus;\n\tlaunch(options: Omit<SandboxLaunch, \"policy\">): Promise<number>;\n\tclose(): Promise<void>;\n}\n\n/**\n * Owns fail-closed policy propagation and lifecycle; OS details remain behind the\n * backend so all testable security semantics are Apex-owned.\n */\nexport function createSandboxSupervisor(options: {\n\tbackend: SandboxBackend;\n\tpolicy: SandboxPolicy;\n}): SandboxSupervisor {\n\treturn {\n\t\tstatus: options.backend.status,\n\t\tasync launch(launch) {\n\t\t\trequireSandboxEnforcement(options.backend.status);\n\t\t\treturn options.backend.launch({ ...launch, policy: options.policy });\n\t\t},\n\t\tasync close() {\n\t\t\tawait options.backend.close();\n\t\t},\n\t};\n}\n"]}

package/dist/core/sandbox/terminal-handoff.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Lends the terminal from the sandboxed child back to the supervisor for a prompt.
+ *
+ * The supervisor has to draw the escalation prompt itself. Per ADR 0023 an approval
+ * asserted from inside the boundary is indistinguishable from one forged by the code the
+ * boundary exists to contain, so the human's answer must be read by the side that owns the
+ * decision. The child cannot read it in any case: it runs under `bwrap --new-session` and
+ * has no controlling terminal, which `terminal-size.ts` documents for the same reason.
+ *
+ * The transport is the one `terminal-size.ts` already established -- a file in the
+ * workspace, which is bind-mounted into the child, watched on the other side. Signals are
+ * unavailable because bwrap sits between the processes as PID 1 and forwards nothing.
+ *
+ * Two files rather than one, because the supervisor must know the child has actually let
+ * go of stdin before it reads an answer. The child inherits stdin and its TUI holds it in
+ * raw mode; prompting while both sides read would lose keystrokes to whichever won.
+ *
+ * The child is asked, never obeyed. A child that never acknowledges delays the prompt by
+ * the timeout and no longer, because a contained process that could withhold
+ * acknowledgement indefinitely would be able to veto the human's decision -- which is the
+ * authority failure ADR 0023 forbids. An unread prompt is a legibility failure, and that
+ * is the direction this is allowed to fail in.
+ */
+/** Env var naming the directory both sides agree on. */
+export declare const TERMINAL_HANDOFF_PATH_VARIABLE = "APEX_TERMINAL_HANDOFF_PATH";
+export interface TerminalHandoff {
+    /**
+     * Suspend the child, run `prompt` with the terminal to itself, then resume the child.
+     * Overlapping calls are serialised, so two prompts never share the terminal.
+     */
+    borrowTerminal<T>(prompt: () => Promise<T>): Promise<T>;
+    stop(): void;
+}
+/** Supervisor side. */
+export declare function createTerminalHandoff(directory: string, options?: {
+    acknowledgementTimeoutMs?: number;
+}): TerminalHandoff;
+/** Child side. Acknowledges a suspend once it has actually stopped drawing and reading. */
+export declare function observeTerminalHandoff(directory: string, hooks: {
+    suspend: () => void | Promise<void>;
+    resume: () => void | Promise<void>;
+}): {
+    stop: () => void;
+};
+//# sourceMappingURL=terminal-handoff.d.ts.map

package/dist/core/sandbox/terminal-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-handoff.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/terminal-handoff.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wDAAwD;AACxD,eAAO,MAAM,8BAA8B,+BAA+B,CAAC;AAwB3E,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxD,IAAI,IAAI,IAAI,CAAC;CACb;AAED,uBAAuB;AACvB,wBAAgB,qBAAqB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IAAE,wBAAwB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,eAAe,CAgFjB;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAChF;IAAE,IAAI,EAAE,MAAM,IAAI,CAAA;CAAE,CAgDtB","sourcesContent":["import { type FSWatcher, readFileSync, rmSync, watch, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\n/**\n * Lends the terminal from the sandboxed child back to the supervisor for a prompt.\n *\n * The supervisor has to draw the escalation prompt itself. Per ADR 0023 an approval\n * asserted from inside the boundary is indistinguishable from one forged by the code the\n * boundary exists to contain, so the human's answer must be read by the side that owns the\n * decision. The child cannot read it in any case: it runs under `bwrap --new-session` and\n * has no controlling terminal, which `terminal-size.ts` documents for the same reason.\n *\n * The transport is the one `terminal-size.ts` already established -- a file in the\n * workspace, which is bind-mounted into the child, watched on the other side. Signals are\n * unavailable because bwrap sits between the processes as PID 1 and forwards nothing.\n *\n * Two files rather than one, because the supervisor must know the child has actually let\n * go of stdin before it reads an answer. The child inherits stdin and its TUI holds it in\n * raw mode; prompting while both sides read would lose keystrokes to whichever won.\n *\n * The child is asked, never obeyed. A child that never acknowledges delays the prompt by\n * the timeout and no longer, because a contained process that could withhold\n * acknowledgement indefinitely would be able to veto the human's decision -- which is the\n * authority failure ADR 0023 forbids. An unread prompt is a legibility failure, and that\n * is the direction this is allowed to fail in.\n */\n\n/** Env var naming the directory both sides agree on. */\nexport const TERMINAL_HANDOFF_PATH_VARIABLE = \"APEX_TERMINAL_HANDOFF_PATH\";\n\nconst STATE_FILE = \"terminal-handoff\";\nconst ACKNOWLEDGEMENT_FILE = \"terminal-handoff-ack\";\nconst DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS = 1_000;\n\n/**\n * How often each side re-reads the state file, independently of the watcher.\n *\n * `fs.watch` is a thin wrapper over whatever the platform provides, and the platforms do\n * not agree. macOS CI delivered a resume more than a second after it was written, and\n * intermittently: the event arrives, late enough that a TUI would sit visibly frozen\n * after the human had already answered. The watcher still does the work in the common\n * case; this only bounds how wrong it can be.\n */\nconst POLL_INTERVAL_MS = 100;\n\ntype HandoffState = \"suspend\" | \"resume\";\n\nfunction parseState(contents: string): HandoffState | undefined {\n\tconst value = contents.trim();\n\treturn value === \"suspend\" || value === \"resume\" ? value : undefined;\n}\n\nexport interface TerminalHandoff {\n\t/**\n\t * Suspend the child, run `prompt` with the terminal to itself, then resume the child.\n\t * Overlapping calls are serialised, so two prompts never share the terminal.\n\t */\n\tborrowTerminal<T>(prompt: () => Promise<T>): Promise<T>;\n\tstop(): void;\n}\n\n/** Supervisor side. */\nexport function createTerminalHandoff(\n\tdirectory: string,\n\toptions?: { acknowledgementTimeoutMs?: number },\n): TerminalHandoff {\n\tconst statePath = join(directory, STATE_FILE);\n\tconst acknowledgementPath = join(directory, ACKNOWLEDGEMENT_FILE);\n\tconst timeout = options?.acknowledgementTimeoutMs ?? DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS;\n\t// Every borrow chains onto the last, which is what keeps two escalations that arrive\n\t// together from drawing over each other.\n\tlet queue: Promise<unknown> = Promise.resolve();\n\n\tfunction write(state: HandoffState): void {\n\t\ttry {\n\t\t\twriteFileSync(statePath, `${state}\\n`);\n\t\t} catch {\n\t\t\t// A handoff we cannot request still leaves the prompt readable often enough to\n\t\t\t// be worth attempting; it is never worth failing the escalation over.\n\t\t}\n\t}\n\n\tfunction waitForAcknowledgement(): Promise<void> {\n\t\treturn new Promise((resolve) => {\n\t\t\tlet watcher: FSWatcher | undefined;\n\t\t\tlet timer: NodeJS.Timeout | undefined;\n\t\t\tlet poll: NodeJS.Timeout | undefined;\n\t\t\tconst finish = () => {\n\t\t\t\tif (timer) clearTimeout(timer);\n\t\t\t\tif (poll) clearInterval(poll);\n\t\t\t\twatcher?.close();\n\t\t\t\tresolve();\n\t\t\t};\n\t\t\tconst check = () => {\n\t\t\t\ttry {\n\t\t\t\t\tif (readFileSync(acknowledgementPath, \"utf8\").trim() === \"suspended\") finish();\n\t\t\t\t} catch {\n\t\t\t\t\t// Not written yet.\n\t\t\t\t}\n\t\t\t};\n\t\t\ttimer = setTimeout(finish, timeout);\n\t\t\ttry {\n\t\t\t\twatcher = watch(directory, check);\n\t\t\t} catch {\n\t\t\t\t// Without a watcher the poll below still delivers, just less promptly.\n\t\t\t}\n\t\t\tpoll = setInterval(check, POLL_INTERVAL_MS);\n\t\t\tpoll.unref();\n\t\t\tcheck();\n\t\t});\n\t}\n\n\tasync function run<T>(prompt: () => Promise<T>): Promise<T> {\n\t\ttry {\n\t\t\trmSync(acknowledgementPath, { force: true });\n\t\t} catch {\n\t\t\t// A stale acknowledgement is handled by the content check, not by its absence.\n\t\t}\n\t\twrite(\"suspend\");\n\t\tawait waitForAcknowledgement();\n\t\ttry {\n\t\t\treturn await prompt();\n\t\t} finally {\n\t\t\twrite(\"resume\");\n\t\t}\n\t}\n\n\treturn {\n\t\tborrowTerminal<T>(prompt: () => Promise<T>): Promise<T> {\n\t\t\tconst next = queue.then(\n\t\t\t\t() => run(prompt),\n\t\t\t\t() => run(prompt),\n\t\t\t);\n\t\t\t// Swallowed here only so one rejected borrow does not poison the queue for the\n\t\t\t// next; the caller still receives the rejection through `next`.\n\t\t\tqueue = next.then(\n\t\t\t\t() => undefined,\n\t\t\t\t() => undefined,\n\t\t\t);\n\t\t\treturn next;\n\t\t},\n\t\tstop(): void {\n\t\t\twrite(\"resume\");\n\t\t},\n\t};\n}\n\n/** Child side. Acknowledges a suspend once it has actually stopped drawing and reading. */\nexport function observeTerminalHandoff(\n\tdirectory: string,\n\thooks: { suspend: () => void | Promise<void>; resume: () => void | Promise<void> },\n): { stop: () => void } {\n\tconst statePath = join(directory, STATE_FILE);\n\tconst acknowledgementPath = join(directory, ACKNOWLEDGEMENT_FILE);\n\tlet current: HandoffState = \"resume\";\n\tlet applying: Promise<void> = Promise.resolve();\n\n\tconst apply = () => {\n\t\tlet state: HandoffState | undefined;\n\t\ttry {\n\t\t\tstate = parseState(readFileSync(statePath, \"utf8\"));\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t\tif (!state || state === current) return;\n\t\tcurrent = state;\n\t\tapplying = applying.then(async () => {\n\t\t\tif (state === \"suspend\") {\n\t\t\t\tawait hooks.suspend();\n\t\t\t\ttry {\n\t\t\t\t\twriteFileSync(acknowledgementPath, \"suspended\\n\");\n\t\t\t\t} catch {\n\t\t\t\t\t// The supervisor's timeout covers an acknowledgement we cannot write.\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tawait hooks.resume();\n\t\t\t}\n\t\t});\n\t};\n\n\tapply();\n\n\tlet watcher: FSWatcher | undefined;\n\ttry {\n\t\twatcher = watch(directory, apply);\n\t} catch {\n\t\t// Without a watcher the poll below still delivers, just less promptly.\n\t}\n\tconst poll = setInterval(apply, POLL_INTERVAL_MS);\n\t// Never hold the process open for this. The child exits on its own schedule and a\n\t// handoff that stops being observed at shutdown has nothing left to deliver.\n\tpoll.unref();\n\n\treturn {\n\t\tstop: () => {\n\t\t\twatcher?.close();\n\t\t\tclearInterval(poll);\n\t\t},\n\t};\n}\n"]}

package/dist/core/sandbox/terminal-handoff.js

@@ -0,0 +1,176 @@
+import { readFileSync, rmSync, watch, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Lends the terminal from the sandboxed child back to the supervisor for a prompt.
+ *
+ * The supervisor has to draw the escalation prompt itself. Per ADR 0023 an approval
+ * asserted from inside the boundary is indistinguishable from one forged by the code the
+ * boundary exists to contain, so the human's answer must be read by the side that owns the
+ * decision. The child cannot read it in any case: it runs under `bwrap --new-session` and
+ * has no controlling terminal, which `terminal-size.ts` documents for the same reason.
+ *
+ * The transport is the one `terminal-size.ts` already established -- a file in the
+ * workspace, which is bind-mounted into the child, watched on the other side. Signals are
+ * unavailable because bwrap sits between the processes as PID 1 and forwards nothing.
+ *
+ * Two files rather than one, because the supervisor must know the child has actually let
+ * go of stdin before it reads an answer. The child inherits stdin and its TUI holds it in
+ * raw mode; prompting while both sides read would lose keystrokes to whichever won.
+ *
+ * The child is asked, never obeyed. A child that never acknowledges delays the prompt by
+ * the timeout and no longer, because a contained process that could withhold
+ * acknowledgement indefinitely would be able to veto the human's decision -- which is the
+ * authority failure ADR 0023 forbids. An unread prompt is a legibility failure, and that
+ * is the direction this is allowed to fail in.
+ */
+/** Env var naming the directory both sides agree on. */
+export const TERMINAL_HANDOFF_PATH_VARIABLE = "APEX_TERMINAL_HANDOFF_PATH";
+const STATE_FILE = "terminal-handoff";
+const ACKNOWLEDGEMENT_FILE = "terminal-handoff-ack";
+const DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS = 1_000;
+/**
+ * How often each side re-reads the state file, independently of the watcher.
+ *
+ * `fs.watch` is a thin wrapper over whatever the platform provides, and the platforms do
+ * not agree. macOS CI delivered a resume more than a second after it was written, and
+ * intermittently: the event arrives, late enough that a TUI would sit visibly frozen
+ * after the human had already answered. The watcher still does the work in the common
+ * case; this only bounds how wrong it can be.
+ */
+const POLL_INTERVAL_MS = 100;
+function parseState(contents) {
+    const value = contents.trim();
+    return value === "suspend" || value === "resume" ? value : undefined;
+}
+/** Supervisor side. */
+export function createTerminalHandoff(directory, options) {
+    const statePath = join(directory, STATE_FILE);
+    const acknowledgementPath = join(directory, ACKNOWLEDGEMENT_FILE);
+    const timeout = options?.acknowledgementTimeoutMs ?? DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS;
+    // Every borrow chains onto the last, which is what keeps two escalations that arrive
+    // together from drawing over each other.
+    let queue = Promise.resolve();
+    function write(state) {
+        try {
+            writeFileSync(statePath, `${state}\n`);
+        }
+        catch {
+            // A handoff we cannot request still leaves the prompt readable often enough to
+            // be worth attempting; it is never worth failing the escalation over.
+        }
+    }
+    function waitForAcknowledgement() {
+        return new Promise((resolve) => {
+            let watcher;
+            let timer;
+            let poll;
+            const finish = () => {
+                if (timer)
+                    clearTimeout(timer);
+                if (poll)
+                    clearInterval(poll);
+                watcher?.close();
+                resolve();
+            };
+            const check = () => {
+                try {
+                    if (readFileSync(acknowledgementPath, "utf8").trim() === "suspended")
+                        finish();
+                }
+                catch {
+                    // Not written yet.
+                }
+            };
+            timer = setTimeout(finish, timeout);
+            try {
+                watcher = watch(directory, check);
+            }
+            catch {
+                // Without a watcher the poll below still delivers, just less promptly.
+            }
+            poll = setInterval(check, POLL_INTERVAL_MS);
+            poll.unref();
+            check();
+        });
+    }
+    async function run(prompt) {
+        try {
+            rmSync(acknowledgementPath, { force: true });
+        }
+        catch {
+            // A stale acknowledgement is handled by the content check, not by its absence.
+        }
+        write("suspend");
+        await waitForAcknowledgement();
+        try {
+            return await prompt();
+        }
+        finally {
+            write("resume");
+        }
+    }
+    return {
+        borrowTerminal(prompt) {
+            const next = queue.then(() => run(prompt), () => run(prompt));
+            // Swallowed here only so one rejected borrow does not poison the queue for the
+            // next; the caller still receives the rejection through `next`.
+            queue = next.then(() => undefined, () => undefined);
+            return next;
+        },
+        stop() {
+            write("resume");
+        },
+    };
+}
+/** Child side. Acknowledges a suspend once it has actually stopped drawing and reading. */
+export function observeTerminalHandoff(directory, hooks) {
+    const statePath = join(directory, STATE_FILE);
+    const acknowledgementPath = join(directory, ACKNOWLEDGEMENT_FILE);
+    let current = "resume";
+    let applying = Promise.resolve();
+    const apply = () => {
+        let state;
+        try {
+            state = parseState(readFileSync(statePath, "utf8"));
+        }
+        catch {
+            return;
+        }
+        if (!state || state === current)
+            return;
+        current = state;
+        applying = applying.then(async () => {
+            if (state === "suspend") {
+                await hooks.suspend();
+                try {
+                    writeFileSync(acknowledgementPath, "suspended\n");
+                }
+                catch {
+                    // The supervisor's timeout covers an acknowledgement we cannot write.
+                }
+            }
+            else {
+                await hooks.resume();
+            }
+        });
+    };
+    apply();
+    let watcher;
+    try {
+        watcher = watch(directory, apply);
+    }
+    catch {
+        // Without a watcher the poll below still delivers, just less promptly.
+    }
+    const poll = setInterval(apply, POLL_INTERVAL_MS);
+    // Never hold the process open for this. The child exits on its own schedule and a
+    // handoff that stops being observed at shutdown has nothing left to deliver.
+    poll.unref();
+    return {
+        stop: () => {
+            watcher?.close();
+            clearInterval(poll);
+        },
+    };
+}
+//# sourceMappingURL=terminal-handoff.js.map

package/dist/core/sandbox/terminal-handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-handoff.js","sourceRoot":"","sources":["../../../src/core/sandbox/terminal-handoff.ts"],"names":[],"mappings":"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","sourcesContent":["import { type FSWatcher, readFileSync, rmSync, watch, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\n/**\n * Lends the terminal from the sandboxed child back to the supervisor for a prompt.\n *\n * The supervisor has to draw the escalation prompt itself. Per ADR 0023 an approval\n * asserted from inside the boundary is indistinguishable from one forged by the code the\n * boundary exists to contain, so the human's answer must be read by the side that owns the\n * decision. The child cannot read it in any case: it runs under `bwrap --new-session` and\n * has no controlling terminal, which `terminal-size.ts` documents for the same reason.\n *\n * The transport is the one `terminal-size.ts` already established -- a file in the\n * workspace, which is bind-mounted into the child, watched on the other side. Signals are\n * unavailable because bwrap sits between the processes as PID 1 and forwards nothing.\n *\n * Two files rather than one, because the supervisor must know the child has actually let\n * go of stdin before it reads an answer. The child inherits stdin and its TUI holds it in\n * raw mode; prompting while both sides read would lose keystrokes to whichever won.\n *\n * The child is asked, never obeyed. A child that never acknowledges delays the prompt by\n * the timeout and no longer, because a contained process that could withhold\n * acknowledgement indefinitely would be able to veto the human's decision -- which is the\n * authority failure ADR 0023 forbids. An unread prompt is a legibility failure, and that\n * is the direction this is allowed to fail in.\n */\n\n/** Env var naming the directory both sides agree on. */\nexport const TERMINAL_HANDOFF_PATH_VARIABLE = \"APEX_TERMINAL_HANDOFF_PATH\";\n\nconst STATE_FILE = \"terminal-handoff\";\nconst ACKNOWLEDGEMENT_FILE = \"terminal-handoff-ack\";\nconst DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS = 1_000;\n\n/**\n * How often each side re-reads the state file, independently of the watcher.\n *\n * `fs.watch` is a thin wrapper over whatever the platform provides, and the platforms do\n * not agree. macOS CI delivered a resume more than a second after it was written, and\n * intermittently: the event arrives, late enough that a TUI would sit visibly frozen\n * after the human had already answered. The watcher still does the work in the common\n * case; this only bounds how wrong it can be.\n */\nconst POLL_INTERVAL_MS = 100;\n\ntype HandoffState = \"suspend\" | \"resume\";\n\nfunction parseState(contents: string): HandoffState | undefined {\n\tconst value = contents.trim();\n\treturn value === \"suspend\" || value === \"resume\" ? value : undefined;\n}\n\nexport interface TerminalHandoff {\n\t/**\n\t * Suspend the child, run `prompt` with the terminal to itself, then resume the child.\n\t * Overlapping calls are serialised, so two prompts never share the terminal.\n\t */\n\tborrowTerminal<T>(prompt: () => Promise<T>): Promise<T>;\n\tstop(): void;\n}\n\n/** Supervisor side. */\nexport function createTerminalHandoff(\n\tdirectory: string,\n\toptions?: { acknowledgementTimeoutMs?: number },\n): TerminalHandoff {\n\tconst statePath = join(directory, STATE_FILE);\n\tconst acknowledgementPath = join(directory, ACKNOWLEDGEMENT_FILE);\n\tconst timeout = options?.acknowledgementTimeoutMs ?? DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS;\n\t// Every borrow chains onto the last, which is what keeps two escalations that arrive\n\t// together from drawing over each other.\n\tlet queue: Promise<unknown> = Promise.resolve();\n\n\tfunction write(state: HandoffState): void {\n\t\ttry {\n\t\t\twriteFileSync(statePath, `${state}\\n`);\n\t\t} catch {\n\t\t\t// A handoff we cannot request still leaves the prompt readable often enough to\n\t\t\t// be worth attempting; it is never worth failing the escalation over.\n\t\t}\n\t}\n\n\tfunction waitForAcknowledgement(): Promise<void> {\n\t\treturn new Promise((resolve) => {\n\t\t\tlet watcher: FSWatcher | undefined;\n\t\t\tlet timer: NodeJS.Timeout | undefined;\n\t\t\tlet poll: NodeJS.Timeout | undefined;\n\t\t\tconst finish = () => {\n\t\t\t\tif (timer) clearTimeout(timer);\n\t\t\t\tif (poll) clearInterval(poll);\n\t\t\t\twatcher?.close();\n\t\t\t\tresolve();\n\t\t\t};\n\t\t\tconst check = () => {\n\t\t\t\ttry {\n\t\t\t\t\tif (readFileSync(acknowledgementPath, \"utf8\").trim() === \"suspended\") finish();\n\t\t\t\t} catch {\n\t\t\t\t\t// Not written yet.\n\t\t\t\t}\n\t\t\t};\n\t\t\ttimer = setTimeout(finish, timeout);\n\t\t\ttry {\n\t\t\t\twatcher = watch(directory, check);\n\t\t\t} catch {\n\t\t\t\t// Without a watcher the poll below still delivers, just less promptly.\n\t\t\t}\n\t\t\tpoll = setInterval(check, POLL_INTERVAL_MS);\n\t\t\tpoll.unref();\n\t\t\tcheck();\n\t\t});\n\t}\n\n\tasync function run<T>(prompt: () => Promise<T>): Promise<T> {\n\t\ttry {\n\t\t\trmSync(acknowledgementPath, { force: true });\n\t\t} catch {\n\t\t\t// A stale acknowledgement is handled by the content check, not by its absence.\n\t\t}\n\t\twrite(\"suspend\");\n\t\tawait waitForAcknowledgement();\n\t\ttry {\n\t\t\treturn await prompt();\n\t\t} finally {\n\t\t\twrite(\"resume\");\n\t\t}\n\t}\n\n\treturn {\n\t\tborrowTerminal<T>(prompt: () => Promise<T>): Promise<T> {\n\t\t\tconst next = queue.then(\n\t\t\t\t() => run(prompt),\n\t\t\t\t() => run(prompt),\n\t\t\t);\n\t\t\t// Swallowed here only so one rejected borrow does not poison the queue for the\n\t\t\t// next; the caller still receives the rejection through `next`.\n\t\t\tqueue = next.then(\n\t\t\t\t() => undefined,\n\t\t\t\t() => undefined,\n\t\t\t);\n\t\t\treturn next;\n\t\t},\n\t\tstop(): void {\n\t\t\twrite(\"resume\");\n\t\t},\n\t};\n}\n\n/** Child side. Acknowledges a suspend once it has actually stopped drawing and reading. */\nexport function observeTerminalHandoff(\n\tdirectory: string,\n\thooks: { suspend: () => void | Promise<void>; resume: () => void | Promise<void> },\n): { stop: () => void } {\n\tconst statePath = join(directory, STATE_FILE);\n\tconst acknowledgementPath = join(directory, ACKNOWLEDGEMENT_FILE);\n\tlet current: HandoffState = \"resume\";\n\tlet applying: Promise<void> = Promise.resolve();\n\n\tconst apply = () => {\n\t\tlet state: HandoffState | undefined;\n\t\ttry {\n\t\t\tstate = parseState(readFileSync(statePath, \"utf8\"));\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t\tif (!state || state === current) return;\n\t\tcurrent = state;\n\t\tapplying = applying.then(async () => {\n\t\t\tif (state === \"suspend\") {\n\t\t\t\tawait hooks.suspend();\n\t\t\t\ttry {\n\t\t\t\t\twriteFileSync(acknowledgementPath, \"suspended\\n\");\n\t\t\t\t} catch {\n\t\t\t\t\t// The supervisor's timeout covers an acknowledgement we cannot write.\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tawait hooks.resume();\n\t\t\t}\n\t\t});\n\t};\n\n\tapply();\n\n\tlet watcher: FSWatcher | undefined;\n\ttry {\n\t\twatcher = watch(directory, apply);\n\t} catch {\n\t\t// Without a watcher the poll below still delivers, just less promptly.\n\t}\n\tconst poll = setInterval(apply, POLL_INTERVAL_MS);\n\t// Never hold the process open for this. The child exits on its own schedule and a\n\t// handoff that stops being observed at shutdown has nothing left to deliver.\n\tpoll.unref();\n\n\treturn {\n\t\tstop: () => {\n\t\t\twatcher?.close();\n\t\t\tclearInterval(poll);\n\t\t},\n\t};\n}\n"]}

package/dist/core/sandbox/terminal-size.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Carries the host terminal's size across the sandbox boundary.
+ *
+ * The sandboxed child runs under `bwrap --new-session`, so it has no
+ * controlling terminal: the kernel never sends it SIGWINCH, and the window size
+ * its stdout reports is frozen at whatever it was when the sandbox was created.
+ * Everything downstream reads `process.stdout.columns`, so a resize left the TUI
+ * rendering to a width the terminal no longer had.
+ *
+ * The supervisor owns a real TTY and does get the resize event. It publishes the
+ * new size to a file inside the workspace, which is already bind-mounted into
+ * the sandbox; the child watches that file and republishes it as a `resize` on
+ * its own stdout. Signals are deliberately not used as the transport: bwrap sits
+ * between the two processes as PID 1 and does not forward SIGWINCH.
+ */
+/** Env var naming the file both sides agree on. */
+export declare const TERMINAL_SIZE_PATH_VARIABLE = "APEX_TERMINAL_SIZE_PATH";
+export interface TerminalSize {
+    columns: number;
+    rows: number;
+}
+export declare function parseTerminalSize(contents: string): TerminalSize | undefined;
+/**
+ * Host side. Publishes the current size, then republishes on every resize.
+ * Returns a stop function; the caller must run it on every launch exit path.
+ */
+export declare function publishTerminalSize(path: string, stdout?: NodeJS.WriteStream): () => void;
+/**
+ * Child side. Applies the published size to `process.stdout` and keeps applying
+ * it as the file changes.
+ *
+ * `columns` and `rows` are redefined as getters because Node recomputes them
+ * from the sandbox's own console on SIGWINCH, which is exactly the stale value
+ * this exists to override. The setters swallow those writes rather than throwing.
+ */
+export declare function applyTerminalSize(path: string, stdout?: NodeJS.WriteStream): {
+    stop: () => void;
+    refresh: () => void;
+};
+//# sourceMappingURL=terminal-size.d.ts.map

package/dist/core/sandbox/terminal-size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-size.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/terminal-size.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,mDAAmD;AACnD,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAErE,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACb;AAMD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAK5E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,WAA4B,GAAG,MAAM,IAAI,CAmBzG;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAAM,CAAC,WAA4B,GACzC;IAAE,IAAI,EAAE,MAAM,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAyC3C","sourcesContent":["import { type FSWatcher, readFileSync, watch, writeFileSync } from \"node:fs\";\n\n/**\n * Carries the host terminal's size across the sandbox boundary.\n *\n * The sandboxed child runs under `bwrap --new-session`, so it has no\n * controlling terminal: the kernel never sends it SIGWINCH, and the window size\n * its stdout reports is frozen at whatever it was when the sandbox was created.\n * Everything downstream reads `process.stdout.columns`, so a resize left the TUI\n * rendering to a width the terminal no longer had.\n *\n * The supervisor owns a real TTY and does get the resize event. It publishes the\n * new size to a file inside the workspace, which is already bind-mounted into\n * the sandbox; the child watches that file and republishes it as a `resize` on\n * its own stdout. Signals are deliberately not used as the transport: bwrap sits\n * between the two processes as PID 1 and does not forward SIGWINCH.\n */\n\n/** Env var naming the file both sides agree on. */\nexport const TERMINAL_SIZE_PATH_VARIABLE = \"APEX_TERMINAL_SIZE_PATH\";\n\nexport interface TerminalSize {\n\tcolumns: number;\n\trows: number;\n}\n\nfunction formatSize(size: TerminalSize): string {\n\treturn `${size.columns} ${size.rows}\\n`;\n}\n\nexport function parseTerminalSize(contents: string): TerminalSize | undefined {\n\tconst [columns, rows] = contents.trim().split(/\\s+/).map(Number);\n\tif (!Number.isInteger(columns) || !Number.isInteger(rows)) return undefined;\n\tif (columns <= 0 || rows <= 0) return undefined;\n\treturn { columns, rows };\n}\n\n/**\n * Host side. Publishes the current size, then republishes on every resize.\n * Returns a stop function; the caller must run it on every launch exit path.\n */\nexport function publishTerminalSize(path: string, stdout: NodeJS.WriteStream = process.stdout): () => void {\n\tif (!stdout.isTTY) return () => {};\n\n\tconst write = () => {\n\t\tconst columns = stdout.columns;\n\t\tconst rows = stdout.rows;\n\t\tif (!Number.isInteger(columns) || !Number.isInteger(rows)) return;\n\t\ttry {\n\t\t\twriteFileSync(path, formatSize({ columns, rows }));\n\t\t} catch {\n\t\t\t// A size we cannot publish is not worth failing a launch over.\n\t\t}\n\t};\n\n\twrite();\n\tstdout.on(\"resize\", write);\n\treturn () => {\n\t\tstdout.off(\"resize\", write);\n\t};\n}\n\n/**\n * Child side. Applies the published size to `process.stdout` and keeps applying\n * it as the file changes.\n *\n * `columns` and `rows` are redefined as getters because Node recomputes them\n * from the sandbox's own console on SIGWINCH, which is exactly the stale value\n * this exists to override. The setters swallow those writes rather than throwing.\n */\nexport function applyTerminalSize(\n\tpath: string,\n\tstdout: NodeJS.WriteStream = process.stdout,\n): { stop: () => void; refresh: () => void } {\n\tlet current: TerminalSize | undefined;\n\n\tconst refresh = () => {\n\t\tlet size: TerminalSize | undefined;\n\t\ttry {\n\t\t\tsize = parseTerminalSize(readFileSync(path, \"utf8\"));\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\t\tif (!size) return;\n\t\tif (current && current.columns === size.columns && current.rows === size.rows) return;\n\t\tcurrent = size;\n\t\tObject.defineProperty(stdout, \"columns\", {\n\t\t\tconfigurable: true,\n\t\t\tget: () => current?.columns,\n\t\t\tset: () => {},\n\t\t});\n\t\tObject.defineProperty(stdout, \"rows\", {\n\t\t\tconfigurable: true,\n\t\t\tget: () => current?.rows,\n\t\t\tset: () => {},\n\t\t});\n\t\tstdout.emit(\"resize\");\n\t};\n\n\trefresh();\n\n\tlet watcher: FSWatcher | undefined;\n\ttry {\n\t\twatcher = watch(path, refresh);\n\t} catch {\n\t\t// Without a watcher the initial size still applies; only live resize is lost.\n\t}\n\n\treturn {\n\t\trefresh,\n\t\tstop: () => {\n\t\t\twatcher?.close();\n\t\t},\n\t};\n}\n"]}