fix(host): recover vision settlement and preserve scoped replanning

[huangruiteng]

Summary

Rebased on main at afff837a0. The five signed commits unique to #4208 remain; already-merged ancestry is not part of this PR.

• MCP complete_task accepts an authored vision decision. review_task_vision supplements a missing decision with the original completion identity and existing TypeScript refresh recovery, without repeating lifecycle completion or quota spend.
• A TypeScript MCP interaction lens removes duplicate raw CLI settlement instructions for admitted Todo delivery. Independent replan and blocked lanes keep their executable actions and authority facts.
• Claude Todo-less replan re-enters once to acquire a Turn, then receives a settlement plan bound to the exact Turn and replan obligation. The same visible-Goal profile set is shared by re-entry, plan construction and spend-source validation.
• Both reported P1s are fixed: unchanged reasons now pass the existing TypeScript vision validator before lifecycle effects, and the post-reentry Claude path now completes a real typed vision delta and settles exactly once.

Behavior boundaries

Todo acceptance, Turn settlement, vision checkpoint satisfaction and Goal termination remain distinct. vision_closed closes a stage and still requires successor planning. no_followup cannot hide independent runnable work or gates. Recovery cannot overwrite a conflicting committed vision.

Correctable authoring syntax or budget errors are rejected before completion. Baseline-dependent checks still execute against current state at writeback. Interrupted older-host transactions retain same-intent recovery. Python adapts host effects; it does not introduce a Claude-specific settlement engine or duplicate the TypeScript vision rules.

Validation

• Exact head: 0925026ac5aa592fbb1029017d3b3a36e5c5f325
• Exact base: afff837a05694bed2f0b113ba319c6773ed486fa
• Change-quality receipt: cqr_c304e76c659513243156, valid for fingerprint c304e76c659513243156db501467029f8655213250591375c11d7fae49eaf9a6

Check kind	Result	Evidence / limitation
TypeScript	passed	test:control-plane: 1108 passed, 1 repository-declared skip, 0 failed; typecheck:control-plane passed.
Python real path	passed	33 focused tests covering real CLI/MCP Claude two-step re-entry, vision recovery, quota settlement and obligation acceptance.
Static	passed	Ruff on every changed Python file, scoped mypy, DCO, diff hygiene and added-line public/private scan.
Change quality	passed	Strict exact-base/exact-head receipt verified; one bounded safe-fix pass recorded.
Canary	baseline failures	16/18 selected checks passed. The two failures reproduce byte-for-byte on unchanged origin/main: heartbeat prompt JSON is already 3825 characters against a 3600 budget, and the full-file public scanner flags vision_checkpoint.ts's own larkoffice rejection regex. No new sensitive content was found in added lines.
Live model	not run	No model-token qualification was rerun for this review fix. Earlier Claude/Doubao runs remain historical evidence only.

No PostgreSQL/store/promotion behavior changes are in scope. Hosted CI qualifies the pushed exact head.

Type of Change

• Bug fix
• Documentation update
• Test update

LoopX Area

• Control plane (goals, todos, quota, scheduler, registry, runtime)
• Host or runtime integration

Technical Direction

• Core control-plane hardening
• Target base branch: main
• Direction tracker or promotion unit: host vision/replan follow-up to merged fix(heartbeat): share automation-first Goal execution contract #4201; no promotion claim.

Shared-authority RFC fixture impact

N/A: no provider, canonical Todo storage, runtime routing or Markdown projection changes. The future-facing pass centralizes the visible-Goal settlement profile set and reuses the existing TypeScript validator and host transaction.

Boundary Checklist

• No private state, credentials, raw traces, private links or local machine paths are included.
• No duplicate maintainer-owned benchmark work.
• Scope remains host vision/replan and preflight-before-effect.
• All commits have DCO sign-off.

Local diagnostic artifacts are excluded.

[huangruiteng]

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

复审绑定 exact head：22dacaf3e23d4e0059ce7f5172a89fad53a0276b。

动机

这个 PR 要解决的问题成立：Todo acceptance、Turn settlement、vision checkpoint 和 Goal terminal state 不能混为一谈；当 host 已完成部分事务但 vision writeback 失败时，也需要在原 completion identity 上给出有界恢复，而不是重新完成 lifecycle 或重复扣 quota。它还把 replan 限制回 active agent lane，并继续让 TypeScript 拥有控制面决策、Python 只适配 host effect，方向是对的。

