windows-development-sandbox 1.0.5 → 1.4.0

package/dist/host/accounts.js

@@ -4,8 +4,14 @@
 // restarted in place with --continue so the conversation carries on.
 import fs from 'node:fs';
 import path from 'node:path';
+import { z } from 'zod';
+import { isSafeFileName } from '../shared/paths.js';
+import { assertTestWritable } from './test-guard.js';
+import { readValid, writeJsonAtomic } from '../shared/rundir.js';
 import { assertNoLinks, fail, fileExists, isLink, removeLink, tryReadJson, writeJson } from '../core/util.js';
 const NAME = /^[A-Za-z0-9_-]{1,40}$/;
+const AccountSchema = z.object({ name: z.string().regex(NAME), savedAt: z.string().max(64), email: z.string().max(200).nullable(), credentials: z.looseObject({}), oauthAccount: z.unknown() });
+const IndexSchema = z.object({ default: z.string().regex(NAME).optional(), active: z.record(z.string().max(200), z.string().regex(NAME)).optional() });
 const ACCOUNT_CACHES = ['remote-settings.json', 'policy-limits.json', 'policy-limits.json.stamp.json'];
 const MAX_LOGIN_BYTES = 1024 * 1024;
 /** .claude.json holds per-project state and can be large; it is still capped so a hostile file cannot exhaust memory. */
@@ -16,15 +22,17 @@ const storageOf = (dataPath) => path.dirname(path.dirname(dataPath));
 const dataName = (dataPath) => path.basename(dataPath);
 const accountFile = (storageRoot, name) => path.join(accountsDir(storageRoot), name + '.json');
 const indexFile = (storageRoot) => path.join(accountsDir(storageRoot), 'index.json');
