windows-development-sandbox 1.4.0 → 1.4.3

package/dist/host/launch/stage.js

@@ -1,11 +1,12 @@
-// What is copied into the launch folder (C:\AgentLaunch inside the sandbox): hooks, the bundled runtime, the git identity.
+// What is copied into the launch folder (C:\AgentLaunch inside the sandbox): hooks, the bundled runtime, the git
+// identity.
 import fs from 'node:fs';
 import path from 'node:path';
-import { userDir } from '../../core/config.js';
-import { dirExists, ensureDir, fail, fileExists, homeDir } from '../../core/util.js';
+import { userDir } from '../../core/config/index.js';
+import { dirExists, ensureDir, fail, fileExists, homeDir } from '../../core/util/index.js';
 const HOOK_STAGES = ['pre-provision', 'pre-agent', 'post-agent'];
 /** Package hooks first, then ~/.agent-sandbox/hooks (same file name = user's wins), then --script / "scripts". */
-export const stageHooks = (packageRoot, launchPath, scripts) => {
+export function stageHooks(packageRoot, launchPath, scripts) {
     for (const stage of HOOK_STAGES) {
         const target = path.join(launchPath, 'hooks', stage);
         ensureDir(target);
@@ -15,19 +16,19 @@ export const stageHooks = (packageRoot, launchPath, scripts) => {
         }
     }
     stageScripts(path.join(launchPath, 'hooks', 'pre-agent'), scripts);
-};
+}
 /** --script / "scripts" files, run before the agent in this order. */
