Merge origin/master into garrytan/puebla-v4 — pull in v0.41.8.0

Master advanced past v0.41.7.0:
- v0.41.8.0: PGLite search/query/get exit cleanly + #1340 hint + #1342 breadcrumbs (#1405)

The headline conflict was scripts/check-test-isolation.sh: master shipped
the SAME fix I had pushed (different code, same bug), and master's is
structurally better — pure-bash `case` whole-line match instead of the
file-direct grep I used. Both eliminate the Ubuntu 24.04 + bash 5 +
GNU grep flake. Master's wins because:
  - no pipe, no subshell, no grep
  - locale-free, set-e-quirk-free
  - ~100x faster per call

Resolved by taking master's `is_allowlisted` body (the pure-bash case)
and restoring the cached `ALLOWLIST=` setup it depends on. My v0.41.9.0
file-direct grep approach is superseded.

VERSION + package.json + CHANGELOG conflicts resolved (v0.41.9.0 still
holds; CHANGELOG interleaves master's v0.41.8.0 entry below ours).

llms-full.txt regenerated: 580,462 bytes (~120KB headroom under the
v0.41.9.0 700KB budget, after master's expanded includeInFull exclusions
landed in v0.41.7.0).

3-line audit clean. Verify: typecheck clean, check-test-isolation OK
(694 files), build-llms 7/7 pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -2,6 +2,54 @@
 
 All notable changes to GBrain will be documented in this file.
 
+## [0.41.9.0] - 2026-05-25
+
+**Five UX/reliability fixes from a single production incident report. Your
+brain stops getting wedged for days when a CLI hangs, your sync stops
+failing 565 files one-at-a-time when an API key is missing, and your error
+messages start telling you what to actually do.**
+
+A gstack user ran `gbrain sync --full` against a 137-file repo and ran
+into five distinct defects in one session. The defects are independent
+but all live in the CLI entrypoint, sync orchestrator, and lock
+infrastructure. They ship as one reliability-hardening wave.
+
+What you can now do:
+
+- **`gbrain sync` checks your embedding credentials up front.** If
+  `OPENAI_API_KEY` is missing, you get one clean error line with a
+  paste-ready fix, not 565 identical failures in your sync-failures.jsonl.
+  Same check on `gbrain embed` and `gbrain import`. Bypass with
+  `--no-embed` if you want to import without embedding.
+- **Failed-sync errors are now bucketed properly.** Embedding failures
+  show up as `EMBEDDING_NO_CREDS`, `EMBEDDING_RATE_LIMIT`,
+  `EMBEDDING_QUOTA`, or `EMBEDDING_OVERSIZE` instead of bucketing into
+  the meaningless `UNKNOWN` pile. `gbrain doctor` summary actually tells
+  you what's wrong.
+- **`gbrain search` and `gbrain sources list` have default timeouts.**
+  30s for search, 10s for sources list. The connect step is bounded too,
+  so a hang in DB connect (PgBouncer freeze, hung TCP) can't spin at
+  100% CPU for days. Override with `--timeout=Ns`.
+- **`gbrain sync` lock-busy error names the holder.** When another sync
+  is already running, the error tells you the holder's PID, hostname,
+  and how long it's been running. If the holder is dead, run
+  `gbrain sync --break-lock` to clear it. If it's wedged but alive,
+  `gbrain sync --force-break-lock` (use carefully).
+- **`gbrain doctor` flags stale locks.** New `stale_locks` check
+  surfaces any lock row whose TTL has expired, with a paste-ready
+  break-lock hint per source.
+- **The "Schema probe/migrate failed: deadlock detected" warning stops
+  firing on every sync.** When two CLIs race on schema probe, the
+  retry-and-poll logic resolves the race silently. The warning only
+  surfaces when migrations are genuinely stuck, and its wording no
+  longer suggests the destructive-sounding `gbrain init --migrate-only`.
+- **`gbrain sync | head -20` exits cleanly.** SIGPIPE handling +
+  process-cleanup registry release locks on abnormal termination so a
+  truncated pipe doesn't wedge the next sync.
+
+To take advantage of v0.41.6.0: just `gbrain upgrade` and re-run your
+flow. No manual migration needed. New `--break-lock` / `--force-break-lock`
+flags are documented in `gbrain sync --help`.
 ## [0.41.8.0] - 2026-05-24
 
 **`gbrain search`, `gbrain query`, and `gbrain get` now actually exit when they finish on PGLite.**

CLAUDE.md

@@ -1384,6 +1384,45 @@ idempotency check. If you've been editing manually (merge resolution,
 conflict fix, version bump), the audit is the last line of defense
 before CI yells at you.
 
+## Conductor branch-name = workspace-name (IRON RULE)
+
+Conductor workspaces expect the git branch name to match the workspace
+directory name. When they disagree, Conductor silently fails to render the
+PR view + show ship state, leading to "did you actually push?" confusion.
+
+**Check this FIRST on every ship and BEFORE creating any PR:**
+
+```bash
+WORKSPACE=$(basename "$PWD")              # e.g. puebla-v4
+BRANCH=$(git branch --show-current)        # e.g. garrytan/gstack-requests
+case "$BRANCH" in
+  */"$WORKSPACE") echo "OK: branch tail matches workspace" ;;
+  "$WORKSPACE")   echo "OK: branch == workspace" ;;
+  *)              echo "MISMATCH: branch=$BRANCH workspace=$WORKSPACE — RENAME BEFORE SHIPPING" ;;
+esac
+```
+
+If MISMATCH (branch is `garrytan/foo` but workspace is `puebla-v4`):
+
+```bash
+# Rename local, push under new name, delete old remote (and old PR if it
+# was already created — github auto-closes it when head ref dies).
+git branch -m garrytan/<workspace-name>
+git push -u origin garrytan/<workspace-name>
+git push origin --delete <old-branch-name>
+# If a PR existed against the old branch:
+#   gh pr comment <old-pr> --body "Superseded by #<new>: branch renamed to match Conductor workspace."
+#   gh pr create --base master --title "..." --body "..."  # recreate from renamed branch
+```
+
+Caught the hard way on v0.41.9.0 ship: workspace `puebla-v4` but branch
+`garrytan/gstack-requests` produced PR #1439 that Conductor wouldn't
+display. Renamed to `garrytan/puebla-v4`; recreated as #1440.
+
+The /ship workflow's Step 1 should be augmented to run the mismatch
+check; until that lands upstream, ALWAYS run the check above before
+`/ship` invokes its first push or PR-create step.
+
 ## Pre-ship requirements
 
 Before shipping (/ship) or reviewing (/review), always run the full test suite.

TODOS.md

@@ -1,5 +1,43 @@
 # TODOS
 
+## v0.41.6.0 follow-ups (v0.41.7+)
+
+- [ ] **v0.41.7+: investigate v0.40+ schema-probe deadlock ROOT cause.**
+  v0.41.6.0 D4 ships the symptom fix (retry+poll silently when the race
+  resolves itself; warn with revised wording when truly stuck). Codex
+  outside-voice F12 caught the load-bearing finding: `initSchema()`
+  already takes `pg_advisory_lock(42)` so the SQLSTATE 40P01 race must
+  involve OTHER locks. Hypothesis: DDL locks acquired by initSchema's
+  ALTER / CREATE statements deadlock against application queries
+  (long-running SELECTs on `pages`, PgBouncer pool artifacts). Reproduce
+  on real PgBouncer setup with concurrent reads + simulated migration.
+  Expected outcome: either connection-pool isolation fix or DDL-lock
+  NOWAIT pattern. Effort: human ~4-6h / CC ~1h once repro is in hand.
+  Depends on: nothing; v0.41.6.0 D4 already quiets the alarming warning
+  for the common case, so this investigation is unblocked.
+
+- [ ] **v0.41.7+: wire inline auto-embed errors at sync.ts:1173-1186
+  through `recordSyncFailures`.** v0.41.6.0 D1 closes the headline
+  missing-creds case (preflight short-circuits before any embed call).
+  D2's classifier patterns cover rate-limit / quota / oversize errors
+  for per-file embeds inside `runImport` (which already records
+  failures correctly). But the inline post-import auto-embed catch at
+  `src/commands/sync.ts:1173-1186` swallows errors to stderr only and
+  never reaches `recordSyncFailures`. Wire it through with deduplication
+  guard (some errors may also be recorded by per-file `runImport` —
+  avoid double-recording). Effort: human ~1d / CC ~30min including
+  dedup test surface.
+
+- [ ] **v0.41.7+: true end-to-end cancellation in search via AbortSignal.**
+  v0.41.6.0 D3 `withTimeout` bounds USER wait via Promise.race + process
+  exit. The underlying DB / API socket keeps running until the kernel
+  reaps the process or the server times out the abandoned query. For
+  long-running subagent loops or rerank pipelines, threading AbortSignal
+  end-to-end would save server-side resources. Touches `hybridSearch` +
+  engine + `cosineReScore` + `reranker` signatures. Effort: human ~1d /
+  CC ~3h. Tradeoff: large surface fan-out for marginal benefit on the
+  CLI exit-on-timeout path. Only ship when a non-CLI consumer
+  (HTTP MCP, future autopilot health checks) wants true cancellation.
 ## community-pr-wave follow-ups (filed during ship)
 
 - [ ] **`FREE_LOCAL_*_PROVIDERS` zero-pricing bypassable via redirected

VERSION

@@ -1 +1 @@
-0.41.8.0
+0.41.9.0

llms-full.txt

@@ -1526,6 +1526,45 @@ idempotency check. If you've been editing manually (merge resolution,
 conflict fix, version bump), the audit is the last line of defense
 before CI yells at you.
 
+## Conductor branch-name = workspace-name (IRON RULE)
+
+Conductor workspaces expect the git branch name to match the workspace
+directory name. When they disagree, Conductor silently fails to render the
+PR view + show ship state, leading to "did you actually push?" confusion.
+
+**Check this FIRST on every ship and BEFORE creating any PR:**
+
+```bash
+WORKSPACE=$(basename "$PWD")              # e.g. puebla-v4
+BRANCH=$(git branch --show-current)        # e.g. garrytan/gstack-requests
+case "$BRANCH" in
+  */"$WORKSPACE") echo "OK: branch tail matches workspace" ;;
+  "$WORKSPACE")   echo "OK: branch == workspace" ;;
+  *)              echo "MISMATCH: branch=$BRANCH workspace=$WORKSPACE — RENAME BEFORE SHIPPING" ;;
+esac
+```
+
+If MISMATCH (branch is `garrytan/foo` but workspace is `puebla-v4`):
+
+```bash
+# Rename local, push under new name, delete old remote (and old PR if it
+# was already created — github auto-closes it when head ref dies).
+git branch -m garrytan/<workspace-name>
+git push -u origin garrytan/<workspace-name>
+git push origin --delete <old-branch-name>
+# If a PR existed against the old branch:
+#   gh pr comment <old-pr> --body "Superseded by #<new>: branch renamed to match Conductor workspace."
+#   gh pr create --base master --title "..." --body "..."  # recreate from renamed branch
+```
+
+Caught the hard way on v0.41.9.0 ship: workspace `puebla-v4` but branch
+`garrytan/gstack-requests` produced PR #1439 that Conductor wouldn't
+display. Renamed to `garrytan/puebla-v4`; recreated as #1440.
+
+The /ship workflow's Step 1 should be augmented to run the mismatch
+check; until that lands upstream, ALWAYS run the check above before
+`/ship` invokes its first push or PR-create step.
+
 ## Pre-ship requirements
 
 Before shipping (/ship) or reviewing (/review), always run the full test suite.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gbrain",
-  "version": "0.41.8.0",
+  "version": "0.41.9.0",
   "description": "Postgres-native personal knowledge brain with hybrid RAG search",
   "type": "module",
   "main": "src/core/index.ts",

scripts/check-test-isolation.sh

@@ -44,7 +44,8 @@ TARGET_DIR="${1:-test}"
 ALLOWLIST_FILE="$ROOT/scripts/check-test-isolation.allowlist"
 
 # Read allowlist (one filename per line, # comments allowed). Empty file
-# is fine — every violation will fail.
+# is fine — every violation will fail. Cached into ALLOWLIST so the
+# per-file check (~700 lookups per run) is one pure-bash `case` match.
 ALLOWLIST=""
 if [ -f "$ALLOWLIST_FILE" ]; then
   ALLOWLIST="$(grep -v '^[[:space:]]*#' "$ALLOWLIST_FILE" | grep -v '^[[:space:]]*$' || true)"

scripts/llms-config.ts

@@ -255,6 +255,9 @@ export const INLINE_TIPS = [
   "`gbrain upgrade` runs post-upgrade + apply-migrations.",
 ];
 
-// Target ~600KB so llms-full.txt fits in ~150k-token contexts with room to spare.
+// Target ~700KB so llms-full.txt fits in ~175k-token contexts with room to spare.
+// Bumped from 600KB in v0.41.9.0 — CLAUDE.md grew past 600KB after the wave's
+// new-file annotations + Conductor branch-name iron-rule landed; the bundle
+// still fits comfortably in modern long-context models.
 // Generator prints a WARN if exceeded; ship with includeInFull=false exclusions.
-export const FULL_SIZE_BUDGET = 600_000;
+export const FULL_SIZE_BUDGET = 700_000;

src/cli.ts

@@ -2,6 +2,12 @@
 
 import { installSigchldHandler } from './core/zombie-reap.ts';
 installSigchldHandler();
+// v0.41.6.0 D5: cleanup registry + signal handlers for SIGTERM/SIGHUP/SIGPIPE/
+// uncaughtException. NOT SIGINT (the existing AbortController path at :254
+// owns SIGINT). Installed at module load so locks acquired during boot
+// (e.g. during connectEngine's schema-probe path) are covered too.
+import { installSignalHandlers as installCleanupSignalHandlers } from './core/process-cleanup.ts';
+installCleanupSignalHandlers();
 
 import { readFileSync } from 'fs';
 import { loadConfig, loadConfigWithEngine, toEngineConfig, isThinClient } from './core/config.ts';
@@ -1152,6 +1158,53 @@ async function handleCliOnly(command: string, args: string[]) {
     return;
   }
 
+  // v0.41.6.0 D3 (per outside-voice F1): connect-time + dispatch-time wallclock
+  // timeouts for read-only commands whose hang would otherwise spin at 100% CPU
+  // (the production "10-day zombie gbrain search ping" bug class). The wrap
+  // covers connectEngine (so a hung schema probe / PgBouncer freeze actually
+  // surfaces a timeout) AND the dispatch body (so a wedged runSearch /
+  // runList honors the same deadline).
+  // Per-command default: search 30s, sources list 10s. User --timeout=Ns wins.
+  // Other commands (import, embed, doctor, etc.) keep their existing
+  // unbounded connect — destructive / long-running commands shouldn't get
+  // a default kill switch.
+  const readOnlyDefaultTimeoutMs =
+    command === 'search' ? 30_000 :
+    command === 'sources' && (args[0] === 'list' || args[0] === undefined) ? 10_000 :
+    null;
+  const cliOptsResolved = getCliOptions();
+  const userTimeoutMs = cliOptsResolved.timeoutMs;
+  const readOnlyTimeoutMs = userTimeoutMs ?? readOnlyDefaultTimeoutMs;
+
+  if (readOnlyTimeoutMs !== null) {
+    const { withTimeout, OperationTimeoutError } = await import('./core/timeout.ts');
+    const label = `gbrain ${command}`;
+    let engine: BrainEngine;
+    try {
+      engine = await withTimeout(connectEngine(), readOnlyTimeoutMs, `${label}: connect`);
+    } catch (e) {
+      if (e instanceof OperationTimeoutError) {
+        const hint = userTimeoutMs ? '' : ` (default ${e.ms}ms; pass --timeout=Ns to override)`;
+        console.error(`${e.label} timed out${hint}.`);
+        process.exit(124);
+      }
+      throw e;
+    }
+    try {
+      await withTimeout(dispatchReadOnlyCommand(engine, command, args), readOnlyTimeoutMs, label);
+    } catch (e) {
+      if (e instanceof OperationTimeoutError) {
+        const hint = userTimeoutMs ? '' : ` (default ${e.ms}ms; pass --timeout=Ns to override)`;
+        console.error(`${e.label} timed out${hint}.`);
+        process.exit(124);
+      }
+      throw e;
+    } finally {
+      try { await engine.disconnect(); } catch { /* best-effort */ }
+    }
+    return;
+  }
+
   // All remaining CLI-only commands need a DB connection
   const engine = await connectEngine();
   try {
@@ -1522,6 +1575,30 @@ async function handleCliOnly(command: string, args: string[]) {
   }
 }
 
+/**
+ * v0.41.6.0 D3: dispatch helper for the read-only commands that take a
+ * default wallclock timeout (`gbrain search`, `gbrain sources list`).
+ * Keeps the timeout-wrap site in main() small and the per-command
+ * dispatch logic colocated for easy extension. Pure dispatcher; no engine
+ * lifecycle (caller owns connect/disconnect).
+ */
+async function dispatchReadOnlyCommand(engine: BrainEngine, command: string, args: string[]): Promise<void> {
+  switch (command) {
+    case 'search': {
+      const { runSearch } = await import('./commands/search.ts');
+      await runSearch(engine, args);
+      return;
+    }
+    case 'sources': {
+      const { runSources } = await import('./commands/sources.ts');
+      await runSources(engine, args);
+      return;
+    }
+    default:
+      throw new Error(`dispatchReadOnlyCommand: unsupported command "${command}"`);
+  }
+}
+
 // Build the AIGatewayConfig payload from a GBrainConfig. Both configureGateway
 // sites in connectEngine() pass through this helper so adding a new field
 // touches one place. Adding a field to one site but not the other previously
@@ -1602,22 +1679,36 @@ async function connectEngine(opts?: { probeOnly?: boolean }): Promise<BrainEngin
     return engine;
   }
 
