opencode-agora 0.1.0__py3-none-any.whl

agorad/core/gate.py

@@ -0,0 +1,281 @@
+"""verify 门与自动合并：任务环境验收→集成环境试合并/验收→目标支最终推进。
+
+done 受理仍执行状态、verify、commit 格式与评审锚前置校验。门体先在任务 env 跑
+verify，再在目标分支当前 HEAD 的 detached integration worktree 内 ff-only 试合并
+并重跑 verify；只有全绿且目标主检出两次干净检查通过，才推进真实目标分支。集成
+失败不再依赖 reset --hard 回滚，用户未提交工作与目标分支均不受测试副作用影响。
+
+默认 runner 以独立进程组执行命令，超时杀全组并返回 124，避免单个挂死验证永久
+堵住串行门。崩溃重排先探测目标支是否已含任务 commit：已含说明上轮最终推进已
+完成，只补 merged/closed 终态，不重验后假 reopened。gate_env 与 target_branch 的
+原始分支位随任务快照持久化，集成环境和分支位均可跨重启收敛。
+
+全程 in-gate 门闩、pending-cancel 门尾原子结算、三连败 blocked 与事件审计保持
+不变。core 只 import stdlib，依赖全构造注入。
+"""
+import os
+import signal
+import subprocess
+import time
+from pathlib import Path
+
+# 升级 kind 与 health 的类别词汇对齐（core 禁 import 兄弟模块，字面量本地定义）
+KIND_QUALITY = "quality"
+KIND_GATEFILES = "gatefiles"
+
+_TAIL = 2000
+# 闸体＝verify 依赖面（构建/测试配置）：任务 diff 触及即升级拍人
+_GATE_PATTERNS = ("Makefile", "*.mk", "pyproject.toml", "setup.py", "setup.cfg",
+                  "requirements*.txt", "package.json", "package-lock.json",
+                  "go.mod", "Cargo.toml", "tox.ini", "noxfile.py",
+                  ".github/workflows/*")
+
+
+def _subprocess_runner(env_dir, cmd, timeout=300):
+    """真 runner：独立进程组跑 verify；超时杀全组，rc=124 按质量败处理。"""
+    proc = subprocess.Popen(cmd, shell=True, cwd=env_dir,
+                            stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                            text=True, start_new_session=True)
+    try:
+        out, err = proc.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(proc.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass  # 超时与正常退出竞速：进程组已消失即无需补杀
+        out, err = proc.communicate()
+        return 124, ((out or "") + (err or "") +
+                     f"\nverify 超时（>{timeout:g}s）——已终止验证进程组；"
+                     "可用 AGORA_VERIFY_TIMEOUT 调整上限")
+    return proc.returncode, (out or "") + (err or "")
+
+
+class Gate:
+    """accept_done 单写者串行受理；run 为后台线程体（httpd 包 Thread 调用）。"""
+
+    def __init__(self, state, gitx, router, oc, read_anchor, health, auth,
+                 store, runner=None, verify_timeout=300, on_blocked=None):
+        self._state, self._gitx, self._router, self._oc = state, gitx, router, oc
+        self._read_anchor, self._health, self._auth = read_anchor, health, auth
+        self._store, self._on_blocked = store, on_blocked
+        self._runner = runner or (lambda env, cmd: _subprocess_runner(
+            env, cmd, timeout=verify_timeout))
+
+    # ---- done 受理（前置六拒，拒收落审计并附动作指引） ----
+
+    def accept_done(self, tid, worker_sid, commit):
+        t = self._state.get(tid)
+        if t["state"] != "running":  # 含二次 done：防重入门
+            return self._deny_done(
+                tid, "state",
+                f"任务 {tid} 当前 {t['state']} 非 running——"
+                "board 查看状态，仅 running 受理 done")
+        if t["verify"]["state"] != "registered":
+            return self._deny_done(
+                tid, "verify-unregistered",
+                f"任务 {tid} verify 未登记——"
+                "post 通知派发方 task_update 登记 verify 命令，"
+                "登记后重新 post(done, commit)")
+        if not t["verify"]["cmd"].strip():  # 兜底：空命令＝无质量闸，拒入门
+            return self._deny_done(
+                tid, "verify-empty",
+                f"任务 {tid} verify 命令为空——"
+                "task_update 登记非空命令后重新 post(done, commit)")
+        c = commit.lower()
+        if len(c) != 40 or any(ch not in "0123456789abcdef" for ch in c):
+            return self._deny_done(  # F13：body-format 先行，参数错不再伪装成锚问题
+                tid, "body-format",
+                f"done body 须为纯 40 位十六进制完整 commit sha（收到 {commit[:20]!r}）"
+                "——无前缀无附言；结论文本另发 post(kind=note)")
+        commit = c  # 归一一次：锚比较与落库均用小写，大写 sha 不再伪装成锚问题（OCR）
+        children = [(cid, x) for cid, x in self._state.snapshot()["tasks"].items()
+                    if x.get("dispatcher_sid") == worker_sid]
+        open_children = [cid for cid, x in children
+                         if x["state"] not in ("merged", "closed", "cancelled")
+                         or str(x.get("cancel_reason", "")).startswith("dependency_failed")]
+        if open_children:
+            return self._deny_done(
+                tid, "children",
+                f"嵌套子任务未结案：{', '.join(sorted(open_children))}——"
+                "等待 result 回传，或由你取消子任务；成功/有意跳过后再 post(done)")
+        # 锚检查仅评审环在位时适用：缺失→放行 done，由门体 review_absent 分支驻留
+        if (Path(t["env_dir"]) / ".review-loop").is_dir():
+            a = self._read_anchor(t["env_dir"])  # 锚＝worktree 分支 HEAD 且无 blocker/high
+            if a is None:
+                return self._deny_done(
+                    tid, "anchor",
+                    f"任务 {tid} 评审环无锚或锚落后（.review-loop/.last-reviewed 缺失"
+                    "或不等于分支 HEAD）——跑 /review-loop 至锚绿，重新 post(done, commit)")
+            if a.get("head") != commit:
+                return self._deny_done(
+                    tid, "anchor",
+                    f"任务 {tid} {commit} ≠ 分支 HEAD {a.get('head')}——"
+                    "以 env 内完整 HEAD sha 重新 post(done, commit)")
+            if not a.get("clean"):
+                return self._deny_done(
+                    tid, "anchor",
+                    f"任务 {tid} 评审环未绿——修复 blocker/high 后"
+                    "重新 post(done, commit)")
+        self._state.transition(tid, "done", commit=commit)
+        self._audit(tid, "done", commit=commit)
+        return "accepted"
+
+    def _deny_done(self, tid, tag, msg):
+        """F13：done 拒收统一出口——先审计 done_rejected（note=tag）再带因拒回。"""
+        self._audit(tid, "done_rejected", note=tag)
+        return f"rejected:{tag}: {msg}"
+
+    # ---- 门体（后台线程体） ----
+
+    def run(self, tid):
+        t = self._state.get(tid)
+        branch = t.get("target_branch")  # 合入目标支（外部工作流）；缺省＝仓默认支
+        env, target, cmd = t["env_dir"], t["project_dir"], t["verify"]["cmd"]
+        integration = t.get("gate_env") or f"{env}__gate"
+        origin = t.get("gate_origin_branch")  # 崩溃重排沿用首轮分支位，不采信漂移后的现场
+        self._state.set_fields(tid, in_gate=True, gate_env=integration)
+        try:
+            # kill 落在“目标已推进、merged 未落库”窗口：任务提交已在目标支即只补终态，
+            # 绝不重跑集成 verify 后把已合法合并的任务假 reopened，更不需要 reset --hard。
+            if self._gitx.contains(target, t["commit"], branch):
+                self._succeed(tid)
+                return
+            self._gitx.ensure_clean(target)  # 主检出写前硬闸：用户未提交/未跟踪工作一律不碰
+            if branch:
+                origin = origin or self._gitx.symref(target)
+                self._state.set_fields(tid, gate_origin_branch=origin)
+            if self.gate_files_touched(tid):  # 闸体变更：拍人不拦门
+                self._health.escalate(KIND_GATEFILES, tid)
+            warn = self._gitx.diff_check(env, branch)  # 冲突标记机械检查，先于用户 verify
+            if warn:  # gt-83185d R3：非空走 verify_failed 口径（截 2000 与 verify 败一致）
+                self._quality_fail(tid, "verify_failed",
+                                   "diff 检查发现冲突标记/空白错误——清理后重新"
+                                   f" post(done, commit)\n输出尾部:\n{warn[-_TAIL:]}")
+                return
+            rc, out = self._runner(env, cmd)
+            if rc != 0:
+                self._quality_fail(tid, "verify_failed",
+                                   f"verify 失败——修复后重新 post(done, commit)"
+                                   f"\n输出尾部:\n{out[-_TAIL:]}")
+                return
+            a = self._read_anchor(env)  # 合并前锚重验：堵 accept→run 窗口 TOCTOU
+            if not a or a.get("head") != t.get("commit") or not a.get("clean"):
+                self._audit(tid, "review_absent_no_merge")
+                self._post(tid, "verify 绿但合并时 .review-loop 锚缺失/落后/未绿——"
+                                "任务驻留 done 待人工审阅合并（dispatcher 可 "
+                                "cancel 或人工 git 合并）")
+                return
+            # 集成阶段全部落在 detached worktree：试合并/测试失败都不会改目标主检出。
+            self._gitx.build_integration(target, integration, branch)
+            before = self._gitx.head(integration)
+            if self._gitx.merge_ff(env, integration) != "ok":
+                self._non_ff(tid, branch, before)
+                return
+            irc, iout = self._runner(integration, cmd)
+            if irc != 0:
+                self._quality_fail(tid, "reopened",
+                                   f"集成 verify 失败，目标分支未改动——修复后重新"
+                                   f" post(done, commit)\n输出尾部:\n{iout[-_TAIL:]}")
+                return
+            # 集成验证可能耗时较长，最终推进前复查，关闭“开始干净、结束时变脏”窗口。
+            self._gitx.ensure_clean(target)
+            if self._gitx.merge_ff(env, target, branch) != "ok":
+                self._non_ff(tid, branch, self._gitx.head(target, branch))
+                return
+            self._succeed(tid)
+        except Exception as e:  # 门内崩（checkout 拒/分支失/脏工作区）：转 reopened 通知
+            if self._state.get(tid)["state"] == "done":
+                self._state.transition(tid, "reopened")
+                self._audit(tid, "reopened")
+                self._post(tid, f"门内异常：{e}——处理目标分支后重新 post(done, commit)")
+            else:  # 终态后异常（如环境回收败）：不逆转门结果，但留痕＋实时提示派发方
+                self._audit(tid, "reclaim_failed", note=str(e)[:200])
+                t = self._state.get(tid)
+                self._router.post(t["worker_sid"], ("up", tid), "milestone",
+                                  f"环境回收失败：{e}——任务终态不变，残留目录需人工清理")
+        finally:
+            try:
+                self._gitx.remove_integration(integration, target)
+                self._state.set_fields(tid, gate_env=None)
+            except Exception as e:  # 回收失败不掩盖门结果；gate_env 保留供下轮/人工定位
+                self._audit(tid, "reclaim_failed", note=f"integration: {e}"[:200])
+            if origin:
+                if not self._gitx.checkout(target, origin):
+                    self._audit(tid, "restore_failed")  # 还原败留痕并保留原分支位供下轮复用
+                else:
+                    self._state.set_fields(tid, gate_origin_branch=None)
+            self._tail(tid)
+
+    def _succeed(self, tid):
+        """唯一成功出口：目标支已含任务 commit，补终态、审计与任务环境回收。"""
+        t = self._state.get(tid)
+        self._state.fail_streak_reset(tid)  # 全绿清连败（R12）
+        self._state.transition(tid, "merged", commit=t.get("commit"))
+        self._audit(tid, "merged", commit=t.get("commit"))
+        self._gitx.remove_env(t["env_dir"])
+        self._post(tid, f"merged @{t.get('commit')}——环境已回收")
+
+    def _non_ff(self, tid, branch, before):
+        """试合并或最终推进遇真 non-ff：重开不计质量连败，目标主检出保持不动。"""
+        t = self._state.get(tid)
+        # 窄竞态守卫：试合并窗口内 commit 已被人工推进目标支，则补终态成功，绝不重开
+        if self._gitx.contains(t["project_dir"], t.get("commit"), branch):
+            self._succeed(tid)
+            return
+        self._state.transition(tid, "reopened")
+        self._audit(tid, "reopened")
+        self._post(tid, f"non-ff 拒并："
+                        f"{branch or self._gitx.symref(t['project_dir'])}@{before}"
+                        f" vs branch@{self._gitx.head(t['env_dir'])}——同步后"
+                        "重新 post(done, commit)")
+
+    def gate_files_touched(self, tid):
+        t = self._state.get(tid)
+        return bool(t.get("env_dir")) and self._gitx.touches_gate(
+            t["env_dir"], _GATE_PATTERNS, t.get("target_branch"))
+
+    # ---- 内部 ----
+
+    def _quality_fail(self, tid, to, body):
+        """质量败（verify 败/集成败）：迁移＋审计＋实时回 worker＋计连败（3 连败拍人）。"""
+        self._state.transition(tid, to)
+        self._audit(tid, to)
+        self._post(tid, body)
+        self._state.fail_streak_bump(tid)
+        if self._state.get(tid)["state"] == "blocked":
+            self._audit(tid, "blocked")
+            self._health.escalate(KIND_QUALITY, tid)
+            self._router.notify_dispatcher(
+                tid, "result", f"任务 {tid} 已 blocked；请重派或取消")
+            if self._on_blocked is not None:
+                self._on_blocked(tid)
+
+    def _tail(self, tid):
+        """门走完：pending-cancel 经 State.gate_tail 原子结算（merged 不逆转历史）；副作用随终态。"""
+        t = self._state.gate_tail(tid)
+        if t["state"] == "cancelled":
+            self._audit(tid, "cancelled")
+            if t.get("env_dir"):  # 同 T7 直路径口径：cancelled 即环境回收
+                try:
+                    self._gitx.remove_env(t["env_dir"])
+                except Exception as e:  # 回收败留痕后继续：终止通知＋凭据作废不得被拦断
+                    self._audit(tid, "reclaim_failed", note=str(e)[:200])
+            if t.get("worker_sid"):  # 同 T7 直路径：终止通知＋凭据作废
+                self._router.post(t["dispatcher_sid"], ("down", tid), "cancel",
+                                  f"task {tid} cancelled at gate tail")
+                self._auth.revoke_session(t["worker_sid"])
+            self._router.notify_dispatcher(tid, "result", f"任务 {tid} 已取消")
+        elif t["state"] == "closed":
+            self._audit(tid, "closed")
+            self._router.notify_dispatcher(
+                tid, "result",
+                f"任务 {tid} 已 closed；commit={t.get('commit') or '-'}")
+
+    def _audit(self, tid, event, **extra):
+        """F8 门段审计：迁移即 events.jsonl 一行（事件名＝迁移后状态名）。"""
+        self._store.append_event({"ts": time.time(), "actor": "gate",
+                                  "event": event, "task": tid, **extra})
+
+    def _post(self, tid, body):
+        t = self._state.get(tid)
+        self._router.post(t["dispatcher_sid"], ("down", tid), "milestone", body)

agorad/core/health.py

@@ -0,0 +1,182 @@
+"""健康探活与升级拍人（F5，设计 §4.4）：定时探死＋边沿判僵、失控实时拍主会话。
+
+tick 只探活动任务的直接下级会话（无全局巡检）；死下级→recover.reinject 自愈
+（静默），失败→升级。父 worker 若正管着在飞链也优先重注入，并同步改绑嵌套
+子任务；只有无法重注入的失管 dispatcher 才直接拍人。
+worker 凭据自愈已推改拉（F25 修正）：inject_silent 推送通道证伪（v2.2.0
+synthetic 不触发 prompt 钩子），改由插件 hook 缓存未命中经 /cred_for_sid 拉取。
+边沿判僵（F5 决策记录 2026-10-28，只提醒不处置）：tick 顺带按 doctor 同口径
+（20min 无活动，report.stale_candidates 构造注入）算僵态候选，新进候选集→
+stalled 升级＋可选邮件（email.json opt-in）；离开候选集复位，oc 不可达轮次
+免判；"僵"的处置仍归人工。升级正文由服务权威合成；任务/worker 供给文本以
+"不可信原文"段携带（拍平换行，防伪造服务行）。escalate 沿 dispatcher_sid
+上行至根任务（根 dispatcher＝主会话 sid，R25-A 活绑定）经 router post——
+落库先行，注入即视为拍到（stalled 例外：synthetic 免通知通道，不弹窗）；
+escalate 同时落 events.jsonl 审计行（F8）。
+core 只 import stdlib，依赖全注入。
+"""
+import json
+import shlex
+import subprocess
+import time
+
+# 升级事件类别（R9 初始集；gate 的质量连败/闸体变更引用此收口）
+KIND_QUALITY = "quality"
+KIND_GATEFILES = "gatefiles"
+KIND_REINJECT = "reinject-fail"
+KIND_DISPATCHER_DEAD = "dispatcher-dead"
+KIND_STALLED = "stalled"
+
+_UNTRUSTED = "---- 不可信原文 ----"
+_RAW_MAX = 500
+# 活动面＝探活与 last_seen 的任务集（verify_failed/reopened 归在飞，同 task 口径）
+_ACTIVE = {"dispatched", "running", "done", "verify_failed", "reopened", "blocked"}
+_IN_FLIGHT = {"dispatched", "running"}  # 自愈重注入仅限 worker 在跑的两态
+
+_KIND_NOTE = {
+    KIND_QUALITY: "同一任务连续 3 次质量失败，已自动 blocked",
+    KIND_GATEFILES: "任务 diff 触及闸体（构建/测试配置）",
+    KIND_REINJECT: "下级会话死亡且重注入失败",
+    KIND_DISPATCHER_DEAD: "派发方会话死亡，其在飞子链失管",
+    KIND_STALLED: "在飞超 20min 无活动（僵态候选），请人工关注",
+}
+
+
+def _subprocess_runner(cmd, input_text):
+    """默认邮件外呼：正文走 stdin，30s 超时；非零退出/超时抛异常由调用方吞。"""
+    r = subprocess.run(cmd, input=input_text, text=True, timeout=30,
+                       capture_output=True)
+    if r.returncode:
+        raise subprocess.CalledProcessError(r.returncode, cmd)
+    return r
+
+
+class Health:
+    """tick 由 main 定时线程驱动；单写者口径（httpd 串行调用）。"""
+
+    def __init__(self, state, oc, router, recover, app, store,
+                 runner=None, stale_candidates=None):
+        """app 按引用注入：main_sid 是活绑定（R25-A），escalate 每次取当前值。
+
+        stale_candidates＝report.stale_candidates（core 禁兄弟 import，构造注入）；
+        runner＝邮件外呼缝（gate 同款），缺省真 subprocess。
+        """
+        self._state, self._oc, self._router = state, oc, router
+        self._recover, self._app = recover, app
+        self._store = store
+        self._runner = runner or _subprocess_runner
+        self._stale_candidates = stale_candidates
+        self._stale_seen = set()  # 僵态候选边沿记忆（内存态，崩溃回退＝重拍一次）
+
+    def tick(self):
+        """探每个活动任务的直接下跳：死→自愈/上报；边沿判僵只提醒不处置。"""
+        tasks = self._state.snapshot()["tasks"]
+        oc_down = False
+        busy = set()  # updated>idle＝回合进行中：僵态本轮免判（doctor 口径减 busy 免决）
+        for tid, t in tasks.items():
+            wsid = t.get("worker_sid")
+            if t["state"] not in _ACTIVE or not wsid:
+                continue
+            try:
+                data = self._oc.session(wsid)
+            except Exception:  # oc 不可达≠会话死：本轮免判（含僵态），勿误杀
+                oc_down = True
+                continue
+            if data is None:
+                manages = any(x.get("dispatcher_sid") == wsid
+                              and x["state"] in _IN_FLIGHT for x in tasks.values())
+                if t["state"] in _IN_FLIGHT:
+                    if self._recover.reinject(tid):
+                        continue  # 父 worker 一并恢复；recover 同步改绑嵌套子任务
+                    self.escalate(KIND_DISPATCHER_DEAD if manages else KIND_REINJECT, tid)
+                elif manages:
+                    self.escalate(KIND_DISPATCHER_DEAD, tid)
+            else:
+                tm = data.get("time") or {}  # 缺形状→不 busy→照判（安全回退）
+                if (tm.get("updated") or 0) > (tm.get("idle") or 0):
+                    busy.add(tid)
+        if not oc_down:
+            self._stale_scan(tasks, busy)
+
+    def _stale_scan(self, tasks, busy):
+        """边沿判僵（F5 决策记录 2026-10-28）：新进候选集→stalled 拍人。
+
+        免判口径（二批）：busy（updated>idle，回合进行中）本轮从候选集剔除；
+        离开 busy 再超阈重新边沿触发。_stale_seen 每轮同步为当前候选集
+        （离开即移除，之后再僵再拍）。
+        """
+        if self._stale_candidates is None:
+            return
+        cand = [(tid, b) for tid, b
+                in self._stale_candidates({"tasks": tasks}, time.time())
+                if tid not in busy]
+        for tid, _ in cand:
+            if tid not in self._stale_seen:  # 边沿：在候选集而不在记忆集
+                self.escalate(KIND_STALLED, tid)
+                self._stale_seen.add(tid)  # 拍到才记：escalate 失败下轮重试不丢报
+        self._stale_seen &= {tid for tid, _ in cand}  # 离开候选集即移除（复位再拍）
+
+    def _notify_email(self, tid, body_text):
+        """可选邮件外呼（F5 决策记录 2026-10-28，opt-in）：未配置＝零行为变化。
+
+        email.json 缺失/缺字段→静默跳过；失败/超时吞异常（邮件尽力而为），
+        成败各落一行审计事件。
+        """
+        try:
+            cfg = json.loads((self._store.home / ".agora" / "email.json")
+                             .read_text(encoding="utf-8"))
+            to, command = cfg["to"], cfg["command"]
+        except Exception:
+            return
+        try:
+            self._runner(shlex.split(command), body_text)
+            event = "email_sent"
+        except Exception:
+            event = "email_failed"
+        # shortcut: 逐任务同步外呼，批量同僵最坏 N×30s 阻塞 tick 线程；规模化再聚合单邮件
+        self._store.append_event({"ts": time.time(), "actor": "health",
+                                  "event": event, "task": tid, "to": to})
+
+    def touch(self, sid):
+        """last_seen 刷新入口：仅 worker 服务调用刷——dispatcher 查看≠worker
+        干活，查看不续命（二批决策；018676 真僵晚拍 40min 实证）。"""
+        for tid, t in self._state.snapshot()["tasks"].items():
+            if sid == t.get("worker_sid"):
+                self._state.touch_seen(tid)  # 心跳只进内存：快照仅随真实迁移追加
+
+    def escalate(self, kind, tid, raw=None):
+        """失控拍人：正文服务权威合成；raw 为任务/worker 供给文本（不可信）。
+
+        stalled 走免通知通道（synthetic，落转录不弹窗，gt-5bc312 用户裁定），
+        其余 kind 照常会话注入。"""
+        t = self._state.get(tid)
+        body = (f"失控[{kind}] 任务{tid}：{_KIND_NOTE[kind]}；"
+                f"状态 {t['state']}，worker={t.get('worker_sid') or '-'}，"
+                f"dispatcher={t.get('dispatcher_sid') or '-'}，"
+                f"连败 {t.get('fail_streak', 0)}")
+        if raw:
+            flat = " ".join(str(raw).split())  # 拍平换行：供给文本不得伪造服务合成行
+            body += f"\n{_UNTRUSTED}\n{flat[:_RAW_MAX]}"
+        root = self._root(tid)
+        rt = self._state.get(root)
+        self._store.append_event({"ts": time.time(), "actor": "health",
+                                  "event": "escalate", "task": tid, "kind": kind})
+        self._router.post(rt.get("worker_sid"), ("up", root), "escalate", body,
+                          silent=(kind == KIND_STALLED))  # stalled 免通知通道：不弹窗（gt-5bc312）
+        if kind == KIND_STALLED:  # 僵态邮件例外（§6 决策记录）：仅此 kind 外呼
+            self._notify_email(tid, body)
+
+    def _root(self, tid):
+        """沿 dispatcher_sid 上行至根任务（根 dispatcher＝主会话 sid，R25-A 活绑定）。"""
+        tasks = self._state.snapshot()["tasks"]
+        seen = set()
+        while (tid not in seen
+               and tasks.get(tid, {}).get("dispatcher_sid") != self._app.main_sid):
+            seen.add(tid)
+            parent = next((p for p, x in tasks.items()
+                           if x.get("worker_sid")
+                           == tasks[tid].get("dispatcher_sid")), None)
+            if parent is None:
+                break  # 链头不在册（main 缺位）——就地升级到已达的最上级
+            tid = parent
+        return tid

agorad/core/msg.py

@@ -0,0 +1,92 @@
+"""消息路由（F4，设计 §4.3）：链边寻址＋落库先行＋幂等补拉。
+
+post 是链上唯一投递路径（cancel 终止通知也走此）：先 write_message 落库
+（库在即不丢），后 inject 一次；inject 失败仅落库，对方 check_mail 补拉。
+已投递集为内存态，与 mail_read 游标（快照持久化）配合：进程内 inject 成功
+即不再补拉，重启后由持久化游标兜底——崩溃回退口径同 State。会话换号重绑定后，
+check_mail 沿牌血统补拉发往旧 sid 的离线消息，嵌套结果不因恢复而丢失。状态迁移
+不在此——post(kind) 只管投递，状态由调用方（gate/task）驱动。
+"""
+import time
+
+
+class NotChainEdge(Exception):
+    """寻址非链边：方向非法/任务缺席/对方未登记/from_sid 非任务另一方。"""
+
+
+class Router:
+    """单写者路由：无锁无线程，httpd 串行调用（设计 §4.8 并发口径）。"""
+
+    def __init__(self, store, state, oc, same_lineage=None):
+        self._store = store
+        self._state = state
+        self._oc = oc
+        self._same_lineage = same_lineage  # F16 血统判定（core 禁兄弟 import，装配注入）
+        self._delivered = set()
+
+    def is_dispatcher(self, sid, t):
+        """sid 是否本任务派发方：现 sid 相等，或血统含旧 dispatcher_sid
+        （F16 dispatcher 换号链边连续；血统判定缺失＝仅相等）。"""
+        d = t.get("dispatcher_sid")
+        return (sid == d
+                or (d is not None and self._same_lineage is not None
+                    and self._same_lineage(sid, d)))
+
+    def post(self, from_sid, to_edge: tuple, kind: str, body: str,
+             silent: bool = False) -> int:
+        to_sid = self._resolve(from_sid, to_edge)
+        return self._deliver(from_sid, to_sid, to_edge[1], kind, body, silent)
+
+    def notify_dispatcher(self, tid, kind, body):
+        """服务侧结果回传：子任务尚无 worker 链边时也能通知其父 dispatcher。"""
+        to_sid = self._state.get(tid).get("dispatcher_sid")
+        if to_sid is None:
+            raise NotChainEdge(f"{tid}: dispatcher 未登记")
+        return self._deliver("agorad", to_sid, tid, kind, body)
+
+    def _deliver(self, from_sid, to_sid, tid, kind, body, silent=False):
+        mid = self._store.write_message(  # 铁则：先落库后注入
+            {"ts": time.time(), "task": tid, "kind": kind,
+             "from": from_sid, "to": to_sid}, body)
+        text = f"[agora] task {tid} {kind} from {from_sid}\n{body}"
+        try:
+            # 取属性入 try：oc 缺 inject_silent 时同落兜底网（评审环 B 册）
+            ok = (self._oc.inject_silent if silent else self._oc.inject)(to_sid, text)
+        except Exception:  # oc 异常（凭据轮换 401/网络故障）同失败口径：落库兜底——
+            ok = False     # done 链路不得因投递面异常断裂（T7 e2e 实测：raise→门不排队）
+        if ok:
+            self._delivered.add(mid)  # 在线送达一次；失败留库待补拉
+        return mid
+
+    def dedup_key(self, msg_id: int) -> bool:
+        """已投递过返回 True（重发不再投递）；否则登记并返回 False。"""
+        if msg_id in self._delivered:
+            return True
+        self._delivered.add(msg_id)
+        return False
+
+    def check_mail(self, sid: str) -> list:
+        cursor = self._state.snapshot()["mail_read"].get(sid, 0.0)
+        got = [m for m in self._store.read_messages()
+               if (m["to"] == sid or (self._same_lineage is not None
+                                      and self._same_lineage(sid, m["to"])))
+               and m["id"] not in self._delivered and float(m["ts"]) > cursor]
+        self._state.touch_mail(sid)
+        self._delivered.update(m["id"] for m in got)  # 拉取即送达（无 ack）
+        return got
+
+    def _resolve(self, from_sid, to_edge) -> str:
+        d, tid = to_edge
+        try:
+            t = self._state.get(tid)
+        except KeyError:
+            raise NotChainEdge(f"{tid}: 任务不存在") from None
+        if d == "up":  # worker 边不加血统：recover 已覆写 worker_sid，无换号缺口
+            to_sid, ok = t.get("dispatcher_sid"), from_sid == t.get("worker_sid")
+        elif d == "down":
+            to_sid, ok = t.get("worker_sid"), self.is_dispatcher(from_sid, t)
+        else:
+            raise NotChainEdge(f"{to_edge}: 方向非法")
+        if to_sid is None or not ok:
+            raise NotChainEdge(f"{from_sid}->{to_edge}: 非链边")
+        return to_sid

agorad/core/peer.py

@@ -0,0 +1,90 @@
+"""同仓协作面（F22）：peer 留言板＋同仓在飞摘要。
+
+留言复用消息库（kind=peer，头带 repo/作者任务；to="" 保持消息库全员有 to
+的不变量——Router.check_mail 按 m["to"] 直取），无收件人＝不入任何信箱。
+分区＝project_dir（normpath 单点归一）；写面仅 worker 牌、作者任务＝
+worker_sid 命中行；四护栏：读只取最近 READ_N 条（噪音）、作者任务终态带
+is_stale（陈旧降权）、单任务软限 SOFT_LIMIT 条（滥用）、留言属不可信文本
+一律带 untrusted 标记（注入防线）。core 零兄弟 import（store/state 注入）。
+"""
+import os
+import time
+
+MAX_LEN = 500     # 单条长度上限（写面超限截断）
+SOFT_LIMIT = 10   # 同作者任务留言软限（超限拒写）
+READ_N = 20       # 读面条数上限（最新在前）
+_TERMINAL = {"merged", "closed", "cancelled"}  # is_stale 口径：作者任务终态
+_INFLIGHT_EXCL = _TERMINAL | {"blocked"}       # 在飞＝非终态/非阻塞（含 todo）
+EV_PEER = "peer_post"
+_LIMIT_MSG = f"留言软限 {SOFT_LIMIT} 条/任务已满——沉淀请走 knowledge index"
+
+
+class Rejected(Exception):
+    """peer 域拒绝（写权限/软限/无作者任务）——报因在消息。"""
+
+
+def _own_task(snap, sid):
+    """调用者作者任务 (tid, row)：worker_sid==sid，活动态优先（终态后读面仍可用）。"""
+    hit = [(tid, t) for tid, t in snap["tasks"].items()
+           if t.get("worker_sid") == sid]
+    active = [kv for kv in hit if kv[1]["state"] not in _TERMINAL]
+    return (active or hit or [(None, None)])[0]
+
+
+class PeerBoard:
+    """单写者串行调用（httpd 单线程口径）；store/state 构造注入。"""
+
+    def __init__(self, store, state):
+        self._store = store
+        self._state = state
+
+    def partition(self, sid):
+        """worker 牌分区＝其任务 project_dir（normpath）；无任务行即拒。"""
+        _tid, t = _own_task(self._state.snapshot(), sid)
+        if t is None:
+            raise Rejected(f"repo_board: {sid} 无 worker 任务行（分区不可定）")
+        return os.path.normpath(t["project_dir"])
+
+    def post(self, sid, body):
+        """写面：作者任务锁 tid，软限内超长截断落库＋审计。返回 msg id。"""
+        tid, t = _own_task(self._state.snapshot(), sid)
+        if t is None:
+            raise Rejected(f"peer 留言: {sid} 无 worker 任务行（作者不可定）")
+        repo = os.path.normpath(t["project_dir"])
+        peers = [m for m in self._store.read_messages()
+                 if m.get("kind") == "peer" and m.get("task") == tid]
+        if len(peers) >= SOFT_LIMIT:
+            raise Rejected(_LIMIT_MSG)
+        mid = self._store.write_message(
+            {"ts": time.time(), "task": tid, "kind": "peer", "repo": repo,
+             "from": sid, "to": ""}, str(body)[:MAX_LEN])
+        self._store.append_event({"ts": time.time(), "actor": sid,
+                                  "event": EV_PEER, "task": tid,
+                                  "repo": repo, "mid": mid})
+        return mid
+
+    def board(self, snap, repo=None):
+        """读面：同仓在飞四字段＋最近 READ_N 条留言。repo=None＝全仓（root/
+        dispatcher 诊断面）；worker 分区由 transport 经 partition() 先定。"""
+        if repo:
+            repo = os.path.normpath(repo)
+        now = time.time()
+        tasks = [{"tid": tid, "title": t.get("title", ""), "state": t["state"],
+                  "last_seen": t.get("last_seen")}
+                 for tid, t in sorted(snap["tasks"].items())
+                 if t["state"] not in _INFLIGHT_EXCL
+                 and (repo is None or os.path.normpath(t.get("project_dir") or "")
+                      == repo)]
+        peers = [m for m in self._store.read_messages()
+                 if m.get("kind") == "peer"
+                 and (repo is None or m.get("repo") == repo)][-READ_N:]
+        msgs = []
+        for m in reversed(peers):  # 最新在前
+            author = snap["tasks"].get(m.get("task"))
+            state = author["state"] if author else None
+            msgs.append({"id": m["id"], "author": m.get("task"),
+                         "author_state": state,
+                         "age_seconds": int(now - float(m["ts"])),
+                         "is_stale": state in _TERMINAL if author else True,
+                         "body": m.get("body", ""), "untrusted": True})
+        return {"repo": repo, "tasks": tasks, "messages": msgs}