@gavinc-cn/touchstone-dsh 0.1.0 → 0.2.0

package/sessparse.py

@@ -19,6 +19,11 @@
   tool_result {call_id, name, text, is_error, truncated}
 （dsh 事件流没有 usage 汇总事件与「本轮失败」独立通道，故不产出 usage / error 条目；
 响应里的 totals 字段保留为 0，维持 API 形状稳定。）
+
+上下文占用（会话窗底栏 ctx 圈，2026-10-10 修「恒为 0」）：dsh 会话日志里有两个
+可用槽位——`request/context` 事件带**上下文窗口**（适配器声明，见 _parse_dsh）、
+`assistant/message` 带本次调用的 **TokenUsage**；`load()` 在有窗口时附带
+`ctx={"used","max"}`（分子口径＝prompt 侧 token 数，见 _dsh_prompt_tokens）。
 """
 
 import base64
@@ -26,6 +31,7 @@ import glob
 import json
 import os
 import re
+import threading
 
 import zstandard
 
@@ -70,13 +76,50 @@ def _obj(raw):
     return d if isinstance(d, dict) else None
 
 
+def _nonneg_int(v):
+    """JSON 值 → 非负整数，其他（bool / 字符串 / 负数 / None）一律 None。
+
+    token 计数与窗口大小都必须是干净的整数：`True` 在 Python 里是 int 子类，
+    直接参与算术会算出垃圾值。
+    """
+    return v if isinstance(v, int) and not isinstance(v, bool) and v >= 0 else None
+
+
+def _dsh_prompt_tokens(usage):
+    """dsh `TokenUsage` → 本次请求的 **prompt 侧 token 数**（上下文占用分子）。
+
+    口径照抄 dsh `dsh-token-meter` 的 `pressureFrom`：
+    `inputTokens + (cacheReadTokens ?? 0) + (cacheWriteTokens ?? 0)`＝「这一次请求
+    送进模型的上下文有多大」。**不能**用 totalTokens：它含本次回复的输出 token，
+    环会随回复长度越画越大（且与上下文窗口不成比例）。inputTokens 缺失（老格式）
+    退回 `totalTokens - outputTokens`；再取不到返回 None（调用方保留上一槽位值）。
+    """
+    if not isinstance(usage, dict):
+        return None
+    inp = _nonneg_int(usage.get("inputTokens"))
+    if inp is not None:
+        return inp + (_nonneg_int(usage.get("cacheReadTokens")) or 0) \
+                   + (_nonneg_int(usage.get("cacheWriteTokens")) or 0)
+    total = _nonneg_int(usage.get("totalTokens"))
+    out = _nonneg_int(usage.get("outputTokens"))
+    if total is not None and out is not None and total >= out:
+        return total - out
+    return None
+
+
 class _Entries:
     """entry 收集器：自动分配 seq 并累计 totals。"""
 
     def __init__(self):
         self.entries = []
-        # token/耗时汇总（API 契约字段）：dsh 事件流无 usage 事件，恒为 0
+        # token/耗时汇总（API 契约字段）：dsh 事件流无 usage 汇总事件，恒为 0
         self.totals = {"input": 0, "output": 0, "cache_read": 0, "duration_ms": 0}
+        # 上下文占用两槽位（会话窗底栏 ctx 圈，2026-10-10 修「恒为 0」）：两个**独立
+        # last-wins** 槽位，口径与 dsh token-meter 的 `contextPressure` 投影一致：
+        #   used = 最新一次 usage 的 prompt 侧 token 数（pressureTokens）
+        #   max  = 最新 `request/context` 事件的 contextWindow（适配器声明的路由窗口）
+        # None = 该槽位尚未出现过（老会话 / 适配器未声明窗口 / 还没有一次模型调用）。
+        self.ctx = {"used": None, "max": None}
         # dsh 回退锚点（仅 _parse_dsh 填充）：[(mid, ese)，...] —— 真实用户提问的
         # 合成 mid 与**会话事件 seq**；dsh 没有原地 undo，回退＝按该 seq fork 新会话
         self.dsh_anchors = []
@@ -88,10 +131,30 @@ class _Entries:
 
 # ---------------------------------------------------------------- dsh 解析
 
-# dsh 会话文件为多帧 zstd 拼接（每帧一批 JSONL 事件行），用 zstandard 的
-# stream_reader(read_across_frames=True) 跨帧解压（项目唯一第三方依赖，见
-# requirements.txt）
-_DSH_DEC = zstandard.ZstdDecompressor()
+# dsh 会话文件为多帧 zstd 拼接（每帧一批 JSONL 事件行），逐帧 `decompressobj` 解压
+# （项目唯一第三方依赖，见 requirements.txt）。
+#
+# **解压器必须按线程隔离**（2026-10-09 定因的 SIGSEGV 实障）：zstandard 的
+# `ZstdDecompressor` **实例并发调用 `decompressobj()` 不是线程安全的**——原先这里
+# 是模块级共享实例，而站点是多线程的（HTTP 请求线程池 + board 30s 调度线程 +
+# 会话窗读口），并发解压直接 **SIGSEGV 打崩整个后端**（面板 502，薄壳不自愈）。
+# 实测对照（8 线程 × 25s 反复解压真实会话文件）：共享实例 **core dumped**；
+# 每线程独立实例同负载 765 次解压**零崩溃**。崩溃现场见
+# `doc_ai/bug_report/20261009_0600_插件后端两次SIGSEGV…`（faulthandler 栈落在
+# `server.py:_api_get_board` 的 `session_title` 调用行，扩展模块清单只有
+# `zstandard.backend_c`）。
+_DEC_TLS = threading.local()
+
+
+def _dec():
+    """取**本线程**的 zstd 解压器（无则新建并缓存，随线程回收）。
+
+    不要改回模块级共享实例——那正是 SIGSEGV 的根因（见上方注释）。
+    """
+    d = getattr(_DEC_TLS, "d", None)
+    if d is None:
+        d = _DEC_TLS.d = zstandard.ZstdDecompressor()
+    return d
 
 
 def _dsh_decompressed(path):
@@ -115,7 +178,7 @@ def _dsh_decompressed(path):
     chunks = []
     rest = buf
     while rest:
-        obj = _DSH_DEC.decompressobj()
+        obj = _dec().decompressobj()
         try:
             chunks.append(obj.decompress(rest))
         except zstandard.ZstdError:
@@ -139,7 +202,8 @@ def _dsh_session_file(sid):
     """按会话 id 跨工作区 bucket 定位 zstd 会话文件（返回路径或 None）。
 
     id 形态两代并存（本机实测 2026-10-02）：`session-<uuid>`（dsh web/headless 新建）
