docs: 更新Agent框架技术事实

Agent框架任务规划与独立验证技术方案.md

@@ -3,8 +3,8 @@
 > 文档定位：通用 Agent 框架演进方案，不属于任何具体业务项目的技术方案
 > 适用范围：当前仓库 `agent/agent` 框架内核
 > 分析日期：2026-07-18
-> 实施状态：Framework V1 已在当前仓库 `cyber-agent 0.4.0` 版本基线落地，本文以当前代码和测试为准
-> 写作原则：说清 V1 已实现什么、还有哪些边界、V2/V3 如何演进；不展开业务表结构和具体业务字段
+> 实施状态：Framework V1 闭环和 V2 第一阶段通用观测、后台 Operation、恢复与验证策略能力已在当前仓库落地，本文以当前代码和测试为准
+> 写作原则：说清当前已实现什么、组装边界和后续 V2/V3 如何演进；不展开业务表结构和具体业务字段
 
 ## 一、结论
 
@@ -52,7 +52,8 @@ Decision：主 Agent 对评估结果做出的最终决定
 - 控制 Planner、Worker、Validator 的工具权限；
 - 管理 Agent 会话生命周期和上下文隔离；
 - 保存 Task、Attempt、Validation、Decision 和 Trace；
-- V1 提供 Python 内核、规划工具、文件存储和通用事件；公开 Task HTTP API、跨进程恢复和分布式观测属于 V2/V3。
+- 提供 Python 内核、规划工具、文件存储、durable Event journal、通用 V2 HTTP 适配器和异步 Python SDK；路由由 Host 显式挂载，不由根 `api_server.py` 自动开启；
+- 支持持久化 Background Operation 状态、stop/resume 和显式恢复，但 Agent 运行仍由当前进程的 `asyncio.Task` 执行，不是分布式队列。
 
 ### 2.2 框架不负责什么
 
@@ -115,19 +116,21 @@ Host 传入的 context 会先合并，但 role、task_id、attempt_id、validati
 
 `agent/agent/orchestration/models.py` 已定义 Task、TaskSpec、Attempt、ArtifactSnapshot、ValidationReport 和 PlannerDecision。`TaskCoordinator` 是唯一 Ledger 写入入口。
 
+`TaskLedger.root_objective` 是只读派生属性：有 Root Task 时始终读取其当前 `TaskSpec.objective`，只有无 Root Task 的旧 Ledger 才回退到历史 `mission` 字段。Ledger 正常提交时会将兼容 JSON 字段 `mission` 归一为当前 `root_objective`，不另建第二套 Root 状态。`root_completion()` 是正式读取入口，`mission_completion()` 仅作兼容代理；Runner 优先调用新接口，对只有旧方法的 Coordinator stub 回退兼容。GoalTree 缺失后的重建同样使用 `root_objective`，因此 Root revise 后不会恢复旧目标。
+
 GoalTree 仍保留任务树展示和焦点能力，但 explicit 模式不向 Planner 暴露旧 `goal` 写入工具。Coordinator 先更新 Ledger，再以 best-effort 方式投影 Goal 状态；Ledger 仍是唯一状态真相。所有自动投影失败都只记录警告，不会把已提交的命令表现成失败；后续可用严格执行的 `reconcile_goal_tree()` 修复不一致。
 
 ### 3.4 Worker 和 Validator 通过 LocalAgentExecutor 运行
 
-`agent/agent/orchestration/executor.py` 为两种角色创建本地 Sub-Trace：
+`agent/agent/orchestration/executor.py` 的 `LocalAgentExecutor` 为 Agent-mode 执行创建本地 Sub-Trace：
 
 - 新 Worker Attempt 默认新 Trace；仅 repair 可经 Coordinator 校验后续用原 Worker Trace；
-- 每次 Validation 都创建新 Validator Trace；
+- 每次 Agent-mode Validation 都创建新 Validator Trace；deterministic mode 只有独立 Validation record 和执行身份，不调用模型、不创建实际 Trace；
 - Worker 必须以 `submit_attempt` 结束；
 - Validator 必须以 `submit_validation` 结束；
 - 两个提交工具都是 terminal tool，成功提交一次后立即结束当前 Agent Loop。
 
-V1 explicit 只支持本地 Sub-Trace，`remote_*` Worker 或 Validator 会被拒绝；远程 Agent 仍走 legacy 路径。
+explicit 闭环只支持本地 Sub-Trace，`remote_*` Worker 或 Validator 会被拒绝；远程 Agent 仍走 legacy 路径。`LocalAgentExecutor` 和 `OperationRuntime` 都是进程内实现：Ledger 中的 Operation 可持久化，但正在运行的模型调用不能跨进程接管。
 
 ### 3.5 独立 Task 批量调度已实现
 
@@ -137,9 +140,11 @@ TaskConflict、单个 Task 预留异常和单个执行周期内的 Artifact/框
 
 ### 3.6 端口、默认适配器和兼容边界已明确
 
