windows-development-sandbox 1.4.1 → 1.4.3

package/dist/shared/pty/protocol.js

@@ -0,0 +1,60 @@
+// Client side of the ptyhost protocol (see sandbox/ptyhost.cs). Used by the window inside the sandbox and by
+// `--terminal` / `attach` on the host, so it only depends on Node built-ins.
+export const FrameType = {
+    Hello: 1,
+    Input: 2,
+    Resize: 3,
+    Restart: 4,
+    Ping: 5,
+    Output: 16,
+    Exit: 17,
+    Error: 18,
+    Restarting: 19,
+    Status: 20,
+    Console: 21,
+};
+/** HELLO flags: control-only connections get no output and never size the console; a query only asks for STATUS. */
+export const HelloFlag = { ControlOnly: 1, Query: 2 };
+/** Viewers ping this often; ptyhost counts a viewer as gone after 15 s of silence (e.g. its terminal tab was closed). */
+export const PING_INTERVAL_MS = 5000;
+/** Ctrl+] — the same detach key telnet uses; Claude Code does not bind it. */
+export const DETACH_KEY = 0x1d;
+export const encodeFrame = (type, payload = Buffer.alloc(0)) => {
+    const header = Buffer.alloc(5);
+    header.writeUInt8(type, 0);
+    header.writeUInt32LE(payload.length, 1);
+    return Buffer.concat([header, payload]);
+};
+export const helloFrame = (token, cols, rows, flags = 0) => {
+    const head = Buffer.alloc(5);
+    head.writeInt16LE(cols, 0);
+    head.writeInt16LE(rows, 2);
+    head.writeUInt8(flags, 4);
+    return encodeFrame(FrameType.Hello, Buffer.concat([head, Buffer.from(token, 'utf8')]));
+};
+export const resizeFrame = (cols, rows) => {
+    const payload = Buffer.alloc(4);
+    payload.writeInt16LE(cols, 0);
+    payload.writeInt16LE(rows, 2);
+    return encodeFrame(FrameType.Resize, payload);
+};
+/** Same limit as ptyhost.cs; a peer announcing more is broken or hostile. */
+export const MAX_FRAME_BYTES = 1 << 20;
+/** Splits a TCP byte stream back into frames. */
+export class FrameReader {
+    pending = Buffer.alloc(0);
+    push(chunk) {
+        this.pending = Buffer.concat([this.pending, chunk]);
+        const frames = [];
+        while (this.pending.length >= 5) {
+            const length = this.pending.readUInt32LE(1);
+            if (length > MAX_FRAME_BYTES)
+                throw new Error('frame too large (' + length + ' bytes)');
+            if (this.pending.length < 5 + length)
+                break;
+            frames.push({ type: this.pending[0], payload: this.pending.subarray(5, 5 + length) });
+            this.pending = this.pending.subarray(5 + length);
+        }
+        return frames;
+    }
+}

package/dist/shared/pty/terminal.d.ts

@@ -0,0 +1,24 @@
+import net from 'node:net';
+export type ClientResult = {
+    reason: 'exit';
+    exitCode: number;
+} | {
+    reason: 'detach' | 'closed';
+} | {
+    reason: 'error';
+    message: string;
+};
+/** Turns off every mouse tracking mode a program may have turned on in your terminal (normal, button, any, UTF-8, SGR, urxvt). */
+export declare const MOUSE_OFF = "\u001B[?1000l\u001B[?1002l\u001B[?1003l\u001B[?1005l\u001B[?1006l\u001B[?1015l";
+/**
+ * Node on Windows reads keys through the console API, where Backspace is ^H and Ctrl+Backspace is DEL: the reverse of
+ * what terminals send. ConPTY reads ^H as Ctrl+Backspace (delete a word), so swap them back.
+ */
+export declare const fixWindowsKeys: (chunk: Buffer) => Buffer;
+/**
+ * Bridges this process's terminal to the remote program until it exits, the connection drops, or the user presses
+ * the detach key. Restores the terminal before resolving.
+ */
+export declare const runTerminalClient: (socket: net.Socket, token: string, options?: {
+    detachKey?: number;
+}) => Promise<ClientResult>;

package/dist/shared/pty/terminal.js

