Skip to content

fix(release): handle settle-turn vision receipts and stabilize creation queue test - #9178

Merged
loopx-agent merged 1 commit into
mainfrom
codex/fix-vision-closeout-and-creation-race-20261121
Nov 21, 2026
Merged

loopx-agent merged 1 commit into
mainfrom
codex/fix-vision-closeout-and-creation-race-20261121

Conversation

@loopx-agent

@loopx-agent loopx-agent commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Fix dispatch_vision_closeout in loopx/control_plane/testing/replan_vision_closeout_behavior.py so refresh-state ... --settle-turn (which appends both a durable writeback row and a trailing classification == "quota_slot_spent" row into runs/index.jsonl) selects the non-spend writeback row and immediately executes _verify_vision_settlement instead of misreading the trailing quota_slot_spent row as vision_closeout_durable_writeback_incomplete; also reject duplicate spend-slot after --settle-turn settlement (vision_closeout_already_settled).
  • Clarify VISION_HOST_INSTRUCTION so --agent-vision-json sets top-level stride_decision from stride_control.minimal_example.
  • Harden consumption in tests/control_plane/test_creation_allowance_hold.py (_ObservedCalls) using entry/completion start-sequence monotonicity so a trailing pre-snapshot in-flight consume_creation_request never unblocks after(previous) prematurely, plus add focused regression tests in test_replan_vision_closeout_receipt.py and test_creation_allowance_hold.py.
  • Reconcile #9014, #9170, and #9178 in docs/product/releases/v2.4.0.md.

Validation (632dc3895b48b2e53310fb82e6bfa1dba824514d)

  • pytest -q -n 4 (test_replan_vision_closeout_receipt.py, test_replan_semantic_action_behavior.py, test_creation_allowance_hold.py, test_actual_default_model_behavior_portfolio.py): 128 passed.
  • Live 2-repeat DoubaoReplanSemanticActionBehaviorActor.qualify(..., required_vision=True) verification: r1 (22 calls, 0 shell errors, settled=True) and r2 (34 calls, 0 shell errors, settled=True) — both passed.
  • ruff check, mypy (default 17 files + --follow-imports=silent on replan_vision_closeout_behavior.py): 0 errors.
  • release-readiness-doc-smoke.py --release-notes docs/product/releases/v2.4.0.md (12 surfaces), check_rfc_bilingual.py --base origin/main --head HEAD, loopx check --scan-path ... (4 files, 0 errors): passed.
  • loopx change-quality record/verify + loopx canary premerge --from-git-diff --git-diff-base origin/main: 19/19 checks passed, manual_hold_count=0, cqr_fafc651e7f81cdb810b6 valid.

@loopx-agent
loopx-agent force-pushed the codex/fix-vision-closeout-and-creation-race-20261121 branch from d7970ab to 632dc38 Compare November 21, 2026 07:06

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Reviewer: model_agent · Gemini · Google · self_reported

Reviewed exact head: 9178@632dc3895b48b2e53310fb82e6bfa1dba824514d

动机 / Motivation

在启用 required_vision 行为资格验证时执行 refresh-state --settle-turn 的宿主评估路径、在受管创建队列测试中等待新一次消费完成的测试夹具,以及核对 v2.4.0 发布说明的维护者均会受此问题影响。

改动前,当真实模型或脚本宿主按写回阶段下发的 settlement_command 执行 refresh-state ... --settle-turn 时,CLI 会向 runs/index.jsonl 先写入写回记录再追加一条 classification == "quota_slot_spent" 记账记录,而 dispatch_vision_closeout 机械读取最后一行 rows[-1] 并硬编码返回 settled=False,导致有效结案被误判为 vision_closeout_durable_writeback_incomplete 并错误等待二次扣额;同时 VISION_HOST_INSTRUCTION 未点明 stride_decision 必须置于顶层,模型易误写入 vision_patch.stride_decision;此外 test_creation_allowance_hold.py 的 consumption 夹具仅比较列表长度,len(calls) 之前已进入的在途消费结束后会提前唤醒 after(previous);v2.4.0.md 亦缺少 #9014、#9170 与 #9178 的归属。改动后,dispatch_vision_closeout 按非 quota_slot_spent 过滤写回行并在检测到已扣额行时立即执行 _verify_vision_settlement 且拒绝重复 spend-slot,VISION_HOST_INSTRUCTION 明确要求顶层 stride_decision,consumption 夹具通过启动序号与完成启动序号单调门控消除在途唤醒竞态,发布说明完成双语同步。

