@omega.js/desktop 0.1.0

package/dist/lib/auto-updater.js

@@ -0,0 +1,752 @@
+// Auto-updater — wraps electron-updater with these triggers:
+//
+//   1. Startup check        — fires `startupDelayMs` after `whenReady` (default 10s, non-blocking).
+//   2. Feed-check timer     — every `feedCheckIntervalMs` (default 1h). HTTP-bound — hits the
+//                             release feed. Hourly to match Discord/Slack/VS Code; running this
+//                             every minute would hammer GitHub at 60× the necessary rate.
+//   3. Idle-eval timer      — every `idleEvalIntervalMs` (default 1m). In-process arithmetic only,
+//                             no HTTP. Decides whether to install an already-downloaded update
+//                             based on user idle time. Frequent so a downloaded update installs
+//                             promptly when the user steps away (rather than waiting up to an
+//                             hour for the next feed-check).
+//   4. 30-day pending gate  — once an update is downloaded, store `downloadedAt`. On every
+//                             feed-check tick + at app start, if (now - downloadedAt) >= maxAgeMs
+//                             (default 30d), force `quitAndInstall()`. Counter is set on the FIRST
+//                             download and not reset by subsequent downloads — first one wins.
+//                             Cleared only when the app actually launches at the
+//                             pendingUpdate.version (i.e. install applied).
+//
+// State machine (broadcast to renderers as `desktop:auto-updater:status`):
+//   idle / checking / available / downloading / downloaded / not-available / error
+//
+// Dev simulation: set `OMEGA_DEV_UPDATE=available|unavailable|error` env var. The updater synthesizes
+// the appropriate event sequence so you can test the UI flow without a real update server.
+// `simulate(scenario)` is the same cascade on demand (View > Developer > Simulate update in the
+// default menu), so a QA pass walks all three outcomes without relaunching per scenario.
+//
+// Renderer surface (added to preload.js as `window.desktop.autoUpdater`):
+//   getStatus()      → { code, version, percent, error?, downloadedAt? }
+//   onStatus(fn)     → unsubscribe fn; called on every state change.
+//   checkNow()       → user-initiated check (shows dialogs on completion).
+//   installNow()     → quitAndInstall() if status === 'downloaded'.
+
+const LoggerLite = require('./logger-lite.js');
+const logger = new LoggerLite('auto-updater');
+
+const STORAGE_KEY = 'autoUpdater';
+
+// Idle-aware install constant — hardcoded for now (not config-shaped). Tune here.
+//
+// A downloaded update no longer auto-installs after a flat 5s delay. Instead, the
+// idle-eval timer (every `DEFAULTS.idleEvalIntervalMs`, default 1m) makes the
+// install decision:
+//   1. Any UI activity (mouse / keyboard / wheel / touch / window focus) bumps
+//      `_lastActivityAt = Date.now()`.
+//   2. The idle-eval tick checks `state.code === 'downloaded'`:
+//        - If user idle ≥ IDLE_INSTALL_THRESHOLD_MS → installNow().
+//        - Else if we haven't prompted for this version yet → native dialog (once).
+//   3. Dismissal ("Later") is "not now" — the idle-eval tick keeps polling and the
+//      install fires whenever the user eventually walks away. We never re-prompt
+//      for the same version (tracked via `_promptedForVersion`).
+//
+// Consumer hook: `manager.autoUpdater.markActive()` lets app code force-bump the
+// activity timestamp from anywhere (e.g. just received an auth event, finished a
+// long-running renderer task, etc.). Use sparingly — the built-in signals cover
+// 99% of real activity.
+//
+// Test mode: when `manager.isTesting()` is true, the threshold collapses to 3s so
+// integration tests can drive a real download → idle wait → install in ~5s instead
+// of 15min. Both timers (feed-check + idle-eval) likewise drop to 500ms in tests so
+// the full sequence fires inside a test run. Wired in `_idleThresholdMs()` and the
+// initialize() timer setup based on the manager's `isTesting()` helper.
+const IDLE_INSTALL_THRESHOLD_MS         = 15 * 60 * 1000;   // 15 min — production
+const IDLE_INSTALL_THRESHOLD_MS_TESTING =      3 * 1000;    // 3 sec  — when isTesting()
+const IDLE_TICK_MS_TESTING              =          500;     // 500ms periodic tick when testing
+
+// The dev simulator's scenarios. Doubles as the OMEGA_DEV_UPDATE value set and the
+// argument set simulate() accepts, so the env var and the menu trigger can never drift.
+const SIMULATION_SCENARIOS = ['available', 'unavailable', 'error'];
+
+// The version the simulator claims to have downloaded. A RESERVED sentinel: the
+// reconciler discards any stored pendingUpdate carrying it (see _reconcilePendingUpdate),
+// so an app must never ship a real release at this version.
+const SIMULATED_VERSION = '999.0.0';
+
+// Two separate timers, two different jobs:
+//
+//   feedCheckIntervalMs   — how often to hit the update feed (HTTP request). EXPENSIVE
+//                           (network I/O against a third-party host every running app
+//                           instance). Default 1h matches Discord/Slack/VS Code.
+//   idleEvalIntervalMs    — how often to re-evaluate "is now a good time to install
+//                           the downloaded update?" CHEAP (in-process arithmetic on
+//                           _lastActivityAt + state check). Default 1min so a downloaded
+//                           update installs promptly when the user steps away.
+//
+// They were briefly merged into a single timer in 1.2.38; that was a mistake — running
+// the feed-check at idle-eval cadence (60s) was hammering GitHub at 60× the necessary
+// rate. Restored as separate timers in 1.3.1.
+const DEFAULTS = {
+  enabled:               true,
+  channel:               'latest',
+  startupDelayMs:           10 * 1000,           // 10s after whenReady
+  feedCheckIntervalMs:      60 * 60 * 1000,      // 1h — feed poll cadence
+  idleEvalIntervalMs:        1 * 60 * 1000,      // 1m — idle-install evaluator cadence
+  maxAgeMs:                 30 * 24 * 60 * 60 * 1000,  // 30 days
+  autoDownload:          true,
+};
+
+// Fresh state object so a single `Object.assign` never bleeds between instances or test runs.
+function freshState() {
+  return {
+    code:          'idle',
+    version:       null,
+    percent:       0,
+    error:         null,
+    downloadedAt:  null,
+    lastCheckedAt: null,
+  };
+}
+
+const autoUpdater = {
+  _initialized: false,
+  _manager:     null,
+  _library:     null,
+  _options:     null,
+  _state:       freshState(),
+  _feedCheckIntervalId: null,
+  _idleEvalIntervalId:  null,
+  _pendingTimers: [],
+  _userInitiated: false,
+  _devSimulating: false,          // a cascade is running RIGHT NOW (re-entrancy guard)
+  _devSimulationSession: false,   // this process has simulated at least once (see _isSimulating)
+
+  // Idle-aware install state.
+  _lastActivityAt:     Date.now(),     // bumped by markActive(); seed to "now" so we don't auto-install the instant we boot
+  _promptedForVersion: null,           // version string we've already prompted about — never prompt twice for the same version
+  _activityHooksWired: false,          // guard: only wire main-side activity listeners once per process
+
+  async initialize(manager) {
+    autoUpdater._manager = manager;
+    autoUpdater._initialized = true;
+    autoUpdater._state = freshState();
+
+    const cfg = (manager && manager.config && manager.config.autoUpdate) || {};
+    autoUpdater._options = { ...DEFAULTS, ...cfg };
+
+    if (autoUpdater._options.enabled === false) {
+      logger.log('auto-updater disabled via config.autoUpdate.enabled=false');
+      return;
+    }
+
+    // 1. Reconcile any pending update from a prior session.
+    autoUpdater._reconcilePendingUpdate();
+
+    // 2. Wire the electron-updater instance (or dev simulator).
+    if (autoUpdater._isSimulating()) {
+      logger.log(`Dev simulation mode active (OMEGA_DEV_UPDATE=${process.env.OMEGA_DEV_UPDATE})`);
+      autoUpdater._wireDevSimulator();
+    } else {
+      autoUpdater._wireElectronUpdater();
+    }
+
+    // 3. IPC: renderer status query + actions. Unhandle first so re-init is idempotent.
+    if (manager && manager.ipc) {
+      const channels = [
+        ['desktop:auto-updater:status',     async () => autoUpdater.getStatus()],
+        ['desktop:auto-updater:check-now',  async () => autoUpdater.checkNow({ userInitiated: true })],
+        ['desktop:auto-updater:install-now', async () => autoUpdater.installNow()],
+      ];
+      for (const [chan, fn] of channels) {
+        manager.ipc.unhandle(chan);
+        manager.ipc.handle(chan, fn);
+      }
+      // Activity ping from preload (debounced renderer-side mouse/keyboard/focus).
+      // Listener (not handle) — fire-and-forget, no response needed. Set-backed
+      // listener registry deduplicates same-fn re-adds, so re-init is safe.
+      if (typeof manager.ipc.on === 'function') {
+        manager.ipc.on('desktop:auto-updater:activity', autoUpdater._onActivityIpc);
+      }
+    }
+
+    // 3b. Wire main-side activity hooks (browser-window focus, tray clicks, menu
+    // invocations, deep-link arrivals — see _wireActivityHooks). One-shot per process.
+    autoUpdater._wireActivityHooks();
+
+    // 4. Schedule startup check (non-blocking).
+    const startupDelay = autoUpdater._options.startupDelayMs;
+    autoUpdater._pendingTimers.push(setTimeout(() => {
+      autoUpdater.checkNow({ userInitiated: false }).catch((e) => logger.warn(`startup check failed: ${e.message}`));
+    }, startupDelay));
+
+    // 5. Schedule TWO independent timers:
+    //
+    //    a) Feed-check timer (EXPENSIVE — HTTP). Hits the GitHub release feed.
+    //       Default 1h cadence. Also enforces the 30-day max-age gate as a safety net
+    //       since this tick is when we'd notice a long-pending update.
+    //
+    //    b) Idle-eval timer (CHEAP — in-process). Re-evaluates whether to install
+    //       a downloaded update based on user idle time. Default 1m cadence so a
+    //       downloaded update installs promptly when the user steps away.
+    //
+    // In tests (`manager.isTesting() === true`) both cadences collapse to
+    // IDLE_TICK_MS_TESTING (500ms) so an integration test sees the full sequence
+    // fire within seconds of a download.
+    const isTesting = manager.isTesting();
+    const feedInterval = isTesting ? IDLE_TICK_MS_TESTING : autoUpdater._options.feedCheckIntervalMs;
+    const idleInterval = isTesting ? IDLE_TICK_MS_TESTING : autoUpdater._options.idleEvalIntervalMs;
+
+    if (feedInterval > 0) {
+      autoUpdater._feedCheckIntervalId = setInterval(() => autoUpdater._feedCheckTick(), feedInterval);
+    }
+    if (idleInterval > 0) {
+      autoUpdater._idleEvalIntervalId  = setInterval(() => autoUpdater._idleEvalTick(),  idleInterval);
+    }
+
+    logger.log(`auto-updater initialized (feed-check=${feedInterval}ms, idle-eval=${idleInterval}ms, maxAge=${autoUpdater._options.maxAgeMs}ms, idle-install threshold=${autoUpdater._idleThresholdMs() / 1000}s${isTesting ? ' [testing]' : ''})`);
+  },
+
+  // Feed-check tick — hits the GitHub release feed. Expensive (HTTP). Also enforces
+  // the 30-day max-age gate since this is the slower-cadence tick.
+  async _feedCheckTick() {
+    try {
+      await autoUpdater.checkNow({ userInitiated: false });
+    } catch (e) {
+      logger.warn(`feed-check failed: ${e.message}`);
+    }
+    autoUpdater._enforceMaxAgeGate();
+  },
+
+  // Idle-eval tick — cheap, no network. Just decides whether to install the
+  // already-downloaded update. Runs frequently so a downloaded update installs
+  // promptly when the user steps away (rather than waiting for the next hourly
+  // feed-check).
+  _idleEvalTick() {
+    autoUpdater._evaluateIdleInstall();
+  },
+
+  // Public API ─────────────────────────────────────────────────────────────────────
+
+  getStatus() {
+    return { ...autoUpdater._state };
+  },
+
+  async checkNow(opts) {
+    opts = opts || {};
+    autoUpdater._state.lastCheckedAt = Date.now();
+
+    if (!autoUpdater._readyToCheck()) {
+      // Already mid-check or sitting on a downloaded update — return without mutating
+      // _userInitiated. Otherwise a user clicking "Check for Updates" while a periodic
+      // background check is in flight would flip _userInitiated=true, which then makes
+      // _evaluateIdleInstall() skip the auto-install path (see line ~303). The flag must
+      // only flip when we actually start a new check.
+      logger.log(`Skipping check — current state=${autoUpdater._state.code}`);
+      return autoUpdater.getStatus();
+    }
+    autoUpdater._userInitiated = !!opts.userInitiated;
+
+    if (autoUpdater._isSimulating()) {
+      autoUpdater._runDevSimulation();
+      return autoUpdater.getStatus();
+    }
+
+    if (!autoUpdater._library) {
+      logger.warn('checkNow() called before library wired.');
+      return autoUpdater.getStatus();
+    }
+
+    try {
+      await autoUpdater._library.checkForUpdates();
+    } catch (e) {
+      autoUpdater._setState({ code: 'error', error: { message: e.message } });
+    }
+    return autoUpdater.getStatus();
+  },
+
+  // Dev-only runtime trigger for the update simulator, wired to the default menu's
+  // View > Developer > Simulate update items. Runs the same synthetic cascade the
+  // OMEGA_DEV_UPDATE env var drives at boot, except per call, so update UX can be
+  // walked scenario by scenario without relaunching the app (or shipping a release).
+  // Resolves with the status once the cascade is running, exactly like checkNow();
+  // the terminal state arrives over the status broadcast a few hundred ms later.
+  async simulate(scenario) {
+    const name = String(scenario || '').toLowerCase();
+    if (!name) {
+      throw new Error(`simulate(): scenario required, one of ${SIMULATION_SCENARIOS.join('|')}`);
+    }
+    if (!SIMULATION_SCENARIOS.includes(name)) {
+      throw new Error(`simulate(): unknown scenario "${scenario}". Expected one of: ${SIMULATION_SCENARIOS.join(', ')}.`);
+    }
+
+    // Same doctrine as _isSimulating(): a packaged production build may simulate, but
+    // only when it was LAUNCHED for QA with OMEGA_DEV_UPDATE set. Without that opt-in a
+    // shipped binary must never be talked into faking an update it cannot deliver.
+    if (autoUpdater._manager.isProduction() && !autoUpdater._isSimulating()) {
+      throw new Error('simulate(): refused in a production build. Relaunch with OMEGA_DEV_UPDATE set to simulate updates.');
+    }
+
+    // A cascade runs on fire-and-forget timers, so a second one cannot share the state
+    // machine with the first: it would reset the state to idle underneath it and then
+    // lose its own scenario to _runDevSimulation's re-entrancy guard. Refuse loudly
+    // rather than accept a call that silently does nothing.
+    if (autoUpdater._devSimulating) {
+      logger.warn(`simulate(${name}): refused, a simulation is already running.`);
+      throw new Error('simulate(): a simulation is already running. Wait for it to finish before starting another.');
+    }
+
+    // Swap the real electron-updater instance out for the synthetic one and LEAVE it
+    // swapped for the rest of the session. Swapping back is not safe: the cascade is
+    // async and fire-and-forget (there is no moment we know it ended), and the real
+    // library's listeners are still attached to its singleton, so a feed check landing
+    // mid-cascade would overwrite the synthetic states. A session that has simulated is
+    // a QA session; relaunch to get the real updater back. Idempotent when the boot-time
+    // simulator is already wired.
+    autoUpdater._wireDevSimulator();
+
+    // Latch the session ON with the swap, never apart from it: the two facts (a
+    // synthetic library is wired / the updater is simulating) must not disagree.
+    autoUpdater._devSimulationSession = true;
+
+    // Clear the visible state so a second simulation does not inherit the version,
+    // percent, or error the previous one left behind. downloadedAt is deliberately
+    // kept: the 30-day pending-update record is not ours to erase.
+    autoUpdater._userInitiated = true;   // keeps the idle-eval tick from installing a simulated download
+    autoUpdater._setState({ code: 'idle', version: null, percent: 0, error: null, lastCheckedAt: Date.now() });
+
+    logger.log(`simulate(${name}): running the dev update cascade`);
+    await autoUpdater._library.checkForUpdates(name);
+    return autoUpdater.getStatus();
+  },
+
+  // Bump the activity timestamp. Called automatically by the built-in activity hooks
+  // (renderer mouse/keyboard, browser-window focus). Consumer code can also call this
+  // directly from anywhere (`manager.autoUpdater.markActive()`) to force-bump on
+  // app-specific activity.
+  markActive() {
+    autoUpdater._lastActivityAt = Date.now();
+  },
+
+  // Named handler for the IPC activity listener so the listener registry's Set-based
+  // dedupe collapses repeated re-init calls into one entry.
+  _onActivityIpc() {
+    autoUpdater.markActive();
+  },
+
+  async installNow() {
+    if (autoUpdater._state.code !== 'downloaded') {
+      logger.log(`installNow ignored — state=${autoUpdater._state.code}`);
+      return false;
+    }
+    if (autoUpdater._isSimulating()) {
+      logger.log('Dev mode — skipping real quitAndInstall().');
+      return true;
+    }
+    // Flip the manager's quit flag so the window-manager close handler lets the
+    // close events through instead of trapping them with hide-on-close. Without
+    // this, quitAndInstall() fires before-quit but the BrowserWindow's close
+    // handler (which runs FIRST since it has its own listener) would call
+    // event.preventDefault() and the install would just hide the window.
+    if (autoUpdater._manager) {
+      autoUpdater._manager._allowQuit = true;
+    }
+    if (autoUpdater._library && typeof autoUpdater._library.quitAndInstall === 'function') {
+      autoUpdater._library.quitAndInstall();
+      return true;
+    }
+    return false;
+  },
+
+  // Lifecycle teardown — used by tests.
+  shutdown() {
+    if (autoUpdater._feedCheckIntervalId) clearInterval(autoUpdater._feedCheckIntervalId);
+    if (autoUpdater._idleEvalIntervalId)  clearInterval(autoUpdater._idleEvalIntervalId);
+    autoUpdater._pendingTimers.forEach((t) => clearTimeout(t));
+    autoUpdater._feedCheckIntervalId = null;
+    autoUpdater._idleEvalIntervalId  = null;
+    autoUpdater._pendingTimers = [];
+    autoUpdater._initialized   = false;
+    autoUpdater._library       = null;
+    autoUpdater._userInitiated = false;
+    autoUpdater._devSimulating = false;
+    autoUpdater._devSimulationSession = false;
+    autoUpdater._promptedForVersion = null;
+    autoUpdater._activityHooksWired = false;
+
+    const m = autoUpdater._manager;
+    if (m && m.ipc && typeof m.ipc.unhandle === 'function') {
+      ['desktop:auto-updater:status', 'desktop:auto-updater:check-now', 'desktop:auto-updater:install-now'].forEach((c) => {
+        m.ipc.unhandle(c);
+      });
+    }
+  },
+
+  // Internals ──────────────────────────────────────────────────────────────────────
+
+  // Auto-updater dev SIMULATION mode — controls whether checkForUpdates() is wired
+  // to electron-updater (real) or our synthetic event sequence (fake). Triggered by
+  // setting OMEGA_DEV_UPDATE=available|unavailable|error. NOT the same as
+  // `manager.isDevelopment()` (which is the runtime "are we packaged" signal); a
+  // packaged production build can absolutely run with OMEGA_DEV_UPDATE set for QA.
+  //
+  // The runtime simulate() latches `_devSimulationSession` for the rest of the process
+  // (cleared by shutdown()). It has to: simulate() leaves the synthetic library wired,
+  // so every LATER trigger drives the simulator too. The feed-check tick would then
+  // produce a fake 'downloaded' that this flag is the only thing keeping out of the
+  // real install path (_evaluateIdleInstall and installNow both bail on it). Reading
+  // only the env var here means a plain dev session could be talked into a native
+  // "restart to update" prompt, `_allowQuit = true`, and a stored pendingUpdate for a
+  // version that does not exist.
+  _isSimulating() {
+    return !!process.env.OMEGA_DEV_UPDATE || autoUpdater._devSimulationSession;
+  },
+
+  _idleThresholdMs() {
+    return autoUpdater._manager.isTesting() ? IDLE_INSTALL_THRESHOLD_MS_TESTING : IDLE_INSTALL_THRESHOLD_MS;
+  },
+
+  _readyToCheck() {
+    // Don't re-check while we're already mid-flight (checking/available/downloading) or sitting
+    // on a downloaded update waiting to install — re-checking would just re-download the same thing.
+    return ['idle', 'not-available', 'error'].includes(autoUpdater._state.code);
+  },
+
+  _setState(patch) {
+    const prevCode = autoUpdater._state.code;
+    autoUpdater._state = { ...autoUpdater._state, ...patch };
+    autoUpdater._broadcastStatus();
+
+    // No post-download install trigger here. All install-decision logic lives in the
+    // idle-eval tick (`_evaluateIdleInstall`). It runs every idleEvalIntervalMs
+    // (default 1m); first evaluation happens on the next tick after download
+    // completes (gives a user who's currently active a chance to reach a natural
+    // pause before any prompt fires).
+  },
+
+  // Evaluate whether to auto-install or prompt. Called from the idle-eval tick.
+  // The 30-day gate runs on the feed-check tick separately.
+  //   - Only runs when state.code === 'downloaded' (i.e. an update is sitting ready).
+  //   - Skips if the original check was user-initiated (consumer UI handles that path).
+  //   - If user idle ≥ _idleThresholdMs() (15min in prod, 3s in tests) → installNow().
+  //   - Else if we haven't prompted for this version yet → show native dialog.
+  //   - Else: do nothing this tick. Try again next tick.
+  _evaluateIdleInstall() {
+    if (autoUpdater._state.code !== 'downloaded') return;
+    if (autoUpdater._userInitiated) return;        // user-initiated path — consumer UI owns the install affordance
+    if (autoUpdater._isSimulating()) return;          // dev simulator never really installs
+
+    const idleMs = Date.now() - autoUpdater._lastActivityAt;
+    const threshold = autoUpdater._idleThresholdMs();
+    if (idleMs >= threshold) {
+      logger.log(`User idle for ${Math.round(idleMs / 1000)}s (threshold=${Math.round(threshold / 1000)}s) — auto-installing update v${autoUpdater._state.version}.`);
+      // installNow is async; any internal throw becomes a rejection caught by
+      // the global unhandledRejection handler in main.js.
+      autoUpdater.installNow().catch((e) => logger.warn(`idle auto-install failed: ${e.message}`));
+      return;
+    }
+
+    // User is active — prompt once per version.
+    const v = autoUpdater._state.version;
+    if (v && autoUpdater._promptedForVersion !== v) {
+      autoUpdater._promptedForVersion = v;
+      autoUpdater._promptToInstall(v).catch((e) => logger.warn(`install prompt failed: ${e.message}`));
+    }
+  },
+
+  // Show a native dialog asking the user to restart now. Non-blocking (fire-and-forget).
+  // Dismissal ("Later") is fine — the watcher keeps polling and will auto-install once
+  // the user goes idle.
+  async _promptToInstall(version) {
+    // In test mode we short-circuit BEFORE invoking the real native dialog. The
+    // dialog is modal + blocking on a real desktop session and pops a window the
+    // user can't dismiss programmatically — exactly what we don't want firing
+    // during automated runs. Tests that want to assert prompt behavior should
+    // override `_promptToInstall` per-test (see auto-updater.test.js).
+    if (autoUpdater._manager.isTesting()) {
+      logger.log(`Test mode: _promptToInstall(${version}) — skipped native dialog.`);
+      return;
+    }
+
+    const { dialog, BrowserWindow } = require('electron');
+    if (!dialog) return;        // renderer/preload context — no dialog API
+
+    const focusedWindow = BrowserWindow.getFocusedWindow();
+    const productName = autoUpdater._manager.config.app?.productName
+      || autoUpdater._manager.config.brand.name;
+
+    // showMessageBox CAN reject (e.g. dialog destroyed, no display) — wrap just
+    // the call. Synchronous setup above doesn't need a try.
+    let result;
+    try {
+      result = await dialog.showMessageBox(focusedWindow, {
+        type:      'info',
+        buttons:   ['Restart Now', 'Later'],
+        defaultId: 0,
+        cancelId:  1,
+        title:     'Update Ready',
+        message:   `${productName} is ready to install version ${version}.`,
+        detail:    `Restart to apply the update now, or it will install automatically the next time you're idle.`,
+      });
+    } catch (e) {
+      logger.warn(`_promptToInstall: dialog.showMessageBox failed: ${e.message}`);
+      return;
+    }
+
+    if (result.response === 0) {
+      logger.log(`User accepted install prompt — installing v${version}.`);
+      autoUpdater.installNow();
+    } else {
+      logger.log(`User dismissed install prompt for v${version} — watcher continues.`);
+      // Bump activity so we don't re-prompt within the same tick window.
+      autoUpdater.markActive();
+    }
+  },
+
+  // Wire main-process activity hooks. Idempotent — only runs once per process.
+  // Renderer-side activity arrives via the 'desktop:auto-updater:activity' IPC listener
+  // wired in initialize() (mouse/keyboard/wheel/touch/focus debounced in preload).
+  // This method covers main-process signals that don't go through the renderer:
+  //   - browser-window-focus: user alt-tabbed back, clicked a window from elsewhere,
+  //     or surfaced the app via tray click / dock click — any path that gives the
+  //     window focus fires this. Tray/menu clicks that show/focus a window are also
+  //     covered by this transitively.
+  // Deep-link arrivals are a softer signal (the user might have clicked a link in a
+  // browser hours ago and walked away) — we deliberately don't bump activity from
+  // them. If a consumer wants to count something specific, they can call markActive().
+  _wireActivityHooks() {
+    if (autoUpdater._activityHooksWired) return;
+    autoUpdater._activityHooksWired = true;
+
+    const { app } = require('electron');
+    app.on('browser-window-focus', () => autoUpdater.markActive());
+  },
+
+  _broadcastStatus() {
+    const m = autoUpdater._manager;
+    if (m && m.ipc && typeof m.ipc.broadcast === 'function') {
+      m.ipc.broadcast('desktop:auto-updater:status', autoUpdater.getStatus());
+    }
+    autoUpdater._updateMenuItem();
+    autoUpdater._updateTrayItem();
+    logger.log(`status → ${autoUpdater._state.code}${autoUpdater._state.version ? ` v${autoUpdater._state.version}` : ''}${autoUpdater._state.percent ? ` (${autoUpdater._state.percent}%)` : ''}`);
+  },
+
+  // Compute the label + enabled fields for any "check for updates" UI item from current state.
+  // Used by both the menu and tray patchers so they stay in lockstep.
+  _menuItemFieldsForState() {
+    const s = autoUpdater._state;
+    let label, enabled = true;
+    switch (s.code) {
+      case 'checking':       label = 'Checking for Updates...';                       enabled = false; break;
+      case 'available':      label = `Downloading Update v${s.version || ''}...`;     enabled = false; break;
+      case 'downloading':    label = `Downloading Update (${Math.round(s.percent)}%)`; enabled = false; break;
+      case 'downloaded':     label = `Restart to Update v${s.version || ''}`;         enabled = true;  break;
+      case 'not-available':  label = 'You\'re up to date';                            enabled = true;  break;
+      case 'error':          label = 'Check for Updates...';                          enabled = true;  break;
+      case 'idle':
+      default:               label = 'Check for Updates...';                          enabled = true;  break;
+    }
+    return { label, enabled };
+  },
+
+  // Reflect updater state into the @omega.js/desktop Check-for-Updates item. The item lives under
+  // `main/check-for-updates` on macOS (App menu) and `help/check-for-updates` on win/linux —
+  // we just patch whichever one exists. Consumer can remove either via
+  // manager.menu.remove('main/check-for-updates') in their integrations/menu/index.js.
+  _updateMenuItem() {
+    const m = autoUpdater._manager;
+    const { label, enabled } = autoUpdater._menuItemFieldsForState();
+
+    // Patch whichever id-path exists. .update() returns false (and warns) if missing,
+    // so try both without doubling up on warnings — silence by checking has() first.
+    if (m.menu.has('main/check-for-updates')) {
+      m.menu.update('main/check-for-updates', { label, enabled });
+    } else if (m.menu.has('help/check-for-updates')) {
+      m.menu.update('help/check-for-updates', { label, enabled });
+    }
+  },
+
+  // Reflect updater state into the tray's `check-for-updates` item, if present. Same
+  // label/enabled semantics as the menu item — keeps both UIs in lockstep.
+  _updateTrayItem() {
+    const m = autoUpdater._manager;
+    const { label, enabled } = autoUpdater._menuItemFieldsForState();
+
+    if (m.tray.has('check-for-updates')) {
+      m.tray.update('check-for-updates', { label, enabled });
+    }
+  },
+
+  // 30-day gate ────────────────────────────────────────────────────────────────────
+
+  _reconcilePendingUpdate() {
+    const m = autoUpdater._manager;
+    const pending = m.storage.get(`${STORAGE_KEY}.pendingUpdate`);
+    if (!pending || !pending.downloadedAt) return;
+
+    // A simulated record (written by a build from before the simulator stopped
+    // touching this key) can never be applied — nothing ships at the sentinel
+    // version, so the clear-on-apply check below would never match it. Discard
+    // it here, or its fake timestamp gets restored into _state.downloadedAt and
+    // force-installs the first REAL download the moment it lands.
+    if (pending.version === SIMULATED_VERSION) {
+      logger.log(`Discarding simulated pendingUpdate record (v${pending.version}) — the dev simulator never downloaded anything.`);
+      m.storage.set(`${STORAGE_KEY}.pendingUpdate`, null);
+      return;
+    }
+
+    const currentVersion = autoUpdater._manager.getVersion();
+    if (pending.version === currentVersion) {
+      logger.log(`Pending update v${pending.version} appears to be applied — clearing flag.`);
+      m.storage.set(`${STORAGE_KEY}.pendingUpdate`, null);
+      return;
+    }
+
+    autoUpdater._state.downloadedAt = pending.downloadedAt;
+    autoUpdater._state.version      = pending.version;
+    logger.log(`Pending update v${pending.version} carried from prior session (downloadedAt=${new Date(pending.downloadedAt).toISOString()})`);
+    // The gate can't install HERE — electron-updater has no download this
+    // session (installNow() requires state 'downloaded'). The startup check
+    // (startupDelayMs) re-downloads; update-downloaded then enforces the gate
+    // against the restored original downloadedAt.
+  },
+
+  _recordDownloadedAt(version) {
+    // The simulator's download is fake, so its record must never reach the
+    // production key: a fake timestamp there outlives the QA session and seeds
+    // the first-download-wins timer for the next REAL download (a fake record
+    // older than maxAgeMs force-installs it on arrival). The in-memory stamp
+    // still happens, so the in-session UI flow reads exactly like a real one.
+    if (autoUpdater._isSimulating()) {
+      autoUpdater._state.downloadedAt = Date.now();
+      logger.log(`Dev simulation — skipping the pendingUpdate write for v${version}.`);
+      return;
+    }
+
+    const m = autoUpdater._manager;
+    if (!m || !m.storage) return;
+
+    const existing = m.storage.get(`${STORAGE_KEY}.pendingUpdate`);
+    // FIRST download wins for the TIMER — but the stored version must track the
+    // NEWEST download, or the clear-on-apply check (version === getVersion())
+    // never matches after the install and the stale flag force-installs every
+    // future download instantly, forever.
+    if (existing && existing.downloadedAt) {
+      logger.log(`pendingUpdate already recorded (v${existing.version} @ ${new Date(existing.downloadedAt).toISOString()}) — keeping existing timestamp.`);
+      if (existing.version !== version) {
+        m.storage.set(`${STORAGE_KEY}.pendingUpdate`, { version, downloadedAt: existing.downloadedAt });
+      }
+      autoUpdater._state.downloadedAt = existing.downloadedAt;
+      return;
+    }
+    const now = Date.now();
+    m.storage.set(`${STORAGE_KEY}.pendingUpdate`, { version, downloadedAt: now });
+    autoUpdater._state.downloadedAt = now;
+    logger.log(`Recorded pendingUpdate v${version} @ ${new Date(now).toISOString()}`);
+  },
+
+  _enforceMaxAgeGate() {
+    const downloadedAt = autoUpdater._state.downloadedAt;
+    if (!downloadedAt) return false;
+
+    const age = Date.now() - downloadedAt;
+    const max = autoUpdater._options.maxAgeMs;
+    if (age < max) return false;
+
+    logger.warn(`Pending update is ${Math.round(age / 86400000)}d old (>= ${Math.round(max / 86400000)}d) — forcing install.`);
+    autoUpdater.installNow();
+    return true;
+  },
+
+  // electron-updater wiring ────────────────────────────────────────────────────────
+
+  _wireElectronUpdater() {
+    let lib;
+    try {
+      lib = require('electron-updater').autoUpdater;
+    } catch (e) {
+      logger.warn(`electron-updater not available: ${e.message}`);
+      return;
+    }
+    autoUpdater._library = lib;
+    lib.autoDownload = autoUpdater._options.autoDownload !== false;
+
+    lib.on('checking-for-update', () => autoUpdater._setState({ code: 'checking', error: null }));
+    lib.on('update-available',    (info) => autoUpdater._setState({ code: 'available', version: info?.version, error: null }));
+    lib.on('update-not-available', (info) => autoUpdater._setState({ code: 'not-available', version: info?.version, error: null }));
+    lib.on('download-progress',   (p) => {
+      const percent = Math.min(100, parseFloat(((p && p.percent) || 0).toFixed(2)) || 0);
+      autoUpdater._setState({ code: 'downloading', percent });
+    });
+    lib.on('update-downloaded', (info) => {
+      autoUpdater._recordDownloadedAt(info?.version);
+      autoUpdater._setState({ code: 'downloaded', version: info?.version, percent: 100, error: null });
+      // A pending update carried from a prior session keeps its ORIGINAL
+      // downloadedAt (first-download-wins), so the 30-day gate can trip the
+      // moment the startup re-download lands — installNow() only works from
+      // the 'downloaded' state, which exists from this line on.
+      autoUpdater._enforceMaxAgeGate();
+    });
+    lib.on('error', (e) => {
+      const err = (e instanceof Error) ? e : new Error(String(e || 'Unknown auto-update error'));
+      autoUpdater._setState({ code: 'error', error: { message: err.message } });
+    });
+  },
+
+  // Dev simulation ─────────────────────────────────────────────────────────────────
+
+  _wireDevSimulator() {
+    autoUpdater._library = {
+      checkForUpdates:  async (scenario) => autoUpdater._runDevSimulation(scenario),
+      quitAndInstall:   () => logger.log('Dev simulator: quitAndInstall() called (no-op in dev).'),
+      autoDownload:     autoUpdater._options.autoDownload !== false,
+      on:               () => {},
+    };
+  },
+
+  // `scenario` is the per-call override simulate() passes. The boot-time path (checkNow
+  // while _isSimulating()) passes nothing and falls back to the OMEGA_DEV_UPDATE value
+  // that put the updater in simulation mode to begin with, so that path is unchanged.
+  _runDevSimulation(scenario) {
+    if (autoUpdater._devSimulating) return;
+    autoUpdater._devSimulating = true;
+
+    const name = (scenario || process.env.OMEGA_DEV_UPDATE || 'available').toLowerCase();
+    const NEW_VERSION = SIMULATED_VERSION;
+
+    autoUpdater._setState({ code: 'checking' });
+
+    setTimeout(() => {
+      if (name === 'unavailable') {
+        autoUpdater._setState({ code: 'not-available', version: NEW_VERSION });
+        autoUpdater._devSimulating = false;
+        return;
+      }
+      if (name === 'error') {
+        autoUpdater._setState({ code: 'error', error: { message: 'Simulated dev-update error' } });
+        autoUpdater._devSimulating = false;
+        return;
+      }
+
+      // 'available' → cascade through download progress → downloaded.
+      autoUpdater._setState({ code: 'available', version: NEW_VERSION });
+
+      let percent = 0;
+      const tick = () => {
+        percent = Math.min(100, percent + 25);
+        autoUpdater._setState({ code: 'downloading', version: NEW_VERSION, percent });
+        if (percent < 100) {
+          autoUpdater._pendingTimers.push(setTimeout(tick, 400));
+        } else {
+          autoUpdater._pendingTimers.push(setTimeout(() => {
+            autoUpdater._recordDownloadedAt(NEW_VERSION);
+            autoUpdater._setState({ code: 'downloaded', version: NEW_VERSION, percent: 100 });
+            autoUpdater._devSimulating = false;
+          }, 400));
+        }
+      };
+      autoUpdater._pendingTimers.push(setTimeout(tick, 400));
+    }, 400);
+  },
+};
+
+module.exports = autoUpdater;