refactor(coordination): unify canonical handoff mode authority and recovery

[huangruiteng]

Behavior

Promoted Goals could report stale frontmatter handoff_mode, while handoff-mode set remained a fenced legacy writer. This closes that command boundary: show reads canonical mode; set checks the complete Todo/lease snapshot and commits mode plus a durable operation receipt with one provider-neutral CAS.

• Concurrent claim/lease changes invalidate the checked revision. Invalid active expiry or unknown lease schema cannot prove quiescence. Stale/missing Markdown and leftover local lease files cannot become fallback authority.
• A lost response recovers the original operation. Even an accepted no-op seals a receipt, so replay after a later switch cannot restore an old mode. --operation-id binds a canonical intent; different-mode reuse is rejected. --dry-run writes neither mode nor receipt.
• Legacy defaults, materialized-state scan scope, invalid-frontmatter repair and state/lease locks stay compatible. Both routes share the typed mode policy. The old Python transition decision is removed; legacy quiescence stops building unrelated status/resume/capability display projections.

Scope and migration economics

20 files: 614 additions / 69 deletions; product 268 / 51, durable validation 250 / 11, docs 96 / 7. Two DCO-signed commits separate runtime/tests from operator docs and bilingual RFC checkpoints.

handoff_mode_policy.ts owns the transition rule; handoff_mode_transaction.ts owns canonical quiescence, CAS and replay. Duplicate mode reads and TS mode literals are consolidated. Existing complete read-model validation, lease expiry rules, provider API and maintenance locks are reused. This adds a previously unsupported command; it is not a net-deletion claim.

Dedicated transport adds 39 Python lines and 29 TS lines, plus existing decision-result adaptation and CLI/handler wiring. Native set/recovery crosses Python→TS once; show uses the existing canonical snapshot request. Legacy frontmatter locks/writer retire after the last unpromoted caller; transport retires with a native CLI. Placement stays with the existing coordination/Todo owner and bundled File/SQLite providers; no new capability, extension, generic store, migration engine or second state machine is introduced.

UI impact: none. CLI is the affected configuration entry point; repository search found no dashboard mode editor. Preview, mutation/errors and authoritative readback are exercised, including the packaged CLI. The Todo-section renderer still excludes frontmatter: use handoff-mode show for current canonical mode. The operation guide documents recovery and changing back with a new operation ID.

Task: owner-requested TS/shared-authority migration slice; target base main. This is independent of #4299 and SQLite D2 #4224. It changes neither provider defaults nor capability grants, does not complete T1–T4/D1–D3, expose a PostgreSQL CLI selector, qualify long-duration SQLite storage, or migrate a live Goal.

Validation

• Tested revision: 8b8cb00b8a58ee38f245a1d45bbe4e422136faa3; base 8570657f1eb6ed268bd2ccbdb781b163f4716b5a.
• Run state: finished. Input classes: synthetic, public_fixture, authorized_private_read_only.

Check kind	Result	Evidence / limitation
static	passed	TS typecheck; native mypy (22 files); changed-file Ruff/compile; diff/private-boundary scan; maintainability ratchet with zero new exceptions/regressions.
unit / integration	passed	1,332 TS tests at final head, zero skips. 284 related Python tests; 158 mode/core/fence tests rerun after the bounded repair. Python runs precede rebase; touched product/test blobs are unchanged by those upstream commits.
real_backend	passed	Isolated PostgreSQL 16.15 plus real File/SQLite. Eight new mode cases × five conformance factories = 40 tests, including NoKV fake/process transports, concurrent claim/CAS conflict and lost-response recovery.
real_entrypoint	passed	Built wheel includes new TS assets; extracted-wheel File/SQLite CLI show/preview/set/replay and unchanged display all pass.
regression_parity	passed	Seven legacy CLI cases match pinned 0cbb8472f JSON, exits and exact state bytes. Canonical stale-read regression fails on that baseline and passes on candidate.
real_entrypoint / real_backend	passed	Readonly snapshot: 474 Todos / 59 retained leases. Disposable File/SQLite CLI and isolated PostgreSQL reject 71 unfinished claimed Todos. A separately labeled quiescent derivative passes transition, original-operation replay and exact record preservation. Source registry/state/snapshot remain unchanged.

Shared-authority fixture: loopx_coordination_production_scale_fixture_v0, existing 464-Todo fixture. Added semantic dimensions: full-source quiescence, expiry equality/invalidity, sealed no-op, old receipt after later mode change, stale/missing display, provider failure and concurrent ownership. Legacy/File/PostgreSQL rehearsal records intentional before/after divergence for the previously unsupported canonical command; it is not a promotion qualification.

