@myagentroam/node 0.13.1 → 0.13.3

package/dist/connector.js

@@ -1677,6 +1677,7 @@ export class NodeConnector {
         this.capabilities = await this.conversationHosting.project(this.capabilities);
         this.computerUseEnablement.initialize();
         this.directTransferService ??= await this.createDirectTransferService();
+        await this.terminalManager.warmup();
         this.connectionLifecycle.start();
         this.controlChannel.connect();
     }

package/dist/marctl/package.json

@@ -1 +1 @@
-{"type":"module","version":"0.13.1"}
+{"type":"module","version":"0.13.3"}

package/dist/runner/mar-agent/hosted-conversation-runtime.js

@@ -84,28 +84,34 @@ export class MarAgentHostedConversationRuntime {
             let cursor = input.cursor === undefined
                 ? undefined
                 : decodeHostedHistoryCursor(input.cursor, input.sessionId);
-            let entries = [];
-            let turns = projectMarAgentHistory(historySession(input), entries);
+            const pages = [];
+            const turnIds = new Set();
             do {
                 const page = await catalog.history(input.sessionId, {
                     limit: Math.min(1000, Math.max(100, limit * 20)),
                     ...(cursor === undefined ? {} : { cursor })
                 });
-                entries = [...page.entries, ...entries];
+                pages.push(page.entries);
+                for (const entry of page.entries) {
+                    const turnId = historyEntryTurnId(entry);
+                    if (turnId !== undefined)
+                        turnIds.add(turnId);
+                }
                 cursor = page.nextCursor;
-                turns = projectMarAgentHistory(historySession(input), entries);
-            } while (cursor !== undefined && turns.length <= limit);
+            } while (cursor !== undefined && turnIds.size <= limit);
+            // Pages arrive newest-first. Materialize and normalize their history only once.
+            const entries = pages.reverse().flat();
+            const turns = projectMarAgentHistory(historySession(input), entries, {
+                registerInputImages: (entry) => this.#registerInputImages(input, entry),
+                registerGeneratedImages: (sessionId, images) => this.#registerGeneratedImages(input, sessionId, images)
+            });
             const selected = turns.slice(-limit);
             const earliestTurnId = selected[0]?.id;
             const earliestSequence = earliestTurnId === undefined
                 ? undefined
                 : entries.find((entry) => historyEntryTurnId(entry) === earliestTurnId)?.sequence;