@@ -0,0 +1,147 @@
+import { FrameReader, encodeFrame, FrameType, resizeFrame, PING_INTERVAL_MS, helloFrame, } from './protocol.js';
+import { OutputFilter } from './output-filter.js';
+import { enableVtInput } from './console-input.js';
+import { InputJoiner, JOIN_MS } from './input-joiner.js';
+/** Turns off every mouse tracking mode a program may have turned on in your terminal (normal, button, any, UTF-8, SGR, urxvt). */
+export const MOUSE_OFF = '\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1005l\x1b[?1006l\x1b[?1015l';
+/**
+ * Node on Windows reads keys through the console API, where Backspace is ^H and Ctrl+Backspace is DEL: the reverse of
+ * what terminals send. ConPTY reads ^H as Ctrl+Backspace (delete a word), so swap them back.
+ */
+export const fixWindowsKeys = (chunk) => {
+    if (!chunk.includes(0x08) && !chunk.includes(0x7f))
+        return chunk;
+    return Buffer.from(chunk.map((b) => (b === 0x08 ? 0x7f : b === 0x7f ? 0x08 : b)));
+};
+/**
+ * Bridges this process's terminal to the remote program until it exits, the connection drops, or the user presses
+ * the detach key. Restores the terminal before resolving.
+ */
+export const runTerminalClient = (socket, token, options = {}) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    // getWindowSize asks the console every time; columns/rows only change when Node noticed a resize.
+    const size = () => {
+        const [c, r] = stdout.isTTY ? stdout.getWindowSize() : [0, 0];
+        return [c || 120, r || 30];
+    };
+    // Until the console passes the terminal's input through as it is (enableVtInput), Node turns Backspace into ^H.
+    let swapKeys = process.platform === 'win32' && stdin.isTTY;
+    return new Promise((resolve) => {
+        let done = false;
+        const reader = new FrameReader();
+        const filter = new OutputFilter();
+        let sent = size();
+        let resizeTimer;
+        let vtInput;
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            stdin.off('data', onInput);
+            stdout.off('resize', onResize);
+            clearTimeout(resizeTimer);
+            clearInterval(heartbeat);
+            clearInterval(sizeWatch);
+            clearTimeout(joinTimer);
+            socket.destroy();
+            // The agent's mouse tracking ends with it: your terminal's wheel scrolls again (and clicks select text).
+            stdout.write('\x1b[0m\x1b[?25h' + MOUSE_OFF + '\r\n');
+            // Wait for a console-mode change still in progress, then give the console back in its normal mode.
+            void (vtInput?.stop() ?? Promise.resolve()).then(() => {
+                if (stdin.isTTY)
+                    stdin.setRawMode(false);
+                stdin.pause();
+                resolve(result);
+            });
+        };
+        const joiner = new InputJoiner();
+        let joinTimer;
+        const sendInput = (data) => {
+            if (data.length && !done)
+                socket.write(encodeFrame(FrameType.Input, swapKeys ? fixWindowsKeys(data) : data));
+        };
+        const onInput = (chunk) => {
+            if (options.detachKey !== undefined && chunk.includes(options.detachKey)) {
+                finish({ reason: 'detach' });
+                return;
+            }
+            clearTimeout(joinTimer);
+            sendInput(joiner.push(chunk));
+            // A lone Esc key press is a "sequence" that never completes: send it after a moment.
+            if (joiner.holding())
+                joinTimer = setTimeout(() => sendInput(joiner.flush()), JOIN_MS);
+        };
+        // Windows' own ConPTY repaints the whole screen on every resize; dragging a window edge fires dozens of them, and
+        // repaints racing each other left the screen garbled. Wait until the size settles, clear what this terminal
+        // reflowed on its own, then let ptyhost repaint everything once at the new size. With conpty.dll (passthrough)
+        // nothing is repainted: this terminal's own reflow and scrollback stay, and the program redraws what it needs.
+        let passthrough = false;
+        const sendSize = () => {
+            const [c, r] = size();
+            if (c === sent[0] && r === sent[1])
+                return;
+            sent = [c, r];
+            if (!passthrough)
+                stdout.write('\x1b[H\x1b[J');
+            socket.write(resizeFrame(c, r));
+        };
+        const onResize = () => {
+            clearTimeout(resizeTimer);
+            resizeTimer = setTimeout(() => {
+                resizeTimer = undefined;
+                sendSize();
+            }, 120);
+        };
+        const heartbeat = setInterval(() => socket.write(encodeFrame(FrameType.Ping)), PING_INTERVAL_MS);
+        // Windows does not always report a resize in raw mode, so the size is also checked twice a second.
+        const sizeWatch = setInterval(() => {
+            if (!resizeTimer)
+                sendSize();
+        }, 500);
+        socket.on('data', (chunk) => {
+            let frames;
+            try {
+                frames = reader.push(chunk);
+            }
+            catch {
+                finish({ reason: 'error', message: 'invalid data from the sandbox' });
+                return;
+            }
+            for (const frame of frames) {
+                if (frame.type === FrameType.Output)
+                    stdout.write(filter.push(frame.payload));
+                else if (frame.type === FrameType.Console)
+                    passthrough = frame.payload.toString('latin1') === 'conpty.dll';
+                else if (frame.type === FrameType.Restarting)
+                    stdout.write(MOUSE_OFF + '\x1b[2J\x1b[3J\x1b[H');
+                else if (frame.type === FrameType.Exit)
+                    finish({ reason: 'exit', exitCode: frame.payload.length >= 4 ? frame.payload.readInt32LE(0) : 1 });
+                else if (frame.type === FrameType.Error)
+                    finish({
+                        reason: 'error',
+                        message: frame.payload
+                            .toString('utf8')
+                            .slice(0, 500)
+                            .replace(/[\x00-\x1f\x7f]/g, ' '),
+                    });
+            }
+        });
+        socket.on('close', () => finish({ reason: 'closed' }));
+        socket.on('error', () => finish({ reason: 'closed' }));
+        const [c, r] = size();
+        stdout.write('\x1b[2J\x1b[3J\x1b[H');
+        socket.write(helloFrame(token, c, r));
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        // After setRawMode (which sets the console mode): mouse reports, focus and keys then arrive as the terminal sent them.
+        vtInput = enableVtInput();
+        void vtInput.ready.then((on) => {
+            if (on)
+                swapKeys = false;
+        });
+        stdin.on('data', onInput);
+        stdin.resume();
+        stdout.on('resize', onResize);
+    });
+};