The old engaged-fence row now expects canonical quiescence rejection, with explicit blocker/no-write assertions. Initial TS execution used system Python 3.9 and failed subprocess startup; corrected to the project Python environment and reran the full suite successfully. No required backend test was skipped.

Performance and remaining costs

Measurement	p50 / p95 (ms)	Samples
Legacy full CLI, pinned baseline	1756.85 / 2589.81	32 alternating pairs
Legacy full CLI, candidate	1885.98 / 2586.26	32 alternating pairs
Warm typed socket request	0.204 / 0.452	200
Complete Python discovery/transport adapter	6.116 / 8.270	200
Managed runtime cold start + first request	262.161 / 286.927	8
Complete durable set, 464 Todos, File	1023.550 / 1651.463	32
Complete durable set, 464 Todos, SQLite	120.511 / 128.073	32

Full-CLI p95 is effectively flat; median rises 7.35%, retained as a warning. No speedup claim. Warm socket requests meet the 2 ms internal target; the full Python adapter is reported separately. Native canonical set had no supported baseline transaction; its new durable path is not compared against a non-durable 2 ms budget. Daemon RSS across eight isolated starts: idle 103216–106720 KiB; after 200 requests 104432–107104 KiB. These bounded samples are not long-duration qualification.

An initial full-CLI sample showed a tail regression; the bounded ownership-only read simplification preceded the final paired run. No performance gate was weakened.

Exact-scope quality

Receipt cqr_031b5b2740af04f6cafe verifies valid, fingerprint 031b5b2740af04f6cafebac15a5dba36752faf9591a4fa49bb088251d435f088. Safe fix allowed/applied: one pass. Blockers 0; warnings 1 (transport/median cost); advisories 0. canary premerge --from-git-diff --goal-id … passed: 18 selected checks, 18 executed, zero failures, zero skips and no manual holds; direct diff checks and Python compile also passed. Changed surfaces: coordination policy/transactions, CLI routing/readback, durable fixture contracts and operation/RFC docs.

No private fixtures, raw logs, credentials, internal links or local machine paths are included. Further work remains on SQLite D2 elapsed-time evidence, remaining command/consumer coverage and approved whole-Goal cutover; this PR grants none of those approvals.

[huangruiteng]

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

Reviewed exact head 4304@8b8cb00b8a58ee38f245a1d45bbe4e422136faa3 against main.

动机

本 PR 希望关闭 promoted Goal 的 handoff-mode authority 缺口：show 从 canonical snapshot 读取，set 在同一 Todo/lease snapshot 上检查 quiescence，并通过 provider-neutral CAS 同时提交 mode 与 durable operation receipt，从而支持 lost-response recovery、idempotent replay 和 sealed no-op。

改动思路

架构方向是合理的：handoff_mode_policy.ts 负责 typed transition rule，handoff_mode_transaction.ts 负责 canonical quiescence、CAS 和 receipt replay，Python provider_handoff_mode.py 只做 promoted/unpromoted routing 与结果适配。完整 canonical Todo/lease read model、lease expiry、authority store 和 effect runtime 都沿用现有 owner；没有新增 capability、provider、通用 store 或第二套状态机。

具体改动

• 新增 TypeScript mode policy/runtime/transaction：拒绝 active claimed Todo、time-active lease、invalid expiry/schema；dry-run 不写入；相同 operation ID 绑定 canonical intent，different-mode reuse 被拒绝；accepted no-op 也写 receipt。
• handoff_mode.py 与 CLI 接入 canonical show/set，legacy frontmatter writer 保留给未 promoted Goal，--operation-id 仅允许 canonical path；effect runtime handler 和 conformance factories 同步扩展。
• Python/TypeScript 测试覆盖 File、SQLite、PostgreSQL、NoKV fake/process transport、CAS conflict、lost-response recovery、stale/missing display 与 sealed no-op；operator guide 和双语 RFC 说明切换与恢复边界。
• UI 无需 companion change：仓库没有 dashboard mode editor，当前受影响入口是 CLI，Todo section renderer 也不声称展示 canonical frontmatter mode。

对主干的风险

存在一个确定的 P1 blocker：set_canonical_handoff_mode() 在 local_authority_is_promoted() 看到 fence 文件后立即转入 canonical effect runtime。对于现有“legacy writer fence 已存在但 canonical provider 结果不可用”的 handoff caller，它在 provider_handoff_mode.py:22-37 抛出 LocalCoordinationAuthorityUnavailable("canonical mode unavailable")，而不是 legacy_todo_write_transaction 既有的 LegacyCoordinationWriterFenced pre-primary-write contract。set_goal_handoff_mode() 位于 handoff_mode.py:451-454 的提前 dispatch 使 legacy fence guard 不再接管该路径。

这个问题已在 exact head 本地稳定复现：

pytest -q tests/control_plane/test_shadow_writer_boundaries.py::test_omitted_writers_refuse_a_fence_before_primary

结果为 handoff 参数失败、followups 参数通过；GitHub stage2c (e2e 2) 是同一失败（1 failed, 110 passed），并连带使 stage2c-correctness-e2e 与 merge-gate 失败。当前远端状态为 21 success、3 failure、0 pending。

最小修复是：在 canonical dispatch 前或其中保留 canonical legacy-write check 的 typed fence 结果，确保这一输入继续抛 LegacyCoordinationWriterFenced 且不触及 primary record；保留现有 [handoff] regression，并补一个 present-fence/canonical-unavailable 的 adapter case。修复后必须重跑 Stage 2C e2e 2、correctness aggregation 和 merge-gate。

我的整体评价

canonical quiescence/CAS/receipt 的产品边界和代码放置总体正确，现有 conformance 与 real-backend 证据也有价值；但 PR 明确承诺 legacy fence compatibility，而 exact head 破坏了该 typed error/dispatch contract，并且 required merge gate 当前为红。因此不能批准本 head。结论：REQUEST_CHANGES。

English verdict: REQUEST_CHANGES — exact head 8b8cb00b8a58ee38f245a1d45bbe4e422136faa3 routes a present legacy fence to LocalCoordinationAuthorityUnavailable instead of LegacyCoordinationWriterFenced; the regression is reproduced locally and fails Stage 2C plus the merge gate.

[huangruiteng]

结论：REQUEST_CHANGES。审阅 exact head 8b8cb00b8a58ee38f245a1d45bbe4e422136faa3。发现 1 个 P1 blocking finding；GitHub 对 PR 作者不允许正式 self-review，因此本条以 comment 形式发布。

动机

PR 要把 per-Goal handoff mode 的 canonical authority、CAS/replay 和 recovery 收口到 TypeScript transaction，并在真正 promotion 后停止把 stale/missing Markdown 当作权威。这是合理且有价值的控制面边界，但现有 legacy writer-fence 仍是 promotion 前的安全契约，不能被一个不充分的 promotion 判定绕过。

改动思路

入口由 handoff_mode.py 通过 provider_handoff_mode.py 路由；canonical 路径调用 handoff_mode_transaction.ts，校验模式、quiescence、CAS/replay 和 provider receipt；legacy 路径继续由 legacy_writer_fence.py 与 frontmatter 负责。正向 canonical conformance 与 targeted tests 都通过。

问题在切换边界：local_authority_is_promoted() 目前只要 legacy_coordination_writer_fence_path 存在就返回 True。因此 legacy-only 的 fence 文件被当成 canonical promotion，set_canonical_handoff_mode() 随即把 provider unavailable 映射成另一类 authority error，绕过了原有 writer-fence rejection。

具体改动

• 新增 typed HandoffMode policy/runtime/transaction，统一 canonical set、CAS、replay、dry-run 与 receipt。
• Python provider bridge 校验 status、source_authority、decision_read_from_provider 和 legacy_fallback_used，canonical read 不再回退到 Markdown。
• claim/show/set caller 改为共享 canonical provider；RFC、reference doc、conformance 和 legacy parity fixture 同步更新。

关键代码讲解

loopx/control_plane/coordination/local_authority.py:68 的 local_authority_is_promoted 只做 fence 路径 stat()，没有读取或验证 canonical selector/provider binding。loopx/control_plane/todos/provider_handoff_mode.py:22 随后将所有这类状态送入 effect_runtime_result("coordination.local_authority.handoff_mode_set", ...)；provider 不可用时在第 36 行抛出 LocalCoordinationAuthorityUnavailable。但已有 legacy_writer_fence.require_legacy_coordination_write_allowed 契约要求同一 legacy-only 状态抛出 LegacyCoordinationWriterFenced、保留 reason code legacy_coordination_writer_fenced，并在写入前终止。

对主干的风险

我在 exact head 重跑了现有 public regression：

uv run --with pytest pytest -q 'tests/control_plane/test_shadow_writer_boundaries.py::test_omitted_writers_refuse_a_fence_before_primary[handoff]'

