What this fixes

gbrain dream on Postgres (local or Supabase) failed every DB-dependent phase with No database connection: connect() has not been called. lint/backlinks (filesystem-only) worked; sync/synthesize/embed/orphans blew up; extract reported "created 0" while silently dropping every row. Each phase worked in isolation (separate process) — only the full cycle broke, and it left a stuck gbrain_cycle_locks row.

This is the canonical landing for a long-standing class with ~15 competing community PRs and zero merged. Closes #1404, #1471, #1619 (symptom tracked in #1570/#1535).

Root cause (confirmed)

The dream cycle opens one long-lived "owner" connection (the module-level sql singleton in src/core/db.ts). Short-lived "borrower" probe engines (lint config-lift, doctor) open without poolSize, so they share that singleton — but their disconnect() cascaded into db.disconnect() and nulled the singleton the owner was still using. The module sql is only ever nulled by db.disconnect() (postgres.js auto-reconnects its own internal pool and never touches our reference), so the failure was always a borrower-disconnect — never the "idle pooler drop" hypothesized in #1570/#1619. PostgresEngine.disconnect() called db.disconnect() for any _connectionStyle === 'module' engine with no check for whether it actually created the singleton.

Prior partial fixes addressed symptoms: v0.41.27.0's retry-with-reconnect rescued batch phases (extract) but not sync/synthesize (they don't use the retry path); v0.42.5.0 stopped the lint phase from being a borrower but left the structural hole open for every other helper.

The fix

• Ownership token. db.connect() now returns boolean — true iff THIS call created the singleton. The decision is atomic: there's no await between the if (sql) null-check and the synchronous sql = postgres(...) assignment, so two concurrent connects can't both claim creation. PostgresEngine stores it as _ownsModuleSingleton and only calls db.disconnect() when it owns the connection; borrowers clear their own marker and leave the shared pool alone.
• Concurrency hardening (same blast radius): db.disconnect() snapshots + nulls sql before awaiting end() (a concurrent connect can't join a closing pool); PostgresEngine.reconnect() uses a shared in-flight _reconnectPromise (replaces the _reconnecting boolean that returned the 2nd caller immediately against a half-rebuilt pool).
• cli.ts invariant tripwire on the dream owner-disconnect documenting that the owner must outlive its borrowers.

Tests

• New test/postgres-engine-singleton-ownership.test.ts — source-level guardrails for the ownership contract (atomic token, guarded teardown, no TOCTOU pre-sample).
• Expanded DB-gated matrix in test/e2e/postgres-engine-disconnect-idempotency.test.ts — owner/borrower, creation-not-role, symmetric CLI-exit (no hang regression), owner-reconnect-with-live-borrower.
• Module-style getter asymmetry in test/postgres-engine-getter-selfheal.test.ts.
• bug: withRetry doesn't reconnect on 'No database connection' — batch rows lost every dream cycle #1570 shared-recovery regression updated to assert the fixed contract (it had pinned the bug).

Verification: bun run verify 29/29; blast-radius + e2e + migrate suites 254/254 against real Postgres. Full unit matrix runs in CI (the local box couldn't complete it under load).

Review

Ran /plan-eng-review + /review with both Codex and Claude adversarial passes. Both verified the core fix correct. They converged on one concern — per-engine ownership state about a shared resource can desync under concurrent module connect/reconnect — which is not reachable in current gbrain (sequential cycle phases, nested borrowers, instance-engine worker pool, background writes reuse the owner). Captured as a TODOS.md follow-up (the refcount/generation hardening to do before any concurrent-module-connect path is introduced), alongside two other pre-existing items (facts-queue drain on dream/fall-through paths; stale ConnectionManager after reconnect).

Credit

The ownership-flag approach that shipped: @nullhex-io (#1651) and @joelwp (#1667). Root-cause walkthroughs: @BrendanGahan, @xaviroblessarries, and the other #1471 reporters.

🤖 Generated with Claude Code