它也延续了 #4201 的 Turn identity 修复边界：没有外部注入 identity 的 Claude replan 会先获得绑定，再看到 refresh/spend。此前我在 Codex App heartbeat 首次执行时漏传 Turn id，是我没有正确遵循已经投影的 LOOPX_TURN=<current_time_iso>; reuse，不是这个 stacked PR 需要重新发明 identity；这里审的是新恢复路径是否在同一 identity 下安全闭环。

改动思路

整体方案是复用现有 typed vision owner：MCP complete_task 可以携带 authored vision，缺失决策时 review_task_vision 在原始 completion identity 上补齐 checkpoint；TS interaction lens 继续生成 settlement/recovery 决策，Python host adapter 执行效果。独立 replan/blocked lane 不被这次抽取吞掉，旧 v0 completion 形状也保留兼容。

关键安全不变量应是：所有可纠正的 authoring 输入都必须先完成 typed preflight，之后才能改变 Todo lifecycle。当前 head 对 agent_vision 做到了，但对 vision_unchanged_reason 没做到。

具体改动

已经确认有效的部分：

• 正常 completion、checkpoint recovery、response-loss replay 和 scoped replanning 的 focused suite 通过。
• recovery 不会重复 spend，冲突的已提交 vision 不能被覆盖。
• static check 通过；GitHub required checks 成功或按预期跳过。SonarCloud Code Analysis 失败是独立的非门禁信号，不是下面结论的来源。

关键代码讲解

goal_mode_mcp.complete_task 进入 typed projectMcpInteraction，host_todo_completion.ts 的 writebackArgs 保留 Todo/Agent/Turn identity 并投影恢复动作；随后 host_adapter_settlement.host_vision_request 负责在真正写状态前做 host preflight。

阻塞点位于 host_vision_request 的 vision is None 分支：它直接 yield 带 vision_unchanged_reason 的 request 并返回，只有 agent_vision 分支会经过现有 prepare_vision_refresh typed validator。于是 PR body 所声明的“over-budget vision 会在 Todo completion 前拒绝”并不覆盖 unchanged reason。

我用 public MCP complete_task 跑了独立反例：同一 open Todo、有效 Turn identity、vision_unchanged_reason 长度 241。结果先把 Todo 变成 done，再在 durable vision writeback 阶段失败；receipt 为 failed_stage=durable_writeback、recovery_tool=complete_task，独立 Todo readback 为 done。也就是说，可纠正输入错误已经产生 lifecycle 部分效果，后续 retry 无法恢复原来的 open 状态。

请做最小修复：让 unchanged reason 在任何 lifecycle effect 前复用现有 typed vision-authoring validation；不要在 Python 再硬编码一份 240。补 real MCP 240/241 边界回归：240 成功并可 durable readback；241 必须在 Todo 仍 open、未 spend、未写 vision 时拒绝。

对主干的风险

这是 P1：任何通过 complete_task 只提交 unchanged reason 的 host 都可能遇到“API 报失败但 Todo 已完成”的不一致。当前 105 项 focused tests 全绿仍能复现，说明现有覆盖主要证明 recovery 形状，没有证明所有 authoring 分支都满足 preflight-before-effect。

它会增加人工修复成本，并可能让重试误以为仍可完成原 transaction。由于 #4208 stacked on #4201，合并前还应在新 exact head 上重跑完整 base-to-head inventory，而不只补单一 helper test。

我的整体评价

结论是 REQUEST CHANGES。我完整审阅了 17 个文件、+845/-63 的 base-to-head diff，并验证了 typed owner、host effect 边界和真实 MCP 顺序。pytest -q tests/test_host_vision_recovery.py tests/test_loopx_turn_driver.py tests/test_loopx_turn_codex_cli.py 为 105 passed；Ruff 与 git diff --check 通过，但独立 real-path 241 字符反例稳定失败。

范围与架构总体仍然合适，不需要拆新框架。future-facing pass 的最高价值就是把两个 vision authoring 分支收敛到同一 typed preflight owner。修复后重新审阅 exact head，确认旧 completion 兼容、240/241 边界、response-loss recovery 和 scoped replan 一起成立。

