feat(cli): cutover-aware ao update (bridge 0.9.6)

[harshitsinghbhandari]

Cutover-aware ao update (bridge 0.9.6)

Teaches the existing ao update command to perform the legacy-to-rewrite cutover while leaving its normal-update behavior byte-for-byte unchanged. Scope is only the ao update command.

When a rewrite build is published under the npm next dist-tag (or AO_CUTOVER_VERSION is set) and the current install is still legacy (major.minor < 0.10), ao update migrates the user's data via ao migrate (#2129) and installs the rewrite at the exact pinned version instead of running the normal channel update. Migration runs before the install because the migrate command is legacy-side and disappears once the rewrite overwrites the binary.

What landed

• update-check.ts
  • resolveCutoverTarget() — AO_CUTOVER_VERSION override wins, else dist-tags.next from the registry; returns null (no cutover) on any network/parse error, never throws.
  • isLegacyVersion(version) — true when major.minor < 0.10.
  • getCutoverInstallCommand(method, version) — exact-pin install for npm/pnpm/bun; null for homebrew/git/unknown (manual instructions instead).
• update.ts
  • Cutover branch sits in front of the existing switch (method): fires only when a target exists and the install is legacy and target != current.
  • handleCutover() follows the mandatory order: worker-busy guard (orchestrator never blocks; it gets migrated) → confirmation/non-interactive gate (api-invoked spawns are refused, never auto-confirmed) → stop daemon (no restore) → migrate → install rewrite → verify → finish without restarting the legacy daemon.
  • Shared stopAoAndVerifyDown() refactored out of pauseAoForUpdate() and reused by the cutover stop.
  • --check now also reports cutoverAvailable and cutoverTarget.
• Migration is invoked as ao migrate --json against the documented contract ({ dbCreated, schemaVersion, projects, orchestrators }); a non-zero exit aborts before any install (user stays on legacy).

Regression budget

With no cutover target (the common case), every existing handler (git/npm/homebrew/unknown), flag (--skip-smoke/--smoke-only/--no-restore/--check), and the stop/restore lifecycle are unchanged. All spawns keep shell: isWindows() + windowsHide: true via the existing helpers.

Tests

New coverage for resolveCutoverTarget, getCutoverInstallCommand, isLegacyVersion, cutover gating, the worker-busy guard (real-shaped sessions with role), api-invoked refusal, migration abort, per-method install, the homebrew/git/unknown manual path, and the success path (cache invalidated, no restart). Full gate green: pnpm build && pnpm typecheck && pnpm lint && pnpm test.

One pre-existing, environment-dependent failure remains — path-equality.test.ts > canonicalCompareKey > expands ~ to HOME — which is byte-identical to main and unrelated to this change.

Explicitly out of scope (not touched)

• ao migrate (feat(cli): unified OFFLINE ao migrate — port legacy projects + sessions into the rewrite (direct-DB), with Claude transcript relocation #2129 — sibling worker; called here only via its --json contract)
• npm publish workflow / dist-tag guard
• Dashboard /api/update route + UpdateBanner
• ao start cutover notice
• Anything in the rewrite repo

Refs #2129

[github-actions]

Test Coverage Report

Metric	Value
Lines covered	1015/1173
Lines not covered	158/1173
Overall coverage	86.5%

Per-file breakdown

File	Coverage
packages/cli/src/commands/update.ts	654/795 (82.3%)
packages/cli/src/lib/update-check.ts	361/378 (95.5%)

Uncovered lines

• packages/cli/src/commands/update.ts: L219-L220, L222-L223, L233-L237, L258-L259, L261-L262, L279-L288, L314-L315, L333-L342, L344-L347, L362-L363, L430-L431, L477-L478, L543-L552, L557-L562, L625-L626, L631-L632, L650-L651, L667-L668, L828-L830, L836-L858, L943-L948, L950-L955, L957-L966, L986-L991, L993-L998, L1004-L1009, L1015-L1020
• packages/cli/src/lib/update-check.ts: L98-L99, L108-L109, L126-L127, L147-L149, L151-L152, L242-L243, L393-L394, L459-L460