windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/selftest/fixtures.d.ts

@@ -0,0 +1,272 @@
+import type { Config, HostProbe, ResolvedRun, RunRequest } from '../core/types.js';
+import { generateSandbox } from '../host/generate.js';
+import type { Harness } from './harness.js';
+export declare const HOST_NODE_VERSION = "v22.3.0";
+/** Colour codes are removed from captured output, so tests can match plain text. */
+export declare const stripAnsi: (text: string) => string;
+export interface NodeRun {
+    status: number | null;
+    out: string;
+    timedOut: boolean;
+}
+export interface NodeRunOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+/** Runs `node <args>` and collects stdout + stderr (colours removed). Never throws; a hung process is killed at the timeout. */
+export declare const runNode: (args: string[], options?: NodeRunOptions) => Promise<NodeRun>;
+export declare const createFixtures: (t: Harness) => {
+    at: (...parts: string[]) => string;
+    hostNode: string;
+    hostClaude: string;
+    hostProfile: string;
+    hostGlobalState: string;
+    install: string;
+    workA: string;
+    workB: string;
+    shared: string;
+    makeConfig: (copyFromHost?: boolean) => Config;
+    baseConfig: {
+        defaultHarness: string;
+        guestWorkspace: string;
+        readOnly: boolean;
+        mappings: {
+            host: string;
+            guest: string;
+            readOnly: boolean;
+            optional?: boolean | undefined;
+        }[];
+        sandbox: {
+            memoryMb: number | "auto";
+            maxMemoryMb: number;
+            maxMemoryPercent: number;
+            cpuLimit: number | "none";
+            reserveHostMb: number;
+            vGpu: boolean;
+            networking: boolean;
+            clipboard: boolean;
+            audioInput: boolean;
+            videoInput: boolean;
+            printerRedirection: boolean;
+            protectedClient: boolean;
+            headless: boolean;
+        };
+        storage: {
+            root: string;
+            persistAgentState: boolean;
+            dataName: string;
+        };
+        network: {
+            blockPrivateRanges: boolean;
+        };
+        provisioning: {
+            copyFromHost: boolean;
+            fallbackToInstall: boolean;
+            refresh: boolean;
+            git: {
+                enabled: boolean;
+                access: "readonly" | "full" | "none";
+            };
+            terminal: {
+                enabled: boolean;
+            };
+        };
+        downloads: {
+            requireChecksum: boolean;
+        };
+        toolchains: {
+            node: {
+                version: string;
+                extraVersions: string[];
+                corepack: boolean;
+                volta: boolean | "auto";
+                globalPackages: string[];
+            };
+            python: {
+                enabled: boolean | "auto";
+                version: string;
+                python2: boolean;
+                pyenv: boolean | "auto";
+                tools: string[];
+            };
+            rust: {
+                enabled: boolean | "auto";
+                toolchain: string;
+                host: string;
+                components: string[];
+                targets: string[];
+                crates: string[];
+                targetDir: string;
+            };
+            msvc: {
+                enabled: boolean | "auto";
+                acceptLicense: boolean;
+                msvcVersion: string;
+                sdkVersion: string;
+            };
+            cpp: {
+                enabled: boolean | "auto";
+                flexBison: boolean;
+            };
+            dotnet: {
+                enabled: boolean | "auto";
+                channels: string[];
+                tools: string[];
+                workloads: string[];
+                frameworkTargets: string[];
+                netfx35: boolean;
+            };
+            go: {
+                enabled: boolean | "auto";
+                version: string;
+                tools: string[];
+            };
+            java: {
+                enabled: boolean | "auto";
+                version: string;
+                maven: boolean;
+                gradle: boolean;
+            };
+            ruby: {
+                enabled: boolean | "auto";
+                version: string;
+                gems: string[];
+            };
+            php: {
+                enabled: boolean | "auto";
+                version: string;
+                composer: boolean;
+            };
+            deno: {
+                enabled: boolean | "auto";
+            };
+            pwsh: {
+                enabled: boolean | "auto";
+            };
+            cli: {
+                gh: boolean | "auto";
+                zstd: boolean | "auto";
+                openssl: boolean | "auto";
+            };
+            bun: {
+                enabled: boolean;
+            };
+            uv: {
+                enabled: boolean;
+            };
+            vcRuntime: {
+                enabled: boolean;
+            };
+            mesa: {
+                enabled: boolean;
+                vulkan: boolean;
+            };
+            vscode: {
+                enabled: boolean;
+            };
+            environment: Record<string, string>;
+        };
+        databases: {
+            postgres: {
+                enabled: boolean | "auto";
+                version: string;
+                port: number;
+            };
+            mysql: {
+                enabled: boolean | "auto";
+                version: string;
+                port: number;
+            };
+            mongodb: {
+                enabled: boolean | "auto";
+                version: string;
+                port: number;
+            };
+            redis: {
+                enabled: boolean | "auto";
+                port: number;
+            };
+            dynamodb: {
+                enabled: boolean | "auto";
+                port: number;
+                adminPort: number;
+                admin: boolean;
+            };
+            sqlserver: {
+                enabled: boolean | "auto";
+            };
+        };
+        attach: {
+            enabled: boolean;
+            reuseSession: boolean;
+            auto: boolean;
+            autoHide: boolean;
+        };
+        agentCommands: {
+            enabled: boolean;
+            agents: string[] | "auto";
+        };
+        secrets: {
+            strip: boolean;
+            allow: string[];
+            patterns: string[];
+            warnFiles: boolean;
+        };
+        personalization: {
+            enabled: boolean;
+        };
+        claudeProfile: {
+            enabled: boolean;
+            hostDir: string;
+            include: string[];
+            globalStateFile: string;
+            copyCredentials: boolean;
+            overwrite: boolean;
+            syncHistory: boolean;
+            syncClaudeMem: boolean;
+        };
+        harnesses: Record<string, {
+            arguments: string[];
+            environment: Record<string, string>;
+            hostExecutable?: string | undefined;
+            hostDir?: string | undefined;
+            npmPackage?: string | undefined;
+            npmBin?: string | undefined;
+            uvPackage?: string | undefined;
+            uvBin?: string | undefined;
+            resumeArguments?: string[] | undefined;
+        }>;
+        hooks: {
+            failFast: boolean;
+        };
+        projects: {
+            all: boolean;
+            exclude: string[];
+            roots: string[];
+            askToAddRoot: boolean;
+            declinedRoots: string[];
+            wsbShare: boolean;
+        };
+        $schema?: string | undefined;
+    };
+    probe: HostProbe;
+    run: (over?: Partial<RunRequest>, config?: Config) => Promise<ResolvedRun>;
+    generate: (r: ResolvedRun, args?: string[], p?: HostProbe) => ReturnType<typeof generateSandbox>;
+    launch: (over?: Partial<RunRequest>, options?: {
+        config?: Config;
+        args?: string[];
+        probe?: HostProbe;
+    }) => Promise<ReturnType<typeof generateSandbox>>;
+    writeLocal: (dir: string, content: unknown) => void;
+    historySides: (name: string, hostWorkspace: string, guestWorkspace: string) => {
+        hostClaudeDir: string;
+        guestClaudeDir: string;
+        hostWorkspace: string;
+        guestWorkspace: string;
+    };
+    runGuest: (launchPath: string, data: string, workspace: string, extra?: Record<string, string>) => Promise<NodeRun>;
+    runBin: (name: string, args: string[], options?: NodeRunOptions) => Promise<NodeRun>;
+    readJson: <T = any>(file: string) => T;
+};
+export type Fixtures = ReturnType<typeof createFixtures>;

package/dist/selftest/fixtures.js

@@ -0,0 +1,80 @@
+// A fake "host PC" inside the temp folder: Node, claude.exe, a ~/.claude profile, workspaces, and helpers to resolve a
+// run, generate the sandbox for it, run the guest against it and start the CLI. Shared by all suites.
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { DEFAULTS } from '../core/config.js';
+import { generateSandbox } from '../host/generate.js';
+import { resolveRun } from '../core/workspace.js';
+export const HOST_NODE_VERSION = 'v22.3.0';
+/** Colour codes are removed from captured output, so tests can match plain text. */
+export const stripAnsi = (text) => text.replace(/\x1b\[[0-9;]*m/g, '');
+/** Runs `node <args>` and collects stdout + stderr (colours removed). Never throws; a hung process is killed at the timeout. */
+export const runNode = (args, options = {}) => new Promise((resolve) => {
+    const child = spawn(process.execPath, args, { cwd: options.cwd, env: options.env ?? process.env, windowsHide: true });
+    let out = '';
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; child.kill(); }, options.timeoutMs ?? 120000);
+    child.stdout.on('data', (c) => { out += c.toString(); });
+    child.stderr.on('data', (c) => { out += c.toString(); });
+    child.on('error', (e) => { out += String(e); });
+    child.on('close', (status) => { clearTimeout(timer); resolve({ status: timedOut ? null : status, out: stripAnsi(out), timedOut }); });
+});
+export const createFixtures = (t) => {
+    const { at, write } = t;
+    // The PC: Node with npm, Claude Code, a ~/.claude profile (with a login that must never be copied) and ~/.claude.json.
+    const hostNode = at('host-node');
+    write(path.join(hostNode, 'node.exe'), 'x');
+    write(path.join(hostNode, 'node_modules', 'npm', 'bin', 'npm-cli.js'), '');
+    const hostClaude = at('host-claude');
+    write(path.join(hostClaude, 'claude.exe'), 'fake-claude');
+    const hostProfile = at('host-dot-claude');
+    write(path.join(hostProfile, 'settings.json'), '{ "theme": "dark" }');
+    write(path.join(hostProfile, 'CLAUDE.md'), 'my rules');
+    write(path.join(hostProfile, 'commands', 'review.md'), 'review cmd');
+    write(path.join(hostProfile, 'plugins', 'installed_plugins.json'), JSON.stringify({ path: hostProfile + '\\plugins\\cache\\claude-mem' }));
+    write(path.join(hostProfile, '.credentials.json'), '{ "token": "secret" }');
+    const hostGlobalState = t.writeJson(at('host-claude.json'), { hasCompletedOnboarding: true, mcpServers: { github: { command: 'npx' } } });
+    // The install folder, two workspaces (B has a setup script), a folder to share, the storage root, and tools "from this PC".
+    const install = at('install');
+    t.dir('install', 'sub');
+    const workA = t.dir('work-a');
+    const workB = at('work-b');
+    t.dir('work-b', 'assets');
+    const shared = t.dir('shared');
+    t.dir('storage');
+    write(path.join(workB, 'setup.mjs'), "import fs from 'node:fs'; import path from 'node:path'; fs.writeFileSync(path.join(process.env.AGENT_DATA, 'hook-ran.txt'), process.env.AGENT_WORKSPACE);\n");
+    write(at('host-tools', 'agents', 'claude', 'claude.exe'), 'fake-claude');
+    /** The default config, pointed at the fake PC. `copyFromHost = false` makes the sandbox download everything instead. */
+    const makeConfig = (copyFromHost = true) => {
+        const c = structuredClone(DEFAULTS);
+        c.storage.root = at('storage');
+        c.storage.dataName = 'testdata';
+        c.sandbox.memoryMb = 8192;
+        c.provisioning.copyFromHost = copyFromHost;
+        c.provisioning.terminal.enabled = false;
+        c.harnesses.claude.hostDir = hostClaude;
+        c.claudeProfile = { ...c.claudeProfile, hostDir: hostProfile, globalStateFile: hostGlobalState };
+        c.personalization.enabled = false;
+        c.mappings = [{ host: at('missing-optional'), guest: 'C:\\GameSources\\Missing', readOnly: true, optional: true }];
+        return c;
+    };
+    const baseConfig = makeConfig();
+    const probe = { nodeDir: hostNode, harnessExe: { dir: hostClaude, file: 'claude.exe' }, gitDir: null, nvmDir: null, hostNodeVersion: HOST_NODE_VERSION };
+    /** Resolves a run for `workA` (or whatever `over` says). */
+    const run = (over = {}, config = baseConfig) => resolveRun({ packageRoot: install, loaded: { config, configPath: null, base: t.temp }, cwd: workA, noAgent: false, noLocalConfig: false, trustConfig: false, scripts: [], ...over }, HOST_NODE_VERSION);
+    const generate = (r, args = [], p = probe) => generateSandbox({ packageRoot: t.packageRoot, run: r, harnessArgs: args, probe: p });
+    /** Resolves a run and generates its sandbox (.wsb + launch folder + session.json) in one step. */
+    const launch = async (over = {}, options = {}) => generate(await run(over, options.config ?? baseConfig), options.args, options.probe);
+    /** Writes a project's `.sandbox-config.json` (objects are serialised; strings are written as they are). */
+    const writeLocal = (dir, content) => { write(path.join(dir, '.sandbox-config.json'), typeof content === 'string' ? content : JSON.stringify(content)); };
+    /** The four folders history sync works with, for a workspace on the PC and its place in the sandbox. */
+    const historySides = (name, hostWorkspace, guestWorkspace) => ({ hostClaudeDir: at(name + '-host'), guestClaudeDir: at(name + '-guest'), hostWorkspace, guestWorkspace });
+    /** Runs the guest's bundled main.js in dry-run mode against fake sandbox folders. */
+    const runGuest = async (launchPath, data, workspace, extra = {}) => runNode([path.join(launchPath, 'runtime', 'main.js')], {
+        env: { ...process.env, AGENT_LAUNCH_DIR: launchPath, AGENT_DATA_DIR: data, AGENT_HOST_TOOLS_DIR: at('host-tools'), AGENT_WORKSPACE: workspace, AGENT_LOCAL_DIR: at('local'), AGENT_MANAGED_DIR: at('managed'), AGENT_DRY_RUN: '1', ...extra },
+    });
+    /** Runs a built command (dist/bin/<name>.js) as its own process. */
+    const runBin = (name, args, options = {}) => runNode([path.join(t.packageRoot, 'dist', 'bin', name + '.js'), ...args], options);
+    const readJson = t.readJson;
+    return { at, hostNode, hostClaude, hostProfile, hostGlobalState, install, workA, workB, shared, makeConfig, baseConfig, probe, run, generate, launch, writeLocal, historySides, runGuest, runBin, readJson };
+};

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

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

