feat(coordination): add reviewed whole-Goal coordination-authority promotion

[huangruiteng]

Summary

• separate the transaction-bound coordination runtime shadow from the older observation-only shadow and expose the same configuration owner through configure-goal, the shared capability catalog, Dashboard write/readback, and bilingual UI copy
• add a TypeScript-owned preview/apply operation for whole-Goal coordination-authority promotion that revalidates the exact source snapshot and shadow lineage under shared locks, requires an already-qualified hard_lease Goal, engages the durable legacy-writer fence, commits canonical authority, and performs exact receipt readback/replay
• make the durable fence-before-canonical interruption window recoverable: the same reviewed operation resumes the canonical commit, while changed operation/fence inputs remain typed conflicts
• normalize symlink and /var versus /private/var runtime-root identity across restart, preserve legacy bindings only with immutable-manifest proof, update the bilingual shared-authority RFC, and ship the rebuilt Chat bundle

This is the safe operator-path slice of #4796. It does not let delegation start/inspect, Dashboard rendering, or Lark implicitly promote authority. It moves Todo/task-lease coordination mutation authority; legacy Goal/Markdown source bytes remain preserved for audit and compatibility.

Entry points

• CLI: configure the transaction-bound shadow; preview/apply the reviewed coordination cutover only with an explicit execute flag
• Dashboard: edit the same Goal configuration owner and read the same typed transition state through the existing capability editor
• Lark: read-only projection only; no mutation grant is added
• managed workers: unchanged and fail-closed until canonical coordination authority exists

Exact-head validation

Exact head: 04e6591

• 92 focused TypeScript authority/shadow tests passed
• 35 Python coordination-shadow, Goal Channel, and delegation-preflight tests passed
• real FileAuthorityStore fault injection passed: durable fence, forced canonical commit failure, unchanged legacy bytes, changed-operation rejection, same-request recovery, exact canonical readback
• disposable migration -> restart -> Goal acceptance -> gpt-5.6-sol/xhigh managed-delegation preflight passed without worker or Turn side effects
• control-plane typecheck passed
• Dashboard delegation-preflight smoke and packaged Chat build passed
• git diff --check passed
• full 2,095-test TypeScript control-plane run: 2,076 passed, 18 skipped, one sqlite-capacity rehearsal failure reproduced unchanged at prior clean head a2e6b9f and is therefore not attributed to this patch

Safety and remaining acceptance

• preview is effect-free; execute is explicit and idempotent
• a non-hard_lease Goal returns typed not-ready without fencing writers
• provider-open failures preserve exact provider evidence and never fall back
• a matching persisted fence with no canonical head is resumable; a changed fence remains fail-closed
• no private Goal state, credentials, or local research artifacts are included
• live finance Goal promotion and manager -> Sol/xhigh acceptance remain separate post-merge/operator acceptance work

Part of #4796.

[huangruiteng]

Follow-up commit 87259cc closes the read-only transition explanation gap without widening authority: managed-delegation preflight now returns typed promotion_required/unavailable/promoted state plus the next operator action; the packaged Dashboard renders it; the Goal Channel projection used by channel/Lark consumers carries the same non-mutating boundary and explicitly disallows promotion from the surface. Only the reviewed TypeScript preview may establish promotion readiness.

Validated: control-plane typecheck; delegation TS suite (8/8); focused Python Goal Channel and unavailable-authority tests (9/9); Chat bundle build; delegation-preflight and personal-workspace contract smokes; diff check. A broader existing delegation-preflight suite still hits the branch baseline CLI-parser mismatch (turn run-once rejects --todo-id), unrelated to this projection change and not hidden as passing evidence.

[huangruiteng]

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

审阅 exact head：a2e6b9f133e240f284108e7c21e8ee2a241db15d

动机

这次改动要补齐 #4796 暴露的真实产品缺口：已有 legacy authority 的 Goal 即使配置好了 managed delegation，也会在 canonical authority 缺失处 fail closed；维护者需要一个显式、可预览、可复核、不会从 delegation / Dashboard / Lark 隐式触发的 Todo/task-lease 协调权威切换入口。

