feat(coordination): preserve claims during authority promotion

[huangruiteng]

Summary

• add an explicit TypeScript-owned handoff-mode migration plan to reviewed whole-Goal coordination-authority promotion;
• support preserve for storage-only cutover and hard_lease for the single claim-preserving policy upgrade;
• preserve Todo, claim, lease, receipt, validation, and evidence fields without synthesizing execution leases;
• bind migration intent, registered-agent facts, and the target projection digest into the durable fence/receipt identity;
• keep the existing omitted-option behavior and v0 plan digest unchanged;
• document the CLI, managed-Turn, Dashboard, and Lark/Chat product boundary in English and Chinese.

Motivation

An active Goal may already contain many claimed Todos. Requiring operators to clear those claims before moving storage authority loses assignment truth and does not prove that older Turns are gone. This change lets the reviewed promotion transaction preserve assignments, validate any active lease that is retained, and rely on the existing durable legacy-writer fence for late writers.

After a direct legacy/soft_claim to hard_lease migration, the original claim owner still has no execution authority until it acquires a lease through the ordinary atomic claim-and-lease path. A foreign owner remains rejected.

Product surfaces

• CLI / managed Turn: coordination-shadow promote is the sole mutation contract and accepts --handoff-mode-migration preserve|hard_lease.
• Dashboard / Lark / Chat: no new mutable control or source of truth. Existing delegation preflight and Goal-channel projections remain read-only and continue to expose promotion_required or the promoted canonical authority.
• Configuration: the migration is one reviewed operation intent, not persistent Goal configuration, so it is intentionally not added to the capability editor.

No live Goal was promoted while developing or validating this PR.

Validation

• node --no-warnings --experimental-sqlite --experimental-strip-types --test tests/control_plane_ts/promotion_handoff_migration.test.ts tests/control_plane_ts/local_authority_runtime.test.ts — 42 passed
• uv run --extra test python -m pytest -q tests/control_plane/test_coordination_shadow_command.py tests/control_plane/test_coordination_runtime_shadow_adapter.py — 23 passed
• npm run typecheck:control-plane — passed
• PATH="$PWD/.venv/bin:$PATH" npm run test:control-plane — 2290 passed, 0 failed, 20 repository-declared skips
• uv run python -m py_compile loopx/cli_commands/coordination_shadow.py loopx/control_plane/coordination/runtime_shadow.py — passed
• git diff --check origin/main...HEAD — passed

Review and rollout

This changes control-plane authority and persisted receipt semantics. It is intentionally left for maintainer review on the exact head and must not be self-merged. After merge, a real Goal should use preview first, review the source revision/digest, target digest, preserved claims, lease dispositions, and conflicts, then apply the exact same plan during a bounded maintenance window.

[huangruiteng]

Exact-head CI triage for 175f1f70a571c808ea1276cc0d9d4c04f2b47ba3:

• node-minimum-compatibility failed only in the two SQLite variants of task_lease_inspection.test.ts. Node 22.18.0 embeds SQLite 3.50.2, which the existing authority admission correctly rejects. This branch does not change that test or the SQLite runtime boundary; #4857 contains the isolated runtime-qualified skip and its public-minimum lane passes.
• test-shard (2) also reproduced the existing settlement fixture gap handled by #4859, plus a stale machine-credential test oracle that expected the SDK override map to contain only the API key even though main intentionally injects verified LOOPX_TURN_* identity. The latter now has an isolated test-only repair in #4872.
• The failure is therefore a current-main CI baseline dependency, not a claim-migration regression. I am not copying that unrelated test repair into this authority PR.
• Local exact-head evidence remains green: 42 targeted TS tests, 23 Python CLI/adapter tests, typecheck:control-plane, 2,290/0/20-skip full control-plane tests, and the real PostgreSQL authority CI lane.

Final approval remains held until repository CI is green. After #4857, #4859, the adjacent mutation-oracle repair #4863, and #4872 land, this branch will be rebased and the exact-head review rerun. No live Goal promotion has been executed.

[huangruiteng]

Rebased the authority-promotion slice onto current main after #4872 merged. New exact head: c395ac77f1eb060335345736580a8641e1f413dd.

Fresh exact-head validation completed:

• focused TypeScript promotion/runtime suites: 42 passed;
• Python coordination-shadow command suite: 8 passed;
• npm run typecheck:control-plane: passed;
• the branch is mergeable and the real PostgreSQL authority lane is green.

The full repository CI rerun is still in progress. #4857, #4859, and #4863 remain the isolated baseline repairs for failures previously reproduced on main; this control-plane PR remains held for an independent maintainer review and merge after the exact-head CI settles. No live Goal promotion has been executed.

[huangruiteng]

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

评审对象：c395ac77f1eb060335345736580a8641e1f413dd

动机

这个 PR 解决的是现有 Goal 从 legacy coordination writer 切换到 canonical authority 时，已有 Todo claim 不能安全保留的问题。旧路径要么要求源状态已经是 hard_lease，要么让操作方在事务之外先清空 claim；后者会丢失任务归属，也无法证明旧 Turn 已经退出。

