fix(gbrain-sync): make stage timeouts configurable via env (garrytan#1611)

`/sync-gbrain --full` on ~100k-page brains reliably exceeded the
hard-coded 35-minute timeout, SIGTERMed mid-import, and lost the staging
checkpoint. Set GSTACK_SYNC_MEMORY_TIMEOUT_MS (or _CODE_ for the code
stage) to override; bad input falls back to the 35-min default with a
stderr warning so a typo can't silently disable the safety net.

Author: cropsgg

bin/gstack-gbrain-sync.ts

@@ -80,6 +80,35 @@ const STATE_PATH = join(GSTACK_HOME, ".gbrain-sync-state.json");
 const LOCK_PATH = join(GSTACK_HOME, ".sync-gbrain.lock");
 const STALE_LOCK_MS = 5 * 60 * 1000;
 
+// Per-stage timeouts. Default 35 minutes is the honest budget for a first-run
+// full sync of a ~30-page-per-second brain (~70k pages). Brains with 100k+
+// pages or slow IO need more headroom — issue #1611. The env knobs accept an
+// integer in milliseconds; non-positive or non-numeric values fall back to the
+// default with a stderr warning so a typo doesn't silently extend a stage
+// indefinitely.
+const DEFAULT_STAGE_TIMEOUT_MS = 35 * 60 * 1000;
+
+function parseTimeoutEnv(name: string): number {
+  const raw = process.env[name];
+  if (!raw) return DEFAULT_STAGE_TIMEOUT_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) {
+    console.warn(
+      `[gstack-gbrain-sync] ignoring ${name}=${JSON.stringify(raw)} — expected a positive integer (milliseconds); using default ${DEFAULT_STAGE_TIMEOUT_MS} ms`,
+    );
+    return DEFAULT_STAGE_TIMEOUT_MS;
+  }
+  return Math.floor(n);
+}
+
+export function codeStageTimeoutMs(): number {
+  return parseTimeoutEnv("GSTACK_SYNC_CODE_TIMEOUT_MS");
+}
+
+export function memoryStageTimeoutMs(): number {
+  return parseTimeoutEnv("GSTACK_SYNC_MEMORY_TIMEOUT_MS");
+}
+
 // ── CLI ────────────────────────────────────────────────────────────────────
 
 function printUsage(): void {
@@ -100,6 +129,12 @@ Options:
 
 Stages run in order: code → memory ingest → curated git push.
 Each stage failure is non-fatal; subsequent stages still run.
+
+Environment:
+  GSTACK_SYNC_CODE_TIMEOUT_MS    Override code stage timeout (default 35 min).
+  GSTACK_SYNC_MEMORY_TIMEOUT_MS  Override memory ingest timeout (default 35 min).
+                                 Set higher (e.g. 5400000 = 90 min) when --full
+                                 import on large brains exceeds the default.
 `);
 }
 
@@ -603,7 +638,7 @@ async function runCodeImport(args: CliArgs): Promise<StageResult> {
 
   const syncResult = spawnGbrain(syncArgs, {
     stdio: args.quiet ? ["ignore", "ignore", "ignore"] : ["ignore", "inherit", "inherit"],
-    timeout: 35 * 60 * 1000,
+    timeout: codeStageTimeoutMs(),
     baseEnv: gbrainEnv,
   });
 
@@ -757,7 +792,7 @@ function runMemoryIngest(args: CliArgs): StageResult {
   // internally and must see the DATABASE_URL from gbrain's own config.
   const result = spawnSync("bun", ingestArgs, {
     encoding: "utf-8",
-    timeout: 35 * 60 * 1000,
+    timeout: memoryStageTimeoutMs(),
     env: buildGbrainEnv({ announce: false }),
   });
 

test/gstack-gbrain-sync.test.ts

@@ -18,6 +18,8 @@ import {
   planHostnameFoldMigration,
   sourceLocalPath,
   _resetGbrainSupportsRenameCache,
+  codeStageTimeoutMs,
+  memoryStageTimeoutMs,
 } from "../bin/gstack-gbrain-sync";
 
 const SCRIPT = join(import.meta.dir, "..", "bin", "gstack-gbrain-sync.ts");
@@ -863,3 +865,80 @@ describe("sourceLocalPath", () => {
     expect(sourceLocalPath("missing-id", envWithBindir(bindir))).toBeNull();
   });
 });
+
+// ──────────────────────────────────────────────────────────────────────────
+// Stage timeout overrides (issue #1611)
+//
+// `/sync-gbrain --full` on a ~100k-page brain blew past the hard-coded
+// 35-min timeout, SIGTERMed mid-import, and lost the staging checkpoint.
+// codeStageTimeoutMs / memoryStageTimeoutMs read env knobs so users with
+// slow IO or huge brains can extend the budget; bad inputs fall back to
+// the 35-min default so a typo doesn't silently disable the safety net.
+// ──────────────────────────────────────────────────────────────────────────
+
+describe("stage timeout overrides (issue #1611)", () => {
+  const DEFAULT_MS = 35 * 60 * 1000;
+  const saved: Record<string, string | undefined> = {};
+  const KEYS = ["GSTACK_SYNC_CODE_TIMEOUT_MS", "GSTACK_SYNC_MEMORY_TIMEOUT_MS"];
+
+  beforeEach(() => {
+    for (const k of KEYS) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+
+  afterEach(() => {
+    for (const k of KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+
+  it("defaults to 35 minutes when no env knob is set", () => {
+    expect(codeStageTimeoutMs()).toBe(DEFAULT_MS);
+    expect(memoryStageTimeoutMs()).toBe(DEFAULT_MS);
+  });
+
+  it("honors GSTACK_SYNC_MEMORY_TIMEOUT_MS for memory ingest", () => {
+    process.env.GSTACK_SYNC_MEMORY_TIMEOUT_MS = "5400000"; // 90 min
+    expect(memoryStageTimeoutMs()).toBe(5_400_000);
+    // Code stage stays on default — env knobs are independent.
+    expect(codeStageTimeoutMs()).toBe(DEFAULT_MS);
+  });
+
+  it("honors GSTACK_SYNC_CODE_TIMEOUT_MS independently", () => {
+    process.env.GSTACK_SYNC_CODE_TIMEOUT_MS = "7200000"; // 2 hr
+    expect(codeStageTimeoutMs()).toBe(7_200_000);
+    expect(memoryStageTimeoutMs()).toBe(DEFAULT_MS);
+  });
+
+  it("rejects non-numeric input and falls back to default", () => {
+    process.env.GSTACK_SYNC_MEMORY_TIMEOUT_MS = "ninety minutes";
+    expect(memoryStageTimeoutMs()).toBe(DEFAULT_MS);
+  });
+
+  it("rejects zero / negative values and falls back to default", () => {
+    process.env.GSTACK_SYNC_MEMORY_TIMEOUT_MS = "0";
+    expect(memoryStageTimeoutMs()).toBe(DEFAULT_MS);
+    process.env.GSTACK_SYNC_MEMORY_TIMEOUT_MS = "-1";
+    expect(memoryStageTimeoutMs()).toBe(DEFAULT_MS);
+  });
+
+  it("floors fractional ms to an integer", () => {
+    process.env.GSTACK_SYNC_MEMORY_TIMEOUT_MS = "1234.9";
+    expect(memoryStageTimeoutMs()).toBe(1234);
+  });
+
+  it("treats empty string as unset (falls back to default)", () => {
+    process.env.GSTACK_SYNC_MEMORY_TIMEOUT_MS = "";
+    expect(memoryStageTimeoutMs()).toBe(DEFAULT_MS);
+  });
+
+  it("--help mentions the env knobs", () => {
+    const r = runScript(["--help"]);
+    expect(r.exitCode).toBe(0);
+    expect(r.stderr).toContain("GSTACK_SYNC_MEMORY_TIMEOUT_MS");
+    expect(r.stderr).toContain("GSTACK_SYNC_CODE_TIMEOUT_MS");
+  });
+});