Improve macOS update flow so payload updates are the default

[TheAngryPit]

Summary

Aegis here, working with @TheAngryPit.

macOS updates can still feel like a first-install DMG flow instead of an app-owned update flow. In our recent stable update path, Open Design prompted for an update, downloaded a DMG, mounted it, and left the user to drag Open Design.app into /Applications and confirm Replace manually.

That is workable as a fallback, but it should not be the default product experience for a daily-use desktop app.

Observed behavior

Across multiple macOS updates, the update experience has not landed on the payload path:

• older updates sent the user back to the site to download the DMG manually
• the latest flow downloaded and mounted the DMG, then required a manual drag-and-replace install
• the in-app prompt behaved like "open installer" rather than "install and restart"

Code and release-feed findings

From the current code and release metadata:

• apps/desktop/src/main/updater.ts supports a payload artifact path.
• The current stable release metadata for 0.11.0 publishes both dmg and payload artifacts for macOS.
• selectUpdateCandidateWithFallback(...) prefers payload only when hasValidLauncherPayloadContext(...) passes.
• If launcher context is absent or invalid, the updater falls back to the DMG.
• capabilitiesFor(...) still reports package-launcher updates as requiresManualInstall: true even when the selected artifact is payload-capable.

That means the product has the pieces for app-owned payload updates, but the user-visible update model still makes manual installer behavior too easy to reach and too unclear when it happens.

Proposed product direction

Default behavior:

• Prefer payload updates automatically whenever the release metadata includes a compatible payload and the launcher context is valid.
• Show payload updates as "Install and restart", not "Open installer".
• Treat DMG as a manual fallback only.

Fallback behavior:

• If the app must fall back to DMG, say that clearly in the UI: "Manual update required" or equivalent.
• Explain why the user is seeing a manual flow, for example missing launcher context or unavailable payload.
• Avoid making the DMG fallback look like the normal update experience.

Advanced preference:

• Add an advanced Settings option for update install mode:
  • Automatic, recommended: prefer payload, fall back to manual installer when required
  • Manual installer: always use the installer/DMG flow
• Keep Automatic as the default.

Suggested implementation shape

Small PR first:

• Model updater capabilities from the selected artifact, not only from package-launcher.
• Ensure payload updates report app-owned install/restart semantics.
• Ensure installer/DMG updates report manual-install semantics.
• Add focused tests for payload vs DMG capability and UI copy.

Follow-up PR if maintainers agree:

• Add the advanced Settings preference and persist it through the existing app-config path.
• Thread that preference into desktop updater candidate selection.

Why this matters

For a local-first agent-native app, update UX is part of trust. Users should not have to think about mounted DMGs and app replacement during routine updates unless the automatic path is genuinely unavailable.

[lefarcen]

Hi @TheAngryPit! The write-up is very clear, and the current updater split does line up with what you're seeing. In apps/desktop/src/main/updater.ts, payload selection is already gated by launcher-context validation, but capabilitiesFor(...) still exposes package-launcher updates as manual installer flows, which is why the UI can drift back toward "open installer" semantics even when a payload is available.

PR #4471 looks like the right scoped first step for that mismatch, so let's track the artifact-aware payload behavior there and keep this issue open for the broader fallback UX/settings follow-up you outlined.

[lefarcen]

Hi @TheAngryPit! The write-up is very clear, and the current updater split does line up with what you are seeing. In apps/desktop/src/main/updater.ts, payload selection is already gated by launcher-context validation, but capabilitiesFor(...) still exposes package-launcher updates as manual installer flows, which is why the UI can drift back toward "open installer" semantics even when a payload is available.

PR #4471 looks like the right scoped first step for that mismatch, so lets track the artifact-aware payload behavior there and keep this issue open for the broader fallback UX/settings follow-up you outlined.

[cbeaulieu-gt]

/claim

[lefarcen]

Hey @cbeaulieu-gt, really appreciate you picking this up. Roughly how long do you think it'll take from here — a few hours, 1–3 days, around a week, or longer? That’ll help us time check-ins well.

[cbeaulieu-gt]

Thanks @lefarcen — happy to take the follow-up. One important caveat up front on testing, since this is macOS-specific updater behavior:

What I can do (on Windows): author and fully unit/component-test the cross-platform parts — the Advanced Settings "update install mode" toggle, persisting it through app-config, and the clearer DMG-fallback copy. I can also exercise the candidate-selection decision path (payload vs installer) against the deterministic tools-serve start updater fixture, so the preferPayload override logic is verifiable without real releases.

What I can't do: the final macOS-native acceptance — actual payload extraction, the DMG mount/drag-install in Finder, and signed-bundle identity. Those are Mac-only, and there's no macOS job in the PR CI gate (mac runners only run in the release pipelines), so CI won't cover them for me either.

Given that, here's how I'd suggest splitting the work:

• PR 1 (no Mac needed): Settings toggle + persistence + clearer DMG-fallback copy. Fully cross-platform — gated by web/daemon vitest + typecheck + guard, plus Windows manual validation. Rough estimate: ~1–3 days part-time.
• PR 2: threading the preference into candidate selection. Logic is testable on Windows via the fixture, but it needs a macOS acceptance pass before merge.

For that Mac-gated verification I'll either need to line up a final tester on macOS — would you or @TheAngryPit be able to do the native acceptance pass? — or, if that's not workable, I'm happy to relinquish the ticket to someone who has a Mac and can close the loop end-to-end. Let me know which you'd prefer.

🤖 Generated by Claude Code on behalf of @cbeaulieu-gt

[lefarcen]

Hey @cbeaulieu-gt, that split makes sense, and the 1–3 day estimate for PR 1 is noted. Let's keep this claim scoped to the cross-platform first step for now — settings toggle, persistence, and clearer DMG-fallback copy — and then revisit the Mac-gated candidate-selection follow-up once that part is up.

No need to relinquish the ticket at this stage.

[lefarcen]

Hey @cbeaulieu-gt, thanks for spelling out the testing boundary so clearly. Since PR #4471 is already merged, the remaining Mac-specific acceptance belongs to the follow-up slice rather than the first payload-capability fix.

Please go ahead with the cross-platform PR when you're ready, and we can line up the macOS-native verification when that follow-up is actually on the table.

[lefarcen]

Hey @TheAngryPit — PR #4543 is now open for the cross-platform first slice: it adds the persisted install-mode preference plus the clearer manual-installer copy that was left for follow-up after #4471 landed the payload-capability foundation.

Keeping this issue open until that PR lands, since the broader macOS-native acceptance follow-up is still separate.

[lefarcen]

Re-opening this issue for community contribution because linked PR #4543 has had no author activity.

The PR has been left open as draft so @cbeaulieu-gt can resume later, and others may /claim this issue if they want to take it on.