fix(gbrain-sync): centralize gbrain spawn surface + seed DATABASE_URL

Cherry-picked from #1508 by jasshultz, restructured per codex review #4
and #7 to widen scope and centralize the spawn surface.

The bug: gbrain auto-loads .env.local from cwd via dotenv. When
/sync-gbrain runs inside a Next.js / Prisma / Rails project whose
.env.local defines its own DATABASE_URL (pointing at the app's local
DB), gbrain reads that value instead of its own
~/.gbrain/config.json — auth fails, code + memory stages crash.

This commit:

- Adds lib/gbrain-exec.ts: buildGbrainEnv, spawnGbrain, execGbrainJson,
  execGbrainText, spawnGbrainAsync (the last one for memory-ingest's
  streaming gbrain import call). buildGbrainEnv seeds DATABASE_URL from
  ${GBRAIN_HOME:-$HOME/.gbrain}/config.json, returns a fresh env object
  (never the caller's by identity — codex review #11), and honors the
  GSTACK_RESPECT_ENV_DATABASE_URL=1 escape hatch.

- Routes every gbrain spawn in bin/gstack-gbrain-sync.ts and
  bin/gstack-memory-ingest.ts through the helpers. Both files now own
  zero direct spawnSync("gbrain"|spawn("gbrain"|execFileSync("gbrain"
  call sites.

- Threads buildGbrainEnv into the spawnSync("bun", [memory-ingest], ...)
  grandchild in runMemoryIngest (codex review #7). Without this, the
  parent fix is half-baked — the bun child inherits a clean env but
  needs DATABASE_URL pre-seeded too. spawnGbrainAsync inside
  memory-ingest provides defense in depth for standalone invocations.

- Adds GBRAIN_HOME support — aligns with detectEngineTier (already
  honors GBRAIN_HOME) so all gstack-side gbrain calls agree on which
  config file matters. Resolves baseEnv.HOME first, then homedir(), so
  test injection works without process-wide HOME mutation.

- Adds test/build-gbrain-env.test.ts: 10 unit tests covering all five
  env-seeding branches (seed from config / override caller /
  GSTACK_RESPECT escape hatch / missing config / unparseable config /
  no database_url field / GBRAIN_HOME path / object-identity guard /
  unrelated-vars preservation / idempotent-when-matches).

- Adds test/gbrain-exec-invariant.test.ts: static-source check that
  greps both bin/gstack-gbrain-sync.ts and bin/gstack-memory-ingest.ts
  for direct spawnSync("gbrain"|spawn("gbrain"|execFileSync("gbrain"|
  execSync(...gbrain matches and fails the build if any are found.
  Refactor-proof against future contributors adding a new gbrain spawn
  without env threading.

The invariant is intentionally narrow — only the two files where the
DATABASE_URL bug actually hurts users are guarded. Migrating the
spawn sites in lib/gbrain-local-status.ts, lib/gstack-memory-helpers.ts,
and bin/gstack-brain-context-load.ts is a follow-up.

Co-Authored-By: Jason Shultz <jasshultz@gmail.com>
Co-Authored-By: Claude <noreply@anthropic.com>

bin/gstack-gbrain-sync.ts

@@ -39,6 +39,7 @@ import "../lib/conductor-env-shim";
 import { detectEngineTier, withErrorContext, canonicalizeRemote } from "../lib/gstack-memory-helpers";
 import { ensureSourceRegistered, sourcePageCount } from "../lib/gbrain-sources";
 import { localEngineStatus, type LocalEngineStatus } from "../lib/gbrain-local-status";
+import { buildGbrainEnv, spawnGbrain, execGbrainJson } from "../lib/gbrain-exec";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -262,11 +263,9 @@ export function _resetGbrainSupportsRenameCache(): void {
 function gbrainSupportsSourcesRename(env?: NodeJS.ProcessEnv): boolean {
   if (_gbrainSupportsRenameCache !== null) return _gbrainSupportsRenameCache;
   try {
-    const r = spawnSync("gbrain", ["sources", "rename", "--help"], {
-      encoding: "utf-8",
+    const r = spawnGbrain(["sources", "rename", "--help"], {
       timeout: 5_000,
-      stdio: ["ignore", "pipe", "pipe"],
-      env: env || process.env,
+      baseEnv: env,
     });
     const out = `${r.stdout || ""}\n${r.stderr || ""}`;
     // Match the exact argument shape: `rename <old> <new>` (with literal
@@ -290,20 +289,13 @@ function gbrainSupportsSourcesRename(env?: NodeJS.ProcessEnv): boolean {
  * helper can be exercised without a real gbrain CLI.
  */
 export function sourceLocalPath(sourceId: string, env?: NodeJS.ProcessEnv): string | null {
-  try {
-    const r = spawnSync("gbrain", ["sources", "list", "--json"], {
-      encoding: "utf-8",
-      timeout: 30_000,
-      stdio: ["ignore", "pipe", "pipe"],
-      env: env || process.env,
-    });
-    if (r.status !== 0) return null;
-    const list = JSON.parse(r.stdout || "[]") as Array<{ id: string; local_path?: string }>;
-    const found = list.find((s) => s.id === sourceId);
-    return found?.local_path ?? null;
-  } catch {
-    return null;
-  }
+  const list = execGbrainJson<Array<{ id: string; local_path?: string }>>(
+    ["sources", "list", "--json"],
+    { baseEnv: env },
+  );
+  if (!list) return null;
+  const found = list.find((s) => s.id === sourceId);
+  return found?.local_path ?? null;
 }
 
 /** Result of `planHostnameFoldMigration` — informs `runCodeImport` of next steps. */
@@ -352,12 +344,7 @@ export function planHostnameFoldMigration(
     };
   }
   if (gbrainSupportsSourcesRename(env)) {
-    const r = spawnSync("gbrain", ["sources", "rename", legacyPathHashId, newSourceId], {
-      encoding: "utf-8",
-      timeout: 30_000,
-      stdio: ["ignore", "pipe", "pipe"],
-      env: env || process.env,
-    });
+    const r = spawnGbrain(["sources", "rename", legacyPathHashId, newSourceId], { baseEnv: env });
     if (r.status === 0) {
       return { kind: "renamed", oldId: legacyPathHashId, newId: newSourceId };
     }
@@ -377,12 +364,8 @@ export function planHostnameFoldMigration(
  * flag-helper centralization in commit 4 (lib/gbrain-exec.ts) will resolve
  * the inconsistency across the codebase.
  */
-export function removeOrphanedSource(oldId: string): boolean {
-  const r = spawnSync("gbrain", ["sources", "remove", oldId, "--confirm-destructive"], {
-    encoding: "utf-8",
-    timeout: 30_000,
-    stdio: ["ignore", "pipe", "pipe"],
-  });
+export function removeOrphanedSource(oldId: string, env?: NodeJS.ProcessEnv): boolean {
+  const r = spawnGbrain(["sources", "remove", oldId, "--confirm-destructive"], { baseEnv: env });
   return r.status === 0;
 }
 
@@ -555,13 +538,16 @@ async function runCodeImport(args: CliArgs): Promise<StageResult> {
   // hits forever if we left the orphan in place. Remove the legacy id once
   // here so users don't accumulate orphans.
   // Failure is non-fatal — we still register the new id below.
+  // gbrainEnv seeds DATABASE_URL from gbrain's config so this stage works
+  // inside Next.js / Prisma / Rails projects with their own .env.local
+  // (codex review #7 — bug fix is wider than #1508 as filed).
+  const gbrainEnv = buildGbrainEnv({ announce: !args.quiet });
   const legacyId = deriveLegacyCodeSourceId(root);
   let legacyRemoved = false;
   if (legacyId !== sourceId) {
-    const rm = spawnSync("gbrain", ["sources", "remove", legacyId, "--confirm-destructive"], {
-      encoding: "utf-8",
+    const rm = spawnGbrain(["sources", "remove", legacyId, "--confirm-destructive"], {
       timeout: 30_000,
-      stdio: ["ignore", "pipe", "pipe"],
+      baseEnv: gbrainEnv,
     });
     // Treat absent-source as success (clean state). gbrain emits "not found" on
     // missing id; treat any non-zero exit without "not found" as a soft fail.
@@ -575,7 +561,7 @@ async function runCodeImport(args: CliArgs): Promise<StageResult> {
   // pages); fall back to register-new → sync-OK → remove-old. Path-drift
   // (user moved the repo, etc.) skips migration with a warning.
   const pathOnlyHashLegacyId = derivePathOnlyHashLegacyId(root);
-  const migration = planHostnameFoldMigration(root, sourceId, pathOnlyHashLegacyId);
+  const migration = planHostnameFoldMigration(root, sourceId, pathOnlyHashLegacyId, gbrainEnv);
   if (migration.kind === "skipped-path-drift" && !args.quiet) {
     console.error(
       `[sync:code] hostname-fold migration skipped: legacy source ${migration.oldId} `
@@ -590,7 +576,7 @@ async function runCodeImport(args: CliArgs): Promise<StageResult> {
   // no synchronous duplicate here (per /codex review #12).
   let registered = false;
   try {
-    const result = await ensureSourceRegistered(sourceId, root, { federated: true });
+    const result = await ensureSourceRegistered(sourceId, root, { federated: true, env: gbrainEnv });
     registered = result.changed;
   } catch (err) {
     return {
@@ -608,9 +594,10 @@ async function runCodeImport(args: CliArgs): Promise<StageResult> {
     ? ["reindex-code", "--source", sourceId, "--yes"]
     : ["sync", "--strategy", "code", "--source", sourceId];
 
-  const syncResult = spawnSync("gbrain", syncArgs, {
+  const syncResult = spawnGbrain(syncArgs, {
     stdio: args.quiet ? ["ignore", "ignore", "ignore"] : ["ignore", "inherit", "inherit"],
     timeout: 35 * 60 * 1000,
+    baseEnv: gbrainEnv,
   });
 
   if (syncResult.status !== 0) {
@@ -633,13 +620,12 @@ async function runCodeImport(args: CliArgs): Promise<StageResult> {
   // the wrong/default source. Treat it as a stage failure (ok=false) so the
   // verdict block surfaces ERR and the user knows to retry rather than
   // trusting stale results.
-  const attach = spawnSync("gbrain", ["sources", "attach", sourceId], {
-    encoding: "utf-8",
+  const attach = spawnGbrain(["sources", "attach", sourceId], {
     timeout: 10_000,
     cwd: root,
-    stdio: ["ignore", "pipe", "pipe"],
+    baseEnv: gbrainEnv,
   });
-  const pageCount = sourcePageCount(sourceId);
+  const pageCount = sourcePageCount(sourceId, gbrainEnv);
 
   // Step 4: Deferred hostname-fold cleanup.
   // Only remove the pre-#1468 path-only-hash source NOW that the new source
@@ -649,7 +635,7 @@ async function runCodeImport(args: CliArgs): Promise<StageResult> {
   // safety: register → sync → verify → THEN delete.
   let hostnameLegacyRemoved = false;
   if (migration.kind === "pending-cleanup" && pageCount !== null && pageCount > 0) {
-    hostnameLegacyRemoved = removeOrphanedSource(migration.oldId);
+    hostnameLegacyRemoved = removeOrphanedSource(migration.oldId, gbrainEnv);
     if (hostnameLegacyRemoved && !args.quiet) {
       console.error(`[sync:code] hostname-fold migration: removed legacy ${migration.oldId} after new source sync verified (page_count=${pageCount})`);
     }
@@ -718,9 +704,14 @@ function runMemoryIngest(args: CliArgs): StageResult {
   else ingestArgs.push("--incremental");
   if (args.quiet) ingestArgs.push("--quiet");
 
+  // Thread the seeded env into the bun grandchild (codex review #7 — the
+  // .env.local footgun affects gstack-memory-ingest.ts too, not just the
+  // direct gbrain spawns in this file). The grandchild calls gbrain import
+  // internally and must see the DATABASE_URL from gbrain's own config.
   const result = spawnSync("bun", ingestArgs, {
     encoding: "utf-8",
     timeout: 35 * 60 * 1000,
+    env: buildGbrainEnv({ announce: false }),
   });
 
   // D6: parse [memory-ingest] lines from the child's stderr. ERR-prefixed

bin/gstack-memory-ingest.ts

@@ -64,6 +64,7 @@ import {
   detectEngineTier,
   withErrorContext,
 } from "../lib/gstack-memory-helpers";
+import { execGbrainText, spawnGbrainAsync } from "../lib/gbrain-exec";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -813,11 +814,10 @@ function gbrainAvailable(): boolean {
     // `import <dir>` (batch markdown import via path-authoritative slugs).
     // If absent, we surface a single clean error here rather than failing
     // the whole stage with a confusing usage message from gbrain itself.
-    const help = execFileSync("gbrain", ["--help"], {
-      encoding: "utf-8",
-      timeout: 5000,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
+    // `gbrain --help` probes only CLI availability, not DB connectivity, so
+    // it doesn't strictly need DATABASE_URL. But routing through the helper
+    // keeps the invariant test from chasing exceptions per call site.
+    const help = execGbrainText(["--help"], { timeout: 5000 });
     _gbrainAvailability = /^\s+import\s/m.test(help);
   } catch {
     _gbrainAvailability = false;
@@ -1316,11 +1316,11 @@ function runGbrainImport(
 ): Promise<{ status: number | null; stdout: string; stderr: string }> {
   installSignalForwarder();
   return new Promise((resolve) => {
-    const child = spawn(
-      "gbrain",
-      ["import", stagingDir, "--no-embed", "--json"],
-      { stdio: ["ignore", "pipe", "pipe"] },
-    );
+    // Seed DATABASE_URL from gbrain's own config so this stage works
+    // inside Next.js / Prisma / Rails projects with their own
+    // .env.local (codex review #7 — defense in depth on top of the
+    // parent gstack-gbrain-sync seeding the bun grandchild's env).
+    const child = spawnGbrainAsync(["import", stagingDir, "--no-embed", "--json"]);
     _activeImportChild = child;
     let stdout = "";
     let stderr = "";