@whyshu/argent-engine 0.0.0-stage → 0.6.1

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/retire-inventory.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// 0.7.0 W8 只读盘点：把"待退役面"逐类定位（⛔ 只读；不改文件、不动生产、不重启）。
+import { readdirSync, readFileSync, statSync, existsSync, writeFileSync } from 'node:fs'
+import { join, relative, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+const REPO = join(dirname(fileURLToPath(import.meta.url)), '..')
+const SKIP = new Set(['.git', 'node_modules', 'dist', '__pycache__', 'attic', '.venv'])
+function walk(dir, out = []) {
+  for (const e of readdirSync(dir)) {
+    if (SKIP.has(e)) continue
+    const p = join(dir, e); const st = statSync(p)
+    if (st.isDirectory()) walk(p, out)
+    else if (/\.(mjs|js|cjs|py|sh|json|md|plist|ts)$/.test(e) && st.size < 2_000_000) out.push(p)
+  }
+  return out
+}
+const files = walk(REPO)
+const hits = (re, filter = () => true) => files.filter(filter).map((f) => ({ f: relative(REPO, f), n: (readFileSync(f, 'utf8').match(re) || []).length })).filter((x) => x.n > 0).sort((a, b) => b.n - a.n)
+const patches = existsSync(join(REPO, 'scripts/patches')) ? readdirSync(join(REPO, 'scripts/patches')).filter((f) => f.endsWith('.patch')) : []
+const doc = {
+  generatedAt: new Date().toISOString(),
+  面: {
+    '内核补丁（patch 数 / 引用点）': { patches: patches.length, files: hits(/scripts\/patches\//).slice(0, 10) },
+    '旧单文件分发 install-argent.mjs': { files: hits(/install-argent\.mjs/).slice(0, 10) },
+    '写死 ~/.dsh 路径': { files: hits(/~\/\.dsh|\.dsh\/argent/, (f) => !f.includes('/docs/') && !f.includes('/patches/')).slice(0, 15) },
+    'launchd 双线（flow-trigger / plist / launchctl）': { files: hits(/flow-trigger|launchctl|LaunchAgents|\.plist/).slice(0, 15) },
+  },
+}
+console.log(JSON.stringify(doc, null, 2))
+if (process.argv.includes('--write')) {
+  const p = join(REPO, 'docs/Argent-0.7.0-退役面盘点.md')
+  const L = ['# Argent 0.7.0 待退役面盘点（只读生成）', '', `生成时间：${doc.generatedAt}`, '', '> 本文件由 `node scripts/retire-inventory.mjs --write` 生成；⛔ 只读盘点，未改动任何被点名的面。', '']
+  for (const [k, v] of Object.entries(doc.面)) {
+    L.push(`## ${k}`, '')
+    if (v.patches !== undefined) L.push(`- patch 文件数：**${v.patches}**`)
+    for (const x of v.files) L.push(`- \`${x.f}\`（${x.n} 处）`)
+    L.push('')
+  }
+  writeFileSync(p, L.join('\n')); console.log(`\n✅ 已写 ${relative(REPO, p)}`)
+}

package/engine/scripts/run-tests.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据（⛔ 不再写死 ~/.dsh/argent）
+# 全量测试入口（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="$ARGENT_DATA_DIR_RESOLVED/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/s1-audit.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// 0.7.0 W8/S1 **精确分类器**（只读）：把 `~/.dsh` 字面量分成
+//   A 写入点（改它才影响"数据落哪"，必须改）｜ B 回退候选（只读候选链，按分类保留）｜ C 注释（不动）。
+// 用法：node scripts/s1-audit.mjs [--json] [--only A]
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+const REPO = join(dirname(fileURLToPath(import.meta.url)), '..')
+const SKIP = new Set(['.git', 'node_modules', 'dist', '__pycache__', 'attic', '.venv', 'docs', 'patches', 'tests'])
+const RE = /\.dsh\/argent|~\/\.dsh|\$HOME\/\.dsh|\$\{HOME\}\/\.dsh/
+function walk(dir, out = []) {
+  for (const e of readdirSync(dir)) {
+    if (SKIP.has(e)) continue
+    const p = join(dir, e); const st = statSync(p)
+    if (st.isDirectory()) walk(p, out)
+    else if (/\.(mjs|js|cjs|py|sh)$/.test(e) && st.size < 2_000_000) out.push(p)
+  }
+  return out
+}
+// 去注释：整块块注释、行首 # 或 // 、以及行尾 // 之后的片段（⚠️ 本文件注释里别写那对定界符，会提前闭合）
+function stripComments(src, ext) {
+  let s = src.replace(/\/\*[\s\S]*?\*\//g, '')
+  return s.split('\n').map((line) => {
+    const t = line.trimStart()
+    if (t.startsWith('#') || t.startsWith('*') || t.startsWith('//')) return ''
+    if (ext === '.py' || ext === '.sh') return line.replace(/(^|\s)#.*$/, '')
+    return line.replace(/\/\/.*$/, '')
+  })
+}
+const WRITE = /(=|>>?|mkdir|touch|tee|appendFile|writeFile|Path\(|open\(|log|LOG_DIR|LOGDIR|DATA_DIR|DATA_HOME|PAUSE)/i
+const FALLBACK = /(for\s+\w+\s+in|\|\||-f\s|\$\(.*\|\||candidates?|fallback|候选)/i
+const files = walk(REPO).map((f) => ({ f, ext: f.slice(f.lastIndexOf('.')) }))
+const rows = []
+for (const { f, ext } of files) {
+  const lines = stripComments(readFileSync(f, 'utf8'), ext)
+  const hits = []
+  lines.forEach((line, i) => {
+    if (!RE.test(line)) return
+    const kind = WRITE.test(line) && !FALLBACK.test(line) ? 'A' : FALLBACK.test(line) ? 'B' : 'A?'
+    hits.push({ n: i + 1, kind, text: line.trim().slice(0, 100) })
+  })
+  if (hits.length) rows.push({ file: relative(REPO, f), hits })
+}
+const count = (k) => rows.reduce((n, r) => n + r.hits.filter((h) => h.kind === k).length, 0)
+const doc = { files: rows.length, A: count('A'), 'A?': count('A?'), B: count('B'), rows: rows.sort((a, b) => b.hits.length - a.hits.length) }
+if (process.argv.includes('--writes')) {
+  // 「非赋值写入」口径：redirect / mkdir / touch / `-f` 测试 / 内嵌 open —— 这些同样决定"数据落哪"
+  const W = /(>>?\s*\S*\.dsh\/argent|mkdir[^\n]*\.dsh\/argent|touch[^\n]*\.dsh\/argent|-f\s+"?\S*\.dsh\/argent|open\([^\n]*\.dsh\/argent|\btee\b[^\n]*\.dsh\/argent)/
+  const MSG = /(echo |scp |note\(|\$FIX)/          // 提示语/夹具路径 ⇒ 不算写入
+  const hits = []
+  for (const r of rows) for (const h of r.hits) if (W.test(h.text) && !MSG.test(h.text)) hits.push({ file: r.file, line: h.n, text: h.text })
+  if (process.argv.includes('--json')) { console.log(JSON.stringify({ total: hits.length, hits }, null, 2)); process.exit(0) }
+  console.log(`非赋值写入残留：**${hits.length} 处**（目标 0；白名单外的都算红）`)
+  for (const h of hits.slice(0, 10)) console.log(`  ${h.file}:${h.line}  ${h.text.slice(0, 88)}`)
+  process.exit(0)
+}
+if (process.argv.includes('--assignments')) {
+  // 「只认赋值行」口径：真正决定"数据落哪"的写法（⛔ 不含候选链/提示语/注释）
+  const ASSIGN = /^\s*(export\s+)?[A-Za-z_][A-Za-z0-9_]*=(.*)$/
+  const out = []
+  for (const r of rows) for (const h of r.hits) if (ASSIGN.test(h.text) && RE.test(h.text)) out.push({ file: r.file, line: h.n, text: h.text })
+  const argentHits = out.filter((h) => /\.dsh\/argent/.test(h.text))
+  const hostHits = out.filter((h) => !/\.dsh\/argent/.test(h.text))
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify({ total: out.length, argentDataDir: argentHits.length, hostOwnedDsh: hostHits.length, hits: out }, null, 2))
+    process.exit(0)
+  }
+  // ⚠️ 必须拆分：`~/.dsh/argent`（= **Argent 数据目录**，W8 要退役的）vs 其它 `.dsh`（dsh 自己的 home：
+  //    settings.yaml / profiles/ / .agent-presets ⇒ 属宿主，不归 Argent 管）
+  const argent = argentHits, hostOwn = hostHits   // 与 --json 同源，⛔ 不写两遍拆分
+  if (process.argv.includes('--json')) { console.log(JSON.stringify({ total: out.length, argentDataDir: argent.length, hostOwnedDsh: hostOwn.length, hits: out }, null, 2)); process.exit(0) }
+  console.log(`赋值行字面量残留：**${out.length} 处**，其中 Argent 数据目录 \`~/.dsh/argent\` **${argent.length} 处**（W8 目标 = 0）`)
+  console.log(`  另 ${hostOwn.length} 处是 **dsh 自己的 home**（settings/profiles/presets）⇒ 属宿主面，不归 Argent`)
+  for (const h of argent.slice(0, 12)) console.log(`  [argent] ${h.file}:${h.line}  ${h.text.slice(0, 84)}`)
+  process.exit(0)
+}
+if (process.argv.includes('--json')) { console.log(JSON.stringify(doc, null, 2)); process.exit(0) }
+console.log(`非注释字面量：${doc.files} 个文件 ｜ A 写入点 ${doc.A} ｜ A? 待判 ${doc['A?']} ｜ B 回退候选 ${doc.B}`)
+const onlyA = process.argv.includes('--only') && process.argv[process.argv.indexOf('--only') + 1] === 'A'
+for (const r of doc.rows.slice(0, 12)) {
+  const hs = onlyA ? r.hits.filter((h) => h.kind.startsWith('A')) : r.hits
+  if (!hs.length) continue
+  console.log(`  ${r.file}  (${hs.length})`)
+  for (const h of hs.slice(0, 3)) console.log(`      [${h.kind}] L${h.n}: ${h.text}`)
+}