windows-development-sandbox 1.0.5 → 1.4.0

package/dist/selftest/live-network.test.js

@@ -0,0 +1,63 @@
+// Live: the sandbox's allowOnly proxy (the real bundled runtime\netproxy.js) and the PC-side port forwarder, on
+// loopback only; and that the cargo shim compiles with the compiler that ships with Windows.
+import net from 'node:net';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { startPortForwards } from '../host/port-forward.js';
+import { PROXY_PORT, relayPort } from '../shared/netpolicy.js';
+import { CSC } from './live.js';
+/** A TCP server that answers every line with "echo:<line>". */
+const echoServer = (port = 0) => new Promise((resolve) => {
+    const server = net.createServer((s) => s.on('data', (d) => s.write('echo:' + d.toString())));
+    server.listen(port, '127.0.0.1', () => resolve(server));
+});
+const portOf = (server) => server.address().port;
+/** Sends `text` after `preamble` (a CONNECT) and resolves with everything received within a short while. */
+const talk = (port, preamble, text) => new Promise((resolve) => {
+    const socket = net.connect(port, '127.0.0.1');
+    let got = '';
+    socket.on('data', (d) => { got += d.toString(); if (preamble && got.includes('\r\n\r\n') && got.startsWith('HTTP/1.1 200') && !got.includes('echo:'))
+        socket.write(text); });
+    socket.on('error', () => resolve(got));
+    socket.on('connect', () => socket.write(preamble || text));
+    setTimeout(() => { socket.destroy(); resolve(got); }, 1500);
+});
+export const liveNetworkSuite = {
+    name: 'live-network',
+    title: 'live: allowOnly proxy, port forwarding, cargo shim',
+    live: true,
+    run: async (t, f) => {
+        t.section('allowOnly proxy');
+        const gen = await f.launch({}, { config: { ...f.baseConfig, network: { ...f.baseConfig.network, allowOnly: ['localhost'] } } });
+        const echo = await echoServer();
+        const proxy = spawn(process.execPath, [path.join(gen.launchPath, 'runtime', 'netproxy.js')], { env: { ...process.env, AGENT_LAUNCH_DIR: gen.launchPath, AGENT_DATA_DIR: t.dir('netproxy-data') }, stdio: 'ignore' });
+        try {
+            const up = await t.waitFor(() => new Promise((resolve) => { const s = net.connect(PROXY_PORT, '127.0.0.1', () => { s.destroy(); resolve(true); }); s.on('error', () => resolve(false)); }), 10000, 200);
+            t.check(Boolean(up), 'the proxy listens on localhost');
+            const allowed = await talk(PROXY_PORT, 'CONNECT localhost:' + portOf(echo) + ' HTTP/1.1\r\nHost: localhost\r\n\r\n', 'hi');
+            t.check(allowed.startsWith('HTTP/1.1 200') && allowed.includes('echo:hi'), 'an allowed host is tunnelled through', allowed);
+            const blocked = await talk(PROXY_PORT, 'CONNECT example.com:443 HTTP/1.1\r\nHost: example.com\r\n\r\n', '');
+            t.check(blocked.startsWith('HTTP/1.1 403'), 'any other host is refused (403)', blocked);
+        }
+        finally {
+            proxy.kill();
+            echo.close();
+        }
+        t.section('port forwarding');
+        const relay = await echoServer(relayPort(0));
+        const free = await echoServer();
+        const pcPort = portOf(free);
+        free.close();
+        await new Promise((r) => setTimeout(r, 200));
+        const stop = startPortForwards([{ pc: pcPort, sandbox: 3000 }], () => '127.0.0.1');
+        await new Promise((r) => setTimeout(r, 300));
+        const forwarded = await talk(pcPort, '', 'ping');
+        stop();
+        relay.close();
+        t.equal(forwarded, 'echo:ping', 'localhost:<pc> on this PC reaches the sandbox\'s relay');
+        t.section('cargo shim');
+        const out = path.join(t.dir('cargoshim'), 'cargo.exe');
+        const compiled = spawnSync(CSC, ['/nologo', '/optimize', '/out:' + out, path.join(gen.launchPath, 'sandbox', 'cargoshim.cs')], { encoding: 'utf8' });
+        t.check(compiled.status === 0, 'cargoshim.cs compiles with the .NET Framework compiler (C# 5)', compiled.stdout + compiled.stderr);
+    },
+};

package/dist/selftest/live-projects.test.d.ts

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const liveProjectsSuite: Suite;

