pi-multi-viewers 0.1.0 → 0.2.0

package/AGENTS.md

@@ -18,7 +18,9 @@ meeting_fs.py        git/文件层
 meeting_engine.py    【唯一状态机】+ 协议信号 + responder 注入
 meeting_loop.py      Pi 薄壳：首唤生成 fork 源 + `--session` 打开 → 存 sid → `--session-id` 续接
 fake_agent.py        测试薄壳：responder = 随机决策
-start_discussion.py  环境生成/启动/清理（viewers 发现 / spec 解析 / fork 源）
+start_discussion.py  组合层：CLI 分发 + 环境创建/启动/清理（_resolve_spec / setup_environment）
+spec_gen.py          spec 生成层（question/骨架/viewers 校验与快照/agent 定义 + pi 环境探测）
+observability.py     观测层（check_status / --report / --wait / loop 存活检测）
 human_viewer.py      【human 通道】只读展示（增量/--follow/游标）
 human_sayer.py       【human 通道】插话命令（单次/stdin/交互 -i）
 scripts/mv.sh        wrapper（prepare/start/status/wait/cleanup/view/say）
@@ -174,7 +176,7 @@ loop、状态从 git 共享事实推导、单一事实源 = protocol.json、无
   extension × 1（multi-viewers-say 插话：零 LLM，直接 spawn human_sayer.py；
   目录发现 = `<cwd>/mv-<sessionId>-*` 最新，兜底 `mv-*`（排除
   `mv-spec-*`）并警告）
-  + wrapper。**npm 已发布 0.1.0（2026-09-11）**。
+  + wrapper。**npm 已发布 0.2.0（2026-09-11）**。
 - **开发机安装（两步，缺一不可；2026-09-10 实测）**：
   ① `pi install /root/pi-multi-viewers`——**注册包**（写
   `~/.pi/agent/settings.json` 的 `packages` 数组）；pi 不是"扫 node_modules

package/README.md

@@ -89,6 +89,8 @@ scripts/mv.sh --start <spec目录>              # 启动（自动挂载主 sessi
 
 # 观看：--start 会输出可直接执行的 !! 流式观看命令（复制执行）
 scripts/mv.sh --view <dir>                    # 或一次性增量查看（主 pi 记录 HEAD 作下轮 --since）
+#  --follow 会打印【状态】(meeting/all-freezing/round-robin/concluded)
+#         与【进度】(meeting 消耗/上限 ｜ freezing 集合 ｜ rr → 下一位)
 
 # 插话 / 状态 / 收尾
 scripts/mv.sh --say <dir> "<文本>"             # 插话（命令行形态；pi 内用 /multi-viewers-say）
@@ -132,14 +134,19 @@ frontmatter 字段、写文件路径、独立参与者纪律。
 ## 架构
 
 ```
-meeting_core.py    纯判定（冻结级联/RR/聚合）
-meeting_fs.py      git 层
-meeting_engine.py  唯一状态机（六分支）
-meeting_loop.py    Pi 薄壳（fork 首唤 + --session-id 续接 + 视角注入）
-start_discussion.py 环境生成/启动/状态/清理
-human_viewer/sayer human 插话通道
+meeting_core.py     纯判定（冻结级联/RR/聚合 + 状态机词汇常量）
+meeting_fs.py       git 层 + fork 源生成/裁剪 + 协议与产物常量
+meeting_engine.py   唯一状态机（六分支）
+meeting_loop.py     Pi 薄壳（fork 首唤 + --session-id 续接 + 视角注入）
+start_discussion.py 组合层：CLI 分发 + 环境创建/启动/清理
+spec_gen.py         spec 生成（question/骨架/viewers 快照/agent 定义 + pi 环境探测）
+observability.py    观测（check_status / --report / --wait / loop 存活）
+human_viewer/sayer  human 插话通道
 ```
 
+依赖方向单向：`core ← fs ← engine ← loop`；`start_discussion` 组合
+`spec_gen` / `observability`（两者只依赖底层，互不依赖、不反向依赖主文件）。
+
 ## 开发
 
 ```bash

package/docs/design.md

@@ -112,6 +112,15 @@ BOUNDARY_TYPE`）——**显式登记"历史（fork 携带）/ 本轮"的分界*
 推断都会漂移（切换叙事改措辞、时钟精度）。2026-09-11 实测：不带边界时报告
 把 717 条 fork 历史算成"本轮 367 次响应 / input 1.2M / cacheRead 136.6M"。
 
