windows-development-sandbox 1.18.2 → 1.18.4

package/dist/host/life/last-end.js

@@ -0,0 +1,91 @@
+// What the sandbox did in its last seconds and how it ended, for the status page and the crash report. The sandbox's
+// daemon writes run\heartbeat.json every 10 seconds; when the sandbox vanishes, the last one is the best evidence.
+// The guest wrote it, so it is read through the schema, never through a link, and printed through safeText.
+import { assertNoLinks, safeText } from '../../core/util/index.js';
+import { RunDir, HeartbeatSchema } from '../../shared/channel/index.js';
+import { readValid } from '../../shared/io/index.js';
+import { hostDataRoot } from '../storage/index.js';
+/** The sandbox's last heartbeat, or null (none written, damaged, or reached through a link). */
+export function readHeartbeat(dataPath) {
+    try {
+        const root = hostDataRoot(dataPath);
+        const file = new RunDir(root).heartbeatFile;
+        assertNoLinks(root, file);
+        return readValid(HeartbeatSchema, file);
+    }
+    catch {
+        // A link or an unreadable folder: no evidence, never an error.
+        return null;
+    }
+}
+const clock = (iso) => {
+    const at = new Date(iso);
+    return Number.isNaN(at.getTime())
+        ? iso
+        : at.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit', hour12: false });
+};
+/** One line of what the sandbox was doing at its last heartbeat (pure; guest text goes through safeText). */
+export function heartbeatLine(hb) {
+    const top = hb.topProcesses.map((p) => safeText(p.name) + ' ' + p.privateMb + ' MB').join(', ');
+    return ('last seen inside at ' +
+        clock(hb.at) +
+        ': up ' +
+        Math.round(hb.uptimeS / 60) +
+        ' min, ' +
+        hb.ramFreePct +
+        '% RAM free, ' +
+        hb.commitPct +
+        '% commit used, builds at step ' +
+        hb.step +
+        (hb.hostStep > 0 ? ' (this PC asked for step ' + hb.hostStep + ')' : '') +
+        (hb.diskQueueReported !== undefined ? ', this PC disk queue ' + hb.diskQueueReported : '') +
+        (top ? '; biggest: ' + top : ''));
+}
+/** The likeliest reason, from the last heartbeat (pure). */
+export function guessReason(hb) {
+    if (hb && hb.diskQueueReported !== undefined && hb.hostStep > 0)
+        return "this PC's disks were overloaded (queue " + hb.diskQueueReported + ')';
+    if (hb && (hb.ramFreePct < 8 || hb.commitPct > 92))
+        return 'the sandbox was running out of memory';
+    return 'Windows stopped it (no reason was logged)';
+}
+/** A heartbeat older than this before the end is not "it was working when it went". */
+const FRESH_MS = 2 * 60 * 1000;
+/**
+ * The sandbox went and nothing was logged (pure): its last heartbeat is fresh, from this run, says it was working
+ * (a session running, or builds slowed down) and does not say it was shutting down in order, and nobody stopped it on
+ * purpose (`sandbox stop`, a restart). The guest cannot tell a closed window from a crash, so the wording says both.
+ */
+export function vanishedCause(hb, startedIso, closedOnPurpose, endedAtMs) {
+    if (!hb || closedOnPurpose || hb.phase === 'ending')
+        return null;
+    const seen = Date.parse(hb.at);
+    if (!Number.isFinite(seen) || seen < Date.parse(startedIso) - 60000 || endedAtMs - seen > FRESH_MS)
+        return null;
+    if (hb.phase !== 'working' && hb.step === 0 && hb.hostStep === 0)
+        return null;
+    return {
+        kind: 'vanished',
+        at: new Date(endedAtMs).toISOString(),
+        text: 'the sandbox ended suddenly while it was working (its window was closed, or it crashed: Windows logged nothing)',
+    };
+}
+/**
+ * How the last sandbox ended (pure): null when it was closed normally, or is still running. `heartbeat` only counts
+ * when it was written during that run.
+ */
+export function lastEndOf(life, heartbeat, running) {
+    if (!life || running)
+        return null;
+    if (life.ended && !life.ended.cause)
+        return null;
+    const hb = heartbeat && Date.parse(heartbeat.at) >= Date.parse(life.started) - 60000 ? heartbeat : null;
+    const at = life.ended?.at ?? life.lastSeen;
+    const why = life.ended?.cause ? safeText(life.ended.cause.text) : guessReason(hb);
+    return { at, text: 'ended unexpectedly ' + clock(at) + ': ' + why };
+}
+/** The status page's "Last sandbox" fact for this data folder. */
+export function readLastEnd(lifeRead, dataPath, running) {
+    const life = lifeRead();
+    return lastEndOf(life, life && !running ? readHeartbeat(dataPath) : null, running);
+}

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

