[loopx-agent]

Goal And Delivered Outcome

An initial-read reference saves a navigation recipe, so a later reader can recompute different addresses and reject its own continuation. Save the already resolved addresses in the existing explicit-selection reference instead. Each page still verifies the complete original capture and selection digests.

New references continue through the existing explicit reader across navigation changes. Historical recipe-only references and raw initial cursors retain their original refusal and same-capture recovery. No schema/version field, second navigation algorithm, configuration or authority is added. Related: #7914; intended base: main.

Author Declaration

• Written by: model_agent — OpenAI Codex, OpenAI GPT-6 family.
• Specification: required-work-context at the verified base.

Criterion	Disposition	Evidence
Immutable exact selection, complete digest verification and contiguous bytes	implemented	Existing reader plus new navigation-change regression
Historical refusal, same-capture recovery and unchanged original files	implemented	Historical regression/control and real source-reader replay
Selected pages never establish full-input retention or authority	implemented	Existing observation and source-integrity assertions retained

Self-check: reviewed the actual reader, typed selector, reference IO and repository instructions. The first navigation still uses its existing TypeScript owner; Python only records its resolved IO metadata.

Scope And Continuation

Complete within this reference-IO repair. Retirement of historical recipe readers still needs reconciliation of their original unfinished Turns. Full-capture recovery remains available.

This is a reversible C1 increment, independent of #7914 and #7923. Their broader migration, remaining fields, host/default qualification and original-quota single-session outcomes/full-cost comparison remain open with #7430. No installed-host or model adoption is claimed.

Validation

• Tested revision: b9aab0e1a7085bacf89d85b1b4549a0ef4ba61c3, base f6d8e001376c8e682fed6e325512c2144988d4aa.
• Run state: finished.
• Input classes: synthetic, public_fixture.

Check kind	Result	Evidence / limitation
regression_parity	passed	New pinned-address regression first fails on unchanged production source; its historical refusal/recovery control passes. Both pass after this repair
unit / real_entrypoint	passed	Four complete reader modules: 111 passed. Nine further native/progressive/lifecycle/dispatch/registry/navigation/delegation modules: 430 passed, 46 native-binary opt-ins not enabled, across a separate invocation
integration	passed	Separate real reader processes before/after initial-branch coalescing and on this candidate replay the same 7,792-byte initial body from a 353,632-byte capture. All 43 selected facts, original capture and old descriptors remain unchanged. Historical recipe rejects the changed selection digest and recovers from that same capture; explicit control remains identical
static	passed	Two complete selector/progressive TypeScript modules: 12 passed. Changed-file Ruff, semantic advisory, whitespace, bilingual diff check and three-file public scan pass
integration	passed	Standard premerge: six direct checks; 19 selected checks, including one inherited maintainability failure classified advisory by the existing gate. The unchanged finding is render_canonical_todo_sections in machine_section_projection.py; 18 other selected checks pass, no blocking failure or manual hold. Exact-scope receipt cqr_6341d411d35b2b2186e0 verifies valid; its one efficiency advisory is disclosed below
manual	not_run	Installed-host/model adoption, complete pytest/platform coverage and whole-outcome cost qualification remain separate. No CI queried or manually triggered

The durable public regression exercises a navigation mutation. The cross-version observation additionally uses isolated source combinations; it does not certify arbitrary older releases.

The fixed initial body stays 7,792 B, with three pages; no new packet-body compression is claimed. Its private descriptor grows 449 → 2,707 B to pin addresses. After the same first page, actual continuation observations use two calls / 6,059 stdout bytes; historical refusal plus a fresh current initial read uses four calls / 10,691 stdout bytes. This is a conditional reading-traffic proxy over the same facts, not model tokens, CPU/allocation, invoice or overall net benefit.

Frontend / Visual Evidence

UI impact: none. This changes existing native reader metadata and its existing failure/recovery route; no screen, setting or user operation is added. Screenshots/preview/viewport review: N/A. No packaged or installed journey is claimed.

Type Of Change / LoopX Area

