@hyzyn/dsh-tty 0.27.0 → 0.30.0

package/scripts/preview/harness.js

@@ -183,6 +183,12 @@
     const s = socket()
     if (s) s._deliver(msg)
   }
+  /**
+   * 造一帧 `sessions`（宿主视角的会话表）——给需要**逐帧改变**清单的场景用（#7④：先有这条
+   * agent 会话、下一帧它出表）。基准表来自 mock 宿主自己的会话表（`__mockSessionList`），
+   * 不要在场景里拿客户端标签推算：那等于用被测对象造夹具。
+   */
+  const sessionList = (extra = []) => window.__mockSessionList().concat(extra)
 
   const openPanel = async () => {
     await waitFor(() => entry())
@@ -497,6 +503,25 @@
       if (endpointCount !== 2) throw new Error('端点组数不为 2：' + String(endpointCount))
       if (document.querySelector('#preview-settings .tt_tunnelArrow') === null) throw new Error('缺少方向箭头')
 
+      /*
+       * 端点组的几何（用户两张截图的正题：「输入框的样式优化一下」）：**贴合内容**——
+       * 组宽 ≈ 组内孩子宽度之和。原先是 `flex: 1 1 190px`，宽卡片里左组被抻到几百像素
+       * （端口框后面一片组内死区），右组的 host 又吃掉全部余量、把冒号 + 端口顶到卡片右缘
+       * （离「服务器侧主机」占位符几百像素）。
+       *
+       * 聚焦环那条**不在这里判**：headless 里 `document.hasFocus()` 是 false，`:focus` 压根
+       * 不匹配（实测 mFocus=false、:focus-within 照常匹配），所以「内层输入有没有自己画环」
+       * 在这一层恒为 none——那种恒绿的断言比没有更坏。它由 test/tunnel-endpoint.test.ts 从
+       * CSS 源上钉（内层 box-shadow: none + 组上 :focus-within 有环，两条成对）。
+       *
+       * 量成纯数字存下来——方向切换会重渲表单、DOM 引用会失效。
+       */
+      const endpointGroups = [...document.querySelectorAll('#preview-settings .tt_tunnelEndpoint')]
+      const endpointSlack = endpointGroups.map((group) => {
+        const inner = [...group.children].reduce((n, el) => n + el.getBoundingClientRect().width, 0)
+        return group.getBoundingClientRect().width - inner
+      })
+
       // 分段控件：本地/远程可切换，当前项高亮
       const segBtns = [...document.querySelectorAll('#preview-settings .tt_segmentedBtn')]
       if (segBtns.length !== 2) throw new Error('分段控件按钮数不为 2：' + String(segBtns.length))
@@ -607,6 +632,18 @@
         if (!names.some((n) => n.startsWith('prod-redis'))) {
           problems.push('编辑波及了别的隧道')
         }
+        /*
+         * 端点组：贴合内容（不许抻出组内死区）。判据与采集处的注释同源；聚焦环那两条见
+         * test/tunnel-endpoint.test.ts（headless 里判不了）。
+         */
+        if (endpointSlack.length !== 2) {
+          problems.push('夹具失效：端点组数不是 2（实测 ' + String(endpointSlack.length) + '）')
+        }
+        for (const slack of endpointSlack) {
+          if (slack > 2.5) {
+            problems.push('端点组没有贴合内容（组内死区 ' + String(Math.round(slack)) + 'px）——用户实测现场')
+          }
+        }
         if (buttonsIn(document.querySelector('#preview-settings .tt_cardBody')).find((b) => saysExact(b, '添加隧道', 'Add tunnel')) === undefined) {
           problems.push('保存后没有退出编辑态')
         }
@@ -739,6 +776,9 @@
       let defaultLabel = ''
       let defaultCleared = ''
       let labelsRepeatId = false
+      // 「保存」按钮是**两张候选表共用**的布局标尺（都用它量「打开候选表有没有把卡片顶动」），
+      // 所以定义提到这里，别在各自的块里各找一次
+      const saveBtn = qa('.tt_cardSave').find((el) => saysExact(el, '保存', 'Save'))
       if (routeInput !== null) {
         // ① 挂载时目录取不到（夹具预先置了 __PREVIEW_CATALOG.fail）
         routeInput.click()
@@ -746,7 +786,6 @@
         unavailableText = routeField.textContent
         // ② 目录恢复：再聚焦一次会重取（失败时 groups 仍为空，守卫放行）
         delete window.__PREVIEW_CATALOG
-        const saveBtn = qa('.tt_cardSave').find((el) => saysExact(el, '保存', 'Save'))
         const saveTopBefore = saveBtn === undefined ? null : saveBtn.getBoundingClientRect().top
         routeInput.click()
         await sleep(400)
@@ -779,6 +818,62 @@
         routeReadOnly = routeInput.readOnly
       }
 
+      /*
+       * Shell 路径的候选表：同一张卡片里的**第二张**候选表，同样必须是浮层。
+       *
+       * 用户截图现场就是内联版——输入框正下方多出一整块，把下面的字段整段推走（原话「这个选择会
+       * 挤占空间破坏布局」）。判据与模型路由一式一样：量「保存」按钮的位置有没有被顶动 + 候选表
+       * 的 computed position；再加两条行为断言——点一条要真的写进输入框、并进保存 payload。
+       */
+      const shellField = qa('.tt_cardField').find((el) => {
+        const label = el.querySelector('.tt_cardLabel')
+        return label !== null && (label.textContent.indexOf('Shell 路径') >= 0 || label.textContent.indexOf('Shell path') >= 0)
+      })
+      const shellInput = shellField === undefined ? null : shellField.querySelector('input.tt_cardInput')
+      const shellList = () => (shellField === undefined ? null : shellField.querySelector('.tt_shellList'))
+      let shellListPosition = ''
+      let shellShift = null
+      let shellShiftTyped = null
+      let shellRows = 0
+      let shellValueBefore = ''
+      let shellPickedItem = ''
+      let shellPicked = ''
+      let shellClosedAfterPick = null
+      if (shellInput !== null) {
+        shellValueBefore = shellInput.value
+        const shellTopBefore = saveBtn === undefined ? null : saveBtn.getBoundingClientRect().top
+        /*
+         * 用例 A：值已经是**完整路径**（`/bin/zsh`）——候选被这个值自己过滤成**同一行**
+         * （用户截图里就是这一幕：输入框下面孤零零一行 `/bin/zsh`）。
+         */
+        shellInput.click()
+        await sleep(300)
+        const listEl = shellList()
+        shellListPosition = listEl === null ? '' : window.getComputedStyle(listEl).position
+        const shellTopOpen = saveBtn === undefined ? null : saveBtn.getBoundingClientRect().top
+        shellShift = shellTopBefore === null || shellTopOpen === null ? null : shellTopOpen - shellTopBefore
+        /*
+         * 用例 B：打字过滤（`/bin/`）→ 候选变成 3 行、列表长高一大截。内联版正是**这里**把
+         * 下面的字段整段推走（列表越高推得越远），所以位移要在这一档再量一次。
+         */
+        setReactInput(shellInput, '/bin/')
+        await sleep(300)
+        const typedList = shellList()
+        shellRows = typedList === null ? 0 : typedList.querySelectorAll('.tt_envItem').length
+        const shellTopTyped = saveBtn === undefined ? null : saveBtn.getBoundingClientRect().top
+        shellShiftTyped = shellTopBefore === null || shellTopTyped === null ? null : shellTopTyped - shellTopBefore
+        // 挑一条与**聚焦前的值**不同的候选：值真的变了才证明「点一下写进去了」，而不是本来就长这样
+        const items = typedList === null ? [] : Array.from(typedList.querySelectorAll('.tt_envItem'))
+        const item = items.find((el) => el.textContent !== shellValueBefore) ?? null
+        if (item !== null) {
+          shellPickedItem = item.textContent
+          item.click()
+          await sleep(250)
+          shellPicked = shellInput.value
+          shellClosedAfterPick = shellList() === null
+        }
+      }
+
       const toggleBefore = qa('.tt_cardLabel').find((el) => says(el, '失败即解释', 'Explain failures'))
       const boxBefore = toggleBefore === undefined ? null : toggleBefore.parentElement.querySelector('input[type=checkbox]')
       const checkedByDefault = boxBefore === null ? null : boxBefore.checked
@@ -858,6 +953,28 @@
         if (postedPayload.assistProvider !== 'mock-provider' || postedPayload.assistModel !== 'mock-fast') {
           return '选中的那一对没进保存 payload：' + JSON.stringify([postedPayload.assistProvider, postedPayload.assistModel])
         }
+        // Shell 路径的候选表：同一张卡片里的第二张候选表，判据同模型路由（用户截图现场）
+        if (shellInput === null) return '设置卡片里没有「Shell 路径」控件'
+        if (shellShift === null || shellShiftTyped === null) return '夹具失效：量不到「保存」按钮的位置（Shell 路径那一栏）'
+        if (Math.abs(shellShift) > 0.5 || Math.abs(shellShiftTyped) > 0.5) {
+          return '打开 Shell 候选表把卡片布局顶动了 '
+            + String(Math.round(shellShift)) + 'px（同值一行）/ ' + String(Math.round(shellShiftTyped)) + 'px（过滤后 3 行）——用户实测现场'
+        }
+        if (shellListPosition !== 'fixed') {
+          return 'Shell 候选表不是浮层（会顶动卡片布局）：position=' + shellListPosition
+        }
+        if (shellRows < 2) return '夹具失效：打字过滤之后候选该有好几行，实测 ' + String(shellRows) + ' 行'
+        if (shellPickedItem === '') return '夹具失效：Shell 候选表里没有可点的候选'
+        if (shellPicked !== shellPickedItem) {
+          return '点 Shell 候选没有写进输入框：' + JSON.stringify([shellPickedItem, shellPicked])
+        }
+        if (shellPicked === shellValueBefore) {
+          return '点 Shell 候选之后值没变（这条断言证明不了「写入」）：' + JSON.stringify(shellPicked)
+        }
+        if (shellClosedAfterPick !== true) return '选中 Shell 候选之后候选表没有收起'
+        if (postedPayload.shell !== shellPicked) {
+          return '选中的 Shell 没进保存 payload：' + JSON.stringify([shellPicked, postedPayload.shell])
+        }
         // 路由是**一个**控件（渠道 + 模型一对）：两栏并列的旧形态不许回来
         const labels = qa('.tt_cardLabel').map((el) => el.textContent)
         const routeLabels = labels.filter((text) => text.indexOf('模型路由') >= 0 || text.indexOf('Model route') >= 0)
@@ -867,6 +984,46 @@
         return null
       }
     },
+    /*
+     * 设置卡片：Shell 路径的候选表（浮层）。
+     *
+     * 这个场景**只为出图**：把值改成 `/bin/` 让候选变成多行、留着列表打开截图。布局那几条判据
+     * 在 `settings-assist` 里（同一张卡片，量「保存」按钮的位移），这里给的是同一幕的肉眼版本——
+     * 用户上报的就是它（内联版会把这下面整段字段推走）。
+     */
+    async 'settings-shell'() {
+      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 list = document.createElement('ul')
+      list.style.cssText = 'display:flex;flex-direction:column;gap:12px;margin:0;padding:0'
+      host.appendChild(list)
+      const tty = cards.find((c) => c.spec.key === 'tty')
+      if (tty === undefined) throw new Error('未注册 tty 设置卡片')
+      const root = window.ReactDOM.createRoot(list)
+      root.render(window.React.createElement(tty.Component))
+      await waitFor(() => q('.tt_card'), 3000)
+      q('.tt_cardHeader').click()
+      await waitFor(() => q('.tt_cardBody'), 4000)
+      await sleep(400)
+      const field = qa('.tt_cardField').find((el) => {
+        const label = el.querySelector('.tt_cardLabel')
+        return label !== null && (label.textContent.indexOf('Shell 路径') >= 0 || label.textContent.indexOf('Shell path') >= 0)
+      })
+      const input = field === undefined ? null : field.querySelector('input.tt_cardInput')
+      if (input === null) throw new Error('设置卡片里没有「Shell 路径」控件')
+      // 先滚到这一栏再聚焦：滚动后浮层要跟着锚点重新定位（夹具顺带把那条路径也走一遍）
+      field.scrollIntoView({ block: 'center' })
+      await sleep(250)
+      input.click()
+      await sleep(250)
+      // 打字过滤走原生 setter + input 事件（直接赋值 React 读到的还是旧值）：候选从「同值一行」变 3 行
+      const desc = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')
+      desc.set.call(input, '/bin/')
+      input.dispatchEvent(new window.Event('input', { bubbles: true }))
+      await sleep(400)
+    },
     /* 设置卡片：docker 与 tty 并排（同一张 ul 里），核对两家的观感是否一致 */
     async 'settings-docker'() {
       const host = document.createElement('div')
@@ -1133,12 +1290,344 @@
       await waitFor(() => q('[data-dsh-tty-entry][data-minimized]'))
       await sleep(150)
     },