方向是对的，且当前 head 已经形成一个有价值的增量：它把 coordination-shadow promote、Goal 级 coordination_runtime_shadow 配置、TypeScript promotion owner，以及 Dashboard/Goal Channel 的只读 transition 解释串了起来。但 #4796 把 crash/replay、restart readback 和 disposable Goal 验收列为最小验收项；当前 exact head 在最关键的 fence-before-canonical 中断窗口仍会把 Goal 卡死，因此本轮不能批准。

改动思路

主链路是：legacy Todo/task-lease projection 与 source snapshot → transaction-bound shadow bootstrap/capture/qualify → 无副作用 preview → 显式 --execute → 在 maintenance/source locks 下重新验证 source → 写 durable legacy-writer fence → 把 qualified shadow head 连同 promotion receipt 提交到 canonical store → 精确 readback。

这个所有权划分总体合理：

• TypeScript 的 reviewLocalCoordinationAuthorityPromotion 保持 qualification、fence、canonical commit 和 receipt 判断的唯一语义权威；
• Python 只构造 source snapshot、桥接 effect runtime 和呈现 CLI；
• Dashboard / delegation / Goal Channel 只投影 promotion_required | unavailable | promoted 和 next action，并明确 promotion_from_surface_allowed=false；
• 默认关闭，配置可发现不等于启用，preview 不写 fence、不建 canonical head。

需要特别澄清数据边界：这个 promotion 不会删除或原地重写原始 Markdown/lease 文件；它把经过资格化的 Todo/task-lease coordination projection 写入 canonical store，并通过 fence 永久阻止 legacy coordination writer 继续写。因此正常成功时，原文件仍保留为审计/兼容材料；“切换权威”不等于“销毁原数据”。

具体改动

关键代码讲解

1. reviewLocalCoordinationAuthorityPromotion：把 source snapshot 重验、shadow qualification、hard_lease gate、preview plan、writer fence、canonical commit 与 readback 放在一个 TypeScript owner 中；happy path 和 already-promoted replay 的结构是正确的。
2. engageLegacyCoordinationWriterFenceUnderLocks：在调用方已持有 source locks 时原子写入 fence；相同 fence replay、不同 fence conflict。这个文件一旦存在，所有 legacy Todo/task-lease writer 都会 fail closed。
3. qualifyCoordinationRuntimeShadowUnderLocks：验证 state bytes、完整 lease inventory、evidence digests、outbox settled、lineage/event coverage，以及 current legacy projection 与 shadow head 的精确一致性；它避免 promotion 只看一次浅层 hash。
4. local_authority_is_promoted：Python 侧目前以 fence 路径存在作为 provider-first mode switch；这保证 cutover 后绝不回退 Markdown，但也意味着 fence-only 中间态必须有可靠恢复。
5. delegation/Goal Channel/Dashboard transition projection：补上 promotion_required / unavailable / promoted 与只读 next action，且没有给 UI/Lark 新增 mutation grant。

其余改动包括：Goal 配置目录与双语本地化、promotion-review schema/generated bindings、CLI preview/apply 渲染、双语 shared-authority RFC、相关 Python/TypeScript/UI tests，以及可重建一致的 Chat bundle。

对主干的风险

[P1] durable fence 写完、canonical head 未提交时无法续跑

我在真实 FileAuthorityStore/source snapshot/shadow/fence 路径上只注入一个故障：让 canonical commit 在 fence 已成功持久化后抛错。结果是：

1. 第一次调用返回 failed，却错误报告 legacy_writer_fenced=false；
2. 实际 fence 已存在，legacy writers 全部被阻断；
3. 同一个 operation 的第二次调用看到 canonical missing + persisted fence，直接返回 local_authority_writer_fence_without_canonical_head；
4. Python 读写路由又只看 fence 是否存在，于是会转向一个不存在的 canonical head，且不允许回退 Markdown。

所以这不会把原始字节“写坏”或删除，但会造成等价严重的可用性事故：原始数据仍在，正常产品路径却既不能继续 legacy 写，也不能从 canonical 读/写，公开的 promote 命令也不能完成恢复。RFC 写的是“等待 operator recovery”，当前 PR 没有暴露这个 recovery。

