fix(coordination): converge terminal validation and reviewed recovery

[huangruiteng]

Agent completion and Monitor stop could report verified success after canonical commit even when display delivery failed. Their retry path also lacked the receipt-first recovery used by reviewed edits. Separately, ordinary completion could accept validation after the provider head changed during execution.

This closes that terminal caller family across the TS transaction, Python facade, Chat, and packaged frontend. It advances the L2/L5 work under #4574, #3225 and #3245; it does not change provider defaults or settle whole-Goal migration.

Behavior and ownership

• Terminal request v2 binds reviewed intent to provider revision/registry witness and binds validation continuation to its issued source revision. TS rechecks source and lease time before completion; v0/v1 reject the new fields instead of silently ignoring obligations.
• Historical business receipts recover before current-source checks or private argv resolution. Fresh work still requires the matching declaration and existing authorization. Reviewed identity also binds note/evidence/reason; legacy fingerprints remain compatible.
• Agent completion and Monitor stop reuse canonical Chat recovery and current-display acknowledgement. The frontend decoder, shared action plan, bilingual feedback and shipped bundle preserve the original proposal on retry and report pending display separately from verified completion.
• Extend the shared mixed native/imported fixture and existing browser scenario. No new provider, writer, capability, RPC method or settings surface. Python retains private effect execution, projection IO and unretired legacy writers.

Validation and cost

