windows-development-sandbox 1.0.5 → 1.1.0

package/dist/selftest/projects.test.js

@@ -0,0 +1,254 @@
+// Several projects in one sandbox: guest paths, the safety of what gets mapped, joining a running sandbox (roots,
+// wsb share, the restart fallback), the project spec sent to the guest, tighten-only protections, the per-project
+// environment, history sync and the repo guard for every project. Offline: temp folders only.
+import fs from 'node:fs';
+import path from 'node:path';
+import { LocalOverrides } from '../core/schema.js';
+import { checkJoin, protectionsOf } from '../core/project-policy.js';
+import { sessionsFirstIn } from '../host/channel.js';
+import { buildWsb } from '../host/launch/wsb.js';
+import { projectSpec, joinRunning } from '../host/join.js';
+import { allProjectsToMap, forgetProject, NeedsRestart, projectHere, projectMapper, readKnown, readRegistry, rememberProject, startRegistry } from '../host/projects.js';
+import { checkRepo, saveRepoSnapshot } from '../host/repo-guard.js';
+import { findWsb, parseCommands, parseIp, parseList, parseVersion } from '../host/wsb.js';
+import { baseEnvFor } from '../guest/project-env.js';
+import { guestDirFor, hostDirFor, hubName, insideProjects, isBelow, isWithin, planProjectMappings, projectForGuestDir, projectForHostDir, PROJECTS_GUEST } from '../shared/projects.js';
+import { GuestRequest, ProjectSpec } from '../shared/schema.js';
+import { projectFolderName } from '../shared/paths.js';
+import { syncHistoryOut } from '../sync/history.js';
+import { validateOptions, validateProjectsArgs } from '../cli/validate.js';
+import { parseCli, parseSessionWant } from '../cli/args.js';
+import { candidateFolders, severalAgentsArgv } from '../cli/menu-multi.js';
+import { generateSandbox } from '../host/generate.js';
+import { askedWhen } from '../cli/manifest.js';
+import { describeSessions } from '../cli/commands/restart.js';
+/** The error `fn` throws, or null. */
+const caught = (fn) => { try {
+    fn();
+    return null;
+}
+catch (e) {
+    return e;
+} };
+export const projectsSuite = {
+    name: 'projects',
+    title: 'several projects in one sandbox (paths, joining, policy, specs, --session)',
+    run: async (t, f) => {
+        t.section('projects: guest paths');
+        t.check(isWithin('C:\\code\\a', 'c:\\CODE\\a\\src') && isWithin('C:\\code\\a\\', 'C:\\code\\a'), 'isWithin: case-insensitive, trailing slashes ignored');
+        t.check(!isWithin('C:\\code\\a', 'C:\\code\\ab') && !isWithin('C:\\code\\a', 'C:\\code'), 'isWithin: no prefix matches (a vs ab) and no parents');
+        t.equal(hubName('F:\\Code\\my app (v2)', []), 'my-app-v2', 'project ids are file-name safe');
+        t.equal(hubName('F:\\Code\\api', ['API', 'api-2']), 'api-3', 'project ids are unique (case-insensitive)');
+        t.equal(hubName('F:\\Code\\...', []), 'project', 'project ids are never empty');
+        t.equal(hubName('F:\\' + 'x'.repeat(80), []).length, 48, 'project ids are capped at 48 characters');
+        const projects = [{ host: 'F:\\Code', guest: 'C:\\Projects\\Code' }, { host: 'F:\\Code\\api', guest: 'C:\\Projects\\api' }];
+        t.equal(projectForHostDir(projects, 'f:\\code\\api\\src')?.guest, 'C:\\Projects\\api', 'the most specific mapped folder wins');
+        t.equal(projectForHostDir(projects, 'F:\\Code\\web')?.guest, 'C:\\Projects\\Code', 'a folder inside a mapped folder belongs to it');
+        t.equal(projectForHostDir(projects, 'F:\\Other'), null, 'unrelated folders belong to no project');
+        t.equal(projectForGuestDir(projects, 'C:\\Projects\\api\\x')?.host, 'F:\\Code\\api', 'the same works from inside the sandbox');
+        const mapped = { host: 'F:\\Code', guest: 'C:\\Projects\\Code' };
+        const webGuest = guestDirFor(mapped, 'F:\\Code\\web\\src');
+        t.equal(webGuest, 'C:\\Projects\\Code\\web\\src', 'host folder -> guest folder');
+        t.equal(hostDirFor(mapped, webGuest), 'F:\\Code\\web\\src', 'guest folder -> host folder (round trip)');
+        t.equal(guestDirFor(mapped, 'F:\\Code'), 'C:\\Projects\\Code', 'the mapped folder itself translates');
+        t.check(insideProjects('C:\\Projects\\api') && insideProjects('c:\\projects\\api\\src'), 'C:\\Projects\\<name> holds projects');
+        t.check(!insideProjects('C:\\Projects') && !insideProjects('C:\\ProjectsX\\a') && !insideProjects('C:\\Windows'), 'C:\\Projects itself and look-alikes do not');
+        t.check(insideProjects('F:\\Code\\web', ['F:\\Code']) && !insideProjects('F:\\Other', ['F:\\Code']), 'a mirrored root counts too');
+        t.check(isBelow('C:\\a', 'C:\\a\\b') && !isBelow('C:\\a', 'C:\\a'), 'isBelow is strict');
+        const plan = planProjectMappings(['F:\\Code', 'E:\\Work\\Code', 'C:\\Users\\me\\src'], ['D:\\x\\api', 'D:\\y\\api'], false);
+        t.equal(plan.roots.map((r) => r.guest), ['C:\\Projects\\Code', 'C:\\Projects\\Code-2', 'C:\\Projects\\src'], 'roots get unique C:\\Projects\\<name> folders');
+        t.equal(plan.projects.map((p) => p.guest), ['C:\\Projects\\api', 'C:\\Projects\\api-2'], 'projects get unique C:\\Projects\\<name> folders');
+        const mirror = planProjectMappings(['F:\\Code', 'C:\\Users\\me\\src'], [], true);
+        t.equal(mirror.roots.map((r) => r.guest), ['F:\\Code', 'C:\\Projects\\src'], 'with "mirror" a root appears at its PC path when the sandbox can show it there (C:\\Users\\... cannot)');
+        t.section('projects: tighten-only protections when joining a running sandbox');
+        const base = protectionsOf(f.baseConfig);
+        const same = checkJoin(base, base);
+        t.equal({ stricter: same.stricter, looser: same.looser }, { stricter: [], looser: [] }, 'the same settings join without notes');
+        const readonlyGit = protectionsOf({ ...f.baseConfig, provisioning: { ...f.baseConfig.provisioning, git: { ...f.baseConfig.provisioning.git, access: 'readonly' } } });
+        t.check(checkJoin(base, readonlyGit).stricter.some((s) => s.startsWith('provisioning.git.access')), 'a project needing stricter git access than the running sandbox is refused (git access is machine-wide)');
+        const loosening = checkJoin(readonlyGit, base);
+        t.equal(loosening.stricter.length, 0, 'a project asking for less git access is not refused...');
+        t.check(loosening.looser.some((s) => s.includes('provisioning.git.access stays "readonly"')), '... it gets the sandbox\'s stricter value, with a note: never loosened', JSON.stringify(loosening.looser));
+        const offline = protectionsOf({ ...f.baseConfig, sandbox: { ...f.baseConfig.sandbox, networking: false } });
+        t.check(checkJoin(base, offline).stricter.some((s) => s.startsWith('sandbox.networking')), 'networking off is stricter than a sandbox with networking');
+        t.check(checkJoin(offline, base).looser.some((s) => s.startsWith('sandbox.networking')), 'networking on is looser than an offline sandbox');
+        const readOnly = protectionsOf({ ...f.baseConfig, readOnly: true });
+        t.check(checkJoin(readOnly, readOnly).stricter.some((s) => s.startsWith('readOnly')), 'a read-only project cannot join (other projects are mapped read/write), even when the launch folder was read-only');
+        t.check(!LocalOverrides.safeParse({ projects: { roots: ['C:\\'] } }).success, 'a project\'s .sandbox-config.json can never set projects.roots (they map folders of this PC)');
+        t.check(!LocalOverrides.safeParse({ projects: { all: true } }).success, 'a project\'s .sandbox-config.json can never set projects.all');
+        // A project file that loosens git access is clamped by keepStrictest first, then joins without being refused.
+        const strictUser = structuredClone(f.baseConfig);
+        strictUser.provisioning.git.access = 'readonly';
+        const looseDir = t.dir('proj-loose');
+        f.writeLocal(looseDir, { provisioning: { git: { access: 'full' } } });
+        const loose = await f.run({ cwd: looseDir, trustConfig: true }, strictUser);
+        t.equal(loose.config.provisioning.git.access, 'readonly', 'tighten-only: a project file cannot loosen git access');
+        t.equal(checkJoin(protectionsOf(strictUser), protectionsOf(loose.config)).stricter, [], 'tighten-only: so it joins a readonly sandbox as readonly');
+        const tightDir = t.dir('proj-tight');
+        f.writeLocal(tightDir, { provisioning: { git: { access: 'none' } } });
+        const tight = await f.run({ cwd: tightDir, trustConfig: true });
+        t.section('projects: registry and joining');
+        const storage = t.at('proj-storage');
+        const data = path.join(storage, 'data', 'testdata');
+        t.dir('proj-storage', 'data', 'testdata');
+        const root = t.at('proj-root');
+        const inRoot = t.dir('proj-root', 'web');
+        const outside = t.dir('proj-outside');
+        const primary = startRegistry(storage, { launchId: '1700000000000-abcdef', protections: base, primary: { host: f.workA, guest: 'C:\\Workspace\\work-a' }, roots: [{ host: root, guest: 'C:\\Projects\\proj-root' }], boot: [{ host: f.workB, guest: 'C:\\Projects\\work-b' }] });
+        const registry = readRegistry(storage);
+        t.check(primary.primary, 'at launch the launch folder is the primary project');
+        t.equal(registry?.projects.length, 2, 'at launch the registry holds the launch folder and the projects mapped with it');
+        t.equal({ mechanism: registry?.projects[1].mechanism, name: registry?.projects[1].name }, { mechanism: 'boot', name: 'work-b' }, 'a project mapped at boot is registered by its mechanism and name');
+        t.equal(projectHere(storage, path.join(f.workA, 'src'))?.guestDir, 'C:\\Workspace\\work-a\\src', 'projectHere: a folder inside the launch folder');
+        t.equal(projectHere(storage, f.workB)?.project.mechanism, 'boot', 'projectHere: a project mapped at boot');
+        t.equal(projectHere(storage, outside), null, 'projectHere: a folder in no project');
+        const noWsb = projectMapper({ storageRoot: storage, packageRoot: f.install, wsbShare: true, detect: () => null });
+        const web = noWsb.register(inRoot);
+        t.equal({ mechanism: web.mechanism, guest: web.guest }, { mechanism: 'root', guest: 'C:\\Projects\\proj-root\\web' }, 'a folder inside a root joins at once (also one created after boot)');
+        t.equal(noWsb.register(inRoot).name, web.name, 'registering the same folder again gives the same project');
+        t.equal(readRegistry(storage)?.projects.filter((p) => p.host === inRoot).length, 1, 'a folder is registered once');
+        const needs = caught(() => noWsb.register(outside));
+        t.check(needs instanceof NeedsRestart && needs.reason.includes('wsb share needs Windows 11 24H2'), 'a folder outside every root without the Windows Sandbox CLI needs a restart (and says why)');
+        const shareOff = caught(() => projectMapper({ storageRoot: storage, packageRoot: f.install, wsbShare: false }).register(outside));
+        t.check(shareOff instanceof NeedsRestart && shareOff.reason.includes('projects.wsbShare'), 'projects.wsbShare off goes straight to the restart offer');
+        const fakeWsb = { exe: t.at('no-such-wsb.exe'), version: '0.1.0', commands: ['share', 'list'], has: (c) => c === 'share' || c === 'list' };
+        const listFails = caught(() => projectMapper({ storageRoot: storage, packageRoot: f.install, wsbShare: true, detect: () => fakeWsb }).register(outside));
+        t.check(listFails instanceof NeedsRestart && listFails.reason.includes('wsb share could not find the running sandbox'), 'when wsb cannot tell which sandbox is ours, it falls back to the restart offer with the reason');
+        await t.throws(() => noWsb.register(storage), 'cannot be the workspace', 'joining uses the launch-folder safety checks: not the storage folder');
+        await t.throws(() => noWsb.register('C:\\'), 'whole drive', 'joining uses the launch-folder safety checks: not a drive root');
+        await t.throws(() => noWsb.unregister(primary.name), 'stays until the sandbox stops', 'the launch folder cannot be removed from a running sandbox');
+        // joinRunning: resolves the folder, checks protections, registers it, guards it, and builds the spec for the guest.
+        const resolveFor = (run) => async () => run;
+        const join = (hostDir, resolve) => joinRunning({ storageRoot: storage, dataPath: data, packageRoot: f.install, hostDir, wsbShare: false, resolve });
+        const webRun = await f.run({ cwd: inRoot, trustConfig: true });
+        const joined = await join(inRoot, resolveFor(webRun));
+        t.equal(joined.spec?.workspace, 'C:\\Projects\\proj-root\\web', 'joining a project builds a spec with its guest folder...');
+        t.check(ProjectSpec.safeParse(joined.spec).success && joined.spec?.harnesses.claude !== undefined, '... that is valid and carries the agent');
+        t.check(readKnown(storage).some((k) => k.host === inRoot), 'joined projects are remembered (projects.all, sandbox projects)');
+        const launchFolder = await join(path.join(f.workA, 'sub'), () => Promise.reject(new Error('must not resolve')));
+        t.equal(launchFolder.spec, null, 'the launch folder (and below) needs no spec: its sessions use the boot environment');
+        await t.throws(() => join(tightDir, resolveFor(tight)), 'stricter protection than the running sandbox', 'a project whose .sandbox-config.json tightens git access beyond the running sandbox is refused, with the reason');
+        t.check(readRegistry(storage)?.projects.every((p) => p.host !== tightDir) === true, 'a refused project is not registered');
+        const outsideRun = await f.run({ cwd: outside });
+        await t.throws(() => join(outside, resolveFor(outsideRun)), 'projects.wsbShare', 'a folder that cannot be shown lets NeedsRestart reach the caller');
+        t.section('projects: the spec and request the guest gets');
+        const spec = projectSpec(webRun, web, false);
+        const sessionRequest = (extra) => GuestRequest.safeParse({ kind: 'session', id: 'r1', harness: 'claude', args: [], cwd: spec.workspace, createdAt: new Date().toISOString(), ...extra });
+        t.check(sessionRequest({ project: spec }).success, 'a session request carries a project spec');
+        t.check(sessionRequest({ project: spec, harnessSpec: f.baseConfig.harnesses.codex }).success, 'a session request carries an agent definition');
+        t.check(!sessionRequest({ project: { ...spec, name: '..\\evil' } }).success, 'specs are validated: project ids are file-name safe');
+        t.check(!sessionRequest({ project: { ...spec, extra: 1 } }).success, 'specs are validated: no unknown keys');
+        const manyDatabases = Array(9).fill(spec.databases[0] ?? { database: 'redis', reasons: [], version: 'x', port: 6379 });
+        t.check(!sessionRequest({ project: { ...spec, databases: manyDatabases } }).success, 'specs are validated: lists are capped');
+        const manyAgents = Object.fromEntries(Array.from({ length: 9 }, (_, i) => ['a' + i, f.baseConfig.harnesses.codex]));
+        t.check(!sessionRequest({ project: { ...spec, harnesses: manyAgents } }).success, 'at most 8 agent definitions in one spec');
+        t.check(GuestRequest.safeParse({ kind: 'project', id: 'p1', project: spec, createdAt: 'x' }).success, '"project" requests (set up without an agent) carry a spec');
+        t.check(!GuestRequest.safeParse({ kind: 'project', id: 'p1', createdAt: 'x' }).success, '"project" requests need a spec');
+        t.check(GuestRequest.safeParse({ kind: 'restart', id: 'x', harness: null, cwd: 'C:\\Projects\\a', createdAt: 'x' }).success, 'restart can be scoped to one project\'s folder');
+        t.check(GuestRequest.safeParse({ kind: 'restart', id: 'x', harness: null, createdAt: 'x' }).success, 'restart still works without a folder');
+        t.section('projects: which projects are mapped at boot');
+        const toMap = allProjectsToMap(['C:\\a', 'C:\\a\\b', 'C:\\work-a\\x', 'C:\\r\\p', 'C:\\ex\\y', 'C:\\gone'], { primary: 'C:\\work-a', roots: ['C:\\r'], exclude: ['C:\\ex'], exists: (p) => p !== 'C:\\gone' });
+        t.equal(toMap, ['C:\\a'], 'projects.all: known projects except excluded, missing, nested, the launch folder\'s and the roots\'');
+        const rootConfig = structuredClone(f.baseConfig);
+        rootConfig.projects = { ...rootConfig.projects, roots: [root, t.at('no-such-root')], all: true };
+        rememberProject(f.baseConfig.storage.root, outside);
+        const gen = f.generate(await f.run({}, rootConfig));
+        const session = f.readJson(gen.sessionPath);
+        const wsb = fs.readFileSync(gen.wsbPath, 'utf8');
+        t.equal(gen.projects.roots.map((r) => r.guest), ['C:\\Projects\\proj-root'], 'roots are mapped as C:\\Projects\\<name>');
+        t.check(gen.projects.notes.some((n) => n.includes('no-such-root')), 'a missing root is skipped with a note', JSON.stringify(gen.projects.notes));
+        t.check(gen.projects.projects.some((p) => p.host === outside), 'projects.all maps the known projects too');
+        t.includes(wsb, '<HostFolder>' + root + '</HostFolder><SandboxFolder>C:\\Projects\\proj-root</SandboxFolder><ReadOnly>false</ReadOnly>', 'roots are mapped read/write in the .wsb');
+        t.equal({ projectsDir: session.projectsDir, roots: session.roots, projectId: session.projectId }, { projectsDir: PROJECTS_GUEST, roots: ['C:\\Projects\\proj-root'], projectId: 'work-a' }, 'session.json tells the guest where other projects can be');
+        const badRoot = structuredClone(f.baseConfig);
+        badRoot.projects = { ...badRoot.projects, roots: [f.baseConfig.storage.root] };
+        await t.throws(async () => f.generate(await f.run({}, badRoot)), 'projects.roots', 'a root that would expose the storage folder is refused');
+        t.check(forgetProject(f.baseConfig.storage.root, outside), '`sandbox projects remove` forgets a project...');
+        t.check(!readKnown(f.baseConfig.storage.root).some((k) => k.host === outside), '... so it is no longer known (its folder is untouched)');
+        t.includes(buildWsb(f.baseConfig, 4096, []), '<MappedFolders></MappedFolders>', 'no projects: nothing extra mapped');
+        t.section('projects: repo guard for every project the sandbox can write');
+        const guardData = t.at('guard-data');
+        const rootG = t.at('guard-root');
+        const old = path.join(rootG, 'old');
+        t.write(path.join(old, '.git', 'hooks', 'pre-commit'), 'mine');
+        t.write(path.join(old, '.git', 'config'), '[core]\n\tbare = false\n');
+        saveRepoSnapshot(guardData, f.workA, [], [rootG]);
+        t.write(path.join(old, '.git', 'hooks', 'post-checkout'), 'planted');
+        const fresh = path.join(rootG, 'created-later');
+        t.write(path.join(fresh, '.git', 'hooks', 'pre-push'), 'planted');
+        t.write(path.join(fresh, '.git', 'config'), '[core]\n\tfsmonitor = evil.exe\n\tbare = false\n');
+        t.write(path.join(fresh, 'node.exe'), 'planted');
+        const found = checkRepo(guardData);
+        t.check(fs.existsSync(path.join(old, '.git', 'hooks', 'pre-commit')), 'a hook that was there before the sandbox ran stays');
+        t.check(!fs.existsSync(path.join(old, '.git', 'hooks', 'post-checkout')), 'a hook added inside the sandbox to a project in a root is quarantined');
+        t.check(!fs.existsSync(path.join(fresh, '.git', 'hooks', 'pre-push')), 'a project that appeared in a root after the start has its planted hooks removed');
+        t.check(!fs.existsSync(path.join(fresh, 'node.exe')), 'a project that appeared in a root after the start has its planted commands removed');
+        t.includes(fs.readFileSync(path.join(fresh, '.git', 'config'), 'utf8'), '# [agent-sandbox] disabled', 'a project that appeared in a root after the start has its program-running git config disabled');
+        t.check(found.some((x) => x.detail.startsWith(fresh)), 'the findings name the project', JSON.stringify(found));
+        t.section('projects: history and environment');
+        const hostClaude = t.at('hist-host');
+        const guestClaude = t.at('hist-guest');
+        const bHost = t.at('hist-b');
+        t.write(path.join(guestClaude, 'projects', projectFolderName('C:\\Projects\\hist-b'), 's.jsonl'), JSON.stringify({ cwd: 'C:\\Projects\\hist-b\\src' }) + '\n');
+        syncHistoryOut({ hostClaudeDir: hostClaude, guestClaudeDir: guestClaude, hostWorkspace: f.workA, guestWorkspace: 'C:\\Workspace\\work-a', extra: [{ hostWorkspace: bHost, guestWorkspace: 'C:\\Projects\\hist-b' }] });
+        const back = path.join(hostClaude, 'projects', projectFolderName(bHost), 's.jsonl');
+        t.check(fs.existsSync(back), 'a joined project\'s history goes back to ITS folder on this PC');
+        t.includes(fs.existsSync(back) ? fs.readFileSync(back, 'utf8') : '', JSON.stringify(bHost + '\\src').slice(1, -1), 'a joined project\'s history paths are translated');
+        const env = baseEnvFor({ basePath: 'C:\\Windows', toolVars: ['NVM_HOME', 'CARGO_HOME'], steps: {}, summary: [], lan: 'blocked' }, { Path: 'C:\\tools\\a;C:\\Windows', NVM_HOME: 'x', CARGO_HOME: 'y', CARGO_TARGET_DIR: 'C:\\Workspace\\a\\target', AGENT_WORKSPACE: 'C:\\Workspace\\a', TEMP: 'C:\\t' });
+        t.equal({ PATH: env.PATH, Path: env.Path, NVM_HOME: env.NVM_HOME, CARGO_TARGET_DIR: env.CARGO_TARGET_DIR, AGENT_WORKSPACE: env.AGENT_WORKSPACE, TEMP: env.TEMP }, { PATH: 'C:\\Windows', Path: undefined, NVM_HOME: undefined, CARGO_TARGET_DIR: undefined, AGENT_WORKSPACE: undefined, TEMP: 'C:\\t' }, 'a joined project starts from the boot\'s base environment: none of the first project\'s tools, workspace or target folder');
+        t.section('projects: commands');
+        const status = (id, cwd, startedAt) => ({ id, launchId: 'l', harness: 'claude', cwd, phase: 'running', message: '', updatedAt: startedAt, startedAt });
+        const sessions = [status('a1', 'C:\\Workspace\\a', '1'), status('b1', 'C:\\Projects\\b', '2'), status('a2', 'C:\\Workspace\\a\\x', '3'), status('b2', 'C:\\Projects\\b\\y', '4')];
+        t.equal(sessionsFirstIn(sessions, 'C:\\Projects\\b').map((x) => x.id), ['b2', 'b1', 'a2', 'a1'], 'attach and sessions put this project\'s sessions first, newest first');
+        t.equal(describeSessions([{ harness: 'claude', cwd: 'C:\\Workspace\\api', project: 'api' }, { harness: 'codex', cwd: 'C:\\Projects\\web' }]), '2 sessions (claude in api, codex in web)', 'the restart offer lists the sessions that would end');
+        await t.throws(() => validateProjectsArgs(['bogus']), 'projects action', '`sandbox projects` rejects an unknown action');
+        await t.throws(() => validateProjectsArgs(['add']), 'Which folder', '`sandbox projects add` needs a folder');
+        await t.throws(() => validateProjectsArgs(['all', 'maybe']), 'on', '`sandbox projects all` needs on or off');
+        await t.throws(() => validateProjectsArgs(['roots', 'add']), 'Which folder', '`sandbox projects roots add` needs a folder');
+        validateProjectsArgs([]);
+        validateProjectsArgs(['roots']);
+        validateProjectsArgs(['all', 'on']);
+        t.check(askedWhen(['add', 'remove'], 'add') && !askedWhen(['add'], 'list') && askedWhen(undefined, 'x') && askedWhen('save', 'save'), 'the menu asks an argument only for the actions it belongs to');
+        t.section('projects: several sessions at once (--session agent@folder)');
+        const want = parseSessionWant('claude@C:\\code\\a@b', 'C:\\here');
+        t.equal({ harness: want.harness, folder: want.folder }, { harness: 'claude', folder: 'C:\\code\\a@b' }, '--session: the first @ splits agent from folder');
+        t.equal(parseSessionWant('codex', 'C:\\here').folder, 'C:\\here', '--session: no folder means this one');
+        t.equal(parseSessionWant('gemini@sub', 'C:\\here').folder, 'C:\\here\\sub', '--session: relative folders become absolute');
+        await t.throws(() => parseSessionWant('@C:\\x'), 'names no agent', '--session without an agent is refused');
+        const own = parseSessionWant('codex@C:\\code\\web|--model o3 "two words"', 'C:\\here');
+        t.equal({ harness: own.harness, folder: own.folder, args: own.args }, { harness: 'codex', folder: 'C:\\code\\web', args: ['--model', 'o3', 'two words'] }, '--session: after | come that agent\'s own arguments (quotes keep words together)');
+        t.equal(parseSessionWant('claude@C:\\x').args, undefined, '--session: no | means no own arguments');
+        const both = parseCli(['launch', '--session', 'claude@C:\\a|--continue', '--session', 'codex@C:\\b', '--', '--verbose']);
+        t.equal(both.passthrough, ['--verbose'], 'arguments after -- go to every session...');
+        t.equal(both.sessions.map((s) => s.args ?? []), [['--continue'], []], '... arguments after | only to that one');
+        const multi = parseCli(['launch', '--session', 'claude@' + f.workA, '--session', 'codex@' + f.workB, '--session', 'claude@' + f.workB, '-t', '--', '--continue']);
+        t.equal({ command: multi.command, sessions: multi.sessions.length, terminal: multi.terminal, second: multi.sessions[1].harness, passthrough: multi.passthrough }, { command: 'launch', sessions: 3, terminal: true, second: 'codex', passthrough: ['--continue'] }, 'several --session options parse in order, with -t and agent arguments');
+        const validationContext = (options) => ({ packageRoot: f.install, entry: '', options, loaded: { config: f.baseConfig, configPath: null, base: t.temp }, storageRoot: f.baseConfig.storage.root, dataPath: t.at('vdata') });
+        await t.throws(() => validateOptions(validationContext(parseCli(['launch', '--session', 'claud@' + f.workA]))), 'Did you mean', 'an unknown agent in --session suggests the closest one');
+        await t.throws(() => validateOptions(validationContext(parseCli(['launch', '--session', 'claude@' + t.at('nope')]))), 'does not exist', 'a missing --session folder is refused before anything starts');
+        await t.throws(() => validateOptions(validationContext(parseCli(['launch', '--session', 'claude@' + f.workA, '--harness', 'codex']))), 'do not apply', '--session cannot be mixed with --harness/--workspace');
+        validateOptions(validationContext(multi));
+        t.equal(severalAgentsArgv([{ harness: 'claude', folder: 'C:\\a' }, { harness: 'codex', folder: 'C:\\b c' }], { headless: true, attachFirst: true }).join(' '), 'launch --session claude@C:\\a --session codex@C:\\b c --headless -t', 'the menu builds the same command line (so repeat-last works)');
+        t.equal(candidateFolders(validationContext(parseCli(['launch'])), f.workA)[0], path.resolve(f.workA), 'the menu offers this folder first, then known projects and the folders in your roots');
+        const multiGen = generateSandbox({ packageRoot: t.packageRoot, run: await f.run(), harnessArgs: [], probe: f.probe, extraProjects: [f.workB, path.join(f.workA, 'sub'), f.workB], autoSession: false });
+        const multiSession = f.readJson(multiGen.sessionPath);
+        const multiWsb = fs.readFileSync(multiGen.wsbPath, 'utf8');
+        t.equal(multiGen.projects.projects.map((p) => p.guest), ['C:\\Projects\\work-b'], 'a multi-project launch maps every other project once (folders inside the launch folder and duplicates need nothing)');
+        t.includes(multiWsb, '<HostFolder>' + f.workB + '</HostFolder><SandboxFolder>C:\\Projects\\work-b</SandboxFolder>', 'a multi-project launch maps the other project in the .wsb');
+        t.equal({ autoSession: multiSession.autoSession, workspaceHost: multiSession.workspaceHost }, { autoSession: false, workspaceHost: f.workA }, 'the boot provisions the launch folder only; the host then opens every session (each project set up on demand, in parallel)');
+        t.section('projects: wsb (Windows Sandbox command line) adapter');
+        t.equal([parseVersion('Windows Sandbox CLI version 0.4.1.0\n'), parseVersion('nothing')], ['0.4.1.0', null], 'wsb --version');
+        const help = 'Description:\n  Windows Sandbox command line\n\nUsage:\n  wsb [command] [options]\n\nOptions:\n  --version  Show version information\n\nCommands:\n  start    Starts a sandbox\n  list     Lists sandboxes\n  exec     Runs a command\n  share    Shares a folder\n  stop     Stops a sandbox\n  connect  Connects\n  ip       Shows the IP\n';
+        t.equal(parseCommands(help), ['start', 'list', 'exec', 'share', 'stop', 'connect', 'ip'], 'wsb --help: the subcommands it offers');
+        t.equal(parseCommands('no commands here').length, 0, 'wsb --help: no commands in other text');
+        const id = '12345678-1234-1234-1234-1234567890ab';
+        t.equal(parseList(JSON.stringify([{ Id: id, Status: 'Running', Uptime: '00:10' }]))[0]?.id, id, 'wsb list --raw: an array');
+        t.equal(parseList(JSON.stringify({ WindowsSandboxEnvironments: [{ id, status: 'Stopped' }] }))[0]?.status, 'Stopped', 'wsb list --raw: an object holding one');
+        t.equal(parseList('Id                                    Status   Uptime\n' + id + '  Running  00:01:02\n')[0]?.status, 'Running', 'wsb list as a table');
+        t.equal(parseList('nothing').length, 0, 'wsb list: nothing to read gives no sandboxes');
+        t.equal([parseIp('172.20.1.5\r\n'), parseIp('none')], ['172.20.1.5', null], 'wsb ip');
+        const apps = 'C:\\Users\\me\\AppData\\Local\\Microsoft\\WindowsApps\\wsb.exe';
+        t.equal(findWsb({ LOCALAPPDATA: 'C:\\Users\\me\\AppData\\Local', SystemRoot: 'C:\\Windows' }, (p) => p === apps), apps, 'wsb.exe is looked for at absolute paths only (WindowsApps alias, System32)');
+        t.equal(findWsb({ SystemRoot: 'C:\\Windows' }, () => false), null, 'wsb.exe is not found when nothing is there');
+    },
+};

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

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