-    与裸 `<uuid>`（早期/桌面端写入，如 64655aea-… 的会话目录名即其 id）。
+    与裸 `<uuid>`（**绝大多数是子代理会话**，少数是老主会话，如 64655aea-…；
+    2026-10-07 实测 82 个裸 uuid 目录里 73 个 origin=subagent、9 个主会话）。
     文件名也带格式版本：`session.v4.jsonl.zstd`（62 个）/ `session.v3.jsonl.zstd`（1 个）
     / 无版本的 `session.jsonl.zstd`（9 个存量）——**只认无版本名会让 v3/v4 会话全部
     found=false**（真机踩中），故按 `session*.jsonl.zstd` 通配并优先取版本号最大者。
@@ -160,6 +224,93 @@ def _dsh_format_version(path):
     return int(m.group(1)) if m else 0
 
 
+# dsh 会话**头行**缓存：{path: (stamp, header)}。头行承载 origin/delegationDepth/cwd，
+# 是判「子代理会话」的唯一可靠依据（目录名不是判据，见 is_subagent）。
+_DSH_HEADER_CACHE = {}
+_DSH_HEADER_FRAMES = 4      # 头行最多向前找几帧（真机 304 个会话全在第 1 帧第 1 行）
+
+
+def _dsh_header(path):
+    """读 dsh 会话**头行**（`{"type":"session","id":…,"origin":…,"delegationDepth":…}`），
+    读不到/无头行返回 {}（老样本与异常一律降级为空）。
+
+    只解前 `_DSH_HEADER_FRAMES` 帧即停（头行就是第 1 帧第 1 行，实测 278 字节）——
+    与 `_dsh_decompressed` 的全量解压相比，判一个会话是不是子代理不该付整段解压的
+    代价（枚举 300+ 会话时差一个量级）。按 (mtime_ns, size) 缓存：会话只追加，
+    stamp 变即失效重读。
+    """
+    try:
+        st = os.stat(path)
+        stamp = (st.st_mtime_ns, st.st_size)
+    except OSError:
+        return {}
+    hit = _DSH_HEADER_CACHE.get(path)
+    if hit and hit[0] == stamp:
+        return hit[1]
+    header = {}
+    try:
+        with open(path, "rb") as f:
+            rest = f.read()
+    except OSError:
+        return {}
+    for _ in range(_DSH_HEADER_FRAMES):
+        if not rest:
+            break
+        obj = _dec().decompressobj()
+        try:
+            text = obj.decompress(rest).decode("utf-8", "replace")
+        except zstandard.ZstdError:
+            break                       # 坏帧：头行读不到就按「未知」（=主会话）
+        rest = obj.unused_data          # 余量即下一帧（逐帧解压，同 _dsh_decompressed）
+        for line in text.split("\n"):
+            line = line.strip()
+            if not line:
+                continue
+            d = _obj(line)
+            if d is not None and d.get("type") == "session":
+                header = d
+                break
+        if header:
+            break
+    _DSH_HEADER_CACHE[path] = (stamp, header)
+    return header
+
+
+def _header_subagent(header):
+    """头行 → 是否子代理会话：`origin=subagent` 为主判据，`delegationDepth>0` 兜底。
+
+    2026-10-07 全机实测 304 个会话目录：73 个 `origin=subagent`（且 delegationDepth
+    全为 1）、231 个主会话（origin 字段缺失、delegationDepth 全为 0），两集合严格互斥。
+    两个判据都留，是防 dsh 后续只写其一。
+    """
+    if str(header.get("origin") or "") == "subagent":
+        return True
+    try:
+        return int(header.get("delegationDepth") or 0) > 0
+    except (TypeError, ValueError):
+        return False
+
+
+def is_subagent(family, sid):
+    """该会话是否 dsh **子代理会话**（主会话派生的调研/审计子代理，非用户会话）。
+
+    子代理会话与主会话同 bucket、同格式，只能靠头行区分（见 `_header_subagent`；
+    **目录名不是判据**——裸 uuid 目录 82 个里 73 个是子代理，另 9 个是老主会话）。
+    子代理是主会话的实现细节：不建看板卡、不进「绑定已有会话」下拉、不按「外部会话
+    在跑」占项目运行位（看板 sync 投影 / server 绑定下拉 / board 占用三处共用本读口）。
+
+    族不在白名单 / 存储不存在 / 头行缺失一律 False（未知按主会话处理——占用判定
+    宁多等不可误放行，与 `dshevents` 的「断连=未知」同向）。
+    """
+    if family not in FAMILIES:
+        return False
+    try:
+        path = _dsh_session_file(sid)
+    except Exception:
+        return False
+    return _header_subagent(_dsh_header(path)) if path else False
+
+
 def dsh_bucket(cwd):
     """工作区路径 → dsh 会话 bucket 目录。
 
@@ -193,8 +344,9 @@ def dsh_latest_session(cwd):
     return best
 
 
-# path -> (stamp, title, first_prompt)：标题与首问同源同缓存——两者都要全量解压
-# 会话文件，一次扫描一起取（30s 同步节拍里同一文件只解压一次）
+# path -> (stamp, title, first_prompt, titles)：当前标题、首问与全部标题事件同源
+# 同缓存——三者都要全量解压会话文件，一次扫描一起取（30s 同步节拍里同一文件只解压
+# 一次）
 _DSH_TITLE_CACHE = {}
 
 
@@ -209,15 +361,31 @@ def _line_at(text, idx):
     return text[start:] if end < 0 else text[start:end]
 
 
-def _dsh_scan_title(text):
-    """首个 session/title 事件的标题（无该事件 / 解析失败返回 ''）。"""
-    idx = text.find('"session/title"')
-    if idx < 0:
-        return ""
-    d = _obj(_line_at(text, idx))
-    if d is None or d.get("type") != "session/title":
-        return ""
-    return str((d.get("data") or {}).get("title") or "")
+def _dsh_scan_titles(text):
+    """全部 `session/title` 事件的标题，按文件顺序（无事件返回 []）。
+
+    **末枚即 DSH 当前标题**（dsh 对同一会话会写多枚：先 fallback 截断句、再由 LLM
+    标题覆盖、用户显式改名再追加；GUI 侧栏显示 last-wins 的那一枚）。平台侧一律
+    取同一口径（会话窗 / 任务标题 / 看板 sync 卡标题）；`list_sessions` 另把整串
+    下发给看板，用于判定「卡面标题是否仍是平台自动写入的形态」。
+
+    逐次 find + **整行 JSON 校验**（同 `_dsh_scan_prompt`）：非事件行里出现同名
+    字符串（坏行 / 别处文本）一律跳过；空标题事件跳过（dsh 不会写空标题，真出现
+    时按「不表态」处理，避免把当前标题抹成空串）。
+    """
+    out = []
+    pos = 0
+    while True:
+        idx = text.find('"session/title"', pos)
+        if idx < 0:
+            return out
+        pos = idx + 1
+        d = _obj(_line_at(text, idx))
+        if d is None or d.get("type") != "session/title":
+            continue
+        title = str((d.get("data") or {}).get("title") or "")
+        if title:
+            out.append(title)
 
 
 def _dsh_scan_prompt(text):
@@ -225,7 +393,7 @@ def _dsh_scan_prompt(text):
 
     判定与会话窗口的 user entry 同口径：`user/message` 且 `source.kind == "user"`
     （系统注入的 plugin / agent-instructions 消息被过滤）；文本块按换行拼接、
-    **原样保留内部换行**——调用方（看板同步卡）再按「首行进标题、其余进描述」切。
+    **原样保留内部换行**——调用方（看板同步卡）直接作为卡描述（首问全文）。
     只有图片没有文本的提问返回 `[图片]`（沿用会话窗的图片占位口径）。
 
     「第一条」按**文件顺序**取（会话窗的展示顺序；真机 20 个会话核对：文件序首条
@@ -254,31 +422,33 @@ def _dsh_scan_prompt(text):
 
 
 def _dsh_meta(path):
-    """一次解压取出 (会话标题, 主会话首问原文)，按文件 stamp 缓存。
-
-    - 会话标题 = **首个** `session/title` 事件的 title。dsh 对同一会话会写多枚标题
-      事件（先 fallback 截断句、再由 LLM 标题覆盖、用户显式改名再追加），本平台
-      此处沿用既有「首个」口径（会话窗 / 任务标题同源），与 dsh GUI 的 last-wins
-      当前标题不一致——差异与取舍见 doc_ai/spec/board/看板增强.md「sync 会话归类」。
-    - 首问 = 见 `_dsh_scan_prompt`，是看板 sync 卡标题/描述的数据源。
+    """一次解压取出 (当前标题, 主会话首问原文, 全部标题事件)，按文件 stamp 缓存。
+
+    - 当前标题 = `titles` 的**末枚**（`session/title` 事件 last-wins）= dsh GUI 侧栏
+      显示的标题（口径说明见 `_dsh_scan_titles`）；
+    - 首问 = 见 `_dsh_scan_prompt`，是看板 sync 卡描述（首问全文）的数据源；
+    - 全部标题事件（tuple）= 该会话历史上出现过的每个标题，看板 sync 卡据此判定
+      「卡面标题是否仍是平台自动写入的形态」（建卡时只有兜底标题、LLM 标题后到的
+      窗口里，旧的兜底标题只存在于事件历史中）。
     """
     try:
         st = os.stat(path)
         stamp = (st.st_mtime_ns, st.st_size)
     except OSError:
