windows-development-sandbox 1.7.0 → 1.10.0

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,41 @@
+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>;
+    diskQueue: z.ZodCatch<z.ZodOptional<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,140 @@
+// 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),
+    /** The disks' queue length now (all disks together); absent when this PC has no such counter. */
+    diskQueue: z.number().nonnegative().max(100000).optional().catch(undefined),
+});
+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 +
+        (memory.diskQueue === undefined ? '' : ' | disk queue ' + memory.diskQueue));
+}
+/**
+ * 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

package/dist/host/life/stop-events.js

@@ -12,12 +12,17 @@ const StopEventsSchema = z
     provider: z.string().max(200),
     process: z
         .string()
-        .max(400)
+        .max(1600)
         .nullable()
         .transform((p) => p ?? ''),
 }))
     .max(100);
 const UPDATERS = /^(trustedinstaller|mousocoreworker|musnotification(ux)?|usoclient|wuauclt|tiworker|updateorchestrator)\.exe$/i;
+/** The stop code in Kernel-Power 41's detail ("BugcheckCode 209" -> "0xD1"); null for 0 (no blue screen). */
+export function bugcheckCode(detail) {
+    const n = Number(/BugcheckCode\s+(\d+)/.exec(detail)?.[1] ?? 0);
+    return n > 0 ? '0x' + n.toString(16).toUpperCase() : 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
@@ -41,12 +46,24 @@ export function explainStop(events) {
                     },
                 ];
         }
-        if ((e.id === 41 && p.includes('kernel-power')) || (e.id === 6008 && p.includes('eventlog')))
+        if (e.id === 41 && p.includes('kernel-power')) {
+            const code = bugcheckCode(e.process);
+            return [
+                {
+                    kind: 'crash',
+                    at: e.at,
+                    text: code
+                        ? 'this PC blue-screened (stop code ' + code + ')'
+                        : 'Windows stopped unexpectedly (a freeze, a crash, a power cut, or the power button held down)',
+                },
+            ];
+        }
+        if (e.id === 6008 && p.includes('eventlog'))
             return [
                 {
                     kind: 'crash',
                     at: e.at,
-                    text: 'Windows stopped unexpectedly (a crash, a power cut, or the power button held down)',
+                    text: 'Windows stopped unexpectedly (a freeze, a crash, a power cut, or the power button held down)',
                 },
             ];
         if (e.id === 42 && p.includes('kernel-power'))

package/dist/host/life/stop-warning.js