最小修复：当 persisted fence 与本轮重新推导的 Goal / operation / shadow revision / projection digest 完全一致 且 canonical head 缺失时，在现有 locks 下把它视为同一笔 in-flight promotion，继续 canonical commit 并以 exact receipt/head readback 结算；不同 fence 仍然 conflict。所有 catch/result 还必须回读或保留真实的 legacy_writer_fenced 状态。

回归测试必须故障注入在 fence readback 与 canonical commit 之间，然后用同一 reviewed request 重试并得到 applied | recovered | replayed；同时验证 changed operation/fence 仍拒绝，legacy bytes 未被改写。建议至少重跑：

node --no-warnings --experimental-sqlite --experimental-strip-types --test \
  tests/control_plane_ts/local_authority_runtime.test.ts \
  tests/control_plane_ts/local_authority_provider.test.ts
uv run --extra test python -m pytest -q \
  tests/control_plane/test_coordination_shadow_command.py \
  tests/control_plane/test_canonical_goal_channel_coordination.py \
  tests/test_delegation_preflight.py

[P2] “whole-Goal authority” 容易被理解成迁移了全部 Goal 数据

typed protocol 与 CLI namespace 实际上都准确地限定在 local coordination authority；但部分 help/UI/docstring 使用 “whole-Goal authority promotion”。本次 payload 与 fence 覆盖的是 Todo/task-lease coordination authority，并不迁移所有 Goal 材料。建议统一成 “whole-Goal coordination-authority cutover / 整 Goal 协调权威切换”，并明确 legacy Goal/Markdown 原始数据保留，移动的是 Todo/task-lease mutation authority。

语义与 CI 对齐

• #4796 明确要求 crash/replay；当前实现的 fence-only 状态没有对应的可恢复 transition，属于现有验收合同的具体违反，而不是推测性边角案例。
• 远端 CI 未按 capability policy 查询。exact head 本地验证：control-plane typecheck 通过；74 个 Node tests 通过；53 个 Python tests 通过；generated contract check、git diff --check、Chat build、delegation-preflight smoke、personal-workspace contract smoke 均通过；loopx check --scan-root . 为 0 error、2 个与本 PR 无关的既有 projection warnings。
• 这些 green checks 没覆盖上述故障窗口；现有 Python CLI test 还 mock 了 runtime，因此不能替代真实 fence/canonical crash/retry 证据。

我的整体评价

架构方向、默认关闭隔离、TypeScript authority ownership、source snapshot 重验以及只读 UI/Lark 边界都值得保留。正常成功的 promotion 不会破坏原始数据；它复制并接管 Todo/task-lease coordination authority，同时保留 legacy 文件。但 authority cutover 的安全性取决于每一个 durable 中间态都可重试。当前 head 恰好在 fence 已生效、canonical 尚未建立的窗口失去恢复能力，并且首个错误回包还误报 fence 状态。

结论：请先修复 P1 并加入真实 store fault-injection + same-command retry 证据，再在 disposable Goal 上完成 qualification → preview → execute → process restart → canonical readback → managed-worker acceptance。P2 可同一轮顺手收窄文案。

English verdict: REQUEST_CHANGES - head a2e6b9f; an interruption after the durable legacy-writer fence but before canonical commit is not resumable, strands all coordination reads/writes, and initially misreports the fence as absent. Local typecheck, 74 Node tests, 53 Python tests, contract generation, bundle build, and UI smokes passed, but the required crash/replay fault injection failed.

[huangruiteng]

Exact-head follow-up is now pushed at 04e6591.

The P1 interruption window is fixed in the reviewed TypeScript owner. After an exact durable fence is present and canonical authority is still missing, the same reviewed operation revalidates the source snapshot and qualified shadow, treats the fence as recovery evidence, and resumes the canonical commit under the existing locks. A different operation/fence remains a typed conflict. Error paths now read back the exact durable fence, so an exception after fence persistence reports legacy_writer_fenced=true rather than hiding the cutover state.

A real FileAuthorityStore fault-injection test now proves: fence persists -> canonical commit throws -> legacy bytes remain unchanged -> changed operation is rejected -> same request returns recovered -> exact canonical head is readable. I also narrowed the CLI, runtime docstrings, Dashboard copy, capability editor copy, smoke expectation, and packaged Chat bundle from whole-Goal authority to whole-Goal coordination-authority.

