windows-development-sandbox 1.0.5 → 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

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

package/dist/selftest/cli.test.js

@@ -1,30 +1,118 @@
-// The command manifest, parser and menu helpers: one definition drives both the flags and the menu.
+// 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, splitArgs } from '../cli/menu.js';
-import { editConfigText } from '../cli/settings.js';
-export const cliTests = (t) => {
-    const { check } = t;
-    t.section('CLI: manifest, parser, menu');
-    const program = buildProgram(() => undefined);
-    const visible = COMMANDS.filter((c) => !c.hidden).map((c) => c.name);
-    check(visible.every((name) => program.commands.some((c) => c.name() === name)) && program.commands.find((c) => c.name() === 'launch').options.some((o) => o.long === '--terminal'), 'every manifest command and option exists in the parser');
-    const start = parseCli(['start', '--headless']);
-    check(start.command === 'launch' && start.noAgent && start.headless === true, '`start` is launch without an agent');
-    const clean = parseCli(['data', 'clean', 'tools/go', 'logs', '--yes']);
-    check(clean.command === 'data' && clean.positionals.join() === 'clean,tools/go,logs' && clean.yes, 'data clean takes targets and --yes');
-    check(parseCli(['start', '--database', 'postgres,redis', '--database', 'mongodb']).databases.join() === 'postgres,redis,mongodb' && parseCli(['db', 'start', 'redis']).positionals.join() === 'start,redis', '--database takes lists and repeats; `db` takes an action and a name');
-    check(parseCli(['launch', '--harness', 'opencode', '--', '--continue']).passthrough.join() === '--continue', 'agent arguments after -- reach the agent');
-    check(JSON.stringify(splitArgs('--model "big one" -c \'x y\'')) === '["--model","big one","-c","x y"]' && commandLine(['exec', 'echo', 'a b']) === 'sandbox exec echo "a b"', 'menu: arguments split like a shell, command lines quoted');
-    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;
-    const invalid = editConfigText(original, ['sandbox', 'memoryMb'], 12);
-    check('text' in reset && reset.text.includes('// my notes stay') && reset.text.includes('"auto": true') && reset.text.includes('"port": 6543') && !reset.text.includes('headless') && 'problems' in invalid && invalid.problems.join().includes('memoryMb'), 'settings screen: changes keep the file\'s comments, nested keys are created, reset removes a key, invalid values are not saved');
-    recordHistory(['launch', '--harness', 'claude']);
-    recordHistory(['status']);
-    recordHistory(['launch', '--harness', 'claude']);
-    recordHistory(['menu']);
-    check(readHistory().map((h) => h.argv.join(' ')).join('|') === 'launch --harness claude|status', 'history: newest first, no duplicates, the menu itself is not recorded');
+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

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

package/dist/selftest/config.test.js

@@ -1,74 +1,38 @@
-// Config loading, argument parsing, workspace resolution and .sandbox-config.json trust.
-import fs from 'node:fs';
+// 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 { parseCli as parseArgs } from '../cli/args.js';
-import { loadConfig } from '../core/config.js';
-import { ensureDir } from '../core/util.js';
-import { autoGuestWorkspace } from '../core/workspace.js';
-export const configTests = async (t, f) => {
-    const { check, rejects, write, temp } = t;
-    t.section('config');
-    const builtIn = loadConfig();
-    check(builtIn.configPath === null && builtIn.config.guestWorkspace === 'auto' && !builtIn.config.sandbox.headless && !builtIn.config.sandbox.vGpu && builtIn.config.provisioning.git.access === 'full', 'no user config: built-in defaults (auto guest folder, headless off, vGPU off, git full)');
-    const custom = loadConfig(write(path.join(temp, 'cfg.json'), JSON.stringify({ sandbox: { headless: true }, toolchains: { rust: { enabled: false } }, mappings: [{ host: 'rel-folder', guest: 'C:\\Rel', readOnly: true }] })));
-    check(custom.config.sandbox.headless && custom.config.toolchains.rust.enabled === false && custom.config.toolchains.python.enabled === 'auto', 'a config file only needs the keys it changes (deep merge over defaults)');
-    check(await rejects(() => loadConfig(path.join(temp, 'missing.json')), 'Config file not found'), 'an explicit --config that does not exist is an error');
-    check(loadConfig(path.join(t.packageRoot, 'config.example.json')).config.defaultHarness === 'claude', 'config.example.json is valid');
-    ensureDir(path.join(temp, 'rel-folder'));
-    const relRun = await f.run({}, { ...custom.config, storage: f.baseConfig.storage });
-    check(relRun.config.mappings.some((m) => m.host === path.join(temp, 'rel-folder')), 'relative mappings in the user config resolve against the config file\'s folder');
-    t.section('arguments');
-    const wrapped = parseArgs(['--terminal', '--continue', '--headless', '--node', '20', '--', '--terminal'], true);
-    check(wrapped.command === 'launch' && wrapped.terminal && wrapped.headless === true && wrapped.node === '20' && wrapped.passthrough.join(' ') === '--continue --terminal', 'claude-sbx: sandbox flags are consumed, everything else goes to the agent');
-    check(await rejects(() => parseArgs(['status', '--bogus']), 'unknown option') && parseArgs(['account', 'use', 'work', '--no-restart']).positionals.join() === 'use,work' && parseArgs(['clean', '--days=3']).days === 3, 'agent-sandbox: unknown options are errors; positionals and --opt=value work');
-    const agentFlags = parseArgs(['--model', 'opus', '-p', 'fix it', '--json', '-f', 'x', '--timeout', '5', '--resume', 'abc'], true);
-    check(agentFlags.passthrough.join(' ') === '--model opus -p fix it --json -f x --timeout 5 --resume abc' && !agentFlags.json && !agentFlags.follow && agentFlags.timeout === 600, 'claude-sbx: only launch options are ours; any other flag (even ones agent-sandbox uses elsewhere) goes to the agent, in order');
-    const reserved = parseArgs(['--sbx-terminal', '--terminal', '--sbx-node=18'], true);
-    check(reserved.terminal && reserved.node === '18' && reserved.passthrough.join(' ') === '' && parseArgs(['launch', '--continue', '--sbx-headless']).passthrough.join() === '--continue' && await rejects(() => parseArgs(['--sbx-nope'], true), 'Unknown option: --sbx-nope'), '--sbx-<option> always means agent-sandbox; agent-sandbox launch passes agent flags too');
-    t.section('workspace');
-    const rA = await f.run();
-    check(rA.workspaceHost === f.workA && rA.config.guestWorkspace === 'C:\\Workspace\\work-a' && rA.harnessName === 'claude' && rA.dataPath.endsWith(path.join('data', 'testdata')), 'any folder is the workspace; guest path is C:\\Workspace\\<folder name>');
-    check(autoGuestWorkspace('C:\\x\\My Proj (2)') === 'C:\\Workspace\\My Proj _2_' && autoGuestWorkspace('D:\\...') === 'C:\\Workspace\\project', 'auto guest folder names are sanitised');
-    check(rA.versions.node.spec === '22.3.0' && rA.versions.node.source === 'this PC' && rA.versions.python.spec === '3', 'default Node version is this PC\'s; Python defaults to latest 3.x');
-    write(path.join(f.workA, '.nvmrc'), 'lts/iron\n');
-    write(path.join(f.workA, '.python-version'), '3.11\n');
-    const rV = await f.run();
-    check(rV.versions.node.spec === 'lts/iron' && rV.versions.node.source === '.nvmrc' && rV.versions.python.spec === '3.11', '.nvmrc and .python-version are respected');
-    check((await f.run({ nodeVersion: '18' })).versions.node.source === 'command line', '--node beats .nvmrc');
-    fs.rmSync(path.join(f.workA, '.nvmrc'));
-    fs.rmSync(path.join(f.workA, '.python-version'));
-    write(path.join(f.workA, '.node-version'), 'v20.11.1');
-    check((await f.run()).versions.node.spec === 'v20.11.1', '.node-version is respected');
-    fs.rmSync(path.join(f.workA, '.node-version'));
-    check(await rejects(() => f.run({ cwd: f.install }), 'install folder') && await rejects(() => f.run({ cwd: temp }), 'must not be able to change') && await rejects(() => f.run({ cwd: path.join(temp, 'storage') }), 'storage folder'), 'refuses the install folder, its parents and the storage folder');
-    const originalWindir = process.env.WINDIR;
-    ensureDir(path.join(temp, 'winroot', 'sys'));
-    process.env.WINDIR = path.join(temp, 'winroot');
-    const sysRefused = await rejects(() => f.run({ cwd: path.join(temp, 'winroot', 'sys') }), 'system folder');
-    process.env.WINDIR = originalWindir;
-    check(sysRefused && await rejects(() => f.run({ cwd: path.parse(temp).root }), 'whole drive'), 'refuses system folders and drive roots');
-    t.section('.sandbox-config.json');
-    const localB = { harness: 'codex', sandbox: { memoryMb: 4096, networking: false, headless: true }, toolchains: { node: { version: '18' }, rust: { enabled: false } }, mappings: [{ host: './assets', guest: 'C:\\Assets', readOnly: true }, { host: '../shared', guest: 'C:\\Shared', readOnly: false }], scripts: ['./setup.mjs'] };
-    f.writeLocal(f.workB, localB);
-    check(await rejects(() => f.run({ cwd: f.workB }), '--trust-config') && await rejects(() => f.run({ cwd: f.workB }), 'READ/WRITE'), 'an untrusted .sandbox-config.json is refused and its effects are listed');
-    check(await rejects(() => f.run({ cwd: f.workB, ask: async () => false }), 'has not been approved'), 'answering "no" refuses it');
-    const rB = await f.run({ cwd: f.workB, ask: async () => true });
-    check(rB.harnessName === 'codex' && rB.config.sandbox.memoryMb === 4096 && rB.config.sandbox.headless && !rB.config.toolchains.rust.enabled && rB.config.toolchains.python.enabled && rB.versions.node.source === '.sandbox-config.json', 'approved local settings apply over the defaults (incl. toolchains, headless)');
-    check(rB.config.mappings.some((m) => m.host === f.shared && !m.readOnly) && rB.scripts.includes(path.join(f.workB, 'setup.mjs')), 'relative paths resolve against the folder of .sandbox-config.json');
-    check((await f.run({ cwd: f.workB })).harnessName === 'codex' && (await f.run({ cwd: f.workB, noLocalConfig: true })).harnessName === 'claude' && (await f.run({ cwd: f.workB, harness: 'gemini' })).harnessName === 'gemini', 'approval is remembered; --no-local-config and --harness win');
-    check((await f.run({ cwd: f.workB, headless: false })).config.sandbox.headless === false, '--window beats a local headless setting');
-    f.writeLocal(f.workB, { ...localB, sandbox: { memoryMb: 6144 } });
-    check(await rejects(() => f.run({ cwd: f.workB }), 'has not been approved'), 'changing the file requires approval again');
-    const dirC = path.join(temp, 'work-c');
-    ensureDir(dirC);
-    const bad = async (content, needle) => { f.writeLocal(dirC, content); return rejects(() => f.run({ cwd: dirC, trustConfig: true }), needle); };
-    check(await bad({ storage: { root: 'C:\\x' } }, 'storage is not allowed') && await bad({ harnesses: {} }, 'harnesses is not allowed'), 'local file cannot change storage or agent executables');
-    check(await bad({ claudeProfile: { hostDir: 'C:\\x' } }, 'claudeProfile.hostDir is not allowed') && await bad({ toolchains: { node: { hostDir: 'x' } } }, 'toolchains.node.hostDir is not allowed'), 'local file cannot point at host folders');
-    check(await bad({ sandbox: { memoryMb: 12 } }, 'sandbox.memoryMb:') && await bad({ mappings: [{ host: 'x', guest: 'C:\\Windows\\x', readOnly: true }] }, 'reserved or invalid guest path') && await bad({ provisioning: { git: { access: 'admin' } } }, 'provisioning.git.access:'), 'values are type-checked; reserved guest paths and unknown git modes are rejected');
-    check(await bad('{\n  // a comment\n  "readOnly": tru\n}', 'line 3') && await bad({ _comment: 'old style' }, '_comment is not allowed'), 'broken JSON is reported with line and column; unknown keys are rejected');
-    f.writeLocal(dirC, '// comments and trailing commas are fine\n{\n  "readOnly": true, /* inline */\n}\n');
-    check((await f.run({ cwd: dirC, trustConfig: true })).config.readOnly === true, '.sandbox-config.json may contain comments and trailing commas');
-    f.writeLocal(dirC, { claudeProfile: { copyCredentials: true }, network: { blockPrivateRanges: false }, provisioning: { git: { access: 'full' } } });
-    check(await rejects(() => f.run({ cwd: dirC }), 'copies your Claude LOGIN') && await rejects(() => f.run({ cwd: dirC }), 'turns OFF the LAN block') && await rejects(() => f.run({ cwd: dirC }), 'commit and push'), 'risky settings are called out before approval');
-    fs.rmSync(path.join(dirC, '.sandbox-config.json'));
+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

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