package/dist/selftest/repair.test.js

@@ -0,0 +1,42 @@
+// `sandbox repair`: finding half-installed toolchains, interrupted downloads, stale pid files and broken state.
+import path from 'node:path';
+import { deadPidFiles, findHalfInstalled, findStagingLeftovers, globalPackages, resolvedVersionsValid } from '../cli/commands/repair/finders.js';
+export const repairSuite = {
+    name: 'repair',
+    title: 'repair detection (half-installed tools, leftovers, stale pids)',
+    run: (t) => {
+        t.section('tools folder');
+        const tools = t.at('repair', 'tools');
+        t.write(path.join(tools, 'go', '1.23.2', 'bin', 'go.exe'), 'x');
+        t.dir('repair', 'tools', 'go', '1.22.8', 'src');
+        t.write(path.join(tools, 'java', 'jdk-21', 'bin', 'java.exe'), 'x');
+        t.dir('repair', 'tools', 'java', 'jdk-17', 'lib');
+        t.write(path.join(tools, 'python', 'python-3.12.7', 'python.exe'), 'x');
+        t.write(path.join(tools, 'nvm', 'settings.txt'), 'x');
+        t.write(path.join(tools, 'nvm', 'v22.11.0', 'node.exe'), 'x');
+        t.dir('repair', 'tools', 'nvm', 'v20.18.0');
+        t.write(path.join(tools, 'git', 'bin', 'bash.exe'), 'x');
+        t.dir('repair', 'tools', 'dotnet', 'sdk');
+        t.dir('repair', 'tools', 'go', '1.24.0.staging-ab12cd');
+        t.dir('repair', 'tools', 'node-staging');
+        t.dir('repair', 'tools', 'rust.staging-0f');
+        const half = findHalfInstalled(tools).map((h) => path.relative(tools, h.path)).sort();
+        const expectedHalf = [path.join('go', '1.22.8'), path.join('java', 'jdk-17'), 'dotnet', 'nvm', path.join('nvm', 'v20.18.0')].sort();
+        t.equal(half, expectedHalf, 'half-installed toolchains are folders without their program');
+        const leftovers = findStagingLeftovers(tools).map((p) => path.relative(tools, p)).sort();
+        t.equal(leftovers, [path.join('go', '1.24.0.staging-ab12cd'), 'node-staging', 'rust.staging-0f'].sort(), 'interrupted downloads are found in tools and one level down');
+        t.section('state files');
+        t.check(resolvedVersionsValid('{"go":"1.23.2"}') && resolvedVersionsValid('{}'), 'resolved-versions.json: a JSON object is valid (a byte-order mark is fine)');
+        t.check(!resolvedVersionsValid('{"go":') && !resolvedVersionsValid('[1]'), 'resolved-versions.json: broken JSON and non-objects are invalid');
+        t.equal(globalPackages('{"dependencies":{"agent-sandbox":{"version":"1.0.0"},"npm":{}}}'), ['agent-sandbox', 'npm'], '`npm ls -g --json` output is read');
+        t.equal(globalPackages('nope'), [], '`npm ls -g` output that is not JSON gives no packages');
+        t.equal(globalPackages('{"dependencies":3}'), [], '`npm ls -g` output of the wrong shape gives no packages');
+        const run = t.at('repair', 'run');
+        t.write(path.join(run, 'watcher-default.pid'), '4242');
+        t.write(path.join(run, 'watcher-other.pid'), String(process.pid));
+        t.write(path.join(run, 'watcher-junk.pid'), 'not a pid');
+        t.write(path.join(run, 'hidden-windows.json'), '[]');
+        const dead = deadPidFiles(run, (pid) => pid === process.pid).map((file) => path.basename(file)).sort();
+        t.equal(dead, ['watcher-default.pid', 'watcher-junk.pid'], 'stale watcher pid files (dead process or junk) are found; a live one is kept');
+    },
+};

