windows-development-sandbox 0.0.0-stage → 1.1.0

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

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

package/dist/selftest/accounts.test.js

@@ -0,0 +1,44 @@
+// Claude accounts: saving logins from the sandbox or this PC, switching, and the names that are refused.
+import fs from 'node:fs';
+import path from 'node:path';
+import { activateAccount, activeAccount, defaultAccount, listAccounts, readAccount, removeAccount, saveAccount, setDefaultAccount } from '../host/accounts.js';
+export const accountsSuite = {
+    name: 'accounts',
+    title: 'Claude accounts (save, switch, remove, safe names)',
+    run: async (t, f) => {
+        t.section('saving and switching');
+        const storage = t.at('acct-storage');
+        const dataA = path.join(storage, 'data', 'x');
+        const sandboxClaude = path.join(dataA, 'state', 'claude');
+        t.write(path.join(sandboxClaude, '.credentials.json'), '{"claudeAiOauth":{"refreshToken":"personal-1"}}');
+        t.write(path.join(sandboxClaude, '.claude.json'), '{"oauthAccount":{"emailAddress":"me@personal"},"other":1}');
+        saveAccount(storage, dataA, 'personal', null);
+        t.write(t.at('host-login', '.credentials.json'), '{"claudeAiOauth":{"refreshToken":"work-1"}}');
+        t.write(t.at('host-login.json'), '{"oauthAccount":{"emailAddress":"me@work"}}');
+        saveAccount(storage, dataA, 'work', { claudeDir: t.at('host-login'), globalStateFile: t.at('host-login.json') });
+        t.equal(listAccounts(storage, dataA).length, 2, 'accounts can be saved from the sandbox and from this PC');
+        t.equal(defaultAccount(storage), 'personal', 'the first account saved becomes the default');
+        t.equal(activeAccount(dataA), 'personal', 'the first account saved is the active one');
+        t.check(!fs.existsSync(path.join(sandboxClaude, '.agent-sandbox-account')), 'which account is active is not recorded inside the sandbox...');
+        t.check(fs.existsSync(path.join(storage, 'accounts', 'index.json')), '... it is recorded host-side');
+        t.write(path.join(sandboxClaude, '.credentials.json'), '{"claudeAiOauth":{"refreshToken":"personal-2"}}');
+        activateAccount(storage, dataA, 'work');
+        const stateAfter = f.readJson(path.join(sandboxClaude, '.claude.json'));
+        t.includes(fs.readFileSync(path.join(sandboxClaude, '.credentials.json'), 'utf8'), 'work-1', 'switching swaps in the other account\'s credentials');
+        t.equal(stateAfter.oauthAccount.emailAddress, 'me@work', 'switching swaps the signed-in account');
+        t.equal(stateAfter.other, 1, 'switching keeps the rest of the sandbox state');
+        t.equal(activeAccount(dataA), 'work', 'the new account is active');
+        t.includes(JSON.stringify(readAccount(storage, 'personal')?.credentials), 'personal-2', 'the outgoing account\'s refreshed tokens are saved back before switching');
+        t.section('removing and refusing');
+        setDefaultAccount(storage, 'work');
+        removeAccount(storage, 'work');
+        t.equal(defaultAccount(storage), null, 'removing the default account clears the default');
+        await t.throws(() => activateAccount(storage, dataA, 'nope'), 'Unknown account', 'an unknown account cannot be activated');
+        await t.throws(() => saveAccount(storage, dataA, '../x', null), 'Invalid account name', 'a path-like account name is rejected');
+        const victim = t.dir('victim');
+        const otherData = t.at('acct-storage', 'data', 'd');
+        const fromHost = { claudeDir: victim, globalStateFile: victim };
+        await t.throws(() => saveAccount(t.at('acct-storage'), otherData, 'index', fromHost), 'Invalid account name', 'an account cannot be called "index" (it would overwrite the index)');
+        await t.throws(() => saveAccount(t.at('acct-storage'), otherData, 'con', fromHost), 'Invalid account name', 'an account cannot be named after a device (it would open a device)');
+    },
+};

package/dist/selftest/agent-commands.test.d.ts

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

package/dist/selftest/agent-commands.test.js

