windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/shared/safe-remove.js

@@ -0,0 +1,55 @@
+// The one way this tool deletes a folder tree. A recursive delete that resolved to the wrong place (an empty
+// variable, a relative path, a planted link) must never be able to take a user profile, a drive or Windows with it.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const norm = (p) => path.resolve(p).replace(/[\\/]+$/, '').toLowerCase();
+const isAncestorOrSame = (parent, child) => { const a = norm(parent); const b = norm(child); return a === b || b.startsWith(a + path.sep); };
+/** Folders no delete may ever reach, or contain: profiles, Windows, program folders. */
+const protectedFolders = () => [
+    os.homedir(), process.env.USERPROFILE, process.env.APPDATA, process.env.LOCALAPPDATA, path.join(os.homedir(), 'Documents'), path.join(os.homedir(), 'Desktop'),
+    process.env.SystemRoot, process.env.WINDIR, process.env.ProgramFiles, process.env['ProgramFiles(x86)'], process.env.ProgramData, 'C:\\Users', 'C:\\Windows',
+].filter((p) => typeof p === 'string' && p.trim() !== '');
+/**
+ * Why `target` may not be deleted, or null when it may. Refused: a relative path, a drive root, a protected folder or
+ * any folder that contains one, and anything that is not strictly inside `root`.
+ */
+export const removeRefusal = (target, root) => {
+    if (!target || !path.isAbsolute(target) || !root || !path.isAbsolute(root))
+        return 'not an absolute path';
+    const t = norm(target);
+    if (t === norm(path.parse(t).root))
+        return 'a drive root';
+    const hit = protectedFolders().find((p) => isAncestorOrSame(t, p));
+    if (hit)
+        return 'it is, or contains, ' + hit;
+    if (!t.startsWith(norm(root) + path.sep))
+        return 'it is not inside ' + root;
+    return null;
+};
+/**
+ * Deletes `target` (a folder tree or file) only when it is strictly inside `root` and nothing protected; a link is
+ * removed itself, never followed. Throws instead of deleting anything else.
+ */
+export const safeRemove = (target, root) => {
+    const refusal = removeRefusal(target, root);
+    if (refusal)
+        throw new Error('Refusing to delete ' + target + ': ' + refusal);
+    let stat;
+    try {
+        stat = fs.lstatSync(target);
+    }
+    catch {
+        return;
+    }
+    if (stat.isSymbolicLink()) {
+        try {
+            fs.unlinkSync(target);
+        }
+        catch {
+            fs.rmdirSync(target);
+        }
+        return;
+    }
+    fs.rmSync(target, { recursive: true, force: true, maxRetries: 2 });
+};

