fix(quota): unify Todo admission and receipt-backed settlement

[huangruiteng]

Explicit Todo selection could revive a canonical completed Todo from stale Markdown (#4837), while refresh returned an actorless spend command and hid missing spend receipts (#4834). This change completes the selection → writeback → same-identity settlement/recovery path.

• Fresh explicit selection replaces Todo facts with one complete todo list snapshot before normal arbitration. Pre-promotion Markdown + event behavior remains; promoted empty/unavailable providers never fall back to display rows. Existing actor, capability, user-gate and hard-lane checks remain.
• TypeScript receipt readback owns settlement progress. Refresh/replay/spend render the same progress in JSON and Markdown; executable commands retain actor, Todo/replan, Turn, route and source. A missing spend receipt reuses the existing writer without another debit. Rejected recovery emits no spend instruction.
• Replaces helper-only tests with real File/SQLite CLI journeys and updates the T3/M7.4 checkpoints and self-repair pattern. No provider promotion or shared executor is introduced.

Validation: final focused Python tests (92), adjacent tests (54), TS receipt tests (47), typecheck, configured mypy, Ruff and public-boundary checks pass. The broader settlement/CLI run had 128 passes and one test harness output-format mismatch; that corrected test passes with the returned visible-goal command. Isolated real PostgreSQL store/service suites pass 193 + 10, with no skips. A supported source-checkout interpreter corrected the initial PostgreSQL invocation. The same real CLI harness on baseline 6212b7a8a reproduces both stale-canonical admission failures and the unusable returned spend command; the fixed journey also verifies one debit after receipt repair and a clean next wake. Final policy-bound canary: 19 checks pass, zero failures; exact diff quality receipt cqr_ee6de73f092745b4e0e3 is valid. Exact-head review concludes APPROVE; maintainer merge required. After latest-base integration, 41 real journey/canonical consumer cases pass; the matching nine-case head comparison also passes.

Affected entry points are quota/refresh CLI and their Markdown renderers. Dashboard/Lark do not consume these response fields or call these APIs directly; no configuration editor or frontend bundle changes are needed. Future-facing pass removes duplicate source/settlement knowledge within the existing quota/Todo owners. Runtime/control-plane change: maintainer merge required.

[huangruiteng]

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

Reviewed exact head: d4b35bfa1484f93d4658186c6723424ab8e49526. Base used for comparison: 6212b7a8ac21cdc352171fce83590482a84e4cdb.

动机

#4837 把 Markdown 展示行追加到当前候选后，会让 canonical 中已完成、展示中仍 open 的 Todo 获得新准入。#4834 的补扣命令缺少 Agent，而且以 spend run 存在代替完整回执。这次按现行 quota 契约、T3 来源边界和 M7 结算所有权评估，目标是完整的选择、回写、原身份结算及恢复。单补 actor 或单换 reader 都会留下已复现的另一半缺口；本 PR 完成这个切片，不宣称 R5/D1–D3 或整体 Goal 验收完成。

改动思路

新准入先复用 list_goal_todos 取得完整两角色 snapshot，再进入现有 eligibility、能力、用户 gate 和高优先级 lane 仲裁。promote 前保留 Markdown＋事件读取；promote 后只认选定 provider，空结果和不可用都不能回退展示。历史绑定的结算仍走原回执身份。

结算进度由既有 TS readback 从效果及回执归约，Python 只投影响应、渲染原身份命令。缺失 spend 回执复用已有幂等 writer；没有引入 executor、provider、配额政策或自动扣款。与 #4818 的 CLI 模块提取、#4795 的 source witness 范围分别核对，不重复其工作。

具体改动

共 24 个文件：生产代码 +156/−135，验证 +291/−210，文档及技能参考 +51。删除 Markdown side reader 和 run-presence 结算捷径；用真实 CLI journey 替换 helper-only 测试。更新英文/中文 T3、M7 检查点、quota 操作契约及 self-repair 模式。正常 refresh、恢复 refresh、spend 的 JSON/Markdown 都接入；Dashboard/Lark 没有直接消费这些字段或调用这些 API，无配置编辑器或前端 bundle 配套缺口。

关键代码讲解

• build_live_quota_should_run_decision：仅 fresh explicit selection 替换该 Goal 的 Todo facts，完整清单进入既有规划路径；不追加第二来源、不修改已绑定历史身份。
• settlementProgress：六态来自现有 typed receipt 结果。run 已写入但 receipt 缺失，仍是待恢复；settled 仅证明 writeback/spend 链，不能替代 Todo 终态或 Goal 验收。
• _settlement_actor_args：由 identity 补齐 Agent，拒绝冲突、重复或缺值 actor；Todo/replan 和带空格 Turn 的命令经过测试。
• attach_settlement_progress：复用原 builder，保留原 source、registry/runtime 路由；尚无 writeback 回执或恢复请求被拒绝时，不给出 spend 指令。CLI 在 refresh event 写入后重新读回，覆盖 raw API 暂缺回执的观察。

对主干的风险

最强反例已通过真实边界执行：canonical done/blocked、空 provider、provider 不可用、其他 Agent/排除/能力 gate、legacy 事件角色覆盖、显示范围外合法目标，以及已扣款但缺回执。原样执行返回命令后再删除临时回执并重放，总 debit 保持 1；下一次 wake 不再恢复同一未结算 Turn。异常注入仅限隔离合成状态。

在 base/head 上，仅移动目标显示位置并倒序其余 35 行，legacy/File/SQLite 六个观察相同：fixture SHA-256 52fa6e9480f517498b735eb0026b185f65fd2d784716406fa30d0cc91c297d9f，稳定观察 SHA-256 96fa48f5656636af27c22ea65b3eced4e384e954ec041f907841c88b19a28718。这说明保留合法可达性并不依赖旧 Markdown 旁路。相同九项真实 CLI 比较在 baseline 有三项预期失败（两个错误准入、一个返回命令执行失败），head 全部通过。

完整读取会增加 fresh explicit selection 的读取成本，但输出与结构预算通过；不据此声称完成大规模延迟或 D2 soak 验证。旧 guard 没有 source 时仍按既有 heartbeat 默认处理，文档已披露。回滚无需状态迁移；provider promotion、真实宿主部署和自动扣款均不在本 PR 内。

语义与 CI 对齐

这是既有结算观察词汇的有界扩展，核心 step/failure、身份、权限和幂等 writer 保持原所有者；新增 progress 是派生值，不是第二份持久化生命周期。默认行为修正已披露，错误和义务文本保持领域中立。建议命令不会自行执行，忽略结算仍会留下原有恢复义务。

本地验证：最终聚焦 92 passed，最新基线集成后真实 journey/canonical consumer 41 passed，邻接套件 54 passed，TS readback 47 passed；隔离真实 PostgreSQL store 193 passed、service 10 passed，无 skip。TypeScript、mypy（22 文件）、Ruff、公开边界检查及最终 19 项 canary 通过。保留了验证过程中的失败：首次 PostgreSQL 启动误用系统 Python 3.9，改用 source-checkout 3.13 后全过；较大 CLI 套件 128 项通过，另一个测试把成功的 Markdown 输出当 JSON 解析，修正测试格式接线后返回的 visible-goal 命令通过。没有把失败或 skip 记成通过。当前 review policy 为 wait_for_ci=false，未获取或等待远端 CI，不能据此宣称 CI 已绿。

我的整体评价

APPROVE，未发现未解决的阻塞项。改善来自删除重复事实/结算判断并完成真实调用、负例和恢复读回，不来自文件或测试数量。未来演进检查已应用于现有 quota/Todo 边界，没有新增公共传递参数或通用框架。最终 quality receipt cqr_ee6de73f092745b4e0e3 对该 head/diff 验证有效，完整 review result 通过当前 policy revision 7 的一致性检查。该检查不代替上面的实测证据，也不授予合并权限；此控制面 PR 留给维护者合并。

English verdict: APPROVE - d4b35bfa1484f93d4658186c6723424ab8e49526. Unified Todo authority prevents stale-display admission; receipt-derived progress supplies executable original-identity commands and repairs missing receipts without a second debit. Real CLI counterfactuals, isolated PostgreSQL, type checks and the 19-check canary pass. Remote CI was not consulted under the configured policy. Maintainer merge required.