package/dist/selftest/live-projects.test.js

@@ -0,0 +1,127 @@
+// Live: the real session daemon + ptyhost with two projects at once. The launch folder (A) and a project in a root
+// (B) each get two sessions requested at the same moment; each runs in its own folder with its own environment; B is
+// set up once for both; viewers attach, detach and reattach, two at a time; exec and restart follow the project.
+// Toolchain installers run as a dry run (no downloads); everything else is real. cmd.exe stands in for the agent.
+import fs from 'node:fs';
+import path from 'node:path';
+import { projectSpec } from '../host/join.js';
+import { resizeFrame } from '../shared/pty-client.js';
+import { readJsonFile } from '../shared/rundir.js';
+import { copyCmdAsFakeAgent, openViewer, sees, startDaemon, tail, viewersWhen } from './live.js';
+export const liveProjectsSuite = {
+    name: 'live-projects',
+    title: 'live: two projects, several sessions, several viewers',
+    live: true,
+    timeoutMs: 480000,
+    run: async (t, f) => {
+        const gen = await f.launch();
+        const data = t.at('live-multi-data');
+        const root = t.dir('live-root');
+        const projB = t.dir('live-root', 'projB');
+        copyCmdAsFakeAgent(data);
+        const session = f.readJson(gen.sessionPath);
+        // B's root appears at its own path here (like guestWorkspace "mirror"), so host and guest paths are the same.
+        Object.assign(session, { workspace: f.workA, attach: { enabled: true }, projectsDir: t.at('live-projects'), roots: [root], projectId: 'work-a' });
+        Object.assign(session.harness, { arguments: ['/d', '/k', 'echo AGENT-READY'], resumeArguments: ['/d', '/k', 'echo AGENT-RESUMED'] });
+        t.writeJson(gen.sessionPath, session);
+        const local = t.at('live-multi-local');
+        const daemon = startDaemon(t, f, { launchPath: gen.launchPath, data, workspace: f.workA, env: { AGENT_LOCAL_DIR: local, AGENT_DRY_RUN: '1', AGENT_MANAGED_DIR: t.at('live-managed') } });
+        const viewers = [];
+        const view = async (attach, cols = 100) => {
+            const v = await openViewer(attach, { cols });
+            viewers.push(v);
+            return v;
+        };
+        try {
+            t.section('live: four sessions at once');
+            const cfg = structuredClone(f.baseConfig);
+            cfg.toolchains.environment = { LIVE_B: 'b-env' };
+            const spec = projectSpec(await f.run({ cwd: projB, trustConfig: true }, cfg), { name: 'projB', host: projB, guest: projB, primary: false, mechanism: 'root', registeredAt: '' }, false);
+            // All four at the same moment: two in the launch folder, two in B (whose setup they share).
+            daemon.request({ kind: 'session', id: 'a1', harness: 'claude', args: [], cwd: f.workA });
+            daemon.request({ kind: 'session', id: 'b1', harness: 'claude', args: [], cwd: projB, project: spec });
+            daemon.request({ kind: 'session', id: 'b2', harness: 'claude', args: [], cwd: projB, project: spec });
+            daemon.request({ kind: 'session', id: 'a2', harness: 'claude', args: [], cwd: f.workA });
+            const [a1, a2, b1, b2] = await Promise.all(['a1', 'a2', 'b1', 'b2'].map((id) => daemon.started(id)));
+            const all = [a1, a2, b1, b2];
+            const notRunning = all.filter((s) => s?.phase !== 'running' || !s.attach);
+            t.check(notRunning.length === 0, 'four sessions requested at once all start (two per project)', notRunning.map((s) => s?.id + ': ' + s?.phase + ' ' + s?.message).join('\n') + '\n' + daemon.diagnostics());
+            if (notRunning.length > 0)
+                return;
+            t.equal([a1.project, b1.project, b2.project], ['work-a', 'projB', 'projB'], 'each session knows its project');
+            const log = fs.readdirSync(path.join(data, 'logs')).filter((n) => n.startsWith('daemon')).map((n) => fs.readFileSync(path.join(data, 'logs', n), 'utf8')).join('\n');
+            t.equal((log.match(/Project projB: setting up/g) ?? []).length, 1, 'two sessions for the same new project at once share one setup (no second provisioning run)');
+            t.equal(readJsonFile(path.join(daemon.run, 'projects', 'projB.json'))?.phase, 'ready', 'the project\'s setup status is written for the host (sandbox status)');
+            t.section('live: each session has its own folder and environment');
+            const views = await Promise.all(all.map((s) => view(s.attach)));
+            for (const v of views)
+                await sees(t, v, 'AGENT-READY');
+            for (const v of views)
+                v.type('echo P=%AGENT_PROJECT% W=%AGENT_WORKSPACE% B=[%LIVE_B%]');
+            const bSees = await sees(t, views[2], 'P=projB W=' + projB + ' B=[b-env]');
+            t.check(Boolean(bSees), 'B\'s first session runs with B\'s workspace, project and variables', tail(views[2].output()));
+            t.check(Boolean(await sees(t, views[3], 'B=[b-env]')), 'B\'s second session runs with B\'s variables', tail(views[3].output()));
+            // (The daemon here runs without the boot's environment, so A's own AGENT_* variables are not set at all.)
+            t.check(Boolean(await sees(t, views[0], 'B=[%LIVE_B%]')), 'A\'s first session is untouched by B (B\'s variables never reach it)', tail(views[0].output()));
+            t.check(Boolean(await sees(t, views[1], 'B=[%LIVE_B%]')), 'A\'s second session is untouched by B', tail(views[1].output()));
+            views[2].type('echo CWD=%CD%.');
+            t.check(Boolean(await sees(t, views[2], 'CWD=' + projB + '.')), 'B\'s session starts in B\'s folder', tail(views[2].output()));
+            t.section('live: several viewers on one session');
+            const second = await view(b1.attach, 60);
+            const two = await viewersWhen(t, b1.attach, (v) => v.viewers === 2);
+            t.check(two !== null, 'a second viewer attaches to the same session');
+            second.socket.write(resizeFrame(90, 25));
+            views[2].type('echo TWO-VIEWERS-OK');
+            t.check(Boolean(await sees(t, views[2], 'TWO-VIEWERS-OK')), 'the first viewer sees what it typed (after the second one resized)', tail(views[2].output()));
+            t.check(Boolean(await sees(t, second, 'TWO-VIEWERS-OK')), 'the second viewer sees it too', tail(second.output()));
+            second.type('echo FROM-SECOND');
+            t.check(Boolean(await sees(t, views[2], 'FROM-SECOND')), 'input from the second viewer reaches the agent and the first viewer', tail(views[2].output()));
+            views[2].close();
+            second.close();
+            const none = await viewersWhen(t, b1.attach, (v) => v.viewers === 0);
+            t.check(none !== null, 'closing every viewer is noticed');
+            t.equal(daemon.status('b1')?.phase, 'running', 'closing every viewer never ends the session');
+            for (let round = 1; round <= 3; round++) {
+                const again = await view(b1.attach);
+                again.type('echo REATTACHED-' + round);
+                t.check(Boolean(await sees(t, again, 'REATTACHED-' + round)), 'reattach ' + round + ': a new viewer works on the same session', tail(again.output()));
+                again.close();
+            }
+            t.section('live: exec, restart and refusals follow the projects');
+            daemon.request({ kind: 'exec', id: 'xb', command: ['echo', '%LIVE_B%'], cwd: projB, timeoutSeconds: 30 });
+            daemon.request({ kind: 'exec', id: 'xa', command: ['echo', '[%LIVE_B%]'], cwd: f.workA, timeoutSeconds: 30 });
+            const [xb, xa] = await Promise.all([daemon.response('xb'), daemon.response('xa')]);
+            t.check(Boolean(xb?.stdout?.includes('b-env')), 'exec in B\'s folder gets B\'s environment', JSON.stringify(xb));
+            t.check(Boolean(xa?.stdout?.includes('[%LIVE_B%]')), 'exec in A\'s folder gets A\'s', JSON.stringify(xa));
+            daemon.request({ kind: 'session', id: 'bad1', harness: 'claude', args: [], cwd: f.workB, project: { ...spec, name: 'outside', workspace: f.workB } });
+            const bad = await daemon.started('bad1');
+            t.check(bad?.phase === 'failed' && bad.message.includes('not visible inside the sandbox'), 'a project outside the launch folder, the roots and C:\\Projects is refused', JSON.stringify(bad));
+            daemon.request({ kind: 'session', id: 'bad2', harness: 'claude', args: [], cwd: f.workA, project: spec });
+            const claimed = await daemon.started('bad2');
+            t.includes(claimed?.message ?? '', 'not inside project projB', 'a session cannot claim a project its folder is not in');
+            daemon.request({ kind: 'restart', id: 'rb', harness: null, cwd: projB });
+            t.equal((await daemon.response('rb'))?.message, 'restarted 2 session(s)', 'restart scoped to a project restarts only its sessions');
+            t.check(fs.existsSync(path.join(local, 'projects', 'projB', 'shell.cmd')), 'sbx-shell projB has a shell script');
+            t.includes(fs.readFileSync(path.join(local, 'projects', 'projB', 'env.cmd'), 'utf8'), 'LIVE_B=b-env', 'sbx-shell projB opens with B\'s environment');
+            t.check(fs.existsSync(path.join(local, 'bin', 'sbx-shell.cmd')), 'sbx-shell is on the sandbox\'s PATH');
+        }
+        finally {
+            for (const v of viewers)
+                v.close();
+            // End every agent: a fresh viewer types exit into each still-running session.
+            for (const id of ['a1', 'a2', 'b1', 'b2']) {
+                const s = daemon.status(id);
+                if (s?.phase !== 'running' || !s.attach)
+                    continue;
+                try {
+                    const v = await openViewer(s.attach);
+                    v.type('exit');
+                    await t.waitFor(() => v.exitCode() !== null, 10000);
+                    v.close();
+                }
+                catch { /* already gone */ }
+            }
+            await daemon.stop();
+        }
+    },
+};

