windows-development-sandbox 1.4.1 → 1.4.3

package/dist/shared/{guest-paths.d.ts → paths/guest-paths.d.ts}

@@ -11,28 +11,22 @@ export declare const guestDrive: (guest: string) => string | null;
  * no '..' or empty segments, no characters Windows rejects in paths.
  */
 export declare const isValidGuestPath: (guest: string) => boolean;
-/** Where a mapping lands when the path it asks for (or the PC path) cannot be used inside the sandbox. */
-export declare const MAPPED_ROOT = "C:\\Mapped";
 /** A guest path as typed, tidied: '/' -> '\', no doubled or trailing backslashes, upper-case drive letter. */
 export declare const tidyGuestPath: (guest: string) => string;
 /** Why a guest path cannot be used as it is (null: it can). Short, plain English. */
 export declare const guestPathProblem: (guest: string) => string | null;
-/** C:\Mapped\<drive>\<rest of path>: a safe place for a folder whose own path cannot be used (odd characters made safe). */
-export declare const mappedFallback: (path: string) => string;
 /** Two guest folders overlap where they really are (F:\x is C:\Mirror\F\x): the same, or one inside the other. */
 export declare const guestOverlaps: (a: string, b: string) => boolean;
+/** How to fix a mapping whose guest path cannot be used: `guest` is what it asked for (none = the PC path). */
+export declare const guestFix: (guest: string | undefined) => string;
 /**
- * Where an extra folder appears in the sandbox. `wanted` is the guest path asked for (or the one derived from the PC
- * path); when the sandbox cannot use it (reserved, invalid, or overlapping a folder in `taken`), the folder goes to
- * C:\Mapped\<drive>\<path> instead (made unique with -2, -3 ...), and `note` says where and why.
+ * Why a folder cannot appear at `guest` in the sandbox (null: it can): a path the sandbox cannot use, or one that
+ * overlaps a folder in `taken`. Folders are never moved somewhere else: the launch names the problem and the fix.
  */