+**viewer 进度行（三样观测面）**：`--follow` 每轮在【状态】之外打印
+【进度】行——`meeting <消耗>/<上限> · … ｜ freezing <已冻结>/<总数>（名单）
+｜ rr → <下一位>`。**状态名一律用协议术语**（`meeting`/`freezing`/`rr`；
+译成中文会引入第二套命名，"冻结"到底指 freezing 还是 all-freezing 说不清）。
+判定与 `--report` 共用 core/engine 单一实现（`meeting_speak_count` /
+`frozen_agents` / `rr_next_speaker`），且共用调用方已读的 `msgs`——
+**零新增 bare 读取**（实测改动前后同为 6 次 run 调用 + 1 次 cat-file 批读；
+`rr` 位置仅在 RR 阶段按需调权威实现）。进度行**只在变化时打印**（避免刷屏）。
+
 **报告的打印位置**：`--report`（手动，任意时刻）+ `--cleanup` 前（自动，
 删目录前最后一次可读——目录删后 `--report` 不可用）。cleanup 层对报告
 fail-open（报告失败不阻断清理，且**打印**失败原因不静默）。
@@ -224,7 +233,39 @@ commit 是溯源记录、本节是长期引用点——不并存两份权威值
    `mv-spec-*`）并**警告降级**
    （宁可提示也不静默插错分析）。观看仍用 `!!` 流式（命令 API 无原生流式
    通道，bash 流式是平台原生能力）。
-10. **git 守卫范围 = 从讨论 workdir 发起的操作**（`GIT_CEILING_DIRECTORIES`
+10. **question.md 的主题行措辞 = `# 分析主题：`（唯一）**：生成端
+    （`gen_question` / `gen_spec_skeleton`）、模板（`spec-readme`）、prompt、
+    消费端（`setup_environment` 提取 `protocol.topic`）四处同一措辞；
+    消费端**只认它**，旧措辞 spec → fail-fast（明确报错，不静默退化）。
+    曾出现双轨（生成产 `# 讨论主题：`、消费端写兼容循环兜两种）——那
+    正是"补丁掩盖设计缺陷"的形态（不改生产、只兜消费端）。
+11. **stall 接管 = 心跳式软仲裁（非互斥）**：非 rw 在无进展超时时接管收尾，
+    先 pull 重检共享事实（concluded / result.md）→ 写接管声明 commit
+    （**只为推进 HEAD**，使对方 `_stall_elapsed` 归零而退出该分支）→
+    finalize。毫秒级同轮窗口存在（双方都可能 finalize），但**不是死锁**：
+    靠 push 容错 + 下轮 concluded 退出兜底，产物始终唯一。声明只降低并发
+    概率，**不构成互斥保证**（注释勿写"天然唯一"）。实测（2026-09-11，
+    381 测试中的 `TestStallTakeover`）：a 进入接管 0.11s 内完成声明→收尾→
+    concluded，b 晚 1.4s 只见 concluded 即退出——正常时序下软仲裁生效。
+12. **`result.md` 的文件名与有效性阈值 = `meeting_fs.RESULT_MD` /
+    `RESULT_MD_MIN_BYTES`**：产品级核心产物，此前 8 处字面量分散在
+    engine/loop/viewer/start_discussion/fake_agent（`repo.git` 早已收归
+    fs 层，产物名却没有家）。文件叫什么、多大算有效——同一概念的两个
+    数字住在一起。
+13. **分层 = core ← fs ← engine ← loop，`start_discussion` 是组合层**
+    （S2 拆分后）：三项职责按"谁消费"拆到两个同层模块——
+    `spec_gen.py`（分析前的静态产物生成 + 为其服务的 pi 环境探测）、
+    `observability.py`（运行期只读观测）；主文件保留 CLI 分发、环境创建、
+    启动、清理与编排。**判据是职责而非行数**：spec 生成与观测各自 350–520
+    行、概念内聚，再拆会制造碎片（import 网变复杂而收益递减）。
+    两个子模块只依赖底层（core/fs/engine），互不依赖、不反向依赖主文件；
+    主文件 re-export 子模块公开符号，保证 `from start_discussion import X`
+    的既有调用方（tests/wrapper）零改动。
+    **拆分暴露的纪律**：`mock.patch` 必须打在**符号定义处**（拆前
+    `start_discussion.check_status` 与定义处同址，拆后 mock re-export
+    不生效——本轮 4 处测试因此假绿/失败，已改到 `spec_gen` /
+    `observability`）。
+14. **git 守卫范围 = 从讨论 workdir 发起的操作**（`GIT_CEILING_DIRECTORIES`
    注入于 spawn）；主项目仓库不在守卫范围（agent 的 cwd 就是主项目，其
    约束归指令层 + 主项目 `.gitignore`）。要拦主仓库需换机制类（沙箱/钩子），
    经评估收益不支撑扩面。

package/fake_agent.py

