@hyzyn/dsh-tty 0.5.0 → 0.10.0

package/README.md

@@ -9,7 +9,19 @@ xterm.js 全交互终端（node-pty 真实 PTY，WebGL 渲染器加速），支
 （OSC 133/7）**——agent 能按「命令」粒度读写终端（`tty_capture{last}` /
 `tty_expect`），并支持 **agent forwarding**、**~/.ssh/config 导入** 等深化
 能力；0.5.0 起内置**端口转发管理**——连接簿条目配隧道（-L/-R 两向），宿主
-自持连接、断线自动重连、状态徽标（见下文）。
+自持连接、断线自动重连、状态徽标（见下文）；0.6.0 起 **bash 3.2（macOS
+自带）补全命令开始标记**（DEBUG trap 兜底，`tty_capture{last}` /
+`tty_expect` 早停恢复可用），设置卡片 **Shell 路径可选可输入**；0.7.0 起内置
+**SFTP 文件传输**——SSH 连接的远程目录浏览与上传/下载/新建目录/重命名/删除
+（面板「文件浏览」对话框 + agent `sftp_*` 工具，见下文）；0.8.0 起面板支持
+**拖拽上传**（文件与文件夹直接拖入，递归展开目录结构逐级上传），agent 侧
+补齐**管理闭环**：`sftp_mkdir`（parents 逐级补齐）/ `sftp_rename`（跨目录
+移动）/ `sftp_remove`（递归删除）/ `sftp_tree`（限深递归列举）；0.9.0 起
+**SFTP 界面可选双栏风格**（左本机 / 右远程、行内直传，宿主服务端对拷），
+面板头部压缩为「标签行 + SSH 连接栏」两行；0.10.0 起支持**会话持久化
+（tmux）**——「持久终端」标签由 tmux server（专用 socket）托管，断线保活
+超时、甚至宿主重启后重开标签即按名接回原现场（正在跑的程序原样存活），
+SSH 侧同理（远程 tmux）。
 
 ![终端面板：多标签页 xterm 弹窗，工具栏含搜索/清屏/复制/粘贴，标题栏含最小化「—」与关闭 ✕](../../docs/dsh-plugin-kit-tty.png)
 
@@ -46,22 +58,31 @@ dsh plugin --profile web add link:$(pwd)/packages/tty   # 仓库开发调试
   把面板收起——PTY 会话与输出缓冲保持存活，侧边栏「终端」入口上显示
   「运行中/总数」徽标与状态点（有输出时脉冲提示），点击入口即可恢复；
   悬浮条 ✕ / 标题栏 ✕ 才真正关闭并结束全部会话；
-- 标题栏 ✕ 关闭面板并结束全部会话（PTY 树级清理）；会话退出后点终端区域可重开；
+- 标题栏 ✕ 关闭面板并结束全部会话（PTY 树级清理；tmux 持久标签同时
+  kill-session）；会话退出后点终端区域可重开；
 - 并发上限默认 4（配置 `maxSessions`，1~16）。
 
 ![终端面板设置卡片：shell / TERM / 并发上限等保存即热生效](../../docs/dsh-plugin-kit-tty-setting.png)
 
 ## agent 工具（P1）
 
-插件向 agent 注入五个工具（与 bash 工具同权，操作实时显示在用户终端里）：
+插件向 agent 注入十三个工具（与 bash 工具同权，操作实时显示在用户终端里）：
 
 | 工具 | 作用 |
 | --- | --- |
-| `tty_list` | 列出活跃终端会话（sid / kind（local\|ssh）/ target / pid / **cwd 实时跟随 cd** / 活动时间） |
+| `tty_list` | 列出活跃终端会话（sid / kind（local\|ssh）/ target / pid / **cwd 实时跟随 cd** / 活动时间；tmux 持久会话带 `persist` 标记） |
 | `tty_capture` | 读取近期输出（尾部 N 行，默认清洗 ANSI，`raw:true` 取原始流）；**`last:true` 只返回上一条已完成命令的输出 + 退出码**（shell 集成标记，见下节） |
 | `tty_screen` | 读取**当前可见屏幕**的渲染结果（xterm-headless 虚拟屏，纯文本）——能真正读懂 vim / htop / 菜单等 TUI 界面 |
 | `tty_expect` | 用正则**等待后续输出**中的就绪信号（dev server URL、构建完成等）；超时不抛错（`matched:false` + 尾部输出），命令提前结束也会带退出码早停 |
 | `tty_send` | 向指定会话发送按键/文本（如 dev server 的 q 键、菜单选择） |