结果为失败：期望 LegacyCoordinationWriterFenced，实际是 LocalCoordinationAuthorityUnavailable（canonical mode unavailable）。GitHub 上 stage2c (e2e 2)、stage2c-correctness-e2e 和 merge-gate 也因此失败；canonical targeted Python 80 tests 与 TypeScript authority-store 52 tests 通过，说明缺口正好位于 pre-promotion legacy boundary，而非 transaction happy path。

请让 promotion 仅在 validated canonical selector/provider binding 存在时成立，或在 legacy-only 状态先执行 writer-fence guard，再进入 canonical provider。补充/保留该回归，断言异常类型、reason code 和 no-write/no-receipt effects，然后重跑 stage2c 与 merge-gate。

我的整体评价

TypeScript ownership migration 的方向、事务边界和 typed receipt 设计是正确的，新增代码也有真实 caller 和 conformance coverage。但当前 promotion 判定把一个 legacy safety marker 当成 authority proof，改变了既有拒绝类型并使 required e2e/merge gate 变红。在修复这个 P1 前，我不能批准该 exact head。

English verdict: REQUEST_CHANGES on exact head 8b8cb00b8a58ee38f245a1d45bbe4e422136faa3. P1: local_authority_is_promoted() treats mere legacy writer-fence file existence as canonical promotion, so a legacy-only fenced handoff now raises LocalCoordinationAuthorityUnavailable instead of the established LegacyCoordinationWriterFenced and bypasses the no-write fence contract. I reproduced the failure locally; hosted stage2c (e2e 2), stage2c-correctness-e2e, and merge-gate are red. Require validated promotion metadata or legacy-fence-first routing, add the regression assertion, and rerun the required gates.

[huangruiteng]

Self-repair / refine follow-up

根因：legacy writer fence 文件存在时，handoff-mode set 会进入 canonical dispatch；canonical provider 不可用时，旧流程继续尝试 legacy 路径，丢失既有 LegacyCoordinationWriterFenced 类型化保护。

修复：

• canonical 不可用时重新执行 legacy fence admission check；存在 fence 时原样返回 legacy_coordination_writer_fenced，不写 Markdown、不生成 shadow/receipt。
• canonical 语义拒绝新增 typed failure_kind=decision_rejection，不会被误判为 provider outage 或 fallback。
• 增加 present-fence + canonical-unavailable 回归，并保留 file/NoKV/SQLite conformance。

验证（head cfc93acc72b3e5359ac9c724d424de5f0f818b4c, base 34710d17addbbdfd56e6ea1f03ec73519a4aa7fd）：

• focused pytest: 43 passed；authority TypeScript conformance: 179 passed；targeted ruff/typecheck passed。
• loopx canary premerge --from-git-diff: 17/18 checks passed；唯一失败为本机 quota-plan-smoke.py 的现有 effect-runtime handler 环境故障（独立手动复现，未触及本改动路径），其余 risk-profile/public-boundary 全部通过。
• required GitHub checks 已重新触发，当前等待远端完成；无人工 hold。

覆盖足够：本修复只改变 canonical outage 到 legacy fence 的 fail-closed 分支，并用异常类型/reason、无写入、无 receipt 的负向回归锁定边界；canonical 语义拒绝及三种 authority provider 的原有 conformance 仍通过。

[huangruiteng]

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

PR #4304 — refactor(coordination): unify canonical handoff mode authority and recovery
Reviewed exact head: cfc93acc72b3e5359ac9c724d424de5f0f818b4c

动机

PR 的目标是把 promoted Goal 的 handoff_mode 从可能陈旧的 Markdown frontmatter 迁移到既有 canonical AuthorityStore，并让 mode change 的完整 Todo/lease quiescence、CAS 和 operation-id replay 由一个 typed transaction 负责。旧 Python _decide_handoff_transition 与 legacy writer 不能原子地绑定 provider revision 和 durable receipt；stale/missing Markdown 也不应继续成为 promoted Goal 的 authority。该目标与现有 coordination owner 相符，PR 没有新增 provider、capability 或 whole-Goal promotion。对 unpromoted Goal，前后 CLI show/set 仍保持 frontmatter 兼容行为；对 promoted Goal，exact head 的 canonical show、dry-run、replay、provider failure 和 full-projection rejection 均有覆盖。

改动思路