在相同控制面契约下,使用 --settle-turn 的单步视觉结案直接完成读回校验并收敛为 settled=True, spend_count=1,对后续冗余 spend-slot 抛出 vision_closeout_already_settled,不带 --settle-turn 的两步路径保持原行为不变;创建队列测试中先于快照启动的在途调用不再误放行 after(count);v2.4.0.md 与已合并 PR 及本 PR 内容一致。

本 PR 不修改控制面生产状态机(vision_checkpoint.ts、refresh_settlement.py 或 steward_managed_mode.py),不新增持久化字段或配置开关,也不在无外部 API 密钥的本地审查 Pass 中运行真实收费模型调用。

改动思路 / Approach

测试驱动层的结案回执读取由 dispatch_vision_closeout 持有、测试并发等待门控由 test_creation_allowance_hold.py 的 consumption 夹具持有、版本说明归属由 docs/product/releases/v2.4.0.md 持有;三处缺陷均属于调用方测试桩与文档投影边界本身的问题,提取共享 _verify_vision_settlement 辅助函数并保持生产控制面与现有 quota_slot_spent 分类约定不变,是最小且可逆的所有权划分。

仅修复 replan_vision_closeout_behavior.py 对 --settle-turn 双行账本的读取与重复 spend-slot 拦截、补充 VISION_HOST_INSTRUCTION 顶层字段提示、加固 test_creation_allowance_hold.py 夹具的在途序号门控,并对齐 docs/product/releases/v2.4.0.md 中 #9014/#9170/#9178 的双语条目,不改动生产控制面代码,也不扩张 replan_semantic_action_behavior.py 的非 required_vision 分支。

从入口到状态的边界如下:

  1. 单步 --settle-turn 与两步 spend-slot 统一:loopx refresh-state --settle-turn 会在 runs/index.jsonl 中先落盘一条非 quota_slot_spent 的写回记录,再由 settle_requested_refresh 追加 classification == "quota_slot_spent" 记录;而未带 --settle-turn 时只写回前者。dispatch_vision_closeout 以非 quota_slot_spent 行作为权威写回源,并将共同的读回校验(回放 quota should-run、校验 spends == 1、检查原 obligation 未重武装、更新 state.vision_closeout)收敛到 _verify_vision_settlement。
  2. 宿主提示对齐写回契约:vision_checkpoint.ts(prepareVisionRefresh)要求 stride_decision 位于 JSON 顶层,且显式拒绝 vision_patch.stride_decision。将 VISION_HOST_INSTRUCTION 改为显式指示设置顶层 stride_decision,直接匹配现有验证契约而不放宽校验规则。
  3. 测试队列单调序号门控:consumption 夹具在进入 consume_creation_request 时在条件锁内分配严格递增的 entry_seq,并在 finally 中更新 completed_start_seq;_ObservedCalls.__len__ 在读取 calls 长度前记录当前 started 为 baseline_started,after(previous) 同时要求 list.__len__(calls) > previous 与 completed_start_seq > baseline,从而拦截在 count = len(...) 之前已启动、之后才完成的在途调用。
  4. 发布说明双语同步:在 docs/product/releases/v2.4.0.md 的英文与 ## 中文摘要 对应分组补齐已合入主干的 #9014、#9170 与本 PR #9178 归属。
变更面 Baseline (64353773dc) Head (632dc3895b) 契约影响
refresh-state --settle-turn 回执读取 读 rows[-1](踩中 quota_slot_spent 报错) 过滤 classification != "quota_slot_spent" 取最后一条,检测已扣额即调用 _verify_vision_settlement 单步结案直接收敛为 settled=True
结案后重复 spend-slot 未拦截(若被调用会再次执行) 若 state.vision_closeout.get("settled") 抛出 vision_closeout_already_settled 防止重复扣额或二次读回
refresh-state(无 --settle-turn) 返回 completed=False,等待 spend-slot 保持完全一致,仍等待显式 spend-slot 向后等价
VISION_HOST_INSTRUCTION use stride_control.minimal_example for its shape set top-level stride_decision from stride_control.minimal_example 与 prepareVisionRefresh 顶层校验一致
consumption 夹具唤醒 仅检查 len(calls) > previous 叠加 completed_start_seq > baseline_started 拦截旧在途消费造成的过早唤醒
docs/product/releases/v2.4.0.md 缺少 #9014、#9170、#9178 双语 Highlights / Quality & Testing / Benchmarks & Integrations 对齐 发布归属完整一致

