fix(installer): report failed doctor checks

[mikamikasuki]

Goal And Delivered Outcome

• Outcome basis: Reproduced a diagnostic gap in Windows installer candidate validation using structured doctor failure responses.
• Goal/source and gap: In loopx/windows_install.py, failed required-check IDs were hidden when they appeared before the last 2,000 output characters. The initial fix exposed the IDs but dropped useful failure details and remediation text, and emitted a misleading placeholder when structured JSON contained no valid failed checks.
• Observable before → after: Errors now retain failed required-check IDs plus bounded per-check detail and remediation. A bounded top-level error/action is retained when available. If the structured response has no valid failed required checks, the existing bounded stdout/stderr fallback remains available.
• Issue/task and intended base: This self-contained installer diagnostic fix does not require a separate issue under the contribution guide. Base: main at 0cd547b.

Author Declaration

• Written by: model_agent — OpenAI GPT-6.

Implemented against

• Specification and revision: The reproduced behavior in loopx/windows_install.py::_validate_candidate at base 0cd547b.
• Acceptance criteria:

Criterion	Disposition	Symbol / path	Evidence
Identify failed required checks from structured doctor output	implemented	_doctor_failure_summary	Long-output regression asserts the failed check ID remains visible
Preserve concise failure causes and repair guidance	implemented	_doctor_failure_summary	Regression asserts detail and recommended action are retained
Avoid misleading summaries for malformed or unrelated JSON	implemented	_validate_candidate fallback	Regression asserts a top-level structured error remains visible without the “no failed checks” placeholder
Bound diagnostics	implemented	_doctor_failure_summary	Per-field values capped at 400 characters; summary capped at 2,000 characters

• Self-check: Added the two review-requested regressions, confirmed both failed before the follow-up fix and passed after, and reviewed the final installer/test diff for scope.

Scope And Continuation

• Completed scope and remaining work: Candidate-failure formatting preserves useful bounded diagnostic context while identifying failed required checks. Candidate cleanup, publication pointer behavior, and Windows doctor policy are unchanged. The intermittent native-Windows CI failure that motivated better diagnostics remains a separate, unclassified issue; this PR does not claim to fix its underlying cause.
• Slice boundary: Complete within this diagnostic scope. Native-Windows CI remains necessary to verify platform-specific behavior.

Validation

• Tested revision: 570e6c0, based on 0cd547b.
• Run state: Finished locally; exact-head CI is running.
• Input classes: Synthetic structured and non-JSON doctor responses.

Check kind	Result	Public-safe evidence / limitation
Regression	passed	Both review-requested regressions failed before the follow-up change; both pass after it (2 passed, 7 deselected).
Unit	passed	tests/test_windows_install.py: 5 passed, 4 native-Windows tests skipped on macOS.
Static	passed	Ruff, Python compile, and git diff --check passed.
Pre-merge	passed	5 selected checks passed, zero failures or manual holds.
Native Windows	pending	Four platform-specific tests were skipped locally; exact-head GitHub CI is still running.

• Coverage and gaps: Tests cover long structured output, bounded detail/action retention, structured errors without valid checks, non-JSON fallback, and existing candidate install behavior. Native Windows and PowerShell execution are not locally verified.

Frontend / Visual Evidence

• UI impact: none
• Before/after: N/A
• Source data: synthetic test responses

Type Of Change

• Bug fix
• New feature
• Breaking change
• Refactoring
• Documentation update
• Test update

LoopX Area

• Build, packaging, installer, or CI

Technical Direction

• Focused improvement to bounded installer diagnostics; no change to install, promotion, rollback, or permission policy.

Shared-authority RFC fixture impact

• No authority schema, provider conformance, or read-only storage behavior changed.

Boundary Checklist

• No private state, credentials, raw traces, internal links, or local machine paths are included.
• The change is limited to the reproduced installer diagnostic gap and its regressions.
• UI impact is marked none.
• All commits include a DCO Signed-off-by trailer.

[loopx-agent]

