windows-development-sandbox 1.1.0 → 1.4.1

package/dist/host/projects.js

@@ -4,13 +4,14 @@
 //    as folders join);
 //  - known-projects.json: every folder this tool has started a project in (for projects.all and `sandbox projects`).
 // Everything about HOW a folder becomes visible is behind ProjectMapper, so the mechanisms can change independently.
+import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
 import { assertSafeWorkspace } from '../core/safe-paths.js';
 import { dirExists, fail } from '../core/util.js';
 import { Id } from '../shared/schema.js';
 import { readValid, writeJsonAtomic } from '../shared/rundir.js';
-import { guestDirFor, hubName, isWithin, PROJECTS_GUEST, projectForHostDir } from '../shared/projects.js';
+import { guestDirFor, hubName, isWithin, ownGuestFolder, PROJECTS_GUEST, projectForHostDir } from '../shared/projects.js';
 import { detectWsb, runningSandboxId, shareFolder } from './wsb.js';
 export { PROJECTS_GUEST };
 const AbsolutePath = z.string().max(1024).refine((p) => path.isAbsolute(p), 'must be an absolute path');
@@ -24,6 +25,13 @@ const Registry = z.strictObject({
     protections: z.record(z.string(), z.union([z.boolean(), z.string()])),
     roots: z.array(z.strictObject({ host: AbsolutePath, guest: z.string().max(1024) })).max(64),
     projects: z.array(Entry).max(1024),
+    /** What the sandbox booted with that a joining project may also want (missing in registries of 1.4.0 and older). */
+    atBoot: z.strictObject({
+        memoryMb: z.number().int().positive().nullable(),
+        mappings: z.array(z.strictObject({ host: z.string().max(1024), guest: z.string().max(1024), readOnly: z.boolean() })).max(1024),
+        /** Boot settings turned on for a project mapped at boot (setting -> project): other projects share them. */
+        widened: z.record(z.string().max(100), z.string().max(100)),
+    }).optional(),
 });
 const registryFile = (storageRoot) => path.join(storageRoot, 'run', 'projects.json');
 export const readRegistry = (storageRoot) => readValid(Registry, registryFile(storageRoot));
@@ -34,17 +42,57 @@ export const startRegistry = (storageRoot, o) => {
     const primary = { name: hubName(o.primary.host, []), host: o.primary.host, guest: o.primary.guest, primary: true, mechanism: 'launch', registeredAt: at };
     const names = [primary.name];
     const boot = o.boot.map((b) => { const name = hubName(b.host, names); names.push(name); return { name, host: b.host, guest: b.guest, primary: false, mechanism: 'boot', registeredAt: at }; });
-    saveRegistry(storageRoot, { launchId: o.launchId, protections: o.protections, roots: o.roots, projects: [primary, ...boot] });
+    saveRegistry(storageRoot, { launchId: o.launchId, protections: o.protections, roots: o.roots, projects: [primary, ...boot], ...(o.atBoot ? { atBoot: o.atBoot } : {}) });
     return primary;
 };