package/dist/shared/schema.d.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+export declare const Id: z.ZodString;
+export declare const AttachEndpoint: z.ZodObject<{
+    addresses: z.ZodArray<z.ZodString>;
+    port: z.ZodNumber;
+    token: z.ZodString;
+}, z.core.$strict>;
+/** C:\AgentData\run\sandbox.json: boot progress of the sandbox as a whole. */
+export declare const SandboxStatus: z.ZodObject<{
+    launchId: z.ZodString;
+    phase: z.ZodEnum<{
+        provisioning: "provisioning";
+        booting: "booting";
+        ready: "ready";
+        failed: "failed";
+    }>;
+    message: z.ZodString;
+    updatedAt: z.ZodString;
+    workspaceHost: z.ZodString;
+    guestWorkspace: z.ZodString;
+    headless: z.ZodBoolean;
+}, z.core.$strip>;
+/** C:\AgentData\run\requests\<id>.json: the ONLY things the host can ask the sandbox to do. */
+export declare const GuestRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"session">;
+    id: z.ZodString;
+    harness: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+    cwd: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"exec">;
+    id: z.ZodString;
+    command: z.ZodArray<z.ZodString>;
+    cwd: z.ZodString;
+    timeoutSeconds: z.ZodNumber;
+    createdAt: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"restart">;
+    id: z.ZodString;
+    harness: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"ping">;
+    id: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strict>], "kind">;
+/** C:\AgentData\run\responses\<id>.json: the guest's reply. */
+export declare const GuestResponse: z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodBoolean;
+    message: z.ZodString;
+    exitCode: z.ZodOptional<z.ZodNumber>;
+    stdout: z.ZodOptional<z.ZodString>;
+    stderr: z.ZodOptional<z.ZodString>;
+    finishedAt: z.ZodString;
+}, z.core.$strip>;
+/** C:\AgentData\run\sessions\<id>.json: one agent session (its own pseudo console and terminal tab). */
+export declare const SessionStatus: z.ZodObject<{
+    id: z.ZodString;
+    launchId: z.ZodString;
+    harness: z.ZodString;
+    cwd: z.ZodString;
+    phase: z.ZodEnum<{
+        failed: "failed";
+        starting: "starting";
+        running: "running";
+        exited: "exited";
+    }>;
+    message: z.ZodString;
+    updatedAt: z.ZodString;
+    startedAt: z.ZodString;
+    exitCode: z.ZodOptional<z.ZodNumber>;
+    attach: z.ZodOptional<z.ZodObject<{
+        addresses: z.ZodArray<z.ZodString>;
+        port: z.ZodNumber;
+        token: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type AttachEndpointT = z.output<typeof AttachEndpoint>;
+export type SandboxStatusT = z.output<typeof SandboxStatus>;
+export type GuestRequestT = z.output<typeof GuestRequest>;
+export type GuestResponseT = z.output<typeof GuestResponse>;
+export type SessionStatusT = z.output<typeof SessionStatus>;

package/dist/shared/schema.js

@@ -0,0 +1,51 @@
+// The host <-> sandbox channel messages, defined once with zod. Both sides parse what they read: the guest only acts on
+// these request kinds, and the host treats everything the guest writes as untrusted (shapes checked, sizes capped).
+import { z } from 'zod';
+export const Id = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/, 'invalid id');
+const Text = (max = 4096) => z.string().max(max);
+const Time = Text(64);
+export const AttachEndpoint = z.strictObject({
+    addresses: z.array(Text(64)).max(16),
+    port: z.number().int().min(1024).max(65535),
+    token: Text(256),
+});
+/** C:\AgentData\run\sandbox.json: boot progress of the sandbox as a whole. */
+export const SandboxStatus = z.object({
+    launchId: Text(64),
+    phase: z.enum(['booting', 'provisioning', 'ready', 'failed']),
+    message: Text(),
+    updatedAt: Time,
+    workspaceHost: Text(),
+    guestWorkspace: Text(),
+    headless: z.boolean(),
+});
+/** C:\AgentData\run\requests\<id>.json: the ONLY things the host can ask the sandbox to do. */
+export const GuestRequest = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('session'), id: Id, harness: Text(64), args: z.array(Text()).max(256), cwd: Text(), createdAt: Time }),
+    z.strictObject({ kind: z.literal('exec'), id: Id, command: z.array(Text()).min(1).max(256), cwd: Text(), timeoutSeconds: z.number().positive().max(86400), createdAt: Time }),
+    z.strictObject({ kind: z.literal('restart'), id: Id, harness: Text(64).nullable(), createdAt: Time }),
+    z.strictObject({ kind: z.literal('ping'), id: Id, createdAt: Time }),
+]);
+/** C:\AgentData\run\responses\<id>.json: the guest's reply. */
+export const GuestResponse = z.object({
+    id: Id,
+    ok: z.boolean(),
+    message: Text(65536),
+    exitCode: z.number().int().optional(),
+    stdout: Text(4 * 1024 * 1024).optional(),
+    stderr: Text(4 * 1024 * 1024).optional(),
+    finishedAt: Time,
+});
+/** C:\AgentData\run\sessions\<id>.json: one agent session (its own pseudo console and terminal tab). */
+export const SessionStatus = z.object({
+    id: Id,
+    launchId: Text(64),
+    harness: Text(64),
+    cwd: Text(),
+    phase: z.enum(['starting', 'running', 'exited', 'failed']),
+    message: Text(),
+    updatedAt: Time,
+    startedAt: Time,
+    exitCode: z.number().int().optional(),
+    attach: AttachEndpoint.optional(),
+});

