windows-development-sandbox 1.0.5 → 1.4.0

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;
@@ -15,8 +22,21 @@ export declare const snapshotRepo: (workspace: string) => RepoSnapshot;
  * Returns what was found (and fixed). Never touches what was already there before the sandbox ran.
  */
 export declare const guardRepo: (workspace: string, before: RepoSnapshot) => RepoFinding[];
-export declare const saveRepoSnapshot: (dataPath: string, workspace: string) => void;
-/** Re-checks the workspace of the current/last launch; findings are kept in a host-only file for `status`. */
+/**
+ * At launch: every folder the sandbox will be able to write. The launch folder, projects mapped with it and every
+ * project already inside a project root are snapshotted as they are now, before the sandbox can touch them.
+ */
+export declare const saveRepoSnapshot: (dataPath: string, workspace: string, more?: string[], roots?: string[]) => void;
+/**
+ * A project that joins the running sandbox: snapshotted before its first session, then guarded like the launch
+ * folder. A project already guarded keeps its first snapshot (what was there before the sandbox could touch it).
+ */
+export declare const addRepoSnapshot: (dataPath: string, workspace: string, o?: {
+    empty?: boolean;
+}) => void;
+/** The folders being guarded (for status). */
+export declare const guardedProjects: (dataPath: string) => string[];
+/** Re-checks every project of the current/last launch; findings are kept in a host-only file for `status`. Returns the new ones. */
 export declare const checkRepo: (dataPath: string) => RepoFinding[];
 export declare const repoFindings: (dataPath: string) => (RepoFinding & {
     at?: string;

package/dist/host/repo-guard.js

@@ -6,14 +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 { dirExists, fileExists, isLink, tryReadJson, writeJson } from '../core/util.js';
+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. */
@@ -30,7 +38,65 @@ 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');
-const hash = (file) => (isLink(file) ? 'link' : crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'));
+/**
+ * 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))
+        return 'link';
+    const sum = crypto.createHash('sha256');
+    const buffer = Buffer.alloc(1 << 20);
+    let fd;
+    // A file that cannot be read (locked by a program in the sandbox) never matches the snapshot, so it is dealt with.
+    try {
+        fd = fs.openSync(file, 'r');
+    }
+    catch {
+        return 'unreadable-' + crypto.randomBytes(4).toString('hex');
+    }
+    try {
+        for (let n = fs.readSync(fd, buffer, 0, buffer.length, null); n > 0; n = fs.readSync(fd, buffer, 0, buffer.length, null))
+            sum.update(buffer.subarray(0, n));
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return sum.digest('hex');
+};
+const MAX_CONFIG_BYTES = 4 * 1024 * 1024;
 const plainGitDir = (workspace) => {
     const dir = path.join(workspace, '.git');
     return dirExists(dir) && !isLink(dir) ? dir : null;
@@ -40,16 +106,68 @@ const filesIn = (dir, accept) => dirExists(dir) && !isLink(dir)
     : {};
 const configLines = (dir) => {
     const file = path.join(dir, 'config');
-    return fileExists(file) && !isLink(file) ? fs.readFileSync(file, 'utf8').split(/\r?\n/) : [];
+    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. */
@@ -59,7 +177,12 @@ const quarantine = (from, names, into, kind) => {
     const target = path.join(into, 'agent-sandbox-quarantine', String(Date.now()));
     fs.mkdirSync(target, { recursive: true });
     return names.map((name) => {
-        fs.renameSync(path.join(from, name), path.join(target, name));
+        try {
+            fs.renameSync(path.join(from, name), path.join(target, name));
+        }
+        catch (e) {
+            return { kind, detail: name + ' (could not be moved: ' + e.code + '; delete it yourself before running anything here)' };
+        }
         return { kind, detail: name + ' (moved to ' + target + ')' };
     });
 };
@@ -70,22 +193,30 @@ 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();
     });
     if (findings.length)
-        fs.writeFileSync(path.join(dir, 'config'), fixed.join('\n'), 'utf8');
+        writeFileAtomic(path.join(dir, 'config'), fixed.join('\n'));
+    const file = path.join(dir, 'config');
+    // A link or a huge file is not read at all, so say so instead of letting it pass as "nothing found".
+    const unchecked = isLink(file) ? '.git/config is a link' : lines.length === 0 && fileExists(file) && fs.statSync(file).size > MAX_CONFIG_BYTES ? '.git/config is over 4 MB' : null;
+    if (unchecked)
+        findings.push({ kind: 'git', detail: unchecked + ', so it cannot be checked. Do not run git in this folder until you have looked at it.' });
     return findings;
 };
 /**
@@ -93,9 +224,19 @@ const disableConfig = (dir, before) => {
  * Returns what was found (and fixed). Never touches what was already there before the sandbox ran.
  */
 export const guardRepo = (workspace, before) => {
+    assertTestWritable(workspace);
     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'));
@@ -103,26 +244,104 @@ 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');
-export const saveRepoSnapshot = (dataPath, workspace) => writeJson(snapshotFile(dataPath), { workspace, snapshot: snapshotRepo(workspace) });
-/** Re-checks the workspace of the current/last launch; findings are kept in a host-only file for `status`. */
+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: 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: {}, agent: {}, repos: {} };
+const MAX_ROOT_PROJECTS = 2000;
+/** The folders directly inside a project root (plain folders only; links are never followed). */
+const rootProjects = (root) => {
+    if (!dirExists(root) || isLink(root))
+        return [];
+    return fs.readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.isSymbolicLink()).slice(0, MAX_ROOT_PROJECTS).map((e) => path.join(root, e.name));
+};
+const has = (projects, workspace) => projects.some((s) => s.workspace.toLowerCase() === workspace.toLowerCase());
+/**
+ * At launch: every folder the sandbox will be able to write. The launch folder, projects mapped with it and every
+ * project already inside a project root are snapshotted as they are now, before the sandbox can touch them.
+ */
+export const saveRepoSnapshot = (dataPath, workspace, more = [], roots = []) => {
+    const folders = _.uniqBy([workspace, ...more, ...roots.flatMap((r) => [r, ...rootProjects(r)])], (w) => w.toLowerCase());
+    writeJsonAtomic(snapshotFile(dataPath), { projects: folders.map((w) => ({ workspace: w, snapshot: snapshotRepo(w) })), roots });
+};
+/**
+ * A project that joins the running sandbox: snapshotted before its first session, then guarded like the launch
+ * folder. A project already guarded keeps its first snapshot (what was there before the sandbox could touch it).
+ */
+export const addRepoSnapshot = (dataPath, workspace, o = {}) => {
+    const store = readStore(dataPath);
+    // A folder inside one that is guarded already is covered by it only for its root files; it gets its own entry.
+    if (has(store.projects, workspace))
+        return;
+    writeJsonAtomic(snapshotFile(dataPath), { ...store, projects: [...store.projects, { workspace, snapshot: o.empty ? EMPTY : snapshotRepo(workspace) }] });
+};
+/**
+ * Folders that appeared inside a project root after the launch: the sandbox could have written them from the start,
+ * so they get an EMPTY baseline: any git hook, git config that runs programs (core.hooksPath, core.fsmonitor, ...)
+ * or planted command in them counts as added inside the sandbox and is neutralised.
+ */
+const discoverRootProjects = (dataPath) => {
+    const store = readStore(dataPath);
+    const found = store.roots.flatMap(rootProjects).filter((w) => !has(store.projects, w)).map((workspace) => ({ workspace, snapshot: EMPTY }));
+    if (!found.length)
+        return store.projects;
+    const projects = [...store.projects, ...found].slice(0, 4096);
+    writeJsonAtomic(snapshotFile(dataPath), { ...store, projects });
+    return projects;
+};
+/** The folders being guarded (for status). */
+export const guardedProjects = (dataPath) => readStore(dataPath).projects.map((s) => s.workspace);
+/** Re-checks every project of the current/last launch; findings are kept in a host-only file for `status`. Returns the new ones. */
 export const checkRepo = (dataPath) => {
-    const saved = tryReadJson(snapshotFile(dataPath));
-    if (!saved?.snapshot?.commands)
+    const saved = discoverRootProjects(dataPath);
+    if (!saved.length)
         return [];
-    const findings = guardRepo(saved.workspace, saved.snapshot);
+    const old = repoFindings(dataPath);
+    // A finding that cannot be fixed (a file locked in the sandbox) is reported once, not every minute.
+    const findings = saved.flatMap((s) => guardRepo(s.workspace, s.snapshot).map((f) => (saved.length > 1 ? { ...f, detail: s.workspace + ': ' + f.detail } : f)))
+        .filter((f) => !old.some((o) => o.kind === f.kind && o.detail === f.detail));
     if (findings.length)
-        writeJson(findingsFile(dataPath), [...repoFindings(dataPath), ...findings.map((f) => ({ ...f, at: new Date().toISOString() }))]);
+        writeJsonAtomic(findingsFile(dataPath), [...old, ...findings.map((f) => ({ ...f, at: new Date().toISOString() }))]);
     return findings;
 };
-export const repoFindings = (dataPath) => tryReadJson(findingsFile(dataPath)) ?? [];
+export const repoFindings = (dataPath) => readValid(z.array(Finding).max(10000), findingsFile(dataPath)) ?? [];

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 {};