@@ -21,6 +21,8 @@ import time
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
+import meeting_core
+import meeting_fs
 from meeting_fs import next_msg_id, write_message
 from meeting_engine import agent_loop
 
@@ -65,7 +67,7 @@ def make_responder(min_sleep, max_sleep, crash_rate):
         # --- 内容决定（LLM 的判断）---
         if finalizing:
             # 收尾指令：resultWriter 写 result.md（双面约束：此时才允许写）
-            result_path = os.path.join(workdir, "result.md")
+            result_path = os.path.join(workdir, meeting_fs.RESULT_MD)
             # 内容 >50 字节（_result_md_valid 阈值，审核#3）——否则恒走
             # loop 兜底代写，正常收尾路径零验证（fake 与真实 responder 语义不一致）
             # 文案三分支（review4 L12）：stall 不误标"配额耗尽"
@@ -81,13 +83,14 @@ def make_responder(min_sleep, max_sleep, crash_rate):
             return True
         if retry:
             # 被重试（上次没产出）：无静默铁律，强制表态
-            decision = "freezing" if not rr_turn else "pass"
+            decision = meeting_core.T_FREEZING if not rr_turn else meeting_core.T_PASS
         elif rr_turn:
             # RR 阶段：单向流，只写 pass（无异议回退，留待以后）
-            decision = "pass"
+            decision = meeting_core.T_PASS
         else:
             # meeting 阶段：有内容 → message；无话可说 → freezing
-            decision = "message" if random.random() < 0.65 else "freezing"
+            decision = meeting_core.T_MESSAGE if random.random() < 0.65 \
+                else meeting_core.T_FREEZING
 
         time.sleep(random.uniform(min_sleep, max_sleep))
         if random.random() < crash_rate:
@@ -116,5 +119,13 @@ if __name__ == "__main__":
     workdir, agent = sys.argv[1], sys.argv[2]
     responder = make_responder(float(sys.argv[3]), float(sys.argv[4]),
                                float(sys.argv[5]))
+    # stall 超时：与生产（meeting_loop.__main__）同款——protocol 优先
+    # （装置对齐生产：此前 fake_agent 恒用默认 600s，stall 路径在测试中
+    # 永不可达——P2 的接管分支零覆盖正是这个原因）
+    stall_timeout = meeting_fs.DEFAULT_STALL_TIMEOUT
+    proto = meeting_fs.read_protocol(meeting_fs.bare_of_workdir(workdir))
+    if proto.get("stallTimeoutSeconds"):
+        stall_timeout = proto["stallTimeoutSeconds"]
     agent_loop(workdir, agent, responder,
-               max_meeting=int(sys.argv[6]), max_rr=int(sys.argv[7]))
+               max_meeting=int(sys.argv[6]), max_rr=int(sys.argv[7]),
+               stall_timeout=stall_timeout)

package/human_viewer.py

@@ -28,10 +28,17 @@ import os
 import sys
 import time
 
+import meeting_core
 import meeting_fs
 from meeting_fs import (run_git, git_show, git_head, is_message_file,
                         parse_log_nameonly, extract_body, parse_frontmatter)
-from meeting_engine import aggregate_mode
+from meeting_core import (
+    aggregate_mode as core_aggregate_mode,
+    frozen_agents,
+    meeting_speak_count,
+)
+from meeting_engine import (each_agent_last, each_agent_messages,
+                            rr_next_speaker)
 
 
 def participants_from_bare(bare):
@@ -94,23 +101,32 @@ def is_finished(bare, agents, mode=None):
     为什么落 viewer：它是唯一增量实现的持有者，也是观察端判据的家。
     """
     if mode is None:
-        mode = aggregate_mode(bare, agents)
-    if mode != "concluded":
+        # 经 engine.each_agent_last（它把最后一条规范化成 {type, mode, next}
+        # ——缺字段补 None）；直接传原始 frontmatter 会在 core 里 KeyError
+        # （core 用 v["mode"] 按契约取值，不猜缺字段）
+        mode = core_aggregate_mode(each_agent_last(bare, agents))
+    if mode != meeting_core.M_CONCLUDED:
         return False
-    content = git_show(bare, "HEAD", "result.md")
-    return bool(content) and len(content) > 50
+    content = git_show(bare, "HEAD", meeting_fs.RESULT_MD)
+    return bool(content) and len(content) > meeting_fs.RESULT_MD_MIN_BYTES
 
 
-def incremental(bare, agents, since):
+def incremental(bare, agents, since, max_meeting=None):
     """单次增量读取。
 
-    返回: (mode, lines: list[str], head, done)
+    返回: (mode, lines: list[str], head, done, progress)
     - mode: 当前聚合 mode（meeting/all-freezing/round-robin/concluded）
     - lines: 新消息展示行（旧→新）
     - head: 当前 HEAD
