windows-development-sandbox 1.4.1 → 1.5.0

package/dist/guest/toolchains/version-cache.js

@@ -0,0 +1,67 @@
+// Versions looked up online, remembered in tools\resolved-versions.json so most boots make no lookups and an offline
+// boot reuses what was installed last time.
+import fs from 'node:fs';
+import { z } from 'zod';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { warn } from '../runtime/log.js';
+import { session } from '../runtime/session.js';
+import { toolsDir } from '../runtime/paths.js';
+import { errMsg } from '../../core/util/errors.js';
+import { tool } from './tool-env.js';
+import { readState } from './state-file.js';
+/** A remembered lookup; plain strings are what older versions wrote (treated as stale, still usable offline). */
+const ResolvedSchema = z.record(z.string(), z.union([z.string(), z.strictObject({ value: z.string(), at: z.number() })]));
+/** How long a looked-up version is trusted: boots within a day make no version lookups at all. */
+const FRESH_MS = 24 * 60 * 60 * 1000;
+function isNetworkError(e) {
+    return /fetch failed|timed? ?out|aborted|ENOTFOUND|EAI_AGAIN|ECONN|ENETUNREACH|EHOSTUNREACH|HTTP 5\d\d|socket/i.test(errMsg(e) + ' ' + String(e?.cause ?? ''));
+}
+export class VersionCache {
+    file;
+    /** Set after a network failure: the remaining lookups go straight to the remembered versions. */
+    offline = false;
+    constructor(file = () => tool('resolved-versions.json')) {
+        this.file = file;
+    }
+    /**
+     * Resolves a version online and remembers it for a day (provisioning.refresh looks again). After a network failure
+     * the remaining lookups use the remembered versions instead of each waiting for the network; other errors (no such
+     * version) do not.
+     */
+    async resolve(key, resolve) {
+        const cached = this.remembered()[key];
+        if (cached && (this.offline || (!session.provisioning.refresh && Date.now() - cached.at < FRESH_MS)))
+            return cached.value;
+        try {
+            const value = await resolve();
+            fs.mkdirSync(toolsDir, { recursive: true });
+            writeJsonAtomic(this.file(), { ...this.remembered(), [key]: { value, at: Date.now() } });
+            return value;
+        }
+        catch (e) {
+            if (isNetworkError(e))
+                this.offline = true;
+            if (!cached)
+                throw e;
+            warn('Could not look up the latest ' +
+                key +
+                ' online (' +
+                errMsg(e) +
+                '); using ' +
+                cached.value +
+                ' from an earlier start.');
+            return cached.value;
+        }
+    }
+    remembered() {
+        return Object.fromEntries(Object.entries(readState(this.file(), ResolvedSchema, {})).map(([k, v]) => [
+            k,
+            typeof v === 'string' ? { value: v, at: 0 } : v,
+        ]));
+    }
+}
+export const versionCache = new VersionCache();
+/** versionCache.resolve: the version for `key`, looked up at most once a day. */
+export function resolveCached(key, resolve) {
+    return versionCache.resolve(key, resolve);
+}

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

@@ -0,0 +1,13 @@
+import type { Config } from '../../core/types.js';
+export declare function commandsDir(storageRoot: string): string;
+export interface AgentCommand {
+    harness: string;
+    command: string;
+    real: string;
+}
+/** cmd.exe expands % and ^ even inside quotes: such paths cannot go into a forwarding file safely. */
+export declare function cmdSafe(p: string): boolean;
+/** The agent's own executable on this PC, skipping this tool's forwarding files. */
+export declare function 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 function agentCommands(config: Config, storageRoot: string, pathValue?: string): AgentCommand[];

package/dist/host/agent-commands/commands.js

@@ -0,0 +1,37 @@
+// (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 path from 'node:path';
+import { fileExists } from '../../core/util/index.js';
+export function commandsDir(storageRoot) {
+    return path.join(storageRoot, 'agent-commands');
+}
+const EXTENSIONS = ['.exe', '.cmd', '.bat'];
+/** cmd.exe expands % and ^ even inside quotes: such paths cannot go into a forwarding file safely. */
+export function cmdSafe(p) {
+    return !/[%"^\r\n]/.test(p);
+}
+/** The agent's own executable on this PC, skipping this tool's forwarding files. */
+export function 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 function 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 }] : [];
+    });
+}

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