English verdict: REQUEST_CHANGES — the recovery and scoped-replan architecture is sound, but over-budget unchanged reasons bypass typed preflight, complete the Todo, and fail only during durable writeback; validate them through the existing typed owner before any lifecycle effect.

[huangruiteng]

Rebased and fixed the reported P1; ready for a fresh exact-head review, not merged.

Head: 94c06965d67cbe50780dc634345d5bd6d5b6456e; base: dbacd1e55 on main.

The three unique commits are preserved (96939750e, d23cddb83, 691485995), followed by the focused fix (94c06965d). The inherited #4201 commits were dropped from the PR ancestry. The final rebase has an entirely equivalent four-commit range-diff.

P1 resolution

host_todo_completion.ts now invokes the existing normalizeVisionUnchangedReason owner from vision_checkpoint.ts during request decoding. This runs before producing any lifecycle/CLI effects, including the completion and checkpoint-only recovery paths. Budget, public-safety checks and normalization remain centralized in TS; no duplicate Python limit was introduced.

The real MCP regression failed before the fix: a 241-character reason bypassed preflight. It now rejects before any CLI command, with byte-identical Todo state and run index. A 240-character reason succeeds with durable checkpoint readback. Correcting the rejected input succeeds, and whitespace-equivalent replay does not spend twice. Shared normalization also fixes the pre-fix normalized-retry mismatch.

Scope and validation

• 165 Python regression tests passed, no skips, on ee4a76130: real CLI/MCP completion/recovery, host Turn driver, Goal prompt dispatch, authority rejection, and release-harness oracles.
• After three non-overlapping Lark ACK and Dashboard/SSH commits landed, rebased again without conflicts. On final head: the 2 real MCP boundary tests and all 98 focused TS tests passed; TS typecheck, changed-Python Ruff, diff hygiene and public/private scans passed.
• No real model calls were rerun in this update. Prior Claude/Doubao evidence is explicitly historical in the updated PR body, not presented as current-head qualification. No PostgreSQL/store/promotion changes; that integration surface is not affected.
• Hosted CI must run for the new head. No merge or installation was performed.

The product motivation remains valid after #4201: exposing authored vision and same-identity checkpoint recovery while distinguishing Todo completion from Goal closure. The bounded refactor reuses the existing typed owner; it neither weakens vision/replan obligations nor introduces a second settlement engine. Baseline-dependent writeback checks and authority failures remain enforced. The temporary local hook bypass was scoped to this authorized branch update; no persistent Git configuration was changed.

[huangruiteng]

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

复审绑定 exact head：94c06965d67cbe50780dc634345d5bd6d5b6456e。

动机

这个 PR 处理的边界真实且重要：MCP Todo acceptance、Turn settlement、vision checkpoint 与 Goal terminal state 不能互相代替。正常交付需要由 complete_task 一次拥有 lifecycle、writeback 与 quota accounting；遗漏的 vision 判断需要在原 completion identity 上补齐，而不能再次完成 Todo 或重复扣费；独立 replan 则必须继续服从当前 obligation 与 Turn 绑定。

上一轮的 241 字符问题已经在本 head 修复：vision_unchanged_reason 现在先经过现有 TypeScript validator，再产生任何 CLI/lifecycle effect。真实 MCP 的 240/241 边界、纠正后提交与空白归一化 replay 都成立。当前阻塞不是旧问题的重复，而是我沿着本 PR 新增的 Claude replan re-entry 做第二步 real-path 反证时发现的另一处 typed-profile 断点。

改动思路

主架构是合理的：GoalModeMCPControlPlane 暴露 vision 输入；Python adapter 只物化临时 JSON 并执行 effect；host_todo_completion.ts 继续掌握 deterministic identity、ordered settlement 与 recovery；projectMcpInteraction 只在已准入的普通 Todo delivery 上移除重复 CLI recipe，blocked/replan lane 保留动态动作。review_task_vision 复用同一 writebackArgs，不重新完成 lifecycle、不生成新 Turn、也不 spend。

