windows-development-sandbox 1.23.2 → 1.25.1

package/dist/guest/setup/headroom.js

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { rotateLog } from '../../shared/io/index.js';
 import { HEADROOM_PORT, headroomArgs, headroomEnv, headroomUrl } from '../../shared/apps/index.js';
 import { logsDir } from '../runtime/paths.js';
 import { portOpen, waitForPort } from '../runtime/ports.js';
@@ -12,6 +13,8 @@ import { log } from '../runtime/log.js';
 import { installedAddon } from './agent-addons.js';
 /** The proxy's log (it redacts keys and tokens in what it logs). */
 export const HEADROOM_LOG = path.join(logsDir, 'headroom.log');
+/** The proxy logs every request and the file lives on the data disk: past this it is kept as headroom.log.1. */
+const HEADROOM_LOG_LIMIT = 20 * 1024 * 1024;
 /** Whether Headroom's own health check answers on the port (not some other program that took it). */
 function answersAsHeadroom(port) {
     return new Promise((resolve) => {
@@ -53,6 +56,7 @@ async function startProxy(env) {
         return false;
     if (await portOpen(HEADROOM_PORT))
         return true;
+    rotateLog(HEADROOM_LOG, HEADROOM_LOG_LIMIT);
     const out = fs.openSync(HEADROOM_LOG, 'a');
     try {
         spawn(exe, headroomArgs(HEADROOM_PORT), {

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

@@ -4,6 +4,8 @@ export interface HookTarget {
     cwd: string;
 }
 export declare function projectHooks(name: string, cwd: string): HookTarget;
+/** Whether `stage` has hooks to run (they write to the terminal themselves). */
+export declare function hasHooks(stage: string, target?: HookTarget): boolean;
 export declare function runHooks(stage: string, env: NodeJS.ProcessEnv, target?: HookTarget): void;
 /** The same without blocking: the session daemon keeps answering other requests while a project's hooks run. */
 export declare function runHooksAsync(stage: string, env: NodeJS.ProcessEnv, target: HookTarget): Promise<void>;

package/dist/guest/setup/hooks.js

@@ -45,6 +45,10 @@ const failed = (stage, name, status) => {
         throw new Error(message);
     warn(message);
 };
+/** Whether `stage` has hooks to run (they write to the terminal themselves). */
+export function hasHooks(stage, target = BOOT) {
+    return hooksOf(stage, target).length > 0;
+}
 export function runHooks(stage, env, target = BOOT) {
     for (const { name, command } of hooksOf(stage, target)) {
         log('Hook [' + stage + ']: ' + name);

package/dist/guest/setup/path-plan.d.ts

@@ -13,6 +13,18 @@ export interface PathPlanInput {
 }
 /** Ordered, de-duplicated (case, trailing slash) PATH folders; missing and dropped folders are left out. */
 export declare function planPath(input: PathPlanInput): string[];
+/**
+ * The PATH folders of the agent environment (sessions, the machine PATH, terminal tabs): the sandbox's own commands
+ * folder first, because its `claude` / `codex` shims carry the sandbox's flags and must beat a copy installed with
+ * `npm i -g` in nvm's node folder; then the toolchains' folders, the process's own and the appended ones. No
+ * duplicates (matched like pathKey); MSVC's tools before Git's usr\bin.
+ */
+export declare function sessionPath(o: {
+    readonly commands: string;
+    readonly prepend: readonly string[];
+    readonly base: readonly string[];
+    readonly append: readonly string[];
+}): string[];
 /** `base` with the folders of `extra` it lacks added at the end (a process keeps its own order and entries). */
 export declare function appendMissing(base: string, extra: string, skip?: (folder: string) => boolean): string;
 /**

package/dist/guest/setup/path-plan.js

@@ -32,6 +32,24 @@ export function planPath(input) {
     }
     return msvcBeforeGitUsr(result);
 }
+/**
+ * The PATH folders of the agent environment (sessions, the machine PATH, terminal tabs): the sandbox's own commands
+ * folder first, because its `claude` / `codex` shims carry the sandbox's flags and must beat a copy installed with
+ * `npm i -g` in nvm's node folder; then the toolchains' folders, the process's own and the appended ones. No
+ * duplicates (matched like pathKey); MSVC's tools before Git's usr\bin.
+ */
+export function sessionPath(o) {
+    const seen = new Set();
+    const result = [];
+    for (const folder of [o.commands, ...o.prepend, ...o.base, ...o.append]) {
+        const key = pathKey(folder);
+        if (!folder.trim() || seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(folder);
+    }
+    return msvcBeforeGitUsr(result);
+}
 /** `base` with the folders of `extra` it lacks added at the end (a process keeps its own order and entries). */
 export function appendMissing(base, extra, skip = () => false) {
     const seen = new Set(splitPath(base).map(pathKey));

package/dist/guest/toolchains/engines/epic-launcher.d.ts

@@ -0,0 +1,26 @@
+import { type LauncherEntry } from '../../../shared/unreal/index.js';
+/** The launcher's program (launcher 17+ is 64-bit; older ones were in Win32). */
+export declare function launcherExe(): string | null;
+/** Downloads the launcher's MSI ahead of the install (once). */
+export declare function fetchLauncher(): Promise<void>;
+/** Installs the launcher when this sandbox does not have it yet (the MSI, quietly). Returns its program. */
+export declare function ensureLauncher(): Promise<string>;
+export interface LauncherPlaceResult {
+    readonly installLocation: string | null;
+    readonly problem: string | null;
+    readonly freeBytes: number | null;
+    readonly needBytes: number;
+}
+/** Points the launcher's default install folder at tools\unreal\engines (every settings file it may read). */
+export declare function placeEngines(persist: boolean): LauncherPlaceResult;
+/** The saved LauncherInstalled.dat entries of engines in tools\unreal\engines whose folder is still there. */
+export declare function savedEntries(): LauncherEntry[];
+/** Puts the saved manifests back where the launcher reads them; the engine folders they name. */
+export declare function restoreLauncherItems(): string[];
+/** Merges these entries into the launcher's LauncherInstalled.dat (foreign entries kept). */
+export declare function writeLauncherEntries(entries: readonly LauncherEntry[]): void;
+/**
+ * Saves what the launcher knows about engines it installed into tools\unreal\engines (new or changed manifests, its
+ * LauncherInstalled.dat entries). Cheap: a few small files. Returns whether something new was saved.
+ */
+export declare function saveLauncherState(): boolean;

package/dist/guest/toolchains/engines/epic-launcher.js

@@ -0,0 +1,127 @@
+// The Epic Games Launcher in the sandbox: installed every boot from its MSI (downloaded once into tools\unreal, run
+// only when Epic's signature checks out; a sandbox loses Program Files), pointed at the data disk for engines
+// (GameUserSettings.ini [Launcher] DefaultAppInstallLocation, in the encoding the file has), and given back what it
+// knew about the engines it installed there: their .item manifests and LauncherInstalled.dat entries are saved on the
+// data disk while the sandbox runs (the daemon calls saveLauncherState) and put back at the next boot.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { readBoundedFile } from '../../../shared/io/bounded.js';
+import { readValid, writeJsonAtomic } from '../../../shared/io/json.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { enginePlaceProblem, ENGINE_NEED_BYTES, entriesUnder, launcherInstalledFile, launcherManifestsDir, launcherSettingsFiles, MAX_LAUNCHER_FILE_BYTES, mergeLauncherInstalled, restoreItems, saveItems, setLauncherInstallLocation, } from '../../../shared/unreal/index.js';
+import { errMsg } from '../../../core/util/errors.js';
+import { runInstaller } from '../../runtime/pools.js';
+import { exists, mkdirp } from '../../runtime/fs.js';
+import { log } from '../../runtime/log.js';
+import { SIGNERS, signedInstaller } from '../installers.js';
+import { ENGINES_DIR, SAVED_DIR, UNREAL_DIR } from './unreal-status.js';
+const MSI_URL = 'https://launcher-public-service-prod06.ol.epicgames.com/launcher/api/installer/download/EpicGamesLauncherInstaller.msi';
+const MSI_FILE = path.join(UNREAL_DIR, 'EpicGamesLauncherInstaller.msi');
+const SAVED_MANIFESTS = path.join(SAVED_DIR, 'Manifests');
+const SAVED_ENTRIES = path.join(SAVED_DIR, 'LauncherInstalled.json');
+const programData = () => process.env.ProgramData ?? 'C:\\ProgramData';
+const localAppData = () => process.env.LOCALAPPDATA ?? '';
+/** The launcher's program (launcher 17+ is 64-bit; older ones were in Win32). */
+export function launcherExe() {
+    const root = path.join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Epic Games', 'Launcher');
+    for (const arch of ['Win64', 'Win32']) {
+        const exe = path.join(root, 'Portal', 'Binaries', arch, 'EpicGamesLauncher.exe');
+        if (exists(exe))
+            return exe;
+    }
+    return null;
+}
+/** Downloads the launcher's MSI ahead of the install (once). */
+export async function fetchLauncher() {
+    if (!launcherExe())
+        await launcherMsi();
+}
+const launcherMsi = () => signedInstaller(MSI_URL, MSI_FILE, 'the Epic Games Launcher (~250 MB once)', SIGNERS.epic);
+/** Installs the launcher when this sandbox does not have it yet (the MSI, quietly). Returns its program. */
+export async function ensureLauncher() {
+    const have = launcherExe();
+    if (have)
+        return have;
+    const msi = await launcherMsi();
+    log('Installing the Epic Games Launcher ...');
+    const code = await runInstaller(SYSTEM.msiexec(), ['/i', msi, '/qn', '/norestart']);
+    const exe = launcherExe();
+    if ((code !== 0 && code !== 3010) || !exe)
+        throw new Error('the Epic Games Launcher installer failed (msiexec exit ' + code + ')');
+    return exe;
+}
+/** Points the launcher's default install folder at tools\unreal\engines (every settings file it may read). */
+export function placeEngines(persist) {
+    let error;
+    if (persist)
+        try {
+            mkdirp(ENGINES_DIR);
+            for (const file of launcherSettingsFiles(localAppData()))
+                setLauncherInstallLocation(file, ENGINES_DIR);
+        }
+        catch (e) {
+            error = "could not write the launcher's settings (" + errMsg(e) + ')';
+        }
+    else
+        error = 'toolchains.unreal.persistEngines is off';
+    const set = persist && !error;
+    const { problem, freeBytes } = enginePlaceProblem(set ? { set } : { set, error: error }, ENGINES_DIR);
+    return { installLocation: set ? ENGINES_DIR : null, problem, freeBytes, needBytes: ENGINE_NEED_BYTES };
+}
+const SavedEntriesSchema = z.object({
+    entries: z
+        .array(z.object({
+        InstallLocation: z.string().max(1024),
+        NamespaceId: z.string().max(200),
+        ItemId: z.string().max(200),
+        ArtifactId: z.string().max(200),
+        AppVersion: z.string().max(200),
+        AppName: z.string().max(200),
+    }))
+        .max(64),
+});
+/** The saved LauncherInstalled.dat entries of engines in tools\unreal\engines whose folder is still there. */
+export function savedEntries() {
+    return (readValid(SavedEntriesSchema, SAVED_ENTRIES)?.entries ?? []).filter((e) => e.InstallLocation.toLowerCase().startsWith(ENGINES_DIR.toLowerCase() + '\\') && exists(e.InstallLocation));
+}
+/** Puts the saved manifests back where the launcher reads them; the engine folders they name. */
+export function restoreLauncherItems() {
+    return restoreItems(SAVED_MANIFESTS, launcherManifestsDir(programData()), ENGINES_DIR, exists);
+}
+/** Merges these entries into the launcher's LauncherInstalled.dat (foreign entries kept). */
+export function writeLauncherEntries(entries) {
+    if (!entries.length)
+        return;
+    const file = launcherInstalledFile(programData());
+    const bytes = readBoundedFile(file, MAX_LAUNCHER_FILE_BYTES);
+    if (!bytes && fs.existsSync(file))
+        throw new Error(file + ' is too big to read');
+    const next = mergeLauncherInstalled(bytes ? bytes.toString('utf8') : null, entries);
+    mkdirp(path.dirname(file));
+    fs.writeFileSync(file, next, 'utf8');
+}
+/**
+ * Saves what the launcher knows about engines it installed into tools\unreal\engines (new or changed manifests, its
+ * LauncherInstalled.dat entries). Cheap: a few small files. Returns whether something new was saved.
+ */
+export function saveLauncherState() {
+    if (!exists(ENGINES_DIR))
+        return false;
+    const items = saveItems(launcherManifestsDir(programData()), SAVED_MANIFESTS, ENGINES_DIR);
+    const bytes = readBoundedFile(launcherInstalledFile(programData()), MAX_LAUNCHER_FILE_BYTES);
+    const live = bytes ? entriesUnder(bytes.toString('utf8'), ENGINES_DIR) : [];
+    const old = readValid(SavedEntriesSchema, SAVED_ENTRIES)?.entries ?? [];
+    const merged = [
+        ...old.filter((o) => !live.some((l) => l.InstallLocation.toLowerCase() === o.InstallLocation.toLowerCase())),
+        ...live,
+    ].filter((e) => exists(e.InstallLocation));
+    const changed = JSON.stringify(merged) !== JSON.stringify(old);
+    if (changed) {
+        mkdirp(SAVED_DIR);
+        writeJsonAtomic(SAVED_ENTRIES, { entries: merged.slice(0, 64) });
+    }
+    if (items.length || changed)
+        log('Unreal: saved what the Epic Games Launcher knows about its engines on the data disk');
+    return items.length > 0 || changed;
+}

package/dist/guest/toolchains/engines/unreal-engines.d.ts

@@ -1,4 +1,24 @@
+import { type EngineFs, type LauncherEntry, type MappedEngine, type UnrealEngine } from '../../../shared/unreal/index.js';
 import type { Toolchains } from '../../../core/types.js';
 import type { ToolCtx } from '../step.js';
 import type { ToolEnv } from '../tool-env.js';
-export declare function setupUnrealEngines(env: ToolEnv, _config: Toolchains['unreal'], _ctx: ToolCtx): Promise<void>;
+/** The real disk, read bounded. */
+export declare const DISK: EngineFs;
+/** This PC's engines the host mapped (session.json's pcInstalls). */
+export declare function mappedEngines(ctx: Pick<ToolCtx, 'pcInstalls'>): MappedEngine[];
+/** Every engine this sandbox has (an install the launcher has not finished is not one yet). */
+export declare function sandboxEngines(ctx: Pick<ToolCtx, 'pcInstalls'>, disk?: EngineFs): UnrealEngine[];
+/** The LauncherInstalled.dat entries for the installed builds: the launcher's own saved ones, else made from them. */
+export declare function launcherEntries(engines: readonly UnrealEngine[], ctx: Pick<ToolCtx, 'pcInstalls'>): LauncherEntry[];
+/** Registers the engines machine-wide: the registry, LauncherInstalled.dat, the .uproject file association. */
+export declare function registerEngines(engines: readonly UnrealEngine[], selectorFrom: UnrealEngine | null, ctx: Pick<ToolCtx, 'pcInstalls'>, aliases?: readonly {
+    readonly id: string;
+    readonly dir: string;
+}[]): Promise<void>;
+/**
+ * While the sandbox runs (the daemon, every few minutes): saves what the launcher learned about engines it installed
+ * on the data disk and, when something is new, registers them and lists them for the Unreal page.
+ */
+export declare function captureLauncherEngines(): Promise<void>;
+/** The project's engine on PATH, its variables, the guide's facts; the engines registered. */
+export declare function setupUnrealEngines(env: ToolEnv, config: Toolchains['unreal'], ctx: ToolCtx): Promise<void>;

package/dist/guest/toolchains/engines/unreal-engines.js

@@ -1,4 +1,164 @@
-import { notAvailableYet } from '../not-yet.js';
-export async function setupUnrealEngines(env, _config, _ctx) {
-    notAvailableYet(env, 'Unreal engines');
+// Unreal engines, for each project: every engine the sandbox has (this PC's, mapped read-only or as folders you
+// registered; the launcher's and other folders in tools\unreal\engines; source builds in project roots) is registered
+// (the registry, the launcher's LauncherInstalled.dat, the .uproject file association), and the engine the project's
+// .uproject names (else the newest) goes on its PATH with UE_ROOT, the derived data cache on the data disk and, with
+// Unreal 5.8's MCP plugin, the editor's MCP server in Claude Code. Machine-wide writes only add; a project that joins
+// later only adds its own engine choice.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readBoundedFile } from '../../../shared/io/bounded.js';
+import { chooseEngine, ddcVars, engineExtraDirs, engineToolDirs, engineVars, fileAssociationPlan, findEngines, findUproject, hasMcpPlugin, incompleteDirs, itemSizes, launcherManifestsDir, launcherEntriesFor, registryPlan, UNREAL_MCP_URL, unrealSummaryLine, uprojectAssociation, versionSelectorIn, versionText, } from '../../../shared/unreal/index.js';
+import { errMsg } from '../../../core/util/errors.js';
+import { exists, mkdirp } from '../../runtime/fs.js';
+import { log, warn } from '../../runtime/log.js';
+import { dryRun } from '../../runtime/paths.js';
+import { runScriptWithJsonAsync } from '../../runtime/process.js';
+import { projectWorkspace } from '../../runtime/project-context.js';
+import { session } from '../../runtime/session.js';
+import { setUnrealMcp, writeAddonMcpServers } from '../../setup/addon-mcp.js';
+import { saveLauncherState, savedEntries, writeLauncherEntries } from './epic-launcher.js';
+import { DDC_DIR, ENGINES_DIR, SAVED_DIR, updateUnrealStatus } from './unreal-status.js';
+const SAVED_MANIFESTS = path.join(SAVED_DIR, 'Manifests');
+/** The real disk, read bounded. */
+export const DISK = {
+    exists: (file) => exists(file),
+    read: (file, max) => readBoundedFile(file, max),
+    list: (dir) => {
+        try {
+            return fs.readdirSync(dir).slice(0, 500);
+        }
+        catch {
+            return []; // Not a folder: nothing in it.
+        }
+    },
+};
+/** This PC's engines the host mapped (session.json's pcInstalls). */
+export function mappedEngines(ctx) {
+    return ctx.pcInstalls.items
+        .filter((i) => i.kind === 'unreal')
+        .map((i) => ({
+        guest: i.guest,
+        id: i.id,
+        ...(i.writable ? { writable: true } : {}),
+        ...(i.buildId ? { buildId: i.buildId } : {}),
+    }));
+}
+/** The project roots of this sandbox (their folders may hold source builds). */
+function projectRoots() {
+    const roots = (session.mappedProjects ?? []).filter((m) => m.root).map((m) => m.guest);
+    return [...new Set([...roots, ...(session.roots ?? [])])].filter((r) => exists(r));
+}
+/** The engines the launcher installed in tools\unreal\engines (its saved manifests and entries name them). */
+function launcherDirs() {
+    return [...savedEntries().map((e) => e.InstallLocation), ...itemSizes(SAVED_MANIFESTS).keys()];
+}
+/** Every engine this sandbox has (an install the launcher has not finished is not one yet). */
+export function sandboxEngines(ctx, disk = DISK) {
+    const incomplete = incompleteDirs(launcherManifestsDir(process.env.ProgramData ?? 'C:\\ProgramData'), SAVED_MANIFESTS);
+    return findEngines({
+        mapped: mappedEngines(ctx),
+        enginesRoot: ENGINES_DIR,
+        launcherDirs: launcherDirs(),
+        projectRoots: projectRoots(),
+    }, disk).filter((e) => !incomplete.has(path.win32.normalize(e.dir).toLowerCase()));
+}
+/** The LauncherInstalled.dat entries for the installed builds: the launcher's own saved ones, else made from them. */
+export function launcherEntries(engines, ctx) {
+    return launcherEntriesFor(engines, savedEntries(), ctx.pcInstalls.items);
+}
+/** Registers the engines machine-wide: the registry, LauncherInstalled.dat, the .uproject file association. */
+export async function registerEngines(engines, selectorFrom, ctx, aliases = []) {
+    const selector = selectorFrom ? versionSelectorIn(selectorFrom.dir) : null;
+    const values = [
+        ...registryPlan(engines, aliases),
+        ...(selector && exists(selector) ? fileAssociationPlan(selector) : []),
+    ];
+    if (values.length)
+        await runScriptWithJsonAsync('set-registry-values.ps1', 'PlanFile', { values });
+    try {
+        writeLauncherEntries(launcherEntries(engines, ctx));
+    }
+    catch (e) {
+        warn("Unreal: the Epic Games Launcher's LauncherInstalled.dat was left as it is (" + errMsg(e) + ')');
+    }
+}
+/**
+ * While the sandbox runs (the daemon, every few minutes): saves what the launcher learned about engines it installed
+ * on the data disk and, when something is new, registers them and lists them for the Unreal page.
+ */
+export async function captureLauncherEngines() {
+    const unreal = session.toolchains.unreal;
+    if (dryRun || unreal.enabled !== true || !unreal.persistEngines || !saveLauncherState())
+        return;
+    const ctx = { pcInstalls: session.pcInstalls ?? { items: [] } };
+    const engines = sandboxEngines(ctx);
+    await registerEngines(engines, engines[0] ?? null, ctx);
+    const sizes = itemSizes(SAVED_MANIFESTS);
+    updateUnrealStatus((s) => ({ ...s, engines: engines.map((e) => statusEngine(e, sizes)) }));
+}
+const statusEngine = (e, sizes) => ({
+    id: e.id,
+    dir: e.dir,
+    version: versionText(e.version),
+    build: e.build,
+    origin: e.origin,
+    writable: e.writable,
+    sizeBytes: sizes.get(e.dir.toLowerCase()) ?? null,
+});
+/** The project's engine on PATH, its variables, the guide's facts; the engines registered. */
+export async function setupUnrealEngines(env, config, ctx) {
+    const workspace = projectWorkspace();
+    const engines = sandboxEngines(ctx);
+    const uproject = findUproject(workspace, DISK);
+    const text = uproject ? readBoundedFile(uproject, 1024 * 1024) : null;
+    const association = (text ? uprojectAssociation(text.toString('utf8')) : null) ?? { kind: 'none' };
+    const choice = chooseEngine(engines, association);
+    const engine = choice.engine;
+    if (dryRun) {
+        log('(dry run) would register ' + engines.length + ' Unreal engines and use ' + (engine?.dir ?? 'none'));
+        return;
+    }
+    try {
+        await registerEngines(engines, engine ?? engines[0] ?? null, ctx, engine && choice.alias ? [{ id: choice.alias, dir: engine.dir }] : []);
+    }
+    catch (e) {
+        warn('Unreal: registering the engines failed (' + errMsg(e) + '); Build.bat and RunUAT.bat still work from PATH');
+    }
+    const ddc = config.derivedDataCache === 'persisted' ? mkdirp(DDC_DIR) : null;
+    Object.assign(env.vars, ddcVars(config.derivedDataCache, DDC_DIR));
+    if (engine) {
+        env.prepend.push(...engineToolDirs(engine.dir, DISK));
+        env.append.push(...engineExtraDirs(engine.dir, DISK));
+        Object.assign(env.vars, engineVars(engine));
+    }
+    const mcp = engine && hasMcpPlugin(engine, DISK) ? UNREAL_MCP_URL : null;
+    if (mcp || !ctx.duringSession) {
+        setUnrealMcp(mcp);
+        try {
+            writeAddonMcpServers();
+        }
+        catch (e) {
+            warn("Unreal: the editor's MCP server was not added to Claude Code (" + errMsg(e) + ')');
+        }
+    }
+    const sizes = itemSizes(SAVED_MANIFESTS);
+    const status = updateUnrealStatus((s) => ({
+        ...s,
+        engines: engines.map((e) => statusEngine(e, sizes)),
+        projects: [
+            ...s.projects.filter((p) => p.workspace.toLowerCase() !== workspace.toLowerCase()),
+            { workspace, engine: engine?.dir ?? null, reason: choice.reason },
+        ].slice(-64),
+        ddc: { mode: config.derivedDataCache, dir: ddc },
+        vaults: ctx.pcInstalls.items.filter((i) => i.kind === 'unreal-vault').map((i) => i.guest),
+        mcpUrl: mcp ?? (ctx.duringSession ? s.mcpUrl : null),
+    }));
+    env.summary.push(unrealSummaryLine(status, workspace));
+    log('Unreal: ' +
+        engines.length +
+        ' engine(s); ' +
+        (engine ? 'this project uses ' + engine.id + ' at ' + engine.dir : 'none for this project') +
+        ' (' +
+        choice.reason +
+        ')');
 }

package/dist/guest/toolchains/engines/unreal-status.d.ts

@@ -0,0 +1,13 @@
+import { type UnrealStatus } from '../../../shared/unreal/index.js';
+export declare const UNREAL_DIR: string;
+/** Where the Epic Games Launcher installs engines (persistEngines). */
+export declare const ENGINES_DIR: string;
+/** The engines' local derived data cache (derivedDataCache "persisted"). */
+export declare const DDC_DIR: string;
+/** The launcher's manifests and entries of the engines in ENGINES_DIR, kept for later boots. */
+export declare const SAVED_DIR: string;
+export declare function readUnrealStatus(): UnrealStatus;
+/** Changes the status with `change` and writes it (whole, atomically). */
+export declare function updateUnrealStatus(change: (s: UnrealStatus) => UnrealStatus): UnrealStatus;
+/** A fresh status at boot: the machine parts start over, the engines and projects are found again. */
+export declare function resetUnrealStatus(): void;

package/dist/guest/toolchains/engines/unreal-status.js

@@ -0,0 +1,41 @@
+// tools\unreal\status.json: what the sandbox found for Unreal, for the guide and the Unreal page on the PC. The boot's
+// machine-wide step writes the launcher, Visual Studio and debugger parts, each project's step its engine; every write
+// keeps what the other parts wrote.
+import path from 'node:path';
+import { readValid, writeJsonAtomic } from '../../../shared/io/json.js';
+import { UNREAL_STATUS_FILE, UnrealStatusSchema } from '../../../shared/unreal/index.js';
+import { mkdirp } from '../../runtime/fs.js';
+import { tool } from '../tool-env.js';
+export const UNREAL_DIR = tool('unreal');
+/** Where the Epic Games Launcher installs engines (persistEngines). */
+export const ENGINES_DIR = path.join(UNREAL_DIR, 'engines');
+/** The engines' local derived data cache (derivedDataCache "persisted"). */
+export const DDC_DIR = path.join(UNREAL_DIR, 'ddc');
+/** The launcher's manifests and entries of the engines in ENGINES_DIR, kept for later boots. */
+export const SAVED_DIR = path.join(UNREAL_DIR, 'launcher');
+const FILE = path.join(UNREAL_DIR, UNREAL_STATUS_FILE);
+const EMPTY = {
+    updatedAt: '',
+    engines: [],
+    projects: [],
+    launcher: { installed: false, installLocation: null, problem: null, freeBytes: null, needBytes: 0 },
+    visualStudio: { version: '', path: '', how: '', check: '', ok: false },
+    debugger: null,
+    ddc: { mode: 'local', dir: null },
+    vaults: [],
+    mcpUrl: null,
+};
+export function readUnrealStatus() {
+    return readValid(UnrealStatusSchema, FILE) ?? EMPTY;
+}
+/** Changes the status with `change` and writes it (whole, atomically). */
+export function updateUnrealStatus(change) {
+    const next = { ...change(readUnrealStatus()), updatedAt: new Date().toISOString() };
+    mkdirp(UNREAL_DIR);
+    writeJsonAtomic(FILE, next);
+    return next;
+}
+/** A fresh status at boot: the machine parts start over, the engines and projects are found again. */
+export function resetUnrealStatus() {
+    updateUnrealStatus(() => EMPTY);
+}

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

@@ -0,0 +1,6 @@
+/** KitsRoot10 from the registry (64-bit view), or null. */
+export declare function kitsRoot(): string | null;
+/** The debuggers' x64 folder when cdb.exe is in it, else null. */
+export declare function debuggersDir(root?: string | null): string | null;
+/** The debuggers' folder, installed with the SDK installer when missing; null when there is no SDK to add them to. */
+export declare function ensureDebuggers(): Promise<string | null>;

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

@@ -0,0 +1,57 @@
+// The Windows SDK's Debugging Tools (cdb, windbg, kd) for reading Unreal crash dumps: not part of the SDK Visual Studio
+// installs, so the Windows SDK installer (downloaded once into tools\visualstudio, Microsoft's signature checked) adds
+// only that feature into the SDK the registry names (KitsRoot10). Visual Studio kept on the data disk has its SDK
+// there, so the debuggers are installed once and come back with it (~45 s, 370 MB).
+import path from 'node:path';
+import { SYSTEM } from '../../../shared/system.js';
+import { runInstaller } from '../../runtime/pools.js';
+import { execOutput } from '../../runtime/process.js';
+import { exists } from '../../runtime/fs.js';
+import { log } from '../../runtime/log.js';
+import { SIGNERS, signedInstaller } from '../installers.js';
+import { tool } from '../tool-env.js';
+/** The Windows SDK 10.0.22621 installer (the SDK version Visual Studio's Unreal components install). */
+const SDK_SETUP_URL = 'https://go.microsoft.com/fwlink/?linkid=2311806';
+const SDK_SETUP = tool('visualstudio', 'winsdksetup-22621.exe');
+/** KitsRoot10 from the registry (64-bit view), or null. */
+export function kitsRoot() {
+    const out = execOutput(SYSTEM.reg(), [
+        'query',
+        'HKLM\\SOFTWARE\\Microsoft\\Windows Kits\\Installed Roots',
+        '/v',
+        'KitsRoot10',
+        '/reg:64',
+    ]);
+    const m = /KitsRoot10\s+REG_SZ\s+(.+)$/im.exec(out);
+    return m ? m[1].trim() : null;
+}
+/** The debuggers' x64 folder when cdb.exe is in it, else null. */
+export function debuggersDir(root = kitsRoot()) {
+    if (!root)
+        return null;
+    const dir = path.join(root, 'Debuggers', 'x64');
+    return exists(path.join(dir, 'cdb.exe')) ? dir : null;
+}
+/** The debuggers' folder, installed with the SDK installer when missing; null when there is no SDK to add them to. */
+export async function ensureDebuggers() {
+    const root = kitsRoot();
+    if (!root)
+        return null;
+    const have = debuggersDir(root);
+    if (have)
+        return have;
+    const setup = await signedInstaller(SDK_SETUP_URL, SDK_SETUP, 'the Windows SDK installer, for its debuggers (~1.5 MB, then ~100 MB)', SIGNERS.microsoft);
+    log('Installing the Windows SDK debuggers (cdb, windbg) into ' + root + ' ...');
+    const code = await runInstaller(setup, [
+        '/features',
+        'OptionId.WindowsDesktopDebuggers',
+        '/quiet',
+        '/norestart',
+        '/ceip',
+        'off',
+    ]);
+    const dir = debuggersDir(root);
+    if (!dir)
+        throw new Error('the Windows SDK installer did not add the debuggers (exit ' + code + ')');
+    return dir;
+}

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

@@ -5,7 +5,8 @@ import { SYSTEM } from '../../../shared/system.js';
 import { dryRun } from '../../runtime/paths.js';
 import { execAsync, scriptOutput } from '../../runtime/process.js';
 import { exists } from '../../runtime/fs.js';
-import { log } from '../../runtime/log.js';
+import { log, warn } from '../../runtime/log.js';
+import { errMsg } from '../../../core/util/errors.js';
 import { arch, tool } from '../tool-env.js';
 import { installFromGithub } from '../install.js';
 /**
@@ -33,6 +34,8 @@ export async function setupMesa(env, config) {
         await setupLavapipe(env, dir);
 }
 const VULKAN_RUNTIME = 'https://sdk.lunarg.com/sdk/download/latest/windows/vulkan-runtime-components.zip';
+/** Used when "latest" is not published yet (LunarG announces a version before its runtime zip is up: a 404). */
+const VULKAN_RUNTIME_PINNED = 'https://sdk.lunarg.com/sdk/download/1.4.350.0/windows/vulkan-runtime-components.zip';
 /**
  * Software Vulkan: Mesa's lavapipe plus the Khronos loader (vulkan-1.dll, from LunarG's runtime components; Windows
  * Sandbox has no Vulkan loader). The loader ignores VK_DRIVER_FILES in elevated processes, and everything in the
@@ -43,15 +46,19 @@ const setupLavapipe = async (env, mesaDir) => {
     if (!exists(icd))
         throw new Error('this Mesa build has no lavapipe (' + path.basename(icd) + ')');
     const dir = tool('vulkan');
-    if (!exists(path.join(dir, 'vulkan-1.dll'))) {
-        log('Downloading the Vulkan loader (~10 MB once) ...');
+    // vulkaninfo.exe too: a copy kept from an older runtime zip may lack it.
+    if (!exists(path.join(dir, 'vulkan-1.dll')) || !exists(path.join(dir, 'vulkaninfo.exe'))) {
+        log('Downloading the Vulkan loader (~20 MB once) ...');
         // LunarG publishes no checksum for this zip; it comes over HTTPS from LunarG, the Khronos SDK's maintainer.
         // The zip has x86 and x64 folders: only the 64-bit loader (and vulkaninfo) is extracted.
-        await downloader.archive(VULKAN_RUNTIME, dir, {
-            locate: 'vulkan-1.dll',
-            fileName: 'vulkan-runtime.zip',
-            members: ['*/x64/*'],
-        });
+        const fetchRuntime = (url) => downloader.archive(url, dir, { locate: 'vulkan-1.dll', fileName: 'vulkan-runtime.zip', members: ['*/x64/*'] });
+        try {
+            await fetchRuntime(VULKAN_RUNTIME);
+        }
+        catch (e) {
+            warn('The latest Vulkan runtime could not be downloaded (' + errMsg(e) + '); using version 1.4.350.0.');
+            await fetchRuntime(VULKAN_RUNTIME_PINNED);
+        }
     }
     const register = (file) => execAsync(SYSTEM.reg(), ['add', 'HKLM\\SOFTWARE\\Khronos\\Vulkan\\Drivers', '/v', file, '/t', 'REG_DWORD', '/d', '0', '/f'], { stdio: 'ignore' });
     await register(icd);

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

@@ -14,6 +14,13 @@ export declare function cargoShim(env: ToolEnv, rust: Toolchains['rust']): void;
  * run at once in the whole sandbox and, with linker "lld", has MinGW's gcc use Rust's own lld instead of GNU ld.
  */
 export declare function linkGate(env: ToolEnv, rust: Toolchains['rust'], host: string): void;
+/**
+ * MSVC host: link.exe writes an executable into a mapped folder (the workspace, C:\AgentData) as all zeros, so a
+ * fresh build script or test program fails with "The file or directory is corrupted and unreadable" (os error 1392).
+ * Rust's own lld (a copy of rust-lld.exe named lld-link.exe, which is how lld picks its mode) writes them whole.
+ * `rust.linker` "gnu" keeps link.exe; a linker the user set for the target wins.
+ */
+export declare function lldLink(env: ToolEnv, rust: Toolchains['rust'], host: string): void;
 /**
  * Cargo defaults that fit Windows, written only when there is no $CARGO_HOME\config.toml yet: fewer parallel jobs
  * (parallel rustc ran out of paging file) and, for the GNU host, only line tables as debug info (full debug info made