@hyzyn/dsh-docker 0.9.6 → 0.11.0

package/scripts/client-smoke.mjs

@@ -1451,43 +1451,51 @@ await test('聚合选择：入口 / 勾选框 / 操作条装配进 bundle', () =
   assert.ok(decoded.includes('已选 '), '缺少「已选 N 个容器」计数')
   assert.ok(decoded.includes('聚合日志 · '), '缺少聚合视图标题')
   assert.ok(decoded.includes('至少选择 2 个容器'), '缺少 N<2 的提示')
-  assert.ok(decoded.includes('连接数较多，浏览器并发长连接有限制'), '缺少软上限提示')
-  // 硬上限文案由「数字 + 后缀」拼出来（数字不写死），且 SSH 与本地后缀不同，
-  // 所以这里分开锁静态部分；具体数字由下面 pickDecide 的用例断言。
+  assert.ok(decoded.includes('已接近上限，再选下去整个页面会变卡'), '缺少软上限提示')
+  // 硬上限文案由「数字 + 后缀」拼出来（数字不写死），所以这里只锁静态部分；
+  // 具体数字由下面 pickDecide 的用例断言（它同时钉住「数字从哪来」）。
   assert.ok(decoded.includes('最多 '), '缺少硬上限的「最多」前缀')
   assert.ok(decoded.includes('个容器'), '缺少硬上限的「个容器」文案')
-  assert.ok(decoded.includes('，浏览器并发长连接有限制'), '缺少本地目标的硬上限后缀')
-  assert.ok(decoded.includes('（SSH 目标上一条连接要同时装实时流与刷新等短命令）'), '缺少 SSH 目标的硬上限后缀')
+  assert.ok(decoded.includes('会占满浏览器的同源连接，整个页面都会卡'), '缺少硬上限的成因后缀')
+  // 上限的来由要写在选择条上（D165）：不写清楚，3 看起来就只是个随手定的数字
+  assert.ok(decoded.includes('浏览器每个站点最多同时保持 4 条实时流'), '缺少「预算从哪来」的说明')
+  assert.ok(code.includes('dk_pickBudget'), '缺少预算说明的样式钩子')
+  // 接线判据走源码级：局部标识符会被压缩改名，产物里 `budget: t(` 认不出来
+  const pickSource = readFileSync(new URL('../client-src/index.js', import.meta.url), 'utf8')
+  assert.ok(/budget: t\('hint\.pickBudget'\)/.test(pickSource), '预算说明必须真的接到操作条上')
+  assert.ok(/props\.budget === undefined \? null/.test(pickSource), '操作条要渲染 budget（拿到不渲染等于没接）')
   assert.ok(decoded.includes('Escape'), '缺少 Esc 退出选择态')
   assert.ok(code.includes('dk_pick'), '缺少勾选框样式钩子')
   assert.ok(code.includes('dk_pickBar'), '缺少聚合操作条样式钩子')
   assert.ok(code.includes('dk_pillPick'), '缺少「聚合选择」激活态样式钩子')
 })
 
