Merge pull request #4862 from loopx-project/codex/authority-execution-closure

fix(issue-fix): close grouped Monitor execution and recovery

Author: huangruiteng

docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md

@@ -3211,7 +3211,7 @@ or moving a helper is not by itself a package exit.
 | A / L1: Monitor configuration (this slice) | Existing `todo update` config enters the TS planner/CAS/receipt; delete Python's duplicate intent field catalog. Separate authoring from observed hashes, times and generations. | Ordinary CLI/API, clear/omission, active lease proof, no-op/replay, failed display delivery, complete fixture and real providers. This does not complete delegated Chat or leased polling. |
 | A / L2: Complete public mutation admission | User completion updates share the TS edit/terminal transaction and reviewed Chat recovery; linked decision consumption/reject/cancel/resume now commit with the source, replacing Python followthrough rules. Continue the actual CLI/Turn/Chat inventory for remaining effect-owned decisions, delegated owner actions and Monitor lifecycle transitions; [caller contract](../../reference/canonical-todo-completion-update.md). | Build on merged T1 owners, not a generic raw patch. Prove permission rejection and exact caller response; remove replaced Python admission and name every remaining unsupported command. |
 | A / L3: Canonical lease lifecycle | Standalone acquire/takeover, atomic claim lease admission and maintenance reuse TS facts/decision/materialization and one provider opening fence. Explicit claimed-work transfer now commits source-authorized Todo ownership and the new lease generation together; canonical request types exclude legacy held-fence fields. Acquire success verifies current execution proof; canonical completion can recover missing display. | Full-head scope conflict, archived/ineffective holders, exact create-CAS retry, stale execution, process loss and real CLI/four-arm rehearsal are covered. [Operation and remaining callers](../../reference/canonical-lease-renew.md). Executor-held external-effect fences remain explicit work; D1–D3/default holds remain. |
-| B / L4: Leased Monitor poll and settlement | Current execution proof now binds CLI intent, observation/generation/independent-successor CAS and historical business receipt. Quota pending admission is frozen before the business write; recovery preserves that decision after lease retirement. | Existing L3 lease lifecycle, real File/SQLite/PostgreSQL, mixed fixtures, process death between business/quota commits, competing renewal and unchanged polling. [Operation and snapshot rehearsal](../../reference/protocols/quota-monitor-observation-receipt-v0.md). Ordinary polls leave leases unchanged and spend no quota; separate authorities stay separate. The retained grouped-Monitor observation/reactivation caller now uses Todo update v4 and the shared Monitor planner, with unchanged-group display recovery. Canonical reactivation now atomically retires retained execution and reopens the observation cycle, sharing typed admission with polling; a fresh execution still needs explicit acquisition. Executor acquisition for grouped reconciliation, wider L2 admission and D1–D3/default remain open. |
+| B / L4: Leased Monitor poll and settlement | Current execution proof now binds CLI intent, observation/generation/independent-successor CAS and historical business receipt. Quota pending admission is frozen before the business write; recovery preserves that decision after lease retirement. | Existing L3 lease lifecycle, real File/SQLite/PostgreSQL, mixed fixtures, process death between business/quota commits, competing renewal and unchanged polling. [Operation and snapshot rehearsal](../../reference/protocols/quota-monitor-observation-receipt-v0.md). Ordinary polls leave leases unchanged and spend no quota; separate authorities stay separate. The retained grouped-Monitor observation/reactivation caller now uses Todo update v4 and the shared Monitor planner, with unchanged-group display recovery. Canonical reactivation now atomically retires retained execution and reopens the observation cycle, sharing typed admission with polling; a fresh execution still needs explicit acquisition. Grouped reconciliation now acquires/revalidates/releases its own bounded execution, recovers interrupted cleanup, and plans the complete bucket set in TS; missing evidence and ambiguous/stale targets reject. This closes that retained caller across legacy/File/SQLite; native/imported mixed fixtures exercise the same effects on real PostgreSQL. Wider L2 admission, external-effect fences and D1–D3/default remain open. |
 | B / L5: Consumer and display closure | Reconcile #4316, audit Turn/quota/Dashboard/Chat source reads, and finish D1 freshness/recovery through the existing projection outbox. | CLI, Lark/Chat and packaged frontend read back their affected interactions; absent/stale display, empty canonical state, pending projection and data beyond UI limits. Delete post-promotion legacy fallbacks with each consumer. |
 | A–C / L6: Local durability qualification | Continue contributor-owned #4224/#4328 on the selected SQLite profile; reuse File/NoKV references and complete 7.2's ledger. | Capacity, real process/crash/restore/upgrade, retained receipts/scans, consumer lag, supported runtimes/OS and the separately authorized >=10-day synthetic soak. Missing measurements remain holds. |
 | A–C / L7: Capture continuity | Reconcile the merged #4315 archive/lease-membership repair; qualify its ladder row/mutant and sustained mixed-writer/event-source matrix rather than reimplementing the closed defect. | Real CLI/File capture, history retained, partial drain unqualified, crash/replay and a new lease after archive/rebootstrap. Keep the legacy migration window provable; T4 cannot be used to skip this row. |