新增 handoff_mode_policy.ts 作为纯 typed decision owner，handoff_mode_transaction.ts 在同一 provider snapshot 上读取 canonical projection，检查完整 claim/lease，计算 mode decision，使用 provider revision CAS 写入 mode 与 receipt，再以相同 operation id 做 readback/replay。handoff_mode_runtime.ts 和 provider_handoff_mode.py 只负责 effect transport、promotion fence 和 fail-closed 适配；handoff_mode.py 保留未晋升路径的 frontmatter/lease compatibility writer。authority_core.py 不再保留平行的 Python mode rule，而是调用同一 TS policy。这样 canonical mode 是 provider authoritative fact，receipt/provider revision 是历史事实，show payload 和旧 frontmatter 只是 projection/compatibility state。

具体改动

关键代码讲解

• loopx/control_plane/coordination/handoff_mode_policy.ts:7 的 planHandoffMode 对 legacy|soft_claim|hard_lease 以及 no_change|rejected|apply 做 exact typed validation；只有 mode 改变且无 active claimed Todo、无 time-active lease 才允许 apply。
• loopx/control_plane/coordination/handoff_mode_transaction.ts:43 的 executeHandoffModeSet 负责 request validation、receipt identity/hash、完整 projection/lease 扫描、dry-run、CAS commit、sealed no-op 和 lost-response replay。拒绝或 conflict 不写 mode/receipt。
• loopx/control_plane/todos/handoff_mode.py:249 的 show_goal_handoff_mode 以 durable writer fence 判断 promotion；promoted 读取 canonical provider，即使 Markdown stale/missing 也不 fallback，未晋升仍走旧 frontmatter。
• loopx/control_plane/todos/provider_handoff_mode.py:23 的 set_canonical_handoff_mode 将 CLI 请求交给 TS effect，并要求 result 明确来自 file_v0|sqlite_v0、decision_read_from_provider=true、legacy_fallback_used=false；provider 不可用时向 CLI 暴露 typed failure。
• tests/control_plane_ts/handoff_mode_conformance.ts:35 为 File、SQLite、NoKV transport 注册同一组大 projection、invalid lease/schema、并发 claim/CAS、lost response、no-op/replay 用例，验证三个 provider 的语义一致性。

整体 diff 为 21 files, +683/-70：生产 coordination/CLI 适配、6 个 RFC/reference 文档、Python/TS conformance tests 和 parity fixture。没有私有日志、凭证或本机路径。

对主干的风险

exact head 的行为验证很充分：相关 Python tests 69 passed，File/SQLite/NoKV authority/conformance TypeScript tests 233 passed，Python compileall 通过；hosted exact-head checks 24 个非 skipped 全部成功。正向路径证明 promoted show 忽略 stale/missing display、canonical set 保留 464-Todo projection、dry-run 不写入、no-op 封存 receipt、后续 mode 切换不改变旧 operation replay；负向路径覆盖 active claim、active/invalid lease、unknown schema、provider failure、CAS race 和 lost response。基线与 exact head 的 unpromoted CLI show/set 输出及 state bytes保持兼容。

P1 blocking finding — 当前主干无法合并。 PR base 是 34710d17addbbdfd56e6ea1f03ec73519a4aa7fd，而当前 origin/main 是 ddf6efa894d5ebcd60f822265eb4651d27416fd0。GitHub 对 exact head 报告 mergeable=CONFLICTING、mergeStateStatus=DIRTY；git merge-tree --write-tree origin/main HEAD 以冲突退出，唯一冲突文件是 tests/control_plane_ts/authority_store_conformance.ts。PR 新增的 registerHandoffModeConformance 与当前主干新增的 receipt conformance registration 必须同时保留；若只保留一方，provider conformance coverage 会被静默删除。最小修复是 rebase 到当前 main，手工合并该 import/registration，再以新 exact head 重跑完整 Python/TS suites 并重新 review。

除此之外没有已复现的运行时 blocking defect。仓库本地没有 tsc/ruff binary，因此本地 typecheck/ruff 未执行；hosted build、kernel-static-checks、pytest、四个 test shards、stage2c、merge-gate 等均成功。这个环境差异不能替代 rebase/冲突修复。

我的整体评价

架构方向是正确且范围合适的：它复用了现有 AuthorityStore/fence/lock，删除了 Python 平行 decision owner，用 typed policy/transaction 统一 canonical authority，同时保留 unpromoted compatibility。authority semantics、typed state、domain neutrality、behavior-change disclosure、guidance-vs-obligation 和 feature-off/default-off 隔离均有证据支持；没有发现第二个 state machine 或不必要 capability。可是当前 exact head 的 DIRTY merge state 是发布阻塞，且共享 conformance registration 正是这次迁移的验证边界。请先解决冲突并生成新 head；新 head 需要重新进行 exact-head freshness 检查和本 review contract 的完整验证后再审。

