Summary

v0.31.4.1 still fails to upgrade legacy schema-v10 origin Postgres brains. The forward-reference bootstrap fixes from #776 (lane 1: #740/#741 covering v39–v41) and the mcp_request_log.agent_name work referenced when closing #695/#657 do not cover the v0.13.0 failure point. Migration v0.13.0 ("Frontmatter becomes a graph") trips on column "page_id" does not exist on the files table before the column has been added.

This appears to be the same class as #366 (v0.13.x → v0.18.1, closed as duplicate of #695) and #451 (pre-v17 bootstrap, also closed via #695), but neither was actually patched for the entry point at v0.12 → v0.13.

Environment

• gbrain --version → 0.31.4.1 (master at 943e7b9, post v0.31.4.1 chore: align VERSION + package.json with #795 + mandate 4-segment versions #815)
• Engine: PostgreSQL (Supabase-hosted)
• Brain age: schema v10 → 49 (39 versions behind)
• Brain content: ~12,200 pages, ~30,000 chunks, 100% embed coverage. Brain is fully queryable on the v0.12.2 CLI; queries continue to work on 0.31.4.1 as long as migrations don't run.
• macOS 14, Node.js via Bun

Repro

cd ~/gbrain
git pull   # master at 943e7b9
bun install
# the postinstall (`gbrain apply-migrations --yes --non-interactive`) fires automatically and fails as below
gbrain apply-migrations --yes --non-interactive

Trace (relevant excerpt)

⚠️  Schema version 10 is behind latest 49.
   Schema migrations run automatically on next connectEngine() / initSchema().
   To run them now: gbrain init --migrate-only

Migration v0.12.0 is WEDGED (3+ consecutive partials with no completion).
Check ~/.gbrain/upgrade-errors.jsonl for the last failure reasons, fix the underlying
issue, then run:
  gbrain apply-migrations --force-retry 0.12.0
Then re-run `gbrain apply-migrations --yes`.

=== Applying migration v0.13.0: Frontmatter becomes a graph — company, investors,
attendees now create typed edges automatically ===

=== v0.13.0 — Frontmatter relationship indexing ===

NOTICE: extension "vector" already exists, skipping
NOTICE: extension "pg_trgm" already exists, skipping
NOTICE: extension "pgcrypto" already exists, skipping
NOTICE: relation "sources" already exists, skipping
NOTICE: relation "pages" already exists, skipping
NOTICE: relation "idx_pages_type" already exists, skipping
NOTICE: relation "idx_pages_frontmatter" already exists, skipping
NOTICE: relation "files" already exists, skipping
NOTICE: column "storage_url" of relation "files" does not exist, skipping
NOTICE: relation "idx_files_page" already exists, skipping

column "page_id" does not exist
Migration v0.13.0 reported status=failed.

The idx_files_page "already exists" notice is the smoking gun: the schema replay creates an index on files(page_id) before migration v0.13.0 has added the page_id column. Same class of forward-reference bootstrap bug as #366 / #695, just at a much earlier table/column pair.

The hinted ~/.gbrain/upgrade-errors.jsonl does not exist on this install — that file is never written. (Minor side bug: the wedge-recovery hint should either point to a path that exists or stop suggesting it.)

Why the v0.31.4.1 fix wave didn't help here

PR #776's upgrade-path lane covered:

• fix: bootstrap forward-references for v39-v41 schema replay #741 — bootstrap forward-references for v39–v41 (modality, emotional_weight, effective_date, effective_date_source, import_filename, salience_touched_at)
• fix: three v0.30.0 upgrade-path bugs (deps, UNSAFE_TRANSACTION, missing connect) #740 — three v0.30.0 issues (image-decoder deps, UNSAFE_TRANSACTION on pooled connections, missing connect() in v0.29.1 Phase B+C)
• mcp_request_log.agent_name forward-ref (referenced when closing Forward-reference bootstrap missing mcp_request_log.agent_name — pre-v0.26.3 PGLite brains wedge on upgrade #695)

None of these touch the v0.13.0 → files.page_id path. The same chicken-and-egg pattern lives much earlier in the migration chain than the fixes have reached.

Side bug: postinstall auto-attempts migration

The npm/bun postinstall script runs gbrain apply-migrations --yes --non-interactive automatically. On a wedged brain this means every bun install attempts the migration, fails, and bumps the wedge counter — without the operator opting in. Suggest either gating this behind a GBRAIN_AUTO_MIGRATE=1 env var or running gbrain doctor first and skipping if a migration is already wedged.

Asks

1. Should this reopen Upgrade v0.13.x → v0.18.1 fails on existing Postgres brains: initSchema() runs SCHEMA_SQL before migrations add source_id / page_id #366 or land as a fresh issue covering the schema-v10 → v0.13.0 entry point specifically?
2. Is there a recommended manual ALTER TABLE files ADD COLUMN page_id … shape that would let the v0.13.0 migration proceed on Postgres engines, or is the cleaner path to extend applyForwardReferenceBootstrap() to cover this column too?
3. Confirm whether the wipe-and-reimport escape hatch is still the recommended fallback for brains this old.

Happy to test patches against this exact brain.