apex-code 0.0.1-alpha.9 → 0.0.4

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

@@ -3,6 +3,11 @@ export interface SandboxLaunch {
     readonly command: string;
     readonly args: readonly string[];
     readonly policy: SandboxPolicy;
+    /**
+     * A supervisor-owned private directory. Platform backends must never derive this
+     * from the workspace or fall back to it.
+     */
+    readonly supervisorStateDirectory: string;
     readonly environment?: NodeJS.ProcessEnv;
     /** Application/runtime directories needed by the child but never writable by it. */
     readonly readOnlyPaths?: readonly string[];
@@ -37,7 +42,13 @@ export interface SandboxBackend {
 }
 export interface SandboxSupervisor {
     readonly status: SandboxStatus;
-    launch(options: Omit<SandboxLaunch, "policy">): Promise<number>;
+    /**
+     * The supervisor may allocate this for low-level callers and tests. The backend
+     * still receives a required, private path on every launch.
+     */
+    launch(options: Omit<SandboxLaunch, "policy" | "supervisorStateDirectory"> & {
+        readonly supervisorStateDirectory?: string;
+    }): Promise<number>;
     close(): Promise<void>;
 }
 /**

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

@@ -1 +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"]}
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor.ts"],"names":[],"mappings":"AAGA,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;;;OAGG;IACH,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,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;;;OAGG;IACH,MAAM,CACL,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,0BAA0B,CAAC,GAAG;QACrE,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;KAC3C,GACC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,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,CAoBpB","sourcesContent":["import { chmodSync, mkdtempSync, rmSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { 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\t/**\n\t * A supervisor-owned private directory. Platform backends must never derive this\n\t * from the workspace or fall back to it.\n\t */\n\treadonly supervisorStateDirectory: string;\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\t/**\n\t * The supervisor may allocate this for low-level callers and tests. The backend\n\t * still receives a required, private path on every launch.\n\t */\n\tlaunch(\n\t\toptions: Omit<SandboxLaunch, \"policy\" | \"supervisorStateDirectory\"> & {\n\t\t\treadonly supervisorStateDirectory?: string;\n\t\t},\n\t): 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\tconst ownsStateDirectory = launch.supervisorStateDirectory === undefined;\n\t\t\tconst supervisorStateDirectory =\n\t\t\t\tlaunch.supervisorStateDirectory ??\n\t\t\t\tmkdtempSync(join(tmpdir(), `apex-supervisor-${process.pid}-`), { encoding: \"utf8\" });\n\t\t\tif (ownsStateDirectory) chmodSync(supervisorStateDirectory, 0o700);\n\t\t\ttry {\n\t\t\t\treturn await options.backend.launch({ ...launch, supervisorStateDirectory, policy: options.policy });\n\t\t\t} finally {\n\t\t\t\tif (ownsStateDirectory) rmSync(supervisorStateDirectory, { force: true, recursive: true });\n\t\t\t}\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

@@ -1,3 +1,6 @@
+import { chmodSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { requireSandboxEnforcement } from "./policy.js";
 /**
  * Owns fail-closed policy propagation and lifecycle; OS details remain behind the
@@ -8,7 +11,18 @@ export function createSandboxSupervisor(options) {
         status: options.backend.status,
         async launch(launch) {
             requireSandboxEnforcement(options.backend.status);
-            return options.backend.launch({ ...launch, policy: options.policy });
+            const ownsStateDirectory = launch.supervisorStateDirectory === undefined;
+            const supervisorStateDirectory = launch.supervisorStateDirectory ??
+                mkdtempSync(join(tmpdir(), `apex-supervisor-${process.pid}-`), { encoding: "utf8" });
+            if (ownsStateDirectory)
+                chmodSync(supervisorStateDirectory, 0o700);
+            try {
+                return await options.backend.launch({ ...launch, supervisorStateDirectory, policy: options.policy });
+            }
+            finally {
+                if (ownsStateDirectory)
+                    rmSync(supervisorStateDirectory, { force: true, recursive: true });
+            }
         },
         async close() {
             await options.backend.close();

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

@@ -1 +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"]}
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../src/core/sandbox/supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,yBAAyB,EAA0C,MAAM,aAAa,CAAC;AAwDhG;;;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,MAAM,kBAAkB,GAAG,MAAM,CAAC,wBAAwB,KAAK,SAAS,CAAC;YACzE,MAAM,wBAAwB,GAC7B,MAAM,CAAC,wBAAwB;gBAC/B,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,mBAAmB,OAAO,CAAC,GAAG,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YACtF,IAAI,kBAAkB;gBAAE,SAAS,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;YACnE,IAAI,CAAC;gBACJ,OAAO,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,wBAAwB,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YACtG,CAAC;oBAAS,CAAC;gBACV,IAAI,kBAAkB;oBAAE,MAAM,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5F,CAAC;QAAA,CACD;QACD,KAAK,CAAC,KAAK,GAAG;YACb,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAAA,CAC9B;KACD,CAAC;AAAA,CACF","sourcesContent":["import { chmodSync, mkdtempSync, rmSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { 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\t/**\n\t * A supervisor-owned private directory. Platform backends must never derive this\n\t * from the workspace or fall back to it.\n\t */\n\treadonly supervisorStateDirectory: string;\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\t/**\n\t * The supervisor may allocate this for low-level callers and tests. The backend\n\t * still receives a required, private path on every launch.\n\t */\n\tlaunch(\n\t\toptions: Omit<SandboxLaunch, \"policy\" | \"supervisorStateDirectory\"> & {\n\t\t\treadonly supervisorStateDirectory?: string;\n\t\t},\n\t): 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\tconst ownsStateDirectory = launch.supervisorStateDirectory === undefined;\n\t\t\tconst supervisorStateDirectory =\n\t\t\t\tlaunch.supervisorStateDirectory ??\n\t\t\t\tmkdtempSync(join(tmpdir(), `apex-supervisor-${process.pid}-`), { encoding: \"utf8\" });\n\t\t\tif (ownsStateDirectory) chmodSync(supervisorStateDirectory, 0o700);\n\t\t\ttry {\n\t\t\t\treturn await options.backend.launch({ ...launch, supervisorStateDirectory, policy: options.policy });\n\t\t\t} finally {\n\t\t\t\tif (ownsStateDirectory) rmSync(supervisorStateDirectory, { force: true, recursive: true });\n\t\t\t}\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,68 @@
+/**
+ * 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 holding the supervisor's command file.
+ *
+ * Supervisor-private where the platform backend allocates one (PS.3): the child reads the
+ * suspend/resume latch there and can never write it. The acknowledgement travels the other
+ * way and therefore has its own variable below.
+ */
+export declare const TERMINAL_HANDOFF_PATH_VARIABLE = "APEX_TERMINAL_HANDOFF_PATH";
+/**
+ * Env var naming the child-writable acknowledgement file.
+ *
+ * Absent means "the file next to the command file", which is the single-directory
+ * arrangement the macOS backend still uses. The two locations are kept explicit rather
+ * than derived because the platforms genuinely differ: Linux can put the command file on a
+ * host path the child sees read-only, and macOS has no `/home` tmpfs to separate them with.
+ */
+export declare const TERMINAL_HANDOFF_ACK_PATH_VARIABLE = "APEX_TERMINAL_HANDOFF_ACK_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;
+}
+export interface TerminalHandoffOptions {
+    acknowledgementTimeoutMs?: number;
+    /**
+     * Where the child writes its acknowledgement. Defaults to the file beside the command
+     * file. Split from it when the command file lives somewhere the child cannot write.
+     */
+    acknowledgementPath?: string;
+}
+/** Supervisor side. `directory` holds the command file; see the env vars above. */
+export declare function createTerminalHandoff(directory: string, options?: TerminalHandoffOptions): 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>;
+}, options?: {
+    acknowledgementPath?: string;
+}): {
+    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":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,+BAA+B,CAAC;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,kCAAkC,mCAAmC,CAAC;AA+CnF,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,MAAM,WAAW,sBAAsB;IACtC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,eAAe,CAwF1G;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,EAClF,OAAO,CAAC,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,MAAM,IAAI,CAAA;CAAE,CAgDtB","sourcesContent":["import { closeSync, constants, type FSWatcher, openSync, readFileSync, rmSync, watch } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { writeWithoutFollowingLinks } from \"./terminal-size.ts\";\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/**\n * Env var naming the directory holding the supervisor's command file.\n *\n * Supervisor-private where the platform backend allocates one (PS.3): the child reads the\n * suspend/resume latch there and can never write it. The acknowledgement travels the other\n * way and therefore has its own variable below.\n */\nexport const TERMINAL_HANDOFF_PATH_VARIABLE = \"APEX_TERMINAL_HANDOFF_PATH\";\n\n/**\n * Env var naming the child-writable acknowledgement file.\n *\n * Absent means \"the file next to the command file\", which is the single-directory\n * arrangement the macOS backend still uses. The two locations are kept explicit rather\n * than derived because the platforms genuinely differ: Linux can put the command file on a\n * host path the child sees read-only, and macOS has no `/home` tmpfs to separate them with.\n */\nexport const TERMINAL_HANDOFF_ACK_PATH_VARIABLE = \"APEX_TERMINAL_HANDOFF_ACK_PATH\";\n\nconst STATE_FILE = \"terminal-handoff\";\nconst ACKNOWLEDGEMENT_FILE = \"terminal-handoff-ack\";\nconst DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS = 1_000;\n\n/**\n * Read without following a symlink at the final path component; undefined when refused.\n *\n * The acknowledgement is the one half of the handoff the contained side writes, so a link\n * planted at its path would otherwise let the child choose which host file the supervisor\n * reads. Its content is not authority (ADR 0023), but the read itself is the supervisor's.\n */\nfunction readWithoutFollowingLinks(path: string): string | undefined {\n\tlet descriptor: number;\n\ttry {\n\t\tdescriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);\n\t} catch {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\treturn readFileSync(descriptor, \"utf8\");\n\t} catch {\n\t\treturn undefined;\n\t} finally {\n\t\tcloseSync(descriptor);\n\t}\n}\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\nexport interface TerminalHandoffOptions {\n\tacknowledgementTimeoutMs?: number;\n\t/**\n\t * Where the child writes its acknowledgement. Defaults to the file beside the command\n\t * file. Split from it when the command file lives somewhere the child cannot write.\n\t */\n\tacknowledgementPath?: string;\n}\n\n/** Supervisor side. `directory` holds the command file; see the env vars above. */\nexport function createTerminalHandoff(directory: string, options?: TerminalHandoffOptions): TerminalHandoff {\n\tconst statePath = join(directory, STATE_FILE);\n\tconst acknowledgementPath = options?.acknowledgementPath ?? join(directory, ACKNOWLEDGEMENT_FILE);\n\tconst acknowledgementDirectory = dirname(acknowledgementPath);\n\t// Floored at two poll intervals. The state file is a latch the child samples, so a\n\t// supervisor that gives up before the child can sample writes `resume` over its own\n\t// `suspend` and the child observes neither: it reads one value equal to what it\n\t// already held. Two intervals guarantee a sampling opportunity even when the\n\t// watcher never fires, which is the macOS case POLL_INTERVAL_MS exists for.\n\tconst timeout = Math.max(\n\t\toptions?.acknowledgementTimeoutMs ?? DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS,\n\t\tPOLL_INTERVAL_MS * 2,\n\t);\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\twriteWithoutFollowingLinks(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\t// No-follow: the acknowledgement path is the one half of the handoff the child\n\t\t\t\t// may write, so a link planted there would otherwise let it choose which host\n\t\t\t\t// file the supervisor reads.\n\t\t\t\tif (readWithoutFollowingLinks(acknowledgementPath)?.trim() === \"suspended\") finish();\n\t\t\t};\n\t\t\ttimer = setTimeout(finish, timeout);\n\t\t\ttry {\n\t\t\t\twatcher = watch(acknowledgementDirectory, 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\toptions?: { acknowledgementPath?: string },\n): { stop: () => void } {\n\tconst statePath = join(directory, STATE_FILE);\n\tconst acknowledgementPath = options?.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\twriteWithoutFollowingLinks(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,221 @@
+import { closeSync, constants, openSync, readFileSync, rmSync, watch } from "node:fs";
+import { dirname, join } from "node:path";
+import { writeWithoutFollowingLinks } from "./terminal-size.js";
+/**
+ * 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 holding the supervisor's command file.
+ *
+ * Supervisor-private where the platform backend allocates one (PS.3): the child reads the
+ * suspend/resume latch there and can never write it. The acknowledgement travels the other
+ * way and therefore has its own variable below.
+ */
+export const TERMINAL_HANDOFF_PATH_VARIABLE = "APEX_TERMINAL_HANDOFF_PATH";
+/**
+ * Env var naming the child-writable acknowledgement file.
+ *
+ * Absent means "the file next to the command file", which is the single-directory
+ * arrangement the macOS backend still uses. The two locations are kept explicit rather
+ * than derived because the platforms genuinely differ: Linux can put the command file on a
+ * host path the child sees read-only, and macOS has no `/home` tmpfs to separate them with.
+ */
+export const TERMINAL_HANDOFF_ACK_PATH_VARIABLE = "APEX_TERMINAL_HANDOFF_ACK_PATH";
+const STATE_FILE = "terminal-handoff";
+const ACKNOWLEDGEMENT_FILE = "terminal-handoff-ack";
+const DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS = 1_000;
+/**
+ * Read without following a symlink at the final path component; undefined when refused.
+ *
+ * The acknowledgement is the one half of the handoff the contained side writes, so a link
+ * planted at its path would otherwise let the child choose which host file the supervisor
+ * reads. Its content is not authority (ADR 0023), but the read itself is the supervisor's.
+ */
+function readWithoutFollowingLinks(path) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return readFileSync(descriptor, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+/**
+ * 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. `directory` holds the command file; see the env vars above. */
+export function createTerminalHandoff(directory, options) {
+    const statePath = join(directory, STATE_FILE);
+    const acknowledgementPath = options?.acknowledgementPath ?? join(directory, ACKNOWLEDGEMENT_FILE);
+    const acknowledgementDirectory = dirname(acknowledgementPath);
+    // Floored at two poll intervals. The state file is a latch the child samples, so a
+    // supervisor that gives up before the child can sample writes `resume` over its own
+    // `suspend` and the child observes neither: it reads one value equal to what it
+    // already held. Two intervals guarantee a sampling opportunity even when the
+    // watcher never fires, which is the macOS case POLL_INTERVAL_MS exists for.
+    const timeout = Math.max(options?.acknowledgementTimeoutMs ?? DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS, POLL_INTERVAL_MS * 2);
+    // 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 {
+            writeWithoutFollowingLinks(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 = () => {
+                // No-follow: the acknowledgement path is the one half of the handoff the child
+                // may write, so a link planted there would otherwise let it choose which host
+                // file the supervisor reads.
+                if (readWithoutFollowingLinks(acknowledgementPath)?.trim() === "suspended")
+                    finish();
+            };
+            timer = setTimeout(finish, timeout);
+            try {
+                watcher = watch(acknowledgementDirectory, 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, options) {
+    const statePath = join(directory, STATE_FILE);
+    const acknowledgementPath = options?.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 {
+                    writeWithoutFollowingLinks(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 { closeSync, constants, type FSWatcher, openSync, readFileSync, rmSync, watch } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { writeWithoutFollowingLinks } from \"./terminal-size.ts\";\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/**\n * Env var naming the directory holding the supervisor's command file.\n *\n * Supervisor-private where the platform backend allocates one (PS.3): the child reads the\n * suspend/resume latch there and can never write it. The acknowledgement travels the other\n * way and therefore has its own variable below.\n */\nexport const TERMINAL_HANDOFF_PATH_VARIABLE = \"APEX_TERMINAL_HANDOFF_PATH\";\n\n/**\n * Env var naming the child-writable acknowledgement file.\n *\n * Absent means \"the file next to the command file\", which is the single-directory\n * arrangement the macOS backend still uses. The two locations are kept explicit rather\n * than derived because the platforms genuinely differ: Linux can put the command file on a\n * host path the child sees read-only, and macOS has no `/home` tmpfs to separate them with.\n */\nexport const TERMINAL_HANDOFF_ACK_PATH_VARIABLE = \"APEX_TERMINAL_HANDOFF_ACK_PATH\";\n\nconst STATE_FILE = \"terminal-handoff\";\nconst ACKNOWLEDGEMENT_FILE = \"terminal-handoff-ack\";\nconst DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS = 1_000;\n\n/**\n * Read without following a symlink at the final path component; undefined when refused.\n *\n * The acknowledgement is the one half of the handoff the contained side writes, so a link\n * planted at its path would otherwise let the child choose which host file the supervisor\n * reads. Its content is not authority (ADR 0023), but the read itself is the supervisor's.\n */\nfunction readWithoutFollowingLinks(path: string): string | undefined {\n\tlet descriptor: number;\n\ttry {\n\t\tdescriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);\n\t} catch {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\treturn readFileSync(descriptor, \"utf8\");\n\t} catch {\n\t\treturn undefined;\n\t} finally {\n\t\tcloseSync(descriptor);\n\t}\n}\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\nexport interface TerminalHandoffOptions {\n\tacknowledgementTimeoutMs?: number;\n\t/**\n\t * Where the child writes its acknowledgement. Defaults to the file beside the command\n\t * file. Split from it when the command file lives somewhere the child cannot write.\n\t */\n\tacknowledgementPath?: string;\n}\n\n/** Supervisor side. `directory` holds the command file; see the env vars above. */\nexport function createTerminalHandoff(directory: string, options?: TerminalHandoffOptions): TerminalHandoff {\n\tconst statePath = join(directory, STATE_FILE);\n\tconst acknowledgementPath = options?.acknowledgementPath ?? join(directory, ACKNOWLEDGEMENT_FILE);\n\tconst acknowledgementDirectory = dirname(acknowledgementPath);\n\t// Floored at two poll intervals. The state file is a latch the child samples, so a\n\t// supervisor that gives up before the child can sample writes `resume` over its own\n\t// `suspend` and the child observes neither: it reads one value equal to what it\n\t// already held. Two intervals guarantee a sampling opportunity even when the\n\t// watcher never fires, which is the macOS case POLL_INTERVAL_MS exists for.\n\tconst timeout = Math.max(\n\t\toptions?.acknowledgementTimeoutMs ?? DEFAULT_ACKNOWLEDGEMENT_TIMEOUT_MS,\n\t\tPOLL_INTERVAL_MS * 2,\n\t);\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\twriteWithoutFollowingLinks(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\t// No-follow: the acknowledgement path is the one half of the handoff the child\n\t\t\t\t// may write, so a link planted there would otherwise let it choose which host\n\t\t\t\t// file the supervisor reads.\n\t\t\t\tif (readWithoutFollowingLinks(acknowledgementPath)?.trim() === \"suspended\") finish();\n\t\t\t};\n\t\t\ttimer = setTimeout(finish, timeout);\n\t\t\ttry {\n\t\t\t\twatcher = watch(acknowledgementDirectory, 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\toptions?: { acknowledgementPath?: string },\n): { stop: () => void } {\n\tconst statePath = join(directory, STATE_FILE);\n\tconst acknowledgementPath = options?.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\twriteWithoutFollowingLinks(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

@@ -15,6 +15,19 @@
  */
 /** Env var naming the file both sides agree on. */
 export declare const TERMINAL_SIZE_PATH_VARIABLE = "APEX_TERMINAL_SIZE_PATH";
+/**
+ * Write without following a symlink at the final path component.
+ *
+ * Shared with `terminal-handoff.ts`, which took its transport from this file and inherits
+ * the same exposure: every file here is written by the supervisor, on the host, at a path
+ * the contained side may be able to create an entry at. A link planted there would
+ * redirect a host write the child could not otherwise make -- the audit demonstrated this
+ * against the workspace state directory. `O_NOFOLLOW` refuses instead.
+ *
+ * Node exposes no `openat`, so this guards the final component only; the containing
+ * directory must be one the child cannot write for the guarantee to be complete.
+ */
+export declare function writeWithoutFollowingLinks(path: string, contents: string): void;
 export interface TerminalSize {
     columns: number;
     rows: number;

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

@@ -1 +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"]}
+{"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;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAW/E;AAED,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 { closeSync, constants, type FSWatcher, openSync, 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\n/**\n * Write without following a symlink at the final path component.\n *\n * Shared with `terminal-handoff.ts`, which took its transport from this file and inherits\n * the same exposure: every file here is written by the supervisor, on the host, at a path\n * the contained side may be able to create an entry at. A link planted there would\n * redirect a host write the child could not otherwise make -- the audit demonstrated this\n * against the workspace state directory. `O_NOFOLLOW` refuses instead.\n *\n * Node exposes no `openat`, so this guards the final component only; the containing\n * directory must be one the child cannot write for the guarantee to be complete.\n */\nexport function writeWithoutFollowingLinks(path: string, contents: string): void {\n\tconst descriptor = openSync(\n\t\tpath,\n\t\tconstants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW,\n\t\t0o600,\n\t);\n\ttry {\n\t\twriteFileSync(descriptor, contents);\n\t} finally {\n\t\tcloseSync(descriptor);\n\t}\n}\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\twriteWithoutFollowingLinks(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"]}

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

@@ -1,4 +1,4 @@
-import { readFileSync, watch, writeFileSync } from "node:fs";
+import { closeSync, constants, openSync, readFileSync, watch, writeFileSync } from "node:fs";
 /**
  * Carries the host terminal's size across the sandbox boundary.
  *
@@ -16,6 +16,27 @@ import { readFileSync, watch, writeFileSync } from "node:fs";
  */
 /** Env var naming the file both sides agree on. */
 export const TERMINAL_SIZE_PATH_VARIABLE = "APEX_TERMINAL_SIZE_PATH";
+/**
+ * Write without following a symlink at the final path component.
+ *
+ * Shared with `terminal-handoff.ts`, which took its transport from this file and inherits
+ * the same exposure: every file here is written by the supervisor, on the host, at a path
+ * the contained side may be able to create an entry at. A link planted there would
+ * redirect a host write the child could not otherwise make -- the audit demonstrated this
+ * against the workspace state directory. `O_NOFOLLOW` refuses instead.
+ *
+ * Node exposes no `openat`, so this guards the final component only; the containing
+ * directory must be one the child cannot write for the guarantee to be complete.
+ */
+export function writeWithoutFollowingLinks(path, contents) {
+    const descriptor = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o600);
+    try {
+        writeFileSync(descriptor, contents);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
 function formatSize(size) {
     return `${size.columns} ${size.rows}\n`;
 }
@@ -40,7 +61,7 @@ export function publishTerminalSize(path, stdout = process.stdout) {
         if (!Number.isInteger(columns) || !Number.isInteger(rows))
             return;
         try {
-            writeFileSync(path, formatSize({ columns, rows }));
+            writeWithoutFollowingLinks(path, formatSize({ columns, rows }));
         }
         catch {
             // A size we cannot publish is not worth failing a launch over.

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

@@ -1 +1 @@
-{"version":3,"file":"terminal-size.js","sourceRoot":"","sources":["../../../src/core/sandbox/terminal-size.ts"],"names":[],"mappings":"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","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"]}
+{"version":3,"file":"terminal-size.js","sourceRoot":"","sources":["../../../src/core/sandbox/terminal-size.ts"],"names":[],"mappings":"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","sourcesContent":["import { closeSync, constants, type FSWatcher, openSync, 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\n/**\n * Write without following a symlink at the final path component.\n *\n * Shared with `terminal-handoff.ts`, which took its transport from this file and inherits\n * the same exposure: every file here is written by the supervisor, on the host, at a path\n * the contained side may be able to create an entry at. A link planted there would\n * redirect a host write the child could not otherwise make -- the audit demonstrated this\n * against the workspace state directory. `O_NOFOLLOW` refuses instead.\n *\n * Node exposes no `openat`, so this guards the final component only; the containing\n * directory must be one the child cannot write for the guarantee to be complete.\n */\nexport function writeWithoutFollowingLinks(path: string, contents: string): void {\n\tconst descriptor = openSync(\n\t\tpath,\n\t\tconstants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW,\n\t\t0o600,\n\t);\n\ttry {\n\t\twriteFileSync(descriptor, contents);\n\t} finally {\n\t\tcloseSync(descriptor);\n\t}\n}\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\twriteWithoutFollowingLinks(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"]}