feat(todos): converge Monitor observation and reactivation on canonical authority

[huangruiteng]

Promoted Goals could create and complete grouped PR Monitors, but membership observations and reopening a completed bucket still fell into the fenced legacy writer. This closes that existing issue-fix caller through the existing TypeScript Todo update transaction and File/SQLite/PostgreSQL providers. It advances #4574 and the TS T2/shared-authority L4 checkpoints.

A versioned observation intent now commits the Monitor transition, status, generation and immutable receipt together. Reactivation requires fresh material evidence after completion; the same member hash starts a new cycle, while replay returns the original receipt without reopening later completion. Current execution proof remains mandatory for leased observations; retained-lease/hard-lease reactivation stays fenced. No new command, RPC or provider-specific state machine is added.

Grouped reconciliation also retries pending Markdown projection when business state is unchanged. Native priority-prefixed Todo text renders without persisting redundant derived fields; explicit display conflicts still fail validation. Legacy updates reuse the same reactivation planner. This intentionally rejects stale reopening and clears terminal markers from the new cycle. Old update request identities remain compatible; provider defaults, live promotion and quota settlement are unchanged.

Validation: 687 provider-contract tests passed with zero skips, including an isolated real PostgreSQL 16.15 server; focused TS tests (54), Python integration/parity suites (66 and 105), final grouped caller tests (15), and fresh-wheel CLI/facade tests (21) passed. The enhanced four-arm rehearsal used a complete read-only Goal snapshot (369 Todos/9 leases), showed baseline poll parity and the previously unsupported update, preserved the original source, and produced identical File/SQLite/PostgreSQL heads. TypeScript typecheck, repository mypy scope and focused Ruff passed. Counts describe separate suites and overlap.

Scope remains bounded: reconciliation is atomic per Todo, not across all buckets; projection and quota retain their own recovery owners. Remaining executor fences, other callers/consumers, SQLite durability/soak, capture continuity and whole-Goal migration/default qualification are still open. No frontend/Lark companion is needed: the existing shared issue-fix command is unchanged and its operator-surface contract is exercised. This runtime PR is for maintainer merge.

Final qualification: risk canary passed 19 selected checks plus 5 direct checks, with no failures, skips or manual holds. Exact change-quality receipt is valid. Paired legacy facade checks preserve ordinary same-second observations and demonstrate the two intentional stale-reactivation/new-cycle fixes. Remote CI is not consulted under the resolved managed-review policy.

[huangruiteng]

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

Reviewed head: 8c46ec0962e95c94def5a20c54b6d0cc04189711 · base: a20e71395c6b6b10ed3c00ecc3631d0aa0402151.

动机

没有发现阻塞问题。这个 PR 是 #4574、TS T2 与 shared-authority L4 的一个有实际 caller 的完整增量：分组 PR Monitor 已能 canonical create/complete，但成员变化和重新出现仍被 Python 的 observation 排除分支送回旧 writer。基线复现中，legacy 通过，File/SQLite 两条路径失败。它闭合既有 CLI/facade 的创建→观察更新→结束→再激活，以及显示失败后的恢复；不把一次 caller 闭合作为默认切换或全量 Python 退役完成。

评审框架采用 TS T2、shared-authority L4/D1–D3 和观察协议。仓库现有后继工作仍覆盖 executor fence、其他 caller/consumer、SQLite durability/soak、capture、whole-Goal migration/default；本 PR 没有取消这些验收项。

改动思路

复用现有 todo_update RPC/事务，通过 v4 携带观察意图；Python 只负责路由、编码和调用已有 projection outbox。TS 的 public/native field planner 共用 monitor_metadata，当前 lease proof、CAS 和 immutable receipt 保持各自唯一 owner。旧版 update 请求 identity 不变。

对“只改路由”的替代方案做了检查：旧 planner 不接纳观察，且不能正确表达完成后的新周期；以 raw metadata 绕过去会把 generation 和状态权交回 caller。新建命令/RPC/Monitor engine 也无必要。因此本次只扩展已有 owner，没有新生产模块。