package/dist/shared/system.d.ts

@@ -0,0 +1,15 @@
+export declare const system32: (exe: string) => string;
+export declare const SYSTEM: {
+    readonly cmd: () => string;
+    readonly powershell: () => string;
+    readonly tasklist: () => string;
+    readonly tar: () => string;
+    readonly reg: () => string;
+    readonly netsh: () => string;
+    readonly netstat: () => string;
+    readonly route: () => string;
+    readonly ipconfig: () => string;
+    readonly robocopy: () => string;
+    readonly shutdown: () => string;
+    readonly dism: () => string;
+};

package/dist/shared/system.js

@@ -0,0 +1,19 @@
+// Absolute paths for the Windows programs agent-sandbox runs. Never spawn them by bare name: Windows looks in the
+// current folder before PATH, and the current folder is often the workspace, which the sandbox can write.
+import path from 'node:path';
+const systemRoot = () => process.env.SystemRoot ?? process.env.WINDIR ?? 'C:\\Windows';
+export const system32 = (exe) => path.join(systemRoot(), 'System32', exe);
+export const SYSTEM = {
+    cmd: () => system32('cmd.exe'),
+    powershell: () => system32('WindowsPowerShell\\v1.0\\powershell.exe'),
+    tasklist: () => system32('tasklist.exe'),
+    tar: () => system32('tar.exe'),
+    reg: () => system32('reg.exe'),
+    netsh: () => system32('netsh.exe'),
+    netstat: () => system32('NETSTAT.EXE'),
+    route: () => system32('ROUTE.EXE'),
+    ipconfig: () => system32('ipconfig.exe'),
+    robocopy: () => system32('Robocopy.exe'),
+    shutdown: () => system32('shutdown.exe'),
+    dism: () => system32('Dism.exe'),
+};

package/dist/sync/claude-mem.d.ts

@@ -0,0 +1,8 @@
+import type { SyncState } from './history.js';
+export type MemResult = 'none' | 'copied-in' | 'copied-out' | 'unchanged' | 'conflict';
+export declare const hostClaudeMemDir: () => string;
+/**
+ * Direction is decided by which side's database changed since the last sync. If BOTH changed, the side about to be
+ * overwritten is kept as `<dir>.conflict-<time>` first, so nothing is ever lost.
+ */
+export declare const syncClaudeMem: (hostDir: string, store: string, state: SyncState, direction: "in" | "out") => MemResult;

package/dist/sync/claude-mem.js

