windows-development-sandbox 1.4.0 → 1.4.3

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

@@ -11,6 +11,27 @@ 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;
+/** 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;
+/** 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;
+/**
+ * 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 guestConflict: (guest: string, taken: readonly {
+    guest: string;
+    what: string;
+}[]) => 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).
+ */
+export declare const deriveGuest: (host: string, projectHost: string, projectGuest: string) => string;
 /** Where a guest path really is inside the sandbox (the .wsb SandboxFolder): C: paths as-is, F:\x -> C:\Mirror\F\x. */
 export declare const sandboxFolder: (guest: string) => string;
 export interface SubstDrive {

package/dist/shared/paths/guest-paths.js

@@ -0,0 +1,146 @@
+// Guest paths on drive letters other than C:. Windows Sandbox can only map folders onto its own C: drive, so a
+// guest path like F:\SteamLibrary\x is mapped to C:\Mirror\F\SteamLibrary\x and, at boot (bootstrap.ps1, before
+// anything else uses the workspace), `subst F: C:\Mirror\F` makes it appear at F:\SteamLibrary\x.
+// Pure functions only: used by the schema, the host (.wsb, session.json) and history sync.
+import { win32 } from 'node:path';
+/** Guest folders no mapping may use: the OS, the sandbox's own folders and the mirror root. */
+export const RESERVED_GUEST = /^C:\\(?:Windows|Program Files|Program Files \(x86\)|ProgramData|Users|AgentLaunch|AgentData|HostTools|nvm|Mirror)(?:\\|$)/i;
+/** Where folders for other drive letters really live inside the sandbox: C:\Mirror\<letter>. */
+export const MIRROR_ROOT = 'C:\\Mirror';
+/** Letters a mirrored path may use. Never C: (the sandbox's own disk); A:/B: are left alone (floppy-era tools). */
+export const MIRROR_LETTER = /^[D-Z]$/;
+const DRIVE_PATH = /^([A-Za-z]):\\(.*)$/;
+// No other ':' (alternate data streams), no wildcards or pipes, no control characters, no forward slashes.
+const BAD_CHARS = /[<>:"|?*/\x00-\x1f]/;
+/** The upper-case drive letter of an absolute guest path (F:\x -> F), or null. */
+export const guestDrive = (guest) => DRIVE_PATH.exec(guest)?.[1].toUpperCase() ?? null;
+/**
+ * A folder the sandbox can show a host folder at: C:\<not reserved>\... or <D-Z>:\..., never a drive root,
+ * no '..' or empty segments, no characters Windows rejects in paths.
+ */
+export const isValidGuestPath = (guest) => {
+    const m = DRIVE_PATH.exec(guest);
+    if (!m)
+        return false;
+    const letter = m[1].toUpperCase();
+    const rest = m[2].replace(/\\+$/, '');
+    if (rest === '' || BAD_CHARS.test(rest))
+        return false;
+    if (rest.split('\\').some((segment) => segment === '' || segment === '.' || segment === '..' || /[. ]$/.test(segment)))
+        return false;
+    if (letter === 'C')
+        return !RESERVED_GUEST.test('C:\\' + rest);
+    return MIRROR_LETTER.test(letter);
+};
+/** 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(/\\+$/, '');
+    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. */
+export const guestPathProblem = (guest) => {
+    if (isValidGuestPath(guest))
+        return null;
+    const letter = guestDrive(guest);
+    if (letter === 'C' && RESERVED_GUEST.test(guest))
+        return guest + ' is a folder the sandbox keeps for itself (Windows, Program Files, Users, AgentData, ...)';
+    if (letter && !MIRROR_LETTER.test(letter) && letter !== 'C')
+        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';
+};
+/** 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>.';
+/**
+ * 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 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
+ * guest folder, any other folder at the same path as on this PC (D: to Z: through C:\Mirror and subst).
+ */
+export const deriveGuest = (host, projectHost, projectGuest) => {
+    const rel = win32.relative(win32.resolve(projectHost), win32.resolve(host));
+    const inside = rel === '' || (!rel.startsWith('..') && !win32.isAbsolute(rel));
+    return inside ? (rel ? win32.join(projectGuest, rel) : projectGuest) : tidyGuestPath(win32.resolve(host));
+};
+/** 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);
+    if (!m || m[1].toUpperCase() === 'C')
+        return guest;
+    return MIRROR_ROOT + '\\' + m[1].toUpperCase() + (m[2] ? '\\' + m[2] : '');
+};
+/** The subst drives the guest must create at boot for these guest paths, one per letter, sorted. */
+export const substDrives = (guests) => {
+    const letters = [...new Set(guests.map(guestDrive).filter((l) => l !== null && l !== 'C'))].sort();
+    return letters.map((letter) => ({ letter, target: MIRROR_ROOT + '\\' + letter }));
+};
+/**
+ * guestWorkspace "mirror": the workspace at the same path as on this PC, so absolute paths (configs, build caches,
+ * cargo fingerprints, Claude's project folder) match. Falls back to `fallback` (C:\Workspace\<name>) when the host
+ * path cannot be used inside the sandbox (C:\Users\..., a UNC path, A:/B:, odd characters), with a note saying why.
+ */
+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.',
+        };
+    }
+    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.',
+    };
+};

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.d.ts → paths/projects.d.ts}

