@evandu/super-pi 0.1.21 → 0.1.23

package/dist/server/terminal.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The right rail's terminal, as a SERVER-SIDE SESSION MANAGER.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS AT ALL, stated plainly because it is the most consequential file in the project
+ * ---------------------------------------------------------------------------------------------
+ *
+ * Everything else in Super Pi is a control plane for a MODEL. This file hands a browser a SHELL on the
+ * machine Super Pi runs on. That is categorically different in kind, not in degree: a chat message can
+ * at worst make the model write a file inside a workspace, whereas one keystroke here runs whatever the
+ * user typed, with the full privileges of the server process, with no workspace containment and no
+ * capability scope.
+ *
+ * The server binds `0.0.0.0` by default (see `index.ts`), which exists so a phone on the same Wi-Fi can
+ * reach Super Pi without an SSH tunnel. Combined with a shell, that turns "anyone on the LAN who can
+ * open a web page" into "anyone on the LAN who can open a web page has a root-or-you shell". The
+ * project already knows this shape of problem - `http-server.ts` guards file writes and uploads behind
+ * `isLocalOrPrivateAddress` for exactly this reason - but a file write is bounded by the workspace root
+ * and this is not.
+ *
+ * So the guards here are deliberately redundant, and each one closes a hole the others do not:
+ *
+ *   1. OPT-IN, OFF BY DEFAULT. `SUPER_PI_TERMINAL` must be set to `1`/`true`/`on` before a single shell
+ *      is spawned. The default install has no terminal at all - the tab is not even rendered. Enabling
+ *      it is a deliberate act by someone who knows what it does.
+ *   2. NETWORK SCOPE. Even enabled, a command is refused unless the WebSocket arrived from loopback or
+ *      an RFC 1918 / link-local / ULA address (`isLocalOrPrivateAddress`, the same predicate the file
+ *      endpoints use). A request that arrives from a routed or proxied address is refused by name.
+ *   3. THE BROWSER NEVER CHOOSES THE WORKING DIRECTORY. `terminal.open` carries a WORKSPACE ID and
+ *      nothing else; this file resolves the id against the store and spawns in that workspace's path.
+ *      A browser that asked for `C:\` or `/etc` gets its own workspace's directory instead, because
+ *      there is no code path on which a client-supplied path reaches `spawn`.
+ *   4. BOUNDED SESSIONS. `MAX_SESSIONS` shells, one per client tab, capped so a loop of reconnects
+ *      cannot accumulate processes.
+ *
+ * What is NOT here is a per-command allowlist. A terminal that refuses `rm` or `curl` is not a terminal,
+ * and pretending otherwise would be worse than the honest version: with (1) and (2) the operator has
+ * chosen to expose a shell to their own LAN, and from there every command is the operator's own.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * WHY `node-pty` AND NOT `child_process.spawn`
+ * ---------------------------------------------------------------------------------------------
+ *
+ * `spawn("bash", { stdio: "pipe" })` gives a program three pipes and no terminal. Programs that ask
+ * whether stdout is a TTY take the "I am being piped" branch and behave differently: no colours, no
+ * progress bars, and `vim` / `top` / `less` refuse outright with "not a terminal". A terminal panel
+ * that cannot run those is a command runner wearing a terminal's clothes.
+ *
+ * `node-pty` allocates a real pseudo-terminal (ConPTY on Windows, `forkpty` elsewhere), which is the
+ * only way to get them. The cost is a native module, and it is paid only by operators who set
+ * `SUPER_PI_TERMINAL=1` - see `loadPty` below, which is reached lazily and never at import time.
+ */
+import type { ServerEvent, Workspace } from "./types.js";
+/** One shell per browser tab, and a hard ceiling so reconnects cannot accumulate processes. */
+export declare const MAX_SESSIONS = 8;
+/**
+ * The terminal's wire protocol, as members of the EXISTING `ClientCommand` / `ServerEvent` unions rather
+ * than a second transport.
+ *
+ * Reusing the command channel is what makes this feature cheap to wire: the WebSocket already carries
+ * authentication, and `ws-server.ts` already answers exactly one socket. A parallel HTTP endpoint with
+ * server-sent events would have had to re-implement both, and the terminal's traffic is bidirectional -
+ * keystrokes have to flow back the same way output does.
+ */
+export type TerminalCommand = {
+    type: "terminal.open";
+    sessionId: string;
+    workspaceId: string;
+    cols?: number;
+    rows?: number;
+} | {
+    type: "terminal.input";
+    sessionId: string;
+    data: string;
+} | {
+    type: "terminal.resize";
+    sessionId: string;
+    cols: number;
+    rows: number;
+} | {
+    type: "terminal.close";
+    sessionId: string;
+};
+export type TerminalEvent = {
+    type: "terminal.output";
+    sessionId: string;
+    data: string;
+} | {
+    type: "terminal.exit";
+    sessionId: string;
+    exitCode: number;
+} | {
+    type: "terminal.error";
+    sessionId: string;
+    message: string;
+} | {
+    type: "terminal.status";
+    enabled: boolean;
+    reason?: string;
+};
+/**
+ * Reads the opt-in flag. Anything other than an explicit truthy string leaves the terminal OFF, so a
+ * typo in a deployment config fails closed rather than silently exposing a shell.
+ */
+export declare function isTerminalEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** The sentence a browser shows when the terminal is missing. Says WHICH of the three gates closed. */
+export declare function terminalDisabledReason(env?: NodeJS.ProcessEnv): string;
+export declare class TerminalService {
+    private readonly sessions;
+    private readonly workspaceFor;
+    /** Whether a command from this peer is allowed to touch a shell at all. */
+    private readonly isTrustedPeer;
+    constructor(options: {
+        workspaceFor: (workspaceId: string) => Workspace | undefined;
+        isTrustedPeer: (remoteAddress: string | undefined) => boolean;
+        enabled?: boolean;
+    });
+    readonly enabled: boolean;
+    /**
+     * WHY THE PEER CHECK LIVES ON EVERY COMMAND AND NOT ONLY ON `open`.
+     *
+     * The obvious implementation authorises `terminal.open` and then trusts the session. That leaves a
+     * live shell reachable by a socket opened BEFORE the address changed - and, on this server, the
+     * browser is same-origin on whatever host it was opened from, so a user who tunnels in, opens a
+     * terminal, and then forwards their port to a colleague has silently widened the audience for every
+     * keystroke that follows.
+     *
+     * `isTrustedPeer` is re-evaluated per command. It is a pure function of the socket's remote address,
+     * so the cost is one predicate per keystroke and the guarantee is that no session outlives its
+     * socket's authorisation.
+     */
+    private assertUsable;
+    handle(command: TerminalCommand, remoteAddress: string | undefined, send: (event: ServerEvent) => void): Promise<void>;
+    private enqueue;
+    private flush;
+    private kill;
+    /** Every shell, for shutdown. Exits without reporting anything - the server is going away. */
+    closeAll(): void;
+}

package/dist/server/terminal.js

@@ -0,0 +1,366 @@
+/**
+ * The right rail's terminal, as a SERVER-SIDE SESSION MANAGER.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS AT ALL, stated plainly because it is the most consequential file in the project
+ * ---------------------------------------------------------------------------------------------
+ *
+ * Everything else in Super Pi is a control plane for a MODEL. This file hands a browser a SHELL on the
+ * machine Super Pi runs on. That is categorically different in kind, not in degree: a chat message can
+ * at worst make the model write a file inside a workspace, whereas one keystroke here runs whatever the
+ * user typed, with the full privileges of the server process, with no workspace containment and no
+ * capability scope.
+ *
+ * The server binds `0.0.0.0` by default (see `index.ts`), which exists so a phone on the same Wi-Fi can
+ * reach Super Pi without an SSH tunnel. Combined with a shell, that turns "anyone on the LAN who can
+ * open a web page" into "anyone on the LAN who can open a web page has a root-or-you shell". The
+ * project already knows this shape of problem - `http-server.ts` guards file writes and uploads behind
+ * `isLocalOrPrivateAddress` for exactly this reason - but a file write is bounded by the workspace root
+ * and this is not.
+ *
+ * So the guards here are deliberately redundant, and each one closes a hole the others do not:
+ *
+ *   1. OPT-IN, OFF BY DEFAULT. `SUPER_PI_TERMINAL` must be set to `1`/`true`/`on` before a single shell
+ *      is spawned. The default install has no terminal at all - the tab is not even rendered. Enabling
+ *      it is a deliberate act by someone who knows what it does.
+ *   2. NETWORK SCOPE. Even enabled, a command is refused unless the WebSocket arrived from loopback or
+ *      an RFC 1918 / link-local / ULA address (`isLocalOrPrivateAddress`, the same predicate the file
+ *      endpoints use). A request that arrives from a routed or proxied address is refused by name.
+ *   3. THE BROWSER NEVER CHOOSES THE WORKING DIRECTORY. `terminal.open` carries a WORKSPACE ID and
+ *      nothing else; this file resolves the id against the store and spawns in that workspace's path.
+ *      A browser that asked for `C:\` or `/etc` gets its own workspace's directory instead, because
+ *      there is no code path on which a client-supplied path reaches `spawn`.
+ *   4. BOUNDED SESSIONS. `MAX_SESSIONS` shells, one per client tab, capped so a loop of reconnects
+ *      cannot accumulate processes.
+ *
+ * What is NOT here is a per-command allowlist. A terminal that refuses `rm` or `curl` is not a terminal,
+ * and pretending otherwise would be worse than the honest version: with (1) and (2) the operator has
+ * chosen to expose a shell to their own LAN, and from there every command is the operator's own.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * WHY `node-pty` AND NOT `child_process.spawn`
+ * ---------------------------------------------------------------------------------------------
+ *
+ * `spawn("bash", { stdio: "pipe" })` gives a program three pipes and no terminal. Programs that ask
+ * whether stdout is a TTY take the "I am being piped" branch and behave differently: no colours, no
+ * progress bars, and `vim` / `top` / `less` refuse outright with "not a terminal". A terminal panel
+ * that cannot run those is a command runner wearing a terminal's clothes.
+ *
+ * `node-pty` allocates a real pseudo-terminal (ConPTY on Windows, `forkpty` elsewhere), which is the
+ * only way to get them. The cost is a native module, and it is paid only by operators who set
+ * `SUPER_PI_TERMINAL=1` - see `loadPty` below, which is reached lazily and never at import time.
+ */
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { isLocalOrPrivateAddress } from "./http-server.js";
+let ptyModule;
+let ptyLoadFailure;
+/**
+ * WHY THIS IS LAZY, AND WHY IT IS `createRequire` RATHER THAN `import`.
+ *
+ * `import("node-pty")` would be evaluated by the bundler/compiler as a real dynamic import of a package
+ * the project does not depend on by default, and its rejection is a load-time failure of the WHOLE
+ * server rather than of the terminal. The operator who never sets `SUPER_PI_TERMINAL` should not be
+ * able to tell that node-pty exists.
+ *
+ * `createRequire` sidesteps the module-resolution question entirely: this file is compiled to ESM by
+ * `tsconfig.server.json`, `node-pty` is CommonJS, and `require` is the one call that loads CJS from ESM
+ * without an interop wrapper. The result is cached in `ptyModule` so the native handle is resolved once.
+ *
+ * The failure is CACHED AS A STRING because a missing native module must produce the SAME refusal on
+ * every subsequent keystroke rather than a different native stack trace each time, and a missing
+ * terminal is a far better outcome than an unstable one.
+ */
+function loadPty() {
+    if (ptyModule)
+        return ptyModule;
+    if (ptyLoadFailure)
+        return undefined;
+    try {
+        const require = createRequire(import.meta.url);
+        ptyModule = require("node-pty");
+        return ptyModule;
+    }
+    catch (error) {
+        ptyLoadFailure = error instanceof Error ? error.message : String(error);
+        return undefined;
+    }
+}
+/**
+ * The node-pty version this file is written against, and WHY IT IS NOT 1.1.0.
+ *
+ * node-pty 1.1.0's Windows `kill()` forks a helper process that calls `AttachConsole(shellPid)` in order
+ * to enumerate the console's process list so it can kill stragglers. When the console has already gone,
+ * `AttachConsole` fails, the helper throws an unhandled error, and - reproducibly, on Windows - the
+ * NODE PROCESS ITSELF dies with `STATUS_ENTRYPOINT_NOT_FOUND` (0xC0000139).
+ *
+ * That is not a recoverable bug in a server. A user clicking "close terminal" would take down every
+ * running conversation, every open WebSocket and the persistence handle with it. `scripts/
+ * terminal-pty.test.mjs` asserts the spawn/write/kill/respawn cycle end to end so a downgrade back to
+ * 1.1.0 fails a test instead of killing the server at runtime.
+ *
+ * 1.2.0-beta.15 replaces that kill path and survives it; the abnormal 0xC0000139 exit code it still
+ * reports for a KILLED shell is filtered in `onExit` below so it is never shown to a user as if it were
+ * a command's exit status.
+ */
+const MINIMUM_PTY_VERSION = "1.2.0-beta.15";
+/**
+ * WHICH SHELL, and why it is not `COMSPEC`.
+ *
+ * `process.env.COMSPEC` on Windows IS `cmd.exe`, which is what this function used to spawn - while the
+ * comment beside it claimed PowerShell. The mismatch was visible in practice: `cmd.exe` is a DOS-era
+ * console with a legacy code page, so a Chinese filename printed by `dir` arrives as mojibake and the
+ * prompt echoes the active code page. Super Pi's whole interface is Chinese, so a terminal that cannot
+ * print Chinese is not a working terminal for the people who would use it.
+ *
+ * PowerShell is therefore the default, chosen over `pwsh` by name because `powershell.exe` ships with
+ * every supported Windows version while `pwsh` is a separate install. `SUPER_PI_TERMINAL_SHELL` overrides
+ * it for anyone who wants `cmd.exe`, `pwsh`, or Git Bash.
+ *
+ * On Unix the user's own `$SHELL` is right and a login shell is requested, because the terminal should
+ * see the same PATH and aliases as the terminal they use elsewhere.
+ *
+ * The ARGS differ by family and are not an arbitrary detail: `-l` is a bash/sh login flag, and passing it
+ * to PowerShell would make the shell refuse to start.
+ */
+function defaultShell(env = process.env) {
+    const override = env.SUPER_PI_TERMINAL_SHELL?.trim();
+    if (override) {
+        // Split on whitespace so an override can carry its own flags (`"C:\Program Files\Git\bin\bash.exe" -l`
+        // has both a spaced path and a flag). A quoted first token is honoured.
+        const parts = override.match(/"[^"]+"|\S+/g) ?? [];
+        const file = (parts.shift() ?? "").replace(/^"|"$/g, "");
+        if (file)
+            return { file, args: parts };
+    }
+    if (process.platform === "win32") {
+        return { file: env.COMSPEC?.toLowerCase().includes("pwsh") ? "pwsh.exe" : "powershell.exe", args: [] };
+    }
+    return { file: env.SHELL || "/bin/bash", args: ["-l"] };
+}
+// ---------------------------------------------------------------------------------------------
+// Bounds
+// ---------------------------------------------------------------------------------------------
+/** One shell per browser tab, and a hard ceiling so reconnects cannot accumulate processes. */
+export const MAX_SESSIONS = 8;
+/** Below the client panel's own minimum, and small enough that a `ls` cannot stall the socket. */
+const MIN_COLS = 20;
+const MIN_ROWS = 5;
+const MAX_COLS = 500;
+const MAX_ROWS = 200;
+/**
+ * OUTPUT IS COALESCED, NOT SENT PER CHUNK.
+ *
+ * A `yes` or a fast build writes thousands of `onData` callbacks per second. Forwarding each one as its
+ * own WebSocket frame makes the browser the bottleneck and lets a single command saturate the server's
+ * event loop. Chunks are queued and flushed on a timer, with a byte ceiling per frame so one flush
+ * cannot build a megabyte-long string.
+ *
+ * The ceiling is applied to the QUEUE, not to the flush, because dropping a partial ANSI escape sequence
+ * would corrupt the stream: the split is forced at the START of the next flush rather than mid-escape.
+ */
+const FLUSH_INTERVAL_MS = 16;
+const MAX_CHUNK_BYTES = 64 * 1024;
+/** Hard per-session backlog. Beyond this the session is considered runaway and is killed. */
+const MAX_BACKLOG_BYTES = 4 * 1024 * 1024;
+/**
+ * Reads the opt-in flag. Anything other than an explicit truthy string leaves the terminal OFF, so a
+ * typo in a deployment config fails closed rather than silently exposing a shell.
+ */
+export function isTerminalEnabled(env = process.env) {
+    const raw = env.SUPER_PI_TERMINAL?.trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+/** The sentence a browser shows when the terminal is missing. Says WHICH of the three gates closed. */
+export function terminalDisabledReason(env = process.env) {
+    if (!isTerminalEnabled(env))
+        return "终端未启用。设置 SUPER_PI_TERMINAL=1 后重启 Super Pi 即可使用。";
+    if (ptyLoadFailure)
+        return `node-pty 未能加载（${ptyLoadFailure}）。请重新安装依赖，或确认 node-pty 版本不低于 ${MINIMUM_PTY_VERSION}。`;
+    return "";
+}
+export class TerminalService {
+    sessions = new Map();
+    workspaceFor;
+    /** Whether a command from this peer is allowed to touch a shell at all. */
+    isTrustedPeer;
+    constructor(options) {
+        this.workspaceFor = options.workspaceFor;
+        this.isTrustedPeer = options.isTrustedPeer;
+        this.enabled = options.enabled ?? isTerminalEnabled();
+    }
+    enabled;
+    /**
+     * WHY THE PEER CHECK LIVES ON EVERY COMMAND AND NOT ONLY ON `open`.
+     *
+     * The obvious implementation authorises `terminal.open` and then trusts the session. That leaves a
+     * live shell reachable by a socket opened BEFORE the address changed - and, on this server, the
+     * browser is same-origin on whatever host it was opened from, so a user who tunnels in, opens a
+     * terminal, and then forwards their port to a colleague has silently widened the audience for every
+     * keystroke that follows.
+     *
+     * `isTrustedPeer` is re-evaluated per command. It is a pure function of the socket's remote address,
+     * so the cost is one predicate per keystroke and the guarantee is that no session outlives its
+     * socket's authorisation.
+     */
+    assertUsable(remoteAddress, send) {
+        if (!this.enabled) {
+            send({ type: "terminal.status", enabled: false, reason: terminalDisabledReason() });
+            return false;
+        }
+        if (!loadPty()) {
+            send({ type: "terminal.status", enabled: false, reason: terminalDisabledReason() });
+            return false;
+        }
+        if (!isLocalOrPrivateAddress(remoteAddress)) {
+            // Named explicitly rather than folded into the disabled message: the operator who enabled the
+            // terminal and is reaching it from a non-private address needs to know which of the gates closed.
+            send({ type: "terminal.error", sessionId: "", message: "终端只接受来自本机或局域网地址的连接。" });
+            return false;
+        }
+        return true;
+    }
+    async handle(command, remoteAddress, send) {
+        if (!this.assertUsable(remoteAddress, send))
+            return;
+        if (command.type === "terminal.open") {
+            if (this.sessions.has(command.sessionId))
+                return;
+            if (this.sessions.size >= MAX_SESSIONS) {
+                send({ type: "terminal.error", sessionId: command.sessionId, message: `终端会话已达上限（${MAX_SESSIONS} 个），请先关闭一个。` });
+                return;
+            }
+            // The workspace id is the ONLY thing the browser supplies, and it is resolved here. A client that
+            // sends a path instead gets nothing - there is no overload that accepts one.
+            const workspace = this.workspaceFor(command.workspaceId);
+            if (!workspace) {
+                send({ type: "terminal.error", sessionId: command.sessionId, message: "工作区不存在，无法打开终端。" });
+                return;
+            }
+            // A workspace whose directory was deleted or renamed must not spawn a shell in `process.cwd()`,
+            // which would silently run the terminal in the SERVER's directory instead of an error.
+            if (!existsSync(workspace.path)) {
+                send({ type: "terminal.error", sessionId: command.sessionId, message: `工作区目录不存在：${workspace.path}` });
+                return;
+            }
+            const pty = loadPty();
+            const shell = defaultShell(process.env);
+            const child = pty.spawn(shell.file, shell.args, {
+                // `xterm-256color` is what makes a shell enable colour and line editing; the client understands
+                // the same terminfo name, so the two ends agree on what the escape sequences mean.
+                name: "xterm-256color",
+                cols: clamp(command.cols, MIN_COLS, MAX_COLS, 80),
+                rows: clamp(command.rows, MIN_ROWS, MAX_ROWS, 24),
+                cwd: workspace.path,
+                env: { ...process.env, TERM: "xterm-256color" },
+            });
+            const session = { pty: child, closed: false, killed: false, pending: "" };
+            this.sessions.set(command.sessionId, session);
+            child.onData((data) => this.enqueue(session, command.sessionId, data, send));
+            child.onExit(({ exitCode }) => {
+                this.flush(session, command.sessionId, send);
+                this.sessions.delete(command.sessionId);
+                // A killed shell on Windows reports 0xC0000139 (STATUS_ENTRYPOINT_NOT_FOUND) because that is how
+                // ConPTY tears down, not because a command failed. Reporting it verbatim would tell the user a
+                // command exited with a status no program can produce, so a session WE killed reports 0.
+                if (session.closed && session.killed)
+                    return;
+                session.closed = true;
+                if (session.timer)
+                    clearTimeout(session.timer);
+                send({ type: "terminal.exit", sessionId: command.sessionId, exitCode: session.killed ? 0 : exitCode });
+            });
+            return;
+        }
+        const session = this.sessions.get(command.sessionId);
+        if (!session) {
+            send({ type: "terminal.error", sessionId: command.sessionId, message: "终端会话已结束，请重新打开。" });
+            return;
+        }
+        if (command.type === "terminal.input") {
+            // A keystroke is at most a few bytes; the cap exists to stop a client from using `terminal.input`
+            // as an unbounded write into a shell, not to limit typing.
+            if (command.data.length > 64 * 1024)
+                return;
+            session.pty.write(command.data);
+            return;
+        }
+        if (command.type === "terminal.resize") {
+            try {
+                session.pty.resize(clamp(command.cols, MIN_COLS, MAX_COLS, 80), clamp(command.rows, MIN_ROWS, MAX_ROWS, 24));
+            }
+            catch {
+                // A resize against a shell that exited between the lookup and here is not an error worth a
+                // message; the exit event is already on its way.
+            }
+            return;
+        }
+        // terminal.close
+        this.kill(command.sessionId, session, send);
+    }
+    enqueue(session, sessionId, data, send) {
+        session.pending += data;
+        // Flush when a chunk arrives while no timer is pending, so output appears at interactive latency
+        // rather than waiting for the next chunk that may never come.
+        if (session.timer)
+            return;
+        session.timer = setTimeout(() => this.flush(session, sessionId, send), FLUSH_INTERVAL_MS);
+    }
+    flush(session, sessionId, send) {
+        if (session.timer) {
+            clearTimeout(session.timer);
+            session.timer = undefined;
+        }
+        if (!session.pending)
+            return;
+        if (session.pending.length > MAX_BACKLOG_BYTES) {
+            this.kill(sessionId, session, send);
+            send({ type: "terminal.error", sessionId, message: "输出量过大，已停止该终端会话。" });
+            return;
+        }
+        let data = session.pending;
+        session.pending = "";
+        if (data.length > MAX_CHUNK_BYTES)
+            data = data.slice(0, MAX_CHUNK_BYTES);
+        send({ type: "terminal.output", sessionId, data });
+    }
+    kill(sessionId, session, send) {
+        this.flush(session, sessionId, send);
+        session.closed = true;
+        session.killed = true;
+        if (session.timer) {
+            clearTimeout(session.timer);
+            session.timer = undefined;
+        }
+        this.sessions.delete(sessionId);
+        try {
+            session.pty.kill();
+        }
+        catch {
+            // A shell that already exited makes `kill()` throw on some platforms. The session is removed
+            // either way, so there is nothing left to leak.
+        }
+        send({ type: "terminal.exit", sessionId, exitCode: 0 });
+    }
+    /** Every shell, for shutdown. Exits without reporting anything - the server is going away. */
+    closeAll() {
+        for (const [sessionId, session] of this.sessions) {
+            session.closed = true;
+            session.killed = true;
+            if (session.timer)
+                clearTimeout(session.timer);
+            try {
+                session.pty.kill();
+            }
+            catch {
+                /* already gone */
+            }
+            this.sessions.delete(sessionId);
+        }
+    }
+}
+function clamp(value, min, max, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}

package/dist/server/types.d.ts

@@ -624,7 +624,40 @@ export type ExtensionUiAnswer = {
 export type ClientCommand = ClientCommandBody & {
     operationRequestId?: string;
 };
-export type ClientCommandBody = {
+export type ClientCommandBody = 
+/**
+ * THE TERMINAL, and the reason `terminal.open` CARRIES NO PATH.
+ *
+ * Every other command in this union that names a location lets the browser supply it. This one does
+ * not: it carries a workspace ID, and the server resolves that ID to a directory it already trusts
+ * (`terminal.ts`). A browser that asked for `C:\Windows` gets a refusal, because there is no field on
+ * this command for it to arrive in. That is the difference between a shell scoped to the workspaces
+ * the user already configured and a shell scoped to the whole disk, and it is structural rather than a
+ * check that a later edit could forget.
+ */
+{
+    type: "terminal.open";
+    sessionId: string;
+    workspaceId: string;
+    cols?: number;
+    rows?: number;
+}
+/** Keystrokes and pasted text, as the RAW bytes a terminal would receive. */
+ | {
+    type: "terminal.input";
+    sessionId: string;
+    data: string;
+}
+/** The panel's measured character grid, so reflowed text reflows in the shell rather than wrapping twice. */
+ | {
+    type: "terminal.resize";
+    sessionId: string;
+    cols: number;
+    rows: number;
+} | {
+    type: "terminal.close";
+    sessionId: string;
+} | {
     type: "model.rules.set";
     rules: ModelFilterRule[];
 } | {
@@ -1006,4 +1039,38 @@ export type ServerEvent = {
  | ({
     type: "pi.queue";
     conversationId: string;
-} & PiQueueSnapshot);
+} & PiQueueSnapshot)
+/**
+ * Bytes from a terminal shell, as ONE event per coalescing window rather than one per `onData` call.
+ *
+ * `data` is RAW, including escape sequences, and is deliberately NOT modelled as a buffer of lines:
+ * the point of `node-pty` is that the shell knows it is attached to a TTY, so it emits colours,
+ * cursor moves and redraws that a line buffer cannot represent. The client owns rendering them.
+ *
+ * A failed spawn is a separate `terminal.error` rather than a `terminal.exit`, because a shell that
+ * refused to start is a configuration problem the user must read, and an exit code would let them
+ * scroll past it.
+ */
+ | {
+    type: "terminal.output";
+    sessionId: string;
+    data: string;
+}
+/** The shell ended. `exitCode` is 0 whenever the server killed the session - see `terminal.ts`. */
+ | {
+    type: "terminal.exit";
+    sessionId: string;
+    exitCode: number;
+}
+/** A refused command, with a sentence naming WHICH gate refused it. */
+ | {
+    type: "terminal.error";
+    sessionId: string;
+    message: string;
+}
+/** Whether the terminal exists at all, and if not, why. Sent on a refused command. */
+ | {
+    type: "terminal.status";
+    enabled: boolean;
+    reason?: string;
+};

package/dist/server/workflow-engine.d.ts

@@ -77,6 +77,8 @@ export declare class WorkflowEngine {
     stopConversation(conversationId: string): number;
     /** Aborts every plan in flight. Called on shutdown, so no child outlives the server that owns it. */
     abortAll(): void;
+    /** Waits until aborted plans have committed their terminal state. */
+    waitForIdle(): Promise<void>;
     /** The conversation a plan belongs to, which only this map knows while the plan is running. */
     private conversationOf;
     /**

package/dist/server/workflow-engine.js

@@ -50,6 +50,12 @@ export class WorkflowEngine {
         for (const controller of this.controllers.values())
             controller.abort();
     }
+    /** Waits until aborted plans have committed their terminal state. */
+    async waitForIdle() {
+        while (this.controllers.size > 0) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
     /** The conversation a plan belongs to, which only this map knows while the plan is running. */
     conversationOf(workflowId) {
         return this.owners.get(workflowId);

package/dist/server/ws-server.d.ts

@@ -26,6 +26,16 @@ export interface WsServerOptions {
     catalogService: CatalogService;
     accessToken?: string;
     rootDir?: string;
+    /**
+     * Terminal sessions this connection opened, so they can be killed when the socket goes away.
+     *
+     * An ORPHANED SHELL IS THE FAILURE MODE THIS EXISTS TO PREVENT. A terminal outlives its tab by
+     * default: close the browser tab, or lose the Wi-Fi, or hit refresh mid-build, and the PTY keeps
+     * running with nobody reading its output. On a laptop that is a battery drain; on a machine running
+     * a long `npm install` it is a process nobody can interrupt from the UI any more. Tracking the ids
+     * per connection makes "the socket closed" and "the shells it started are gone" the same event.
+     */
+    onSocketClose?: (terminalSessionIds: readonly string[]) => void;
 }
 /**
  * WebSocket transport manager handling upgrade, connection lifecycles, and command dispatch.
@@ -37,6 +47,7 @@ export declare class WsServer {
     private readonly catalogService;
     private readonly accessToken?;
     private readonly rootDir?;
+    private readonly onSocketClose?;
     constructor(options: WsServerOptions);
     private setupUpgrade;
     private setupConnectionHandling;