正向流程是：既有 issue-fix CLI 获取并分组 PR 事实→观察更新→读取原回执/当前完整 authority→检查 actor、lease 和观察新鲜度→一次 CAS 写入状态、generation、回执→独立投影。多个 bucket 仍按 Todo 分别提交，quota settlement 仍有独立 owner。Frontend/Lark 不需要新设置或指令，既有共享命令合同和真实 CLI 路径已测试。

具体改动

26 文件，+670/-58：生产代码 +156/-34，验证 +409/-17，文档 +105/-7。验证复用完整混合 fixture 与四臂 rehearsal，不提交真实快照、私有日志或生成文件。RFC 原 checkpoint 已更新。

关键代码讲解

1. monitor_metadata.poll：done→open 必须是晚于 completion 的新 material observation。即使 hash 相同，也推进新周期 generation；历史 effect 不能重新激活。字段 planner 同时清理当前 terminal 标记，legacy/native 共享此规则。
2. todoUpdateAdmissionRejection：观察必须来自合法 Agent Monitor 与注册 actor；不接受 delegated observation override。已有 execution 仍验证当前 key/version，任何 retained lease 都阻止再激活，hard-lease 不获得缺少 proof 的豁免。
3. executeCoordinationTodoUpdate：observation 进入请求摘要与原回执，状态/代数/回执一次 CAS。原请求重试先恢复历史结果，不会重开后来完成的 Todo。并发竞争不留下新 receipt；提交成功后响应丢失可由原 receipt 恢复。
4. materialize_issue_fix_grouped_monitors：无成员变化也尝试已有 projection delivery，避免“业务已完成、显示永远不恢复”。保留 unkeyed observation 的同秒兼容语义，没有强加新 effect ID。
5. _projection_record：从文本派生缺失的 display priority/title，不修改 canonical record；显式字段冲突仍被 parity 检查拒绝。

对主干的风险

主要风险是把历史成功当作当前许可，或让新周期继承旧 completion 状态。反例已覆盖：旧回执在后续 completion 后重试、不同 ID 的过期观察、混合 owner/config/copy intent、未注册/错误 actor、archived/superseded Todo、失效/错误 lease proof、retained lease 再激活、真实 CAS 竞争和提交后响应丢失。负例检查状态与 receipt 没有意外写入。Proxy 只在真实 provider commit 后注入响应/回读故障，并没有伪造持久化成功。

受影响生产入口、真实后端与安装包均验证：687 项 provider 契约测试通过、0 skip，包含隔离 PostgreSQL 16.15；54 项聚焦 TS、66/105 项 Python 集成与 parity、15 项最终 caller、21 项 fresh-wheel CLI/facade 测试通过。计数属于有重叠的不同 suite。

完整只读快照 rehearsal 使用 369 Todos/9 leases，在 disposable File/SQLite/PostgreSQL 上运行：基线 leased poll 语义保持；v4 在基线拒绝且无写入；最终三个 provider head 相同，非目标记录及原始源保持不变。它证明真实 backend 上的事务语义，不代表已部署 PostgreSQL service、跨平台容量资格或长期 soak 完成。

语义与 CI 对齐

共享词汇、状态和 effect owner 继续复用。显式行为变化已在中英协议/RFC、PR 和 routing 测试中披露：旧观察不再重开任务，同 hash 新周期推进代数并清理 terminal 字段。额外的同 fixture 基线/head legacy facade 对照确认：普通 unkeyed 同秒观察完全一致；基线 stale reopen 成功而 head 拒绝且原文件不变；fresh same-hash 从基线 generation 1/残留 completion 改为 generation 2/清理完成标记。这些是有理由的修复，不是为了 byte parity 保留错误行为。