package/dist/selftest/repo-guard.test.d.ts

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

package/dist/selftest/repo-guard.test.js

@@ -0,0 +1,63 @@
+// Repository guard (zero-click code execution on this PC): after the sandbox ran, hooks, program-running git config
+// and commands planted in the repository are quarantined before anything on this PC can run them.
+import fs from 'node:fs';
+import path from 'node:path';
+import { guardRepo, snapshotRepo } from '../host/repo-guard.js';
+export const repoGuardSuite = {
+    name: 'repo-guard',
+    title: 'repository guard (hooks, git config, planted commands, replaced .git)',
+    run: (t) => {
+        const readConfig = (repo) => fs.readFileSync(path.join(repo, '.git', 'config'), 'utf8');
+        const disabled = (keyPattern) => new RegExp('# \\[agent-sandbox\\] disabled.*' + keyPattern);
+        t.section('hooks and git config');
+        const repo = t.at('repo');
+        t.write(path.join(repo, '.git', 'config'), '[core]\n\trepositoryformatversion = 0\n[remote "origin"]\n\turl = https://example.com/x.git\n');
+        t.write(path.join(repo, '.git', 'hooks', 'pre-commit.sample'), 'sample');
+        t.write(path.join(repo, '.git', 'hooks', 'pre-push'), 'existing hook');
+        const before = snapshotRepo(repo);
+        t.write(path.join(repo, '.git', 'hooks', 'post-checkout'), 'calc.exe');
+        t.write(path.join(repo, '.git', 'hooks', 'pre-push'), 'changed hook');
+        fs.appendFileSync(path.join(repo, '.git', 'config'), '[core]\n\tfsmonitor = calc.exe\n\tsshCommand = evil\n[include]\n\tpath = C:/evil.cfg\n[branch "feature"]\n\tremote = origin\n');
+        const findings = guardRepo(repo, before);
+        t.check(!fs.existsSync(path.join(repo, '.git', 'hooks', 'post-checkout')), 'a new git hook is quarantined');
+        t.check(!fs.existsSync(path.join(repo, '.git', 'hooks', 'pre-push')), 'a changed git hook is quarantined');
+        t.check(fs.existsSync(path.join(repo, '.git', 'hooks', 'pre-commit.sample')), 'hook samples are left alone');
+        t.equal(findings.filter((x) => x.kind === 'hook').length, 2, 'both hooks are reported');
+        const config = readConfig(repo);
+        t.matches(config, disabled('fsmonitor'), 'git config: fsmonitor (runs a program) is disabled');
+        t.matches(config, disabled('sshCommand'), 'git config: sshCommand is disabled');
+        t.matches(config, disabled('path = C:/evil'), 'git config: [include] of an outside file is disabled');
+        t.matches(config, /^\tremote = origin$/m, 'git config: a harmless change stays');
+        t.matches(config, /^\turl = https/m, 'git config: existing lines stay');
+        t.equal(guardRepo(repo, before).length, 0, 'the guard is idempotent');
+        t.section('planted commands and tricks');
+        const repo2 = t.at('repo2');
+        t.write(path.join(repo2, '.git', 'config'), '[core]\n\tbare = false\n');
+        t.write(path.join(repo2, 'build.cmd'), 'echo legit');
+        const before2 = snapshotRepo(repo2);
+        for (const name of ['node.exe', 'git.cmd', 'sandbox.cmd', 'opencode.ps1'])
+            t.write(path.join(repo2, name), name === 'node.exe' ? 'MZ' : 'calc');
+        t.write(path.join(repo2, '.git', 'commondir'), 'C:/evil');
+        fs.appendFileSync(path.join(repo2, '.git', 'config'), '[core] fsmonitor = calc.exe\n');
+        const found2 = guardRepo(repo2, before2);
+        const gone = ['node.exe', 'git.cmd', 'sandbox.cmd', 'opencode.ps1'].filter((name) => !fs.existsSync(path.join(repo2, name)));
+        t.equal(gone, ['node.exe', 'git.cmd', 'sandbox.cmd', 'opencode.ps1'], 'executables planted under command names are quarantined');
+        t.check(fs.existsSync(path.join(repo2, 'build.cmd')), 'other scripts stay');
+        t.equal(found2.filter((x) => x.kind === 'command').length, 4, 'every planted command is reported');
+        t.check(!fs.existsSync(path.join(repo2, '.git', 'commondir')), 'a planted commondir is removed');
+        t.matches(readConfig(repo2), disabled('fsmonitor'), 'a key on the same line as its [section] is neutralised');
+        t.section('a replaced or oversized .git');
+        const victim = t.dir('repo-victim');
+        const repo3 = t.at('repo3');
+        t.write(path.join(repo3, '.git', 'config'), '[core]\n');
+        const before3 = snapshotRepo(repo3);
+        fs.rmSync(path.join(repo3, '.git'), { recursive: true });
+        fs.symlinkSync(victim, path.join(repo3, '.git'), 'junction');
+        t.check(guardRepo(repo3, before3).some((x) => x.kind === 'git' && x.detail.includes('replaced')), '.git replaced by a link is reported loudly');
+        const repo4 = t.at('repo4');
+        t.write(path.join(repo4, '.git', 'config'), '[core]\n');
+        const before4 = snapshotRepo(repo4);
+        fs.appendFileSync(path.join(repo4, '.git', 'config'), '#'.repeat(5 * 1024 * 1024));
+        t.check(guardRepo(repo4, before4).some((x) => x.kind === 'git' && x.detail.includes('over 4 MB')), 'a git config too big to check is reported instead of passing');
+    },
+};

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

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