English verdict: REQUEST_CHANGES — exact head cfc93acc72b3e5359ac9c724d424de5f0f818b4c has 24 successful hosted checks and strong canonical-mode coverage, but GitHub reports CONFLICTING/DIRTY and git merge-tree finds a conflict in tests/control_plane_ts/authority_store_conformance.ts. Rebase onto current main, preserve both conformance registrations, rerun the suites, and request a fresh review.

[huangruiteng]

RFC #4330/#4344 scope clarification / 范围澄清：this PR remains a separate coordination-authority transaction. Its Goal/Todo handoff_mode is not the M2 collaboration WorkRequest admission policy, does not require same-Goal/unclaimed-Todo as a universal request gate, and does not implement request/context/assessment/result or return delivery. Keep its canonical mode CAS/recovery semantics, but do not count it as M2/M3 completion or make it a provider/deployment prerequisite.

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Reviewed the complete rebased diff at exact head 4304@50f1d723e9e41eb53b5da57aa72fcad30cd9ee44 against main at ba6ba1b6e3a2788d188f36e012eb795e2616800e. The previous P1 and the base-branch conformance conflict are resolved. No blocking finding remains.

动机

本 PR 解决 promoted Goal 的 handoff_mode 权威性缺口。旧路径可能继续把陈旧的 Markdown frontmatter 当成模式来源；同时，在 legacy writer fence 已存在而 canonical provider 不可用时，handoff caller 可能先得到 provider unavailable，绕过既有 LegacyCoordinationWriterFenced 的“写入前拒绝”契约。这样会让模式显示、Todo/lease quiescence、并发更新和失败恢复出现两套语义。

现在 promoted Goal 的 show/set 使用 canonical AuthorityStore；unpromoted Goal 保留 frontmatter 兼容路径。canonical provider 故障时，适配层重新执行 legacy fence admission check，确保旧安全边界不被 outage 改写。

改动思路

入口仍是 handoff-mode show/set CLI。handoff_mode_policy.ts 是纯 typed mode/quiescence decision owner；handoff_mode_transaction.ts 在同一个完整 Todo/lease snapshot 上校验 schema、active claim、time-active lease、operation identity 和 request hash，然后执行 dry-run、provider-revision CAS、durable receipt、sealed no-op、lost-response replay 与 readback。handoff_mode_runtime.ts 只负责 effect-runtime transport。

Python provider_handoff_mode.py 负责 provider payload/readback 适配，不复制 canonical decision rule。handoff_mode.py 在 promoted path 调 canonical provider，在 unpromoted path 继续使用 legacy_todo_write_transaction；canonical unavailable 时先调用 require_legacy_coordination_write_allowed，所以 present fence 仍返回 LegacyCoordinationWriterFenced，不会写 Markdown、shadow 或 receipt。这个拆分复用了现有 AuthorityStore、lease validator、effect-runtime registry 和 legacy fence owner，没有新增 capability、provider 或第二套状态机。

具体改动

• 新增 typed HandoffMode policy、canonical transaction、runtime handler 和 receipt/event schemas；相同 mode 形成可重放 sealed no-op，mode 变化必须满足完整 projection quiescence。
• promoted show 以 provider projection 为 authority，即使 Markdown stale/missing 也不回退；promoted set 通过单次 CAS 同时提交 mode、event 和 operation receipt。
• Python/CLI 保留 unpromoted frontmatter compatibility，并将 decision_rejection、provider outage、operation-id misuse 和 legacy fence 拆成可观察的 typed 错误。
• conformance 扩展到 File、SQLite、NoKV 及 disposable PostgreSQL；测试覆盖 active claim/lease、invalid schema/expiry、CAS race、lost response、replay、sealed no-op、provider failure 和 legacy fence parity。
• RFC/reference 文档说明 promotion、quiescence、recovery、operation-id 与 legacy boundary；本次重基保留了主干已有 authority conformance registration。

关键代码讲解

• loopx/control_plane/coordination/handoff_mode_policy.ts:9 的 planHandoffMode 对 mode literal 和 active claim/lease 列表执行单一、无副作用的 apply/no_change/rejected 判定。
• loopx/control_plane/coordination/handoff_mode_transaction.ts:43 的 executeHandoffModeSet 负责 replay/hash、完整 projection 扫描、dry-run、CAS、receipt sealing 和 readback；拒绝路径在 commit 前结束。
• loopx/control_plane/todos/handoff_mode.py:402 的 set_goal_handoff_mode 只做 promoted/legacy 路由；第 469-480 行的 outage recheck 保留 present-fence 的原始 typed rejection。