@@ -0,0 +1,7 @@
+import type { AgentCommand } from './commands.js';
+/** Marks files this tool wrote, so only those are ever replaced or removed. */
+export declare const MARKER = "windows-development-sandbox agent command";
+/** The .cmd file for one agent (cmd, PowerShell and Windows Terminal all run it). */
+export declare function forwardingCmd(a: AgentCommand, node: string, entry: string): string;
+/** The same for Git Bash, which looks for a file without an extension. */
+export declare function forwardingSh(a: AgentCommand, node: string, entry: string): string;

package/dist/host/agent-commands/forwarders.js

@@ -0,0 +1,33 @@
+/** Marks files this tool wrote, so only those are ever replaced or removed. */
+export const MARKER = 'windows-development-sandbox agent command';
+/** The .cmd file for one agent (cmd, PowerShell and Windows Terminal all run it). */
+export function forwardingCmd(a, node, entry) {
+    return [
+        '@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 function 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');
+}

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

@@ -0,0 +1,4 @@
+export * from './commands.js';
+export * from './forwarders.js';
+export * from './user-path.js';
+export * from './reconcile.js';

package/dist/host/agent-commands/index.js

@@ -0,0 +1,4 @@
+export * from './commands.js';
+export * from './forwarders.js';
+export * from './user-path.js';
+export * from './reconcile.js';

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

@@ -0,0 +1,12 @@
+import type { Config } from '../../core/types.js';
+import { type AgentCommand } from './commands.js';
+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 function reconcileAgentCommands(config: Config, storageRoot: string, node: string, entry: string): Reconciled;

package/dist/host/agent-commands/reconcile.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureDir, fileExists } from '../../core/util/index.js';
+import { writeFileAtomic } from '../../shared/io/index.js';
+import { safeRemove } from '../../shared/io/index.js';
+import { MARKER, forwardingCmd, forwardingSh } from './forwarders.js';
+import { commandsDir, cmdSafe, agentCommands } from './commands.js';
+import { editUserPath } from './user-path.js';
+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 function 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, storageRoot);
+        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, storageRoot);
+    return { on: true, commands, changed: changed || !onPath };
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Edits YOUR PATH (HKCU\Environment) unexpanded, then tells Windows it changed: HostTools.exe user-path (built in
+ * <storageRoot>\bin), else native\scripts\edit-user-path.ps1.
+ */
+export declare function editUserPath(dir: string, add: boolean, storageRoot: string): void;

package/dist/host/agent-commands/user-path.js