-const readIndex = (storageRoot) => tryReadJson(indexFile(storageRoot)) ?? {};
-const updateIndex = (storageRoot, change) => writeJson(indexFile(storageRoot), change(readIndex(storageRoot)));
-const assertName = (name) => { if (!NAME.test(name))
+const readIndex = (storageRoot) => readValid(IndexSchema, indexFile(storageRoot)) ?? {};
+const updateIndex = (storageRoot, change) => writeJsonAtomic(indexFile(storageRoot), change(readIndex(storageRoot)));
+/** A file name of its own: not "index" (the index file), not a Windows device name such as con or nul. */
+const validName = (name) => NAME.test(name) && name.toLowerCase() !== 'index' && isSafeFileName(name + '.json');
+const assertName = (name) => { if (!validName(name))
     fail('Invalid account name "' + name + '".', 'Use letters, numbers, - and _ only (max 40), e.g. work or personal.'); };
 const emailOf = (oauthAccount) => {
     const email = oauthAccount?.emailAddress;
     return typeof email === 'string' ? email.slice(0, 200) : null;
 };
-export const readAccount = (storageRoot, name) => (NAME.test(name) ? tryReadJson(accountFile(storageRoot, name)) : null);
+export const readAccount = (storageRoot, name) => (validName(name) ? readValid(AccountSchema, accountFile(storageRoot, name)) : null);
 export const defaultAccount = (storageRoot) => readIndex(storageRoot).default ?? null;
 export const activeAccount = (dataPath) => readIndex(storageOf(dataPath)).active?.[dataName(dataPath)] ?? null;
 const setActive = (dataPath, name) => updateIndex(storageOf(dataPath), (i) => ({ ...i, active: { ...i.active, [dataName(dataPath)]: name } }));
@@ -51,7 +59,7 @@ const readLogin = (claudeDir, globalStateFile) => {
 };
 const store = (storageRoot, name, login) => {
     const account = { name, savedAt: new Date().toISOString(), email: emailOf(login.oauthAccount), ...login };
-    writeJson(accountFile(storageRoot, name), account);
+    writeJsonAtomic(accountFile(storageRoot, name), account);
     return account;
 };
 const sandboxLogin = (dataPath) => {
@@ -71,6 +79,7 @@ export const saveAccount = (storageRoot, dataPath, name, fromHost) => {
 };
 /** Replaces a file that may be a sandbox-planted link instead of writing through it. */
 const writeSandboxJson = (file, value) => {
+    assertTestWritable(file);
     if (isLink(file))
         removeLink(file);
     writeJson(file, value);

package/dist/host/agent-commands.d.ts

@@ -0,0 +1,25 @@
+import type { Config } from '../core/types.js';
+export declare const commandsDir: (storageRoot: string) => string;
+export interface AgentCommand {
+    harness: string;
+    command: string;
+    real: string;
+}
+/** The agent's own executable on this PC, skipping this tool's forwarding files. */
+export declare const realAgent: (command: string, skipDir: string, pathValue?: string) => string | null;
+/** The agents that get a forwarding command: installed on this PC, and listed (or "auto" = all of them). */
+export declare const agentCommands: (config: Config, storageRoot: string, pathValue?: string) => AgentCommand[];
+/** The .cmd file for one agent (cmd, PowerShell and Windows Terminal all run it). */
+export declare const forwardingCmd: (a: AgentCommand, node: string, entry: string) => string;
+/** The same for Git Bash, which looks for a file without an extension. */
+export declare const forwardingSh: (a: AgentCommand, node: string, entry: string) => string;
+export interface Reconciled {
+    on: boolean;
+    commands: AgentCommand[];
+    changed: boolean;
+}
+/**
+ * Makes this PC match agentCommands: on = a forwarding file per installed agent and the folder first on your PATH;
+ * off = no files, no PATH entry. Only touches files it wrote and its own PATH entry; does nothing when already right.
+ */
+export declare const reconcileAgentCommands: (config: Config, storageRoot: string, node: string, entry: string) => Reconciled;

package/dist/host/agent-commands.js

@@ -0,0 +1,145 @@
+// (Beta) Agent commands: with agentCommands.enabled, typing an agent's own command on this PC (claude, codex, ...) starts
+// it in a hidden sandbox for the folder you are in and attaches that terminal. Small forwarding files in
+// <storage>\agent-commands go first on YOUR PATH (so they win over npm's and the installers' copies); turning it off
+// removes the files and that one PATH entry. SANDBOX_AGENT_DIRECT=1 runs the real agent on this PC instead.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { ensureDir, fileExists } from '../core/util.js';
+import { writeFileAtomic } from '../shared/rundir.js';
+import { safeRemove } from '../shared/safe-remove.js';
+import { SYSTEM } from '../shared/system.js';
+import { refuseInSelfTest } from './test-guard.js';
+export const commandsDir = (storageRoot) => path.join(storageRoot, 'agent-commands');
+/** Marks files this tool wrote, so only those are ever replaced or removed. */
+const MARKER = 'windows-development-sandbox agent command';
+const EXTENSIONS = ['.exe', '.cmd', '.bat'];
+/** cmd.exe expands % and ^ even inside quotes: such paths cannot go into a forwarding file safely. */
+const cmdSafe = (p) => !/[%"^\r\n]/.test(p);
+/** The agent's own executable on this PC, skipping this tool's forwarding files. */
+export const realAgent = (command, skipDir, pathValue = process.env.PATH ?? process.env.Path ?? '') => {
+    const skip = path.resolve(skipDir).toLowerCase();
+    const dirs = pathValue.split(path.delimiter).filter((d) => d && path.resolve(d).toLowerCase() !== skip);
+    for (const dir of dirs)
+        for (const ext of EXTENSIONS) {
+            const candidate = path.join(dir, command + ext);
+            if (fileExists(candidate))
+                return candidate;
+        }
+    return null;
+};
+/** The agents that get a forwarding command: installed on this PC, and listed (or "auto" = all of them). */
+export const agentCommands = (config, storageRoot, pathValue) => {
+    const wanted = config.agentCommands.agents;
+    return Object.entries(config.harnesses).flatMap(([harness, h]) => {
+        if (wanted !== 'auto' && !wanted.includes(harness))
+            return [];
+        const command = h.npmBin ?? (h.hostExecutable ? path.parse(h.hostExecutable).name : harness);
+        const real = /^[A-Za-z0-9._-]+$/.test(command) ? realAgent(command, commandsDir(storageRoot), pathValue) : null;
+        return real && cmdSafe(real) ? [{ harness, command, real }] : [];
+    });
+};
+/** The .cmd file for one agent (cmd, PowerShell and Windows Terminal all run it). */
+export const forwardingCmd = (a, node, entry) => [
+    '@echo off',
+    'rem ' + MARKER + ' (Beta). Turn off: sandbox agent-commands off. Run the real one: set SANDBOX_AGENT_DIRECT=1',
+    'if "%SANDBOX_AGENT_DIRECT%"=="1" goto direct',
+    '"' + node + '" "' + entry + '" launch --harness ' + a.harness + ' --headless --terminal -- %*',
+    'exit /b %errorlevel%',
+    ':direct',
+    'call "' + a.real + '" %*',
+    '',
+].join('\r\n');
+/** The same for Git Bash, which looks for a file without an extension. */
+export const forwardingSh = (a, node, entry) => {
+    const posix = (p) => p.replace(/^([A-Za-z]):/, (_m, d) => '/' + d.toLowerCase()).replace(/\\/g, '/');
+    const q = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+    return [
+        '#!/bin/sh',
+        '# ' + MARKER + ' (Beta). Turn off: sandbox agent-commands off. Run the real one: SANDBOX_AGENT_DIRECT=1',
+        'if [ "$SANDBOX_AGENT_DIRECT" = "1" ]; then exec ' + q(posix(a.real)) + ' "$@"; fi',
+        'exec ' + q(posix(node)) + ' ' + q(posix(entry)) + ' launch --harness ' + a.harness + ' --headless --terminal -- "$@"',
+        '',
+    ].join('\n');
+};
+/** Runs a PowerShell script that edits YOUR PATH (HKCU\Environment) unexpanded, then tells Windows it changed. */
+const editUserPath = (dir, add) => {
+    refuseInSelfTest('change your PATH');
+    const quoted = "'" + dir.replace(/'/g, "''") + "'";
+    const script = [
+        '$dir = ' + quoted,
+        "$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')",
+        'try {',
+        "  $raw = [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)",
+        "  $rest = @($raw -split ';' | Where-Object { $_ -and $_.TrimEnd('\\') -ine $dir.TrimEnd('\\') })",
+        // First, so these commands win over the agents' own folders (also on YOUR PATH).
+        add ? '  $new = (@($dir) + $rest) -join \';\'' : "  $new = $rest -join ';'",
+        '  if ($new -eq $raw.TrimEnd(\';\')) { exit 0 }',
+        "  if ($new.Length -gt 32000) { Write-Error 'PATH too long'; exit 3 }",
+        "  $kind = if ($key.GetValueNames() -contains 'Path') { $key.GetValueKind('Path') } else { [Microsoft.Win32.RegistryValueKind]::ExpandString }",
+        "  $key.SetValue('Path', $new, $kind)",
+        '} finally { $key.Close() }',
+        "Add-Type -Namespace WdsAgents -Name Native -MemberDefinition '[System.Runtime.InteropServices.DllImport(\"user32.dll\", CharSet = System.Runtime.InteropServices.CharSet.Auto)] public static extern System.IntPtr SendMessageTimeout(System.IntPtr hWnd, uint msg, System.UIntPtr wParam, string lParam, uint flags, uint timeout, out System.UIntPtr result);'",
+        '$ignored = [UIntPtr]::Zero',
+        "[void][WdsAgents.Native]::SendMessageTimeout([IntPtr]0xffff, 0x1A, [UIntPtr]::Zero, 'Environment', 2, 5000, [ref]$ignored)",
+    ].join('\n');
+    const result = spawnSync(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-OutputFormat', 'Text', '-Command', script], { encoding: 'utf8', windowsHide: true });
+    if (result.status === 3)
+        throw new Error('Your PATH is too long to add ' + dir + '.');
+    if (result.status !== 0)
+        throw new Error('Could not ' + (add ? 'add ' + dir + ' to' : 'remove ' + dir + ' from') + ' your PATH: ' + (result.stderr || result.error?.message || 'exit ' + result.status).trim());
+};
+const ownFiles = (dir) => fs.existsSync(dir)
+    ? fs.readdirSync(dir).map((f) => path.join(dir, f)).filter((f) => { try {
+        return fs.lstatSync(f).isFile() && fs.readFileSync(f, 'utf8').includes(MARKER);
+    }
+    catch {
+        return false;
+    } })
+    : [];
+/**
+ * Makes this PC match agentCommands: on = a forwarding file per installed agent and the folder first on your PATH;
+ * off = no files, no PATH entry. Only touches files it wrote and its own PATH entry; does nothing when already right.
+ */
+export const reconcileAgentCommands = (config, storageRoot, node, entry) => {
+    const dir = commandsDir(storageRoot);
+    if (!config.agentCommands.enabled) {
+        if (!fs.existsSync(dir))
+            return { on: false, commands: [], changed: false };
+        for (const f of ownFiles(dir))
+            fs.rmSync(f, { force: true });
+        editUserPath(dir, false);
+        if (fs.readdirSync(dir).length === 0)
+            safeRemove(dir, storageRoot);
+        return { on: false, commands: [], changed: true };
+    }
+    if (!cmdSafe(node) || !cmdSafe(entry))
+        throw new Error('This tool is installed in a folder whose path has % " or ^, which cannot go into a command file safely.');
+    const commands = agentCommands(config, storageRoot);
+    ensureDir(dir);
+    const wanted = new Map();
+    for (const a of commands) {
+        wanted.set(path.join(dir, a.command + '.cmd'), forwardingCmd(a, node, entry));
+        wanted.set(path.join(dir, a.command), forwardingSh(a, node, entry));
+    }
+    let changed = false;
+    for (const f of ownFiles(dir))
+        if (!wanted.has(f)) {
+            fs.rmSync(f, { force: true });
+            changed = true;
+        }
+    for (const [file, text] of wanted) {
+        const current = fileExists(file) ? fs.readFileSync(file, 'utf8') : null;
+        // A file of the same name that this tool did not write is never replaced.
+        if (current !== null && !current.includes(MARKER))
+            continue;
+        if (current !== text) {
+            writeFileAtomic(file, text);
+            changed = true;
+        }
+    }
+    const onPath = (process.env.PATH ?? '').split(path.delimiter).some((d) => path.resolve(d).toLowerCase() === path.resolve(dir).toLowerCase());
+    if (changed || !onPath)
+        editUserPath(dir, true);
+    return { on: true, commands, changed: changed || !onPath };
+};

package/dist/host/attach.d.ts

@@ -0,0 +1,17 @@
+import os from 'node:os';
+import type { SessionStatus } from '../core/types.js';
+import { type Viewers } from '../shared/pty-client.js';
+/**
+ * True only for IPv4 addresses inside the subnet of one of this PC's Hyper-V adapters ("vEthernet ..."), which is
+ * where Windows Sandbox lives. Stops a compromised sandbox from pointing the host (and your keystrokes) anywhere else.
+ */
+export declare const isSandboxAddress: (ip: string, interfaces?: NodeJS.Dict<os.NetworkInterfaceInfo[]>) => boolean;
+/** Who is watching a session right now (closed terminals do not count); null when it cannot be asked. */
+export declare const sessionViewers: (session: SessionStatus) => Promise<Viewers | null>;
+/**
+ * The newest running session of this agent in exactly this folder that no terminal on this PC is attached to, so
+ * sandbox claude -t picks it back up instead of starting another. A session that cannot answer is never reused.
+ */
+export declare const findUnwatchedSession: (dataPath: string, harness: string, cwd: string) => Promise<SessionStatus | null>;
+/** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
+export declare const attachTerminal: (session: SessionStatus) => Promise<number>;

package/dist/host/attach.js

@@ -0,0 +1,70 @@
+// Attaching this terminal to an agent session inside the sandbox. Only addresses on this PC's own Hyper-V network are
+// trusted, and everything the sandbox reports is printed through safeText.
+import net from 'node:net';
+import os from 'node:os';
+import { fail, safeText, sleep } from '../core/util.js';
+import { connect, DETACH_KEY, queryViewers, runTerminalClient } from '../shared/pty-client.js';
+import { currentSessions } from './channel.js';
+import { insideSandbox } from './platform.js';
+const ipToInt = (ip) => ip.split('.').reduce((n, part) => n * 256 + Number(part), 0);
+/**
+ * True only for IPv4 addresses inside the subnet of one of this PC's Hyper-V adapters ("vEthernet ..."), which is
+ * where Windows Sandbox lives. Stops a compromised sandbox from pointing the host (and your keystrokes) anywhere else.
+ */
+export const isSandboxAddress = (ip, interfaces = os.networkInterfaces()) => {
+    if (!net.isIPv4(ip))
+        return false;
+    // WSL's adapter is a Hyper-V adapter too, but no sandbox lives there: keystrokes must never go to a WSL VM.
+    return Object.entries(interfaces).some(([name, list]) => /^vEthernet/i.test(name) && !/WSL/i.test(name) && (list ?? []).some((i) => {
+        if (i.family !== 'IPv4' || i.internal)
+            return false;
+        const mask = ipToInt(i.netmask);
+        return mask !== 0 && (ipToInt(i.address) & mask) === (ipToInt(ip) & mask) && i.address !== ip;
+    }));
+};
+/** Where this PC may connect for a session: only addresses on its own Hyper-V network (null if there are none). */
+const hostEndpoint = (session) => {
+    // Inside the sandbox every session is on loopback; on the PC only addresses on its Hyper-V network are trusted.
+    const addresses = insideSandbox() ? ['127.0.0.1'] : session.attach?.addresses.filter((a) => isSandboxAddress(a)) ?? [];
+    return session.attach && addresses.length ? { ...session.attach, addresses } : null;
+};
+/** Who is watching a session right now (closed terminals do not count); null when it cannot be asked. */
+export const sessionViewers = (session) => {
+    const endpoint = hostEndpoint(session);
+    return endpoint ? queryViewers(endpoint) : Promise.resolve(null);
+};
+/**
+ * The newest running session of this agent in exactly this folder that no terminal on this PC is attached to, so
+ * sandbox claude -t picks it back up instead of starting another. A session that cannot answer is never reused.
+ */
+export const findUnwatchedSession = async (dataPath, harness, cwd) => {
+    const candidates = currentSessions(dataPath).filter((s) => s.harness === harness && s.cwd.toLowerCase() === cwd.toLowerCase()).reverse().slice(0, 8);
+    for (const session of candidates)
+        if ((await sessionViewers(session))?.remote === 0)
+            return session;
+    return null;
+};
+/** Bridges this terminal to a session. Returns the agent's exit code, or 0 when the user detaches. */
+export const attachTerminal = async (session) => {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        fail('--terminal / attach needs an interactive terminal.', 'Run it directly in Windows Terminal or PowerShell, not through a pipe or script.');
+    if (!session.attach)
+        fail('This session cannot be attached to: networking or attach is disabled for this sandbox.', 'Set sandbox.networking and attach.enabled to true, then start a new sandbox.');
+    const endpoint = hostEndpoint(session) ?? fail('Refusing to connect: the sandbox reported no address on this PC\'s Hyper-V (vEthernet) network (' + session.attach.addresses.join(', ') + ').', 'Use the sandbox window instead (sbx-show); if this keeps happening, run sandbox doctor.');
+    const socket = await connect(endpoint);
+    console.log('Attaching to ' + safeText(session.harness) + ' session ' + session.id + ' (' + safeText(session.cwd) + '). Detach any time with Ctrl+]');
+    await sleep(400);
+    const result = await runTerminalClient(socket, session.attach.token, { detachKey: DETACH_KEY });
+    switch (result.reason) {
+        case 'detach':
+            console.log('Detached. The session keeps running; reattach with: sandbox attach ' + session.id);
+            return 0;
+        case 'exit':
+            console.log(safeText(session.harness) + ' exited with code ' + result.exitCode + '.');
+            return result.exitCode;
+        case 'error': fail('The sandbox refused the connection: ' + result.message, 'Try sandbox attach again; the session may have restarted.');
+        default:
+            console.log('Connection to the sandbox closed.');
+            return 1;
+    }
+};

package/dist/host/audit/collect.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+declare const AuditSettings: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    days: z.ZodNumber;
+    maxMb: z.ZodNumber;
+    processes: z.ZodBoolean;
+    files: z.ZodBoolean;
+    projects: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type AuditSettings = z.output<typeof AuditSettings>;
+/** Host-only: the audit settings of the running sandbox (written at launch, read by the watcher). */
+export declare const saveAuditSettings: (storageRoot: string, dataPath: string, settings: AuditSettings) => void;
+export declare const readAuditSettings: (storageRoot: string, dataPath: string) => AuditSettings | null;
+export declare class AuditCollector {
+    private readonly dataPath;
+    private readonly settings;
+    private readonly log;
+    private pending;
+    private sessions;
+    private watchers;
+    constructor(dataPath: string, storageRoot: string, settings: AuditSettings);
+    private add;
+    /** Starts watching the projects' files (when audit.files). */
+    start(): void;
+    /** Programs the sandbox reported: taken in (checked) and deleted. */
+    private takeGuestReports;
+    private trackSessions;
+    guard(detail: string): void;
+    /** Writes what came in since the last call (repeats folded); call every few seconds. */
+    flush(): void;
+    stop(): void;
+    maintain(): void;
+}
+export {};

package/dist/host/audit/collect.js

@@ -0,0 +1,126 @@
+// What goes into the audit log, from the background watcher while the sandbox runs:
+//  - programs started in the sandbox: the .jsonl files it leaves in run\audit\ (untrusted: links refused, each file
+//    and line size-capped, every line checked and forced to kind "proc"), taken in and deleted;
+//  - files changed in the projects: watched from this PC (the sandbox cannot hide or fake these);
+//  - sessions starting and ending, and what the repo guard caught.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { assertNoLinks } from '../../core/util.js';
+import { listSessions, readValid, runPaths, writeJsonAtomic } from '../../shared/rundir.js';
+import { AuditEvent, AuditLog, fold } from './log.js';
+const MAX_FILES_PER_PASS = 200;
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+/** Paths in a project not worth a line each (git's own bookkeeping, dependency folders). */
+const QUIET = /(^|[\\/])(\.git[\\/](objects|logs|refs|index\.lock|FETCH_HEAD|ORIG_HEAD)|node_modules[\\/]|target[\\/]|\.venv[\\/]|__pycache__[\\/])/i;
+const AuditSettings = z.object({
+    enabled: z.boolean(), days: z.number().int().min(1).max(365), maxMb: z.number().int().min(5).max(5000), processes: z.boolean(), files: z.boolean(),
+    projects: z.array(z.string().max(1024)).max(64),
+});
+const settingsFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-audit.json');
+/** Host-only: the audit settings of the running sandbox (written at launch, read by the watcher). */
+export const saveAuditSettings = (storageRoot, dataPath, settings) => writeJsonAtomic(settingsFile(storageRoot, dataPath), settings);
+export const readAuditSettings = (storageRoot, dataPath) => readValid(AuditSettings, settingsFile(storageRoot, dataPath));
+export class AuditCollector {
+    dataPath;
+    settings;
+    log;
+    pending = [];
+    sessions = new Map();
+    watchers = [];
+    constructor(dataPath, storageRoot, settings) {
+        this.dataPath = dataPath;
+        this.settings = settings;
+        this.log = new AuditLog(AuditLog.dirFor(storageRoot, dataPath), settings);
+    }
+    add(e) { this.pending.push({ t: new Date().toISOString(), ...e }); }
+    /** Starts watching the projects' files (when audit.files). */
+    start() {
+        this.add({ k: 'note', p: 'sandbox started; audit: ' + [this.settings.processes && 'programs', this.settings.files && 'files', 'sessions'].filter(Boolean).join(', ') });
+        if (!this.settings.files)
+            return;
+        for (const project of this.settings.projects) {
+            try {
+                this.watchers.push(fs.watch(project, { recursive: true }, (event, file) => {
+                    const rel = file ? String(file) : '';
+                    if (!rel || QUIET.test(rel))
+                        return;
+                    this.add({ k: 'file', a: event === 'rename' ? 'rename' : 'change', p: rel.replace(/\\/g, '/').slice(0, 1024), w: project });
+                }));
+            }
+            catch { /* a project that is gone */ }
+        }
+    }
+    /** Programs the sandbox reported: taken in (checked) and deleted. */
+    takeGuestReports() {
+        if (!this.settings.processes)
+            return;
+        const dir = runPaths(this.dataPath).audit;
+        assertNoLinks(this.dataPath, dir);
+        let names = [];
+        try {
+            names = fs.readdirSync(dir).filter((n) => /^[\w-]+\.jsonl$/.test(n)).sort().slice(0, MAX_FILES_PER_PASS);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const file = path.join(dir, name);
+            try {
+                const stat = fs.lstatSync(file);
+                if (stat.isFile() && stat.size <= MAX_FILE_BYTES) {
+                    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+                        if (!line.trim() || line.length > 8192)
+                            continue;
+                        let raw;
+                        try {
+                            raw = JSON.parse(line);
+                        }
+                        catch {
+                            continue;
+                        }
+                        const e = AuditEvent.safeParse(raw);
+                        if (e.success)
+                            this.pending.push({ ...e.data, k: 'proc', w: undefined, a: undefined });
+                    }
+                }
+            }
+            finally {
+                fs.rmSync(file, { force: true });
+            }
+        }
+    }
+    trackSessions() {
+        const now = new Map(listSessions(this.dataPath).map((s) => [s.id, s.phase]));
+        for (const s of listSessions(this.dataPath)) {
+            const before = this.sessions.get(s.id);
+            if (!before && s.phase === 'running')
+                this.add({ k: 'session', a: 'start', p: s.harness, w: s.cwd, c: s.id });
+            if (before === 'running' && (s.phase === 'exited' || s.phase === 'failed'))
+                this.add({ k: 'session', a: 'end', p: s.harness, w: s.cwd, c: s.id + (s.exitCode !== undefined ? ' exit ' + s.exitCode : '') });
+        }
+        this.sessions = now;
+    }
+    guard(detail) { this.add({ k: 'guard', p: detail.slice(0, 1024) }); }
+    /** Writes what came in since the last call (repeats folded); call every few seconds. */
+    flush() {
+        try {
+            this.takeGuestReports();
+        }
+        catch { /* next pass */ }
+        try {
+            this.trackSessions();
+        }
+        catch { /* next pass */ }
+        const events = this.pending.sort((a, b) => a.t.localeCompare(b.t));
+        this.pending = [];
+        this.log.append(fold(events));
+    }
+    stop() {
+        this.watchers.forEach((w) => w.close());
+        this.add({ k: 'note', p: 'sandbox closed' });
+        this.flush();
+        this.log.maintain();
+    }
+    maintain() { this.log.maintain(); }
+}

package/dist/host/audit/log.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+/** One event. k: proc (a program started), file (changed in a project), session, guard (repo guard), note. */
+export declare const AuditEvent: z.ZodObject<{
+    t: z.ZodString;
+    k: z.ZodEnum<{
+        file: "file";
+        session: "session";
+        proc: "proc";
+        guard: "guard";
+        note: "note";
+    }>;
+    p: z.ZodOptional<z.ZodString>;
+    c: z.ZodOptional<z.ZodString>;
+    pp: z.ZodOptional<z.ZodString>;
+    a: z.ZodOptional<z.ZodString>;
+    w: z.ZodOptional<z.ZodString>;
+    n: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AuditEvent = z.output<typeof AuditEvent>;
+export declare class AuditLog {
+    readonly dir: string;
+    private readonly limits;
+    constructor(dir: string, limits: {
+        days: number;
+        maxMb: number;
+    });
+    /** <storage>\audit\<data set name>. */
+    static dirFor(storageRoot: string, dataPath: string): string;
+    private dayFile;
+    append(events: AuditEvent[]): void;
+    /** Compresses finished days, then deletes days past the limits. Cheap when there is nothing to do. */
+    maintain(today?: string): void;
+    /** Events of the last `days` days (newest last), optionally of some kinds and containing a text. */
+    read(o?: {
+        days?: number;
+        kinds?: AuditEvent['k'][];
+        grep?: string;
+    }): AuditEvent[];
+    /** Total size on disk. */
+    bytes(): number;
+}
+/**
+ * Folds repeats: the same event (kind, program/path, command line, action, project) within one minute becomes one line
+ * with n = how many times; after `cap` distinct lines a minute, the rest of that minute is one "note" line.
+ */
+export declare const fold: (events: AuditEvent[], cap?: number) => AuditEvent[];