-    - done: 分析是否已收尾（mode == concluded）
+    - done: 分析是否已收尾（concluded 且 result.md 有效）
+    - progress: 进度行文本（三样观测面，见 progress_text）
+
+    **单次读取**：一次 each_agent_messages → 派生 mode 与全部三样观测面
+    （mode 判定、freezing 集合、meeting 配额），不重复读 bare。
     """
-    mode = aggregate_mode(bare, agents)
+    msgs = each_agent_messages(bare, agents)
+    lasts = {a: (msgs[a][-1] if msgs[a] else None) for a in agents}
+    mode = core_aggregate_mode(lasts)
     lines = []
     for commit, path in new_messages(bare, since):
         content = git_show(bare, commit, path)
@@ -120,7 +136,43 @@ def incremental(bare, agents, since):
         if s:
             lines.append(s)
     head = git_head(bare)
-    return mode, lines, head, is_finished(bare, agents, mode)
+    return (mode, lines, head, is_finished(bare, agents, mode),
+            progress_text(bare, agents, msgs, lasts, mode, max_meeting))
+
+
+def progress_text(bare, agents, msgs, lasts, mode, max_meeting=None):
+    """进度行：三样观测面（**状态名一律用协议术语**，不翻译）。
+
+    形态：`meeting 7/10 · 6/10 ｜ freezing 2/3（性能、简单）｜ rr → 简单`
+
+    - `meeting`：配额消耗/上限（`meeting_core.meeting_speak_count` 口径
+      ——"mode:meeting 且 type:message"的发言轮；上限来自 protocol，
+      调用方传入；未传则只显示消耗数）。
+    - `freezing`：已冻结数/总数（`meeting_core.frozen_agents`）。
+    - `rr`：RR 阶段轮到谁（**权威实现** `rr_next_speaker`；仅
+      round-robin 阶段出现）。
+
+    **为什么用协议术语而非中文**（用户 2026-09-11）：状态名是协议的
+    一等概念（`meeting`/`freezing`/`round-robin`），翻译成中文会引入
+    第二套命名（"冻结"到底指 freezing 还是 all-freezing？）——协议名
+    在代码、消息 frontmatter、`--report`、viewer 里只有一个说法。
+
+    判定全部复用 core/engine 的单一实现（与 `--report` 同一份），
+    且共用调用方已读的 msgs——**零新增 bare 读取**；仅 rr 位置在
+    RR 阶段调权威实现（需要读 HEAD 的文件列表，属必要成本）。
+    """
+    types = {a: (lasts[a].get("type") if lasts[a] else None) for a in agents}
+    parts = []
+    counts = " · ".join(f"{meeting_speak_count(msgs, a)}"
+                        + (f"/{max_meeting}" if max_meeting else "")
+                        for a in agents)
+    parts.append(f"meeting {counts}")
+    frozen = frozen_agents(agents, types)
+    parts.append(f"freezing {len(frozen)}/{len(agents)}"
+                 + (f"（{'、'.join(frozen)}）" if frozen else ""))
+    if mode == meeting_core.M_ROUND_ROBIN:
+        parts.append(f"rr → {rr_next_speaker(bare, agents) or '（未定）'}")
+    return " ｜ ".join(parts)
 
 
 def _cursor_path(base):
@@ -150,15 +202,27 @@ def _write_cursor(base, ref):
 OBSERVER_POLL_INTERVAL = 2.0
 
 
-def follow(base, bare, agents, poll_interval=OBSERVER_POLL_INTERVAL):
-    """--follow：循环展示（tail -f 式）直到分析结束。"""
+def follow(base, bare, agents, max_meeting=None,
+           poll_interval=OBSERVER_POLL_INTERVAL):
+    """--follow：循环展示（tail -f 式）直到分析结束。
+
+    状态名用协议术语（`【状态】meeting` / `all-freezing` / `round-robin`
+    / `concluded`）；进度行见 progress_text。
+    """
     since = _read_cursor(base)
     last_mode = None
+    last_progress = None
     while True:
-        mode, lines, head, done = incremental(bare, agents, since)
+        mode, lines, head, done, progress = incremental(
+            bare, agents, since, max_meeting)
         if mode != last_mode:
             print(f"【状态】{mode}", flush=True)
             last_mode = mode
+        # 进度行只在**变化时**打印（每轮都打会刷屏；冻结/配额/RR 位
+        # 置在两次消息之间本就不变）
+        if progress != last_progress:
+            print(f"【进度】{progress}", flush=True)
+            last_progress = progress
         for s in lines:
             print(s, flush=True)
         if head != since:
@@ -184,17 +248,22 @@ def main():
         print(f"错误: 分析不存在: {base}", file=sys.stderr)
         return 1
 
-    agents = participants_from_bare(bare)
+    proto = meeting_fs.read_protocol(bare)   # 一次读取：参与者 + 配额上限
+    agents = proto.get("participants") or None
     if not agents:
         print(f"错误: 无法读取 protocol.json（分析未初始化?）: {base}",
               file=sys.stderr)
         return 1
+    max_meeting = proto.get("maxMeetingRounds")
 
     sys.stdout.reconfigure(line_buffering=True)
     if args.follow:
-        follow(base, bare, agents)
+        follow(base, bare, agents, max_meeting=max_meeting)
     else:
-        mode, lines, _, done = incremental(bare, agents, args.since)
+        mode, lines, _, done, progress = incremental(
+            bare, agents, args.since, max_meeting)
+        print(f"【状态】{mode}", flush=True)
+        print(f"【进度】{progress}", flush=True)
         print(f"【状态】{mode}", flush=True)
         for s in lines:
             print(s, flush=True)

package/meeting_core.py

@@ -16,6 +16,25 @@
 MEETING_TYPES = {"message", "freezing", "all-freezing", "pass", "concluded"}
 """meeting 模式合法 type 集合（校验器白名单）"""
 
+# ---------------------------------------------------------------
+# 状态机词汇（**字面量的家**）——消息 type / 全局 mode 的合法值。
+# 谁消费：core（全部判定）、engine（信号写点 + 分支）、loop（fatal 文案）、
+# viewer（展示）、fake_agent（responder 决策池）。
+# 为什么建家：这些字符串是**状态机的词表**，任何一处拼写漂移 = 判定静默
+# 失效。曾是 46 处字面量散在 6 个文件（e2e15 自审 S3）。
+# 注意：**不要**为了用常量而替换注释/日志文案里的词（那是给人读的）——
+# 只替换"参与判定的值"。
+# ---------------------------------------------------------------
+T_MESSAGE = "message"
+T_FREEZING = "freezing"
+T_ALL_FREEZING = "all-freezing"
+T_PASS = "pass"
+T_CONCLUDED = "concluded"
+M_MEETING = "meeting"
+M_ROUND_ROBIN = "round-robin"
+M_ALL_FREEZING = T_ALL_FREEZING          # mode 值与 type 值同形（af 复用）
+M_CONCLUDED = T_CONCLUDED
+
 # ---------------------------------------------------------------
 # 1. 冻结判定（阶段 1.1）
 # ---------------------------------------------------------------
@@ -187,7 +206,7 @@ def meeting_speak_count(messages, agent):
     "meeting 6/2" 的超限假象——6 是消息总数、2 是配额上限）。
     """
     return sum(1 for fm in messages.get(agent, [])
-               if fm.get("mode") == "meeting" and fm.get("type") == "message")
+               if fm.get("mode") == M_MEETING and fm.get("type") == T_MESSAGE)
 
 
 def frozen_agents(agents, all_last_types):