+| `sftp_list` | 列出 SSH 远程目录内容（名称/类型/大小/修改时间，目录在前）；`book` 为连接簿条目名，`path` 缺省为登录 home |
+| `sftp_read` | 读取远程**文本**文件（默认 ≤256KB 可调至 1MB，超出截断；含 NUL 字节按二进制拒绝） |
+| `sftp_write` | 写远程文本文件（默认覆盖，`append:true` 追加；单次 ≤1MB） |
+| `sftp_mkdir` | 创建远程目录；`parents:true` 逐级补齐缺失父目录（等效 `mkdir -p`，自底向上创建，已存在目录幂等跳过） |
+| `sftp_rename` | 重命名/移动远程文件或目录（`to` 与 `from` 不同目录即移动；不覆盖已存在的目标） |
+| `sftp_remove` | 删除远程文件/目录；目录默认 rmdir（非空明确报错），`recursive:true` 整树删除（不可恢复） |
+| `sftp_tree` | 递归列举远程目录结构（深度优先、目录优先；`maxDepth` 1~8 / `maxEntries` 1~2000 限流，超限 `truncated:true`；symlink 不跟随防环） |
+| `tunnel_list` | 列出端口转发隧道及其实时状态（活跃/连接中/错误/停止、规则、连接数） |
 
 典型 agent 流程（推荐）：`tty_send` 启动长任务 → `tty_expect` 等就绪标记 →
 `tty_capture{last:true}` 拿单条命令结果。此外 `systemPrompt` 里注册了动态
@@ -74,8 +95,14 @@ spawn 时经既有的 `-c` 包装层按 shell 类型注入钩子（对用户透
 
 - **zsh**：`ZDOTDIR` 指向临时桩目录（VS Code 同款方案），桩文件先 source
   用户原 rc 再追加 `precmd`/`preexec` 钩子；
-- **bash**：`--rcfile` 桩（先 source `~/.bashrc`）；命令开始标记走 `PS0`
-  （bash ≥ 4.4，macOS 自带 bash 3.2 优雅降级：仅丢 B 标记）；
+- **bash**：`--rcfile` 桩（先 source `~/.bashrc`）；命令开始标记按版本二选一：
+  bash ≥ 4.4 走 `PS0`；bash < 4.4（macOS 自带 3.2）无 PS0，用 **DEBUG trap
+  兜底**（handler 按 `$BASH_COMMAND` 过滤掉 PROMPT_COMMAND 机制自身的
+  fire，避免幻影标记把用户输出切出捕获区间；bash 3.2 的
+  `trap - DEBUG` 在 handler 内卸载不生效，故按「永久武装 + 过滤」设计）。
+  副作用：循环体等复合命令的内部命令会多发 B 标记，仅影响
+  `tty_capture{last}` 对这类命令的截取起点，D/退出码与 `tty_expect` 不受影响；
+  PROMPT_COMMAND 挂钩兼容字符串与数组（bash 5.1+）两种形态；
 - 标记语义：`133;A` prompt 开始 / `133;B` 命令开始 / `133;D;<exit>` 命令
   结束带退出码 / `OSC 7 file://…` cwd 上报（`tty_list.cwd` 跟随 `cd`，
   SSH 会话则上报远程路径）；
@@ -104,6 +131,90 @@ SSH 会话同表调度：`tty_list` 里 `kind: 'ssh'` 的条目按 `target`
   `tunnel_list` 工具查询状态；
 - TOFU 与终端会话共享同一份 hostKeys 钉扎；端口不占用 maxSessions 名额。
 
