windows-development-sandbox 1.0.5 → 1.1.0

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

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

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

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

package/dist/selftest/mirror.test.js

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

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

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

package/dist/selftest/network.test.js

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

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

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

package/dist/selftest/personalization.test.js

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

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

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