收口 orchestrator remote turn binding facade

[kxn]

父 issue

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

背景

#713 的 A/B/C/D 已完成。重新评估 E（orchestrator runtime facade）后，结论是不能直接开一个大而泛的 “orchestrator runtime facade” 子单：当前 s.turns / s.progress / s.pickers / s.catalog 的直接访问仍然横跨 queue、snapshot、compact、request cleanup、picker owner-flow 等多条状态机，整包推进会导致验证面过大。

第一刀应选 remote turn binding facade，因为相关逻辑已经部分集中在 service_queue_binding.go，但仍有多个文件直接读写 s.turns.pendingRemote / s.turns.activeRemote。这类 direct map access 是 queue/dispatch ownership 的核心 SSOT 风险。

范围

本 issue 只覆盖 orchestrator 中 remote turn binding 的 pending/active map 访问收口：

• s.turns.pendingRemote
• s.turns.activeRemote
• pending/active remote turn bind/promote/clear/lookup/interrupt/surface ownership 查询

不覆盖：

• s.turns.pendingSteers
• s.turns.compactTurns
• s.progress.*
• picker/catalog runtime facade
• 跨包拆分 orchestrator

目标

把 pending/active remote turn binding 的直接 map 访问收口到 serviceTurnRuntime 或 service_queue_binding.go 的 facade 方法，降低 queue/dispatch/routing/snapshot 横向改动时漏同步或绕过清理逻辑的风险。

非目标

• 不改变 attach/use/follow/new、queue dispatch、request gate 或 compact 的用户语义。
• 不改变 remote surface state machine。
• 不移动 Service ownership 到新 package。
• 不重写 queue 或 dispatch 流程。
• 不处理 pendingSteers 与 compactTurns，它们后续应另拆。

相关文档

• docs/general/remote-surface-state-machine.md
• docs/general/issue-orchestration-workflow.md

涉及文件

重点：

