fix(app-bundle): overlay-sync test stops mutating the fork checkout; add refusal guards (#842)

[aarontrowbridge]

Related Issue

Closes #842

Description

The overlay-sync suite ran overlay-sync.mjs --apply with no target, which resolved the real fork checkout and copied its current branch over packages/app-bundle/overlay/** — ~250 committed files mutated mid-suite (the repeated working-tree hazard the #823 origin-flip cast had to restore before every commit). Separately, the sync treated the fork as authoritative for every file it copied, including files amicode had fixed, so a sync could silently revert a recorded fix (the #964 class).

This change:

• overlay-sync.mjs — adds --target / --manifest / --source-branch and a no-write --check mode. --apply now refuses when the source checkout is on the wrong branch (default local/amicode) or dirty, with a named remedy; AMICODE_OVERLAY_SYNC_OVERRIDE=<reason> waives it but is recorded (empty reason refuses). Crucially, --apply refuses writing nothing when the post-apply tree would revert a known amicode-side fix, naming the fix.
• known_fixes.mjs (new) — the known-fix fixture list extracted to ONE shared module consumed by both overlay-sync.mjs and deploy_guard.mjs; no third forked copy.
• deploy_guard.mjs — imports the shared list instead of carrying its own.
• overlay_sync.test.ts — every invocation aims --source/--target at a temp tree; adds a beforeAll/afterAll hash proof that the real overlay stays byte-clean across the suite.
• deploy_guard.test.ts — parity test cross-checks the shared list against the Sync-reconciliation: the fork→overlay sync clobbers amicode-side fixes (#929's fix regressed by ff7b69c8; the diff_version fix owes a fork mirror) #964 source of record and asserts deploy_guard no longer forks it.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• Config / infrastructure (CI, tooling, build, docs)

Verification

• pnpm run typecheck exits 0 (all 4 workspace projects: schema, amico-run, extension)
• pnpm -r run test exits 0 — focused suites run here (below); full suite not run in-cast
• Manual testing described below

Focused suites (run twice, idempotence):

packages/extension $ pnpm exec vitest run test/overlay_sync.test.ts test/overlay_known_fixes_964.test.ts test/deploy_guard.test.ts
 ✓ test/overlay_known_fixes_964.test.ts (2 tests)
 ✓ test/deploy_guard.test.ts (19 tests)
 ✓ test/overlay_sync.test.ts (14 tests)
 Test Files  3 passed (3)
      Tests  35 passed (35)

Hygiene proof — git status --porcelain packages/app-bundle/overlay is EMPTY both after run 1 and after run 2, and the full worktree status is empty (the suite no longer mutates committed overlay state).

Manual Testing Notes

• --check against the real repo: read-only, exit 1 on drift (expected; the local fork is currently on agent-picker-order, not local/amicode).
• --apply against the real fork with a temp --target: refused by the source-branch guard (branch 'agent-picker-order', expected local/amicode), wrote nothing — temp target directory remained absent.

Ops note for the director: the shared fork checkout ~/harmoniqs/opencode is on agent-picker-order (clean). The new branch guard means a default overlay-sync --apply on this machine now refuses rather than clobbering — intended, but the director should decide whether local/amicode remains the right expected branch for this checkout, or whether the sync should be run with --source-branch / a recorded override. That shared checkout was not switched by this cast.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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.}