@hyzyn/dsh-tty 0.21.0 → 0.22.0-rc.2

package/scripts/integration.mjs

@@ -19,7 +19,7 @@
  *   B14. tty_screen 虚拟屏 + tty_capture ANSI 清洗
  *   B15. shell 集成（OSC 133 命令捕获/退出码 + OSC 7 cwd 跟随）
  *   B16. ~/.ssh/config 解析器
- *   B17. tty_expect 匹配与超时
+ *   B17. tty_expect 匹配与超时（含 D72：命令已结束后的回溯命中、回显不算命中）
  *   B18. data 帧合并后帧序不变量（exit 在最后一帧 data 之后）
  *   B19. known_hosts 解析器
  *   B20. 端口转发隧道（forwardOut 往返 + forwardIn 就绪 + 状态与工具）
@@ -38,6 +38,9 @@
  *        （不新建 PTY / 不占名额）、输出扇出、kill 广播 exit
  *   B29. 禁用热生效（enabled 开关）：工具/公告撤下与恢复、数据路由 403、
  *        /config 保持可读写、存量 WS 被关闭与新升级被拒
+ *   B34. 退出后的只读保留（D77）：命令跑完仍可读、写被拒、tty_close 释放
+ *   B35. `tty_open command=` 执行整段 shell 代码（D78）：`a; b` / `cd x && cmd` /
+ *        `for` 不被 exec 截断，退出码取自最后一条
  *
  * 用法：pnpm --filter @hyzyn/dsh-tty integration
  * 退出码：0 = 全部 PASS，1 = 任一 FAIL。
@@ -56,6 +59,15 @@ import { parseKnownHosts } from '../lib/known-hosts.js'
 import { assertSupportedJsonSchema, validateJsonSchemaValue } from '@deepseek-ai/dsh-tools'
 import { startSftpSshd, TEST_USER, TEST_PASSWORD } from './lib/test-sshd.mjs'
 