本 PR 是一个合理、可独立评审的增量：在既有 whole-Goal promotion 事务里加入显式的 preserve / hard_lease handoff migration，保留 claim、lease、receipt、validation 和 evidence，同时明确不凭空生成执行 lease。它不执行任何真实 Goal promotion，也不启动 managed worker；合入后的安装、preview/apply/readback 仍是后续验收。

改动思路

设计上复用了现有 owner，而没有增加第二套队列、存储或 writer：

1. coordination-shadow promote 是唯一 mutation entry point；Python 只负责把 registry agent facts 和一次性 migration intent 传入 TypeScript。
2. planPromotionHandoffMigration 作为纯函数，从完整 shadow projection 派生目标 projection，逐条验证 claim 和 active lease。
3. review 阶段把 source revision/digest、strategy、registered-agent set 和 target projection digest 绑定进 promotion plan/fence identity。
4. execute 阶段在 source/canonical writer lock 内重新计算并核对同一 plan，然后复用现有 authority-store CAS、event、receipt 与 readback。
5. hard_lease migration 只改变 handoff mode；原 claim owner 之后仍必须通过既有 atomic claim-and-lease 路径取得执行 lease，foreign owner 继续被拒绝。

这比“直接改一个 handoff_mode 字段”更重，但额外机制正好覆盖 active-lease 资格、并发漂移和 ambiguous commit recovery，属于该 authority boundary 所需的最小安全闭环。

具体改动

关键代码讲解

• planPromotionHandoffMigration：规范化 source projection，验证 registered owner、required write scopes、lease activity/version/epoch，并返回 typed conflicts、target projection 和 digest。它不会写存储，也不会制造 lease。
• reviewLocalCoordinationAuthorityPromotion：保持 omitted-option 的 v0 digest/旧拒绝行为；只有显式 migration 才进入 v1 reviewed plan，并在 preview 时保持零副作用。
• localCoordinationPromotionPlanSha256：把 migration strategy、agent set 和 target digest 纳入 durable identity，避免不同策略或不同 agent facts 复用旧 fence。
• promoteLocalCoordinationAuthority：在 effect 前和 writer lock 内再次核对 source/target；发生 lost response 时只允许 exact receipt/lineage recovery。
• coordinationTodoWriteScopes：抽出 claim 与 migration 共用的 Todo scope owner，避免两条路径各自维护授权规则。

产品入口边界也交代清楚：CLI/managed Turn 复用同一个 promote contract；Dashboard、Lark 与 Chat 继续只读 canonical projection，不增加第二个可写配置源；migration 是一次性 reviewed operation intent，不进入 capability editor。英文、中文 RFC 与 handoff-mode reference 同步更新。

对主干的风险

最大的风险不是字段转换本身，而是 whole-Goal authority cutover：丢失合法 claim、保留不安全 active lease，或用不同 strategy/agent set 恢复旧 fence，都会影响同一 Goal 的所有 agent。

当前实现对这些路径采取 fail-closed：unsafe owner/scope/mode/fencing counter 在 preview 前返回 typed conflict；source 或 target 漂移会在 execute/recovery 被 digest 拦住；50-claim 用例证明 claim 全部保留且不会生成 lease；原 owner/foreign owner 用例证明 migration 没有扩大执行权限。default-off 也保持隔离：省略新 flag 时仍使用原 v0 digest、原 hard-lease source 要求和无 fence 的拒绝语义。

本次 rebase 后的 exact-head 本地证据为：42 个定向 TypeScript 测试通过，23 个 Python CLI/adapter 测试通过，control-plane typecheck 与 Python compile/diff check 通过，完整 control-plane suite 为 2,290 pass / 0 fail / 20 repository-declared skips；真实 PostgreSQL authority lane 也为 green。

阻塞项来自仓库 required CI：node-minimum-compatibility 仍在 unchanged SQLite runtime qualification case 上失败，对应隔离修复 #4857；#4859/#4863 仍承接相邻 baseline failures，当前 exact-head 还有部分 jobs 未完成。因此不能把本地绿灯或 admin bypass 当成 merge-ready 证据。最小修复是先让这些 baseline PR 收敛，再在不变 head 上重跑 required CI 与 exact-head review。

语义与 CI 对齐

本 PR 复用已有 legacy / soft_claim / hard_lease vocabulary，只为一次性 promotion plan 扩展 preserve / hard_lease migration strategy；没有新建持久的 handoff 语义源。当前语义实现与 RFC/CLI 文档对齐，但 required CI 尚未满足，所以结论必须保持阻塞。

我的整体评价

从架构和实现看，我没有发现新的 code-level blocker：authority owner、effect owner、retry owner 与 readback 都在原有 cutover transaction 内，改动规模与 claim-loss/lease-escalation 风险相称，默认路径和权限边界有明确反事实验证。

但这是 control-plane authority 变更，且 exact-head required CI 尚未 green；因此当前结论是 REQUEST_CHANGES。待 #4857/#4859/#4863 收敛、该 head 的 required checks 全部完成后，需要重新执行 exact-head review，由独立 maintainer 决定合并；合并后才能安装并对真实 Goal 做 preview → reviewed apply → canonical readback，再进入 managed-worker acceptance。

English verdict: REQUEST_CHANGES - head c395ac77f1eb060335345736580a8641e1f413dd; the claim-preserving promotion design and exact-head local validation are sound, but required CI is not green and independent maintainer review remains mandatory.