windows-development-sandbox 1.7.0 → 1.9.0

package/dist/host/launch/generate.js

@@ -3,18 +3,24 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import os from 'node:os';
 import { widenForProjects } from '../../core/local-config/index.js';
 import { dirExists, ensureDir, fail, writeJson } from '../../core/util/index.js';
+import { engineFor } from '../engines/index.js';
 import { capturePersonalization, stageClaudeProfile } from '../profile/index.js';
 import { clearSecrets, writeSecrets } from '../secrets/index.js';
+import { folderAttachment } from '../storage/providers/index.js';
 import { assertTestWritable } from '../test-guard.js';
+import { writeLoadSettings } from '../life/watchdog.js';
+import { loadProfileOf } from './risk-notes.js';
 import { planBootProjects } from './boot-projects.js';
 import { planDatabases } from './database-plan.js';
 import { collectMappings } from './mappings.js';
 import { guestSession, logonEnv } from './session-file.js';
 import { copyRuntime, stageGitIdentity, stageHooks } from './stage.js';
 import { decideProjectToolchains } from './toolchains.js';
-import { buildWsb, resolveMemoryMb } from './wsb-file.js';
+import { buildLaunchPlan } from './launch-plan.js';
+import { decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
 const NO_PROFILE = { hostDir: null, staged: [], skipped: [], credentials: false, secretsRemoved: [] };
 /** Moves the staged copy of this PC's Claude login out of the launch folder; its text goes in the one-shot file. */
 function takeStagedCredentials(launchPath) {
@@ -25,7 +31,9 @@ function takeStagedCredentials(launchPath) {
     fs.rmSync(file, { force: true });
     return text;
 }
-export function generateSandbox(given) {
+export function generateSandbox(given, 
+/** The engine launch.ts opened (hcs needs a look at this PC first); Windows Sandbox when left out. */
+opened) {
     // Several projects at boot: the sandbox also gets what the others want and you allowed (core/local-config).
     const others = given.bootWants?.projects ?? [];
     const boot = planBootProjects({
@@ -43,10 +51,15 @@ export function generateSandbox(given) {
             fail('Unknown agent: ' + harnessName, 'Configured agents: ' + Object.keys(config.harnesses).join(', ')));
     if (!dirExists(workspaceHost))
         fail('The workspace folder does not exist: ' + workspaceHost, 'cd into the project first.');
+    // An engine or storage kind that cannot work yet stops the launch here, before anything is written.
+    const engine = opened ?? engineFor(config);
+    if (config.storage.contained !== 'off' && !o.dataMappings)
+        fail('Contained storage was not prepared for this launch.', 'Launch with sandbox launch (it mounts the image first).');
     assertTestWritable(storageRoot);
     assertTestWritable(dataPath);
     // Checked before anything is written, so a refusal leaves nothing behind.
-    const memoryMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes), ...others.map((p) => (typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0)));
+    const commitAvailableMb = o.commitAvailableMb ?? null;
+    const memoryMb = Math.max(resolveMemoryMb(config.sandbox, o.freeMemoryBytes, undefined, commitAvailableMb), ...others.map((p) => (typeof p.config.sandbox.memoryMb === 'number' ? p.config.sandbox.memoryMb : 0)));
     const launchId = Date.now() + '-' + crypto.randomBytes(3).toString('hex');
     const launchPath = path.join(storageRoot, 'launches', launchId);
     // Whatever must stay secret goes in a one-shot file in the data folder, never into the launch folder (the sandbox
@@ -65,29 +78,58 @@ export function generateSandbox(given) {
     const personalization = config.personalization.enabled ? capturePersonalization(launchPath) : 'disabled';
     const databases = o.databases ?? planDatabases(config.databases, workspaceHost);
     const toolchains = decideProjectToolchains(o);
-    if (o.vpn) {
+    if (o.vpn?.profile) {
         ensureDir(path.join(launchPath, 'vpn'));
         fs.writeFileSync(path.join(launchPath, 'vpn', 'server.ovpn'), o.vpn.profile, 'utf8');
     }
-    const session = guestSession(o, { launchId, launchPath, harness, boot, mappings, profile, databases, toolchains });
+    const session = guestSession(o, {
+        launchId,
+        launchPath,
+        harness,
+        boot,
+        mappings,
+        profile,
+        databases,
+        toolchains,
+        memoryMb,
+    });
     const sessionPath = path.join(launchPath, 'session.json');
     writeJson(sessionPath, session);
+    writeLoadSettings(storageRoot, dataPath, {
+        profile: loadProfileOf(config),
+        reserveHostMb: config.sandbox.reserveHostMb,
+    });
     writeSecrets(dataPath, launchId, {
         ...(harness && Object.keys(harness.environment).length ? { harnessEnvironment: harness.environment } : {}),
         ...(claudeCredentials ? { claudeCredentials } : {}),
-        ...(o.vpn ? { vpn: o.vpn.credentials } : {}),
+        ...(o.vpn?.credentials ? { vpn: o.vpn.credentials } : {}),
+        ...(o.vpn?.wireguardConfig ? { wireguardConfig: o.vpn.wireguardConfig } : {}),
     });
     fs.writeFileSync(path.join(launchPath, 'env.cmd'), logonEnv(session.workspace), 'utf8');
     copyRuntime(o.packageRoot, launchPath);
     stageHooks(o.packageRoot, launchPath, o.run.scripts);
-    const wsbPath = path.join(launchPath, 'agent.wsb');
-    fs.writeFileSync(wsbPath, buildWsb(config, memoryMb, mappings), 'utf8');
+    const enginePlan = engine.plan(buildLaunchPlan({
+        config,
+        memoryMb,
+        mappings,
+        launchPath,
+        storage: o.dataMappings
+            ? o.dataMappings.map((m) => ({ kind: 'folder', host: m.host, guest: m.guest, readOnly: m.readOnly }))
+            : [folderAttachment({ dataPath, guest: GUEST.data })],
+    }));
+    for (const file of enginePlan.files)
+        fs.writeFileSync(file.path, file.text, 'utf8');
+    const wsbPath = enginePlan.entry;
     return {
         wsbPath,
+        enginePlan,
         launchPath,
         launchId,
         sessionPath,
         memoryMb,
+        memoryNote: config.sandbox.memoryMb === 'auto'
+            ? memoryNote(decideMemory(config.sandbox, Math.floor((o.freeMemoryBytes ?? os.freemem()) / 1048576), Math.floor(os.totalmem() / 1048576), commitAvailableMb))
+            : null,
         bootConfig: config,
         widened: wide.widened,
         mappings,

package/dist/host/launch/index.d.ts

@@ -1,7 +1,9 @@
 export { generateSandbox } from './generate.js';
 export { decideProjectToolchains } from './toolchains.js';
 export { hostToolsOf, logonEnv } from './session-file.js';
-export { GUEST, buildWsb, resolveMemoryMb } from './wsb-file.js';
+export { agentMemoryLimitMb, decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+export { GENTLE_NOTE, vgpuSource, vgpuWarning } from './risk-notes.js';
+export { buildLaunchPlan, buildWsb } from './launch-plan.js';
 export { MAX_BOOT_PROJECTS, planBootProjects, shownByRoot, type BootProjects } from './boot-projects.js';
 export { databaseCatalog, planDatabases } from './database-plan.js';
 export { msvcHint, projectEntries, readProjectFiles, uvHint } from './project-scan.js';

package/dist/host/launch/index.js

@@ -1,7 +1,9 @@
 export { generateSandbox } from './generate.js';
 export { decideProjectToolchains } from './toolchains.js';
 export { hostToolsOf, logonEnv } from './session-file.js';
-export { GUEST, buildWsb, resolveMemoryMb } from './wsb-file.js';
+export { agentMemoryLimitMb, decideMemory, GUEST, memoryNote, resolveMemoryMb } from './wsb-file.js';
+export { GENTLE_NOTE, vgpuSource, vgpuWarning } from './risk-notes.js';
+export { buildLaunchPlan, buildWsb } from './launch-plan.js';
 export { MAX_BOOT_PROJECTS, planBootProjects, shownByRoot } from './boot-projects.js';
 export { databaseCatalog, planDatabases } from './database-plan.js';
 export { msvcHint, projectEntries, readProjectFiles, uvHint } from './project-scan.js';

package/dist/host/launch/launch-plan.d.ts

@@ -0,0 +1,13 @@
+import type { Config, ResolvedMapping } from '../../core/types.js';
+import { type LaunchPlan } from '../engines/index.js';
+import type { StorageAttachment } from '../storage/providers/index.js';
+export interface LaunchPlanInput {
+    readonly config: Config;
+    readonly memoryMb: number;
+    readonly mappings: readonly ResolvedMapping[];
+    readonly launchPath: string;
+    readonly storage: readonly StorageAttachment[];
+}
+export declare function buildLaunchPlan(input: LaunchPlanInput): LaunchPlan;
+/** The .wsb text for these settings (the Windows Sandbox engine's file, without writing it). */
+export declare function buildWsb(config: Config, memoryMb: number, mappings: readonly ResolvedMapping[]): string;

package/dist/host/launch/launch-plan.js

@@ -0,0 +1,26 @@
+import { wsbText } from '../engines/index.js';
+import { GUEST } from './wsb-file.js';
+export function buildLaunchPlan(input) {
+    const s = input.config.sandbox;
+    return {
+        launchPath: input.launchPath,
+        memoryMb: input.memoryMb,
+        cpuLimit: s.cpuLimit,
+        networking: s.networking,
+        devices: {
+            gpu: s.vGpu,
+            clipboard: s.clipboard,
+            audioInput: s.audioInput,
+            videoInput: s.videoInput,
+            printers: s.printerRedirection,
+            protectedClient: s.protectedClient,
+        },
+        mappings: input.mappings,
+        logonCommand: GUEST.launch + '\\sandbox\\boot\\logon.cmd',
+        storage: input.storage,
+    };
+}
+/** The .wsb text for these settings (the Windows Sandbox engine's file, without writing it). */
+export function buildWsb(config, memoryMb, mappings) {
+    return wsbText(buildLaunchPlan({ config, memoryMb, mappings, launchPath: GUEST.launch, storage: [] }));
+}

package/dist/host/launch/mappings.js

@@ -6,6 +6,7 @@ import { assertSafeMapping } from '../../core/safe-paths.js';
 import { dirExists, errMsg, fail, isInsideOrEqual, UserError } from '../../core/util/index.js';
 import { shownByRoot } from './boot-projects.js';
 import { deriveGuest, isValidGuestPath, guestConflict, guestFix, PROJECTS_GUEST, sandboxFolder, tidyGuestPath, } from '../../shared/paths/index.js';
+import { dataMapping } from '../storage/providers/index.js';
 import { GUEST } from './wsb-file.js';
 import { guestGitDir, planView } from '../workspace-view/index.js';
 /**
@@ -23,7 +24,7 @@ export function collectMappings(o, launchPath, boot = { roots: [], projects: [],
     const inRoot = !view && shownByRoot(boot.roots, workspaceHost, config.guestWorkspace);
     const mappings = [
         { host: launchPath, guest: GUEST.launch, readOnly: true },
-        { host: dataPath, guest: GUEST.data, readOnly: false },
+        ...(o.dataMappings ?? [dataMapping({ dataPath, guest: GUEST.data })]),
         ...(inRoot
             ? []
             : [{ host: view ? view.options.view : workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly }]),

package/dist/host/launch/risk-notes.d.ts

@@ -0,0 +1,10 @@
+import type { Config } from '../../core/types.js';
+import type { LoadProfile } from '../../shared/memory/index.js';
+/** The stricter load profile applies whenever vGPU is on, from any source. */
+export declare function loadProfileOf(config: Config): LoadProfile;
+/** Where vGpu being on comes from, for the sentence below: your own settings, or a project file you allowed. */
+export declare function vgpuSource(yourSettingOn: boolean): string;
+/** The vGPU warning (pure). `source` is vgpuSource(...) or "your settings". */
+export declare function vgpuWarning(source: string): string;
+/** The launch note that goes with the vGPU warning: what the tool does about it by itself. */
+export declare const GENTLE_NOTE = "vGPU is on: the sandbox runs gentler so this PC stays responsive.";

package/dist/host/launch/risk-notes.js

@@ -0,0 +1,18 @@
+// Plain-words warnings about settings that can take the whole PC down, shown at launch, by doctor and in crash reports.
+/** The stricter load profile applies whenever vGPU is on, from any source. */
+export function loadProfileOf(config) {
+    return config.sandbox.vGpu ? 'gentle' : 'normal';
+}
+/** Where vGpu being on comes from, for the sentence below: your own settings, or a project file you allowed. */
+export function vgpuSource(yourSettingOn) {
+    return yourSettingOn ? 'your settings' : "this project's .sandbox-config.json, which you allowed";
+}
+/** The vGPU warning (pure). `source` is vgpuSource(...) or "your settings". */
+export function vgpuWarning(source) {
+    return ('vGPU is on (from ' +
+        source +
+        "): the sandbox uses this PC's graphics card. With some graphics drivers, heavy use can freeze the whole PC. " +
+        'Turn it off unless a program in the sandbox needs the GPU (the mesa toolchain gives software OpenGL without it).');
+}
+/** The launch note that goes with the vGPU warning: what the tool does about it by itself. */
+export const GENTLE_NOTE = 'vGPU is on: the sandbox runs gentler so this PC stays responsive.';

package/dist/host/launch/session-file.d.ts

@@ -10,6 +10,8 @@ export interface SessionParts {
     readonly profile: ProfileResult;
     readonly databases: DatabasePlan[];
     readonly toolchains: Generated['toolchains'];
+    /** The sandbox's memory (MB), for the agents' memory limit. */
+    readonly memoryMb: number;
 }
 /** What was found on this PC to copy instead of download. */
 export declare function hostToolsOf(probe: HostProbe): GuestSession['hostTools'];

package/dist/host/launch/session-file.js

@@ -5,6 +5,9 @@ import { resolveToolchains } from '../../core/detect/index.js';
 import { hubName, PROJECTS_GUEST, substDrives } from '../../shared/paths/index.js';
 import { hostClaudeDir } from '../profile/index.js';
 import { databaseCatalog } from './database-plan.js';
+import { agentMemoryLimitMb } from './wsb-file.js';
+import { effectiveCpuLimit } from '../../shared/memory/index.js';
+import { loadProfileOf } from './risk-notes.js';
 /** What was found on this PC to copy instead of download. */
 export function hostToolsOf(probe) {
     return {
@@ -59,8 +62,11 @@ export function guestSession(o, parts) {
         },
         personalization: fs.existsSync(path.join(parts.launchPath, 'personalize', 'personalize.reg')),
         substDrives: substDrives(parts.mappings.map((m) => m.guest)),
-        cpuLimitPercent: config.sandbox.cpuLimit === 'none' ? null : config.sandbox.cpuLimit,
+        cpuLimitPercent: effectiveCpuLimit(config.sandbox.cpuLimit, loadProfileOf(config)),
+        loadProfile: loadProfileOf(config),
         pageFileMb: config.sandbox.pageFileMb,
+        agentMemoryLimitMb: agentMemoryLimitMb(parts.memoryMb, config.sandbox.agentMemoryHeadroomMb),
+        pressureResponse: config.sandbox.pressureResponse,
         apps: config.apps,
         auditProcesses: config.audit.enabled && config.audit.processes,
         agentHomes: Object.assign({}, ...Object.values(config.harnesses).map((h) => h.home?.env ?? {})),

package/dist/host/launch/wsb-file.d.ts

@@ -1,4 +1,4 @@
-import type { Config, ResolvedMapping } from '../../core/types.js';
+import type { Config } from '../../core/types.js';
 export declare const GUEST: {
     readonly launch: "C:\\AgentLaunch";
     readonly data: "C:\\AgentData";
@@ -6,7 +6,31 @@ export declare const GUEST: {
     readonly mirror: "C:\\Mirror";
 };
 type SandboxSettings = Config['sandbox'];
-/** "auto": free RAM minus the reserve, but never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM. */
-export declare function resolveMemoryMb(sandbox: SandboxSettings, freeMemoryBytes?: number, totalMemoryBytes?: number): number;
-export declare function buildWsb(config: Config, memoryMb: number, mappings: ResolvedMapping[]): string;
+export type MemoryLimit = 'free' | 'share' | 'max' | 'commit';
+export interface MemoryDecision {
+    readonly mb: number;
+    /** What set the size. */
+    readonly limitedBy: MemoryLimit;
+    /** What it would have been without looking at the commit (the old rule). */
+    readonly withoutCommitMb: number;
+    /** The inputs of the refusal, when mb is below the minimum. */
+    readonly freeMb: number;
+    readonly commitAvailableMb: number | null;
+}
+/**
+ * "auto" (pure): free RAM minus the reserve, never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM,
+ * and, when the PC's available commit (RAM plus paging file, what the sandbox's memory is charged against) is known,
+ * never more than that minus the reserve either.
+ */
+export declare function decideMemory(sandbox: SandboxSettings, freeMb: number, totalMb: number, commitAvailableMb: number | null): MemoryDecision;
+/**
+ * The most memory everything the agents start may use together (pure): the sandbox's memory minus the headroom
+ * ("auto" =
+ * the larger of 2048 MB and 10 %), at least half of it so a tiny sandbox still works; null = no limit ("none").
+ */
+export declare function agentMemoryLimitMb(memoryMb: number, headroom: SandboxSettings['agentMemoryHeadroomMb']): number | null;
+/** A plain-words note when the commit made the sandbox's memory much smaller (2 GB or more) than free RAM allowed. */
+export declare function memoryNote(decision: MemoryDecision): string | null;
+/** "auto": see decideMemory. commitAvailableMb: from HostTools memory-status (omitted = not checked). */
+export declare function resolveMemoryMb(sandbox: SandboxSettings, freeMemoryBytes?: number, totalMemoryBytes?: number, commitAvailableMb?: number | null): number;
 export {};

package/dist/host/launch/wsb-file.js

@@ -1,56 +1,75 @@
-// The .wsb file Windows Sandbox starts from: memory, devices and the folders mapped in.
+// The guest's fixed folders, and how much memory the sandbox gets.
 import os from 'node:os';
-import { fail, xmlEscape } from '../../core/util/index.js';
-import { MIRROR_ROOT, sandboxFolder } from '../../shared/paths/index.js';
+import { fail } from '../../core/util/index.js';
+import { MIRROR_ROOT } from '../../shared/paths/index.js';
 export const GUEST = {
     launch: 'C:\\AgentLaunch',
     data: 'C:\\AgentData',
     hostTools: 'C:\\HostTools',
     mirror: MIRROR_ROOT,
 };
-/** The .wsb elements switched on or off by a sandbox setting, in the order Windows Sandbox expects them. */
-const DEVICES = [
-    ['vGPU', 'vGpu'],
-    ['Networking', 'networking'],
-    ['ClipboardRedirection', 'clipboard'],
-    ['AudioInput', 'audioInput'],
-    ['VideoInput', 'videoInput'],
-    ['PrinterRedirection', 'printerRedirection'],
-    ['ProtectedClient', 'protectedClient'],
-];
 const MB = 1048576;
 const MIN_AUTO_MEMORY_MB = 4096;
-function element(name, value) {
-    return '<' + name + '>' + value + '</' + name + '>';
+const roundDown = (mb) => Math.floor(mb / 1024) * 1024;
+/**
+ * "auto" (pure): free RAM minus the reserve, never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM,
+ * and, when the PC's available commit (RAM plus paging file, what the sandbox's memory is charged against) is known,
+ * never more than that minus the reserve either.
+ */
+export function decideMemory(sandbox, freeMb, totalMb, commitAvailableMb) {
+    const shareMb = Math.floor((totalMb * sandbox.maxMemoryPercent) / 100);
+    const byFree = freeMb - sandbox.reserveHostMb;
+    const byCommit = commitAvailableMb === null ? Infinity : commitAvailableMb - sandbox.reserveHostMb;
+    const candidates = [
+        ['max', sandbox.maxMemoryMb],
+        ['share', shareMb],
+        ['free', byFree],
+        ['commit', byCommit],
+    ];
+    const lowest = candidates.reduce((a, b) => (b[1] < a[1] ? b : a));
+    const withoutCommit = roundDown(Math.min(sandbox.maxMemoryMb, shareMb, byFree));
+    return { mb: roundDown(lowest[1]), limitedBy: lowest[0], withoutCommitMb: withoutCommit, freeMb, commitAvailableMb };
 }
-function toggle(value) {
-    return value ? 'Enable' : 'Disable';
+/**
+ * The most memory everything the agents start may use together (pure): the sandbox's memory minus the headroom
+ * ("auto" =
+ * the larger of 2048 MB and 10 %), at least half of it so a tiny sandbox still works; null = no limit ("none").
+ */
+export function agentMemoryLimitMb(memoryMb, headroom) {
+    if (headroom === 'none')
+        return null;
+    const keep = headroom === 'auto' ? Math.max(2048, Math.floor(memoryMb / 10)) : headroom;
+    return Math.max(Math.floor(memoryMb / 2), memoryMb - keep);
 }
-/** "auto": free RAM minus the reserve, but never more than maxMemoryMb or maxMemoryPercent of the PC's total RAM. */
-export function resolveMemoryMb(sandbox, freeMemoryBytes = os.freemem(), totalMemoryBytes = os.totalmem()) {
+/** A plain-words note when the commit made the sandbox's memory much smaller (2 GB or more) than free RAM allowed. */
+export function memoryNote(decision) {
+    if (decision.limitedBy !== 'commit' || decision.withoutCommitMb - decision.mb < 2048)
+        return null;
+    return ('The sandbox gets ' +
+        decision.mb / 1024 +
+        ' GB of memory instead of ' +
+        decision.withoutCommitMb / 1024 +
+        ' GB: this PC has only ' +
+        Math.floor((decision.commitAvailableMb ?? 0) / 1024) +
+        ' GB of memory (RAM plus paging file) left to hand out, and if it runs out Windows closes the sandbox. ' +
+        'A bigger Windows paging file, or closing other programs, gives it more.');
+}
+/** "auto": see decideMemory. commitAvailableMb: from HostTools memory-status (omitted = not checked). */
+export function resolveMemoryMb(sandbox, freeMemoryBytes = os.freemem(), totalMemoryBytes = os.totalmem(), commitAvailableMb = null) {
     if (sandbox.memoryMb !== 'auto')
         return sandbox.memoryMb;
-    const freeMb = Math.floor(freeMemoryBytes / MB);
-    const shareMb = Math.floor(((totalMemoryBytes / MB) * sandbox.maxMemoryPercent) / 100);
-    const rounded = Math.floor(Math.min(sandbox.maxMemoryMb, shareMb, freeMb - sandbox.reserveHostMb) / 1024) * 1024;
-    if (rounded < MIN_AUTO_MEMORY_MB)
-        fail('Not enough free RAM for the sandbox (' +
-            freeMb +
-            ' MB free, ' +
-            sandbox.reserveHostMb +
-            ' MB kept for this PC).', 'Close some apps, lower sandbox.reserveHostMb, or set sandbox.memoryMb to a fixed value (>= 4096).');
-    return rounded;
-}
-export function buildWsb(config, memoryMb, mappings) {
-    const s = config.sandbox;
-    // Guest paths on other drive letters (F:\x) really live under C:\Mirror\F; bootstrap.ps1 substs F: onto it at boot.
-    const folders = mappings
-        .map((m) => element('MappedFolder', element('HostFolder', xmlEscape(m.host)) +
-        element('SandboxFolder', xmlEscape(sandboxFolder(m.guest))) +
-        element('ReadOnly', String(m.readOnly))))
-        .join('');
-    return element('Configuration', element('MemoryInMB', String(memoryMb)) +
-        DEVICES.map(([name, setting]) => element(name, toggle(s[setting]))).join('') +
-        element('MappedFolders', folders) +
-        element('LogonCommand', element('Command', xmlEscape(GUEST.launch + '\\sandbox\\boot\\logon.cmd'))));
+    const decision = decideMemory(sandbox, Math.floor(freeMemoryBytes / MB), Math.floor(totalMemoryBytes / MB), commitAvailableMb);
+    if (decision.mb < MIN_AUTO_MEMORY_MB)
+        fail(decision.limitedBy === 'commit'
+            ? 'Not enough memory left on this PC for the sandbox (' +
+                decision.commitAvailableMb +
+                ' MB of RAM plus paging file left, ' +
+                sandbox.reserveHostMb +
+                ' MB kept for this PC).'
+            : 'Not enough free RAM for the sandbox (' +
+                decision.freeMb +
+                ' MB free, ' +
+                sandbox.reserveHostMb +
+                ' MB kept for this PC).', 'Close some apps, enlarge the Windows paging file, lower sandbox.reserveHostMb, or set sandbox.memoryMb to a fixed value (>= 4096).');
+    return decision.mb;
 }

package/dist/host/life/crash-report.d.ts

@@ -1,9 +1,35 @@
 import { type StopCause, type StopEvent } from './stop-events.js';
+/** A crash dump Windows left (name and time only; never read). */
+export interface DumpFile {
+    readonly name: string;
+    readonly at: string;
+}
+/** Extra evidence for the report (all optional): this PC's own memory log lines and the dumps found. */
+export interface CrashExtra {
+    readonly hostMemoryLog?: string;
+    readonly dumps?: readonly DumpFile[];
+    readonly hostMemoryNow?: string;
+    /** The frozen sandbox's launch had vGPU on (read from its .wsb). */
+    readonly vgpu?: boolean;
+}
+/** "This PC stopped responding at X and was restarted at Y (n minutes later)", or null when there was no long gap. */
+export declare function freezeLine(cause: StopCause, lastSeen: string): string | null;
+/** What each kind of event usually means, one line per kind that appears (pure). */
+export declare function findingLines(events: readonly StopEvent[]): string[];
+/** Crash dumps in these folders newer than `since`: names and times only. */
+export declare function findDumps(dirs: readonly string[], since: Date): DumpFile[];
+/** Whether the newest launch started at or before `lastSeen` had vGPU on (host-only .wsb in <storage>\launches). */
+export declare function launchHadVgpu(storageRoot: string, lastSeen: string): boolean;
 /**
  * The report text (pure): what happened (the sandbox's or this PC's stop code, where the dump is) and the memory log's
  * last lines. `memoryLog` is the sandbox's own file, so it is shown through safeText.
  */
-export declare function crashReportText(cause: StopCause, events: readonly StopEvent[], memoryLog: string, lastSeen: string): string;
+export declare function crashReportText(cause: StopCause, events: readonly StopEvent[], memoryLog: string, lastSeen: string, extra?: CrashExtra): string;
+/** The newest crash report in <storage>\logs\crashes (at most 64 KB of it), or null. */
+export declare function newestCrashReport(storageRoot: string): {
+    file: string;
+    text: string;
+} | null;
 /**
  * When the sandbox ended in a crash (its own, this PC's, power, low memory): writes the report and returns its path.
  */