The preceding commit cdcd630 additionally fixes /var versus /private/var and symlink runtime-root identity across restart, preserves legacy active shadow bindings only with immutable-manifest proof, and adds the disposable migration -> restart -> Goal acceptance -> gpt-5.6-sol/xhigh managed-delegation preflight E2E without worker or Turn side effects.

Validated locally:

• 92 focused TypeScript authority/shadow tests passed
• 35 Python coordination-shadow, Goal Channel, and delegation-preflight tests passed
• disposable migration/restart/managed-worker E2E passed
• control-plane typecheck passed
• Dashboard delegation-preflight smoke and packaged Chat build passed
• git diff --check passed

The full 2,095-test control-plane run reached 2,076 pass / 18 skip with one existing sqlite-capacity rehearsal failure; the same isolated failure reproduces unchanged at prior head a2e6b9f, so it is not attributed to this patch. No self-merge; review and CI remain required.

[huangruiteng]

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

审阅 exact head：d64f8b421315b83322ef974dd7822b4d37c753c5

动机

这次改动完成 #4796 的具体产品闭环：legacy Goal 即使已经具备 managed-delegation 配置，也会因 canonical coordination authority 缺失而 fail closed；此前没有一个受评审、可预览、可恢复且不会从 delegation／Dashboard／Lark 隐式触发的 Todo/task-lease 权威切换入口。

现在的可观察结果是：维护者对一个显式启用的 hard_lease Goal 完成 transaction-bound shadow 资格化，先无副作用 preview，再显式 --execute；进程重启后从 canonical provider 读回同一 head/receipt，并获得不会启动 worker 的 managed-delegation preflight。这个结果关闭了本 PR 的目标，不把 PostgreSQL 长程资格化、自动 promotion 或非 coordination Goal 数据迁移算进本次交付。

改动思路

主链路是：registered Goal/state path 与完整 legacy Todo/lease snapshot → transaction-bound file shadow capture/qualification → TypeScript promotion owner → durable legacy-writer fence → canonical AuthorityStore head/event/receipt → exact readback → delegation/Goal Channel 只读解释。

所有权放置正确：TypeScript 继续拥有 state/effect 决策；既有 AuthorityStore、shadow qualification、maintenance/source locks 和 writer fence 被复用；Python 只负责 registry/source adapter 与 CLI 呈现；Dashboard、Chat、delegation、Goal Channel/Lark 只消费状态，不能执行 promotion。availability、配置发现和 preview 都不等于 activation，真正不可逆的切换仍要求 Goal 级 opt-in 加显式 --execute。

正向路径验证了 qualification → preview → execute → fresh-process readback → acceptance → managed preflight。负向路径直接在 fence 写入后、canonical commit 前注入中断：首轮失败如实报告 fence 已生效；不同 operation 被 conflict 拒绝；原 exact request 重试得到 recovered，legacy bytes 不变且没有 fallback。

具体改动

关键代码讲解

1. reviewLocalCoordinationAuthorityPromotion 统一拥有资格化、hard_lease gate、preview plan、fence identity、canonical commit、replay/recovery 与 receipt/head readback。它把此前 P1 所在的 fence-only durable intermediate state变成“仅 exact request 可续跑”的合法恢复态。
2. engageLegacyCoordinationWriterFenceUnderLocks 复用既有 primary-write guard 与 file mutation lock：同 fence replay、异 fence conflict，且要求注册的 source state path 精确一致。
3. review_local_coordination_authority_promotion 与 coordination-shadow promote 只桥接已注册 Goal、source snapshot 和显式 execute；disabled Goal 在进入 effect runtime 前 fail closed。
4. delegationPreflight 与 Goal Channel projection 增加 promotion_required | unavailable | promoted 解释；Dashboard/Lark 无 promotion 按钮或 mutation grant，Goal Channel 仍由 mode=read_only、projection_is_writable=false、write_authority=none 约束。
5. 配置入口覆盖 CLI、共享 catalog、Chat/Dashboard editor 和双语 copy；生成 contract 与 Chat bundle 已从当前源码重建。

本轮 future-facing pass 也做了两个有界收敛：把两类 shadow 配置的 Python summary/validation/apply 归并到同一组合 owner，避免 configure_goal.py 继续膨胀；把 status 中可由既有 observation/truth contract 推导的重复 authority 字段移到 renderer，保留三态语义并让 CLI base/head 输出预算恢复通过。