package/dist/selftest/secrets.test.js

@@ -0,0 +1,71 @@
+// What reaches the sandbox from this PC's Claude files, and what is stripped first: API keys, cloud credentials, tokens in
+// MCP server definitions. Also the secret-looking files in a workspace that the launch warns about.
+import path from 'node:path';
+import { sandboxGlobalState } from '../host/claude-profile.js';
+import { findSecretFiles, stripMcpServers, stripSettings } from '../host/secrets.js';
+const REMOVED = '[removed by agent-sandbox]';
+export const secretsSuite = {
+    name: 'secrets',
+    title: 'credentials stripped from everything copied into the sandbox',
+    run: (t) => {
+        t.section('~/.claude.json');
+        const state = sandboxGlobalState({
+            primaryApiKey: 'sk-secret',
+            oauthAccount: { emailAddress: 'me' },
+            mcpServers: { a: {} },
+            theme: 'dark',
+            projects: { 'D:/Code/app': { mcpServers: { db: { env: { TOKEN: 'mine' } } } }, 'D:/Other': { mcpServers: { x: { env: { TOKEN: 'other' } } } } },
+        }, 'D:\\Code\\app');
+        const stateText = JSON.stringify(state);
+        t.check(!('primaryApiKey' in state), 'the sandbox never gets your API key');
+        t.check(!('oauthAccount' in state), 'the sandbox never gets your signed-in account');
+        t.includes(stateText, 'mine', 'the sandbox gets this project\'s MCP servers');
+        t.excludes(stateText, 'other', 'the sandbox never gets other projects');
+        t.equal(state.theme, 'dark', 'ordinary settings are kept');
+        t.section('settings.json');
+        const secrets = { strip: true, allow: ['AWS_REGION'], patterns: ['ACME_*'], warnFiles: true };
+        const removed = [];
+        const settings = stripSettings({
+            apiKeyHelper: 'aws-vault exec prod -- get-key',
+            model: 'opus',
+            env: {
+                AWS_ACCESS_KEY_ID: 'x', AWS_SECRET_ACCESS_KEY: 'y', AWS_REGION: 'eu-west-2', AZURE_CLIENT_SECRET: 'z', ARM_CLIENT_ID: 'id', CLOUDFLARE_API_TOKEN: 't',
+                GOOGLE_APPLICATION_CREDENTIALS: 'C:\\key.json', PROD_DB_HOST: 'db.internal', STRIPE_KEY: 'k', ACME_THING: 'a', DATABASE_URL: 'postgres://u:p@h/db',
+                INNOCENT: 'AKIAABCDEFGHIJKLMNOP', SAFE_URL: 'https://example.com', DISABLE_TELEMETRY: '1', CLAUDE_CODE_USE_BEDROCK: '1',
+            },
+        }, secrets, removed);
+        const env = settings.env;
+        t.check(!('apiKeyHelper' in settings) && settings.model === 'opus', 'settings: the API key helper goes, ordinary settings stay');
+        t.equal(Object.keys(env).sort(), ['AWS_REGION', 'CLAUDE_CODE_USE_BEDROCK', 'DISABLE_TELEMETRY', 'SAFE_URL'], 'settings: AWS, Azure, Google, Cloudflare, prod, payment and database credentials (by name or by value) stay on this PC; secrets.allow and ordinary settings pass');
+        t.check(removed.some((r) => r.endsWith('AWS_SECRET_ACCESS_KEY')), 'settings: what was removed is reported', JSON.stringify(removed));
+        t.equal(JSON.stringify(stripSettings({ env: { AWS_SECRET_ACCESS_KEY: 'y' } }, { ...secrets, strip: false }, [])), '{"env":{"AWS_SECRET_ACCESS_KEY":"y"}}', 'secrets.strip = false copies settings unchanged');
+        t.section('MCP servers');
+        const mcp = stripMcpServers({
+            mcpServers: { gh: { command: 'npx', args: ['server', '--api-key', 'plain', '--verbose', 'ghp_abcdefghijklmnopqrstuvwxyz0123456789'], env: { GITHUB_TOKEN: 'g', LOG_LEVEL: 'debug' } } },
+            projects: { 'D:/app': { mcpServers: { api: { type: 'http', url: 'https://x', headers: { Authorization: 'Bearer abcdefghijklmnopqrstuvwxyz', Accept: 'json' } } } } },
+        }, secrets, []);
+        const gh = mcp.mcpServers.gh;
+        const api = mcp.projects['D:/app'].mcpServers.api;
+        t.equal(gh.args, ['server', '--api-key', REMOVED, '--verbose', REMOVED], 'MCP servers: key arguments and token-looking arguments are removed');
+        t.equal(gh.env, { LOG_LEVEL: 'debug' }, 'MCP servers: token env vars are removed, the rest stays');
+        t.equal(api.headers, { Accept: 'json' }, 'MCP servers: Authorization headers are removed');
+        const sneaky = stripMcpServers({
+            mcpServers: {
+                r: {
+                    type: 'http', url: 'https://mcp.example.com/mcp?api_key=0123456789abcdef&region=eu',
+                    headers: { 'X-API-Key': 'k', 'x-auth-token': 't', Accept: 'json' },
+                    args: ['--api-key=deadbeefdeadbeef', '--header', 'Authorization: Bearer abcdefghijklmnopqrstuvwxyz', '--port=8080'],
+                },
+            },
+        }, secrets, []);
+        const r = sneaky.mcpServers.r;
+        t.equal(r.url, 'https://mcp.example.com/mcp?api_key=REMOVED&region=eu', 'MCP servers: ?api_key= in URLs is removed');
+        t.equal(r.headers, { Accept: 'json' }, 'MCP servers: X-API-Key style headers are removed');
+        t.equal([r.args[0], r.args[2], r.args[3]], [REMOVED, REMOVED, '--port=8080'], 'MCP servers: --flag=value keys and "Authorization: Bearer" arguments are removed, ordinary flags stay');
+        t.section('secret-looking files in the workspace');
+        const workspace = t.at('secret-ws');
+        for (const file of ['.env', '.env.example', 'server.pem', 'README.md', 'api/credentials.json', 'node_modules/x/.env'])
+            t.write(path.join(workspace, file), 'x');
+        t.equal(findSecretFiles(workspace).sort(), ['.env', 'api\\credentials.json', 'server.pem'], 'secret-looking workspace files are found for the launch warning (templates and dependencies ignored)');
+    },
+};

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

