pi-multi-viewers 0.2.2 → 0.4.0

package/observability.py

@@ -9,6 +9,7 @@ human_viewer（observability 是"读"侧，human_viewer.incremental 是它
 的进展数据源）；不准 import 主文件。
 """
 
+import datetime
 import glob
 import json
 import os
@@ -326,27 +327,94 @@ def build_report(base):
                    f"{_dur(d['max_ms'] // 1000)} | rc≠0 {d['fails']} 次")
 
     # ---- LLM 运行事实（session 文档化字段；流式预过滤，不整文件解析） ----
+    # ---- 终止原因（只报事实与计数）----
+    _report_termination(base, agents, out)
+
+    # ---- 每次唤醒构成表（零插桩事后推导）----
+    _report_wake_table(base, agents, out)
+
     out.append("LLM（session 文档化字段）：")
     any_usage = False
     for a in agents:
-        u = _report_session_usage(base, a)
-        if not u:
+        m = _report_session_metrics(base, a)
+        if not m:
             out.append(f"  {a}: n/a")
             continue
         any_usage = True
-        out.append(f"  {a}: input {u['input']} | cacheRead "
-                   f"{u['cache_read']} | output {u['output']} | 响应 "
-                   f"{u['responses']} 次 | error {u['errors']} 次")
+        u = m["usage"]
+        # usage 合计：reasoning ⊂ output（**不可相加**）——缺席时省略该括注
+        # （缺席 ≠ 0），出现时即使为 0 也写出
+        rea = ("" if u["reasoning"] is None
+               else f"（reasoning {_num(u['reasoning'])}）")
+        out.append(f"  {a}: 响应 {m['responses']} 次 | input {_num(u['input'])}"
+                   f" | cacheRead {_num(u['cacheRead'])}"
+                   f" | output {_num(u['output'])}{rea}")
+        # 按 stopReason 原值分组：**键集固定，不随数据增长**——新同类数字
+        # 只多一个键。error 那笔账（计数 + 时长）就在这里，这是 provider
+        # 失败从"完全不可见"变为"一行可读"的落点。
+        # 键 = 原值（含 None）：解释性命名会因"长消息也是 toolUse"立刻过期。
+        parts = []
+        for k in sorted(m["stop"], key=lambda x: (x is None, x or "")):
+            d = m["stop"][k]
+            parts.append(f"{k if k is not None else '（无）'} "
+                         f"{d['n']}（{_dur(d['sec'])}）")
+        out.append(f"      stopReason：{' | '.join(parts)}")
     if not any_usage:
         out.append("  n/a（session 缺失，或无本轮数据——边界条目自 2026-09-11 "
                    "起写入，此前的老分析不适用）")
+    # ---- 档位对照：声明值（spec/pi-agent.json）vs 生效值（session） ----
+    out.append(_report_levels_line(base, agents))
     out.append("（口径：进程跨度=pi 进程生命周期；输出=prompt 分段合计；"
                "墙钟=commit 时间差——三者不可互替；"
+               "stopReason 括注 = **相邻条目 Δ 合计**（含每次唤醒首条响应；"
+               "跨唤醒空闲不进入 Δ——唤醒 prompt 本身是一条 user 条目）；"
                "消息数含流程信号（freezing/pass/concluded）与 human，"
                "配额只计 meeting 发言）")
     return out
 
 
+def _report_levels_line(base, agents):
+    """档位对照行：**声明值 vs 生效值**（e2e17 评审 §1）。
+
+    为什么需要：声明值（`pi-agent.json.thinking`）从来没人跟生效值对照过——
+    探测失败 → 静默取 DEFAULT_THINKING，spec 文件表面完全正常。这一行是那个
+    缺口的最小可见性形态：**零新增字段**（两个值都已有家，只是从没被并列读出）、
+    **零新增分支**（集合比较）。
+
+    生效值来源 = session 的 `thinking_level_change` 条目（pi 在会话缺该条目时
+    写入，位于边界之后）——**本仓只读，不复刻 pi 的解析链**（那是 pi 的配置）。
+    fail-open：任一侧读不到 → 显式 n/a（不猜、不写 0）。
+    """
+    declared, effective = {}, {}
+    for a in agents:
+        try:
+            with open(os.path.join(base, f"work-{a}", "pi-agent.json")) as f:
+                v = json.load(f).get("thinking") or ""
+            if v:
+                declared[a] = v
+        except (OSError, ValueError):
+            continue
+        levels = _report_session_levels(base, a)
+        effective[a] = levels
+    if not declared and not effective:
+        return "档位：n/a（无 pi-agent.json 且无 session 档位条目）"
+    d_set = set(declared.values())
+    e_set = {x for v in effective.values() for x in v}
+    d_txt = "、".join(sorted(d_set)) if d_set else "n/a"
+    e_txt = "、".join(sorted(e_set)) if e_set else "n/a"
+    if d_set and e_set:
+        same = (
+            f"✓ 一致" if d_set == e_set
+            # 不一致是两个方向的异常：声明了没生效（写错/被覆盖），或生效值
+            # 不在声明里（外部改档/会话遗留）——两种都要人看到
+            else f"⚠ 不一致（声明 {d_txt} / 生效 {e_txt}）")
+    else:
+        same = "（一侧 n/a，无法对照）"
+    detail = "、".join(f"{a} {v or 'n/a'}"
+                       for a, v in ((a, declared.get(a, "")) for a in agents))
+    return f"档位：声明 {d_txt}（{detail}）| 生效 {e_txt} | {same}"
+
+
 def _dur(sec):
     """人类可读时长（口径由调用方在同一行标注——进程跨度/墙钟/间隔）。"""
     sec = int(sec)
@@ -361,6 +429,195 @@ def _hhmm(ts):
     return time.strftime("%H:%M:%S", time.localtime(ts))
 
 
+def _parse_wake_windows(base, agent):
+    """从一个 agent 的 loop log 解析每次唤醒的窗口（零判定输入——只读登记行）。
+
+    返回 [(spawn_epoch, exit_epoch, elapsed_ms, rc, retries)]；日志时间戳是
+    **本地无时区**（`[2026-09-13T19:43:10.123]`）→ 转 epoch 再与 session 的
+    UTC 时间戳 / git 的 epoch 对齐。fail-open：文件缺失 → []。
+    """
+    path = os.path.join(base, f"loop-{agent}.log")
+    wakes, cur = [], None
+    try:
+        lines = open(path, encoding="utf-8", errors="replace").read().splitlines()
+    except OSError:
+        return []
+    for line in lines:
+        m = re.match(r"\[([^\]]+)\]\s+\S+:\s+(.*)$", line)
+        if not m:
+            continue
+        try:
+            dt = datetime.datetime.fromisoformat(m.group(1))
+        except ValueError:
+            continue
+        epoch = time.mktime(dt.timetuple()) + dt.microsecond / 1e6
+        body = m.group(2)
+        if body.startswith("唤醒 pi"):
+            cur = [epoch, None, 0, 0, 0]
+        elif cur is not None and body.startswith("pi 完成"):
+            mm = re.search(r"elapsed_ms=(\d+) rc=(-?\d+)", body)
+            if mm:
+                cur[1] = epoch
+                cur[2] = int(mm.group(1))
+                cur[3] = int(mm.group(2))
+                wakes.append(tuple(cur))
+            cur = None
+        elif cur is not None and "无产出" in body and "重试" in body:
+            cur[4] += 1
+    return wakes
+
+
+def _agent_event_roles(base, agent):
+    """该 agent 本轮（边界之后）的事件流：[(epoch, role)]——顺序读取，fail-open。"""
+    fp = _agent_session_file(base, agent)
+    if not fp:
+        return []
+    out = []
+    for ev in meeting_fs.iter_after_boundary(fp):
+        m = ev.get("message") or {}
+        role, ts = m.get("role"), ev.get("timestamp")
+        if not role or not ts:
+            continue
+        try:
+            out.append((datetime.datetime.fromisoformat(
+                ts.replace("Z", "+00:00")).timestamp(), role))
+        except ValueError:
+            continue
+    return out
+
+
+def _wake_rows(base, agent, commits):
+    """每次唤醒的构成记录（零插桩事后推导；精度契约见 design.md 观测面契约）。
+
+    每条 = 四端点（spawn / 首事件 / 末事件 / exit）+ 往返数 + assistant Δ +
+    toolResult Δ + retry + 本唤醒内的 commit。**不承诺**单次调用内的
+    TTFT/生成拆分（session 只有完成时间戳）。
+    """
+    wakes = _parse_wake_windows(base, agent)
+    if not wakes:
+        return []
+    events = _agent_event_roles(base, agent)
+    rows = []
+    for i, (t0, t1, ms, rc, retries) in enumerate(wakes, 1):
+        t1 = t1 or (t0 + ms / 1000)
+        row = {"n": i, "spawn": t0, "exit": t1, "ms": ms, "rc": rc,
+               "retries": retries, "rounds": 0, "d_assist": 0.0,
+               "d_tool": 0.0, "first": None, "last": None, "commit": None}
+        prev = None
+        for t, role in events:
+            if not (t0 - 2 <= t <= t1 + 2):
+                continue
+            if role == "assistant":
+                row["rounds"] += 1
+                if prev is not None and t >= prev:
+                    row["d_assist"] += t - prev
+            elif role == "toolResult" and prev is not None and t >= prev:
+                row["d_tool"] += t - prev
+            if row["first"] is None:
+                row["first"] = t
+            row["last"] = t
+            prev = t
+        for c in commits:
+            if t0 <= c <= t1:
+                row["commit"] = c
+                break
+        rows.append(row)
+    return rows
+
+
+def _report_wake_table(base, agents, out):
+    """每次唤醒构成表 + 聚合（只读 loop log / session / bare 三处已有事实）。"""
+    r = meeting_fs.run_git(meeting_fs.bare_of_base(base), "log",
+                           "--format=%ct", check=False)
+    commits = sorted(int(x) for x in r.stdout.split() if x.isdigit())
+    any_row = False
+    for agent in agents:
+        rows = _wake_rows(base, agent, commits)
+        if not rows:
+            continue
+        if not any_row:
+            out.append("唤醒构成（每次一行；Δ 助手/Δ 工具 = 相邻条目差，"
+                       "不含跨唤醒空闲）：")
+            any_row = True
+        start = tail = inner = 0.0
+        decomposed = no_ev = 0      # 无 session 事件的唤醒无法分解（不冒充 0）
+        for row in rows:
+            pre = (row["first"] - row["spawn"]) if row["first"] else 0.0
+            post = (row["exit"] - row["last"]) if row["last"] else 0.0
+            inner += (row["last"] - row["first"]) if row["first"] else 0.0
+            start += pre
+            tail += post
+            if row["first"]:
+                decomposed += row["ms"] / 1000
+            else:
+                no_ev += 1
+            retry = f" retry×{row['retries']}" if row["retries"] else ""
+            commit = _hhmm(row["commit"]) if row["commit"] else "—"
+            out.append(
+                f"  {agent} #{row['n']:>2} {_hhmm(row['spawn'])}"
+                f" 启动{pre:4.1f}s"
+                f" 内{_dur(row['last'] - row['first']) if row['first'] else 'n/a':>7}"
+                f" 收尾{post:4.1f}s | 往返 {row['rounds']:>2}"
+                f" | Δ助手 {_dur(row['d_assist']):>6} Δ工具 {_dur(row['d_tool']):>6}"
+                f" | commit {commit}{retry}"
+                + ("  rc≠0" if row["rc"] else ""))
+        total = sum(x["ms"] for x in rows) / 1000
+        out.append(f"  {agent} 合计：{len(rows)} 唤 | 跨度 {_dur(total)} = "
+                   f"启动前 {_dur(start)} + 事件内 {_dur(inner)} + 收尾 {_dur(tail)}"
+                   f" | 平均 {total / len(rows):.1f}s"
+                   f" | 往返 {sum(x['rounds'] for x in rows)}"
+                   f" | retry {sum(x['retries'] for x in rows)}"
+                   + (f" | 未分解 {no_ev} 次（无 session 事件）" if no_ev else ""))
+        # 对账恒等式（e2e23 分析产出）：**仅有事件的那部分**应满足
+        # Σ(启动+事件内+收尾) = Σ进程跨度；差>2s 说明时间源没对齐
+        # （loop 日志=本地无时区 / session=UTC）。只报告事实，不进任何代码
+        # 分支（跨度阈值不得参与判定，观测面契约）。
+        diff = abs((start + inner + tail) - decomposed)
+        if diff > 2:
+            out.append(f"    恒等校验：Σ(启动+事件内+收尾) 与可分解跨度 差 "
+                       f"{diff:.1f}s——时间源未对齐（日志=本地时区，"
+                       f"session=UTC）")
+    if not any_row:
+        out.append("唤醒构成：n/a（无 loop log 或无登记行）")
+
+
+def _report_termination(base, agents, out):
+    """终止原因——**只报事实与计数**（不做评分/判定；观测面契约）。"""
+    bare = meeting_fs.bare_of_base(base)
+    msgs = meeting_engine.each_agent_messages(bare, agents)
+    types = {}
+    for a in agents:
+        for fm in msgs.get(a, []):        # each_agent_messages → frontmatter dict 列表
+            t = (fm or {}).get("type")
+            types[t] = types.get(t, 0) + 1
+    has_result = bool(meeting_fs.run_git(bare, "show", "HEAD:result.md",
+                                        check=False).stdout.strip())
+    stalls = 0
+    for f in glob.glob(os.path.join(base, "loop-*.log")):
+        try:
+            txt = open(f, encoding="utf-8", errors="replace").read()
+        except OSError:
+            continue
+        stalls += txt.count("超时兜底") + txt.count("声明接管")
+    if not meeting_fs.read_protocol(bare).get("participants"):
+        out.append("终止：n/a（协议不可读）")
+        return
+    if stalls:
+        why = "stall 接管"
+    elif types.get("pass"):
+        why = "共识（RR 全体 pass）"
+    elif types.get("freezing") or types.get("all-freezing"):
+        why = "配额耗尽（冻结，无 pass）"
+    elif has_result:
+        why = "已收尾（无 pass/冻结记录）"
+    else:
+        why = "未完成"
+    out.append(f"终止：{why} | freezing {types.get('freezing', 0)}"
+               f" / all-freezing {types.get('all-freezing', 0)}"
+               f" / pass {types.get('pass', 0)} / stall 接管行 {stalls}"
+               + (" | result.md 已提交" if has_result else ""))
+
+
 def _report_wake_fields(base):
     """解析 loop-*.log 的登记字段（`elapsed_ms` / `rc`）。
 
