Repository navigation
fix(release): handle settle-turn vision receipts and stabilize creation queue test - #9178
Conversation
…on queue test Signed-off-by: LoopX Agent <[email protected]>
d7970ab to
632dc38
Compare
loopx-agent
left a comment
There was a problem hiding this comment.
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 分支。
从入口到状态的边界如下:
- 单步
--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。 - 宿主提示对齐写回契约:
vision_checkpoint.ts(prepareVisionRefresh)要求stride_decision位于 JSON 顶层,且显式拒绝vision_patch.stride_decision。将VISION_HOST_INSTRUCTION改为显式指示设置顶层stride_decision,直接匹配现有验证契约而不放宽校验规则。 - 测试队列单调序号门控:
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(...)之前已启动、之后才完成的在途调用。 - 发布说明双语同步:在
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
关键代码讲解
-
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(VisionShellHostinvoke回调)以及新增测试tests/control_plane/test_replan_vision_closeout_receipt.py:114-211。
- 职责:在
-
_verify_vision_settlement(loopx/control_plane/testing/replan_vision_closeout_behavior.py:136-173)- 职责:独立重放原 Turn 的
quota should-run与新-readbackTurn 的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两条路径共用同一套结案不变量,消除重复代码。
- 职责:独立重放原 Turn 的
-
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")保持一致。
- 职责:为
-
_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。
- 职责:在
-
测试与发布说明(
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)。 本次改动未触及生产控制面状态机、权威存储或并发调度代码,风险总体可控;以下为非阻塞后续改进与验证边界说明:
- 非阻塞改进建议(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()方法,使多并发调用下同样严格线性化。 - 非阻塞改进建议(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,未受影响,后续若扩展可一并对齐)。 - 非阻塞文字建议(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.py21 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 head632dc3895b48b2e53310fb82e6bfa1dba824514d运行同夹具对照:settle_turn=True在 Baseline 复现ValueError: vision_closeout_durable_writeback_incomplete,在 Head 通过并收敛为settled=True, spend_count=1;settle_turn=False两端输出完全一致。 - 直接调用
vision_checkpoint.tsbuildVisionCheckpoint确认嵌套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.ts65 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_checks4/4、python_compile1/1、risk_profile_smokes8/8、public_boundary1/1、catalog_canaries9/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).
Summary
dispatch_vision_closeoutinloopx/control_plane/testing/replan_vision_closeout_behavior.pysorefresh-state ... --settle-turn(which appends both a durable writeback row and a trailingclassification == "quota_slot_spent"row intoruns/index.jsonl) selects the non-spend writeback row and immediately executes_verify_vision_settlementinstead of misreading the trailingquota_slot_spentrow asvision_closeout_durable_writeback_incomplete; also reject duplicatespend-slotafter--settle-turnsettlement (vision_closeout_already_settled).VISION_HOST_INSTRUCTIONso--agent-vision-jsonsets top-levelstride_decisionfromstride_control.minimal_example.consumptionintests/control_plane/test_creation_allowance_hold.py(_ObservedCalls) using entry/completion start-sequence monotonicity so a trailing pre-snapshot in-flightconsume_creation_requestnever unblocksafter(previous)prematurely, plus add focused regression tests intest_replan_vision_closeout_receipt.pyandtest_creation_allowance_hold.py.#9014,#9170, and#9178indocs/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.DoubaoReplanSemanticActionBehaviorActor.qualify(..., required_vision=True)verification:r1(22calls,0shell errors,settled=True) andr2(34calls,0shell errors,settled=True) — both passed.ruff check,mypy(default 17 files +--follow-imports=silentonreplan_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_fafc651e7f81cdb810b6valid.