-        return "", ""
+        return "", "", ()
     hit = _DSH_TITLE_CACHE.get(path)
     if hit and hit[0] == stamp:
-        return hit[1], hit[2]
+        return hit[1], hit[2], hit[3]
     text = _dsh_decompressed(path)
-    title = _dsh_scan_title(text)
+    titles = tuple(_dsh_scan_titles(text))
+    title = titles[-1] if titles else ""
     prompt = _dsh_scan_prompt(text)
-    _DSH_TITLE_CACHE[path] = (stamp, title, prompt)
-    return title, prompt
+    _DSH_TITLE_CACHE[path] = (stamp, title, prompt, titles)
+    return title, prompt, titles
 
 
 def dsh_title(sid):
-    """读取 dsh 会话标题（首个 session/title 事件），无/不可读返回 ''。"""
+    """读取 dsh 会话当前标题（最后一枚 session/title 事件），无/不可读返回 ''。"""
     path = _dsh_session_file(sid)
     return _dsh_meta(path)[0] if path else ""
 
@@ -286,7 +456,7 @@ def dsh_title(sid):
 def dsh_first_prompt(sid):
     """读取主会话第一条真实用户提问的原文（可多行），无/不可读返回 ''。
 
-    看板 sync 卡的标题/描述数据源（见 board.sync_sessions）：会话还没收到提问时
+    看板 sync 卡的描述数据源（见 board.sync_sessions）：会话还没收到提问时
     返回 ''，调用方按会话标题 / sid 短码兜底，首问落盘后由同步节拍补齐。
     """
     path = _dsh_session_file(sid)