@@ -1,5 +1,12 @@
-/** Where roots, boot-mapped projects and shared folders appear inside the sandbox. */
+/** Where project roots appear inside the sandbox. */
 export declare const PROJECTS_GUEST = "C:\\Projects";
+/** Where projects mapped on their own appear (the launch folder with guestWorkspace "auto", boot-mapped and shared ones). */
+export declare const WORKSPACES_GUEST = "C:\\Workspace";
+/**
+ * guestWorkspace "auto" for a folder: C:\Workspace\<folder name>. Keeping the real folder name means Claude's
+ * per-project history and claude-mem's project name match this PC instead of every project being "Workspace".
+ */
+export declare const autoGuestFolder: (hostDir: string) => string;
 /** How a project got into the sandbox. */
 export type Mechanism = 'launch' | 'root' | 'boot' | 'wsb';
 /** One project the running sandbox works on. */
@@ -37,17 +44,33 @@ export declare const hostDirFor: (mapped: {
 }, guestDir: string) => string;
 /** Strictly below `parent` (never `parent` itself). */
 export declare const isBelow: (parent: string, child: string) => boolean;
-/** A guest folder some project can be in: below C:\Projects, or inside one of the roots (their guest paths). */
+/**
+ * A guest folder some project can be in: below C:\Projects or C:\Workspace (projects mapped on their own, also shared
+ * after boot), or inside one of `roots` (the roots' and boot-mapped projects' guest paths).
+ */
 export declare const insideProjects: (guestDir: string, roots?: string[], projectsDir?: string) => boolean;
 export interface RootMapping {
     host: string;
     guest: string;
 }
+/** The project roots that are mapped, in order: existing folders, none inside a root listed before it. */
+export declare const usableRoots: (roots: string[], exists: (dir: string) => boolean) => string[];
 /**
- * Guest folders for the project roots and the projects mapped at boot: C:\Projects\<name>, unique; with
- * guestWorkspace "mirror" a root appears at its PC path when the sandbox can show it there.
+ * Where a project mapped on its own appears, the same place it has as the launch folder: with "mirror" its PC path
+ * when the sandbox can show it there, else C:\Workspace\<name>. -2, -3, ... when that overlaps a folder in `taken`.
+ */
+export declare const ownGuestFolder: (hostDir: string, mirror: boolean, taken?: string[]) => string;
+/**
+ * Guest folders for the project roots (C:\Projects\<name>, unique; with guestWorkspace "mirror" at its PC path when
+ * the sandbox can show it there) and the projects mapped at boot (ownGuestFolder, unique against `taken` and each
+ * other). A root's folder depends only on the roots, so every launch with the same roots shows them at the same place.
  */
 export declare const planProjectMappings: (roots: string[], projects: string[], mirror: boolean, taken?: string[]) => {
     roots: RootMapping[];
     projects: RootMapping[];
 };
+/**
+ * Where a folder inside one of the (usable) roots appears: under the root's guest folder, whichever project started
+ * the sandbox. Null when it is in no root.
+ */
+export declare const rootGuestDir: (roots: string[], mirror: boolean, hostDir: string) => string | null;

package/dist/shared/paths/projects.js