Claude Todo-less replan 的意图同样正确：第一次 should_run 缺 Turn 时先返回带 --turn-instance-id 的 re-entry，绑定后才应暴露带 exact replan obligation 的 refresh/spend plan。不过这个“先绑定、再结算”的两半目前由两个不同的 profile 集判断：host_goal_turn_reentry_action 已把 CLAUDE_CODE_VISIBLE 纳入，build_accountable_work_item_settlement_plan 仍只接受 native profiles 与 generic CLI。因此第一步能出现，第二步却无法完成。

具体改动

本 PR 共 17 个文件、+909/-64：9 个 runtime/production surface，5 个测试或 fixture，1 份双语测试文档，以及 2 个 release qualification runner。范围集中在 host vision/replan，不是机械搬迁，也没有新增第二套 state owner。

关键代码讲解

• visionAuthoringContract 与 normalizeVisionUnchangedReason 共用已有字段/总预算和 public-safe 规则，避免在 Python 再复制 240 上限；这一点修复正确。
• writebackArgs 同时服务首次 delivery 与 checkpoint-only recovery，保留 Todo/Agent/Turn identity；recovery 不含 lifecycle 和 spend，response-loss replay 由现有 refresh recovery 判定。
• projectMcpInteraction 对 normal delivery 投影 mcp_channel，保留 admission/workspace/required-read facts；没有选中 Todo 的 autonomous replan 不会被错误吞掉。
• host_goal_turn_reentry_action 在 spend_sources.py 第 69–84 行新增 Claude replan 分支，但它的下游 build_accountable_work_item_settlement_plan 在 unchanged accountable_settlement.py 第 41–58 行仍会对 CLAUDE_CODE_VISIBLE 返回 None。

当前有一个 P1 合并阻塞：

1. Claude re-entry 之后仍没有 accountable settlement binding。 我用仓库新增的真实 setup_replan fixture 跑完整两步：首次 quota should-run --runtime-profile claude_code 正确只给出带 Turn placeholder 的 re-entry；填入真实 Turn 后再次 should_run，interaction_contract.cli_channel 仍没有 settlement_plan，唯一 refresh-state 动作同时丢失 --turn-instance-id 与 --replan-obligation-id。把该动作的所有 progress placeholders 换成新的 typed 值并执行，CLI 退出 1，返回“open autonomous replan obligation requires a typed semantic delta”以及同一条泛化动作。也就是说，本 PR 声称的“Claude re-entry obtains a Turn identity before exposing bound writeback/spend”在真实第二步不成立。

最低修复应复用现有 owner：让 CLAUDE_CODE_VISIBLE 在拿到 Turn 后进入 build_turn_scoped_cli_settlement_plan，并确保 post-reentry action 绑定 exact obligation/Turn；对于 vision_successor_required，动作还应给出能够真正满足该 obligation 的 vision path 或 successor 路径，而不是永远失败的泛化 progress 模板。不要新建 Claude 专属 settlement engine。

对主干的风险

这个缺陷会把 Claude Goal 卡在最需要 replan 的路径：首屏 contract 看起来已经修复 Turn id，agent 也按提示重入，但下一屏又退回 unbound action。它不会绕过权限或直接损坏状态——writeback 会 fail closed——但会造成重复 should_run、人工拼 identity/obligation，以及“按 next_cli_actions[0] 执行仍无法推进”的宿主摩擦，正是此 PR 试图消除的问题。

现有测试漏掉它的原因也很具体：test_replan_fixture_has_real_settlement_but_unfinished_business_acceptance 只断言第一次动作字符串含 --turn-instance-id 且不含 spend，没有执行该动作、没有检查第二次 contract 的 settlement_plan，也没有执行 fully substituted follow-on action。请把这个 fixture 扩成两步 public CLI 回归，并断言 durable semantic delta 与 settlement receipts；只测字符串存在不足以证明 re-entry 可用。

当前 exact head 上，我跑了 153 个 focused Python tests 和 14 个 changed TS tests，全部通过；Ruff 与 diff hygiene 通过。广域 TS 运行有 1102 项通过，补正确 Python runtime 后对应的 Python/TS identity 用例也通过；本机唯一剩余启动失败是未安装 pg 的未触及 PostgreSQL integration。GitHub 当前 DCO、dependency、Python shards、merge-gate、build、Node compatibility 与 stage2c 均通过；SonarCloud Code Analysis 是非门禁 failure。上述绿色证据不覆盖两步 Claude re-entry 反例。

我的整体评价