-V1 已定义 TaskStore、ArtifactStore、AgentExecutor、ToolPolicy 和 EventSink Protocol，并提供文件存储、本地执行、默认权限和 JSONL 事件实现。
+当前已定义 TaskStore、ArtifactStore、AgentExecutor、ToolPolicy、EventSink、ValidationPolicy、DeterministicValidator 和 EvidenceProvider 等通用端口，并提供文件存储、本地执行、默认权限、默认完整 Validator 策略及规则型确定性 Validator。
+
+Orchestration Event 的默认真源是 `FileSystemTaskStore` 在 Ledger 提交中原子写入的 durable journal。`wire_orchestration(..., event_sink=None)` 默认不生成重复 `events.jsonl`；`TraceEventSink` 仅是 Host 显式注入时启用的 best-effort 兼容镜像。
 
-`RunConfig.completion_policy` 默认仍是 `legacy_auto`。新闭环必须显式使用 planner preset、`explicit_validation` 并调用 `wire_orchestration()`。旧 `agent`、`evaluate`、`goal`、Trace 读取和 project_name 入口保持兼容。
+`RunConfig.completion_policy` 默认仍是 `legacy_auto`。新闭环必须显式使用 planner preset、`explicit_validation` 并完成 Coordinator、Executor 与 Runner 的等价装配；`wire_orchestration()` 是标准便利路径，自定义验证策略时也可由可信 composition root 直接构造并绑定。旧 `agent`、`evaluate`、`goal`、Trace 读取和 project_name 入口保持兼容。
 
 ## 四、V1 已解决的原始问题
 
@@ -161,7 +166,7 @@ Worker Trace completed
 
 ### 4.2 正式 Validator 与旧 evaluate 已分开
 
-V1 已增加 validator preset、独立 Validator Trace、固定 Snapshot 输入和 `submit_validation` 结构化协议。运行状态 error/stopped/expired 与评审结论 failed/inconclusive 分开保存。
+V1 已增加 validator preset、独立 Validation record、固定 Snapshot 输入和 `submit_validation` 结构化协议。Agent mode 使用独立 Validator Trace；deterministic mode 使用独立执行身份但不创建模型 Trace。运行状态 error/stopped/expired 与评审结论 failed/inconclusive 分开保存。
 
 旧 `evaluate()` 仅在 `legacy_auto` 中保留原语义，不参与 explicit 闭环。
 
@@ -173,7 +178,7 @@ legacy 模式仍保留原 tools/tool_groups 并集行为，避免旧业务立即
 
 ### 4.4 父任务自动完成已关闭
 
-GoalTree 的旧级联行为保留为 legacy 默认。Coordinator 投影 Goal 时始终传入 `cascade_completion=False`。子 Task 全部 completed 后，父 Task 只从 `waiting_children` 进入 `needs_replan`，不会自动 completed。
+GoalTree 的旧级联行为保留为 legacy 默认。Coordinator 投影 Goal 时始终传入 `cascade_completion=False`。直接子 Task 全部进入 terminal 状态（completed/cancelled/superseded）后，父 Task 只从 `waiting_children` 进入 `needs_replan`，不会自动 completed。
 
 ### 4.5 repair 续用已进行身份校验
 
@@ -187,7 +192,7 @@ Ledger commit 成功后不会因观测失败而回滚，因此 Ledger 始终是
 
 ### 4.7 核心回归测试已建立
 
-当前 `agent/tests` 共有 49 个测试用例，覆盖状态机、Ledger/Snapshot、terminal tool、角色权限、Worker→Validator→Decision 闭环、repair/retry/revise/split/revalidate、并行异常隔离、Goal 投影、批次结果持久化故障、幂等请求绑定与并发重放、legacy 真实执行和 Host 解耦。
+当前 `agent/tests` 已覆盖状态机、Ledger/Snapshot、terminal tool、角色权限、Worker→Validator→Decision 闭环、repair/retry/revise/split/revalidate、并行异常隔离、Goal 投影、Root revise、子 Decision 冻结绑定、Background Operation、V2 API/SDK、Event/Trace 关联、幂等并发重放、ValidationPolicy/Evidence Port、legacy 真实执行和 Host 解耦。
 
 ## 五、目标架构
 
@@ -204,7 +209,7 @@ flowchart TD
     Executor --> Worker[Worker Sub-Trace]
     Worker --> Submission[submit_attempt]
     Submission --> Snapshot[ArtifactSnapshot Manifest]
-    Snapshot --> Validator[Validator Sub-Trace]
+    Snapshot --> Validator[Agent-mode Validator Sub-Trace / deterministic rule execution]
     Validator --> Report[ValidationReport]
 
     Report --> Runner
@@ -212,10 +217,11 @@ flowchart TD
     Decision --> Ledger
 
     Coordinator --> TraceStore[TraceStore]
-    Coordinator --> EventSink[TraceEventSink]
+    Coordinator --> Journal[TaskStore Durable Event Journal]
 
     Host -.注入.-> Tools[Business Tools]
     Host -.注入.-> ArtifactStore[ArtifactStore]
