feat(quota): move monitor poll commit into TypeScript

[hhyykk]

Summary

• move quota monitor-poll admission, target/event/result construction, replay/CAS, provider intent, and repairable JSON/Markdown/index persistence into one versioned TypeScript transaction;
• keep Python as a bounded facade for compact facts, the real Todo provider, one shared cross-writer lock, transport, and legacy after-projection;
• delete the replaced Python policy/target authority and its implementation-specific smoke;
• remove the full-CLI tail regression with one conservative prepared WAL and a provably-non-Git registry fast path, without weakening crash repair or Git-backed freshness.

Placement

• capability owner: existing quota control-plane boundary;
• provider: built-in Python monitor-Todo persistence provider, retained only because it performs the real registry mutation;
• extension boundary: none; this is an existing built-in product contract, so no new capability, provider package, or extension lifecycle is introduced;
• nearest owner: loopx/control_plane/quota/ owns the transaction; scheduler/Todo modules expose only the retained provider and typed metadata.

Migration economics receipt

Field	Evidence
Canonical owner	Before: Python monitor_poll.py, monitor_poll_policy.py, and monitor_target.py. After: TypeScript quota.monitor_poll.commit; Python retains compact facts, provider, transport, lock, and legacy projection only.
Legacy semantic code deleted	826 Python product LOC: 601 replaced lines in monitor_poll.py, 161 policy LOC, and 64 target LOC.
Bridge code added	495 Python diff LOC for compact fact projection, typed rejection transport, _native_result/_request, and the named compatibility projections. The 34-line _provider_writeback is excluded because it adapts the retained real provider.
Cross-runtime calls	Before: zero because the path was all Python. After: one request/response for no-Todo write, replay, or recovery; one preflight plus one final reduction around the real Todo provider.
Product-code net change	2,743 added - 831 deleted = +1,912 product LOC. Tests/examples are separately 1,045 added - 242 deleted = +803; docs are excluded. The next deletion is the 495-line bridge when quota decision, Todo persistence, status projection, and remaining index writers are native.
Migration scaffolding	Deleted the 218-line implementation-specific policy smoke and 18 target-helper assertions. No temporary parity or performance harness is committed; retained tests cover shipped or persisted contracts.
Facade exit	Delete the facade when should-run, Todo monitor persistence, status projection, and every run-index writer execute in the native TypeScript process.
Correctness and performance	Identity/admission, effect isolation, provider fencing, malformed receipts, concurrent CAS, crash repair, packaging, launcher, and the final full-CLI gate pass. The earlier Todo-write p95 hold is resolved below.

The bilingual durable receipt is also recorded in the migration RFC.

Performance

Managed runtime, 10 cold / 100 warm / 25 durable samples:

Metric	p50	p95
Cold start	274.35 ms	450.44 ms
Warm event	1.13 ms	1.72 ms
Durable commit	2.06 ms	2.27 ms

Daemon RSS was 126.0 MiB both idle and after a bounded 50-request burst.

Final-head 64 interleaved full-CLI pairs against origin/main@0233a2f32ca6bd4f86dad4eb215dd49428864a71:

Path	Baseline p50/p95	Candidate p50/p95	Result
Todo write	663.34 / 971.40 ms	631.96 / 878.10 ms	p50 -31.38 ms / -4.73%; p95 -93.31 ms / -9.61% — pass
Exact replay	598.23 / 910.75 ms	580.13 / 900.69 ms	p50 -18.09 ms / -3.02%; p95 -10.06 ms / -1.10% — pass

Both p95 deltas are within the 5% and 25 ms full-CLI limits. This supersedes the earlier performance hold without relaxing a threshold or substituting a microbenchmark for the product path.

Validation

• npm run test:control-plane — 231 passed;
• npm run typecheck:control-plane — passed;
• focused monitor/Todo/registry Python qualification — 72 passed, 42 deselected;
• Ruff on the changed registry implementation and tests — passed;
• source-tree and isolated-wheel monitor-poll-writeback public smokes — passed;
• final-head managed-runtime and 64-pair full-CLI performance gates — passed;
• wheel and sdist built from a clean Git archive and passed Twine; both contain monitor_poll_commit.ts and registry.py;
• isolated wheel install passed packaged write/replay and console-launcher version readback;
• loopx canary premerge --from-git-diff --git-diff-base origin/main --goal-id loopx-goal --tier standard — all 18 selected checks passed with zero failures, warnings, or manual holds;
• diff whitespace, exact merge base/base, DCO trailers on every branch commit, and explicit public/private scans — passed.