+## SFTP 文件传输（0.7.0，0.8.0/0.9.0 增强）
+
+不动终端、不占会话名额，直接对 SSH 连接做远程文件操作（`ssh2` 的 sftp
+subsystem，宿主半体 `src/sftp.ts`）：
+
+![SFTP 单窗体：远程目录浏览，行内 下载/重命名/删除](../../docs/dsh-plugin-kit-tty-sftp-dialog.png)
+
+![SFTP 双栏（0.9.0）：左本机 / 右远程，行内 ⇨/⇦ 服务端直传](../../docs/dsh-plugin-kit-tty-sftp-dual.png)
+
+- **入口**：① 标签栏「+」菜单的连接簿条目带 📂（按该条目打开文件浏览）；
+  ② SSH 连接对话框填好主机/认证后点「文件浏览」（不落连接簿也能浏览）；
+- **操作**：目录浏览（路径框回车跳转、`..（上级目录）`、单击文件即下载）、
+  **上传**（多选文件，XHR 流式 + 进度百分比；0.8.0 起支持**拖拽**——文件与
+  文件夹直接拖入对话框，文件夹经 `webkitGetAsEntry` 递归展开逐个上传，目录
+  用 mkdir parents 逐级补齐）、**下载**（POST → 浏览器 Blob
+  → `<a download>`）、**新建目录**、**重命名**（行内编辑器）、**删除**
+  （🗑 二次点击确认，目录带 `recursive` 整目录删除）；
+- **连接管理**：懒连接池——首次操作才建 SSH 连接，空闲 120 秒自动回收，
+  断开后下次操作自动重连；连接簿条目在每次（重）连接时实时解析（改密码
+  后自动用新凭证）；TOFU 与终端会话/隧道共用同一份 `hostKeys` 钉扎，指纹
+  变同样拒绝；SFTP 不计入 `maxSessions` 名额；
+- **传输通道**：`POST /api/dsh-tty/sftp/list|mkdir|rename|remove|download|
+  upload`（全部 loopback 围栏）。连接规格经 JSON 体（连接簿名或内联字段，
+  与 WS ssh 帧同语义「条目作基底 + 内联逐项覆盖」）或 upload 的
+  `x-dsh-sftp-meta` 头（base64url）携带——**凭证不进 URL/查询串**；上传下载
+  均为流式 pipe，不整文件进内存；
+- **agent 工具**：`sftp_list` / `sftp_read` / `sftp_write` / `sftp_mkdir` /
+  `sftp_rename` / `sftp_remove` / `sftp_tree`（见上表）——只收
+  `book` 连接簿条目名，**不接受内联凭证**（agent 上下文不进明文密钥）；
+- **双栏风格（0.9.0 可选，配置 `sftpStyle`）**：左本机 / 右远程两栏——本机
+  侧浏览与文件操作走新增的 `/api/dsh-tty/local-fs` 路由（list/mkdir/rename/
+  remove，loopback 围栏）；行内 `⇨ / ⇦` 把条目对拷到对面栏的当前目录
+  （`/api/dsh-tty/local-fs/transfer` 由宿主服务端把两个路径流式直传，目录
+  递归、同名覆盖，**字节不经过浏览器**）；单窗体风格照旧，设置卡片切换，
+  重新打开 SFTP 生效。
+
+## 会话持久化（tmux，0.10.0）
+
+默认安全模型不变：会话随宿主生死（内核级 PTY 清理）。需要「活得比宿主久」
+的工作（dev server、build、训练任务），开**持久终端**——会话状态委托给
+tmux server（专用 socket `dsh-tty`，与用户自己的 tmux 完全隔离），断线保活
+超时、甚至宿主重启后都能接回：
+
+- **入口（0.10.1 简化）**：设置卡片「会话持久化」选 `tmux` 即唯一开关——开启后
+  **所有新开的标签默认持久化**：「+」菜单的「本地终端」、连接簿条目点击、
+  SSH 连接对话框（「持久会话」默认勾选，单次连接可取消）。不再有单独的
+  「持久终端」菜单项与条目级勾选；
+- **机制**：spawn/ssh 帧带 `persist` + 客户端生成、随标签规格保存的稳定
+  `persistName`——本地把 `-c` 包装层换成 `exec tmux -L dsh-tty -f
+  <conf> new-session -A -s dsh-<名>`（cwd 由 node-pty spawn 继承）；SSH 则
+  远程 `exec tmux -L dsh-tty -f /dev/null new-session -A -s dsh-<名>` 开
+  pty channel。`-A` attach-or-create：宿主重启后重开标签按同名接回原
+  tmux 会话，正在跑的程序、pane 状态原样恢复；
+- **恢复链路**：浏览器重连后查 `sessions`——持久标签 sid 已失效的，客户端
+  自动按原 persistName 重新 spawn（非持久标签维持丢弃语义）；保活回收器
+  超时只杀 PTY（tmux 客户端），**不杀 tmux 会话**，回收后照样可接回；
+  同宿主内的重连（attach）对 tmux 会话**不回放宿主缓冲**——回放会把可见屏
+  先写进全新 xterm（幽灵滚动条），tmux 整屏重画再画一遍（重影）——改为
+  强制 `tmux refresh-client` 重画恰好一次；
+  持久标签规格同时写入 **localStorage**（sessionStorage 只对同一浏览器标签
+  可见，dsh 重启自动打开的新窗口原本读不到、恢复就断在这一环）——全新
+  窗口打开面板时按规格直接 respawn：tmux 会话存活则接回原现场，已消失
+  （远程重装/重装丢失）则开新 shell；规格只随「标签被主动关闭/退出」淘汰，
+  不做事前存活确认（确认依赖的留存状态一旦漂移会让恢复静默失效）；
+- **关闭语义**：kill 帧（标签 ✕ / 关面板）对 tmux 背书会话先
+  `tmux kill-session` 再杀客户端——真正结束，而不是 detach 留活口；
+  整个页面关闭时默认**留存**（保活期后可再恢复），配置
+  `endOnPageClose: true` 则改为保活期结束时连 tmux 会话一起结束；
+- **shell 集成兼容**：tmux 会吞掉不认识的转义序列——钩子检测 `$TMUX` 把
+  OSC 133/7 包进 DCS passthrough 信封（payload 内 ESC 双写），tmux ≥3.3 +
+  `allow-passthrough on`（宿主自动写入桩 conf）时解包转发，宿主解析器看到的
+  仍是裸标记：`tty_expect` / OSC 7 cwd 跟随在持久标签内照常工作；
+  `tty_capture{last}` 另有一层修正——tmux 的 pane 重画是异步批量的，命令输出
+  会落在 D 标记之后逃出捕获窗口，故钩子在发 D 前先 `capture-pane` 把 pane
+  内容经 `OSC 133;T`（base64，最近 200 行）随流直送，宿主优先采用 T 快照
+  作为命令输出（超出 200 行的输出截断头部，与环形缓冲语义一致）；
+- **运行资产**：`<DSH_HOME|~/.dsh>/tty/` 下的稳定桩目录（tmux server 比宿主
+  进程活得久，不能用临时目录）：`tmux.conf`（status off 防重绘污染捕获、
+  真色 overrides、`default-command` 指向内层启动器）与 `inner.sh`（按当前
+  配置 exec 内层 shell，zsh ZDOTDIR / bash --rcfile 桩照常注入）；配置热改
+  对新开 pane 生效，`tmux.conf` 本身只在 tmux server 首启时读取；
+- **降级**：本机/远程未安装 tmux 时，持久 spawn 自动落回普通会话，终端里
+  回一行灰字提示；不装任何东西也能正常用，只是无持久化。
+
 ## SSH 连接（方案 C）
 
 0.2.0 起标签栏「+」变为一键菜单，除本地终端外还能开 **SSH 标签页**：宿主
