windows-development-sandbox 1.0.5 → 1.1.0

package/dist/selftest/guest-boot.test.js

@@ -0,0 +1,76 @@
+// The guest's boot script (runtime/main.js) run in dry-run mode against fake sandbox folders: what it provisions,
+// what it copies in, and what it refuses to.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonFile } from '../shared/rundir.js';
+export const guestBootSuite = {
+    name: 'guest-boot',
+    title: 'guest boot in dry-run mode (provisioning, Claude state, git policy)',
+    run: async (t, f) => {
+        const gen = await f.launch({}, { args: ['--version'], probe: { ...f.probe, gitDir: f.shared, nvmDir: f.workB } });
+        t.section('first boot');
+        const data1 = t.at('data1');
+        const boot = await f.runGuest(gen.launchPath, data1, f.workA, { AGENT_TEST_EXEMPT: '172.28.0.1' });
+        t.check(boot.status === 0, 'the guest boots and exits cleanly', 'exit code ' + boot.status + '\n' + boot.out);
+        t.includes(boot.out, 'would run:', 'the guest starts the agent...');
+        t.includes(boot.out, '--version', '... with its arguments...');
+        t.includes(boot.out, 'cwd=' + f.workA, '... in the workspace');
+        for (const step of ['would provision nvm and Node 22.3.0 (from this PC)', 'would provision Python 3', 'would provision MinGW-w64 GCC', 'would provision Rust', '.NET SDK', 'would provision bun', 'would provision uv', 'would provision Git for Windows from this PC']) {
+            t.includes(boot.out, step, 'the guest provisions: ' + step);
+        }
+        t.includes(boot.out, 'AgentSandbox-Block-Private', 'the firewall plan blocks the LAN...');
+        t.includes(boot.out, 'remoteport=1-52,54-65535', '... but keeps DNS to the gateway');
+        t.equal(readJsonFile(path.join(data1, 'run', 'sandbox.json'))?.phase, 'ready', 'the guest reports "ready" in run/sandbox.json');
+        t.section('Claude state copied in');
+        const claudeState = path.join(data1, 'state', 'claude');
+        t.includes(fs.readFileSync(path.join(claudeState, 'settings.json'), 'utf8'), 'dark', 'the guest applied this PC\'s Claude settings');
+        t.check(fs.existsSync(path.join(claudeState, 'commands', 'review.md')), 'custom commands are copied');
+        t.check(!fs.existsSync(path.join(claudeState, '.credentials.json')), 'the login is not copied');
+        const plugins = fs.readFileSync(path.join(claudeState, 'plugins', 'installed_plugins.json'), 'utf8');
+        t.includes(plugins, JSON.stringify(claudeState).slice(1, -1), 'plugin manifests are re-pointed at the sandbox Claude folder');
+        const guestState = f.readJson(path.join(claudeState, '.claude.json'));
+        t.equal(guestState.mcpServers?.github?.command, 'npx', 'MCP servers from this PC are in the sandbox');
+        const manifest = fs.readFileSync(f.at('managed', 'CLAUDE.md'), 'utf8');
+        t.includes(manifest, 'DISPOSABLE Windows Sandbox', 'the agent manifest goes to the managed CLAUDE.md...');
+        t.includes(manifest, f.workA, '... naming the workspace');
+        t.check(manifest.split('\n').length < 16, 'the managed manifest stays tiny', manifest.split('\n').length + ' lines');
+        t.equal(fs.readFileSync(path.join(claudeState, 'CLAUDE.md'), 'utf8'), 'my rules', 'the user\'s own CLAUDE.md is untouched');
+        t.check(fs.existsSync(path.join(data1, 'SANDBOX.md')), 'SANDBOX.md is written to the data folder');
+        t.check(!fs.existsSync(f.at('managed', 'managed-settings.json')), 'git access full: no managed deny rules');
+        t.section('second boot');
+        // The host changed its MCP servers: the sandbox keeps its own login and .claude.json but gets the new servers.
+        fs.writeFileSync(path.join(claudeState, '.claude.json'), JSON.stringify({ ...guestState, oauthAccount: { emailAddress: 'sandbox@x' }, mcpServers: { local: { command: 'x' } } }));
+        t.writeJson(path.join(gen.launchPath, 'claude-profile', '.claude.json'), { mcpServers: { github: { command: 'npx2' } }, projects: { [f.workA.replace(/\\/g, '/')]: { mcpServers: { db: { command: 'pg' } } } } });
+        await f.runGuest(gen.launchPath, data1, f.workA);
+        const merged = f.readJson(path.join(claudeState, '.claude.json'));
+        t.equal(merged.oauthAccount.emailAddress, 'sandbox@x', 'MCP re-sync leaves the sandbox login alone');
+        t.equal(merged.mcpServers.github.command, 'npx2', 'MCP re-sync updates a server changed on this PC');
+        t.equal(merged.mcpServers.local.command, 'x', 'MCP re-sync keeps a server added in the sandbox');
+        const projectServers = Object.values(merged.projects);
+        t.check(projectServers.some((p) => p.mcpServers?.db), 'MCP re-sync brings in project-scope servers', JSON.stringify(merged.projects));
+        t.section('other modes');
+        const readonlyConfig = f.makeConfig();
+        readonlyConfig.provisioning.git.access = 'readonly';
+        const genRo = await f.launch({}, { config: readonlyConfig });
+        await f.runGuest(genRo.launchPath, t.at('data-ro'), f.workA, { AGENT_MANAGED_DIR: t.at('managed-ro') });
+        const deny = f.readJson(t.at('managed-ro', 'managed-settings.json')).permissions.deny;
+        t.check(deny.includes('Bash(git commit:*)') && deny.includes('PowerShell(git push:*)'), 'git readonly: Claude managed settings deny writing git commands', JSON.stringify(deny));
+        t.check(deny.includes('Edit(**/.git/**)'), 'git readonly: .git edits are denied');
+        t.check(!deny.includes('Bash(git status:*)'), 'git readonly: reading git commands stay allowed');
+        f.writeLocal(f.workB, { scripts: ['./setup.mjs'] });
+        const genHook = await f.launch({ cwd: f.workB, harness: 'claude', trustConfig: true });
+        const hook = await f.runGuest(genHook.launchPath, t.at('data-hook'), f.workB);
+        t.check(hook.status === 0, 'a project with "scripts" boots', hook.out);
+        t.equal(fs.readFileSync(t.at('data-hook', 'hook-ran.txt'), 'utf8'), f.workB, 'local "scripts" run inside the sandbox with the workspace set');
+        const genInstall = await f.launch({}, { config: f.makeConfig(false), probe: { ...f.probe, nodeDir: null, harnessExe: null } });
+        const install = await f.runGuest(genInstall.launchPath, t.at('data3'), f.workA, { AGENT_HOST_TOOLS_DIR: t.at('empty') });
+        t.check(install.status === 0, 'install mode boots', install.out);
+        t.includes(install.out, 'npm-cli.js', 'install mode: npm is used...');
+        t.includes(install.out, '@anthropic-ai/claude-code', '... to install the agent');
+        t.excludes(fs.readFileSync(genInstall.wsbPath, 'utf8'), 'HostTools', 'install mode: nothing is mapped from this PC');
+        const genNoAgent = await f.launch({ noAgent: true });
+        const noAgent = await f.runGuest(genNoAgent.launchPath, t.at('data5'), f.workA);
+        t.check(noAgent.status === 0, '--no-agent boots', noAgent.out);
+        t.includes(noAgent.out, 'no agent requested', '--no-agent provisions without an agent');
+    },
+};