-await test('聚合选择：N<2 置灰、2~6 可聚合、7~8 软提示、>8 置灰（SSH 目标上限收到 6）', () => {
+await test('聚合选择：上限绑在浏览器同源连接预算上（4 条流 − 事件流 = 3）', () => {
   const pick = pickApi()
-  assert.equal(pick.MAX, 8)
-  assert.equal(pick.SOFT_MAX, 6)
+  /*
+   * D165（2026-10-08 真机实测）：宿主是 HTTP/1.1，每条 EventSource 独占一条同源
+   * 连接且不释放。实测常驻流 4 条 → 页内请求 6/6 成功（中位 29ms）；5 条 → 0/6 全部超时
+   * （同时刻进程外请求 41ms 正常，堵在浏览器不在宿主）。容器页常开着事件流，所以聚合
+   * 只能用掉剩下的 3 条。这条用例把「数字从哪来」钉住，免得后人凭手感调大。
+   */
+  assert.equal(pick.MAX, 3)
+  assert.equal(pick.SSH_MAX, 3, 'SSH 与本地共用同一个浏览器预算（卡页面的是浏览器，不是 MaxSessions）')
+  assert.equal(pick.SOFT_MAX, 2)
+  assert.equal(pick.BUDGET, 4, '同源预算：4 条常驻流')
+  assert.equal(pick.RESERVED, 1, '其中 1 条留给活动条的事件流')
   assert.deepEqual(pick.decide(0), { canRun: false, hint: '' })
   assert.deepEqual(pick.decide(1), { canRun: false, hint: '至少选择 2 个容器' })
   assert.deepEqual(pick.decide(2), { canRun: true, hint: '' })
-  assert.deepEqual(pick.decide(6), { canRun: true, hint: '' })
-  assert.deepEqual(pick.decide(7), { canRun: true, hint: '连接数较多，浏览器并发长连接有限制' })
-  assert.deepEqual(pick.decide(8), { canRun: true, hint: '连接数较多，浏览器并发长连接有限制' })
-  const over = pick.decide(9)
+  // 第 3 个已经在吃满预算前的最后一格：可点，但给一句软提示
+  assert.equal(pick.decide(3).canRun, true)
+  assert.match(pick.decide(3).hint, /整个页面会变卡/)
+  const over = pick.decide(4)
   assert.equal(over.canRun, false, '超过硬上限必须置灰')
-  assert.match(over.hint, /最多 8 个容器/)
+  assert.match(over.hint, /最多 3 个容器/)
 
-  // SSH 目标更紧：一条 TCP 连接的通道额度（MaxSessions 默认 10）要同时装下聚合流、
-  // 统计流、事件流与「刷新列表」这类短命令，所以聚合上限收到 6（= 软提示线，于是 SSH
-  // 上不再有「可点但已偏多」的区间）。本地目标走子进程，没有这个约束。
-  assert.equal(pick.SSH_MAX, 6)
-  assert.deepEqual(pick.decide(6, true), { canRun: true, hint: '' })
-  const sshOver = pick.decide(7, true)
-  assert.equal(sshOver.canRun, false, 'SSH 目标上 7 个容器必须置灰')
-  assert.match(sshOver.hint, /最多 6 个容器/)
-  assert.match(sshOver.hint, /SSH 目标/, '提示必须说明 SSH 上为什么更紧')
-  assert.equal(pick.decide(7, false).canRun, true, '本地目标不受 SSH 上限影响')
+  // 两个目标类型走同一套上限：真正卡住页面的是浏览器同源预算，与目标是 SSH 还是本机无关
+  assert.deepEqual(pick.decide(4, true).canRun, false, 'SSH 目标同样在 4 个时置灰')
+  assert.match(pick.decide(4, true).hint, /最多 3 个容器/)
 })
 
 await test('聚合选择：勾选增删保序 + 列表刷新按 id 对账', () => {
@@ -1606,7 +1614,7 @@ await test('事件流断开：状态判定只认 closed，unsupported 不给重
 await test('事件流断开：活动条接线（兄弟按钮、不是嵌套按钮）与 ⟳ 接手动刷新', () => {
   const decoded = decodeBundle(code)
   assert.ok(decoded.includes('重连'), '缺少重连按钮文案')
-  assert.ok(decoded.includes('不会自己回来'), '缺少「不会自愈」的说明')
+  assert.ok(decoded.includes('不会自动恢复'), '缺少「不会自愈」的说明')
   assert.ok(code.includes('dk_activityHeadRow'), '缺少头行容器（兄弟布局的前提）')
   assert.ok(code.includes('dk_activityRetry'), '缺少重连按钮样式钩子')
 
@@ -1653,6 +1661,45 @@ await test('事件流断开：活动条接线（兄弟按钮、不是嵌套按
     '重连补偿的判据必须含 manualReconnect（否则从未 open 过的流重连后列表不刷新）')
 })
 
+/*
+ * D164：服务端**拒绝了**这条流时，「重连」看起来毫无反应——真机现场（2026-10-08）：
+ * 248 上长流配额恒满 8/8，每次点重连都被拒；而客户端把 `event: error` 的 data 整个丢掉，
+ * 只置 `closed`，于是界面与点击前逐像素相同。统计流一直是读出 message 的，这里补齐。
+ */
+await test('D164：事件流的 error 帧要解出服务端原因（而不是丢掉）', () => {
+  const api = eventsApi()
+  assert.ok(api.errorMessage !== undefined, '缺少 __events.errorMessage 测试缝')
+  // 配额拒绝：必须原样带出那句可执行的文案
+  const refused = api.errorMessage({ data: JSON.stringify({ message: '目标 248 上已有 8 条实时流（上限 8）' }) })
+  assert.equal(refused, '目标 248 上已有 8 条实时流（上限 8）')
+  // 非 JSON 的 data：整段当原因（宁可显示原文，也别显示「不知道」）
+  assert.equal(api.errorMessage({ data: 'boom' }), 'boom')
+  // 连接层错误（无 data）：不是「服务端说了什么」，必须返回空串——
+  // 那种情况 EventSource 会自己重连，不能冒充成一次被拒绝的重连
+  assert.equal(api.errorMessage({}), '')
+  assert.equal(api.errorMessage({ data: '' }), '')
+  assert.equal(api.errorMessage(new Event('error')), '')
+  assert.equal(api.errorMessage(null), '')
+  assert.equal(api.errorMessage(undefined), '')
+  // 畸形 JSON 不许把半截载荷当文案漏出去
+  assert.equal(api.errorMessage({ data: '{"message":' }), '{"message":')
+  // message 不是字符串时退回原文，而不是渲染出 [object Object]
+  assert.equal(api.errorMessage({ data: JSON.stringify({ message: 42 }) }), '{"message":42}')
+})
+
+await test('D164：被拒原因要接到界面上（接线判据）', () => {
+  const decoded = decodeBundle(code)
+  assert.ok(decoded.includes('重连被拒'), '缺少「被拒绝」的提示文案')
+  assert.ok(decoded.includes('不会自动恢复'), '原有的「不会自愈」说明必须保留')
+  const source = readFileSync(new URL('../client-src/index.js', import.meta.url), 'utf8')
+  // 拒绝原因必须进 state，并作为 props 传给活动条（只解出来不传等于没修）
+  assert.ok(/setEventsRefused\(message\)/.test(source), 'error 帧的原因必须写进 state')
+  assert.ok(/refused: eventsRefused/.test(source), '活动条必须拿到被拒原因')
+  assert.ok(/hint\.eventsReconnectRefused/.test(source), '活动条必须渲染被拒文案')
+  // 重连成功要清掉（否则「上次被拒」会一直挂着，看着像现在还坏着）
+  assert.ok(/setEventsRefused\(''\)/.test(source), '重连成功 / 重新建流时必须清掉上一条原因')
+})
+
 await test('变更操作执行中态：按钮转圈 + 卡片锁组 + 确认框不关', () => {
   // 三处过渡态钩子：按钮 data-busy（图标换转圈）、卡片 data-pending（整组变更按钮压暗锁住）、
   // 确认框 k_confirmBusy（保持打开 + 「执行中…」）。真实点击路径需要浏览器，这里锁契约。
@@ -2419,6 +2466,195 @@ await test('连接本机：下拉项接的是 connectLocal（哨兵被拦在换
   assert.ok(/return/.test(branch), '哨兵分支必须 return，不能继续走换目标')
 })
 
+/* ------------------------------------------------------------------ *
+ * 就地提权：多能力 pending → 一条命令解锁全部（一次粘贴）
+ * ------------------------------------------------------------------ */
+
+/**
+ * 为什么这一组用例必须存在：改前 `elevation` 是**单槽** state（`setElevation({capability})`），
+ * 面板开着时再点另一个开关会把前一个能力的面板**替换**掉、它的命令从界面消失（宿主侧 challenge
+ * 仍在 pending）。2026-09-26 的设置卡片截图实测：两次授权时刻差 14 秒——用户必须在宿主终端
+ * **粘贴两次**。逐能力记录 + 合并复制修掉的就是这件事：两个开关各点一次，界面上同时有两块面板
+ * 与一个「复制全部」，终端**粘贴一次**两行。
+ *
+ * 断言打在**渲染树**与**按钮交下去的字节**上（不只是纯函数）：纯函数对而接线错（按钮接错回调、
+ * 只复制了第一条、顺序反了）在真机上才暴露，正是离线冒烟要拦的那一类。
+ */
+function elevationApi() {
+  const exports_ = registration.factory((spec) => SEED[spec])
+  assert.ok(exports_.__elevation !== undefined, '缺少 __elevation 测试缝')
+  return exports_.__elevation
+}
+
+/** 面板组的渲染：回调用桩记录，配置值默认都关着（与「开关还没打开」的真实初态一致）。 */
+function renderElevationPanels(records, overrides = {}) {
+  const api = elevationApi()
+  const copied = []
+  const closed = []
+  const regenerated = []
+  const tree = api.view(records, {
+    now: overrides.now ?? 1_700_000_000_000,
+    copiedKey: overrides.copiedKey ?? '',
+    configured: overrides.configured ?? (() => false),
+    onCopy: (capability, command) => copied.push({ capability, command }),
+    onCopyAll: (text) => copied.push({ capability: api.COPY_ALL_KEY, command: text }),
+    onRegenerate: (capability) => regenerated.push(capability),
+    onClose: (capability) => closed.push(capability),
+    onDisableFirst: () => {},
+  })
+  return { api, tree, copied, closed, regenerated }
+}
+
+/** 合并按钮：从渲染树里找（而不是读入参），保证「界面上真的有」这件事被测到。 */
+function mergeButtonOf(tree) {
+  return treeFind(tree, (node) => node.type === 'button' && node.props?.key === 'copyAll')[0]
+}
+
+await test('就地提权：两个 pending → 合并按钮复制的内容 = 两条命令按发起顺序的换行连接（逐字节）', () => {
+  const api = elevationApi()
+  const expiresAt = 1_700_000_000_000 + 300_000
+  // 发起顺序：先点 allowMutations，再点 allowExec（数组顺序就是点击顺序）
+  const records = [
+    { capability: 'allowMutations', command: "touch '/home/u/.dsh/dsh-kit/grant-confirm/aaa'", expiresAt },
+    { capability: 'allowExec', command: "touch '/home/u/.dsh/dsh-kit/grant-confirm/bbb'", expiresAt },
+  ]
+  const { tree, copied } = renderElevationPanels(records)
+  const button = mergeButtonOf(tree)
+  assert.ok(button !== undefined, '两个 pending 时必须出「复制全部」按钮')
+
+  /*
+   * 驱动按钮的 onClick（真跑一次「点了会怎样」）：断言的是**交给复制动作的那个字符串**
+   * （桩里没有 navigator，剪贴板本身是浏览器的事）——内容错（少一条 / 顺序反 / 用 && 连接）
+   * 才是本用例要拦的。
+   */
+  button.props.onClick()
+  assert.equal(copied.length, 1, '点一次合并按钮应恰好触发一次复制')
+  const text = copied[0].command
+  const expected = records[0].command + '\n' + records[1].command
+  assert.equal(text, expected, '合并内容必须逐字节等于两条命令的换行连接')
+  assert.equal(
+    Buffer.from(text, 'utf8').toString('base64'),
+    Buffer.from(expected, 'utf8').toString('base64'),
+    '按字节比对（换行符形态也是契约）',
+  )
+  assert.equal(text.split('\n').length, 2, '两条命令 = 两行')
+  assert.ok(!text.includes('&&'), '不得用 && 连接（PS 5.1 不认）')
+  assert.ok(!text.includes('; '), '不得用 ; 连接（cmd 不认）')
+  assert.ok(text.indexOf(records[0].command) < text.indexOf(records[1].command), '顺序必须是发起顺序（先点的在前）')
+  assert.equal(copied[0].capability, api.COPY_ALL_KEY, '合并复制的反馈键必须与单条按钮隔离')
+
+  // 每块面板自己的单条复制按钮仍在（用户仍可只复制一条），且只复制自己那条
+  const singleButtons = treeFind(tree, (node) => node.type === 'button' && node.props?.key === 'copy')
+  assert.equal(singleButtons.length, 2, '两块面板各自保留单条复制按钮')
+  singleButtons[0].props.onClick()
+  assert.equal(copied[1].command, records[0].command, '单条复制只复制自己那条命令')
+  assert.equal(copied[1].capability, 'allowMutations', '单条复制的反馈键是能力名（与合并按钮互不串）')
+})
+
+await test('就地提权：单个 pending → 无合并按钮（那条命令就在自己的面板里）', () => {
+  const expiresAt = 1_700_000_000_000 + 300_000
+  const single = [{ capability: 'allowMutations', command: "touch '/tmp/a'", expiresAt }]
+  const { tree, api } = renderElevationPanels(single)
+  assert.equal(mergeButtonOf(tree), undefined, '只点过一个开关时不该出现「复制全部（1 条）」')
+  // 反面判据：纯判定同样为假（防止某天有人把「≥2」放宽成「≥1」而用例只看渲染树）
+  assert.equal(api.shouldOfferMerge(single, 1_700_000_000_000), false)
+  // 界面结构不变形：一块面板 + 一个单条复制按钮
+  assert.equal(treeFind(tree, (node) => node.props?.className === 'dk_elevPanel').length, 1)
+  assert.equal(treeFind(tree, (node) => node.type === 'button' && node.props?.key === 'copy').length, 1)
+})
+
+await test('就地提权：一个 granted 后 → 合并按钮只剩剩下那一条（组里还有别的能力没解锁）', () => {
+  const api = elevationApi()
+  const expiresAt = 1_700_000_000_000 + 300_000
+  const two = [
+    { capability: 'allowMutations', command: "touch '/tmp/a'", expiresAt },
+    { capability: 'allowExec', command: "touch '/tmp/b'", expiresAt },
+  ]
+  // allowMutations 先解锁：记录留痕（面板消失），命令清掉
+  const afterGrant = api.markGranted(two, 'allowMutations')
+  assert.equal(api.shouldOfferMerge(afterGrant, 1_700_000_000_000), true, '还有一条没解锁时按钮要留着')
+  assert.deepEqual(api.merge(afterGrant, 1_700_000_000_000), ["touch '/tmp/b'"], '只剩仍 pending 的那一条')
+  assert.equal(api.text(afterGrant, 1_700_000_000_000), "touch '/tmp/b'", '合并内容退化成那一行（没有多余换行）')
+
+  const { tree, copied } = renderElevationPanels(afterGrant)
+  const button = mergeButtonOf(tree)
+  assert.ok(button !== undefined, '一个 granted 后合并按钮仍在')
+  button.props.onClick()
+  assert.equal(copied[0].command, "touch '/tmp/b'", '按钮此刻只复制仍 pending 的那条')
+  // 已授权的那块面板消失，仍 pending 的那块还在
+  assert.equal(treeFind(tree, (node) => node.props?.className === 'dk_elevPanel').length, 1, '已授权的面板必须消失')
+
+  // 两条都解锁 → 组里没有可复制命令：留痕被收掉，按钮自然消失
+  const allGranted = api.markGranted(afterGrant, 'allowExec')
+  assert.deepEqual(allGranted, [], '全部解锁后整组清空（含留痕）')
+  assert.equal(
+    api.view(allGranted, { copiedKey: '', configured: () => false, onCopy() {}, onCopyAll() {}, onRegenerate() {}, onClose() {}, onDisableFirst() {} }),
+    null,
+    '全部结束后面板组不渲染',
+  )
+})
+
+await test('就地提权：过期的那条不进合并（复制过去只会让宿主落一个过期后才出现的文件）', () => {
+  const api = elevationApi()
+  const now = 1_700_000_000_000
+  const records = [
+    { capability: 'allowMutations', command: "touch '/tmp/a'", expiresAt: now - 1 },
+    { capability: 'allowExec', command: "touch '/tmp/b'", expiresAt: now + 300_000 },
+  ]
+  assert.deepEqual(api.merge(records, now), ["touch '/tmp/b'"], '过期的从合并里剔掉')
+  const { tree, copied } = renderElevationPanels(records, { now })
+  const button = mergeButtonOf(tree)
+  assert.ok(button !== undefined, '组里仍有两条记录时按钮在（只是内容少了一条）')
+  button.props.onClick()
+  assert.equal(copied[0].command, "touch '/tmp/b'", '合并按钮只复制仍 pending 的那些')
+  // 两条都过期 → 没有可复制的：按钮收起（不再承诺一个不可能发生的解锁）
+  const bothExpired = records.map((record) => ({ ...record, expiresAt: now - 1 }))
+  assert.equal(api.shouldOfferMerge(bothExpired, now), false)
+})
+
+await test('就地提权：✕ 只关一个能力的面板，另一个照常解锁（不撤销宿主 challenge）', () => {
+  const api = elevationApi()
+  const expiresAt = 1_700_000_000_000 + 300_000
+  const records = [
+    { capability: 'allowMutations', command: "touch '/tmp/a'", expiresAt },
+    { capability: 'allowExec', command: "touch '/tmp/b'", expiresAt },
+  ]
+  const { tree, closed } = renderElevationPanels(records)
+  const closeButtons = treeFind(tree, (node) => node.type === 'button' && node.props?.key === 'close')
+  assert.equal(closeButtons.length, 2, '每块面板各有自己的收起按钮')
+  closeButtons[0].props.onClick()
+  assert.deepEqual(closed, ['allowMutations'], '✕ 只收起被点的那一个能力')
+  // 关掉 A 之后 B 照常解锁：记录集里仍留着 B，合并内容只剩 B 那条
+  const afterClose = api.remove(records, 'allowMutations')
+  assert.deepEqual(api.merge(afterClose, 1_700_000_000_000), ["touch '/tmp/b'"])
+  assert.equal(api.shouldOfferMerge(afterClose, 1_700_000_000_000), false, '只剩一个 pending 时合并按钮收起')
+})
+
+await test('就地提权：两条命令各自独立——一条出错 / 在途不影响另一条的合并', () => {
+  const api = elevationApi()
+  const expiresAt = 1_700_000_000_000 + 300_000
+  const records = [
+    { capability: 'allowMutations', error: 'HTTP 429' },
+    { capability: 'allowExec', command: "touch '/tmp/b'", expiresAt },
+  ]
+  assert.deepEqual(api.merge(records, 1_700_000_000_000), ["touch '/tmp/b'"], '出错那条没有命令，不进合并')
+  assert.equal(api.shouldOfferMerge(records, 1_700_000_000_000), false, '只有一条可复制时不出按钮')
+  // 在途（begin 还没回）同样不参与合并
+  assert.deepEqual(api.merge([{ capability: 'allowExec' }], 1_700_000_000_000), [])
+})
+
+await test('就地提权：i18n 双份齐（新增键 zh/en 都在，且都进了产物）', () => {
+  const source = readFileSync(new URL('../client-src/index.js', import.meta.url), 'utf8')
+  for (const key of ['elev.copyAll', 'elev.copyAllHint', 'elev.copyAllCopied']) {
+    const hits = source.split(`'${key}':`).length - 1
+    assert.equal(hits, 2, `${key} 必须在 zh / en 两份目录里各出现一次（现在是 ${String(hits)} 次）`)
+  }
+  const decoded = decodeBundle(code)
+  assert.ok(decoded.includes('复制全部'), 'bundle 里应有合并按钮的中文兜底文案')
+  assert.ok(code.includes('dk_elevPanels'), 'bundle 里应有面板组的样式钩子')
+  assert.ok(code.includes('dk_elevMerge'), 'bundle 里应有合并复制行的样式钩子')
+})
+
 /* ------------------------------------------------------------------ *
  * 结果
  * ------------------------------------------------------------------ */

package/scripts/route-smoke.mjs

@@ -181,6 +181,8 @@ function makeCtx(config, options = {}) {
     settingsStored: {},
     ttyConfig: options.ttyConfig,
     disposers: [],
+    // 宿主日志捕获：info / warn 都进这里（其余宿主侧断言用）
+    logs: [],
     /**
      * 本插件 entry 的安装级配置（= apply 拿到的 config）。DSH ≥0.1.7 的
      * `settings.describe()` 返回的是「默认值 ← 组合 base ← 用户层」的 resolved 值，
@@ -202,7 +204,10 @@ function makeCtx(config, options = {}) {
       return () => {}
     }
     const child = {
-      logger: { info: () => {}, warn: () => {} },
+      logger: {
+        info: (msg) => { state.logs.push(msg) },
+        warn: (msg) => { state.logs.push(msg) },
+      },
       effect: (callback, _name) => {
         const dispose = callback()
         state.disposers.push(typeof dispose === 'function' ? dispose : () => {})
@@ -1185,6 +1190,143 @@ await test('重启路径：settings 命名空间已禁用时挂载 → 挂载即
   assert.equal(config.body.config.enabled, false)
 })
 
+/* ------------------------------------------------------------------ *
+ * 7.5 能力使用审计（capability-use）：过闸的变更 / exec 每次一行
+ * ------------------------------------------------------------------ */
+
+const USE_PREFIX = '[dsh-docker] capability-use: '
+/*
+ * 审计行的出口是宿主 stdout（console.log，docker D162）——断言面因此是 console 捕获，
+ * 不是假 ctx 的 logger（那是其余宿主侧断言用的）。捕获行原样放行，不影响人工排障。
+ */
+const consoleLogs = []
+const origConsoleLog = console.log.bind(console)
+console.log = (...args) => {
+  consoleLogs.push(args.map((arg) => String(arg)).join(' '))
+  origConsoleLog(...args)
+}
+const useLines = () => consoleLogs.filter((line) => line.startsWith(USE_PREFIX))
+/** 前段字段无空格；detail 恒在行尾且值可含空格、可含像 key=value 的文本（exec 命令）——从最后一个 ` detail=` 处整段吃下。 */
+function parseUseLine(line) {
+  const fields = {}
+  const body = line.slice(USE_PREFIX.length)
+  const detailAt = body.lastIndexOf(' detail=')
+  const head = detailAt === -1 ? body : body.slice(0, detailAt)
+  for (const pair of head.split(' ')) {
+    const eq = pair.indexOf('=')
+    if (eq > 0) fields[pair.slice(0, eq)] = pair.slice(eq + 1)
+  }
+  if (detailAt !== -1) fields.detail = body.slice(detailAt + ' detail='.length)
+  return fields
+}
+/** 跑一条变更路由，断言它**恰好**产生一行 use 行且指定字段逐一对上。 */
+async function auditCase(sub, body, expected) {
+  const before = useLines().length
+  const res = await call('POST', sub, body)
+  assert.equal(res.status, 200, `${sub} 前置：路由本身要成功`)
+  const lines = useLines().slice(before)
+  assert.equal(lines.length, 1, `${sub} 应恰好产生一行 use 行，实际 ${String(lines.length)} 行`)
+  const fields = parseUseLine(lines[0])
+  for (const [key, value] of Object.entries(expected)) {
+    assert.equal(fields[key], value, `${sub}: 字段 ${key}`)
+  }
+  assert.equal(fields.target, '本机', `${sub}: target`)
+  assert.equal(fields.ok, 'true', `${sub}: ok`)
+  assert.notEqual(Number(fields.durationMs), NaN, `${sub}: durationMs 应是数字`)
+  return fields
+}
+
+await test('审计：八条变更 / exec 路由各恰好一行，字段与操作一一对应', async () => {
+  await auditCase('/images/remove', { target: '本机', ref: 'nginx:1.27' }, { capability: 'allowMutations', source: 'http', action: 'image.remove', ref: 'nginx:1.27' })
+  const prune = await auditCase('/images/prune', { target: '本机' }, { capability: 'allowMutations', source: 'http', action: 'image.prune' })
+  assert.equal('ref' in prune, false, 'prune 无目标：ref 字段应省略')
+  await auditCase('/networks/remove', { target: '本机', name: 'shop_default' }, { capability: 'allowMutations', source: 'http', action: 'network.remove', ref: 'shop_default' })
+  await auditCase('/networks/prune', { target: '本机' }, { capability: 'allowMutations', source: 'http', action: 'network.prune' })
+  await auditCase('/volumes/remove', { target: '本机', name: 'pgdata' }, { capability: 'allowMutations', source: 'http', action: 'volume.remove', ref: 'pgdata' })
+  await auditCase('/volumes/prune', { target: '本机' }, { capability: 'allowMutations', source: 'http', action: 'volume.prune' })
+  await auditCase('/action', { target: '本机', action: 'start', id: 'shop-web-1' }, { capability: 'allowMutations', source: 'http', action: 'container.start', ref: 'shop-web-1' })
+  await auditCase('/exec', { target: '本机', id: 'shop-web-1', command: 'echo hi' }, { capability: 'allowExec', source: 'http', action: 'exec', ref: 'shop-web-1', detail: 'code=0 cmd=echo hi' })
+})
+
+await test('审计：pull 流开记 start、收尾记 end（reason / code / durationMs）', async () => {
+  const before = useLines().length
+  const res = await call('GET', '/images/pull/stream?target=本机&ref=nginx:1.27')
+  assert.equal(res.status, 200)
+  const lines = useLines().slice(before)
+  assert.equal(lines.length, 2, 'pull 流应恰好产生 start + end 两行')
+  const start = parseUseLine(lines[0])
+  assert.equal(start.event, 'start')
+  assert.equal(start.action, 'image.pull')
+  assert.equal(start.ref, 'nginx:1.27')
+  assert.equal('ok' in start, false, 'start 行还没有结果：不带 ok')
+  const end = parseUseLine(lines[1])
+  assert.equal(end.event, 'end')
+  assert.equal(end.ok, 'true')
+  assert.equal(end.reason, 'pull-exit')
+  assert.equal(end.code, '0')
+  assert.notEqual(Number(end.durationMs), NaN)
+})
+
+await test('审计：只读路由与 /connect-local 产生零 use 行', async () => {
+  const before = useLines().length
+  for (const [method, sub, body] of [
+    ['POST', '/probe', { target: '本机' }],
+    ['POST', '/containers', { target: '本机' }],
+    ['POST', '/inspect', { target: '本机', id: 'shop-web-1' }],
+    ['POST', '/logs', { target: '本机', id: 'shop-web-1' }],
+    ['POST', '/stats', { target: '本机', ids: ['shop-web-1'] }],
+    ['POST', '/images', { target: '本机' }],
+    ['POST', '/networks', { target: '本机' }],
+    ['POST', '/volumes', { target: '本机' }],
+    ['POST', '/connect-local', {}],
+  ]) {
+    const res = await call(method, sub, body)
+    assert.equal(res.status, 200, `${sub} 前置`)
+  }
+  assert.equal(useLines().length - before, 0, '只读操作与 /connect-local 不该产生 use 行')
+})
+
+await test('审计：agent 工具 source=tool（不经 HTTP 路由，不与路由重复计数）', async () => {
+  const before = useLines().length
+  const action = state.tools.find((item) => item.name === 'docker_action')
+  assert.ok(action !== undefined)
+  await action.execute({ target: '本机', action: 'stop', id: 'shop-web-1' })
+  const exec = state.tools.find((item) => item.name === 'docker_exec')
+  assert.ok(exec !== undefined)
+  await exec.execute({ target: '本机', id: 'shop-web-1', command: 'ls -la' })
+  const lines = useLines().slice(before)
+  assert.equal(lines.length, 2, '两个工具各恰好一行')
+  const stop = parseUseLine(lines[0])
+  assert.equal(stop.source, 'tool')
+  assert.equal(stop.capability, 'allowMutations')
+  assert.equal(stop.action, 'container.stop')
+  assert.equal(stop.ref, 'shop-web-1')
+  const execLine = parseUseLine(lines[1])
+  assert.equal(execLine.source, 'tool')
+  assert.equal(execLine.capability, 'allowExec')
+  assert.equal(execLine.action, 'exec')
+  assert.equal(execLine.detail, 'code=0 cmd=ls -la')
+})
+
+await test('审计：403 不记（使用 = 过了闸）；开关恢复后一切照旧', async () => {
+  const before = useLines().length
+  const off = await call('POST', '/config', { allowMutations: false, allowExec: false })
+  assert.equal(off.status, 200)
+  const action = await call('POST', '/action', { target: '本机', action: 'stop', id: 'shop-web-1' })
+  assert.equal(action.status, 403)
+  const exec = await call('POST', '/exec', { target: '本机', id: 'shop-web-1', command: 'ls' })
+  assert.equal(exec.status, 403)
+  const pull = await call('GET', '/images/pull/stream?target=本机&ref=nginx:1.27')
+  assert.equal(pull.status, 403)
+  assert.equal(useLines().length - before, 0, '被闸挡回的请求不算使用')
+
+  // 恢复开关：后续用例（若有）不受影响，工具重新注册
+  const on = await call('POST', '/config', { allowMutations: true, allowExec: true })
+  assert.equal(on.status, 200)
+  assert.equal(toolNames().includes('docker_action'), true)
+  await auditCase('/action', { target: '本机', action: 'start', id: 'shop-web-1' }, { capability: 'allowMutations', source: 'http', action: 'container.start', ref: 'shop-web-1' })
+})
+
 /* ------------------------------------------------------------------ *
  * 8. 结果
  * ------------------------------------------------------------------ */