windows-development-sandbox 1.4.0 → 1.4.1

package/dist/selftest/channel.test.js

@@ -1,8 +1,9 @@
 // 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 { GuestRequest, SandboxStatus, SessionStatus } from '../shared/schema.js';
+import { bootLine, firstStartNotice, pendingDownloads, readyIn, stillWorking } from '../cli/boot-progress.js';
+import { encodeFrame, FrameReader, FrameType, fixWindowsKeys, helloFrame, InputJoiner, MAX_FRAME_BYTES, MOUSE_OFF, OutputFilter } from '../shared/pty-client.js';
 export const channelSuite = {
     name: 'channel',
     title: 'request/status validation and the terminal protocol (frames, OSC 52, keys)',
@@ -19,6 +20,32 @@ export const channelSuite = {
         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) => SandboxStatus.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([
@@ -40,5 +67,14 @@ export const channelSuite = {
         const hello = new FrameReader().push(helloFrame('tok', 100, 30, 2))[0];
         t.equal({ type: hello.type, cols: hello.payload.readInt16LE(0), rows: hello.payload.readInt16LE(2), flags: hello.payload[4], token: hello.payload.subarray(5).toString() }, { type: FrameType.Hello, cols: 100, rows: 30, flags: 2, token: 'tok' }, 'a hello frame carries size, flags and token');
         t.equal(fixWindowsKeys(Buffer.from([0x61, 0x08, 0x7f, 0x1b])), Buffer.from([0x61, 0x7f, 0x08, 0x1b]), 'Windows console Backspace (^H) reaches the agent as DEL, so it deletes one character, not a word');
+        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/fixtures.d.ts

@@ -45,8 +45,8 @@ export declare const createFixtures: (t: Harness) => {
         };
         mappings: {
             host: string;
-            guest: string;
             readOnly: boolean;
+            guest?: string | undefined;
             optional?: boolean | undefined;
         }[];
         sandbox: {
@@ -291,6 +291,7 @@ export declare const createFixtures: (t: Harness) => {
             roots: string[];
             askToAddRoot: boolean;
             declinedRoots: string[];
+            allowOutsideMappings: boolean | "ask";
             wsbShare: boolean;
         };
         $schema?: string | undefined;

package/dist/selftest/index.js

@@ -42,6 +42,7 @@ import { toolchainsSuite } from './toolchains.test.js';
 import { workspaceSuite } from './workspace.test.js';
 import { workspaceViewSuite } from './workspace-view.test.js';
 import { liveNetworkSuite } from './live-network.test.js';
+import { liveTerminalSuite } from './live-terminal.test.js';
 import { auditSuite } from './audit.test.js';
 /** Every suite, in the order they run. The live ones come last: they are the slowest and need Windows. */
 export const SUITES = [
@@ -58,7 +59,7 @@ export const SUITES = [
     // every command as its own process
     hostSimSuite,
     // real processes
-    liveDaemonSuite, liveProjectsSuite, liveGitSuite, liveNetworkSuite,
+    liveDaemonSuite, liveProjectsSuite, liveGitSuite, liveNetworkSuite, liveTerminalSuite,
 ];
 /** Windows Sandbox (its user is always WDAGUtilityAccount) or a GitHub Actions runner: never someone's PC. */
 export const onThrowawayMachine = () => os.userInfo().username.toLowerCase() === 'wdagutilityaccount' || process.env.GITHUB_ACTIONS === 'true';

package/dist/selftest/live-terminal.test.d.ts

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

package/dist/selftest/live-terminal.test.js

@@ -0,0 +1,169 @@
+// Live: the terminal path as you use it. An outer ptyhost stands in for Windows Terminal (it hosts the console, like
+// Windows Terminal's own pseudo console) and runs the real viewer/attach client (runTerminalClient), which is attached
+// to an inner ptyhost running a stand-in agent. The agent turns SGR mouse tracking on and echoes every byte it reads.
+// Checks: clicks and the wheel reach the agent, Backspace stays Backspace, a split escape sequence arrives whole,
+// 500 printed lines scroll through as lines (no alternate screen, no scrollback clear), and a viewer that joins after
+// a screen clear still gets mouse tracking.
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { encodeFrame, FrameType } from '../shared/pty-client.js';
+import { CSC, openViewer, tail, WAIT } from './live.js';
+/** The stand-in agent: VT input and SGR mouse tracking on, echoes what it reads ("got <1b>[<0;10;5M"). L prints 500 lines, K clears the screen, q quits. */
+const AGENT_CS = String.raw `
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+static class MouseAgent
+{
+    [DllImport("kernel32.dll")] static extern IntPtr GetStdHandle(int n);
+    [DllImport("kernel32.dll")] static extern bool GetConsoleMode(IntPtr h, out uint m);
+    [DllImport("kernel32.dll")] static extern bool SetConsoleMode(IntPtr h, uint m);
+    [DllImport("kernel32.dll")] static extern bool ReadFile(IntPtr h, byte[] b, int n, out int read, IntPtr o);
+    static void Say(string s) { Console.Out.Write(s); Console.Out.Flush(); }
+    static int Main()
+    {
+        IntPtr input = GetStdHandle(-10), output = GetStdHandle(-11);
+        uint mode;
+        GetConsoleMode(output, out mode); SetConsoleMode(output, mode | 4);
+        SetConsoleMode(input, 0x200);
+        Say("\x1b[?1000h\x1b[?1006hAGENT-READY\r\n");
+        var buffer = new byte[512];
+        int n;
+        while (ReadFile(input, buffer, buffer.Length, out n, IntPtr.Zero) && n > 0)
+        {
+            var text = new StringBuilder();
+            for (int i = 0; i < n; i++) text.Append(buffer[i] < 32 || buffer[i] > 126 ? "<" + buffer[i].ToString("x2") + ">" : ((char)buffer[i]).ToString());
+            string got = text.ToString();
+            Say("got " + got + "\r\n");
+            if (got == "L") { var lines = new StringBuilder(); for (int i = 1; i <= 500; i++) lines.Append("line " + i + "\r\n"); Say(lines.ToString() + "LINES-DONE\r\n"); }
+            if (got == "K") Say("\x1b[2J\x1b[HCLEARED\r\n");
+            if (got == "q") break;
+        }
+        // Exits with mouse tracking still on (like a crash): the client must turn it off.
+        return 0;
+    }
+}
+`;
+const freePort = () => new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => { const port = server.address().port; server.close(() => resolve(port)); });
+});
+const compile = (source, exe) => {
+    const result = spawnSync(CSC, ['/nologo', '/optimize', '/target:exe', '/out:' + exe, source], { encoding: 'utf8', windowsHide: true });
+    return result.status === 0 ? '' : ((result.stdout ?? '') + (result.stderr ?? '')).trim().slice(0, 1500) || 'csc failed';
+};
+/** conpty.dll as a sandbox has it (C:\AgentData\tools\conpty), when this machine has one; else only Windows' own is tested. */
+const conptyDll = () => {
+    const dll = path.join(process.env.AGENT_DATA_DIR ?? 'C:\\AgentData', 'tools', 'conpty', 'conpty.dll');
+    return fs.existsSync(dll) && fs.existsSync(path.join(path.dirname(dll), 'OpenConsole.exe')) ? dll : null;
+};
+export const liveTerminalSuite = {
+    name: 'live-terminal',
+    title: 'live: the viewer/attach client in a terminal (mouse clicks and wheel, keys, scrolling lines, late viewers)',
+    live: true,
+    timeoutMs: 300000,
+    run: async (t) => {
+        const ptyhost = t.at('ptyhost.exe');
+        const agent = t.at('mouse-agent.exe');
+        fs.writeFileSync(t.at('mouse-agent.cs'), AGENT_CS);
+        const errors = compile(path.join(t.packageRoot, 'sandbox', 'ptyhost.cs'), ptyhost) || compile(t.at('mouse-agent.cs'), agent);
+        t.check(!errors, 'ptyhost and the stand-in agent compile', errors);
+        if (errors)
+            return;
+        const client = t.at('client.mjs');
+        fs.writeFileSync(client, [
+            'import { connect, runTerminalClient } from ' + JSON.stringify(pathToFileURL(path.join(t.packageRoot, 'dist', 'shared', 'pty-client.js')).href) + ';',
+            'const socket = await connect({ addresses: ["127.0.0.1"], port: Number(process.argv[2]), token: "tok" });',
+            'const result = await runTerminalClient(socket, "tok");',
+            'console.log("CLIENT-DONE " + result.reason);',
+        ].join('\n'));
+        const dll = conptyDll();
+        const kinds = dll ? [dll, null] : [null];
+        if (!dll)
+            t.skip('conpty.dll not found on this machine: only Windows\' own pseudo console is tested');
+        for (const kind of kinds) {
+            const label = kind ? 'conpty.dll' : 'Windows\' pseudo console';
+            t.section('live terminal (' + label + ')');
+            const children = [];
+            const viewers = [];
+            const start = (port, command, log) => {
+                const env = { ...process.env, PTYHOST_BIND: 'loopback' };
+                delete env.PTYHOST_CONPTY;
+                if (kind)
+                    env.PTYHOST_CONPTY = kind;
+                children.push(spawn(ptyhost, [String(port), 'tok', '100', '30', t.at(log), command], { env, stdio: 'ignore', windowsHide: true }));
+            };
+            try {
+                const innerPort = await freePort();
+                start(innerPort, '"' + agent + '"', 'inner-' + kinds.indexOf(kind) + '.log');
+                const outerPort = await freePort();
+                start(outerPort, '"' + process.execPath + '" "' + client + '" ' + innerPort, 'outer-' + kinds.indexOf(kind) + '.log');
+                // The terminal: what it shows is what the client wrote; what it types goes to the client's console.
+                const terminal = await openViewer({ addresses: ['127.0.0.1'], port: outerPort, token: 'tok' });
+                viewers.push(terminal);
+                const screen = () => terminal.output();
+                const send = (text) => { terminal.socket.write(encodeFrame(FrameType.Input, Buffer.from(text, 'latin1'))); };
+                const ready = await t.waitFor(() => screen().includes('AGENT-READY'), WAIT.screen);
+                t.check(Boolean(ready), 'the client shows the agent', 'screen: ' + tail(screen()));
+                if (!ready)
+                    continue;
+                // The client switches its console to pass the terminal's input through as it is; until then clicks are lost.
+                const click = '\x1b[<0;10;5M\x1b[<0;10;5m';
+                const clicked = await t.waitFor(() => { if (!screen().includes('got <1b>[<0;10;5M'))
+                    send(click); return screen().includes('got <1b>[<0;10;5M'); }, WAIT.screen, 1000);
+                t.check(Boolean(clicked), 'a mouse click in the terminal reaches the agent (SGR mouse report)', 'screen: ' + tail(screen(), 800));
+                const mark = screen().length;
+                const after = () => screen().slice(mark);
+                send('\x1b[<64;10;5M');
+                t.check(Boolean(await t.waitFor(() => after().includes('got <1b>[<64;10;5M'), WAIT.screen)), 'the mouse wheel reaches the agent while it tracks the mouse', 'screen: ' + tail(after(), 800));
+                send('\x7f');
+                t.check(Boolean(await t.waitFor(() => after().includes('got <7f>'), WAIT.screen)), 'Backspace reaches the agent as DEL (one character, not a word)', 'screen: ' + tail(after(), 800));
+                send('\x08');
+                t.check(Boolean(await t.waitFor(() => after().includes('got <08>'), WAIT.screen)), 'Ctrl+Backspace reaches the agent as ^H', 'screen: ' + tail(after(), 800));
+                send('\x1b[');
+                await new Promise((r) => setTimeout(r, 5));
+                send('C');
+                t.check(Boolean(await t.waitFor(() => after().includes('got <1b>[C'), WAIT.screen)), 'a Right arrow that reaches the client in two pieces arrives whole (no stray "C")', 'screen: ' + tail(after(), 800));
+                const before = screen().length;
+                send('L');
+                const done = await t.waitFor(() => screen().includes('LINES-DONE'), WAIT.screen);
+                const printed = screen().slice(before);
+                const seen = new Set([...printed.matchAll(/line (\d+)\b/g)].map((m) => Number(m[1])));
+                const missing = Array.from({ length: 500 }, (_, i) => i + 1).filter((n) => !seen.has(n)).map((n) => 'line ' + n);
+                t.check(Boolean(done) && missing.length === 0, 'all 500 printed lines reach the terminal as lines', 'missing: ' + missing.slice(0, 10).join(', ') + '\n' + tail(printed));
+                // (The client clears the tab once when it starts; from then on nothing may take the scrollback away.)
+                const session = screen().slice(screen().indexOf('AGENT-READY'));
+                for (const [sequence, what] of [['\x1b[?1049h', 'alternate screen'], ['\x1b[?47h', 'alternate screen (47)'], ['\x1b[?1047h', 'alternate screen (1047)'], ['\x1b[3J', 'clear scrollback']]) {
+                    t.excludes(session, sequence, 'the terminal is never sent ' + what + ' (' + JSON.stringify(sequence) + ')');
+                }
+                if (kind) {
+                    // A viewer that joins after the agent cleared its screen: the replay starts at the clear, the modes come first.
+                    send('K');
+                    await t.waitFor(() => screen().includes('CLEARED'), WAIT.screen);
+                    const late = await openViewer({ addresses: ['127.0.0.1'], port: innerPort, token: 'tok' });
+                    viewers.push(late);
+                    await t.waitFor(() => late.output().includes('CLEARED'), WAIT.screen);
+                    const head = late.output().slice(0, late.output().indexOf('CLEARED'));
+                    t.check(head.includes('\x1b[?1000h') && head.includes('\x1b[?1006h'), 'a viewer joining after a screen clear gets the agent\'s mouse tracking before the replay', 'late viewer: ' + JSON.stringify(late.output().slice(0, 300)));
+                    late.close();
+                }
+                send('q');
+                const ended = await t.waitFor(() => screen().includes('CLIENT-DONE'), WAIT.exit);
+                t.check(Boolean(ended), 'the client ends with the agent', 'screen: ' + tail(screen()));
+                if (kind)
+                    t.includes(screen().slice(screen().lastIndexOf('got q')), '\x1b[?1000l', 'leaving the session turns mouse tracking off in the terminal again');
+            }
+            finally {
+                for (const v of viewers)
+                    v.close();
+                for (const c of children)
+                    if (c.exitCode === null)
+                        c.kill();
+            }
+        }
+    },
+};

package/dist/selftest/local-config.test.js

@@ -50,14 +50,39 @@ export const localConfigSuite = {
         await rejectedBecause({ claudeProfile: { hostDir: 'C:\\x' } }, 'claudeProfile.hostDir is not allowed', 'a project file cannot point at the Claude profile folder');
         await rejectedBecause({ toolchains: { node: { hostDir: 'x' } } }, 'toolchains.node.hostDir is not allowed', 'a project file cannot point at host tool folders');
         await rejectedBecause({ sandbox: { memoryMb: 12 } }, 'sandbox.memoryMb:', 'values are type-checked (memory too small)');
-        await rejectedBecause({ mappings: [{ host: 'x', guest: 'C:\\Windows\\x', readOnly: true }] }, 'reserved or invalid guest path', 'reserved guest paths are rejected');
-        await rejectedBecause({ mappings: [{ host: '../shared', guest: 'C:\\Shared', readOnly: true }] }, 'only map folders inside the project', 'a project file cannot map folders outside the project');
-        await rejectedBecause({ mappings: [{ host: '%APPDATA%', guest: 'C:\\Startup', readOnly: false }] }, 'only map folders inside the project', '... not even through environment variables');
         await rejectedBecause({ provisioning: { git: { access: 'admin' } } }, 'provisioning.git.access:', 'unknown git access modes are rejected');
         await rejectedBecause('{\n  // a comment\n  "readOnly": tru\n}', 'line 3', 'broken JSON is reported with its line');
         await rejectedBecause({ _comment: 'old style' }, '_comment is not allowed', 'unknown keys are rejected');
         f.writeLocal(dirC, '// comments and trailing commas are fine\n{\n  "readOnly": true, /* inline */\n}\n');
         t.equal((await f.run({ cwd: dirC, trustConfig: true })).config.readOnly, true, '.sandbox-config.json may contain comments and trailing commas');
+        t.section('folders outside the project (projects.allowOutsideMappings)');
+        const dirD = t.dir('work-d');
+        const withOutside = (setting) => ({ ...f.baseConfig, projects: { ...f.baseConfig.projects, allowOutsideMappings: setting } });
+        const outsideFile = { mappings: [{ host: '../shared', readOnly: true }] };
+        f.writeLocal(dirD, outsideFile);
+        const notAllowed = await t.thrownMessage(() => f.run({ cwd: dirD, trustConfig: true }, withOutside(false)));
+        t.check(notAllowed.includes('outside the project') && notAllowed.includes(f.shared) && notAllowed.includes('projects.allowOutsideMappings'), 'false: refused, naming the folder and the setting that allows it', notAllowed);
+        const allowedOutside = await f.run({ cwd: dirD, trustConfig: true }, withOutside(true));
+        t.check(allowedOutside.config.mappings.some((m) => m.host === f.shared) && (allowedOutside.outsideMappings ?? []).includes(f.shared), 'true: allowed, and marked as outside the project');
+        f.writeLocal(dirD, { ...outsideFile, readOnly: true });
+        t.includes(await t.thrownMessage(() => f.run({ cwd: dirD }, withOutside(true))), '(outside the project)', 'true: still listed, flagged, when you approve the file');
+        const asking = await t.thrownMessage(() => f.run({ cwd: dirD, trustConfig: true, ask: async () => true, interactive: false }));
+        t.check(asking.includes('projects.allowOutsideMappings') && asking.includes('interactive'), '"ask" without a terminal (even with --trust-config): refused, naming the setting and that an interactive launch asks', asking);
+        t.includes(await t.thrownMessage(() => f.run({ cwd: dirD, trustConfig: true, ask: async () => false, interactive: true })), 'You did not allow', '"ask": answering no stops the launch');
+        const questions = [];
+        f.writeLocal(dirD, { ...outsideFile, sandbox: { vGpu: true } });
+        const asked = await f.run({ cwd: dirD, trustConfig: true, interactive: true, ask: async (q) => { questions.push(q); return true; } });
+        t.check(questions.length === 1 && asked.config.sandbox.vGpu && asked.config.mappings.some((m) => m.host === f.shared), '"ask": the folder and a looser setting (vGPU) are asked together, once', JSON.stringify(questions));
+        t.check((await f.run({ cwd: dirD, trustConfig: true, interactive: false })).config.mappings.some((m) => m.host === f.shared), '"ask": the answer is remembered for this project file');
+        // What counts as outside is where the folder really is: environment variables are expanded and links followed.
+        f.writeLocal(dirD, { mappings: [{ host: '%APPDATA%', readOnly: false }] });
+        t.includes(await t.thrownMessage(() => f.run({ cwd: dirD, trustConfig: true }, withOutside(false))), 'outside the project', '%VAR% is expanded before deciding inside or outside');
+        fs.symlinkSync(f.shared, path.join(dirD, 'link'), 'junction');
+        f.writeLocal(dirD, { mappings: [{ host: './link', readOnly: true }] });
+        t.includes(await t.thrownMessage(() => f.run({ cwd: dirD, trustConfig: true }, withOutside(false))), 'outside the project', 'a link inside the project to a folder outside counts as outside');
+        fs.rmSync(path.join(dirD, 'link'));
+        f.writeLocal(dirD, { mappings: [{ host: './assets', readOnly: true }] });
+        t.check((await f.run({ cwd: dirD, trustConfig: true }, withOutside(false))).config.mappings.some((m) => m.host === path.join(dirD, 'assets')), 'a folder inside the project needs no permission');
         t.section('a project can only tighten protections');
         // Settings that would loosen a protection are listed before approval, then ignored.
         f.writeLocal(dirC, {

package/dist/selftest/mirror.test.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { Config, Mapping } from '../core/schema.js';
 import { guestPathFor } from '../cli/commands/context.js';
 import { buildWsb } from '../host/launch/wsb.js';
-import { guestDrive, isValidGuestPath, planMirrorWorkspace, sandboxFolder, substDrives } from '../shared/guest-paths.js';
+import { deriveGuest, guestDrive, isValidGuestPath, planMirrorWorkspace, sandboxFolder, substDrives } from '../shared/guest-paths.js';
 import { guestWorkspaceAliases, projectFolderName } from '../shared/paths.js';
 import { syncHistoryIn, syncHistoryOut } from '../sync/history.js';
 export const mirrorSuite = {
@@ -17,8 +17,7 @@ export const mirrorSuite = {
         const invalid = ['C:\\', 'F:\\', 'F:', 'C:\\Windows\\x', 'C:\\Users\\me', 'c:\\program files\\x', 'C:\\AgentData\\x', 'C:\\Mirror', 'C:\\Mirror\\F\\x', 'A:\\x', 'B:\\x', 'C:\\a\\..\\Windows', 'F:\\a\\..\\b', 'F:\\a:b', 'F:\\a/b', 'F:\\a\\\\b', 'F:\\a.\\b', 'F:\\a|b', 'F:\\a\nb', '\\\\server\\share\\x', 'relative\\x', 'F:x'];
         t.equal(invalid.filter(isValidGuestPath), [], 'drive roots, reserved folders, C:\\Mirror, A:/B:, .., streams, odd characters and UNC paths are refused');
         const mappingAccepts = (guest) => Mapping.safeParse({ host: 'E:\\Games', guest, readOnly: true }).success;
-        t.check(mappingAccepts('F:\\SteamLibrary\\Game') && mappingAccepts('C:\\F'), 'schema: mappings[].guest may be on another drive letter');
-        t.check(!mappingAccepts('C:\\Mirror\\F\\x') && !mappingAccepts('F:\\'), 'schema: mappings[].guest may never be C:\\Mirror or a drive root');
+        t.check(mappingAccepts('F:\\SteamLibrary\\Game') && mappingAccepts('C:\\Windows\\x') && mappingAccepts(undefined), 'schema: any mappings[].guest is accepted, or none (the launch places it; it never fails the config)');
         const workspaceAccepts = (guestWorkspace) => Config.safeParse({ ...f.makeConfig(), guestWorkspace }).success;
         t.check(workspaceAccepts('mirror') && workspaceAccepts('F:\\AgentProjects\\x'), 'schema: guestWorkspace accepts "mirror" and D:-Z: paths');
         t.check(!workspaceAccepts('C:\\Users\\x'), 'schema: guestWorkspace refuses reserved paths');
@@ -64,10 +63,40 @@ export const mirrorSuite = {
         t.includes(text, '<SandboxFolder>C:\\Mirror\\G\\Projects\\work-a</SandboxFolder>', '.wsb: the workspace is under C:\\Mirror');
         t.includes(text, '<SandboxFolder>C:\\Mirror\\F\\SteamLibrary\\steamapps\\common\\Game</SandboxFolder>', '.wsb: the mapping is under C:\\Mirror');
         t.equal(f.readJson(f.generate(base).sessionPath).substDrives, [], 'no other drive letters: no subst drives');
-        const withMapping = (guest) => ({ ...run, config: { ...run.config, mappings: [{ host: game, guest, readOnly: true }] } });
-        await t.throws(() => f.generate(withMapping('C:\\Mirror\\F\\x')), 'not a usable sandbox folder', 'a mapping straight into C:\\Mirror is refused');
-        await t.throws(() => f.generate(withMapping('C:\\Windows\\x')), 'not a usable sandbox folder', 'a reserved guest folder is refused by the host too (not only the schema)');
-        await t.throws(() => f.generate(withMapping('g:\\projects\\work-a\\game')), 'overlapping', 'mappings overlapping on the same mirrored drive are refused');
+        t.section('where an extra folder goes: guest left out, or one the sandbox cannot use');
+        t.equal([
+            deriveGuest('F:\\P\\mw2\\data\\maps', 'F:\\P\\mw2', 'C:\\Workspace\\mw2'),
+            deriveGuest('C:\\Steam\\MOHAA', 'F:\\P\\mw2', 'C:\\Workspace\\mw2'),
+            deriveGuest('f:\\SteamLibrary\\steamapps\\common\\MW2\\', 'F:\\P\\mw2', 'C:\\Workspace\\mw2'),
+        ], ['C:\\Workspace\\mw2\\data\\maps', 'C:\\Steam\\MOHAA', 'F:\\SteamLibrary\\steamapps\\common\\MW2'], 'no guest: inside the project = the same place in it; outside = the same path as on the PC (C: as is, F: through C:\\Mirror\\F + subst)');
+        const other = t.dir('steam', 'Other');
+        const placed = (mappings) => {
+            const g = f.generate({ ...run, config: { ...run.config, mappings } });
+            return { guests: g.mappings.filter((m) => m.host === game || m.host === other).map((m) => m.guest), notes: g.mappingNotes, wsb: fs.readFileSync(g.wsbPath, 'utf8') };
+        };
+        const awkward = placed([
+            { host: game, guest: 'C:\\Windows\\foo', readOnly: true },
+            { host: game, guest: 'C:\\Users\\x', readOnly: true },
+            { host: game, guest: 'C:\\AgentData\\y', readOnly: true },
+            { host: game, guest: 'C:\\Mirror\\F\\x', readOnly: true },
+            { host: game, guest: 'D:\\Games', readOnly: true },
+            { host: game, guest: 'G:\\Projects\\work-a', readOnly: true },
+            { host: game, guest: 'c:/assets/', readOnly: true },
+            { host: other, guest: 'C:\\Assets', readOnly: true },
+            { host: game, guest: 'C:\\Assets', readOnly: true },
+        ]);
+        t.equal(awkward.guests, ['C:\\Mapped\\C\\Windows\\foo', 'C:\\Mapped\\C\\Users\\x', 'C:\\Mapped\\C\\AgentData\\y', 'C:\\Mapped\\C\\Mirror\\F\\x', 'D:\\Games', 'C:\\Mapped\\G\\Projects\\work-a', 'C:\\assets', 'C:\\Mapped\\C\\Assets'], 'reserved paths, C:\\Mirror and the workspace itself go to C:\\Mapped\\<drive>\\<path>; D:\\Games and a tidied c:/assets/ are used as they are; a repeat is mapped once; a second folder on the same path moves');
+        t.check(awkward.notes.some((n) => n.includes('C:\\Windows\\foo') && n.includes('keeps for itself') && n.includes('C:\\Mapped\\C\\Windows\\foo')), 'a note says where a reserved path went and why', awkward.notes.join('\n'));
+        t.check(awkward.notes.some((n) => n.startsWith(other) && n.includes('already used by') && n.includes(game)), 'a conflict note names both folders', awkward.notes.join('\n'));
+        t.check(!/<SandboxFolder>C:\\(Windows|Users|AgentData\\y|Mirror\\F\\x)/i.test(awkward.wsb), 'a reserved guest path never reaches the .wsb');
+        const derived = placed([{ host: game, readOnly: true }]);
+        t.check(derived.guests.length === 1 && (/^C:\\Mapped\\C\\Users\\/i.test(derived.guests[0]) || derived.guests[0].toLowerCase() === game.toLowerCase()), 'no guest, outside the project: the PC path, or C:\\Mapped\\... when that path is reserved (the temp folder is under C:\\Users)', JSON.stringify(derived));
+        const inside = t.dir('work-a', 'data');
+        const insideRun = await f.run();
+        const insideGen = f.generate({ ...insideRun, config: { ...insideRun.config, mappings: [{ host: inside, readOnly: true }] } });
+        t.check(!insideGen.mappings.some((m) => m.host === inside) && insideGen.mappingNotes.some((n) => n.includes('already in the sandbox at C:\\Workspace\\work-a\\data')), 'no guest, inside the project: already there, no second mapping', insideGen.mappingNotes.join('\n'));
+        const missingRequired = await t.thrownMessage(() => f.generate({ ...run, config: { ...run.config, mappings: [{ host: t.at('nope-1'), readOnly: true }, { host: t.at('nope-2'), guest: 'C:\\Windows', readOnly: true }] } }));
+        t.check(missingRequired.includes('2 mapped folders cannot be used') && missingRequired.includes('nope-1') && missingRequired.includes('nope-2') && missingRequired.includes('"optional": true'), 'folders that are not there: one message listing each, with the fix', missingRequired);
         t.section('exec, attach and history for a mirrored workspace');
         const workspace = 'F:\\AgentProjects\\mw2-agent';
         t.equal(guestPathFor(workspace + '\\crates\\engine', workspace, workspace), workspace + '\\crates\\engine', 'a host folder maps to the same guest folder');

package/dist/selftest/projects.test.js

@@ -4,15 +4,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { LocalOverrides } from '../core/schema.js';
-import { checkJoin, protectionsOf } from '../core/project-policy.js';
+import { checkJoin, describeMissing, missingAtBoot, missingTip, nothingMissing, protectionsOf } from '../core/project-policy.js';
+import { allowStorePath, saveAllowed } from '../core/local-config.js';
 import { sessionsFirstIn } from '../host/channel.js';
 import { buildWsb } from '../host/launch/wsb.js';
 import { projectSpec, joinRunning } from '../host/join.js';
-import { allProjectsToMap, forgetProject, NeedsRestart, projectHere, projectMapper, readKnown, readRegistry, rememberProject, startRegistry } from '../host/projects.js';
+import { allProjectsToMap, forgetProject, NeedsRestart, parseWsbBoot, projectHere, projectMapper, readKnown, readRegistry, rememberProject, startRegistry } from '../host/projects.js';
 import { checkRepo, saveRepoSnapshot } from '../host/repo-guard.js';
 import { findWsb, parseCommands, parseIp, parseList, parseVersion } from '../host/wsb.js';
 import { baseEnvFor } from '../guest/project-env.js';
-import { guestDirFor, hostDirFor, hubName, insideProjects, isBelow, isWithin, planProjectMappings, projectForGuestDir, projectForHostDir, PROJECTS_GUEST } from '../shared/projects.js';
+import { guestDirFor, hostDirFor, hubName, insideProjects, isBelow, isWithin, planProjectMappings, projectForGuestDir, projectForHostDir, PROJECTS_GUEST, rootGuestDir } from '../shared/projects.js';
 import { GuestRequest, ProjectSpec } from '../shared/schema.js';
 import { projectFolderName } from '../shared/paths.js';
 import { syncHistoryOut } from '../sync/history.js';
@@ -57,7 +58,11 @@ export const projectsSuite = {
         t.check(isBelow('C:\\a', 'C:\\a\\b') && !isBelow('C:\\a', 'C:\\a'), 'isBelow is strict');
         const plan = planProjectMappings(['F:\\Code', 'E:\\Work\\Code', 'C:\\Users\\me\\src'], ['D:\\x\\api', 'D:\\y\\api'], false);
         t.equal(plan.roots.map((r) => r.guest), ['C:\\Projects\\Code', 'C:\\Projects\\Code-2', 'C:\\Projects\\src'], 'roots get unique C:\\Projects\\<name> folders');
-        t.equal(plan.projects.map((p) => p.guest), ['C:\\Projects\\api', 'C:\\Projects\\api-2'], 'projects get unique C:\\Projects\\<name> folders');
+        t.equal(plan.projects.map((p) => p.guest), ['C:\\Workspace\\api', 'C:\\Workspace\\api-2'], 'projects mapped on their own get unique C:\\Workspace\\<name> folders (where they are as the launch folder)');
+        t.equal(planProjectMappings([], ['D:\\x\\app'], false, ['C:\\Workspace\\app']).projects[0].guest, 'C:\\Workspace\\app-2', 'a project mapped on its own never lands on the launch folder\'s place');
+        t.equal(planProjectMappings(['F:\\Code'], ['D:\\x\\api'], true).projects[0].guest, 'D:\\x\\api', 'with "mirror" a project mapped on its own appears at its PC path, as it would as the launch folder');
+        t.equal(rootGuestDir(['F:\\Code'], false, 'F:\\Code\\web\\src'), 'C:\\Projects\\Code\\web\\src', 'a folder inside a root is placed under the root\'s guest folder');
+        t.equal(rootGuestDir(['F:\\Code'], false, 'F:\\Other'), null, 'a folder in no root has no root place');
         const mirror = planProjectMappings(['F:\\Code', 'C:\\Users\\me\\src'], [], true);
         t.equal(mirror.roots.map((r) => r.guest), ['F:\\Code', 'C:\\Projects\\src'], 'with "mirror" a root appears at its PC path when the sandbox can show it there (C:\\Users\\... cannot)');
         t.section('projects: tighten-only protections when joining a running sandbox');
@@ -159,7 +164,23 @@ export const projectsSuite = {
         t.check(gen.projects.notes.some((n) => n.includes('no-such-root')), 'a missing root is skipped with a note', JSON.stringify(gen.projects.notes));
         t.check(gen.projects.projects.some((p) => p.host === outside), 'projects.all maps the known projects too');
         t.includes(wsb, '<HostFolder>' + root + '</HostFolder><SandboxFolder>C:\\Projects\\proj-root</SandboxFolder><ReadOnly>false</ReadOnly>', 'roots are mapped read/write in the .wsb');
-        t.equal({ projectsDir: session.projectsDir, roots: session.roots, projectId: session.projectId }, { projectsDir: PROJECTS_GUEST, roots: ['C:\\Projects\\proj-root'], projectId: 'work-a' }, 'session.json tells the guest where other projects can be');
+        t.equal({ projectsDir: session.projectsDir, roots: session.roots, projectId: session.projectId }, { projectsDir: PROJECTS_GUEST, roots: ['C:\\Projects\\proj-root', 'C:\\Workspace\\proj-outside'], projectId: 'work-a' }, 'session.json tells the guest where other projects can be');
+        // The same project is at the same place whether it started the sandbox or joined one another project started.
+        const fromRoot = f.generate(await f.run({ cwd: inRoot }, rootConfig));
+        const joinedAt = guestDirFor(gen.projects.roots[0], inRoot);
+        t.equal([f.readJson(fromRoot.sessionPath).workspace, joinedAt], ['C:\\Projects\\proj-root\\web', 'C:\\Projects\\proj-root\\web'], 'a project in a root: the same guest folder as the launch folder and when another project started the sandbox');
+        t.check(!fromRoot.mappings.some((m) => m.host.toLowerCase() === inRoot.toLowerCase()), 'a launch folder inside a root is shown by the root (no second mapping of it)');
+        t.includes(fs.readFileSync(path.join(fromRoot.launchPath, 'env.cmd'), 'utf8'), 'AGENT_WORKSPACE=C:\\Projects\\proj-root\\web', 'env.cmd: AGENT_WORKSPACE follows');
+        const asLaunch = f.readJson(f.generate(await f.run({ cwd: outside })).sessionPath).workspace;
+        t.equal([asLaunch, gen.projects.projects.find((p) => p.host === outside)?.guest], ['C:\\Workspace\\proj-outside', 'C:\\Workspace\\proj-outside'], 'a project outside the roots: the same guest folder as the launch folder and when mapped at boot by another');
+        const mirrorRoot = structuredClone(rootConfig);
+        mirrorRoot.guestWorkspace = 'mirror';
+        t.equal(f.readJson(f.generate(await f.run({ cwd: inRoot }, mirrorRoot)).sessionPath).workspace, rootGuestDir([root], true, inRoot), 'with "mirror" a launch folder inside a root is where the root shows it (no overlapping mappings)');
+        const filtered = structuredClone(rootConfig);
+        filtered.workspaceFilter = { ...filtered.workspaceFilter, enabled: true };
+        const filteredRun = await f.run({ cwd: inRoot }, filtered);
+        t.equal(filteredRun.config.guestWorkspace, 'C:\\Workspace\\web', 'workspaceFilter: a launch folder inside a root keeps its own (filtered) mapping');
+        t.check(filteredRun.notes.some((n) => n.includes('C:\\Projects\\proj-root\\web')), 'and a note says where it is when another project starts the sandbox', JSON.stringify(filteredRun.notes));
         const badRoot = structuredClone(f.baseConfig);
         badRoot.projects = { ...badRoot.projects, roots: [f.baseConfig.storage.root] };
         await t.throws(async () => f.generate(await f.run({}, badRoot)), 'projects.roots', 'a root that would expose the storage folder is refused');
@@ -233,9 +254,57 @@ export const projectsSuite = {
         const multiGen = generateSandbox({ packageRoot: t.packageRoot, run: await f.run(), harnessArgs: [], probe: f.probe, extraProjects: [f.workB, path.join(f.workA, 'sub'), f.workB], autoSession: false });
         const multiSession = f.readJson(multiGen.sessionPath);
         const multiWsb = fs.readFileSync(multiGen.wsbPath, 'utf8');
-        t.equal(multiGen.projects.projects.map((p) => p.guest), ['C:\\Projects\\work-b'], 'a multi-project launch maps every other project once (folders inside the launch folder and duplicates need nothing)');
-        t.includes(multiWsb, '<HostFolder>' + f.workB + '</HostFolder><SandboxFolder>C:\\Projects\\work-b</SandboxFolder>', 'a multi-project launch maps the other project in the .wsb');
+        t.equal(multiGen.projects.projects.map((p) => p.guest), ['C:\\Workspace\\work-b'], 'a multi-project launch maps every other project once (folders inside the launch folder and duplicates need nothing)');
+        t.includes(multiWsb, '<HostFolder>' + f.workB + '</HostFolder><SandboxFolder>C:\\Workspace\\work-b</SandboxFolder>', 'a multi-project launch maps the other project in the .wsb');
         t.equal({ autoSession: multiSession.autoSession, workspaceHost: multiSession.workspaceHost }, { autoSession: false, workspaceHost: f.workA }, 'the boot provisions the launch folder only; the host then opens every session (each project set up on demand, in parallel)');
+        t.section('projects: what a joining project wants at boot (vGPU, memory, its mappings)');
+        // A games project: its approved file asks for vGPU (you allowed it for this project) and maps a folder of its own.
+        const games = t.dir('proj-games');
+        t.dir('proj-games', 'assets');
+        f.writeLocal(games, { sandbox: { vGpu: true }, mappings: [{ host: 'assets', guest: 'F:\\GameAssets', readOnly: true }] });
+        saveAllowed(allowStorePath(f.baseConfig.storage.root), path.join(games, '.sandbox-config.json'), 'sandbox.vGpu', true, true);
+        const gamesRun = await f.run({ cwd: games, trustConfig: true });
+        t.equal(gamesRun.config.sandbox.vGpu, true, 'the vGPU you allowed for the project is in its effective config');
+        const launchedRun = await f.run();
+        const runningBoot = { memoryMb: 8192, mappings: [{ host: f.workA, guest: 'C:\\Workspace\\work-a', readOnly: false }] };
+        const wanted = missingAtBoot(protectionsOf(launchedRun.config), runningBoot, gamesRun.config, fs.existsSync);
+        t.equal({ settings: wanted.settings, memoryMb: wanted.memoryMb, mappings: wanted.mappings.map((m) => m.guest) }, { settings: ['sandbox.vGpu'], memoryMb: null, mappings: ['F:\\GameAssets'] }, 'missingAtBoot: vGPU and the project\'s folder are missing from a sandbox started without them (the missing optional mapping is no wish)');
+        const mappedMirror = missingAtBoot(protectionsOf(gamesRun.config), { memoryMb: 8192, mappings: [{ host: path.join(games, 'assets'), guest: 'C:\\Mirror\\F\\GameAssets', readOnly: true }] }, gamesRun.config, fs.existsSync);
+        t.check(nothingMissing(mappedMirror), 'missingAtBoot: nothing missing when the sandbox has vGPU and the folder (F:\\x is C:\\Mirror\\F\\x in the .wsb)', JSON.stringify(mappedMirror));
+        const bigger = structuredClone(launchedRun.config);
+        bigger.sandbox.memoryMb = 16384;
+        t.equal(missingAtBoot(protectionsOf(launchedRun.config), runningBoot, bigger).memoryMb, 16384, 'missingAtBoot: a larger fixed memory size is missing too');
+        const twoFolders = { settings: ['sandbox.vGpu'], memoryMb: null, mappings: [{ host: 'C:\\Steam\\common', guest: 'C:\\Steam', readOnly: true }, { host: 'F:\\SteamLibrary', guest: 'F:\\SteamLibrary', readOnly: true }] };
+        t.equal(describeMissing('mw2-agent', twoFolders), 'mw2-agent wants vGPU and 2 folders (C:\\Steam\\common, F:\\SteamLibrary), but this sandbox started without them.', 'the message names each missing item');
+        t.equal(missingTip(twoFolders), 'Set sandbox.vGpu (or the mappings) in your own settings to have them in every sandbox.', 'the tip names the settings');
+        t.equal(describeMissing('api', { settings: ['sandbox.vGpu'], memoryMb: null, mappings: [] }), 'api wants vGPU, but this sandbox started without it.', 'one item reads naturally');
+        t.equal(parseWsbBoot(buildWsb(f.baseConfig, 6144, [{ host: 'C:\\a&b', guest: 'F:\\x', readOnly: true }])), { memoryMb: 6144, mappings: [{ host: 'C:\\a&b', guest: 'C:\\Mirror\\F\\x', readOnly: true }], widened: {} }, 'a sandbox started by an older version: memory and mapped folders are read back from its .wsb');
+        const widenedJoin = checkJoin({ ...base, 'sandbox.vGpu': true }, base, ['sandbox.vGpu']);
+        t.equal({ stricter: widenedJoin.stricter, shared: widenedJoin.shared }, { stricter: [], shared: ['sandbox.vGpu'] }, 'vGPU turned on at boot for another project you allowed it for: a project without it shares it instead of being refused');
+        t.check(checkJoin({ ...base, 'sandbox.vGpu': true }, base).stricter.some((s) => s.startsWith('sandbox.vGpu')), '... without that record a project without vGPU is still refused (it needs it off)');
+        // joinRunning asks before anything is registered: restart (NeedsRestart with what is missing), or continue without.
+        const storage2 = t.dir('proj-storage2');
+        const data2 = t.dir('proj-storage2', 'data', 'testdata');
+        startRegistry(storage2, { launchId: '1700000000001-abcdef', protections: protectionsOf(launchedRun.config), primary: { host: f.workA, guest: 'C:\\Workspace\\work-a' }, roots: [{ host: path.dirname(games), guest: 'C:\\Projects\\temp' }], boot: [], atBoot: { ...runningBoot, widened: {} } });
+        const joinGames = (choice) => joinRunning({ storageRoot: storage2, dataPath: data2, packageRoot: f.install, hostDir: games, wsbShare: false, resolve: resolveFor(gamesRun), decide: async () => choice });
+        const restartFor = await joinGames('restart').then(() => null, (e) => e);
+        t.check(restartFor instanceof NeedsRestart && restartFor.missing?.settings.includes('sandbox.vGpu') === true && restartFor.missing.mappings.length === 1, 'choosing "Restart with them" hands the restart offer what is missing');
+        await t.throws(() => joinGames('cancel'), 'Cancelled', '"Cancel" stops with a short line');
+        t.check(!readRegistry(storage2)?.projects.some((p) => p.host === games), 'neither registers the project');
+        const continued = await joinGames('continue');
+        t.equal(continued.missing?.settings, ['sandbox.vGpu'], '"Continue anyway" joins without them and says what is missing');
+        // The restart that adds it (and any launch with it mapped at boot) boots with the union.
+        const unionGen = generateSandbox({ packageRoot: t.packageRoot, run: launchedRun, harnessArgs: [], probe: f.probe, extraProjects: [games], autoSession: false, bootWants: { projects: [{ name: 'proj-games', config: gamesRun.config }], keepOff: [] } });
+        const unionWsb = fs.readFileSync(unionGen.wsbPath, 'utf8');
+        t.includes(unionWsb, '<vGPU>Enable</vGPU>', 'the restart plan: vGPU on because the added project asks for it (and you allowed it)');
+        t.includes(unionWsb, '<HostFolder>' + path.join(games, 'assets') + '</HostFolder><SandboxFolder>C:\\Mirror\\F\\GameAssets</SandboxFolder><ReadOnly>true</ReadOnly>', 'the restart plan: the added project\'s mapping is mapped');
+        t.includes(unionWsb, '<HostFolder>' + games + '</HostFolder><SandboxFolder>C:\\Workspace\\proj-games</SandboxFolder>', 'the restart plan: the added project itself is mapped (where it is as the launch folder)');
+        t.equal(unionGen.widened, { 'sandbox.vGpu': 'proj-games' }, 'the registry learns which boot setting was turned on for which project');
+        t.check(unionGen.projects.notes.some((n) => n.startsWith('vGPU is on in this sandbox')), 'the launch says vGPU is on for every project and why', JSON.stringify(unionGen.projects.notes));
+        t.check(nothingMissing(missingAtBoot(protectionsOf(unionGen.bootConfig), { memoryMb: unionGen.memoryMb, mappings: unionGen.mappings }, gamesRun.config, fs.existsSync)), 'after that restart the project joins with nothing missing');
+        const keptOff = generateSandbox({ packageRoot: t.packageRoot, run: launchedRun, harnessArgs: [], probe: f.probe, extraProjects: [games], autoSession: false, bootWants: { projects: [{ name: 'proj-games', config: gamesRun.config }], keepOff: ['sandbox.vGpu'] } });
+        t.includes(fs.readFileSync(keptOff.wsbPath, 'utf8'), '<vGPU>Disable</vGPU>', 'a device the launch folder\'s own file switched off stays off');
+        t.includes(fs.readFileSync(f.generate(launchedRun).wsbPath, 'utf8'), '<vGPU>Disable</vGPU>', 'without other projects nothing changes');
         t.section('projects: wsb (Windows Sandbox command line) adapter');
         t.equal([parseVersion('Windows Sandbox CLI version 0.4.1.0\n'), parseVersion('nothing')], ['0.4.1.0', null], 'wsb --version');
         const help = 'Description:\n  Windows Sandbox command line\n\nUsage:\n  wsb [command] [options]\n\nOptions:\n  --version  Show version information\n\nCommands:\n  start    Starts a sandbox\n  list     Lists sandboxes\n  exec     Runs a command\n  share    Shares a folder\n  stop     Stops a sandbox\n  connect  Connects\n  ip       Shows the IP\n';

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; } };
+};