# 生产环境调度/复原循环——需求文档

**日期**: 2026-08-06
**性质**: 需求文档（BRD/PRD 层面），不含详细技术设计。回应一次真实事故的根因排查——任务 `3605272e-fe33-48cc-b3f3-e0c0ba26f970` 在 `validating` 状态卡死 15+ 小时，`execution_event` 表在此期间零记录，`work_graph_run` 里从未出现 Validator 的运行记录。
**状态**: FR-2（在途任务复原）✅ 已实现（2026-08-06）。FR-1（新 Goal 自动派发）仍是草案，按第 3 节非目标/第 7 节风险的既定判断，未与 FR-2 一起做——它改变系统自主权边界，需要单独评审决策。

## 0. FR-2 实现记录（2026-08-06）

- `src/task_reconciliation.py`（新增）：`find_stale_resumable_tasks()`（纯查询，判定信号是 `execution_event` 里该任务最近一条记录的 `MAX(created_at)`，没有则退回 `task.created_at`——不是 `task.updated_at`，理由见模块 docstring 和 FR-3）+ `reconcile_once()`（扫描后逐个 dispatch，单个候选 dispatch 失败不影响其余候选，呼应 04-P"调度器继续执行队列中其他任务"）。
- `src/task_execution.py`：新增进程内 `_in_flight_task_ids`（`threading.Lock` 保护的内存 set）+ `is_in_flight()`/`_try_claim()`/`_release()`，`start_task_execution_in_background()` 接线为"已在途则立即 `TaskExecutionError`，不重复派发"——这正是 FR-5 之外一条隐含但必须有的约束（防止复原循环和人工点 Start 竞争同一个任务）。
- `src/backend_server.py`：新增 `_start_reconciliation_loop()`，**只在 `main()`（真实 CLI 入口）里启动，不放进 `create_server()`**——后者被几乎每个 `test_backend_server.py` 测试实例化，放进去会让每次跑测试都触发真实的后台任务派发。新增 CLI 参数 `--reconciliation-interval-seconds`（默认 300）、`--disable-reconciliation-loop`。
- `stale_after_seconds` 默认 1800（30 分钟）——比这套代码里最长的单节点默认超时（Validator 自己的 Work Graph `timeout=1200`）留了充分余量，正常还在跑的节点不会被误判。
- **实现过程中真实抓到并修了两个问题，不是纸面设计就想到的**：
  1. 测试污染：`_in_flight_task_ids` 是进程级全局状态，第一版新增测试里有一个没有完整 mock 掉后续真实调用路径，导致被测线程超出 `join(timeout=10)` 仍在跑，"task-1" 这个在测试文件里被大量复用的字面量 task_id 永久卡在 in-flight 集合里，导致全量跑 `discover -s src` 时（而不是单独跑这个文件时）另外 3 个无关测试跟着炸——已修正 mock 完整性，并在 `StartTaskExecutionInBackgroundTest` 加了防御性 `setUp`/`tearDown` 兜底清理。
  2. 生产副作用：Deploy Supervisor 的候选进程（`supervisor/deploy_stage.py::_launch_candidate`）启动的 `backend_server.py` 实例，`--db-path` 指向的是**生产库的一份拷贝**——默认开启复原循环会让候选进程一启动就对着这份拷贝库真的派发 `claude -p` 调用，这在候选还没通过健康检查、Deploy Supervisor 还没决定要不要采用它之前完全不该发生。已在 `_launch_candidate` 加 `--disable-reconciliation-loop`，并补了对应的代码注释说明原因。
- `python3 -m unittest discover -s src`（635 tests）+ `discover -s supervisor -p "test_*.py"`（125 tests）全绿，零回归。

## 1. 背景

排查这次真实事故发现两层原因：