package/dist/selftest/live.d.ts

@@ -0,0 +1,65 @@
+import { type ChildProcess } from 'node:child_process';
+import type net from 'node:net';
+import type { GuestResponse, SessionStatus } from '../core/types.js';
+import { type Endpoint, type Viewers } from '../shared/pty-client.js';
+import type { Fixtures } from './fixtures.js';
+import type { Harness } from './harness.js';
+export declare const CSC: string;
+/** Live suites need Windows (ConPTY) and the .NET Framework compiler that ships with it. */
+export declare const liveTestsAvailable: () => boolean;
+/** Deadlines, in ms. Generous on purpose: they only matter when something is really wrong. */
+export declare const WAIT: {
+    readonly start: 120000;
+    readonly screen: 45000;
+    readonly response: 60000;
+    readonly viewers: 45000;
+    readonly exit: 45000;
+};
+export declare const tail: (text: string, chars?: number) => string;
+/** Connects, retrying until `ms`: a connection attempt can time out while the machine is busy. */
+export declare const connectPatiently: (endpoint: Endpoint, ms?: number) => Promise<net.Socket>;
+/** One connection to a session's ptyhost, collecting what the server sends. */
+export interface Viewer {
+    socket: net.Socket;
+    /** Everything the agent has printed since this viewer connected. */
+    output: () => string;
+    /** The exit code frame, once the agent ended. */
+    exitCode: () => number | null;
+    /** The error frame ("access denied"), if the server sent one. */
+    error: () => string;
+    /** True once the server closed the connection. */
+    closed: () => boolean;
+    type: (text: string) => void;
+    close: () => void;
+}
+/** Connects like a terminal tab would (`token` can be wrong on purpose) and says hello. */
+export declare const openViewer: (attach: Endpoint, options?: {
+    token?: string;
+    cols?: number;
+    rows?: number;
+}) => Promise<Viewer>;
+/** Polls until the viewer's screen shows `needle`. */
+export declare const sees: (t: Harness, viewer: Viewer, needle: string, ms?: number) => Promise<true | null>;
+/** Polls the session's viewer count until `accept` is satisfied; null when it never was. A query that gets no answer is retried. */
+export declare const viewersWhen: (t: Harness, attach: Endpoint, accept: (v: Viewers) => boolean, ms?: number) => Promise<Viewers | null>;
+export declare const copyCmdAsFakeAgent: (dataPath: string) => void;
+/** A real session daemon (guest runtime) working on a generated launch folder, driven through the run folder like the host does. */
+export interface LiveDaemon {
+    run: string;
+    child: ChildProcess;
+    request: (body: Record<string, unknown>) => void;
+    response: (id: string, ms?: number) => Promise<GuestResponse | null>;
+    status: (id: string) => SessionStatus | null;
+    /** Waits until a session has left "starting". */
+    started: (id: string, ms?: number) => Promise<SessionStatus | null>;
+    /** The daemon's stdout/stderr and its log files, for failure messages. */
+    diagnostics: () => string;
+    /** Ends the daemon. */
+    stop: () => Promise<void>;
+}
+export declare const startDaemon: (t: Harness, f: Fixtures, options: {
+    launchPath: string;
+    data: string;
+    workspace: string;
+    env?: Record<string, string>;
+}) => LiveDaemon;