-export declare const placeGuest: (host: string, wanted: string, taken: {
+export declare const guestConflict: (guest: string, taken: readonly {
     guest: string;
     what: string;
-}[]) => {
-    guest: string;
-    note: string | null;
-};
+}[]) => string | null;
 /**
  * The guest path a mapping asks for when it gives none: a folder inside the project at the same place in the project's
  * guest folder, any other folder at the same path as on this PC (D: to Z: through C:\Mirror and subst).

package/dist/shared/{guest-paths.js → paths/guest-paths.js}

@@ -32,11 +32,13 @@ export const isValidGuestPath = (guest) => {
         return !RESERVED_GUEST.test('C:\\' + rest);
     return MIRROR_LETTER.test(letter);
 };
-/** Where a mapping lands when the path it asks for (or the PC path) cannot be used inside the sandbox. */
-export const MAPPED_ROOT = 'C:\\Mapped';
 /** A guest path as typed, tidied: '/' -> '\', no doubled or trailing backslashes, upper-case drive letter. */
 export const tidyGuestPath = (guest) => {
-    const p = guest.trim().replace(/\//g, '\\').replace(/\\{2,}/g, '\\').replace(/\\+$/, '');
+    const p = guest
+        .trim()
+        .replace(/\//g, '\\')
+        .replace(/\\{2,}/g, '\\')
+        .replace(/\\+$/, '');
     return /^[a-z]:/.test(p) ? p[0].toUpperCase() + p.slice(1) : p;
 };
 /** Why a guest path cannot be used as it is (null: it can). Short, plain English. */
@@ -50,36 +52,38 @@ export const guestPathProblem = (guest) => {
         return 'the sandbox cannot show drive ' + letter + ':';
     if (letter && /^[A-Za-z]:\\?$/.test(guest))
         return guest + ' is a whole drive';
+    if (!letter)
+        return (guest +
+            ' is not a full path (guest paths start with a drive, such as C:\\Games\\' +
+            (guest.split('\\').pop() || 'Name') +
+            ')');
     return guest + ' is not a folder path the sandbox can use';
 };
-/** C:\Mapped\<drive>\<rest of path>: a safe place for a folder whose own path cannot be used (odd characters made safe). */
-export const mappedFallback = (path) => {
-    const m = /^([A-Za-z]):\\?(.*)$/.exec(tidyGuestPath(path)) ?? /^\\\\(.*)$/.exec(path);
-    const letter = m && m.length === 3 ? m[1].toUpperCase() : 'UNC';
-    const rest = (m ? m[m.length - 1] : path).split(/[\\/]+/).map((s) => s.replace(/[<>:"|?*\x00-\x1f]/g, '_').replace(/[. ]+$/, '')).filter((s) => s !== '' && s !== '..').join('\\');
-    return MAPPED_ROOT + '\\' + letter + (rest ? '\\' + rest : '');
-};
 /** Two guest folders overlap where they really are (F:\x is C:\Mirror\F\x): the same, or one inside the other. */
 export const guestOverlaps = (a, b) => {
     const x = sandboxFolder(a).replace(/\\+$/, '').toLowerCase();
     const y = sandboxFolder(b).replace(/\\+$/, '').toLowerCase();
     return x === y || x.startsWith(y + '\\') || y.startsWith(x + '\\');
 };
+/** How to fix a mapping whose guest path cannot be used: `guest` is what it asked for (none = the PC path). */
+export const guestFix = (guest) => guest
+    ? 'set "guest" to a full path of a free folder, such as C:\\Games\\<name>, or leave it out to use the same path as on this PC.'
+    : 'its path on this PC cannot be used inside the sandbox; give it a "guest" path such as C:\\Games\\<name>.';
 /**
- * Where an extra folder appears in the sandbox. `wanted` is the guest path asked for (or the one derived from the PC
- * path); when the sandbox cannot use it (reserved, invalid, or overlapping a folder in `taken`), the folder goes to
- * C:\Mapped\<drive>\<path> instead (made unique with -2, -3 ...), and `note` says where and why.
+ * Why a folder cannot appear at `guest` in the sandbox (null: it can): a path the sandbox cannot use, or one that
+ * overlaps a folder in `taken`. Folders are never moved somewhere else: the launch names the problem and the fix.
  */
-export const placeGuest = (host, wanted, taken) => {
-    const clash = (g) => taken.find((t) => guestOverlaps(g, t.guest));
-    const tidy = tidyGuestPath(wanted);
-    const problem = guestPathProblem(tidy);
-    const other = problem ? null : clash(tidy);
-    if (!problem && !other)
-        return { guest: tidy, note: null };
-    const why = problem ?? tidy + ' is already used by ' + other.what + (other.guest.toLowerCase() === tidy.toLowerCase() ? '' : ' (' + other.guest + ')');
-    const guest = freePlace(mappedFallback(/^[A-Za-z]:/.test(tidy) ? tidy : host), clash);
-    return { guest, note: host + ': ' + why + ', so it is at ' + guest + ' in the sandbox.' };
+export const guestConflict = (guest, taken) => {
+    const problem = guestPathProblem(guest);
+    if (problem)
+        return problem;
+    const other = taken.find((t) => guestOverlaps(guest, t.guest));
+    if (!other)
+        return null;
+    return (guest +
+        ' is already used by ' +
+        other.what +
+        (other.guest.toLowerCase() === guest.toLowerCase() ? '' : ' (' + other.guest + ')'));
 };
 /**
  * The guest path a mapping asks for when it gives none: a folder inside the project at the same place in the project's
@@ -90,15 +94,6 @@ export const deriveGuest = (host, projectHost, projectGuest) => {
     const inside = rel === '' || (!rel.startsWith('..') && !win32.isAbsolute(rel));
     return inside ? (rel ? win32.join(projectGuest, rel) : projectGuest) : tidyGuestPath(win32.resolve(host));
 };
-const freePlace = (base, clash) => {
-    const ok = (g) => isValidGuestPath(g) && !clash(g);
-    if (ok(base))
-        return base;
-    for (let i = 2; i < 1000; i++)
-        if (ok(base + '-' + i))
-            return base + '-' + i;
-    return base + '-' + Date.now();
-};
 /** Where a guest path really is inside the sandbox (the .wsb SandboxFolder): C: paths as-is, F:\x -> C:\Mirror\F\x. */
 export const sandboxFolder = (guest) => {
     const m = DRIVE_PATH.exec(guest);
@@ -120,10 +115,32 @@ export const planMirrorWorkspace = (workspaceHost, fallback) => {
     const host = workspaceHost.replace(/\\+$/, '');
     if (isValidGuestPath(host)) {
         const letter = guestDrive(host);
-        return { guest: letter + host.slice(1), note: letter === 'C' ? null : 'guestWorkspace "mirror": ' + host + ' is mapped to ' + sandboxFolder(letter + host.slice(1)) + ' and shown as ' + letter + ': (subst) inside the sandbox.' };
+        return {
+            guest: letter + host.slice(1),
+            note: letter === 'C'
+                ? null
+                : 'guestWorkspace "mirror": ' +
+                    host +
+                    ' is mapped to ' +
+                    sandboxFolder(letter + host.slice(1)) +
+                    ' and shown as ' +
+                    letter +
+                    ': (subst) inside the sandbox.',
+        };
     }
-    const why = !guestDrive(host) ? 'it is not on a drive letter'
-        : guestDrive(host) === 'C' && RESERVED_GUEST.test(host) ? 'that folder is reserved inside the sandbox (Windows, Program Files, Users, ...)'
+    const why = !guestDrive(host)
+        ? 'it is not on a drive letter'
+        : guestDrive(host) === 'C' && RESERVED_GUEST.test(host)
+            ? 'that folder is reserved inside the sandbox (Windows, Program Files, Users, ...)'
             : 'the sandbox cannot show a folder at that path';
-    return { guest: fallback, note: 'guestWorkspace "mirror": ' + host + ' cannot appear at the same path (' + why + '); using ' + fallback + ' instead.' };
+    return {
+        guest: fallback,
+        note: 'guestWorkspace "mirror": ' +
+            host +
+            ' cannot appear at the same path (' +
+            why +
+            '); using ' +
+            fallback +
+            ' instead.',
+    };
 };

package/dist/shared/paths/index.d.ts

@@ -0,0 +1,3 @@
+export * from './guest-paths.js';
+export * from './claude-paths.js';
+export * from './projects.js';

package/dist/shared/paths/index.js

@@ -0,0 +1,3 @@
+export * from './guest-paths.js';
+export * from './claude-paths.js';
+export * from './projects.js';

package/dist/shared/{projects.js → paths/projects.js}

@@ -22,10 +22,16 @@ export const WORKSPACES_GUEST = 'C:\\Workspace';
  * per-project history and claude-mem's project name match this PC instead of every project being "Workspace".
  */
 export const autoGuestFolder = (hostDir) => {
-    const name = path.win32.basename(hostDir.replace(/[\\/]+$/, '')).replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^[. ]+|[. ]+$/g, '');
+    const name = path.win32
+        .basename(hostDir.replace(/[\\/]+$/, ''))
+        .replace(/[^A-Za-z0-9._ -]/g, '_')
+        .replace(/^[. ]+|[. ]+$/g, '');
     return WORKSPACES_GUEST + '\\' + (name || 'project');
 };
-const norm = (p) => path.win32.resolve(p).replace(/[\\/]+$/, '').toLowerCase();
+const norm = (p) => path.win32
+    .resolve(p)
+    .replace(/[\\/]+$/, '')
+    .toLowerCase();
 /** `child` is `parent` or somewhere below it (Windows paths, case-insensitive). */
 export const isWithin = (parent, child) => {
     const a = norm(parent);
@@ -37,7 +43,11 @@ export const isWithin = (parent, child) => {
  * '_' (ids become file names on both sides), at most 48 characters, made unique against `taken` with -2, -3, ...
  */
 export const hubName = (hostDir, taken) => {
-    const base = path.win32.basename(path.win32.resolve(hostDir)).replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'project';
+    const base = path.win32
+        .basename(path.win32.resolve(hostDir))
+        .replace(/[^A-Za-z0-9_-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48) || 'project';
     const used = new Set([...taken].map((t) => t.toLowerCase()));
     if (!used.has(base.toLowerCase()))
         return base;

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

@@ -0,0 +1,21 @@
+import net from 'node:net';
+export interface Endpoint {
+    addresses: string[];
+    port: number;
+    token: string;
+}
+/** Tries every address the sandbox published and returns the first one that answers. */
+export declare const connect: (endpoint: Endpoint, timeoutMs?: number) => Promise<net.Socket>;
+/** Sends one control frame (e.g. RESTART) without taking over the screen. */
+export declare const sendControl: (endpoint: Endpoint, type: number) => Promise<void>;
+/** Who is watching a session right now: `remote` counts viewers on the PC (not the sandbox's own tabs). */
+export interface Viewers {
+    viewers: number;
+    remote: number;
+}
+/**
+ * Asks a session's ptyhost who is attached. Only viewers heard from in the last few seconds count, so a terminal that
+ * was closed (or a PC that went to sleep) is not reported. null when the session does not answer: an older ptyhost
+ * treats the query as a silent control connection, so the caller must not assume anything.
+ */
+export declare const queryViewers: (endpoint: Endpoint, timeoutMs?: number) => Promise<Viewers | null>;

package/dist/shared/pty/client.js

@@ -0,0 +1,79 @@
+import net from 'node:net';
+import { helloFrame, HelloFlag, encodeFrame, FrameReader, FrameType } from './protocol.js';
+const connectOnce = (host, port, timeoutMs) => {
+    return new Promise((resolve, reject) => {
+        const socket = net.connect({ host, port });
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error('timed out connecting to ' + host + ':' + port));
+        }, timeoutMs);
+        socket.once('connect', () => {
+            clearTimeout(timer);
+            socket.setNoDelay(true);
+            resolve(socket);
+        });
+        socket.once('error', (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+};
+/** Tries every address the sandbox published and returns the first one that answers. */
+export const connect = async (endpoint, timeoutMs = 3000) => {
+    const errors = [];
+    for (const address of endpoint.addresses) {
+        try {
+            return await connectOnce(address, endpoint.port, timeoutMs);
+        }
+        catch (e) {
+            errors.push(address + ': ' + (e instanceof Error ? e.message : String(e)));
+        }
+    }
+    throw new Error('Could not reach the sandbox session (' + errors.join('; ') + ')');
+};
+/** Sends one control frame (e.g. RESTART) without taking over the screen. */
+export const sendControl = async (endpoint, type) => {
+    const socket = await connect(endpoint);
+    await new Promise((resolve) => socket.end(Buffer.concat([helloFrame(endpoint.token, 80, 24, HelloFlag.ControlOnly), encodeFrame(type)]), resolve));
+};
+/**
+ * Asks a session's ptyhost who is attached. Only viewers heard from in the last few seconds count, so a terminal that
+ * was closed (or a PC that went to sleep) is not reported. null when the session does not answer: an older ptyhost
+ * treats the query as a silent control connection, so the caller must not assume anything.
+ */
+export const queryViewers = async (endpoint, timeoutMs = 2000) => {
+    let socket;
+    try {
+        socket = await connect(endpoint, timeoutMs);
+    }
+    catch {
+        return null;
+    }
+    return new Promise((resolve) => {
+        const reader = new FrameReader();
+        const done = (value) => {
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(value);
+        };
+        const timer = setTimeout(() => done(null), timeoutMs);
+        socket.on('data', (chunk) => {
+            let frames;
+            try {
+                frames = reader.push(chunk);
+            }
+            catch {
+                done(null);
+                return;
+            }
+            const status = frames.find((f) => f.type === FrameType.Status && f.payload.length >= 4);
+            if (status)
+                done({ viewers: status.payload.readInt16LE(0), remote: status.payload.readInt16LE(2) });
+            else if (frames.some((f) => f.type === FrameType.Error))
+                done(null);
+        });
+        socket.on('error', () => done(null));
+        socket.on('close', () => done(null));
+        socket.write(helloFrame(endpoint.token, 80, 24, HelloFlag.Query));
+    });
+};

package/dist/shared/{console-input.js → pty/console-input.js}

@@ -5,7 +5,7 @@
 // Node has no API for the console mode, so a PowerShell child sets it on the console both share (the input mode
 // belongs to the console, not to a handle). Only built-ins here: view.js bundles this.
 import { spawn } from 'node:child_process';
-import { SYSTEM } from './system.js';
+import { SYSTEM } from '../system.js';
 /**
  * PowerShell starts in a console of its own, hidden (so it never retitles your tab or touches its modes), then switches
  * to ours. Started without any console, powershell.exe does nothing at all.
@@ -45,17 +45,37 @@ export const enableVtInput = () => {
     let exited = Promise.resolve();
     const ready = new Promise((resolve) => {
         try {
-            child = spawn(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', Buffer.from(script(process.pid), 'utf16le').toString('base64')], { stdio: 'ignore', windowsHide: true });
+            child = spawn(SYSTEM.powershell(), [
+                '-NoLogo',
+                '-NoProfile',
+                '-NonInteractive',
+                '-ExecutionPolicy',
+                'Bypass',
+                '-EncodedCommand',
+                Buffer.from(script(process.pid), 'utf16le').toString('base64'),
+            ], { stdio: 'ignore', windowsHide: true });
         }
         catch {
             resolve(false);
             return;
         }
         exited = new Promise((done) => {
-            child?.on('exit', (code) => { resolve(code === 0); done(); });
-            child?.on('error', () => { resolve(false); done(); });
+            child?.on('exit', (code) => {
+                resolve(code === 0);
+                done();
+            });
+            child?.on('error', () => {
+                resolve(false);
+                done();
+            });
         });
     });
-    return { ready, stop: () => { if (child && child.exitCode === null && child.signalCode === null)
-            child.kill(); return exited; } };
+    return {
+        ready,
+        stop: () => {
+            if (child && child.exitCode === null && child.signalCode === null)
+                child.kill();
+            return exited;
+        },
+    };
 };

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

@@ -0,0 +1,6 @@
+export { FrameType, HelloFlag, PING_INTERVAL_MS, type Frame, DETACH_KEY, encodeFrame, helloFrame, resizeFrame, MAX_FRAME_BYTES, FrameReader, } from './protocol.js';
+export { type Endpoint, connect, sendControl, type Viewers, queryViewers } from './client.js';
+export { type ClientResult, MOUSE_OFF, fixWindowsKeys, runTerminalClient } from './terminal.js';
+export { JOIN_MS, InputJoiner } from './input-joiner.js';
+export { type VtInput, enableVtInput } from './console-input.js';
+export { OutputFilter } from './output-filter.js';

package/dist/shared/pty/index.js

@@ -0,0 +1,6 @@
+export { FrameType, HelloFlag, PING_INTERVAL_MS, DETACH_KEY, encodeFrame, helloFrame, resizeFrame, MAX_FRAME_BYTES, FrameReader, } from './protocol.js';
+export { connect, sendControl, queryViewers } from './client.js';
+export { MOUSE_OFF, fixWindowsKeys, runTerminalClient } from './terminal.js';
+export { JOIN_MS, InputJoiner } from './input-joiner.js';
+export { enableVtInput } from './console-input.js';
+export { OutputFilter } from './output-filter.js';

package/dist/shared/pty/input-joiner.d.ts

@@ -0,0 +1,15 @@
+/** How long an unfinished escape sequence is held back waiting for the rest (a lone Esc key press waits this long). */
+export declare const JOIN_MS = 30;
+/**
+ * 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 declare class InputJoiner {
+    private held;
+    /** The bytes to send now; an unfinished sequence at the end is kept for the next chunk. */
+    push(chunk: Buffer): Buffer;
+    holding(): boolean;
+    flush(): Buffer;
+}

package/dist/shared/pty/input-joiner.js

@@ -0,0 +1,44 @@
+// Keeps escape sequences typed into your terminal whole, so ConPTY never sees half of one.
+/** 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). */
+function 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;
+}

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[];
+}