fix(migrations): cold-start robustness in apply-migrations + v0.29.1 orchestrator

[knee5]

Summary

Two bugs found during clevin's gbrain v0.22 → v0.30.1 migration on 2026-05-08 that together cause gbrain apply-migrations --yes to fail from any cold-start state (pre-v0.28 or pre-v0.30 schema). Both fixes make the command "just work" in one shot without flags or workarounds, completing the operational hardening intent stated in v0.30.1's release notes.

---

Bug 1 — v0.29.1 phaseBBackfill / phaseCVerify missing engine.connect()

File: src/commands/migrations/v0_29_1.ts

Symptom: During gbrain apply-migrations --yes on a schema at v29 or below, Phase B fails immediately with: "No database connection". Phase C has the same bug.

Root cause: Both phases called createEngine(config) to instantiate the engine but never called await engine.connect(engineConfig). createEngine returns an unconnected instance; connect is the separate lifecycle call that establishes the pool. Compare the v0.28.0 orchestrator (the established pattern) — it calls await engine.connect(engineConfig) in its shared setup block right after createEngine.

Repro:

1. Schema at v29 (or any pre-v30 version)
2. gbrain apply-migrations --yes
3. Phase A succeeds (DDL via gbrain init --migrate-only); Phase B (phaseBBackfill) throws "No database connection"

Workaround used (2026-05-08): gbrain reindex-frontmatter directly (examined=2286, updated=2286, fallback=1616, 467 s), then manually appended a complete row to ~/.gbrain/migrations/completed.jsonl.

Patch: Added await engine.connect(engineConfig) immediately after createEngine(engineConfig) in both phaseBBackfill and phaseCVerify, plus try/finally + engine.disconnect() for resource cleanup — matching the v0.28.0 pattern exactly.

---

Bug 2 — v0.28.0 Phase A aborts instead of applying schema on cold-start

File: src/commands/migrations/v0_28_0.ts

Symptom: gbrain apply-migrations --yes on a brain upgrading from v0.22 (or any pre-v0.28 version) fails with: "expected schema version >= 38 (takes + access_tokens.permissions); got <N>". The command exits 1 before doing any work.

Root cause: v0.28.0 Phase A was a pure verify: it checked schema_version >= 38 and returned status: 'failed' if behind. The design comment says "the schema runner does the actual DDL during gbrain upgrade/initSchema" — but on a direct install upgrade (not via gbrain upgrade), the DDL hasn't run yet.

Diagnosis: The --force-schema flag in apply-migrations.ts calls runMigrations(eng) in-process to resolve exactly this drift. The two-step workaround (--force-schema --yes then --yes) works because --force-schema brings the DDL to LATEST_VERSION before the orchestrator chain starts.

Patch: When Phase A detects schema < 38, call await engine.initSchema() inline (the engine is already connected via the v0.28.0 shared orchestrator setup block) before the post-condition table check. Re-reads the version after apply to surface any partial DDL failure clearly. This makes apply-migrations --yes succeed from any starting schema version in one shot.

Workaround used (2026-05-08):

gbrain apply-migrations --force-schema --yes
gbrain apply-migrations --yes

---

Testing

• Added test/migration-orchestrator-v0_29_1.test.ts — registry, phase shape, and dry-run assertions following the migration-orchestrator-v0_21_0.test.ts style.
• All existing unit tests pass: bun test test/migration-orchestrator-v0_29_1.test.ts test/migrations-registry.test.ts test/apply-migrations.test.ts → 32 pass, 0 fail.
• Build note: bun build --compile fails on missing optional packages (heic-decode, @jsquash/png) in the checkout — pre-existing, not introduced by this PR.

---

Discovered during

clevin's gbrain v0.22.2 → v0.30.1 migration on 2026-05-08. These fixes complete the intent of v0.30.1's "operational hardening — make upgrades just work on Supabase" release note: with both patches, gbrain apply-migrations --yes succeeds from any pre-v0.30 starting state without flags or manual workarounds.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews