收口 orchestrator pending steer binding facade

[kxn]

父 issue

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

背景

#713 的 E 阶段目标是逐步收口 orchestrator runtime facade，降低 Service 内部 runtime map 被多处直接读写导致的 SSOT 漂移风险。

#718 已收口 pendingRemote / activeRemote，#719 已收口 compactTurns。重新评估后，下一片应选择 pendingSteers，而不是 progress：

• pendingSteers 范围比 progress 小，集中在 reply auto-steer、snapshot runtime、surface pending check 与 queue binding。
• progress 横跨 final text、plan snapshot、MCP progress、request cleanup、queue，验证面更大，暂不混入本单。
• pendingSteers 直接关系用户补充输入/steer 恢复语义，适合先通过 facade 固化 owner 边界。

当前生产代码中 s.turns.pendingSteers 直接访问点集中在：

• internal/core/orchestrator/service_reply_auto_steer.go
• internal/core/orchestrator/service_surface_actions.go
• internal/core/orchestrator/service_snapshot_query.go
• internal/core/orchestrator/service_snapshot_runtime.go
• internal/core/orchestrator/service_queue_binding.go
• internal/core/orchestrator/service_runtime_clusters.go

目标

把 pendingSteers 的创建、查询、删除、恢复、迭代和 surface/instance pending 判断收口到 serviceTurnRuntime / Service facade，避免业务路径继续直接读写 s.turns.pendingSteers map。

非目标

• 不改变用户补充输入、reply auto-steer、command ack/reject、surface pending check、snapshot restore 的产品语义。
• 不混入 progress、pendingRemote / activeRemote、compactTurns、picker/catalog runtime。
• 不做 orchestrator 跨包拆分。
• 不改 Feishu 卡片视觉、文案或交互行为。

完成标准

• 生产代码中除 runtime owner/facade 文件外，不再直接访问 s.turns.pendingSteers。
• 新增结构测试防止 pendingSteers direct map access 回归。
• 现有 steer / queue / dispatch / remote / snapshot / reply auto-steer 语义测试通过。
• 若触及 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。
• 不依赖 progress facade。

信息索引

相关文件：

• internal/core/orchestrator/service_runtime_clusters.go
• internal/core/orchestrator/service_reply_auto_steer.go
• internal/core/orchestrator/service_surface_actions.go
• internal/core/orchestrator/service_snapshot_query.go
• internal/core/orchestrator/service_snapshot_runtime.go
• internal/core/orchestrator/service_queue_binding.go
• internal/core/orchestrator/service_timeline_text.go
• internal/core/orchestrator/service_steer_all_test.go
• internal/core/orchestrator/service_config_prompt_test.go
• docs/general/remote-surface-state-machine.md

当前直接访问扫描命令：

rg -n "pendingSteers|pendingSteer" internal/core/orchestrator --glob '*.go'

建议范围

1. 先加结构测试，允许 owner/facade 文件访问 pendingSteers，预期红灯列出当前 offenders。
2. 在 serviceTurnRuntime 增加 pending steer 基础方法：bind/get/delete/iterate/keys 或按语义封装所需能力。
3. 在 Service 层增加语义 helper，覆盖：
   • reply auto-steer bind。
   • /steer all 或 surface action bind。
   • command ack/reject 查找与删除。
   • snapshot restore 删除/恢复。
   • surface/instance 是否存在 pending steer。
   • queue item 关联 pending steer 迭代。
4. 更新生产调用点改走 facade。
5. 更新测试断言，优先通过 helper 观察语义，只有 owner/facade 结构测试允许检查底层 map。
6. 跑目标测试和全量测试，完成 guardrail/issue close-out。

执行决策

• 是否拆分：不再拆。本 issue 是 调研核心大包与高耦合结构拆分方案 #713/E 的一个窄切片，当前 worker 边界只覆盖 pendingSteers facade。
• 当前执行单元：收口 orchestrator pending steer binding facade #720 自身作为单 worker 执行单元。
• verifier：需要。该单属于内部结构治理但触及 remote/steer/snapshot 状态机路径，完成后默认做独立 verifier pass。

实现参考

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

• service_runtime_clusters.go 保持 runtime map owner。
• 选择一个小的 facade/owner 文件承载 Service 语义 helper；如果复用 service_snapshot_runtime.go 会让 owner 语义偏窄，优先考虑新增 service_pending_steer_binding.go 或类似文件。
• 结构测试应禁止非 owner/facade 文件直接出现 .turns.pendingSteers 或 s.turns.pendingSteers。
• 不要通过兼容 fallback 保留旧 direct map 访问。

需要保持的关键行为：

• reply auto-steer 创建 binding 时保留 ThreadID/TurnID/InstanceID/CommandID/OwnerCardMessageID/QueueItems。
• command ack 成功和 rejection 对 pending steer 的删除/恢复顺序不变。
• snapshot restore 时对不存在 surface/instance 的 pending steer 清理语义不变。
• pending steer summary 中 queue item 顺序不变。
• surface disconnect / instance removal / transport degraded 的清理效果不变。

检查参考

建议验证命令：

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

验证记录

• RED：go test ./internal/core/orchestrator -run TestPendingSteerBindingMapStaysBehindFacade -count=1 失败，offenders 为 service_queue_binding.go、service_reply_auto_steer.go、service_snapshot_query.go、service_snapshot_runtime.go、service_surface_actions.go。
• GREEN：go test ./internal/core/orchestrator -run 'PendingSteer|Steer|Queue|Dispatch|Remote|Snapshot|ReplyAutoSteer|Routing|Surface' -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 中 steering overlay、turn.steer ack/restore、disconnect restore、command matrix 等条目；本次只收口 owner/facade，未改变状态迁移或用户可见语义，不需要更新 canonical doc。

[kxn]

独立 verifier 结果：pass

Findings：无阻塞发现。

核对结果：

• 目标对齐：pendingSteers 的创建、查询、删除、恢复、迭代和 surface/instance pending 判断已收口到 serviceTurnRuntime / Service facade。
• 非目标约束：未混入 progress、remote binding、compact、picker/catalog，也未改 Feishu 卡片视觉或用户语义。
• 验收覆盖：结构测试已证明生产 direct map access 不会回归；steer/queue/dispatch/remote/snapshot/reply auto-steer 目标测试、orchestrator 包、相关包、全量测试、文件长度和 diff check 均通过。
• durable knowledge：remote-state-machine canonical doc 已覆盖 steering overlay 与 ack/restore/disconnect restore 语义；本次只是 owner/facade 收口，不需要更新文档。
• close-out：还需回卷 调研核心大包与高耦合结构拆分方案 #713、commit/push、close-plan、finish --close。

Verifier 中发现的低价值测试-only helper 已在 close-out 前删除，测试改用已有按 instance 查询 helper。

[kxn]

#720 已完成并关闭。

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