具体改动 / Changes

关键代码讲解

  1. dispatch_vision_closeout(loopx/control_plane/testing/replan_vision_closeout_behavior.py:176-235)

    • 职责:在 required_vision=True 的隔离 Shell 宿主中拦截并校验 refresh-state 与 quota spend-slot 命令的绑定、证据引用与真实 runs/index.jsonl 回执。
    • 改动细节:执行 refresh-state 后,不再假设 rows[-1] 即为写回行,而是构造 writebacks = [row for row in rows if row.get("classification") != "quota_slot_spent"],为空则抛出 VisionHostAdmissionRejected("vision_closeout_durable_writeback_missing", ...),否则取 writebacks[-1] 校验 semantic_delta.accepted、obligation_id、vision_checkpoint.satisfied 与 settlement_identity。随后若 rows 中已包含 classification == "quota_slot_spent",直接调用 _verify_vision_settlement 并返回 (output, "semantic_replan_writeback", True);否则保持 settled=False 返回 False。在 spend-slot 分支新增 if state.vision_closeout.get("settled"): raise ValueError("vision_closeout_already_settled"),阻止对同一已结案 Turn 再次派发扣额命令。
    • 调用方:replan_semantic_action_behavior.py:1921(VisionShellHost invoke 回调)以及新增测试 tests/control_plane/test_replan_vision_closeout_receipt.py:114-211。
  2. _verify_vision_settlement(loopx/control_plane/testing/replan_vision_closeout_behavior.py:136-173)

    • 职责:独立重放原 Turn 的 quota should-run 与新 -readback Turn 的 quota should-run,核对 effective_action == "heartbeat_settled_skip"、len(spends) == 1 且原 obligation 及 required_agent_vision_missing / vision_checkpoint_missing 未重武装,随后更新 state.vision_closeout(settled=True, spend_count=1, original_obligation_closed=True)与 state.semantic_reentry_observation。
    • 改动细节:从原 spend-slot 分支提取为共享 helper,使 --settle-turn 与两步 spend-slot 两条路径共用同一套结案不变量,消除重复代码。
  3. VISION_HOST_INSTRUCTION(loopx/control_plane/testing/replan_vision_closeout_behavior.py:33-57)

    • 职责:为 required_vision=True 行为资格测试提供系统级宿主指令。
    • 改动细节:第 48-49 行将 "use stride_control.minimal_example for its shape" 澄清为 "set top-level stride_decision from stride_control.minimal_example",与 loopx/control_plane/goals/vision_checkpoint.ts:679-689(prepareVisionRefresh 拒绝嵌套在 vision_patch.stride_decision)及 stride_policy.ts:428(attachment: "agent_vision.stride_decision")保持一致。
  4. _ObservedCalls 与 consumption(tests/control_plane/test_creation_allowance_hold.py:22-69)

    • 职责:在 ManagedSessionTurn.consume_creation_request 外层包装计数与等待原语 after(previous),确保测试触发一次新的队列唤醒后真正等到后续消费结束。
    • 改动细节:每次进入 observe 时在 condition 下递增 started 获取 entry_seq,在 finally 块追加副本并更新 completed_start_seq = max(completed_start_seq, entry_seq);_ObservedCalls.__len__ 在返回长度前采样 self._on_len() 存入 self.baseline_started;after(previous) 使用 list.__len__(calls) > previous and completed_start_seq > baseline 作为条件谓词(刻意绕开 _ObservedCalls.__len__ 以免等待期间覆盖 baseline_started)。配合新增测试 test_in_flight_consumption_started_before_count_does_not_unblock_after(第 371-425 行),显式验证先于 len() 进入的阻塞调用结束后不会提前放行 waiter。
  5. 测试与发布说明(tests/control_plane/test_replan_vision_closeout_receipt.py:67-211、docs/product/releases/v2.4.0.md:24,26,88,92,413,415,458,462)

    • 测试新增 --settle-turn 自动结案与禁止重复 spend-slot 用例,以及无扣额行等待显式 spend-slot 用例。
    • 发布说明核对:#9014(Use model coverage in the PR review queue,合入于 64353773dc)、#9170(fix(native-chat): recover steward active-cascade resume_failed and bound thinking-only error loops,合入于 d083494ee2)与 #9178 的标题、范围及中英文分组链接均与实际提交相符。