-            const projected = projectMarAgentHistory(historySession(input), entries, {
-                registerInputImages: (entry) => this.#registerInputImages(input, entry),
-                registerGeneratedImages: (sessionId, images) => this.#registerGeneratedImages(input, sessionId, images)
-            }).slice(-limit);
             return {
-                turns: projected,
+                turns: selected,
                 nextCursor: turns.length > selected.length && earliestSequence !== undefined
                     ? encodeHostedHistoryCursor(input.sessionId, earliestSequence)
                     : null

package/dist/terminal-pty-host.mjs

@@ -0,0 +1,103 @@
+import { spawn } from 'node-pty';
+import { writeSync } from 'node:fs';
+import { terminatePtyTree } from './terminal-pty-tree.mjs';
+
+/** Owns exactly one native PTY. No replay, attachment or Node service state belongs here. */
+let pty;
+let finishing = false;
+let stopping = false;
+let orphaning = false;
+const pipeWait = new Int32Array(new SharedArrayBuffer(4));
+
+function output(data) {
+  if (orphaning) return;
+  const bytes = Buffer.from(data);
+  let offset = 0;
+  // Kernel backpressure blocks only this isolated host, not the main Node. Unlike
+  // async stdout.write, it cannot accumulate an unbounded queue or run PTY exit
+  // timers while output is paused. Interactive writes normally finish immediately.
+  while (offset < bytes.length) {
+    try {
+      offset += writeSync(1, bytes, offset, bytes.length - offset);
+    } catch (error) {
+      if (error.code === 'EAGAIN' || error.code === 'EWOULDBLOCK') Atomics.wait(pipeWait, 0, 0, 1);
+      else {
+        orphaned();
+        return;
+      }
+    }
+  }
+}
+
+function send(message, complete = () => {}) {
+  if (process.connected) process.send(message, complete);
+  else complete();
+}
+
+function finish(event) {
+  if (finishing || orphaning) return;
+  finishing = true;
+  // Explicit exit also releases native addon threads/handles after normal PTY cleanup.
+  // Synchronous output is already flushed; parent close joins the pipe before exit.
+  send({ type: 'exit', event }, () => process.exit(0));
+}
+
+function stop() {
+  if (stopping || finishing) return;
+  stopping = true;
+  // The parent has its own deadline even if a native kill blocks this event loop.
+  try {
+    if (pty === undefined) finish({ exitCode: 127 });
+    else pty.kill();
+  } catch {
+    send({ type: 'error', code: 'TERMINAL_PTY_HOST_FAILED' });
+    // Parent force-close owns final process-tree recovery.
+  }
+}
+
+function orphaned() {
+  if (finishing || orphaning) return;
+  orphaning = true;
+  stopping = true;
+  // No synchronous addon call here: there is no parent left to enforce its deadline.
+  void terminatePtyTree(pty?.pid).then(
+    () => process.exit(0),
+    () => process.exit(1)
+  );
+}
+
+process.on('disconnect', orphaned);
+process.on('SIGTERM', orphaned);
+process.on('SIGINT', orphaned);
+process.on('message', (message) => {
+  if (finishing || orphaning) return;
+  try {
+    switch (message.type) {
+      case 'start':
+        pty = spawn(message.shell, message.args, message.options);
+        // Keep draining native output, including its final chunks. Network backpressure
+        // belongs to the main Node's existing bounded relay, not this local pipe.
+        pty.onData(output);
+        pty.onExit(finish);
+        send({ type: 'started', pid: pty.pid });
+        break;
+      case 'input':
+        if (!stopping) pty.write(message.data);
+        break;
+      case 'resize':
+        if (!stopping) pty.resize(message.cols, message.rows);
+        break;
+      case 'kill':
+        stop();
+        break;
+    }
+  } catch {
+    send({
+      type: 'error',
+      code: message.type === 'start' ? 'TERMINAL_PTY_START_FAILED' : 'TERMINAL_PTY_HOST_FAILED'
+    });
+    if (pty === undefined) finish({ exitCode: 127 });
+    else stop();
+  }
+});
+send({ type: 'ready' });

package/dist/terminal-pty-pool.js

@@ -0,0 +1,50 @@
+import { TerminalPtyProcess } from './terminal-pty.js';
+/** Owns one warm, unassigned host. Active hosts transfer to TerminalManager's proxies. */
+export class TerminalPtyPool {
+    standby;
+    refillTimer;
+    closing;
+    warmup() {
+        this.refill();
+        if (this.standby === undefined)
+            return Promise.reject(new Error('TERMINAL_PTY_CLOSED'));
+        return this.standby.ready;
+    }
+    open(shell, args, options) {
+        if (this.closing !== undefined)
+            throw new Error('TERMINAL_PTY_CLOSED');
+        clearTimeout(this.refillTimer);
+        const host = this.standby ?? new TerminalPtyProcess();
+        // A rejected handoff remains owned here until its physical close settles.
+        this.standby = host;
+        const active = host.start(shell, args, options);
+        this.standby = undefined;
+        // Handoff changes ownership; ending an active host must never refill the pool.
+        this.refill();
+        return active;
+    }
+    close() {
+        if (this.closing !== undefined)
+            return this.closing;
+        clearTimeout(this.refillTimer);
+        const host = this.standby;
+        this.standby = undefined;
+        this.closing = host?.closed ?? Promise.resolve();
+        host?.kill();
+        return this.closing;
+    }
+    refill() {
+        if (this.closing !== undefined || this.standby !== undefined)
+            return;
+        const host = new TerminalPtyProcess();
+        this.standby = host;
+        const ended = () => {
+            if (this.standby !== host)
+                return;
+            this.standby = undefined;
+            // Avoid a hot spawn loop when the runtime or native installation is broken.
+            this.refillTimer = setTimeout(() => this.refill(), 1_000);
+        };
+        void host.closed.then(ended, ended);
+    }
+}

package/dist/terminal-pty-tree.mjs

@@ -0,0 +1,49 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execute = promisify(execFile);
+
+/** Reaps the native PTY tree without entering the potentially blocked addon. */
+export async function terminatePtyTree(pid) {
+  if (pid === undefined) return;
+  if (process.platform === 'win32') {
+    try {
+      await execute('taskkill', ['/pid', String(pid), '/T', '/F'], {
+        windowsHide: true,
+        timeout: 2_000
+      });
+    } catch (error) {
+      try {
+        process.kill(pid, 0);
+      } catch (probe) {
+        if (probe.code === 'ESRCH') return;
+        throw probe;
+      }
+      throw error;
+    }
+    return;
+  }
+  // Foreground jobs can have a different group from their shell, on both POSIX platforms.
+  const { stdout } = await execute('ps', ['-A', '-o', 'pid=,ppid='], { timeout: 1_000 });
+  const rows = stdout
+    .trim()
+    .split('\n')
+    .map((line) => line.trim().split(/\s+/u).map(Number));
+  const tree = [pid];
+  const seen = new Set(tree);
+  for (let index = 0; index < tree.length; index++) {
+    for (const [child, parent] of rows) {
+      if (parent === tree[index] && !seen.has(child)) {
+        tree.push(child);
+        seen.add(child);
+      }
+    }
+  }
+  for (const target of tree.reverse()) {
+    try {
+      process.kill(target, 'SIGKILL');
+    } catch (error) {
+      if (error.code !== 'ESRCH') throw error;
+    }
+  }
+}

package/dist/terminal-pty.js

@@ -0,0 +1,278 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { terminatePtyTree } from './terminal-pty-tree.mjs';
+const CLOSE_TIMEOUT_MS = 2_000;
+const START_TIMEOUT_MS = 10_000;
+const MAX_PENDING_INPUT_BYTES = 1024 * 1024;
+/** Owns one PTY host and its IPC, not terminal state, attachments or replay. */
+export class TerminalPtyProcess {
+    pid;
+    closed;
+    ready;
+    child;
+    dataListeners = new Set();
+    exitListeners = new Set();
+    errorListeners = new Set();
+    closeFailures = [];
+    closing = false;
+    closeTimer;
+    startTimer;
+    nativePid;
+    exit;
+    failure;
+    pendingInputBytes = 0;
+    started = false;
+    forcing = false;
+    nativeCleanup;
+    rejectReadiness;
+    constructor(child = spawn(process.execPath, [fileURLToPath(new URL('./terminal-pty-host.mjs', import.meta.url))], {
+        stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+        windowsHide: true
+    })) {
+        this.child = child;
+        this.pid = child.pid;
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (data) => {
+            for (const listener of this.dataListeners)
+                listener(data);
+        });
+        // Native diagnostics must not block the host or expose its spawn environment.
+        child.stderr.resume();
+        let resolveReady;
+        this.ready = new Promise((resolve, reject) => {
+            resolveReady = resolve;
+            this.rejectReadiness = reject;
+        });
+        // A standby can be closed without a caller waiting for warmup.
+        void this.ready.catch(() => undefined);
+        child.on('message', (message) => {
+            if (message.type === 'ready') {
+                if (this.closing || this.failure !== undefined)
+                    return;
+                if (!this.started)
+                    clearTimeout(this.startTimer);
+                resolveReady();
+                this.rejectReadiness = undefined;
+            }
+            if (message.type === 'started') {
+                this.nativePid = message.pid;
+                clearTimeout(this.startTimer);
+            }
+            if (message.type === 'exit') {
+                this.exit = message.event;
+                // The native process is reaped; never signal this PID after it can be reused.
+                this.nativePid = undefined;
+            }
+            else if (message.type === 'error') {
+                this.reportError(message.code);
+                this.kill();
+            }
+        });
+        child.on('error', () => {
+            this.reportError('TERMINAL_PTY_HOST_FAILED');
+            this.kill();
+        });
+        this.closed = new Promise((resolve, reject) => {
+            // Unlike exit, close also joins stdout: no terminal exit can overtake tail output.
+            child.once('close', async (code, signal) => {
+                clearTimeout(this.closeTimer);
+                clearTimeout(this.startTimer);
+                this.closeTimer = undefined;
+                this.startTimer = undefined;
+                this.child = undefined;
+                const abnormal = this.exit === undefined || code !== 0 || signal !== null;
+                const unexpected = abnormal && !this.forcing;
+                let cleanupFailed = false;
+                if (abnormal || this.nativeCleanup !== undefined) {
+                    // A crashed host cannot run its disconnect cleanup; finish its native lease here.
+                    try {
+                        await this.reapNative();
+                    }
+                    catch (error) {
+                        cleanupFailed = true;
+                        this.closeFailures.push(error);
+                    }
+                }
+                this.failReadiness(this.failure ?? 'TERMINAL_PTY_HOST_FAILED');
+                try {
+                    if (unexpected || cleanupFailed)
+                        this.reportError('TERMINAL_PTY_HOST_FAILED');
+                    const event = unexpected || this.failure !== undefined
+                        ? { exitCode: 127 }
+                        : (this.exit ?? { exitCode: 127 });
+                    for (const listener of this.exitListeners) {
+                        try {
+                            listener(event);
+                        }
+                        catch (error) {
+                            this.closeFailures.push(error);
+                        }
+                    }
+                }
+                finally {
+                    this.dataListeners.clear();
+                    this.exitListeners.clear();
+                    this.errorListeners.clear();
+                    child.removeAllListeners();
+                    child.stdout.removeAllListeners();
+                    this.nativeCleanup = undefined;
+                    const failures = this.closeFailures.splice(0);
+                    if (failures.length === 0)
+                        resolve();
+                    else {
+                        const error = failures.length === 1
+                            ? failures[0]
+                            : new AggregateError(failures, 'TERMINAL_PTY_CLOSE_FAILED');
+                        for (const failure of [...failures, error]) {
+                            if (failure instanceof Error) {
+                                try {
+                                    void failure.stack;
+                                }
+                                catch {
+                                    /* Formatters must not prevent cleanup settlement. */
+                                }
+                            }
+                        }
+                        reject(error);
+                    }
+                }
+            });
+        });
+        // Natural exit reports cleanup failures through onError even without a join caller.
+        void this.closed.catch(() => undefined);
+        this.watchStartup();
+    }
+    start(shell, args, options) {
+        if (this.started || this.closing || this.child === undefined)
+            throw new Error('TERMINAL_PTY_CLOSED');
+        this.started = true;
+        this.watchStartup();
+        // Private IPC keeps command arguments and secret environment values out of argv.
+        this.send({ type: 'start', shell, args, options });
+        return this;
+    }
+    write(data) {
+        const bytes = Buffer.byteLength(data);
+        if (this.pendingInputBytes + bytes > MAX_PENDING_INPUT_BYTES)
+            throw new Error('TERMINAL_BACKPRESSURE');
+        this.pendingInputBytes += bytes;
+        try {
+            this.send({ type: 'input', data }, () => {
+                this.pendingInputBytes -= bytes;
+            });
+        }
+        catch (error) {
+            this.pendingInputBytes -= bytes;
+            throw error;
+        }
+    }
+    resize(cols, rows) {
+        this.send({ type: 'resize', cols, rows });
+    }
+    kill() {
+        if (this.child === undefined)
+            return false;
+        if (this.closing)
+            return true;
+        this.closing = true;
+        this.closeTimer = setTimeout(() => {
+            void this.forceClose();
+        }, CLOSE_TIMEOUT_MS);
+        this.send({ type: 'kill' });
+        return true;
+    }
+    onData(listener) {
+        this.dataListeners.add(listener);
+        return {
+            dispose: () => {
+                this.dataListeners.delete(listener);
+            }
+        };
+    }
+    onExit(listener) {
+        this.exitListeners.add(listener);
+        return {
+            dispose: () => {
+                this.exitListeners.delete(listener);
+            }
+        };
+    }
+    onError(listener) {
+        this.errorListeners.add(listener);
+        return {
+            dispose: () => {
+                this.errorListeners.delete(listener);
+            }
+        };
+    }
+    send(message, complete) {
+        const child = this.child;
+        if (child === undefined)
+            throw new Error('TERMINAL_PTY_CLOSED');
+        if (!child.connected) {
+            complete?.();
+            return;
+        }
+        child.send(message, (error) => {
+            complete?.();
+            if (error !== null && !this.closing) {
+                this.reportError('TERMINAL_PTY_HOST_FAILED');
+                this.kill();
+            }
+        });
+    }
+    reportError(code) {
+        if (this.failure !== undefined)
+            return;
+        this.failure = code;
+        for (const listener of this.errorListeners) {
+            try {
+                listener(code);
+            }
+            catch (error) {
+                this.closeFailures.push(error);
+            }
+        }
+    }
+    watchStartup() {
+        clearTimeout(this.startTimer);
+        this.startTimer = setTimeout(() => {
+            this.failReadiness('TERMINAL_PTY_START_FAILED');
+            this.reportError('TERMINAL_PTY_START_FAILED');
+            this.kill();
+        }, START_TIMEOUT_MS);
+    }
+    failReadiness(code) {
+        if (this.rejectReadiness === undefined)
+            return;
+        const error = new Error(code);
+        try {
+            void error.stack;
+        }
+        catch {
+            /* Keep the original startup error even if a custom formatter fails. */
+        }
+        this.rejectReadiness(error);
+        this.rejectReadiness = undefined;
+    }
+    reapNative(root = this.nativePid) {
+        return (this.nativeCleanup ??= terminatePtyTree(root));
+    }
+    async forceClose() {
+        const child = this.child;
+        if (child === undefined)
+            return;
+        this.forcing = true;
+        try {
+            await this.reapNative(this.nativePid ?? child.pid);
+        }
+        catch {
+            if (this.child === child)
+                this.reportError('TERMINAL_PTY_HOST_FAILED');
+        }
+        finally {
+            if (this.child === child)
+                child.kill('SIGKILL');
+        }
+    }
+}

