[moz] docs: §18 Mail Handler Verify/Prompt 强化设计

§15 Runaway Guard — per-task dispatch_count 上限，防止无限循环 dispatch

问题：mail/toolchain task 走 handler auto-working（跳过 claim），不受
claim_timeout 3 次重试兜底保护。如果反复 spawn 但永远到不了 done/failed，
会无限循环消耗资源（实际案例：2026-06-15 mention 重复投递事件）。

设计：
- tasks 表新增 dispatch_count 字段
- 每次 ticker 成功 dispatch 时递增
- dispatch_count >= 10 时自动标 failed（reason=runaway_guard）
- 覆盖所有非终态（pending/working/claimed）
- 参考 Hermes v0.13 §3 Per-Task 重试上限

改动文件：
- src/blackboard/db.py: _safe_add_column dispatch_count
- src/blackboard/models.py: Task dataclass 加 dispatch_count
- src/daemon/ticker.py: dispatch 递增 + _check_timeouts runaway guard
- docs/design/15-runaway-guard.md: 设计文档
- tests/integration/test_ticker_integration.py: E13 测试 3 个

测试：456 passed, 3 skipped

.gitea/workflows/ci.yml

@@ -62,12 +62,30 @@ jobs:
           (echo '=== RETRY WITH VERBOSE ===' && \
            PYTHONPATH=$(pwd) /tmp/ci-venv-test/bin/pytest tests/ -m "not e2e" -x -v 2>&1 | tail -30)
 
-  # ── Job 3: CI 失败通知 ───────────────────────────────
+  # ── Job 3: Frontend Build ───────────────────────────
+  frontend:
+    runs-on: macos-arm64
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install & Build
+        run: |
+          cd src/frontend
+          npm ci || npm install
+          npm run build
+
+  # ── Job 4: CI 失败通知 ───────────────────────────────
   # 使用 needs.<job>.result 直接判断，不查询 commit status API
   # 根因：notify 自身的 pending status 会污染 commit status 查询结果（竞态条件）
   notify-on-failure:
     runs-on: macos-arm64
-    needs: [lint, test]
+    needs: [lint, test, frontend]
     if: always()
     steps:
       - name: Check results and notify
@@ -75,12 +93,13 @@ jobs:
           GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
           LINT_RESULT: ${{ needs.lint.result }}
           TEST_RESULT: ${{ needs.test.result }}
+          FRONTEND_RESULT: ${{ needs.frontend.result }}
         run: |
           echo "Lint result: $LINT_RESULT"
           echo "Test result: $TEST_RESULT"
 
           # 只有 lint 或 test 明确失败时才发通知
-          if [ "$LINT_RESULT" = "failure" ] || [ "$TEST_RESULT" = "failure" ]; then
+          if [ "$LINT_RESULT" = "failure" ] || [ "$TEST_RESULT" = "failure" ] || [ "$FRONTEND_RESULT" = "failure" ]; then
             echo "CI has failures, sending notification..."
 
             # 如果是 PR 事件，写评论通知
@@ -90,6 +109,7 @@ jobs:
               FAILED_JOBS=""
               [ "$LINT_RESULT" = "failure" ] && FAILED_JOBS="${FAILED_JOBS}lint "
               [ "$TEST_RESULT" = "failure" ] && FAILED_JOBS="${FAILED_JOBS}test "
+              [ "$FRONTEND_RESULT" = "failure" ] && FAILED_JOBS="${FAILED_JOBS}frontend "
 
               curl -sf -X POST \
                 -H "Authorization: token $GITEA_TOKEN" \

.gitea/workflows/deploy.yml

@@ -110,15 +110,7 @@ jobs:
           PR_AUTHOR=$(curl --max-time 5 -sf \
             -H "Authorization: token $GITEA_TOKEN" \
             "$API_URL/repos/$REPO/pulls?state=closed&sort=updated&order=desc&limit=10" | \
-            python3 -c "
-import json, sys
-sha = '$COMMIT_SHA'
-for pr in json.load(sys.stdin):
-    merge_sha = pr.get('merge_commit_sha', '') or ''
-    if merge_sha.startswith(sha) or sha.startswith(merge_sha):
-        print(pr['user']['login'])
-        break
-" 2>/dev/null || echo "")
+            python3 -c "import json,sys; sha='$COMMIT_SHA'; matches=[pr['user']['login'] for pr in json.load(sys.stdin) if (pr.get('merge_commit_sha','') or '').startswith(sha) or sha.startswith(pr.get('merge_commit_sha','') or '')]; print(matches[0] if matches else '')" 2>/dev/null || echo "")
 
           # 确定通知对象
           if [ -n "$PR_AUTHOR" ]; then

docs/design/14-task-type-architecture.md

@@ -1,10 +1,11 @@
 ---
 title: "TaskTypeRegistry + Handler 架构重构"
 created: 2026-06-10
-version: v3.0
+version: v3.1
 ---
 
 > 状态: ✅ 已完成（Step 1-5 全部合并，394 passed）
+> v3.1 新增 §18：Mail Handler Verify/Prompt 强化（2026-06-16，进行中）
 
 # §1 现状分析（v3.0 更新说明：§1-§13 保留原样，新增 §14-§18，更新 §3/§5/§7）
 
@@ -585,6 +586,18 @@ class PromptComposer:
 | 50-59 | 硬约束 | 安全红线、禁止行为 |
 | 60-69 | 扩展段 | 保留给未来使用 |
 
+## 共性 Section（三 handler 共享）
+
+以下三个 Section 在 `prompt_composer.py` 中统一定义，被 Task/Mail/Toolchain 三个 handler 共同注入：
+
+| Section | priority | 用途 |
+|---------|----------|------|
+| `GiteaConventionSection` | 55 | Gitea Issue/PR 标题规范、分支命名、提交格式 |
+| `DeliveryChecklistSection` | 55 | 交付前检查清单（产出格式、验证项、必读文档） |
+| `WikiGuideSection` | 60 | Wiki 知识库检索指引（检索路径、优先级、知识缺口记录） |
+
+设计意图：将跨 handler 的共性约束从各 handler 的 ConstraintsSection 中抽离，避免重复维护。
+
 ---
 
 # §13 三个 Handler 的 Section 注册
@@ -601,6 +614,9 @@ def get_sections(self) -> list[PromptSection]:
         RoleSkillSection(priority=30),         # BootstrapBuilder 段 3（Skill 全文）
         TaskApiSection(priority=40),           # API 操作指令，success_status="review"
         TaskConstraintsSection(priority=50),   # 硬约束
+        GiteaConventionSection(priority=55),   # Gitea 协作规范（共性）
+        WikiGuideSection(priority=60),         # Wiki 知识库检索指引（共性）
+        DeliveryChecklistSection(priority=55), # 交付检查清单（共性）
     ]
 ```
 
@@ -611,6 +627,9 @@ def get_sections(self) -> list[PromptSection]:
 | RoleSkillSection | BootstrapBuilder 段 3 | 个性：只有 task 读 Skill 全文 |
 | TaskApiSection | spawner `_build_api_section` | **共性基础 + 个性参数**（success_status） |
 | TaskConstraintsSection | BootstrapBuilder 段 4 | 个性：每种 task 约束不同 |
+| GiteaConventionSection | prompt_composer.py | **共性**：Gitea Issue/PR 规范 |
+| WikiGuideSection | prompt_composer.py | **共性**：Wiki 检索指引 |
+| DeliveryChecklistSection | prompt_composer.py | **共性**：交付前检查清单 |
 
 ## MailHandler sections
 
@@ -620,6 +639,9 @@ def get_sections(self) -> list[PromptSection]:
         MailContextSection(priority=10),       # from/to/title/text，区分 inform/request
         MailApiSection(priority=40),           # API 操作指令，success_status="done"
         MailConstraintsSection(priority=50),   # 硬约束（禁止状态转换命令等）
+        GiteaConventionSection(priority=55),   # Gitea 协作规范（共性）
+        WikiGuideSection(priority=60),         # Wiki 知识库检索指引（共性）
+        DeliveryChecklistSection(priority=55), # 交付检查清单（共性）
     ]
 ```
 
@@ -628,6 +650,9 @@ def get_sections(self) -> list[PromptSection]:
 | MailContextSection | MAIL_INFORM_TEMPLATE / MAIL_REQUEST_TEMPLATE | 个性：邮件格式 |
 | MailApiSection | spawner `_build_api_section` 变体 | **共性基础 + 个性参数**（success_status="done"，含 Mail API 指令） |
 | MailConstraintsSection | 模板中的 ⚠️ 约束 | 个性 |
+| GiteaConventionSection | prompt_composer.py | **共性**：Gitea Issue/PR 规范 |
+| WikiGuideSection | prompt_composer.py | **共性**：Wiki 检索指引 |
+| DeliveryChecklistSection | prompt_composer.py | **共性**：交付前检查清单 |
 
 ## ToolchainHandler sections
 
@@ -637,6 +662,9 @@ def get_sections(self) -> list[PromptSection]:
         ToolchainContextSection(priority=10),  # 事件类型 + 事件详情
         ToolchainApiSection(priority=40),      # API 操作指令，success_status="done"
         ToolchainConstraintsSection(priority=50),  # 硬约束