+    Host -.可选注入.-> EventSink[External / Trace Event Sink]
     Tools -.read capability.-> Validator
 ```
 
@@ -303,7 +309,8 @@ Coordinator 不是 Agent，而是一层确定性程序。
 - 绑定 Task 版本和固定输出快照；
 - 在 Worker、Validator 和主 Agent 之间传递正确上下文；
 - 防止重复请求产生重复执行；
-- V1 归一化 executor 返回的 failed、error、stopped 和 expired 状态；主动超时、后台 stop/resume 和进程重启恢复属于 V2；
+- 归一化 executor 返回的 failed、error、stopped 和 expired 状态，并管理可持久化 Background Operation 的 dispatch/revalidate、deadline、stop/resume 和显式恢复；
+- 恢复时不猜测旧模型调用是否产生了外部副作用，也不自动重跑模型；Agent 执行仍受制于当前进程的 `OperationRuntime`；
 - 保证只有主 Agent Decision 能完成 Task。
 
 Agent 负责判断，Coordinator 负责守规则。
@@ -347,7 +354,7 @@ Worker 负责执行一次 Task Attempt。
 
 ### 7.5 Validator
 
-Validator 使用独立 Trace 和独立上下文进行评估。
+Agent-mode Validator 使用独立 Trace 和独立上下文进行评估；deterministic Validator 不调用 AgentRunner，但仍有独立 Validation record、冻结计划和执行身份。
 
 代码上它与主 Agent 共用完整 AgentRunner，因此可以在一次 Validation 内自主安排核验步骤、多轮推理并多次调用已授权只读工具。但它不是业务 Planner，不能规划任务树、派发 Worker/Validator、创建 SubAgent 或作出 Task Decision。
 
@@ -371,7 +378,7 @@ Validator 使用独立 Trace 和独立上下文进行评估。
 - 发布输出；
 - 完成 Task。
 
-每次 Validation 都使用新 Trace，一轮内只能成功调用一次 `submit_validation`，提交后立即结束本轮 Agent Loop。Validator 不能自己发起第二轮验证。
+每次 Agent-mode Validation 都使用新 Trace，一轮内只能成功调用一次 `submit_validation`，提交后立即结束本轮 Agent Loop。Validator 不能自己发起第二轮验证。deterministic mode 由 Coordinator 调规则引擎并直接提交结构化结果，没有聊天轮次。
 
 ## 八、核心对象
 
@@ -401,7 +408,15 @@ Attempt 表示一个 Worker 对某个 Task 版本做过的一次执行。
 - 使用不同模型重做；
 - 使用不同工具组合重做。
 
-每个 Attempt 都绑定自己的 Worker Trace。只有成功调用 `submit_attempt` 的 Attempt 才会绑定新提交清单快照；failed、stopped 或 expired Attempt 只保留状态、错误和 Trace，不生成 Snapshot。V1 ArtifactSnapshot 冻结的是 summary、artifact_refs 和 evidence_refs 的规范化 manifest 及 SHA-256，不复制外部产物字节。
+每个 Attempt 都绑定自己的 Worker Trace。只有成功调用 `submit_attempt` 并提交 Ledger 的 Attempt 才会绑定 `snapshot_id`；failed、stopped 或 expired Attempt 不绑定 Snapshot。由于 freeze 先于 Ledger commit，后续所有权/CAS 失败可能在 ArtifactStore 留下可清理的孤儿 Snapshot，不能将其自动挂到其他 Attempt。V1 ArtifactSnapshot 冻结的是 summary、artifact_refs 和 evidence_refs 的规范化 manifest 及 SHA-256，不复制外部产物字节。
+
+Attempt 创建时还会冻结 `accepted_child_decision_ids`，作为父 Worker 输入的因果绑定：
+
+- `None`：升级前的旧 Attempt 没有记录，历史输入未知；
+- `()`：新 Attempt 明确没有直接子任务输入；
+- 非空 tuple：按直接子 Task 的 `display_path` 顺序保存已 completed 子 Task 的有效 ACCEPT Decision ID；cancelled/superseded 子 Task 不提供 Decision 输入。
+
+Worker 只能从该冻结列表解析子结果，不扫描“当前最新子任务状态”。Coordinator 会校验 ID 唯一、顺序正确、属于直接子 Task、action=ACCEPT，且能闭合到该子 Task 的 Decision→Attempt→Validation→ArtifactSnapshot。遗留 RUNNING Attempt 若该字段为 `None`，不猜测输入，而是以 `PROTOCOL_VIOLATION` 失败并进入正常重新规划；新 Attempt 会记录完整绑定。
 
 ### 8.3 Validation
 
@@ -451,6 +466,12 @@ V1 不定义独立 EvidenceRef 类，evidence_refs 复用 ArtifactRef 结构。
 - Trace；
 - 人工复核。
 
+### 8.7 Background Operation
+
+BackgroundOperation 表示一次可异步控制的 dispatch 或 revalidate 命令，是持久化控制面对象，不是 Task/Attempt/Validation 的第二份状态。它记录 Operation kind/status、关联 task/attempt/validation IDs、result reference、deadline、execution epoch、错误和时间戳。
+
+request 和 request fingerprint 用于持久幂等和恢复校验，但不在 `OperationView` 和 Mission Snapshot 的 wire 响应中公开。`execution_epoch` 使 stop/resume 后的旧运行任务无法越过所有权边界提交迟到结果。
+
 ## 九、状态模型
 
 ### 9.1 Task 状态
@@ -514,7 +535,7 @@ inconclusive   无法判断或证据不足
 4. Validation Run Status=completed 后，无论 Verdict 是什么，都进入 awaiting_decision；
 5. 普通 accept 只允许绑定当前 Task Version、当前 Attempt Snapshot，以及 Run Status=completed 且 Verdict=passed 的 Validation；
 6. 只有主 Agent 的有效 accept Decision 能把 Task 写成 completed；
-7. 子 Task 全部 completed 后，父 Task 从 waiting_children 进入 needs_replan，绝不自动 completed；
+7. 直接子 Task 全部 terminal（completed/cancelled/superseded）后，父 Task 从 waiting_children 进入 needs_replan，绝不自动 completed；父 Attempt 的冻结输入只包含 completed 子 Task 的有效 ACCEPT Decision；
 8. 旧 Task 版本的 Validation 不能用于新版本；
 9. 执行失败和评估异常不能伪装成业务不通过；
 10. 重复请求不能重复创建 Attempt 或重复接受输出。
@@ -570,11 +591,13 @@ sequenceDiagram
 
 ## 十一、Validator 设计
 
-### 11.1 V1 的验证方式与后续分层
+### 11.1 已实现的验证分层
+
+Coordinator 现在会通过 `ValidationPolicy` 为每次 Validation 冻结可序列化 `ValidationPlan`。默认 `DefaultValidationPolicy` 仍选择完整 Validator Agent，因此不改变 V1 的默认行为；Host 也可注入 `RuleBasedDeterministicValidator` 及其规则，运行确定性验证。
 
-V1 每次都运行完整 Validator Agent。Validator 可通过 Host 注入的 read capability 工具执行格式、文件、哈希、接口和测试结果检查；Coordinator 只校验结构化报告是否覆盖验收条件，以及总体 passed 是否与硬性条件冲突。
+Agent Validator 可通过 Host 注入的 read capability 工具执行格式、文件、哈希、接口和测试结果检查；Coordinator 校验结构化报告是否覆盖验收条件，以及总体 passed 是否与硬性条件冲突。第二模型、人工复核和更完整的风险分层治理仍是后续能力。
 
-独立 DeterministicCheck 引擎、按风险选择轻量检查/完整 Validator、第二模型和人工复核策略属于 V2/V3，不是 V1 已实现组件。
+组装边界必须单独说明：`TaskCoordinator.__init__()` 已支持传入 `validation_policy`、`deterministic_validator` 和 `evidence_provider`，但当前便利函数 `wire_orchestration()` 尚未暴露这三个参数。需要自定义策略的 Host 必须在 composition root 直接构造 Coordinator 或完成对 wiring 的通用扩展，不能只写配置就假设已生效。
 
 ### 11.2 Validator 必须评估固定快照
 
@@ -632,7 +655,7 @@ Validator 可以在 `criterion_results.reason` 和 `summary` 里说明失败位
 
 Coordinator 必须检查 Decision 是否适用于当前状态。例如已经 superseded 的 Task 不能再次 accept，已经修改验收条件的 Task 不能继续使用旧 Validation。
 
-`revalidate` 不通过 `task_decide` 执行，而是 Planner 调用独立 `validate_attempt` 工具。它只允许在上一次 Validator 为 error、stopped 或 expired，且 Task 处于 needs_replan 时，对未变化 Snapshot 创建新 Validator Trace。failed/inconclusive 是有效评审结论，不能使用 revalidate 绕过主 Agent 重规划。
+`revalidate` 不通过 `task_decide` 执行，而是 Planner 调用独立 `validate_attempt` 工具。它只允许在上一次 Validator 为 error、stopped 或 expired，且 Task 处于 needs_replan 时，对未变化 Snapshot 创建新 Validation；Agent mode 创建新 Validator Trace，deterministic mode 不创建模型 Trace。failed/inconclusive 是有效评审结论，不能使用 revalidate 绕过主 Agent 重规划。
 
 “补证据”不是 V1 的独立 DecisionAction。主 Agent 应通过 `task_plan` 创建补证据 Task，或使用 split、revise、block 组合表达。
 
@@ -697,7 +720,7 @@ New Attempt → New Worker Sub-Trace
 
 ### 13.4 Validator 默认每次新建上下文
 
-每次 Validation 默认使用新 Trace，避免上一轮结论影响新一轮证据判断。
+每次 Agent-mode Validation 默认使用新 Trace，避免上一轮结论影响新一轮证据判断。deterministic mode 不创建模型 Trace。
 
 框架可以复用 Validator Preset，但不复用其评估聊天历史。
 
@@ -781,13 +804,13 @@ V1 已提供 TaskStore Protocol 和 FileSystemTaskStore。V2 可替换为关系
 
 框架只认识 Artifact Reference，不认识具体内容结构。
 
-### 15.3 Evidence Port（V2 扩展）
+### 15.3 Evidence Port
 
-负责向 Validator 提供业务证据查询能力。V1 不定义独立证据读取端口；证据使用 `evidence_refs` 字段中的 ArtifactRef 和经 capability 授权的只读工具提供。
+EvidenceProvider/EvidencePort 及 `EvidenceQuery`/`EvidenceResponse` 已实现，Coordinator 会校验 root、task、attempt、validation、snapshot 和 Validator 执行身份归属，并执行每次 Validation 的查询次数、单次数量和超时限制。查询结果会按 Validation 持久化和幂等复用。
 
-实际实现可以是 ToolRegistry 中注册的只读工具，也可以是业务提供的适配器。
+当前缺口是 Agent 工具集尚未暴露通用 `query_evidence` terminal/non-terminal 工具，`wire_orchestration()` 也尚未接收 EvidenceProvider。因此 Host 可直接调用 Coordinator 端口或继续使用 capability 授权的只读业务工具，但不应宣称 Validator Agent 已能自动调用该通用 Evidence Port。
 
-### 15.4 Validation Policy（V2 扩展）
+### 15.4 Validation Policy
 
 用于定义：
 
@@ -797,7 +820,7 @@ V1 已提供 TaskStore Protocol 和 FileSystemTaskStore。V2 可替换为关系
 - 哪些 Task 需要人工复核；
 - 最大验证次数和成本。
 
-V1 没有 ValidationPolicy 类或策略引擎，每次都启动完整 Validator。以上风险分层属于 V2/V3。
+当前已有 `ValidationPolicy`、冻结 `ValidationPlan`、默认 Agent 验证和规则型确定性验证。第二模型、人工复核、自动风险分层和总验证成本上限仍属于 V2/V3 后续治理。
 
 ### 15.5 Tool Policy
 
@@ -807,7 +830,7 @@ Tool Policy 负责角色到工具权限的映射，并在工具执行前进行
 
 ### 15.6 Event Sink
 
-当前 TraceEventSink 输出的主要事件包括：
+当前 Orchestration Event 已使用 schema v2，旧 v1 事件仍可读，sequence/cursor 语义不变。主要事件包括：
 
 ```text
 ledger_created