• Integrated on f19ecaa1d (including validator-revision PR feat: revise open Todo completion validators #4833): full TS suite 2,514 passed, zero failures/skips, with real PostgreSQL store and service on separate disposable databases.
• Python terminal/User completion/authority/edit coverage: 99 passed initially; the sole failure was the old two-request cost assertion. The same successor/archive case passes on immutable base and final head after explicitly asserting the new phases. New terminal/packaged HTTP coverage includes File and SQLite, response loss, display failure, stale validation and unavailable private declarations.
• Packaged typed-actions browser scenario passes for edits, User completion, Agent completion and Monitor stop; original identity and verified readback are checked. Direct browser interaction with the real SQLite-backed action endpoint also recovers both terminal operations.
• Read-only local-source rehearsal: 1,012 Todos and 10 leases, isolated synthetic overlays. The immutable latest-main baseline reproduces stale validation acceptance; File/SQLite/real PostgreSQL reject it and agree on fresh completion/replay. Non-target records and original source remain unchanged.
• Control-plane/dashboard typechecks, Ruff, configured mypy, packaged build and maintainability ratchet pass. Public-boundary scan is clean. The existing bundle-size warning remains.

A validated fresh completion now uses three terminal requests instead of two: admit/recover and resolve the private declaration, plan validation, commit. The extra crossing makes historical recovery independent of private argv; unvalidated completion/replay retains one request. This cost is documented and checked with the same base/head workload rather than hidden by a relaxed ceiling. The bounded refactor reuses the existing recovery/source owners; no larger framework was needed.

The dual-language RFC checkpoints retain the conditional 5–8 further delivery packages for remaining callers/executor fencing, D1 consumers, contributor-owned SQLite D2, capture/whole-Goal qualification, and default onboarding/retirement. PostgreSQL deployment/authenticated transport, capacity/soak and provider promotion remain separate. A missing original private declaration can still block lossless display recovery. Maintainer merge is required for this control-plane change.

Exact-scope quality receipt: cqr_24957dfff2c958225bcd, status valid, fingerprint 24957dfff2c958225bcd0b64f40e1a83a26f6dfb98022cc5a640fe861e336b0c; one bounded safe-fix pass, zero unresolved blockers/warnings/advisories. Risk-based canary premerge --from-git-diff --goal-id ... passed: 19 selected/executed checks, zero failures; exact-scope receipt valid. Coverage includes module/risk/maintenance contracts, CLI output budgets, Todo lifecycle, canary infrastructure and public boundary. No local validation holds; maintainer review/merge and remote CI remain separate.

[Job28703]

Independent review of exact head db51008b26c172e308d037e4358953aca53aaf0f (adversarial review chain, reviewer PASS):

Verdict: APPROVE.

Strong convergence slice. The three defects (false verified-success after display failure, missing receipt-first retry, stale validation acceptance) are fixed by one shared skeleton rather than three patches. Verified directly in the head source: receipt recovery now precedes freshness checks and private-argv resolution (todo_terminal_lifecycle.ts:791); the v0/v1 fail-closed rejection of new fields (local_authority_runtime.ts:1188); the witness closure re-hashing the registry file across awaits (authority_source.ts:31-40); Python's reviewed-completion fallback to legacy authority converted from silent to raise (provider_terminal_lifecycle.py:180). The 2×2×2 test matrix (provider × operation × failure boundary) plus the race/stale/HTTP-packaged scenarios pin each boundary claim in the new reference doc.

CI at this head: test-shard (2)'s single failure is the inherited refresh_state fixture regression (present on current main shard 3, fixed per #4859); node-min's two sqlite cases are the runtime-qualification gate addressed by #4857; shards 1/3/4, kernel-static-checks, real PostgreSQL, and all stage2c lanes pass at this head.

The 3-request cost for validated fresh completion is documented and measured rather than hidden — good practice.

[huangruiteng]

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

Exact head reviewed: db51008b26c172e308d037e4358953aca53aaf0f

动机

这次修复针对的是一个真实且高风险的终态语义缺口：Chat/Personal Workspace 中的终态操作已经经过人工 review，并不等于后续校验、执行和投影一定仍然基于同一份 canonical source。旧路径在 source revision 变化、provider 暂时不可用或 canonical commit 后投影失败时，可能出现“review 的是 A、执行的是 B”、canonical 失败后落到 legacy authority，或者操作已经提交但界面仍报失败且重试可能重复执行的问题。

这个问题不适合只修 UI 文案，也不适合只在 Python 层补一个异常分支；真正要守住的是从 review proposal 到 TypeScript 决策、provider effect、receipt replay、projection settlement 的一条完整因果链。

改动思路

本 PR 复用了现有的 authority 分层，而没有新增第二套决策源：

• Chat proposal 携带 versioned loopx_chat_canonical_terminal_basis_v0，把 provider revision 与 registry SHA 固定为被 review 的事实；
• Python ChatTodoActionMixin 只把这个 basis 适配到既有 terminal API，不重新判断终态资格；
• TypeScript todo_terminal_lifecycle.ts 继续拥有 request identity、source freshness、validation 与 terminal transition 的决定权；
• provider adapter 负责真实 effect 与 projection settlement，并明确禁止 reviewed canonical action 静默回退到 legacy authority；
• 重试优先读取 immutable historical receipt，再检查当前 source eligibility，因此“提交成功但投影/响应丢失”可以恢复，而不会因为 source 已前进就重复执行或错误拒绝历史结果。

我专门按最强反例检查了：source 在 review 后变化、provider 在执行时不可用、旧 v0/v1 payload 混入 source-bound 字段、commit 后 projection delivery 失败、同一 operation 重放。实现与测试都把这些路径落在同一个 TypeScript authority owner 上。

具体改动

1. loopx/chat_todo_actions.py

   • _reviewed_terminal_options 验证并传递 exact reviewed basis；
   • completion/reject 路径共享稳定 operation identity；
   • canonical reviewed terminal action 不再通过 Python 重建决策。

2. loopx/control_plane/coordination/todo_terminal_lifecycle.ts

   • terminalRequestSha 纳入 review/validation source binding；
   • historical receipt replay 位于当前资格判断之前；
   • stale source、非法旧协议字段和 source revision 不一致均明确拒绝；
   • terminal effect、receipt 与 source witness 保持单一事务语义。

3. loopx/control_plane/todos/provider_terminal_lifecycle.py

   • provider-first 终态执行携带 review/validation 绑定；
   • canonical provider 不可用时 fail closed；
   • canonical commit 与 projection delivery 分离结算，允许安全恢复。

4. Dashboard、示例与双语文档

   • schema/copy 与新 basis 对齐；
   • canonical terminal review 文档明确了 source binding、failure、replay 和 projection 行为；
   • 打包 web asset 与源代码一致。

5. 回归覆盖

   • 新增 reviewed terminal action、terminal source conformance、旧协议拒绝、lost response、projection recovery 与 production-scale authority 场景。

对主干的风险

主要风险在跨层协议兼容和不同 authority backend 的重放一致性。为此我在 exact head 上实际运行了：

• focused Python suite：58 passed（96.61s）；
• source-checkout TypeScript/authority suite：412 passed（187.35s），覆盖 file 与 SQLite 真实 authority 路径；
• ruff check：通过；
• git diff --check：通过；
• 对当前 origin/main 的 git merge-tree --write-tree：无冲突。

第一次直接调用 system node 时，子进程误用了系统 Python，触发 dataclass(slots=...) 环境错误；这不是 PR 失败。我随后按仓库要求用 uv run --extra test node ... 绑定 checkout interpreter，完整套件全绿。未在本地重跑 PostgreSQL integration，因此它仍是剩余的 backend-specific 风险；但 file/SQLite 真实后端、完整 source/replay negative cases 与 current-main merge tree 已覆盖本次核心语义。

代码量为 30 files、+729/-83，但生产热点集中在既有三个 owner；增量的大头是 322 行聚焦测试和双语契约文档。没有发现可以在不削弱 source-binding 证明的情况下安全删除的并行框架。

我的整体评价

没有发现阻塞问题。这个 PR 修复的是“review、validation、effect、receipt、projection 必须指向同一 canonical source”这一条完整语义，而不是把失败隐藏在更好看的状态或错误文本后面。实现保持 TypeScript 决策权、Python effect adapter、UI/readback consumer 的既有边界，负例也覆盖了最容易在重构中遗漏的 source drift 与 historical replay 顺序。

未来向前看的小步重构已经体现在本 PR：重复的终态 source 判断收敛到 typed lifecycle，Python 没有再复制一套规则。继续抽象反而会扩大协议面，当前无需额外框架。

English verdict: APPROVE - exact head db51008b26c172e308d037e4358953aca53aaf0f correctly binds reviewed canonical terminal actions to one source across validation, effect, receipt replay, and projection recovery; the focused Python and real file/SQLite TypeScript authority suites passed with no blocking finding.