+        GiteaConventionSection(priority=55),   # Gitea 协作规范（共性）
+        WikiGuideSection(priority=60),         # Wiki 知识库检索指引（共性）
+        DeliveryChecklistSection(priority=55), # 交付检查清单（共性）
     ]
 ```
 
@@ -645,6 +673,9 @@ def get_sections(self) -> list[PromptSection]:
 | ToolchainContextSection | toolchain_templates.py + md 文件 | 个性：事件格式 |
 | ToolchainApiSection | spawner `_build_api_section` 变体 | **共性基础 + 个性参数** |
 | ToolchainConstraintsSection | 新增 | 个性 |
+| GiteaConventionSection | prompt_composer.py | **共性**：Gitea Issue/PR 规范 |
+| WikiGuideSection | prompt_composer.py | **共性**：Wiki 检索指引 |
+| DeliveryChecklistSection | prompt_composer.py | **共性**：交付前检查清单 |
 
 ## Section 复用分析
 
@@ -655,6 +686,9 @@ def get_sections(self) -> list[PromptSection]:
 | *ConstraintsSection | ✅ | ✅ | ✅ | ❌ 约束内容不同，各自实现 |
 | PriorOutputsSection | ✅ | ❌ | ❌ | 仅 task |
 | RoleSkillSection | ✅ | ❌ | ❌ | 仅 task |
+| GiteaConventionSection | ✅ | ✅ | ✅ | **共性**：三 handler 共享，prompt_composer.py 定义 |
+| WikiGuideSection | ✅ | ✅ | ✅ | **共性**：三 handler 共享，prompt_composer.py 定义 |
+| DeliveryChecklistSection | ✅ | ✅ | ✅ | **共性**：三 handler 共享，prompt_composer.py 定义 |
 
 **结论**：ApiSection 可以抽一个 BaseApiSection（curl 模板 + success_status 参数），其余 section 各自实现。
 
@@ -667,9 +701,9 @@ src/daemon/
 ├── task_type_registry.py    # §3 + §4：Protocol + Registry
 ├── prompt_composer.py        # §12 PromptSection + PromptContext + PromptComposer
 ├── base_task_handler.py      # §16 BaseTaskHandler 基类
-├── task_handler.py           # §13 TaskHandler（继承 BaseTaskHandler）+ 5 sections
-├── mail_handler.py           # §13 MailHandler（继承 BaseTaskHandler）+ 3 sections
-├── toolchain_handler.py      # §13 ToolchainHandler（继承 BaseTaskHandler）+ 3 sections
+├── task_handler.py           # §13 TaskHandler（继承 BaseTaskHandler）+ 8 sections
+├── mail_handler.py           # §13 MailHandler（继承 BaseTaskHandler）+ 6 sections
+├── toolchain_handler.py      # §13 ToolchainHandler（继承 BaseTaskHandler）+ 6 sections
 ├── dispatcher.py             # §6 改动
 ├── spawner.py                # §6 改动
 ├── ticker.py                 # §6 改动
@@ -952,7 +986,219 @@ handler.post_complete(task_id, agent_id, outcome, db_path)
 
 ---
 
-## §14. Mail 失败通知机制
+## §18. Mail Handler Verify/Prompt 强化
+
+> 日期：2026-06-16 | 作者：庞统 | 状态：方向 1-5 全部已确认
+
+## 18.1 问题背景
+
+### 触发事件
+
+2026-06-12 daemon 重启后，_mail DB 中积压的 E2E 测试遗留邮件（5/18~6/1 创建，type=request，performative="text"）被 dispatch 给 agent。agent 正常处理并输出文本（如"已阅，无需处理"），但 `verify_completion` 判定 no_reply → 标 failed → 触发 `notify_mail_failed` → 产生 38 封 `[投递失败]` 通知邮件，每 ~2.5 分钟一轮，持续 10 轮。
+
+### 根因链
+
+```
+E2E 测试脚本 bug（type="text"）
+  → mail_routes.py 不校验 type 值，直接透传
+  → performative="text" ≠ "inform" → 走 _check_reply
+  → _check_reply 查 in_reply_to task，agent 没用 Mail API 回复
+  → verify 失败 → on_failure 标 failed
+  → notify_mail_failed 发 [投递失败] 通知
+  → 通知本身也是 task，循环触发
+```
+
+### 三种 handler verify 对比
+
+| 维度 | TaskHandler | MailHandler | ToolchainHandler |
+|------|------------|-------------|------------------|
+| verify 信号 | output / comment(≥50字) / terminal_status（三信号） | in_reply_to task（单信号） | action_report / output / comment(≥20字)（三层 fallback） |
+| inform 处理 | N/A | 直接通过（不检查执行证据） | N/A |
+| verify 失败后 | **留 working**（覆盖 post_complete） | **标 failed**（base post_complete + mail on_failure） | 标 failed（base post_complete + tc on_failure） |
+| agent 输出持久化 | 靠 agent 主动 POST output/comment | **无**（agent 输出只在内存） | 靠 agent 主动 POST action_report |
+
+**关键发现**：
+1. MailHandler 继承 BaseTaskHandler，未覆盖 `post_complete` → verify 失败时走 base 的 `on_failure` → 标 failed
+2. TaskHandler 覆盖了 `post_complete` → verify 失败时留 working，让 ticker 重试
+3. MailHandler 的 verify 只有 `in_reply_to` 一条路径，没有 fallback
+4. inform 类型直接通过（`VerifyResult(True)`），不检查任何执行证据——inform 是"无需回复"不是"无需检查"
+5. E2E 测试用 `TestClient(app)` 写生产 `_mail DB`，且测试脚本用了非标准 `type="text"`
+
+## 18.2 修复方向
+
+### 方向 1：mail verify 对齐 toolchain 模式（✅ 已确认）
+
+**问题**：mail verify 只有 in_reply_to task 一条路径。task/toolchain 都有多层 fallback（outputs / comments）。
+
+**方案**：mail 对齐 toolchain 模式——prompt 加 action report 要求，verify 优先查 action_report → fallback outputs → fallback comments。in_reply_to 回复邮件从唯一信号降为 request 类型的第 4 优先级信号。
+
+#### prompt 强化（MailApiSection）
+
+参照 ToolchainApiSection，在 mail prompt 中追加 action report 要求：
+```
+### 完成后必须提交 action report
+执行完邮件处理后，必须提交 action report：
+curl -s -X POST "http://localhost:8083/api/projects/_mail/tasks/{task_id}/comments" \
+  -H "Content-Type: application/json" \
+  -d '{"author": "{agent_id}", "comment_type": "action_report", "body": "处理结果摘要"}'
+
+⚠️ 不提交 action report 的任务会被标记为 failed。
+```
+
+#### verify 改造（MailHandler.verify_completion）
+
+```python
+def verify_completion(self, task_id, db_path) -> VerifyResult:
+    performative = self._parse_performative(task_id, db_path)
+
+    # 1. 优先检查 action_report comment（所有类型通用）
+    if self._has_action_report(task_id, db_path):
+        return VerifyResult(True, "has_action_report", "action_report found")
+
+    # 2. fallback: outputs
+    if self._has_outputs(task_id, db_path):
+        return VerifyResult(True, "has_output", f"output_count={count}")
+
+    # 3. fallback: 有实质内容的 comment（≥20字，非 system）
+    if self._has_comment(task_id, db_path):
+        return VerifyResult(True, "has_comment", f"comment_count={count}")
+
+    # 4. request 特有：检查 in_reply_to 回复邮件
+    if performative == "request":
+        if self._check_reply(task_id, db_path):
+            return VerifyResult(True, "has_reply", "in_reply_to found")
+
+    return VerifyResult(False, "no_action",
+                        "no action_report, no output, no comment, no reply")
+```
+
+注意：action_report 提交到 moziplus DB（comments 表），不是 Gitea。Gitea comment 是跨 agent 协作用的，不是 verify 检查的依据。
+
+### 方向 2：prompt 约束强化（✅ 已确认）
+
+**问题**：当前 mail prompt 只给了 curl 示例，没有硬约束要求 agent 必须输出处理结果。agent 判断"已阅"后直接跳过，不创建 in_reply_to task。
+
+**方案**：mail request/inform prompt 加 JSON 输出约束（参考 toolchain 的 Red Flags 模式）。
+
+#### MailContextSection 强化
+
+**request 类型**追加：
+```
+### 输出要求
+- 你的回复必须包含对邮件的实际处理结果
+- 如果是第一次收到：正常处理，输出处理结果
+- 如果是重复邮件（你之前处理过相同 ID 的邮件）：输出"此前已处理" + 之前的处理结果摘要
+- ⚠️ "已阅""无需处理"不是有效处理结果
+```
+
+**inform 类型**追加：
+```
+### 输出要求
+- 你的回复必须确认已处理（读取/执行/记录），不能只说"已阅"
+- 如果是重复邮件：输出"此前已处理" + 处理结果摘要
+- ⚠️ "已阅"不是有效输出
+```
+
+**MailConstraintsSection** 追加 Red Flags：
+```
+| Agent 想法 | Red Flag 驳回 |
+|------------|--------------|
+| "已阅即可" | ❌ 错！必须输出处理结果或确认执行 |
+| "重复邮件忽略" | ❌ 错！输出"此前已处理" + 结果摘要 |
+| "无需回复" | ❌ 错！request 必须回复，inform 必须确认处理 |
+```
+
+### 方向 3：inform 也要检查执行证据（✅ 已确认）
+
+**问题**：当前 inform verify 直接返回 `VerifyResult(True)`，不检查任何执行证据。inform 是"无需回复"不是"无需检查"。
+
+**方案**：inform verify 改为检查 agent 是否有实质输出（comment/output），和 request 走不同的验证路径但都需要验证。
+
+**改动文件**：`src/daemon/mail_handler.py` `verify_completion` 方法
+
+### 方向 4：verify 失败保持 working（✅ 已确认）
+
+**问题**：MailHandler 继承 BaseTaskHandler，verify 失败时走 base 的 `on_failure` → 标 failed。而 TaskHandler 覆盖了 `post_complete`，verify 失败时留 working。
+
+**原始设计意图**（§2 设计文档）："不通过 → 留 working，ticker 重查（最多 3 次，然后标 failed）"。
+
+**方案**：MailHandler 覆盖 `post_complete`，verify 失败时不标 failed，保持 working。ticker 的 `_check_timeouts` 超时兜底：
+- `check_completion` 通过（有回复）→ done
+- `check_completion` 不通过 → 超时后标 failed
+- Runaway Guard（§15 dispatch_count ≥ 10）兜底防止无限循环
+
+**改动文件**：`src/daemon/mail_handler.py`，新增 `post_complete` 覆盖
+
+### 方向 5：type 校验 + E2E 修复 + DB 清理（✅ 已确认）
+
+#### 5.1 mail_routes.py type 校验
+
+**问题**：`mail_type = body.get("type")` 直接透传，传什么存什么。`"text"` 不是标准值。
+
+**方案**：创建时校验 type 只允许 `inform` / `request`，非法值默认 `request`。
+
+```python
+mail_type = body.get("type")
+if mail_type is None:
+    mail_type = "inform" if in_reply_to else "request"
+elif mail_type not in ("inform", "request"):
+    # 非标准值，校正为默认值
+    mail_type = "inform" if in_reply_to else "request"
+```
+
+**改动文件**：`src/api/mail_routes.py`
+
+#### 5.2 _parse_performative 容错
+
+**问题**：`meta.get("performative", meta.get("type", "request"))` 当 performative="text" 时返回 "text"，不等于 "inform" → 走 _check_reply。
+
+**方案**：只认 `inform` 和 `request` 两个值，其他一律当 `request`。
+
+```python
+def _parse_performative(self, task_id, db_path) -> str:
+    raw = meta.get("performative", meta.get("type", "request"))
+    if raw == "inform":
+        return "inform"
+    return "request"  # 非标准值一律当 request
+```
+
+**改动文件**：`src/daemon/mail_handler.py` `_parse_performative` 方法
+
+#### 5.3 E2E 测试修复
+
+**问题**：`tests/e2e/test_e2e_v27.py` 用 `type="text"` 创建测试邮件，且用 `TestClient(app)` 写生产 `_mail DB`。
+
+**修复**：
+1. `type="text"` 全部改为 `type="inform"` 或 `type="request"`
+2. E2E 测试跑完后清理测试邮件（`mail_ids` 列表中记录的 task）
+
+**改动文件**：`tests/e2e/test_e2e_v27.py`
+
+#### 5.4 生产 DB 清理
+
+**问题**：生产 `_mail DB` 中残留大量 E2E 测试邮件（5/18~6/3 创建的"筛选测试""详情测试""已读测试""任务分配"等）。
+
+**方案**：手动清理这些测试残留（一次性操作，不需要代码改动）。
+
+## 18.3 影响范围
+
+| 文件 | 改动类型 | 影响面 |
+|------|---------|--------|
+| `src/daemon/mail_handler.py` | verify + post_complete + prompt section | MailHandler 核心逻辑 |
+| `src/api/mail_routes.py` | type 校验 | Mail API 创建入口 |
+| `tests/e2e/test_e2e_v27.py` | type 值修正 + 清理 | E2E 测试 |
+| 生产 `_mail DB` | 清理测试残留 | 一次性操作 |
+
+## 18.4 验证计划
+
+1. 单元测试：mail_handler verify/prompt 变更
+2. 集成测试：mail dispatch → verify → done/working 全链路
+3. 回归测试：`pytest -m "not e2e"` 全量
+4. 手工验证：创建 inform/request 邮件，确认 verify 行为正确
+
+---
+
+# §14. Mail 失败通知机制
 
 ### 20.1 背景
 

docs/design/15-runaway-guard.md

@@ -0,0 +1,61 @@
+# §15 Runaway Guard — Per-Task Dispatch 上限
+
+> 设计文档 v1.0 | 2026-06-16
+
+## 问题
+
+mail/toolchain task 走 handler auto-working（跳过 claim 阶段），不受 claim_timeout 的 3 次重试兜底保护。如果一个 auto-working task 反复 spawn 但永远到不了 done/failed，会无限循环消耗资源。
+
+### 实际案例
+
+2026-06-15 mention 重复投递事件：`spawn_full_agent` 在 `use_main_session=True` 时返回 `None`，ticker `_process_mentions` 误判为失败，每次 tick（30s）都重试。同一 mention 投递了 4 次，直到 retry_count 达到 mention_queue 的 5 次上限才停止。
+
+直接根因已由 PR #80 修复，但如果类似 bug 再次出现，当前没有任何机制阻止 task 层面的无限循环。
+
+## 设计
+
+### 机制
+
+tasks 表新增 `dispatch_count` 字段，每次 ticker 成功 dispatch 一个 task 时递增。当 `dispatch_count >= 10`（全局默认）时，自动标 failed。
+
+### 默认值选择
+
+全局默认 10 次。参考 Hermes v0.13 Best Practices §3 "Per-Task 重试上限"：
+
+- 简单任务重试 1 次
+- 复杂任务重试 3 次
+- crash recovery（3 次）+ api_retry（3 次）余量 = ~10 次
+
+### 适用范围
+
+所有 task 类型（task/mail/toolchain），所有非终态（pending/working/claimed）。
+
+### 检查时机
+
+在 `_check_timeouts` 方法开头，先于现有的 claimed/working 超时检查执行。
+
+### 与现有机制的关系
+
+| 机制 | 覆盖场景 | 触发动作 |
+|------|---------|---------|
+| claim_timeout retry_count >= 3 | 广播任务无人认领 | 升级庞统 |
+| crash_limit 3/30min | working 状态 crash | 标 failed |
+| api_retry_count | API 连续失败 | 标 failed |
+| 续杯 max_retries 3 | 续杯耗尽 | 标 failed |
+| working timeout | working 超时 | 标 failed 或 done |
+| **runaway_guard 10 次** | **任何状态的无限循环** | **标 failed** |
+
+runaway_guard 是最后一道防线，覆盖所有其他机制遗漏的循环场景。
+
+## 改动文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/blackboard/db.py` | `_safe_add_column(conn, "tasks", "dispatch_count", "INTEGER DEFAULT 0")` |
+| `src/blackboard/models.py` | Task dataclass 加 `dispatch_count: int = 0` |
+| `src/daemon/ticker.py` | `_dispatch_pending` / `_dispatch_reviews` 递增 dispatch_count；`_check_timeouts` 加 runaway guard 检查 |
+
+## 参考
+
+- Hermes v0.13 Kanban Best Practices §3 "Per-Task 重试上限"
+- 实际案例：2026-06-15 mention 重复投递事件（PR #80 修复了直接根因，runaway guard 作为兜底）

