windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/shared/test-guard.js

@@ -0,0 +1,37 @@
+// Defence in depth for the self-test: while AGENT_SANDBOX_SELFTEST=1 is set, nothing may act on the real PC. Every write or
+// delete on the host is limited to the temp folder the tests use (outward actions refuse in host/test-guard.ts). The
+// self-test sets the variable for itself and its child processes. No imports from core/: the sandbox bundles this file too.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const selfTestRunning = () => process.env.AGENT_SANDBOX_SELFTEST === '1';
+/** Resolves links in the part of the path that exists, so C:\Users\WDAGUT~1 and C:\Users\WDAGUtilityAccount compare equal. */
+const canonical = (p) => {
+    let rest = '';
+    let current = path.resolve(p);
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync.native(current), rest).toLowerCase();
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.resolve(p).toLowerCase();
+            rest = path.join(path.basename(current), rest);
+            current = parent;
+        }
+    }
+};
+/** Why the self-test may not write, copy or delete at `target` (anywhere but the temp folder), or null. */
+export const testWriteRefusal = (target) => {
+    if (!selfTestRunning())
+        return null;
+    const temp = canonical(os.tmpdir());
+    const t = canonical(target);
+    return t === temp || t.startsWith(temp + path.sep) ? null : 'The self-test refused to change ' + target + ': it only works in temp folders, so it can never change this PC.';
+};
+export const assertTestWritable = (target) => {
+    const refusal = testWriteRefusal(target);
+    if (refusal)
+        throw new Error(refusal);
+};

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,79 @@
+// 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';
+import { assertTestWritable } from '../host/test-guard.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)) && !isLink(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) => {
+    assertTestWritable(direction === 'in' ? store : hostDir);
+    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,41 @@
+import { z } from 'zod';
+import { projectFolderName, translatePaths } from '../shared/paths.js';
+export { projectFolderName, translatePaths };
+declare const SyncStateSchema: z.ZodObject<{
+    hostClaudeDir: z.ZodString;
+    hostWorkspace: z.ZodString;
+    guestWorkspace: z.ZodString;
+    syncHistory: z.ZodOptional<z.ZodBoolean>;
+    syncClaudeMem: z.ZodOptional<z.ZodBoolean>;
+    memHostStamp: z.ZodOptional<z.ZodNumber>;
+    memGuestStamp: z.ZodOptional<z.ZodNumber>;
+    projects: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        hostWorkspace: z.ZodString;
+        guestWorkspace: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type SyncState = z.output<typeof SyncStateSchema>;
+export interface WorkspacePair {
+    hostWorkspace: string;
+    guestWorkspace: string;
+}
+/** extra: projects registered after boot (C:\Projects\<name> -> their real folder on this PC). */
+export interface SyncPaths extends WorkspacePair {
+    hostClaudeDir: string;
+    guestClaudeDir: string;
+    extra?: WorkspacePair[];
+}
+/** Brings this PC's history into the sandbox state (run before the sandbox starts). Returns files copied. */
+export declare const syncHistoryIn: (p: SyncPaths, options?: {
+    promptHistory?: boolean;
+}) => 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;
+/** A state file that is missing, oversized or not in this shape counts as no state (nothing syncs back until the next launch). */
+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,161 @@
+// 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 { z } from 'zod';
+import { guestWorkspaceAliases, isSafeFileName, projectFolderName, translatePaths } from '../shared/paths.js';
+import { readValid, writeJsonAtomic } from '../shared/rundir.js';
+import { assertTestWritable } from '../host/test-guard.js';
+import { dirExists, ensureDir, fileExists, isLink, removeLink } 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;
+/** Host-only record of the last launch: which folders map to each other and what syncs (from the effective config). */
+const AbsolutePath = z.string().max(1024).refine((p) => path.isAbsolute(p), 'must be an absolute path');
+const SyncStateSchema = z.object({
+    hostClaudeDir: AbsolutePath, hostWorkspace: AbsolutePath, guestWorkspace: z.string().max(1024),
+    syncHistory: z.boolean().optional(), syncClaudeMem: z.boolean().optional(),
+    /** Newest claude-mem database time on each side right after the last sync (detects edits on both sides). */
+    memHostStamp: z.number().optional(), memGuestStamp: z.number().optional(),
+    /** Projects registered while the sandbox ran (their history goes back to their own folders). */
+    projects: z.array(z.object({ hostWorkspace: AbsolutePath, guestWorkspace: z.string().max(1024) })).max(256).optional(),
+});
+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) => {
+        if (!isSafeFileName(entry.name))
+            return 0;
+        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 isJsonObject = (line) => { try {
+    const v = JSON.parse(line);
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+catch {
+    return false;
+} };
+const lineTime = (line) => { try {
+    return Number(JSON.parse(line).timestamp) || 0;
+}
+catch {
+    return 0;
+} };
+/** Every workspace pair of the sandbox: the launch folder's, then the projects registered later (most specific first). */
+const pairsOf = (p) => _.sortBy([{ hostWorkspace: p.hostWorkspace, guestWorkspace: p.guestWorkspace }, ...(p.extra ?? [])], (x) => -x.hostWorkspace.length);
+const translateAll = (text, pairs) => pairs.reduce((out, [from, to]) => translatePaths(out, from, to), text);
+/** Brings this PC's history into the sandbox state (run before the sandbox starts). Returns files copied. */
+export const syncHistoryIn = (p, options = {}) => {
+    assertTestWritable(p.guestClaudeDir);
+    const pairs = pairsOf(p);
+    const byHost = new Map(pairs.map((x) => [projectFolderName(x.hostWorkspace), projectFolderName(x.guestWorkspace)]));
+    const guestNames = new Set(pairs.map((x) => projectFolderName(x.guestWorkspace)));
+    const transform = (t) => translateAll(t, pairs.map((x) => [x.hostWorkspace, x.guestWorkspace]));
+    const hostProjects = path.join(p.hostClaudeDir, 'projects');
+    const names = dirExists(hostProjects) ? fs.readdirSync(hostProjects).filter((name) => isSafeFileName(name) && (!guestNames.has(name) || byHost.has(name))) : [];
+    const projects = _.sumBy(names, (name) => byHost.has(name)
+        ? copyNewer(path.join(hostProjects, name), path.join(p.guestClaudeDir, 'projects', byHost.get(name)), { 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)));
+    if (options.promptHistory === false)
+        return projects + sessions;
+    // 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) => {
+    assertTestWritable(p.hostClaudeDir);
+    // A mirrored workspace on F: really lives at C:\Mirror\F\...; tools that resolve real paths record that one. A
+    // project registered later is in the hub (C:\Projects\<name>) and goes back to its real folder on this PC.
+    const pairs = pairsOf(p).flatMap((x) => guestWorkspaceAliases(x.guestWorkspace).map((guest) => [guest, x.hostWorkspace]));
+    const byGuest = new Map(pairs.map(([guest, host]) => [projectFolderName(guest), projectFolderName(host)]));
+    const transform = (t) => translateAll(t, pairs);
+    const guestProjectsDir = path.join(p.guestClaudeDir, 'projects');
+    const names = dirExists(guestProjectsDir) && !isLink(guestProjectsDir) ? fs.readdirSync(guestProjectsDir).filter(isSafeFileName) : [];
+    const projects = _.sumBy(names, (name) => byGuest.has(name)
+        ? copyNewer(path.join(guestProjectsDir, name), path.join(p.hostClaudeDir, 'projects', byGuest.get(name)), { 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));
+    // Only prompt-history entries (one JSON object per line) come back, whatever else the sandbox wrote in that file.
+    const missing = readLines(path.join(p.guestClaudeDir, 'history.jsonl')).filter(isJsonObject).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');
+/** A state file that is missing, oversized or not in this shape counts as no state (nothing syncs back until the next launch). */
+export const readSyncState = (dataPath) => readValid(SyncStateSchema, syncStatePath(dataPath));
+export const writeSyncState = (dataPath, state) => writeJsonAtomic(syncStatePath(dataPath), state);

package/dist/sync/watcher.d.ts

@@ -0,0 +1,21 @@
+import type { Config } from '../core/types.js';
+import { type MemResult } from './claude-mem.js';
+/**
+ * A project registered while the sandbox runs: its history comes in now (the sandbox's copy only gains files), and
+ * from now on syncs back to its own folder on this PC.
+ */
+export declare const syncProjectIn: (dataPath: string, project: {
+    hostWorkspace: string;
+    guestWorkspace: string;
+}) => number;
+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,135 @@
+// 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 { writeFileAtomic } from '../shared/rundir.js';
+import { refuseInSelfTest } from '../host/test-guard.js';
+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, extra: state.projects ?? [] };
+};
+/**
+ * A project registered while the sandbox runs: its history comes in now (the sandbox's copy only gains files), and
+ * from now on syncs back to its own folder on this PC.
+ */
+export const syncProjectIn = (dataPath, project) => {
+    const state = readSyncState(dataPath);
+    if (!state)
+        return 0;
+    const projects = [...(state.projects ?? []).filter((p) => p.hostWorkspace.toLowerCase() !== project.hostWorkspace.toLowerCase()), project];
+    const next = { ...state, projects };
+    writeSyncState(dataPath, next);
+    // Prompt history is left alone: sessions are appending to the sandbox's copy right now.
+    return state.syncHistory ? syncHistoryIn(toPaths(next, dataPath), { promptHistory: false }) : 0;
+};
+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, projects: [] };
+    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');
+// Signal 0 only asks whether the process exists. pid 0 would mean "my own process group", so it never counts.
+const alive = (pid) => { if (!Number.isInteger(pid) || pid <= 0)
+    return false; 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) => {
+    refuseInSelfTest('start the background sync');
+    if (watcherRunning(dataPath))
+        return;
+    fs.mkdirSync(hostRunDir(dataPath), { recursive: true });
+    fs.mkdirSync(path.dirname(watcherLog(dataPath)), { recursive: true });
+    writeFileAtomic(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).

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "windows-development-sandbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "A disposable Windows Sandbox for development, with or without an AI agent (Claude Code, Codex, Gemini, opencode, ...): the folder you run it from is the workspace, toolchains and databases for your project install themselves, and nothing else on your PC is reachable.",
+  "type": "module",
+  "license": "MIT",
+  "os": [
+    "win32"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "sandbox": "dist/bin/sandbox.js",
+    "windows-development-sandbox": "dist/bin/sandbox.js",
+    "agent-sandbox": "dist/bin/agent-sandbox.js",
+    "claude-sbx": "dist/bin/claude-sbx.js",
+    "claude-sandbox": "dist/bin/claude-sbx.js",
+    "codex-sbx": "dist/bin/codex-sbx.js",
+    "codex-sandbox": "dist/bin/codex-sbx.js",
+    "gemini-sbx": "dist/bin/gemini-sbx.js",
+    "gemini-sandbox": "dist/bin/gemini-sbx.js",
+    "claude-host": "dist/bin/claude-host.js",
+    "sbx-show": "dist/bin/sbx-show.js",
+    "sbx-hide": "dist/bin/sbx-hide.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/api.d.ts",
+      "default": "./dist/api.js"
+    }
+  },
+  "files": [
+    "dist",
+    "sandbox",
+    "schemas",
+    "hooks",
+    "config.example.json",
+    ".sandbox-config.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/bundle.mjs && node scripts/schemas.mjs",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "rebuild": "npm run clean && npm run build",
+    "test": "npm run build && node dist/bin/agent-sandbox.js self-test",
+    "prepack": "npm run rebuild",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags",
+    "install:global": "node scripts/install-global.mjs",
+    "publish:npm": "node scripts/publish-npm.mjs",
+    "doctor": "node dist/bin/agent-sandbox.js doctor"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "windows-sandbox",
+    "sandbox",
+    "agent",
+    "codex",
+    "gemini",
+    "development",
+    "opencode",
+    "databases",
+    "dynamodb"
+  ],
+  "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
+    "commander": "^14.0.3",
+    "jsonc-parser": "^3.3.1",
+    "lodash": "^4.18.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/lodash": "^4.17.26",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.28.2",
+    "typescript": "^5.8.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JoshDiDuca/windows-development-sandbox.git"
+  },
+  "homepage": "https://github.com/JoshDiDuca/windows-development-sandbox#readme",
+  "bugs": {
+    "url": "https://github.com/JoshDiDuca/windows-development-sandbox/issues"
+  }
+}