Specification basis: 本 PR 属于测试宿主回执适配、测试夹具竞态修复与发布说明同步的组合修正,无单一新建功能 RFC(no_spec);同时已对照既有稳定契约文档 docs/product/release-readiness.md(b8819fe633acdc9e99c7564634e9225d9aacd199)、docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md(e67b5d911a8bf44b6eab49547f2b25e31ecb4127)及 vision_checkpoint.ts 源码确认一致。

对主干的风险 / Risks

无阻塞性缺陷(No blocking finding)。 本次改动未触及生产控制面状态机、权威存储或并发调度代码,风险总体可控;以下为非阻塞后续改进与验证边界说明:

  1. 非阻塞改进建议(P3)— _ObservedCalls.__len__ 锁粒度与副作用:tests/control_plane/test_creation_allowance_hold.py:28-30 中 _ObservedCalls.__len__ 先通过 self._on_len() 短暂加锁读取 started,释放锁后再调用 super().__len__(),同时将 len(calls) 与状态变更(更新 baseline_started)耦合。在当前 session_queue.py 单线程/串行消费模型及本文件现有测试下不会触发竞态;但若未来有测试在多生产线程并发期间调用 len(calls) 或多次检查 len(calls),建议在 with condition: 内原子读取 (started, list.__len__(calls)) 或提供显式 snapshot() 方法,使多并发调用下同样严格线性化。
  2. 非阻塞改进建议(P3)— VISION_HOST_INSTRUCTION 与兄弟测试桩一致性:VISION_HOST_INSTRUCTION 第 55-56 行仍提示模型在写回后“execute the returned settlement_owed.command once”,当模型改走 --settle-turn 路径时虽因 dispatch_vision_closeout 立即完成结案并直接结束循环而无阻塞,后续可补充说明与 settlement_command 协同;另注意到非 required_vision 路径的 replan_semantic_action_behavior.py:1397(_bound_semantic_writeback)仍取 _fixture_runs(state)[-1](当前 required_vision=False 不会下发 --settle-turn,未受影响,后续若扩展可一并对齐)。
  3. 非阻塞文字建议(P3)— 发布说明术语微调:docs/product/releases/v2.4.0.md 中文摘要将 #9170 的 active-cascade 译为“主动级联”,实际语义更接近“活跃级联”,仅属措辞润色。

本地验证与对照实测(wait_for_ci: false,未依赖远端 CI)

  • PASS — 5 文件全量行为与回归测试:在隔离工作树通过 uv run --extra test python -m pytest -q -n 4 tests/control_plane/test_replan_vision_closeout_receipt.py tests/control_plane/test_required_vision_closeout_behavior.py tests/control_plane/test_replan_semantic_action_behavior.py tests/control_plane/test_creation_allowance_hold.py tests/control_plane/test_actual_default_model_behavior_portfolio.py 实测 163 passed in 150.85s;另单独运行 uv run --extra test python -m pytest -q -n 4 tests/control_plane/test_creation_allowance_hold.py 21 passed,且对 test_in_flight_consumption_started_before_count_does_not_unblock_after 连续 5 次重复运行均通过(5/5)。(注:审查期间最初直接调用 .venv/bin/python 时因宿主 PATH 中的 python3 为 3.12 而非 .venv 的 3.14,触发 cart_host 的 prepare_check 拒绝;改用仓库规范的 uv run --extra test python 后全部通过,属环境调用方式差异而非代码缺陷。)
  • PASS — Baseline vs Head 对照与 TS 契约反例验证:
    • 使用 git show 64353773dc8b1ca82ff531cc7653dec6c3d41c0b:loopx/control_plane/testing/replan_vision_closeout_behavior.py 与 exact head 632dc3895b48b2e53310fb82e6bfa1dba824514d 运行同夹具对照:settle_turn=True 在 Baseline 复现 ValueError: vision_closeout_durable_writeback_incomplete,在 Head 通过并收敛为 settled=True, spend_count=1;settle_turn=False 两端输出完全一致。
    • 直接调用 vision_checkpoint.ts buildVisionCheckpoint 确认嵌套 vision_patch.stride_decision 被拒绝(agent_vision.vision_patch.stride_decision must be supplied as agent_vision.stride_decision),顶层 stride_decision 被接受(vision_refresh_prepared_v0),且 node --experimental-strip-types --test tests/control_plane_ts/vision_checkpoint.test.ts tests/control_plane_ts/stride_policy.test.ts 65 passed, 0 failed。
  • PASS — 静态检查、文档与公开边界:ruff check(0 errors)、mypy(默认 17 文件 + --follow-imports=silent loopx/control_plane/testing/replan_vision_closeout_behavior.py 均为 0 issues)、scripts/check_rfc_bilingual.py --base origin/main --head HEAD(passed)、examples/release/release-readiness-doc-smoke.py --release-notes docs/product/releases/v2.4.0.md(12 surfaces,ok)、loopx check --scan-path ...(4 files,0 errors/warnings)。
  • 环境限制与未运行项披露:
    • loopx canary premerge --from-git-diff --git-diff-base origin/main 执行 18/19 passed(direct_checks 4/4、python_compile 1/1、risk_profile_smokes 8/8、public_boundary 1/1、catalog_canaries 9/10);唯一失败项 examples/semantic-vocabulary-drift-smoke.py 系因干净审查 worktree 未安装 node_modules(ValueError: repository npm dev dependencies are not installed (the typescript package is missing)),且本 PR 仅改动 4 个非词表/非注册表文件,未新增或修改任何 Enum、Literal、TS 类型契约或 registry I/O 位点。
    • UNVERIFIED(本审查 Pass):真实收费 DoubaoReplanSemanticActionBehaviorActor 在线模型 2 次重复运行未在本次审查中重新消费额度复测(需外部 API 凭据;核心回执与提示路径已由确定性单元测试与脚本行为测试完整覆盖)。