对主干的风险

我以 exact head 重跑了完整验证：

• npm run typecheck:control-plane 通过。
• npm run test:control-plane：1494 个测试，1493 通过、0 失败、1 个既有 intentional placeholder skip。
• npm run test:postgresql-authority-store：在 disposable isolated PostgreSQL 实例上 98/98 通过，0 失败/跳过。
• focused Python：test_canonical_handoff_mode.py、test_shadow_writer_boundaries.py、test_shadow_fence_caller_parity_e2e.py 共 69 通过；ruff、py_compile、git diff --check 通过。
• targeted handoff boundary canary：Todo contract、read-model boundary、structured active-state 三项 3/3 通过；public/private boundary scan 通过。

标准 loopx canary premerge --from-git-diff 另外暴露了两个与本 diff 无关的主干基线故障：bounded-context-namespace-smoke.py 对既有 loopx.capabilities.cross_runtime shim 的断言，以及 quota-plan-smoke.py 的既有 effect-runtime handler 环境故障；它们在主工作树同样稳定复现，且错误不触及本 PR 的 handoff symbols。它们已在本评论中明确记录，不被静默当成绿色；与本 PR 直接相关的 targeted canary、public boundary、所有 exact-head 本地测试和远端 CI 均通过。无人工 hold，无 tracked side effect。

我的整体评价

本 PR 的范围与问题匹配：canonical mode、quiescence、CAS/receipt/replay 和 legacy fence 都放在各自既有 owner，Python 只是适配层；协议名称也没有扩展为更宽的 actor 或 multi-agent authority。之前的 P1（provider outage 绕过 legacy fence）已由最小 recheck 修复，并由负向回归锁定异常类型、reason code 和 no-write/no-receipt 语义。重基后的 exact head 与 main 无冲突，质量收据 cqr_0bd7ecf561a7c6386e53 对应当前 21 文件 fingerprint 且验证有效。结论：批准自合并。

English verdict: APPROVE — exact head 4304@50f1d723e9e41eb53b5da57aa72fcad30cd9ee44 is rebased onto ba6ba1b6e3a2788d188f36e012eb795e2616800e; canonical handoff mode now has typed quiescence/CAS/receipt/replay semantics, and canonical-provider outage preserves the legacy writer-fence rejection. The prior P1 and conformance conflict are fixed. All exact-head tests, isolated PostgreSQL, targeted canary/boundary checks, and hosted checks pass; two standard-canary failures are independently reproduced baseline faults and do not mention changed handoff paths.

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Reviewed the complete rebased diff at exact head 4304@9567086ebbf446c2429a729e4e6d53b4160146c1 against main at b0f7aa0d12eab1947808d5af3f46ac51d37ec794. The previous P1 and the base-branch conformance conflict are resolved. No blocking finding remains.

动机

本 PR 解决 promoted Goal 的 handoff_mode 权威性缺口。旧路径可能继续把陈旧的 Markdown frontmatter 当成模式来源；同时，在 legacy writer fence 已存在而 canonical provider 不可用时，handoff caller 可能先得到 provider unavailable，绕过既有 LegacyCoordinationWriterFenced 的“写入前拒绝”契约。这样会让模式显示、Todo/lease quiescence、并发更新和失败恢复出现两套语义。

现在 promoted Goal 的 show/set 使用 canonical AuthorityStore；unpromoted Goal 保留 frontmatter 兼容路径。canonical provider 故障时，适配层重新执行 legacy fence admission check，确保旧安全边界不被 outage 改写。

改动思路

入口仍是 handoff-mode show/set CLI。handoff_mode_policy.ts 是纯 typed mode/quiescence decision owner；handoff_mode_transaction.ts 在同一个完整 Todo/lease snapshot 上校验 schema、active claim、time-active lease、operation identity 和 request hash，然后执行 dry-run、provider-revision CAS、durable receipt、sealed no-op、lost-response replay 与 readback。handoff_mode_runtime.ts 只负责 effect-runtime transport。

