@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/check-billing-mode.sh

@@ -0,0 +1,377 @@
+#!/usr/bin/env bash
+# check-billing-mode.sh —— **provider 装配巡检**（只读报告；2026-10-02 重做判据与文案）
+#
+# ⚠️ 文件名保留 `check-billing-mode.sh`（不是"还在用计费模式"）：LaunchAgent
+#    `com.whyshu.billing-mode-check` 的 plist 与 `scripts/billing-mode-daily.sh` 指的就是这个路径，
+#    改名要同时动 plist/定时器 —— 不值当。文件名的 "billing-mode" 只是历史遗留。
+#
+# ## 历史：旧「计费模式」机制**已移除**
+# 曾经的做法是"切模式"= 改写 `llm-deepseek.baseURL`（官方直连 ↔ 问述代理二选一）——那等于
+# **劫持官方直连 provider**（provider id 仍叫 `deepseek-official`，实际指向问述），用户明确禁止。
+# 现在的形态是：**两个独立 provider 并存**，用户在 dsh 输入框旁的**模型选择器**里选：
+#   · `llm-deepseek` 实例（`@deepseek-ai/dsh-llm-deepseek-api-key`）→ provider `deepseek-official`
+#     = 真·官方直连（`https://api.deepseek.com` + `DEEPSEEK_API_KEY`，不扣积分）
+#   · `llm-whyshu` 实例（`argent-core/llm-whyshu`）→ provider `whyshu`
+#     = 问述代理（`https://whyshu.com/api/argent/v1` + `WHYSHU_API_KEY`，扣积分）
+# ⇒ **"某台机器只装官方直连"是合法配置，不是装配损坏**。
+#
+# ## 判据（2026-10-02 重做：**期望值由组合声明推导**，不写死任何 provider 名单）
+#   声明（declared）：`~/.dsh/profiles/<profile>/cordis.patch.yml` 里**有**该 id 的条目
+#                     （普通条目**或** `- insert:` 块里的条目都算）⇒ **才期望它装上**；
+#                     没有 ⇒ 未装配属**正常**（如"没登录问述"，按设计），**不算缺失**。
+#   在位（mounted）  ：`dsh --profile <p> --dump-config` 的**组合树**里有该 id（权威判据，来源标 composed）。
+#                     基础组合（`@deepseek-ai/dsh-base` 之类）提供的实例也在这里出现。
+#   四态：
+#     declared ∧ mounted            ⇒ ✓ 在位
+#     declared ∧ ¬mounted（组合树读到了）⇒ ✗ **组合声明了但未装配** ⇒ exit 1（唯一的硬失败）
+#     ¬declared ∧ mounted           ⇒ ✓ 在位（基础组合提供，补丁未声明 —— 合法）
+#     ¬declared ∧ ¬mounted          ⇒ – 未装配（按设计；**不算缺失**）⇒ exit 0
+#     declared ∧ 组合树读不到        ⇒ ⚠ 未确认（**不敢说"没装上"**）⇒ exit 2
+#     ¬declared ∧ 组合树读不到       ⇒ – 未声明（什么都没声明 ⇒ 没什么要验的）⇒ exit 0
+#
+# 用法：bash scripts/check-billing-mode.sh [--json]
+#   环境变量（排障/测试用，全是只读输入）：
+#     ARGENT_CORDIS_PATCH   组合补丁路径（默认 ~/.dsh/profiles/web/cordis.patch.yml）
+#     SETTINGS              设置文件路径（默认 ~/.dsh/settings.yaml）
+#     ARGENT_PROFILE        profile 名（默认 = 组合补丁所在目录名，如 web）
+#     ARGENT_DSH_BIN        dsh 可执行文件（默认 PATH 里的 dsh；测试可指向假桩，不真起 dsh）
+#     ARGENT_DUMP_TIMEOUT   dump-config 超时秒数（默认 20）
+# 退出码：0=合法配置（声明的都在位；未声明的按设计视为不装）；
+#         1=**组合声明了却没装上**（唯一硬失败）；
+#         2=无法判定（声明了但组合树读不到：dsh 缺失/超时/输出不可解析）——"未确认"，不是"坏了"；
+#         3=调用了写意图参数（拒绝）
+#
+# ## ⛔ 只读熔断（2026-10-01 加固，任务「--fix 死代码」）
+# 本脚本**没有任何写路径**：全文只有 yaml 读两个文件 + 把 `--dump-config` 的**输出经管道读进内存**
+# （**不落任何临时文件**），直接 `exit`；不 open(…,'w')、不调用任何会落盘的命令。
+# 为把这条性质变成"结构上不可能"而不是"靠人记住"，这里加**硬熔断**：
+# 任何写意图参数（--fix/--apply/--write/--set/--mode/--provider/--force）⇒ **在读任何文件之前**
+# 就拒绝并 `exit 3`。历史教训：旧版 `--fix` 会改写 `llm-deepseek.baseURL` = **劫持官方直连 provider**
+# （provider id 仍叫 deepseek-official，实际指向问述）—— 用户明确禁止（见 AGENTS.md「LLM provider 设计」
+# 与「不写 ~/.dsh/settings.yaml」）。改 provider 请用输入框旁的**模型选择器**，或
+# `bash scripts/provider-select.sh {status|whyshu|deepseek}`（那条路才是有意为之的写入者）。
+#
+# ## 历史判据备注（保留供排障）
+# · 2026-10-01：客户机上 `llm-deepseek` 由**基础组合**提供、补丁里根本没有它 ⇒ 旧版"只扫补丁"
+#   会误报缺失。修法 = 以**组合树**为首选判据（来源标 `composed`），补丁扫描只作回退。
+# · 2026-09-30：组合补丁里**新增实例的规范写法是 `- insert:` 块**（普通条目是"按 id 覆盖已有条目"，
+#   写错了会被静默跳过）⇒ 声明扫描必须**两个位置都看**（顶层 + insert 块）。
+set -uo pipefail
+
+# ── ⛔ 写操作熔断：必须在读任何文件之前（放最前面，与 REPO/PATCH/SETTINGS 的求值无关）──
+# ⚠️ `$arg` 后面紧跟中文字符时必须写 `${arg}`：bash 在 CJK locale 下会把全角字符当标识符字符
+# （仓库门禁 scripts/tests/shell-cjk-var.test.py 就是为这个坑立的）。
+for arg in "$@"; do
+  case "$arg" in
+    --fix|--apply|--write|--set|--set-mode|--mode|--provider|--force)
+      echo "⛔ check-billing-mode.sh 是**只读**报告：不接受 ${arg}，也不会改任何文件。" >&2
+      echo "   改 provider：用 dsh 输入框旁的**模型选择器**，" >&2
+      echo "   或 bash scripts/provider-select.sh {status|whyshu|deepseek}（改完需重启 dsh）。" >&2
+      echo "   ⛔ 本脚本绝不写 ~/.dsh/settings.yaml，也不改写官方 provider 的 baseURL。" >&2
+      exit 3
+      ;;
+  esac
+done
+
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PY="${ARGENT_PY:-$HOME/.dsh/argent/venv/bin/python3}"; [ -x "$PY" ] || PY=python3
+PATCH="${ARGENT_CORDIS_PATCH:-$HOME/.dsh/profiles/web/cordis.patch.yml}"
+SETTINGS="${SETTINGS:-$HOME/.dsh/settings.yaml}"
+# profile 名：优先显式给定，否则取组合补丁所在目录名（~/.dsh/profiles/<p>/cordis.patch.yml ⇒ <p>）
+PROFILE="${ARGENT_PROFILE:-$(basename "$(dirname "$PATCH")")}"
+DSH_BIN="${ARGENT_DSH_BIN:-dsh}"
+DUMP_TIMEOUT="${ARGENT_DUMP_TIMEOUT:-20}"
+
+# ── 权威判据：组合后的树（`dsh --profile <p> --dump-config`）────────────────
+# 它才是 dsh 真正加载的那份（基础组合 + 补丁 overlay 的结果）；基础组合提供的实例（补丁里根本没有）
+# 也能在这里看到。dsh 不可用/超时/输出不可解析 ⇒ 组合树"读不到"，由 python 侧按状态区分。
+# 可移植超时：本机 macOS **没有** `timeout`/`gtimeout` ⇒ 纯 shell 实现（后台 + 看门狗 + kill），
+# 且**不落任何临时文件**（stdout 直接进命令替换的内存变量）。
+_run_dump_config() {   # $1=dsh 可执行 $2=profile $3=超时秒；成功：stdout=组合树文本
+  local bin="$1" prof="$2" secs="$3" pid watcher rc
+  "$bin" --profile "$prof" --dump-config 2>/dev/null &
+  pid=$!
+  # ⚠️ 看门狗必须把 stdout/stderr 重定向到 /dev/null：否则它（及其 `sleep` 子进程）会**继续持有
+  # 命令替换的管道** ⇒ 即使主命令早已结束，`$( )` 也要等到 `sleep` 自然醒来才拿到 EOF
+  # （实测：每次调用白等满 DUMP_TIMEOUT）。
+  ( sleep "$secs"; kill -0 "$pid" 2>/dev/null && kill -9 "$pid" 2>/dev/null ) >/dev/null 2>&1 &
+  watcher=$!
+  wait "$pid"; rc=$?
+  kill "$watcher" 2>/dev/null
+  wait "$watcher" 2>/dev/null
+  return $rc
+}
+
+dump_text=""; dump_status="unavailable"; dump_rc=0
+if command -v "$DSH_BIN" >/dev/null 2>&1; then
+  dump_text=$(_run_dump_config "$DSH_BIN" "$PROFILE" "$DUMP_TIMEOUT") || dump_rc=$?
+  if [ "$dump_rc" -eq 0 ] && [ -n "$dump_text" ]; then
+    dump_status="ok"
+  elif [ "$dump_rc" -eq 137 ]; then
+    dump_status="timeout"; dump_text=""
+  else
+    dump_status="failed"; dump_text=""
+  fi
+fi
+
+# 组合树文本经 **stdin** 交给 python（不写临时文件）；状态经 argv 传递。
+PY_SRC=$(cat <<'PY'
+import sys, yaml, json, pathlib
+
+patch       = sys.argv[1]
+settings    = sys.argv[2]
+fmt         = sys.argv[3] if len(sys.argv) > 3 else ''
+dump_status = sys.argv[4] if len(sys.argv) > 4 else 'unavailable'
+profile     = sys.argv[5] if len(sys.argv) > 5 else ''
+dsh_bin     = sys.argv[6] if len(sys.argv) > 6 else 'dsh'
+dump_text   = sys.stdin.read() if dump_status == 'ok' else ''
+
+# ── YAML：容忍 `!!js` 等自定义标签 ──────────────────────────────────────────
+# 组合树里合法地存在 `disabled: !!js '…'`、`root: !!js dshHomePath('sessions')`；
+# yaml.safe_load 遇到未知标签直接抛错 ⇒ 会被误当成"组合树读不到"。这里只把未知标签
+# 按其**字面内容**收下（本脚本只用 id/name/config，不执行任何表达式）。
+class _Tolerant(yaml.SafeLoader):
+    pass
+
+def _construct_unknown(loader, tag_suffix, node):
+    if isinstance(node, yaml.ScalarNode):
+        return loader.construct_scalar(node)
+    if isinstance(node, yaml.SequenceNode):
+        return loader.construct_sequence(node, deep=True)
+    return loader.construct_mapping(node, deep=True)
+
+_Tolerant.add_multi_constructor(None, _construct_unknown)
+
+def load_yaml(text):
+    return yaml.load(text, Loader=_Tolerant)
+
+# 本脚本认识的 provider 实例（**只用于给出可读的说明文案**，不参与"该不该装"的判断——
+# 该不该装一律由组合声明推导）。其余 `llm-*` 条目照样按同一套判据巡。
+PROVIDERS = {
+    'llm-deepseek': '官方直连',
+    'llm-whyshu': '问述代理',
+}
+# 官方直连的正式端点（事实常量，不是"期望清单"）：baseURL 等于它 = 与不写 baseURL 等价 ⇒ 不告警。
+OFFICIAL_DEEPSEEK_BASE = 'api.deepseek.com'
+
+# ── 判据①（权威）：组合后的树里找 `id:` 条目 ────────────────────────────────
+composed, composed_note = {}, ''
+
+def _walk(node):
+    if isinstance(node, dict):
+        i = node.get('id')
+        if isinstance(i, str) and i.strip():
+            composed.setdefault(i.strip(), node)      # 先出现者优先（贴近 dsh 的合并顺序）
+        for k, v in node.items():
+            if k == 'config':
+                continue        # config 里的 `models[].id` 是模型 id，不是条目 id，别误收
+            _walk(v)
+    elif isinstance(node, list):
+        for v in node:
+            _walk(v)
+
+if dump_status == 'ok' and dump_text.strip():
+    try:
+        _walk(load_yaml(dump_text))
+        if composed:
+            composed_note = f"{len(composed)} 条条目"
+        else:
+            composed_note = '组合树里没有任何 id 条目（形状异常）'
+            composed = {}
+    except Exception as e:
+        composed = {}
+        composed_note = f'组合树解析失败：{e}'
+elif dump_status == 'ok':
+    composed_note = '组合树输出为空'
+else:
+    composed_note = {'unavailable': 'dsh 不可用（PATH / ARGENT_DSH_BIN 里找不到）',
+                     'timeout': 'dsh --dump-config 超时',
+                     'failed': 'dsh --dump-config 执行失败（非 0 退出）'}.get(dump_status, f'未知状态 {dump_status}')
+composed_ok = bool(composed)
+
+# ── 判据②：组合**声明**扫描（补丁顶层条目 + `- insert:` 块）—— 期望值的唯一来源 ──
+ok_yaml = True
+doc = []
+try:
+    doc = load_yaml(pathlib.Path(patch).read_text(encoding='utf-8')) or []
+except Exception as e:
+    ok_yaml = False
+    print(f"  ⚠️ 组合补丁读取失败（无法推导期望值）：{e}")
+if ok_yaml and not isinstance(doc, list):
+    ok_yaml = False
+    print("  ⚠️ 组合补丁顶层不是列表（形状异常；无法推导期望值）")
+
+# 顶层同名条目优先（它才是"覆盖已有条目"的那份），但两个来源都记下来供排障。
+index, sources = {}, {}
+if ok_yaml:
+    for e in doc:
+        if not isinstance(e, dict):
+            continue
+        if e.get('id'):
+            index.setdefault(str(e['id']), e)
+            sources.setdefault(str(e['id']), 'top')
+        block = e.get('insert')
+        if isinstance(block, list):
+            for item in block:
+                if isinstance(item, dict) and item.get('id'):
+                    k = str(item['id'])
+                    index.setdefault(k, item)
+                    sources.setdefault(k, 'insert')
+
+def entry(eid):
+    return index.get(eid)
+
+# ── 补充来源：`~/.dsh/settings.yaml` 顶层同名段（键 = 实例 id）────────────────
+# 历史「计费模式」的**改写落点**就在这里（`llm-deepseek: {baseURL: …}`）⇒ 仍要读一眼，
+# 免得只在 settings.yaml 里留着的改写看不见。**只是补充**：组合树（dsh 真正加载的那份）优先。
+settings_cfg = {}
+try:
+    _s = load_yaml(pathlib.Path(settings).read_text(encoding='utf-8')) or {}
+    if isinstance(_s, dict):
+        settings_cfg = _s
+except Exception:
+    settings_cfg = {}
+
+# ── 当前会话/默认 provider（真源 = dsh 的 `agent-default-model`；来源照旧标注）──
+default, default_src = '', ''
+for name, cfgv in (('composed', (composed.get('agent-default-model') or {}).get('config')),
+                   ('patch',    (entry('agent-default-model') or {}).get('config'))):
+    if isinstance(cfgv, dict) and str(cfgv.get('provider') or '').strip():
+        default, default_src = str(cfgv['provider']).strip(), name
+        break
+default_note = {'composed': 'composed（dsh 组合树里的 agent-default-model）',
+                'patch':  '组合补丁（顶层条目 agent-default-model）'}.get(default_src, '未读到（不猜）')
+
+# ── 巡哪些 provider：认识的两位 + 组合里**声明**过的任何 `llm-*` ──────────────
+declared = {k: v for k, v in sources.items() if k in PROVIDERS or k.startswith('llm-')}
+watch = sorted(set(PROVIDERS) | set(declared))
+
+inst, missing, unconfirmed, not_declared = {}, [], [], []
+for pid in watch:
+    decl = pid in declared
+    mnt = pid in composed
+    c = composed.get(pid) or {}
+    p = entry(pid) or {}
+    ccfg, pcfg = (c.get('config') or {}), (p.get('config') or {})
+    scfg = settings_cfg.get(pid) or {}
+    if not isinstance(scfg, dict):
+        scfg = {}
+    # baseURL/apiKeyEnv：组合树（权威，含基础组合的 config）→ 补丁条目 → settings.yaml 同名段
+    base = ccfg.get('baseURL') or pcfg.get('baseURL') or scfg.get('baseURL') or ''
+    akey = ccfg.get('apiKeyEnv') or pcfg.get('apiKeyEnv') or scfg.get('apiKeyEnv') or ''
+    disabled = bool(c.get('disabled') if c else p.get('disabled'))
+    # 提示（**不改退出码**）：`llm-deepseek` 带 baseURL = 官方直连被改指 —— 那正是历史上
+    # 「计费模式」切路由留下的**劫持形态**（provider id 仍叫 deepseek-official，实际指向别处）。
+    # 合规的官方直连应**无** baseURL、key 用 DEEPSEEK_API_KEY。这里只如实标注，不据此判失败
+    # （"声明了却没装上"才是唯一的硬失败）。
+    warn = ''
+    if pid == 'llm-deepseek' and base and OFFICIAL_DEEPSEEK_BASE not in base:
+        warn = ('⚠️ 带 baseURL ⇒ **不是**官方直连（历史「计费模式」改写形态；'
+                '官方直连应无 baseURL、key 用 DEEPSEEK_API_KEY）')
+    if decl and mnt:
+        state = 'ok'
+    elif decl and not composed_ok:
+        state = 'unconfirmed'
+    elif decl:
+        state = 'missing'
+    elif mnt:
+        state = 'ok_base'
+    else:
+        state = 'absent'
+    inst[pid] = {
+        'declared': decl,
+        'declaredFrom': declared.get(pid, ''),
+        'mounted': mnt,
+        'from': 'composed' if mnt else (declared.get(pid, '') if decl else ''),
+        'plugin': c.get('name', '') or p.get('name', ''),
+        'baseURL': base, 'apiKeyEnv': akey,
+        'disabled': disabled, 'state': state, 'warning': warn,
+    }
+    if state == 'missing':
+        missing.append(pid)
+    elif state == 'unconfirmed':
+        unconfirmed.append(pid)
+    elif state == 'absent':
+        not_declared.append(pid)
+
+verdict = 'missing' if missing else ('unconfirmed' if unconfirmed else 'ok')
+
+# ── 输出 ────────────────────────────────────────────────────────────────────
+_MODE = {'whyshu': '问述代理，扣积分', 'deepseek-official': '官方直连，不扣积分'}
+mode = f"{default}（{_MODE[default]}）" if default in _MODE else f"未设置({default or '空'})"
+
+if fmt == '--json':
+    print(json.dumps({'defaultProvider': default, 'defaultProviderSource': default_src,
+                      'mode': mode, 'profile': profile,
+                      'composed': {'ok': composed_ok, 'status': dump_status, 'note': composed_note},
+                      'declared': declared, 'instances': inst,
+                      'missing': missing, 'unconfirmed': unconfirmed, 'notDeclared': not_declared,
+                      'warnings': [f"{k}: {v['warning']}" for k, v in inst.items() if v['warning']],
+                      'verdict': verdict, 'patchReadable': ok_yaml},
+                     ensure_ascii=False, indent=2))
+else:
+    print("  provider 装配巡检（只读）——两个独立 provider 并存（deepseek-official 官方直连 / whyshu 问述代理），用户在模型选择器里选")
+    print(f"  当前默认 provider：{mode}")
+    print(f"  默认 provider 来源：{default_note}")
+    if composed_ok:
+        print(f"  判据来源：组合树 composed（dsh --profile {profile} --dump-config，{composed_note}）＋ 组合声明（补丁顶层/insert）")
+    else:
+        print(f"  判据来源：组合声明（补丁顶层/insert）｜组合树**未读到**：{composed_note}")
+    if declared:
+        print("  组合声明：" + "、".join(f"{k}（{v}）" for k, v in sorted(declared.items())))
+    else:
+        print("  组合声明：（无 llm-* provider 实例 ⇒ 不期望任何 provider，未装配属正常）")
+    for pid in watch:
+        v = inst[pid]
+        if v['state'] in ('ok', 'ok_base'):
+            label = PROVIDERS.get(pid, '')
+            bu = f"baseURL {v['baseURL']}" if v['baseURL'] else '无 baseURL'
+            line = f"  ✓ {pid}（{(label + '，') if label else ''}{bu}）｜来源 {v['from']}"
+            if v['apiKeyEnv']:
+                line += f"｜key {v['apiKeyEnv']}"
+            if v['state'] == 'ok_base':
+                line += '｜基础组合提供（组合补丁未声明）'
+            if v['disabled']:
+                line += ' ⛔ 条目被 disabled ⇒ 实际不会加载'
+            if v['warning']:
+                line += f" {v['warning']}"
+            print(line)
+        elif v['state'] == 'missing':
+            print(f"  ✗ {pid} 组合声明了但未装配（补丁 {v['declaredFrom']} 有它，组合树里没有该 id ⇒ 会被 dsh 静默跳过）")
+        elif v['state'] == 'unconfirmed':
+            print(f"  ? {pid} 组合声明了（补丁 {v['declaredFrom']}）但组合树**未读到** ⇒ 未确认（不敢断言「没装上」）")
+        else:
+            why = '未登录问述即如此，' if pid == 'llm-whyshu' else ''
+            if composed_ok:
+                print(f"  – {pid} 未装配（组合未声明：{why}按设计；**不算缺失**）")
+            else:
+                print(f"  – {pid} 未声明（组合未声明，且组合树未读到 ⇒ 未确认是否有基础组合提供）")
+    if missing:
+        print(f"  ⚠️ **组合声明了但未装配**：{', '.join(missing)}")
+        for k in missing:
+            v = inst[k]
+            print(f"     · {k}：组合补丁（{v['declaredFrom']}）声明了它"
+                  f"{('（name: ' + v['plugin'] + '）') if v['plugin'] else ''}，"
+                  f"但 dsh --profile {profile} --dump-config 的组合树（{composed_note}）里没有该 id")
+        print("     ⇒ 新增实例必须写在 `- insert:` 块里（普通条目是「按 id 覆盖」，找不到会被静默跳过），")
+        print("       且 name 必须能被 profile 依赖图解析（dsh plugin --profile web list 能看到它）。")
+        print(f"     重启前门禁：dsh --profile {profile} --dump-config | grep {' '.join(missing)}")
+    elif unconfirmed:
+        print(f"  ⚠️ **无法判定**（组合树读不到）：{', '.join(unconfirmed)}")
+        for k in unconfirmed:
+            print(f"     · {k}：组合补丁（{inst[k]['declaredFrom']}）声明了它，但组合树没能读到（{composed_note}）")
+        print("     ⇒ 这是「未确认」，**不是**「装配坏了」：确认 dsh 可执行后重跑"
+              f"（当前 dsh：{dsh_bin}）")
+        print("     重跑：bash scripts/check-billing-mode.sh")
+    elif not ok_yaml:
+        print("  ⚠️ **无法判定**：组合补丁读不到 ⇒ 推导不出期望值（这条不是「provider 没装上」）")
+    else:
+        n_ok = len([k for k in watch if inst[k]['state'] in ('ok', 'ok_base')])
+        print(f"  ✅ 装配与组合声明一致：声明 {len(declared)} 个 / 在位 {n_ok} 个；"
+              f"未声明的 provider 按设计视为未装配（**不算缺失**）")
+
+sys.exit(1 if missing else (2 if (unconfirmed or not ok_yaml) else 0))
+PY
+)
+
+printf '%s' "$dump_text" | "$PY" -c "$PY_SRC" "$PATCH" "$SETTINGS" "${1:-}" "$dump_status" "$PROFILE" "$DSH_BIN"

