Skip to content

Keep write scopes on demand during Todo preparation - #9078

Open
loopx-agent wants to merge 4 commits into
mainfrom
codex/turn-workspace-selection-scope-read-20261119
Open

loopx-agent wants to merge 4 commits into
mainfrom
codex/turn-workspace-selection-scope-read-20261119

Conversation

@loopx-agent

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

Copy link
Copy Markdown
Collaborator

Goal And Delivered Outcome

Large write-scope lists can fill the initial quota read while an Agent is choosing a Todo, relocating to a worktree, or preparing an ordinary managed claim. The initial read keeps the candidate or selected Todo, the available action and the current stops. Long lists are available at their original digest-bound addresses. The guard after binding and claim supplies the complete current scope before delivery.

  • Intended base is main.
  • Written by model_agent (OpenAI Codex, GPT-6).
  • The progressive delivery contract and setup cases are documented in docs/reference/required-work-context.md. The claim presentation matches the selected Todo with the current claim before deferring its scope.

Validation

  • Tested revision is fd7c76fd41c0c0126c7149ec4273f26516125ae1 against 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25.
  • Run state is finished. Inputs are synthetic File and SQLite fixtures.
Check kind Result Evidence
regression_parity passed In the 355-path managed-claim fixture, the initial serialized CLI response dropped from 26,578 bytes to 10,292 with File and from 26,592 to 10,306 with SQLite. Both went from three pages to one.
real_entrypoint passed The original digest recovers all 355 paths. Ordinary managed claim and same-Turn readiness return the complete current list. Preparation, detail reads and the ready guard use the original Turn, with zero quota spent.
integration passed 168 first-read and nine workspace or selection cases cover both unbound routes, the managed claim, and the ready path.
unit passed The TypeScript control-plane suite passed 6,664 cases and skipped 91.
static passed TypeScript typecheck, the CLI output-budget smoke, changed-file Ruff, RFC diff verification and the local premerge checks passed.
static failed Repository-wide mypy and Ruff produced identical failures on this head and the exact target. Mypy reports an optional settlement plan mismatch, and Ruff reports an unused import in the generic monitor test. Mypy repair
unit not_run The full Python suite and platform matrix are covered by the repository CI workflow.

The measurements cover the production CLI on isolated fixtures. Live host and model costs remain unmeasured. Required Python checks and exact-head independent review remain open.

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
@loopx-agent loopx-agent changed the title Keep workspace repair candidate scopes on demand Keep write scopes on demand before Todo selection Nov 19, 2026
…selection-scope-read-20261119

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>

@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.

Reviewer: actor_kind=model_agent, declared_model=Gemini, declared_provider=Google, declaration_source=self_reported

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

本次针对 PR #9078(Keep write scopes on demand before Todo selection,head 5b28c0594028ec213fcca4a4a09e83b36e15d3fd,基于 origin/main ff905437669054465a4d7aa8c70ba3396aaf9182)的独立 exact-head 审查结论为:APPROVE(无阻塞缺陷)。

动机 / Motivation

当调度宿主或 Agent 在启用原生渐进上下文交付(--context-delivery on)下执行 quota should-run 或对已保存决策执行 quota context-project,且存在多个可执行候选 Todo 尚未绑定 --todo-id 时,无论是共享检出目录中的工作树修复路径还是独立 worktree 中的普通选单路径都会遭遇首读体积膨胀。

在改动前的基线(ff90543766)上,当首选候选包含较长的允许写入路径列表 required_write_scopes(如 355 条路径、约 21 KB)时,该列表不仅出现在推荐项 selected_todo 中,还重复出现在 action_portfolio.suggested_actions 中:独立 worktree 选单下两处长列表都未折叠,工作树修复选单下候选列表里的同份长范围仍留在首读正文,导致备选候选、选择命令和 context_details 被挤到后续分页,浪费首屏预算。本 PR 实现的可观测改善是:首读保留候选标识、短范围(小于 1024 字节)、选择命令与当前迁移/准备义务,将大于等于 1024 字节的 selected_todo.required_write_scopes 与 action_portfolio.suggested_actions[*].required_write_scopes 留在带摘要校验的原捕获中由 --select 按需读取,并在绑定 --todo-id(及必要时迁出工作树)后通过同一 Turn 的下一次 quota should-run 交付完整当前范围。非目标边界:本 PR 不改变候选排序与准入规则,不改变 --context-delivery off 完整输出,不免除后续选定 Todo 时的真实 guard 再准入,也未测量真实模型端 token 消耗。

