windows-development-sandbox 1.18.3 → 1.20.0

package/dist/guest/toolchains/native/visual-studio.js

@@ -10,15 +10,20 @@ import path from 'node:path';
 import { z } from 'zod';
 import { spawnAsync } from '../../../shared/download/index.js';
 import { writeJsonAtomic } from '../../../shared/io/json.js';
+import { robocopyFailed } from '../../../shared/io/robocopy-result.js';
+import { safeRemove } from '../../../shared/io/safe-remove.js';
+import { SYSTEM } from '../../../shared/system.js';
 import { execOutput } from '../../runtime/process.js';
 import { exists, mkdirp } from '../../runtime/fs.js';
 import { log, warn } from '../../runtime/log.js';
+import { logsDir } from '../../runtime/paths.js';
 import { duringSession } from '../../runtime/project-context.js';
 import { errMsg } from '../../../core/util/errors.js';
 import { SIGNERS, signedInstaller } from '../installers.js';
-import { assertLocalRoom, freeBytes } from '../persisted.js';
+import { assertLocalRoom, freeBytes, LOCAL_RESERVE_BYTES } from '../persisted.js';
 import { tool } from '../tool-env.js';
-export { BUILD_TOOLS_COMPONENTS, UNREAL_COMPONENTS, visualStudioWanted } from './vs-request.js';
+import { layoutNextStep, vsExitText } from './vs-request.js';
+export { BUILD_TOOLS_COMPONENTS, UNREAL_COMPONENTS, unrealUsesAutosdk, visualStudioWanted, } from './vs-request.js';
 const BOOTSTRAPPERS = {
     community: {
         url: 'https://aka.ms/vs/17/release/vs_community.exe',
@@ -63,6 +68,61 @@ export function installedVs() {
 function layoutDir(product) {
     return path.join(VS_DIR, product === 'community' ? 'layout' : 'layout-buildtools');
 }
+/** The layout arguments of the bootstrapper (the same for the data disk and the staging folder). */
+const layoutArgs = (req, folder) => [
+    '--layout',
+    folder,
+    '--lang',
+    'en-US',
+    '--quiet',
+    '--wait',
+    ...req.components.flatMap((id) => ['--add', id]),
+];
+/** The bootstrapper's newest log (dd_bootstrapper_*.log) in these folders, or null. */
+function newestBootstrapperLog(folders) {
+    const logs = folders.flatMap((dir) => {
+        try {
+            return fs
+                .readdirSync(dir)
+                .filter((n) => /^dd_bootstrapper_.*\.log$/i.test(n))
+                .map((n) => path.join(dir, n));
+        }
+        catch {
+            return []; // The folder is not there: no log in it.
+        }
+    });
+    const stamp = (f) => {
+        try {
+            return fs.statSync(f).mtimeMs;
+        }
+        catch {
+            return 0; // Gone since the listing.
+        }
+    };
+    return logs.sort((x, y) => stamp(y) - stamp(x))[0] ?? null;
+}
+/** Says why the layout failed and keeps the installer's log where the sandbox's logs are. */
+function reportLayoutFailure(code, temps) {
+    warn('Visual Studio: saving the install files failed (exit ' + code + '): ' + vsExitText(code));
+    const found = newestBootstrapperLog(temps);
+    if (!found)
+        return;
+    const kept = path.join(logsDir, 'vs-layout-' + new Date().toISOString().slice(0, 10) + '.log');
+    try {
+        fs.mkdirSync(logsDir, { recursive: true });
+        fs.copyFileSync(found, kept);
+        warn('Visual Studio: the installer log is ' + found + ' (a copy is in ' + kept + ')');
+    }
+    catch (e) {
+        warn('Visual Studio: the installer log is ' + found + ' (could not copy it: ' + errMsg(e) + ')');
+    }
+}
+/** Copies a finished layout onto the data disk (never /MOV: mapped folders refuse rename-over). */
+async function copyLayout(from, to) {
+    mkdirp(to);
+    const code = await spawnAsync(SYSTEM.robocopy(), [from, to, '/E', '/COPY:DAT', '/R:1', '/W:1', '/MT:8', '/NP']);
+    return !robocopyFailed(code);
+}
 /** The offline copy's installer when it holds every component; made or completed when there is room. */
 async function layoutInstaller(req, bootstrapper) {
     const layout = layoutDir(req.product);
@@ -79,6 +139,10 @@ async function layoutInstaller(req, bootstrapper) {
             return false;
         }
     };
+    const finish = () => {
+        writeJsonAtomic(marker, { components: [...req.components] });
+        return installer;
+    };
     if (has())
         return installer;
     if (freeBytes(mkdirp(VS_DIR)) < LAYOUT_ROOM_BYTES) {
@@ -87,21 +151,36 @@ async function layoutInstaller(req, bootstrapper) {
     }
     log('Saving the Visual Studio install files for later boots (~10 GB, once) ...');
     fs.rmSync(marker, { force: true });
-    const code = await spawnAsync(bootstrapper, [
-        '--layout',
-        layout,
-        '--lang',
-        'en-US',
-        '--quiet',
-        '--wait',
-        ...req.components.flatMap((id) => ['--add', id]),
-    ]);
-    if (!OK_EXIT_CODES.includes(code) || !exists(installer)) {
-        warn('Visual Studio: saving the install files failed (exit ' + code + '); downloading this boot');
+    // (a) The installer writes its scratch files to TEMP and moves them into the layout: a TEMP on the same (mapped)
+    // volume, inside the layout's folder tree, keeps those moves on one volume.
+    const scratch = mkdirp(path.join(VS_DIR, 'tmp'));
+    const code = await spawnAsync(bootstrapper, layoutArgs(req, layout), {
+        env: { ...process.env, TEMP: scratch, TMP: scratch },
+    });
+    if (OK_EXIT_CODES.includes(code) && exists(installer))
+        return finish();
+    reportLayoutFailure(code, [scratch, os.tmpdir()]);
+    // (b) Build it on the sandbox's own disk instead, then copy it over.
+    const drive = (process.env.SystemDrive ?? 'C:') + '\\';
+    if (layoutNextStep(code, freeBytes(drive), LOCAL_RESERVE_BYTES) !== 'stage') {
+        warn('Visual Studio: not enough room on ' + drive + ' to build the install files there; downloading this boot');
         return null;
     }
-    writeJsonAtomic(marker, { components: [...req.components] });
-    return installer;
+    const staging = path.join(drive, 'vs-layout-staging');
+    log('Building the install files on ' + drive + ' and copying them to ' + layout + ' ...');
+    const stagedCode = await spawnAsync(bootstrapper, layoutArgs(req, staging));
+    const staged = path.join(staging, BOOTSTRAPPERS[req.product].file);
+    let kept = false;
+    if (OK_EXIT_CODES.includes(stagedCode) && exists(staged)) {
+        kept = await copyLayout(staging, layout);
+        if (!kept)
+            warn('Visual Studio: copying the install files to ' + layout + ' failed');
+    }
+    else {
+        reportLayoutFailure(stagedCode, [os.tmpdir()]);
+    }
+    safeRemove(staging, drive);
+    return kept && exists(installer) ? finish() : null;
 }
 async function install(req, keepInstallFiles) {
     const boot = BOOTSTRAPPERS[req.product];
@@ -125,7 +204,12 @@ async function install(req, keepInstallFiles) {
         ...req.components.flatMap((id) => ['--add', id]),
     ]);
     if (!OK_EXIT_CODES.includes(code) || !installedVs())
-        throw new Error('the Visual Studio installer failed (exit ' + code + '); its logs are the dd_*.log files in ' + os.tmpdir());
+        throw new Error('the Visual Studio installer failed (exit ' +
+            code +
+            ': ' +
+            vsExitText(code) +
+            '); its logs are the dd_*.log files in ' +
+            os.tmpdir());
 }
 /** Visual Studio as asked for: installed at boot when it is not there yet; its folder and version. */
 export async function ensureVisualStudio(env, req, o) {

package/dist/guest/toolchains/native/vs-request.d.ts

@@ -17,3 +17,24 @@ export interface VsRequest {
     readonly accepted: boolean;
 }
 export declare function visualStudioWanted(t: Toolchains, on?: (setting: boolean | 'auto', name: string) => boolean): VsRequest | null;
+/** Whether Unreal is on and builds from the portable MSVC through AutoSDK instead of Visual Studio. */
+export declare function unrealUsesAutosdk(t: Toolchains, on?: (setting: boolean | 'auto', name: string) => boolean): boolean;
+/** The Visual Studio installer's exit code in plain words (it is a uint32: -1 and 4294967295 are the same). */
+export declare function vsExitText(code: number): string;
+/** Room the staging copy of the layout needs on the sandbox's own disk, on top of the reserve. */
+export declare const LAYOUT_STAGING_BYTES: number;
+/**
+ * What to do after the layout attempt in the data disk: 'done' when it worked, 'stage' (build it on the sandbox's
+ * own disk and copy it over) when it failed and that disk has room, 'skip' (download this boot) otherwise.
+ */
+export declare function layoutNextStep(exit: number | null, localFreeBytes: number, reserveBytes: number): 'done' | 'stage' | 'skip';
+export interface CopyPair {
+    readonly from: string;
+    readonly to: string;
+}
+/**
+ * The copies that make an Unreal AutoSDK tree from the portable MSVC (copies, not links: mapped folders refuse
+ * junctions): MSVC's tools into HostWin64\Win64\VS2022\<msvc> and the Windows SDK's Include, Lib and bin folders into
+ * HostWin64\Win64\Windows Kits\10. Pure.
+ */
+export declare function autosdkLayout(msvcRoot: string, msvc: string, sdk: string, autosdkRoot: string): CopyPair[];

package/dist/guest/toolchains/native/vs-request.js

@@ -1,3 +1,8 @@
+// Which Visual Studio this sandbox installs (a real installer: it runs every boot), from every toolchain that needs
+// one: Unreal (Community with the C++ game workload), Flutter's Windows desktop builds and Unity's Windows IL2CPP
+// builds (the Build Tools' C++ parts). Pure: no runtime, so the self-test loads it. Community holds everything the
+// Build Tools would add, so one install serves all of them.
+import path from 'node:path';
 /**
  * What Epic lists for Unreal Engine 5 with Visual Studio 2022: the game workload, MSVC v143, a Windows SDK of
  * 10.0.18362 or newer, the C++ profiling tools, the .NET Framework targeting packs some engine tools build against,
@@ -22,7 +27,8 @@ export const BUILD_TOOLS_COMPONENTS = [
 /** Whether a toolchain is on (the host resolved "auto"; a session file that still says "auto" counts as off). */
 const isOn = (setting) => setting === true;
 export function visualStudioWanted(t, on = isOn) {
-    const unreal = on(t.unreal.enabled, 'unreal');
+    // Unreal with visualStudio "autosdk" needs no Visual Studio: it builds from the portable MSVC (autosdk.ts).
+    const unreal = on(t.unreal.enabled, 'unreal') && t.unreal.visualStudio === 'full';
     const flutter = on(t.flutter.enabled, 'flutter') && t.flutter.windowsDesktop;
     const unity = on(t.unity.enabled, 'unity') && t.unity.modules.includes('windows-il2cpp');
     const users = [...(unreal ? ['unreal'] : []), ...(flutter ? ['flutter'] : []), ...(unity ? ['unity'] : [])];
@@ -44,3 +50,56 @@ export function visualStudioWanted(t, on = isOn) {
         accepted: t.msvc.acceptLicense,
     };
 }
+/** Whether Unreal is on and builds from the portable MSVC through AutoSDK instead of Visual Studio. */
+export function unrealUsesAutosdk(t, on = isOn) {
+    return on(t.unreal.enabled, 'unreal') && t.unreal.visualStudio === 'autosdk';
+}
+/** The Visual Studio installer's exit code in plain words (it is a uint32: -1 and 4294967295 are the same). */
+export function vsExitText(code) {
+    const c = code >>> 0;
+    switch (c) {
+        case 0:
+            return 'installed';
+        case 3010:
+            return 'done; a restart would finish it (not needed here)';
+        case 1602:
+            return 'cancelled';
+        case 5007:
+            return 'the installer refused to run (blocked by Windows, for example a restart waiting)';
+        case 8006:
+            return 'Visual Studio is running and must be closed first';
+        case 0xe0434352:
+            return '0xE0434352: the Visual Studio installer crashed';
+        default:
+            return 'the installer failed with exit ' + c + ' (0x' + c.toString(16).toUpperCase() + ')';
+    }
+}
+/** Room the staging copy of the layout needs on the sandbox's own disk, on top of the reserve. */
+export const LAYOUT_STAGING_BYTES = 12 * 1024 ** 3;
+/**
+ * What to do after the layout attempt in the data disk: 'done' when it worked, 'stage' (build it on the sandbox's
+ * own disk and copy it over) when it failed and that disk has room, 'skip' (download this boot) otherwise.
+ */
+export function layoutNextStep(exit, localFreeBytes, reserveBytes) {
+    if (exit !== null && (exit === 0 || exit === 3010))
+        return 'done';
+    return localFreeBytes >= LAYOUT_STAGING_BYTES + reserveBytes ? 'stage' : 'skip';
+}
+/**
+ * The copies that make an Unreal AutoSDK tree from the portable MSVC (copies, not links: mapped folders refuse
+ * junctions): MSVC's tools into HostWin64\Win64\VS2022\<msvc> and the Windows SDK's Include, Lib and bin folders into
+ * HostWin64\Win64\Windows Kits\10. Pure.
+ */
+export function autosdkLayout(msvcRoot, msvc, sdk, autosdkRoot) {
+    const win64 = path.win32.join(autosdkRoot, 'HostWin64', 'Win64');
+    return [
+        {
+            from: path.win32.join(msvcRoot, 'VC', 'Tools', 'MSVC', msvc),
+            to: path.win32.join(win64, 'VS2022', msvc),
+        },
+        ...['Include', 'Lib', 'bin'].map((part) => ({
+            from: path.win32.join(msvcRoot, 'Windows Kits', '10', part, sdk),
+            to: path.win32.join(win64, 'Windows Kits', '10', part, sdk),
+        })),
+    ];
+}

package/dist/guest/toolchains/not-yet.d.ts

@@ -1,2 +1,2 @@
 import type { ToolEnv } from './tool-env.js';
-export declare function notAvailableYet(env: ToolEnv, what: string): void;
+export declare function notAvailableYet(_env: ToolEnv, what: string): void;

package/dist/guest/toolchains/not-yet.js

@@ -1,6 +1,6 @@
-// What a toolchain step whose module is not written yet does: says so in the log and the summary, installs nothing.
+// What a toolchain step whose module is not written yet does: says so in the log, installs nothing and adds no
+// summary line.
 import { log } from '../runtime/log.js';
-export function notAvailableYet(env, what) {
+export function notAvailableYet(_env, what) {
     log(what + ': not available yet (nothing installed)');
-    env.summary.push(what + ': not available yet');
 }

package/dist/guest/toolchains/persisted.js

@@ -7,6 +7,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { freeBytesAt } from '../../shared/io/disk.js';
 import { readValid, writeJsonAtomic } from '../../shared/io/json.js';
 import { safeRemove } from '../../shared/io/safe-remove.js';
 import { dataDir } from '../runtime/paths.js';
@@ -27,13 +28,7 @@ function checkSpec(spec) {
 }
 /** Free bytes for this user on the disk holding `dir` (0 when it cannot be told). */
 export function freeBytes(dir, deps = {}) {
-    try {
-        const s = (deps.statfs ?? fs.statfsSync)(dir);
-        return s.bavail * s.bsize;
-    }
-    catch {
-        return 0;
-    }
+    return freeBytesAt(dir, deps.statfs) ?? 0;
 }
 const gb = (bytes) => (bytes / GB).toFixed(1) + ' GB';
 /** Throws (with the fix) when the disk holding `dir` has less than `needBytes` free. */

package/dist/guest/toolchains/plan.js

@@ -21,7 +21,7 @@ import { setupPhp } from './languages/php.js';
 import { setupRuby } from './languages/ruby.js';
 import { setupVcRuntime } from './native/vcruntime.js';
 import { setupVscode } from './tools/vscode.js';
-import { ensureVisualStudio, visualStudioWanted } from './native/visual-studio.js';
+import { ensureVisualStudio, unrealUsesAutosdk, visualStudioWanted } from './native/visual-studio.js';
 import { duringSession } from '../runtime/project-context.js';
 import { setupSteam } from './steam/steam.js';
 import { setupGodot } from './engines/godot.js';
@@ -42,6 +42,8 @@ export function plan(config, versions, o) {
     const android = wanted(config.android.enabled, 'android');
     // One Visual Studio for every toolchain that needs the real one (Unreal, Flutter desktop, Unity IL2CPP).
     const vs = visualStudioWanted(config, (setting, name) => wanted(setting, name));
+    // Unreal on the portable MSVC (AutoSDK) needs that MSVC even when nothing else asked for it.
+    const autosdk = unrealUsesAutosdk(config, (setting, name) => wanted(setting, name));
     const ctx = {
         refresh: o.refresh,
         pcInstalls: o.pcInstalls ?? { items: [] },
@@ -77,13 +79,16 @@ export function plan(config, versions, o) {
             name: 'Unreal',
             enabled: unreal,
             shared: true,
-            after: ['Visual Studio'],
+            after: ['Visual Studio', 'MSVC'],
             install: (env) => setupUnreal(env, config.unreal, ctx),
         },
         {
             name: 'MSVC',
-            enabled: wanted(config.msvc.enabled, 'msvc') && vs === null,
-            install: (env) => setupMsvc(env, config.msvc),
+            enabled: (wanted(config.msvc.enabled, 'msvc') || (autosdk && config.msvc.enabled !== false)) && vs === null,
+            // The same Visual Studio licence terms, which Unreal's acceptLicense already names.
+            install: (env) => setupMsvc(env, autosdk
+                ? { ...config.msvc, acceptLicense: config.msvc.acceptLicense || config.unreal.acceptLicense }
+                : config.msvc),
         },
         // Rust links with MSVC (msvc host) or MinGW's gcc (GNU host): whichever it uses goes first.
         {

package/dist/guest/toolchains/signature.d.ts

@@ -0,0 +1,5 @@
+import { type AppSigner, type Signature } from '../../shared/signer.js';
+/** The names on a file's valid signature, or null when it is unsigned, tampered with, or cannot be read. */
+export declare function signatureOf(file: string): Signature | null;
+/** Whether a file's valid signature is the expected signer's. */
+export declare function signedBy(file: string, signer: AppSigner): boolean;

package/dist/guest/toolchains/signature.js

@@ -0,0 +1,22 @@
+// A file's Authenticode signature (sandbox\scripts\get-signature.ps1) checked against the signer a download names.
+import { z } from 'zod';
+import { signerMatches } from '../../shared/signer.js';
+import { scriptOutput } from '../runtime/process.js';
+const SignatureSchema = z.object({ subject: z.string().max(4096), issuer: z.string().max(4096) });
+/** The names on a file's valid signature, or null when it is unsigned, tampered with, or cannot be read. */
+export function signatureOf(file) {
+    const text = scriptOutput('get-signature.ps1', ['-Path', file]).trim();
+    if (!text)
+        return null;
+    try {
+        const parsed = SignatureSchema.safeParse(JSON.parse(text));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null; // Not the script's JSON: treated as unsigned.
+    }
+}
+/** Whether a file's valid signature is the expected signer's. */
+export function signedBy(file, signer) {
+    return signerMatches(signatureOf(file), signer);
+}

package/dist/guest/vpn/tunnel.d.ts

@@ -1,6 +1,9 @@
+import { type VpnFailureCode } from '../../shared/vpn/failure.js';
 export interface TunnelOutcome {
     readonly ok: boolean;
     readonly message: string;
+    /** Why it failed (when it did), for the host to act on. */
+    readonly code?: VpnFailureCode;
     /** The tunnel's own address (what the kill switch lets through). */
     readonly tunnelIp?: string;
 }

package/dist/guest/vpn/tunnel.js

@@ -6,21 +6,14 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { classifyFailure } from '../../shared/vpn/failure.js';
 import { tunnelAddressFromLog } from '../../shared/vpn/kill-switch.js';
 import { logsDir } from '../runtime/paths.js';
 import { log } from '../runtime/log.js';
 const DONE = 'Initialization Sequence Completed';
 /** Why the log says OpenVPN stopped, in a short plain sentence (or null when it does not say). */
 export function failureReason(text) {
-    if (/AUTH_FAILED/i.test(text))
-        return 'the VPN refused the login (for NordVPN use the service credentials, not your account password)';
-    if (/TLS Error: TLS key negotiation failed|TLS handshake failed/i.test(text))
-        return 'it could not reach the VPN server (the network blocks it, or the server is down)';
-    if (/All wintun adapters on this system are in use|Cannot open TUN\/TAP|Could not create Wintun|ovpn-dco.*(error|failed)/i.test(text))
-        return 'the network driver for the tunnel could not be used';
-    if (/Exiting due to fatal error/i.test(text))
-        return 'OpenVPN stopped with an error';
-    return null;
+    return classifyFailure(text)?.reason ?? null;
 }
 const tail = (text, lines = 12) => text.trim().split(/\r?\n/).slice(-lines).join('\n');
 /** Connects. Never leaves the login on disk; kills OpenVPN when the tunnel does not come up in time. */
@@ -57,17 +50,22 @@ export async function startTunnel(o) {
                 const tunnelIp = tunnelAddressFromLog(text) ?? undefined;
                 return { ok: true, message: 'the tunnel is up', ...(tunnelIp ? { tunnelIp } : {}) };
             }
-            const reason = failureReason(text);
+            const failure = classifyFailure(text);
+            const reason = failure?.reason ?? null;
             if (exited !== null || reason) {
                 if (exited === null)
                     child.kill();
                 keepLog();
-                return { ok: false, message: (reason ?? 'OpenVPN stopped') + '. ' + tail(text, 4) };
+                return {
+                    ok: false,
+                    code: failure?.code ?? 'other',
+                    message: (reason ?? 'OpenVPN stopped') + '. ' + tail(text, 4),
+                };
             }
             if (Date.now() > deadline) {
                 child.kill();
                 keepLog();
-                return { ok: false, message: 'the tunnel did not come up in time. ' + tail(text, 4) };
+                return { ok: false, code: 'timeout', message: 'the tunnel did not come up in time. ' + tail(text, 4) };
             }
             await new Promise((r) => setTimeout(r, 500));
         }

package/dist/guest/vpn/vpn.js

@@ -123,6 +123,7 @@ export async function setupVpn(secrets, ptyHostExe) {
             warn('VPN: the kill switch did not hold: a direct connection still got out. If the tunnel drops, traffic leaves through your normal connection.');
     };
     setVpnStatus('starting', 'Starting the VPN');
+    let failureCode;
     try {
         if (!session.networking)
             throw new Error('networking is off for this sandbox');
@@ -178,6 +179,7 @@ export async function setupVpn(secrets, ptyHostExe) {
         if (!result.ok) {
             if (wireguardExe)
                 await removeWireguardTunnel(wireguardExe);
+            failureCode = result.code;
             throw new Error(result.message);
         }
         if (!result.tunnelIp || !hasAdapter(result.tunnelIp))
@@ -207,7 +209,10 @@ export async function setupVpn(secrets, ptyHostExe) {
                 ? ' The kill switch is on, so this sandbox has NO internet access.'
                 : ' The kill switch could NOT close the network, so this sandbox is ONLINE through your normal connection, without the VPN.';
         warn('VPN failed: ' + reason + after);
-        setVpnStatus('failed', reason, killSwitch ? { killSwitchHeld: held } : {});
+        setVpnStatus('failed', reason, {
+            code: failureCode ?? 'other',
+            ...(killSwitch ? { killSwitchHeld: held } : {}),
+        });
         return false;
     }
 }

package/dist/host/accounts/leases.d.ts

@@ -3,13 +3,13 @@ import { type ServiceKind } from '../../shared/accounts/index.js';
 declare const LeaseSchema: z.ZodObject<{
     kind: z.ZodEnum<{
         unity: "unity";
-        steam: "steam";
-        epic: "epic";
-        cfx: "cfx";
         keystore: "keystore";
         play: "play";
         expo: "expo";
         appstore: "appstore";
+        cfx: "cfx";
+        steam: "steam";
+        epic: "epic";
     }>;
     dataSet: z.ZodString;
     launchId: z.ZodString;

package/dist/host/accounts/source.js

@@ -11,5 +11,5 @@ export function pcEnv() {
 }
 /** What a kind whose host side is not written yet says. */
 export function notAvailableYet(kind) {
-    return fail('Saving a ' + SERVICE_SPECS[kind].label + ' sign-in is not available yet.', 'It comes in a later version of the sandbox.');
+    return fail('Saving a ' + SERVICE_SPECS[kind].label + ' sign-in comes in a later version of the sandbox.', 'Nothing was changed.');
 }

package/dist/host/agent-commands/commands.js

@@ -1,4 +1,4 @@
-// (Beta) Agent commands: with agentCommands.enabled, typing an agent's own command on this PC (claude, codex, ...)
+// Agent commands: with agentCommands.enabled, typing an agent's own command on this PC (claude, codex, ...)
 // starts it in a hidden sandbox for the folder you are in and attaches that terminal. Small forwarding files in
 // <storage>\agent-commands go first on YOUR PATH (so they win over npm's and the installers' copies); turning it off
 // removes the files and that one PATH entry. SANDBOX_AGENT_DIRECT=1 runs the real agent on this PC instead.

package/dist/host/agent-commands/forwarders.d.ts

@@ -1,7 +1,19 @@
 import type { AgentCommand } from './commands.js';
 /** Marks files this tool wrote, so only those are ever replaced or removed. */
 export declare const MARKER = "windows-development-sandbox agent command";
+/** What a forwarding file runs: the managed install's launcher when there is one, else node + the entry file. */
+export interface ForwardTarget {
+    readonly node: string;
+    readonly entry: string;
+    /** The managed install's `bin\sandbox.cmd`: it survives updates, which remove the version folder `entry` is in. */
+    readonly launcher?: string;
+}
+/**
+ * Where the forwarding files send the typed command. Under a managed install (installRoot, the folder with `bin`,
+ * `versions` and `node`) that is its launcher; otherwise the entry file of this copy.
+ */
+export declare function forwardTarget(packageRoot: string, installRoot: string | null, node: string): ForwardTarget;
 /** The .cmd file for one agent (cmd, PowerShell and Windows Terminal all run it). */
-export declare function forwardingCmd(a: AgentCommand, node: string, entry: string): string;
+export declare function forwardingCmd(a: AgentCommand, target: ForwardTarget): string;
 /** The same for Git Bash, which looks for a file without an extension. */
-export declare function forwardingSh(a: AgentCommand, node: string, entry: string): string;
+export declare function forwardingSh(a: AgentCommand, target: ForwardTarget): string;

package/dist/host/agent-commands/forwarders.js

@@ -1,12 +1,30 @@
+import path from 'node:path';
 /** Marks files this tool wrote, so only those are ever replaced or removed. */
 export const MARKER = 'windows-development-sandbox agent command';
+/**
+ * Where the forwarding files send the typed command. Under a managed install (installRoot, the folder with `bin`,
+ * `versions` and `node`) that is its launcher; otherwise the entry file of this copy.
+ */
+export function forwardTarget(packageRoot, installRoot, node) {
+    const entry = path.join(packageRoot, 'dist', 'bin', 'sandbox.js');
+    return installRoot ? { node, entry, launcher: path.join(installRoot, 'bin', 'sandbox.cmd') } : { node, entry };
+}
+const posix = (p) => p.replace(/^([A-Za-z]):/, (_m, d) => '/' + d.toLowerCase()).replace(/\\/g, '/');
 /** The .cmd file for one agent (cmd, PowerShell and Windows Terminal all run it). */
-export function forwardingCmd(a, node, entry) {
+export function forwardingCmd(a, target) {
+    const launch = ' launch --harness ' + a.harness + ' --headless --terminal -- %*';
     return [
         '@echo off',
-        'rem ' + MARKER + ' (Beta). Turn off: sandbox agent-commands off. Run the real one: set SANDBOX_AGENT_DIRECT=1',
+        'rem ' + MARKER + '. Turn off: sandbox agent-commands off. Run the real one: set SANDBOX_AGENT_DIRECT=1',
         'if "%SANDBOX_AGENT_DIRECT%"=="1" goto direct',
-        '"' + node + '" "' + entry + '" launch --harness ' + a.harness + ' --headless --terminal -- %*',
+        // A missing program (the tool was uninstalled or moved) runs the real agent instead of failing.
+        ...(target.launcher
+            ? ['if not exist "' + target.launcher + '" goto direct', 'call "' + target.launcher + '"' + launch]
+            : [
+                'if not exist "' + target.node + '" goto direct',
+                'if not exist "' + target.entry + '" goto direct',
+                '"' + target.node + '" "' + target.entry + '"' + launch,
+            ]),
         'exit /b %errorlevel%',
         ':direct',
         'call "' + a.real + '" %*',
@@ -14,20 +32,20 @@ export function forwardingCmd(a, node, entry) {
     ].join('\r\n');
 }
 /** The same for Git Bash, which looks for a file without an extension. */
-export function forwardingSh(a, node, entry) {
-    const posix = (p) => p.replace(/^([A-Za-z]):/, (_m, d) => '/' + d.toLowerCase()).replace(/\\/g, '/');
+export function forwardingSh(a, target) {
     const q = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+    const launch = ' launch --harness ' + a.harness + ' --headless --terminal -- "$@"';
+    const shLauncher = target.launcher ? posix(target.launcher).replace(/\.cmd$/i, '') : null;
     return [
         '#!/bin/sh',
-        '# ' + MARKER + ' (Beta). Turn off: sandbox agent-commands off. Run the real one: SANDBOX_AGENT_DIRECT=1',
+        '# ' + MARKER + '. Turn off: sandbox agent-commands off. Run the real one: SANDBOX_AGENT_DIRECT=1',
         'if [ "$SANDBOX_AGENT_DIRECT" = "1" ]; then exec ' + q(posix(a.real)) + ' "$@"; fi',
-        'exec ' +
-            q(posix(node)) +
-            ' ' +
-            q(posix(entry)) +
-            ' launch --harness ' +
-            a.harness +
-            ' --headless --terminal -- "$@"',
+        ...(shLauncher
+            ? ['[ -f ' + q(shLauncher) + ' ] || exec ' + q(posix(a.real)) + ' "$@"', 'exec ' + q(shLauncher) + launch]
+            : [
+                '[ -f ' + q(posix(target.entry)) + ' ] || exec ' + q(posix(a.real)) + ' "$@"',
+                'exec ' + q(posix(target.node)) + ' ' + q(posix(target.entry)) + launch,
+            ]),
         '',
     ].join('\n');
 }

package/dist/host/agent-commands/reconcile.d.ts

@@ -1,4 +1,5 @@
 import type { Config } from '../../core/types.js';
+import { type ForwardTarget } from './forwarders.js';
 import { type AgentCommand } from './commands.js';
 export interface Reconciled {
     on: boolean;
@@ -9,4 +10,4 @@ export interface Reconciled {
  * Makes this PC match agentCommands: on = a forwarding file per installed agent and the folder first on your PATH;
  * off = no files, no PATH entry. Only touches files it wrote and its own PATH entry; does nothing when already right.
  */
-export declare function reconcileAgentCommands(config: Config, storageRoot: string, node: string, entry: string): Reconciled;
+export declare function reconcileAgentCommands(config: Config, storageRoot: string, target: ForwardTarget): Reconciled;