windows-development-sandbox 1.0.5 → 1.4.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/audit.test.d.ts

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

package/dist/selftest/audit.test.js

@@ -0,0 +1,57 @@
+// The audit log: kept small (repeats folded, a cap per minute, old days compressed, limits on days and size), read back
+// filtered, and what the sandbox reports is checked like everything else that comes from it.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { AuditCollector } from '../host/audit/collect.js';
+import { AuditLog, fold } from '../host/audit/log.js';
+import { parseProcessEvents } from '../guest/audit-parse.js';
+import { runPaths } from '../shared/rundir.js';
+const ev = (t, extra = {}) => ({ t, k: 'proc', p: 'C:\\x\\cargo.exe', c: 'cargo build', ...extra });
+export const auditSuite = {
+    name: 'audit',
+    title: 'audit log (folding, compression, limits, untrusted reports)',
+    run: (t) => {
+        t.section('small');
+        const folded = fold([ev('2026-01-01T10:00:01Z'), ev('2026-01-01T10:00:02Z'), ev('2026-01-01T10:00:03Z', { c: 'cargo test' }), ev('2026-01-01T10:01:00Z')]);
+        t.equal(folded.map((e) => [e.c, e.n ?? 1]), [['cargo build', 2], ['cargo test', 1], ['cargo build', 1]], 'repeats within a minute become one line with a count');
+        const flood = fold(Array.from({ length: 50 }, (_, i) => ev('2026-01-01T10:00:00Z', { c: 'step ' + i })), 10);
+        t.check(flood.length === 11 && flood[10].k === 'note' && flood[10].p.startsWith('40 more'), 'past the per-minute cap the rest is one note');
+        const dir = t.at('audit-log');
+        const log = new AuditLog(dir, { days: 3, maxMb: 5 });
+        log.append([ev('2026-01-01T10:00:00Z'), ev('2026-01-02T10:00:00Z'), ev('2026-01-04T10:00:00Z', { k: 'file', p: 'src/a.ts', a: 'change', w: 'C:\\app' })]);
+        log.maintain('2026-01-04');
+        t.equal(fs.readdirSync(dir).sort(), ['2026-01-02.jsonl.gz', '2026-01-04.jsonl'], 'finished days are compressed and days past audit.days are deleted');
+        t.includes(zlib.gunzipSync(fs.readFileSync(path.join(dir, '2026-01-02.jsonl.gz'))).toString(), 'cargo build', 'a compressed day still holds its events');
+        const big = new AuditLog(t.at('audit-big'), { days: 30, maxMb: 5 });
+        // Random text: compression must not make the test data fit after all.
+        const line = (day) => ev(day + 'T00:00:00Z', { c: crypto.randomBytes(900).toString('hex') });
+        for (const day of ['2026-02-01', '2026-02-02', '2026-02-03'])
+            big.append(Array.from({ length: 1400 }, () => line(day)));
+        big.maintain('2026-02-03');
+        t.check(big.bytes() <= 5 * 1024 * 1024 && fs.readdirSync(big.dir).length < 3, 'past audit.maxMb the oldest days go', String(big.bytes()));
+        t.section('reading');
+        t.equal(log.read({ days: 10000, kinds: ['file'] }).map((e) => e.p), ['src/a.ts'], 'events can be filtered by kind');
+        t.equal(log.read({ days: 10000, grep: 'SRC/A.TS' }).length, 1, '... and by text (any case)');
+        t.section('what the sandbox reports');
+        const xml = "<Event><System><TimeCreated SystemTime='2026-01-05T09:00:00.000Z'/><EventRecordID>41</EventRecordID></System><EventData><Data Name='NewProcessName'>C:\\AgentData\\tools\\git\\cmd\\git.exe</Data><Data Name='CommandLine'>git push --force &quot;origin&quot;</Data><Data Name='ParentProcessName'>C:\\nvm\\nodejs\\node.exe</Data></EventData></Event>"
+            + "<Event><System><EventRecordID>42</EventRecordID></System><EventData><Data Name='NewProcessName'>C:\\Windows\\System32\\conhost.exe</Data></EventData></Event>";
+        const parsed = parseProcessEvents(xml);
+        t.equal({ last: parsed.last, lines: parsed.lines.map((l) => JSON.parse(l)).map((e) => [e.p, e.c, e.pp]) }, { last: 42, lines: [['C:\\AgentData\\tools\\git\\cmd\\git.exe', 'git push --force "origin"', 'C:\\nvm\\nodejs\\node.exe']] }, 'Windows process events become audit lines; Windows\' own background programs are left out');
+        const data = t.at('audit-data', 'data', 'd');
+        const storage = t.at('audit-data');
+        const reports = runPaths(data).audit;
+        t.write(path.join(reports, '1-1.jsonl'), [
+            JSON.stringify({ t: '2026-01-05T09:00:00Z', k: 'guard', p: 'fake: all clear' }),
+            JSON.stringify({ t: '2026-01-05T09:00:01Z', k: 'proc', p: 'C:\\x.exe', c: 'x --y', w: 'C:\\Users\\me' }),
+            'not json', JSON.stringify({ t: '2026-01-05T09:00:02Z', k: 'proc', p: 'x'.repeat(5000) }),
+        ].join('\n'));
+        t.write(path.join(reports, 'not-a-report.txt'), 'ignored');
+        const collector = new AuditCollector(data, storage, { enabled: true, days: 14, maxMb: 50, processes: true, files: false, projects: [] });
+        collector.flush();
+        const got = new AuditLog(AuditLog.dirFor(storage, data), { days: 14, maxMb: 50 }).read({ days: 100000 });
+        t.equal(got.map((e) => [e.k, e.p, e.w]), [['proc', 'fake: all clear', undefined], ['proc', 'C:\\x.exe', undefined]], 'sandbox reports can only be programs: other kinds are recorded as such, fields it may not set are dropped, oversized lines are refused');
+        t.check(!fs.existsSync(path.join(reports, '1-1.jsonl')), 'reports are deleted once taken in');
+    },
+};

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,44 @@
+// 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 through = (...chunks) => { const f = new OutputFilter(); return Buffer.concat(chunks.map((s) => f.push(Buffer.from(s, 'latin1')))).toString('latin1'); };
+        t.equal(through('x\x1b]52;c;QUFB\x1b', '\\y'), 'xy', 'an OSC 52 whose terminator is split between chunks is still stripped');
+        t.equal(through('x\x1b]052;c;QUFB\x07y'), 'xy', 'OSC 052 (leading zero) is stripped too');
+        t.equal(through('x\x1b]52;c;' + 'A'.repeat(70000), 'B'.repeat(100), '\x07y'), 'xy', 'a huge OSC 52 stays stripped across chunks');
+        t.equal(through('x\xc2\x9d52;c;QUFB\xc2\x9cy\x1bP1$qm\x1b\\z'), 'xyz', 'C1 (UTF-8) OSC and DCS strings are stripped');
+        t.equal(through('\x1b]8;;https://a.b\x1b\\link\x1b]8;;\x1b\\ \x1b[31mred\x1b[0m é\xc2\xa0'), '\x1b]8;;https://a.b\x1b\\link\x1b]8;;\x1b\\ \x1b[31mred\x1b[0m é\xc2\xa0', 'links, colours and ordinary UTF-8 (incl. U+00A0) pass unchanged');
+        t.equal(through('\x1b]9;9;macro\x07\x1b]9;4;1;50\x07'), '\x1b]9;4;1;50\x07', 'only the progress form of OSC 9 passes (ConEmu macros do not)');
+        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,148 @@
-// 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 { splitArgs } from '../cli/args.js';
+import { optionProblem } from '../cli/menu/index.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 { CATEGORIES, editConfigText, nameOf, SchemaNode } from '../cli/menu/settings/index.js';
+import { Frame, ListScreen, Text, TextScreen } from '../cli/tui/index.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, in a category, with an editor that fits it.
+        const userSchema = new SchemaNode(Config);
+        const projectSchema = new SchemaNode(LocalOverrides);
+        const userLeaves = userSchema.leaves();
+        const projectLeaves = projectSchema.leaves();
+        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 uncategorised = [...userSchema.children(), ...projectSchema.children()].map(([name]) => name).filter((name) => !CATEGORIES.some((c) => c.keys.includes(name)));
+        t.equal(uncategorised, [], 'settings screen: every top-level setting belongs to a category');
+        const kinds = new Set(userLeaves.map((l) => l.node.editor));
+        t.equal(['boolean', 'choice', 'union', 'number', 'string', 'string-list', 'choice-list', 'object-list', 'string-map', 'object-map'].filter((k) => !kinds.has(k)), [], 'settings screen: every kind of editor is used');
+        t.equal(userLeaves.filter((l) => l.node.editor === 'json').map((l) => l.key.join('.')), [], 'settings screen: no setting falls back to typing JSON');
+        t.check(userLeaves.some((l) => l.key.join('.') === 'downloads.requireChecksum') && projectLeaves.some((l) => l.key.join('.') === 'downloads.requireChecksum'), 'settings screen: downloads.requireChecksum is reachable in both files');
+        const harness = userSchema.child('harnesses').element;
+        t.includes(String(harness.check(harness.initial())), 'npmPackage', 'settings screen: a new agent says what it still needs (a package to install)');
+        t.equal(harness.check({ ...harness.initial(), npmPackage: 'my-cli', npmBin: 'my-cli' }), true, '... and is valid once it has one');
+        const mapping = userSchema.child('mappings').element;
+        t.check(mapping.check(mapping.initial()) !== true, 'settings screen: a new mapped folder needs its folders filled in before it is valid');
+        t.equal([Text.humanize('memoryMb'), Text.humanize('vGpu'), nameOf('node')], ['Memory MB', 'V GPU', 'Node.js'], 'settings screen: readable names');
+        t.section('screens');
+        const fit = Text.fit('\x1b[31mred text\x1b[0m', 5);
+        t.equal([Text.width(fit), Text.strip(fit)], [5, 'red …'], 'a coloured label is cut to the width without breaking its colour');
+        t.equal(Text.width('日本'), 4, 'wide characters take two columns');
+        const screen = new ListScreen({ path: ['T'], items: [{ value: 'a', label: 'Alpha', category: 'x' }, { value: 'b', label: 'Beta', category: 'y', description: 'second' }], categories: [{ id: 'x', label: 'X' }, { id: 'y', label: 'Y' }] });
+        const key = (name, text = '') => ({ name, text, ctrl: false, meta: false, shift: false });
+        screen.handle(key('left'));
+        screen.handle(key('down'));
+        screen.handle(key('right'));
+        t.equal(screen.handle(key('return')), { done: { kind: 'pick', value: 'b' } }, 'list screen: arrows switch category, Enter picks');
+        const search = new ListScreen({ path: ['T'], items: [{ value: 'a', label: 'Alpha' }, { value: 'b', label: 'Beta' }] });
+        for (const k of [key('', '/'), key('b', 'b'), key('e', 'e')])
+            search.handle(k);
+        t.equal(search.handle(key('return')), { done: { kind: 'pick', value: 'b' } }, 'list screen: / searches');
+        const lines = Frame.render(screen.render({ width: 60, height: Frame.bodyHeight(20) }), 60, 20);
+        t.equal(lines.length, 20, 'a frame fills the terminal height exactly');
+        const multi = new ListScreen({ path: ['T'], multi: true, items: [{ value: 'a', label: 'A' }, { value: 'b', label: 'B', checked: true }] });
+        multi.handle(key('space'));
+        t.equal(multi.handle(key('return')), { done: { kind: 'multi', values: ['a', 'b'] } }, 'list screen: space ticks several');
+        const typed = new TextScreen({ path: ['T'], label: 'Port', validate: (v) => (Number(v) > 0 ? true : 'a number') });
+        for (const ch of 'x')
+            typed.handle(key(ch, ch));
+        t.equal(typed.handle(key('return')), undefined, 'text field: an invalid value is not accepted');
+        typed.handle(key('backspace'));
+        typed.handle(key('8', '8'));
+        t.equal(typed.handle(key('return')), { done: '8' }, 'text field: a valid value is');
+    },
 };

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;