app-bundle drift on main: #620's hand-cherry-picked titlebar overlay is unreachable-green — pick the pin and re-extract

[aarontrowbridge]

Important

Problem — main is red on app-bundle-gate since #620 (2026-08-28 02:37Z): the overlay file packages/app/src/components/titlebar-channel.test.ts (and its sibling titlebar-channel.ts) no longer matches manifest.json's per-file hash. Every PR against main now inherits the failure (first casualty: #622, docs-only, all other checks green).
Approach — A human-owned pin decision, then the extractor. #620 cherry-picked the titlebar change by hand from fork commit e94eb7d329 (branch fix/titlebar-dev-beta-badge) onto the v1.18.10-amicode.16-pinned overlay. The gate's design admits exactly one green state: the overlay as extracted at a pinned tag — so a hand-cherry-pick is unreachable-green no matter what manifest edits follow. The repair is: pick the pin, re-run the extractor, commit the regenerated overlay + manifest.
Scope — in: one decision (below) + one extractor run + the regenerated files · out: any extension-code change.
Assumptions — the fork team's tag cadence (.13→.17) is the sync protocol of record; pins move by tag, never by hand.

Acceptance Criteria

• The pin decision is made and recorded here (A or B below).
• node packages/app-bundle/scripts/extract_overlay.mjs --tag <chosen> regenerates the overlay + manifest at the chosen pin.
• node packages/app-bundle/scripts/drift_gate.mjs exits 0 with a fork clone present (full re-derivation, not just the committed-state check).
• main green on app-bundle-gate; docs(adr): Harness Contract v1 — the fixture-pinned opencode API subset (A2, #621) #622 (and any other parked PRs) merges clean.

Key Decisions — the pin choice (owner call, not auto-resolved)

• A. Re-pin to v1.18.10-amicode.17 (9c7c8783c) — the newest tag the fork team cut. Carries ~59 files of fork-side app changes (website-chat-style rework etc.) into the overlay — all the fork's own merged work, but unreviewed on the amicode side at once. Finishes the sync chore: bump to v0.3.1, sync titlebar dev->DEV / beta->BETA #620 gestured at, with the badge fix coming along if .17 contains it — note: e94eb7d329 is NOT an ancestor of .17, so verify the titlebar change is actually in .17's tree before choosing this path (diff the two files at the tag).
• B. Revert the overlay hand-edit, keep the version bump — restores the byte-exact .16 state (gate green immediately), at the cost of re-introducing the dev→BETA badge behavior chore: bump to v0.3.1, sync titlebar dev->DEV / beta->BETA #620 fixed. The titlebar change then lands properly with the next blessed pin that contains it.
• A synthetic tag (.16 + titlebar files only) was considered and rejected: tags are the fork team's cadence, not a repair tool.

Constraints & Invariants

• Never hand-edit packages/app-bundle/overlay/ — the extractor is the only writer (the gate's whole point).
• The manifest's fork_tag/fork_sha/upstream_base* and per-file hashes move together, via the extractor, never by hand.
• The local fork clone at ~/armonia/repos/opencode is current as of this issue (fetched today; e94eb7d329 and .17 both present).

Prior Art

• packages/app-bundle/scripts/drift_gate.mjs — checks, in order: pins resolve; fresh extraction reproduces the manifest; every overlay file matches its hash.
• packages/app-bundle/scripts/extract_overlay.mjs — deterministic extraction at a tag (--fork, --tag).
• docs/migration-canonical-opencode.md §2–3 — the overlay architecture.

Source

• Found while landing the Harness Contract v1 ADR (docs(adr): Harness Contract v1 — the fixture-pinned opencode API subset (A2, #621) #622 — parked ready-for-review on this failure).
• Fork state: fix/titlebar-dev-beta-badge @ e94eb7d329; v1.18.10-amicode.17 @ 9c7c8783c (contains neither the other).

Notes

• Whoever picks the pin: option A requires first confirming git -C ~/armonia/repos/opencode diff 77bb1c8b 9c7c8783c -- packages/app/src/components/titlebar-channel.ts shows the dev→DEV change. If it doesn't, option A loses the badge fix too and B + a follow-up fork tag is the honest path.