windows-development-sandbox 1.1.0 → 1.4.1

package/dist/shared/pty-client.js

@@ -1,11 +1,14 @@
 // 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.
 import net from 'node:net';
-export const FrameType = { Hello: 1, Input: 2, Resize: 3, Restart: 4, Ping: 5, Output: 16, Exit: 17, Error: 18, Restarting: 19, Status: 20 };
+import { enableVtInput } from './console-input.js';
+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;
+/** 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';
 /** 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)) => {
@@ -47,23 +50,140 @@ export class FrameReader {
         return frames;
     }
 }
+/** OSC commands that may reach your terminal: window title (0, 1, 2), links (8), progress (9;4), shell marks (133). */
+const KEPT_OSC = (body) => {
+    const number = /^(\d{1,4})(;|$)/.exec(body);
+    if (!number)
+        return false;
+    const n = Number(number[1]);
+    return n <= 2 || n === 8 || n === 133 || (n === 9 && body.startsWith(number[1] + ';4;'));
+};
+/** Longest OSC kept (a title or a link); anything longer is dropped whole. */
+const MAX_KEPT_STRING = 4096;
 /**
- * Removes OSC 52 (clipboard write) from the sandbox's output before it reaches your terminal: an untrusted program
- * must not be able to silently put text into your clipboard. Everything else (colours, titles, links) passes.
- * Stateful, so a sequence split across chunks is still caught.
+ * Removes the terminal "strings" an untrusted program could abuse from the sandbox's output before it reaches your
+ * terminal: clipboard writes (OSC 52), terminal macros (ConEmu's OSC 9), DCS / APC / PM / SOS, and their C1 forms.
+ * Titles, links, progress and colours pass. A byte-level state machine, so no split across chunks, leading zero
+ * (ESC]052) or huge payload slips through: a dropped string stays dropped until its terminator, however long it is.
  */
 export class OutputFilter {
-    carry = '';
+    /** text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc / stringC2: a possible terminator inside one. */
+    state = 'text';
+    /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
+    body = null;
     push(chunk) {
-        let text = (this.carry + chunk.toString('latin1')).replace(/\x1b\]52;[^\x07\x1b]*(\x07|\x1b\\)/g, '');
-        this.carry = '';
-        const open = text.lastIndexOf('\x1b');
-        const tail = open === -1 ? '' : text.slice(open);
-        if (tail.length < 1 << 16 && /^\x1b(\](5(2(;[^\x07\x1b]*)?)?)?)?$/.test(tail)) {
-            this.carry = tail;
-            text = text.slice(0, open);
+        const out = Buffer.allocUnsafe(chunk.length + MAX_KEPT_STRING + 8);
+        let n = 0;
+        const put = (...bytes) => { for (const b of bytes)
+            out[n++] = b; };
+        /** After ESC (or the C1 form): ] opens an OSC (maybe kept), P X ^ _ open DCS / SOS / PM / APC (dropped). */
+        const opens = (b, c1) => {
+            if (b === (c1 ? 0x9d : 0x5d)) {
+                this.body = c1 ? null : [];
+                this.state = 'string';
+                return true;
+            }
+            if ((c1 ? [0x90, 0x98, 0x9e, 0x9f] : [0x50, 0x58, 0x5e, 0x5f]).includes(b)) {
+                this.body = null;
+                this.state = 'string';
+                return true;
+            }
+            return false;
+        };
+        const endString = (terminator) => {
+            const body = this.body && Buffer.from(this.body).toString('latin1');
+            if (body !== null && KEPT_OSC(body)) {
+                put(0x1b, 0x5d);
+                out.write(body, n, 'latin1');
+                n += body.length;
+                put(...terminator);
+            }
+            this.body = null;
+            this.state = 'text';
+        };
+        const collect = (b) => { if (this.body && this.body.push(b) > MAX_KEPT_STRING)
+            this.body = null; };
+        for (const b of chunk) {
+            switch (this.state) {
+                case 'text':
+                    if (b === 0x1b)
+                        this.state = 'esc';
+                    else if (b === 0xc2)
+                        this.state = 'c2';
+                    else
+                        put(b);
+                    break;
+                case 'esc':
+                    if (opens(b, false))
+                        break;
+                    if (b !== 0x1b) {
+                        put(0x1b, b);
+                        this.state = 'text';
+                    }
+                    else
+                        put(0x1b);
+                    break;
+                case 'c2':
+                    if (opens(b, true))
+                        break;
+                    if (b === 0x1b) {
+                        put(0xc2);
+                        this.state = 'esc';
+                    }
+                    else if (b === 0xc2)
+                        put(0xc2);
+                    else {
+                        put(0xc2, b);
+                        this.state = 'text';
+                    }
+                    break;
+                case 'string':
+                    if (b === 0x07)
+                        endString([0x07]);
+                    else if (b === 0x1b)
+                        this.state = 'stringEsc';
+                    else if (b === 0xc2)
+                        this.state = 'stringC2';
+                    else if (b === 0x18 || b === 0x1a) {
+                        this.body = null;
+                        this.state = 'text';
+                    }
+                    else
+                        collect(b);
+                    break;
+                case 'stringC2':
+                    // U+009C is the C1 string terminator; any other character is part of the string.
+                    if (b === 0x9c)
+                        endString([0x1b, 0x5c]);
+                    else {
+                        collect(0xc2);
+                        this.state = 'string';
+                        if (b === 0x07)
+                            endString([0x07]);
+                        else if (b === 0x1b)
+                            this.state = 'stringEsc';
+                        else if (b !== 0xc2)
+                            collect(b);
+                        else
+                            this.state = 'stringC2';
+                    }
+                    break;
+                case 'stringEsc':
+                    if (b === 0x5c) {
+                        endString([0x1b, 0x5c]);
+                        break;
+                    }
+                    // ESC inside a string ends it (dropped) and starts a new sequence.
+                    this.body = null;
+                    this.state = 'esc';
+                    if (!opens(b, false) && b !== 0x1b) {
+                        put(0x1b, b);
+                        this.state = 'text';
+                    }
+                    break;
+            }
         }
-        return Buffer.from(text, 'latin1');
+        return out.subarray(0, n);
     }
 }
 const connectOnce = (host, port, timeoutMs) => {
@@ -138,6 +258,41 @@ export const fixWindowsKeys = (chunk) => {
         return chunk;
     return Buffer.from(chunk.map((b) => (b === 0x08 ? 0x7f : b === 0x7f ? 0x08 : b)));
 };
+/** How long an unfinished escape sequence is held back waiting for the rest (a lone Esc key press waits this long). */
+export const JOIN_MS = 30;
+/** Longest sequence held back; anything longer is not a key, mouse report or terminal reply, and is sent as it is. */
+const MAX_HELD = 64;
+/**
+ * Keeps each escape sequence typed into your terminal (keys, mouse reports, the terminal's replies) in one INPUT frame.
+ * The console can hand one over in pieces; ConPTY reads a lone "ESC[" as Alt+[ and the rest as typed text, so a split
+ * Right arrow (ESC[C) left a stray "C" in the agent's prompt. An unfinished sequence at the end of a chunk is held
+ * until the rest arrives (or JOIN_MS passes).
+ */
+export class InputJoiner {
+    held = Buffer.alloc(0);
+    /** The bytes to send now; an unfinished sequence at the end is kept for the next chunk. */
+    push(chunk) {
+        const data = this.held.length ? Buffer.concat([this.held, chunk]) : chunk;
+        const cut = unfinishedSequence(data);
+        this.held = Buffer.from(data.subarray(cut));
+        return data.subarray(0, cut);
+    }
+    holding() { return this.held.length > 0; }
+    flush() { const out = this.held; this.held = Buffer.alloc(0); return out; }
+}
+/** Where an escape sequence that has not ended yet starts at the end of `data` (data.length if there is none). */
+const unfinishedSequence = (data) => {
+    const start = data.lastIndexOf(0x1b, -1);
+    if (start === -1 || data.length - start > MAX_HELD)
+        return data.length;
+    const rest = data.subarray(start + 1);
+    if (rest.length === 0)
+        return start;
+    // ESC [ or ESC O (SS3) followed only by parameter / intermediate bytes: the final byte has not arrived yet.
+    if (rest[0] === 0x5b || rest[0] === 0x4f)
+        return rest.subarray(1).every((b) => b >= 0x20 && b <= 0x3f) && (rest[0] === 0x5b || rest.length === 1) ? start : data.length;
+    return data.length;
+};
 /**
  * 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.
@@ -147,13 +302,15 @@ export const runTerminalClient = (socket, token, options = {}) => {
     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]; };
-    const swapKeys = process.platform === 'win32' && stdin.isTTY;
+    // 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;
@@ -163,29 +320,45 @@ export const runTerminalClient = (socket, token, options = {}) => {
             clearTimeout(resizeTimer);
             clearInterval(heartbeat);
             clearInterval(sizeWatch);
-            if (stdin.isTTY)
-                stdin.setRawMode(false);
-            stdin.pause();
+            clearTimeout(joinTimer);
             socket.destroy();
-            stdout.write('\x1b[0m\x1b[?25h\r\n');
-            resolve(result);
+            // 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;
             }
-            socket.write(encodeFrame(FrameType.Input, swapKeys ? fixWindowsKeys(chunk) : chunk));
+            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);
         };
-        // Dragging a window edge fires dozens of resizes; each one makes ConPTY reflow and repaint, and repaints racing each
-        // other are what 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.
+        // 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];
-            stdout.write('\x1b[H\x1b[J');
+            if (!passthrough)
+                stdout.write('\x1b[H\x1b[J');
             socket.write(resizeFrame(c, r));
         };
         const onResize = () => { clearTimeout(resizeTimer); resizeTimer = setTimeout(() => { resizeTimer = undefined; sendSize(); }, 120); };
@@ -205,8 +378,10 @@ export const runTerminalClient = (socket, token, options = {}) => {
             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('\x1b[2J\x1b[3J\x1b[H');
+                    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)
@@ -220,6 +395,10 @@ export const runTerminalClient = (socket, token, options = {}) => {
         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/rundir.d.ts

@@ -11,6 +11,8 @@ export declare const runPaths: (dataDir: string) => {
     responses: string;
     sessions: string;
     projects: string;
+    /** audit.processes: programs the sandbox started, in small .jsonl files the host takes in and deletes. */
+    audit: string;
     request: (id: string) => string;
     response: (id: string) => string;
     session: (id: string) => string;

package/dist/shared/rundir.js

@@ -19,6 +19,8 @@ export const runPaths = (dataDir) => {
         responses: path.join(run, 'responses'),
         sessions: path.join(run, 'sessions'),
         projects: path.join(run, 'projects'),
+        /** audit.processes: programs the sandbox started, in small .jsonl files the host takes in and deletes. */
+        audit: path.join(run, 'audit'),
         request: file('requests'),
         response: file('responses'),
         session: file('sessions'),

package/dist/shared/schema.d.ts

@@ -5,6 +5,18 @@ export declare const AttachEndpoint: z.ZodObject<{
     port: z.ZodNumber;
     token: z.ZodString;
 }, z.core.$strict>;
+/** The boot's progress in a shape the host can show: step n of m, what is being set up now, how many are done. */
+export declare const BootProgress: z.ZodObject<{
+    step: z.ZodNumber;
+    steps: z.ZodNumber;
+    title: z.ZodString;
+    active: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        percent: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    done: z.ZodNumber;
+    total: z.ZodNumber;
+}, 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;
@@ -19,6 +31,18 @@ export declare const SandboxStatus: z.ZodObject<{
     workspaceHost: z.ZodString;
     guestWorkspace: z.ZodString;
     headless: z.ZodBoolean;
+    addresses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    progress: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        step: z.ZodNumber;
+        steps: z.ZodNumber;
+        title: z.ZodString;
+        active: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            percent: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        done: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strict>>>;
 }, z.core.$strip>;
 /**
  * A project the host registered after boot (sandbox claude from another folder): everything the guest needs to
@@ -118,6 +142,9 @@ export declare const ProjectSpec: z.ZodObject<{
         }, z.core.$strict>;
         vscode: z.ZodObject<{
             enabled: z.ZodBoolean;
+            setup: z.ZodBoolean;
+            recommended: z.ZodBoolean;
+            extensions: z.ZodArray<z.ZodString>;
         }, z.core.$strict>;
         environment: z.ZodRecord<z.ZodString, z.ZodString>;
     }, z.core.$strict>;
@@ -259,6 +286,9 @@ export declare const GuestRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }, z.core.$strict>;
             vscode: z.ZodObject<{
                 enabled: z.ZodBoolean;
+                setup: z.ZodBoolean;
+                recommended: z.ZodBoolean;
+                extensions: z.ZodArray<z.ZodString>;
             }, z.core.$strict>;
             environment: z.ZodRecord<z.ZodString, z.ZodString>;
         }, z.core.$strict>;
@@ -408,6 +438,9 @@ export declare const GuestRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }, z.core.$strict>;
             vscode: z.ZodObject<{
                 enabled: z.ZodBoolean;
+                setup: z.ZodBoolean;
+                recommended: z.ZodBoolean;
+                extensions: z.ZodArray<z.ZodString>;
             }, z.core.$strict>;
             environment: z.ZodRecord<z.ZodString, z.ZodString>;
         }, z.core.$strict>;
@@ -522,6 +555,7 @@ export type ProjectSpecT = z.output<typeof ProjectSpec>;
 export type ProjectStatusT = z.output<typeof ProjectStatus>;
 export type AttachEndpointT = z.output<typeof AttachEndpoint>;
 export type SandboxStatusT = z.output<typeof SandboxStatus>;
+export type BootProgressT = z.output<typeof BootProgress>;
 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

@@ -10,6 +10,16 @@ export const AttachEndpoint = z.strictObject({
     port: z.number().int().min(1024).max(65535),
     token: Text(256),
 });
+/** The boot's progress in a shape the host can show: step n of m, what is being set up now, how many are done. */
+export const BootProgress = z.strictObject({
+    step: z.number().int().min(1).max(32),
+    steps: z.number().int().min(1).max(32),
+    title: Text(120),
+    /** Being set up now; percent while it downloads (when the size is known). */
+    active: z.array(z.strictObject({ name: Text(64), percent: z.number().int().min(0).max(100).optional() })).max(8),
+    done: z.number().int().min(0).max(1000),
+    total: z.number().int().min(0).max(1000),
+});
 /** C:\AgentData\run\sandbox.json: boot progress of the sandbox as a whole. */
 export const SandboxStatus = z.object({
     launchId: Text(64),
@@ -19,6 +29,10 @@ export const SandboxStatus = z.object({
     workspaceHost: Text(),
     guestWorkspace: Text(),
     headless: z.boolean(),
+    /** The sandbox's IPv4 addresses (for network.forwardPorts; the host only uses ones on its Hyper-V network). */
+    addresses: z.array(z.string().max(45)).max(8).optional(),
+    /** A malformed progress is dropped, never the status (the phase still counts). */
+    progress: BootProgress.optional().catch(undefined),
 });
 const Version = z.strictObject({ spec: Text(128), source: Text(256) });
 const DatabasePlan = z.strictObject({

package/dist/shared/system.d.ts

@@ -12,4 +12,5 @@ export declare const SYSTEM: {
     readonly robocopy: () => string;
     readonly shutdown: () => string;
     readonly dism: () => string;
+    readonly msiexec: () => string;
 };

package/dist/shared/system.js

@@ -16,4 +16,5 @@ export const SYSTEM = {
     robocopy: () => system32('Robocopy.exe'),
     shutdown: () => system32('shutdown.exe'),
     dism: () => system32('Dism.exe'),
+    msiexec: () => system32('msiexec.exe'),
 };

package/dist/sync/claude-mem.js

@@ -1,7 +1,7 @@
 // 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:
+// OUT (sandbox -> this PC), only with claudeProfile.syncClaudeMemBack: 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';
@@ -10,7 +10,8 @@ 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;
+// 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;
 /** 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;

package/dist/sync/history.d.ts

@@ -7,6 +7,11 @@ declare const SyncStateSchema: z.ZodObject<{
     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<{
@@ -28,6 +33,7 @@ export interface SyncPaths extends 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;
+    scope?: "project" | "all";
 }) => 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;

package/dist/sync/history.js

@@ -7,8 +7,11 @@
 //
 // 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.
+//  - what comes BACK is limited to the sandbox's own projects: their transcripts (.jsonl) and prompt-history lines,
+//    plus to-do lists (.json), each capped in size, and never Claude's memory folders. A sandbox cannot plant a
+//    conversation for another project on this PC (claude --resume there would load it);
+//  - what goes IN is, by default (historyScope "project"), only the sandbox's own projects: other projects'
+//    conversations, file backups and prompts are not the agent's business.
 import fs from 'node:fs';
 import path from 'node:path';
 import _ from 'lodash';
@@ -25,7 +28,7 @@ const MAX_FILE_BYTES = 100 * 1024 * 1024;
 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(),
+    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). */
@@ -91,6 +94,16 @@ const isJsonObject = (line) => { try {
 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());
+    }
+    catch {
+        return false;
+    }
+};
 const lineTime = (line) => { try {
     return Number(JSON.parse(line).timestamp) || 0;
 }
@@ -102,22 +115,24 @@ const pairsOf = (p) => _.sortBy([{ hostWorkspace: p.hostWorkspace, guestWorkspac
 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 = {}) => {
+    const all = options.scope === 'all';
     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 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', name)));
-    const sessions = _.sumBy(SESSION_DIRS, (dir) => copyNewer(path.join(p.hostClaudeDir, dir), path.join(p.guestClaudeDir, dir)));
+    // 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;
     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 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) {
@@ -136,15 +151,15 @@ export const syncHistoryOut = (p) => {
     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 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 }));
     // 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));
+    // 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));
     if (missing.length) {
         ensureDir(p.hostClaudeDir);
         fs.appendFileSync(hostFile, missing.join('\n') + '\n', 'utf8');