Skip to content

Require runtime qualification before preparing macOS preview updates - #9029

Merged
huangruiteng merged 1 commit into
mainfrom
codex/macos-preview-adoption-20261118
Nov 19, 2026
Merged

huangruiteng merged 1 commit into
mainfrom
codex/macos-preview-adoption-20261118

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

User-visible result

A macOS preview update is prepared only when its signed App archive carries the published runtime default that the release tooling supports. The update panel can keep the current workspace open while this channel has no eligible package.

Reproduction and change

The public desktop preview carries a runtime that defaults to the complete Turn envelope. Its updater signature is valid. The current updater prepares that package from the feed and also reuses it from disk without checking its runtime qualification.

The macOS updater now reads the publisher's runtime identity from the signature-verified archive before caching a download, reusing a cache, or replacing the App. The native updater, Python release tooling and standalone installer all read the same supported contract. Historical stable packages can still be prepared. Windows uses its existing separate runtime path.

Validation

  • macOS arm64, pinned updater transport and the public release verification key. On the current base, the signed preview is accepted from both a fresh preparation and its existing cache. On this head, both paths report no eligible package. In both runs the real signed 2.3.0 stable package can be prepared and read back. These runs exercised isolated preparation in a native test harness.
  • Native Rust suite passed 202 tests with 12 opt-in cases skipped. The focused test covers missing and unknown contracts, rejection of the C1 default, acceptance of the supported contract, and retention of the last good cache after a failed write.
  • 40 update-artifact tests passed. A local wheel contained the shared contract and produced a standalone installer with the same policy.
  • The producer rejected the unqualified default on the current source line. The fix requires an independently qualified signed desktop release before users of already-shipped binaries receive it. No publication or installation is part of this PR.

Related installer fix: #9026.

@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

macOS 桌面用户通过现有更新面板准备、重用或应用 main 预览。已发布预览能通过更新签名验证,归档内 runtime 的默认契约却超出当前发行资格。现有版本能直接把它准备成候选。新版本在写缓存、读旧缓存和替换 App 之前检查归档内观测到的契约,保留已发布 stable 的历史兼容路径。本次独立验证覆盖原生资格与更新缓存。

改动思路 / Approach

原生 updater 继续负责验证签名。macOS 适配器从已验证的归档读取 runtime identity,并与 Python 发行工具共用契约数据。当前修复复用既有下载、缓存、错误反馈和安装入口。预览读取归档里的身份记录后才取得候选资格,历史 stable 的已验证签名仍走现有兼容路径。

具体改动 / Changes

精确 head 92c5c61704a1444f67faba0cedfc82eaf6464612,diff base 4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46,7 个文件 +136/-9。逐项复核 signed-preview-qualification、all-native-paths、shared-and-historical-contract。验收约定

关键代码讲解

  • 同一签名归档由 base 准备和读回,新版在资格检查时拒绝,已有缓存指针保留。源码
  • 现有直接应用入口在启动替换前检查已下载的归档。源码
  • Python 加载共用资源,单文件安装器内嵌同一份策略。源码

对主干的风险 / Risks

独立原生验证使用了两个公开、真实签名的归档。已发布预览在新缓存、旧缓存重读和直接资格检查中拒绝,旧指针保留。2.3.0 stable 在两版均可准备和读回。完整 App 更新和 wheel 安装属于尚未独立验证的范围。

语义与 CI 对齐

12 项原生测试通过,2 项重复的可选签名用例跳过,独立组合用例已实际验证两份签名。base 与 head 的 Python update-artifact 测试各 40 项通过。

我的整体评价 / Verdict

同意这个 head 的代码变更。归档签名成立后,三个候选入口还要经过同一发行资格检查。稳定包的历史兼容有公开制品验证,资格缺失时仍保留上一次有效缓存。

English verdict: APPROVE. The signed unqualified preview is rejected across fresh, cached and direct qualification paths, while the historical signed stable archive remains usable. Independent validation covered native cache and qualification, plus 40 Python artifact checks per revision.

@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; host runtime observation unavailable)

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

