windows-development-sandbox 1.4.0 → 1.4.1

package/dist/shared/download.d.ts

@@ -17,6 +17,9 @@ export interface Checksums {
 }
 /** downloads.requireChecksum: from then on download() refuses anything it has no expected hash for. The guest sets it from session.json. */
 export declare const setChecksumRequired: (on: boolean) => void;
+/** Who wants coarse download progress: called as a download starts (in the caller's async context), returns its reporter. */
+export type DownloadWatcher = () => ((fraction: number) => void) | null;
+export declare const watchDownloads: (watcher: DownloadWatcher | null) => void;
 /**
  * Streams a download to disk, hashing as it goes: big archives (PostgreSQL is ~330 MB) never sit in memory, and the
  * event loop stays free so other toolchains keep downloading meanwhile. A mismatch (or any failure) leaves no file behind.

package/dist/shared/download.js

@@ -46,6 +46,8 @@ export const fetchText = async (url) => await (await fetchRetry(url)).text();
 let checksumRequired = false;
 /** downloads.requireChecksum: from then on download() refuses anything it has no expected hash for. The guest sets it from session.json. */
 export const setChecksumRequired = (on) => { checksumRequired = on; };
+let downloadWatcher = null;
+export const watchDownloads = (watcher) => { downloadWatcher = watcher; };
 /**
  * Streams a download to disk, hashing as it goes: big archives (PostgreSQL is ~330 MB) never sit in memory, and the
  * event loop stays free so other toolchains keep downloading meanwhile. A mismatch (or any failure) leaves no file behind.
@@ -64,8 +66,29 @@ export const download = async (url, destination, expected = null) => {
         const want = sums[kind]?.trim().toLowerCase();
         return want ? [{ want, hash: crypto.createHash(kind) }] : [];
     });
-    const tap = new Transform({ transform(chunk, _encoding, done) { for (const c of checks)
-            c.hash.update(chunk); done(null, chunk); } });
+    // Progress for the boot screen: every 10% or 5 s at most, never per chunk; called here so it knows who is downloading.
+    const size = Number(response.headers.get('content-length')) || 0;
+    const report = size > 0 ? downloadWatcher?.() ?? null : null;
+    let received = 0;
+    let tenth = 0;
+    let reportedAt = Date.now();
+    const tap = new Transform({ transform(chunk, _encoding, done) {
+            for (const c of checks)
+                c.hash.update(chunk);
+            if (report) {
+                received += chunk.length;
+                const now = Math.floor((received * 10) / size);
+                if (now !== tenth || Date.now() - reportedAt > 5000) {
+                    tenth = now;
+                    reportedAt = Date.now();
+                    try {
+                        report(Math.min(1, received / size));
+                    }
+                    catch { /* progress never breaks a download */ }
+                }
+            }
+            done(null, chunk);
+        } });
     // Written to <destination>.part and moved into place only once complete and verified, so an interrupted download never
     // leaves a partial file under the real name.
     const partial = destination + '.part';

package/dist/shared/guest-paths.d.ts

@@ -11,6 +11,33 @@ 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;
+/**
+ * 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.
+ */
+export declare const placeGuest: (host: string, wanted: string, taken: {
+    guest: string;
+    what: string;
+}[]) => {
+    guest: string;
+    note: 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/guest-paths.js

@@ -2,6 +2,7 @@
 // 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>. */
@@ -31,6 +32,73 @@ 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(/\\+$/, '');
+    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';
+    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 + '\\');
+};
+/**
+ * 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.
+ */
+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.' };
+};
+/**
+ * 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));
+};
+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);

package/dist/shared/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/projects.js

@@ -1,16 +1,30 @@
 // 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, as always);
+//  - 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).
-// Roots, boot-mapped projects and shares appear under C:\Projects (roots at their PC path with guestWorkspace "mirror").
+// 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 } from './guest-paths.js';
-/** Where roots, boot-mapped projects and shared folders appear inside the sandbox. */
+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) => {
@@ -47,21 +61,66 @@ export const hostDirFor = (mapped, guestDir) => {
 };
 /** 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 inside one of the roots (their guest paths). */
-export const insideProjects = (guestDir, roots = [], projectsDir = PROJECTS_GUEST) => isBelow(projectsDir, guestDir) || roots.some((r) => isWithin(r, guestDir));
 /**
- * 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.
+ * 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 = [...taken];
-    const place = (host, tryMirror) => {
-        const resolved = path.win32.resolve(host).replace(/[\\/]+$/, '');
-        if (tryMirror && isValidGuestPath(resolved) && !isWithin(PROJECTS_GUEST, resolved))
+    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) };
     };
-    return { roots: roots.map((r) => place(r, mirror)), projects: projects.map((p) => place(p, false)) };
+    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

@@ -37,6 +37,8 @@ export type ClientResult = {
     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";
 /** 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;
@@ -82,6 +84,21 @@ export declare const queryViewers: (endpoint: Endpoint, timeoutMs?: number) => P
  * what terminals send. ConPTY reads ^H as Ctrl+Backspace (delete a word), so swap them back.
  */
 export declare const fixWindowsKeys: (chunk: Buffer) => Buffer;
+/** 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;
+}
 /**
  * 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.

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';
+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)) => {
@@ -255,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.
@@ -264,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;
@@ -280,19 +320,32 @@ 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);
         };
         // 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
@@ -328,7 +381,7 @@ export const runTerminalClient = (socket, token, options = {}) => {
                 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)
@@ -342,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/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;
@@ -20,6 +32,17 @@ export declare const SandboxStatus: z.ZodObject<{
     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
@@ -532,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),
@@ -21,6 +31,8 @@ export const SandboxStatus = z.object({
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windows-development-sandbox",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "A disposable Windows Sandbox for development, with or without an AI agent (Claude Code, Codex, Gemini, opencode, ...): the folder you run it from is the workspace, toolchains and databases for your project install themselves, and nothing else on your PC is reachable.",
   "type": "module",
   "license": "MIT",