@@ -112,8 +223,9 @@ SSH 会话同表调度：`tty_list` 里 `kind: 'ssh'` 的条目按 `target`
 关闭、输出缓冲、背压与 agent 工具全部复用同一套调度。
 
 - **「+」菜单三个入口**：本地终端 / **SSH 连接簿**（配置里保存过的条目，
-  显示 `user@host[:port] · auth`，**条目带 ✎ 进入编辑模式**）/ SSH 连接…
-  （表单手填 host / port / username / auth，连接前可勾选保存）；
+  显示 `user@host[:port] · auth`，**条目带 📂 文件浏览与 ✎ 编辑**）/ SSH 连接…
+  （表单手填 host / port / username / auth，连接前可勾选保存，对话框底部
+  「文件浏览」可跳过终端直接以当前信息打开 SFTP）；
 - **连接簿**：SSH 连接对话框勾选「保存到连接簿」即存为条目（同名覆盖，
   名称留空用主机名）；「+」菜单条目的 ✎ 与设置卡片里的 **编辑** 都走同一
   编辑表单（行内改 host/port/username/auth/私钥/密码/agent forwarding，
@@ -160,32 +272,36 @@ SSH 会话同表调度：`tty_list` 里 `kind: 'ssh'` 的条目按 `target`
 | `enabled` | true | 关闭整个插件（需重启生效） |
 | `announceToAgent` | true | 是否向 agent 公告终端面板能力（systemPrompt 注入） |
 | `maxSessions` | 4 | 并发 PTY 会话上限（1~16） |