审阅结论:无阻断性缺陷(APPROVE)。已基于工作树独立完成 Rust 更新器测试、基线与精确头部的反事实对比、13 组 Python 更新/分发测试、uv build 打包与单文件安装器隔离探测,以及安全边界扫描;下面按要求给出完整双语核验记录。

动机 / Motivation

使用 macOS 桌面应用内更新面板或终端 loopx upgrade 通道切换至 main 预览版的桌面用户及维护者。

改动前,公开 desktop-main 渠道的签名更新包(如 0.0.0-main.44258978273.1)虽然能通过 minisign 签名校验,但其内嵌 runtime 的默认契约并未满足当前发行资格(指向完整 Turn envelope),macOS 原生更新器在写缓存、重用缓存和直接应用安装时均会直接接纳该候选;改动后,三条路径都会先从已签名的 .app.tar.gz 内读取 LoopX.app/Contents/Resources/runtime/identity.json,校验 schema_version、source_revision 和 default_contract 是否与 public_default_contract.json 一致,不一致则拒绝准备或安装并返回 update_platform_unavailable,同时保持工作区与上一次有效缓存不被破坏。

未取得当前发行资格(quota_packet)的 macOS main 或带 main. 预发布标签归档不再写入 prepared-app-update、不被 prepared_update::load 复用,也不会进入 install_verified_app 替换当前应用;历史 stable 非预览包保持兼容。

边界说明:本 PR 不发布新的签名桌面预览包、不开启 complete_turn 默认契约、不修改 Tauri 远端 desktop-updater.json feed 结构以实现下载前拦截,也不改动 Windows 更新路径与独立前端文案映射。

改动思路 / Approach

针对“保持桌面预览渠道可用且不放行未达标默认契约”的问题,作者没有额外发明第二套签名机制或前端开关,而是复用 Tauri 原生 minisign 签名校验链路:签名确认归档完整可信后,再由 macOS 适配层解析包内构建时写入的 runtime identity。

将唯一受支持的 quota_packet 默认契约外置为单一份 loopx/cli_commands/public_default_contract.json,由 Rust macOS 更新器在编译期通过 include_str! 读取并由 Python update_artifact 与独立安装脚本共同消费,比在 Swift/Rust/Python 中分别维护三份硬编码常量更不易漂移,无需新增新协议字段或配置开关。

当前 PR 边界收口在 macOS .app.tar.gz 签名验证之后的 qualify_candidate 准入校验(覆盖缓存写入 prepared_update::save、缓存读回 prepared_update::read 与直接下载安装 maintenance::perform)以及共享契约 JSON 打包分发。

  [Signed .app.tar.gz]
          |
          +--> stable (non-main.* semver) -----------------> Ok(()) [historical compatibility]
          |
          +--> channel == "main" OR semver pre "main.*"
                    |
                    +--> inspect LoopX.app/Contents/Resources/runtime/identity.json
                              |-- corrupt tar / symlink / dup / >16KiB / bad rev --> Err("runtime_bundle_invalid")
                              |-- missing or default_contract != PUBLIC_DEFAULT_CONTRACT --> Err("update_platform_unavailable")
                              +-- exact match (quota_packet / v0) --> Ok(()) -> allow save / load / install_verified_app

说明:上方控制流示意图基于精确 head 92c5c61704a1444f67faba0cedfc82eaf6464612 源码梳理,用于辅助理解分支逻辑,不作为实测替代。

同时对照了同契约相关在审 PR #9026(head 6a9894c6909da64c97f4da39ad15ee343b344514,OPEN):两份 PR 在 loopx/cli_commands/update_artifact.py 中的修改行号互不重叠,#9029 提取了共享 JSON 与 standalone_source() 注入位,未发现语义冲突或重复决策 owner。

具体改动 / Changes