@@ -3233,7 +3233,7 @@ PRs**, conditional on the caller audit finding no additional missing effects:
 | L7 capture plus L8 integrated migration | 1–2 | Mixed-writer continuity, fenced whole-Goal rehearsal, export/rollback and cohort evidence. |
 | L9 default and bounded retirement | 1 | New-Goal onboarding/settings/install choose the qualified profile; remove final obsolete callers. |
 
-The retained-Monitor cycle slice removes a concrete L4 hold, not an entire
+The retained-Monitor cycle and grouped executor closure remove concrete L4 holds, not an entire
 remaining package: the **5–8 PR planning range remains conditional**, rather than
 subtracting one for a lifecycle fix. Actual remaining executor/caller coverage,
 L5 consumers, contributor-owned D2, integrated migration and default onboarding

docs/architecture/rfcs/typescript-control-plane-migration-v0.md

@@ -783,8 +783,24 @@ all T2 commands or authorize whole-Goal promotion.
   must be acquired explicitly. `todo_monitor_cycle.ts` owns shared update/poll
   admission, removing their duplicate actor/lease branches and correcting their
   soft-claim disagreement. No new Python transition owner or RPC is introduced.
-  Other lifecycle callers, executor acquisition for grouped reconciliation,
-  legacy persistence/capture and whole-Goal qualification remain separate.
+  Grouped reconciliation now plans the complete bucket set in
+  `capabilities/issue_fix_monitor_reconciliation.ts`; Python retains ledger IO,
+  public writer calls and display delivery. The caller acquires its own bounded
+  execution for hard-lease observations/stops, rechecks the plan after acquisition,
+  and releases only that attempt. Retry after an observation commit can clean up
+  a surviving lease without repeating the business mutation. Reactivation remains
+  a non-execution transition through the existing TS owner.
+  Missing/malformed ledger evidence, duplicate active targets and older empty
+  observations now reject instead of silently dropping or completing a target.
+  Membership hashes preserve the original Python Unicode/ASCII encoding contract.
+  Explicit runtime-root routing reaches every affected writer and readback.
+  This is a complete issue-fix caller closure, not an atomic transaction over all
+  buckets: earlier committed buckets survive a later failure. Unchanged retries
+  may release their own interrupted execution and drain display. The remaining
+  Python adapter is a real caller, not a removable compatibility wrapper.
+  See the [operator contract](../../../loopx/capabilities/issue_fix/README.md#pr-lifecycle-monitor).
+  Other lifecycle callers, external-effect execution fences, legacy
+  persistence/capture and whole-Goal qualification remain separate.
 - Preserve unchanged polling/reschedule behavior, generation fences,
   material-change successor deduplication and accountable settlement.
   A monitor remains non-executable delivery context; its independent

docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md

@@ -594,8 +594,17 @@ delivery pending；这不代表全部 T2 命令或整 Goal promotion 已完成
   raw patch 权限或轮询引擎。完成后的新观察即使 hash 相同也推进新一代；历史重放
   不会重开当前任务。无变化的分组也能恢复显示，包括带优先级前缀的 native 文本。
   见[观察更新与再激活](../../reference/protocols/quota-monitor-observation-receipt-v0.md#observation-updates-and-reactivation)。
-  保留 execution lease／hard-lease 模式的再激活、其他 lifecycle caller、旧持久化／
-  capture 和整 Goal 资格仍是独立边界。
+  再激活已由既有 TS owner 原子退役旧 execution；分组对账的完整桶集合决策现由
+  `capabilities/issue_fix_monitor_reconciliation.ts` 负责，Python 保留 ledger IO、
+  公开 writer 调用和展示交付。hard-lease 观察／结束先领取自己的有限期 execution，
+  领取后重新核对计划，只释放本次执行。观察提交后进程退出，原样重试可清理残留
+  lease，不重复 Todo 业务写入；再激活本身仍不授予执行权。
+  缺失／损坏 ledger、重复活动 target、旧的空组观察现在明确拒绝；成员 hash 保留
+  Python 原有 Unicode 排序及 ASCII 转义合同。显式 runtime-root 贯穿读取和写回。
+  这是 issue-fix 调用链闭合，不是所有桶的一笔原子事务：后续桶失败不回滚之前已
+  提交的桶。无变化重试可以清理自己的中断 execution 并恢复展示。Python 适配器仍
+  有真实调用方，不能直接删除。其他 lifecycle caller、跨外部 effect 的围栏、旧持久化／
+  capture 和整 Goal 资格仍独立。见[操作合同](../../../loopx/capabilities/issue_fix/README.zh-CN.md#pr-lifecycle-monitor)。
 - 保持 unchanged poll/reschedule、generation fence、material-change successor
   去重和可归属 settlement。Monitor 不是 delivery 执行任务；独立 advancement Todo
   不能被 monitor 自身替代。

loopx/capabilities/issue_fix/README.md

@@ -1054,6 +1054,35 @@ private material remain explicit gates. Each material transition must yield a
 `runnable_successor`, concrete blocker, or structured no-follow-up; unchanged
 polls remain quiet and do not spend delivery quota.
 
+With `--execute-transition`, one Monitor represents each nonempty repository/state
+bucket. Membership changes advance its observation generation; an empty bucket
+ends it, and a newer nonempty observation reopens the same unarchived Todo. New
+Monitors use explicit `priority=P2`; their text is not a priority argument.
+
+In `hard_lease` mode the reconciler acquires a 60-second execution lease for
+observation/stop and releases that exact execution afterward. It never borrows
+another attempt merely because the Agent ID matches. An identical retry can
+recover its own active acquisition; after a committed observation it cleans up
+its remaining lease without repeating that business write. Expired or released
+attempts require fresh acquisition. Reactivation itself grants no execution.
+The existing `--runtime-root` override applies to reads, leases, writes and
+projection recovery. No new provider or capability is enabled.
+
+Missing ledger files, malformed bucket declarations, duplicate current targets,
+and older empty observations are errors, not evidence that all work has ended.
+Restore the ledger or resolve the duplicate before retrying; do not switch to
+legacy state. Buckets commit independently, so after a later failure read back
+`loopx todo list --goal-id GOAL` using the same registry/runtime root, then retry
+the original observation. `write_performed` describes Todo business writes;
+lease cleanup and current display delivery may still happen on an unchanged
+retry. Pending display is recoverable with `loopx todo project-markdown` and
+never rolls back a successful business commit.
+
+Omit `--execute-transition` to inspect without reconciling Todos. To roll back
+this implementation, retain canonical state, writer fences and receipts; restore
+compatible code instead of reviving old Markdown authority. This does not grant
+publication, merge, additional capabilities or access to private material.
+
 Pass `--issue-ref` when persisting PR lifecycle state. This explicit public-safe
 link lets the outcome read model join the PR to its issue without guessing from
 branch names, titles, or text.

loopx/capabilities/issue_fix/README.zh-CN.md

@@ -927,6 +927,27 @@ review、maintainer correction、mergeability、stale branch 和 terminal status
 transition 必须生成 `runnable_successor`、具体 blocker 或结构化 no-follow-up；
 unchanged poll 保持安静且不消耗 delivery quota。
 
+`--execute-transition` 为每个非空的「仓库／状态」分组维护一个 Monitor。成员变化
+推进观察 generation；空组结束；完成后的新非空观察重新开启同一个未归档 Todo。
+创建时通过显式 `priority=P2` 传入优先级，不再把正文当前缀参数使用。
+
+`hard_lease` 模式的观察／结束先领取 60 秒 execution lease，之后只释放这次执行。
+Agent ID 相同也不能借用另一轮的 lease。原样重试可以恢复自己的活动领取；观察
+提交后进程退出，重试清理残留 lease 而不重复业务写入。到期或已释放的旧执行需要
+重新领取；再激活本身不授予执行权。已有 `--runtime-root` 参数贯穿读取、租约、
+写入和显示恢复，不新增 provider 或 capability 启用方式。
+
+缺失 ledger、损坏的分组声明、重复活动 target、旧的空组观察都会报错，不能当作
+「工作已全部结束」。恢复 ledger 或解决重复项后重试，不回退旧存储。各桶独立提交，
+后面的桶失败不会回滚前面的桶；用同一 registry/runtime root 执行
+`loopx todo list --goal-id GOAL` 读回，再重试原观察。`write_performed` 只表示 Todo
+业务写入；无变化重试仍可能清理 lease 和恢复当前显示。显示 pending 可通过
+`loopx todo project-markdown` 重试，不回滚已提交业务。
+
+不传 `--execute-transition` 即只检查而不对账 Todo。回滚实现时保留 canonical
+state、writer fence 和 receipt，恢复兼容代码，不能复活旧 Markdown authority。
+该过程不授予发布、合并、新 capability 或私有材料访问权限。
+
 持久化 PR lifecycle 时应传入 `--issue-ref`。这个显式、public-safe 的关联让 outcome
 read model 可以把 PR 精确连接到 issue，而不用从分支名、标题或正文中猜测。
 

loopx/capabilities/issue_fix/cli.py

@@ -1315,6 +1315,7 @@ def handle_issue_fix_command(
                     raise ValueError("PR lifecycle transition is missing")
                 grouped_monitor_writeback = materialize_issue_fix_grouped_monitors(
                     registry_path=registry_path,
+                    runtime_root=Path(runtime_root_arg).expanduser() if runtime_root_arg else None,
                     goal_id=args.goal_id,
                     project=Path(args.project).expanduser(),
                     ledger_path=ledger_path,