pi-multi-viewers 0.1.0

package/start_discussion.py

@@ -0,0 +1,1485 @@
+#!/usr/bin/env python3
+"""start_discussion.py —— Meeting 模式讨论环境生成 + 启动（独立于 agents-rr-discuss）。
+
+用法：
+  python3 start_discussion.py --dir mymeet --topic "主题" --agents a,b \
+      [--stances '{"a": "立场1", "b": "立场2"}'] [--start] [--pure] \
+      [--models '{"a": "provider/model"}'] [--max-meeting 10] [--max-rr 7]
+
+复杂内容用 spec 规格目录（设计 16，与 CLI 内容参数互斥）：
+  1. 生成骨架:  python3 start_discussion.py --spec-gen myspec --agents a,b,c
+  2. 编辑内容:  vim myspec/question.md myspec/background.md myspec/models.md myspec/agents/*.md
+  3. 创建讨论:  python3 start_discussion.py --dir mymeet --spec myspec/ --result-writer c
+
+生命周期：
+  创建（--dir）→ 启动（--start，可选）→ 观察（--status/--wait）→ 清理（--cleanup）
+"""
+
+import argparse
+import glob
+import json
+import os
+import meeting_fs
+import human_viewer
+import meeting_core
+import meeting_engine
+import re
+import shutil
+import subprocess
+import sys
+import time
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+TPL_DIR = os.path.join(HERE, "templates")
+PI_AGENT_DIR = os.environ.get("PI_CODING_AGENT_DIR",
+                             os.path.expanduser("~/.pi/agent"))
+GIT_USER = "meeting-bot"
+GIT_EMAIL = "meeting-bot@local"
+
+
+def run_cmd(cmd, cwd=None, check=True):
+    """执行一次性环境命令（git init/clone/config/push 等）。
+
+    **读路径不走这里**：读取仓库内容的 git 命令一律用 `meeting_fs.run_git`
+    （带 core.quotepath=false 加固——中文视角名下 quotepath 转义会让路径
+    解析失效；两个入口并存时加固只覆盖一半，是同类问题的潜在根因）。
+    """
+    r = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
+    if check and r.returncode != 0:
+        raise RuntimeError(f"cmd {cmd} 失败: {r.stderr.strip()}")
+    return r
+
+
+def _spec_read(spec_dir, rel):
+    """读 spec 文件内容，永远跳过第一行（说明行，B 方案）。
+
+    设计 16.4：第一行是骨架生成时的用途说明，不注入；正文从第二行起。
+    文件不存在 → 返回 None（逐文件独立回退）。
+    """
+    fp = os.path.join(spec_dir, rel)
+    if not os.path.isfile(fp):
+        return None
+    with open(fp) as f:
+        lines = f.read().splitlines()
+    return "\n".join(lines[1:]).strip("\n")
+
+
+def _join_model_ref(provider, model_id):
+    """按 pi 契约把 (provider, model_id) 拼成完整 model ref。
+
+    契约（pi 源码 resolveSpawnContext）：PI_PROVIDER=provider、
+    PI_MODEL=model id；session 的 model_change 同样分 provider/modelId
+    两字段；settings 的 defaultModel/defaultProvider 同构。**model id 本身
+    可含 '/'**（聚合类 provider 的命名空间 id，如 commandcode-goat 的
+    "deepseek/deepseek-v4-flash"）——因此拼接是**无条件**的字段拼接，
+    不得按"是否含斜杠"猜形状（形状启发式会把 provider 丢掉，解析到
+    同名的另一个 provider，静默失真；2026-09-10 实测 fix）。
+
+    provider 缺失时只能原样返回（无法拼接）——这是调用方应保证的前置。
+    """
+    provider = (provider or "").strip()
+    model_id = (model_id or "").strip()
+    if not model_id:
+        return ""
+    if not provider:
+        return model_id
+    return f"{provider}/{model_id}"
+
+
+def _default_model():
+    """本机默认模型（如 opencode-go/deepseek-v4-flash）。
+
+    从 pi settings.json 读取 defaultProvider/defaultModel，按契约拼接
+    （_join_model_ref——defaultModel 同样可能是含 '/' 的 id）。
+    无默认模型配置 → 返回 None（pi-agent.json 不写 model，回退 pi 默认）。
+    获取失败（pi 不可用/无 settings）→ 返回 None。
+    """
+    try:
+        with open(os.path.join(PI_AGENT_DIR, "settings.json")) as f:
+            cfg = json.load(f)
+        provider = cfg.get("defaultProvider") or ""
+        model = cfg.get("defaultModel") or ""
+        if not model:
+            return None
+        return _join_model_ref(provider, model) or None
+    except (OSError, ValueError):
+        return None
+
+
+def _detect_pi_model_thinking():
+    """探测主 pi 当前 model/thinking（spec models.md 预填，对齐 wrapper 旧语义）。
+
+    顺序：PI_MODEL/PI_PROVIDER/PI_REASONING_LEVEL 环境变量（wrapper 由主 pi
+    bash 注入）→ session 文件最后 model_change/thinking_level_change 事件
+    （PI_SESSION_FILE 或 cwd 编码目录最新 jsonl）→ settings 默认（_default_model）。
+    返回 (model, thinking)——缺失项为空串。
+    """
+    model = os.environ.get("PI_MODEL") or ""
+    provider = os.environ.get("PI_PROVIDER") or ""
+    thinking = os.environ.get("PI_REASONING_LEVEL") or ""
+    # 契约拼接（不按形状猜——id 可含 '/'，见 _join_model_ref）
+    model = _join_model_ref(provider, model)
+    if model and thinking:
+        return model, thinking
+    # session 文件兜底（查找规则单点：current_session_file）
+    try:
+        sf = current_session_file()
+        if sf:
+            sm = st = sp = ""
+            with open(sf, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        ev = json.loads(line)
+                    except ValueError:
+                        continue
+                    t = ev.get("type")
+                    if t == "model_change":
+                        sm = ev.get("modelId") or sm
+                        sp = ev.get("provider") or sp
+                    elif t == "thinking_level_change":
+                        st = ev.get("thinkingLevel") or st
+            if not model and sm:
+                # model_change 是 provider + modelId 两字段——同样按契约拼接
+                model = _join_model_ref(sp, sm)
+            if not thinking and st:
+                thinking = st
+    except OSError:
+        pass
+    if not model:
+        model = _default_model() or ""
+    return model, thinking
+
+
+def _spec_models(spec_dir, participants):
+    """解析 models.md（容错，用户 8024/9204 定）：返回 {agent: (model, variant)}。
+
+    每行格式：`agent名: model, variant`（model 与 variant 逗号分隔）。
+    - model 缺省/'default' → None（创建时填本机默认模型）
+    - variant 缺省/'default'/'max' → 'max'（默认档，专业用户才改）
+    容错：空行/无 ':'/agent 不在 participants → 跳过；单字段行只有 model。
+    规则：第一行说明跳过（_spec_read）。
+    """
+    if spec_dir is None:
+        return {}
+    content = _spec_read(spec_dir, "models.md")
+    if content is None:
+        return {}
+    out = {}
+    for line in content.splitlines():
+        line = line.strip()
+        if not line or ":" not in line:
+            continue
+        agent, _, rest = line.partition(":")
+        agent = agent.strip()
+        if agent not in participants:
+            continue
+        # 逗号分隔：model, variant（variant 可缺省）
+        parts = [p.strip() for p in rest.split(",")]
+        model = parts[0] if parts and parts[0] else ""
+        variant = parts[1] if len(parts) > 1 else ""
+        m = None if (not model or model == "default") else model
+        v = "max" if (not variant or variant == "default") else variant
+        out[agent] = (m, v)
+    return out
+
+
+def _strip_empty_sections(question):
+    """去掉 question.md 中未填的可选节（打磨项 2026-09-01 讨论结论）。
+
+    模板生成的可选节（## 初始立场 / ## 待回答的问题）如果用户没编辑，
+    节内只有占位符行（"- X: 立场" / "- 问题"）——注入前整节去掉，
+    避免占位符混入讨论环境。判据精确：占位符是确定字符串，用户真实
+    内容不会写成 "- X: 立场"（立场值就是"立场"二字）。
+    """
+    placeholder = re.compile(r"^-\s+(\w+:)?\s*立场$|^-\s+问题$")
+    out = []
+    pending_title = None  # 当前节的标题（占位符节连标题一起删）
+    cur = []  # 当前节内容行
+    cur_is_placeholder = True
+
+    def flush():
+        if not cur_is_placeholder:
+            if pending_title is not None:
+                out.append(pending_title)
+            out.extend(cur)
+
+    for line in question.splitlines():
+        if line.startswith("## "):
+            flush()
+            pending_title = line
+            cur = []
+            cur_is_placeholder = True
+        elif line.strip() == "":
+            cur.append(line)
+        else:
+            cur.append(line)
+            if not placeholder.match(line):
+                cur_is_placeholder = False
+    flush()
+    return "\n".join(out)
+
+
+def gen_spec_skeleton(spec_dir, participants, topic=None, background=None,
+                      viewers_dir=None):
+    """生成 spec 骨架（--spec-gen，唯一实现）：question.md + background.md +
+    models.md + agents/。
+
+    agents/ 三态：viewers_dir 给定 → _snapshot_viewers（校验+快照，失败
+    返回 (None, err)、零产物）；显式 participants → 占位骨架；两者皆无 →
+    无 agents/（start 报错提示）。
+    topic/background: wrapper --prepare 传入（直接填进骨架）；CLI 直用
+      时缺省 = 占位文案。
+    models.md 预填主 pi 当前 model/thinking（_detect_pi_model_thinking，
+    对齐旧 wrapper read_pi_model_thinking 语义——用户少改一个文件）。
+    每个文件第一行 = 用途说明（不注入，设计 16.4）。
+    """
+    if viewers_dir:
+        participants, err = _snapshot_viewers(spec_dir, viewers_dir)
+        if err:
+            return None, err
+    # spec 目录本身无条件创建（2026-09-09 回归修复：agents 创建并入条件
+    # 分支后，viewers 骨架曾连 spec_dir 都不建 → README copy 崩）
+    os.makedirs(spec_dir, exist_ok=True)
+    # agents/ 占位骨架仅显式 --agents 时生成（viewers 快照路径已建好并
+    # 含内容——不能被占位覆盖；两者皆无 = viewers 发现留给启动时点）
+    if participants and not viewers_dir:
+        os.makedirs(os.path.join(spec_dir, "agents"), exist_ok=True)
+    # README.md：从模板复制（内容不变——模板化，用户 7909）
+    shutil.copyfile(os.path.join(TPL_DIR, "spec-readme.md.tpl"),
+                    os.path.join(spec_dir, "README.md"))
+    # question.md：第一行说明 + 基本结构模板（用户 7713：提供基本结构）
+    q = [
+        "# question.md——分析起点（话题/立场/待答问题，自由 markdown）。本行是说明行，不会注入。",
+        "",
+        f"# 分析主题：{topic or "请填写"}",
+        "",
+        "## 初始立场（可选，每参与者一行）",
+    ]
+    q += [f"- {p}: 立场" for p in participants]
+    q += ["", "## 待回答的问题（可选）", "- 问题", ""]
+    with open(os.path.join(spec_dir, "question.md"), "w") as f:
+        f.write("\n".join(q))
+    # background.md（第一行说明 + 正文；用户 7707：文件可以是空的）
+    with open(os.path.join(spec_dir, "background.md"), "w") as f:
+        f.write("# background.md——显式边界与约定（注入每个 work 的 AGENTS.md 背景节）。"
+                "本行是说明行，不会注入。\n\n")
+        if background:
+            f.write(background + "\n")
+    # models.md（用户 8024/9204/9271：预列各 agent，每行 agent名: model，
+    # variant 默认 max 隐式——只有非 max 才写 `, variant`，日常更简洁；
+    # model/thinking 预填主 pi 当前值，用户少改一个文件）
+    pm, pt = _detect_pi_model_thinking()
+    with open(os.path.join(spec_dir, "models.md"), "w") as f:
+        lines = ["# models.md——模型配置（可选）。每行：agent名: model[, variant]。"
+                 "model 默认 default，variant 默认 max（只有不用 max 才写 variant）。"
+                 "本行是说明行，不会注入。"]
+        for p in participants:
+            if pm and pt:
+                lines.append(f"{p}: {pm}, {pt}")
+            elif pm:
+                lines.append(f"{p}: {pm}")
+            elif pt:
+                lines.append(f"{p}: default, {pt}")
+            else:
+                lines.append(f"{p}: default")
+        f.write("\n".join(lines) + "\n")
+    # agents/X.md 占位 + .order（仅显式 --agents 时；快照路径的 .order
+    # 由 _snapshot_viewers 写入，此处不得重写）
+    if participants and not viewers_dir:
+        for p in participants:
+            with open(os.path.join(spec_dir, "agents", f"{p}.md"), "w") as f:
+                f.write(f"# {p}.md——agent {p} 的分工/补充（追加到 agent {p} 定义正文）。"
+                        f"本行是说明行，不会注入。\n\n")
+        # .order：固化 --agents 顺序（审核#6——sorted() 推断破坏顺序语义，
+        # starter/默认 resultWriter/RR 轮转链依赖 participants 顺序）
+        with open(os.path.join(spec_dir, "agents", ".order"), "w") as f:
+            f.write("\n".join(participants) + "\n")
+    return participants, None
+
+
+def gen_agents_md(args, agent, participants, spec_background=None,
+                 main_pi_cwd=None):
+    """meeting 协议 AGENTS.md（共享协议 + background；身份/立场在 agent
+    定义/question.md）。
+
+    spec_background: spec 提供时优先（设计 16.6），否则 args.background，否则占位。
+    main_pi_cwd: 主 pi 工作目录（程序化注入，用户 2026-09-02）——直接进
+      AGENTS.md（注入 system prompt 的载体），不经 background.md 转接：
+      background.md 是人工编辑的讨论内容（用户审核 spec 时看），cwd 是
+      环境事实（程序化写入），分开保持各自干净。None（手动场景）→ 节隐藏。
+    """
+    others = [p for p in participants if p != agent]
+    sample = others[0] if others else "x"
+    background = (spec_background if spec_background is not None
+                  else (args.background or "（无）"))
+    with open(os.path.join(TPL_DIR, "AGENTS.md.tpl")) as f:
+        tpl = f.read()
+    # cwd 节：占位符填充（T5 修复，e2e7 评审）——原实现先 format 出
+    # "（未提供）"再整段字符串 replace 删除：模板文案/换行一改，隐藏
+    # 静默失效（模板与 python 双份文本耦合）。占位符方案：节文本单份
+    # 定义在此，模板位置显式可见；None → 空串（节消失）
+    if main_pi_cwd:
+        cwd_section = (
+            f"\n## 主 pi 工作目录\n\n分析环境的主 pi 在 `{main_pi_cwd}` "
+            f"目录运行。与该目录相关的信息\n（源码、文档、配置）可在其中"
+            f"查找：如有需要可查看相关文件以获取\n比本背景更详细的信息。\n")
+    else:
+        cwd_section = ""
+    out = tpl.format(
+        AGENT_NAME=agent,
+        N=str(len(participants)),
+        PARTICIPANTS_DISPLAY="、".join(participants),
+        SAMPLE_OTHER=sample,
+        BACKGROUND=background,
+        MAIN_PI_CWD_SECTION=cwd_section,
+    )
+    return out
+
+
+def gen_agent_def(agent, participants, models=None, stances=None, extra=None):
+    """agent prompt 文件（Pi 适配：纯 markdown，无 opencode frontmatter）。
+
+    Pi 没有 opencode agent 定义机制；每个 agent 的身份/分工通过
+    --append-system-prompt 注入。模型与 thinking 写进 pi-agent.json，
+    由 meeting_loop 启动时以 --model/--thinking 传入。
+    分层：**身份由本函数生成**（agent 名 = 文件名，单一来源）；视角内容
+    （lenses/边界/交锋义务）来自 spec/agents/X.md 或 viewers/X.md。
+    共享协议/背景在 AGENTS.md；话题/立场/问题在 question.md。
+    extra: 视角任务书正文——追加在"你的视角任务书"标题之后。
+    （thinking/variant 由 pi-agent.json 承载，不在本函数定义中）
+    """
+    model_body = ""
+    if models and agent in models:
+        model_body = f"你使用模型 {models[agent]} 参与讨论。\n"
+    stance_ref = ("你的立场和观点见 question.md 与讨论中的发言。\n"
+                  if stances and agent in stances else "")
+    with open(os.path.join(TPL_DIR, "agent.md.tpl")) as f:
+        tpl = f.read()
+    result = (tpl
+              .replace("{AGENT_NAME}", agent)
+              .replace("{N}", str(len(participants)))
+              .replace("{PARTICIPANTS_DISPLAY}", "、".join(participants))
+              .replace("{MODEL_BODY}", model_body)
+              .replace("{STANCE_REF}", stance_ref))
+    if extra:
+        # 视角正文接在"## 你的视角任务书"标题下（本函数只管拼接，
+        # 身份与任务书的分界由模板定义）
+        result = result.rstrip() + "\n\n" + extra.strip() + "\n"
+    return result
+
+
+def gen_question(topic, stances, background, questions):
+    """question.md（讨论起点：话题 + 可选立场 + 待回答问题）。
+
+    分层（2026-08-09）：background 移到 AGENTS.md（共享，system prompt）；
+    立场保持在此（非强制、可被说服，不进 system prompt）。
+    """
+    lines = [f"# 讨论主题：{topic}", ""]
+    if stances:
+        lines += ["## 初始立场", "每个参与者有自己的初始立场（可被论据说服）：", ""]
+        for k, v in stances.items():
+            lines.append(f"- {k}: {v}")
+        lines += ["", "开场时请声明你的立场，然后参与讨论。"]
+    if questions:
+        lines += ["", "## 待回答的问题"] + [f"- {q}" for q in questions] + [""]
+    return "\n".join(lines)
+
+
+def gen_protocol(topic, participants, max_meeting, max_rr, pure=False,
+                 result_writer=None, stall_timeout=600,
+                 fork_source=None, fork_cwd=None,
+                 fork_mode=meeting_fs.DEFAULT_FORK_MODE):
+    """protocol.json（meeting 模式）。"""
+    rw = result_writer or participants[-1]
+    proto = {
+        "mode": "meeting",
+        "protocol_version": 2,
+        "topic": topic or "",
+        "participants": participants,
+        "resultWriter": rw,
+        "maxMeetingRounds": max_meeting,
+        "maxRRRounds": max_rr,
+        "stallTimeoutSeconds": stall_timeout,
+        "commitPolicy": "one-message-per-commit",
+    }
+    if pure:
+        proto["pure"] = True
+    if fork_source:
+        # fork 模式（多视角）：首唤挂载主 session + cwd=主项目
+        # forkMode 取值域与默认值的定义在 meeting_fs（FORK_MODES /
+        # DEFAULT_FORK_MODE，单一事实源）；此处只写入选定值
+        proto["forkSource"] = fork_source
+        proto["forkCwd"] = fork_cwd or os.getcwd()
+        proto["forkMode"] = fork_mode
+    return proto
+
+
+def _resolve_path(p):
+    """路径解析（review4 L10 抽取）：含路径符（/~.）→ 绝对路径；否则 cwd 下拼接。"""
+    if any(ch in p for ch in "/~."):
+        return os.path.abspath(os.path.expanduser(p))
+    return os.path.join(os.getcwd(), p)
+
+MAX_AGENT_NAME_LEN = 32
+
+
+def pi_sessions_dir(cwd):
+    """主 pi session 目录（编码约定单点，T7 收归 e2e7 评审）。
+
+    pi 的 session 目录编码 = "--" + 去首尾斜杠 + 内斜杠换 "-" + "--"
+    （/root/x → --root-x--；/tmp → --tmp--）。此前该约定在
+    _detect_pi_model_thinking 与 resolve_fork_source 两处字面量重复，
+    AGENTS.md 明言"编码错一根横线 = 静默解析不到"——风险点不应复制。
+    """
+    enc = "--" + cwd.strip("/").replace("/", "-") + "--"
+    return os.path.join(PI_AGENT_DIR, "sessions", enc)
+
+
+def current_session_file():
+    """当前主 pi 的 session 文件路径（解析不到 → 空串）。
+
+    **查找规则的唯一实现**（此前两处各写一遍：resolve_fork_source 按
+    PI_SESSION_ID 匹配文件名、_detect_pi_model_thinking 兜底取目录内
+    **字典序最后**——同一概念两套规则，兜底可能选到别的 session）。
+    规则：PI_SESSION_FILE（pi 直接给的路径，最精确）→ PI_SESSION_ID
+    匹配文件名 → 目录内字典序最后（都无法确认时只能如此，调用方自决
+    是否接受）。
+    """
+    sf = os.environ.get("PI_SESSION_FILE") or ""
+    if sf and os.path.isfile(sf):
+        return sf
+    sdir = pi_sessions_dir(os.getcwd())
+    try:
+        cands = sorted(f for f in os.listdir(sdir) if f.endswith(".jsonl"))
+    except OSError:
+        cands = []
+    if not cands:
+        return ""
+    sid = os.environ.get("PI_SESSION_ID") or ""
+    if sid:
+        hits = [f for f in cands if sid in f]
+        if hits:
+            return os.path.join(sdir, hits[-1])
+    return os.path.join(sdir, cands[-1])
+
+
+def check_agent_name(name):
+    """单个 agent/视角名合法性（T4 收归，e2e7 评审）：唯一实现。
+
+    规则（viewers 文件名即 agent 名 → 同一套规则两处来源）：
+    非空 / 无路径分隔符与空白 / ≤32 字符 / 非 human 保留名。
+    返回错误信息或 None。
+    """
+    if not name:
+        return "空名"
+    if re.search(r"[/\\\s]", name):
+        return "含路径分隔符或空白"
+    if len(name) > MAX_AGENT_NAME_LEN:
+        return f"超过 {MAX_AGENT_NAME_LEN} 字符"
+    if name == "human":
+        return "'human' 是保留名（human 插话通道），不可作为参与者"
+    return None
+
+
+def list_agent_md(d):
+    """列出目录下的 agent 定义文件名（去 `.md`、**排除隐藏文件**、排序）。
+
+    **列举规则的唯一实现**——viewers/ 与 spec/agents/ 两条来源共用。
+    为什么排除隐藏文件：`.draft.md` 之类会被当成参与者（名为 `.draft`，
+    点号不在名字规则的禁止集内）静默进入讨论。此前只有 viewers 分支
+    排除、spec/agents 的两处列举没排除（实测缺口）。
+    """
+    return sorted(f[:-3] for f in os.listdir(d)
+                  if f.endswith(".md") and not f.startswith("."))
+
+
+def validate_participants(participants):
+    """整组名字校验（**名字规则的唯一入口**）。返回错误或 None。
+
+    覆盖：非空 / 无路径分隔符与空白 / ≤32 / 非 human 保留名。
+    CLI（--agents）与 spec/viewers（文件名）三条来源路径都经此。
+    """
+    for p in participants:
+        err = check_agent_name(p)
+        if err:
+            return f"错误: 非法 agent 名（{err}）：{p}"
+    return None
+
+
+def viewer_set_error(names, empty, where="viewers/"):
+    """viewers 集合级校验（**唯一实现**）：空正文视角 + 至少 2 个。
+
+    where: 报错时指路的目录前缀（"viewers/" 或 "spec/agents/"）。
+    返回错误文本或 None。为什么单点：同一套规则曾在 prepare 快照路径与
+    spec 解析路径各写一遍，文案与检查项已经漂移（实测：非法名文案带不带
+    文件名后缀不一致、≥2 检查一处列参与者一处不列）。
+    """
+    if empty:
+        # 空视角 = 没有 lenses 的 agent：行为由模型自由发挥，多视角退化成
+        # "同名随机视角"——静默退化，与无静默铁律相悖（占位文件忘写是常见成因）
+        detail = "、".join(f"{where}{n}.md（{why}）" for n, why in empty)
+        return (f"错误: {detail}——视角任务书不能为空"
+                f"（写清该视角用什么 lenses 看分析对象）")
+    if len(names) < 2:
+        return (f"错误: {where} 下仅发现 {len(names)} 个视角"
+                f"（{', '.join(names)}）——多视角分析至少需要 2 个")
+    return None
+
+
+def _discover_viewers(viewers_dir):
+    """发现 viewers 目录（多视角产品约定）：*.md 文件名即 agent 名。
+
+    返回 (participants, briefs, errors)——participants 按文件名排序（决定
+    starter/RR 轮转与默认 resultWriter）；briefs = {agent: 视角任务书正文}；
+    errors = [(name, 原因)]（空/纯空白视角——这类视角无 lenses，会让多视角
+    退化成同名随机视角，属静默退化，必须报错而非放行）。
+    目录不存在/无文件 → (None, None, [])（调用方决定报错或回退）。
+    """
+    if not os.path.isdir(viewers_dir):
+        return None, None, []
+    names = list_agent_md(viewers_dir)
+    if not names:
+        return None, None, []
+    briefs, errors = {}, []
+    for n in names:
+        with open(os.path.join(viewers_dir, f"{n}.md"), encoding="utf-8") as f:
+            brief = f.read().strip("\n")
+        if not brief.strip():
+            errors.append((n, "空视角任务书（没有任何视角内容）"))
+            continue
+        briefs[n] = brief
+    return names, briefs, errors
+
+
+def resolve_fork_source():
+    """从主 pi 环境（PI_SESSION_ID）解析当前 session 文件绝对路径
+    （fork-only 启动必需，2026-09-09 从 wrapper 收归——session 文件发现
+    逻辑与 _detect_pi_model_thinking 同款路径约定）。
+
+    sessions 目录编码 = "--" + 去首尾斜杠内斜杠换 "-" + "--"。
+    返回 (fork_source 或 None, error)——PI_SESSION_ID 未注入/文件缺失
+    都是明确错误（fork-only 无静默退化）。
+    """
+    sid = os.environ.get("PI_SESSION_ID") or ""
+    if not sid:
+        return None, ("错误: PI_SESSION_ID 未注入——多视角分析必须在主 pi "
+                      "session 内经 wrapper 启动。若确实在 session 内，"
+                      "检查是否有扩展接管了 bash 工具（如 AFT 的 "
+                      "`~/.config/cortexkit/aft.jsonc` 未设 \"bash\": false）"
+                      "——接管后 pi 的环境变量不会传入 bash")
+    # 委托 current_session_file（查找规则单点）；这里只管错误语义
+    path = current_session_file()
+    if not path or sid not in os.path.basename(path):
+        sdir = pi_sessions_dir(os.getcwd())
+        enc = os.path.basename(sdir)
+        return None, (f"错误: 未找到主 session 文件（{enc}/*_{sid}.jsonl）"
+                      "——fork-only 模式必须挂载主 session")
+    return path, None
+
+
+def _snapshot_viewers(spec_dir, viewers_dir):
+    """viewers 校验（prepare 时点）+ 快照进 spec/agents/（单一事实源：
+    所有视角都源自 viewers/，spec agents/ = 本场快照，可按场修改，
+    分析结束 spec 即删、资产永续；用户 2026-09-09 设计）。
+
+    校验（任何违规 → 返回错误，不产生任何 spec 文件——用户：不合规
+    根本不应该开始 spec-gen）：目录存在 / ≥2 个合法 .md（排除隐藏）/
+    无 human / 名字合法（空白/路径分隔符/≤32）。
+    快照文件含说明行首行（spec 约定：_spec_read 跳过首行——裸拷贝会
+    把正文首行当说明吃掉，实测缺口）。
+    返回 (participants, error)。
+    """
+    names, _briefs, empty = _discover_viewers(viewers_dir)
+    if names is None:
+        return None, ("错误: 未找到 viewers/ 目录——多视角分析的视角资产"
+                      "必须先建好（项目 cwd 下 viewers/<视角名>.md，至少 2 个）")
+    err = validate_participants(names) or viewer_set_error(names, empty)
+    if err:
+        return None, err
+    agents_dir = os.path.join(spec_dir, "agents")
+    os.makedirs(agents_dir, exist_ok=True)
+    for n in names:
+        with open(os.path.join(viewers_dir, f"{n}.md")) as f:
+            brief = f.read()
+        with open(os.path.join(agents_dir, f"{n}.md"), "w") as f:
+            f.write(f"# {n}.md——快照自 viewers/{n}.md（本行说明不注入；"
+                    f"按场修改这里，不影响 viewers/ 资产）\n\n")
+            f.write(brief)
+    with open(os.path.join(agents_dir, ".order"), "w") as f:
+        f.write("\n".join(names) + "\n")
+    return names, None
+
+
+def _resolve_spec(spec, agents, topic, background, stances, questions, models,
+                  viewers_dir=None):
+    """--spec 模式解析（审核#5 抽成可测函数）：互斥校验 + spec 目录 +
+    participants 推断 + question.md 必填。
+
+    participants 来源优先级：spec/agents/（显式自定义，含 .order）>
+    viewers_dir 发现（项目稳定视角，*.md 文件名即 agent 名）> 错误。
+    返回 (spec_dir, participants, viewer_briefs, error)——error 非 None 时
+    前两者为 None；viewer_briefs = {agent: 视角正文}（viewers 模式非空）。
+    """
+    if not spec:
+        return None, None, None, None
+    # 明确互斥（用户 7782）：内容/参与者参数二选一，不留"忽略/优先"中间态
+    # （审核#18→review4 M2）：--agents 默认 None——显式传（任何值，含 a,b）
+    # 一律报互斥，消除默认值字符串比较的漏报/误报
+    conflicting = []
+    if agents is not None:
+        conflicting.append("--agents")
+    if topic:
+        conflicting.append("--topic")
+    if background:
+        conflicting.append("--background")
+    if stances:
+        conflicting.append("--stances")
+    if questions:
+        conflicting.append("--questions")
+    if models:
+        conflicting.append("--models")
+    if conflicting:
+        return None, None, None, (
+            f"错误: --spec 与 {', '.join(conflicting)} 互斥——"
+            f"内容要么全在 spec，要么全在命令行")
+    # spec 目录解析（相对 → cwd 下，L10 抽取）
+    spec_dir = _resolve_path(spec)
+    if not os.path.isdir(spec_dir):
+        return None, None, None, f"错误: spec 目录不存在 {spec_dir}"
+    agents_dir = os.path.join(spec_dir, "agents")
+    viewer_briefs = {}
+    if os.path.isdir(agents_dir):
+        # participants 从 spec/agents/ 推断（无 --agents，避免冲突）
+        # 顺序：agents/.order 固化 --agents 顺序（审核#6），未列出的 .md 按
+        # 字母序追加（用户增删 agent 自然处理）；无 .order 回退 sorted
+        order_file = os.path.join(agents_dir, ".order")
+        if os.path.isfile(order_file):
+            with open(order_file) as f:
+                order = [l.strip() for l in f.read().splitlines() if l.strip()]
+            listed = [p for p in order
+                      if os.path.isfile(os.path.join(agents_dir, f"{p}.md"))]
+            listed_set = set(listed)
+            extra = sorted(n for n in list_agent_md(agents_dir)
+                           if n not in listed_set)
+            participants = listed + extra
+        else:
+            participants = list_agent_md(agents_dir)
+        if not participants:
+            return None, None, None, "错误: spec/agents/ 下没有 agent 定义文件"
+    else:
+        # viewers 发现（多视角产品约定）：cwd/viewers/*.md，文件名即 agent 名
+        participants, viewer_briefs, empty = _discover_viewers(viewers_dir)
+        if participants is None:
+            return None, None, None, (
+                "错误: spec 缺少 agents/ 且未找到 viewers/ 目录"
+                "（项目 cwd 下建 viewers/<视角名>.md，或 --spec-gen --agents 生成）")
+        # 集合级校验（空正文 / ≥2）——名字规则由 main 的中心闸门统一把
+        # （同一实现；此处只管 viewers 特有的集合级规则）
+        err = viewer_set_error(participants, empty)
+        if err:
+            return None, None, None, err
+    # spec 必须有 question.md（讨论起点不可缺）
+    if not os.path.isfile(os.path.join(spec_dir, "question.md")):
+        return None, None, None, "错误: spec 缺少 question.md（讨论起点，先 --spec-gen 生成）"
+    # 空正文校验（审核#19）：删到只剩说明行 → 无讨论主题（CLI 路径有
+    # --topic 必填对等约束）
+    if not (_spec_read(spec_dir, "question.md") or "").strip():
+        return None, None, None, "错误: spec 的 question.md 正文为空（讨论起点不可缺）"
+    return spec_dir, participants, viewer_briefs, None
+
+
+def _clone_work(base, p):
+    """clone work-<p> + 配置 git 身份 + 建本地目录（T6 后唯一 clone 入口）。
+
+    git 身份在此统一配置（调用方不再重复 config——e2e7 评审 T6）。
+    """
+    workdir = os.path.join(base, f"work-{p}")
+    run_cmd(["git", "clone", meeting_fs.bare_of_base(base), workdir])
+    run_cmd(["git", "config", "user.name", GIT_USER], cwd=workdir)
+    run_cmd(["git", "config", "user.email", GIT_EMAIL], cwd=workdir)
+    for sub in [".pi/agent", p]:   # L9：只建自己的目录（读走 bare，写有 makedirs 兜底）
+        os.makedirs(os.path.join(workdir, sub), exist_ok=True)
+    return workdir
+
+
+def setup_environment(args, participants, base, spec_dir=None,
+                      viewer_briefs=None):
+    """生成讨论环境（bare + clones + 配置 + setup commit + 重建）。
+
+    spec_dir: 讨论规格目录（设计 16）——内容优先：question.md →
+    question.md、background.md → AGENTS.md 背景节、agents/X.md → agent 定义
+    正文。逐文件独立回退（缺哪个走 CLI/占位）。
+    viewer_briefs: viewers 发现的视角任务书 {agent: 正文}（2026-09-09）——
+    优先级低于 spec/agents/（显式自定义胜出），作为 agent 定义正文。
+    """
+    # spec 内容预读（跳过首行说明）
+    spec_question = _spec_read(spec_dir, "question.md") if spec_dir else None
+    if spec_question is not None:
+        # 未填的可选节（占位符）去掉，避免注入混入模板内容（打磨项 2026-09-01）
+        spec_question = _strip_empty_sections(spec_question)
+        # topic 固化（e2e7 评审 W——此前 spec 主路径 protocol.json.topic
+        # 恒空串：gen_protocol(args.topic=None) 碰巧工作因 AGENTS.md 不
+        # 消费 topic，但 protocol 是单一事实源，空串是撒谎）。提取
+        # question.md 的 "# 分析主题：" 行；无可辨识主题行 → fail-fast
+        # （与 _snapshot_viewers 的"不合规零产物"同哲学）
+    spec_topic = None
+    if spec_question is not None:
+        for line in spec_question.splitlines():
+            # 兼容两种措辞（make_spec fixture 用旧版"讨论主题"）
+            for prefix in ("# 分析主题：", "# 讨论主题："):
+                if line.startswith(prefix):
+                    spec_topic = line.replace(prefix, "").strip()
+                    break
+            if spec_topic:
+                break
+    if spec_dir and not spec_topic:
+        raise ValueError(
+            f"错误: spec 的 question.md 缺少 '# 分析主题：' 行（无法固化 "
+            f"protocol.topic）——补主题行后重试")
+    spec_background = _spec_read(spec_dir, "background.md") if spec_dir else None
+    spec_agents = {}
+    if spec_dir:
+        for p in participants:
+            c = _spec_read(spec_dir, f"agents/{p}.md")
+            if c is not None:
+                spec_agents[p] = c
+    # viewers briefs：spec/agents/ 优先（显式自定义胜出），否则 viewers 正文
+    agent_extra = {p: (spec_agents.get(p) or (viewer_briefs or {}).get(p))
+                   for p in participants}
+    agent_extra = {k: v for k, v in agent_extra.items() if v}
+    # models：spec 模式从 models.md 读（自包含，{agent: (model, variant)}），
+    # CLI --models 已互斥（{agent: model} 旧格式——variant 用默认 max）
+    if spec_dir:
+        models = _spec_models(spec_dir, participants)
+    else:
+        models = {p: (m, "max") for p, m in (args.models or {}).items()}
+    # default 模型 → 创建时实时获取 Pi 默认模型填入：
+    # pi-agent.json 带 model 后，meeting_loop 才会传 --model；
+    # 骨架期 models.md 仍写 default（--spec-gen 不获取），创建时（--spec）
+    # 才解析。运行期固化不变（环境自包含）。
+    if spec_dir:
+        dm = _default_model()
+        if dm:
+            for p in participants:
+                if p not in models or models[p][0] is None:
+                    models[p] = (dm, models.get(p, (None, "max"))[1])
+    # stance_ref（agent 定义"立场见 question.md"提示）：spec 模式一律保留
+    # （设计 16.6：无法程序判断 question.md 有无立场节 → 一律提示；
+    # 互斥下 CLI stances 必为 None，传占位 dict 触发生成）
+    stances_arg = (args.stances if not spec_dir
+                   else {p: "" for p in participants})
+
+    os.makedirs(base, exist_ok=True)
+    run_cmd(["git", "init", "--bare", meeting_fs.bare_of_base(base)])
+
+    # T6 重构（e2e7 评审）：原流程 = 全部 clone → 写共享 → commit → 再
+    # rmtree+clone 重建 others + 回写本地文件（2N-1 次 clone，~40% 冗余；
+    # "保存→删→克隆→回写"是为绕开未跟踪文件冲突的补丁）。新流程：
+    # 先 clone work-a 提交共享配置，再 clone others（一次拿到 setup
+    # commit）——clone 恰 N 次，无重建、无回写、无重复 git config。
+    wa = os.path.join(base, f"work-{participants[0]}")
+    if os.path.exists(wa):
+        shutil.rmtree(wa)
+    _clone_work(base, participants[0])   # clone + git 身份 + 建目录
+
+    # 共享配置（work-a 提交，setup commit 进 bare）
+    with open(os.path.join(wa, "protocol.json"), "w") as f:
+        json.dump(gen_protocol(spec_topic or args.topic, participants, args.max_meeting,
+                               args.max_rr, args.pure, args.result_writer,
+                               args.stall_timeout,
+                               fork_source=getattr(args, "fork_source", None),
+                               fork_cwd=os.getcwd(),
+                               fork_mode=getattr(args, "fork_mode", meeting_fs.DEFAULT_FORK_MODE)),
+                  f, indent=2, ensure_ascii=False)
+    with open(os.path.join(wa, "question.md"), "w") as f:
+        if spec_question is not None:
+            # spec 提供 → 整文件（跳过首行）作为 question.md（设计 16.6）
+            f.write(spec_question + "\n")
+        else:
+            f.write(gen_question(args.topic, args.stances, args.background,
+                                 args.questions))
+    with open(os.path.join(TPL_DIR, "gitignore.tpl")) as gtf:
+        gitignore = gtf.read()
+    with open(os.path.join(wa, ".gitignore"), "w") as f:
+        f.write(gitignore)
+    run_cmd(["git", "add", "-A"], cwd=wa)
+    run_cmd(["git", "-c", f"user.name={GIT_USER}", "-c", f"user.email={GIT_EMAIL}",
+         "commit", "-m", "discuss: setup"], cwd=wa)
+    # push 当前分支（不用硬编码 master——用户可能配置了
+    # init.defaultBranch=main，硬编码会导致 bare 双分支、clone 检出空
+    # 分支 → 环境损坏。审核 C2。）
+    branch = run_cmd(["git", "branch", "--show-current"], cwd=wa,
+                 check=False).stdout.strip()
+    run_cmd(["git", "push", meeting_fs.bare_of_base(base),
+         branch or "master"], cwd=wa)
+
+    # others clone（直接拿到 setup commit；work-a 已在上方创建）
+    for p in participants[1:]:
+        workdir = os.path.join(base, f"work-{p}")
+        if os.path.exists(workdir):
+            shutil.rmtree(workdir)
+        _clone_work(base, p)   # clone + git 身份 + 建目录
+
+    # 本地配置（每个 work 各自；.gitignore 已随 setup commit 分发）
+    for p in participants:
+        workdir = os.path.join(base, f"work-{p}")
+        with open(os.path.join(workdir, "AGENTS.md"), "w") as f:
+            f.write(gen_agents_md(args, p, participants, spec_background,
+                                 main_pi_cwd=os.getcwd()))
+        mv = models.get(p, (None, "max"))
+        with open(os.path.join(workdir, ".pi/agent", f"{p}.md"), "w") as f:
+            f.write(gen_agent_def(p, participants, {p: mv[0]} if mv[0] else None,
+                                  stances_arg, agent_extra.get(p)))
+        with open(os.path.join(workdir, "pi-agent.json"), "w") as f:
+            json.dump({
+                "model": mv[0] or "",
+                "thinking": mv[1] if mv[1] else "max",
+                "prompt_file": f".pi/agent/{p}.md",
+            }, f, indent=2, ensure_ascii=False)
+
+    # work-human：human 插话的提交通道（helper 设计 §5.4）——
+    # 固定存在、不占参与者名额、无 agent 定义/pi-agent.json/AGENTS.md
+    # （human 无 LLM 身份），不启动 loop 进程。
+    # **必须在重建循环之外独立创建**（循环内会每迭代 clone 一次 →
+    # 第二个参与者起 already exists，实测暴露）；rmtree 守卫幂等。
+    wh = os.path.join(base, "work-human")
+    if os.path.exists(wh):
+        shutil.rmtree(wh)
+    _clone_work(base, "human")
+
+    # 复制 meeting_loop.py + 依赖模块（脚本同目录，自包含）
+    for mod in ["meeting_loop.py", "meeting_fs.py", "meeting_core.py",
+                "meeting_engine.py"]:
+        shutil.copy(os.path.join(HERE, mod), os.path.join(base, mod))
+    rw = args.result_writer or participants[-1]
+    print(f"[setup] 环境就绪: {base}（{len(participants)} agents: {', '.join(participants)}）")
+    print(f"[setup] resultWriter={rw}, maxMeeting={args.max_meeting}, maxRR={args.max_rr}, "
+          f"立场={'有' if (args.stances or spec_dir) else '无'}, pure={args.pure}")
+
+
+def _preserve_result_md(base):
+    """清理前保存 result.md（薄包装 → meeting_fs.preserve_result_md，
+    T2 合并：与 loop 退出路径共享同一实现）。"""
+    dest = meeting_fs.preserve_result_md(base)
+    if dest:
+        print(f"[cleanup] 已保存 result.md → {dest}")
+
+
+def cleanup_discussion(base):
+    """清理一次讨论：保存 result.md（若存在）→ 删目录。
+
+    result.md 是讨论唯一产物（审核报告等）——清理前先从 bare git 历史
+    复制到父级目录（<base名>-result.md），避免清理丢产物（用户建议）。
+    Pi 的 session 文件存放在 <base>/pi-sessions，随目录一起删除，无需
+    额外清理全局 DB。
+    不负责终止 loop 进程（职责边界，用户 2026-08-31 定）——loop 每轮
+    检测到 repo.git 消失即自行退出（meeting_engine.agent_loop）。
+    """
+    if not os.path.isdir(base):
+        print(f"[cleanup] 目录不存在: {base}")
+        return
+    _preserve_result_md(base)
+    # 报告（**删目录前最后一次可读**——目录删后 --report 不可用）。
+    # 报告是附加信息、清理是主职责：报告生成失败**不阻断**清理
+    # （fail-open 只在这一层兜底——build_report 内部各段已各自 fail-open）。
+    print("[cleanup] —— 本次分析报告（删除目录前最后一次可读）——")
+    try:
+        for line in build_report(base):
+            print(line)
+    except Exception as e:                       # noqa: BLE001（兜底不吞：打印）
+        print(f"[cleanup] 报告生成失败（不影响清理）: {e!r}")
+    shutil.rmtree(base)
+    print(f"[cleanup] 已删除目录 {base}（含 pi-sessions）")
+
+
+def _loop_pids(base):
+    """本讨论存活的 loop PID 列表。
+
+    **判据 = argv 精确相等，不是命令行文本正则**（2026-09-10 评审 A2）：
+    `pgrep -f <正则>` 会匹配到**任何**命令行里含该文本的进程——从 shell
+    包装调用时（`bash -c "...pgrep -f 'meeting_loop.py.*<base>'..."`）会命中
+    调用者自身，误判"有 loop 存活"。项目已固化该教训（docs/test-methodology.md
+    方法 2：方括号技巧或精确 PID），此处用 /proc 的 argv 逐项比较根治：
+    只看 argv 里是否有**恰好等于** `os.path.join(base, "meeting_loop.py")`
+    的元素——与启动方（Popen cmd 的第一个参数）同一构造。
+    附带：/proc 扫描 ≈1.1ms vs pgrep ≈5.9ms（不构成选型理由，理由是判据精度）。
+
+    读不到 /proc（非 Linux/权限）→ 返回空列表（fail-open：与"无 loop"同义，
+    只影响状态显示，不影响流程——loop 自身不依赖此函数）。
+    """
+    target = os.path.join(base, "meeting_loop.py")
+    pids = []
+    for entry in glob.glob("/proc/[0-9]*/cmdline"):
+        try:
+            with open(entry, "rb") as f:
+                argv = f.read().decode("utf-8", "replace").split("\0")
+        except OSError:
+            continue
+        if target in argv:
+            pids.append(entry.split("/")[2])
+    return pids
+
+
+def _loops_alive(base):
+    """讨论的 loop 进程是否存活（argv 精确匹配，见 _loop_pids）。"""
+    return bool(_loop_pids(base))
+
+
+def check_status(base):
+    """讨论状态（单值；状态全集显式于此，T3/#7 修复 e2e7 评审）：
+
+      not-exists   无 bare（目录不存在/未创建）
+      done         result.md + concluded（权威收尾完成）
+      running      有 loop 存活（讨论中 / 收尾中——收尾中细分见下）
+      stalled      有 result.md 无 concluded 且 **loop 均不存活**
+                   （收尾中断：rw 崩溃在 result.md 之后、concluded 之前）
+      stopped      无 result.md 且 loop 不存活（未启动/中断）
+
+    修复动因（e2e7 评审 T3）：原实现"有 result.md 无 concluded"恒返回
+    running 且不看存活 → "收尾进行中"与"收尾间隙崩溃"不可区分，--wait
+    无限轮询（无终止上界）。现 stalled 使 --wait 有界退出。
+    移除恒 None 第二返回值（#7 装饰性契约）——信息由状态本身表达。
+    """
+    bare = meeting_fs.bare_of_base(base)
+    if not os.path.isdir(bare):
+        return "not-exists"
+    # 读路径统一走 fs.run_git（quotepath 加固单点；run_cmd 只做一次性
+    # 环境命令——init/clone/config/push）
+    # 读路径统一走 fs.run_git（quotepath 加固单点；run_cmd 只做一次性
+    # 环境命令——init/clone/config/push）
+    agents = meeting_fs.read_protocol(bare).get("participants", [])
+    # "收尾完成"判据**单源** = human_viewer.is_finished（concluded 且
+    # HEAD:result.md 有效）——与 viewer 的 done 同一判据（§3.5-P5：此前
+    # viewer 认 concluded、这里还额外认 result.md 存在，分叉会让 viewer
+    # 在产物落盘前先报"已结束"并打印尚不存在的路径）。
+    # 不用 git grep 全文：行文本匹配会被 result.md/消息正文里的
+    # `type: concluded` 误触发（实测）；human 消息天然排除（aggregate_mode
+    # 只按 participants 取末条）。
+    if human_viewer.is_finished(bare, agents):
+        return "done"
+    # 未完成：有 result.md 但未收尾 → 看 loop 存活区分收尾中/收尾中断
+    r = meeting_fs.run_git(bare, "log", "--all", "--format=%H", "--",
+                           "result.md", check=False)
+    if r.stdout.strip():
+        return "running" if _loops_alive(base) else "stalled"
+    return "running" if _loops_alive(base) else "stopped"
+
+
+def _parse_agents(agents_arg):
+    """--agents 解析（唯一实现，2026-09-09 从 wrapper 收归）：
+    None → []；纯数字 n → a..（第 n 个字母）；逗号分隔 → 名称列表
+    （去空白、滤空段）。数字下限 2（meeting 至少两个 LLM agents）。
+    返回 (participants, error)。
+    """
+    if agents_arg is None:
+        return [], None
+    if agents_arg.isdigit():
+        n = int(agents_arg)
+        if n < 2:
+            return None, "错误: agents 数量至少为 2（meeting 至少两个 LLM agents）"
+        if n > 26:
+            return None, "错误: agents 数量最多 26（a..z）"
+        return [chr(97 + i) for i in range(n)], None
+    participants = [a.strip() for a in agents_arg.split(",") if a.strip()]
+    # 完整名字规则（非空/无空白与路径分隔符/非 human/≤32）——单实现。
+    # 此前只查 human，非法名（如 "a/b"）会一路走到 spec-gen 才炸：
+    # FileNotFoundError traceback + spec 半成品落盘（实测）
+    err = validate_participants(participants)
+    if err:
+        return None, err
+    return participants, None
+
+
+def wait_for_completion(base):
+    """`--wait`：阻塞展示进展直到收尾或终态。返回退出码（0 完成 / 1 终止）。
+
+    从 main 内联抽出（main 里最大单块；项目方法论把 main/CLI 分发
+    列为独立测试盲区）。**纯结构变换**：调用序列与 sleep 序列逐字
+    不变——helper 只做机械动作（状态判定 → 打印 → 增量展示 → sleep），
+    不吸收"何时进入分支"的阶段判断。
+
+    终止语义（四种终态，各有明确文案）：stalled / not-exists /
+    stopped（按 loop-*.log 分叉成因）/ done（含固定位 result.md 提示）。
+    """
+    # T1 收归（e2e7 评审）：进展展示复用 human_viewer.incremental
+    # （原内联 65 行自行 git log 全量 + 手工解析 frontmatter——与
+    # viewer 两套输出格式、非增量、概念丢失）。incremental 走
+    # since..HEAD 增量 + 统一 format_message。
+    import human_viewer
+    sys.stdout.reconfigure(line_buffering=True)
+    print(f"[wait] 等待讨论完成: {base}")
+    bare = meeting_fs.bare_of_base(base)
+    agents = human_viewer.participants_from_bare(bare) or []
+    since = ""   # 首次全量（--wait 一次性观察，无游标持久需求）
+    first = True
+    while True:
+        state = check_status(base)
+        if state == "stalled":
+            print("[wait] 收尾中断（result.md 已提交、concluded 缺失、"
+                  "无 loop 存活）——停止等待；可读 result.md 或 --cleanup")
+            return 1
+        if state == "not-exists":
+            print(f"[wait] 讨论不存在: {base}")
+            return 1
+        if state == "stopped":
+            # 终态：无 result.md 且无 loop 存活。
+            #
+            # **不用 loop-*.log 存在性分叉成因**（§3.4-P4）：那是拿日志当
+            # 判定输入（唯一实例，与"日志零判定输入"不变量冲突），且两个
+            # 分支给出的动作此前都不可执行（`--start` 对已存在目录报"请先
+            # --cleanup"；裸 `--start <base>` 又因缺 question.md 失败）。
+            # 合并为一条动作完整的提示——真正可执行的是 `--skip-setup
+            # --start`（环境不完整则先 --cleanup 重建）。
+            print(f"[wait] 未在运行且未收尾（{base}：无 loop 存活、无 "
+                  "result.md）——查 loop-*.log / status-*.json 判断原因；"
+                  "重跑：--skip-setup --start（protocol 缺失则先 --cleanup "
+                  "后重建）")
+            return 1
+        _mode, lines, head, done = human_viewer.incremental(
+            bare, agents, since)
+        if done:
+            for line in lines:
+                print(line)
+                print()
+            print("[wait] 讨论完成 ✅")
+            # 固定位（与 prompt 收尾指引一致）：resultWriter 的 loop
+            # 退出时保存、cleanup 兜底再存一次——调用方无需推 rw 是谁
+            print(f"[wait] result.md: {base}-result.md")
+            return 0
+        for line in lines:
+            print(f"[wait] {time.strftime('%H:%M:%S')} 新进展:")
+            print(line)
+            print()
+        since = head or since
+        if first:
+            first = False
+        # 观察刷新节奏（消费端常量——与 loop 的空闲重试节奏有意独立，
+        # 见 human_viewer.OBSERVER_POLL_INTERVAL 注释）。原硬编码 10s
+        # 会让结束观察延迟最长 10s（e2e13 时间流分析：唯一 >10s 的
+        # 非必要等待点）。
+        time.sleep(human_viewer.OBSERVER_POLL_INTERVAL)
+
+
+def build_report(base):
+    """只读报告（`--report`）——观测面的**唯一机器消费出口**。
+
+    契约（design.md 观测面契约节）：
+    - **冷路径一次性**：不常驻、不被轮询；调用方（人/主 pi）按需触发。
+    - **不持久化**：视图不占"数字的家"——数字的家是 bare（判定域）、
+      loop log 的登记字段、pi session 的文档化字段；报告只是它们的一次投影。
+    - **fail-open**：任何一段读不出（缺目录/缺文件/格式变）→ 该段显示 n/a，
+      不报错、不改判定、不阻塞。
+    - **跨度分标**：进程跨度（elapsed_ms）≠ per-response 跨度（session
+      时间戳差）≠ 墙钟跨度（commit 时间差）——各自标名，不混算。
+    - **不得升级为验收 gate**：有效期判断留给人 + result.md（本轮 §4 明确
+      不做运行期评分）。
+
+    返回输出行列表（调用方 print）。
+    """
+    out = []
+    out.append(f"[报告] {base}")
+    bare = meeting_fs.bare_of_base(base)
+    if not os.path.isdir(bare):
+        out.append("  分析目录不存在（已 cleanup？）——n/a")
+        return out
+    agents = meeting_fs.read_protocol(bare).get("participants", [])
+    if not agents:
+        out.append("  协议不可读（participants 空）——n/a")
+        return out
+    proto = meeting_fs.read_protocol(bare)
+
+    # ---- 流程时间线（bare = 判定域，现场派生） ----
+    r = meeting_fs.run_git(bare, "log", "--reverse", "--format=%ct%x09%s",
+                           "HEAD", check=False)
+    rows = []
+    for line in r.stdout.splitlines():
+        if "\t" not in line:
+            continue
+        ts, subj = line.split("\t", 1)
+        rows.append((int(ts), subj))
+    per_agent = {a: 0 for a in agents}
+    human_n = 0
+    for _, subj in rows:
+        m = re.match(r"discuss:\s*(.+?)/(\d+)$", subj)
+        if not m:
+            continue
+        who = m.group(1)
+        if who == "human" or who not in per_agent:
+            human_n += 1
+        else:
+            per_agent[who] += 1
+    if rows:
+        span = rows[-1][0] - rows[0][0]
+        out.append(f"流程：{len(agents)} agents | 提交 "
+                   f"{sum(per_agent.values())}（含流程信号；"
+                   + " / ".join(f"{a} {n}" for a, n in per_agent.items())
+                   + f"）| 墙钟跨度 {_dur(span)}（首末 commit 差）")
+    # 最长无进展间隔（相邻 commit 间隔的最大值）
+    gaps = [(rows[i + 1][0] - rows[i][0], rows[i][0], rows[i + 1][0])
+            for i in range(len(rows) - 1)]
+    if gaps:
+        g, t1, t2 = max(gaps)
+        out.append(f"节奏：最长无进展 interval {_dur(g)}"
+                   f"（{_hhmm(t1)} → {_hhmm(t2)}，commit 间隔）")
+
+    # ---- 配额与 human 插话（bare 派生，无状态） ----
+    # **配额消耗从 frontmatter 统计**（mode==meeting 且 type==message），
+    # 不是"该 agent 的消息总数"——上限约束的是 meeting 发言轮次，而一个
+    # agent 的消息里还有 freezing/all-freezing/pass/concluded 等流程信号。
+    # 两者混算会出现"meeting 6/2"这种超限假象（口径错误，2026-09-11 实测）。
+    msgs = meeting_engine.each_agent_messages(bare, agents)
+    lasts = {a: (msgs[a][-1] if msgs[a] else None) for a in agents}
+    types = {a: (lasts[a].get("type") if lasts[a] else None) for a in agents}
+    quota_meeting = proto.get("maxMeetingRounds", 10)
+    quota_rr = proto.get("maxRRRounds", 7)
+    out.append("配额：meeting " + "、".join(
+        f"{a} {meeting_core.meeting_speak_count(msgs, a)}/{quota_meeting}"
+        for a in agents)
+        + f"（消耗/上限，口径 = mode:meeting 且 type:message）"
+        f"| RR 上限 {quota_rr}/agent | human 插话 {human_n} 条"
+        "（不占配额；各 agent 上限 +human 条数）")
+    frozen = meeting_core.frozen_agents(agents, types)
+    not_frozen = [a for a in agents if a not in frozen]
+    out.append(f"冻结：{len(frozen)}/{len(agents)} 已冻结"
+               + (f"（{'、'.join(frozen)}）" if frozen else "")
+               + (f"；未冻结 {'、'.join(not_frozen)}" if not_frozen else ""))
+    # aggregate_mode 期望 {agent: {type, mode}}（core 判定入口形态）——
+    # 用 `.get` 规范化：消息缺字段（老产物/手工 fixture）时按 None 处理，
+    # 不得 KeyError（报告契约：读不出 → 降级，不崩）
+    mode_now = meeting_core.aggregate_mode(
+        {a: ({"type": fm.get("type"), "mode": fm.get("mode")} if fm else None)
+         for a, fm in lasts.items()})
+    if mode_now == "round-robin":
+        out.append(f"RR：轮到 "
+                   f"{meeting_engine.rr_next_speaker(bare, agents) or '（未定）'}")
+    else:
+        out.append(f"阶段：{mode_now}")
+    # 标题与口径：一次读取派生的三样观测面（配额进度 / 冻结集合 / RR 位置）
+
+    # ---- 进程事实（登记字段；日志的唯一机器消费点） ----
+    proc = _report_wake_fields(base)
+    out.append("进程（loop log 登记字段）：")
+    if not proc:
+        out.append("  n/a（无完成行——尚未唤醒或日志缺失）")
+    for a in agents:
+        d = proc.get(a)
+        if not d:
+            out.append(f"  {a}: n/a")
+            continue
+        out.append(f"  {a}: 唤醒 {d['wakes']} 次 | 进程跨度 总 "
+                   f"{_dur(d['total_ms'] // 1000)} / 最大 "
+                   f"{_dur(d['max_ms'] // 1000)} | rc≠0 {d['fails']} 次")
+
+    # ---- LLM 运行事实（session 文档化字段；流式预过滤，不整文件解析） ----
+    out.append("LLM（session 文档化字段）：")
+    any_usage = False
+    for a in agents:
+        u = _report_session_usage(base, a)
+        if not u:
+            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']} 次")
+    if not any_usage:
+        out.append("  n/a（session 缺失，或无本轮数据——边界条目自 2026-09-11 "
+                   "起写入，此前的老分析不适用）」")
+    out.append("（口径：进程跨度=pi 进程生命周期；输出=prompt 分段合计；"
+               "墙钟=commit 时间差——三者不可互替）")
+    return out
+
+
+def _dur(sec):
+    """人类可读时长（口径由调用方在同一行标注——进程跨度/墙钟/间隔）。"""
+    sec = int(sec)
+    if sec < 60:
+        return f"{sec}s"
+    if sec < 3600:
+        return f"{sec // 60}m{sec % 60:02d}s"
+    return f"{sec // 3600}h{(sec % 3600) // 60:02d}m"
+
+
+def _hhmm(ts):
+    return time.strftime("%H:%M:%S", time.localtime(ts))
+
+
+def _report_wake_fields(base):
+    """解析 loop-*.log 的登记字段（`elapsed_ms` / `rc`）。
+
+    **日志的唯一机器消费点**（观测面契约：日志零判定输入，报告只读已登记
+    字段——不解析自由文本、不做启发式猜测）。fail-open：读不到 → 跳过。
+    """
+    out = {}
+    for f in sorted(glob.glob(os.path.join(base, "loop-*.log"))):
+        agent = os.path.basename(f)[len("loop-"):-len(".log")]
+        d = {"wakes": 0, "total_ms": 0, "max_ms": 0, "fails": 0}
+        try:
+            with open(f, encoding="utf-8", errors="replace") as fh:
+                for line in fh:
+                    m = re.search(r"elapsed_ms=(\d+) rc=(-?\d+)", line)
+                    if not m:
+                        continue
+                    d["wakes"] += 1
+                    ms, rc = int(m.group(1)), int(m.group(2))
+                    d["total_ms"] += ms
+                    d["max_ms"] = max(d["max_ms"], ms)
+                    if rc != 0:
+                        d["fails"] += 1
+        except OSError:
+            continue
+        if d["wakes"]:
+            out[agent] = d
+    return out
+
+
+def _report_session_usage(base, agent):
+    """从该 agent 的 session 文件取 usage（**单一适配器** + 流式预过滤）。
+
+    字段来源 = pi 的**文档化** session schema（`docs/session-format.md`：
+    `usage` / `stopReason`）。行级预过滤（`"usage" in line` 才 json.loads）
+    ——避免对 MB 级文件整解析（实测 json.loads 3MB ≈27ms，预过滤可省大部分）。
+    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):
+        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}
+    for ev in meeting_fs.iter_after_boundary(fp):
+        m = ev.get("message") or {}
+        if m.get("role") != "assistant":
+            continue
+        u["responses"] += 1
+        if m.get("stopReason") == "error":
+            u["errors"] += 1
+        usage = m.get("usage") or {}
+        for k, key in (("input", "input"), ("cacheRead", "cache_read"),
+                       ("output", "output")):
+            v = usage.get(k)
+            if isinstance(v, int):
+                u[key] += v
+    if not u["responses"]:
+        return {}
+    # 数字格式化（人读）：千分位缩写
+    for k in ("input", "cache_read", "output"):
+        u[k] = _num(u[k])
+    return u
+
+
+def _num(n):
+    """人可读数字（k/M 缩写；原值精度对人读报告无意义）。"""
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}M"
+    if n >= 1_000:
+        return f"{n / 1_000:.1f}k"
+    return str(n)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Meeting 模式讨论环境")
+    parser.add_argument("--dir",
+                        help="讨论运行目录（创建/启动/清理/状态/等待用；--spec-gen 不需要）")
+    parser.add_argument("--agents", default=None,
+                        help="参与者（逗号分隔，默认 a,b；--spec 时不可传）")
+    parser.add_argument("--topic", default=None, help="讨论主题（--skip-setup 时不需要）")
+    parser.add_argument("--stances", default=None, help='JSON: {"a": "立场"}')
+    parser.add_argument("--background", default=None, help="背景说明")
+    parser.add_argument("--questions", default=None, help="待回答问题（|分隔，对齐 RR）")
+    parser.add_argument("--models", default=None, help='JSON: {"a": "provider/model"}')
+    parser.add_argument("--result-writer", default=None, help="resultWriter（默认最后一位参与者）")
+    parser.add_argument("--max-meeting", type=int, default=10, help="meeting 阶段发言配额（每 agent）")
+    parser.add_argument("--max-rr", type=int, default=7, help="RR 阶段轮次配额（starter）")
+    parser.add_argument("--stall-timeout", type=int, default=600,
+                        help="无进展超时兜底（秒，默认 600；防 provider API 慢）")
+    parser.add_argument("--spec-gen", metavar="DIR", default=None,
+                        help="生成 spec 骨架到 DIR（如 --spec-gen myspec/；不需 --dir）")
+    parser.add_argument("--spec", default=None,
+                        help="讨论规格目录（内容源：question/background/agents，优先于 CLI 内容参数）")
+    parser.add_argument("--fork-mode", default=meeting_fs.DEFAULT_FORK_MODE,
+                        choices=list(meeting_fs.FORK_MODES),
+                        help="fork 裁剪策略：budget=预算+折叠（默认，长会话可行）；"
+                             "compaction=按 compaction 边界（中小会话零损失）；"
+                             "full=全量（小会话/验证）")
+    parser.add_argument("--fork-source", default=None,
+                        help="主 session 文件绝对路径（fork-only）：写入 "
+                             "protocol.json，各 agent 首唤由本地生成 fork "
+                             "源挂载主上下文；不传 = 从主 pi 环境自动解析"
+                             "（PI_SESSION_ID；解析失败明确报错）")
+    parser.add_argument("--pure", action="store_true", help="--pure 模式（禁外部插件）")
+    parser.add_argument("--start", action="store_true", help="创建后启动讨论")
+    parser.add_argument("--skip-setup", action="store_true",
+                        help="跳过环境生成，只启动已有环境（需 --dir）")
+    parser.add_argument("--cleanup", action="store_true", help="清理讨论（目录，含 pi-sessions）")
+    parser.add_argument("--status", action="store_true", help="检查讨论状态")
+    parser.add_argument("--report", action="store_true",
+                        help="只读报告（观测面聚合：流程/配额/进程/LLM；"
+                             "冷路径一次性，不持久化）")
+    parser.add_argument("--wait", action="store_true", help="阻塞直到讨论完成")
+    args = parser.parse_args()
+
+    participants, agents_err = _parse_agents(args.agents)
+    if agents_err:
+        print(agents_err)
+        sys.exit(1)
+    try:
+        args.stances = json.loads(args.stances) if args.stances else None
+        args.models = json.loads(args.models) if args.models else None
+    except ValueError as e:
+        print(f"错误: JSON 参数解析失败: {e}（--stances/--models 需合法 JSON）")
+        sys.exit(1)
+    args.questions = args.questions.split("|") if args.questions else None
+
+    # --spec-gen 直接带目录位置参数（--spec-gen myspec/，不需 --dir/--spec）
+    if args.spec_gen:
+        # agents/ 三态（2026-09-09）：显式 --agents = 占位骨架（覆盖路径）；
+        # 缺省 = viewers 快照（校验前移——不合规零产物）；python 单一事实源，
+        # bash --prepare 与 CLI 直用产出一致
+        spec_dir = _resolve_path(args.spec_gen)   # L10
+        viewers_dir = (os.path.join(os.getcwd(), "viewers")
+                       if not participants else None)
+        participants, err = gen_spec_skeleton(
+            spec_dir, participants, topic=args.topic,
+            background=args.background, viewers_dir=viewers_dir)
+        if err:
+            print(err)
+            sys.exit(1)
+        print(f"[spec-gen] 已生成骨架: {spec_dir}")
+        return
+
+    # 其他模式必须 --dir（讨论运行目录）
+    if not args.dir:
+        print("错误: 需要 --dir（讨论运行目录；--spec-gen 不需要）")
+        sys.exit(1)
+    # --dir 语义分场景（2026-09-03 修正）：
+    # 创建模式（--dir 裸名 + 非消费标志）：快捷命名 → cwd/discussion-<name>
+    # 消费模式（--cleanup/--status/--wait/--skip-setup，操作已存在目录）：
+    #   裸名按字面解释（cwd 下同名目录），存在就用不存在报错——前缀快捷
+    #   只属于创建；操作时套用会找错目录（实测 cleanup 裸名潜伏 bug）
+    consuming = (args.cleanup or args.status or args.wait or args.skip_setup
+                 or args.report)
+    if any(ch in args.dir for ch in "/~."):
+        base = os.path.abspath(os.path.expanduser(args.dir))
+    elif consuming:
+        base = os.path.join(os.getcwd(), args.dir)
+    else:
+        base = os.path.join(os.getcwd(), f"discussion-{args.dir}")
+
+    if args.cleanup:
+        cleanup_discussion(base)
+        return
+    if args.status:
+        print(f"[status] {check_status(base)}")
+        return
+    if args.report:
+        for line in build_report(base):
+            print(line)
+        return
+    if args.wait:
+        return wait_for_completion(base)
+    # 创建（--start 总是 setup；--skip-setup = 跳过创建，只启动已有环境）
+    if args.skip_setup:
+        if not os.path.exists(base):
+            print(f"错误: 环境不存在 {base}")
+            sys.exit(1)
+        print(f"[start] 跳过环境生成——只启动已有环境")
+        # 参与者从已有环境的 protocol.json 读（单一事实源 = bare HEAD，
+        # 不依赖 CLI；读不到 → 明确报错，不静默）
+        participants = meeting_fs.read_protocol(
+            meeting_fs.bare_of_base(base)).get("participants", [])
+        if not participants:
+            print("[error] 无法读取已有环境 protocol.json")
+            sys.exit(1)
+    else:
+        # review5 A8：创建前检测 base 已存在——git init --bare 幂等不删
+        # 旧对象，重复 --dir 会复用旧 bare（旧 concluded 污染新讨论）。
+        # 提示先 --cleanup（或手动删目录）。
+        if os.path.exists(base):
+            print(f"错误: 讨论目录已存在 {base}（请先 --cleanup 或删除，"
+                  f"避免旧 bare 污染）")
+            sys.exit(1)
+        # 创建分支（--spec 提供内容源时 spec 优先，设计 16.5）
+        spec_dir = None
+        viewer_briefs = {}
+        if args.spec:
+            # 互斥校验 + spec 目录解析 + participants 推断 + question.md 必填
+            # （审核#5：抽成 _resolve_spec 可测函数）
+            spec_dir, parts, viewer_briefs, err = _resolve_spec(
+                args.spec, args.agents, args.topic, args.background,
+                args.stances, args.questions, args.models,
+                viewers_dir=os.path.join(os.getcwd(), "viewers"))
+            if err:
+                print(err)
+                sys.exit(1)
+            participants = parts
+        # 非 spec：--agents 未传 → 默认 a,b（M2：argparse 默认 None）
+        if not args.spec and not participants:
+            participants = ["a", "b"]
+        # agent 名校验 + 非空校验（审核#20：--agents "," 全空）
+        # 2026-09-09 放宽：viewers 模式下文件名即 agent 名（中文人物名/
+        # 视角名合法）——非法 = 空名/路径分隔符/空白/human 保留名/>32 字符
+        if not participants:
+            print("错误: 参与者为空（--agents 或 spec/agents/ 无有效 agent）")
+            sys.exit(1)
+        # 名字合法性（T4 收归：唯一实现 check_agent_name/validate_participants，
+        # 含 human 保留名）
+        err = validate_participants(participants)
+        if err:
+            print(err)
+            sys.exit(1)
+        # resultWriter 必须 ∈ participants（spec 推断或 CLI 的 participants）
+        if args.result_writer and args.result_writer not in participants:
+            print(f"错误: resultWriter {args.result_writer} 不在参与者 {participants} 中")
+            sys.exit(1)
+        # fork-only（2026-09-09 定）：创建必须携带主 session 文件——无
+        # fork 上下文的多视角分析违背产品本质，明确报错而非静默退化。
+        # --fork-source 未显式传 → 从主 pi 环境（PI_SESSION_ID）自动解析
+        # （收归 python：与 models 探测同款路径约定）
+        if not args.fork_source:
+            args.fork_source, fork_err = resolve_fork_source()
+            if fork_err:
+                print(fork_err)
+                sys.exit(1)
+        # 无 spec 时创建必须给 --topic（否则是无效的 --start 单独用）
+        if not args.spec and not args.topic:
+            print("错误: 需要 --topic（或使用 --skip-setup 启动已有环境）")
+            sys.exit(1)
+        setup_environment(args, participants, base, spec_dir,
+                          viewer_briefs=viewer_briefs)
+    if args.start:
+        # 启动每个 agent 的 meeting_loop（独立进程，git 触发）
+        procs = []
+        for p in participants:
+            workdir = os.path.join(base, f"work-{p}")
+            cmd = [sys.executable, os.path.join(base, "meeting_loop.py"),
+                   workdir, p]
+            if args.pure:
+                cmd.append("--pure")
+            # 配额（max-meeting/max-rr/stall-timeout）是环境属性：创建时
+            # 固化在 protocol.json，启动继承（loop 读 protocol 优先）。
+            # 不传 CLI —— 避免无条件覆盖 protocol.json 的固化值
+            # （审核 C1：配额单一事实源；与 pure 处理一致）
+            with open(os.path.join(base, f"loop-{p}.log"), "w") as f:
+                procs.append(subprocess.Popen(cmd, stdout=f,
+                                              stderr=subprocess.STDOUT,
+                                              start_new_session=True))
+        print(f"[start] 已拉起 {len(procs)} 个进程"
+              f"（存活未校验；loop 状态见 status-*.json 与 {base}/loop-*.log）")
+
+
+if __name__ == "__main__":
+    # 传递 main 返回码（--wait 超时返回 1——此前被丢弃，wrapper 判据失效）
+    sys.exit(main() or 0)