@hyzyn/dsh-tty 0.19.2 → 0.20.0

package/scripts/integration.mjs

@@ -53,7 +53,7 @@ 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 { assertSupportedJsonSchema, validateJsonSchemaValue } from '@deepseek-ai/dsh-tools'
 import { startSftpSshd, TEST_USER, TEST_PASSWORD } from './lib/test-sshd.mjs'
 
 
@@ -139,6 +139,8 @@ async function run() {
   // 最小 settings 服务 stub：让插件的 settings 注入回调触发，并可手动派发
   // settings/updated 事件（与 dsh-settings 的 dispatch 方式一致）来测配置热生效。
   const toolDefs = []
+  /** 输出契约违约（§B33：返回值与声明的 output.schema 不符，真实宿主会直接判工具错）。 */
+  const outputViolations = []
   const promptParts = []
   const stubFiber = app.plugin({
     name: 'settings-stub',
@@ -146,6 +148,32 @@ async function run() {
       ctx.provide('settings', { register: () => ({ get: () => ({}), update: async () => {} }) })
       ctx.provide('tools', {
         register: (definition) => {
+          // 输出契约看门狗（§B33）：把 execute 的返回值按**声明的 output.schema**
+          // 校验一遍，把违约记进 outputViolations。
+          //
+          // 为什么在这里做：宿主真的会校验（dsh-tools 用 additionalProperties:false
+          // 判非法输出，工具直接返回 Error），而此前的 B12e 只校验「schema 形状是否
+          // 受支持」，校验不了「返回值是否符合 schema」——tty_list 加 owner 字段时
+          // 漏改 schema 就是这样溜过去的：schema 形状合法、返回值多一个字段，
+          // 只有在真实宿主里调用才炸。
+          const origin = definition.execute
+          if (typeof origin === 'function') {
+            definition.execute = async (args, ctx) => {
+              const value = await origin(args, ctx)
+              try {
+                const schema = definition.output?.schema
+                if (schema !== undefined) {
+                  const violations = validateJsonSchemaValue(schema, value)
+                  if (Array.isArray(violations) && violations.length > 0) {
+                    outputViolations.push(`${definition.name}: ${violations.join('; ')}`)
+                  }
+                }
+              } catch (error) {
+                outputViolations.push(`${definition.name}: 校验抛错 ${String(error && error.message ? error.message : error)}`)
+              }
+              return value
+            }
+          }
           toolDefs.push(definition)
           // dispose 必须真摘除：B29 禁用场景要断言「工具全部撤下」
           return () => {
@@ -463,6 +491,26 @@ async function run() {
       }
       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))
+      // capture{last:true}：走「上一条已完成命令 + 退出码」分支。这条分支的返回值
+      // 带可选 exitCode（曾用 `?? undefined` 留下 undefined 键 → 宿主输出校验判错，
+      // 见 B33），此前 B12 只用 lines 路径、恰好绕过了它。这里跑一条会失败的命令，
+      // 退出码必然存在，同时也把该分支送进输出契约看门狗。
+      let lastResult = null
+      for (let i = 0; i < 16; i++) {
+        await sleep(250)
+        try {
+          lastResult = await capture.execute({ sid: 't12', last: true })
+        } catch {
+          lastResult = null // 命令在途时抛错（inProgress 语义），继续等
+          continue
+        }
+        if (lastResult !== null && lastResult.inProgress !== true) break
+      }
+      if (lastResult !== null && lastResult.inProgress !== true && typeof lastResult.tail === 'string' && lastResult.tail.includes('CAPTURE_OK')) {
+        pass('B12f tty_capture{last:true} 拿到上一条命令输出与退出码')
+      } else {
+        fail('B12f tty_capture{last:true} 拿到上一条命令输出与退出码', JSON.stringify(lastResult).slice(0, 140))
+      }
       let rejected = false
       try {
         await capture.execute({ sid: 'ghost-session' })
@@ -1259,14 +1307,23 @@ async function run() {
       else fail('B26c 恢复会话 kill 后 tmux 会话清理', JSON.stringify(listedFinal))
       w2.client.close()
 
-      // B26d: attach 不回放缓冲 —— 重连后现场由 tmux refresh-client 重画恰好一次
-      //（旧行为：回放缓冲 + tmux 重画 = 内容重影 + 幽灵滚动条）
+      // B26d: attach 不回放宿主环形缓冲。
+      //
+      // 判据（D51 修订）：**不能**数「marker 在屏幕上出现几次」——attach 天然有
+      // 两个重画来源（tmux `-A` 自身 + 宿主 refresh-client），偶尔都落帧就是 2 次，
+      // 而那是观感问题、不是本用例要锁的回归；旧断言因此在真实 PTY 下偶发假红。
+      //
+      // 真正要锁的是「回放 vs 不回放」。用一个滚出可见屏的 marker 区分：
+      //   · 回放宿主 256KB 环形缓冲 → 连历史一起送到 → marker 出现（回归）
+      //   · 跳过回放、只由 tmux 重画可见屏 → 历史不在屏上 → marker 不出现（正确）
+      // 尾部再打一个 B26TAIL 留在屏上，用它证明「确实重画过了」，避免把
+      // 「什么都没收到」误判成通过。
       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 输出')
+      w3.client.send(JSON.stringify({ t: 'input', sid: 'b26d', d: 'printf "B26REFRESH-%s\\n" ok; for i in $(seq 1 40); do echo "B26FILLER-$i"; done; printf "B26TAIL-%s\\n" ok\n' }))
+      await w3.waitFor(() => /B26TAIL-ok/.test(w3.state.text), 10000, 'b26d 输出（marker 已滚出可见屏）')
       await sleep(600) // 等 D 标记与重画尘埃落定
       w3.client.close() // 异常断开 → 孤儿（grace=1s，需在回收前尽快 attach）
       await sleep(200)
@@ -1274,16 +1331,20 @@ async function run() {
       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 重画（不碰尺寸）
+      // 等 tmux 把可见屏重画出来（尾部 marker 可见 = 重画确实发生了）
+      await w4.waitFor(() => /B26TAIL-ok/.test(w4.state.text), 10000, 'refresh-client 重画')
+      await sleep(600) // 重画可能多帧落定：等稳定后再判定
+      const replayed = /B26REFRESH-ok/.test(w4.state.text)
+      if (!replayed) pass('B26d attach 跳过缓冲回放（仅 tmux 重画可见屏，无重影/幽灵滚动条）')
+      else fail('B26d attach 跳过缓冲回放（仅 tmux 重画可见屏，无重影/幽灵滚动条）', 'attach 后收到了已滚出屏的历史（宿主环形缓冲被回放）')
+      // refresh 帧：reset 后请宿主 refresh-client 重画（不碰尺寸）。
+      // 判据用屏上可见的尾部 marker（B26REFRESH 已滚出屏，见上一条），且
+      // 只要求「重画后仍可见」——不数次数（多来源重画是正常观感，见 D51）。
       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
+      const refreshedOk = /B26TAIL-ok/.test(w4.state.text) && w4.state.errors.length === 0
       if (refreshedOk) pass('B26e refresh 帧（refresh-client 重画，无错误）')
-      else fail('B26e refresh 帧（refresh-client 重画，无错误）', `errors=${JSON.stringify(w4.state.errors)}`)
+      else fail('B26e refresh 帧（refresh-client 重画，无错误）', `errors=${JSON.stringify(w4.state.errors)} tailVisible=${String(/B26TAIL-ok/.test(w4.state.text))}`)
       w4.client.send(JSON.stringify({ t: 'kill', sid: 'b26d' }))
       await w4.waitFor(() => w4.state.exited !== null, 10000, 'b26d exit')
       w4.client.close()
@@ -1447,8 +1508,8 @@ async function run() {
     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 (toolDefs.length === 16) pass('B29i 重新启用后 16 个 agent 工具回归')
+    else fail('B29i 重新启用后 16 个 agent 工具回归', `当前 ${String(toolDefs.length)}`)
     if (promptParts.length === 2) pass('B29j 重新启用后公告与动态快照恢复')
     else fail('B29j 重新启用后公告与动态快照恢复', `当前 ${String(promptParts.length)}`)
     const again = openSession(port)
@@ -1679,6 +1740,102 @@ async function run() {
     await postConfig({ sshHosts: [] })
   }
 
+  // B32: agent 自开终端（0.20.0 tty_open / tty_close / tty_stats）
+  //
+  // 锁的是「闭环」这件事：agent 能自己开一个会话（不必用户在面板里点）、
+  // 长了长驻进程能读到就绪信号、用完能自己关；同时锁住两条边界：
+  //   ① agent 开的会话不被孤儿回收器当孤儿收掉（否则长驻任务一开就没）；
+  //   ② tty_close 拒绝关用户开的会话（agent 不越权结束用户正在用的标签）。
+  console.log('\n[30] agent 自开终端')
+  {
+    const open = toolDefs.find((d) => d.name === 'tty_open')
+    const close = toolDefs.find((d) => d.name === 'tty_close')
+    const statsT = toolDefs.find((d) => d.name === 'tty_stats')
+    const list = toolDefs.find((d) => d.name === 'tty_list')
+    const expect = toolDefs.find((d) => d.name === 'tty_expect')
+    if (open === undefined || close === undefined || statsT === undefined) {
+      fail('B32 agent 自开终端工具集', '缺工具: ' + toolDefs.map((d) => d.name).join(','))
+    } else {
+      // 面板连接先开着：验证 agent 开的会话会被推到面板（用户可见）
+      const panel = openSession(port)
+      await panel.open()
+
+      const opened = await open.execute({ cwd: '/tmp' })
+      const sid = opened.sid
+      if (typeof sid === 'string' && sid !== '') pass('B32a tty_open 开出会话')
+      else fail('B32a tty_open 开出会话', JSON.stringify(opened))
+
+      // owner=agent 出现在 tty_list 里
+      const listed = await list.execute({})
+      const mine = (listed.sessions ?? []).find((x) => x.sid === sid)
+      if (mine !== undefined && mine.owner === 'agent') pass('B32b tty_list 标出 owner=agent')
+      else fail('B32b tty_list 标出 owner=agent', JSON.stringify(mine))
+
+      // 面板可见（sessions 帧广播带 owner=agent，且 attachable）
+      let visible = false
+      for (let i = 0; i < 20; i++) {
+        await sleep(150)
+        const frame = panel.state.frames.filter((f) => f.t === 'sessions').at(-1)
+        const entry = (frame?.list ?? []).find((x) => x.sid === sid)
+        if (entry !== undefined && entry.owner === 'agent' && entry.attachable === true) { visible = true; break }
+      }
+      if (visible) pass('B32c agent 开的会话对面板可见（owner=agent + attachable）')
+      else fail('B32c agent 开的会话对面板可见', '面板没收到该会话的 sessions 帧')
+
+      // 长驻任务闭环：起一个「先等一拍再打印就绪」的进程，用 tty_expect 等它
+      const send = toolDefs.find((d) => d.name === 'tty_send')
+      await send.execute({ sid, data: 'sleep 1; printf "B32READY-%s\\n" go\n' })
+      const waited = await expect.execute({ sid, pattern: 'B32READY-go', timeoutSec: 15 })
+      if (waited.matched === true) pass('B32d tty_open + tty_expect 长任务就绪闭环')
+      else fail('B32d tty_open + tty_expect 长任务就绪闭环', JSON.stringify(waited).slice(0, 120))
+
+      // 用户开一个会话，验证 agent 关不掉它
+      panel.client.send(JSON.stringify({ t: 'spawn', sid: 'b32user', cols: 80, rows: 24 }))
+      await panel.waitFor(() => panel.state.ready, 10000, 'b32user ready')
+      let refused = false
+      try {
+        await close.execute({ sid: 'b32user' })
+      } catch {
+        refused = true
+      }
+      const stillAlive = (await list.execute({})).sessions.some((x) => x.sid === 'b32user')
+      if (refused && stillAlive) pass('B32e tty_close 拒绝关用户开的会话（不越权）')
+      else fail('B32e tty_close 拒绝关用户开的会话', `refused=${String(refused)} alive=${String(stillAlive)}`)
+
+      // agent 关自己的会话
+      const closed = await close.execute({ sid })
+      if (closed.ok === true) pass('B32f tty_close 关掉 agent 自己的会话')
+      else fail('B32f tty_close 关掉 agent 自己的会话', JSON.stringify(closed))
+      await sleep(300)
+      const gone = !(await list.execute({})).sessions.some((x) => x.sid === sid)
+      if (gone) pass('B32g 关闭后会话从清单消失')
+      else fail('B32g 关闭后会话从清单消失', '仍在 sessions 里')
+
+      // tty_stats：本地会话取宿主机指标（本机是 macOS，部分字段可采；只要有数据即通过）
+      const stat = await statsT.execute({ sid: 'b32user' })
+      if (stat.available === true && (typeof stat.memPct === 'number' || typeof stat.cpuPct === 'number')) {
+        pass('B32h tty_stats 取到本机指标')
+      } else {
+        fail('B32h tty_stats 取到本机指标', JSON.stringify(stat).slice(0, 160))
+      }
+
+      panel.client.send(JSON.stringify({ t: 'kill', sid: 'b32user' }))
+      await panel.waitFor(() => panel.state.exited !== null, 10000, 'b32user exit')
+      panel.client.close()
+    }
+  }
+
+  // B33: 输出契约（所有已调用工具的真实返回值都符合各自声明的 output.schema）
+  //
+  // 这一条是 §B12e 的补充：B12e 只证明 schema 形状受支持，证明不了返回值合法。
+  // 真实宿主对输出做 additionalProperties:false 校验，违约会直接把工具调用变成
+  // Error（tty_list 加 owner 漏改 schema 即此）。
+  console.log('\n[31] 输出契约')
+  {
+    if (outputViolations.length === 0) pass('B33 工具返回值符合声明的 output.schema')
+    else fail('B33 工具返回值符合声明的 output.schema', outputViolations.slice(0, 3).join(' | '))
+  }
+
   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 : ''}`)

package/scripts/preview/harness.js

@@ -246,6 +246,33 @@
         return null
       }
     },
+    /* 宿主采样慢（D50）：stats 帧 4 秒才来一次——旧代码的 3s 陈旧窗口会让状态条
+       每秒整条收起再出现（用户报的「瞬间消失又出现」）。这里连续采样 9 秒（跨两个
+       帧间隔），要求状态条**一次都没有**隐藏过。 */
+    async 'stats-slow'() {
+      window.__PREVIEW_STATS_INTERVAL_MS = 4000
+      await openPanel()
+      await waitFor(() => tabs().length === 1)
+      // 首帧立即推 → 状态条先出来
+      await waitFor(() => {
+        const bar = q('.tt_statsBar')
+        return bar !== null && bar.hidden !== true && /CPU/.test(bar.textContent)
+      }, 4000)
+      const visible = []
+      const timer = setInterval(() => {
+        const bar = q('.tt_statsBar')
+        visible.push(bar !== null && bar.hidden !== true)
+      }, 100)
+      await sleep(9000)
+      clearInterval(timer)
+      window.__previewAssert = async () => {
+        const hidden = visible.filter((value) => value !== true).length
+        if (hidden > 0) {
+          return '4s 一帧时状态条有 ' + String(hidden) + '/' + String(visible.length) + ' 次采样是隐藏的（整条消失又出现）'
+        }
+        return null
+      }
+    },
     /* 坏数据兜底：宿主发来的 stats 帧是垃圾（字符串/数组/null/越界值/缺字段），
        面板必须既不抛异常也不出现非法渲染——最多整条隐藏 */
     async 'stats-broken'() {
@@ -359,6 +386,172 @@
       await waitFor(() => q('#preview-settings .tt_cardBody'))
       await sleep(400)
     },
+    /* 端口转发：编辑一条隧道（此前隧道区块零界面回归，D53/D54/D56 就是这么潜伏的） */
+    async 'tunnel-edit'() {
+      const host = document.createElement('div')
+      host.id = 'preview-settings'
+      host.style.cssText = 'position:fixed;inset:24px 24px 24px 260px;overflow:auto;z-index:2000;background:var(--dsw-alias-bg-base);padding:8px;border-radius:16px'
+      document.body.appendChild(host)
+      const root = window.ReactDOM.createRoot(host)
+      root.render(window.React.createElement(cards[0].Component))
+      await waitFor(() => q('#preview-settings .tt_card'))
+      await sleep(80)
+      q('#preview-settings .tt_cardHeader').click()
+      await waitFor(() => q('#preview-settings .tt_cardBody'))
+      await sleep(400)
+
+      const rowOf = (name) => [...document.querySelectorAll('#preview-settings .tt_sshHostRow')]
+        .find((r) => (r.querySelector('.tt_sshHostName')?.textContent ?? '').startsWith(name))
+      const buttonsIn = (el) => [...el.querySelectorAll('button')]
+
+      // 「编辑」按钮是本次新增的能力：先在第一条隧道行上找到它
+      const firstRow = rowOf('staging-pg')
+      if (firstRow === undefined) throw new Error('找不到 staging-pg 行（fixture 应有该隧道）')
+      const editBtn = buttonsIn(firstRow).find((b) => b.textContent === '编辑')
+      if (editBtn === undefined) throw new Error('隧道行没有「编辑」按钮')
+      editBtn.click()
+      await sleep(150)
+
+      // 把隧道区块滚进视口：截图要能拍到表单本身（设置卡片很长，隧道在下方）
+      const scrollTunnelIntoView = () => {
+        const anchor = document.querySelector('#preview-settings .tt_segmented') ?? document.querySelector('#preview-settings .tt_tunnelEndpoints')
+        if (anchor !== null) anchor.scrollIntoView({ block: 'center' })
+      }
+      scrollTunnelIntoView()
+      await sleep(120)
+
+      // 回填：本地转发那边「127.0.0.1:<端口>」成对呈现，端口输入带 aria-label 标识
+      const localPortInput = document.querySelector('#preview-settings [aria-label="本机监听端口"]')
+      if (localPortInput === null) throw new Error('本地转发表单没渲染（找不到本机监听端口输入）')
+      if (localPortInput.value !== '15432') throw new Error('编辑未回填本地端口：' + String(localPortInput.value))
+
+      // 固定端必须是**静态文本**而不是输入框（宿主硬编码了 127.0.0.1，给个能改的框是骗人）
+      const staticEnd = document.querySelector('#preview-settings .tt_tunnelEndpointStatic')
+      if (staticEnd === null) throw new Error('固定端没有渲染成静态文本')
+      if (staticEnd.textContent !== '127.0.0.1') throw new Error('固定端文本不对：' + String(staticEnd.textContent))
+      if (staticEnd.tagName === 'INPUT') throw new Error('固定端是输入框（应为静态文本）')
+
+      // 端点必须是成对呈现（host+port 同组），且中间有方向箭头
+      const endpointCount = document.querySelectorAll('#preview-settings .tt_tunnelEndpoint').length
+      if (endpointCount !== 2) throw new Error('端点组数不为 2：' + String(endpointCount))
+      if (document.querySelector('#preview-settings .tt_tunnelArrow') === null) throw new Error('缺少方向箭头')
+
+      // 分段控件：本地/远程可切换，当前项高亮
+      const segBtns = [...document.querySelectorAll('#preview-settings .tt_segmentedBtn')]
+      if (segBtns.length !== 2) throw new Error('分段控件按钮数不为 2：' + String(segBtns.length))
+      const activeSeg = segBtns.filter((b) => b.hasAttribute('data-active'))
+      if (activeSeg.length !== 1) throw new Error('分段控件没有唯一高亮项：' + String(activeSeg.length))
+
+      // 切到「远程 -R」：固定端应换到**右侧**（本机拨号），左侧变成可填的服务器侧监听地址
+      // ——两个方向的固定端不同，这正是不能照搬单一形状的原因
+      segBtns.find((b) => (b.textContent ?? '').includes('远程')).click()
+      await sleep(200)
+      scrollTunnelIntoView()
+      const remoteEndpoints = [...document.querySelectorAll('#preview-settings .tt_tunnelEndpoint')]
+      if (remoteEndpoints.length !== 2) throw new Error('远程方向端点组数不为 2：' + String(remoteEndpoints.length))
+      const hasStaticInFirst = remoteEndpoints[0].querySelector('.tt_tunnelEndpointStatic') !== null
+      const hasStaticInSecond = remoteEndpoints[1].querySelector('.tt_tunnelEndpointStatic') !== null
+      if (hasStaticInFirst || !hasStaticInSecond) {
+        throw new Error('远程方向的固定端没有换到右侧（左静态=' + String(hasStaticInFirst) + ' 右静态=' + String(hasStaticInSecond) + '）')
+      }
+      // 箭头在远程方向应翻转（CSS 旋转 180°，data-direction 决定）
+      const arrow = document.querySelector('#preview-settings .tt_tunnelArrow')
+      if (arrow === null || arrow.getAttribute('data-direction') !== 'remote') {
+        throw new Error('远程方向的箭头没有翻转标记')
+      }
+      // 切回本地 -L，后续断言按本地方向的期望继续
+      segBtns.find((b) => (b.textContent ?? '').includes('本地')).click()
+      await sleep(200)
+      scrollTunnelIntoView()
+      await sleep(80)
+
+      /*
+       * 窄容器下的排布：端点用 flex-wrap，最怕的是"挤不下也不换行 → 内容溢出到卡片外"。
+       * 设置卡片在真实界面里可能只有一栏宽度，所以这里把容器压到 420px 验证：
+       * ① 端点该换行（不是硬挤一行）；② 没有任何子元素横向溢出容器。
+       */
+      {
+        const settingsHost = document.querySelector('#preview-settings')
+        const originalWidth = settingsHost.style.width
+        settingsHost.style.width = '420px'
+        await sleep(200)
+        const endpointsRow = document.querySelector('#preview-settings .tt_tunnelEndpoints')
+        const card = document.querySelector('#preview-settings .tt_card')
+        if (endpointsRow !== null && card !== null) {
+          const rowRect = endpointsRow.getBoundingClientRect()
+          const cardRect = card.getBoundingClientRect()
+          if (rowRect.right > cardRect.right + 1) {
+            throw new Error('窄容器下端点半点溢出卡片（右边界 ' + rowRect.right.toFixed(0) + ' > 卡片 ' + cardRect.right.toFixed(0) + '）')
+          }
+          // 两个端点必须真的换行（上下排布），而不是压成一行把内容挤扁
+          const groups = [...document.querySelectorAll('#preview-settings .tt_tunnelEndpoint')]
+          if (groups.length === 2) {
+            const a = groups[0].getBoundingClientRect()
+            const b = groups[1].getBoundingClientRect()
+            if (Math.abs(a.top - b.top) < 4) {
+              throw new Error('窄容器下两个端点没有换行（仍在同一行，会被挤扁）')
+            }
+          }
+        }
+        settingsHost.style.width = originalWidth
+        await sleep(200)
+        scrollTunnelIntoView()
+      }
+
+      // 方向切换会重渲表单：DOM 节点可能被替换，重新取一次（别用切换前的引用）
+      const localPortInput2 = document.querySelector('#preview-settings [aria-label="本机监听端口"]')
+      if (localPortInput2 === null) throw new Error('切回本地后表单没渲染')
+
+      const body = q('#preview-settings .tt_cardBody')
+      if (buttonsIn(body).find((b) => b.textContent === '保存修改') === undefined) throw new Error('编辑态没有「保存修改」')
+      if (buttonsIn(body).find((b) => b.textContent === '取消') === undefined) throw new Error('编辑态没有「取消」')
+      if (buttonsIn(body).find((b) => b.textContent === '添加隧道') !== undefined) {
+        throw new Error('编辑态仍显示「添加隧道」（会误加一条而不是改这条）')
+      }
+      if (document.querySelectorAll('#preview-settings .tt_sshHostRow[data-editing]').length !== 1) {
+        throw new Error('正在编辑的行没有唯一标记（data-editing）')
+      }
+
+      // 改端口 → 保存：名字必须按规则**重新派生**（`<bookName>-L<localPort>`）。
+      //
+      // 注意 fixture 里那条叫 `staging-pg`（手写的假名字，不符合派生规则），
+      // bookName 是 `staging-db`——所以编辑后新名字是 `staging-db-L15433`。
+      // 真实数据里隧道名一律由规则派生（UI 没有"自定义名字"入口），编辑不会改名；
+      // 这里恰好顺带钉住了"名字按规则重算"这个语义。
+      //
+      // 直接 `input.value = x` 对 React 无效：React 在 input 上装了 value 的原生
+      // setter，直接赋值后它读到的还是旧值（受控组件状态不更新）。必须先取 prototype
+      // 上的原生 setter 赋值、再派发冒泡的 input 事件。harness 里此前没有"往输入框
+      // 打字"的场景，这是第一个（`setReactInput` 供后续场景复用）。
+      const setReactInput = (el, value) => {
+        const desc = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')
+        desc.set.call(el, value)
+        el.dispatchEvent(new window.Event('input', { bubbles: true }))
+      }
+      setReactInput(localPortInput2, '15433')
+      await sleep(150)
+      buttonsIn(body).find((b) => b.textContent === '保存修改').click()
+      await sleep(400)
+
+      window.__previewAssert = async () => {
+        const problems = []
+        const names = [...document.querySelectorAll('#preview-settings .tt_sshHostName')].map((el) => el.textContent ?? '')
+        if (!names.some((n) => n.startsWith('staging-db-L15433'))) {
+          problems.push('改端口后名字没按规则重新派生：' + names.join(' | '))
+        }
+        if (names.some((n) => n.startsWith('staging-pg'))) {
+          problems.push('旧名字仍在（按原始名定位替换失败）')
+        }
+        // 另一条隧道不能受影响（编辑只动被编辑的那条）
+        if (!names.some((n) => n.startsWith('prod-redis'))) {
+          problems.push('编辑波及了别的隧道')
+        }
+        if (buttonsIn(document.querySelector('#preview-settings .tt_cardBody')).find((b) => b.textContent === '添加隧道') === undefined) {
+          problems.push('保存后没有退出编辑态')
+        }
+        return problems.length > 0 ? problems.join('；') : null
+      }
+    },
     /* 设置卡片：docker 与 tty 并排（同一张 ul 里），核对两家的观感是否一致 */
     async 'settings-docker'() {
       const host = document.createElement('div')
@@ -397,6 +590,94 @@
         ttyDesc: getComputedStyle(q('.tt_cardDescription')).fontSize,
       }
     },
+    /*
+     * docker 设置卡片：失效的连接簿引用要**看得出来**。
+     *
+     * 背景：`book` 下拉的候选项来自 ttyBooks，引用的名字若不在其中，下拉会渲染成**空白**
+     * （没有匹配的 option）——界面上完全看不出错，直到真去连才报「引用的连接簿条目不存在」。
+     * 实测踩过：目标引用 HS-248，而连接簿里只有 HS_248_ADMIN（改名后残留的旧引用）。
+     * 这里钉住：失效行有 data-stale 标记 + 下拉里补了显式 option + 给出了提示文案。
+     */
+    async 'docker-stale-book'() {
+      const host = document.createElement('div')
+      host.id = 'preview-docker-settings'
+      host.style.cssText = 'position:fixed;inset:24px 24px 24px 260px;overflow:auto;z-index:2000;background:var(--dsw-alias-bg-base);padding:8px;border-radius:16px'
+      document.body.appendChild(host)
+      const docker = cards.find((c) => c.spec.key === 'docker')
+      if (docker === undefined) throw new Error('未注册 docker 设置卡片')
+      const root = window.ReactDOM.createRoot(host)
+      root.render(window.React.createElement(docker.Component))
+      await waitFor(() => q('#preview-docker-settings .dk_settingsCard'), 4000)
+      q('#preview-docker-settings .dk_settingsHead').click()
+      await waitFor(() => q('#preview-docker-settings .dk_settingsBody'), 4000)
+      await sleep(500)
+
+      /*
+       * 「目标名」输入框必须能连续打字。
+       *
+       * 实测 bug：那一行的 React key 写成 `String(index) + item.name`——key 里含 item.name，
+       * 于是每敲一个字符 key 就变一次，React 判定为"新元素"、卸载重建整行 DOM，输入框当场
+       * 失焦（表现就是"这个输入框无法聚焦"，只能输进去一个字）。修法是 key 只留 index
+       * （行是**按位置**编辑的，顺序变化由数组本身负责，名字不该参与身份）。
+       *
+       * 这里模拟真实输入：聚焦 → 逐个字符派发 input 事件 → 检查焦点是否还在同一个节点上、
+       * 且累积的文本完整（重建会让 value 回退/焦点丢失）。
+       */
+      const nameInput = document.querySelector('#preview-docker-settings .dk_targetRow .dk_input')
+      if (nameInput === null) throw new Error('找不到目标名输入框')
+      nameInput.focus()
+      if (document.activeElement !== nameInput) throw new Error('目标名输入框无法聚焦')
+      const setNative = (el, value) => {
+        const desc = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')
+        desc.set.call(el, value)
+        el.dispatchEvent(new window.Event('input', { bubbles: true }))
+      }
+      // 逐字符敲 "abc"：若 key 含 name，每次都会重建节点 → 焦点丢失
+      const typed = 'Xy9'
+      let accumulated = ''
+      for (const ch of typed) {
+        accumulated += ch
+        setNative(nameInput, accumulated)
+        await sleep(60)
+        if (document.activeElement !== nameInput) {
+          throw new Error('敲入第 ' + String(accumulated.length) + ' 个字符后输入框失焦（key 含可变字段导致 DOM 重建）')
+        }
+      }
+      if (nameInput.value !== typed) {
+        throw new Error('输入未累积完整（期望 ' + typed + '，实得 ' + String(nameInput.value) + '）')
+      }
+
+      window.__previewAssert = async () => {
+        const problems = []
+        const rows = [...document.querySelectorAll('#preview-docker-settings .dk_targetRow')]
+        if (rows.length === 0) return '目标行没渲染出来'
+        const staleRows = rows.filter((r) => r.hasAttribute('data-stale'))
+        if (staleRows.length !== 1) {
+          problems.push('应恰好有 1 行被标为失效引用，实得 ' + String(staleRows.length))
+        }
+        // 失效那一行的下拉必须**显示得出那个失效的名字**（否则是空白，看不出问题）。
+        // 注意一行里有**两个** select：第 1 个是「本机 / SSH 主机」的 kind，第 2 个才是
+        // 连接簿下拉——按 title 定位它（staleBookRef 命中时会给它加提示 title）。
+        const staleSelect = staleRows[0]?.querySelector('select[title]')
+        if (staleSelect === undefined || staleSelect === null) {
+          problems.push('失效引用那行的连接簿下拉没有提示 title')
+        } else {
+          const text = staleSelect.options[staleSelect.selectedIndex]?.textContent ?? ''
+          if (!text.includes('已改名的条目')) problems.push('失效引用的名字没在下拉里显式显示：' + text)
+          if (!text.includes('不存在')) problems.push('失效引用没有标注「不存在」：' + text)
+        }
+        // 提示文案要给出可执行的下一步
+        const warn = staleRows[0]?.querySelector('.dk_hintWarn')
+        if (warn === null || warn === undefined) problems.push('失效引用那行没有警示文案')
+        // 正常引用（prod-web-01）不能被误标
+        const healthy = rows.find((r) => {
+          const sel = r.querySelector('select[title], select')
+          return sel !== null && [...sel.options].some((o) => o.value === 'prod-web-01' && o.selected)
+        })
+        if (healthy !== undefined && healthy.hasAttribute('data-stale')) problems.push('正常引用被误标为失效')
+        return problems.length > 0 ? problems.join('；') : null
+      }
+    },
     /* SFTP 单窗体（0.16.0 起挂进右侧挂载位，终端保持可见） */
     async sftp() {
       await openPanel()
@@ -563,6 +844,47 @@
       await waitFor(() => q('.tt_tunnelPop'))
       await sleep(300)
     },
+    /*
+     * 连接栏「⋯」更多（没有启用隧道的连接）。
+     *
+     * 这条路径此前**完全不可见**：隧道入口只在 `count > 0` 时出现，没配隧道的连接在界面上
+     * 没有任何线索能发现"这里可以配端口转发"。现在没隧道时收进「⋯」——既有发现路径、
+     * 又不占常驻宽度（连接栏宽度优先给标签条）。
+     */
+    async 'connbar-more'() {
+      await openPanel()
+      // bare-host 在 fixture 里刻意没有任何隧道
+      await clickAdd()
+      await clickMenuItem('bare-host')
+      await waitFor(() => tabs().length === 2)
+      await sleep(300)
+
+      const acts = qa('.tt_connAct')
+      // 没有隧道 ⇒ 不该出现常驻「隧道 N」按钮
+      if (acts.some((b) => b.textContent.includes('隧道'))) {
+        throw new Error('没有隧道的连接却出现了常驻「隧道」按钮')
+      }
+      const more = acts.find((b) => b.textContent.includes('更多'))
+      if (more === undefined) throw new Error('没有隧道的连接缺少「⋯ 更多」入口')
+      more.click()
+      await waitFor(() => q('.tt_connMore'))
+      await sleep(250)
+
+      // 闭环：菜单项必须真的可点、并给出可执行的信息（该连接没有启用隧道 + 去哪配）
+      const item = qa('.tt_connMore .tt_addMenuItem').find((el) => el.textContent.includes('端口转发'))
+      if (item === undefined) throw new Error('「⋯」菜单里没有端口转发项')
+      item.click()
+      await waitFor(() => q('.tt_tunnelPop'))
+      await sleep(300)
+      window.__previewAssert = async () => {
+        const pop = q('.tt_tunnelPop')
+        if (pop === null) return '点击菜单项后没有打开隧道弹层'
+        const text = pop.textContent ?? ''
+        if (!text.includes('暂无启用')) return '弹层没有说明「该连接暂无启用的隧道」：' + text
+        if (!text.includes('插件配置') && !text.includes('设置')) return '弹层没有告诉用户去哪配置'
+        return null
+      }
+    },
     /* 搜索框展开 */
     async search() {
       await openPanel()

package/scripts/preview/mock-host.js

@@ -45,6 +45,9 @@
     sshHosts: [
       { name: 'prod-web-01', host: '198.51.100.20', port: 22, username: 'deploy', auth: 'key', keyPath: '~/.ssh/id_ed25519', passphrase: '', password: '', agentForward: true, persist: false },
       { name: 'staging-db', host: 'db.staging.internal', port: 2222, username: 'root', auth: 'password', keyPath: '', passphrase: '', password: 'env:STAGING_DB_PASSWORD', agentForward: false, persist: false },
+      // 刻意**没有**任何隧道：验证「没配隧道时收进 ⋯ 更多」这条路径
+      // （上面两条都有隧道，走的是常驻「隧道 N」按钮）
+      { name: 'bare-host', host: 'bare.internal', port: 22, username: 'ops', auth: 'agent', keyPath: '', passphrase: '', password: '', agentForward: false, persist: false },
     ],
     hostKeys: [
       { host: '198.51.100.20', port: 22, fingerprint: 'SHA256:9xQ2mVr7Kp3sTf1cZbLd8uYwAe4nHjR6gPoXkMvQ2Bc' },
@@ -131,6 +134,9 @@
       { name: '目标1', kind: 'ssh', book: '', host: '192.0.2.10', port: 22, username: 'root', auth: 'agent', agentForward: false },
       { name: '目标2', kind: 'local', book: '', host: '', port: 22, username: '', auth: 'agent', agentForward: false },
       { name: 'prod-web-01', kind: 'ssh', book: 'prod-web-01', host: '', port: 22, username: '', auth: 'agent', agentForward: false },
+      // 刻意引用一个**不在 ttyBooks 里**的条目名：验证设置卡片能把"失效引用"标出来
+      // （不标的话那个 book 下拉渲染成空白，看不出错，要等真去连才报）
+      { name: '陈旧引用', kind: 'ssh', book: '已改名的条目', host: '', port: 22, username: '', auth: 'agent', agentForward: false },
     ],
   }
   window.__PREVIEW_DOCKER_CONTAINERS = [
@@ -307,7 +313,9 @@
           } })
         }
         push()
-        this._statsTimer = setInterval(push, 1000)
+        // 推送间隔可调（stats-slow 场景用 4s 复现「宿主采样慢」：D50 里那台 macOS
+        // 的 netstat -ib 挂 3s、帧间隔被拉到 4s，旧的 3s 陈旧窗口于是每 4 秒闪一次）
+        this._statsTimer = setInterval(push, Number(window.__PREVIEW_STATS_INTERVAL_MS) || 1000)
         return
       }
       if (msg.t === 'statsOff') {