Exact-head GitHub checks are tracked separately on this draft PR. It remains unmerged.

Future-facing pass

Applied: duplicate Python admission/target/event/replay/artifact authority is deleted, provider identity is effect-bound, receipt/artifact durability has one typed owner, and guaranteed-failing non-Git probes no longer launch subprocesses. The conservative prepared WAL retains the public index as commit proof. Further facade deletion is deferred because native quota decision, Todo persistence, status projection, and all index writers are not yet present; adding speculative native providers here would widen the PR without an active caller.

中文摘要

本 PR 把 Quota monitor-poll 的准入复核、事件与结果构造、effect replay、index CAS、provider intent 和耐久写入统一迁到 TypeScript。Python 只保留 compact facts、真实 Todo provider、共享锁、transport 与 legacy projection；共删除 826 行旧 Python 语义代码。

性能修复保留一份保守的 prepared WAL，并继续以 public index 作为 commit proof；只有在 registry 可证明不位于 Git worktree 时才跳过 Git subprocess。最终头部的 64 对完整 CLI 样本中，Todo write p95 从 971.40 ms 降至 878.10 ms，replay p95 从 910.75 ms 降至 900.69 ms，两者均通过 5% 与 25 ms 门槛。此前的 owner-review 性能 hold 已解除，PR 仍保持 draft 且未合并。

[hhyykk]

Pre-merge validation receipt

Changed surfaces

• TypeScript quota control-plane transaction: admission revalidation, target/event/result reduction, exact-effect replay, provider intent, CAS, and durable JSON/Markdown/index/receipt repair.
• Python compatibility facade: compact fact projection, typed rejection transport, retained Todo provider, managed transport, shared cross-writer lock, and legacy after-projection.
• Todo monitor metadata plus scheduler/provider seams.
• Risk-based canary selection, focused public smokes, tests, and bilingual migration/operation docs.

Migration economics against the PR merge base: product code +2,715/-831 (net +1,884), tests/examples +913/-242 (net +671), and 826 lines of replaced Python semantic authority deleted. The bounded Python bridge is 495 diff LOC; it is the next deletion target once quota decision, Todo persistence, status projection, and all remaining index writers are native.

Checks run

• npm run test:control-plane: 231/231 passed.
• npm run typecheck:control-plane: passed.
• Focused monitor/Todo/effect-runtime Python tests: 33 passed.
• Full Python suite: 4,679 passed, 12 skipped in 19m09s.
• CONTRIBUTING Ruff scope: passed with Ruff 0.15.22.
• Mypy: passed, 15 source files.
• Public monitor-poll-writeback, external-evidence-observation, and monitor-todo-policy-seam smokes: passed.
• examples/repository-hygiene-smoke.py: passed.
• Wheel and sdist built from a clean Git archive; both contain monitor_poll_commit.ts, and an isolated wheel install passed packaged durable write/replay plus CLI version readback.
• loopx canary premerge --from-git-diff --git-diff-base origin/main --goal-id loopx-goal --tier standard: 18/18 selected checks passed; changed-file compile and 24-file public/private boundary scan also passed.
• Diff whitespace, DCO trailers on every branch commit, debug-marker scan, and explicit public/private wording scan: passed.

Failures, skips, and superseded runs

