windows-development-sandbox 1.4.0 → 1.4.3

package/dist/shared/pty/output-filter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare class OutputFilter {
+    /** text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc / stringC2: a possible terminator inside one. */
+    private state;
+    /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
+    private body;
+    push(chunk: Buffer): Buffer;
+}

package/dist/shared/pty/output-filter.js

@@ -0,0 +1,140 @@
+/** 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 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 {
+    /** 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) {
+        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 out.subarray(0, n);
+    }
+}

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

@@ -0,0 +1,36 @@
+export declare const FrameType: {
+    readonly Hello: 1;
+    readonly Input: 2;
+    readonly Resize: 3;
+    readonly Restart: 4;
+    readonly Ping: 5;
+    readonly Output: 16;
+    readonly Exit: 17;
+    readonly Error: 18;
+    readonly Restarting: 19;
+    readonly Status: 20;
+    readonly Console: 21;
+};
+/** HELLO flags: control-only connections get no output and never size the console; a query only asks for STATUS. */
+export declare const HelloFlag: {
+    readonly ControlOnly: 1;
+    readonly 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 declare const PING_INTERVAL_MS = 5000;
+export interface Frame {
+    type: number;
+    payload: Buffer;
+}
+/** Ctrl+] — the same detach key telnet uses; Claude Code does not bind it. */
+export declare const DETACH_KEY = 29;
+export declare const encodeFrame: (type: number, payload?: Buffer) => Buffer;
+export declare const helloFrame: (token: string, cols: number, rows: number, flags?: number) => Buffer;
+export declare const resizeFrame: (cols: number, rows: number) => Buffer;
+/** Same limit as ptyhost.cs; a peer announcing more is broken or hostile. */
+export declare const MAX_FRAME_BYTES: number;
+/** Splits a TCP byte stream back into frames. */
+export declare class FrameReader {
+    private pending;
+    push(chunk: Buffer): Frame[];
+}

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;