-| `shell` | `$SHELL` | shell 路径 |
+| `shell` | `$SHELL` | shell 路径；设置卡片可选可输入（下拉候选来自 `/etc/shells` + `$SHELL` + 常见安装路径，仅列存在且可执行者，`$SHELL` 优先），也可手输任意路径 |
 | `term` | `xterm-256color` | TERM 值 |
 | `colorTerm` | `truecolor` | COLORTERM 值 |
 | `cwd` | 宿主启动目录 | 兜底工作目录（客户端当前会话 cwd 优先） |
 | `reconnectGraceSec` | 120 | 异常断开后会话保活秒数（0~3600）：刷新页面/网络抖动后会话存活等待重连，超时由回收器结束；`0` = 旧行为，断开立即结束 |
-| `sshHosts` | `[]` | SSH 连接簿（面板「+」菜单可选）：条目 `{name, host, port=22, username, auth=agent\|key\|password, keyPath, passphrase, password}`；保存时整体替换、同名覆盖；`password` / `passphrase` 支持 `env:VAR` 引用，避免明文入库 |
+| `sshHosts` | `[]` | SSH 连接簿（面板「+」菜单可选）：条目 `{name, host, port=22, username, auth=agent\|key\|password, keyPath, passphrase, password, agentForward}`；保存时整体替换、同名覆盖；`password` / `passphrase` 支持 `env:VAR` 引用，避免明文入库；持久化开启时条目点击默认以 tmux 持久会话打开 |
 | `hostKeys` | `[]` | SSH 主机指纹记录（TOFU，自动维护）：条目 `{host, port, fingerprint}`；按 host:port 唯一，首次连接自动追加，指纹变更拒绝连接；设置卡片可删除重置 |
 | `shellIntegration` | true | 注入 OSC 133/7 shell 集成（命令边界标记 + cwd 上报；`tty_capture{last}` 依赖它）；zsh/bash 支持，其他 shell 自动跳过；出兼容问题时可关闭 |
 | `tunnels` | `[]` | 端口转发隧道：条目 `{name, bookName, direction=local\|remote, localPort?, remoteHost?, remotePort?, localTargetHost?, localTargetPort?, enabled}`；`bookName` 引用连接簿条目提供主机与认证；卡片「端口转发」区块可视化维护 |
+| `sftpStyle` | `dialog` | SFTP 文件浏览界面风格：`dialog` 单窗体（远程目录 + 上传/下载/拖拽）/ `dual` 双栏（左本机 / 右远程，行内 `⇨/⇦` 宿主服务端直传）；重新打开 SFTP 生效 |
+| `persistence` | `off` | 会话持久化：`off` 会话随宿主生死（默认）；`tmux` 开启后**所有新开的标签默认由 tmux server 托管**、可跨宿主重启恢复（需本机/远程安装 tmux）；SSH 对话框可对单次连接取消 |
+| `endOnPageClose` | `false` | 页面（最后一个连接）断开且保活期结束时，是否连 tmux 持久会话一起结束。默认 `false` = 留存可恢复；`true` = 页面关了就不保活（保活期内刷新仍可无缝接回） |
 
 ## 帧协议（/api/dsh-tty/ws，JSON 文本帧；v3 = 单连接多会话 + 断线重连）
 
 | 方向 | 帧 | 说明 |
 | --- | --- | --- |
-| C→S | `{t:'spawn', sid?, cols?, rows?, cwd?}` | 创建会话；sid 缺省由宿主生成，cwd 缺省用配置兜底 |
-| C→S | `{t:'ssh', sid?, cols?, rows?, name? \| host, username, …}` | 创建 SSH 会话（ssh2 原生）；`name` 引用连接簿条目作基底，内联 `host/port/username/auth/keyPath/passphrase/password/agentForward` 可逐项覆盖 |
+| C→S | `{t:'spawn', sid?, cols?, rows?, cwd?, persist?, persistName?}` | 创建会话；sid 缺省由宿主生成，cwd 缺省用配置兜底；`persist` + 稳定 `persistName`（0.10.0）= tmux 持久会话（`dsh-<名>`，需 persistence=tmux） |
+| C→S | `{t:'ssh', sid?, cols?, rows?, name? \| host, username, …, persist?, persistName?}` | 创建 SSH 会话（ssh2 原生）；`name` 引用连接簿条目作基底，内联 `host/port/username/auth/keyPath/passphrase/password/agentForward` 可逐项覆盖；`persist` 语义同 spawn（远程 tmux 托管） |
 | C→S | `{t:'input', sid?, d}` | 按键/粘贴数据 |
 | C→S | `{t:'resize', sid?, cols, rows}` | 面板尺寸变化 |
