Skip to content

fix(desktop): stage and verify AppImage replacements - #21621

Open
juliusmarminge wants to merge 5 commits into
mainfrom
desktop-app-12/appimage-replacement
Open

juliusmarminge wants to merge 5 commits into
mainfrom
desktop-app-12/appimage-replacement

Conversation

@juliusmarminge

@juliusmarminge juliusmarminge commented Oct 19, 2026 •

Copy link
Copy Markdown
Member

A failed cross-filesystem AppImage update can remove the installed executable before the downloaded replacement finishes copying. Stage the replacement beside its destination, verify release size and SHA-512, set executable permissions, sync it, and commit with one rename. Cleanup runs after the commit and preserves aliases of the installed file.

This is the file-replacement layer rebuilt from @MarMarLabs's #20117. The dependent layer activates it in electron-updater. The original identified the failure correctly; the rebuild keeps its verified staging behavior and drops the separate shutdown/telemetry drain work.

Stack: #21622 is the dependent integration layer.

Verification:

  • This layer: 15 passing tests in the existing ElectronUpdater.test.ts (5 existing + 10 behavioral cases). Removing SHA verification makes the corruption regression fail.
  • The complete stack: 22 passing updater tests, plus 43 passing existing desktop update/lifecycle tests; desktop typecheck, scoped lint, and formatting pass.
  • Real Linux mount-namespace proof uses the actual AppImageUpdater.install with 40 MiB executable fixtures, separate tmpfs filesystems, and real ENOSPC. Stock updater leaves a 24 MiB partial executable that cannot run; the rebuilt stack keeps the runnable 40 MiB old executable and complete download. A separate real bind-mounted cache test verifies that cleanup preserves the committed executable.
cross-filesystem ENOSPC: stock installedBytes=25165824 oldAppRuns=false
cross-filesystem ENOSPC: rebuilt installedBytes=41943040 oldAppRuns=true
bind-mounted cache alias: rebuilt newAppRuns=true destinationSurvivesCleanup=true

The live fixtures are shell executables, not packaged Electron/FUSE AppImages. Packaged Linux success/failure, real Electron shutdown/relaunch and single-instance locking still need human qualification before landing. macOS, Windows, iOS, Android and Electron desktop UI were not exercised. This nonvisual filesystem change has test/CLI evidence instead of screenshots.

Staging always copies the download so a later verification, sync, or final-rename failure leaves the cached download available. This requires another AppImage-sized allocation even on one filesystem, and copy/hash/sync run synchronously during installation. Rename-first staging would need rollback handling to preserve a valid cache after later failures; that optimization is outside this repair.

Two independent full-stack review rounds (Claude Opus 5.5 and GPT-6-Sol) found no remaining code defects. The full-copy allocation/I/O cost is accepted and documented; packaged qualification remains a landing gate.

Implementation and tests: GPT-6.1-Sol and GPT-6-Astra through Codex in T3 Code; independent review: Claude Opus 5.5 and GPT-6-Sol in T3 Code.

Closes #10685

Rebuilt from #20117 by MarMarLabs to preserve the installed AppImage until a verified replacement can be committed.
@github-actions github-actions Bot added the vouch:trusted Author is trusted by repo permissions or the VOUCHED list. label Oct 19, 2026
@juliusmarminge juliusmarminge changed the title desktop app 12/appimage replacement fix(desktop): stage and verify AppImage replacements Oct 19, 2026
@juliusmarminge juliusmarminge added the macroscope-review Opt PRs made by unvouched contributors in for Macroscope review. Vouched contributors auto-reviews label Oct 19, 2026
@github-actions github-actions Bot added the size:L 100-499 changed lines (additions + deletions). label Oct 19, 2026
@macroscopeapp

macroscopeapp Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Approvability

Verdict: Needs Human Approval

Macroscope's review found this PR requires human approval — The helper stages and verifies AppImage replacements before atomic installation. Its new file-level static-analysis suppression requires human review to confirm the exception is justified.

You can add or adjust custom eligibility rules. Learn more.

@coderabbitai

coderabbitai Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The change adds installAppImageUpdate to validate a downloaded AppImage, stage and verify it beside the destination, and replace the destination. Filesystem-backed tests cover successful installs, validation and commit failures, path aliases, and cleanup failures.

Changes: AppImage Update Installation