@@ -824,9 +847,12 @@ validation_error
 task_cycle_failed
 dispatch_completed
 goal_projection_linked
+execution_stats_recorded
 ```
 
-`planner_decision` 的 action/payload 表达 accept、block、split 等具体动作，V1 不为每个动作另造事件名。当前实现为本地 `events.jsonl`；稳定的对外订阅协议属于 V2。
+Event 只是变化通知和实体引用，不复制 Task、Decision 或 Validation 对象：Attempt 事件带 `task_id + attempt_id`，Validation 带 `task_id + attempt_id + validation_id`，Decision 带 `task_id + decision_id`，Task 创建带 `parent_task_id + task_ids`，Operation 复用 envelope 顶层 `operation_id`。`validation_restarted` 和 `execution_stats_recorded` 也会补齐实体关联；没有实际状态变化时不产生重复事件。
+
+`planner_decision` 通过 Decision 实体表达 accept、block、split 等具体动作，不为每个动作另造事件名。`FileSystemTaskStore` 内的 durable journal 是默认唯一真源；`TraceEventSink` 保留为显式兼容适配器或外部 Sink 示例，不再默认写重复 `orchestration/events.jsonl`。
 
 ## 十六、存储、恢复和可观测性
 
@@ -846,22 +872,23 @@ goal_projection_linked
 
 V1 Ledger 不保存完整 resolved tool policy 快照；可审计的策略快照属于 V2。
 
-### 16.2 V1 已实现文件存储
+### 16.2 已实现的文件存储
 
-V1 已定义 TaskStore/ArtifactStore/EventSink 端口，并提供 FileSystemTaskStore、FileSystemArtifactStore 和 TraceEventSink。默认目录为：
+当前已定义 TaskStore/ArtifactStore/EventSink 端口，并提供 FileSystemTaskStore、FileSystemArtifactStore 和可选 TraceEventSink。默认持久目录为：
 
 ```text
 .trace/{root_trace_id}/orchestration/
 ├── ledger.json