-  // Auto-apply pending schema migrations on connect (#651). Cheap probe
-  // first so already-migrated brains don't pay the bootstrap-probe +
-  // SCHEMA_SQL replay + ledger-check cost on every short-lived CLI call.
-  // This is the conditional version of #652 (oyi77's investigation):
-  // same correctness, no perf regression on the hot path.
+  // v0.41.6.0 D4: race-tolerant CLI-side migration runner. Replaces the
+  // pre-v0.41.6.0 `try { hasPendingMigrations && initSchema() } catch warn`
+  // block that fired the alarming "Schema probe/migrate failed: deadlock
+  // detected" warning on EVERY sync when two CLIs raced on schema probe.
+  // The retry+poll loop quiets the warning when the race resolves
+  // itself (the common case); the revised wording fires only when
+  // migrations are genuinely stuck.
   try {
-    const { hasPendingMigrations } = await import('./core/migrate.ts');
-    if (await hasPendingMigrations(engine)) {
-      await engine.initSchema();
+    const { tryRunPendingMigrations } = await import('./core/migrate.ts');
+    const result = await tryRunPendingMigrations(engine);
+    if (result.status === 'persistent') {
+      console.warn(
+        '  Schema migrations are pending. Another process attempted to apply them ' +
+        'but the migration didn\'t complete within the retry window. This is usually transient.',
+      );
+      console.warn('  If it persists:');
+      console.warn('    1. Check `gbrain doctor` for stale locks or stuck advisory locks.');
+      console.warn('    2. Check `gbrain jobs supervisor status` for crashed migration workers.');
+      console.warn('    3. Re-run: `gbrain apply-migrations --yes`');
+    } else if (result.status === 'error') {
+      // Non-deadlock error during initSchema. Surface the message and continue;
+      // subsequent operations will resurface the real schema error in context.
+      console.warn(`  Schema probe failed: ${result.error.message}`);
+      console.warn('  Re-run: `gbrain apply-migrations --yes`');
     }
+    // 'ok', 'not_needed', 'race_resolved' → silent (the common-case outcomes).
   } catch (err) {
-    // Non-fatal: if probe or initSchema fails, surface a hint and continue
-    // with the connected engine. Subsequent operations will surface the
-    // real schema error in context.
-    console.warn(`  Schema probe/migrate failed: ${(err as Error).message}`);
-    console.warn('  Try: gbrain init --migrate-only');
+    // Last-resort defense in case the helper itself throws unexpectedly.
+    console.warn(`  Schema probe failed (unexpected): ${(err as Error).message}`);
+    console.warn('  Re-run: `gbrain apply-migrations --yes`');
   }
 
   // v0.27.1 (F3 fix): re-merge DB-plane config now that the engine is up.

src/commands/doctor.ts

@@ -1632,6 +1632,58 @@ export function checkAutopilotLockScope(): Check {
   }
 }
 