-    /* 会话退出遮罩 */
+    /*
+     * 会话退出：**不画遮罩** + 顶部提示条（issue #7①②）。
+     *
+     * 现场（用户截图）：agent 跑的每条命令都会落一个标签，退出后被一层铺满终端区的遮罩
+     * （inset:0 + 半透明底 + 模糊 + 整块可点）盖住——结果看不清、连选中复制都做不到，
+     * 用户的绕过手段是 F12 里把 `.tt_overlay` 藏掉。
+     *
+     * 断言四条（缺一条都是静默回归）：① 面板标签的退出遮罩是空的；② 顶部提示条出现且文案
+     * 是「已退出」；③ 条子真的把终端往下推了（`.tt_term` 的 top 偏移 ≥ 条高，否则第一行被盖）；
+     * ④ 条上有「重新打开」这颗按钮（原来那个入口是「点遮罩」，撤了遮罩就必须补上它）。
+     */
     async exited() {
       await openPanel()
       const el = activeTabEl()
       emit({ t: 'exit', sid: sidOf(el), code: 0 })
+      await sleep(250)
+      window.__previewAssert = async () => {
+        const term = qa('.tt_term').find((node) => node.style.display !== 'none')
+        if (term === undefined) return '夹具失效：没有可见的终端容器'
+        const overlay = term.querySelector('.tt_overlay')
+        if (overlay !== null && (overlay.textContent || '') !== '') {
+          return '退出态又画上了遮罩（输出会被挡住）：' + String(overlay.textContent)
+        }
+        const bar = q('.tt_exitBar')
+        if (bar === null || bar.hidden === true) return '退出提示条没出现（撤了遮罩就没人告诉用户会话已退出）'
+        if (!says(bar, '已退出', 'Exited')) return '提示条文案不对：' + String(bar.textContent)
+        const body = q('.tt_body')
+        const offset = Math.round(term.getBoundingClientRect().top - body.getBoundingClientRect().top)
+        if (offset < 24) return '提示条没让位：终端 top 偏移只有 ' + String(offset) + 'px'
+        if (bar.querySelector('.tt_exitBarBtn') === null) return '提示条上没有「重新打开」这颗按钮'
+        return null
+      }
+    },
+    /*
+     * #7③：「⋯」标签列表里的「清理已退出的标签」——**长什么样**。
+     *
+     * 现场：用户攒了 47 个已退出的标签，只能一个一个点标签上的 ✕。入口在「⋯」里，而那个
+     * 按钮此前**只在标签栏溢出时**才出现。这条钉「没溢出但有死标签时它也在」以及菜单里那
+     * 一行（截图要看清的就是它）；「点一下真的收走」在 `clean-exited-apply` 里做——
+     * 断言在截图**之前**跑，凡是会改界面的检查都不该放在断言里（截图会变成点完的样子）。
+     */
+    async 'clean-exited'() {
+      await openPanel()
+      // 造三个标签，退掉其中两个：留一条活会话，面板不会因为清理把自己关掉
+      for (let i = 0; i < 2; i += 1) {
+        await clickAdd()
+        await clickMenuItem('本地终端', 'Local terminal')
+        await waitFor(() => tabs().length === i + 2, 4000)
+      }
+      const all = tabs()
+      emit({ t: 'exit', sid: sidOf(all[1]), code: 0 })
+      emit({ t: 'exit', sid: sidOf(all[2]), code: 0 })
+      await sleep(250)
+      const more = q('.tt_tabMore')
+      if (more !== null && more.hidden !== true) {
+        more.click()
+        await waitFor(() => q('.tt_tabMenu'))
+        await sleep(120)
+      }
+      window.__previewAssert = async () => {
+        if (tabs().length !== 3) return '夹具失效：期望 3 个标签，实际 ' + String(tabs().length)
+        if (more === null || more.hidden === true) return '有已退出的标签时「⋯」没出现（清理入口够不着）'
+        const menu = q('.tt_tabMenu')
+        if (menu === null) return '「⋯」菜单没打开'
+        const row = qa('.tt_addMenuItem').find((el) => says(el, '清理已退出', 'Clean up exited'))
+        if (row === undefined) return '菜单里没有「清理已退出的标签」这一行'
+        if (!row.textContent.includes('2')) return '清理行没写明条数：' + String(row.textContent)
+        return null
+      }
+    },
+    /*
+     * #7③ 的功能面：点那一下真的把死标签收走，且「⋯」自己藏回去（没有死标签、也没溢出）。
+     * 断言只读（收集结果），界面动作全在场景体里——同 `clean-exited` 的理由。
+     */
+    async 'clean-exited-apply'() {
+      await openPanel()
+      for (let i = 0; i < 2; i += 1) {
+        await clickAdd()
+        await clickMenuItem('本地终端', 'Local terminal')
+        await waitFor(() => tabs().length === i + 2, 4000)
+      }
+      const all = tabs()
+      emit({ t: 'exit', sid: sidOf(all[1]), code: 0 })
+      emit({ t: 'exit', sid: sidOf(all[2]), code: 0 })
+      await sleep(250)
+      const more = q('.tt_tabMore')
+      if (more !== null) more.click()
+      await waitFor(() => q('.tt_tabMenu'))
+      await sleep(120)
+      const row = await waitFor(() => qa('.tt_addMenuItem').find((el) => says(el, '清理已退出', 'Clean up exited')))
+      row.click()
+      await sleep(300)
+      const state = { tabs: tabs().length, moreHidden: more === null ? null : more.hidden === true, menu: q('.tt_tabMenu') !== null }
+      window.__previewAssert = async () => {
+        if (state.tabs !== 1) return '清理没生效：还剩 ' + String(state.tabs) + ' 个标签'
+        if (state.menu) return '清理后菜单还挂着'
+        if (state.moreHidden === false) return '死标签清完了，「⋯」没藏回去'
+        return null
+      }
+    },
+    /*
+     * #7④：AI 显式释放会话 → 标签跟着走。
+     *
+     * 判据是「宿主表里还有没有这一条」（agent 的 tty_close / tty_run 收尾会让它出表），
+     * 而不是「进程退没退出」——只读保留（exited: true）的那种要**留着可读**。
+     *
+     * 两条路一起钉：后台的 agent 标签当场收走；**正在看的**那一条先留一台阶（提示条写
+     * 「AI 已结束这个会话」），切走时再收。反向验证：把 `holdReleasedTab` 摘掉 → 第一条红；
+     * 把「出表」也当只读保留 → 第二条红（标签不会消失）。
+     */
+    async 'agent-release'() {
+      await openPanel()
+      await waitFor(() => tabs().length === 1, 4000)
+      const agentOf = (sid) => ({ sid, owner: 'agent', kind: 'local', cwd: window.__PREVIEW_CWD, attachable: true })
+      // ① 后台的 agent 标签：宿主推的会话清单里多一条 owner:'agent'
+      emit({ t: 'sessions', list: sessionList([agentOf('agent-bg')]) })
+      await waitFor(() => tabs().length === 2, 4000)
+      await sleep(200)
+      // AI 释放它（宿主表里撤掉）→ 后台标签应当当场消失
+      emit({ t: 'sessions', list: sessionList() })
+      await sleep(300)
+      const bgClosed = qa('.tt_tab').every((el) => sidOf(el) !== 'agent-bg')
+      // ② 正在看的那一条：再开一条 agent 会话，切到它，然后释放
+      emit({ t: 'sessions', list: sessionList([agentOf('agent-watch')]) })
+      await waitFor(() => qa('.tt_tab').some((el) => sidOf(el) === 'agent-watch'), 4000)
+      qa('.tt_tab').find((el) => sidOf(el) === 'agent-watch').click()
+      await sleep(200)
+      emit({ t: 'sessions', list: sessionList() })
+      await sleep(300)
+      const held = {
+        count: tabs().length,
+        stillThere: qa('.tt_tab').some((el) => sidOf(el) === 'agent-watch'),
+        text: q('.tt_exitBar') === null ? '' : String(q('.tt_exitBar').textContent),
+      }
+      // ③ 切走 → 台阶结束，标签被收走
+      const other = qa('.tt_tab').find((el) => sidOf(el) !== 'agent-watch')
+      if (other !== undefined) other.click()
+      await sleep(300)
+      const closedOnSwitch = !qa('.tt_tab').some((el) => sidOf(el) === 'agent-watch')
+      /*
+       * ④ 再走一遍，把「AI 已结束这个会话 + 收起」的样子留给截图（截图在断言之后拍，
+       * 断言又必须只读——所以要在场景体里把界面弄成要拍的样子，不能等断言去点）。
+       */
+      emit({ t: 'sessions', list: sessionList([agentOf('agent-shot')]) })
+      await waitFor(() => qa('.tt_tab').some((el) => sidOf(el) === 'agent-shot'), 4000)
+      qa('.tt_tab').find((el) => sidOf(el) === 'agent-shot').click()
       await sleep(200)
+      emit({ t: 'sessions', list: sessionList() })
+      await sleep(300)
+      const shotState = {
+        tabs: tabs().length,
+        text: q('.tt_exitBar') === null ? '' : String(q('.tt_exitBar').textContent),
+        dismiss: q('.tt_exitBarBtn') === null ? '' : String(q('.tt_exitBarBtn').textContent),
+      }
+      window.__previewAssert = async () => {
+        if (!bgClosed) return '后台的 agent 标签没被收走（AI 释放后还留着）'
+        if (!held.stillThere || held.count !== 2) return '正在看的 agent 标签被当场收走了（少了那一步台阶）'
+        if (!held.text.includes('AI 已结束') && !held.text.includes('The AI finished')) {
+          return '提示条没说明「AI 已结束这个会话」：' + held.text
+        }
+        if (!closedOnSwitch) return '切走之后台阶没结束：标签还在'
+        if (!shotState.text.includes('AI 已结束') && !shotState.text.includes('The AI finished')) {
+          return '台阶态的提示条文案不对：' + shotState.text
+        }
+        if (!/收起|Dismiss/.test(shotState.dismiss)) return '台阶态没有「收起」这颗按钮：' + shotState.dismiss
+        return null
+      }
+    },
+    /*
+     * 4b 现场回归（2026-10-10 真机验收）：**客户端自己顶上去的活动标签不算「正在看」**。
+     *
+     * 现场：AI 在后台开了一条 `sleep 300`，随即 `tty_close`；工具侧确实没有这条会话了，
+     * 可标签栏里还留着它——「标签退出了，但是还在」。根因不在删除逻辑，而在台阶的判据：
+     * 那一刻它的 `sid === activeSid` 成立（客户端自己把它顶成了活动标签：关掉一个标签时
+     * `closeTab` 会选一个邻居、`adoptAgentSessions` 在没有活动标签时也会切过去），于是走
+     * 了「AI 已结束这个会话 + 收起」那条保留分支。
+     *
+     * 修法：台阶只认**用户自己切过**的标签（`switchTab(sid, { user: true })` 打的
+     * `watched` 标记）。本场景正是那条路：先让关标签的「邻居选择」把 agent 标签顶成活动
+     * 标签（没有用户点击），再释放它——**必须直接收走**。
+     * 反向验证：把 `holdReleasedTab` 里的 `tab.watched !== true` 去掉 → 本场景红。
+     */
+    async 'agent-release-neighbor'() {
+      await openPanel()
+      // 再开一个用户标签（两个用户标签 + 一个后台 agent 标签，面板不会因为清空而关掉）
+      await clickAdd()
+      await clickMenuItem('本地终端', 'Local terminal')
+      await waitFor(() => tabs().length === 2, 4000)
+      const agentOf = (sid) => ({ sid, owner: 'agent', kind: 'local', cwd: window.__PREVIEW_CWD, attachable: true })
+      emit({ t: 'sessions', list: sessionList([agentOf('agent-nb')]) })
+      await waitFor(() => qa('.tt_tab').some((el) => sidOf(el) === 'agent-nb'), 4000)
+      await sleep(200)
+      const adopted = {
+        tabs: tabs().length,
+        agentIsActive: sidOf(activeTabEl()) === 'agent-nb',
+      }
+      // 关掉当前活动标签：closeTab 会选「最后一个标签」当邻居 = 刚采纳的 agent 标签
+      const activeClose = activeTabEl().querySelector('.tt_tabClose')
+      activeClose.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+      await sleep(250)
+      const promoted = {
+        active: sidOf(activeTabEl()),
+        tabs: tabs().length,
+      }
+      // AI 释放它（宿主表里撤掉）→ 必须直接收走，不能留台阶
+      emit({ t: 'sessions', list: sessionList() })
+      await sleep(350)
+      window.__previewAssert = async () => {
+        if (adopted.tabs !== 3) return '夹具失效：期望 3 个标签，实际 ' + String(adopted.tabs)
+        if (adopted.agentIsActive) return '夹具失效：agent 标签一开始就该在后台'
+        if (promoted.active !== 'agent-nb') return '夹具失效：关标签的邻居选择没把 agent 标签顶成活动标签（' + String(promoted.active) + '）'
+        if (qa('.tt_tab').some((el) => sidOf(el) === 'agent-nb')) {
+          return 'AI 释放的是**客户端自己顶上去**的活动标签，标签却留下了（4b 现场：标签退出了但还在）'
+        }
+        const bar = q('.tt_exitBar')
+        if (bar !== null && bar.hidden !== true && says(bar, 'AI 已结束', 'The AI finished')) {
+          return '错误地走了「AI 已结束 + 收起」的保留分支'
+        }
+        if (tabs().length !== 1) return '收走之后标签数不对：' + String(tabs().length)
+        return null
+      }
+    },
+    /*
+     * issue #8：点 ✕ 关面板时，有活会话就先问一句。
+     *
+     * 判据是「这一下会结束几条**活会话**」，不是「开了几个标签」：本场景只有一条活会话
+     * 也必须问；而「只剩已退出的标签」时不该问（那条由 `close-confirm-empty` 钉）。
+     * 「取消不关面板 / 不结束会话」这一段在场景体里做（断言必须只读：它跑在截图之前，
+     * 在断言里点掉确认会让截图变成点完的样子）。
+     */
+    async 'close-confirm'() {
+      await openPanel()
+      await sleep(120)
+      q('.tt_close').click()
+      await waitFor(() => q('.tt_confirmLayer'))
+      await sleep(150)
+      // 先验证「取消」这条路，再重新打开确认层留给截图
+      const before = tabs().length
+      q('.tt_confirmCancel').click()
+      await sleep(150)
+      const afterCancel = { layer: q('.tt_confirmLayer') !== null, panel: modal() !== null, tabs: tabs().length, before }
+      q('.tt_close').click()
+      await waitFor(() => q('.tt_confirmLayer'))
+      await sleep(150)
+      // 再验证「点层内空白 = 取消」（下面留给截图的那一份重新打开）
+      q('.tt_confirmLayer').dispatchEvent(new MouseEvent('mousedown', { bubbles: true }))
+      await sleep(150)
+      const afterBlank = { layer: q('.tt_confirmLayer') !== null, panel: modal() !== null }
+      q('.tt_close').click()
+      await waitFor(() => q('.tt_confirmLayer'))
+      await sleep(150)
+      /*
+       * 第三颗按钮「最小化」（2026-10-10，用户看过截图后加的）：这次的错点往往不是「结束」，
+       * 而是「想收起来」——而确认层盖住整个视口，hint 里那句「点「—」」在这时候根本点不到。
+       * 所以把它放到手边，并在这里钉死**它只能收起、绝不能结束会话**：接成 `closeModal` 的话
+       * 这条断言会当场红（这是本仓最该拦住的一类事故：把安全出路做成破坏按钮）。
+       * 走完这一步把面板恢复出来，最后再开一次确认层留给截图。
+       */
+      const minBtnExists = q('.tt_confirmMin') !== null
+      const minLabel = minBtnExists ? String(q('.tt_confirmMin').textContent) : ''
+      const beforeMin = tabs().length
+      if (minBtnExists) q('.tt_confirmMin').click()
+      await sleep(200)
+      const afterMin = {
+        layer: q('.tt_confirmLayer') !== null,
+        minimized: isMinimized(),
+        panelAlive: modal() !== null,
+        tabs: tabs().length,
+        before: beforeMin,
+      }
+      // 恢复面板：点侧边栏入口（收起态下它就是「恢复」那条路）
+      entry().click()
+      await waitFor(() => !isMinimized())
+      await sleep(150)
+      q('.tt_close').click()
+      await waitFor(() => q('.tt_confirmLayer'))
+      await sleep(150)
+      window.__previewAssert = async () => {
+        if (afterCancel.layer) return '点「取消」没关掉确认层'
+        if (!afterCancel.panel) return '点「取消」把面板关掉了'
+        if (afterCancel.tabs !== afterCancel.before) return '点「取消」把会话结束了'
+        if (afterBlank.layer) return '点确认层里的空白没关掉它（对话框的常规手感）'
+        if (!afterBlank.panel) return '点空白把面板也关掉了'
+        if (!minBtnExists) return '确认框里没有「最小化」这颗按钮（用户看过截图后要求加的那颗）'
+        if (!/最小化|Minimize/.test(minLabel)) return '第三颗按钮不是「最小化」：' + minLabel
+        if (afterMin.layer) return '点「最小化」没关掉确认层'
+        if (!afterMin.minimized) return '点「最小化」没把面板收起来'
+        if (!afterMin.panelAlive) return '点「最小化」把面板 DOM 也拆了（那等于关了面板）'
+        if (afterMin.tabs !== afterMin.before) return '点「最小化」把会话结束了：' + String(afterMin.before) + ' → ' + String(afterMin.tabs)
+        const layer = q('.tt_confirmLayer')
+        if (layer === null) return '有活会话时点 ✕ 没弹确认'
+        const okText = (q('.tt_confirmOk') || {}).textContent || ''
+        if (!okText.includes('1')) return '主按钮没写明会结束几条会话：' + okText
+        if (!says(layer, '最小化', 'Minimize')) return '确认里没给出「最小化」这条出路（hint 与按钮都算）'
+        /*
+         * issue #8 的口径守卫（2026-10-10 核对挖出来的那处出入）：判据是「活会话」= **还开着**
+         * （`close-guard.js` 只看 `exited !== true`），**判不出命令在不在跑**——面板上挂着一个停在
+         * 提示符的空 shell，与跑着 `pnpm build` 的那条，在判据眼里一模一样。所以文案不许把这批会话
+         * 说成「正在运行 / running sessions」：那是替实现吹一个它做不到的牛，报告者照回帖原文验收时
+         * 就会发现对不上。要改这条断言，先把「在跑」这个态真的接上线（宿主已有 `runningOf`，见
+         * `src/index.ts` 与 ROADMAP 的 0.28.0 那节），别直接改字。
+         *
+         * 措辞本身改过一轮（2026-10-10 晚些，用户看过右键菜单截图后问「什么叫还没退出」）：
+         * 「还没退出」→「还开着」——**判据一字未动**，只是把内部判据词换成用户词（与菜单里
+         * 已有的「已退出」成对）。下面那句正向断言跟着改，正向要钉的仍是「不许超出判据」。
+         */
+        const layerText = String(layer.textContent || '')
+        if (/正在运行|running sessions|are running/.test(layerText)) {
+          return '确认文案把这批会话说成「正在运行」了，而判据只是「还开着」（#8 口径）：' + layerText
+        }
+        if (!says(layer, '还开着', 'still open')) return '确认文案没说清这批会话是「还开着」的：' + layerText
+        // ✕ 的 tooltip 是同一句话的另一个出口（`btn.closePanelTitle`），一并钉
+        const closeTitle = (q('.tt_close') || {}).title || ''
+        if (/在跑|正在运行|running sessions/.test(closeTitle)) {
+          return '✕ 的 tooltip 说成「在跑 / 正在运行」了（#8 口径同样只到「还开着」）：' + closeTitle
+        }
+        return null
+      }
+    },
+    /*
+     * 关面板确认的反面：只剩已退出的标签时**不问**，直接关。
+     *
+     * 为什么要有这一条：判据若写成「有标签就问」，用户关掉一个跑完的终端也会被拦一次，
+     * 确认会被点成习惯（那时真正的拦阻就失效了）。反向验证：把判据换成 `tabs.size > 0`
+     * → 本场景红。
+     */
+    async 'close-confirm-empty'() {
+      await openPanel()
+      const el = activeTabEl()
+      emit({ t: 'exit', sid: sidOf(el), code: 0 })
+      await sleep(200)
+      q('.tt_close').click()
+      await sleep(250)
+      window.__previewAssert = async () => {
+        if (q('.tt_confirmLayer') !== null) return '只剩已退出的标签也弹了确认（纯噪音）'
+        if (modal() !== null) return '没有活会话时点 ✕ 没关掉面板'
+        return null
+      }
     },
     /* 连接错误遮罩 */
     async error() {
@@ -1895,6 +2384,203 @@
         return null
       }
     },