@@ -1,7 +1,7 @@
 const ADVICE = {
     updates: 'Before leaving agents overnight, restart for pending updates first or pause them (Settings > Windows Update > Pause updates).',
     restart: 'If that was not you, check Settings > Windows Update and Event Viewer > Windows Logs > System.',
-    crash: 'Event Viewer > Windows Logs > System has the details; a laptop also needs to stay plugged in.',
+    crash: 'sandbox logs --crash prints what Windows logged and how much memory this PC had; Event Viewer > Windows Logs > System has the rest. A laptop also needs to stay plugged in.',
     sleep: 'sandbox.keepAwake keeps this PC awake while a sandbox runs (closing a laptop lid still sleeps it). Check it is on, and that sleep is not forced by a policy.',
     sandboxCrash: 'C:\\AgentData\\logs\\memory-*.log shows what used memory just before. Fewer builds at once inside the sandbox (e.g. cargo build.jobs) makes it less likely.',
     memory: 'Give the sandbox less RAM (sandbox.maxMemoryMb, sandbox.reserveHostMb) or run fewer builds at once inside it.',

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

@@ -0,0 +1,56 @@
+import type os from 'node:os';
+import { type HostThresholds, type LoadProfile } from '../../shared/memory/index.js';
+import { type HostMemory } from './host-memory.js';
+export interface WatchdogState {
+    readonly low: boolean;
+    readonly calm: number;
+    /** Seconds the CPU has been above the limit. */
+    readonly cpuHighSeconds: number;
+    /** Seconds the disk queue has been above the limit. */
+    readonly diskHighSeconds: number;
+    /** Time (ms) the last request went out. */
+    readonly lastSentAt: number;
+}
+export declare const WATCHDOG_START: WatchdogState;
+/** The request is repeated this often while the PC stays low, and each one lasts a bit longer than that. */
+export declare const RESEND_MS = 30000;
+export declare const REQUEST_SECONDS = 90;
+export interface WatchdogInput {
+    /** Null when memory could not be read this time (only the CPU counts then). */
+    readonly memory: HostMemory | null;
+    /** Total CPU use since the last sample (percent), null when unknown. */
+    readonly cpuPercent: number | null;
+    readonly intervalSeconds: number;
+    readonly nowMs: number;
+    readonly reserveHostMb: number;
+    readonly profile: LoadProfile;
+}
+export interface WatchdogStep {
+    readonly state: WatchdogState;
+    /** Send a request to the sandbox now. */
+    readonly send: boolean;
+    /** Why the PC is low (plain words), empty when it is not. */
+    readonly reason: string;
+    /** The state changed (the log says so). */
+    readonly changed: boolean;
+}
+/**
+ * Why this PC counts as low, for these numbers ("" when it does not). Low = available RAM under max(4 GB, 12 % of RAM)
+ * or available commit under 15 % of the commit limit or half the reserve (the gentle profile: 6 GB, 15 %, 20 %).
+ * `scale` widens the limits (1.25 = the level it must climb back above).
+ */
+export declare function lowReason(memory: HostMemory, reserveHostMb: number, t: HostThresholds, scale: number): string;
+/** One watchdog step. Hysteresis: low starts at the limits and ends above 1.25 times them for calmSamples samples. */
+export declare function watchdogStep(prev: WatchdogState, input: WatchdogInput): WatchdogStep;
+/** Total CPU use between two os.cpus() readings (percent). */
+export declare function cpuPercentBetween(a: readonly os.CpuInfo[], b: readonly os.CpuInfo[]): number | null;
+/** One line in <storage>\logs\host-memory-<data>.log, which the crash report reads; the file is kept small. */
+export declare function appendHostMemory(file: string, memory: HostMemory, cpuPercent: number | null): void;
+/** What the launch decided for the watchdog (host-only, in <storage>\run): the load profile and the PC's reserve. */
+export interface LoadSettings {
+    readonly profile: LoadProfile;
+    readonly reserveHostMb: number;
+}
+export declare function writeLoadSettings(storageRoot: string, dataPath: string, settings: LoadSettings): void;
+/** The settings of the running launch; the defaults (normal profile, 8 GB reserve) when none were written. */
+export declare function readLoadSettings(storageRoot: string, dataPath: string): LoadSettings;

package/dist/host/life/watchdog.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import fs from 'node:fs';
+import path from 'node:path';
+import { HOST_THRESHOLDS } from '../../shared/memory/index.js';
+import { hostMemoryLine } from './host-memory.js';
+export const WATCHDOG_START = {
+    low: false,
+    calm: 0,
+    cpuHighSeconds: 0,
+    diskHighSeconds: 0,
+    lastSentAt: 0,
+};
+/** The request is repeated this often while the PC stays low, and each one lasts a bit longer than that. */
+export const RESEND_MS = 30000;
+export const REQUEST_SECONDS = 90;
+/**
+ * Why this PC counts as low, for these numbers ("" when it does not). Low = available RAM under max(4 GB, 12 % of RAM)
+ * or available commit under 15 % of the commit limit or half the reserve (the gentle profile: 6 GB, 15 %, 20 %).
+ * `scale` widens the limits (1.25 = the level it must climb back above).
+ */
+export function lowReason(memory, reserveHostMb, t, scale) {
+    const availableLimit = Math.max(t.availableMinMb, (memory.totalMb * t.availablePercent) / 100) * scale;
+    if (memory.availableMb < availableLimit)
+        return 'only ' + memory.availableMb + " MB of this PC's RAM is free";
+    const commitLimit = Math.max((memory.commitLimitMb * t.commitAvailablePercent) / 100, reserveHostMb / 2) * scale;
+    if (memory.commitAvailableMb < commitLimit)
+        return 'only ' + memory.commitAvailableMb + ' MB of memory (RAM plus paging file) is left on this PC';
+    return '';
+}
+/** One watchdog step. Hysteresis: low starts at the limits and ends above 1.25 times them for calmSamples samples. */
+export function watchdogStep(prev, input) {
+    const t = HOST_THRESHOLDS[input.profile];
+    let reason = '';
+    if (input.memory)
+        reason = lowReason(input.memory, input.reserveHostMb, t, 1);
+    const cpuHigh = input.cpuPercent !== null && input.cpuPercent >= t.cpuPercent ? prev.cpuHighSeconds + input.intervalSeconds : 0;
+    if (!reason && cpuHigh >= t.cpuSeconds)
+        reason = "this PC's CPU has been above " + t.cpuPercent + '% for ' + cpuHigh + ' seconds';
+    const diskQueue = input.memory?.diskQueue;
+    const diskHigh = diskQueue !== undefined && diskQueue >= t.diskQueue ? prev.diskHighSeconds + input.intervalSeconds : 0;
+    if (!reason && diskHigh >= t.diskSeconds)
+        reason = "this PC's disks have had a queue of " + diskQueue + ' for ' + diskHigh + ' seconds';
+    const calmNow = input.memory ? lowReason(input.memory, input.reserveHostMb, t, 1.25) === '' : true;
+    let low = prev.low;
+    let calm = prev.calm;
+    if (reason) {
+        low = true;
+        calm = 0;
+    }
+    else if (prev.low) {
+        calm = calmNow && cpuHigh === 0 && diskHigh === 0 ? prev.calm + 1 : 0;
+        if (calm >= t.calmSamples) {
+            low = false;
+            calm = 0;
+        }
+    }
+    const send = low && input.nowMs - prev.lastSentAt >= RESEND_MS;
+    return {
+        state: {
+            low,
+            calm,
+            cpuHighSeconds: cpuHigh,
+            diskHighSeconds: diskHigh,
+            lastSentAt: send ? input.nowMs : prev.lastSentAt,
+        },
+        send,
+        reason: reason || (low ? 'this PC is still low' : ''),
+        changed: low !== prev.low,
+    };
+}
+/** Total CPU use between two os.cpus() readings (percent). */
+export function cpuPercentBetween(a, b) {
+    let busy = 0;
+    let total = 0;
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        const x = a[i].times;
+        const y = b[i].times;
+        const idle = y.idle - x.idle;
+        const all = y.user - x.user + (y.nice - x.nice) + (y.sys - x.sys) + (y.irq - x.irq) + idle;
+        busy += all - idle;
+        total += all;
+    }
+    return total > 0 ? Math.round((busy / total) * 100) : null;
+}
+const MAX_LOG_BYTES = 512 * 1024;
+/** One line in <storage>\logs\host-memory-<data>.log, which the crash report reads; the file is kept small. */
+export function appendHostMemory(file, memory, cpuPercent) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        try {
+            if (fs.statSync(file).size > MAX_LOG_BYTES)
+                fs.renameSync(file, file + '.old');
+        }
+        catch {
+            // No log yet.
+        }
+        fs.appendFileSync(file, hostMemoryLine(memory) + (cpuPercent === null ? '' : ' | CPU ' + cpuPercent + '%') + '\n');
+    }
+    catch {
+        // The log is a courtesy: never a reason to fail.
+    }
+}
+const LoadSettingsSchema = z.object({
+    profile: z.enum(['normal', 'gentle']),
+    reserveHostMb: z.number().int().nonnegative(),
+});
+function loadFile(storageRoot, dataPath) {
+    return path.join(storageRoot, 'run', 'load-' + path.basename(dataPath) + '.json');
+}
+export function writeLoadSettings(storageRoot, dataPath, settings) {
+    const file = loadFile(storageRoot, dataPath);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(settings));
+}
+/** The settings of the running launch; the defaults (normal profile, 8 GB reserve) when none were written. */
+export function readLoadSettings(storageRoot, dataPath) {
+    try {
+        return LoadSettingsSchema.parse(JSON.parse(fs.readFileSync(loadFile(storageRoot, dataPath), 'utf8')));
+    }
+    catch {
+        // Not written (an older launch) or damaged: the defaults.
+        return { profile: 'normal', reserveHostMb: 8192 };
+    }
+}