src/api/shared.py

@@ -0,0 +1,73 @@
+"""共享 helper 和常量"""
+
+from typing import Any, Dict
+from fastapi import HTTPException
+
+from src.blackboard.operations import Blackboard
+from src.blackboard.queries import Queries
+from src.blackboard.models import Task
+from src.blackboard.registry import ProjectRegistry
+from src.utils import get_data_root
+
+# 虚拟项目白名单
+_VIRTUAL_PROJECTS = frozenset({"_general", "_mail", "_toolchain"})
+
+
+def _validate_project(project_id: str) -> str:
+    """校验 project_id"""
+    if project_id in _VIRTUAL_PROJECTS:
+        return project_id
+    reg = ProjectRegistry(get_data_root())
+    if reg.get_project(project_id):
+        return project_id
+    raise HTTPException(400, {
+        "ok": False,
+        "error": "project_not_found",
+        "detail": f"Project '{project_id}' is not registered.",
+        "suggestions": [
+            f"Register first: POST /api/projects with id='{project_id}'",
+            "Or use '_general' for tasks without a specific project",
+        ],
+    })
+
+
+def _bb(project_id: str) -> Blackboard:
+    _validate_project(project_id)
+    return Blackboard(get_data_root() / project_id / "blackboard.db")
+
+
+def _q(project_id: str) -> Queries:
+    _validate_project(project_id)
+    return Queries(get_data_root() / project_id / "blackboard.db")
+
+
+def _task_to_dict(t: Task) -> Dict[str, Any]:
+    d = {k: v for k, v in t.__dict__.items() if v is not None}
+    return d
+
+
+_KNOWN_AGENT_IDS: list = []
+
+
+def _init_agent_ids():
+    """从配置文件加载 Agent ID 列表"""
+    global _KNOWN_AGENT_IDS
+    if _KNOWN_AGENT_IDS:
+        return
+    try:
+        import yaml
+        import os
+        cfg_path = os.path.join(os.path.dirname(__file__), "..", "..", "config", "default.yaml")
+        with open(cfg_path) as f:
+            cfg = yaml.safe_load(f)
+        _KNOWN_AGENT_IDS = list(cfg.get("daemon", {}).get("agent_profiles", {}).keys())
+    except Exception:
+        _KNOWN_AGENT_IDS = []
+
+
+def _extract_mentions(text: str) -> list:
+    """从文本中自动提取 @agent-id 格式的 mention"""
+    import re
+    _init_agent_ids()
+    candidates = set(re.findall(r'@([a-z][a-z0-9]*(?:-[a-z][a-z0-9]*)+)', text))
+    return [a for a in candidates if a in _KNOWN_AGENT_IDS]

src/api/task_relation_routes.py

