windows-development-sandbox 1.18.3 → 1.18.4

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/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"),
@@ -27319,7 +27320,8 @@ var HeartbeatSchema = external_exports.object({
   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(),
-  phase: external_exports.enum(["ready", "working"])
+  /** "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,