@@ -0,0 +1,136 @@
+// Several projects in one running sandbox. Windows Sandbox fixes its mapped folders at boot, so a project can only
+// join a running sandbox when it is already visible inside:
+//  - the launch folder (mapped directly, or shown by the project root it is in);
+//  - a folder inside a project root (projects.roots: whole folders of projects, mapped at every start), including
+//    projects created after boot;
+//  - projects mapped at boot because they were in use when the sandbox was restarted to add them;
+//  - a folder shared into the running sandbox with `wsb share` (Windows 11 24H2+, untested).
+// A project is at the same place inside the sandbox whichever project started it (git worktrees and Claude's project
+// folders store absolute paths):
+//  - a project inside a root is always under the root's folder, C:\Projects\<root>\<name> (also as the launch folder);
+//  - any other project, mapped on its own, is always at C:\Workspace\<name> (also when it is mapped at boot or shared).
+// With guestWorkspace "mirror" both appear at their PC paths when the sandbox can show them there.
+// Pure functions only: used by the host (registration, commands), the guest (daemon checks) and the tests.
+import path from 'node:path';
+import { isValidGuestPath, planMirrorWorkspace } from './guest-paths.js';
+/** Where project roots appear inside the sandbox. */
+export const PROJECTS_GUEST = 'C:\\Projects';
+/** Where projects mapped on their own appear (the launch folder with guestWorkspace "auto", boot-mapped and shared ones). */
+export const WORKSPACES_GUEST = 'C:\\Workspace';
+/**
+ * guestWorkspace "auto" for a folder: C:\Workspace\<folder name>. Keeping the real folder name means Claude's
+ * 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, '');
+    return WORKSPACES_GUEST + '\\' + (name || 'project');
+};
+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);
+    const b = norm(child);
+    return a === b || b.startsWith(a.endsWith('\\') ? a : a + '\\');
+};
+/**
+ * A project id (also its folder name under C:\Projects) for a folder: its name with only letters, digits, '-' and
+ * '_' (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 used = new Set([...taken].map((t) => t.toLowerCase()));
+    if (!used.has(base.toLowerCase()))
+        return base;
+    for (let i = 2;; i++)
+        if (!used.has((base + '-' + i).toLowerCase()))
+            return base + '-' + i;
+};
+/** The project a folder on this PC belongs to: the most specific one that contains it (a project inside another wins). */
+export const projectForHostDir = (projects, hostDir) => projects.filter((p) => isWithin(p.host, hostDir)).sort((a, b) => b.host.length - a.host.length)[0] ?? null;
+/** The same for a folder inside the sandbox. */
+export const projectForGuestDir = (projects, guestDir) => projects.filter((p) => isWithin(p.guest, guestDir)).sort((a, b) => b.guest.length - a.guest.length)[0] ?? null;
+/** Where a folder on this PC appears inside the sandbox, given the mapped folder (project or root) that contains it. */
+export const guestDirFor = (mapped, hostDir) => {
+    const rel = path.win32.relative(path.win32.resolve(mapped.host), path.win32.resolve(hostDir));
+    return rel ? path.win32.join(mapped.guest, rel) : mapped.guest;
+};
+/** The other way: where a folder inside the sandbox is on this PC, given the mapped folder that contains it. */
+export const hostDirFor = (mapped, guestDir) => {
+    const rel = path.win32.relative(path.win32.resolve(mapped.guest), path.win32.resolve(guestDir));
+    return rel ? path.win32.join(mapped.host, rel) : mapped.host;
+};
+/** Strictly below `parent` (never `parent` itself). */
+export const isBelow = (parent, child) => isWithin(parent, child) && norm(parent) !== norm(child);
+/**
+ * A guest folder some project can be in: below C:\Projects or C:\Workspace (projects mapped on their own, also shared
+ * after boot), or inside one of `roots` (the roots' and boot-mapped projects' guest paths).
+ */
+export const insideProjects = (guestDir, roots = [], projectsDir = PROJECTS_GUEST) => isBelow(projectsDir, guestDir) || isBelow(WORKSPACES_GUEST, guestDir) || roots.some((r) => isWithin(r, guestDir));
+const resolveDir = (dir) => path.win32.resolve(dir).replace(/[\\/]+$/, '');
+/** The project roots that are mapped, in order: existing folders, none inside a root listed before it. */
+export const usableRoots = (roots, exists) => {
+    const out = [];
+    for (const root of roots.map(resolveDir))
+        if (exists(root) && !out.some((r) => isWithin(r, root)))
+            out.push(root);
+    return out;
+};
+/**
+ * Where a project mapped on its own appears, the same place it has as the launch folder: with "mirror" its PC path
+ * when the sandbox can show it there, else C:\Workspace\<name>. -2, -3, ... when that overlaps a folder in `taken`.
+ */
+export const ownGuestFolder = (hostDir, mirror, taken = []) => {
+    const host = resolveDir(hostDir);
+    const free = (guest) => !taken.some((t) => isWithin(t, guest) || isWithin(guest, t));
+    const mirrored = mirror ? planMirrorWorkspace(host, '').guest : '';
+    if (mirrored && !isWithin(PROJECTS_GUEST, mirrored) && !isWithin(WORKSPACES_GUEST, mirrored) && free(mirrored))
+        return mirrored;
+    const base = autoGuestFolder(host);
+    if (free(base))
+        return base;
+    for (let i = 2;; i++)
+        if (free(base + '-' + i))
+            return base + '-' + i;
+};
+/**
+ * Guest folders for the project roots (C:\Projects\<name>, unique; with guestWorkspace "mirror" at its PC path when
+ * the sandbox can show it there) and the projects mapped at boot (ownGuestFolder, unique against `taken` and each
+ * other). A root's folder depends only on the roots, so every launch with the same roots shows them at the same place.
+ */
+export const planProjectMappings = (roots, projects, mirror, taken = []) => {
+    const names = [];
+    const placeRoot = (host) => {
+        const resolved = resolveDir(host);
+        if (mirror && isValidGuestPath(resolved) && !isWithin(PROJECTS_GUEST, resolved))
+            return { host: resolved, guest: resolved };
+        const name = hubName(resolved, names);
+        names.push(name);
+        return { host: resolved, guest: path.win32.join(PROJECTS_GUEST, name) };
+    };
+    const planned = roots.map(placeRoot);
+    const used = [...taken, ...planned.map((r) => r.guest)];
+    const placed = projects.map((p) => {
+        const guest = ownGuestFolder(p, mirror, used);
+        used.push(guest);
+        return { host: resolveDir(p), guest };
+    });
+    return { roots: planned, projects: placed };
+};
+/**
+ * Where a folder inside one of the (usable) roots appears: under the root's guest folder, whichever project started
+ * the sandbox. Null when it is in no root.
+ */
+export const rootGuestDir = (roots, mirror, hostDir) => {
+    const root = projectForHostDir(planProjectMappings(roots, [], mirror).roots, hostDir);
+    return root ? guestDirFor(root, hostDir) : null;
+};

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/pty/console-input.d.ts

