@moxxy/plugin-terminal 0.27.0

package/dist/terminal.js

@@ -0,0 +1,437 @@
+import { randomBytes } from 'node:crypto';
+import { defineSurface, defineTool, z } from '@moxxy/sdk';
+import { createTerminalProcess } from './pty.js';
+/**
+ * Shared terminal processes, keyed by cwd. The surface and the `terminal` tool
+ * resolve the SAME process for a cwd, so a command the agent runs appears in the
+ * pane the user is watching (and vice-versa). A dead process is replaced on the
+ * next request.
+ */
+const shared = new Map();
+/**
+ * In-flight creates, keyed by cwd. Memoizing the PROMISE (not the resolved
+ * process) closes a create race: `createTerminalProcess` awaits, so two
+ * concurrent callers for the same cwd would both miss `shared`, both spawn a
+ * shell, and the second `set` would orphan the first PTY. By recording the
+ * promise synchronously before awaiting, the second caller reuses the first's
+ * in-flight create instead of spawning a duplicate.
+ */
+const pending = new Map();
+/**
+ * Monotonic shutdown generation, bumped by every `closeAllTerminals`. A create
+ * captures the epoch when it STARTS; if a shutdown happened since (the epoch
+ * advanced), its continuation self-disposes — the kill loop already ran and
+ * cleared `shared`, so storing that freshly-spawned shell would strand a live
+ * PTY/child past session teardown (the onShutdown hook already fired).
+ *
+ * A counter, not a boolean, on purpose: a new session reusing this module
+ * singleton calls `getSharedTerminal` again, which must re-arm so the NEW
+ * create is retained. A boolean reset on every call would ALSO resurrect a
+ * STALE pre-shutdown create that resolves after the re-arm, double-spawning and
+ * orphaning a shell. Comparing the create's captured epoch to the live one
+ * disposes only the creates that actually straddle a shutdown, regardless of
+ * later re-arms.
+ */
+let epoch = 0;
+export async function getSharedTerminal(cwd, create = createTerminalProcess) {
+    const existing = shared.get(cwd);
+    if (existing && existing.alive)
+        return existing;
+    const inFlight = pending.get(cwd);
+    if (inFlight)
+        return inFlight;
+    // Capture the epoch this create belongs to. If a shutdown bumps `epoch` while
+    // we await, the continuation sees the mismatch and disposes the orphan.
+    const startedEpoch = epoch;
+    const promise = (async () => {
+        const proc = await create(cwd);
+        // A shutdown landed while this create was in flight (epoch advanced) — the
+        // kill loop already ran and cleared `shared`, so dispose this orphan
+        // immediately instead of storing a shell nothing will ever kill.
+        if (epoch !== startedEpoch) {
+            proc.kill();
+            return proc;
+        }
+        shared.set(cwd, proc);
+        proc.onExit(() => {
+            if (shared.get(cwd) === proc)
+                shared.delete(cwd);
+        });
+        return proc;
+    })().finally(() => {
+        // Clear the in-flight slot only once this create settles, AND only if it's
+        // still ours — a shutdown + re-arm may have replaced the slot with a newer
+        // create for the same cwd, which we must not clobber.
+        if (pending.get(cwd) === promise)
+            pending.delete(cwd);
+    });
+    pending.set(cwd, promise);
+    return promise;
+}
+/** Dispose every shared terminal (plugin shutdown / session close). */
+export function closeAllTerminals() {
+    // Bump the epoch FIRST so any create that resolves after this point sees the
+    // mismatch and self-kills (see getSharedTerminal). `pending.clear()` alone is
+    // insufficient — the promise body still runs to completion and would
+    // otherwise store the proc.
+    epoch += 1;
+    for (const proc of shared.values())
+        proc.kill();
+    shared.clear();
+    pending.clear();
+}
+/** A terminal dimension (cols/rows) is usable only if it's a finite, positive
+ *  number. Rejects NaN/Infinity/0/negatives/floats-with-no-magnitude before
+ *  they reach the PTY, where they'd throw or be silently coerced. */
+function isValidDimension(n) {
+    return typeof n === 'number' && Number.isFinite(n) && n >= 1;
+}
+// --- Surface ----------------------------------------------------------------
+/** The `terminal` surface: streams the shared PTY's output and feeds a viewer's
+ *  keystrokes / resizes back into it. */
+export function buildTerminalSurface() {
+    return defineSurface({
+        kind: 'terminal',
+        description: 'An embedded shell the user and the agent share.',
+        open: async (ctx) => {
+            const proc = await getSharedTerminal(ctx.cwd);
+            const dataSubs = new Set();
+            const emit = (payload) => {
+                for (const cb of dataSubs) {
+                    try {
+                        cb(payload);
+                    }
+                    catch {
+                        /* a bad viewer must not break the stream (matches pty.ts emitData) */
+                    }
+                }
+            };
+            const unsubData = proc.onData((data) => emit({ type: 'data', data }));
+            const unsubExit = proc.onExit((code) => emit({ type: 'exit', code }));
+            // Honest degraded state: without a real PTY the pane can't function as an
+            // interactive terminal (no echo, a viewer's Enter never reaches the shell).
+            // Tell the viewer rather than presenting a box that silently ignores input.
+            if (proc.backend === 'pipe') {
+                emit({
+                    type: 'status',
+                    text: proc.ptyError
+                        ? `Terminal unavailable: the PTY backend failed to start (${proc.ptyError}).`
+                        : 'Terminal unavailable: a real PTY backend (node-pty) is not available.',
+                });
+            }
+            return {
+                id: 'terminal',
+                kind: 'terminal',
+                onData: (cb) => {
+                    dataSubs.add(cb);
+                    return () => dataSubs.delete(cb);
+                },
+                snapshot: () => ({
+                    type: 'snapshot',
+                    data: proc.scrollback(),
+                    backend: proc.backend,
+                    ptyError: proc.ptyError,
+                }),
+                input: (msg) => {
+                    if (msg.type === 'data' && typeof msg.data === 'string') {
+                        proc.write(msg.data);
+                    }
+                    else {
+                        // A viewer/relay sending a wrong-shaped message (field rename,
+                        // numeric data, protocol skew) gets the keystroke silently dropped.
+                        // Log it so the "terminal ignores my input" symptom is diagnosable.
+                        ctx.logger?.debug?.('terminal surface dropped unrecognized input', { type: msg.type });
+                    }
+                },
+                resize: (size) => {
+                    // Validate before touching the PTY: a viewer/relay may send NaN,
+                    // Infinity, floats, negatives, or 0 (SurfaceSize.cols/rows are bare
+                    // `number`s — anything decoded off the wire). `resize` in pty.ts also
+                    // clamps, but reject obviously-bad shapes here with a diagnostic so a
+                    // dropped resize is traceable rather than a silent no-op.
+                    if (isValidDimension(size.cols) && isValidDimension(size.rows)) {
+                        proc.resize(size.cols, size.rows);
+                    }
+                    else {
+                        ctx.logger?.debug?.('terminal surface dropped malformed resize', { size });
+                    }
+                },
+                close: () => {
+                    // Detach this viewer; the underlying shared process stays alive for
+                    // the agent's tool and any other viewer (closed on session teardown).
+                    unsubData();
+                    unsubExit();
+                },
+            };
+        },
+    });
+}
+// --- Tool -------------------------------------------------------------------
+const terminalInputSchema = z.object({
+    command: z
+        .string()
+        .min(1)
+        .max(10_000)
+        .describe('A shell command to run in the user-visible terminal.'),
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .max(600_000)
+        .optional()
+        .describe('Max time to wait for the command to finish (default 30s).'),
+});
+/**
+ * The `terminal` tool runs a command in the SHARED terminal the user sees. It
+ * appends a unique sentinel that echoes the exit code, then reads output until
+ * the sentinel returns — reliable completion detection in an interactive,
+ * input-echoing shell. The command and its output stay visible to the user, who
+ * can take over at any time.
+ */
+export function buildTerminalTool() {
+    return defineTool({
+        name: 'terminal',
+        description: 'Run a shell command in the user-visible terminal and return its output. ' +
+            'The terminal is SHARED with the user — they see what you run and can take over. ' +
+            'Use this to run applications or commands for the user (builds, scripts, CLIs). ' +
+            'For long-running/interactive programs, expect partial output up to the timeout.',
+        inputSchema: terminalInputSchema,
+        // Bash-class honest caps: this drives a real shell (node-pty), so the
+        // command can touch anything the user could. The shared shell deliberately
+        // inherits the FULL runner env (see the SECURITY note in pty.ts); the env
+        // list below is the shell-relevant subset an enforcing isolator should
+        // provide when it re-spawns under a constrained env.
+        isolation: {
+            capabilities: {
+                subprocess: true,
+                fs: { read: ['$cwd/**', '/tmp/**'], write: ['$cwd/**', '/tmp/**'] },
+                net: { mode: 'any' },
+                env: ['PATH', 'HOME', 'USER', 'SHELL', 'COMSPEC', 'LANG', 'LC_ALL', 'TERM'],
+                timeMs: 600_000,
+            },
+        },
+        handler: async (input, ctx) => {
+            const proc = await getSharedTerminal(ctx.cwd ?? process.cwd());
+            const timeoutMs = input.timeoutMs ?? 30_000;
+            // Honor the turn's abort signal: when the loop/user cancels the turn, the
+            // command must stop waiting PROMPTLY rather than blocking the tool slot for
+            // up to the full timeout (600s) on a session that's already being torn down.
+            // We do NOT kill the shared shell (it's user-facing and may host other work)
+            // — we just stop awaiting its sentinel.
+            return runCommand(proc, input.command, makeMarker(), timeoutMs, ctx.signal);
+        },
+    });
+}
+/**
+ * A high-entropy, unpredictable completion marker. The exit code is detected by
+ * matching `<marker> <digits>` on its own line; a time+counter marker was
+ * predictable, so untrusted command output (a printed file, a remote response)
+ * could deliberately emit `<predicted-marker> <chosen-exit>` to spoof an
+ * attacker-chosen exit status and truncate the output. 64 bits of randomness
+ * makes that practically impossible to reproduce.
+ */
+function makeMarker() {
+    return `__MOXXY_DONE_${randomBytes(8).toString('hex')}__`;
+}
+/**
+ * Cap the per-command accumulator. The shared scrollback in pty.ts is bounded,
+ * but THIS accumulator is per-call: a command that floods output before its
+ * sentinel arrives (`cat huge.log`, `yes`, a `tail -f` that never returns until
+ * the 600s timeout) would otherwise grow `acc` unbounded → OOM the runner. The
+ * sentinel is always at the END of the stream, so retaining only the tail keeps
+ * detection correct while making memory O(cap) instead of O(total output).
+ */
+const MAX_ACC = 1_000_000;
+/**
+ * Per-shared-process command serialization. The surface and the tool share ONE
+ * shell per cwd; runCommand writes `command` + a sentinel `printf` and reads the
+ * merged stream until ITS sentinel appears. With no serialization, two
+ * concurrent tool calls (parallel tool calls are normal) — or a tool call
+ * overlapping a user typing in the pane — would interleave their command +
+ * sentinel writes into one line-oriented shell, scrambling output and letting
+ * each `$?` capture the OTHER command's exit. We hold a per-proc tail promise: a
+ * command writes only once the previous one on the same shell has finished, so
+ * writes are single-file. The entry is deleted once the shell goes idle, so the
+ * NEXT command on an idle shell writes synchronously (no microtask hop) —
+ * preserving the single-command happy path exactly (listener + write in the same
+ * tick the caller invokes runCommand). Keyed weakly so a disposed process drops
+ * its tail.
+ */
+const commandTails = new WeakMap();
+/**
+ * Write `command` then a sentinel `printf` to a shared shell and collect output
+ * until the sentinel line appears. Returns the captured output (best-effort
+ * stripped of the echoed sentinel command) + the exit code parsed from it.
+ *
+ * Serialized per shared process: a command writes only once the previous one on
+ * the same shell finishes, so concurrent callers never interleave their writes
+ * on the single stdin and each `$?` reflects its OWN command.
+ */
+export function runCommand(proc, command, marker, timeoutMs, 
+/** Optional turn-abort signal; firing it finishes the command immediately
+ *  (timedOut=false) without waiting for the sentinel or the timeout. */
+signal) {
+    // Idle shell (no pending tail) → write synchronously (undefined). Busy shell →
+    // defer this command's writes until the current tail settles.
+    const startWrites = commandTails.get(proc);
+    const run = runCommandSerialized(proc, command, marker, timeoutMs, startWrites, signal);
+    // This command becomes the new tail; later callers wait on it. Swallow
+    // rejections (it never rejects today) so one failure can't poison the queue.
+    const settled = run.then(() => { }, () => { });
+    commandTails.set(proc, settled);
+    // Once this command settles, if nothing newer queued behind it, the shell is
+    // idle again — drop the entry so the next command writes synchronously.
+    void settled.then(() => {
+        if (commandTails.get(proc) === settled)
+            commandTails.delete(proc);
+    });
+    return run;
+}
+function runCommandSerialized(proc, command, marker, timeoutMs, 
+/** Resolves when it's this command's turn to write; undefined = write now. */
+startWrites, 
+/** Turn-abort signal; firing it finishes immediately (see runCommand). */
+signal) {
+    return new Promise((resolve) => {
+        let acc = '';
+        let settled = false;
+        const finish = (exitCode, timedOut) => {
+            if (settled)
+                return;
+            settled = true;
+            unsubData();
+            unsubExit();
+            clearTimeout(timer);
+            if (onAbort)
+                signal?.removeEventListener('abort', onAbort);
+            resolve({ output: cleanOutput(acc, command, marker), exitCode, timedOut });
+        };
+        // Already aborted before we even start? Finish immediately — don't write to
+        // the shell, don't arm a timeout. The command never runs; null exit.
+        if (signal?.aborted) {
+            // `finish` below isn't fully wired yet (unsubData/unsubExit/timer are
+            // declared after this point), so resolve directly for the pre-armed case.
+            resolve({ output: '', exitCode: null, timedOut: false });
+            return;
+        }
+        // Abort while waiting/running → stop awaiting the sentinel and resolve with a
+        // null exit (the command may have partially run; we report what we captured).
+        // We deliberately do NOT kill the shared shell here — it is user-facing and
+        // may be hosting other work; we only detach this command's reader.
+        const onAbort = () => finish(null, false);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        // Compile the sentinel matcher ONCE — `marker` is fixed for this call. The
+        // sentinel is `<marker> <digits>`; the marker is `__MOXXY_DONE_<hex>__`, so
+        // nothing in it is a regex metacharacter and it needs no escaping. Anchor the
+        // match to a REAL newline — `\n` only, NOT the regex `^` — so command OUTPUT
+        // that merely CONTAINS the literal string (echoing a captured transcript,
+        // grepping a file) cannot false-trigger completion. (`^` is deliberately
+        // excluded: we scan a SLICE of the buffer for O(n) cost, and `^` would match
+        // the slice's first char even when that char is mid-line — a hostile line
+        // like `prefix<marker> 137` whose `<marker>` happens to land at the slice
+        // start would otherwise spoof an attacker-chosen exit code. By requiring a
+        // literal `\n`, a sentinel is only ever recognized when a genuine newline
+        // precedes it in the buffer.) printf always appends a trailing `\n`.
+        const sentinel = new RegExp(`\\n${marker} (\\d+)\\r?\\n`);
+        // Re-scanning the whole accumulated buffer per chunk is O(n^2). The sentinel
+        // appears exactly once (unique marker) and we finish on first match, so it
+        // suffices to scan only the new chunk plus a carry-over of the previous
+        // tail long enough to catch a sentinel split across the chunk boundary:
+        // a leading newline + marker + space + a generous run of digits + trailing
+        // newline.
+        const carry = marker.length + 64;
+        // The shell ALWAYS echoes the command (and our printf) on their own lines, so
+        // a real sentinel is always preceded by a newline IN the buffer — we never
+        // need to treat the very first byte of the stream as a line start. To keep
+        // the `\n`-anchored match correct across the slice boundary, the scan window
+        // is widened by one extra leading char so the newline that precedes a
+        // sentinel can never be sliced away (see `scanStart` below).
+        let scanFrom = 0;
+        const unsubData = proc.onData((d) => {
+            // Begin the scan window just before the bytes that could only now have
+            // completed a sentinel that started in an earlier chunk.
+            let from = Math.max(scanFrom, acc.length - carry, 0);
+            acc += d;
+            // Bound the accumulator: keep only the tail. The sentinel lives at the
+            // end of the stream, so trimming the head never drops it. Shift the scan
+            // index down by the trimmed amount so the carry-window math stays correct.
+            if (acc.length > MAX_ACC) {
+                const removed = acc.length - MAX_ACC;
+                acc = acc.slice(removed);
+                from = Math.max(0, from - removed);
+            }
+            // Scan from one char BEFORE `from` so the newline that precedes a sentinel
+            // straddling the carry boundary is inside the window (the match needs the
+            // leading `\n`). Slicing exactly at `from` could otherwise drop that
+            // newline and miss — or, with a bare `^` anchor, falsely match — the
+            // sentinel. Backing up one char keeps the real preceding newline in scope.
+            const scanStart = Math.max(0, from - 1);
+            // At the TRUE stream start (scanStart === 0) a sentinel may legitimately be
+            // the very first line, with no real newline before it. Prepend a synthetic
+            // `\n` ONLY there so the `\n`-anchored match recognizes it — this never
+            // creates a false mid-stream line start, because it's applied solely when
+            // the slice begins at byte 0 of the whole stream.
+            const hay = scanStart > 0 ? acc.slice(scanStart) : `\n${acc}`;
+            sentinel.lastIndex = 0;
+            const m = sentinel.exec(hay);
+            if (m)
+                finish(Number(m[1]), false);
+            // Everything before this point can never start a future sentinel match.
+            scanFrom = Math.max(0, acc.length - carry);
+        });
+        // If the shared shell dies while this command runs (user types `exit`, the
+        // shell crashes, the process is killed), the sentinel never arrives — finish
+        // immediately with the shell's exit code rather than hanging to the full
+        // timeout (up to 600s) on a known-dead process.
+        const unsubExit = proc.onExit((code) => finish(code, false));
+        let timer;
+        // Two writes to the interactive shell: the command, then the sentinel whose
+        // $? reflects the command's exit. A leading newline before the printf
+        // terminates any dangling/unterminated command line (trailing backslash,
+        // unbalanced quote) so the sentinel is always emitted rather than consumed
+        // as a continuation — otherwise such a command would always time out. On a
+        // non-PTY pipe the shell still runs both sequentially.
+        const writeAndArm = () => {
+            if (settled)
+                return; // shell died (or we were torn down) before our turn
+            // The shell is ALREADY dead at write time (it exited before our turn, or
+            // in the TOCTOU window between getSharedTerminal returning it and now).
+            // `onExit` won't fire again — it already fired and is single-shot — so a
+            // bare write would hang to the full timeout (up to 600s) on a known-dead
+            // process. Finish immediately instead. Reported as timedOut=false / null
+            // exit: the command never actually ran, so there is no real exit status.
+            if (!proc.alive) {
+                finish(null, false);
+                return;
+            }
+            timer = setTimeout(() => finish(null, true), timeoutMs);
+            proc.write(`${command}\n`);
+            proc.write(`\nprintf '%s %s\\n' "${marker}" "$?"\n`);
+        };
+        // Idle shell → write now (keeps the single-command path fully synchronous).
+        // Busy shell → wait our turn; the timeout clock only starts when we write, so
+        // a command queued behind a slow predecessor doesn't burn its budget waiting.
+        if (startWrites)
+            void startWrites.then(writeAndArm);
+        else
+            writeAndArm();
+    });
+}
+/** Strip the echoed command + sentinel lines so the model sees just the output. */
+function cleanOutput(acc, command, marker) {
+    // A multi-line command is echoed by an echo-on PTY one line at a time; none of
+    // those echoed lines equals the full `command`, so match each command line
+    // independently. (Single-line commands are the trivial one-element case.)
+    const commandLines = new Set(command
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0));
+    return acc
+        .split('\n')
+        .filter((line) => !line.includes(marker) &&
+        !commandLines.has(line.trim()) &&
+        !line.includes(`printf '%s %s\\n' "${marker}"`))
+        .join('\n')
+        .trim();
+}
+//# sourceMappingURL=terminal.js.map

