nterminal 1.2.79 → 1.2.81

package/dist/server/terminal/TerminalManager.js

@@ -1,9 +1,12 @@
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
+import { normalizeTerminalTitle } from './PtyAdapter.js';
 import { resolveProcessCwd } from './cwdResolver.js';
 import { OutputBuffer } from './outputBuffer.js';
 import { readTranscriptHistoryPage } from './transcriptHistory.js';
 import { AgentTranscriptTracker } from './agentTranscriptStatus.js';
+import { listTerminalSubagents, resolveSubagentTranscriptSource, subagentSummary } from './subagentSources.js';
+import { mapWithConcurrency } from './asyncCommand.js';
 // Window for the output-rate component of busy detection. Slightly larger
 // than the poll interval so a tab that just stopped emitting output
 // transitions to idle on the very next poll (rather than lagging a tick),
@@ -16,9 +19,16 @@ const BUSY_OUTPUT_WINDOW_MS = 2_500;
 // before a "command completed" notification reaches the operator at 2s,
 // which is fast enough to feel responsive without spamming polls.
 const STATUS_POLL_INTERVAL_MS = 2_000;
+const RESTORE_RETRY_INTERVAL_MS = 2_000;
+const TRANSCRIPT_POLL_CONCURRENCY = 2;
+const TRANSCRIPT_SOURCE_MISS_GRACE_MS = 10_000;
+const TRANSCRIPT_SLOW_WARNING_MS = 3_000;
+const DIAGNOSTIC_REPORT_INTERVAL_MS = 30_000;
+const DESTROY_ALL_CONCURRENCY = 4;
 const HISTORY_PAGE_LINES = 1000;
 const HISTORY_PAGE_MAX_LINES = 5000;