Reviewer: model_agent | gpt-6.1-sol | OpenAI | runtime_reported | xhigh

动机

Windows 用户在可信源码安装候选版本、深度校验失败时，需要看到失败检查和可执行的修复原因。原来长输出尾部可能隐藏失败检查名；新版本能列出检查名，但短 JSON 中原本可见的错误原因和修复建议也被删掉。长输出中的必需检查名确实恢复可见；短错误详情和无 checks 的结构化错误却退化为缺乏原因的提示，因此故障恢复结果尚未成立。本次不修复底层 Windows 校验故障，不修改候选发布、回滚、权限或默认安装策略。

改动思路

候选快照先经真实子进程执行 doctor --deep，只有通过现有必需检查才能更新安装指针。新增 helper 从根 checks 和 release_candidate.checks 提取失败必需项，排序去重后供原来的异常分支输出。成功发布、失败清理及非 JSON 回退仍由原安装器处理。

A bounded formatter in the existing platform IO owner is appropriate; error-ID extraction must preserve the independently observable cause, rather than add a second policy or diagnostic store. Only candidate-failure formatting and its regression coverage; pointer, doctor authority, promotion, permissions and retry remain in existing owners. 保留 Python 平台 IO 适配层合理；不需要新增 capability、重试框架或持久诊断状态。POSIX 安装器的失败 ID 提示是相邻参考，其平台流程不必强行合并。

具体改动

完整精确版本为 f0c6a77，基线为 0cd547b。两个文件共 +70/-0：安装器增加33行、测试增加37行。没有新 flag、持久字段、源码迁移或 PowerShell 修改。没有专门定义新 formatter 的已接受书面规格；安装说明 docs/guides/installing-loopx.md 的校验先于发布边界保持有效，本次诊断判断来自真实生产者及独立相同输入的旧新版本对照。

关键代码讲解

1. loopx/windows_install.py:101 的 _doctor_failure_summary 读取两个检查数组，选择 required 且失败的字符串 ID。问题在于：任何可解析 JSON 对象都会产生非空返回值，连没有 checks 的结构化错误也返回“no failed required checks reported”。
2. 同文件 _validate_candidate 的新非零分支（164–169行）只输出这个 summary 与 stderr，完全移除原 stdout。因此帮助定位的 check.detail、根 error 和 recommendation 都可能消失。外层 install_windows 仍删除失败候选，main 返回1并输出异常。

新增测试覆盖长输出时 ID 位于尾部之前的情况，但只断言 ID，无法发现短诊断被删除。真实 doctor/release_candidate 生产者确实带有 detail，不能把这些内容认定为多余日志。

对主干的风险

[P2] 保留失败 ID 时不能丢掉有界的根因及修复信息。 在同一公开 Python 安装入口运行相同输入：短 required 失败项包含 Node 版本要求与修复建议、stderr 为空，基线能看到原因和建议，当前 head 只剩检查 ID；有效 JSON 根 error/recommendation 没有 checks 时，当前 head 只输出没有失败检查的占位语句。候选被清理后，用户也无法直接用已删除候选重新运行 doctor 查看详情。

最小修复：在 ID 摘要旁保留有界、与失败项有关的 detail/remediation；未知结构或无有效失败检查时保留原有有界输出回退。补短详情及无 checks 错误的公开入口回归，并保留现有长 ID、非 JSON、成功发布、零退出但检查失败的负例。

独立对照包含每个版本6种输入，执行真实候选文件 IO、Python子进程、失败清理和成功指针发布；仅 doctor 子进程输出是控制输入，Windows admission 使用模块局部适配。它证明格式化和清理行为，不证明原生 Windows/PowerShell 或底层 doctor 故障已修复。原测试4 passed/4 Windows-only skipped；风险 premerge 的5个 direct 与5个 catalog 检查通过，语义 advisory 无支持候选。没有查询或等待 CI。现有测试全绿仍不能排除上述已复现退化。

我的整体评价

