windows-development-sandbox 1.7.0 → 1.9.0

package/dist/selftest/menu-perf.test.js

@@ -0,0 +1,248 @@
+// The menu stays quick: no key or draw waits for a child process (tasklist is faked and counted), a slow tab load shows
+// "Loading…" instead of holding up the keys, a held key is drawn once, and the terminal writes only the rows that
+// changed (the screen after the diffs is the same as a full draw, also after a resize).
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { DEFAULTS } from '../core/config/index.js';
+import { sleep } from '../core/util/index.js';
+import { Menu } from '../cli/menu/menu.js';
+import { LiveStatus } from '../cli/menu/live.js';
+import { ListPage } from '../cli/menu/pages/list-page.js';
+import { App, Text, Terminal } from '../cli/tui/index.js';
+import { supportsSyncUpdate } from '../cli/tui/terminal.js';
+import { isSandboxRunning, useTasklistCache, useTasklistRunners } from '../host/sandbox/index.js';
+const TASKLIST = [
+    '"System Idle Process","0","Services","0","8 K"',
+    '"WindowsSandboxClient.exe","4242","Console","1","9,000 K"',
+].join('\r\n');
+const KEYS = { down: '\x1b[B', up: '\x1b[A', left: '\x1b[D', right: '\x1b[C', tab: '\t', ctrlC: '\x03' };
+/** A terminal the test can type into and read: the keys go in as bytes, everything written is kept. */
+class FakeTty {
+    stdin = Object.assign(new PassThrough(), { isTTY: true, setRawMode: () => undefined });
+    stdout = Object.assign(new EventEmitter(), {
+        columns: 100,
+        rows: 30,
+        write: (chunk) => {
+            this.writes.push(String(chunk));
+            return true;
+        },
+    });
+    writes = [];
+    terminal() {
+        return new Terminal(this.stdin, this.stdout);
+    }
+    type(bytes) {
+        this.stdin.write(bytes);
+    }
+}
+/** What the screen shows after a stream of writes: rows set by "ESC[r;1H", wiped by "ESC[H ESC[2J". */
+function replay(writes, height) {
+    const rows = Array.from({ length: height }, () => '');
+    for (const write of writes) {
+        const body = write.replace(/\x1b\[\?2026[hl]/g, '');
+        if (body.startsWith('\x1b[?1049h'))
+            continue;
+        for (const part of body.split(/(?=\x1b\[(?:\d+;1H|H))/)) {
+            const clear = /^\x1b\[H\x1b\[2J/.exec(part);
+            if (clear)
+                rows.fill('');
+            const at = /^\x1b\[(\d+);1H([\s\S]*?)\x1b\[0m/.exec(part.slice(clear ? clear[0].length : 0));
+            if (at)
+                rows[Number(at[1]) - 1] = at[2];
+        }
+    }
+    return rows;
+}
+function context(t) {
+    const root = t.dir('menu-perf');
+    return {
+        packageRoot: t.packageRoot,
+        entry: 'sandbox.js',
+        options: {},
+        loaded: {
+            config: structuredClone(DEFAULTS),
+            configPath: null,
+            base: root,
+            layers: { machine: null, user: null },
+        },
+        storageRoot: root,
+        dataPath: t.dir('menu-perf', 'data'),
+    };
+}
+export const menuPerfSuite = {
+    name: 'menu-perf',
+    title: 'menu speed: no child process on a key or a draw, diff rendering, slow loads',
+    run: async (t) => {
+        t.section('the terminal writes only what changed');
+        {
+            const tty = new FakeTty();
+            const term = tty.terminal();
+            const height = term.height;
+            const frame = (mark) => Array.from({ length: height }, (_, i) => 'row ' + i + (i === 7 ? mark : ''));
+            term.start();
+            tty.writes.length = 0;
+            term.render(frame('a'));
+            const first = tty.writes.join('');
+            term.render(frame('a'));
+            const unchanged = tty.writes.length;
+            term.render(frame('b'));
+            const diff = tty.writes.slice(1).join('');
+            t.check(unchanged === 1 && diff.includes('row 7b') && !diff.includes('row 6') && diff.length < first.length / 5, 'an identical frame writes nothing and a change writes only its rows, in one write', diff);
+            t.equal(replay(tty.writes, height).map((r) => r.trimEnd()), frame('b').map((r) => Text.fit(r, term.width - 1).trimEnd()), 'the screen after the diffs equals a full draw');
+            tty.stdout.rows = height + 5;
+            tty.stdout.emit('resize');
+            tty.writes.length = 0;
+            const bigger = Array.from({ length: height + 5 }, (_, i) => 'big ' + i);
+            term.render(bigger);
+            t.check(tty.writes.length === 1 && tty.writes[0].includes('\x1b[2J'), 'a resize repaints everything in one write');
+            t.equal(replay(tty.writes, height + 5).map((r) => r.trimEnd()), bigger.map((r) => Text.fit(r, term.width - 1).trimEnd()), 'the screen after a resize equals a full draw');
+            term.stop();
+            t.check(supportsSyncUpdate({ WT_SESSION: 'x' }) &&
+                !supportsSyncUpdate({}) &&
+                !supportsSyncUpdate({ WT_SESSION: 'x', AGENT_SANDBOX_SYNC_UPDATE: '0' }) &&
+                supportsSyncUpdate({ AGENT_SANDBOX_SYNC_UPDATE: '1' }), 'synchronized updates are used where the terminal is known to take them, and can be forced on or off');
+        }
+        t.section('a held key is drawn once');
+        {
+            const tty = new FakeTty();
+            const app = new App(tty.terminal());
+            let renders = 0;
+            let handled = 0;
+            const screen = {
+                render: (_size) => {
+                    renders++;
+                    return { path: [], body: ['x'], keys: [] };
+                },
+                handle: (key) => {
+                    handled++;
+                    return key.text === 'q' ? { done: 'bye' } : undefined;
+                },
+            };
+            // Thirty keys arrive together (a held arrow, a paste).
+            tty.type(KEYS.down.repeat(30) + 'q');
+            const result = await app.show(screen);
+            app.close();
+            t.check(result === 'bye' && handled === 31 && renders < 10, 'keys that are already waiting are handled first and drawn once, not once each', 'handled ' + handled + ', drawn ' + renders);
+        }
+        t.section('a slow load does not hold up the keys');
+        {
+            const tty = new FakeTty();
+            const app = new App(tty.terminal());
+            class Slow extends ListPage {
+                label = 'Slow';
+                rows = [];
+                async load() {
+                    await sleep(500);
+                    this.rows = ['alpha', 'beta'];
+                }
+                options() {
+                    return { path: [], items: this.rows.map((r) => ({ value: r, label: r })) };
+                }
+                act() {
+                    return Promise.resolve({});
+                }
+            }
+            const page = new Slow(app);
+            const started = Date.now();
+            await page.open();
+            const waited = Date.now() - started;
+            const text = () => Text.strip(page.render({ width: 80, height: 14 }).body.join('\n'));
+            t.check(waited < 400 && page.loading && text().includes('Loading'), 'the tab opens at once and says Loading… while the data comes', 'waited ' + waited + ' ms');
+            const arrived = await t.waitFor(() => (text().includes('beta') ? true : null), 5000, 20);
+            t.check(arrived === true && !page.loading, 'the list is built when the data arrives');
+        }
+        t.section('no child process on a key or a draw');
+        const saved = { hostOnly: process.env.AGENT_SANDBOX_HOST_ONLY };
+        process.env.AGENT_SANDBOX_HOST_ONLY = '1';
+        const calls = { sync: 0, async: 0 };
+        useTasklistRunners({
+            sync: () => {
+                calls.sync++;
+                return TASKLIST;
+            },
+            async: async () => {
+                calls.async++;
+                // A busy PC: every look at the process list takes a second and a half.
+                await sleep(1500);
+                return TASKLIST;
+            },
+        });
+        try {
+            const tty = new FakeTty();
+            const menu = new Menu(context(t), () => Promise.resolve(0), {
+                terminal: tty.terminal(),
+                fetchTasklist: async () => {
+                    calls.async++;
+                    await sleep(1500);
+                    return TASKLIST;
+                },
+                refreshMs: 100,
+            });
+            const done = menu.start();
+            const shown = await t.waitFor(() => tty.writes.length > 0, 20000, 20);
+            t.check(shown === true, 'the menu draws its first screen');
+            const slowest = { ms: 0, key: '' };
+            const press = async (name, bytes) => {
+                const before = tty.writes.length;
+                const at = Date.now();
+                tty.type(bytes);
+                // Not every key changes the screen: give the ones that do a chance, and measure those.
+                await t.waitFor(() => tty.writes.length > before, 400, 5);
+                const took = Date.now() - at;
+                if (tty.writes.length > before && took > slowest.ms) {
+                    slowest.ms = took;
+                    slowest.key = name;
+                }
+                await sleep(15);
+            };
+            const syncBefore = calls.sync;
+            for (const section of ['2', '3', '4', '5', '6', '7', '1'])
+                await press('section ' + section, section);
+            for (const k of ['down', 'down', 'up', 'left', 'down', 'down', 'right', 'down', 'down', 'tab'])
+                await press(k, KEYS[k]);
+            for (const section of ['5', '4', '2', '1'])
+                await press('section ' + section, section);
+            t.check(calls.sync === syncBefore, 'no key or draw ran tasklist (' + (calls.sync - syncBefore) + ' calls in 21 keys and every draw)', String(calls.sync - syncBefore));
+            t.check(calls.async >= 2, 'the process list is refreshed in the background (' + calls.async + ' times)');
+            t.check(slowest.ms < 1000, 'with a 1.5 second tasklist, no key took a second to show its result (slowest: ' +
+                slowest.key +
+                ' ' +
+                slowest.ms +
+                ' ms)');
+            tty.type(KEYS.ctrlC);
+            const code = await Promise.race([done, sleep(5000).then(() => -1)]);
+            t.check(code === 130, 'Ctrl+C leaves the menu');
+            const after = calls.sync;
+            isSandboxRunning();
+            t.check(calls.sync === after + 1, 'after the menu, "is the sandbox running?" runs tasklist again');
+        }
+        finally {
+            useTasklistRunners();
+            useTasklistCache(null);
+            if (saved.hostOnly === undefined)
+                delete process.env.AGENT_SANDBOX_HOST_ONLY;
+            else
+                process.env.AGENT_SANDBOX_HOST_ONLY = saved.hostOnly;
+        }
+        t.section('the status line');
+        {
+            let facts = 'a';
+            let changes = 0;
+            const live = new LiveStatus({
+                fetch: () => Promise.resolve(facts),
+                derive: () => 'status ' + facts,
+                onChange: () => changes++,
+                intervalMs: 20,
+            });
+            await live.start();
+            t.equal([live.line(), changes], ['status a', 1], 'the first look sets the line');
+            facts = 'b';
+            const changed = await t.waitFor(() => live.line() === 'status b', 3000, 10);
+            t.check(changed === true && changes === 2, 'a change is picked up in the background and announced');
+            live.stop();
+            facts = 'c';
+            await sleep(80);
+            t.check(live.line() === 'status b' && changes === 2, 'a stopped status looks at nothing');
+        }
+    },
+};

package/dist/selftest/menu-screens.js

@@ -3,7 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { Draft } from '../cli/menu/settings/draft.js';
-import { ConfigFile } from '../cli/menu/settings/config-file.js';
+import { ConfigFile } from '../app/features/settings/index.js';
 import { AppsModel } from '../cli/menu/apps.js';
 import { accountsOptions } from '../cli/menu/pages/accounts-page.js';
 import { appsOptions } from '../cli/menu/pages/apps-page.js';
@@ -11,7 +11,7 @@ import { maintenanceOptions } from '../cli/menu/pages/maintenance-page.js';
 import { sandboxOptions } from '../cli/menu/pages/sandbox-page.js';
 import { sessionsOptions } from '../cli/menu/pages/sessions-page.js';
 import { settingsOf, settingsOptions } from '../cli/menu/pages/settings-page.js';
-import { CATEGORIES } from '../cli/menu/settings/categories.js';
+import { CATEGORIES } from '../app/features/settings/index.js';
 import { agentsOptions } from '../cli/menu/pages/agents-page.js';
 import { SECTION_LABELS } from '../cli/menu/shell.js';
 import { Frame, ListScreen, OverlayScreen, Text } from '../cli/tui/index.js';
@@ -57,6 +57,7 @@ const SESSIONS = [
         projectName: 'api',
         here: true,
         viewers: { remote: 1, viewers: 1 },
+        canOpen: true,
     },
     {
         id: '1791927991436-cc22dd',
@@ -67,6 +68,7 @@ const SESSIONS = [
         projectName: 'web',
         here: false,
         viewers: { remote: 0, viewers: 0 },
+        canOpen: true,
     },
 ];
 /** The navigation the shell would show: every section, the open one with the categories of `options`. */

package/dist/selftest/menu.test.js

@@ -2,11 +2,13 @@
 // box, the Draft of unsaved changes, and the sections' lists. With MENU_SCREENS_OUT set it also writes every screen as
 // text there, for review.
 import fs from 'node:fs';
-import { ConfigFile } from '../cli/menu/settings/config-file.js';
+import { CATEGORIES, ConfigFile, SETTINGS_ELSEWHERE } from '../app/features/settings/index.js';
 import { Draft } from '../cli/menu/settings/draft.js';
 import { z } from 'zod';
 import { AddAgent, agentNameProblem, commandFromPackage, makeDefaultAgent, newAgent, removeAgent, } from '../cli/menu/add-agent.js';
-import { APP_GROUPS, AppsModel } from '../cli/menu/apps.js';
+import { APP_GROUPS, AppsModel, REQUEST_APP, requestAppUrl } from '../cli/menu/apps.js';
+import { readMenuView, saveMenuView } from '../cli/menu/memory.js';
+import path from 'node:path';
 import { argPathKind, optionLabel, optionPathKind, plainDescription } from '../cli/menu/command-fields.js';
 import { CommandForm } from '../cli/menu/command-form.js';
 import { COMMANDS, commandSpec } from '../cli/manifest.js';
@@ -15,12 +17,10 @@ import { addedAgents, agentActions, agentCategories, agentsOptions, hostAgentsTo
 import { ListPage } from '../cli/menu/pages/list-page.js';
 import { sandboxOptions } from '../cli/menu/pages/sandbox-page.js';
 import { sessionsOptions } from '../cli/menu/pages/sessions-page.js';
-import { pathKindOf } from '../cli/menu/settings/path-kind.js';
-import { SchemaNode } from '../cli/menu/settings/schema-node.js';
+import { pathKindOf, SchemaNode } from '../app/kernel/index.js';
 import { numberProblem, ValueEditor } from '../cli/menu/settings/value-editor.js';
 import { APP_CATEGORIES } from '../shared/apps/index.js';
 import { settingsOf, settingsOptions } from '../cli/menu/pages/settings-page.js';
-import { CATEGORIES, SETTINGS_ELSEWHERE } from '../cli/menu/settings/index.js';
 import { SECTION_LABELS, Shell } from '../cli/menu/shell.js';
 import { DEFAULTS } from '../core/config/index.js';
 import { HarnessSchema } from '../core/schema/index.js';
@@ -103,6 +103,7 @@ export const menuSuite = {
             stages = false;
             capturing = false;
             category;
+            search = '';
             focusList = true;
             constructor(label, ids) {
                 this.label = label;
@@ -116,6 +117,9 @@ export const menuSuite = {
                 this.category = id;
                 return Promise.resolve();
             }
+            restoreSearch(text) {
+                this.search = text;
+            }
             setFocus(list) {
                 this.focusList = list;
             }
@@ -153,8 +157,32 @@ export const menuSuite = {
         t.check(keys.includes('→ open') && keys.includes('1-7 jump'), 'the key bar shows the navigation keys while it has the keyboard', keys.join(', '));
         const leave = await shell.handle(press('escape'));
         t.check(leave !== undefined && leave.done.kind === 'quit', 'Esc in the navigation quits');
-        await shell.restore({ section: 2, category: 'd' });
-        t.equal([shell.page.label, pages[2].category, shell.view()], ['Three', 'd', { section: 2, category: 'd' }], 'the menu can be put back on the section and category it was left on');
+        await shell.restore({ section: 2, screens: { Three: { category: 'd', search: 'abc' }, One: { category: 'b' } } });
+        t.equal([shell.page.label, pages[2].category, pages[2].search, shell.view()], [
+            'Three',
+            'd',
+            'abc',
+            { section: 2, screens: { Three: { category: 'd', search: 'abc' }, One: { category: 'b' } } },
+        ], 'the menu can be put back on the section, category and search it was left on (other sections keep theirs)');
+        await shell.openTab(0);
+        t.equal([pages[0].category, pages[0].search], ['b', ''], 'a section opened later goes back to its own category');
+        t.section('menu memory file');
+        const labels = ['Agents', 'Sessions', 'Sandbox'];
+        const memDir = t.dir('menu-memory');
+        const view = { section: 2, screens: { Sessions: { category: 'x', search: 'foo' }, Gone: { category: 'y' } } };
+        saveMenuView(view, labels, memDir);
+        t.equal(readMenuView(labels, memDir), { section: 2, screens: { Sessions: { category: 'x', search: 'foo' } } }, 'the last section, category and search are saved and read back (a section that is gone is dropped)');
+        t.equal(readMenuView(['Agents', 'Sessions'], memDir)?.section, 0, 'a remembered section that no longer exists falls back to the first (Agents)');
+        fs.writeFileSync(path.join(memDir, 'menu-state.json'), '{"section": 5, "screens": "no"}');
+        t.equal(readMenuView(labels, memDir), undefined, 'an invalid state file is ignored');
+        fs.writeFileSync(path.join(memDir, 'menu-state.json'), 'not json');
+        t.equal(readMenuView(labels, memDir), undefined, 'a file that is not JSON is ignored');
+        t.section('request an app');
+        const issue = new URL(requestAppUrl());
+        t.check(issue.origin === 'https://github.com' &&
+            issue.pathname.endsWith('/issues/new') &&
+            (issue.searchParams.get('title') ?? '').startsWith('App request') &&
+            (issue.searchParams.get('body') ?? '').includes('App name'), 'the request-an-app address is a GitHub new-issue page with a title and a body template', requestAppUrl());
         t.section('list categories driven from outside');
         const catItems = (id, n) => Array.from({ length: n }, (_, i) => ({ value: id + i, label: id + ' item ' + i, category: id }));
         const catList = {
@@ -577,7 +605,7 @@ export const menuSuite = {
         t.section('apps in a few groups');
         const appsUser = new AppsModel(user2, t.dir('apps-groups'));
         const groupIds = appsUser.categories().map((c) => c.id);
-        const appItems = appsUser.items(new Draft());
+        const appItems = appsUser.items(new Draft()).filter((i) => i.value !== REQUEST_APP);
         t.check(groupIds.length <= 6 &&
             new AppsModel(ConfigFile.project(t.dir('apps-groups', 'project')), t.dir('apps-groups')).categories().length <=
                 5 &&

package/dist/selftest/support/engine-cases.d.ts

@@ -0,0 +1,8 @@
+import type { Config, ResolvedMapping } from '../../core/types.js';
+export interface EngineCase {
+    readonly name: string;
+    readonly config: Config;
+    readonly memoryMb: number;
+    readonly mappings: readonly ResolvedMapping[];
+}
+export declare const ENGINE_CASES: readonly EngineCase[];

package/dist/selftest/support/engine-cases.js

@@ -0,0 +1,65 @@
+import { DEFAULTS } from '../../core/config/index.js';
+const BASE = [
+    { host: 'C:\\L\\launches\\1', guest: 'C:\\AgentLaunch', readOnly: true },
+    { host: 'C:\\S\\data\\default', guest: 'C:\\AgentData', readOnly: false },
+    { host: 'C:\\Work\\app', guest: 'C:\\Workspace\\app', readOnly: false },
+];
+function withSandbox(change) {
+    const config = structuredClone(DEFAULTS);
+    Object.assign(config.sandbox, change);
+    return config;
+}
+export const ENGINE_CASES = [
+    { name: 'default', config: withSandbox({}), memoryMb: 8192, mappings: BASE },
+    { name: 'vGpu on', config: withSandbox({ vGpu: true }), memoryMb: 8192, mappings: BASE },
+    { name: 'networking off', config: withSandbox({ networking: false }), memoryMb: 4096, mappings: BASE },
+    {
+        name: 'several projects and roots',
+        config: withSandbox({}),
+        memoryMb: 16384,
+        mappings: [
+            ...BASE,
+            { host: 'C:\\Work\\one', guest: 'C:\\Projects\\Work\\one', readOnly: false },
+            { host: 'C:\\Work\\two', guest: 'C:\\Projects\\Work\\two', readOnly: false },
+            { host: 'D:\\Roots\\r', guest: 'C:\\Projects\\r', readOnly: false },
+        ],
+    },
+    {
+        name: 'read-only workspace and extra folders',
+        config: withSandbox({}),
+        memoryMb: 8192,
+        mappings: [
+            BASE[0],
+            BASE[1],
+            { host: 'C:\\Work\\app', guest: 'C:\\Workspace\\app', readOnly: true },
+            { host: 'C:\\Data', guest: 'C:\\Assets', readOnly: true, label: 'outside the project, allowed' },
+        ],
+    },
+    {
+        name: 'mirror paths on another drive and escaped characters',
+        config: withSandbox({}),
+        memoryMb: 6144,
+        mappings: [
+            ...BASE,
+            { host: 'F:\\Games\\a&b <x>', guest: 'F:\\SteamLibrary\\steamapps\\common\\Game', readOnly: true },
+        ],
+    },
+    {
+        name: 'memory 2048 and protectedClient off',
+        config: withSandbox({ protectedClient: false }),
+        memoryMb: 2048,
+        mappings: BASE,
+    },
+    {
+        name: 'every device on',
+        config: withSandbox({ vGpu: true, clipboard: true, audioInput: true, videoInput: true, printerRedirection: true }),
+        memoryMb: 12288,
+        mappings: BASE,
+    },
+    {
+        name: 'every device off',
+        config: withSandbox({ clipboard: false, networking: false, protectedClient: false }),
+        memoryMb: 8192,
+        mappings: [BASE[0], BASE[1]],
+    },
+];

package/dist/selftest/support/engine-golden.d.ts

@@ -0,0 +1,3 @@
+export declare const ENGINE_GOLDEN: Readonly<Record<string, string>>;
+/** The files of a default launch folder (the fixtures' default launch) before the engine layer existed. */
+export declare const LAUNCH_FILES_GOLDEN: readonly string[];

package/dist/selftest/support/engine-golden.js

@@ -0,0 +1,66 @@
+// The .wsb text written before the engine layer existed (captured from the old buildWsb); never regenerate it.
+export const ENGINE_GOLDEN = {
+    default: '<Configuration><MemoryInMB>8192</MemoryInMB><vGPU>Disable</vGPU><Networking>Enable</Networking><ClipboardRedirection>Enable</ClipboardRedirection><AudioInput>Disable</AudioInput><VideoInput>Disable</VideoInput><PrinterRedirection>Disable</PrinterRedirection><ProtectedClient>Enable</ProtectedClient><MappedFolders><MappedFolder><HostFolder>C:\\L\\launches\\1</HostFolder><SandboxFolder>C:\\AgentLaunch</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\S\\data\\default</HostFolder><SandboxFolder>C:\\AgentData</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Work\\app</HostFolder><SandboxFolder>C:\\Workspace\\app</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder></MappedFolders><LogonCommand><Command>C:\\AgentLaunch\\sandbox\\boot\\logon.cmd</Command></LogonCommand></Configuration>',
+    'vGpu on': '<Configuration><MemoryInMB>8192</MemoryInMB><vGPU>Enable</vGPU><Networking>Enable</Networking><ClipboardRedirection>Enable</ClipboardRedirection><AudioInput>Disable</AudioInput><VideoInput>Disable</VideoInput><PrinterRedirection>Disable</PrinterRedirection><ProtectedClient>Enable</ProtectedClient><MappedFolders><MappedFolder><HostFolder>C:\\L\\launches\\1</HostFolder><SandboxFolder>C:\\AgentLaunch</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\S\\data\\default</HostFolder><SandboxFolder>C:\\AgentData</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Work\\app</HostFolder><SandboxFolder>C:\\Workspace\\app</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder></MappedFolders><LogonCommand><Command>C:\\AgentLaunch\\sandbox\\boot\\logon.cmd</Command></LogonCommand></Configuration>',
+    'networking off': '<Configuration><MemoryInMB>4096</MemoryInMB><vGPU>Disable</vGPU><Networking>Disable</Networking><ClipboardRedirection>Enable</ClipboardRedirection><AudioInput>Disable</AudioInput><VideoInput>Disable</VideoInput><PrinterRedirection>Disable</PrinterRedirection><ProtectedClient>Enable</ProtectedClient><MappedFolders><MappedFolder><HostFolder>C:\\L\\launches\\1</HostFolder><SandboxFolder>C:\\AgentLaunch</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\S\\data\\default</HostFolder><SandboxFolder>C:\\AgentData</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Work\\app</HostFolder><SandboxFolder>C:\\Workspace\\app</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder></MappedFolders><LogonCommand><Command>C:\\AgentLaunch\\sandbox\\boot\\logon.cmd</Command></LogonCommand></Configuration>',
+    'several projects and roots': '<Configuration><MemoryInMB>16384</MemoryInMB><vGPU>Disable</vGPU><Networking>Enable</Networking><ClipboardRedirection>Enable</ClipboardRedirection><AudioInput>Disable</AudioInput><VideoInput>Disable</VideoInput><PrinterRedirection>Disable</PrinterRedirection><ProtectedClient>Enable</ProtectedClient><MappedFolders><MappedFolder><HostFolder>C:\\L\\launches\\1</HostFolder><SandboxFolder>C:\\AgentLaunch</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\S\\data\\default</HostFolder><SandboxFolder>C:\\AgentData</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Work\\app</HostFolder><SandboxFolder>C:\\Workspace\\app</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Work\\one</HostFolder><SandboxFolder>C:\\Projects\\Work\\one</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Work\\two</HostFolder><SandboxFolder>C:\\Projects\\Work\\two</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>D:\\Roots\\r</HostFolder><SandboxFolder>C:\\Projects\\r</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder></MappedFolders><LogonCommand><Command>C:\\AgentLaunch\\sandbox\\boot\\logon.cmd</Command></LogonCommand></Configuration>',
+    'read-only workspace and extra folders': '<Configuration><MemoryInMB>8192</MemoryInMB><vGPU>Disable</vGPU><Networking>Enable</Networking><ClipboardRedirection>Enable</ClipboardRedirection><AudioInput>Disable</AudioInput><VideoInput>Disable</VideoInput><PrinterRedirection>Disable</PrinterRedirection><ProtectedClient>Enable</ProtectedClient><MappedFolders><MappedFolder><HostFolder>C:\\L\\launches\\1</HostFolder><SandboxFolder>C:\\AgentLaunch</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\S\\data\\default</HostFolder><SandboxFolder>C:\\AgentData</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Work\\app</HostFolder><SandboxFolder>C:\\Workspace\\app</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Data</HostFolder><SandboxFolder>C:\\Assets</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder></MappedFolders><LogonCommand><Command>C:\\AgentLaunch\\sandbox\\boot\\logon.cmd</Command></LogonCommand></Configuration>',
+    'mirror paths on another drive and escaped characters': '<Configuration><MemoryInMB>6144</MemoryInMB><vGPU>Disable</vGPU><Networking>Enable</Networking><ClipboardRedirection>Enable</ClipboardRedirection><AudioInput>Disable</AudioInput><VideoInput>Disable</VideoInput><PrinterRedirection>Disable</PrinterRedirection><ProtectedClient>Enable</ProtectedClient><MappedFolders><MappedFolder><HostFolder>C:\\L\\launches\\1</HostFolder><SandboxFolder>C:\\AgentLaunch</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\S\\data\\default</HostFolder><SandboxFolder>C:\\AgentData</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Work\\app</HostFolder><SandboxFolder>C:\\Workspace\\app</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>F:\\Games\\a&amp;b &lt;x&gt;</HostFolder><SandboxFolder>C:\\Mirror\\F\\SteamLibrary\\steamapps\\common\\Game</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder></MappedFolders><LogonCommand><Command>C:\\AgentLaunch\\sandbox\\boot\\logon.cmd</Command></LogonCommand></Configuration>',
+    'memory 2048 and protectedClient off': '<Configuration><MemoryInMB>2048</MemoryInMB><vGPU>Disable</vGPU><Networking>Enable</Networking><ClipboardRedirection>Enable</ClipboardRedirection><AudioInput>Disable</AudioInput><VideoInput>Disable</VideoInput><PrinterRedirection>Disable</PrinterRedirection><ProtectedClient>Disable</ProtectedClient><MappedFolders><MappedFolder><HostFolder>C:\\L\\launches\\1</HostFolder><SandboxFolder>C:\\AgentLaunch</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\S\\data\\default</HostFolder><SandboxFolder>C:\\AgentData</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Work\\app</HostFolder><SandboxFolder>C:\\Workspace\\app</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder></MappedFolders><LogonCommand><Command>C:\\AgentLaunch\\sandbox\\boot\\logon.cmd</Command></LogonCommand></Configuration>',
+    'every device on': '<Configuration><MemoryInMB>12288</MemoryInMB><vGPU>Enable</vGPU><Networking>Enable</Networking><ClipboardRedirection>Enable</ClipboardRedirection><AudioInput>Enable</AudioInput><VideoInput>Enable</VideoInput><PrinterRedirection>Enable</PrinterRedirection><ProtectedClient>Enable</ProtectedClient><MappedFolders><MappedFolder><HostFolder>C:\\L\\launches\\1</HostFolder><SandboxFolder>C:\\AgentLaunch</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\S\\data\\default</HostFolder><SandboxFolder>C:\\AgentData</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\Work\\app</HostFolder><SandboxFolder>C:\\Workspace\\app</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder></MappedFolders><LogonCommand><Command>C:\\AgentLaunch\\sandbox\\boot\\logon.cmd</Command></LogonCommand></Configuration>',
+    'every device off': '<Configuration><MemoryInMB>8192</MemoryInMB><vGPU>Disable</vGPU><Networking>Disable</Networking><ClipboardRedirection>Disable</ClipboardRedirection><AudioInput>Disable</AudioInput><VideoInput>Disable</VideoInput><PrinterRedirection>Disable</PrinterRedirection><ProtectedClient>Disable</ProtectedClient><MappedFolders><MappedFolder><HostFolder>C:\\L\\launches\\1</HostFolder><SandboxFolder>C:\\AgentLaunch</SandboxFolder><ReadOnly>true</ReadOnly></MappedFolder><MappedFolder><HostFolder>C:\\S\\data\\default</HostFolder><SandboxFolder>C:\\AgentData</SandboxFolder><ReadOnly>false</ReadOnly></MappedFolder></MappedFolders><LogonCommand><Command>C:\\AgentLaunch\\sandbox\\boot\\logon.cmd</Command></LogonCommand></Configuration>',
+};
+/** The files of a default launch folder (the fixtures' default launch) before the engine layer existed. */
+export const LAUNCH_FILES_GOLDEN = [
+    'agent.wsb',
+    'claude-profile/.claude.json',
+    'claude-profile/CLAUDE.md',
+    'claude-profile/commands/review.md',
+    'claude-profile/plugins/installed_plugins.json',
+    'claude-profile/settings.json',
+    'env.cmd',
+    'home/.gitconfig',
+    'hooks/post-agent/README.txt',
+    'hooks/pre-provision/README.txt',
+    'package.json',
+    'runtime/agent.js',
+    'runtime/daemon.js',
+    'runtime/db.js',
+    'runtime/gitguard.js',
+    'runtime/main.js',
+    'runtime/netproxy.js',
+    'runtime/view.js',
+    'sandbox/boot/bootstrap.ps1',
+    'sandbox/boot/bootstrap/drives.ps1',
+    'sandbox/boot/bootstrap/files.ps1',
+    'sandbox/boot/bootstrap/runner.ps1',
+    'sandbox/boot/bootstrap/status.ps1',
+    'sandbox/boot/logon.cmd',
+    'sandbox/boot/trust.cmd',
+    'sandbox/csharp/CargoShim.cs',
+    'sandbox/csharp/Desktop.cs',
+    'sandbox/csharp/EnvBroadcast.cs',
+    'sandbox/csharp/GitShim.cs',
+    'sandbox/csharp/LinkGate.cs',
+    'sandbox/csharp/MemGov.cs',
+    'sandbox/csharp/OpenSsl.cs',
+    'sandbox/csharp/PathSync.cs',
+    'sandbox/csharp/PtyHost.cs',
+    'sandbox/csharp/SandboxTools/CpuCap.cs',
+    'sandbox/csharp/SandboxTools/MemoryLog.cs',
+    'sandbox/csharp/SandboxTools/PageFile.cs',
+    'sandbox/csharp/SandboxTools/Program.cs',
+    'sandbox/csharp/VsWhere.cs',
+    'sandbox/csharp/VtInput.cs',
+    'sandbox/scripts/enable-vt-input.ps1',
+    'sandbox/scripts/expand-archive.ps1',
+    'sandbox/scripts/get-gpu-names.ps1',
+    'sandbox/scripts/get-signer.ps1',
+    'sandbox/scripts/install-shell-path.ps1',
+    'sandbox/scripts/link-profile-dirs.ps1',
+    'sandbox/scripts/new-shortcuts.ps1',
+    'sandbox/scripts/set-desktop.ps1',
+    'sandbox/scripts/set-dns-servers.ps1',
+    'sandbox/scripts/set-machine-environment.ps1',
+    'session.json',
+];

package/dist/selftest/support/fixtures.d.ts

@@ -53,12 +53,15 @@ export declare function createFixtures(t: Harness): {
             optional?: boolean | undefined;
         }[];
         sandbox: {
+            engine: "windows-sandbox" | "hcs";
             memoryMb: number | "auto";
             maxMemoryMb: number;
             maxMemoryPercent: number;
             cpuLimit: number | "none";
             pageFileMb: number;
             reserveHostMb: number;
+            agentMemoryHeadroomMb: number | "auto" | "none";
+            pressureResponse: boolean;
             vGpu: boolean;
             networking: boolean;
             clipboard: boolean;
@@ -77,6 +80,8 @@ export declare function createFixtures(t: Harness): {
             persistAgentState: boolean;
             dataName: string;
             markSandboxFiles: boolean;
+            contained: "off" | "vhdx";
+            containedMaxGb: number;
             warnDataGb: number;
         };
         network: {
@@ -92,7 +97,7 @@ export declare function createFixtures(t: Harness): {
         };
         vpn: {
             enabled: boolean;
-            provider: "nordvpn" | "openvpn-file";
+            provider: "nordvpn" | "openvpn-file" | "wireguard-file";
             protocol: "udp" | "tcp";
             country: string;
             configFile: string;
@@ -308,6 +313,7 @@ export declare function createFixtures(t: Harness): {
                 hostDir?: string | undefined;
             } | undefined;
             localState?: Record<string, string> | undefined;
+            bootReset?: string[] | undefined;
             resumeArguments?: string[] | undefined;
             resumeOneArguments?: string[] | undefined;
         }>;

package/dist/selftest/support/hcs-probes.d.ts

@@ -0,0 +1,17 @@
+import type { HcsProbes, TokenGroups } from '../../host/engines/hcs/check.js';
+import type { HcsImage } from '../../host/engines/hcs/documents.js';
+export declare const FAKE_IMAGE: HcsImage;
+export interface FakePc {
+    windows: boolean;
+    build: number | null;
+    computecore: boolean;
+    services: Record<string, boolean | null>;
+    token: TokenGroups | null;
+    image: HcsImage | null;
+}
+export declare const GOOD_PC: FakePc;
+export declare function fakeProbes(pc?: Partial<FakePc>): HcsProbes & {
+    readonly calls: string[];
+};
+/** A PC without the HCS pieces, for the tests that must not depend on the PC they run on. */
+export declare const NO_HCS_PC: HcsProbes;

package/dist/selftest/support/hcs-probes.js

@@ -0,0 +1,41 @@
+export const FAKE_IMAGE = {
+    id: 'sha256:' + 'a'.repeat(64),
+    layers: ['C:\\img\\base', 'C:\\img\\l2'],
+    utilityVmFiles: 'C:\\img\\base\\UtilityVM\\Files',
+};
+export const GOOD_PC = {
+    windows: true,
+    build: 22621,
+    computecore: true,
+    services: { vmcompute: true, cexecsvc: true },
+    token: { elevatedAdministrator: true, hyperVAdministrators: false },
+    image: FAKE_IMAGE,
+};
+export function fakeProbes(pc = {}) {
+    const p = { ...GOOD_PC, ...pc };
+    const calls = [];
+    const store = {
+        name: 'fake store',
+        find: () => {
+            calls.push('imageStore.find');
+            return { image: p.image, reason: p.image ? '' : 'The fake store has no image.' };
+        },
+    };
+    return {
+        calls,
+        isWindows: () => p.windows,
+        windowsBuild: () => p.build,
+        serviceInstalled: (name) => {
+            calls.push('serviceInstalled:' + name);
+            return name in p.services ? p.services[name] : null;
+        },
+        fileExists: (file) => {
+            calls.push('fileExists:' + file);
+            return file.toLowerCase().endsWith('computecore.dll') ? p.computecore : false;
+        },
+        tokenGroups: () => p.token,
+        imageStores: () => [store],
+    };
+}
+/** A PC without the HCS pieces, for the tests that must not depend on the PC they run on. */
+export const NO_HCS_PC = fakeProbes({ computecore: false, services: { vmcompute: false, cexecsvc: false } });