@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/patches/verify-bundled-migrators.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * verify-bundled-migrators.mjs — 校验**打包副本**里的迁移器/校验器也带上了 hotfix。
+ *
+ * 由来（2026-09-29 事故，实例 session-06732069「Argent项目」）：
+ *   `@deepseek-ai/dsh-session-persistence-jsonl` 在做 v3→v4 迁移时，会另起一个
+ *   **worker 线程**对迁移产物做最终校验，而那个 worker 是**打包件**
+ *   （`lib/worker.cjs`，~540KB，内联了一整份 v0→v1 与 v3→v4 的迁移器/校验器）。
+ *   `scripts/patches/*.patch` 历来只打在 `lib/index.js` 这些**模块**上 ⇒
+ *     · `verify-session-migration.mjs`（import 模块）**一直假绿**；
+ *     · 真实 resume 走 worker 的旧副本 → `SessionPersistenceCorruptionError:
+ *       stored log is corrupt: Error: tool/result is outside an open turn`
+ *     ⇒ 前端发消息弹 toast、会话打不开。
+ *
+ * 判据（文本级，诚实说明边界）：worker 是打包件、无导出，无法直接做行为断言；
+ * 这里用**紧贴语义的代码形状**断言两处 hotfix 是否在打包副本里：
+ *   A. v3→v4 `tool()`：turn 外的替换型 tool/result 必须走"校验 data.turn 指向已关闭
+ *      历史 turn"的放宽分支，**不得**再是裸 `this.requireTurn(event.type);`。
+ *   B. v0 `permission/preset`：必须容忍旧数据里的 `origin` 键。
+ * 任一不满足 → exit 1，提示先跑 `node scripts/dsh-upgrade.mjs --patches-only`。
+ *
+ * 用法：node scripts/patches/verify-bundled-migrators.mjs
+ * 退出码：0 通过（或本机无该打包件，跳过）/ 1 失守
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { requireDshScope } from '../lib/dsh-scope.mjs'
+
+// 0.6.0 F1 修复批（2026-10-14）：探不到 scope ⇒ 响亮失败（⛔ 不用假路径 ⇒ 否则本脚本会
+// "本机无该打包件，跳过"地**假绿** —— 而它正是防"worker 打包副本漏打 hotfix"的那道门禁）。
+let SCOPE
+try { SCOPE = requireDshScope({ what: '打包副本校验（verify-bundled-migrators）' }) }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(1) }
+const WORKER = `${SCOPE}/dsh-session-persistence-jsonl/lib/worker.cjs`
+
+let pass = 0, fail = 0
+const ok = (c, n) => { c ? (pass++, console.log(`  ✅ ${n}`)) : (fail++, console.log(`  ❌ ${n}`)) }
+
+console.log('【打包副本】dsh-session-persistence-jsonl/lib/worker.cjs 的迁移器 hotfix')
+
+if (!existsSync(WORKER)) {
+  console.log(`  ⏭  本机没有该打包件（${WORKER}）——跳过（上游可能改了实现）`)
+  process.exit(0)
+}
+
+const src = readFileSync(WORKER, 'utf8')
+
+// ── A. v3→v4 tool()：放宽 turn 外的替换型 tool/result ──────────────────────────
+const toolAt = src.indexOf('\ttool(event, data) {')
+if (toolAt === -1) {
+  ok(false, 'worker 里能找到 v3→v4 的 tool() 方法（上游结构可能已变，本门禁需同步）')
+} else {
+  // 取该方法开头到 `this.requireStep(` 之间的片段（即 surfaceOp !== "append" 分支）
+  const stepAt = src.indexOf('this.requireStep(event, data);', toolAt)
+  const branch = stepAt === -1 ? src.slice(toolAt, toolAt + 1200) : src.slice(toolAt, stepAt)
+  ok(/Hardening \(2026-09-29, argent-dsh hotfix, mirrored into the bundled worker\)/.test(branch),
+    'A1 打补丁标记存在（mirrored into the bundled worker）')
+  ok(!/^\s*this\.requireTurn\(event\.type\);\s*$/m.test(branch),
+    'A2 已不再是裸 requireTurn（否则 turn 外替换型 tool/result 会否掉整个迁移）')
+  ok(/const t = data\["turn"\];/.test(branch) && /t >= this\.nextTurn/.test(branch),
+    'A3 放宽分支在校验 data.turn 指向已关闭的历史 turn（不是无条件放行）')
+}
+
+// ── B. v0 permission/preset：容忍 origin ────────────────────────────────────
+ok(/"permission\/preset": disposition\(\["preset"\], \["origin"\]\)/.test(src),
+  'B1 v0 的 permission/preset 容忍旧数据的 origin 键（2026-09-10 hotfix 的镜像）')
+ok(!/"permission\/preset": disposition\(\["preset"\]\),/.test(src),
+  'B2 旧的严格 disposition 已不存在')
+
+// ── C. 共享的 requireTurn 仍应保持严格（放宽只针对替换型 tool/result）─────────
+ok(/requireTurn\(type\) \{\s*\n\s*if \(this\.turn === null\) throw new SessionFormatError\(`\$\{type\} is outside an open turn`\);/.test(src),
+  'C1 requireTurn 本身仍是严格的（放宽没有波及别的下游事件类型）')
+
+console.log(`\n── 合计：通过 ${pass} / 失败 ${fail}`)
+if (fail > 0) {
+  console.log('❌ 打包副本未同步 hotfix —— 真实 resume 会否掉会话（前端发送消息报 toast）')
+  console.log('   修法：node scripts/dsh-upgrade.mjs --patches-only   （必须重启前跑）')
+  process.exit(1)
+}
+console.log('✅ 打包副本的迁移器 hotfix 已同步（模块 + worker 两侧一致）')

package/engine/scripts/patches/verify-hardening.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * 加固补丁校验（2026-09-18 会话毒化事故的防线）。
+ *
+ * 两个补丁：
+ *   A. dsh-tools--render-return-shape.patch
+ *      `createSuccessResult()` 把 output.render 的返回值**直接**当作 tool-result content。
+ *      补丁把非数组返回值规范化成 [{type:'text',text}] 并 warn 点名工具。
+ *   B. dsh-session--append-message-shape.patch
+ *      `Session.append()` 原本只做 validateSessionEventData + surface 校验，**漏了
+ *      assertMessageEventShape** ⇒ 一个非法 message 事件能写进日志，直到**下次从磁盘加载**
+ *      才炸（"message must contain one tool-result block"），此时会话根本打不开，
+ *      surface replace 也救不回来（校验针对事件本身，不是 surface 视图）。
+ *
+ * 本脚本对 B 做**真实行为验证**（真造一个会话、真 append），对 A 做源码语义断言
+ * （ToolRuntime 需要完整 ctx，其端到端验证在运行中的实例里用动态插件完成）。
+ *
+ * 用法：node verify-hardening.mjs   （只读 + 内存会话，不触碰任何 session 文件）
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { requireDshScope } from '../lib/dsh-scope.mjs'
+
+// 2026-09-28：scope 解析改为共享实现（客户机 dsh 在 ~/node/lib/node_modules，
+// 写死 homebrew 会让校验在客户机上一律假红 —— 实测把升级门禁整片挡住）。
+// 0.6.0 F1 修复批（2026-10-14）：**探不到**（null / 空壳）⇒ 响亮失败；⛔ 不许拿假路径继续 ——
+// 那会让下面 `existsSync(TOOLS)` 恒 false 而"降级"成跳过 ⇒ 门禁**假绿**（看着通过、其实没验）。
+let SCOPE
+try { SCOPE = requireDshScope({ what: '补丁校验（verify-hardening）' }) }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(1) }
+const TOOLS = `${SCOPE}/dsh-tools/lib/index.js`
+const SESSION = `${SCOPE}/dsh-session/lib/index.js`
+
+let pass = 0, fail = 0
+const ok = (c, n) => { c ? (pass++, console.log(`  ✅ ${n}`)) : (fail++, console.log(`  ❌ ${n}`)) }
+
+console.log('【补丁 A】dsh-tools：output.render 返回值规范化')
+if (!existsSync(TOOLS)) { ok(false, `dsh-tools 存在（${TOOLS}）`) }
+else {
+  const src = readFileSync(TOOLS, 'utf8')
+  ok(/function normalizeRenderOutput\(toolName, rendered\)/.test(src), 'normalizeRenderOutput() 已定义')
+  ok(/snapshotProjection\(tool\.name, "render", normalizeRenderOutput\(tool\.name, rendered\)\)/.test(src),
+    'createSuccessResult() 已经过它规范化 render 返回值')
+  ok(/if \(Array\.isArray\(rendered\)\) return rendered;/.test(src), '数组返回值原样透传（不改变正常工具行为）')
+
+  // 行为验证：把函数体取出来直接调用（补丁把它插在 defineTool 之前，故以下一个顶层函数为界）
+  const start = src.indexOf('function normalizeRenderOutput(')
+  const end = src.indexOf('\nfunction defineTool(', start)
+  const body = start === -1 || end === -1 ? '' : src.slice(start, end)
+  let normalize = null
+  try { normalize = new Function(`${body}\nreturn normalizeRenderOutput`)() } catch { /* 保持 null */ }
+  ok(typeof normalize === 'function', 'normalizeRenderOutput 可独立求值（用于行为断言）')
+  if (typeof normalize === 'function') {
+    const originalWarn = console.warn
+    const warnings = []
+    console.warn = (msg) => warnings.push(String(msg))
+    let cases
+    try {
+      cases = {
+        passThrough: normalize('probe', [{ type: 'text', text: 'ok' }]),
+        fromString: normalize('probe', '流程 full：无未处置失败'),
+        fromObject: normalize('probe', { count: 2 }),
+        fromUndefined: normalize('probe', undefined),
+        fromNull: normalize('probe', null),
+      }
+    } finally { console.warn = originalWarn }
+    const isBlocks = (v) => Array.isArray(v) && v.length > 0
+      && v.every((b) => b && typeof b === 'object' && typeof b.type === 'string' && typeof b.text === 'string')
+    ok(Array.isArray(cases.passThrough) && cases.passThrough[0].text === 'ok', '数组原样返回（不复制、不改写）')
+    ok(isBlocks(cases.fromString) && cases.fromString[0].text === '流程 full：无未处置失败',
+      `毒源场景：字符串被包装成 ContentBlock（${JSON.stringify(cases.fromString)}）`)
+    ok(isBlocks(cases.fromObject) && cases.fromObject[0].text === '{"count":2}', '对象被 JSON 化后包装')
+    ok(isBlocks(cases.fromUndefined) && cases.fromUndefined[0].text === 'undefined', 'undefined 被安全包装（不会写成 content: undefined）')
+    ok(isBlocks(cases.fromNull), 'null 被安全包装')
+    ok(warnings.length === 4 && warnings.every((w) => w.includes('"probe"') && w.includes('output.render must return a ContentBlock array')),
+      `每次都 warn 并点名工具（${warnings.length} 条）`)
+  }
+}
+
+console.log('\n【补丁 B】dsh-session：append 边界补上 message 形状校验')
+if (!existsSync(SESSION)) { ok(false, `dsh-session 存在（${SESSION}）`) }
+else {
+  const src = readFileSync(SESSION, 'utf8')
+  ok(/Hardening \(2026-09-18, argent-dsh hotfix\)/.test(src), '打补丁标记存在')
+  const appendBody = src.slice(src.indexOf('\tappend(type, data, ...opts) {'), src.indexOf('headerFold;', src.indexOf('\tappend(type, data, ...opts) {')))
+  ok(/validateSessionEventData\(event, `session event "\$\{type\}" at seq \$\{event\.seq\}`\);\s*\n\s*\/\* Hardening[\s\S]*?\*\/\s*\n\s*assertMessageEventShape\(event, `session event "\$\{type\}" at seq \$\{event\.seq\}`\);/.test(appendBody),
+    'append() 在落盘前调用 assertMessageEventShape()')
+
+  // 真实行为验证：真造会话、真 append
+  const { Session } = await import(SESSION)
+  const session = Session.create('verify-hardening-probe')
+  // ⚠️ 版本差异（2026-09-29 实测）：0.1.5 的 `tool/result` 容忍 message.role='user'，
+  // 0.1.7 起收紧为必须 'tool'（dsh 自己的 MESSAGE_ROLE_BY_TYPE 校验）。
+  // 夹具按目标版本自适应：先试 'tool'，抛"role"错再退回 'user'。
+  // ⚠️ 夹具形态修正（2026-09-29）：`mkToolResult` 的参数是 **message.content 本身**。
+  // 0.1.7 真实写入路径 = dsh-llm `createToolResultMessage({content})` 把 render 输出
+  // **直接**当 message.content（v4 形态，见 dsh-agent-loop `appendToolResult`）；
+  // 旧夹具套了一层 v3 的 `{type:'tool-result',content}` wrapper —— 那是 v3 遗留形态
+  // （v3→v4 迁移器会把它展开，retired syntax），append 边界本就容忍，
+  // 拿它当"坏样本"只会得到**假红**（补丁 10:34 放宽规则后一直红着）。
+  const mkToolResult = (content, role) => ({
+    turn: 1,
+    step: 1,
+    message: {
+      id: 'verify-message-1',
+      role,
+      toolCallId: 'verify-call-1',
+      content,
+      source: { kind: 'tool', callId: 'verify-call-1' },
+    },
+  })
+
+  let role = 'tool'
+  let good = null
+  try { good = session.append('tool/result', mkToolResult([{ type: 'text', text: '正常工具结果' }], role), { surfaceOp: 'append' }) }
+  catch (err) {
+    if (/must have role/i.test(err.message)) {
+      role = 'user'
+      try { good = session.append('tool/result', mkToolResult([{ type: 'text', text: '正常工具结果' }], role), { surfaceOp: 'append' }) }
+      catch (err2) { good = { error: err2.message } }
+    } else { good = { error: err.message } }
+  }
+  ok(good && good.error === undefined, `合法 tool-result 仍可写入（seq ${good && good.seq}）`)
+
+  // 坏样本 ①：真毒源 —— render 返回裸字符串且补丁 A 未打时，message.content 就是字符串。
+  // （上游 0.1.7 自带 Array.isArray 会先拦；这断言保证这条线不会静默失守。）
+  let bad = null
+  try { session.append('tool/result', mkToolResult('裸字符串', role), { surfaceOp: 'append' }); bad = null }
+  catch (err) { bad = err.message }
+  ok(bad !== null && /invalid content|non-empty content block array/.test(bad),
+    `毒源 tool-result（content 为裸字符串）在**写入时**即被拒绝：${bad || '竟然写进去了！'}`)
+
+  // 坏样本 ②：空数组 —— 上游 Array.isArray 放行，**只有**补丁 B 的规则能拦住，
+  // 用它证明"我方加固规则确实在生效"（否则 ① 可能只是上游功劳）。
+  let empty = null
+  try { session.append('tool/result', mkToolResult([], role), { surfaceOp: 'append' }); empty = null }
+  catch (err) { empty = err.message }
+  ok(empty !== null && /must contain a non-empty content block array/.test(empty),
+    `空 content 数组在**写入时**即被拒绝（补丁 B 独立生效）：${empty || '竟然写进去了！'}`)
+
+  let roleBad = null
+  try {
+    session.append('assistant/message', {
+      turn: 1, step: 1,
+      message: { id: 'verify-message-2', role: 'user', content: [{ type: 'text', text: 'x' }], source: { kind: 'model', provider: 'p', model: 'm' } },
+      stream: [],
+    }, { surfaceOp: 'append' })
+    roleBad = null
+  } catch (err) { roleBad = err.message }
+  ok(roleBad !== null && /must have role/.test(roleBad), `role 不符的 message 也被拒绝：${roleBad || '竟然写进去了！'}`)
+
+  let nonMessage = null
+  try { nonMessage = session.append('turn/start', { turn: 1 }) }
+  catch (err) { nonMessage = { error: err.message } }
+  ok(nonMessage && nonMessage.error === undefined, '非 message 事件（turn/start）不受影响，照常写入')
+
+  // 拒绝后日志不应增长（校验先于 this.log.push）
+  const before = session.seq
+  try { session.append('tool/result', mkToolResult('又一个裸字符串'), { surfaceOp: 'append' }) } catch { /* 预期 */ }
+  ok(session.seq === before, '被拒绝的事件**没有**进入日志（校验先于 push）')
+}
+
+console.log(`\n── 合计：通过 ${pass} / 失败 ${fail}`)
+if (fail > 0) {
+  console.log('❌ 加固补丁校验未通过：补丁可能没打上或上游已改动 —— 先别重启，见 AGENTS.md「会话毒化事故」')
+  process.exit(1)
+}
+console.log('✅ 加固补丁校验通过：render 返回值被规范化 + append 边界拒绝无法重放的 message 事件')