结论是 REQUEST CHANGES。上一轮 241 字符 preflight 问题已经按正确 owner 修复，MCP vision/recovery、Todo/Goal 分离、v0 compatibility 与 typed authority 方向都值得保留；整体 909 行也与新增 real-path qualification 基本成比例。剩余 blocker 是一个局部但真实的 profile parity 缺口：发出 re-entry 的 profile 集与构造 settlement plan 的 profile 集不一致。

future-facing pass 不需要扩大范围：共享“哪些 visible hosts 支持 turn-scoped settlement”的 typed predicate，或至少为两个 owner 加 parity test；再补两步可执行回归即可。修复后请用新 exact head 重跑 240/241、response-loss recovery、普通 MCP delivery、Claude replan 两步绑定和 hosted checks。

English verdict: REQUEST_CHANGES — exact head 94c06965d67cbe50780dc634345d5bd6d5b6456e fixes the prior 240/241 preflight defect, but Claude re-entry still cannot build a settlement plan: the next action drops both Turn and replan-obligation binding and fails when executed; align the supported-profile owners and add a real two-step regression.

[huangruiteng]

Exact-head self-review completed for 0925026ac5aa592fbb1029017d3b3a36e5c5f325 on base afff837a05694bed2f0b113ba319c6773ed486fa.

Review conclusion

No remaining diff-local blocker found. Both prior P1s are resolved:

1. vision_unchanged_reason is normalized and budget/public-safety validated by the existing TypeScript vision owner before any lifecycle effect.
2. Claude visible-Goal re-entry and settlement now share one supported-profile set. A real two-step CLI test proves that re-entry binds an exact Turn, the next contract binds the exact replan obligation, the typed vision delta is accepted, spend commits once, and replay remains exactly-once.

The architecture remains appropriately bounded: TypeScript owns vision and settlement semantics; Python adapts host effects. The future-facing pass reused the existing validator/transaction and centralized profile parity rather than introducing a Claude-specific settlement engine.

Exact-head validation

• npm run test:control-plane with the repository's supported Python runtime: 1108 passed, 1 repository-declared skip, 0 failed (1109 total).
• npm run typecheck:control-plane: passed.
• Focused real CLI/MCP Python suite: 33 passed in 377.03s.
• Ruff on all changed Python: passed.
• Scoped mypy for the accountable-settlement facade: passed.
• DCO, diff hygiene, untracked-file inventory and added-line public/private scan: passed.
• Change-quality receipt cqr_c304e76c659513243156: valid for fingerprint c304e76c659513243156db501467029f8655213250591375c11d7fae49eaf9a6; one bounded safe-fix pass, zero unresolved blockers.

The first wide TypeScript invocation exposed that the macOS system Python 3.9 cannot parse the repository's dataclass(slots=True) code. Re-running with the supported Python 3.13 runtime passed the entire suite; this is a local runtime-selection issue, not a product failure.

Canary and holds

loopx canary premerge --from-git-diff --goal-id loopx-meta ran all 18 selected checks: 16 passed and 2 failed. Both failures reproduce unchanged on origin/main:

• the existing heartbeat prompt JSON is 3825 characters against its 3600-character budget;
• the full-file public scanner flags vision_checkpoint.ts's own larkoffice rejection regex as private_doc_url.

The PR adds neither the prompt growth nor private content; the added-line boundary scan is clean. There are no canary manual holds. Live-model qualification was not rerun, and PostgreSQL is not an affected surface. Hosted CI remains the final exact-head gate before the authorized admin-bypass self-merge.

[huangruiteng]

Hosted exact-head CI is complete.

• Passed: DCO, dependency review, both builds, Node minimum/forward compatibility, Windows, both Python shards, all three Stage 2C lanes and the Stage 2C correctness gate.
• The sole primary failure is checks / Measure dashboard browser interactions: reload did not reconnect the active Turn within 10 seconds. pytest and merge-gate fail only because they aggregate that upstream job.
• This is a current-main baseline failure, not a fix(host): recover vision settlement and preserve scoped replanning #4208 regression: the same dashboard step fails on exact base afff837a0 in main run 34602207840. fix(host): recover vision settlement and preserve scoped replanning #4208 changes no dashboard file or dashboard interaction contract.