package/dist/shared/test-guard.js

@@ -28,7 +28,9 @@ export const testWriteRefusal = (target) => {
         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.';
+    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);

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

@@ -1,4 +1,4 @@
-import type { SyncState } from './history.js';
+import type { SyncState } from './sync-state.js';
 export type MemResult = 'none' | 'copied-in' | 'copied-out' | 'unchanged' | 'conflict';
 export declare const hostClaudeMemDir: () => string;
 /**

package/dist/sync/claude-mem.js

@@ -7,8 +7,8 @@
 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 { dirExists, homeDir, isLink } from '../core/util/index.js';
+import { safeRemove } from '../shared/io/index.js';
 import { assertTestWritable } from '../host/test-guard.js';
 // Never in: its settings (provider API keys), .env files and backups; nor run-time files that mean nothing elsewhere.
 const SKIP_IN = /(^logs$|^backups?$|^settings\.json$|^\.env|\.pid$|\.port$|\.lock$|^worker.*\.json$|\.incoming$|\.conflict-\d+$)/i;
@@ -17,14 +17,19 @@ 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()) : [];
+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)) });
+    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);
 };

package/dist/sync/history.d.ts

@@ -1,25 +1,5 @@
-import { z } from 'zod';
-import { projectFolderName, translatePaths } from '../shared/paths.js';
+import { projectFolderName, translatePaths } from '../shared/paths/index.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>;
-    syncClaudeMemBack: z.ZodOptional<z.ZodBoolean>;
-    historyScope: z.ZodOptional<z.ZodEnum<{
-        project: "project";
-        all: "all";
-    }>>;
-    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;
@@ -37,11 +17,3 @@ export declare const syncHistoryIn: (p: SyncPaths, options?: {
 }) => 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

@@ -15,25 +15,13 @@
 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 { guestWorkspaceAliases, isSafeFileName, projectFolderName, translatePaths } from '../shared/paths/index.js';
 import { assertTestWritable } from '../host/test-guard.js';
-import { dirExists, ensureDir, fileExists, isLink, removeLink } from '../core/util.js';
+import { dirExists, ensureDir, fileExists, isLink, removeLink } from '../core/util/index.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(), syncClaudeMemBack: z.boolean().optional(), historyScope: z.enum(['project', 'all']).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');
@@ -86,30 +74,40 @@ const copyNewer = (from, to, options = {}) => {
         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 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;
+    }
+};
 /** A prompt-history line whose project is one of `workspaces` (on this PC's side). */
 const inProjects = (line, workspaces) => {
     try {
         const project = JSON.parse(line).project;
-        return typeof project === 'string' && workspaces.some((w) => path.resolve(w).toLowerCase() === path.resolve(project).toLowerCase());
+        return (typeof project === 'string' &&
+            workspaces.some((w) => path.resolve(w).toLowerCase() === path.resolve(project).toLowerCase()));
     }
     catch {
         return false;
     }
 };
-const lineTime = (line) => { try {
-    return Number(JSON.parse(line).timestamp) || 0;
-}
-catch {
-    return 0;
-} };
+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);
@@ -122,17 +120,28 @@ export const syncHistoryIn = (p, options = {}) => {
     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) && (all ? !guestNames.has(name) || byHost.has(name) : byHost.has(name))) : [];
+    const names = dirExists(hostProjects)
+        ? fs
+            .readdirSync(hostProjects)
+            .filter((name) => isSafeFileName(name) && (all ? !guestNames.has(name) || byHost.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', byHost.get(name)), {
+            transform,
+        })
         : copyNewer(path.join(hostProjects, name), path.join(p.guestClaudeDir, 'projects', name)));
     // To-do lists, plans and file backups are kept by session, not by project: only with historyScope "all".
