@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/repair-unresolved-tools.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * repair-unresolved-tools.mjs — 修复"step/end 时存在未解决 tool call"的 v4 session。
+ *
+ * 背景（2026-09-29）：0.1.7 初版加固补丁 `dsh-session--tool-result-block-017.patch` 的
+ * "message 必须含 tool-result block" 规则与 v4 形态矛盾（v4 中该 wrapper 是 retired syntax，
+ * 迁移器会把 tool/result 展开为 text block），导致合法的 tool/result 在 append 边界被拒：
+ *   - tool/result 写入失败 → step/end 时悬挂未解决的 tool call
+ *   - session 只能加载失败（"stored log is corrupt: step/end leaves unresolved tool call"）
+ * 修正版补丁已上线；本脚本用于修复已被毒化的存量 session。
+ *
+ * 修复原理：对每个未解决点，把前缀交给 dsh 官方 `interruptedTurnClosers` 生成
+ * 补齐事件（tool/result、isError、ToolOutcomeUnknownError / ToolNotStartedError），
+ * 插入后对后续事件 seq 顺移并修正内部引用（surfaceOp/sourceEventSeqs/messageSeqs/headerSeq）。
+ *
+ * 用法：
+ *   node repair-unresolved-tools.mjs --scan                        扫描全部
+ *   node repair-unresolved-tools.mjs --repair <id> [--dir <path>]  预演（不写盘）
+ *   node repair-unresolved-tools.mjs --repair <id> --apply         写盘（自动备份 .bak）
+ */
+// 2026-09-29 修：原实现写死开发机路径 `/opt/homebrew/lib/...` ⇒ 客户机（node 官方包，
+// 树在 ~/node/lib/node_modules）一跑就 ERR_MODULE_NOT_FOUND。按仓库规矩走共享解析器，
+// 且用**动态 import**（scope 要到运行时才知道）。
+// 0.6.0 F1 修复批（2026-10-14）：本脚本**必须**有宿主树（`interruptedTurnClosers` 从它 import）
+// ⇒ 探不到就**响亮失败**（⛔ 不用假路径 —— 旧写法在 npx 宿主上会拿一个不存在的树去 import）。
+import { requireDshScope } from './lib/dsh-scope.mjs';
+let _SCOPE;
+try { _SCOPE = requireDshScope({ what: '未决工具修复（repair-unresolved-tools）' }); }
+catch (e) { console.error(`  ❌ ${e.message}`); process.exit(1); }
+const { interruptedTurnClosers } = await import(`${_SCOPE}/dsh-session/lib/index.js`);
+import { zstdCompress, zstdDecompress, constants } from 'node:zlib';
+import { promisify } from 'node:util';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+
+const zstdCompressAsync = promisify(zstdCompress);
+const CHECKSUM_OPTIONS = { params: { [constants.ZSTD_c_checksumFlag]: 1 } };
+const SESSIONS_ROOT = path.join(os.homedir(), '.dsh', 'sessions');
+
+// ---------- 工具 ----------
+function findSessionDir(id) {
+  for (const proj of fs.readdirSync(SESSIONS_ROOT)) {
+    const p = path.join(SESSIONS_ROOT, proj, id);
+    if (fs.existsSync(path.join(p, 'session.v4.jsonl.zstd'))) return p;
+  }
+  return null;
+}
+
+async function readLog(file) {
+  // 注意：node:zlib 的 zstdDecompress 只解第一帧；多帧文件须用 zstd CLI 全量解压
+  const raw = execFileSync('zstd', ['-d', '-c', file], { maxBuffer: 1 << 30 });
+  const lines = raw.toString('utf8').trim().split('\n');
+  return { header: JSON.parse(lines[0]), events: lines.slice(1).map(l => JSON.parse(l)) };
+}
+
+async function writeLog(file, header, events) {
+  const headerLine = JSON.stringify(header) + '\n';
+  const body = events.map(e => JSON.stringify(e)).join('\n') + '\n';
+  const f1 = await zstdCompressAsync(Buffer.from(headerLine), CHECKSUM_OPTIONS);
+  const f2 = await zstdCompressAsync(Buffer.from(body), CHECKSUM_OPTIONS);
+  fs.writeFileSync(file, Buffer.concat([f1, f2]));
+}
+
+/** 检测未解决点：step/end（或 turn/end）时 pendingCalls 非空 */
+function analyze(events) {
+  const pending = new Map();
+  const issues = [];
+  for (let i = 0; i < events.length; i++) {
+    const ev = events[i], t = ev.type, d = ev.data || {};
+    if (t === 'turn/start') pending.clear();
+    else if (t === 'turn/end') { if (pending.size) issues.push({ index: i, type: 'turn/end', pending: [...pending.entries()] }); pending.clear(); }
+    else if (t === 'step/end') { if (pending.size) issues.push({ index: i, type: 'step/end', pending: [...pending.entries()] }); pending.clear(); }
+    else if (t === 'assistant/message') {
+      for (const b of (d.message?.content || [])) if (b.type === 'tool-call') pending.set(b.id, { step: d.step });
+    } else if (t === 'tool/call') {
+      const e = pending.get(d.callId); if (e) e.callSeq = ev.seq;
+    } else if (t === 'tool/result') {
+      pending.delete(d.message?.source?.callId);
+    }
+  }
+  return issues;
+}
+
+/** 顺移事件内部引用 */
+function shiftRefs(ev, fromSeq, delta) {
+  const d = ev.data || {};
+  if (d.surfaceOp && typeof d.surfaceOp === 'object') {
+    if (typeof d.surfaceOp.startSeq === 'number' && d.surfaceOp.startSeq >= fromSeq) d.surfaceOp.startSeq += delta;
+    if (typeof d.surfaceOp.endSeq === 'number' && d.surfaceOp.endSeq >= fromSeq) d.surfaceOp.endSeq += delta;
+  }
+  if (Array.isArray(d.sourceEventSeqs)) d.sourceEventSeqs = d.sourceEventSeqs.map(s => (typeof s === 'number' && s >= fromSeq) ? s + delta : s);
+  if (Array.isArray(d.messageSeqs)) d.messageSeqs = d.messageSeqs.map(s => (typeof s === 'number' && s >= fromSeq) ? s + delta : s);
+  if (typeof d.headerSeq === 'number' && d.headerSeq >= fromSeq) d.headerSeq += delta;
+}
+
+/** 修复一个会话的事件流（返回修复后事件数组 + 修复报告） */
+function repair(events) {
+  const issues = analyze(events);
+  if (issues.length === 0) return { events, fixes: [] };
+  let fixed = structuredClone(events);
+  const fixes = [];
+  // 从后往前修，避免编号漂移
+  for (const issue of issues.reverse()) {
+    const insertAt = issue.index; // 该 step/end（或 turn/end）在 fixed 中的位置
+    const prefix = fixed.slice(0, insertAt);
+    const closers = interruptedTurnClosers(prefix);
+    const results = closers.filter(c => c.type === 'tool/result');
+    if (results.length === 0) { fixes.push({ at: insertAt, note: 'closers 未产出（跳过）' }); continue; }
+    const insertSeq = prefix.length > 0 ? prefix.at(-1).seq + 1 : 0;
+    // 原事件（step/end 起）顺移
+    const tail = fixed.slice(insertAt).map(ev => {
+      const copy = structuredClone(ev);
+      copy.seq += results.length;
+      shiftRefs(copy, insertSeq, results.length);
+      return copy;
+    });
+    fixed = [...prefix, ...results, ...tail];
+    fixes.push({ at: insertAt, inserted: results.length, seq: insertSeq, calls: results.map(r => r.data.message.source.callId) });
+  }
+  // 连续性校验
+  for (let i = 0; i < fixed.length; i++) {
+    if (fixed[i].seq !== i) throw new Error(`修复后 seq 断裂 at index ${i}: got ${fixed[i].seq}`);
+  }
+  return { events: fixed, fixes };
+}
+
+// ---------- 主流程 ----------
+const args = process.argv.slice(2);
+const mode = args.includes('--scan') ? 'scan' : args.includes('--repair') ? 'repair' : null;
+const apply = args.includes('--apply');
+const id = args[args.indexOf('--repair') + 1];
+
+if (mode === 'scan') {
+  let checked = 0, broken = 0;
+  for (const proj of fs.readdirSync(SESSIONS_ROOT)) {
+    for (const sess of fs.readdirSync(path.join(SESSIONS_ROOT, proj))) {
+      const f = path.join(SESSIONS_ROOT, proj, sess, 'session.v4.jsonl.zstd');
+      if (!fs.existsSync(f)) continue;
+      checked++;
+      try {
+        const { events } = await readLog(f);
+        const issues = analyze(events);
+        if (issues.length) {
+          broken++;
+          console.log(`☠ ${sess}  (${issues.length} 个未解决点)`);
+          for (const is of issues) console.log(`    ${is.type} · 缺失: ${is.pending.map(([c]) => c).join(', ')}`);
+        }
+      } catch (e) {
+        console.log(`?! ${sess}: ${e.message}`);
+      }
+    }
+  }
+  console.log(`\n扫描 ${checked} 个 v4 文件；损坏 ${broken} 个`);
+} else if (mode === 'repair' && id) {
+  const dir = findSessionDir(id);
+  if (!dir) { console.error(`找不到会话: ${id}`); process.exit(1); }
+  const file = path.join(dir, 'session.v4.jsonl.zstd');
+  const { header, events } = await readLog(file);
+  console.log(`会话 ${id}: ${events.length} 事件`);
+  const issues = analyze(events);
+  if (!issues.length) { console.log('✓ 健康，无需修复'); process.exit(0); }
+  console.log(`发现 ${issues.length} 个未解决点`);
+  const { events: fixed, fixes } = repair(events);
+  for (const fx of fixes) console.log('  修复:', JSON.stringify(fx));
+  console.log(`修复后: ${fixed.length} 事件，seq 0..${fixed.at(-1).seq}`);
+  if (!apply) {
+    console.log('\n[预演] 未写盘。加 --apply 执行（自动备份 .bak-<ts>）');
+  } else {
+    const bak = `${file}.bak-${Date.now()}`;
+    fs.copyFileSync(file, bak);
+    await writeLog(file, header, fixed);
+    console.log(`\n✓ 已写盘。备份: ${bak}`);
+  }
+} else {
+  console.log('用法:\n  node repair-unresolved-tools.mjs --scan\n  node repair-unresolved-tools.mjs --repair <session-id> [--apply]');
+}