@@ -1,2 +1,2 @@
-import type { Harness } from './harness.js';
-export declare const setupTests: (t: Harness) => void;
+import type { Suite } from './suite.js';
+export declare const setupSuite: Suite;

package/dist/selftest/setup.test.js

@@ -1,23 +1,46 @@
-// `agent-sandbox setup`: the pure pieces of the machine checklist.
-import { buildChecks, canEnableFeature, editionSupport, featureFromInstallState, nodeMajor, parseDismState, parseProbe, parseRegQuery } from '../cli/commands/setup.js';
-export const setupTests = (t) => {
-    const { check } = t;
-    t.section('setup checklist');
-    const reg = parseRegQuery('\r\nHKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\r\n    CurrentBuild    REG_SZ    22631\r\n    EditionID    REG_SZ    Professional\r\n    ProductName    REG_SZ    Windows 10 Pro\r\n    InstallDate    REG_DWORD    0x65a1b2c3\r\n');
-    check(reg.EditionID === 'Professional' && reg.CurrentBuild === '22631' && reg.ProductName === 'Windows 10 Pro', 'reg query output parses into name/value pairs');
-    check(editionSupport('Professional') === 'supported' && editionSupport('EnterpriseS') === 'supported' && editionSupport('EducationN') === 'supported' && editionSupport('Core') === 'home' && editionSupport('CoreSingleLanguage') === 'home' && editionSupport('ServerStandard') === 'unsupported' && editionSupport('Weird') === 'unknown' && editionSupport(null) === 'unknown', 'editions: Pro/Enterprise/Education yes, Home and Server no');
-    const dism = (state) => 'Deployment Image Servicing and Management tool\r\n\r\nFeature Name : Containers-DisposableClientVM\r\nDisplay Name : Windows Sandbox\r\nRestart Required : Possible\r\nState : ' + state + '\r\n';
-    check(parseDismState(dism('Enabled')) === 'enabled' && parseDismState(dism('Enable Pending')) === 'pending' && parseDismState(dism('Disabled')) === 'disabled' && parseDismState(dism('Disabled with Payload Removed')) === 'disabled' && parseDismState('Error: 740\r\nElevated permissions are required') === 'unknown', 'DISM feature state: enabled, pending restart, disabled; errors are unknown');
-    check(featureFromInstallState(1) === 'enabled' && featureFromInstallState(2) === 'disabled' && featureFromInstallState(null) === 'unknown', 'Win32_OptionalFeature install state maps to the feature state');
-    check(parseProbe('WARNING: x\r\n{"virtualizationFirmware":false,"hypervisorPresent":true,"installState":1}\r\n').hypervisorPresent === true && Object.keys(parseProbe('not json')).length === 0 && Object.keys(parseProbe('{"installState":"1"}')).length === 0, 'PowerShell probe: last line is validated JSON; anything else is ignored');
-    check(nodeMajor('v22.11.0') === 22 && nodeMajor('18.0.0') === 18 && nodeMajor('') === 0, 'Node major version');
-    const GB = 1024 ** 3;
-    const good = { edition: 'Professional', build: 22631, feature: 'enabled', sandboxExe: true, virtualizationFirmware: false, hypervisorPresent: true, totalRamBytes: 16 * GB, freeDiskBytes: 100 * GB, storageRoot: 'C:\\store', nodeVersion: 'v22.11.0' };
-    const status = (f) => Object.fromEntries(buildChecks({ ...good, ...f }).map((c) => [c.name, c.status]));
-    check(buildChecks(good).every((c) => c.status === 'ok'), 'a ready PC is all OK (a running hypervisor counts as virtualization on)');
-    check(status({ edition: 'Core' })['Windows edition'] === 'action' && status({ build: 17763 })['Windows edition'] === 'action' && status({ edition: 'Weird' })['Windows edition'] === 'warn', 'Home and old builds need action; unknown editions warn');
-    check(status({ hypervisorPresent: false })['CPU virtualization'] === 'action' && status({ hypervisorPresent: null, virtualizationFirmware: null })['CPU virtualization'] === 'warn' && status({ hypervisorPresent: false, virtualizationFirmware: true })['CPU virtualization'] === 'ok', 'virtualization: off needs action, unknown warns');
-    check(status({ feature: 'disabled', sandboxExe: false })['Windows Sandbox feature'] === 'action' && buildChecks({ ...good, feature: 'pending', sandboxExe: false })[2].detail.includes('restart') && buildChecks({ ...good, feature: 'enabled', sandboxExe: false })[2].detail.includes('restart'), 'feature: off or waiting for a restart needs action');
-    check(status({ totalRamBytes: 6 * GB }).Memory === 'warn' && status({ totalRamBytes: 3 * GB }).Memory === 'action' && status({ freeDiskBytes: 10 * GB })['Free disk'] === 'warn' && status({ freeDiskBytes: 2 * GB })['Free disk'] === 'action' && status({ freeDiskBytes: null })['Free disk'] === 'warn' && status({ nodeVersion: 'v18.20.0' })['Node.js'] === 'action', 'RAM under 8 GB warns, disk and Node limits');
-    check(canEnableFeature({ ...good, feature: 'disabled', sandboxExe: false }) && !canEnableFeature({ ...good, edition: 'Core', feature: 'disabled', sandboxExe: false }) && !canEnableFeature({ ...good, feature: 'pending', sandboxExe: false }) && !canEnableFeature(good), 'offers to enable the feature only when it is off on an edition that has it');
+// `agent-sandbox setup`: the pure pieces of the machine checklist (parsing what Windows reports, judging each item).
+import { buildChecks, canEnableFeature, editionSupport, nodeMajor } from '../cli/commands/setup/checks.js';
+import { featureFromInstallState, parseDismState, parseProbe, parseRegQuery } from '../cli/commands/setup/facts.js';
+const GB = 1024 ** 3;
+export const setupSuite = {
+    name: 'setup',
+    title: 'machine checklist for `sandbox setup`',
+    run: (t) => {
+        t.section('reading what Windows reports');
+        const reg = parseRegQuery('\r\nHKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\r\n    CurrentBuild    REG_SZ    22631\r\n    EditionID    REG_SZ    Professional\r\n    ProductName    REG_SZ    Windows 10 Pro\r\n    InstallDate    REG_DWORD    0x65a1b2c3\r\n');
+        t.equal({ EditionID: reg.EditionID, CurrentBuild: reg.CurrentBuild, ProductName: reg.ProductName }, { EditionID: 'Professional', CurrentBuild: '22631', ProductName: 'Windows 10 Pro' }, 'reg query output parses into name/value pairs');
+        t.equal(['Professional', 'EnterpriseS', 'EducationN', 'Core', 'CoreSingleLanguage', 'ServerStandard', 'Weird', null].map(editionSupport), ['supported', 'supported', 'supported', 'home', 'home', 'unsupported', 'unknown', 'unknown'], 'editions: Pro/Enterprise/Education yes, Home and Server no');
+        const dism = (state) => 'Deployment Image Servicing and Management tool\r\n\r\nFeature Name : Containers-DisposableClientVM\r\nDisplay Name : Windows Sandbox\r\nRestart Required : Possible\r\nState : ' + state + '\r\n';
+        t.equal([parseDismState(dism('Enabled')), parseDismState(dism('Enable Pending')), parseDismState(dism('Disabled')), parseDismState(dism('Disabled with Payload Removed')), parseDismState('Error: 740\r\nElevated permissions are required')], ['enabled', 'pending', 'disabled', 'disabled', 'unknown'], 'DISM feature state: enabled, pending restart, disabled; errors are unknown');
+        t.equal([featureFromInstallState(1), featureFromInstallState(2), featureFromInstallState(null)], ['enabled', 'disabled', 'unknown'], 'Win32_OptionalFeature install state maps to the feature state');
+        t.equal(parseProbe('WARNING: x\r\n{"virtualizationFirmware":false,"hypervisorPresent":true,"installState":1}\r\n').hypervisorPresent, true, 'PowerShell probe: the last line is read as JSON');
+        t.equal(Object.keys(parseProbe('not json')).length, 0, 'PowerShell probe: text that is not JSON is ignored');
+        t.equal(Object.keys(parseProbe('{"installState":"1"}')).length, 0, 'PowerShell probe: JSON of the wrong shape is ignored');
+        t.equal([nodeMajor('v22.11.0'), nodeMajor('18.0.0'), nodeMajor('')], [22, 18, 0], 'Node major version');
+        t.section('judging each item');
+        const good = { edition: 'Professional', build: 22631, feature: 'enabled', sandboxExe: true, virtualizationFirmware: false, hypervisorPresent: true, totalRamBytes: 16 * GB, freeDiskBytes: 100 * GB, storageRoot: 'C:\\store', nodeVersion: 'v22.11.0' };
+        const status = (facts) => Object.fromEntries(buildChecks({ ...good, ...facts }).map((c) => [c.name, c.status]));
+        t.check(buildChecks(good).every((c) => c.status === 'ok'), 'a ready PC is all OK (a running hypervisor counts as virtualization on)');
+        t.equal(status({ edition: 'Core' })['Windows edition'], 'action', 'Windows Home needs action');
+        t.equal(status({ build: 17763 })['Windows edition'], 'action', 'an old Windows build needs action');
+        t.equal(status({ edition: 'Weird' })['Windows edition'], 'warn', 'an unknown edition warns');
+        t.equal(status({ hypervisorPresent: false })['CPU virtualization'], 'action', 'virtualization: off needs action');
+        t.equal(status({ hypervisorPresent: null, virtualizationFirmware: null })['CPU virtualization'], 'warn', 'virtualization: unknown warns');
+        t.equal(status({ hypervisorPresent: false, virtualizationFirmware: true })['CPU virtualization'], 'ok', 'virtualization: on in the firmware is fine');
+        t.equal(status({ feature: 'disabled', sandboxExe: false })['Windows Sandbox feature'], 'action', 'feature: off needs action');
+        const waiting = buildChecks({ ...good, feature: 'pending', sandboxExe: false })[2];
+        t.includes(waiting.detail, 'restart', 'feature: waiting for a restart says so');
+        t.includes(buildChecks({ ...good, feature: 'enabled', sandboxExe: false })[2].detail, 'restart', 'feature: enabled but not usable yet says to restart');
+        t.equal(status({ totalRamBytes: 6 * GB }).Memory, 'warn', 'RAM under 8 GB warns');
+        t.equal(status({ totalRamBytes: 3 * GB }).Memory, 'action', 'RAM under 4 GB needs action');
+        t.equal(status({ freeDiskBytes: 10 * GB })['Free disk'], 'warn', 'low free disk warns');
+        t.equal(status({ freeDiskBytes: 2 * GB })['Free disk'], 'action', 'very low free disk needs action');
+        t.equal(status({ freeDiskBytes: null })['Free disk'], 'warn', 'unknown free disk warns');
+        t.equal(status({ nodeVersion: 'v18.20.0' })['Node.js'], 'action', 'an old Node.js needs action');
+        const off = { ...good, feature: 'disabled', sandboxExe: false };
+        t.check(canEnableFeature(off), 'offers to enable the feature when it is off on an edition that has it');
+        t.check(!canEnableFeature({ ...off, edition: 'Core' }), 'does not offer it on Windows Home');
+        t.check(!canEnableFeature({ ...off, feature: 'pending' }), 'does not offer it while a restart is pending');
+        t.check(!canEnableFeature(good), 'does not offer it when it is already on');
+    },
 };

package/dist/selftest/suite.d.ts

@@ -0,0 +1,13 @@
+import type { Fixtures } from './fixtures.js';
+import type { Harness } from './harness.js';
+export interface Suite {
+    /** Short name used to run just this suite: `sandbox self-test <name>`. */
+    name: string;
+    /** One line: what area this suite covers (shown by `self-test --list` style output and in failures). */
+    title: string;
+    run: (t: Harness, f: Fixtures) => void | Promise<void>;
+    /** Starts real processes (the daemon, ptyhost, csc, git): skipped where Windows cannot run them. */
+    live?: boolean;
+    /** A suite that takes longer than this is reported as a failure and the run continues. Default 2 minutes. */
+    timeoutMs?: number;
+}

package/dist/selftest/suite.js

@@ -0,0 +1 @@
+export {};

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

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