feat(ci): add overlay-promotion-bot workflow (#1010 Phase 1)

[jack-champagne]

Phase 1 of #1010.

Update: originally this depended on #1025 (Phase 0) landing first. JJ's #1012 independently fixed the vsix-gate breakage as a bonus alongside an unrelated change, so main's packaging is unblocked already. #1025 is now scoped down to the one remaining bug (overlay_promotion.test.ts failing on main) and this PR has been rebased on current main independently — both are green standalone, no ordering dependency between them anymore.

What this does

Automates the diff JJ has been generating by hand across #947, #1005, #1006, #1009, #1011: on a schedule (every 2h) or manual dispatch, runs the existing overlay-promotion.mjs --check against harmoniqs/opencode's local/amicode tip. On drift, it runs --apply on a deterministic overlay-promotion branch and opens (or force-updates) one PR.

What this deliberately does NOT do

No signed webhook receiver, no GitHub App, no compare-and-swap bot-merge authority, no exception-approval automation. Looking at JJ's own promotion PRs: #1009 was merged 6 seconds after opening, #1011 was merged 27 seconds after opening — both once CI was green. The actual toil is producing the diff and remembering to run the command, not the review/merge step. So a human (or required status checks, once branch protection is enabled — separately flagged, not yet decided) still merges here, exactly like today.

This is intentionally disposable: if the app-bundle overlay itself is retired later (the direction tracked separately, off this issue), this workflow gets deleted, not migrated.

Verification

Ran the actual logic end-to-end against a scratch git remote and the real harmoniqs/opencode clone, not just described:

• --check against the current in-sync state (fork tip 6fa55b660a3, matching the manifest) exits 0 — no PR would be opened.
• Simulated a fork commit and confirmed --check correctly flips to exit 1.
• Found and fixed a real ordering bug during this: --apply must run on the review branch, created before the apply call — Enforce overlay provenance for main rebuilds #1005's own "refuse promotion directly on main" guard otherwise refuses the bot's apply, since the job starts checked out on main. Verified the corrected order runs cleanly and reproduces the exact manifest + overlay diff.
• Re-ran the branch-reset → apply cycle twice to confirm idempotency: each run resets overlay-promotion from main and reproduces the same tree, so repeated triggers before a human merges are safe to force-push and never diverge.
• Rebased onto current main post-BUG: Scrolling in development projects forces back to top upon scrolldown #1012; all CI checks (fast, vsix-gate, app-bundle-gate, etc.) pass.

Open follow-up (not in this PR)

Branch protection / required status checks are still off on main — this bot's PRs get the same protection as any human's today, which is none. Flagged for a separate decision, not blocking this PR.

[coderabbitai]

Warning

Review limit reached

Next included review available in 32 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 6007d768-6aff-49f4-93e2-70e517ab2a4b

📥 Commits

Reviewing files that changed from the base of the PR and between bd4c7d6 and ad99e0d.

📒 Files selected for processing (1)

• .github/workflows/overlay-promotion-bot.yml

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[jack-champagne]

Folded into #1025 — combining Phase 0 + Phase 1 into one PR to land today.