[songoow]

目标与当前状态

本 PR 面向 LoopX 控制上下文开销，补上一段 C2「当前工作必读范围 → 实际交付 → 同次快照详情与恢复」 的实现：复用现有 context-delivery on，完整交付当前 Agent 和关联工作的 outcome 要求；对声明关系范围之外的其他 Agent 的 outcome，保留当前索引和原始内容的精确引用，避免每次都默认展开全部正文。

本 PR 已转为普通 PR，供正式审阅；不代表已满足合并条件。 当前主干整合、真实原生输入路径和完整测试仍需完成。此次状态及说明更新未修改代码，也没有启动付费模型压测；不宣称实际 token、账单或任务分数已经改善。

• 当前提交：c80b15fe86e711257ef4fb0de99795a886e57030
• 实现基线：843be494266774b63b3de61d0adf5dd7f4f877a2，目标分支：main
• 已发布改动：19 个文件，+1164 / −40
• 初次发布时观察到的目标版本：0cfbf11dcea4ba7bc8fb13f06f1c915b63ce8fad；当时目标比实现基线多 16 个提交。这是历史发布信息，不作为当前主干整合已完成的证明。

为什么需要这样调整

1. 差分解决「不要重复发送」，但不自动解决「第一次需要读多少」

只对完整大包做 full/delta，仍可能在冷启动、压缩后恢复或基线失效时重新展开全部累计 outcome。当前只推进局部工作时，其他 Agent 的大量要求正文、来源说明和历史评审也会进入输入。

本次要减少的是这类默认展开，而不是缩短原始要求或让模型少看必要证据。目标是把 当前必须完整读取的材料 与 保留索引、依赖前再精确读取的材料 分开；是否降低完整请求成本，仍需把补读、历史回放、恢复和往返一起验证。

2. 不能只在 renderer 中裁剪 JSON

如果输出已经省略部分正文，但原交互指令仍要求完整读取所有 outcome，模型会补读整包，甚至增加工具和模型往返。反过来，仅删除必读指令，也可能遗漏共享要求、跨任务依赖或反面证据。

因此读取范围由现有验收语义 owner 产生，交互指令、实际投影、详情读取与恢复共同消费同一份来源。Python 只传递参数和处理文件/分页，不建立第二套范围判断或准入规则。

3. 「属于其他 Agent」不等于「与当前任务无关」

实现使用规范工作快照和已有结构化关系，保留当前 Agent 的全部 outcomes，并沿选中工作的关系扩展必读集合；共享验收绑定、请求/证据引用以及失败或过期观察都会扩大范围。工作未绑定、关系无法解析、来源版本不一致或范围不可用时，回退完整交付。

这里没有按标题、关键词或自然语言相似度猜测相关性。声明关系的闭包仍不等于对任意自然语言要求的独立性证明，这也是需要重点审阅和进一步验证的限制。

4. 按需读取必须保留原始来源，不能用「再跑一次 guard」代替恢复

重新执行 guard 可能得到不同的工作、权限、来源版本或结算身份，不能拿来补齐旧决策的遗漏内容。此实现先保留完整原始 capture，再保存独立的 required-context.json；详情绑定原始文件与 SHA-256，差分基线和恢复则绑定实际交付的那份上下文。

未交付的可选正文不能被当作模型已经读过。单个 outcome/index 的分页也不能建立完整上下文的连续性基线。为防止同一原始文件在 reader 升级后产生不同分页布局，派生读取额外绑定 selection_sha256。

修改前后与实际路径

关注点	修改前的限制	本 PR 的处理
默认展开范围	差分减少重复传输，但完整来源中的累计 outcome 仍可能全部展开	只在有效的原生 opt-in 路径上应用保守必读集合；其余保留索引与精确详情入口
必读指令	仅缩小输出会与完整读取义务冲突	只替换现有 interaction owner 的已识别指令；未知指令或未完成必读保持全量
细节补读	为一个 outcome 可能需要读取整份来源	quota context-read --outcome-ref 从同一次原始 capture 返回索引或完整 outcome
差分与恢复	不区分完整来源和实际已交付视图，可能错误复用未读内容	完整来源与 required-context 分别保存，复用已有 full/delta 和生命周期机制
额外包装开销	索引、引用和说明也可能比小正文更长	对包含包装和指令的完整投影比较 UTF-8 字节；不更小时返回原始内容
关闭与其他入口	不能让可选优化改变普通执行语义	默认 off 与显式 --turn-envelope 不采用新的范围裁剪；不新增模型会话