+/*
+ * 变更端点要求「同源证明」（docker D32 口径，见 docs/architecture.md § 7 与
+ * packages/tty/src/index.ts 的 gateRoute）：浏览器同源 fetch 必带
+ * `sec-fetch-site: same-origin`——本脚本模拟的正是**面板**这条调用路径，所以照带。
+ * 少了它，/probe 与 /sftp 的写动作会被 403「缺少同源证明」（本脚本此前就踩在这里）。
+ */
+const SAME_ORIGIN = { 'sec-fetch-site': 'same-origin' }
+
+
 
 /* 全局看门狗：任何环节卡死时留痕退出（正常路径会先 process.exit）。 */
 setTimeout(() => {
@@ -432,11 +444,11 @@ async function run() {
     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 res2 = await fetch(base, { method: 'POST', headers: { ...SAME_ORIGIN, '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 res3 = await fetch(base, { method: 'POST', headers: { ...SAME_ORIGIN, '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))
@@ -446,7 +458,7 @@ async function run() {
   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 fetch(base, { method: 'POST', headers: { ...SAME_ORIGIN, 'content-type': 'application/json' }, body: JSON.stringify({ maxSessions: 2 }) })
     await sleep(200)
     const s1 = openSession(port)
     await s1.open()
@@ -474,7 +486,7 @@ async function run() {
     s1.client.close()
     s2.client.close()
     s3.client.close()
-    await fetch(base, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ maxSessions: 4 }) })
+    await fetch(base, { method: 'POST', headers: { ...SAME_ORIGIN, 'content-type': 'application/json' }, body: JSON.stringify({ maxSessions: 4 }) })
   }
 
   // B12: agent 工具集（tty_list / tty_capture / tty_send）
@@ -732,6 +744,29 @@ async function run() {
       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))
+
+      // B17c（D72）：命令**早已跑完**（输出到达发生在注册之前）时也要回溯命中。
+      // 真实场景就是 AI 无法预测命令耗时：`tty_send` 与 `tty_expect` 之间隔着一次
+      // 模型推理，命令若在这个窗口里跑完，旧实现只能白等满超时并返回空文本。
+      // 这里刻意「先等输出落地、再注册」，把那个窗口显式做出来。
+      s.client.send(JSON.stringify({ t: 'input', sid: 'ex-1', d: 'printf "BACKFILL_%s\\n" MARK\n' }))
+      await s.waitFor(() => /BACKFILL_MARK/.test(s.state.text), 10000, 'BACKFILL_MARK 输出')
+      await sleep(500) // 等 D 标记与 prompt 落定：注册这一刻命令已经结束
+      const backStarted = Date.now()
+      const backResult = await expect.execute({ sid: 'ex-1', pattern: 'BACKFILL_MARK', timeoutSec: 8 })
+      const backElapsed = Date.now() - backStarted
+      // matchedFrom 必须是回溯（last = 上一条命令的输出 / buffered = 未读缓冲）：
+      // 若回成 live，说明它是注册之后才到的，这条用例就没有意义了
+      if (backResult.matched === true && backResult.matchedFrom !== undefined && backResult.matchedFrom !== 'live' && backElapsed < 2000) pass(`B17c 命令已结束后注册仍回溯命中（matchedFrom=${backResult.matchedFrom}，${backElapsed}ms）`)
+      else fail('B17c 命令已结束后注册仍回溯命中', JSON.stringify(backResult).slice(0, 160) + ` elapsed=${backElapsed}ms`)
+
+      // B17d（D72）：回显**不算**命中。上面那条命令的回显里带着 BACKFILL_%s（输出是
+      // BACKFILL_MARK），它落在 shell 集成的 A..B 之间——真实 zsh / bash 是否真的如此，
+      // 是「用 A..B 边界去回显」这个设计唯一没法在单测里自证的前提（单测的标记是
+      // 自己造的，属循环论证），所以在这里拿真 shell 钉一次。
+      const echoResult = await expect.execute({ sid: 'ex-1', pattern: 'BACKFILL_%s', timeoutSec: 1 })
+      if (echoResult.matched === false && echoResult.timedOut === true) pass('B17d 回显里的字样不算命中（A..B 边界在真 shell 上成立）')
+      else fail('B17d 回显里的字样不算命中（A..B 边界在真 shell 上成立）', JSON.stringify(echoResult).slice(0, 160) + '（若本机 shell 未启用集成，这是降级语义而非回归）')
     }
     s.client.send(JSON.stringify({ t: 'kill', sid: 'ex-1' }))
     await s.waitFor(() => s.state.exited !== null, 10000, 'ex-1 exit')
@@ -858,7 +893,7 @@ async function run() {
     })
     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) })
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { ...SAME_ORIGIN, 'content-type': 'application/json' }, body: JSON.stringify(body) })
       return res.json()
     }
     const put = await post({
@@ -944,7 +979,7 @@ async function run() {
     } else {
       await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, {
         method: 'POST',
-        headers: { 'content-type': 'application/json' },
+        headers: { ...SAME_ORIGIN, 'content-type': 'application/json' },
         body: JSON.stringify({ shell: '/bin/bash' }),
       })
       const s = openSession(port)
@@ -995,7 +1030,7 @@ async function run() {
     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) })
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { ...SAME_ORIGIN, '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 }] })
@@ -1006,7 +1041,7 @@ async function run() {
     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' },
+        headers: { ...SAME_ORIGIN, 'content-type': 'application/json' },
         body: JSON.stringify({ name: 'b23-ssh', ...payload }),
       })
       const data = await res.json().catch(() => ({}))