+| C→S | `{t:'refresh', sid?}` | 强制重画（0.10.1）：宿主对 tmux 会话执行 `refresh-client`（客户端 reset 清残 scrollback 后请现场重画；非 tmux 会话 no-op） |
 | C→S | `{t:'kill', sid?}` | 关闭会话（孤儿会话也允许跨连接 kill，防泄漏） |
 | C→S | `{t:'sessions'}` | 列出全局会话快照（`attachable` 标记可重连者） |
 | C→S | `{t:'attach', sid}` | 重连孤儿会话（保活窗口内）：`ready(reattached:true)` 后紧跟一帧 `data` 回放输出缓冲 |
-| S→C | `{t:'ready', sid, pid, kind, target?, reattached?}` | 会话就绪；`kind:'local'` 带 pid，`kind:'ssh'` 时 pid=null、target=user@host[:port]；attach 复用此帧并带 `reattached:true` |
+| S→C | `{t:'ready', sid, pid, kind, target?, persist?, reattached?}` | 会话就绪；`kind:'local'` 带 pid，`kind:'ssh'` 时 pid=null、target=user@host[:port]；attach 复用此帧并带 `reattached:true`；`persist:true` 表示 tmux 持久会话（0.10.0） |
 | S→C | `{t:'data', sid, d}` | 终端输出（utf8 文本，StringDecoder 兜跨帧多字节序列）；**12ms 窗口/64KB 阈值合并成帧**（0.4.1），exit/kill 前强制冲刷保证帧序 |
 | S→C | `{t:'exit', sid, code, signal}` | PTY 退出事实（恰好一次；attach 换连接后仍随当前连接送达） |
 | S→C | `{t:'error', sid?, m}` | 错误 |
-| S→C | `{t:'sessions', list}` | 会话快照（`{sid, kind, target, pid?, cwd, startedAt, lastOutputAt, attachable}`） |
+| S→C | `{t:'sessions', list, tmux?}` | 会话快照（`{sid, kind, target, pid?, cwd, startedAt, lastOutputAt, attachable, persist?}`）；`tmux` = 专用 socket 上现存的持久会话名 + SSH 持久会话留存名（0.10.1，可观测字段） |
 
 断线保活语义：客户端正常关面板会先逐个发 `kill` 再断开；因此「WS close
 且仍有存活会话」判定为异常断开——会话转入孤儿状态（输出继续积累进环形
@@ -233,11 +349,14 @@ pnpm --filter @hyzyn/dsh-tty ssh-smoke    # SSH 冒烟：内存 SSH server（ssh
   内保活可重连，宿主进程重启则所有会话结束；超期后未重连的会话由回收器
   结束，输出缓冲（尾部 256KB）之外的滚动历史无法恢复。
 - **shell 集成仅 zsh / bash**：其他 shell 自动跳过（`tty_capture{last}` 会
-  明确报错而非错报）；bash 3.2（macOS 自带）无 `PS0`，仅丢「命令开始」
-  标记——`tty_capture{last}` 依赖 B..D 区间，此时不可用，`tty_expect` 的
-  早停同步失效（超时路径不受影响）。用户 rc 若覆盖 `PROMPT_COMMAND`/钩子
-  数组，集成可能失效——可关闭 `shellIntegration` 或反馈补丁兼容。
+  明确报错而非错报）。bash < 4.4 走 DEBUG trap 兜底：循环体等复合命令的
+  内部命令会多发 B 标记，`tty_capture{last}` 对这类命令只截取最后一个内部
+  命令之后的输出（退出码与 `tty_expect` 不受影响）。用户 rc 若覆盖
+  `PROMPT_COMMAND`/钩子数组，集成可能失效——可关闭 `shellIntegration` 或
+  反馈补丁兼容。
 - **端口转发边界**：本地监听固定 127.0.0.1（不暴露局域网）；remote 方向服务端监听还受服务端 sshd `GatewayPorts` 限制；隧道的 SSH 连接与终端会话独立，均走 TOFU 钉扎与连接簿认证；隧道规格变更（端口/目标/启停）经「保存」热生效，热改连接簿凭证则在下次重连时生效。