Layer / File(s) Summary
Validate and commit the replacement
apps/desktop/src/electron/AppImageInstall.ts, apps/desktop/src/electron/AppImageInstall.test.ts
The installer selects a destination, validates the download, stages it on the destination filesystem, verifies its size and SHA-512 digest, sets executable permissions, syncs it, and renames it into place. Tests cover stable and versioned destinations, success, and pre-commit failures.
Sync and clean up after replacement
apps/desktop/src/electron/AppImageInstall.ts, apps/desktop/src/electron/AppImageInstall.test.ts
After replacement, the installer syncs the destination directory and removes obsolete paths best-effort. A directory-sync failure retains the prior AppImage and cached installer. Tests cover path aliases and cleanup and sync failures.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant installAppImageUpdate
  participant installerPath
  participant StagedFile
  participant Destination
  installAppImageUpdate->>installerPath: check file size
  installAppImageUpdate->>StagedFile: copy and verify staged file
  installAppImageUpdate->>StagedFile: set permissions and sync file
  installAppImageUpdate->>Destination: rename staged file into place
  installAppImageUpdate->>Destination: sync directory and remove obsolete paths
Loading

Suggested reviewers: wladefant, macroscopeapp

Merge Risk: Minimal · up to 0fd40

This change adds a staged, verified AppImage replacement helper that is not yet used in production. The installed executable is left intact when verification or the commit rename fails. No actionable merge-blocking risk is identified, and packaged-app validation is still pending in the dependent integration PR.

Pre-merge checks: Passed 3 · Inconclusive 1

Failed Failed checks: 1 inconclusive

Check name Status Explanation Resolution
Linked Issues check Inconclusive Issue #10685 requires that a failed AppImage install not destroy the working executable, that the replacement be verified against the downloaded artifact, and that the install step be diagnosable.

Ad…
Provide current review evidence for PR #21622, or confirm in its head that installAppImageUpdate replaces the stock electron-updater install path in production code. Show that the install step emits diagnostic log lines (install start, veri…
Passed Passed checks: 3 passed

Check name Status Explanation
Title check Passed The title "fix(desktop): stage and verify AppImage replacements" matches the main change: the new installAppImageUpdate helper stages the download beside the destination, verifies size and SHA-512, an…
Description check Passed The description follows the template's main sections: Problem, Change, Scope, and Verification. It explains the failure, the staged and verified replacement, the linked issue (#10685), and the depende…
Out of Scope Changes check Passed The whole-PR changes (merge base 66ca7cd to head 0fd401a) are limited to apps/desktop/src/electron/AppImageInstall.ts (new installAppImageUpdate helper and private helpers) and AppImageInstall.test.…
Full details: Title check

Explanation

The title "fix(desktop): stage and verify AppImage replacements" matches the main change: the new installAppImageUpdate helper stages the download beside the destination, verifies size and SHA-512, and commits with one rename. It is a conventional commit title in plain language, consistent with the template example, and it names the affected component (desktop).

Full details: Description check

Explanation

The description follows the template's main sections: Problem, Change, Scope, and Verification. It explains the failure, the staged and verified replacement, the linked issue (#10685), and the dependent stack PR (#21622). Verification lists specific test counts, a Linux mount-namespace proof with observed output, and states what was not exercised. The Scope section is only partly addressed: it cites the predecessor PR and closes the issue, but does not explicitly say why this bug fix needs no separate issue or whether a maintainer requested the rebuild. The template's agent-model footer is present. The description is mostly complete and in line with the template.

Full details: Out of Scope Changes check

Explanation

The whole-PR changes (merge base 66ca7cd to head 0fd401a) are limited to apps/desktop/src/electron/AppImageInstall.ts (new installAppImageUpdate helper and private helpers) and AppImageInstall.test.ts (filesystem-backed tests). Both directly implement the staged, verified, rename-based replacement described in #10685. The tests cover the objective's behavior: size and SHA-512 verification, executable mode, failure preservation of the installed image and cache, symlink and mount-alias cleanup, and directory-sync failure. The PR description states that the separate shutdown and telemetry drain work from #20117 was dropped, and no such changes appear in the summary. No unrelated changes were identified.

Full details: Linked Issues check

Explanation

Issue #10685 requires that a failed AppImage install not destroy the working executable, that the replacement be verified against the downloaded artifact, and that the install step be diagnosable.