package/engine/scripts/check-child-sessions.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * 检查某 parent session 的子会话关系：
+ *  1. 扫 sessions/ 全部目录的**所有版本化文件**的 header
+ *  2. 找 origin=subagent && parentSession=<parent> 的子会话（是否存在、哪个文件）
+ *  3. 扫 parent 自己的事件，列出 subagent 引用（subagent/descriptor 等）
+ * 用法: node scripts/check-child-sessions.mjs <parentSessionId>
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { execFileSync } from 'node:child_process'
+
+const parent = process.argv[2]
+if (!parent) { console.error('用法: node check-child-sessions.mjs <parentSessionId>'); process.exit(1) }
+
+const ROOT = join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'sessions')
+
+function readHeader(file) {
+  try {
+    const out = execFileSync('zstd', ['-dc', file], { maxBuffer: 10 * 1024 * 1024 })
+    const first = out.toString('utf8').split('\n')[0]
+    return JSON.parse(first)
+  } catch { return null }
+}
+
+console.log('=== 1. 扫描所有 session 的所有版本化文件 ===')
+let count = 0
+const children = []
+for (const proj of readdirSync(ROOT)) {
+  const projDir = join(ROOT, proj)
+  let dirs = []
+  try { dirs = readdirSync(projDir) } catch { continue }
+  for (const d of dirs) {
+    const dir = join(projDir, d)
+    let files = []
+    try { files = readdirSync(dir).filter((f) => /^session(\.v\d+)?\.jsonl(\.zstd)?$/.test(f)) } catch { continue }
+    for (const f of files) {
+      count++
+      const h = readHeader(join(dir, f))
+      if (!h) { console.log(`  ⚠️ 无法读 header: ${proj}/${d}/${f}`); continue }
+      if (h.parentSession === parent && h.origin === 'subagent') {
+        children.push({ file: `${proj}/${d}/${f}`, id: h.id, createdAt: h.createdAt })
+      }
+    }
+  }
+}
+console.log(`  扫描 ${count} 个文件`)
+console.log(`\n=== 2. 找到的子会话: ${children.length} 个 ===`)
+for (const c of children) console.log(`  ✅ ${c.id}\n      → ${c.file}\n      createdAt=${c.createdAt}`)
+if (children.length === 0) console.log('  ❌ 没有任何子会话文件')
+
+console.log(`\n=== 3. parent(${parent}) 里的 subagent 引用 ===`)
+const parentFile = (() => {
+  for (const proj of readdirSync(ROOT)) {
+    const dir = join(ROOT, proj, parent)
+    if (!existsSync(dir)) continue
+    const files = readdirSync(dir).filter((f) => /^session(\.v\d+)?\.jsonl(\.zstd)?$/.test(f))
+    return files.sort().map((f) => join(dir, f))
+  }
+  return []
+})()
+console.log('  parent 文件:', parentFile)
+for (const pf of parentFile) {
+  try {
+    const out = execFileSync('zstd', ['-dc', pf], { maxBuffer: 500 * 1024 * 1024 }).toString('utf8')
+    const refs = new Set()
+    const types = {}
+    for (const line of out.split('\n')) {
+      if (!line.trim()) continue
+      let e
+      try { e = JSON.parse(line) } catch { continue }
+      if (e.type && e.type.includes('subagent')) {
+        types[e.type] = (types[e.type] || 0) + 1
+        const cid = e.data?.childId || e.data?.childSessionId || e.data?.sessionId
+        if (cid) refs.add(cid)
+      }
+    }
+    console.log(`  文件: ${pf}`)
+    console.log('  subagent 相关事件类型:', types)
+    console.log('  引用的 child ids:', [...refs])
+  } catch (e) { console.log(`  读取失败: ${e.message}`) }
+}