-├── artifacts/{snapshot_id}.json
-└── events.jsonl
+└── artifacts/{snapshot_id}.json
 ```
 
-`ledger.json` 使用临时文件加 `os.replace`、每 root trace 的 `asyncio.Lock` 和 revision 乐观锁。这些保证仅针对单进程 V1。
+durable Event journal 作为 `ledger.json` 内部数据与相同 Ledger revision 原子提交，不需要默认平行 JSONL 文件。`ledger.json` 使用跨进程文件锁、revision CAS、临时文件、`fsync` 和 `os.replace`；Artifact 也有独立文件锁和 first-write-wins 约束。因此该实现支持同一主机的多进程安全读写，但不提供跨机共享语义。
 
-### 16.3 生产化使用共享存储
+### 16.3 部署边界
 
-多进程、多实例或跨机器运行时，需要共享持久化能力，否则会出现：
+对于单机、持久磁盘、单活 Host 的长期部署，当前 FileSystemTaskStore/FileSystemArtifactStore 是有效选择，不必为了“生产”标签强制换成数据库。Host 必须保证相同持久目录、备份、权限及单活运行约束。
+
+如果将来要求多主机、水平多实例或远程 Worker，则需要共享持久化、分布式协调和运行时所有权机制，否则会出现：
 
 - 一个实例看不到另一个实例创建的 Task；
 - 进程重启后无法恢复运行状态；
@@ -869,7 +896,23 @@ V1 已定义 TaskStore/ArtifactStore/EventSink 端口，并提供 FileSystemTask
 - 重复调度同一个 Attempt；
 - 多个主 Agent同时接受同一个输出。
 
-### 16.4 每一步必须可追踪
+### 16.4 原子 Mission 读取和关联 Trace
+
+当前已提供可选 FastAPI V2 适配器和 `OrchestrationClient`，包括：
+
+- `GET /api/v2/capabilities`；
+- `GET /api/v2/roots/{root_trace_id}/snapshot`：单次 `TaskStore.load()` 返回同一 revision 的 Task、Attempt、Validation、Decision 和 Operation；
+- `GET /api/v2/roots/{root_trace_id}/completion`：返回 Root objective、status、blocked reason 和已接受结果摘要；
+- `GET /api/v2/roots/{root_trace_id}/snapshots/{snapshot_id}`：返回 Artifact manifest 的 hash 和引用，不公开重复 `normalized_content`；
+- Task/Attempt/Validation 查询、Operation start/poll/stop/resume 和 cursor Event 读取。
+
+`MissionSnapshotView` 的集合按 `created_at + id` 稳定排序，`AttemptView` 公开 `accepted_child_decision_ids`，`PlannerDecisionView` 提供 Decision 关联。SDK 已提供 `get_mission_snapshot()`、`get_root_completion()`、`get_artifact_snapshot()`、Event watch 和关联 Trace 查询。
+
+通用 TraceStore/API 已支持 `agent_role`、`parent_trace_id`、`root_trace_id`、`task_id`、`attempt_id`、`validation_id` 和 `operation_id` 过滤。文件 TraceStore 在扫描 meta 时先过滤、再排序和应用 `limit`，Trace detail/WebSocket 也通过带过滤条件的 Store 查询获取子 Trace，不先截断一批无关 Trace 再过滤。
+
+该路由是可选适配器：业务 Host 需要对已组装的 Coordinator 调用 `create_orchestration_router()` 并显式 `include_router()`。当前根 `agent/api_server.py` 不会自动挂载 Orchestration V2 路由，Trace API 也需由 Host 保证与 SDK 使用同一服务基址。
+
+### 16.5 每一步必须可追踪
 
 一次完整闭环应能追踪：
 
@@ -879,14 +922,14 @@ Task
 → Worker Trace
 → Output Snapshot
 → Validation
-→ Validator Trace
+→ Agent mode: Validator Trace / deterministic mode: Validation execution identity
 → Planner Decision
 → 下一 Task 状态
 ```
 
 ## 十七、并行和异步边界
 