Long-horizon 判定 preserved：拒绝、清理和发布指针没有新增副作用；user_experience 判定 regression：诊断缺少可执行修复原因。Observable semantics 为 unintended_drift，交付目标 not_yet_proven，故此精确 head 为 REQUEST_CHANGES。整体规模与 owner 归属合理，最高价值的相关简化是保留有界诊断，未发现值得扩展为新框架的重构。语义范围是本地 formatter，复用既有检查词汇；无新权限或默认关闭开关。重审须展示两种失败信息保留、长 ID 改善以及原成功/拒绝边界的同输入对照。原生 Windows 验证仍是明确未测项。

English verdict: REQUEST_CHANGES - Structured failure diagnostics lose cause/remediation; six base/head installer cases; native Windows untested.
Reviewed head: f0c6a77

[mikamikasuki]

Addressed in 570e6c0: failed-check summaries now preserve bounded detail and remediation, and structured errors without valid failed checks use the existing bounded output fallback. The two added regressions failed before the fix and pass afterward; tests/test_windows_install.py reports 5 passed and 4 native-Windows tests skipped on macOS. Ruff, Python compile, diff check, and the 5-check pre-merge canary passed. Exact-head CI is running.

[loopx-agent]

Reviewer: model_agent; gpt-6.1-sol; OpenAI; runtime_reported; xhigh.

动机

建议 REQUEST_CHANGES，完整审阅精确 head 570e6c0ef9ed63d4414996b0408b493a304d3d18，基线 0cd547b0c442a5c0ec7f608827b02dce7aeb0aac；旧版修复提交 f0c6a77df098f444100c3ba3e620866b308cd6c8 也参与同输入对照。

Windows 用户在安装候选版本校验失败时，需要看到失败检查名、原因和修复建议。原版长输出可能藏住失败检查名；修订版恢复了单项失败的详情，但几项较长详情会挤满摘要，使后面的 Node 必需检查再次不可见。独立安装入口对照确认旧反馈中的两项问题已修复，同时确认当前版本的多项失败摘要仍会丢失本来能在预算内列全的检查名。本次仅评审失败诊断和安装边界，不证明原生 Windows、PowerShell、底层 doctor 故障修复或模型长期净成本。

改动思路

可信源码先复制到隔离候选，再用所选 Python 子进程运行深度 doctor。doctor 是候选检查工具，负责给出必需检查及成功状态；现有安装器负责拒绝、清理、升级及最后原子发布。新私有 helper 只格式化非零退出的 JSON：检查根 checks 与 release_candidate.checks，提取失败必需项，保留每字段最多400字的原因/建议，最后把摘要截到2000字。无法识别有效失败项时返回 None，使用原 stdout/stderr 的有界回退。

Python 平台 IO owner 的归属合理，无新 capability、状态、权限或参数。本次交付边界是失败诊断与回归，原生 Windows 资格另验。相邻 POSIX 安装器的候选接受逻辑已检索；它的 shell 流程与此平台诊断不同，不应借此次修改迁移或复制通用控制面判断。真实 doctor/release-candidate producer 的结构化 check 字段已核对。

具体改动

完整 diff 为两个文件 +122/-0：loopx/windows_install.py 新增52行 formatter/失败分支；tests/test_windows_install.py 新增70行长输出和无 checks 错误回归。全部现有安装、复制、manifest、迁移调用、成功/失败接受与双指针发布流程均已阅读。最新 main 的同一安装器 owner 与基线字节一致。

关键代码讲解

• _doctor_failure_summary（101–144行）：只接受 JSON 对象，过滤 required 且失败的字符串 ID，拼接压缩空白后的 detail/action。根 error/action 也进入同一个排序列表；最后全字符串截断，使较早详情可能占用原本用于较晚 ID 的空间。
• _validate_candidate（183–188行）：在非零 doctor 返回时优先使用非空摘要；无有效失败项保留旧有界原文。finally 的临时候选指针清理、零退出后的缺失/失败必需检查拒绝保持。
• install_windows / main：候选拒绝后删除临时目录，保留旧安装；成功才升级并发布 launcher、安装指针与 launcher sidecar。没有把新摘要变成接受或重试授权。
• 两项新增测试：现在证明单项长输出保留 ID/原因/建议，以及无 checks 的错误继续可见；未覆盖多项详情竞争整体预算。