TS typecheck、仓库指定 mypy 22 文件、聚焦 Ruff、public/private 扫描通过。Risk canary 19 项选择检查 + 5 项直接检查通过，0 failure/skip/manual hold；包含 CLI 输出、热路径及 maintainability 预算，未调整预算。精确质量回执 cqr_ce5c86a49d5f10d69301 有效，fingerprint ce5c86a49d5f10d6930104ca91c6c116a0269f037363d70cd8ccc7c98257abf1；safe-fix allowed，正式 quality pass 未追加修复，blocker/warning/advisory 均为 0。当前 Goal 评审策略为 wait_for_ci=false，因此未查询或等待远端 CI，不能把本地通过描述为 CI 全绿。

我的整体评价

APPROVE，此结论只适用于上述 exact head。 pr-review policy revision 7 的 19 项 evidence 已完成，结构化 result check 通过；发布前远端 head 未变。未来重构检查已应用：删除 observation routing exclusion、复用 Monitor/field planner、减少重复 Python intent 计算，并沿用 projection owner；更大的执行 fence 迁移留在原 owner/后继边界。

这是一个已交付实际 caller 闭合的增量。保留 lease 的再激活仍明确拒绝、bucket 间不原子、旧 writer 仍服务未迁移 Goal；这些边界没有被测试数量或 green canary 掩盖。回滚须保留处理 v4 pending retry 的兼容代码，不可解除 writer fence 恢复旧 Markdown 为权威。运行时改动按仓库规则留给维护者合并。

English verdict: APPROVE - 8c46ec0. The existing grouped-Monitor caller now uses the shared typed observation/update transaction with fresh-cycle semantics and independent projection recovery. Real File/SQLite/PostgreSQL, baseline counterfactuals, full-snapshot rehearsal, installed-wheel paths and risk canaries passed. No blocking finding; retained-lease reactivation and provider/default qualification remain explicitly open. Remote CI was not consulted under the resolved Goal policy; maintainer merge required.

[huangruiteng]

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

动机

该 PR 补齐 issue-fix grouped Monitor 在 canonical authority 上的最后一段确定性断点：已 promotion 的 Goal 可以创建和完成 Monitor，但 material membership observation、完成后的 reactivation，以及“业务状态未变但 projection 上次失败”的恢复仍可能回到旧 writer 或被 early return 跳过。这会让同一个调用方在 canonical create/complete 与 legacy observe/reactivate 之间分裂，也会让 monitor_changed 依赖方和永久 Markdown 读者看见不一致状态。

本次复审未发现阻塞项。分支已 rebase 到最新 main (e7ef75c08a8398c9cc8e1a04369f13184389185b)；range-diff 显示原 3 个提交与新 3 个提交均为 =，说明 refine 仅更新基线，没有改变已审补丁语义。

改动思路

实现没有新增第二套 Monitor 引擎，而是把 observation 作为 Todo update v4 的 typed intent，复用现有 admission、Monitor planner、AuthorityStore CAS/receipt 和 projection outbox：

• 调用方只提交观察事实；generation、状态、schedule 与 terminal marker 的下一状态由持锁后的 canonical head 决定。
• completed Monitor 只有在 observation 晚于当前 completion、确有 material lifecycle occurrence 且没有 retained lease 时才允许 reactivation。
• 同一成员 hash 在新的、足够新的 lifecycle 中仍会推进 generation；历史 receipt 可以只读 replay 旧结果，但不能重新授权当前状态变更。
• projection delivery 独立于业务 CAS；业务状态已相同也会重试 pending display，而不会重复业务 effect。

这个边界保持 TypeScript 为状态机与 effect authority，Python 仅适配已有 issue-fix 入口和 projection 回读；quota settlement、lease lifecycle、provider promotion/default 均未扩大。

具体改动

• 扩展 versioned Todo update request/receipt，加入 monitor_observation 与 monitor_poll_transition，旧 v0-v3 身份和 pending retry 兼容性保留。
• 在通用 Todo admission 中校验 actor、target、archive/supersede、status intent 和 retained lease；混合 ownership/config/copy intent fail closed。
• 复用 Monitor metadata planner 统一 freshness、effect replay、generation、schedule 与 completion marker 规则。
• issue-fix grouped materialization 对 promoted File/SQLite/PostgreSQL authority 走 canonical update；unchanged reconciliation 也会 drain 现有 projection outbox。
• 永久 projection 从 canonical Todo text 派生缺失的 priority/title，不把显示字段反写成第二份权威状态。
• 补充 provider-wide、public facade、lost-response/CAS、stale replay、same-hash new lifecycle、retained-lease rejection 和 projection retry 覆盖，并同步协议/RFC 的中英文语义。

关键代码讲解

• materialize_issue_fix_grouped_monitors：现有公开 caller 的 orchestration 边界；构造 observation、调用统一 Todo facade，并在业务 no-op 时仍结算 projection。
• todoUpdateAdmissionRejection：在写入前集中拥有 actor、status、archive/supersede 与 lease authority 的拒绝语义。
• executeCoordinationTodoUpdate：在一个 AuthorityStore CAS 中提交 Todo、Monitor transition、audit 与 immutable receipt，并用 receipt 处理 lost-response replay。
• monitor_metadata.poll：拥有 observation freshness/materiality、generation、schedule 以及 completed-to-open transition 的共享规则。
• _projection_record：只做 canonical record 到永久显示的可重建派生，避免投影字段成为新 authority。

对主干的风险

最高风险是：旧的成功 observation 在 Monitor 再次完成后被 replay，错误地重开更新的 terminal lifecycle 或推进两次 generation。当前实现通过“历史 receipt 只返回旧结果、不重写当前 head”、新 operation 重新执行当前 admission、generated_at > completed_at、source witness 与 store CAS 一起封住该路径。测试同时覆盖 stale new-id、lost response、racing CAS、retained lease、unrelated Todo/lease/receipt 不变和 real PostgreSQL provider。

剩余风险被清楚限制在本 PR 外：retained-lease reactivation 的生命周期解决、其他 caller/consumer、跨 bucket 原子性、SQLite 长时 durability/soak、capture continuity、whole-Goal migration/default，以及 deployed PostgreSQL service qualification。它们不应被本 PR 的 caller-level 通过结论误认成已完成。

语义与 CI 对齐

• 精确 head：b76b676805b0fbab38fc846328582ab64efb88df；patch SHA-256：fa91a4e331005ad92627a6a681182a4eeb2f826496865ec18d22699cc183fa4e。
• 本地：control-plane typecheck 与 changed-path Ruff 通过；focused Python 66 passed；完整 control-plane 2089 tests / 2071 passed / 0 failed / 18 repository-declared skips；git diff --check 通过。
• GitHub exact-head required checks 全部通过，包括 4 个 test shards、kernel static、Node min/forward compatibility、Windows、installed/e2e/mutant、dashboard/frontstage/release、DCO、dependency review 和 real PostgreSQL。deploy/presentation/upload/publish 是条件式 skipped job，不是缺失的 required evidence。
• 一次额外的全仓 ad-hoc mypy 会沿当前主干 imports 扫出既存噪声；它不是仓库定义的 scoped oracle，因此没有被伪报为通过，也不替代已通过的 kernel static/typecheck。

我的整体评价

这是一个边界完整、owner 正确且可回滚的 caller slice：它消除了 create/complete 与 observe/reactivate 的 authority split，修正了 stale reopen 与 same-hash new lifecycle 语义，也把 projection retry 与业务 effect 正确解耦；没有引入新命令、store、table、capability 或 provider-specific state machine。补丁规模主要来自跨 provider 与负向合约证据，和所改变的 authority 风险相称。

结论：无阻塞发现，建议合并。由于这是 loopx/control_plane/**、Todo persisted state/receipt 与 runtime authority 的行为变更，仓库规则要求由 maintainer 在精确 head 上完成合并；本条是 author-owned PR 的 COMMENTED approval record，不执行作者自合并。

English verdict: APPROVE - b76b676. No blocking findings; the patch is semantically unchanged after rebasing, exact-head validation is green, and maintainer merge is required by the control-plane policy.