PRD: Ship canonical opencode with Amicode — retire the fork-built binary from user machines #451

PRD: Ship canonical opencode with Amicode — retire the fork-built binary from user machines

User Stories

• Onboarding — a researcher installs Amicode on a clean machine (even offline): the Amicode terminal's opencode is canonical upstream, amicode-aware (persona, skills, tools active), seeing the same sessions as the app.
• Currency — upstream ships a release; within 48h a connected user runs it, without a VSIX release or any action on their part.
• Broken release — an upstream release breaks our surface: the adopt gate fails, the user keeps last-known-good silently, sessions intact.
• Existing user — upgrades across the cutover: every session written by the fork-built server remains readable; no capability they use today regresses.

Acceptance Criteria

1. fresh_install_fork_binaries == 0 — clean VM per platform (incl. WSL), offline: terminal opencode resolves to the vendored canonical bootstrap; no file matches any fork release-asset sha256.
2. vsix_fork_binary_refs == 0 — shipped lock names anomalyco/opencode, no -amicode. tag, no vendored binary sha from the fork (docs/skills textual mentions out of scope).
3. route_parity_pct == 100 — 18/18 amicode route modules pass fork-derived contract tests against the extension-host service (golden fixtures from the live fork server for modules known-red on the fork).
4. app_e2e_unexpected_failures == 0 — ported app e2e suite: every failure on the quarantine list frozen at M0; anything else blocks.
5. drill_adopt_lag_h <= 48 — a gate-passing upstream release goes from publish to adoption marker within 48h on a connected test machine.
6. failed_update_data_loss == 0 — corrupted-download, plugin-load-failure, and app-health-failure drills each end with sessions intact and last-known-good current.
7. cutover_session_retention_pct == 100 — dogfood DB + synthetic corpus (≥500 sessions, all part types) structurally identical pre/post cutover.

Key Decisions

• One push — no incremental user-visible rollout; the cutover release is the first user-visible change and ships zero fork-built bytes.
• Managed canonical wins — inside the Amicode terminal the extension-managed binary resolves first on PATH; user installs elsewhere untouched.
• Auto-adopt after smoke gate — activation + daily checks; adoption is an atomic symlink swap only after: digest verification, boot smoke, plugin-registration assert for the amicode tool pack, and app + service health against a consistent (sqlite-backup) copy of the live DB.
• Port, don't rewrite — the 18 route modules move wholesale into the extension host; parity is judged by fork-derived contract tests, with golden fixtures recorded from the running fork server for the modules whose tests are known-red on the fork itself.
• Vocabulary — upstream = anomalyco/opencode ("canonical opencode"); the fork is never user-facing. Code comments that call the fork binary "canonical" are corrected in the app-bundle milestone.

Modules & Interfaces

• Plugin pack (unchanged) — amicode tools via opencode's standard plugin loader; single-export contract.
• Config injection (unchanged) — spawn-time config content carrying persona, skills paths, permissions, plugin paths.
• Extension-host amicode service (new) — the ported routes serving widgets, vault browser, connections, and amicode app calls; the deck shell's iframe origin check widens to it.
• App bundle (new, extracted from the fork) — composes upstream app components; CI-pinned against canonical releases; owns the amicode i18n keys.
• Runtime updater (new) — managed install under the amico state dir with a current symlink; the VSIX vendors one canonical copy per platform as offline bootstrap.

Testing Decisions

Parity via fork-derived contract tests + golden fixtures; app e2e ported with a frozen quarantine list; three fault-injection drills plus a live adopt-lag drill; retention corpus ≥500 sessions; clean-VM matrix per platform including WSL; parallel-run harness (extension service alongside the fork server) as the migration's verification backbone.

Risks

• App↔canonical client-API drift becomes the recurring post-cutover cost; CI-pinned overlay is the mitigation, and breaking releases hold users on last-known-good by design.
• The app-bundle extraction is the long pole; the parallel-run harness de-risks taking it slowly.
• Post-adoption breakage (passes gate, breaks later) heals on the next release; the existing binary-override setting remains the manual escape hatch.
• Supply chain: TLS + GitHub-API digest only, no third-party mirrors; digest absence refuses adoption.

Constraints & Invariants

• Last-known-good is never deleted; adoption only via the full adopt gate.
• The chat DB stays pinned by the extension across every spawn — the binary never picks its DB by build channel (the 2026-08-08 channel-flip incident).
• No coupling to canonical internals; supported surfaces are the plugin API, config injection, and the documented client HTTP API. No feature is added by re-forking.
• The fork's default branch is never force-pushed; the repo is archived, not deleted.
• All work on Harmoniqs repos goes through issue + PR (development gate).

Source

Durable record: personal Armonia vault, amicode/specs/spec-20260820-044920-ship-canonical-opencode.md (deliberated 2026-08-20, manual adversarial review — 1 blocking contradiction fixed, 9 advisories) · compiled plan at amicode/plans/plan-20260820-044920-ship-canonical-opencode.md · related: harmoniqs/opencode#159

Notes

Decisions locked with the researcher 2026-08-20: one-push cutover; managed-canonical PATH precedence inside the Amicode terminal; auto-adopt after smoke gate. The spec's deliberation was hand-run (spec tooling unavailable on the host) — a weaker review claim than a tooled one, noted for the record.