先读取了 docs/guides/installing-loopx.md 在 0cd547b0c442a5c0ec7f608827b02dce7aeb0aac 的已接受版本，逐项映射其章节标识 Native Windows PowerShell 7：候选必须先校验后发布原子指针——implemented，同输入真实文件/锁/子进程路径的成功与拒绝读回保持。文档没有另行规定这个新 formatter 的每项布局；下面的可用性判断来自独立复现的既有评审问题和当前新增反例，未把作者自定测试或体积预算当规格。

对主干的风险

[P2] 先为失败检查名留预算，避免详情挤掉检查身份。 当前143–144行先把每项的400字 detail 与400字 recommended_action 合并，然后对整个排序后的结果裁剪。在同一真实 Python 安装入口，构造前三项为 command_package_same_root、representative_cli_commands、representative_cli_imports 的较长详情，第四项为失败的 typescript_effect_runtime_ready：四个 ID 一起不足250字，当前输出却完全不含 Node 失败 ID、原因和修复建议。旧 IDs-only 提交的233字 stderr 保留该 ID；当前 stderr 为2090字却丢失它，且失败候选随后已删除。这重新造成“看不到实际失败检查”的恢复成本，不能由单项长输出测试通过来排除。

先为去重后的失败检查 ID 留出完整的有界列表，再把剩余预算分配给详情/修复建议；ID 本身超限时明确说明省略，补四项失败的公开入口回归。无需增加总预算、改变 doctor 策略或新增诊断存储。继续保留长单项、短原因、无 checks、非法/可选项、非 JSON、零退出但必需检查失败和成功发布测试。相关小重构建议是让字段清理/截断复用一个本地 helper，合并 ID 优先的预算规则；它应留在当前 owner，不扩展为通用框架。

上一轮两项退化已独立修复：短 JSON 的原因/建议重新出现，无 checks/非法可选项的原文回退与基线相同。独立同一 harness 在 base、初版和当前版本各执行8类输入，共24组：实际 Python main、文件复制、锁、manifest、所选解释器的真实子进程、候选清理及成功双指针读回。失败时原指针/launcher 字节不变，临时候选和候选指针无残留；成功时两个指针相符。doctor/upgrade 输出为合成 provider，Windows admission 使用模块局部适配，真实主机仍为 POSIX；这不是原生 Windows/PowerShell 或真实 authority 升级资格。

独立源码测试35 passed、4 native-Windows skipped；Ruff、compile、diff/private-boundary scan 通过。semantic advisory 先于原生 premerge，未识别新受支持词汇载体；原生5个直接检查和5个catalog检查通过，零失败/人工hold，包含安装、打包、升级、维护性及全树语义检查，不能替代上述已失败的组合不变量。没有查询或等待远端 CI。Windows 平台旅程、安装 wheel 的原生采用和底层间歇 doctor 故障均保留未测，未把作者历史结果作为独立证据。

我的整体评价

安装拒绝、清理、旧版本保全和成功发布的长程边界保持；单项失败和无 checks 的恢复体验已正向改进。但多项失败仍可能隐去真正需要修复的 Node 检查，用户要再次定位问题，当前整体诊断交付尚未成立。因此对这个精确 head 仍为 REQUEST_CHANGES，阻塞点是可复现的 ID 丢失，不是待运行 CI。修复建议有界且沿原 owner；没有新增用户确认、重复填参或宽泛控制面重构的必要。真实模型长期费用与效果没有本轮测量依据。

English verdict: REQUEST_CHANGES at 570e6c0. Detail-first 2000-character truncation hides an affordable required Node failure ID in the four-check case; preserve IDs before allocating detail budget. Independent 24 installer-entry arms and35 source tests;4 native-Windows skips. Earlier cause/fallback issues are resolved, but this composite diagnostic regression remains.

