@hyzyn/dsh-tty 0.5.0 → 0.10.0

package/lib/index.js

@@ -1,9 +1,11 @@
 import z from '@deepseek-ai/schemastery';
 import { randomUUID } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
+import { accessSync, constants as fsConstants, existsSync, readFileSync } from 'node:fs';
+import { mkdir as fsMkdir, readdir as fsReaddir, rename as fsRename, rm as fsRm, stat as fsStat } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { PassThrough } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { StringDecoder } from 'node:string_decoder';
 import WebSocket, { WebSocketServer } from 'ws';
 // @xterm/headless 是 CJS 包：ESM 具名导入在 Node 运行时会炸（Named export not
@@ -17,6 +19,8 @@ import { buildShellSpawn } from './shell-integration.js';
 import { parseSshConfig } from './ssh-config.js';
 import { parseKnownHosts } from './known-hosts.js';
 import { TunnelManager } from './tunnels.js';
+import { SftpManager } from './sftp.js';
+import { buildTmuxSpawnPlan, ensureTmuxAssets, killTmuxSession, listTmuxSessions, probeTmux, refreshTmuxClient, sanitizePersistName } from './tmux.js';
 const SSH_HOST_SCHEMA = z.object({
     name: z.string(),
     host: z.string(),
@@ -27,6 +31,8 @@ const SSH_HOST_SCHEMA = z.object({
     passphrase: z.string().default(''),
     password: z.string().default(''),
     agentForward: z.boolean().default(false),
+    /** 该条目的 SSH 标签默认以 tmux 持久会话打开（仅 persistence=tmux 时生效）。 */
+    persist: z.boolean().default(false),
 });
 const HOST_KEY_SCHEMA = z.object({
     host: z.string(),
@@ -58,6 +64,10 @@ const TTY_SETTINGS_SCHEMA = z.object({
     hostKeys: z.array(HOST_KEY_SCHEMA).default([]),
     tunnels: z.array(TUNNEL_SCHEMA).default([]),
     shellIntegration: z.boolean().default(true),
+    sftpStyle: z.union([z.const('dialog'), z.const('dual')]).default('dialog'),
+    persistence: z.union([z.const('off'), z.const('tmux')]).default('off'),
+    endOnPageClose: z.boolean().default(false),
+    persistSessions: z.array(z.object({ tmuxName: z.string() })).default([]),
 });
 /* ------------------------------------------------------------------ *
  * 常量
@@ -75,7 +85,7 @@ const BUFFER_CAP = 256 * 1024;
 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} 拿结果。';
+const TTY_GUIDANCE = '本机已安装 dsh-tty 插件（终端面板）：Web GUI 侧边栏的「终端」入口可打开交互终端（xterm.js + PTY），可运行任意命令与 TUI 程序（vim/htop 等），支持多标签页与断线自动重连（刷新页面/网络抖动后会话保活并恢复现场）；新标签默认在当前会话工作目录打开。标签栏「+」菜单还能开 SSH 标签页（ssh2 原生连接，连接簿在设置卡片维护，支持 agent forwarding 与主机指纹 TOFU 钉扎），像本地终端一样操作远程主机。设置卡片开启「会话持久化（tmux）」后，新开的本地/SSH 标签默认由 tmux server 托管（宿主重启/断线超时后重开即恢复现场），长任务建议在持久化开启时运行。长驻进程（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 列出端口转发隧道状态——操作会实时显示在用户终端里。SFTP 文件传输：面板内可对 SSH 连接簿条目（或 SSH 连接对话框当前填写的信息）打开文件浏览（上传/下载/建目录/重命名/删除），agent 配套 sftp_list 列远程目录、sftp_tree 递归看目录结构、sftp_read 读远程文本文件（≤1MB）、sftp_write 写远程文本文件（≤1MB，可追加）、sftp_mkdir 建目录（parents 可逐级补齐）、sftp_rename 重命名/移动、sftp_remove 删除（目录需 recursive），book 参数为连接簿条目名。端口转发：连接簿条目可配本地/远程隧道（如把远程数据库映射到本地端口），宿主自动保活重连，用户提到「转发端口 / 访问远程库」时引导其到终端面板设置卡片配置。推荐流程：tty_send 启动长任务 → tty_expect 等就绪标记 → tty_capture{last:true} 拿结果。';
 /** 本地 PTY 包装成 TermHandle（resize/kill 仍是透传 node-pty 的内部耦合；防御性降级）。 */
 function wrapLocalPty(handle) {
     let resizeWarned = false;
@@ -127,6 +137,12 @@ class LiveConfig {
     shellIntegration;
     /** 端口转发隧道规格。 */
     tunnels;
+    /** 会话持久化模式（off / tmux）。 */
+    persistence;
+    /** 页面断开且保活期结束时是否结束 tmux 持久会话（默认 false = 留存）。 */
+    endOnPageClose;
+    /** SSH 持久会话名（远程 tmux 托管；本机 socket 清单看不到，随 settings 留存）。 */
+    persistSessions;
     constructor(init) {
         this.shell = init.shell;
         this.term = sanitizeTermValue(init.term, 'xterm-256color');
@@ -137,6 +153,9 @@ class LiveConfig {
         this.hostKeys = init.hostKeys ?? [];
         this.shellIntegration = init.shellIntegration;
         this.tunnels = init.tunnels ?? [];
+        this.persistence = init.persistence === 'tmux' ? 'tmux' : 'off';
+        this.endOnPageClose = init.endOnPageClose === true;
+        this.persistSessions = init.persistSessions ?? [];
     }
     /** 合并部分更新；空字符串/undefined 保持原值；sshHosts/hostKeys/tunnels 传数组即整体替换。 */
     apply(partial) {
@@ -159,6 +178,12 @@ class LiveConfig {
             this.shellIntegration = partial.shellIntegration;
         if (Array.isArray(partial.tunnels))
             this.tunnels = partial.tunnels;
+        if (partial.persistence === 'tmux' || partial.persistence === 'off')
+            this.persistence = partial.persistence;
+        if (typeof partial.endOnPageClose === 'boolean')
+            this.endOnPageClose = partial.endOnPageClose;
+        if (Array.isArray(partial.persistSessions))
+            this.persistSessions = partial.persistSessions;
     }
     findSshHost(name) {
         return this.sshHosts.find((entry) => entry.name === name);
@@ -203,8 +228,11 @@ function cleanAnsiTail(raw) {
         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 133 命令标记帧：\x1b]133;<A|B|D|T>[;<payload>](BEL|ST)。
+ * T（0.10.0）= tmux 持久标签的 pane 内容快照（base64）：tmux 的 pane 重画是
+ * 异步批量的，命令输出会落在 D 标记之后逃出 B..D 捕获窗口，故由钩子在发 D
+ * 前 capture-pane 随流直送，宿主优先采用。 */
+const OSC133_RE = /\x1b\]133;([ABDCT])(?:;([^\x07\x1b]*))?(?:\x07|\x1b\\)/g;
 /** OSC 7 cwd 上报帧：\x1b]7;file://<host><path>(BEL|ST)。 */
 const OSC7_RE = /\x1b\]7;([^\x07\x1b]*)(?:\x07|\x1b\\)/g;
 /** 单条命令输出捕获上限（环形，超出丢头部）。 */
@@ -214,7 +242,14 @@ const FLUSH_INTERVAL_MS = 12;
 /** 待发输出超过该字符数时跳过窗口立即冲刷（防超长输出无限延迟）。 */
 const FLUSH_SIZE_CHARS = 64 * 1024;
 function createShellState() {
-    return { carry: '', inCommand: false, cmdBuffer: '', lastCommand: null };
+    return { carry: '', inCommand: false, cmdBuffer: '', pendingT: null, lastCommand: null };
+}
+/** OSC 133;T 的 base64 payload → utf8 文本（无效输入返回 null）。 */
+function decodeBase64Utf8(payload) {
+    if (payload === undefined || payload === '')
+        return null;
+    const text = Buffer.from(payload, 'base64').toString('utf8');
+    return text !== '' ? text : null;
 }
 /** OSC 7 body（file://host/path）→ 解码后的路径；解析失败返回 undefined。 */
 function osc7Path(body) {
@@ -244,11 +279,11 @@ function feedShellIntegration(session, text) {
     if (lastOpen !== -1) {
         const tail = data.slice(lastOpen);
         if (!/\x07|\x1b\\/.test(tail)) {
-            if (tail.length <= 512) {
+            if (tail.length <= 64 * 1024) {
                 state.carry = tail;
                 data = data.slice(0, lastOpen);
             }
-            // 超过 512B 仍不闭合视为垃圾：放弃扣留，整块照常处理
+            // 超过 64KB 仍不闭合视为垃圾：放弃扣留，整块照常处理（上限容纳 T 快照）
         }
     }
     for (const match of data.matchAll(OSC7_RE)) {
@@ -267,17 +302,22 @@ function feedShellIntegration(session, text) {
         if (kind === 'B') {
             state.inCommand = true;
             state.cmdBuffer = '';
+            state.pendingT = null;
+        }
+        else if (kind === 'T') {
+            state.pendingT = decodeBase64Utf8(match[2]);
         }
         else if (kind === 'D') {
             if (state.inCommand) {
-                const exitCode = match[2] !== undefined ? Number(match[2]) : null;
+                const exitCode = match[2] !== undefined && /^\d+$/.test(match[2]) ? Number(match[2]) : null;
                 state.lastCommand = {
-                    output: state.cmdBuffer.slice(-COMMAND_CAP),
+                    output: (state.pendingT ?? state.cmdBuffer).slice(-COMMAND_CAP),
                     exitCode: exitCode !== null && Number.isFinite(exitCode) ? exitCode : null,
                     endedAt: Date.now(),
                 };
                 state.inCommand = false;
                 state.cmdBuffer = '';
+                state.pendingT = null;
             }
         }
         // A（prompt 开始）无需记录
@@ -396,6 +436,7 @@ function sanitizeSshHosts(input) {
             passphrase: typeof raw.passphrase === 'string' ? raw.passphrase : '',
             password: typeof raw.password === 'string' ? raw.password : '',
             agentForward: raw.agentForward === true,
+            persist: raw.persist === true,
         });
     }
     return out;
@@ -431,6 +472,9 @@ function validateSshHosts(input) {
         if (raw.agentForward !== undefined && typeof raw.agentForward !== 'boolean') {
             return { error: 'sshHosts.agentForward 必须是布尔值' };
         }
+        if (raw.persist !== undefined && typeof raw.persist !== 'boolean') {
+            return { error: 'sshHosts.persist 必须是布尔值' };
+        }
         if ((raw.auth === 'key') && (typeof raw.keyPath !== 'string' || raw.keyPath.trim() === '')) {
             return { error: `sshHosts「${String(raw.name)}」auth=key 需要 keyPath` };
         }
@@ -482,6 +526,20 @@ function validateHostKeys(input) {
     }
     return { keys: sanitizeHostKeys(input) };
 }
+/** 宽松清洗一份 persistSessions（内部状态：SSH 持久会话名）；非法条目丢弃。 */
+function sanitizePersistSessions(input) {
+    if (!Array.isArray(input))
+        return undefined;
+    const out = [];
+    for (const item of input) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const name = item.tmuxName;
+        if (typeof name === 'string' && /^dsh-[A-Za-z0-9_-]{1,64}$/.test(name) && !out.includes(name))
+            out.push(name);
+    }
+    return out;
+}
 /**
  * TOFU 主机指纹存储：get/record 面向 spawnSsh 的 hostVerifier；
  * record 时经 persist 回调写入 settings（宿主重启后钉扎仍在）。
@@ -543,8 +601,12 @@ function isLoopbackUpgrade(req) {
 class SessionManager {
     sessions = new Map();
     limit;
-    constructor(maxSessions) {
+    /** 回收器销毁孤儿时是否连 tmux 持久会话一起结束（endOnPageClose 策略）。 */
+    endTmuxOnReap = () => false;
+    constructor(maxSessions, endTmuxOnReap) {
         this.limit = maxSessions;
+        if (endTmuxOnReap !== undefined)
+            this.endTmuxOnReap = endTmuxOnReap;
     }
     get limitValue() {
         return this.limit;
@@ -568,7 +630,7 @@ class SessionManager {
     get(id) {
         return this.sessions.get(id);
     }
-    /** 会话的只读快照（SSH 会话无本地 pid，该字段省略）。 */
+    /** 会话的只读快照（SSH 会话无本地 pid，该字段省略；tmux 持久会话带 persist）。 */
     snapshotOf(session) {
         const base = {
             sid: session.id,
@@ -577,6 +639,7 @@ class SessionManager {
             target: session.target,
             startedAt: session.startedAt,
             lastOutputAt: session.lastOutputAt,
+            ...(session.tmuxName !== null ? { persist: true } : {}),
         };
         return session.handle.pid === null ? base : { ...base, pid: session.handle.pid };
     }
@@ -588,9 +651,17 @@ class SessionManager {
     listForAttach() {
         return [...this.sessions.values()].map((session) => ({
             ...this.snapshotOf(session),
-            attachable: session.ws === null && !session.closed,
+            attachable: session.clients.size === 0 && !session.closed,
         }));
     }
+    /** 按 tmux 持久会话名查找存活会话（跨窗口共享用）；不存在/已关闭返回 undefined。 */
+    findByTmuxName(tmuxName) {
+        for (const session of this.sessions.values()) {
+            if (session.tmuxName === tmuxName && !session.closed)
+                return session;
+        }
+        return undefined;
+    }
     /** 同步退役：移出全局表 + 释放虚拟屏（幂等，不杀进程）。 */
     retire(session) {
         session.closed = true;
@@ -602,9 +673,18 @@ class SessionManager {
             /* 已释放 */
         }
     }
-    /** 释放并销毁会话：退役 + 树级终止（等待 terminate 完成，最慢 ~20s）。 */
+    /** 释放并销毁会话：退役 + 树级终止（等待 terminate 完成，最慢 ~20s）。
+     *  endOnPageClose 策略下，回收器销毁孤儿时连 tmux 持久会话一起结束。 */
     async destroy(session) {
         this.retire(session);
+        if (session.tmuxName !== null && this.endTmuxOnReap()) {
+            try {
+                await session.handle.tmuxTeardown?.();
+            }
+            catch {
+                /* tmux 收尾失败不阻断回收 */
+            }
+        }
         await forceKill(session.handle);
     }
     /** 回收超过保活期的孤儿会话（回收器定时调用；graceMs<=0 时不动作）。 */
@@ -641,12 +721,18 @@ class TtyServer {
     sessions;
     options;
     hostKeyStore;
+    trackPersist;
     wss = new WebSocketServer({ noServer: true });
-    constructor(ctx, sessions, options, hostKeyStore) {
+    /** 在途的持久会话创建（tmuxName → 创建 promise）：dsh 重启后多页面并发恢复时收敛竞态。 */
+    pendingTmux = new Map();
+    constructor(ctx, sessions, options, hostKeyStore, 
+    /** SSH 持久会话名留存回调（apply 闭包实现，settings 落盘）。 */
+    trackPersist) {
         this.ctx = ctx;
         this.sessions = sessions;
         this.options = options;
         this.hostKeyStore = hostKeyStore;
+        this.trackPersist = trackPersist;
         this.wss.on('connection', (ws) => this.onConnection(ws));
     }
     /** registerUpgrade 的 handler（loopback 围栏 + ws 握手）。 */
@@ -663,16 +749,21 @@ class TtyServer {
         /** 本连接上的会话表（sid → session）；单连接多会话（标签页）。 */
         const local = new Map();
         const cleanupAll = async () => {
-            const all = [...local.values()];
+            const all = [...local.entries()];
             local.clear();
-            await Promise.all(all.map(async (session) => {
+            await Promise.all(all.map(async ([clientSid, session]) => {
                 if (session.closed)
                     return;
+                // 解绑本连接的客户端；其余窗口仍绑定着（跨连接共享）时会话继续在线
+                session.clients.delete(clientSid);
+                if (session.clients.size > 0) {
+                    this.flushPendingOutput(session);
+                    return;
+                }
                 if (this.options.reconnectGraceMs > 0) {
                     // 客户端正常关面板会先逐个 kill（会话已移出 local），走到这里的都是
                     // 「异常断开仍有存活会话」：转孤儿保活，等待新连接 attach，到点由回收器清理
                     this.flushPendingOutput(session); // 没了收件人，待发帧直接丢弃（回放走环形缓冲）
-                    session.ws = null;
                     session.orphanedAt = Date.now();
                     return;
                 }
@@ -720,13 +811,66 @@ class TtyServer {
         send(ws, { t: 'error', m: local.size === 0 ? '没有可用会话（先发 spawn）' : '存在多个会话，请指定 sid' });
         return undefined;
     }
+    /** 把一个客户端连接重绑定到既有会话（跨窗口共享 / 并发恢复收敛共用）。 */
+    rebindClient(session, sid, ws, local) {
+        session.clients.set(sid, ws);
+        session.orphanedAt = null;
+        if (session.paused) {
+            session.paused = false;
+            try {
+                session.handle.output.resume();
+            }
+            catch {
+                /* 已退出 */
+            }
+        }
+        local.set(sid, session);
+        send(ws, {
+            t: 'ready',
+            sid,
+            pid: session.handle.pid,
+            kind: session.kind,
+            target: session.target !== '' ? session.target : undefined,
+            ...(session.tmuxName !== null ? { persist: true } : {}),
+        });
+        if (session.tmuxName !== null)
+            void session.handle.tmuxRefresh?.();
+    }
+    /** 等待同 tmuxName 的在途创建完成；返回可重绑定的会话（null = 无在途/已失败）。 */
+    async waitPendingTmux(tmuxName) {
+        const inflight = this.pendingTmux.get(tmuxName);
+        if (inflight === undefined)
+            return null;
+        try {
+            return await inflight;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * 立即终止会话：同步退役 + 顶层 shell 直接 SIGKILL，让 done/exit 帧立刻可发；
      * 树级子进程清理（SIGTERM→grace→SIGKILL，交互式 zsh 忽略 SIGTERM 时最慢
      * 可拖 ~20s）由 terminate 在后台继续收尾，不阻塞 kill 帧处理。
+     * tmux 背书会话先向 tmux server 发 kill-session（杀客户端只会 detach，
+     * 会话会留在 tmux server 上）；2.5s 兜底 forceKill 防收尾悬挂。
      */
     killSessionNow(session) {
         this.sessions.retire(session);
+        const teardown = session.handle.tmuxTeardown;
+        if (teardown !== undefined) {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                void forceKill(session.handle);
+            };
+            const timer = setTimeout(finish, 2500);
+            timer.unref?.();
+            void teardown().catch(() => { }).then(finish);
+            return;
+        }
         try {
             session.handle.forceKill?.();
         }
@@ -757,8 +901,25 @@ class TtyServer {
                     send(ws, { t: 'error', sid, m: 'sid 已存在' });
                     return;
                 }
+                // 持久化（0.10.0）：配置 persistence=tmux 且帧带 persist 时，spawn 包装层
+                // 换成 `exec tmux -L dsh-tty -A -s <名>`（tmux 托管）；tmux 未安装则降级
+                // 普通会话并回灰字提示。持久名稳定（客户端生成、随标签规格保存），
+                // 宿主重启后重开标签按同名 attach 回原 tmux 会话
+                const persistName = msg.persist === true && this.options.persistence === 'tmux'
+                    ? sanitizePersistName(msg.persistName, sid)
+                    : null;
+                // 跨窗口共享（0.10.1）：同 tmuxName 的宿主会话还活着（别的窗口接回过，
+                // 或同刻并发恢复的在途创建）时不再新建 PTY，本连接重绑定到它——
+                // 单 PTY 多客户端扇出，名额不翻倍
+                if (persistName !== null) {
+                    const existing = (this.sessions.findByTmuxName(persistName) ?? (await this.waitPendingTmux(persistName))) ?? null;
+                    if (existing !== null) {
+                        this.rebindClient(existing, sid, ws, local);
+                        return;
+                    }
+                }
                 if (!this.sessions.canSpawn()) {
-                    send(ws, { t: 'error', sid, m: `会话数已达上限（${this.sessions.limitValue}）` });
+                    send(ws, { t: 'error', sid, m: `会话数已达上限（${this.sessions.limitValue}）——每个窗口的每个标签各占一个名额：关闭不用的窗口/标签，或在设置卡片调大「并发会话上限」` });
                     return;
                 }
                 // 客户端（当前会话）cwd 优先；校验存在性，避免 node-pty 抛难懂错误
@@ -772,37 +933,70 @@ 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: spawnPlan.argv,
-                    rows: Number(msg.rows) || 24,
-                    cols: Number(msg.cols) || 80,
-                    cwd,
-                    env: { TERM: this.options.term, COLORTERM: this.options.colorTerm, ...spawnPlan.env },
-                    graceMs: 5000,
-                }));
-                const next = {
-                    id: sid,
-                    handle,
-                    ws,
-                    closed: false,
-                    paused: false,
-                    cwd,
-                    kind: 'local',
-                    target: '',
-                    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' });
+                const wantsPersist = persistName !== null;
+                let spawnPlan = buildShellSpawn(this.options.shell, this.options.term, this.options.colorTerm, this.options.shellIntegration);
+                let tmuxName = null;
+                if (wantsPersist) {
+                    const probe = await probeTmux();
+                    if (probe.available) {
+                        tmuxName = persistName;
+                        ensureTmuxAssets({ shell: this.options.shell, colorTerm: this.options.colorTerm, shellIntegration: this.options.shellIntegration, passthrough: probe.passthrough });
+                        spawnPlan = buildTmuxSpawnPlan({ shell: this.options.shell, term: this.options.term, colorTerm: this.options.colorTerm, tmuxName });
+                    }
+                }
+                // 在途注册：tmuxName 相同的并发 spawn 等本次创建完成后重绑定（防竞态翻倍）
+                const create = (async () => {
+                    const handle = wrapLocalPty(await subprocess.spawnTerminal({
+                        argv: spawnPlan.argv,
+                        rows: Number(msg.rows) || 24,
+                        cols: Number(msg.cols) || 80,
+                        cwd,
+                        env: { TERM: this.options.term, COLORTERM: this.options.colorTerm, ...spawnPlan.env },
+                        graceMs: 5000,
+                    }));
+                    if (tmuxName !== null) {
+                        handle.tmuxTeardown = () => killTmuxSession(tmuxName);
+                        handle.tmuxRefresh = () => refreshTmuxClient(tmuxName);
+                    }
+                    const next = {
+                        id: sid,
+                        handle,
+                        clients: new Map([[sid, ws]]),
+                        closed: false,
+                        paused: false,
+                        cwd,
+                        kind: 'local',
+                        target: '',
+                        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,
+                        tmuxName,
+                    };
+                    local.set(sid, next);
+                    this.sessions.add(next);
+                    return next;
+                })();
+                if (tmuxName !== null) {
+                    const registered = create.catch(() => null);
+                    this.pendingTmux.set(tmuxName, registered);
+                    void registered.finally(() => {
+                        if (this.pendingTmux.get(tmuxName) === registered)
+                            this.pendingTmux.delete(tmuxName);
+                    });
+                }
+                const next = await create;
+                send(ws, { t: 'ready', sid, pid: next.handle.pid, kind: 'local', ...(tmuxName !== null ? { persist: true } : {}) });
+                if (wantsPersist && tmuxName === null) {
+                    const notice = '\x1b[2m[dsh-tty] 未检测到 tmux，本标签以普通会话运行；安装 tmux 后持久化标签可跨宿主重启恢复现场\x1b[0m\r\n';
+                    next.buffer = (next.buffer + notice).slice(-BUFFER_CAP);
+                    send(ws, { t: 'data', sid, d: notice });
+                }
                 this.attachOutput(next);
                 this.watchDone(next, local);
             }
@@ -816,77 +1010,108 @@ class TtyServer {
                     send(ws, { t: 'error', sid, m: 'sid 已存在' });
                     return;
                 }
-                if (!this.sessions.canSpawn()) {
-                    send(ws, { t: 'error', sid, m: `会话数已达上限（${this.sessions.limitValue}）` });
-                    return;
+                // 跨窗口共享（0.10.1）：同 tmuxName 的 SSH 持久会话还活着时不重建远程
+                // 连接，本连接重绑定到现有会话（单 PTY 多客户端扇出）
+                const persistName = msg.persist === true && this.options.persistence === 'tmux'
+                    ? sanitizePersistName(msg.persistName, sid)
+                    : null;
+                if (persistName !== null) {
+                    const existing = (this.sessions.findByTmuxName(persistName) ?? (await this.waitPendingTmux(persistName))) ?? null;
+                    if (existing !== null && existing.kind === 'ssh' && !existing.closed) {
+                        this.rebindClient(existing, sid, ws, local);
+                        return;
+                    }
                 }
-                // name 引用连接簿条目作基底，内联字段可逐项覆盖
-                const profile = typeof msg.name === 'string' && msg.name !== '' ? this.options.findSshHost(msg.name) : undefined;
-                if (typeof msg.name === 'string' && msg.name !== '' && profile === undefined) {
-                    send(ws, { t: 'error', sid, m: `连接簿中不存在: ${msg.name}` });
+                if (!this.sessions.canSpawn()) {
+                    send(ws, { t: 'error', sid, m: `会话数已达上限（${this.sessions.limitValue}）——每个窗口的每个标签各占一个名额：关闭不用的窗口/标签，或在设置卡片调大「并发会话上限」` });
                     return;
                 }
-                const spec = {
-                    host: typeof msg.host === 'string' && msg.host.trim() !== '' ? msg.host.trim() : profile?.host ?? '',
-                    port: Number(msg.port) || profile?.port || 22,
-                    username: typeof msg.username === 'string' && msg.username.trim() !== '' ? msg.username.trim() : profile?.username ?? '',
-                    auth: msg.auth === 'key' || msg.auth === 'password' || msg.auth === 'agent' ? msg.auth : profile?.auth ?? 'agent',
-                    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 引用连接簿）' });
+                // name 引用连接簿条目作基底，内联字段可逐项覆盖（与 SFTP 路由共用 mergeSshSpec）
+                const merged = mergeSshSpec((name) => this.options.findSshHost(name), msg.name, msg);
+                if (merged.error !== undefined || merged.spec === undefined) {
+                    send(ws, { t: 'error', sid, m: merged.error ?? 'SSH 连接参数缺失' });
                     return;
                 }
+                const spec = merged.spec;
                 const target = sshTarget(spec);
                 send(ws, { t: 'data', sid, d: `\x1b[2mConnecting ${target} …\x1b[0m\r\n` });
-                let handle;
-                try {
-                    handle = await spawnSsh(spec, {
-                        term: this.options.term,
-                        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,
+                // 持久化（0.10.0）：远程 `exec tmux new-session -A` 托管；远程无 tmux 时
+                // spawnSsh 降级普通 shell channel 并经 startupNotice 回灰字提示
+                const wantsPersist = persistName !== null;
+                const persistOpt = wantsPersist ? { name: persistName } : undefined;
+                // 在途注册：同 persistName 的并发恢复等待本次创建完成后重绑定（防竞态翻倍）
+                const create = (async () => {
+                    let handle;
+                    try {
+                        handle = await spawnSsh(spec, {
+                            term: this.options.term,
+                            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,
+                            ...(persistOpt !== undefined ? { persist: persistOpt } : {}),
+                        });
+                    }
+                    catch (error) {
+                        send(ws, { t: 'error', sid, m: error instanceof Error ? error.message : String(error) });
+                        throw error;
+                    }
+                    const tmuxName = persistOpt !== undefined && handle.startupNotice === undefined ? persistOpt.name : null;
+                    const next = {
+                        id: sid,
+                        handle,
+                        clients: new Map([[sid, ws]]),
+                        closed: false,
+                        paused: false,
+                        cwd: '',
+                        kind: 'ssh',
+                        target,
+                        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,
+                        tmuxName,
+                    };
+                    local.set(sid, next);
+                    this.sessions.add(next);
+                    send(ws, { t: 'ready', sid, pid: null, kind: 'ssh', target, ...(tmuxName !== null ? { persist: true } : {}) });
+                    if (tmuxName !== null)
+                        this.trackPersist(tmuxName, true); // 留存：远程 tmux 本机清单看不到
+                    if (handle.startupNotice !== undefined) {
+                        const notice = `\x1b[2m[dsh-tty] ${handle.startupNotice}\x1b[0m\r\n`;
+                        next.buffer = (next.buffer + notice).slice(-BUFFER_CAP);
+                        send(ws, { t: 'data', sid, d: notice });
+                    }
+                    this.attachOutput(next);
+                    this.watchDone(next, local);
+                    return next;
+                })();
+                if (persistName !== null) {
+                    const registered = create.catch(() => null);
+                    this.pendingTmux.set(persistName, registered);
+                    void registered.finally(() => {
+                        if (this.pendingTmux.get(persistName) === registered)
+                            this.pendingTmux.delete(persistName);
                     });
                 }
-                catch (error) {
-                    send(ws, { t: 'error', sid, m: error instanceof Error ? error.message : String(error) });
-                    return;
+                try {
+                    await create;
+                }
+                catch {
+                    return; // 错误帧已在创建闭包内发送
                 }
-                const next = {
-                    id: sid,
-                    handle,
-                    ws,
-                    closed: false,
-                    paused: false,
-                    cwd: '',
-                    kind: 'ssh',
-                    target,
-                    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);
             }
             else if (msg.t === 'input') {
                 const resolved = this.resolveSid(ws, msg, local);
                 if (resolved === undefined || 'unknown' in resolved)
                     return;
                 const session = local.get(resolved.sid);
-                if (session !== undefined)
+                if (session !== undefined && !session.closed)
                     await session.handle.write(String(msg.d ?? ''));
             }
             else if (msg.t === 'resize') {
@@ -906,6 +1131,18 @@ class TtyServer {
                     }
                 }
             }
+            else if (msg.t === 'refresh') {
+                // 强制 tmux 重画（0.10.1）：客户端 reset 清掉残 scrollback 后请宿主
+                // refresh-client 重画现场——不碰尺寸，规避隐藏标签下 proposeDimensions
+                // 返回垃圾尺寸把 pane 压扁的隐患；非 tmux 会话为无害 no-op
+                const resolved = this.resolveSid(ws, msg, local);
+                if (resolved === undefined || 'unknown' in resolved)
+                    return;
+                const session = local.get(resolved.sid);
+                if (session !== undefined && !session.closed && session.tmuxName !== null) {
+                    void session.handle.tmuxRefresh?.();
+                }
+            }
             else if (msg.t === 'kill') {
                 const resolved = this.resolveSid(ws, msg, local);
                 if (resolved === undefined)
@@ -927,7 +1164,12 @@ class TtyServer {
                 this.killSessionNow(session);
             }
             else if (msg.t === 'sessions') {
-                send(ws, { t: 'sessions', list: this.sessions.listForAttach() });
+                // tmux 字段（0.10.1）：本机 socket 现存持久会话 + SSH 持久会话名（远程
+                // tmux 托管、本机清单看不到，从 settings 留存读取）——客户端用它确认
+                // localStorage 里的持久标签规格是否仍可恢复（新窗口/新浏览器）
+                const localTmux = await listTmuxSessions();
+                const tmuxSessions = [...new Set([...localTmux, ...this.options.persistSessions])];
+                send(ws, { t: 'sessions', list: this.sessions.listForAttach(), tmux: tmuxSessions });
             }
             else if (msg.t === 'attach') {
                 const raw = msg.sid;
@@ -940,14 +1182,16 @@ class TtyServer {
                     send(ws, { t: 'error', sid: raw, m: `会话不存在或已结束: ${raw}` });
                     return;
                 }
-                if (session.ws !== null) {
+                // 跨连接共享（0.10.1）：tmux 持久会话允许多窗口同时绑定（单 PTY 扇出）；
+                // 非 tmux 会话仍独占（两个视图交错输入无意义）
+                if (session.clients.size > 0 && session.tmuxName === null) {
                     send(ws, { t: 'error', sid: raw, m: '会话已连接到其它窗口' });
                     return;
                 }
-                // 重新绑定到本连接：解孤儿态，恢复被背压暂停的输出流
-                session.ws = ws;
+                // 重新绑定到本连接（key = 本连接侧的 sid）：解孤儿态，恢复被背压暂停的输出流
+                session.clients.set(raw, ws);
                 session.orphanedAt = null;
-                local.set(session.id, session);
+                local.set(raw, session);
                 if (session.paused) {
                     session.paused = false;
                     try {
@@ -957,10 +1201,17 @@ class TtyServer {
                         /* 已退出 */
                     }
                 }
-                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 });
+                send(ws, { t: 'ready', sid: raw, pid: session.handle.pid, kind: session.kind, target: session.target !== '' ? session.target : undefined, reattached: true, ...(session.tmuxName !== null ? { persist: true } : {}) });
+                // 断线期间的输出经 256KB 环形缓冲回放（缓冲为空则跳过）。
+                // tmux 背书会话例外：现场由 tmux 负责重画——回放会把缓冲里的可见屏
+                // 先写进全新 xterm（制造屏外幽灵滚动历史 → 莫名滚动条），随后 tmux
+                // 整屏重画再画一遍（内容重影）；故跳过回放，强制 tmux 重画一次
+                if (session.tmuxName !== null) {
+                    void session.handle.tmuxRefresh?.();
+                }
+                else if (session.buffer !== '') {
+                    send(ws, { t: 'data', sid: raw, d: session.buffer });
+                }
             }
         }
         catch (error) {
@@ -978,6 +1229,8 @@ class TtyServer {
             session.closed = true;
             local.delete(session.id);
             this.sessions.remove(session.id);
+            if (session.kind === 'ssh' && session.tmuxName !== null)
+                this.trackPersist(session.tmuxName, false);
             try {
                 session.screen?.dispose();
             }
@@ -985,7 +1238,11 @@ class TtyServer {
                 /* 已释放 */
             }
             this.flushPendingOutput(session); // exit 前冲掉合并窗口里的尾巴，保序
-            send(session.ws, { t: 'exit', sid: session.id, code: outcome.exitCode, signal: outcome.signal });
+            // exit 广播到所有绑定连接（跨窗口共享），各客户端按自己的 sid 收址
+            for (const [clientSid, clientWs] of session.clients) {
+                send(clientWs, { t: 'exit', sid: clientSid, code: outcome.exitCode, signal: outcome.signal });
+            }
+            session.clients.clear();
         }).catch(() => { });
     }
     /** 输出下行 + 基于 ws.bufferedAmount 的背压（暂停/恢复 PassThrough）。 */
@@ -993,17 +1250,25 @@ class TtyServer {
         const output = session.handle.output;
         const flush = () => {
             session.flushTimer = null;
-            const ws = session.ws;
             const pending = session.pendingOutput;
-            if (session.closed || ws === null || pending === '')
+            if (session.closed || session.clients.size === 0 || 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();
+            let maxBuffered = 0;
+            for (const [clientSid, clientWs] of session.clients) {
+                try {
+                    clientWs.send(JSON.stringify({ t: 'data', sid: clientSid, d: pending }), () => {
+                        if (session.paused && clientWs.bufferedAmount < BACKPRESSURE_LOW && output.readableFlowing === false) {
+                            output.resume();
+                        }
+                    });
+                    maxBuffered = Math.max(maxBuffered, clientWs.bufferedAmount);
                 }
-            });
-            if (!session.paused && ws.bufferedAmount > BACKPRESSURE_HIGH) {
+                catch {
+                    /* 客户端已断开 */
+                }
+            }
+            if (!session.paused && maxBuffered > BACKPRESSURE_HIGH) {
                 session.paused = true;
                 output.pause();
             }
@@ -1022,8 +1287,7 @@ class TtyServer {
             catch {
                 /* 虚拟屏异常不阻断输出链路 */
             }
-            const ws = session.ws;
-            if (ws === null)
+            if (session.clients.size === 0)
                 return; // 孤儿会话：仅积累缓冲，等待重连 attach 回放
             // data 帧合并：窗口内攒批，超阈值立即冲刷；exit/kill 前会强制 flush 保序
             session.pendingOutput += text;
@@ -1048,12 +1312,13 @@ class TtyServer {
             clearTimeout(session.flushTimer);
             session.flushTimer = null;
         }
-        const ws = session.ws;
         const pending = session.pendingOutput;
         session.pendingOutput = '';
-        if (session.closed || ws === null || pending === '')
+        if (session.closed || session.clients.size === 0 || pending === '')
             return;
-        send(ws, { t: 'data', sid: session.id, d: pending });
+        for (const [clientSid, clientWs] of session.clients) {
+            send(clientWs, { t: 'data', sid: clientSid, d: pending });
+        }
     }
     close() {
         for (const client of this.wss.clients) {
@@ -1098,6 +1363,71 @@ function readManagedEnvKeys() {
         return [];
     }
 }
+/**
+ * 设置卡片「Shell 路径」候选（可选可输入的数据源）：/etc/shells + $SHELL +
+ * 常见安装路径，去重后过滤「存在且可执行」，$SHELL 排最前。只回路径，
+ * 不做任何执行。
+ */
+function listCandidateShells() {
+    const candidates = [];
+    const push = (value) => {
+        const path = value?.trim() ?? '';
+        if (path !== '' && !candidates.includes(path))
+            candidates.push(path);
+    };
+    try {
+        for (const line of readFileSync('/etc/shells', 'utf8').split('\n')) {
+            const path = line.trim();
+            if (path !== '' && !path.startsWith('#'))
+                push(path);
+        }
+    }
+    catch {
+        /* 无 /etc/shells（如 Windows）时跳过 */
+    }
+    push(process.env.SHELL);
+    for (const path of [
+        '/bin/zsh', '/usr/bin/zsh', '/usr/local/bin/zsh', '/opt/homebrew/bin/zsh',
+        '/bin/bash', '/usr/bin/bash', '/usr/local/bin/bash', '/opt/homebrew/bin/bash',
+        '/bin/fish', '/usr/bin/fish', '/usr/local/bin/fish', '/opt/homebrew/bin/fish',
+        '/bin/sh', '/bin/dash', '/bin/ksh', '/bin/tcsh', '/bin/csh',
+    ])
+        push(path);
+    const usable = candidates.filter((path) => {
+        try {
+            accessSync(path, fsConstants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    const shell = process.env.SHELL?.trim() ?? '';
+    usable.sort((a, b) => (a === shell ? -1 : b === shell ? 1 : a.localeCompare(b)));
+    return usable;
+}
+/**
+ * 「连接簿条目作基底 + 内联字段逐项覆盖」的共享解析（WS ssh 帧与 SFTP 路由共用）。
+ * name 指向连接簿缺失条目、或解析结果缺 host/username 时返回 error。
+ */
+function mergeSshSpec(findSshHost, name, inline) {
+    const profile = typeof name === 'string' && name !== '' ? findSshHost(name) : undefined;
+    if (typeof name === 'string' && name !== '' && profile === undefined)
+        return { error: `连接簿中不存在: ${name}` };
+    const spec = {
+        host: typeof inline.host === 'string' && inline.host.trim() !== '' ? inline.host.trim() : profile?.host ?? '',
+        port: Number(inline.port) || profile?.port || 22,
+        username: typeof inline.username === 'string' && inline.username.trim() !== '' ? inline.username.trim() : profile?.username ?? '',
+        auth: inline.auth === 'key' || inline.auth === 'password' || inline.auth === 'agent' ? inline.auth : profile?.auth ?? 'agent',
+        keyPath: typeof inline.keyPath === 'string' && inline.keyPath !== '' ? inline.keyPath : profile?.keyPath,
+        passphrase: typeof inline.passphrase === 'string' && inline.passphrase !== '' ? inline.passphrase : profile?.passphrase,
+        password: typeof inline.password === 'string' && inline.password !== '' ? inline.password : profile?.password,
+        agentForward: typeof inline.agentForward === 'boolean' ? inline.agentForward : profile?.agentForward ?? false,
+    };
+    if (spec.host === '' || spec.username === '')
+        return { error: 'SSH 会话需要 host 与 username（或用 name 引用连接簿）' };
+    return { spec };
+}
 /** HTTP 路由的 loopback 信任围栏（与 dsh-mcp 同思路）。 */
 function isLoopbackHttp(req) {
     const address = req.socket.remoteAddress;
@@ -1131,6 +1461,31 @@ function writeJson(res, status, body) {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'referrer-policy': 'no-referrer' });
     res.end(JSON.stringify(body));
 }
+/** 下载响应的 content-disposition：ASCII 兜底 + RFC 5987 UTF-8 扩展（非 ASCII 文件名）。 */
+function contentDispositionValue(name) {
+    const ascii = name.replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_');
+    return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+}
+/** 远程路径取末段（下载文件名展示用）；空串/根路径退化为 'download'。 */
+function remoteBasename(path) {
+    const trimmed = path.trim().replace(/\/+$/, '');
+    const index = trimmed.lastIndexOf('/');
+    const base = index >= 0 ? trimmed.slice(index + 1) : trimmed;
+    return base === '' ? 'download' : base;
+}
+/** 人类可读文件大小（sftp_list render 用）。 */
+function humanFileSize(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = bytes;
+    let index = 0;
+    while (value >= 1024 && index < units.length - 1) {
+        value /= 1024;
+        index += 1;
+    }
+    return `${value >= 100 || index === 0 ? Math.round(value) : Math.round(value * 10) / 10} ${units[index]}`;
+}
 async function readJsonBody(req) {
     const chunks = [];
     let size = 0;
@@ -1153,6 +1508,34 @@ async function readJsonBody(req) {
         return undefined;
     }
 }
+/**
+ * 本机目录列表（/api/dsh-tty/local-fs/list）：path 空 = 用户 home，返回实际
+ * 绝对路径。stat 失败的条目（悬空符号链接等）按 size/mtime = 0 占位仍列出。
+ */
+async function listLocalDir(rawPath) {
+    const root = rawPath !== '' ? expandHome(rawPath) : homedir();
+    const resolved = resolve(root);
+    const dirents = await fsReaddir(resolved, { withFileTypes: true });
+    const entries = [];
+    for (const dirent of dirents) {
+        let isDir = dirent.isDirectory();
+        let isFile = dirent.isFile();
+        let size = 0;
+        let mtime = 0;
+        try {
+            const stats = await fsStat(join(resolved, dirent.name));
+            isDir = stats.isDirectory();
+            isFile = stats.isFile();
+            size = Number(stats.size ?? 0);
+            mtime = Number(stats.mtimeMs ?? 0);
+        }
+        catch {
+            /* stat 失败：保留 dirent 类型判断，占位展示 */
+        }
+        entries.push({ name: dirent.name, isDir, isFile, isSymlink: dirent.isSymbolicLink(), size, mtime });
+    }
+    return { path: resolved, entries };
+}
 const plugin = definePlugin({
     name: 'tty',
     // 声明 inject：tools 服务只有声明式 inject 才能解析（动态 ctx.inject/ctx.get
@@ -1171,8 +1554,11 @@ const plugin = definePlugin({
             hostKeys: Array.isArray(config?.hostKeys) ? config.hostKeys : [],
             shellIntegration: config?.shellIntegration !== false,
             tunnels: Array.isArray(config?.tunnels) ? config.tunnels : [],
+            persistence: config?.persistence === 'tmux' ? 'tmux' : 'off',
+            endOnPageClose: config?.endOnPageClose === true,
+            persistSessions: sanitizePersistSessions(config?.persistSessions) ?? [],
         });
-        const sessions = new SessionManager(config?.maxSessions ?? DEFAULT_MAX_SESSIONS);
+        const sessions = new SessionManager(config?.maxSessions ?? DEFAULT_MAX_SESSIONS, () => live.endOnPageClose);
         /** TOFU 指纹记录持久化：写入 settings 命名空间（合并语义），失败不影响连接。 */
         const persistHostKeys = (records) => {
             const scope = settingsScope;
@@ -1183,9 +1569,31 @@ const plugin = definePlugin({
             });
         };
         const hostKeyStore = new HostKeyStore(live, persistHostKeys);
+        /** SSH 持久会话名留存（远程 tmux 本机 socket 看不到；新窗口恢复确认的数据源）。 */
+        const persistPersistSessions = () => {
+            const scope = settingsScope;
+            if (scope === undefined)
+                return;
+            void Promise.resolve(scope.update({ persistSessions: live.persistSessions.map((name) => ({ tmuxName: name })) })).catch((error) => {
+                console.warn('[dsh-tty] 持久会话名留存失败: ' + (error instanceof Error ? error.message : String(error)));
+            });
+        };
+        /** 记录/移除一个 SSH 持久会话名并落盘（幂等）。 */
+        const trackPersistSession = (tmuxName, present) => {
+            const next = present
+                ? (live.persistSessions.includes(tmuxName) ? live.persistSessions : [...live.persistSessions, tmuxName])
+                : live.persistSessions.filter((name) => name !== tmuxName);
+            if (next.join('|') === live.persistSessions.join('|'))
+                return;
+            live.persistSessions = next;
+            persistPersistSessions();
+        };
         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 };
+        // SFTP 文件传输：懒连接池 + TOFU 同源（见 src/sftp.ts）；spec 由各请求携带
+        // （连接簿名或内联字段），连接簿凭证热改后天然生效
+        const sftpManager = new SftpManager({ info: (m) => ctx.logger.info(m), warn: (m) => ctx.logger.warn(m) }, hostKeyStore);
+        const server = new TtyServer(ctx, sessions, live, hostKeyStore, trackPersistSession);
+        const stateRef = { enabled: true, announceToAgent: config?.announceToAgent !== false, toolsRegistered: false, sftpStyle: config?.sftpStyle === 'dual' ? 'dual' : 'dialog' };
         let settingsScope;
         const snapshot = () => ({
             enabled: stateRef.enabled,
@@ -1200,6 +1608,9 @@ const plugin = definePlugin({
             hostKeys: live.hostKeys,
             tunnels: live.tunnels,
             shellIntegration: live.shellIntegration,
+            sftpStyle: stateRef.sftpStyle,
+            persistence: live.persistence,
+            endOnPageClose: live.endOnPageClose,
             toolsRegistered: stateRef.toolsRegistered,
         });
         /** 规范化并应用一份配置补丁（settings/updated 事件与 HTTP POST 共用；幂等）。 */
@@ -1214,6 +1625,9 @@ const plugin = definePlugin({
                 hostKeys: sanitizeHostKeys(section.hostKeys),
                 shellIntegration: typeof section.shellIntegration === 'boolean' ? section.shellIntegration : undefined,
                 tunnels: sanitizeTunnels(section.tunnels),
+                persistence: section.persistence === 'tmux' || section.persistence === 'off' ? section.persistence : undefined,
+                endOnPageClose: typeof section.endOnPageClose === 'boolean' ? section.endOnPageClose : undefined,
+                persistSessions: sanitizePersistSessions(section.persistSessions),
             });
             // 隧道按最新规格对齐（幂等；sshHosts 变更也会触发，让重连取到新凭证）
             tunnelManager.reconcile(live.tunnels);
@@ -1224,12 +1638,14 @@ const plugin = definePlugin({
                 stateRef.enabled = section.enabled;
             if (typeof section.announceToAgent === 'boolean')
                 stateRef.announceToAgent = section.announceToAgent;
+            if (section.sftpStyle === 'dialog' || section.sftpStyle === 'dual')
+                stateRef.sftpStyle = section.sftpStyle;
             console.log(`[dsh-tty] config applied (shell=${live.shell}, term=${live.term}, cwd=${live.cwd}, maxSessions=${sessions.limitValue}, sshHosts=${live.sshHosts.length})`);
         };
         /** 校验 HTTP POST 的配置体；返回规范化补丁或错误信息。 */
         const normalizePatch = (input) => {
             const patch = {};
-            const known = new Set(['enabled', 'announceToAgent', 'maxSessions', 'shell', 'term', 'colorTerm', 'cwd', 'reconnectGraceSec', 'sshHosts', 'hostKeys', 'tunnels', 'shellIntegration']);
+            const known = new Set(['enabled', 'announceToAgent', 'maxSessions', 'shell', 'term', 'colorTerm', 'cwd', 'reconnectGraceSec', 'sshHosts', 'hostKeys', 'tunnels', 'shellIntegration', 'sftpStyle', 'persistence', 'endOnPageClose']);
             for (const key of Object.keys(input)) {
                 if (!known.has(key))
                     return { error: '未知配置项: ' + key };
@@ -1261,6 +1677,21 @@ const plugin = definePlugin({
                     return { error: 'shellIntegration 必须是布尔值' };
                 patch.shellIntegration = input.shellIntegration;
             }
+            if (input.sftpStyle !== undefined) {
+                if (input.sftpStyle !== 'dialog' && input.sftpStyle !== 'dual')
+                    return { error: 'sftpStyle 必须是 dialog 或 dual' };
+                patch.sftpStyle = input.sftpStyle;
+            }
+            if (input.persistence !== undefined) {
+                if (input.persistence !== 'off' && input.persistence !== 'tmux')
+                    return { error: 'persistence 必须是 off 或 tmux' };
+                patch.persistence = input.persistence;
+            }
+            if (input.endOnPageClose !== undefined) {
+                if (typeof input.endOnPageClose !== 'boolean')
+                    return { error: 'endOnPageClose 必须是布尔值' };
+                patch.endOnPageClose = input.endOnPageClose;
+            }
             for (const key of ['shell', 'term', 'colorTerm']) {
                 if (input[key] === undefined)
                     continue;
@@ -1416,6 +1847,22 @@ const plugin = definePlugin({
                         }
                     },
                 }));
+                // 已安装 shell 候选（设置卡片「Shell 路径」可选可输入）：loopback 围栏，只回路径不执行
+                disposers.push(webServer.register({
+                    kind: 'exact',
+                    path: '/api/dsh-tty/shells',
+                    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, shells: listCandidateShells(), current: process.env.SHELL ?? '' });
+                    },
+                }));
                 // 端口转发隧道实时状态（设置卡片轮询徽标 + tunnel_list 工具数据源）
                 disposers.push(webServer.register({
                     kind: 'exact',
@@ -1432,6 +1879,228 @@ const plugin = definePlugin({
                         writeJson(res, 200, { ok: true, tunnels: tunnelManager.list() });
                     },
                 }));
+                // SFTP 文件传输（0.7.0，src/sftp.ts）：loopback 围栏；spec 解析与 WS ssh
+                // 帧同款（mergeSshSpec：连接簿条目作基底 + 内联字段覆盖）。list/mkdir/
+                // rename/remove/download 走 JSON 体（凭证不进 URL/查询串）；download 响应
+                // 为文件字节流（stat 成功时带 content-length）；upload 以 x-dsh-sftp-meta
+                // 头携带 base64url(JSON)（spec + path + append），请求体即原始文件字节，
+                // pipeline 直灌 SFTP 写流——上传下载都不整文件进内存。
+                disposers.push(webServer.register({
+                    kind: 'prefix',
+                    path: '/api/dsh-tty/sftp',
+                    handler: async (req, res) => {
+                        if (!isLoopbackHttp(req)) {
+                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                            return;
+                        }
+                        const sub = new URL(req.url ?? '/', 'http://loopback').pathname.slice('/api/dsh-tty/sftp'.length);
+                        const jsonAction = ['/list', '/mkdir', '/rename', '/remove', '/download'].find((action) => action === sub);
+                        if (jsonAction !== undefined) {
+                            if (req.method !== 'POST') {
+                                writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
+                                return;
+                            }
+                            const body = await readJsonBody(req);
+                            if (body === undefined) {
+                                writeJson(res, 400, { error: 'invalid JSON body' });
+                                return;
+                            }
+                            const parsed = mergeSshSpec((name) => live.findSshHost(name), body.name, body);
+                            if (parsed.spec === undefined) {
+                                writeJson(res, 400, { error: parsed.error ?? '无效的 SSH 连接规格' });
+                                return;
+                            }
+                            const spec = parsed.spec;
+                            const strField = (key) => (typeof body[key] === 'string' ? body[key].trim() : '');
+                            try {
+                                if (jsonAction === '/list') {
+                                    const result = await sftpManager.list(spec, strField('path'));
+                                    writeJson(res, 200, { ok: true, path: result.path, entries: result.entries });
+                                    return;
+                                }
+                                if (jsonAction === '/mkdir') {
+                                    if (strField('path') === '')
+                                        throw new Error('path 必填');
+                                    await sftpManager.mkdir(spec, strField('path'), body.parents === true);
+                                    writeJson(res, 200, { ok: true });
+                                    return;
+                                }
+                                if (jsonAction === '/rename') {
+                                    if (strField('from') === '' || strField('to') === '')
+                                        throw new Error('from/to 必填');
+                                    await sftpManager.rename(spec, strField('from'), strField('to'));
+                                    writeJson(res, 200, { ok: true });
+                                    return;
+                                }
+                                if (jsonAction === '/remove') {
+                                    if (strField('path') === '')
+                                        throw new Error('path 必填');
+                                    await sftpManager.remove(spec, strField('path'), body.recursive === true);
+                                    writeJson(res, 200, { ok: true });
+                                    return;
+                                }
+                                // download：路径必填（无 home 兜底），流式回包
+                                const target = strField('path');
+                                if (target === '')
+                                    throw new Error('path 必填');
+                                const { stream, size } = await sftpManager.openDownload(spec, target);
+                                res.writeHead(200, {
+                                    'content-type': 'application/octet-stream',
+                                    'content-disposition': contentDispositionValue(remoteBasename(target)),
+                                    ...(size !== null ? { 'content-length': String(size) } : {}),
+                                });
+                                // 客户端中断或写流失败都要回收 SFTP 读流，避免连接池通道悬挂
+                                res.on('close', () => {
+                                    if (res.writableEnded !== true)
+                                        stream.destroy();
+                                });
+                                stream.on('error', (error) => {
+                                    ctx.logger.warn('[dsh-tty] sftp 下载流错误: ' + error.message);
+                                    res.destroy();
+                                });
+                                stream.pipe(res);
+                                return;
+                            }
+                            catch (error) {
+                                writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                                return;
+                            }
+                        }
+                        if (sub === '/upload') {
+                            if (req.method !== 'POST') {
+                                writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
+                                return;
+                            }
+                            const metaRaw = req.headers['x-dsh-sftp-meta'];
+                            let meta;
+                            if (typeof metaRaw === 'string' && metaRaw !== '') {
+                                try {
+                                    const parsedMeta = JSON.parse(Buffer.from(metaRaw, 'base64url').toString('utf8'));
+                                    if (typeof parsedMeta === 'object' && parsedMeta !== null && !Array.isArray(parsedMeta))
+                                        meta = parsedMeta;
+                                }
+                                catch {
+                                    /* 落到下面的 400 */
+                                }
+                            }
+                            if (meta === undefined) {
+                                writeJson(res, 400, { error: '缺少或非法的 x-dsh-sftp-meta 头' });
+                                return;
+                            }
+                            const target = typeof meta.path === 'string' ? meta.path.trim() : '';
+                            if (target === '') {
+                                writeJson(res, 400, { error: 'meta.path 必填' });
+                                return;
+                            }
+                            const parsed = mergeSshSpec((name) => live.findSshHost(name), meta.name, meta);
+                            if (parsed.spec === undefined) {
+                                writeJson(res, 400, { error: parsed.error ?? '无效的 SSH 连接规格' });
+                                return;
+                            }
+                            try {
+                                const { stream, done } = await sftpManager.openUpload(parsed.spec, target, meta.append === true);
+                                let bytes = 0;
+                                req.on('data', (chunk) => {
+                                    bytes += chunk.length;
+                                });
+                                await pipeline(req, stream);
+                                await done;
+                                writeJson(res, 200, { ok: true, bytes });
+                            }
+                            catch (error) {
+                                const message = error instanceof Error ? error.message : String(error);
+                                if (res.headersSent)
+                                    res.destroy();
+                                else
+                                    writeJson(res, 500, { error: message });
+                            }
+                            return;
+                        }
+                        writeJson(res, 404, { error: 'not found: ' + sub });
+                    },
+                }));
+                // 本机文件浏览（0.9.0，双栏 SFTP 的本机一侧）：loopback 围栏。信任模型
+                // 与终端/SFTP 一致——浏览器仅同源可访问，且本机能做的 SSH 会话也能做；
+                // list/mkdir/rename/remove 操作本机路径；transfer 在服务端把本机路径与
+                // 远程路径流式对拷（凭证不落浏览器，字节不经过浏览器）。
+                disposers.push(webServer.register({
+                    kind: 'prefix',
+                    path: '/api/dsh-tty/local-fs',
+                    handler: async (req, res) => {
+                        if (!isLoopbackHttp(req)) {
+                            writeJson(res, 403, { error: 'forbidden: loopback-only' });
+                            return;
+                        }
+                        const sub = new URL(req.url ?? '/', 'http://loopback').pathname.slice('/api/dsh-tty/local-fs'.length);
+                        if (req.method !== 'POST') {
+                            writeJson(res, 405, { error: 'method not allowed: ' + String(req.method) });
+                            return;
+                        }
+                        const body = await readJsonBody(req);
+                        if (body === undefined) {
+                            writeJson(res, 400, { error: 'invalid JSON body' });
+                            return;
+                        }
+                        const strField = (key) => (typeof body[key] === 'string' ? body[key].trim() : '');
+                        try {
+                            if (sub === '/list') {
+                                const result = await listLocalDir(strField('path'));
+                                writeJson(res, 200, { ok: true, path: result.path, entries: result.entries });
+                                return;
+                            }
+                            if (sub === '/mkdir') {
+                                const target = strField('path');
+                                if (target === '')
+                                    throw new Error('path 必填');
+                                await fsMkdir(target, { recursive: body.parents === true });
+                                writeJson(res, 200, { ok: true });
+                                return;
+                            }
+                            if (sub === '/rename') {
+                                const from = strField('from');
+                                const to = strField('to');
+                                if (from === '' || to === '')
+                                    throw new Error('from/to 必填');
+                                await fsRename(from, to);
+                                writeJson(res, 200, { ok: true });
+                                return;
+                            }
+                            if (sub === '/remove') {
+                                const target = strField('path');
+                                if (target === '')
+                                    throw new Error('path 必填');
+                                await fsRm(target, { recursive: body.recursive === true });
+                                writeJson(res, 200, { ok: true });
+                                return;
+                            }
+                            if (sub === '/transfer') {
+                                // up = 本机→远程（上传），down = 远程→本机（下载）；目录递归
+                                const direction = strField('direction');
+                                const localPath = strField('localPath');
+                                const remotePath = strField('remotePath');
+                                if (localPath === '' || remotePath === '')
+                                    throw new Error('localPath/remotePath 必填');
+                                if (direction !== 'up' && direction !== 'down')
+                                    throw new Error('direction 必须是 up 或 down');
+                                const parsed = mergeSshSpec((name) => live.findSshHost(name), body.name, body);
+                                if (parsed.spec === undefined) {
+                                    writeJson(res, 400, { error: parsed.error ?? '无效的 SSH 连接规格' });
+                                    return;
+                                }
+                                if (direction === 'up')
+                                    await sftpManager.uploadFromLocal(parsed.spec, localPath, remotePath);
+                                else
+                                    await sftpManager.downloadToLocal(parsed.spec, remotePath, localPath);
+                                writeJson(res, 200, { ok: true });
+                                return;
+                            }
+                            writeJson(res, 404, { error: 'not found: ' + sub });
+                        }
+                        catch (error) {
+                            writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+                        }
+                    },
+                }));
                 return () => {
                     server.close();
                     for (const dispose of disposers) {
@@ -1474,6 +2143,15 @@ const plugin = definePlugin({
                 }
                 if (stored.shellIntegration === false)
                     startup.shellIntegration = false;
+                if (stored.sftpStyle === 'dual')
+                    startup.sftpStyle = 'dual';
+                if (stored.persistence === 'tmux')
+                    startup.persistence = 'tmux';
+                if (stored.endOnPageClose === true)
+                    startup.endOnPageClose = true;
+                const storedPersistSessions = sanitizePersistSessions(stored.persistSessions);
+                if (storedPersistSessions !== undefined && storedPersistSessions.length > 0)
+                    startup.persistSessions = storedPersistSessions;
                 const storedHosts = sanitizeSshHosts(stored.sshHosts);
                 if (storedHosts !== undefined && storedHosts.length > 0)
                     startup.sshHosts = storedHosts;
@@ -1533,6 +2211,7 @@ const plugin = definePlugin({
                                             cwd: { type: 'string', required: true },
                                             startedAt: { type: 'number', required: true },
                                             lastOutputAt: { type: 'number', required: true },
+                                            persist: { type: 'boolean' },
                                         },
                                     },
                                 },
@@ -1544,7 +2223,8 @@ const plugin = definePlugin({
                                 ? '当前没有活跃的终端面板会话（请引导用户先打开终端面板，或用户尚未打开）'
                                 : '终端面板会话：' + sessions.map((s) => {
                                     const where = s.kind === 'ssh' ? `ssh ${s.target}` : `pid=${String(s.pid ?? '?')} cwd=${s.cwd}`;
-                                    return `\n- sid=${s.sid} [${s.kind}] ${where} (启动于 ${new Date(s.startedAt).toLocaleString()})`;
+                                    const persist = s.persist === true ? ' [tmux 持久]' : '';
+                                    return `\n- sid=${s.sid} [${s.kind}]${persist} ${where} (启动于 ${new Date(s.startedAt).toLocaleString()})`;
                                 }).join('');
                             return [{ type: 'text', text }];
                         },
@@ -1806,8 +2486,334 @@ const plugin = definePlugin({
                         return { tunnels: tunnelManager.list().map((t) => ({ ...t, error: t.error ?? undefined })) };
                     },
                 })));
+                // —— SFTP 文件传输工具（0.7.0）——
+                // 只收连接簿条目名（book），不接受内联凭证：agent 上下文不进明文密钥；
+                // 连接与终端/隧道共用同一 HostKeyStore（TOFU 同源）。
+                const sftpBookSpec = (book) => {
+                    if (typeof book !== 'string' || book.trim() === '')
+                        throw new Error('book 必须是 SSH 连接簿条目名');
+                    const entry = live.findSshHost(book.trim());
+                    if (entry === undefined)
+                        throw new Error(`连接簿中不存在: ${book.trim()}`);
+                    return entry;
+                };
+                disposers.push(tools.register(defineTool({
+                    name: 'sftp_list',
+                    description: '列出 SSH 远程目录内容（名称/类型/大小/修改时间，目录在前）。book 为 SSH 连接簿条目名；path 缺省为远程登录 home。用于查找远程文件、确认上传下载结果。',
+                    parameters: {
+                        book: { type: 'string', required: true, description: 'SSH 连接簿条目名（设置 → 插件 → 终端面板 维护）' },
+                        path: { type: 'string', description: '远程目录路径（缺省 = 登录 home）' },
+                    },
+                    output: {
+                        schema: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                path: { type: 'string', required: true },
+                                entries: {
+                                    type: 'array',
+                                    required: true,
+                                    items: {
+                                        type: 'object',
+                                        additionalProperties: false,
+                                        properties: {
+                                            name: { type: 'string', required: true },
+                                            isDir: { type: 'boolean', required: true },
+                                            size: { type: 'number', required: true },
+                                            mtime: { type: 'number', required: true },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        render: (_args, value) => {
+                            const v = value;
+                            const entries = v.entries ?? [];
+                            if (entries.length === 0)
+                                return [{ type: 'text', text: `远程目录 ${v.path ?? '?'} 为空` }];
+                            const text = `远程目录 ${v.path ?? '?'}（${String(entries.length)} 项）：` + entries.map((e) => `\n- ${e.name}${e.isDir ? '/' : ''} — ${e.isDir ? '目录' : humanFileSize(e.size)}`).join('');
+                            return [{ type: 'text', text }];
+                        },
+                    },
+                    async execute(args) {
+                        const input = args;
+                        const spec = sftpBookSpec(input.book);
+                        const result = await sftpManager.list(spec, typeof input.path === 'string' ? input.path : '');
+                        return { path: result.path, entries: result.entries.map((e) => ({ name: e.name, isDir: e.isDir, size: e.size, mtime: e.mtime })) };
+                    },
+                })));
+                disposers.push(tools.register(defineTool({
+                    name: 'sftp_read',
+                    description: '读取 SSH 远程文本文件（book 连接簿条目 + path）。默认最多 256KB（可调至 1MB），超出截断；检测到 NUL 字节按二进制文件拒绝。适合查看远程配置、小日志。',
+                    parameters: {
+                        book: { type: 'string', required: true, description: 'SSH 连接簿条目名' },
+                        path: { type: 'string', required: true, description: '远程文件路径' },
+                        maxBytes: { type: 'number', description: '最大读取字节数（1~1048576，默认 262144）' },
+                    },
+                    output: {
+                        schema: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                path: { type: 'string', required: true },
+                                content: { type: 'string', required: true },
+                                truncated: { type: 'boolean', required: true },
+                            },
+                        },
+                        render: (_args, value) => {
+                            const v = value;
+                            const head = `远程文件 ${v.path ?? '?'}${v.truncated === true ? '（已截断）' : ''}：`;
+                            return [{ type: 'text', text: head + '\n' + String(v.content ?? '') }];
+                        },
+                    },
+                    async execute(args) {
+                        const input = args;
+                        const spec = sftpBookSpec(input.book);
+                        if (typeof input.path !== 'string' || input.path.trim() === '')
+                            throw new Error('path 必须是非空字符串');
+                        const maxBytes = typeof input.maxBytes === 'number' && Number.isInteger(input.maxBytes) && input.maxBytes >= 1 && input.maxBytes <= 1024 * 1024 ? input.maxBytes : 256 * 1024;
+                        const { stream } = await sftpManager.openDownload(spec, input.path);
+                        const chunks = [];
+                        let total = 0;
+                        try {
+                            for await (const chunk of stream) {
+                                const piece = chunk;
+                                chunks.push(piece);
+                                total += piece.length;
+                                if (total > maxBytes)
+                                    break; // 只多读一段用于判定截断，其余丢弃
+                            }
+                        }
+                        finally {
+                            stream.destroy();
+                        }
+                        const buf = Buffer.concat(chunks);
+                        const truncated = buf.length > maxBytes;
+                        const sliced = truncated ? buf.subarray(0, maxBytes) : buf;
+                        if (sliced.includes(0))
+                            throw new Error('疑似二进制文件（含 NUL 字节），sftp_read 只支持文本内容');
+                        return { path: input.path.trim(), content: sliced.toString('utf8'), truncated };
+                    },
+                })));
+                disposers.push(tools.register(defineTool({
+                    name: 'sftp_write',
+                    description: '写 SSH 远程文本文件（book 连接簿条目 + path + content）。默认覆盖写入，append:true 追加到文件尾；单次最多 1MB。适合远程写配置、落结果文件。',
+                    parameters: {
+                        book: { type: 'string', required: true, description: 'SSH 连接簿条目名' },
+                        path: { type: 'string', required: true, description: '远程文件路径' },
+                        content: { type: 'string', required: true, description: '要写入的文本内容（≤1MB）' },
+                        append: { type: 'boolean', description: 'true 追加到文件尾（默认覆盖）' },
+                    },
+                    output: {
+                        schema: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                ok: { type: 'boolean', required: true },
+                                path: { type: 'string', required: true },
+                                bytes: { type: 'number', required: true },
+                                append: { type: 'boolean', required: true },
+                            },
+                        },
+                        render: (_args, value) => {
+                            const v = value;
+                            return [{ type: 'text', text: `已${v.append === true ? '追加' : '写入'}远程文件 ${v.path ?? '?'}（${String(v.bytes ?? 0)} 字节）` }];
+                        },
+                    },
+                    async execute(args) {
+                        const input = args;
+                        const spec = sftpBookSpec(input.book);
+                        if (typeof input.path !== 'string' || input.path.trim() === '')
+                            throw new Error('path 必须是非空字符串');
+                        if (typeof input.content !== 'string')
+                            throw new Error('content 必须是字符串');
+                        const bytes = Buffer.byteLength(input.content, 'utf8');
+                        if (bytes > 1024 * 1024)
+                            throw new Error(`content 超过上限：${String(bytes)} 字节 > 1MB（大文件请用终端 scp 或面板上传）`);
+                        const append = input.append === true;
+                        const { stream, done } = await sftpManager.openUpload(spec, input.path, append);
+                        stream.write(input.content, 'utf8');
+                        stream.end();
+                        await done;
+                        return { ok: true, path: input.path.trim(), bytes, append };
+                    },
+                })));
+                // —— SFTP 管理闭环（0.8.0）——
+                // mkdir（可逐级补齐）/ rename（可跨目录，等效移动）/ remove（目录
+                // 递归）/ tree（限深限数的递归列举），与 sftp_list/read/write 一起
+                // 让 agent 不开面板也能完整管理远程文件；同样只收连接簿条目名。
+                disposers.push(tools.register(defineTool({
+                    name: 'sftp_mkdir',
+                    description: '在 SSH 远程创建目录（book 连接簿条目 + path）。parents:true 时逐级补齐缺失的父目录（等效 mkdir -p，默认 false，父目录缺失直接报错）。',
+                    parameters: {
+                        book: { type: 'string', required: true, description: 'SSH 连接簿条目名（设置 → 插件 → 终端面板 维护）' },
+                        path: { type: 'string', required: true, description: '要创建的远程目录路径' },
+                        parents: { type: 'boolean', description: 'true 逐级补齐缺失父目录（默认 false）' },
+                    },
+                    output: {
+                        schema: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                ok: { type: 'boolean', required: true },
+                                path: { type: 'string', required: true },
+                            },
+                        },
+                        render: (_args, value) => {
+                            const v = value;
+                            return [{ type: 'text', text: `已创建远程目录 ${v.path ?? '?'}` }];
+                        },
+                    },
+                    async execute(args) {
+                        const input = args;
+                        const spec = sftpBookSpec(input.book);
+                        if (typeof input.path !== 'string' || input.path.trim() === '')
+                            throw new Error('path 必须是非空字符串');
+                        await sftpManager.mkdir(spec, input.path, input.parents === true);
+                        return { ok: true, path: input.path.trim() };
+                    },
+                })));
+                disposers.push(tools.register(defineTool({
+                    name: 'sftp_rename',
+                    description: '在 SSH 远程重命名 / 移动文件或目录（book 连接簿条目 + from + to）。to 与 from 不同目录即为移动（目标目录需已存在）；不会覆盖已存在的目标（服务端 rename 语义）。',
+                    parameters: {
+                        book: { type: 'string', required: true, description: 'SSH 连接簿条目名' },
+                        from: { type: 'string', required: true, description: '原远程路径' },
+                        to: { type: 'string', required: true, description: '新远程路径（跨目录即移动）' },
+                    },
+                    output: {
+                        schema: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                ok: { type: 'boolean', required: true },
+                                from: { type: 'string', required: true },
+                                to: { type: 'string', required: true },
+                            },
+                        },
+                        render: (_args, value) => {
+                            const v = value;
+                            return [{ type: 'text', text: `已将远程 ${v.from ?? '?'} 重命名/移动为 ${v.to ?? '?'}` }];
+                        },
+                    },
+                    async execute(args) {
+                        const input = args;
+                        const spec = sftpBookSpec(input.book);
+                        if (typeof input.from !== 'string' || input.from.trim() === '')
+                            throw new Error('from 必须是非空字符串');
+                        if (typeof input.to !== 'string' || input.to.trim() === '')
+                            throw new Error('to 必须是非空字符串');
+                        await sftpManager.rename(spec, input.from, input.to);
+                        return { ok: true, from: input.from.trim(), to: input.to.trim() };
+                    },
+                })));
+                disposers.push(tools.register(defineTool({
+                    name: 'sftp_remove',
+                    description: '删除 SSH 远程文件或目录（book 连接簿条目 + path）。文件直接删除；目录默认走 rmdir（非空明确报错），recursive:true 整目录递归删除（不可恢复，谨慎使用）。',
+                    parameters: {
+                        book: { type: 'string', required: true, description: 'SSH 连接簿条目名' },
+                        path: { type: 'string', required: true, description: '要删除的远程路径' },
+                        recursive: { type: 'boolean', description: '目录 true 时递归删除全部内容（默认 false）' },
+                    },
+                    output: {
+                        schema: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                ok: { type: 'boolean', required: true },
+                                path: { type: 'string', required: true },
+                                recursive: { type: 'boolean', required: true },
+                            },
+                        },
+                        render: (_args, value) => {
+                            const v = value;
+                            return [{ type: 'text', text: `已删除远程 ${v.path ?? '?'}${v.recursive === true ? '（含全部内容）' : ''}` }];
+                        },
+                    },
+                    async execute(args) {
+                        const input = args;
+                        const spec = sftpBookSpec(input.book);
+                        if (typeof input.path !== 'string' || input.path.trim() === '')
+                            throw new Error('path 必须是非空字符串');
+                        const recursive = input.recursive === true;
+                        await sftpManager.remove(spec, input.path, recursive);
+                        return { ok: true, path: input.path.trim(), recursive };
+                    },
+                })));
+                disposers.push(tools.register(defineTool({
+                    name: 'sftp_tree',
+                    description: '递归列举 SSH 远程目录结构（book 连接簿条目 + path）：深度优先、目录优先，maxDepth（1~8，默认 3）限层、maxEntries（1~2000，默认 500）限条数，超限 truncated:true；符号链接不跟随；读取失败的子目录列入 errors。适合先看远程项目结构再定位文件。',
+                    parameters: {
+                        book: { type: 'string', required: true, description: 'SSH 连接簿条目名' },
+                        path: { type: 'string', description: '远程目录路径（缺省 = 登录 home）' },
+                        maxDepth: { type: 'number', description: '最大下钻层数（1~8，默认 3）' },
+                        maxEntries: { type: 'number', description: '最大条目数（1~2000，默认 500）' },
+                    },
+                    output: {
+                        schema: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                path: { type: 'string', required: true },
+                                entries: {
+                                    type: 'array',
+                                    required: true,
+                                    items: {
+                                        type: 'object',
+                                        additionalProperties: false,
+                                        properties: {
+                                            path: { type: 'string', required: true },
+                                            name: { type: 'string', required: true },
+                                            depth: { type: 'number', required: true },
+                                            isDir: { type: 'boolean', required: true },
+                                            size: { type: 'number', required: true },
+                                            mtime: { type: 'number', required: true },
+                                        },
+                                    },
+                                },
+                                truncated: { type: 'boolean', required: true },
+                                errors: {
+                                    type: 'array',
+                                    required: true,
+                                    items: {
+                                        type: 'object',
+                                        additionalProperties: false,
+                                        properties: {
+                                            path: { type: 'string', required: true },
+                                            message: { type: 'string', required: true },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        render: (_args, value) => {
+                            const v = value;
+                            const entries = v.entries ?? [];
+                            if (entries.length === 0)
+                                return [{ type: 'text', text: `远程目录 ${v.path ?? '?'} 为空` }];
+                            const head = `远程目录 ${v.path ?? '?'} 结构（${String(entries.length)} 项${v.truncated === true ? '，已截断' : ''}）：`;
+                            const lines = entries.map((e) => {
+                                const indent = '  '.repeat(Math.max(0, e.depth - 1));
+                                const tail = e.isDir ? '/' : ' — ' + humanFileSize(e.size);
+                                return `${indent}- ${e.name}${tail}`;
+                            });
+                            for (const item of v.errors ?? [])
+                                lines.push(`! ${item.path}（${item.message}）`);
+                            return [{ type: 'text', text: head + '\n' + lines.join('\n') }];
+                        },
+                    },
+                    async execute(args) {
+                        const input = args;
+                        const spec = sftpBookSpec(input.book);
+                        const result = await sftpManager.tree(spec, typeof input.path === 'string' ? input.path : '', {
+                            maxDepth: typeof input.maxDepth === 'number' && Number.isInteger(input.maxDepth) ? input.maxDepth : undefined,
+                            maxEntries: typeof input.maxEntries === 'number' && Number.isInteger(input.maxEntries) ? input.maxEntries : undefined,
+                        });
+                        return result;
+                    },
+                })));
                 stateRef.toolsRegistered = true;
-                console.log('[dsh-tty] agent tools registered (tty_list, tty_capture, tty_screen, tty_expect, tty_send, tunnel_list)');
+                console.log('[dsh-tty] agent tools registered (tty_list, tty_capture, tty_screen, tty_expect, tty_send, tunnel_list, sftp_list, sftp_read, sftp_write, sftp_mkdir, sftp_rename, sftp_remove, sftp_tree)');
                 return () => {
                     stateRef.toolsRegistered = false;
                     for (const dispose of disposers) {
@@ -1838,7 +2844,7 @@ const plugin = definePlugin({
                                 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()})`;
+                                return `- sid=${s.sid} [${s.kind}]${s.persist === true ? ' [tmux 持久]' : ''} ${where} (最后活动 ${new Date(s.lastOutputAt).toLocaleTimeString()})`;
                             }).join('\n');
                         },
                     });
@@ -1857,11 +2863,12 @@ const plugin = definePlugin({
         }, REAPER_INTERVAL_MS);
         reaperTimer.unref?.();
         ctx.effect(() => () => clearInterval(reaperTimer), 'dsh-tty: orphan reaper');
-        // 插件卸载时回收全部会话与隧道
+        // 插件卸载时回收全部会话、隧道与 SFTP 连接
         ctx.effect(() => {
             return () => {
                 void sessions.disposeAll();
                 tunnelManager.disposeAll();
+                sftpManager.disposeAll();
             };
         }, 'dsh-tty: session cleanup');
         console.log(`[dsh-tty] mounted (shell=${live.shell}, term=${live.term}, cwd=${live.cwd}, maxSessions=${sessions.limitValue})`);