【实现】 Agent Loop 重构 Phase 3：受约束 DAG 调度与节点级恢复

[wynxing]

关联 RFC / 架构

• 父架构 RFC：【架构】 重构 NeoCode Agent Loop：Workflow Orchestrator、统一 AgentLoop 与上下文隔离 #721
• 阶段：Phase 3
• 前置依赖：【实现】 Agent Loop 重构 Phase 1：Workflow 领域模型与持久化 #723 Workflow Store、【实现】 Agent Loop 重构 Phase 2：提取统一 AgentLoop 执行内核 #724 统一 AgentLoop；验收使用 【实现】 Agent Loop 重构 Phase 0：建立任务质量评测基线与迁移护栏 #722 基线。

目标问题

NeoCode 已有 Todo DAG Scheduler，但它不是主 Run 的编排真源，也不能恢复 provider/tool 节点执行。需要一个以持久化 Workflow 状态为真源的 Scheduler，统一处理依赖、只读并发、单写者、取消、固定失败策略和进程重启后的节点级恢复。

实现设计（How）

• 实现受约束 Workflow DAG 校验器，节点类型固定为 route、explore、synthesize、execute、verify、finalize。
• Scheduler 从 Store snapshot 计算 ready 节点，使用 revision 原子 claim，调用 【实现】 Agent Loop 重构 Phase 2：提取统一 AgentLoop 执行内核 #724 AgentLoop，并通过 【实现】 Agent Loop 重构 Phase 1：Workflow 领域模型与持久化 #723 事务提交结果。
• Explore 可按配置并发；Execute 获取 Workflow 写租约，任意时刻最多一个写节点 running。
• 固定节点失败策略：Route 回退、Explore 有限重试并允许部分成功、Synthesize 必须成功、Execute 写后中断需要恢复、Verify 区分检查失败与基础设施错误。
• 启动时扫描非终态 Workflow，将遗留 running 标为 interrupted；只读节点可重试，发生成功写入的 Execute 转 needs_recovery。
• Execute 恢复审计联合 tool receipt、node transcript、run/per-edit checkpoint 与当前 diff，禁止盲目重放写工具。
• 迁移 Todo Scheduler 中通用的图校验、priority、retry/backoff 思路；Workflow Scheduler 成为唯一编排真源后删除重复调度路径。

影响模块：Runtime orchestration、Workflow Store、Checkpoint bridge、Todo/subagent scheduler 迁移和恢复事件。

边界与非目标：本阶段使用静态工作流 fixture，不实现模型 Router/Planner；不实现并行写入、路径租约或 worktree 合并。

任务拆解

• 实现受约束 DAG 校验和 ready 计算。
• 实现节点 claim、执行、结果提交、依赖解锁和 Workflow 终止。
• 实现只读并发池、单写者租约和 context cancellation 传播。
• 实现按 NodeKind 固定的 retry、partial success、fail-fast 和 backoff。
• 实现启动恢复扫描与 interrupted 状态迁移。
• 实现 Execute workspace journal、checkpoint guard 和 needs_recovery 审计。
• 实现 recovery 决议：resume、restore checkpoint、keep current state、cancel。
• 迁移并收敛现有 Todo Scheduler 的可复用逻辑。
• 增加 Scheduler snapshot/metrics 及完整状态机文档。

测试与验证（Done）

• 正常路径：线性 DAG、多个 Explore 并行、依赖解锁、Execute 独占和 Finalize 终止。
• 边界条件：空图、环、重复 ID、未知依赖、无 Explore 成功、达到并发/重试/replan 上限。
• 异常分支：Store revision 冲突、AgentLoop 错误、checkpoint 错误、worker stale result 和取消竞态。
• 恢复路径：只读节点 interrupted 后重试；Execute 无写入可重试；写入成功后进入 needs_recovery。
• 幂等路径：tool 成功但消息未保存时从 receipt 重建结果，不重放写工具。
• 单写者：压力测试证明任何时刻最多一个写节点 running，取消后租约可释放。
• go test ./...、race 相关测试和 【实现】 Agent Loop 重构 Phase 0：建立任务质量评测基线与迁移护栏 #722 评测通过，新增修改逻辑达到 100% 覆盖目标。

风险与回滚

• 风险：Scheduler 与 Store 状态竞态导致重复节点。所有 claim/result 使用 revision，stale worker 结果不得提交。
• 风险：错误恢复造成重复写入。写后中断一律 needs_recovery，不自动调用写工具。
• 风险：迁移 Todo Scheduler 影响现有 Todo 展示。先保持 Todo 作为用户计划视图，Workflow Node 作为执行真源，明确单向投影。
• 回滚：可将执行入口切回 【实现】 Agent Loop 重构 Phase 2：提取统一 AgentLoop 执行内核 #724 的单节点 adapter；新增 Workflow 数据保留但停止调度，不回滚已产生的工作区修改。