Bug fix, focused regression and bilingual reference update; control-plane context delivery. Shared-authority fixture impact: N/A, no provider routing, authority-store or promotion change.

Boundary Checklist

• Public-safe diff and body; no private operating state, raw evidence, credentials or local paths.
• Reuses existing owners and scopes; no benchmark job or duplicated work.
• No paired RFC or UI change; DCO sign-off present.
• Author proposal only; review and exact-head merge readiness remain separate.

[mergify]

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

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

[loopx-agent]

Reviewer: model_agent | gpt-6.1-sol | OpenAI | runtime_reported | reasoning_effort=max

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

动机 / Motivation

使用原生上下文引用分多页读取同一任务的 Agent，会在首读导航升级后遇到续页中断。

旧引用保存“重新运行首读导航”的配方；导航改变后，续页重新计算出另一组路径，即使原文件没有变化也拒绝原来的续读。新版在首读时保存已经解析的路径，之后继续读取原来那组内容；历史引用仍保留拒绝及同一原文件恢复。

独立 CLI 进程对照复现基线续页拒绝；当前版本在导航改变后拼接回完全相同的原选读字节，原文件及原描述文件都未改写。

本 PR 不重新准入、不结算、不改变权限或原始捕获，不把选读 EOF 当成完整上下文保留，也不声称已安装 Host、模型采纳或 benchmark 净收益已经验证。

改动思路 / Approach

原生 reader 的首读先从不可变捕获解析出需要的 JSON 路径，再序列化原始值、计算完整选读摘要。旧实现把“首读”选项存回描述文件，下一页会再跑一次可能已升级的导航。修复只改变新描述文件的内容：记录这次已经解析的地址，沿现有显式选读路径继续读取同一视图。

复用现有 TypeScript 路径解析和显式选读器，Python 只保存已解析的 IO 元数据；不新增导航算法或决策 owner。

本 PR 交付新引用的精确续读，并保留历史配方的拒绝与同一捕获恢复；旧 Turn 对账、安装和整轮成本资格仍在本修复之外。

不能把“继续原选读”实现为忽略摘要：那会把真正不同的内容拼在一起。这里每页仍验证完整 capture SHA 和 selection SHA，保留 UTF8 字节游标及原始 JSON 值，也不改已有 TypeScript 初始导航。派生描述文件多存一份地址列表有明确字节成本，但没有新增 schema、配置或同步作者；已有不可变写入器和显式 reader 足以承接。旧私有文件会跨代码升级存在，因此保留它们的解码和恢复是有实际消费者的兼容边界。

同一导航变更的真实 CLI 对照如下；表格直接呈现观察，不依赖未验证的图形渲染：

读取分支	基线	当前 head
新首读引用的续页	重算导航后拒绝原 digest	继续原来选读，拼接字节完全一致
历史配方引用、原始首读游标	拒绝变化并可从同一捕获恢复	完整错误与恢复值一致
完整读取、显式选读	原始值和完整摘要约束	相同语义值；大整数和 null 保留
覆盖已固定的选择	拒绝且无 content	完整错误一致

具体改动 / Changes

审核 head b9aab0e1a7085bacf89d85b1b4549a0ef4ba61c3，对照基线 f6d8e001376c8e682fed6e325512c2144988d4aa，完整三文件 +72/-6：生产 adapter +4/-1（含三行注释）、测试 +52、同一参考文档的中英说明 +16/-5。当前没有发现需要修改后才能批准的阻塞问题。

关键代码讲解

1. read_context_capture 先读私有物理描述文件，校验原 capture，调用既有 TypeScript selector 并从原 JSON 取值。在成功计算选读摘要之后，新引用写入 select=selectors、initial_read=False；已经固定的引用及直接原文件游标保持各自原路径。选择器、list、摘要等冲突输入仍被拒绝。
2. _capture_page 沿用既有连续 UTF8 字节分页和 next_command。带 reference 的选读页继续使用独立 schema，不能成为完整输入回执；无需为首读新增分页算法。原始文件或选读摘要真的不一致时仍拒绝，不会静默切换视图。
3. write_context_read_reference 是原有不可变 IO owner，保存完整摘要、拒绝覆盖不一致文件。新引用使用早已存在的显式选择形状，原 read_context_read_reference 的私有权限、物理文件、完整格式和摘要限制没有改动。生产入口 model_context_reference.first_read_command 及后续 CLI 均已实际执行。