@@ -229,7 +248,7 @@ def can_start_rr(all_last_types):
         return False
     if any(t is None for t in all_last_types.values()):
         return False
-    return all(t == "all-freezing" for t in all_last_types.values())
+    return all(t == T_ALL_FREEZING for t in all_last_types.values())
 
 
 def aggregate_mode(all_last):
@@ -243,13 +262,13 @@ def aggregate_mode(all_last):
     4. 否则 → meeting
     """
     if not all_last:
-        return "meeting"   # 空 → 无任何 agent → 无冻结无 RR（review5 F3）
+        return M_MEETING   # 空 → 无任何 agent → 无冻结无 RR（review5 F3）
     types = {a: (v["type"] if v else None) for a, v in all_last.items()}
     modes = {a: (v["mode"] if v else None) for a, v in all_last.items()}
-    if any(t == "concluded" for t in types.values()):
-        return "concluded"
-    if any(m == "round-robin" for m in modes.values()):
-        return "round-robin"
-    if all(t in ("freezing", "all-freezing") for t in types.values()):
-        return "all-freezing"
+    if any(t == T_CONCLUDED for t in types.values()):
+        return T_CONCLUDED
+    if any(m == M_ROUND_ROBIN for m in modes.values()):
+        return M_ROUND_ROBIN
+    if all(t in (T_FREEZING, T_ALL_FREEZING) for t in types.values()):
+        return T_ALL_FREEZING
     return "meeting"

package/meeting_engine.py

@@ -35,6 +35,7 @@ from meeting_fs import (
     git_show, is_message_file, parse_log_nameonly,
     read_protocol, cat_batch, remove_message, write_text, file_size,
     bare_of_base, bare_of_workdir, log,
+    RESULT_MD, RESULT_MD_MIN_BYTES, DEFAULT_STALL_TIMEOUT,
 )
 from meeting_core import (
     meeting_speak_count as core_meeting_speak_count,
@@ -42,6 +43,8 @@ from meeting_core import (
     should_write_af, can_start_rr, validate_and_fix, is_all_last_in,
     aggregate_mode as core_aggregate_mode,
     has_new_messages_for_me,
+    T_MESSAGE, T_FREEZING, T_ALL_FREEZING, T_PASS, T_CONCLUDED,
+    M_MEETING, M_ROUND_ROBIN, M_ALL_FREEZING, M_CONCLUDED,
 )
 POLL_INTERVAL = 2.0
 JITTER = 0.3
@@ -209,7 +212,7 @@ def rr_active_count(messages, agents):
     """
     starter = agents[0]
     return sum(1 for fm in messages.get(starter, [])
-               if fm.get("mode") == "round-robin")
+               if fm.get("mode") == M_ROUND_ROBIN)
 
 
 def human_msg_count(bare):