已有验收 owner：当前工作快照 + 结构化关系 + 验收来源
    → 带来源修订和摘要绑定的必读计划
    → 保存完整原始 capture
    → 生成必要上下文、当前索引和原文引用
    → 确认完整投影更小并保存 required-context
    → 复用现有原生 full/delta、分页、连续性与同次恢复

当前目标、全局约束、权限、停止条件、未完成必读和原 Turn 结算身份不能因范围优化而被省略。全局重规划、未知字段、未知指引、不完整来源或失效范围保持完整来源。优化/发布失败采用原有完整内容回退；这不是新的执行授权或验收判定。

各文件为什么需要修改

范围产生与调用链：让决定来自已有语义 owner

文件	调整内容与原因
loopx/cli_commands/quota.py	在已有 capture、显式 context delivery 开启且非 TurnEnvelope 时传递范围请求，避免普通关闭路径被隐式改变。
loopx/control_plane/quota/live_decision.py	将 opt-in 请求传入工作上下文读取链；不在 live decision 层重新选择工作或判断 outcome 相关性。
loopx/control_plane/work_items/context_readback.py	将当前 Agent 和范围请求交给验收来源读取，使范围与该次读取绑定，而非从后续显示摘要推断。
loopx/control_plane/goals/acceptance.py	给现有验收检查适配器传递可选的 context Agent 身份，维持 Python 传输适配职责。
loopx/control_plane/goals/acceptance_authority.ts	在现有验收检查路径生成并附带读计划及 provider revision，避免另查一份可能变化的权威状态。
loopx/control_plane/goals/outcome_requirements.ts	增加 outcomeContextReadPlan，从规范工作快照、owner、工作关系和共享证据计算保守集合；信息不足扩大为全量，不按正文猜测。

投影与交互指令：减少正文，但不丢失义务

文件	调整内容与原因
loopx/control_plane/quota/outcome_context.ts	提取并适配 #7430 的 outcome 交付片段，集中校验读计划、生成索引、保留必读正文和精确详情，执行完整投影大小检查；不新建验收或权限 owner。
loopx/control_plane/work_items/outcome_read_guidance.ts	共用原始与 scoped 读取指引，仅在已知、完整、无待读义务的条件下切换，避免投影省略正文却仍要求无条件补读全文。
loopx/control_plane/work_items/interaction_contract.ts	引用共用的读取指引，保持未启用路径的原义务，避免两处提示词各自演化。
loopx/control_plane/quota/turn_envelope.ts	将原生交付和 captured outcome 读取接入已有 typed endpoint，不增加平行的调用入口或决策引擎。
loopx/control_plane/quota/context_delivery.ts	识别 scoped presentation，并对其内部实际交付上下文沿用现有 fresh/reuse 规则；不另写一套 diff，也不把未读原文纳入已保留基线。

传输与恢复：读取同一份内容，而不是重新做决定

文件	调整内容与原因
loopx/cli_commands/quota_registration.py	将现有 --outcome-ref 扩展到 context-read，增加派生分页摘要参数；索引和详情使用同一公开 reader。
loopx/cli_commands/quota_capture.py	校验精确 outcome 选择与 selection_sha256，保留 UTF-8 分页和原始来源恢复；拒绝混用不同派生布局的游标。完整交付直接复用已有 recovery 文件，避免写出没有消费者的重复 wire。
loopx/control_plane/turn_driver/decision_capture.py	在已有读取命令和 capture 写入 helper 中携带 outcome 选择/分页绑定，并支持独立 required-context 文件；不复制新的 capture 服务。
loopx/control_plane/turn_driver/codex_context.py	先发布完整来源，再发布实际必读视图；将 recovery、pending 和后续差分绑定该视图。第二份文件发布失败时保持完整来源回退，不伪造连续性。

测试与说明：明确要验证什么，而不是把测试文件存在当成通过