-### 17.1 V1 使用现有同步闭环
+### 17.1 前台闭环和并行边界
 
 同一个 Task 的顺序固定为：
 
@@ -894,19 +937,22 @@ Task
 Worker → Validator → Planner Decision
 ```
 
-V1 当前使用 `await` 模式跑完工具内的同步闭环，没有引入分布式队列。
+前台 `dispatch_tasks` 使用 `await` 模式跑完工具内闭环，没有引入分布式队列。
 
 多个互不依赖的 Task 由 Coordinator 使用 Semaphore 并发调用 LocalAgentExecutor，不复用 legacy `agent()` 的多分支聚合语义。Task 预留和执行周期中的分支异常会逐 Task 隔离，其他 Task 继续执行，成功返回时顺序与输入一致。批次级 `dispatch_completed` 幂等缓存写入失败时返回已完成的逐 Task 结果；相同幂等请求重试会复用原 Attempt/Validation 并重新保存整批结果，不重复运行 Agent。
 
-### 17.2 后续增加后台任务接口
+### 17.2 Background Operation 已实现
+
+当前 `BackgroundOperation` 和 `OperationController` 已提供：
 
-当主 Agent需要在 Worker 或 Validator 运行期间继续规划其他 Task 时，再提供：
+- start：启动 dispatch 或 revalidate Operation；
+- poll/wait：查询持久状态和结果引用；
+- event：通过 durable Event journal 通知 Operation 状态变化；
+- stop：先持久化 stop intent 和 execution epoch，再通知当前进程的 Agent Task；
+- recover：只把 durable Operation 与丢失的进程内 Task 对齐为 pending/stopped/failed 等安全状态，不调用模型；
+- resume：只接续框架判定为尚未安全启动的 stage，跳过已持久化阶段；已经启动后停止的模型 stage 返回 `resume_not_safe`，交由 Planner retry/replan。
 
-- start：启动后台 Attempt 或 Validation；
-- poll：查询状态；
-- event：完成后通知主 Agent；
-- stop：停止运行；
-- resume：恢复允许继续的运行。
+Operation 记录、幂等命令和 execution epoch 在 Ledger 中可持久化；`OperationRuntime` 中的 `asyncio.Task` 不可持久化。崩溃恢复不猜测未提交模型调用的外部副作用，也不会在无 Host/Planner 决策时自动重跑模型。
 
 ### 17.3 分布式调度放在 V3
 
@@ -924,9 +970,9 @@ explicit_validation
 使用 Task、Attempt、Validation、Decision 的显式完成协议
 ```
 
-框架 `RunConfig` 默认仍使用 `legacy_auto`。采用 V1 的新 Host 必须显式选择 planner preset 和 `explicit_validation`，并先调用 `wire_orchestration()`；缺少 Coordinator 时启动失败，不会静默退回 legacy。
+框架 `RunConfig` 默认仍使用 `legacy_auto`。采用 V1 的新 Host 必须显式选择 planner preset 和 `explicit_validation`，并先完成 Coordinator/Executor/Runner 等价装配；标准路径是 `wire_orchestration()`。缺少 Coordinator 时启动失败，不会静默退回 legacy。
 
-旧 evaluate 暂时保留，新 Validator 使用独立工具名、独立 Trace 类型和独立结构化结果。等旧调用完成迁移后，再决定是否废弃 evaluate。
+旧 evaluate 暂时保留，新 Validator 使用独立工具名和独立结构化结果；Agent mode 使用独立 Trace 类型，deterministic mode 只有 Validation execution identity。等旧调用完成迁移后，再决定是否废弃 evaluate。
 
 ## 十九、V1 实际代码落点
 