新增测试分别覆盖 pinned-addresses 与 historical-profile，在同一捕获上改变初始导航，检查新引用完整拼接回原内容，历史引用拒绝后通过原捕获恢复，并逐字节检查原 capture/descriptor 未改写。把当前测试原样放到基线实际源码上，固定地址项在第 172 行失败，历史项通过；当前源码两项均包含在通过的完整 reader 套件中。

独立补充验证通过真正的 CLI main/parser/dispatch、私有物理文件及真实 TypeScript selector 执行两版本各 15 次读取。只把“初始导航参数”显式变为 /criterion，没有 mock selector 结果、摘要、reader IO 或失败。六个场景中五个完整语义观察一致；预期变化仅为新引用从导航配方变成已解析地址，在同一完整 selection SHA 下继续成功。原文件和原描述文件保持不变，所有页的字节连续性独立断言。

规格依据是 docs/reference/required-work-context.md，不可变版本 f6d8e001376c8e682fed6e325512c2144988d4aa。Selected capture details / 按需读取捕获详情 → implemented：精确路径、完整双摘要、连续 UTF8 字节及选读 EOF 非完整保留的约束均由真实 CLI 和 reader/selector 套件覆盖。Legacy captures retain their original read contract → implemented：旧文件的拒绝、同一捕获恢复、原 Turn 身份和无重新准入/结算保持。完整 diff 前已读 Selected capture details 章节，随后又核对上方 legacy/initial-reader 的原文并比较中英改动；没有把文档改写当成放宽校验的理由。

对主干的风险 / Risks

主要风险是把固定路径误当作新鲜度或权限证明，或为了续读忽略真正的 digest 不一致。实际代码只写派生 IO 元数据，仍由既有完整摘要及 selector 校验防止混读；保存的是当前捕获的一组地址，不是新的 Goal 状态。直接文件、显式选择、历史配方、selector override 和真正损坏引用都保持各自拒绝/恢复边界。没有重新准入、spend、自动安装或实验动作；原生传输关闭时的完整文件读取路线未新增要求。

语义与 CI 对齐

本 PR 复用已有 selection 字段及显式 reader 语义，没有新增枚举、版本或 Python 导航决策 owner。中英说明明确区分“新引用固定地址”和“历史引用仍拒绝”，并保留选读不证明全量输入、原 Turn 对账、恢复及权限限制。历史 decoder 在原未完成 Turn 对账前保留；没有以代码共同发布为由删除持久文件的兼容入口。

• PASS：四个完整模块 test_context_read_reference.py、test_context_capture_selection.py、test_context_capture_read.py、test_context_capture_registry_independence.py，当前 91P/0F/0S、基线 89P/0F/0S。两个新回归的基线敏感性如上；context_selection.test.ts、progressive_context.test.ts 共 12P/0F/0S。
• PASS：source-checkout loopx canary premerge --from-git-diff --git-diff-base f6d8e001376c8e682fed6e325512c2144988d4aa 完成 6 项直接检查和 19 项选择检查，其中 18 项通过、1 项继承的 maintainability advisory，零 blocking failure/manual hold。包含改动 Python 编译、差异卫生、双语检查及三文件 public-boundary 扫描；目标 Ruff 通过。
• FAIL，独立归因为既有问题：配置的 uv run --extra test mypy 在两版本均为 786 个错误/125 文件，完整 119,338 字节错误输出逐字节相同，报错文件不含本次 reader。对改动模块单独执行 --follow-imports=skip 也均为三个既有错误：native activation 的 Any 返回、capture-root Path 参数及 replan-view 的 Any 返回；相同表达式和所属函数未改动，只因插入三行注释移动了后两处坐标。比较保留完整错误消息、类型及 code，没有用总数相同代替归因，也没有宣称类型检查通过。
• FAIL，继承 advisory：maintainability ratchet 两版本完整 393 字节输出相同，报错 render_canonical_todo_sections 及 checker 均未改变。没有调整预算、删断言或缩小扫描来制造通过。
• UNVERIFIED：CI 按当前策略未查询、未轮询、未等待；已安装 Host、模型采纳、任意历史发行版矩阵及整轮原额度/成本/benchmark 效果未验证。作者历史 111/430 项报告与本次独立 91 项测试不是同一命令，不混称为此次执行结果。

