@skanl/brambo-sandbox-local 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SKANL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cgroup.d.ts

@@ -0,0 +1,19 @@
+export interface CgroupFilesystem {
+    readFile(path: string): Promise<string>;
+    mkdir(path: string): Promise<void>;
+    writeFile(path: string, value: string): Promise<void>;
+    rm(path: string): Promise<void>;
+}
+export interface CgroupSession {
+    /** Whether this session can place a child in the cgroup before it executes. */
+    readonly containsStartup: boolean;
+    attach(pid: number | undefined): Promise<void>;
+    teardown(): Promise<void>;
+}
+export declare function detectCgroupV2(filesystem?: CgroupFilesystem, root?: string): Promise<boolean>;
+export declare function createCgroupSession(filesystem?: CgroupFilesystem, root?: string, limits?: {
+    readonly memoryBytes?: number;
+    readonly processCount?: number;
+    readonly cpuQuotaMicros?: number;
+    readonly cpuPeriodMicros?: number;
+}): Promise<CgroupSession>;

package/dist/cgroup.js

@@ -0,0 +1,74 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { BRAMBO_ERROR_CODES, BramboError } from '@skanl/brambo-contracts';
+const nativeFilesystem = { readFile: (path) => readFile(path, 'utf8'), mkdir: (path) => mkdir(path), writeFile: (path, value) => writeFile(path, value), rm: (path) => rm(path, { recursive: true, force: true }) };
+function unavailable(message, cause) {
+    return new BramboError(BRAMBO_ERROR_CODES.sandboxUnavailable, message, { cause });
+}
+export async function detectCgroupV2(filesystem = nativeFilesystem, root = '/sys/fs/cgroup') {
+    try {
+        const controllers = (await filesystem.readFile(`${root}/cgroup.controllers`)).split(/\s+/).filter(Boolean);
+        return controllers.includes('memory') && controllers.includes('pids');
+    }
+    catch {
+        return false;
+    }
+}
+export async function createCgroupSession(filesystem = nativeFilesystem, root = '/sys/fs/cgroup', limits = {}) {
+    try {
+        const controllers = (await filesystem.readFile(`${root}/cgroup.controllers`)).split(/\s+/).filter(Boolean);
+        if (limits.memoryBytes !== undefined && !controllers.includes('memory'))
+            throw new Error('cgroup v2 memory controller is unavailable');
+        if (limits.processCount !== undefined && !controllers.includes('pids'))
+            throw new Error('cgroup v2 pids controller is unavailable');
+        if (limits.cpuQuotaMicros !== undefined && !controllers.includes('cpu'))
+            throw new Error('cgroup v2 cpu controller is unavailable');
+        if (limits.cpuQuotaMicros !== undefined && limits.cpuPeriodMicros === undefined)
+            throw new Error('cgroup v2 CPU quota requires a period');
+        if (limits.cpuQuotaMicros === undefined && limits.cpuPeriodMicros !== undefined)
+            throw new Error('cgroup v2 CPU period requires a quota');
+        const path = `${root}/brambo-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        await filesystem.mkdir(path);
+        try {
+            if (limits.memoryBytes !== undefined)
+                await filesystem.writeFile(`${path}/memory.max`, String(limits.memoryBytes));
+            if (limits.processCount !== undefined)
+                await filesystem.writeFile(`${path}/pids.max`, String(limits.processCount));
+            if (limits.cpuQuotaMicros !== undefined && limits.cpuPeriodMicros !== undefined) {
+                await filesystem.writeFile(`${path}/cpu.max`, `${limits.cpuQuotaMicros} ${limits.cpuPeriodMicros}`);
+            }
+        }
+        catch (error) {
+            await filesystem.rm(path).catch(() => undefined);
+            throw error;
+        }
+        return {
+            // Writing a PID after node:child_process.spawn has returned leaves an
+            // unbounded execution window. This direct cgroup-v2 implementation has no
+            // pre-exec hook, so callers must refuse resource-limited execution.
+            containsStartup: false,
+            async attach(pid) {
+                try {
+                    if (pid === undefined)
+                        throw new Error('sandbox child has no pid for cgroup attachment');
+                    await filesystem.writeFile(`${path}/cgroup.procs`, String(pid));
+                }
+                catch (error) {
+                    throw unavailable('sandbox cgroup attachment failed', error);
+                }
+            },
+            async teardown() {
+                try {
+                    await filesystem.rm(path);
+                }
+                catch (error) {
+                    throw unavailable('sandbox cgroup teardown failed', error);
+                }
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof BramboError)
+            throw error;
+        throw unavailable('sandbox cgroup setup failed', error);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { LocalSandboxProvider, LocalSandboxProviderOptions } from './shared.ts';
+export type { LocalDiscovery, LocalPlatform, LocalSandboxProvider, LocalSandboxProviderOptions } from './shared.ts';
+export { createLinuxSandboxProvider } from './linux.ts';
+export { createMacosSandboxProvider } from './macos.ts';
+export { createWindowsSandboxProvider } from './windows.ts';
+/** Dispatches by process.platform unless an explicit platform is supplied for deterministic tests. */
+export declare function createLocalSandboxProvider(options?: LocalSandboxProviderOptions): Promise<LocalSandboxProvider>;

package/dist/index.js

@@ -0,0 +1,15 @@
+import { createLinuxSandboxProvider } from './linux.js';
+import { createMacosSandboxProvider } from './macos.js';
+import { createWindowsSandboxProvider } from './windows.js';
+export { createLinuxSandboxProvider } from './linux.js';
+export { createMacosSandboxProvider } from './macos.js';
+export { createWindowsSandboxProvider } from './windows.js';
+/** Dispatches by process.platform unless an explicit platform is supplied for deterministic tests. */
+export async function createLocalSandboxProvider(options = {}) {
+    switch (options.platform ?? process.platform) {
+        case 'linux': return createLinuxSandboxProvider(options);
+        case 'darwin': return createMacosSandboxProvider(options);
+        case 'win32': return createWindowsSandboxProvider(options);
+        default: throw new Error(`local sandbox provider is unavailable on '${options.platform ?? process.platform}'`);
+    }
+}

package/dist/linux.d.ts

@@ -0,0 +1,9 @@
+import type { SandboxExecutionRequest } from '@skanl/brambo-contracts';
+import type { LocalSandboxAuditCallback, LocalSandboxProvider, LocalSandboxProviderOptions } from './shared.ts';
+export type LinuxSandboxProviderOptions = LocalSandboxProviderOptions & {
+    readonly audit?: LocalSandboxAuditCallback;
+};
+/** Builds only bwrap tokens. The target argv is appended after `--` without shell interpretation. */
+export declare function buildBubblewrapArgv(request: SandboxExecutionRequest): readonly [string, ...string[]];
+export declare function buildPrlimitArgv(request: SandboxExecutionRequest, baseArgv: readonly [string, ...string[]]): readonly [string, ...string[]];
+export declare function createLinuxSandboxProvider(options: LinuxSandboxProviderOptions): Promise<LocalSandboxProvider>;

package/dist/linux.js

@@ -0,0 +1,88 @@
+import { spawn } from 'node:child_process';
+import { createProvider, DEFAULT_TIMEOUT_MS, probe } from './shared.js';
+import { createCgroupSession, detectCgroupV2 } from './cgroup.js';
+const RUNTIME_DIRECTORIES = ['/usr', '/bin', '/lib', '/lib64', '/etc'];
+function directoriesToCreate(path) {
+    const segments = path.split('/').filter(Boolean);
+    return segments.map((_, index) => `/${segments.slice(0, index + 1).join('/')}`);
+}
+/** Builds only bwrap tokens. The target argv is appended after `--` without shell interpretation. */
+export function buildBubblewrapArgv(request) {
+    const argv = [
+        'bwrap', '--die-with-parent', '--new-session', '--unshare-user', '--unshare-pid',
+        ...(request.policy.networkMode === 'unrestricted' ? [] : ['--unshare-net']), '--clearenv',
+        '--tmpfs', '/', '--proc', '/proc', '--dev', '/dev',
+        '--dir', '/tmp', '--tmpfs', '/tmp',
+    ];
+    for (const directory of RUNTIME_DIRECTORIES)
+        argv.push('--dir', directory, '--ro-bind', directory, directory);
+    for (const directory of directoriesToCreate(request.policy.workspaceRoot)) {
+        if (!RUNTIME_DIRECTORIES.includes(directory) && directory !== '/tmp')
+            argv.push('--dir', directory);
+    }
+    argv.push(request.policy.mode === 'workspace-write' ? '--bind' : '--ro-bind', request.policy.workspaceRoot, request.policy.workspaceRoot);
+    for (const directory of directoriesToCreate(request.cwd)) {
+        if (directory !== request.policy.workspaceRoot)
+            argv.push('--dir', directory);
+    }
+    argv.push('--chdir', request.cwd);
+    for (const [key, value] of Object.entries(request.environment)) {
+        if (!/(?:token|secret|password|credential|api[_-]?key|authorization|cookie)/i.test(key))
+            argv.push('--setenv', key, value);
+    }
+    argv.push('--', ...request.argv);
+    return argv;
+}
+async function functionalBubblewrap() {
+    const argv = buildBubblewrapArgv({
+        argv: ['/bin/true'], cwd: '/tmp', environment: {},
+        policy: { version: 1, mode: 'read-only', workspaceRoot: '/tmp', requiredCapabilities: { filesystem: 'full' } },
+    });
+    return new Promise((resolve) => {
+        const child = spawn(argv[0], argv.slice(1), { shell: false, stdio: 'ignore', windowsHide: true });
+        const timer = setTimeout(() => child.kill('SIGKILL'), 3_000);
+        child.once('error', () => { clearTimeout(timer); resolve(false); });
+        child.once('close', (code) => { clearTimeout(timer); resolve(code === 0); });
+    });
+}
+async function functionalPrlimit(options) {
+    const argv = ['/usr/bin/prlimit', '--version'];
+    if (options.inspect !== undefined)
+        return options.inspect(argv);
+    return new Promise((resolve) => {
+        const child = spawn(argv[0], [argv[1]], { shell: false, stdio: 'ignore', windowsHide: true });
+        const timer = setTimeout(() => { child.kill('SIGKILL'); resolve(false); }, 3_000);
+        child.once('error', () => { clearTimeout(timer); resolve(false); });
+        child.once('close', (code) => { clearTimeout(timer); resolve(code === 0); });
+    });
+}
+export function buildPrlimitArgv(request, baseArgv) {
+    const fileSizeBytes = request.policy.resourceLimits?.fileSizeBytes;
+    if (fileSizeBytes === undefined)
+        return baseArgv;
+    return ['/usr/bin/prlimit', `--fsize=${fileSizeBytes}`, '--', ...baseArgv];
+}
+export async function createLinuxSandboxProvider(options) {
+    const isLinux = (options.platform ?? process.platform) === 'linux';
+    const bubblewrap = isLinux && await functionalBubblewrap();
+    const prlimit = isLinux && await functionalPrlimit(options);
+    const landlock = isLinux && (await probe(options, ['landlock', '--version']));
+    const cgroup = isLinux && await detectCgroupV2(options.cgroupFilesystem, options.cgroupRoot);
+    return createProvider('local-linux', { bubblewrap, landlock, cgroup, seatbelt: false, windowsSandboxBroker: false, jobObjectHelper: false }, bubblewrap ? 'full' : 'none', options.timeoutMs ?? DEFAULT_TIMEOUT_MS, (request) => buildPrlimitArgv(request, bubblewrap ? buildBubblewrapArgv(request) : request.argv), options.runner, options.audit, {
+        network: bubblewrap ? 'full' : 'none',
+        process: bubblewrap ? 'full' : 'none',
+        resources: cgroup ? 'full' : 'none',
+    }, async (policy) => {
+        const limits = policy.resourceLimits;
+        if (limits === undefined || (limits.memoryBytes === undefined &&
+            limits.processCount === undefined &&
+            limits.cpuQuotaMicros === undefined &&
+            limits.cpuPeriodMicros === undefined))
+            return undefined;
+        if (!cgroup)
+            throw new Error(limits.memoryBytes !== undefined || limits.processCount !== undefined
+                ? 'requested resource limits require cgroup v2 memory/pids enforcement'
+                : 'requested CPU limits require cgroup v2 CPU enforcement');
+        return createCgroupSession(options.cgroupFilesystem, options.cgroupRoot, limits);
+    }, prlimit ? ['fileSizeBytes'] : [], bubblewrap ? ['unrestricted'] : []);
+}

package/dist/macos.d.ts

@@ -0,0 +1,9 @@
+import type { SandboxExecutionRequest } from '@skanl/brambo-contracts';
+import type { LocalSandboxAuditCallback, LocalSandboxProvider, LocalSandboxProviderOptions } from './shared.ts';
+type MacosSandboxProviderOptions = LocalSandboxProviderOptions & {
+    readonly audit?: LocalSandboxAuditCallback;
+};
+/** Builds a Seatbelt profile and exact sandbox-exec argv; the target command is never interpreted by a shell. */
+export declare function buildSeatbeltArgv(request: SandboxExecutionRequest): readonly [string, ...string[]];
+export declare function createMacosSandboxProvider(options: MacosSandboxProviderOptions): Promise<LocalSandboxProvider>;
+export {};

package/dist/macos.js

@@ -0,0 +1,79 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createProvider, DEFAULT_TIMEOUT_MS, probe } from './shared.js';
+const SYSTEM_READ_PATHS = ['/System', '/usr', '/bin', '/sbin', '/Library', '/private/etc', '/opt/homebrew'];
+const SENSITIVE_ENVIRONMENT = /(?:token|secret|password|credential|api[_-]?key|authorization|cookie)/i;
+const ENVIRONMENT_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function quoted(value) {
+    return JSON.stringify(value);
+}
+function safeEnvironment(environment) {
+    return Object.entries(environment)
+        .filter(([key]) => ENVIRONMENT_KEY.test(key) && !SENSITIVE_ENVIRONMENT.test(key))
+        .map(([key, value]) => `${key}=${value}`);
+}
+/** Builds a Seatbelt profile and exact sandbox-exec argv; the target command is never interpreted by a shell. */
+export function buildSeatbeltArgv(request) {
+    const workspace = quoted(request.policy.workspaceRoot);
+    const profile = [
+        '(version 1)',
+        '(deny default)',
+        '(import "system.sb")',
+        '(deny network*)',
+        '(allow process-exec)',
+        '(allow process-fork)',
+        '(allow signal (target same-sandbox))',
+        '(allow sysctl-read)',
+        '(allow mach-lookup)',
+        '(allow file-read-metadata)',
+        ...SYSTEM_READ_PATHS.map((path) => `(allow file-read* (subpath ${quoted(path)}))`),
+        '(allow file-read* (literal "/dev/null"))',
+        '(allow file-read* (literal "/dev/urandom"))',
+        `(allow file-read* (subpath ${workspace}))`,
+        ...(request.policy.mode === 'workspace-write' ? [`(allow file-write* (subpath ${workspace}))`] : []),
+    ].join('\n');
+    return [
+        'sandbox-exec', '-p', profile, '/usr/bin/env', '-i', 'PATH=/usr/bin:/bin:/usr/sbin:/sbin',
+        ...safeEnvironment(request.environment), '--', ...request.argv,
+    ];
+}
+function run(argv) {
+    return new Promise((resolve) => {
+        const child = spawn(argv[0], argv.slice(1), { shell: false, stdio: 'ignore', windowsHide: true });
+        const timer = setTimeout(() => child.kill('SIGKILL'), 3_000);
+        child.once('error', () => { clearTimeout(timer); resolve(false); });
+        child.once('close', (code) => { clearTimeout(timer); resolve(code === 0); });
+    });
+}
+async function functionalSeatbelt() {
+    const workspace = await mkdtemp(join(tmpdir(), 'brambo-seatbelt-'));
+    try {
+        const writableFile = join(workspace, 'writable');
+        const deniedFile = join(workspace, 'denied');
+        const writable = await run(buildSeatbeltArgv({
+            argv: ['/usr/bin/touch', writableFile], cwd: workspace, environment: {},
+            policy: { version: 1, mode: 'workspace-write', workspaceRoot: workspace, requiredCapabilities: { filesystem: 'full' } },
+        }));
+        if (!writable || !existsSync(writableFile))
+            return false;
+        const readOnly = await run(buildSeatbeltArgv({
+            argv: ['/usr/bin/touch', deniedFile], cwd: workspace, environment: {},
+            policy: { version: 1, mode: 'read-only', workspaceRoot: workspace, requiredCapabilities: { filesystem: 'full' } },
+        }));
+        return !readOnly && !existsSync(deniedFile);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await rm(workspace, { recursive: true, force: true });
+    }
+}
+export async function createMacosSandboxProvider(options) {
+    const available = process.platform === 'darwin' && await probe(options, ['sandbox-exec', '-h']);
+    const seatbelt = available && await functionalSeatbelt();
+    return createProvider('local-macos', { bubblewrap: false, landlock: false, cgroup: false, seatbelt, windowsSandboxBroker: false, jobObjectHelper: false }, seatbelt ? 'full' : 'none', options.timeoutMs ?? DEFAULT_TIMEOUT_MS, seatbelt ? buildSeatbeltArgv : undefined, undefined, options.audit);
+}

package/dist/shared.d.ts

@@ -0,0 +1,31 @@
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+import type { SandboxCapabilityFacts, SandboxAuditEvent, SandboxControlEvidence, SandboxExecutionRequest, SandboxNetworkMode, SandboxProvider, SandboxSessionRequest } from '@skanl/brambo-contracts';
+import type { CgroupSession, CgroupFilesystem } from './cgroup.ts';
+declare const DEFAULT_TIMEOUT_MS: number;
+export type LocalPlatform = 'linux' | 'darwin' | 'win32';
+export interface LocalSandboxProviderOptions {
+    readonly platform?: NodeJS.Platform;
+    /** Test seam for executable probes. It never establishes full enforcement. */
+    readonly inspect?: (argv: readonly [string, ...string[]]) => Promise<boolean>;
+    readonly timeoutMs?: number;
+    readonly runner?: LocalSandboxRunner;
+    readonly cgroupFilesystem?: CgroupFilesystem;
+    readonly cgroupRoot?: string;
+}
+export interface LocalDiscovery {
+    readonly bubblewrap: boolean;
+    readonly landlock: boolean;
+    readonly cgroup: boolean;
+    readonly seatbelt: boolean;
+    readonly windowsSandboxBroker: boolean;
+    readonly jobObjectHelper: boolean;
+}
+export interface LocalSandboxProvider extends SandboxProvider {
+    readonly discovery: LocalDiscovery;
+}
+export type LocalSandboxRunner = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+export type LocalSandboxAuditCallback = (event: SandboxAuditEvent) => void | PromiseLike<void>;
+export declare function containedWorkspace(cwd: string, workspaceRoot: string): Promise<boolean>;
+export declare function createProvider(id: string, discovery: LocalDiscovery, filesystem: SandboxControlEvidence, timeoutMs: number, buildArgv?: (request: SandboxExecutionRequest) => readonly [string, ...string[]], runner?: LocalSandboxRunner, audit?: LocalSandboxAuditCallback, controlEvidence?: Partial<SandboxCapabilityFacts['controls']>, cgroupFactory?: (policy: SandboxSessionRequest['policy']) => Promise<CgroupSession | undefined>, supportedResourceLimits?: readonly ('fileSizeBytes')[], supportedNetworkModes?: readonly SandboxNetworkMode[]): LocalSandboxProvider;
+export declare function probe(options: LocalSandboxProviderOptions, argv: readonly [string, ...string[]]): Promise<boolean>;
+export { DEFAULT_TIMEOUT_MS };

package/dist/shared.js

@@ -0,0 +1,657 @@
+import { constants, existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { lstat, open, realpath, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { delimiter, isAbsolute, relative, resolve, sep } from 'node:path';
+import { BRAMBO_ERROR_CODES, BramboError, SANDBOX_ERROR_CODES, validateSandboxCapabilities, validateSandboxAuditEvent, validateSandboxExecutionRequest, validateSandboxPolicy, validateSandboxSnapshot, } from '@skanl/brambo-contracts';
+const OUTPUT_CAP_BYTES = 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const SENSITIVE_ENVIRONMENT = /(?:token|secret|password|credential|api[_-]?key|authorization|cookie)/i;
+function abortedStdio(message) {
+    return new BramboError(SANDBOX_ERROR_CODES.aborted, message);
+}
+function unavailableStdio(message, cause) {
+    return new BramboError(SANDBOX_ERROR_CODES.unavailable, message, cause === undefined ? {} : { cause });
+}
+function controls(value) {
+    return Object.freeze({ filesystem: value, network: 'none', process: 'none', resources: 'none' });
+}
+function unavailable(enforcement, message) {
+    return {
+        status: 'unavailable', stdout: '', stderr: '', enforcement,
+        error: { code: SANDBOX_ERROR_CODES.unavailable, message },
+    };
+}
+function scrubEnvironment(environment) {
+    const scrubbed = Object.fromEntries(Object.entries(environment).filter(([key]) => !SENSITIVE_ENVIRONMENT.test(key)));
+    // Wrapper lookup must not use a PATH supplied by the execution caller.
+    scrubbed.PATH = process.env['PATH'] ?? (process.platform === 'win32' ? '' : '/usr/bin:/bin');
+    return scrubbed;
+}
+function hasUnsupportedResourceLimits(policy, supportsFileSize) {
+    const limits = policy.resourceLimits;
+    return limits?.fileSizeBytes !== undefined && !supportsFileSize;
+}
+function hasUnenforcedResourceLimits(policy, cgroup) {
+    const limits = policy.resourceLimits;
+    return cgroup === undefined && (limits?.memoryBytes !== undefined || limits?.processCount !== undefined);
+}
+function cannotContainStartup(policy, cgroup) {
+    const limits = policy.resourceLimits;
+    return cgroup !== undefined && !cgroup.containsStartup && (limits?.memoryBytes !== undefined || limits?.processCount !== undefined);
+}
+export async function containedWorkspace(cwd, workspaceRoot) {
+    try {
+        const [physicalCwd, physicalRoot] = await Promise.all([realpath(cwd), realpath(workspaceRoot)]);
+        const path = relative(physicalRoot, physicalCwd);
+        return path === '' || (!isAbsolute(path) && path !== '..' && !path.startsWith(`..${sep}`));
+    }
+    catch {
+        return false;
+    }
+}
+function terminate(child) {
+    if (child.pid !== undefined && process.platform !== 'win32') {
+        try {
+            return process.kill(-child.pid, 'SIGKILL');
+        }
+        catch { /* fall through to direct child termination */ }
+    }
+    return child.kill('SIGKILL');
+}
+async function runExact(request, policy, enforcement, wallTimeMs, outputBytes, cleanupTimeoutMs, argv, runner, cgroup, isActive, register, invalidate, recordTeardownFailure) {
+    if (request.signal?.aborted)
+        return { status: 'aborted', stdout: '', stderr: '', enforcement, error: { code: SANDBOX_ERROR_CODES.aborted, message: 'sandbox process was aborted before spawn' } };
+    if (!(await containedWorkspace(request.cwd, policy.workspaceRoot)))
+        return unavailable(enforcement, 'sandbox cwd cannot be physically proven inside workspace');
+    if (!isActive())
+        return { status: 'aborted', stdout: '', stderr: '', enforcement, error: { code: SANDBOX_ERROR_CODES.aborted, message: 'sandbox session was disposed before spawn' } };
+    if (cannotContainStartup(policy, cgroup))
+        return unavailable(enforcement, 'sandbox provider cannot contain cgroup-limited process startup before execution');
+    return new Promise((resolveResult) => {
+        const [command, ...args] = argv;
+        const child = runner(command, args, {
+            cwd: request.cwd,
+            env: scrubEnvironment(request.environment),
+            shell: false,
+            detached: process.platform !== 'win32',
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let status;
+        let disposalTimer;
+        let attachmentComplete = cgroup === undefined;
+        let attachmentError;
+        let childClosed = false;
+        let childExitCode = null;
+        const cleanup = new Promise((resolveCleanup, rejectCleanup) => {
+            child.once('close', () => resolveCleanup());
+            child.once('error', rejectCleanup);
+        });
+        const abortForDisposal = () => {
+            status = 'aborted';
+            try {
+                if (terminate(child)) {
+                    if (!settled)
+                        disposalTimer = setTimeout(() => finish({ status: 'aborted', stdout, stderr, enforcement, error: { code: SANDBOX_ERROR_CODES.aborted, message: 'sandbox process cleanup timed out during disposal' } }), cleanupTimeoutMs);
+                    return;
+                }
+            }
+            catch (error) {
+                finish({ status, stdout, stderr, enforcement, error: { code: SANDBOX_ERROR_CODES.aborted, message: 'sandbox process could not be terminated during disposal' } });
+                throw error;
+            }
+            finish({ status, stdout, stderr, enforcement, error: { code: SANDBOX_ERROR_CODES.aborted, message: 'sandbox process could not be terminated during disposal' } });
+            throw new Error('child termination was not accepted');
+        };
+        register(child, cleanup, abortForDisposal);
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (disposalTimer !== undefined)
+                clearTimeout(disposalTimer);
+            request.signal?.removeEventListener('abort', abort);
+            resolveResult(result);
+        };
+        const truncate = (chunk, target) => {
+            const next = target === 'stdout' ? stdout + chunk.toString('utf8') : stderr + chunk.toString('utf8');
+            if (Buffer.byteLength(next) > outputBytes) {
+                status = 'failed';
+                terminate(child);
+                return;
+            }
+            if (target === 'stdout')
+                stdout = next;
+            else
+                stderr = next;
+        };
+        const abort = () => { status = 'aborted'; terminate(child); };
+        const timer = setTimeout(() => { status = 'timed-out'; terminate(child); }, wallTimeMs);
+        request.signal?.addEventListener('abort', abort, { once: true });
+        child.stdout?.on('data', (chunk) => truncate(chunk, 'stdout'));
+        child.stderr?.on('data', (chunk) => truncate(chunk, 'stderr'));
+        child.on('error', (error) => finish({ status: 'failed', stdout, stderr, enforcement, error: { code: SANDBOX_ERROR_CODES.runnerFailed, message: error.message } }));
+        child.on('close', (exitCode) => {
+            childClosed = true;
+            childExitCode = exitCode;
+            if (!attachmentComplete)
+                return;
+            finishAfterAttachment();
+        });
+        const finishAfterAttachment = () => {
+            if (attachmentError !== undefined)
+                return;
+            const exitCode = childExitCode;
+            if (status === 'timed-out')
+                return finish({ status, stdout, stderr, enforcement, error: { code: SANDBOX_ERROR_CODES.timedOut, message: 'sandbox process exceeded its timeout' } });
+            if (status === 'aborted')
+                return finish({ status, stdout, stderr, enforcement, error: { code: SANDBOX_ERROR_CODES.aborted, message: 'sandbox process was aborted' } });
+            if (status === 'failed')
+                return finish({ status, stdout, stderr, enforcement, error: { code: SANDBOX_ERROR_CODES.runnerFailed, message: 'sandbox process exceeded its output cap' } });
+            if (exitCode === 0)
+                return finish({ status: 'ok', stdout, stderr, exitCode, enforcement });
+            return finish({ status: 'failed', stdout, stderr, enforcement, error: { code: SANDBOX_ERROR_CODES.runnerFailed, message: `sandbox process exited with code ${exitCode ?? 'unknown'}` } });
+        };
+        void cgroup?.attach(child.pid).then(() => {
+            attachmentComplete = true;
+            if (childClosed)
+                finishAfterAttachment();
+        }).catch((error) => {
+            attachmentError = error;
+            let terminated = false;
+            try {
+                terminated = terminate(child);
+            }
+            catch (terminationError) {
+                recordTeardownFailure(new AggregateError([error, terminationError], 'cgroup attachment and child termination both failed'));
+            }
+            if (!terminated) {
+                recordTeardownFailure(error);
+                finish({ status: 'failed', stdout, stderr, enforcement, error: { code: SANDBOX_ERROR_CODES.runnerFailed, message: 'sandbox cgroup attachment failed and the child could not be terminated' } });
+                return;
+            }
+            invalidate(error);
+            finish(unavailable(enforcement, `sandbox cgroup attachment failed: ${error instanceof Error ? error.message : String(error)}`));
+        });
+    });
+}
+class Session {
+    #disposed = false;
+    #invalidated = false;
+    #teardownFailure;
+    #disposePromise;
+    id;
+    policy;
+    enforcement;
+    timeoutMs;
+    buildArgv;
+    runner;
+    snapshots;
+    active = new Map();
+    cleanups = new Map();
+    snapshotContent = new Map();
+    constructor(id, policy, enforcement, timeoutMs, buildArgv, runner, audit, cgroup, supportsFileSize, snapshots = []) {
+        this.id = id;
+        this.policy = policy;
+        this.enforcement = enforcement;
+        this.timeoutMs = timeoutMs;
+        this.buildArgv = buildArgv;
+        this.runner = runner;
+        this.cgroup = cgroup;
+        this.supportsFileSize = supportsFileSize;
+        this.audit = audit;
+        this.snapshots = Object.freeze(snapshots.map((snapshot) => Object.freeze({ ...snapshot })));
+    }
+    audit;
+    cgroup;
+    supportsFileSize;
+    emitAudit(kind) {
+        if (this.policy.mode !== 'danger-full-access' || this.audit === undefined)
+            return;
+        try {
+            const event = validateSandboxAuditEvent({
+                providerId: this.enforcement.providerId,
+                sessionId: this.id,
+                mode: 'danger-full-access',
+                timestamp: new Date().toISOString(),
+                kind,
+            });
+            void Promise.resolve(this.audit(event)).catch(() => undefined);
+        }
+        catch {
+            // Audit delivery is best effort and must not affect sandbox behavior.
+        }
+    }
+    async execute(value) {
+        if (this.#disposed || this.#invalidated)
+            return unavailable(this.enforcement, 'sandbox session is unavailable');
+        const request = validateSandboxExecutionRequest(value);
+        if (!samePolicy(this.policy, request.policy)) {
+            throw new BramboError(BRAMBO_ERROR_CODES.sandboxRequestInvalid, `sandbox execution policy does not match session '${this.id}' policy`);
+        }
+        validateSandboxCapabilities(this.policy, this.enforcement);
+        if (this.buildArgv === undefined && this.policy.mode !== 'danger-full-access')
+            return unavailable(this.enforcement, 'safe sandbox mode has no verified execution backend');
+        if (hasUnsupportedResourceLimits(this.policy, this.supportsFileSize))
+            return unavailable(this.enforcement, 'sandbox provider cannot prove all requested resource limits');
+        if (hasUnenforcedResourceLimits(this.policy, this.cgroup))
+            return unavailable(this.enforcement, 'sandbox provider cannot prove requested memory/process limits');
+        this.emitAudit('execution-started');
+        try {
+            const limits = this.policy.resourceLimits;
+            return await runExact(request, this.policy, this.enforcement, limits?.wallTimeMs ?? this.timeoutMs, limits?.outputBytes ?? OUTPUT_CAP_BYTES, this.timeoutMs, this.buildArgv?.(request) ?? request.argv, this.runner, this.cgroup, () => !this.#disposed && !this.#invalidated, (child, cleanup, abort) => this.registerChild(child, cleanup, abort), (error) => this.invalidate(error), (error) => this.recordTeardownFailure(error));
+        }
+        finally {
+            this.emitAudit('execution-completed');
+        }
+    }
+    async openStdio(value) {
+        if (this.#disposed || this.#invalidated)
+            throw new BramboError(BRAMBO_ERROR_CODES.sandboxUnavailable, 'sandbox session is unavailable');
+        const request = validateSandboxExecutionRequest(value);
+        if (!samePolicy(this.policy, request.policy))
+            throw new BramboError(BRAMBO_ERROR_CODES.sandboxRequestInvalid, `sandbox execution policy does not match session '${this.id}' policy`);
+        validateSandboxCapabilities(this.policy, this.enforcement);
+        if (request.signal?.aborted)
+            throw new BramboError(SANDBOX_ERROR_CODES.aborted, 'stdio sandbox process was aborted before spawn');
+        if (this.buildArgv === undefined && this.policy.mode !== 'danger-full-access')
+            throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'safe sandbox mode has no verified execution backend');
+        if (hasUnsupportedResourceLimits(this.policy, this.supportsFileSize))
+            throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'sandbox provider cannot prove all requested resource limits');
+        if (hasUnenforcedResourceLimits(this.policy, this.cgroup))
+            throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'sandbox provider cannot prove requested memory/process limits');
+        if (cannotContainStartup(this.policy, this.cgroup))
+            throw unavailableStdio('sandbox provider cannot contain cgroup-limited process startup before execution');
+        if (!(await containedWorkspace(request.cwd, this.policy.workspaceRoot)))
+            throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'sandbox cwd cannot be physically proven inside workspace');
+        if (request.signal?.aborted)
+            throw abortedStdio('stdio process was aborted before spawn');
+        if (!(await containedWorkspace(request.cwd, this.policy.workspaceRoot)))
+            throw unavailableStdio('sandbox cwd cannot be physically proven inside workspace');
+        this.emitAudit('execution-started');
+        try {
+            const [command, ...args] = this.buildArgv?.(request) ?? request.argv;
+            const child = this.runner(command, args, { cwd: request.cwd, env: scrubEnvironment(request.environment), shell: false, detached: process.platform !== 'win32', windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+            let buffer = '';
+            const frames = [];
+            const waiters = [];
+            const sendWaiters = new Set();
+            let processClosed = false;
+            let terminalError;
+            let outputBytes = 0;
+            const timeout = setTimeout(() => stop(new BramboError(SANDBOX_ERROR_CODES.timedOut, 'stdio process exceeded its timeout')), this.policy.resourceLimits?.wallTimeMs ?? this.timeoutMs);
+            const rejectWaiters = (error) => {
+                terminalError ??= error;
+                while (waiters.length > 0) {
+                    const waiter = waiters.shift();
+                    waiter.signal?.removeEventListener('abort', waiter.abort);
+                    waiter.reject(error);
+                }
+                for (const reject of sendWaiters)
+                    reject(error);
+                sendWaiters.clear();
+            };
+            const stop = (error) => {
+                rejectWaiters(error);
+                if (!processClosed && !child.killed && !terminate(child)) {
+                    this.invalidate(new Error('child termination was not accepted'));
+                }
+            };
+            child.stdout?.setEncoding('utf8');
+            child.stdout?.on('data', (chunk) => {
+                outputBytes += Buffer.byteLength(chunk);
+                if (outputBytes > Math.min(this.policy.resourceLimits?.outputBytes ?? OUTPUT_CAP_BYTES, OUTPUT_CAP_BYTES)) {
+                    stop(new BramboError(SANDBOX_ERROR_CODES.runnerFailed, 'stdio process exceeded its output cap'));
+                    return;
+                }
+                buffer += chunk;
+                let newline = buffer.indexOf('\n');
+                while (newline >= 0) {
+                    const frame = buffer.slice(0, newline);
+                    buffer = buffer.slice(newline + 1);
+                    const waiter = waiters.shift();
+                    if (waiter) {
+                        waiter.signal?.removeEventListener('abort', waiter.abort);
+                        waiter.resolve(frame);
+                    }
+                    else {
+                        frames.push(frame);
+                    }
+                    newline = buffer.indexOf('\n');
+                }
+            });
+            // Always consume stderr so a noisy child cannot block on a full pipe.
+            child.stderr?.on('data', (chunk) => {
+                outputBytes += Buffer.byteLength(chunk.toString());
+                if (outputBytes > Math.min(this.policy.resourceLimits?.outputBytes ?? OUTPUT_CAP_BYTES, OUTPUT_CAP_BYTES)) {
+                    stop(new BramboError(SANDBOX_ERROR_CODES.runnerFailed, 'stdio process exceeded its output cap'));
+                }
+            });
+            const cleanup = new Promise((resolveCleanup, rejectCleanup) => {
+                child.once('close', () => {
+                    clearTimeout(timeout);
+                    processClosed = true;
+                    rejectWaiters(terminalError ?? unavailableStdio('stdio process closed before a frame was received'));
+                    resolveCleanup();
+                });
+                child.once('error', (error) => {
+                    clearTimeout(timeout);
+                    processClosed = true;
+                    rejectWaiters(terminalError ?? unavailableStdio('stdio process failed before a frame was received'));
+                    rejectCleanup(error);
+                });
+            });
+            const abort = () => {
+                if (!processClosed && !child.killed && !terminate(child))
+                    throw new Error('child termination was not accepted');
+            };
+            this.registerChild(child, cleanup, abort);
+            try {
+                await this.cgroup?.attach(child.pid);
+            }
+            catch (error) {
+                let terminationError;
+                try {
+                    if (!terminate(child))
+                        terminationError = new Error('child termination was not accepted');
+                }
+                catch (cause) {
+                    terminationError = cause;
+                }
+                if (terminationError !== undefined) {
+                    const failure = new AggregateError([error, terminationError], 'stdio cgroup attachment and child termination both failed');
+                    this.recordTeardownFailure(failure);
+                    throw unavailableStdio('stdio cgroup attachment failed and child termination could not be verified', failure);
+                }
+                this.invalidate(error);
+                throw unavailableStdio('stdio cgroup attachment failed', error);
+            }
+            let closePromise;
+            const close = () => {
+                if (closePromise !== undefined)
+                    return closePromise;
+                closePromise = (async () => {
+                    let terminationError;
+                    try {
+                        abort();
+                    }
+                    catch (error) {
+                        terminationError = error;
+                        this.recordTeardownFailure(error);
+                    }
+                    try {
+                        await this.boundedCleanup(cleanup);
+                    }
+                    catch (error) {
+                        throw unavailableStdio('stdio process cleanup failed', error);
+                    }
+                    if (terminationError !== undefined)
+                        throw unavailableStdio('stdio process could not be terminated', terminationError);
+                })();
+                return closePromise;
+            };
+            return Object.freeze({
+                sendFrame: async (frame, signal) => {
+                    if (signal?.aborted)
+                        throw abortedStdio('stdio send was aborted');
+                    if (frame.includes('\n') || frame.includes('\r'))
+                        throw new BramboError(BRAMBO_ERROR_CODES.sandboxRequestInvalid, 'stdio frames cannot contain line breaks');
+                    const stdin = child.stdin;
+                    if (terminalError !== undefined)
+                        throw terminalError;
+                    if (stdin === null || processClosed || stdin.destroyed || stdin.writableEnded)
+                        throw unavailableStdio('stdio process input is unavailable');
+                    await new Promise((resolveSend, rejectSend) => {
+                        let settled = false;
+                        const finish = (error) => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            sendWaiters.delete(onClose);
+                            signal?.removeEventListener('abort', onAbort);
+                            stdin.removeListener('drain', onDrain);
+                            if (error === undefined)
+                                resolveSend();
+                            else
+                                rejectSend(error);
+                        };
+                        const onAbort = () => finish(abortedStdio('stdio send was aborted'));
+                        const onDrain = () => finish();
+                        const onClose = (error) => finish(error);
+                        sendWaiters.add(onClose);
+                        signal?.addEventListener('abort', onAbort, { once: true });
+                        try {
+                            if (signal?.aborted)
+                                return onAbort();
+                            if (stdin.write(`${frame}\n`))
+                                finish();
+                            else
+                                stdin.once('drain', onDrain);
+                        }
+                        catch (error) {
+                            finish(error);
+                        }
+                    });
+                },
+                receiveFrame: async (signal) => {
+                    if (signal?.aborted)
+                        throw abortedStdio('stdio receive was aborted');
+                    if (frames.length > 0)
+                        return frames.shift();
+                    if (processClosed)
+                        throw unavailableStdio('stdio process output is unavailable');
+                    if (terminalError !== undefined)
+                        throw terminalError;
+                    return new Promise((resolveFrame, rejectFrame) => {
+                        const waiter = {
+                            resolve: resolveFrame,
+                            reject: rejectFrame,
+                            abort: () => {
+                                const index = waiters.indexOf(waiter);
+                                if (index >= 0)
+                                    waiters.splice(index, 1);
+                                signal?.removeEventListener('abort', waiter.abort);
+                                rejectFrame(abortedStdio('stdio receive was aborted'));
+                            },
+                            signal,
+                        };
+                        signal?.addEventListener('abort', waiter.abort, { once: true });
+                        if (signal?.aborted)
+                            waiter.abort();
+                        else
+                            waiters.push(waiter);
+                    });
+                },
+                close,
+            });
+        }
+        finally {
+            this.emitAudit('execution-completed');
+        }
+    }
+    async snapshot(paths) {
+        if (this.#disposed || this.#invalidated)
+            throw new BramboError(BRAMBO_ERROR_CODES.sandboxUnavailable, 'sandbox session is unavailable');
+        const snapshots = [];
+        for (const path of paths) {
+            const absolute = resolve(this.policy.workspaceRoot, path);
+            if (!(await containedWorkspace(absolute, this.policy.workspaceRoot))) {
+                throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'snapshot path is outside the workspace');
+            }
+            let content;
+            let kind;
+            let directoryInfo;
+            try {
+                const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const current = await handle.stat();
+                    if (!current.isFile())
+                        throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'snapshot path is not a regular file');
+                    if (await realpath(absolute) !== absolute) {
+                        throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'snapshot path is symbolic link');
+                    }
+                    content = await handle.readFile();
+                    kind = 'file';
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch (error) {
+                if (error instanceof BramboError)
+                    throw error;
+                const info = await lstat(absolute);
+                if (!info.isDirectory() || info.isSymbolicLink()) {
+                    throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'snapshot path is not a regular file or directory');
+                }
+                directoryInfo = info;
+                kind = 'directory';
+            }
+            const digest = kind === 'file'
+                ? createHash('sha256').update(content).digest('hex')
+                : createHash('sha256').update(`${kind}:${directoryInfo.size}:${directoryInfo.mtimeMs}`).digest('hex');
+            snapshots.push(validateSandboxSnapshot({ version: 1, path, kind, digest }));
+            if (kind === 'file')
+                this.snapshotContent.set(digest, content);
+        }
+        return Object.freeze(snapshots);
+    }
+    async restore(snapshots) {
+        if (this.#disposed || this.#invalidated)
+            throw new BramboError(BRAMBO_ERROR_CODES.sandboxUnavailable, 'sandbox session is unavailable');
+        for (const snapshot of snapshots.map((entry) => validateSandboxSnapshot(entry))) {
+            if (snapshot.kind !== 'file')
+                throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'directory snapshot restore is unavailable');
+            const content = this.snapshotContent.get(snapshot.digest);
+            if (content === undefined)
+                throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'snapshot content is not owned by this session');
+            const absolute = resolve(this.policy.workspaceRoot, snapshot.path);
+            if (!(await containedWorkspace(absolute, this.policy.workspaceRoot)))
+                throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'snapshot restore path is outside the workspace');
+            await writeFile(absolute, content, { flag: 'w' });
+        }
+    }
+    dispose() {
+        if (this.#disposePromise !== undefined)
+            return this.#disposePromise;
+        this.#disposed = true;
+        const cleanups = [...this.active.entries()].map(([child, abort]) => {
+            try {
+                abort();
+            }
+            catch (error) {
+                this.recordTeardownFailure(error);
+            }
+            const cleanup = this.cleanups.get(child);
+            return cleanup === undefined
+                ? Promise.resolve()
+                : this.boundedCleanup(cleanup).catch((cleanupError) => {
+                    this.recordTeardownFailure(cleanupError);
+                    throw cleanupError;
+                });
+        });
+        this.#disposePromise = Promise.allSettled(cleanups).then(async (outcomes) => {
+            for (const outcome of outcomes) {
+                if (outcome.status === 'rejected')
+                    this.recordTeardownFailure(outcome.reason);
+            }
+            const cleanupFailure = this.#teardownFailure;
+            let cgroupFailure;
+            try {
+                await this.cgroup?.teardown();
+            }
+            catch (error) {
+                cgroupFailure = error;
+                this.recordTeardownFailure(error);
+            }
+            if (cleanupFailure !== undefined && cgroupFailure !== undefined)
+                throw new BramboError(BRAMBO_ERROR_CODES.sandboxUnavailable, `sandbox session '${this.id}' child cleanup and cgroup teardown outcomes are uncertain`, { cause: new AggregateError([cleanupFailure, cgroupFailure]) });
+            if (cleanupFailure !== undefined)
+                throw new BramboError(BRAMBO_ERROR_CODES.sandboxUnavailable, `sandbox session '${this.id}' teardown outcome is uncertain`, { cause: cleanupFailure });
+            if (cgroupFailure !== undefined)
+                throw new BramboError(BRAMBO_ERROR_CODES.sandboxUnavailable, `sandbox session '${this.id}' cgroup teardown outcome is uncertain`, { cause: cgroupFailure });
+        });
+        return this.#disposePromise;
+    }
+    boundedCleanup(cleanup) {
+        return new Promise((resolveCleanup, rejectCleanup) => {
+            const timer = setTimeout(() => rejectCleanup(new Error(`sandbox session '${this.id}' child cleanup timed out`)), this.timeoutMs);
+            void cleanup.then(() => { clearTimeout(timer); resolveCleanup(); }, (error) => { clearTimeout(timer); rejectCleanup(error); });
+        });
+    }
+    invalidate(error) {
+        this.#invalidated = true;
+        void error;
+    }
+    recordTeardownFailure(error) {
+        this.#invalidated = true;
+        this.#teardownFailure ??= error ?? new Error('unknown child cleanup failure');
+    }
+    registerChild(child, cleanup, abort) {
+        this.active.set(child, abort);
+        this.cleanups.set(child, cleanup);
+        void cleanup.then(() => this.removeChild(child), (error) => {
+            this.recordTeardownFailure(error);
+            this.removeChild(child);
+        });
+        if (this.#disposed)
+            terminate(child);
+    }
+    removeChild(child) {
+        this.active.delete(child);
+        this.cleanups.delete(child);
+    }
+}
+function samePolicy(left, right) {
+    if (left.version !== right.version ||
+        left.mode !== right.mode ||
+        left.workspaceRoot !== right.workspaceRoot ||
+        (left.networkMode ?? 'deny') !== (right.networkMode ?? 'deny') ||
+        left.allowDangerous !== right.allowDangerous) {
+        return false;
+    }
+    const leftEntries = Object.entries(left.requiredCapabilities).sort(([a], [b]) => a.localeCompare(b));
+    const rightEntries = Object.entries(right.requiredCapabilities).sort(([a], [b]) => a.localeCompare(b));
+    if (!(leftEntries.length === rightEntries.length && leftEntries.every(([key, value], index) => rightEntries[index]?.[0] === key && rightEntries[index]?.[1] === value)))
+        return false;
+    const leftLimits = Object.entries(left.resourceLimits ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    const rightLimits = Object.entries(right.resourceLimits ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    return leftLimits.length === rightLimits.length && leftLimits.every(([key, value], index) => rightLimits[index]?.[0] === key && rightLimits[index]?.[1] === value);
+}
+export function createProvider(id, discovery, filesystem, timeoutMs, buildArgv, runner = (command, args, options) => spawn(command, [...args], options), audit, controlEvidence = {}, cgroupFactory, supportedResourceLimits = [], supportedNetworkModes = []) {
+    const capabilities = Object.freeze({
+        version: 1,
+        providerId: id,
+        enforcement: filesystem === 'none' ? 'partial' : 'os',
+        controls: Object.freeze({ ...controls(filesystem), ...controlEvidence }),
+    });
+    let sessions = 0;
+    return Object.freeze({
+        id,
+        discovery: Object.freeze(discovery),
+        capabilities,
+        async createSession(value) {
+            const policy = validateSandboxPolicy(value.policy);
+            if (policy.networkMode !== undefined && policy.networkMode !== 'deny' && !supportedNetworkModes.includes(policy.networkMode)) {
+                throw new BramboError(BRAMBO_ERROR_CODES.sandboxCapabilityUnavailable, `local provider '${id}' cannot prove network mode '${policy.networkMode}'`);
+            }
+            value.snapshots.forEach(validateSandboxSnapshot);
+            validateSandboxCapabilities(policy, capabilities);
+            const cgroup = cgroupFactory === undefined ? undefined : await cgroupFactory(policy);
+            sessions += 1;
+            return new Session(`${id}-${sessions}`, policy, capabilities, timeoutMs, buildArgv, runner, audit, cgroup, supportedResourceLimits.includes('fileSizeBytes'), value.snapshots);
+        },
+    });
+}
+export async function probe(options, argv) {
+    if (options.inspect !== undefined)
+        return options.inspect(argv);
+    const executable = argv[0];
+    return executable !== undefined && (existsSync(executable) || process.env['PATH']?.split(delimiter).some((entry) => existsSync(resolve(entry, executable))) === true);
+}
+export { DEFAULT_TIMEOUT_MS };

package/dist/windows.d.ts

@@ -0,0 +1,6 @@
+import type { LocalSandboxAuditCallback, LocalSandboxProvider, LocalSandboxProviderOptions } from './shared.ts';
+type WindowsSandboxProviderOptions = LocalSandboxProviderOptions & {
+    readonly audit?: LocalSandboxAuditCallback;
+};
+export declare function createWindowsSandboxProvider(options: WindowsSandboxProviderOptions): Promise<LocalSandboxProvider>;
+export {};

package/dist/windows.js

@@ -0,0 +1,117 @@
+import { spawn } from 'node:child_process';
+import { BramboError, SANDBOX_ERROR_CODES, validateSandboxCapabilities, validateSandboxPolicy, validateSandboxSnapshot } from '@skanl/brambo-contracts';
+import { createProvider, DEFAULT_TIMEOUT_MS, probe } from './shared.js';
+const BROKER = 'brambo-windows-sandbox-broker';
+const SELF_TEST_TIMEOUT_MS = 10_000;
+function brokerCapabilities(available) {
+    return Object.freeze({
+        version: 1,
+        providerId: 'local-windows',
+        // A missing broker is not partial enforcement: this provider has no
+        // verified execution substrate and must fail closed.
+        enforcement: available ? 'os' : 'none',
+        controls: Object.freeze({
+            filesystem: available ? 'full' : 'none',
+            process: available ? 'full' : 'none',
+            network: available ? 'full' : 'none',
+            // The broker self-test does not prove resource quotas.
+            resources: available ? 'partial' : 'none',
+        }),
+    });
+}
+function brokerPolicy(policy) {
+    return Object.freeze({
+        ...policy,
+        requiredCapabilities: Object.freeze({ filesystem: 'full' }),
+    });
+}
+function withEnforcement(result, enforcement) {
+    return Object.freeze({ ...result, enforcement });
+}
+function unavailableSession(id, enforcement) {
+    const unavailable = () => Object.freeze({
+        status: 'unavailable',
+        stdout: '',
+        stderr: '',
+        enforcement,
+        error: { code: SANDBOX_ERROR_CODES.unavailable, message: 'Windows Sandbox broker is unavailable' },
+    });
+    return Object.freeze({
+        id,
+        execute: async () => unavailable(),
+        openStdio: async () => {
+            throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'Windows Sandbox broker is unavailable');
+        },
+        dispose: async () => undefined,
+    });
+}
+function brokerSession(session, enforcement, policy) {
+    const delegatedPolicy = brokerPolicy(policy);
+    const delegatedRequest = (request) => ({ ...request, policy: delegatedPolicy });
+    return Object.freeze({
+        id: session.id,
+        execute: async (request) => withEnforcement(await session.execute(delegatedRequest(request)), enforcement),
+        openStdio: async (request) => {
+            if (session.openStdio === undefined)
+                throw new BramboError(SANDBOX_ERROR_CODES.unavailable, 'Windows Sandbox broker stdio is unavailable');
+            return session.openStdio(delegatedRequest(request));
+        },
+        dispose: () => session.dispose(),
+    });
+}
+async function usableBroker(options) {
+    if (!(await probe(options, [BROKER, '--version'])))
+        return false;
+    const argv = [BROKER, 'self-test', '--network', 'disabled', '--cleanup'];
+    // `inspect` is the injected execution seam. Production discovery remains
+    // conservative: a broker is unusable until its own isolation self-test passes.
+    if (options.inspect !== undefined)
+        return options.inspect(argv);
+    return new Promise((resolve) => {
+        const child = spawn(argv[0], argv.slice(1), { shell: false, windowsHide: true, stdio: 'ignore' });
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const timer = setTimeout(() => { child.kill('SIGKILL'); finish(false); }, SELF_TEST_TIMEOUT_MS);
+        child.once('error', () => finish(false));
+        child.once('close', (code) => finish(code === 0));
+    });
+}
+export async function createWindowsSandboxProvider(options) {
+    const windowsSandboxBroker = await usableBroker(options);
+    const jobObjectHelper = await probe(options, ['brambo-windows-job-helper', '--version']);
+    const discovery = { bubblewrap: false, landlock: false, cgroup: false, seatbelt: false, windowsSandboxBroker, jobObjectHelper };
+    const capabilities = brokerCapabilities(windowsSandboxBroker);
+    const base = createProvider('local-windows', discovery, windowsSandboxBroker ? 'full' : 'none', options.timeoutMs ?? DEFAULT_TIMEOUT_MS, windowsSandboxBroker
+        ? (request) => [
+            BROKER,
+            'run',
+            '--workspace-root', request.policy.workspaceRoot,
+            '--working-directory', request.cwd,
+            '--network', 'disabled',
+            '--workspace-transfer', 'controlled',
+            '--cleanup', 'always',
+            '--',
+            ...request.argv,
+        ]
+        : undefined, undefined, options.audit);
+    return Object.freeze({
+        id: base.id,
+        discovery: base.discovery,
+        capabilities,
+        async createSession(value) {
+            const policy = validateSandboxPolicy(value.policy);
+            value.snapshots.forEach(validateSandboxSnapshot);
+            validateSandboxCapabilities(policy, capabilities);
+            if (!windowsSandboxBroker)
+                return unavailableSession('local-windows-unavailable', capabilities);
+            const session = await base.createSession({ ...value, policy: brokerPolicy(policy) });
+            return brokerSession(session, capabilities, policy);
+        },
+    });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@skanl/brambo-sandbox-local",
+  "version": "0.1.1",
+  "description": "Conservative local operating-system sandbox provider for brambo.",
+  "keywords": [
+    "ai-agent",
+    "brambo",
+    "sandbox",
+    "local"
+  ],
+  "homepage": "https://github.com/SKANL/brambo#readme",
+  "bugs": {
+    "url": "https://github.com/SKANL/brambo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SKANL/brambo.git",
+    "directory": "packages/sandbox-local"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "brambo-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@skanl/brambo-contracts": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "~7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json"
+  }
+}