收口 orchestrator pending completed text/proposal facade

[kxn]

父 issue

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

背景

#713 的 E 阶段已经完成三个 turn runtime facade 切片：

• 收口 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。

重新评估 progress 后，不适合创建一个“大 progress facade”一次性处理。当前 serviceProgressRuntime 同时承载：

• completed agent text 的 pending final render buffer：pendingTurnText。
• completed plan item 的 pending plan proposal buffer：pendingPlanProposal。
• turnPlanSnapshots。
• mcpToolCallProgress。
• turnFileChanges。
• turnDiffSnapshots。

这些状态的生命周期和验证面不同。下一片应先切 pendingTurnText / pendingPlanProposal，因为二者同属 completed text item 暂存，范围比 MCP progress 或 plan snapshot 更小，且当前 direct map access 已分散在 queue completion、turn completed、turn artifact cleanup、instance removal 和 plan proposal presentation 中。

当前相关 direct access：

• internal/core/orchestrator/service_queue.go：store/flush pending completed agent text。
• internal/core/orchestrator/service_plan_proposal.go：store/take pending completed plan proposal。
• internal/core/orchestrator/service.go：turn completed 时读取 final text、flush final text。
• internal/core/orchestrator/service_snapshot_runtime.go：instance removal cleanup。
• internal/core/orchestrator/service_routing_request_state.go：turn artifact cleanup。
• internal/core/orchestrator/service_autowhip.go：pendingTurnTextValue helper 仍接收底层 map。
• internal/core/orchestrator/service_plan_proposal_test.go：测试直接读取 svc.progress.pendingPlanProposal。

目标

把 progress.pendingTurnText 和 progress.pendingPlanProposal 的 store/get/take/delete/cleanup 收口到 serviceProgressRuntime / Service facade，避免业务路径继续直接读写这两个 map。

非目标

• 不改变 completed agent text、final turn output、file summary 拼接、plan proposal handoff 的用户语义。
• 不混入 turnPlanSnapshots、mcpToolCallProgress、turnFileChanges、turnDiffSnapshots。
• 不改 exec progress card、MCP progress、reasoning progress 或 compact gating。
• 不做 orchestrator 跨包拆分。

完成标准

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

依赖

• 已完成：收口 orchestrator remote turn binding facade #718 remote turn binding facade。
• 已完成：收口 orchestrator compact turn binding facade #719 compact turn binding facade。
• 已完成：收口 orchestrator pending steer binding facade #720 pending steer binding facade。
• 不依赖 MCP progress / plan snapshot facade。

信息索引

相关文件：

• internal/core/orchestrator/service_runtime_clusters.go
• internal/core/orchestrator/service_queue.go
• internal/core/orchestrator/service_plan_proposal.go
• internal/core/orchestrator/service.go
• internal/core/orchestrator/service_snapshot_runtime.go
• internal/core/orchestrator/service_routing_request_state.go
• internal/core/orchestrator/service_autowhip.go
• internal/core/orchestrator/service_plan_proposal_test.go
• docs/general/remote-surface-state-machine.md

扫描命令：

rg -n "pendingTurnText|pendingPlanProposal" internal/core/orchestrator --glob '*.go'

建议范围

1. 先加结构测试，允许 owner/facade 文件访问 pendingTurnText / pendingPlanProposal，预期红灯列出当前 offenders。
2. 在 serviceProgressRuntime 增加 pending completed text/proposal 基础方法：store/get/take/deleteMatchingInstance/deleteForTurn。
3. 在 Service 层保留业务语义 helper：storePendingTurnText、flushPendingTurnText...、storePendingPlanProposal、takePendingPlanProposal 等，但内部不再直接访问 map。
4. 迁移 turn completed final text 读取、turn artifact cleanup、instance removal cleanup。
5. 更新测试断言，改走 facade/helper 观察状态。
6. 跑目标测试和全量测试，完成 guardrail/issue close-out。

执行决策

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

实现参考

优先沿用 #718/#719/#720 的模式：

• service_runtime_clusters.go 保持 runtime map owner。
• 可新增 service_progress_pending_text.go 或类似文件承载 Service 语义 facade，避免把 owner 语义散回 service_queue.go / service_plan_proposal.go。
• 结构测试应禁止非 owner/facade 文件直接出现 .progress.pendingTurnText / .progress.pendingPlanProposal。
• 不要保留旧 helper 接收底层 map 的旁路，例如 pendingTurnTextValue(map, ...) 这种形态应改成 runtime/facade 方法。

需要保持的关键行为：

• 第二个 agent_message completed 到来时，前一个 pending text 仍会先被 render，新的 text 作为 pending 保存。
• turn completed 时，final text 判断仍使用 pending agent text；成功 turn 即使 final text 为空也保持原有 final output 物化规则。
• flush pending turn text 时仍可附带 file summary、turn diff、final summary。
• plan proposal 只在 completed plan item text 存在时进入 pending proposal，take 后删除。
• clear turn artifacts / remove instance 继续清理对应 pending text/proposal。

检查参考

建议验证命令：

go test ./internal/core/orchestrator -run 'PendingTurnText|PlanProposal|TurnCompleted|FileChange|Snapshot|Routing|Queue|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_pending_text.go facade；生产 direct access 已迁移；测试 direct map 断言已迁移到 facade helper；remote-state-machine guardrail 已复核。
• 下一步：提交并通过 safe-push 推送，然后运行 close-plan / finish --close。
• 当前阻塞：无。
• 最近改变的假设：无；MCP progress、plan snapshot、file change/diff 仍不混入本切片。
• 最后一致状态：rg -n "\.progress\.pendingTurnText|\.progress\.pendingPlanProposal" internal/core/orchestrator --glob '*.go' 只剩 facade/结构测试；全量测试、文件长度与 diff check 均通过；remote-state-machine canonical doc 已覆盖 completed plan item / final output 语义，行为未变不需更新。
• 未完成尾项：commit、safe-push、close-plan、finish --close。
• 恢复步骤：读取本 issue与当前 diff；确认 调研核心大包与高耦合结构拆分方案 #713 已回卷后提交推送并关闭 收口 orchestrator pending completed text/proposal facade #721。

验证记录

• RED：go test ./internal/core/orchestrator -run TestProgressPendingTextMapsStayBehindFacade -count=1 失败，offenders 为 service.go、service_plan_proposal.go、service_queue.go、service_routing_request_state.go、service_snapshot_runtime.go。
• GREEN：go test ./internal/core/orchestrator -run 'PendingTurnText|PlanProposal|TurnCompleted|FileChange|Snapshot|Routing|Queue|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 中 completed plan item / 提案计划、turn completed final output 与 command matrix 相关条目；本次只收口 owner/facade，未改变状态迁移或用户可见语义，不需要更新 canonical doc。

[kxn]

独立 verifier 结果：pass

Findings：无阻塞发现。

核对结果：

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

[kxn]

#721 已完成并关闭。

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