@@ -344,6 +514,18 @@ def _parse_dsh(path):
                     col.add("think", tm, text=b.get("text", ""))
                 elif b.get("type") == "text":
                     col.add("assistant", tm, text=b.get("text", ""))
+            # 上下文占用分子（会话窗 ctx 圈）：每次模型调用结算的 prompt 侧 token 数，
+            # last-wins（无 usage 的中断消息不参与，槽位保留上一次可用的值）
+            used = _dsh_prompt_tokens(data.get("usage"))
+            if used is not None:
+                col.ctx["used"] = used
+        elif t == "request/context":
+            # 上下文占用分母（会话窗 ctx 圈）：宿主为该路由解析出的上下文窗口
+            # （适配器声明才有；中途 /model 换模型会再落一条，故 last-wins）。
+            # 0/缺失一律忽略——窗口必须为正才有意义（宿主 schema 也是 positive）。
+            win = _nonneg_int(data.get("contextWindow"))
+            if win:
+                col.ctx["max"] = win
         elif t == "tool/call":
             cid = data.get("callId", "")
             tool_names[cid] = data.get("name", "")
@@ -460,6 +642,8 @@ def load(family, sid, agent, after=0):
     或 {"found": False, "reason": "missing" | "unsupported"}。
     entries 为 seq >= after 的增量；total 为全量条数（变小时客户端应重置重拉）。
     dsh 为单线会话（固定 main，无子 agent）。