@@ -255,11 +258,12 @@ def write_af_if_no_rr(bare, workdir, agent, agents):
     head = git_head(workdir)
     # 重检：bare 是否有 RR 已启动（任一 agent 最后一条 mode==round-robin）
     lasts = each_agent_last(bare, agents)
-    if any(v is not None and v.get("mode") == "round-robin" for v in lasts.values()):
+    if any(v is not None and v.get("mode") == M_ROUND_ROBIN
+           for v in lasts.values()):
         log(agent, "bare 已有 RR 启动——放弃补写 af")
         return
     # 无 RR → 正常写 af
-    write_protocol_signal(workdir, agent, "all-freezing", "all-freezing")
+    write_protocol_signal(workdir, agent, T_ALL_FREEZING, M_ALL_FREEZING)
 
 
 def write_protocol_signal(workdir, agent, type_, mode, next_=None):
@@ -331,11 +335,11 @@ def respond_with_fallback(workdir, agent, responder, head, meta, is_first,
     if rr_turn:
         nxt_a = core_next(agents, agent)
         log(agent, f"responder 无法产出——loop 代写 pass（无静默铁律最后执行）")
-        write_protocol_signal(workdir, agent, "pass", "round-robin",
+        write_protocol_signal(workdir, agent, T_PASS, M_ROUND_ROBIN,
                               nxt_a)
     else:
         log(agent, f"responder 无法产出——loop 代写 freezing")
-        write_protocol_signal(workdir, agent, "freezing", "meeting")
+        write_protocol_signal(workdir, agent, T_FREEZING, M_MEETING)
     # 代写 = 无产出（设计 11.1：只数 responder 成功产出的轮，
     # 代写不耗配额）——返回 False（审核#1：原先 return True 让 C' 修复失效）
     return False
@@ -391,7 +395,7 @@ def commit_new_files(workdir, agent, head, mode):
         # review5 A6：next 无条件覆盖为顺序下一位（与 mode 无条件覆盖对称）。
         # 只补缺省会让 LLM 写错的 next 保留 → 轮转顺序混乱。单向流下
         # RR 只有 pass（无异议），next 是轮转顺序（协议状态），LLM 不知道。
-        if mode == "round-robin" and fixed.get("type") in ("pass", "message"):
+        if mode == M_ROUND_ROBIN and fixed.get("type") in (T_PASS, T_MESSAGE):
             fixed["next"] = core_next(
                 participants(bare_of_workdir(workdir)), agent)
         new_content = serialize_message(fixed, content)
@@ -447,7 +451,7 @@ def _result_md_valid(workdir):
     LLM 可能写空文件/仅 frontmatter——存在性检查退化为空提交（审核 A2）。
     存在性与大小经由 fs.file_size 一次判定（-1 = 不存在/不可读）。
     """
-    return file_size(workdir, "result.md") > 50
+    return file_size(workdir, RESULT_MD) > RESULT_MD_MIN_BYTES
 
 
 def finalize_discussion(workdir, agent, responder, head, reason="consensus"):
@@ -462,7 +466,7 @@ def finalize_discussion(workdir, agent, responder, head, reason="consensus"):
     responder(workdir, agent, head, [], False, False, False,
               finalizing=True, finalize_reason=reason)
     # ② 校验 result.md 有效（存在 + 非空）；无则重试（无静默铁律的扩展）
-    result_path = os.path.join(workdir, "result.md")
+    result_path = os.path.join(workdir, RESULT_MD)
     for _ in range(MAX_RETRY):
         if _result_md_valid(workdir):
             break
@@ -475,11 +479,11 @@ def finalize_discussion(workdir, agent, responder, head, reason="consensus"):
         _commit_result_md(workdir, agent, "discuss: result.md")
     else:
         log(agent, "result.md 重试后仍无效——loop 兜底代写")
-        write_text(workdir, "result.md",
+        write_text(workdir, RESULT_MD,
                    "# 讨论结论\n\n（resultWriter 未能生成有效 result.md，"
                    f"由本地循环兜底代写。收尾原因：{reason}）\n")
         _commit_result_md(workdir, agent, "discuss: result.md (loop fallback)")
-    write_protocol_signal(workdir, agent, "concluded", "concluded")
+    write_protocol_signal(workdir, agent, T_CONCLUDED, M_CONCLUDED)
     return True
 
 
@@ -491,16 +495,17 @@ def _commit_result_md(workdir, agent, subject):
     用 git status --porcelain（不用 git diff --quiet——diff 看不到
     未跟踪新文件，会误判"已提交"导致 result.md 永不 commit）。
     """
-    r = run_git(workdir, "status", "--porcelain", "--", "result.md",
+    r = run_git(workdir, "status", "--porcelain", "--", RESULT_MD,
                 check=False)
     if r.stdout.strip():
-        git_commit(workdir, ["result.md"], subject)
+        git_commit(workdir, [RESULT_MD], subject)
     else:
         log(agent, "result.md 无改动——跳过 commit（幂等）")
 
 
 def agent_loop(workdir, agent, responder, max_meeting=10, max_rr=7,
-               poll_interval=POLL_INTERVAL, stall_timeout=600):
+               poll_interval=POLL_INTERVAL,
+               stall_timeout=DEFAULT_STALL_TIMEOUT):
     """主状态机（v2）。responder 注入：响应一轮并返回是否产出。
 
     stall_timeout: 无进展超时兜底（秒，默认 600=10 分钟）。任何 agent
@@ -542,7 +547,7 @@ def agent_loop(workdir, agent, responder, max_meeting=10, max_rr=7,
             mode = core_aggregate_mode(lasts)
 
             # ===== ① concluded → 退出 =====
-            if mode == "concluded":
+            if mode == M_CONCLUDED:
                 log(agent, "讨论已收尾，退出")
                 return
 
@@ -559,16 +564,29 @@ def agent_loop(workdir, agent, responder, max_meeting=10, max_rr=7,
                     finalize_discussion(workdir, agent, responder, head,
                                         reason="stall")
                     continue
-                # 非 rw：rw 可能离线（崩溃/未启动）——接管收尾（审核#2，
-                # 主协议 7.6"任一 agent 可接管"，meeting 收紧成仅 rw 是缺口）。
-                # 接管仲裁（review5 A3）：两个非 rw 同时接管 → 各自 finalize
-                # → 双写 result.md → rebase 冲突真死锁。仲裁：
-                # ① 先 pull 重检 bare 是否已收尾（result.md 已提交 → 让位）
-                # ② 写接管声明消息（推进 HEAD → 其他 agent 的 stall 判定被
-                #    重置 → 天然唯一接管者；push 冲突由现有容错重试仲裁，
-                #    先到者赢）③ finalize。
+                # 非 rw：rw 可能离线（崩溃/未启动）——接管收尾（主协议
+                # 7.6"任一 agent 可接管"；meeting 收紧成仅 rw 是缺口）。
+                #
+                # 仲裁 = **心跳式软仲裁**（不是互斥锁）：
+                # ① 先 pull + 重检两个"是否已收尾"的共享事实（concluded /
+                #    result.md 已提交）——已收尾则让位；
+                # ② 写一条接管声明 commit，作用是**推进 HEAD**：其他 agent
+                #    下一轮 `_stall_elapsed` 看到 HEAD 变化 → 累计归零 →
+                #    退出接管分支（先到者成为事实上的唯一收尾者）；
+                # ③ finalize。
+                #
+                # **残余窗口（诚实边界）**：声明落地前，另一方若已走完本轮
+                # 的 git_head + stall 判定，则同样进入本分支（窗口≈毫秒级，
+                # 同一轮竞态）。此时双方各自唤醒 LLM 写 result.md——结果
+                # **不是死锁**：先 push 者成功；后者 push 走 git_push 的
+                # pull --rebase 重试，内容冲突则耗尽重试抛错 → loop 顶层
+                # 异常边界接住 → 下一轮看到 concluded 退出。
+                # 代价 = 偶尔多一次 LLM 调用（约 30–60s）；产物始终唯一
+                # （bare 只有一个 result.md 版本）。
+                # **真正的兜底是 push 容错 + 下一轮 concluded 退出这两层**；
+                # 声明只降低并发概率，不构成互斥保证（勿读成"天然唯一"）。
                 git_pull(workdir)
-                if aggregate_mode(bare, agents) == "concluded":
+                if aggregate_mode(bare, agents) == M_CONCLUDED:
                     log(agent, "收尾已完成（他人接管）——让位")
                     continue
                 r = run_git(bare, "show", "HEAD:result.md", check=False)
@@ -577,8 +595,9 @@ def agent_loop(workdir, agent, responder, max_meeting=10, max_rr=7,
                     continue
                 # 写接管声明（freezing——推进 HEAD + 不破坏流程）
                 log(agent, "rw 未收尾——声明接管（推进 HEAD 天然唯一接管者）")
-                write_protocol_signal(workdir, agent, "freezing",
-                                      aggregate_mode(bare, agents) or "meeting")
+                write_protocol_signal(workdir, agent, T_FREEZING,
+                                      aggregate_mode(bare, agents)
+                                      or M_MEETING)
                 finalize_discussion(workdir, agent, responder, head,
                                     reason="stall")
                 continue
@@ -591,7 +610,7 @@ def agent_loop(workdir, agent, responder, max_meeting=10, max_rr=7,
                 continue
 
             # ===== ③ all-freezing 阶段：starter 启动 RR =====
-            if mode == "all-freezing":
+            if mode == M_ALL_FREEZING:
                 # starter 严格条件：全员 af → 启动 RR（用户 10084/10089：
                 # 唤醒目的 = 有新的文件可提交给 LLM 处理。starter 冻结期间
                 # 别人可能发了 message（读取点后），必须唤醒读完再 pass；
@@ -609,14 +628,14 @@ def agent_loop(workdir, agent, responder, max_meeting=10, max_rr=7,
                     else:
                         # 无新消息 → 确定性写 pass（启动 RR，带 next 轮转链）
                         nxt_a = core_next(agents, agent)
-                        write_protocol_signal(workdir, agent, "pass",
-                                              "round-robin", nxt_a)
+                        write_protocol_signal(workdir, agent, T_PASS,
+                                              M_ROUND_ROBIN, nxt_a)
                     continue
                 time.sleep(poll_interval)
                 continue
 
             # ===== ④ round-robin 阶段（发言锁已解）=====
-            if mode == "round-robin":
+            if mode == M_ROUND_ROBIN:
                 # 全员 pass → resultWriter 收尾（写 result.md + concluded）
                 # 判定收敛到 core（审核 D：判定只此一份——core 吃完整消息列表，
                 # 引擎只做 bare 组装）
@@ -649,8 +668,8 @@ def agent_loop(workdir, agent, responder, max_meeting=10, max_rr=7,
                 meta = new_messages_with_meta(workdir, rp, agent)
                 if not has_new_messages_for_me(meta, agent):
                     nxt_a = core_next(agents, agent)
-                    write_protocol_signal(workdir, agent, "pass",
-                                          "round-robin", nxt_a)
+                    write_protocol_signal(workdir, agent, T_PASS,
+                                          M_ROUND_ROBIN, nxt_a)
                     continue
                 before = len(list_my_messages(workdir, agent))
                 respond_with_fallback(workdir, agent, responder, head, meta,
@@ -691,7 +710,7 @@ def agent_loop(workdir, agent, responder, max_meeting=10, max_rr=7,
                     and all_last.get(agent) != "freezing"):
                 log(agent, f"meeting 配额耗尽（{quota} 轮，含 human 增量"
                            f"{quota - max_meeting}）——确定性 freezing")
-                write_protocol_signal(workdir, agent, "freezing", "meeting")
+                write_protocol_signal(workdir, agent, T_FREEZING, M_MEETING)
                 continue
 
             # ⑤.3 触发判断
@@ -705,7 +724,7 @@ def agent_loop(workdir, agent, responder, max_meeting=10, max_rr=7,
             # 唯一未冻结者（无新消息）→ 确定性 freezing（不经 responder）
             if others_frozen and not triggered and all_last.get(agent) != "freezing":
                 log(agent, "其他人都已冻结且无新消息——确定性 freezing")
-                write_protocol_signal(workdir, agent, "freezing", "meeting")
+                write_protocol_signal(workdir, agent, T_FREEZING, M_MEETING)
                 continue
             # 无新消息（非唯一未冻结者）→ 等待（L2：化简，先 freezing 后 sleep）
             if not triggered:
@@ -713,7 +732,7 @@ def agent_loop(workdir, agent, responder, max_meeting=10, max_rr=7,
                 continue
 
             # ⑤.4 发言锁：我最后是 freezing → 锁（不发 message，等 RR）
-            if all_last.get(agent) == "freezing":
+            if all_last.get(agent) == T_FREEZING:
                 time.sleep(poll_interval)
                 continue