对主干的风险

最高风险仍是不可逆 authority cutover：fence 生效后不得回退 legacy writer；错误实现会让单个 Goal split-brain 或完全不可写。本 head 通过 exact revision/digest/fence/operation identity、共享 locks、provider CAS 与 receipt/head readback控制该风险，且用真实 FileAuthorityStore 只 fault-inject canonical commit，而不是 mock 最终 postcondition。

默认关闭隔离已验证：未配置时不创建 shadow/fence/canonical state；preview 不创建 authority 目录、不产生 worker context、不花 quota、不启动 Turn；UI 与 Lark 只提供解释。新增 schema/CLI 字段是 additive，原输入继续有效。公共命名始终限定在 local/coordination authority；“whole-Goal”在双语 RFC 中明确指完整 Todo/task-lease coordination boundary，不宣称迁移全部 Goal 数据或授予新的 agent lifecycle authority。

语义与 CI 对齐

• rebased exact-head 定向验证：97 个 Python tests、100 个 TypeScript tests、Dashboard/Chat build、delegation-preflight／personal-workspace smokes、typecheck 与 py_compile 全部通过。
• 前一 PR head 的完整 Stage 2C mutation run 退出 0；已输出的 source／goal／fence／receipt／cursor／management 等 mutants 均为 killed_by_assertion=true；最新 head 只额外合入 origin/main@0ef7ebd7，并已重跑上述定向验证和标准 canary。
• loopx canary premerge --from-git-diff --git-diff-base origin/main --tier standard 通过：10 项 catalog checks、8 项 risk-profile checks、public/private boundary scan、module ceiling、diff hygiene 均无失败或 manual hold。
• CLI output budget 在同一 public fixture 上做 base/head differential；最初 +322 chars 的回归没有通过抬预算处理，而是消除重复字段后按原预算通过。
• GitHub exact-head CI：推送后已触发，但按用户明确指示未等待；本评论不把它视为已通过或合并授权。

没有 blocking finding。剩余风险是这仍是较大的 control-plane/runtime 变更，且 promotion 在 fence 后刻意不可回滚；因此必须保留显式 operator intent、exact-request recovery 和独立 maintainer merge 边界。

我的整体评价

相对上一轮 REQUEST_CHANGES，原 P1 已被真实 store fault injection 复现并修复，P2 的 scope 文案也收窄为“whole-Goal coordination-authority”。当前实现没有新增第二套 authority，使用既有 typed state/store/fence vocabulary，并把新语义限制在一个完整、可验证的迁移旅程内；改动规模与 split-brain／stranding 风险相称。