-/** Why a folder cannot join the running sandbox without a restart (the caller offers one). */
+/** Reads the memory and mapped folders back from a .wsb this tool wrote (host-only launch folder; bounded). */
+export const parseWsbBoot = (xml) => {
+    const text = xml.slice(0, 1_000_000);
+    const unescape = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, '\'').replace(/&amp;/g, '&');
+    const mappings = [...text.matchAll(/<MappedFolder><HostFolder>([^<]{1,1024})<\/HostFolder><SandboxFolder>([^<]{1,1024})<\/SandboxFolder><ReadOnly>(true|false)<\/ReadOnly><\/MappedFolder>/g)]
+        .slice(0, 1024).map((m) => ({ host: unescape(m[1]), guest: unescape(m[2]), readOnly: m[3] === 'true' }));
+    const memory = /<MemoryInMB>(\d{1,7})<\/MemoryInMB>/.exec(text);
+    return { memoryMb: memory ? Number(memory[1]) : null, mappings, widened: {} };
+};
+/**
+ * What the running sandbox booted with. A sandbox started by 1.4.0 or older has no record: it is read from the .wsb in
+ * its launch folder (host-only storage) and recorded. null when neither is there.
+ */
+export const bootRecordOf = (storageRoot, launchPath) => {
+    const registry = readRegistry(storageRoot);
+    if (!registry)
+        return null;
+    if (registry.atBoot)
+        return registry.atBoot;
+    if (!launchPath)
+        return null;
+    let xml;
+    try {
+        xml = fs.readFileSync(path.join(launchPath, 'agent.wsb'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const atBoot = parseWsbBoot(xml);
+    try {
+        saveRegistry(storageRoot, { ...registry, atBoot });
+    }
+    catch { /* the record is a convenience */ }
+    return atBoot;
+};
+/**
+ * Why a folder cannot join the running sandbox without a restart (the caller offers one). With `missing`: it could
+ * join, but you chose to restart for what it wants at boot (core/project-policy.ts).
+ */
 export class NeedsRestart extends Error {
     hostDir;
     reason;
-    constructor(hostDir, reason) {
+    missing;
+    constructor(hostDir, reason, missing) {
         super(reason);
         this.hostDir = hostDir;
         this.reason = reason;
+        this.missing = missing;
     }
 }
 /** Roots first (instant), then `wsb share` where the Windows Sandbox CLI exists, else NeedsRestart. */
@@ -84,7 +132,8 @@ export const projectMapper = (o) => {
             const sandbox = runningSandboxId(wsb);
             if (!sandbox.id)
                 throw new NeedsRestart(host, 'wsb share could not find the running sandbox: ' + sandbox.error);
-            const guest = path.win32.join(PROJECTS_GUEST, name);
+            // Where it is as a launch folder too (C:\Workspace\<name>), unless another project already uses that place.
+            const guest = ownGuestFolder(host, false, [...reg.projects.map((p) => p.guest), ...reg.roots.map((r) => r.guest)]);
             const shared = shareFolder(wsb, sandbox.id, host, guest);
             if (!shared.ok)
                 throw new NeedsRestart(host, 'wsb share failed (untested on this Windows): ' + shared.error);

package/dist/host/repo-guard.d.ts

@@ -1,12 +1,19 @@
-export interface RepoSnapshot {
-    gitDir: boolean;
+/** A git folder's own state: config lines, hooks, redirect files. */
+export interface GitState {
     config: string[];
     hooks: Record<string, string>;
     redirects: string[];
+}
+export interface RepoSnapshot extends GitState {
+    gitDir: boolean;
     commands: Record<string, string>;
+    /** Fingerprints of AGENT_FILES (missing in snapshots of older versions: then they are not checked). */
+    agent?: Record<string, string>;
+    /** Other git folders: submodules (.git/modules/...) and repositories nested in the project, by relative path. */
+    repos?: Record<string, GitState>;
 }
 export interface RepoFinding {
-    kind: 'hook' | 'config' | 'git' | 'command';
+    kind: 'hook' | 'config' | 'git' | 'command' | 'agent';
     detail: string;
 }
 export declare const snapshotRepo: (workspace: string) => RepoSnapshot;

package/dist/host/repo-guard.js

@@ -6,17 +6,22 @@
 //  - git: new or changed hooks, and config that makes git run programs (core.fsmonitor, core.sshCommand, filters,
 //    include.path, ...), plus files that redirect where git reads config and hooks (commondir, config.worktree);
 //  - commands: executables dropped in the project root under the name of something you type there (node.exe,
-//    git.cmd, npm.cmd, ...), because Windows runs a program from the current folder before searching PATH.
+//    git.cmd, npm.cmd, ...), because Windows runs a program from the current folder before searching PATH;
+//  - agent and editor files: hooks, helper commands and MCP servers in .claude/ and .mcp.json, VS Code folder-open
+//    tasks and program paths, .envrc. Submodules and nested repositories get the git checks too.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import _ from 'lodash';
 import { z } from 'zod';
+import { parse as parseJsonc } from 'jsonc-parser';
 import { readValid, writeFileAtomic, writeJsonAtomic } from '../shared/rundir.js';
 import { assertTestWritable } from './test-guard.js';
 import { dirExists, fileExists, isLink } from '../core/util.js';
 /** Config keys that make git run a program, or load more config. */
-const DANGEROUS_KEY = /^(fsmonitor|hookspath|sshcommand|pager|editor|askpass|program|gpgprogram|textconv|command|cmd|clean|smudge|process|driver|helper|uploadpack|receivepack|path|attributesfile|excludesfile|worktree|worktreeconfig|gitproxy|proxycommand|sendemailvalidate|tool)\s*=/i;
+const DANGEROUS_KEY = /^(fsmonitor|hookspath|sshcommand|pager|editor|askpass|program|gpgprogram|textconv|command|cmd|clean|smudge|process|driver|helper|uploadpack|receivepack|path|attributesfile|excludesfile|worktree|worktreeconfig|gitproxy|proxycommand|sendemailvalidate|tool|external|difffilter|defaultkeycommand|alternaterefscommand)\s*=/i;
+/** Sections where any key runs a program ([pager] log = x), or where a "!" value does ([alias] st = !x). */
+const dangerousInSection = (section, keyPart) => (section === 'pager' && keyPart.includes('=')) || (section === 'alias' && /^[^=]+=\s*"?\s*!/.test(keyPart));
 const SECTION = /^\s*\[([^\]]*)\]\s*/;
 const MARK = '# [agent-sandbox] disabled, added inside the sandbox: ';
 /** Files in .git that make git read config/hooks from somewhere else. */
@@ -33,6 +38,41 @@ const COMMANDS = new RegExp('^(' + [
     'make', 'cmake', 'ninja', 'gcc', 'g\\+\\+', 'clang', 'psql', 'mysql', 'mariadb', 'mongosh', 'redis-cli', 'docker', 'kubectl', 'terraform', 'az', 'aws',
     'powershell', 'pwsh', 'cmd', 'where', 'tasklist', 'tar', 'curl', 'ssh', 'scp',
 ].join('|') + ')\\.(exe|com|bat|cmd|vbs|vbe|js|jse|wsf|wsh|msc|ps1)$', 'i');
+/**
+ * Project files that tools on this PC act on by themselves: Claude Code runs a project's hooks, helpers and MCP servers,
+ * VS Code runs folder-open tasks and the programs workspace settings point at, direnv runs .envrc. For each, only the
+ * part that can run something is compared (`risky`), so the agent may still edit the rest (permissions, formatting).
+ */
+const AGENT_FILES = {
+    '.claude/settings.json': (d) => claudeRisk(d),
+    '.claude/settings.local.json': (d) => claudeRisk(d),
+    '.mcp.json': (_d, text) => text,
+    '.vscode/tasks.json': (d) => JSON.stringify(d).match(/"runOn"\s*:\s*"folderOpen"/) ? d : null,
+    '.vscode/settings.json': (d) => _.pickBy(_.isPlainObject(d) ? d : {}, (_v, k) => /path|executable|command|interpreter|shell|profile|args|env|exec|program|server|launch|runtime|binary/i.test(k)),
+    '.envrc': (_d, text) => text,
+};
+const claudeRisk = (d) => {
+    const s = (_.isPlainObject(d) ? d : {});
+    const permissions = (_.isPlainObject(s.permissions) ? s.permissions : {});
+    return { ..._.pick(s, ['hooks', 'apiKeyHelper', 'awsAuthRefresh', 'awsCredentialExport', 'otelHeadersHelper', 'statusLine', 'env', 'enableAllProjectMcpServers', 'enabledMcpjsonServers', 'disableAllHooks']), permissions: _.pick(permissions, ['defaultMode', 'additionalDirectories']) };
+};
+const MAX_AGENT_FILE_BYTES = 1024 * 1024;
+/** What can run in one agent file, as a short fingerprint (null = the file is not there). */
+const agentRisk = (workspace, rel) => {
+    const file = path.join(workspace, ...rel.split('/'));
+    if (!fs.existsSync(file))
+        return null;
+    if (isLink(file) || isLink(path.dirname(file)) || !fileExists(file))
+        return 'link-or-not-a-file';
+    if (fs.statSync(file).size > MAX_AGENT_FILE_BYTES)
+        return 'too-large-' + hash(file);
+    const text = fs.readFileSync(file, 'utf8');
+    const errors = [];
+    const data = parseJsonc(text, errors, { allowTrailingComma: true });
+    const risk = AGENT_FILES[rel](rel === '.envrc' ? null : data, text);
+    return crypto.createHash('sha256').update(JSON.stringify(risk ?? null) + (errors.length && rel !== '.envrc' && rel !== '.mcp.json' ? hash(file) : '')).digest('hex');
+};
+const agentSnapshot = (workspace) => Object.fromEntries(Object.keys(AGENT_FILES).flatMap((rel) => { const r = agentRisk(workspace, rel); return r ? [[rel, r]] : []; }));
 /** SHA-256 in small chunks: a sandbox can plant a multi-gigabyte "node.exe" to exhaust this PC's memory. */
 const hash = (file) => {
     if (isLink(file))
@@ -68,14 +108,66 @@ const configLines = (dir) => {
     const file = path.join(dir, 'config');
     return fileExists(file) && !isLink(file) && fs.statSync(file).size <= MAX_CONFIG_BYTES ? fs.readFileSync(file, 'utf8').split(/\r?\n/) : [];
 };
+const gitState = (dir) => ({
+    config: dir ? configLines(dir) : [],
+    hooks: dir ? filesIn(path.join(dir, 'hooks'), (n) => !n.endsWith('.sample')) : {},
+    redirects: dir ? REDIRECTS.filter((n) => fs.existsSync(path.join(dir, n))) : [],
+});
+const EMPTY_GIT = { config: [], hooks: {}, redirects: [] };
+const MAX_OTHER_REPOS = 64;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'agent-sandbox-quarantine', 'target', 'dist', 'build', 'bin', 'obj', '.venv', 'venv']);
+const plainDirs = (dir, limit) => {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.isSymbolicLink()).slice(0, limit).map((e) => path.join(dir, e.name));
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Git folders other than the project's own: submodules (.git/modules/**) and repositories nested up to two levels deep.
+ * git runs their hooks and config too (git status in a subfolder, VS Code's repository scan). Bounded: links are never
+ * followed and at most MAX_OTHER_REPOS are looked at.
+ */
+const otherGitDirs = (workspace) => {
+    const found = [];
+    const main = plainGitDir(workspace);
+    // Submodules: a folder with a config and a HEAD is a git folder, and may have modules of its own.
+    const walk = (dir, depth) => {
+        for (const d of plainDirs(dir, 200)) {
+            if (found.length >= MAX_OTHER_REPOS)
+                return;
+            if (fileExists(path.join(d, 'config')) && fileExists(path.join(d, 'HEAD'))) {
+                found.push(d);
+                if (depth < 3)
+                    walk(path.join(d, 'modules'), depth + 1);
+            }
+            else if (depth < 3)
+                walk(d, depth + 1);
+        }
+    };
+    if (main)
+        walk(path.join(main, 'modules'), 0);
+    for (const sub of plainDirs(workspace, 500).filter((d) => !SKIP_DIRS.has(path.basename(d).toLowerCase()))) {
+        for (const candidate of [sub, ...plainDirs(sub, 200).filter((d) => !SKIP_DIRS.has(path.basename(d).toLowerCase()))]) {
+            if (found.length >= MAX_OTHER_REPOS)
+                return found;
+            const git = plainGitDir(candidate);
+            if (git)
+                found.push(git);
+        }
+    }
+    return found;
+};
+const relative = (workspace, dir) => path.relative(workspace, dir).split(path.sep).join('/');
 export const snapshotRepo = (workspace) => {
     const dir = plainGitDir(workspace);
     return {
         gitDir: dir !== null,
-        config: dir ? configLines(dir) : [],
-        hooks: dir ? filesIn(path.join(dir, 'hooks'), (n) => !n.endsWith('.sample')) : {},
-        redirects: dir ? REDIRECTS.filter((n) => fs.existsSync(path.join(dir, n))) : [],
+        ...gitState(dir),
         commands: filesIn(workspace, (n) => COMMANDS.test(n)),
+        agent: agentSnapshot(workspace),
+        repos: Object.fromEntries(otherGitDirs(workspace).map((d) => [relative(workspace, d), gitState(d)])),
     };
 };
 /** Moves files into <dir>\agent-sandbox-quarantine\<time>\ and reports them. */
@@ -101,16 +193,19 @@ const disableConfig = (dir, before) => {
     const seen = {};
     const findings = [];
     let inInclude = false;
+    let section = '';
     const fixed = lines.map((line) => {
         const header = SECTION.exec(line);
-        if (header)
+        if (header) {
+            section = header[1].trim().toLowerCase().split(/\s/)[0];
             inInclude = /^include(if\s+"[^"]*")?$/i.test(header[1].trim());
+        }
         seen[line] = (seen[line] ?? 0) + 1;
         if (line.startsWith(MARK) || seen[line] <= (known[line] ?? 0))
             return line;
         // git also accepts "[core] fsmonitor = x" on one line, so look past a leading section header.
         const keyPart = line.replace(SECTION, '').trim();
-        if (!(DANGEROUS_KEY.test(keyPart) || (inInclude && keyPart.includes('='))))
+        if (!(DANGEROUS_KEY.test(keyPart) || (inInclude && keyPart.includes('=')) || dangerousInSection(section, keyPart)))
             return line;
         findings.push({ kind: 'config', detail: line.trim() });
         return MARK + line.trim();
@@ -133,6 +228,15 @@ export const guardRepo = (workspace, before) => {
     const findings = [];
     const commandsNow = filesIn(workspace, (n) => COMMANDS.test(n));
     findings.push(...quarantine(workspace, Object.keys(commandsNow).filter((n) => before.commands[n] !== commandsNow[n]), workspace, 'command'));
+    // Snapshots from before these checks existed have no baseline: checking against nothing would move your own files.
+    if (before.agent)
+        findings.push(...guardAgentFiles(workspace, before.agent));
+    if (before.repos) {
+        for (const other of otherGitDirs(workspace)) {
+            const rel = relative(workspace, other);
+            findings.push(...guardGitDir(other, before.repos[rel] ?? EMPTY_GIT).map((f) => ({ ...f, detail: rel + ': ' + f.detail })));
+        }
+    }
     const dir = plainGitDir(workspace);
     if (!dir) {
         const replaced = before.gitDir && fs.existsSync(path.join(workspace, '.git'));
@@ -140,26 +244,50 @@ export const guardRepo = (workspace, before) => {
             findings.push({ kind: 'git', detail: '.git was replaced by a link or a "gitdir:" file inside the sandbox. Do not run git in ' + workspace + ' until you have checked it.' });
         return findings;
     }
+    findings.push(...guardGitDir(dir, before));
+    return findings;
+};
+const guardGitDir = (dir, before) => {
     const hooksDir = path.join(dir, 'hooks');
     const hooksNow = filesIn(hooksDir, (n) => !n.endsWith('.sample'));
-    findings.push(...quarantine(hooksDir, Object.keys(hooksNow).filter((n) => before.hooks[n] !== hooksNow[n]), dir, 'hook'));
-    findings.push(...quarantine(dir, REDIRECTS.filter((n) => fs.existsSync(path.join(dir, n)) && !before.redirects.includes(n)), dir, 'git'));
-    findings.push(...disableConfig(dir, before.config));
-    return findings;
+    return [
+        ...quarantine(hooksDir, Object.keys(hooksNow).filter((n) => before.hooks[n] !== hooksNow[n]), dir, 'hook'),
+        ...quarantine(dir, REDIRECTS.filter((n) => fs.existsSync(path.join(dir, n)) && !before.redirects.includes(n)), dir, 'git'),
+        ...disableConfig(dir, before.config),
+    ];
+};
+/** Agent files whose runnable part changed are moved to the quarantine folder (the rest of your edits are in there too). */
+const guardAgentFiles = (workspace, before) => {
+    const changed = Object.keys(AGENT_FILES).filter((rel) => { const now = agentRisk(workspace, rel); return now !== null && now !== before[rel]; });
+    if (!changed.length)
+        return [];
+    const target = path.join(workspace, 'agent-sandbox-quarantine', String(Date.now()));
+    fs.mkdirSync(target, { recursive: true });
+    return changed.map((rel) => {
+        const what = rel + ' (the sandbox added something it would run on this PC: hooks, MCP servers, helper commands or tasks';
+        try {
+            fs.renameSync(path.join(workspace, ...rel.split('/')), path.join(target, rel.replace(/\//g, '_')));
+        }
+        catch (e) {
+            return { kind: 'agent', detail: what + '; could not be moved: ' + e.code + '. Check it before you open this folder in Claude Code or VS Code)' };
+        }
+        return { kind: 'agent', detail: what + '; moved to ' + target + ')' };
+    });
 };
 // ---- snapshot storage (host-only, next to the sync state) ---------------------------------------------------------
 const syncDir = (dataPath) => path.join(path.dirname(path.dirname(dataPath)), 'sync');
 const snapshotFile = (dataPath) => path.join(syncDir(dataPath), path.basename(dataPath) + '-repo.json');
 const findingsFile = (dataPath) => path.join(syncDir(dataPath), path.basename(dataPath) + '-repo-findings.json');
-const Finding = z.object({ kind: z.enum(['hook', 'config', 'git', 'command']), detail: z.string().max(4096), at: z.string().max(64).optional() });
+const Finding = z.object({ kind: z.enum(['hook', 'config', 'git', 'command', 'agent']), detail: z.string().max(4096), at: z.string().max(64).optional() });
+const GitStateSchema = z.object({ config: z.array(z.string()), hooks: z.record(z.string(), z.string()), redirects: z.array(z.string()) });
 const Saved = z.object({
     workspace: z.string().max(1024).refine((p) => path.isAbsolute(p)),
-    snapshot: z.object({ gitDir: z.boolean(), config: z.array(z.string()), hooks: z.record(z.string(), z.string()), redirects: z.array(z.string()), commands: z.record(z.string(), z.string()) }),
+    snapshot: GitStateSchema.extend({ gitDir: z.boolean(), commands: z.record(z.string(), z.string()), agent: z.record(z.string(), z.string()).optional(), repos: z.record(z.string(), GitStateSchema).optional() }),
 });
 const Store = z.strictObject({ projects: z.array(Saved).max(4096), roots: z.array(z.string().max(1024).refine((p) => path.isAbsolute(p))).max(64) });
 const StoreAny = z.union([Store, Saved.transform((s) => ({ projects: [s], roots: [] }))]);
 const readStore = (dataPath) => readValid(StoreAny, snapshotFile(dataPath)) ?? { projects: [], roots: [] };
-const EMPTY = { gitDir: false, config: [], hooks: {}, redirects: [], commands: {} };
+const EMPTY = { gitDir: false, config: [], hooks: {}, redirects: [], commands: {}, agent: {}, repos: {} };
 const MAX_ROOT_PROJECTS = 2000;
 /** The folders directly inside a project root (plain folders only; links are never followed). */
 const rootProjects = (root) => {

package/dist/host/stops.d.ts

@@ -0,0 +1,67 @@
+import { type ChildProcess } from 'node:child_process';
+import { z } from 'zod';
+declare const Life: 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>>;
+    }, z.core.$strip>>;
+    reported: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type LifeT = z.infer<typeof Life>;
+export declare const readLife: (storageRoot: string, dataPath: string) => LifeT | null;
+/** At launch: a fresh record (the previous one has been reported by then). */
+export declare const startLife: (storageRoot: string, dataPath: string, keepAwake: boolean, now?: Date) => void;
+/** Every minute while the sandbox runs. */
+export declare const beatLife: (storageRoot: string, dataPath: string, now?: Date) => void;
+/** The watcher saw the sandbox close while this PC kept running: closed by you (no cause), or by sleep / low memory. */
+export declare const endLife: (storageRoot: string, dataPath: string, cause: StopCause | null, now?: Date) => void;
+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;
+/**
+ * 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).
+ */
+export declare const lastStopWarning: (storageRoot: string, dataPath: string, watcherAlive: boolean, find?: (lastSeen: string) => StopCause | null) => string | null;
+/** 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.";
+/**
+ * sandbox.keepAwake: asks Windows not to sleep while the sandbox runs (as a video player does; the screen may still turn
+ * off). A small PowerShell holds the request until `ownerPid` exits, so it never outlives the watcher.
+ */
+export declare const keepAwake: (ownerPid: number) => ChildProcess | null;
+export {};

package/dist/host/stops.js

@@ -0,0 +1,126 @@
+// 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 { spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { z } from 'zod';
+import { SYSTEM } from '../shared/system.js';
+import { readValid, writeJsonAtomic } from '../shared/rundir.js';
+import { isWin } from '../core/util.js';
+import { refuseInSelfTest } from './test-guard.js';
+const Iso = z.string().max(40);
+const Life = z.object({
+    started: Iso, lastSeen: Iso, keepAwake: z.boolean(),
+    ended: z.object({ at: Iso, cause: z.object({ kind: z.enum(['updates', 'restart', 'crash', 'sleep', 'memory', 'sandboxCrash']), at: Iso, text: z.string().max(400) }).nullable() }).optional(),
+    reported: z.boolean().optional(),
+});
+const lifeFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-life.json');
+export const readLife = (storageRoot, dataPath) => readValid(Life, lifeFile(storageRoot, dataPath));
+const writeLife = (storageRoot, dataPath, life) => writeJsonAtomic(lifeFile(storageRoot, dataPath), life);
+/** At launch: a fresh record (the previous one has been reported by then). */
+export const startLife = (storageRoot, dataPath, keepAwake, now = new Date()) => writeLife(storageRoot, dataPath, { started: now.toISOString(), lastSeen: now.toISOString(), keepAwake });
+/** Every minute while the sandbox runs. */
+export const beatLife = (storageRoot, dataPath, now = new Date()) => {
+    const life = readLife(storageRoot, dataPath);
+    if (life && !life.ended)
+        writeLife(storageRoot, dataPath, { ...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. */
+export const endLife = (storageRoot, dataPath, cause, now = new Date()) => {
+    const life = readLife(storageRoot, dataPath);
+    if (life && !life.ended)
+        writeLife(storageRoot, dataPath, { ...life, ended: { at: now.toISOString(), cause } });
+};
+const StopEvents = z.array(z.object({ at: Iso, 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 === 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;
+};
+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.',
+};
+/** 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 script = "$ErrorActionPreference='SilentlyContinue'; $t=[datetime]::Parse('" + since.toISOString() + "').ToLocalTime(); $e = Get-WinEvent -FilterHashtable @(@{LogName='System'; Id=1074,6008,41,42,2004; StartTime=$t}, @{LogName='Microsoft-Windows-Hyper-V-Worker-Admin'; Id=18590; StartTime=$t}) -MaxEvents 100 | ForEach-Object { [pscustomobject]@{ at=$_.TimeCreated.ToUniversalTime().ToString('o'); id=$_.Id; provider=$_.ProviderName; process=$(if ($_.Id -eq 1074) { [string]$_.Properties[0].Value } elseif ($_.Id -eq 18590) { ([string]$_.Message).Substring(0, [math]::Min(390, ([string]$_.Message).Length)) } else { '' }) } }; ConvertTo-Json -Compress -InputObject @($e)";
+    const result = spawnSync(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { encoding: 'utf8', windowsHide: true, timeout: 60000 });
+    try {
+        return StopEvents.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)));
+const when = (iso) => new Date(iso).toLocaleString(undefined, { weekday: 'short', hour: '2-digit', minute: '2-digit' });
+/**
+ * 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).
+ */
+export const lastStopWarning = (storageRoot, dataPath, watcherAlive, find = causeSince) => {
+    const life = readLife(storageRoot, dataPath);
+    if (!life || life.reported || watcherAlive)
+        return null;
+    writeLife(storageRoot, dataPath, { ...life, reported: true });
+    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;
+    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.';
+};
+// ---- 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.';
+/**
+ * sandbox.keepAwake: asks Windows not to sleep while the sandbox runs (as a video player does; the screen may still turn
+ * off). A small PowerShell holds the request until `ownerPid` exits, so it never outlives the watcher.
+ */
+export const keepAwake = (ownerPid) => {
+    if (!isWin)
+        return null;
+    refuseInSelfTest('keep this PC awake');
+    const script = "Add-Type -Name Power -Namespace AgentSandbox -MemberDefinition '[DllImport(\"kernel32.dll\")] public static extern uint SetThreadExecutionState(uint f);'; "
+        + '[void][AgentSandbox.Power]::SetThreadExecutionState([uint32]2147483649); Wait-Process -Id ' + Math.trunc(ownerPid) + ' -ErrorAction SilentlyContinue';
+    const child = spawn(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { stdio: 'ignore', windowsHide: true });
+    child.on('error', () => undefined);
+    return child;
+};

package/dist/host/terminal.d.ts

@@ -29,4 +29,12 @@ export declare const ensureTerminal: (dataPath: string, refresh: boolean, option
     exe: string | null;
     message: string;
 }>;
+/** Where the sandbox finds conpty.dll + OpenConsole.exe (guest/ptyhost.ts points ptyhost at it). */
+export declare const conptyDir: (dataPath: string) => string;
+/**
+ * Microsoft's newer pseudo console (the Microsoft.Windows.Console.ConPTY package: conpty.dll and OpenConsole.exe, the
+ * same one Windows Terminal and VS Code use), downloaded once and verified against the SHA-512 NuGet publishes. Agent
+ * sessions use it instead of the one built into Windows, which re-renders the screen and garbles it after resizes.
+ */
+export declare const ensureConpty: (dataPath: string, refresh: boolean) => Promise<string>;
 export {};

package/dist/host/terminal.js

@@ -2,7 +2,7 @@
 // logon.cmd can open it the moment the sandbox logs in (no PowerShell window first).
 import fs from 'node:fs';
 import path from 'node:path';
-import { githubAsset, installArchive } from '../shared/download.js';
+import { download, extractArchive, fetchJson, githubAsset, installArchive, moveIntoPlace, stagingFolder } from '../shared/download.js';
 import { safeRemove } from '../shared/safe-remove.js';
 import { assertTestWritable } from './test-guard.js';
 import { z } from 'zod';
@@ -88,6 +88,50 @@ export const ensureTerminal = async (dataPath, refresh, options = {}) => {
     }
     return result;
 };
+// ---- conpty.dll ------------------------------------------------------------------------------------------------------
+/** Where the sandbox finds conpty.dll + OpenConsole.exe (guest/ptyhost.ts points ptyhost at it). */
+export const conptyDir = (dataPath) => path.join(dataPath, 'tools', 'conpty');
+const NUGET_CONPTY = 'https://api.nuget.org/v3-flatcontainer/microsoft.windows.console.conpty/';
+const NugetVersions = z.object({ versions: z.array(z.string()) });
+const NugetLeaf = z.object({ catalogEntry: z.string().url() });
+const NugetCatalog = z.object({ packageHash: z.string(), packageHashAlgorithm: z.literal('SHA512') });
+/**
+ * Microsoft's newer pseudo console (the Microsoft.Windows.Console.ConPTY package: conpty.dll and OpenConsole.exe, the
+ * same one Windows Terminal and VS Code use), downloaded once and verified against the SHA-512 NuGet publishes. Agent
+ * sessions use it instead of the one built into Windows, which re-renders the screen and garbles it after resizes.
+ */
+export const ensureConpty = async (dataPath, refresh) => {
+    const dir = conptyDir(dataPath);
+    assertTestWritable(dir);
+    assertNoLinks(dataPath, dir);
+    if (fileExists(path.join(dir, 'conpty.dll')) && fileExists(path.join(dir, 'OpenConsole.exe')) && !refresh)
+        return 'cached';
+    const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+    const work = stagingFolder(dir);
+    try {
+        const version = NugetVersions.parse(await fetchJson(NUGET_CONPTY + 'index.json')).versions.filter((v) => !v.includes('-')).pop();
+        if (!version)
+            throw new Error('no release found');
+        const leaf = NugetLeaf.parse(await fetchJson('https://api.nuget.org/v3/registration5-gz-semver2/microsoft.windows.console.conpty/' + version + '.json'));
+        const sha512 = Buffer.from(NugetCatalog.parse(await fetchJson(leaf.catalogEntry)).packageHash, 'base64').toString('hex');
+        const pkg = path.join(work, 'conpty.nupkg');
+        await download(NUGET_CONPTY + version + '/microsoft.windows.console.conpty.' + version + '.nupkg', pkg, { sha512 });
+        const files = { 'conpty.dll': 'runtimes/win-' + arch + '/native/conpty.dll', 'OpenConsole.exe': 'build/native/runtimes/' + arch + '/OpenConsole.exe' };
+        await extractArchive(pkg, path.join(work, 'x'), Object.values(files));
+        fs.mkdirSync(path.join(work, 'out'));
+        for (const [name, member] of Object.entries(files))
+            fs.copyFileSync(path.join(work, 'x', ...member.split('/')), path.join(work, 'out', name));
+        fs.writeFileSync(path.join(work, 'out', 'VERSION'), version);
+        moveIntoPlace(path.join(work, 'out'), dir);
+        return 'downloaded ' + version;
+    }
+    catch (e) {
+        return 'not downloaded, sessions use Windows\' own pseudo console (' + errMsg(e) + ')';
+    }
+    finally {
+        safeRemove(work, path.dirname(work));
+    }
+};
 const installTerminal = async (dataPath, refresh) => {
     const exe = terminalExe(dataPath);
     const dir = terminalDir(dataPath);