本次审查对象为精确 head 92c5c61704a1444f67faba0cedfc82eaf6464612(对比 base 4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46),共涉及 7 个文件(+136 / -9),无新增外部依赖。对照接受契约文档 docs/product/release-readiness.md(修订 4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46 第 284-308 行)逐项评估验收标准:

  • RR-DC-1(desktop_packaging_shared_validator,implemented):public_default_contract.json 抽出 quota_packet / loopx_interaction_contract_v0 唯一数据源;pyproject.toml 将其纳入 loopx.cli_commands package-data;update_artifact.py 改为加载该 JSON 并在 standalone_source() 中将字面量嵌入单文件安装器。uv build 构建出的 wheel 与 sdist 均实测包含该 JSON 且可脱离仓库通过 python -I 导入运行。
  • RR-DC-2(reject_unsupported_before_activate_bind_identity,implemented):macos_update.rs 新增 qualify_candidate,并在三条 macOS 更新主路径接入:prepared_update::save(L78-79,后台准备与终端升级缓存写入前)、prepared_update::read(L161-162,缓存重用与终端重启交接读回前)以及 maintenance::perform(L899-907,直接下载且在 install_verified_app 替换应用前)。(注:受 Tauri desktop-updater.json feed 本身未携带 default_contract 限制,macOS 原生更新器在下载并验证归档后、写缓存或替换应用前完成拒绝;Python 侧则保留下载前拒绝。)
  • RR-DC-3(historical_compatibility_and_scope_boundary,implemented):qualify_candidate 仅对 channel == "main" 或 semver 预发布标识以 main. 开头的版本执行 default_contract 校验,避免本地 prepared.json 改标 channel 为 stable 绕过拦截,同时允许既有 stable 发布包(如 2.3.0、2.4.0)继续准备与安装,未擅自开启 complete_turn 默认切换。

关键代码讲解

  1. bundled_runtime::parse_identity:从 identity_at 拆出的公共身份 JSON 解析器,强制检查 schema_version == "desktop_runtime_bundle_v1" 与 40 位十六进制 source_revision,失败统一返回 "runtime_bundle_invalid",复用于运行时加载与更新包资格准入,避免重复解析逻辑。
  2. macos_update::qualify_candidate:使用编译期嵌入的 PUBLIC_DEFAULT_CONTRACT 校验 .app.tar.gz 中的 LoopX.app/Contents/Resources/runtime/identity.json。明确拒绝非普通文件(如 symlink)、重复条目、大于 16 KiB 条目及非法身份 JSON("runtime_bundle_invalid");缺失身份文件或契约不匹配返回 "update_platform_unavailable"。反事实探针同时实测 ./LoopX.app/... 前缀在 Rust Path 比较下可正常归一化命中。
  3. prepared_update::save 与 prepared_update::read:save 在创建缓存目录与写入字节前执行 qualify_candidate,失败则完整保留既有的已验证 prepared.json 缓存;read 在 minisign 签名校验通过后紧接执行 qualify_candidate,防止升级 App 之前遗留的未达标预览缓存继续进入重启安装交接。
  4. maintenance::perform:手工直接应用路径在命中有效缓存之外的下载分支,在 spawn_blocking 中调用 qualify_candidate 后再调用 install_verified_app;若早期缓存含未达标预览,load(...).ok().flatten() 会安全回落至重新下载并再次被 qualify_candidate 拦截,不会将未达标包送入应用替换。
  5. update_artifact.standalone_source:模块导入时加载同目录 public_default_contract.json,生成单文件安装脚本时将 PUBLIC_DEFAULT_CONTRACT = {...} 字面量内联替换进脚本源码(经 python -I 脱离仓库环境验证可用)。

对主干的风险 / Risks

验证结果与归因