package/dist/selftest/live.js

@@ -0,0 +1,109 @@
+// Helpers for the live suites: they run the real session daemon, ptyhost (ConPTY) and the compiled git shim on Windows.
+//
+// Timing rule: a live test never sleeps for a fixed time and never gives up early. It polls until the condition holds,
+// with a generous deadline (a busy machine, a cold csc.exe or an antivirus scan can make any step 10x slower), and a
+// failure prints what was seen (the viewer's screen, the daemon's log) so the cause is visible.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { ensureDir, sleep } from '../core/util.js';
+import { connect, encodeFrame, FrameReader, FrameType, helloFrame, queryViewers } from '../shared/pty-client.js';
+import { readJsonFile, writeJsonAtomic } from '../shared/rundir.js';
+const WINDIR = process.env.WINDIR ?? 'C:\\Windows';
+export const CSC = path.join(WINDIR, 'Microsoft.NET', 'Framework64', 'v4.0.30319', 'csc.exe');
+/** Live suites need Windows (ConPTY) and the .NET Framework compiler that ships with it. */
+export const liveTestsAvailable = () => process.platform === 'win32' && fs.existsSync(CSC);
+/** Deadlines, in ms. Generous on purpose: they only matter when something is really wrong. */
+export const WAIT = { start: 120000, screen: 45000, response: 60000, viewers: 45000, exit: 45000 };
+export const tail = (text, chars = 500) => (text.length > chars ? '...' + text.slice(-chars) : text).replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
+/** Connects, retrying until `ms`: a connection attempt can time out while the machine is busy. */
+export const connectPatiently = async (endpoint, ms = 60000) => {
+    const end = Date.now() + ms;
+    for (;;) {
+        try {
+            return await connect(endpoint, 10000);
+        }
+        catch (e) {
+            if (Date.now() >= end)
+                throw e;
+            await sleep(250);
+        }
+    }
+};
+/** Connects like a terminal tab would (`token` can be wrong on purpose) and says hello. */
+export const openViewer = async (attach, options = {}) => {
+    const socket = await connectPatiently({ ...attach, addresses: ['127.0.0.1'] });
+    const reader = new FrameReader();
+    let output = '';
+    let exitCode = null;
+    let error = '';
+    let closed = false;
+    socket.on('data', (chunk) => {
+        for (const frame of reader.push(chunk)) {
+            if (frame.type === FrameType.Output)
+                output += frame.payload.toString();
+            else if (frame.type === FrameType.Exit)
+                exitCode = frame.payload.readInt32LE(0);
+            else if (frame.type === FrameType.Error)
+                error = frame.payload.toString();
+        }
+    });
+    socket.on('error', () => undefined);
+    socket.on('close', () => { closed = true; });
+    socket.write(helloFrame(options.token ?? attach.token, options.cols ?? 100, options.rows ?? 30));
+    return {
+        socket,
+        output: () => output,
+        exitCode: () => exitCode,
+        error: () => error,
+        closed: () => closed,
+        type: (text) => { socket.write(encodeFrame(FrameType.Input, Buffer.from(text + '\r'))); },
+        close: () => socket.destroy(),
+    };
+};
+/** Polls until the viewer's screen shows `needle`. */
+export const sees = (t, viewer, needle, ms = WAIT.screen) => t.waitFor(() => viewer.output().includes(needle), ms);
+/** Polls the session's viewer count until `accept` is satisfied; null when it never was. A query that gets no answer is retried. */
+export const viewersWhen = (t, attach, accept, ms = WAIT.viewers) => t.waitFor(async () => {
+    const v = await queryViewers({ ...attach, addresses: ['127.0.0.1'] }, 5000);
+    return v && accept(v) ? v : null;
+}, ms);
+export const copyCmdAsFakeAgent = (dataPath) => {
+    const agentDir = path.join(dataPath, 'tools', 'agents', 'claude');
+    ensureDir(agentDir);
+    fs.copyFileSync(path.join(WINDIR, 'System32', 'cmd.exe'), path.join(agentDir, 'claude.exe'));
+};
+export const startDaemon = (t, f, options) => {
+    const { launchPath, data } = options;
+    const output = t.at(path.basename(data) + '-daemon.out');
+    const fd = fs.openSync(output, 'w');
+    const env = { ...process.env, AGENT_LAUNCH_DIR: launchPath, AGENT_DATA_DIR: data, AGENT_WORKSPACE: options.workspace, AGENT_LOCAL_DIR: f.at(path.basename(data) + '-local'), AGENT_LOG_PREFIX: 'daemon', AGENT_NO_TABS: '1', ...options.env };
+    const child = spawn(process.execPath, [path.join(launchPath, 'runtime', 'daemon.js')], { env, stdio: ['ignore', fd, fd], windowsHide: true });
+    let exited = false;
+    child.on('exit', () => { exited = true; });
+    const run = path.join(data, 'run');
+    const status = (id) => readJsonFile(path.join(run, 'sessions', id + '.json'));
+    return {
+        run,
+        child,
+        request: (body) => writeJsonAtomic(path.join(run, 'requests', body.id + '.json'), { createdAt: new Date().toISOString(), ...body }),
+        response: (id, ms = WAIT.response) => t.waitFor(() => readJsonFile(path.join(run, 'responses', id + '.json')), ms),
+        status,
+        started: (id, ms = WAIT.start) => t.waitFor(() => { const s = status(id); return s && s.phase !== 'starting' ? s : null; }, ms),
+        diagnostics: () => {
+            const logs = path.join(data, 'logs');
+            const files = fs.existsSync(logs) ? fs.readdirSync(logs).filter((n) => n.startsWith('daemon')) : [];
+            const logText = files.map((n) => fs.readFileSync(path.join(logs, n), 'utf8')).join('\n');
+            return 'daemon output: ' + tail(fs.readFileSync(output, 'utf8'), 600) + '\ndaemon log: ' + tail(logText, 1200);
+        },
+        stop: async () => {
+            if (!exited)
+                child.kill();
+            await t.waitFor(() => exited, 10000);
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* already closed */ }
+        },
+    };
+};