Addressed in this PR (helper layer, verified at head in apps/desktop/src/electron/AppImageInstall.ts, function installAppImageUpdate):

  • Staging: the download is copied to a private directory beside the destination (same filesystem), so the final step is one renameSync. [#10685] Partially addressed on its own.
  • Verification: size is checked against the release size and the staged copy's size and SHA-512 are checked before rename. [#10685] Addressed in the helper.
  • Old file retained until commit: the old AppImage is not unlinked before the rename. Cleanup runs only after the rename and directory sync. [#10685] Addressed in the helper.
  • Executable mode is set and synced before rename. Supporting behavior.

Not established by this PR alone:

  • Production wiring. Per the PR objectives and description, the helper is imported only by AppImageInstall.test.ts at this layer. The stock electron-updater install path in ElectronUpdater.ts is not replaced here. Integration is in dependent PR [#21622]. Stack review evidence is unavailable, so this integration cannot be confirmed. Stack status for the install-path objective: Uncertain.
  • Diagnosability: the helper logs only cleanup and directory-sync failures. It emits no log line for the install step itself or for the successful replacement. The issue asks for install logging and wiring of the updater logger into the trace. Whether #21622 provides this cannot be established from the available evidence.

No coding requirement is shown to be contradicted. The outstanding items depend on the unavailable dependent-stack evidence.

Resolution

Provide current review evidence for PR #21622, or confirm in its head that installAppImageUpdate replaces the stock electron-updater install path in production code. Show that the install step emits diagnostic log lines (install start, verification result, commit result, and failures) and that the updater logger reaches the trace. Then reassess the install-path and diagnosability objectives. Packaged-app qualification is also required by the PR description; it is not a coding check here.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 4f41f68 and 0fd401a.

Files selected for processing: 2

  • apps/desktop/src/electron/AppImageInstall.test.ts
  • apps/desktop/src/electron/AppImageInstall.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.

Wladefant

This comment was marked as spam.

@t3dotgg
t3dotgg dismissed Wladefant’s stale review November 8, 2026 23:27

Dismissed: unsolicited automated review from a blocked account.

@pingdotgg pingdotgg deleted a comment from Wladefant Nov 8, 2026
@juliusmarminge juliusmarminge added the takeover:in-progress A takeover lead is working on this PR label Nov 14, 2026
juliusmarminge and others added 2 commits November 14, 2026 20:50
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Main rewrote ElectronUpdater.test.ts around the real electron-updater, so
the helper's tests get their own file and mock copyFileSync instead of a
test-only copyFile parameter. Overlapping failure cases are folded into one
table.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added size:M 30-99 changed lines (additions + deletions). and removed size:L 100-499 changed lines (additions + deletions). labels Nov 14, 2026
@juliusmarminge

Copy link
Copy Markdown
Member Author

The automated pipeline stopped on this pull request and will not merge it:

in the real app the problem is still there, and the rework changed nothing:

No code change. The reported failure is electron-updater's stock AppImage install path, which this layer does not change. On 4f41f68, installAppImageUpdate is imported only by AppImageInstall.test.ts. ElectronUpdater.ts and the rest of production never call it; the wiring is the dependent PR #21622, as this PR's scope already states. The packaged build therefore still runs electron-updater's own install, which deletes the old AppImage and then copies the new one. That produces exactly the reported 16,777,216-byte, mode-0700 partial file, and it is why both proof builds behaved identically. To check that the helper is right for this scenario, I mounted a real 16,777,216-byte tmpfs as the install directory, put a 315,634,226-byte update with a matching SHA-512 in a cache on ext4, and called installAppImageUpdate with the real fs. The staged copy hit ENOSPC and the helper threw. The installed AppImage was left as it was (mode 0755) and still ran (exit 0), the private staging directory was removed, and the cached download stayed complete. Packaged-app proof that #10685 is fixed has to run on a build that includes #21622's integration.

It stays open for a person to finish or close.

@juliusmarminge juliusmarminge added takeover:blocked Takeover blocked; reason in the PR body and removed takeover:in-progress A takeover lead is working on this PR labels Nov 14, 2026
@juliusmarminge juliusmarminge added takeover:in-progress A takeover lead is working on this PR and removed takeover:blocked Takeover blocked; reason in the PR body labels Nov 22, 2026
…succeeds

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added size:L 100-499 changed lines (additions + deletions). and removed size:M 30-99 changed lines (additions + deletions). labels Nov 22, 2026
@juliusmarminge juliusmarminge added takeover:needs-julius Takeover done; route gate says Julius decides and removed takeover:in-progress A takeover lead is working on this PR labels Nov 22, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

macroscope-review Opt PRs made by unvouched contributors in for Macroscope review. Vouched contributors auto-reviews size:L 100-499 changed lines (additions + deletions). takeover:needs-julius Takeover done; route gate says Julius decides vouch:trusted Author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

AppImage auto-update leaves a 0-byte binary and the app never launches again

2 participants