@@ -0,0 +1,77 @@
+// claude-mem data (~/.claude-mem) between this PC and the sandbox's persistent store.
+//
+// IN (this PC -> sandbox): the whole folder is mirrored; nothing flows to your PC in that direction.
+// OUT (sandbox -> this PC): ONLY the SQLite database files come back. Never settings, never the Chroma vector store:
+// Chroma keeps Python pickle files, and a crafted pickle runs code when loaded, so copying it back would let a
+// compromised sandbox execute code on your PC. claude-mem rebuilds its vector index from the database by itself.
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { dirExists, homeDir, isLink } from '../core/util.js';
+import { safeRemove } from '../shared/safe-remove.js';
+const SKIP_IN = /(^logs$|\.pid$|\.port$|\.lock$|^worker.*\.json$|\.incoming$|\.conflict-\d+$)/i;
+/** The only files that may come back from the sandbox. */
+const DATABASE = /^claude-mem\.db(-wal|-shm)?$/i;
+const MAX_DB_BYTES = 2 * 1024 * 1024 * 1024;
+export const hostClaudeMemDir = () => process.env.CLAUDE_MEM_DATA_DIR ?? path.join(homeDir(), '.claude-mem');
+/** Plain database files at the top of a claude-mem folder (links and anything else are ignored). */
+const databaseFiles = (dir) => dirExists(dir) && !isLink(dir) ? fs.readdirSync(dir).filter((f) => DATABASE.test(f) && fs.lstatSync(path.join(dir, f)).isFile()) : [];
+/** Newest database file time: the only thing that matters for deciding the direction. */
+const stampOf = (dir) => _.max(databaseFiles(dir).map((f) => fs.statSync(path.join(dir, f)).mtimeMs)) ?? 0;
+/** Host -> sandbox: replace the sandbox store with a copy of this PC's folder (staging folder, then swap). */
+const mirrorIn = (hostDir, store) => {
+    const incoming = store + '.incoming';
+    safeRemove(incoming, path.dirname(store));
+    fs.cpSync(hostDir, incoming, { recursive: true, filter: (src) => src === hostDir || !SKIP_IN.test(path.basename(src)) });
+    safeRemove(store, path.dirname(store));
+    fs.renameSync(incoming, store);
+};
+/** Sandbox -> host: copy only the database files, each via a temp file + rename; everything else on this PC stays. */
+const copyDatabaseOut = (store, hostDir) => {
+    fs.mkdirSync(hostDir, { recursive: true });
+    for (const name of databaseFiles(store)) {
+        const source = path.join(store, name);
+        if (fs.statSync(source).size > MAX_DB_BYTES)
+            throw new Error('claude-mem database in the sandbox is suspiciously large; not copied back: ' + source);
+        const temp = path.join(hostDir, name + '.from-sandbox');
+        fs.copyFileSync(source, temp);
+        fs.renameSync(temp, path.join(hostDir, name));
+    }
+};
+/** Keeps a copy of this PC's databases before they are replaced after both sides changed. */
+const parkHostDatabases = (hostDir) => {
+    const parked = hostDir + '.conflict-' + Date.now();
+    fs.mkdirSync(parked, { recursive: true });
+    for (const name of databaseFiles(hostDir))
+        fs.copyFileSync(path.join(hostDir, name), path.join(parked, name));
+};
+/**
+ * Direction is decided by which side's database changed since the last sync. If BOTH changed, the side about to be
+ * overwritten is kept as `<dir>.conflict-<time>` first, so nothing is ever lost.
+ */
+export const syncClaudeMem = (hostDir, store, state, direction) => {
+    if (isLink(store))
+        throw new Error('Refusing to sync claude-mem: ' + store + ' is a link.');
+    const hostStamp = stampOf(hostDir);
+    const guestStamp = stampOf(store);
+    if (hostStamp === 0 && guestStamp === 0 && !dirExists(hostDir))
+        return 'none';
+    const hostChanged = hostStamp > (state.memHostStamp ?? 0) + 1;
+    const guestChanged = state.memGuestStamp !== undefined && guestStamp > state.memGuestStamp + 1;
+    let result = 'unchanged';
+    if (direction === 'in' && dirExists(hostDir) && (hostChanged || guestStamp === 0)) {
+        if (guestChanged)
+            fs.cpSync(store, store + '.conflict-' + Date.now(), { recursive: true });
+        mirrorIn(hostDir, store);
+        result = guestChanged ? 'conflict' : 'copied-in';
+    }
+    else if (direction === 'out' && guestChanged) {
+        if (hostChanged)
+            parkHostDatabases(hostDir);
+        copyDatabaseOut(store, hostDir);
+        result = hostChanged ? 'conflict' : 'copied-out';
+    }
+    state.memHostStamp = stampOf(hostDir);
+    state.memGuestStamp = stampOf(store);
+    return result;
+};

package/dist/sync/history.d.ts