@@ -0,0 +1,47 @@
+// Agent commands (Beta): which agents get a forwarding command, what the files contain, and that "off" changes nothing.
+// Everything happens in the test's temp folder with a made-up PATH; your real PATH is never read or written.
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULTS } from '../core/config.js';
+import { agentCommands, commandsDir, forwardingCmd, forwardingSh, realAgent, reconcileAgentCommands } from '../host/agent-commands.js';
+export const agentCommandsSuite = {
+    name: 'agent-commands',
+    title: 'agent commands (Beta): claude, codex ... forwarded into a hidden sandbox',
+    run: async (t) => {
+        const storage = t.at('agent-cmd-storage');
+        const npmDir = t.at('agent-cmd-npm');
+        const localBin = t.at('agent-cmd-local');
+        t.write(path.join(npmDir, 'codex.cmd'), '@echo codex');
+        t.write(path.join(npmDir, 'gemini.cmd'), '@echo gemini');
+        t.write(path.join(localBin, 'claude.exe'), 'MZ');
+        // A forwarding file of our own, first on PATH, must never count as the real agent.
+        t.write(path.join(commandsDir(storage), 'claude.cmd'), '@rem windows-development-sandbox agent command');
+        const PATH = [commandsDir(storage), npmDir, localBin].join(path.delimiter);
+        const on = { ...DEFAULTS, agentCommands: { enabled: true, agents: 'auto' } };
+        t.section('finding agents');
+        t.equal(realAgent('claude', commandsDir(storage), PATH), path.join(localBin, 'claude.exe'), 'the real agent is found on PATH, skipping this tool\'s own forwarding files');
+        t.equal(realAgent('nope', commandsDir(storage), PATH), null, 'an agent that is not installed is not found');
+        const commandsOf = (config, searchPath) => agentCommands(config, storage, searchPath).map((a) => a.command).sort();
+        t.equal(commandsOf(on, PATH), ['claude', 'codex', 'gemini'], '"auto": every agent installed on this PC gets a command, agents not installed none');
+        t.equal(commandsOf({ ...on, agentCommands: { enabled: true, agents: ['codex'] } }, PATH), ['codex'], 'a list limits it to the named agents');
+        const unsafeDir = t.at('agent%cmd^dir');
+        t.write(path.join(unsafeDir, 'aider.cmd'), '@echo');
+        t.check(!agentCommands(on, storage, unsafeDir).some((a) => a.command === 'aider'), 'an agent in a folder whose path has % or ^ (which cmd.exe would expand) is left alone');
+        t.section('the forwarding files');
+        const claude = { harness: 'claude', command: 'claude', real: path.join(localBin, 'claude.exe') };
+        const cmd = forwardingCmd(claude, 'C:\\node\\node.exe', 'C:\\tool\\dist\\bin\\sandbox.js');
+        t.includes(cmd, '"C:\\node\\node.exe" "C:\\tool\\dist\\bin\\sandbox.js" launch --harness claude --headless --terminal -- %*', 'the .cmd starts the agent in a hidden sandbox attached to this terminal...');
+        t.includes(cmd, 'if "%SANDBOX_AGENT_DIRECT%"=="1" goto direct', '... unless SANDBOX_AGENT_DIRECT=1...');
+        t.includes(cmd, 'call "' + claude.real + '" %*', '... which runs the real agent');
+        const sh = forwardingSh({ ...claude, real: 'C:\\Users\\me\\it\'s\\claude.exe' }, 'C:\\node\\node.exe', 'C:\\tool\\sandbox.js');
+        t.check(sh.startsWith('#!/bin/sh'), 'Git Bash gets a shell script');
+        t.includes(sh, "exec '/c/node/node.exe' '/c/tool/sandbox.js' launch --harness claude --headless --terminal -- \"$@\"", 'the shell script starts the same sandbox, with POSIX paths');
+        t.includes(sh, "'/c/Users/me/it'\\''s/claude.exe'", 'the shell script quotes awkward paths safely');
+        t.section('off changes nothing');
+        // Off with nothing set up: nothing to do, no PATH edit (which would be refused during the self-test anyway).
+        const fresh = t.at('agent-cmd-fresh');
+        const off = reconcileAgentCommands(DEFAULTS, fresh, 'C:\\node\\node.exe', 'C:\\tool\\sandbox.js');
+        t.equal({ on: off.on, changed: off.changed, wrote: fs.existsSync(commandsDir(fresh)) }, { on: false, changed: false, wrote: false }, 'off (the default) writes nothing and leaves your PATH alone');
+        await t.throws(() => reconcileAgentCommands(on, t.at('agent-cmd-on'), 'C:\\node\\node.exe', 'C:\\tool\\sandbox.js'), /self-test|PATH/i, 'turning it on edits your PATH, which the self-test refuses (it never changes this PC)');
+    },
+};

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

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

package/dist/selftest/channel.test.js

@@ -0,0 +1,37 @@
+// The host <-> sandbox channel and the terminal protocol: everything arriving from the sandbox is validated, sized and
+// filtered before this PC acts on it.
+import { safeId } from '../shared/rundir.js';
+import { GuestRequest, SessionStatus } from '../shared/schema.js';
+import { encodeFrame, FrameReader, FrameType, fixWindowsKeys, helloFrame, MAX_FRAME_BYTES, OutputFilter } from '../shared/pty-client.js';
+export const channelSuite = {
+    name: 'channel',
+    title: 'request/status validation and the terminal protocol (frames, OSC 52, keys)',
+    run: async (t) => {
+        t.section('requests and session status');
+        const validRequest = (r) => GuestRequest.safeParse(r).success;
+        const validSession = (s) => SessionStatus.safeParse(s).success;
+        await t.throws(() => safeId('../evil'), 'invalid id', 'a path-like id is rejected');
+        t.check(!validRequest({ kind: 'shell', id: 'a' }), 'unknown request kinds are rejected');
+        t.check(!validRequest({ kind: 'exec', id: 'a/b', command: ['x'], cwd: 'C:\\', timeoutSeconds: 1 }), 'request ids must be safe file names');
+        t.check(validRequest({ kind: 'ping', id: 'abc', createdAt: 'x' }), 'a known request kind with a safe id is accepted');
+        t.check(!validRequest({ kind: 'ping', id: 'abc', createdAt: 'x', extra: 1 }), 'requests with unknown keys are rejected');
+        const goodSession = { id: 's1', launchId: 'l', harness: 'claude', cwd: 'C:\\Workspace', message: 'ok', phase: 'running', updatedAt: 'x', startedAt: 'x', attach: { addresses: ['172.20.1.5'], port: 5000, token: 't' } };
+        t.check(validSession(goodSession), 'a well-formed session status is accepted');
+        t.check(!validSession({ ...goodSession, attach: { ...goodSession.attach, port: 70000 } }), 'a session status with an impossible port is rejected');
+        t.check(!validSession({ ...goodSession, phase: 'pwned' }), 'a session status with an unknown phase is rejected');
+        t.section('terminal frames');
+        const filter = new OutputFilter();
+        const filtered = Buffer.concat([
+            filter.push(Buffer.from('a\x1b]52;c;ZXZpbA==\x07b\x1b]0;title\x07')),
+            filter.push(Buffer.from('c\x1b]5')),
+            filter.push(Buffer.from('2;c;cGF5\x1b\\d')),
+        ]).toString('latin1');
+        t.equal(filtered, 'a' + 'b\x1b]0;title\x07' + 'c' + 'd', 'clipboard writes (OSC 52) from the sandbox are stripped, even split across chunks; titles pass');
+        const oversizedHeader = Buffer.concat([Buffer.from([16]), Buffer.from([0, 0, 0, 0x7f])]);
+        await t.throws(() => new FrameReader().push(oversizedHeader), 'frame too large', 'a frame announcing too much data is rejected instead of buffered');
+        t.equal(new FrameReader().push(encodeFrame(16, Buffer.alloc(MAX_FRAME_BYTES))).length, 1, 'a frame of exactly the maximum size is accepted');
+        const hello = new FrameReader().push(helloFrame('tok', 100, 30, 2))[0];
+        t.equal({ type: hello.type, cols: hello.payload.readInt16LE(0), rows: hello.payload.readInt16LE(2), flags: hello.payload[4], token: hello.payload.subarray(5).toString() }, { type: FrameType.Hello, cols: 100, rows: 30, flags: 2, token: 'tok' }, 'a hello frame carries size, flags and token');
+        t.equal(fixWindowsKeys(Buffer.from([0x61, 0x08, 0x7f, 0x1b])), Buffer.from([0x61, 0x7f, 0x08, 0x1b]), 'Windows console Backspace (^H) reaches the agent as DEL, so it deletes one character, not a word');
+    },
+};

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

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

