Summary

Fix (fix(minions): route lock claim/renewLock through direct session pool): The Minion lock heartbeat (claim + renewLock in src/core/minions/queue.ts) ran every UPDATE through engine.executeRaw(), hardcoded to the read pool. On Supabase that is the transaction-mode pooler (6543), which recycles connections per transaction. A lock is held for minutes, so the pooler periodically reaps the socket mid-heartbeat → CONNECTION_ENDED → the lock looks expired → the worker force-evicts its own job and the claim loop wedges silently (process alive, no errors, claiming nothing). Showed up most under enrich fan-out.

The fix adds BrainEngine.executeRawDirect() — same contract as executeRaw, but routes to the direct session-mode pool (5432, GBRAIN_DIRECT_DATABASE_URL) when dual-pool is active, holding the connection open for the worker's life so heartbeats survive. No-op delegation on PGLite / non-Supabase / kill-switch (GBRAIN_DISABLE_DIRECT_POOL). claim/renewLock now use it. Single-statement UPDATEs only, so the double-claim guard and the renewLock no-inline-retry contract are preserved. Statements inside an open transaction keep their tx connection (in-transaction guard keys on peekReadPool() !== _sql); the lock hot-path never runs inside transaction(). The Postgres impl shares its cancellation plumbing with executeRaw via a private runUnsafe helper.

No new infrastructure — GBRAIN_DIRECT_DATABASE_URL was already configured; this just makes the lock path use the pool built for exactly this workload. Supersedes PR #1816 (closed).

Test Coverage

New test/postgres-execute-raw-direct.test.ts covers the Postgres routing decision (dual-pool on/off × in-tx/not, plus abort short-circuit) with stubbed connections — runs in CI without a live Postgres, the branch the fix exists to exercise. test/queue-lock-retry.test.ts gains a guard that claim can never fall back to executeRaw.

• bun run typecheck — clean repo-wide on the merged state
• Targeted suite — 200 pass / 0 fail (minions, queue-lock-retry, postgres-execute-raw-direct, worker-lock-renewal, postgres-engine-getter-selfheal, postgres-reconnect-singleton)
• 5 project guards green: check-worker-pool-atomicity, check-worker-lock-renewal-shape, check-no-double-retry, check-no-legacy-getconnection, check-jsonb-pattern
• Verified the inTransaction guard survives v0.42.20.0's reconnect-race rework: the instance reconnect path re-runs setReadPool(this._sql), so peekReadPool() === _sql still holds for a live worker.

Pre-Landing Review

/plan-eng-review cleared the change this session. Three findings applied before ship: DRY refactor (shared runUnsafe helper), the routing unit test above, and a P3 follow-up TODO for direct-pool sizing under enrich fan-out.

Design Review

No frontend files changed — design review skipped.

Eval Results

No prompt-related files changed — evals skipped.

Plan Completion

No plan file detected (diff-scoped change reviewed via /plan-eng-review).

TODOS

• Filed P3 — "Size the direct session pool for enrich fan-out" (TODOS.md, Minion-lock direct-pool follow-up section).

Documentation

• docs/architecture/KEY_FILES.md — documented the new BrainEngine.executeRawDirect() contract method (lock-hot-path sibling of executeRaw; routes to the direct session-mode pool when dual-pool is active, PGLite delegates straight to executeRaw) on the src/core/engine.ts entry; noted on the src/core/minions/queue.ts entry that claim/renewLock now issue their UPDATE via executeRawDirect.

Documentation Debt (pre-existing, not introduced here)

• docs/ENGINES.md lists only the transaction pooler (6543) and never documents the dual-pool / direct session-mode (5432) design. Candidate for a follow-up /document-generate pass.

Test plan

• typecheck clean repo-wide
• Targeted lock/engine suite: 200 pass / 0 fail
• 5 lock/pool/jsonb guards green
• CI runs the Postgres e2e suite (engine-parity, reconnect-singleton) which needs a live Postgres service unavailable locally

🤖 Generated with Claude Code