package/dist/selftest/generate.test.js

@@ -0,0 +1,63 @@
+// What the host generates for a sandbox: the .wsb file, the launch folder (runtime, C# sources, boot scripts),
+// session.json, the staged Claude profile, and the values read from this PC (git identity, free RAM).
+import fs from 'node:fs';
+import path from 'node:path';
+import { LocalOverrides } from '../core/schema.js';
+import { gitIdentity } from '../host/launch/stage.js';
+import { buildWsb, resolveMemoryMb } from '../host/launch/wsb.js';
+export const generateSuite = {
+    name: 'generate',
+    title: 'generated .wsb, launch folder and session.json',
+    run: async (t, f) => {
+        t.section('the .wsb file');
+        const gen = await f.launch({}, { args: ['--version'], probe: { ...f.probe, gitDir: f.shared, nvmDir: f.workB } });
+        const wsb = fs.readFileSync(gen.wsbPath, 'utf8');
+        t.includes(wsb, '<MemoryInMB>8192</MemoryInMB>', 'wsb: the configured memory');
+        t.includes(wsb, '<SandboxFolder>C:\\Workspace\\work-a</SandboxFolder>', 'wsb: the workspace is mapped to its guest folder');
+        t.includes(wsb, 'C:\\HostTools\\git', 'wsb: this PC\'s git is mapped');
+        t.includes(wsb, 'C:\\HostTools\\nvm', 'wsb: this PC\'s nvm is mapped');
+        t.excludes(wsb, 'Missing', 'wsb: an optional mapping whose folder is missing is skipped');
+        t.includes(wsb, 'logon.cmd</Command>', 'wsb: the logon command');
+        t.includes(wsb, '<vGPU>Disable</vGPU>', 'wsb: vGPU is off');
+        t.includes(buildWsb(f.baseConfig, 4096, [{ host: 'C:\\a&b', guest: 'C:\\X', readOnly: true }]), 'C:\\a&amp;b', 'wsb values are XML-escaped');
+        t.section('the launch folder');
+        const expectedFiles = ['package.json', 'runtime/main.js', 'runtime/daemon.js', 'runtime/view.js', 'runtime/gitguard.js', 'sandbox/bootstrap.ps1', 'sandbox/logon.cmd', 'sandbox/trust.cmd', 'sandbox/ptyhost.cs', 'sandbox/gitshim.cs'];
+        const missing = expectedFiles.filter((file) => !fs.existsSync(path.join(gen.launchPath, file)));
+        t.equal(missing, [], 'the launch folder has the runtime, the C# sources and the boot scripts');
+        t.equal(fs.readdirSync(path.join(gen.launchPath, 'runtime')).length, 5, 'the runtime is 5 self-contained files');
+        const logon = fs.readFileSync(path.join(gen.launchPath, 'sandbox', 'logon.cmd'), 'utf8');
+        t.check(logon.indexOf('trust.cmd') < logon.indexOf('wt.exe'), 'logon.cmd applies the sandbox trust settings before opening Windows Terminal');
+        t.includes(logon, 'tools\\terminal\\wt.exe', 'logon.cmd opens Windows Terminal from the tools folder');
+        t.includes(logon, '-NoExit', 'logon.cmd falls back to a PowerShell window');
+        t.section('session.json');
+        const session = f.readJson(gen.sessionPath);
+        t.equal({
+            launchId: session.launchId === gen.launchId,
+            workspace: session.workspace,
+            workspaceHost: session.workspaceHost,
+            firstArgument: session.harnessArguments[0],
+            gitFromHost: Boolean(session.hostTools.git),
+            nvmFromHost: Boolean(session.hostTools.nvm),
+            nodeSpec: session.versions.node.spec,
+            gitAccess: session.provisioning.git.access,
+        }, { launchId: true, workspace: 'C:\\Workspace\\work-a', workspaceHost: f.workA, firstArgument: '--version', gitFromHost: true, nvmFromHost: true, nodeSpec: '22.3.0', gitAccess: 'full' }, 'session.json carries the id, paths, agent arguments, host tools, versions and git access');
+        t.matches(session.hostTools.nodeVersion ?? '', /^\d+\.\d+\.\d+$/, 'session.json: the host Node version is a plain version');
+        t.equal(session.cpuLimitPercent, 80, 'session.json carries the CPU cap for cpucap.ps1 (default 80 %)');
+        t.check(!LocalOverrides.safeParse({ sandbox: { cpuLimit: 'none' } }).success, "a project's .sandbox-config.json cannot lift your CPU cap (sandbox.cpuLimit is yours only)");
+        t.section('what is copied from this PC');
+        const staged = path.join(gen.launchPath, 'claude-profile');
+        const stagedMissing = ['settings.json', 'CLAUDE.md', '.claude.json', 'plugins'].filter((name) => !fs.existsSync(path.join(staged, name)));
+        t.equal(stagedMissing, [], 'Claude settings, instructions, global state and plugins are staged');
+        t.check(!fs.existsSync(path.join(staged, '.credentials.json')), 'the Claude login is not staged');
+        const gitconfig = '[user]\n\tname = Josh\n\temail = "j@x.io"\n[credential]\n\thelper = store\n[url "https://TOKEN@github.com/"]\n\tinsteadOf = https://github.com/\n';
+        t.equal(gitIdentity(gitconfig), '[user]\n\tname = Josh\n\temail = j@x.io\n', 'only name/email from ~/.gitconfig reach the sandbox (no credential helpers or token URLs)');
+        t.equal(gitIdentity('[core]\n\tname = x\n'), '', 'a name outside [user] is not an identity');
+        const auto = { ...f.baseConfig.sandbox, memoryMb: 'auto' };
+        const MB = 1048576;
+        const pcRam = 64 * 1024 * MB;
+        t.equal(resolveMemoryMb(auto, 40000 * MB, pcRam), 31744, "memory 'auto' follows free RAM minus the reserve");
+        await t.throws(() => resolveMemoryMb(auto, 9000 * MB, pcRam), 'Not enough free RAM', "memory 'auto' refuses when too little RAM is free");
+        t.equal(resolveMemoryMb({ ...auto, maxMemoryPercent: 80 }, 30000 * MB, 32 * 1024 * MB), 21504, "memory 'auto' never takes more than maxMemoryPercent of the PC's RAM");
+        t.equal(resolveMemoryMb({ ...auto, maxMemoryPercent: 50 }, 60000 * MB, pcRam), 32768, "memory 'auto' is capped at half the PC's RAM with maxMemoryPercent 50 (free RAM and maxMemoryMb still apply)");
+    },
+};

