@hyzyn/dsh-tty 0.18.2 → 0.19.0

package/scripts/integration.mjs

@@ -0,0 +1,1691 @@
+#!/usr/bin/env node
+/**
+ * @hyzyn/dsh-tty — M1 集成测试：把构建后的真实插件（lib/index.js）加载进
+ * 真实 DSH 服务组合（dsh-host-webserver + dsh-subprocess-local），模拟浏览器
+ * 半体用 ws 客户端完整走一遍协议，并验证边界：
+ *   B1. spawn → ready → data（输入回显）→ kill → exit 全链路
+ *   B2. resize 帧生效（stty size 校验）
+ *   B3. 单会话约束：同连接二次 spawn 报「会话已存在」
+ *   B4. maxSessions 上限：第二连接 spawn 报「会话数已达上限」
+ *   B5. loopback 围栏：伪造 Host 的 upgrade 请求被拒
+ *   B6. TERM 注入（-c 包装层）生效
+ *   B7. 单连接多会话：共存、数据隔离、单独 kill
+ *   B8. cwd 跟随与校验
+ *   B9. 配置热生效（settings/updated）
+ *   B10. /api/dsh-tty/config 读写 API
+ *   B11. 超限被拒后的恢复
+ *   B12. agent 工具集（tty_list / tty_capture / tty_screen / tty_expect / tty_send）
+ *   B13. 断线保活与重连（sessions/attach 帧，协议 v3）
+ *   B14. tty_screen 虚拟屏 + tty_capture ANSI 清洗
+ *   B15. shell 集成（OSC 133 命令捕获/退出码 + OSC 7 cwd 跟随）
+ *   B16. ~/.ssh/config 解析器
+ *   B17. tty_expect 匹配与超时
+ *   B18. data 帧合并后帧序不变量（exit 在最后一帧 data 之后）
+ *   B19. known_hosts 解析器
+ *   B20. 端口转发隧道（forwardOut 往返 + forwardIn 就绪 + 状态与工具）
+ *   B21. /api/dsh-tty/shells 候选列表（Shell 路径可选可输入的数据源）
+ *   B22. bash 3.2（无 PS0）shell 集成：DEBUG trap 兜底 B 标记（capture{last} + expect 早停）
+ *   B23. SFTP 文件传输（/api/dsh-tty/sftp/* 路由：list/mkdir/upload/download/remove
+ *        + agent 工具 sftp_list/sftp_read/sftp_write，test-sshd 内存 sshd）
+ *   B24. SFTP 管理闭环（agent sftp_mkdir/sftp_rename/sftp_remove/sftp_tree：
+ *        mkdir -p、tree 限深截断、跨目录 rename、非空删除拒绝与递归删除）
+ *   B25. 会话持久化（tmux，0.10.0）：配置门控、tmux 会话托管、kill-session
+ *        收尾、shell 集成 DCS passthrough（capture{last}）；无 tmux 时降级
+ *        普通会话 + 灰字提示（本机无 tmux 则跳过 tmux 断言）
+ *   B26. 持久恢复（tmux）：保活回收只杀 PTY 不杀 tmux 会话；同 persistName
+ *        重新 spawn 按 `tmux -A` 接回原现场（屏幕重画含此前输出）
+ *   B27. 跨窗口共享（0.10.1）：同 persistName 二次 spawn 重绑定现有宿主会话
+ *        （不新建 PTY / 不占名额）、输出扇出、kill 广播 exit
+ *   B29. 禁用热生效（enabled 开关）：工具/公告撤下与恢复、数据路由 403、
+ *        /config 保持可读写、存量 WS 被关闭与新升级被拒
+ *
+ * 用法：pnpm --filter @hyzyn/dsh-tty integration
+ * 退出码：0 = 全部 PASS，1 = 任一 FAIL。
+ */
+import { Context } from '@deepseek-ai/cordis'
+import WebServerRuntime from '@deepseek-ai/dsh-host-webserver'
+import { LocalSubprocessRuntime } from '@deepseek-ai/dsh-subprocess-local'
+import WebSocket from 'ws'
+import fsp from 'node:fs/promises'
+import net from 'node:net'
+import os from 'node:os'
+import path from 'node:path'
+import { name, inject, apply } from '../lib/index.js'
+import { parseSshConfig } from '../lib/ssh-config.js'
+import { parseKnownHosts } from '../lib/known-hosts.js'
+import { assertSupportedJsonSchema } from '@deepseek-ai/dsh-tools'
+import { startSftpSshd, TEST_USER, TEST_PASSWORD } from './lib/test-sshd.mjs'
+
+
+/* 全局看门狗：任何环节卡死时留痕退出（正常路径会先 process.exit）。 */
+setTimeout(() => {
+  console.error('[watchdog] 120s 看门狗触发：集成测试卡死')
+  process.exit(2)
+}, 120000).unref()
+process.on('unhandledRejection', (reason) => {
+  console.error('[unhandledRejection]', reason)
+})
+
+const RESULTS = []
+function pass(name) { RESULTS.push(['PASS', name]); console.log('  ✔ PASS  ' + name) }
+function fail(name, detail) { RESULTS.push(['FAIL', name, detail]); console.error('  ✘ FAIL  ' + name + (detail ? ' — ' + detail : '')) }
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** 简易 ws 会话客户端：收集 data 帧文本，提供 send 与等待匹配。 */
+function openSession(port, headers) {
+  const client = new WebSocket(`ws://127.0.0.1:${port}/api/dsh-tty/ws`, { headers })
+  client.setMaxListeners(0) // 测试里多次重连会反复挂 once 监听，避免告警
+  const state = {
+    frames: [],
+    text: '',
+    ready: false,
+    exited: null,
+    errors: [],
+    closed: false,
+    waiters: [],
+  }
+  client.on('message', (raw) => {
+    const msg = JSON.parse(raw.toString())
+    state.frames.push(msg)
+    // 收集器剥掉 shell 集成标记（133;B 与命令输出同行，会粘住 ^…$ 行匹配）
+    if (msg.t === 'data') state.text += String(msg.d ?? '').replace(/\x1b\]133;[ABDC](?:;\d+)?(?:\x07|\x1b\\)|\x1b\]7;[^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+    if (msg.t === 'ready') state.ready = true
+    if (msg.t === 'exit') state.exited = { sid: msg.sid, code: msg.code, signal: msg.signal }
+    if (msg.t === 'error') state.errors.push(String(msg.m ?? ''))
+    for (const w of [...state.waiters]) w()
+  })
+  client.on('close', () => {
+    state.closed = true
+    for (const w of [...state.waiters]) w()
+  })
+  const waitFor = async (pred, timeoutMs = 12000, label = '条件') => {
+    const start = Date.now()
+    while (!pred()) {
+      if (Date.now() - start > timeoutMs) {
+        // 超时信息带上下文（0.19.0）：受限环境里 PTY spawn 被拒时此前只显示
+        // 「已收文本: ""」，排查者会误判成插件 bug——error 帧 / 退出事实一并打出
+        const details = [`已收文本: ${JSON.stringify(state.text.slice(-200))}`]
+        if (state.errors.length > 0) details.push(`error 帧: ${JSON.stringify(state.errors.slice(-3))}`)
+        if (state.exited !== null && state.exited !== undefined) details.push(`进程已退出: ${JSON.stringify(state.exited)}`)
+        if (state.closed) details.push('ws 已关闭')
+        throw new Error(`等待${label}超时（${details.join('；')}）`)
+      }
+      await Promise.race([
+        new Promise((resolve) => state.waiters.push(resolve)),
+        sleep(200),
+      ])
+    }
+  }
+  const open = async () => {
+    const start = Date.now()
+    let lastError = ''
+    while (client.readyState !== WebSocket.OPEN) {
+      if (Date.now() - start > 10000) throw new Error('ws 连接超时：' + (lastError || '无错误事件') + '（可能 upgrade 路由未就绪）')
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, 100)
+        client.once('open', () => { clearTimeout(timer); resolve() })
+        client.once('error', (error) => { lastError = error.message })
+        client.once('close', () => { clearTimeout(timer); resolve() })
+      })
+    }
+  }
+  return { client, state, waitFor, open }
+}
+
+async function run() {
+  const app = new Context()
+  const wsFiber = app.plugin(WebServerRuntime, { host: '127.0.0.1', port: 0 })
+  const subFiber = app.plugin(LocalSubprocessRuntime)
+  // 最小 settings 服务 stub：让插件的 settings 注入回调触发，并可手动派发
+  // settings/updated 事件（与 dsh-settings 的 dispatch 方式一致）来测配置热生效。
+  const toolDefs = []
+  const promptParts = []
+  const stubFiber = app.plugin({
+    name: 'settings-stub',
+    apply: (ctx) => {
+      ctx.provide('settings', { register: () => ({ get: () => ({}), update: async () => {} }) })
+      ctx.provide('tools', {
+        register: (definition) => {
+          toolDefs.push(definition)
+          // dispose 必须真摘除：B29 禁用场景要断言「工具全部撤下」
+          return () => {
+            const index = toolDefs.indexOf(definition)
+            if (index >= 0) toolDefs.splice(index, 1)
+          }
+        },
+      })
+      // systemPrompt 桩：记录 section/context 注册与撤下（B29 公告断言用）
+      ctx.provide('systemPrompt', {
+        section: (options) => {
+          promptParts.push(options)
+          return () => {
+            const index = promptParts.indexOf(options)
+            if (index >= 0) promptParts.splice(index, 1)
+          }
+        },
+        context: (options) => {
+          promptParts.push(options)
+          return () => {
+            const index = promptParts.indexOf(options)
+            if (index >= 0) promptParts.splice(index, 1)
+          }
+        },
+      })
+    },
+  })
+  await stubFiber.await()
+  const emitSettingsUpdated = (ns, next) => {
+    const args = ['settings/updated', ns, next, {}, 'test']
+    for (const cb of app.events.dispatch('emit', args)) cb(...args)
+  }
+  const pluginFiber = app.plugin({ name, inject, apply }, { maxSessions: 2, term: 'xterm-256color', colorTerm: 'truecolor' })
+  await wsFiber.await()
+  await subFiber.await()
+  await pluginFiber.await()
+  const port = app.webServer.port
+  console.log(`webServer on 127.0.0.1:${port}，插件已挂载`)
+  await sleep(400) // 等 ctx.inject(['webServer']) 回调完成路由注册
+
+  // B1 + B6: 全链路 + TERM
+  console.log('\n[1] 全链路（spawn→data→kill→exit）与 TERM 注入')
+  {
+    const s = openSession(port)
+    await s.open()
+    s.client.send(JSON.stringify({ t: 'spawn', cols: 80, rows: 24 }))
+    await s.waitFor(() => s.state.ready, 10000, 'ready')
+    s.client.send(JSON.stringify({ t: 'input', d: 'printf "IT_TERM_%s\\n" "$TERM"\n' }))
+    await s.waitFor(() => /IT_TERM_xterm-256color/.test(s.state.text), 10000, 'TERM 输出')
+    pass('B6 TERM 注入生效（xterm-256color）')
+    s.client.send(JSON.stringify({ t: 'input', d: 'printf "IT_READY_%s\\n" OK\n' }))
+    await s.waitFor(() => /IT_READY_OK/.test(s.state.text), 10000, '回显')
+    pass('B1a spawn→data 全链路（输入回显可见）')
+    s.client.send(JSON.stringify({ t: 'kill' }))
+    await s.waitFor(() => s.state.exited !== null, 10000, 'exit 帧')
+    pass('B1b kill→exit 帧（code=' + s.state.exited.code + ' signal=' + s.state.exited.signal + '）')
+    s.client.close()
+  }
+
+  // B2: resize
+  console.log('\n[2] resize 帧')
+  {
+    const s = openSession(port)
+    await s.open()
+    s.client.send(JSON.stringify({ t: 'spawn', cols: 80, rows: 24 }))
+    await s.waitFor(() => s.state.ready, 10000, 'ready')
+    s.client.send(JSON.stringify({ t: 'input', d: 'stty size\n' }))
+    await s.waitFor(() => /^\d+ \d+$/m.test(s.state.text), 10000, '初始尺寸')
+    const before = s.state.text.match(/^(\d+) (\d+)$/m)
+    s.client.send(JSON.stringify({ t: 'resize', cols: 110, rows: 33 }))
+    await sleep(400)
+    s.client.send(JSON.stringify({ t: 'input', d: 'stty size\n' }))
+    const after = await new Promise((resolve, reject) => {
+      const start = Date.now()
+      const check = () => {
+        const matches = [...s.state.text.matchAll(/^(\d+) (\d+)$/gm)]
+        const last = matches[matches.length - 1]
+        if (last !== undefined && last.index !== before.index) return resolve(last)
+        if (Date.now() - start > 10000) return reject(new Error('resize 后 stty size 超时'))
+        setTimeout(check, 50)
+      }
+      check()
+    })
+    const ok = Number(after[1]) === 33 && Number(after[2]) === 110
+    console.log(`    before=${before[1]}x${before[2]} after=${after[1]}x${after[2]}（期望 33x110）`)
+    if (ok) pass('B2 resize 帧生效')
+    else fail('B2 resize 帧生效', `${after[1]}x${after[2]}`)
+    s.client.send(JSON.stringify({ t: 'kill' }))
+    await s.waitFor(() => s.state.exited !== null, 10000, 'exit')
+    s.client.close()
+  }
+
+  // B3: sid 冲突约束（v2：同连接多会话，同 sid 才拒绝）
+  console.log('\n[3] sid 冲突约束')
+  {
+    const s = openSession(port)
+    await s.open()
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'tab-a' }))
+    await s.waitFor(() => s.state.ready, 10000, 'ready')
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'tab-a' }))
+    await s.waitFor(() => s.state.errors.length > 0, 10000, '重复 sid 错误')
+    if (/sid 已存在/.test(s.state.errors[0])) pass('B3 同 sid 二次 spawn 被拒')
+    else fail('B3 同 sid 二次 spawn 被拒', s.state.errors[0])
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'tab-a' }))
+    await s.waitFor(() => s.state.exited !== null, 10000, 'exit')
+    s.client.close()
+  }
+
+  // B4: maxSessions 上限（跨连接）
+  console.log('\n[4] maxSessions 上限')
+  {
+    const s1 = openSession(port)
+    await s1.open()
+    s1.client.send(JSON.stringify({ t: 'spawn', sid: 's1' }))
+    await s1.waitFor(() => s1.state.ready, 10000, 's1 ready')
+    const s2 = openSession(port)
+    await s2.open()
+    s2.client.send(JSON.stringify({ t: 'spawn', sid: 's2' }))
+    await s2.waitFor(() => s2.state.ready, 10000, 's2 ready')
+    const s3 = openSession(port)
+    await s3.open()
+    s3.client.send(JSON.stringify({ t: 'spawn', sid: 's3' }))
+    await s3.waitFor(() => s3.state.errors.length > 0, 10000, 's3 上限错误')
+    if (/会话数已达上限/.test(s3.state.errors[0])) pass('B4 maxSessions=2 生效（第三连接被拒）')
+    else fail('B4 maxSessions=2 生效（第三连接被拒）', s3.state.errors[0])
+    s3.client.close()
+    s2.client.send(JSON.stringify({ t: 'kill', sid: 's2' }))
+    await s2.waitFor(() => s2.state.exited !== null, 10000, 's2 exit')
+    s2.client.close()
+    s1.client.send(JSON.stringify({ t: 'kill', sid: 's1' }))
+    await s1.waitFor(() => s1.state.exited !== null, 10000, 's1 exit')
+    s1.client.close()
+  }
+
+  // B5: loopback 围栏
+  console.log('\n[5] loopback 围栏')
+  {
+    const s = openSession(port, { Host: 'attacker.example.com' })
+    let outcome
+    try {
+      await s.open()
+      outcome = 'open'
+    } catch {
+      outcome = s.client.readyState === WebSocket.CLOSED ? 'rejected' : 'other'
+    }
+    if (outcome === 'rejected') pass('B5 伪造 Host 的 upgrade 被拒')
+    else fail('B5 伪造 Host 的 upgrade 被拒', '连接意外建立（' + outcome + '）')
+    try { s.client.terminate() } catch { /* 忽略 */ }
+  }
+
+  // B7: 单连接多会话（共存、数据隔离、单独 kill）
+  console.log('\n[6] 单连接多会话')
+  {
+    const s = openSession(port)
+    await s.open()
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'tab-1' }))
+    await s.waitFor(() => s.state.ready, 10000, 'tab-1 ready')
+    s.state.ready = false
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'tab-2' }))
+    await s.waitFor(() => s.state.ready, 10000, 'tab-2 ready')
+    s.client.send(JSON.stringify({ t: 'input', sid: 'tab-1', d: 'printf "TAB1_%s\\n" OK\n' }))
+    await s.waitFor(() => /TAB1_OK/.test(s.state.text), 10000, 'tab-1 回显')
+    s.client.send(JSON.stringify({ t: 'input', sid: 'tab-2', d: 'printf "TAB2_%s\\n" OK\n' }))
+    await s.waitFor(() => /TAB2_OK/.test(s.state.text), 10000, 'tab-2 回显')
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'tab-1' }))
+    await s.waitFor(() => s.state.exited !== null && s.state.exited.sid === 'tab-1', 10000, 'tab-1 exit（带 sid）')
+    s.client.send(JSON.stringify({ t: 'input', sid: 'tab-2', d: 'printf "TAB2_%s\\n" STILL\n' }))
+    await s.waitFor(() => /TAB2_STILL/.test(s.state.text), 10000, 'tab-2 仍可用')
+    // 竞态回归：对已删除 sid 发 input/resize 应静默忽略（无错误帧）
+    const errorsBefore = s.state.errors.length
+    s.client.send(JSON.stringify({ t: 'input', sid: 'tab-1', d: 'echo ghost\n' }))
+    s.client.send(JSON.stringify({ t: 'resize', sid: 'tab-1', cols: 90, rows: 20 }))
+    await sleep(600)
+    if (s.state.errors.length === errorsBefore) pass('B7b 已删除 sid 的 input/resize 静默忽略（无错误帧）')
+    else fail('B7b 已删除 sid 的 input/resize 静默忽略（无错误帧）', JSON.stringify(s.state.errors.slice(errorsBefore)))
+    pass('B7 单连接多会话：双 tab 共存、数据隔离、单独 kill 后另一 tab 存活')
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'tab-2' }))
+    await s.waitFor(() => s.state.exited !== null && s.state.exited.sid === 'tab-2', 10000, 'tab-2 exit')
+    s.client.close()
+  }
+
+  // B8: cwd 跟随与校验
+  console.log('\n[7] cwd 跟随与校验')
+  {
+    const s = openSession(port)
+    await s.open()
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'cwd-tab', cwd: '/tmp' }))
+    await s.waitFor(() => s.state.ready, 10000, 'ready')
+    s.client.send(JSON.stringify({ t: 'input', sid: 'cwd-tab', d: 'pwd\n' }))
+    await s.waitFor(() => s.state.text.includes('/tmp'), 10000, 'pwd 输出')
+    pass('B8 spawn 携带 cwd 生效（pwd=/tmp）')
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'bad-cwd', cwd: '/nonexistent-dir-xyz' }))
+    await s.waitFor(() => s.state.errors.some((m) => /cwd 不存在/.test(m)), 10000, 'cwd 错误')
+    pass('B8b 不存在的 cwd 被拒')
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'cwd-tab' }))
+    await s.waitFor(() => s.state.exited !== null, 10000, 'exit')
+    s.client.close()
+  }
+
+  // B9: 配置热生效（settings/updated → LiveConfig / maxSessions）
+  console.log('\n[8] 配置热生效')
+  {
+    const s = openSession(port)
+    await s.open()
+    emitSettingsUpdated('tty', { shell: '', term: 'xterm-256color', colorTerm: 'truecolor', cwd: '/tmp', maxSessions: 1 })
+    await sleep(300)
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'hot' })) // 不带 cwd → 应落到热改后的 /tmp
+    await s.waitFor(() => s.state.ready, 10000, 'ready')
+    s.client.send(JSON.stringify({ t: 'input', sid: 'hot', d: 'pwd\n' }))
+    await s.waitFor(() => s.state.text.includes('/tmp'), 10000, 'pwd=/tmp')
+    pass('B9 配置热生效：cwd 动态更新后新会话生效（pwd=/tmp）')
+    const s2 = openSession(port)
+    await s2.open()
+    s2.client.send(JSON.stringify({ t: 'spawn', sid: 's2' }))
+    await s2.waitFor(() => s2.state.errors.length > 0, 10000, 's2 上限错误')
+    if (/会话数已达上限/.test(s2.state.errors[0])) pass('B9b maxSessions 热改生效（上限降为 1）')
+    else fail('B9b maxSessions 热改生效（上限降为 1）', s2.state.errors[0])
+    s2.client.close()
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'hot' }))
+    await s.waitFor(() => s.state.exited !== null, 10000, 'exit')
+    s.client.close()
+  }
+
+  // B10: /api/dsh-tty/config 读写 API
+  console.log('\n[9] 配置 API')
+  {
+    const base = `http://127.0.0.1:${port}/api/dsh-tty/config`
+    const res1 = await fetch(base)
+    const d1 = await res1.json().catch(() => ({}))
+    if (res1.status === 200 && d1.ok === true && typeof d1.config?.shell === 'string') pass('B10a GET 当前配置')
+    else fail('B10a GET 当前配置', res1.status + ' ' + JSON.stringify(d1))
+    const res2 = await fetch(base, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ maxSessions: 3, term: 'xterm-256color' }) })
+    const d2 = await res2.json().catch(() => ({}))
+    if (res2.status === 200 && d2.ok === true && d2.config?.maxSessions === 3) pass('B10b POST 配置生效（maxSessions=3）')
+    else fail('B10b POST 配置生效（maxSessions=3）', res2.status + ' ' + JSON.stringify(d2))
+    const res3 = await fetch(base, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ maxSessions: 99 }) })
+    const d3 = await res3.json().catch(() => ({}))
+    if (res3.status === 400 && /maxSessions/.test(String(d3.error ?? ''))) pass('B10c 非法 maxSessions 被拒')
+    else fail('B10c 非法 maxSessions 被拒', res3.status + ' ' + JSON.stringify(d3))
+  }
+
+  // B11: 超限被拒后的恢复（用户场景：kill 一个会话后新 spawn 必须成功）
+  console.log('\n[10] 超限恢复')
+  {
+    const base = `http://127.0.0.1:${port}/api/dsh-tty/config`
+    await fetch(base, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ maxSessions: 2 }) })
+    await sleep(200)
+    const s1 = openSession(port)
+    await s1.open()
+    s1.client.send(JSON.stringify({ t: 'spawn', sid: 'x1' }))
+    await s1.waitFor(() => s1.state.ready, 10000, 'x1 ready')
+    const s2 = openSession(port)
+    await s2.open()
+    s2.client.send(JSON.stringify({ t: 'spawn', sid: 'x2' }))
+    await s2.waitFor(() => s2.state.ready, 10000, 'x2 ready')
+    const s3 = openSession(port)
+    await s3.open()
+    s3.client.send(JSON.stringify({ t: 'spawn', sid: 'x3' }))
+    await s3.waitFor(() => s3.state.errors.length > 0, 10000, 'x3 被拒')
+    if (/会话数已达上限/.test(s3.state.errors[0])) pass('B11a 超限拒绝（cap=2 第三个被拒）')
+    else fail('B11a 超限拒绝（cap=2 第三个被拒）', s3.state.errors[0])
+    s1.client.send(JSON.stringify({ t: 'kill', sid: 'x1' }))
+    await s1.waitFor(() => s1.state.exited !== null, 10000, 'x1 exit')
+    s3.client.send(JSON.stringify({ t: 'spawn', sid: 'x3b' }))
+    await s3.waitFor(() => s3.state.ready, 10000, 'x3b ready')
+    pass('B11b 释放名额后新 spawn 成功')
+    s2.client.send(JSON.stringify({ t: 'kill', sid: 'x2' }))
+    await s2.waitFor(() => s2.state.exited !== null, 10000, 'x2 exit')
+    s3.client.send(JSON.stringify({ t: 'kill', sid: 'x3b' }))
+    await s3.waitFor(() => s3.state.exited !== null, 10000, 'x3b exit')
+    s1.client.close()
+    s2.client.close()
+    s3.client.close()
+    await fetch(base, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ maxSessions: 4 }) })
+  }
+
+  // B12: agent 工具集（tty_list / tty_capture / tty_send）
+  console.log('\n[11] agent 工具集')
+  {
+    const s = openSession(port)
+    await s.open()
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 't12' }))
+    await s.waitFor(() => s.state.ready, 10000, 't12 ready')
+    const list = toolDefs.find((d) => d.name === 'tty_list')
+    const capture = toolDefs.find((d) => d.name === 'tty_capture')
+    const send = toolDefs.find((d) => d.name === 'tty_send')
+    if (list === undefined || capture === undefined || send === undefined) {
+      fail('B12 agent 工具集', '工具未注册: ' + toolDefs.map((d) => d.name).join(','))
+    } else {
+      // 真实宿主同样的校验（注册时 assertSupportedJsonSchema）
+      let schemaOk = true
+      for (const d of toolDefs.filter((x) => x.name.startsWith('tty_'))) {
+        try {
+          assertSupportedJsonSchema(d.parameters)
+          assertSupportedJsonSchema(d.output?.schema ?? {})
+        } catch (e) {
+          schemaOk = false
+          fail('B12e 工具 schema 通过 DSH 校验', d.name + ': ' + String(e && e.message ? e.message : e))
+        }
+      }
+      if (schemaOk) pass('B12e 工具 schema 通过 DSH 校验（assertSupportedJsonSchema）')
+      const listed = await list.execute({})
+      if (Array.isArray(listed.sessions) && listed.sessions.some((x) => x.sid === 't12')) pass('B12a tty_list 列出活跃会话')
+      else fail('B12a tty_list 列出活跃会话', JSON.stringify(listed))
+      const sent = await send.execute({ sid: 't12', data: 'printf "CAPTURE_%s\\n" OK\n' })
+      if (sent.ok === true && sent.sent > 0) pass('B12b tty_send 发送输入')
+      else fail('B12b tty_send 发送输入', JSON.stringify(sent))
+      await sleep(600)
+      // shell 执行有延迟（.zshrc 启动），轮询等待标记出现在输出缓冲
+      let captured = null
+      for (let i = 0; i < 16; i++) {
+        await sleep(250)
+        captured = await capture.execute({ sid: 't12', lines: 20 })
+        if (typeof captured.tail === 'string' && captured.tail.includes('CAPTURE_OK')) break
+      }
+      if (captured !== null && typeof captured.tail === 'string' && captured.tail.includes('CAPTURE_OK')) pass('B12c tty_capture 读到会话输出')
+      else fail('B12c tty_capture 读到会话输出', JSON.stringify(captured === null ? null : captured.tail).slice(0, 120))
+      let rejected = false
+      try {
+        await capture.execute({ sid: 'ghost-session' })
+      } catch {
+        rejected = true
+      }
+      if (rejected) pass('B12d 不存在的 sid 调用工具被拒')
+      else fail('B12d 不存在的 sid 调用工具被拒', '未抛错')
+    }
+    s.client.send(JSON.stringify({ t: 'kill', sid: 't12' }))
+    await s.waitFor(() => s.state.exited !== null, 10000, 't12 exit')
+    s.client.close()
+  }
+
+  // B13: 断线保活与重连（sessions/attach 帧，协议 v3）
+  console.log('\n[12] 断线保活与重连')
+  {
+    const s1 = openSession(port)
+    await s1.open()
+    s1.client.send(JSON.stringify({ t: 'spawn', sid: 're-1' }))
+    await s1.waitFor(() => s1.state.ready, 10000, 're-1 ready')
+    s1.client.send(JSON.stringify({ t: 'input', sid: 're-1', d: 'printf "REPLAY_%s\\n" MARK\n' }))
+    await s1.waitFor(() => /REPLAY_MARK/.test(s1.state.text), 10000, '回放标记输出')
+    // 不 kill 直接断开 = 异常断开：会话应转孤儿保活（默认 reconnectGraceSec=120）
+    s1.client.close()
+    await sleep(400)
+    const s2 = openSession(port)
+    await s2.open()
+    s2.client.send(JSON.stringify({ t: 'sessions' }))
+    await s2.waitFor(() => s2.state.frames.some((f) => f.t === 'sessions'), 10000, 'sessions 帧')
+    const sessionsFrame = s2.state.frames.find((f) => f.t === 'sessions')
+    const entry = (sessionsFrame?.list ?? []).find((x) => x.sid === 're-1')
+    if (entry !== undefined && entry.attachable === true) pass('B13a 异常断开后会话保活且 attachable')
+    else fail('B13a 异常断开后会话保活且 attachable', JSON.stringify(sessionsFrame))
+    // attach → ready（reattached:true）→ data 帧回放断线前输出
+    s2.client.send(JSON.stringify({ t: 'attach', sid: 're-1' }))
+    await s2.waitFor(() => s2.state.frames.some((f) => f.t === 'ready' && f.sid === 're-1'), 10000, 'attach ready')
+    if (s2.state.frames.some((f) => f.t === 'ready' && f.sid === 're-1' && f.reattached === true)) pass('B13b attach 成功（ready.reattached）')
+    else fail('B13b attach 成功（ready.reattached）', '缺 reattached 标记')
+    await s2.waitFor(() => /REPLAY_MARK/.test(s2.state.text), 10000, '缓冲回放')
+    pass('B13c attach 后回放断线前输出（REPLAY_MARK）')
+    s2.client.send(JSON.stringify({ t: 'input', sid: 're-1', d: 'printf "AFTER_%s\\n" ATTACH\n' }))
+    await s2.waitFor(() => /AFTER_ATTACH/.test(s2.state.text), 10000, 'attach 后输入')
+    pass('B13d attach 后会话继续交互')
+    // 已连接会话的重复 attach 被拒（防多窗口抢绑）
+    const errorsBefore = s2.state.errors.length
+    s2.client.send(JSON.stringify({ t: 'attach', sid: 're-1' }))
+    await s2.waitFor(() => s2.state.errors.length > errorsBefore, 10000, '重复 attach 错误')
+    if (/已连接/.test(s2.state.errors[s2.state.errors.length - 1])) pass('B13e 已连接会话的重复 attach 被拒')
+    else fail('B13e 已连接会话的重复 attach 被拒', s2.state.errors[s2.state.errors.length - 1])
+    s2.client.send(JSON.stringify({ t: 'kill', sid: 're-1' }))
+    await s2.waitFor(() => s2.state.exited !== null && s2.state.exited.sid === 're-1', 10000, 're-1 exit')
+    s2.client.close()
+  }
+
+  // B14: tty_screen 虚拟屏 + tty_capture ANSI 清洗
+  console.log('\n[13] tty_screen 与 tty_capture 清洗')
+  {
+    const s = openSession(port)
+    await s.open()
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'screen-1' }))
+    await s.waitFor(() => s.state.ready, 10000, 'screen-1 ready')
+    const screenTool = toolDefs.find((d) => d.name === 'tty_screen')
+    const capture = toolDefs.find((d) => d.name === 'tty_capture')
+    if (screenTool === undefined || capture === undefined) {
+      fail('B14 工具注册', '缺工具: ' + toolDefs.map((d) => d.name).join(','))
+    } else {
+      s.client.send(JSON.stringify({ t: 'input', sid: 'screen-1', d: 'printf "SCREEN_%s\\n" OK\n' }))
+      await s.waitFor(() => /SCREEN_OK/.test(s.state.text), 10000, '屏幕标记输出')
+      // tty_screen：虚拟屏渲染的可见屏幕应包含标记（等价用户此刻看到的画面）
+      let shot = null
+      for (let i = 0; i < 16; i++) {
+        await sleep(250)
+        shot = await screenTool.execute({ sid: 'screen-1' })
+        if (typeof shot?.text === 'string' && shot.text.includes('SCREEN_OK')) break
+      }
+      if (shot !== null && typeof shot.text === 'string' && shot.text.includes('SCREEN_OK')) pass('B14a tty_screen 虚拟屏渲染可见屏幕（SCREEN_OK）')
+      else fail('B14a tty_screen 虚拟屏渲染可见屏幕（SCREEN_OK）', JSON.stringify(shot === null ? null : shot.text).slice(0, 120))
+      // tty_capture：默认清洗后尾部应为纯文本（无 ESC 转义）且包含标记
+      let cap = null
+      for (let i = 0; i < 16; i++) {
+        await sleep(250)
+        cap = await capture.execute({ sid: 'screen-1', lines: 80 })
+        if (typeof cap.tail === 'string' && cap.tail.includes('SCREEN_OK')) break
+      }
+      const cleanOk = cap !== null && typeof cap.tail === 'string' && cap.tail.includes('SCREEN_OK') && !/\x1b/.test(cap.tail)
+      if (cleanOk) pass('B14b tty_capture 默认清洗 ANSI（尾部为纯文本且含标记）')
+      else fail('B14b tty_capture 默认清洗 ANSI（尾部为纯文本且含标记）', JSON.stringify(cap === null ? null : cap.tail).slice(0, 120))
+    }
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'screen-1' }))
+    await s.waitFor(() => s.state.exited !== null, 10000, 'screen-1 exit')
+    s.client.close()
+  }
+
+  // B15: shell 集成（OSC 133/7）—— 命令捕获 + 退出码 + cwd 跟随（真实 zsh）
+  console.log('\n[14] shell 集成（OSC 133/7）')
+  {
+    const s = openSession(port)
+    await s.open()
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'si-1' }))
+    await s.waitFor(() => s.state.ready, 10000, 'si-1 ready')
+    const capture = toolDefs.find((d) => d.name === 'tty_capture')
+    const list = toolDefs.find((d) => d.name === 'tty_list')
+    const expect = toolDefs.find((d) => d.name === 'tty_expect')
+    if (capture === undefined || list === undefined || expect === undefined) {
+      fail('B15 工具注册', '缺工具: ' + toolDefs.map((d) => d.name).join(','))
+    } else {
+      s.client.send(JSON.stringify({ t: 'input', sid: 'si-1', d: 'printf "SI_%s\\n" OK\n' }))
+      await s.waitFor(() => /SI_OK/.test(s.state.text), 10000, 'SI_OK 输出')
+      await sleep(600) // 等 D 标记（precmd 在下一 prompt 前发出）
+      let last = null
+      for (let i = 0; i < 12; i++) {
+        await sleep(250)
+        try {
+          last = await capture.execute({ sid: 'si-1', last: true })
+        } catch (error) {
+          last = { error: error.message }
+        }
+        if (last !== null && last.source === 'last') break
+      }
+      if (last !== null && last.source === 'last' && String(last.tail).includes('SI_OK') && last.exitCode === 0) pass('B15a tty_capture{last:true} 拿到命令输出 + exitCode=0')
+      else fail('B15a tty_capture{last:true} 拿到命令输出 + exitCode=0', JSON.stringify(last).slice(0, 160))
+      // OSC 7：cd 之后 tty_list 的 cwd 跟随
+      s.client.send(JSON.stringify({ t: 'input', sid: 'si-1', d: 'cd /tmp\n' }))
+      let cwdOk = false
+      for (let i = 0; i < 16 && !cwdOk; i++) {
+        await sleep(300)
+        const listed = await list.execute({})
+        const entry = listed.sessions.find((x) => x.sid === 'si-1')
+        cwdOk = entry !== undefined && entry.cwd === '/tmp'
+      }
+      if (cwdOk) pass('B15b OSC 7 cwd 上报生效（tty_list 跟随 cd /tmp）')
+      else fail('B15b OSC 7 cwd 上报生效（tty_list 跟随 cd /tmp）', 'cwd 未更新')
+    }
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'si-1' }))
+    await s.waitFor(() => s.state.exited !== null, 10000, 'si-1 exit')
+    s.client.close()
+  }
+
+  // B16: ~/.ssh/config 解析器（纯函数，不读文件系统）
+  console.log('\n[15] ssh-config 解析器')
+  {
+    const sample = [
+      '# comment',
+      'Host web1',
+      '  HostName web1.example.com',
+      '  User alice',
+      '  Port 2222',
+      '  IdentityFile ~/.ssh/id_ed25519',
+      '',
+      'Host = db1',
+      '  hostname = db1.internal # inline comment',
+      '  user = bob',
+      '',
+      'Host *',
+      '  Compression yes',
+      '',
+      'Host nouser',
+      '  HostName nowhere',
+    ].join('\n')
+    const entries = parseSshConfig(sample)
+    const web1 = entries.find((e) => e.name === 'web1')
+    const db1 = entries.find((e) => e.name === 'db1')
+    const ok = entries.length === 2
+      && web1 !== undefined && web1.host === 'web1.example.com' && web1.username === 'alice'
+      && web1.port === 2222 && web1.auth === 'key' && web1.keyPath === '~/.ssh/id_ed25519'
+      && db1 !== undefined && db1.host === 'db1.internal' && db1.username === 'bob' && db1.auth === 'agent'
+      && db1.port === 22
+    if (ok) pass('B16 ssh-config 解析（别名/=/行内注释/IdentityFile→key/通配与无User跳过）')
+    else fail('B16 ssh-config 解析（别名/=/行内注释/IdentityFile→key/通配与无User跳过）', JSON.stringify(entries))
+  }
+
+  // B17: tty_expect —— 匹配与超时两分支
+  console.log('\n[16] tty_expect')
+  {
+    const s = openSession(port)
+    await s.open()
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'ex-1' }))
+    await s.waitFor(() => s.state.ready, 10000, 'ex-1 ready')
+    const expect = toolDefs.find((d) => d.name === 'tty_expect')
+    if (expect === undefined) {
+      fail('B17 tty_expect 注册', '未找到 tty_expect')
+    } else {
+      // 先注册等待再发命令（工具内部同步挂 output 监听，无竞态窗口）
+      const pendingOk = expect.execute({ sid: 'ex-1', pattern: 'EXPECT_HIT', timeoutSec: 15 })
+      await sleep(300)
+      s.client.send(JSON.stringify({ t: 'input', sid: 'ex-1', d: 'sleep 1; printf "EXPECT_%s\\n" HIT\n' }))
+      const okResult = await pendingOk
+      if (okResult.matched === true && okResult.timedOut === false && /EXPECT_HIT/.test(okResult.text)) pass('B17a tty_expect 等到就绪标记（matched=true）')
+      else fail('B17a tty_expect 等到就绪标记（matched=true）', JSON.stringify(okResult).slice(0, 160))
+      await sleep(800) // 等上一条命令的 D 标记与 prompt 落定，走纯超时分支
+      const missResult = await expect.execute({ sid: 'ex-1', pattern: 'NEVER_APPEARS_XYZ', timeoutSec: 1 })
+      if (missResult.matched === false && missResult.timedOut === true && typeof missResult.text === 'string') pass('B17b tty_expect 超时不抛错（matched=false, timedOut=true）')
+      else fail('B17b tty_expect 超时不抛错（matched=false, timedOut=true）', JSON.stringify(missResult).slice(0, 160))
+    }
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'ex-1' }))
+    await s.waitFor(() => s.state.exited !== null, 10000, 'ex-1 exit')
+    s.client.close()
+  }
+
+  // B18: data 帧合并与帧序不变量（exit 永远在最后一帧 data 之后）
+  console.log('\n[17] data 帧合并与帧序')
+  {
+    const s = openSession(port)
+    await s.open()
+    console.log('    [B18] spawning…')
+    s.client.send(JSON.stringify({ t: 'spawn', sid: 'co-1' }))
+    await s.waitFor(() => s.state.ready, 10000, 'co-1 ready')
+    console.log('    [B18] ready ✓')
+    s.client.send(JSON.stringify({ t: 'input', sid: 'co-1', d: 'printf "COARSE_%s\\n" OK\n' }))
+    console.log('    [B18] input sent')
+    await s.waitFor(() => /COARSE_OK/.test(s.state.text), 10000, 'COARSE_OK 输出')
+    console.log('    [B18] COARSE_OK ✓')
+    await sleep(300)
+    console.log('    [B18] killing…')
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'co-1' }))
+    await s.waitFor(() => s.state.exited !== null && s.state.exited.sid === 'co-1', 10000, 'co-1 exit')
+    console.log('    [B18] exit ✓')
+    const exitIndex = s.state.frames.findIndex((f) => f.t === 'exit' && f.sid === 'co-1')
+    const lastDataIndex = s.state.frames.reduce((acc, f, i) => (f.t === 'data' && f.sid === 'co-1' ? i : acc), -1)
+    if (exitIndex > lastDataIndex && /COARSE_OK/.test(s.state.text)) pass('B18 帧合并后帧序不变量（exit 在最后一帧 data 之后，输出完整）')
+    else fail('B18 帧合并后帧序不变量（exit 在最后一帧 data 之后，输出完整）', `exitIndex=${exitIndex} lastDataIndex=${lastDataIndex}`)
+    s.client.close()
+  }
+
+  // B19: known_hosts 解析器（非 hashed / [host]:port / 通配跳过 / @marker 跳过 / hashed 候选还原）
+  console.log('\n[18] known_hosts 解析器')
+  {
+    const { createHash, createHmac, randomBytes } = await import('node:crypto')
+    const blob1 = Buffer.from('web1-host-key-bytes', 'utf8').toString('base64')
+    const blob2 = Buffer.from('db1-host-key-bytes', 'utf8').toString('base64')
+    const blob3 = Buffer.from('hashed-host-key-bytes', 'utf8').toString('base64')
+    const salt = randomBytes(20)
+    const hmac = createHmac('sha1', salt).update('web1.example.com').digest('base64')
+    const sample = [
+      '# comment',
+      '@cert-authority *.example.com ssh-ed25519 ' + blob1,
+      'web1.example.com,alias ssh-ed25519 ' + blob1,
+      '[db1.internal]:2222 ssh-rsa ' + blob2,
+      '*.wildcard ssh-ed25519 ' + blob1,
+      '|1|' + salt.toString('base64') + '|' + hmac + ' ssh-ed25519 ' + blob3,
+    ].join('\n')
+    const entries = parseKnownHosts(sample, ['web1.example.com'])
+    const fp1 = createHash('sha256').update(Buffer.from('web1-host-key-bytes')).digest('hex')
+    const fp2 = createHash('sha256').update(Buffer.from('db1-host-key-bytes')).digest('hex')
+    const web1 = entries.find((e) => e.host === 'web1.example.com')
+    const alias = entries.find((e) => e.host === 'alias')
+    const db1 = entries.find((e) => e.host === 'db1.internal')
+    const hashedReplayed = entries.filter((e) => e.host === 'web1.example.com').length
+    // 0.19.0 起解析结果按 host:port 聚合、指纹进 fingerprints 集合（一机多把钥匙）
+    // 0.19.0 起解析结果按 host:port 聚合、指纹进 fingerprints 集合（一机多把钥匙）：
+    // hashed 条目还原出的 web1 指纹并入 web1 记录（不再「只留首条」被丢弃）
+    const fp3 = createHash('sha256').update(Buffer.from('hashed-host-key-bytes')).digest('hex')
+    const ok = entries.length === 3
+      && web1 !== undefined && web1.port === 22 && Array.isArray(web1.fingerprints) && web1.fingerprints.length === 2 && web1.fingerprints[0] === fp1 && web1.fingerprints[1] === fp3
+      && alias !== undefined && alias.port === 22 && Array.isArray(alias.fingerprints) && alias.fingerprints.length === 1 && alias.fingerprints[0] === fp1
+      && db1 !== undefined && db1.port === 2222 && Array.isArray(db1.fingerprints) && db1.fingerprints.length === 1 && db1.fingerprints[0] === fp2
+      && hashedReplayed === 1
+    if (ok) pass('B19 known_hosts 解析（别名拆分/[host]:port/@marker与通配跳过/hashed 候选还原+去重）')
+    else fail('B19 known_hosts 解析（别名拆分/[host]:port/@marker与通配跳过/hashed 候选还原+去重）', JSON.stringify(entries))
+  }
+
+  // B20: 端口转发隧道（内存 SSH 服务桥接 + 双隧道 + 本地转发往返）
+  console.log('\n[19] 端口转发隧道')
+  {
+    const ssh2mod = await import('ssh2')
+    const ssh2 = ssh2mod.default ?? ssh2mod
+    const netMod = await import('node:net')
+    const net = netMod.default ?? netMod
+    const { generateKeyPairSync } = await import('node:crypto')
+    const mkEcho = () => new Promise((resolve) => {
+      const server = net.createServer((socket) => socket.on('data', (d) => socket.write(d)))
+      server.listen(0, '127.0.0.1', () => resolve({ server, port: server.address().port }))
+    })
+    const targetA = await mkEcho() // local 方向的「远程服务」
+    const targetB = await mkEcho() // remote 方向的「本地服务」
+    const freePort = () => new Promise((resolve, reject) => {
+      const probe = net.createServer()
+      probe.on('error', reject)
+      probe.listen(0, '127.0.0.1', () => {
+        const p = probe.address().port
+        probe.close(() => resolve(p))
+      })
+    })
+    const tunnelLocalPort = await freePort()
+    const remoteBindPort = await freePort()
+    const { privateKey } = generateKeyPairSync('rsa', {
+      modulusLength: 2048,
+      publicKeyEncoding: { type: 'spki', format: 'pem' },
+      privateKeyEncoding: { type: 'pkcs1', format: 'pem' },
+    })
+    const sshServer = new ssh2.Server({ hostKeys: [privateKey] }, (client) => {
+      client.on('authentication', (ctx) => {
+        if (ctx.method === 'password' && ctx.username === 'test' && ctx.password === 'secret') ctx.accept()
+        else ctx.reject()
+      })
+      client.on('request', (accept, reject, name) => {
+        if (name === 'tcpip-forward' || name === 'cancel-tcpip-forward') accept()
+        else reject()
+      })
+      client.on('tcpip', (accept, reject, info) => {
+        const stream = accept()
+        const upstream = net.connect(info.destPort, info.destIP, () => {
+          stream.pipe(upstream)
+          upstream.pipe(stream)
+        })
+        upstream.on('error', () => stream.end())
+        stream.on('error', () => upstream.end())
+      })
+      client.on('error', () => {})
+    })
+    await new Promise((resolve, reject) => {
+      sshServer.once('error', reject)
+      sshServer.listen(0, '127.0.0.1', () => {
+        sshServer.removeListener('error', reject)
+        resolve()
+      })
+    })
+    const sshPort = sshServer.address().port
+    const post = async (body) => {
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+      return res.json()
+    }
+    const put = await post({
+      sshHosts: [{ name: 'it-ssh', host: '127.0.0.1', port: sshPort, username: 'test', auth: 'password', password: 'secret', keyPath: '', passphrase: '', agentForward: false }],
+      tunnels: [
+        { name: 't-local', bookName: 'it-ssh', direction: 'local', localPort: tunnelLocalPort, remoteHost: '127.0.0.1', remotePort: targetA.port, enabled: true },
+        { name: 't-remote', bookName: 'it-ssh', direction: 'remote', remotePort: remoteBindPort, localTargetPort: targetB.port, enabled: true },
+      ],
+    })
+    if (put.ok === true && Array.isArray(put.config?.tunnels) && put.config.tunnels.length === 2) pass('B20a tunnels 配置热生效（POST → reconcile）')
+    else fail('B20a tunnels 配置热生效（POST → reconcile）', JSON.stringify(put).slice(0, 160))
+    let statuses = []
+    for (let i = 0; i < 30; i++) {
+      await sleep(400)
+      const r = await (await fetch(`http://127.0.0.1:${port}/api/dsh-tty/tunnels`)).json()
+      statuses = r.tunnels ?? []
+      if (statuses.length === 2 && statuses.every((t) => t.state === 'active')) break
+    }
+    if (statuses.length === 2 && statuses.every((t) => t.state === 'active')) pass('B20b 双隧道到达 active（forwardOut + forwardIn）')
+    else fail('B20b 双隧道到达 active（forwardOut + forwardIn）', JSON.stringify(statuses))
+    const roundtrip = await new Promise((resolve) => {
+      const socket = net.connect(tunnelLocalPort, '127.0.0.1', () => socket.write('PING_B20'))
+      let buf = ''
+      socket.on('data', (d) => {
+        buf += d.toString()
+        if (buf.includes('PING_B20')) {
+          socket.end()
+          resolve(buf)
+        }
+      })
+      socket.on('error', (e) => resolve('ERR:' + e.message))
+      setTimeout(() => resolve('TIMEOUT:' + buf), 6000)
+    })
+    if (typeof roundtrip === 'string' && roundtrip.includes('PING_B20')) pass('B20c 本地转发往返（TCP → forwardOut → 服务端桥 → echo 目标）')
+    else fail('B20c 本地转发往返（TCP → forwardOut → 服务端桥 → echo 目标）', String(roundtrip).slice(0, 120))
+    const tunnelList = toolDefs.find((d) => d.name === 'tunnel_list')
+    if (tunnelList === undefined) {
+      fail('B20d tunnel_list 注册', '未找到 tunnel_list')
+    } else {
+      const listed = await tunnelList.execute({})
+      const names = (listed.tunnels ?? []).map((t) => `${t.name}:${t.state}`).join(',')
+      if (Array.isArray(listed.tunnels) && listed.tunnels.some((t) => t.name === 't-local' && t.state === 'active')) pass('B20d tunnel_list 工具可见隧道状态（' + names + '）')
+      else fail('B20d tunnel_list 工具可见隧道状态', names)
+    }
+    await post({ tunnels: [] })
+    await sleep(400)
+    const after = await (await fetch(`http://127.0.0.1:${port}/api/dsh-tty/tunnels`)).json()
+    if ((after.tunnels ?? []).length === 0) pass('B20e tunnels 清空即停止（reconcile 移除）')
+    else fail('B20e tunnels 清空即停止（reconcile 移除）', JSON.stringify(after.tunnels))
+    targetA.server.close()
+    targetB.server.close()
+    await new Promise((resolve) => {
+      const timer = setTimeout(resolve, 1000).unref()
+      sshServer.close(() => {
+        clearTimeout(timer)
+        resolve()
+      })
+    })
+    sshServer.closeAllConnections?.()
+  }
+
+  // B21: /api/dsh-tty/shells 候选列表（设置卡片「Shell 路径」数据源）
+  console.log('\n[19] shells 候选路由')
+  {
+    const { existsSync } = await import('node:fs')
+    const data = await (await fetch(`http://127.0.0.1:${port}/api/dsh-tty/shells`)).json()
+    const shells = Array.isArray(data.shells) ? data.shells : []
+    const allAbsolute = shells.every((p) => typeof p === 'string' && p.startsWith('/'))
+    const hasCurrent = typeof process.env.SHELL !== 'string' || process.env.SHELL.trim() === '' || shells.includes(process.env.SHELL)
+    const hasBash = !existsSync('/bin/bash') || shells.includes('/bin/bash')
+    if (data.ok === true && shells.length > 0 && allAbsolute && hasCurrent && hasBash) pass('B21 shells 候选路由（/etc/shells + $SHELL 去重、存在且可执行、$SHELL 优先）')
+    else fail('B21 shells 候选路由（/etc/shells + $SHELL 去重、存在且可执行、$SHELL 优先）', JSON.stringify(data).slice(0, 200))
+  }
+
+  // B22: bash 3.2（macOS 自带，无 PS0）shell 集成 —— DEBUG trap 兜底 B 标记
+  // 注意：本用例把 config.shell 热切成 /bin/bash（内存 settings stub 不持久），
+  // 必须放在所有依赖默认 shell 的用例之后。
+  console.log('\n[20] bash 3.2 shell 集成（DEBUG trap 兜底）')
+  {
+    const { existsSync } = await import('node:fs')
+    if (!existsSync('/bin/bash')) {
+      console.log('  ⊘ SKIP  B22（本机无 /bin/bash）')
+    } else {
+      await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ shell: '/bin/bash' }),
+      })
+      const s = openSession(port)
+      await s.open()
+      s.client.send(JSON.stringify({ t: 'spawn', sid: 'b32-1' }))
+      await s.waitFor(() => s.state.ready, 10000, 'b32-1 ready')
+      const capture = toolDefs.find((d) => d.name === 'tty_capture')
+      const expect = toolDefs.find((d) => d.name === 'tty_expect')
+      if (capture === undefined || expect === undefined) {
+        fail('B22 工具注册', '缺工具: ' + toolDefs.map((d) => d.name).join(','))
+      } else {
+        // a) DEBUG trap 补出 B 标记 → capture{last:true} 可用
+        s.client.send(JSON.stringify({ t: 'input', sid: 'b32-1', d: 'printf "B32_%s\\n" OK\n' }))
+        await s.waitFor(() => /B32_OK/.test(s.state.text), 10000, 'B32_OK 输出')
+        await sleep(600) // 等 D 标记（PROMPT_COMMAND 在下一 prompt 前发出）
+        let last = null
+        for (let i = 0; i < 12; i++) {
+          await sleep(250)
+          try {
+            last = await capture.execute({ sid: 'b32-1', last: true })
+          } catch (error) {
+            last = { error: error.message }
+          }
+          if (last !== null && last.source === 'last') break
+        }
+        if (last !== null && last.source === 'last' && String(last.tail).includes('B32_OK') && last.exitCode === 0) pass('B22a bash 3.2 tty_capture{last:true} 拿到命令输出 + exitCode=0（DEBUG trap 补 B 标记）')
+        else fail('B22a bash 3.2 tty_capture{last:true} 拿到命令输出 + exitCode=0（DEBUG trap 补 B 标记）', JSON.stringify(last).slice(0, 160))
+        // b) 命令在飞时注册 expect → 命令结束（D 标记）早停并带退出码
+        await sleep(600) // 等 B22a 的 prompt 落定，避免吃到上一条的 D
+        const startedAt = Date.now()
+        s.client.send(JSON.stringify({ t: 'input', sid: 'b32-1', d: 'sleep 2\n' }))
+        await sleep(500) // B 标记已到（inCommand=true）后再注册
+        const early = await expect.execute({ sid: 'b32-1', pattern: 'NEVER_APPEARS_B32', timeoutSec: 20 })
+        const elapsed = Date.now() - startedAt
+        if (early.matched === false && early.timedOut === false && early.exitCode === 0 && elapsed < 10000) pass(`B22b bash 3.2 tty_expect 命令结束早停（exitCode=0，${elapsed}ms << 20s 超时）`)
+        else fail('B22b bash 3.2 tty_expect 命令结束早停（exitCode=0）', JSON.stringify(early).slice(0, 160) + ` elapsed=${elapsed}ms`)
+      }
+      s.client.send(JSON.stringify({ t: 'kill', sid: 'b32-1' }))
+      await s.waitFor(() => s.state.exited !== null, 10000, 'b32-1 exit')
+      s.client.close()
+    }
+  }
+
+  // B23: SFTP 文件传输（0.7.0）—— /api/dsh-tty/sftp/* 路由 + sftp_* agent 工具
+  // 数据源是 scripts/lib/test-sshd.mjs 的内存 sshd（sftp subsystem 映射临时目录）。
+  console.log('\n[21] SFTP 文件传输（HTTP 路由 + agent 工具）')
+  {
+    const rootDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'dsh-tty-b23-'))
+    const sftpd = await startSftpSshd({ rootDir })
+    const post = async (body) => {
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+      return res.json()
+    }
+    const put = await post({ sshHosts: [{ name: 'b23-ssh', host: '127.0.0.1', port: sftpd.port, username: TEST_USER, auth: 'password', password: TEST_PASSWORD, keyPath: '', passphrase: '', agentForward: false }] })
+    if (put.ok === true) pass('B23a 连接簿写入（POST config sshHosts → SFTP 走连接簿凭证）')
+    else fail('B23a 连接簿写入（POST config sshHosts → SFTP 走连接簿凭证）', JSON.stringify(put).slice(0, 160))
+    await fsp.writeFile(path.join(rootDir, 'seed.txt'), 'SEED_CONTENT_B23')
+
+    const sftpApi = async (action, payload) => {
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/sftp/${action}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name: 'b23-ssh', ...payload }),
+      })
+      const data = await res.json().catch(() => ({}))
+      return { status: res.status, data }
+    }
+
+    // b) list：path 缺省 → realpath home（rootDir）+ 预置文件可见
+    const listed = await sftpApi('list', { path: '' })
+    const seed = (listed.data.entries ?? []).find((e) => e.name === 'seed.txt')
+    if (listed.data.ok === true && listed.data.path === rootDir && seed?.isFile === true && seed?.size === 16) {
+      pass('B23b list 路由（path 缺省 realpath 到 rootDir，seed.txt 文件属性正确）')
+    } else {
+      fail('B23b list 路由（path 缺省 realpath 到 rootDir，seed.txt 文件属性正确）', JSON.stringify(listed).slice(0, 200))
+    }
+
+    // c) mkdir + upload（原始字节 body，x-dsh-sftp-meta 头带 spec+path）
+    const mk = await sftpApi('mkdir', { path: rootDir + '/b23dir' })
+    const payload = Buffer.alloc(4096, 0x62)
+    const up = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/sftp/upload`, {
+      method: 'POST',
+      headers: { 'x-dsh-sftp-meta': Buffer.from(JSON.stringify({ name: 'b23-ssh', path: rootDir + '/b23dir/up.bin' })).toString('base64url') },
+      body: payload,
+    })
+    const upData = await up.json().catch(() => ({}))
+    let stored = null
+    try {
+      stored = await fsp.readFile(path.join(rootDir, 'b23dir', 'up.bin'))
+    } catch {
+      stored = null
+    }
+    if (mk.data.ok === true && up.status === 200 && upData.ok === true && upData.bytes === 4096 && stored !== null && stored.equals(payload)) {
+      pass('B23c mkdir + upload 路由（4096 字节流式落盘逐一一致）')
+    } else {
+      fail('B23c mkdir + upload 路由（4096 字节流式落盘逐一一致）', `mk=${JSON.stringify(mk.data).slice(0, 80)} up=${up.status}/${JSON.stringify(upData).slice(0, 80)} stored=${stored === null ? '缺失' : String(stored.length) + 'B'}`)
+    }
+
+    // d) download：流式响应 + content-disposition + 字节一致
+    const dl = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/sftp/download`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'b23-ssh', path: rootDir + '/b23dir/up.bin' }),
+    })
+    const dlBuf = Buffer.from(await dl.arrayBuffer())
+    const disposition = dl.headers.get('content-disposition') ?? ''
+    if (dl.status === 200 && dlBuf.equals(payload) && disposition.includes('up.bin')) {
+      pass('B23d download 路由（octet-stream + content-disposition + 字节一致）')
+    } else {
+      fail('B23d download 路由（octet-stream + content-disposition + 字节一致）', `status=${String(dl.status)} bytes=${String(dlBuf.length)} disposition=${JSON.stringify(disposition)}`)
+    }
+
+    // e) agent 工具：schema 校验 + sftp_list / sftp_write（追加）/ sftp_read
+    const sftpList = toolDefs.find((d) => d.name === 'sftp_list')
+    const sftpRead = toolDefs.find((d) => d.name === 'sftp_read')
+    const sftpWrite = toolDefs.find((d) => d.name === 'sftp_write')
+    if (sftpList === undefined || sftpRead === undefined || sftpWrite === undefined) {
+      fail('B23e sftp_* agent 工具（schema + list/read/write）', '缺工具: ' + toolDefs.map((d) => d.name).filter((n) => n.startsWith('sftp')).join(',') || '无')
+    } else {
+      let schemaOk = true
+      for (const d of [sftpList, sftpRead, sftpWrite]) {
+        try {
+          assertSupportedJsonSchema(d.parameters)
+          assertSupportedJsonSchema(d.output?.schema ?? {})
+        } catch (e) {
+          schemaOk = false
+          fail('B23e sftp_* agent 工具（schema + list/read/write）', d.name + ' schema: ' + String(e && e.message ? e.message : e))
+        }
+      }
+      const toolListed = schemaOk ? await sftpList.execute({ book: 'b23-ssh', path: rootDir + '/b23dir' }) : null
+      const saw = toolListed !== null && (toolListed.entries ?? []).some((e) => e.name === 'up.bin' && e.isDir === false && e.size === 4096)
+      let noteOk = false
+      let readBack = null
+      try {
+        await sftpWrite.execute({ book: 'b23-ssh', path: rootDir + '/b23dir/note.txt', content: 'hello-b23', append: true })
+        await sftpWrite.execute({ book: 'b23-ssh', path: rootDir + '/b23dir/note.txt', content: '-again', append: true })
+        readBack = await sftpRead.execute({ book: 'b23-ssh', path: rootDir + '/b23dir/note.txt' })
+        noteOk = readBack.content === 'hello-b23-again' && readBack.truncated === false
+      } catch (error) {
+        readBack = { error: error.message }
+      }
+      if (schemaOk && saw === true && noteOk) pass('B23e sftp_* agent 工具（schema 通过 + list 可见上传文件 + write 追加后 read 一致）')
+      else fail('B23e sftp_* agent 工具（schema 通过 + list 可见上传文件 + write 追加后 read 一致）', `saw=${String(saw)} note=${JSON.stringify(readBack).slice(0, 120)}`)
+    }
+
+    // f) remove 递归 + 连接簿清空
+    const rm = await sftpApi('remove', { path: rootDir + '/b23dir', recursive: true })
+    const gone = await fsp.access(path.join(rootDir, 'b23dir')).then(() => false, () => true)
+    if (rm.data.ok === true && gone) pass('B23f remove 路由（目录递归删除）')
+    else fail('B23f remove 路由（目录递归删除）', `status=${String(rm.status)} data=${JSON.stringify(rm.data).slice(0, 120)} gone=${String(gone)}`)
+    await post({ sshHosts: [] })
+    await sftpd.close()
+    await fsp.rm(rootDir, { recursive: true, force: true })
+    console.log('    sftp sshd 已关闭，临时目录已清理')
+  }
+
+  // B24: SFTP 管理闭环（0.8.0）—— agent sftp_mkdir/sftp_rename/sftp_remove/
+  // sftp_tree（test-sshd 内存 sshd，覆盖 parents 逐级补齐、tree 限深截断、
+  // 跨目录 rename = mv、非空目录非递归删除拒绝、递归删除与不存在路径报错）。
+  console.log('\n[22] SFTP 管理闭环（agent sftp_mkdir/rename/remove/tree）')
+  {
+    const rootDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'dsh-tty-b24-'))
+    const sftpd = await startSftpSshd({ rootDir })
+    const post = async (body) => {
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+      return res.json()
+    }
+    const put = await post({ sshHosts: [{ name: 'b24-ssh', host: '127.0.0.1', port: sftpd.port, username: TEST_USER, auth: 'password', password: TEST_PASSWORD, keyPath: '', passphrase: '', agentForward: false }] })
+    if (put.ok === true) pass('B24a 连接簿写入（b24-ssh）')
+    else fail('B24a 连接簿写入（b24-ssh）', JSON.stringify(put).slice(0, 160))
+
+    const sftpMkdir = toolDefs.find((d) => d.name === 'sftp_mkdir')
+    const sftpRename = toolDefs.find((d) => d.name === 'sftp_rename')
+    const sftpRemove = toolDefs.find((d) => d.name === 'sftp_remove')
+    const sftpTree = toolDefs.find((d) => d.name === 'sftp_tree')
+    const sftpWrite = toolDefs.find((d) => d.name === 'sftp_write')
+    const sftpRead = toolDefs.find((d) => d.name === 'sftp_read')
+    if (sftpMkdir === undefined || sftpRename === undefined || sftpRemove === undefined || sftpTree === undefined || sftpWrite === undefined || sftpRead === undefined) {
+      fail('B24 工具注册', '缺工具: ' + toolDefs.map((d) => d.name).filter((n) => n.startsWith('sftp')).join(',') || '无')
+    } else {
+      let schemaOk = true
+      for (const d of [sftpMkdir, sftpRename, sftpRemove, sftpTree]) {
+        try {
+          assertSupportedJsonSchema(d.parameters)
+          assertSupportedJsonSchema(d.output?.schema ?? {})
+        } catch (e) {
+          schemaOk = false
+          fail('B24 工具注册（schema 校验）', d.name + ' schema: ' + String(e && e.message ? e.message : e))
+        }
+      }
+      if (schemaOk) pass('B24a sftp_mkdir/rename/remove/tree schema 校验')
+
+      // b) mkdir parents 逐级补齐（等效 mkdir -p）
+      const libDir = rootDir + '/b24/proj/src/lib'
+      await sftpMkdir.execute({ book: 'b24-ssh', path: libDir, parents: true })
+      const libStat = await fsp.stat(libDir).then((s) => s.isDirectory(), () => false)
+      let noParentsRejected = false
+      try {
+        await sftpMkdir.execute({ book: 'b24-ssh', path: rootDir + '/b24/no/such/dir' })
+      } catch {
+        noParentsRejected = true
+      }
+      if (libStat && noParentsRejected) pass('B24b sftp_mkdir（parents 逐级补齐 + 缺父目录被拒）')
+      else fail('B24b sftp_mkdir（parents 逐级补齐 + 缺父目录被拒）', `libDir=${String(libStat)} noParentsRejected=${String(noParentsRejected)}`)
+
+      // seed 一个文件（sftp_write），供 tree / rename / 移动断言
+      await sftpWrite.execute({ book: 'b24-ssh', path: libDir + '/util.ts', content: 'export const b24 = 1\n' })
+
+      // c) tree：深度优先目录优先 + maxDepth 限深截断
+      const treeShallow = await sftpTree.execute({ book: 'b24-ssh', path: rootDir + '/b24', maxDepth: 1 })
+      const shallowOk = treeShallow.entries.length === 1 && treeShallow.entries[0].path === rootDir + '/b24/proj' && treeShallow.entries[0].depth === 1 && treeShallow.entries[0].isDir === true && treeShallow.truncated === true
+      const treeFull = await sftpTree.execute({ book: 'b24-ssh', path: rootDir + '/b24', maxDepth: 4 })
+      const names = treeFull.entries.map((e) => e.path)
+      const fullOk = names.join('|') === [rootDir + '/b24/proj', rootDir + '/b24/proj/src', rootDir + '/b24/proj/src/lib', rootDir + '/b24/proj/src/lib/util.ts'].join('|')
+        && treeFull.truncated === false
+        && treeFull.entries[3].size === 'export const b24 = 1\n'.length
+      if (shallowOk && fullOk) pass('B24c sftp_tree（深度优先目录优先 + maxDepth 截断标记）')
+      else fail('B24c sftp_tree（深度优先目录优先 + maxDepth 截断标记）', `shallow=${JSON.stringify(treeShallow).slice(0, 160)} full=${names.join('|')} truncated=${String(treeFull.truncated)}`)
+
+      // d) rename 文件 + 内容不变
+      await sftpRename.execute({ book: 'b24-ssh', from: libDir + '/util.ts', to: libDir + '/helper.ts' })
+      const renamed = await fsp.access(libDir + '/util.ts').then(() => false, () => true)
+      const readBack = await sftpRead.execute({ book: 'b24-ssh', path: libDir + '/helper.ts' })
+      if (renamed && readBack.content === 'export const b24 = 1\n') pass('B24d sftp_rename（文件重命名 + 内容不变）')
+      else fail('B24d sftp_rename（文件重命名 + 内容不变）', `renamed=${String(renamed)} content=${JSON.stringify(readBack.content ?? readBack).slice(0, 80)}`)
+
+      // e) rename 跨目录 = 移动
+      await sftpMkdir.execute({ book: 'b24-ssh', path: rootDir + '/b24/dest' })
+      await sftpRename.execute({ book: 'b24-ssh', from: libDir + '/helper.ts', to: rootDir + '/b24/dest/helper.ts' })
+      const movedAway = await fsp.access(libDir + '/helper.ts').then(() => false, () => true)
+      const movedContent = await fsp.readFile(rootDir + '/b24/dest/helper.ts', 'utf8').catch(() => null)
+      if (movedAway && movedContent === 'export const b24 = 1\n') pass('B24e sftp_rename（跨目录移动 = mv）')
+      else fail('B24e sftp_rename（跨目录移动 = mv）', `movedAway=${String(movedAway)} content=${JSON.stringify(movedContent).slice(0, 80)}`)
+
+      // f) remove：非空目录不带 recursive 被拒；recursive 整树删除；已删路径再操作报错
+      let nonEmptyRejected = false
+      try {
+        await sftpRemove.execute({ book: 'b24-ssh', path: rootDir + '/b24/proj' })
+      } catch {
+        nonEmptyRejected = true
+      }
+      await sftpRemove.execute({ book: 'b24-ssh', path: rootDir + '/b24', recursive: true })
+      const treeGone = await fsp.access(rootDir + '/b24').then(() => false, () => true)
+      let missingRejected = false
+      try {
+        await sftpTree.execute({ book: 'b24-ssh', path: rootDir + '/b24' })
+      } catch {
+        missingRejected = true
+      }
+      if (nonEmptyRejected && treeGone && missingRejected) pass('B24f sftp_remove（非空目录需 recursive + 递归删除 + 复查报错）')
+      else fail('B24f sftp_remove（非空目录需 recursive + 递归删除 + 复查报错）', `nonEmptyRejected=${String(nonEmptyRejected)} treeGone=${String(treeGone)} missingRejected=${String(missingRejected)}`)
+    }
+
+    await post({ sshHosts: [] })
+    await sftpd.close()
+    await fsp.rm(rootDir, { recursive: true, force: true })
+    console.log('    sftp sshd 已关闭，临时目录已清理')
+  }
+
+  // B25/B26: 会话持久化（tmux，0.10.0）—— persistence 门控 / tmux 托管 /
+  // kill-session 收尾 / shell 集成 DCS passthrough / 保活回收不杀 tmux 会话 /
+  // 同 persistName 接回现场。本机无 tmux 时只验证降级提示路径。
+  console.log('\n[23] 会话持久化（tmux）')
+  {
+    const execFileP = (file, args) => new Promise((resolve) => {
+      import('node:child_process').then(({ execFile }) => {
+        execFile(file, args, { timeout: 5000 }, (error, stdout, stderr) => resolve({ error, stdout: String(stdout), stderr: String(stderr) }))
+      })
+    })
+    const tmuxList = async () => {
+      const out = await execFileP('tmux', ['-L', 'dsh-tty', 'list-sessions', '-F', '#{session_name}'])
+      return out.error !== null && out.error !== undefined ? [] : out.stdout.trim().split('\n').filter(Boolean)
+    }
+    const post = async (body) => {
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+      return res.json()
+    }
+    const probe = await execFileP('tmux', ['-V'])
+    const hasTmux = probe.error === null || probe.error === undefined
+    const versionMatch = /tmux\s+(\d+)\.(\d+)/.exec(probe.stdout)
+    const hasPassthrough = hasTmux && versionMatch !== null && (Number(versionMatch[1]) > 3 || (Number(versionMatch[1]) === 3 && Number(versionMatch[2]) >= 3))
+
+    // B25a: persistence=off 时 persist 帧被门控 —— 普通会话、ready 无 persist、无 tmux 会话
+    await post({ persistence: 'off' })
+    {
+      const s = openSession(port)
+      await s.open()
+      s.client.send(JSON.stringify({ t: 'spawn', sid: 'b25off', persist: true, persistName: 'b25gate' }))
+      await s.waitFor(() => s.state.ready, 10000, 'ready')
+      const ready = s.state.frames.find((f) => f.t === 'ready' && f.sid === 'b25off')
+      const listed = hasTmux ? await tmuxList() : []
+      if (ready !== undefined && ready.persist !== true && !listed.includes('dsh-b25gate')) pass('B25a persistence=off 门控 persist 帧（普通会话）')
+      else fail('B25a persistence=off 门控 persist 帧（普通会话）', `persist=${String(ready?.persist)} listed=${JSON.stringify(listed)}`)
+      s.client.send(JSON.stringify({ t: 'kill', sid: 'b25off' }))
+      await s.waitFor(() => s.state.exited !== null, 10000, 'exit')
+      s.client.close()
+    }
+
+    if (!hasTmux) {
+      // 降级路径：persistence=tmux + persist 帧 + 无 tmux → 普通会话 + 灰字提示
+      await post({ persistence: 'tmux' })
+      const s = openSession(port)
+      await s.open()
+      s.client.send(JSON.stringify({ t: 'spawn', sid: 'b25fb', persist: true, persistName: 'b25fb' }))
+      await s.waitFor(() => s.state.ready, 10000, 'ready')
+      await s.waitFor(() => /未检测到 tmux/.test(s.state.text), 10000, '降级提示')
+      const ready = s.state.frames.find((f) => f.t === 'ready' && f.sid === 'b25fb')
+      if (ready !== undefined && ready.persist !== true) pass('B25b 无 tmux 降级为普通会话 + 灰字提示')
+      else fail('B25b 无 tmux 降级为普通会话 + 灰字提示', `persist=${String(ready?.persist)}`)
+      s.client.send(JSON.stringify({ t: 'kill', sid: 'b25fb' }))
+      await s.waitFor(() => s.state.exited !== null, 10000, 'exit')
+      s.client.close()
+      await post({ persistence: 'off' })
+      console.log('    本机无 tmux：B25c/B26 跳过')
+    } else {
+      await post({ persistence: 'tmux' })
+      const s = openSession(port)
+      await s.open()
+      s.client.send(JSON.stringify({ t: 'spawn', sid: 'b25tmux', cols: 80, rows: 24, persist: true, persistName: 'b25persist' }))
+      await s.waitFor(() => s.state.ready, 10000, 'ready')
+      const ready = s.state.frames.find((f) => f.t === 'ready' && f.sid === 'b25tmux')
+      // ready 只代表 channel 打开；tmux server 是 fork 出来的，会话出现要晚一点。
+      // 本地（快）一次就中，CI runner 上会输给这个竞态——轮询到出现为止（最多 ~6s）。
+      let listed = await tmuxList()
+      for (let i = 0; i < 20 && !listed.includes('dsh-b25persist'); i++) {
+        await sleep(300)
+        listed = await tmuxList()
+      }
+      if (ready !== undefined && ready.persist === true && listed.includes('dsh-b25persist')) pass('B25b persistence=tmux 持久 spawn（tmux 会话托管 + ready.persist）')
+      else fail('B25b persistence=tmux 持久 spawn（tmux 会话托管 + ready.persist）', `persist=${String(ready?.persist)} listed=${JSON.stringify(listed)}`)
+
+      // shell 集成经 DCS passthrough 送达宿主：capture{last} 拿到命令输出与退出码
+      if (hasPassthrough) {
+        s.client.send(JSON.stringify({ t: 'input', sid: 'b25tmux', d: 'printf "B25LAST-%s\\n" 42\n' }))
+        await s.waitFor(() => /B25LAST-42/.test(s.state.text), 10000, '命令输出')
+        await sleep(600) // 等 D 标记（precmd）到达
+        const ttyCapture = toolDefs.find((d) => d.name === 'tty_capture')
+        const last = await ttyCapture.execute({ sid: 'b25tmux', last: true })
+        if (last.source === 'last' && /B25LAST-42/.test(last.tail ?? '') && last.exitCode === 0) pass('B25c tmux passthrough shell 集成（capture{last} + 退出码）')
+        else fail('B25c tmux passthrough shell 集成（capture{last} + 退出码）', JSON.stringify({ source: last.source, exitCode: last.exitCode, tail: (last.tail ?? '').slice(-80) }))
+      } else {
+        console.log('    tmux <3.3（无 allow-passthrough）：B25c 跳过')
+      }
+
+      // B25d: kill 帧 → tmux 会话真正结束（kill-session 而非 detach）
+      s.client.send(JSON.stringify({ t: 'kill', sid: 'b25tmux' }))
+      await s.waitFor(() => s.state.exited !== null, 10000, 'exit')
+      await sleep(500)
+      const listedAfterKill = await tmuxList()
+      if (!listedAfterKill.includes('dsh-b25persist')) pass('B25d kill 帧收尾 tmux 会话（kill-session）')
+      else fail('B25d kill 帧收尾 tmux 会话（kill-session）', JSON.stringify(listedAfterKill))
+
+      // B26: 恢复现场 —— 保活回收只杀 PTY（tmux 会话存活）；同 persistName 接回
+      await post({ reconnectGraceSec: 1 })
+      const w1 = openSession(port)
+      await w1.open()
+      w1.client.send(JSON.stringify({ t: 'spawn', sid: 'b26a', cols: 80, rows: 24, persist: true, persistName: 'b26resume' }))
+      await w1.waitFor(() => w1.state.ready, 10000, 'b26a ready')
+      w1.client.send(JSON.stringify({ t: 'input', sid: 'b26a', d: 'printf "B26MARK-%s\\n" resume\n' }))
+      await w1.waitFor(() => /B26MARK-resume/.test(w1.state.text), 10000, '标记输出')
+      // 异常断开 → 孤儿 → 保活 1s + 回收器扫描（≤10s）只杀 PTY；tmux 会话应存活
+      w1.client.close()
+      await sleep(12500)
+      const listedAfterReap = await tmuxList()
+      if (listedAfterReap.includes('dsh-b26resume')) pass('B26a 保活回收只杀 PTY（tmux 会话存活可恢复）')
+      else fail('B26a 保活回收只杀 PTY（tmux 会话存活可恢复）', JSON.stringify(listedAfterReap))
+      // sessions 帧带 tmux 会话名清单（新窗口恢复持久标签的存活确认数据源）
+      const wq = openSession(port)
+      await wq.open()
+      wq.client.send(JSON.stringify({ t: 'sessions' }))
+      await wq.waitFor(() => wq.state.frames.some((f) => f.t === 'sessions'), 5000, 'sessions 帧')
+      const sframe = wq.state.frames.find((f) => f.t === 'sessions')
+      if (sframe !== undefined && Array.isArray(sframe.tmux) && sframe.tmux.includes('dsh-b26resume')) pass('B26a2 sessions 帧带 tmux 会话名清单')
+      else fail('B26a2 sessions 帧带 tmux 会话名清单', JSON.stringify(sframe?.tmux))
+      wq.client.close()
+      const w2 = openSession(port)
+      await w2.open()
+      w2.client.send(JSON.stringify({ t: 'spawn', sid: 'b26b', cols: 80, rows: 24, persist: true, persistName: 'b26resume' }))
+      await w2.waitFor(() => w2.state.ready, 10000, 'b26b ready')
+      await w2.waitFor(() => /B26MARK-resume/.test(w2.state.text), 10000, '接回重画')
+      pass('B26b 同 persistName 重新 spawn 接回原现场（tmux -A 重画）')
+      w2.client.send(JSON.stringify({ t: 'kill', sid: 'b26b' }))
+      await w2.waitFor(() => w2.state.exited !== null, 10000, 'b26b exit')
+      await sleep(500)
+      const listedFinal = await tmuxList()
+      if (!listedFinal.includes('dsh-b26resume')) pass('B26c 恢复会话 kill 后 tmux 会话清理')
+      else fail('B26c 恢复会话 kill 后 tmux 会话清理', JSON.stringify(listedFinal))
+      w2.client.close()
+
+      // B26d: attach 不回放缓冲 —— 重连后现场由 tmux refresh-client 重画恰好一次
+      //（旧行为：回放缓冲 + tmux 重画 = 内容重影 + 幽灵滚动条）
+      const w3 = openSession(port)
+      await w3.open()
+      w3.client.send(JSON.stringify({ t: 'spawn', sid: 'b26d', cols: 80, rows: 24, persist: true, persistName: 'b26refresh' }))
+      await w3.waitFor(() => w3.state.ready, 10000, 'b26d ready')
+      w3.client.send(JSON.stringify({ t: 'input', sid: 'b26d', d: 'printf "B26REFRESH-%s\\n" ok\n' }))
+      await w3.waitFor(() => /B26REFRESH-ok/.test(w3.state.text), 10000, 'b26d 输出')
+      await sleep(600) // 等 D 标记与重画尘埃落定
+      w3.client.close() // 异常断开 → 孤儿（grace=1s，需在回收前尽快 attach）
+      await sleep(200)
+      const w4 = openSession(port)
+      await w4.open()
+      w4.client.send(JSON.stringify({ t: 'attach', sid: 'b26d' }))
+      await w4.waitFor(() => w4.state.ready, 10000, 'b26d attach ready')
+      await w4.waitFor(() => /B26REFRESH-ok/.test(w4.state.text), 10000, 'refresh-client 重画')
+      const occurrences = (w4.state.text.match(/B26REFRESH-ok/g) ?? []).length
+      if (occurrences === 1) pass('B26d attach 跳过缓冲回放（tmux 重画一次，无重影/幽灵滚动条）')
+      else fail('B26d attach 跳过缓冲回放（tmux 重画一次，无重影/幽灵滚动条）', `marker 出现 ${occurrences} 次`)
+      // refresh 帧：reset 后请宿主 refresh-client 重画（不碰尺寸）
+      w4.client.send(JSON.stringify({ t: 'refresh', sid: 'b26d' }))
+      await sleep(600)
+      const refreshedOk = (w4.state.text.match(/B26REFRESH-ok/g) ?? []).length >= 1 && w4.state.errors.length === 0
+      if (refreshedOk) pass('B26e refresh 帧（refresh-client 重画，无错误）')
+      else fail('B26e refresh 帧（refresh-client 重画，无错误）', `errors=${JSON.stringify(w4.state.errors)}`)
+      w4.client.send(JSON.stringify({ t: 'kill', sid: 'b26d' }))
+      await w4.waitFor(() => w4.state.exited !== null, 10000, 'b26d exit')
+      w4.client.close()
+      await post({ reconnectGraceSec: 120, persistence: 'off' })
+      console.log('    持久化配置已还原（persistence=off，grace=120）')
+    }
+  }
+
+  // B27: 跨窗口共享持久会话（0.10.1）——同 persistName 的第二次 spawn 重绑定
+  // 到现有宿主会话（不新建 PTY、不占名额），输出扇出两侧可见；kill 广播 exit
+  console.log('\n[24] 跨窗口共享持久会话')
+  {
+    const post = async (body) => {
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+      return res.json()
+    }
+    await post({ persistence: 'tmux' })
+    const wA = openSession(port)
+    await wA.open()
+    wA.client.send(JSON.stringify({ t: 'spawn', sid: 'b27a', cols: 80, rows: 24, persist: true, persistName: 'b27share' }))
+    await wA.waitFor(() => wA.state.ready, 10000, 'b27a ready')
+    wA.client.send(JSON.stringify({ t: 'input', sid: 'b27a', d: 'printf "B27MARK-%s\\n" shared\n' }))
+    await wA.waitFor(() => /B27MARK-shared/.test(wA.state.text), 10000, 'b27a 标记输出')
+    const wB = openSession(port)
+    await wB.open()
+    wB.client.send(JSON.stringify({ t: 'spawn', sid: 'b27b', cols: 80, rows: 24, persist: true, persistName: 'b27share' }))
+    await wB.waitFor(() => wB.state.ready, 10000, 'b27b ready（重绑定）')
+    await wB.waitFor(() => /B27MARK-shared/.test(wB.state.text), 10000, 'B 侧可见共享输出')
+    const ttyList = toolDefs.find((d) => d.name === 'tty_list')
+    const listed = await ttyList.execute({})
+    const persistCount = listed.sessions.filter((s) => s.persist === true).length
+    const bothAlive = wA.state.exited === null && wB.state.exited === null
+    if (persistCount === 1 && bothAlive) pass('B27a 同 persistName 二次 spawn 重绑定（不新建 PTY / 不占名额）')
+    else fail('B27a 同 persistName 二次 spawn 重绑定（不新建 PTY / 不占名额）', `persist 会话数=${String(persistCount)}`)
+    // kill A → exit 广播到 B（共享会话随 kill 结束）
+    wA.client.send(JSON.stringify({ t: 'kill', sid: 'b27a' }))
+    await wB.waitFor(() => wB.state.exited !== null, 10000, 'B 侧 exit 广播')
+    if (wB.state.exited !== null) pass('B27b kill 广播 exit 到共享连接')
+    else fail('B27b kill 广播 exit 到共享连接', JSON.stringify(wB.state.exited))
+    wA.client.close()
+    wB.client.close()
+    await post({ persistence: 'off' })
+    console.log('    持久化配置已还原')
+  }
+
+  // B28: SSH 连接测试路由 /api/dsh-tty/probe（0.11.0）
+  // 连接簿行「测试」（bookRecord=true 完整 TOFU）与对话框「试连」（无 store
+  // 只比对）共用；验证：成功分类、host key 记录/匹配、坏密码、端口不通
+  console.log('\n[25] SSH 连接测试路由')
+  {
+    const probe = async (body) => {
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/probe`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      })
+      return res.json()
+    }
+    // 起一个内存 sshd（password test/secret，无 shell——probe 只握手不开 channel）
+    const sftpd = await startSftpSshd({ rootDir: os.tmpdir() })
+    const spec = { host: '127.0.0.1', port: sftpd.port, username: TEST_USER, auth: 'password', password: TEST_PASSWORD }
+    // 试连（bookRecord=false）：成功且不落盘 hostKeys
+    const cfgBefore = await (await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`)).json()
+    const hostsBefore = Array.isArray(cfgBefore.config?.hostKeys) ? cfgBefore.config.hostKeys.length : 0
+    const r1 = await probe({ ...spec, bookRecord: false })
+    if (r1.ok === true && r1.result?.auth?.ok === true && r1.result?.tcp?.ok === true) pass('B28a 试连成功（auth.ok，hostkey=' + String(r1.result?.hostkey?.state) + '）')
+    else fail('B28a 试连成功', JSON.stringify(r1))
+    const cfgAfter1 = await (await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`)).json()
+    const hostsAfter1 = Array.isArray(cfgAfter1.config?.hostKeys) ? cfgAfter1.config.hostKeys.length : 0
+    if (hostsAfter1 === hostsBefore) pass('B28b 试连不落盘 hostKeys（对话框试连语义）')
+    else fail('B28b 试连不落盘 hostKeys（对话框试连语义）', `before=${hostsBefore} after=${hostsAfter1}`)
+
+    // 连接簿测试（bookRecord=true）：新指纹当场 TOFU 记录
+    const r2 = await probe({ ...spec, bookRecord: true })
+    if (r2.ok === true && r2.result?.auth?.ok === true && r2.result?.hostkey?.state === 'recorded') pass('B28c 连接簿测试：新指纹 TOFU 记录（' + String(r2.result?.hostkey?.fingerprint?.slice(0, 12)) + '…）')
+    else fail('B28c 连接簿测试：新指纹 TOFU 记录', JSON.stringify(r2))
+    const cfgAfter2 = await (await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`)).json()
+    const hostsAfter2 = Array.isArray(cfgAfter2.config?.hostKeys) ? cfgAfter2.config.hostKeys : []
+    // 0.19.0：记录形态为 {host, port, fingerprints[]}（旧单 fingerprint 字段兼容读取）
+    const recordedKey = hostsAfter2.some((hk) => hk.host === '127.0.0.1' && Number(hk.port) === sftpd.port && ((Array.isArray(hk.fingerprints) && hk.fingerprints.length > 0) || typeof hk.fingerprint === 'string'))
+    if (recordedKey) pass('B28d 指纹已持久化到 hostKeys（可被后续连接校验）')
+    else fail('B28d 指纹已持久化到 hostKeys', JSON.stringify(hostsAfter2))
+    // 再连同主机 → matched（与记录一致放行）
+    const r3 = await probe({ ...spec, bookRecord: true })
+    if (r3.ok === true && r3.result?.auth?.ok === true && r3.result?.hostkey?.state === 'matched') pass('B28e 二次测试：指纹匹配放行')
+    else fail('B28e 二次测试：指纹匹配放行', JSON.stringify(r3))
+
+    // 坏密码 → 认证被拒（分类文案）
+    const r4 = await probe({ ...spec, password: 'wrong', bookRecord: true })
+    if (r4.ok === false && r4.result?.auth?.ok === false && /认证被拒绝/.test(r4.result?.auth?.error || '')) pass('B28f 坏密码 → 认证被拒绝')
+    else fail('B28f 坏密码 → 认证被拒绝', JSON.stringify(r4))
+
+    // 端口不通 → TCP 拒绝（不进入握手）
+    const dead = net.createServer()
+    await new Promise((resolve) => dead.listen(0, '127.0.0.1', resolve))
+    const deadPort = dead.address().port
+    await new Promise((resolve) => dead.close(resolve))
+    const r5 = await probe({ ...spec, port: deadPort, bookRecord: false })
+    if (r5.ok === false && r5.result?.tcp?.ok === false && r5.result?.auth?.ok === false) pass('B28g 端口不通 → tcp 拒绝')
+    else fail('B28g 端口不通 → tcp 拒绝', JSON.stringify(r5))
+
+    // 字段校验：缺 username / 非法端口 → 友好错误（不触发网络）
+    const r6 = await probe({ host: '127.0.0.1', port: 22, username: '', auth: 'password', password: 'x' })
+    if (r6.ok === false && /用户名|主机/.test(r6.error || '')) pass('B28h 缺字段 → 友好错误')
+    else fail('B28h 缺字段 → 友好错误', JSON.stringify(r6))
+    const r7 = await probe({ host: '127.0.0.1', port: 70000, username: 'u', auth: 'password', password: 'x' })
+    if (r7.ok === false && /端口/.test(r7.error || '')) pass('B28i 非法端口 → 友好错误')
+    else fail('B28i 非法端口 → 友好错误', JSON.stringify(r7))
+
+    await sftpd.close()
+  }
+
+  // B29: 禁用热生效（enabled 开关）：工具/公告撤下、数据路由 403、WS 关闭与拒绝、/config 保持可用
+  console.log('\n[29] 禁用热生效与恢复（enabled 开关）')
+  {
+    const configPost = async (body) => {
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+      return { status: res.status, body: await res.json() }
+    }
+
+    // 存量 WS 先连上（插件仍启用），禁用后应被服务端正常关闭
+    const alive = openSession(port)
+    await alive.open()
+
+    const off = await configPost({ enabled: false })
+    if (off.status === 200 && off.body.config?.enabled === false) pass('B29a POST /config enabled=false 生效')
+    else fail('B29a POST /config enabled=false 生效', `status=${String(off.status)}`)
+    await sleep(100)
+    if (toolDefs.length === 0) pass('B29b 禁用后 agent 工具全部撤下')
+    else fail('B29b 禁用后 agent 工具全部撤下', `残留: ${toolDefs.map((d) => d.name).join(',')}`)
+    if (promptParts.length === 0) pass('B29c 禁用后公告与动态快照撤下')
+    else fail('B29c 禁用后公告与动态快照撤下', `残留 ${String(promptParts.length)}`)
+    const probeRes = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/probe`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ host: '127.0.0.1', username: 'u' }) })
+    if (probeRes.status === 403) pass('B29d 禁用后数据路由 403（/probe）')
+    else fail('B29d 禁用后数据路由 403（/probe）', `status=${String(probeRes.status)}`)
+    const cfgGet = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`)
+    if (cfgGet.status === 200 && (await cfgGet.json()).config?.enabled === false) pass('B29e 禁用后 /config 仍可读（卡片依赖）')
+    else fail('B29e 禁用后 /config 仍可读（卡片依赖）', `status=${String(cfgGet.status)}`)
+
+    // 存量 WS 已在禁用前连上：应被服务端正常关闭（会话转孤儿保活，PTY 进程不动）
+    try {
+      await alive.waitFor(() => alive.state.closed, 5000, '禁用后存量 WS 关闭')
+      pass('B29f 禁用后存量 WS 被服务端关闭')
+    } catch (error) {
+      fail('B29f 禁用后存量 WS 被服务端关闭', String(error?.message ?? error).slice(0, 140))
+    }
+
+    // 新升级被拒（socket 直接 destroy：ws 客户端应快速 error/close 而非建连成功）
+    const rejected = await new Promise((resolve) => {
+      const ws = new WebSocket(`ws://127.0.0.1:${port}/api/dsh-tty/ws`)
+      const timer = setTimeout(() => { ws.terminate(); resolve(false) }, 3000)
+      ws.once('open', () => { clearTimeout(timer); ws.terminate(); resolve(false) })
+      ws.once('error', () => { clearTimeout(timer); resolve(true) })
+      ws.once('close', () => { clearTimeout(timer); resolve(true) })
+    })
+    if (rejected) pass('B29g 禁用后新 WS 升级被拒')
+    else fail('B29g 禁用后新 WS 升级被拒', '3s 内未收到 error/close 或握手成功')
+
+    // 重新启用：工具、公告、WS 全部恢复
+    const on = await configPost({ enabled: true })
+    if (on.status === 200 && on.body.config?.enabled === true) pass('B29h 重新启用生效')
+    else fail('B29h 重新启用生效', `status=${String(on.status)}`)
+    await sleep(100)
+    if (toolDefs.length === 13) pass('B29i 重新启用后 13 个 agent 工具回归')
+    else fail('B29i 重新启用后 13 个 agent 工具回归', `当前 ${String(toolDefs.length)}`)
+    if (promptParts.length === 2) pass('B29j 重新启用后公告与动态快照恢复')
+    else fail('B29j 重新启用后公告与动态快照恢复', `当前 ${String(promptParts.length)}`)
+    const again = openSession(port)
+    try {
+      await again.open()
+      pass('B29k 重新启用后 WS 可连接')
+    } catch (error) {
+      fail('B29k 重新启用后 WS 可连接', String(error?.message ?? error).slice(0, 140))
+    }
+    again.client.close()
+  }
+
+  // B30: 服务器状态条（0.17.0）：SSH 会话的远端采集（非 PTY exec channel）
+  //      + 订阅驱动 + 开关热生效。刻意不用本地会话：本用例不依赖本机 PTY
+  //      （无 ptmx 的环境照样能跑），且远端采集正是该特性的主路径。
+  console.log('\n[30] 服务器状态条（SSH 远端采集 / 订阅 / 开关热生效）')
+  {
+    const ssh2mod = await import('ssh2')
+    const ssh2 = ssh2mod.default ?? ssh2mod
+    const { generateKeyPairSync } = await import('node:crypto')
+    const { privateKey } = generateKeyPairSync('rsa', {
+      modulusLength: 2048,
+      publicKeyEncoding: { type: 'spki', format: 'pem' },
+      privateKeyEncoding: { type: 'pkcs1', format: 'pem' },
+    })
+    /** 伪远端：只实现 shell + exec；exec 按真实采集脚本的输出形状回吐 JSON 行。 */
+    const execLog = []
+    const remote = new ssh2.Server({ hostKeys: [privateKey] }, (client) => {
+      client.on('authentication', (ctx) => {
+        if (ctx.method === 'password' && ctx.username === 'test' && ctx.password === 'secret') ctx.accept()
+        else ctx.reject()
+      })
+      client.on('ready', () => {
+        client.on('session', (accept) => {
+          const session = accept()
+          // 客户端的 conn.shell 会先发 pty-req：不接住的话 ssh2 服务端会自动拒绝，
+          // shell 根本开不起来（ssh-smoke 同一处坑）
+          session.on('pty', (acceptPty) => { acceptPty() })
+          session.on('window-change', () => {})
+          session.on('shell', (acceptShell) => {
+            const stream = acceptShell()
+            stream.write('dsh-integ:~$ ')
+            stream.on('data', () => {})
+          })
+          session.on('exec', (acceptExec, _rejectExec, info) => {
+            const stream = acceptExec()
+            execLog.push(typeof info?.command === 'string' ? info.command : '')
+            let tick = 0
+            const timer = setInterval(() => {
+              tick += 1
+              stream.write(JSON.stringify({
+                cpuPct: 30 + tick, cores: 4, memUsed: 1e9 * tick, memTotal: 4e9, memPct: 25 + tick,
+                diskTotal: 1e11, diskUsed: 5e10, diskPct: 50, uptimeSec: 1000 + tick,
+                tcpConns: 10 + tick, rxRate: 2048 * tick, txRate: 4096 * tick, tempC: 41.5,
+              }) + '\n')
+            }, 120)
+            const stop = () => clearInterval(timer)
+            stream.on('close', stop)
+            stream.on('end', stop)
+          })
+        })
+      })
+      client.on('error', () => {})
+    })
+    await new Promise((resolve) => remote.listen(0, '127.0.0.1', resolve))
+    const remotePort = remote.address().port
+    const postConfig = async (body) => {
+      const res = await fetch('http://127.0.0.1:' + String(port) + '/api/dsh-tty/config', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+      return { status: res.status, body: await res.json() }
+    }
+    const put = await postConfig({ sshHosts: [{ name: 'b30-ssh', host: '127.0.0.1', port: remotePort, username: 'test', auth: 'password', password: 'secret', keyPath: '', passphrase: '', agentForward: false }] })
+    if (put.status === 200) pass('B30a 内存 sshd + 连接簿就绪')
+    else fail('B30a 内存 sshd + 连接簿就绪', 'status=' + String(put.status))
+
+    const s = openSession(port)
+    const other = openSession(port)
+    await s.open()
+    await other.open()
+    s.client.send(JSON.stringify({ t: 'ssh', sid: 'b30', cols: 80, rows: 24, name: 'b30-ssh' }))
+    await s.waitFor(() => s.state.ready, 12000, 'ssh ready')
+    const statsFrames = () => s.state.frames.filter((f) => f.t === 'stats')
+    const otherStats = () => other.state.frames.filter((f) => f.t === 'stats')
+
+    // 懒启动：没有 statsOn 就不该开 exec channel
+    await sleep(900)
+    if (statsFrames().length === 0 && execLog.length === 0) pass('B30b 未订阅时不采集（懒启动，无 exec channel）')
+    else fail('B30b 未订阅时不采集（懒启动）', 'frames=' + String(statsFrames().length) + ' exec=' + String(execLog.length))
+
+    s.client.send(JSON.stringify({ t: 'statsOn', sid: 'b30' }))
+    await s.waitFor(() => statsFrames().length >= 2, 10000, 'stats 帧')
+    const frame = statsFrames()[statsFrames().length - 1]
+    const stats = frame.stats
+    const shapeOk = stats !== null && typeof stats === 'object' && stats.cores === 4 && Number.isFinite(stats.cpuPct) && stats.cpuPct >= 30 && stats.cpuPct <= 100 && Number.isFinite(stats.uptimeSec) && stats.tempC === 41.5
+    if (frame.sid === 'b30' && shapeOk) pass('B30c statsOn → 远端 exec 帧（逐行 JSON，cpuPct=' + String(stats.cpuPct) + ' cores=4 tempC=41.5）')
+    else fail('B30c statsOn → 远端 exec 帧', 'sid=' + String(frame.sid) + ' stats=' + JSON.stringify(stats).slice(0, 160))
+
+    const command = execLog[0] ?? ''
+    if (command.startsWith('sh -c ') && command.includes('/proc/stat')) pass('B30d 采集命令经 sh -c 单引号包裹（' + String(command.length) + ' 字符）')
+    else fail('B30d 采集命令形状', command.slice(0, 80))
+
+    await sleep(1200)
+    if (otherStats().length === 0) pass('B30e stats 帧只发给订阅者')
+    else fail('B30e stats 帧只发给订阅者', '旁路连接收到 ' + String(otherStats().length) + ' 帧')
+
+    const off = await postConfig({ statsEnabled: false })
+    if (off.status === 200 && off.body.config && off.body.config.statsEnabled === false) pass('B30f POST statsEnabled=false 生效')
+    else fail('B30f POST statsEnabled=false 生效', 'status=' + String(off.status))
+    const mark = statsFrames().length
+    await sleep(2000)
+    if (statsFrames().length === mark) pass('B30g 关闭后停表（远端 channel 关闭、不再发帧）')
+    else fail('B30g 关闭后停表', '多出 ' + String(statsFrames().length - mark) + ' 帧')
+
+    await postConfig({ statsEnabled: true })
+    await s.waitFor(() => statsFrames().length > mark, 10000, '重开后的 stats 帧')
+    pass('B30h 重开后按存留订阅自动恢复采集')
+
+    s.client.send(JSON.stringify({ t: 'statsOff', sid: 'b30' }))
+    await sleep(400)
+    const mark2 = statsFrames().length
+    await sleep(1600)
+    if (statsFrames().length === mark2) pass('B30i statsOff 后停表（无帧）')
+    else fail('B30i statsOff 后停表（无帧）', '多出 ' + String(statsFrames().length - mark2) + ' 帧')
+
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'b30' }))
+    await s.waitFor(() => s.state.exited !== null, 12000, 'exit 帧')
+    s.client.close()
+    other.client.close()
+    await new Promise((resolve) => remote.close(resolve))
+    remote.closeAllConnections?.()
+    await postConfig({ sshHosts: [] })
+  }
+
+  // B31: 服务器状态条——Windows 远端的自动回退（POSIX 脚本被拒 → PowerShell 分支）
+  //      伪远端模拟 cmd.exe：sh -c 脚本立即非零退出且 stdout 一个字节都不吐，
+  //      只有 -EncodedCommand 才回吐帧。断言：回退生效、只回退一次、退订即停表。
+  console.log('\n[31] 服务器状态条：Windows 远端回退（POSIX → PowerShell）')
+  {
+    const ssh2mod = await import('ssh2')
+    const ssh2 = ssh2mod.default ?? ssh2mod
+    const { generateKeyPairSync } = await import('node:crypto')
+    const { privateKey } = generateKeyPairSync('rsa', {
+      modulusLength: 2048,
+      publicKeyEncoding: { type: 'spki', format: 'pem' },
+      privateKeyEncoding: { type: 'pkcs1', format: 'pem' },
+    })
+    const execLog = []
+    const remote = new ssh2.Server({ hostKeys: [privateKey] }, (client) => {
+      client.on('authentication', (ctx) => {
+        if (ctx.method === 'password' && ctx.username === 'test' && ctx.password === 'secret') ctx.accept()
+        else ctx.reject()
+      })
+      client.on('ready', () => {
+        client.on('session', (accept) => {
+          const session = accept()
+          session.on('pty', (acceptPty) => { acceptPty() })
+          session.on('window-change', () => {})
+          session.on('shell', (acceptShell) => {
+            const stream = acceptShell()
+            stream.write('PS> ')
+            stream.on('data', () => {})
+          })
+          session.on('exec', (acceptExec, _rejectExec, info) => {
+            const command = typeof info?.command === 'string' ? info.command : ''
+            execLog.push(command)
+            const stream = acceptExec()
+            if (command.includes('-EncodedCommand')) {
+              // Windows 分支：用可辨认的值（cores=12 / cpuPct>=70）与 POSIX 分支区分
+              let tick = 0
+              const timer = setInterval(() => {
+                tick += 1
+                stream.write(JSON.stringify({
+                  cpuPct: 70 + tick, cores: 12, memTotal: 17179869184, memUsed: 9663676416, memPct: 56,
+                  diskTotal: 511000000000, diskUsed: 302000000000, diskPct: 59, uptimeSec: 1000 + tick,
+                  tcpConns: 142 + tick, rxRate: 4096 * tick, txRate: 8192 * tick,
+                }) + '\n')
+              }, 120)
+              const stop = () => clearInterval(timer)
+              stream.on('close', stop)
+              stream.on('end', stop)
+              return
+            }
+            // POSIX 分支：cmd.exe 语义——非零退出、stdout 无输出
+            stream.exit(1)
+            stream.end()
+          })
+        })
+      })
+      client.on('error', () => {})
+    })
+    await new Promise((resolve) => remote.listen(0, '127.0.0.1', resolve))
+    const remotePort = remote.address().port
+    const postConfig = async (body) => {
+      const res = await fetch('http://127.0.0.1:' + String(port) + '/api/dsh-tty/config', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+      return { status: res.status, body: await res.json() }
+    }
+    await postConfig({ sshHosts: [{ name: 'b31-ssh', host: '127.0.0.1', port: remotePort, username: 'test', auth: 'password', password: 'secret', keyPath: '', passphrase: '', agentForward: false }] })
+    const s = openSession(port)
+    await s.open()
+    s.client.send(JSON.stringify({ t: 'ssh', sid: 'b31', cols: 80, rows: 24, name: 'b31-ssh' }))
+    await s.waitFor(() => s.state.ready, 12000, 'ssh ready')
+    const statsFrames = () => s.state.frames.filter((f) => f.t === 'stats')
+
+    s.client.send(JSON.stringify({ t: 'statsOn', sid: 'b31' }))
+    await s.waitFor(() => statsFrames().length >= 2, 12000, '回退后的 stats 帧')
+    const stats = statsFrames()[statsFrames().length - 1].stats
+    if (stats !== null && stats.cores === 12 && Number.isFinite(stats.cpuPct) && stats.cpuPct >= 70) pass('B31a POSIX 被拒后自动回退 PowerShell 分支并出帧（cores=12）')
+    else fail('B31a 回退后出帧', JSON.stringify(stats))
+
+    const orderOk = execLog.length >= 2 && execLog[0].startsWith('sh -c ') && execLog[0].includes('/proc/stat') && execLog[1].includes('-EncodedCommand')
+    if (orderOk) pass('B31b 两跳顺序正确：先 POSIX（sh -c），后 -EncodedCommand')
+    else fail('B31b 两跳顺序', execLog.map((c) => c.slice(0, 40)).join(' | '))
+    await sleep(1200)
+    if (execLog.length === 2) pass('B31c 只回退一次（不无限重试）')
+    else fail('B31c 只回退一次', 'exec 次数=' + String(execLog.length))
+
+    s.client.send(JSON.stringify({ t: 'statsOff', sid: 'b31' }))
+    await sleep(400)
+    const mark = statsFrames().length
+    await sleep(1600)
+    if (statsFrames().length === mark) pass('B31d statsOff 后停表（无帧）')
+    else fail('B31d statsOff 后停表', '多出 ' + String(statsFrames().length - mark) + ' 帧')
+
+    s.client.send(JSON.stringify({ t: 'kill', sid: 'b31' }))
+    await s.waitFor(() => s.state.exited !== null, 12000, 'exit 帧')
+    s.client.close()
+    await new Promise((resolve) => remote.close(resolve))
+    remote.closeAllConnections?.()
+    await postConfig({ sshHosts: [] })
+  }
+
+  const failed = RESULTS.filter(([kind]) => kind === 'FAIL')
+  console.log(`\n==== 集成测试：${RESULTS.length - failed.length}/${RESULTS.length} PASS ====`)
+  for (const [kind, name, detail] of RESULTS) console.log(`  ${kind === 'PASS' ? '✔' : '✘'} ${name}${detail ? ' — ' + detail : ''}`)
+  process.exit(failed.length > 0 ? 1 : 0)
+}
+
+run().catch((error) => {
+  console.error('集成测试崩溃：', error)
+  process.exit(1)
+})