1. **生产后端进程从来没有接入过任何轮询循环**。`docs/implementation-gap-analysis.md` 第 6 条早就记录了这个缺口："给某个常驻进程（`backend_server.py` 或独立进程）接入 `scheduler.run_scheduler_once()` 的轮询循环"，评级"高"，并且明确建议"改变系统自己的自主权边界，建议单独一批、额外人工审查 diff，不要和其他 gap 混跑"。这次事故是这条缺口第一次以真实用户可见的方式发作。
2. **即使真的接上 `scheduler.run_scheduler_once()`，也不会自动修好这次事故这类问题**——这是排查过程中新发现的、比原缺口描述更精确的一点。`run_scheduler_once(db_path, goals, max_workers=None)` 的入参 `goals` 是 `[(target_folder_path, goal_text), ...]`，语义是"这一轮要**新建**并跑完这些 Goal"，内部通过 `task_create.create_task()` 每次都新建一个 `task` 行。它解决的是"新 Goal 怎么被自动拿去跑"，**不是**"一个已经存在、卡在某个中间状态的 `task_id` 怎么被自动接回去继续跑"——后者需要的是 `task_execution.run_or_resume_task_lifecycle`（按 `task_id` 恢复），是完全不同的另一个函数、另一条代码路径。这次事故属于第二类：任务本身已经存在、状态是 `validating`（`task_execution._RESUMABLE_STATUSES` 里合法的可恢复状态之一），只是没有任何东西在合适的时机去调用恢复逻辑。

这次事故本身的具体触发点（`validating` 状态本来就无法通过 `run_or_resume_task_lifecycle` 恢复）已经单独修复（见 `src/task_execution.py` 的 `_RESUMABLE_STATUSES`/`request_pause` 改动，2026-08-06）——这是"人工点 Resume 现在能生效了"，不等于"以后不会再有任务卡死没人管"。本需求要解决的是后者。

## 2. 目标

把生产环境需要的"持续推进任务"能力，拆成两个明确区分、可以分开排期的子问题：

1. **新 Goal 派发**：`queued` 状态的任务（或者说，还没被任何调用触发过 `run_goal_to_completion`/`run_or_resume_task_lifecycle` 的新 Goal）需要被自动拿去执行，不需要人工每次手动点 Start。
2. **在途任务复原（这次事故的真正根因）**：任何已经开始执行、但因为驱动它的那次调用提前退出（进程重启、脚本运行完毕、连接断开等任何原因）而卡在某个可恢复中间状态（`task_execution._RESUMABLE_STATUSES`：`queued`/`planning_brd_prd_sdd`/`coding`/`validating`）、且已经**一段时间没有新进展**的任务，需要被自动重新接回去继续跑，而不是无限期地停在原地、既不算 `blocked_pending_human`（触发不了人工介入通知），也没有任何东西在真的干活。

## 3. 非目标

1. **不在本文档里裁定"要不要做""什么时候做"这个更大的问题**。`docs/implementation-gap-analysis.md` 已经把这条标注为"改变系统自己的自主权边界"——是否现在就投入、要不要额外的人工评审门槛，是需要单独确认的决策，本文档只负责把需求本身讲清楚，供决策时参考。
2. **不要求解决方案是常驻进程/独立进程/`backend_server.py` 内置线程三选一中的哪一个**。具体载体形式留给设计阶段，本文档只描述行为需求。
3. **不重新设计 `run_scheduler_once`/`run_goal_to_completion`/`run_or_resume_task_lifecycle` 这三个已经存在且经过测试的函数本身**。它们的行为已经是对的，本需求要解决的是"谁、在什么时机去调用它们"这一层，不是重写它们的内部逻辑。
4. **不要求第一版就有一套精细的"任务卡死"判定算法**（比如区分"真的卡死"和"合理地在等真实的 `claude -p` 长耗时调用"）。第一版可以用一个保守、简单的阈值（比如"`updated_at`/最近一条 `execution_event` 距今超过 N 分钟，且没有已知的进行中标记"），不需要一次做到完美。

## 4. 功能需求