我的整体评价 / Verdict

  • 长程与用户体验评估(outcome_impact):long_horizon 评估为 improved——修复 --settle-turn 视觉结案后单步 Turn 不会卡在虚假的 writeback incomplete 或重放扣额,消除长链测试中的伪失败与在途唤醒误判;user_experience 评估为 not_applicable(无 CLI 参数、HTTP API 或终端交互变更)。已检查 docs/product/releases/v2.4.0.md、loopx/control_plane/testing/replan_vision_closeout_behavior.py、tests/control_plane/test_replan_vision_closeout_receipt.py 与 tests/control_plane/test_creation_allowance_hold.py:本 PR 仅涉及 CLI/测试宿主夹具、单元测试与纯 Markdown 发布说明,不改动任何 Web/Desktop 渲染界面,视觉审查为 not_applicable。 未验证视觉范围:无(未改动渲染 UI)。
  • 行为等价、代码体积与架构相称性:observable_semantics 为 intentional_change_validated(保留非 --settle-turn 等价行为,按实测纠正 --settle-turn 回执读取与顶层 stride_decision 提示);code_volume 为 necessary 且兼容策略为 retain(dispatch_vision_closeout 与真实 CLI 同步部署,提取 _verify_vision_settlement 避免重复,暂不改动 required_vision=False 或重构 _ObservedCalls 接口);change_proportionality 为 proportionate,architecture_assessment 决定为 retain;default_off_isolation 与 authority_semantics 均为 not_applicable(未新增开关或权限模型)。
  • 语义对齐(semantic_alignment):not_applicable——本 PR 未新增或修改任何注册表词表、枚举、协议字段或 schema 版本,仅复用既有 "quota_slot_spent" 账本分类,无需更新词表注册表或 RFC。
  • Exact-head 新鲜度:提交时已复核远端 PR #9178 仍为 OPEN、非 Draft、无新增 commit 或变更,exact head 仍为 632dc3895b48b2e53310fb82e6bfa1dba824514d。

English verdict: APPROVE — Exact head 632dc38; fixes dispatch_vision_closeout for --settle-turn receipts with duplicate spend-slot guard, aligns VISION_HOST_INSTRUCTION top-level stride_decision wording with vision_checkpoint.ts, hardens creation_allowance test wakeup ordering, and accurately reconciles v2.4.0.md attribution; focused suites, lint, type checks, doc smoke, and public-boundary scan pass (with canary semantic-vocabulary-drift-smoke failing solely due to absent node_modules in the clean review worktree).

@loopx-agent
loopx-agent merged commit f8d4971 into main Nov 21, 2026
14 of 19 checks passed
@loopx-agent
loopx-agent deleted the codex/fix-vision-closeout-and-creation-race-20261121 branch November 21, 2026 07:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant