@hyzyn/dsh-tty 0.2.0 → 0.5.0

package/lib/index.js

@@ -1,11 +1,22 @@
 import z from '@deepseek-ai/schemastery';
 import { randomUUID } from 'node:crypto';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { PassThrough } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
 import WebSocket, { WebSocketServer } from 'ws';
+// @xterm/headless 是 CJS 包：ESM 具名导入在 Node 运行时会炸（Named export not
+// found），必须默认导入后取 Terminal；类型用 InstanceType 别名保持同名可用
+import xtermHeadless from '@xterm/headless';
+const HeadlessTerminal = xtermHeadless.Terminal;
 import { definePlugin } from '@hyzyn/dsh-kit';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { spawnSsh, sshTarget } from './ssh.js';
+import { spawnSsh, sshTarget, expandHome } from './ssh.js';
+import { buildShellSpawn } from './shell-integration.js';
+import { parseSshConfig } from './ssh-config.js';
+import { parseKnownHosts } from './known-hosts.js';
+import { TunnelManager } from './tunnels.js';
 const SSH_HOST_SCHEMA = z.object({
     name: z.string(),
     host: z.string(),
@@ -15,6 +26,23 @@ const SSH_HOST_SCHEMA = z.object({
     keyPath: z.string().default(''),
     passphrase: z.string().default(''),
     password: z.string().default(''),
+    agentForward: z.boolean().default(false),
+});
+const HOST_KEY_SCHEMA = z.object({
+    host: z.string(),
+    port: z.natural().max(65535).default(22),
+    fingerprint: z.string(),
+});
+const TUNNEL_SCHEMA = z.object({
+    name: z.string(),
+    bookName: z.string(),
+    direction: z.union([z.const('local'), z.const('remote')]).default('local'),
+    localPort: z.natural().max(65535).default(0),
+    remoteHost: z.string().default(''),
+    remotePort: z.natural().max(65535).default(0),
+    localTargetHost: z.string().default(''),
+    localTargetPort: z.natural().max(65535).default(0),
+    enabled: z.boolean().default(true),
 });
 /** 与「设置 → 插件 → 终端面板」卡片表单对齐的 schema。 */
 const TTY_SETTINGS_SCHEMA = z.object({
@@ -25,58 +53,112 @@ const TTY_SETTINGS_SCHEMA = z.object({
     term: z.string().default('xterm-256color'),
     colorTerm: z.string().default('truecolor'),
     cwd: z.string().default(''),
+    reconnectGraceSec: z.natural().max(3600).default(120),
     sshHosts: z.array(SSH_HOST_SCHEMA).default([]),
+    hostKeys: z.array(HOST_KEY_SCHEMA).default([]),
+    tunnels: z.array(TUNNEL_SCHEMA).default([]),
+    shellIntegration: z.boolean().default(true),
 });
 /* ------------------------------------------------------------------ *
  * 常量
  * ------------------------------------------------------------------ */
 const WS_PATH = '/api/dsh-tty/ws';
 const DEFAULT_MAX_SESSIONS = 4;
+/** 断线保活默认秒数（reconnectGraceSec；0 = 旧行为，断开立即结束会话）。 */
+const DEFAULT_RECONNECT_GRACE_SEC = 120;
 /** 下行背压阈值（ws.bufferedAmount 字节）。 */
 const BACKPRESSURE_HIGH = 512 * 1024;
 const BACKPRESSURE_LOW = 128 * 1024;
 const SID_RE = /^[A-Za-z0-9_-]{1,64}$/;
 const BUFFER_CAP = 256 * 1024;
-const TTY_GUIDANCE = '本机已安装 dsh-tty 插件（终端面板）：Web GUI 侧边栏的「终端」入口可打开交互终端（xterm.js + PTY），可运行任意命令与 TUI 程序（vim/htop 等），支持多标签页；新标签默认在当前会话工作目录打开，工作目录可随当前会话切换。标签栏「+」菜单还能开 SSH 标签页（ssh2 原生连接，连接簿在设置卡片维护），像本地终端一样操作远程主机。长驻进程（dev server、watch、交互式程序）应引导用户到终端面板里运行，不要在 bash 工具里挂起等待；用户提到「开个终端 / 在终端里跑 / SSH 到某台机器」时引导其打开该面板。agent 侧也有配套工具：tty_list 列出活跃终端会话（含 SSH 会话的 target），tty_capture 读取会话近期输出（可查看 dev server/NPM 日志），tty_send 向会话发送按键——操作会实时显示在用户终端里。';
-/** 本地 PTY 包装成 TermHandle（resize/kill 仍是透传 node-pty 的内部耦合）。 */
+/** TERM/COLORTERM 白名单：防止值里的引号破坏 -c 包装层命令（shellArgv 单引号包裹）。 */
+const TERM_RE = /^[A-Za-z0-9_.+-]+$/;
+/** 孤儿会话回收器的扫描间隔。 */
+const REAPER_INTERVAL_MS = 10_000;
+const TTY_GUIDANCE = '本机已安装 dsh-tty 插件（终端面板）：Web GUI 侧边栏的「终端」入口可打开交互终端（xterm.js + PTY），可运行任意命令与 TUI 程序（vim/htop 等），支持多标签页与断线自动重连（刷新页面/网络抖动后会话保活并恢复现场）；新标签默认在当前会话工作目录打开。标签栏「+」菜单还能开 SSH 标签页（ssh2 原生连接，连接簿在设置卡片维护，支持 agent forwarding 与主机指纹 TOFU 钉扎），像本地终端一样操作远程主机。长驻进程（dev server、watch、交互式程序）应引导用户到终端面板里运行，不要在 bash 工具里挂起等待；用户提到「开个终端 / 在终端里跑 / SSH 到某台机器」时引导其打开该面板。agent 侧配套工具：tty_list 列出活跃终端会话（含 SSH 的 target 与实时 cwd），tty_capture 读取近期输出（默认清洗 ANSI；last:true 拿「上一条命令」的输出+退出码），tty_screen 读取当前可见屏幕（可读懂 vim/htop 等 TUI），tty_expect 用正则等待输出中的就绪信号（如 dev server URL、构建完成），tty_send 发送按键，tunnel_list 列出端口转发隧道状态——操作会实时显示在用户终端里。端口转发：连接簿条目可配本地/远程隧道（如把远程数据库映射到本地端口），宿主自动保活重连，用户提到「转发端口 / 访问远程库」时引导其到终端面板设置卡片配置。推荐流程：tty_send 启动长任务 → tty_expect 等就绪标记 → tty_capture{last:true} 拿结果。';
+/** 本地 PTY 包装成 TermHandle（resize/kill 仍是透传 node-pty 的内部耦合；防御性降级）。 */
 function wrapLocalPty(handle) {
+    let resizeWarned = false;
     return {
         kind: 'local',
         pid: handle.pid,
         output: handle.output,
         done: handle.done,
         write: (data) => handle.write(data),
-        resize: (cols, rows) => handle.terminal.resize(cols, rows),
+        resize: (cols, rows) => {
+            try {
+                handle.terminal?.resize?.(cols, rows);
+            }
+            catch (error) {
+                // DSH 升级若改内部结构，降级为固定尺寸而不是每帧抛错
+                if (!resizeWarned) {
+                    resizeWarned = true;
+                    console.warn('[dsh-tty] resize 透传失败（DSH 内部结构可能已变化，退化为固定尺寸）: ' + String(error?.message ?? error));
+                }
+            }
+        },
         terminate: () => handle.terminate(),
-        forceKill: () => handle.terminal.kill('SIGKILL'),
+        forceKill: () => {
+            try {
+                handle.terminal?.kill?.('SIGKILL');
+            }
+            catch {
+                /* 已退出 */
+            }
+        },
     };
 }
+/** TERM/COLORTERM 值白名单校验：不合法回退 fallback（防止破坏 -c 包装层）。 */
+function sanitizeTermValue(value, fallback) {
+    const trimmed = value.trim();
+    return TERM_RE.test(trimmed) ? trimmed : fallback;
+}
 /** 可热更新的运行时配置（settings/updated 动态应用）。 */
 class LiveConfig {
     shell;
     term;
     colorTerm;
     cwd;
+    /** 异常断开后会话保活毫秒数（0 = 立即结束）。 */
+    reconnectGraceMs;
     sshHosts;
+    hostKeys;
+    /** 是否注入 OSC 133/7 shell 集成。 */
+    shellIntegration;
+    /** 端口转发隧道规格。 */
+    tunnels;
     constructor(init) {
         this.shell = init.shell;
-        this.term = init.term;
-        this.colorTerm = init.colorTerm;
+        this.term = sanitizeTermValue(init.term, 'xterm-256color');
+        this.colorTerm = sanitizeTermValue(init.colorTerm, 'truecolor');
         this.cwd = init.cwd;
+        this.reconnectGraceMs = Math.max(0, Math.min(3600, init.reconnectGraceSec)) * 1000;
         this.sshHosts = init.sshHosts ?? [];
+        this.hostKeys = init.hostKeys ?? [];
+        this.shellIntegration = init.shellIntegration;
+        this.tunnels = init.tunnels ?? [];
     }
-    /** 合并部分更新；空字符串/undefined 保持原值；sshHosts 传数组即整体替换。 */
+    /** 合并部分更新；空字符串/undefined 保持原值；sshHosts/hostKeys/tunnels 传数组即整体替换。 */
     apply(partial) {
         if (typeof partial.shell === 'string' && partial.shell.trim() !== '')
             this.shell = partial.shell.trim();
         if (typeof partial.term === 'string' && partial.term.trim() !== '')
-            this.term = partial.term.trim();
+            this.term = sanitizeTermValue(partial.term, this.term);
         if (typeof partial.colorTerm === 'string' && partial.colorTerm.trim() !== '')
-            this.colorTerm = partial.colorTerm.trim();
+            this.colorTerm = sanitizeTermValue(partial.colorTerm, this.colorTerm);
         if (typeof partial.cwd === 'string' && partial.cwd.trim() !== '')
             this.cwd = partial.cwd.trim();
+        if (typeof partial.reconnectGraceSec === 'number' && Number.isInteger(partial.reconnectGraceSec) && partial.reconnectGraceSec >= 0 && partial.reconnectGraceSec <= 3600) {
+            this.reconnectGraceMs = partial.reconnectGraceSec * 1000;
+        }
         if (Array.isArray(partial.sshHosts))
             this.sshHosts = partial.sshHosts;
+        if (Array.isArray(partial.hostKeys))
+            this.hostKeys = partial.hostKeys;
+        if (typeof partial.shellIntegration === 'boolean')
+            this.shellIntegration = partial.shellIntegration;
+        if (Array.isArray(partial.tunnels))
+            this.tunnels = partial.tunnels;
     }
     findSshHost(name) {
         return this.sshHosts.find((entry) => entry.name === name);
@@ -99,18 +181,192 @@ async function forceKill(handle) {
         }
     }
 }
-/**
- * shell argv。node-pty 的 name 优先于 env.TERM，而 DSH 硬编码 name:"dumb"，
- * 只能在 exec 真正的 shell 之前 export（M0 A2 实测结论）。
- */
-function shellArgv(shell, term, colorTerm) {
-    return [shell, '-c', `export TERM='${term}'; export COLORTERM='${colorTerm}'; exec "${shell}"`];
-}
 function send(ws, msg) {
-    if (ws.readyState !== WebSocket.OPEN)
+    if (ws === null || ws.readyState !== WebSocket.OPEN)
         return;
     ws.send(JSON.stringify(msg));
 }
+/**
+ * tty_capture 的默认清洗：剥离 OSC/CSI/杂项转义序列，并把同行内 \r 覆盖
+ * 收敛为最后一次覆盖结果（进度条不再刷屏）。逐行近似，不追求完整 VT 语义
+ * （要完整画面用 tty_screen / xterm-headless 虚拟屏）。
+ */
+function cleanAnsiTail(raw) {
+    const withoutOsc = raw.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '');
+    const withoutCsi = withoutOsc.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+    const withoutEsc = withoutCsi.replace(/\x1b[@-Z\\-_]/g, '');
+    // 先把「行尾 \r\n」（zsh 行结束常为 \r\r\n）归一成 \n，再按同行覆盖处理
+    // 剩余孤立的 \r —— 否则回显/输出行会被误判为覆盖而整行抹掉
+    const normalized = withoutEsc.replace(/\r+\n/g, '\n');
+    return normalized.split('\n').map((line) => {
+        const idx = line.lastIndexOf('\r');
+        return idx === -1 ? line : line.slice(idx + 1);
+    }).join('\n');
+}
+/** OSC 133 命令标记帧：\x1b]133;<A|B|D>[;<exit>](BEL|ST)。 */
+const OSC133_RE = /\x1b\]133;([ABDC])(?:;(\d+))?(?:\x07|\x1b\\)/g;
+/** OSC 7 cwd 上报帧：\x1b]7;file://<host><path>(BEL|ST)。 */
+const OSC7_RE = /\x1b\]7;([^\x07\x1b]*)(?:\x07|\x1b\\)/g;
+/** 单条命令输出捕获上限（环形，超出丢头部）。 */
+const COMMAND_CAP = 256 * 1024;
+/** data 帧合并窗口（毫秒）：窗口内的 PTY chunk 合成一帧，显著降帧/降 CPU。 */
+const FLUSH_INTERVAL_MS = 12;
+/** 待发输出超过该字符数时跳过窗口立即冲刷（防超长输出无限延迟）。 */
+const FLUSH_SIZE_CHARS = 64 * 1024;
+function createShellState() {
+    return { carry: '', inCommand: false, cmdBuffer: '', lastCommand: null };
+}
+/** OSC 7 body（file://host/path）→ 解码后的路径；解析失败返回 undefined。 */
+function osc7Path(body) {
+    try {
+        const url = new URL(body);
+        if (url.protocol !== 'file:')
+            return undefined;
+        const decoded = decodeURIComponent(url.pathname);
+        return decoded !== '' ? decoded : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 把一块输出喂进 shell 集成解析（cwd 跟随 + 命令边界捕获）。
+ * 残包处理：尾部若有未闭合的 OSC 序列（lastIndexOf('\x1b]') 起无终结符），
+ * 扣回 carry 等下一块拼齐；扣留部分不进命令捕获，避免半截序列混入。
+ * 命令捕获按「标记之间的文本段」累积——B、输出、D 常在同一 chunk 到达，
+ * 先处理段再翻转状态，才能把 B..D 之间的输出完整收进 lastCommand。
+ */
+function feedShellIntegration(session, text) {
+    const state = session.shellState;
+    let data = state.carry + text;
+    state.carry = '';
+    const lastOpen = data.lastIndexOf('\x1b]');
+    if (lastOpen !== -1) {
+        const tail = data.slice(lastOpen);
+        if (!/\x07|\x1b\\/.test(tail)) {
+            if (tail.length <= 512) {
+                state.carry = tail;
+                data = data.slice(0, lastOpen);
+            }
+            // 超过 512B 仍不闭合视为垃圾：放弃扣留，整块照常处理
+        }
+    }
+    for (const match of data.matchAll(OSC7_RE)) {
+        const path = osc7Path(match[1]);
+        if (path !== undefined)
+            session.cwd = path;
+    }
+    OSC133_RE.lastIndex = 0;
+    let cursor = 0;
+    for (const match of data.matchAll(OSC133_RE)) {
+        const segment = data.slice(cursor, match.index).replace(OSC7_RE, '');
+        if (state.inCommand && segment !== '') {
+            state.cmdBuffer = (state.cmdBuffer + segment).slice(-COMMAND_CAP);
+        }
+        const kind = match[1];
+        if (kind === 'B') {
+            state.inCommand = true;
+            state.cmdBuffer = '';
+        }
+        else if (kind === 'D') {
+            if (state.inCommand) {
+                const exitCode = match[2] !== undefined ? Number(match[2]) : null;
+                state.lastCommand = {
+                    output: state.cmdBuffer.slice(-COMMAND_CAP),
+                    exitCode: exitCode !== null && Number.isFinite(exitCode) ? exitCode : null,
+                    endedAt: Date.now(),
+                };
+                state.inCommand = false;
+                state.cmdBuffer = '';
+            }
+        }
+        // A（prompt 开始）无需记录
+        cursor = match.index + match[0].length;
+    }
+    if (state.inCommand) {
+        const rest = data.slice(cursor).replace(OSC7_RE, '');
+        if (rest !== '')
+            state.cmdBuffer = (state.cmdBuffer + rest).slice(-COMMAND_CAP);
+    }
+}
+/** 宽松清洗一份 tunnels 输入；输入不是数组时返回 undefined（表示「未提供，保持原值」）。 */
+function sanitizeTunnels(input) {
+    if (!Array.isArray(input))
+        return undefined;
+    const out = [];
+    for (const item of input) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const raw = item;
+        if (typeof raw.name !== 'string' || raw.name.trim() === '')
+            continue;
+        if (typeof raw.bookName !== 'string' || raw.bookName.trim() === '')
+            continue;
+        const num = (value) => {
+            const n = Number(value);
+            return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : 0;
+        };
+        out.push({
+            name: raw.name.trim(),
+            bookName: raw.bookName.trim(),
+            direction: raw.direction === 'remote' ? 'remote' : 'local',
+            localPort: num(raw.localPort),
+            remoteHost: typeof raw.remoteHost === 'string' ? raw.remoteHost.trim() : '',
+            remotePort: num(raw.remotePort),
+            localTargetHost: typeof raw.localTargetHost === 'string' ? raw.localTargetHost.trim() : '',
+            localTargetPort: num(raw.localTargetPort),
+            enabled: raw.enabled !== false,
+        });
+    }
+    return out;
+}
+/** 严格校验 tunnels（HTTP POST 路径）；bookNames 为同次提交（或现有）的连接簿名字集合。 */
+function validateTunnels(input, bookNames) {
+    if (!Array.isArray(input))
+        return { error: 'tunnels 必须是数组' };
+    const names = new Set();
+    for (const item of input) {
+        if (typeof item !== 'object' || item === null)
+            return { error: 'tunnels 条目必须是对象' };
+        const raw = item;
+        if (typeof raw.name !== 'string' || raw.name.trim() === '')
+            return { error: 'tunnels.name 必须是非空字符串' };
+        const name = raw.name.trim();
+        if (names.has(name))
+            return { error: `tunnels.name 重复: ${name}` };
+        names.add(name);
+        if (typeof raw.bookName !== 'string' || raw.bookName.trim() === '')
+            return { error: `tunnels「${name}」bookName 必须是非空字符串` };
+        if (!bookNames.has(raw.bookName.trim()))
+            return { error: `tunnels「${name}」引用的连接簿条目不存在: ${String(raw.bookName)}` };
+        const direction = raw.direction === 'remote' ? 'remote' : 'local';
+        const intIn = (value) => {
+            const n = Number(value);
+            return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : null;
+        };
+        if (direction === 'local') {
+            if (intIn(raw.localPort) === null)
+                return { error: `tunnels「${name}」local 方向需要 localPort（1~65535）` };
+            if (typeof raw.remoteHost !== 'string' || raw.remoteHost.trim() === '')
+                return { error: `tunnels「${name}」local 方向需要 remoteHost` };
+            if (intIn(raw.remotePort) === null)
+                return { error: `tunnels「${name}」local 方向需要 remotePort（1~65535）` };
+        }
+        else {
+            if (intIn(raw.remotePort) === null)
+                return { error: `tunnels「${name}」remote 方向需要 remotePort（服务端监听端口 1~65535）` };
+            if (intIn(raw.localTargetPort) === null)
+                return { error: `tunnels「${name}」remote 方向需要 localTargetPort（1~65535）` };
+            if (raw.remoteHost !== undefined && typeof raw.remoteHost !== 'string')
+                return { error: `tunnels「${name}」remoteHost 必须是字符串` };
+            if (raw.localTargetHost !== undefined && typeof raw.localTargetHost !== 'string')
+                return { error: `tunnels「${name}」localTargetHost 必须是字符串` };
+        }
+        if (raw.enabled !== undefined && typeof raw.enabled !== 'boolean')
+            return { error: `tunnels「${name}」enabled 必须是布尔值` };
+    }
+    return { tunnels: sanitizeTunnels(input) };
+}
 /**
  * 宽松清洗一份 sshHosts 输入（settings 存储/热更新事件路径）：
  * 不合法条目直接丢弃；输入不是数组时返回 undefined（表示「未提供，保持原值」）。
@@ -139,6 +395,7 @@ function sanitizeSshHosts(input) {
             keyPath: typeof raw.keyPath === 'string' ? raw.keyPath : '',
             passphrase: typeof raw.passphrase === 'string' ? raw.passphrase : '',
             password: typeof raw.password === 'string' ? raw.password : '',
+            agentForward: raw.agentForward === true,
         });
     }
     return out;
@@ -171,12 +428,86 @@ function validateSshHosts(input) {
             if (raw[key] !== undefined && typeof raw[key] !== 'string')
                 return { error: `sshHosts.${key} 必须是字符串` };
         }
+        if (raw.agentForward !== undefined && typeof raw.agentForward !== 'boolean') {
+            return { error: 'sshHosts.agentForward 必须是布尔值' };
+        }
         if ((raw.auth === 'key') && (typeof raw.keyPath !== 'string' || raw.keyPath.trim() === '')) {
             return { error: `sshHosts「${String(raw.name)}」auth=key 需要 keyPath` };
         }
     }
     return { hosts: sanitizeSshHosts(input) };
 }
+/** 宽松清洗一份 hostKeys 输入；输入不是数组时返回 undefined（表示「未提供，保持原值」）。 */
+function sanitizeHostKeys(input) {
+    if (!Array.isArray(input))
+        return undefined;
+    const out = [];
+    for (const item of input) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const raw = item;
+        if (typeof raw.host !== 'string' || raw.host.trim() === '')
+            continue;
+        if (typeof raw.fingerprint !== 'string' || raw.fingerprint.trim() === '' || raw.fingerprint.length > 256)
+            continue;
+        const port = Number(raw.port);
+        out.push({
+            host: raw.host.trim().toLowerCase(),
+            port: Number.isInteger(port) && port >= 1 && port <= 65535 ? port : 22,
+            fingerprint: raw.fingerprint.trim(),
+        });
+    }
+    return out;
+}
+/** 严格校验一份 hostKeys 输入（HTTP POST 路径）；返回错误信息或清洗后的数组。 */
+function validateHostKeys(input) {
+    if (!Array.isArray(input))
+        return { error: 'hostKeys 必须是数组' };
+    const seen = new Set();
+    for (const item of input) {
+        if (typeof item !== 'object' || item === null)
+            return { error: 'hostKeys 条目必须是对象' };
+        const raw = item;
+        if (typeof raw.host !== 'string' || raw.host.trim() === '')
+            return { error: 'hostKeys.host 必须是非空字符串' };
+        if (typeof raw.fingerprint !== 'string' || raw.fingerprint.trim() === '')
+            return { error: 'hostKeys.fingerprint 必须是非空字符串' };
+        const port = Number(raw.port ?? 22);
+        if (!Number.isInteger(port) || port < 1 || port > 65535)
+            return { error: 'hostKeys.port 必须是 1~65535 的整数' };
+        const key = `${raw.host.trim().toLowerCase()}:${port}`;
+        if (seen.has(key))
+            return { error: `hostKeys 主机重复: ${key}` };
+        seen.add(key);
+    }
+    return { keys: sanitizeHostKeys(input) };
+}
+/**
+ * TOFU 主机指纹存储：get/record 面向 spawnSsh 的 hostVerifier；
+ * record 时经 persist 回调写入 settings（宿主重启后钉扎仍在）。
+ */
+class HostKeyStore {
+    live;
+    persist;
+    constructor(live, persist) {
+        this.live = live;
+        this.persist = persist;
+    }
+    key(host, port) {
+        return `${host.trim().toLowerCase()}:${port}`;
+    }
+    get(host, port) {
+        const key = this.key(host, port);
+        return this.live.hostKeys.find((record) => `${record.host}:${record.port}` === key)?.fingerprint;
+    }
+    record(host, port, fingerprint) {
+        const key = this.key(host, port);
+        const next = this.live.hostKeys.filter((record) => `${record.host}:${record.port}` !== key);
+        next.push({ host: host.trim().toLowerCase(), port, fingerprint });
+        this.live.hostKeys = next;
+        this.persist(next);
+    }
+}
 /** upgrade 路由的 loopback 信任围栏（与 dsh-mcp 的 HTTP 围栏同思路，socket 版）。 */
 function isLoopbackUpgrade(req) {
     const address = req.socket.remoteAddress;
@@ -237,24 +568,69 @@ class SessionManager {
     get(id) {
         return this.sessions.get(id);
     }
-    /** agent 工具用的只读快照（SSH 会话无本地 pid，该字段省略）。 */
+    /** 会话的只读快照（SSH 会话无本地 pid，该字段省略）。 */
+    snapshotOf(session) {
+        const base = {
+            sid: session.id,
+            cwd: session.cwd,
+            kind: session.kind,
+            target: session.target,
+            startedAt: session.startedAt,
+            lastOutputAt: session.lastOutputAt,
+        };
+        return session.handle.pid === null ? base : { ...base, pid: session.handle.pid };
+    }
+    /** agent 工具用的只读快照。 */
     list() {
-        return [...this.sessions.values()].map((session) => {
-            const base = {
-                sid: session.id,
-                cwd: session.cwd,
-                kind: session.kind,
-                target: session.target,
-                startedAt: session.startedAt,
-                lastOutputAt: session.lastOutputAt,
-            };
-            return session.handle.pid === null ? base : { ...base, pid: session.handle.pid };
-        });
+        return [...this.sessions.values()].map((session) => this.snapshotOf(session));
+    }
+    /** sessions 帧用：额外带 attachable（孤儿且未关闭的会话可被新连接 attach）。 */
+    listForAttach() {
+        return [...this.sessions.values()].map((session) => ({
+            ...this.snapshotOf(session),
+            attachable: session.ws === null && !session.closed,
+        }));
+    }
+    /** 同步退役：移出全局表 + 释放虚拟屏（幂等，不杀进程）。 */
+    retire(session) {
+        session.closed = true;
+        this.sessions.delete(session.id);
+        try {
+            session.screen?.dispose();
+        }
+        catch {
+            /* 已释放 */
+        }
+    }
+    /** 释放并销毁会话：退役 + 树级终止（等待 terminate 完成，最慢 ~20s）。 */
+    async destroy(session) {
+        this.retire(session);
+        await forceKill(session.handle);
+    }
+    /** 回收超过保活期的孤儿会话（回收器定时调用；graceMs<=0 时不动作）。 */
+    async reapOrphans(graceMs) {
+        if (graceMs <= 0)
+            return;
+        const now = Date.now();
+        for (const session of [...this.sessions.values()]) {
+            if (session.orphanedAt !== null && now - session.orphanedAt >= graceMs) {
+                void this.destroy(session); // 后台收尾：terminate 最慢可达 ~20s，不阻塞回收器
+            }
+        }
     }
     async disposeAll() {
         const all = [...this.sessions.values()];
         this.sessions.clear();
-        await Promise.all(all.map((session) => forceKill(session.handle)));
+        await Promise.all(all.map((session) => {
+            session.closed = true;
+            try {
+                session.screen?.dispose();
+            }
+            catch {
+                /* 已释放 */
+            }
+            return forceKill(session.handle);
+        }));
     }
 }
 /* ------------------------------------------------------------------ *
@@ -264,11 +640,13 @@ class TtyServer {
     ctx;
     sessions;
     options;
+    hostKeyStore;
     wss = new WebSocketServer({ noServer: true });
-    constructor(ctx, sessions, options) {
+    constructor(ctx, sessions, options, hostKeyStore) {
         this.ctx = ctx;
         this.sessions = sessions;
         this.options = options;
+        this.hostKeyStore = hostKeyStore;
         this.wss.on('connection', (ws) => this.onConnection(ws));
     }
     /** registerUpgrade 的 handler（loopback 围栏 + ws 握手）。 */
@@ -288,9 +666,18 @@ class TtyServer {
             const all = [...local.values()];
             local.clear();
             await Promise.all(all.map(async (session) => {
-                session.closed = true;
-                this.sessions.remove(session.id);
-                await forceKill(session.handle);
+                if (session.closed)
+                    return;
+                if (this.options.reconnectGraceMs > 0) {
+                    // 客户端正常关面板会先逐个 kill（会话已移出 local），走到这里的都是
+                    // 「异常断开仍有存活会话」：转孤儿保活，等待新连接 attach，到点由回收器清理
+                    this.flushPendingOutput(session); // 没了收件人，待发帧直接丢弃（回放走环形缓冲）
+                    session.ws = null;
+                    session.orphanedAt = Date.now();
+                    return;
+                }
+                this.flushPendingOutput(session);
+                this.killSessionNow(session);
             }));
         };
         ws.on('message', (raw) => {
@@ -333,6 +720,31 @@ class TtyServer {
         send(ws, { t: 'error', m: local.size === 0 ? '没有可用会话（先发 spawn）' : '存在多个会话，请指定 sid' });
         return undefined;
     }
+    /**
+     * 立即终止会话：同步退役 + 顶层 shell 直接 SIGKILL，让 done/exit 帧立刻可发；
+     * 树级子进程清理（SIGTERM→grace→SIGKILL，交互式 zsh 忽略 SIGTERM 时最慢
+     * 可拖 ~20s）由 terminate 在后台继续收尾，不阻塞 kill 帧处理。
+     */
+    killSessionNow(session) {
+        this.sessions.retire(session);
+        try {
+            session.handle.forceKill?.();
+        }
+        catch {
+            /* 已退出 */
+        }
+        void forceKill(session.handle);
+    }
+    /** 每会话一块虚拟屏（xterm-headless）：tty_screen 的数据源；失败降级为 null。 */
+    createScreen(cols, rows) {
+        try {
+            // buffer 命名空间在 xterm 5.x 是提案 API，必须开 allowProposedApi
+            return new HeadlessTerminal({ cols, rows, scrollback: 0, allowProposedApi: true });
+        }
+        catch {
+            return null;
+        }
+    }
     async handleMessage(ws, msg, local, cleanupAll) {
         try {
             if (msg.t === 'spawn') {
@@ -360,12 +772,13 @@ class TtyServer {
                     send(ws, { t: 'error', sid, m: 'subprocess 服务不可用' });
                     return;
                 }
+                const spawnPlan = buildShellSpawn(this.options.shell, this.options.term, this.options.colorTerm, this.options.shellIntegration);
                 const handle = wrapLocalPty(await subprocess.spawnTerminal({
-                    argv: shellArgv(this.options.shell, this.options.term, this.options.colorTerm),
+                    argv: spawnPlan.argv,
                     rows: Number(msg.rows) || 24,
                     cols: Number(msg.cols) || 80,
                     cwd,
-                    env: { TERM: this.options.term, COLORTERM: this.options.colorTerm },
+                    env: { TERM: this.options.term, COLORTERM: this.options.colorTerm, ...spawnPlan.env },
                     graceMs: 5000,
                 }));
                 const next = {
@@ -380,12 +793,18 @@ class TtyServer {
                     startedAt: Date.now(),
                     lastOutputAt: Date.now(),
                     buffer: '',
+                    decoder: new StringDecoder('utf8'),
+                    screen: this.createScreen(Number(msg.cols) || 80, Number(msg.rows) || 24),
+                    orphanedAt: null,
+                    shellState: createShellState(),
+                    pendingOutput: '',
+                    flushTimer: null,
                 };
                 local.set(sid, next);
                 this.sessions.add(next);
                 send(ws, { t: 'ready', sid, pid: handle.pid, kind: 'local' });
                 this.attachOutput(next);
-                this.watchDone(next, local, ws);
+                this.watchDone(next, local);
             }
             else if (msg.t === 'ssh') {
                 const sid = typeof msg.sid === 'string' && msg.sid !== '' ? msg.sid : randomUUID();
@@ -415,6 +834,7 @@ class TtyServer {
                     keyPath: typeof msg.keyPath === 'string' && msg.keyPath !== '' ? msg.keyPath : profile?.keyPath,
                     passphrase: typeof msg.passphrase === 'string' && msg.passphrase !== '' ? msg.passphrase : profile?.passphrase,
                     password: typeof msg.password === 'string' && msg.password !== '' ? msg.password : profile?.password,
+                    agentForward: typeof msg.agentForward === 'boolean' ? msg.agentForward : profile?.agentForward ?? false,
                 };
                 if (spec.host === '' || spec.username === '') {
                     send(ws, { t: 'error', sid, m: 'SSH 会话需要 host 与 username（或用 name 引用连接簿）' });
@@ -429,6 +849,7 @@ class TtyServer {
                         cols: Number(msg.cols) || 80,
                         rows: Number(msg.rows) || 24,
                         logger: { info: (m) => this.ctx.logger.info(m), warn: (m) => this.ctx.logger.warn(m) },
+                        hostKeyStore: this.hostKeyStore,
                     });
                 }
                 catch (error) {
@@ -447,12 +868,18 @@ class TtyServer {
                     startedAt: Date.now(),
                     lastOutputAt: Date.now(),
                     buffer: '',
+                    decoder: new StringDecoder('utf8'),
+                    screen: this.createScreen(Number(msg.cols) || 80, Number(msg.rows) || 24),
+                    orphanedAt: null,
+                    shellState: createShellState(),
+                    pendingOutput: '',
+                    flushTimer: null,
                 };
                 local.set(sid, next);
                 this.sessions.add(next);
                 send(ws, { t: 'ready', sid, pid: null, kind: 'ssh', target });
                 this.attachOutput(next);
-                this.watchDone(next, local, ws);
+                this.watchDone(next, local);
             }
             else if (msg.t === 'input') {
                 const resolved = this.resolveSid(ws, msg, local);
@@ -468,20 +895,72 @@ class TtyServer {
                     return;
                 const session = local.get(resolved.sid);
                 if (session !== undefined) {
-                    session.handle.resize(Number(msg.cols) || 80, Number(msg.rows) || 24);
+                    const cols = Number(msg.cols) || 80;
+                    const rows = Number(msg.rows) || 24;
+                    session.handle.resize(cols, rows);
+                    try {
+                        session.screen?.resize(cols, rows);
+                    }
+                    catch {
+                        /* 非法尺寸或已释放 */
+                    }
                 }
             }
             else if (msg.t === 'kill') {
                 const resolved = this.resolveSid(ws, msg, local);
-                if (resolved === undefined || 'unknown' in resolved)
+                if (resolved === undefined)
+                    return;
+                if ('unknown' in resolved) {
+                    // 本连接没有该 sid：若是孤儿会话（前连接已断）也允许 kill，
+                    // 避免「关闭面板杀不掉孤儿」泄漏到保活期结束
+                    const orphan = this.sessions.get(String(msg.sid ?? ''));
+                    if (orphan !== undefined && !orphan.closed) {
+                        this.flushPendingOutput(orphan);
+                        this.killSessionNow(orphan);
+                    }
                     return;
+                }
                 const session = local.get(resolved.sid);
                 if (session === undefined)
                     return;
-                session.closed = true;
                 local.delete(resolved.sid);
-                this.sessions.remove(resolved.sid);
-                await forceKill(session.handle);
+                this.killSessionNow(session);
+            }
+            else if (msg.t === 'sessions') {
+                send(ws, { t: 'sessions', list: this.sessions.listForAttach() });
+            }
+            else if (msg.t === 'attach') {
+                const raw = msg.sid;
+                if (typeof raw !== 'string' || raw === '' || !SID_RE.test(raw)) {
+                    send(ws, { t: 'error', m: 'attach 需要合法 sid' });
+                    return;
+                }
+                const session = this.sessions.get(raw);
+                if (session === undefined || session.closed) {
+                    send(ws, { t: 'error', sid: raw, m: `会话不存在或已结束: ${raw}` });
+                    return;
+                }
+                if (session.ws !== null) {
+                    send(ws, { t: 'error', sid: raw, m: '会话已连接到其它窗口' });
+                    return;
+                }
+                // 重新绑定到本连接：解孤儿态，恢复被背压暂停的输出流
+                session.ws = ws;
+                session.orphanedAt = null;
+                local.set(session.id, session);
+                if (session.paused) {
+                    session.paused = false;
+                    try {
+                        session.handle.output.resume();
+                    }
+                    catch {
+                        /* 已退出 */
+                    }
+                }
+                send(ws, { t: 'ready', sid: session.id, pid: session.handle.pid, kind: session.kind, target: session.target !== '' ? session.target : undefined, reattached: true });
+                // 断线期间的输出经 256KB 环形缓冲回放（缓冲为空则跳过）
+                if (session.buffer !== '')
+                    send(ws, { t: 'data', sid: session.id, d: session.buffer });
             }
         }
         catch (error) {
@@ -489,30 +968,37 @@ class TtyServer {
         }
     }
     /** 会话退出事实 → exit 帧（恰好一次；本地 PTY 与 SSH 共用）。 */
-    watchDone(session, local, ws) {
+    watchDone(session, local) {
         session.handle.done.then((outcome) => {
-            // kill 主动关闭时会话可能已被移出 local，用 exitSent 保证 exit 帧恰好一次
+            // kill 主动关闭时会话可能已被移出 local，用 exitSent 保证 exit 帧恰好一次；
+            // 发送走 session.ws 动态取值——attach 换连接后 exit 也能跟着新连接走
             if (session.exitSent === true)
                 return;
             session.exitSent = true;
             session.closed = true;
             local.delete(session.id);
             this.sessions.remove(session.id);
-            send(ws, { t: 'exit', sid: session.id, code: outcome.exitCode, signal: outcome.signal });
+            try {
+                session.screen?.dispose();
+            }
+            catch {
+                /* 已释放 */
+            }
+            this.flushPendingOutput(session); // exit 前冲掉合并窗口里的尾巴，保序
+            send(session.ws, { t: 'exit', sid: session.id, code: outcome.exitCode, signal: outcome.signal });
         }).catch(() => { });
     }
     /** 输出下行 + 基于 ws.bufferedAmount 的背压（暂停/恢复 PassThrough）。 */
     attachOutput(session) {
         const output = session.handle.output;
-        const onData = (chunk) => {
-            if (session.closed)
-                return;
-            const text = chunk.toString('utf8');
-            session.lastOutputAt = Date.now();
-            session.buffer = (session.buffer + text).slice(-BUFFER_CAP);
+        const flush = () => {
+            session.flushTimer = null;
             const ws = session.ws;
-            const sid = session.id;
-            ws.send(JSON.stringify({ t: 'data', sid, d: text }), () => {
+            const pending = session.pendingOutput;
+            if (session.closed || ws === null || pending === '')
+                return;
+            session.pendingOutput = '';
+            ws.send(JSON.stringify({ t: 'data', sid: session.id, d: pending }), () => {
                 if (session.paused && ws.bufferedAmount < BACKPRESSURE_LOW && output.readableFlowing === false) {
                     output.resume();
                 }
@@ -522,8 +1008,53 @@ class TtyServer {
                 output.pause();
             }
         };
+        const onData = (chunk) => {
+            if (session.closed)
+                return;
+            // StringDecoder 兜跨 chunk 多字节序列，再喂 shell 集成解析与虚拟屏
+            const text = session.decoder.write(chunk);
+            session.lastOutputAt = Date.now();
+            session.buffer = (session.buffer + text).slice(-BUFFER_CAP);
+            feedShellIntegration(session, text);
+            try {
+                session.screen?.write(text);
+            }
+            catch {
+                /* 虚拟屏异常不阻断输出链路 */
+            }
+            const ws = session.ws;
+            if (ws === null)
+                return; // 孤儿会话：仅积累缓冲，等待重连 attach 回放
+            // data 帧合并：窗口内攒批，超阈值立即冲刷；exit/kill 前会强制 flush 保序
+            session.pendingOutput += text;
+            if (session.pendingOutput.length >= FLUSH_SIZE_CHARS) {
+                if (session.flushTimer !== null) {
+                    clearTimeout(session.flushTimer);
+                    session.flushTimer = null;
+                }
+                flush();
+            }
+            else if (session.flushTimer === null) {
+                const timer = setTimeout(flush, FLUSH_INTERVAL_MS);
+                timer.unref?.();
+                session.flushTimer = timer;
+            }
+        };
         output.on('data', onData);
     }
+    /** 立即冲刷待发的合并输出（exit/kill 前调用，保证 exit 帧永远在最后一帧 data 之后）。 */
+    flushPendingOutput(session) {
+        if (session.flushTimer !== null) {
+            clearTimeout(session.flushTimer);
+            session.flushTimer = null;
+        }
+        const ws = session.ws;
+        const pending = session.pendingOutput;
+        session.pendingOutput = '';
+        if (session.closed || ws === null || pending === '')
+            return;
+        send(ws, { t: 'data', sid: session.id, d: pending });
+    }
     close() {
         for (const client of this.wss.clients) {
             try {
@@ -538,6 +1069,35 @@ class TtyServer {
 /* ------------------------------------------------------------------ *
  * 插件本体
  * ------------------------------------------------------------------ */
+/**
+ * env 插件托管变量名（~/.dsh/env.yml 托管区块内的 key，路径解析与 env 插件
+ * 一致：DSH_ENV_FILE / DSH_HOME 优先）。只提取键名、绝不读值——这些是用户
+ * 明确交给 dsh-env-manager 托管的变量，才是 env:VAR 引用的推荐来源；键行由
+ * env 插件以 yaml 数组渲染（`- key: NAME`），逐行宽容提取即可，不引 YAML 依赖。
+ */
+function readManagedEnvKeys() {
+    const dshHome = process.env.DSH_HOME?.trim() || join(homedir(), '.dsh');
+    const file = process.env.DSH_ENV_FILE?.trim() || join(dshHome, 'env.yml');
+    try {
+        const lines = readFileSync(file, 'utf8').split('\n');
+        const start = lines.findIndex((line) => line.includes('dsh-env-manager managed'));
+        if (start === -1)
+            return [];
+        const end = lines.findIndex((line, index) => index > start && line.includes('end dsh-env-manager managed'));
+        if (end === -1)
+            return [];
+        const keys = [];
+        for (const line of lines.slice(start + 1, end)) {
+            const match = line.match(/^\s*-\s*key:\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1\s*$/);
+            if (match !== null)
+                keys.push(match[2]);
+        }
+        return [...new Set(keys)].sort().slice(0, 200);
+    }
+    catch {
+        return [];
+    }
+}
 /** HTTP 路由的 loopback 信任围栏（与 dsh-mcp 同思路）。 */
 function isLoopbackHttp(req) {
     const address = req.socket.remoteAddress;
@@ -606,10 +1166,25 @@ const plugin = definePlugin({
             term: config?.term?.trim() || 'xterm-256color',
             colorTerm: config?.colorTerm?.trim() || 'truecolor',
             cwd: config?.cwd?.trim() || process.cwd(),
+            reconnectGraceSec: typeof config?.reconnectGraceSec === 'number' && Number.isInteger(config.reconnectGraceSec) && config.reconnectGraceSec >= 0 ? config.reconnectGraceSec : DEFAULT_RECONNECT_GRACE_SEC,
             sshHosts: Array.isArray(config?.sshHosts) ? config.sshHosts : [],
+            hostKeys: Array.isArray(config?.hostKeys) ? config.hostKeys : [],
+            shellIntegration: config?.shellIntegration !== false,
+            tunnels: Array.isArray(config?.tunnels) ? config.tunnels : [],
         });
         const sessions = new SessionManager(config?.maxSessions ?? DEFAULT_MAX_SESSIONS);
-        const server = new TtyServer(ctx, sessions, live);
+        /** TOFU 指纹记录持久化：写入 settings 命名空间（合并语义），失败不影响连接。 */
+        const persistHostKeys = (records) => {
+            const scope = settingsScope;
+            if (scope === undefined)
+                return;
+            void Promise.resolve(scope.update({ hostKeys: records })).catch((error) => {
+                console.warn('[dsh-tty] 主机密钥记录持久化失败: ' + (error instanceof Error ? error.message : String(error)));
+            });
+        };
+        const hostKeyStore = new HostKeyStore(live, persistHostKeys);
+        const tunnelManager = new TunnelManager({ info: (m) => ctx.logger.info(m), warn: (m) => ctx.logger.warn(m) }, hostKeyStore, (bookName) => live.findSshHost(bookName));
+        const server = new TtyServer(ctx, sessions, live, hostKeyStore);
         const stateRef = { enabled: true, announceToAgent: config?.announceToAgent !== false, toolsRegistered: false };
         let settingsScope;
         const snapshot = () => ({
@@ -620,7 +1195,11 @@ const plugin = definePlugin({
             term: live.term,
             colorTerm: live.colorTerm,
             cwd: live.cwd,
+            reconnectGraceSec: Math.round(live.reconnectGraceMs / 1000),
             sshHosts: live.sshHosts,
+            hostKeys: live.hostKeys,
+            tunnels: live.tunnels,
+            shellIntegration: live.shellIntegration,
             toolsRegistered: stateRef.toolsRegistered,
         });
         /** 规范化并应用一份配置补丁（settings/updated 事件与 HTTP POST 共用；幂等）。 */
@@ -630,8 +1209,14 @@ const plugin = definePlugin({
                 term: typeof section.term === 'string' ? section.term : undefined,
                 colorTerm: typeof section.colorTerm === 'string' ? section.colorTerm : undefined,
                 cwd: typeof section.cwd === 'string' ? section.cwd : undefined,
+                reconnectGraceSec: typeof section.reconnectGraceSec === 'number' ? section.reconnectGraceSec : undefined,
                 sshHosts: sanitizeSshHosts(section.sshHosts),
+                hostKeys: sanitizeHostKeys(section.hostKeys),
+                shellIntegration: typeof section.shellIntegration === 'boolean' ? section.shellIntegration : undefined,
+                tunnels: sanitizeTunnels(section.tunnels),
             });
+            // 隧道按最新规格对齐（幂等；sshHosts 变更也会触发，让重连取到新凭证）
+            tunnelManager.reconcile(live.tunnels);
             if (typeof section.maxSessions === 'number' && Number.isInteger(section.maxSessions) && section.maxSessions >= 1 && section.maxSessions <= 16) {
                 sessions.setLimit(section.maxSessions);
             }
@@ -644,7 +1229,7 @@ const plugin = definePlugin({
         /** 校验 HTTP POST 的配置体；返回规范化补丁或错误信息。 */
         const normalizePatch = (input) => {
             const patch = {};
-            const known = new Set(['enabled', 'announceToAgent', 'maxSessions', 'shell', 'term', 'colorTerm', 'cwd', 'sshHosts']);
+            const known = new Set(['enabled', 'announceToAgent', 'maxSessions', 'shell', 'term', 'colorTerm', 'cwd', 'reconnectGraceSec', 'sshHosts', 'hostKeys', 'tunnels', 'shellIntegration']);
             for (const key of Object.keys(input)) {
                 if (!known.has(key))
                     return { error: '未知配置项: ' + key };
@@ -665,6 +1250,17 @@ const plugin = definePlugin({
                     return { error: 'maxSessions 必须是 1~16 的整数' };
                 patch.maxSessions = value;
             }
+            if (input.reconnectGraceSec !== undefined) {
+                const value = Number(input.reconnectGraceSec);
+                if (!Number.isInteger(value) || value < 0 || value > 3600)
+                    return { error: 'reconnectGraceSec 必须是 0~3600 的整数' };
+                patch.reconnectGraceSec = value;
+            }
+            if (input.shellIntegration !== undefined) {
+                if (typeof input.shellIntegration !== 'boolean')
+                    return { error: 'shellIntegration 必须是布尔值' };
+                patch.shellIntegration = input.shellIntegration;
+            }
             for (const key of ['shell', 'term', 'colorTerm']) {
                 if (input[key] === undefined)
                     continue;
@@ -689,6 +1285,21 @@ const plugin = definePlugin({
                     return { error: validated.error };
                 patch.sshHosts = validated.hosts;
             }
+            if (input.hostKeys !== undefined) {
+                const validated = validateHostKeys(input.hostKeys);
+                if (validated.error !== undefined)
+                    return { error: validated.error };
+                patch.hostKeys = validated.keys;
+            }
+            if (input.tunnels !== undefined) {
+                // bookName 交叉校验：优先用同次提交的 sshHosts（整体替换语义），否则用现有连接簿
+                const bookSource = Array.isArray(patch.sshHosts) ? patch.sshHosts : live.sshHosts;
+                const bookNames = new Set(bookSource.map((host) => host.name));
+                const validated = validateTunnels(input.tunnels, bookNames);
+                if (validated.error !== undefined)
+                    return { error: validated.error };
+                patch.tunnels = validated.tunnels;
+            }
             return { patch };
         };
         // webServer：WS upgrade 路由 + 配置读写路由（/api/dsh-tty/config）
@@ -744,6 +1355,83 @@ const plugin = definePlugin({
                         writeJson(res, 200, { ok: true, config: snapshot() });
                     },
                 }));
+                // ~/.ssh/config 导入候选（连接簿）：loopback 围栏，只回解析结果不落盘
+                disposers.push(webServer.register({
+                    kind: 'exact',
+                    path: '/api/dsh-tty/ssh-config',
+                    handler: async (req, res) => {
+                        if (!isLoopbackHttp(req)) {
+                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                            return;
+                        }
+                        if (req.method !== 'GET') {
+                            writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
+                            return;
+                        }
+                        try {
+                            const text = readFileSync(expandHome('~/.ssh/config'), 'utf8');
+                            writeJson(res, 200, { ok: true, entries: parseSshConfig(text) });
+                        }
+                        catch (error) {
+                            writeJson(res, 200, { ok: false, error: '无法读取 ~/.ssh/config: ' + (error instanceof Error ? error.message : String(error)) });
+                        }
+                    },
+                }));
+                // env:VAR 下拉数据源（SSH 对话框）：只回 env 插件托管变量名，绝不含值
+                disposers.push(webServer.register({
+                    kind: 'exact',
+                    path: '/api/dsh-tty/env-vars',
+                    handler: async (req, res) => {
+                        if (!isLoopbackHttp(req)) {
+                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                            return;
+                        }
+                        if (req.method !== 'GET') {
+                            writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
+                            return;
+                        }
+                        writeJson(res, 200, { ok: true, names: readManagedEnvKeys() });
+                    },
+                }));
+                // known_hosts 指纹导入候选（TOFU 预填充）：hashed 条目用连接簿主机名还原
+                disposers.push(webServer.register({
+                    kind: 'exact',
+                    path: '/api/dsh-tty/known-hosts',
+                    handler: async (req, res) => {
+                        if (!isLoopbackHttp(req)) {
+                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                            return;
+                        }
+                        if (req.method !== 'GET') {
+                            writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
+                            return;
+                        }
+                        try {
+                            const text = readFileSync(expandHome('~/.ssh/known_hosts'), 'utf8');
+                            const candidates = live.sshHosts.flatMap((entry) => [entry.host, `[${entry.host}]:${entry.port}`]);
+                            writeJson(res, 200, { ok: true, entries: parseKnownHosts(text, candidates) });
+                        }
+                        catch (error) {
+                            writeJson(res, 200, { ok: false, error: '无法读取 ~/.ssh/known_hosts: ' + (error instanceof Error ? error.message : String(error)) });
+                        }
+                    },
+                }));
+                // 端口转发隧道实时状态（设置卡片轮询徽标 + tunnel_list 工具数据源）
+                disposers.push(webServer.register({
+                    kind: 'exact',
+                    path: '/api/dsh-tty/tunnels',
+                    handler: async (req, res) => {
+                        if (!isLoopbackHttp(req)) {
+                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                            return;
+                        }
+                        if (req.method !== 'GET') {
+                            writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
+                            return;
+                        }
+                        writeJson(res, 200, { ok: true, tunnels: tunnelManager.list() });
+                    },
+                }));
                 return () => {
                     server.close();
                     for (const dispose of disposers) {
@@ -781,9 +1469,20 @@ const plugin = definePlugin({
                     startup.enabled = false;
                 if (stored.announceToAgent === false)
                     startup.announceToAgent = false;
+                if (stored.reconnectGraceSec !== 120 && typeof stored.reconnectGraceSec === 'number' && Number.isInteger(stored.reconnectGraceSec) && stored.reconnectGraceSec >= 0 && stored.reconnectGraceSec <= 3600) {
+                    startup.reconnectGraceSec = stored.reconnectGraceSec;
+                }
+                if (stored.shellIntegration === false)
+                    startup.shellIntegration = false;
                 const storedHosts = sanitizeSshHosts(stored.sshHosts);
                 if (storedHosts !== undefined && storedHosts.length > 0)
                     startup.sshHosts = storedHosts;
+                const storedKeys = sanitizeHostKeys(stored.hostKeys);
+                if (storedKeys !== undefined && storedKeys.length > 0)
+                    startup.hostKeys = storedKeys;
+                const storedTunnels = sanitizeTunnels(stored.tunnels);
+                if (storedTunnels !== undefined && storedTunnels.length > 0)
+                    startup.tunnels = storedTunnels;
                 if (Object.keys(startup).length > 0)
                     applyPatch(startup);
                 const events = settingsCtx;
@@ -856,10 +1555,12 @@ const plugin = definePlugin({
                 })));
                 disposers.push(tools.register(defineTool({
                     name: 'tty_capture',
-                    description: '读取某个终端面板会话（tty_list 提供 sid）的近期输出（默认尾部 60 行，最多 500 行）。适合查看用户终端里正在运行的 dev server / watch / 构建输出。',
+                    description: '读取某个终端面板会话（tty_list 提供 sid）的近期输出。默认读取尾部 N 行（60，最多 500，已剥离 ANSI 转义序列并收敛同行覆盖）；last:true 时只返回「上一条已完成命令」的输出与退出码（依赖 shell 集成标记，更适合拿单条命令的结果）。',
                     parameters: {
                         sid: { type: 'string', required: true, description: '会话 id（来自 tty_list）' },
-                        lines: { type: 'number', description: '读取尾部行数（1~500，默认 60）' },
+                        lines: { type: 'number', description: '读取尾部行数（1~500，默认 60）；last:true 时忽略' },
+                        last: { type: 'boolean', description: 'true 只返回上一条命令的输出+退出码（默认 false 读尾部）' },
+                        raw: { type: 'boolean', description: 'true 返回含 ANSI 转义序列的原始输出（默认 false 清洗为纯文本）' },
                     },
                     output: {
                         schema: {
@@ -868,22 +1569,162 @@ const plugin = definePlugin({
                             properties: {
                                 sid: { type: 'string', required: true },
                                 tail: { type: 'string', required: true },
+                                source: { type: 'string' },
+                                exitCode: { type: 'number' },
                             },
                         },
                         render: (_args, value) => {
                             const v = value;
-                            return [{ type: 'text', text: `终端会话 ${v.sid ?? '?'} 尾部输出：\n\n${v.tail ?? ''}` }];
+                            const head = v.source === 'last'
+                                ? `终端会话 ${v.sid ?? '?'} 上一条命令的输出（exitCode=${String(v.exitCode ?? '?')}）：\n\n`
+                                : `终端会话 ${v.sid ?? '?'} 尾部输出：\n\n`;
+                            return [{ type: 'text', text: head + (v.tail ?? '') }];
                         },
                     },
                     async execute(args) {
                         const input = args;
                         if (typeof input.sid !== 'string' || input.sid === '')
                             throw new Error('sid 必须是非空字符串');
+                        const session = sessions.get(input.sid);
+                        if (session === undefined || session.closed)
+                            throw new Error(`会话不存在或已退出: ${input.sid}`);
+                        const useRaw = input.raw === true;
+                        if (input.last === true) {
+                            const last = session.shellState.lastCommand;
+                            if (last === null) {
+                                throw new Error('暂无「上一条命令」记录（shell 集成未生效——shell 不受支持或被配置关闭——或尚未执行过命令）；可改用 lines 读尾部');
+                            }
+                            return { sid: input.sid, source: 'last', exitCode: last.exitCode ?? undefined, tail: (useRaw ? last.output : cleanAnsiTail(last.output)).slice(0, 128 * 1024) };
+                        }
                         const lines = Math.max(1, Math.min(500, typeof input.lines === 'number' && Number.isInteger(input.lines) && input.lines >= 1 ? input.lines : 60));
+                        const rawTail = tailLines(session, lines);
+                        return { sid: input.sid, source: 'tail', tail: useRaw ? rawTail : cleanAnsiTail(rawTail) };
+                    },
+                })));
+                disposers.push(tools.register(defineTool({
+                    name: 'tty_screen',
+                    description: '读取某个终端面板会话（tty_list 提供 sid）当前可见屏幕的渲染结果（纯文本，等价于用户此刻看到的画面）。适合查看全屏交互程序（vim / htop / 菜单选择）的当前界面状态；要历史滚动输出用 tty_capture。',
+                    parameters: {
+                        sid: { type: 'string', required: true, description: '会话 id（来自 tty_list）' },
+                    },
+                    output: {
+                        schema: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                sid: { type: 'string', required: true },
+                                cols: { type: 'number', required: true },
+                                rows: { type: 'number', required: true },
+                                text: { type: 'string', required: true },
+                            },
+                        },
+                        render: (_args, value) => {
+                            const v = value;
+                            return [{ type: 'text', text: `终端会话 ${v.sid ?? '?'} 当前屏幕（${String(v.cols ?? '?')}×${String(v.rows ?? '?')}）：\n\n${v.text ?? ''}` }];
+                        },
+                    },
+                    async execute(args) {
+                        const input = args;
+                        if (typeof input.sid !== 'string' || input.sid === '')
+                            throw new Error('sid 必须是非空字符串');
                         const session = sessions.get(input.sid);
                         if (session === undefined || session.closed)
                             throw new Error(`会话不存在或已退出: ${input.sid}`);
-                        return { sid: input.sid, tail: tailLines(session, lines) };
+                        const screen = session.screen;
+                        if (screen === null)
+                            throw new Error(`虚拟屏不可用: ${input.sid}`);
+                        const buffer = screen.buffer.active;
+                        const lines = [];
+                        for (let row = 0; row < screen.rows; row++) {
+                            lines.push(buffer.getLine(row)?.translateToString(true) ?? '');
+                        }
+                        while (lines.length > 0 && lines[lines.length - 1].trim() === '')
+                            lines.pop();
+                        return { sid: input.sid, cols: screen.cols, rows: screen.rows, text: lines.join('\n').slice(0, 32 * 1024) };
+                    },
+                })));
+                disposers.push(tools.register(defineTool({
+                    name: 'tty_expect',
+                    description: '在某个终端面板会话（tty_list 提供 sid）的后续输出中等待一个正则出现（如 dev server 的 ready/URL、构建完成标记、交互提示）。匹配到立即返回 matched:true 与周边输出；超时不抛错，返回 matched:false + 尾部输出供判断重试或放弃；期间该命令若已结束（shell 集成标记）也会提前返回并带退出码。适合先 tty_send 启动长任务、再 tty_expect 等就绪信号的流程。',
+                    parameters: {
+                        sid: { type: 'string', required: true, description: '会话 id（来自 tty_list）' },
+                        pattern: { type: 'string', required: true, description: '等待匹配的正则表达式（JavaScript RegExp 语法）' },
+                        timeoutSec: { type: 'number', description: '等待秒数（1~600，默认 30）' },
+                    },
+                    output: {
+                        schema: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                matched: { type: 'boolean', required: true },
+                                timedOut: { type: 'boolean', required: true },
+                                text: { type: 'string', required: true },
+                                exitCode: { type: 'number' },
+                            },
+                        },
+                        render: (_args, value) => {
+                            const v = value;
+                            if (v.matched === true)
+                                return [{ type: 'text', text: `已匹配到等待的模式：\n\n${v.text ?? ''}` }];
+                            const why = v.timedOut === true ? '等待超时' : `命令已结束（exitCode=${String(v.exitCode ?? '?')}）但未出现匹配`;
+                            return [{ type: 'text', text: `${why}。尾部输出：\n\n${v.text ?? ''}` }];
+                        },
+                    },
+                    async execute(args) {
+                        const input = args;
+                        if (typeof input.sid !== 'string' || input.sid === '')
+                            throw new Error('sid 必须是非空字符串');
+                        if (typeof input.pattern !== 'string' || input.pattern === '')
+                            throw new Error('pattern 必须是非空字符串');
+                        const session = sessions.get(input.sid);
+                        if (session === undefined || session.closed)
+                            throw new Error(`会话不存在或已退出: ${input.sid}`);
+                        let re;
+                        try {
+                            re = new RegExp(input.pattern);
+                        }
+                        catch (error) {
+                            throw new Error('pattern 不是合法的正则表达式: ' + (error instanceof Error ? error.message : String(error)));
+                        }
+                        const timeoutSec = Math.max(1, Math.min(600, typeof input.timeoutSec === 'number' && Number.isInteger(input.timeoutSec) && input.timeoutSec >= 1 ? input.timeoutSec : 30));
+                        const timeoutMs = timeoutSec * 1000;
+                        return await new Promise((resolve) => {
+                            const startedAt = Date.now();
+                            const startedInCommand = session.shellState.inCommand;
+                            let acc = '';
+                            let settled = false;
+                            const decoder = new StringDecoder('utf8');
+                            const output = session.handle.output;
+                            const finish = (result) => {
+                                if (settled)
+                                    return;
+                                settled = true;
+                                clearTimeout(timer);
+                                output.off('data', onData);
+                                resolve(result);
+                            };
+                            const onData = (chunk) => {
+                                acc += decoder.write(chunk);
+                                const hay = acc.length > 16 * 1024 ? acc.slice(-16 * 1024) : acc;
+                                if (re.test(hay)) {
+                                    finish({ matched: true, timedOut: false, text: cleanAnsiTail(hay.slice(-6 * 1024)) });
+                                    return;
+                                }
+                                // 命令早停：注册时命令在飞（B..D 之间），如今 D 已到仍未匹配
+                                const state = session.shellState;
+                                if (startedInCommand && !state.inCommand && state.lastCommand !== null && state.lastCommand.endedAt >= startedAt) {
+                                    finish({ matched: false, timedOut: false, exitCode: state.lastCommand.exitCode ?? undefined, text: cleanAnsiTail(acc.slice(-6 * 1024)) });
+                                }
+                            };
+                            const timer = setTimeout(() => {
+                                finish({ matched: false, timedOut: true, text: cleanAnsiTail(acc.slice(-6 * 1024)) });
+                            }, timeoutMs);
+                            timer.unref?.();
+                            output.on('data', onData);
+                            void session.handle.done.then(() => {
+                                finish({ matched: false, timedOut: false, text: cleanAnsiTail(acc.slice(-6 * 1024)) });
+                            });
+                        });
                     },
                 })));
                 disposers.push(tools.register(defineTool({
@@ -920,8 +1761,53 @@ const plugin = definePlugin({
                         return { ok: true, sent: input.data.length };
                     },
                 })));
+                disposers.push(tools.register(defineTool({
+                    name: 'tunnel_list',
+                    description: '列出端口转发隧道及其实时状态（活跃/连接中/错误/停止、规则、当前与累计连接数、最近错误）。用户说「隧道连不上 / 转发挂了 / 端口转发不通」时先用它诊断；隧道在 设置 → 插件 → 终端面板 卡片维护。',
+                    parameters: {},
+                    output: {
+                        schema: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                tunnels: {
+                                    type: 'array',
+                                    required: true,
+                                    items: {
+                                        type: 'object',
+                                        additionalProperties: false,
+                                        properties: {
+                                            name: { type: 'string', required: true },
+                                            direction: { type: 'string', required: true },
+                                            rule: { type: 'string', required: true },
+                                            bookName: { type: 'string', required: true },
+                                            state: { type: 'string', required: true },
+                                            error: { type: 'string' },
+                                            connections: { type: 'number', required: true },
+                                            totalConnections: { type: 'number', required: true },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        render: (_args, value) => {
+                            const v = value;
+                            const tunnels = v.tunnels ?? [];
+                            if (tunnels.length === 0)
+                                return [{ type: 'text', text: '当前没有配置端口转发隧道（设置 → 插件 → 终端面板 卡片可添加）' }];
+                            const text = '端口转发隧道：' + tunnels.map((t) => {
+                                const tail = t.error !== null && t.error !== undefined ? `（错误: ${t.error}）` : t.lastForwardError !== null && t.lastForwardError !== undefined ? `（最近转发失败: ${t.lastForwardError}）` : `（连接 ${String(t.connections)}）`;
+                                return `\n- ${t.name} [${t.direction}] ${t.rule} — ${t.state}${tail}`;
+                            }).join('');
+                            return [{ type: 'text', text }];
+                        },
+                    },
+                    async execute() {
+                        return { tunnels: tunnelManager.list().map((t) => ({ ...t, error: t.error ?? undefined })) };
+                    },
+                })));
                 stateRef.toolsRegistered = true;
-                console.log('[dsh-tty] agent tools registered (tty_list, tty_capture, tty_send)');
+                console.log('[dsh-tty] agent tools registered (tty_list, tty_capture, tty_screen, tty_expect, tty_send, tunnel_list)');
                 return () => {
                     stateRef.toolsRegistered = false;
                     for (const dispose of disposers) {
@@ -938,19 +1824,44 @@ const plugin = definePlugin({
         else {
             console.log('[dsh-tty] tools service unavailable; agent tools skipped');
         }
-        // 向 agent 公告终端面板能力
+        // 向 agent 公告终端面板能力（静态 section）+ 每轮注入活跃会话快照（动态 context）
         if (config?.announceToAgent !== false) {
             ctx.inject(['systemPrompt'], (promptCtx) => {
                 promptCtx.effect(() => {
                     const systemPrompt = promptCtx.systemPrompt;
-                    return systemPrompt.section({ name: 'plugin:dsh-tty', order: 150, text: TTY_GUIDANCE });
+                    const contextDisposable = systemPrompt.context({
+                        name: 'plugin:dsh-tty:terminals',
+                        order: 150,
+                        text: () => {
+                            const list = sessions.list();
+                            if (list.length === 0)
+                                return '当前没有活跃的终端面板会话（可引导用户打开「终端」面板，或用 spawn 类工作流替代）。';
+                            return '当前活跃的终端面板会话（可用 tty_capture / tty_screen / tty_expect / tty_send 操作，sid 如下）：\n' + list.map((s) => {
+                                const where = s.kind === 'ssh' ? `ssh ${s.target}` : `pid=${String(s.pid ?? '?')} cwd=${s.cwd}`;
+                                return `- sid=${s.sid} [${s.kind}] ${where} (最后活动 ${new Date(s.lastOutputAt).toLocaleTimeString()})`;
+                            }).join('\n');
+                        },
+                    });
+                    const sectionDisposable = systemPrompt.section({ name: 'plugin:dsh-tty', order: 150, text: TTY_GUIDANCE });
+                    return () => {
+                        sectionDisposable();
+                        contextDisposable();
+                    };
                 }, 'dsh-tty: announcement');
             });
         }
-        // 插件卸载时回收全部会话
+        // 孤儿会话回收器：超过保活期的异常断开会话定期清理（grace=0 时为 no-op，
+        // 断开时立即结束）；插件卸载时随 effect 一起停掉
+        const reaperTimer = setInterval(() => {
+            void sessions.reapOrphans(live.reconnectGraceMs);
+        }, REAPER_INTERVAL_MS);
+        reaperTimer.unref?.();
+        ctx.effect(() => () => clearInterval(reaperTimer), 'dsh-tty: orphan reaper');
+        // 插件卸载时回收全部会话与隧道
         ctx.effect(() => {
             return () => {
                 void sessions.disposeAll();
+                tunnelManager.disposeAll();
             };
         }, 'dsh-tty: session cleanup');
         console.log(`[dsh-tty] mounted (shell=${live.shell}, term=${live.term}, cwd=${live.cwd}, maxSessions=${sessions.limitValue})`);