package/dist/selftest/harness.d.ts

@@ -1,14 +1,51 @@
+/** Text a failure message must contain (string) or match (RegExp). */
+export type Expected = string | RegExp;
 export interface Harness {
     packageRoot: string;
+    /** The folder every test works in; removed at the end. */
     temp: string;
-    check: (ok: boolean, name: string) => void;
-    rejects: (fn: () => unknown, needle: string) => Promise<boolean>;
-    write: (file: string, content: string) => string;
-    /** Polls `read` until it returns something truthy (or the timeout passes). */
-    waitFor: <T>(read: () => T | null | undefined | false | Promise<T | null | undefined | false>, ms?: number) => Promise<T | null>;
     section: (title: string) => void;
+    /** Prints a SKIP line (not a check). */
+    skip: (what: string) => void;
+    /** The basic assertion. `detail` is printed under a failing check, so say what was found. */
+    check: (ok: boolean, name: string, detail?: string) => void;
+    /** Deep equality; on failure both values are shown. */
+    equal: <T>(actual: T, expected: T, name: string) => void;
+    /** `text` contains `needle`; on failure the text is shown. */
+    includes: (text: string, needle: string, name: string) => void;
+    /** `text` does not contain `needle`. */
+    excludes: (text: string, needle: string, name: string) => void;
+    /** `text` matches the pattern. */
+    matches: (text: string, pattern: RegExp, name: string) => void;
+    /** `fn` (sync or async) throws an error whose message (or `fix` hint) contains/matches `expected`. */
+    throws: (fn: () => unknown, expected: Expected, name: string) => Promise<void>;
+    /** Runs `fn` and returns the message of the error it throws ('' when it does not throw). */
+    thrownMessage: (fn: () => unknown) => Promise<string>;
+    /** Path below the temp folder (nothing is created). */
+    at: (...parts: string[]) => string;
+    /** Creates (if needed) and returns a folder below the temp folder. */
+    dir: (...parts: string[]) => string;
+    /** Writes a text file below anywhere in the temp folder (parents are created) and returns its path. */
+    write: (file: string, content: string) => string;
+    /** Writes `value` as JSON and returns the path. */
+    writeJson: (file: string, value: unknown) => string;
+    readJson: <T = any>(file: string) => T;
+    /**
+     * Sets a file's modified time to `secondsFromNow` (default: 10 s ahead). Sync decides what changed by comparing
+     * modified times, so tests make a change clearly newer this way instead of sleeping.
+     */
+    touch: (file: string, secondsFromNow?: number) => void;
+    /**
+     * Polls `read` every `everyMs` until it returns something truthy and returns that, or returns null after `ms`.
+     * Use this instead of fixed sleeps: it is fast when the machine is idle and patient when it is busy.
+     */
+    waitFor: <T>(read: () => T | null | undefined | false | Promise<T | null | undefined | false>, ms?: number, everyMs?: number) => Promise<T | null>;
 }