package/engine/scripts/run-tests.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# 全量测试入口（2026-09-30 补：本仓库此前有 123 个测试却无总入口 ⇒ 门禁无法一键复验）
+#
+# 用法：
+#   bash scripts/run-tests.sh [--filter <关键字>] [--skip <子串>]...
+#   bash scripts/run-tests.sh --clean-tree-check [--filter <关键字>]
+#   bash scripts/run-tests.sh --print-git-skips [<树>]     # 测试钩子：打印该树里因缺 .git 要跳过的用例
+#   · *.test.mjs → node
+#   · *.test.py  → venv python（缺 venv 则回落系统 python3）
+# 退出码：任一失败即 1；末尾打印通过/失败计数与失败清单。
+#
+# `--clean-tree-check` = **干净树自检**：`git archive HEAD` 解到临时目录后跑**同一套**判据，
+# 用来判"HEAD 既存红"（提交本身就是红的）。它**自动规避三类环境性假红**（2026-10-08 固化）：
+#   ① `/tmp` → `/private/tmp` 符号链接（用 `pwd -P` 的物理路径建树并 `cd` 进去）；
+#   ② git 不跟踪的空目录（`git archive` 不带 ⇒ `ENOENT`），自动镜像 —— **通用兜底**；
+#      `scripts/flow-prompts/` 曾是唯一实例，该用例的根因已于 2026-10-08 修（用例容忍缺目录）；
+#   ③ **需要 `.git` 的用例**（裸检出没有 `.git`）按**判据 `[ -d .git ]`** 跳过、点名原因
+#      （判据在 `git_index_skips()` 一处；候选见 `NEED_GIT_CANDIDATES`）。
+# 判据与两条假红的区别见 docs/CI-自建runner.md §8.1「两类假红」。保树调试：`ARGENT_CLEAN_TREE_KEEP=1`。
+set -uo pipefail
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO"
+PY="$HOME/.dsh/argent/venv/bin/python3"; [ -x "$PY" ] || PY=python3
+# 测试期间**绝不发遥测**（2026-09-30：夹具流程 flowA 的失败事件曾被推到生产告警）
+export ARGENT_TELEMETRY_OFF=1
+export ARGENT_TESTS_OFFLINE=1   # 测试期**零网络**（2026-10-11）：监听类用例（dsh-release-watch 等）见到它就**拒绝**真发请求 ⇒ "夹具回归零网络"由开关兜住，不靠自觉
+# 测试进程**不继承会话/实例的 DSH_HOME**（2026-10-02）：
+#   DSH_HOME 是**实例级**开关，而数据目录三级链把它排在"默认 ~/.dsh/argent"之前 ⇒
+#   测试用假 HOME 隔离时会被会话的 DSH_HOME 覆盖，**静默写进真实实例**（实测：本机
+#   DSH_HOME=~/.dsh 时，role-mapping/skin/设置页用例把 roles.json、skin.json 写进了生产数据目录）。
+#   故跑测试时清掉它（venv 解释器先落成 ARGENT_PY，避免清掉后找不到 venv）。
+if [ -z "${ARGENT_PY:-}" ] && [ -x "${DSH_HOME:-$HOME/.dsh}/argent/venv/bin/python3" ]; then
+  export ARGENT_PY="${DSH_HOME:-$HOME/.dsh}/argent/venv/bin/python3"
+fi
+unset DSH_HOME
+
+# ── 「需要 git 索引」的用例：**按判据跳过**，⛔ 不是一份"永远跳过"的静态名单 ──────────────
+# 判据只有一个：**被跑的树里有没有 `.git`**（`[ -d .git ]`）。
+#   · 树里有 `.git` ⇒ 这些用例**照常跑**（它们的判据本身就是"仓库/工作树状态"）；
+#   · 树里没有（`git archive HEAD` 出来的裸检出）⇒ 显式跳过并**点名原因**（这才是"干净树不适用"）。
+# 为什么必须判据驱动（2026-10-14 批）：③ 的实例里 `agent-title-naming` / `dead-pointer-scan`
+# 靠 `git ls-files` 列受控文件 ⇒ 裸检出（没有索引）里恒红，是**检查器**的缺陷，不是用例的问题。
+# ⛔ 不许因此改那两条用例的判据、⛔ 不许把它们删掉 —— 只在这里按 `.git` 的有无跳过。
+NEED_GIT_CANDIDATES=(
+  # release-dl：跑 release-argent.sh，它做 git status / git rev-parse refs/tags
+  release-dl
+  # install-capabilities：【7b】完整安装以本仓为克隆源（ARGENT_REPO_URL=<repo>）⇒ 需 .git
+  install-capabilities
+  # install-registry-loadable：按设计要读工作树/仓库身份（`git rev-parse` 一类）
+  install-registry-loadable
+  # agent-title-naming：`git ls-files -z` 列受控文本文件（裸检出没有索引 ⇒ execFileSync 抛）
+  agent-title-naming
+  # dead-pointer-scan：同上（`git ls-files -z` 列受控文件）
+  dead-pointer-scan
+)
+
+# 该树里**因缺 `.git`** 要跳过的用例子串（一行一个；有 `.git` ⇒ 零行）。
+# ⭐ 这是判据的**唯一实现**：干净树分支与回归夹具（`scripts/tests/clean-tree-git-skips.test.mjs`）
+#    都调它，⛔ 不写第二份名单。
+git_index_skips() {
+  local tree="${1:-.}"
+  [ -d "$tree/.git" ] || printf '%s\n' "${NEED_GIT_CANDIDATES[@]}"
+}
+
+# ── 参数解析（**默认行为不变**：不带参数 = 跑全量套件）──────────────────────────────
+MODE="run"; FILTER=""; SKIP=()
+while [ $# -gt 0 ]; do
+  case "${1:-}" in
+    --filter) FILTER="${2:-}"; if [ $# -ge 2 ]; then shift 2; else shift; fi ;;
+    --skip)   if [ $# -ge 2 ] && [ -n "${2:-}" ]; then SKIP+=("$2"); shift 2
+              else echo "  ✗ --skip 需要一个非空子串（用法见 bash scripts/run-tests.sh --help）"; exit 2; fi ;;
+    --clean-tree-check) MODE="clean-tree"; shift ;;
+    --print-git-skips) git_index_skips "${2:-.}"; exit 0 ;;
+    -h|--help) sed -n '4,19p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "  ✗ 未知参数：$1（用法见 bash scripts/run-tests.sh --help）"; exit 2 ;;
+  esac
+done
+
+# 命中任一 --skip 子串 ⇒ 跳过（与 --filter 同样按路径子串匹配）
+skip_match() {
+  local f="$1" s
+  for s in ${SKIP[@]+"${SKIP[@]}"}; do [ -n "$s" ] && [[ "$f" == *"$s"* ]] && return 0; done
+  return 1
+}
+
+# ── `--clean-tree-check`：先建干净树并规避三类环境性假红，再把自己重跑一遍（判据不变）──────
+if [ "$MODE" = "clean-tree" ]; then
+  if [ "${ARGENT_CLEAN_TREE_PHASE:-}" = "1" ]; then
+    echo "  ✗ 已经在干净树自检的子里程里了（不要嵌套）——直接跑 bash scripts/run-tests.sh 即可"; exit 2
+  fi
+  command -v git >/dev/null 2>&1 || { echo "  ✗ 需要 git（干净树自检靠 git archive HEAD 取树）"; exit 2; }
+  git -C "$REPO" rev-parse --verify HEAD >/dev/null 2>&1 || {
+    echo "  ✗ $REPO 不是一个带 HEAD 的 git 仓 —— 干净树自检要在**有 .git 的检出**里发起"
+    echo "    （它取的是 HEAD 的内容；在裸检出里无从取树）"; exit 2; }
+
+  CLEAN_DIR="$(mktemp -d "${TMPDIR:-/tmp}argent-clean-tree-XXXXXX")" || exit 2
+  if [ "${ARGENT_CLEAN_TREE_KEEP:-}" != "1" ]; then
+    trap 'rm -rf "$CLEAN_DIR"' EXIT INT TERM
+  fi
+  git -C "$REPO" archive HEAD | tar -x -C "$CLEAN_DIR" || { echo "  ✗ git archive HEAD 取树失败"; exit 2; }
+
+  # 闸门：**取出来的那棵树里的 `run-tests.sh` 必须认识 `--skip`**。
+  # 为什么必须有它（2026-10-08 实测踩到）：干净树取自 `HEAD`，若本次改动**还没提交**，
+  # 树里就是**旧版**脚本 —— 而旧版**静默忽略**未知参数 ⇒ `--skip`/`--filter` 全部失效、
+  # 跑成"全量 + 那 2 条按设计跳过的用例照样红" ⇒ 输出看起来像"干净树有 4 条红"，
+  # **把环境性假红伪装成 HEAD 既存红**（正是本自检要消灭的误导）。宁可当场停下，也不给假结论。
+  if ! grep -q -- '--skip)' "$CLEAN_DIR/scripts/run-tests.sh" 2>/dev/null; then
+    echo "  ✗ HEAD 里的 scripts/run-tests.sh 还是旧版（不认识 --skip）——多半是本次改动尚未提交。"
+    echo "    裸检出取的是 HEAD 的内容 ⇒ 现在跑只会得到**误导性**结果（--skip/--filter 被静默忽略）。"
+    echo "    处置：先 commit（或先把新版 run-tests.sh 提交），再跑 --clean-tree-check。"
+    exit 2
+  fi
+
+  # ① 真实路径：`/tmp` → `/private/tmp`（macOS 亦含 `/var` → `/private/var`）是符号链接。
+  #    若沿用逻辑路径 `$PWD`，node 侧（`import.meta.url` 走 realpath）与 bash 侧（`pwd` 走 `$PWD`）
+  #    会各说各话 ⇒ `repo-root` 用例句"开发机：解析到本仓"恒红。故一律 `pwd -P` 取物理路径再 cd 进去。
+  REAL="$(cd "$CLEAN_DIR" && pwd -P)" || exit 2
+  cd "$REAL"
+
+  # ② git **不跟踪空目录** ⇒ `git archive` 自然不带 ⇒ 裸检出里没有该目录。
+  #    **历史实例**：`scripts/flow-prompts/`（`check-sop-consistency.mjs` 的 C2 曾无条件 readdirSync 它
+  #    ⇒ 真·新克隆上 ENOENT 判红）。**该条根因已于 2026-10-08 修**（用例容忍缺目录，
+  #    见 `legacyPromptFiles()`）⇒ 本步骤现在只是**通用兜底**：对**其它**未跟踪空目录仍然必要。
+  #    只镜像**空目录**：内容为空 ⇒ 不可能夹带任何在制品，纯粹补回"目录存在"这个事实。
+  MIRRORED=()
+  while IFS= read -r d; do
+    [ -n "$d" ] || continue
+    rel="${d#./}"
+    [ -d "$REAL/$rel" ] && continue
+    mkdir -p "$REAL/$rel" && MIRRORED+=("$rel")
+  done < <(cd "$REPO" && find . -type d -empty -not -name .git -not -name node_modules -not -path '*/.git/*' -not -path '*/node_modules/*' 2>/dev/null | sort)
+
+  # ③ 需要 `.git` 的用例：**干净树不适用**（裸检出没有 `.git`，它们查的是"仓库/工作树状态"，
+  #    不是被测代码本身）。⭐ **判据 = `[ -d .git ]`**（实现在 `git_index_skips()` 一处）：
+  #    树里有 `.git` ⇒ 照常跑；没有 ⇒ 跳过并点名原因。⛔ **不因此改用例语义**、⛔ 不删用例。
+  NEED_GIT=()
+  while IFS= read -r g; do [ -n "$g" ] && NEED_GIT+=("$g"); done < <(git_index_skips "$REAL")
+
+  echo
+  echo "  ═══ 干净树自检（HEAD=$(git -C "$REPO" rev-parse --short HEAD)，不含工作树在制品）═══"
+  echo "     树位置：$REAL"
+  echo "     ① 符号链接：已用 pwd -P 的**物理路径**建树并 cd（规避 /tmp → /private/tmp）"
+  if [ "${#MIRRORED[@]}" -gt 0 ]; then
+    echo "     ② 未跟踪空目录：已镜像 ${#MIRRORED[@]} 个 —— ${MIRRORED[*]}"
+  else
+    echo "     ② 未跟踪空目录：无（无需镜像）"
+  fi
+  if [ -d "$REAL/.git" ]; then
+    echo "     ③ 需要 .git 的用例：判据 \`[ -d .git ]\` ⇒ 这棵树**有** .git ⇒ 全部照常跑（0 条跳过）"
+  else
+    echo "     ③ 需要 .git 的用例：判据 \`[ -d .git ]\` ⇒ 这棵树**没有** .git ⇒ 按设计跳过 ${#NEED_GIT[@]} 条 —— ${NEED_GIT[*]}"
+    echo "        · release-dl：跑 release-argent.sh --help，该脚本做 git status / git rev-parse refs/tags"
+    echo "        · install-capabilities：【7b】完整安装以本仓为克隆源（ARGENT_REPO_URL=<repo>）⇒ 需 .git"
+    echo "        · install-registry-loadable：按设计要读工作树/仓库身份（\`git rev-parse\` 一类）"
+    echo "        · agent-title-naming / dead-pointer-scan：靠 \`git ls-files\` 列受控文件 ⇒ 裸检出（无索引）里必然抛（2026-10-14 复现；检查器按判据跳过，⛔ 不改用例判据、⛔ 不删用例）"
+  fi
+  echo "        ⛔ 这是「干净树不适用」，**不是红**；不得据此放宽这些用例的判据（docs/CI-自建runner.md §8.1）"
+  echo "        · 判据的唯一实现：\`bash scripts/run-tests.sh --print-git-skips <树>\`（一行一个；有 .git ⇒ 零行）"
+  echo "  ═══════════════════════════════════════════════════════════════════════"
+
+  inner=()
+  for g in "${NEED_GIT[@]}"; do inner+=(--skip "$g"); done
+  for s in ${SKIP[@]+"${SKIP[@]}"}; do inner+=(--skip "$s"); done
+  [ -n "$FILTER" ] && inner+=(--filter "$FILTER")
+  env ARGENT_CLEAN_TREE_PHASE=1 bash "$REAL/scripts/run-tests.sh" ${inner[@]+"${inner[@]}"}
+  rc=$?
+  if [ "${ARGENT_CLEAN_TREE_KEEP:-}" = "1" ]; then echo "     （树已保留：${REAL}）"; fi
+  exit $rc
+fi
+
+pass=0; fail=0; failed=(); skipped=()
+shopt -s nullglob
+
+# ── 测试环境卫生：**结果判据**（2026-10-03 两次事故后补；2026-10-04 扩成三层）──────────────
+# 为什么在这里：跑测试**前**给真实数据目录拍一份只读快照，跑完**后**比对 ⇒ 只要有任何一条
+# 路径漏了隔离、写了真实目录，就在**这一轮**被抓（不靠"下次注意"）。三层判据：
+#   ① 关键文件（skin.json / flow-ledger.jsonl / license-gate.jsonl …）的 size/mtime/sha256 —— **判红**；
+#   ② 目录级发现：全树**路径集合差**，只报"新增" —— 抓"在真实目录里新建文件"这个盲区
+#      （1016 份夹具备份就是这么溜过去的：当时①全程绿）；
+#   ③ 配置形态（`*.json`/`*.yml`/`*.yaml`/`*.toml`，排除体积区）的**内容** sha256。
+# 姿态（起步）：②③ **只报告、不改退出码**（允许表 `CHURN_ALLOW` 稳定前不判红；要判红得显式
+# `--verify <snap> --strict`）⇒ 本脚本的失败判据仍只由①与各用例决定。
+# 快照文件落在 ${TMPDIR}（不在数据目录里）；判据实现见 scripts/check-test-env-safety.mjs。
+SNAP="$(mktemp -t argent-tests-env-snapshot)"
+node scripts/check-test-env-safety.mjs --snapshot "$SNAP" >/dev/null 2>&1 || true
+
+for f in scripts/tests/*.test.mjs; do
+  [ -n "$FILTER" ] && [[ "$f" != *"$FILTER"* ]] && continue
+  if skip_match "$f"; then skipped+=("$f"); continue; fi
+  if out=$(env -u DSH_HOME node "$f" 2>&1); then pass=$((pass+1)); else fail=$((fail+1)); failed+=("$f"); printf '  ❌ %s\n%s\n' "$f" "$(printf '%s' "$out" | tail -6 | sed 's/^/     /')"; fi
+done
+for f in scripts/tests/*.test.py; do
+  [ -n "$FILTER" ] && [[ "$f" != *"$FILTER"* ]] && continue
+  if skip_match "$f"; then skipped+=("$f"); continue; fi
+  if out=$(env -u DSH_HOME "$PY" "$f" 2>&1); then pass=$((pass+1)); else fail=$((fail+1)); failed+=("$f"); printf '  ❌ %s\n%s\n' "$f" "$(printf '%s' "$out" | tail -6 | sed 's/^/     /')"; fi
+done
+echo
+if [ "${#skipped[@]}" -gt 0 ]; then
+  printf '    ⏭  按 --skip 跳过 %d 条（**不计入失败**，但它们没有在本轮被验证）：%s\n' "${#skipped[@]}" "${skipped[*]}"
+fi
+echo "  ============================================="
+printf '    测试结果：%d 通过 / %d 失败' "$pass" "$fail"
+[ "$fail" -eq 0 ] && printf ' ✓\n' || printf '\n    失败清单：%s\n' "${failed[*]}"
+echo "  ============================================="
+# 红了先分清"真问题"与"环境/在制品"：**干净树（= git archive HEAD，不含工作树在制品）也应全绿**。
+# 仍红 ⇒ HEAD 既存红（提交本身的问题，必须修）。判据与**两类假红**的区分见 docs/CI-自建runner.md §8.1。
+# 下面这条命令是**可复现**的：它自己规避符号链接、镜像未跟踪空目录、并按设计跳过需要 .git 的用例。
+[ "$fail" -eq 0 ] || echo "     ↳ 干净树判据（可复现）：bash scripts/run-tests.sh --clean-tree-check"
+
+# ── 跑完立刻比对真实数据目录（只读比较）──────────────────────────────────────────────
+# ① 变了 ⇒ 判红并点名文件（**退出码语义与以前一致**）；②③ 的发现只打印（起步姿态），不在这里判红。
+if [ -f "$SNAP" ]; then
+  if ! env -u DSH_HOME node scripts/check-test-env-safety.mjs --verify "$SNAP"; then
+    fail=$((fail+1)); failed+=("(真实数据目录被写)")
+  fi
+  rm -f "$SNAP"
+fi
+[ "$fail" -eq 0 ] || exit 1
+
+# ── 能力包闭包体检（只报告；**不**参与失败判据，2026-10-04）────────────────────────────
+# 判据：`scripts/check-pack-closure.mjs` —— 按每个能力包的 pack.engine + files 清单解析包内代码的
+#   静态 import / Python import / 子进程调用图，报"引用到、仓库里有、但不在包内"的运行期文件。
+# 为什么接在**非失败**位置：缺件可能常年存在（输出里带修法），接进失败判据就是把门禁变成恒红陷阱；
+#   真要有非零判据请单独跑 `node scripts/check-pack-closure.mjs --strict`（或接进 CI）。
+# 全量跑时打一次基线，让"包内容漂移"不会悄悄发生；`--filter` 迭代时不跑（省时间）。
+# 位置在 provider 装配巡检之前：那一段是最后一块且不改变退出码（本段同样不改变）。
+if [ -z "$FILTER" ] && [ -f "$REPO/scripts/check-pack-closure.mjs" ]; then
+  echo
+  if closure=$(env -u DSH_HOME node "$REPO/scripts/check-pack-closure.mjs" --quiet 2>&1); then
+    printf '%s\n' "$closure" | sed '/^[[:space:]]*$/d; s/^/  /'
+    case "$closure" in
+      *"缺件 0 个"*) ;;
+      *) echo "     ↳ 缺件修法：写进 scripts/flow-requirements.json#pack.engine（core 件另进 CORE_KEY），"
+         echo "        再提三个带 flow 的能力包版本 + python3 scripts/capability_pack.py --stamp；详见 docs/README.md §六.13" ;;
+    esac
+  else
+    echo "  ⚠️ 能力包闭包体检没跑成（exit≠0，多半是 python 不可用）—— 手动跑 node scripts/check-pack-closure.mjs"
+  fi
+fi
+
+# ── 生产状态守卫（2026-09-30 加；2026-10-02 口径更新）：跑完测试立刻做一次 **provider 装配巡检** ──
+# 背景（历史）：`~/.dsh/settings.yaml` 会被"自身 schema 重写"丢掉未知的 `llm-deepseek` 段 ⇒ 当时那套
+# 「计费模式」静默退回直连（实测：文件只剩 1 字节）。**那套机制已移除** —— 现在是两个独立 provider
+# 并存（官方直连 / 问述代理），由用户在输入框的模型选择器里选 ⇒ 判据变成「**组合声明了的** provider
+# 有没有装上」：exit 1 = 声明了却没装上；exit 2 = 无法判定（组合树读不到）。
+if [ -x "$REPO/scripts/check-billing-mode.sh" ]; then
+  if ! bash "$REPO/scripts/check-billing-mode.sh" >/tmp/billing-guard.out 2>&1; then
+    echo
+    echo "  ⚠️ provider 装配守卫：组合**声明了**的 provider 没装上（exit 1）或无法判定（exit 2）"
+    sed 's/^/     /' /tmp/billing-guard.out
+    echo "     ↳ 处置（**请手动执行**）：bash scripts/provider-select.sh status 看当前默认 provider；"
+    echo "       要切换用 bash scripts/provider-select.sh {whyshu|deepseek}（改完需重启 dsh）。"
+    echo "       ⛔ 不要用 check-billing-mode.sh --fix（已熔断 exit 3）：它会诱使人改官方 provider 的 baseURL。"
+    # 不再因此失败：**用户有权选择官方直连**（2026-09-30 纠正）。只大声提示，不阻断。
+  fi
+fi

package/engine/scripts/self-sign-license.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * self-sign-license —— **离线自签**一份许可（演练 / 测试 / 无服务端时跑通离线激活闭环），2026-10-03
+ *
+ * ## 它解决什么
+ * 离线激活闭环是「`license request` 拿设备码 → 服务端签发 v2 许可 → `install --file`」。
+ * 没有服务端在场时（开发机、隔离环境、客户现场演练）这条链路跑不通 ⇒ 本工具用**本地密钥**
+ * 按**同一份载荷契约**签一份，让闭环可验（`core/lib/license-file.mjs#signLicenseFile` 是唯一实现，
+ * 本脚本不重写载荷构造）。
+ *
+ * ## ⛔ 三条硬约束（都是刻意的摩擦，不是遗漏）
+ *   ① **密钥必须显式**：只认 `--secret-file`（或 `ARGENT_LICENSE_SECRET`）；**不**读本机已装的
+ *      `license.secret` —— 那会让"拿生产密钥自签"变成一次无意识的默认动作。
+ *   ② **产物路径必须显式**：必须给 `--out <路径>`；`--out` 落在**本机现役许可位**
+ *      （`$ARGENT_DATA_DIR/license.json`）时**拒绝**，除非显式 `--allow-live-target`
+ *      （那条路应该走 `install-license.mjs`，它带备份/读回验收/设备比对）。
+ *   ③ **不扩权**：`capabilities/verticals/seats/expiresAt/graceDays` 全部来自命令行**显式**参数，
+ *      默认最小（无能力、30 天、席位 1）—— 本工具不会"读一份现有许可然后放宽它"。
+ *
+ * ## ⚠️ 它不是"防伪"的一环
+ * 许可签名是 **HMAC-SHA256（对称密钥）**：验签方必须持有同一把密钥 ⇒ 能读 `license.secret` 的人
+ * **本来就能自签**。本工具只是把这件事**摆到明面上**（工具化、留痕、口径唯一），不构成新的能力。
+ * 真防伪造需要**非对称签名**（Ed25519，客户端只拿公钥）—— 见 §3.6③ 与实施方案的服务端方案。
+ *
+ * 用法：
+ *   node scripts/self-sign-license.mjs --user <账号id> --secret-file <密钥文件> --out <许可文件>
+ *        [--cap <能力id>]… [--vertical <业务线id>]… [--seats N] [--days N | --expires <ISO>] [--grace N]
+ *        [--instance <提示串>] [--device-code <64hex> | --device-from-local | --no-device]
+ *        [--sign-v1 | --sign-v2] [--json] [--dry-run] [--force]
+ * 缺省：**v2 + 本机设备码**（D1：新签发默认带 `device`）；`--no-device` ⇒ v2 但不声明设备（unbound，
+ * 缺位一样进签名）；`--sign-v1` ⇒ 旧形态（9 项载荷，**不含** device）。
+ * 退出码：0 已签（含 dry-run）｜ 1 写入失败/自验失败 ｜ 2 用法或环境错误
+ */
+import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { DEVICE_ALGO, currentDevice } from '../core/lib/license-device.mjs'
+import { defaultLicensePath, resolveSecret, signLicenseFile, verifyLicenseFile } from '../core/lib/license-file.mjs'
+
+const argv = process.argv.slice(2)
+const has = (f) => argv.includes(f)
+const allOf = (f) => argv.reduce((acc, a, i) => (a === f && argv[i + 1] !== undefined ? [...acc, argv[i + 1]] : acc), [])
+const argOf = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] ?? null : null }
+const die = (m) => { console.error(`✗ ${m}`); process.exit(2) }
+const fail = (m) => { console.error(`✗ ${m}`); process.exit(1) }
+
+if (has('--help') || has('-h')) {
+  console.log('用法：node scripts/self-sign-license.mjs --user <id> --secret-file <密钥文件> --out <许可文件>')
+  console.log('      [--cap <id>]… [--vertical <id>]… [--seats N] [--days N|--expires <ISO>] [--grace N] [--instance <hint>]')
+  console.log('      [--device-code <64hex>|--device-from-local|--no-device] [--sign-v1|--sign-v2] [--json] [--dry-run] [--force]')
+  console.log('⚠️ 离线**自签**（演练/测试用）；真实签发在服务端（whyshu-svr）。签名是 HMAC 对称密钥 ⇒ 不是防伪边界。')
+  process.exit(0)
+}
+
+const dryRun = has('--dry-run')
+const jsonOut = has('--json')
+const asJson = jsonOut
+
+const userId = String(argOf('--user') || '').trim()
+if (!userId) die('必须给 --user <账号id>（许可里的 userId；空值会被判 malformed）')
+
+const secretSrc = argOf('--secret-file') ? resolve(argOf('--secret-file')) : null
+if (!secretSrc && !String(process.env.ARGENT_LICENSE_SECRET || '').trim()) {
+  die('必须显式给密钥来源：--secret-file <密钥文件> 或 ARGENT_LICENSE_SECRET'
+    + '（⛔ 不读本机已装的 license.secret：自签必须是**刻意**的动作）')
+}
+if (secretSrc && !existsSync(secretSrc)) die(`密钥文件不存在：${secretSrc}`)
+const key = resolveSecret({ secret: undefined, secretPath: secretSrc || undefined })
+if (!key.secret) die(`读不到密钥：${secretSrc || 'ARGENT_LICENSE_SECRET'}`)
+
+const outArg = argOf('--out')
+if (!outArg) die('必须给 --out <许可文件路径>（本工具**不**默认往数据目录写）')
+const out = resolve(outArg)
+const live = defaultLicensePath()
+if (out === live && !has('--allow-live-target')) {
+  die(`--out 指向**本机现役许可位**（${live}）：这条路请走 \`install-license.mjs\`（带备份 + 读回验收 + 设备比对）；`
+    + '确实要直接覆盖请显式加 --allow-live-target')
+}
+if (existsSync(out) && !has('--force') && !dryRun) die(`--out 已存在：${out}（要覆盖请加 --force）`)
+
+// 版本（缺省 v2 —— D1：新签发默认带 device）
+const signV1 = has('--sign-v1')
+const signV2 = has('--sign-v2')
+if (signV1 && signV2) die('--sign-v1 与 --sign-v2 只能给一个')
+const version = signV1 ? 1 : 2
+
+// 设备声明（v2 才有意义）：缺省 = **本机设备码**
+const noDevice = has('--no-device')
+const deviceCodeArg = argOf('--device-code')
+let device = null
+if (version === 2 && !noDevice) {
+  if (deviceCodeArg) {
+    const code = String(deviceCodeArg).trim()
+    if (!/^[0-9a-f]{64}$/i.test(code)) {
+      die(`--device-code 必须是 64 位十六进制的**设备码**（\`argent license request\` 打印的那串）；`
+        + '⛔ 不要给主机名/MAC/IP（D3：指纹只认硬件 UUID 一项）')
+    }
+    device = { code: code.toLowerCase(), algo: DEVICE_ALGO, issuedAt: new Date().toISOString() }
+  } else {
+    const dev = currentDevice({})
+    if (!dev.ok) {
+      die(`读不到本机设备码（${dev.reason}）：${dev.error} ⇒ 要么 --device-code <64hex>，要么显式 --no-device`)
+    }
+    device = { code: dev.code, algo: dev.algo, issuedAt: dev.issuedAt }
+  }
+}
+
+// 期限：`--days`（缺省 30）或 `--expires`（显式 ISO）
+const now = new Date()
+const days = argOf('--days') === null ? 30 : Number(argOf('--days'))
+if (!Number.isFinite(days) || days <= 0) die(`--days 必须是正数：${argOf('--days')}`)
+const expiresArg = argOf('--expires')
+let expiresAt = new Date(now.getTime() + days * 86400000).toISOString()
+if (expiresArg) {
+  const t = Date.parse(String(expiresArg))
+  if (!Number.isFinite(t)) die(`--expires 不是可解析时间：${expiresArg}`)
+  expiresAt = new Date(t).toISOString()
+}
+const graceDays = argOf('--grace') === null ? 14 : Number(argOf('--grace'))
+if (!Number.isFinite(graceDays) || graceDays < 0) die(`--grace 必须 ≥ 0：${argOf('--grace')}`)
+
+const file = {
+  v: version,
+  userId,
+  capabilities: [...new Set(allOf('--cap').map(String).filter(Boolean))].sort(),
+  verticals: [...new Set(allOf('--vertical').map(String).filter(Boolean))].sort(),
+  seats: argOf('--seats') === null ? 1 : Number(argOf('--seats')),
+  issuedAt: now.toISOString(),
+  expiresAt,
+  graceDays,
+  instanceHint: String(argOf('--instance') || 'self-sign'),
+  ...(device ? { device } : {}),
+}
+if (!Number.isFinite(file.seats) || file.seats < 1) die(`--seats 必须是正数：${argOf('--seats')}`)
+
+const signed = signLicenseFile(file, key.secret, { version })
+if (!signed.ok) fail(`签名失败（${signed.reason}${signed.warning ? `：${signed.warning}` : ''}）`)
+// **自验**：产物必须能在**独立入口**（verifyLicenseFile）验过 —— "我签完了"不算数
+const check = verifyLicenseFile(signed.file, { secret: key.secret, now: now.getTime() })
+if (!check.ok) fail(`自验失败（${check.reason}）：拒绝写出（别把一份自己都验不过的许可交给别人）`)
+
+const result = {
+  ok: true, empty: false, code: 0, reason: null,
+  tool: 'scripts/self-sign-license.mjs',
+  warning: '离线**自签**：真实签发在服务端（whyshu-svr）；签名是 HMAC 对称密钥 ⇒ 本工具不构成安全边界',
+  out, dryRun, written: false,
+  signatureVersion: version,
+  deviceSigned: version === 2,
+  payload: signed.payload,
+  licenseFile: signed.file,
+  keySource: secretSrc ? `secret-file:${secretSrc}` : 'env:ARGENT_LICENSE_SECRET',
+  verified: { ok: check.ok, reason: check.reason, state: check.inGrace ? 'grace' : (check.ok ? 'valid' : 'denied') },
+}
+
+if (!dryRun) {
+  try {
+    mkdirSync(dirname(out), { recursive: true, mode: 0o700 })
+    const tmp = `${out}.tmp`
+    writeFileSync(tmp, JSON.stringify(signed.file, null, 2) + '\n', { mode: 0o600 })
+    chmodSync(tmp, 0o600)
+    renameSync(tmp, out)
+    result.written = true
+  } catch (e) {
+    rmSync(`${out}.tmp`, { force: true })
+    fail(`写入失败：${e.message}`)
+  }
+}
+
+if (asJson) {
+  console.log(JSON.stringify(result, null, 2))
+} else {
+  console.log(`${dryRun ? '🔎 [dry-run] 会自签' : '✅ 已自签'}离线许可（v${version}）：→ ${out}`)
+  console.log(`   账号：${userId} ｜ 席位：${file.seats} ｜ 到期：${expiresAt} ｜ 宽限 ${graceDays} 天`)
+  console.log(`   能力：${file.capabilities.join(',') || '(空 ⇒ 客户端拒一切能力)'} ｜ 业务线：${file.verticals.join(',') || '(空 = 不限)'}`)
+  console.log(`   设备：${device ? `已声明（${device.code.slice(0, 12)}…，进签名）` : '未声明（unbound；缺位也已进签名）'}`)
+  console.log(`   自验：${check.reason}（独立入口 verifyLicenseFile）`)
+  console.log(`   ⚠️ ${result.warning}`)
+  console.log('   下一步：node scripts/install-license.mjs --file <该文件> [--dry-run]')
+}
+process.exit(0)