v0.41.5.0 fix-wave: warm-narwhal — 6 community PRs + E2E reliability (#1374)

* fix(recipes/openai): add max_batch_tokens to embedding touchpoint OpenAI is the only recipe in the codebase without a max_batch_tokens cap. Every other provider declares one (voyage=120K, azure-openai=8K, dashscope=8K, zhipu=8K, minimax=4K). Without it, gbrain's recursive-halving safety net never engages — batches dispatched purely on the char/4 estimator window will trip OpenAI's 1M-token TPM ceiling on token-dense pages (Discord exports, JSON dumps, code-heavy markdown), then retry storm and block the queue head. Setting cap to 100_000: - gbrain's batcher estimates tokens as chars/4 - Token-dense markdown+JSON tokenizes at ~chars/2.7 - 100K estimated = ~150K real worst-case, safely under OpenAI's 300K per-request hard cap and the 1M/min TPM ceiling - Leaves headroom for recursive-halving on outlier chunks (cherry picked from commit 40536aace5) * fix(ai/embed): recognize OpenAI 'maximum request size' error in isTokenLimitError OpenAI's /v1/embeddings endpoint hard-caps a single request at 300k tokens total across all input items. When the cap is exceeded it returns: Invalid 'input': maximum request size is 300000 tokens per request. None of the three existing regexes in isTokenLimitError matched this phrasing, so the recursive-halving safety net in embedSubBatch never engaged for OpenAI. The same fat page (a token-dense markdown export, e.g. a Discord transcript) would re-fail every pass, blocking forward progress on the whole batch indefinitely. Locally reproduced on a 31,129-chunk Postgres brain: 2,125 chunks stuck at 'remaining' across 30+ embed --stale passes with retry loops + sleep delays. Adding the two new patterns lets halving fire; the same backlog cleared in one pass after the regex change (the companion max_batch_tokens recipe fix from PR #924 caps fresh batches, but existing oversize pages still need halving to recover). Adds: - /maximum request size.*tokens/i — OpenAI verbatim - /max.*tokens.*per.*request/i — defensive against minor rewording Tests: - Regression test for the exact OpenAI error string - Coverage for the generic 'max tokens per request' variant - All 25 tests in adaptive-embed-batch.test.ts pass No behavior change for providers whose errors already matched. (cherry picked from commit b834e84c56) * fix(connection-manager): strip .<project-ref> suffix from username when deriving direct URL `deriveDirectUrl()` correctly rewrites the host (`aws-0-us-east-1.pooler.supabase.com` → `db.abcxyz.supabase.co`) but preserves the full pooler-form username (`postgres.abcxyz`). Supabase direct connections expect a bare `postgres` username — Supavisor uses the `.<ref>` suffix for tenant routing, but it's not a real database user. The auto-derived URL therefore fails to authenticate even with the correct password: password authentication failed for user "postgres.abcxyz" Strip the suffix to `postgres` whenever the project-ref was successfully extracted (same condition that triggers the host rewrite). The non-pooler username branch is unaffected — preserved as-is to keep the port-only fallback case working. Hit while exercising v0.30.1's dual-pool routing on a real Supabase brain; the kill switch (`GBRAIN_DISABLE_DIRECT_POOL=1`) papered over it locally but every Supabase user with a stock pooler URL would silently fall through to single-pool until the user-supplied a `GBRAIN_DIRECT_DATABASE_URL` override. With this fix, dual-pool works out of the box for the canonical Supabase shape. Test additions: - 1 case asserting bare `postgres:secret@` in the derived URL when project-ref is parseable from the pooler URL (the new behavior) - extends the existing "falls back to port-only" case with an assertion that non-pooler usernames are preserved (unchanged behavior) `bun run typecheck` clean. `deriveDirectUrl` test block passes 5/5. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> (cherry picked from commit ddf2c6a9a0) * fix(init): --help should not mutate config or scan filesystem `gbrain init --help` (and `-h`) currently fall through to the smart-detection branch in runInit(), which scans cwd for .md files and on a directory with 1000+ files prints "Found ~1500 .md files. For a brain this size, Supabase gives faster search..." then defaults to PGLite — calling saveConfig() and overwriting any existing Postgres config with `engine: 'pglite' + database_path: ~/.gbrain/brain.pglite`. Confirmed in the wild: ran `gbrain init --help` from $HOME on a machine where ~/.gbrain/config.json pointed at a Supabase Postgres brain with 10K+ pages. The config was silently flipped to PGLite. The Supabase data was intact, but gbrain stopped pointing at it until the config was manually restored. Root cause: cli.ts:62-69 only routes --help → printOpHelp() for shared-op commands; CLI_ONLY commands (init, embed, etc.) fall through to their handler with --help still in argv. None of them check for it. Fix: add a --help/-h guard at the top of runInit() that prints help text and returns. Help should never mutate state — Postel's robustness principle for CLI tools. Help text covers all flags (engine selection, AI provider options, thin-client mode) so users running `--help` get the canonical list rather than having to read the source. A wider architectural fix — adding --help routing for all CLI_ONLY commands in cli.ts — is plausible follow-up, but each CLI_ONLY command would still need its own help text. This per-command pattern matches how shared ops handle it via printOpHelp(). Init is the highest-stakes case because it's the only CLI_ONLY command that calls saveConfig(). Smoke test: from a directory with 1500 .md files, with GBRAIN_HOME pointed at a fresh tempdir: - Before fix: ~/.gbrain/config.json materialized with engine: 'pglite' - After fix: help text printed, no config dir created `bun run typecheck` clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> (cherry picked from commit ed11fdd58c) * test(frontmatter-install-hook): isolate hooksPath assertion from developer global config The "installHook writes ... and sets core.hooksPath" test asserted `git config --get core.hooksPath` returns `.githooks`, which falls back to the global scope when local is unset. Developers who set `core.hooksPath` globally (common with dotfiles managers pointing at ~/.config/git/hooks) saw a deterministic FAIL because installHook intentionally respects an existing global value and skips writing the local one — exactly the documented contract. Fix: read via `git config --local --get core.hooksPath` (scope-locked) and branch the assertion on whether a global is already set. Both clean-CI (local should be '.githooks') and developer-with-global (local should be empty; installHook correctly didn't clobber) now pass deterministically. No API change. installHook behavior is unchanged. Verified locally with the affected test passing under `GIT_CONFIG_GLOBAL=~/.gitconfig` carrying `core.hooksPath=...`. (cherry picked from commit 0e4da2cb38) * fix: guard against missing 'intent' field in routing-eval fixtures Two defensive fixes: 1. normalizeText(): return empty string on null/undefined input instead of crashing with 'undefined is not an object (evaluating s.toLowerCase)' 2. loadRoutingFixtures(): validate that parsed fixture has 'intent' as a string before adding to fixtures array. Fixtures with wrong field names (e.g. 'input' instead of 'intent') are now reported as malformed with a helpful error message listing the actual keys found. Root cause: a skill's routing-eval.jsonl used {"input": ...} instead of {"intent": ...}. The JSON parsed fine but the cast to RoutingFixture was unchecked, so fixture.intent was undefined. normalizeText(undefined) then crashed. This made 'gbrain doctor' completely unusable. (cherry picked from commit b142bbdb0d) * fix(test): isolate HOME in run-e2e.sh to stop config corruption Replaces #517 (re-ported fresh against current scripts/run-e2e.sh after v0.23.1 rewrote the script — original cherry-pick would not apply). E2E tests call setupDB which writes $HOME/.gbrain/config.json pointing at the docker test container. When the container tears down, the user's real autopilot daemon wedges trying to connect to a vanished postgres. Three operators hit this within 16 days before the original PR filed. Fix: wrapper exports HOME + GBRAIN_HOME to a mktemp tmpdir BEFORE bun starts so config writes land in the tmpdir, with a post-run breach detector that compares md5 of the user's real config against pre-run. Both env vars required: loadConfig/saveConfig resolve via HOME while configPath honors GBRAIN_HOME. HOME set before bun starts because os.homedir() caches at first call. Test seam: test/gbrain-home-isolation.test.ts updated to assert against homedir() === configDir() when GBRAIN_HOME unset (correct under the safety wrapper itself) instead of the prior "not /tmp/" sentinel. Revert path: git revert <this-sha> if test:e2e regresses on master. Co-Authored-By: orendi84 <orendi84@users.noreply.github.com> * test(dream-cycle): add schema-suggest to EXPECTED_PHASES v0.40.7.0 Schema Cathedral v3 added the 'schema-suggest' phase between 'orphans' and 'purge' in ALL_PHASES, but the E2E phase-order test was not updated to match. ALL_PHASES vs EXPECTED_PHASES diverged and the shape-pin test failed every run on master. Surfaced during fix-wave: warm-narwhal E2E gate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(autopilot-fanout): use relative timestamp inside freshness window The 'end-to-end: updateSourceConfig persists timestamp visible to next listAllSources' test pinned last_full_cycle_at to a hardcoded '2026-05-22T15:00:00.000Z'. The 60-minute freshness window passed within ~1 hour of write — every run after the deadline classified the source as stale and dispatched it, breaking the test's .skippedFresh expectation. Switch to Date.now() - 30min relative timestamp (mirrors the prior 'source with last_full_cycle_at < 60min ago is skipped by gate' test). Surfaced during fix-wave: warm-narwhal E2E gate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(fresh-install-pglite): unset other provider keys in beforeEach init.ts:455 fails loud when multiple embedding providers are env-ready in non-TTY mode. The test sets ZEROENTROPY_API_KEY then runs init, but developer machines commonly have OPENAI_API_KEY + VOYAGE_API_KEY + ZEROENTROPY_API_KEY all set, so init sees 3 providers and exits 1. Save+unset OPENAI_API_KEY + VOYAGE_API_KEY in beforeEach, restore in afterEach. Now only ZE is env-ready, init picks it, schema sized to zembed-1's 1280d as the test expects. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(voyage-multimodal): switch fixture from AVIF to PNG Voyage's /multimodalembeddings endpoint rejects AVIF as of 2026-05 with 'Please provide a valid base64-encoded image'. The prior comment ('AVIF is fine for an embed call') held at v0.27.x and regressed silently on the provider side. Add test/fixtures/images/tiny.png (16x16 RGB PNG, 1307 bytes generated via sips from the macOS default wallpaper). PNG is universally accepted by Voyage and other multimodal providers. Surfaced during fix-wave: warm-narwhal E2E gate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(cycle/synthesize): prefix bare anthropic model ids before queue.add queue.add's subagent capability validator (classifyCapabilities → resolveRecipe) requires provider:model format and rejects bare ids with 'unknown provider'. resolveModel returns the bare id from TIER_DEFAULTS / DEFAULT_ALIASES (e.g. 'claude-sonnet-4-6'), which the validator then rejects, dropping the synthesize phase to status:fail with SYNTH_PHASE_FAIL. Narrow fix at the call site: if config.model has no colon AND starts with 'claude-', prefix 'anthropic:'. Other providers must already declare a colon. Avoids changing TIER_DEFAULTS / DEFAULT_ALIASES constant shapes, which would ripple across every resolveModel caller. Surfaced by dream-synthesize-chunking E2E during fix-wave: warm-narwhal. Affected tests: 'single-chunk transcript uses legacy idempotency key' and 'multi-chunk transcript spawns N children with chunk-suffixed idempotency keys' — both relied on result.details.children_submitted which only the ok() path sets; the failed() path returns details: {}. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(mechanical): pin doctor init embedding model + clean non-default sources Two fixes in the E2E Doctor Command describe block, both surfaced by cross-file state pollution under the full sequential E2E run: 1. Pass --embedding-model openai:text-embedding-3-large to the init subprocess. Without the explicit flag, doctor inherits whatever the resolver picks from env keys (ZE if ZEROENTROPY_API_KEY is set, defaulting to zembed-1 at 1280d). The test's setupDB initialized schema at 1536d, so the dim mismatch fires embedding_width_consistency WARN, exiting doctor 1. 2. DELETE FROM sources WHERE id != 'default' in beforeAll. Prior E2E files leave non-default source rows (e.g. 'delta' from autopilot / sources tests). sync_freshness + cycle_freshness then FAIL on those orphans because they were never synced/cycled, exiting doctor 1. setupDB TRUNCATEs sources but schema.sql re-seeds 'default' via initSchema; this leaves only the canonical single-source brain the test expects. Surfaced during fix-wave: warm-narwhal E2E gate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(run-e2e): per-file connection flush + 180s outer timeout Two cross-file isolation hardenings for the sequential E2E runner: 1. Terminate stale Postgres connections before each file. Without this, idle connections from the prior bun process's pool race with the next file's setupDB() TRUNCATE CASCADE, producing 'fixture pages disappear mid-test' failures. The terminate call is idempotent + ~50ms; first iteration is a no-op. 2. Hard outer timeout (180s per file) via gtimeout / timeout. bun's --timeout=60000 is per-test; if a PGLite WASM call hangs in beforeAll/afterAll (e.g. ingestion-roundtrip.test.ts wedging 30+ minutes on macOS), --timeout never fires and the entire suite wedges. Outer SIGKILL lets the suite advance and the file is recorded as failed for triage. Falls through to bare bun if neither gtimeout nor timeout is on PATH. Surfaced during fix-wave: warm-narwhal — 3 of 5 cross-file flakes caught by the connection flush; ingestion-roundtrip 30-min wedge caught by the outer timeout. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v0.41.3.0) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs: annotate synthesize.ts narrow prefix fix (v0.41.3.0) CLAUDE.md gains the v0.41.3.0 note on src/core/cycle/synthesize.ts (narrow anthropic: prefix at the queue.add boundary so resolveModel's bare ids satisfy the subagent validator). llms-full.txt regenerated to match. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * chore: rebump v0.41.3.0 → v0.41.5.0 (queue drift; PR #1377 claimed .4.0) Sibling fix-wave PR #1377 (garrytan/community-pr-wave) claimed v0.41.4.0 between my queue check (.3.0 was available) and PR creation. Re-bump to the next available slot per workspace-aware allocator. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(cycle/synthesize): refuse empty brainDir + resolve relative paths Pre-fix, runPhaseSynthesize accepted any brainDir string and passed it to writeReversePages which does join(brainDir, '<slug>.md'). When brainDir is '' or relative ('.' / './brain' / etc), join() produces a relative path that writeFileSync resolves against cwd. Result: every synthesize reverse-write spills into <cwd>/companies/<slug>.md, <cwd>/people/<slug>.md, etc. instead of the intended brainDir tempdir. Surfaced by the warm-narwhal wave when E2E test cleanup found orphan synthesize pages (companies/novamind.md, people/sarah-chen.md, meetings/2025-04-01-novamind-board-update.md) at the gbrain repo root from a runCycle({brainDir: '.'}) chain that ran during morning E2E execution. Fix at the function entry, single location, all callers protected: 1. Empty/whitespace brainDir → return failed(BRAINDIR_EMPTY) loud instead of silently resolving against cwd 2. Relative brainDir → resolve(opts.brainDir) before any read/write can use it. opts.brainDir mutated so writeReversePages, writeSummaryPage, and every join() downstream see the absolute path Regression test pins all 4 contracts: - empty string → fail(BRAINDIR_EMPTY) - whitespace-only → fail(BRAINDIR_EMPTY) - '.' → mutated to absolute on entry - already-absolute → unchanged Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(dream): resolve brainDir to absolute at CLI surface Defense-in-depth for the synthesize-braindir spillage bug class. The core fix lives in runPhaseSynthesize (commit 98222a08); this resolves brainDir one layer earlier so the entire 9-phase runCycle gets the absolute path, not just synthesize. Two paths in resolveBrainDir get path.resolve(): - explicit --dir argument (e.g., `gbrain dream --dir .`) - sync.repo_path config (in case it was ever stored relative) resolveBrainDir already checked existsSync; resolve() just canonicalizes before return. No behavior change for paths already absolute. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Matt Gunnin <mgunnin@esports.one> Co-authored-by: Brandon Lipman <brandon@offdeck.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Jeremy Knows <jeremy@veefriends.com> Co-authored-by: root <root@localhost> Co-authored-by: orendi84 <orendigergo@gmail.com> Co-authored-by: orendi84 <orendi84@users.noreply.github.com> Co-authored-by: Garry Tan <garry@ycombinator.com>
2026-07-27 21:19:18 +00:00 · 2026-05-25 12:48:55 -07:00
parent dab441f59f
commit e084457c2d
18 changed files with 325 additions and 17 deletions
@@ -2,6 +2,45 @@

 All notable changes to GBrain will be documented in this file.

+## [0.41.5.0] - 2026-05-24
+
+**Six community bug-fix PRs land + the E2E suite stops lying about itself.** A fix-wave triage swept the 333-PR queue, closed 10 PRs as already-shipped (with credit, naming the commits + files), and bundled 6 real fixes from the community into one collector. Plus three E2E-suite reliability fixes that surfaced while getting the full Docker suite to 100% green.
+
+You can now run `gbrain init --help` from inside a directory with 1000+ markdown files without it silently overwriting your Supabase config with PGLite. Your Supabase brain stops auth-failing at the direct connection because the pooler-form `postgres.<ref>` username now gets stripped before deriving the direct URL. OpenAI embedding batches that hit the 1M-token TPM ceiling actually engage the recursive-halving safety net (the `Invalid 'input': maximum request size is 300000 tokens per request.` error message now matches the recognition regex; pre-fix it never fired). The dream-cycle's synthesize phase stops dying with `subagent job rejected: data.model "claude-sonnet-4-6" references an unknown provider` because the queue.add subagent validator now sees `anthropic:claude-sonnet-4-6` from a narrow prefix-fix at the call site.
+
+To turn it on: `gbrain upgrade`. The contributor closure comments include the exact commit SHA + file:line that already shipped each fix, so anyone who filed a duplicate or stale PR can verify the work landed.
+
+What you'd see in a concrete example. Pre-this-release: `gbrain init --help` from `~/Documents` (with 1500+ `.md` files inferred as a brain candidate) writes `engine: 'pglite'` + `database_path: ~/.gbrain/brain.pglite` to your real config, silently disconnecting you from Supabase. Post-fix: `--help` short-circuits before any state write; help text prints; config untouched. Same shape for the other five fixes: documented bugs, real repros, real fixes, real tests.
+
+Things to know about. (1) Two cross-file E2E reliability fixes in `scripts/run-e2e.sh`: per-file `pg_terminate_backend` flush kills stale connections from the prior bun process before the next file's `setupDB()` TRUNCATE races them, AND a hard 180s outer `gtimeout`/`timeout` cap so a wedged PGLite WASM call in beforeAll/afterAll can't pin the entire suite (this caught a real 30+ min wedge on `ingestion-roundtrip.test.ts` during the wave). (2) The `gbrain doctor` test in `test/e2e/mechanical.test.ts` now pins `--embedding-model openai:text-embedding-3-large` on its init step (was inheriting whatever the resolver picked from env keys, producing dim-mismatch warnings under sequential E2E) and `DELETE FROM sources WHERE id != 'default'` in beforeAll (was inheriting orphan `delta` source rows from prior files, producing `sync_freshness FAIL`).
+
+Credit to the 6 community contributors whose PRs landed: @mgunnin (x2: max_batch_tokens + isTokenLimitError regex), @brandonlipman (x2: connection-manager username strip + init --help guard), @jeremyknows (frontmatter-install-hook test isolation), @garrytan-agents (routing-eval intent-field guard). Plus 10 superseded PRs closed with credit (#798, #1083, #918, #1119, #602, #758, #539, #1287, #1117, #1125) — fix already on master via prior waves (v0.31.7 #804 + v0.36.1.1 #1182 + v0.38.2.0 #1297 + others); contributor closures cite each landing commit + file location.
+
+### Itemized changes
+
+**The 6 community fix-wave cherry-picks:**
+
+- **#924 (mgunnin):** `src/core/ai/recipes/openai.ts` gains `max_batch_tokens: 100_000` on the embedding touchpoint. Pre-fix OpenAI was the only recipe missing this cap; the recursive-halving safety net never engaged on token-dense pages (Discord exports, JSON dumps, code-heavy markdown), then retry storm and block the queue head. 100K estimated = ~150K real worst-case, safely under OpenAI's 300K per-request hard cap.
+- **#990 (mgunnin):** `src/core/ai/gateway.ts:1264` `isTokenLimitError` now matches `maximum request size.*tokens` so OpenAI's actual error string triggers recursive halving. Pre-fix the regex caught Voyage and generic shapes but not OpenAI's literal wording. Tests in `test/ai/adaptive-embed-batch.test.ts` pin the recognition.
+- **#761 (brandonlipman):** `src/core/connection-manager.ts:144-148` `deriveDirectUrl` now strips the `postgres.<ref>` pooler-form username down to bare `postgres` when synthesizing the Supabase direct URL. Pre-fix Supabase direct connections silently failed auth because they expect bare `postgres` (the `.<ref>` suffix is a pooler-routing-only thing). Tests in `test/connection-manager.serial.test.ts`.
+- **#762 (brandonlipman):** `src/commands/init.ts:13-16` adds a `--help`/`-h` short-circuit at the top of `runInit`. Pre-fix `gbrain init --help` from a directory with many `.md` files would fall through to smart-detection, scan cwd, then `saveConfig()` — silently overwriting any existing Postgres config with PGLite defaults. Confirmed in the wild on a 10K-page Supabase brain.
+- **#916 (jeremyknows):** `test/frontmatter-install-hook.test.ts` test isolation fix — uses `--local --get` instead of `--get` (which falls back to global config). Without this, developers with `core.hooksPath` set globally (dotfiles managers pointing at `~/.config/git/hooks`) see a deterministic FAIL.
+- **#1332 (garrytan-agents):** `src/core/routing-eval.ts` adds defensive guard so `loadRoutingFixtures({intent: undefined})` doesn't crash `gbrain doctor` with `undefined is not an object (evaluating s.toLowerCase)`. Fixture validation now reports malformed entries instead of crashing the whole doctor run.
+
+**Three E2E reliability fixes (surfaced during this wave):**
+
+- **`src/core/cycle/synthesize.ts:395-404`** narrow `anthropic:` prefix fix at the queue.add boundary. `resolveModel` returns the bare id from `TIER_DEFAULTS`/`DEFAULT_ALIASES` (e.g. `claude-sonnet-4-6`); the subagent validator requires `provider:model` and rejected with `unknown provider`, dropping synthesize to `status: fail` with `SYNTH_PHASE_FAIL`. Narrow conditional prefix at the call site (only when no colon AND starts with `claude-`) avoids changing the constants which would ripple across every `resolveModel` caller.
+- **`scripts/run-e2e.sh` per-file connection flush + outer timeout.** Two cross-file isolation hardenings: (1) `psql -At -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid != pg_backend_pid() AND datname = current_database()"` before each file kills idle connections from the prior bun process's pool, which were racing with the next file's `TRUNCATE CASCADE` and producing 'fixture pages disappear mid-test' failures; (2) hard 180s outer `gtimeout`/`timeout` cap so a PGLite WASM hang in beforeAll/afterAll can't wedge the entire suite. Both surfaced during the wave: 3 of 5 cross-file flakes caught by the connection flush; `ingestion-roundtrip` 30-min wedge caught by the outer timeout.
+- **`test/e2e/mechanical.test.ts` doctor test hardening.** Two fixes: pin `--embedding-model openai:text-embedding-3-large` on the init subprocess (was inheriting env-resolver defaults that produced dim-mismatch under sequential E2E); `DELETE FROM sources WHERE id != 'default'` in beforeAll (was inheriting orphan `delta` source rows from prior files, producing `sync_freshness FAIL`).
+
+### For contributors
+
+Wave triage process notes:
+- 333-PR queue evaluated via per-PR isolation runs + cross-reference against master HEAD (the load-bearing trick: read each PR's diff against its OWN base, not against current master, to see the actual intended change without v0.38-0.40 reverts contaminating the view).
+- 10 PRs closed-as-superseded with credit comments citing the landing commit SHA + file:line so contributors can verify the fix shipped. The contributor close template is captured in `~/.claude/plans/time-for-fix-wave-warm-narwhal.md`.
+- 2 mid-wave additional supersession discoveries (PR #1117 + PR #1125) caught via the `git log -S "configuredProviderIds" origin/master` pattern after master had already absorbed them via v0.36.1.1 #1182 (28-fix collector from 5 weeks ago); both closed with credit pointing at the absorbed commit.
+- Tests on the wave reached 117/117 files / 821/821 tests pass against fresh Docker pgvector container after fixing the cross-file flake class.
+
 ## [0.41.4.0] - 2026-05-24

 **Run your embedder, your reranker, and your dream judge on your own hardware. Windows users can pipe into `gbrain` like everyone else.** Three community PRs land together in one wave that takes gbrain's "local AI" story from "kinda" to "first-class." If you point gbrain at a llama.cpp embedding server, an Ollama box, or a self-hosted llama.cpp running Qwen3-Reranker, the doctor / autopilot / budget / models surfaces all treat them as real providers. The dream-cycle significance judge stops being hardcoded to Anthropic — point it at DeepSeek or any other registered chat provider via one config line. And `gbrain put my-slug` finally reads stdin correctly on Windows.
@@ -1 +1 @@
-0.41.4.0
+0.41.5.0
@@ -1,6 +1,6 @@
 {
  "name": "gbrain",
-  "version": "0.41.4.0",
+  "version": "0.41.5.0",
  "description": "Postgres-native personal knowledge brain with hybrid RAG search",
  "type": "module",
  "main": "src/core/index.ts",
@@ -134,7 +134,29 @@ for f in "${files[@]}"; do
  name=$(basename "$f")
  echo ""
  echo "=== $name ==="
-  if output=$(bun test --timeout=60000 "$f" 2>&1); then
+  # Cross-file isolation: terminate any stale connections from the prior
+  # file's pool before the next file's setupDB() runs. Without this,
+  # idle postgres connections from the previous bun process race with
+  # the next file's TRUNCATE CASCADE → cross-file fixture-state pollution
+  # (people/sarah-chen disappears mid-test, etc.). The terminate call is
+  # idempotent + fast (~50ms); on the first iteration there's nothing to
+  # terminate so it's effectively free.
+  if [ -n "${DATABASE_URL:-}" ]; then
+    psql "$DATABASE_URL" -At -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid != pg_backend_pid() AND datname = current_database()" >/dev/null 2>&1 || true
+  fi
+  # Hard outer timeout (180s per file). bun's --timeout is per-test; if a
+  # PGLite WASM call hangs in beforeAll/afterAll, --timeout never fires and
+  # the file wedges indefinitely. gtimeout/timeout SIGKILLs the file so the
+  # suite advances. gtimeout (macOS via coreutils) preferred; timeout (Linux)
+  # fallback; bare bun (no outer cap) if neither is installed.
+  if command -v gtimeout >/dev/null 2>&1; then
+    TIMEOUT_CMD="gtimeout 180"
+  elif command -v timeout >/dev/null 2>&1; then
+    TIMEOUT_CMD="timeout 180"
+  else
+    TIMEOUT_CMD=""
+  fi
+  if output=$($TIMEOUT_CMD bun test --timeout=60000 "$f" 2>&1); then
    pass_files=$((pass_files + 1))
    # Extract pass/fail counts from bun's summary (e.g., "123 pass")
    p=$(echo "$output" | grep -oE '[0-9]+ pass' | tail -1 | grep -oE '[0-9]+' || echo 0)
@@ -31,6 +31,7 @@ import {
  type CycleReport,
 } from '../core/cycle.ts';
 import { existsSync } from 'fs';
+import { resolve } from 'node:path';

 interface DreamArgs {
  json: boolean;
@@ -144,13 +145,15 @@ async function resolveBrainDir(
      console.error(`--dir path does not exist: ${explicit}`);
      process.exit(1);
    }
-    return explicit;
+    // Resolve to absolute so downstream writeFileSync(join(brainDir, slug))
+    // can't silently land at cwd when explicit is `.` / `./brain` / etc.
+    return resolve(explicit);
  }

  if (engine) {
    const configured = await engine.getConfig('sync.repo_path');
    if (configured && existsSync(configured)) {
-      return configured;
+      return resolve(configured);
    }
  }

@@ -11,6 +11,20 @@ import { createEngine } from '../core/engine-factory.ts';
 import { discoverOAuth, mintClientCredentialsToken, smokeTestMcp } from '../core/remote-mcp-probe.ts';

 export async function runInit(args: string[]) {
+  // Help guard: cli.ts only routes --help to printOpHelp() for shared-op
+  // commands; CLI_ONLY commands (init, embed, etc.) fall through to their
+  // handler with --help in argv. Without this guard, `gbrain init --help`
+  // proceeds into the smart-detection branch below, scans cwd for .md files,
+  // and on a directory with 1000+ files (e.g. $HOME for someone whose brain
+  // and notes share a root) silently overwrites the existing Supabase config
+  // with a fresh PGLite brain at ~/.gbrain/brain.pglite. Confirmed in the
+  // wild — flipped a working `engine: postgres` config to `engine: pglite`
+  // on a brain with 10K+ pages. Help should never mutate state.
+  if (args.includes('--help') || args.includes('-h')) {
+    printInitHelp();
+    return;
+  }
+
  const isSupabase = args.includes('--supabase');
  const isPGLite = args.includes('--pglite');
  const isMcpOnly = args.includes('--mcp-only');
@@ -1401,3 +1415,48 @@ export function reportModStatus(): void {
  console.log('Soul audit: run `gbrain soul-audit` to customize agent identity');
  console.log('');
 }
+
+function printInitHelp() {
+  console.log(`
+gbrain init — initialize a brain (PGLite or Supabase Postgres)
+
+USAGE
+  gbrain init [flags]
+
+ENGINE SELECTION (mutually exclusive)
+  --pglite              Use embedded PGLite (zero-config, default for <1000 .md files)
+  --supabase            Use Supabase Postgres (recommended for 1000+ files)
+  --url <URL>           Use a manual Postgres connection string
+  --mcp-only            Thin-client mode: connect to a remote gbrain MCP, no local engine
+
+OPTIONS
+  --force               Overwrite an existing config (gated by default)
+  --non-interactive     Don't prompt; use defaults
+  --migrate-only        Apply pending schema migrations against the configured engine
+                        without re-saving config (used by post-upgrade and orchestrators)
+  --json                JSON output for status reporting
+  --path <DIR>          Override default brain path (PGLite only)
+  --key <APIKEY>        Provide an API key non-interactively (Supabase only)
+  --embedding-model <PROVIDER:MODEL>
+                        e.g. openai:text-embedding-3-large, voyage:voyage-multimodal-3
+  --model <PROVIDER>    Shorthand: pick recipe default for a provider
+  --embedding-dimensions <N>
+                        Embedding dimensions (must match the model)
+  --expansion-model <PROVIDER:MODEL>
+                        Model for query expansion (default: anthropic:claude-haiku)
+  --chat-model <PROVIDER:MODEL>
+                        Default subagent driver (v0.27+)
+
+EXAMPLES
+  gbrain init --pglite                      # Local-only, no API keys
+  gbrain init --supabase                    # Interactive Supabase setup
+  gbrain init --url postgresql://...        # Use a custom Postgres
+  gbrain init --mcp-only --url https://...  # Thin-client mode
+
+NOTES
+  - Bare \`gbrain init\` in a directory with 1000+ .md files defaults to Supabase
+    interactive setup. With <1000 files (or with --pglite explicitly), defaults
+    to PGLite at ~/.gbrain/brain.pglite.
+  - Existing config is preserved unless --force is passed.
+`.trim());
+}
@@ -1259,7 +1259,10 @@ export function isTokenLimitError(err: unknown): boolean {
  return (
    /max.*allowed.*tokens.*batch/i.test(msg) ||
    /batch.*too.*many.*tokens/i.test(msg) ||
-    /token.*limit.*exceeded/i.test(msg)
+    /token.*limit.*exceeded/i.test(msg) ||
+    // OpenAI embeddings: "Invalid 'input': maximum request size is 300000 tokens per request."
+    /maximum request size.*tokens/i.test(msg) ||
+    /max.*tokens.*per.*request/i.test(msg)
  );
 }

@@ -17,6 +17,12 @@ export const openai: Recipe = {
      dims_options: [256, 512, 768, 1024, 1536, 3072],
      cost_per_1m_tokens_usd: 0.13,
      price_last_verified: '2026-04-20',
+      // OpenAI per-request hard cap is 300K tokens. Free/Tier-1 TPM is 1M.
+      // Cap batches conservatively at 100K to handle token-dense content
+      // (Discord/Slack markdown+JSON tokenizes at ~chars/2.7, not the chars/4
+      // estimate the batcher uses). 100K estimated = ~150K real tokens worst-case,
+      // safely under both the 300K per-request and 1M TPM ceilings.
+      max_batch_tokens: 100_000,
    },
    expansion: {
      models: ['gpt-5.2', 'gpt-4o-mini'],
@@ -142,16 +142,22 @@ export function deriveDirectUrl(url: string): string | null {
    const decodedUser = decodeURIComponent(user);
    const refMatch = decodedUser.match(/^postgres\.([a-z0-9]+)$/i);
    let directHost = hostname;
+    let directUser = parsed.username;
    if (refMatch && refMatch[1] && isPoolerHost) {
      directHost = `db.${refMatch[1]}.supabase.co`;
+      // Supabase direct connections use bare `postgres`; the `postgres.<ref>`
+      // form is pooler-only (Supavisor uses the suffix for tenant routing).
+      // Without this strip, direct auth fails with `password authentication
+      // failed for user "postgres.<ref>"` even though the password is correct.
+      directUser = 'postgres';
    }
    // Compose direct URL by swapping host + port. Preserve auth, db, query.
    parsed.hostname = directHost;
    parsed.port = '5432';
    // Reconstruct with the original scheme.
    const scheme = url.match(/^postgres(?:ql)?:\/\//i)?.[0] ?? 'postgres://';
-    const auth = parsed.username
-      ? `${parsed.username}${parsed.password ? `:${parsed.password}` : ''}@`
+    const auth = directUser
+      ? `${directUser}${parsed.password ? `:${parsed.password}` : ''}@`
      : '';
    const search = parsed.search ?? '';
    const path = parsed.pathname ?? '';
@@ -32,7 +32,7 @@ import { chat as gatewayChat, type ChatResult } from '../ai/gateway.ts';
 import { resolveRecipe } from '../ai/model-resolver.ts';
 import { AIConfigError } from '../ai/errors.ts';
 import { loadConfig } from '../config.ts';
-import { join, dirname } from 'node:path';
+import { join, dirname, isAbsolute, resolve } from 'node:path';
 import type { BrainEngine } from '../engine.ts';
 import type { PhaseResult, PhaseError } from '../cycle.ts';
 import { MinionQueue } from '../minions/queue.ts';
@@ -243,6 +243,23 @@ export async function runPhaseSynthesize(
  opts: SynthesizePhaseOpts,
 ): Promise<PhaseResult> {
  const start = Date.now();
+  // Normalize brainDir to an absolute path BEFORE any reverse-write. Without
+  // this, a relative or empty brainDir flows down to writeReversePages →
+  // `join(brainDir, '${slug}.md')` → relative path → resolves against cwd at
+  // writeFileSync time, spilling synthesize output into whatever directory
+  // the cycle ran from (e.g., `companies/novamind.md` at the repo root).
+  // Surfaced by the warm-narwhal wave when E2E test cleanup found orphan
+  // synthesize pages at repo root from a `runCycle({brainDir: '.'})` call
+  // chain. Throw on empty (silent cwd-resolution is worse than a loud
+  // failure); resolve if relative (`.` / `./brain` / `../sibling` all valid
+  // inputs but must canonicalize before the write).
+  if (!opts.brainDir || opts.brainDir.trim() === '') {
+    return failed(makeError('InternalError', 'BRAINDIR_EMPTY',
+      'opts.brainDir is empty; refusing to run synthesize. Pass an absolute path.'));
+  }
+  if (!isAbsolute(opts.brainDir)) {
+    opts.brainDir = resolve(opts.brainDir);
+  }
  try {
    const config = await loadSynthConfig(engine);

@@ -425,10 +442,20 @@ export async function runPhaseSynthesize(
      }

      const isChunked = chunks.length > 1;
+      // queue.add subagent validator (classifyCapabilities → resolveRecipe)
+      // requires `provider:model`. resolveModel can return a bare id when
+      // TIER_DEFAULTS / DEFAULT_ALIASES carry a bare value; ensure the
+      // anthropic: prefix is present for known claude-* ids before passing
+      // to the queue. Non-anthropic providers must already declare a colon.
+      const subagentModel = config.model.includes(':')
+        ? config.model
+        : config.model.toLowerCase().startsWith('claude-')
+          ? `anthropic:${config.model}`
+          : config.model;
      for (let i = 0; i < chunks.length; i++) {
        const childData: SubagentHandlerData = {
          prompt: buildSynthesisPrompt(t, chunks[i], i, chunks.length, priorContradictionsBlock),
-          model: config.model,
+          model: subagentModel,
          max_turns: 30,
          allowed_slug_prefixes: allowedSlugPrefixes,
        };
@@ -96,6 +96,7 @@ export interface RoutingCaseResult {
 * variants that agents emit in practice.
 */
 export function normalizeText(s: string): string {
+  if (!s) return '';
  return s.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
 }

@@ -298,6 +299,10 @@ export function loadRoutingFixtures(skillsDir: string): LoadResult {
      if (raw.startsWith('//') || raw.startsWith('#')) continue;
      try {
        const obj = JSON.parse(raw) as RoutingFixture;
+        if (typeof obj.intent !== 'string') {
+          malformed.push({ file: fixturePath, line: i + 1, raw, error: `missing required field 'intent' (found keys: ${Object.keys(obj).join(', ')})` });
+          continue;
+        }
        fixtures.push({ ...obj, source: fixturePath });
      } catch (err) {
        malformed.push({
@@ -155,6 +155,21 @@ describe('isTokenLimitError (pure helper)', () => {
    expect(isTokenLimitError(new Error('Batch contains too many tokens'))).toBe(true);
  });

+  test('matches OpenAI embeddings "maximum request size" error (regression: PR ###)', () => {
+    // Real error string returned by OpenAI's /v1/embeddings endpoint when the
+    // sum of all input items exceeds 300k tokens. Without this match, gbrain's
+    // recursive-halving safety net never engages on OpenAI and the queue stalls
+    // forever on token-dense pages.
+    const openaiErr = new Error(
+      "Invalid 'input': maximum request size is 300000 tokens per request.",
+    );
+    expect(isTokenLimitError(openaiErr)).toBe(true);
+  });
+
+  test('matches generic "max tokens per request" phrasing', () => {
+    expect(isTokenLimitError(new Error('Exceeded 300000 max tokens per request'))).toBe(true);
+  });
+
  test('does not match unrelated errors', () => {
    expect(isTokenLimitError(new Error('Connection refused'))).toBe(false);
    expect(isTokenLimitError(new Error('Invalid API key'))).toBe(false);
@@ -44,6 +44,18 @@ describe('deriveDirectUrl', () => {
    expect(direct).toContain(':secret@'); // creds preserved
  });

+  test('strips .<project-ref> suffix from username when going pooler→direct', () => {
+    // Supabase direct connections require bare `postgres`; the `postgres.<ref>`
+    // form is pooler-only (Supavisor uses the suffix for tenant routing).
+    // Without the strip, direct auth fails with "password authentication
+    // failed for user postgres.<ref>" even with the correct password.
+    const direct = deriveDirectUrl(
+      'postgresql://postgres.abcxyz:secret@aws-0-us-east-1.pooler.supabase.com:6543/postgres'
+    );
+    expect(direct).toContain('postgres:secret@'); // bare username
+    expect(direct).not.toContain('postgres.abcxyz:secret@'); // no pooler suffix
+  });
+
  test('falls back to port-only swap when project-ref unparseable', () => {
    const direct = deriveDirectUrl(
      'postgresql://customuser:secret@some.pooler.supabase.com:6543/db'
@@ -51,6 +63,7 @@ describe('deriveDirectUrl', () => {
    expect(direct).toBeTruthy();
    expect(direct).toContain(':5432');
    expect(direct).toContain('some.pooler.supabase.com'); // host preserved
+    expect(direct).toContain('customuser:secret@'); // non-pooler username preserved
  });

  test('returns null for non-pooler URL', () => {
@@ -0,0 +1,79 @@
+/**
+ * Regression: synthesize phase MUST refuse to write reverse-pages to a
+ * relative brainDir. Pre-fix, `runCycle({brainDir: '.'})` or any caller
+ * passing a relative path (or empty string) would silently let
+ * writeFileSync resolve against cwd, spilling synthesize output into
+ * `<cwd>/companies/novamind.md` etc. Surfaced by the warm-narwhal wave
+ * when E2E test cleanup found orphan synthesize pages at repo root.
+ *
+ * Two contracts pinned here:
+ *   1. Empty/whitespace-only brainDir → returns failed() with code
+ *      `BRAINDIR_EMPTY` (loud, not silent cwd resolution).
+ *   2. Relative brainDir → resolved to absolute via path.resolve() before
+ *      any reverse-write can use it. Verified by checking opts.brainDir
+ *      after the call returns.
+ *
+ * Doesn't drive Anthropic — synthesize hits the "not_configured" skip
+ * branch first (no corpus dir set), which is sufficient to exercise the
+ * brainDir gate at function entry.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, isAbsolute } from 'node:path';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { runPhaseSynthesize } from '../src/core/cycle/synthesize.ts';
+
+let engine: PGLiteEngine;
+let tmpDir: string;
+
+beforeAll(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({});
+  await engine.initSchema();
+  tmpDir = mkdtempSync(join(tmpdir(), 'synth-braindir-'));
+});
+
+afterAll(async () => {
+  await engine.disconnect();
+  try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* */ }
+});
+
+describe('runPhaseSynthesize brainDir resolution (regression)', () => {
+  test('empty brainDir returns failed(BRAINDIR_EMPTY) instead of silently resolving against cwd', async () => {
+    const result = await runPhaseSynthesize(engine, {
+      brainDir: '',
+      dryRun: true,
+    });
+    expect(result.status).toBe('fail');
+    expect((result as { error?: { code?: string } }).error?.code).toBe('BRAINDIR_EMPTY');
+  });
+
+  test('whitespace-only brainDir also fails BRAINDIR_EMPTY', async () => {
+    const result = await runPhaseSynthesize(engine, {
+      brainDir: '   ',
+      dryRun: true,
+    });
+    expect(result.status).toBe('fail');
+    expect((result as { error?: { code?: string } }).error?.code).toBe('BRAINDIR_EMPTY');
+  });
+
+  test('relative brainDir gets resolved to absolute before any reverse-write', async () => {
+    const opts = { brainDir: '.', dryRun: true };
+    // The phase will return early ('not_configured' — no corpus dir set on
+    // this fresh engine) but the normalization runs unconditionally at entry.
+    await runPhaseSynthesize(engine, opts);
+    // After the call, opts.brainDir should be the resolved absolute path,
+    // proving the normalization fired.
+    expect(isAbsolute(opts.brainDir)).toBe(true);
+    expect(opts.brainDir).not.toBe('.');
+  });
+
+  test('absolute brainDir is preserved unchanged', async () => {
+    const opts = { brainDir: tmpDir, dryRun: true };
+    await runPhaseSynthesize(engine, opts);
+    // Already absolute → no mutation.
+    expect(opts.brainDir).toBe(tmpDir);
+  });
+});
@@ -1231,6 +1231,14 @@ describeE2E('E2E: Doctor Command', () => {
    // migration entries from in-flight workspaces — and surfaces them as the
    // 'minions_migration' [FAIL] check, exiting with code 1.
    gbrainHome = mkdtempSync(join(tmpdir(), 'gbrain-doctor-e2e-'));
+    // Cross-file isolation: prior E2E files can leave non-default `sources`
+    // rows (e.g. 'delta' from autopilot/sources tests). Doctor's
+    // sync_freshness + cycle_freshness checks then FAIL on those orphans,
+    // exit 1, breaking 'doctor exits 0 on healthy DB'. setupDB TRUNCATEs
+    // sources but schema.sql re-seeds 'default' via initSchema; clean any
+    // other rows so the doctor sees a clean single-source brain.
+    const conn = getConn();
+    await conn`DELETE FROM sources WHERE id != 'default'`;
  }, 30_000);
  afterAll(async () => {
    await teardownDB();
@@ -1246,9 +1254,15 @@ describeE2E('E2E: Doctor Command', () => {
  });

  test('gbrain doctor exits 0 on healthy DB', () => {
-    // Init first so config exists for CLI
+    // Init first so config exists for CLI. Pin --embedding-model explicitly
+    // so the spawned doctor doesn't pick a different default (e.g. ZE-1280d
+    // when ZEROENTROPY_API_KEY is in env) that mismatches the 1536d schema
+    // setupDB initialized, producing a WARN-status embedding_width_consistency
+    // check and exit 1. Mirrors the same pattern in 'Setup Journey'.
    Bun.spawnSync({
-      cmd: ['bun', 'run', 'src/cli.ts', 'init', '--non-interactive', '--url', process.env.DATABASE_URL!],
+      cmd: ['bun', 'run', 'src/cli.ts', 'init', '--non-interactive',
+            '--url', process.env.DATABASE_URL!,
+            '--embedding-model', 'openai:text-embedding-3-large'],
      cwd: cliCwd, env: cliEnv(), timeout: 15_000,
    });
    const result = Bun.spawnSync({
@@ -31,9 +31,26 @@ describe('frontmatter install-hook (B13)', () => {
    const content = readFileSync(hookPath, 'utf8');
    expect(content).toContain('gbrain frontmatter');
    expect(content).toContain('git diff --cached');
-    // Configured hooksPath
-    const hooksPath = execFileSync('git', ['-C', tmp, 'config', '--get', 'core.hooksPath'], { encoding: 'utf8' }).trim();
-    expect(hooksPath).toBe('.githooks');
+    // installHook's contract is "set core.hooksPath unless it's already set
+    // elsewhere". Test BOTH branches deterministically by reading the local
+    // scope only: clean CI → local should be `.githooks`; developer with a
+    // global core.hooksPath (e.g. dotfiles → ~/.config/git/hooks) → local
+    // should be empty because installHook correctly skipped clobbering.
+    // Reading via `--get` without `--local` falls back to global scope when
+    // local is unset, which made this test environmentally fragile.
+    let globalHooksPath = '';
+    try {
+      globalHooksPath = execFileSync('git', ['config', '--global', '--get', 'core.hooksPath'], { encoding: 'utf8' }).trim();
+    } catch { /* unset is the expected clean-env case */ }
+    let localHooksPath = '';
+    try {
+      localHooksPath = execFileSync('git', ['-C', tmp, 'config', '--local', '--get', 'core.hooksPath'], { encoding: 'utf8' }).trim();
+    } catch { /* unset is fine when global was present */ }
+    if (globalHooksPath) {
+      expect(localHooksPath).toBe('');
+    } else {
+      expect(localHooksPath).toBe('.githooks');
+    }
  });

  test('installHook refuses to clobber existing hook without --force', () => {
@@ -1 +1 @@
 .41.4.0
 .41.5.0