改动思路 / Approach

本 PR 复用既有渐进上下文架构中的唯一决策边界:TypeScript 控制面 loopx/control_plane/quota/turn_envelope.ts 内的 progressivePreparationScopes() 向 progressive_context.ts 的 progressiveContextPlan() 与 requiredNativeContext() 传递 PreparationScopeDetail[] 延后清单,Python 侧(quota_capture.py / quota_context_reader.py)仅作为无状态 IO 适配器执行字节切片、SHA-256 校验与 --select 按需恢复。没有引入第二套决策逻辑、新配置开关或新持久化状态。

下表对比了改动前后在关键场景下的首读范围处理路径(基于 ff90543766 与 5b28c05940 的同输入对比):

场景 / 路径 基线 origin/main (ff90543766) 本 PR Head (5b28c05940) 权威状态与约束
agent_workspace_repair + selecting 仅延后 goal_boundary.write_scope 与 selected_todo.required_write_scopes;suggested_actions[*].required_write_scopes 仍内联 同步延后 suggested_actions[*].required_write_scopes(>=1024B),尾注统一追加迁出后重跑 guard 提示 delivery_allowed=false、spend_allowed_now=false 不变;重跑 guard 后恢复完整范围
normal_run + selecting 仅延后 goal_boundary.write_scope;selected_todo 与 suggested_actions 长范围均内联 同时延后 selected_todo.required_write_scopes 与 suggested_actions[*].required_write_scopes(>=1024B),尾注统一追加就绪后使用完整范围提示 selection_required=true、spend_allowed_now=false 不变
claim_required (!selecting) 仅延后 goal_boundary.write_scope 与基线完全一致 不触及已选 Todo 的认领前语义
ready (delivery_allowed=true) 不延后(直接返回空数组) 与基线完全一致 交付前完整写入范围始终内联
--context-delivery off / 异常或短列表 全部原始字段内联保留 与基线完全一致(fail-closed 原样保留) 默认关闭隔离完整

从架构评估来看:展示规划职责留在 TS turn_envelope.ts 的 progressivePreparationScopes 中,使选单与工作树修复的长写入范围折叠与准入/权威边界(run_decision / interaction_contract)及 Python 文件 IO 保持清晰分离,且受 requiredNativeContext 字节缩减与类型校验的 fail-closed 保护。当前 PR 边界仅覆盖未绑定选单与工作树修复场景,保留 claim_required 下 selected_todo.required_write_scopes 既有行为不变,改动内聚且可独立回滚。

具体改动 / Changes

全部改动共 3 个文件(+101 / -6),职责清晰分离:

  1. 生产运行控制面(+17 / -6):loopx/control_plane/quota/turn_envelope.ts 扩展 progressivePreparationScopes()。
  2. 公开参考文档(+4 / -0):docs/reference/required-work-context.md 补充未绑定选单时候选长写入范围按需读取说明。
  3. 端到端控制面测试(+80 / -0):tests/control_plane/test_context_first_read.py 新增双模式参数化用例 test_unbound_candidate_scopes_are_only_expanded_on_request。