@@ -938,7 +984,14 @@ agent/agent/orchestration/
 ├── protocols.py       # TaskStore/ArtifactStore/AgentExecutor/ToolPolicy/EventSink
 ├── config.py          # 并行度、repair 次数和默认 preset
 ├── state_machine.py   # 法定 Task 状态转换
-├── store.py           # 文件 Store 和 JSONL EventSink
+├── store.py           # 文件 Store、durable journal 和可选 JSONL 兼容 Sink
+├── operations.py      # 持久化 Background Operation 状态与恢复控制
+├── runtime.py         # 进程内 asyncio Operation 执行注册表
+├── validation_policy.py # ValidationPolicy 和确定性 Validator
+├── evidence.py        # EvidenceProvider/EvidencePort 数据合同
+├── api_v2.py          # 可选 FastAPI V2 路由
+├── client_v2.py       # 异步 Python SDK
+├── wire.py            # 严格对外 View/Request 模型
 ├── policy.py          # capability 权限解析
 ├── executor.py        # 本地 Worker/Validator Sub-Trace
 ├── coordinator.py     # 唯一 Ledger 状态写入入口
@@ -974,23 +1027,23 @@ agent/agent/orchestration/
 - Worker 不能创建孙 Agent；
 - Task、Attempt、Validation、Decision 分离；
 - Worker 成功调用 `submit_attempt` 后进入 awaiting_validation；未提交、异常、停止或过期则进入 needs_replan；
-- 独立 Validator Trace；
+- 独立 Validation record；Agent mode 另有独立 Validator Trace，deterministic mode 无模型 Trace；
 - 结构化 Validation Report；
 - `task_decide` 支持 accept、repair、retry、revise、split、block、unblock、cancel、supersede；
 - `validate_attempt` 支持 Validator error/stopped/expired 后对未变 Snapshot 重新评估；
 - 父 Task 不自动完成；
 - Worker 默认新 Trace；
-- Validator 默认新 Trace；
+- Agent-mode Validator 默认新 Trace；
 - Planner、Worker、Validator 工具权限隔离；
 - 定义最小 TaskStore Protocol，并提供文件系统默认实现；
 - 定义最小 ArtifactStore、AgentExecutor、ToolPolicy 和 EventSink 协议及默认实现；
 - 使用不可变 AttemptSubmission manifest Snapshot，外部产物通过 version/digest 保证不可变；
-- 提供单进程幂等键，防止同一请求重复创建 Attempt、Validation 或 Decision；
+- 提供 Ledger 持久化 CommandRecord、请求 fingerprint 和 revision CAS，防止同一请求重复创建 Attempt、Validation、Decision 或 Operation；
 - orchestration 内核不再动态 import examples 或业务包；
 - `legacy_auto` 与 `explicit_validation` 双模式；
-- 建立 49 个当前回归用例；
+- 建立覆盖 V1 闭环及 V2 第一阶段能力的回归用例；
 - 批量 Task 在预留和执行周期内按分支隔离异常，正常返回时顺序与输入一致；批次幂等缓存写入失败时仍返回结果，重试不重复执行 Agent；
-- 明确 V1 限制：仅本地 Sub-Trace、同步工具调用、单进程文件存储、无新 Task HTTP API。
+- 明确 V1 执行边界：仅本地 Sub-Trace，不支持远程 Worker/Validator 或分布式队列。`FileSystemTaskStore` 与 `FileSystemArtifactStore` 已具备同机锁/CAS或 first-write-wins 保护；`FileSystemTraceStore` 不具备同等级的跨进程锁与原子替换保证，因此完整 Agent 运行仍要求 Host 单活。V2 HTTP/SDK 已作为可选 Host 适配器落地。
 
 ### 20.2 Framework V2：通用扩展接口与可靠恢复
 
@@ -1000,17 +1053,21 @@ agent/agent/orchestration/
 
 当前 FileSystemTaskStore 是单机 Host 参考实现，通过文件锁、CAS revision 和原子替换保证同一主机多进程安全；恢复不会猜测已经启动的模型调用是否产生过外部副作用，也不会自动重跑模型，必须由 Host 显式 resume 或由 Planner 重新规划。共享数据库、后台队列、Lease/心跳、多实例协调、多租户和人工复核仍属于后续 V2 适配器或 V3 治理范围。
 
-包括：
+已落地内容：
 
-- TaskStore、Artifact、Evidence 和 ToolPolicy 的生产级可插拔实现与业务适配器；
-- Validation Policy；
-- 通用 API 和 Python SDK；
-- 把 V1 本地 EventSink/JSONL 升级为稳定对外事件协议；
-- 跨进程、可持久化的幂等和防重复执行；
-- 超时和重试限制；
-- 进程重启后的状态恢复；
-- start、poll、event、stop、resume；
-- 统一成本、耗时、模型和失败原因统计。
+- 通用 API、严格 wire view 和异步 Python SDK；
+- Mission Snapshot、Root Completion、Artifact detail、Capabilities 和关联 Trace 查询；
+- Event schema v2、稳定 cursor 和 Ledger durable journal；
+- 持久化 CommandRecord、Background Operation、deadline、start/poll/stop/resume 和显式恢复；
+- 冻结 ValidationPlan、ValidationPolicy、确定性 Validator 和受归属/预算约束的 Evidence Port；
+- Attempt/Validation 的模型、Token、成本、耗时和失败分类。
+
+仍需由 Host 完成或后续扩展的内容：
+
+- 显式挂载 V2 路由并与 Trace API 组装为同一服务；
+- 将 ValidationPolicy、DeterministicValidator 和 EvidenceProvider 暴露到便利 wiring，并为 Validator 提供通用 Evidence 工具；
+- 业务适配器、风险分层策略、总预算和完整监控告警；
+- 需要跨机扩展时的共享 Store、队列、Lease 和心跳。
 
 ### 20.3 Framework V3：分布式生产治理
 