@@ -0,0 +1,25 @@
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { refuseInSelfTest } from '../test-guard.js';
+import { hostToolsExe, nativeScript } from '../native.js';
+/** Exit code of HostTools user-path / edit-user-path.ps1 when PATH would pass 32000 characters. */
+const TOO_LONG = 3;
+/**
+ * Edits YOUR PATH (HKCU\Environment) unexpanded, then tells Windows it changed: HostTools.exe user-path (built in
+ * <storageRoot>\bin), else native\scripts\edit-user-path.ps1.
+ */
+export function editUserPath(dir, add, storageRoot) {
+    refuseInSelfTest('change your PATH');
+    const tools = hostToolsExe(storageRoot);
+    const options = { encoding: 'utf8', windowsHide: true };
+    const result = tools
+        ? spawnSync(tools, ['user-path', add ? '--add' : '--remove', dir], options)
+        : spawnSync(SYSTEM.powershell(), nativeScript('edit-user-path.ps1', ['-Dir', dir, ...(add ? ['-Add'] : [])]), options);
+    if (result.status === TOO_LONG)
+        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());
+}

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-declare const AuditSettings: z.ZodObject<{
+declare const AuditSettingsSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
     days: z.ZodNumber;
     maxMb: z.ZodNumber;
@@ -7,10 +7,10 @@ declare const AuditSettings: z.ZodObject<{
     files: z.ZodBoolean;
     projects: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
-export type AuditSettings = z.output<typeof AuditSettings>;
+export type AuditSettings = z.output<typeof AuditSettingsSchema>;
 /** 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 function saveAuditSettings(storageRoot: string, dataPath: string, settings: AuditSettings): void;
+export declare function readAuditSettings(storageRoot: string, dataPath: string): AuditSettings | null;
 export declare class AuditCollector {
     private readonly dataPath;
     private readonly settings;

package/dist/host/audit/collect.js

@@ -6,21 +6,31 @@
 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';
+import { assertNoLinks } from '../../core/util/index.js';
+import { RunDir } from '../../shared/channel/index.js';
+import { JsonFile } from '../../shared/io/index.js';
+import { hostStateFile } from '../storage/index.js';
+import { AuditEventSchema, 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(),
+const AuditSettingsSchema = 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');
+const settingsFile = (storageRoot, dataPath) => new JsonFile(AuditSettingsSchema, hostStateFile(storageRoot, 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 function saveAuditSettings(storageRoot, dataPath, settings) {
+    return settingsFile(storageRoot, dataPath).write(settings);
+}
+export function readAuditSettings(storageRoot, dataPath) {
+    return settingsFile(storageRoot, dataPath).read();
+}
 export class AuditCollector {
     dataPath;
     settings;
@@ -33,10 +43,16 @@ export class AuditCollector {
         this.settings = settings;
         this.log = new AuditLog(AuditLog.dirFor(storageRoot, dataPath), settings);
     }
-    add(e) { this.pending.push({ t: new Date().toISOString(), ...e }); }
+    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(', ') });
+        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) {
@@ -45,21 +61,32 @@ export class AuditCollector {
                     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 });
+                    this.add({
+                        k: 'file',
+                        a: event === 'rename' ? 'rename' : 'change',
+                        p: rel.replace(/\\/g, '/').slice(0, 1024),
+                        w: project,
+                    });
                 }));
             }
-            catch { /* a project that is gone */ }
+            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;
+        const dir = new RunDir(this.dataPath).auditDir;
         assertNoLinks(this.dataPath, dir);
         let names = [];
         try {
-            names = fs.readdirSync(dir).filter((n) => /^[\w-]+\.jsonl$/.test(n)).sort().slice(0, MAX_FILES_PER_PASS);
+            names = fs
+                .readdirSync(dir)
+                .filter((n) => /^[\w-]+\.jsonl$/.test(n))
+                .sort()
+                .slice(0, MAX_FILES_PER_PASS);
         }
         catch {
             return;
@@ -79,7 +106,7 @@ export class AuditCollector {
                         catch {
                             continue;
                         }
-                        const e = AuditEvent.safeParse(raw);
+                        const e = AuditEventSchema.safeParse(raw);
                         if (e.success)
                             this.pending.push({ ...e.data, k: 'proc', w: undefined, a: undefined });
                     }
@@ -91,27 +118,39 @@ export class AuditCollector {
         }
     }
     trackSessions() {
-        const now = new Map(listSessions(this.dataPath).map((s) => [s.id, s.phase]));
-        for (const s of listSessions(this.dataPath)) {
+        const now = new Map(new RunDir(this.dataPath).listSessions().map((s) => [s.id, s.phase]));
+        for (const s of new RunDir(this.dataPath).listSessions()) {
             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.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) }); }
+    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 */ }
+        catch {
+            /* next pass */
+        }
         try {
             this.trackSessions();
         }
-        catch { /* next pass */ }
+        catch {
+            /* next pass */
+        }
         const events = this.pending.sort((a, b) => a.t.localeCompare(b.t));
         this.pending = [];
         this.log.append(fold(events));
@@ -122,5 +161,7 @@ export class AuditCollector {
         this.flush();
         this.log.maintain();
     }
-    maintain() { this.log.maintain(); }
+    maintain() {
+        this.log.maintain();
+    }
 }

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