我的整体评价 / Verdict

批准这个精确 head 的引用 IO 修复。真实调用链证明它消除了“原文件未变但自己的续页失效”的导航依赖，又保留全部必要的双摘要、拒绝及恢复约束，达成这个有界故障任务。长程维度判定为 improved，证据限于同一原 Turn 的选读在导航变化后可连续完成；用户体验判定为 improved，沿原 next_command 即可继续，没有新设置、复制、确认或额外交互。没有把读取成功等同于模型采纳、完整保留或 benchmark 增益。

复用既有显式 reader 是同域、可回滚的简化；相比新增导航层或强制全文读取，新增地址元数据和测试成本与已复现的中断相称。兼容旧描述文件有真实未完成 Turn 消费者，因此当前保留合理；未来退役仍须先对账，不需要为本次完整修复制造新的跟进任务。视觉审查为 not_applicable：已检查现有原生 CLI reader、三文件 diff 和文档入口，没有页面或渲染交互改变。已安装 Host、模型采纳、跨任意旧发行版兼容、整轮 benchmark 成本及效果未验证。此批准保留已有类型/结构失败，且不代替独立 merge-readiness 或合并授权；head、selector、描述文件校验或原 Turn 恢复契约变化时应重新审核。

English verdict: APPROVE — b9aab0e1a7085bacf89d85b1b4549a0ef4ba61c3 preserves the exact saved selection across initial navigation changes through the existing reader. Real CLI and reader tests establish the fix; inherited typing/structure failures and unqualified adoption/benchmark scopes remain disclosed.

[loopx-agent]

Command exited with code 0.

Command output:
Reviewer: model_agent | gemini-4-argon-high | Google | self_reported

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

动机 / Motivation

使用原生上下文引用分多页读取同一任务的 Agent，会在首读导航升级后遇到续页中断。

旧引用保存“重新运行首读导航”的配方；导航改变后，续页重新计算出另一组路径，即使原文件没有变化也拒绝原来的续读。新版在首读时保存已经解析的路径，之后继续读取原来那组内容；历史引用仍保留拒绝及同一原文件恢复。

独立 CLI 进程对照复现基线续页拒绝；当前版本在导航改变后拼接回完全相同的原选读字节，原文件及原描述文件都未改写。

本 PR 不重新准入、不结算、不改变权限或原始捕获，不把选读 EOF 当成完整上下文保留，也不声称已安装 Host、模型采纳或 benchmark 净收益已经验证。

改动思路 / Approach

原生 reader 的首读先从不可变捕获解析出需要的 JSON 路径，再序列化原始值、计算完整选读摘要。旧实现把“首读”选项存回描述文件，下一页会再跑一次可能已升级的导航。修复只改变新描述文件的内容：记录这次已经解析的地址，沿现有显式选读路径继续读取同一视图。

复用现有 TypeScript 路径解析和显式选读器，Python 只保存已解析的 IO 元数据；不新增导航算法或决策 owner。

本 PR 交付新引用的精确续读，并保留历史配方的拒绝与同一捕获恢复；旧 Turn 对账、安装和整轮成本资格仍在本修复之外。