package/dist/terminal.js

@@ -4,10 +4,13 @@ import { chmodSync, existsSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { spawn } from 'node-pty';
 import { terminalDataFrameSchema } from '@myagentroam/protocol';
 import { nodeExecutionEnvironment } from './node-execution-environment.js';
+import { nodeLog } from './operational.js';
 import { terminateProcessTree } from './process-tree.js';
+import { TerminalPtyProcess } from './terminal-pty.js';
+import { TerminalPtyPool } from './terminal-pty-pool.js';
+import { safeErrorCode } from './util/safe-error.js';
 const MAX_FRAME_CHARACTERS = 65_536;
 const TERMINAL_COMMAND_MAX_BYTES = 64 * 1024;
 const DEFAULT_MAX_TERMINALS = 10;
@@ -15,7 +18,10 @@ const DEFAULT_MAX_TERMINALS_PER_WORKSPACE = 5;
 const DEFAULT_MAX_REPLAY_BYTES = 512 * 1024;
 const DEFAULT_IDLE_TIMEOUT_MS = 60 * 60_000;
 /**
- * Owns Node-local PTY/ConPTY processes and their bounded output replay.
+ * Owns terminal state, attachments and bounded output replay. PTY proxies own their
+ * isolated hosts; binary pipes keep their separate lifecycle. Native PTY details
+ * belong only to the host, never to this service or its browser relay callers.
+ * The owned standby pool activates at warmup and transfers each host to its proxy.
  * Browser relay transport intentionally lives outside this class: callers pass
  * only schema-validated TerminalDataFrame values after Server authorization.
  */
@@ -29,6 +35,8 @@ export class TerminalManager {
     idleTimeoutMs;
     now;
     ptyFactory;
+    ptyPool;
+    pooledPty;
     pipeFactory;
     terminate;
     terminals = new Map();
@@ -65,11 +73,26 @@ export class TerminalManager {
             throw new Error('TERMINAL_CONFIG_INVALID');
         }
         this.now = options.now ?? Date.now;
-        this.ptyFactory = options.ptyFactory ?? nodePtyFactory;
+        this.pooledPty = options.ptyFactory === undefined;
+        this.ptyFactory =
+            options.ptyFactory ??
+                ((shell, args, spawnOptions) => this.requirePtyPool().open(shell, args, spawnOptions));
         this.pipeFactory = options.pipeFactory ?? nodePipeFactory;
         this.terminate =
             options.terminate ?? ((child, platform) => terminateProcessTree(child, platform));
-        this.idleTimer = setInterval(() => void this.closeExpired(), Math.min(this.idleTimeoutMs, 60_000));
+        this.idleTimer = setInterval(() => {
+            void this.closeExpired().catch((error) => {
+                try {
+                    nodeLog('terminal.cleanup.failed', {
+                        source: 'idle',
+                        errorCode: safeErrorCode(error, 'TERMINAL_CLEANUP_FAILED')
+                    });
+                }
+                catch {
+                    // Logging must not turn a handled background failure into another rejection.
+                }
+            });
+        }, Math.min(this.idleTimeoutMs, 60_000));
         this.idleTimer.unref();
     }
     availableProfiles() {
@@ -113,8 +136,7 @@ export class TerminalManager {
             else {
                 const pty = this.ptyFactory(deferred.shell, deferred.args, deferred.options);
                 terminal.pty = pty;
-                pty.onData((data) => this.recordOutput(terminal, data));
-                pty.onExit((event) => this.exited(terminal, event.exitCode));
+                this.listenToPty(terminal, pty);
             }
         }
         catch {
@@ -160,6 +182,7 @@ export class TerminalManager {
             profile,
             pty,
             pipe: undefined,
+            subscriptions: [],
             binary,
             ...(commandArgs === undefined
                 ? {}
@@ -178,8 +201,8 @@ export class TerminalManager {
             detachedAt: createdAt
         };
         this.terminals.set(terminal.id, terminal);
-        pty?.onData((data) => this.recordOutput(terminal, data));
-        pty?.onExit((event) => this.exited(terminal, event.exitCode));
+        if (pty !== undefined)
+            this.listenToPty(terminal, pty);
         return this.notifySummary(terminal);
     }
     list() {
@@ -327,8 +350,7 @@ export class TerminalManager {
         });
         this.closing.set(terminalId, closing);
         void (async () => {
-            this.detachAll(terminal);
-            const summary = this.notifySummary(terminal);
+            const { summary, failures } = this.detachAndNotify(terminal);
             try {
                 if (terminal.pty !== undefined) {
                     // Native PTY hangup reaches POSIX foreground jobs in a separate process group
@@ -337,15 +359,31 @@ export class TerminalManager {
                         terminal.pty.kill();
                     }
                     catch {
-                        await this.terminate(terminal.pty, this.platform);
+                        try {
+                            await this.terminate(terminal.pty, this.platform);
+                        }
+                        catch (error) {
+                            failures.push(error);
+                        }
                     }
+                    await terminal.pty.closed;
                 }
                 if (terminal.pipe !== undefined)
                     await this.terminate(terminal.pipe, this.platform);
             }
+            catch (error) {
+                failures.push(error);
+            }
             finally {
-                this.emit({ type: 'exit', terminalId: terminal.id, exitCode: terminal.exitCode });
+                this.releaseTerminalResources(terminal);
+                try {
+                    this.emit({ type: 'exit', terminalId: terminal.id, exitCode: terminal.exitCode });
+                }
+                catch (error) {
+                    failures.push(error);
+                }
             }
+            this.throwCleanupFailures(failures);
             return summary;
         })().then((summary) => {
             this.closing.delete(terminalId);
@@ -358,15 +396,30 @@ export class TerminalManager {
     }
     /** Ends current terminals without disposing the manager's idle collection. */
     async closeAll() {
-        await Promise.all([...this.terminals.values()]
+        const results = await Promise.allSettled([...this.terminals.values()]
             .filter((terminal) => terminal.state === 'RUNNING' || this.closing.has(terminal.id))
             .map((terminal) => this.close(terminal.id)));
+        this.throwCleanupFailures(results.flatMap((result) => (result.status === 'rejected' ? [result.reason] : [])));
+    }
+    /** Activates the standby only at Node startup, never during connector composition. */
+    warmup() {
+        return this.pooledPty ? this.requirePtyPool().warmup() : Promise.resolve();
+    }
+    requirePtyPool() {
+        repairPtySpawnHelper();
+        return (this.ptyPool ??= new TerminalPtyPool());
     }
     async shutdown() {
         if (this.idleTimer !== undefined)
             clearInterval(this.idleTimer);
         this.idleTimer = undefined;
-        await this.closeAll();
+        const pool = this.ptyPool;
+        const standbyDrain = pool?.close();
+        const results = await Promise.allSettled([this.closeAll(), standbyDrain]);
+        // Concurrent shutdown callers must keep joining the same owned standby.
+        if (this.ptyPool === pool)
+            this.ptyPool = undefined;
+        this.throwCleanupFailures(results.flatMap((result) => (result.status === 'rejected' ? [result.reason] : [])));
     }
     onFrame(listener) {
         this.frameListeners.add(listener);
@@ -461,9 +514,117 @@ export class TerminalManager {
         terminal.state = 'EXITED';
         terminal.exitCode = exitCode;
         terminal.updatedAt = this.now();
-        this.detachAll(terminal);
-        this.notifySummary(terminal);
-        this.emit({ type: 'exit', terminalId: terminal.id, exitCode });
+        const { failures } = this.detachAndNotify(terminal);
+        try {
+            this.releaseTerminalResources(terminal);
+            this.emit({ type: 'exit', terminalId: terminal.id, exitCode });
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        this.throwCleanupFailures(failures);
+    }
+    throwCleanupFailures(failures) {
+        if (failures.length === 0)
+            return;
+        const failure = failures.length === 1
+            ? failures[0]
+            : new AggregateError(failures, 'Terminal cleanup did not complete.');
+        const pending = [failure];
+        const seen = new Set();
+        while (pending.length > 0) {
+            const error = pending.pop();
+            if (seen.has(error))
+                continue;
+            seen.add(error);
+            try {
+                if (!(error instanceof Error))
+                    continue;
+                try {
+                    // Lazy V8 stacks can retain native receivers even after all subscriptions are disposed.
+                    void error.stack;
+                }
+                catch {
+                    // A custom stack formatter must not replace the original cleanup failure.
+                }
+                pending.push(error.cause);
+                if (error instanceof AggregateError && Array.isArray(error.errors)) {
+                    for (const nested of error.errors)
+                        pending.push(nested);
+                }
+            }
+            catch {
+                // Preserve errors with custom cause/errors accessors without masking the original failure.
+            }
+        }
+        throw failure;
+    }
+    detachAndNotify(terminal) {
+        const failures = [];
+        let summary = this.summary(terminal);
+        try {
+            this.detachAll(terminal);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            summary = this.notifySummary(terminal);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        return { summary, failures };
+    }
+    listenToPty(terminal, pty) {
+        const track = (subscription) => {
+            if (terminal.state === 'RUNNING')
+                terminal.subscriptions.push(subscription);
+            else
+                this.disposeSubscription(terminal, subscription);
+        };
+        track(pty.onData((data) => this.recordOutput(terminal, data)));
+        if (pty.onError !== undefined)
+            track(pty.onError((code) => this.emit({ type: 'error', terminalId: terminal.id, code })));
+        if (terminal.state !== 'RUNNING')
+            return;
+        let subscribing = true;
+        let failure;
+        const subscription = pty.onExit((event) => {
+            try {
+                this.exited(terminal, event.exitCode);
+            }
+            catch (error) {
+                if (!subscribing)
+                    throw error;
+                failure = { error };
+            }
+        });
+        subscribing = false;
+        track(subscription);
+        if (failure !== undefined)
+            throw failure.error;
+    }
+    disposeSubscription(terminal, subscription) {
+        try {
+            subscription.dispose();
+        }
+        catch {
+            try {
+                this.emit({ type: 'error', terminalId: terminal.id, code: 'TERMINAL_CLEANUP_FAILED' });
+            }
+            catch {
+                // A failing error observer must not prevent the remaining resources from being released.
+            }
+        }
+    }
+    releaseTerminalResources(terminal) {
+        // Historical summaries and replay must not keep native handles or spawn environments alive.
+        terminal.pty = undefined;
+        terminal.pipe = undefined;
+        delete terminal.deferredCommand;
+        for (const subscription of terminal.subscriptions.splice(0))
+            this.disposeSubscription(terminal, subscription);
     }
     replayFrames(terminal, afterSequence) {
         const first = terminal.replay[0]?.sequence;
@@ -526,7 +687,18 @@ export class TerminalManager {
             .sort((left, right) => left.lastUsedAt - right.lastUsedAt || left.createdAt - right.createdAt)[0];
         if (candidate === undefined)
             throw new Error('TERMINAL_LIMIT_REACHED');
-        void this.close(candidate.id);
+        void this.close(candidate.id).catch((error) => {
+            try {
+                nodeLog('terminal.cleanup.failed', {
+                    source: 'capacity',
+                    terminalId: candidate.id,
+                    errorCode: safeErrorCode(error, 'TERMINAL_CLEANUP_FAILED')
+                });
+            }
+            catch {
+                // Logging must not turn a handled background failure into another rejection.
+            }
+        });
     }
     runningCountForWorkspace(workspaceId) {
         return [...this.terminals.values()].filter((terminal) => terminal.state === 'RUNNING' && terminal.workspaceId === workspaceId).length;
@@ -551,14 +723,7 @@ export class TerminalManager {
 }
 export function nodePtyFactory(shell, args, options) {
     repairPtySpawnHelper();
-    const pty = spawn(shell, [...args], {
-        name: options.name,
-        cols: options.cols,
-        rows: options.rows,
-        cwd: options.cwd,
-        env: options.env
-    });
-    return pty;
+    return new TerminalPtyProcess().start(shell, args, options);
 }
 export function repairPtySpawnHelper(platform = process.platform, architecture = process.arch, packageRoot) {
     if (platform !== 'darwin')

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
   "files": [
     "dist/**/*.js",
+    "dist/terminal-pty-host.mjs",
+    "dist/terminal-pty-tree.mjs",
     "dist/marctl/**/*.mjs",
     "dist/marctl/**/*.cjs",
     "dist/marctl/package.json",
@@ -42,14 +44,14 @@
     "turndown-plugin-gfm": "^1.0.2",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/agent": "0.13.1",
-    "@myagentroam/protocol": "0.13.1"
+    "@myagentroam/agent": "0.13.3",
+    "@myagentroam/protocol": "0.13.3"
   },
   "devDependencies": {
     "@types/turndown": "^5.0.6",
     "@types/ws": "^8.18.1",
     "@myagentroam/code-navigation": "0.11.1",
-    "@myagentroam/marctl": "0.13.1"
+    "@myagentroam/marctl": "0.13.3"
   },
   "exports": {
     "./config": {