feat(ENG-850): add shell auto-update lifecycle foundation

[pnewsam]

Status

Draft / first implementation slice. This PR intentionally does not enable shell auto-update at runtime yet. It establishes the testable lifecycle and serialized electron-updater boundary first, so feed/version/release work cannot accidentally point existing installs at an incomplete channel.

Stacked on #453 (ENG-849), which remains the manual installer fallback and current shell-update notice.

What this slice adds

• electron-updater as an application dependency.
• An explicit, pure shell-update lifecycle:
  • disabled
  • idle
  • checking
  • available
  • downloading
  • ready-to-install
  • installing
  • complete
  • failed
• Auto/manual mode semantics in the transition model.
• A serialized effect runner that coalesces concurrent checks and downloads.
• Adaptation of electron-updater events into immutable authoritative snapshots.
• Stable recoverable vs terminal error classification, including signature/checksum failures.
• A guarded quitAndInstall transition and synchronous launch-failure recovery.
• Unit coverage for legal/illegal transitions, retry behavior, progress, installation reconciliation, single-flight behavior, and error classification.

Why this shape

This follows the ENG-850 design discussion: a small state machine for the shell updater only, not a rewrite of the existing UI/server update path. The renderer will eventually consume the authoritative snapshot rather than reconstructing truth from several phase strings.

The adapter sets autoDownload = false because the lifecycle runner owns when download starts. autoInstallOnAppQuit remains an explicit factory choice so auto and manual modes cannot silently share install behavior. Downgrades are disabled.

Important release constraint discovered

The user-visible release version is currently a five-component CalVer (for example 2.26.7.27.1), while electron-updater compares SemVer and the packaged Electron version currently remains 2.0.7. Feed generation therefore needs a deterministic, order-preserving internal SemVer mapping that remains separate from the displayed CalVer. This must land before runtime enablement.

Remaining work

• Define and test the display-CalVer → updater-SemVer mapping.
• Add explicit prod/stable feed eligibility and keep unknown/dev/unsupported builds disabled.
• Generate and publish signed macOS ZIP + latest-mac.yml alongside the existing PKG fallback.
• Publish signed Windows NSIS artifact + latest.yml/blockmap without renaming metadata out of sync.
• Upload immutable artifacts first and mutable channel metadata last; verify CDN URLs.
• Wire the lifecycle into main startup behind safe channel eligibility.
• Add snapshot get/change IPC plus check/download/relaunch commands.
• Persist minimal downloaded-target evidence and reconcile it on next launch.
• Add the lightweight maintenance gate so shell install cannot race UI/server mutation.
• Integrate ENG-849 UI with progress, ready-to-relaunch, retry, and manual fallback states.
• Complete signed packaged N → N+1 smoke tests on macOS and Windows before production enablement.

Verification

• npm run typecheck
• npm test — 631/631 passed
• npm run check:cowork-purity
• git diff --check

Refs ENG-850.
Depends on #453.

[pnewsam]

Consolidated into #508, which now carries the whole ENG-850 stack as one PR (this lifecycle-foundation slice included). Closing in favor of #508; branch left intact.

[pnewsam]

Correction: the consolidated PR is #521 (I mislabeled it #508 above — the branch rename auto-closed #508). All four ENG-850 slices now live in #521, stacked on #453.