Deploy guard: build_app_bundle refuses stale/unrecorded trees

[aarontrowbridge]

Closes #992.

What

The 2026-09-10 deploy race — a local-tree deploy overwrote the recorded-main dist-app swap and the #987 crash returned — gets enforced at the moment of building:

• Pre-flight (packages/extension/scripts/build_app_bundle.mjs): fetch origin; refuse (exit 1, named reason + remedy) when HEAD ≠ origin/main (behind/diverged/ahead) or the tree is dirty. Override via AMICODE_DEPLOY_OVERRIDE=<reason>: empty/missing reason with the flag set refuses (no silent overrides); a valid override proceeds but is recorded.
• Deploy manifest: every stage stamps dist-app/deploy.json — {commit, branch, dirty, override_reason, built_at, deployed_by} — so the served dist always traces to a recorded commit.
• Known-fixes check at deploy time: 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 known-fixed hunks (fix: restore V2 composer translation callback #929 3-arg translate callback, chore: fix pre-existing main breakages blocking clean overlay composition (#821) #832 diff_version shape + guarded delete, chore: fix pre-existing main breakages blocking clean overlay composition (#821) #832 exportTrace locales) asserted against the overlay before any build. Missing fix → named-remedy refusal, never overridable. deploy_guard.mjs mirrors the fixture list from test/overlay_known_fixes_964.test.ts (source of record); the test suite cross-checks the two lists can't drift silently.

Shape

The decision logic (evaluatePreflight, checkKnownFixes, buildDeployManifest, headRelation) lives in packages/extension/scripts/deploy_guard.mjs as pure functions, driven by both the script and test/deploy_guard.test.ts.

Verification (all run live)

• vitest run test/deploy_guard.test.ts test/overlay_known_fixes_964.test.ts → 20/20 passed: refuse-on-behind, refuse-on-diverged, refuse-on-dirty, refuse-on-empty-override, refuse-on-whitespace-override, proceed-with-recorded-override, proceed-clean, manifest shape (override_reason serializes null), known-fixes pass + per-file refusals, fixture-list parity, headRelation mapping.
• Real deploy runs (scratch clone + the guard worktree):
  • behind-main clone → exit 1, BEHIND + dirty named reasons + remedies
  • same clone, AMICODE_DEPLOY_OVERRIDE= (empty) → exit 1, empty-override refusal added
  • same clone, valid override → override recorded, then 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 known-fixes refusal fires (that tree predates Sync-reconciliation: restore #929's translate-callback fix + the pre-sync guard (#964) #965) — exit 1, no dist staged
  • guard worktree (at origin/main, clean) → refused its own ahead-of-main commit; valid override → staged + stamped deploy.json
• Hub dist-app redeployed through the guard (override honestly records the pre-merge state; dist content is the byte-identical b66d623 build); served surfaces verified.

Notes

• The pre-merge hub deploy used AMICODE_DEPLOY_OVERRIDE with the reason stamped in the served deploy.json — after this merges, the next deploy should run clean (no override).
• Follow-up: the deploy race's other half — whoever copies the staged dist to the service dir — could adopt the same manifest check (verify the served deploy.json before overwrite). Not in this slice.

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

[aarontrowbridge]

Second commit b9374bfd: the vsix-gate caught the guard itself — CI packaging runs build:app from the PR merge ref (ahead of origin/main, shallow-cloned), so the pre-flight refused and broke packaging. Under CI the stale/dirty checks are now advisory (recorded in the manifest's override_reason with the merge ref + branch); the #964 known-fixes check stays enforcing. Also unshallow-fetches before the ancestry probes. CI green.

Live incident worth flagging (pre-existing, #964 class): running the full extension suite (pnpm test) executed overlay_sync.test.ts's --apply test against my worktree, which applied fork→overlay drift over 256 files and clobbered the #832 exportTrace fix mid-session — the deploy-time known-fixes check then correctly REFUSED the redeploy until the overlay was restored. The sync tool's own test suite can regenerate the exact regression #964 guards against. Recommend follow-up: make that test --check-only or run it in a temp dir.