收口 orchestrator turn plan snapshot facade

[kxn]

父 issue

• 调研核心大包与高耦合结构拆分方案 #713

背景

#713 的 E 阶段已经完成：

• 收口 orchestrator remote turn binding facade #718：pending/active remote turn binding facade。
• 收口 orchestrator compact turn binding facade #719：compact turn binding facade。
• 收口 orchestrator pending steer binding facade #720：pending steer binding facade。
• 收口 orchestrator pending completed text/proposal facade #721：pending completed text/proposal facade。

progress 剩余 direct map access 主要集中在：

• turnPlanSnapshots
• mcpToolCallProgress
• turnFileChanges
• turnDiffSnapshots

下一片选择 turnPlanSnapshots，而不是 MCP tool progress：

• turnPlanSnapshots direct access 更少，集中在 plan update upsert/dedup 和 turn cleanup。
• MCP tool progress 还牵涉 exec progress entry 生成、final/non-final item progress、transport 节流与 tool status，验证面更大。
• turnFileChanges / turnDiffSnapshots 当前已有较多 runtime method，后续可另行评估是否需要结构测试收口。

目标

把 progress.turnPlanSnapshots 的 upsert/dedup 和 cleanup 收口到 serviceProgressRuntime / Service facade，避免业务路径继续直接读写该 map。

非目标

• 不改变 plan update 投影、reply lane、temporary session label、exec progress boundary 或用户可见 plan 行为。
• 不混入 mcpToolCallProgress、turnFileChanges、turnDiffSnapshots。
• 不改 completed plan proposal handoff；该部分已由 收口 orchestrator pending completed text/proposal facade #721 覆盖。
• 不做 orchestrator 跨包拆分。

完成标准

• 生产代码中除 runtime owner/facade 文件外，不再直接访问 s.progress.turnPlanSnapshots。
• 新增结构测试防止该 map direct access 回归。
• plan update dedup、turn completed cleanup、turn artifact cleanup 相关测试通过。
• 若触及 remote surface 状态机逻辑 carrier，完成 remote-state-machine guardrail 复核，并记录是否需要更新 canonical doc。
• 子 issue 结果回卷到 调研核心大包与高耦合结构拆分方案 #713 后再关闭。

依赖

• 已完成：收口 orchestrator pending completed text/proposal facade #721 pending completed text/proposal facade。
• 不依赖 MCP progress facade。

信息索引

相关文件：

• internal/core/orchestrator/service_runtime_clusters.go
• internal/core/orchestrator/service_plan_update.go
• internal/core/orchestrator/service.go
• internal/core/orchestrator/service_routing_request_state.go
• docs/general/remote-surface-state-machine.md

扫描命令：

rg -n "turnPlanSnapshots|deleteMatchingTurnPlanSnapshots" internal/core/orchestrator --glob '*.go'

建议范围

1. 先加结构测试，允许 owner/facade 文件访问 turnPlanSnapshots，预期红灯列出当前 offenders。
2. 在 serviceProgressRuntime 增加 plan snapshot upsert/dedup 和 delete matching 方法。
3. 迁移 applyTurnPlanUpdate、turn completed cleanup、clear turn artifacts。
4. 跑目标测试和全量测试，完成 guardrail/issue close-out。

执行决策

• 是否拆分：不再拆。本 issue 是 调研核心大包与高耦合结构拆分方案 #713/E 的一个窄切片，只覆盖 turnPlanSnapshots facade。
• 当前执行单元：收口 orchestrator turn plan snapshot facade #722 自身作为单 worker 执行单元。
• verifier：需要。该单属于内部结构治理但触及 plan update / cleanup 生命周期，完成后默认做独立 verifier pass。

实现参考

• service_runtime_clusters.go 保持 runtime map owner。
• 可新增 service_progress_plan_snapshot.go 或类似文件承载 Service 语义 facade。
• 结构测试应禁止非 owner/facade 文件直接出现 .progress.turnPlanSnapshots。
• 现有 deleteMatchingTurnPlanSnapshots(records, ...) 接收底层 map，应收口为 runtime/facade 方法，避免继续泄露存储。

需要保持的关键行为：

• 相同 TurnPlanSnapshot 重复事件仍不投影新 event。
• 新 plan snapshot 仍按 surface/instance/thread/turn 维度缓存。
• turn completed 和 clear turn artifacts 仍清理对应 snapshot。