+
+    /*
+     * 批量关标签 ①（0.29.0）：用户报告「现在一个个关闭体验不是特别好」。
+     *
+     * 「⋯」的显隐判据从「溢出 **或** 有死标签」再放宽一格到「**标签 ≥ 2 个就在**」——
+     * 它现在同时是「关闭其他 / 关闭左侧 / 关闭右侧」的可见入口（右键是快路径，但不该是唯一出路）。
+     * 门槛正好留在 2：只剩一个标签时没有任何可管理的对象，仍要藏起来（D89 的「单标签时
+     * 『+』紧贴页签」和 tab-list 里那条「不溢出时不该可见」也正因此原样成立）。
+     *
+     * 钉三件事：① 单标签时入口不可见；② 3 个标签、**不溢出**时它也在；③ 菜单里有
+     * 「关闭其他标签（2）」，而活动标签是最后一个 → **「关闭右侧」这一行不该出现**
+     * （目标为空的行不出现，点了才不会空转）。
+     */
+    async 'tab-bulk-menu'() {
+      window.__PREVIEW_CONFIG.maxSessions = 12
+      await openPanel()
+      await sleep(200)
+      const moreAtOneTab = q('.tt_tabMore')
+      const visibleAtOneTab = moreAtOneTab === null ? null : moreAtOneTab.getBoundingClientRect().width > 0
+      for (let i = 0; i < 2; i += 1) {
+        await clickAdd()
+        await clickMenuItem('本地终端', 'Local terminal')
+        await waitFor(() => tabs().length === i + 2, 4000)
+      }
+      await sleep(220)
+      const strip = q('.tt_tabs')
+      const overflow = strip === null ? null : strip.scrollWidth > strip.clientWidth + 1
+      const more = q('.tt_tabMore')
+      const moreVisible = more === null ? null : more.getBoundingClientRect().width > 0
+      if (moreVisible === true) {
+        more.click()
+        await waitFor(() => q('.tt_tabMenu'))
+        await sleep(120)
+      }
+      window.__previewAssert = async () => {
+        if (tabs().length !== 3) return '夹具失效：期望 3 个标签，实际 ' + String(tabs().length)
+        if (visibleAtOneTab !== false) return '只有一个标签时「⋯」不该可见（实测 ' + String(visibleAtOneTab) + '）'
+        if (overflow !== false) return '夹具失效：三个标签就溢出了，量不到「不溢出也常驻」'
+        if (moreVisible !== true) return '标签 ≥ 2 个时「⋯」没出现（批量入口够不着）'
+        const menu = q('.tt_tabMenu')
+        if (menu === null) return '「⋯」菜单没打开'
+        const row = (zh, en) => qa('.tt_addMenuItem').find((el) => says(el, zh, en))
+        const others = row('关闭其他标签', 'Close other tabs')
+        if (others === undefined) return '「⋯」里没有「关闭其他标签」这一行'
+        if (!others.textContent.includes('2')) return '「关闭其他」没写明条数：' + String(others.textContent)
+        // 批量行副文案是同一口径的第四个出口（`list.subLive`）：同样只能说「还开着」
+        if (/正在运行|are running/.test(String(others.textContent))) {
+          return '批量行副文案说成「正在运行」了（#8 口径只到「还开着」）：' + String(others.textContent)
+        }
+        if (!says(others, '还开着', 'still open')) {
+          return '批量行副文案没说清这批标签是「还开着」的：' + String(others.textContent)
+        }
+        // 活动标签是最后一个 → 「关闭左侧」有目标（左边两个）、「关闭右侧」没有
+        const left = row('关闭左侧标签', 'Close tabs to the left')
+        if (left === undefined) return '活动标签在末尾时「关闭左侧标签」该出现（左边还有两个）'
+        if (!left.textContent.includes('2')) return '「关闭左侧」条数不对：' + String(left.textContent)
+        if (row('关闭右侧标签', 'Close tabs to the right') !== undefined) {
+          return '活动标签是最后一个，「关闭右侧」这一行不该出现（目标为空 = 点了空转）'
+        }
+        if (row('清理已退出', 'Clean up exited') !== undefined) return '没有已退出的标签，不该有清理行'
+        return null
+      }
+    },
+
+    /*
+     * 批量关标签 ②（0.29.0）：**右键**一个标签 = 以它为参照。
+     *
+     * 为什么是右键而不是「+」后面再加一个菜单按钮：「关闭其他 / 关闭左侧 / 关闭右侧」必须以
+     * 某个标签为参照，而「+」本身就是一个菜单触发器（`openAddMenu`），两个挨着的内容不同的
+     * 菜单按钮是明确的歧义源（理由全文见 client-src 的 `openTabContextMenu`）。
+     *
+     * 这里右键**中间**那个（3 个标签）：菜单要同时有「关闭此标签」「关闭其他标签（2）」
+     * 「关闭左侧标签（1）」「关闭右侧标签（1）」，且落在光标附近而不是被夹到左上角。
+     */
+    async 'tab-context-menu'() {
+      window.__PREVIEW_CONFIG.maxSessions = 12
+      await openPanel()
+      for (let i = 0; i < 2; i += 1) {
+        await clickAdd()
+        await clickMenuItem('本地终端', 'Local terminal')
+        await waitFor(() => tabs().length === i + 2, 4000)
+      }
+      await sleep(220)
+      const all = tabs()
+      const mid = all[1]
+      const rect = mid.getBoundingClientRect()
+      const at = { x: Math.round(rect.left + 24), y: Math.round(rect.bottom) }
+      mid.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: at.x, clientY: at.y }))
+      await waitFor(() => q('.tt_tabCtxMenu'))
+      await sleep(120)
+      window.__previewAssert = async () => {
+        if (tabs().length !== 3) return '夹具失效：期望 3 个标签，实际 ' + String(tabs().length)
+        const menu = q('.tt_tabCtxMenu')
+        if (menu === null) return '右键标签没弹出菜单'
+        if (q('.tt_tabMenu') !== null) return '右键时「⋯」列表还挂着（两个浮层叠在一起）'
+        if (q('.tt_addMenu:not(.tt_tabCtxMenu)') !== null) return '右键时「+」菜单还挂着（两个浮层叠在一起）'
+        const row = (zh, en) => qa('.tt_addMenuItem').find((el) => says(el, zh, en))
+        if (row('关闭此标签', 'Close this tab') === undefined) return '菜单里没有「关闭此标签」'
+        const others = row('关闭其他标签', 'Close other tabs')
+        if (others === undefined) return '菜单里没有「关闭其他标签」'
+        if (!others.textContent.includes('2')) return '「关闭其他」条数不对（参照在中间，另有两个）：' + String(others.textContent)
+        const left = row('关闭左侧标签', 'Close tabs to the left')
+        if (left === undefined) return '参照在中间时「关闭左侧」该出现'
+        if (!left.textContent.includes('1')) return '「关闭左侧」条数不对（参照左边还有一个）：' + String(left.textContent)
+        const right = row('关闭右侧标签', 'Close tabs to the right')
+        if (right === undefined) return '参照在中间时「关闭右侧」该出现'
+        if (!right.textContent.includes('1')) return '「关闭右侧」条数不对（参照右边还有一个）：' + String(right.textContent)
+        const box = menu.getBoundingClientRect()
+        if (Math.abs(box.left - at.x) > 320 || Math.abs(box.top - at.y) > 120) {
+          return '菜单没落在光标附近：光点 (' + String(at.x) + ',' + String(at.y) + ') → 菜单 (' + String(Math.round(box.left)) + ',' + String(Math.round(box.top)) + ')'
+        }
+        return null
+      }
+    },
+
+    /*
+     * 批量关标签 ③（0.29.0）：功能面 + 确认层。
+     *
+     * 右键第 1 个 → 「关闭其他标签（2）」：这一下要结束 **2 条活会话**，所以先弹确认
+     * （判据在 `client-src/tab-bulk.js`：只关一条与点它自己的 ✕ 等价，不弹）；点「结束」后
+     * 只留下被右键的那一个，**而且它要成为活动标签**（关掉活动标签时 closeTab 自己会接续）。
+     */
+    async 'tab-context-close-others'() {
+      window.__PREVIEW_CONFIG.maxSessions = 12
+      await openPanel()
+      for (let i = 0; i < 2; i += 1) {
+        await clickAdd()
+        await clickMenuItem('本地终端', 'Local terminal')
+        await waitFor(() => tabs().length === i + 2, 4000)
+      }
+      await sleep(220)
+      const refSid = sidOf(tabs()[0])
+      const rect = tabs()[0].getBoundingClientRect()
+      tabs()[0].dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: Math.round(rect.left + 24), clientY: Math.round(rect.bottom) }))
+      await waitFor(() => q('.tt_tabCtxMenu'))
+      await sleep(120)
+      const others = await waitFor(() => qa('.tt_addMenuItem').find((el) => says(el, '关闭其他标签', 'Close other tabs')))
+      others.click()
+      await waitFor(() => q('.tt_confirmLayer'))
+      await sleep(150)
+      const layer = q('.tt_confirmLayer')
+      const title = layer === null ? '' : String(layer.querySelector('.tt_confirmTitle').textContent)
+      const okText = layer === null ? '' : String(layer.querySelector('.tt_confirmOk').textContent)
+      if (layer !== null) layer.querySelector('.tt_confirmOk').click()
+      await sleep(320)
+      const left = tabs()
+      const state = {
+        count: left.length,
+        kept: left.length === 1 ? sidOf(left[0]) : null,
+        active: sidOf(q('.tt_tab[data-active]') || {}),
+        ctxMenu: q('.tt_tabCtxMenu') !== null,
+      }
+      window.__previewAssert = async () => {
+        if (state.count !== 1) return '「关闭其他」没关干净：还剩 ' + String(state.count) + ' 个标签'
+        if (state.kept !== refSid) return '留下的不是被右键的那个标签（' + String(state.kept) + ' ≠ ' + String(refSid) + '）'
+        if (state.active !== refSid) return '关完之后活动标签没接续到留下的那个'
+        if (state.ctxMenu) return '关完之后右键菜单还挂着'
+        if (!title.includes('2')) return '确认层没写清这一下要结束几条会话：' + title
+        if (!okText.includes('2')) return '确认按钮没写清条数：' + okText
+        return null
+      }
+    },
+
+    /*
+     * 批量关标签 ④（0.29.0）：中键 = 直接关（浏览器 / 编辑器的通用手感，零新增 UI）。
+     * 与 ✕ 同一条落点（`closeTab`），所以**不问**。
+     */
+    async 'tab-mid-click'() {
+      window.__PREVIEW_CONFIG.maxSessions = 12
+      await openPanel()
+      for (let i = 0; i < 2; i += 1) {
+        await clickAdd()
+        await clickMenuItem('本地终端', 'Local terminal')
+        await waitFor(() => tabs().length === i + 2, 4000)
+      }
+      await sleep(220)
+      const victim = sidOf(tabs()[1])
+      const before = tabs().length
+      tabs()[1].dispatchEvent(new MouseEvent('auxclick', { bubbles: true, cancelable: true, button: 1 }))
+      await sleep(300)
+      const after = tabs().length
+      const gone = !tabs().some((el) => sidOf(el) === victim)
+      const askLayer = q('.tt_confirmLayer') !== null
+      // 再中键一次量「连着关」（留下 1 个标签：截图要看清的还是标签栏）
+      const second = tabs()[1]
+      if (second !== undefined) second.dispatchEvent(new MouseEvent('auxclick', { bubbles: true, cancelable: true, button: 1 }))
+      await sleep(300)
+      const finalCount = tabs().length
+      window.__previewAssert = async () => {
+        if (before !== 3) return '夹具失效：期望 3 个标签，实际 ' + String(before)
+        if (!gone) return '中键没有关掉标签'
+        if (after !== 2) return '中键关了不止一个标签：' + String(after)
+        if (askLayer) return '中键关一个标签不该弹确认（与点 ✕ 同一条路）'
+        if (finalCount !== 1) return '连着中键关两次只该剩 1 个标签，实际 ' + String(finalCount)
+        return null
+      }
+    },
   }
 
   const name = new URLSearchParams(location.search).get('scenario') || 'local'