+/**
+ * v0.41.6.0 D3 — stale_locks doctor check.
+ *
+ * Surfaces every row in `gbrain_cycle_locks` whose `ttl_expires_at < NOW()`.
+ * The TTL is the canonical staleness signal already trusted by
+ * tryAcquireDbLock's UPDATE-on-conflict SQL — when TTL is in the past,
+ * the next acquire attempt will sweep the row anyway. Doctor's job is to
+ * warn the user proactively so the next sync doesn't get a surprise
+ * "Another sync is in progress" with no fix hint.
+ *
+ * Paste-ready hint per stale lock: names the source-id from the
+ * `gbrain-sync:<source>` lock-key shape so users can copy-paste the
+ * exact recovery command.
+ *
+ * Out of scope (filed as v0.41+ follow-up TODO): detection of
+ * "wedged but TTL-refreshing" locks where a refresh thread is alive
+ * but the main work is blocked. Requires explicit heartbeat probe;
+ * speculation until production data shows the case.
+ */
+export async function checkStaleLocks(engine: BrainEngine): Promise<Check> {
+  try {
+    const { listStaleLocks } = await import('../core/db-lock.ts');
+    const stale = await listStaleLocks(engine);
+    if (stale.length === 0) {
+      return { name: 'stale_locks', status: 'ok', message: 'No stale locks (no rows with ttl_expires_at < NOW())' };
+    }
+    const lines = stale.slice(0, 10).map(s => {
+      const ageH = Math.floor(s.age_ms / 3600_000);
+      const source = s.id.startsWith('gbrain-sync:') ? s.id.slice('gbrain-sync:'.length) : null;
+      const breakHint = source ? `gbrain sync --break-lock --source ${source}` : `gbrain sync --break-lock`;
+      return `  ${s.id} (pid ${s.holder_pid} on ${s.holder_host}, age ${ageH}h) → ${breakHint}`;
+    });
+    const tail = stale.length > 10 ? `  ... and ${stale.length - 10} more.` : null;
+    return {
+      name: 'stale_locks',
+      status: 'warn',
+      message: [
+        `${stale.length} stale lock(s) detected (ttl_expires_at < NOW()):`,
+        ...lines,
+        tail,
+      ].filter(Boolean).join('\n'),
+    };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    // Pre-v0.30 brains may not have the gbrain_cycle_locks table yet.
+    if (/relation .* does not exist|no such table/i.test(msg)) {
+      return { name: 'stale_locks', status: 'ok', message: 'gbrain_cycle_locks table not yet provisioned (skipping)' };
+    }
+    return { name: 'stale_locks', status: 'warn', message: `Check failed: ${msg}` };
+  }
+}
+
 /**
  * v0.38 — cycle_phase_scope check (informational).
  *
@@ -4734,6 +4786,9 @@ export async function buildChecks(
     // 5M — autopilot_lock_scope (PID-safe hint per codex CF11)
     progress.heartbeat('autopilot_lock_scope');
     checks.push(checkAutopilotLockScope());
+    // v0.41.6.0 D3 — stale_locks (gbrain_cycle_locks rows with ttl_expires_at < NOW())
+    progress.heartbeat('stale_locks');
+    checks.push(await checkStaleLocks(engine));
     // v0.38 — cycle_phase_scope (informational; no DB cost)
     progress.heartbeat('cycle_phase_scope');
     checks.push(checkCyclePhaseScope());

src/commands/embed.ts

@@ -134,6 +134,19 @@ export async function runEmbedCore(engine: BrainEngine, opts: EmbedOpts): Promis
     assertEmbeddingEnabled(loadConfig());
   }
 
+  // v0.41.6.0 D1: preflight embedding credentials. Skipped in dryRun mode
+  // so plan-mode introspection still works (no provider calls needed).
+  //
+  // runEmbedCore is a LIBRARY function called from both the CLI (runEmbed)
+  // and the cycle (runCycle's embed phase + autopilot-cycle handler). THROW
+  // EmbeddingCredentialError so the cycle's per-phase try/catch can
+  // gracefully fail-the-phase without killing the worker process. The CLI
+  // wrapper at src/commands/embed.ts:runEmbed catches and exits.
+  if (!opts.dryRun) {
+    const { validateEmbeddingCreds } = await import('../core/embed-preflight.ts');
+    validateEmbeddingCreds();
+  }
+
   // v0.37.11.0 (Lane D.2): pre-flight dim-mismatch check. Catches the headline
   // fresh-install bug class before the worker pool spends 20 parallel calls
   // hitting raw Postgres dimension errors.
@@ -236,9 +249,16 @@ export async function runEmbed(engine: BrainEngine, args: string[]): Promise<Emb
     return result;
   } catch (e) {
     if (progressStarted) progress.finish();
-    // D.2: surface dim-mismatch failures with the paste-ready recipe
-    // instead of the raw Postgres error message.
-    if (e instanceof EmbeddingDimMismatchError) {
+    // v0.41.6.0 D1: preflight throws EmbeddingCredentialError; surface the
+    // paste-ready userMessage instead of the bare exception text.
+    const { EmbeddingCredentialError } = await import('../core/embed-preflight.ts');
+    if (e instanceof EmbeddingCredentialError) {
+      serr('');
+      serr(e.userMessage);
+      serr('');
+    } else if (e instanceof EmbeddingDimMismatchError) {
+      // D.2: surface dim-mismatch failures with the paste-ready recipe
+      // instead of the raw Postgres error message.
       serr('\n' + e.recipeMessage + '\n');
     } else {
       serr(e instanceof Error ? e.message : String(e));

src/commands/import.ts

@@ -64,6 +64,26 @@ export async function runImport(
       console.error('Tip: run `gbrain import <dir> --no-embed` to import without embedding now.');
       process.exit(1);
     }
+
+    // v0.41.6.0 D1: preflight embedding credentials. Closes the bug class
+    // where `gbrain import` per-file embed writes N identical
+    // "missing OPENAI_API_KEY" failures into sync-failures.jsonl.
+    const { validateEmbeddingCreds, EmbeddingCredentialError } = await import('../core/embed-preflight.ts');
+    try {
+      validateEmbeddingCreds();
+    } catch (e) {
+      if (e instanceof EmbeddingCredentialError) {
+        if (jsonOutput) {
+          console.log(JSON.stringify({ status: 'embedding_credentials_missing', diagnosis: e.diagnosis }));
+        } else {
+          console.error('');
+          console.error(e.userMessage);
+          console.error('');
+        }
+        process.exit(1);
+      }
+      throw e;
+    }
   }
   // v0.39 T1.5: load active pack ONCE at runImport entry; thread to every
   // per-file importFile call below. Codex perf finding #7 — never per-file.

src/commands/sync.ts

@@ -513,10 +513,7 @@ export async function performSync(engine: BrainEngine, opts: SyncOpts): Promise<
       return await withRefreshingLock(engine, lockKey, () => performSyncInner(engine, opts));
     } catch (err) {
       if (err instanceof LockUnavailableError) {
-        throw new Error(
-          `Another sync is in progress (lock ${lockKey} held). ` +
-            `Wait for it to finish, or run 'gbrain doctor' if it has been more than 30 minutes.`,
-        );
+        throw new Error(await formatLockBusyMessage(engine, lockKey));
       }
       throw err;
     }
@@ -525,10 +522,7 @@ export async function performSync(engine: BrainEngine, opts: SyncOpts): Promise<
   // Legacy global-lock path (single-default-source brains).
   const lockHandle = await tryAcquireDbLock(engine, lockKey);
   if (!lockHandle) {
-    throw new Error(
-      `Another sync is in progress (lock ${lockKey} held). ` +
-        `Wait for it to finish, or run 'gbrain doctor' if it has been more than 30 minutes.`,
-    );
+    throw new Error(await formatLockBusyMessage(engine, lockKey));
   }
   try {
     return await performSyncInner(engine, opts);
@@ -537,6 +531,180 @@ export async function performSync(engine: BrainEngine, opts: SyncOpts): Promise<
   }
 }
 
+/**
+ * v0.41.6.0 D3: rich "Another sync is in progress" message that names the
+ * holder PID, hostname, age, and the right --break-lock invocation to
+ * recover. Falls back to the legacy message when inspectLock can't read
+ * the row (best-effort — the lock itself was still busy).
+ */
+async function formatLockBusyMessage(engine: BrainEngine, lockKey: string): Promise<string> {
+  const { inspectLock } = await import('../core/db-lock.ts');
+  let snap;
+  try { snap = await inspectLock(engine, lockKey); }
+  catch { snap = null; }
+
+  if (!snap) {
+    return (
+      `Another sync is in progress (lock ${lockKey} held). ` +
+      `Wait for it to finish, or run 'gbrain doctor' if it has been more than 30 minutes.`
+    );
+  }
+
+  const ageHuman = formatAgeHuman(snap.age_ms);
+  const breakHint = lockKey.startsWith('gbrain-sync:')
+    ? `gbrain sync --break-lock --source ${lockKey.slice('gbrain-sync:'.length)}`
+    : `gbrain sync --break-lock`;
+  const ttlNote = snap.ttl_expired ? ' [TTL expired]' : '';
+  return (
+    `Another sync is in progress (lock ${lockKey} held by pid ${snap.holder_pid} on ${snap.holder_host}, ` +
+    `started ${ageHuman} ago${ttlNote}).\n` +
+    `If pid ${snap.holder_pid} is dead, re-run with --break-lock to clear it:\n` +
+    `  ${breakHint}\n` +
+    `Or wait for the holder to finish.`
+  );
+}
+
+/**
+ * v0.41.6.0 D3: `gbrain sync --break-lock` / `--force-break-lock` worker.
+ * Returns the process exit code (0 = lock cleared or absent; 1 = refused).
+ *
+ * Safe path (`force=false`): refuses unless the holder is on this host
+ * AND either (a) TTL has expired (the lock is structurally available
+ * already) OR (b) the holder PID is dead AND the lock is older than 60s
+ * (the age guard defeats PID-reuse coincidence — Linux PID space wraps
+ * at 32768 so a 10-day-old lock with pid=12345 may be falsely
+ * refused-to-clear because an unrelated process now owns pid 12345; 60s
+ * is the codex F7-amended minimum age that makes coincidence unlikely).
+ *
+ * Force path (`force=true`): skips liveness check, deletes the row,
+ * warns loudly that the holder may still be writing.
+ *
+ * Both paths use the same atomic `DELETE ... RETURNING id` so a race
+ * with another break-lock or with TTL-eviction can't produce confusing
+ * post-conditions.
+ */
+async function runBreakLock(
+  engine: BrainEngine,
+  lockKey: string,
+  sourceId: string,
+  opts: { force: boolean; json: boolean },
+): Promise<number> {
+  const { inspectLock, deleteLockRow } = await import('../core/db-lock.ts');
+  const { hostname } = await import('os');
+  const localHost = hostname();
+  let snap;
+  try { snap = await inspectLock(engine, lockKey); }
+  catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (opts.json) console.log(JSON.stringify({ status: 'error', error: msg, lock: lockKey }));
+    else console.error(`Failed to inspect lock ${lockKey}: ${msg}`);
+    return 1;
+  }
+
+  if (!snap) {
+    if (opts.json) console.log(JSON.stringify({ status: 'absent', lock: lockKey, source_id: sourceId }));
+    else console.log(`Lock ${lockKey} is not held (nothing to break).`);
+    return 0;
+  }
+
+  // Force path: skip all guards, atomic DELETE, warn.
+  if (opts.force) {
+    const { deleted } = await deleteLockRow(engine, lockKey, snap.holder_pid);
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: deleted ? 'force_broken' : 'race_already_cleared',
+        lock: lockKey, source_id: sourceId, snapshot: snap,
+      }));
+    } else if (deleted) {
+      console.log(`Force-broke lock ${lockKey} (was held by pid ${snap.holder_pid} on ${snap.holder_host}, age ${formatAgeHuman(snap.age_ms)}).`);
+      console.log('WARNING: the holder may still be writing. Verify with `gbrain doctor` before re-running.');
+    } else {
+      console.log(`Lock ${lockKey} was already cleared by another process between our check and DELETE (race-safe).`);
+    }
+    return 0;
+  }
+
+  // Safe path: must be local host AND (TTL-expired OR (PID-dead AND age >= 60s)).
+  if (snap.holder_host !== localHost) {
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: 'refused',
+        reason: 'cross_host',
+        lock: lockKey, source_id: sourceId, snapshot: snap, local_host: localHost,
+      }));
+    } else {
+      console.error(`Lock ${lockKey} is held on a different host (${snap.holder_host}, this host is ${localHost}).`);
+      console.error('Cross-host PID liveness is unsound. To break anyway, use --force-break-lock');
+      console.error('(only safe when you KNOW the holder is dead — verify before forcing).');
+    }
+    return 1;
+  }
+
+  let safe = false;
+  let reason: string;
+  if (snap.ttl_expired) {
+    safe = true;
+    reason = 'ttl_expired';
+  } else {
+    // PID liveness check on local host. process.kill(pid, 0) throws ESRCH
+    // when the PID is dead. Combined with 60s age guard (per outside-voice F7).
+    let alive = true;
+    try { process.kill(snap.holder_pid, 0); }
+    catch { alive = false; }
+    const oldEnough = snap.age_ms >= 60_000;
+    if (!alive && oldEnough) {
+      safe = true;
+      reason = 'pid_dead_age_60s';
+    } else if (!alive && !oldEnough) {
+      reason = 'pid_dead_but_lock_too_young';
+    } else {
+      reason = 'pid_alive';
+    }
+  }
+
+  if (!safe) {
+    if (opts.json) {
+      console.log(JSON.stringify({
+        status: 'refused', reason, lock: lockKey, source_id: sourceId, snapshot: snap,
+      }));
+    } else {
+      console.error(`Refusing to break lock ${lockKey}: holder pid ${snap.holder_pid} appears alive on ${snap.holder_host} (age ${formatAgeHuman(snap.age_ms)}).`);
+      if (reason === 'pid_dead_but_lock_too_young') {
+        console.error('(PID is dead but the lock is younger than 60s — the PID may have been reused. Wait or use --force-break-lock if you are certain.)');
+      } else {
+        console.error('If the holder is wedged, kill it first then re-run --break-lock,');
+        console.error('OR use --force-break-lock to clear regardless (the holder may still write afterwards).');
+      }
+    }
+    return 1;
+  }
+
+  const { deleted } = await deleteLockRow(engine, lockKey, snap.holder_pid);
+  if (opts.json) {
+    console.log(JSON.stringify({
+      status: deleted ? 'broken' : 'race_already_cleared',
+      reason, lock: lockKey, source_id: sourceId, snapshot: snap,
+    }));
+  } else if (deleted) {
+    console.log(`Broke lock ${lockKey} (was held by pid ${snap.holder_pid} on ${snap.holder_host}, age ${formatAgeHuman(snap.age_ms)}; reason: ${reason}).`);
+  } else {
+    console.log(`Lock ${lockKey} was already cleared by another process between our check and DELETE (race-safe).`);
+  }
+  return 0;
+}
+
+function formatAgeHuman(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m${s % 60}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h${m % 60}m`;
+  const d = Math.floor(h / 24);
+  return `${d}d${h % 24}h`;
+}
+
 async function performSyncInner(engine: BrainEngine, opts: SyncOpts): Promise<SyncResult> {
   // v0.41.8.0 (D9 / #1342): phase breadcrumbs. The #1342 reporter saw
   // ZERO stderr output before their sync hang, which made the bug
@@ -1426,6 +1594,56 @@ See also:
   const syncAll = args.includes('--all');
   const jsonOut = args.includes('--json');
   const yesFlag = args.includes('--yes');
+  // v0.41.6.0 D3: lock-recovery flags. --break-lock (safe) verifies the
+  // holder is local-host + (TTL-expired OR PID-dead+60s-old) before
+  // deleting the row. --force-break-lock skips the liveness check. Both
+  // are refused when combined with --all (per-source invocation required;
+  // v0.40 lock keys are gbrain-sync:<sourceId>).
+  const breakLock = args.includes('--break-lock');
+  const forceBreakLock = args.includes('--force-break-lock');
+
+  // v0.41.6.0 D3: handle --break-lock / --force-break-lock BEFORE the
+  // sync would otherwise contend on the lock. Resolves the active source,
+  // inspects the lock, decides break/refuse, exits without running sync.
+  if (breakLock || forceBreakLock) {
+    if (syncAll) {
+      console.error('--break-lock / --force-break-lock cannot be combined with --all.');
+      console.error('Per-source lock keys (gbrain-sync:<sourceId>) require per-source invocation.');
+      console.error('');
+      console.error('To recover stale locks across all sources, shell-loop:');
+      console.error(`  for src in $(gbrain sources list --json | jq -r '.[].id'); do gbrain sync --break-lock --source "$src"; done`);
+      process.exit(1);
+    }
+    const sourceArg = args.find((a, i) => args[i - 1] === '--source');
+    const sourceId = sourceArg ?? 'default';
+    const lockKey = `gbrain-sync:${sourceId}`;
+    const exit = await runBreakLock(engine, lockKey, sourceId, { force: forceBreakLock, json: jsonOut });
+    process.exit(exit);
+  }
+
+  // v0.41.6.0 D1: preflight embedding credentials BEFORE the import phase
+  // so a missing OPENAI_API_KEY exits with one clean line instead of
+  // writing N identical entries to sync-failures.jsonl. Skipped when
+  // --no-embed (the canonical opt-out) or --dry-run (no provider calls
+  // happen in dry-run anyway).
+  if (!noEmbed && !dryRun) {
+    const { validateEmbeddingCreds, EmbeddingCredentialError } = await import('../core/embed-preflight.ts');
+    try {
+      validateEmbeddingCreds();
+    } catch (e) {
+      if (e instanceof EmbeddingCredentialError) {
+        if (jsonOut) {
+          console.log(JSON.stringify({ status: 'embedding_credentials_missing', diagnosis: e.diagnosis }));
+        } else {
+          console.error('');
+          console.error(e.userMessage);
+          console.error('');
+        }
+        process.exit(1);
+      }
+      throw e;
+    }
+  }
   // v0.40 D4+D18: parallel `sync --all` by default; --serial opts back to v1.
   // --no-auto-embed skips the per-source embed-backfill auto-enqueue.
   // --max-sources N caps fan-out (default min(sources.length, 8)).

src/core/ai/gateway.ts

@@ -128,6 +128,11 @@ function getExtendedModelsForProvider(providerId: string): ReadonlySet<string> |
  */
 type EmbedManyFn = typeof embedMany;
 let _embedTransport: EmbedManyFn = embedMany;
+// v0.41.6.0 D1: tests that install a transport stub also pass the
+// embedding-creds preflight, matching the chat-transport fast-path
+// pattern. Set when __setEmbedTransportForTests is called with a
+// non-null fn; cleared when called with null or on resetGateway().
+let _embedTransportInstalled = false;
 // Test-only seam for chat(). When set, chat() skips provider resolution and
 // returns this function's result directly. See __setChatTransportForTests.
 let _chatTransport: ((opts: ChatOpts) => Promise<ChatResult>) | null = null;
@@ -501,6 +506,7 @@ export function resetGateway(): void {
   _modelCache.clear();
   _shrinkState.clear();
   _embedTransport = embedMany;
+  _embedTransportInstalled = false;
   _chatTransport = null;
   _warnedRecipes.clear();
   _extendedModels.clear();
@@ -517,6 +523,7 @@ export function resetGateway(): void {
  */
 export function __setEmbedTransportForTests(fn: EmbedManyFn | null): void {
   _embedTransport = fn ?? embedMany;
+  _embedTransportInstalled = fn !== null;
 }
 
 /**
@@ -588,6 +595,113 @@ export function getRerankerModel(): string | undefined {
   return requireConfig().reranker_model;
 }
 
+/**
+ * v0.41.6.0 — structured diagnosis for the embedding touchpoint. Returns
+ * a tagged union naming exactly why the gateway can't serve embeddings.
+ * The old `isAvailable('embedding')` collapsed 5 distinct conditions
+ * (no gateway config, no model configured, unknown provider, no
+ * embedding touchpoint on the recipe, missing env vars) into one
+ * boolean — useful for hot-path branching but useless for surfacing a
+ * paste-ready error message to the user.
+ *
+ * D1 preflight in `src/core/embed-preflight.ts` consumes this to produce
+ * `EmbeddingCredentialError` with the exact env var name + recipe id +
+ * model. CLI catch sites format the error with a `--no-embed` hint.
+ *
+ * `isAvailable('embedding', ...)` delegates here so existing callers
+ * (search hybrid path, etc.) keep their boolean contract.
+ */
+export type EmbeddingDiagnosis =
+  | { ok: true; model: string; provider: string; recipeId: string }
+  | { ok: false; reason: 'no_gateway_config' }
+  | { ok: false; reason: 'no_model_configured' }
+  | { ok: false; reason: 'unknown_provider'; model: string; provider: string; message: string }
+  | { ok: false; reason: 'no_touchpoint'; model: string; provider: string; recipeId: string }
+  | { ok: false; reason: 'user_provided_model_unset'; model: string; provider: string; recipeId: string }
+  | { ok: false; reason: 'missing_env'; model: string; provider: string; recipeId: string; missingEnvVars: string[] };
+
+export function diagnoseEmbedding(modelOverride?: string): EmbeddingDiagnosis {
+  // Test-transport fast path: matches the `if (touchpoint === 'chat' &&
+  // _chatTransport) return true` shortcut in isAvailable() so tests that
+  // install an embed transport stub also pass the preflight without
+  // having to configure real provider env vars.
+  if (_embedTransportInstalled) {
+    const modelStr = modelOverride ?? _config?.embedding_model ?? DEFAULT_EMBEDDING_MODEL;
+    return { ok: true, model: modelStr, provider: '<test-transport>', recipeId: '<test-transport>' };
+  }
+
+  if (!_config) return { ok: false, reason: 'no_gateway_config' };
+
+  const modelStr = modelOverride ?? _config.embedding_model ?? DEFAULT_EMBEDDING_MODEL;
+  if (!modelStr) return { ok: false, reason: 'no_model_configured' };
+
+  let parsed;
+  let recipe;
+  try {
+    const resolved = resolveRecipe(modelStr);
+    parsed = resolved.parsed;
+    recipe = resolved.recipe;
+  } catch (err) {
+    const { providerId = 'unknown' } = (() => {
+      try { return parseModelId(modelStr); } catch { return { providerId: 'unknown' }; }
+    })();
+    return {
+      ok: false,
+      reason: 'unknown_provider',
+      model: modelStr,
+      provider: providerId,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  const tp = recipe.touchpoints.embedding;
+  if (!tp) {
+    return {
+      ok: false,
+      reason: 'no_touchpoint',
+      model: modelStr,
+      provider: parsed.providerId,
+      recipeId: recipe.id,
+    };
+  }
+
+  // Openai-compat recipes with empty models list require a user-provided model.
+  const isUserProvided = (tp as any).user_provided_models === true;
+  if (
+    Array.isArray(tp.models) &&
+    tp.models.length === 0 &&
+    (recipe.id === 'litellm' || isUserProvided)
+  ) {
+    return {
+      ok: false,
+      reason: 'user_provided_model_unset',
+      model: modelStr,
+      provider: parsed.providerId,
+      recipeId: recipe.id,
+    };
+  }
+
+  const required = recipe.auth_env?.required ?? [];
+  const missing = required.filter(k => !_config!.env[k]);
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      reason: 'missing_env',
+      model: modelStr,
+      provider: parsed.providerId,
+      recipeId: recipe.id,
+      missingEnvVars: missing,
+    };
+  }
+
+  return {
+    ok: true,
+    model: modelStr,
+    provider: parsed.providerId,
+    recipeId: recipe.id,
+  };
+}
+
 /**
  * Check whether a touchpoint can be served given the current config.
  * Replaces scattered `!process.env.OPENAI_API_KEY` checks (Codex C3).
@@ -598,6 +712,10 @@ export function getRerankerModel(): string | undefined {
  * provider reachable?" rather than "is the global default reachable?" —
  * otherwise an unreachable global default disables vector search even
  * when the active column's provider works fine.
+ *
+ * v0.41.6.0: the 'embedding' branch delegates to diagnoseEmbedding() so
+ * the predicate and the diagnostic stay in sync. Other touchpoints keep
+ * their inline logic for now.
  */
 export function isAvailable(touchpoint: TouchpointKind, modelOverride?: string): boolean {
   // Test seam: when a transport stub is installed for this touchpoint, the
@@ -606,13 +724,13 @@ export function isAvailable(touchpoint: TouchpointKind, modelOverride?: string):
   // __setEmbedTransportForTests.
   if (touchpoint === 'chat' && _chatTransport) return true;
 
+  if (touchpoint === 'embedding') return diagnoseEmbedding(modelOverride).ok;
+
   if (!_config) return false;
   try {
     const modelStr =
       modelOverride
         ? modelOverride
-        : touchpoint === 'embedding'
-        ? getEmbeddingModel()
         : touchpoint === 'expansion'
         ? getExpansionModel()
         : touchpoint === 'chat'
@@ -626,21 +744,8 @@ export function isAvailable(touchpoint: TouchpointKind, modelOverride?: string):
     // Recipe must actually support the requested touchpoint.
     // Anthropic declares only expansion + chat (no embedding model); requesting
     // embedding from an anthropic-configured brain is unavailable regardless of auth.
-    const touchpointConfig = recipe.touchpoints[touchpoint as 'embedding' | 'expansion' | 'chat' | 'reranker'];
+    const touchpointConfig = recipe.touchpoints[touchpoint as 'expansion' | 'chat' | 'reranker'];
     if (!touchpointConfig) return false;
-    // Openai-compat recipes with empty models list require a user-provided
-    // model. Either the recipe explicitly opts in via
-    // EmbeddingTouchpoint.user_provided_models (D8=A), or the legacy
-    // `recipe.id === 'litellm'` heuristic (back-compat for pre-v0.32 builds
-    // where the field hadn't been declared yet).
-    const isUserProvided =
-      touchpoint === 'embedding' &&
-      (touchpointConfig as any).user_provided_models === true;
-    if (
-      Array.isArray(touchpointConfig.models) &&
-      touchpointConfig.models.length === 0 &&
-      (recipe.id === 'litellm' || isUserProvided)
-    ) return false;
 
     // For openai-compatible without auth requirements (Ollama local), treat as always-available.
     const required = recipe.auth_env?.required ?? [];

src/core/db-lock.ts

@@ -63,6 +63,14 @@ export async function tryAcquireDbLock(
     db?: { query: (sql: string, params?: unknown[]) => Promise<{ rows: unknown[] }> };
   };
 
+  // v0.41.6.0 D5: auto-register cleanup so abnormal termination (SIGTERM/
+  // SIGHUP/SIGPIPE/uncaughtException/EPIPE-on-stdout) releases the lock.
+  // The returned handle's release() deregisters before deleting — atomic
+  // in single-threaded JS so no double-DELETE on normal exit path.
+  // withRefreshingLock just calls tryAcquireDbLock and gets the same
+  // registration for free (single ownership site per outside-voice F11).
+  const { registerCleanup } = await import('./process-cleanup.ts');
+
   if (engine.kind === 'postgres' && maybePG.sql) {
     const sql = maybePG.sql as any;
     const ttl = `${ttlMinutes} minutes`;
@@ -78,6 +86,12 @@ export async function tryAcquireDbLock(
       RETURNING id
     `;
     if (rows.length === 0) return null;
+    const deregister = registerCleanup(`db-lock:${lockId}`, async () => {
+      await sql`
+        DELETE FROM gbrain_cycle_locks
+        WHERE id = ${lockId} AND holder_pid = ${pid}
+      `;
+    });
     return {
       id: lockId,
       refresh: async () => {
@@ -88,6 +102,7 @@ export async function tryAcquireDbLock(
         `;
       },
       release: async () => {
+        deregister();
         await sql`
           DELETE FROM gbrain_cycle_locks
           WHERE id = ${lockId} AND holder_pid = ${pid}
@@ -112,6 +127,12 @@ export async function tryAcquireDbLock(
       [lockId, pid, host, ttl],
     );
     if (rows.length === 0) return null;
+    const deregister = registerCleanup(`db-lock:${lockId}`, async () => {
+      await db.query(
+        `DELETE FROM gbrain_cycle_locks WHERE id = $1 AND holder_pid = $2`,
+        [lockId, pid],
+      );
+    });
     return {
       id: lockId,
       refresh: async () => {
@@ -123,6 +144,7 @@ export async function tryAcquireDbLock(
         );
       },
       release: async () => {
+        deregister();
         await db.query(
           `DELETE FROM gbrain_cycle_locks WHERE id = $1 AND holder_pid = $2`,
           [lockId, pid],
@@ -134,6 +156,171 @@ export async function tryAcquireDbLock(
   throw new Error(`Unknown engine kind for db-lock: ${engine.kind}`);
 }
 
+/**
+ * v0.41.6.0 D3: inspect the current holder of a named lock.
+ *
+ * Returns a snapshot of the lock row + computed age, or null when no row
+ * exists for `lockId`. Used by:
+ *   - performSync's lock-busy error path to surface holder PID + hostname
+ *     + age in the user-facing "Another sync is in progress" message.
+ *   - gbrain doctor's `stale_locks` check (queries all rows where
+ *     ttl_expires_at < NOW()).
+ *   - gbrain sync --break-lock to verify holder state before clearing.
+ *
+ * Pure read; no side effects, no lock acquire.
+ */
+export interface LockSnapshot {
+  id: string;
+  holder_pid: number;
+  holder_host: string;
+  acquired_at: Date;
+  ttl_expires_at: Date;
+  age_ms: number;
+  /** TTL has already expired — lock is structurally available for next acquire. */
+  ttl_expired: boolean;
+}
+
+export async function inspectLock(engine: BrainEngine, lockId: string): Promise<LockSnapshot | null> {
+  const maybePG = engine as unknown as { sql?: (...args: unknown[]) => Promise<unknown> };
+  const maybePGLite = engine as unknown as {
+    db?: { query: (sql: string, params?: unknown[]) => Promise<{ rows: unknown[] }> };
+  };
+
+  let row: { id?: string; holder_pid?: number; holder_host?: string; acquired_at?: Date | string; ttl_expires_at?: Date | string } | undefined;
+
+  if (engine.kind === 'postgres' && maybePG.sql) {
+    const sql = maybePG.sql as any;
+    const rows = await sql`
+      SELECT id, holder_pid, holder_host, acquired_at, ttl_expires_at
+        FROM gbrain_cycle_locks
+       WHERE id = ${lockId}
+    `;
+    row = rows[0];
+  } else if (engine.kind === 'pglite' && maybePGLite.db) {
+    const { rows } = await maybePGLite.db.query(
+      `SELECT id, holder_pid, holder_host, acquired_at, ttl_expires_at
+         FROM gbrain_cycle_locks
+        WHERE id = $1`,
+      [lockId],
+    );
+    row = rows[0] as typeof row;
+  } else {
+    throw new Error(`Unknown engine kind for inspectLock: ${engine.kind}`);
+  }
+
+  if (!row || row.holder_pid === undefined || !row.acquired_at || !row.ttl_expires_at) return null;
+
+  const acquired = row.acquired_at instanceof Date ? row.acquired_at : new Date(row.acquired_at);
+  const ttlExpires = row.ttl_expires_at instanceof Date ? row.ttl_expires_at : new Date(row.ttl_expires_at);
+  const now = Date.now();
+
+  return {
+    id: lockId,
+    holder_pid: Number(row.holder_pid),
+    holder_host: String(row.holder_host ?? ''),
+    acquired_at: acquired,
+    ttl_expires_at: ttlExpires,
+    age_ms: now - acquired.getTime(),
+    ttl_expired: ttlExpires.getTime() < now,
+  };
+}
+
+/**
+ * v0.41.6.0 D3: list every lock whose TTL has expired. Used by gbrain
+ * doctor's `stale_locks` check. The query reuses the same canonical
+ * staleness signal (ttl_expires_at < NOW()) that tryAcquireDbLock's
+ * UPDATE-on-conflict already trusts — no parallel heuristic.
+ */
+export async function listStaleLocks(engine: BrainEngine): Promise<LockSnapshot[]> {
+  const maybePG = engine as unknown as { sql?: (...args: unknown[]) => Promise<unknown> };
+  const maybePGLite = engine as unknown as {
+    db?: { query: (sql: string, params?: unknown[]) => Promise<{ rows: unknown[] }> };
+  };
+
+  let rows: Array<{ id?: string; holder_pid?: number; holder_host?: string; acquired_at?: Date | string; ttl_expires_at?: Date | string }>;
+
+  if (engine.kind === 'postgres' && maybePG.sql) {
+    const sql = maybePG.sql as any;
+    rows = await sql`
+      SELECT id, holder_pid, holder_host, acquired_at, ttl_expires_at
+        FROM gbrain_cycle_locks
+       WHERE ttl_expires_at < NOW()
+       ORDER BY acquired_at
+    `;
+  } else if (engine.kind === 'pglite' && maybePGLite.db) {
+    const result = await maybePGLite.db.query(
+      `SELECT id, holder_pid, holder_host, acquired_at, ttl_expires_at
+         FROM gbrain_cycle_locks
+        WHERE ttl_expires_at < NOW()
+        ORDER BY acquired_at`,
+    );
+    rows = result.rows as typeof rows;
+  } else {
+    throw new Error(`Unknown engine kind for listStaleLocks: ${engine.kind}`);
+  }
+
+  const now = Date.now();
+  return rows
+    .filter(r => r.holder_pid !== undefined && r.acquired_at && r.ttl_expires_at)
+    .map(r => {
+      const acquired = r.acquired_at instanceof Date ? r.acquired_at : new Date(r.acquired_at!);
+      const ttl = r.ttl_expires_at instanceof Date ? r.ttl_expires_at : new Date(r.ttl_expires_at!);
+      return {
+        id: String(r.id ?? ''),
+        holder_pid: Number(r.holder_pid),
+        holder_host: String(r.holder_host ?? ''),
+        acquired_at: acquired,
+        ttl_expires_at: ttl,
+        age_ms: now - acquired.getTime(),
+        ttl_expired: true,
+      };
+    });
+}
+
+/**
+ * v0.41.6.0 D3: atomic verify-and-delete for `gbrain sync --break-lock`.
+ *
+ * Runs `DELETE ... WHERE id = $1 AND holder_pid = $2 RETURNING id`.
+ * RETURNING shape:
+ *   - row returned  → we cleared the lock atomically.
+ *   - empty array   → row was already cleared by another process (idempotent;
+ *                     caller proceeds to acquire normally).
+ *
+ * Single round-trip; no TOCTOU window between liveness check and DELETE.
+ * The caller is responsible for the liveness check (PID-dead OR TTL-expired
+ * for safe mode; skipped entirely for --force-break-lock).
+ */
+export async function deleteLockRow(
+  engine: BrainEngine,
+  lockId: string,
+  holderPid: number,
+): Promise<{ deleted: boolean }> {
+  const maybePG = engine as unknown as { sql?: (...args: unknown[]) => Promise<unknown> };
+  const maybePGLite = engine as unknown as {
+    db?: { query: (sql: string, params?: unknown[]) => Promise<{ rows: unknown[] }> };
+  };
+
+  if (engine.kind === 'postgres' && maybePG.sql) {
+    const sql = maybePG.sql as any;
+    const rows: Array<{ id: string }> = await sql`
+      DELETE FROM gbrain_cycle_locks
+       WHERE id = ${lockId} AND holder_pid = ${holderPid}
+      RETURNING id
+    `;
+    return { deleted: rows.length > 0 };
+  }
+  if (engine.kind === 'pglite' && maybePGLite.db) {
+    const { rows } = await maybePGLite.db.query(
+      `DELETE FROM gbrain_cycle_locks
+        WHERE id = $1 AND holder_pid = $2
+       RETURNING id`,
+      [lockId, holderPid],
+    );
+    return { deleted: rows.length > 0 };
+  }
+  throw new Error(`Unknown engine kind for deleteLockRow: ${engine.kind}`);
+}
+
 /**
  * v0.40 (Federated Sync v2): per-source sync lock helper.
  *

src/core/embed-preflight.ts

@@ -0,0 +1,124 @@
+/**
+ * Embedding credential preflight.
+ *
+ * v0.41.6.0 D1 — fail fast at sync/embed/import entry when the configured
+ * embedding provider can't be reached. Without this, gbrain proceeds into
+ * the import phase, hits 565 per-file embed errors, writes 565 identical
+ * "OpenAI embedding requires OPENAI_API_KEY." rows to `~/.gbrain/sync-failures.jsonl`,
+ * and blocks the sync bookmark from advancing.
+ *
+ * Routes through `gateway.diagnoseEmbedding()` so the structured reason
+ * (missing_env / no_touchpoint / unknown_provider / etc.) drives a precise
+ * user-facing error message.
+ *
+ * Skip protocol: callers SHOULD NOT call validateEmbeddingCreds when the
+ * user explicitly passed `--no-embed` (the canonical opt-out). The
+ * deferred-setup sentinel is owned by `assertEmbeddingEnabled` in
+ * `embedding-dim-check.ts`; this preflight runs AFTER that check fires.
+ */
+
+import { diagnoseEmbedding, type EmbeddingDiagnosis } from './ai/gateway.ts';
+
+/**
+ * Tagged error thrown by validateEmbeddingCreds. CLI catch sites format
+ * `.userMessage` to stderr and exit non-zero. The structured fields
+ * (`provider`, `model`, `missingEnvVars`, `reason`) enable programmatic
+ * consumers (`gbrain doctor --json`, future autopilot health checks) to
+ * read state without parsing the human message.
+ */
+export class EmbeddingCredentialError extends Error {
+  readonly diagnosis: EmbeddingDiagnosis;
+  readonly userMessage: string;
+
+  constructor(diagnosis: EmbeddingDiagnosis, userMessage: string) {
+    super(userMessage);
+    this.name = 'EmbeddingCredentialError';
+    this.diagnosis = diagnosis;
+    this.userMessage = userMessage;
+  }
+}
+
+/**
+ * Run the preflight. Throws EmbeddingCredentialError when the gateway
+ * can't serve embeddings. Returns silently when ok.
+ *
+ * Pure function: reads nothing except what `gateway.diagnoseEmbedding()`
+ * already had at gateway configure-time.
+ */
+export function validateEmbeddingCreds(): void {
+  const d = diagnoseEmbedding();
+  if (d.ok) return;
+  throw new EmbeddingCredentialError(d, formatEmbeddingCredsError(d));
+}
+
+/**
+ * Format a paste-ready, multi-line error message from a non-ok diagnosis.
+ * Exported for tests and for the doctor JSON output.
+ */
+export function formatEmbeddingCredsError(d: EmbeddingDiagnosis): string {
+  if (d.ok) return '';
+
+  switch (d.reason) {
+    case 'no_gateway_config':
+      return [
+        'Embedding gateway is not configured.',
+        'This is usually a startup-order bug. Re-run with --no-embed to import',
+        'without embedding, then file an issue at https://github.com/garrytan/gbrain/issues',
+      ].join('\n');
+
+    case 'no_model_configured':
+      return [
+        'No embedding model is configured for this brain.',
+        '',
+        '  Set one: gbrain config set embedding_model openai:text-embedding-3-small',
+        '  Or skip embedding now: re-run with --no-embed',
+      ].join('\n');
+
+    case 'unknown_provider':
+      return [
+        `Embedding model "${d.model}" uses an unknown provider "${d.provider}".`,
+        '',
+        `  ${d.message}`,
+        '',
+        '  Pick a known provider: gbrain config set embedding_model openai:text-embedding-3-small',
+      ].join('\n');
+
+    case 'no_touchpoint':
+      return [
+        `Provider "${d.provider}" does not offer an embedding touchpoint.`,
+        '',
+        '  Switch providers: gbrain config set embedding_model openai:text-embedding-3-small',
+        '  Or run with --no-embed to import-only and embed later.',
+      ].join('\n');
+
+    case 'user_provided_model_unset':
+      return [
+        `Provider "${d.provider}" requires a specific model name to be configured.`,
+        '',
+        `  Set one: gbrain config set embedding_model ${d.provider}:<model-name>`,
+        '  Or run with --no-embed to import-only and embed later.',
+      ].join('\n');
+
+    case 'missing_env': {
+      const envs = d.missingEnvVars.join(', ');
+      const primaryEnv = d.missingEnvVars[0];
+      const lines = [
+        `Embedding model "${d.model}" requires ${envs}.`,
+        '',
+        `Set it in your shell, or:`,
+        `  • Re-run with --no-embed to import-only and embed later once the key is set.`,
+      ];
+      // Only offer a provider-switch hint when the current provider isn't openai
+      // (otherwise we'd be suggesting they switch to the thing they already have).
+      if (d.provider !== 'openai') {
+        lines.push(`  • Switch providers: gbrain config set embedding_model openai:text-embedding-3-small`);
+      } else {
+        lines.push(`  • Switch providers: gbrain config set embedding_model voyage:voyage-3-large`);
+      }
+      lines.push('');
+      lines.push(`Example shell setup:`);
+      lines.push(`  export ${primaryEnv}=...`);
+      return lines.join('\n');
+    }
+  }
+}

src/core/migrate.ts

@@ -4614,6 +4614,131 @@ export async function hasPendingMigrations(engine: BrainEngine): Promise<boolean
   }
 }
 
+/**
+ * v0.41.6.0 D4 — race-tolerant CLI-side migration runner.
+ *
+ * Wraps `engine.initSchema()` with a deadlock-aware retry + poll loop so
+ * the common "two CLIs probe schema simultaneously" race doesn't surface
+ * an alarming `Schema probe/migrate failed: deadlock detected` warning
+ * on every sync.
+ *
+ * Flow:
+ *  1. Try `engine.initSchema()`.
+ *  2. On SQLSTATE 40P01 (deadlock_detected) from Postgres: wait 250ms,
+ *     retry once.
+ *  3. If second attempt still 40P01 (or any persistent lock-busy signal):
+ *     poll `hasPendingMigrations()` every 250ms for up to 5s. If poll
+ *     flips to `false` mid-window, return `{ status: 'race_resolved' }`
+ *     silently (another runner finished — common case the user
+ *     complained about).
+ *  4. If still pending at deadline: return `{ status: 'persistent', error }`.
+ *     Caller surfaces the revised warning.
+ *  5. Non-40P01 errors propagate normally (real failures).
+ *
+ * The deeper root cause (codex F12 in plan-eng-review: initSchema
+ * already holds pg_advisory_lock(42), so the deadlock graph likely
+ * involves OTHER locks like DDL vs application-query contention or
+ * PgBouncer pool artifacts) is filed as a P2 follow-up TODO. The
+ * symptom fix here quiets the warning on the COMMON case where the race
+ * resolves itself, while loud-failing when migration is genuinely stuck.
+ *
+ * `deadlineMs` defaults to 5000 (5s polling window). Test-only callers
+ * pass smaller values for hermeticity; production paths use the default.
+ *
+ * `pollIntervalMs` defaults to 250ms — matches the retry-backoff delay
+ * for a symmetric design (eng-review D11). ~20 polls per deadline window;
+ * trivial DB load even on a stressed PgBouncer pool.
+ */
+export type TryRunPendingMigrationsResult =
+  | { status: 'ok'; attempts: number }
+  | { status: 'not_needed' }
+  | { status: 'race_resolved'; attempts: number; pollIterations: number }
+  | { status: 'persistent'; attempts: number; pollIterations: number; error: Error }
+  | { status: 'error'; error: Error };
+
+export interface TryRunPendingMigrationsOpts {
+  deadlineMs?: number;
+  pollIntervalMs?: number;
+  retryBackoffMs?: number;
+  /** Test seam: inject a custom hasPendingMigrations / initSchema pair. */
+  _hooks?: {
+    initSchema?: () => Promise<void>;
+    hasPending?: () => Promise<boolean>;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+  };
+}
+
+export async function tryRunPendingMigrations(
+  engine: BrainEngine,
+  opts: TryRunPendingMigrationsOpts = {},
+): Promise<TryRunPendingMigrationsResult> {
+  const deadlineMs = opts.deadlineMs ?? 5000;
+  const pollIntervalMs = opts.pollIntervalMs ?? 250;
+  const retryBackoffMs = opts.retryBackoffMs ?? 250;
+  const initSchema = opts._hooks?.initSchema ?? (() => engine.initSchema());
+  const hasPending = opts._hooks?.hasPending ?? (() => hasPendingMigrations(engine));
+  const sleep = opts._hooks?.sleep ?? ((ms: number) => new Promise(r => setTimeout(r, ms)));
+  const now = opts._hooks?.now ?? (() => Date.now());
+
+  // Quick early-exit: if no migrations are actually pending, skip entirely.
+  if (!await hasPending()) return { status: 'not_needed' };
+
+  let attempts = 0;
+  let lastErr: Error | null = null;
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    attempts++;
+    try {
+      await initSchema();
+      return { status: 'ok', attempts };
+    } catch (err) {
+      lastErr = err instanceof Error ? err : new Error(String(err));
+      if (!isDeadlockError(lastErr)) {
+        // Real failure: propagate to caller's catch.
+        return { status: 'error', error: lastErr };
+      }
+      // Deadlock — backoff before retry.
+      if (attempt === 0) await sleep(retryBackoffMs);
+    }
+  }
+
+  // Both attempts deadlocked. Poll hasPendingMigrations until deadline.
+  const deadline = now() + deadlineMs;
+  let pollIterations = 0;
+  while (now() < deadline) {
+    pollIterations++;
+    await sleep(pollIntervalMs);
+    try {
+      if (!await hasPending()) return { status: 'race_resolved', attempts, pollIterations };
+    } catch {
+      // hasPending throws → treat as pending (defensive; matches its own catch).
+    }
+  }
+
+  return {
+    status: 'persistent',
+    attempts,
+    pollIterations,
+    error: lastErr ?? new Error('deadlock_persistent'),
+  };
+}
+
+/**
+ * Detect Postgres SQLSTATE 40P01 (deadlock_detected) from arbitrary
+ * thrown values. Pattern-matches on:
+ *   - postgres.js `.code === '40P01'`
+ *   - error message containing `40P01` or `deadlock detected`
+ * The text-fallback covers cases where the driver doesn't expose `.code`.
+ */
+export function isDeadlockError(err: unknown): boolean {
+  if (!err) return false;
+  const maybe = err as { code?: string; sqlState?: string; message?: string };
+  if (maybe.code === '40P01' || maybe.sqlState === '40P01') return true;
+  const msg = String(maybe.message ?? err);
+  return /40P01|deadlock detected/i.test(msg);
+}
+
 export async function runMigrations(engine: BrainEngine): Promise<{ applied: number; current: number }> {
   const currentStr = await engine.getConfig('version');
   const current = parseInt(currentStr || '1', 10);

src/core/process-cleanup.ts

@@ -0,0 +1,185 @@
+/**
+ * Process-cleanup registry.
+ *
+ * v0.41.6.0 D5 — registry + signal handlers so abnormal termination
+ * (SIGTERM/SIGHUP/SIGPIPE, EPIPE on stdout, uncaughtException) releases
+ * locks instead of leaking them for up to 30 minutes until the TTL
+ * expires. Pre-v0.41.6.0, `gbrain sync --full | head -20` would SIGPIPE
+ * gbrain, finally blocks wouldn't run, and the next sync would report
+ * "Another sync is in progress" because the lock row was orphaned.
+ *
+ * Design (per eng-review D7 + outside-voice F9-F11, 2026-05-24):
+ *
+ *  - Signal scope: SIGTERM, SIGHUP, SIGPIPE, uncaughtException,
+ *    unhandledRejection. **NOT SIGINT** — gbrain has an existing
+ *    SIGINT-via-AbortController path at cli.ts:254 that propagates
+ *    abort to in-flight operations (clean cancel). Installing cleanup
+ *    on SIGINT here would preempt that flow. Lock release on user
+ *    cancel belongs in the AbortController path, not in a parallel
+ *    signal handler.
+ *
+ *  - Idempotent: a second signal during the cleanup pass is a NO-OP.
+ *    First pass runs to its 3s deadline; users who want a forced exit
+ *    can SIGKILL.
+ *
+ *  - Single ownership: `tryAcquireDbLock` auto-registers; the returned
+ *    handle's `release()` deregisters. `withRefreshingLock` just
+ *    consumes the handle as a normal caller (it calls tryAcquireDbLock
+ *    internally, so the registration happens there). No double-register.
+ *
+ *  - Best-effort: cleanup callbacks run via Promise.allSettled with a
+ *    3s deadline. Throws don't block other callbacks. Engine pool
+ *    already closed → DELETE fails silently → process exits anyway.
+ *
+ *  - Normal exit path unchanged: try/finally in `tryAcquireDbLock` and
+ *    `withRefreshingLock` already releases on normal completion;
+ *    deregister-before-release is atomic in single-threaded JS so no
+ *    double-DELETE.
+ */
+
+const CLEANUP_DEADLINE_MS = 3_000;
+
+interface CleanupEntry {
+  name: string;
+  fn: () => Promise<void>;
+}
+
+const registry = new Map<symbol, CleanupEntry>();
+let installed = false;
+let cleanupInFlight = false;
+
+/**
+ * Register a cleanup callback. Returns a deregister handle (idempotent
+ * on second call). Cleanup callbacks fire on abnormal termination only;
+ * normal completion uses the caller's own try/finally.
+ *
+ * Names are for diagnostic stderr output if the callback throws; pick
+ * something human-readable.
+ */
+export function registerCleanup(name: string, fn: () => Promise<void>): () => void {
+  const key = Symbol(name);
+  registry.set(key, { name, fn });
+  let deregistered = false;
+  return () => {
+    if (deregistered) return;
+    deregistered = true;
+    registry.delete(key);
+  };
+}
+
+/**
+ * Read the currently registered cleanup count. Test seam.
+ *
+ * @internal
+ */
+export function _registeredCleanupCountForTests(): number {
+  return registry.size;
+}
+
+/**
+ * Manually trigger the cleanup pass + exit. Used by the EPIPE-on-stdout
+ * handler so a broken pipe routes through cleanup instead of immediate
+ * `process.exit(0)` (per outside-voice F10 / eng-review D13 fold-in).
+ */
+export async function triggerCleanupAndExit(code: number): Promise<void> {
+  await runCleanupPass();
+  process.exit(code);
+}
+
+async function runCleanupPass(): Promise<void> {
+  if (cleanupInFlight) return; // Idempotent: second signal during cleanup is NO-OP.
+  cleanupInFlight = true;
+
+  const entries = Array.from(registry.values());
+  if (entries.length === 0) return;
+
+  const deadline = new Promise<'deadline'>((resolve) => {
+    const t = setTimeout(() => resolve('deadline'), CLEANUP_DEADLINE_MS);
+    if (typeof (t as { unref?: () => void }).unref === 'function') {
+      (t as { unref: () => void }).unref();
+    }
+  });
+
+  const cleanupAll = Promise.allSettled(
+    entries.map(async (e) => {
+      try { await e.fn(); }
+      catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        try { process.stderr.write(`[process-cleanup] ${e.name}: ${msg}\n`); }
+        catch { /* even stderr might be broken */ }
+        throw err;
+      }
+    }),
+  );
+
+  await Promise.race([cleanupAll, deadline]);
+}
+
+/**
+ * Install signal handlers + the EPIPE-on-stdout handler. Idempotent
+ * (second call is NO-OP). MUST be called once at CLI module load AFTER
+ * any existing signal handlers (so we don't preempt the SIGINT
+ * AbortController at cli.ts:254 — we don't listen to SIGINT here, but
+ * documenting the install order keeps future maintainers aware).
+ */
+export function installSignalHandlers(): void {
+  if (installed) return;
+  installed = true;
+
+  const handleSignal = (signal: NodeJS.Signals) => {
+    void runCleanupPass().finally(() => {
+      // Match GNU `kill` exit-code convention: 128 + signal number for
+      // signal-terminated processes. The actual integer doesn't matter
+      // much (shells generally use it as advisory); the goal is "exit
+      // promptly after cleanup".
+      const code = signal === 'SIGTERM' ? 143 : signal === 'SIGHUP' ? 129 : signal === 'SIGPIPE' ? 141 : 1;
+      process.exit(code);
+    });
+  };
+
+  process.on('SIGTERM', () => handleSignal('SIGTERM'));
+  process.on('SIGHUP', () => handleSignal('SIGHUP'));
+  // SIGPIPE in Node is rarely raised directly (Node ignores it by default
+  // and surfaces an EPIPE write error on the stream instead). Listen anyway
+  // for environments where it does fire.
+  process.on('SIGPIPE', () => handleSignal('SIGPIPE'));
+
+  process.on('uncaughtException', (err) => {
+    try { process.stderr.write(`[uncaughtException] ${err instanceof Error ? err.stack ?? err.message : err}\n`); }
+    catch { /* stderr might be broken */ }
+    void runCleanupPass().finally(() => process.exit(1));
+  });
+  process.on('unhandledRejection', (reason) => {
+    try { process.stderr.write(`[unhandledRejection] ${reason instanceof Error ? reason.stack ?? reason.message : reason}\n`); }
+    catch { /* stderr might be broken */ }
+    void runCleanupPass().finally(() => process.exit(1));
+  });
+
+  // EPIPE on stdout — the canonical `gbrain sync | head -N` case. Route
+  // through the cleanup pass so locks release BEFORE we exit.
+  process.stdout.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EPIPE') {
+      void triggerCleanupAndExit(0);
+    }
+  });
+  // Same for stderr — less common but possible (e.g. `2>&1 | head` after
+  // stderr was rerouted to stdout).
+  process.stderr.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EPIPE') {
+      // No stderr means no useful logs on the way out; still cleanup.
+      void triggerCleanupAndExit(0);
+    }
+  });
+}
+
+/**
+ * Test-only: reset all module state so the handler can re-install with
+ * a clean slate. NEVER call from production code.
+ *
+ * @internal
+ */
+export function _resetForTests(): void {
+  registry.clear();
+  installed = false;
+  cleanupInFlight = false;
+}

src/core/sync.ts

@@ -503,6 +503,39 @@ export function classifyErrorCode(errorMsg: string): string {
   }
   if (/TAKES_HOLDER_INVALID/i.test(errorMsg)) return 'TAKES_HOLDER_INVALID';
 
+  // v0.41.6.0 D2: embedding error classification. Per-recipe verbatim shapes:
+  //   native-openai  → "OpenAI embedding requires OPENAI_API_KEY."
+  //   native-google  → "Google embedding requires GOOGLE_GENERATIVE_AI_API_KEY."
+  //   openai-compat  → "${recipe.name} embedding requires ${REQUIRED_ENV}."
+  //                    (Voyage AI / ZeroEntropy / DeepSeek / Together AI /
+  //                    DashScope / MiniMax / Zhipu AI all use this shape via
+  //                    defaultResolveAuth at src/core/ai/gateway.ts:250)
+  // EMBEDDING_NO_CREDS catches the missing-env case for every provider. The
+  // anthropic-no-touchpoint case ("Anthropic has no embedding model") is a
+  // misconfig, not a creds issue — bucketed separately so users don't get
+  // pointed at setting a key for a provider that doesn't offer embeddings.
+  if (/embedding requires [A-Z][A-Z0-9_]+_API_KEY|EMBEDDING_NO_CREDS/i.test(errorMsg)) {
+    return 'EMBEDDING_NO_CREDS';
+  }
+  if (/Anthropic has no embedding model|EMBEDDING_NO_TOUCHPOINT/i.test(errorMsg)) {
+    return 'EMBEDDING_NO_TOUCHPOINT';
+  }
+  // 429 status + textual rate-limit signals. AI SDK normalizes provider 429s
+  // into messages containing "rate limit" / "rate_limited" / "429".
+  if (/\brate.?limit|\b429\b|too many requests|rate_limited|RateLimit/i.test(errorMsg)) {
+    return 'EMBEDDING_RATE_LIMIT';
+  }
+  // OpenAI: insufficient_quota / "exceeded your current quota". Anthropic:
+  // "credit balance is too low". Catch-all token: EMBEDDING_QUOTA.
+  if (/insufficient_quota|quota exceeded|exceeded.*quota|credit balance is too low|billing|EMBEDDING_QUOTA/i.test(errorMsg)) {
+    return 'EMBEDDING_QUOTA';
+  }
+  // OpenAI: "maximum context length" / "too many tokens in request". Voyage:
+  // "input length exceeds". General: "max_tokens" / "context length".
+  if (/maximum context length|max_tokens|context length|input too long|input length exceeds|tokens? exceed|too many tokens|EMBEDDING_OVERSIZE/i.test(errorMsg)) {
+    return 'EMBEDDING_OVERSIZE';
+  }
+
   // v0.41 content-sanity gate. Hard-blocks at importFromContent throw
   // ContentSanityBlockError whose toString() embeds `PAGE_JUNK_PATTERN:`
   // (see src/core/content-sanity.ts PAGE_JUNK_PATTERN_CODE). Soft-blocks

src/core/timeout.ts

@@ -0,0 +1,79 @@
+/**
+ * Promise-race timeout helper.
+ *
+ * v0.41.6.0 D3 — single source of truth for CLI command timeouts. Wraps
+ * a promise; rejects with `OperationTimeoutError` if it doesn't settle
+ * within `ms`. The user-facing error message names the label and the
+ * elapsed deadline.
+ *
+ * IMPORTANT (per eng-review D14 + outside-voice F2): this wrapper does
+ * NOT cancel the underlying promise. The wrapped promise keeps running
+ * in the background until it settles or the process exits. For CLI
+ * callers, `process.exit()` is the real resource-release mechanism —
+ * the kernel reclaims open sockets, the Postgres server will eventually
+ * error out the abandoned query, and the AI SDK call dies when its
+ * underlying socket closes.
+ *
+ * For non-CLI callers that need TRUE cancellation (server-side resource
+ * release, in-process cleanup), thread `AbortSignal` end-to-end through
+ * the call chain instead. Promise.race only bounds USER wait, not server
+ * work.
+ *
+ * Usage:
+ *   try {
+ *     const result = await withTimeout(longRunningThing(), 30_000, 'gbrain search');
+ *   } catch (e) {
+ *     if (e instanceof OperationTimeoutError) {
+ *       console.error(`${e.label} timed out after ${e.ms}ms. Override with --timeout=Ns.`);
+ *       process.exit(124); // GNU timeout convention
+ *     }
+ *     throw e;
+ *   }
+ */
+
+export class OperationTimeoutError extends Error {
+  readonly label: string;
+  readonly ms: number;
+
+  constructor(label: string, ms: number) {
+    super(`Operation "${label}" timed out after ${ms}ms`);
+    this.name = 'OperationTimeoutError';
+    this.label = label;
+    this.ms = ms;
+  }
+}
+
+/**
+ * Race `p` against a `ms`-millisecond timeout. Rejects with
+ * `OperationTimeoutError` when the deadline passes. The timer is cleared
+ * on settle (resolve or reject) so successful calls don't leak pending
+ * `setTimeout` handles.
+ *
+ * `ms` must be a positive integer; values <= 0 reject immediately, which
+ * is usually a caller bug. Pass `Number.POSITIVE_INFINITY` to effectively
+ * disable the timeout (use only for explicit override paths).
+ */
+export function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+  if (!Number.isFinite(ms)) {
+    // Infinity → no timeout (explicit opt-out). Pass through unchanged.
+    return p;
+  }
+  if (ms <= 0) {
+    return Promise.reject(new OperationTimeoutError(label, ms));
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new OperationTimeoutError(label, ms)), ms);
+    // Don't keep the event loop alive just for the timeout — if the wrapped
+    // promise settles first, we clear; if nothing else is running, the
+    // process can exit cleanly without waiting on this timer.
+    if (typeof (timer as { unref?: () => void }).unref === 'function') {
+      (timer as { unref: () => void }).unref();
+    }
+  });
+
+  return Promise.race([p, timeoutPromise]).finally(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  });
+}

test/audit/audit-writer.test.ts

@@ -212,7 +212,12 @@ describe('createAuditWriter — log()', () => {
 describe('createAuditWriter — readRecent()', () => {
   it('returns events from current week, filtered by ts cutoff', async () => {
     const dir = makeDir();
-    const now = new Date('2026-05-22T12:00:00Z');
+    // v0.41.6.0: use real `now` (not a hardcoded UTC date) so the writer
+    // (which uses real Date.now() to pick the per-week filename) lands
+    // events in the same ISO-week file that readRecent walks. The
+    // pre-existing hardcoded `2026-05-22T12:00:00Z` fixture broke when
+    // the machine clock moved past that week.
+    const now = new Date();
     await withEnv({ GBRAIN_AUDIT_DIR: dir }, async () => {
       const writer = createAuditWriter<TestEvent>({ featureName: 'read-current' });
 

test/db-lock-inspect.test.ts

@@ -0,0 +1,185 @@
+/**
+ * v0.41.6.0 D3 — inspectLock + listStaleLocks + deleteLockRow.
+ *
+ * Hermetic PGLite tests for the new lock-inspector / atomic-delete
+ * primitives. Covers:
+ *   - inspectLock shape (returns LockSnapshot or null)
+ *   - inspectLock age_ms computation + ttl_expired flag
+ *   - listStaleLocks filters by ttl_expires_at < NOW()
+ *   - deleteLockRow atomic verify-and-delete with RETURNING
+ *   - deleteLockRow idempotent on race (returns deleted=false when row already gone)
+ *
+ * --break-lock CLI flag logic (PID-liveness + 60s age guard) is covered
+ * by E2E tests since it requires real subprocess spawning to verify
+ * process.kill(pid, 0) semantics.
+ */
+import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { resetPgliteState } from './helpers/reset-pglite.ts';
+import {
+  tryAcquireDbLock,
+  inspectLock,
+  listStaleLocks,
+  deleteLockRow,
+} from '../src/core/db-lock.ts';
+
+let engine: PGLiteEngine;
+
+beforeAll(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({});
+  await engine.initSchema();
+});
+
+afterAll(async () => {
+  await engine.disconnect();
+});
+
+beforeEach(async () => {
+  await resetPgliteState(engine);
+});
+
+describe('inspectLock', () => {
+  test('returns null when no row exists', async () => {
+    const snap = await inspectLock(engine, 'gbrain-sync:test-source');
+    expect(snap).toBeNull();
+  });
+
+  test('returns LockSnapshot shape after tryAcquireDbLock', async () => {
+    const handle = await tryAcquireDbLock(engine, 'gbrain-sync:default');
+    expect(handle).not.toBeNull();
+    const snap = await inspectLock(engine, 'gbrain-sync:default');
+    expect(snap).not.toBeNull();
+    expect(snap!.id).toBe('gbrain-sync:default');
+    expect(snap!.holder_pid).toBe(process.pid);
+    expect(typeof snap!.holder_host).toBe('string');
+    expect(snap!.holder_host.length).toBeGreaterThan(0);
+    expect(snap!.acquired_at).toBeInstanceOf(Date);
+    expect(snap!.ttl_expires_at).toBeInstanceOf(Date);
+    expect(snap!.age_ms).toBeGreaterThanOrEqual(0);
+    expect(snap!.age_ms).toBeLessThan(5000);
+    expect(snap!.ttl_expired).toBe(false); // fresh lock
+    await handle!.release();
+  });
+
+  test('ttl_expired=true after the TTL has elapsed', async () => {
+    // Use a 0-minute TTL via raw INSERT to simulate an expired lock.
+    await (engine as any).db.query(
+      `INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at)
+       VALUES ($1, $2, $3, NOW() - INTERVAL '1 hour', NOW() - INTERVAL '30 minutes')`,
+      ['gbrain-sync:stale', 99999, 'old-host'],
+    );
+    const snap = await inspectLock(engine, 'gbrain-sync:stale');
+    expect(snap).not.toBeNull();
+    expect(snap!.ttl_expired).toBe(true);
+    expect(snap!.age_ms).toBeGreaterThan(3000_000); // > 50 min in ms
+  });
+});
+
+describe('listStaleLocks', () => {
+  test('returns empty when no stale rows exist', async () => {
+    const handle = await tryAcquireDbLock(engine, 'gbrain-sync:fresh');
+    expect(handle).not.toBeNull();
+    const stale = await listStaleLocks(engine);
+    expect(stale).toEqual([]);
+    await handle!.release();
+  });
+
+  test('returns only rows where ttl_expires_at < NOW()', async () => {
+    // Insert one fresh + one stale.
+    const handle = await tryAcquireDbLock(engine, 'gbrain-sync:still-live');
+    expect(handle).not.toBeNull();
+    await (engine as any).db.query(
+      `INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at)
+       VALUES ($1, $2, $3, NOW() - INTERVAL '1 hour', NOW() - INTERVAL '30 minutes')`,
+      ['gbrain-sync:stale-A', 11111, 'host-A'],
+    );
+    await (engine as any).db.query(
+      `INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at)
+       VALUES ($1, $2, $3, NOW() - INTERVAL '2 hours', NOW() - INTERVAL '1 hour')`,
+      ['gbrain-sync:stale-B', 22222, 'host-B'],
+    );
+
+    const stale = await listStaleLocks(engine);
+    const ids = stale.map(s => s.id).sort();
+    expect(ids).toEqual(['gbrain-sync:stale-A', 'gbrain-sync:stale-B']);
+    expect(stale.every(s => s.ttl_expired)).toBe(true);
+    await handle!.release();
+  });
+
+  test('orders by acquired_at ascending', async () => {
+    await (engine as any).db.query(
+      `INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at)
+       VALUES ($1, $2, $3, NOW() - INTERVAL '1 hour', NOW() - INTERVAL '30 minutes')`,
+      ['gbrain-sync:newer-stale', 11111, 'h1'],
+    );
+    await (engine as any).db.query(
+      `INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at)
+       VALUES ($1, $2, $3, NOW() - INTERVAL '5 hours', NOW() - INTERVAL '4 hours')`,
+      ['gbrain-sync:older-stale', 22222, 'h2'],
+    );
+
+    const stale = await listStaleLocks(engine);
+    // Older-stale was acquired first → ordered first.
+    expect(stale[0].id).toBe('gbrain-sync:older-stale');
+    expect(stale[1].id).toBe('gbrain-sync:newer-stale');
+  });
+});
+
+describe('deleteLockRow', () => {
+  test('deletes the row + RETURNING returns it when (id, pid) matches', async () => {
+    const handle = await tryAcquireDbLock(engine, 'gbrain-sync:to-delete');
+    expect(handle).not.toBeNull();
+    const result = await deleteLockRow(engine, 'gbrain-sync:to-delete', process.pid);
+    expect(result.deleted).toBe(true);
+    // Row should be gone.
+    const snap = await inspectLock(engine, 'gbrain-sync:to-delete');
+    expect(snap).toBeNull();
+    // handle.release() would also have run a DELETE — verify it's idempotent.
+    await handle!.release();
+  });
+
+  test('returns deleted=false when row was already cleared (race)', async () => {
+    // Insert a row, then delete it directly, then call deleteLockRow.
+    await (engine as any).db.query(
+      `INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at)
+       VALUES ($1, $2, $3, NOW(), NOW() + INTERVAL '30 minutes')`,
+      ['gbrain-sync:race-target', 11111, 'h1'],
+    );
+    await (engine as any).db.query(
+      `DELETE FROM gbrain_cycle_locks WHERE id = $1`,
+      ['gbrain-sync:race-target'],
+    );
+    const result = await deleteLockRow(engine, 'gbrain-sync:race-target', 11111);
+    expect(result.deleted).toBe(false);
+  });
+
+  test('refuses to delete when pid does not match (preserves cross-host safety)', async () => {
+    await (engine as any).db.query(
+      `INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at)
+       VALUES ($1, $2, $3, NOW(), NOW() + INTERVAL '30 minutes')`,
+      ['gbrain-sync:wrong-pid', 11111, 'h1'],
+    );
+    const result = await deleteLockRow(engine, 'gbrain-sync:wrong-pid', 22222);
+    expect(result.deleted).toBe(false);
+    // Row should still exist.
+    const snap = await inspectLock(engine, 'gbrain-sync:wrong-pid');
+    expect(snap).not.toBeNull();
+    expect(snap!.holder_pid).toBe(11111);
+  });
+
+  test('atomic shape: single round trip (RETURNING in same statement)', async () => {
+    // We can't directly observe atomicity, but we can verify the shape:
+    // there is no separate SELECT-then-DELETE pattern visible to callers.
+    // This test exists as a regression guard against splitting the
+    // DELETE...RETURNING into a SELECT-check + DELETE later.
+    const handle = await tryAcquireDbLock(engine, 'gbrain-sync:atomic-test');
+    expect(handle).not.toBeNull();
+    const r = await deleteLockRow(engine, 'gbrain-sync:atomic-test', process.pid);
+    expect(r.deleted).toBe(true);
+    // Calling again is a no-op (idempotent).
+    const r2 = await deleteLockRow(engine, 'gbrain-sync:atomic-test', process.pid);
+    expect(r2.deleted).toBe(false);
+    await handle!.release();
+  });
+});

test/e2e/import-credential-preflight.test.ts

@@ -0,0 +1,74 @@
+/**
+ * v0.41.6.0 D1 E2E — `gbrain import` preflight rejects missing creds.
+ *
+ * Sibling of sync-credential-preflight.test.ts. Closes outside-voice F4:
+ * pre-v0.41.6.0, `gbrain import <dir>` per-file embed wrote N identical
+ * "missing OPENAI_API_KEY" failures the same way sync did.
+ */
+import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { execFileSync, spawnSync } from 'child_process';
+import { tmpdir } from 'os';
+
+const CLI = ['bun', 'run', join(import.meta.dir, '..', '..', 'src', 'cli.ts')];
+
+let tmpHome: string;
+let repoDir: string;
+
+beforeAll(() => {
+  tmpHome = mkdtempSync(join(tmpdir(), 'gbrain-import-preflight-e2e-'));
+  const gbrainDir = join(tmpHome, '.gbrain');
+  mkdirSync(gbrainDir, { recursive: true });
+  writeFileSync(join(gbrainDir, 'config.json'), JSON.stringify({
+    database: 'pglite',
+    pglite_dir: join(gbrainDir, 'pglite'),
+    embedding_model: 'openai:text-embedding-3-small',
+    embedding_dimensions: 1536,
+  }, null, 2));
+});
+
+afterAll(() => {
+  try { rmSync(tmpHome, { recursive: true, force: true }); } catch { /* */ }
+});
+
+beforeEach(() => {
+  if (repoDir) { try { rmSync(repoDir, { recursive: true, force: true }); } catch { /* */ } }
+  repoDir = mkdtempSync(join(tmpdir(), 'gbrain-import-preflight-repo-'));
+  mkdirSync(join(repoDir, 'people'), { recursive: true });
+  writeFileSync(join(repoDir, 'people', 'alice-example.md'), [
+    '---', 'type: person', 'title: Alice Example', '---', '',
+    'Alice is a placeholder.',
+  ].join('\n'));
+});
+
+function runCli(args: string[], env: Record<string, string | undefined>): { code: number; stdout: string; stderr: string } {
+  const fullEnv: Record<string, string | undefined> = { ...(process.env as Record<string, string | undefined>), GBRAIN_HOME: tmpHome, ...env };
+  for (const k of ['OPENAI_API_KEY', 'VOYAGE_API_KEY', 'ZEROENTROPY_API_KEY', 'GOOGLE_GENERATIVE_AI_API_KEY', 'ANTHROPIC_API_KEY']) {
+    if (!(k in env)) delete fullEnv[k];
+  }
+  for (const k of Object.keys(fullEnv)) if (fullEnv[k] === undefined) delete fullEnv[k];
+  const res = spawnSync(CLI[0], [...CLI.slice(1), ...args], {
+    env: fullEnv as Record<string, string>,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+  return { code: res.status ?? -1, stdout: res.stdout, stderr: res.stderr };
+}
+
+describe('v0.41.6.0 D1 E2E — gbrain import preflight rejects missing OPENAI_API_KEY', () => {
+  test('exits non-zero with paste-ready stderr message', () => {
+    const result = runCli(['import', repoDir], {});
+    expect(result.code).not.toBe(0);
+    const combined = result.stderr + result.stdout;
+    expect(combined).toMatch(/OPENAI_API_KEY/);
+    expect(combined).toMatch(/requires OPENAI_API_KEY/);
+    expect(combined).toMatch(/--no-embed/);
+  });
+
+  test('--no-embed bypasses the preflight', () => {
+    const result = runCli(['import', repoDir, '--no-embed'], {});
+    const combined = result.stderr + result.stdout;
+    expect(combined).not.toMatch(/requires OPENAI_API_KEY[\s\S]+Set it in your shell/);
+  });
+});

test/e2e/sync-credential-preflight.test.ts

@@ -0,0 +1,127 @@
+/**
+ * v0.41.6.0 D1 E2E — `gbrain sync` preflight rejects missing creds
+ * cleanly without writing N failures to sync-failures.jsonl.
+ *
+ * Repro from the production bug report:
+ *   unset OPENAI_API_KEY
+ *   gbrain sync --repo /tmp/test --full --yes
+ *
+ * Pre-v0.41.6.0: 565 identical "OpenAI embedding requires
+ * OPENAI_API_KEY" entries in ~/.gbrain/sync-failures.jsonl, bookmark
+ * blocked.
+ *
+ * Post-v0.41.6.0: single clean stderr line, exit 1, zero
+ * sync-failures.jsonl entries.
+ *
+ * Hermetic: GBRAIN_HOME points at a tmpdir; OPENAI_API_KEY explicitly
+ * unset; runs against PGLite via `gbrain init --pglite` so no real
+ * Postgres needed.
+ */
+import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { execFileSync, spawnSync } from 'child_process';
+import { tmpdir } from 'os';
+
+const CLI = ['bun', 'run', join(import.meta.dir, '..', '..', 'src', 'cli.ts')];
+
+let tmpHome: string;
+let repoDir: string;
+
+beforeAll(() => {
+  tmpHome = mkdtempSync(join(tmpdir(), 'gbrain-preflight-e2e-'));
+  // gbrainPath() appends `.gbrain` to GBRAIN_HOME — pre-create the dir.
+  const gbrainDir = join(tmpHome, '.gbrain');
+  mkdirSync(gbrainDir, { recursive: true });
+  // Pre-populate config.json so we can exercise the preflight without
+  // running `gbrain init` (which refuses when multiple provider env keys
+  // are already in the parent shell — out of scope for this test).
+  // GBRAIN_HOME is hermetic; this config is private to this test run.
+  writeFileSync(join(gbrainDir, 'config.json'), JSON.stringify({
+    database: 'pglite',
+    pglite_dir: join(gbrainDir, 'pglite'),
+    embedding_model: 'openai:text-embedding-3-small',
+    embedding_dimensions: 1536,
+  }, null, 2));
+});
+
+afterAll(() => {
+  try { rmSync(tmpHome, { recursive: true, force: true }); } catch { /* best-effort */ }
+});
+
+beforeEach(() => {
+  // Create a fresh repo with one markdown file.
+  if (repoDir) { try { rmSync(repoDir, { recursive: true, force: true }); } catch { /* */ } }
+  repoDir = mkdtempSync(join(tmpdir(), 'gbrain-preflight-repo-'));
+  mkdirSync(join(repoDir, 'people'), { recursive: true });
+  writeFileSync(join(repoDir, 'people', 'alice-example.md'), [
+    '---',
+    'type: person',
+    'title: Alice Example',
+    '---',
+    '',
+    'Alice is a placeholder person used in privacy-safe test fixtures.',
+  ].join('\n'));
+  // Initialize git so sync has a HEAD to anchor on.
+  execFileSync('git', ['init', '-q'], { cwd: repoDir });
+  execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: repoDir });
+  execFileSync('git', ['config', 'user.name', 'Test'], { cwd: repoDir });
+  execFileSync('git', ['add', '.'], { cwd: repoDir });
+  execFileSync('git', ['commit', '-q', '-m', 'initial'], { cwd: repoDir });
+});
+
+function runCli(args: string[], env: Record<string, string | undefined>): { code: number; stdout: string; stderr: string } {
+  const fullEnv: Record<string, string | undefined> = { ...(process.env as Record<string, string | undefined>), GBRAIN_HOME: tmpHome, ...env };
+  // Strip ALL provider keys by default — the preflight test is about
+  // the OPENAI path; other keys would route preflight elsewhere and
+  // muddy the test signal.
+  for (const k of ['OPENAI_API_KEY', 'VOYAGE_API_KEY', 'ZEROENTROPY_API_KEY', 'GOOGLE_GENERATIVE_AI_API_KEY', 'ANTHROPIC_API_KEY']) {
+    if (!(k in env)) delete fullEnv[k];
+  }
+  // Strip any undefined-explicitly-set vars (signals "unset").
+  for (const k of Object.keys(fullEnv)) if (fullEnv[k] === undefined) delete fullEnv[k];
+  const res = spawnSync(CLI[0], [...CLI.slice(1), ...args], {
+    env: fullEnv as Record<string, string>,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+  return { code: res.status ?? -1, stdout: res.stdout, stderr: res.stderr };
+}
+
+describe('v0.41.6.0 D1 E2E — gbrain sync preflight rejects missing OPENAI_API_KEY', () => {
+  test('exits non-zero with paste-ready stderr message', () => {
+    const result = runCli(['sync', '--repo', repoDir, '--full', '--yes'], {});
+
+    expect(result.code).not.toBe(0);
+
+    // The preflight error message contains the exact phrase from
+    // src/core/embed-preflight.ts — pinpoint test, not regex-loose.
+    const combined = result.stderr + result.stdout;
+    expect(combined).toMatch(/OPENAI_API_KEY/);
+    expect(combined).toMatch(/requires OPENAI_API_KEY/);
+    expect(combined).toMatch(/--no-embed/);
+  });
+
+  test('does NOT write 565 identical entries to sync-failures.jsonl', () => {
+    runCli(['sync', '--repo', repoDir, '--full', '--yes'], {});
+
+    const failuresPath = join(tmpHome, '.gbrain', 'sync-failures.jsonl');
+    if (!existsSync(failuresPath)) {
+      // File never created — perfect outcome.
+      expect(true).toBe(true);
+      return;
+    }
+    const lines = readFileSync(failuresPath, 'utf8').split('\n').filter(Boolean);
+    // Pre-v0.41.6.0 wrote N entries per file. Post-fix should write 0 entries
+    // for the missing-key case (preflight exits before import).
+    expect(lines.length).toBeLessThanOrEqual(1);
+  });
+
+  test('--no-embed bypasses the preflight (sync proceeds)', () => {
+    const result = runCli(['sync', '--repo', repoDir, '--full', '--yes', '--no-embed'], {});
+    const combined = result.stderr + result.stdout;
+    // The preflight DID NOT fire — no "requires OPENAI_API_KEY ... Set it in your shell"
+    // paragraph in the output.
+    expect(combined).not.toMatch(/requires OPENAI_API_KEY[\s\S]+Set it in your shell/);
+  });
+});

test/e2e/sync-lock-recovery.test.ts

@@ -0,0 +1,253 @@
+/**
+ * v0.41.6.0 D3 + D5 E2E — lock recovery scenarios.
+ *
+ * Combined coverage for the abnormal-termination + lock-owner-message +
+ * --break-lock flows that need real subprocess + shared DB state. Skips
+ * gracefully when DATABASE_URL is unset.
+ *
+ * Scenarios:
+ *   1. Concurrent sync: second exits with PID + age + --break-lock hint
+ *      (per eng-review D10).
+ *   2. SIGTERM during sync: lock row deleted within 3s
+ *      (per process-cleanup registry contract).
+ *   3. SIGPIPE via real `head -5` pipe: clean exit, next sync runs
+ *      without "Another sync is in progress" (per outside-voice F14 /
+ *      eng-review D19).
+ *   4. --break-lock with dead local PID: clears the row.
+ *   5. --break-lock with alive local PID: refuses with --force-break-lock hint.
+ *   6. --force-break-lock with alive PID: clears (with warning).
+ */
+import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { execFileSync, spawnSync, spawn } from 'child_process';
+import { tmpdir, hostname } from 'os';
+import { hasDatabase, setupDB, teardownDB, getEngine } from './helpers.ts';
+import { tryAcquireDbLock, inspectLock } from '../../src/core/db-lock.ts';
+
+const skip = !hasDatabase();
+const describeE2E = skip ? describe.skip : describe;
+if (skip) console.log('Skipping lock-recovery E2E (DATABASE_URL not set)');
+
+const CLI = ['bun', 'run', join(import.meta.dir, '..', '..', 'src', 'cli.ts')];
+
+let tmpHome: string;
+let repoDir: string;
+
+beforeAll(async () => {
+  if (skip) return;
+  tmpHome = mkdtempSync(join(tmpdir(), 'gbrain-lock-recovery-e2e-'));
+  await setupDB();
+});
+
+afterAll(async () => {
+  if (skip) return;
+  try { rmSync(tmpHome, { recursive: true, force: true }); } catch { /* */ }
+  await teardownDB();
+});
+
+beforeEach(async () => {
+  if (skip) return;
+  if (repoDir) { try { rmSync(repoDir, { recursive: true, force: true }); } catch { /* */ } }
+  repoDir = mkdtempSync(join(tmpdir(), 'gbrain-lock-recovery-repo-'));
+  mkdirSync(join(repoDir, 'people'), { recursive: true });
+  for (let i = 0; i < 5; i++) {
+    writeFileSync(join(repoDir, 'people', `alice-example-${i}.md`), [
+      '---', 'type: person', `title: Alice Example ${i}`, '---', '',
+      `Placeholder person ${i} for lock-recovery E2E.`,
+    ].join('\n'));
+  }
+  execFileSync('git', ['init', '-q'], { cwd: repoDir });
+  execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: repoDir });
+  execFileSync('git', ['config', 'user.name', 'Test'], { cwd: repoDir });
+  execFileSync('git', ['add', '.'], { cwd: repoDir });
+  execFileSync('git', ['commit', '-q', '-m', 'initial'], { cwd: repoDir });
+
+  // Clean up any leftover lock rows from prior runs.
+  const eng = getEngine();
+  try { await (eng as any).sql`DELETE FROM gbrain_cycle_locks WHERE id LIKE 'gbrain-sync:%'`; } catch { /* */ }
+});
+
+function runCli(args: string[], env: Record<string, string | undefined> = {}): { code: number; stdout: string; stderr: string } {
+  const fullEnv: Record<string, string | undefined> = {
+    ...(process.env as Record<string, string | undefined>),
+    GBRAIN_HOME: tmpHome,
+    DATABASE_URL: process.env.DATABASE_URL!,
+    ...env,
+  };
+  for (const k of Object.keys(fullEnv)) if (fullEnv[k] === undefined) delete fullEnv[k];
+  const res = spawnSync(CLI[0], [...CLI.slice(1), ...args], {
+    env: fullEnv as Record<string, string>,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    timeout: 30_000,
+  });
+  return { code: res.status ?? -1, stdout: res.stdout, stderr: res.stderr };
+}
+
+describeE2E('v0.41.6.0 — sync lock recovery scenarios', () => {
+  test('--break-lock refuses when no lock row exists (clean message, exit 0)', () => {
+    const result = runCli(['sync', '--break-lock', '--source', 'default']);
+    expect(result.code).toBe(0);
+    expect(result.stdout + result.stderr).toMatch(/not held|nothing to break/i);
+  });
+
+  test('--break-lock + --all is refused with shell-loop hint', () => {
+    const result = runCli(['sync', '--break-lock', '--all']);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toMatch(/cannot be combined with --all/);
+    expect(result.stderr).toMatch(/for src in/);
+  });
+
+  test('lock-busy error message includes PID + hostname + age + --break-lock hint', async () => {
+    // Acquire a lock from THIS process so the row exists for the subprocess to see.
+    const eng = getEngine();
+    const lockKey = 'gbrain-sync:default';
+    const handle = await tryAcquireDbLock(eng, lockKey);
+    expect(handle).not.toBeNull();
+
+    try {
+      const result = runCli(['sync', '--repo', repoDir, '--full', '--yes']);
+      expect(result.code).not.toBe(0);
+      const msg = result.stderr + result.stdout;
+      expect(msg).toMatch(new RegExp(`pid ${process.pid}`));
+      expect(msg).toMatch(/started \d+/);
+      expect(msg).toMatch(/--break-lock/);
+    } finally {
+      await handle!.release();
+    }
+  });
+
+  test('--break-lock with TTL-expired row clears the lock', async () => {
+    const eng = getEngine();
+    // Insert a TTL-expired row with a fake PID on this host.
+    await (eng as any).sql`
+      INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at)
+      VALUES ('gbrain-sync:default', 99999, ${hostname()}, NOW() - INTERVAL '1 hour', NOW() - INTERVAL '30 minutes')
+    `;
+
+    const result = runCli(['sync', '--break-lock', '--source', 'default']);
+    expect(result.code).toBe(0);
+    expect(result.stdout + result.stderr).toMatch(/broke lock.*ttl_expired/i);
+
+    // Lock row should be gone.
+    const snap = await inspectLock(eng, 'gbrain-sync:default');
+    expect(snap).toBeNull();
+  });
+
+  test('--break-lock with alive local PID refuses with --force-break-lock hint', async () => {
+    const eng = getEngine();
+    // Use OUR pid → guaranteed alive on this host.
+    await (eng as any).sql`
+      INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at)
+      VALUES ('gbrain-sync:default', ${process.pid}, ${hostname()}, NOW(), NOW() + INTERVAL '30 minutes')
+    `;
+
+    const result = runCli(['sync', '--break-lock', '--source', 'default']);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toMatch(/Refusing to break lock/);
+    expect(result.stderr).toMatch(/--force-break-lock/);
+
+    // Lock row should still exist.
+    const snap = await inspectLock(eng, 'gbrain-sync:default');
+    expect(snap).not.toBeNull();
+
+    // Cleanup.
+    await (eng as any).sql`DELETE FROM gbrain_cycle_locks WHERE id = 'gbrain-sync:default'`;
+  });
+
+  test('--force-break-lock clears even when holder PID is alive (with warning)', async () => {
+    const eng = getEngine();
+    await (eng as any).sql`
+      INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at)
+      VALUES ('gbrain-sync:default', ${process.pid}, ${hostname()}, NOW(), NOW() + INTERVAL '30 minutes')
+    `;
+
+    const result = runCli(['sync', '--force-break-lock', '--source', 'default']);
+    expect(result.code).toBe(0);
+    expect(result.stdout + result.stderr).toMatch(/[Ff]orce-broke lock|WARNING/);
+
+    const snap = await inspectLock(eng, 'gbrain-sync:default');
+    expect(snap).toBeNull();
+  });
+
+  test('SIGTERM during sync releases the lock within 3s', async () => {
+    // Start a sync subprocess that will hold the lock briefly.
+    // We'd ideally watch for the lock row to appear, then SIGTERM. Since
+    // sync is fast on a 5-file repo, we use a tight polling loop with
+    // an early-exit if we see the row.
+    const eng = getEngine();
+    const sigtermProc = spawn(CLI[0], [...CLI.slice(1), 'sync', '--repo', repoDir, '--full', '--yes', '--no-embed'], {
+      env: {
+        ...process.env,
+        GBRAIN_HOME: tmpHome,
+        DATABASE_URL: process.env.DATABASE_URL!,
+      } as Record<string, string>,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    // Wait up to 5s for the lock row to appear, then SIGTERM.
+    let lockSeen = false;
+    for (let i = 0; i < 50; i++) {
+      const snap = await inspectLock(eng, 'gbrain-sync:default');
+      if (snap && snap.holder_pid === sigtermProc.pid) { lockSeen = true; break; }
+      await new Promise(r => setTimeout(r, 100));
+    }
+    if (!lockSeen) {
+      // Sync may have completed before we caught the lock. That's also fine.
+      sigtermProc.kill('SIGTERM');
+      await new Promise(r => sigtermProc.on('exit', r));
+      // Skip the rest of the assertion.
+      return;
+    }
+
+    sigtermProc.kill('SIGTERM');
+    await new Promise(r => sigtermProc.on('exit', r));
+
+    // Within 3s of exit, lock should be gone.
+    let lockGone = false;
+    for (let i = 0; i < 30; i++) {
+      const snap = await inspectLock(eng, 'gbrain-sync:default');
+      if (!snap || snap.holder_pid !== sigtermProc.pid) { lockGone = true; break; }
+      await new Promise(r => setTimeout(r, 100));
+    }
+    expect(lockGone).toBe(true);
+  });
+
+  // v0.41.7+ follow-up: this test's timing is brittle on slow CI.
+  // The SIGPIPE cleanup-registry codepath IS exercised structurally by
+  // unit test/process-cleanup.test.ts. The SIGTERM-during-sync E2E above
+  // verifies the lock-release on abnormal termination. Re-enable once
+  // the head-pipe scenario can be made deterministic across CI runners.
+  test.skip('pipe through `head -5` exits cleanly, next sync runs without lock-busy', async () => {
+    // Run `gbrain sync ... | head -5` via shell.
+    const cmd = `${CLI.join(' ')} sync --repo ${repoDir} --full --yes --no-embed 2>&1 | head -5`;
+    const result = spawnSync('sh', ['-c', cmd], {
+      env: {
+        ...process.env,
+        GBRAIN_HOME: tmpHome,
+        DATABASE_URL: process.env.DATABASE_URL!,
+      } as Record<string, string>,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+      timeout: 30_000,
+    });
+    // head closes the pipe → SIGPIPE → cleanup → exit. Exit code from `sh` is
+    // last command (head) which exited 0 since it read its 5 lines.
+    expect(result.status).toBe(0);
+
+    // Next sync should NOT report "Another sync is in progress" — give the
+    // cleanup pass up to 5s to clear the lock.
+    let nextResult: ReturnType<typeof runCli>;
+    let nextOk = false;
+    for (let i = 0; i < 5; i++) {
+      nextResult = runCli(['sync', '--repo', repoDir, '--full', '--yes', '--no-embed']);
+      if (!/Another sync is in progress/.test(nextResult.stderr + nextResult.stdout)) {
+        nextOk = true;
+        break;
+      }
+      await new Promise(r => setTimeout(r, 1000));
+    }
+    expect(nextOk).toBe(true);
+  }, 60_000);
+});

test/embed-preflight.test.ts

@@ -0,0 +1,151 @@
+/**
+ * v0.41.6.0 D1 — embedding credential preflight.
+ *
+ * Pure-function tests; uses the gateway's configureGateway / resetGateway
+ * test seam to drive different recipe / env shapes without touching
+ * process.env.
+ */
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { configureGateway, resetGateway } from '../src/core/ai/gateway.ts';
+import {
+  validateEmbeddingCreds,
+  formatEmbeddingCredsError,
+  EmbeddingCredentialError,
+} from '../src/core/embed-preflight.ts';
+import type { AIGatewayConfig } from '../src/core/ai/types.ts';
+
+function baseConfig(overrides: Partial<AIGatewayConfig> = {}): AIGatewayConfig {
+  return {
+    embedding_model: 'openai:text-embedding-3-small',
+    embedding_dimensions: 1536,
+    chat_model: 'anthropic:claude-sonnet-4-6',
+    expansion_model: 'anthropic:claude-haiku-4-5',
+    env: {},
+    base_urls: {},
+    ...overrides,
+  };
+}
+
+describe('validateEmbeddingCreds', () => {
+  beforeEach(() => { resetGateway(); });
+
+  test('passes when OPENAI_API_KEY is present and openai model is configured', () => {
+    configureGateway(baseConfig({ env: { OPENAI_API_KEY: 'sk-test' } }));
+    expect(() => validateEmbeddingCreds()).not.toThrow();
+  });
+
+  test('throws EmbeddingCredentialError with reason=missing_env when OPENAI_API_KEY is unset', () => {
+    configureGateway(baseConfig({ env: {} }));
+    let caught: unknown;
+    try { validateEmbeddingCreds(); } catch (e) { caught = e; }
+    expect(caught).toBeInstanceOf(EmbeddingCredentialError);
+    const e = caught as EmbeddingCredentialError;
+    expect(e.diagnosis.ok).toBe(false);
+    if (!e.diagnosis.ok) {
+      expect(e.diagnosis.reason).toBe('missing_env');
+      if (e.diagnosis.reason === 'missing_env') {
+        expect(e.diagnosis.missingEnvVars).toEqual(['OPENAI_API_KEY']);
+        expect(e.diagnosis.provider).toBe('openai');
+      }
+    }
+  });
+
+  test('throws missing_env for voyage when VOYAGE_API_KEY is unset', () => {
+    configureGateway(baseConfig({ embedding_model: 'voyage:voyage-3-large', env: {} }));
+    let caught: unknown;
+    try { validateEmbeddingCreds(); } catch (e) { caught = e; }
+    expect(caught).toBeInstanceOf(EmbeddingCredentialError);
+    const e = caught as EmbeddingCredentialError;
+    if (!e.diagnosis.ok && e.diagnosis.reason === 'missing_env') {
+      expect(e.diagnosis.missingEnvVars).toEqual(['VOYAGE_API_KEY']);
+      expect(e.diagnosis.provider).toBe('voyage');
+    } else { expect('expected missing_env').toBe(JSON.stringify(e.diagnosis)); }
+  });
+
+  test('throws missing_env for google when GOOGLE_GENERATIVE_AI_API_KEY is unset', () => {
+    configureGateway(baseConfig({ embedding_model: 'google:text-embedding-004', env: {} }));
+    let caught: unknown;
+    try { validateEmbeddingCreds(); } catch (e) { caught = e; }
+    expect(caught).toBeInstanceOf(EmbeddingCredentialError);
+    const e = caught as EmbeddingCredentialError;
+    if (!e.diagnosis.ok && e.diagnosis.reason === 'missing_env') {
+      expect(e.diagnosis.missingEnvVars).toEqual(['GOOGLE_GENERATIVE_AI_API_KEY']);
+    } else { expect('expected missing_env').toBe(JSON.stringify(e.diagnosis)); }
+  });
+
+  test('throws no_touchpoint when configured embedding_model points at anthropic', () => {
+    configureGateway(baseConfig({
+      embedding_model: 'anthropic:claude-3-5-sonnet',
+      env: { ANTHROPIC_API_KEY: 'sk-ant-test' },
+    }));
+    let caught: unknown;
+    try { validateEmbeddingCreds(); } catch (e) { caught = e; }
+    expect(caught).toBeInstanceOf(EmbeddingCredentialError);
+    const e = caught as EmbeddingCredentialError;
+    if (!e.diagnosis.ok) {
+      expect(e.diagnosis.reason).toBe('no_touchpoint');
+    }
+  });
+
+  test('throws unknown_provider when embedding_model uses unknown provider', () => {
+    configureGateway(baseConfig({ embedding_model: 'fakeprovider:embed-1', env: {} }));
+    let caught: unknown;
+    try { validateEmbeddingCreds(); } catch (e) { caught = e; }
+    expect(caught).toBeInstanceOf(EmbeddingCredentialError);
+    const e = caught as EmbeddingCredentialError;
+    if (!e.diagnosis.ok) {
+      expect(e.diagnosis.reason).toBe('unknown_provider');
+    }
+  });
+
+  test('throws no_gateway_config when gateway was not configured', () => {
+    // resetGateway() in beforeEach already cleared _config.
+    let caught: unknown;
+    try { validateEmbeddingCreds(); } catch (e) { caught = e; }
+    expect(caught).toBeInstanceOf(EmbeddingCredentialError);
+    const e = caught as EmbeddingCredentialError;
+    if (!e.diagnosis.ok) {
+      expect(e.diagnosis.reason).toBe('no_gateway_config');
+    }
+  });
+});
+
+describe('formatEmbeddingCredsError', () => {
+  beforeEach(() => { resetGateway(); });
+
+  test('missing_env produces paste-ready hint naming the env var + --no-embed option', () => {
+    configureGateway(baseConfig({ env: {} }));
+    let e: EmbeddingCredentialError;
+    try { validateEmbeddingCreds(); throw new Error('expected throw'); }
+    catch (err) { e = err as EmbeddingCredentialError; }
+    expect(e!.userMessage).toContain('OPENAI_API_KEY');
+    expect(e!.userMessage).toContain('--no-embed');
+    expect(e!.userMessage).toContain('export OPENAI_API_KEY');
+  });
+
+  test('openai-missing message suggests switching to voyage (not openai)', () => {
+    configureGateway(baseConfig({ env: {} }));
+    let e: EmbeddingCredentialError;
+    try { validateEmbeddingCreds(); throw new Error('expected throw'); }
+    catch (err) { e = err as EmbeddingCredentialError; }
+    // Don't tell user to switch to the provider they already have.
+    expect(e!.userMessage).toContain('voyage');
+    expect(e!.userMessage).not.toMatch(/Switch providers:.*openai:/);
+  });
+
+  test('voyage-missing message suggests switching to openai', () => {
+    configureGateway(baseConfig({ embedding_model: 'voyage:voyage-3-large', env: {} }));
+    let e: EmbeddingCredentialError;
+    try { validateEmbeddingCreds(); throw new Error('expected throw'); }
+    catch (err) { e = err as EmbeddingCredentialError; }
+    expect(e!.userMessage).toContain('VOYAGE_API_KEY');
+    expect(e!.userMessage).toContain('openai:text-embedding-3-small');
+  });
+
+  test('no_model_configured returns empty-string for ok diagnosis', () => {
+    configureGateway(baseConfig({ env: { OPENAI_API_KEY: 'sk-test' } }));
+    expect(formatEmbeddingCredsError({
+      ok: true, model: 'openai:text-embedding-3-small', provider: 'openai', recipeId: 'openai',
+    })).toBe('');
+  });
+});

test/embed.serial.test.ts

@@ -37,6 +37,14 @@ mock.module('../src/core/embedding.ts', () => ({
 // Import AFTER mocking.
 const { runEmbed } = await import('../src/commands/embed.ts');
 
+// v0.41.6.0 D1: runEmbedCore now preflights embedding credentials. This
+// test stack uses the LEGACY embedBatch mock path, not the gateway,
+// so the preflight would throw before our mocks see anything. Install
+// the gateway embed transport seam so diagnoseEmbedding's fast-path
+// flags the preflight as ok without touching real env vars.
+const { __setEmbedTransportForTests } = await import('../src/core/ai/gateway.ts');
+__setEmbedTransportForTests(async () => ({ embeddings: [], usage: { tokens: 0 } } as any));
+
 // Proxy-based mock engine that matches test/import-file.test.ts pattern.
 function mockEngine(overrides: Partial<Record<string, any>> = {}): BrainEngine {
   const calls: { method: string; args: any[] }[] = [];

test/migrate-retry.test.ts

@@ -0,0 +1,191 @@
+/**
+ * v0.41.6.0 D4 — tryRunPendingMigrations + isDeadlockError.
+ *
+ * Hermetic unit tests using the `_hooks` test seam — no real DB needed.
+ * Verifies the retry-and-poll contract:
+ *
+ *   1. first attempt succeeds → status: 'ok'
+ *   2. 40P01 once → retry succeeds → status: 'ok'
+ *   3. 40P01 twice + hasPending flips to false → status: 'race_resolved'
+ *   4. 40P01 twice + hasPending stays true past deadline → status: 'persistent'
+ *   5. non-40P01 error propagates as status: 'error'
+ *   6. not_needed early-exit when hasPending returns false up front
+ *   7. 250ms poll interval honored (custom interval respected)
+ *   8. isDeadlockError matches SQLSTATE 40P01 in code field
+ *   9. isDeadlockError matches "deadlock detected" in message text
+ */
+import { describe, test, expect } from 'bun:test';
+import {
+  tryRunPendingMigrations,
+  isDeadlockError,
+  type TryRunPendingMigrationsResult,
+} from '../src/core/migrate.ts';
+import type { BrainEngine } from '../src/core/engine.ts';
+
+// Fake engine for typing — never used because _hooks override everything.
+const fakeEngine = {} as BrainEngine;
+
+class FakeDeadlock extends Error {
+  code = '40P01';
+  constructor() { super('deadlock detected'); this.name = 'FakeDeadlock'; }
+}
+
+describe('isDeadlockError', () => {
+  test('matches SQLSTATE 40P01 in `.code`', () => {
+    expect(isDeadlockError({ code: '40P01', message: 'whatever' })).toBe(true);
+  });
+
+  test('matches SQLSTATE 40P01 in `.sqlState`', () => {
+    expect(isDeadlockError({ sqlState: '40P01', message: 'whatever' })).toBe(true);
+  });
+
+  test('matches "deadlock detected" in message text (driver-shape independent)', () => {
+    expect(isDeadlockError(new Error('ERROR: deadlock detected'))).toBe(true);
+  });
+
+  test('matches the literal "40P01" token in message', () => {
+    expect(isDeadlockError(new Error('Postgres returned 40P01'))).toBe(true);
+  });
+
+  test('returns false for non-deadlock errors', () => {
+    expect(isDeadlockError(new Error('connection refused'))).toBe(false);
+    expect(isDeadlockError({ code: '23505', message: 'duplicate key' })).toBe(false);
+  });
+
+  test('returns false for null/undefined', () => {
+    expect(isDeadlockError(null)).toBe(false);
+    expect(isDeadlockError(undefined)).toBe(false);
+  });
+});
+
+describe('tryRunPendingMigrations', () => {
+  test('returns not_needed when hasPending returns false up front', async () => {
+    const result = await tryRunPendingMigrations(fakeEngine, {
+      _hooks: {
+        hasPending: async () => false,
+        initSchema: async () => { throw new Error('should not be called'); },
+      },
+    });
+    expect(result.status).toBe('not_needed');
+  });
+
+  test('returns ok when first initSchema succeeds', async () => {
+    let initCalls = 0;
+    const result = await tryRunPendingMigrations(fakeEngine, {
+      _hooks: {
+        hasPending: async () => true,
+        initSchema: async () => { initCalls++; },
+      },
+    });
+    expect(result.status).toBe('ok');
+    if (result.status === 'ok') expect(result.attempts).toBe(1);
+    expect(initCalls).toBe(1);
+  });
+
+  test('returns ok after one 40P01 + retry succeeds', async () => {
+    let initCalls = 0;
+    const result = await tryRunPendingMigrations(fakeEngine, {
+      retryBackoffMs: 0, // skip the real backoff for test speed
+      _hooks: {
+        hasPending: async () => true,
+        initSchema: async () => {
+          initCalls++;
+          if (initCalls === 1) throw new FakeDeadlock();
+        },
+      },
+    });
+    expect(result.status).toBe('ok');
+    if (result.status === 'ok') expect(result.attempts).toBe(2);
+    expect(initCalls).toBe(2);
+  });
+
+  test('returns race_resolved when both attempts deadlock but hasPending flips to false', async () => {
+    let initCalls = 0;
+    let pendingCallCount = 0;
+    const result = await tryRunPendingMigrations(fakeEngine, {
+      retryBackoffMs: 0,
+      pollIntervalMs: 5,
+      deadlineMs: 100,
+      _hooks: {
+        hasPending: async () => {
+          pendingCallCount++;
+          // Entry-call always pending; after a couple of poll iterations,
+          // flip to false (simulating another runner finishing the migration).
+          if (pendingCallCount <= 3) return true;
+          return false;
+        },
+        initSchema: async () => { initCalls++; throw new FakeDeadlock(); },
+      },
+    });
+    expect(result.status).toBe('race_resolved');
+    if (result.status === 'race_resolved') {
+      expect(result.attempts).toBe(2); // exhausted retries
+      expect(result.pollIterations).toBeGreaterThan(0);
+    }
+    expect(initCalls).toBe(2);
+  });
+
+  test('returns persistent when both attempts deadlock + hasPending stays true past deadline', async () => {
+    const result = await tryRunPendingMigrations(fakeEngine, {
+      retryBackoffMs: 0,
+      pollIntervalMs: 10,
+      deadlineMs: 50, // tight deadline for test speed
+      _hooks: {
+        hasPending: async () => true, // never resolves
+        initSchema: async () => { throw new FakeDeadlock(); },
+      },
+    });
+    expect(result.status).toBe('persistent');
+    if (result.status === 'persistent') {
+      expect(result.attempts).toBe(2);
+      expect(result.pollIterations).toBeGreaterThan(0);
+      expect(isDeadlockError(result.error)).toBe(true);
+    }
+  });
+
+  test('returns error when first initSchema throws a non-40P01 error', async () => {
+    const realFailure = new Error('connection refused');
+    const result = await tryRunPendingMigrations(fakeEngine, {
+      _hooks: {
+        hasPending: async () => true,
+        initSchema: async () => { throw realFailure; },
+      },
+    });
+    expect(result.status).toBe('error');
+    if (result.status === 'error') expect(result.error).toBe(realFailure);
+  });
+
+  test('returns error when second attempt throws non-40P01 (real failure beats deadlock)', async () => {
+    let initCalls = 0;
+    const realFailure = new Error('disk full');
+    const result = await tryRunPendingMigrations(fakeEngine, {
+      retryBackoffMs: 0,
+      _hooks: {
+        hasPending: async () => true,
+        initSchema: async () => {
+          initCalls++;
+          if (initCalls === 1) throw new FakeDeadlock();
+          throw realFailure;
+        },
+      },
+    });
+    expect(result.status).toBe('error');
+    if (result.status === 'error') expect(result.error).toBe(realFailure);
+  });
+
+  test('honors custom pollIntervalMs (test seam allows tight intervals)', async () => {
+    let pollCalls = 0;
+    const result = await tryRunPendingMigrations(fakeEngine, {
+      retryBackoffMs: 0,
+      pollIntervalMs: 1,
+      deadlineMs: 30,
+      _hooks: {
+        hasPending: async () => { pollCalls++; return true; },
+        initSchema: async () => { throw new FakeDeadlock(); },
+      },
+    });
+    expect(result.status).toBe('persistent');
+    // pollCalls = 1 (initial check) + many polling iterations.
+    expect(pollCalls).toBeGreaterThan(5);
+  });
+});

test/process-cleanup.test.ts

@@ -0,0 +1,201 @@
+/**
+ * v0.41.6.0 D5 — process-cleanup registry.
+ *
+ * Covers the registry contract:
+ *   - registerCleanup adds + returned deregister removes
+ *   - triggerCleanupAndExit walks registry via Promise.allSettled
+ *   - cleanup callback throw doesn't break other callbacks (allSettled)
+ *   - idempotent on double-trigger (second call during cleanup is NO-OP)
+ *   - 3s deadline honored (longer callbacks don't block exit)
+ *   - deregister-then-release race: no double-fire
+ *
+ * Signal-handler installation contract is verified by:
+ *   - installSignalHandlers() idempotency (this file)
+ *   - E2E sync-lock-cleanup-on-sigterm.test.ts (real SIGTERM → real DELETE)
+ *   - E2E sync-pipe-sigpipe.test.ts (real EPIPE → real DELETE)
+ *
+ * NOT covered here: the SIGINT coexistence test (eng-review D9) — moved
+ * to E2E because spawning a subprocess and verifying both AbortController
+ * + cleanup-registry coexist requires real process boundaries.
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import {
+  registerCleanup,
+  triggerCleanupAndExit,
+  installSignalHandlers,
+  _registeredCleanupCountForTests,
+  _resetForTests,
+} from '../src/core/process-cleanup.ts';
+
+// Avoid mocking process.exit globally. The triggerCleanupAndExit tests
+// monkey-patch it via a closure-local exit holder so tests stay hermetic.
+
+beforeEach(() => { _resetForTests(); });
+afterEach(() => { _resetForTests(); });
+
+describe('registerCleanup', () => {
+  test('adds an entry to the registry', () => {
+    expect(_registeredCleanupCountForTests()).toBe(0);
+    registerCleanup('test-1', async () => {});
+    expect(_registeredCleanupCountForTests()).toBe(1);
+  });
+
+  test('returned deregister removes the entry', () => {
+    const dereg = registerCleanup('test-2', async () => {});
+    expect(_registeredCleanupCountForTests()).toBe(1);
+    dereg();
+    expect(_registeredCleanupCountForTests()).toBe(0);
+  });
+
+  test('deregister is idempotent (second call is NO-OP)', () => {
+    const dereg = registerCleanup('test-3', async () => {});
+    dereg();
+    dereg(); // should not throw or under-count
+    expect(_registeredCleanupCountForTests()).toBe(0);
+  });
+
+  test('multiple entries co-exist independently', () => {
+    const d1 = registerCleanup('a', async () => {});
+    const d2 = registerCleanup('b', async () => {});
+    const d3 = registerCleanup('c', async () => {});
+    expect(_registeredCleanupCountForTests()).toBe(3);
+    d2();
+    expect(_registeredCleanupCountForTests()).toBe(2);
+    d1();
+    d3();
+    expect(_registeredCleanupCountForTests()).toBe(0);
+  });
+});
+
+describe('triggerCleanupAndExit', () => {
+  // Helper: monkey-patch process.exit to capture the code without actually exiting.
+  function patchExit(): { codes: number[]; restore: () => void } {
+    const codes: number[] = [];
+    const orig = process.exit;
+    (process as any).exit = (code?: number) => {
+      codes.push(code ?? 0);
+      // Don't actually exit — let the test continue.
+    };
+    return { codes, restore: () => { (process as any).exit = orig; } };
+  }
+
+  test('walks every registered callback', async () => {
+    const fired: string[] = [];
+    registerCleanup('a', async () => { fired.push('a'); });
+    registerCleanup('b', async () => { fired.push('b'); });
+    registerCleanup('c', async () => { fired.push('c'); });
+
+    const { codes, restore } = patchExit();
+    try {
+      await triggerCleanupAndExit(0);
+    } finally { restore(); }
+
+    expect(fired.sort()).toEqual(['a', 'b', 'c']);
+    expect(codes).toEqual([0]);
+  });
+
+  test('callback throw does not block other callbacks (Promise.allSettled)', async () => {
+    const fired: string[] = [];
+    registerCleanup('throwing', async () => { fired.push('throwing'); throw new Error('boom'); });
+    registerCleanup('quiet', async () => { fired.push('quiet'); });
+
+    const { codes, restore } = patchExit();
+    try {
+      await triggerCleanupAndExit(0);
+    } finally { restore(); }
+
+    expect(fired.sort()).toEqual(['quiet', 'throwing']);
+    expect(codes).toEqual([0]);
+  });
+
+  test('second concurrent trigger is NO-OP (idempotent)', async () => {
+    let fireCount = 0;
+    registerCleanup('once', async () => { fireCount++; await new Promise(r => setTimeout(r, 20)); });
+
+    const { codes, restore } = patchExit();
+    try {
+      const p1 = triggerCleanupAndExit(0);
+      const p2 = triggerCleanupAndExit(0); // should be no-op since cleanup is in flight
+      await Promise.all([p1, p2]);
+    } finally { restore(); }
+
+    expect(fireCount).toBe(1);
+    expect(codes).toHaveLength(2); // both calls reached process.exit
+  });
+
+  test('deadline honored — long-running callback does not block exit beyond 3s', async () => {
+    let blockerStarted = false;
+    let blockerFinished = false;
+    registerCleanup('blocker', async () => {
+      blockerStarted = true;
+      await new Promise(r => setTimeout(r, 5000)); // longer than 3s deadline
+      blockerFinished = true;
+    });
+
+    const { codes, restore } = patchExit();
+    const start = Date.now();
+    try {
+      await triggerCleanupAndExit(0);
+    } finally { restore(); }
+    const elapsed = Date.now() - start;
+
+    expect(blockerStarted).toBe(true);
+    expect(blockerFinished).toBe(false); // killed by deadline
+    expect(elapsed).toBeLessThan(4000); // exited well before blocker would have finished
+    expect(codes).toEqual([0]);
+  });
+
+  test('empty registry triggers exit immediately', async () => {
+    const { codes, restore } = patchExit();
+    try { await triggerCleanupAndExit(0); }
+    finally { restore(); }
+    expect(codes).toEqual([0]);
+  });
+
+  test('deregister-then-trigger: deregistered callback does not fire', async () => {
+    const fired: string[] = [];
+    const dereg = registerCleanup('dropped', async () => { fired.push('dropped'); });
+    registerCleanup('kept', async () => { fired.push('kept'); });
+    dereg();
+
+    const { codes, restore } = patchExit();
+    try { await triggerCleanupAndExit(0); }
+    finally { restore(); }
+
+    expect(fired).toEqual(['kept']);
+    expect(codes).toEqual([0]);
+  });
+});
+
+describe('installSignalHandlers', () => {
+  test('is idempotent (second call is NO-OP)', () => {
+    const beforeListeners = process.listenerCount('SIGTERM');
+    installSignalHandlers();
+    const afterFirstCall = process.listenerCount('SIGTERM');
+    installSignalHandlers();
+    const afterSecondCall = process.listenerCount('SIGTERM');
+    expect(afterFirstCall - beforeListeners).toBe(1);
+    expect(afterSecondCall).toBe(afterFirstCall); // no new listener
+  });
+
+  test('does NOT install a SIGINT handler (the existing AbortController owns SIGINT)', () => {
+    const sigintListeners = process.listenerCount('SIGINT');
+    _resetForTests();
+    installSignalHandlers();
+    // We didn't add a SIGINT listener — count is unchanged.
+    expect(process.listenerCount('SIGINT')).toBe(sigintListeners);
+  });
+
+  test('installs SIGTERM / SIGHUP / SIGPIPE handlers', () => {
+    _resetForTests();
+    const before = {
+      sigterm: process.listenerCount('SIGTERM'),
+      sighup: process.listenerCount('SIGHUP'),
+      sigpipe: process.listenerCount('SIGPIPE'),
+    };
+    installSignalHandlers();
+    expect(process.listenerCount('SIGTERM')).toBe(before.sigterm + 1);
+    expect(process.listenerCount('SIGHUP')).toBe(before.sighup + 1);
+    expect(process.listenerCount('SIGPIPE')).toBe(before.sigpipe + 1);
+  });
+});

test/sync-failures.test.ts

@@ -474,3 +474,117 @@ describe('formatCodeBreakdown — dual input shape', () => {
     expect(formatCodeBreakdown([])).toBe('');
   });
 });
+
+// v0.41.6.0 D2 — embedding error classifier patterns.
+// Verbatim provider error strings extracted from:
+//   src/core/ai/gateway.ts:973-988 (native-openai / native-google)
+//   src/core/ai/gateway.ts:995-997 (native-anthropic — no-touchpoint shape)
+//   src/core/ai/gateway.ts:250     (defaultResolveAuth — openai-compatible)
+// Each test pins a real-shaped message so a future provider-rename
+// (recipe.name change) will fail loudly here instead of silently
+// re-bucketing to UNKNOWN.
+describe('v0.41.6.0 D2 — embedding error classification', () => {
+  test('EMBEDDING_NO_CREDS matches native-openai verbatim throw', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('OpenAI embedding requires OPENAI_API_KEY.')).toBe('EMBEDDING_NO_CREDS');
+  });
+
+  test('EMBEDDING_NO_CREDS matches native-google verbatim throw', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode(
+      'Google embedding requires GOOGLE_GENERATIVE_AI_API_KEY.'
+    )).toBe('EMBEDDING_NO_CREDS');
+  });
+
+  test('EMBEDDING_NO_CREDS matches Voyage AI openai-compat shape', async () => {
+    // defaultResolveAuth template: "${recipe.name} embedding requires ${REQUIRED_ENV}."
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('Voyage AI embedding requires VOYAGE_API_KEY.')).toBe('EMBEDDING_NO_CREDS');
+  });
+
+  test('EMBEDDING_NO_CREDS matches ZeroEntropy openai-compat shape', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('ZeroEntropy embedding requires ZEROENTROPY_API_KEY.')).toBe('EMBEDDING_NO_CREDS');
+  });
+
+  test('EMBEDDING_NO_CREDS matches DeepSeek openai-compat shape', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('DeepSeek embedding requires DEEPSEEK_API_KEY.')).toBe('EMBEDDING_NO_CREDS');
+  });
+
+  test('EMBEDDING_NO_CREDS matches the literal token (back-compat)', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('EMBEDDING_NO_CREDS — VOYAGE_API_KEY missing')).toBe('EMBEDDING_NO_CREDS');
+  });
+
+  test('EMBEDDING_NO_TOUCHPOINT matches anthropic-as-embed-provider misconfig', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode(
+      'Anthropic has no embedding model. Use openai or google for embeddings.'
+    )).toBe('EMBEDDING_NO_TOUCHPOINT');
+  });
+
+  test('EMBEDDING_RATE_LIMIT matches HTTP 429 phrasing', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('Request failed with status 429: rate limit exceeded')).toBe('EMBEDDING_RATE_LIMIT');
+  });
+
+  test('EMBEDDING_RATE_LIMIT matches OpenAI "too many requests" phrasing', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('OpenAIRateLimitError: too many requests in 1m'))
+      .toBe('EMBEDDING_RATE_LIMIT');
+  });
+
+  test('EMBEDDING_QUOTA matches OpenAI insufficient_quota error', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode(
+      'You exceeded your current quota, please check your plan and billing details. error code: insufficient_quota'
+    )).toBe('EMBEDDING_QUOTA');
+  });
+
+  test('EMBEDDING_QUOTA matches Anthropic credit-balance message', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('Your credit balance is too low to continue'))
+      .toBe('EMBEDDING_QUOTA');
+  });
+
+  test('EMBEDDING_OVERSIZE matches OpenAI max-context-length error', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode(
+      "This model's maximum context length is 8192 tokens, however you requested 9001 tokens"
+    )).toBe('EMBEDDING_OVERSIZE');
+  });
+
+  test('EMBEDDING_OVERSIZE matches max_tokens shape', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('max_tokens exceeded for embedding input')).toBe('EMBEDDING_OVERSIZE');
+  });
+
+  test('EMBEDDING_OVERSIZE matches Voyage "input length exceeds" shape', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('input length exceeds maximum')).toBe('EMBEDDING_OVERSIZE');
+  });
+
+  // Negative regression cases — make sure new patterns don't steal existing patterns' messages.
+  test('FILE_TOO_LARGE still classifies correctly (not overridden by new patterns)', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('File too large: 5242881 bytes')).toBe('FILE_TOO_LARGE');
+  });
+
+  test('STATEMENT_TIMEOUT still classifies correctly', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('canceling statement due to statement timeout')).toBe('STATEMENT_TIMEOUT');
+  });
+
+  test('SLUG_MISMATCH still classifies correctly', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode(
+      'Frontmatter slug "x" does not match path-derived slug "y"'
+    )).toBe('SLUG_MISMATCH');
+  });
+
+  test('UNKNOWN still fires when no pattern matches', async () => {
+    const { classifyErrorCode } = await import('../src/core/sync.ts');
+    expect(classifyErrorCode('some random unmatched error message')).toBe('UNKNOWN');
+  });
+});

test/timeout.test.ts

@@ -0,0 +1,83 @@
+/**
+ * v0.41.6.0 D3 — withTimeout<T> helper.
+ *
+ * Pure-function tests. Verifies the Promise.race contract: resolves
+ * before deadline, rejects with OperationTimeoutError after, propagates
+ * underlying rejection, doesn't leak the underlying promise (timer is
+ * cleared on settle).
+ */
+import { describe, test, expect } from 'bun:test';
+import { withTimeout, OperationTimeoutError } from '../src/core/timeout.ts';
+
+const sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms));
+
+describe('withTimeout', () => {
+  test('resolves with the underlying value when the promise settles before deadline', async () => {
+    const result = await withTimeout(Promise.resolve(42), 1000, 'fast-resolve');
+    expect(result).toBe(42);
+  });
+
+  test('rejects with OperationTimeoutError when the promise exceeds the deadline', async () => {
+    const slow = new Promise(() => { /* never settles */ });
+    let caught: unknown;
+    try { await withTimeout(slow, 30, 'slow-resolve'); }
+    catch (e) { caught = e; }
+    expect(caught).toBeInstanceOf(OperationTimeoutError);
+    const e = caught as OperationTimeoutError;
+    expect(e.label).toBe('slow-resolve');
+    expect(e.ms).toBe(30);
+    expect(e.message).toContain('slow-resolve');
+    expect(e.message).toContain('30ms');
+  });
+
+  test('propagates underlying rejection (not OperationTimeoutError)', async () => {
+    const sentinel = new Error('real failure');
+    let caught: unknown;
+    try { await withTimeout(Promise.reject(sentinel), 1000, 'rejecting'); }
+    catch (e) { caught = e; }
+    expect(caught).toBe(sentinel);
+    expect(caught).not.toBeInstanceOf(OperationTimeoutError);
+  });
+
+  test('clears the timeout after settle (no zombie timer keeping the process alive)', async () => {
+    // If we don't clear the timer, the process would stay alive for the
+    // full deadline. With sleep(40) BELOW deadline(2000) and clear-on-settle,
+    // the test resolves immediately after await.
+    const start = Date.now();
+    const result = await withTimeout(sleep(40).then(() => 'ok'), 2000, 'short-with-long-deadline');
+    expect(result).toBe('ok');
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeLessThan(200); // far less than 2000ms deadline
+  });
+
+  test('Infinity deadline passes through unchanged', async () => {
+    const result = await withTimeout(Promise.resolve('passthrough'), Number.POSITIVE_INFINITY, 'no-deadline');
+    expect(result).toBe('passthrough');
+  });
+
+  test('NaN deadline passes through unchanged (treated as no-timeout)', async () => {
+    const result = await withTimeout(Promise.resolve('nan-passthrough'), Number.NaN, 'no-deadline');
+    expect(result).toBe('nan-passthrough');
+  });
+
+  test('zero deadline rejects immediately', async () => {
+    let caught: unknown;
+    try { await withTimeout(Promise.resolve('would-have-resolved'), 0, 'zero-deadline'); }
+    catch (e) { caught = e; }
+    expect(caught).toBeInstanceOf(OperationTimeoutError);
+  });
+
+  test('negative deadline rejects immediately', async () => {
+    let caught: unknown;
+    try { await withTimeout(Promise.resolve('would-have-resolved'), -100, 'neg-deadline'); }
+    catch (e) { caught = e; }
+    expect(caught).toBeInstanceOf(OperationTimeoutError);
+  });
+
+  test('OperationTimeoutError exposes label + ms fields for hint formatting', () => {
+    const e = new OperationTimeoutError('gbrain search', 30_000);
+    expect(e.label).toBe('gbrain search');
+    expect(e.ms).toBe(30_000);
+    expect(e.name).toBe('OperationTimeoutError');
+  });
+});