package/engine/scripts/patches/verify-session-migration.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * verify-session-migration.mjs — 对真实 session 文件跑完整格式迁移链（v0→v3）验证。
+ *
+ * 用途：dsh 升级后检查旧 session 兼容性（如 0.1.5 的 v0-to-v1 origin 遗漏 bug）。
+ * 用法：
+ *   node verify-session-migration.mjs <session.jsonl.zstd> [...more]
+ *   node verify-session-migration.mjs ~/.dsh/sessions/.../session-<id>/session.jsonl.zstd
+ *
+ * 依赖：全局 dsh scope（/opt/homebrew/lib/node_modules/@deepseek-ai）。
+ * 输出：每个文件 ✅/❌ + 事件数；全部通过 exit 0，任一失败 exit 1。
+ */
+import { createRequire } from 'node:module'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { requireDshScope } from '../lib/dsh-scope.mjs'
+import { decodeSessionLines, readSessionHeader } from '../lib/zstd-frames.mjs'
+import { existsSync, readdirSync } from 'node:fs'
+
+// 2026-09-10 修复：本脚本在**仓库目录**下运行，裸 specifier 无法从全局 scope 解析
+// （原实现 `import ... from '@deepseek-ai/dsh-session-format-catalog'` 直接 ERR_MODULE_NOT_FOUND）。
+// 改为锚定全局 scope 的 require（Node ≥22.12 的 require(esm) 可用），并允许 DSH_SCOPE 覆盖。
+// 0.6.0 F1 修复批（2026-10-14）：本脚本的 require 就锚在 scope 上 ⇒ 拿不到 scope 就**响亮失败**
+// （⛔ 不用假路径 —— 那会 ERR_MODULE_NOT_FOUND，看着像"宿主坏了"，其实是 scope 探错树）。
+let _SCOPE_DIR
+try { _SCOPE_DIR = requireDshScope({ what: '会话迁移校验（verify-session-migration）' }) }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(1) }
+const SCOPE = _SCOPE_DIR.replace(/\/?$/, '/')
+const requireGlobal = createRequire(SCOPE)
+const { sessionFormatCatalog, createSessionFormatCatalogWithChildren } = requireGlobal('@deepseek-ai/dsh-session-format-catalog')
+
+/**
+ * 收集某会话的**子会话事实**（v3→v4 迁移需要）。
+ *
+ * 为什么必须自己找（2026-09-29）：0.1.7 新增 v3→v4 迁移，它要求父会话显式声明其历史子会话
+ * （含"没有子会话"时的空数组）。真实加载路径 `dsh-session-persistence-jsonl` 会扫
+ * `origin === 'subagent' && parentSession === <id>` 并把结果传进
+ * `createSessionFormatCatalogWithChildren()`；本校验器原先直接拿默认 catalog ⇒
+ * 报 "requires explicit historical child facts"，**把"校验器绕过真实路径"误报成"旧会话打不开"**。
+ * 这里照真实路径的口径补上。
+ */
+function collectChildren(sessionId) {
+  const root = join(process.env.DSH_HOME || join(process.env.HOME || '', '.dsh'), 'sessions')
+  const out = []
+  let dirs = []
+  try {
+    for (const a of readdirSync(root)) {
+      for (const b of readdirSync(join(root, a))) {
+        const d = join(root, a, b)
+        // 2026-09-29 修复：对齐 dsh 的 listArtifacts——识别**所有生成文件**（含版本化
+        // session.v3/.v4.jsonl.zstd），每个目录选最高版本；此前只认未版本化文件名，
+        // 且证据缺 descriptorCount/descriptor ⇒ 误报 "requires historical child identity"。
+        let files = []
+        try { files = readdirSync(d).filter((f) => /^session(\.v\d+)?\.jsonl\.zstd$/.test(f)) } catch { continue }
+        if (files.length === 0) continue
+        const ver = (f) => { const m = /\.v(\d+)\./.exec(f); return m ? Number(m[1]) : 0 }
+        files.sort((x, y) => ver(y) - ver(x) || (x < y ? -1 : 1))
+        dirs.push(join(d, files[0]))
+      }
+    }
+  } catch { return out }
+  for (const f of dirs) {
+    const h = readSessionHeader(f)
+    if (!h || h.origin !== 'subagent' || h.parentSession !== sessionId) continue
+    // 提取 descriptor 证据（对齐 dsh historicalChildCatalogSource）：descriptor 键必须存在；
+    // 读取失败 → 与 dsh 的 unavailable 兜底同款（descriptorCount: 0, descriptor: null）。
+    let descriptorCount = 0
+    let descriptor = null
+    try {
+      const { lines } = decodeSessionLines(readFileSync(f))
+      const descs = lines.map((l) => JSON.parse(l.raw)).filter((e) => e.type === 'subagent/descriptor')
+      descriptorCount = descs.length
+      descriptor = descs[0]?.data ?? null
+    } catch { /* 读失败 → 兜底 */ }
+    out.push({ childId: h.id, childCreatedAt: h.createdAt, descriptorCount, descriptor })
+  }
+  return out.sort((x, y) => x.childCreatedAt - y.childCreatedAt || (x.childId < y.childId ? -1 : 1))
+}
+
+const files = process.argv.slice(2)
+if (files.length === 0) {
+  console.error('用法: node verify-session-migration.mjs <session.jsonl.zstd> [...]')
+  process.exit(2)
+}
+
+let failed = 0
+for (const file of files) {
+  // 解压：走共享的多帧切帧实现（lib/zstd-frames.mjs）。
+  // 2026-09-28 两个坑都在这里踩过：
+  //   ① 原来只走 `zstd` CLI（本机 homebrew 有、客户机没装）⇒ 一律 "spawnSync zstd ENOENT"；
+  //   ② 改用 Node 内置 zstdDecompressSync ⇒ **只解首帧**（65MB 日志只出 182 字节），
+  //      校验会"通过"却什么都没看 —— 假绿比报错更危险。
+  const tmp = join(tmpdir(), `dsh-sess-verify-${process.pid}.jsonl`)
+  try {
+    const { frames } = decodeSessionLines(readFileSync(file))
+    if (frames.length === 0) throw new Error('切帧结果为空')
+    writeFileSync(tmp, Buffer.concat(frames.map((f) => f.plain)))
+  } catch (e) {
+    console.log(`❌ ${file}: 解压失败 ${e.message}`)
+    failed++
+    continue
+  }
+
+  // ⚠️ 2026-09-29 修复「假红」：**不要**用 Node readline 切行。
+  // readline 把 U+2028/U+2029 也当行终止符，而真实加载路径
+  // （dsh-session-persistence-jsonl）只按**字节 10 (`\n`)** 切（`chunk.indexOf(10)`；
+  // U+2028 的 UTF-8 是 E2 80 A8，不含 0x0A）。实测 session-f82d039e 的 tool-result
+  // 文本里含 U+2028 ⇒ readline 把一行劈成两半，报 "Unterminated string in JSON"，
+  // 把**能正常打开**的会话判成打不开。这里与真实路径统一口径：只按 '\n' 切。
+  const lines = readFileSync(tmp, 'utf8').split('\n')
+  let header = null
+  let restore = null
+  let lineNo = 0
+  let firstError = null
+  try {
+    for (const line of lines) {
+      if (!line.trim()) continue
+      lineNo++
+      if (header === null) {
+        header = JSON.parse(line)
+        // 与真实加载路径一致：带上该会话的子会话事实（v3→v4 迁移需要；无子会话=显式空数组）
+        const children = collectChildren(header.id)
+        const catalog = createSessionFormatCatalogWithChildren
+          ? createSessionFormatCatalogWithChildren(children)
+          : sessionFormatCatalog
+        restore = catalog.createRestore(header, { recovery: 'strict', validation: 'transformed' })
+        continue
+      }
+      if (firstError) continue
+      try {
+        restore.decodeRow(JSON.parse(line))
+      } catch (e) {
+        firstError = `行 ${lineNo}: ${e.message}`
+      }
+    }
+    if (firstError) throw new Error(firstError)
+    const artifact = restore.finish()
+    console.log(`✅ ${file}`)
+    console.log(`   v${header.version} → v${artifact.header.version}, 事件 ${artifact.events.length}, 行 ${lineNo}`)
+  } catch (e) {
+    console.log(`❌ ${file}`)
+    console.log(`   ${e.message}`)
+    failed++
+  }
+}
+
+process.exit(failed > 0 ? 1 : 0)