package/dist/selftest/local-config.test.d.ts

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const localConfigSuite: Suite;

package/dist/selftest/local-config.test.js

@@ -0,0 +1,120 @@
+// A project's .sandbox-config.json: it must be approved before it applies, it can never loosen protections, and it is
+// validated. The project file is untrusted input (it arrives with a cloned repository).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { download, setChecksumRequired } from '../shared/download.js';
+import { allowedAnswer, allowStorePath, saveAllowed } from '../core/local-config.js';
+export const localConfigSuite = {
+    name: 'local-config',
+    title: '.sandbox-config.json: approval, tighten-only rules, validation',
+    run: async (t, f) => {
+        t.section('approval');
+        const localB = {
+            harness: 'codex',
+            sandbox: { memoryMb: 4096, networking: false, headless: true },
+            toolchains: { node: { version: '18' }, rust: { enabled: false } },
+            mappings: [{ host: './assets', guest: 'C:\\Assets', readOnly: true }, { host: './data', guest: 'C:\\Data', readOnly: false }],
+            scripts: ['./setup.mjs'],
+        };
+        f.writeLocal(f.workB, localB);
+        const untrusted = await t.thrownMessage(() => f.run({ cwd: f.workB }));
+        t.includes(untrusted, '--trust-config', 'an untrusted .sandbox-config.json is refused, with the way to approve it');
+        t.includes(untrusted, 'READ/WRITE', 'the refusal lists what the file would change (read/write folders)');
+        await t.throws(() => f.run({ cwd: f.workB, ask: async () => false }), 'has not been approved', 'answering "no" refuses it');
+        const approved = await f.run({ cwd: f.workB, ask: async () => true });
+        t.equal({
+            harness: approved.harnessName,
+            memoryMb: approved.config.sandbox.memoryMb,
+            headless: approved.config.sandbox.headless,
+            rustEnabled: approved.config.toolchains.rust.enabled,
+            pythonStillOn: Boolean(approved.config.toolchains.python.enabled),
+            nodeSource: approved.versions.node.source,
+        }, { harness: 'codex', memoryMb: 4096, headless: true, rustEnabled: false, pythonStillOn: true, nodeSource: '.sandbox-config.json' }, 'approved local settings apply over the defaults (including toolchains and headless)');
+        t.check(approved.config.mappings.some((m) => m.host === path.join(f.workB, 'data') && !m.readOnly), 'relative mapping paths resolve against the folder of .sandbox-config.json', 'mappings: ' + JSON.stringify(approved.config.mappings));
+        t.check(approved.scripts.includes(path.join(f.workB, 'setup.mjs')), 'relative script paths resolve against the folder of .sandbox-config.json', 'scripts: ' + JSON.stringify(approved.scripts));
+        t.equal((await f.run({ cwd: f.workB })).harnessName, 'codex', 'an approval is remembered');
+        t.equal((await f.run({ cwd: f.workB, noLocalConfig: true })).harnessName, 'claude', '--no-local-config ignores the file');
+        t.equal((await f.run({ cwd: f.workB, harness: 'gemini' })).harnessName, 'gemini', '--harness beats the file');
+        t.equal((await f.run({ cwd: f.workB, headless: false })).config.sandbox.headless, false, '--window beats a local headless setting');
+        f.writeLocal(f.workB, { ...localB, sandbox: { memoryMb: 6144 } });
+        await t.throws(() => f.run({ cwd: f.workB }), 'has not been approved', 'changing the file requires approval again');
+        t.section('validation');
+        const dirC = t.dir('work-c');
+        const rejectedBecause = (content, needle, name) => {
+            f.writeLocal(dirC, content);
+            return t.throws(() => f.run({ cwd: dirC, trustConfig: true }), needle, name);
+        };
+        await rejectedBecause({ storage: { root: 'C:\\x' } }, 'storage is not allowed', 'a project file cannot change the storage folder');
+        await rejectedBecause({ harnesses: {} }, 'harnesses is not allowed', 'a project file cannot change agent executables');
+        await rejectedBecause({ claudeProfile: { hostDir: 'C:\\x' } }, 'claudeProfile.hostDir is not allowed', 'a project file cannot point at the Claude profile folder');
+        await rejectedBecause({ toolchains: { node: { hostDir: 'x' } } }, 'toolchains.node.hostDir is not allowed', 'a project file cannot point at host tool folders');
+        await rejectedBecause({ sandbox: { memoryMb: 12 } }, 'sandbox.memoryMb:', 'values are type-checked (memory too small)');
+        await rejectedBecause({ mappings: [{ host: 'x', guest: 'C:\\Windows\\x', readOnly: true }] }, 'reserved or invalid guest path', 'reserved guest paths are rejected');
+        await rejectedBecause({ mappings: [{ host: '../shared', guest: 'C:\\Shared', readOnly: true }] }, 'only map folders inside the project', 'a project file cannot map folders outside the project');
+        await rejectedBecause({ mappings: [{ host: '%APPDATA%', guest: 'C:\\Startup', readOnly: false }] }, 'only map folders inside the project', '... not even through environment variables');
+        await rejectedBecause({ provisioning: { git: { access: 'admin' } } }, 'provisioning.git.access:', 'unknown git access modes are rejected');
+        await rejectedBecause('{\n  // a comment\n  "readOnly": tru\n}', 'line 3', 'broken JSON is reported with its line');
+        await rejectedBecause({ _comment: 'old style' }, '_comment is not allowed', 'unknown keys are rejected');
+        f.writeLocal(dirC, '// comments and trailing commas are fine\n{\n  "readOnly": true, /* inline */\n}\n');
+        t.equal((await f.run({ cwd: dirC, trustConfig: true })).config.readOnly, true, '.sandbox-config.json may contain comments and trailing commas');
+        t.section('a project can only tighten protections');
+        // Settings that would loosen a protection are listed before approval, then ignored.
+        f.writeLocal(dirC, {
+            claudeProfile: { copyCredentials: true },
+            network: { blockPrivateRanges: false },
+            provisioning: { git: { access: 'full' } },
+            sandbox: { vGpu: true, clipboard: true, networking: true, protectedClient: false },
+            readOnly: false,
+        });
+        await t.throws(() => f.run({ cwd: dirC }), 'only used if it is stricter', 'settings a project may only tighten are called out before approval');
+        const strictUser = {
+            ...f.baseConfig,
+            readOnly: true,
+            network: { ...f.baseConfig.network, blockPrivateRanges: true },
+            provisioning: { ...f.baseConfig.provisioning, git: { ...f.baseConfig.provisioning.git, access: 'readonly' } },
+            sandbox: { ...f.baseConfig.sandbox, vGpu: false, clipboard: false, networking: false, protectedClient: true },
+        };
+        const keptRun = await f.run({ cwd: dirC, trustConfig: true }, strictUser);
+        const kept = keptRun.config;
+        t.check(keptRun.notes.some((n) => n.includes('sandbox.vGpu = true') && n.includes('your own settings')), 'what a project asked for and did not get is said at launch, with how to allow it', keptRun.notes.join('\n'));
+        t.equal({
+            readOnly: kept.readOnly,
+            blockPrivateRanges: kept.network.blockPrivateRanges,
+            gitAccess: kept.provisioning.git.access,
+            vGpu: kept.sandbox.vGpu,
+            clipboard: kept.sandbox.clipboard,
+            networking: kept.sandbox.networking,
+            protectedClient: kept.sandbox.protectedClient,
+            copyCredentials: kept.claudeProfile.copyCredentials,
+        }, { readOnly: true, blockPrivateRanges: true, gitAccess: 'readonly', vGpu: false, clipboard: false, networking: false, protectedClient: true, copyCredentials: false }, 'a project file can never loosen network, git, read-only, GPU, clipboard or login settings');
+        // You allowed one request for this project (asked once at an interactive launch): only that one is let through.
+        const store = allowStorePath(strictUser.storage.root);
+        saveAllowed(store, path.join(dirC, '.sandbox-config.json'), 'sandbox.vGpu', true, true);
+        saveAllowed(store, path.join(dirC, '.sandbox-config.json'), 'sandbox.clipboard', true, false);
+        const allowedRun = await f.run({ cwd: dirC, trustConfig: true }, strictUser);
+        t.equal({ vGpu: allowedRun.config.sandbox.vGpu, clipboard: allowedRun.config.sandbox.clipboard, networking: allowedRun.config.sandbox.networking }, { vGpu: true, clipboard: false, networking: false }, 'a request you allowed for this project is used; one you declined and the others are not');
+        t.check(allowedRun.notes.some((n) => n.includes('Allowed for this project: sandbox.vGpu')) && allowedRun.notes.some((n) => n.includes('sandbox.clipboard') && n.includes('You said no')), 'launch says what was allowed and what you declined', allowedRun.notes.join('\n'));
+        t.equal(allowedAnswer(store, path.join(f.workB, '.sandbox-config.json'), 'sandbox.vGpu', true), null, 'an answer is kept per project file');
+        f.writeLocal(dirC, { readOnly: true, network: { blockPrivateRanges: true }, provisioning: { git: { access: 'none' } }, sandbox: { networking: false, clipboard: false } });
+        const tightened = (await f.run({ cwd: dirC, trustConfig: true })).config;
+        t.equal({ readOnly: tightened.readOnly, gitAccess: tightened.provisioning.git.access, networking: tightened.sandbox.networking, clipboard: tightened.sandbox.clipboard }, { readOnly: true, gitAccess: 'none', networking: false, clipboard: false }, 'a project file can still make things stricter');
+        t.section('downloads.requireChecksum');
+        f.writeLocal(dirC, { downloads: { requireChecksum: false } });
+        const keptOn = (await f.run({ cwd: dirC, trustConfig: true }, { ...f.baseConfig, downloads: { requireChecksum: true } })).config;
+        f.writeLocal(dirC, { downloads: { requireChecksum: true } });
+        const turnedOn = (await f.run({ cwd: dirC, trustConfig: true })).config;
+        t.equal(keptOn.downloads.requireChecksum, true, 'a project file cannot switch the checksum requirement off');
+        t.equal(turnedOn.downloads.requireChecksum, true, 'a project file can switch the checksum requirement on');
+        t.equal(f.baseConfig.downloads.requireChecksum, false, '(the requirement is off in the defaults)');
+        // With the requirement on, a download without a hash is refused before anything is fetched.
+        setChecksumRequired(true);
+        const target = path.join(os.tmpdir(), 'agent-sandbox-no-such-download.bin');
+        const refused = await download('http://127.0.0.1:9/tool.zip', target).then(() => '', (e) => e.message);
+        setChecksumRequired(false);
+        t.includes(refused, 'requireChecksum', 'a download with no hash is refused when checksums are required');
+        t.includes(refused, 'tool.zip', 'the refusal names the download');
+        t.check(!fs.existsSync(target) && !fs.existsSync(target + '.part'), 'a refused download leaves nothing behind');
+        fs.rmSync(path.join(dirC, '.sandbox-config.json'));
+    },
+};

package/dist/selftest/mirror.test.d.ts

@@ -1,3 +1,2 @@
-import type { Fixtures } from './fixtures.js';
-import type { Harness } from './harness.js';
-export declare const mirrorTests: (t: Harness, f: Fixtures) => Promise<void>;
+import type { Suite } from './suite.js';
+export declare const mirrorSuite: Suite;