@jingyi0605/codingns4dsh 0.2.0-rc.2 → 0.2.0-rc3

package/data/build/dist/host/terminal/terminal-service.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { debugInfo, debugWarn } from '../../shared/debug.js';
 /**
  * 持久终端生命周期服务。
  *
@@ -10,6 +11,8 @@ export class CodingNsTerminalService {
     runtimes;
     now;
     controllers = new Map();
+    residents = new Map();
+    residentPromises = new Map();
     followers = new Map();
     operations = new Map();
     exitCallbacks = new Map();
@@ -24,6 +27,10 @@ export class CodingNsTerminalService {
             return;
         await this.store.load();
         this.initialized = true;
+        debugInfo('codingns4dsh: terminal service initialized', {
+            recordCount: this.store.list().length,
+            records: this.store.list().map(recordSummary),
+        });
     }
     supportsRuntimeType(runtimeType) {
         return this.runtimes.supports(runtimeType);
@@ -77,21 +84,47 @@ export class CodingNsTerminalService {
         validateTerminalId(input.terminalId);
         validateSize(input.cols, input.rows);
         const identity = { ...input.scope, terminalId: input.terminalId };
+        debugInfo('codingns4dsh: terminal service create start', {
+            identity,
+            runtimeType: input.runtimeType,
+            shellProfileId: input.shell.profileId,
+            cols: input.cols,
+            rows: input.rows,
+        });
         return this.enqueue(identity, async () => {
             const existing = this.store.get(identity);
+            debugInfo('codingns4dsh: terminal service create queued', {
+                identity,
+                existing: existing === undefined ? null : recordSummary(existing),
+            });
             if (existing !== undefined) {
                 if (existing.state === 'closed' || existing.state === 'closing') {
                     throw new TerminalServiceError('TERMINAL_UNAVAILABLE', '终端已关闭，不能复用相同标识');
                 }
                 const runtime = await this.runtimes.inspect(existing);
+                debugInfo('codingns4dsh: terminal service create existing inspect', {
+                    identity,
+                    record: recordSummary(existing),
+                    runtime: runtimeSummary(runtime),
+                });
                 if (runtime.alive) {
                     const running = existing.state === 'running'
                         ? existing
                         : await this.update(existing, { state: 'running', error: '' });
+                    try {
+                        await this.ensureResident(running);
+                    }
+                    catch (error) {
+                        debugWarn('codingns4dsh: terminal resident connection warmup failed', {
+                            identity,
+                            error: errorMessage(error),
+                        });
+                    }
                     return this.info(running);
                 }
-                await this.update(existing, { state: 'lost', error: '持久终端运行时不存在' });
-                throw new TerminalServiceError('TERMINAL_RUNTIME_LOST', '持久终端运行时不存在');
+                // 运行时确实没了：同一个 terminalId 允许重建，这样 Sidebar 标签、标题和
+                // 尺寸都能保留。旧实现只把记录标成 lost 再抛错，用户点"重建终端"永远失败。
+                return this.rebuild(existing, input);
             }
             const timestamp = this.now().toISOString();
             const record = {
@@ -117,20 +150,41 @@ export class CodingNsTerminalService {
                 updatedAt: timestamp,
             };
             await this.store.put(record);
+            debugInfo('codingns4dsh: terminal service record starting', { record: recordSummary(record) });
             try {
                 const runtime = await this.runtimes.create(record);
+                debugInfo('codingns4dsh: terminal service runtime created', {
+                    identity,
+                    runtime: runtimeSummary(runtime),
+                });
                 if (!runtime.alive)
                     throw new Error('backend 创建后未报告存活状态');
                 if (input.onExit !== undefined)
                     this.exitCallbacks.set(identityKey(identity), input.onExit);
                 const running = await this.update(record, { state: 'running', error: '' });
-                if (input.onExit !== undefined)
-                    await this.runtimes.monitor(running, (exitCode) => { void this.markExited(identity, exitCode); });
+                // 常驻连接同时承担自然退出监听。这样普通终端和启动项终端都使用同一
+                // 条 Host 内存连接，浏览器 follow 不再反复创建 backend attach。
+                try {
+                    await this.ensureResident(running);
+                }
+                catch (error) {
+                    debugWarn('codingns4dsh: terminal resident connection warmup failed', {
+                        identity,
+                        error: errorMessage(error),
+                    });
+                }
+                debugInfo('codingns4dsh: terminal service create success', { record: recordSummary(running) });
                 return this.info(running);
             }
             catch (error) {
                 this.exitCallbacks.delete(identityKey(identity));
-                await this.update(record, { state: 'error', error: errorMessage(error) });
+                const message = errorMessage(error);
+                debugWarn('codingns4dsh: terminal service create failed', {
+                    identity,
+                    record: recordSummary(record),
+                    error: message,
+                });
+                await this.update(record, { state: 'error', error: message });
                 throw error;
             }
         });
@@ -140,6 +194,72 @@ export class CodingNsTerminalService {
         this.requireInitialized();
         return this.store.get(identity);
     }
+    /**
+     * 用同一个 terminalId 重建已经丢失的运行时。
+     *
+     * 保留 cwd、标题、shell 与工作区归属，只换一个新的 runtimeSessionKey；旧的
+     * tmux 会话/PTY 已经不存在，先按幂等方式清理一次再创建。
+     */
+    async rebuild(existing, input) {
+        await this.update(existing, { state: 'lost', error: '持久终端运行时不存在' });
+        // 重建会更换 runtimeSessionKey；旧 resident 即使 backend 已经丢失，也不能
+        // 留在内存映射里，否则后面的 ensureResident 会把新终端绑定到旧订阅。
+        await this.releaseResident(identityOfRecord(existing));
+        try {
+            await this.runtimes.terminate(existing);
+        }
+        catch { /* 旧运行时已经不存在 */ }
+        await this.runtimes.detachTerminal(existing);
+        this.exitCallbacks.delete(identityKey(existing));
+        const identity = { ...input.scope, terminalId: existing.terminalId };
+        const timestamp = this.now().toISOString();
+        const record = {
+            ...existing,
+            ...input.scope,
+            runtimeSessionKey: randomUUID(),
+            runtimeType: input.runtimeType,
+            shellPath: input.shell.path,
+            shellProfileId: input.shell.profileId,
+            shellName: input.shell.name,
+            shellArgs: [...input.shell.args],
+            ...(input.commandPath === undefined ? {} : { commandPath: input.commandPath }),
+            ...(input.commandArgs === undefined ? {} : { commandArgs: [...input.commandArgs] }),
+            ...(input.commandEnv === undefined ? {} : { commandEnv: { ...input.commandEnv } }),
+            ...(input.launchProfileId === undefined ? {} : { launchProfileId: input.launchProfileId }),
+            cwd: input.cwd,
+            title: input.title?.trim() || existing.title,
+            cols: input.cols,
+            rows: input.rows,
+            state: 'starting',
+            exitCode: null,
+            error: '',
+            updatedAt: timestamp,
+        };
+        await this.store.put(record);
+        try {
+            const runtime = await this.runtimes.create(record);
+            if (!runtime.alive)
+                throw new Error('backend 重建后未报告存活状态');
+            if (input.onExit !== undefined)
+                this.exitCallbacks.set(identityKey(identity), input.onExit);
+            const running = await this.update(record, { state: 'running', error: '' });
+            try {
+                await this.ensureResident(running);
+            }
+            catch (error) {
+                debugWarn('codingns4dsh: terminal resident connection warmup failed', {
+                    identity,
+                    error: errorMessage(error),
+                });
+            }
+            return this.info(running);
+        }
+        catch (error) {
+            this.exitCallbacks.delete(identityKey(identity));
+            await this.update(record, { state: 'error', error: errorMessage(error) });
+            throw error;
+        }
+    }
     async inspect(identity) {
         const record = this.getRecord(identity);
         if (record === undefined)
@@ -156,6 +276,7 @@ export class CodingNsTerminalService {
                 if (current === undefined || current.state === 'closed')
                     return;
                 if (current.state === 'closing') {
+                    await this.releaseResident(identityOfRecord(current));
                     await this.runtimes.terminate(current);
                     await this.runtimes.detachTerminal(current);
                     await this.update(current, { state: 'closed', exitCode: null, error: '' });
@@ -163,9 +284,25 @@ export class CodingNsTerminalService {
                 }
                 try {
                     const identity = await this.runtimes.inspect(current);
-                    await this.update(current, identity.alive
-                        ? { state: 'running', error: '' }
-                        : { state: 'lost', error: identity.detail ?? '持久终端运行时不存在' });
+                    if (identity.alive) {
+                        await this.update(current, { state: 'running', error: '' });
+                        // 恢复阶段提前建立常驻连接，用户第一次点击终端时直接收到已有状态。
+                        try {
+                            await this.ensureResident(this.store.get(current) ?? current);
+                        }
+                        catch (error) {
+                            debugWarn('codingns4dsh: terminal resident connection restore failed', {
+                                identity: identityOfRecord(current),
+                                error: errorMessage(error),
+                            });
+                        }
+                        return;
+                    }
+                    // 运行时不在了：有真实退出码才算 exited，否则只能报告 lost。
+                    // 少了这一步，DSH 重启后会把"用户已经退出的终端"一直显示成丢失。
+                    await this.update(current, identity.exitCode === undefined || identity.exitCode === null
+                        ? { state: 'lost', exitCode: null, error: identity.detail ?? '持久终端运行时不存在' }
+                        : { state: 'exited', exitCode: identity.exitCode, error: '' });
                 }
                 catch (error) {
                     await this.update(current, { state: 'error', error: errorMessage(error) });
@@ -181,51 +318,84 @@ export class CodingNsTerminalService {
     }
     async *follow(input) {
         const record = this.requireAvailable(input.identity);
+        debugInfo('codingns4dsh: terminal service follow start', {
+            identity: input.identity,
+            attachmentId: input.attachmentId,
+            generation: input.generation,
+            record: recordSummary(record),
+        });
         const key = identityKey(input.identity);
+        // create/recover 通常已经建立 resident；旧记录或连接抖动时在这里补建一次。
+        await this.ensureResident(record);
+        const resident = this.residents.get(key);
+        if (resident === undefined)
+            throw new TerminalServiceError('TERMINAL_RUNTIME_LOST', '终端常驻连接不可用');
         const queue = new TerminalFrameQueue(2 * 1024 * 1024);
         const follower = { attachmentId: input.attachmentId, generation: input.generation, queue };
-        this.addFollower(key, follower);
-        // 无论 backend attach 是否同步吐出恢复画面，wire 的第一帧都必须是 snapshot。
-        queue.pushSnapshot(this.info(record));
-        let attachment;
+        // resident 已经存在时不再等待 backend attach；先从 tmux server 读取完整历史，
+        // 这样第一帧能真正填充 xterm scrollback，而不是只重放当前屏幕。
+        // 如果把它当作 output 增量发送，切换会话或 resident 重连时会把整屏再次追加，
+        // 造成 prompt 重复和 ANSI 内容错位。
+        let snapshot = resident.replay;
         try {
-            attachment = await this.runtimes.attach(record, {
-                identity: input.identity,
-                generation: input.generation,
-                streamId: input.attachmentId,
-                requestedAttachmentId: input.attachmentId,
-                cols: record.cols,
-                rows: record.rows,
-                onData: (data) => queue.pushOutput(data),
-                onExit: (exitCode) => { void this.handleRuntimeExit(input.identity, exitCode, queue); },
-            });
+            const captured = await this.runtimes.captureHistory(record, RESIDENT_HISTORY_LINES);
+            if (captured !== undefined) {
+                resident.replay = captured;
+                snapshot = captured;
+                debugInfo('codingns4dsh: terminal history snapshot ready', {
+                    identity: input.identity,
+                    source: 'runtime-capture',
+                    historyLines: countLines(captured),
+                    historyCharacters: captured.length,
+                });
+            }
+            else {
+                debugInfo('codingns4dsh: terminal history snapshot fallback', {
+                    identity: input.identity,
+                    source: 'resident-replay',
+                    replayCharacters: snapshot.length,
+                });
+            }
         }
         catch (error) {
-            this.removeFollower(key, follower);
-            queue.finish();
-            throw error;
+            debugWarn('codingns4dsh: terminal history capture failed, using resident replay', {
+                identity: input.identity,
+                error: errorMessage(error),
+                replayCharacters: snapshot.length,
+            });
         }
-        this.controllers.set(key, {
+        // 历史读取期间不登记 follower，避免极短竞态把 output 排在 snapshot 之前。
+        snapshot = resident.replay;
+        this.addFollower(key, follower);
+        this.addController(key, input.attachmentId, {
             attachmentId: input.attachmentId,
-            subscriptionId: attachment.subscriptionId,
+            subscriptionId: resident.subscriptionId,
             generation: input.generation,
         });
-        this.broadcastState(input.identity);
-        const abort = () => queue.finish();
-        input.signal.addEventListener('abort', abort, { once: true });
-        if (input.signal.aborted)
-            abort();
+        queue.pushSnapshot(this.info(record, input.attachmentId), snapshot);
+        queue.pushState(this.info(record, input.attachmentId));
         try {
+            debugInfo('codingns4dsh: terminal service follow subscribed', {
+                identity: input.identity,
+                attachmentId: input.attachmentId,
+                residentSubscriptionId: resident.subscriptionId,
+                residentRuntimeAttachmentId: resident.runtimeAttachmentId,
+            });
+            const abort = () => queue.finish();
+            input.signal.addEventListener('abort', abort, { once: true });
+            if (input.signal.aborted)
+                abort();
             yield* queue.read();
+            input.signal.removeEventListener('abort', abort);
         }
         finally {
-            input.signal.removeEventListener('abort', abort);
             this.removeFollower(key, follower);
-            if (this.controllers.get(key)?.subscriptionId === attachment.subscriptionId) {
-                this.controllers.delete(key);
-                this.broadcastState(input.identity);
-            }
-            await this.runtimes.detach(attachment.subscriptionId);
+            this.removeController(key, input.attachmentId);
+            debugInfo('codingns4dsh: terminal service follow unsubscribed', {
+                identity: input.identity,
+                attachmentId: input.attachmentId,
+                residentSubscriptionId: resident.subscriptionId,
+            });
         }
     }
     async write(identity, attachmentId, data) {
@@ -239,6 +409,11 @@ export class CodingNsTerminalService {
         this.requireInitialized();
         await this.enqueue(identity, async () => {
             const record = this.requireAvailable(identity);
+            const resident = this.residents.get(identityKey(identity));
+            if (resident !== undefined) {
+                await this.runtimes.write(resident.subscriptionId, data);
+                return;
+            }
             await this.runtimes.writeSession(record, data);
         });
     }
@@ -263,29 +438,41 @@ export class CodingNsTerminalService {
     }
     async close(identity) {
         this.requireInitialized();
+        debugInfo('codingns4dsh: terminal service close start', { identity });
         await this.enqueue(identity, async () => {
             const record = this.store.get(identity);
-            if (record === undefined || record.state === 'closed')
+            if (record === undefined || record.state === 'closed') {
+                debugInfo('codingns4dsh: terminal service close noop', { identity, record: record === undefined ? null : recordSummary(record) });
                 return;
+            }
             const closing = record.state === 'closing' ? record : await this.update(record, { state: 'closing' });
             this.broadcastState(identity);
+            await this.releaseResident(identity);
             await this.runtimes.terminate(closing);
+            debugInfo('codingns4dsh: terminal service runtime terminated', { identity, record: recordSummary(closing) });
             await this.runtimes.detachTerminal(identity);
             this.controllers.delete(identityKey(identity));
             this.exitCallbacks.delete(identityKey(identity));
             const closed = await this.update(closing, { state: 'closed', exitCode: null, error: '' });
             this.broadcastState(identity, closed);
             this.finishFollowers(identityKey(identity));
+            debugInfo('codingns4dsh: terminal service close success', { identity, record: recordSummary(closed) });
         });
     }
     async detachGeneration(generation) {
+        // 浏览器 attach 已经只是 resident 的订阅，不再拥有 backend attachment；
+        // RuntimeManager 的 generation 清理仍保留，用于兼容旧的 monitor/调用方。
         await this.runtimes.detachGeneration(generation);
         const changed = new Set();
-        for (const [key, binding] of this.controllers) {
-            if (binding.generation !== generation)
-                continue;
-            this.controllers.delete(key);
-            changed.add(key);
+        for (const [key, bindings] of this.controllers) {
+            for (const [attachmentId, binding] of bindings) {
+                if (binding.generation !== generation)
+                    continue;
+                bindings.delete(attachmentId);
+                changed.add(key);
+            }
+            if (bindings.size === 0)
+                this.controllers.delete(key);
         }
         for (const [key, followers] of this.followers) {
             for (const follower of followers) {
@@ -305,13 +492,14 @@ export class CodingNsTerminalService {
                 follower.queue.finish();
         this.followers.clear();
         this.controllers.clear();
+        this.residents.clear();
         this.exitCallbacks.clear();
         await this.runtimes.dispose();
     }
     requireController(identity, attachmentId) {
         this.requireAvailable(identity);
-        const controller = this.controllers.get(identityKey(identity));
-        if (controller?.attachmentId !== attachmentId) {
+        const controller = this.controllers.get(identityKey(identity))?.get(attachmentId);
+        if (controller === undefined) {
             throw new TerminalServiceError('TERMINAL_CONTROL_UNAVAILABLE', '当前 attach 没有终端输入控制权');
         }
         return controller;
@@ -340,34 +528,74 @@ export class CodingNsTerminalService {
             this.broadcastState(identity, failed);
         }
     }
-    async handleRuntimeExit(identity, exitCode, queue) {
+    /**
+     * 浏览器 attach 客户端结束了。
+     *
+     * tmux 客户端在"服务器消失""会话被销毁""只是这次连接断了"时都会退出，退出码
+     * 本身不能证明 shell 结束。因此这里必须回查运行时的真实状态：只有确实拿到
+     * shell 的退出码才算 `exited`，否则只能标记 `lost`，让用户重新连接而不是看到
+     * 一个假的"进程已退出（1）"。
+     */
+    async handleAttachmentExit(identity, exitCode, queue) {
         try {
-            await this.markExited(identity, exitCode);
+            await this.finishRuntime(identity, exitCode);
         }
         finally {
-            // 先发 exited 元数据，再结束 Remote 流；否则官方 Client 会把正常退出误判为 attach 故障。
+            // 先发终态元数据，再结束 Remote 流；否则官方 Client 会把正常退出误判为 attach 故障。
             queue.finish();
         }
     }
-    async markExited(identity, exitCode) {
+    /** 以运行时的实际状态收尾：能确认真实退出码才算 exited，否则是 lost。 */
+    async finishRuntime(identity, exitCode) {
+        debugInfo('codingns4dsh: terminal service runtime exit observed', { identity, callbackExitCode: exitCode });
         await this.enqueue(identity, async () => {
             const record = this.store.get(identity);
             if (record === undefined || record.state !== 'running')
                 return;
-            const exited = await this.update(record, { state: 'exited', exitCode, error: '' });
-            this.broadcastState(identity, exited);
+            let runtime;
+            try {
+                runtime = await this.runtimes.inspect(record);
+            }
+            catch (error) {
+                const failed = await this.update(record, { state: 'error', error: errorMessage(error) });
+                this.broadcastState(identity, failed);
+                return;
+            }
+            debugInfo('codingns4dsh: terminal service runtime exit inspect', {
+                identity,
+                record: recordSummary(record),
+                runtime: runtimeSummary(runtime),
+            });
+            if (runtime.alive)
+                return;
+            const confirmed = runtime.exitCode ?? null;
+            const kind = runtime.exitCode === undefined || runtime.exitCode === null ? 'lost' : 'exited';
+            const finished = kind === 'exited'
+                ? await this.update(record, { state: 'exited', exitCode: confirmed, error: '' })
+                : await this.update(record, {
+                    state: 'lost',
+                    exitCode: null,
+                    error: runtime.detail ?? `持久终端连接中断（客户端退出码 ${exitCode ?? '未知'}）`,
+                });
+            this.broadcastState(identity, finished);
             const callback = this.exitCallbacks.get(identityKey(identity));
             this.exitCallbacks.delete(identityKey(identity));
-            await callback?.(exitCode);
+            await callback?.(confirmed, kind);
+            debugInfo('codingns4dsh: terminal service runtime finalized', {
+                identity,
+                kind,
+                record: recordSummary(finished),
+            });
         });
     }
-    info(record) {
-        const controllerId = this.controllers.get(identityKey(record))?.attachmentId;
+    info(record, controllerId) {
         const state = record.state === 'running' || record.state === 'starting'
             ? 'running'
             : record.state === 'closed' || record.state === 'exited'
                 ? 'exited'
-                : 'failed';
+                : record.state === 'lost'
+                    ? 'lost'
+                    : 'failed';
         return {
             id: record.terminalId,
             title: record.title,
@@ -381,18 +609,210 @@ export class CodingNsTerminalService {
             ...(controllerId === undefined ? {} : { controllerId }),
         };
     }
+    /**
+     * 确保一个终端只有一条 Host backend attachment。
+     *
+     * 这个连接不绑定某个浏览器 generation，直到显式 close 或 Host dispose 才释放。
+     * 多个会话的 follow 都复用同一条连接，避免每次点击都重新启动 tmux client/PTY。
+     */
+    async ensureResident(record) {
+        const key = identityKey(record);
+        const existing = this.residents.get(key);
+        if (existing !== undefined)
+            return existing;
+        const pending = this.residentPromises.get(key);
+        if (pending !== undefined)
+            return pending;
+        const identity = identityOfRecord(record);
+        // 每次 resident 都使用独立 token。旧 backend attachment 的迟到回调不能
+        // 误删同一 terminalId 后面刚重建的新 resident。
+        const generation = `host-resident:${key}:${randomUUID()}`;
+        const requestedAttachmentId = `resident:${record.terminalId}`;
+        // resident 断线重连时，tmux attach 的首批输出是整屏重绘；它可能在
+        // backend.attach 返回后异步到达，不能只依赖 runtime-manager 的 earlyData。
+        // 在短暂启动窗口内先收集，随后以 snapshot 发给已有 follower。
+        const hadFollowers = (this.followers.get(key)?.size ?? 0) > 0;
+        // attach 尚未完成时先无限期收集 earlyData；真正的窗口从 attachment
+        // 建立后开始计算，避免慢机器上首屏在 100ms 后才到达而被误当增量。
+        let bootstrapDeadline = Number.POSITIVE_INFINITY;
+        let bootstrapReplay = '';
+        let replay = '';
+        let task;
+        task = this.runtimes.attach(record, {
+            identity,
+            generation,
+            streamId: requestedAttachmentId,
+            requestedAttachmentId,
+            cols: record.cols,
+            rows: record.rows,
+            onData: (data) => {
+                replay = boundedAppend(replay, data);
+                const resident = this.residents.get(key);
+                if (resident !== undefined)
+                    resident.replay = replay;
+                if (hadFollowers && Date.now() < bootstrapDeadline) {
+                    bootstrapReplay = boundedAppend(bootstrapReplay, data);
+                    return;
+                }
+                this.broadcastOutput(key, data);
+            },
+            onExit: (exitCode) => { void this.handleResidentExit(identity, generation, exitCode); },
+        }).then(async (attachment) => {
+            const resident = {
+                subscriptionId: attachment.subscriptionId,
+                runtimeAttachmentId: attachment.runtimeAttachmentId,
+                generation,
+                replay,
+            };
+            this.residents.set(key, resident);
+            // tmux attach 的原始 ANSI 首屏不含 scrollback；把 server buffer 的纯文本历史
+            // 作为恢复快照，后续 output 仍由常驻连接增量推送。
+            try {
+                const captured = await this.runtimes.captureHistory(record, RESIDENT_HISTORY_LINES);
+                if (captured !== undefined) {
+                    replay = captured;
+                    resident.replay = captured;
+                    debugInfo('codingns4dsh: terminal resident history captured', {
+                        identity,
+                        historyLines: countLines(captured),
+                        historyCharacters: captured.length,
+                    });
+                }
+            }
+            catch (error) {
+                debugWarn('codingns4dsh: terminal resident history capture failed', {
+                    identity,
+                    error: errorMessage(error),
+                });
+            }
+            bootstrapDeadline = Date.now() + RESIDENT_BOOTSTRAP_WINDOW_MS;
+            if (hadFollowers) {
+                // 等待 tmux attach 的初始整屏重绘收齐，再替换已有 xterm 画面。
+                // 新 follow 不走这里，它会直接收到上面的 snapshot。
+                setTimeout(() => {
+                    const current = this.residents.get(key);
+                    if (current?.generation !== generation || bootstrapReplay === '')
+                        return;
+                    const currentRecord = this.store.get(identity);
+                    if (currentRecord === undefined || currentRecord.state !== 'running')
+                        return;
+                    for (const follower of this.followers.get(key) ?? []) {
+                        follower.queue.pushSnapshot(this.info(currentRecord, follower.attachmentId), current.replay);
+                    }
+                    debugInfo('codingns4dsh: terminal resident bootstrap replay promoted to snapshot', {
+                        identity,
+                        generation,
+                        replayCharacters: current.replay.length,
+                    });
+                }, RESIDENT_BOOTSTRAP_WINDOW_MS);
+            }
+            debugInfo('codingns4dsh: terminal resident connection ready', {
+                identity,
+                subscriptionId: resident.subscriptionId,
+                runtimeAttachmentId: resident.runtimeAttachmentId,
+                generation,
+            });
+            return resident;
+        }).finally(() => {
+            if (this.residentPromises.get(key) === task)
+                this.residentPromises.delete(key);
+        });
+        this.residentPromises.set(key, task);
+        return task;
+    }
+    async releaseResident(identity) {
+        const key = identityKey(identity);
+        const pending = this.residentPromises.get(key);
+        if (pending !== undefined) {
+            try {
+                await pending;
+            }
+            catch { /* 创建失败时没有可释放的连接 */ }
+        }
+        const resident = this.residents.get(key);
+        if (resident === undefined)
+            return;
+        this.residents.delete(key);
+        await this.runtimes.detach(resident.subscriptionId);
+        debugInfo('codingns4dsh: terminal resident connection released', {
+            identity,
+            subscriptionId: resident.subscriptionId,
+            runtimeAttachmentId: resident.runtimeAttachmentId,
+        });
+    }
+    async handleResidentExit(identity, generation, exitCode) {
+        const key = identityKey(identity);
+        const resident = this.residents.get(key);
+        if (resident === undefined || resident.generation !== generation) {
+            debugInfo('codingns4dsh: terminal resident stale exit ignored', {
+                identity,
+                generation,
+                currentGeneration: resident?.generation ?? null,
+                exitCode,
+            });
+            return;
+        }
+        this.residents.delete(key);
+        // 这条 backend 连接已经不能继续向浏览器送数据。先撤销输入控制权；
+        // 是否结束订阅要等 finishRuntime 判断出“连接断开”还是“Shell 退出”之后决定。
+        this.controllers.delete(key);
+        try {
+            await this.runtimes.detach(resident.subscriptionId);
+        }
+        catch { /* backend 已经回收 attachment */ }
+        await this.finishRuntime(identity, exitCode);
+        const current = this.store.get(identity);
+        if (current?.state === 'running') {
+            // tmux client 断线不等于 Shell 结束。连接层恢复时保留已有 follower，
+            // 重新建立 resident；真正退出则由 finishRuntime 收敛并结束所有订阅。
+            try {
+                const nextResident = await this.ensureResident(current);
+                // resident 重建后 subscriptionId 已变化，原 follower 仍然有效，必须
+                // 重新绑定它们的输入与 resize 控制权。
+                for (const follower of this.followers.get(key) ?? []) {
+                    this.addController(key, follower.attachmentId, {
+                        attachmentId: follower.attachmentId,
+                        subscriptionId: nextResident.subscriptionId,
+                        generation: follower.generation,
+                    });
+                }
+                debugInfo('codingns4dsh: terminal resident connection reattached', {
+                    identity,
+                    subscriptionId: nextResident.subscriptionId,
+                });
+                return;
+            }
+            catch (error) {
+                debugWarn('codingns4dsh: terminal resident connection reattach failed', {
+                    identity,
+                    error: errorMessage(error),
+                });
+            }
+        }
+        // finishRuntime 已经把 exited/lost 状态推入队列，队列此时才可结束，
+        // 保证 Client 先收到终态再看到流结束。
+        this.finishFollowers(key);
+    }
     async update(record, patch) {
         const next = await this.store.patch(record, { ...patch, updatedAt: this.now().toISOString() });
         if (next === undefined)
             throw new Error('终端记录在更新期间消失');
+        if (record.state !== next.state || patch.error !== undefined || patch.exitCode !== undefined) {
+            debugInfo('codingns4dsh: terminal service state update', {
+                identity: identityOfRecord(record),
+                before: recordSummary(record),
+                patch,
+                after: recordSummary(next),
+            });
+        }
         return next;
     }
     broadcastState(identity, record = this.store.get(identity)) {
         if (record === undefined)
             return;
-        const info = this.info(record);
-        for (const follower of this.followers.get(identityKey(identity)) ?? [])
-            follower.queue.pushState(info);
+        for (const follower of this.followers.get(identityKey(identity)) ?? []) {
+            follower.queue.pushState(this.info(record, follower.attachmentId));
+        }
     }
     broadcastStateByKey(key) {
         const record = this.store.list().find((candidate) => identityKey(candidate) === key);
@@ -407,6 +827,26 @@ export class CodingNsTerminalService {
         }
         followers.add(follower);
     }
+    addController(key, attachmentId, binding) {
+        let bindings = this.controllers.get(key);
+        if (bindings === undefined) {
+            bindings = new Map();
+            this.controllers.set(key, bindings);
+        }
+        bindings.set(attachmentId, binding);
+    }
+    removeController(key, attachmentId) {
+        const bindings = this.controllers.get(key);
+        if (bindings === undefined)
+            return;
+        bindings.delete(attachmentId);
+        if (bindings.size === 0)
+            this.controllers.delete(key);
+    }
+    broadcastOutput(key, data) {
+        for (const follower of this.followers.get(key) ?? [])
+            follower.queue.pushOutput(data);
+    }
     removeFollower(key, follower) {
         const followers = this.followers.get(key);
         followers?.delete(follower);
@@ -453,11 +893,14 @@ class TerminalFrameQueue {
     constructor(maxBytes) {
         this.maxBytes = maxBytes;
     }
-    pushSnapshot(info) {
-        this.push({ type: 'snapshot', sequence: this.sequence, screen: '', info });
+    pushSnapshot(info, screen = '') {
+        // tmux capture-pane 返回纯文本 LF；xterm 的真实 PTY 模式不会自动把 LF
+        // 转成 CRLF，必须在 wire 边界补回 CR，否则历史行会逐行继承上一行的列位置。
+        this.push({ type: 'snapshot', sequence: this.sequence, screen: normalizeSnapshotLineEndings(screen), info });
     }
     pushOutput(data) {
         this.sequence += 1;
+        // 增量 PTY 输出保留原始 VT 语义；只有 capture-pane 的纯文本快照需要补 CR。
         this.push({ type: 'output', sequence: this.sequence, data });
     }
     pushState(info) {
@@ -515,6 +958,33 @@ function shellInfo(record) {
 function identityKey(identity) {
     return JSON.stringify([identity.hostId, identity.workspaceId, identity.terminalId]);
 }
+function identityOfRecord(record) {
+    return {
+        hostId: record.hostId,
+        workspaceId: record.workspaceId,
+        terminalId: record.terminalId,
+    };
+}
+function recordSummary(record) {
+    return {
+        ...identityOfRecord(record),
+        dshSessionId: record.dshSessionId ?? null,
+        runtimeSessionKey: record.runtimeSessionKey,
+        runtimeType: record.runtimeType,
+        state: record.state,
+        exitCode: record.exitCode,
+        error: record.error || null,
+    };
+}
+function runtimeSummary(runtime) {
+    return {
+        alive: runtime.alive,
+        runtimePid: runtime.runtimePid ?? null,
+        shellPid: runtime.shellPid ?? null,
+        exitCode: runtime.exitCode ?? null,
+        detail: runtime.detail ?? null,
+    };
+}
 function validateTerminalId(id) {
     if (!/^[\w-]{1,128}$/u.test(id))
         throw new TypeError('终端标识无效');
@@ -527,6 +997,26 @@ function validateSize(cols, rows) {
 function frameBytes(frame) {
     return new TextEncoder().encode(JSON.stringify(frame)).byteLength;
 }
+function normalizeSnapshotLineEndings(value) {
+    return value.replace(/\r?\n/gu, '\r\n');
+}
+/** 常驻连接只保留有限的原始输出，避免长期运行终端无限增长。 */
+const MAX_RESIDENT_REPLAY_CHARACTERS = 1024 * 1024;
+/** tmux attach 的首屏通常在一个很短的窗口内分片送达。 */
+const RESIDENT_BOOTSTRAP_WINDOW_MS = 100;
+/** 初次恢复读取的 tmux 历史行数；xterm 会再按自身 scrollback 上限裁剪。 */
+const RESIDENT_HISTORY_LINES = 2000;
+function countLines(value) {
+    if (value.length === 0)
+        return 0;
+    return value.split('\n').length;
+}
+function boundedAppend(current, data) {
+    const combined = current + data;
+    return combined.length <= MAX_RESIDENT_REPLAY_CHARACTERS
+        ? combined
+        : combined.slice(-MAX_RESIDENT_REPLAY_CHARACTERS);
+}
 function untilAborted(signal) {
     if (signal.aborted)
         return Promise.resolve();