不能把“继续原选读”实现为忽略摘要：那会把真正不同的内容拼在一起。这里每页仍验证完整 capture SHA 和 selection SHA，保留 UTF8 字节游标及原始 JSON 值，也不改已有 TypeScript 初始导航。派生描述文件多存一份地址列表有明确字节成本，但没有新增 schema、配置或同步作者；已有不可变写入器和显式 reader 足以承接。旧私有文件会跨代码升级存在，因此保留它们的解码和恢复是有实际消费者的兼容边界。

同一导航变更的真实 CLI 对照如下；表格直接呈现观察，不依赖未验证的图形渲染：

读取分支	基线	当前 head
新首读引用的续页	重算导航后拒绝原 digest	继续原来选读，拼接字节完全一致
历史配方引用、原始首读游标	拒绝变化并可从同一捕获恢复	完整错误与恢复值一致
完整读取、显式选读	原始值和完整摘要约束	相同语义值；大整数和 null 保留
覆盖已固定的选择	拒绝且无 content	完整错误一致

具体改动 / Changes

审核 head 67bdc6d549006b85b7ecd30bd299cb3cfdfdeee8，对照基线 d1bd9735468d549d55e2965b1b4d9030c50e1854，完整三文件 +72/-6：生产 adapter +4/-1（含三行注释）、测试 +52、同一参考文档的中英说明 +16/-5。当前没有发现需要修改后才能批准的阻塞问题。

关键代码讲解

1. read_context_capture 先读私有物理描述文件，校验原 capture，调用既有 TypeScript selector 并从原 JSON 取值。在成功计算选读摘要之后，新引用写入 select=selectors、initial_read=False；已经固定的引用及直接原文件游标保持各自原路径。选择器、list、摘要等冲突输入仍被拒绝。
2. _capture_page 沿用既有连续 UTF8 字节分页和 next_command。带 reference 的选读页继续使用独立 schema，不能成为完整输入回执；无需为首读新增分页算法。原始文件或选读摘要真的不一致时仍拒绝，不会静默切换视图。
3. write_context_read_reference 是原有不可变 IO owner，保存完整摘要、拒绝覆盖不一致文件。新引用使用早已存在的显式选择形状，原 read_context_read_reference 的私有权限、物理文件、完整格式和摘要限制没有改动。生产入口 model_context_reference.first_read_command 及后续 CLI 均已实际执行。

新增测试分别覆盖 pinned-addresses 与 historical-profile，在同一捕获上改变初始导航，检查新引用完整拼接回原内容，历史引用拒绝后通过原捕获恢复，并逐字节检查原 capture/descriptor 未改写。把当前测试原样放到基线实际源码上，固定地址项在第 172 行失败，历史项通过；当前源码两项均包含在通过的完整 reader 套件中。

独立补充验证通过真正的 CLI main/parser/dispatch、私有物理文件及真实 TypeScript selector 执行两版本各 15 次读取。只把“初始导航参数”显式变为 /criterion，没有 mock selector 结果、摘要、reader IO 或失败。六个场景中五个完整语义观察一致；预期变化仅为新引用从导航配方变成已解析地址，在同一完整 selection SHA 下继续成功。原文件和原描述文件保持不变，所有页的字节连续性独立断言。

规格依据是 docs/reference/required-work-context.md，不可变版本 d1bd9735468d549d55e2965b1b4d9030c50e1854。Selected capture details / 按需读取捕获详情 → implemented：精确路径、完整双摘要、连续 UTF8 字节及选读 EOF 非完整保留的约束均由真实 CLI 和 reader/selector 套件覆盖。Legacy captures retain their original read contract → implemented：旧文件的拒绝、同一捕获恢复、原 Turn 身份和无重新准入/结算保持。完整 diff 前已读 Selected capture details 章节，随后又核对上方 legacy/initial-reader 的原文并比较中英改动；没有把文档改写当成放宽校验的理由。

对主干的风险 / Risks

主要风险是把固定路径误当作新鲜度或权限证明，或为了续读忽略真正的 digest 不一致。实际代码只写派生 IO 元数据，仍由既有完整摘要及 selector 校验防止混读；保存的是当前捕获的一组地址，不是新的 Goal 状态。直接文件、显式选择、历史配方、selector override 和真正损坏引用都保持各自拒绝/恢复边界。没有重新准入、spend、自动安装或实验动作；原生传输关闭时的完整文件读取路线未新增要求。

