windows-development-sandbox 1.5.0 → 1.9.0

package/dist/host/launch/stage.js

@@ -26,7 +26,7 @@ export function stageScripts(target, scripts) {
         fs.copyFileSync(script, path.join(target, '90-extra-' + index + '-' + path.basename(script)));
     });
 }
-export const RUNTIME_FILES = ['main.js', 'daemon.js', 'view.js', 'gitguard.js', 'db.js', 'netproxy.js'];
+export const RUNTIME_FILES = ['main.js', 'daemon.js', 'view.js', 'gitguard.js', 'db.js', 'netproxy.js', 'agent.js'];
 /** The bundled sandbox runtime (dist/runtime: one self-contained file per entry point) and the sandbox/ scripts. */
 export function copyRuntime(packageRoot, launchPath) {
     const runtime = path.join(packageRoot, 'dist', 'runtime');

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.
  */

package/dist/host/life/crash-report.js

@@ -3,19 +3,137 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { assertNoLinks, safeText } from '../../core/util/index.js';
-import { explainStop, readStopEvents } from './stop-events.js';
+import { vgpuWarning } from '../launch/risk-notes.js';
+import { hostMemoryLine, readHostMemory } from './host-memory.js';
+import { hostDataFolder, hostDataRoot } from '../storage/index.js';
+import { bugcheckCode, explainStop, readStopEvents } from './stop-events.js';
 const KEEP_REPORTS = 20;
 const MEMORY_TAIL_BYTES = 16 * 1024;
+/** A gap longer than this between "last seen running" and the restart means the PC stopped responding first. */
+const FREEZE_GAP_MS = 5 * 60 * 1000;
 function crashDir(storageRoot) {
     return path.join(storageRoot, 'logs', 'crashes');
 }
+/** "This PC stopped responding at X and was restarted at Y (n minutes later)", or null when there was no long gap. */
+export function freezeLine(cause, lastSeen) {
+    if (cause.kind !== 'crash')
+        return null;
+    const gap = Date.parse(cause.at) - Date.parse(lastSeen);
+    if (!Number.isFinite(gap) || gap <= FREEZE_GAP_MS)
+        return null;
+    return ('This PC stopped responding at ' +
+        lastSeen +
+        ' (the last time anything was seen running) and was restarted at ' +
+        cause.at +
+        ' (' +
+        Math.round(gap / 60000) +
+        ' minutes later).');
+}
+/** What each kind of event usually means, one line per kind that appears (pure). */
+export function findingLines(events) {
+    const lines = [];
+    const has = (pred) => events.find(pred);
+    const lower = (e) => e.provider.toLowerCase();
+    const resource = has((e) => e.id === 2004 && lower(e).includes('resource-exhaustion'));
+    if (resource)
+        lines.push('Resource-Exhaustion-Detector 2004: memory ran out (RAM plus paging file). Programs were using too much at once.');
+    const bug = has((e) => e.id === 1001 && lower(e).includes('systemerrorreporting'));
+    const bugCode = bug ? /bugcheck was:\s*(0x[0-9a-f]{1,8})/i.exec(bug.process)?.[1] : undefined;
+    const power = has((e) => e.id === 41 && lower(e).includes('kernel-power'));
+    const powerCode = power ? bugcheckCode(power.process) : null;
+    if (bug || powerCode)
+        lines.push('Blue screen with stop code ' +
+            (bugCode ?? powerCode) +
+            ': search that code on Microsoft Learn; drivers, memory or hardware are the usual causes.');
+    else if (power)
+        lines.push('Kernel-Power 41 without a stop code: the PC froze, lost power or was reset by hand, with no blue screen.');
+    if (has((e) => lower(e).includes('whea-logger')))
+        lines.push('WHEA-Logger: Windows reported a hardware error (CPU, memory, a bus or a disk): heat or failing hardware.');
+    if (has((e) => lower(e).startsWith('hyper-v')))
+        lines.push("Hyper-V events: the sandbox's virtual machine (or the service that runs it) reported a problem.");
+    if (has((e) => /^(application error|windows error reporting)$/i.test(e.provider)))
+        lines.push("A crash report names vmwp.exe or vmmem, the programs that hold the sandbox's VM.");
+    return lines;
+}
+/** Crash dumps in these folders newer than `since`: names and times only. */
+export function findDumps(dirs, since) {
+    const found = [];
+    for (const dir of dirs) {
+        try {
+            for (const name of fs.readdirSync(dir)) {
+                if (!/\.dmp$/i.test(name))
+                    continue;
+                const stat = fs.lstatSync(path.join(dir, name));
+                if (stat.isFile() && stat.mtime >= since)
+                    found.push({ name: path.join(dir, name), at: stat.mtime.toISOString() });
+            }
+        }
+        catch {
+            // No such folder, or no access: no dumps to list.
+        }
+    }
+    return found.sort((a, b) => a.at.localeCompare(b.at)).slice(0, 10);
+}
+/** Whether the newest launch started at or before `lastSeen` had vGPU on (host-only .wsb in <storage>\launches). */
+export function launchHadVgpu(storageRoot, lastSeen) {
+    try {
+        const root = path.join(storageRoot, 'launches');
+        const limit = Date.parse(lastSeen) + 60 * 1000;
+        const newest = fs
+            .readdirSync(root)
+            .map((name) => ({ name, at: fs.lstatSync(path.join(root, name)).mtimeMs }))
+            .filter((l) => l.at <= limit)
+            .sort((a, b) => b.at - a.at)[0];
+        if (!newest)
+            return false;
+        const dir = path.join(root, newest.name);
+        const wsb = fs.readdirSync(dir).find((f) => f.endsWith('.wsb'));
+        return wsb
+            ? /<VGpu>\s*Enable\s*<\/VGpu>/i.test(fs.readFileSync(path.join(dir, wsb), 'utf8').slice(0, 65536))
+            : false;
+    }
+    catch {
+        // No launch folder to read: unknown, so nothing is claimed.
+        return false;
+    }
+}
+/** A tail of this PC's own memory log (written by the watcher), without following links. */
+function hostMemoryTail(storageRoot, dataPath) {
+    try {
+        const file = path.join(storageRoot, 'logs', 'host-memory-' + path.basename(dataPath) + '.log');
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile())
+            return '';
+        const length = Math.min(stat.size, MEMORY_TAIL_BYTES);
+        const fd = fs.openSync(file, 'r');
+        try {
+            const buffer = Buffer.alloc(length);
+            fs.readSync(fd, buffer, 0, length, stat.size - length);
+            return buffer.toString('utf8');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * 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 function crashReportText(cause, events, memoryLog, lastSeen) {
-    const eventLines = events.length
-        ? events.map((e) => '  ' + e.at + '  ' + e.provider + ' ' + e.id + (e.process ? ': ' + e.process.replace(/\s+/g, ' ') : ''))
+export function crashReportText(cause, events, memoryLog, lastSeen, extra = {}) {
+    const seen = new Set();
+    const unique = events.filter((e) => {
+        const key = e.at + '|' + e.id + '|' + e.provider;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const eventLines = unique.length
+        ? unique.map((e) => '  ' + e.at + '  ' + e.provider + ' ' + e.id + (e.process ? ': ' + e.process.replace(/\s+/g, ' ') : ''))
         : ['  (none)'];
     const memoryLines = memoryLog
         ? memoryLog
@@ -24,23 +142,63 @@ export function crashReportText(cause, events, memoryLog, lastSeen) {
             .slice(-30)
             .map((l) => '  ' + safeText(l))
         : ['  (none found)'];
+    const hostLines = (extra.hostMemoryLog ?? '')
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .slice(-20)
+        .map((l) => '  ' + safeText(l));
+    const freeze = freezeLine(cause, lastSeen);
+    const meaning = findingLines(unique);
+    const dumps = extra.dumps ?? [];
+    const vgpu = extra.vgpu ? ['vGPU was on for this sandbox. ' + vgpuWarning('its launch settings'), ''] : [];
     return [
         'Sandbox crash report, written ' + new Date().toISOString(),
         'What happened: ' + cause.text + ' at ' + cause.at + ' (the sandbox was last seen running at ' + lastSeen + ').',
+        ...(freeze ? [freeze] : []),
         '',
         'Windows events around then:',
         ...eventLines,
         '',
+        ...vgpu,
+        'What that usually means:',
+        ...(meaning.length ? meaning.map((l) => '  ' + l) : ['  (no memory, blue screen or hardware event was logged)']),
+        '',
+        'Crash dumps Windows left (C:\\Windows\\Minidump, MEMORY.DMP):',
+        ...(dumps.length ? dumps.map((d) => '  ' + d.name + '  ' + d.at) : ['  (none from that time)']),
+        '',
+        "This PC's memory while the sandbox ran (host-memory log):",
+        ...(hostLines.length ? hostLines : ['  (none: the background sync was not running)']),
+        ...(extra.hostMemoryNow ? ['  after the restart: ' + extra.hostMemoryNow] : []),
+        '',
         "The sandbox's memory log, last lines (C:\\AgentData\\logs\\memory-*.log inside it):",
         ...memoryLines,
         '',
     ].join('\n');
 }
+/** The newest crash report in <storage>\logs\crashes (at most 64 KB of it), or null. */
+export function newestCrashReport(storageRoot) {
+    try {
+        const dir = crashDir(storageRoot);
+        const newest = fs
+            .readdirSync(dir)
+            .filter((f) => /^crash-.*\.txt$/.test(f))
+            .sort()
+            .pop();
+        if (!newest)
+            return null;
+        const file = path.join(dir, newest);
+        return { file, text: safeText(fs.readFileSync(file, 'utf8').slice(0, 64 * 1024)) };
+    }
+    catch {
+        // No reports folder: none yet.
+        return null;
+    }
+}
 /** The newest memory log the sandbox wrote, last 16 KB at most, without following links in the data folder. */
 function memoryLogTail(dataPath) {
     try {
-        const logs = path.join(dataPath, 'logs');
-        assertNoLinks(dataPath, logs);
+        const logs = hostDataFolder(dataPath, 'logs');
+        assertNoLinks(hostDataRoot(dataPath), logs);
         const newest = fs
             .readdirSync(logs)
             .filter((f) => /^memory-\d{8}-\d{6}\.log$/.test(f))
@@ -78,7 +236,15 @@ export function saveCrashReport(storageRoot, dataPath, lastSeen) {
     const dir = crashDir(storageRoot);
     fs.mkdirSync(dir, { recursive: true });
     const file = path.join(dir, 'crash-' + cause.at.replace(/[:.]/g, '-') + '.txt');
-    fs.writeFileSync(file, crashReportText(cause, events, memoryLogTail(dataPath), lastSeen));
+    const since = new Date(Date.parse(lastSeen) - 10 * 60 * 1000);
+    const windir = process.env.SystemRoot ?? 'C:\\Windows';
+    const memoryNow = readHostMemory(storageRoot);
+    fs.writeFileSync(file, crashReportText(cause, events, memoryLogTail(dataPath), lastSeen, {
+        hostMemoryLog: hostMemoryTail(storageRoot, dataPath),
+        vgpu: launchHadVgpu(storageRoot, lastSeen),
+        dumps: findDumps([path.join(windir, 'Minidump'), windir], since),
+        ...(memoryNow ? { hostMemoryNow: hostMemoryLine(memoryNow) } : {}),
+    }));
     for (const old of fs
         .readdirSync(dir)
         .filter((f) => f.startsWith('crash-'))

package/dist/host/life/host-memory.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const HostMemorySchema: z.ZodObject<{
+    totalMb: z.ZodNumber;
+    availableMb: z.ZodNumber;
+    commitLimitMb: z.ZodNumber;
+    commitAvailableMb: z.ZodNumber;
+    pageFile: z.ZodCatch<z.ZodEnum<{
+        auto: "auto";
+        none: "none";
+        fixed: "fixed";
+    }>>;
+    pageFileMaxMb: z.ZodCatch<z.ZodNumber>;
+}, z.core.$strip>;
+export type HostMemory = z.output<typeof HostMemorySchema>;
+/** The parsed answer of memory-status, or null (not Windows, unreadable, nonsense). */
+export declare function parseHostMemory(text: string): HostMemory | null;
+/** This PC's memory now, or null when it cannot be read (and always during the self-test: it never asks Windows). */
+export declare function readHostMemory(storageRoot: string): HostMemory | null;
+/** The same without blocking: for the watcher, which must never wait on it. */
+export declare function readHostMemoryAsync(storageRoot: string): Promise<HostMemory | null>;
+/** How low this PC's memory is: what the host watchdog acts on (pure). */
+export interface HostPressure {
+    readonly low: boolean;
+    /** Plain words for the log and the sandbox. */
+    readonly reason: string;
+}
+/** Low = available commit under half the reserve, or available RAM under 2 GB. */
+export declare function hostPressure(memory: HostMemory, reserveHostMb: number): HostPressure;
+/** One line for the host memory log. */
+export declare function hostMemoryLine(memory: HostMemory, at?: Date): string;
+/**
+ * Whether Windows Sandbox could push this PC past its commit limit (pure): the paging file is fixed or off and the
+ * commit limit leaves less than the sandbox's memory plus what this PC already uses. Null when all is well.
+ */
+export declare function pageFileRisk(memory: HostMemory, sandboxMb: number): {
+    neededGb: number;
+    text: string;
+} | null;
+/** Whether the page file hint may be shown now (once a day at most); records that it was. */
+export declare function takePageFileHint(storageRoot: string, now?: Date): boolean;

package/dist/host/life/host-memory.js

@@ -0,0 +1,137 @@
+// This PC's memory (RAM and commit) for sizing the sandbox, the host watchdog and the doctor. HostTools.exe
+// memory-status reads it (built in <storage>\bin), else native\scripts\memory-status.ps1. Windows Sandbox takes its
+// memory from this PC as it goes (the setting is a ceiling, not a reservation), so what decides "slow or closed" is the
+// PC's commit limit (RAM plus paging files), not only free RAM.
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { isWin } from '../../core/util/index.js';
+import { SYSTEM } from '../../shared/system.js';
+import { hostToolsExe, nativeScript } from '../native.js';
+import { selfTestRunning } from '../test-guard.js';
+export const HostMemorySchema = z.object({
+    totalMb: z.number().int().nonnegative(),
+    availableMb: z.number().int().nonnegative(),
+    commitLimitMb: z.number().int().nonnegative(),
+    commitAvailableMb: z.number().int().nonnegative(),
+    /** How the paging file is set up: Windows manages it, a fixed size, or none. */
+    pageFile: z.enum(['auto', 'fixed', 'none']).catch('auto'),
+    /** Fixed: the total of its maximum sizes (MB). */
+    pageFileMaxMb: z.number().int().nonnegative().catch(0),
+});
+const TIMEOUT_MS = 20000;
+/** The parsed answer of memory-status, or null (not Windows, unreadable, nonsense). */
+export function parseHostMemory(text) {
+    try {
+        const parsed = HostMemorySchema.safeParse(JSON.parse(text));
+        return parsed.success && parsed.data.totalMb > 0 ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+function command(storageRoot) {
+    const tools = hostToolsExe(storageRoot);
+    return tools
+        ? { file: tools, args: ['memory-status'] }
+        : { file: SYSTEM.powershell(), args: nativeScript('memory-status.ps1') };
+}
+/** This PC's memory now, or null when it cannot be read (and always during the self-test: it never asks Windows). */
+export function readHostMemory(storageRoot) {
+    if (!isWin || selfTestRunning())
+        return null;
+    const { file, args } = command(storageRoot);
+    const result = spawnSync(file, args, { encoding: 'utf8', windowsHide: true, timeout: TIMEOUT_MS });
+    return parseHostMemory(result.stdout || '');
+}
+/** The same without blocking: for the watcher, which must never wait on it. */
+export function readHostMemoryAsync(storageRoot) {
+    if (!isWin || selfTestRunning())
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        try {
+            const { file, args } = command(storageRoot);
+            const child = spawn(file, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+            let out = '';
+            child.stdout.on('data', (d) => (out += d.toString('utf8').slice(0, 4096)));
+            const timer = setTimeout(() => child.kill(), TIMEOUT_MS);
+            child.on('error', () => resolve(null));
+            child.on('close', () => {
+                clearTimeout(timer);
+                resolve(parseHostMemory(out));
+            });
+        }
+        catch {
+            // Could not even start it: no answer this time.
+            resolve(null);
+        }
+    });
+}
+/** Low = available commit under half the reserve, or available RAM under 2 GB. */
+export function hostPressure(memory, reserveHostMb) {
+    if (memory.commitAvailableMb < reserveHostMb / 2)
+        return {
+            low: true,
+            reason: 'this PC has only ' + memory.commitAvailableMb + ' MB of memory (RAM plus paging file) left to hand out',
+        };
+    if (memory.availableMb < 2048)
+        return { low: true, reason: 'this PC has only ' + memory.availableMb + ' MB of free RAM left' };
+    return { low: false, reason: '' };
+}
+/** One line for the host memory log. */
+export function hostMemoryLine(memory, at = new Date()) {
+    return (at.toISOString() +
+        ' | RAM free/total MB ' +
+        memory.availableMb +
+        '/' +
+        memory.totalMb +
+        ' | commit free/limit MB ' +
+        memory.commitAvailableMb +
+        '/' +
+        memory.commitLimitMb +
+        ' | page file ' +
+        memory.pageFile);
+}
+/**
+ * Whether Windows Sandbox could push this PC past its commit limit (pure): the paging file is fixed or off and the
+ * commit limit leaves less than the sandbox's memory plus what this PC already uses. Null when all is well.
+ */
+export function pageFileRisk(memory, sandboxMb) {
+    if (memory.pageFile === 'auto')
+        return null;
+    const inUseMb = memory.commitLimitMb - memory.commitAvailableMb;
+    const neededMb = inUseMb + sandboxMb;
+    if (memory.commitLimitMb >= neededMb)
+        return null;
+    // The commit limit is RAM plus the paging files: the paging file has to make up the difference.
+    const neededGb = Math.max(1, Math.ceil((neededMb - memory.totalMb) / 1024));
+    return {
+        neededGb,
+        text: 'Windows Sandbox takes its memory from this PC as it goes; if this PC runs out, Windows closes the sandbox instead of slowing it down. ' +
+            'Let Windows manage the page file size (System > Advanced system settings > Performance > Settings > Advanced > Virtual memory: "Automatically manage paging file size"), or make the page file at least ' +
+            neededGb +
+            ' GB.',
+    };
+}
+const HINT_EVERY_MS = 24 * 60 * 60 * 1000;
+/** Whether the page file hint may be shown now (once a day at most); records that it was. */
+export function takePageFileHint(storageRoot, now = new Date()) {
+    const file = path.join(storageRoot, 'run', 'pagefile-hint.txt');
+    try {
+        const last = Number(fs.readFileSync(file, 'utf8'));
+        if (Number.isFinite(last) && now.getTime() - last < HINT_EVERY_MS)
+            return false;
+    }
+    catch {
+        // Never shown: show it.
+    }
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, String(now.getTime()));
+    }
+    catch {
+        // Cannot record it: showing it again next time is fine.
+    }
+    return true;
+}

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

@@ -5,3 +5,5 @@ export * from './keep-awake.js';
 export * from './windows-update.js';
 export * from './crash-report.js';
 export * from './session-ledger.js';
+export * from './host-memory.js';
+export * from './watchdog.js';

package/dist/host/life/index.js

@@ -5,3 +5,5 @@ export * from './keep-awake.js';
 export * from './windows-update.js';
 export * from './crash-report.js';
 export * from './session-ledger.js';
+export * from './host-memory.js';
+export * from './watchdog.js';

package/dist/host/life/stop-events.d.ts

@@ -12,6 +12,8 @@ export interface StopCause {
     at: string;
     text: string;
 }
+/** The stop code in Kernel-Power 41's detail ("BugcheckCode 209" -> "0xD1"); null for 0 (no blue screen). */
+export declare function bugcheckCode(detail: string): string | null;
 /**
  * The first event that ends a running sandbox (pure): Windows inside the sandbox crashing (Hyper-V 18590; `process`
  * holds its message with the stop code), a restart or shutdown, a crash or power loss, sleep, low memory. Switching