Single .dmg installer from aoagents.dev (daemon bundled in the app)

[harshitsinghbhandari]

A second distribution channel for the rewrite, aimed at non-technical users: a single signed + notarized .dmg downloadable from aoagents.dev. Download, drag to Applications, double-click, it just works. No "start the daemon" step, no separate frontend install.

This sits alongside the npm channel (@aoagents/ao, for CLI/developer users). Same product, same ~/.ao data dir; two front doors.

The vision

A normal human visits aoagents.dev, clicks Download, opens the app like any Mac app, and is using Agent Orchestrator. They never see a terminal, a daemon, or a port.

How it works (the crux)

Today the Go daemon and the Electron app are separate processes. The Electron main process already knows how to supervise and launch the daemon (daemon-launch + port-discovery, per the frontend survey). The missing piece is making the app self-contained:

• Bundle the Go daemon binary inside the .app (in Resources). On launch, Electron spawns the bundled daemon, discovers its port, and the user never sees it. The supervision logic already exists; it just points at the bundled binary instead of an external one.
• Package the result as a signed + notarized .dmg via electron-forge (makers + the notarization checklist already exist in docs/desktop-release.md).
• Host the .dmg on aoagents.dev. The app self-updates via Electron's existing auto-update.

Decisions locked

• GUI + CLI always. The .app bundles the ao CLI and links it onto PATH (e.g. symlink into /usr/local/bin) so one install gives both the GUI and the command. (npm stays the CLI-first channel; this just means a .dmg user also gets ao.)
• New-users-only for migration. The .dmg does NOT run the legacy-to-rewrite migration. If an existing legacy user downloads it, the app's first boot detects "legacy data present + empty ~/.ao store" and directs them to run the npm ao update path (which owns migration). The .dmg itself never touches legacy data.

Build workstreams

1. Bundle daemon-in-app - embed the Go daemon binary in the Electron app resources; wire the existing daemon supervisor to launch the bundled binary (per-arch).
2. Bundle + link the CLI - ship the ao CLI in the app and symlink it onto PATH on launch (handle the privilege prompt for writing to /usr/local/bin).
3. Signing + notarization - Apple Developer ID signing + notarization. Config is already sketched in docs/desktop-release.md; needs team-provisioned secrets. This is a hard prerequisite for a double-clickable app (Gatekeeper).
4. .dmg maker - electron-forge .dmg output (drag-to-Applications layout).
5. Release CI - build/sign/notarize the .dmg per release, publish it + the auto-update feed.
6. Website download - a Download button/page on aoagents.dev (the landing site exists under frontend/src/landing/) pointing at the latest .dmg.
7. First-boot legacy detection - "legacy data + empty store -> tell the user to run npm ao update" (shared with the rewrite first-boot work already on the migration track).

Relationship to the npm channel

• Same product, same ~/.ao data dir, same Go daemon + Electron app. The only difference is delivery: npm ships the daemon + CLI (Electron fetched separately); the .dmg ships everything in one bundle.
• A user could in principle have both; since both resolve ~/.ao, they operate on the same data. Worth a guard so two installs don't fight over the daemon/port, but they're designed to share state, not duplicate it.
• Auto-update: the .dmg app self-updates via Electron's channel; npm users update via ao update / npm. Two update channels for two install methods.

Open questions

• Signing secrets ownership - who provisions the Apple Developer ID + notarization credentials in CI? Blocks the whole channel.
• CLI symlink UX - writing to /usr/local/bin needs elevated permission on first launch; what's the prompt/flow? (VS Code's "Install 'code' command in PATH" is the reference, but we link unconditionally per the decision above.)
• Auto-update vs the npm next tag - the .dmg app updates itself; does its update feed track the same versions as the npm next tag, or its own channel? Need them not to diverge.
• Other platforms - this is macOS .dmg first. Windows .exe / Linux AppImage are the obvious follow-ups (electron-forge already has those makers); confirm Mac-first is the v1 scope.