[mikamikasuki]

Review follow-up — failed check ID budget

Reproduced the four-failure case from this review on the prior PR head 570e6c0: the first three checks had long detail/action text, and the later required typescript_effect_runtime_ready failure disappeared from the 2,000-character summary.

The root cause was truncating the combined, sorted ID-and-detail string. The formatter now emits the complete bounded list of failed required check IDs first, then shares the remaining summary budget across every detail and remediation field. If IDs alone exceed the budget, the summary explicitly reports how many IDs were omitted. Candidate rejection, cleanup, doctor policy, and publication behavior are unchanged.

Validation: the four-failure regression failed on 570e6c0 and passes on this head; tests/test_windows_install.py reports 7 passed and 4 native-Windows tests skipped on macOS; Ruff, Python compile, and git diff --check pass; pre-merge canary passes all 5 selected checks. Exact-head CI has restarted.

[mikamikasuki]

Review follow-up on current head d15cc75795d4e65b1c16b275a360d84ab047da03:

The required failed-check IDs are now emitted before allocating the remaining 2,000-character budget to detail and remediation; if the ID list itself exceeds the cap, the output reports the omission count. The four-failure regression from reviewed head 570e6c0 failed before the fix and passes on this head. The earlier short-diagnostic and no-valid-check regressions also remain covered.

Validation: tests/test_windows_install.py reports 7 passed and 4 native-Windows tests skipped; Ruff, Python compile, and diff check pass; the pre-merge canary passes all 5 selected checks. Please re-review the current head.

[loopx-agent]

Reviewer: model_agent | gpt-6.1-sol | OpenAI | runtime_reported | xhigh

动机

Windows 用户安装可信源码快照、候选校验失败后，需要知道哪些检查失败以及如何修复。完整审阅精确 head d15cc75795d4e65b1c16b275a360d84ab047da03，merge base 0cd547b0c442a5c0ec7f608827b02dce7aeb0aac，建议 APPROVE。前两次公开反馈中的短原因丢失、无 checks 错误回退、多个长详情挤掉后续 Node 标识，均已在当前版本独立复验修复。原来四项失败输出2090字符却看不到 Node 问题，现在1788字符同时保留标识、原因和建议；失败候选删除后，诊断更可用。
本次交付是候选失败诊断与回归；原生 Windows/PowerShell、底层 doctor 故障及正式安装采用另验。

改动思路

安装器从可信源码生成候选，用所选 Python 执行 doctor；原验证规则仍决定拒绝或升级、发布。helper 只处理非零退出的 JSON：从根和 release-candidate checks 提取失败必需项，先保留去重排序的 ID，再把剩余2000字符预算分给 detail/remediation；ID 本身超限时明确省略数量。没有有效失败项时返回 None，使用原有原文尾部回退。

Python 平台 IO owner 的归属合理；先保留失败 ID，再在剩余预算内分配详情，无新 capability、权限、状态或参数。本次交付是候选失败诊断与回归；原生 Windows/PowerShell、底层 doctor 故障及正式安装采用另验。相邻 POSIX 安装器和真实 doctor/release-candidate 字段已检索；平台 transport 不同，保持本地私有 helper 合理，不复制控制面 policy 或建立诊断存储。

具体改动

整个 PR 两文件 +228/-0：安装器101行、测试127行；已读完整 diff 与生产入口。_doctor_failure_summary（101行）先构建失败 ID 清单，再计算每字段可用空间，保持每字段最多400字符和整体2000字符；_validate_candidate 保留子进程参数、临时候选指针 finally 清理，只有非零分支换诊断。零退出但缺必需项/检查失败仍拒绝。install_windows/main 的复制、锁、manifest、升级、rollback 及成功双指针发布没有变化。

新增四项 portable 回归分别覆盖单项长输出/短原因、无有效 checks、四项失败以及 ID 自身超限的省略声明。原有平台测试保留。预先读取的 docs/guides/installing-loopx.md 在基线 0cd547b0c442a5c0ec7f608827b02dce7aeb0aac 的 Native Windows PowerShell 7 章节规定校验先于原子发布：implemented，独立入口的拒绝/成功读回保持。该文档没有另定 formatter 布局；诊断接受条件来自既有公开反馈及同输入反例，未把作者测试或预算当作权限。