+- **会话持久化（tmux）边界**：持久标签由 tmux server（专用 socket `dsh-tty`）托管——宿主被硬杀 / 保活回收 / 浏览器丢失标签规格时，tmux 会话会**留存**（这正是恢复能力的前提），直到机器重启或手动 `tmux -L dsh-tty kill-server`；agent 命令粒度工具（capture{last}/expect）依赖 tmux ≥3.3 的 DCS `allow-passthrough`，更低版本持久化可用但该能力降级（SSH 远程会话不注入 shell 集成钩子，capture{last} 本就不可用，与持久化无关）；恢复接回重画的是当前可见屏，断线前的滚动历史在 tmux 自己的 history buffer（copy-mode）里，不在外层 xterm 滚动区；持久标签的 `exit` 帧退出码是 tmux 客户端的（0），shell 退出码经 OSC 133;D 标记照常可用；`tmux.conf` 只在 tmux server 首启时读取（改配置后需 `tmux -L dsh-tty kill-server` 让下次 spawn 重建 server）；`grace=0` 的「断开立即结束」对持久标签同样会 kill-session（tmux 会话不存活）；持久 SSH 会话要求远程装有 tmux（未装自动降级普通会话，连接栏常驻「未持久化」标记），且远程 `~/.tmux.conf` 不影响专用 socket 的独立 conf（`-f /dev/null`）；SSH 持久会话名随 settings 留存；**两个窗口同时接回同一持久会话**时共享同一个宿主 PTY（0.10.1，单客户端扇出，名额不翻倍），两侧行数以最近调整尺寸的窗口为准（尺寸不一致时较大一侧由 onResize 自愈重画）。
+- **SFTP 边界**：文件权限 = 对应 SSH 账号的终端权限（无额外沙箱/chroot）；下载经浏览器内存（超大文件建议终端 `scp`/`rsync`）；agent 工具 `sftp_read` ≤1MB 且拒绝二进制、`sftp_write` 单次 ≤1MB（大内容走面板上传或终端）；`sftp_*` 工具只收连接簿条目名，内联凭证仅供面板对话框使用。
 - **SSH host key 为 TOFU 钉扎**：首次连接自动记录 sha256 指纹（trust on
   first use），之后指纹一致放行、变更拒绝——不再是无条件放行的
   accept-and-log。注意 TOFU 的固有边界：首次连接若已遭遇 MITM 则记录的
@@ -274,9 +393,20 @@ pnpm --filter @hyzyn/dsh-tty ssh-smoke    # SSH 冒烟：内存 SSH server（ssh
   │  残包 carry）→ 命令边界捕获（tty_capture{last} / tty_expect 早停）
   │  与 cwd 跟随（tty_list）
   ├─ 本地路径：ctx.get('subprocess').spawnTerminal({ argv: shell -c 包装层, cwd })
+  │  持久标签（0.10.0）：包装层换 `exec tmux -L dsh-tty -f <conf> new -A -s dsh-<名>`
+  │  （src/tmux.ts：探测/资产生成/spawn 计划/kill-session；稳定资产在
+  │  <DSH_HOME|~/.dsh>/tty/——tmux.conf + inner.sh + zsh/bash 桩；tmux 会吞
+  │  不认识的序列，shell 集成钩子检测 $TMUX 把 OSC 133/7 包 DCS passthrough
+  │  信封，tmux ≥3.3 解包转发，宿主解析器零改动）
   ├─ 辅助路由：/api/dsh-tty/ssh-config（~/.ssh/config 导入候选）、
   │  /api/dsh-tty/env-vars（env 插件托管变量名）、/api/dsh-tty/known-hosts
