windows-development-sandbox 1.5.0 → 1.9.0

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: {
@@ -90,6 +95,14 @@ export declare function createFixtures(t: Harness): {
             dns: string[];
             proxy: string;
         };
+        vpn: {
+            enabled: boolean;
+            provider: "nordvpn" | "openvpn-file" | "wireguard-file";
+            protocol: "udp" | "tcp";
+            country: string;
+            configFile: string;
+            killSwitch: boolean;
+        };
         provisioning: {
             copyFromHost: boolean;
             fallbackToInstall: boolean;
@@ -241,6 +254,10 @@ export declare function createFixtures(t: Harness): {
             auto: boolean;
             autoHide: boolean;
         };
+        web: {
+            enabled: boolean;
+            port: number;
+        };
         agentCommands: {
             enabled: boolean;
             agents: string[] | "auto";
@@ -274,6 +291,7 @@ export declare function createFixtures(t: Harness): {
             globalStateFile: string;
             copyCredentials: boolean;
             overwrite: boolean;
+            sharePluginsAcrossAccounts: boolean;
             syncHistory: boolean;
             historyScope: "project" | "all";
             syncClaudeMem: boolean;
@@ -294,6 +312,8 @@ export declare function createFixtures(t: Harness): {
                 profileDirs?: string[] | undefined;
                 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 } });

package/dist/selftest/support/releases.js

@@ -64,7 +64,7 @@ export async function installFirst(t, root, scope = 'user', autoUpdate = false)
 /** What a user gets by running the command: the shim, through cmd.exe. */
 export function runShim(layout) {
     const shim = path.join(layout.binDir, 'sandbox.cmd');
-    const run = spawnSync(SYSTEM.cmd(), ['/d', '/s', '/c', '""' + shim + '" --version"'], {
+    const run = spawnSync(SYSTEM.cmd(), ['/d', '/s', '/c', '""' + shim + '" --version --short"'], {
         encoding: 'utf8',
         windowsVerbatimArguments: true,
         windowsHide: true,

package/dist/selftest/toolchains.test.js

@@ -207,6 +207,27 @@ export const toolchainsSuite = {
             chosen.skipped.length === 1 &&
             appsNeedMesa({ install: ['godot'], custom: {} }) &&
             !appsNeedMesa({ install: ['jq'], custom: {} }), 'apps: 7-Zip first when an installer needs it; an app with its own git is skipped unless git access is "full"; engines bring Mesa');
+        // The release files the entries were written against (GitHub, 2026-10): the x64 build matches, the others do not.
+        const pick = (id, files) => {
+            const source = APPS.find((x) => x.id === id)?.source;
+            const re = new RegExp(source && 'github' in source ? source.asset : '$^');
+            return files.filter((f) => re.test(f));
+        };
+        t.equal([
+            pick('ast-grep', [
+                'app-aarch64-pc-windows-msvc.zip',
+                'app-i686-pc-windows-msvc.zip',
+                'app-x86_64-pc-windows-msvc.zip',
+            ]),
+            pick('jj', ['jj-v0.46.0-aarch64-pc-windows-msvc.zip', 'jj-v0.46.0-x86_64-pc-windows-msvc.zip']),
+            pick('rust-analyzer', ['rust-analyzer-i686-pc-windows-msvc.zip', 'rust-analyzer-x86_64-pc-windows-msvc.zip']),
+        ], [
+            ['app-x86_64-pc-windows-msvc.zip'],
+            ['jj-v0.46.0-x86_64-pc-windows-msvc.zip'],
+            ['rust-analyzer-x86_64-pc-windows-msvc.zip'],
+        ], 'apps: ast-grep, Jujutsu and rust-analyzer pick the x64 Windows release file');
+        t.check(appsToInstall({ install: ['jj', 'ast-grep', 'rust-analyzer'], custom: {} }, 'readonly').skipped.length === 1 &&
+            appsToInstall({ install: ['jj'], custom: {} }, 'full').entries.some((e) => e.id === 'jj'), 'apps: Jujutsu brings its own git, so it needs git access "full"; the other two do not');
         const custom = (app) => ConfigSchema.shape.apps.shape.custom.safeParse({ x: app }).success;
         t.check(custom({ name: 'A', github: 'o/r', asset: 'win.*\\.zip$', exe: 'a.exe' }) &&
             custom({ name: 'B', url: 'https://x.org/b.zip', exe: 'b.exe' }) &&

package/dist/selftest/update-service.test.js

@@ -7,11 +7,11 @@ import { spawnSync } from 'node:child_process';
 import { parseCli } from '../cli/args.js';
 import { describeResult, runUpdate } from '../cli/commands/maintenance/update.js';
 import { UpdateService, runsAsSystem } from '../cli/services/index.js';
-import { InstallLayout, InstallRecordFile, UpdateTask } from '../host/install/index.js';
+import { InstallLayout, InstallRecordFile, UpdateTask, shimText } from '../host/install/index.js';
 import { nativeScript } from '../host/native.js';
 import { FolderFeed, UpdateLock, updateNotice } from '../host/update/index.js';
 import { SYSTEM } from '../shared/system.js';
-import { installFirst, publish, runShim } from './support/releases.js';
+import { NODE, installFirst, publish, runShim } from './support/releases.js';
 /** A scheduled task that only remembers what it was asked. */
 class FakeTask {
     calls = [];
@@ -97,6 +97,89 @@ async function service(t) {
     t.equal([dueOff, savedOn, dueSoon, due, svc.autoUpdateDue()], [false, true, false, true, false], 'never due while off; the setting is in install.json; not due a moment after a look, due after a day, never while a sandbox runs');
     sandbox = false;
 }
+/** A failed install puts the old version back (pointers, shims), turns automatic updates off and says so once. */
+async function failedInstall(t) {
+    t.section('update service: a failed install is undone');
+    const root = t.dir('fail', 'install');
+    const feed = t.at('fail', 'feed');
+    const layout = await installFirst(t, root, 'machine', true);
+    const task = new FakeTask();
+    const clock = { at: new Date('2026-10-14T12:00:00Z') };
+    const svc = new UpdateService(layout, {
+        source: new FolderFeed(feed),
+        sandboxRunning: () => false,
+        task,
+        version: '1.0.0',
+        userDir: t.dir('fail', 'user'),
+        now: () => clock.at,
+    });
+    const record = new InstallRecordFile(root);
+    publish(t, feed, '1.0.1', 'good');
+    fs.rmSync(path.join(feed, 'windows-development-sandbox-1.0.1.tgz'));
+    const offline = await svc.run();
+    t.check(offline?.kind === 'failed' &&
+        !offline.blocked &&
+        !offline.autoUpdateOff &&
+        offline.rolledBack &&
+        record.read()?.autoUpdate === true &&
+        task.calls.length === 0 &&
+        svc.status().autoOffText === null &&
+        svc.notice() === null, 'a download that never arrived (the network) changes nothing and leaves automatic updates on');
+    const goodShim = fs.readFileSync(path.join(layout.binDir, 'sandbox.cmd'), 'utf8');
+    t.check(goodShim === shimText('sandbox', 'cmd'), 'the shim text is the standard one before the failed update');
+    fs.writeFileSync(path.join(layout.binDir, 'sandbox.cmd'), '@echo off\r\nrem marker\r\n');
+    publish(t, feed, '1.0.2', 'broken');
+    clock.at = new Date(clock.at.getTime() + 3600_000);
+    const bad = await svc.run();
+    t.check(bad?.kind === 'failed' &&
+        bad.blocked &&
+        bad.rolledBack &&
+        bad.autoUpdateOff &&
+        layout.activeVersion() === '1.0.0' &&
+        layout.activeNode() === NODE &&
+        fs.readFileSync(path.join(layout.binDir, 'sandbox.cmd'), 'utf8') === goodShim &&
+        runShim(layout) === '1.0.0' &&
+        !layout.installedVersions().includes('1.0.2'), 'a release that does not start is undone: pointers, shims and the version folder are as before');
+    t.check(record.read()?.autoUpdate === false &&
+        task.calls.join() === 'remove' &&
+        svc.status().autoUpdate === false &&
+        svc.status().state.autoOff?.version === '1.0.2', 'automatic updates are off in install.json, the scheduled task is removed, the reason is recorded');
+    const told = svc.notice();
+    if (told)
+        svc.markNoticeSeen(told);
+    t.check(told?.text ===
+        'The update to 1.0.2 failed and was undone (you are on 1.0.0). Automatic updates are off; turn them back on in Maintenance > Updates or with sandbox update --auto on.' &&
+        svc.notice() === null &&
+        svc.status().autoOffText === told.text, 'the user is told once, in plain words; the status carries the same sentence for the menu', told?.text);
+    svc.setAuto(true);
+    t.check(svc.status().autoOffText === null && record.read()?.autoUpdate === true, 'turning updates back on clears the remark');
+    // The same failure when the task cannot be removed (no admin): not an error; install.json is what the task reads.
+    const root2 = t.dir('fail2', 'install');
+    const feed2 = t.at('fail2', 'feed');
+    const layout2 = await installFirst(t, root2, 'machine', true);
+    const task2 = new FakeTask();
+    task2.fail = true;
+    publish(t, feed2, '1.0.1', 'broken');
+    const svc2 = new UpdateService(layout2, {
+        source: new FolderFeed(feed2),
+        sandboxRunning: () => false,
+        task: task2,
+        version: '1.0.0',
+    });
+    const bad2 = await svc2.run();
+    t.check(bad2?.kind === 'failed' &&
+        bad2.autoUpdateOff &&
+        new InstallRecordFile(root2).read()?.autoUpdate === false &&
+        (await runUpdate(svc2, { check: false, rollback: false, unattended: true }, () => undefined)) === 0 &&
+        layout2.activeVersion() === '1.0.0', 'a task that cannot be removed does not stop the rollback; an unattended run with updates off does nothing');
+    publish(t, feed2, '1.0.2', 'good');
+    const ok2 = await svc2.run();
+    fs.writeFileSync(path.join(layout2.binDir, 'sandbox.cmd'), '@echo off\r\nrem marker\r\n');
+    const back = ok2?.kind === 'installed' ? svc2.rollback() : null;
+    t.check(back === '1.0.0' &&
+        fs.readFileSync(path.join(layout2.binDir, 'sandbox.cmd'), 'utf8') === goodShim &&
+        runShim(layout2) === '1.0.0', 'sandbox update --rollback writes the shims of the version it returns to');
+}
 function pure(t) {
     t.section('update notice and options');
     const state = { lastResult: { version: '1.5.0', ok: true, at: '2026-10-14T03:00:00Z' } };
@@ -154,7 +237,7 @@ async function command(t) {
         describeResult(waiting, false).code === 1 &&
         describeResult(waiting, true).code === 0 &&
         describeResult({ kind: 'installed', version: '1.0.1', previous: '1.0.0' }, false).line.includes('from 1.0.0 to 1.0.1') &&
-        describeResult({ kind: 'failed', version: '1.0.1', reason: 'x', blocked: true }, false).code === 1, 'exit codes: a running sandbox fails by hand but just waits unattended; a failed update exits 1');
+        describeResult({ kind: 'failed', version: '1.0.1', reason: 'x', blocked: true, rolledBack: true, autoUpdateOff: true }, false).code === 1, 'exit codes: a running sandbox fails by hand but just waits unattended; a failed update exits 1');
 }
 function script(t) {
     t.section('set-update-task.ps1');
@@ -181,6 +264,7 @@ export const updateServiceSuite = {
     title: 'sandbox update, automatic updates, the update notice',
     run: async (t) => {
         await service(t);
+        await failedInstall(t);
         pure(t);
         await command(t);
         script(t);

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

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