package/dist/selftest/cli.test.js

@@ -0,0 +1,118 @@
+// The command manifest, the argument parser, the interactive menu helpers and the settings screen. One definition
+// (cli/manifest.ts) drives both the flags and the menu.
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildProgram, parseCli } from '../cli/args.js';
+import { COMMANDS } from '../cli/manifest.js';
+import { commandLine, readHistory, recordHistory } from '../cli/history.js';
+import { optionProblem, splitArgs } from '../cli/menu.js';
+import { cleanTargetOf } from '../cli/commands/data/collect.js';
+import { ago, colorEnabled, shorten, shortenMiddle } from '../cli/colors.js';
+import { hoistConfig, withoutConfig } from '../cli/index.js';
+import { closest, validNodeSpec, validPythonSpec } from '../cli/validate.js';
+import { editConfigText, SECTION_TITLES } from '../cli/settings/index.js';
+import { childrenOf, isSection, jsonExample, leavesOf, promptKind } from '../cli/settings/schema.js';
+import { Config, LocalOverrides } from '../core/schema.js';
+export const cliSuite = {
+    name: 'cli',
+    title: 'command manifest, argument parser, menu helpers, settings screen',
+    run: async (t) => {
+        t.section('manifest and parser');
+        const program = buildProgram(() => undefined);
+        const visible = COMMANDS.filter((c) => !c.hidden).map((c) => c.name);
+        const missingFromParser = visible.filter((name) => !program.commands.some((c) => c.name() === name));
+        t.equal(missingFromParser, [], 'every manifest command exists in the parser');
+        t.check(program.commands.find((c) => c.name() === 'launch').options.some((o) => o.long === '--terminal'), 'every manifest option exists in the parser (launch --terminal)');
+        const packageJson = JSON.parse(fs.readFileSync(path.join(t.packageRoot, 'package.json'), 'utf8'));
+        t.equal(program.version(), packageJson.version, '--version prints the package version');
+        t.check(program.options.some((o) => o.short === '-v' && o.long === '--version'), '-v is a short form of --version');
+        const start = parseCli(['start', '--headless']);
+        t.equal({ command: start.command, noAgent: start.noAgent, headless: start.headless }, { command: 'launch', noAgent: true, headless: true }, '`start` is launch without an agent');
+        const clean = parseCli(['data', 'clean', 'tools/go', 'logs', '--yes']);
+        t.equal({ command: clean.command, positionals: clean.positionals, yes: clean.yes }, { command: 'data', positionals: ['clean', 'tools/go', 'logs'], yes: true }, 'data clean takes targets and --yes');
+        t.equal(parseCli(['start', '--database', 'postgres,redis', '--database', 'mongodb']).databases, ['postgres', 'redis', 'mongodb'], '--database takes lists and can repeat');
+        t.equal(parseCli(['db', 'start', 'redis']).positionals, ['start', 'redis'], '`db` takes an action and a name');
+        t.equal(parseCli(['launch', '--harness', 'opencode', '--', '--continue']).passthrough, ['--continue'], 'agent arguments after -- reach the agent');
+        t.section('parser: agent wrappers (claude-sbx ...) and agent-sandbox');
+        const wrapped = parseCli(['--terminal', '--continue', '--headless', '--node', '20', '--', '--terminal'], true);
+        t.equal({ command: wrapped.command, terminal: wrapped.terminal, headless: wrapped.headless, node: wrapped.node, passthrough: wrapped.passthrough }, { command: 'launch', terminal: true, headless: true, node: '20', passthrough: ['--continue', '--terminal'] }, 'claude-sbx: sandbox flags are consumed, everything else goes to the agent');
+        await t.throws(() => parseCli(['status', '--bogus']), 'unknown option', 'agent-sandbox: unknown options are errors');
+        t.equal(parseCli(['account', 'use', 'work', '--no-restart']).positionals, ['use', 'work'], 'agent-sandbox: positionals are collected');
+        t.equal(parseCli(['clean', '--days=3']).days, 3, 'agent-sandbox: --opt=value works');
+        const agentFlags = parseCli(['--model', 'opus', '-p', 'fix it', '--json', '-f', 'x', '--timeout', '5', '--resume', 'abc'], true);
+        t.equal(agentFlags.passthrough, ['--model', 'opus', '-p', 'fix it', '--json', '-f', 'x', '--timeout', '5', '--resume', 'abc'], 'claude-sbx: any flag that is not a launch option goes to the agent, in order (even ones agent-sandbox uses elsewhere)');
+        t.equal({ json: agentFlags.json, follow: agentFlags.follow, timeout: agentFlags.timeout }, { json: false, follow: false, timeout: 600 }, 'claude-sbx: the agent\'s flags do not set agent-sandbox options');
+        const reserved = parseCli(['--sbx-terminal', '--terminal', '--sbx-node=18'], true);
+        t.equal({ terminal: reserved.terminal, node: reserved.node, passthrough: reserved.passthrough }, { terminal: true, node: '18', passthrough: [] }, '--sbx-<option> always means agent-sandbox');
+        t.equal(parseCli(['launch', '--continue', '--sbx-headless']).passthrough, ['--continue'], 'agent-sandbox launch passes agent flags too');
+        await t.throws(() => parseCli(['--sbx-nope'], true), 'Unknown option: --sbx-nope', 'an unknown --sbx-<option> is an error');
+        t.section('menu helpers');
+        t.equal(splitArgs('--model "big one" -c \'x y\''), ['--model', 'big one', '-c', 'x y'], 'menu: arguments split like a shell');
+        t.equal(commandLine(['exec', 'echo', 'a b']), 'sandbox exec echo "a b"', 'menu: command lines are quoted');
+        const optionOf = (flag) => COMMANDS.flatMap((cmd) => cmd.options).find((o) => o.flag === flag);
+        t.check(optionProblem(optionOf('--node'), 'abc') !== undefined, 'menu: a bad Node version is rejected while typing');
+        t.check(optionProblem(optionOf('--node'), '22') === undefined, 'menu: a good Node version is accepted');
+        t.check(optionProblem(optionOf('--workspace'), path.join(t.packageRoot, 'no-such-folder-here')) !== undefined, 'menu: a missing folder is rejected');
+        t.check(optionProblem(optionOf('--workspace'), t.packageRoot) === undefined, 'menu: an existing folder is accepted');
+        t.check(optionProblem(optionOf('--days'), '0') !== undefined, 'menu: a number below the minimum is rejected');
+        const rowOf = (area, name) => ({ area, name, path: 'x', bytes: 1 });
+        t.equal([cleanTargetOf(rowOf('tools', 'go')), cleanTargetOf(rowOf('tools', 'agents/claude')), cleanTargetOf(rowOf('databases', 'databases/pg')), cleanTargetOf(rowOf('host', 'launches'))], ['tools/go', 'tools/agents/claude', 'databases/pg', 'launches'], 'data menu: removable rows become checkbox targets');
+        t.equal([cleanTargetOf(rowOf('host', 'accounts')), cleanTargetOf(rowOf('tools', '(files in tools)'))], [null, null], 'data menu: accounts and loose files are never offered');
+        t.equal(COMMANDS.find((cmd) => cmd.name === 'data').options.find((o) => o.flag === '--yes')?.noMenu, true, 'data menu: --yes is never offered');
+        t.section('--config placement, history, validation, text helpers');
+        t.equal(hoistConfig(['--config', 'a.json', 'status', '--json']), ['status', '--config', 'a.json', '--json'], '--config before the command is moved behind it');
+        t.equal(hoistConfig(['--config=a.json']), ['menu', '--config', 'a.json'], '--config alone opens the menu with it');
+        t.equal(withoutConfig(['status', '--config', 'a.json', '--json']), ['status', '--json'], 'the recorded history drops --config');
+        recordHistory(['launch', '--harness', 'claude']);
+        recordHistory(['status']);
+        recordHistory(['launch', '--harness', 'claude']);
+        recordHistory(['menu']);
+        t.equal(readHistory().map((h) => h.argv.join(' ')), ['launch --harness claude', 'status'], 'history: newest first, no duplicates, the menu itself is not recorded');
+        t.check(validNodeSpec('22') && validNodeSpec('v22.1.0') && validNodeSpec('lts/*') && !validNodeSpec('abc'), 'validation: Node version syntax');
+        t.check(validPythonSpec('3.12') && !validPythonSpec('2.7'), 'validation: Python version syntax');
+        t.equal(closest('cluade', ['claude', 'codex']), 'claude', 'validation: did-you-mean for agent names');
+        t.equal(closest('zzzzzz', ['claude']), undefined, 'validation: nothing is suggested for an unrelated name');
+        const env = (vars, isTty) => colorEnabled(vars, isTty);
+        t.check(env({}, true), 'colours: on for a terminal');
+        t.check(!env({}, false), 'colours: off for a pipe');
+        t.check(!env({ NO_COLOR: '1' }, true) && !env({ TERM: 'dumb' }, true), 'colours: off for NO_COLOR and TERM=dumb');
+        t.check(env({ FORCE_COLOR: '1' }, false) && !env({ FORCE_COLOR: '0' }, true), 'colours: FORCE_COLOR overrides');
+        t.equal(shorten('abcdefghij', 6), 'abcde…', 'text helpers: shorten');
+        t.equal(shortenMiddle('C:\\Users\\me\\project', 11), 'C:\\Us…oject', 'text helpers: shorten in the middle');
+        t.equal([ago(0, 10 * 60 * 1000), ago(0, 5000), ago(0, 3 * 86400 * 1000)], ['10 min ago', 'just now', '3 d ago'], 'text helpers: relative time');
+        t.section('settings screen');
+        const original = '{\n  // my notes stay\n  "sandbox": { "headless": true }\n}\n';
+        const set = editConfigText(original, ['attach', 'auto'], true);
+        const nested = 'text' in set ? editConfigText(set.text, ['databases', 'postgres', 'port'], 6543) : set;
+        const reset = 'text' in nested ? editConfigText(nested.text, ['sandbox', 'headless'], undefined) : nested;
+        t.check('text' in reset, 'editing a config file gives new text');
+        const resetText = 'text' in reset ? reset.text : '';
+        t.includes(resetText, '// my notes stay', 'settings screen: changes keep the file\'s comments');
+        t.includes(resetText, '"auto": true', 'settings screen: a new setting is added');
+        t.includes(resetText, '"port": 6543', 'settings screen: nested keys are created');
+        t.excludes(resetText, 'headless', 'settings screen: reset removes a key');
+        const invalid = editConfigText(original, ['sandbox', 'memoryMb'], 12);
+        t.check('problems' in invalid && invalid.problems.join().includes('memoryMb'), 'settings screen: invalid values are not saved', JSON.stringify(invalid));
+        const missing = editConfigText('{ "storage": { "root": "C:\\\\x" } }', ['agentCommands', 'enabled'], undefined);
+        t.check('text' in missing && missing.text.includes('"root"'), 'removing a setting the file does not have changes nothing (no crash)');
+        const projectEdit = editConfigText('{}', ['downloads', 'requireChecksum'], true, 'project');
+        const projectBad = editConfigText('{}', ['storage', 'root'], 'C:\\x', 'project');
+        t.check('text' in projectEdit && projectEdit.text.includes('requireChecksum'), 'settings screen: a project file accepts project settings');
+        t.check('problems' in projectBad, 'settings screen: a project file is validated against the project schema (storage cannot be set there)');
+        // Every setting must be reachable in the settings screen: each leaf has a prompt, each top-level section a title.
+        const userLeaves = leavesOf(Config);
+        const projectLeaves = leavesOf(LocalOverrides);
+        const sectionNames = (schema) => childrenOf(schema).filter(([, s]) => isSection(s)).map(([name]) => name);
+        const kinds = new Set(userLeaves.map((l) => promptKind(l.schema)));
+        t.check(userLeaves.length > 100 && projectLeaves.length > 50, 'settings screen: every setting is a leaf (' + userLeaves.length + ' settings, ' + projectLeaves.length + ' in a project file)');
+        const missingKinds = ['boolean', 'enum', 'union', 'number', 'string', 'string-list', 'json'].filter((k) => !kinds.has(k));
+        t.equal(missingKinds, [], 'settings screen: every kind of setting has a prompt');
+        t.check(userLeaves.some((l) => l.key.join('.') === 'downloads.requireChecksum'), 'settings screen: downloads.requireChecksum is reachable in your settings');
+        t.check(projectLeaves.some((l) => l.key.join('.') === 'downloads.requireChecksum'), 'settings screen: downloads.requireChecksum is reachable in a project file');
+        const untitled = [...sectionNames(Config), ...sectionNames(LocalOverrides)].filter((name) => !SECTION_TITLES[name]);
+        t.equal(untitled, [], 'settings screen: every top-level section has a title');
+        const jsonLeaves = userLeaves.filter((l) => promptKind(l.schema) === 'json');
+        t.check(jsonLeaves.length > 0 && jsonLeaves.every((l) => jsonExample(l.key, l.schema).length > 5), 'settings screen: JSON settings show an example of the expected shape');
+        t.includes(jsonExample(['harnesses'], jsonLeaves[0].schema), 'npmPackage', 'settings screen: the agent definition example shows its fields');
+    },
+};

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

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