@@ -1031,7 +1088,7 @@ agent/agent/orchestration/
 - 人工复核扩展点；
 - 完整监控和告警。
 
-## 二十一、V1 验收用例
+## 二十一、当前验收用例
 
 ### 21.1 完成语义
 
@@ -1048,7 +1105,7 @@ agent/agent/orchestration/
 - 同一个 Task 换 Worker 后产生新 Attempt；
 - 修改目标或验收条件后形成新 Task Version；
 - Task 被拆分后，子 Task分别执行和验证；
-- 子 Task全部完成后，父 Task 不自动完成；
+- 直接子 Task 全部 terminal 后，父 Task 不自动完成；
 - 被 superseded 的 Task 不能再次 accept。
 
 ### 21.3 上下文隔离
@@ -1057,7 +1114,7 @@ agent/agent/orchestration/
 - 同 Task、同版本的局部 repair 可以续用 Worker Trace，但必须创建新 Attempt，且只有成功提交才创建新 Snapshot；
 - revise、split 和 retry 默认创建新 Trace；
 - 改题后继续旧 Trace 必须被拒绝；
-- Validator 每次使用干净 Trace。
+- Agent-mode Validator 每次使用干净 Trace；deterministic mode 不创建模型 Trace。
 
 ### 21.4 权限
 
@@ -1093,6 +1150,21 @@ agent/agent/orchestration/
 - 业务存储通过 Protocol 或 Port 注入；
 - 框架在没有任何具体业务项目代码时可以独立运行测试。
 
+### 21.8 Root 和因果绑定
+
+- Root revise 后 `root_objective`、兼容 `mission` 字段和 GoalTree 重建都使用新目标；
+- `accepted_child_decision_ids=None`、空 tuple 和多个子 Decision 都有明确兼容语义；
+- 重复、乱序、跨 Task、非 ACCEPT 和无法闭合到 Attempt/Validation/Snapshot 的绑定必须拒绝；
+- 升级前 RUNNING Attempt 不从当前子任务状态猜测输入。
+
+### 21.9 API、Event 和 Trace
+
+- Mission Snapshot 只加载一次 Ledger，所有集合共享 revision，稳定排序且 wire schema 拒绝多余字段；
+- Root Completion 返回当前 Root objective，Artifact Snapshot 不存在时稳定返回 404；
+- Event v1/v2 混合数据保持 sequence/cursor 连续，无状态变化不追加新事件；
+- `event_sink=None` 时不生成重复 JSONL 镜像，显式 TraceEventSink 失败不回滚 Ledger；
+- Trace 关联过滤在 `limit` 前生效，即使有超过 1000 个无关 Trace 仍能找到目标。
+
 ## 二十二、主要风险和控制方式
 
 ### 22.1 状态模型变复杂
@@ -1101,11 +1173,11 @@ agent/agent/orchestration/
 
 ### 22.2 Validator 与 Worker 可能有共同偏差
 
-当前控制：Validator 使用独立 Trace、固定 Snapshot 和只读工具，框架保留评估历史。独立确定性检查引擎、第二模型和人工复核策略属于 V2/V3。
+当前控制：Agent-mode Validator 使用独立 Trace、固定 Snapshot 和只读工具；deterministic mode 使用独立 Validation record/execution identity；框架保留评估历史，并可通过 ValidationPolicy 选择规则型确定性验证。第二模型和人工复核策略属于 V2/V3 后续治理。
 
 ### 22.3 Validator 增加成本和延迟
 
-当前控制：Host 可通过 validator preset 选择模型、轮次和工具。按风险自动选择规则检查、完整 Validator 或高级复核的 ValidationPolicy 属于 V2。
+当前控制：Host 可通过 validator preset 选择模型、轮次和工具，也可通过 ValidationPolicy 选择 Agent 或确定性验证。自动风险分级、第二模型、人工复核和总成本预算仍属于后续治理。
 
 ### 22.4 主 Agent上下文越来越长
 
@@ -1162,4 +1234,4 @@ Main Agent Planning
 → Replan or Complete
 ```
 
-下一阶段不是重做 V1，而是二选一或并行推进：Host 业务接入这个协议，或进入 V2 的公开 API、共享存储、恢复和策略化验证。框架只负责保证通用协议正确；业务项目负责告诉框架“做什么、用什么工具、如何验收、输出保存在哪里”。
+下一阶段不是重做 V1 或重复开发已有 V2 API，而是由 Host 业务接入当前协议，显式组装路由和策略端口，并在确有跨机需求时再演进共享存储和分布式执行。框架只负责保证通用协议正确；业务项目负责告诉框架“做什么、用什么工具、如何验收、输出保存在哪里”。