@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/flow_triage.py

@@ -0,0 +1,849 @@
+#!/usr/bin/env python3
+"""flow_triage —— 流程调度/分诊：**本轮该派发什么**（只出计划，不执行）。
+
+分工（见 docs/Argent-宿主适配契约.md §1「判断归属」）：
+  flow_source  来源 → case（含字段缺口）
+  flow_triage  分诊 + 幂等/在飞/停滞/重试判定 → **派发计划**（本脚本）
+  （E3）       按计划派生 subagent 执行 —— 由会话/官方 subagent 承载，不在此脚本内
+
+台账：~/.dsh/argent/flow-ledger.jsonl，每行一条事件
+  {"ts":..,"caseId":..,"event":"dispatched|done|failed|blocked","attempt":N,"error":".."}
+判定规则（**一律按"有效末条事件"判定**，见 INFO_EVENTS）：
+  · 最近事件 dispatched 且未超在飞窗口        → in_flight（跳过）
+  · 最近事件 dispatched 且已超窗口            → stale（需人工关注/重试）
+  · 最近事件 failed 且 attempt < max-attempts → retry（重试）
+  · 最近事件 failed 且 attempt >= 上限        → needs_human
+  · 无事件                                    → to_dispatch
+  · 最近事件 blocked                          → needs_human（等人工/运营；可见优于静默）
+  · 最近事件 done / failed_ack                → 本轮不动（终态 / 人工已确认消案）
+  · 人工重新放行（Rule R，`pick.releaseReDispatch`）：最近事件 failed/blocked（或
+    `flow_retry.py` 写的 retry）**且**放行位「就绪」=true ⇒ to_dispatch（带 kind=release），
+    受「每票上限 + 冷却」约束；超限/冷却中 ⇒ needs_human（写明原因）。
+    —— 2026-09-21 用户口径：运营自己补好数据、自己勾「就绪」就该自动重跑，不必运维介入。
+  · **上游数据变了 ⇒ 放行额度重置**（2026-10-13，修「加了上限之后再也不会被拾取」的 BUG；
+    生产实测某发票票（`<flow>__79406731`）：运营按提示补好数据并重勾放行位，分诊却给
+    `release_capped`（3/3）⇒ **永远不再拾取**）。判据 = 该票**上游行走流程读取的字段**
+    相对**上次派发**的**稳定哈希**变了（⛔ 不是"又勾了一次就绪"：放行勾本身**不参与**哈希）
+    ⇒ 计数从 0 起算、写一条**信息性** `policy_apply`（`policy=release_budget_reset`）并放行；
+    ⛔ 上游未变时**不许**重置（否则退化成无限重试）。
+  · **外部时序类失败不占运营放行额度**（2026-10-13，同一现场的第二条根因：「门户尚未生成/
+    标签未就绪」被记成"运营该补数据"，运营白补了产品图）：判据复用**现有失败分类器**
+    （`flow_failure.classify` 的 `needs_agent` 档 ⇒ 需判断/门户类）**或**该流程显式声明的
+    窄标记（`pick.releaseReDispatch.externalTiming.patterns`，如「外部时序/尚未生成/等待平台」）
+    ⇒ 走**独立通道**：长冷却 + 独立更高上限，`planned` 记 `externalTiming=true`（⛔ **不写**
+    `release`）⇒ 既不占 `maxPerCase`、也不受其约束。
+字段缺口按 owner 分类：**运营等人工字段缺失 → need_fields（落卡等人）**；
+仅"系统"字段缺失 → 仍可派发（流程内回写）。
+
+⛔ 两条**不可动摇**的可见性纪律（2026-10-09 生产实测 P0，某发票票）：
+  ① **信息性事件不得让票消失**：角色/引擎只写说明的事件（`phase` 叙述、`wake` 唤醒、
+     `policy_apply`/`policy_new` 政策记账）**不改变票据的工作状态** ⇒ 不能当判定依据。
+     判据 = 先跳过它们，回退到最近一条**状态性**事件再套上面的规则（实现见 `read_ledger` 的 `eff`）。
+     现场：尾部 = `blocked`(15:30:11) → **`phase`(15:30:59)** ⇒ 旧代码落空 ⇒ 分诊摘要全 0、
+     勾了「发票就绪」也永远不可派发、且**不在"需人工"里** = 静默卡死。
+  ② **任何未被归入任何桶的 case 一律兜底进 needs_human**，reason 写明「分诊未归类（末条事件=…）」。
+     实现是**循环之后的对账**（`placed` 集合），不是逐分支 `if` —— 将来新增分支忘了归桶也逃不掉。
+
+用法：
+  python3 scripts/flow_triage.py --flow wenyao-invoice [--limit 5] [--json]
+  python3 scripts/flow_triage.py --flow wenyao-invoice --cases-from-dir /tmp/cases   # 离线/夹具
+退出码：0 = 已产出计划；2 = 错误
+"""
+from __future__ import annotations
+import argparse, hashlib, json, pathlib, re, subprocess, sys, time, datetime as dt
+
+HERE = pathlib.Path(__file__).resolve().parent
+REQ = HERE / 'flow-requirements.json'
+SOURCE = HERE / 'flow_source.py'
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+from flow_failure import classify        # noqa: E402  与失败回路**同一套**失败判据
+# 放行位真值判据与 apply_pick（flow_source）**同源**：飞书 checkbox 经 _flat() 变字符串，
+# 'False' 是非空字符串 ⇒ 朴素 `if` 会误判成"已放行"。两处必须一致，故直接复用。
+from flow_source import _truthy          # noqa: E402
+
+try:
+    from flow_registry import consumer_doc as _registry_doc      # P2a：base + 业务线合并（唯一真源）
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件（升级链路要能跑）
+    def _registry_doc(path=None):
+        _p = pathlib.Path(path) if path else (HERE / "flow-requirements.json")
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+DEFAULT_LEDGER = pathlib.Path(resolve_data_dir()['dir']) / 'flow-ledger.jsonl'
+
+# 人工重新放行（Rule R，2026-09-21）可重新派发的上游事件
+RELEASE_UPSTREAM = ('failed', 'blocked')
+
+# ── 放行额度重置（①，2026-10-13）──────────────────────────────────────────────
+# 事件形状：`policy_apply` + `policy=release_budget_reset`。选 policy_apply 是因为它**已在
+# INFO_EVENTS 里**（信息性事件不改变票据的工作状态 ⇒ 不会让判定依据漂移），且 flow_ledger 的
+# EVENTS 白名单本就有它（⛔ 不加事件类型，向后兼容）。
+RESET_POLICY = 'release_budget_reset'
+RESET_DETAIL = '上游数据已变 ⇒ 放行额度重置'
+# **外部时序**的内置兜底标记（`externalTiming.patterns` 未声明时用；流程声明优先）。
+# 口径：只认"**平台/门户侧还没生成**"这类**我方与运营都改不动**的措辞 —— ⛔ 不认业务缺字段
+# （缺字段必须照旧占运营放行额度，那是运营真能修的）。
+EXTERNAL_BUILTIN_PATTERNS = (r'外部时序', r'尚未生成', r'未生成', r'等待平台', r'平台尚未', r'timing gap')
+# 单元格值里这些键是**易变**的（带签名的临时 URL / 过期时间…）：每次读都可能不同 ⇒
+# 一律不进哈希（否则每轮都被判成"上游变了" ⇒ 无限重放）。飞书附件经 `_flat()` 后通常已是
+# 文件名，这里是**防御性**收口（原始 dict 形态直传时也稳）。
+_UPSTREAM_VOLATILE_KEY_HINTS = ('url', 'expire', 'thumbnail', 'token', 'sign')
+
+
+def pick_of(spec) -> dict:
+    """该流程**生效**的 `pick`（变体优先）：`flow_config` 正常时会解析到顶层；
+    解析失败（半坏机器）时退回 `source.variants.<default>.pick`（FULL 的 pick 写在那里）。"""
+    src = (spec or {}).get('source') or {}
+    pick = src.get('pick') or {}
+    if pick:
+        return pick
+    variants = src.get('variants') or {}
+    name = str(src.get('default') or '')
+    return ((variants.get(name) or {}).get('pick') or {})
+
+
+def upstream_ignore(spec) -> set:
+    """**不参与**"上游变化"判据的列名集合（唯一实现，两个通道共用）。
+
+    判据 = "流程**自己回写**的列" —— 它们变了不代表运营改了数据（否则每轮都"变了"⇒ 无限重试）。
+    「自己回写的列」按**既有口径**取，⛔ 不另立一套：
+      ① `pick.releaseReDispatch.upstreamHash.ignore`（显式声明，最优先、最可审计）；
+      ② `guards.writeFields`（流程声明的写白名单；两个发票流程 = 发票状态/发票文件/大货标签/发票错误信息）；
+      ③ `guards.errorField`（失败收口必写的那一列）；
+      ④ `source.variants.*.fields` 的值并集（与 `orchestrator._full_allowed_fields` 同一判据 ——
+         FULL 的写白名单就是这么推出来的）。
+    另外**永远**排除：放行勾本身（勾一次 ≠ 改数据；这正是 BUG 的文案形态）、票号列
+    （它变了就是**另一张票**，caseId 都不同）、`_` 前缀的合成列（`_phase`/`_record_id`… 每轮重算）。
+    """
+    src = (spec or {}).get('source') or {}
+    pick = pick_of(spec)
+    guards = (spec or {}).get('guards') or {}
+    up = (pick.get('releaseReDispatch') or {}).get('upstreamHash') or {}
+    out: set = set()
+    for name in (up.get('ignore') or []):
+        if str(name).strip():
+            out.add(str(name).strip())
+    if not out:                       # 未显式声明 ⇒ 按既有口径推（发票流程靠 writeFields 就够）
+        for name in (guards.get('writeFields') or []):
+            if str(name).strip():
+                out.add(str(name).strip())
+        if str(guards.get('errorField') or '').strip():
+            out.add(str(guards['errorField']).strip())
+        for v in (src.get('variants') or {}).values():
+            for val in ((v or {}).get('fields') or {}).values():
+                if isinstance(val, str) and val:
+                    out.add(val)
+    rel_col = str((pick.get('release') or {}).get('field')
+                  or (src.get('fields') or {}).get('ready') or '').strip()
+    if rel_col:
+        out.add(rel_col)              # 放行勾**不参与**：勾一次 ≠ 运营改了数据
+    out.add(str(src.get('ticketField') or '货件号'))
+    return out
+
+
+def external_cfg(rd: dict) -> dict:
+    """外部时序通道参数（缺省：开启 / 上限 8 / 长冷却 120 分钟）。"""
+    et = (rd or {}).get('externalTiming') or {}
+    return {'enabled': et.get('enabled', True) is not False,
+            'maxPerCase': int(et.get('maxPerCase') or 0) or 8,
+            'cooldownMin': int(et.get('cooldownMin') or 0) or 120,
+            'patterns': [str(x) for x in (et.get('patterns') or []) if str(x).strip()]}
+
+
+def external_wait_copy(cooldown_min: int, ready_field: str) -> str:
+    """**外部时序**阻塞时的**运营可见文案**（卡片 markdown 版；表字段版见发票链运行器的
+    `_label_wait_text` —— 同一句，那边按纯文本写、不加 `**`）。
+
+    两要素**缺一即判红**（回归 `scripts/tests/external-timing-ops-copy.test.py`）：
+      ① **自动再试节奏**：系统将在约 N 分钟后自动再试
+         —— N 取自声明面 `pick.releaseReDispatch.externalTiming.cooldownMin`，⛔ **不写死 120**；
+      ② **人工接管方式**：现在人工处理完**取消勾选**「<放行位>」，系统就不再自动拾取。
+    为什么必须两句都给：运营看到"需人工"时只有两种正确动作 —— 等（节奏）或现在就自己处理（接管），
+    而"取消勾选放行位"正是后者的**唯一**开关（放行位为真才进本通道，见 `release_gate`）。
+    """
+    rel = ready_field or '放行位'
+    return (f'系统将在约 {int(cooldown_min or 0)} 分钟后自动再试；'
+            f'你也可以现在人工处理（处理完**取消勾选**「{rel}」，系统就不再自动拾取）')
+
+
+def _canon_scalar(v) -> str:
+    """标量规范化：空白折叠、真/假归一、空值/None/False ⇒ `''`（`'False'` 同义）。"""
+    if v is None or v is False:
+        return ''
+    if v is True:
+        return 'true'
+    s = ' '.join(str(v).split())
+    return '' if s.lower() in ('false', 'none', 'null') else s
+
+
+def _canon_value(v):
+    """单元格值 → 稳定可比形态（规范化排序、忽略易变键；⛔ 不含任何业务解读）。"""
+    if isinstance(v, list):
+        parts = [_canon_value(x) for x in v]
+        parts = [p for p in parts if p not in ('', [], {})]
+        return sorted(parts, key=lambda x: json.dumps(x, ensure_ascii=False, sort_keys=True))
+    if isinstance(v, dict):
+        out = {}
+        for k, x in v.items():
+            kl = str(k).lower()
+            if any(h in kl for h in _UPSTREAM_VOLATILE_KEY_HINTS):
+                continue
+            out[str(k)] = _canon_value(x)
+        return out
+    return _canon_scalar(v)
+
+
+def upstream_field_hashes(fields, ignore) -> dict:
+    """上游行的**稳定哈希**（逐字段）：`{字段名: sha256(规范值)[:8]}`（纯函数）。
+
+    · 参与 = case.fields − `ignore` − `_` 前缀合成列；空值不进（"填了/清空"由**键的出现/消失**体现）；
+    · 只保存**哈希**（8 位）不保存值 ⇒ 台账里不会留业务数据，理由文案也只点字段名（⛔ 不点值）。
+    """
+    out = {}
+    for k, v in (fields or {}).items():
+        k = str(k)
+        if k.startswith('_') or k in ignore:
+            continue
+        cv = _canon_value(v)
+        if cv in ('', [], {}):
+            continue
+        blob = json.dumps(cv, ensure_ascii=False, sort_keys=True)
+        out[k] = hashlib.sha256(blob.encode('utf-8')).hexdigest()[:8]
+    return out
+
+
+def _parse_ts(v) -> float:
+    """ISO8601（`…+08:00` / `…Z`）或 epoch 数字 → epoch 秒；解析不了 ⇒ 0.0。"""
+    s = str(v or '').strip()
+    if not s:
+        return 0.0
+    try:
+        return float(s)
+    except Exception:                                     # noqa: BLE001
+        pass
+    try:
+        if s.endswith('Z'):
+            s = s[:-1] + '+00:00'
+        return dt.datetime.fromisoformat(s).timestamp()
+    except Exception:                                     # noqa: BLE001
+        return 0.0
+
+
+def upstream_changed(case, spec, snap, last_disp_ts) -> tuple:
+    """上游行相对**上次派发**是否**真的变了** → `(变化字段名列表, 判据来源)`（纯函数）。
+
+    两条判据（**有快照就用快照**，没有才退回 case 文件自带的时间戳）：
+
+      · `ledger-snapshot` —— 台账里**上次派发**（`planned`）记的逐字段哈希（`upstreamFieldHash`，
+        由 `flow_claim` 写入）与当前值比；键出现/消失/哈希不同都算变。**最准**（不依赖时间戳）。
+      · `case-provenance` —— 0.1.7 既有台账**没有**这个字段（本次改动之前派的票），退回
+        `case.provenance.<字段>.at` = 该字段**最后一次变化**的时间（`flow_case.merge_case` 只在
+        值变化时更新它），比"上次派发时间"新 ⇒ 该字段变了。
+        ⛔ **保守闸门**：case 文件比上次派发还新（`createdAt > 上次派发`，例如 case 目录被清过）
+        ⇒ 时间戳没有可信基线 ⇒ **判"没变"**（宁可不重置，也不无限重试）。
+      · 两条都拿不到 ⇒ `([], 'none')`（**缺证据 ≠ 变了**）。
+    """
+    ignore = upstream_ignore(spec)
+    cur = upstream_field_hashes((case or {}).get('fields') or {}, ignore)
+    old = (snap or {}).get('hash') if isinstance(snap, dict) else None
+    if isinstance(old, dict) and old:
+        old = {str(k): str(v) for k, v in old.items()}
+        changed = sorted([k for k in set(old) | set(cur) if old.get(k) != cur.get(k)])
+        return changed, 'ledger-snapshot'
+    prov = (case or {}).get('provenance') or {}
+    if not prov or not last_disp_ts:
+        return [], 'none'
+    created = _parse_ts((case or {}).get('createdAt'))
+    if created and created > float(last_disp_ts):
+        return [], 'none'                       # case 比上次派发还新 ⇒ 无可信基线
+    changed = []
+    for k in cur:
+        at = _parse_ts((prov.get(k) or {}).get('at'))
+        if at and at > float(last_disp_ts):
+            changed.append(k)
+    return (sorted(changed), 'case-provenance') if changed else ([], 'none')
+
+
+def is_external_timing(text, cfg) -> tuple:
+    """这段失败文本是不是**外部时序**类（门户/平台侧还没生成）→ `(是否, 判据说明)`。
+
+    ⛔ **不新造分类**：先看流程声明的窄标记（`externalTiming.patterns`，缺省用内置兜底），
+    再看**现有分类器** `flow_failure.classify` 的结论（`needs_agent` = 需判断/门户类）。
+    空白文本 ⇒ **不是**外部类（无从判定 ⇒ 照旧走 Rule R，避免把"没写原因"当成平台问题）。
+    """
+    t = ' '.join(str(text or '').split())
+    if not t:
+        return False, ''
+    pats = [str(x) for x in ((cfg or {}).get('patterns') or []) if str(x).strip()] \
+        or list(EXTERNAL_BUILTIN_PATTERNS)
+    for p in pats:
+        try:
+            if re.search(p, t, re.I):
+                return True, f'外部时序标记 /{p}/'
+        except re.error:
+            continue
+    try:
+        kind = str((classify(t) or {}).get('kind') or '')
+    except Exception:                                     # noqa: BLE001
+        kind = ''
+    if kind == 'needs_agent':
+        return True, '既有分类器判定 needs_agent（需判断/门户类）'
+    return False, ''
+
+
+def err_text(ev) -> str:
+    """取一条失败/阻塞事件里的**失败原因**文本（`reason` → `error`；与 `flow_failure.reasons()` 同源口径）。
+
+    ⛔ **刻意不读 `detail`**：它是通用的过程叙述（阶段说明/退出码/角色补白），不是失败原因 ——
+    实测（既有夹具 `A-BLOCK-PHASE` 的 `blocked{detail:"两卡发送失败"}`）把 detail 当原因是
+    **误判成外部时序**并把票送进独立通道。原因只认这两个字段；两者都空 ⇒ 无从判定 ⇒ 走 Rule R。
+    """
+    if not isinstance(ev, dict):
+        return ''
+    for k in ('reason', 'error'):
+        s = ' '.join(str(ev.get(k) or '').split())
+        if s:
+            return s
+    return ''
+
+
+def write_reset(ledger: str, cid: str, changed, basis: str) -> bool:
+    """写一条**信息性** `policy_apply`（`policy=release_budget_reset`）—— 计数基线归零。
+
+    ⛔ 它不是 `release`：不占任何额度、不改变票据状态（`INFO_EVENTS` 已含 `policy_apply`）。
+    ⛔ 只记**字段名**（`changed`），绝不记字段值。
+    写失败 ⇒ 返回 False（**fail-closed**：调用方不派发 —— 否则计数不归零 ⇒ 每轮都重置 ⇒ 无限重放）。
+    """
+    if not ledger:
+        return False
+    try:
+        import flow_ledger as _L                             # noqa: PLC0415  同目录模块
+        _L.append(pathlib.Path(ledger), {
+            'ts': int(time.time()), 'caseId': cid, 'event': 'policy_apply',
+            'policy': RESET_POLICY, 'by': 'flow-triage',
+            'detail': f"{RESET_DETAIL}（变化字段：{'、'.join(changed)}；判据：{basis}）"[:300],
+        })
+        return True
+    except Exception as exc:                                 # noqa: BLE001
+        print(f'  ⚠ 放行额度重置事件写入失败（{exc}）⇒ 本轮不派发该票（计数未归零时重派会无限重放）',
+              file=sys.stderr)
+        return False
+
+# ── 有效末条事件（2026-10-09 P0）──────────────────────────────────────────────
+# **信息性事件**：只带说明，不改变票据的工作状态 ⇒ 判定时必须跳过、回退到最近一条状态性事件。
+# 逐条理由（都能在 `flow_ledger.py#EVENTS` 里对上）：
+#   phase        角色写的阶段叙述（"两卡发送失败"/"掌舵-汇报"…）——**本次 P0 的元凶**
+#   wake         引擎因失败唤醒角色（`flow_failure` 的交接动作）——票的状态没变
+#   policy_apply 依政策执行（`flow_policy.py`）——政策记账，不是票据进度
+#   policy_new   提议新政策（同上）
+# ⛔ 刻意**不**收进来的（它们是状态性事件，必须参与判定）：
+#   retry（Rule R 认 `by=flow_retry` 的那条）、requeued（停滞回收）、failed_ack（见 IDLE_EVENTS）
+INFO_EVENTS = ('phase', 'wake', 'policy_apply', 'policy_new')
+# **已确认事件**：人工确认/消案（`flow_failure.HANDLED_EVENTS` 同口径）⇒ 本轮**不动**，
+# 且**不参与回退**（否则消案的票会退回它前面的 `failed`，每轮复活成 needs_human）。
+IDLE_EVENTS = ('failed_ack',)
+
+
+def load_flow(flow_id):
+    doc = _registry_doc()
+    # P2a：旧 id 经别名解析（`full` → `<vertical>.full`），否则业务线流程全查不到
+    canonical = (doc.get('aliases') or {}).get(flow_id, flow_id)
+    spec = (doc.get('flows') or {}).get(canonical)
+    # 字段要求与**字段名映射**都按当前变体取（flow_config 是唯一解析点）：
+    #   · required 决定缺口算谁的（影响 need_fields 分桶）；
+    #   · source.fields 里的 store 名字 —— 2026-09-18 修：变体流程（full 的 lip/legacy）
+    #     把字段映射写在 `source.variants.<名>.fields`，顶层 `source.fields` 是 null
+    #     ⇒ 这里以前恒取到空字符串 ⇒ 每张票的 store 都是 ''。
+    #     后果（实测 15:34:15 那轮）：flow_claim 按"虚拟空店"计同店并发 ⇒ perStore=1 变成
+    #     **全局一次只跑一票**，跨店并行与 concurrency.max 全部失效（可派发 1 却认领 0 张）。
+    try:
+        import flow_config as _fc
+        _cfg = _fc.load_config(flow_id, strict=False)   # P2a：不要传 base 路径（会退化成单文件）
+        if _cfg.get('required'):
+            spec = {**spec, 'required': _cfg['required']}
+        if _cfg.get('source'):
+            spec = {**spec, 'source': {**(spec.get('source') or {}), **(_cfg.get('source') or {})}}
+        # `guards` 也要合并：写白名单（`writeFields`/`errorField`）由 **capability** 提供
+        # （业务线 flows.json 里可能没写）—— ① 的"忽略自身回写列"判据要读它（见 upstream_ignore）。
+        if _cfg.get('guards'):
+            spec = {**spec, 'guards': {**(spec.get('guards') or {}), **(_cfg.get('guards') or {})}}
+    except Exception:
+        pass
+    if not spec:
+        print(f'未知流程: {flow_id}', file=sys.stderr); sys.exit(2)
+    return spec
+
+
+def owners(spec):
+    """字段 → 责任说明（**仅供展示**）。机器判据见 roles()。"""
+    out = {}
+    for r in spec.get('required') or []:
+        out.setdefault(r.get('name'), r.get('owner') or '')
+    return out
+
+
+def roles(spec):
+    """字段 → 机器判据 role（input/state/output/derived）；缺 role 时按旧 owner 规则兜底。
+
+    2026-09-20（迭代1-步骤2）：此前"缺了要不要落卡等人"用的是 `'系统' not in owner`
+    —— 中文自由文本当判据，改名即静默翻转。现在只认显式 role：
+      · input  ⇒ 缺了落卡等人
+      · state/output/derived ⇒ 不落卡等人（state 由流程或运营在运行中推进）
+    """
+    out = {}
+    for r in spec.get('required') or []:
+        role = str(r.get('role') or '')
+        if not role:                       # 兜底（flow_config 会拒绝缺 role 的注册表）
+            role = 'output' if '系统' in str(r.get('owner') or '') else 'input'
+        out.setdefault(r.get('name'), role)
+    return out
+
+
+def release_gate(spec, case):
+    """人工重新放行（Rule R，2026-09-21）的三个量：配置 / 放行字段名 / 是否已放行。
+
+    放行字段与 apply_pick **同源**（`pick.release.field` → `source.fields.ready`），
+    值走 `flow_source._truthy`（`'False'`/`'否'`/空 ⇒ 未放行）。
+    """
+    src = spec.get('source') or {}
+    pick = src.get('pick') or {}
+    rd = pick.get('releaseReDispatch') or {}
+    rel_col = ((pick.get('release') or {}).get('field')
+               or (src.get('fields') or {}).get('ready') or '')
+    val = (case.get('fields') or {}).get(rel_col) if rel_col else None
+    return rd, rel_col, _truthy(val)
+
+
+def dispatch_rec(rec: dict, cur_hash, **extra) -> dict:
+    """派发记录 = 判定记录 + 派发专属字段 + **当前上游逐字段哈希**。
+
+    为什么每一次派发都要带哈希：① 的判据是"上游相对**上次派发**变了吗" ⇒ 台账里必须有
+    "上次派发时上游长什么样"。`flow_claim.planned_record` 会把它抄进 `planned` 事件
+    （`upstreamFieldHash`），下一次分诊才有基线可比；⛔ 不记字段值，只记 8 位哈希。
+    """
+    out = {**rec, **extra}
+    if cur_hash:
+        out['upstreamFieldHash'] = cur_hash
+    return out
+
+
+def read_ledger(path: pathlib.Path) -> dict:
+    """读台账 → {'last': {caseId: 末条事件}, 'eff': {caseId: 有效末条事件}, 'attempts': {...}, …}。
+
+    2026-09-18（实测 77445732 续跑成功后的乱序记账）：角色的 `dispatched` 事件**记晚了** ——
+    实际链路是 `retry`(23:23) → 干完 `done`(23:30) → 才补记 `dispatched`(23:31)。
+    若只看"最后一行"，这条**已经跑完**的票会被算成"在飞"，30 分钟后变"停滞"，
+    在工作台上显示成一条幽灵在飞票（正是用户此前抱怨过的"在飞不准"）。
+    ⇒ 已 `done` 的 case，之后补记的 `dispatched` **一律忽略**（done 是终态；票据状态
+    也会变成「已完成」而不进候选，所以不存在"done 之后还能再派发"的合法场景）。
+
+    2026-09-21（Rule R）：额外统计**人工放行重跑**的次数与最近时间 ——
+    判据是认领记录 `planned` 带 `release=true`（flow_claim 写，仅 Rule R 候选带）。
+    用 planned 而不是"失败次数"：上限约束的是**人工放行这条通道被用了几次**，
+    与流程内部重试（`auto_fail_retry`/`retry`）无关。
+
+    2026-10-09（P0，生产实测的某发票票：`blocked` 之后角色补了一条 `phase`）：新增两套映射，**判定一律用 `eff`**：
+      · `last[cid]` = 台账末条事件（**原样**，含信息性事件）—— 用于诊断与 reason 文案；
+      · `eff[cid]`  = **有效末条事件** = 最后一条**非** `INFO_EVENTS` 的事件。
+    只留末条会让"blocked 之后角色补一句 phase"的票从所有桶消失（分诊摘要全 0 ⇒ 静默卡死）。
+    `IDLE_EVENTS`（`failed_ack`）**算状态性**：人工已确认/消案的票**不许**退回它前面的 `failed`
+    每轮复活（那是把"消案"变成"没消案"）。
+
+    2026-10-13（放行额度与上游变化）：
+      · **额度从"上次重置"起算** —— 台账里的 `policy_apply{policy=release_budget_reset}`
+        （分诊在上游数据变化时写，见 `write_reset`）把该票的放行/外部两条通道计数**归零**。
+        计数按**行序**（事件在文件里的先后）判定，与 `ts` 同秒也不打架。
+      · 新增 `externalRetry`/`externalTs`（`planned{externalTiming=true}` 的计数，② 独立通道）；
+      · 新增 `dispatchTs`（**任何** `planned` 的最近时间 = 外部通道的长冷却基线）与
+        `upstreamSnap`（最近一次派发记下的逐字段哈希 = ① 的"上次派发快照"）。
+    `releaseRetry`/`releaseTs` 的**键名与语义不变**（只是把基线挪到最近一次重置之后）。
+    """
+    last, eff, attempts, rel_cnt, rel_ts = {}, {}, {}, {}, {}
+    ext_cnt, ext_ts, disp_ts, upstream_snap, reset_idx = {}, {}, {}, {}, {}
+    rel_marks: dict = {}          # cid → [(行号, ts)]：`planned{release=true}`
+    ext_marks: dict = {}          # cid → [(行号, ts)]：`planned{externalTiming=true}`
+    disp_marks: dict = {}         # cid → [(行号, ts)]：任何 `planned`
+    done_cases: set = set()
+    idx = 0
+    if not path.exists():
+        return {'last': last, 'eff': eff, 'attempts': attempts,
+                'releaseRetry': rel_cnt, 'releaseTs': rel_ts,
+                'externalRetry': ext_cnt, 'externalTs': ext_ts,
+                'dispatchTs': disp_ts, 'upstreamSnap': upstream_snap}
+    for line in path.read_text(encoding='utf-8').splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        idx += 1
+        try:
+            e = json.loads(line)
+        except Exception:
+            continue
+        cid = e.get('caseId')
+        if not cid:
+            continue
+        # 放行额度重置（信息性政策记账）：只当**计数基线**，⛔ 不当票据状态（故仍在 INFO_EVENTS 里）
+        if e.get('event') == 'policy_apply' and str(e.get('policy') or '') == RESET_POLICY:
+            reset_idx[cid] = idx
+        if e.get('event') == 'planned':
+            disp_marks.setdefault(cid, []).append((idx, float(e.get('ts') or 0)))
+            if e.get('release'):
+                rel_marks.setdefault(cid, []).append((idx, float(e.get('ts') or 0)))
+            if e.get('externalTiming'):
+                ext_marks.setdefault(cid, []).append((idx, float(e.get('ts') or 0)))
+            _h = e.get('upstreamFieldHash')
+            if isinstance(_h, dict) and _h:
+                upstream_snap[cid] = {'ts': float(e.get('ts') or 0),
+                                      'hash': {str(k): str(v) for k, v in _h.items()}}
+            else:
+                # 本次派发没记哈希（老版本写的 planned / 非 Rule R 流程）⇒ **清掉**上一次的快照：
+                # 快照必须恒等于"**上一次派发**时上游的样子"，否则判据窗口会算错（比上次派发更早）。
+                upstream_snap.pop(cid, None)
+        if e.get('event') == 'done':
+            done_cases.add(cid)
+        # 已经 done 过、之后才补记的 dispatched ⇒ 迟到的记账，不作为"在飞"依据
+        if e.get('event') == 'dispatched' and cid in done_cases:
+            continue
+        last[cid] = e
+        if str(e.get('event') or '') not in INFO_EVENTS:
+            eff[cid] = e                          # 信息性事件不覆盖"有效末条"
+        if e.get('event') == 'failed':
+            attempts[cid] = max(attempts.get(cid, 0), int(e.get('attempt') or 1))
+    for cid, marks in rel_marks.items():
+        after = [t for i, t in marks if i > reset_idx.get(cid, 0)]
+        rel_cnt[cid] = len(after)
+        rel_ts[cid] = max(after) if after else 0.0
+    for cid, marks in ext_marks.items():
+        after = [t for i, t in marks if i > reset_idx.get(cid, 0)]
+        ext_cnt[cid] = len(after)
+        ext_ts[cid] = max(after) if after else 0.0
+    for cid, marks in disp_marks.items():
+        after = [t for i, t in marks if i > reset_idx.get(cid, 0)]
+        if after:
+            disp_ts[cid] = max(after)
+    return {'last': last, 'eff': eff, 'attempts': attempts,
+            'releaseRetry': rel_cnt, 'releaseTs': rel_ts,
+            'externalRetry': ext_cnt, 'externalTs': ext_ts,
+            'dispatchTs': disp_ts, 'upstreamSnap': upstream_snap}
+
+
+SOURCE_NOTES: list = []          # 源清单自带的"为什么没有待处理单元"（cases-json 用）
+
+
+def collect_cases(args, spec) -> list[dict]:
+    """cases-from-dir（离线）优先；否则调 flow_source 拉源。"""
+    if args.cases_from_dir:
+        out = []
+        for f in sorted(pathlib.Path(args.cases_from_dir).glob('*.json')):
+            out.append(json.loads(f.read_text(encoding='utf-8')))
+        return out
+    # 源类型由**流程声明**决定（P2：日报这类"单元不在表里"的流程用 cases-json 批量清单）；
+    # 缺省 feishu-base，向后兼容既有流程。
+    src = (spec or {}).get('source') or {}
+    kind = str(src.get('kind') or 'feishu-base')
+    cmd = [sys.executable, str(SOURCE), '--flow', args.flow, '--source', kind, '--json']
+    if kind == 'cases-json':
+        cmd += ['--from-json', str(src.get('file') or '-')]
+        # 夹具/排障：显式要求"按现状读清单"（不跑再生成、不查过期）。
+        # 生产路径**不要**加它 —— 2026-09-20 的静默停摆正是因为该跑没跑。
+        if getattr(args, 'no_regenerate', False):
+            cmd += ['--no-regenerate']
+    if args.limit:
+        cmd += ['--limit', str(args.limit)]
+    if args.out_dir:
+        cmd += ['--out-dir', args.out_dir]
+    p = subprocess.run(cmd, capture_output=True, text=True)
+    if not p.stdout.strip().startswith('{'):
+        print(f'flow_source 失败：{(p.stderr or p.stdout).strip()[:300]}', file=sys.stderr)
+        sys.exit(2)
+    plan = json.loads(p.stdout)
+    # 源清单的说明（"已推送/未到点/窗口已过"）——没有它，空清单只能显示成
+    # "无票可认领"（2026-09-18 用户实测：日报因此静默停摆一整天无人察觉）
+    SOURCE_NOTES.clear()
+    SOURCE_NOTES.extend([str(x) for x in (plan.get('notes') or [])][:6])
+    # 把 case 文件读回来（带 fields/provenance），与 gap 结果合并
+    out = []
+    for item in plan.get('cases') or []:
+        case_file = pathlib.Path(args.out_dir or (pathlib.Path(resolve_data_dir()['dir']) / 'flow-cases')) / f"{args.flow}__{item['ticket']}.json"
+        case = json.loads(case_file.read_text(encoding='utf-8')) if case_file.exists() else {'ticketKey': item['ticket'], 'fields': {}}
+        case['_missing'] = item.get('missing') or []
+        case['_gapError'] = item.get('gapError')   # 缺口检查失败 ⇒ 绝不能当作"无缺口"
+        out.append(case)
+    return out
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='流程分诊：产出本轮派发计划（只读）')
+    ap.add_argument('--flow', required=True)
+    ap.add_argument('--limit', type=int, help='本轮最多处理多少行（源读取上限）')
+    ap.add_argument('--no-regenerate', action='store_true',
+                    help='不跑 source.regenerate、不查过期（仅夹具/排障）')
+    ap.add_argument('--cases-from-dir', help='离线：直接读该目录下的 case 文件（跳过源读取）')
+    ap.add_argument('--out-dir', help='case 落盘目录（默认 ~/.dsh/argent/flow-cases）')
+    ap.add_argument('--no-ledger-write', dest='no_ledger_write', action='store_true',
+                    help='只读诊断：不写「放行额度重置」事件（仍照常给出计划）—— \n'
+                         '给只读巡检用（customer-preflight），生产链路**不要**加')
+    ap.add_argument('--ledger', default=str(DEFAULT_LEDGER))
+    ap.add_argument('--inflight-min', type=int, default=30, help='在飞窗口（分钟），超过算停滞')
+    ap.add_argument('--max-attempts', type=int, default=2, help='失败重试上限')
+    ap.add_argument('--json', action='store_true')
+    args = ap.parse_args(argv)
+
+    spec = load_flow(args.flow)
+    own = owners(spec)
+    rl = roles(spec)
+    led = read_ledger(pathlib.Path(args.ledger))
+    now = time.time()
+    b = {'to_dispatch': [], 'need_fields': [], 'await_release': [], 'in_flight': [], 'stale': [], 'retry': [], 'needs_human': []}
+
+    recs: dict = {}          # cid → rec（循环后兜底对账用；⛔ 不参与判定）
+    eff_ev: dict = {}        # cid → 有效末条事件名（兜底 reason 用）
+    idle: set = set()        # cid → **有意**本轮不动（done / failed_ack），兜底对账不得误报
+    for case in collect_cases(args, spec):
+        cid = case.get('caseId') or f"{args.flow}__{case.get('ticketKey')}"
+        # 2026-09-15 加固（文鳐实跑发现）：缺口检查**失败**时绝不能当作"无缺口"——
+        # 实测：安装克隆缺 ml_schema_check.py ⇒ 子进程失败 ⇒ missing=[] ⇒ 误判可派发。
+        if case.get('_gapError'):
+            b['needs_human'].append({'caseId': cid, 'ticket': case.get('ticketKey'),
+                                     'reason': '缺口检查失败：' + str(case.get('_gapError'))[:120]})
+            continue
+        missing = case.get('_missing') or []
+        # 人工字段缺失 ⇒ 必须等人（系统字段缺失不阻塞派发）
+        # 机器判据＝role（不再是 owner 的中文子串）：只有 input 类缺口才等人
+        human_missing = [m for m in missing if rl.get(m, 'input') == 'input']
+        # ── 有效末条事件（2026-10-09 P0）──────────────────────────────────────
+        # `raw_last` = 台账末条（含 `phase` 这类信息性事件，**只用于诊断/文案**）；
+        # `last`     = **有效**末条（跳过 INFO_EVENTS）—— 下面所有判定一律用它。
+        raw_last = led['last'].get(cid)
+        last = led['eff'].get(cid)
+        tail = str(raw_last.get('event') or '') if (raw_last is not None and raw_last is not last) else ''
+        ev_now = str(last.get('event') or '') if last else ''
+        recs[cid] = None            # 占位：rec 在下面建好后覆盖（兜底对账要保证"处理过"）
+        eff_ev[cid] = ev_now
+        # 2026-09-17（用户口径 F5「triage 即识别层」）：case 带 `_phase`
+        #   identify      = 状态为空的新行 ⇒ 派发去**识别**（校验授权/必填 → 写「待执行」或「跳过」+备注）
+        #   execute       = 已识别且已放行 ⇒ 正常作业
+        #   await_release = 已识别但运营尚未勾「就绪」⇒ **只报数、不派发、不落卡**（等人放行）
+        phase = str((case.get('fields') or {}).get('_phase') or '')
+        rec = {'caseId': cid, 'ticket': case.get('ticketKey'), 'missing': missing, 'phase': phase,
+               'route': (case.get('fields') or {}).get((spec.get('routing') or {}).get('routeBy') or ''),
+               # P5（2026-09-17）：带上 store —— claim 按 (flow, store) 限并发（同店串行、跨店并行）
+               'store': (case.get('fields') or {}).get(
+                   ((spec.get('source') or {}).get('fields') or {}).get('store') or '')}
+        if tail:
+            rec['tail'] = tail          # 末条是信息性事件（已回退到有效末条判定）——留在证据里
+        recs[cid] = rec
+
+        if human_missing and not (last and last.get('event') in ('dispatched',)):
+            rec['humanMissing'] = human_missing
+            b['need_fields'].append(rec); continue
+        # 2026-09-17：**缺字段优先于"待放行"** —— 比如 FULL 的 91 行「状态=待执行但店铺为空」，
+        # 先报"缺店铺（等人补）"才有意义；否则会被 await_release 吞掉，看着像"只等放行"。
+        if phase == 'await_release':
+            b['await_release'].append({**rec, 'reason': '已识别、等运营勾「就绪」放行'})
+            continue
+        # ── 人工重新放行（Rule R，2026-09-21）──────────────────────────────────
+        # 用户口径（逐字）：「如果是运营自行根据提示在表格数据上补充好了，并且打勾就绪，
+        # 那么 Argent 会自行重跑吗？」—— 此前答案是**不会**：下面 `failed`/`blocked` 两个
+        # 分支都不派，`retry` 桶又只有 flow_retry.py 一个消费者，于是失败过的行**永远**
+        # 停在原地（2026-09-21 实测：写表重置 + 勾就绪后两轮「可派发 0」）。
+        # 判据（全部确定性，无时间猜测）：① 上游事件 ∈ {failed, blocked}，或
+        # `flow_retry.py` 写的 retry（`by=flow_retry`；**角色**写的 retry 归角色自己派发，
+        # 引擎不抢 ⇒ 避免与 ruling/dispatch 双派）；② 放行位为真 —— 失败收口一律写
+        # 就绪=false（`_fail_record` / SKU 未找到 / `_hand_to_ops_close`），所以为真
+        # 只可能是**人工重新勾的**；③ 未达 maxPerCase；④ 距上次人工放行重跑已过冷却。
+        rd, rel_col, released = release_gate(spec, case)
+        # 上游逐字段哈希：只要该流程开了 Rule R 通道就算一次（派发时随 `planned` 落台账 ⇒
+        # 下一轮的"上次派发快照"；见 dispatch_rec）。
+        cur_hash = (upstream_field_hashes(case.get('fields') or {}, upstream_ignore(spec))
+                    if rd.get('enabled') else None)
+        if last and rd.get('enabled'):
+            ev0, by0 = ev_now, str(last.get('by') or '')
+            upstream = ev0 in RELEASE_UPSTREAM or (ev0 == 'retry' and by0 == 'flow_retry')
+            if upstream and released:
+                err_txt = err_text(last)
+                et = external_cfg(rd)
+                is_ext, ext_why = is_external_timing(err_txt, et) if et['enabled'] else (False, '')
+                # ── ② 外部时序类 ⇒ **独立通道**（⛔ 不写 release、不占运营放行额度）────────
+                # 现场：`门户搜索订单 … 命中 0 行（仅缺大货标签）…外部时序缺口` 被判成
+                # "缺数据 ⇒ 运营该补"，运营于是白补了产品图 —— 这类**运营改不动**，
+                # 该等平台生成，故给它自己的长冷却 + 更高上限，并**不吃** Rule R 的 3 次额度。
+                if is_ext:
+                    ue = int(led['externalRetry'].get(cid, 0))
+                    cap_e, cool_e = et['maxPerCase'], et['cooldownMin']
+                    last_disp = float(led['dispatchTs'].get(cid) or 0)
+                    if ue >= cap_e:
+                        b['needs_human'].append({**rec, 'kind': 'external_capped', 'attempt': ue,
+                                                 'reason': f"外部时序类（{ext_why}）已达外部通道上限"
+                                                           f"（{ue}/{cap_e}）⇒ 交人核查门户/平台侧是否已生成"
+                                                           f"（⛔ 不是运营数据问题：**取消勾选**「{rel_col}」即不再自动拾取）"})
+                        continue
+                    if last_disp and (now - last_disp) < cool_e * 60:
+                        left = int((cool_e * 60 - (now - last_disp) + 59) // 60)
+                        b['needs_human'].append({**rec, 'kind': 'external_cooldown',
+                                                 'reason': f"外部时序类（{ext_why}）⇒ "
+                                                           f"{external_wait_copy(cool_e, rel_col)}"
+                                                           f"｜本轮距上次派发还需约 {left} 分钟"
+                                                           f"（长冷却 {cool_e} 分钟，**不占**运营放行额度）"})
+                        continue
+                    b['to_dispatch'].append(dispatch_rec(
+                        rec, cur_hash, kind='external', externalRetry=ue + 1,
+                        externalMax=cap_e, externalCooldownMin=cool_e, externalWhy=ext_why,
+                        reason=f"外部时序类（{ext_why}）⇒ 走**独立通道**重派"
+                               f"（第 {ue + 1}/{cap_e} 次；冷却 {cool_e} 分钟；"
+                               f"⛔ 不占运营放行额度、也无需运营再勾「{rel_col}」）"))
+                    continue
+                # ── ① 上游数据变化 ⇒ 放行额度重置（⛔ 不是"又勾了一次就绪"）────────────
+                # 现场（某发票票 `79406731`）：3 次放行重跑用满后再也不会被拾取，即便运营
+                # 已经补好数据。口径：额度约束的是"**同一份上游数据**被反复放行"。
+                used = int(led['releaseRetry'].get(cid, 0))
+                cap = int(rd.get('maxPerCase') or 0) or 3
+                cool = int(rd.get('cooldownMin') or 0)
+                last_rel = float(led['releaseTs'].get(cid) or 0)
+                cooling = bool(last_rel and cool and (now - last_rel) < cool * 60)
+                if used >= cap or cooling:
+                    changed, basis = upstream_changed(case, spec, led['upstreamSnap'].get(cid),
+                                                      led['dispatchTs'].get(cid))
+                    if changed:
+                        if not args.no_ledger_write and not write_reset(args.ledger, cid, changed, basis):
+                            b['needs_human'].append({**rec, 'kind': 'release_reset_failed',
+                                                     'attempt': used,
+                                                     'reason': f'上游数据已变（变化字段：{"、".join(changed)}）'
+                                                               f'但**额度重置事件写不进台账** ⇒ 本轮不派发'
+                                                               f'（没有归零就重派会变成无限重放）：请查台账可写性'})
+                            continue
+                        b['to_dispatch'].append(dispatch_rec(
+                            rec, cur_hash, kind='release', releaseRetry=1, upstreamReset=True,
+                            changedFields=changed, upstreamHashBasis=basis,
+                            reason=f"上游数据已变（变化字段：{'、'.join(changed)}；"
+                                   f"判据：{basis}）⇒ 放行额度重置，重新派发（第 1/{cap} 次）"))
+                        continue
+                if used >= cap:
+                    b['needs_human'].append({**rec, 'kind': 'release_capped', 'attempt': used,
+                                             'reason': f'人工放行重跑已达上限（{used}/{cap}）且上游数据'
+                                                       f'自上次派发**未变** ⇒ 交人：先查为什么每次都失败；'
+                                                       f'再勾「{rel_col}」不会重跑，'
+                                                       f'**改好上游数据（本流程读取的任一字段）后额度自动重置**'})
+                    continue
+                if cooling:
+                    left = int((cool * 60 - (now - last_rel) + 59) // 60)
+                    b['needs_human'].append({**rec, 'kind': 'release_cooldown',
+                                             'reason': f'人工放行重跑冷却中（还需约 {left} 分钟）'})
+                    continue
+                b['to_dispatch'].append(dispatch_rec(
+                    rec, cur_hash, kind='release', releaseRetry=used + 1,
+                    reason=f'运营人工放行（{rel_col}=true）⇒ 允许重新派发'
+                           f'（人工放行第 {used + 1}/{cap} 次）'))
+                continue
+        if raw_last is None:
+            b['to_dispatch'].append(dispatch_rec(rec, cur_hash)); continue   # 台账里**一条事件都没有** ⇒ 新行
+        if last is None:
+            # 只有信息性事件、没有任何状态事件（2026-10-09）：**不能**当新行派发 ——
+            # `phase` 说明有人在动这张票（而它没走 `planned` 认领）⇒ 盲派即可能双跑。
+            # 可见优于静默 ⇒ 交人；也绝不静默消失。
+            b['needs_human'].append({**rec, 'kind': 'info_only',
+                                     'reason': f"台账只有信息性事件（末条 {tail or 'phase'}），"
+                                               f"没有任何状态事件 ⇒ 无法判定是否在跑（⛔ 不自动重派以免双跑）"
+                                               f"：请人工确认这张票该派发、该等还是该作废"})
+            continue
+        # 停滞回收（2026-09-23）：flow_stale 写了 requeued ⇒ 这张票重新可派发。
+        # 没有这条规则时，停滞票**永远不会**回到 to_dispatch（claim 只取 to_dispatch）⇒
+        # 环境故障留下的票只能靠人发现（实测：可派发 6 却连续 4 轮无票可认领）。
+        if ev_now == 'requeued':
+            b['to_dispatch'].append(dispatch_rec(rec, cur_hash, kind='stale-reclaim')); continue
+        ev, ts = ev_now, float(last.get('ts') or 0)
+        age_min = (now - ts) / 60 if ts else 1e9
+        if ev == 'planned':
+            # 2026-09-15：**认领（planned）= 在飞**（带租约）—— 防"唤起后、派发前"的重复唤起。
+            lease_until = float(last.get('leaseUntil') or 0)
+            if lease_until and now > lease_until:
+                b['stale'].append({**rec, 'reason': '认领租约到期未派发（可回收重派）'})
+            else:
+                b['in_flight'].append({**rec, 'planned': True,
+                                       'leaseMinLeft': round(max(0.0, (lease_until - now) / 60), 1) if lease_until else None})
+            continue
+        if ev == 'dispatched':
+            (b['in_flight'] if age_min < args.inflight_min else b['stale']).append({**rec, 'ageMin': round(age_min, 1)})
+        elif ev == 'failed':
+            att = led['attempts'].get(cid, 1)
+            # P3.6（2026-09-17 实测不一致）：只看 attempt 次数会把"缺数据 / 选错行"的票判成**可重试**
+            # ⇒ 派下去必然再失败（白跑一轮 + 白烧一个 subagent 轮次）。
+            # 改为问一次**错误分类器**（与失败回路同一套判据）：
+            #   retryable（网络/限流，未到上限） ⇒ retry（允许重派）
+            #   其余（needs_human 缺数据/选错行、needs_agent 需判断） ⇒ needs_human（**不许自动派发**）
+            err_txt = str(last.get('error') or '').strip()
+            if err_txt:
+                try:
+                    kind = classify(err_txt, att, args.max_attempts)['kind']
+                except Exception:
+                    kind = 'retryable' if att < args.max_attempts else 'needs_agent'
+            else:
+                # 没有错误文本 = 无从判断原因 ⇒ 沿用 attempt 规则（兼容历史数据/简化夹具）
+                kind = 'retryable' if att < args.max_attempts else 'needs_agent'
+            if kind == 'retryable' and att < args.max_attempts:
+                b['retry'].append({**rec, 'attempt': att, 'kind': kind})
+            else:
+                b['needs_human'].append({**rec, 'attempt': att, 'kind': kind,
+                                         'reason': f'分类器判定 {kind}（缺数据/需人/需判断 ⇒ 不自动重派）'})
+        elif ev in ('done',) or ev in IDLE_EVENTS:
+            idle.add(cid)   # 已完成 / 人工已确认（消案）⇒ 本轮不动（**有意**不进任何桶，非静默漏判）
+        elif ev == 'blocked':
+            # 2026-10-09（与 P0 同族的生产实测）：blocked = **等人工/运营**，旧代码 `pass`
+            # ⇒ 票从分诊摘要里彻底消失（摘要「需人工 0」而票确实卡着）。现在**可见**。
+            hint = (f"；补齐数据后勾「{rel_col}」即自动重跑（无需通知运维）"
+                    if (rd.get('enabled') and rel_col) else "；该流程未开「人工放行重跑」⇒ 请人工裁定")
+            b['needs_human'].append({**rec, 'kind': 'blocked',
+                                     'reason': f"台账末条 blocked（= 等人工/运营处置）"
+                                               f"{'（其后只有信息性事件 ' + tail + '）' if tail else ''}{hint}"})
+        else:
+            # 状态性事件但**没有对应分支**（未知事件类型 / 将来新增的事件）—— 到不了这里也没关系：
+            # 循环后的对账兜底会把"处理过、却没进任何桶"的 case 收进 needs_human。
+            pass
+    # ── 兜底对账（2026-10-09 P0，**结构上**不可能漏）────────────────────────────
+    # 判据 = "处理过的 case" − "已进桶的 case"；**不依赖**上面任何分支写了 `continue`/`append`。
+    # ⇒ 将来新增事件类型/新增分支忘了归桶，票也只会**可见地**落进 needs_human，绝不静默消失。
+    placed = {str(r.get('caseId')) for v in b.values() for r in v}
+    unclassified = []
+    for cid, rec in recs.items():
+        if cid in placed or cid in idle or not isinstance(rec, dict):
+            continue
+        unclassified.append(cid)
+        raw_ev = str((led['last'].get(cid) or {}).get('event') or '无')
+        eff = str(eff_ev.get(cid) or '无')
+        why = f"分诊未归类（末条事件={raw_ev}" + (f"，有效末条={eff}" if eff != raw_ev else "") + "）"
+        b['needs_human'].append({**rec, 'kind': 'unclassified',
+                                 'reason': f"{why} ⇒ 请人工确认这张票该派发、等人还是作废（可见优于静默）"})
+    summary = {k: len(v) for k, v in b.items()}
+    # 人工放行重跑在日志里**单独报数**：运维看一行日志就能判断"勾了就绪到底有没有用"
+    rel_n = len([r for r in b['to_dispatch'] if str(r.get('kind') or '') == 'release'])
+    # 「上游数据变化 ⇒ 额度重置」与「外部时序独立通道」也**单独报数**（③：机制与文案一致，
+    # 运维一眼能看出"运营改了数据到底有没有生效""这张票是不是平台侧还没生成"）。
+    reset_n = len([r for r in b['to_dispatch'] if r.get('upstreamReset')])
+    ext_n = len([r for r in b['to_dispatch'] if str(r.get('kind') or '') == 'external'])
+    # 信息性事件回退数也单独报数：≥1 说明"末条是 phase/wake"这类票本来会**静默消失**
+    info_n = len([1 for r in recs.values() if isinstance(r, dict) and r.get('tail')])
+    if args.json:
+        print(json.dumps({'flow': args.flow, 'summary': summary, 'plan': b,
+                          'releaseRetry': rel_n, 'releaseReset': reset_n, 'externalReDispatch': ext_n,
+                          'infoFallback': info_n,
+                          'unclassified': sorted(unclassified), 'notes': SOURCE_NOTES},
+                         ensure_ascii=False, indent=2))
+    else:
+        print(f"  流程 {args.flow}｜本轮：可派发 {summary['to_dispatch']}（其中人工放行重跑 {rel_n}"
+              + (f"、上游变化重置 {reset_n}" if reset_n else "")
+              + (f"、外部时序通道 {ext_n}" if ext_n else "") + "）"
+              f"｜待放行 {summary['await_release']}｜等人补字段 {summary['need_fields']}"
+              f"｜在飞 {summary['in_flight']}｜停滞 {summary['stale']}｜可重试 {summary['retry']}｜需人工 {summary['needs_human']}"
+              + (f"｜信息性事件回退 {info_n}" if info_n else ""))
+        if SOURCE_NOTES:
+            print('    · 源清单说明：' + '；'.join(SOURCE_NOTES))
+        for k in ('to_dispatch', 'await_release', 'need_fields', 'stale', 'retry', 'needs_human'):
+            for r in b[k]:
+                extra = ('缺: ' + '、'.join(r.get('humanMissing') or r.get('missing') or [])[:60]) if (r.get('humanMissing') or r.get('missing')) else ''
+                print(f"    [{k}] {r['ticket']}  {extra}")
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())