文件	覆盖目的
tests/control_plane_ts/outcome_context_scope.test.ts	覆盖范围与关联规则、保守回退、精确引用及与既有差分机制的组合行为。
tests/control_plane/test_outcome_context_transport.py	覆盖实际 projector/reader、原始快照详情分页、派生摘要、原生生命周期模拟和发布失败恢复。
tests/control_plane/test_outcome_scope_cli.py	覆盖公开 quota opt-in 到分页 stdout 的调用链，核对关闭路径、原始来源保留和缩减后的投影。
docs/reference/scoped-outcome-context.md	记录启用方式、读取义务、详情/恢复约束、回退方式和验证限制，避免将传输层变化误读为收益已成立。

与现有 PR 和设计的关系

本次从 #7430 的 outcome-context 方向提取有限的、面向现有 native quota 的实现，不复制整个 C1 完整契约切换，也不引入 controller/executor 双会话。后续仍需要对齐 #7430 与主干的 owner、调用方和格式变化，避免两套实现长期并存。

#7543 修的是 Harbor 用量统计的未知值/零值混淆；本 PR 修改的是模型可见上下文的交付路径，两者目的不同。包体缩小与少一次本地解析都不能直接证明模型 token 或费用下降。

**当前限制：同一个 Agent 名下的全部 outcomes 仍完整保留。**本次主要尝试减少其他 Agent 的非关联正文，不能声称已经解决全部单 Agent 长任务开销，也没有完成 C2 的全部入口迁移。

验证事实、待完成项与合并条件

已核实代码提交、分支和 PR 的远端读回。**尚未对恢复后的当前提交重新完成本地测试、原生宿主测试和完整仓库检查；此前无法核实的通过数量不作为本 PR 的验证证据。**此次仅更新 PR 状态和说明，不改变这一事实。CI 结果以当前 head 的 Checks 为准，本说明不宣称全部通过。

合并前仍需：

1. 整合最新 main，处理与 WIP: converge governed work inputs and packaged heartbeat consumers #7430 及其他已采用实现的重叠，验证默认关闭路径及已有 reader 的兼容性。
2. 在受支持环境运行精确 head 的 TypeScript 测试/类型检查、Python 聚焦与相邻测试、File/SQLite 真实路径，以及按影响范围要求的其他 provider 和 premerge 检查；不能绕过 SQLite 资格检查，不能将 skip 当成 pass。
3. 验证真实原生输入的冷启动、warm delta、相关要求变化、详情补读、压缩、截断、hook 失败和同次恢复；确认没有新增准入、错误沿用权限或重复结算。
4. 在固定源码和任务条件下比较完整序列化模型请求、输入分类、请求次数、补读与恢复开销；保留回退和性能回退证据。真实模型结果和账单收益单独验证，不由本 PR 自动启动付费实验。

聚焦 Python 检查入口：

uv run --extra test python -m pytest \
  tests/control_plane/test_outcome_context_transport.py \
  tests/control_plane/test_outcome_scope_cli.py

TypeScript 使用仓库的规范测试/类型检查命令，覆盖 tests/control_plane_ts/outcome_context_scope.test.ts 与相邻 context delivery suites。上述是待执行入口，不是本次已执行结果。

启用、回退与公开边界

沿用现有差分上下文开关及配套 native hooks；保存偏好不等于宿主已加载、信任或实际使用它。新运行可显式选择 --context-delivery off 保持普通完整交付，不改变活跃或冻结实验的配置。

回退或降级 reader 前，保留原始 capture、required-context 和未结算回执；先恢复/完成原工作，不能用新的 guard 替换旧快照。无新增 UI，复用已有 opt-in 入口；已安装宿主的实际采用仍待验证。

提交不以私有日志、原始 trace、凭据或隐藏评测数据作为公开 fixture；现有新增 fixture 为合成数据。没有修改评分、评测机会、预算、执行权限或 active/frozen trial，没有合并、安装、发布或启动付费推理。

作者声明：在贡献者指导下由 OpenAI GPT-6 Astra Pro 辅助实现，提交保留 DCO sign-off 与 assistance attribution。

[mergify]

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @songoow.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-28T10:43:31.996729Z	c80b15f	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.