windows-development-sandbox 1.4.0 → 1.4.3

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

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

package/dist/selftest/accounts.test.js

@@ -1,7 +1,7 @@
 // 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';
+import { AccountStore } from '../host/profile/index.js';
 export const accountsSuite = {
     name: 'accounts',
     title: 'Claude accounts (save, switch, remove, safe names)',
@@ -12,33 +12,36 @@ export const accountsSuite = {
         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);
+        new AccountStore(storage).save(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');
+        new AccountStore(storage).save(dataA, 'work', {
+            claudeDir: t.at('host-login'),
+            globalStateFile: t.at('host-login.json'),
+        });
+        t.equal(new AccountStore(storage).list(dataA).length, 2, 'accounts can be saved from the sandbox and from this PC');
+        t.equal(new AccountStore(storage).defaultName(), 'personal', 'the first account saved becomes the default');
+        t.equal(new AccountStore(storage).activeFor(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');
+        new AccountStore(storage).activate(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.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.equal(new AccountStore(storage).activeFor(dataA), 'work', 'the new account is active');
+        t.includes(JSON.stringify(new AccountStore(storage).read('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');
+        new AccountStore(storage).setDefault('work');
+        new AccountStore(storage).remove('work');
+        t.equal(new AccountStore(storage).defaultName(), null, 'removing the default account clears the default');
+        await t.throws(() => new AccountStore(storage).activate(dataA, 'nope'), 'Unknown account', 'an unknown account cannot be activated');
+        await t.throws(() => new AccountStore(storage).save(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)');
+        await t.throws(() => new AccountStore(t.at('acct-storage')).save(otherData, 'index', fromHost), 'Invalid account name', 'an account cannot be called "index" (it would overwrite the index)');
+        await t.throws(() => new AccountStore(t.at('acct-storage')).save(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

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

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

@@ -2,8 +2,10 @@
 // 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';
+import { DEFAULTS } from '../core/config/index.js';
+import { agentCommands, commandsDir, realAgent } from '../host/agent-commands/index.js';
+import { forwardingCmd, forwardingSh } from '../host/agent-commands/index.js';
+import { reconcileAgentCommands } from '../host/agent-commands/index.js';
 export const agentCommandsSuite = {
     name: 'agent-commands',
     title: 'agent commands (Beta): claude, codex ... forwarded into a hidden sandbox',
@@ -19,9 +21,11 @@ export const agentCommandsSuite = {
         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('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();
+        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');
@@ -33,7 +37,7 @@ export const agentCommandsSuite = {
         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');
+        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');

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

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

package/dist/selftest/audit.test.js

@@ -6,21 +6,40 @@ 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 });
+import { parseProcessEvents } from '../guest/audit/parse.js';
+import { RunDir } from '../shared/channel/index.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 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.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');
@@ -35,23 +54,37 @@ export const auditSuite = {
         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 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');
+        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;
+        const reports = new RunDir(data).auditDir;
         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) }),
+            '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: [] });
+        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.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

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

package/dist/selftest/channel.test.js

@@ -1,24 +1,84 @@
 // 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';
+import { safeId } from '../shared/channel/index.js';
+import { GuestRequestSchema, SandboxStatusSchema, SessionStatusSchema } from '../shared/channel/index.js';
+import { bootLine, firstStartNotice, pendingDownloads, readyIn, stillWorking } from '../cli/commands/launch/index.js';
+import { encodeFrame, FrameReader, FrameType, fixWindowsKeys, helloFrame, InputJoiner, MAX_FRAME_BYTES, MOUSE_OFF, OutputFilter, } from '../shared/pty/index.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;
+        const validRequest = (r) => GuestRequestSchema.safeParse(r).success;
+        const validSession = (s) => SessionStatusSchema.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' } };
+        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('boot progress');
+        const goodStatus = {
+            launchId: 'l1',
+            phase: 'provisioning',
+            message: '[3/8] Developer tools',
+            updatedAt: 'x',
+            workspaceHost: 'C:\\p',
+            guestWorkspace: 'C:\\Workspace',
+            headless: false,
+        };
+        const progress = {
+            step: 3,
+            steps: 8,
+            title: 'Developer tools',
+            active: [{ name: 'Rust', percent: 40 }, { name: 'Go' }],
+            done: 2,
+            total: 6,
+        };
+        const parsed = (s) => SandboxStatusSchema.safeParse(s);
+        t.equal(parsed({ ...goodStatus, progress }).data?.progress, progress, 'a well-formed boot progress is accepted');
+        t.check(parsed(goodStatus).success && parsed(goodStatus).data?.progress === undefined, 'a status without progress (an older sandbox) is accepted');
+        const hostile = [
+            { ...progress, title: 'x'.repeat(5000) },
+            { ...progress, active: Array.from({ length: 100 }, () => ({ name: 'a' })) },
+            { ...progress, active: [{ name: 'a', percent: 500 }] },
+            { ...progress, step: -1 },
+            { ...progress, done: 1e9 },
+            { ...progress, extra: 1 },
+            'pwned',
+        ];
+        t.equal(hostile.map((p) => {
+            const r = parsed({ ...goodStatus, progress: p });
+            return r.success && r.data.progress === undefined;
+        }), hostile.map(() => true), 'an oversized or malformed progress is dropped, the status itself still counts');
+        t.check(!parsed({ ...goodStatus, phase: 'pwned', progress }).success, 'a status with an unknown phase is still rejected');
+        const line = (p) => bootLine(parsed({ ...goodStatus, progress: p }).data ?? null).line;
+        t.equal(line(progress), '[3/8] Developer tools: downloading Rust 40%; setting up Go (2 of 6 done)', 'the line shows the step, the download and what is set up');
+        t.equal(line({ ...progress, title: 'Agent: claude', step: 6, active: [], done: 0, total: 0 }), '[6/8] Agent: claude', 'a step without tools is just its title');
+        t.equal(line({ ...progress, active: [{ name: '\x1b]52;c;ZXZpbA==\x07Ru\x1b[2Jst\r\n', percent: 99 }] }), '[3/8] Developer tools: downloading Rust 99% (2 of 6 done)', 'escape sequences and control characters from the sandbox never reach the terminal');
+        t.equal(bootLine(null).line, 'Starting Windows Sandbox', 'before the sandbox writes anything');
+        t.equal(bootLine(parsed({ ...goodStatus, message: 'Installing Go (1 of 3 done)' }).data).line, 'Installing Go (1 of 3 done)', 'an older sandbox: its message');
+        t.equal(bootLine(parsed({ ...goodStatus, progress: { ...progress, active: [{ name: 'Rust', percent: 50 }] } }).data).key, bootLine(parsed({ ...goodStatus, progress: { ...progress, active: [{ name: 'Rust', percent: 60 }] } }).data).key, 'a download moving on is no new plain line (only a new step or tool is)');
+        t.equal(stillWorking('Rust', 3 * 60 * 1000), 'Still working on Rust (3 min). Full log: sandbox logs -f', 'the notice after a long quiet spell');
+        t.equal(readyIn(432_000), 'Ready in 7 min 12 s.', 'the time a first start took');
+        const pending = pendingDownloads(['node', 'rust', 'cpp', 'postgres', 'node', 'constructor'], (dir) => dir === 'nvm');
+        t.equal(pending, { names: ['rust', 'C/C++', 'PostgreSQL'], mb: 900 }, 'only what is not downloaded yet counts, once each');
+        t.equal(firstStartNotice(false, { names: [], mb: 0 }), null, 'a later start with everything downloaded says nothing');
+        t.check(/^First start: .*\(about 900 MB: rust, C\/C\+\+, PostgreSQL\)\. This can take 5-20 minutes/.test(firstStartNotice(true, pending) ?? ''), 'the first start says what it downloads, roughly how much, and how long it can take');
+        t.check(/^New tools for this project: .*about 1\.8 GB: MSVC, rust/.test(firstStartNotice(false, pendingDownloads(['msvc', 'rust'], () => false)) ?? ''), 'a new toolchain later on gets its own heads-up');
         t.section('terminal frames');
         const filter = new OutputFilter();
         const filtered = Buffer.concat([
@@ -27,7 +87,10 @@ export const channelSuite = {
             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'); };
+        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');
@@ -38,7 +101,27 @@ export const channelSuite = {
         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({
+            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');
+        t.section('typed input keeps escape sequences whole');
+        const joined = (...chunks) => {
+            const j = new InputJoiner();
+            const out = chunks.map((c) => j.push(Buffer.from(c, 'latin1')).toString('latin1'));
+            out.push(j.flush().toString('latin1'));
+            return out.filter(Boolean);
+        };
+        t.equal(joined('ab\x1b[', 'C'), ['ab', '\x1b[C'], 'a Right arrow split after ESC[ is sent whole (ConPTY would read Alt+[ and a typed "C")');
+        t.equal(joined('\x1b', '[<0;10;', '5M', 'x'), ['\x1b[<0;10;5M', 'x'], 'a mouse report split three ways is sent as one');
+        t.equal(joined('\x1bO', 'A'), ['\x1bOA'], 'an SS3 key split after ESC O is sent whole');
+        t.equal(joined('a\x1b'), ['a', '\x1b'], 'a lone Esc key is held, then sent by the flush');
+        t.equal(joined('\x1b[A\x1bx\x7f'), ['\x1b[A\x1bx\x7f'], 'complete keys (arrows, Alt+x, Backspace) pass at once');
+        t.equal(joined('\x1b[' + '1;'.repeat(40)), ['\x1b[' + '1;'.repeat(40)], 'an endless "sequence" is not held back');
+        t.check(MOUSE_OFF.includes('\x1b[?1000l') && MOUSE_OFF.includes('\x1b[?1003l') && MOUSE_OFF.includes('\x1b[?1006l'), 'leaving a session turns every mouse tracking mode off in your terminal');
     },
 };

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

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

package/dist/selftest/cli.test.js

@@ -8,12 +8,12 @@ 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 { ago, colorEnabled, shorten, shortenMiddle } from '../cli/output/index.js';
+import { hoistConfig, withoutConfig } from '../cli/argv.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';
+import { ConfigSchema, LocalOverridesSchema } from '../core/schema/index.js';
 export const cliSuite = {
     name: 'cli',
     title: 'command manifest, argument parser, menu helpers, settings screen',
@@ -36,13 +36,19 @@ export const cliSuite = {
         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');
+        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');
+        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');
@@ -57,7 +63,12 @@ export const cliSuite = {
         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('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');
@@ -88,7 +99,7 @@ export const cliSuite = {
         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, '// 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');
@@ -101,17 +112,35 @@ export const cliSuite = {
         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 userSchema = new SchemaNode(ConfigSchema);
+        const projectSchema = new SchemaNode(LocalOverridesSchema);
         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.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([
+            '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');
+        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');
@@ -122,19 +151,42 @@ export const cliSuite = {
         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 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' }] });
+        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 }] });
+        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') });

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

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

package/dist/selftest/cmdline.test.js

@@ -3,10 +3,23 @@
 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';
+import { isWin } from '../core/util/index.js';
+import { runNode } from './support/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%'];
+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',
@@ -21,14 +34,26 @@ export const cmdlineSuite = {
             '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') },
+        const probe = await runNode([
+            '--input-type=module',
+            '-e',
+            script,
+            pathToFileURL(path.join(t.packageRoot, 'dist', 'guest', 'sessions', '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 */ }
+        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);
@@ -36,7 +61,11 @@ export const cmdlineSuite = {
         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 });
+            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

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

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