检查项 结果 说明
Rust 工作树全量单测 cargo test --locked(移除代理环境变量) 194 passed / 8 failed / 12 ignored 新增 only_qualified_preview_can_replace_the_prepared_candidate 等 194 项全部 PASS;8 项 maintenance::transfer_tests::* 失败均为 update_unavailable / 未发出请求,经基线 4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46 同命令对照复现完全一致的 8 项失败签名,归因本机 macOS scutil --proxy SOCKS5 代理配置导致未改动的 find_update reqwest 客户端构建失败(pre_existing_unrelated)。
基线 vs 头部 Rust 反事实探针 PASS 基线 4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46 下 prepared_update::save 对未达标 "main" 预览包返回 Ok;头部 92c5c61704a1444f67faba0cedfc82eaf6464612 下缺失/不匹配/main. 改标为 stable/symlink/重复条目/损坏 JSON/非法 source_revision/>16 KiB 均被精确分类拒绝且保留先前有效缓存,历史 "stable" 2.4.0 仍返回 Ok。
Python 更新与分发测试(13 个文件 pytest) 511 passed / 13 skipped / 13 subtests passed 13 项跳过仅限 Windows 专属用例(os.name != "nt")及需外部 macOS AppKit fixture 的可选用例,核心更新制品、安装、打包构建与升级测试全绿。
uv build 打包与 python -I 隔离安装脚本探针 PASS 验证 wheel 与 sdist 均包含 public_default_contract.json,可脱离源码目录运行 standalone_source()。
ruff check / mypy / loopx check --scan-path PASS ruff 与 mypy(仓库配置 17 个文件)零错误,7 个改动文件公私边界扫描零告警。
loopx canary premerge(standard,origin/main 为基准) 直接检查 6/6 PASS;Catalog 10 项全核验 5 项当场 PASS;3 项(cli-output-budget-regression-smoke.py、codex-cli-packaged-install-smoke.py、install-local-smoke.py)因多并发负载触发 120s Runner 超时,随后独立执行全部 PASS(rc=0);semantic-vocabulary-drift-smoke.py 在链接 node_modules 后 PASS;1 项 advisory 检查(control-plane-maintainability-ratchet-smoke.py)在干净 origin/main 上同样报既有 _admitted_interaction_next_cli_actions(未触及文件)。

风险分析与未覆盖边界

  1. 下载后拦截边界:由于远端 desktop-updater.json feed 未携带 default_contract,若远端 main 渠道挂着不合格预览包,macOS 客户端仍会先完成一次下载与签名验证,随后在 qualify_candidate 返回 update_platform_unavailable 并中止安装。该行为不污染磁盘缓存或已安装 App,属预期设计边界。
  2. 历史 stable 放行假设:channel != "main" 且版本非 main. 预发布时跳过 identity.json 校验;这依赖已有构建期门控保证新打包的 stable 桌面包本身已满足契约。
  3. 尚未本地实测的端到端场景:依赖真实外部签名归档与独立 APFS/HFS+ 卷的 #[ignore] 替换测试(real_release_*、signed_release_cache_is_reverified_after_reopen_and_rejects_tampering)以及在无系统 SOCKS5 代理环境下执行 maintenance::transfer_tests 仍属 UNVERIFIED。
  4. 未阻断合并的非缺陷观察:update_artifact 与 Rust 校验共同守护 PUBLIC_DEFAULT_CONTRACT(词表属于 reuse_existing,未引入新协议枚举或状态字段);当前主干分支合入状态在 GitHub 显示 BEHIND 且待常规合并门禁检查。

我的整体评价 / Verdict

本次改动范围克制、边界清楚、与仓库既有双语验收文档及 PR #9026 契约共享方案高度协同:把桌面预览包的运行时默认契约资格闭环到了 macOS 原生更新器的缓存写入、缓存重读与直接安装全部三条路径,同时保留了历史 stable 包兼容并避免在失败时破坏现存工作区与上次有效缓存。

  • 长程与用户体验评估:long_horizon 为 preserved(不合格预览包不会跨重启污染 prepared-app-update 缓存或把应用替换到不兼容版本);user_experience 为 improved(用户在面板停留当前工作区并收到既有 update_platform_unavailable 状态)。
  • 视觉与 UI 边界(visual_review: not_applicable):PR #9029 的 7 个改动文件仅涉及 Rust 桌面更新后端、Python 更新构件模块、契约 JSON 与 pyproject.toml,未更改前端 TSX/HTML/CSS 或 boot.js 渲染界面,现有错误码提示路径复用既有映射。 未触发图形界面或前端布局变动,未单独运行浏览器端到端桌面更新面板渲染截图。
  • 架构与工作量结论(retain):将唯一受支持的 quota_packet 默认契约外置为单一份 loopx/cli_commands/public_default_contract.json,由 Rust macOS 更新器在编译期通过 include_str! 读取并由 Python update_artifact 与独立安装脚本共同消费,比在 Swift/Rust/Python 中分别维护三份硬编码常量更不易漂移,无需新增新协议字段或配置开关。 当前 PR 边界收口在 macOS .app.tar.gz 签名验证之后的 qualify_candidate 准入校验(覆盖缓存写入 prepared_update::save、缓存读回 prepared_update::read 与直接下载安装 maintenance::perform)以及共享契约 JSON 打包分发。 词表选择上属于复用既有契约(reuse_existing),无新状态/协议词表漂移。
  • 未覆盖范围声明:远程 GitHub Actions CI 未等待(wait_for_ci: false);本地 8 项 maintenance::transfer_tests 在 4a0188c1ca 与当前头均受本机 scutil SOCKS5 代理影响呈同源失败;真实签名外部安装包体积跨卷替换测试按 #[ignore] 保持跳过。