package/engine/scripts/patches/verify-transport-diagnostics.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * TRANSPORT 诊断补丁校验（2026-10-02，任务 D）。
+ *
+ * 补丁：`dsh-llm-deepseek--transport-diagnostics.patch`
+ * 目标：`@deepseek-ai/dsh-llm-deepseek/lib/index.js`（官方 Messages 适配器；
+ *       **问述代理复用同一份**，见 `plugins/argent-core/src/llm-whyshu.js`）。
+ *
+ * ## 为什么要有它
+ * 线上现象：Web 回合偶发 `This turn failed / DeepSeek Messages transport failed`。
+ * 实测（session-06732069 / session-878f3e3b 的会话日志）该 failure 落进 `llm/retry`
+ * 事件时**只有 `{message, code}`**，没有 cause、没有请求标识、没有"已产出多少"
+ * ⇒ 事后既分不清 ECONNRESET / 提前关闭 / 5xx 断流，也无法判断"这次到底产出了没有"。
+ * 补丁只做**可观测性**（判定语义不变）。
+ *
+ * ## 本脚本验什么
+ *   ① 源码语义断言：三分支判定**未被改动**（顺序、code、`instanceof LlmError` 直通都还在）；
+ *   ② 行为断言：把补丁插入的纯函数**取出来真跑**，逐个覆盖
+ *      ECONNRESET / socket hang up / ETIMEDOUT / 非 2xx + 响应体片段 / AbortError，
+ *      以及"已产出长度"的累加（文本/思维链/工具参数/块）；
+ *   ③ 装配断言：`registerDeepSeekProvider` 里确实把 `onTransportFailure` 接上了 logger；
+ *   ④ 覆盖断言：`failure.requestId` 会被写进 LlmError（从而随 `llm/retry` 落进会话日志）。
+ *
+ * 用法：`node scripts/patches/verify-transport-diagnostics.mjs`（只读，不碰任何 session 文件）
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { requireDshScope } from '../lib/dsh-scope.mjs'
+
+// 0.6.0 F1 修复批（2026-10-14）：探不到 scope ⇒ 响亮失败（⛔ 不用假路径 —— 否则本脚本会
+// 一路"目标不在 ⇒ 跳过"，把"没验"报成"通过"）。
+let SCOPE
+try { SCOPE = requireDshScope({ what: '补丁校验（verify-transport-diagnostics）' }) }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(1) }
+const TARGET = `${SCOPE}/dsh-llm-deepseek/lib/index.js`
+const LLM = `${SCOPE}/dsh-llm/lib/index.js`
+
+let pass = 0, fail = 0
+const ok = (c, n) => { c ? (pass++, console.log(`  ✅ ${n}`)) : (fail++, console.log(`  ❌ ${n}`)) }
+
+console.log('【TRANSPORT 诊断补丁】dsh-llm-deepseek/lib/index.js')
+
+if (!existsSync(TARGET)) {
+  ok(false, `目标存在（${TARGET}）`)
+} else {
+  const src = readFileSync(TARGET, 'utf8')
+
+  // ── ① 判定语义不变（这是补丁的红线：只加可观测字段，不动三分支）────────────────
+  console.log('\n  ── ① 判定语义未变 ──')
+  const catchBlock = (src.match(/\/\* Argent hotfix \(2026-10-02\)：\*\*判定不变\*\*[\s\S]*?\n\t\t\t\} finally \{/) || [''])[0]
+  ok(/Argent hotfix \(2026-10-02\)/.test(src), '补丁标记存在')
+  const branches = [
+    /if \(timeoutOf\(watchdog\.signal, "MESSAGES_IDLE"\) !== void 0\) throw new LlmError\("DeepSeek Messages stream idle timeout", "TIMEOUT", \{ cause: error \}\);/,
+    /if \(options\.signal\?\.aborted\) throw new LlmError\("DeepSeek Messages request aborted", "ABORTED", \{ cause: error \}\);/,
+    /if \(error instanceof LlmError\) throw error;/,
+  ]
+  ok(branches.every((re) => re.test(src)), 'TIMEOUT / ABORTED / LlmError-直通 三个分支**逐字未变**')
+  const order = [
+    src.indexOf('if (timeoutOf(watchdog.signal, "MESSAGES_IDLE") !== void 0) throw new LlmError("DeepSeek Messages stream idle timeout"'),
+    src.indexOf('if (options.signal?.aborted) throw new LlmError("DeepSeek Messages request aborted"'),
+    src.indexOf('if (error instanceof LlmError) throw error;'),
+  ]
+  ok(order.every((i) => i > -1) && order[0] < order[1] && order[1] < order[2],
+    `三分支**顺序不变**（TIMEOUT → ABORTED → LlmError 直通；实测 ${JSON.stringify(order)}）`)
+  ok(/throw new LlmError\("DeepSeek Messages transport failed", "TRANSPORT", \{/.test(src),
+    'TRANSPORT 仍是"其余一律"的兜底（message 与 code 逐字未变）')
+  ok(catchBlock !== '', 'catch 块里带"判定不变"注释（人改这里时会被提醒）')
+
+  // ── ② 行为断言：把补丁插入的纯函数取出来真跑 ────────────────────────────────
+  console.log('\n  ── ② cause 形态与"已产出长度"（真跑补丁插入的函数） ──')
+  const start = src.indexOf('let argentTransportCallSeq = 0;')
+  const end = src.indexOf('/** DeepSeek provider using Messages content and native thinking replay. */', start)
+  const body = start === -1 || end === -1 ? '' : src.slice(start, end)
+  let H = null
+  try {
+    H = new Function(`${body}
+const ProviderRequestId = (id) => id;
+return { argentTransportDiagnostics, argentRecordProducedChunk, argentProducedSummary, argentRequestIdOf, argentNoteResponse, argentNoteHttpFailure, argentDescribeTransportCause, argentTransportReport, argentTransportLogLine };`)()
+  } catch (e) { ok(false, `补丁函数可独立求值（${e.message}）`) }
+  ok(H !== null && typeof H.argentTransportReport === 'function',
+    '补丁插入的纯函数可独立求值（用它们做行为断言，不依赖完整 ctx）')
+
+  if (H !== null) {
+    const conn = { streamIdleTimeoutMs: 300000 }
+    const diagFor = (opts = { provider: 'whyshu', model: 'deepseek-flash' }) => H.argentTransportDiagnostics(opts, conn)
+    const resp = (status, headers = {}) => ({ status, headers: new Headers(headers) })
+
+    // ── cause 分类 ──
+    const cases = {
+      reset: Object.assign(new TypeError('fetch failed'), { cause: Object.assign(new Error('read ECONNRESET'), { code: 'ECONNRESET', errno: -54, syscall: 'read' }) }),
+      hangup: Object.assign(new Error('socket hang up'), { code: 'ECONNRESET' }),
+      etimedout: Object.assign(new Error('connect ETIMEDOUT 1.2.3.4:443'), { code: 'ETIMEDOUT', syscall: 'connect', errno: -60 }),
+      earlyClose: Object.assign(new TypeError('terminated'), { cause: Object.assign(new Error('other side closed'), { code: 'UND_ERR_SOCKET' }) }),
+      aborted: Object.assign(new Error('This operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' }),
+      refused: Object.assign(new TypeError('fetch failed'), { cause: Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' }) }),
+    }
+    // `report.cause` = 描述 `error.cause ?? error` —— undici 常把真因藏在 cause 上，
+    // 所以断言一律走 report（这才是真正写进日志的那个形态）。
+    const kindOf = (e) => H.argentTransportReport(diagFor(), e, conn).cause.kind
+    const kinds = Object.fromEntries(Object.entries(cases).map(([k, e]) => [k, kindOf(e)]))
+    ok(kinds.reset === 'ECONNRESET', `ECONNRESET（undici 常见形态：TypeError fetch failed + cause.code）⇒ kind=${kinds.reset}`)
+    ok(kinds.hangup === 'ECONNRESET', `socket hang up ⇒ kind=${kinds.hangup}`)
+    ok(kinds.etimedout === 'ETIMEDOUT', `ETIMEDOUT ⇒ kind=${kinds.etimedout}`)
+    ok(kinds.earlyClose === 'EARLY_CLOSE', `提前关闭（terminated / other side closed / UND_ERR_SOCKET）⇒ kind=${kinds.earlyClose}`)
+    ok(H.argentTransportReport(diagFor(), cases.earlyClose, conn).causeChain[1]?.code === 'UND_ERR_SOCKET',
+      '内层原始 code（UND_ERR_SOCKET）仍逐字保留在 causeChain 里（kind 只是给人看的上位分类）')
+    ok(kinds.aborted === 'AbortError', `AbortError 可区分（不误判成网络错）⇒ kind=${kinds.aborted}`)
+    ok(kinds.refused === 'ECONNREFUSED', `ECONNREFUSED ⇒ kind=${kinds.refused}`)
+    // 单节点版只看自己：外层 `fetch failed` 没有 code 时归 FETCH_FAILED（链在 report.causeChain 里）
+    ok(H.argentDescribeTransportCause(cases.reset).kind === 'FETCH_FAILED',
+      '单节点描述不被内层 cause 污染（外层 fetch failed 归 FETCH_FAILED，真因在 causeChain 里）')
+    const chain = H.argentTransportReport(diagFor(), cases.reset, conn).causeChain
+    ok(chain.length === 2 && chain[0].kind === 'FETCH_FAILED' && chain[1].kind === 'ECONNRESET',
+      `cause 链被完整摊开（外层 fetch failed → 内层 ECONNRESET；实测 ${JSON.stringify(chain.map((c) => c.kind))}）`)
+    ok(chain[1].errno === '-54' && chain[1].syscall === 'read', 'errno/syscall 被带上（定位连接层用）')
+
+    // ── 已产出长度 ──
+    const d0 = diagFor()
+    const r0 = H.argentTransportReport(d0, cases.hangup, conn)
+    ok(r0.produced.chunks === 0 && r0.produced.anyOutput === false,
+      '**尚无任何输出**的回合：chunks=0 且 anyOutput=false（这正是"可安全重试"的判据）')
+
+    const d1 = diagFor()
+    H.argentRecordProducedChunk(d1, { type: 'block-start', index: 0, blockType: 'text' })
+    H.argentRecordProducedChunk(d1, { type: 'text-delta', index: 0, text: '你好世界' })
+    H.argentRecordProducedChunk(d1, { type: 'reasoning-delta', index: 1, text: '想一想' })
+    H.argentRecordProducedChunk(d1, { type: 'tool-call-delta', index: 2, id: 'c1', name: 'flow_failures', argumentsDelta: '{"flow":' })
+    const r1 = H.argentTransportReport(d1, cases.earlyClose, conn)
+    ok(r1.produced.chunks === 4 && r1.produced.anyOutput === true,
+      `**已产出内容**的回合被识别出来（${JSON.stringify(r1.produced)}）`)
+    ok(r1.produced.textChars === 4 && r1.produced.reasoningChars === 3 && r1.produced.toolCallChars === 8,
+      `分类计数正确：text=${r1.produced.textChars} reasoning=${r1.produced.reasoningChars} toolArgs=${r1.produced.toolCallChars}`)
+    ok(r1.produced.toolCallNames.length === 1 && r1.produced.toolCallNames[0] === 'flow_failures',
+      '工具名被记下（判断"是否已经开始产生副作用"用）')
+    H.argentRecordProducedChunk(d1, { type: 'finish', reason: { kind: 'stop' } })
+    ok(H.argentProducedSummary(d1).settled === true, 'finish/usage 会标记 settled')
+
+    // ── 请求标识（streamId）与 HTTP 状态 ──
+    const d2 = diagFor()
+    H.argentNoteResponse(d2, resp(200, { 'x-request-id': 'req-abc-123' }))
+    const r2 = H.argentTransportReport(d2, cases.earlyClose, conn)
+    ok(r2.requestId === 'req-abc-123' && r2.httpStatus === 200,
+      `响应头里的 provider 请求标识被抓到（requestId=${r2.requestId}, status=${r2.httpStatus}）`)
+    const d3 = diagFor()
+    H.argentNoteResponse(d3, resp(200, { 'request-id': 'rid-1' }))
+    H.argentNoteResponse(d3, resp(200, { 'x-deepseek-request-id': 'rid-2' }))
+    ok(H.argentRequestIdOf(new Headers({ 'request-id': 'a' })) === 'a'
+      && H.argentRequestIdOf(new Headers({ 'x-request-id': 'b' })) === 'b'
+      && H.argentRequestIdOf(new Headers({})) === undefined,
+      '三个头按同一优先级取值（request-id → x-request-id → x-deepseek-request-id）')
+
+    // ── 非 2xx + 响应体片段 ──
+    const d4 = diagFor()
+    H.argentNoteHttpFailure(d4, resp(502, { 'x-request-id': 'gw-1' }), '<html><body>502 Bad Gateway</body></html>')
+    const r4 = H.argentTransportReport(d4, Object.assign(new Error('invalid response status'), { code: 'HPE_INVALID_STATUS' }), conn)
+    ok(r4.httpStatus === 502 && /502 Bad Gateway/.test(r4.bodySnippet),
+      `非 2xx 的状态码与响应体片段被记下（status=${r4.httpStatus}, snippet=${JSON.stringify(r4.bodySnippet)}）`)
+    const longBody = 'x'.repeat(5000)
+    const d5 = diagFor()
+    H.argentNoteHttpFailure(d5, resp(500), longBody)
+    ok(H.argentTransportReport(d5, cases.hangup, conn).bodySnippet.length === 400,
+      '响应体片段被截断到 400 字符（不刷屏）')
+
+    // ── 日志行：可 grep + 关键字段齐全 ──
+    const line = H.argentTransportLogLine(r2)
+    ok(line.startsWith('[argent-transport] '), '日志行以固定前缀 `[argent-transport]` 开头（便于 grep）')
+    for (const field of ['route=whyshu/deepseek-flash', 'callId=', 'providerRequestId=req-abc-123', 'httpStatus=200', 'cause=EARLY_CLOSE', 'produced={chunks:', 'elapsedMs=', 'idleTimeoutMs=300000']) {
+      ok(line.includes(field), `日志行含字段 ${field}`)
+    }
+    ok(!line.includes('\n'), '单行输出（不会被日志系统按多行拆散）')
+    const line4 = H.argentTransportLogLine(r4)
+    ok(line4.includes('bodySnippet='), '非 2xx 时日志行附 bodySnippet')
+    const line0 = H.argentTransportLogLine(r0)
+    ok(line0.includes('providerRequestId=(none)') && line0.includes('httpStatus=(no response)'),
+      '连响应都没拿到时也明确标注 (none)/(no response)，不假装有值')
+  }
+
+  // ── ③ 装配：onTransportFailure 接到 logger ────────────────────────────────
+  console.log('\n  ── ③ 装配与落盘 ──')
+  ok(/onTransportFailure: \(report\) => \{/.test(src) && /ctx\.logger\.warn\(argentTransportLogLine\(report\)\)/.test(src),
+    'registerDeepSeekProvider 把 onTransportFailure 接到 ctx.logger.warn')
+  ok(/ctx\.logger\.warn\("llm-deepseek: TRANSPORT detail %o"/.test(src),
+    '同时打一份结构化 detail（%o，供日志详情/工具解析）')
+  ok(/this\.dependencies\.onTransportFailure\?\.\(transportReport\)/.test(src),
+    '适配器侧用可选链调用（第三方复用 registerDeepSeekProvider 时不会因缺回调而炸）')
+  ok(/\.\.\.transportReport\.requestId === void 0 \? \{\} : \{ requestId: transportReport\.requestId \}/.test(src),
+    'requestId 被写进 LlmError 的字段 ⇒ `failure.requestId` 随 `llm/retry` 事件落进会话日志')
+  ok(/const transportDiagnostics = argentTransportDiagnostics\(options, connection\);/.test(src)
+    && /argentRecordProducedChunk\(transportDiagnostics, next\.value\);/.test(src),
+    'generate() 里每产出一片就记一次（`yield` 之前，故计数与消费端所见一致）')
+
+  // ── ④ LlmError 真的保留 requestId（跨包契约，非本补丁可改）──────────────────
+  if (existsSync(LLM)) {
+    const llmSrc = readFileSync(LLM, 'utf8')
+    ok(/\.\.\.options\?\.requestId === void 0 \? \{\} : \{ requestId: options\.requestId \}/.test(llmSrc),
+      'dsh-llm 的 LlmError 会把 requestId 保留进 .failure（本补丁依赖该既有契约，未改动它）')
+    // 但"落进会话日志"还差三段链路，逐一钉住（否则 requestId 会停在内存里）：
+    //   适配器 throw ⇒ LlmRuntime 的 adapterFailureChunk 转成终态 finish 块
+    //   ⇒ normalizeLlmFailure 取 error.failure 快照 ⇒ failureSnapshot 白名单里必须有 requestId
+    ok(/function adapterFailureChunk\(error, signal\)/.test(llmSrc)
+      && /kind: "error",\s*\n\s*failure/.test(llmSrc),
+      '抛出的适配器错误被 LlmRuntime 转成终态 finish 块（这才是 `agent/request-error` 被触发的路径）')
+    ok(/function normalizeLlmFailure\(value\)/.test(llmSrc)
+      && /const carried = ownFailureSnapshot\(error\);\s*\n\s*if \(carried !== void 0 && carried\.code === ownErrorCode\(error\)\) return carried;/.test(llmSrc),
+      'normalizeLlmFailure 直接复用 LlmError 自带的 .failure 快照（code 一致时）—— requestId 不会被丢掉')
+    ok(/const requestId = candidate\.requestId;/.test(llmSrc)
+      && /\.\.\.requestId === void 0 \? \{\} : \{ requestId \}/.test(llmSrc),
+      'failureSnapshot 的白名单里有 requestId（也校验类型，非空字符串才放行）')
+    // 端到端（真造一个 LlmError，走同一段 normalize 逻辑）：确认 requestId 真的留在 failure 里
+    const { LlmError } = await import(LLM)
+    const probe = new LlmError('DeepSeek Messages transport failed', 'TRANSPORT', {
+      cause: new Error('read ECONNRESET'),
+      requestId: 'req_probe_1',
+    })
+    ok(probe.failure.requestId === 'req_probe_1' && probe.failure.code === 'TRANSPORT' && probe.failure.message === 'DeepSeek Messages transport failed',
+      `端到端：TRANSPORT 的 LlmError 带出 {code, message, requestId}（实测 ${JSON.stringify(probe.failure)}）`)
+    const noId = new LlmError('DeepSeek Messages transport failed', 'TRANSPORT', { cause: new Error('x') })
+    ok(noId.failure.requestId === undefined && Object.keys(noId.failure).sort().join(',') === 'code,message',
+      '没拿到请求标识时不会伪造：failure 仍是 {message, code}（与既有行为一致）')
+  }
+}
+
+console.log(`\n── 合计：通过 ${pass} / 失败 ${fail}`)
+if (fail > 0) {
+  console.log('❌ TRANSPORT 诊断补丁校验未通过：补丁可能没打上或上游已改动 —— 先别重启，见 docs / AGENTS.md')
+  process.exit(1)
+}
+console.log('✅ TRANSPORT 诊断补丁校验通过：cause / streamId / 已产出长度均可观测，判定语义未变')