-  │  （TOFU 指纹预填充，src/known-hosts.ts 解析含 hashed 条目）——均 loopback 围栏
+  │  （TOFU 指纹预填充，src/known-hosts.ts 解析含 hashed 条目）、
+  │  /api/dsh-tty/shells（Shell 路径候选）——均 loopback 围栏
+  ├─ SFTP（src/sftp.ts，0.7.0）：懒连接池（空闲 120s 回收、断开按需重连、
+  │  TOFU 共用）→ POST /api/dsh-tty/sftp/list|mkdir|rename|remove|download|
+  │  upload（spec 走体/头，凭证不进 URL；上传下载流式 pipe）+
+  │  sftp_list/read/write/mkdir/rename/remove/tree 工具（只收连接簿名；
+  │  mkdir 支持 parents 自底向上逐级补齐，tree 限深限数递归列举）
   ├─ 端口转发（src/tunnels.ts）：宿主自持隧道（-L/-R 双向），断线退避重连、
   │  TOFU 共用、连接计数；GET /api/dsh-tty/tunnels 实时状态 + tunnel_list 工具
   └─ 帧协议：spawn|ssh / input / resize / kill / sessions / attach
@@ -287,15 +417,30 @@ SSH 路径 (src/ssh.ts，方案 C)
      password·passphrase 支持 env:VAR 取密；host key 经 HostKeyStore
      TOFU 钉扎），开 shell channel 包装成与 PTY 同形状的 TermHandle
      （pid=null，kind='ssh'，target=user@host[:port]），
-     背压一并透传到 channel —— 之后与本地 PTY 无差别调度
+     背压一并透传到 channel —— 之后与本地 PTY 无差别调度；
+     persist 时先 `command -v tmux` 探测再 `exec tmux -L dsh-tty -f /dev/null
+     new -A -s dsh-<名>` 开 pty channel（远程 tmux 托管；无 tmux 降级普通
+     shell channel + 灰字提示；kill 经连接内 `tmux kill-session` 收尾）
 ```
 
-M0 探针、集成测试（B1~B17 共 35 项断言）与真实实例冒烟（live / TUI）在
+M0 探针、集成测试（B1~B24 共 58 项断言）与真实实例冒烟（live / TUI）在
 真实 DSH 服务组合上验证过：TERM 注入、resize 透传、sid 冲突、并发上限、
 loopback 围栏、多会话数据隔离、cwd 跟随与校验、配置热生效（settings/updated）、
 kill→exit 全链路、断线保活 + sessions/attach 重连回放、tty_screen 虚拟屏、
 tty_capture ANSI 清洗、shell 集成（capture{last} + exitCode、OSC 7 cwd
-跟随）、tty_expect 匹配与超时、~/.ssh/config 解析器、端口转发（双隧道 active + forwardOut 往返 + reconcile 清理）。SSH 路径由 `ssh-smoke`
+跟随）、tty_expect 匹配与超时、~/.ssh/config 解析器、端口转发（双隧道 active + forwardOut 往返 + reconcile 清理）、
+shells 候选路由、bash 3.2 shell 集成（DEBUG trap 兜底：capture{last} +
+exitCode、tty_expect 命令结束早停）、SFTP 文件传输（list/mkdir/upload/
+download/remove 路由 + sftp_* 工具，test-sshd 内存 sshd 端到端）、SFTP 管理
+闭环（agent sftp_mkdir/-rename/-remove/-tree：parents 补齐、tree 限深截断、
+跨目录移动、非空删除拒绝与递归删除）；会话持久化（B25/B26：persistence
+门控、tmux 会话托管与 kill-session 收尾、无 tmux 降级提示、DCS passthrough
+下 capture{last}、保活回收只杀 PTY 不杀 tmux 会话、同 persistName 接回现场
+——本机无 tmux 时自动只跑降级路径）。SSH 路径由 `ssh-smoke`
 （内存 SSH server × 真实 `spawnSsh`）验证：password 认证建链与 prompt、
 命令往返、pty-req 初始尺寸与 resize（window-change）、terminate /
-exit-status 全链路，以及 TOFU 指纹记录（S7）与指纹变更拒绝连接（S8）。
+exit-status 全链路，以及 TOFU 指纹记录（S7）与指纹变更拒绝连接（S8）；
+SFTP 由 ssh-smoke S9（test-sshd 的 sftp subsystem × 真实 SftpManager）覆盖：
+目录列表与 realpath home、上传覆盖+追加、下载（stat size 作 content-length）、
+mkdir/rename/非递归删除拒绝/递归删除、TOFU 指纹变更拒绝；S9g 覆盖 mkdir
+`parents` 自底向上逐级补齐（幂等）与 `tree` 限深截断/全量。