Repository navigation
Fix archive rollback with custom install directories - #9066
loopx-agent wants to merge 1 commit into
Conversation
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · Gemini · Google · self_reported
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
动机 / Motivation
通过 LOOPX_BIN_DIR 或 LOOPX_RELEASES_DIR 将归档版 LoopX 安装到自定义目录、并执行 loopx update --rollback 的运维人员或自动化脚本。
修改前,即便安装时指定了自定义 bin 与 releases 目录,执行 loopx update --rollback previous 仍只扫描默认 ~/.local/share/loopx/releases 导致报错找不到旧快照(或在仅自定义 LOOPX_BIN_DIR 时误改默认 ~/.local/bin/loopx 并返回成功);修改后,当未传入显式 home 时,回滚直接读取 LOOPX_BIN_DIR 与 LOOPX_RELEASES_DIR 定位快照与 launcher,空值或未设置时保持默认路径,且互不污染。
在自定义目录布局、仅自定义单一目录、空环境变量回退及兼容性拒绝/Doctor 失败恢复路径上,loopx update --rollback 均能准确选中目标快照、保护已有 Goal 与 Todo 权威状态、并原子切换或回滚对应的自定义 launcher,同时完全不触碰默认 ~/.local/bin/loopx。
本 PR 不修改或回滚伴生辅助入口 loopx-apply-rrule(已明确交由配套 PR #9007 处理),不新增全局持久化安装位置配置,也不实现原生 Windows 自动归档回滚。
改动思路 / Approach
安装脚本 scripts/install-local.sh 已长期使用 LOOPX_BIN_DIR 与 LOOPX_RELEASES_DIR 决定归档快照目录与启动器位置,且 execute_update_plan 及 update_operation.installation_key 均沿用同样的非空环境变量覆盖语义(空字符串与未设置回退默认值)。本 PR 未新增配置持久化或第二套路径解析器,而是直接在现有属主 _user_loopx_bin 与 _user_releases_dir 中支持环境变量覆盖。
将目录环境变量覆盖直接收敛在既有路径属主 _user_loopx_bin 与 _user_releases_dir 中(home 为 None 时生效),避免在回滚规划与执行路径重复解析或引入新的全局状态文件。
本 PR 仅解决 loopx 主启动器与快照目录在自定义 LOOPX_BIN_DIR / LOOPX_RELEASES_DIR 下的定位与原子切换/回退,明确将伴生 loopx-apply-rrule 联动保留给配套 PR #9007。
正向流程中,CLI 入口在 home=None 时通过 _user_releases_dir 读取 LOOPX_RELEASES_DIR 扫描目标快照,再由 execute_rollback_plan 依次完成目标版本权威兼容性校验、在目标 releases_dir 下持有 .install-guard 锁并校验已注册 Goal 的 Todo 读取、通过 _user_loopx_bin 定位自定义 bin_dir/loopx 完成原子 os.replace,最后运行 doctor 与 extension doctor;负向路径下,缺失自定义释放目录、兼容性拒绝或核心 Doctor 失败分别保持零变更或精确恢复原链接。
具体改动 / Changes
按 scripts/install-local.sh(基线 5cfd6ae7d571f2f97da40982db23f76540723c89)既定安装契约逐项映射如下:
| Criterion | Disposition | Symbol / Path | Validation |
|---|---|---|---|
| INSTALL-LAYOUT-ENV | implemented | loopx/self_update.py (_user_loopx_bin, _user_releases_dir) |
test_rollback_cli_preserves_selected_route_and_failure_boundaries + 基线/Head 真 CLI 对照 |
| ROLLBACK-PREFLIGHT-LOCK | implemented | loopx/self_update.py (build_rollback_plan, execute_rollback_plan) |
pytest 226 passed (5 skipped) + 真实 SQLite/兼容性/Doctor 失败探针 |
关键代码讲解
_user_loopx_bin(loopx/self_update.py:335-338):当home is None且LOOPX_BIN_DIR非空时返回Path(bin_dir) / "loopx",否则保留(home or Path.home()) / ".local" / "bin" / "loopx"。home is None守卫使显式传入home的测试(如并发锁恢复测试)不受外部环境变量污染,空字符串""则与 bash${LOOPX_BIN_DIR:-...}一致回退默认路径。_user_releases_dir(loopx/self_update.py:341-344):当home is None且LOOPX_RELEASES_DIR非空时返回Path(releases_dir),否则回退默认~/.local/share/loopx/releases。不会主动创建不存在的自定义目录。build_rollback_plan与execute_rollback_plan(loopx/self_update.py:579, 1457):分别消费_user_releases_dir(home)与_user_loopx_bin(home),并在release_root.parent / ".install-guard"上加锁;这意味着自定义LOOPX_RELEASES_DIR下的并发安装护栏与主更新流程完全对齐,无需改动核心切换/恢复逻辑。test_rollback_cli_preserves_selected_route_and_failure_boundaries(tests/test_self_update_runtime_activation.py:984-1069):移除原本对_user_loopx_bin与_user_releases_dir的 monkeypatch,改为通过Path.home与环境变量测试default(空串"")与configured(含空格自定义目录且校验默认~/.local/bin/loopx不被修改)共 8 组用例。docs/product/release-readiness.md:51-53:补充提示归档回滚时需保留安装阶段使用的LOOPX_BIN_DIR或LOOPX_RELEASES_DIR,与实际 CLI 行为一致且保留全部既有预检与锁说明。
对主干的风险 / Risks
在精确提交 23042c8ff1ec57eebf3e9cdfc54cce6b90b4e249 上未发现阻塞主干合入的缺陷;跨基线对照与本地验证结果如下(远程 CI 未等待,wait_for_ci: false):
| 检查项 | 结果 | 关键观测 |
|---|---|---|
基线回归对照 (5cfd6ae7d571 vs 23042c8ff1ec) |
PASS | test_rollback_cli_preserves_selected_route_and_failure_boundaries 在基线上 4/4 configured-* 全部失败;在 Head 上 8/8 全通过 |
更新/安装/Doctor 单元测试 (pytest) |
PASS | 7 个相关测试文件共 226 passed, 5 skipped(3 个为 Windows 专用用例,2 个为 macOS AppKit fixture 用例) |
静态检查与边界扫描 (ruff, mypy, loopx check, canary premerge --tier quick) |
PASS | ruff 通过;mypy 17 个受控文件通过且改动行零报错;loopx check 3 文件零告警;canary premerge 全部直接检查与 4 项精选检查通过 |
真实 scripts/loopx CLI 与 SQLite 探针 |
PASS | 实测双自定义目录、单变量覆盖(基线曾误写默认 ~/.local/bin/loopx 并返回成功,Head 准确切至自定义启动器)、空串回退、缺失目录零副作用、兼容性拒绝保持原 inode、Doctor 失败恢复原链接,以及真实 sqlite_v0 Goal + Todo 预检与回滚后读回成功 |
非阻塞风险与边界说明:
- 伴生入口与并行 PR 协调:在本 PR 单独合入后,自定义
LOOPX_BIN_DIR下的loopx-apply-rrule仍指向原版本,完整双启动器回滚由开放中的#9007负责;#9007与本 PR 在docs/product/release-readiness.md及tests/test_self_update_runtime_activation.py存在文本冲突,但loopx/self_update.py无冲突且#9007基于_user_loopx_bin(home)与release_root.parent可直接组合。另一并行 PR#9036修改self_update.py的 Python 分发更新分支,与本改动正交;#8966重构self_update.py整体类型。 - 环境变量持久性边界:自定义目录依赖调用方在回滚时显式保留
LOOPX_BIN_DIR/LOOPX_RELEASES_DIR(已在文档声明);纯空白字符环境变量与install-local.sh${VAR:-...}一致按字面路径处理(在找不到目录时安全失败,不误改~/.local)。 - 既有测试遗留:
test_rollback_checks_registered_todo_read_before_switching仍沿用私有 helper monkeypatch,但本次补充的真实sqlite_v0CLI 探针已覆盖该路径。
我的整体评价 / Verdict
本次改动对 long_horizon(保留自定义锁、Todo 预检、原子替换与 Doctor 恢复不变量)保持 preserved,对 user_experience(修复自定义归档目录回滚不可用及单边覆盖误改默认启动器的问题并补齐文档说明)达到 improved。visual_review 为 not_applicable(已核对 loopx/self_update.py、loopx/cli_commands/support_control_update.py 与 docs/product/release-readiness.md,无渲染界面变更;unverified_scope: none,唯一环境跳过项为 Windows 原生与 AppKit 专用测试用例)。
从 observable_semantics 与 code_volume 看,基线对照清晰复现了原有缺陷,Head 在维持默认与空值完全兼容的前提下以最小 4 行生产改动收敛到既有路径属主,未引入新词汇、新状态或兼容性分支(沿用既有环境变量契约),确认为可合入的独立修复切片(审查基于 exact head 23042c8ff1ec57eebf3e9cdfc54cce6b90b4e249)。
English Verdict: APPROVE — exact head 23042c8ff1ec57eebf3e9cdfc54cce6b90b4e249 cleanly fixes custom LOOPX_BIN_DIR / LOOPX_RELEASES_DIR archive rollback in the existing path owners with zero blocking findings, passing local regression parity (226 passed, 5 skipped), premerge checks, and real SQLite/CLI verification.
Goal And Delivered Outcome
Archive installs support custom bin and release directories. Rollback previously searched the default releases directory and resolved the default launcher. It now uses the same directory overrides as installation. An omitted or empty override keeps its existing default.
The configured layout regression fails in all four cases on
5cfd6ae7d571f2f97da40982db23f76540723c89. The fix passes those cases and the four default layout cases. The intended base ismain.Author Declaration
Written by model_agent, OpenAI Codex (GPT-6).
The existing installer directory contract in
scripts/install-local.shand documented rollback preflight indocs/product/release-readiness.mdat5cfd6ae7d571f2f97da40982db23f76540723c89define the scope.loopx/self_update.pytests/test_self_update_runtime_activation.pyScope And Continuation
The rollback selects the snapshot and switches the
loopxlauncher in the configured layout. The isolated rehearsal still observedloopx-apply-rrulepointing at the candidate. Paired launcher recovery is tracked in #9007.Validation
Tested revision
23042c8ff1ec57eebf3e9cdfc54cce6b90b4e249. Run statefinished. Inputssyntheticandpublic_fixture.regression_paritypassedtest_rollback_cli_preserves_selected_route_and_failure_boundariesruns the exact CLI route with configured and default directories. Four configured cases fail on main and pass on the fix. All four default cases pass on both. The cases cover success, compatibility refusal, doctor recovery and extension failure.unitpasseduv run --extra test python -m pytest -q tests/test_self_update_runtime_activation.py tests/test_archive_installer_commit_response.py tests/test_update_artifact.pyreported 138 passed and 3 skipped. Ruff passed on both changed Python files.real_entrypointandreal_backendpassedloopx update --rollback previousswitched the installed launcher back to 2.3.0 and preserved the existing Todo, active lease, stored receipts and configuration. The older launcher read and replayed the candidate's compatible write with no extra revision and performed a fresh write under the original lease. The pre-upgrade backup was verified in a separate destination. Released 2.3.0 archiveintegrationpassedintegrationblockedThe four branch outcomes and the two real providers cover the custom directory scope. Three tests were skipped by the suite. PR review and hosted validation remain separate from the local results.
Isolated integration with #9007
The exact heads
23042c8ff1ec57eebf3e9cdfc54cce6b90b4e249and26aedee3d4624d1fdf2ebbcba91ba5e388b44329conflict in
docs/product/release-readiness.mdandtests/test_self_update_runtime_activation.py. The runtime file merges cleanly.On main
5cfd6ae7d571f2f97da40982db23f76540723c89, the isolated reconciliationpreserved both directory overrides, kept the paired launcher behavior and ran
the joint test across default/configured layouts and absent/present helpers.
The three updater and installer test modules reported 157 passed and 3 skipped.
On macOS, File and SQLite backed the same in-place upgrade from the published
2.3.0 archive to the reconciled source snapshot. With an executable target
helper, both launchers returned to 2.3.0 and the original Todo, lease, receipts
and compatible candidate write remained readable. Replaying the original
operation kept its revision and a fresh write succeeded under the same lease.
Removing execute permission from the target helper refused the switch. A
controlled core Doctor failure and a real SIGINT during target Doctor restored
both owned launchers. A simulated later writer replaced the helper symlink
with a new inode pointing to the same target. Rollback preserved that replacement
and recovered its own primary launcher. All failure cases preserved authority
state in both providers. The reconciled tree was tested locally. The public
2.4.0 archive qualification above remains open.
Frontend / Visual Evidence
UI impact
none. The change is in POSIX CLI snapshot rollback directory resolution.Type Of Change
LoopX Area
Shared-authority RFC Fixture Impact
N/A. This patch changes launcher and snapshot path resolution.
Boundary Checklist