@@ -1027,7 +1062,7 @@ async function run() {
     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') },
+      headers: { ...SAME_ORIGIN, '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(() => ({}))
@@ -1046,7 +1081,7 @@ async function run() {
     // 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' },
+      headers: { ...SAME_ORIGIN, 'content-type': 'application/json' },
       body: JSON.stringify({ name: 'b23-ssh', path: rootDir + '/b23dir/up.bin' }),
     })
     const dlBuf = Buffer.from(await dl.arrayBuffer())
@@ -1109,7 +1144,7 @@ async function run() {
     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) })
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { ...SAME_ORIGIN, '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 }] })
@@ -1221,7 +1256,7 @@ async function run() {
       return tmuxListError !== null ? [] : 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) })
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { ...SAME_ORIGIN, 'content-type': 'application/json' }, body: JSON.stringify(body) })
       return res.json()
     }
     const probe = await execFileP('tmux', ['-V'])
@@ -1397,7 +1432,7 @@ async function run() {
   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) })
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { ...SAME_ORIGIN, 'content-type': 'application/json' }, body: JSON.stringify(body) })
       return res.json()
     }
     await post({ persistence: 'tmux' })
@@ -1437,7 +1472,7 @@ async function run() {
     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' },
+        headers: { ...SAME_ORIGIN, 'content-type': 'application/json' },
         body: JSON.stringify(body),
       })
       return res.json()
@@ -1500,7 +1535,7 @@ async function run() {
   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) })
+      const res = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/config`, { method: 'POST', headers: { ...SAME_ORIGIN, 'content-type': 'application/json' }, body: JSON.stringify(body) })
       return { status: res.status, body: await res.json() }
     }
 
@@ -1516,7 +1551,7 @@ async function run() {
     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' }) })
+    const probeRes = await fetch(`http://127.0.0.1:${port}/api/dsh-tty/probe`, { method: 'POST', headers: { ...SAME_ORIGIN, '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`)
@@ -1616,7 +1651,7 @@ async function run() {
     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) })