package/dist/selftest/git-access.test.d.ts

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

package/dist/selftest/git-access.test.js

@@ -0,0 +1,26 @@
+// Git access modes ("full", "readonly", "none"): which git commands the guard allows and the matching Claude deny rules.
+import { gitDecision } from '../guest/gitguard.js';
+import { gitDenyRules } from '../guest/gitrules.js';
+export const gitAccessSuite = {
+    name: 'git-access',
+    title: 'git access modes and Claude deny rules',
+    run: (t) => {
+        t.section('readonly');
+        const allowed = (args, mode = 'readonly') => gitDecision(args, mode).allow;
+        const reading = ['status', 'log --oneline', 'diff HEAD~1', 'show HEAD', 'blame a.ts', 'branch', 'branch -a', 'branch --contains HEAD', 'tag', 'tag -l v*', 'remote -v', 'config --get user.name', 'stash list', '-C sub status', '--no-pager log'];
+        t.equal(reading.filter((command) => !allowed(command.split(' '))), [], 'readonly: reading commands are allowed');
+        const writing = ['commit -m x', 'push', 'add .', 'checkout main', 'switch -c x', 'reset --hard', 'stash', 'stash pop', 'branch new', 'branch -D x', 'tag v1', 'merge x', 'rebase main', 'fetch', 'pull', 'config user.name x', 'remote add o u', '-c core.hooksPath=x status', '--git-dir=x status', 'clean -fd', 'apply p.diff'];
+        t.equal(writing.filter((command) => allowed(command.split(' '))), [], 'readonly: anything that writes (or overrides config) is refused');
+        t.section('none and full');
+        t.check(!allowed(['status'], 'none') && !allowed(['--version'], 'none'), 'none: every git call is refused');
+        t.check(allowed(['commit'], 'full'), 'full: everything is allowed');
+        t.section('Claude managed deny rules');
+        const readonlyRules = gitDenyRules('readonly');
+        const noneRules = gitDenyRules('none');
+        t.equal(gitDenyRules('full').length, 0, 'full: no deny rules');
+        t.includes(readonlyRules.join('\n'), 'Bash(git push:*)', 'readonly: pushing is denied');
+        t.check(!readonlyRules.some((r) => r.startsWith('Read(')), 'readonly: reading .git is not denied');
+        t.check(noneRules.includes('Bash(git:*)'), 'none: every git command is denied');
+        t.check(noneRules.includes('Read(**/.git/**)'), 'none: reading .git is denied too');
+    },
+};

package/dist/selftest/guest-boot.test.d.ts

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

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

@@ -0,0 +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;
+    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 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;