@@ -0,0 +1,30 @@
+import { projectFolderName, translatePaths } from '../shared/paths.js';
+export { projectFolderName, translatePaths };
+/** Host-only record of the last launch: which folders map to each other and what syncs (from the effective config). */
+export interface SyncState {
+    hostClaudeDir: string;
+    hostWorkspace: string;
+    guestWorkspace: string;
+    syncHistory?: boolean;
+    syncClaudeMem?: boolean;
+    /** Newest claude-mem database time on each side right after the last sync (detects edits on both sides). */
+    memHostStamp?: number;
+    memGuestStamp?: number;
+}
+export interface SyncPaths {
+    hostClaudeDir: string;
+    guestClaudeDir: string;
+    hostWorkspace: string;
+    guestWorkspace: string;
+}
+/** Brings this PC's history into the sandbox state (run before the sandbox starts). Returns files copied. */
+export declare const syncHistoryIn: (p: SyncPaths) => number;
+/** Copies new sandbox history back to this PC (safe while the sandbox runs: transcripts are append-only). */
+export declare const syncHistoryOut: (p: SyncPaths) => number;
+/**
+ * Host-only: <storage>\sync\<dataName>.json. It records which folder on this PC history flows back into, so it must
+ * never live in the data folder the sandbox can write (a forged copy could redirect writes anywhere on this PC).
+ */
+export declare const syncStatePath: (dataPath: string) => string;
+export declare const readSyncState: (dataPath: string) => SyncState | null;
+export declare const writeSyncState: (dataPath: string, state: SyncState) => void;

package/dist/sync/history.js