package/dist/terminal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.js","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC,EAAwB,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAwB,MAAM,UAAU,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,GAAG,IAAI,GAAG,EAA2B,CAAC;AAClD;;;;;;;GAOG;AACH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoC,CAAC;AAC5D;;;;;;;;;;;;;;GAcG;AACH,IAAI,KAAK,GAAG,CAAC,CAAC;AAEd,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAW,EACX,SAAoD,qBAAqB;IAEzE,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,QAAQ,IAAI,QAAQ,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC;IAChD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,8EAA8E;IAC9E,wEAAwE;IACxE,MAAM,YAAY,GAAG,KAAK,CAAC;IAC3B,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;QAC1B,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,2EAA2E;QAC3E,qEAAqE;QACrE,iEAAiE;QACjE,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE;YACf,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI;gBAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;QAChB,2EAA2E;QAC3E,2EAA2E;QAC3E,sDAAsD;QACtD,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO;YAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC1B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,iBAAiB;IAC/B,6EAA6E;IAC7E,8EAA8E;IAC9E,qEAAqE;IACrE,4BAA4B;IAC5B,KAAK,IAAI,CAAC,CAAC;IACX,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAChD,MAAM,CAAC,KAAK,EAAE,CAAC;IACf,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC;AAED;;qEAEqE;AACrE,SAAS,gBAAgB,CAAC,CAAqB;IAC7C,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED,+EAA+E;AAE/E;yCACyC;AACzC,MAAM,UAAU,oBAAoB;IAClC,OAAO,aAAa,CAAC;QACnB,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,iDAAiD;QAC9D,IAAI,EAAE,KAAK,EAAE,GAAG,EAA4B,EAAE;YAC5C,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA8B,CAAC;YACvD,MAAM,IAAI,GAAG,CAAC,OAAgB,EAAQ,EAAE;gBACtC,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;oBAC1B,IAAI,CAAC;wBACH,EAAE,CAAC,OAAO,CAAC,CAAC;oBACd,CAAC;oBAAC,MAAM,CAAC;wBACP,sEAAsE;oBACxE,CAAC;gBACH,CAAC;YACH,CAAC,CAAC;YACF,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YACtE,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YACtE,0EAA0E;YAC1E,4EAA4E;YAC5E,4EAA4E;YAC5E,IAAI,IAAI,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;gBAC5B,IAAI,CAAC;oBACH,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,IAAI,CAAC,QAAQ;wBACjB,CAAC,CAAC,0DAA0D,IAAI,CAAC,QAAQ,IAAI;wBAC7E,CAAC,CAAC,uEAAuE;iBAC5E,CAAC,CAAC;YACL,CAAC;YACD,OAAO;gBACL,EAAE,EAAE,UAAU;gBACd,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;oBACb,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;oBACjB,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACnC,CAAC;gBACD,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;oBACf,IAAI,EAAE,UAAU;oBAChB,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE;oBACvB,OAAO,EAAE,IAAI,CAAC,OAAO;oBACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;iBACxB,CAAC;gBACF,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE;oBACb,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;wBACxD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBACvB,CAAC;yBAAM,CAAC;wBACN,+DAA+D;wBAC/D,oEAAoE;wBACpE,oEAAoE;wBACpE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,6CAA6C,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;oBACzF,CAAC;gBACH,CAAC;gBACD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;oBACf,iEAAiE;oBACjE,oEAAoE;oBACpE,sEAAsE;oBACtE,sEAAsE;oBACtE,0DAA0D;oBAC1D,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;wBAC/D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAc,EAAE,IAAI,CAAC,IAAc,CAAC,CAAC;oBACxD,CAAC;yBAAM,CAAC;wBACN,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,2CAA2C,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;oBAC7E,CAAC;gBACH,CAAC;gBACD,KAAK,EAAE,GAAG,EAAE;oBACV,oEAAoE;oBACpE,sEAAsE;oBACtE,SAAS,EAAE,CAAC;oBACZ,SAAS,EAAE,CAAC;gBACd,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,+EAA+E;AAE/E,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,MAAM,CAAC;SACX,QAAQ,CAAC,sDAAsD,CAAC;IACnE,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,GAAG,CAAC,OAAO,CAAC;SACZ,QAAQ,EAAE;SACV,QAAQ,CAAC,2DAA2D,CAAC;CACzE,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,CAAC;QAChB,IAAI,EAAE,UAAU;QAChB,WAAW,EACT,0EAA0E;YAC1E,kFAAkF;YAClF,iFAAiF;YACjF,iFAAiF;QACnF,WAAW,EAAE,mBAAmB;QAChC,sEAAsE;QACtE,2EAA2E;QAC3E,0EAA0E;QAC1E,uEAAuE;QACvE,qDAAqD;QACrD,SAAS,EAAE;YACT,YAAY,EAAE;gBACZ,UAAU,EAAE,IAAI;gBAChB,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE;gBACnE,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;gBACpB,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC;gBAC3E,MAAM,EAAE,OAAO;aAChB;SACF;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YAC5B,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,GAAG,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;YAC/D,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,MAAM,CAAC;YAC5C,0EAA0E;YAC1E,4EAA4E;YAC5E,6EAA6E;YAC7E,6EAA6E;YAC7E,wCAAwC;YACxC,OAAO,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC9E,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,UAAU;IACjB,OAAO,gBAAgB,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,GAAG,SAAS,CAAC;AAE1B;;;;;;;;;;;;;;GAcG;AACH,MAAM,YAAY,GAAG,IAAI,OAAO,EAAkC,CAAC;AAEnE;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CACxB,IAAqB,EACrB,OAAe,EACf,MAAc,EACd,SAAiB;AACjB;wEACwE;AACxE,MAAoB;IAEpB,+EAA+E;IAC/E,8DAA8D;IAC9D,MAAM,WAAW,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IACxF,uEAAuE;IACvE,6EAA6E;IAC7E,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CACtB,GAAG,EAAE,GAAE,CAAC,EACR,GAAG,EAAE,GAAE,CAAC,CACT,CAAC;IACF,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAChC,6EAA6E;IAC7E,wEAAwE;IACxE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE;QACrB,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,OAAO;YAAE,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpE,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,oBAAoB,CAC3B,IAAqB,EACrB,OAAe,EACf,MAAc,EACd,SAAiB;AACjB,8EAA8E;AAC9E,WAAsC;AACtC,0EAA0E;AAC1E,MAA+B;IAE/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,CAAC,QAAuB,EAAE,QAAiB,EAAQ,EAAE;YAClE,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,SAAS,EAAE,CAAC;YACZ,SAAS,EAAE,CAAC;YACZ,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,OAAO;gBAAE,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC7E,CAAC,CAAC;QACF,4EAA4E;QAC5E,qEAAqE;QACrE,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,sEAAsE;YACtE,0EAA0E;YAC1E,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;YACzD,OAAO;QACT,CAAC;QACD,8EAA8E;QAC9E,8EAA8E;QAC9E,4EAA4E;QAC5E,mEAAmE;QACnE,MAAM,OAAO,GAAG,GAAS,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAChD,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,2EAA2E;QAC3E,4EAA4E;QAC5E,8EAA8E;QAC9E,6EAA6E;QAC7E,0EAA0E;QAC1E,yEAAyE;QACzE,6EAA6E;QAC7E,0EAA0E;QAC1E,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,qEAAqE;QACrE,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,MAAM,MAAM,gBAAgB,CAAC,CAAC;QAC1D,6EAA6E;QAC7E,2EAA2E;QAC3E,wEAAwE;QACxE,wEAAwE;QACxE,2EAA2E;QAC3E,WAAW;QACX,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC;QACjC,8EAA8E;QAC9E,2EAA2E;QAC3E,2EAA2E;QAC3E,6EAA6E;QAC7E,sEAAsE;QACtE,6DAA6D;QAC7D,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YAClC,uEAAuE;YACvE,yDAAyD;YACzD,IAAI,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;YACrD,GAAG,IAAI,CAAC,CAAC;YACT,uEAAuE;YACvE,yEAAyE;YACzE,2EAA2E;YAC3E,IAAI,GAAG,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;gBACzB,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC;gBACrC,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBACzB,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC;YACrC,CAAC;YACD,2EAA2E;YAC3E,0EAA0E;YAC1E,qEAAqE;YACrE,qEAAqE;YACrE,2EAA2E;YAC3E,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;YACxC,4EAA4E;YAC5E,2EAA2E;YAC3E,wEAAwE;YACxE,0EAA0E;YAC1E,kDAAkD;YAClD,MAAM,GAAG,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YAC9D,QAAQ,CAAC,SAAS,GAAG,CAAC,CAAC;YACvB,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC;gBAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YACnC,wEAAwE;YACxE,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,2EAA2E;QAC3E,6EAA6E;QAC7E,yEAAyE;QACzE,gDAAgD;QAChD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7D,IAAI,KAAgD,CAAC;QACrD,4EAA4E;QAC5E,sEAAsE;QACtE,yEAAyE;QACzE,2EAA2E;QAC3E,2EAA2E;QAC3E,uDAAuD;QACvD,MAAM,WAAW,GAAG,GAAS,EAAE;YAC7B,IAAI,OAAO;gBAAE,OAAO,CAAC,oDAAoD;YACzE,yEAAyE;YACzE,wEAAwE;YACxE,yEAAyE;YACzE,yEAAyE;YACzE,yEAAyE;YACzE,yEAAyE;YACzE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;gBAChB,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBACpB,OAAO;YACT,CAAC;YACD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC;YACxD,IAAI,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;YAC3B,IAAI,CAAC,KAAK,CAAC,wBAAwB,MAAM,UAAU,CAAC,CAAC;QACvD,CAAC,CAAC;QACF,4EAA4E;QAC5E,8EAA8E;QAC9E,8EAA8E;QAC9E,IAAI,WAAW;YAAE,KAAK,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;;YAC/C,WAAW,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,mFAAmF;AACnF,SAAS,WAAW,CAAC,GAAW,EAAE,OAAe,EAAE,MAAc;IAC/D,+EAA+E;IAC/E,2EAA2E;IAC3E,0EAA0E;IAC1E,MAAM,YAAY,GAAG,IAAI,GAAG,CAC1B,OAAO;SACJ,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAC/B,CAAC;IACF,OAAO,GAAG;SACP,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CACL,CAAC,IAAI,EAAE,EAAE,CACP,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QACtB,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC9B,CAAC,IAAI,CAAC,QAAQ,CAAC,sBAAsB,MAAM,GAAG,CAAC,CAClD;SACA,IAAI,CAAC,IAAI,CAAC;SACV,IAAI,EAAE,CAAC;AACZ,CAAC"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@moxxy/plugin-terminal",
+  "version": "0.27.0",
+  "description": "A shared terminal surface for moxxy: an embedded PTY the user and the agent drive together (the `terminal` tool runs commands; the desktop renders the live session).",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "terminal",
+    "pty",
+    "tools"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-terminal"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@moxxy/sdk": "0.27.0"
+  },
+  "peerDependencies": {
+    "node-pty": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "node-pty": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it, vi } from 'vitest';
+import { terminalPlugin } from './index.js';
+import { buildTerminalSurface, closeAllTerminals, getSharedTerminal } from './terminal.js';
+import type { TerminalProcess } from './pty.js';
+
+describe('plugin-terminal', () => {
+  it('contributes a terminal surface and a terminal tool', () => {
+    expect(terminalPlugin.surfaces?.map((s) => s.kind)).toContain('terminal');
+    expect(terminalPlugin.tools?.map((t) => t.name)).toContain('terminal');
+  });
+
+  it('terminal tool validates its input schema', () => {
+    const tool = terminalPlugin.tools?.find((t) => t.name === 'terminal');
+    expect(tool).toBeDefined();
+    // A command is required; an empty object is rejected.
+    expect(tool!.inputSchema.safeParse({ command: 'ls -la' }).success).toBe(true);
+    expect(tool!.inputSchema.safeParse({}).success).toBe(false);
+    // timeoutMs is bounded.
+    expect(tool!.inputSchema.safeParse({ command: 'x', timeoutMs: 5000 }).success).toBe(true);
+    expect(tool!.inputSchema.safeParse({ command: 'x', timeoutMs: -1 }).success).toBe(false);
+  });
+
+  it('getSharedTerminal does not spawn a duplicate PTY under a concurrent create', async () => {
+    let spawns = 0;
+    // A factory that yields the event loop before resolving — reproducing the
+    // create race where two callers both miss the map before either set()s.
+    const create = vi.fn(async (): Promise<TerminalProcess> => {
+      spawns++;
+      await Promise.resolve();
+      const proc: TerminalProcess = {
+        backend: 'pipe',
+        onData: () => () => {},
+        onExit: () => () => {},
+        scrollback: () => '',
+        write: () => {},
+        resize: () => {},
+        kill: () => {},
+        alive: true,
+      };
+      return proc;
+    });
+
+    const cwd = `/tmp/race-${Math.random()}`;
+    const [a, b] = await Promise.all([
+      getSharedTerminal(cwd, create),
+      getSharedTerminal(cwd, create),
+    ]);
+
+    expect(a).toBe(b);
+    expect(spawns).toBe(1);
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+
+  // MEDIUM: a create in flight when closeAllTerminals runs must NOT strand a
+  // live shell — the create continuation kills it instead of storing an orphan.
+  it('kills a shell whose create resolves after closeAllTerminals', async () => {
+    let release!: () => void;
+    const gate = new Promise<void>((r) => {
+      release = r;
+    });
+    let killed = false;
+    const create = async (): Promise<TerminalProcess> => {
+      await gate; // hold the create open across the shutdown
+      return {
+        backend: 'pipe',
+        ptyError: null,
+        onData: () => () => {},
+        onExit: () => () => {},
+        scrollback: () => '',
+        write: () => {},
+        resize: () => {},
+        kill: () => {
+          killed = true;
+        },
+        alive: true,
+      };
+    };
+
+    const cwd = `/tmp/shutdown-${Math.random()}`;
+    const p = getSharedTerminal(cwd, create); // create is now in flight
+    closeAllTerminals(); // shutdown lands before the create resolves
+    release(); // create finally resolves
+    const proc = await p;
+
+    expect(killed).toBe(true);
+    expect(proc.kill).toBeDefined();
+  });
+
+  // u112-5: the surface's viewer fan-out must isolate a throwing viewer so it
+  // does not abort delivery to the other viewers (matches pty.ts emitData).
+  it('surface emit() isolates a throwing viewer from the others', async () => {
+    // Capture the data callback the surface registers on the shared process so
+    // the test can drive a frame through the real emit() loop.
+    let pushData: ((d: string) => void) | undefined;
+    const create = async (): Promise<TerminalProcess> => ({
+      backend: 'pipe',
+      onData: (cb) => {
+        pushData = cb;
+        return () => {};
+      },
+      onExit: () => () => {},
+      scrollback: () => '',
+      write: () => {},
+      resize: () => {},
+      kill: () => {},
+      alive: true,
+    });
+
+    const cwd = `/tmp/emit-${Math.random()}`;
+    // Pre-seed the shared map so the surface's getSharedTerminal(ctx.cwd) reuses
+    // this fake (no real PTY spawn).
+    await getSharedTerminal(cwd, create);
+
+    const surface = buildTerminalSurface();
+    const instance = await surface.open({ cwd });
+
+    const second = vi.fn();
+    instance.onData(() => {
+      throw new Error('bad viewer');
+    });
+    instance.onData(second);
+
+    // Drive a frame; the shared process relays it through the surface's emit().
+    expect(() => pushData?.('hello')).not.toThrow();
+    expect(second).toHaveBeenCalledWith({ type: 'data', data: 'hello' });
+  });
+});