package/dist/selftest/cmdline.test.js

@@ -0,0 +1,45 @@
+// How the sandbox builds command lines for npm-installed agents (.cmd files run through cmd.exe): & | < > ^ % and quotes
+// must reach the agent unchanged.
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isWin } from '../core/util.js';
+import { runNode } from './fixtures.js';
+// Odd quote counts flip cmd's quote state for every later argument: those come after them on purpose.
+const TRICKY_ARGUMENTS = ['https://x?a=1&b=2', '50% off', 'a|b<c>d', 'x^y', 'say "hi" & go', 'plain', '%PATH%', 'a"b&c', 'q"x|y^z"w', 'e"5%', 'k&v', '100%'];
+export const cmdlineSuite = {
+    name: 'cmdline',
+    title: 'cmd.exe quoting for npm-installed agents',
+    run: async (t) => {
+        t.section('command lines');
+        // guest/cmdline.ts is loaded in a child process with a throwaway launch/data folder (it reads session.json on load).
+        const quoteDir = t.at('quote');
+        t.write(path.join(quoteDir, 'launch', 'session.json'), '{}');
+        const agentCmd = t.write(path.join(quoteDir, 'agent.cmd'), '@"' + process.execPath + '" -e "console.log(JSON.stringify(process.argv.slice(1)))" %*\r\n');
+        const script = [
+            'const m = await import(process.argv[1]); const [cmd, tricky] = JSON.parse(process.argv[2]);',
+            'console.log(JSON.stringify({ normal: m.commandLine("C:\\\\W\\\\cmd.exe", ["/d", "/c", "C:\\\\a\\\\agent.cmd", "--model", "big one", "plain", ""]), direct: m.commandLine("C:\\\\a\\\\agent.exe", ["a&b", "50%"]),',
+            '  url: m.cmdArgs(["https://x?a=1&b=2"]), pct: m.cmdArgs(["50%"]), live: m.commandLine("cmd.exe", ["/d", "/c", cmd, ...tricky]).slice(8) }));',
+        ].join('\n');
+        const probe = await runNode(['--input-type=module', '-e', script, pathToFileURL(path.join(t.packageRoot, 'dist', 'guest', 'cmdline.js')).href, JSON.stringify([agentCmd, TRICKY_ARGUMENTS])], {
+            env: { ...process.env, AGENT_LAUNCH_DIR: path.join(quoteDir, 'launch'), AGENT_DATA_DIR: path.join(quoteDir, 'data') },
+        });
+        let quoting = {};
+        try {
+            quoting = JSON.parse(probe.out);
+        }
+        catch { /* reported below */ }
+        const whyEmpty = quoting.normal ? '' : 'the helper printed: ' + probe.out.trim().slice(0, 300);
+        t.check(quoting.normal === 'C:\\W\\cmd.exe /d /c C:\\a\\agent.cmd --model "big one" plain ""', 'ordinary arguments are quoted as before', whyEmpty + '\nactual: ' + quoting.normal);
+        t.check(quoting.direct === 'C:\\a\\agent.exe a&b 50%', 'a program started directly gets & and % unchanged', 'actual: ' + quoting.direct);
+        t.equal(quoting.url, '"https://x?a=1&b=2"', 'cmd /c arguments: & | < > ^ are quoted');
+        t.equal(quoting.pct, '"50"%""', 'cmd /c arguments: % is split out so no %name% expands');
+        // (A temp folder with spaces would also need cmd's own quote rules, so this end-to-end run skips those.)
+        if (isWin && quoting.live && !/\s/.test(agentCmd)) {
+            const echoed = spawnSync(process.env.ComSpec ?? 'cmd.exe', [quoting.live], { encoding: 'utf8', windowsVerbatimArguments: true, windowsHide: true });
+            t.equal(echoed.stdout.trim(), JSON.stringify(TRICKY_ARGUMENTS), 'cmd /d /c <agent>.cmd passes &, |, <, >, ^, % and quotes through to the agent unchanged');
+        }
+        else
+            t.skip('end-to-end cmd.exe quoting run (not Windows, or the temp path has spaces)');
+    },
+};

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

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

