windows-development-sandbox 1.1.0 → 1.4.0

package/dist/host/generate.js

@@ -37,6 +37,12 @@ const hostToolsOf = (probe) => ({
     volta: Boolean(probe.volta),
     pyenv: Boolean(probe.pyenv),
 });
+/**
+ * env.cmd, which logon.cmd calls before it opens Windows Terminal: Terminal expands "%AGENT_WORKSPACE%" (the starting
+ * folder of new tabs) from its own environment, and the runtime only sets the variable machine-wide after Terminal
+ * started. `%` is doubled for cmd; a Windows path holds no quotes.
+ */
+export const logonEnv = (workspace) => '@set "AGENT_WORKSPACE=' + workspace.replace(/[\r\n"]/g, '').replace(/%/g, '%%') + '"\r\n';
 export const generateSandbox = (o) => {
     const { config, dataPath, workspaceHost, harnessName, storageRoot } = o.run;
     const harness = harnessName === 'none' ? null : config.harnesses[harnessName] ?? fail('Unknown agent: ' + harnessName, 'Configured agents: ' + Object.keys(config.harnesses).join(', '));
@@ -87,9 +93,13 @@ export const generateSandbox = (o) => {
         personalization: fs.existsSync(path.join(launchPath, 'personalize', 'personalize.reg')),
         substDrives: substDrives(mappings.map((m) => m.guest)),
         cpuLimitPercent: config.sandbox.cpuLimit === 'none' ? null : config.sandbox.cpuLimit,
+        pageFileMb: config.sandbox.pageFileMb,
+        apps: config.apps,
+        auditProcesses: config.audit.enabled && config.audit.processes,
     };
     const sessionPath = path.join(launchPath, 'session.json');
     writeJson(sessionPath, session);
+    fs.writeFileSync(path.join(launchPath, 'env.cmd'), logonEnv(session.workspace), 'utf8');
     copyRuntime(o.packageRoot, launchPath);
     stageHooks(o.packageRoot, launchPath, o.run.scripts);
     const wsbPath = path.join(launchPath, 'agent.wsb');

package/dist/host/launch/mappings.js

@@ -3,13 +3,17 @@ import { assertSafeMapping } from '../../core/safe-paths.js';
 import { dirExists, fail } from '../../core/util.js';
 import { isValidGuestPath, sandboxFolder } from '../../shared/guest-paths.js';
 import { GUEST } from './wsb.js';
+import { guestGitDir, planView } from '../workspace-view/index.js';
 export const collectMappings = (o, launchPath, boot = { roots: [], projects: [], notes: [] }) => {
     const { config, dataPath, workspaceHost, harnessName } = o.run;
     assertGuestPath(config.guestWorkspace, 'guestWorkspace');
+    // workspaceFilter: the sandbox gets the project's filtered view (no git-ignored files) and its real .git beside it.
+    const view = planView(config, o.run.storageRoot, workspaceHost);
     const mappings = [
         { host: launchPath, guest: GUEST.launch, readOnly: true },
         { host: dataPath, guest: GUEST.data, readOnly: false },
-        { host: workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly },
+        { host: view ? view.options.view : workspaceHost, guest: config.guestWorkspace, readOnly: config.readOnly },
+        ...(view?.hostGit ? [{ host: view.hostGit, guest: guestGitDir(config.guestWorkspace), readOnly: config.readOnly }] : []),
     ];
     for (const m of config.mappings) {
         const host = m.host;

package/dist/host/launch/stage.js

@@ -25,7 +25,7 @@ export const stageScripts = (target, scripts) => {
         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'];
+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) => {
     const runtime = path.join(packageRoot, 'dist', 'runtime');

package/dist/host/motw.d.ts

@@ -0,0 +1,17 @@
+/** What Windows runs when you open it (not source files such as .js or .py: those need a program you choose). */
+export declare const RISKY: RegExp;
+/** Marks one file if it is a program or script (and a plain file, not a link). Returns true when it marked it. */
+export declare const markFromSandbox: (file: string) => boolean;
+/** Has this file the mark? */
+export declare const isMarked: (file: string) => boolean;
+/** Watches the projects while the sandbox runs and marks what appears or changes; returns a function that stops it. */
+export declare const watchAndMark: (projects: string[], note?: (message: string) => void) => (() => void);
+/** The projects to watch and mark (empty: storage.markSandboxFiles is off). */
+export declare const saveMarkedProjects: (storageRoot: string, dataPath: string, projects: string[]) => void;
+export declare const readMarkedProjects: (storageRoot: string, dataPath: string) => string[];
+/** The data folder's size, measured by the watcher when a sandbox closes (measuring at launch would be slow). */
+export declare const saveDataSize: (storageRoot: string, dataPath: string, bytes: number) => void;
+export declare const readDataSize: (storageRoot: string, dataPath: string) => {
+    bytes: number;
+    at: string;
+} | null;

package/dist/host/motw.js

@@ -0,0 +1,74 @@
+// storage.markSandboxFiles: programs and scripts that appear or change in a project while a sandbox runs get Windows'
+// "downloaded from the internet" mark (the Zone.Identifier stream, zone 3). Running one on this PC then goes through
+// SmartScreen, and PowerShell's RemoteSigned policy refuses an unsigned marked script. So something an agent planted is
+// not run by a double-click or a habit. Runs in the background watcher; only the mark is written, never the file.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { readValid, writeJsonAtomic } from '../shared/rundir.js';
+/** What Windows runs when you open it (not source files such as .js or .py: those need a program you choose). */
+export const RISKY = /\.(exe|dll|com|scr|pif|msi|msix|msp|appx|appxbundle|bat|cmd|ps1|psm1|psd1|vbs|vbe|wsf|wsh|hta|lnk|url|jar|reg|cpl|application|gadget|chm)$/i;
+const MARK = '[ZoneTransfer]\r\nZoneId=3\r\nHostUrl=about:windows-development-sandbox\r\n';
+/** Folders not worth watching closely (git's own files; dependency and build folders are still marked). */
+const SKIP = /(^|[\\/])\.git([\\/]|$)/i;
+/** Marks one file if it is a program or script (and a plain file, not a link). Returns true when it marked it. */
+export const markFromSandbox = (file) => {
+    if (!RISKY.test(file) || SKIP.test(file))
+        return false;
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile())
+            return false;
+        fs.writeFileSync(file + ':Zone.Identifier', MARK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Has this file the mark? */
+export const isMarked = (file) => {
+    try {
+        return fs.readFileSync(file + ':Zone.Identifier', 'utf8').includes('ZoneId=3');
+    }
+    catch {
+        return false;
+    }
+};
+/** Watches the projects while the sandbox runs and marks what appears or changes; returns a function that stops it. */
+export const watchAndMark = (projects, note = () => undefined) => {
+    const pending = new Set();
+    let timer;
+    const flush = () => {
+        timer = undefined;
+        const marked = [...pending].filter(markFromSandbox);
+        pending.clear();
+        if (marked.length)
+            note('marked as from the sandbox (SmartScreen asks before they run here): ' + marked.slice(0, 10).map((f) => path.basename(f)).join(', ') + (marked.length > 10 ? ' and ' + (marked.length - 10) + ' more' : ''));
+    };
+    const watchers = projects.flatMap((project) => {
+        try {
+            return [fs.watch(project, { recursive: true }, (_event, file) => {
+                    const rel = file ? String(file) : '';
+                    if (!rel || !RISKY.test(rel) || SKIP.test(rel))
+                        return;
+                    pending.add(path.join(project, rel));
+                    timer ??= setTimeout(flush, 1000);
+                })];
+        }
+        catch {
+            return [];
+        }
+    });
+    return () => { watchers.forEach((w) => w.close()); clearTimeout(timer); if (pending.size)
+        flush(); };
+};
+// ---- what the watcher marks, and the size of the persisted data (host-only files next to the sync state) ----------
+const marksFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-mark.json');
+const sizeFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-size.json');
+/** The projects to watch and mark (empty: storage.markSandboxFiles is off). */
+export const saveMarkedProjects = (storageRoot, dataPath, projects) => writeJsonAtomic(marksFile(storageRoot, dataPath), projects);
+export const readMarkedProjects = (storageRoot, dataPath) => readValid(z.array(z.string().max(1024)).max(64), marksFile(storageRoot, dataPath)) ?? [];
+/** The data folder's size, measured by the watcher when a sandbox closes (measuring at launch would be slow). */
+export const saveDataSize = (storageRoot, dataPath, bytes) => writeJsonAtomic(sizeFile(storageRoot, dataPath), { bytes, at: new Date().toISOString() });
+export const readDataSize = (storageRoot, dataPath) => readValid(z.object({ bytes: z.number().min(0), at: z.string().max(40) }), sizeFile(storageRoot, dataPath));

package/dist/host/platform.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { SYSTEM } from '../shared/system.js';
 import { refuseInSelfTest } from './test-guard.js';
+import { updateRestartPending } from './stops.js';
 import { commandsDir, realAgent } from './agent-commands.js';
 import { dirExists, ensureDir, fail, fileExists, findOnPath, homeDir, isWin, realPath } from '../core/util.js';
 const findHarnessExe = (config, harnessName) => {
@@ -116,6 +117,8 @@ export const doctorRows = (config, harnessName, storageRoot, configPath) => {
         ['Windows Sandbox feature', sandboxFeatureInstalled() ? 'enabled' : 'NOT enabled'],
         ['Sandbox running', isSandboxRunning() ? 'YES' : 'no'],
         ['Free host RAM (MB)', String(Math.floor(os.freemem() / 1048576))],
+        ['Update restart pending', updateRestartPending() ? 'YES (Windows may restart on its own and close the sandbox; restart first or pause updates)' : 'no'],
+        ['Keep this PC awake', config.sandbox.keepAwake ? 'yes, while a sandbox runs' : 'no (sandbox.keepAwake is off: the PC may sleep under running agents)'],
         ['Provisioning', config.provisioning.copyFromHost ? 'copy from this PC' + (config.provisioning.fallbackToInstall ? ', fall back to download' : ', no fallback') : 'download inside sandbox'],
         ['Host Node (runner)', probe.nvmNode ? 'nvm ' + probe.hostNodeVersion : probe.nodeDir ?? '(none; will download)'],
         ['Host nvm versions', probe.nvmDir ?? '(no NVM_HOME; versions will be downloaded)'],

package/dist/host/port-forward.d.ts

@@ -0,0 +1,8 @@
+import { type PortForward } from '../shared/netpolicy.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[];
+/** The sandbox's address on this PC's Hyper-V network, from its status (null until it has one). */
+export declare const sandboxAddress: (dataPath: string) => string | null;
+/** Starts one listener per forward; returns a function that stops them. */
+export declare const startPortForwards: (forwards: PortForward[], address: () => string | null, note?: (message: string) => void) => (() => void);

package/dist/host/port-forward.js

@@ -0,0 +1,37 @@
+// network.forwardPorts, PC side: http://localhost:<pc> on this PC reaches <sandbox> inside the sandbox while it runs.
+// Runs in the background watcher. Listens on 127.0.0.1 only (nothing else on your network can use it), and connects
+// only to an address the sandbox published that is on this PC's Hyper-V network (isSandboxAddress). Bytes are passed
+// through, never looked at. No admin rights needed (no netsh portproxy).
+import net from 'node:net';
+import path from 'node:path';
+import { z } from 'zod';
+import { relayPort } from '../shared/netpolicy.js';
+import { readSandboxStatus, readValid, writeJsonAtomic } from '../shared/rundir.js';
+import { isSandboxAddress } from './attach.js';
+const Forwards = z.array(z.object({ pc: z.number().int().min(1).max(65535), sandbox: z.number().int().min(1).max(65535) })).max(64);
+const forwardsFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-forwards.json');
+/** Host-only: the forwards of the running sandbox (written at launch, read by the watcher). */
+export const saveForwards = (storageRoot, dataPath, forwards) => writeJsonAtomic(forwardsFile(storageRoot, dataPath), forwards);
+export const readForwards = (storageRoot, dataPath) => readValid(Forwards, forwardsFile(storageRoot, dataPath)) ?? [];
+/** The sandbox's address on this PC's Hyper-V network, from its status (null until it has one). */
+export const sandboxAddress = (dataPath) => readSandboxStatus(dataPath)?.addresses?.find((a) => isSandboxAddress(a)) ?? null;
+/** Starts one listener per forward; returns a function that stops them. */
+export const startPortForwards = (forwards, address, note = () => undefined) => {
+    const servers = forwards.map((f, i) => {
+        const server = net.createServer((client) => {
+            const ip = address();
+            if (!ip) {
+                client.destroy();
+                return;
+            }
+            const target = net.connect(relayPort(i), ip);
+            client.pipe(target).pipe(client);
+            target.on('error', () => client.destroy());
+            client.on('error', () => target.destroy());
+        });
+        server.on('error', (e) => note('localhost:' + f.pc + ' could not be forwarded' + (e.code === 'EADDRINUSE' ? ': something on this PC already uses that port' : ': ' + e.message)));
+        server.listen(f.pc, '127.0.0.1', () => note('localhost:' + f.pc + ' -> sandbox port ' + f.sandbox));
+        return server;
+    });
+    return () => servers.forEach((s) => s.close());
+};

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