-export declare const createHarness: (packageRoot: string) => Harness & {
+export interface RunningHarness extends Harness {
+    /** Number of checks that failed so far. */
     failures: () => number;
+    /** Number of checks that ran so far (passed or failed). */
+    checks: () => number;
     dispose: () => void;
-};
+}
+export declare const createHarness: (packageRoot: string) => RunningHarness;

package/dist/selftest/harness.js

@@ -1,36 +1,77 @@
-// Minimal test harness: PASS/FAIL lines, a temp folder that is always removed, small helpers.
+// Minimal test harness: PASS/FAIL lines (a failure shows what was expected and what was found), assertion helpers,
+// and a temp folder that is always removed. Every test writes only below `t.temp`.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { inspect, isDeepStrictEqual } from 'node:util';
 import { ensureDir, errMsg, sleep } from '../core/util.js';
+const show = (value) => inspect(value, { depth: 6, breakLength: 110, maxStringLength: 600, maxArrayLength: 40 });
+const indent = (text) => text.split('\n').map((line) => '        ' + line).join('\n');
+const clip = (text, max = 800) => (text.length > max ? text.slice(0, max) + ' ... (' + text.length + ' characters)' : text);
 export const createHarness = (packageRoot) => {
-    let failures = 0;
+    let failed = 0;
+    let total = 0;
     const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-sandbox-test-'));
-    return {
-        packageRoot,
-        temp,
-        failures: () => failures,
-        check: (ok, name) => { console.log((ok ? '\x1b[32mPASS\x1b[0m  ' : '\x1b[31mFAIL\x1b[0m  ') + name); if (!ok)
-            failures++; },
-        rejects: async (fn, needle) => { try {
+    const check = (ok, name, detail) => {
+        total++;
+        console.log((ok ? '\x1b[32mPASS\x1b[0m  ' : '\x1b[31mFAIL\x1b[0m  ') + name);
+        if (ok)
+            return;
+        failed++;
+        if (detail)
+            console.log(indent(detail));
+    };
+    /** Runs `fn` once; the message includes the `fix` hint of a UserError. */
+    const attempt = async (fn) => {
+        try {
             await fn();
-            return false;
+            return { threw: false };
         }
         catch (e) {
-            return (errMsg(e) + ' ' + (e.fix ?? '')).includes(needle);
-        } },
-        write: (file, content) => { ensureDir(path.dirname(file)); fs.writeFileSync(file, content); return file; },
-        waitFor: async (read, ms = 30000) => {
+            return { threw: true, message: (errMsg(e) + ' ' + (e.fix ?? '')).trim() };
+        }
+    };
+    const thrownMessage = async (fn) => {
+        const outcome = await attempt(fn);
+        return outcome.threw ? outcome.message : '';
+    };
+    const write = (file, content) => { ensureDir(path.dirname(file)); fs.writeFileSync(file, content); return file; };
+    return {
+        packageRoot,
+        temp,
+        failures: () => failed,
+        checks: () => total,
+        check,
+        equal: (actual, expected, name) => check(isDeepStrictEqual(actual, expected), name, 'expected: ' + show(expected) + '\nactual:   ' + show(actual)),
+        includes: (text, needle, name) => check(text.includes(needle), name, 'expected to contain: ' + show(needle) + '\nactual: ' + show(clip(text))),
+        excludes: (text, needle, name) => check(!text.includes(needle), name, 'expected NOT to contain: ' + show(needle) + '\nactual: ' + show(clip(text))),
+        matches: (text, pattern, name) => check(pattern.test(text), name, 'expected to match: ' + String(pattern) + '\nactual: ' + show(clip(text))),
+        throws: async (fn, expected, name) => {
+            const outcome = await attempt(fn);
+            const message = outcome.threw ? outcome.message : '';
+            const ok = outcome.threw && (typeof expected === 'string' ? message.includes(expected) : expected.test(message));
+            check(ok, name, 'expected an error containing: ' + String(expected) + '\n' + (outcome.threw ? 'actual error: ' + show(clip(message)) : 'but nothing was thrown'));
+        },
+        thrownMessage,
+        section: (title) => console.log('\n\x1b[36m-- ' + title + '\x1b[0m'),
+        skip: (what) => console.log('SKIP  ' + what),
+        at: (...parts) => path.join(temp, ...parts),
+        dir: (...parts) => { const p = path.join(temp, ...parts); ensureDir(p); return p; },
+        write,
+        writeJson: (file, value) => write(file, JSON.stringify(value)),
+        readJson: (file) => JSON.parse(fs.readFileSync(file, 'utf8')),
+        touch: (file, secondsFromNow = 10) => { const when = new Date(Date.now() + secondsFromNow * 1000); fs.utimesSync(file, when, when); },
+        waitFor: async (read, ms = 30000, everyMs = 100) => {
             const end = Date.now() + ms;
-            while (Date.now() < end) {
-                const v = await read();
-                if (v)
-                    return v;
-                await sleep(250);
+            for (;;) {
+                const value = await read();
+                if (value)
+                    return value;
+                if (Date.now() >= end)
+                    return null;
+                await sleep(everyMs);
             }
-            return null;
         },
-        section: (title) => console.log('\n\x1b[36m-- ' + title + '\x1b[0m'),
         dispose: () => fs.rmSync(temp, { recursive: true, force: true, maxRetries: 5, retryDelay: 300 }),
     };
 };

package/dist/selftest/host-sim.test.d.ts

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

package/dist/selftest/host-sim.test.js

@@ -0,0 +1,93 @@
+// Runs every command and shortcut binary as a separate process in a simulated HOST: none of the sandbox-only folders
+// or variables exist (C:\AgentLaunch, C:\AgentData, CLAUDE_CONFIG_DIR, ...), with a fresh home and storage. Tests
+// usually run inside a sandbox, where those exist, so this is what catches code that only works there. Every command
+// must either succeed or fail with a friendly "Error:" message; a crash or stack trace fails.
+//
+// Each command gets its own home and storage folder, so they cannot disturb each other and run several at a time
+// (every one is a fresh Node process, which is what makes this the slowest suite when run one by one).
+import fs from 'node:fs';
+import path from 'node:path';
+const SANDBOX_ONLY_VARS = ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'GEMINI_CLI_HOME', 'AGENT_WORKSPACE', 'AGENT_DATA', 'AGENT_TOOLS', 'AGENT_PROJECT', 'NVM_HOME', 'NVM_SYMLINK', 'BASH_ENV', 'CLAUDE_CODE_GIT_BASH_PATH', 'AGENT_GIT_ACCESS', 'AGENT_REAL_GIT', 'AGENT_SANDBOX_CONFIG'];
+const PARALLEL = 2;
+const sandbox = (label, ...args) => ({ bin: 'agent-sandbox', label, args, config: true });
+const COMMANDS = [
+    { bin: 'agent-sandbox', label: '--help', args: ['--help'] },
+    sandbox('status', 'status'),
+    sandbox('status --json', 'status', '--json'),
+    sandbox('sessions', 'sessions'),
+    sandbox('doctor', 'doctor'),
+    sandbox('account list', 'account', 'list'),
+    sandbox('account use nobody', 'account', 'use', 'nobody'),
+    { bin: 'agent-sandbox', label: 'config path', args: ['config', 'path'] },
+    sandbox('config show', 'config', 'show'),
+    { bin: 'agent-sandbox', label: 'config schema', args: ['config', 'schema'] },
+    sandbox('clean', 'clean'),
+    sandbox('sync', 'sync'),
+    sandbox('logs', 'logs'),
+    sandbox('attach', 'attach'),
+    { bin: 'agent-sandbox', label: 'exec', args: ['exec'], after: ['--', 'echo', 'hi'], config: true },
+    sandbox('restart', 'restart'),
+    sandbox('stop', 'stop'),
+    sandbox('show', 'show'),
+    sandbox('hide', 'hide'),
+    sandbox('generate', 'generate'),
+    sandbox('launch', 'launch'),
+    { bin: 'agent-sandbox', label: 'unknown command', args: ['frobnicate'] },
+    { bin: 'claude-sbx', label: 'claude-sbx --headless --continue', args: ['--headless', '--continue'], config: true },
+    { bin: 'codex-sbx', label: 'codex-sbx', args: [], config: true },
+    { bin: 'gemini-sbx', label: 'gemini-sbx', args: [], config: true },
+    { bin: 'sbx-show', label: 'sbx-show', args: [], config: true },
+    { bin: 'claude-host', label: 'claude-host --version', args: ['--version'] },
+];
+export const hostSimSuite = {
+    name: 'host-sim',
+    title: 'every command run as its own process on a simulated host PC',
+    timeoutMs: 300000,
+    run: async (t, f) => {
+        t.section('every command outside a sandbox');
+        const baseEnv = Object.fromEntries(Object.entries(process.env).filter(([k]) => !SANDBOX_ONLY_VARS.includes(k)));
+        const project = t.dir('host-sim-project');
+        const envFor = (home) => ({
+            ...baseEnv,
+            AGENT_SANDBOX_HOME: home,
+            AGENT_LAUNCH_DIR: t.at('no-agent-launch'),
+            AGENT_DATA_DIR: t.at('no-agent-data'),
+            AGENT_HOST_TOOLS_DIR: t.at('no-host-tools'),
+            NO_COLOR: '1',
+            // This test may itself run inside a sandbox: the CLI must behave as it would on a PC.
+            AGENT_SANDBOX_HOST_ONLY: '1',
+        });
+        /** A fresh home, storage and config file for one command. */
+        const freshPc = (name) => {
+            const home = t.dir('host-sim', name, 'home');
+            const storage = t.dir('host-sim', name, 'storage');
+            const config = t.writeJson(t.at('host-sim', name, 'config.json'), { storage: { root: storage }, personalization: { enabled: false }, provisioning: { terminal: { enabled: false } } });
+            return { home, config };
+        };
+        const broken = [];
+        const runOne = async (command, index, pc = freshPc('c' + index)) => {
+            const args = command.config ? [...command.args, '--config', pc.config, ...(command.after ?? [])] : command.args;
+            const r = await f.runBin(command.bin, args, { cwd: project, env: envFor(pc.home), timeoutMs: 120000 });
+            const crashed = r.status === null || r.status > 1 || /Unexpected error|node:internal|^\s+at .+:\d+:\d+\)?$/m.test(r.out);
+            const unexplained = r.status === 1 && !/(^|\n)(Error: |error: )/.test(r.out) && command.bin !== 'claude-host';
+            if (crashed || unexplained)
+                broken.push(command.label + ' (exit ' + r.status + (r.timedOut ? ', timed out' : '') + '): ' + r.out.trim().split('\n').slice(0, 4).join(' | '));
+        };
+        // `config init` twice must see the same home (the second run finds the files the first one made).
+        const initPc = freshPc('init');
+        const queue = COMMANDS.map((command, index) => ({ command, index }));
+        const workers = Array.from({ length: PARALLEL }, async () => {
+            for (let next = queue.shift(); next; next = queue.shift())
+                await runOne(next.command, next.index);
+        });
+        const initRuns = (async () => {
+            await runOne({ bin: 'agent-sandbox', label: 'config init', args: ['config', 'init'] }, 1000, initPc);
+            await runOne({ bin: 'agent-sandbox', label: 'config init (again)', args: ['config', 'init'] }, 1001, initPc);
+        })();
+        await Promise.all([...workers, initRuns]);
+        t.equal(broken, [], 'all ' + (COMMANDS.length + 2) + ' commands work or fail with a clear message when run outside a sandbox');
+        for (const file of ['config.json', 'config.schema.json', 'sandbox-config.schema.json']) {
+            t.check(fs.existsSync(path.join(initPc.home, file)), 'on a fresh PC, config init creates ' + file);
+        }
+    },
+};

package/dist/selftest/hostile-input.test.d.ts

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

package/dist/selftest/hostile-input.test.js

@@ -0,0 +1,54 @@
+// Names, paths and text coming from a hostile sandbox or workspace: file names, deletes, printed text, mappings, state
+// files and the launch path.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { assertCmdSafePath } from '../host/platform.js';
+import { assertSafeMapping } from '../core/safe-paths.js';
+import { safeText } from '../core/util.js';
+import { isSafeFileName } from '../shared/paths.js';
+import { removeRefusal, safeRemove } from '../shared/safe-remove.js';
+import { writeJsonAtomic } from '../shared/rundir.js';
+export const hostileInputSuite = {
+    name: 'hostile-input',
+    title: 'file names, deletes, printed text, mappings and state files from an untrusted sandbox',
+    run: async (t) => {
+        t.section('file names');
+        const unsafe = ['CON.jsonl', 'nul', 'aux.json', 'COM1.txt', 'a:b', 'x.jsonl.', 'x ', '..', 'a\\b', 'LPT3'];
+        t.equal(unsafe.filter(isSafeFileName), [], 'device names, streams and trailing dots are not valid names to copy into this PC');
+        const fine = ['C--Workspace-app', 'a.jsonl', '.credentials.json', 'console.jsonl'];
+        t.equal(fine.filter((name) => !isSafeFileName(name)), [], 'ordinary names (even ones that merely contain a device name) are valid');
+        t.section('deletes');
+        const profile = os.homedir();
+        const root = t.at('safe-root');
+        const targets = {
+            'your profile': profile,
+            'a folder above your profile': path.dirname(profile),
+            'a drive root': 'C:\\',
+            Windows: 'C:\\Windows',
+            'an empty path': '',
+            'a relative path': 'relative\\folder',
+            'a path outside the root': t.at('outside-root', 'x'),
+        };
+        for (const [what, target] of Object.entries(targets))
+            t.check(removeRefusal(target, root) !== null, 'a delete is refused for ' + what);
+        t.check(removeRefusal('\\\\?\\C:\\Users\\someone\\x', '\\\\?\\C:\\Users\\someone') !== null, 'a delete is refused for \\\\?\\ paths');
+        t.check(removeRefusal('C:\\Windows\\Temp\\x', 'C:\\Windows\\Temp') !== null, 'a delete is refused inside Windows');
+        t.check(removeRefusal('C:\\Program Files\\x\\y', 'C:\\Program Files\\x') !== null, 'a delete is refused inside Program Files');
+        const allowedTarget = path.join(root, 'tools', 'go');
+        t.write(path.join(allowedTarget, 'go.exe'), 'x');
+        safeRemove(allowedTarget, root);
+        t.check(!fs.existsSync(allowedTarget), 'a folder inside its root is deleted');
+        t.section('text, mappings, state files, launch path');
+        t.equal(safeText('ok \x1b[31mred\x1b[0m \x1b]52;c;ZXZpbA==\x07\x1b]0;title\x07\x1b[2J\x07end'), 'ok \x1b[31mred\x1b[0m end', 'sandbox text printed on this PC keeps colours but loses every other escape sequence');
+        await t.throws(() => assertSafeMapping(path.join(t.packageRoot, 'dist'), t.packageRoot, t.at('storage')), 'overlaps', 'extra mappings may not reach the install folder');
+        await t.throws(() => assertSafeMapping(t.at('storage', 'data'), t.packageRoot, t.at('storage')), 'overlaps', 'extra mappings may not reach the storage folder');
+        const atomicFile = t.at('atomic', 'state.json');
+        writeJsonAtomic(atomicFile, { a: 1 });
+        writeJsonAtomic(atomicFile, { a: 2 });
+        t.equal(t.readJson(atomicFile).a, 2, 'state files are replaced whole...');
+        t.equal(fs.readdirSync(path.dirname(atomicFile)).length, 1, '... with no temp files left behind');
+        await t.throws(() => assertCmdSafePath('C:\\a\\%TEMP%\\agent.wsb'), 'cannot be started safely', 'a launch path with %VAR% (which cmd.exe would expand) is refused');
+        await t.throws(() => assertCmdSafePath('C:\\a"&calc&"\\agent.wsb'), 'cannot be started safely', 'a launch path with quotes and & is refused');
+    },
+};

package/dist/selftest/index.d.ts

@@ -1 +1,8 @@
-export declare const selfTest: (packageRoot: string) => Promise<number>;
+import type { Suite } from './suite.js';
+/** Every suite, in the order they run. The live ones come last: they are the slowest and need Windows. */
+export declare const SUITES: Suite[];
+/** Windows Sandbox (its user is always WDAGUtilityAccount) or a GitHub Actions runner: never someone's PC. */
+export declare const onThrowawayMachine: () => boolean;
+/** Resolves "a,b" / ["a", "b"] to suites; throws with the list of valid names for an unknown one. */
+export declare const pickSuites: (names: string[]) => Suite[];
+export declare const selfTest: (packageRoot: string, suiteNames?: string[]) => Promise<number>;

package/dist/selftest/index.js

@@ -1,55 +1,154 @@
-// `agent-sandbox self-test`: offline logic and security tests, plus live tests of the session daemon, ptyhost and
-// the git guard when running on Windows (they need csc.exe and ConPTY, both part of Windows 10/11).
+// `agent-sandbox self-test [suite...]`: offline logic and security tests, plus live tests of the session daemon, ptyhost
+// and the git guard when running on Windows (they need csc.exe and ConPTY, both part of Windows 10/11).
+// They start real processes (the guest runtime, the daemon, csc, git), so they only run on a throwaway machine.
+//
+// Each area is one suite in its own *.test.ts file; the list below is the order they run in. Give suite names (or a
+// comma-separated list) to run only those: `sandbox self-test config`, `npm test -- live-daemon`.
+import os from 'node:os';
+import path from 'node:path';
 import { errMsg } from '../core/util.js';
-import { configTests } from './config.test.js';
-import { cliTests } from './cli.test.js';
-import { dataTests } from './data.test.js';
-import { detectTests } from './detect.test.js';
-import { mirrorTests } from './mirror.test.js';
 import { createFixtures } from './fixtures.js';
-import { guestTests } from './guest.test.js';
 import { createHarness } from './harness.js';
-import { helperTests } from './helpers.test.js';
-import { hostTests } from './host.test.js';
-import { daemonTests, gitGuardTests, liveTestsAvailable } from './live.test.js';
-import { securityTests } from './security.test.js';
-import { setupTests } from './setup.test.js';
-import { syncTests } from './sync.test.js';
-export const selfTest = async (packageRoot) => {
+import { liveTestsAvailable } from './live.js';
+import { accountsSuite } from './accounts.test.js';
+import { agentCommandsSuite } from './agent-commands.test.js';
+import { channelSuite } from './channel.test.js';
+import { cliSuite } from './cli.test.js';
+import { cmdlineSuite } from './cmdline.test.js';
+import { configSuite } from './config.test.js';
+import { dataSuite } from './data.test.js';
+import { detectSuite } from './detect.test.js';
+import { generateSuite } from './generate.test.js';
+import { gitAccessSuite } from './git-access.test.js';
+import { guestBootSuite } from './guest-boot.test.js';
+import { hostileInputSuite } from './hostile-input.test.js';
+import { hostSimSuite } from './host-sim.test.js';
+import { linksSuite } from './links.test.js';
+import { liveDaemonSuite } from './live-daemon.test.js';
+import { liveGitSuite } from './live-git.test.js';
+import { liveProjectsSuite } from './live-projects.test.js';
+import { localConfigSuite } from './local-config.test.js';
+import { mirrorSuite } from './mirror.test.js';
+import { networkSuite } from './network.test.js';
+import { personalizationSuite } from './personalization.test.js';
+import { projectsSuite } from './projects.test.js';
+import { repairSuite } from './repair.test.js';
+import { repoGuardSuite } from './repo-guard.test.js';
+import { secretsSuite } from './secrets.test.js';
+import { setupSuite } from './setup.test.js';
+import { syncSuite } from './sync.test.js';
+import { testGuardSuite } from './test-guard.test.js';
+import { toolchainsSuite } from './toolchains.test.js';
+import { workspaceSuite } from './workspace.test.js';
+/** Every suite, in the order they run. The live ones come last: they are the slowest and need Windows. */
+export const SUITES = [
+    // settings and project files
+    configSuite, workspaceSuite, localConfigSuite,
+    // the generated sandbox and the guest that boots it
+    generateSuite, guestBootSuite, mirrorSuite, projectsSuite,
+    // syncing with this PC
+    syncSuite, accountsSuite,
+    // an untrusted sandbox: what the host refuses to do with what it finds
+    linksSuite, channelSuite, gitAccessSuite, repoGuardSuite, secretsSuite, hostileInputSuite, testGuardSuite,
+    // pure helpers and the command line
+    toolchainsSuite, detectSuite, networkSuite, personalizationSuite, cmdlineSuite, setupSuite, dataSuite, repairSuite, cliSuite, agentCommandsSuite,
+    // every command as its own process
+    hostSimSuite,
+    // real processes
+    liveDaemonSuite, liveProjectsSuite, liveGitSuite,
+];
+/** Windows Sandbox (its user is always WDAGUtilityAccount) or a GitHub Actions runner: never someone's PC. */
+export const onThrowawayMachine = () => os.userInfo().username.toLowerCase() === 'wdagutilityaccount' || process.env.GITHUB_ACTIONS === 'true';
+const withDeadline = async (work, ms, what) => {
+    let timer;
+    const deadline = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(what + ' did not finish within ' + Math.round(ms / 1000) + ' s')), ms); });
+    try {
+        return await Promise.race([work, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+const runSuite = async (suite, t, f) => {
+    const checksBefore = t.checks();
+    const failedBefore = t.failures();
+    const started = Date.now();
+    let note;
+    if (suite.live && !liveTestsAvailable()) {
+        t.section(suite.name);
+        t.skip(suite.title + ' (needs Windows with the .NET Framework compiler)');
+        note = 'skipped';
+    }
+    else {
+        try {
+            await withDeadline(Promise.resolve(suite.run(t, f)), suite.timeoutMs ?? 120000, 'suite "' + suite.name + '"');
+        }
+        catch (e) {
+            t.check(false, 'suite "' + suite.name + '" stopped with an unexpected error', errMsg(e) + (e instanceof Error && e.stack ? '\n' + e.stack : ''));
+        }
+    }
+    return { suite, checks: t.checks() - checksBefore, failed: t.failures() - failedBefore, seconds: (Date.now() - started) / 1000, note };
+};
+const printSummary = (results) => {
+    const width = Math.max(...results.map((r) => r.suite.name.length));
+    console.log('\n\x1b[36m-- summary\x1b[0m');
+    for (const r of results) {
+        const state = r.note ?? (r.failed ? r.failed + ' FAILED' : 'ok');
+        console.log('  ' + r.suite.name.padEnd(width) + '  ' + String(r.checks).padStart(4) + ' checks  ' + r.seconds.toFixed(1).padStart(6) + ' s  ' + state);
+    }
+    const total = results.reduce((sum, r) => sum + r.checks, 0);
+    console.log('  ' + 'total'.padEnd(width) + '  ' + String(total).padStart(4) + ' checks  ' + results.reduce((sum, r) => sum + r.seconds, 0).toFixed(1).padStart(6) + ' s');
+};
+/** Resolves "a,b" / ["a", "b"] to suites; throws with the list of valid names for an unknown one. */
+export const pickSuites = (names) => {
+    const wanted = names.flatMap((n) => n.split(',')).map((n) => n.trim()).filter(Boolean);
+    if (wanted.length === 0)
+        return SUITES;
+    const unknown = wanted.filter((name) => !SUITES.some((s) => s.name === name));
+    if (unknown.length)
+        throw new Error('No test suite called ' + unknown.join(', ') + '. Suites: ' + SUITES.map((s) => s.name).join(', '));
+    return SUITES.filter((s) => wanted.includes(s.name));
+};
+export const selfTest = async (packageRoot, suiteNames = []) => {
+    if (!onThrowawayMachine()) {
+        console.error('The self-test only runs inside a Windows Sandbox, so it can never change this PC.\nRun it there: `sandbox start` in this folder, then `npm test` in the sandbox\'s terminal.');
+        return 1;
+    }
+    let chosen;
+    try {
+        chosen = pickSuites(suiteNames);
+    }
+    catch (e) {
+        console.error(errMsg(e));
+        return 1;
+    }
+    // Defence in depth (shared/test-guard.ts): with this set, host code refuses outward actions and writes outside temp.
+    process.env.AGENT_SANDBOX_SELFTEST = '1';
     const t = createHarness(packageRoot);
     const saved = { home: process.env.AGENT_SANDBOX_HOME, windir: process.env.WINDIR };
-    process.env.AGENT_SANDBOX_HOME = t.temp + '\\user-home';
+    process.env.AGENT_SANDBOX_HOME = path.join(t.temp, 'user-home');
+    const results = [];
     try {
         const f = createFixtures(t);
-        await configTests(t, f);
-        const launchPath = await guestTests(t, f);
-        await syncTests(t, f);
-        await mirrorTests(t, f);
-        await securityTests(t, f);
-        helperTests(t);
-        detectTests(t);
-        setupTests(t);
-        hostTests(t);
-        dataTests(t);
-        cliTests(t);
-        if (liveTestsAvailable()) {
-            await daemonTests(t, f, launchPath);
-            await gitGuardTests(t, f, launchPath);
-        }
-        else
-            console.log('SKIP  live tests (need Windows with the .NET Framework compiler)');
+        for (const suite of chosen)
+            results.push(await runSuite(suite, t, f));
     }
     catch (e) {
-        t.check(false, 'unexpected error: ' + errMsg(e) + (e instanceof Error && e.stack ? '\n' + e.stack : ''));
+        t.check(false, 'unexpected error: ' + errMsg(e), e instanceof Error ? e.stack : undefined);
     }
     finally {
         if (saved.home === undefined)
             delete process.env.AGENT_SANDBOX_HOME;
         else
             process.env.AGENT_SANDBOX_HOME = saved.home;
-        process.env.WINDIR = saved.windir;
+        if (saved.windir === undefined)
+            delete process.env.WINDIR;
+        else
+            process.env.WINDIR = saved.windir;
         t.dispose();
     }
+    if (results.length > 1)
+        printSummary(results);
     const failures = t.failures();
     console.log(failures === 0 ? '\nALL TESTS PASSED' : '\n' + failures + ' TEST(S) FAILED');
     return failures === 0 ? 0 : 1;

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

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