English verdict: APPROVE. Verified exact head 92c5c61704a1444f67faba0cedfc82eaf6464612 closes the macOS preview qualification gap across prepare, cache readback, and direct apply while preserving historical stable compatibility and existing valid caches, with full independent Python/build/boundary validation and baseline-matched counterfactual attribution.

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
@huangruiteng
huangruiteng force-pushed the codex/macos-preview-adoption-20261118 branch from 92c5c61 to 0673655 Compare November 19, 2026 06:44

@huangruiteng huangruiteng left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · GPT-5 · OpenAI · self_reported

审批结论 / Approval conclusion

动机 / Motivation

macOS preview 更新即使签名有效,也可能携带当前不支持的 runtime default。基线会从新下载和已有 cache 两条路径接受这种 preview;候选在缓存、复用或替换 App 前读取签名归档中的 runtime identity。

  • affected_caller_or_operator: macOS desktop preview users and release/installer operators preparing updates.
  • before_after_scenario: The public preview defaulting to complete-Turn was accepted on the baseline from fresh and cached paths; the candidate returns no eligible package while the signed 2.3.0 stable package remains preparable.
  • observable_outcome: Rust 202 passed with 12 opt-in skips; Python update/release tests 44 passed; install-local, packaged CLI and update smokes pass.
  • non_goals: Does not publish, install or promote an update; Windows keeps its existing updater path.

改动思路 / Approach

reason: One shared contract plus a provider-local archive reader matches the deployment boundary. current_pr_boundary: Qualification before cache/replacement; publication and actual promotion remain separate.

macOS updater 使用已有的签名验证结果,读取有界的 runtime/identity.json 并比较 default_contract。Python publisher 与 standalone installer 读取同一个 JSON,因此 native 与发布侧不再各自维护期望值。

具体改动 / Changes

关键代码讲解

  • qualify_candidate 对 main/preview archive 校验 runtime identity,对历史 stable 保持兼容。
  • prepared_update::save 在发布 cache 指针前完成资格门禁,失败时保留 last-good cache。
  • PUBLIC_DEFAULT_CONTRACT 从共享 JSON 读取并嵌入 standalone installer;Rust 同步使用该文件。

对主干的风险 / Risks

最强反例是 parser 错误接受畸形 identity,或过严拒绝有效 stable。缺失、重复和超限 identity 均 fail closed;stable/qualified-preview controls 保持可更新。202 个 Rust tests、44 个 Python tests 和三项安装/更新 smoke 通过。

我的整体评价 / Verdict

该改动把“签名有效”与“runtime 可发布”分开,并在真正产生 cache/App 副作用之前执行检查。共享 contract 避免了 Python 与 native 漂移,作用范围与现有 updater 边界一致。

English verdict: APPROVE for 0673655. Signed macOS preview updates are now runtime-qualified before cache or replacement, while stable compatibility and last-good recovery remain intact.

@huangruiteng
huangruiteng merged commit 036a95f into main Nov 19, 2026
28 of 58 checks passed
@huangruiteng
huangruiteng deleted the codex/macos-preview-adoption-20261118 branch November 19, 2026 06:57
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.

2 participants