-    const sessions = all ? _.sumBy(SESSION_DIRS, (dir) => copyNewer(path.join(p.hostClaudeDir, dir), path.join(p.guestClaudeDir, dir))) : 0;
+    const sessions = all
+        ? _.sumBy(SESSION_DIRS, (dir) => copyNewer(path.join(p.hostClaudeDir, dir), path.join(p.guestClaudeDir, dir)))
+        : 0;
     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')).filter((l) => all || inProjects(l, pairs.map((x) => x.hostWorkspace))).map(transform);
+    const hostLines = readLines(path.join(p.hostClaudeDir, 'history.jsonl'))
+        .filter((l) => all ||
+        inProjects(l, pairs.map((x) => x.hostWorkspace)))
+        .map(transform);
     const known = new Set(hostLines);
     const merged = _.sortBy([...hostLines, ...readLines(target).filter((l) => !known.has(l))], lineTime);
     if (merged.length) {
@@ -150,27 +159,30 @@ export const syncHistoryOut = (p) => {
     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 names = dirExists(guestProjectsDir) && !isLink(guestProjectsDir)
+        ? fs.readdirSync(guestProjectsDir).filter(isSafeFileName)
+        : [];
     // Only this sandbox's projects: a transcript under any other folder name would be planted into that project on this PC.
-    const projects = _.sumBy(names.filter((name) => byGuest.has(name)), (name) => copyNewer(path.join(guestProjectsDir, name), path.join(p.hostClaudeDir, 'projects', byGuest.get(name)), { accept: transcript, skipDirs: NO_MEMORY, transform }));
+    const projects = _.sumBy(names.filter((name) => byGuest.has(name)), (name) => copyNewer(path.join(guestProjectsDir, name), path.join(p.hostClaudeDir, 'projects', byGuest.get(name)), {
+        accept: transcript,
+        skipDirs: NO_MEMORY,
+        transform,
+    }));
     // 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 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) of this sandbox's projects come back.
     const hostWorkspaces = pairsOf(p).map((x) => x.hostWorkspace);
-    const missing = readLines(path.join(p.guestClaudeDir, 'history.jsonl')).filter(isJsonObject).map(transform).filter((l) => inProjects(l, hostWorkspaces) && !known.has(l));
+    const missing = readLines(path.join(p.guestClaudeDir, 'history.jsonl'))
+        .filter(isJsonObject)
+        .map(transform)
+        .filter((l) => inProjects(l, hostWorkspaces) && !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/index.d.ts

@@ -0,0 +1,5 @@
+export * from './claude-mem.js';
+export * from './history.js';
+export * from './sync-state.js';
+export * from './sync-cycle.js';
+export * from './watcher.js';

package/dist/sync/index.js

@@ -0,0 +1,5 @@
+export * from './claude-mem.js';
+export * from './history.js';
+export * from './sync-state.js';
+export * from './sync-cycle.js';
+export * from './watcher.js';

package/dist/sync/sync-cycle.d.ts

@@ -0,0 +1,18 @@
+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;

package/dist/sync/sync-cycle.js

@@ -0,0 +1,85 @@
+import path from 'node:path';
+import { assertNoLinks } from '../core/util/index.js';
+import { hostClaudeDir } from '../host/profile/index.js';
+import { hostClaudeMemDir, syncClaudeMem } from './claude-mem.js';
+import { readSyncState, writeSyncState } from './sync-state.js';
+import { syncHistoryIn, syncHistoryOut } from './history.js';
+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, scope: state.historyScope })
+        : 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,
+        historyScope: profile.historyScope,
+        syncClaudeMem: profile.syncClaudeMem,
+        syncClaudeMemBack: profile.syncClaudeMemBack,
+        projects: [],
+    };
+    if (profile.syncHistory)
+        summary.history = syncHistoryIn(toPaths(state, dataPath), { scope: profile.historyScope });
+    if (profile.syncClaudeMem) {
+        if (previous?.syncClaudeMem && previous.syncClaudeMemBack)
+            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 && state.syncClaudeMemBack)
+        summary.claudeMem = memSync(dataPath, state, 'out');
+    writeSyncState(dataPath, state);
+    return summary;
+};

package/dist/sync/sync-state.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+declare const SyncStateSchema: z.ZodObject<{
+    hostClaudeDir: z.ZodString;
+    hostWorkspace: z.ZodString;
+    guestWorkspace: z.ZodString;
+    syncHistory: z.ZodOptional<z.ZodBoolean>;
+    syncClaudeMem: z.ZodOptional<z.ZodBoolean>;
+    syncClaudeMemBack: z.ZodOptional<z.ZodBoolean>;
+    historyScope: z.ZodOptional<z.ZodEnum<{
+        project: "project";
+        all: "all";
+    }>>;
+    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>;
+/**
+ * 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;
+export {};