@@ -0,0 +1,240 @@
+"""Task 关联路由 — comments / outputs / decisions / observations / reviews / events / experiences / summary"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, Optional
+
+from fastapi import APIRouter, HTTPException, Query
+
+from src.blackboard.models import Review
+from src.blackboard.db import OUTPUT_TYPES
+
+from src.api.shared import (
+    _bb,
+    _q,
+    _extract_mentions,
+)
+
+router = APIRouter(prefix="/api/projects/{project_id}", tags=["blackboard"])
+
+
+# --------------------------------------------------------------------------- #
+# Comments
+# --------------------------------------------------------------------------- #
+
+@router.get("/tasks/{task_id}/comments")
+async def get_comments(project_id: str, task_id: str,
+                       comment_type: Optional[str] = None):
+    bb = _bb(project_id)
+    comments = bb.get_comments(task_id, comment_type=comment_type)
+    return {"comments": [dict(c.__dict__) for c in comments]}
+
+
+@router.post("/tasks/{task_id}/comments")
+async def add_comment(project_id: str, task_id: str, body: Dict[str, Any]):
+    bb = _bb(project_id)
+    mentions_raw = body.get("mentions")
+    comment_body = body["body"]
+
+    # #04: 自动从 body 提取 @mention，与显式传的 mentions 取并集
+    auto_mentions = _extract_mentions(comment_body)
+    if isinstance(mentions_raw, str):
+        try:
+            explicit_mentions = json.loads(mentions_raw)
+        except Exception:
+            explicit_mentions = []
+    elif isinstance(mentions_raw, list):
+        explicit_mentions = mentions_raw
+    else:
+        explicit_mentions = []
+    merged_mentions = list(set(explicit_mentions + auto_mentions))
+
+    cid = bb.add_comment(task_id, body["author"], comment_body,
+                         comment_type=body.get("comment_type", "general"),
+                         mentions=merged_mentions)
+    if merged_mentions:
+        bb.record_mentions(cid, task_id, merged_mentions)
+    # #10: SSE 通知前端黑板有新 comment
+    try:
+        from src.api.sse_routes import get_broker
+        broker = get_broker()
+        broker.publish_sync("comment_added", {
+            "project_id": project_id,
+            "task_id": task_id,
+            "comment_id": cid,
+            "author": body["author"],
+        })
+    except Exception:
+        pass
+
+    return {"ok": True, "comment_id": cid, "mentions": merged_mentions}
+
+
+# --------------------------------------------------------------------------- #
+# Outputs
+# --------------------------------------------------------------------------- #
+
+@router.get("/tasks/{task_id}/outputs")
+async def get_outputs(project_id: str, task_id: str):
+    bb = _bb(project_id)
+    return {"outputs": [dict(o.__dict__) for o in bb.get_outputs(task_id)]}
+
+
+@router.post("/tasks/{task_id}/outputs")
+async def write_output(project_id: str, task_id: str, body: Dict[str, Any]):
+    bb = _bb(project_id)
+
+    # 字段校验 + Agent-friendly 错误
+    agent = body.get("agent")
+    if not agent:
+        raise HTTPException(422, {
+            "error": "validation_failed",
+            "detail": "Missing required field: agent",
+            "hint": "Provide your agent ID, e.g. 'zhangfei-dev'",
+        })
+
+    # type 字段：接受 type 或 content_type（别名兼容）
+    output_type = body.get("type") or body.get("content_type")
+    valid_types = sorted(OUTPUT_TYPES)
+    if not output_type:
+        raise HTTPException(422, {
+            "error": "validation_failed",
+            "detail": "Missing required field: type",
+            "valid_values": {"type": valid_types},
+            "hint": "Use 'type' field. Also accepts 'content_type' as alias.",
+        })
+    if output_type not in OUTPUT_TYPES:
+        raise HTTPException(422, {
+            "error": "validation_failed",
+            "detail": f"Invalid type: '{output_type}'",
+            "valid_values": {"type": valid_types},
+        })
+
+    title = body.get("title")
+    if not title:
+        raise HTTPException(422, {
+            "error": "validation_failed",
+            "detail": "Missing required field: title",
+            "hint": "Provide a brief title describing this output",
+        })
+
+    # 内容模式：content（直传）或 content_path（引用）
+    content = body.get("content")
+    content_path = body.get("content_path") or body.get("path")
+
+    if content and not content_path:
+        # 内容直传模式：自动写文件
+        artifacts_dir = os.path.join(
+            os.path.dirname(bb.db_path), "artifacts", task_id
+        )
+        os.makedirs(artifacts_dir, exist_ok=True)
+        # 安全文件名
+        safe_name = "".join(
+            c if c.isalnum() or c in "._-" else "_" for c in title)
+        if not safe_name:
+            safe_name = "output"
+        file_path = os.path.join(artifacts_dir, safe_name)
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(content)
+        content_path = file_path
+
+    oid = bb.write_output(
+        task_id, agent, output_type, title,
+        content_path=content_path,
+        summary=body.get("summary"),
+        metadata=body.get("metadata"),
+    )
+    return {"ok": True, "output_id": oid}
+
+
+# --------------------------------------------------------------------------- #
+# Decisions
+# --------------------------------------------------------------------------- #
+
+@router.get("/tasks/{task_id}/decisions")
+async def get_decisions(project_id: str, task_id: str):
+    bb = _bb(project_id)
+    return {"decisions": [dict(d.__dict__) for d in bb.get_decisions(task_id)]}
+
+
+@router.post("/tasks/{task_id}/decisions")
+async def add_decision(project_id: str, task_id: str, body: Dict[str, Any]):
+    bb = _bb(project_id)
+    did = bb.add_decision(task_id, body["decider"], body["decision"],
+                          body["rationale"],
+                          alternatives=body.get("alternatives"))
+    return {"ok": True, "decision_id": did}
+
+
+# --------------------------------------------------------------------------- #
+# Observations
+# --------------------------------------------------------------------------- #
+
+@router.post("/tasks/{task_id}/observations")
+async def add_observation(project_id: str, task_id: str, body: Dict[str, Any]):
+    bb = _bb(project_id)
+    oid = bb.add_observation(task_id, body["observer"], body["body"],
+                             severity=body.get("severity", "info"))
+    return {"ok": True, "observation_id": oid}
+
+
+# --------------------------------------------------------------------------- #
+# Reviews
+# --------------------------------------------------------------------------- #
+
+@router.get("/tasks/{task_id}/reviews")
+async def get_reviews(project_id: str, task_id: str):
+    bb = _bb(project_id)
+    return {"reviews": [dict(r.__dict__) for r in bb.get_reviews(task_id)]}
+
+
+@router.post("/tasks/{task_id}/reviews")
+async def add_review(project_id: str, task_id: str, body: Dict[str, Any]):
+    bb = _bb(project_id)
+    review = Review(
+        id=body["id"], task_id=task_id, reviewer=body["reviewer"],
+        review_type=body["review_type"], verdict=body["verdict"],
+        summary=body["summary"], confidence=body.get("confidence"),
+        round=body.get("round", 1), max_rounds=body.get("max_rounds", 3),
+    )
+    bb.add_review(review)
+    return {"ok": True, "review_id": review.id}
+
+
+# --------------------------------------------------------------------------- #
+# Per-task Events & Experiences
+# --------------------------------------------------------------------------- #
+
+@router.get("/tasks/{task_id}/events")
+async def get_task_events(project_id: str, task_id: str,
+                          limit: int = Query(50, le=200)):
+    q = _q(project_id)
+    return {"events": q.task_events(task_id, limit)}
+
+
+@router.get("/tasks/{task_id}/experiences")
+async def get_task_experiences(project_id: str, task_id: str):
+    q = _q(project_id)
+    return {"experiences": q.task_experiences(task_id)}
+
+
+# --------------------------------------------------------------------------- #
+# Global Events
+# --------------------------------------------------------------------------- #
+
+@router.get("/events")
+async def get_events(project_id: str, limit: int = Query(50, le=200)):
+    q = _q(project_id)
+    return {"events": q.recent_events(limit)}
+
+
+# --------------------------------------------------------------------------- #
+# Summary
+# --------------------------------------------------------------------------- #
+
+@router.get("/summary")
+async def task_summary(project_id: str):
+    q = _q(project_id)
+    return {"summary": q.task_summary()}

src/api/task_routes.py

@@ -1,68 +1,45 @@
-"""API 路由 — 黑板 CRUD"""
+"""Task 核心路由 — CRUD、状态、归档"""
 
 from __future__ import annotations
 
 import json
 import os
+import sqlite3
+from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, Optional
 
-from fastapi import APIRouter, HTTPException, Query
-
-from src.blackboard.operations import Blackboard
-from src.blackboard.models import Task, Review
-from src.blackboard.queries import Queries
-from src.blackboard.db import VALID_STATUSES, OUTPUT_TYPES
-from src.blackboard.registry import ProjectRegistry
+from fastapi import APIRouter, HTTPException
 
+from src.blackboard.models import Task
+from src.blackboard.db import VALID_STATUSES, VALID_TRANSITIONS
 from src.utils import get_data_root
 
+from src.api.shared import (
+    _bb,
+    _q,
+    _task_to_dict,
+    _extract_mentions,
+)
+
 router = APIRouter(prefix="/api/projects/{project_id}", tags=["blackboard"])
 
-# 虚拟项目白名单（不需要在 registry 注册）
-_VIRTUAL_PROJECTS = frozenset({"_general", "_mail"})
 
-
-def _validate_project(project_id: str) -> str:
-    """校验 project_id，已知项目/虚拟项目放行，未知项目返回 400"""
-    if project_id in _VIRTUAL_PROJECTS:
-        return project_id
-    reg = ProjectRegistry(get_data_root())
-    if reg.get_project(project_id):
-        return project_id
-    raise HTTPException(400, {
-        "ok": False,
-        "error": "project_not_found",
-        "detail": f"Project '{project_id}' is not registered.",
-        "suggestions": [
-            f"Register first: POST /api/projects with id='{project_id}'",
-            "Or use '_general' for tasks without a specific project",
-        ],
-    })
-
-
-def _bb(project_id: str) -> Blackboard:
-    _validate_project(project_id)
-    return Blackboard(get_data_root() / project_id / "blackboard.db")
-
-
-def _q(project_id: str) -> Queries:
-    _validate_project(project_id)
-    return Queries(get_data_root() / project_id / "blackboard.db")
-
-
-# --- Tasks ---
+# --------------------------------------------------------------------------- #
+# Tasks
+# --------------------------------------------------------------------------- #
 
 @router.get("/tasks")
 async def list_tasks(project_id: str,
                      status: Optional[str] = None,
                      assignee: Optional[str] = None,
-                     parent_task: Optional[str] = None):
+                     parent_task: Optional[str] = None,
+                     q: Optional[str] = None):
     bb = _bb(project_id)
-    tasks = bb.list_tasks(
-        status=status,
-        assignee=assignee,
-        parent_task=parent_task)
+    tasks = bb.list_tasks(status=status, assignee=assignee, parent_task=parent_task)
+    if q:
+        q_lower = q.lower()
+        tasks = [t for t in tasks if q_lower in (t.title or "").lower()]
     return {"tasks": [_task_to_dict(t) for t in tasks]}
 
 
@@ -74,6 +51,11 @@ async def get_task(project_id: str, task_id: str,
     if not task:
         raise HTTPException(404, f"Task not found: {task_id}")
     result = _task_to_dict(task)
+
+    if not expand:
+        return result
+
+    # expand=all: 保持旧格式（list + 聚合字段），向后兼容前端 TaskModal
     if expand == "all":
         q = _q(project_id)
         detail = q.task_detail(task_id)
@@ -90,6 +72,37 @@ async def get_task(project_id: str, task_id: str,
                                for d in bb.get_decisions(task_id)]
         result["events"] = q.task_events(task_id)
         result["experiences"] = q.task_experiences(task_id)
+        return result
+
+    # 细粒度 expand: 新格式（comments/events 带 limit + total_count）
+    expand_list = expand.split(",")
+    q = _q(project_id)
+
+    if "comments" in expand_list:
+        all_comments = bb.get_comments(task_id)
+        result["comments"] = {
+            "items": [dict(c.__dict__) for c in all_comments[-20:]],
+            "total_count": len(all_comments),
+            "limit": 20,
+        }
+
+    if "events" in expand_list:
+        all_events = q.task_events(task_id, limit=99999)
+        result["events"] = {
+            "items": all_events[-30:],
+            "total_count": len(all_events),
+            "limit": 30,
+        }
+
+    if "outputs" in expand_list:
+        result["outputs"] = [dict(o.__dict__) for o in bb.get_outputs(task_id)]
+
+    if "reviews" in expand_list:
+        result["reviews"] = [dict(r.__dict__) for r in bb.get_reviews(task_id)]
+
+    if "decisions" in expand_list:
+        result["decisions"] = [dict(d.__dict__) for d in bb.get_decisions(task_id)]
+
     return result
 
 
@@ -100,11 +113,9 @@ async def create_task(project_id: str, body: Dict[str, Any]):
     task_id = body.get("id")
     if not task_id:
         import re
-        from datetime import datetime
         prefix = re.sub(r'[^a-z0-9]', '-', project_id.lower()).strip('-')[:20]
         date_str = datetime.now().strftime('%Y%m%d')
         # seq: 查当前项目最大 seq
-        import sqlite3
         db_path = get_data_root() / project_id / "blackboard.db"
         try:
             conn = sqlite3.connect(str(db_path), timeout=5)
@@ -237,7 +248,6 @@ async def update_status(project_id: str, task_id: str, body: Dict[str, Any]):
         })
 
     # 检查转换是否合法
-    from src.blackboard.db import VALID_TRANSITIONS
     current = old_task.status
     allowed = VALID_TRANSITIONS.get(current, set())
     if new_status not in allowed:
@@ -271,220 +281,6 @@ async def update_status(project_id: str, task_id: str, body: Dict[str, Any]):
     return {"ok": True, "old_status": current, "new_status": new_status}
 
 
-# --- @mention 自动提取（#04） ---
-_KNOWN_AGENT_IDS: list = []
-
-
-def _init_agent_ids():
-    """从配置文件加载 Agent ID 列表"""
-    global _KNOWN_AGENT_IDS
-    if _KNOWN_AGENT_IDS:
-        return
-    try:
-        import yaml
-        cfg_path = os.path.join(
-            os.path.dirname(__file__),
-            "..",
-            "..",
-            "config",
-            "default.yaml")
-        with open(cfg_path) as f:
-            cfg = yaml.safe_load(f)
-        _KNOWN_AGENT_IDS = list(
-            cfg.get(
-                "daemon",
-                {}).get(
-                "agent_profiles",
-                {}).keys())
-    except Exception:
-        _KNOWN_AGENT_IDS = []
-
-
-def _extract_mentions(text: str) -> list:
-    """从文本中自动提取 @agent-id 格式的 mention"""
-    import re
-    _init_agent_ids()
-    candidates = set(
-        re.findall(
-            r'@([a-z][a-z0-9]*(?:-[a-z][a-z0-9]*)+)',
-            text))
-    return [a for a in candidates if a in _KNOWN_AGENT_IDS]
-
-
-# --- Comments ---
-
-@router.get("/tasks/{task_id}/comments")
-async def get_comments(project_id: str, task_id: str,
-                       comment_type: Optional[str] = None):
-    bb = _bb(project_id)
-    comments = bb.get_comments(task_id, comment_type=comment_type)
-    return {"comments": [dict(c.__dict__) for c in comments]}
-
-
-@router.post("/tasks/{task_id}/comments")
-async def add_comment(project_id: str, task_id: str, body: Dict[str, Any]):
-    bb = _bb(project_id)
-    mentions_raw = body.get("mentions")
-    comment_body = body["body"]
-
-    # #04: 自动从 body 提取 @mention，与显式传的 mentions 取并集
-    auto_mentions = _extract_mentions(comment_body)
-    if isinstance(mentions_raw, str):
-        try:
-            explicit_mentions = json.loads(mentions_raw)
-        except Exception:
-            explicit_mentions = []
-    elif isinstance(mentions_raw, list):
-        explicit_mentions = mentions_raw
-    else:
-        explicit_mentions = []
-    merged_mentions = list(set(explicit_mentions + auto_mentions))
-
-    cid = bb.add_comment(task_id, body["author"], comment_body,
-                         comment_type=body.get("comment_type", "general"),
-                         mentions=merged_mentions)
-    if merged_mentions:
-        bb.record_mentions(cid, task_id, merged_mentions)
-    # #10: SSE 通知前端黑板有新 comment
-    try:
-        from src.api.sse_routes import get_broker
-        broker = get_broker()
-        broker.publish_sync("comment_added", {
-            "project_id": project_id,
-            "task_id": task_id,
-            "comment_id": cid,
-            "author": body["author"],
-        })
-    except Exception:
-        pass
-
-    return {"ok": True, "comment_id": cid, "mentions": merged_mentions}
-
-
-# --- Outputs ---
-
-@router.get("/tasks/{task_id}/outputs")
-async def get_outputs(project_id: str, task_id: str):
-    bb = _bb(project_id)
-    return {"outputs": [dict(o.__dict__) for o in bb.get_outputs(task_id)]}
-
-
-@router.post("/tasks/{task_id}/outputs")
-async def write_output(project_id: str, task_id: str, body: Dict[str, Any]):
-    bb = _bb(project_id)
-
-    # 字段校验 + Agent-friendly 错误
-    agent = body.get("agent")
-    if not agent:
-        raise HTTPException(422, {
-            "error": "validation_failed",
-            "detail": "Missing required field: agent",
-            "hint": "Provide your agent ID, e.g. 'zhangfei-dev'",
-        })
-
-    # type 字段：接受 type 或 content_type（别名兼容）
-    output_type = body.get("type") or body.get("content_type")
-    valid_types = sorted(OUTPUT_TYPES)
-    if not output_type:
-        raise HTTPException(422, {
-            "error": "validation_failed",
-            "detail": "Missing required field: type",
-            "valid_values": {"type": valid_types},
-            "hint": "Use 'type' field. Also accepts 'content_type' as alias.",
-        })
-    if output_type not in OUTPUT_TYPES:
-        raise HTTPException(422, {
-            "error": "validation_failed",
-            "detail": f"Invalid type: '{output_type}'",
-            "valid_values": {"type": valid_types},
-        })
-
-    title = body.get("title")
-    if not title:
-        raise HTTPException(422, {
-            "error": "validation_failed",
-            "detail": "Missing required field: title",
-            "hint": "Provide a brief title describing this output",
-        })
-
-    # 内容模式：content（直传）或 content_path（引用）
-    content = body.get("content")
-    content_path = body.get("content_path") or body.get("path")
-
-    if content and not content_path:
-        # 内容直传模式：自动写文件
-        import os
-        artifacts_dir = os.path.join(
-            os.path.dirname(bb.db_path), "artifacts", task_id
-        )
-        os.makedirs(artifacts_dir, exist_ok=True)
-        # 安全文件名
-        safe_name = "".join(
-            c if c.isalnum() or c in "._-" else "_" for c in title)
-        if not safe_name:
-            safe_name = "output"
-        file_path = os.path.join(artifacts_dir, safe_name)
-        with open(file_path, "w", encoding="utf-8") as f:
-            f.write(content)
-        content_path = file_path
-
-    oid = bb.write_output(
-        task_id, agent, output_type, title,
-        content_path=content_path,
-        summary=body.get("summary"),
-        metadata=body.get("metadata"),
-    )
-    return {"ok": True, "output_id": oid}
-
-
-# --- Decisions ---
-
-@router.get("/tasks/{task_id}/decisions")
-async def get_decisions(project_id: str, task_id: str):
-    bb = _bb(project_id)
-    return {"decisions": [dict(d.__dict__) for d in bb.get_decisions(task_id)]}
-
-
-@router.post("/tasks/{task_id}/decisions")
-async def add_decision(project_id: str, task_id: str, body: Dict[str, Any]):
-    bb = _bb(project_id)
-    did = bb.add_decision(task_id, body["decider"], body["decision"],
-                          body["rationale"],
-                          alternatives=body.get("alternatives"))
-    return {"ok": True, "decision_id": did}
-
-
-# --- Observations ---
-
-@router.post("/tasks/{task_id}/observations")
-async def add_observation(project_id: str, task_id: str, body: Dict[str, Any]):
-    bb = _bb(project_id)
-    oid = bb.add_observation(task_id, body["observer"], body["body"],
-                             severity=body.get("severity", "info"))
-    return {"ok": True, "observation_id": oid}
-
-
-# --- Reviews ---
-
-@router.get("/tasks/{task_id}/reviews")
-async def get_reviews(project_id: str, task_id: str):
-    bb = _bb(project_id)
-    return {"reviews": [dict(r.__dict__) for r in bb.get_reviews(task_id)]}
-
-
-@router.post("/tasks/{task_id}/reviews")
-async def add_review(project_id: str, task_id: str, body: Dict[str, Any]):
-    bb = _bb(project_id)
-    review = Review(
-        id=body["id"], task_id=task_id, reviewer=body["reviewer"],
-        review_type=body["review_type"], verdict=body["verdict"],
-        summary=body["summary"], confidence=body.get("confidence"),
-        round=body.get("round", 1), max_rounds=body.get("max_rounds", 3),
-    )
-    bb.add_review(review)
-    return {"ok": True, "review_id": review.id}
-
-
 @router.patch("/tasks/{task_id}")
 async def patch_task(project_id: str, task_id: str, body: Dict[str, Any]):
     """更新任务元数据（归档、标题等）"""
@@ -497,7 +293,6 @@ async def patch_task(project_id: str, task_id: str, body: Dict[str, Any]):
     if not updates:
         return {"ok": True}
     # 直接用 SQL 更新
-    import sqlite3
     conn = sqlite3.connect(str(bb.db_path), timeout=5)
     try:
         set_clause = ", ".join(f"{k}=?" for k in updates)
@@ -509,38 +304,9 @@ async def patch_task(project_id: str, task_id: str, body: Dict[str, Any]):
     return {"ok": True}
 
 
-# --- Per-task Events & Experiences ---
-
-@router.get("/tasks/{task_id}/events")
-async def get_task_events(project_id: str, task_id: str,
-                          limit: int = Query(50, le=200)):
-    q = _q(project_id)
-    return {"events": q.task_events(task_id, limit)}
-
-
-@router.get("/tasks/{task_id}/experiences")
-async def get_task_experiences(project_id: str, task_id: str):
-    q = _q(project_id)
-    return {"experiences": q.task_experiences(task_id)}
-
-
-# --- Global Events ---
-
-@router.get("/events")
-async def get_events(project_id: str, limit: int = Query(50, le=200)):
-    q = _q(project_id)
-    return {"events": q.recent_events(limit)}
-
-
-# --- Summary ---
-
-@router.get("/summary")
-async def task_summary(project_id: str):
-    q = _q(project_id)
-    return {"summary": q.task_summary()}
-
-
-# --- Archive (v2.8) ---
+# --------------------------------------------------------------------------- #
+# Archive (v2.8)
+# --------------------------------------------------------------------------- #
 
 @router.post("/tasks/{task_id}/archive")
 async def archive_task(project_id: str, task_id: str,
@@ -563,10 +329,3 @@ async def archive_done_tasks(project_id: str):
     bb = _bb(project_id)
     count = bb.archive_done_tasks()
     return {"ok": True, "archived_count": count}
-
-
-# --- Helper ---
-
-def _task_to_dict(t: Task) -> Dict[str, Any]:
-    d = {k: v for k, v in t.__dict__.items() if v is not None}
-    return d

src/blackboard/db.py

@@ -117,6 +117,7 @@ def _migrate_v28(conn: sqlite3.Connection) -> None:
 
     _safe_add_column(conn, "tasks", "round_count", "INTEGER DEFAULT 0")
     _safe_add_column(conn, "tasks", "resumed_from", "TEXT")
+    _safe_add_column(conn, "tasks", "dispatch_count", "INTEGER DEFAULT 0")
 
     # 3. checkpoints 表（M3）
     conn.execute("""CREATE TABLE IF NOT EXISTS checkpoints (

src/blackboard/models.py

@@ -41,6 +41,8 @@ class Task:
     resumed_from: Optional[str] = None       # 暂停前状态，恢复时回到原状态
     # v2.9 四相循环
     round_count: int = 0                     # 庞统 review 轮次计数
+    # §15 Runaway Guard
+    dispatch_count: int = 0                  # 被 ticker dispatch 的总次数
     # v2.8 归档
     archived: bool = False
     archived_at: Optional[str] = None

src/blackboard/operations.py

@@ -208,7 +208,7 @@ class Blackboard:
                 params.append(parent_task)
             if conditions:
                 query += " WHERE " + " AND ".join(conditions)
-            query += " ORDER BY priority ASC, created_at ASC"
+            query += " ORDER BY priority ASC, created_at DESC"
             rows = conn.execute(query, params).fetchall()
             return [Task.from_row(r) for r in rows]
         finally:

src/daemon/mail_handler.py

@@ -9,7 +9,7 @@ import logging
 from pathlib import Path
 
 from src.daemon.base_task_handler import BaseTaskHandler, VerifyResult
-from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection
+from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection, DeliveryChecklistSection
 from src.blackboard.db import get_connection
 
 logger = logging.getLogger("moziplus-v2.handler.mail")
@@ -36,7 +36,7 @@ class MailHandler(BaseTaskHandler):
         return composer.compose(context)
 
     def get_sections(self) -> list:
-        return [MailContextSection(), MailApiSection(), MailConstraintsSection(), GiteaConventionSection(), WikiGuideSection()]
+        return [MailContextSection(), MailApiSection(), MailConstraintsSection(), GiteaConventionSection(), WikiGuideSection(), DeliveryChecklistSection()]
 
     def verify_completion(self, task_id: str, db_path: Path) -> VerifyResult:
         """Mail 完成验证：区分 inform/request。

src/daemon/prompt_composer.py

@@ -174,3 +174,27 @@ class WikiGuideSection:
 
     def should_include(self, context: "PromptContext") -> bool:
         return True
+
+
+# ---------------------------------------------------------------------------
+# DeliveryChecklistSection — 交付检查清单
+# ---------------------------------------------------------------------------
+class DeliveryChecklistSection:
+    """交付检查清单 — 提醒 Agent 完成前同步关联成果物。"""
+
+    name: str = "delivery_checklist"
+    priority: int = 55  # CONSTRAINTS(50) 和 EXTENSION(60) 之间
+
+    CHECKLIST_TEXT = (
+        "## 交付检查\n"
+        "完成代码改动前确认：\n"
+        "- 改了实现 → docs/design/ 对应设计文档是否需要更新\n"
+        "- 改了实现 → tests/ 是否有对应测试脚本需要更新\n"
+        "- 所有成果物变更通过 PR 流程：PR review 把关设计合理性，CI 把关代码质量，CD 把关部署正确性\n"
+    )
+
+    def render(self, context: "PromptContext") -> str:
+        return self.CHECKLIST_TEXT
+
+    def should_include(self, context: "PromptContext") -> bool:
+        return True

src/daemon/spawner.py

@@ -625,19 +625,24 @@ curl -X POST http://{self.api_host}:{self.api_port}/api/projects/{project_id}/ta
                 stdout=asyncio.subprocess.PIPE,
                 stderr=asyncio.subprocess.PIPE,
             )
-            self._register_session(session_id, agent_id, task_id, proc.pid,
+            # use_main_session=True 时 session_id 为 None,但 _register_session 和
+            # _monitor_process 需要一个非 None 的 key;同时 ticker 等调用方用
+            # `result is not None` 判断 spawn 是否成功,返回 None 会被误判为失败。
+            # 统一用 "main" 作为占位标识。
+            effective_sid = session_id or "main"
+            self._register_session(effective_sid, agent_id, task_id, proc.pid,
                                    broadcast_task_ids=broadcast_task_ids)
             logger.info("Spawned agent %s (session=%s, pid=%d)",
-                        agent_id, session_id, proc.pid)
+                        agent_id, effective_sid, proc.pid)
 
             # Schedule monitor(传 wrapped_on_complete)
             asyncio.create_task(
-                self._monitor_process(session_id, proc, agent_id, task_id,
+                self._monitor_process(effective_sid, proc, agent_id, task_id,
                                       on_complete=_wrapped_on_complete,
                                       db_path=task_db_path or self.db_path)
             )
 
-            return session_id
+            return effective_sid
 
         except Exception as e:
             # spawn 失败也要 release counter
@@ -1949,6 +1954,19 @@ curl -X POST http://{api_host}:{api_port}/api/projects/{project_id}/tasks/{task_
                 try:
                     from src.daemon.mail_notify import _is_mail_project, notify_mail_failed
                     if _is_mail_project(db_path):
+                        # 防御性检查：如果 task 已经 done，不触发失败通知（竞态保护）
+                        # 场景：spawner 标 failed 和 handler 标 done 同时发生
+                        try:
+                            conn2 = get_connection(db_path)
+                            current_status = conn2.execute(
+                                "SELECT status FROM tasks WHERE id=?", (task_id,)
+                            ).fetchone()
+                            conn2.close()
+                            if current_status and current_status["status"] == "done":
+                                logger.info("Task %s already done, skipping mail failure notification", task_id)
+                                return
+                        except Exception:
+                            pass
                         # Mail 失败：通知发件人，不 @pangtong
                         notify_mail_failed(db_path, task_id, reason, detail)
                     else:

src/daemon/task_handler.py

@@ -10,7 +10,7 @@ from pathlib import Path
 from typing import Dict, Optional
 
 from src.daemon.base_task_handler import BaseTaskHandler, VerifyResult
-from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection
+from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection, DeliveryChecklistSection
 from src.blackboard.db import get_connection
 
 logger = logging.getLogger("moziplus-v2.handler")
@@ -315,6 +315,7 @@ class TaskHandler(BaseTaskHandler):
             TaskConstraintsSection(),
             GiteaConventionSection(),
             WikiGuideSection(),
+            DeliveryChecklistSection(),
         ]
 
     def build_prompt(self, context: PromptContext) -> str:

src/daemon/ticker.py

@@ -1084,6 +1084,19 @@ Parent Task ID: {parent_task.id}
             broadcast_ids = await self._broadcast_claim(broadcast_tasks, db_path, project_id)
             dispatched.extend(broadcast_ids)
 
+        # §15 Runaway Guard: 统一递增 dispatch_count
+        if dispatched:
+            conn = get_connection(db_path)
+            try:
+                for tid in dispatched:
+                    conn.execute(
+                        "UPDATE tasks SET dispatch_count = COALESCE(dispatch_count, 0) + 1 WHERE id=?",
+                        (tid,),
+                    )
+                conn.commit()
+            finally:
+                conn.close()
+
         return dispatched
 
     async def _broadcast_claim(self, tasks: list, db_path: Path,
@@ -1376,6 +1389,19 @@ Parent Task ID: {parent_task.id}
             except Exception:
                 logger.exception("Review dispatch failed for %s", task.id)
 
+        # §15 Runaway Guard: 统一递增 dispatch_count (review)
+        if dispatched:
+            conn = get_connection(db_path)
+            try:
+                for tid in dispatched:
+                    conn.execute(
+                        "UPDATE tasks SET dispatch_count = COALESCE(dispatch_count, 0) + 1 WHERE id=?",
+                        (tid,),
+                    )
+                conn.commit()
+            finally:
+                conn.close()
+
         return dispatched
 
     # ------------------------------------------------------------------
@@ -1388,6 +1414,31 @@ Parent Task ID: {parent_task.id}
         reclaimed: List[str] = []
         now = datetime.utcnow()  # UTC，与 SQLite datetime('now') 一致
 
+        # §15 Runaway Guard: per-task dispatch_count 上限检查
+        # 覆盖所有状态，防止无限循环 dispatch
+        MAX_DISPATCH_COUNT = 10
+        for status_to_check in ("pending", "working", "claimed"):
+            tasks_to_check = queries.tasks_by_status(status_to_check)
+            for task in tasks_to_check:
+                dispatch_count = getattr(task, 'dispatch_count', 0) or 0
+                if dispatch_count >= MAX_DISPATCH_COUNT:
+                    conn = get_connection(db_path)
+                    try:
+                        ok = self._transition_status(
+                            conn, task.id, "failed",
+                            agent="daemon",
+                            detail={"reason": "runaway_guard",
+                                    "dispatch_count": dispatch_count,
+                                    "message": f"dispatch {dispatch_count} 次仍未完成，自动标 failed"},
+                        )
+                        if ok:
+                            reclaimed.append(task.id)
+                            logger.error(
+                                "Task %s: runaway guard triggered (dispatch_count=%d, status=%s), marking failed",
+                                task.id, dispatch_count, status_to_check)
+                    finally:
+                        conn.close()
+
         # claimed 超时 → 重置为 pending（如果 retry_count >= 3 则升级庞统）
         claimed = queries.tasks_by_status("claimed")
         for task in claimed:

src/daemon/toolchain_handler.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from typing import Dict, List
 
 from src.daemon.base_task_handler import BaseTaskHandler, VerifyResult
-from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection
+from src.daemon.prompt_composer import PromptComposer, PromptContext, GiteaConventionSection, WikiGuideSection, DeliveryChecklistSection
 from src.daemon.toolchain_templates import render_template, _TEMPLATE_MAP
 from src.blackboard.db import get_connection
 
@@ -51,17 +51,41 @@ class ToolchainContextSection:
     name: str = "toolchain_context"
     priority: int = 10
 
+    EVENT_LABELS_ZH: Dict[str, str] = {
+        "review_request": "Review 请求",
+        "review_result": "Review 结果",
+        "review_merged": "PR 合并",
+        "review_comment": "Review 评论",
+        "review_updated": "Review 更新",
+        "ci_failure": "CI 失败",
+        "deploy_failure": "部署失败",
+        "issue_assigned": "Issue 指派",
+        "mention": "@提及",
+    }
+
     def render(self, context: PromptContext) -> str:
         event_type = context.event_type
         event_data: Dict = context.event_data or {}
 
+        # 事件类型中文标签
+        event_label = self.EVENT_LABELS_ZH.get(event_type, event_type or '未知')
+
+        # from / to 信息
+        to_agent = context.agent_id or ''
+        from_agent = 'system'
+
         # Part 1: 事件信息(现有模板引擎)
         if event_type in _TEMPLATE_MAP:
             variables = {k: str(v) for k, v in event_data.items()}
             event_text = render_template(event_type, variables)
+            # 补充事件类型中文标签 + from/to
+            header = f"- **事件类型**: {event_label}\n- **来源**: {from_agent}\n- **指派**: {to_agent}\n"
+            event_text = header + "\n" + event_text
         else:
             lines = ["## 工具链事件", ""]
-            lines.append(f"- **事件类型**: {event_type or '未知'}")
+            lines.append(f"- **事件类型**: {event_label}")
+            lines.append(f"- **来源**: {from_agent}")
+            lines.append(f"- **指派**: {to_agent}")
             if event_data:
                 lines.append("- **事件详情**:")
                 for key, value in event_data.items():
@@ -228,6 +252,7 @@ class ToolchainHandler(BaseTaskHandler):
             ToolchainConstraintsSection(),
             GiteaConventionSection(),
             WikiGuideSection(),
+            DeliveryChecklistSection(),
         ]
 
     def build_prompt(self, context: PromptContext) -> str:

src/frontend/src/components/SettingsPanel.tsx

@@ -5,6 +5,7 @@
 
 import { useState, useCallback } from 'react';
 import { api, AgentsStatusData } from '../api';
+import ToolchainPanel from './ToolchainPanel';
 
 interface ServiceCheckResult {
   name: string;
@@ -15,7 +16,7 @@ interface ServiceCheckResult {
 }
 
 export default function SettingsPanel() {
-  const [tab, setTab] = useState<'connections' | 'security' | 'version' | 'logs'>('connections');
+  const [tab, setTab] = useState<'connections' | 'security' | 'version' | 'logs' | 'toolchain'>('connections');
 
   // 接线状态巡检
   const [checking, setChecking] = useState(false);
@@ -95,6 +96,7 @@ export default function SettingsPanel() {
           { key: 'security' as const, label: '🛡️ 安全防务' },
           { key: 'version' as const, label: '📦 版本更新' },
           { key: 'logs' as const, label: '📋 城防日志' },
+          { key: 'toolchain' as const, label: '⛓️ 工具链' },
         ].map((t) => (
           <button key={t.key} className={`btn ${tab === t.key ? 'btn-primary' : ''}`} onClick={() => setTab(t.key)}>
             {t.label}
@@ -288,6 +290,9 @@ export default function SettingsPanel() {
           </div>
         </div>
       )}
+
+      {/* ========== 工具链 ========== */}
+      {tab === 'toolchain' && <ToolchainPanel />}
     </div>
   );
 }

src/frontend/src/components/ToolchainPanel.tsx

@@ -0,0 +1,250 @@
+/**
+ * ToolchainPanel — 工具链事件（系统级）
+ * 展示 _toolchain 项目的 tasks：CI/PR/部署/Review 通知
+ */
+import { useEffect, useState } from 'react';
+
+const AGENT_NAMES: Record<string, string> = {
+  'pangtong-fujunshi': '庞统',
+  'simayi-challenger': '司马懿',
+  'zhangfei-dev': '张飞',
+  'guanyu-dev': '关羽',
+  'zhaoyun-data': '赵云',
+  'jiangwei-infra': '姜维',
+  'system': '系统',
+};
+
+const EVENT_LABELS: Record<string, string> = {
+  'review_request': 'Review 请求',
+  'review_result': 'Review 结果',
+  'review_merged': 'PR 合并',
+  'review_comment': 'Review 评论',
+  'review_updated': 'Review 更新',
+  'ci_failure': 'CI 失败',
+  'deploy_failure': '部署失败',
+  'issue_assigned': 'Issue 指派',
+  'mention': '@提及',
+};
+
+const STATUS_COLORS: Record<string, string> = {
+  pending: '#f59e0b22', claimed: '#6a9eff22', working: '#6a9eff22',
+  review: '#818cf822', done: '#2ecc8a22', failed: '#ef444422',
+  cancelled: '#6b728022', blocked: '#ef444422',
+};
+
+const STATUS_LABELS: Record<string, string> = {
+  pending: '待处理', claimed: '已认领', working: '处理中',
+  review: '审查中', done: '已完成', failed: '失败',
+  cancelled: '已取消', blocked: '已拦截',
+};
+
+function fmtTime(iso: string): string {
+  try {
+    const d = new Date(iso.includes('T') ? iso : iso.replace(' ', 'T') + 'Z');
+    const now = Date.now();
+    const diff = now - d.getTime();
+    const mins = Math.floor(diff / 60000);
+    if (mins < 1) return '刚刚';
+    if (mins < 60) return `${mins}分钟前`;
+    const hrs = Math.floor(mins / 60);
+    if (hrs < 24) return `${hrs}小时前`;
+    return `${d.getMonth() + 1}/${d.getDate()} ${d.getHours()}:${String(d.getMinutes()).padStart(2, '0')}`;
+  } catch { return iso; }
+}
+
+export default function ToolchainPanel() {
+  const [tasks, setTasks] = useState<any[]>([]);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [detail, setDetail] = useState<any>(null);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [filterMode, setFilterMode] = useState<'all' | 'pending'>('all');
+
+  const loadTasks = async (q?: string) => {
+    setLoading(true);
+    try {
+      const url = q
+        ? `/api/projects/_toolchain/tasks?q=${encodeURIComponent(q)}`
+        : `/api/projects/_toolchain/tasks`;
+      const res = await fetch(url);
+      if (res.ok) {
+        const data = await res.json();
+        setTasks(data.tasks || []);
+      }
+    } catch { /* */ }
+    setLoading(false);
+  };
+
+  const displayed = filterMode === 'pending'
+    ? tasks.filter(t => !['done', 'failed', 'cancelled'].includes(t.status))
+    : tasks;
+
+  useEffect(() => { loadTasks(); }, []);
+
+  // 搜索防抖 300ms
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      if (searchQuery !== undefined) loadTasks(searchQuery || undefined);
+    }, 300);
+    return () => clearTimeout(timer);
+  }, [searchQuery]);
+
+  useEffect(() => {
+    if (!selectedId) { setDetail(null); return; }
+    (async () => {
+      try {
+        const res = await fetch(
+          `/api/projects/_toolchain/tasks/${selectedId}?expand=comments`
+        );
+        if (res.ok) setDetail(await res.json());
+      } catch { /* */ }
+    })();
+  }, [selectedId]);
+
+  // 渲染评论列表（兼容 expand 和裸 list 格式）
+  const renderComments = (comments: any[]) => {
+    if (!comments || comments.length === 0) return null;
+    return (
+      <div style={{ marginTop: 16 }}>
+        <div style={{ fontSize: 11, color: 'var(--muted)', marginBottom: 8, fontWeight: 600 }}>
+          📋 处理记录 ({comments.length})
+        </div>
+        {comments.map((c: any, i: number) => (
+          <div key={c.id || i} style={{
+            padding: '8px 12px', background: 'var(--panel2)', borderRadius: 6, marginBottom: 6,
+          }}>
+            <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 4 }}>
+              <span style={{ fontSize: 10, color: 'var(--acc)', fontWeight: 600 }}>
+                {c.author || 'system'}
+              </span>
+              <span style={{ fontSize: 9, color: 'var(--muted)' }}>{fmtTime(c.created_at)}</span>
+            </div>
+            <div style={{ fontSize: 12, color: '#a0aec0', lineHeight: 1.5 }}>{c.body}</div>
+          </div>
+        ))}
+      </div>
+    );
+  };
+
+  return (
+    <div style={{ display: 'flex', gap: 0, height: '100%', minHeight: 500 }}>
+      {/* 左侧列表 */}
+      <div style={{ width: 380, borderRight: '1px solid var(--line)', display: 'flex', flexDirection: 'column', flexShrink: 0 }}>
+        {/* 搜索栏 + 刷新 */}
+        <div style={{ padding: '10px 14px', borderBottom: '1px solid var(--line)', display: 'flex', gap: 6, alignItems: 'center' }}>
+          <input
+            type="text"
+            placeholder="搜索工具链事件..."
+            value={searchQuery}
+            onChange={e => setSearchQuery(e.target.value)}
+            style={{
+              flex: 1, padding: '4px 8px', borderRadius: 4, fontSize: 11,
+              border: '1px solid #2a3550', background: '#161b2e', color: '#dde4f8',
+              outline: 'none',
+            }}
+          />
+          <button onClick={() => loadTasks(searchQuery || undefined)} style={{
+            padding: '3px 8px', borderRadius: 4, fontSize: 10,
+            border: '1px solid #2a3550', background: '#161b2e', color: '#8899aa', cursor: 'pointer',
+          }}>🔄</button>
+          <button onClick={() => setFilterMode('all')} style={{
+            padding: '3px 8px', borderRadius: 4, fontSize: 10,
+            border: `1px solid ${filterMode === 'all' ? 'var(--acc)' : '#2a3550'}`,
+            background: filterMode === 'all' ? 'var(--acc)22' : '#161b2e',
+            color: filterMode === 'all' ? 'var(--acc)' : '#8899aa', cursor: 'pointer',
+          }}>全部</button>
+          <button onClick={() => setFilterMode('pending')} style={{
+            padding: '3px 8px', borderRadius: 4, fontSize: 10,
+            border: `1px solid ${filterMode === 'pending' ? 'var(--acc)' : '#2a3550'}`,
+            background: filterMode === 'pending' ? 'var(--acc)22' : '#161b2e',
+            color: filterMode === 'pending' ? 'var(--acc)' : '#8899aa', cursor: 'pointer',
+          }}>未处理</button>
+          <span style={{ fontSize: 10, color: 'var(--muted)' }}>{filterMode === 'pending' ? displayed.length : tasks.length} 条</span>
+        </div>
+
+        {/* 事件列表 */}
+        <div style={{ flex: 1, overflowY: 'auto' }}>
+          {tasks.length === 0 && (
+            <div style={{ textAlign: 'center', padding: 40, color: 'var(--muted)', fontSize: 12 }}>
+              {loading ? '加载中...' : '暂无工具链事件'}
+            </div>
+          )}
+          {displayed.map((t: any) => (
+            <div key={t.id} onClick={() => setSelectedId(t.id)} style={{
+              padding: '10px 14px', borderBottom: '1px solid var(--line)',
+              cursor: 'pointer', transition: 'background .15s',
+              background: selectedId === t.id ? 'var(--panel2)' : 'transparent',
+            }}
+              onMouseEnter={e => e.currentTarget.style.background = 'var(--panel2)'}
+              onMouseLeave={e => e.currentTarget.style.background = selectedId === t.id ? 'var(--panel2)' : 'transparent'}
+            >
+              <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 4 }}>
+                <span style={{
+                  fontSize: 9, padding: '1px 5px', borderRadius: 3,
+                  background: STATUS_COLORS[t.status] || '#2a3550',
+                  color: '#dde4f8',
+                }}>{STATUS_LABELS[t.status] || t.status}</span>
+                <span style={{ fontSize: 9, color: 'var(--muted)' }}>{fmtTime(t.created_at)}</span>
+              </div>
+              <div style={{
+                fontSize: 12, fontWeight: 500, color: '#dde4f8',
+                overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+              }}>{t.title}</div>
+              <div style={{ fontSize: 10, color: 'var(--muted)', marginTop: 2 }}>
+                {AGENT_NAMES['system'] || '系统'} → {AGENT_NAMES[t.assignee] || t.assignee || '?'}
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      {/* 右侧详情 */}
+      <div style={{ flex: 1, padding: '16px 20px', overflowY: 'auto' }}>
+        {!detail ? (
+          <div style={{ textAlign: 'center', padding: 60, color: 'var(--muted)' }}>
+            <div style={{ fontSize: 36, marginBottom: 12 }}>⛓️</div>
+            <div style={{ fontSize: 13 }}>选择一条事件查看详情</div>
+          </div>
+        ) : (
+          <>
+            {/* 头部 */}
+            <div style={{ marginBottom: 16 }}>
+              <div style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 6 }}>
+                <span style={{ fontSize: 10, padding: '2px 6px', borderRadius: 4, background: STATUS_COLORS[detail.status] || '#2a3550', color: '#dde4f8' }}>
+                  {STATUS_LABELS[detail.status] || detail.status}
+                </span>
+                <span style={{ fontSize: 10, color: 'var(--muted)' }}>{detail.id}</span>
+              </div>
+              <div style={{ fontSize: 18, fontWeight: 700, lineHeight: 1.3 }}>{detail.title}</div>
+              <div style={{ fontSize: 11, color: 'var(--muted)', marginTop: 4 }}>
+                {AGENT_NAMES['system'] || '系统'} → {AGENT_NAMES[detail.assignee] || detail.assignee || '?'}
+              </div>
+              <div style={{ fontSize: 12, color: 'var(--muted)', marginTop: 6 }}>
+                {fmtTime(detail.created_at)}
+              </div>
+            </div>
+
+            {/* 正文 */}
+            {detail.description && (
+              <div style={{
+                padding: '14px 16px', background: 'var(--panel2)', borderRadius: 10,
+                fontSize: 13, color: '#a0aec0', lineHeight: 1.7, whiteSpace: 'pre-wrap',
+              }}>
+                {detail.description}
+              </div>
+            )}
+
+            {/* action_report 评论 — expand 格式 {items, total_count} */}
+            {detail.comments && detail.comments.items && detail.comments.items.length > 0 &&
+              renderComments(detail.comments.items)
+            }
+            {/* 兼容裸 list 格式 */}
+            {detail.comments && Array.isArray(detail.comments) && detail.comments.length > 0 &&
+              renderComments(detail.comments)
+            }
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

src/main.py

@@ -7,7 +7,8 @@ from src.api.sse_routes import router as sse_router
 from src.api.project_routes import router as project_router
 from src.api.daemon_routes import router as daemon_router
 from src.api.checkpoint_routes import router as checkpoint_router
-from src.api.blackboard_routes import router as blackboard_router
+from src.api.task_routes import router as task_router
+from src.api.task_relation_routes import router as task_relation_router
 
 import logging
 from contextlib import asynccontextmanager
@@ -273,7 +274,8 @@ app.add_middleware(
 # ---------------------------------------------------------------------------
 
 
-app.include_router(blackboard_router)
+app.include_router(task_router)
+app.include_router(task_relation_router)
 app.include_router(checkpoint_router)
 app.include_router(daemon_router)
 app.include_router(project_router)

tests/integration/test_ticker_integration.py

@@ -543,3 +543,94 @@ class TestCheckTimeoutsUnified:
         reclaimed = ticker._check_timeouts(db_path)
 
         assert "t-review-dead" not in reclaimed
+
+
+# ---------------------------------------------------------------------------
+# E13: §15 Runaway Guard — per-task dispatch_count 上限
+# ---------------------------------------------------------------------------
+
+class TestRunawayGuard:
+    """E13: dispatch_count >= 10 → 自动标 failed（覆盖所有非终态）"""
+
+    @pytest.fixture
+    def guard_project(self, tmp_path):
+        """创建项目 + 任务"""
+        data_root = tmp_path / "projects"
+        registry = ProjectRegistry(data_root)
+        registry.create_project("guard-proj", "Guard Test", agents=["agent-a"])
+        db_path = data_root / "guard-proj" / "blackboard.db"
+        bb = Blackboard(db_path)
+        return registry, db_path, bb
+
+    def test_runaway_guard_triggers_working(self, guard_project):
+        """E13.1: working 状态 dispatch_count >= 10 → 标 failed"""
+        registry, db_path, bb = guard_project
+
+        bb.create_task(Task(
+            id="t-runaway", title="Runaway Task", status="working",
+            assigned_by="daemon", current_agent="agent-a",
+        ))
+
+        conn = bb._conn()
+        try:
+            conn.execute(
+                "UPDATE tasks SET dispatch_count = 10 WHERE id = ?", ("t-runaway",))
+            conn.commit()
+        finally:
+            conn.close()
+
+        ticker = Ticker(registry, tick_interval=30)
+        reclaimed = ticker._check_timeouts(db_path)
+
+        assert "t-runaway" in reclaimed
+        task = Queries(db_path).task_by_id("t-runaway")
+        assert task.status == "failed"
+
+    def test_runaway_guard_triggers_pending(self, guard_project):
+        """E13.2: pending 状态 dispatch_count >= 10 → 标 failed"""
+        registry, db_path, bb = guard_project
+
+        bb.create_task(Task(
+            id="t-pending-runaway", title="Pending Runaway", status="pending",
+            assigned_by="daemon",
+        ))
+
+        conn = bb._conn()
+        try:
+            conn.execute(
+                "UPDATE tasks SET dispatch_count = 10 WHERE id = ?",
+                ("t-pending-runaway",))
+            conn.commit()
+        finally:
+            conn.close()
+
+        ticker = Ticker(registry, tick_interval=30)
+        reclaimed = ticker._check_timeouts(db_path)
+
+        assert "t-pending-runaway" in reclaimed
+        task = Queries(db_path).task_by_id("t-pending-runaway")
+        assert task.status == "failed"
+
+    def test_runaway_guard_not_triggered(self, guard_project):
+        """E13.3: dispatch_count < 10 → 正常流程不受影响"""
+        registry, db_path, bb = guard_project
+
+        bb.create_task(Task(
+            id="t-normal", title="Normal Task", status="working",
+            assigned_by="daemon", current_agent="agent-a",
+        ))
+
+        conn = bb._conn()
+        try:
+            conn.execute(
+                "UPDATE tasks SET dispatch_count = 5 WHERE id = ?", ("t-normal",))
+            conn.commit()
+        finally:
+            conn.close()
+
+        ticker = Ticker(registry, tick_interval=30)
+        reclaimed = ticker._check_timeouts(db_path)
+
+        assert "t-normal" not in reclaimed
+        task = Queries(db_path).task_by_id("t-normal")
+        assert task.status == "working"