@@ -14,6 +14,9 @@ declare const LifeSchema: z.ZodObject<{
                 sleep: "sleep";
                 memory: "memory";
                 sandboxCrash: "sandboxCrash";
+                gpu: "gpu";
+                hyperv: "hyperv";
+                vanished: "vanished";
             }>;
             at: z.ZodString;
             text: z.ZodString;

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

@@ -5,7 +5,7 @@
 import { z } from 'zod';
 import { JsonFile } from '../../shared/io/index.js';
 import { hostStateFile } from '../storage/index.js';
-import { causeSince, IsoSchema } from './stop-events.js';
+import { causeSince, IsoSchema, STOP_KINDS } from './stop-events.js';
 import { stopWarning } from './stop-warning.js';
 import { saveCrashReport } from './crash-report.js';
 const LifeSchema = z.object({
@@ -17,7 +17,7 @@ const LifeSchema = z.object({
         at: IsoSchema,
         cause: z
             .object({
-            kind: z.enum(['updates', 'restart', 'crash', 'sleep', 'memory', 'sandboxCrash']),
+            kind: z.enum(STOP_KINDS),
             at: IsoSchema,
             text: z.string().max(400),
         })

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

@@ -6,7 +6,9 @@ export interface StopEvent {
     provider: string;
     process: string;
 }
-export type StopKind = 'updates' | 'restart' | 'crash' | 'sleep' | 'memory' | 'sandboxCrash';
+/** The ways a sandbox can end that nobody asked for (the life record stores one of these). */
+export declare const STOP_KINDS: readonly ["updates", "restart", "crash", "sleep", "memory", "sandboxCrash", "gpu", "hyperv", "vanished"];
+export type StopKind = (typeof STOP_KINDS)[number];
 export interface StopCause {
     kind: StopKind;
     at: string;

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

@@ -17,6 +17,24 @@ const StopEventsSchema = z
         .transform((p) => p ?? ''),
 }))
     .max(100);
+/** The ways a sandbox can end that nobody asked for (the life record stores one of these). */
+export const STOP_KINDS = [
+    'updates',
+    'restart',
+    'crash',
+    'sleep',
+    'memory',
+    'sandboxCrash',
+    /** The graphics driver reset (display 4101, a GPU LiveKernelEvent): vGPU and the GPU's shared memory. */
+    'gpu',
+    /** Hyper-V reported an error, or a program that holds the VM (vmwp.exe, vmmem) crashed. */
+    'hyperv',
+    /** Nothing was logged, but the sandbox was working and left no word of leaving. */
+    'vanished',
+];
+/** Windows live kernel events that are a graphics driver (GPU) reset or timeout. */
+const GPU_LIVE_KERNEL = ['117', '141', '1a8'];
+const VM_PROGRAMS = /vmwp\.exe|vmmem\w*|vmcompute|windowssandbox\w*/i;
 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) {
@@ -85,6 +103,47 @@ export function explainStop(events) {
                 },
             ];
         }
