Plan、Goal 与 Todo

结论：Plan、Goal 与 Todo 不是同一种“计划状态”的三个名字

因此，“进入 Plan”不会创建 Goal，“创建 Goal”不会自动生成 Todo，Todo 中出现多个 in_progress 也不代表 Todo tool 自己并发执行。三者可以同时存在，但没有任何一者是另外两者的隐藏数据库或调度器。

1. 三套状态机的权威事实、有效期与执行者

三者都借 SessionEvent 获得重放能力，但“事件耐久”不等于“同样长期可见”。Plan 与 Goal 的当前状态跨 Turn 折叠；Todo 的事件也耐久，产品 projection 却有意把它解释成只站立到下一 Turn 的清单。

2. Plan 的双状态：已记录模式与待生效选择

plan/mode 是 log-only、非 Surface、last-write-wins 的布尔事件；没有记录时为 false。已提交值可以随 Session resume、Fork 与完整日志重放恢复。Controller 另有一个按 Session 键控的 WeakMap，保存尚未到提交边界的目标模式及是否需要给模型叙述切换。PLANSTATE-PLAN-STATE

3. Plan 改的是提示词，不是权限或工具目录

Active 时，plan:policy 在 system prompt order 50 渲染部署提供的 section；inactive 时贡献空文本。发布配置要求先探索、只做非变更检查、提交完整可执行计划，并明确禁止在 Plan 阶段用 Todo 代替最终计划。PLANSTATE-PLAN-ASSEMBLYPLANSTATE-SHIPPED-PLAN-POLICY

这个选择维持了 tool schema 与 Code Mode SDK 的前缀稳定性，但也意味着应用不能把“Plan chip 亮着”解释成“写操作在执行层必然被拒绝”。若部署需要硬只读，必须单独配置执行权限。

4. Plan 的三条控制面：命令进入、工具评审、服务直调

退出工具要求 trim 后以一级 # 标题开头。只有唯一一条 plan-review answer、唯一选择 Approve、且没有 custom text 才算同意；“Keep planning”、自定义反馈、重复或缺失 answer 都以失败 tool result 返回，让模型继续修订。批准只写一个 silent pending exit，当前 assistant tool batch 仍处于 Plan，下一 accepted pre-step 才切换。PLANSTATE-PLAN-CONTROLS

5. Plan 的 Web、projection 与崩溃恢复并不完全等价

plan projection 同时折叠 command/run(name="plan") 和 plan/mode：前者推导 wanted target，后者提交 active 并清空 wanted。因此它能从冷日志恢复 { active, pending }，并通过 history baseline 与 session/projection frame 分发给多个浏览器。PLANSTATE-PLAN-PROJECTION

Web 只在“有效目标”为 Plan 时显示 Plan × chip；点击通过 command Remote 执行 /plan off。同一 projection 还切换输入框 placeholder。Plan review 则由专用 decision panel 呈现 Approve、Keep planning 和讨论／dismiss；不认识 intent 的 provider 仍可退化成通用 options。PLANSTATE-PLAN-UIPLANSTATE-PLAN-REVIEW-UI

没有独立的 plan.get/plan.set 业务 API 家族：Web 使用通用 command Remote 加 projection；模型使用稳定的 exit tool；host 内插件使用 service。

6. Goal 是一个带 compare-and-set revision 的完整状态机

Goal identity 在多次修订间稳定，GoalRef { id, revision } 精确标识一个版本。Snapshot 每次都带 objective、phase、maxGoalRounds；blocked phase 额外且仅额外带 { code, message }。四个 phase 是 active、paused、blocked、complete。PLANSTATE-GOAL-TYPES

create → active(r1)
active → edit → active(r+1)
active → pause → paused(r+1)
active → block → blocked(r+1)
active|paused|blocked → complete(r+1)
active|paused|blocked --resume, capacity remains→ active(r+1)
any current → clear tombstone(r+1)
complete → create a fresh id at r1

7. Durable phase 与 process-local activation 是两条轴

Activation 从不写入日志。新 cache、每次 agent/session-start、driver 热加载与不确定失败都会 disarm；resume 则写一个新的 revision 并 arm。于是 resume、Fork 和进程重启可以恢复 objective、phase、revision、round count，却不会偷偷恢复自动执行 authority。PLANSTATE-GOAL-SERVICEPLANSTATE-GOAL-COMMIT

GoalService 还要求传入的是 AgentRegistry 中精确的 live object，而不仅是相同 id；create 之后的 edit、pause、resume、complete、block 与 clear 都用当前 GoalRef 做 CAS。多标签页、模型工具和人类命令同时修改时，先提交者推进 revision，后来的旧 ref 明确失败，而不是覆盖新状态。

8. Goal continuation driver：同一 Session、一个 reservation、逐轮 durability barrier

goal/change arms or revises goal
→ driver coalesces wakeups per exact Agent
→ wait until Agent idle and no competing queued human work
→ flush pending durable prefix
→ reserve {goalId, revision, roundsStarted + 1}
→ Agent.followup(<goal_round>...)
→ pre-step validates full message + live revision before and after downstream hooks
→ admitted user/message increments roundsStarted
→ whole Agent returns idle
→ flush the settled round before reserving the next one

每个 Agent 的 driver state 只允许一个 queued/claimed/admitted attempt。Prompt 把 JSON-quoted objective、round/maxGoalRounds 和“依据当前 workspace、工具结果、耐久状态验证进展”的指令写成普通 user message；它不创建新 Agent，也不复制 Session。PLANSTATE-GOAL-DRIVER

Round cap 是 admitted-round 数量上限，不是 token、费用或时间预算。到达上限时 driver 写 durable blocked，code 为 round-limit；测试源码要求恰好接纳 1..N 且不多发一轮。PLANSTATE-GOAL-DRIVER-TEST