+    另在**分母（上下文窗口）已知**时附带 `ctx`（会话窗底栏占用圈的数据源，
+    见 _dsh_prompt_tokens / `request/context`）；窗口未知时**不带**该键。
     """
     if family not in FAMILIES:
         return {"found": False, "reason": "unsupported"}
@@ -476,14 +660,21 @@ def load(family, sid, agent, after=0):
         cache = _CACHE.get(key)
         if cache is None or cache["stamp"] != stamp:
             col = _parse_dsh(zpath)
-            cache = {"stamp": stamp, "entries": col.entries, "totals": col.totals}
+            cache = {"stamp": stamp, "entries": col.entries, "totals": col.totals,
+                     "ctx": col.ctx}
             _CACHE[key] = cache
     except (OSError, ValueError):
         return {"found": False, "reason": "missing"}
     entries = cache["entries"]
     after = max(0, int(after or 0))
-    return {"found": True, "agents": agents, "agent": agent,
-            "entries": entries[after:], "total": len(entries), "totals": cache["totals"]}
+    out = {"found": True, "agents": agents, "agent": agent,
+           "entries": entries[after:], "total": len(entries), "totals": cache["totals"]}
+    # 上下文占用（会话窗底栏 ctx 圈，2026-10-10）：只在**分母已知**时下发——前端按
+    # `+ctx.max > 0` 决定画不画进度弧，窗口未知时给了也只能画成 0%（本次修的旧形态）。
+    # 分子缺省 0：窗口已知但还没有一次模型调用＝空上下文，0% 是真实读数。
+    if cache["ctx"]["max"]:
+        out["ctx"] = {"used": cache["ctx"]["used"] or 0, "max": cache["ctx"]["max"]}
+    return out
 
 
 def resolve_media(family, sid, agent, media_id):
@@ -564,7 +755,8 @@ def _dsh_archived_ids():
 def session_title(family, sid):
     """统一会话标题读取（异常静默返回 ''，标题只是展示增强，不打断主流程）。
 
