windows-development-sandbox 1.18.4 → 1.23.0

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,58 @@ 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;
+/** 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.
+ */
+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

@@ -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, 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';
@@ -42,11 +42,16 @@ 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: [] },
         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',
@@ -69,27 +74,35 @@ 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 });
             },
         },
         {
             name: 'Unreal',
             enabled: unreal,
             shared: true,
-            after: ['Visual Studio'],
+            after: ['Visual Studio', 'MSVC'],
+            ...ahead(() => fetchDirectX(config.unreal)),
             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.
         {
             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);
@@ -159,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);
             },
@@ -167,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) },
@@ -203,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;
+}>;

package/dist/guest/toolchains/setup.js

@@ -1,25 +1,44 @@
-import { log } from '../runtime/log.js';
+import fs from 'node:fs';
+import { log, runQuiet } from '../runtime/log.js';
+import { toolsDir } from '../runtime/paths.js';
+import { installedToolPaths } from '../setup/path-plan.js';
 import { mkdirp } from '../runtime/fs.js';
-import { emptyEnv, tool } from './tool-env.js';
+import { tool } from './tool-env.js';
 import { plan } from './plan.js';
 import { scheduler } from './scheduler.js';
-/** Provisions every enabled toolchain and database, and returns the combined environment for the agent. */
-export async function setupToolchains(config, versions, options, run = {}) {
+import { mergeParts, runSplit } from './split.js';
+/** The parts of these steps merged in the order of `names` (and the config's own variables on top). */
+export function mergeToolchains(config, names, parts, planNames = names) {
+    const map = parts instanceof Map ? parts : new Map(Object.entries(parts));
+    return {
+        ...mergeParts(names, map, { environment: config.environment, bin: mkdirp(tool('bin')) }),
+        names: [...planNames],
+    };
+}
+/**
+ * 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 async function setupToolchains(config, versions, options, run = {}, extras = {}) {
     const steps = plan(config, versions, options).filter((s) => s.enabled);
-    const envs = await scheduler.run(steps, run);
-    // Merged in plan order, so PATH order never depends on which download finished first.
-    const env = { ...emptyEnv(), steps: Object.fromEntries(envs) };
-    env.prepend.push(mkdirp(tool('bin')));
-    for (const part of envs.values()) {
-        Object.assign(env.vars, part.vars);
-        env.prepend.push(...part.prepend);
-        env.append.push(...part.append);
-        env.summary.push(...part.summary);
-    }
-    Object.assign(env.vars, config.environment);
-    // The git guard's variables (AGENT_GIT_ACCESS, GIT_DIR, GIT_CONFIG_*, BASH_ENV) always win over
-    // toolchains.environment.
-    Object.assign(env.vars, envs.get('Git')?.vars);
-    log('Set up ' + steps.length + ' toolchains and databases.');
-    return env;
+    const split = await runSplit(scheduler, steps, run, { ...extras, quiet: runQuiet });
+    const result = mergeToolchains(config, split.nowNames, split.now, steps.map((s) => s.name));
+    // Python and rust already installed in the persistent tools are on PATH for every project (at the end, nothing is
+    // installed): the project this session is for may not have asked for them, but its scripts and neighbours use them.
+    const have = new Set(steps.map((s) => s.name));
+    const installed = installedToolPaths(toolsDir, { exists: fs.existsSync, list: (dir) => (fs.existsSync(dir) ? fs.readdirSync(dir) : []) }, new Set([...(have.has('Python') ? ['python'] : []), ...(have.has('Rust') ? ['rust'] : [])]));
+    result.append.push(...installed.append);
+    result.summary.push(...installed.summary);
+    for (const [name, value] of Object.entries(installed.vars))
+        result.vars[name] ??= value;
+    log('Set up ' +
+        split.nowNames.length +
+        ' toolchains and databases' +
+        (split.laterNames.length ? ' (' + split.laterNames.length + ' more later)' : '') +
+        '.');
+    const later = split.later
+        ? split.later.then((parts) => mergeToolchains(config, split.laterNames, parts, steps.map((s) => s.name)))
+        : null;
+    later?.catch(() => undefined);
+    return Object.assign(result, { later });
 }

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/toolchains/split.d.ts

@@ -0,0 +1,28 @@
+import { type ToolEnv } from './tool-env.js';
+import type { ToolchainStep } from './step.js';
+import type { RunOptions, StepScheduler } from './step-scheduler.js';
+/** The steps that wait for the gate: the ones marked `background`, and every step that comes after one. */
+export declare function backgroundNames(steps: readonly ToolchainStep[]): Set<string>;
+export interface SplitRun {
+    /** What the foreground steps contributed, in plan order. */
+    readonly now: Map<string, ToolEnv>;
+    readonly nowNames: readonly string[];
+    readonly laterNames: readonly string[];
+    /** The background steps' parts, once the gate opened and they ran; null when nothing was left for later. */
+    readonly later: Promise<Map<string, ToolEnv>> | null;
+}
+/**
+ * Runs the foreground steps and returns; the background steps (their downloads start now, behind the foreground ones)
+ * run after `gate`, inside `quiet` (file-only logging).
+ */
+export declare function runSplit(scheduler: StepScheduler, steps: readonly ToolchainStep[], run: RunOptions, o?: {
+    gate?: Promise<void>;
+    quiet?: <T>(work: () => T) => T;
+}): Promise<SplitRun>;
+/** The parts of these steps merged in the order of `names`, so PATH order never depends on which finished first. */
+export declare function mergeParts(names: readonly string[], parts: ReadonlyMap<string, ToolEnv>, o: {
+    environment: Readonly<Record<string, string>>;
+    bin: string;
+}): ToolEnv & {
+    steps: Record<string, ToolEnv>;
+};

package/dist/guest/toolchains/split.js

@@ -0,0 +1,60 @@
+// Splits a plan into the steps that run now and the ones that wait for a gate (the background: Visual Studio and what
+// needs it), and merges the steps' parts in plan order. Pure apart from the scheduler it is given.
+import { asBackground } from '../../shared/concurrency/index.js';
+import { emptyEnv } from './tool-env.js';
+/** The steps that wait for the gate: the ones marked `background`, and every step that comes after one. */
+export function backgroundNames(steps) {
+    const later = new Set(steps.filter((s) => s.background).map((s) => s.name));
+    for (let grew = later.size > 0; grew;) {
+        grew = false;
+        for (const s of steps)
+            if (!later.has(s.name) && (s.after ?? []).some((n) => later.has(n))) {
+                later.add(s.name);
+                grew = true;
+            }
+    }
+    return later;
+}
+/**
+ * Runs the foreground steps and returns; the background steps (their downloads start now, behind the foreground ones)
+ * run after `gate`, inside `quiet` (file-only logging).
+ */
+export async function runSplit(scheduler, steps, run, o = {}) {
+    const waiting = backgroundNames(steps);
+    const now = steps.filter((s) => !waiting.has(s.name));
+    const rest = steps.filter((s) => waiting.has(s.name));
+    asBackground(() => scheduler.startFetches(rest));
+    const parts = await scheduler.run(now, run);
+    const quiet = o.quiet ?? ((work) => work());
+    const later = rest.length
+        ? (async () => {
+            await o.gate;
+            // A progress callback that does nothing: the scheduler must not rewrite the boot's status as "ready".
+            return quiet(() => asBackground(() => scheduler.run(rest, { progress: () => undefined })));
+        })()
+        : null;
+    // Nobody may see a failed background run as an unhandled rejection before the boot awaits it.
+    later?.catch(() => undefined);
+    return { now: parts, nowNames: now.map((s) => s.name), laterNames: rest.map((s) => s.name), later };
+}
+/** The parts of these steps merged in the order of `names`, so PATH order never depends on which finished first. */
+export function mergeParts(names, parts, o) {
+    const present = names.filter((n) => parts.has(n));
+    const env = {
+        ...emptyEnv(),
+        steps: Object.fromEntries(present.map((n) => [n, parts.get(n)])),
+    };
+    env.prepend.push(o.bin);
+    for (const name of present) {
+        const p = parts.get(name);
+        Object.assign(env.vars, p.vars);
+        env.prepend.push(...p.prepend);
+        env.append.push(...p.append);
+        env.summary.push(...p.summary);
+    }
+    Object.assign(env.vars, o.environment);
+    // The git guard's variables (AGENT_GIT_ACCESS, GIT_DIR, GIT_CONFIG_*, BASH_ENV) always win over
+    // toolchains.environment.
+    Object.assign(env.vars, parts.get('Git')?.vars);
+    return env;
+}

package/dist/guest/toolchains/steam/client.js

@@ -4,6 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { errMsg } from '../../../core/util/errors.js';
+import { heavy } from '../../../shared/concurrency/index.js';
 import { moveIntoPlace, spawnAsync, stagingFolder } from '../../../shared/download/index.js';
 import { safeRemove } from '../../../shared/io/safe-remove.js';
 import { exists } from '../../runtime/fs.js';
@@ -38,7 +39,7 @@ async function installSteamClient() {
     try {
         log('Unpacking the Steam client into tools\\steam ...');
         // NSIS: /S silent, /D= the folder (last, unquoted: the staging path has no spaces).
-        const code = await spawnAsync(setup, ['/S', '/D=' + work], { timeout: SETUP_TIMEOUT_MS });
+        const code = await heavy.run(() => spawnAsync(setup, ['/S', '/D=' + work], { timeout: SETUP_TIMEOUT_MS }));
         const unpacked = path.join(work, 'steam.exe');
         if (!exists(unpacked))
             throw new Error('SteamSetup.exe did not unpack steam.exe (exit code ' + code + ')');