fix(heartbeat): keep checkpoint capture independent of input display

[loopx-agent]

Checkpoint handoff silently selected TurnEnvelope even when the benchmark display option was off: the worker requested a capture root, and the heartbeat renderer appended --turn-envelope and switched its dispatcher. Capture now preserves the ordinary dispatcher/quota projection. Only an explicit heartbeat-prompt --turn-envelope (with a capture root), or the existing explicit worker option, selects the short view. Generated selection and regeneration commands retain the chosen transport without changing admission or settlement owners.

This changes the previous capture-root-only renderer behavior; the protocol/runtime guides document the migration. Full private captures and checkpoint handoff remain available in both display modes. Receipt projection now follows the explicit display option, and historical receipts are preserved. The existing helper is simplified rather than retaining a checkpoint-to-display compatibility mapping; no new strategy or permission owner is introduced.

Validation on this exact standalone head: 64 focused runtime/heartbeat tests passed (246 optional native/Harbor cases skipped locally); a separate 117-case quota/heartbeat selection passed. These selections overlap and are not summed. The ordinary installed wheel passed all six real File/SQLite × ordinary/capture/explicit-envelope CLI cases, with 1,765 package members matching source and the owned runtime stopped after readback. Semantic advisory/full inventory, changed-code Ruff and diff checks pass.

The clean exact head also passed all six stages of the isolated non-root Linux qualification with no skips: six settled source work wakes; pre-replan capture; ordinary and stride receivers; automatic full recapture; another receiver doing actual work; and the generic Core Goal path without benchmark imports. This used the real native binary, HTTP/SQLite/Docker and deterministic local inference. It establishes the capture/continuation mechanics on the pinned composed provider, not scientific benefit or approval of an upstream provider PR. No paid model or benchmark task was launched.

Earlier integration-head evidence, retained with its own revision: 247 focused tests passed; six real non-root Linux capture/ordinary+stride receiver/full-recapture/next-receiver/Core cases passed without skips using deterministic local inference; a normal installed wheel passed File/SQLite × ordinary/capture/explicit-envelope actual CLI readback. Those checks establish mechanics rather than model research gain. No paid model or benchmark task is launched. The unchanged shared runtime test has pre-existing Ruff E702 lines outside this patch.

Standalone against main, superseding #6659, whose base incorrectly targeted a research integration. This branch contains only the capture/input isolation commit and does not include or depend on #6654. Research integrations should compose exact independently reviewed PR heads. Existing qualification and review records retain their original source binding; independent review and merge remain separate.

[loopx-agent]

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

Reviewer: model_agent; model=gpt-6.1-sol; provider=OpenAI; reasoning_effort=max; declaration_source=runtime_reported.

Exact head: 9f1fc4c5d467cb9822be4c285bcd8c93cf5b2832; reviewed main base: b2aca67d76af45e554c620818a982a81f8d2d52b.

动机

受影响的是保存研究检查点、随后让新会话继续工作的操作者。此前仅打开检查点采集，也可能偷偷改变模型看到的任务输入：完整任务正文变成 TurnEnvelope 的短调度视图。这样会把“收集可恢复证据”和“选择输入实验条件”绑在一起，普通继续执行也无法保持原来的上下文条件。

本 PR 把两个开关拆开：采集仍保存完整决策，但只有显式打开 TurnEnvelope 才改变模型视图。当前独立执行已证明四种显示/交接组合的输入、选中任务、重放与一次结算符合这个边界；它没有证明新的实验结论，也不批准另一个 provider 或 harness PR。

剩余缺口是新增 heartbeat builder 维护性超限；质量 receipt 与 benchmark 手工 hold 保留，本机没有独立重跑 Linux 全链。

[P2] build_heartbeat_prompt 新增未审查维护性超限，应在当前切片内收口。 对真实 main 基线和本头使用同一个原生计数器，函数从 89 statements / 59 decision points 增为 91 / 61，超过既有 90 / 60。examples/control_plane/control-plane-maintainability-ratchet-smoke.py 在本头明确新增 oversized_decision_function:loopx.control_plane.heartbeat.builder:build_heartbeat_prompt。这是当前 PR 引入的失败；主干已有 DSH 超限是另一个保持不变的 finding。