@@ -390,48 +647,113 @@ def _report_wake_fields(base):
     return out
 
 
-def _report_session_usage(base, agent):
-    """从该 agent 的 session 文件取 usage（**单一适配器** + 流式预过滤）。
+def _report_session_metrics(base, agent):
+    """该 agent **本轮**（边界之后）的 session 运行事实——**单一适配器**。
 
     字段来源 = pi 的**文档化** session schema（`docs/session-format.md`：
-    `usage` / `stopReason`）。行级预过滤（`"usage" in line` 才 json.loads）
-    ——避免对 MB 级文件整解析（实测 json.loads 3MB ≈27ms，预过滤可省大部分）。
+    `usage` / `stopReason` / `timestamp`）——**只读已有家，不新增记录**
+    （同一事实两处 = 双写；loop log 的不变量是零判定输入）。
+
+    返回：{responses, usage: {input, cacheRead, output, reasoning},
+           stop: {stopReason 原值: {"n": 次数, "sec": 响应跨度合计}}}
+    `usage["reasoning"]` = None 表示**从未出现**（缺席 ≠ 0）。
+
+    响应跨度口径：`Δt = ts(本条) − ts(紧邻前一条事件)`——单次遍历顺序读取，
+    不需要随机访问。**每次唤醒的首条响应也计入**：每次唤醒都会在 session 里
+    写入 user 条目（唤醒 prompt），跨唤醒空闲落在"上一唤醒末条 → 本次 user
+    条目"之间，**从不进入任何 Δ**（e2e20 评审批实测：本场 7 个唤醒 user 条目
+    每个后面直接跟 assistant；首响 Δ 与非首响同量级，无分钟级样本）。
+    **不做"首响不计时"**：那是基于错误归因的排除——当时以为 e2e19 的
+    "Δ 合计 33m09s > 进程跨度 13m09s"来自跨唤醒空闲，实际根因是边界子串
+    误判（`iter_after_boundary` 把历史条目算进本轮；修好后 ΣΔ ≤ 墙钟成立），
+    排除掉的是真数据里常最贵的那条。
+    error 类单列（usage 全零）——不并入也不丢弃：否则 provider 抖动会被算成
+    "生成变慢"（e2e14 评审）。
     fail-open：文件缺失/字段变 → 返回 {}。
     """
-    try:
-        with open(os.path.join(base, f"status-{agent}.json")) as f:
-            sid = json.load(f).get("sessionID") or ""
-    except (OSError, ValueError):
-        sid = ""
-    if not sid:
-        return {}
-    fp = os.path.join(base, "pi-sessions", f"fork-src-{sid}.jsonl")
-    if not os.path.isfile(fp):
+    fp = _agent_session_file(base, agent)
+    if not fp:
         return {}
     # **只统计边界之后的条目**（本轮运行事实）——fork 携带的历史条目里也
     # 有大量 assistant+usage，全文件统计会把主 pi 的历史算成本次分析的
     # 消耗（2026-09-11 实测：717 条 fork 历史被算成"本轮 367 次响应 /
     # input 1.2M"）。边界由 append_handoff_turns 写入（显式登记，非推断）。
-    u = {"input": 0, "cache_read": 0, "output": 0, "responses": 0, "errors": 0}
+    r = {"responses": 0,
+         "usage": {"input": 0, "cacheRead": 0, "output": 0,
+                   "reasoning": None},
+         "stop": {}}
+    prev_ts = None
     for ev in meeting_fs.iter_after_boundary(fp):
         m = ev.get("message") or {}
         if m.get("role") != "assistant":
+            prev_ts = ev.get("timestamp") or prev_ts
             continue
-        u["responses"] += 1
-        if m.get("stopReason") == "error":
-            u["errors"] += 1
+        r["responses"] += 1
+        reason = m.get("stopReason")
+        dur = _delta_seconds(prev_ts, ev.get("timestamp"))
+        d = r["stop"].setdefault(reason, {"n": 0, "sec": 0})
+        d["n"] += 1
+        if dur is not None:
+            d["sec"] += dur
         usage = m.get("usage") or {}
-        for k, key in (("input", "input"), ("cacheRead", "cache_read"),
+        for k, key in (("input", "input"), ("cacheRead", "cacheRead"),
                        ("output", "output")):
             v = usage.get(k)
             if isinstance(v, int):
-                u[key] += v
-    if not u["responses"]:
+                r["usage"][key] += v
+        rv = usage.get("reasoning")
+        if isinstance(rv, int):
+            r["usage"]["reasoning"] = (r["usage"]["reasoning"] or 0) + rv
+        prev_ts = ev.get("timestamp") or prev_ts
+    if not r["responses"]:
         return {}
-    # 数字格式化（人读）：千分位缩写
-    for k in ("input", "cache_read", "output"):
-        u[k] = _num(u[k])
-    return u
+    return r
+
+
+def _delta_seconds(prev_iso, cur_iso):
+    """两个 ISO 时间戳的秒差；任一缺失/不可解析 → None（缺席 ≠ 0）。"""
+    if not prev_iso or not cur_iso:
+        return None
+    try:
+        a = datetime.datetime.fromisoformat(prev_iso.replace("Z", "+00:00"))
+        b = datetime.datetime.fromisoformat(cur_iso.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    d = (b - a).total_seconds()
+    return d if d >= 0 else None
+
+
+def _agent_session_file(base, agent):
+    """该 agent 的 fork 源 session 文件路径（找不到 → ""）。"""
+    try:
+        with open(os.path.join(base, f"status-{agent}.json")) as f:
+            sid = json.load(f).get("sessionID") or ""
+    except (OSError, ValueError):
+        sid = ""
+    if not sid:
+        return ""
+    fp = os.path.join(base, "pi-sessions", f"fork-src-{sid}.jsonl")
+    return fp if os.path.isfile(fp) else ""
+
+
+def _report_session_levels(base, agent):
+    """该 agent 本轮**生效的 thinking 档位**（去重、保序）——session 侧的家。
+
+    pi 在会话缺 `thinking_level_change` 条目时写入它（每次打开会话至多一次），
+    且位于我们的边界之后——所以边界过滤后读到的就是"本场生效值"。
+    **本仓只读，不复刻 pi 的解析链**（`modelThinkingLevels` →
+    `defaultThinkingLevel` 是 pi 的配置，复刻 = 两处实现/必漂移）。
+    """
+    fp = _agent_session_file(base, agent)
+    if not fp:
+        return []
+    out = []
+    for ev in meeting_fs.iter_after_boundary(fp):
+        if ev.get("type") == "thinking_level_change":
+            lv = ev.get("thinkingLevel")
+            if lv and lv not in out:
+                out.append(lv)
+    return out
 
 
 def _num(n):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multi-viewers",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Multi-perspective analysis for Pi: fork the main session into N perspective agents over the meeting protocol.",
   "type": "module",
   "private": false,

package/prompts/multi-viewers.md

@@ -53,7 +53,7 @@ argument-hint: '"<主题>"'
 视角之间**互补或对立都可以**——对立产生的分歧正是多视角分析的价值。
 每个视角任务书必须包含：
 
-1. **单一 lenses**：明确该 agent 用什么角度看（性能/简单化/安全/……），
+1. **单一 lenses**：明确该 agent 用什么角度看（效率/简单化/安全/……），
    要求"所有观点必须从该视角出发"
 2. **不越界**："其它视角由别的参与者负责，你不要越界展开"（**不要**列举
    具体是哪几个视角——参与者会变，列举会过期）

package/scripts/check-residue.sh

@@ -4,6 +4,10 @@
 # 用法: ./scripts/check-residue.sh [--verbose]
 # 退出码: 0 = 干净；1 = 有残留（列出清单）
 #
+# **调用纪律**（2026-09-12）：看退出码 + 末行 `[residue] ...` 汇总；
+# 不要只 grep 某一类残留——那会把其它类整块滤掉，把"有残留"跑成"看起来
+# 干净"（实测：grep 残留-2|残留-3 滤掉了 4 个 session 残留）。
+#
 # 检查三类测试残留形态（2026-09-09 建立——此前靠人工记忆逐项检查，
 # 反复漏检：afk-e2e 引导 session 漏删即反例）：
 #   1. 主 pi 侧 session：~/.pi/agent/sessions/<编码目录>/*.jsonl 中
@@ -40,6 +44,9 @@ is_registered() {
 }
 
 RESIDUE=0
+N_SESSION=0
+N_PROC=0
+N_DIR=0
 
 say() { [ "$1" = "--verbose" ] || [ -n "$VERBOSE" ] && echo "$2"; }
 
@@ -64,16 +71,25 @@ for d in "$SESS_DIR"/*/; do
                 "$w"*|"$w") whitelisted=1 ;;
             esac
         done
-        if [ "$whitelisted" = "0" ]; then
-            # 归属判定（2026-09-09）：登记日志回查——已登记=测试产物
-            # （可删），未登记=非本流程创建（勿删，提示加白名单）。
-            # 首条消息摘要仅作补充信息（不再作为删除判断依据）。
-            if is_registered "$f"; then
-                owner="[已登记-测试产物，可删]"
-            else
-                owner="[未登记-非本流程创建，勿删]"
-                RESIDUE=1
-            fi
+        # 归属判定（2026-09-09 起）：登记日志回查——已登记=测试产物（可删），
+        # 未登记=非本流程创建（勿删，提示加白名单）。首条消息摘要仅作补充
+        # 信息（不作删除依据）。
+        # **登记优先于白名单**（2026-09-12 修）：登记是**显式事实**（创建即
+        # 登记），白名单是**按 cwd 的猜测**。此前白名单在前 → 探针跑在白名单
+        # 项目目录（如 --print 冒烟在 /root/pi-agents-helper）时整个文件被跳过、
+        # 连"已登记"都不报——实测漏检（那次 4 个漏检 session 里有 1 个正是此形）。
+        if is_registered "$f"; then
+            # 已登记 = **本流程测试产物**（可删）——但"还存在"本身就是残留：
+            # 验收语义是"清理完毕"→ 计入 RESIDUE（归属标记只决定谁来删）
+            owner="[已登记-测试产物，可删]"
+            RESIDUE=1
+        elif [ "$whitelisted" = "0" ]; then
+            owner="[未登记-非本流程创建，勿删]"
+            RESIDUE=1
+        else
+            continue   # 白名单 cwd 且未登记 = 用户自己的长期会话，不是残留
+        fi
+            N_SESSION=$((N_SESSION + 1))
             first_user=$(python3 -c "
 import json, sys
 try:
@@ -87,10 +103,9 @@ try:
 except Exception:
     print('')
 " 2>/dev/null)
-            echo "[残留-1] session（24h 内 cwd=$cwd，创建 $(stat -c %y "$f" | cut -d. -f1)）$owner"
-            echo "        首条消息: ${first_user:-（无 user 消息）}"
-            echo "        路径: $f"
-        fi
+        echo "[残留-1] session（24h 内 cwd=$cwd，创建 $(stat -c %y "$f" | cut -d. -f1)）$owner"
+        echo "        首条消息: ${first_user:-（无 user 消息）}"
+        echo "        路径: $f"
     done
 done
 
@@ -128,6 +143,7 @@ for d in /proc/[0-9]*; do
             */meeting_loop.py)
                 echo "[残留-2] meeting_loop 进程 PID=$pid: $(ps -p "$pid" -o cmd= 2>/dev/null)"
                 RESIDUE=1
+                N_PROC=$((N_PROC + 1))
                 LOOP_PIDS="$LOOP_PIDS $pid"
                 break
                 ;;
@@ -143,12 +159,14 @@ for d in /proc/[0-9]*; do
         # loop 已退出、pi 被 init 收养（PPID=1）——孤儿残留
         echo "[残留-2] pi 进程 PID=$pid（孤儿：PPID=1，其 loop 已退出）"
         RESIDUE=1
+        N_PROC=$((N_PROC + 1))
         continue
     fi
     case " $LOOP_PIDS " in
         *" $ppid "*)
             echo "[残留-2] pi 进程 PID=$pid（父 meeting_loop PID=$ppid）"
             RESIDUE=1
+            N_PROC=$((N_PROC + 1))
             ;;
         # 其余 comm=pi 的进程不报：用户自己正在用的 pi 会话（PPID 是
         # pi-web/shell 等）不是残留——"名称 + PPID"两个条件同时成立才判定
@@ -165,6 +183,7 @@ for d in mv-*/; do
     esac
     echo "[残留-3] 分析目录: $PWD/$d"
     RESIDUE=1
+    N_DIR=$((N_DIR + 1))
 done
 
 # 3b. 结构形态：任何含 repo.git/ + pi-sessions/ 的目录 = 讨论环境
@@ -181,10 +200,13 @@ for base in "$PWD" "${TMPDIR:-/tmp}"; do
         SEEN_ENVS="$SEEN_ENVS $d"
         echo "[残留-3] 讨论环境: $d（$(du -sh "$d" 2>/dev/null | cut -f1)）"
         RESIDUE=1
+        N_DIR=$((N_DIR + 1))
     done < <(find "$base" -maxdepth 3 -type d -name repo.git 2>/dev/null)
 done
 
-if [ "$RESIDUE" = "0" ]; then
-    echo "干净：无测试残留"
-fi
+# 汇总行：**结论只在这一行**——调用方看这一行 + 退出码即可，
+# 不必（也不得）只 grep 某一类（2026-09-12：调用方 grep "残留-2|残留-3"
+# 把 [残留-1] 整类滤掉，把有残留跑成"看起来干净"）。
+echo "[residue] session=$N_SESSION 进程=$N_PROC 目录=$N_DIR →" \
+     "$([ "$RESIDUE" = "0" ] && echo 干净 || echo 有残留)"
 exit "$RESIDUE"