+        // The graphics driver stopped responding and was reset: with vGPU the sandbox shares the GPU, so the VM goes too.
+        if (e.id === 4101 && p === 'display')
+            return [
+                {
+                    kind: 'gpu',
+                    at: e.at,
+                    text: 'the graphics driver stopped responding and was reset while the sandbox used the GPU (vGPU)',
+                },
+            ];
+        const programs = VM_PROGRAMS.exec(e.process)?.[0];
+        if (e.id === 1001 && p.includes('windows error reporting') && /LiveKernelEvent/i.test(e.process)) {
+            const code = /\bP1:\s*([0-9a-f]{2,4})\b/i.exec(e.process)?.[1]?.toLowerCase();
+            if (code && GPU_LIVE_KERNEL.includes(code))
+                return [
+                    {
+                        kind: 'gpu',
+                        at: e.at,
+                        text: 'the graphics driver reset (Windows live kernel event ' +
+                            code +
+                            ') while the sandbox used the GPU (vGPU)',
+                    },
+                ];
+        }
+        if ((e.id === 1000 || e.id === 1001) &&
+            programs &&
+            /^(application error|windows error reporting)$/i.test(e.provider))
+            return [
+                {
+                    kind: 'hyperv',
+                    at: e.at,
+                    text: 'a program that runs the sandbox VM (' + programs.toLowerCase() + ') crashed',
+                },
+            ];
+        if (/^microsoft-windows-hyper-v-(worker|vmswitch|compute)/.test(p) && e.id !== 18590 && e.id !== 40001)
+            return [
+                {
+                    kind: 'hyperv',
+                    at: e.at,
+                    text: 'Hyper-V, which runs the sandbox VM, reported an error (event ' + e.id + ')',
+                },
+            ];
         return [];
     });
     return causes.sort((a, b) => Date.parse(a.at) - Date.parse(b.at))[0] ?? null;

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

@@ -4,6 +4,9 @@ const ADVICE = {
     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.',
+    gpu: 'The graphics driver reset while the sandbox used the GPU (vGPU). Turn vGPU off (sandbox config set sandbox.vGpu false) or lower the GPU load, and keep heavy builds and a GPU game apart.',
+    hyperv: 'Hyper-V, which runs the sandbox, reported an error. Closing other virtual machines, updating the graphics driver, or turning vGPU off usually helps; sandbox logs --crash has the events.',
+    vanished: 'If you did not close its window, this is the known pattern of heavy builds plus a GPU game with vGPU on: turn vGPU off or run fewer builds at once. sandbox logs --crash says what it was doing in its last seconds.',
     memory: 'Give the sandbox less RAM (sandbox.maxMemoryMb, sandbox.reserveHostMb) or run fewer builds at once inside it.',
 };
 const when = (iso) => new Date(iso).toLocaleString(undefined, { weekday: 'short', hour: '2-digit', minute: '2-digit' });

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

@@ -10,6 +10,8 @@ export interface WatchdogState {
     readonly cpuHighSeconds: number;
     /** Seconds the disk queue has been above the limit. */
     readonly diskHighSeconds: number;
+    /** Seconds the disk queue has been at or above twice the limit (for the severe step). */
+    readonly diskSevereSeconds: number;
     /** Time (ms) the last request went out. */
     readonly lastSentAt: number;
 }

package/dist/host/life/watchdog.js

@@ -9,6 +9,7 @@ export const WATCHDOG_START = {
     calm: 0,
     cpuHighSeconds: 0,
     diskHighSeconds: 0,
+    diskSevereSeconds: 0,
     lastSentAt: 0,
 };
 /** The request is repeated this often while the PC stays low, and each one lasts a bit longer than that. */