@@ -0,0 +1,129 @@
+// Two-way sync of Claude Code history between this PC and the sandbox's persistent state.
+//
+// Claude keeps transcripts per working folder (~/.claude/projects/<folder with every non-alphanumeric char as '-'>)
+// and writes absolute paths inside them. The sandbox sees the workspace under a different path, so the current
+// project's folder is renamed and paths inside its files are translated in both directions. Everything else is
+// copied as-is, newest file wins, and modification times are preserved so repeated syncs are cheap.
+//
+// Safety (the sandbox side is untrusted):
+//  - links are never followed or written through, on either side;
+//  - what comes BACK is limited to transcripts (.jsonl), prompt history and to-do lists (.json), each capped in
+//    size, and never Claude's memory folders. Nothing executable or instruction-like flows to this PC.
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { guestWorkspaceAliases, projectFolderName, translatePaths } from '../shared/paths.js';
+import { dirExists, ensureDir, fileExists, isLink, removeLink, tryReadJson, writeJson } from '../core/util.js';
+export { projectFolderName, translatePaths };
+const SESSION_DIRS = ['todos', 'plans', 'file-history'];
+const DATA_FILE = /\.(jsonl?|txt|md)$/i;
+const MAX_FILE_BYTES = 100 * 1024 * 1024;
+const anyFile = () => true;
+const transcript = (name) => name.endsWith('.jsonl');
+const json = (name) => name.endsWith('.json');
+/** Claude's auto-memory is loaded into every host session, so the sandbox must never write it. */
+const NO_MEMORY = /^memory$/i;
+const newerThan = (source, destination) => {
+    try {
+        return source.mtimeMs > fs.statSync(destination).mtimeMs + 1;
+    }
+    catch {
+        return true;
+    }
+};
+/** Writes a file, replacing a link at that path instead of writing through it. */
+const writeSafely = (destination, write) => {
+    if (isLink(destination))
+        removeLink(destination);
+    write();
+};
+/** Copies files that are newer in `from`, optionally translating text content, and keeps the source mtime. */
+const copyNewer = (from, to, options = {}) => {
+    if (!dirExists(from) || isLink(from) || isLink(to))
+        return 0;
+    const accept = options.accept ?? anyFile;
+    return _.sumBy(fs.readdirSync(from, { withFileTypes: true }), (entry) => {
+        const source = path.join(from, entry.name);
+        const destination = path.join(to, entry.name);
+        if (entry.isDirectory())
+            return options.skipDirs?.test(entry.name) ? 0 : copyNewer(source, destination, options);
+        if (!entry.isFile() || !accept(entry.name))
+            return 0;
+        const stat = fs.statSync(source);
+        if (stat.size > MAX_FILE_BYTES || !newerThan(stat, destination))
+            return 0;
+        ensureDir(to);
+        writeSafely(destination, () => {
+            if (!options.transform || !DATA_FILE.test(entry.name)) {
+                fs.copyFileSync(source, destination);
+                return;
+            }
+            let text = fs.readFileSync(source, 'utf8');
+            // A transcript can be mid-write; only take complete lines, the rest arrives with the next sync.
+            if (entry.name.endsWith('.jsonl') && !text.endsWith('\n'))
+                text = text.slice(0, text.lastIndexOf('\n') + 1);
+            fs.writeFileSync(destination, options.transform(text), 'utf8');
+        });
+        fs.utimesSync(destination, stat.atime, stat.mtime);
+        return 1;
+    });
+};
+const readLines = (file) => fileExists(file) && !isLink(file) && fs.statSync(file).size <= MAX_FILE_BYTES ? fs.readFileSync(file, 'utf8').split(/\r?\n/).filter((l) => l.trim() !== '') : [];
+const lineTime = (line) => { try {
+    return Number(JSON.parse(line).timestamp) || 0;
+}
+catch {
+    return 0;
+} };
+/** Brings this PC's history into the sandbox state (run before the sandbox starts). Returns files copied. */
+export const syncHistoryIn = (p) => {
+    const hostProject = projectFolderName(p.hostWorkspace);
+    const guestProject = projectFolderName(p.guestWorkspace);
+    const transform = (t) => translatePaths(t, p.hostWorkspace, p.guestWorkspace);
+    const hostProjects = path.join(p.hostClaudeDir, 'projects');
+    const names = dirExists(hostProjects) ? fs.readdirSync(hostProjects).filter((name) => name !== guestProject || hostProject === guestProject) : [];
+    const projects = _.sumBy(names, (name) => name === hostProject
+        ? copyNewer(path.join(hostProjects, name), path.join(p.guestClaudeDir, 'projects', guestProject), { transform })
+        : copyNewer(path.join(hostProjects, name), path.join(p.guestClaudeDir, 'projects', name)));
+    const sessions = _.sumBy(SESSION_DIRS, (dir) => copyNewer(path.join(p.hostClaudeDir, dir), path.join(p.guestClaudeDir, dir)));
+    // Prompt history: rebuild the sandbox copy from this PC's file plus anything only the sandbox has.
+    const target = path.join(p.guestClaudeDir, 'history.jsonl');
+    const hostLines = readLines(path.join(p.hostClaudeDir, 'history.jsonl')).map(transform);
+    const known = new Set(hostLines);
+    const merged = _.sortBy([...hostLines, ...readLines(target).filter((l) => !known.has(l))], lineTime);
+    if (merged.length) {
+        ensureDir(p.guestClaudeDir);
+        writeSafely(target, () => fs.writeFileSync(target, merged.join('\n') + '\n', 'utf8'));
+    }
+    return projects + sessions;
+};
+/** Copies new sandbox history back to this PC (safe while the sandbox runs: transcripts are append-only). */
+export const syncHistoryOut = (p) => {
+    const hostProject = projectFolderName(p.hostWorkspace);
+    // A mirrored workspace on F: really lives at C:\Mirror\F\...; tools that resolve real paths record that one.
+    const guestNames = guestWorkspaceAliases(p.guestWorkspace);
+    const guestProjects = new Set(guestNames.map(projectFolderName));
+    const transform = (t) => guestNames.reduce((out, guest) => translatePaths(out, guest, p.hostWorkspace), t);
+    const guestProjectsDir = path.join(p.guestClaudeDir, 'projects');
+    const names = dirExists(guestProjectsDir) && !isLink(guestProjectsDir) ? fs.readdirSync(guestProjectsDir) : [];
+    const projects = _.sumBy(names, (name) => guestProjects.has(name)
+        ? copyNewer(path.join(guestProjectsDir, name), path.join(p.hostClaudeDir, 'projects', hostProject), { accept: transcript, skipDirs: NO_MEMORY, transform })
+        : copyNewer(path.join(guestProjectsDir, name), path.join(p.hostClaudeDir, 'projects', name), { accept: transcript, skipDirs: NO_MEMORY }));
+    // Only to-do lists come back besides transcripts; plans and file backups stay in the sandbox.
+    const sessions = copyNewer(path.join(p.guestClaudeDir, 'todos'), path.join(p.hostClaudeDir, 'todos'), { accept: json });
+    const hostFile = path.join(p.hostClaudeDir, 'history.jsonl');
+    const known = new Set(readLines(hostFile));
+    const missing = readLines(path.join(p.guestClaudeDir, 'history.jsonl')).map(transform).filter((l) => !known.has(l));
+    if (missing.length) {
+        ensureDir(p.hostClaudeDir);
+        fs.appendFileSync(hostFile, missing.join('\n') + '\n', 'utf8');
+    }
+    return projects + sessions + missing.length;
+};
+/**
+ * Host-only: <storage>\sync\<dataName>.json. It records which folder on this PC history flows back into, so it must
+ * never live in the data folder the sandbox can write (a forged copy could redirect writes anywhere on this PC).
+ */
+export const syncStatePath = (dataPath) => path.join(path.dirname(path.dirname(dataPath)), 'sync', path.basename(dataPath) + '.json');
+export const readSyncState = (dataPath) => tryReadJson(syncStatePath(dataPath));
+export const writeSyncState = (dataPath, state) => writeJson(syncStatePath(dataPath), state);

