windows-development-sandbox 1.20.0 → 1.23.0

package/dist/guest/toolchains/native/msvc/packages.js

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { downloader, extractArchive, fetchJson } from '../../../../shared/download/index.js';
 import { safeRemove } from '../../../../shared/io/safe-remove.js';
 import { system32 } from '../../../../shared/system.js';
-import { execAsync } from '../../../runtime/process.js';
+import { runInstallerChecked } from '../../../runtime/pools.js';
 import { exists, mkdirp } from '../../../runtime/fs.js';
 import { log } from '../../../runtime/log.js';
 import { msiCabs, pickMsvcVersion, pickWindowsSdk } from '../../../../core/detect/versions.js';
@@ -93,9 +93,15 @@ const unpackVsix = async (vsix, work) => {
 const unpackMsi = async (msi) => {
     const logFile = msi + '.log';
     try {
-        await execAsync(system32('msiexec.exe'), ['/a', msi, '/quiet', '/qn', 'TARGETDIR=' + ROOT, '/l*v', logFile], {
-            stdio: 'ignore',
-        });
+        await runInstallerChecked(system32('msiexec.exe'), [
+            '/a',
+            msi,
+            '/quiet',
+            '/qn',
+            'TARGETDIR=' + ROOT,
+            '/l*v',
+            logFile,
+        ]);
     }
     catch (e) {
         const lines = exists(logFile)

package/dist/guest/toolchains/native/rust.d.ts

@@ -1,3 +1,5 @@
 import type { Toolchains } from '../../../core/types.js';
 import { type ToolEnv } from '../tool-env.js';
+/** rustup-init.exe (the small installer; the toolchain itself downloads when it runs), kept with Rust's tools. */
+export declare function fetchRustupInit(): Promise<void>;
 export declare function setupRust(env: ToolEnv, config: Toolchains['rust'], refresh: boolean): Promise<void>;

package/dist/guest/toolchains/native/rust.js

@@ -1,7 +1,7 @@
 // Rust: rustup + cargo, with crates installed prebuilt where possible (binstall.ts).
 import path from 'node:path';
 import { dryRun } from '../../runtime/paths.js';
-import { execAsync } from '../../runtime/process.js';
+import { execHeavy as execAsync } from '../../runtime/pools.js';
 import { exists } from '../../runtime/fs.js';
 import { log } from '../../runtime/log.js';
 import { arch, tool, versionOf } from '../tool-env.js';
@@ -9,6 +9,15 @@ import { downloadFile } from '../install.js';
 import { installOnce } from '../package-ledger.js';
 import { crateInstaller } from './binstall.js';
 import { installedMsvcEnv } from './msvc/index.js';
+/** rustup-init.exe (the small installer; the toolchain itself downloads when it runs), kept with Rust's tools. */
+export async function fetchRustupInit() {
+    const init = tool('rust', 'rustup-init.exe');
+    if (exists(init) || exists(path.join(tool('rust', 'cargo'), 'bin', 'rustup.exe')))
+        return;
+    await downloadFile('https://static.rust-lang.org/rustup/dist/' +
+        (arch === 'arm64' ? 'aarch64' : 'x86_64') +
+        '-pc-windows-msvc/rustup-init.exe', init);
+}
 export async function setupRust(env, config, refresh) {
     const RUSTUP_HOME = tool('rust', 'rustup');
     const CARGO_HOME = tool('rust', 'cargo');
@@ -21,9 +30,7 @@ export async function setupRust(env, config, refresh) {
     if (!exists(rustup)) {
         const init = tool('rust', 'rustup-init.exe');
         log('Installing Rust with rustup (~300 MB once; the toolchain downloads after rustup itself) ...');
-        await downloadFile('https://static.rust-lang.org/rustup/dist/' +
-            (arch === 'arm64' ? 'aarch64' : 'x86_64') +
-            '-pc-windows-msvc/rustup-init.exe', init);
+        await fetchRustupInit();
         await execAsync(init, [
             '-y',
             '--no-modify-path',

package/dist/guest/toolchains/native/unreal.d.ts

@@ -2,4 +2,6 @@ import type { Toolchains } from '../../../core/types.js';
 import type { ToolCtx } from '../step.js';
 import { type ToolEnv } from '../tool-env.js';
 export { UNREAL_COMPONENTS } from './vs-request.js';
+/** Downloads the DirectX redistributable ahead of the install (only once the licence is accepted). */
+export declare function fetchDirectX(config: Toolchains['unreal']): Promise<void>;
 export declare function setupUnreal(env: ToolEnv, config: Toolchains['unreal'], ctx: ToolCtx): Promise<void>;

package/dist/guest/toolchains/native/unreal.js

@@ -4,7 +4,7 @@
 // (visual-studio.ts), which the plan runs first. The engine itself comes from the Epic Games Launcher or its source.
 import os from 'node:os';
 import path from 'node:path';
-import { spawnAsync } from '../../../shared/download/index.js';
+import { runInstaller } from '../../runtime/pools.js';
 import { safeRemove } from '../../../shared/io/safe-remove.js';
 import { dryRun } from '../../runtime/paths.js';
 import { exists, mkdirp } from '../../runtime/fs.js';
@@ -17,17 +17,27 @@ import { installedVs } from './visual-studio.js';
 export { UNREAL_COMPONENTS } from './vs-request.js';
 const DIRECTX_URL = 'https://download.microsoft.com/download/8/4/A/84A35BF1-DAFE-4AE8-82AF-AD2AE20B6B14/directx_Jun2010_redist.exe';
 /** The June 2010 DirectX End-User Runtime (D3DX, XAudio 2.7, XInput 1.3), which Epic lists for the engine. */
-async function installDirectX() {
+const directXInstalled = () => {
     const system32 = path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32');
-    if (exists(path.join(system32, 'd3dx9_43.dll')) && exists(path.join(system32, 'XAudio2_7.dll')))
+    return exists(path.join(system32, 'd3dx9_43.dll')) && exists(path.join(system32, 'XAudio2_7.dll'));
+};
+/** The redistributable (downloaded once, signature checked). */
+const directXRedist = () => signedInstaller(DIRECTX_URL, path.join(tool('visualstudio'), 'directx_Jun2010_redist.exe'), 'the DirectX End-User Runtime (~95 MB once)', SIGNERS.microsoft);
+/** Downloads the DirectX redistributable ahead of the install (only once the licence is accepted). */
+export async function fetchDirectX(config) {
+    if (config.acceptLicense && !directXInstalled())
+        await directXRedist();
+}
+async function installDirectX() {
+    if (directXInstalled())
         return;
-    const redist = await signedInstaller(DIRECTX_URL, path.join(tool('visualstudio'), 'directx_Jun2010_redist.exe'), 'the DirectX End-User Runtime (~95 MB once)', SIGNERS.microsoft);
+    const redist = await directXRedist();
     const unpacked = path.join(os.tmpdir(), 'directx-redist');
     safeRemove(unpacked, os.tmpdir());
     mkdirp(unpacked);
-    if ((await spawnAsync(redist, ['/Q', '/T:' + unpacked])) !== 0 || !exists(path.join(unpacked, 'DXSETUP.exe')))
+    if ((await runInstaller(redist, ['/Q', '/T:' + unpacked])) !== 0 || !exists(path.join(unpacked, 'DXSETUP.exe')))
         throw new Error('could not unpack the DirectX End-User Runtime');
-    const code = await spawnAsync(path.join(unpacked, 'DXSETUP.exe'), ['/silent']);
+    const code = await runInstaller(path.join(unpacked, 'DXSETUP.exe'), ['/silent']);
     safeRemove(unpacked, os.tmpdir());
     if (code !== 0)
         throw new Error('the DirectX End-User Runtime installer failed (exit ' + code + ')');

package/dist/guest/toolchains/native/vcruntime.d.ts

@@ -1,4 +1,6 @@
 import { type ToolEnv } from '../tool-env.js';
+/** Downloads the installer ahead of `setupVcRuntime` (nothing when the runtime or the installer is there). */
+export declare function fetchVcRuntime(): Promise<void>;
 /**
  * A real installer (it writes to System32), so it runs on every boot; the installer itself is kept in persistent
  * storage and only run when Microsoft's signature on it checks out. Resolves true when this call ran the installer.

package/dist/guest/toolchains/native/vcruntime.js

@@ -1,7 +1,7 @@
 // The Visual C++ runtime (vcruntime140.dll & co.) that PHP and other native tools need.
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawnAsync } from '../../../shared/download/index.js';
+import { runInstaller } from '../../runtime/pools.js';
 import { dryRun } from '../../runtime/paths.js';
 import { exists } from '../../runtime/fs.js';
 import { log } from '../../runtime/log.js';
@@ -11,6 +11,14 @@ import { tool } from '../tool-env.js';
 const VC_REDIST = 'https://aka.ms/vs/17/release/vc_redist.x64.exe';
 /** 1638: a newer version is already installed; 3010: installed, a restart would finish it (not needed for the DLLs). */
 const OK_EXIT_CODES = [0, 1638, 3010];
+/** Downloads the installer ahead of `setupVcRuntime` (nothing when the runtime or the installer is there). */
+export async function fetchVcRuntime() {
+    const system32 = path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32');
+    const installer = tool('vcredist', 'vc_redist.x64.exe');
+    if (exists(installer) || exists(path.join(system32, 'vcruntime140.dll')))
+        return;
+    await downloadFile(VC_REDIST, installer);
+}
 /**
  * A real installer (it writes to System32), so it runs on every boot; the installer itself is kept in persistent
  * storage and only run when Microsoft's signature on it checks out. Resolves true when this call ran the installer.
@@ -34,7 +42,7 @@ export async function setupVcRuntime(env, summary = true) {
             throw new Error('vc_redist.x64.exe is not signed by Microsoft; deleted it (it is downloaded again next boot)');
         }
         log('Installing the Visual C++ runtime ...');
-        const code = await spawnAsync(installer, ['/install', '/quiet', '/norestart']);
+        const code = await runInstaller(installer, ['/install', '/quiet', '/norestart']);
         if (!OK_EXIT_CODES.includes(code ?? -1) || !exists(path.join(system32, 'vcruntime140.dll')))
             throw new Error('the Visual C++ runtime installer failed (exit ' + code + ')');
     }

package/dist/guest/toolchains/native/visual-studio.d.ts

@@ -6,9 +6,12 @@ export declare function installedVs(): {
     path: string;
     version: string;
 } | null;
+/** Downloads the bootstrapper now, so the install later starts without waiting for it. */
+export declare function prefetchVisualStudio(req: VsRequest): Promise<void>;
 /** Visual Studio as asked for: installed at boot when it is not there yet; its folder and version. */
 export declare function ensureVisualStudio(env: ToolEnv, req: VsRequest, o: {
     keepInstallFiles: boolean;
+    lowPriority?: boolean;
 }): Promise<{
     path: string;
     version: string;

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

@@ -9,6 +9,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { z } from 'zod';
 import { spawnAsync } from '../../../shared/download/index.js';
+import { heavy, runInstaller } from '../../runtime/pools.js';
 import { writeJsonAtomic } from '../../../shared/io/json.js';
 import { robocopyFailed } from '../../../shared/io/robocopy-result.js';
 import { safeRemove } from '../../../shared/io/safe-remove.js';
@@ -18,11 +19,12 @@ 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 { backgroundRunning } from '../../runtime/status.js';
 import { errMsg } from '../../../core/util/errors.js';
 import { SIGNERS, signedInstaller } from '../installers.js';
-import { assertLocalRoom, freeBytes, LOCAL_RESERVE_BYTES } from '../persisted.js';
+import { assertLocalRoom, freeBytes } from '../persisted.js';
 import { tool } from '../tool-env.js';
-import { layoutNextStep, vsExitText } from './vs-request.js';
+import { LAYOUT_STAGING_BYTES, layoutNextStep, STAGING_RESERVE_BYTES, vsExitText, } from './vs-request.js';
 export { BUILD_TOOLS_COMPONENTS, UNREAL_COMPONENTS, unrealUsesAutosdk, visualStudioWanted, } from './vs-request.js';
 const BOOTSTRAPPERS = {
     community: {
@@ -120,11 +122,11 @@ function reportLayoutFailure(code, temps) {
 /** 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']);
+    const code = await heavy.run(() => 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) {
+async function layoutInstaller(req, bootstrapper, lowPriority) {
     const layout = layoutDir(req.product);
     const marker = path.join(layout, '.complete.json');
     const installer = path.join(layout, BOOTSTRAPPERS[req.product].file);
@@ -151,24 +153,21 @@ async function layoutInstaller(req, bootstrapper) {
     }
     log('Saving the Visual Studio install files for later boots (~10 GB, once) ...');
     fs.rmSync(marker, { force: true });
-    // (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.
+    // The installer crashes (0xE0434352) when it builds the layout in a mapped folder, so it is built on the sandbox's
+    // own disk and copied over. That runs before Visual Studio is installed and the copy on C: is deleted first, so it
+    // needs room for the layout only (STAGING_RESERVE_BYTES spare), not for the layout and the install together.
     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');
+    if (layoutNextStep(null, freeBytes(drive), STAGING_RESERVE_BYTES) !== 'stage') {
+        warn('Visual Studio: less than ' +
+            Math.round((LAYOUT_STAGING_BYTES + STAGING_RESERVE_BYTES) / 1024 ** 3) +
+            ' GB free on ' +
+            drive +
+            ' to build the install files; downloading this boot');
         return null;
     }
     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 stagedCode = await runInstaller(bootstrapper, layoutArgs(req, staging), { lowPriority });
     const staged = path.join(staging, BOOTSTRAPPERS[req.product].file);
     let kept = false;
     if (OK_EXIT_CODES.includes(stagedCode) && exists(staged)) {
@@ -182,27 +181,44 @@ async function layoutInstaller(req, bootstrapper) {
     safeRemove(staging, drive);
     return kept && exists(installer) ? finish() : null;
 }
-async function install(req, keepInstallFiles) {
+/** The bootstrapper, downloaded (net pool) and checked; kept in tools\ for later boots. */
+function bootstrapperFor(req) {
+    const boot = BOOTSTRAPPERS[req.product];
+    return signedInstaller(boot.url, path.join(VS_DIR, boot.file), 'the ' + boot.name + ' installer', SIGNERS.microsoft);
+}
+/** Downloads the bootstrapper now, so the install later starts without waiting for it. */
+export async function prefetchVisualStudio(req) {
+    if (!req.accepted || installedVs())
+        return;
+    await bootstrapperFor(req);
+}
+async function install(req, keepInstallFiles, lowPriority) {
     const boot = BOOTSTRAPPERS[req.product];
-    const bootstrapper = await signedInstaller(boot.url, path.join(VS_DIR, boot.file), 'the ' + boot.name + ' installer', SIGNERS.microsoft);
+    const bootstrapper = await bootstrapperFor(req);
     let installer = null;
     if (keepInstallFiles) {
         try {
-            installer = await layoutInstaller(req, bootstrapper);
+            installer = await layoutInstaller(req, bootstrapper, lowPriority);
         }
         catch (e) {
             warn('Visual Studio: the offline copy failed (' + errMsg(e) + '); downloading this boot');
         }
     }
-    log('Installing ' + boot.name + (installer ? ' from the saved install files' : ' (downloads ~5-8 GB)') + ' ...');
-    const code = await spawnAsync(installer ?? bootstrapper, [
+    const run = (from, offline) => runInstaller(from, [
         '--quiet',
         '--wait',
         '--norestart',
         '--nocache',
-        ...(installer ? ['--noWeb'] : []),
+        ...(offline ? ['--noWeb'] : []),
         ...req.components.flatMap((id) => ['--add', id]),
-    ]);
+    ], { lowPriority });
+    log('Installing ' + boot.name + (installer ? ' from the saved install files' : ' (downloads ~5-8 GB)') + ' ...');
+    let code = await run(installer ?? bootstrapper, installer !== null);
+    if (installer && (!OK_EXIT_CODES.includes(code) || !installedVs())) {
+        // The saved copy is on the shared data disk: if installing from it fails, this boot downloads instead.
+        warn('Visual Studio: installing from the saved install files failed (' + vsExitText(code) + '); downloading');
+        code = await run(bootstrapper, false);
+    }
     if (!OK_EXIT_CODES.includes(code) || !installedVs())
         throw new Error('the Visual Studio installer failed (exit ' +
             code +
@@ -226,9 +242,11 @@ export async function ensureVisualStudio(env, req, o) {
     if (have)
         return have;
     if (duringSession())
-        throw new Error('Visual Studio is installed when the sandbox starts: restart it (sandbox restart) to get it');
+        throw new Error(backgroundRunning('Visual Studio')
+            ? 'Visual Studio is still installing in the background; it is ready in a few minutes'
+            : 'Visual Studio is installed when the sandbox starts: restart it (sandbox restart) to get it');
     assertLocalRoom(INSTALL_BYTES[req.product], BOOTSTRAPPERS[req.product].name);
-    await install(req, o.keepInstallFiles);
+    await install(req, o.keepInstallFiles, o.lowPriority === true);
     const vs = installedVs();
     env.summary.push('visual studio: ' +
         BOOTSTRAPPERS[req.product].name +

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

@@ -23,6 +23,8 @@ export declare function unrealUsesAutosdk(t: Toolchains, on?: (setting: boolean
 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;
+/** Spare room on the sandbox's disk while the layout is built there (before Visual Studio is installed). */
+export declare const STAGING_RESERVE_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.

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

@@ -76,6 +76,8 @@ export function vsExitText(code) {
 }
 /** 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;
+/** Spare room on the sandbox's disk while the layout is built there (before Visual Studio is installed). */
+export const STAGING_RESERVE_BYTES = 3 * 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.

package/dist/guest/toolchains/plan.js

@@ -1,4 +1,4 @@
-import { appsNeedMesa, appsNeedUv, setupApps } from '../apps/index.js';
+import { appsNeedMesa, appsNeedUv, prefetchApps, setupApps } from '../apps/index.js';
 import { dryRun } from '../runtime/paths.js';
 import { wanted } from './detect.js';
 import { DATABASE_NAMES, setupDatabase } from '../databases/index.js';
@@ -11,17 +11,17 @@ import { setupCpp } from './native/cpp.js';
 import { setupDotnet } from './native/dotnet.js';
 import { setupMesa } from './native/mesa.js';
 import { setupMsvc } from './native/msvc/index.js';
-import { setupUnreal } from './native/unreal.js';
-import { setupRust } from './native/rust.js';
+import { fetchDirectX, setupUnreal } from './native/unreal.js';
+import { fetchRustupInit, setupRust } from './native/rust.js';
 import { setupNode } from './languages/node.js';
 import { setupPwsh } from './tools/pwsh.js';
 import { setupPython } from './languages/python.js';
 import { setupBun, setupDeno, setupUv } from './runtimes.js';
-import { setupPhp } from './languages/php.js';
+import { fetchPhp, setupPhp } from './languages/php.js';
 import { setupRuby } from './languages/ruby.js';
-import { setupVcRuntime } from './native/vcruntime.js';
+import { fetchVcRuntime, setupVcRuntime } from './native/vcruntime.js';
 import { setupVscode } from './tools/vscode.js';
-import { ensureVisualStudio, unrealUsesAutosdk, visualStudioWanted } from './native/visual-studio.js';
+import { ensureVisualStudio, prefetchVisualStudio, 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';
@@ -49,6 +49,9 @@ export function plan(config, versions, o) {
         pcInstalls: o.pcInstalls ?? { items: [] },
         duringSession: duringSession(),
     };
+    // Downloads that run ahead of their steps (the scheduler starts them at once); a dry run downloads nothing.
+    const ahead = (work) => (dryRun ? {} : { fetch: work });
+    const deferred = o.deferHeavy === true && !dryRun;
     return [
         {
             name: 'Git',
@@ -71,8 +74,10 @@ export function plan(config, versions, o) {
             name: 'Visual Studio',
             enabled: vs !== null,
             shared: true,
+            background: deferred,
+            ...ahead(() => prefetchVisualStudio(vs)),
             install: async (env) => {
-                await ensureVisualStudio(env, vs, { keepInstallFiles: config.unreal.keepInstallFiles });
+                await ensureVisualStudio(env, vs, { keepInstallFiles: config.unreal.keepInstallFiles, lowPriority: deferred });
             },
         },
         {
@@ -80,6 +85,7 @@ export function plan(config, versions, o) {
             enabled: unreal,
             shared: true,
             after: ['Visual Studio', 'MSVC'],
+            ...ahead(() => fetchDirectX(config.unreal)),
             install: (env) => setupUnreal(env, config.unreal, ctx),
         },
         {
@@ -94,7 +100,9 @@ export function plan(config, versions, o) {
         {
             name: 'Rust',
             enabled: wanted(config.rust.enabled, 'rust'),
-            after: ['C/C++', 'MSVC', 'Visual Studio', 'Unreal'],
+            // Only the msvc host links with Visual Studio (and Unreal's tools): the GNU host does not wait for them.
+            after: rustHost(config).endsWith('-msvc') ? ['C/C++', 'MSVC', 'Visual Studio', 'Unreal'] : ['C/C++'],
+            ...ahead(fetchRustupInit),
             install: async (env) => {
                 await setupRust(env, { ...config.rust, host: rustHost(config) }, o.refresh);
                 const rust = resolveTargetDir(config.rust);
@@ -164,6 +172,7 @@ export function plan(config, versions, o) {
             name: 'Visual C++ runtime',
             enabled: config.vcRuntime.enabled || apps,
             shared: true,
+            ...ahead(fetchVcRuntime),
             install: async (env) => {
                 await setupVcRuntime(env);
             },
@@ -172,6 +181,7 @@ export function plan(config, versions, o) {
             name: 'PHP',
             enabled: wanted(config.php.enabled, 'php'),
             after: ['Visual C++ runtime'],
+            ...ahead(() => fetchPhp(config.php)),
             install: (env) => setupPhp(env, config.php),
         },
         { name: 'Deno', enabled: wanted(config.deno.enabled, 'deno'), install: (env) => setupDeno(env) },
@@ -208,6 +218,7 @@ export function plan(config, versions, o) {
             enabled: apps,
             shared: true,
             after: ['Mesa 3D', 'Visual C++ runtime', 'uv'],
+            ...ahead(() => prefetchApps(o.apps, { gitAccess: o.gitAccess, refresh: o.refresh })),
             install: (env) => setupApps(env, o.apps, { gitAccess: o.gitAccess, refresh: o.refresh }),
         },
         {

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

@@ -1,22 +1,3 @@
-import { type ToolEnv } from './tool-env.js';
-import type { ToolchainStep } from './step.js';
-export interface RunOptions {
-    /** Progress lines ("Installing Go, Rust (3 of 9 done)"); default: the sandbox's boot status. */
-    report?: (message: string) => void;
-    /** What machine-wide (shared) steps contributed at boot: reused instead of run again. */
-    reuse?: Record<string, ToolEnv>;
-}
-export declare class StepScheduler {
-    private readonly parallel;
-    /** One lock per kind of step ("Node 20" and "Node 22" share nvm's folders): held while that step runs, in any run. */
-    private readonly locks;
-    /** The step a download belongs to (several run at once), for its progress. */
-    private readonly currentStep;
-    constructor(parallel?: number);
-    /** Runs the steps (each with its own environment) and returns each step's environment, in plan order. */
-    run(steps: readonly ToolchainStep[], o: RunOptions): Promise<Map<string, ToolEnv>>;
-    /** Runs `work` once no other step of the same kind (first word of the name) is running. */
-    private exclusive;
-}
-/** The one scheduler: its locks span the boot's run and every project's run. */
+import { StepScheduler } from './step-scheduler.js';
+export { StepScheduler, type RunOptions, type SchedulerSink } from './step-scheduler.js';
 export declare const scheduler: StepScheduler;

package/dist/guest/toolchains/scheduler.js

@@ -1,123 +1,9 @@
-// Runs the planned steps in parallel, a few at a time, after the steps they depend on. One lock per kind of step is
-// held across runs: the boot and projects that join later never install two Nodes (or two Gos) at once.
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { downloader } from '../../shared/download/index.js';
+// The one scheduler: its locks span the boot's run and every project's run.
 import { warn } from '../runtime/log.js';
 import { setSandboxStatus } from '../runtime/status.js';
-import { errMsg } from '../../core/util/errors.js';
-import { emptyEnv } from './tool-env.js';
-/** How many installers run at once: enough to overlap downloads with installs, few enough not to thrash the disk. */
-const PARALLEL = 4;
-/** Runs one installer; a failure is reported and skipped so it never blocks the other toolchains. */
-async function runReported(name, env, work) {
-    try {
-        await work();
-    }
-    catch (e) {
-        warn(name +
-            ' could not be set up and is skipped; everything else still works, and the next start tries again. Reason: ' +
-            errMsg(e));
-        env.summary.push(name + ': FAILED');
-    }
-}
-export class StepScheduler {
-    parallel;
-    /** One lock per kind of step ("Node 20" and "Node 22" share nvm's folders): held while that step runs, in any run. */
-    locks = new Map();
-    /** The step a download belongs to (several run at once), for its progress. */
-    currentStep = new AsyncLocalStorage();
-    constructor(parallel = PARALLEL) {
-        this.parallel = parallel;
-    }
-    /** Runs the steps (each with its own environment) and returns each step's environment, in plan order. */
-    async run(steps, o) {
-        const envs = new Map(steps.map((s) => [s.name, emptyEnv()]));
-        const finished = new Map();
-        const running = new Set();
-        const waiting = [];
-        let done = 0;
-        // The boot (no `report`) also publishes structured progress: what runs now, how far its download is, how many are
-        // done.
-        const percent = new Map();
-        const active = () => [...running].map((name) => ({ name, ...(percent.has(name) ? { percent: percent.get(name) } : {}) }));
-        const say = o.report ??
-            ((message) => setSandboxStatus('provisioning', message, { active: active(), done, total: steps.length }));
-        const report = () => {
-            if (running.size)
-                say('Installing ' + [...running].join(', ') + ' (' + done + ' of ' + steps.length + ' done)');
-        };
-        if (!o.report)
-            downloader.watch(() => {
-                const name = this.currentStep.getStore();
-                return name
-                    ? (fraction) => {
-                        percent.set(name, Math.round(fraction * 100));
-                        report();
-                    }
-                    : null;
-            });
-        for (const s of steps) {
-            // Dependencies first (they are earlier in the plan, so their promises exist), then a free slot.
-            finished.set(s.name, (async () => {
-                await Promise.all((s.after ?? []).map((name) => finished.get(name)));
-                const env = envs.get(s.name);
-                const reused = s.shared ? o.reuse?.[s.name] : undefined;
-                if (reused) {
-                    envs.set(s.name, structuredClone(reused));
-                    done++;
-                    return;
-                }
-                while (running.size >= this.parallel)
-                    await new Promise((r) => waiting.push(r));
-                running.add(s.name);
-                report();
-                try {
-                    await this.currentStep.run(s.name, () => this.exclusive(s.name, () => runReported(s.name, env, async () => s.install(env))));
-                }
-                finally {
-                    running.delete(s.name);
-                    percent.delete(s.name);
-                    done++;
-                    report();
-                    waiting.shift()?.();
-                }
-            })());
-        }
-        try {
-            await Promise.all(finished.values());
-        }
-        finally {
-            if (!o.report)
-                downloader.watch(null);
-        }
-        if (!o.report)
-            setSandboxStatus('provisioning', 'Set up ' + steps.length + ' toolchains and databases', {
-                active: [],
-                done,
-                total: steps.length,
-            });
-        return envs;
-    }
-    /** Runs `work` once no other step of the same kind (first word of the name) is running. */
-    async exclusive(name, work) {
-        const key = name.split(' ')[0].toLowerCase();
-        const previous = this.locks.get(key) ?? Promise.resolve();
-        let release = () => undefined;
-        const mine = new Promise((r) => {
-            release = r;
-        });
-        const chained = previous.then(() => mine);
-        this.locks.set(key, chained);
-        await previous;
-        try {
-            return await work();
-        }
-        finally {
-            release();
-            if (this.locks.get(key) === chained)
-                this.locks.delete(key);
-        }
-    }
-}
-/** The one scheduler: its locks span the boot's run and every project's run. */
-export const scheduler = new StepScheduler();
+import { StepScheduler } from './step-scheduler.js';
+export { StepScheduler } from './step-scheduler.js';
+export const scheduler = new StepScheduler({
+    warn,
+    status: (message, progress) => setSandboxStatus('provisioning', message, progress),
+});

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

@@ -5,6 +5,19 @@ import { type RunOptions } from './scheduler.js';
 /** The combined environment, plus what each step contributed (kept so later projects reuse the shared steps). */
 export interface ToolchainResult extends ToolEnv {
     steps: Record<string, ToolEnv>;
+    /** Every enabled step of the plan (foreground and background), in plan order: the order the parts are merged in. */
+    names: string[];
 }
-/** Provisions every enabled toolchain and database, and returns the combined environment for the agent. */
-export declare function setupToolchains(config: Toolchains, versions: ToolVersions, options: ToolchainOptions, run?: RunOptions): Promise<ToolchainResult>;
+export interface SetupExtras {
+    /** The background steps start once this resolves (the boot: the agent's first session is running). */
+    gate?: Promise<void>;
+}
+/** The parts of these steps merged in the order of `names` (and the config's own variables on top). */
+export declare function mergeToolchains(config: Toolchains, names: readonly string[], parts: ReadonlyMap<string, ToolEnv> | Readonly<Record<string, ToolEnv>>, planNames?: readonly string[]): ToolchainResult;
+/**
+ * Provisions every enabled toolchain and database, and returns the combined environment for the agent. `later` is
+ * set when steps were left for the background: it resolves with the result of those steps alone.
+ */
+export declare function setupToolchains(config: Toolchains, versions: ToolVersions, options: ToolchainOptions, run?: RunOptions, extras?: SetupExtras): Promise<ToolchainResult & {
+    later: Promise<ToolchainResult> | null;
+}>;