package/dist/selftest/config.test.js

@@ -0,0 +1,38 @@
+// Loading the settings: built-in defaults, a user config file, and the example config that ships with the tool.
+import path from 'node:path';
+import _ from 'lodash';
+import { DEFAULTS, loadConfig } from '../core/config.js';
+import { readJsonc } from '../core/util.js';
+export const configSuite = {
+    name: 'config',
+    title: 'built-in defaults, user config file, config.example.json',
+    run: async (t, f) => {
+        t.section('built-in defaults');
+        const builtIn = loadConfig();
+        t.equal({
+            configPath: builtIn.configPath,
+            guestWorkspace: builtIn.config.guestWorkspace,
+            headless: builtIn.config.sandbox.headless,
+            vGpu: builtIn.config.sandbox.vGpu,
+            gitAccess: builtIn.config.provisioning.git.access,
+        }, { configPath: null, guestWorkspace: 'auto', headless: false, vGpu: false, gitAccess: 'full' }, 'with no user config the built-in defaults apply (auto guest folder, headless off, vGPU off, git full)');
+        t.section('a user config file');
+        const customFile = t.writeJson(t.at('cfg.json'), {
+            sandbox: { headless: true },
+            toolchains: { rust: { enabled: false } },
+            mappings: [{ host: 'rel-folder', guest: 'C:\\Rel', readOnly: true }],
+        });
+        const custom = loadConfig(customFile);
+        t.equal({ headless: custom.config.sandbox.headless, rust: custom.config.toolchains.rust.enabled, python: custom.config.toolchains.python.enabled }, { headless: true, rust: false, python: 'auto' }, 'a config file only needs the keys it changes (deep merge over the defaults)');
+        await t.throws(() => loadConfig(t.at('missing.json')), 'Config file not found', 'an explicit --config that does not exist is an error');
+        t.dir('rel-folder');
+        const relativeRun = await f.run({}, { ...custom.config, storage: f.baseConfig.storage });
+        const mappedHosts = relativeRun.config.mappings.map((m) => m.host);
+        t.check(mappedHosts.includes(t.at('rel-folder')), 'relative mappings in the user config resolve against the config file\'s folder', 'mapped hosts: ' + JSON.stringify(mappedHosts));
+        t.section('config.example.json');
+        const examplePath = path.join(t.packageRoot, 'config.example.json');
+        t.equal(loadConfig(examplePath).config.defaultHarness, 'claude', 'config.example.json is valid');
+        const example = _.omit(readJsonc(examplePath), '$schema');
+        t.check(_.isEqual(example, DEFAULTS), 'config.example.json lists exactly the built-in defaults', 'the differences are in: ' + Object.keys(DEFAULTS).filter((key) => !_.isEqual(example[key], DEFAULTS[key])).join(', '));
+    },
+};

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

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