9. Goal 工具的 authority 比 GoalService 本身更严格

Tool authority 通过 open Turn 内实际提交的 user/message.source 判定，而不是相信模型参数。Goal-round 必须匹配当前 id、revision 与 roundsStarted；自动 round 无权 edit、pause 或 resume。PLANSTATE-GOAL-AUTHORITYPLANSTATE-GOAL-TOOLS

10. Goal 的命令、Remote/API 与 Web UI 是三种不同能力面

/goal 在 command plane 内直接执行，不开启模型 Turn；Web 还把耐久 command/run 投影成右对齐的 command-input bubble。GoalBar 每次点击都从最新 projection 读取 CAS ref，并用同步 ref + React pending 做 single-flight；clear 成功后先本地隐藏该 id，等待 null projection 收敛。PLANSTATE-GOAL-COMMANDPLANSTATE-GOAL-COMMAND-UIPLANSTATE-GOAL-COMMAND-VIEWPLANSTATE-GOAL-UIPLANSTATE-GOAL-UI-REMOTE

Host mutation façade 会复用 live Agent 或冷恢复普通 Session，并拒绝仍属于 subagent routing 的 identity。它不复用模型工具的“direct human Turn”规则——这是受信控制面的直接 domain mutation。GoalError 当前统一映射为 wire internal，稳定 domain code 放在 details.goalCode；客户端必须看 details 才能区分 stale revision 等业务拒绝。PLANSTATE-GOAL-APIPLANSTATE-GOAL-API-ROUTINGPLANSTATE-GOAL-API-ERRORS

11. Goal 的失败、取消与并发恢复策略

Driver 的“串行”由每 Agent 的一个 attempt 和 coalesced run promise 保证；Goal mutation 的“并发”由 revision CAS 保证。它们解决的是不同问题。外部 LLM retry plugin 若在同一 Step 内成功恢复，原 reservation 仍可结算；driver 自己不会把未分类的异常重新排成新 round。PLANSTATE-GOAL-DRIVERPLANSTATE-GOAL-DURABILITY-TEST

12. Todo 是 whole-value replacement，不是任务数据库

todo_write({ todos }) 每次必须发送完整清单；成功后同步 append 一条 todo/write，当前值就是最后一条 snapshot。Item 只有规范化后的非空 content 与三态 status：pending、in_progress、completed。没有 id、priority、dependency、nesting、patch、delete-one 或 read-back operation。空数组是合法的显式空清单。PLANSTATE-TODO-TOOL

allowParallelInProgress 是必选部署决策。true 同时改变模型说明和验证，允许多个 active item；false 拒绝超过一个。发布的 base profile 选择 true。耐久 invariant 故意不按当前配置重验 active count，否则用宽松策略写出的旧日志会在以后收紧部署时无法重放。PLANSTATE-SHIPPED-TODO-POLICYPLANSTATE-TODO-INVARIANT

13. Todo 事件长期存在，standing projection 只活到下一 Turn

Turn N: todo_write(snapshot A)
        todo_write(snapshot B)   → projection = B
        turn/end                 → projection still B
Turn N+1: turn/start             → projection = null
        ... old todo/write events remain in the Session log

todos projection 在首次 write 前为 null，遇到 write 整值替换，遇到每个 turn/start 清空；它不在 turn/end 清空，因此完成清单在 Agent idle 后仍能显示，直到下一条人类或自动 goal round 真正开启新 Turn。冷读、resume 和 Fork 都按完整日志重做同一 fold。PLANSTATE-TODO-PROJECTION

Web TodoPanel 只读这个 projection：非空时显示折叠卡片、按状态计数并可展开所有项；另一个 todo_write tool row 从耐久 call arguments 生成 “done/total + 首个 active + 额外 active 数”摘要。前者显示被产品认定仍站立的清单，后者是历史工具调用，两者寿命不同。PLANSTATE-TODO-UIPLANSTATE-TODO-ROW

14. “Todo 允许并行”与“Todo tool 并行执行”恰好相反

ToolRuntime 只有定义显式提供 isConcurrencySafe(args) 且返回严格 true 时才把调用归入 parallel group；省略、异常、隐藏或无效定义一律 exclusive。Plan exit、三个 Goal tool 与 todo_write 都没有 opt-in，因此都是 ordering barrier。PLANSTATE-TOOL-EXCLUSIVE

所以两个连续 todo_write 在同一模型 batch 中按顺序执行，第二个稳定覆盖第一个；多个 in_progress 只表示 Agent 可能通过 subagent、后台命令或 workflow 同时推进多项工作。它不是对 Todo snapshot 的并发写许可，更不是共享 swarm task registry。PLANSTATE-TOOL-SCHEDULER

15. 事件、Surface、projection 与重放矩阵

Compaction 改写的是 model Surface，不会删除这些 log-only domain facts。于是 Plan active 与 Goal lifecycle 不依赖摘要是否记住它们；Todo projection 也可从完整日志恢复，但它的下一-Turn清空规则仍然生效。相反，goal-round prompt、tool calls 和 results 是 Surface 内容，未来可能只通过 checkpoint 向模型保留其语义。

16. 三处已确认的文档漂移

这些结论来自固定 commit 上的生产源码与测试，不是仅凭文档措辞推测。Plan 与 Todo 的核心 README 在本章核对范围内基本匹配当前控制流；Goal 的跨包演进更快，出现了明显同步滞后。PLANSTATE-DOC-GOAL-TOOLPLANSTATE-DOC-GOAL-UIPLANSTATE-DOC-GOAL-COMMAND

17. 已确认的限制、缺口与有意取舍

18. 设计评价与验证状态