@@ -50,8 +51,12 @@ export function watchdogStep(prev, input) {
         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;
+    const diskDouble = diskQueue !== undefined && diskQueue >= 2 * t.diskQueue ? prev.diskSevereSeconds + input.intervalSeconds : 0;
+    const diskSevere = diskDouble >= t.diskSeconds || diskHigh >= 3 * t.diskSeconds;
     if (!reason && diskHigh >= t.diskSeconds)
-        reason = "this PC's disks have had a queue of " + diskQueue + ' for ' + diskHigh + ' seconds';
+        reason = diskSevere
+            ? "this PC's disks are overloaded (queue " + diskQueue + ' for ' + diskHigh + ' seconds)'
+            : "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;
@@ -66,7 +71,7 @@ export function watchdogStep(prev, input) {
             calm = 0;
         }
     }
-    const severe = low && input.memory !== null && severeHost(input.memory);
+    const severe = low && ((input.memory !== null && severeHost(input.memory)) || diskSevere);
     // Getting severe is sent at once; otherwise the request is repeated every RESEND_MS while the PC stays low.
     const send = low && (input.nowMs - prev.lastSentAt >= RESEND_MS || (severe && !prev.severe));
     return {
@@ -76,6 +81,7 @@ export function watchdogStep(prev, input) {
             calm,
             cpuHighSeconds: cpuHigh,
             diskHighSeconds: diskHigh,
+            diskSevereSeconds: diskDouble,
             lastSentAt: send ? input.nowMs : prev.lastSentAt,
         },
         send,

package/dist/host/sandbox/cleanup.d.ts

@@ -0,0 +1,37 @@
+import { LEFTOVER_IMAGES, type SandboxFacts, type SandboxJudgement } from '../health/stale.js';
+/** taskkill arguments that end exactly these programs (pure). */
+export declare function killArgs(pids: readonly number[]): string[];
+/** Ends these Windows Sandbox programs (taskkill by absolute path). Returns false when taskkill failed. */
+export declare function endSandboxPrograms(pids: readonly number[]): boolean;
+/** Restarts the Windows Sandbox service (CmService) in an elevated PowerShell: Windows asks for permission. */
+export declare function restartSandboxService(): boolean;
+/** What the person is asked, and what is done about it: everything outside the decision is passed in. */
+export interface CleanupDeps {
+    /** The facts now (a fresh process list each time). */
+    readonly facts: () => Promise<SandboxFacts>;
+    readonly end: (pids: readonly number[]) => boolean;
+    readonly restartService: () => boolean;
+    /** An interactive question: true for yes. */
+    readonly confirm: (q: {
+        title: string;
+        lines: string[];
+        yes: string;
+    }) => Promise<boolean>;
+    readonly say: (line: string) => void;
+    /** Also restart the service even when the programs ended (the caller said Windows still refuses). */
+    readonly alsoService?: boolean;
+}
+export type CleanupOutcome = 
+/** Nothing of the sandbox is on this PC. */
+'nothing'
+/** A live sandbox (or another user's): nothing was ended. */
+ | 'alive' | 'declined' | 'cleaned' | 'service-restarted' | 'failed';
+/** The question for a judgement of "leftover" (pure). */
+export declare function cleanupQuestion(j: SandboxJudgement): {
+    title: string;
+    lines: string[];
+    yes: string;
+};
+/** The whole clean-up: judge, ask, end, check, and (when needed and allowed) restart the service. */
+export declare function cleanUpLeftovers(deps: CleanupDeps): Promise<CleanupOutcome>;
+export { LEFTOVER_IMAGES };

package/dist/host/sandbox/cleanup.js

@@ -0,0 +1,82 @@
+// Windows Sandbox leaves its programs behind when the VM dies (a crash, a kill from the host side): the next start then
+// fails ("the sandbox was signed out", or "already running"). This ends those leftovers, after asking, and when Windows
+// still refuses, restarts the Windows Sandbox service (CmService), which needs administrator permission. The decisions
+// are pure and the actions are injected, so tests never end a process.
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { refuseInSelfTest } from '../test-guard.js';
+import { nativeScript } from '../native.js';
+import { judgeSandbox, LEFTOVER_IMAGES } from '../health/stale.js';
+const HELPER_TIMEOUT_MS = 15000;
+const SERVICE_TIMEOUT_MS = 120000;
+/** taskkill arguments that end exactly these programs (pure). */
+export function killArgs(pids) {
+    const safe = pids.filter((pid) => Number.isInteger(pid) && pid > 4);
+    return ['/F', ...safe.flatMap((pid) => ['/PID', String(pid)])];
+}
+/** Ends these Windows Sandbox programs (taskkill by absolute path). Returns false when taskkill failed. */
+export function endSandboxPrograms(pids) {
+    refuseInSelfTest('end Windows Sandbox programs');
+    if (killArgs(pids).length <= 1)
+        return true;
+    const result = spawnSync(SYSTEM.taskkill(), killArgs(pids), { windowsHide: true, timeout: HELPER_TIMEOUT_MS });
+    return result.status === 0;
+}
+/** Restarts the Windows Sandbox service (CmService) in an elevated PowerShell: Windows asks for permission. */
+export function restartSandboxService() {
+    refuseInSelfTest('restart the Windows Sandbox service');
+    const result = spawnSync(SYSTEM.powershell(), nativeScript('run-elevated.ps1', ['-Command', 'Restart-Service -Name CmService -Force']), { windowsHide: true, timeout: SERVICE_TIMEOUT_MS });
+    return result.status === 0;
+}
+const NAMES = (j) => j.images.join(', ');
+/** The question for a judgement of "leftover" (pure). */
+export function cleanupQuestion(j) {
+    return {
+        title: 'Close the leftover Windows Sandbox programs?',
+        lines: [
+            j.why,
+            'Windows Sandbox leaves its programs behind when the sandbox dies, and then refuses to start again.',
+            'Only these programs of your Windows session are closed: ' + NAMES(j) + '. Nothing else.',
+        ],
+        yes: 'Close them',
+    };
+}
+/** The whole clean-up: judge, ask, end, check, and (when needed and allowed) restart the service. */
+export async function cleanUpLeftovers(deps) {
+    const first = judgeSandbox(await deps.facts());
+    if (first.state === 'none')
+        return 'nothing';
+    if (first.state !== 'leftover') {
+        deps.say(first.why + ' Nothing was closed.');
+        return 'alive';
+    }
+    if (!(await deps.confirm(cleanupQuestion(first))))
+        return 'declined';
+    const ended = deps.end(first.pids);
+    const after = judgeSandbox(await deps.facts());
+    const gone = after.state === 'none' || after.state === 'foreign';
+    if (gone && !deps.alsoService) {
+        deps.say('Closed ' + first.pids.length + ' leftover program(s). The sandbox can start again now.');
+        return 'cleaned';
+    }
+    if (!gone)
+        deps.say(ended ? 'Some programs are still there.' : 'Windows would not let them be closed.');
+    const restart = deps.alsoService === true ||
+        (await deps.confirm({
+            title: 'Restart the Windows Sandbox service?',
+            lines: [
+                'Windows still holds the old sandbox. Restarting its service (CmService) clears that.',
+                'Windows asks for administrator permission once.',
+            ],
+            yes: 'Restart it',
+        }));
+    if (!restart)
+        return gone ? 'cleaned' : 'declined';
+    if (!deps.restartService()) {
+        deps.say('The service was not restarted (the permission was declined, or Windows refused).');
+        return 'failed';
+    }
+    deps.say('The Windows Sandbox service was restarted.');
+    return 'service-restarted';
+}
+export { LEFTOVER_IMAGES };

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

@@ -1,4 +1,5 @@
 export * from './platform.js';
+export * from './cleanup.js';
 export * from './probe.js';
 export * from './tasklist.js';
 export * from './host-claude.js';

package/dist/host/sandbox/index.js

@@ -1,4 +1,5 @@
 export * from './platform.js';
+export * from './cleanup.js';
 export * from './probe.js';
 export * from './tasklist.js';
 export * from './host-claude.js';

package/dist/host/sandbox/platform.js

@@ -89,7 +89,7 @@ export async function confirmSandboxStarted(wsbPath, waitMs = START_WAIT_MS) {
         if (Date.now() >= deadline)
             fail('Windows Sandbox did not start within ' + Math.round(waitMs / 1000) + ' seconds.', 'Open ' +
                 wsbPath +
-                ' yourself to see the message Windows gives, or run sandbox doctor to check the Windows Sandbox feature.');
+                ' yourself to see the message Windows gives, or run sandbox doctor to check the Windows Sandbox feature. If Windows says the sandbox was signed out, a sandbox that died left its programs behind: run sandbox cleanup.');
         await sleep(1000);
     }
 }