package/dist/selftest/data.test.js

@@ -0,0 +1,80 @@
+// `sandbox data` and `sandbox clean`: what a clean target may name, how sizes and removal treat links, and which old
+// launch folders, logs and downloads are pruned.
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveCleanTargets } from '../cli/commands/data/clean.js';
+import { removeTree } from '../cli/commands/data/remove.js';
+import { findLinks } from '../cli/commands/repair/finders.js';
+import { humanBytes, sizeOf } from '../core/disk.js';
+import { pruneStorage } from '../host/cleanup.js';
+export const dataSuite = {
+    name: 'data',
+    title: 'data clean targets, sizes and removal with links, storage cleanup',
+    run: async (t) => {
+        t.section('clean targets');
+        const storage = t.at('data-store');
+        const dataPath = path.join(storage, 'data', 'default');
+        const resolve = (...inputs) => resolveCleanTargets(inputs, dataPath, storage).map((r) => path.relative(storage, r.path));
+        const inData = (...parts) => path.join('data', 'default', ...parts);
+        t.equal(resolve('tools/go'), [inData('tools', 'go')], 'tools/<name> resolves inside the data folder');
+        t.equal(resolve('tools\\go'), [inData('tools', 'go')], 'either slash works');
+        t.equal(resolve('Tools/agents/claude'), [inData('tools', 'agents', 'claude')], 'tools/agents/<name> resolves, whatever the case');
+        t.equal(resolve('databases/postgres-18'), [inData('databases', 'postgres-18')], 'databases/<name> resolves');
+        t.equal(resolve('logs'), [inData('logs')], 'logs resolves');
+        t.equal(resolve('launches'), ['launches'], 'launches resolves to the storage folder\'s launches');
+        t.equal(resolve('state/claude'), [inData('state', 'claude')], 'state/<agent> resolves');
+        t.equal(resolve('tools', 'tools/go', 'tools/go'), [inData('tools')], 'nested and repeated targets collapse');
+        t.equal(resolve('all', 'logs'), [inData(), 'launches'], '`all` is the data folder plus launches');
+        t.check(Boolean(resolveCleanTargets(['state/claude'], dataPath, storage)[0].warning?.includes('login')), 'cleaning state warns about the login');
+        t.check(Boolean(resolveCleanTargets(['all'], dataPath, storage)[0].warning), 'cleaning everything carries a warning');
+        const badTargets = ['', '..', 'tools/..', 'tools/../../x', '../data', 'C:\\Windows', 'C:tools', '/etc', '\\\\server\\share', 'tools/*', 'tools/go:stream', 'tools/a/b', 'tools/agents/a/b', 'logs/guest.log', 'accounts', 'sync', 'windows', 'tools/.', 'tools/go.'];
+        const accepted = badTargets.filter((target) => {
+            try {
+                resolveCleanTargets([target], dataPath, storage);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        t.equal(accepted, [], 'rejected: .., absolute paths, drive letters, UNC, wildcards, streams, too deep, unknown areas');
+        await t.throws(() => resolveCleanTargets([], dataPath, storage), '', 'rejected: no target at all (that is not "everything")');
+        t.section('sizes and removal never follow links');
+        const sized = t.at('sized');
+        t.write(path.join(sized, 'a.bin'), 'x'.repeat(1000));
+        t.write(path.join(sized, 'sub', 'b.bin'), 'y'.repeat(24));
+        const outside = t.at('outside');
+        t.write(path.join(outside, 'keep.txt'), 'z'.repeat(5000));
+        let linked = false;
+        try {
+            fs.symlinkSync(outside, path.join(sized, 'sub', 'escape'), 'junction');
+            linked = true;
+        }
+        catch { /* no junctions here */ }
+        t.equal(sizeOf(sized), 1024, 'sizes count real files only' + (linked ? ' (a junction counts 0)' : ''));
+        t.equal([humanBytes(1536), humanBytes(0), humanBytes(3 * 1024 ** 3)], ['1.5 KB', '0 B', '3.0 GB'], 'sizes are shown in readable units');
+        if (linked)
+            t.equal(findLinks(sized).length, 1, 'repair finds a junction planted in the data folder');
+        removeTree(sized, t.temp);
+        t.check(!fs.existsSync(sized), 'a folder is removed');
+        t.check(fs.existsSync(path.join(outside, 'keep.txt')), 'removing a folder never deletes what a link inside points to');
+        t.section('storage cleanup');
+        const store = t.at('prune');
+        const aged = (p, days) => { const d = new Date(Date.now() - days * 86400000); fs.utimesSync(p, d, d); };
+        for (const [name, days] of [['old', 9], ['kept', 30], ['new', 1]]) {
+            aged(t.write(path.join(store, 'launches', name, 'agent.wsb'), 'x'), days);
+            aged(path.join(store, 'launches', name), days);
+        }
+        aged(t.write(path.join(store, 'data', 'd', 'logs', 'guest-old.log'), 'x'), 20);
+        t.write(path.join(store, 'data', 'd', 'logs', 'guest-new.log'), 'x');
+        const staging = t.dir('prune', 'data', 'd', 'tools', 'git.staging-ab12');
+        aged(staging, 2);
+        t.dir('prune', 'data', 'd', 'tools', 'node');
+        const pruned = pruneStorage(store, { keep: ['kept'] });
+        const left = (p) => fs.existsSync(path.join(store, p));
+        t.equal(pruned.launches, 1, 'cleanup removes one launch folder');
+        t.equal({ old: left('launches/old'), kept: left('launches/kept'), new: left('launches/new') }, { old: false, kept: true, new: true }, 'cleanup: launch folders older than 7 days go; the running launch and recent ones stay');
+        t.equal({ oldLog: left('data/d/logs/guest-old.log'), newLog: left('data/d/logs/guest-new.log') }, { oldLog: false, newLog: true }, 'cleanup: logs older than 14 days go');
+        t.equal({ interrupted: left('data/d/tools/git.staging-ab12'), realTool: left('data/d/tools/node') }, { interrupted: false, realTool: true }, 'cleanup: interrupted downloads go; real tools stay');
+    },
+};

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

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

package/dist/selftest/detect.test.js

@@ -0,0 +1,58 @@
+// "What does this project need?": databases and toolchains detected from project files, and the plans built from them.
+import { databasesFromServices, detectDatabases } from '../core/detect-databases.js';
+import { DEFAULTS } from '../core/config.js';
+import { databaseCatalog, planDatabases } from '../host/database-plan.js';
+import { decideToolchains, resolveToolchains } from '../core/detect-toolchains.js';
+const found = (files, host = []) => detectDatabases(files, host).map((d) => d.database);
+const file = (path, text) => ({ path, text });
+export const detectSuite = {
+    name: 'detect',
+    title: 'database and toolchain detection from project files',
+    run: (t) => {
+        t.section('databases from project files');
+        const compose = file('docker-compose.yml', 'services:\n  db:\n    image: postgres:16-alpine\n  cache:\n    image: "redis:7"\n  dynamo:\n    image: amazon/dynamodb-local:latest\n');
+        t.equal(found([compose]), ['postgres', 'redis', 'dynamodb'], 'compose services: postgres, redis and DynamoDB Local images');
+        t.equal(found([file('package.json', '{"dependencies":{"pg":"^8.11.0","ioredis":"5","@aws-sdk/client-dynamodb":"3"}}')]), ['postgres', 'redis', 'dynamodb'], 'package.json: pg, ioredis, @aws-sdk/client-dynamodb');
+        t.equal(found([file('package.json', '{"dependencies":{"pgadmin-ui":"1","mysql-logger":"2","express":"4"}}')]), [], 'package.json: names that only contain a driver name do not count');
+        t.equal(found([file('prisma/schema.prisma', 'datasource db {\n  provider = "mysql"\n  url = env("DATABASE_URL")\n}')]), ['mysql'], 'Prisma: the datasource provider decides');
+        t.equal(found([file('requirements.txt', 'django==5.0\npsycopg2-binary==2.9\npymongo>=4\n')]), ['postgres', 'mongodb'], 'Python requirements: psycopg2 and pymongo');
+        t.equal(found([file('Api/Api.csproj', '<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.0" />')]), ['sqlserver'], '.NET: EF Core SQL Server provider');
+        t.equal(found([file('.env.example', 'DATABASE_URL=postgresql://user:pass@localhost:5432/app\nMONGO_URL=mongodb+srv://cluster/x\n')]), ['postgres', 'mongodb'], '.env templates: connection-string schemes');
+        t.equal(found([file('template.yaml', 'Resources:\n  Table:\n    Type: AWS::DynamoDB::Table\n')]), ['dynamodb'], 'SAM/CloudFormation: a DynamoDB table resource');
+        t.equal(found([file('go.mod', 'require (\n\tgithub.com/jackc/pgx/v5 v5.5.0\n\tgithub.com/aws/aws-sdk-go-v2/service/dynamodb v1.0.0\n)')]), ['postgres', 'dynamodb'], 'go.mod: pgx and the DynamoDB SDK');
+        const knex = [file('package.json', '{"dependencies":{"knex":"3"}}')];
+        t.equal(found(knex), [], 'an ORM that names no database uses nothing when this PC has none');
+        t.equal(found(knex, ['mysql']), ['mysql'], 'an ORM that names no database uses the one installed on this PC');
+        t.equal(databasesFromServices(['postgresql-x64-16', 'MySQL80', 'MSSQL$SQLEXPRESS', 'Spooler', 'Redis']), ['postgres', 'mysql', 'sqlserver', 'redis'], 'database services on this PC are recognised by name');
+        // Hostile workspace files (a cloned repository is untrusted): detection must stay linear.
+        const hostile = [
+            file('.env', 'Server=a;Database=a;'.repeat(12000)),
+            file('compose.yaml', 'services:\n  x:\n    image: ' + 'postgres'.repeat(20000) + '!\n'),
+            file('appsettings.json', 'Host=a;'.repeat(30000)),
+        ];
+        const started = Date.now();
+        detectDatabases(hostile);
+        const took = Date.now() - started;
+        t.check(took < 2000, 'database detection stays fast on hostile workspace files (no catastrophic backtracking)', 'took ' + took + ' ms');
+        t.section('the database plan');
+        const plan = planDatabases({ ...DEFAULTS.databases, mongodb: { ...DEFAULTS.databases.mongodb, enabled: true }, redis: { ...DEFAULTS.databases.redis, enabled: false } }, 'unused', { files: [compose], host: [] });
+        t.equal(plan.map((p) => p.database + '@' + p.version + ':' + p.port), ['postgres@16:5432', 'mongodb@latest:27017', 'dynamodb@latest:8000'], 'plan: "auto" from the project (compose pins Postgres 16), true always, false never');
+        t.equal(plan.find((p) => p.database === 'dynamodb')?.adminPort, 8001, 'plan: DynamoDB gets its admin UI port');
+        const catalog = databaseCatalog({ ...DEFAULTS.databases, postgres: { ...DEFAULTS.databases.postgres, enabled: false, port: 6543 } });
+        t.equal(catalog.map((p) => p.database), ['postgres', 'mysql', 'mongodb', 'redis', 'dynamodb'], 'sbx-db catalog: every database that can run (not SQL Server), even ones off at boot');
+        t.equal(catalog[0].port, 6543, 'sbx-db catalog: configured ports are used');
+        t.section('toolchains from project files');
+        const tc = DEFAULTS.toolchains;
+        const goProject = decideToolchains(tc, ['README.md', 'go.mod', 'api/main.go'], ['python', 'rust']);
+        t.equal({ go: goProject.go.on, reason: goProject.go.reason }, { go: true, reason: 'go.mod' }, 'toolchains: a Go project gets Go (and says why)');
+        t.equal({ python: goProject.python.on, rust: goProject.rust.on, dotnet: goProject.dotnet.on, java: goProject.java.on }, { python: false, rust: false, dotnet: false, java: false }, 'toolchains: a Go project gets nothing it does not use, whatever this PC has');
+        const fresh = decideToolchains(tc, ['notes.txt'], ['python', 'dotnet']);
+        t.equal({ python: fresh.python.on, dotnet: fresh.dotnet.on, go: fresh.go.on }, { python: true, dotnet: true, go: false }, 'toolchains: a folder that is no project yet gets the languages this PC has');
+        t.includes(fresh.python.reason, 'this PC', 'toolchains: the reason names this PC');
+        const rusty = decideToolchains({ ...tc, python: { ...tc.python, enabled: true } }, ['Cargo.toml'], []);
+        t.equal({ rust: rusty.rust.on, cpp: rusty.cpp.on }, { rust: true, cpp: true }, 'toolchains: Rust brings its C/C++ linker');
+        t.equal({ python: rusty.python.on, reason: rusty.python.reason }, { python: true, reason: 'enabled in config' }, 'toolchains: true in config always wins');
+        const resolved = resolveToolchains(tc, goProject);
+        t.equal({ go: resolved.go.enabled, python: resolved.python.enabled }, { go: true, python: false }, 'the sandbox gets plain decisions instead of "auto"');
+    },
+};