-const HISTORY_CURSOR_PROBE_LINES = 1;
+const MAX_PENDING_CONTROL_OPERATIONS = 256;
+const MAX_PENDING_CONTROL_BYTES = 16 * 1024 * 1024;
 export class TerminalManager {
     config;
     ptyAdapter;
@@ -26,21 +36,37 @@ export class TerminalManager {
     resolveCwd;
     now;
     onCompletion;
+    onDiagnostic;
     // Captured at construction so every spawn can compare a poll's
     // pane_current_command against the configured shell to decide "is this
     // terminal idle at a prompt or busy running something else?".
     shellBasename;
     terminalCapabilities;
     agentTranscriptTracker = new AgentTranscriptTracker();
+    transcriptQueue = [];
+    lastDiagnosticAt = new Map();
     completionStates = new Map();
     statusPollTimer = null;
+    restoreRetryTimer = null;
+    restoreInflight = null;
     statusPollInflight = false;
+    activeTranscriptWorkers = 0;
+    pendingInitializations = new Set();
+    // Restored tmux sessions start without a local PTY client. Keep a single
+    // reattach/catalog refresh in flight per terminal so an input burst cannot
+    // spawn competing tmux clients or repeatedly query the catalog.
+    reattachInflight = new Map();
+    terminalResetBlockers = 0;
+    terminalMutationGeneration = 0;
+    shutdownRequested = false;
+    disposed = false;
     constructor(config, ptyAdapter, options = {}) {
         this.config = config;
         this.ptyAdapter = ptyAdapter;
         this.resolveCwd = options.resolveCwd ?? resolveProcessCwd;
         this.now = options.now ?? (() => new Date());
         this.onCompletion = options.onCompletion ?? null;
+        this.onDiagnostic = options.onDiagnostic ?? null;
         this.shellBasename = path.basename(this.config.shell);
         this.terminalCapabilities =
             typeof this.ptyAdapter.scrollbackScroll === 'function' &&
@@ -58,86 +84,236 @@ export class TerminalManager {
             if (this.statusPollInflight)
                 return;
             this.statusPollInflight = true;
-            void this.pollOnce().finally(() => {
-                this.statusPollInflight = false;
-            });
+            void this.runStatusPoll();
         }, STATUS_POLL_INTERVAL_MS);
         // Unref so the interval doesn't keep the Node event loop alive on its
         // own — the HTTP server is what should be holding the process up.
         this.statusPollTimer.unref?.();
     }
+    async runStatusPoll() {
+        try {
+            await this.pollOnce();
+        }
+        catch (error) {
+            this.reportDiagnostic({ event: 'terminal.status_poll_failed', error });
+        }
+        finally {
+            this.statusPollInflight = false;
+        }
+    }
     async pollOnce() {
         const poll = this.ptyAdapter.pollSessions;
         if (!poll)
             return;
-        let result;
-        try {
-            result = await poll.call(this.ptyAdapter);
-        }
-        catch {
-            return;
-        }
+        const result = await poll.call(this.ptyAdapter);
         const now = Date.now();
-        for (const [terminalId, { currentCommand, busy }] of result) {
-            const record = this.terminals.get(terminalId);
-            if (!record || record.summary.status !== 'running')
-                continue;
-            // Two complementary signals for "is this tab working":
-            //   - kernel run state: catches CPU-bound work like npm install,
-            //     vim :%s, codex executing a tool call locally
-            //   - PTY output rate: catches I/O-bound work like codex streaming
-            //     tokens or claude printing a response — those processes spend
-            //     most of their time sleeping in epoll_wait (state S) but
-            //     output is steadily flowing, which is what the operator
-            //     actually means by "it's working"
-            // OR them together so either signal alone is enough.
-            const recentOutput = now - record.lastOutputAt < BUSY_OUTPUT_WINDOW_MS;
-            const nextCommand = currentCommand === this.shellBasename ? null : currentCommand;
-            const nextAgentTranscript = await this.resolveAgentTranscript(terminalId, nextCommand);
-            const nextAgentStatus = nextAgentTranscript?.status;
-            const nextAgentCache = nextAgentTranscript?.cache;
-            const nextActivity = activityFromSignals({ busy, recentOutput, agentStatus: nextAgentStatus });
-            if (record.summary.activity === nextActivity &&
-                record.summary.currentCommand === nextCommand &&
-                agentStatusEquals(record.summary.agentStatus, nextAgentStatus) &&
-                agentCacheEquals(record.summary.agentCache, nextAgentCache)) {
-                continue;
+        for (const [terminalId, snapshot] of result) {
+            try {
+                this.applyProcessSnapshot(terminalId, snapshot, now);
             }
-            record.summary.activity = nextActivity;
-            record.summary.currentCommand = nextCommand;
-            if (nextAgentStatus) {
-                record.summary.agentStatus = nextAgentStatus;
+            catch (error) {
+                this.reportDiagnostic({ event: 'terminal.process_snapshot_failed', terminalId, error });
             }
-            else {
+        }
+    }
+    applyProcessSnapshot(terminalId, snapshot, now) {
+        const record = this.terminals.get(terminalId);
+        if (!record || record.summary.status !== 'running' || record.closing)
+            return;
+        // Kernel run state catches CPU/I/O work; recent PTY output catches agents
+        // that spend most of a streaming turn asleep in epoll_wait. These fresh
+        // signals take priority over a transcript's previous completed state.
+        const recentOutput = now - record.lastOutputAt < BUSY_OUTPUT_WINDOW_MS;
+        const nextCommand = snapshot.currentCommand === this.shellBasename ? null : snapshot.currentCommand;
+        const commandChanged = record.summary.currentCommand !== nextCommand;
+        if (commandChanged) {
+            record.transcriptGeneration += 1;
+        }
+        record.lastKernelBusy = snapshot.busy;
+        let summaryChanged = commandChanged;
+        record.summary.currentCommand = nextCommand;
+        if (!nextCommand) {
+            this.agentTranscriptTracker.reset(terminalId);
+            record.transcriptSourceMissingSince = null;
+            if (record.summary.agentStatus) {
                 delete record.summary.agentStatus;
+                summaryChanged = true;
             }
-            if (nextAgentCache) {
-                record.summary.agentCache = nextAgentCache;
-            }
-            else {
+            if (record.summary.agentCache) {
                 delete record.summary.agentCache;
+                summaryChanged = true;
             }
+        }
+        const nextActivity = activityFromSignals({
+            busy: snapshot.busy,
+            recentOutput,
+            agentStatus: record.summary.agentStatus
+        });
+        if (record.summary.activity !== nextActivity) {
+            record.summary.activity = nextActivity;
+            summaryChanged = true;
+        }
+        if (summaryChanged) {
             record.summary.updatedAt = this.timestamp();
             this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
             this.trackCompletion(record.summary);
         }
+        if (nextCommand) {
+            this.scheduleTranscriptRefresh(terminalId);
+        }
+        else {
+            record.transcriptRerun = false;
+            this.cancelQueuedTranscriptRefresh(record);
+        }
+    }
+    scheduleTranscriptRefresh(terminalId) {
+        if (this.disposed)
+            return;
+        const record = this.terminals.get(terminalId);
+        if (!record || record.summary.status !== 'running' || record.closing || !record.summary.currentCommand)
+            return;
+        if (record.transcriptRefreshState === 'running') {
+            record.transcriptRerun = true;
+            return;
+        }
+        if (record.transcriptRefreshState === 'queued')
+            return;
+        record.transcriptRefreshState = 'queued';
+        this.transcriptQueue.push(terminalId);
+        this.pumpTranscriptQueue();
+    }
+    pumpTranscriptQueue() {
+        while (!this.disposed &&
+            this.activeTranscriptWorkers < TRANSCRIPT_POLL_CONCURRENCY &&
+            this.transcriptQueue.length > 0) {
+            const terminalId = this.transcriptQueue.shift();
+            const record = this.terminals.get(terminalId);
+            if (!record || record.transcriptRefreshState !== 'queued')
+                continue;
+            record.transcriptRefreshState = 'running';
+            this.activeTranscriptWorkers += 1;
+            void this.refreshAgentTranscript(terminalId)
+                .catch((error) => {
+                this.reportDiagnostic({ event: 'terminal.transcript_poll_failed', terminalId, error });
+            })
+                .finally(() => {
+                this.activeTranscriptWorkers -= 1;
+                if (this.terminals.get(terminalId) === record) {
+                    record.transcriptRefreshState = 'idle';
+                    const rerun = record.transcriptRerun;
+                    record.transcriptRerun = false;
+                    if (rerun && record.summary.status === 'running' && !record.closing && record.summary.currentCommand) {
+                        this.scheduleTranscriptRefresh(terminalId);
+                    }
+                }
+                this.pumpTranscriptQueue();
+            });
+        }
+    }
+    async refreshAgentTranscript(terminalId) {
+        const startedAt = Date.now();
+        const slowTimer = setTimeout(() => {
+            this.reportDiagnostic({
+                event: 'terminal.transcript_poll_slow',
+                terminalId,
+                queueDepth: this.transcriptQueue.length,
+                elapsedMs: Date.now() - startedAt
+            });
+        }, TRANSCRIPT_SLOW_WARNING_MS);
+        slowTimer.unref?.();
+        try {
+            await this.refreshAgentTranscriptOnce(terminalId);
+        }
+        finally {
+            clearTimeout(slowTimer);
+        }
+    }
+    async refreshAgentTranscriptOnce(terminalId) {
+        const record = this.terminals.get(terminalId);
+        const currentCommand = record?.summary.currentCommand ?? null;
+        if (!record || record.summary.status !== 'running' || record.closing || !currentCommand)
+            return;
+        const generation = record.transcriptGeneration;
+        const isCurrent = () => !this.disposed &&
+            this.terminals.get(terminalId) === record &&
+            record.summary.status === 'running' &&
+            !record.closing &&
+            record.transcriptGeneration === generation &&
+            record.summary.currentCommand === currentCommand;
+        const transcript = await this.resolveAgentTranscript(terminalId, currentCommand, isCurrent);
+        if (transcript === null || !isCurrent())
+            return;
+        const nextAgentStatus = transcript?.status;
+        const nextAgentCache = transcript?.cache;
+        if (agentSessionChanged(record.summary.agentStatus?.sessionId ?? null, nextAgentStatus?.sessionId ?? null)) {
+            record.transcriptGeneration += 1;
+        }
+        const nextActivity = activityFromSignals({
+            busy: record.lastKernelBusy,
+            recentOutput: Date.now() - record.lastOutputAt < BUSY_OUTPUT_WINDOW_MS,
+            agentStatus: nextAgentStatus
+        });
+        if (record.summary.activity === nextActivity &&
+            agentStatusEquals(record.summary.agentStatus, nextAgentStatus) &&
+            agentCacheEquals(record.summary.agentCache, nextAgentCache)) {
+            return;
+        }
+        record.summary.activity = nextActivity;
+        if (nextAgentStatus) {
+            record.summary.agentStatus = nextAgentStatus;
+        }
+        else {
+            delete record.summary.agentStatus;
+        }
+        if (nextAgentCache) {
+            record.summary.agentCache = nextAgentCache;
+        }
+        else {
+            delete record.summary.agentCache;
+        }
+        record.summary.updatedAt = this.timestamp();
+        this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
+        this.trackCompletion(record.summary);
     }
     // Allow the process to shut down cleanly without leaking the polling
     // interval — called by the server's graceful-shutdown path.
     dispose() {
+        this.disposed = true;
+        this.shutdownRequested = true;
         if (this.statusPollTimer) {
             clearInterval(this.statusPollTimer);
             this.statusPollTimer = null;
         }
+        this.clearRestoreRetryTimer();
+        this.transcriptQueue.length = 0;
+        for (const record of this.terminals.values()) {
+            record.transcriptRerun = false;
+            if (record.transcriptRefreshState === 'queued') {
+                record.transcriptRefreshState = 'idle';
+            }
+        }
     }
     async createTerminal(options = {}) {
+        if (this.shutdownRequested || this.terminalResetBlockers > 0) {
+            throw new Error('terminal manager is not accepting new terminals');
+        }
+        const initialization = this.createTerminalUntracked(options);
+        this.pendingInitializations.add(initialization);
+        try {
+            return await initialization;
+        }
+        finally {
+            this.pendingInitializations.delete(initialization);
+        }
+    }
+    async createTerminalUntracked(options) {
         const cwd = await this.resolveInitialCwd(options);
         const cols = normalizeDimension(options.cols, 80);
         const rows = normalizeDimension(options.rows, 24);
         const id = randomUUID();
         const timestamp = this.timestamp();
         const initialTitle = this.createTitle(cwd);
-        const pty = this.ptyAdapter.spawn({
+        const pty = await this.ptyAdapter.spawn({
             sessionId: id,
             shell: this.config.shell,
             cwd,
@@ -170,7 +346,19 @@ export class TerminalManager {
             exitDisposable: { dispose: () => undefined },
             pauseCount: 0,
             lastOutputAt: 0,
-            history: null
+            history: null,
+            lastKernelBusy: false,
+            transcriptGeneration: 0,
+            transcriptRefreshState: 'idle',
+            transcriptRerun: false,
+            transcriptSourceMissingSince: null,
+            cwdRefreshGeneration: 0,
+            controlTail: Promise.resolve(),
+            pendingControlOperations: 0,
+            pendingControlBytes: 0,
+            pendingScroll: null,
+            closePromise: null,
+            closing: false
         };
         this.wireUpPty(record, pty);
         this.terminals.set(id, record);
@@ -182,7 +370,57 @@ export class TerminalManager {
     // reattach to their live shells instead of being silently replaced by
     // fresh ones. A no-op for adapters without persistence (NodePtyAdapter).
     async restoreSessions() {
-        const existing = this.ptyAdapter.listExisting?.() ?? [];
+        if (this.shutdownRequested || this.terminalResetBlockers > 0) {
+            return;
+        }
+        if (this.ptyAdapter.listExisting &&
+            (!this.ptyAdapter.attachExisting || !this.ptyAdapter.destroySession)) {
+            this.reportDiagnostic({
+                event: 'terminal.restore_failed',
+                error: new Error('persistent adapter must implement attachExisting and destroySession')
+            });
+            return;
+        }
+        if (this.restoreInflight) {
+            await this.restoreInflight;
+            return;
+        }
+        const initialization = this.restoreSessionsUntracked();
+        this.restoreInflight = initialization;
+        this.pendingInitializations.add(initialization);
+        let restored = false;
+        try {
+            restored = await initialization;
+        }
+        finally {
+            this.pendingInitializations.delete(initialization);
+            if (this.restoreInflight === initialization) {
+                this.restoreInflight = null;
+            }
+        }
+        if (restored) {
+            this.clearRestoreRetryTimer();
+        }
+        else {
+            this.scheduleRestoreRetry();
+        }
+    }
+    async restoreSessionsUntracked() {
+        const restoreGeneration = this.terminalMutationGeneration;
+        let existing;
+        try {
+            existing = await (this.ptyAdapter.listExisting?.() ?? []);
+        }
+        catch (error) {
+            this.reportDiagnostic({ event: 'terminal.restore_failed', error });
+            return false;
+        }
+        // A close/reset that completed while listExisting() was in flight makes
+        // that catalog stale. Retry from a fresh adapter snapshot instead of
+        // resurrecting a session the operator just deleted.
+        if (restoreGeneration !== this.terminalMutationGeneration) {
+            return false;
+        }
         const now = this.timestamp();
         for (const session of existing) {
             const sessionId = session.sessionId;
@@ -192,12 +430,12 @@ export class TerminalManager {
             // operator had renamed the tab in a previous run — that's how a
             // human-readable label survives NTerminal restarts. Fall back to a
             // distinguishable placeholder when no name was set.
-            const restoredTitle = session.title?.trim() || `Terminal ${sessionId.slice(0, 6)}`;
+            const restoredTitle = normalizeTerminalTitle(session.title?.trim() || `Terminal ${sessionId.slice(0, 6)}`);
             this.terminals.set(sessionId, {
                 summary: {
                     id: sessionId,
                     title: restoredTitle,
-                    cwd: session.cwd?.trim() || this.config.workspaceRoot,
+                    cwd: session.cwd || this.config.workspaceRoot,
                     pid: null,
                     cols: 80,
                     rows: 24,
@@ -214,13 +452,53 @@ export class TerminalManager {
                 exitDisposable: { dispose: () => undefined },
                 pauseCount: 0,
                 lastOutputAt: 0,
-                history: null
+                history: null,
+                lastKernelBusy: false,
+                transcriptGeneration: 0,
+                transcriptRefreshState: 'idle',
+                transcriptRerun: false,
+                transcriptSourceMissingSince: null,
+                cwdRefreshGeneration: 0,
+                controlTail: Promise.resolve(),
+                pendingControlOperations: 0,
+                pendingControlBytes: 0,
+                pendingScroll: null,
+                closePromise: null,
+                closing: false
             });
         }
+        return true;
+    }
+    scheduleRestoreRetry() {
+        if (this.restoreRetryTimer || this.shutdownRequested || this.disposed) {
+            return;
+        }
+        this.restoreRetryTimer = setTimeout(() => {
+            this.restoreRetryTimer = null;
+            if (this.shutdownRequested || this.disposed) {
+                return;
+            }
+            if (this.terminalResetBlockers > 0) {
+                this.scheduleRestoreRetry();
+                return;
+            }
+            void this.restoreSessions();
+        }, RESTORE_RETRY_INTERVAL_MS);
+        this.restoreRetryTimer.unref?.();
+    }
+    clearRestoreRetryTimer() {
+        if (!this.restoreRetryTimer) {
+            return;
+        }
+        clearTimeout(this.restoreRetryTimer);
+        this.restoreRetryTimer = null;
     }
     wireUpPty(record, pty) {
         const id = record.summary.id;
         record.pty = pty;
+        if (record.pauseCount > 0) {
+            pty.pause();
+        }
         record.summary.pid = pty.pid;
         record.summary.status = 'running';
         record.summary.exitCode = null;
@@ -232,21 +510,103 @@ export class TerminalManager {
             this.publish(record, { type: 'output', terminalId: id, data });
         });
         record.exitDisposable = pty.onExit((event) => {
-            record.summary.status = 'exited';
-            record.summary.exitCode = event.exitCode;
+            if (record.pty !== pty) {
+                return;
+            }
+            record.dataDisposable.dispose();
+            record.exitDisposable.dispose();
+            record.transcriptGeneration += 1;
+            record.transcriptRerun = false;
+            this.cancelQueuedTranscriptRefresh(record);
             record.summary.pid = null;
             record.summary.updatedAt = this.timestamp();
-            delete record.summary.agentCache;
             record.pty = null;
-            this.completionStates.delete(id);
-            this.publish(record, { type: 'exit', terminalId: id, exitCode: event.exitCode });
+            this.finishPtyExit(record, event.exitCode);
         });
     }
+    finishPtyExit(record, exitCode) {
+        const id = record.summary.id;
+        const persistentState = record.closing ? false : this.persistentSessionState(id);
+        if (isPromiseLike(persistentState)) {
+            void persistentState.then((state) => {
+                this.applyPtyExitState(record, exitCode, state);
+            });
+            return;
+        }
+        this.applyPtyExitState(record, exitCode, persistentState);
+    }
+    applyPtyExitState(record, exitCode, persistentState) {
+        const id = record.summary.id;
+        if (this.terminals.get(id) !== record ||
+            record.pty !== null ||
+            record.closing ||
+            record.summary.status !== 'running') {
+            return;
+        }
+        if (persistentState !== false) {
+            record.summary.status = 'running';
+            record.summary.exitCode = null;
+            if (record.subscribers.size > 0) {
+                // A local tmux client can exit while the backing session remains
+                // alive. Refresh the catalog before deciding it disappeared.
+                void this.ensureAttachedAsync(record);
+            }
+            record.summary.updatedAt = this.timestamp();
+            this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
+            return;
+        }
+        this.markSessionUnavailable(record, exitCode);
+    }
+    persistentSessionState(sessionId) {
+        if (!this.ptyAdapter.listExisting) {
+            return false;
+        }
+        try {
+            const existing = this.ptyAdapter.listExisting();
+            if (isPromiseLike(existing)) {
+                return existing
+                    .then((sessions) => sessions.some((session) => session.sessionId === sessionId))
+                    .catch(() => null);
+            }
+            return existing.some((session) => session.sessionId === sessionId);
+        }
+        catch {
+            return null;
+        }
+    }
+    markSessionUnavailable(record, exitCode) {
+        if (this.terminals.get(record.summary.id) !== record || record.closing) {
+            return;
+        }
+        if (record.summary.status === 'exited') {
+            if (record.summary.exitCode === null && exitCode !== null) {
+                record.summary.exitCode = exitCode;
+                record.summary.updatedAt = this.timestamp();
+            }
+            return;
+        }
+        const id = record.summary.id;
+        record.summary.pid = null;
+        record.summary.status = 'exited';
+        record.summary.exitCode = exitCode;
+        record.summary.updatedAt = this.timestamp();
+        record.history = null;
+        delete record.summary.activity;
+        delete record.summary.currentCommand;
+        delete record.summary.agentStatus;
+        delete record.summary.agentCache;
+        this.agentTranscriptTracker.reset(id);
+        this.completionStates.delete(id);
+        this.publish(record, { type: 'exit', terminalId: id, exitCode });
+    }
     // Spawn a fresh local client for a restored session that hasn't been
     // attached since startup. Called lazily on the first attachTerminal so
     // sessions the operator never reopens don't consume processes.
     reattachToSession(record) {
-        const pty = this.ptyAdapter.spawn({
+        if (!this.ptyAdapter.attachExisting) {
+            throw new Error('persistent adapter cannot attach an existing session');
+        }
+        const pty = this.ptyAdapter.attachExisting({
             sessionId: record.summary.id,
             shell: this.config.shell,
             cwd: record.summary.cwd,
@@ -256,23 +616,6 @@ export class TerminalManager {
         });
         this.wireUpPty(record, pty);
     }
-    captureTerminalHistoryCursor(record) {
-        const capture = this.ptyAdapter.captureHistory?.(record.summary.id, {
-            beforeLine: 0,
-            limit: HISTORY_CURSOR_PROBE_LINES
-        });
-        if (!capture) {
-            return null;
-        }
-        if (!capture.hasMore && capture.endLine < capture.startLine) {
-            return null;
-        }
-        return {
-            startLine: 0,
-            endLine: 0,
-            hasMore: capture.hasMore || capture.endLine >= capture.startLine
-        };
-    }
     listTerminals() {
         return [...this.terminals.values()].map((record) => cloneSummary(record.summary));
     }
@@ -283,17 +626,28 @@ export class TerminalManager {
     getOutputSnapshot(id) {
         return this.terminals.get(id)?.output.snapshot() ?? null;
     }
-    getTerminalHistory(id, options = {}) {
+    async getTerminalHistory(id, options = {}) {
         const record = this.terminals.get(id);
-        if (!record || record.summary.status !== 'running') {
+        if (!record || record.summary.status !== 'running' || record.closing) {
+            return null;
+        }
+        if (!record.pty && !await this.ensureAttachedAsync(record)) {
             return null;
         }
         const limit = normalizeHistoryLimit(options.limit);
-        const capture = this.ptyAdapter.captureHistory?.(id, {
+        const capture = await this.ptyAdapter.captureHistory?.(id, {
             ...(options.beforeLine !== undefined ? { beforeLine: options.beforeLine } : {}),
+            ...(options.snapshotHistorySize !== undefined ? { snapshotHistorySize: options.snapshotHistorySize } : {}),
+            ...(options.snapshotHistoryLimit !== undefined ? { snapshotHistoryLimit: options.snapshotHistoryLimit } : {}),
+            ...(options.snapshotHistoryToken !== undefined
+                ? { snapshotHistoryToken: options.snapshotHistoryToken }
+                : {}),
+            ...(options.snapshotPaneWidth !== undefined
+                ? { snapshotPaneWidth: options.snapshotPaneWidth }
+                : {}),
             limit
         });
-        if (!capture) {
+        if (!capture || this.terminals.get(id) !== record || record.summary.status !== 'running' || record.closing) {
             return null;
         }
         return {
@@ -301,70 +655,167 @@ export class TerminalManager {
             startLine: capture.startLine,
             endLine: capture.endLine,
             hasMore: capture.hasMore,
+            ...(capture.invalidated ? { invalidated: true } : {}),
+            ...(capture.snapshotHistorySize !== undefined
+                ? { snapshotHistorySize: capture.snapshotHistorySize }
+                : {}),
+            ...(capture.snapshotHistoryLimit !== undefined
+                ? { snapshotHistoryLimit: capture.snapshotHistoryLimit }
+                : {}),
+            ...(capture.snapshotHistoryToken !== undefined
+                ? { snapshotHistoryToken: capture.snapshotHistoryToken }
+                : {}),
+            ...(capture.snapshotPaneWidth !== undefined
+                ? { snapshotPaneWidth: capture.snapshotPaneWidth }
+                : {}),
             output: capture.output
         };
     }
-    getTerminalTranscriptHistory(id, options = {}) {
+    // Shared liveness guard for the transcript endpoints: resolve the pane's
+    // source, re-validating the record after the await so a pane that closed
+    // or switched sessions mid-request never serves another session's data.
+    async resolveLiveTranscriptSource(id) {
         const record = this.terminals.get(id);
-        if (!record || record.summary.status !== 'running') {
+        if (!record || record.summary.status !== 'running' || record.closing) {
             return null;
         }
-        const source = this.ptyAdapter.resolveTranscriptSource?.(id);
-        if (!source) {
+        const generation = record.transcriptGeneration;
+        const source = await this.ptyAdapter.resolveTranscriptSource?.(id);
+        if (!source ||
+            !transcriptSourceMatchesForeground(record.summary, source.provider) ||
+            !this.transcriptRequestStillLive(id, record, generation)) {
             return null;
         }
-        return readTranscriptHistoryPage(id, source, options);
+        return { record, generation, source };
     }
-    getTerminalTranscriptSource(id) {
-        const record = this.terminals.get(id);
-        if (!record || record.summary.status !== 'running') {
+    transcriptRequestStillLive(id, record, generation) {
+        return this.terminals.get(id) === record &&
+            record.summary.status === 'running' &&
+            !record.closing &&
+            record.transcriptGeneration === generation;
+    }
+    async getTerminalTranscriptHistory(id, options = {}) {
+        const live = await this.resolveLiveTranscriptSource(id);
+        if (!live) {
+            return null;
+        }
+        const page = await readTranscriptHistoryPage(id, live.source, options);
+        return this.transcriptRequestStillLive(id, live.record, live.generation) ? page : null;
+    }
+    async getTerminalTranscriptSource(id) {
+        const live = await this.resolveLiveTranscriptSource(id);
+        if (!live) {
+            return null;
+        }
+        return {
+            terminalId: id,
+            source: { provider: live.source.provider, sessionId: live.source.sessionId }
+        };
+    }
+    async getTerminalSubagents(id) {
+        const live = await this.resolveLiveTranscriptSource(id);
+        if (!live) {
             return null;
         }
-        const source = this.ptyAdapter.resolveTranscriptSource?.(id);
-        if (!source) {
+        const subagents = await listTerminalSubagents(live.source);
+        if (!this.transcriptRequestStillLive(id, live.record, live.generation)) {
             return null;
         }
         return {
             terminalId: id,
-            source: { provider: source.provider, sessionId: source.sessionId }
+            source: { provider: live.source.provider, sessionId: live.source.sessionId },
+            subagents: subagents.map(subagentSummary)
         };
     }
+    async getTerminalSubagentTranscript(id, subagentId, options = {}) {
+        const live = await this.resolveLiveTranscriptSource(id);
+        if (!live) {
+            return null;
+        }
+        // Resolve the child through the server-side listing rather than trusting
+        // the client id as a path component: the transcript path is always
+        // server-derived.
+        const childSource = await resolveSubagentTranscriptSource(live.source, subagentId);
+        if (!childSource || !this.transcriptRequestStillLive(id, live.record, live.generation)) {
+            return null;
+        }
+        const page = await readTranscriptHistoryPage(id, childSource, { ...options, archiveTrailer: false });
+        return this.transcriptRequestStillLive(id, live.record, live.generation) ? page : null;
+    }
     async resolveTerminalCwd(id) {
         const record = this.terminals.get(id);
-        if (!record || !this.ensureAttached(record)) {
+        if (!record || !await this.ensureAttachedAsync(record)) {
+            return null;
+        }
+        const pty = record.pty;
+        if (!pty) {
             return null;
         }
-        return this.safeResolveCwd(record.pty.pid);
+        const cwd = await this.safeResolveCwd(pty.pid);
+        return (cwd &&
+            this.terminals.get(id) === record &&
+            !record.closing &&
+            record.summary.status === 'running' &&
+            record.pty === pty) ? cwd : null;
     }
     // Push a new human title to the record and the persistence adapter so the
     // operator's rename of a tab survives both detach (the title shows up on
     // the pill) and NTerminal restart (tmux holds the title as its window
-    // name). Returns the updated summary, or null when the id is unknown.
-    renameTerminal(id, title) {
+    // name). The adapter write and in-memory update share the terminal's control
+    // queue so rename, input, scrollback, and close cannot overtake each other.
+    async renameTerminal(id, title) {
         const record = this.terminals.get(id);
         if (!record)
-            return null;
-        const trimmed = title.trim();
-        if (!trimmed || trimmed === record.summary.title) {
-            return cloneSummary(record.summary);
+            return { status: 'not_found' };
+        if (record.closing)
+            return { status: 'closing' };
+        const normalizedTitle = normalizeTerminalTitle(title);
+        if (normalizedTitle === record.summary.title && record.pendingControlOperations === 0) {
+            return { status: 'renamed', terminal: cloneSummary(record.summary) };
         }
-        record.summary.title = trimmed;
-        record.summary.updatedAt = this.timestamp();
-        this.ptyAdapter.setSessionTitle?.(id, trimmed);
-        this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
-        return cloneSummary(record.summary);
+        this.sealPendingScroll(record);
+        if (!this.canEnqueueControl(record)) {
+            return { status: 'queue_full' };
+        }
+        return await this.enqueueControl(record, async () => {
+            if (this.terminals.get(id) !== record)
+                return { status: 'not_found' };
+            if (record.closing)
+                return { status: 'closing' };
+            if (record.summary.title === normalizedTitle) {
+                return { status: 'renamed', terminal: cloneSummary(record.summary) };
+            }
+            try {
+                await this.ptyAdapter.setSessionTitle?.(id, normalizedTitle);
+            }
+            catch {
+                return { status: 'persistence_failed' };
+            }
+            if (this.terminals.get(id) !== record)
+                return { status: 'not_found' };
+            // Persistence already succeeded. Publish the same value even if a
+            // close request arrived while the adapter call was in flight; if that
+            // close later fails, memory and tmux must not diverge.
+            record.summary.title = normalizedTitle;
+            record.summary.updatedAt = this.timestamp();
+            const terminal = cloneSummary(record.summary);
+            this.publish(record, { type: 'terminal_updated', terminal });
+            return { status: 'renamed', terminal };
+        });
     }
     async refreshTerminalCwd(id) {
         const record = this.terminals.get(id);
-        if (!record || !this.ensureAttached(record)) {
+        if (!record || !await this.ensureAttachedAsync(record)) {
             return null;
         }
         await this.refreshCwd(record);
-        return cloneSummary(record.summary);
+        return this.terminals.get(id) === record && !record.closing
+            ? cloneSummary(record.summary)
+            : null;
     }
     attachTerminal(id, subscriber, options = {}) {
         const record = this.terminals.get(id);
-        if (!record) {
+        if (!record || record.closing) {
             return null;
         }
         // Lazy attach for restored sessions: if the record exists in memory but
@@ -372,11 +823,30 @@ export class TerminalManager {
         // at startup but haven't reconnected yet), spawn one now. From the
         // client's perspective this is indistinguishable from a normal attach
         // — tmux replays the current screen on connect.
-        if (!this.ensureAttached(record) && record.summary.status === 'running') {
+        if (record.summary.status === 'running' && !this.ensureAttached(record)) {
+            return null;
+        }
+        return this.createAttachment(record, subscriber, options);
+    }
+    async attachTerminalAsync(id, subscriber, options = {}) {
+        const record = this.terminals.get(id);
+        if (!record || record.closing) {
+            return null;
+        }
+        if (record.summary.status === 'running' && !await this.ensureAttachedAsync(record)) {
+            return null;
+        }
+        if (this.terminals.get(id) !== record || record.closing) {
             return null;
         }
+        return this.createAttachment(record, subscriber, options);
+    }
+    createAttachment(record, subscriber, options) {
+        const id = record.summary.id;
         if (record.summary.status === 'running') {
-            record.history = this.captureTerminalHistoryCursor(record);
+            record.history = typeof this.ptyAdapter.captureHistory === 'function'
+                ? { startLine: 0, endLine: 0, hasMore: true }
+                : null;
         }
         const output = record.output.snapshot();
         record.subscribers.add(subscriber);
@@ -416,35 +886,124 @@ export class TerminalManager {
             }
         };
     }
-    writeToTerminal(id, data, options = {}) {
+    async writeToTerminal(id, data, options = {}) {
         const record = this.terminals.get(id);
-        if (!record?.pty || record.summary.status !== 'running') {
+        const inputBytes = Buffer.byteLength(data, 'utf8');
+        if (!controlOperationAllowed(options)) {
             return false;
         }
-        if (options.cancelScrollbackMode && !this.cancelTerminalScrollbackMode(id)) {
+        if (record && !record.pty && record.summary.status === 'running' && !record.closing) {
+            await this.ensureAttachedAsync(record);
+        }
+        if (!record?.pty ||
+            record.summary.status !== 'running' ||
+            record.closing ||
+            !this.canEnqueueControl(record, inputBytes)) {
             return false;
         }
-        record.pty.write(data);
-        record.summary.updatedAt = this.timestamp();
-        return true;
+        this.sealPendingScroll(record);
+        return await this.enqueueControl(record, async () => {
+            if (!controlOperationAllowed(options) ||
+                this.terminals.get(id) !== record ||
+                !record.pty ||
+                record.summary.status !== 'running' ||
+                record.closing) {
+                return false;
+            }
+            if (options.cancelScrollbackMode &&
+                this.ptyAdapter.cancelScrollbackMode &&
+                !await this.ptyAdapter.cancelScrollbackMode(id)) {
+                return false;
+            }
+            if (!controlOperationAllowed(options) ||
+                this.terminals.get(id) !== record ||
+                !record.pty ||
+                record.summary.status !== 'running' ||
+                record.closing) {
+                return false;
+            }
+            record.pty.write(data);
+            record.summary.updatedAt = this.timestamp();
+            return true;
+        }, inputBytes);
     }
-    scrollTerminalScrollback(id, lines) {
+    async scrollTerminalScrollback(id, lines, options = {}) {
         const record = this.terminals.get(id);
-        if (!record || record.summary.status !== 'running' || !this.ensureAttached(record)) {
+        const scroll = this.ptyAdapter.scrollbackScroll;
+        if (!controlOperationAllowed(options) ||
+            !record ||
+            record.summary.status !== 'running' ||
+            record.closing ||
+            !scroll) {
+            return false;
+        }
+        if (!record.pty && !await this.ensureAttachedAsync(record)) {
+            return false;
+        }
+        const normalizedLines = clampScrollLines(lines);
+        const pending = record.pendingScroll;
+        if (pending) {
+            addPendingScrollDelta(pending.groups, options.canExecute, normalizedLines);
+            return await pending.promise;
+        }
+        if (!this.canEnqueueControl(record)) {
             return false;
         }
-        return this.ptyAdapter.scrollbackScroll?.(id, lines) ?? false;
+        const groups = new Map();
+        addPendingScrollDelta(groups, options.canExecute, normalizedLines);
+        const next = { groups, promise: Promise.resolve(false) };
+        next.promise = this.enqueueControl(record, async () => {
+            if (record.pendingScroll === next) {
+                record.pendingScroll = null;
+            }
+            if (this.terminals.get(id) !== record || record.summary.status !== 'running' || record.closing) {
+                return false;
+            }
+            let combinedLines = 0;
+            let hasExecutableRequest = false;
+            for (const [canExecute, groupLines] of next.groups) {
+                if (!controlCallbackAllowed(canExecute)) {
+                    continue;
+                }
+                hasExecutableRequest = true;
+                combinedLines += groupLines;
+            }
+            if (!hasExecutableRequest) {
+                return false;
+            }
+            return await scroll.call(this.ptyAdapter, id, clampScrollLines(combinedLines));
+        });
+        record.pendingScroll = next;
+        return next.promise;
     }
-    cancelTerminalScrollbackMode(id) {
+    async cancelTerminalScrollbackMode(id, options = {}) {
         const record = this.terminals.get(id);
-        if (!record || record.summary.status !== 'running' || !this.ensureAttached(record)) {
+        if (!controlOperationAllowed(options) ||
+            !record ||
+            record.summary.status !== 'running' ||
+            record.closing ||
+            !this.canEnqueueControl(record)) {
+            return false;
+        }
+        if (!record.pty && !await this.ensureAttachedAsync(record)) {
             return false;
         }
-        return this.ptyAdapter.cancelScrollbackMode?.(id) ?? true;
+        this.sealPendingScroll(record);
+        return await this.enqueueControl(record, async () => {
+            if (!controlOperationAllowed(options) ||
+                this.terminals.get(id) !== record ||
+                record.summary.status !== 'running' ||
+                record.closing) {
+                return false;
+            }
+            return this.ptyAdapter.cancelScrollbackMode
+                ? await this.ptyAdapter.cancelScrollbackMode(id)
+                : true;
+        });
     }
     resizeTerminal(id, cols, rows) {
         const record = this.terminals.get(id);
-        if (!record?.pty || record.summary.status !== 'running') {
+        if (!record?.pty || record.summary.status !== 'running' || record.closing) {
             return false;
         }
         const normalizedCols = normalizeDimension(cols, record.summary.cols);
@@ -459,47 +1018,148 @@ export class TerminalManager {
         this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
         return true;
     }
-    closeTerminal(id) {
+    async closeTerminal(id) {
         const record = this.terminals.get(id);
         if (!record) {
             return false;
         }
-        if (!record.pty && record.summary.status === 'running') {
-            this.ptyAdapter.destroySession?.(id);
+        if (this.ptyAdapter.listExisting && !this.ptyAdapter.destroySession) {
+            return false;
         }
-        this.disposeRecord(record);
-        this.terminals.delete(id);
-        return true;
-    }
-    closeAll() {
-        // Differs from closeTerminal: we tear down our in-memory bookkeeping but
-        // DO NOT call pty.kill() when the adapter is persistent (tmux). Killing
-        // here would destroy every tmux session on NTerminal shutdown — defeating
-        // the entire across-restart persistence design. For non-persistent
-        // adapters (NodePtyAdapter), the child shells get SIGHUP via process
-        // tree exit anyway, so explicitly killing is just being polite.
-        const persistent = typeof this.ptyAdapter.listExisting === 'function';
-        for (const record of this.terminals.values()) {
-            record.dataDisposable.dispose();
-            record.exitDisposable.dispose();
-            record.subscribers.clear();
-            if (!persistent && record.pty && record.summary.status === 'running') {
-                record.pty.kill();
+        if (record.closePromise)
+            return record.closePromise;
+        this.markClosing(record);
+        const queuedClose = this.enqueueControl(record, async () => {
+            if (this.terminals.get(id) !== record)
+                return false;
+            if (this.ptyAdapter.destroySession) {
+                let destroyed = false;
+                try {
+                    destroyed = await this.ptyAdapter.destroySession(id);
+                }
+                catch (error) {
+                    this.reportDiagnostic({ event: 'terminal.destroy_failed', terminalId: id, error });
+                }
+                if (!destroyed) {
+                    return await this.recoverOrFinalizeFailedClose(record);
+                }
             }
-            record.pty = null;
+            this.disposeRecord(record);
+            this.terminals.delete(id);
+            return true;
+        }, 0, true);
+        const close = queuedClose.catch(async (error) => {
+            let finalized = false;
+            if (this.terminals.get(id) === record) {
+                finalized = await this.recoverOrFinalizeFailedClose(record);
+            }
+            this.reportDiagnostic({ event: 'terminal.close_failed', terminalId: id, error });
+            return finalized;
+        });
+        record.closePromise = close;
+        void close.finally(() => {
+            if (record.closePromise === close) {
+                record.closePromise = null;
+            }
+        }).catch(() => undefined);
+        return close;
+    }
+    sealPendingScroll(record) {
+        record.pendingScroll = null;
+    }
+    markClosing(record) {
+        if (record.closing)
+            return;
+        record.closing = true;
+        this.terminalMutationGeneration += 1;
+        record.transcriptGeneration += 1;
+        this.sealPendingScroll(record);
+        record.transcriptRerun = false;
+        this.cancelQueuedTranscriptRefresh(record);
+    }
+    async recoverOrFinalizeFailedClose(record) {
+        record.closing = false;
+        if (record.pty) {
+            return false;
         }
-        this.terminals.clear();
+        const persistentState = await this.persistentSessionState(record.summary.id);
+        if (persistentState === false) {
+            this.disposeRecord(record);
+            this.terminals.delete(record.summary.id);
+            return true;
+        }
+        record.summary.status = 'running';
+        record.summary.exitCode = null;
+        record.summary.updatedAt = this.timestamp();
+        if (record.subscribers.size > 0) {
+            void this.ensureAttachedAsync(record);
+        }
+        this.publish(record, {
+            type: 'terminal_updated',
+            terminal: cloneSummary(record.summary)
+        });
+        return false;
     }
-    destroyAllTerminals() {
-        for (const record of this.terminals.values()) {
-            if (record.summary.status === 'running' && this.ptyAdapter.destroySession) {
-                this.ptyAdapter.destroySession(record.summary.id);
+    async closeAll() {
+        this.shutdownRequested = true;
+        this.clearRestoreRetryTimer();
+        await this.awaitPendingInitializations();
+        // PtyProcess.kill() disposes only the local client. Persistent backing
+        // sessions are destroyed exclusively by destroySession(), so detaching
+        // every local client here preserves tmux sessions across restart. An
+        // explicit close already accepted by the control queue is different:
+        // let it finish first so shutdown cannot erase the record and silently
+        // turn a requested deletion into a detach.
+        while (true) {
+            const pendingCloses = [...this.terminals.values()]
+                .map((record) => record.closePromise)
+                .filter((close) => close !== null);
+            if (pendingCloses.length === 0) {
+                break;
             }
+            await Promise.allSettled(pendingCloses);
+        }
+        for (const record of this.terminals.values()) {
             this.disposeRecord(record);
         }
         this.terminals.clear();
+        this.completionStates.clear();
     }
-    ensureAttached(record) {
+    async destroyAllTerminals() {
+        this.terminalResetBlockers += 1;
+        try {
+            await this.awaitPendingInitializations();
+            const records = [...this.terminals.values()];
+            for (const record of records) {
+                if (this.terminals.get(record.summary.id) === record) {
+                    this.markClosing(record);
+                }
+            }
+            const results = await mapWithConcurrency(records, DESTROY_ALL_CONCURRENCY, async (record) => {
+                if (this.terminals.get(record.summary.id) !== record)
+                    return false;
+                return await this.closeTerminal(record.summary.id);
+            });
+            const destroyed = results.filter(Boolean).length;
+            return {
+                requested: records.length,
+                destroyed,
+                failed: records.length - destroyed
+            };
+        }
+        finally {
+            this.terminalResetBlockers = Math.max(0, this.terminalResetBlockers - 1);
+        }
+    }
+    async awaitPendingInitializations() {
+        while (this.pendingInitializations.size > 0) {
+            await Promise.allSettled([...this.pendingInitializations]);
+        }
+    }
+    ensureAttached(record, onAttachFailure) {
+        if (record.closing) {
+            return false;
+        }
         if (record.pty) {
             return true;
         }
@@ -509,11 +1169,69 @@ export class TerminalManager {
         try {
             this.reattachToSession(record);
         }
-        catch {
+        catch (error) {
+            onAttachFailure?.(error);
             return false;
         }
         return record.pty !== null;
     }
+    async ensureAttachedAsync(record) {
+        if (this.terminals.get(record.summary.id) !== record ||
+            record.closing ||
+            record.summary.status !== 'running') {
+            return false;
+        }
+        if (record.pty)
+            return true;
+        if (!this.ptyAdapter.listExisting || !this.ptyAdapter.attachExisting) {
+            return false;
+        }
+        const existing = this.reattachInflight.get(record.summary.id);
+        if (existing) {
+            return await existing;
+        }
+        const recovery = this.attachOrRefresh(record);
+        this.reattachInflight.set(record.summary.id, recovery);
+        try {
+            return await recovery;
+        }
+        finally {
+            if (this.reattachInflight.get(record.summary.id) === recovery) {
+                this.reattachInflight.delete(record.summary.id);
+            }
+        }
+    }
+    async attachOrRefresh(record) {
+        if (this.ensureAttached(record)) {
+            return true;
+        }
+        return await this.refreshAndAttach(record);
+    }
+    async refreshAndAttach(record) {
+        const id = record.summary.id;
+        try {
+            const existing = await this.ptyAdapter.listExisting?.();
+            if (this.terminals.get(id) !== record ||
+                record.closing ||
+                record.summary.status !== 'running') {
+                return false;
+            }
+            if (!existing?.some((session) => session.sessionId === id)) {
+                this.markSessionUnavailable(record, null);
+                return false;
+            }
+            // listExisting() refreshes the tmux adapter's pane-PID catalog. This
+            // second attach is the only retry; terminal input itself is never
+            // replayed by the manager.
+            return this.ensureAttached(record, (attachError) => {
+                this.reportDiagnostic({ event: 'terminal.reattach_failed', terminalId: id, error: attachError });
+            });
+        }
+        catch (error) {
+            this.reportDiagnostic({ event: 'terminal.reattach_failed', terminalId: id, error });
+            return false;
+        }
+    }
     async resolveInitialCwd(options) {
         if (options.cwd?.trim()) {
             return path.resolve(options.cwd);
@@ -540,18 +1258,52 @@ export class TerminalManager {
         if (!pty || record.summary.status !== 'running') {
             return;
         }
+        const refreshGeneration = ++record.cwdRefreshGeneration;
         const cwd = await this.safeResolveCwd(pty.pid);
-        if (!cwd || record.pty !== pty || record.summary.status !== 'running' || cwd === record.summary.cwd) {
+        if (!cwd ||
+            this.terminals.get(record.summary.id) !== record ||
+            record.closing ||
+            record.pty !== pty ||
+            record.summary.status !== 'running' ||
+            record.cwdRefreshGeneration !== refreshGeneration ||
+            cwd === record.summary.cwd) {
             return;
         }
-        const previousAutoTitle = this.createTitle(record.summary.cwd);
-        const shouldAutoRename = record.summary.title === previousAutoTitle;
-        record.summary.cwd = cwd;
-        if (shouldAutoRename) {
-            record.summary.title = this.createTitle(cwd);
+        this.sealPendingScroll(record);
+        if (!this.canEnqueueControl(record)) {
+            return;
         }
-        record.summary.updatedAt = this.timestamp();
-        this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
+        await this.enqueueControl(record, async () => {
+            if (this.terminals.get(record.summary.id) !== record ||
+                record.closing ||
+                record.pty !== pty ||
+                record.summary.status !== 'running' ||
+                record.cwdRefreshGeneration !== refreshGeneration ||
+                cwd === record.summary.cwd) {
+                return;
+            }
+            const previousAutoTitle = this.createTitle(record.summary.cwd);
+            const shouldAutoRename = record.summary.title === previousAutoTitle;
+            const nextAutoTitle = this.createTitle(cwd);
+            let autoTitlePersisted = shouldAutoRename;
+            if (shouldAutoRename && this.ptyAdapter.setSessionTitle) {
+                try {
+                    await this.ptyAdapter.setSessionTitle(record.summary.id, nextAutoTitle);
+                }
+                catch {
+                    autoTitlePersisted = false;
+                }
+            }
+            if (this.terminals.get(record.summary.id) !== record) {
+                return;
+            }
+            record.summary.cwd = cwd;
+            if (autoTitlePersisted) {
+                record.summary.title = nextAutoTitle;
+            }
+            record.summary.updatedAt = this.timestamp();
+            this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
+        }).catch(() => undefined);
     }
     publish(record, message) {
         for (const subscriber of record.subscribers) {
@@ -607,26 +1359,72 @@ export class TerminalManager {
         }
         void Promise.resolve(this.onCompletion(event)).catch(() => undefined);
     }
-    async resolveAgentTranscript(terminalId, currentCommand) {
+    async resolveAgentTranscript(terminalId, currentCommand, isCurrent = () => true) {
         if (!currentCommand) {
             this.agentTranscriptTracker.reset(terminalId);
+            const record = this.terminals.get(terminalId);
+            if (record)
+                record.transcriptSourceMissingSince = null;
             return undefined;
         }
+        const record = this.terminals.get(terminalId);
         const inferredProvider = inferAgentProviderFromCommand(currentCommand);
-        const source = this.ptyAdapter.resolveTranscriptSource?.(terminalId);
-        if (!source) {
-            this.agentTranscriptTracker.reset(terminalId);
-            return inferredProvider ? { status: { provider: inferredProvider, state: 'unknown' }, cache: null } : undefined;
+        const graceProvider = expectedAgentProvider(currentCommand, record?.summary.agentStatus?.provider);
+        const source = await this.ptyAdapter.resolveTranscriptSource?.(terminalId);
+        if (!isCurrent())
+            return null;
+        const providerMismatch = Boolean(source && graceProvider && source.provider !== graceProvider);
+        if (!source || providerMismatch) {
+            const now = Date.now();
+            const missingSince = record?.transcriptSourceMissingSince ?? now;
+            if (record)
+                record.transcriptSourceMissingSince = missingSince;
+            const existing = record?.summary;
+            if (now - missingSince <= TRANSCRIPT_SOURCE_MISS_GRACE_MS &&
+                graceProvider &&
+                existing?.agentStatus &&
+                existing.agentStatus.provider === graceProvider) {
+                return {
+                    status: { ...existing.agentStatus },
+                    cache: existing.agentCache ? { ...existing.agentCache, source: { ...existing.agentCache.source } } : null
+                };
+            }
+            // A node wrapper cannot identify the provider itself. Once the grace
+            // window outlives the adapter's short resolution cache, a consistently
+            // different resolved provider is evidence of a real in-pane switch.
+            if (source && providerMismatch && inferredProvider === null) {
+                if (record)
+                    record.transcriptSourceMissingSince = null;
+            }
+            else {
+                this.agentTranscriptTracker.reset(terminalId);
+                // A generic node process is only an ambiguous wrapper during the
+                // bounded grace window above. Keeping the previous provider after
+                // that window would misclassify an unrelated node application as an
+                // agent indefinitely.
+                return inferredProvider
+                    ? { status: { provider: inferredProvider, state: 'unknown' }, cache: null }
+                    : undefined;
+            }
         }
+        if (record)
+            record.transcriptSourceMissingSince = null;
         try {
-            return await this.agentTranscriptTracker.readSnapshot(terminalId, source);
+            const snapshot = await this.agentTranscriptTracker.readSnapshot(terminalId, source);
+            return isCurrent() ? snapshot : null;
         }
         catch {
-            return { status: { provider: source.provider, state: 'unknown' }, cache: null };
+            return isCurrent() ? { status: { provider: source.provider, state: 'unknown' }, cache: null } : null;
         }
     }
     disposeRecord(record) {
+        record.transcriptGeneration += 1;
         this.agentTranscriptTracker.reset(record.summary.id);
+        this.completionStates.delete(record.summary.id);
+        record.transcriptSourceMissingSince = null;
+        record.transcriptRerun = false;
+        this.cancelQueuedTranscriptRefresh(record);
+        record.pendingScroll = null;
         record.dataDisposable.dispose();
         record.exitDisposable.dispose();
         record.subscribers.clear();
@@ -636,11 +1434,59 @@ export class TerminalManager {
         record.pty = null;
     }
     createTitle(cwd) {
-        return path.basename(cwd) || 'Terminal';
+        return normalizeTerminalTitle(path.basename(cwd) || 'Terminal');
+    }
+    cancelQueuedTranscriptRefresh(record) {
+        if (record.transcriptRefreshState !== 'queued') {
+            return;
+        }
+        record.transcriptRefreshState = 'idle';
+        const terminalId = record.summary.id;
+        for (let index = this.transcriptQueue.length - 1; index >= 0; index -= 1) {
+            if (this.transcriptQueue[index] === terminalId) {
+                this.transcriptQueue.splice(index, 1);
+            }
+        }
     }
     timestamp() {
         return this.now().toISOString();
     }
+    reportDiagnostic(diagnostic) {
+        const now = Date.now();
+        const lastReportedAt = this.lastDiagnosticAt.get(diagnostic.event);
+        if (lastReportedAt !== undefined && now - lastReportedAt < DIAGNOSTIC_REPORT_INTERVAL_MS)
+            return;
+        this.lastDiagnosticAt.set(diagnostic.event, now);
+        try {
+            this.onDiagnostic?.(diagnostic);
+        }
+        catch {
+            // Diagnostics must never turn a contained background failure into a
+            // process-level unhandled rejection.
+        }
+    }
+    canEnqueueControl(record, bytes = 0) {
+        return (Number.isSafeInteger(bytes) &&
+            bytes >= 0 &&
+            record.pendingControlOperations < MAX_PENDING_CONTROL_OPERATIONS &&
+            record.pendingControlBytes + bytes <= MAX_PENDING_CONTROL_BYTES);
+    }
+    enqueueControl(record, operation, bytes = 0, force = false) {
+        if (!force && !this.canEnqueueControl(record, bytes)) {
+            return Promise.reject(new Error('terminal control queue is full'));
+        }
+        record.pendingControlOperations += 1;
+        record.pendingControlBytes += bytes;
+        const previous = record.controlTail;
+        const result = previous.then(operation, operation);
+        const tracked = result.finally(() => {
+            record.pendingControlOperations = Math.max(0, record.pendingControlOperations - 1);
+            record.pendingControlBytes = Math.max(0, record.pendingControlBytes - bytes);
+        });
+        const tail = tracked.then(() => undefined, () => undefined);
+        record.controlTail = tail;
+        return tracked;
+    }
 }
 function agentCompletionOutcome(state) {
     if (state === 'done')
@@ -649,6 +1495,20 @@ function agentCompletionOutcome(state) {
         return 'stopped';
     return null;
 }
+function controlOperationAllowed(options) {
+    return controlCallbackAllowed(options.canExecute);
+}
+function controlCallbackAllowed(canExecute) {
+    try {
+        return canExecute?.() !== false;
+    }
+    catch {
+        return false;
+    }
+}
+function addPendingScrollDelta(groups, canExecute, lines) {
+    groups.set(canExecute, (groups.get(canExecute) ?? 0) + lines);
+}
 function agentSessionChanged(previous, current) {
     return previous !== null && current !== null && previous !== current;
 }
@@ -661,6 +1521,11 @@ function normalizeHistoryLimit(value) {
     }
     return Math.min(value, HISTORY_PAGE_MAX_LINES);
 }
+function clampScrollLines(lines) {
+    if (!Number.isFinite(lines))
+        return 0;
+    return Math.max(-240, Math.min(240, Math.trunc(lines)));
+}
 function cloneSummary(summary) {
     return {
         ...summary,
@@ -670,15 +1535,14 @@ function cloneSummary(summary) {
     };
 }
 function activityFromSignals(options) {
-    if (options.agentStatus?.state === 'working') {
+    if (options.busy || options.recentOutput || options.agentStatus?.state === 'working') {
         return 'busy';
     }
     if (options.agentStatus &&
-        options.agentStatus.state !== 'unknown' &&
-        !options.recentOutput) {
+        options.agentStatus.state !== 'unknown') {
         return 'idle';
     }
-    return options.busy || options.recentOutput ? 'busy' : 'idle';
+    return 'idle';
 }
 function agentStatusEquals(left, right) {
     return left?.provider === right?.provider && left?.sessionId === right?.sessionId && left?.state === right?.state;
@@ -705,6 +1569,20 @@ function inferAgentProviderFromCommand(command) {
     }
     return null;
 }
+function isAgentRuntimeWrapperCommand(command) {
+    const base = path.basename(command).toLowerCase();
+    return base === 'node' || base === 'nodejs';
+}
+function expectedAgentProvider(command, existingProvider) {
+    return inferAgentProviderFromCommand(command) ?? (isAgentRuntimeWrapperCommand(command) ? existingProvider ?? null : null);
+}
+function transcriptSourceMatchesForeground(summary, sourceProvider) {
+    if (!summary.currentCommand) {
+        return false;
+    }
+    const expected = expectedAgentProvider(summary.currentCommand, summary.agentStatus?.provider);
+    return expected === null || expected === sourceProvider;
+}
 function terminalEnv() {
     const env = {};
     const allowedKeys = ['HOME', 'LANG', 'LC_ALL', 'LC_CTYPE', 'LOGNAME', 'PATH', 'SHELL', 'TMPDIR', 'USER'];
@@ -739,4 +1617,7 @@ function ensureUtf8TerminalLocale(env) {
 function isUtf8Locale(value) {
     return value !== undefined && /utf-?8/i.test(value);
 }
+function isPromiseLike(value) {
+    return typeof value?.then === 'function';
+}
 //# sourceMappingURL=TerminalManager.js.map