| # | 需求描述 | 优先级 |
|---|---|---|
| FR-1 | 需要一个机制，定期（具体周期留待设计阶段）调用 `scheduler.run_scheduler_once()` 派发新 Goal——对应「目标 1」。 | 必须 |
| FR-2 | 需要一个独立的机制，定期扫描 `task` 表里状态属于 `task_execution._RESUMABLE_STATUSES` 且"已经一段时间没有新进展"的任务，对每一个调用 `task_execution.run_or_resume_task_lifecycle`（或 `start_task_execution_in_background`）——对应「目标 2」，是这次事故的直接对应修复。 | 必须 |
| FR-3 | FR-2 的"已经一段时间没有新进展"判定，需要能区分"真的没人管"和"确实在真实执行中，只是这一步本来就耗时"——不能简单靠 `task.status` 停留时间判断（比如 Validator 自己的 Work Graph 跑一次可能就要接近 `timeout=1200` 秒），需要参考更细粒度的信号（比如该任务关联的 `work_node_execution`/`execution_event` 最近一次活动时间，而不是 `task.updated_at`——`task.updated_at` 在阶段内部执行期间根本不会变，这正是这次事故排查时的真实盲点）。 | 必须 |
| FR-4 | FR-1、FR-2 两个机制必须能独立开关/独立排期——不能因为"要接 FR-1 需要走完整的人工评审流程"就连带阻塞了 FR-2（这次事故的直接修复）。 | 必须 |
| FR-5 | 无论 FR-1/FR-2 最终选择常驻进程还是独立进程实现，都不能引入新的"共享一个 sqlite 连接跨线程"风险——复用 `scheduler.py` 模块文档里已经验证过的模式（每个 worker 各自开自己的连接 + `busy_timeout`），不要重新踩 U-027 已经用真实 SIGSEGV 验证过的坑。 | 必须 |

## 5. 验收标准

1. 人为构造一个"任务卡在 `validating`，很久没有新进展"的场景（复现这次事故的条件），验证 FR-2 的机制能在设定的检测周期内把它重新接回去执行，不需要人工干预。
2. 人为构造一个"任务正常在跑，Validator 的 Work Graph 正在执行中，还没超过合理耗时"的场景，验证 FR-2 的机制**不会**误判成"卡死"、不会对一个正常在跑的任务重复触发 `run_or_resume_task_lifecycle`（这会导致同一个任务被并发跑两次，需要明确防止）。
3. 新建一个 `queued` 状态的 Goal，不手动点 Start，验证 FR-1 的机制能在设定周期内自动派发执行。
4. FR-1 和 FR-2 分别单独关闭时，各自的行为符合预期（关 FR-1 不影响 FR-2 正常工作，反之亦然）。

## 6. 约束与假设

- 复用现有的 `task_execution._RESUMABLE_STATUSES`（已扩展为包含 `validating`）作为 FR-2 判断"这个任务原则上可以恢复"的依据，不重新定义一套判断标准。
- FR-2 的具体实现要避免和「人工点 Resume」竞争——如果一个任务已经在被 `start_task_execution_in_background` 的某个后台线程处理，FR-2 的扫描不能对同一个 `task_id` 重复触发第二次执行。具体的互斥机制（数据库标记、内存锁、还是别的方式）留给设计阶段。

## 7. 风险

- **FR-1（新 Goal 自动派发）是这次事故排查之前就已经被 `implementation-gap-analysis.md` 标注为"改变系统自主权边界"的决策**，本文档不试图淡化这一点——它意味着系统会在没有人显式点击"Start"的情况下自主开始消耗真实 API 调用、真实修改代码。这条风险原样保留，需要在决策阶段被认真对待。
- **FR-2（在途任务复原）看起来风险更小（只是让已经存在的任务继续跑完，不是凭空发起新工作），但仍然是自主行为的扩展**——需要在设计阶段想清楚"防误判"（FR-3/验收标准 2）没做好的后果：一个只是耗时较长、并没有真的卡死的任务被提前打断重跑，可能造成重复的 API 花费或者更糟的状态不一致。
- **两个机制如果实现成同一个循环、共享同一套判断逻辑，容易在后续维护中被混为一谈**——按第 2 节"目标"明确拆开成两个独立问题，是为了避免这种混淆，设计阶段应该保持这个拆分，不要图省事合并成一个"万能调度循环"。

## 8. 开放问题（留给详细设计阶段回答）

- [ ] FR-1/FR-2 各自的轮询周期定多少。
- [ ] FR-3"已经一段时间没有新进展"的具体判定信号和阈值——参考哪张表的哪个时间戳字段，阈值怎么定（是否要按 `task` 当前所处的具体阶段给不同阈值，比如 Coder 阶段允许的空闲时间可能比 Validator 阶段更长）。
- [ ] FR-1/FR-2 的载体形式：`backend_server.py` 内置后台线程，还是独立进程（类似 Deploy Supervisor 的"独立进程、无共享失败域"哲学）。
- [ ] FR-2 的互斥机制具体怎么实现，防止同一个任务被并发重复触发。
- [ ] 这两个机制要不要暴露成可配置项（管理后台开关/环境变量），还是先硬编码一个保守的默认行为。