-    dsh 标题取会话 `session/title` 事件；族不在白名单返回 ''。
+    dsh 标题取会话**当前**标题（末枚 `session/title` 事件，与 dsh GUI 侧栏一致）；
+    族不在白名单返回 ''。
     """
     if family not in FAMILIES:
         return ""
@@ -580,6 +772,10 @@ def _list_dsh(cwd):
 
     目录名两代并存：`session-<uuid>` 与裸 `<uuid>`；文件名带格式版本
     （session.v4.jsonl.zstd 等），故目录匹配与文件匹配都用通配（见 _dsh_session_file）。
+    **子代理会话不进列表**（2026-10-07 实障修复）：它由主会话派生，被当成独立会话
+    会各自建卡（实测 72 张、70 张永留「待审核」）并在跑时占项目运行位，判据取会话
+    头行的 origin/delegationDepth（见 `is_subagent`）。裸 uuid 目录**不代表**是子代理：
+    实测 82 个里 73 个是子代理、9 个是老主会话。
     归档只影响归档标记：会话目录仍在 bucket 里，列表照常枚举到它（平台据此把
     归档会话建成落在「已完成」的 sync 卡 / 在绑定下拉里标 [已归档]）。
     """
@@ -594,20 +790,24 @@ def _list_dsh(cwd):
         except OSError:
             continue
         sid = os.path.basename(sdir)
