feat(electron): in-app install, R2 auto-update feed, gaia:// deep links

[kovtcharov-amd]

Why this matters

The Agent UI shell had three broken/missing install-and-update surfaces, all in the Electron main/preload layer:

• Before: clicking install on a published agent hit a dead agent:install IPC stub that threw "not yet implemented" — the UI could never actually import an agent. After: the IPC handlers proxy to the real backend install runtime (POST /api/agents/install → poll install-status → DELETE for uninstall), streaming progress to the renderer. One tested install path, no duplicated download/verify/uv logic in the main process. (Closes In-app install runtime: remove/redirect the stale agent:install Electron IPC stub (backend runtime landed) #1721)
• Before: auto-update was hard-wired to GitHub Releases. After: the forward channel is a configurable generic R2 feed with a mutable latest channel pointer; the URL resolves from GAIA_UPDATE_FEED_URL / update-config.json, and an unconfigured app enters a loud "no channel configured" state instead of silently checking a dead feed. (Closes R2-primary auto-update: generic electron-updater feed + mutable latest channel #1724)
• Before: the website's "Open in GAIA" button had nowhere to land. After: the app registers the gaia:// protocol and handles gaia://hub/install/<id> (macOS open-url, Win/Linux argv + second-instance), dispatching the agent id to the install runtime; malformed links raise an actionable dialog. (Closes gaia:// deep-link install bridge (website → app) + protocol registration #1725)

No silent fallbacks: a missing backend port, missing update feed, or malformed deep link each surface a loud, actionable error.

Part of #2014.

Dependency note (#1724)

The actual R2 publish feed + Worker latest*.yml channel pointer are milestone-52 work (#1719) and not live yet. This PR ships the app-side integration + config so it works against any configurable feed URL (a local/mock feed exercises the full path); electron-builder.yml switches provider: github → generic. Rollback (#1336) still lists/installs from GitHub Releases — independent of the forward feed, migrates with #1719.

Test plan

• cd tests/electron && npm install && npx jest — full suite green (659 passed, 1 skipped, 20 suites)
• New: tests/electron/deep-link.test.cjs — gaia:// parse: valid, bad scheme, missing/invalid id, extra segments, argv extraction
• New: tests/electron/auto-updater-feed.test.cjs — feed from env + config file, env precedence, loud NO_CHANNEL when unset, checkForUpdates picks up a later-configured feed
• Updated: tests/electron/test_agent_process_manager.js — install/uninstall IPC redirect (POST/DELETE shape + X-Gaia-UI header), failed-install surfaces, loud no-backend error
• Updated: tests/electron/auto-updater.test.cjs — clearPin restores the R2 forward feed
• cd src/gaia/apps/webui && npm run build — TypeScript + Vite build compiles
• Manual: GAIA_UPDATE_FEED_URL=<mock> end-to-end update against a local feed (blocked on a real R2 feed / Publish Agent UI to R2 as an app (manifest + catalog entry + signed release workflow) #1719 for the production path)

[kovtcharov]

🔒 SECURITY CONCERN — @kovtcharov-amd

The deep-link install path performs an agent install without any user confirmation: main.cjs dispatchDeepLink calls agentProcessManager.installAgent(command.agentId) directly, and the backend's trust enforcement only guards native packages. That means an external web page can trigger installation (download + pip install + hot-register) of any non-native catalog agent — including community/experimental tier — off a single generic OS "Open GAIA?" prompt, bypassing the trust gate that #2201 makes a hard requirement for the same action in-app. Recommend gating deep-link installs behind the same trust/confirmation dialog before this merges; happy to discuss specifics privately.

Separate note for the tracking issue rather than this PR: until code signing lands (#1719), auto-update integrity rests solely on HTTPS + same-origin checksum — fine as a documented accepted risk, but it should stay a hard blocker for enabling a production feed.

Otherwise the PR is in good shape — deep-link parser, feed resolution, and install/uninstall IPC proxy are all unit-tested (the main.cjs dispatch wiring is the untested piece, which is also where the concern above lives).

[github-actions]

🟡 When the app starts in NO_CHANNEL (no feed configured) and a feed is later set, periodic background checks are never scheduled — only manual checkForUpdates() calls will work until the app restarts.

init() returns early at line 803 without reaching the initialCheckTimeout = setTimeout(...) block (line 807). scheduleNextCheck() is only ever called from inside that timeout callback, so the 4-hour background-check cadence is never initiated. checkForUpdates() itself re-resolves the feed on each call and will work, but nothing triggers it on a schedule after a late feed configuration.

The test "checkForUpdates() picks up a feed configured after init()" exercises a single manual check — it confirms the check runs but does not verify that periodic scheduling resumes. The gap is invisible to the test suite.

Since the R2 feed isn't live yet this won't affect users today, but it contradicts the intent of the late-configuration path the tests document.

🔍 Technical details

services/auto-updater.cjs — the new init() flow:

initialized = true;

if (!feedReady && !savedPin) {
    // …log…
    return;  // ← exits before the block below
}

initialCheckTimeout = setTimeout(async () => {
    await checkForUpdates();
    scheduleNextCheck();  // ← never reached when NO_CHANNEL at startup
}, CHECK_DELAY_MS);

Fix: when checkForUpdates() transitions out of NO_CHANNEL (i.e., _applyForwardFeed() returns true on line 497), kick off periodic scheduling if neither timer is already running:

if (!forwardFeedUrl && !state.pinnedVersion) {
    if (!_applyForwardFeed()) return;
    // Feed was just configured; start the periodic cadence if nothing else has.
    if (!initialCheckTimeout && !scheduledTimeout) scheduleNextCheck();
}

This mirrors the scheduleNextCheck() call that initialCheckTimeout would have made, without double-scheduling when a pin is active.

[kovtcharov]

The deep-link concern is fully addressed: installs from gaia:// now require an explicit per-agent confirmation (default Cancel), the gate lives in deep-link.cjs with injected deps, and the security-critical control flow is unit-tested — confirm-before-install ordering, decline, and dismissed-dialog (non-true) all covered. Note: the currently red build/Vitest checks are main's AgentHubGrid breakage (missing module after the #2190/#2201 merge ordering), not this PR — re-run after main is fixed and they should go green. The auto-update feed integrity note stands as an accepted risk tracked in #1719.