@@ -0,0 +1,11 @@
+export interface VtInput {
+    /** true once the console passes the terminal's input through (mouse reports included); false if it could not. */
+    ready: Promise<boolean>;
+    /** Stops a change still in progress; resolves when nothing can change the console mode any more. */
+    stop: () => Promise<void>;
+}
+/**
+ * Turns on ENABLE_VIRTUAL_TERMINAL_INPUT for this process's console. Call it after stdin.setRawMode(true) (which
+ * overwrites the mode); setRawMode(false) turns it off again. No-op off Windows or without a console.
+ */
+export declare const enableVtInput: () => VtInput;

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

@@ -0,0 +1,81 @@
+// Windows: lets the terminal's own input sequences (mouse clicks and wheel, focus) reach a Node process in raw mode.
+// Node reads the console as key records in raw mode and drops every mouse record, so an agent that turned mouse
+// tracking on (its terminal then sends the wheel and clicks as mouse reports) got neither. With
+// ENABLE_VIRTUAL_TERMINAL_INPUT the console hands over the terminal's input as it is: mouse reports, focus, keys.
+// 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';
+/**
+ * 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.
+ */
+const script = (pid) => [
+    'Add-Type -TypeDefinition @"',
+    'using System; using System.Runtime.InteropServices;',
+    'public static class SbxVtInput {',
+    '  [DllImport("kernel32.dll")] static extern bool FreeConsole();',
+    '  [DllImport("kernel32.dll")] static extern bool AttachConsole(uint pid);',
+    '  [DllImport("kernel32.dll", CharSet = CharSet.Unicode)] static extern IntPtr CreateFileW(string name, uint access, uint share, IntPtr security, uint creation, uint flags, IntPtr template);',
+    '  [DllImport("kernel32.dll")] static extern bool GetConsoleMode(IntPtr handle, out uint mode);',
+    '  [DllImport("kernel32.dll")] static extern bool SetConsoleMode(IntPtr handle, uint mode);',
+    '  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr handle);',
+    '  public static int On(uint pid) {',
+    '    FreeConsole();',
+    '    if (!AttachConsole(pid)) return 2;',
+    '    IntPtr input = CreateFileW("CONIN$", 0xC0000000, 3, IntPtr.Zero, 3, 0, IntPtr.Zero);',
+    '    if (input == new IntPtr(-1)) return 3;',
+    '    uint mode; bool ok = GetConsoleMode(input, out mode) && SetConsoleMode(input, mode | 0x200);',
+    '    CloseHandle(input);',
+    '    FreeConsole();',
+    '    return ok ? 0 : 4;',
+    '  }',
+    '}',
+    '"@',
+    'exit [SbxVtInput]::On(' + pid + ')',
+].join('\n');
+/**
+ * Turns on ENABLE_VIRTUAL_TERMINAL_INPUT for this process's console. Call it after stdin.setRawMode(true) (which
+ * overwrites the mode); setRawMode(false) turns it off again. No-op off Windows or without a console.
+ */
+export const enableVtInput = () => {
+    if (process.platform !== 'win32' || !process.stdin.isTTY)
+        return { ready: Promise.resolve(false), stop: () => Promise.resolve() };
+    let child = null;
+    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 });
+        }
+        catch {
+            resolve(false);
+            return;
+        }
+        exited = new Promise((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;
+        },
+    };
+};

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