windows-development-sandbox 0.0.0-stage → 1.1.0

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,107 @@
+// 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';
+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: '../shared', guest: 'C:\\Shared', 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 === f.shared && !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({ 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 kept = (await f.run({ cwd: dirC, trustConfig: true }, strictUser)).config;
+        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');
+        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

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

package/dist/selftest/mirror.test.js

@@ -0,0 +1,101 @@
+// Guest paths on other drive letters (C:\Mirror\<letter> + subst) and guestWorkspace "mirror".
+import fs from 'node:fs';
+import path from 'node:path';
+import { Config, Mapping } from '../core/schema.js';
+import { guestPathFor } from '../cli/commands/context.js';
+import { buildWsb } from '../host/launch/wsb.js';
+import { guestDrive, isValidGuestPath, planMirrorWorkspace, sandboxFolder, substDrives } from '../shared/guest-paths.js';
+import { guestWorkspaceAliases, projectFolderName } from '../shared/paths.js';
+import { syncHistoryIn, syncHistoryOut } from '../sync/history.js';
+export const mirrorSuite = {
+    name: 'mirror',
+    title: 'guest paths on other drive letters, guestWorkspace "mirror"',
+    run: async (t, f) => {
+        t.section('which guest paths are valid');
+        const valid = ['C:\\Assets', 'C:\\Workspace\\x', 'F:\\SteamLibrary\\steamapps\\common\\Game', 'f:\\x', 'Z:\\a b\\c (1)'];
+        t.equal(valid.filter((p) => !isValidGuestPath(p)), [], 'guest paths under C:\\ or on D: to Z: are accepted');
+        const invalid = ['C:\\', 'F:\\', 'F:', 'C:\\Windows\\x', 'C:\\Users\\me', 'c:\\program files\\x', 'C:\\AgentData\\x', 'C:\\Mirror', 'C:\\Mirror\\F\\x', 'A:\\x', 'B:\\x', 'C:\\a\\..\\Windows', 'F:\\a\\..\\b', 'F:\\a:b', 'F:\\a/b', 'F:\\a\\\\b', 'F:\\a.\\b', 'F:\\a|b', 'F:\\a\nb', '\\\\server\\share\\x', 'relative\\x', 'F:x'];
+        t.equal(invalid.filter(isValidGuestPath), [], 'drive roots, reserved folders, C:\\Mirror, A:/B:, .., streams, odd characters and UNC paths are refused');
+        const mappingAccepts = (guest) => Mapping.safeParse({ host: 'E:\\Games', guest, readOnly: true }).success;
+        t.check(mappingAccepts('F:\\SteamLibrary\\Game') && mappingAccepts('C:\\F'), 'schema: mappings[].guest may be on another drive letter');
+        t.check(!mappingAccepts('C:\\Mirror\\F\\x') && !mappingAccepts('F:\\'), 'schema: mappings[].guest may never be C:\\Mirror or a drive root');
+        const workspaceAccepts = (guestWorkspace) => Config.safeParse({ ...f.makeConfig(), guestWorkspace }).success;
+        t.check(workspaceAccepts('mirror') && workspaceAccepts('F:\\AgentProjects\\x'), 'schema: guestWorkspace accepts "mirror" and D:-Z: paths');
+        t.check(!workspaceAccepts('C:\\Users\\x'), 'schema: guestWorkspace refuses reserved paths');
+        t.equal([guestDrive('f:\\x'), guestDrive('\\\\s\\x')], ['F', null], 'drive letter of a guest path');
+        t.section('where a drive-letter path really lives');
+        t.equal([sandboxFolder('F:\\SteamLibrary\\Game'), sandboxFolder('f:\\x'), sandboxFolder('C:\\Assets')], ['C:\\Mirror\\F\\SteamLibrary\\Game', 'C:\\Mirror\\F\\x', 'C:\\Assets'], 'F:\\x really lives at C:\\Mirror\\F\\x; C: paths stay as they are');
+        t.equal(substDrives(['C:\\a', 'G:\\z', 'F:\\x', 'f:\\y']), [{ letter: 'F', target: 'C:\\Mirror\\F' }, { letter: 'G', target: 'C:\\Mirror\\G' }], 'one subst drive per used letter (never C:), sorted');
+        t.equal(guestWorkspaceAliases('F:\\AgentProjects\\mw2'), ['C:\\Mirror\\F\\AgentProjects\\mw2', 'F:\\AgentProjects\\mw2'], 'a mirrored workspace is also known by its real C:\\Mirror path');
+        t.equal(guestWorkspaceAliases('C:\\Workspace\\x').length, 1, 'a C: workspace has no alias');
+        const wsb = buildWsb(f.baseConfig, 4096, [
+            { host: 'E:\\SteamLibrary\\steamapps\\common\\Game', guest: 'F:\\SteamLibrary\\steamapps\\common\\Game', readOnly: true },
+            { host: 'D:\\Assets', guest: 'C:\\Assets', readOnly: false },
+        ]);
+        t.includes(wsb, '<SandboxFolder>C:\\Mirror\\F\\SteamLibrary\\steamapps\\common\\Game</SandboxFolder>', 'the .wsb maps F:\\ guests under C:\\Mirror\\F');
+        t.includes(wsb, '<SandboxFolder>C:\\Assets</SandboxFolder>', 'the .wsb maps C:\\ guests as they are');
+        t.excludes(wsb, '<SandboxFolder>F:', 'the .wsb never maps a drive-letter folder directly');
+        t.section('guestWorkspace "mirror"');
+        const fallback = 'C:\\Workspace\\mw2-agent';
+        const onF = planMirrorWorkspace('F:\\AgentProjects\\mw2-agent', fallback);
+        t.equal(onF.guest, 'F:\\AgentProjects\\mw2-agent', 'a workspace on F: appears at its PC path (mirror + subst)');
+        t.includes(onF.note ?? '', 'C:\\Mirror\\F\\AgentProjects\\mw2-agent', 'a workspace on F: comes with a note saying where it really is');
+        t.equal(planMirrorWorkspace('f:\\AgentProjects\\x\\', fallback).guest, 'F:\\AgentProjects\\x', 'a trailing backslash and a lower-case letter are normalised');
+        const onC = planMirrorWorkspace('C:\\dev\\mw2-agent', fallback);
+        t.equal({ guest: onC.guest, note: onC.note }, { guest: 'C:\\dev\\mw2-agent', note: null }, 'a workspace on C: outside reserved folders keeps its path');
+        const reserved = planMirrorWorkspace('C:\\Users\\josh\\mw2-agent', fallback);
+        t.equal(reserved.guest, fallback, 'C:\\Users\\... falls back to C:\\Workspace\\<name>...');
+        t.includes(reserved.note ?? '', 'reserved', '... with a note');
+        t.equal(planMirrorWorkspace('\\\\server\\share\\mw2-agent', fallback).guest, fallback, 'UNC paths fall back');
+        t.equal(planMirrorWorkspace('A:\\mw2-agent', fallback).guest, fallback, 'A: and B: fall back');
+        const resolved = await f.run({}, { ...f.makeConfig(), guestWorkspace: 'mirror' });
+        const expected = planMirrorWorkspace(f.workA, 'C:\\Workspace\\work-a');
+        t.equal(resolved.config.guestWorkspace, expected.guest, 'resolveRun turns "mirror" into a concrete guest path');
+        t.check(expected.note === null || resolved.notes.includes(expected.note), 'resolveRun explains a fallback in run.notes', JSON.stringify(resolved.notes));
+        t.section('generating a sandbox with drive-letter folders');
+        const game = t.dir('steam', 'Game');
+        const base = await f.run();
+        const run = { ...base, config: { ...base.config, guestWorkspace: 'G:\\Projects\\work-a', mappings: [{ host: game, guest: 'F:\\SteamLibrary\\steamapps\\common\\Game', readOnly: true }] } };
+        const generated = f.generate(run);
+        const session = f.readJson(generated.sessionPath);
+        const text = fs.readFileSync(generated.wsbPath, 'utf8');
+        t.equal(session.workspace, 'G:\\Projects\\work-a', 'session.json: the workspace is at its drive-letter path');
+        t.equal(session.substDrives, [{ letter: 'F', target: 'C:\\Mirror\\F' }, { letter: 'G', target: 'C:\\Mirror\\G' }], 'session.json: subst drives are listed for bootstrap.ps1');
+        t.includes(text, '<SandboxFolder>C:\\Mirror\\G\\Projects\\work-a</SandboxFolder>', '.wsb: the workspace is under C:\\Mirror');
+        t.includes(text, '<SandboxFolder>C:\\Mirror\\F\\SteamLibrary\\steamapps\\common\\Game</SandboxFolder>', '.wsb: the mapping is under C:\\Mirror');
+        t.equal(f.readJson(f.generate(base).sessionPath).substDrives, [], 'no other drive letters: no subst drives');
+        const withMapping = (guest) => ({ ...run, config: { ...run.config, mappings: [{ host: game, guest, readOnly: true }] } });
+        await t.throws(() => f.generate(withMapping('C:\\Mirror\\F\\x')), 'not a usable sandbox folder', 'a mapping straight into C:\\Mirror is refused');
+        await t.throws(() => f.generate(withMapping('C:\\Windows\\x')), 'not a usable sandbox folder', 'a reserved guest folder is refused by the host too (not only the schema)');
+        await t.throws(() => f.generate(withMapping('g:\\projects\\work-a\\game')), 'overlapping', 'mappings overlapping on the same mirrored drive are refused');
+        t.section('exec, attach and history for a mirrored workspace');
+        const workspace = 'F:\\AgentProjects\\mw2-agent';
+        t.equal(guestPathFor(workspace + '\\crates\\engine', workspace, workspace), workspace + '\\crates\\engine', 'a host folder maps to the same guest folder');
+        const project = projectFolderName(workspace);
+        t.equal(project, 'F--AgentProjects-mw2-agent', 'the Claude project folder is the same on both sides');
+        const sides = f.historySides('mirror', workspace, workspace);
+        const hostProject = path.join(sides.hostClaudeDir, 'projects', project);
+        const guestProject = path.join(sides.guestClaudeDir, 'projects', project);
+        t.write(path.join(hostProject, 's1.jsonl'), '{"cwd":"F:\\\\AgentProjects\\\\mw2-agent","t":1}\n');
+        t.write(path.join(sides.hostClaudeDir, 'history.jsonl'), '{"display":"hi","timestamp":1,"project":"F:\\\\AgentProjects\\\\mw2-agent"}\n');
+        syncHistoryIn(sides);
+        t.includes(fs.readFileSync(path.join(guestProject, 's1.jsonl'), 'utf8'), 'F:\\\\AgentProjects\\\\mw2-agent', 'history in: paths are unchanged');
+        t.equal(fs.readdirSync(path.join(sides.guestClaudeDir, 'projects')).length, 1, 'history in: only the one project folder is created');
+        t.write(path.join(guestProject, 's2.jsonl'), '{"cwd":"F:\\\\AgentProjects\\\\mw2-agent","t":2}\n');
+        const realPathProject = path.join(sides.guestClaudeDir, 'projects', 'C--Mirror-F-AgentProjects-mw2-agent');
+        t.write(path.join(realPathProject, 's3.jsonl'), '{"cwd":"C:\\\\Mirror\\\\F\\\\AgentProjects\\\\mw2-agent","f":"C:/Mirror/F/AgentProjects/mw2-agent/src/main.rs"}\n');
+        fs.appendFileSync(path.join(sides.guestClaudeDir, 'history.jsonl'), '{"display":"real path","timestamp":2,"project":"C:\\\\Mirror\\\\F\\\\AgentProjects\\\\mw2-agent"}\n');
+        syncHistoryOut(sides);
+        const s3 = path.join(hostProject, 's3.jsonl');
+        t.check(fs.existsSync(path.join(hostProject, 's2.jsonl')), 'history out: transcripts under the PC path come back');
+        t.check(fs.existsSync(s3), 'history out: transcripts under the real C:\\Mirror path come back into the PC project folder');
+        t.check(!fs.existsSync(path.join(sides.hostClaudeDir, 'projects', 'C--Mirror-F-AgentProjects-mw2-agent')), 'history out: no C:\\Mirror project folder appears on the PC');
+        const s3Text = fs.existsSync(s3) ? fs.readFileSync(s3, 'utf8') : '';
+        t.includes(s3Text, '"cwd":"F:\\\\AgentProjects\\\\mw2-agent"', 'history out: C:\\Mirror\\F\\... paths are translated back to F:\\...');
+        t.includes(s3Text, 'F:/AgentProjects/mw2-agent/src/main.rs', 'history out: forward-slash paths are translated too');
+        t.excludes(s3Text, 'Mirror', 'history out: nothing mentions C:\\Mirror any more');
+        const promptHistory = fs.readFileSync(path.join(sides.hostClaudeDir, 'history.jsonl'), 'utf8');
+        t.includes(promptHistory, '"project":"F:\\\\AgentProjects\\\\mw2-agent"}', 'prompt history out: real paths are translated');
+        t.excludes(promptHistory, 'Mirror', 'prompt history out: nothing mentions C:\\Mirror');
+    },
+};

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

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

package/dist/selftest/network.test.js

@@ -0,0 +1,28 @@
+import { isSandboxAddress } from '../host/attach.js';
+import { buildFirewallCommands, cidrToRange, ipv4DnsServers, parseDefaultGateways, parseDnsServers, subtractIps } from '../shared/netrules.js';
+export const networkSuite = {
+    name: 'network',
+    title: 'firewall maths, gateway/DNS parsing, attach address checks',
+    run: (t) => {
+        t.section('firewall');
+        const [start172, end172] = cidrToRange('172.16.0.0/12');
+        const gateway = 172 * 16777216 + 28 * 65536 + 1;
+        const remaining = subtractIps([[start172, end172]], ['172.28.0.1']);
+        t.check(remaining.every(([start, end]) => gateway < start || gateway > end), 'the private block minus the gateway no longer contains the gateway');
+        t.excludes(buildFirewallCommands(['8.8.8.8']).join(), '8.8.8.8', 'public addresses are not part of the private-range rules');
+        t.section('reading Windows output');
+        t.equal(parseDefaultGateways('  0.0.0.0          0.0.0.0     172.28.80.1   172.28.85.200     5\n'), ['172.28.80.1'], 'the default gateway is read from the route table');
+        t.equal(parseDnsServers('   DNS Servers . . . : 172.28.80.1\n                       8.8.8.8\n   NetBIOS : x\n'), ['172.28.80.1', '8.8.8.8'], 'DNS servers are read from ipconfig output');
+        t.equal(ipv4DnsServers(['172.28.80.1', '8.8.8.8:1053', '[::1]:53', 'fe80::1']), ['172.28.80.1', '8.8.8.8'], 'DNS servers from the resolver (any Windows language): IPv4 only, ports dropped');
+        t.section('attach only reaches into the sandbox');
+        const interfaces = {
+            'vEthernet (Default Switch)': [{ address: '172.20.0.1', netmask: '255.255.240.0', family: 'IPv4', internal: false, mac: '', cidr: null }],
+            Ethernet: [{ address: '192.168.1.10', netmask: '255.255.255.0', family: 'IPv4', internal: false, mac: '', cidr: null }],
+        };
+        t.check(isSandboxAddress('172.20.5.9', interfaces), 'an address in the Hyper-V subnet is the sandbox');
+        t.check(!isSandboxAddress('192.168.1.20', interfaces), 'a LAN address is not');
+        t.check(!isSandboxAddress('127.0.0.1', interfaces), 'loopback is not');
+        t.check(!isSandboxAddress('8.8.8.8', interfaces), 'an internet address is not');
+        t.check(!isSandboxAddress('172.20.0.1', interfaces), 'this PC\'s own address on that subnet is not');
+    },
+};

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

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

package/dist/selftest/personalization.test.js

@@ -0,0 +1,53 @@
+// Things written for Windows itself on this PC: the registry personalisation (.reg file) and the Windows Terminal
+// PowerShell 7 profile. The Windows Terminal part is only tried on temp copies.
+import fs from 'node:fs';
+import path from 'node:path';
+import { toRegFile } from '../host/personalize.js';
+import { PWSH_PROFILE_GUID, syncPwshProfile, withPwshProfile } from '../host/terminal.js';
+export const personalizationSuite = {
+    name: 'personalization',
+    title: 'registry personalisation (.reg) and the Windows Terminal PowerShell 7 profile',
+    run: (t) => {
+        t.section('registry values');
+        const reg = toRegFile([
+            { key: 'Control Panel\\Desktop', name: 'WallpaperStyle', kind: 'String', value: '10' },
+            { key: 'X', name: 'D', kind: 'DWord', value: 4294967295 },
+            { key: 'X', name: 'B', kind: 'Binary', value: Buffer.from([1, 255]).toString('base64') },
+        ]);
+        t.includes(reg, '[HKEY_CURRENT_USER\\Control Panel\\Desktop]', 'the .reg file only writes under HKCU');
+        t.includes(reg, '"WallpaperStyle"="10"', 'string values are written as strings');
+        t.includes(reg, '"D"=dword:ffffffff', 'DWORD values are written in hex');
+        t.includes(reg, '"B"=hex:01,ff', 'binary values are written as hex bytes');
+        t.section('Windows Terminal profile');
+        const shown = withPwshProfile({ theme: 'dark', profiles: { defaults: { font: {} } } }, true);
+        const shownProfiles = shown?.profiles;
+        t.equal(shownProfiles?.list.length, 1, 'a PowerShell 7 profile is added once pwsh is installed');
+        t.equal(shownProfiles?.list[0].guid, PWSH_PROFILE_GUID, 'the added profile has our GUID');
+        t.includes(String(shownProfiles?.list[0].commandline), 'pwsh.exe', 'the added profile starts pwsh.exe');
+        t.check(Boolean(shownProfiles?.defaults) && shown?.theme === 'dark', 'the rest of the settings are kept');
+        t.equal(withPwshProfile(shown, true), null, 'nothing is rewritten when the profile is already there');
+        t.equal(withPwshProfile({ profiles: { defaults: {} } }, false), null, 'nothing is rewritten when pwsh was never wanted');
+        const edited = { profiles: { list: [{ guid: 'other' }, { guid: PWSH_PROFILE_GUID.toUpperCase(), name: 'My pwsh', fontSize: 14 }] } };
+        const hidden = withPwshProfile(edited, false)?.profiles;
+        t.equal({ hidden: hidden?.list[1].hidden, name: hidden?.list[1].name, fontSize: hidden?.list[1].fontSize, count: hidden?.list.length }, { hidden: true, name: 'My pwsh', fontSize: 14, count: 2 }, 'turning pwsh off hides the profile and keeps the user\'s edits');
+        const oldForm = withPwshProfile({ profiles: [{ guid: 'a' }] }, true)?.profiles;
+        t.equal(oldForm.list.length, 2, 'the old array form of "profiles" works');
+        t.section('Windows Terminal settings.json on disk (JSONC, temp copy)');
+        const data = t.at('wt-data');
+        const settings = t.write(path.join(data, 'tools', 'terminal', 'settings', 'settings.json'), '// edited in the sandbox\n{ "theme": "light", "profiles": { "list": [{ "guid": "{x}", }] } }');
+        const read = () => JSON.parse(fs.readFileSync(settings, 'utf8'));
+        syncPwshProfile(data, true);
+        const untouched = fs.readFileSync(settings, 'utf8');
+        t.check(untouched.startsWith('// edited'), 'untouched until pwsh is installed (comments and trailing commas survive)');
+        t.write(path.join(data, 'tools', 'pwsh', 'pwsh.exe'), 'MZ');
+        syncPwshProfile(data, true);
+        const added = read();
+        t.equal(added.theme, 'light', 'once pwsh is installed the profile is added and the user\'s settings are kept');
+        t.equal(added.profiles.list.map((p) => p.guid), ['{x}', PWSH_PROFILE_GUID], 'the profile is added after the existing ones');
+        syncPwshProfile(data, false);
+        t.equal(read().profiles.list[1].hidden, true, 'the profile is hidden when pwsh is turned off');
+        t.write(settings, '{ not json');
+        syncPwshProfile(data, true);
+        t.equal(fs.readFileSync(settings, 'utf8'), '{ not json', 'an unreadable settings file is left alone');
+    },
+};