package/dist/runtime/agent.js

@@ -5541,6 +5541,7 @@ var SYSTEM = {
   cmd: () => system32("cmd.exe"),
   powershell: () => system32("WindowsPowerShell\\v1.0\\powershell.exe"),
   tasklist: () => system32("tasklist.exe"),
+  taskkill: () => system32("taskkill.exe"),
   whoami: () => system32("whoami.exe"),
   icacls: () => system32("icacls.exe"),
   tar: () => system32("tar.exe"),
@@ -25466,7 +25467,7 @@ var SandboxSchema = external_exports.strictObject({
     '(alpha) What runs the sandbox. "windows-sandbox" = Windows Sandbox (the default: desktop, Windows Terminal, GPU, clipboard, audio, printers). "hcs" = a headless Hyper-V isolated Server Core container for agents (no desktop, GPU or clipboard); it needs Windows features and an image on this PC (sandbox engine check hcs lists what is missing), and starting it is not enabled yet in this alpha. sandbox engine shows what each engine can do. Yours only: a project file (.sandbox-config.json) cannot set it.'
   ),
   memoryMb: external_exports.union([external_exports.literal("auto"), external_exports.number().int().min(2048)]).describe(
-    'Sandbox RAM in MB (>= 2048), or "auto": free RAM minus reserveHostMb, capped at maxMemoryMb. Never more than this PC can keep in RAM for it (its RAM minus the larger of reserveHostMb and 25 %, 2 GB more with vGPU): a bigger value is lowered.'
+    'Sandbox RAM in MB (>= 2048), or "auto": free RAM minus reserveHostMb, capped at maxMemoryMb. Never more than this PC can keep in RAM for it (its RAM minus the larger of reserveHostMb and 25 %, 4 GB more with vGPU): a bigger value is lowered.'
   ),
   maxMemoryMb: external_exports.number().int().positive().describe('Upper limit for memoryMb "auto".'),
   maxMemoryPercent: external_exports.number().int().min(10).max(100).describe(`memoryMb "auto" never takes more than this share of this PC's total RAM (percent).`),
@@ -25628,13 +25629,13 @@ var ToolchainsSchema = external_exports.strictObject({
       '["sccache", "cargo-nextest", "cargo-deny"]'
     ),
     targetDir: external_exports.string().min(1).describe(
-      `"shared": cargo's default target\\ (shared with builds on this PC, so builds on either side invalidate the other), "separate": <workspace>\\target\\sandbox (kept, no cross-talk), "local": on the sandbox's own disk (fastest, lost every boot), or a guest path.`
+      `"auto" (default): on the sandbox's own disk when C: has 25 GB free at boot, else "separate" (builds then write through the mapped workspace, which can overload this PC's disk). "shared": cargo's default target\\ (shared with builds on this PC, so builds on either side invalidate the other), "separate": <workspace>\\target\\sandbox (kept, no cross-talk), "local": on the sandbox's own disk (fastest, lost every boot), or a guest path.`
     ),
     linker: external_exports.enum(["lld", "gnu"]).describe(
       `GNU host: "lld" links with Rust's own lld through MinGW's gcc (much less memory than GNU ld), "gnu" with GNU ld.`
     ),
     linkSlots: external_exports.union([external_exports.literal("auto"), external_exports.number().int().min(1).max(32)]).describe(
-      'GNU host: how many programs may link at the same time in the whole sandbox (other links wait). "auto" = one per 3 GB of sandbox memory after 6 GB, 2 to 8 (the memory governor slows links down too when memory runs short).'
+      'GNU host: how many programs may link at the same time in the whole sandbox (other links wait). "auto" = one per 6 GB of sandbox memory, 1 to 4 (the memory governor slows links down too when memory runs short).'
     )
   }),
   msvc: external_exports.strictObject({
@@ -27282,6 +27283,8 @@ var GuestRequestSchema = external_exports.discriminatedUnion("kind", [
     seconds: external_exports.number().int().min(10).max(300),
     /** "severe": the PC is nearly out of memory; builds go to the governor's last step at once. */
     level: external_exports.enum(["slow", "severe"]).optional(),
+    /** The disk queue the PC reported (shown in the heartbeat). */
+    diskQueue: external_exports.number().min(0).max(1e5).optional(),
     createdAt: TimeSchema
   })
 ]);
@@ -27304,6 +27307,22 @@ var PressureStatusSchema = external_exports.object({
   lastAction: Text(300),
   updatedAt: TimeSchema
 });
+var HeartbeatSchema = external_exports.object({
+  at: TimeSchema,
+  /** Seconds since the sandbox booted. */
+  uptimeS: external_exports.number().int().min(0).max(1e9),
+  ramFreePct: external_exports.number().min(0).max(100),
+  commitPct: external_exports.number().min(0).max(100),
+  /** The governor's dial now, and the step this PC asked for. */
+  step: external_exports.number().int().min(0).max(4),
+  hostStep: external_exports.number().int().min(0).max(4),
+  /** The biggest programs in the agents' job. */
+  topProcesses: external_exports.array(external_exports.object({ name: Text(64), privateMb: external_exports.number().int().min(0).max(1e7) })).max(5),
+  /** The disk queue this PC last reported while asking the sandbox to slow down. */
+  diskQueueReported: external_exports.number().min(0).max(1e5).optional(),
+  /** "ending": the sandbox is shutting down in order (idle shutdown, sandbox stop, Windows shutting down). */
+  phase: external_exports.enum(["ready", "working", "ending"])
+});
 var GuestResponseSchema = external_exports.object({
   id: IdSchema,
   ok: external_exports.boolean(),
@@ -27489,6 +27508,8 @@ var RunDir = class {
   vpnFile;
   /** What the memory governor in the sandbox is doing (pressure.json). */
   pressureFile;
+  /** The daemon's heartbeat every 10 seconds (heartbeat.json): what the sandbox did last. */
+  heartbeatFile;
   /** What the sandbox's programs may really use (budget.json): processors, memory, build jobs, link slots. */
   budgetFile;
   requestsDir;
@@ -27512,6 +27533,7 @@ var RunDir = class {
     this.sandboxFile = path5.join(this.root, "sandbox.json");
     this.vpnFile = path5.join(this.root, "vpn.json");
     this.pressureFile = path5.join(this.root, "pressure.json");
+    this.heartbeatFile = path5.join(this.root, "heartbeat.json");
     this.budgetFile = path5.join(this.root, "budget.json");
     this.requestsDir = path5.join(this.root, "requests");
     this.responsesDir = path5.join(this.root, "responses");
@@ -27556,6 +27578,9 @@ var RunDir = class {
   readPressure() {
     return readValid(PressureStatusSchema, this.pressureFile);
   }
+  readHeartbeat() {
+    return readValid(HeartbeatSchema, this.heartbeatFile);
+  }
   readSession(id) {
     return readValid(SessionStatusSchema, this.sessionFile(id));
   }