检查参考

建议验证命令：

go test ./internal/core/orchestrator -run 'PlanUpdate|TurnCompleted|Routing|Snapshot|Progress' -count=1
go test ./internal/core/orchestrator -count=1
go test ./internal/core/orchestrator ./internal/core/control ./internal/app/daemon -count=1
go test ./...
bash scripts/check/go-file-length.sh && git diff --check

Guardrail：

• 触及 remote-surface state-machine logic carrier 时，运行 remote-state-machine guardrail。
• 若确认只是 facade 化且行为不变，记录 canonical doc 无需更新的理由。

收尾参考

• 把完成结果、验证结果、verifier 结果和 commit 写回 调研核心大包与高耦合结构拆分方案 #713 总调度表/子 issue 回卷。
• 关闭本 issue 前运行 issuectl close-plan。
• 使用 issuectl finish --close 关闭。
• 提交并通过 ./safe-push.sh 推送。

执行快照

• 当前阶段：close-out
• 当前执行点：close-out tail；verifier 已完成，下一步确认 调研核心大包与高耦合结构拆分方案 #713 回卷后 commit/push/close。
• 已完成：TDD 结构测试红灯确认 offenders；新增 service_progress_plan_snapshot.go facade；生产 direct access 已迁移；remote-state-machine guardrail 已复核。
• 下一步：提交并通过 safe-push 推送，然后运行 close-plan / finish --close。
• 当前阻塞：无。
• 最近改变的假设：无；MCP progress、file change/diff 仍不混入本切片。
• 最后一致状态：rg -n "\.progress\.turnPlanSnapshots|deleteMatchingTurnPlanSnapshots" internal/core/orchestrator --glob '*.go' 只剩结构测试自身；全量测试、文件长度与 diff check 均通过；remote-state-machine canonical doc 已覆盖 plan update / plan proposal 语义，行为未变不需更新。
• 未完成尾项：commit、safe-push、close-plan、finish --close。
• 恢复步骤：读取本 issue与当前 diff；确认 调研核心大包与高耦合结构拆分方案 #713 已回卷后提交推送并关闭 收口 orchestrator turn plan snapshot facade #722。

验证记录

• RED：go test ./internal/core/orchestrator -run TestProgressPlanSnapshotMapStaysBehindFacade -count=1 失败，offenders 为 service.go、service_plan_update.go、service_routing_request_state.go。
• GREEN：go test ./internal/core/orchestrator -run 'PlanUpdate|TurnCompleted|Routing|Snapshot|Progress' -count=1 通过。
• 包级：go test ./internal/core/orchestrator -count=1 通过。
• 相关包：go test ./internal/core/orchestrator ./internal/core/control ./internal/app/daemon -count=1 通过。
• 全量：go test ./... 通过。
• 收尾检查：bash scripts/check/go-file-length.sh、git diff --check 通过。
• Guardrail：已复核 docs/general/remote-surface-state-machine.md 中 plan update / completed plan item / 提案计划相关条目；本次只收口 owner/facade，未改变状态迁移或用户可见语义，不需要更新 canonical doc。

[kxn]

独立 verifier 结果：pass

Findings：无阻塞发现。

核对结果：

• 目标对齐：turnPlanSnapshots 的 upsert/dedup 与 cleanup 已收口到 serviceProgressRuntime / Service facade。
• 非目标约束：未混入 mcpToolCallProgress、turnFileChanges、turnDiffSnapshots，也未改变 completed plan proposal handoff。
• 验收覆盖：结构测试已证明生产 direct map access 不会回归；plan update / turn completed / routing cleanup 目标测试、orchestrator 包、相关包、全量测试、文件长度和 diff check 均通过。
• durable knowledge：remote-state-machine canonical doc 已覆盖 plan update / plan proposal 语义；本次只是 owner/facade 收口，不需要更新文档。
• close-out：还需回卷 调研核心大包与高耦合结构拆分方案 #713、commit/push、close-plan、finish --close。

[kxn]

#722 已完成并关闭。

• commit：e25a9d80 已推送到 origin/master。
• 结果：turnPlanSnapshots direct map access 已收口到 runtime/service facade。
• 验证：结构测试红绿灯、plan update / turn completed / routing cleanup 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• 母单：结果已回卷到 调研核心大包与高耦合结构拆分方案 #713。