Together with the exact-head local TypeScript suite, focused real CLI/MCP suite and valid strict change-quality receipt, the changed host vision/replan surfaces are qualified. Per the owner's self-merge authorization, I am using admin bypass for this independently evidenced main-only dashboard failure; I am not folding that unrelated repair into #4208.

[huangruiteng]

Post-merge audit finding for exact merged head

动机

合并 head 0925026ac5aa592fbb1029017d3b3a36e5c5f325（merge commit 091379eb32cae711ae4dd444378506452e5e93ee）正确修复了我之前指出的两个问题：240/241 unchanged-reason preflight 不再先完成 Todo，Claude 两步 replan 也补上了与 Turn/obligation 绑定的 settlement plan。复审完整 cross-host 路径后，我发现同一套 MCP lens 在 native Kunlun outer-controller 模式下产生了新的 P1 authority contradiction。

改动思路

这次重构的方向是让每个 admitted Turn 只有一个 settlement executor：MCP-owned host 隐藏底层 CLI sequence，统一调用 complete_task；replan/blocked 路径保留真实 CLI binding/actions。这个方向成立，但 executor ownership 不能只由 normal_delivery_allowed + selected_todo 推断，因为这两个字段只表达准入与工作对象，并不表达 MCP 是否拥有 durable writeback。

具体改动

在 projectMcpInteraction() 中，只要 normal delivery 有 selected Todo，就会删除 settlement_plan 和 next_cli_actions，并返回 executor=mcp_complete_task / delivery_executor=complete_task。共享 GoalModeMCPControlPlane.should_run() 同时被 Claude 与 native Kunlun 使用；而 native qualification 在 LOOPX_KUNLUNCODE_OUTER_CONTROLLER=1 时又明确 guard complete_task/review_task_vision，因为 durable writeback 只能由 outer controller 执行。

关键代码讲解

我用真实 native qualification fixture、真实 GoalModeMCPControlPlane.should_run() 和真实 outer-controller guard 做了成对反例。返回结果是：normal_delivery_allowed=true、next_cli_actions=[]、executor=mcp_complete_task、mcp_channel.delivery_executor=complete_task；随后调用该工具得到 ok=false，错误明确说明 complete_task is owned by the LoopX outer controller。也就是说，live contract 删除了唯一可执行的 outer-controller settlement plan，却把一个被同一 runtime 明确禁止的 MCP 工具声明为唯一 executor。

最小修复不是再加一个 effect path，而是在 host boundary 增加 typed delivery-owner/mode 信号，或只对真正 MCP-owned 的 host 应用该 lens：native outer-controller 模式必须保留绑定当前 Turn 的 settlement plan/actions，且不得宣告 complete_task。请用一个最小后续修复 PR 补 real should_run + guarded executor invocation 双向测试：同一个 selected Todo 在 MCP-owned 模式只有 MCP 路径成功，在 native outer-controller 模式只有 outer-controller 路径存在并成功。

验证方面，当前 head 的 83 个 Python 测试（357.65s）和 31 个 Node 测试通过，Ruff 与 git diff --check 通过，说明前两处 comment 修复本身有效；但这些测试没有覆盖上述 shared native caller。远端 exact head 复审时还有一个 Python Tests/checks 失败和一个运行中检查，也需要 readback/retry 后恢复。

对主干的风险

这是 P1：任何被正常准入的 native outer-controller Todo 都可能拿到一个不可执行的 must-attempt contract，导致 Turn 卡住、额度/写回不一致，或者诱导调用方绕过既有 authority guard。该问题位于 heartbeat/Goal 热路径，不能因为 Claude 路径与局部单测通过而忽略。

我的整体评价

前两轮指出的细微语义差异已经认真修好，重构方向也比手写多套 settlement 更合理；但已合并 exact head 仍把“工作准入”误当成“传输层拥有完成权限”，导致公开 contract 与实际 guard 相互矛盾。需要尽快用后续 PR 把 ownership 做成 typed host decision，并在真实两种 host mode 上证明 declared executor 可执行且唯一。

English verdict: POST_MERGE_AUDIT finding for exact merged head 0925026. The prior two fixes validate, but native Kunlun outer-controller delivery is projected as MCP-only while that same runtime blocks complete_task; ship a focused repair that preserves typed host ownership and adds a real paired executor counterfactual.