windows-development-sandbox 1.0.5 → 1.4.0

package/dist/selftest/fixtures.d.ts

@@ -2,6 +2,20 @@ import type { Config, HostProbe, ResolvedRun, RunRequest } from '../core/types.j
 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;
@@ -17,6 +31,18 @@ export declare const createFixtures: (t: Harness) => {
         defaultHarness: string;
         guestWorkspace: string;
         readOnly: boolean;
+        workspaceFilter: {
+            enabled: boolean;
+            exclude: string[];
+            include: string[];
+        };
+        audit: {
+            enabled: boolean;
+            days: number;
+            maxMb: number;
+            processes: boolean;
+            files: boolean;
+        };
         mappings: {
             host: string;
             guest: string;
@@ -26,6 +52,9 @@ export declare const createFixtures: (t: Harness) => {
         sandbox: {
             memoryMb: number | "auto";
             maxMemoryMb: number;
+            maxMemoryPercent: number;
+            cpuLimit: number | "none";
+            pageFileMb: number;
             reserveHostMb: number;
             vGpu: boolean;
             networking: boolean;
@@ -35,14 +64,25 @@ export declare const createFixtures: (t: Harness) => {
             printerRedirection: boolean;
             protectedClient: boolean;
             headless: boolean;
+            keepAwake: boolean;
         };
         storage: {
             root: string;
             persistAgentState: boolean;
             dataName: string;
+            markSandboxFiles: boolean;
+            warnDataGb: number;
         };
         network: {
             blockPrivateRanges: boolean;
+            allowOnly: string[];
+            blockHosts: string[];
+            forwardPorts: {
+                pc: number;
+                sandbox: number;
+            }[];
+            dns: string[];
+            proxy: string;
         };
         provisioning: {
             copyFromHost: boolean;
@@ -55,6 +95,12 @@ export declare const createFixtures: (t: Harness) => {
             terminal: {
                 enabled: boolean;
             };
+            conpty: {
+                enabled: boolean;
+            };
+        };
+        downloads: {
+            requireChecksum: boolean;
         };
         toolchains: {
             node: {
@@ -145,6 +191,9 @@ export declare const createFixtures: (t: Harness) => {
             };
             vscode: {
                 enabled: boolean;
+                setup: boolean;
+                recommended: boolean;
+                extensions: string[];
             };
             environment: Record<string, string>;
         };
@@ -184,6 +233,10 @@ export declare const createFixtures: (t: Harness) => {
             auto: boolean;
             autoHide: boolean;
         };
+        agentCommands: {
+            enabled: boolean;
+            agents: string[] | "auto";
+        };
         secrets: {
             strip: boolean;
             allow: string[];
@@ -193,6 +246,19 @@ export declare const createFixtures: (t: Harness) => {
         personalization: {
             enabled: boolean;
         };
+        apps: {
+            install: string[];
+            custom: Record<string, {
+                name: string;
+                exe: string;
+                github?: string | undefined;
+                asset?: string | undefined;
+                url?: string | undefined;
+                sha256?: string | undefined;
+                unpack?: "file" | "archive" | "nsis" | "msi" | undefined;
+                cli?: boolean | undefined;
+            }>;
+        };
         claudeProfile: {
             enabled: boolean;
             hostDir: string;
@@ -201,7 +267,9 @@ export declare const createFixtures: (t: Harness) => {
             copyCredentials: boolean;
             overwrite: boolean;
             syncHistory: boolean;
+            historyScope: "project" | "all";
             syncClaudeMem: boolean;
+            syncClaudeMemBack: boolean;
         };
         harnesses: Record<string, {
             arguments: string[];
@@ -217,16 +285,33 @@ export declare const createFixtures: (t: Harness) => {
         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;
-    runGuest: (launchPath: string, data: string, workspace: string, extra?: Record<string, string>) => {
-        status: number | null;
-        out: string;
+    historySides: (name: string, hostWorkspace: string, guestWorkspace: string) => {
+        hostClaudeDir: string;
+        guestClaudeDir: string;
+        hostWorkspace: string;
+        guestWorkspace: string;
     };
-    readJson: (file: string) => any;
+    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

@@ -1,16 +1,27 @@
-// A fake "host PC" inside the temp folder: Node, claude.exe, a ~/.claude profile, workspaces, and helpers to resolve,
-// generate and run the guest against it.
-import fs from 'node:fs';
+// 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 { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { DEFAULTS } from '../core/config.js';
 import { generateSandbox } from '../host/generate.js';
-import { ensureDir } from '../core/util.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 { temp, write } = t;
-    const at = (...parts) => path.join(temp, ...parts);
+    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'), '');
@@ -22,16 +33,18 @@ export const createFixtures = (t) => {
     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 = write(at('host-claude.json'), JSON.stringify({ hasCompletedOnboarding: true, mcpServers: { github: { command: 'npx' } } }));
+    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');
-    ensureDir(path.join(install, 'sub'));
-    const workA = at('work-a');
+    t.dir('install', 'sub');
+    const workA = t.dir('work-a');
     const workB = at('work-b');
-    const shared = at('shared');
-    for (const d of [workA, workB, shared, path.join(workB, 'assets'), at('storage')])
-        ensureDir(d);
+    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');
@@ -47,17 +60,23 @@ export const createFixtures = (t) => {
     };
     const baseConfig = makeConfig();
     const probe = { nodeDir: hostNode, harnessExe: { dir: hostClaude, file: 'claude.exe' }, gitDir: null, nvmDir: null, hostNodeVersion: HOST_NODE_VERSION };
-    const run = (over = {}, config = baseConfig) => resolveRun({ packageRoot: install, loaded: { config, configPath: null, base: 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 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) => 
+    // A fixed "this PC has" list, so "auto" toolchains decide the same on every machine the tests run on.
+    generateSandbox({ packageRoot: t.packageRoot, run: r, harnessArgs: args, probe: p, pcLanguages: ['python', 'rust', 'cpp', 'dotnet'] });
+    /** 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 = (launchPath, data, workspace, extra = {}) => {
-        const r = spawnSync(process.execPath, [path.join(launchPath, 'runtime', 'main.js')], {
-            encoding: 'utf8',
-            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 },
-        });
-        return { status: r.status, out: (r.stdout ?? '') + (r.stderr ?? '') };
-    };
-    const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
-    return { at, hostNode, hostClaude, hostProfile, hostGlobalState, install, workA, workB, shared, makeConfig, baseConfig, probe, run, generate, writeLocal, runGuest, readJson };
+    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,68 @@
+// 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 { logonEnv } from '../host/generate.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', 'sandbox/cpucap.ps1', 'sandbox/cpucap.cs', 'sandbox/pagefile.ps1', 'sandbox/pagefile.cs', 'sandbox/memlog.ps1'];
+        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, 6, 'the runtime is 6 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.check(logon.indexOf('env.cmd') > 0 && logon.indexOf('env.cmd') < logon.indexOf('wt.exe'), 'logon.cmd sets AGENT_WORKSPACE (env.cmd) before Windows Terminal starts, so new tabs can open in it');
+        t.includes(fs.readFileSync(path.join(gen.launchPath, 'env.cmd'), 'utf8'), 'AGENT_WORKSPACE=', 'env.cmd names the workspace');
+        t.equal(logonEnv('C:\\Workspace\\100%\\x'), '@set "AGENT_WORKSPACE=C:\\Workspace\\100%%\\x"\r\n', 'a % in the workspace path is escaped for cmd');
+        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.equal(session.pageFileMb, 16384, 'session.json carries the paging file limit for pagefile.ps1 (default 16 GB)');
+        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

@@ -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;