@@ -1,6 +1,6 @@
 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<{
+export declare const AuditEventSchema: z.ZodObject<{
     t: z.ZodString;
     k: z.ZodEnum<{
         file: "file";
@@ -16,7 +16,7 @@ export declare const AuditEvent: z.ZodObject<{
     w: z.ZodOptional<z.ZodString>;
     n: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
-export type AuditEvent = z.output<typeof AuditEvent>;
+export type AuditEvent = z.output<typeof AuditEventSchema>;
 export declare class AuditLog {
     readonly dir: string;
     private readonly limits;
@@ -43,4 +43,4 @@ export declare class AuditLog {
  * 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[];
+export declare function fold(events: AuditEvent[], cap?: number): AuditEvent[];

package/dist/host/audit/log.js

@@ -6,7 +6,7 @@ import path from 'node:path';
 import zlib from 'node:zlib';
 import { z } from 'zod';
 /** One event. k: proc (a program started), file (changed in a project), session, guard (repo guard), note. */
-export const AuditEvent = z.object({
+export const AuditEventSchema = z.object({
     /** ISO time. */
     t: z.string().max(40),
     k: z.enum(['proc', 'file', 'session', 'guard', 'note']),
@@ -32,8 +32,12 @@ export class AuditLog {
         this.limits = limits;
     }
     /** <storage>\audit\<data set name>. */
-    static dirFor(storageRoot, dataPath) { return path.join(storageRoot, 'audit', path.basename(dataPath)); }
-    dayFile(day, gz = false) { return path.join(this.dir, day + '.jsonl' + (gz ? '.gz' : '')); }
+    static dirFor(storageRoot, dataPath) {
+        return path.join(storageRoot, 'audit', path.basename(dataPath));
+    }
+    dayFile(day, gz = false) {
+        return path.join(this.dir, day + '.jsonl' + (gz ? '.gz' : ''));
+    }
     append(events) {
         if (!events.length)
             return;
@@ -61,10 +65,16 @@ export class AuditLog {
             fs.rmSync(file);
         }
         const oldest = new Date(Date.parse(today) - (this.limits.days - 1) * 86400000).toISOString().slice(0, 10);
-        const files = fs.readdirSync(this.dir).filter((n) => DAY_FILE.test(n)).sort();
+        const files = fs
+            .readdirSync(this.dir)
+            .filter((n) => DAY_FILE.test(n))
+            .sort();
         for (const name of files.filter((n) => DAY_FILE.exec(n)[1] < oldest))
             fs.rmSync(path.join(this.dir, name), { force: true });
-        let left = fs.readdirSync(this.dir).filter((n) => DAY_FILE.test(n)).sort();
+        let left = fs
+            .readdirSync(this.dir)
+            .filter((n) => DAY_FILE.test(n))
+            .sort();
         const size = () => left.reduce((sum, n) => sum + fs.statSync(path.join(this.dir, n)).size, 0);
         while (left.length > 1 && size() > this.limits.maxMb * 1024 * 1024) {
             fs.rmSync(path.join(this.dir, left[0]), { force: true });
@@ -78,7 +88,10 @@ export class AuditLog {
         const since = new Date(Date.now() - ((o.days ?? 1) - 1) * 86400000).toISOString().slice(0, 10);
         const needle = o.grep?.toLowerCase();
         const events = [];
-        for (const name of fs.readdirSync(this.dir).filter((n) => DAY_FILE.test(n) && DAY_FILE.exec(n)[1] >= since).sort()) {
+        for (const name of fs
+            .readdirSync(this.dir)
+            .filter((n) => DAY_FILE.test(n) && DAY_FILE.exec(n)[1] >= since)
+            .sort()) {
             const raw = fs.readFileSync(path.join(this.dir, name));
             const text = name.endsWith('.gz') ? zlib.gunzipSync(raw).toString('utf8') : raw.toString('utf8');
             for (const line of text.split('\n')) {
@@ -91,7 +104,7 @@ export class AuditLog {
                 catch {
                     continue;
                 }
-                const e = AuditEvent.safeParse(parsed);
+                const e = AuditEventSchema.safeParse(parsed);
                 if (!e.success)
                     continue;
                 if (o.kinds?.length && !o.kinds.includes(e.data.k))
@@ -107,14 +120,17 @@ export class AuditLog {
     bytes() {
         if (!fs.existsSync(this.dir))
             return 0;
-        return fs.readdirSync(this.dir).filter((n) => DAY_FILE.test(n)).reduce((sum, n) => sum + fs.statSync(path.join(this.dir, n)).size, 0);
+        return fs
+            .readdirSync(this.dir)
+            .filter((n) => DAY_FILE.test(n))
+            .reduce((sum, n) => sum + fs.statSync(path.join(this.dir, n)).size, 0);
     }
 }
 /**
  * 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 const fold = (events, cap = 300) => {
+export function fold(events, cap = 300) {
     const out = [];
     const index = new Map();
     const perMinute = new Map();
@@ -140,4 +156,4 @@ export const fold = (events, cap = 300) => {
     for (const [minute, n] of dropped)
         out.push({ t: minute + ':59.999Z', k: 'note', p: n + ' more events in this minute were not listed (audit cap)' });
     return out;
-};
+}

package/dist/host/channel/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/index.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 function 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 function 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 function 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 function attachTerminal(session: SessionStatus): Promise<number>;