-export const stageScripts = (target, scripts) => {
+export function stageScripts(target, scripts) {
     ensureDir(target);
     scripts.forEach((script, index) => {
         if (!fileExists(script))
             fail('Script file not found: ' + script, 'Check the --script path.');
         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'];
 /** The bundled sandbox runtime (dist/runtime: one self-contained file per entry point) and the sandbox/ scripts. */
-export const copyRuntime = (packageRoot, launchPath) => {
+export function copyRuntime(packageRoot, launchPath) {
     const runtime = path.join(packageRoot, 'dist', 'runtime');
     const missing = RUNTIME_FILES.filter((f) => !fileExists(path.join(runtime, f)));
     if (missing.length)
@@ -37,9 +38,9 @@ export const copyRuntime = (packageRoot, launchPath) => {
         fs.copyFileSync(path.join(runtime, file), path.join(launchPath, 'runtime', file));
     fs.writeFileSync(path.join(launchPath, 'package.json'), '{ "type": "module" }\n', 'utf8');
     fs.cpSync(path.join(packageRoot, 'sandbox'), path.join(launchPath, 'sandbox'), { recursive: true });
-};
+}
 /** Only the identity from ~/.gitconfig: the rest can hold credentials (helpers, tokens in insteadOf URLs). */
-export const gitIdentity = (gitconfig) => {
+export function gitIdentity(gitconfig) {
     const values = {};
     let section = '';
     for (const line of gitconfig.split(/\r?\n/)) {
@@ -54,13 +55,13 @@ export const gitIdentity = (gitconfig) => {
     }
     const lines = Object.entries(values).map(([k, v]) => '\t' + k + ' = ' + v);
     return lines.length ? '[user]\n' + lines.join('\n') + '\n' : '';
-};
+}
 /** Writes this PC's git name and email to home\.gitconfig in the launch folder (nothing when there are none). */
-export const stageGitIdentity = (launchPath) => {
+export function stageGitIdentity(launchPath) {
     const gitconfig = path.join(homeDir(), '.gitconfig');
     const identity = fileExists(gitconfig) ? gitIdentity(fs.readFileSync(gitconfig, 'utf8')) : '';
     if (!identity)
         return;
     ensureDir(path.join(launchPath, 'home'));
     fs.writeFileSync(path.join(launchPath, 'home', '.gitconfig'), identity, 'utf8');
-};
+}

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

@@ -0,0 +1,4 @@
+import type { GenerateOptions } from '../../core/types.js';
+import { decideToolchains } from '../../core/detect/index.js';
+/** Which toolchains the project needs ("auto" settings follow the project's files and what this PC has). */
+export declare function decideProjectToolchains(o: Pick<GenerateOptions, 'run' | 'pcLanguages'>): ReturnType<typeof decideToolchains>;

package/dist/host/launch/toolchains.js

@@ -0,0 +1,11 @@
+import { decideToolchains, readPwshScripts, usesPwsh } from '../../core/detect/index.js';
+import { pcLanguages } from './pc-scan.js';
+import { msvcHint, projectEntries } from './project-scan.js';
+/** Which toolchains the project needs ("auto" settings follow the project's files and what this PC has). */
+export function decideProjectToolchains(o) {
+    const { config, workspaceHost } = o.run;
+    const msvcScript = config.toolchains.msvc.enabled === 'auto' ? msvcHint(workspaceHost) : undefined;
+    const pwshScript = config.toolchains.pwsh.enabled === 'auto' ? usesPwsh(readPwshScripts(workspaceHost)) : null;
+    const hints = { ...(msvcScript ? { msvc: msvcScript } : {}), ...(pwshScript ? { pwsh: pwshScript } : {}) };
+    return decideToolchains(config.toolchains, projectEntries(workspaceHost), o.pcLanguages ?? pcLanguages(), hints);
+}

package/dist/host/launch/{wsb.d.ts → wsb-file.d.ts}

@@ -5,6 +5,8 @@ export declare const GUEST: {
     readonly hostTools: "C:\\HostTools";
     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 const resolveMemoryMb: (sandbox: Config["sandbox"], freeMemoryBytes?: number, totalMemoryBytes?: number) => number;
-export declare const buildWsb: (config: Config, memoryMb: number, mappings: ResolvedMapping[]) => string;
+export declare function resolveMemoryMb(sandbox: SandboxSettings, freeMemoryBytes?: number, totalMemoryBytes?: number): number;
+export declare function buildWsb(config: Config, memoryMb: number, mappings: ResolvedMapping[]): string;
+export {};

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

@@ -0,0 +1,56 @@
+// The .wsb file Windows Sandbox starts from: memory, devices and the folders mapped in.
+import os from 'node:os';
+import { fail, xmlEscape } from '../../core/util/index.js';
+import { MIRROR_ROOT, sandboxFolder } 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 + '>';
+}
+function toggle(value) {
+    return value ? 'Enable' : 'Disable';
+}
+/** "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()) {
+    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\\logon.cmd'))));
+}

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

@@ -0,0 +1,8 @@
+import { type StopCause, type StopEvent } from './stop-events.js';
+/**
+ * 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;
+/** When the sandbox ended in a crash (its own, this PC's, power, low memory): writes the report and returns its path. */
+export declare function saveCrashReport(storageRoot: string, dataPath: string, lastSeen: string): string | null;

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

@@ -0,0 +1,87 @@
+// The crash report: what Windows logged when the sandbox ended and the last minutes of the sandbox's memory log, kept
+// in <storage>\logs\crashes (the newest 20).
+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';
+const KEEP_REPORTS = 20;
+const MEMORY_TAIL_BYTES = 16 * 1024;
+function crashDir(storageRoot) {
+    return path.join(storageRoot, 'logs', 'crashes');
+}
+/**
+ * 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, ' ') : ''))
+        : ['  (none)'];
+    const memoryLines = memoryLog
+        ? memoryLog
+            .split(/\r?\n/)
+            .filter(Boolean)
+            .slice(-30)
+            .map((l) => '  ' + safeText(l))
+        : ['  (none found)'];
+    return [
+        'Sandbox crash report, written ' + new Date().toISOString(),
+        'What happened: ' + cause.text + ' at ' + cause.at + ' (the sandbox was last seen running at ' + lastSeen + ').',
+        '',
+        'Windows events around then:',
+        ...eventLines,
+        '',
+        "The sandbox's memory log, last lines (C:\\AgentData\\logs\\memory-*.log inside it):",
+        ...memoryLines,
+        '',
+    ].join('\n');
+}
+/** 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 newest = fs
+            .readdirSync(logs)
+            .filter((f) => /^memory-\d{8}-\d{6}\.log$/.test(f))
+            .sort()
+            .pop();
+        if (!newest)
+            return '';
+        const file = path.join(logs, newest);
+        if (!fs.lstatSync(file).isFile())
+            return '';
+        const size = fs.statSync(file).size;
+        const fd = fs.openSync(file, 'r');
+        try {
+            const length = Math.min(size, MEMORY_TAIL_BYTES);
+            const buffer = Buffer.alloc(length);
+            fs.readSync(fd, buffer, 0, length, size - length);
+            return buffer.toString('utf8');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return '';
+    }
+}
+/** When the sandbox ended in a crash (its own, this PC's, power, low memory): writes the report and returns its path. */
+export function saveCrashReport(storageRoot, dataPath, lastSeen) {
+    const events = readStopEvents(new Date(Date.parse(lastSeen) - 2 * 60 * 1000));
+    const cause = explainStop(events);
+    if (!cause || !['sandboxCrash', 'crash', 'memory'].includes(cause.kind))
+        return null;
+    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));
+    for (const old of fs
+        .readdirSync(dir)
+        .filter((f) => f.startsWith('crash-'))
+        .sort()
+        .slice(0, -KEEP_REPORTS))
+        fs.rmSync(path.join(dir, old), { force: true });
+    return file;
+}

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

@@ -0,0 +1,6 @@
+export * from './life-record.js';
+export * from './stop-events.js';
+export * from './stop-warning.js';
+export * from './keep-awake.js';
+export * from './windows-update.js';
+export * from './crash-report.js';

package/dist/host/life/index.js

@@ -0,0 +1,6 @@
+export * from './life-record.js';
+export * from './stop-events.js';
+export * from './stop-warning.js';
+export * from './keep-awake.js';
+export * from './windows-update.js';
+export * from './crash-report.js';

package/dist/host/life/keep-awake.d.ts

@@ -0,0 +1,10 @@
+/**
+ * sandbox.keepAwake: asks Windows not to sleep while the sandbox runs (as a video player does; the screen may still
+ * turn off). native\keep-awake.ps1 holds the request until `ownerPid` exits, so it never outlives the watcher.
+ */
+export declare class KeepAwake {
+    private readonly child;
+    private constructor();
+    static start(ownerPid: number): KeepAwake | null;
+    stop(): void;
+}

package/dist/host/life/keep-awake.js

@@ -0,0 +1,29 @@
+import { spawn } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { isWin } from '../../core/util/index.js';
+import { refuseInSelfTest } from '../test-guard.js';
+import { nativeScript } from '../native.js';
+/**
+ * sandbox.keepAwake: asks Windows not to sleep while the sandbox runs (as a video player does; the screen may still
+ * turn off). native\keep-awake.ps1 holds the request until `ownerPid` exits, so it never outlives the watcher.
+ */
+export class KeepAwake {
+    child;
+    constructor(child) {
+        this.child = child;
+    }
+    static start(ownerPid) {
+        if (!isWin)
+            return null;
+        refuseInSelfTest('keep this PC awake');
+        const child = spawn(SYSTEM.powershell(), nativeScript('keep-awake.ps1', ['-OwnerId', String(Math.trunc(ownerPid))]), {
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        child.on('error', () => undefined);
+        return new KeepAwake(child);
+    }
+    stop() {
+        this.child.kill();
+    }
+}

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

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { type StopCause } from './stop-events.js';
+declare const LifeSchema: z.ZodObject<{
+    started: z.ZodString;
+    lastSeen: z.ZodString;
+    keepAwake: z.ZodBoolean;
+    ended: z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        cause: z.ZodNullable<z.ZodObject<{
+            kind: z.ZodEnum<{
+                restart: "restart";
+                updates: "updates";
+                crash: "crash";
+                sleep: "sleep";
+                memory: "memory";
+                sandboxCrash: "sandboxCrash";
+            }>;
+            at: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$strip>>;
+        report: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    reported: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type Life = z.output<typeof LifeSchema>;
+/** <storage>\sync\<data>-life.json: how the running (or last) sandbox lived and ended. */
+export declare class LifeRecord {
+    private readonly storageRoot;
+    private readonly dataPath;
+    private readonly file;
+    constructor(storageRoot: string, dataPath: string);
+    read(): Life | null;
+    /** At launch: a fresh record (the previous one has been reported by then). */
+    start(keepAwake: boolean, now?: Date): void;
+    /** Every minute while the sandbox runs. */
+    beat(now?: Date): void;
+    /**
+     * The watcher saw the sandbox close while this PC kept running: closed by you (no cause), or by sleep / low memory.
+     */
+    end(cause: StopCause | null, now?: Date, report?: string | null): void;
+    /**
+     * At launch: one warning when the last sandbox ended without anyone closing it (the PC restarted, crashed, slept or
+     * ran out of memory), then never again for that run. `watcherAlive` = its watcher is still running (then it did not
+     * end).
+     */
+    lastStopWarning(watcherAlive: boolean, find?: (lastSeen: string) => StopCause | null): string | null;
+}
+export {};

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

@@ -0,0 +1,76 @@
+// Why the last sandbox stopped, when nobody stopped it. The background watcher writes a host-only "life" record (when
+// the sandbox started, when it was last seen running, how it ended) and keeps this PC awake while it runs
+// (sandbox.keepAwake). When the PC restarts, sleeps or crashes, the watcher stops too and the record has no end: the
+// next launch reads Windows' System log from that moment on and says what happened, and what keeps it from happening.
+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 { stopWarning } from './stop-warning.js';
+import { saveCrashReport } from './crash-report.js';
+const LifeSchema = z.object({
+    started: IsoSchema,
+    lastSeen: IsoSchema,
+    keepAwake: z.boolean(),
+    ended: z
+        .object({
+        at: IsoSchema,
+        cause: z
+            .object({
+            kind: z.enum(['updates', 'restart', 'crash', 'sleep', 'memory', 'sandboxCrash']),
+            at: IsoSchema,
+            text: z.string().max(400),
+        })
+            .nullable(),
+        report: z.string().max(1000).optional(),
+    })
+        .optional(),
+    reported: z.boolean().optional(),
+});
+/** <storage>\sync\<data>-life.json: how the running (or last) sandbox lived and ended. */
+export class LifeRecord {
+    storageRoot;
+    dataPath;
+    file;
+    constructor(storageRoot, dataPath) {
+        this.storageRoot = storageRoot;
+        this.dataPath = dataPath;
+        this.file = new JsonFile(LifeSchema, hostStateFile(storageRoot, dataPath, '-life.json'));
+    }
+    read() {
+        return this.file.read();
+    }
+    /** At launch: a fresh record (the previous one has been reported by then). */
+    start(keepAwake, now = new Date()) {
+        this.file.write({ started: now.toISOString(), lastSeen: now.toISOString(), keepAwake });
+    }
+    /** Every minute while the sandbox runs. */
+    beat(now = new Date()) {
+        const life = this.read();
+        if (life && !life.ended)
+            this.file.write({ ...life, lastSeen: now.toISOString() });
+    }
+    /**
+     * The watcher saw the sandbox close while this PC kept running: closed by you (no cause), or by sleep / low memory.
+     */
+    end(cause, now = new Date(), report = null) {
+        const life = this.read();
+        if (life && !life.ended)
+            this.file.write({ ...life, ended: { at: now.toISOString(), cause, ...(report ? { report } : {}) } });
+    }
+    /**
+     * At launch: one warning when the last sandbox ended without anyone closing it (the PC restarted, crashed, slept or
+     * ran out of memory), then never again for that run. `watcherAlive` = its watcher is still running (then it did not
+     * end).
+     */
+    lastStopWarning(watcherAlive, find = causeSince) {
+        const life = this.read();
+        if (!life || life.reported || watcherAlive)
+            return null;
+        this.file.write({ ...life, reported: true });
+        // The watcher writes the report when it sees the end; when this PC itself went down, it is written now.
+        const report = () => life.ended?.report ??
+            (find === causeSince ? saveCrashReport(this.storageRoot, this.dataPath, life.lastSeen) : null);
+        return stopWarning(life, find, report);
+    }
+}

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

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+export declare const IsoSchema: z.ZodString;
+export interface StopEvent {
+    at: string;
+    id: number;
+    provider: string;
+    process: string;
+}
+export type StopKind = 'updates' | 'restart' | 'crash' | 'sleep' | 'memory' | 'sandboxCrash';
+export interface StopCause {
+    kind: StopKind;
+    at: string;
+    text: string;
+}
+/**
+ * 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
+ * user does not end it (seen on 13 Oct 2026: the sandbox ran on after a switch).
+ */
+export declare const explainStop: (events: StopEvent[]) => StopCause | null;
+/**
+ * System log and Hyper-V events since `since` that can end a sandbox (Windows only; empty when the logs cannot be
+ * read).
+ */
+export declare const readStopEvents: (since: Date) => StopEvent[];
+/** Looking back from the last time the sandbox was seen running (a minute between checks, plus margin). */
+export declare const causeSince: (lastSeen: string) => StopCause | null;

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

@@ -0,0 +1,96 @@
+import { spawnSync } from 'node:child_process';
+import { z } from 'zod';
+import { SYSTEM } from '../../shared/system.js';
+import { isWin } from '../../core/util/index.js';
+import { refuseInSelfTest } from '../test-guard.js';
+import { nativeScript } from '../native.js';
+export const IsoSchema = z.string().max(40);
+const StopEventsSchema = z
+    .array(z.object({
+    at: IsoSchema,
+    id: z.number().int(),
+    provider: z.string().max(200),
+    process: z
+        .string()
+        .max(400)
+        .nullable()
+        .transform((p) => p ?? ''),
+}))
+    .max(100);
+const UPDATERS = /^(trustedinstaller|mousocoreworker|musnotification(ux)?|usoclient|wuauclt|tiworker|updateorchestrator)\.exe$/i;
+/**
+ * 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
+ * user does not end it (seen on 13 Oct 2026: the sandbox ran on after a switch).
+ */
+export const explainStop = (events) => {
+    const causes = events.flatMap((e) => {
+        const p = e.provider.toLowerCase();
+        if (e.id === 1074 && p.includes('user32')) {
+            const exe = e.process
+                .split(/[\\/]/)
+                .pop()
+                ?.replace(/\s*\(.*$/, '') ?? '';
+            return UPDATERS.test(exe)
+                ? [{ kind: 'updates', at: e.at, text: 'Windows restarted this PC to install updates' }]
+                : [
+                    {
+                        kind: 'restart',
+                        at: e.at,
+                        text: 'this PC was restarted or shut down' + (exe ? ' (by ' + exe + ')' : ''),
+                    },
+                ];
+        }
+        if ((e.id === 41 && p.includes('kernel-power')) || (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)',
+                },
+            ];
+        if (e.id === 42 && p.includes('kernel-power'))
+            return [{ kind: 'sleep', at: e.at, text: 'this PC went to sleep or hibernated' }];
+        if (e.id === 2004 && p.includes('resource-exhaustion'))
+            return [{ kind: 'memory', at: e.at, text: 'this PC ran out of memory' }];
+        if (e.id === 1001 && p.includes('systemerrorreporting')) {
+            const code = /bugcheck was:\s*(0x[0-9a-f]{1,8})/i.exec(e.process)?.[1];
+            return [{ kind: 'crash', at: e.at, text: 'this PC blue-screened' + (code ? ' (stop code ' + code + ')' : '') }];
+        }
+        if (e.id === 18590 && p.includes('hyper-v-worker')) {
+            const code = /ErrorCode0:\s*(0x[0-9a-f]{1,8})/i.exec(e.process)?.[1];
+            const sub = /ErrorCode1:\s*(0x[0-9a-f]{1,16})/i.exec(e.process)?.[1];
+            return [
+                {
+                    kind: 'sandboxCrash',
+                    at: e.at,
+                    text: 'Windows inside the sandbox crashed' + (code ? ' (stop code ' + code + (sub ? ', ' + sub : '') + ')' : ''),
+                },
+            ];
+        }
+        return [];
+    });
+    return causes.sort((a, b) => Date.parse(a.at) - Date.parse(b.at))[0] ?? null;
+};
+/**
+ * System log and Hyper-V events since `since` that can end a sandbox (Windows only; empty when the logs cannot be
+ * read).
+ */
+export const readStopEvents = (since) => {
+    if (!isWin)
+        return [];
+    refuseInSelfTest('read the Windows event log');
+    const result = spawnSync(SYSTEM.powershell(), nativeScript('stop-events.ps1', ['-Since', since.toISOString()]), {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 60000,
+    });
+    try {
+        return StopEventsSchema.parse(JSON.parse(result.stdout || '[]'));
+    }
+    catch {
+        return [];
+    }
+};
+/** Looking back from the last time the sandbox was seen running (a minute between checks, plus margin). */
+export const causeSince = (lastSeen) => explainStop(readStopEvents(new Date(Date.parse(lastSeen) - 2 * 60 * 1000)));

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

@@ -0,0 +1,4 @@
+import type { StopCause } from './stop-events.js';
+import type { Life } from './life-record.js';
+/** What to tell about a sandbox that ended without anyone closing it (null: it was closed normally). */
+export declare function stopWarning(life: Life, find: (since: string) => StopCause | null, crashReport?: () => string | null): string | null;

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

@@ -0,0 +1,25 @@
+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.',
+    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.',
+};
+const when = (iso) => new Date(iso).toLocaleString(undefined, { weekday: 'short', hour: '2-digit', minute: '2-digit' });
+/** What to tell about a sandbox that ended without anyone closing it (null: it was closed normally). */
+export function stopWarning(life, find, crashReport = () => null) {
+    if (life.ended && !life.ended.cause)
+        return null;
+    const cause = life.ended ? life.ended.cause : find(life.lastSeen);
+    const what = cause
+        ? cause.text + ' at ' + when(cause.at) + '. ' + ADVICE[cause.kind]
+        : 'this PC stopped (Windows logged no reason). ' + ADVICE.crash;
+    const report = crashReport();
+    return ('The last sandbox did not close normally: it was last seen running at ' +
+        when(life.lastSeen) +
+        ', and ' +
+        what +
+        ' Agent conversations are kept: /resume in Claude picks one up.' +
+        (report ? ' Crash report: ' + report : ''));
+}

package/dist/host/life/windows-update.d.ts

@@ -0,0 +1,3 @@
+/** Windows has installed updates and waits to restart: it may do so on its own, outside your active hours. */
+export declare const updateRestartPending: () => boolean;
+export declare const UPDATE_RESTART_WARNING = "Windows is waiting to restart for updates and may do so on its own (often overnight), which closes the sandbox. Restart first, or pause updates: Settings > Windows Update > Pause updates.";

package/dist/host/life/windows-update.js

@@ -0,0 +1,11 @@
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { isWin } from '../../core/util/index.js';
+// ---- Windows Update and keeping awake ----------------------------------------------------------------------------
+/** Windows has installed updates and waits to restart: it may do so on its own, outside your active hours. */
+export const updateRestartPending = () => isWin &&
+    [
+        'HKLM\\SOFTWARE\\Microsoft\\WindowsUpdate\\Auto Update\\RebootRequired',
+        'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\RebootPending',
+    ].some((key) => spawnSync(SYSTEM.reg(), ['query', key], { windowsHide: true, stdio: 'ignore', timeout: 15000 }).status === 0);
+export const UPDATE_RESTART_WARNING = 'Windows is waiting to restart for updates and may do so on its own (often overnight), which closes the sandbox. Restart first, or pause updates: Settings > Windows Update > Pause updates.';

package/dist/host/native.d.ts

@@ -0,0 +1,4 @@
+/** The full path of native\<name>. */
+export declare function nativeFile(name: string): string;
+/** powershell.exe arguments that run native\<name> (a .ps1 shipped next to dist) with `args`. */
+export declare function nativeScript(name: string, args?: readonly string[]): string[];

package/dist/host/native.js

@@ -0,0 +1,11 @@
+// This package's native\ folder: PowerShell scripts (and the C# they load) that the host runs by path.
+import path from 'node:path';
+import { PACKAGE_ROOT } from '../core/package-info.js';
+/** The full path of native\<name>. */
+export function nativeFile(name) {
+    return path.join(PACKAGE_ROOT, 'native', name);
+}
+/** powershell.exe arguments that run native\<name> (a .ps1 shipped next to dist) with `args`. */
+export function nativeScript(name, args = []) {
+    return ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', nativeFile(name), ...args];
+}

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

@@ -0,0 +1 @@
+export * from './port-forward.js';

package/dist/host/network/index.js

@@ -0,0 +1 @@
+export * from './port-forward.js';

package/dist/host/{port-forward.d.ts → network/port-forward.d.ts}

@@ -1,4 +1,4 @@
-import { type PortForward } from '../shared/netpolicy.js';
+import { type PortForward } from '../../shared/network/index.js';
 /** Host-only: the forwards of the running sandbox (written at launch, read by the watcher). */
 export declare const saveForwards: (storageRoot: string, dataPath: string, forwards: PortForward[]) => void;
 export declare const readForwards: (storageRoot: string, dataPath: string) => PortForward[];