-        # 一次解压同时取标题与首问（同 stamp 缓存）：看板 sync 卡建卡/补齐标题都要
-        # 首问，逐会话各调一次读口会重复解压同一个文件（见 _dsh_meta）
-        title, first_prompt = _dsh_meta(zfile)
-        out.append({"sid": sid, "title": title, "first_prompt": first_prompt,
+        if _header_subagent(_dsh_header(zfile)):
+            continue            # 子代理会话：先判头行再解全量（省一次整段解压）
+        # 一次解压同时取当前标题、首问与全部标题事件（同 stamp 缓存）：看板 sync 卡
+        # 建卡/标题同步都要后两者，逐会话各调一次读口会重复解压同一个文件（见 _dsh_meta）
+        title, first_prompt, titles = _dsh_meta(zfile)
+        out.append({"sid": sid, "title": title, "titles": list(titles),
+                    "first_prompt": first_prompt,
                     "mtime": mtime, "archived": sid in archived})
     return out
 
 
 def list_sessions(family, cwd):
-    """按工作区枚举 dsh 会话 [{sid, title, first_prompt, mtime秒, archived}]，
+    """按工作区枚举 dsh 会话 [{sid, title, titles, first_prompt, mtime秒, archived}]，
     mtime 降序、上限 LIST_SESSIONS_LIMIT。
 
-    `title` = 首个会话标题事件，`first_prompt` = 主会话第一条真实用户提问原文
-    （看板 sync 卡取它做「首行=标题、其余=描述」）。
+    `title` = **当前**会话标题（末枚 session/title 事件，与 dsh GUI 一致）、
+    `titles` = 全部标题事件、`first_prompt` = 主会话第一条真实用户提问原文
+    （看板 sync 卡取它做描述、取 title 做卡标题）。
 
     供看板「绑定已有会话」下拉与「自动同步」共用；`archived` 读宿主归档集
     （`<dsh home>/storages/workspace.json` 的 `global.archivedSessionIds`，读不到

package/touchstone.py

@@ -6,7 +6,7 @@ Windows 原生运行的首选入口（bash/nohup/kill 不可用），Linux 上
 .run/server.log）。用法:
 
     python3 touchstone.py start|stop|restart|status|build|test|test-full|test-ui
-    # Windows: python touchstone.py 或 touchstone.cmd
+    # Windows: python touchstone.py 或 touchstone.cmd（后者自动解析 python → python3）
 
 行为对齐 touchstone.sh:
 - start / restart 先按需构建前端（npm install 按需：依赖指纹未变化则跳过，
@@ -117,8 +117,11 @@ def precheck_deps():
         import requests   # noqa: F401
         import zstandard  # noqa: F401
     except ImportError as e:
-        print_err(f"错误: python3 缺少运行依赖（{e}），请先执行:")
-        print_err("    python3 -m pip install -r requirements.txt")
+        # 用当前解释器自己的路径提示（不写死 python3/python）: Windows 官方安装器只有
+        # `python.exe`、Linux 惯例是 `python3`, 报用户机器上真正在跑的那个最不容易误导。
+        py = sys.executable or "python"
+        print_err(f"错误: 当前解释器缺少运行依赖（{e}），请先执行:")
+        print_err(f"    {py} -m pip install -r requirements.txt")
         sys.exit(1)
 
 
@@ -448,7 +451,8 @@ def cmd_test_full():
     ran = 0
     for name in ("e2e_board_continue.py", "e2e_board_stream.py", "e2e_chat_queue.py",
                  "e2e_unit_state.py", "e2e_stress_case.py", "e2e_board_archive.py",
-                 "e2e_board_worktree.py"):
+                 "e2e_board_worktree.py", "e2e_ext_stale_recovery.py",
+                 "e2e_subagent_no_occupancy.py"):
         script = os.path.join(ROOT, "tests", name)
         if not os.path.isfile(script):
             print(f"(跳过: 未随附 tests/{name})")

package/waitq.py

@@ -727,6 +727,9 @@ def selfcheck(probe=None):
     的扫描集内**——③ 只取 `kind=KIND_CARD` 的活跃行，ext 行永不被 ③ 覆盖
     （v3 终审修复：原文「③ 只对『卡行已删』形态告警」不成立；③ 的实际报告面
     是两类 c: 行形态——卡不在 doing（列已非开发容器）+ 卡行已删（行无主））。
+    反向形态「占位在、行不在」（doing+queue 卡无活跃 c: 行）**不在本函数面**：
+    它要读 board_cards 的排队占位语义，归 `board._heal_queue_placeholders`
+    的 30s 节拍（报告 + 补建一体，2026-10-10 实障卡 936）。
     probe：行判活探针（web busy 三态；`selfcheck_units` 透传，直调缺省 None）。
     """
     problems = []
@@ -1216,6 +1219,26 @@ def msg_get(msg_id):
                             (str(msg_id),)).fetchone()
 
 
+def msg_meta(msg_id):
+    """消息等待项 meta（取该 target 的**最后一行**，含终态行）：飞书回流钩子在
+    终态收口之后读「提交时定格」的载荷（feishu 命名空间）。无行返回 {}，坏 JSON 亦 {}。
+
+    只读口：与 msg_get 相邻；口径上不看 state（收口已把行落终态，活跃口径读不到），
+    也不去 join chat_msgs——载荷只在等待项行上（chat_msgs 无 meta 列）。
+    """
+    with db.connect() as conn:
+        row = conn.execute(
+            "SELECT meta FROM wait_items WHERE kind=? AND target_id=?"
+            " ORDER BY id DESC LIMIT 1", (KIND_MSG, str(msg_id))).fetchone()
+    if row is None:
+        return {}
+    try:
+        meta = json.loads(row["meta"] or "{}")
+    except ValueError:
+        return {}
+    return meta if isinstance(meta, dict) else {}
+
+
 def msg_rows(sid=None, card_id=None, states=None):
     """消息行查询（chat 读侧专用）：sid/card_id/states 可选过滤，created_at 升序
     （idx_chat_msgs_sid 覆盖 sid 过滤）；states 传元组。"""