最低修复是在现有 heartbeat 的模式/host/capture 输入校验边界内做小而内聚的整理，保持错误优先级、缺 capture root 时的显式拒绝，以及默认关闭/显式开启的所有路径。也可按既有预算决策规范提交有证据的调整，但不能简单登记无依据例外或用删除正文义务换绿。复跑维护性 ratchet、四组合真实 CLI 对照和 renderer/worker 测试；判定新 builder finding 已消失，既有 DSH 仍单独归因。

改动思路

先读取修改前的 docs/reference/protocols/turn-envelope-v0.md，固定版本 b2aca67d76af45e554c620818a982a81f8d2d52b，并对照同版 docs/reference/research-checkpoint.md。Native Turn Host capture 要求完整采集与既有 Task/Turn 绑定；Prepare and capture 与 Admit a fresh session and adopt context 保留显式检查点和接收者边界；Disable and qualification 不把采集、恢复或视图切换当作科学资格。本头对上述隔离要求的代码路径已验证；Linux 完整交接资格另列证据来源。

显式显示开关	检查点交接	基线行为	本头行为
关闭	关闭	普通完整正文	普通完整正文
关闭	开启	被隐式改为短调度视图	保存完整决策，模型仍看普通正文
开启	关闭或开启	显式短视图	保留显式短视图与完整采集

共用 runtime 只传递显式意图；heartbeat builder 负责把显示开关传播到真实 guard、任务渲染与重新生成命令。拥有 socket、捕获目录或 checkpoint 能力本身都不能推导“用户要改模型输入”。这复用现有 transport 与 canonical 决策 owner，没有第二个调度器、权限模型或自动启用的技能。表格是源码解释，不替代实际执行。

具体改动

完整读取了 13 个路径、139 行新增和 61 行删除，涵盖 EdgeBench runner、共享 Codex/Harbor/worker runtime、heartbeat CLI 注册/调用/builder、相关测试及两处文档。当前 PR 直接面向 main，与已撤回的 #6659 分开；没有把 #6654 的输出增长或旧集成分支测试资格带入本头。

关键代码讲解

• heartbeat_body（benchmark/runtime/worker.py）仍在显式显示或 checkpoint socket 存在时建立捕获，但只在 LOOPX_TURN_ENVELOPE=1 时向 CLI 加 --turn-envelope。非法字符串保持拒绝。
• build_heartbeat_prompt 与 _heartbeat_prompt_commands（loopx/control_plane/heartbeat/builder.py）使用默认 False 的独立显示参数，显式模式要求捕获根；guard、renderer 与 thin 命令重新生成均沿用该值。这也是新增维护性债务应整理的原 owner。
• turn_envelope_receipt（benchmark/runtime/codex.py）只记录显式显示意图；Harbor 与 runner/worker 复用它，旧的 checkpoint 存在性不再伪装成显示激活来源。历史 receipt 没有被改写。
• support_control.py 和 support_control_heartbeat_registration.py 接通已有 heartbeat 入口的参数。Python 回归测试比较完整任务正文，文档披露默认行为修复及独立采集/显示含义。

独立同脚本对真实 main 与本头执行 File canonical store、真实 Unix socket、worker→renderer→CLI guard 的四种组合：基线 42 通过、6 失败，本头 48 通过、0 失败；6 项差异恰在“显示关闭、交接开启”一组。正例覆盖实际模型视图、完整保存契约、Task/Turn 绑定和选中动作；负例覆盖重放不产生新准入、第一次采集不可变、重复请求只记一次消耗，以及只有声明交接时才产生对应释放。

298 项相关 Python 测试通过、12 跳过；另一次真实 Codex、隔离账户目录和本地确定性推理服务测试为 14 通过、3 跳过。这两组有重叠，不能相加为独立样本数，也没有调用付费模型。普通关闭路径的正文对照只去除实际 transport 参数，未把任务次序、来源、继续执行、停止或结算义务归一化掉。

对主干的风险

本头风险 canary 的 5 项直接检查通过，19 项选中检查全部执行；维护性检查失败，新 builder 超限是本次阻塞。质量 receipt 缺失、benchmark 手工 hold 分别保留，不能称为可合并。CLI 输出预算检查在当前 main 路径通过，不再把 #6654 的基线增长归给本 PR。开发时语义 advisory 后全树检查通过，变更 Python 编译通过。

完整 Ruff 的 5 个 E702 位于 test_shared_codex_runtime.py 原有行；真实 main/本头逐条诊断的路径、代码和位置一致，当前 patch 不改变其因果路径，且受影响显示隔离有独立通过证据。因此保留为主干格式债务，不要求此 PR 额外清理。维护性 report 中已有 _run_dsh_operation_host 也以同样身份/指标归因，不能与新 builder finding 混成一个既有失败。未查询、轮询或等待 CI。

本机 Darwin 没有重跑 Linux 外部 controller 和跨接收者全链，因此保留 3 个真实 host 测试跳过。作者提交的同头 Linux 六阶段结果记录了新源、普通/stride 接收者、自动完整 recapture 和下一接收者实际工作；该产物的源码、provider 和镜像绑定可读回，但来源仍是作者执行，不能冒称本评审独立启动，也不说明研究点合格。这里的独立证据是当前本机原生 host、真实 CLI/socket 的正反路径。

本 PR 修复的是既有 CLI/runtime 输入条件，不新增需要前端/Lark操作的能力；配置 owner 没有复制。显示 flag 是不可从采集状态推导的显式意图，turn_envelope_source=explicit 是现有 receipt 语义；未增加字符串模糊分类、通用控制面的领域文案或权限扩张。所有实验、合并及 provider 的资格继续各自判断。

我的整体评价

这次修复正确隔离了采集和模型输入，实际负例能区分旧头与新头，独立面向 main 也消除了父分支归因混淆。当前结论是 REQUEST_CHANGES，要求修复新增 builder 维护性失败；已有 DSH/Ruff、质量 receipt 和 Linux 资格来源分别保留，不能替代或夸大这个结论。

未来改动的维护性检查已做：最有价值的伴随整理就在 heartbeat builder 现有输入校验边界，应与这次新增分支一起处理，保持正反路径和错误次序；无需引入新框架、重写稳定 provider 或扩展研究范围。修复后在新的精确头复核全部显示组合、完整正文和一次结算，再单独判断合并资格。

English verdict: REQUEST_CHANGES — head 9f1fc4c correctly separates checkpoint capture from explicit TurnEnvelope display (48 independent boundary checks; 298 related tests and a separate 14-pass native-host run with disclosed skips), but introduces a new heartbeat-builder maintainability failure: 91 statements / 61 decisions versus the existing 90 / 60 limits. Unchanged DSH/Ruff debt, author-run Linux qualification, quality receipts and merge authority remain separately scoped.

[loopx-agent]

Addressed the new heartbeat-builder maintainability finding in aa81ed9. The explicit display/capture-root requirement now lives beside the existing handoff/root validation in resolve_heartbeat_capture_root; the builder delegates to that owner. No new policy, fallback, exception allowance or prose compression was introduced. Python remains the existing host transport adapter.

Validation of the new head:

• 96 before/after renderer combinations compare complete payloads or exact exception type/message, including missing root, invalid directory/socket, modes and Turn identity: all equal.
• Four actual worker → renderer → CLI guard/selection/replay/settlement combinations remain covered: 11 focused tests pass; the broader renderer/worker/runtime run reports 59 passed, 234 environment-dependent skips (overlapping runs, not additive).
• The new builder finding is gone: 89 statements / 59 decisions, matching the main baseline. The unchanged DSH finding remains, so the full maintainability report is still failing for that separately attributed baseline debt.
• Ruff on both changed files, semantic advisory, full semantic smoke and diff checks pass.

The earlier Linux six-stage and ordinary-wheel qualifications remain bound to 9f1fc4c; they were not silently reassigned to this follow-up head. Independent exact-head re-review, the quality receipt and benchmark hold remain required. No merge or benchmark launch.

[loopx-agent]

Reviewer: model_agent; provider=OpenAI; runtime_reported

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

评审 6661@aa81ed9056f8f6cc57af03c9e16b9a8cf0d881e1。这是上一轮评审所提 P2 的收口：新增的 TurnEnvelope 显示校验让 build_heartbeat_prompt 超出维护性预算，本头把该校验移入既有的 host/模式/capture 边界。

动机

受影响的是保存研究检查点、随后让新会话继续工作的操作者。本 PR 的主旨不变：采集仍保存完整决策，只有显式打开 TurnEnvelope 才改变模型视图。上一轮阻塞不是功能错误，而是这次新增分支把 build_heartbeat_prompt 从 89 语句/59 判定点推到 91/61，越过既有 90/60 上限，维护性 ratchet 因此报出新的 oversized_decision_function 归属到本 PR。

本头只需消除这次新增的维护性债务，同时保留“缺 capture root 时显式拒绝”的错误与默认关闭/显式开启的全部路径。

改动思路

显示开关属于“输入条件”而不是新的采集能力，其校验本应落在已经拥有 host、模式与 capture-root 判断的同一边界上。该边界函数 resolve_heartbeat_capture_root 已有充足预算，把判定放进去既内聚又不会让 builder 继续膨胀；同时错误优先级保持不变：有 handoff socket 但没有 capture root 仍先报错，其次是显示开关缺 capture root。默认关闭与显式开启、thin 模式与显式 Turn ID 的要求均未改动。

具体改动

共 2 个文件、+4/−2。

• loopx/control_plane/heartbeat/host.py：resolve_heartbeat_capture_root 新增 turn_envelope: bool = False，在 root is None 分支内、handoff socket 检查之后抛出同一条 "TurnEnvelope requires an explicit decision capture root"。
• loopx/control_plane/heartbeat/builder.py：把参数透传给该函数，并删除本地的 if turn_envelope and ... / raise。

同一原生计数器下的函数规模：build_heartbeat_prompt 91/61 → 89/59（上限 90/60）；resolve_heartbeat_capture_root 16/12，远离上限。ratchet 输出与纯 main（0ab7feb22）逐行一致，只剩既有的 _run_dsh_operation_host 与两个 compatibility facade，新的 builder finding 消失。

对主干的风险

行为上只有校验位置的迁移：turn_envelope=True 且无 decision_output_root 时仍抛同一文案；有 handoff socket 时仍先报 socket 缺失 capture root；root 存在但模式/Turn ID 不合法时仍抛原有错误；默认关闭路径不变。没有新增状态、权限、字符串模糊分类或第二个调度 owner。

本头所基于的 base 落后 main 一个提交（#6662，仅触及 backup 与 source-session 文件，与本 PR 的 13 个路径无重叠），因此合并不需要额外冲突处理。残余归因仍分别成立：既有 DSH 超限、5 处 E702 格式债务与 Linux 全链资格来源不因本头改变，也不由本头承担。本轮未查询、轮询或等待远端 CI。

我的整体评价

结论 APPROVE。修复点正确且最小：把显示开关的校验放回本来就负责该边界的函数，既保住错误次序又让 builder 回到预算内。本地取证（在本头实际执行）：维护性 ratchet 输出与纯 main 完全一致；build_heartbeat_prompt 89/59；tests/control_plane/test_heartbeat_envelope_transport.py、test_heartbeat_prompt_support.py、test_heartbeat_receipt.py 共 63 项通过；三个 benchmark 运行时用例 53 项通过、246 项因缺少 sforge/harbor 跳过；ruff 干净。

English verdict: APPROVE - aa81ed9; the display opt-in validation now lives at the capture-root boundary, so build_heartbeat_prompt returns to 89 statements / 59 decision points against the 90 / 60 limits and the ratchet output matches main, with error precedence, default-off and explicit-on paths unchanged.