关键代码讲解

  1. progressivePreparationScopes(loopx/control_plane/quota/turn_envelope.ts#L2456-L2510)

    • 职责与输入:在已验证 interaction_contract 版本为 loopx_interaction_contract_v0、should_run === true、agent_channel.delivery_allowed === false 且 spend_allowed_now === false && spend_after_validation === false 后,识别 repair(agent_workspace_repair + agent_workspace_guard)与 selecting(hasUnboundActionSelection(cli))和 claiming 三类准备态。
    • 前后变化:原先仅在 repair 时把 selected_todo.required_write_scopes 加入延后清单,且完全忽略 action_portfolio.suggested_actions;现改为在 repair || selecting 时均对合法 quota_selected_todo_v0 的长 required_write_scopes 加入延后路径 ["selected_todo", "required_write_scopes"],并在 selecting 时遍历 action_portfolio.suggested_actions,对每个 typeof candidate?.todo_id === "string" 且 longScope(candidate.required_write_scopes)(字符串数组且 UTF-8 JSON 字节数 >= 1024)的候选追加 ["action_portfolio", "suggested_actions", index, "required_write_scopes"]。最后统一在 finalScope(scopes.at(-1))尾部拼接当前阶段义务提示(repair 强调迁出后同 Turn 重跑 guard;非 repair 强调交付前使用就绪决策中的完整当前范围),避免每条范围重复同一句提示。
    • 不变量与 fail-closed:非字符串 todo_id、非数组或含非字符串的 required_write_scopes、以及不足 1024 字节的短范围均被跳过并保留内联;已进入交付(delivery_allowed !== false)或非 normal_run / agent_workspace_repair 的动作在函数入口即提前返回空数组。
  2. checkedContextPresentationPlan / contextPresentationPlan(loopx/control_plane/quota/turn_envelope.ts#L2003-L2012, #L2542-L2545)

    • 职责与调用路径:分别服务 complete_turn(校验签名捕获 loopx_turn_envelope_v1 并临时剥离 schema_version 与 contract_binding 以生成无修改原文的展示计划)与 quota_packet 路径,将 progressivePreparationScopes(...) 产出的作用域列表直接注入 progressiveContextPlan(...)。
    • 验证情况:TS 探针确认无论是直接 quota_packet 还是经过 composeCompleteTurnDecision 签名的 complete_turn 载荷,均可正确生成对应 unread_context_index.pointers 并完整保留原 contract_binding。
  3. progressiveContextPlan 与 requiredNativeContext(loopx/control_plane/quota/progressive_context.ts#L475-L556, #L560-L708)

    • 职责:消费 scopes,将每个 scope.path 写入 deferred 并在投影副本上删除对应叶子字段,同时将精确 JSON Pointer 写入 context_details.unread_context_index.pointers,拼接所有 read_instruction 到 context_details.instruction,并通过 Buffer.byteLength(JSON.stringify(required)) - Buffer.byteLength(JSON.stringify(context)) + adjustment(remaining) - adjustment(tokens) < 0 确保只有体积真正减小时才应用投影,同时保留 Python 大整数/浮点数字面量 source_number_tokens 血缘。
  4. test_unbound_candidate_scopes_are_only_expanded_on_request(tests/control_plane/test_context_first_read.py#L316-L393)

    • 职责:以 workspace_repair (True / False) 参数化覆盖共享检出修复与独立 worktree 选单两条路径,通过真实 loopx.entrypoint quota context-project --codex-app --context-delivery on 子进程执行并读取 first_read_command,断言短范围保留在 suggested_actions[1]、长范围(355 项)从 suggested_actions[0] 与 selected_todo 移出首读并可通过 context_details.command_template 联合 --select 原样恢复,且原 decision.json 与缺席 registry/runtime 未受任何写入影响。

规范依据与准则映射

本次依据修改前 origin/main(ff905437669054465a4d7aa8c70ba3396aaf9182)的既有公开契约文档 docs/reference/required-work-context.md 进行独立判定:

  • RWC-SEL-1(显式选单首读保留发现/选单命令与约束,docs/reference/required-work-context.md 第 332-336 行):implemented — 由 progressivePreparationScopes + initialContextReadGroups / prepareInitialOpening 实现;经 test_unbound_candidate_scopes_are_only_expanded_on_request 与 File/SQLite 生产 quota should-run CLI 探针验证。
  • RWC-WR-2(工作树修复及准备阶段保留迁移/就绪义务,同 Turn 重跑 guard 恢复完整范围,不改变 --context-delivery off 视图,docs/reference/required-work-context.md 第 349-355 行):implemented — 由 progressivePreparationScopes 与 requiredNativeContext 实现;经 --context-delivery off 对照、workspace_repair=True/False 全流程迁移/绑定重入验证。
  • RWC-DIGEST-3(延后详情必须从同份带摘要的原捕获经 --select 恢复且投影仅在字节缩小时生效,docs/reference/required-work-context.md 第 153-156、239-244 行):implemented — 由 requiredNativeContext 字节保护及 quota context-read --select 验证。
  • 文档新增说明评估:PR 在 docs/reference/required-work-context.md#L211-L214 新增 4 行说明未绑定 Todo 选择期间长候选写入范围按需展开语义,与修订前条文完全自洽,未放松任何既有限制。(注:文中第 349-355、384-388 行及第 401-410 行中文段未同步补充候选路径指针说明,因该文档非 docs/architecture/rfcs/ 成对 RFC,不构成阻塞。)

对主干的风险 / Risks

负面案例、边界与反事实检查

  • 默认关闭隔离(default_off_isolation: isolated):在 CLI 探针中以 --context-delivery off 运行完全相同的共享检出修复与独立 worktree 选单夹具,并在 TS 对比探针中以 progressive_enabled: false 调用 evaluateTurnEnvelope,输出均原样保留 355 条 required_write_scopes 在 selected_todo 与 action_portfolio.suggested_actions[0] 中且无 context_details,与基线行为完全一致。
  • Fail-closed 与非目标分支保持:经 TS 反事实探针验证,当候选 required_write_scopes 小于 1024 字节、类型为非字符串数组(如 [123])、或候选缺少字符串 todo_id(如 todo_id: 42)时,longScope / 类型守卫均拒绝延后并保持原值内联;当处于 claim_required(selection_required: false)或已就绪交付态(delivery_allowed: true)时,progressivePreparationScopes 输出与 origin/main 完全一致。
  • 权限边界(authority_semantics: not_applicable):本改动仅调整已有渐进展示路径集合,不新增任何角色、生命周期或 schema 版本;首读阶段 spend_allowed_now=false、delivery_allowed=false 与 selection_required=true 全部保持不变,绑选并迁出后才由真实 quota should-run 准入提供完整当前范围,且准备与按需读取花费 0 quota。
  • Caller / 作用域契合度(scope_fit):改动直接命中 quota should-run / quota context-project 的生产调用链(quota_result_delivery.py / quota_capture.py -> turn_envelope.py -> turn_envelope.ts),非死代码或仅测试路径;不涉及跨领域硬编码文案、不引入字符串子串匹配替代类型守卫、未触发静默默认行为变更,且指令提示明确区分了条件按需读取与重跑 guard / 就绪后必读义务。

本地真实校验矩阵(exact head 5b28c05940,未等待或参考远程 CI)

  • npm run typecheck:control-plane:PASS。
  • TS 定向单测(turn_envelope.test.ts, progressive_context.test.ts, context_delivery.test.ts, action_portfolio.test.ts, action_selection_admission.test.ts, interaction_contract.test.ts):PASS(167/167 passed)。
  • Python 定向套件(test_context_first_read.py, test_quota_authority_settlement_journey.py, test_quota_execution_preparation.py, test_workspace_git_fact_reads.py, test_saved_context_project.py, test_unadmitted_selection_construction.py, test_user_gate_lane_progress.py):466 passed, 14 skipped(经 -rs 确认全部 14 项跳过均为 test_saved_context_project.py 第 738/1225/1582 行因未设置 LOOPX_NATIVE_CHECKPOINT_BIN 的原生 Codex 二进制环境门控,与本 PR 无关);另单独跑通 test_codex_context_lifecycle.py(171 passed)。
  • 生产 quota should-run CLI 真实后端对比探针(File & SQLite × 共享检出工作树修复 & 独立 worktree 选单):PASS(File 修复态首读 1 页 9,964 B / 独立态 1 页 8,770 B;SQLite 修复态 1 页 9,968 B / 独立态 1 页 8,774 B;按需 --select 1 页恢复全部 355 项;绑定/迁出后同一 Turn 进入 normal_run 且完整范围就绪、quota 消耗为 0)。
  • TS 基线对比与反事实探针(ff90543766 vs 5b28c05940):PASS(证实旧 head 在独立 worktree 选单及修复选单下均未折叠候选范围,新 head 在 quota_packet 与 complete_turn 均正确延后并保留 contract_binding)。
  • 静态检查与门禁:ruff check(loopx/control_plane/quota 与改动测试):PASS;mypy(仓库配置 strict 集 17 文件):PASS;scripts/check_rfc_bilingual.py --base origin/main --head HEAD:PASS;git diff --check:PASS;loopx check --scan-path ...(3 个改动文件公开边界扫描):PASS。
  • loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main(临时挂载本地 node_modules 以运行 TS 词汇扫描,运行后已解除):PASS(gate.status = passed,direct_failure_count = 0,run_failure_count = 0,其中 semantic-vocabulary-drift-smoke.py、quota-plan-smoke.py、公开边界扫描均通过;control-plane-maintainability-ratchet-smoke.py 报告 1 项继承基线提醒 oversized_decision_function 位于未改动的 loopx/control_plane/work_items/interaction_contract.py _admitted_interaction_next_cli_actions(58 决策点 / 96 语句 > 90),已在不变基线 ff90543766 上验证出现完全一致的失败签名,归类为 pre_existing_unrelated,不阻塞本 PR)。

(非阻塞跟进建议:可按需在 tests/control_plane_ts/turn_envelope.test.ts 补一条纯 TS 单元测试直接覆盖 progressivePreparationScopes 的候选范围延后,并在后续文档整理中按需同步 docs/reference/required-work-context.md 对应中文段落。)

我的整体评价 / Verdict

综合上述架构、语义与本地实测证据,本次改动规模小而精准(code_volume: necessary;compatibility_assessment: retain;change_proportionality: proportionate,architecture_assessment: retain),只复用现有 TS PreparationScopeDetail 与 context_details 通道,在语义分类上属于局部演示规划改进(local_only,semantic_alignment: not_applicable),无新增词表、schema 版本或预算放宽。

从 outcome_impact 来看:long_horizon 为 improved——在跨多候选选择及跨工作树迁移的多步骤流程中,避免重复长范围列表挤爆首读分页并阻断备选可见性,同时保持相同 Turn 收据与准入边界;user_experience 为 improved——Agent/宿主首屏即可同时看到候选标识、短范围、选择命令与迁出/重跑指引而无需多轮分页翻找。针对渲染界面检查:已审阅 loopx/control_plane/quota/turn_envelope.ts、docs/reference/required-work-context.md 与 tests/control_plane/test_context_first_read.py,本 PR 仅涉及 CLI/JSON 渐进上下文展示,无任何渲染 UI 改动,visual_review 为 not_applicable,未验证界面范围 unverified_scope 为 none。相比 origin/main(ff90543766),精确 head 5b28c0594028ec213fcca4a4a09e83b36e15d3fd 消除了选单阶段重复长范围占页问题并保持禁用路径与非目标阶段完全等价。残余风险仅在于实测计量的是本地合成与孤立 File/SQLite 夹具的 reader 字节(未测真实 LLM 端 token 消耗),且该风险不影响控制面正确性与可恢复性。远端 PR 当前仍处于目标精确 head 5b28c0594028ec213fcca4a4a09e83b36e15d3fd(可无冲突合并至 origin/main)。

英文简短结论:
English Verdict: APPROVE — Exact head 5b28c0594028ec213fcca4a4a09e83b36e15d3fd safely defers long required_write_scopes on selected_todo and action_portfolio.suggested_actions during unbound Todo selection (both agent_workspace_repair and normal_run) in the TypeScript progressivePreparationScopes owner, preserves short scopes, selection commands, digest-bound --select recovery, and --context-delivery off parity, and passes TypeScript typecheck/167 TS tests, 466 targeted Python tests (14 native-bin-gated skips) + 171 lifecycle tests, File/SQLite production CLI probes, and quick premerge canaries (with one pre-existing unrelated ratchet advisory in untouched interaction_contract.py verified on ff90543766).

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
@loopx-agent loopx-agent changed the title Keep write scopes on demand before Todo selection Keep write scopes on demand during Todo preparation Nov 19, 2026

@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.

Reviewer: model_agent · gpt-6.2-sol · OpenAI (runtime_reported, max)

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

动机 / Motivation

Codex App 使用原生首读选择工作,或为已选 Todo 取得受管 claim。主干的准备输出仍会内联很长的 Todo 写入范围。候选保留 Todo 身份、选择命令、claim 及停止条件,把达到阈值的范围列表放到原始 capture 的按需选择器。在 File 和 SQLite 复跑中,初次读取各减少 13,514 字节。单独读取原始范围及同一 Turn 的 ready 输出都得到完整 355 条。本次核验覆盖准备阶段的读取和授权边界。实际交付继续以 claim 后的当前 guard 为准。

改动思路 / Approach

继续用 TypeScript 的 Turn 投影计算可延迟字段,并交给原始 capture 的精确选择器读回。3 个文件只调整长范围的准备阶段投影、命令说明和本地验证。命令、选中项和短范围保持可直接读取。对准备阶段的匹配 Todo 或待选项,通过原始路径取回长列表。ready 输出保留完整范围。

具体改动 / Changes

精确 head fd7c76fd41c0c0126c7149ec4273f26516125ae1,diff base 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25,3 个文件 +178/-8。逐项复核 same-todo-claim、unbound-candidate-detail、ready-and-spend。验收约定

关键代码讲解

  • 只有宿主可执行、与已选 Todo 同 ID 的 claim_required 或现有显式选择进入相应准备投影。范围仍按原始 capture 路径读回。源码
  • 未绑定选项保留已排序的候选身份和短列表。需要工作区修复与已有独立工作区两种情况下,长列表和已选范围都能按各自的指针读回。源码
  • File 与 SQLite 用同一 Turn 走 claim 前后的真实 CLI。准备输出保留命令,ready 恢复完整范围和 settlement identity。源码

对主干的风险 / Risks

主要风险是把其他 Todo 的 claim 当成当前准备,或让已可交付的输出丢失范围。代码以选中 Todo 与 preparation 的身份相等作为门槛,保留当前授权字段和原始 capture 的读取路径。外来导航摘要与改动过的 capture 在直接复跑中被拒绝。

语义与 CI 对齐

聚焦套件在基线通过 266 项,候选通过 270 项。File 首读从 22,606 降到 9,092 字节,SQLite 从 22,620 降到 9,106 字节。两种 provider 的同轮 ready 都保留 355 条,准备和 claim 的配额支出为零。两版本复现同一可选参数 mypy 错误和 F401,来源为未变更的 Python 文件。

我的整体评价 / Verdict

批准当前提交。长范围延迟读取覆盖选项和 claim 两条准备路径,恢复同轮范围及授权边界通过验证。字节统计来自本地精确源代码的初次 JSON 读取。宿主部署和实际模型成本仍待验。

English verdict: APPROVE. The native preparation reads are smaller, with exact source recovery, complete same-Turn ready scopes, and unchanged spend and delivery gates.

@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.

Reviewer: model_agent · Gemini · Google (self_reported)

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

动机 / Motivation

调度宿主与 Codex App 等原生控制面调用方在开启渐进上下文交付(--context-delivery on)执行 quota should-run 或 quota context-project 时会遇到该问题。 改动前,当处于未绑定 Todo 选单(含 agent_workspace_repair 工作区修复与独立工作区 normal_run)或已选定 Todo 但需先执行一次受管认领 claim_required 才能解锁交付时,长达 355 项的 required_write_scopes 会内联占满首读预算,在真实 File/SQLite CLI 上使 claim_required 首读超过 22 KB 并跨多页挤出候选与认领命令;改动后,首读仅保留候选与选中 Todo 身份、短范围、选单/认领命令及停止约束,将 >=1024 字节的长写入范围延后到带 SHA-256 摘要校验的原捕获按需 --select 指针中,使首读降至约 9 KB(单页),并在绑定/认领就绪后的同 Turn ready 决策恢复全部 355 项当前写入范围。 未绑定选单、工作区修复及同 ID claim_required 准备态下的首读保留关键控制信息并仅按需展开长 required_write_scopes,完成准备后同一 Turn 的 ready 决策内联交付完整当前范围且消耗 0 quota。 本 PR 不改变准入判定、候选排序规则与 --context-delivery off 完整输出,不放宽 ready 或其他阻断态,也未测量真实线上模型端 token 消耗。

改动思路 / Approach

本 PR 在 TypeScript 控制面 loopx/control_plane/quota/turn_envelope.ts 中扩展既有 progressivePreparationScopes(),统一服务于 quota_packet 与签名 complete_turn 展示规划,并在 Python 侧维持纯无状态读取恢复路径。复用 TypeScript 控制面 loopx/control_plane/quota/turn_envelope.ts 内唯一的 progressivePreparationScopes() 向 progressiveContextPlan() 与 requiredNativeContext() 传递延后路径,让 Python quota_capture.py / quota_context_reader.py 保持无状态 IO 适配器,不引入第二套展示规则或配置开关,同时受字节缩减检查与 todo_id/host_execution_allowed 守卫的 fail-closed 保护。 当前边界声明:仅针对未绑定选单(含工作区修复与独立选单)和同 todo_id claim_required 准备态下 >=1024 字节写入范围的按需折叠与回归测试,保持 ready 与 --context-delivery off 原样内联。

场景 / 状态 基线 origin/main (6a0f8bc17b) 本 PR Head (fd7c76fd41) 权威状态与恢复约束
agent_workspace_repair + 选单 仅延后 selected_todo.required_write_scopes;suggested_actions[*] 仍内联 同步延后 suggested_actions[*].required_write_scopes(>=1024B),尾注统一追加重跑 guard 指引 delivery_allowed=false、spend_allowed_now=false;迁出重跑后恢复
normal_run + 未绑定选单 候选与 selected_todo 长范围均内联 两者均按 >=1024B 延后并给出 JSON 指针,短范围(<1024B)保持内联 selection_required=true 不变;按原捕获 --select 恢复
normal_run + claim_required selected_todo.required_write_scopes 内联(File 首读 22,577 B) 同 todo_id 且允许宿主认领时延后 /selected_todo/required_write_scopes(File 首读降至 8,956 B) todo_id 不匹配或 host_execution_allowed!=true 时拒绝延后;todo claim 后同 Turn ready 交付全量
ready / --context-delivery off 完整内联 与基线完全一致 delivery_allowed=true 与默认关闭态零影响

具体改动 / Changes

精确 head fd7c76fd41c0c0126c7149ec4273f26516125ae1,对比合并基线 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25,共修改 3 个文件(+178 / -8):生产控制面 1 个文件(loopx/control_plane/quota/turn_envelope.ts +18/-8)、公开参考文档 1 个文件(docs/reference/required-work-context.md +8/-0)、控制面集成测试 1 个文件(tests/control_plane/test_context_first_read.py +152/-0)。

关键代码讲解

  1. progressivePreparationScopes:在入口确认 interaction_contract 版本为 loopx_interaction_contract_v0、should_run === true、agent_channel.delivery_allowed === false 且 spend_allowed_now === false && spend_after_validation === false 后,区分 repair(agent_workspace_repair + agent_workspace_guard)、selecting(hasUnboundActionSelection(cli))与 claiming(cli.selection_required !== true && normal_delivery_allowed === false && preparation.state === "claim_required" && preparation.delivery_allowed === false && typeof selected?.todo_id === "string" && preparation.todo_id === selected.todo_id && claim.host_execution_allowed === true)。仅当 longScope(字符串数组且 UTF-8 JSON >= 1024B)满足时延后 /selected_todo/required_write_scopes 及 selecting 下的 /action_portfolio/suggested_actions/<idx>/required_write_scopes,并在末条指针统一追加对应阶段的必读尾注。
  2. checkedContextPresentationPlan:同时覆盖普通 quota_packet 与签名 complete_turn 路径(剥离顶层 schema_version 与 contract_binding 后复用 progressivePreparationScopes),由 prepare_progressive_context / prepare_context_delivery 调用并在 requiredNativeContext 确认总字节确实缩小时才生效。
  3. test_unbound_candidate_scopes_are_only_expanded_on_request 与 test_claim_preparation_keeps_requested_write_scopes_on_demand:分别以参数化 workspace_repair(True/False)及真实 File/SQLite 后端 hard_lease quota should-run 验证短范围保留、长范围移出首读并经 command_template --select 原样恢复,以及 todo claim 后同一 Turn ready 交付完整 355 条范围且 settlement_identity 一致、0 quota 消耗。

规范依据与准则映射

依据修改前 origin/main 修订 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25 的公开契约文档 https://github.com/loopx-project/loopx/blob/6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25/docs/reference/required-work-context.md 逐项映射(PR 在该文档第 211-218 行补充的说明与既有条款完全一致,未放宽任何既有限制):

  • RWC-SEL-OPEN(显式选单首读保留候选标识、发现与选单命令及停止约束,第 335-339 行):implemented — 由 progressivePreparationScopes 与 initialContextReadGroups 实现,经 test_unbound_candidate_scopes_are_only_expanded_on_request 验证。
  • RWC-WR-CLAIM(工作区修复与受管认领准备保留迁移/认领指引并在同 Turn ready 恢复完整范围,第 352-358 行):implemented — 由 progressivePreparationScopes 实现,经 test_claim_preparation_keeps_requested_write_scopes_on_demand 与基线/Head File/SQLite 实测对比验证。
  • RWC-OFF-PARITY(--context-delivery off、ready、短列表及异常/不匹配准备态保持原始全量内联):implemented — 由 requiredNativeContext 与 progressivePreparationScopes 类型/身份守卫保证,经 TS+Python 反事实探针验证。

对主干的风险 / Risks

  • 默认关闭与边界隔离(default_off_isolation: isolated):progressive_enabled: false / --context-delivery off 入口直接跳过延后,保留全部 355 条范围与无 context_details 输出;在 claiming 路径中若 preparation.todo_id !== selected.todo_id、host_execution_allowed !== true、required_write_scopes 小于 1024 字节或非字符串数组,或已进入 delivery_allowed: true 的 ready 状态,反事实探针均证实保持原值内联且不修改 contract_binding。
  • 生产调用链与权限边界(scope_fit / authority_semantics):改动直接命中 quota should-run 与 quota context-project 生产入口(quota_capture.py -> turn_envelope.py -> turn_envelope.ts),无死代码;未新增任何 actor 生命周期、schema 版本或权限声明,spend_allowed_now=false、delivery_allowed=false 与零 quota 准备语义不变。非阻塞细节提示:docs/reference/required-work-context.md 对应中文段落可按需在后续文档整理中同步补充 claim_required 指针说明(该文档非成对 RFC,不构成阻塞)。

语义与 CI 对齐

本 PR 属于局部展示规划改进(local_only,未改动共享词表或持久化 schema,semantic_alignment: not_applicable)。本地直接校验结果(未等待或参考远程 CI,wait_for_ci: false):

  • npm run typecheck:control-plane 与 6 份定向 TS 单测(turn_envelope.test.ts, progressive_context.test.ts, context_delivery.test.ts, action_portfolio.test.ts, action_selection_admission.test.ts, interaction_contract.test.ts):PASS(167/167 passed)。
  • Python 定向套件:test_context_first_read.py 168 passed;test_codex_context_lifecycle.py + test_quota_execution_preparation.py + test_quota_authority_settlement_journey.py 305 passed;test_quota_settlement_cli.py -k "claim or selection or scope" 38 passed(注:早先将 test_quota_settlement_cli.py 与跨文件混合并发运行时出现 pytest session effect-runtime0 临时目录清理碰撞报错,已对碰撞用例 test_recovery_does_not_bind_current_replan_and_reenters_same_turn 单独复跑 2/2 PASS 排除回归)。
  • 基线 vs Head 真实 File/SQLite CLI 对比(claim_required 355 项范围):File 首读从基线 6a0f8bc17b 的 22,577 B 降至 Head fd7c76fd41 的 8,956 B(序列化页 10,138 B),SQLite 从 22,591 B 降至 8,970 B(序列化页 10,152 B),两后端均降至单页且 --select 与 todo claim 后 ready 均恢复完整 355 条。
  • TS+Python 反事实探针(覆盖 mismatch_todo、host_allowed=False、progressive_enabled=False、短范围、ready 及签名 complete_turn):PASS。
  • ruff check tests/control_plane/test_context_first_read.py、git diff --check、scripts/check_rfc_bilingual.py、loopx check --scan-path(3 个改动文件公开边界扫描):PASS。
  • loopx canary premerge --tier quick --from-git-diff --git-diff-base 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25:PASS(gate.status = passed,merge_gate_passed = true,direct_failure_count = 0,run_failure_count = 0)。
  • mypy(仓库配置 strict 17 文件):报 1 项既有的 interaction_contract.py:1004 类型错误,已在合并基线 6a0f8bc17b439f1e5fa1d389ad5a87faf7d73b25 上复现相同错误签名(pre_existing_unrelated)。

我的整体评价 / Verdict

从 outcome_impact 评估:long_horizon 为 improved(消除选单与普通受管认领前重复长写入范围对首读分页预算的挤压,同时在同 Turn 认领或迁出就绪后恢复完整范围与原 settlement_identity),user_experience 为 improved(首屏即可完整呈现候选、认领与迁移命令而无须多轮翻页)。本 PR 仅涉及控制面 JSON 渐进展示规划,无任何渲染 UI 改动,visual_review 为 not_applicable(已审阅全部 3 个改动文件,未验证界面范围 unverified_scope 为 none)。综合 code_volume(necessary、compatibility_assessment: retain)、change_proportionality(proportionate、architecture_assessment: retain)、default_off_isolation(isolated)、authority_semantics(not_applicable)及局部词表评估(local_only),整体实现简洁精准。残余风险为未测量真实线上模型端 token 消耗且未重跑完整全仓 Python 矩阵,但不影响控制面正确性。当前远程 PR 仍位于目标精确 head fd7c76fd41c0c0126c7149ec4273f26516125ae1。

英文简短结论:
English verdict: APPROVE — Exact head fd7c76fd41c0c0126c7149ec4273f26516125ae1 cleanly defers long (>=1024 B) required_write_scopes on selected_todo and action_portfolio.suggested_actions during unbound Todo selection, workspace repair, and matching claim_required preparation in TypeScript progressivePreparationScopes, cuts claim_required first-read size from ~22.6 KB to ~9.0 KB on real File and SQLite backends while preserving exact --select recovery, same-Turn ready scope restoration, complete_turn signing, and --context-delivery off parity, and passes TS typecheck + 167 TS tests, 473 + 38 targeted Python tests, counterfactual probes, Ruff/boundary/RFC checks, and quick premerge canaries (with pre-existing mypy error in untouched interaction_contract.py verified on base 6a0f8bc17b).

This branch has not been deployed

No deployments
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