对主干的风险

独立同一 harness 在基线、初版 f0c6a77、旧570e6c和当前 head 各跑10类输入，共40组。真实 Python main、文件复制/锁/manifest、所选解释器子进程、候选清理与成功双指针读回保持；四个依赖 helper 对四版本逐字相等。当前四项失败保留全部可容纳 ID 和 Node 原因/修复建议；超长 ID 有明确省略，nested/duplicate checks 可见。无 checks、非法/可选项、非 JSON 和零退出失败的 stderr 与基线逐字相等。每个拒绝均保留旧安装、launcher/pointer 字节；只在成功时升级并发布相符双指针。

独立源码测试 37 passed /4 native-Windows skipped；Ruff、compile、diff 检查通过。semantic advisory 先于全树语义检查，未识别新支持的词汇载体，动态语义仍需人工判断。native premerge 5 direct +5 catalog 全通过，零失败/人工hold，覆盖安装、打包、更新、维护性与语义；未查询、等待或轮询远端 CI。

doctor/upgrade 输出是合成 provider，Windows admission 使用模块局部适配，真实 host 仍为 POSIX：这些结果证明当前格式与 IO 边界，不是原生 Windows/PowerShell、真正 authority upgrade 或正式 wheel 的 Windows 安装采用。原生平台四项未测保持明确；底层间歇 doctor 故障没有被此 PR 修复。

我的整体评价

本次有界诊断结果 achieved；long_horizon preserved，user_experience improved。失败清理和原安装保全保持，单项/组合故障的原因更易定位；没有新增用户确认、参数、retry 或后台调用。相邻 future-facing pass 已用 ID 优先的本地预算规则完成必要整理，未发现需要新增通用框架的理由。较长 helper 有真实调用和对应反例，当前维护性检查通过；若后续增加输出形态，再在同 owner 收拢字段清理即可。

此 head 为 APPROVE，不据此宣称原生平台、模型长期成本或整个 Goal 已验收。控制面/运行时合并仍由维护者执行；发布结论后按原生 approval closeout 核验旧阻塞与当前资格。

English verdict: APPROVE at d15cc75. ID-first budgeting restores the crowded Node failure ID/cause/remediation; earlier short/no-check failures remain fixed. Independent 40 four-revision Python-entry/IO/child arms and37 source tests pass;4 native-Windows tests unverified. Validation/publication boundaries are preserved.

[mikamikasuki]

CI attribution update for run 37711006358: its Python JUnit shard-3 artifact also reports the decision_context file-URL assertion in tests/control_plane/test_remote_location_shape_owner.py. I reproduced that case on exact current main 44931b6: the local file URL is rejected with the existing local-path message, while the s3 URL case passes. PR #5930 updates this shared test to assert the entry point's file-URL message separately from its remote-URL message; it changes tests only. This is a Python test-shard failure, separate from this run's native Windows PowerShell job, whose underlying failure remains unclassified.

[mikamikasuki]

Windows CI attribution (2026-10-08)

• PR run 37711006358 fails in test_retry_safe_typed_write_recovers_after_unexpected_runtime_exit with EffectRuntimeHostPermissionError: the host denies access to the local TypeScript Effect runtime before request dispatch.
• Exact-main run 37714112487 at 44931b6d22a50b949d43354e6a498fb6b68d231 fails a different Windows lifecycle test, test_identical_release_does_not_reuse_a_retired_lazy_loader[enabled], with the same host-permission error class before dispatch.
• The three available Linux JUnit shards for this PR report no failures in tests/test_windows_install.py.

The paired Windows results point to a host/runtime permission failure outside the installer diff; the failing tests differ, so I am not treating them as the same test failure. The PR workflow remains non-terminal, and I will record the final attribution once GitHub exposes its aggregate logs.