package/dist/sync/watcher.d.ts

@@ -0,0 +1,13 @@
+import type { Config } from '../core/types.js';
+import { type MemResult } from './claude-mem.js';
+export interface SyncSummary {
+    history: number;
+    claudeMem: MemResult | 'disabled';
+}
+/** Before launch: finish syncing the previous run out, then bring this PC's history (and claude-mem) in. */
+export declare const syncBeforeLaunch: (config: Config, dataPath: string, hostWorkspace: string) => SyncSummary;
+/** Syncs the sandbox's history (and, when `final`, claude-mem) back to this PC, as configured for the last launch. */
+export declare const syncBack: (dataPath: string, final: boolean) => SyncSummary;
+export declare const watcherRunning: (dataPath: string) => boolean;
+/** Body of the detached watcher process (`agent-sandbox _watch`). */
+export declare const watch: (dataPath: string) => Promise<void>;

package/dist/sync/watcher.js

@@ -0,0 +1,116 @@
+// When history and claude-mem move: in before every launch, out every minute while the sandbox runs (history) and
+// once more when it closes (history + claude-mem). The watcher runs detached on the host for the sandbox's lifetime.
+// Its pid file and log live in host-only storage, never in the data folder the sandbox can write.
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertNoLinks, errMsg, sleep } from '../core/util.js';
+import { hostClaudeDir } from '../host/claude-profile.js';
+import { checkRepo } from '../host/repo-guard.js';
+import { isSandboxRunning } from '../host/platform.js';
+import { hostClaudeMemDir, syncClaudeMem } from './claude-mem.js';
+import { readSyncState, syncHistoryIn, syncHistoryOut, writeSyncState } from './history.js';
+const WATCH_INTERVAL_MS = 60 * 1000;
+const storageOf = (dataPath) => path.dirname(path.dirname(dataPath));
+const guestClaude = (dataPath) => path.join(dataPath, 'state', 'claude');
+const guestMem = (dataPath) => path.join(dataPath, 'state', 'claude-mem');
+/** Sync paths for the sandbox side, after checking nothing on the way there is a link planted by the sandbox. */
+const toPaths = (state, dataPath) => {
+    assertNoLinks(dataPath, guestClaude(dataPath));
+    return { hostClaudeDir: state.hostClaudeDir, guestClaudeDir: guestClaude(dataPath), hostWorkspace: state.hostWorkspace, guestWorkspace: state.guestWorkspace };
+};
+const memSync = (dataPath, state, direction) => {
+    assertNoLinks(dataPath, guestMem(dataPath));
+    return syncClaudeMem(hostClaudeMemDir(), guestMem(dataPath), state, direction);
+};
+/** Before launch: finish syncing the previous run out, then bring this PC's history (and claude-mem) in. */
+export const syncBeforeLaunch = (config, dataPath, hostWorkspace) => {
+    const profile = config.claudeProfile;
+    const summary = { history: 0, claudeMem: 'disabled' };
+    if (!config.storage.persistAgentState)
+        return summary;
+    const previous = readSyncState(dataPath);
+    if (previous?.syncHistory)
+        syncHistoryOut(toPaths(previous, dataPath));
+    const state = { ...previous, hostClaudeDir: hostClaudeDir(profile), hostWorkspace, guestWorkspace: config.guestWorkspace, syncHistory: profile.syncHistory, syncClaudeMem: profile.syncClaudeMem };
+    if (profile.syncHistory)
+        summary.history = syncHistoryIn(toPaths(state, dataPath));
+    if (profile.syncClaudeMem) {
+        if (previous?.syncClaudeMem)
+            memSync(dataPath, state, 'out');
+        summary.claudeMem = memSync(dataPath, state, 'in');
+    }
+    writeSyncState(dataPath, state);
+    return summary;
+};
+/** Syncs the sandbox's history (and, when `final`, claude-mem) back to this PC, as configured for the last launch. */
+export const syncBack = (dataPath, final) => {
+    const state = readSyncState(dataPath);
+    const summary = { history: 0, claudeMem: 'disabled' };
+    if (!state)
+        return summary;
+    if (state.syncHistory)
+        summary.history = syncHistoryOut(toPaths(state, dataPath));
+    if (final && state.syncClaudeMem)
+        summary.claudeMem = memSync(dataPath, state, 'out');
+    writeSyncState(dataPath, state);
+    return summary;
+};
+const hostRunDir = (dataPath) => path.join(storageOf(dataPath), 'run');
+const watcherPidFile = (dataPath) => path.join(hostRunDir(dataPath), 'watcher-' + path.basename(dataPath) + '.pid');
+const watcherLog = (dataPath) => path.join(storageOf(dataPath), 'logs', 'host-sync-' + path.basename(dataPath) + '.log');
+const alive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch {
+    return false;
+} };
+export const watcherRunning = (dataPath) => {
+    try {
+        return alive(Number(fs.readFileSync(watcherPidFile(dataPath), 'utf8')));
+    }
+    catch {
+        return false;
+    }
+};
+/** Body of the detached watcher process (`agent-sandbox _watch`). */
+export const watch = async (dataPath) => {
+    if (watcherRunning(dataPath))
+        return;
+    fs.mkdirSync(hostRunDir(dataPath), { recursive: true });
+    fs.mkdirSync(path.dirname(watcherLog(dataPath)), { recursive: true });
+    fs.writeFileSync(watcherPidFile(dataPath), String(process.pid));
+    const note = (message) => { try {
+        fs.appendFileSync(watcherLog(dataPath), new Date().toISOString() + ' ' + message + '\n');
+    }
+    catch { /* ignore */ } };
+    const sync = (final) => {
+        try {
+            for (const finding of checkRepo(dataPath))
+                note('SECURITY: neutralised a git ' + finding.kind + ' added inside the sandbox: ' + finding.detail);
+        }
+        catch (e) {
+            note('repo guard failed: ' + errMsg(e));
+        }
+        try {
+            const s = syncBack(dataPath, final);
+            if (s.history || final)
+                note((final ? 'sandbox closed; final sync: ' : '') + 'history ' + s.history + ', claude-mem ' + s.claudeMem);
+        }
+        catch (e) {
+            note('sync failed: ' + errMsg(e));
+        }
+    };
+    try {
+        await sleep(30000);
+        while (isSandboxRunning()) {
+            sync(false);
+            await sleep(WATCH_INTERVAL_MS);
+        }
+        await sleep(3000);
+        sync(true);
+    }
+    finally {
+        fs.rmSync(watcherPidFile(dataPath), { force: true });
+    }
+};

package/hooks/post-agent/README.txt

@@ -0,0 +1 @@
+Put .ps1 / .mjs / .cmd files here to run inside the sandbox AFTER the agent exits (name order).

package/hooks/pre-provision/README.txt

@@ -0,0 +1 @@
+Put .ps1 / .mjs / .cmd files here to run inside the sandbox BEFORE tools are provisioned (name order).