+      const res = await fetch('http://127.0.0.1:' + String(port) + '/api/dsh-tty/config', { method: 'POST', headers: { ...SAME_ORIGIN, '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 }] })
@@ -1741,7 +1776,7 @@ async function run() {
     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) })
+      const res = await fetch('http://127.0.0.1:' + String(port) + '/api/dsh-tty/config', { method: 'POST', headers: { ...SAME_ORIGIN, '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 }] })
@@ -1864,12 +1899,140 @@ async function run() {
     }
   }
 
+  // B34: 退出后的只读保留（D77，用户上报 issue #4 的正题）
+  //
+  // 现场：`tty_open` 跑一条**会结束**的命令，跑完会话就退役——输出还在终端上，
+  // AI 一个字符都取不回来（用户被迫先开 `/bin/sh` 再往里塞命令）。这一条用真 PTY
+  // 走一遍修好之后的链路：命令跑完 → 清单里仍有它（exited）→ tty_capture 读得到
+  // 输出 → tty_send 拒写 → tty_close 释放。
+  console.log('\n[31] 退出后的只读保留（D77）')
+  {
+    const open77 = toolDefs.find((d) => d.name === 'tty_open')
+    const close77 = toolDefs.find((d) => d.name === 'tty_close')
+    const list77 = toolDefs.find((d) => d.name === 'tty_list')
+    const capture77 = toolDefs.find((d) => d.name === 'tty_capture')
+    const send77 = toolDefs.find((d) => d.name === 'tty_send')
+    if (open77 === undefined || close77 === undefined || list77 === undefined || capture77 === undefined || send77 === undefined) {
+      fail('B34 D77 工具集', '缺工具: ' + toolDefs.map((d) => d.name).join(','))
+    } else {
+      const opened = await open77.execute({ cwd: '/tmp', command: 'printf "D77_%s\\n" RETAINED' })
+      const sid = opened.sid
+      // 命令瞬间跑完：等它转成只读保留态（清单里带 exited:true）
+      let entry = null
+      for (let i = 0; i < 40; i++) {
+        await sleep(150)
+        entry = ((await list77.execute({})).sessions ?? []).find((x) => x.sid === sid)
+        if (entry !== undefined && entry.exited === true) break
+      }
+      if (entry !== undefined && entry.exited === true && entry.retainMs === undefined) {
+        pass('B34a 命令退出后会话仍在清单里（exited:true，默认不按时间释放）')
+      } else {
+        fail('B34a 命令退出后会话仍在清单里', JSON.stringify(entry))
+      }
+
+      const read = await capture77.execute({ sid, lines: 100 })
+      if (read.exited === true && String(read.tail).includes('D77_RETAINED')) {
+        pass('B34b tty_capture 读得到退出前的输出（带 exited 标记）')
+      } else {
+        fail('B34b tty_capture 读得到退出前的输出', JSON.stringify(read).slice(0, 160))
+      }
+
+      let refused = false
+      try {
+        await send77.execute({ sid, data: 'echo nope\n' })
+      } catch {
+        refused = true
+      }
+      if (refused) pass('B34c tty_send 对只读保留态明确拒写')
+      else fail('B34c tty_send 对只读保留态明确拒写', '居然写进去了')
+
+      const closed = await close77.execute({ sid })
+      const gone = !((await list77.execute({})).sessions ?? []).some((x) => x.sid === sid)
+      if (closed.ok === true && gone) pass('B34d tty_close 释放保留态（关掉后从清单消失）')
+      else fail('B34d tty_close 释放保留态', `ok=${String(closed.ok)} gone=${String(gone)}`)
+    }
+  }
+
+  // B35: `tty_open command=` 执行的是**整段 shell 代码**（D78）
+  //
+  // 旧实现把用户命令直接缀在 `exec` 后面——`exec` 只作用于简单命令，于是
+  // `echo A; echo B` 只跑 A、`cd /tmp && pwd` 空输出、`echo X; exit 3` 报 0、
+  // `for …` 直接 parse error（2026-09-27 报告）。这里用真 PTY 钉住五条形态，
+  // 判据取「后半段的输出真的出现了」+「退出码取自最后一条」。
+  console.log('\n[32] `command` 按 shell 语法整体执行（D78）')
+  {
+    const open = toolDefs.find((d) => d.name === 'tty_open')
+    const close = toolDefs.find((d) => d.name === 'tty_close')
+    const list = toolDefs.find((d) => d.name === 'tty_list')
+    const capture = toolDefs.find((d) => d.name === 'tty_capture')
+    if (open === undefined || close === undefined || list === undefined || capture === undefined) {
+      fail('B35 D78 工具集', '缺工具: ' + toolDefs.map((d) => d.name).join(','))
+    } else {
+      /** 开一条命令会话并等它转成只读保留态（命令跑完），返回 { sid, entry }。 */
+      const openAndSettle = async (command) => {
+        const opened = await open.execute({ cwd: '/tmp', command })
+        for (let i = 0; i < 80; i++) {
+          await sleep(150)
+          const entry = ((await list.execute({})).sessions ?? []).find((x) => x.sid === opened.sid) ?? null
+          if (entry !== null && entry.exited === true) return { sid: opened.sid, entry }
+        }
+        return { sid: opened.sid, entry: null }
+      }
+      const readTail = async (sid) => String((await capture.execute({ sid, lines: 80 })).tail ?? '')
+      const opened = []
+      try {
+        // ① `a; b`：旧实现只跑第一条
+        const semi = await openAndSettle('echo A; echo B; echo C; echo D')
+        opened.push(semi.sid)
+        const semiTail = await readTail(semi.sid)
+        if (['A', 'B', 'C', 'D'].every((m) => semiTail.includes(m))) pass('B35a 分号列表整段执行（A/B/C/D 都在）')
+        else fail('B35a 分号列表整段执行', JSON.stringify(semiTail).slice(0, 160))
+
+        // ② `cd x && cmd`：agent 最惯用的写法，旧实现空输出
+        const and = await openAndSettle('cd /tmp && pwd')
+        opened.push(and.sid)
+        const andTail = await readTail(and.sid)
+        if (andTail.includes('/tmp')) pass('B35b `cd && cmd` 完整执行（拿到 /tmp）')
+        else fail('B35b `cd && cmd` 完整执行', JSON.stringify(andTail).slice(0, 160))
+
+        // ③ 退出码取自命令列表最后一条（旧实现取被 exec 的第一条）
+        const rc = await openAndSettle('echo X; exit 3')
+        opened.push(rc.sid)
+        if (rc.entry !== null && rc.entry.exitCode === 3) pass('B35c 退出码取自最后一条（echo X; exit 3 → exitCode=3）')
+        else fail('B35c 退出码取自最后一条', JSON.stringify(rc.entry))
+
+        // ④ 复合语句（for）不再 parse error
+        const loop = await openAndSettle('for i in 1 2 3; do echo L$i; done')
+        opened.push(loop.sid)
+        const loopTail = await readTail(loop.sid)
+        if (['L1', 'L2', 'L3'].every((m) => loopTail.includes(m))) pass('B35d `for …; do …; done` 整段执行（L1/L2/L3 都在）')
+        else fail('B35d `for …` 整段执行', JSON.stringify(loopTail).slice(0, 200))
+
+        // ⑤ 命令里的单引号安全穿过包装层
+        const quoted = await openAndSettle("echo 'QUOTED-OK'")
+        opened.push(quoted.sid)
+        const quotedTail = await readTail(quoted.sid)
+        if (quotedTail.includes('QUOTED-OK')) pass("B35e 命令内的单引号不被包装层吃掉（echo 'QUOTED-OK'）")
+        else fail('B35e 命令内的单引号', JSON.stringify(quotedTail).slice(0, 160))
+      } catch (error) {
+        fail('B35 D78 `command` 按 shell 语法整体执行', error.message)
+      }
+      for (const sid of opened) {
+        try {
+          await close.execute({ sid })
+        } catch {
+          /* 已释放 */
+        }
+      }
+    }
+  }
+
   // B33: 输出契约（所有已调用工具的真实返回值都符合各自声明的 output.schema）
   //
   // 这一条是 §B12e 的补充：B12e 只证明 schema 形状受支持，证明不了返回值合法。
   // 真实宿主对输出做 additionalProperties:false 校验，违约会直接把工具调用变成
   // Error（tty_list 加 owner 漏改 schema 即此）。
-  console.log('\n[31] 输出契约')
+  console.log('\n[33] 输出契约')
   {
     if (outputViolations.length === 0) pass('B33 工具返回值符合声明的 output.schema')
     else fail('B33 工具返回值符合声明的 output.schema', outputViolations.slice(0, 3).join(' | '))

package/scripts/jump-smoke.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * @hyzyn/dsh-tty — 跳板机（ProxyJump 单跳）的真机冒烟。
+ *
+ * 为什么必须真机跑一遍：`forwardOut → ConnectConfig.sock` 这条链路的正确性**不可能**靠单测
+ * 证明——假 ssh2 只能验「谁先连、config 长什么样」，而「通道真的把字节送到了另一台 sshd、
+ * 目标在通道上完成了握手并开了 SFTP 通道」只有真实现才能给。本脚本起**两个真的 ssh2 服务端**：
+ *
+ *   - bastion：接受密码认证，并处理 `direct-tcpip`（把通道接到目标端口）；
+ *   - target：`scripts/lib/test-sshd.mjs` 的内存 SFTP 服务端。
+ *
+ * **两者的凭据刻意不同**（bastion: jump/jump-secret，target: test/secret）：这样「跳板机凭据
+ * 没被目标凭据顶掉」也能一并验到——那正是 `jumpSpecOf` 的继承规则最容易写错的地方。
+ *
+ * 三个用例：
+ *   J1 经跳板机列 SFTP 目录（正向：通道 + 目标握手 + 通道建立）
+ *   J2 跳板机密码错 → 文案点名**跳板机**（而不是笼统的目标超时）
+ *   J3 通道通了但目标不可达 → 文案同时点名目标与**经跳板机 X**（两跳归属不能混）
+ *
+ * 退出码：全部 PASS → 0；任一 FAIL → 1（CI 与发布闸都跑它）。
+ */
+import net from 'node:net'
+import os from 'node:os'
+import path from 'node:path'
+import fsp from 'node:fs/promises'
+import ssh2 from 'ssh2'
+import { generateKeyPairSync } from 'node:crypto'
+import { SftpManager } from '../lib/sftp.js'
+import { startSftpSshd } from './lib/test-sshd.mjs'
+
+const BASTION_USER = 'jump'
+const BASTION_PASSWORD = 'jump-secret'
+
+let failed = 0
+function pass(name) {
+  console.log(`  ✔ PASS  ${name}`)
+}
+function fail(name, detail) {
+  failed += 1
+  console.log(`  ✘ FAIL  ${name}${detail === undefined ? '' : ` — ${detail}`}`)
+}
+
+/** 起一个「能当跳板机」的 sshd：密码认证 + `direct-tcpip` 转发到目标端口。 */
+async function startBastion() {
+  const { privateKey } = generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs1', format: 'pem' },
+  })
+  /** 观测量：建了几条连接、开了几条转发通道（用例里断言「确实过了跳板机」）。 */
+  const seen = { connections: 0, forwards: 0, closed: 0 }
+  const server = new ssh2.Server({ hostKeys: [privateKey] }, (client) => {
+    seen.connections += 1
+    client.on('authentication', (ctx) => {
+      if (ctx.method === 'password' && ctx.username === BASTION_USER && ctx.password === BASTION_PASSWORD) {
+        ctx.accept()
+        return
+      }
+      ctx.reject()
+    })
+    client.on('ready', () => {
+      // direct-tcpip：这就是 forwardOut 落在服务端的那一半
+      client.on('tcpip', (accept, reject, info) => {
+        seen.forwards += 1
+        const channel = accept()
+        const socket = net.connect(info.destPort, info.destIP)
+        socket.on('connect', () => {
+          channel.pipe(socket).pipe(channel)
+        })
+        socket.on('error', () => {
+          try {
+            channel.close()
+          } catch {
+            /* 已关闭 */
+          }
+        })
+        channel.on('close', () => socket.destroy())
+      })
+    })
+    client.on('close', () => {
+      seen.closed += 1
+    })
+    client.on('error', () => {
+      /* 认证失败 / 断开：用例自己断言 */
+    })
+  })
+  await new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => resolve())
+  })
+  const port = server.address().port
+  return {
+    port,
+    seen,
+    close: () => new Promise((resolve) => server.close(() => resolve())),
+  }
+}
+
+const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'dsh-tty-jump-'))
+await fsp.writeFile(path.join(root, 'hello.txt'), 'via bastion\n')
+
+const bastion = await startBastion()
+const target = await startSftpSshd({ rootDir: root })
+
+/** 经跳板机连目标的规格（凭据刻意不同：bastion 用 jump/jump-secret）。 */
+const specWithJump = (jumpOverride = {}) => ({
+  host: '127.0.0.1',
+  port: target.port,
+  username: 'test',
+  auth: 'password',
+  password: 'secret',
+  jump: { host: '127.0.0.1', port: bastion.port, username: BASTION_USER, auth: 'password', password: BASTION_PASSWORD, ...jumpOverride },
+})
+
+const sftp = new SftpManager({ info: () => {}, warn: () => {} })
+
+try {
+  // ---- J1：正向。SFTP 的 list 要经跳板机通道到达目标 ----
+  try {
+    const listed = await sftp.list(specWithJump(), root)
+    const names = listed.entries.map((entry) => entry.name)
+    if (names.includes('hello.txt') && bastion.seen.forwards >= 1) {
+      pass(`J1 经跳板机列 SFTP 目录（跳板机转发 ${bastion.seen.forwards} 次，目标 ${names.length} 项）`)
+    } else {
+      fail('J1 经跳板机列 SFTP 目录', `files=${JSON.stringify(names)} forwards=${bastion.seen.forwards}`)
+    }
+  } catch (error) {
+    fail('J1 经跳板机列 SFTP 目录', error instanceof Error ? error.message : String(error))
+  }
+
+  // ---- J2：跳板机密码错 → 必须点名跳板机 ----
+  try {
+    await sftp.list(specWithJump({ password: 'wrong' }), root)
+    fail('J2 跳板机密码错', '竟然没报错')
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (message.includes('跳板机') && message.includes(`${BASTION_USER}@127.0.0.1:${String(bastion.port)}`)) {
+      pass('J2 跳板机密码错 → 文案点名跳板机')
+    } else {
+      fail('J2 跳板机密码错 → 文案点名跳板机', message)
+    }
+  }
+
+  // ---- J3：通道通了但目标不可达 → 目标与「经跳板机 X」都要出现 ----
+  try {
+    const deadPort = target.port + 1
+    // 指向一个没人监听的端口：bastion 的 net.connect 会成功（本机 127.0.0.1），
+    // 但通道上的目标握手会失败
+    await sftp.list({ ...specWithJump(), port: deadPort }, root)
+    fail('J3 通道通了但目标不可达', '竟然没报错')
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (message.includes('经跳板机') && message.includes('127.0.0.1')) {
+      pass('J3 目标不可达 → 文案同时点名目标与跳板机')
+    } else {
+      fail('J3 目标不可达 → 文案同时点名目标与跳板机', message)
+    }
+  }
+
+  // ---- 清理：跳板机连接必须被关掉（不留 keepalive 养着的连接） ----
+  await sftp.disposeAll()
+  await new Promise((resolve) => setTimeout(resolve, 200))
+  if (bastion.seen.closed >= bastion.seen.connections) {
+    pass(`J4 收尾后跳板机连接全部关闭（${bastion.seen.closed}/${bastion.seen.connections}）`)
+  } else {
+    fail('J4 收尾后跳板机连接全部关闭', `closed=${bastion.seen.closed} opened=${bastion.seen.connections}`)
+  }
+} finally {
+  await bastion.close().catch(() => {})
+  await target.close().catch(() => {})
+  await fsp.rm(root, { recursive: true, force: true }).catch(() => {})
+}
+
+console.log(failed === 0 ? '\njump smoke: 全部 PASS' : `\njump smoke: ${failed} 个 FAIL`)
+process.exit(failed === 0 ? 0 : 1)

package/scripts/lib/proxy-bridge.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * 最小 `ProxyCommand` 桥：把 stdio 接到 `host port`。
+ *
+ * 这就是 `ssh -W %h:%p bastion` / `nc host port` 的原语，写成脚本是为了**不依赖系统工具**
+ * （CI 上未必有 ssh / nc，参数还各不相同）。真机冒烟 `scripts/proxycommand-smoke.mjs` 用它
+ * 当代理命令，从而把「子进程 stdio ↔ SSH 传输」这条链路整条跑通。
+ *
+ * 用法：node proxy-bridge.mjs <host> <port>
+ */
+import net from 'node:net'
+
+const [host, port] = process.argv.slice(2)
+if (host === undefined || port === undefined) {
+  process.stderr.write('usage: proxy-bridge.mjs <host> <port>\n')
+  process.exit(2)
+}
+
+const socket = net.connect(Number(port), host)
+socket.on('connect', () => {
+  process.stdin.pipe(socket)
+  socket.pipe(process.stdout)
+})
+socket.on('error', (error) => {
+  process.stderr.write(`${error.message}\n`)
+  process.exit(1)
+})
+socket.on('close', () => {
+  process.exit(0)
+})