语义与 CI 对齐

本 PR 复用已有 selection 字段及显式 reader 语义，没有新增枚举、版本或 Python 导航决策 owner。中英说明明确区分“新引用固定地址”和“历史引用仍拒绝”，并保留选读不证明全量输入、原 Turn 对账、恢复及权限限制。历史 decoder 在原未完成 Turn 对账前保留；没有以代码共同发布为由删除持久文件的兼容入口。

• PASS：四个完整模块 test_context_read_reference.py、test_context_capture_selection.py、test_context_capture_read.py、test_context_capture_registry_independence.py，当前 118P/0F/0S、基线 116P/0F/0S。两个新回归的基线敏感性如上；context_selection.test.ts、progressive_context.test.ts 共 12P/0F/0S。
• PASS：source-checkout loopx canary premerge --from-git-diff --git-diff-base d1bd9735468d549d55e2965b1b4d9030c50e1854 完成 6 项直接检查和 19 项选择检查，其中 18 项通过、1 项继承的 maintainability advisory，零 blocking failure/manual hold。包含改动 Python 编译、差异卫生、双语检查及三文件 public-boundary 扫描；目标 Ruff 通过。
• FAIL，独立归因为既有问题：配置的 uv run --extra test mypy 在两版本均为 786 个错误/125 文件，完整 119,338 字节错误输出逐字节相同，报错文件不含本次 reader。对改动模块单独执行 --follow-imports=skip 也均为三个既有错误：native activation 的 Any 返回、capture-root Path 参数及 replan-view 的 Any 返回；相同表达式和所属函数未改动，只因插入三行注释移动了后两处坐标。比较保留完整错误消息、类型及 code，没有用总数相同代替归因，也没有宣称类型检查通过。
• FAIL，继承 advisory：maintainability ratchet 两版本完整 393 字节输出相同，报错 render_canonical_todo_sections 及 checker 均未改变。没有调整预算、删断言或缩小扫描来制造通过。
• UNVERIFIED：CI 按当前策略未查询、未轮询、未等待；已安装 Host、模型采纳、任意历史发行版矩阵及整轮原额度/成本/benchmark 效果未验证。作者历史 111/430 项报告与本次独立 118 项测试不是同一命令，不混称为此次执行结果。

我的整体评价 / Verdict

批准这个精确 head 的引用 IO 修复。真实调用链证明它消除了“原文件未变但自己的续页失效”的导航依赖，又保留全部必要的双摘要、拒绝及恢复约束，达成这个有界故障任务。长程维度判定为 improved，证据限于同一原 Turn 的选读在导航变化后可连续完成；用户体验判定为 improved，沿原 next_command 即可继续，没有新设置、复制、确认或额外交互。没有把读取成功等同于模型采纳、完整保留或 benchmark 增益。

复用既有显式 reader 是同域、可回滚的简化；相比新增导航层或强制全文读取，新增地址元数据和测试成本与已复现的中断相称。兼容旧描述文件有真实未完成 Turn 消费者，因此当前保留合理；未来退役仍须先对账，不需要为本次完整修复制造新的跟进任务。视觉审查为 not_applicable：已检查现有原生 CLI reader、三文件 diff 和文档入口，没有页面或渲染交互改变。已安装 Host、模型采纳、跨任意旧发行版兼容、整轮 benchmark 成本及效果未验证。此批准保留已有类型/结构失败，且不代替独立 merge-readiness 或合并授权；head、selector、描述文件校验或原 Turn 恢复契约变化时应重新审核。

English verdict: APPROVE — 67bdc6d549006b85b7ecd30bd299cb3cfdfdeee8 preserves the exact saved selection across initial navigation changes through the existing reader. Real CLI and reader tests establish the fix; inherited typing/structure failures and unqualified adoption/benchmark scopes remain disclosed.