• internal/core/orchestrator/service_runtime_clusters.go
• internal/core/orchestrator/service_queue_binding.go
• internal/core/orchestrator/service_dispatch_core.go
• internal/core/orchestrator/service_snapshot_query.go
• internal/core/orchestrator/service_snapshot_runtime.go
• internal/core/orchestrator/service_queue.go
• internal/core/orchestrator/service_autowhip.go
• internal/core/orchestrator/service_autocontinue.go
• internal/core/orchestrator/service_reply_auto_steer.go
• internal/core/orchestrator/*queue*test.go
• internal/core/orchestrator/*remote*test.go

建议范围

1. 先补结构测试，锁定除少数 runtime owner 文件外不应直接访问 s.turns.pendingRemote / s.turns.activeRemote。
2. 在 serviceTurnRuntime 上补 pending/active remote binding facade 方法，例如 get/set/delete/iterate 或语义化 bind/clear/lookup helpers。
3. 迁移散落在 snapshot query/runtime、queue/autowhip/autocontinue/reply-auto-steer 中的直接 pending/active map access。
4. 保留 pendingSteers / compactTurns direct access，不在本 issue 混做。
5. 跑 queue/remote/snapshot 相关测试和 remote-state-machine guardrail；若行为未变，文档无需更新，但收尾必须记录复核结论。

完成标准

• 除 owner/facade 文件外，生产代码不再直接读写 s.turns.pendingRemote / s.turns.activeRemote。
• pending/active remote binding 的 create/promote/clear/lookup/ownership 查询通过统一 facade。
• 现有 queue/dispatch/remote/snapshot 行为保持等价。
• remote-state-machine guardrail 已复核；如发现行为变化，必须同步文档或回退行为变化。
• 中型结构重构默认需要独立 verifier pass。

实现参考

可能的 owner 选择：

• serviceTurnRuntime 拥有 map 基础操作和枚举。
• Service 级语义 helper 继续留在 service_queue_binding.go，但内部通过 runtime facade，而不是直接 map access。
• service_dispatch_core.go 的 bind/clear 可作为第一批迁移重点，因为它是写入源头。

注意：不要把 compact 和 steer 混进来。compactTurns 与 pendingSteers 语义不同，后续独立拆更安全。

检查参考

目标检查：

• go test ./internal/core/orchestrator -run 'Queue|Dispatch|Remote|Snapshot|AutoContinue|AutoWhip|ReplyAutoSteer|Surface' -count=1
• go test ./internal/core/orchestrator -count=1
• go test ./...
• bash scripts/check/go-file-length.sh && git diff --check

结构检查：

• rg -n 's\.turns\.(pendingRemote|activeRemote)' internal/core/orchestrator --glob '*.go' --glob '!*_test.go'

收尾参考

• 把结果回卷到 调研核心大包与高耦合结构拆分方案 #713。
• 记录 remote-state-machine guardrail 结论。
• 独立 verifier pass 后再 close。

执行决策

• 是否拆分：不再拆。本 issue 是 调研核心大包与高耦合结构拆分方案 #713/E 的第一执行切片，只覆盖 pending/active remote binding facade。
• 当前执行单元：orchestrator remote turn binding facade。
• verifier：需要。该 issue 触及 queue/dispatch/routing remote binding 状态 owner，默认需要独立 verifier。

执行快照

• 当前阶段：plan
• 当前执行点：子 issue 已创建，等待 prepare/lint 后进入实现。
• 已完成：调研核心大包与高耦合结构拆分方案 #713 A/B/C/D 已完成；E 重新评估后决定先拆 remote turn binding facade，而不是大范围 runtime facade。
• 下一步：运行 issue workflow prepare/lint；通过后按 TDD 先补结构测试再实现。
• 当前阻塞：无产品决策阻塞。
• 最后一致状态：master 与 origin/master 同步到 bf282ad2，工作区干净。
• 未完成尾项：prepare、lint、实现、验证、remote guardrail、verifier、回卷 调研核心大包与高耦合结构拆分方案 #713、commit/push、close。
• 恢复步骤：读取本 issue 与 调研核心大包与高耦合结构拆分方案 #713；确认 s.turns.pendingRemote/activeRemote 直接访问现状；先补结构测试，再实现 facade。

[kxn]

实施进展

已完成本地实现与验证：

• 新增 serviceTurnRuntime pending/active remote binding 基础 facade：get/bind/clear/iterate。
• bindPendingRemoteTurn、bindActiveRemoteTurn、clearPendingRemoteTurn、clearActiveRemoteTurn 已改为调用 runtime facade。
• 新增 Service 级语义 helper：hasPendingRemoteTurn、bindPendingRemoteCommand、pendingRemoteBindingByCommandForInstance、activeRemoteBindingForSurface、remoteBindingSurfaceByCommand。
• 迁移 queue/autowhip/autocontinue/compact/snapshot/reply-auto-steer 中对 s.turns.pendingRemote / s.turns.activeRemote 的直接访问。
• 保留 pendingSteers / compactTurns 不动，符合本 issue 非目标。

验证证据

已通过：

• RED：go test ./internal/core/orchestrator -run TestRemoteTurnBindingMapsStayBehindFacade -count=1 在实现前失败，列出 service_autocontinue.go、service_autowhip.go、service_compact.go、service_dispatch_core.go、service_queue.go、service_reply_auto_steer.go、service_snapshot_binding.go、service_snapshot_query.go、service_snapshot_runtime.go。
• GREEN：go test ./internal/core/orchestrator -run TestRemoteTurnBindingMapsStayBehindFacade -count=1
• go test ./internal/core/orchestrator -run 'Queue|Dispatch|Remote|Snapshot|AutoContinue|AutoWhip|ReplyAutoSteer|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

Remote State Machine Guardrail 结论

• 本次改动触及 queue/dispatch remote binding owner 边界，因此已按 remote-state-machine guardrail 复核。
• 行为语义保持等价：没有改变 attach/use/follow/new、queue dispatch、request gate、compact、interrupt 或 command availability 的状态迁移。
• activeReplySteerTarget 在迁移时保持 active-only 查询，未把 pending remote turn 当成可 steer target。
• 未发现需要更新 docs/general/remote-surface-state-machine.md 的实现行为变化。

执行快照

• 当前阶段：verification
• 当前执行点：实现和本地验证已完成，等待独立 verifier pass。
• 已完成：结构测试红灯、remote binding facade 实现、目标/全量/guardrail 测试。
• 下一步：执行独立 verifier；若 pass，回卷 调研核心大包与高耦合结构拆分方案 #713，commit/push，close 收口 orchestrator remote turn binding facade #718。
• 当前阻塞：无产品决策阻塞。
• 最后一致状态：本地工作区只有 收口 orchestrator remote turn binding facade #718 预期改动；全量测试与文件长度检查通过。
• 未完成尾项：verifier、调研核心大包与高耦合结构拆分方案 #713 回卷、commit/push、close-plan、finish/close。
• 恢复步骤：读取本 issue 与 调研核心大包与高耦合结构拆分方案 #713；检查当前 diff；确认 verifier 结果；完成收尾。

[kxn]

独立 verifier 结果：pass

Findings: none.

Verifier notes:

• Goal alignment: pass. pendingRemote / activeRemote 的直接 map 访问已收口到 serviceTurnRuntime 与 service_queue_binding.go facade 层；非 owner/facade 文件由结构测试防回归。
• Non-goal discipline: pass. 未触碰 pendingSteers、compactTurns、s.progress.*、picker/catalog runtime，也未跨包拆 orchestrator。
• Acceptance coverage: pass. create/promote/clear/lookup/ownership 查询路径已通过 runtime/service facade；queue/autowhip/autocontinue/compact/snapshot/reply-auto-steer 的直接访问已迁移。
• Regression surface: pass. activeReplySteerTarget 仍只使用 active remote binding，未把 pending binding 纳入可 steer target；compact/queue busy 判断仍按是否存在 pending remote turn 判定。
• Durable knowledge sync: pass. 已按 remote-state-machine guardrail 复核，未改变 attach/use/follow/new、queue dispatch、request gate、compact、interrupt 或 command availability 语义，因此无需更新 canonical doc。

Validation evidence:

• go test ./internal/core/orchestrator -run TestRemoteTurnBindingMapsStayBehindFacade -count=1
• go test ./internal/core/orchestrator -run 'Queue|Dispatch|Remote|Snapshot|AutoContinue|AutoWhip|ReplyAutoSteer|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

Recommendation: pass. Ready for parent roll-up, commit/push, close-plan and finish.

[kxn]

收尾更新

• commit：76d8d90f (Hide remote turn binding maps behind facade)
• push：已通过 ./safe-push.sh 推送到 origin/master
• verifier：独立 verifier 结果为 pass
• close 判断：目标、非目标、验证、remote guardrail 和父 issue 回卷均已完成