Legacy → rewrite cutover: the ao update migration flow

[harshitsinghbhandari]

How an existing legacy user moves from the legacy stack to the rewrite (Go backend + Electron app), end to end. This is the runtime flow; the npm packaging mechanics are in #229, and the data import/reconcile is coordinated separately with the legacy side.

Two version numbers

The migration code has to be on the machine before it can run, so there are two releases in play:

• 0.9.6 (legacy) — the bridge release. Its job is to ship the migration-aware ao update.
• 0.10.0 (rewrite) — the cutover target. Same package name @aoagents/ao, new version. This is the Go+Electron rewrite that gets installed.

Path for a user on 0.9.5:

1. ao update → lands on 0.9.6 (a normal in-place legacy update; no migration yet, it just delivers the smarter ao update).
2. ao update again → 0.9.6's logic sees the cutover is available and performs the migration to 0.10.0.

(0.9.6 can chain straight into the cutover so it feels like one step, but "must be on 0.9.6 first" is unavoidable since the migrating code ships in 0.9.6.)

ao update pins the exact cutover version (@aoagents/ao@0.10.0), it does not chase @latest, so every migrating user lands on the same tested version.

What ao update does, in order

1. Detect install method (npm / pnpm / bun global; homebrew and git installs handled specially).
2. Refuse if any session is active — lists the running sessions/projects, exits non-zero. User finishes or stops them first.
3. Safety guard — if the new store looks fresher than the legacy data (user is already on the rewrite), refuse unless --force-migrate.
4. Mandatory confirm — this is an irreversible cross-stack move.
5. Back up legacy data to ~/.ao/backups/legacy-<timestamp>/ (legacy flat files + a copy of any prior ao.db + the old pipelines dir for forensics).
6. Install the rewrite — npm install -g @aoagents/ao@0.10.0 (or pnpm/bun equivalent). Its postinstall lays down the ~20 MB Go binary + CLI.
7. Fetch the Electron app — the ~254 MB desktop app is downloaded from GitHub Releases as part of the cutover, so it's ready and the first GUI launch is instant. (It is NOT shipped through npm; see "Why" below.)
8. Init the new store at the pinned schema and run the importer — legacy data → new store, preserving native agent resume IDs (claudeSessionUuid, codexThreadId + codexModel, opencodeSessionId) so sessions resume.
9. Health-check the new daemon (/healthz, /readyz).
10. On success → done, print a summary (what imported, backup location, what was preserved-but-not-imported). On failure → restore the backup + reinstall the prior legacy version, exit non-zero.

After cutover — how it runs

• ao start → starts the Go daemon only. Headless; the CLI works fully without the GUI.
• A separate command opens the Electron desktop app, which discovers and attaches to the running daemon.

So CLI-only users never need the GUI in their way, but the 254 MB app is already on disk and one command away.

Why the Electron app is fetched separately (not via npm)

Measured built sizes (darwin/arm64, on current main):

• Go daemon binary: ~20 MB — fine to deliver through npm.
• Electron app: ~254 MB (232 MB of that is the Electron runtime itself).

Pushing a 254 MB app through npm per platform would mean ~1 GB+ of registry artifacts per release and a 254 MB download for every install, with no delta updates. Electron's own auto-update does binary deltas; npm does not. So:

• npm carries the ~20 MB Go daemon + CLI.
• The Electron app stays on its native installer + Electron auto-update track, fetched from Releases during the cutover and self-updating afterward.

Summary of decisions captured here

• Bridge release 0.9.6 (legacy) ships the migration-aware ao update; cutover target is 0.10.0 (rewrite), same package name, pinned (not @latest).
• ao update = refuse-if-active → guard → confirm → backup → install rewrite → fetch Electron → import (with resume IDs) → health-check → rollback on failure.
• Electron app is fetched during the migration so it's ready.
• ao start runs the daemon only; opening the GUI is a separate command.
• npm delivers the Go binary + CLI; the Electron app is delivered/updated natively.

Related

• Packaging the rewrite as @aoagents/ao (Go backend + Electron via npm) #229 — packaging the rewrite as @aoagents/ao (Go + Electron via npm), postinstall vs optional-deps, platform matrix.
• Data import/reconcile contract (snapshot format + importer call signature) — coordinated with the legacy side; authoritative store is the legacy flat files.