• An initial full-suite collection attempt found an ignored stale build/lib copy and stopped on module mismatch. The ignored artifact was moved outside the worktree; no tracked source was changed.
• One clean full-suite run was superseded when origin/main advanced and was interrupted after 424 passes. A later run was intentionally stopped after 1,629 passes / 4 skips when self-review found a prose-substring retry classification; the implementation now preserves the typed monitor_poll_admission_rejected diagnostic code, with a negative regression test proving prose alone cannot authorize retry.
• An exploratory repository-wide Ruff invocation (outside CONTRIBUTING's prescribed scope) reported 631 pre-existing findings in deprecated, example, and otherwise out-of-scope files. The exact prescribed scope passes.
• The final full suite skipped 12 platform/environment-specific tests (including native Windows-only coverage); zero tests failed.

Manual hold and merge decision

The managed runtime passes its direct gates: cold start 312.50/523.48 ms p50/p95, warm event 1.27/1.78 ms, durable commit 2.25/5.67 ms, and 126.5 MiB RSS before/after a bounded burst. In 64 order-alternated full-CLI pairs against the merge-base baseline, exact replay changes by +1.54%/+1.41% p50/p95 and passes; Todo write changes by +3.94%/+19.54%, with p95 rising 179.39 ms to 1,097.63 ms.

That write-tail miss remains an explicit owner-review hold. The PR is suitable for code review because typed behavior, compatibility, crash repair, concurrency, packaging, and risk-selected boundaries are covered, but it must not merge until the owner reviews the p95 result. No threshold was relaxed and no faster direct-runtime result is substituted for the full-CLI gate.

Future-facing pass

Applied within the same boundary: duplicate Python admission/target/event/replay/artifact authority was deleted, rejection classification became typed, provider identity is effect-bound, and one TypeScript transaction now owns durability. Further facade deletion is deferred because native quota decision, Todo persistence, status projection, and every index writer are not yet available; speculative providers were not added.

[hhyykk]

Sonar reliability repair receipt

Exact pushed head: b1de40ebdc997e6ded788aafc75c41337b13145e.

Changed surfaces

• Runtime: loopx/control_plane/quota/monitor_poll_commit.ts. The original blocker repair uses codePointAt and an explicit UTF-8 ordinal key comparator. The final follow-up replaces the trailing-hyphen regex with a bounded backward scan (+6/-1 from the prior head).
• Docs: both TypeScript-migration RFC receipts now report the exact merge-base economics: 2,720 added minus 831 deleted product LOC, net +1,889 (+2/-2 from the prior head). Test/example +671 and the 495-line bridge are unchanged.
• Exact Sonar readback after a666290c showed that S8786 remained open even though the overall quality gate had passed. Splitting the alternation into an end-anchored /-+$/ regex was insufficient because a near miss can still retry every start position; the explicit scan removes that backtracking path.

Checks run

• Static source oracle: no trailing-hyphen replacement regex remains.
• Focused TypeScript monitor-poll transaction tests: 11/11 passed.
• Full TypeScript control-plane suite: 231/231 passed.
• TypeScript control-plane typecheck: passed.
• Focused Python monitor/Todo/CLI compatibility tests at the preceding runtime repair head: 30 passed; the final follow-up changes no Python.
• git diff --check, explicit path staging, DCO trailers, merge-base/base verification, and the public/private scan: passed.
• loopx canary premerge --from-git-diff --git-diff-base origin/main --goal-id loopx-goal --tier standard: 4 direct checks and all 18 selected checks passed, with zero failures, warnings, advisory failures, policy failures, or canary-level holds.
• Exact-final-head GitHub checks: pytest, Windows PowerShell, both builds, DCO, dependency review, and SonarCloud Code Analysis all passed.

Failures, skips, and holds

• No local or required remote validation failed, and no test in the repair runs was skipped. PR-only deploy/upload/publish jobs were expectedly skipped.
• Correction: the earlier receipt described the end-anchored tail regex as resolved before exact Sonar issue readback proved otherwise. SonarCloud automatic analysis at 2026-08-28T03:21:39Z now covers exact final head b1de40eb; the quality gate is OK, unresolved S8786/S2871/S7758 findings are all zero, and the open smell count fell from 22 to 21.
• The previously disclosed full-CLI Todo-write p95 owner-review hold remains unchanged. This PR stays draft and must not merge until that hold is reviewed.

Why this coverage is enough

The final runtime delta changes only artifact-stem tail trimming and preserves the same output for every admitted character shape. The focused suite exercises artifact naming, digest compatibility, admission, replay, concurrency, provider fencing, and durable repair; the full TypeScript suite and risk-selected canary cover the registered runtime boundary and adjacent control-plane contracts. The bilingual docs change only reconciles the line-count receipt. Broader non-blocking maintainability refactors remain deferred because they would widen this reliability repair and invalidate the already reviewed migration/performance scope.

[hhyykk]

Performance hold closure receipt

Exact pushed head: 177f3a4dcb1121cf44871ffc4c1393f77267f689.
Pinned baseline and merge base: 0233a2f32ca6bd4f86dad4eb215dd49428864a71.

Changed surfaces

• quota.monitor_poll.commit now persists one conservative canonical prepared WAL instead of both prepared and committed-stage copies. The public index remains the commit proof; prepared and committed crash repair, exact replay, CAS, and legacy sidecar cleanup remain covered.
• Registry Git classification skips subprocesses only when ancestor-marker discovery proves the registry is outside a normal worktree and no GIT_DIR/GIT_WORK_TREE override exists. Git worktrees, linked worktrees, submodules, ignored/tracked/untracked classification, and missing-Git behavior retain their original fresh boundary.

Final performance

Final-head managed runtime (10 cold / 100 warm / 25 durable): cold start 274.35/450.44 ms p50/p95, warm event 1.13/1.72 ms, durable commit 2.06/2.27 ms, and 126.0 MiB RSS idle/after the bounded burst.

In 64 interleaved full-CLI pairs:

Path	Baseline p50/p95	Candidate p50/p95	Delta
Todo write	663.34 / 971.40 ms	631.96 / 878.10 ms	p50 -31.38 ms / -4.73%; p95 -93.31 ms / -9.61%
Exact replay	598.23 / 910.75 ms	580.13 / 900.69 ms	p50 -18.09 ms / -3.02%; p95 -10.06 ms / -1.10%

Both p95 deltas are within the 5% and 25 ms full-CLI limits. This supersedes the earlier performance hold without changing a threshold or substituting the direct runtime benchmark for the product path.

Qualification

• prepared-WAL replay and crash repair, legacy prepared-plus-sidecar cleanup, and canonical committed-receipt repair: passed;
• non-Git no-subprocess, Git tracked/ignored/untracked, and missing-Git tests: passed;
• all 231 TypeScript control-plane tests and typecheck: passed;
• focused Python monitor/Todo/registry qualification: 72 passed, 42 deselected; changed-file Ruff passed;
• clean-archive wheel/sdist build, Twine, required package contents, isolated wheel monitor-poll write/replay, and console launcher: passed;
• standard premerge canary: 18/18 selected checks, zero failures, warnings, or manual holds;
• exact merge base/base, DCO trailers, diff hygiene, and public/private boundary scans: passed;
• exact-head GitHub checks: DCO, dependency review, Release Artifacts build, Frontstage build, pytest, Windows PowerShell, and SonarCloud passed; PR-only deploy/upload/publish jobs were expectedly skipped.

The performance hold is closed. The PR remains draft and unmerged for normal review.

[huangruiteng]

评审 exact head：177f3a4dcb1121cf44871ffc4c1393f77267f689

动机

这个 PR 把 quota monitor-poll 的准入、事件构造、事务提交、CAS、重放和损坏尾部修复迁到 TypeScript control-plane owner，Python 缩为参数适配与 Todo provider writeback，目标是减少 Python/TypeScript 双重状态权威，并让 monitor poll 与现有 typed effect runtime 共用 durable transaction contract。方向正确，也与 migration RFC 和 quota 文档的更新一致。

改动思路

主路径现在是：Python monitor_poll.py 解析 CLI/刷新 status，调用 TypeScript quota.monitor_poll.commit 做 event/preflight；如果需要 Todo 状态写回，TypeScript 产出绑定 effect id 的 provider plan，Python write_monitor_poll_todo_state 在锁内更新 monitor metadata/创建 successor，再把 provider receipt 交回 TypeScript commit。TypeScript 以 request digest、index digest 和 effect receipt 做同 effect replay、不同 effect CAS、artifact repair，并由 effect_runtime_handlers.ts 注册新 handler。

正向路径覆盖了 due/external/blocked monitor 的准入、material transition、successor receipt、run record/index/Markdown artifact 和 status reload。负向路径覆盖了非法 schema/goal/todo、provider plan 不匹配、陈旧 index fence、receipt path escape、丢失 index history 和 artifact drift，并采用 fail-closed 行为。monitor_metadata.py 新增 effect identity replay，registry.py 增加 Git probe fast path；旧 Python policy/target 实现和过宽 smoke 被删除，相关 canary、docs、smoke 与 TypeScript/Python tests 同步改到新 owner。

具体改动

• monitor_poll_commit.ts 新增 typed request/decision/observation schema、admission、record rendering、provider-plan/receipt 校验、事务 receipt、CAS、same-effect replay、artifact repair；effect_runtime_handlers.ts / effect_runtime_io.ts / tsconfig.control-plane.json 接入该 handler。
• monitor_poll.py 从 1,130 行的 Python authority 收缩为 runtime bridge；monitor_poll_policy.py、monitor_target.py 以及旧 policy smoke 被移除，scheduler writeback 改为携带 monitor_effect_id 和 successor receipts。
• Todo monitor metadata 在锁内识别同 provider effect 的幂等重放，并保留 generation/counter；测试明确覆盖 material successor 复用和并发 poll。
• registry Git probe、canary catalog/qualification、quota 文档、迁移 RFC、开发课程与 focused smokes 均更新到 TypeScript owner。

我独立验证了：231 个 TypeScript control-plane tests、TypeScript typecheck、27 个 focused Python tests、Ruff、compileall、monitor-poll-writeback-smoke.py、external-evidence-observation-smoke.py、monitor-todo-policy-seam-smoke.py、git diff --check；远端 11 个 checks 均成功或按预期 skipped。

[P1] provider receipt 只在 plan 字段非空时校验 successor route，不能真正 fence “full material successor receipt”

validateSuccessorReceipts 在约第 982–1016 行只在 plan.next_task_repository、next_required_capabilities、next_continuation_policy、next_target_key、next_claimed_by 非空时比较，而且大多只比较 successor_receipts，没有把 next_todos 的相同 route 字段与 plan/receipt 绑定。于是 provider receipt 可以在 plan 未声明 repository/capability/claim 时注入任意值，或让 next_todos 与 successor_receipts 在这些字段上互相矛盾，TypeScript 仍会接受并把它作为 transaction payload/receipt 输出。对于未显式提供的字段，Python provider 仍有确定语义（例如 derived target key、默认 continuation policy、空 capabilities/claim/repository），不能简单跳过校验。

这破坏了本 PR 最核心的 authority migration invariant：TypeScript commit 无法证明 durable receipt 与实际创建的 Todo route 相同；provider 漂移或回归会被静默固化成错误 evidence，而不是 fail closed。请把 agent successor 的全部 canonical route 同时绑定到 plan 的显式值或 provider 的确定默认/派生值，并逐字段校验 next_todos 与 successor_receipts 一致；增加 negative tests，至少覆盖空 plan 字段注入、derived target mismatch、以及 next_todo/receipt route 分叉。

对主干的风险

当前 blocker 不影响普通无 successor 的 unchanged poll，也不否定 CAS/replay/artifact repair 的整体实现；但 material monitor 正是会驱动后续工作的控制面路径。若不修复，错误 repository、capability、continuation、claim 或 target lineage 可以进入 API payload 与 durable evidence，后续调度/审计看到的 route 可能与 Todo state 不一致。这属于事务边界完整性缺口，应该在合入前修复。除此之外，没有发现 typed-state、domain-neutral wording、默认行为披露、guidance-vs-obligation 或 public/private boundary 的额外 blocker；删除旧 smoke 与 owner migration 也有相应文档和 focused coverage。

我的整体评价

结论：REQUEST_CHANGES。迁移方向、架构分层、幂等/CAS/repair 设计和验证面总体扎实，future-facing pass 也正确地删除了第二套 Python policy authority，而不是继续叠兼容层。但 provider receipt 是 Python writeback 与 TypeScript transaction authority 之间的关键边界，当前“只验证非空字段、且没有双向绑定 next_todos”的缺口使整个 material successor receipt 尚未被完整证明。补齐全字段 canonical fence 和负向测试后，这个 PR 很接近可批准状态。

English verdict: REQUEST_CHANGES on exact head 177f3a4dcb1121cf44871ffc4c1393f77267f689. The TypeScript ownership migration, CAS/replay/repair design, docs, and broad validation are strong, but validateSuccessorReceipts does not fence the full canonical successor route: absent plan fields can be injected and next_todos can diverge from successor_receipts. Bind all route fields (including defaults/derived target) across plan, next Todo, and receipt, with negative tests. Validation: 231 TS tests, TS typecheck, 27 focused Python tests, Ruff, compileall, three focused smokes, diff check, and all remote checks successful/skipped as expected.

[huangruiteng]

评审 exact head：9e1e5480294428daef45b8085d49f57e2222de06。未发现新的 blocker。 先前提出的 P1 已关闭：material agent successor 的 canonical route 现在同时逐字段绑定 provider plan、next_todos 与 successor_receipts；即使 plan 未显式给出字段，也会使用真实 provider 的确定默认值（空 repository/capabilities/claim、independent_handoff）和同算法派生的 target key，任何注入或分叉都 fail closed。

动机

这个 PR 把 quota monitor-poll 的准入复核、事件/结果构造、effect replay、index CAS、provider intent 以及可修复的 JSON/Markdown/index persistence 迁到 TypeScript control-plane owner，解决 Python policy、target 与 artifact transaction 多处重复权威的问题，同时保留真实 Todo provider 与 legacy projection 的兼容窗口。

改动思路

Python facade 只投影 compact facts、持有共享 cross-writer lock、调用真实 Todo provider 并传输 typed request/receipt；TypeScript 的 quota.monitor_poll.commit 负责 preflight/commit 两阶段 transaction、effect identity、provider-plan fencing、CAS、replay 和 crash repair。Todo 写回仍是两次 reduction 中间唯一的外部 effect，没有在 Python 重新建立第二套 admission 或 durable receipt authority。

具体改动

TypeScript handler 接管 monitor admission、target/event/result reduction、prepared WAL、canonical artifacts/index 与 repair；Python 旧 policy/target owner 被删除，monitor facade 和 writeback seam 缩为 provider adapter。registry Git probe 只在可证明为非 Git 路径且没有 Git 环境覆盖时跳过 subprocess，保留 worktree/submodule/tracked/ignored/untracked freshness。此次 refine 新增 requireCanonicalSuccessorRoute，对 repository、capabilities、continuation、target、claim 逐字段校验 receipt 与 next Todo，并补充 injected defaults、derived target mismatch、next_todo/receipt divergence 的负向测试。

对主干的风险

主要风险是 material monitor 错误路由后续 Todo、并发 poll 的 CAS/replay、crash repair 与 hot-path 性能。完整 route fence 已关闭 provider drift 缺口；同 effect replay、different-effect CAS、malformed receipt、path escape、lost index history 和 artifact drift 都有负向覆盖。此前完整 CLI 性能门禁的 Todo write/replay p95 均优于基线，prepared WAL 仍以 public index 为 commit proof。该设计复用既有 Effect runtime、Todo provider 和共享锁，未来只有在 Todo persistence/status/index writers 全部 native 后再删除剩余 facade，当前无需增加 speculative abstraction。

我的整体评价

rebase 到 main@d073854bd7f4ced5cce59a2950292a2c28e2ce53 后，focused Python 29/29、TypeScript control-plane 386/386（1 个 PostgreSQL 环境 gate skip）、TypeScript typecheck、mypy、changed-scope Ruff、compile、diff/DCO 与公共边界均通过；此前同一完整功能 scope 的 full Python 为 5061 passed、12 skipped，3 个并行/timeout 失败逐一复跑通过。LoopX exact scope 29 files，fingerprint 2c8f0c4da1a60043cf9db8d2d89a0045c95d3b801ac8d844b5a144f29449e83a，receipt cqr_2c8f0c4da1a60043cf9d 有效；standard premerge 18/18 通过、0 manual hold。exact-head GitHub DCO、dependency review、两个 build、Windows、Linux pytest、Sonar 均绿。结论：APPROVE 并自合并。

English verdict: APPROVED for exact head 9e1e5480294428daef45b8085d49f57e2222de06. The TypeScript monitor-poll transaction now fences the full canonical material-successor route across the provider plan, next Todo, and successor receipt, including deterministic defaults and derived target identity. The ownership migration, replay/CAS/repair semantics, performance closure, focused and broad validation, exact-scope quality receipt, premerge gate, and required GitHub checks all pass. Self-merge is authorized.