Python provider_handoff_mode.py 负责 provider payload/readback 适配，不复制 canonical decision rule。handoff_mode.py 在 promoted path 调 canonical provider，在 unpromoted path 继续使用 legacy_todo_write_transaction；canonical unavailable 时先调用 require_legacy_coordination_write_allowed，所以 present fence 仍返回 LegacyCoordinationWriterFenced，不会写 Markdown、shadow 或 receipt。这个拆分复用了现有 AuthorityStore、lease validator、effect-runtime registry 和 legacy fence owner，没有新增 capability、provider 或第二套状态机。

具体改动

• 新增 typed HandoffMode policy、canonical transaction、runtime handler 和 receipt/event schemas；相同 mode 形成可重放 sealed no-op，mode 变化必须满足完整 projection quiescence。
• promoted show 以 provider projection 为 authority，即使 Markdown stale/missing 也不回退；promoted set 通过单次 CAS 同时提交 mode、event 和 operation receipt。
• Python/CLI 保留 unpromoted frontmatter compatibility，并将 decision_rejection、provider outage、operation-id misuse 和 legacy fence 拆成可观察的 typed 错误。
• conformance 扩展到 File、SQLite、NoKV 及 disposable PostgreSQL；测试覆盖 active claim/lease、invalid schema/expiry、CAS race、lost response、replay、sealed no-op、provider failure 和 legacy fence parity。
• RFC/reference 文档说明 promotion、quiescence、recovery、operation-id 与 legacy boundary；本次重基保留了主干已有 authority conformance registration。

关键代码讲解

• loopx/control_plane/coordination/handoff_mode_policy.ts:9 的 planHandoffMode 对 mode literal 和 active claim/lease 列表执行单一、无副作用的 apply/no_change/rejected 判定。
• loopx/control_plane/coordination/handoff_mode_transaction.ts:43 的 executeHandoffModeSet 负责 replay/hash、完整 projection 扫描、dry-run、CAS、receipt sealing 和 readback；拒绝路径在 commit 前结束。
• loopx/control_plane/todos/handoff_mode.py:402 的 set_goal_handoff_mode 只做 promoted/legacy 路由；第 469-480 行的 outage recheck 保留 present-fence 的原始 typed rejection。

对主干的风险

我以 exact head 重跑了完整验证：

• npm run typecheck:control-plane 通过。
• npm run test:control-plane：1495 个测试，1494 通过、0 失败、1 个既有 intentional placeholder skip。
• npm run test:postgresql-authority-store：在 disposable isolated PostgreSQL 实例上 98/98 通过，0 失败/跳过。
• focused Python：test_canonical_handoff_mode.py、test_shadow_writer_boundaries.py、test_shadow_fence_caller_parity_e2e.py 共 69 通过；ruff、py_compile、git diff --check 通过。
• targeted handoff boundary canary：Todo contract、read-model boundary、structured active-state 三项 3/3 通过；public/private boundary scan 通过。

标准 loopx canary premerge --from-git-diff 另外暴露了两个与本 diff 无关的主干基线故障：bounded-context-namespace-smoke.py 对既有 loopx.capabilities.cross_runtime shim 的断言，以及 quota-plan-smoke.py 的既有 effect-runtime handler 环境故障；它们在主工作树同样稳定复现，且错误不触及本 PR 的 handoff symbols。它们已在本评论中明确记录，不被静默当成绿色；与本 PR 直接相关的 targeted canary、public boundary、所有 exact-head 本地测试和远端 CI 均通过。无人工 hold，无 tracked side effect。

我的整体评价

本 PR 的范围与问题匹配：canonical mode、quiescence、CAS/receipt/replay 和 legacy fence 都放在各自既有 owner，Python 只是适配层；协议名称也没有扩展为更宽的 actor 或 multi-agent authority。之前的 P1（provider outage 绕过 legacy fence）已由最小 recheck 修复，并由负向回归锁定异常类型、reason code 和 no-write/no-receipt 语义。重基后的 exact head 与 main 无冲突，质量收据 cqr_942cadf52e392ac353ea 对应当前 21 文件 fingerprint 且验证有效。结论：批准自合并。

English verdict: APPROVE — exact head 4304@9567086ebbf446c2429a729e4e6d53b4160146c1 is rebased onto b0f7aa0d12eab1947808d5af3f46ac51d37ec794; canonical handoff mode now has typed quiescence/CAS/receipt/replay semantics, and canonical-provider outage preserves the legacy writer-fence rejection. The prior P1 and conformance conflict are fixed. All exact-head tests, isolated PostgreSQL, targeted canary/boundary checks, and hosted checks pass; two standard-canary failures are independently reproduced baseline faults and do not mention changed handoff paths.