结论：exact head 无阻塞代码问题，批准合入。由于这是 loopx/** 与 apps/** 的 control-plane/runtime 行为变更，仓库规则禁止作者自合并；本评论记录 author-owned exact-head approval conclusion，但实际 merge 仍须独立 maintainer 执行。

English verdict: APPROVE - head d64f8b4; the prior fence-before-canonical crash window now recovers only the exact reviewed request, changed identities still fail closed, default-off/read-only surfaces do not grant promotion authority, and exact-head local real-path validation passed with no blocking finding. Exact-head remote CI was triggered but intentionally not awaited and is not claimed green. Repository policy still requires an independent maintainer to merge this control-plane/runtime change.

[huangruiteng]

动机

这个 PR 解决的是一次不可逆 authority cutover：在 shadow 已经满足 hard-lease 协调条件后，由显式 operator 命令把 Todo / task-lease 的 mutation authority 从 legacy state 提升到 canonical authority。当前 head 也修复了上一版最危险的 crash window——durable writer fence 已写入、canonical commit 尚未完成时，重试应能恢复而不是永久卡死 Goal。

我按“原始数据不应被迁移破坏”的风险重新审了完整调用链。当前实现没有覆写或搬走原 Goal/source bytes；promotion 的写入边界集中在 writer fence、canonical authority object、event/receipt 与 lineage readback，这个方向是正确的。Dashboard、Lark、delegation 和普通 read path 也没有获得隐式 promote 权限。

改动思路

实现采用 preview/apply 两阶段，并在锁内重新读取 source snapshot 与 shadow qualification。apply 先落 durable fence，再提交 canonical authority；如果进程恰好在两者之间退出，下一次相同请求通过读取 fence 恢复。新 head 同时把 runtime-root alias / symlink 情况归一到同一 shadow lineage，并只在 immutable manifest 能证明同一真实 root 时兼容旧 lexical digest。

这个设计的关键不是“同一个 operation id 就能恢复”，而是“恢复的必须是同一份已审阅 promotion plan”。因此 durable recovery identity 必须覆盖所有会改变 qualification 结论的语义输入。

具体改动

• reviewLocalCoordinationAuthorityPromotion 解析并执行 minimum_operations 与 required_event_kinds qualification，持锁重验 shadow/source 后进入 fence → canonical commit → receipt/readback。
• legacy_writer_fence.ts 提供严格 typed schema，旧写路径在 fence 存在时 fail closed。
• shadow_management.ts 为真实 runtime root 建立稳定 digest，并用 manifest proof 限制 alias 兼容范围。
• CLI、Dashboard 与 Lark 只投影显式 operator review/result；feature 默认关闭，读取路径不触发 cutover。

关键代码讲解

当前 fence 在 local_authority_runtime.ts:202 附近只绑定 Goal、由 operation 推导的 fence id、shadow provider revision 和 projection digest；local_authority_runtime.ts:263-275 的 recovery 又只比较这些 fence bytes。与此同时，同一入口在前面单独解码了 minimum_operations 和 required_event_kinds，说明这两个字段确实属于 promotion decision，而不是展示参数。receipt / promotion identity 也没有补上这部分语义。

我用真实 FileAuthorityStore、真实 fence/source fixtures 复现了 fence 已写入但 canonical commit 抛错的中断，只注入了 commit failure。随后保持 Goal、operation 和 head 不变，把 required_event_kinds 从 ["todo_claim"] 改成 [] 重试；当前 head 返回 status="recovered" 并提交了 canonical authority。也就是说，第二次请求可以用更弱的 evidence policy 消费第一次请求创建的不可逆 fence。

对主干的风险

[P1] durable recovery identity 没有绑定完整的 qualification policy

这不是 source data corruption：原始 Goal/source bytes 仍被保留。风险是更细的 request-semantics 漂移——operator 审阅并触发的请求 A 写下 fence 后，语义不同的请求 B 可以被当成 A 的 exact retry 并完成不可逆 cutover。结果 receipt 看起来是一次正常 recovery，但它并未证明最终执行的是最初审阅的 qualification plan。

最小修复建议：对所有会影响 promotion decision 的输入构造 canonical plan digest（至少包括规范化后的 minimum_operations 和排序/去重后的 required_event_kinds，排除纯 preview/execute mode），把 digest 持久化进 fence/event/receipt，并在 recovery 时逐字节校验。回归应分别 mutation 两个 policy 字段并要求 conflict，同时证明完全相同的请求仍能 recovery。

语义与 CI 对齐

本地 exact-head 验证结果：92 个 TypeScript 测试通过；59 个 Python 测试通过；control-plane typecheck、Ruff、git diff --check 均通过。上面的 changed-policy recovery mutation 在当前 head 上按预期暴露失败，因此不能被这些绿色回归覆盖所抵消。当前远端 CI 仍有 pending 项，但这个可复现 blocker 不依赖它们转绿与否。

我的整体评价

当前 head 已经正确修复“fence 写入后崩溃会永久搁浅”的上一轮 blocker，也把 source preservation、default-off isolation、alias lineage 与 read-only projection 做得更完整。未来向的 bounded refactor 也基本放在正确 ownership：typed TypeScript runtime 持有 state-machine authority，Python 只做 adapter。不过，recovery identity 仍少了 qualification policy 这一决定性维度；在不可逆 authority cutover 上，这个缺口必须在合并前补齐。

English verdict: REQUEST_CHANGES - head d64f8b4; recovery after the durable fence accepts changed minimum/event qualification inputs because the fence and receipt do not bind the complete reviewed plan. 92 TypeScript and 59 Python tests, typecheck, Ruff, and diff check passed; the changed-policy recovery mutation failed as expected and exposes the blocker.