windows-development-sandbox 1.1.0 → 1.4.1

package/dist/selftest/sync.test.js

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { syncClaudeMem } from '../sync/claude-mem.js';
 import { readSyncState, syncHistoryIn, syncHistoryOut, syncStatePath, translatePaths } from '../sync/history.js';
+import { beatLife, endLife, explainStop, lastStopWarning, startLife } from '../host/stops.js';
 export const syncSuite = {
     name: 'sync',
     title: 'history and claude-mem sync',
@@ -19,13 +20,17 @@ export const syncSuite = {
         t.write(path.join(hostProject, 's1.jsonl'), '{"cwd":"D:\\\\Code\\\\my-app","t":1}\n');
         t.write(path.join(hostDot, 'projects', 'C--Other', 's2.jsonl'), '{"x":1}\n');
         t.write(path.join(hostDot, 'todos', 's1.json'), '[]');
-        t.write(path.join(hostDot, 'history.jsonl'), '{"display":"hi","timestamp":1,"project":"D:\\\\Code\\\\my-app"}\n');
+        t.write(path.join(hostDot, 'history.jsonl'), '{"display":"hi","timestamp":1,"project":"D:\\\\Code\\\\my-app"}\n{"display":"secret plan","timestamp":0,"project":"C:\\\\Other"}\n');
         const sides = { hostClaudeDir: hostDot, guestClaudeDir: guestDot, hostWorkspace: hostWs, guestWorkspace: guestWs };
         syncHistoryIn(sides);
         t.includes(fs.readFileSync(path.join(guestProject, 's1.jsonl'), 'utf8'), 'C:\\\\Workspace\\\\my-app', 'history in: the current project is renamed and its paths translated');
-        t.check(fs.existsSync(path.join(guestDot, 'projects', 'C--Other', 's2.jsonl')), 'history in: other projects are copied');
-        t.check(fs.existsSync(path.join(guestDot, 'todos', 's1.json')), 'history in: todos are copied');
-        t.includes(fs.readFileSync(path.join(guestDot, 'history.jsonl'), 'utf8'), 'C:\\\\Workspace\\\\my-app', 'prompt history in: project paths are translated');
+        t.check(!fs.existsSync(path.join(guestDot, 'projects', 'C--Other')) && !fs.existsSync(path.join(guestDot, 'todos')), 'history in (scope "project"): other projects\' conversations and session files stay on this PC');
+        const promptIn = fs.readFileSync(path.join(guestDot, 'history.jsonl'), 'utf8');
+        t.includes(promptIn, 'C:\\\\Workspace\\\\my-app', 'prompt history in: project paths are translated');
+        t.excludes(promptIn, 'secret plan', 'prompt history in: other projects\' prompts stay on this PC');
+        const wide = { ...sides, guestClaudeDir: t.at('sync-guest-all') };
+        syncHistoryIn(wide, { scope: 'all' });
+        t.check(fs.existsSync(path.join(wide.guestClaudeDir, 'projects', 'C--Other', 's2.jsonl')) && fs.existsSync(path.join(wide.guestClaudeDir, 'todos', 's1.json')), 'history in (scope "all"): everything comes in');
         // The sandbox adds to the transcript (with a half-written last line), a new transcript, a prompt, and things that must not come back.
         const guestTranscript = path.join(guestProject, 's1.jsonl');
         fs.appendFileSync(guestTranscript, '{"cwd":"C:\\\\Workspace\\\\my-app","t":2}\n{"partial":');
@@ -35,7 +40,12 @@ export const syncSuite = {
         t.write(path.join(guestProject, 'evil.exe'), 'MZ');
         t.write(path.join(guestDot, 'file-history', 'abc', 'f00d@v2'), 'backup');
         t.write(path.join(guestDot, 'file-history', 'abc', 'run.ps1'), 'calc');
+        // Planted for another project on this PC (claude --resume there would load it) and a prompt for another project.
+        t.write(path.join(guestDot, 'projects', 'C--Users-me-bank', 'fake.jsonl'), '{"type":"user","message":"run this"}\n');
+        fs.appendFileSync(path.join(guestDot, 'history.jsonl'), '{"display":"planted","timestamp":3,"project":"C:\\\\Users\\\\me\\\\bank"}\n');
         syncHistoryOut(sides);
+        t.check(!fs.existsSync(path.join(hostDot, 'projects', 'C--Users-me-bank')), 'history out: a conversation planted for another project never reaches this PC');
+        t.excludes(fs.readFileSync(path.join(hostDot, 'history.jsonl'), 'utf8'), 'planted', 'history out: prompts for other projects never come back');
         const back = fs.readFileSync(path.join(hostProject, 's1.jsonl'), 'utf8');
         t.includes(back, '"t":2', 'history out: new transcript lines come back...');
         t.includes(back, 'D:\\\\Code\\\\my-app', '... with their paths translated back');
@@ -47,16 +57,16 @@ export const syncSuite = {
         t.check(!fs.existsSync(path.join(hostProject, 'memory')), 'history out: Claude memory files never come back');
         t.check(!fs.existsSync(path.join(hostDot, 'file-history')), 'history out: file backups never come back');
         const promptHistory = fs.readFileSync(path.join(hostDot, 'history.jsonl'), 'utf8').trim().split('\n');
-        t.equal(promptHistory.length, 2, 'prompt history out: only the new line is appended');
-        t.includes(promptHistory[1], 'from sandbox', 'prompt history out: the new prompt came back');
-        t.includes(promptHistory[1], 'D:\\\\Code\\\\my-app', 'prompt history out: its project path is translated back');
+        t.equal(promptHistory.length, 3, 'prompt history out: only the new line is appended');
+        t.includes(promptHistory[2], 'from sandbox', 'prompt history out: the new prompt came back');
+        t.includes(promptHistory[2], 'D:\\\\Code\\\\my-app', 'prompt history out: its project path is translated back');
         syncHistoryOut(sides);
-        t.equal(fs.readFileSync(path.join(hostDot, 'history.jsonl'), 'utf8').trim().split('\n').length, 2, 'syncing again adds nothing (idempotent)');
+        t.equal(fs.readFileSync(path.join(hostDot, 'history.jsonl'), 'utf8').trim().split('\n').length, 3, 'syncing again adds nothing (idempotent)');
         t.section('history sync: what the sandbox may write into the prompt history');
         const hostile = f.historySides('hostile-history', hostWs, guestWs);
-        t.write(path.join(hostile.guestClaudeDir, 'history.jsonl'), 'not json\n[1,2]\n{"display":"ok","timestamp":2}\n"text"\n');
+        t.write(path.join(hostile.guestClaudeDir, 'history.jsonl'), 'not json\n[1,2]\n{"display":"ok","timestamp":2,"project":"C:\\\\Workspace\\\\my-app"}\n{"display":"no project","timestamp":2}\n"text"\n');
         syncHistoryOut(hostile);
-        t.equal(fs.readFileSync(path.join(hostile.hostClaudeDir, 'history.jsonl'), 'utf8'), '{"display":"ok","timestamp":2}\n', 'only JSON prompt-history entries come back from the sandbox, nothing else it wrote in that file');
+        t.equal(fs.readFileSync(path.join(hostile.hostClaudeDir, 'history.jsonl'), 'utf8'), '{"display":"ok","timestamp":2,"project":"D:\\\\Code\\\\my-app"}\n', 'only JSON prompt-history entries of this project come back from the sandbox, nothing else it wrote in that file');
         t.section('sync state file');
         const stateData = t.at('state-storage', 'data', 'd');
         t.writeJson(syncStatePath(stateData), { hostClaudeDir: 'relative\\.claude', hostWorkspace: 'D:\\x', guestWorkspace: 'C:\\x' });
@@ -90,5 +100,35 @@ export const syncSuite = {
         t.touch(t.write(hostDb, 'host-v3'), 30);
         t.equal(syncClaudeMem(memHost, memGuest, memState, 'out'), 'conflict', 'claude-mem: both sides changed is reported as a conflict');
         t.check(fs.readdirSync(t.temp).some((name) => name.startsWith('mem-host.conflict-')), 'claude-mem: this PC\'s database is kept as .conflict-<time> first', fs.readdirSync(t.temp).join(', '));
+        t.section('how the last sandbox ended');
+        const ev = (id, provider, at, process = '') => ({ id, provider, at, process });
+        t.equal(explainStop([ev(1074, 'User32', '2026-10-13T02:10:30Z', 'C:\\Windows\\servicing\\TrustedInstaller.exe (HOST)')])?.kind, 'updates', 'a restart by Windows Update is recognised');
+        t.equal(explainStop([ev(1074, 'User32', '2026-10-13T02:10:30Z', 'C:\\Windows\\System32\\winlogon.exe (HOST)')])?.text, 'this PC was restarted or shut down (by winlogon.exe)', 'another restart names the program');
+        t.equal(explainStop([ev(41, 'Microsoft-Windows-Kernel-Power', '2026-10-13T02:20:00Z'), ev(42, 'Microsoft-Windows-Kernel-Power', '2026-10-13T02:10:00Z')])?.kind, 'sleep', 'the first event counts (sleep, then a crash)');
+        t.equal(explainStop([ev(2004, 'Microsoft-Windows-Resource-Exhaustion-Detector', '2026-10-13T02:10:00Z')])?.kind, 'memory', 'low memory is recognised');
+        t.equal(explainStop([ev(41, 'SomethingElse', '2026-10-13T02:10:00Z')]), null, 'the same event id from another source is ignored');
+        // The message Hyper-V logged on 13 Oct 2026 when Windows inside the sandbox crashed.
+        const crashMessage = "'8abb707a-972e-42e2-9599-01d125d4595c' has encountered a fatal error.  The guest operating system reported that it failed with the following error codes: ErrorCode0: 0x1A, ErrorCode1: 0x13003, ErrorCode2: 0x2346E5, ErrorCode3: 0x1";
+        t.equal(explainStop([ev(18590, 'Microsoft-Windows-Hyper-V-Worker', '2026-10-13T08:49:08Z', crashMessage)])?.text, 'Windows inside the sandbox crashed (stop code 0x1A, 0x13003)', 'a crash of Windows inside the sandbox is recognised, with its stop code');
+        t.equal(explainStop([ev(24, 'Microsoft-Windows-TerminalServices-LocalSessionManager', '2026-10-13T08:41:40Z', 'PC\\Admin')]), null, 'switching user is not taken for the cause (the sandbox keeps running)');
+        const lifeRoot = t.at('life-storage');
+        const lifeData = path.join(lifeRoot, 'data', 'testdata');
+        const noEvents = () => null;
+        t.equal(lastStopWarning(lifeRoot, lifeData, false, noEvents), null, 'no record: nothing to say');
+        startLife(lifeRoot, lifeData, true, new Date('2026-10-12T20:16:00Z'));
+        beatLife(lifeRoot, lifeData, new Date('2026-10-13T02:09:00Z'));
+        t.equal(lastStopWarning(lifeRoot, lifeData, true, noEvents), null, 'its watcher still runs: the sandbox has not ended');
+        let since = '';
+        const warning = lastStopWarning(lifeRoot, lifeData, false, (s) => { since = s; return { kind: 'updates', at: '2026-10-13T02:10:30Z', text: 'Windows restarted this PC to install updates' }; });
+        t.includes(warning ?? '', 'Windows restarted this PC to install updates', 'the PC stopped under a running sandbox: the next launch says why');
+        t.includes(warning ?? '', 'Pause updates', '... and what keeps it from happening again');
+        t.equal(since, '2026-10-13T02:09:00.000Z', 'the System log is read from the last time the sandbox was seen running');
+        t.equal(lastStopWarning(lifeRoot, lifeData, false, noEvents), null, 'said once only');
+        startLife(lifeRoot, lifeData, true);
+        endLife(lifeRoot, lifeData, null);
+        t.equal(lastStopWarning(lifeRoot, lifeData, false, noEvents), null, 'closed while this PC ran (by you): nothing to say');
+        startLife(lifeRoot, lifeData, true);
+        endLife(lifeRoot, lifeData, { kind: 'sleep', at: '2026-10-13T02:10:00Z', text: 'this PC went to sleep or hibernated' });
+        t.includes(lastStopWarning(lifeRoot, lifeData, false, noEvents) ?? '', 'sandbox.keepAwake', 'ended by sleep: the next launch names keepAwake');
     },
 };

package/dist/selftest/toolchains.test.js

@@ -5,6 +5,9 @@ import { javaMajorFrom, pickGoRelease, pickNodeVersion, pickPackageVersion, pick
 import { parseReleasePage, parseReleaseTags } from '../shared/download.js';
 import { decidePwsh, pcHasPwsh, PWSH_MAX_BYTES, readPwshScripts, usesPwsh } from '../core/detect-pwsh.js';
 import { binstallAsset, CLI_TOOLS, decideCli, pwshAsset } from '../guest/toolchains/catalogue.js';
+import { missingExtensions, vscodeExtensions, vscodeSettings } from '../guest/toolchains/vscode-profile.js';
+import { APP_CATEGORIES, APPS, appsNeedMesa, appsToInstall, exeMatcher } from '../shared/apps.js';
+import { Config, LocalOverrides } from '../core/schema.js';
 export const toolchainsSuite = {
     name: 'toolchains',
     title: 'version pickers, release assets, PowerShell 7 and CLI tool decisions',
@@ -99,5 +102,32 @@ export const toolchainsSuite = {
         const scanned = readPwshScripts(scanRoot);
         t.equal(scanned.map((s) => s.path), ['moh.ps1', 'scripts/build.ps1'], 'pwsh scan: *.ps1 at the root and one folder down only (node_modules skipped)');
         t.equal(scanned[1].text.length, PWSH_MAX_BYTES, 'pwsh scan: each script is read up to its cap');
+        t.section('VS Code set-up');
+        const vs = vscodeSettings({ javaHome: 'C:\\t\\java\\jdk-17.0.9+9', python: 'C:\\t\\python\\python.exe', pwsh: 'C:\\t\\pwsh\\pwsh.exe', gcc: 'C:\\t\\mingw\\bin\\gcc.exe', cl: 'C:\\t\\msvc\\cl.exe', dotnet: 'C:\\t\\dotnet\\dotnet.exe' });
+        t.equal([vs['java.jdt.ls.java.home'], vs['java.configuration.runtimes'][0].name, vs['python.defaultInterpreterPath'], vs['terminal.integrated.defaultProfile.windows'], vs['C_Cpp.default.compilerPath'], vs['dotnet.dotnetPath']], ['C:\\t\\java\\jdk-17.0.9+9', 'JavaSE-17', 'C:\\t\\python\\python.exe', 'PowerShell 7', 'C:\\t\\msvc\\cl.exe', 'C:\\t\\dotnet'], 'vscode: settings point at the sandbox\'s JDK (with its version), Python, PowerShell 7, compiler (MSVC first) and .NET');
+        t.check(!('go.goroot' in vs) && !('git.path' in vs), 'vscode: tools that are not installed are not set');
+        const ext = vscodeExtensions({ toolchains: ['node', 'java'], databases: ['postgres'], recommended: ['Foo.Bar', 'not an id'], extra: ['eamodio.gitlens', 'redhat.java'] });
+        t.check(ext.includes('redhat.java') && ext.includes('mtxr.sqltools-driver-pg') && ext.includes('foo.bar') && ext.includes('eamodio.gitlens') && !ext.includes('not an id') && ext.filter((e) => e === 'redhat.java').length === 1, 'vscode: extensions for the languages and databases in use, the project\'s and yours (no duplicates, nothing malformed)');
+        t.equal(missingExtensions(['golang.go', 'redhat.java'], ['golang.go-0.48.0', 'extensions.json']), ['redhat.java'], 'vscode: only extensions not installed yet are downloaded');
+        t.section('apps catalogue');
+        const ids = APPS.map((a) => a.id);
+        t.equal(ids.filter((id, i) => ids.indexOf(id) !== i), [], 'apps: every id is unique');
+        t.equal(APPS.filter((a) => !APP_CATEGORIES.some((c) => c.id === a.category)).map((a) => a.id), [], 'apps: every app is in a known category');
+        t.equal(APPS.filter((a) => 'github' in a.source && (() => { try {
+            new RegExp(a.source.asset);
+            return false;
+        }
+        catch {
+            return true;
+        } })()).map((a) => a.id), [], 'apps: every GitHub asset pattern compiles');
+        t.check(exeMatcher('/^Godot_v[\\d.]+-stable_win64\\.exe$/')('Godot_v4.7.2-stable_win64.exe') && !exeMatcher('/^Godot_v[\\d.]+-stable_win64\\.exe$/')('Godot_v4.7.2-stable_win64_console.exe') && exeMatcher('Code.exe')('code.EXE'), 'apps: the program is found by name or by pattern');
+        const chosen = appsToInstall({ install: ['firefox', 'jq', 'githubdesktop'], custom: { mine: { name: 'Mine', url: 'https://example.com/m.zip', exe: 'm.exe' } } }, 'readonly');
+        t.equal(chosen.entries.map((e) => e.id), ['7zip', 'firefox', 'jq', 'custom/mine'], 'apps: 7-Zip comes first when an installer needs it; your own programs follow');
+        t.equal(chosen.skipped.length, 1, 'apps: an app with its own git (GitHub Desktop) is skipped unless git access is "full"');
+        t.check(appsNeedMesa({ install: ['godot'], custom: {} }) && !appsNeedMesa({ install: ['jq'], custom: {} }), 'apps: game engines bring Mesa (OpenGL without a GPU) along');
+        const custom = (app) => Config.shape.apps.shape.custom.safeParse({ x: app }).success;
+        t.check(custom({ name: 'A', github: 'o/r', asset: 'win.*\\.zip$', exe: 'a.exe' }) && custom({ name: 'B', url: 'https://x.org/b.zip', exe: 'b.exe' }), 'apps: your own program comes from a GitHub release or an https link');
+        t.check(!custom({ name: 'C', url: 'http://x.org/c.zip', exe: 'c.exe' }) && !custom({ name: 'D', github: 'o/r', asset: '(', exe: 'd.exe' }) && !custom({ name: 'E', github: 'o/r', asset: 'x', url: 'https://x.org', exe: 'e.exe' }), 'apps: plain http, a broken pattern, or both sources are refused');
+        t.check(!LocalOverrides.safeParse({ apps: { custom: {} } }).success && LocalOverrides.safeParse({ apps: { install: ['jq'] } }).success, 'apps: a project file may add catalogue apps but never programs of its own');
     },
 };

package/dist/selftest/workspace-view.test.d.ts

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

package/dist/selftest/workspace-view.test.js

@@ -0,0 +1,89 @@
+// workspaceFilter: the sandbox works on a copy of the project without what git ignores, kept in step both ways.
+import fs from 'node:fs';
+import path from 'node:path';
+import { IgnoreRules } from '../host/workspace-view/rules.js';
+import { WorkspaceView } from '../host/workspace-view/view.js';
+export const workspaceViewSuite = {
+    name: 'workspace-view',
+    title: 'git-ignored files kept out of the sandbox (filtered view, two-way sync)',
+    run: async (t, f) => {
+        t.section('a filtered launch');
+        const project = t.dir('filtered-app');
+        fs.mkdirSync(path.join(project, '.git'));
+        const filtered = { ...f.baseConfig, workspaceFilter: { enabled: true, exclude: [], include: [] } };
+        const gen = await f.launch({ cwd: project }, { config: filtered });
+        const workspace = gen.mappings.find((m) => m.guest.toLowerCase().endsWith('\\filtered-app'));
+        const git = gen.mappings.find((m) => m.guest.toLowerCase().endsWith('\\filtered-app.git'));
+        t.check(Boolean(workspace) && !workspace.host.toLowerCase().startsWith(project.toLowerCase()) && workspace.host.includes('views'), 'the sandbox maps the filtered view, not the project folder');
+        t.check(git?.host === path.join(project, '.git') && !git.readOnly, '... and the project\'s .git beside it, so git works');
+        const noGit = await f.launch({ cwd: project }, { config: { ...filtered, provisioning: { ...filtered.provisioning, git: { ...filtered.provisioning.git, access: 'none' } } } });
+        t.check(!noGit.mappings.some((m) => m.guest.toLowerCase().endsWith('.git')), 'with git access "none" no .git is mapped at all');
+        t.section('which files git ignores');
+        const rulesRoot = t.at('rules');
+        t.write(path.join(rulesRoot, '.gitignore'), 'node_modules/\n*.log\n!keep.log\n.env*\n!.env.example\ndist\n');
+        t.write(path.join(rulesRoot, 'sub', '.gitignore'), 'secret.txt\n!*.log\n');
+        t.write(path.join(rulesRoot, '.git', 'info', 'exclude'), 'local-notes.md\n');
+        const rules = new IgnoreRules(rulesRoot, ['*.pem'], ['dist/keep-me.js']);
+        const verdicts = Object.fromEntries(['src/a.ts', 'node_modules/x/index.js', 'a.log', 'keep.log', '.env', '.env.local', '.env.example', 'dist/out.js', 'sub/secret.txt', 'sub/b.log', 'local-notes.md', 'key.pem', 'dist/keep-me.js', '.git/config'].map((p) => [p, rules.isIgnored(p)]));
+        t.equal(verdicts, {
+            'src/a.ts': false, 'node_modules/x/index.js': true, 'a.log': true, 'keep.log': false, '.env': true, '.env.local': true, '.env.example': false,
+            'dist/out.js': true, 'sub/secret.txt': true, 'sub/b.log': false, 'local-notes.md': true, 'key.pem': true, 'dist/keep-me.js': false, '.git/config': true,
+        }, 'rules: nested .gitignore files, ! exceptions, .git/info/exclude, your own exclude and include patterns');
+        t.section('the view');
+        const host = t.at('project');
+        t.write(path.join(host, '.gitignore'), 'node_modules/\n.env\ndist/\n');
+        t.write(path.join(host, 'src', 'main.ts'), 'console.log(1);\n');
+        t.write(path.join(host, 'README.md'), '# hi\n');
+        t.write(path.join(host, '.env'), 'API_KEY=secret\n');
+        t.write(path.join(host, 'node_modules', 'pkg', 'index.js'), 'host build');
+        fs.mkdirSync(path.join(host, '.git'), { recursive: true });
+        const paths = WorkspaceView.pathsFor(t.at('storage'), host);
+        const view = new WorkspaceView({ ...paths, guestGitDir: 'C:\\Workspace\\project.git' });
+        view.prepare();
+        const inView = (rel) => fs.existsSync(path.join(paths.view, ...rel.split('/')));
+        t.check(inView('src/main.ts') && inView('README.md') && inView('.gitignore'), 'view: what git tracks is there');
+        t.check(!inView('.env') && !inView('node_modules'), 'view: ignored files (.env, node_modules) are not');
+        t.equal(fs.readFileSync(path.join(paths.view, '.git'), 'utf8'), 'gitdir: C:/Workspace/project.git\n', 'view: its .git points at the project\'s real .git (mapped separately)');
+        t.check(!paths.view.toLowerCase().startsWith(host.toLowerCase()), 'view: it lives outside the project');
+        t.section('both ways');
+        t.write(path.join(host, 'src', 'main.ts'), 'console.log(2);\n');
+        t.touch(path.join(host, 'src', 'main.ts'), 5);
+        view.syncChanged(['src/main.ts']);
+        t.equal(fs.readFileSync(path.join(paths.view, 'src', 'main.ts'), 'utf8'), 'console.log(2);\n', 'your edit reaches the sandbox');
+        t.write(path.join(paths.view, 'src', 'new.ts'), 'export {};\n');
+        t.write(path.join(paths.view, 'node_modules', 'pkg', 'index.js'), 'sandbox build');
+        t.write(path.join(paths.view, 'dist', 'bundle.js'), 'built');
+        view.syncAll();
+        t.check(fs.existsSync(path.join(host, 'src', 'new.ts')), 'a file the agent creates reaches your project');
+        t.equal(fs.readFileSync(path.join(host, 'node_modules', 'pkg', 'index.js'), 'utf8'), 'host build', 'the sandbox\'s own node_modules never overwrite yours');
+        t.check(!fs.existsSync(path.join(host, 'dist')), 'its build output stays in the sandbox');
+        fs.rmSync(path.join(paths.view, 'README.md'));
+        view.syncAll();
+        t.check(!fs.existsSync(path.join(host, 'README.md')), 'a deletion in the sandbox is repeated in your project');
+        fs.rmSync(path.join(host, 'src', 'new.ts'));
+        view.syncAll();
+        t.check(!inView('src/new.ts'), 'a deletion in your project is repeated in the sandbox');
+        t.section('conflicts and changing rules');
+        t.write(path.join(host, 'src', 'main.ts'), 'yours\n');
+        t.touch(path.join(host, 'src', 'main.ts'), 20);
+        t.write(path.join(paths.view, 'src', 'main.ts'), 'sandbox\n');
+        t.touch(path.join(paths.view, 'src', 'main.ts'), 30);
+        const stats = view.syncAll();
+        const conflicts = fs.readdirSync(path.join(host, 'src')).filter((n) => n.includes('.sandbox-conflict-'));
+        t.check(stats.conflicts === 1 && fs.readFileSync(path.join(host, 'src', 'main.ts'), 'utf8') === 'yours\n' && conflicts.length === 1 && fs.readFileSync(path.join(host, 'src', conflicts[0]), 'utf8') === 'sandbox\n', 'changed on both sides: yours stays, the sandbox\'s version is kept next to it');
+        t.equal(fs.readFileSync(path.join(paths.view, 'src', 'main.ts'), 'utf8'), 'yours\n', '... and the sandbox sees yours');
+        t.write(path.join(host, '.gitignore'), 'node_modules/\ndist/\n');
+        view.syncChanged(['.gitignore']);
+        t.check(inView('.env'), 'a file no longer ignored comes in when .gitignore changes');
+        t.equal(view.syncAll(), { toView: 0, toHost: 0, deleted: 0, conflicts: 0, skipped: 0 }, 'a pass with nothing changed copies nothing');
+        t.check(view.syncChanged(['../outside.txt', 'C:/Windows/x', '']).toHost === 0, 'paths from outside the project are ignored');
+        t.section('live');
+        const stop = view.watch(60000);
+        t.write(path.join(host, 'live.txt'), 'from you');
+        const arrived = await t.waitFor(() => inView('live.txt'), 5000);
+        t.write(path.join(paths.view, 'live-back.txt'), 'from the sandbox');
+        const back = await t.waitFor(() => fs.existsSync(path.join(host, 'live-back.txt')), 5000);
+        stop();
+        t.check(Boolean(arrived) && Boolean(back), 'changes on either side arrive within a second or two while it watches');
+    },
+};

package/dist/shared/apps.d.ts

@@ -0,0 +1,49 @@
+import type { Config, GitAccess } from '../core/types.js';
+export type AppCategory = 'editors' | 'databases' | 'api' | 'git' | 'utilities' | 'browsers' | 'gamedev' | 'cloud' | 'diagrams' | 'network' | 'cli';
+export declare const APP_CATEGORIES: {
+    id: AppCategory;
+    label: string;
+    description: string;
+}[];
+/** Where a download comes from. Resolvers (sublime, kubectl ...) are code in guest/apps, named here by id. */
+export type AppSource = {
+    github: string;
+    asset: string;
+} | {
+    url: string;
+} | {
+    resolve: string;
+} | {
+    npm: string;
+};
+export interface AppEntry {
+    id: string;
+    name: string;
+    category: AppCategory;
+    about: string;
+    size: string;
+    source: AppSource;
+    /** How the download is unpacked: an archive (zip/7z/tar, the default), the file itself, an NSIS installer or an MSI. */
+    unpack?: 'archive' | 'file' | 'nsis' | 'msi';
+    /** The program to start (or the tool on PATH): a file name, or a regex (/.../) for names with a version in them. */
+    exe: string;
+    /** A command-line tool: its folder goes on PATH (no desktop shortcut). */
+    cli?: boolean;
+    /** Needs these first: 7-Zip to unpack an installer, Mesa for OpenGL without a GPU. */
+    needs?: ('7zip' | 'mesa')[];
+    /** Settings elsewhere that this entry stands for (VS Code, Windows Terminal): shown in the catalogue, not installed by it. */
+    setting?: string;
+    /** Only with full git access (it pushes on its own, past the sandbox's git guard). */
+    fullGitOnly?: boolean;
+}
+export declare const APPS: AppEntry[];
+export declare const appById: (id: string) => AppEntry | undefined;
+/** A catalogue `exe` that is a regex ("/.../") matches names with a version in them. */
+export declare const exeMatcher: (exe: string) => ((name: string) => boolean);
+/** The apps to install, in order: 7-Zip first when anything needs it to unpack. */
+export declare const appsToInstall: (apps: Config["apps"], gitAccess: GitAccess) => {
+    entries: AppEntry[];
+    skipped: string[];
+};
+/** Does any chosen app draw with OpenGL (so the Mesa step must run first)? */
+export declare const appsNeedMesa: (apps: Config["apps"] | undefined) => boolean;

package/dist/shared/apps.js

@@ -0,0 +1,114 @@
+export const APP_CATEGORIES = [
+    { id: 'editors', label: 'Editors & IDEs', description: 'Code and text editors (VS Code is a setting of its own and on by default).' },
+    { id: 'databases', label: 'Database clients', description: 'GUIs for the databases the sandbox runs (PostgreSQL, MySQL, MongoDB, Redis, SQLite, DynamoDB).' },
+    { id: 'api', label: 'API clients', description: 'Send HTTP, REST and GraphQL requests to what you are building.' },
+    { id: 'git', label: 'Git tools', description: 'Git GUIs and terminal UIs. They use the sandbox\'s git, so its git access rules apply.' },
+    { id: 'utilities', label: 'Utilities', description: 'Archives, comparing files, finding files, process tools, hex editing.' },
+    { id: 'browsers', label: 'Browsers', description: 'Browsers for testing web apps (Edge is already in Windows).' },
+    { id: 'gamedev', label: 'Game development', description: 'Engines and editors. They draw with OpenGL on the CPU (Mesa) when the sandbox has no GPU.' },
+    { id: 'cloud', label: 'Cloud & Kubernetes', description: 'Command-line tools for clouds, Kubernetes and infrastructure as code.' },
+    { id: 'diagrams', label: 'Diagrams & docs', description: 'Diagrams and document conversion.' },
+    { id: 'network', label: 'Network & HTTP', description: 'Inspect and test HTTP traffic and APIs.' },
+    { id: 'cli', label: 'Command-line tools', description: 'Small tools developers reach for: JSON and YAML, search, diff, builds, media, load testing ...' },
+];
+const gh = (github, asset) => ({ github, asset });
+export const APPS = [
+    // ---- editors
+    { id: 'vscode', name: 'Visual Studio Code', category: 'editors', about: 'Code editor with debugging, set up for the sandbox\'s languages.', size: '150 MB', source: { resolve: 'setting' }, exe: 'Code.exe', setting: 'toolchains.vscode.enabled' },
+    { id: 'windows-terminal', name: 'Windows Terminal', category: 'utilities', about: 'The sandbox window: tabs, panes, PowerShell 7 profile.', size: '40 MB', source: { resolve: 'setting' }, exe: 'WindowsTerminal.exe', setting: 'provisioning.terminal.enabled' },
+    { id: 'notepadpp', name: 'Notepad++', category: 'editors', about: 'Fast text and code editor.', size: '8 MB', source: gh('notepad-plus-plus/notepad-plus-plus', '^npp\\.[\\d.]+\\.portable\\.x64\\.zip$'), exe: 'notepad++.exe' },
+    { id: 'sublime', name: 'Sublime Text', category: 'editors', about: 'Fast code editor (paid licence, free to evaluate).', size: '28 MB', source: { resolve: 'sublime' }, exe: 'sublime_text.exe' },
+    { id: 'neovim', name: 'Neovim', category: 'editors', about: 'Terminal text editor (nvim).', size: '12 MB', source: gh('neovim/neovim', '^nvim-win64\\.zip$'), exe: 'nvim.exe', cli: true },
+    // ---- database clients
+    { id: 'dbeaver', name: 'DBeaver Community', category: 'databases', about: 'Universal database client: PostgreSQL, MySQL, SQLite, SQL Server and more.', size: '120 MB', source: gh('dbeaver/dbeaver', '^dbeaver-ce-[\\d.]+-windows-x86_64\\.zip$'), exe: 'dbeaver.exe' },
+    { id: 'pgadmin', name: 'pgAdmin 4', category: 'databases', about: 'The PostgreSQL admin GUI (from the PostgreSQL binaries zip).', size: '330 MB', source: { resolve: 'pgadmin' }, exe: 'pgAdmin4.exe' },
+    { id: 'heidisql', name: 'HeidiSQL', category: 'databases', about: 'Light client for MySQL, MariaDB, PostgreSQL and SQL Server.', size: '28 MB', source: gh('HeidiSQL/HeidiSQL', '^HeidiSQL_[\\d.]+_64_Portable\\.zip$'), exe: 'heidisql.exe' },
+    { id: 'sqlitebrowser', name: 'DB Browser for SQLite', category: 'databases', about: 'Open, browse and edit SQLite files.', size: '21 MB', source: gh('sqlitebrowser/sqlitebrowser', '^DB\\.Browser\\.for\\.SQLite-v?[\\d.]+-win64\\.zip$'), exe: 'DB Browser for SQLite.exe' },
+    { id: 'compass', name: 'MongoDB Compass', category: 'databases', about: 'The MongoDB GUI.', size: '220 MB', source: gh('mongodb-js/compass', '^mongodb-compass-[\\d.]+-win32-x64\\.zip$'), exe: 'MongoDBCompass.exe' },
+    { id: 'redisinsight', name: 'Redis Insight', category: 'databases', about: 'The Redis GUI.', size: '110 MB', source: gh('redis/RedisInsight', '^Redis-Insight-win-installer\\.exe$'), unpack: 'nsis', exe: 'Redis Insight.exe', needs: ['7zip'] },
+    { id: 'dbgate', name: 'DbGate', category: 'databases', about: 'Database manager for SQL and NoSQL databases.', size: '180 MB', source: gh('dbgate/dbgate', '^dbgate-[\\d.]+-win_x64\\.zip$'), exe: 'DbGate.exe' },
+    { id: 'beekeeper', name: 'Beekeeper Studio', category: 'databases', about: 'SQL editor and database manager.', size: '245 MB', source: gh('beekeeper-studio/beekeeper-studio', '^Beekeeper-Studio-[\\d.]+-portable\\.exe$'), unpack: 'nsis', exe: 'Beekeeper Studio.exe', needs: ['7zip'] },
+    { id: 'dynamodb-admin', name: 'dynamodb-admin', category: 'databases', about: 'Web GUI for DynamoDB Local: run dynamodb-admin, then open http://localhost:8001.', size: '5 MB', source: { npm: 'dynamodb-admin' }, exe: 'dynamodb-admin.cmd', cli: true },
+    // ---- API clients
+    { id: 'bruno', name: 'Bruno', category: 'api', about: 'Offline, git-friendly API client (collections are files in your repo).', size: '175 MB', source: gh('usebruno/bruno', '^bruno_[\\d.]+_x64_win\\.zip$'), exe: 'Bruno.exe' },
+    { id: 'insomnia', name: 'Insomnia', category: 'api', about: 'REST, GraphQL and gRPC client.', size: '590 MB', source: gh('Kong/insomnia', '^insomnia-[\\d.]+-full\\.nupkg$'), exe: 'Insomnia.exe' },
+    // ---- git
+    { id: 'sourcegit', name: 'SourceGit', category: 'git', about: 'Fast open-source Git GUI.', size: '26 MB', source: gh('sourcegit-scm/sourcegit', '^sourcegit_[\\d.]+\\.win-x64\\.zip$'), exe: 'SourceGit.exe' },
+    { id: 'githubdesktop', name: 'GitHub Desktop', category: 'git', about: 'Simple Git GUI from GitHub. It has its own git, so it needs provisioning.git.access "full".', size: '300 MB', source: gh('desktop/desktop', '^GitHubDesktop-[\\d.]+-x64-full\\.nupkg$'), exe: 'GitHubDesktop.exe', fullGitOnly: true },
+    { id: 'lazygit', name: 'lazygit', category: 'git', about: 'Git in the terminal.', size: '7 MB', source: gh('jesseduffield/lazygit', '^lazygit_[\\d.]+_windows_x86_64\\.zip$'), exe: 'lazygit.exe', cli: true },
+    // ---- utilities
+    { id: '7zip', name: '7-Zip', category: 'utilities', about: 'Archive manager (7z, zip, rar, tar ...). Also unpacks installers for other apps.', size: '2 MB', source: { resolve: '7zip' }, exe: '7zFM.exe' },
+    { id: 'winmerge', name: 'WinMerge', category: 'utilities', about: 'Compare and merge files and folders.', size: '23 MB', source: gh('WinMerge/winmerge', '^winmerge-[\\d.]+-x64-exe\\.zip$'), exe: 'WinMergeU.exe' },
+    { id: 'everything', name: 'Everything', category: 'utilities', about: 'Finds files by name instantly.', size: '2 MB', source: { resolve: 'everything' }, exe: 'Everything.exe' },
+    { id: 'sysinternals', name: 'Sysinternals Suite', category: 'utilities', about: 'Process Explorer, Process Monitor, Autoruns, TCPView and more (on PATH).', size: '200 MB', source: { url: 'https://download.sysinternals.com/files/SysinternalsSuite.zip' }, exe: 'procexp64.exe' },
+    { id: 'imhex', name: 'ImHex', category: 'utilities', about: 'Hex editor for reverse engineering and binary formats.', size: '80 MB', source: gh('WerWolv/ImHex', '^imhex-[\\d.]+-Windows-Portable-NoGPU-x86_64\\.zip$'), exe: 'imhex-gui.exe' },
+    // ---- browsers
+    { id: 'chrome', name: 'Chrome for Testing', category: 'browsers', about: 'Chrome build made for automated tests (with chromedriver on PATH).', size: '170 MB', source: { resolve: 'chrome' }, exe: 'chrome.exe' },
+    { id: 'firefox', name: 'Firefox', category: 'browsers', about: 'Firefox for testing.', size: '75 MB', source: { resolve: 'firefox' }, unpack: 'nsis', exe: 'firefox.exe', needs: ['7zip'] },
+    // ---- game development
+    { id: 'godot', name: 'Godot', category: 'gamedev', about: 'Open-source 2D and 3D game engine.', size: '80 MB', source: gh('godotengine/godot', '^Godot_v[\\d.]+-stable_win64\\.exe\\.zip$'), exe: '/^Godot_v[\\d.]+-stable_win64\\.exe$/', needs: ['mesa'] },
+    { id: 'blender', name: 'Blender', category: 'gamedev', about: '3D modelling, animation and rendering.', size: '400 MB', source: { resolve: 'blender' }, exe: 'blender.exe', needs: ['mesa'] },
+    { id: 'love', name: 'LÖVE', category: 'gamedev', about: 'Lua framework for 2D games.', size: '4 MB', source: gh('love2d/love', '^love-[\\d.]+-win64\\.zip$'), exe: 'love.exe', needs: ['mesa'] },
+    { id: 'defold', name: 'Defold', category: 'gamedev', about: 'Free 2D/3D game engine and editor.', size: '330 MB', source: gh('defold/defold', '^Defold-x86_64-win32\\.zip$'), exe: 'Defold.exe', needs: ['mesa'] },
+    { id: 'pixelorama', name: 'Pixelorama', category: 'gamedev', about: 'Pixel-art and sprite editor.', size: '40 MB', source: gh('Orama-Interactive/Pixelorama', '^Pixelorama-Windows-64bit\\.zip$'), exe: 'Pixelorama.exe', needs: ['mesa'] },
+    { id: 'tiled', name: 'Tiled', category: 'gamedev', about: 'Tile map editor.', size: '22 MB', source: gh('mapeditor/tiled', '^Tiled-[\\d.]+_Windows-10\\+_x86_64\\.msi$'), unpack: 'msi', exe: 'tiled.exe' },
+    // ---- cloud
+    { id: 'kubectl', name: 'kubectl', category: 'cloud', about: 'Kubernetes command line.', size: '60 MB', source: { resolve: 'kubectl' }, unpack: 'file', exe: 'kubectl.exe', cli: true },
+    { id: 'helm', name: 'Helm', category: 'cloud', about: 'Kubernetes package manager.', size: '20 MB', source: { resolve: 'helm' }, exe: 'helm.exe', cli: true },
+    { id: 'k9s', name: 'k9s', category: 'cloud', about: 'Kubernetes cluster UI in the terminal.', size: '40 MB', source: gh('derailed/k9s', '^k9s_Windows_amd64\\.zip$'), exe: 'k9s.exe', cli: true },
+    { id: 'terraform', name: 'Terraform', category: 'cloud', about: 'Infrastructure as code.', size: '30 MB', source: { resolve: 'terraform' }, exe: 'terraform.exe', cli: true },
+    { id: 'azure-cli', name: 'Azure CLI', category: 'cloud', about: 'Manage Azure (az).', size: '90 MB', source: { url: 'https://aka.ms/installazurecliwindowszipx64' }, exe: 'az.cmd', cli: true },
+    { id: 'gcloud', name: 'Google Cloud CLI', category: 'cloud', about: 'Manage Google Cloud (gcloud, gsutil, bq).', size: '120 MB', source: { url: 'https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-windows-x86_64-bundled-python.zip' }, exe: 'gcloud.cmd', cli: true },
+    { id: 'aws-cli', name: 'AWS CLI', category: 'cloud', about: 'Manage AWS (aws).', size: '50 MB', source: { url: 'https://awscli.amazonaws.com/AWSCLIV2.msi' }, unpack: 'msi', exe: 'aws.exe', cli: true },
+    // ---- diagrams and docs
+    { id: 'drawio', name: 'draw.io', category: 'diagrams', about: 'Diagram editor (flowcharts, architecture, UML).', size: '170 MB', source: gh('jgraph/drawio-desktop', '^draw\\.io-[\\d.]+-windows\\.zip$'), exe: 'draw.io.exe' },
+    { id: 'pandoc', name: 'Pandoc', category: 'diagrams', about: 'Convert documents between Markdown, HTML, Word, PDF ...', size: '35 MB', source: gh('jgm/pandoc', '^pandoc-[\\d.]+-windows-x86_64\\.zip$'), exe: 'pandoc.exe', cli: true },
+    // ---- network
+    { id: 'mitmproxy', name: 'mitmproxy', category: 'network', about: 'Intercepting HTTPS proxy (mitmweb opens a web UI).', size: '90 MB', source: { resolve: 'mitmproxy' }, exe: 'mitmweb.exe', cli: true },
+    { id: 'xh', name: 'xh', category: 'network', about: 'Friendly HTTP requests from the terminal (like HTTPie).', size: '5 MB', source: gh('ducaale/xh', '^xh-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'xh.exe', cli: true },
+    { id: 'grpcurl', name: 'grpcurl', category: 'network', about: 'curl for gRPC servers.', size: '10 MB', source: gh('fullstorydev/grpcurl', '^grpcurl_[\\d.]+_windows_x86_64\\.zip$'), exe: 'grpcurl.exe', cli: true },
+    { id: 'k6', name: 'k6', category: 'network', about: 'Load testing with JavaScript scripts.', size: '30 MB', source: gh('grafana/k6', '^k6-v[\\d.]+-windows-amd64\\.zip$'), exe: 'k6.exe', cli: true },
+    // ---- command-line tools
+    { id: 'jq', name: 'jq', category: 'cli', about: 'Query and reshape JSON.', size: '1 MB', source: gh('jqlang/jq', '^jq-windows-amd64\\.exe$'), unpack: 'file', exe: 'jq.exe', cli: true },
+    { id: 'yq', name: 'yq', category: 'cli', about: 'Query and edit YAML, JSON, XML and TOML.', size: '10 MB', source: gh('mikefarah/yq', '^yq_windows_amd64\\.exe$'), unpack: 'file', exe: 'yq.exe', cli: true },
+    { id: 'ripgrep', name: 'ripgrep', category: 'cli', about: 'Very fast recursive search (rg).', size: '2 MB', source: gh('BurntSushi/ripgrep', '^ripgrep-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'rg.exe', cli: true },
+    { id: 'fd', name: 'fd', category: 'cli', about: 'Fast, friendly alternative to find.', size: '2 MB', source: gh('sharkdp/fd', '^fd-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'fd.exe', cli: true },
+    { id: 'bat', name: 'bat', category: 'cli', about: 'cat with syntax highlighting and git changes.', size: '3 MB', source: gh('sharkdp/bat', '^bat-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'bat.exe', cli: true },
+    { id: 'fzf', name: 'fzf', category: 'cli', about: 'Fuzzy finder for the terminal.', size: '2 MB', source: gh('junegunn/fzf', '^fzf-[\\d.]+-windows_amd64\\.zip$'), exe: 'fzf.exe', cli: true },
+    { id: 'delta', name: 'delta', category: 'cli', about: 'Readable git diffs with syntax highlighting.', size: '3 MB', source: gh('dandavison/delta', '^delta-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'delta.exe', cli: true },
+    { id: 'just', name: 'just', category: 'cli', about: 'Command runner (a simpler make for project tasks).', size: '2 MB', source: gh('casey/just', '^just-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'just.exe', cli: true },
+    { id: 'hyperfine', name: 'hyperfine', category: 'cli', about: 'Benchmark commands.', size: '1 MB', source: gh('sharkdp/hyperfine', '^hyperfine-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'hyperfine.exe', cli: true },
+    { id: 'watchexec', name: 'watchexec', category: 'cli', about: 'Run a command when files change.', size: '5 MB', source: gh('watchexec/watchexec', '^watchexec-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'watchexec.exe', cli: true },
+    { id: 'protoc', name: 'protoc', category: 'cli', about: 'Protocol Buffers compiler.', size: '3 MB', source: gh('protocolbuffers/protobuf', '^protoc-[\\d.]+-win64\\.zip$'), exe: 'protoc.exe', cli: true },
+    { id: 'ninja', name: 'Ninja', category: 'cli', about: 'Small, fast build system (CMake\'s favourite generator).', size: '1 MB', source: gh('ninja-build/ninja', '^ninja-win\\.zip$'), exe: 'ninja.exe', cli: true },
+    { id: 'ffmpeg', name: 'FFmpeg', category: 'cli', about: 'Convert and process audio and video.', size: '200 MB', source: gh('BtbN/FFmpeg-Builds', '^ffmpeg-master-latest-win64-gpl\\.zip$'), exe: 'ffmpeg.exe', cli: true },
+    { id: 'sqlite', name: 'SQLite tools', category: 'cli', about: 'sqlite3 command-line shell.', size: '5 MB', source: { resolve: 'sqlite' }, exe: 'sqlite3.exe', cli: true },
+    { id: 'shellcheck', name: 'ShellCheck', category: 'cli', about: 'Finds bugs in shell scripts.', size: '10 MB', source: gh('koalaman/shellcheck', '^shellcheck-v[\\d.]+\\.zip$'), exe: 'shellcheck.exe', cli: true },
+    { id: 'gitleaks', name: 'Gitleaks', category: 'cli', about: 'Finds secrets committed to git.', size: '8 MB', source: gh('gitleaks/gitleaks', '^gitleaks_[\\d.]+_windows_x64\\.zip$'), exe: 'gitleaks.exe', cli: true },
+];
+export const appById = (id) => APPS.find((a) => a.id === id);
+/** A catalogue `exe` that is a regex ("/.../") matches names with a version in them. */
+export const exeMatcher = (exe) => {
+    const regex = /^\/(.+)\/$/.exec(exe);
+    if (regex) {
+        const r = new RegExp(regex[1], 'i');
+        return (name) => r.test(name);
+    }
+    return (name) => name.toLowerCase() === exe.toLowerCase();
+};
+/** Your own program as a catalogue entry (its folder is apps\custom\<id>). */
+const customEntry = (id, app) => ({
+    id: 'custom/' + id, name: app.name, category: 'utilities', about: 'Your own program.', size: '?',
+    source: app.github && app.asset ? { github: app.github, asset: app.asset } : { url: app.url },
+    unpack: app.unpack, exe: app.exe, cli: app.cli,
+});
+/** The apps to install, in order: 7-Zip first when anything needs it to unpack. */
+export const appsToInstall = (apps, gitAccess) => {
+    const chosen = apps.install.flatMap((id) => { const e = appById(id); return e && !e.setting ? [e] : []; });
+    const skipped = chosen.filter((e) => e.fullGitOnly && gitAccess !== 'full').map((e) => e.name + ' (needs provisioning.git.access "full")');
+    const allowed = [...chosen.filter((e) => !(e.fullGitOnly && gitAccess !== 'full')), ...Object.entries(apps.custom).map(([id, app]) => customEntry(id, app))];
+    const needs7zip = allowed.some((e) => e.needs?.includes('7zip') || e.unpack === 'nsis') && !allowed.some((e) => e.id === '7zip');
+    return { entries: [...(needs7zip ? [appById('7zip')] : []), ...allowed], skipped };
+};
+/** Does any chosen app draw with OpenGL (so the Mesa step must run first)? */
+export const appsNeedMesa = (apps) => Boolean(apps?.install.some((id) => appById(id)?.needs?.includes('mesa')));

package/dist/shared/console-input.d.ts

@@ -0,0 +1,11 @@
+export interface VtInput {
+    /** true once the console passes the terminal's input through (mouse reports included); false if it could not. */
+    ready: Promise<boolean>;
+    /** Stops a change still in progress; resolves when nothing can change the console mode any more. */
+    stop: () => Promise<void>;
+}
+/**
+ * Turns on ENABLE_VIRTUAL_TERMINAL_INPUT for this process's console. Call it after stdin.setRawMode(true) (which
+ * overwrites the mode); setRawMode(false) turns it off again. No-op off Windows or without a console.
+ */
+export declare const enableVtInput: () => VtInput;

package/dist/shared/console-input.js

@@ -0,0 +1,61 @@
+// Windows: lets the terminal's own input sequences (mouse clicks and wheel, focus) reach a Node process in raw mode.
+// Node reads the console as key records in raw mode and drops every mouse record, so an agent that turned mouse
+// tracking on (its terminal then sends the wheel and clicks as mouse reports) got neither. With
+// ENABLE_VIRTUAL_TERMINAL_INPUT the console hands over the terminal's input as it is: mouse reports, focus, keys.
+// Node has no API for the console mode, so a PowerShell child sets it on the console both share (the input mode
+// belongs to the console, not to a handle). Only built-ins here: view.js bundles this.
+import { spawn } from 'node:child_process';
+import { SYSTEM } from './system.js';
+/**
+ * PowerShell starts in a console of its own, hidden (so it never retitles your tab or touches its modes), then switches
+ * to ours. Started without any console, powershell.exe does nothing at all.
+ */
+const script = (pid) => [
+    'Add-Type -TypeDefinition @"',
+    'using System; using System.Runtime.InteropServices;',
+    'public static class SbxVtInput {',
+    '  [DllImport("kernel32.dll")] static extern bool FreeConsole();',
+    '  [DllImport("kernel32.dll")] static extern bool AttachConsole(uint pid);',
+    '  [DllImport("kernel32.dll", CharSet = CharSet.Unicode)] static extern IntPtr CreateFileW(string name, uint access, uint share, IntPtr security, uint creation, uint flags, IntPtr template);',
+    '  [DllImport("kernel32.dll")] static extern bool GetConsoleMode(IntPtr handle, out uint mode);',
+    '  [DllImport("kernel32.dll")] static extern bool SetConsoleMode(IntPtr handle, uint mode);',
+    '  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr handle);',
+    '  public static int On(uint pid) {',
+    '    FreeConsole();',
+    '    if (!AttachConsole(pid)) return 2;',
+    '    IntPtr input = CreateFileW("CONIN$", 0xC0000000, 3, IntPtr.Zero, 3, 0, IntPtr.Zero);',
+    '    if (input == new IntPtr(-1)) return 3;',
+    '    uint mode; bool ok = GetConsoleMode(input, out mode) && SetConsoleMode(input, mode | 0x200);',
+    '    CloseHandle(input);',
+    '    FreeConsole();',
+    '    return ok ? 0 : 4;',
+    '  }',
+    '}',
+    '"@',
+    'exit [SbxVtInput]::On(' + pid + ')',
+].join('\n');
+/**
+ * Turns on ENABLE_VIRTUAL_TERMINAL_INPUT for this process's console. Call it after stdin.setRawMode(true) (which
+ * overwrites the mode); setRawMode(false) turns it off again. No-op off Windows or without a console.
+ */
+export const enableVtInput = () => {
+    if (process.platform !== 'win32' || !process.stdin.isTTY)
+        return { ready: Promise.resolve(false), stop: () => Promise.resolve() };
+    let child = null;
+    let exited = Promise.resolve();
+    const ready = new Promise((resolve) => {
+        try {
+            child = spawn(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', Buffer.from(script(process.pid), 'utf16le').toString('base64')], { stdio: 'ignore', windowsHide: true });
+        }
+        catch {
+            resolve(false);
+            return;
+        }
+        exited = new Promise((done) => {
+            child?.on('exit', (code) => { resolve(code === 0); done(); });
+            child?.on('error', () => { resolve(false); done(); });
+        });
+    });
+    return { ready, stop: () => { if (child && child.exitCode === null && child.signalCode === null)
+            child.kill(); return exited; } };
+};

package/dist/shared/download.d.ts

@@ -17,6 +17,9 @@ export interface Checksums {
 }
 /** downloads.requireChecksum: from then on download() refuses anything it has no expected hash for. The guest sets it from session.json. */
 export declare const setChecksumRequired: (on: boolean) => void;
+/** Who wants coarse download progress: called as a download starts (in the caller's async context), returns its reporter. */
+export type DownloadWatcher = () => ((fraction: number) => void) | null;
+export declare const watchDownloads: (watcher: DownloadWatcher | null) => void;
 /**
  * Streams a download to disk, hashing as it goes: big archives (PostgreSQL is ~330 MB) never sit in memory, and the
  * event loop stays free so other toolchains keep downloading meanwhile. A mismatch (or any failure) leaves no file behind.

package/dist/shared/download.js

@@ -46,6 +46,8 @@ export const fetchText = async (url) => await (await fetchRetry(url)).text();
 let checksumRequired = false;
 /** downloads.requireChecksum: from then on download() refuses anything it has no expected hash for. The guest sets it from session.json. */
 export const setChecksumRequired = (on) => { checksumRequired = on; };
+let downloadWatcher = null;
+export const watchDownloads = (watcher) => { downloadWatcher = watcher; };
 /**
  * Streams a download to disk, hashing as it goes: big archives (PostgreSQL is ~330 MB) never sit in memory, and the
  * event loop stays free so other toolchains keep downloading meanwhile. A mismatch (or any failure) leaves no file behind.
@@ -64,8 +66,29 @@ export const download = async (url, destination, expected = null) => {
         const want = sums[kind]?.trim().toLowerCase();
         return want ? [{ want, hash: crypto.createHash(kind) }] : [];
     });
-    const tap = new Transform({ transform(chunk, _encoding, done) { for (const c of checks)
-            c.hash.update(chunk); done(null, chunk); } });
+    // Progress for the boot screen: every 10% or 5 s at most, never per chunk; called here so it knows who is downloading.
+    const size = Number(response.headers.get('content-length')) || 0;
+    const report = size > 0 ? downloadWatcher?.() ?? null : null;
+    let received = 0;
+    let tenth = 0;
+    let reportedAt = Date.now();
+    const tap = new Transform({ transform(chunk, _encoding, done) {
+            for (const c of checks)
+                c.hash.update(chunk);
+            if (report) {
+                received += chunk.length;
+                const now = Math.floor((received * 10) / size);
+                if (now !== tenth || Date.now() - reportedAt > 5000) {
+                    tenth = now;
+                    reportedAt = Date.now();
+                    try {
+                        report(Math.min(1, received / size));
+                    }
+                    catch { /* progress never breaks a download */ }
+                }
+            }
+            done(null, chunk);
+        } });
     // Written to <destination>.part and moved into place only once complete and verified, so an interrupted download never
     // leaves a partial file under the real name.
     const partial = destination + '.part';

package/dist/shared/guest-paths.d.ts

@@ -11,6 +11,33 @@ export declare const guestDrive: (guest: string) => string | null;
  * no '..' or empty segments, no characters Windows rejects in paths.
  */
 export declare const isValidGuestPath: (guest: string) => boolean;
+/** Where a mapping lands when the path it asks for (or the PC path) cannot be used inside the sandbox. */
+export declare const MAPPED_ROOT = "C:\\Mapped";
+/** A guest path as typed, tidied: '/' -> '\', no doubled or trailing backslashes, upper-case drive letter. */
+export declare const tidyGuestPath: (guest: string) => string;
+/** Why a guest path cannot be used as it is (null: it can). Short, plain English. */
+export declare const guestPathProblem: (guest: string) => string | null;
+/** C:\Mapped\<drive>\<rest of path>: a safe place for a folder whose own path cannot be used (odd characters made safe). */
+export declare const mappedFallback: (path: string) => string;
+/** Two guest folders overlap where they really are (F:\x is C:\Mirror\F\x): the same, or one inside the other. */
+export declare const guestOverlaps: (a: string, b: string) => boolean;
+/**
+ * Where an extra folder appears in the sandbox. `wanted` is the guest path asked for (or the one derived from the PC
+ * path); when the sandbox cannot use it (reserved, invalid, or overlapping a folder in `taken`), the folder goes to
+ * C:\Mapped\<drive>\<path> instead (made unique with -2, -3 ...), and `note` says where and why.
+ */
+export declare const placeGuest: (host: string, wanted: string, taken: {
+    guest: string;
+    what: string;
+}[]) => {
+    guest: string;
+    note: string | null;
+};
+/**
+ * The guest path a mapping asks for when it gives none: a folder inside the project at the same place in the project's
+ * guest folder, any other folder at the same path as on this PC (D: to Z: through C:\Mirror and subst).
+ */
+export declare const deriveGuest: (host: string, projectHost: string, projectGuest: string) => string;
 /** Where a guest path really is inside the sandbox (the .wsb SandboxFolder): C: paths as-is, F:\x -> C:\Mirror\F\x. */
 export declare const sandboxFolder: (guest: string) => string;
 export interface SubstDrive {