test(sync): pin the config-fingerprint gate wiring end-to-end (#2156)

The primitives (compute/read/write) were pinned but nothing exercised the
actual performSync gate: glob drift with git HEAD unchanged must break out
of the 'Already up to date' early return, force a full re-walk that imports
newly-included files, and settle back to up_to_date once re-stamped.
Deleting the configMismatch term from the gate now fails a committed test.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/guides/multi-source-brains.md

@@ -115,6 +115,7 @@ Full subcommand reference:
 
 ```
 gbrain sources add <id> --path <p> [--name <n>] [--federated|--no-federated] [--force]
+                                  [--include <glob>...] [--exclude <glob>...]
                                Register a source. id: [a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?
                                --path must be a git repo (or a subdirectory of one) — see
                                "The git requirement for --path sources" below. --force
@@ -131,6 +132,43 @@ gbrain sources federate <id>
 gbrain sources unfederate <id>
 ```
 
+## Filtering what gets synced (--include / --exclude)
+
+`--include` and `--exclude` on `gbrain sources add` accept repeatable glob
+patterns and are honored by every subsequent sync AND lint of the source.
+Common Obsidian vault setups need to exclude authoring scaffolding so it
+doesn't pollute search:
+
+```bash
+# Skip Templates/, Drafts/, and the smart-env sidecar; everything else syncs.
+gbrain sources add vault \
+  --path ~/Documents/vault --federated \
+  --exclude 'Templates/**' \
+  --exclude 'Drafts/**' \
+  --exclude '.smart-env/**'
+
+# Or: only sync the people/ and companies/ subtrees of a CRM vault.
+gbrain sources add crm \
+  --path ~/Documents/crm --no-federated \
+  --include 'people/**' \
+  --include 'companies/**'
+```
+
+Both persist into `sources.config.include_globs` / `exclude_globs` arrays.
+The filter runs `include` first, then `exclude`, so a path inside
+`people/**` is still rejected if it also matches `exclude_globs`. Globs use
+the same matcher as the rest of gbrain's sync classifier (`matchesAnyGlob`
+in `src/core/sync.ts`) and are matched against the source-root-relative
+path. Exclusion is conservative: it never deletes previously-imported pages.
+
+`gbrain sync --include <glob> --exclude <glob>` and
+`gbrain lint <dir> --include <glob> --exclude <glob>` take the same
+repeatable flags for one-off scope changes; for lint the persisted source
+globs are auto-applied when the lint target matches a source's `local_path`.
+Changing the persisted globs on an existing source triggers a full re-walk
+on the next sync (the source's config fingerprint invalidates the
+"already up to date" gate).
+
 ## The git requirement for --path sources
 
 Every `--path` source must be a git repository (or live inside one — a

src/cli.ts

@@ -466,11 +466,6 @@ async function main() {
     const result = JSON.parse(JSON.stringify(rawResult, bigintToStringReplacer));
     const output = formatResult(op.name, result);
     if (output) process.stdout.write(output);
-    // #1484 — invisible-miss hint: a bare query/search that hit zero results
-    // on a multi-source brain tells the user (stderr) which source it
-    // actually searched and how to widen the scope.
-    const hint = await sourceScopeHint(op.name, params, ctx.sourceId, engine, result);
-    if (hint) console.error(hint);
   } catch (e: unknown) {
     // v0.42.20.0 (codex D4): on error, set exitCode + return so the `finally`
     // STILL runs (drains every background-work sink + disconnects). A bare
@@ -842,44 +837,6 @@ async function makeContext(engine: BrainEngine, params: Record<string, unknown>)
   };
 }
 
-/**
- * #1484 — a bare `gbrain query`/`search` silently scopes to the resolved
- * source (usually 'default'); on a multi-source brain a zero-hit run looks
- * identical to "the brain doesn't know this" even when the answer lives in
- * another source. Returns a stderr hint when (a) the op is query/search,
- * (b) it returned zero results, (c) the caller did NOT scope explicitly
- * (--source / --source-id / --all-sources), and (d) the brain has >1
- * registered source. Best-effort: any lookup failure returns null.
- *
- * Exported for tests (same import-safety contract as formatResult).
- */
-export async function sourceScopeHint(
-  opName: string,
-  params: Record<string, unknown>,
-  sourceId: string,
-  engine: BrainEngine,
-  result: unknown,
-): Promise<string | null> {
-  if (opName !== 'query' && opName !== 'search') return null;
-  if (!Array.isArray(result) || result.length > 0) return null;
-  // Explicit scoping (flag tier) = user intent; don't second-guess it.
-  if (params.source || params.source_id || params.all_sources) return null;
-  if (sourceId === '__all__') return null;
-  try {
-    const rows = await engine.executeRaw<{ n: number }>(
-      `SELECT count(*)::int AS n FROM sources`,
-    );
-    const n = Number(rows[0]?.n ?? 0);
-    if (n <= 1) return null;
-    return (
-      `Hint: this brain has ${n} sources; you searched only "${sourceId}". ` +
-      `Retry with --source-id __all__ (all sources) or --source-id <id>.`
-    );
-  } catch {
-    return null; // hint is best-effort; never fail the query over it
-  }
-}
-
 // Exported for tests (same import-safety contract as cliAliases/printOpHelp).
 export function formatResult(opName: string, result: unknown): string {
   switch (opName) {

src/commands/import.ts

@@ -53,6 +53,13 @@ export async function runImport(
     strategy?: SyncStrategy;
     sourceId?: string;
     managedBookmark?: boolean;
+    /**
+     * #2156: allow-list glob patterns — only dir-relative paths matching at
+     * least one pattern are imported. Applied BEFORE `exclude`. Threaded by
+     * performFullSync from `gbrain sync --include` / the source row's
+     * persisted `config.include_globs`.
+     */
+    include?: string[];
     /**
      * #753/#774: glob patterns to exclude from the import (same semantics as
      * `isSyncable`'s `exclude` — matched against the dir-relative path).
@@ -215,6 +222,10 @@ export async function runImport(
   );
   const fileTypeLabel = strategy === 'code' ? 'code'
     : strategy === 'auto' ? 'syncable' : 'markdown';
+  // #2156: apply --include allow-list globs first (threaded by performFullSync).
+  if (opts.include && opts.include.length > 0) {
+    allFiles = allFiles.filter(abs => matchesAnyGlob(relative(dir, abs), opts.include));
+  }
   // #753/#774: apply --exclude glob patterns (threaded by performFullSync).
   if (opts.exclude && opts.exclude.length > 0) {
     const beforeExclude = allFiles.length;

src/commands/lint.ts

@@ -17,7 +17,7 @@
  */
 
 import { readFileSync, writeFileSync, readdirSync, statSync, lstatSync, existsSync } from 'fs';
-import { join, relative } from 'path';
+import { join, relative, resolve } from 'path';
 import { isAborted } from '../core/abort-check.ts';
 import { parseMarkdown, type ParseValidationCode } from '../core/markdown.ts';
 import {
@@ -26,7 +26,9 @@ import {
   DEFAULT_BYTES_WARN,
 } from '../core/content-sanity.ts';
 import { loadOperatorLiterals } from '../core/content-sanity-literals.ts';
-import { loadConfig, loadConfigWithEngine, gbrainPath } from '../core/config.ts';
+import { loadConfig, loadConfigWithEngine, toEngineConfig, gbrainPath } from '../core/config.ts';
+import { matchesAnyGlob } from '../core/sync.ts';
+import { parseGlobList } from './sync.ts';
 import type { BrainEngine } from '../core/engine.ts';
 
 export interface LintIssue {
@@ -378,21 +380,89 @@ async function resolveLintContentSanity(
   };
 }
 
-/** Collect markdown files from a directory */
-function collectPages(dir: string): string[] {
+/** Collect markdown files from a directory.
+ *
+ *  When `opts.include` or `opts.exclude` are set, each candidate `.md` path's
+ *  POSIX-style relative path (relative to `dir`) is matched against the same
+ *  glob semantics sync uses (`matchesAnyGlob`). `include` allow-lists;
+ *  `exclude` deny-lists. Empty or undefined arrays leave the filter
+ *  unengaged. Symmetric with `isSyncable` in `src/core/sync.ts` so a
+ *  source-config `exclude_globs` honored by `gbrain sync` is also honored
+ *  by `gbrain lint` against the same dir.
+ */
+function collectPages(
+  dir: string,
+  opts: { include?: string[]; exclude?: string[] } = {},
+): string[] {
+  const { include, exclude } = opts;
+  const haveInclude = !!(include && include.length > 0);
+  const haveExclude = !!(exclude && exclude.length > 0);
   const pages: string[] = [];
   function walk(d: string) {
     for (const entry of readdirSync(d)) {
       if (entry.startsWith('.') || entry.startsWith('_')) continue;
       const full = join(d, entry);
       if (lstatSync(full).isDirectory()) walk(full);
-      else if (entry.endsWith('.md')) pages.push(full);
+      else if (entry.endsWith('.md')) {
+        if (haveInclude || haveExclude) {
+          // Match against the path RELATIVE to `dir` (the source root),
+          // normalized to POSIX separators by matchesAnyGlob. A
+          // source-config glob like `Resources/veriff/**` is anchored at
+          // the source root; matching against the absolute path would
+          // require the user to anchor on their `$HOME` or repo prefix,
+          // which is brittle.
+          const rel = relative(dir, full);
+          if (haveInclude && !matchesAnyGlob(rel, include)) continue;
+          if (haveExclude && matchesAnyGlob(rel, exclude)) continue;
+        }
+        pages.push(full);
+      }
     }
   }
   walk(dir);
   return pages.sort();
 }
 
+/** Look up the source row whose `local_path` resolves to the same absolute
+ *  directory as `target`, and return its persisted `include_globs` /
+ *  `exclude_globs` as parsed string arrays. Returns an empty object when no
+ *  matching source exists, when the row has no globs configured, or when the
+ *  lookup throws (best-effort — auto-resolution must never break standalone
+ *  lint on brains without a sources table).
+ *
+ *  Mirrors how `syncOneSource` lifts the same fields off `src.config` before
+ *  threading them into `SyncOpts.include` / `SyncOpts.exclude`.
+ */
+async function resolveSourceGlobsForTarget(
+  engine: BrainEngine,
+  target: string,
+): Promise<{ include?: string[]; exclude?: string[] }> {
+  try {
+    const absTarget = resolve(target);
+    const rows = await engine.executeRaw<{ config: unknown }>(
+      `SELECT config FROM sources
+        WHERE archived IS NOT TRUE
+          AND local_path IS NOT NULL
+          AND local_path = $1
+        LIMIT 1`,
+      [absTarget],
+    );
+    if (rows.length === 0) return {};
+    const cfg = (rows[0].config && typeof rows[0].config === 'object')
+      ? rows[0].config as Record<string, unknown>
+      : {};
+    return {
+      include: parseGlobList(cfg.include_globs),
+      exclude: parseGlobList(cfg.exclude_globs),
+    };
+  } catch {
+    // Engine not connected, sources table missing on a fresh brain, RLS
+    // denial in an unusual scope — all best-effort. Lint proceeds without
+    // filtering rather than fail-closed.
+    return {};
+  }
+}
+
 export interface LintOpts {
   target: string;
   fix?: boolean;
@@ -414,6 +484,22 @@ export interface LintOpts {
    * yields + checks this every 200 pages.
    */
   signal?: AbortSignal;
+  /**
+   * Glob filters threaded into the file walker. When set, paths relative to
+   * `target` are matched against the patterns using the same semantics as
+   * `gbrain sync` (`matchesAnyGlob` in `src/core/sync.ts`). `include`
+   * allow-lists; `exclude` deny-lists; both unset == no filter.
+   *
+   * When BOTH are unset AND `engine` is provided, `runLintCore` attempts to
+   * auto-resolve them from the `sources` row whose `local_path` matches
+   * `target` — symmetric with `syncOneSource`, so a user who has run
+   * `gbrain sources add --exclude 'Resources/veriff/**'` sees the same
+   * exclusion applied to `gbrain lint <same-dir>` and to the cycle.lint
+   * phase without restating it on every invocation. Explicit caller-supplied
+   * arrays always win over the source-row lift.
+   */
+  include?: string[];
+  exclude?: string[];
 }
 
 export interface LintResult {
@@ -440,7 +526,21 @@ export async function runLintCore(opts: LintOpts): Promise<LintResult> {
   }
 
   const isSingleFile = statSync(opts.target).isFile();
-  const pages = isSingleFile ? [opts.target] : collectPages(opts.target);
+
+  // Resolve glob filters. Explicit caller-supplied include/exclude win;
+  // otherwise lift from `sources.config.{include,exclude}_globs` when an
+  // engine is available and the target matches a known source's local_path.
+  // Single-file lints skip the resolve entirely — globs are a directory
+  // walk concern.
+  let include = opts.include;
+  let exclude = opts.exclude;
+  const haveExplicit = (include && include.length > 0) || (exclude && exclude.length > 0);
+  if (!isSingleFile && !haveExplicit && opts.engine) {
+    const resolved = await resolveSourceGlobsForTarget(opts.engine, opts.target);
+    include = resolved.include;
+    exclude = resolved.exclude;
+  }
+  const pages = isSingleFile ? [opts.target] : collectPages(opts.target, { include, exclude });
 
   // Resolve content-sanity config once for this lint run (D1: lift DB
   // config when reachable). Caller can pre-pass via opts.contentSanity
@@ -491,14 +591,27 @@ export async function runLintCore(opts: LintOpts): Promise<LintResult> {
 }
 
 export async function runLint(args: string[]) {
-  const target = args.find(a => !a.startsWith('--'));
+  const target = args.find(a => !a.startsWith('--') && !args[args.indexOf(a) - 1]?.match(/^--(include|exclude)$/));
   const doFix = args.includes('--fix');
   const dryRun = args.includes('--dry-run');
 
+  // Parse repeatable `--include <glob>` and `--exclude <glob>` flags.
+  // Symmetric with `gbrain sources add --include / --exclude` from PR #2157;
+  // explicit flags here override the source-config lift performed below for
+  // dir-mode lints.
+  const cliInclude: string[] = [];
+  const cliExclude: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--include' && i + 1 < args.length) cliInclude.push(args[++i]);
+    else if (args[i] === '--exclude' && i + 1 < args.length) cliExclude.push(args[++i]);
+  }
+
   if (!target) {
-    console.error('Usage: gbrain lint <dir|file.md> [--fix] [--dry-run]');
-    console.error('  --fix      Auto-fix fixable issues (LLM preambles, code fences)');
-    console.error('  --dry-run  Preview fixes without writing');
+    console.error('Usage: gbrain lint <dir|file.md> [--fix] [--dry-run] [--include <glob>]... [--exclude <glob>]...');
+    console.error('  --fix              Auto-fix fixable issues (LLM preambles, code fences)');
+    console.error('  --dry-run          Preview fixes without writing');
+    console.error('  --include <glob>   Repeatable; only lint paths matching at least one pattern');
+    console.error('  --exclude <glob>   Repeatable; skip paths matching any pattern (applied after --include)');
     process.exit(1);
   }
 
@@ -510,7 +623,44 @@ export async function runLint(args: string[]) {
   // Single file or directory — print human detail as we go, then rely on
   // Core for the aggregate numbers at the end.
   const isSingleFile = statSync(target).isFile();
-  const pages = isSingleFile ? [target] : collectPages(target);
+
+  // Resolve glob filters for directory lints. Explicit CLI flags win;
+  // otherwise lift from `sources.config.{include,exclude}_globs` matching
+  // `target`. Connect a transient engine for the lookup only when (a) no
+  // explicit flags were passed AND (b) file/env config suggests an engine is
+  // available — mirrors the connect-disconnect pattern in
+  // `resolveLintContentSanity` (issue #1678: standalone CLI never shares the
+  // db.ts singleton, so create + dispose here is safe).
+  let runInclude: string[] | undefined = cliInclude.length > 0 ? cliInclude : undefined;
+  let runExclude: string[] | undefined = cliExclude.length > 0 ? cliExclude : undefined;
+  if (!isSingleFile && runInclude === undefined && runExclude === undefined) {
+    const base = loadConfig();
+    if (base?.database_url || base?.database_path) {
+      try {
+        const { createEngine } = await import('../core/engine-factory.ts');
+        const { connectWithRetry } = await import('../core/db.ts');
+        const engineCfg = toEngineConfig(base);
+        const engine = await createEngine(engineCfg);
+        try {
+          // Use the same connect path the rest of the CLI uses
+          // (`connectEngine` in cli.ts). `engine.connect({})` with empty
+          // opts drops the URL — confirmed by direct probe. `noRetry: true`
+          // keeps the standalone lint snappy (no retry tax when the brain
+          // happens to be unreachable; auto-resolve degrades to no-filter).
+          await connectWithRetry(engine, engineCfg, { noRetry: true });
+          const lifted = await resolveSourceGlobsForTarget(engine, target);
+          runInclude = lifted.include;
+          runExclude = lifted.exclude;
+        } finally {
+          await engine.disconnect().catch(() => { /* best-effort */ });
+        }
+      } catch {
+        // best-effort; fall through to no-filter
+      }
+    }
+  }
+
+  const pages = isSingleFile ? [target] : collectPages(target, { include: runInclude, exclude: runExclude });
 
   // Progress on stderr. Stdout keeps the per-issue human output it always had.
   const { createProgress } = await import('../core/progress.ts');
@@ -557,7 +707,17 @@ export async function runLint(args: string[]) {
   // produces canonical numbers for the summary line).
   // Pass contentSanity through so runLintCore skips its own resolve
   // (we already resolved once for the human-detail loop above).
-  const result = await runLintCore({ target, fix: doFix, dryRun, contentSanity });
+  // Pass include/exclude so the aggregate scope matches the human-detail
+  // walk above — otherwise the summary line reports the unfiltered count
+  // even though the per-page details were already filtered.
+  const result = await runLintCore({
+    target,
+    fix: doFix,
+    dryRun,
+    contentSanity,
+    include: runInclude,
+    exclude: runExclude,
+  });
   console.log(`\n${result.pages_scanned} pages scanned. ${result.total_issues} issue(s) in ${result.pages_with_issues} page(s).`);
   if (doFix) {
     console.log(`${dryRun ? '(dry run) ' : ''}${result.total_fixed} auto-fixed.`);

src/commands/sources.ts

@@ -122,7 +122,8 @@ async function runAdd(engine: BrainEngine, args: string[]): Promise<void> {
   if (!id) {
     console.error(
       'Usage: gbrain sources add <id> [--path <path> | --url <https-url>] ' +
-        '[--name <display>] [--federated|--no-federated] [--clone-dir <path>] [--force]',
+        '[--name <display>] [--federated|--no-federated] [--clone-dir <path>] [--force] ' +
+        '[--include <glob>...] [--exclude <glob>...]',
     );
     process.exit(2);
   }
@@ -135,6 +136,12 @@ async function runAdd(engine: BrainEngine, args: string[]): Promise<void> {
   let patFile: string | undefined;
   let noHarden = false;
   let force = false;
+  // Repeatable. `--include 'people/**' --include 'companies/**'` accumulates.
+  // Persisted into sources.config.include_globs / .exclude_globs and read at
+  // sync time by commands/sync.ts so `Templates/`, `.smart-env/`, `Drafts/`
+  // and other vault scaffolding can be skipped without renaming directories.
+  const includeGlobs: string[] = [];
+  const excludeGlobs: string[] = [];
 
   for (let i = 1; i < args.length; i++) {
     const a = args[i];
@@ -147,6 +154,24 @@ async function runAdd(engine: BrainEngine, args: string[]): Promise<void> {
     if (a === '--pat-file') { patFile = args[++i]; continue; }
     if (a === '--no-harden') { noHarden = true; continue; }
     if (a === '--force') { force = true; continue; }
+    if (a === '--include') {
+      const v = args[++i];
+      if (!v || v.startsWith('--')) {
+        console.error('Error: --include requires a glob argument (e.g. --include "people/**")');
+        process.exit(2);
+      }
+      includeGlobs.push(v);
+      continue;
+    }
+    if (a === '--exclude') {
+      const v = args[++i];
+      if (!v || v.startsWith('--')) {
+        console.error('Error: --exclude requires a glob argument (e.g. --exclude "Templates/**")');
+        process.exit(2);
+      }
+      excludeGlobs.push(v);
+      continue;
+    }
     console.error(`Unknown flag: ${a}`);
     process.exit(2);
   }
@@ -167,6 +192,8 @@ async function runAdd(engine: BrainEngine, args: string[]): Promise<void> {
     federated,
     cloneDir,
     force,
+    includeGlobs: includeGlobs.length > 0 ? includeGlobs : undefined,
+    excludeGlobs: excludeGlobs.length > 0 ? excludeGlobs : undefined,
   });
 
   // Topology A discovery: if the just-added source carries a brain-resident
@@ -190,6 +217,12 @@ async function runAdd(engine: BrainEngine, args: string[]): Promise<void> {
   console.log(
     `  federated: ${fed}${fed ? ' — appears in cross-source default search' : ' — only searched when explicitly named via --source'}`,
   );
+  if (includeGlobs.length > 0) {
+    console.log(`  include globs: ${includeGlobs.join(', ')}`);
+  }
+  if (excludeGlobs.length > 0) {
+    console.log(`  exclude globs: ${excludeGlobs.join(', ')}`);
+  }
 
   // v0.42.44 — auto-harden managed clones for git durability the moment a brain
   // repo is added with a PAT. Best-effort: NEVER fail `add` if hardening fails.

src/commands/sync.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, writeFileSync, statSync, realpathSync } from 'fs';
 import { execFileSync } from 'child_process';
 import { join, relative } from 'path';
+import { createHash } from 'crypto';
 import type { BrainEngine } from '../core/engine.ts';
 import { DELETE_BATCH_SIZE } from '../core/engine-constants.ts';
 import { importFile } from '../core/import-file.ts';
@@ -756,12 +757,23 @@ export interface SyncOpts {
    * are rejected before any git op runs.
    */
   srcSubpath?: string;
+  /**
+   * #2156 — glob patterns files must match to be synced (allow-list).
+   * Populated from the source row's persisted `config.include_globs`
+   * (set via `gbrain sources add --include <glob>`) or the repeatable
+   * `--include` CLI flag. Matched against the scope-relative path, same
+   * anchoring as `exclude`. `exclude` is applied after `include`: a path
+   * matching an include pattern is still rejected if it also matches an
+   * exclude pattern. Empty arrays are the same as undefined (no filter).
+   */
+  include?: string[];
   /**
    * #753/#774 — glob patterns for files to exclude from sync (repeatable
-   * `--exclude` on the CLI). Matched against the scope-relative path in both
-   * the full-sync and incremental paths. Excluded files are never imported;
-   * exclusion does NOT delete previously-imported pages (conservative,
-   * matching the #1433 metafile posture).
+   * `--exclude` on the CLI; #2156: also populated from the source row's
+   * persisted `config.exclude_globs`). Matched against the scope-relative
+   * path in both the full-sync and incremental paths. Excluded files are
+   * never imported; exclusion does NOT delete previously-imported pages
+   * (conservative, matching the #1433 metafile posture).
    */
   exclude?: string[];
   /**
@@ -1153,6 +1165,29 @@ function unique<T>(items: T[]): T[] {
 // `src/core/sync-delta.ts` (re-imported below) so the inline cost estimator
 // prices detached sources through the same code the executor imports them with.
 
+/**
+ * Defensive parse for the JSONB-loaded `config.include_globs` / `config.exclude_globs`
+ * arrays read off the sources row. The column is a free-form JSONB and could
+ * contain anything — coerce to a string-only array, drop empties, and return
+ * undefined when the result has no useful entries so the caller can decide
+ * not to engage glob-filtering at all.
+ */
+export function parseGlobList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const globs = value.filter((v): v is string => typeof v === 'string' && v.length > 0);
+  return globs.length > 0 ? globs : undefined;
+}
+
+/**
+ * Union of CLI-supplied glob patterns (one-off, this invocation) and the
+ * source row's persisted config globs (every sync). Deduped; undefined when
+ * neither side has entries so `SyncOpts` stays unset and no filter engages.
+ */
+export function mergeGlobs(cli: string[], persisted: string[] | undefined): string[] | undefined {
+  const merged = [...new Set([...cli, ...(persisted ?? [])])];
+  return merged.length > 0 ? merged : undefined;
+}
+
 // v0.18.0 Step 5: source-scoped sync state helpers. When opts.sourceId
 // is set, read/write the per-source row instead of the global config
 // keys. These wrappers centralize the branch so every read/write site
@@ -1315,6 +1350,125 @@ async function writeChunkerVersion(
   );
 }
 
+/**
+ * #2157 follow-on: detect when sources.config has shifted in a way that
+ * affects which paths the walker will include this run. The "Already up
+ * to date" gate at performSync's git-HEAD equality check honored chunker
+ * version match but ignored config drift — a user who changes
+ * `sources.config.exclude_globs` mid-life got "Already up to date" on
+ * the next sync because git HEAD was unchanged, with no observable
+ * effect until `gbrain sync --full`.
+ *
+ * Fingerprint covers exactly the walk-affecting fields that flow from
+ * `sources.config` into `SyncOpts` at the syncOneSource call site:
+ * `strategy`, `include_globs`, `exclude_globs`. CLI-supplied --include
+ * / --exclude overrides do NOT participate — they are one-off scope
+ * changes, not source state, and shouldn't invalidate the row's
+ * checkpoint. (A user running `gbrain sync --exclude X` on a row whose
+ * stored config has no X is intentionally narrowing this one pass; on
+ * the next no-flags sync, the row config governs again.)
+ *
+ * Array order is normalized (alphabetical, post-defensive-parse) so
+ * `["a/**", "b/**"]` and `["b/**", "a/**"]` fingerprint identically.
+ * `parseGlobList` shares the same defensive coercion as the call site
+ * that builds SyncOpts, so hand-edited or pre-normalization rows
+ * fingerprint to the same shape the walker actually sees.
+ */
+export function computeSourceConfigFingerprint(rawConfig: unknown): string {
+  const cfg = (rawConfig || {}) as {
+    strategy?: unknown;
+    include_globs?: unknown;
+    exclude_globs?: unknown;
+  };
+  const canonical = JSON.stringify({
+    strategy: typeof cfg.strategy === 'string' ? cfg.strategy : null,
+    include_globs: (parseGlobList(cfg.include_globs) ?? []).slice().sort(),
+    exclude_globs: (parseGlobList(cfg.exclude_globs) ?? []).slice().sort(),
+  });
+  return createHash('sha256').update(canonical).digest('hex');
+}
+
+/**
+ * Read the per-source fingerprint stamp. NULL on pre-migration rows or
+ * sources that have never been synced — the gate treats NULL as
+ * "fingerprint unknown" and skips the invalidation check so first-time
+ * post-upgrade syncs don't spuriously force-full.
+ */
+export async function readConfigFingerprint(
+  engine: BrainEngine,
+  sourceId: string | undefined,
+): Promise<string | null> {
+  if (!sourceId) return null;
+  const rows = await engine.executeRaw<{ config_fingerprint: string | null }>(
+    `SELECT config_fingerprint FROM sources WHERE id = $1`,
+    [sourceId],
+  );
+  return rows[0]?.config_fingerprint ?? null;
+}
+
+export async function writeConfigFingerprint(
+  engine: BrainEngine,
+  sourceId: string | undefined,
+  fingerprint: string,
+): Promise<void> {
+  if (!sourceId) return;
+  await engine.executeRaw(
+    `UPDATE sources SET config_fingerprint = $1 WHERE id = $2`,
+    [fingerprint, sourceId],
+  );
+}
+
+/**
+ * Read the raw `sources.config` value for the named source. Returns an
+ * empty object for missing or never-configured rows. The reader is
+ * defensive about legacy double-encoded JSONB rows (`{"federated":true}`
+ * stored as a JSON string scalar, the #2339 class) — the engine's
+ * `r.config` may arrive as either a string or an object, and both are
+ * normalized to an object before the fingerprint computation walks the
+ * keys.
+ */
+async function readSourceConfig(
+  engine: BrainEngine,
+  sourceId: string | undefined,
+): Promise<unknown> {
+  if (!sourceId) return {};
+  const rows = await engine.executeRaw<{ config: unknown }>(
+    `SELECT config FROM sources WHERE id = $1`,
+    [sourceId],
+  );
+  const raw = rows[0]?.config;
+  if (raw === null || raw === undefined) return {};
+  if (typeof raw === 'string') {
+    try { return JSON.parse(raw); } catch { return {}; }
+  }
+  return raw;
+}
+
+/**
+ * Read-hash-stamp wrapper for sync-completion sites outside the gate's
+ * scope (e.g. `performFullSync`'s `advanceFull` closure, which doesn't
+ * see `performSync`'s cached `currentConfigFp` because it's a separate
+ * function). Reads the row's current config and stamps a fresh
+ * fingerprint.
+ *
+ * Race note: if `sources.config` was mutated between the gate's read
+ * and this stamp, the freshly-read value wins. The walker still used
+ * the gate-time effective globs (already captured into `opts.include` /
+ * `opts.exclude` upstream), so the stamp can drift from what was
+ * actually walked. In practice mid-sync mutations are rare and the
+ * NEXT sync will re-evaluate against the latest config anyway, so the
+ * minor staleness is acceptable and avoids threading the gate-time
+ * fingerprint through every helper signature.
+ */
+async function stampSourceConfigFingerprint(
+  engine: BrainEngine,
+  sourceId: string | undefined,
+): Promise<void> {
+  if (!sourceId) return;
+  const cfg = await readSourceConfig(engine, sourceId);
+  await writeConfigFingerprint(engine, sourceId, computeSourceConfigFingerprint(cfg));
+}
+
 /**
  * v0.40 Federated Sync v2: `gbrain sync trigger --source <id> [--priority high|normal|low]`
  *
@@ -2163,7 +2317,25 @@ async function performSyncInner(engine: BrainEngine, opts: SyncOpts): Promise<Sy
       detachedWorkingTreeManifest.deleted.length > 0 ||
       detachedWorkingTreeManifest.renamed.length > 0);
 
-  if (lastCommit === headCommit && !versionMismatch && !versionNeverSet && !hasDetachedWorkingTreeChanges) {
+  // #2157 follow-on: parallel gate for sources.config drift. Without
+  // this, changing `sources.config.exclude_globs` (or include_globs /
+  // strategy) on a synced source had no observable effect on the next
+  // sync because git HEAD was unchanged — the "Already up to date"
+  // branch below returned without re-walking. Mismatch path mirrors the
+  // chunker_version gate exactly so both kinds of drift route through
+  // the same `performFullSync` recovery.
+  //
+  // NULL stored fingerprint is "never stamped" (pre-v125 brain OR fresh
+  // source whose first sync hasn't completed yet). Treated as
+  // pass-through in the up-to-date check — first post-upgrade sync
+  // stamps the column quietly so subsequent passes have a baseline.
+  const storedConfigFp = await readConfigFingerprint(engine, opts.sourceId);
+  const currentSourceConfig = await readSourceConfig(engine, opts.sourceId);
+  const currentConfigFp = computeSourceConfigFingerprint(currentSourceConfig);
+  const configMismatch = storedConfigFp !== null && storedConfigFp !== currentConfigFp;
+  const configNeverStamped = storedConfigFp === null && opts.sourceId !== undefined;
+
+  if (lastCommit === headCommit && !versionMismatch && !versionNeverSet && !hasDetachedWorkingTreeChanges && !configMismatch) {
     // v0.42.52.0 (PR #22xx): bump last_sync_at as a heartbeat on every successful
     // 0-changes sync. D4 invariant ("never advance last_commit on partial") is
     // preserved: last_sync_at is a monitoring signal (doctor sync_freshness
@@ -2176,6 +2348,14 @@ async function performSyncInner(engine: BrainEngine, opts: SyncOpts): Promise<Sy
         [opts.sourceId],
       );
     }
+    // First post-upgrade sync on a pre-v125 brain lands here with
+    // configNeverStamped=true; stamp the fingerprint so the gate has a
+    // baseline for the NEXT pass. A spurious re-walk on the upgrade
+    // pass would surprise users; quietly establishing the baseline does
+    // not.
+    if (configNeverStamped) {
+      await writeConfigFingerprint(engine, opts.sourceId, currentConfigFp);
+    }
     return {
       status: 'up_to_date',
       fromCommit: lastCommit,
@@ -2187,13 +2367,21 @@ async function performSyncInner(engine: BrainEngine, opts: SyncOpts): Promise<Sy
     };
   }
 
-  if ((versionMismatch || versionNeverSet) && lastCommit === headCommit) {
+  if ((versionMismatch || versionNeverSet || configMismatch) && lastCommit === headCommit) {
+    const reasons: string[] = [];
+    if (versionMismatch || versionNeverSet) {
+      reasons.push(`chunker_version=${storedVersion ?? 'unset'}→${currentVersion}`);
+    }
+    if (configMismatch) {
+      reasons.push(`config_fingerprint=${storedConfigFp?.slice(0, 8)}→${currentConfigFp.slice(0, 8)}`);
+    }
     slog(
-      `[sync] chunker_version gate: stored=${storedVersion ?? 'unset'}, current=${currentVersion}. ` +
-      `Forcing full re-chunk pass (git HEAD unchanged but pipeline version advanced).`,
+      `[sync] full re-walk forced (${reasons.join(', ')}): ` +
+      `git HEAD unchanged but a walk-affecting setting advanced.`,
     );
     const result = await performFullSync(engine, fullSyncRoots, headCommit, opts);
     await writeChunkerVersion(engine, opts.sourceId, currentVersion);
+    await writeConfigFingerprint(engine, opts.sourceId, currentConfigFp);
     return result;
   }
 
@@ -2237,8 +2425,16 @@ async function performSyncInner(engine: BrainEngine, opts: SyncOpts): Promise<Sy
     scoped && p.startsWith(syncScopeRelPath + '/') ? p.slice(syncScopeRelPath.length + 1) : p;
   const excluded = (p: string): boolean =>
     opts.exclude !== undefined && opts.exclude.length > 0 && matchesAnyGlob(scopeRel(p), opts.exclude);
+  // #2156: include globs are an allow-list, same scope-relative anchoring as
+  // exclude. Populated from the source row's persisted config.include_globs
+  // (or CLI --include). Deliberately NOT threaded into syncOpts/isSyncable:
+  // the unsyncable-cleanup loop below deletes pages for non-metafile
+  // classifications, and glob filtering must stay conservative (never delete
+  // previously-imported pages — the documented #1433 posture for --exclude).
+  const included = (p: string): boolean =>
+    opts.include === undefined || opts.include.length === 0 || matchesAnyGlob(scopeRel(p), opts.include);
 
-  // Filter to syncable files (strategy-aware + scope-aware + exclude-aware)
+  // Filter to syncable files (strategy-aware + scope-aware + glob-aware)
   const syncOpts = opts.strategy ? { strategy: opts.strategy } : undefined;
   // #1970 (F-C): a rename whose DESTINATION is unsyncable drops out of BOTH
   // `renamed` (only `r.to` is kept below) AND `deleted` (git emits it as `R`,
@@ -2252,13 +2448,13 @@ async function performSyncInner(engine: BrainEngine, opts: SyncOpts): Promise<Sy
       !(inScope(r.to) && isSyncable(r.to, syncOpts)))
     .map(r => r.from);
   const filtered: SyncManifest = {
-    added: manifest.added.filter(p => inScope(p) && !excluded(p) && isSyncable(p, syncOpts)),
-    modified: manifest.modified.filter(p => inScope(p) && !excluded(p) && isSyncable(p, syncOpts)),
+    added: manifest.added.filter(p => inScope(p) && included(p) && !excluded(p) && isSyncable(p, syncOpts)),
+    modified: manifest.modified.filter(p => inScope(p) && included(p) && !excluded(p) && isSyncable(p, syncOpts)),
     deleted: unique([
       ...manifest.deleted.filter(p => inScope(p) && isSyncable(p, syncOpts)),
       ...renamedToUnsyncable,
     ]),
-    renamed: manifest.renamed.filter(r => inScope(r.to) && !excluded(r.to) && isSyncable(r.to, syncOpts)),
+    renamed: manifest.renamed.filter(r => inScope(r.to) && included(r.to) && !excluded(r.to) && isSyncable(r.to, syncOpts)),
   };
 
   // NAV-4: warn when --exclude filtered out every candidate change — almost
@@ -2355,6 +2551,7 @@ async function performSyncInner(engine: BrainEngine, opts: SyncOpts): Promise<Sy
     await writeSyncAnchor(engine, opts.sourceId, 'last_commit', pin, commitTimeMs(gitContextRoot, pin));
     await engine.setConfig('sync.last_run', new Date().toISOString());
     await writeChunkerVersion(engine, opts.sourceId, String(CHUNKER_VERSION));
+    await writeConfigFingerprint(engine, opts.sourceId, currentConfigFp);
     await clearOpCheckpoint(engine, ckpt.paths);
     await clearOpCheckpoint(engine, ckpt.target);
     return {
@@ -3179,6 +3376,7 @@ async function performSyncInner(engine: BrainEngine, opts: SyncOpts): Promise<Sy
     await engine.setConfig('sync.last_run', new Date().toISOString());
     await writeSyncAnchor(engine, opts.sourceId, 'repo_path', anchorPath);
     await writeChunkerVersion(engine, opts.sourceId, String(CHUNKER_VERSION));
+    await writeConfigFingerprint(engine, opts.sourceId, currentConfigFp);
     await clearOpCheckpoint(engine, ckpt.paths);
     await clearOpCheckpoint(engine, ckpt.target);
   };
@@ -3430,6 +3628,9 @@ async function performFullSync(
   // files were waiting.
   if (opts.dryRun) {
     let allFiles = collectSyncableFiles(syncScopeRoot, { strategy: opts.strategy ?? 'markdown' });
+    if (opts.include && opts.include.length > 0) {
+      allFiles = allFiles.filter(abs => matchesAnyGlob(relative(syncScopeRoot, abs), opts.include));
+    }
     if (opts.exclude && opts.exclude.length > 0) {
       allFiles = allFiles.filter(abs => !matchesAnyGlob(relative(syncScopeRoot, abs), opts.exclude));
     }
@@ -3475,6 +3676,7 @@ async function performFullSync(
     commit: headCommit,
     strategy: opts.strategy,
     sourceId: opts.sourceId,
+    include: opts.include,
     exclude: opts.exclude,
     slugRoot,
     // issue #1939: performFullSync owns the failure ledger + bookmark via the
@@ -3504,6 +3706,7 @@ async function performFullSync(
     await engine.setConfig('sync.last_run', new Date().toISOString());
     await writeSyncAnchor(engine, opts.sourceId, 'repo_path', anchorPath);
     await writeChunkerVersion(engine, opts.sourceId, String(CHUNKER_VERSION));
+    await stampSourceConfigFingerprint(engine, opts.sourceId);
   };
 
   const fullGate = await applySyncFailureGate({
@@ -3967,8 +4170,12 @@ Options:
                        run at the repo root; imports are scoped to the subdir
                        and slugs stay root-relative (wiki/page1). Passing the
                        subdirectory directly as --repo also works.
+  --include <glob>     Only sync files matching at least one glob (repeatable;
+                       matched against the scope-relative path). Merged with
+                       the source's persisted config.include_globs.
   --exclude <glob>     Exclude files matching the glob from sync (repeatable;
-                       matched against the scope-relative path).
+                       matched against the scope-relative path; applied after
+                       --include). Merged with config.exclude_globs.
   --dry-run            Show what would be synced without writing.
   --skip-failed        Acknowledge previously-recorded sync failures so
                        the bookmark can advance past unparseable files.
@@ -4129,14 +4336,17 @@ See also:
   }
   const strategyArg = args.find((a, i) => args[i - 1] === '--strategy') as SyncOpts['strategy'] | undefined;
   // #753/#774: monorepo subdir-source flags. --exclude is repeatable.
+  // #2156: --include is the allow-list counterpart, same repeatable shape.
   const srcSubpath = args.find((a, i) => args[i - 1] === '--src-subpath') || undefined;
   const excludePatterns: string[] = [];
+  const includePatterns: string[] = [];
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--exclude' && i + 1 < args.length) excludePatterns.push(args[i + 1]);
+    if (args[i] === '--include' && i + 1 < args.length) includePatterns.push(args[i + 1]);
   }
-  if (syncAll && (srcSubpath || excludePatterns.length > 0)) {
+  if (syncAll && (srcSubpath || excludePatterns.length > 0 || includePatterns.length > 0)) {
     console.error(
-      `--src-subpath/--exclude scope a single sync invocation; they cannot be combined with --all. ` +
+      `--src-subpath/--include/--exclude scope a single sync invocation; they cannot be combined with --all. ` +
       `For --all runs, register the subdirectory as the source's local_path instead ` +
       `(gbrain sources add <id> --path <repo>/<subdir>).`,
     );
@@ -4337,7 +4547,11 @@ See also:
     const onAllSigint = () => { try { allInterrupt.abort(new Error('SIGINT')); } catch { /* */ } };
 
     const runOne = async (src: typeof sources[number]): Promise<SyncResult> => {
-      const cfg = (src.config || {}) as { strategy?: 'markdown' | 'code' | 'auto' };
+      const cfg = (src.config || {}) as {
+        strategy?: 'markdown' | 'code' | 'auto';
+        include_globs?: unknown;
+        exclude_globs?: unknown;
+      };
       // D18: parallel path defers embed; auto-enqueue embed-backfill after.
       // v0.42.42.0 (#2139): `autoDeferEmbeds` (the inline gate tripped in a
       // non-TTY session) ALSO forces deferral — global by design (the gate's
@@ -4375,6 +4589,8 @@ See also:
         skipFailed, retryFailed, noSchemaPack,
         sourceId: src.id,
         strategy: cfg.strategy,
+        include: parseGlobList(cfg.include_globs),
+        exclude: parseGlobList(cfg.exclude_globs),
         concurrency,
         signal: composeAbortSignals(allInterrupt.signal, controller?.signal),
       };
@@ -4586,11 +4802,27 @@ See also:
   // lock released by its own finally) instead of a hard cut.
   const singleSourceInterrupt = new AbortController();
   const onSingleSourceSigint = () => { try { singleSourceInterrupt.abort(new Error('SIGINT')); } catch { /* */ } };
+  // Read persisted include/exclude globs from the source row, mirroring the
+  // --all fan-out's `runOne` closure above. Best-effort: a fetch failure
+  // falls through to "no glob filters", preserving pre-existing behavior.
+  // sourceId is always set here (resolveSourceWithTier ran above), so this
+  // path never silently runs without source-config awareness.
+  let sourceCfg: { include_globs?: unknown; exclude_globs?: unknown } = {};
+  try {
+    const { fetchSource } = await import('../core/sources-load.ts');
+    const src = await fetchSource(engine, sourceId);
+    if (src?.config && typeof src.config === 'object') {
+      sourceCfg = src.config as { include_globs?: unknown; exclude_globs?: unknown };
+    }
+  } catch { /* fall through to no filters */ }
   const opts: SyncOpts = {
     repoPath, dryRun, full, noPull, noEmbed, noExtract, skipFailed, retryFailed, noSchemaPack, sourceId,
     strategy: strategyArg, concurrency,
     srcSubpath,
-    exclude: excludePatterns.length > 0 ? excludePatterns : undefined,
+    // #2156: union of the repeatable CLI flags (one-off, this invocation
+    // only) and the source row's persisted config globs (every sync).
+    include: mergeGlobs(includePatterns, parseGlobList(sourceCfg.include_globs)),
+    exclude: mergeGlobs(excludePatterns, parseGlobList(sourceCfg.exclude_globs)),
     signal: composeAbortSignals(singleSourceInterrupt.signal, singleSourceController?.signal),
   };
 
@@ -4818,7 +5050,11 @@ export async function syncOneSource(
     noExtract?: boolean;
   },
 ): Promise<{ result: SyncResult; log: string }> {
-  const cfg = (src.config || {}) as { strategy?: 'markdown' | 'code' | 'auto' };
+  const cfg = (src.config || {}) as {
+    strategy?: 'markdown' | 'code' | 'auto';
+    include_globs?: unknown;
+    exclude_globs?: unknown;
+  };
   const log = `\n--- Syncing source: ${src.name} ---\n`;
   const repoOpts: SyncOpts = {
     repoPath: src.local_path!,
@@ -4832,6 +5068,8 @@ export async function syncOneSource(
     noSchemaPack: shared.noSchemaPack,
     sourceId: src.id,
     strategy: cfg.strategy,
+    include: parseGlobList(cfg.include_globs),
+    exclude: parseGlobList(cfg.exclude_globs),
     concurrency: shared.concurrency,
     // lockId defaults to `gbrain-sync:${src.id}` via the invariant in
     // performSync (no explicit override needed — sourceId triggers it).

src/core/ai/gateway.ts

@@ -1000,24 +1000,9 @@ const voyageCompatFetch = (async (input: RequestInfo | URL, init?: RequestInit)
   // Voyage diverges from OpenAI in two places that break the parser:
   //   - `embedding` is a base64 string (SDK schema expects `number[]`)
   //   - `usage` lacks `prompt_tokens` (SDK schema requires it when usage present)
-  //
-  // #1610: read the body ONCE via text() and JSON.parse it. The pre-fix
-  // `await resp.clone().json()` truncated large bodies on bun < 1.1.27
-  // (oven-sh/bun#6348) — the parse threw, the catch fell back to the raw
-  // response, and multi-chunk pages died with "Invalid JSON response".
-  // Every JSON return path below rebuilds the Response so a stale
-  // Content-Length/Content-Encoding header from the original can't lie
-  // about the rewritten body.
-  const bodyText = await resp.text();
-  const rebuild = (body: string) => {
-    const headers = new Headers(resp.headers);
-    headers.delete('content-length');
-    headers.delete('content-encoding');
-    return new Response(body, { status: resp.status, statusText: resp.statusText, headers });
-  };
   try {
-    const json: any = JSON.parse(bodyText);
-    if (!json || typeof json !== 'object') return rebuild(bodyText);
+    const json: any = await resp.clone().json();
+    if (!json || typeof json !== 'object') return resp;
     let modified = false;
     if (Array.isArray(json.data)) {
       for (const item of json.data) {
@@ -1052,19 +1037,22 @@ const voyageCompatFetch = (async (input: RequestInfo | URL, init?: RequestInit)
         : 0;
       modified = true;
     }
-    if (!modified) return rebuild(bodyText);
-    return rebuild(JSON.stringify(json));
+    if (!modified) return resp;
+    return new Response(JSON.stringify(json), {
+      status: resp.status,
+      statusText: resp.statusText,
+      headers: resp.headers,
+    });
   } catch (err) {
     // OOM-cap throws MUST propagate. The catch is here for "Voyage returned
     // JSON I can't reshape" (parse error, unexpected schema) — falling back
-    // to the original body is correct in that case. Letting the
+    // to the original response is correct in that case. Letting the
     // too-large response through here would defeat the entire purpose of
     // Layer 2 (the per-embedding cap that fires when Content-Length wasn't
     // available to Layer 1).
     if (err instanceof VoyageResponseTooLargeError) throw err;
-    // If parsing/transformation fails, pass the original body through
-    // (rebuilt — resp's body stream is already consumed by text()).
-    return rebuild(bodyText);
+    // If parsing/transformation fails, fall back to the original response.
+    return resp;
   }
 }) as unknown as typeof fetch;
 
@@ -1204,21 +1192,9 @@ const zeroEntropyCompatFetch = (async (input: RequestInfo | URL, init?: RequestI
   // validates. Also map usage.total_tokens → prompt_tokens (SDK requires
   // prompt_tokens when `usage` is present — same divergence Voyage hit at
   // gateway.ts:655).
-  //
-  // #1610: read the body ONCE via text() + JSON.parse — `resp.clone().json()`
-  // truncated large bodies on bun < 1.1.27 (oven-sh/bun#6348), so the parse
-  // threw and the catch fell back to the RAW ZE `{results: ...}` shape, which
-  // the AI SDK schema rejects → "Invalid JSON response" on multi-chunk pages.
-  const bodyText = await resp.text();
-  const rebuild = (body: string) => {
-    const headers = new Headers(resp.headers);
-    headers.delete('content-length');
-    headers.delete('content-encoding');
-    return new Response(body, { status: resp.status, statusText: resp.statusText, headers });
-  };
   try {
-    const json: any = JSON.parse(bodyText);
-    if (!json || typeof json !== 'object') return rebuild(bodyText);
+    const json: any = await resp.clone().json();
+    if (!json || typeof json !== 'object') return resp;
     let modified = false;
     if (Array.isArray(json.results) && !Array.isArray(json.data)) {
       // Layer 2 OOM cap — per-embedding size. ZE returns float[] arrays,
@@ -1252,25 +1228,20 @@ const zeroEntropyCompatFetch = (async (input: RequestInfo | URL, init?: RequestI
       // SDK also expects total_tokens; ZE provides it directly.
       modified = true;
     }
-    if (!modified) return rebuild(bodyText);
-    return rebuild(JSON.stringify(json));
+    if (!modified) return resp;
+    return new Response(JSON.stringify(json), {
+      status: resp.status,
+      statusText: resp.statusText,
+      headers: resp.headers,
+    });
   } catch (err) {
     // OOM-cap throws MUST propagate. Voyage's pattern: instanceof check on
     // its own tagged class. Same here — only rethrow our own cap class.
     if (err instanceof ZeroEntropyResponseTooLargeError) throw err;
-    return rebuild(bodyText);
+    return resp;
   }
 }) as unknown as typeof fetch;
 
-/**
- * Test-only seams (#1610): the compat shims are module-private closures;
- * exporting them lets tests drive the response-rewrite paths behaviorally
- * (truncating clone(), stale Content-Length) without a live provider.
- * Same pattern as __getShrinkStateForTests.
- */
-export const __voyageCompatFetchForTests = voyageCompatFetch;
-export const __zeroEntropyCompatFetchForTests = zeroEntropyCompatFetch;
-
 /**
  * Generic asymmetric-embedding shim for openai-compatible recipes that
  * ship no compat fetch of their own (llama-server, litellm, ollama, ...).

src/core/migrate.ts

@@ -5671,6 +5671,32 @@ export const MIGRATIONS: Migration[] = [
 `);
     },
   },
+  {
+    version: 125,
+    name: 'sources_config_fingerprint',
+    // #2157 follow-on: the "Already up to date" gate at sync.ts honors
+    // git-HEAD equality + chunker-version match but ignored source-config
+    // drift. A user who runs `gbrain sources add default --exclude
+    // 'Templates/**'` AFTER an initial sync got "Already up to date" on
+    // the next pass because git HEAD was unchanged — the new exclusion
+    // never reached the walk until `gbrain sync --full`.
+    //
+    // This column caches a SHA-256 fingerprint of the walk-affecting
+    // fields in `sources.config` (strategy + include_globs +
+    // exclude_globs); mismatches trigger a full re-walk via the same code
+    // path as a chunker_version bump.
+    //
+    // NULL on pre-migration rows is treated as "not yet stamped" by
+    // readConfigFingerprint, so the FIRST sync after upgrade is normal
+    // (no spurious force-full just because the column was added).
+    //
+    // Keep in sync with src/schema.sql and src/core/schema-embedded.ts.
+    idempotent: true,
+    sql: `
+      ALTER TABLE sources
+        ADD COLUMN IF NOT EXISTS config_fingerprint TEXT;
+    `,
+  },
 ];
 
 export const LATEST_VERSION = MIGRATIONS.length > 0

src/core/operations.ts

@@ -499,7 +499,7 @@ export function linkReadScopeOpts(ctx: OperationContext): { sourceId?: string; s
  * FAIL-CLOSED: anything not strictly `ctx.remote === false` is untrusted.
  *
  * This is the SINGLE resolver for every read op that accepts a per-call
- * `source_id` / `all_sources` parameter (query, search, code_callers, code_callees,
+ * `source_id` / `all_sources` parameter (query, code_callers, code_callees,
  * get_page, search_by_image, code_blast, code_flow). Inlining the `__all__`
  * branch per handler is the bug class that leaked cross-source reads (#1924,
  * #1371): a remote client could pass `source_id: '__all__'` to opt out of its
@@ -1442,24 +1442,13 @@ const search: Operation = {
     limit: { type: 'number', description: 'Max results (default 20)' },
     offset: { type: 'number', description: 'Skip first N results (for pagination)' },
     mode: { type: 'string', description: 'Search mode (conservative|balanced|tokenmax). Local callers only.' },
-    source_id: {
-      type: 'string',
-      description:
-        "Scope search to a single source. Defaults to OperationContext.sourceId. Pass '__all__' to span every source for trusted local callers; for remote callers '__all__' spans only your granted sources.",
-    },
-    all_sources: { type: 'boolean', description: "Span sources (equivalent to source_id=__all__): every source locally, your grant remotely." },
   },
   handler: async (ctx, p) => {
     const startedAt = Date.now();
     const queryText = p.query as string;
     const limit = (p.limit as number) || 20;
     const offset = (p.offset as number) || 0;
-    // #1484 follow-up: route through the canonical fail-closed resolver so
-    // `--source-id __all__` / `all_sources` behave the same as on `query`
-    // (the zero-hit CLI hint advises exactly that retry). Without a per-call
-    // param, `search` silently ignored --source-id — the retry looked like
-    // a genuine miss.
-    const scope = resolveRequestedScope(ctx, p.source_id as string | undefined, p.all_sources === true);
+    const scope = sourceScopeOpts(ctx);
 
     // T4/D5 — per-call mode honored ONLY for trusted/local callers so a remote
     // OAuth client can't escalate to the costly tokenmax bundle. Local + unknown

src/core/schema-embedded.ts

@@ -39,6 +39,13 @@ CREATE TABLE IF NOT EXISTS sources (
   -- bypassing the git-HEAD up_to_date early-return so CHUNKER_VERSION bumps
   -- actually trigger re-chunking on upgrade.
   chunker_version TEXT,
+  -- #2157 follow-on: SHA-256 fingerprint of the walk-affecting fields in
+  -- \`config\` (strategy + include_globs + exclude_globs). Mismatch forces a
+  -- full re-walk via the same code path as chunker_version, so a user who
+  -- changes \`sources.config.exclude_globs\` mid-life doesn't get "Already up
+  -- to date" on the next sync. NULL on pre-migration rows is treated as
+  -- "not yet stamped" and skips the gate (preserves first-run semantics).
+  config_fingerprint TEXT,
   -- v0.26.5: soft-delete + recovery window. \`archive\` flips archived=true and
   -- sets archive_expires_at = now() + 72h. The autopilot purge phase
   -- hard-deletes rows where archive_expires_at <= now(). Promoted from a

src/core/search/hybrid.ts

@@ -1323,18 +1323,8 @@ export async function hybridSearch(
       if (effectiveModality === 'both' && imageVectorList !== null) {
         vectorLists = [...vectorLists, imageVectorList];
       }
-    } catch (err) {
-      // Embedding/vector failure is non-fatal — fall back to keyword-only —
-      // but say WHY (#1626): this arm only runs when the embedding provider
-      // probed available, so a throw here is a real failure (embed timeout,
-      // transient pooler error on the searchVector fan-out). Pre-fix the bare
-      // catch made a cross-source `--source __all__` run silently collapse to
-      // keyword-only/"No results" with zero diagnostics.
-      warnOncePerProcess(
-        'hybrid-vector-arm-failed',
-        `[gbrain] vector arm failed (fail-open, keyword-only fallback): ` +
-          `${err instanceof Error ? err.message : String(err)}`,
-      );
+    } catch {
+      // Embedding failure is non-fatal, fall back to keyword-only
     }
   }
 

src/core/sources-ops.ts

@@ -155,6 +155,19 @@ export interface AddSourceOpts {
    * runs). Does NOT auto-`git init` anything — see `addSource` docstring.
    */
   force?: boolean;
+  /**
+   * Glob filters persisted into `sources.config.include_globs` /
+   * `sources.config.exclude_globs`. Read at sync time by
+   * `commands/sync.ts:syncOneSource` and the single-source path, threaded
+   * into `isSyncable` / `unsyncableReason` (their `SyncableOptions` shape
+   * has carried this contract since v0.41.13).
+   *
+   * Empty / unspecified arrays are not persisted at all (no `[]` written
+   * to the JSONB), which keeps the row identical to today for sources
+   * that don't use filtering.
+   */
+  includeGlobs?: string[];
+  excludeGlobs?: string[];
 }
 
 export interface RemoveSourceOpts {
@@ -429,6 +442,12 @@ export async function addSource(
     if (opts.federated !== null && opts.federated !== undefined) {
       config.federated = opts.federated;
     }
+    if (opts.includeGlobs && opts.includeGlobs.length > 0) {
+      config.include_globs = opts.includeGlobs;
+    }
+    if (opts.excludeGlobs && opts.excludeGlobs.length > 0) {
+      config.exclude_globs = opts.excludeGlobs;
+    }
     const displayName = opts.name ?? opts.id;
 
     try {
@@ -508,6 +527,12 @@ export async function addSource(
     if (opts.federated !== null && opts.federated !== undefined) {
       config.federated = opts.federated;
     }
+    if (opts.includeGlobs && opts.includeGlobs.length > 0) {
+      config.include_globs = opts.includeGlobs;
+    }
+    if (opts.excludeGlobs && opts.excludeGlobs.length > 0) {
+      config.exclude_globs = opts.excludeGlobs;
+    }
     const displayName = opts.name ?? opts.id;
     await engine.executeRaw(
       `INSERT INTO sources (id, name, local_path, config)

src/core/sync.ts

@@ -219,6 +219,13 @@ function globToRegex(pattern: string): RegExp {
   return new RegExp(regex);
 }
 
+/**
+ * Test a normalized POSIX-style path against an array of glob patterns. Returns
+ * true if any pattern matches. Empty / undefined `patterns` returns false (no
+ * filter engaged). Exported so non-sync surfaces (lint walker, future ingest
+ * variants) can apply the same glob semantics as `isSyncable` without
+ * re-declaring `globToRegex`.
+ */
 export function matchesAnyGlob(path: string, patterns?: string[]): boolean {
   if (!patterns || patterns.length === 0) return false;
   const normalized = path.replace(/\\/g, '/');

src/schema.sql

@@ -35,6 +35,13 @@ CREATE TABLE IF NOT EXISTS sources (
   -- bypassing the git-HEAD up_to_date early-return so CHUNKER_VERSION bumps
   -- actually trigger re-chunking on upgrade.
   chunker_version TEXT,
+  -- #2157 follow-on: SHA-256 fingerprint of the walk-affecting fields in
+  -- `config` (strategy + include_globs + exclude_globs). Mismatch forces a
+  -- full re-walk via the same code path as chunker_version, so a user who
+  -- changes `sources.config.exclude_globs` mid-life doesn't get "Already up
+  -- to date" on the next sync. NULL on pre-migration rows is treated as
+  -- "not yet stamped" and skips the gate (preserves first-run semantics).
+  config_fingerprint TEXT,
   -- v0.26.5: soft-delete + recovery window. `archive` flips archived=true and
   -- sets archive_expires_at = now() + 72h. The autopilot purge phase
   -- hard-deletes rows where archive_expires_at <= now(). Promoted from a

test/ai/compat-fetch-body-read.serial.test.ts

@@ -1,115 +0,0 @@
-/**
- * #1610 — Voyage/ZeroEntropy compat shims must read the response body ONCE
- * via text() instead of `resp.clone().json()`.
- *
- * On bun < 1.1.27, Response.clone() truncates large bodies (oven-sh/bun#6348):
- * the clone().json() parse threw, the shim's catch fell back to the ORIGINAL
- * response — whose wire shape (ZE `{results: ...}`, Voyage base64 embeddings)
- * the AI SDK's openai-compatible Zod schema rejects — and multi-chunk pages
- * failed with "Invalid JSON response".
- *
- * These tests simulate the truncating clone() and assert the shims still
- * return the fully rewritten body. They also pin that the rewritten Response
- * does NOT carry the original (now stale) Content-Length header, which lied
- * about the rewritten body's size (gateway.ts previously copied
- * `headers: resp.headers` verbatim).
- */
-
-import { afterEach, describe, expect, test } from 'bun:test';
-import {
-  __voyageCompatFetchForTests,
-  __zeroEntropyCompatFetchForTests,
-} from '../../src/core/ai/gateway.ts';
-
-const origFetch = globalThis.fetch;
-afterEach(() => {
-  globalThis.fetch = origFetch;
-});
-
-/** Build a Response whose clone() truncates the body (bun < 1.1.27 behavior). */
-function truncatingCloneResponse(body: string): Response {
-  const headers = {
-    'content-type': 'application/json',
-    // Deliberately stale after any rewrite: the original wire body's length.
-    'content-length': String(Buffer.byteLength(body)),
-  };
-  const resp = new Response(body, { status: 200, headers });
-  (resp as any).clone = () =>
-    new Response(body.slice(0, 32), { status: 200, headers });
-  return resp;
-}
-
-describe('voyageCompatFetch — single body read (#1610)', () => {
-  test('rewrites base64 embeddings even when clone() truncates the body', async () => {
-    const floats = new Float32Array([0.5, 0.25, -1]);
-    const b64 = Buffer.from(floats.buffer).toString('base64');
-    const wireBody = JSON.stringify({
-      object: 'list',
-      data: [{ object: 'embedding', embedding: b64, index: 0 }],
-      model: 'voyage-3',
-      usage: { total_tokens: 7 },
-    });
-    globalThis.fetch = (async () => truncatingCloneResponse(wireBody)) as unknown as typeof fetch;
-
-    const out = await __voyageCompatFetchForTests('https://api.voyageai.com/v1/embeddings', {
-      method: 'POST',
-      body: JSON.stringify({ input: ['hello'], model: 'voyage-3' }),
-      headers: { 'content-type': 'application/json' },
-    });
-
-    const json: any = await out.json();
-    expect(Array.from(json.data[0].embedding)).toEqual([0.5, 0.25, -1]);
-    expect(json.usage.prompt_tokens).toBe(7);
-    // Stale Content-Length from the wire body must not survive the rewrite.
-    expect(out.headers.get('content-length')).toBeNull();
-    expect(out.headers.get('content-encoding')).toBeNull();
-  });
-});
-
-describe('zeroEntropyCompatFetch — single body read (#1610)', () => {
-  test('rewrites {results} → {data} even when clone() truncates the body', async () => {
-    const wireBody = JSON.stringify({
-      results: [{ embedding: [0.1, 0.2] }, { embedding: [0.3, 0.4] }],
-      usage: { total_bytes: 42, total_tokens: 9 },
-    });
-    let fetchedUrl = '';
-    globalThis.fetch = (async (url: string | URL | Request) => {
-      fetchedUrl = String(url);
-      return truncatingCloneResponse(wireBody);
-    }) as unknown as typeof fetch;
-
-    const out = await __zeroEntropyCompatFetchForTests('https://api.zeroentropy.dev/v1/embeddings', {
-      method: 'POST',
-      body: JSON.stringify({ input: ['hello'], model: 'zembed-1' }),
-      headers: { 'content-type': 'application/json' },
-    });
-
-    expect(fetchedUrl.endsWith('/v1/models/embed')).toBe(true);
-    const json: any = await out.json();
-    // The AI SDK schema requires {data: [{embedding, index}]} — the raw ZE
-    // {results} fallback is exactly the pre-fix "Invalid JSON response".
-    expect(json.results).toBeUndefined();
-    expect(json.data).toHaveLength(2);
-    expect(json.data[0]).toEqual({ object: 'embedding', embedding: [0.1, 0.2], index: 0 });
-    expect(json.data[1].index).toBe(1);
-    expect(json.usage.prompt_tokens).toBe(9);
-    expect(out.headers.get('content-length')).toBeNull();
-  });
-
-  test('non-JSON body falls back to the original bytes (rebuilt, still readable)', async () => {
-    const wireBody = 'plain text, not json';
-    globalThis.fetch = (async () =>
-      new Response(wireBody, {
-        status: 200,
-        headers: { 'content-type': 'application/json' },
-      })) as unknown as typeof fetch;
-
-    const out = await __zeroEntropyCompatFetchForTests('https://api.zeroentropy.dev/v1/embeddings', {
-      method: 'POST',
-      body: JSON.stringify({ input: ['hello'] }),
-    });
-    // Body was consumed by the shim's single read; the fallback must
-    // rebuild a readable Response rather than return the drained original.
-    expect(await out.text()).toBe(wireBody);
-  });
-});

test/ai/zeroentropy-compat-fetch.test.ts

@@ -98,18 +98,16 @@ describe('zeroEntropyCompatFetch — OOM caps', () => {
     expect(src).toMatch(/MAX_ZEROENTROPY_RESPONSE_BYTES\s*=\s*256\s*\*\s*1024\s*\*\s*1024/);
   });
 
-  test('Layer 1: Content-Length pre-check before the body is read', async () => {
+  test('Layer 1: Content-Length pre-check before resp.clone().json()', async () => {
     const src = await Bun.file(GATEWAY_PATH).text();
     // Find the zeroEntropyCompatFetch block bounds, then assert ordering
-    // within it (mirroring the voyage cap test pattern). #1610 moved the
-    // body read from `resp.clone().json()` to a single `resp.text()` (bun
-    // < 1.1.27 truncates clone()d bodies, oven-sh/bun#6348).
+    // within it (mirroring the voyage cap test pattern).
     const zeFetchStart = src.indexOf('const zeroEntropyCompatFetch');
     expect(zeFetchStart).toBeGreaterThan(0);
-    const block = src.slice(zeFetchStart, zeFetchStart + 9000);
+    const block = src.slice(zeFetchStart, zeFetchStart + 8000);
 
     const preCheckIdx = block.indexOf("resp.headers.get('content-length')");
-    const jsonParseIdx = block.indexOf('const bodyText = await resp.text()');
+    const jsonParseIdx = block.indexOf('await resp.clone().json()');
     expect(preCheckIdx).toBeGreaterThan(0);
     expect(jsonParseIdx).toBeGreaterThan(0);
     // The pre-check MUST appear before the JSON parse — Voyage's lesson

test/cli-source-scope-hint.test.ts

@@ -1,61 +0,0 @@
-/**
- * #1484 — invisible-miss hint. A bare `gbrain query` resolves to a single
- * source (usually 'default'); on a multi-source brain a zero-hit run gave no
- * signal that the answer might live in another source. sourceScopeHint
- * returns the stderr hint exactly when: query/search op + zero results +
- * no explicit scoping param + >1 registered source.
- */
-
-import { describe, expect, test } from 'bun:test';
-import { sourceScopeHint } from '../src/cli.ts';
-import type { BrainEngine } from '../src/core/engine.ts';
-
-function fakeEngine(sourceCount: number, fail = false): BrainEngine {
-  return {
-    executeRaw: async () => {
-      if (fail) throw new Error('sources table missing');
-      return [{ n: sourceCount }];
-    },
-  } as unknown as BrainEngine;
-}
-
-describe('sourceScopeHint (#1484)', () => {
-  test('fires on a bare zero-hit query against a multi-source brain', async () => {
-    const hint = await sourceScopeHint('query', {}, 'default', fakeEngine(3), []);
-    expect(hint).toContain('3 sources');
-    expect(hint).toContain('"default"');
-    expect(hint).toContain('--source-id __all__');
-  });
-
-  test('fires for search too', async () => {
-    const hint = await sourceScopeHint('search', {}, 'wiki', fakeEngine(2), []);
-    expect(hint).toContain('"wiki"');
-  });
-
-  test('silent when results were found', async () => {
-    expect(await sourceScopeHint('query', {}, 'default', fakeEngine(3), [{ slug: 'a' }])).toBeNull();
-  });
-
-  test('silent when the caller scoped explicitly', async () => {
-    expect(await sourceScopeHint('query', { source_id: 'wiki' }, 'wiki', fakeEngine(3), [])).toBeNull();
-    expect(await sourceScopeHint('query', { source: 'wiki' }, 'wiki', fakeEngine(3), [])).toBeNull();
-    expect(await sourceScopeHint('query', { all_sources: true }, '__all__', fakeEngine(3), [])).toBeNull();
-  });
-
-  test('silent when the resolved scope is already __all__', async () => {
-    expect(await sourceScopeHint('query', {}, '__all__', fakeEngine(3), [])).toBeNull();
-  });
-
-  test('silent on a single-source brain', async () => {
-    expect(await sourceScopeHint('query', {}, 'default', fakeEngine(1), [])).toBeNull();
-  });
-
-  test('silent for non-search ops and non-array results', async () => {
-    expect(await sourceScopeHint('get_stats', {}, 'default', fakeEngine(3), [])).toBeNull();
-    expect(await sourceScopeHint('query', {}, 'default', fakeEngine(3), { rows: [] })).toBeNull();
-  });
-
-  test('best-effort: sources lookup failure returns null, never throws', async () => {
-    expect(await sourceScopeHint('query', {}, 'default', fakeEngine(3, true), [])).toBeNull();
-  });
-});

test/hybrid-vector-arm-warn.serial.test.ts

@@ -1,77 +0,0 @@
-/**
- * #1626 — hybridSearch's text-vector arm must not fail DARK.
- *
- * The arm only runs when the embedding provider probed available, so a throw
- * inside it (embed timeout, transient pooler error on searchVector) is a real
- * failure. Pre-fix, a bare `catch {}` swallowed it and the run silently
- * collapsed to keyword-only — under `--source __all__` on a strained pooler
- * that read as a non-deterministic "No results". The fix logs the swallowed
- * reason via warnOncePerProcess while keeping the keyword fallback.
- */
-
-import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
-import { PGLiteEngine } from '../src/core/pglite-engine.ts';
-import { hybridSearch } from '../src/core/search/hybrid.ts';
-import {
-  __setEmbedTransportForTests,
-  configureGateway,
-  resetGateway,
-} from '../src/core/ai/gateway.ts';
-import { _resetWarnOnceForTests } from '../src/core/utils.ts';
-
-let engine: PGLiteEngine;
-const origWarn = console.warn;
-
-beforeAll(async () => {
-  // Pin the gateway to OpenAI with a stub key (put-page-provenance pattern):
-  // embed() runs instantiateEmbedding — which requires OPENAI_API_KEY — BEFORE
-  // the stubbed transport is reached. Without this, a keyless CI environment
-  // throws the config error instead of the transport's, and the assertion on
-  // the swallowed reason fails. The key never leaves the process.
-  configureGateway({
-    embedding_model: 'openai:text-embedding-3-large',
-    embedding_dimensions: 1536,
-    env: { ...process.env, OPENAI_API_KEY: process.env.OPENAI_API_KEY || 'sk-test-stub' },
-  });
-  engine = new PGLiteEngine();
-  await engine.connect({});
-  await engine.initSchema();
-  await engine.putPage('people/alice-example', {
-    type: 'person',
-    title: 'Alice Example',
-    compiled_truth: 'Alice Example is a test person for the vector-arm warn test.',
-  });
-});
-
-afterAll(async () => {
-  console.warn = origWarn;
-  __setEmbedTransportForTests(null);
-  resetGateway();
-  await engine.disconnect();
-});
-
-describe('hybridSearch vector-arm failure telemetry (#1626)', () => {
-  test('embed failure logs the swallowed reason and falls back to keyword', async () => {
-    _resetWarnOnceForTests();
-    // Installing a transport makes isAvailable('embedding') true (test-seam
-    // fast path), so the vector arm RUNS — and then throws.
-    __setEmbedTransportForTests(() => {
-      throw new Error('pooler exploded mid-fanout');
-    });
-    const warnings: string[] = [];
-    console.warn = (...args: unknown[]) => {
-      warnings.push(args.map(String).join(' '));
-    };
-    try {
-      const results = await hybridSearch(engine, 'alice');
-      // Keyword fallback still returns results — fail-open preserved.
-      expect(results.some((r) => r.slug === 'people/alice-example')).toBe(true);
-    } finally {
-      console.warn = origWarn;
-      __setEmbedTransportForTests(null);
-    }
-    const armWarnings = warnings.filter((w) => w.includes('vector arm failed'));
-    expect(armWarnings).toHaveLength(1);
-    expect(armWarnings[0]).toContain('pooler exploded mid-fanout');
-  });
-});

test/lint-source-globs.test.ts

@@ -0,0 +1,153 @@
+/**
+ * `gbrain lint` source-glob filter — walker integration.
+ *
+ * PR #2157 (commit cf9a3b18, `feat/sync-source-glob-filters`) wired
+ * `sources.config.include_globs` / `exclude_globs` into `gbrain sync` so a
+ * user could exclude `Resources/veriff/**` and have every subsequent sync
+ * honor it. The lint command walked the same source dirs blind and emitted
+ * findings against paths the user had already declared out of scope — a
+ * half-finished feature.
+ *
+ * This patch extends the same persisted glob contract to lint:
+ *   - `gbrain lint` gains `--include / --exclude` flags (parallel to sync).
+ *   - `runLintCore` lifts `sources.config.{include,exclude}_globs` for any
+ *     target whose absolute path matches a source row's `local_path`, so the
+ *     cycle.lint phase + Minion lint handlers honor the same filter without
+ *     restating it.
+ *   - The walker in `collectPages` applies the filter using the SAME
+ *     `matchesAnyGlob` helper sync uses, anchored at the target dir (so a
+ *     persisted `Resources/veriff/**` glob written against the source root
+ *     works without rewriting it as an absolute path).
+ *
+ * These tests pin the walker contract. The engine-side lift
+ * (`resolveSourceGlobsForTarget`) is best-effort by design (returns `{}` on
+ * any error) and is exercised by the dream-cycle lint phase end-to-end.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+// runLintCore is the library entry — the same surface the cycle.lint phase
+// and Minion handlers call. Exercising it covers the walker via its real
+// callsite; testing `collectPages` directly would skip the wiring.
+import { runLintCore } from '../src/commands/lint.ts';
+
+// A self-contained content-sanity stub so the test never touches a real
+// engine / config file. Empty operator-literal list keeps the content-sanity
+// pass silent so the only findings come from the structural rules
+// (no-frontmatter etc.).
+const STUB_CS = {
+  fail_on_throw: false,
+  warn_on_throw: false,
+  bytes_warn: 1024 * 1024,
+  operator_literals: [],
+};
+
+describe('runLintCore — source-glob walker filter', () => {
+  let root: string;
+
+  beforeAll(() => {
+    root = mkdtempSync(join(tmpdir(), 'gbrain-lint-globs-'));
+    // Three subtrees with mixed structured / archive-style content.
+    // All pages have `# Title` headers but no frontmatter so each one
+    // emits at least one `no-frontmatter` issue under the default rule set.
+    mkdirSync(join(root, 'Notes'), { recursive: true });
+    mkdirSync(join(root, 'Resources', 'veriff'), { recursive: true });
+    mkdirSync(join(root, 'Resources', 'prior-art', 'archive-v1'), { recursive: true });
+
+    writeFileSync(join(root, 'Notes', 'a.md'), '# A\nbody\n');
+    writeFileSync(join(root, 'Notes', 'b.md'), '# B\nbody\n');
+    writeFileSync(join(root, 'Resources', 'veriff', 'spec-1.md'), '# Veriff spec 1\nbody\n');
+    writeFileSync(join(root, 'Resources', 'veriff', 'spec-2.md'), '# Veriff spec 2\nbody\n');
+    writeFileSync(join(root, 'Resources', 'prior-art', 'archive-v1', 'old.md'), '# Old\nbody\n');
+  });
+
+  afterAll(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  test('no filter — walks every .md (regression guard for default behavior)', async () => {
+    const result = await runLintCore({
+      target: root,
+      contentSanity: STUB_CS,
+    });
+    expect(result.pages_scanned).toBe(5);
+    expect(result.pages_with_issues).toBeGreaterThan(0);
+  });
+
+  test('exclude glob skips matching paths (Resources/veriff/** off-limits)', async () => {
+    const result = await runLintCore({
+      target: root,
+      contentSanity: STUB_CS,
+      exclude: ['Resources/veriff/**'],
+    });
+    // 5 total minus 2 veriff specs = 3 pages walked.
+    expect(result.pages_scanned).toBe(3);
+  });
+
+  test('exclude with multiple patterns is union (veriff + prior-art both skipped)', async () => {
+    const result = await runLintCore({
+      target: root,
+      contentSanity: STUB_CS,
+      exclude: ['Resources/veriff/**', 'Resources/prior-art/**'],
+    });
+    // 5 total minus 3 (2 veriff + 1 archive-v1) = 2 pages walked.
+    expect(result.pages_scanned).toBe(2);
+  });
+
+  test('include glob narrows the walk to matching paths only', async () => {
+    const result = await runLintCore({
+      target: root,
+      contentSanity: STUB_CS,
+      include: ['Notes/**'],
+    });
+    expect(result.pages_scanned).toBe(2);
+  });
+
+  test('exclude runs AFTER include (same precedence as `gbrain sync`)', async () => {
+    const result = await runLintCore({
+      target: root,
+      contentSanity: STUB_CS,
+      include: ['**/*.md'],
+      exclude: ['Resources/**'],
+    });
+    // include lets everything through; exclude drops the 3 Resources/* files.
+    expect(result.pages_scanned).toBe(2);
+  });
+
+  test('empty include / exclude arrays do NOT engage the filter', async () => {
+    // Symmetric with `parseGlobList` returning undefined for empty input —
+    // an empty include would otherwise classify every path as a miss and
+    // silently zero out the lint scope. Pin the guard at the walker level.
+    const result = await runLintCore({
+      target: root,
+      contentSanity: STUB_CS,
+      include: [],
+      exclude: [],
+    });
+    expect(result.pages_scanned).toBe(5);
+  });
+
+  test('exclude semantics match sync — `**` matches across path segments', async () => {
+    const result = await runLintCore({
+      target: root,
+      contentSanity: STUB_CS,
+      exclude: ['**/spec-*.md'],
+    });
+    // Both Veriff specs match the deep glob; Notes + archive-v1 survive.
+    expect(result.pages_scanned).toBe(3);
+  });
+
+  test('single-file target bypasses the filter (file mode is not a walk)', async () => {
+    // A user lints one .md explicitly: filters are a directory-walk concern,
+    // so the file is processed even if its name would match an exclude.
+    const result = await runLintCore({
+      target: join(root, 'Resources', 'veriff', 'spec-1.md'),
+      contentSanity: STUB_CS,
+      exclude: ['Resources/veriff/**'],
+    });
+    expect(result.pages_scanned).toBe(1);
+  });
+});

test/schema-bootstrap-coverage.test.ts

@@ -694,6 +694,12 @@ const COLUMN_EXEMPTIONS = new Set<string>([
   'minion_jobs.quiet_hours',
   'minion_jobs.stagger_key',
   'sources.chunker_version',
+  // #2157 follow-on (migration v125). TEXT column read by performSync's
+  // `Already up to date` gate; not referenced by any CREATE INDEX. Same
+  // upgrade-path coverage as sources.chunker_version above: fresh installs
+  // get it via the CREATE TABLE in src/schema.sql + schema-embedded.ts;
+  // pre-existing brains get it via the idempotent ALTER TABLE in v125.
+  'sources.config_fingerprint',
   'access_tokens.permissions',
   'takes.resolved_quality',
   'pages.emotional_weight_recomputed_at',

test/search-op-source-scope.test.ts

@@ -1,87 +0,0 @@
-/**
- * #1484 follow-up — the `search` op must honor per-call `source_id` /
- * `all_sources` through the canonical fail-closed resolver
- * (resolveRequestedScope), exactly like `query` does.
- *
- * Pre-fix, `search` had no source_id param at all: the zero-hit CLI hint
- * advised "retry with --source-id __all__", the flag parsed into params,
- * NOTHING consumed it, and the retry silently re-ran the same single-source
- * search — an invisible false negative (and the retry's params.source_id
- * suppressed the hint, so the user got no second warning).
- */
-
-import { describe, expect, test } from 'bun:test';
-import { operationsByName } from '../src/core/operations.ts';
-import type { OperationContext } from '../src/core/operations.ts';
-import type { BrainEngine } from '../src/core/engine.ts';
-
-const searchOp = operationsByName['search'];
-
-/** Fake engine: keyword-only config so the handler's scope goes straight to
- *  searchKeyword, where we capture the opts it was called with. */
-function makeCtx(remote: boolean, allowedSources?: string[]) {
-  const captured: { opts?: Record<string, unknown> } = {};
-  const engine = {
-    getConfig: async (key: string) => (key === 'search.mcp_keyword_only' ? 'true' : null),
-    searchKeyword: async (_q: string, opts: Record<string, unknown>) => {
-      captured.opts = opts;
-      return [];
-    },
-  } as unknown as BrainEngine;
-  const ctx = {
-    engine,
-    config: { engine: 'pglite' },
-    logger: { info: () => {}, warn: () => {}, error: () => {} },
-    dryRun: false,
-    remote,
-    sourceId: 'default',
-    ...(allowedSources ? { auth: { allowedSources } } : {}),
-  } as unknown as OperationContext;
-  return { ctx, captured };
-}
-
-describe('search op per-call source scope (#1484 follow-up)', () => {
-  test('op declares source_id + all_sources params (the CLI hint advises them)', () => {
-    expect(searchOp.params.source_id).toBeDefined();
-    expect(searchOp.params.all_sources).toBeDefined();
-  });
-
-  test('default: scopes to ctx.sourceId', async () => {
-    const { ctx, captured } = makeCtx(false);
-    await searchOp.handler(ctx, { query: 'x' });
-    expect(captured.opts?.sourceId).toBe('default');
-  });
-
-  test("local + source_id '__all__' spans the whole brain (no source filter)", async () => {
-    const { ctx, captured } = makeCtx(false);
-    await searchOp.handler(ctx, { query: 'x', source_id: '__all__' });
-    expect(captured.opts?.sourceId).toBeUndefined();
-    expect(captured.opts?.sourceIds).toBeUndefined();
-  });
-
-  test('local + all_sources=true spans the whole brain', async () => {
-    const { ctx, captured } = makeCtx(false);
-    await searchOp.handler(ctx, { query: 'x', all_sources: true });
-    expect(captured.opts?.sourceId).toBeUndefined();
-    expect(captured.opts?.sourceIds).toBeUndefined();
-  });
-
-  test('explicit source_id wins over ctx.sourceId', async () => {
-    const { ctx, captured } = makeCtx(false);
-    await searchOp.handler(ctx, { query: 'x', source_id: 'wiki' });
-    expect(captured.opts?.sourceId).toBe('wiki');
-  });
-
-  test("remote + '__all__' collapses to the caller's grant (fail-closed)", async () => {
-    const { ctx, captured } = makeCtx(true, ['wiki', 'essays']);
-    await searchOp.handler(ctx, { query: 'x', source_id: '__all__' });
-    expect(captured.opts?.sourceIds).toEqual(['wiki', 'essays']);
-  });
-
-  test('remote + out-of-grant source_id is denied', async () => {
-    const { ctx } = makeCtx(true, ['wiki']);
-    await expect(searchOp.handler(ctx, { query: 'x', source_id: 'secrets' })).rejects.toThrow(
-      /outside your granted sources/,
-    );
-  });
-});

test/sources.test.ts

@@ -159,6 +159,127 @@ describe('sources add', () => {
     await expect(runSources(engine, ['add', 'plans', '--path', '/tmp/gstack/plans']))
       .rejects.toThrow(/overlaps with existing source "gstack"/);
   });
+
+  // Glob filters — TODO #3 from the brettdavies fork recon. Pre-fix, the
+  // `SyncableOptions` shape in `src/core/sync.ts` had been carrying
+  // `include` / `exclude` since v0.41.13, but commands/sync.ts:1454 never
+  // populated them and `sources add` had no flag to persist them — so users
+  // had no way to tell gbrain to skip `Templates/` in an Obsidian vault.
+  test('--exclude persists glob into sources.config.exclude_globs', async () => {
+    const { engine, calls } = makeStub({
+      'SELECT id, name, local_path, last_commit, last_sync_at, config, created_at': [{
+        id: 'vault',
+        name: 'vault',
+        local_path: '/tmp/vault',
+        last_commit: null,
+        last_sync_at: null,
+        config: '{"exclude_globs":["Templates/**"]}',
+        created_at: new Date(),
+      }],
+    });
+    await runSources(engine, ['add', 'vault', '--path', '/tmp/vault', '--exclude', 'Templates/**']);
+    const insert = calls.find(c => c.sql.includes('INSERT INTO sources'));
+    expect(insert!.params[3]).toBe('{"exclude_globs":["Templates/**"]}');
+  });
+
+  test('--include persists glob into sources.config.include_globs', async () => {
+    const { engine, calls } = makeStub({
+      'SELECT id, name, local_path, last_commit, last_sync_at, config, created_at': [{
+        id: 'wiki',
+        name: 'wiki',
+        local_path: '/tmp/wiki',
+        last_commit: null,
+        last_sync_at: null,
+        config: '{"include_globs":["people/**"]}',
+        created_at: new Date(),
+      }],
+    });
+    await runSources(engine, ['add', 'wiki', '--path', '/tmp/wiki', '--include', 'people/**']);
+    const insert = calls.find(c => c.sql.includes('INSERT INTO sources'));
+    expect(insert!.params[3]).toBe('{"include_globs":["people/**"]}');
+  });
+
+  test('--exclude is repeatable; preserves order', async () => {
+    const { engine, calls } = makeStub({
+      'SELECT id, name, local_path, last_commit, last_sync_at, config, created_at': [{
+        id: 'vault',
+        name: 'vault',
+        local_path: '/tmp/vault',
+        last_commit: null,
+        last_sync_at: null,
+        config: '{}',
+        created_at: new Date(),
+      }],
+    });
+    await runSources(engine, [
+      'add', 'vault', '--path', '/tmp/vault',
+      '--exclude', 'Templates/**',
+      '--exclude', '.smart-env/**',
+      '--exclude', 'Drafts/**',
+    ]);
+    const insert = calls.find(c => c.sql.includes('INSERT INTO sources'));
+    expect(insert!.params[3]).toBe('{"exclude_globs":["Templates/**",".smart-env/**","Drafts/**"]}');
+  });
+
+  test('--include and --exclude compose in one command (federated source with both filter axes)', async () => {
+    const { engine, calls } = makeStub({
+      'SELECT id, name, local_path, last_commit, last_sync_at, config, created_at': [{
+        id: 'vault',
+        name: 'vault',
+        local_path: '/tmp/vault',
+        last_commit: null,
+        last_sync_at: null,
+        config: '{"federated":true,"include_globs":["people/**"],"exclude_globs":["Templates/**"]}',
+        created_at: new Date(),
+      }],
+    });
+    await runSources(engine, [
+      'add', 'vault', '--path', '/tmp/vault', '--federated',
+      '--include', 'people/**',
+      '--exclude', 'Templates/**',
+    ]);
+    const insert = calls.find(c => c.sql.includes('INSERT INTO sources'));
+    expect(insert!.params[3]).toBe(
+      '{"federated":true,"include_globs":["people/**"],"exclude_globs":["Templates/**"]}',
+    );
+  });
+
+  test('omitted glob flags leave config untouched (no [] entries persisted)', async () => {
+    // Regression guard: empty glob arrays must NOT be written. Otherwise a
+    // brain that never opts into filtering grows {"include_globs": [],
+    // "exclude_globs": []} cruft in every source row, and the parseGlobList
+    // path would return undefined anyway (the cruft is purely noise).
+    const { engine, calls } = makeStub({
+      'SELECT id, name, local_path, last_commit, last_sync_at, config, created_at': [{
+        id: 'gstack',
+        name: 'gstack',
+        local_path: '/tmp/gstack',
+        last_commit: null,
+        last_sync_at: null,
+        config: '{}',
+        created_at: new Date(),
+      }],
+    });
+    await runSources(engine, ['add', 'gstack', '--path', '/tmp/gstack']);
+    const insert = calls.find(c => c.sql.includes('INSERT INTO sources'));
+    expect(insert!.params[3]).toBe('{}');
+  });
+
+  test('--exclude requires a glob argument', async () => {
+    const { engine } = makeStub();
+    const code = await withExitCapture(() => runSources(engine, [
+      'add', 'vault', '--path', '/tmp/vault', '--exclude',
+    ]));
+    expect(code).toBe(2);
+  });
+
+  test('--include rejects a flag-like value (--include --path looks like a typo)', async () => {
+    const { engine } = makeStub();
+    const code = await withExitCapture(() => runSources(engine, [
+      'add', 'vault', '--path', '/tmp/vault', '--include', '--federated',
+    ]));
+    expect(code).toBe(2);
+  });
 });
 
 // ── add — #2707 git-repo validation (CLI wiring) ───────────────

test/sync-config-fingerprint-gate.test.ts

@@ -0,0 +1,95 @@
+/**
+ * #2157 follow-on (migration v125) — end-to-end gate wiring.
+ *
+ * `test/sync-config-fingerprint.test.ts` pins the persistence + comparison
+ * primitives (compute/read/write). This file pins the WIRING inside
+ * `performSync`: with git HEAD unchanged, a drift in the walk-affecting
+ * `sources.config` fields must break out of the "Already up to date" early
+ * return and force a full re-walk — and the re-stamped fingerprint must
+ * settle the gate back to `up_to_date` on the following pass. Deleting the
+ * `configMismatch` term from the gate condition fails this test; none of the
+ * primitive tests would catch that.
+ */
+
+import { test, expect, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { execFileSync } from 'child_process';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { performSync } from '../src/commands/sync.ts';
+
+let engine: PGLiteEngine;
+let repoPath: string;
+
+function git(cwd: string, ...args: string[]) {
+  execFileSync('git', args, { cwd, stdio: 'pipe' });
+}
+
+beforeAll(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({});
+  await engine.initSchema();
+
+  repoPath = mkdtempSync(join(tmpdir(), 'gbrain-fp-gate-'));
+  mkdirSync(join(repoPath, 'wiki'));
+  mkdirSync(join(repoPath, 'memory'));
+  writeFileSync(join(repoPath, 'wiki', 'page1.md'), '# Page 1\n\nbody\n');
+  writeFileSync(join(repoPath, 'memory', 'note1.md'), '# Note 1\n\nbody\n');
+  git(repoPath, 'init');
+  git(repoPath, 'add', '-A');
+  git(repoPath, '-c', 'user.email=t@example.com', '-c', 'user.name=t', 'commit', '-m', 'init');
+
+  await engine.executeRaw(
+    `INSERT INTO sources (id, name, local_path, config) VALUES ($1, $2, $3, $4::text::jsonb)`,
+    ['vault', 'vault', repoPath, JSON.stringify({ include_globs: ['wiki/**'] })],
+  );
+}, 60_000);
+
+afterAll(async () => {
+  await engine?.disconnect();
+  rmSync(repoPath, { recursive: true, force: true });
+});
+
+test('config-glob drift with unchanged git HEAD forces a re-walk, then settles', async () => {
+  // First sync: row config include_globs = ['wiki/**'], caller threads it
+  // (as syncOneSource / the single-source CLI path do). memory/* skipped.
+  const first = await performSync(engine, {
+    repoPath, sourceId: 'vault', include: ['wiki/**'],
+    noPull: true, noEmbed: true, full: true,
+  });
+  expect(first.status).toBe('first_sync');
+  expect(await engine.getPage('wiki/page1')).not.toBeNull();
+  expect(await engine.getPage('memory/note1')).toBeNull();
+
+  // No drift, HEAD unchanged: gate stays quiet.
+  const second = await performSync(engine, {
+    repoPath, sourceId: 'vault', include: ['wiki/**'],
+    noPull: true, noEmbed: true,
+  });
+  expect(second.status).toBe('up_to_date');
+
+  // User widens the persisted globs (what `gbrain sources add --include`
+  // writes). Git HEAD has NOT moved.
+  await engine.executeRaw(
+    `UPDATE sources SET config = $1::text::jsonb WHERE id = $2`,
+    [JSON.stringify({ include_globs: ['wiki/**', 'memory/**'] }), 'vault'],
+  );
+
+  // Pre-fix this returned `up_to_date` (HEAD unchanged) and memory/note1
+  // stayed missing until a manual `--full`. The fingerprint gate must force
+  // the full re-walk instead.
+  const third = await performSync(engine, {
+    repoPath, sourceId: 'vault', include: ['wiki/**', 'memory/**'],
+    noPull: true, noEmbed: true,
+  });
+  expect(third.status).not.toBe('up_to_date');
+  expect(await engine.getPage('memory/note1')).not.toBeNull();
+
+  // Re-stamped fingerprint matches the current row: gate settles.
+  const fourth = await performSync(engine, {
+    repoPath, sourceId: 'vault', include: ['wiki/**', 'memory/**'],
+    noPull: true, noEmbed: true,
+  });
+  expect(fourth.status).toBe('up_to_date');
+});

test/sync-config-fingerprint.test.ts

@@ -0,0 +1,234 @@
+/**
+ * #2157 follow-on (migration v125 — `sources.config_fingerprint`).
+ *
+ * The "Already up to date" gate at performSync's git-HEAD equality check
+ * honored chunker_version match but ignored `sources.config` drift.
+ * Changing `sources.config.exclude_globs` (or include_globs / strategy)
+ * had no observable effect on the next sync because git HEAD was
+ * unchanged — the gate returned early and the new walk scope never
+ * applied. This file exercises the persistence shape + drift detection
+ * end-to-end on PGLite, including:
+ *
+ *   - Migration v125 actually adds the column (regression guard against
+ *     a future re-numbering or accidental deletion).
+ *   - read/write round-trips preserve the value.
+ *   - The fingerprint differs across the three walk-affecting fields
+ *     and is order-insensitive on the array fields.
+ *   - NULL fingerprint on pre-v125 rows treats as "not stamped" so a
+ *     first post-upgrade sync doesn't spuriously force-full.
+ *   - A toggle-and-revert leaves the stored fingerprint matching the
+ *     current row, so the gate stays quiet.
+ *
+ * The wired-up gate behavior (force-full triggered on mismatch) is
+ * exercised by the existing sync end-to-end tests; here we pin the
+ * persistence + comparison primitives the gate depends on.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import {
+  computeSourceConfigFingerprint,
+  readConfigFingerprint,
+  writeConfigFingerprint,
+} from '../src/commands/sync.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+
+let engine: PGLiteEngine;
+
+beforeAll(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({});
+  await engine.initSchema();
+}, 60_000);
+
+afterAll(async () => {
+  await engine?.disconnect();
+});
+
+/** Insert a fresh source row with the given config. Returns the id. */
+async function makeSource(
+  id: string,
+  config: Record<string, unknown> = {},
+): Promise<string> {
+  await engine.executeRaw(
+    `INSERT INTO sources (id, name, local_path, config) VALUES ($1, $2, $3, $4::text::jsonb)`,
+    [id, id, `/tmp/${id}`, JSON.stringify(config)],
+  );
+  return id;
+}
+
+describe('migration v125 — sources.config_fingerprint column', () => {
+  test('column exists on the sources table', async () => {
+    const rows = await engine.executeRaw<{ column_name: string }>(
+      `SELECT column_name FROM information_schema.columns
+        WHERE table_name = 'sources' AND column_name = 'config_fingerprint'`,
+    );
+    expect(rows).toHaveLength(1);
+  });
+
+  test('column is nullable (preserves pre-migration row semantics)', async () => {
+    const rows = await engine.executeRaw<{ is_nullable: string }>(
+      `SELECT is_nullable FROM information_schema.columns
+        WHERE table_name = 'sources' AND column_name = 'config_fingerprint'`,
+    );
+    expect(rows[0]?.is_nullable).toBe('YES');
+  });
+});
+
+describe('readConfigFingerprint / writeConfigFingerprint — persistence round-trip', () => {
+  test('round-trip: write then read returns the same value', async () => {
+    const id = await makeSource('rt-basic', { exclude_globs: ['Templates/**'] });
+    const fp = computeSourceConfigFingerprint({ exclude_globs: ['Templates/**'] });
+    await writeConfigFingerprint(engine, id, fp);
+    const got = await readConfigFingerprint(engine, id);
+    expect(got).toBe(fp);
+  });
+
+  test('NULL on never-stamped row (pre-v125 semantics)', async () => {
+    const id = await makeSource('rt-never');
+    const got = await readConfigFingerprint(engine, id);
+    expect(got).toBeNull();
+  });
+
+  test('undefined sourceId returns null (legacy non-source-scoped sync)', async () => {
+    const got = await readConfigFingerprint(engine, undefined);
+    expect(got).toBeNull();
+  });
+
+  test('write with undefined sourceId is a no-op (does not throw)', async () => {
+    // The legacy global-sync code path hits this branch; the guard must
+    // be silent rather than fail the sync run.
+    await writeConfigFingerprint(engine, undefined, 'deadbeef'.repeat(8));
+    // No assertion beyond "did not throw"; the function returns void.
+  });
+
+  test('overwrite: a second write replaces the prior fingerprint', async () => {
+    const id = await makeSource('rt-overwrite');
+    await writeConfigFingerprint(engine, id, 'a'.repeat(64));
+    await writeConfigFingerprint(engine, id, 'b'.repeat(64));
+    const got = await readConfigFingerprint(engine, id);
+    expect(got).toBe('b'.repeat(64));
+  });
+});
+
+describe('end-to-end drift simulation — the gate semantics this column enables', () => {
+  test('first stamp matches computed fingerprint of the row config', async () => {
+    const cfg = { exclude_globs: ['Templates/**', 'Photos/**'], strategy: 'markdown' };
+    const id = await makeSource('e2e-first-stamp', cfg);
+    const computed = computeSourceConfigFingerprint(cfg);
+    await writeConfigFingerprint(engine, id, computed);
+    expect(await readConfigFingerprint(engine, id)).toBe(computed);
+  });
+
+  test('exclude_globs mutation makes stored != current (drift detected)', async () => {
+    const before = { exclude_globs: ['Templates/**'] };
+    const after = { exclude_globs: ['Templates/**', 'Photos/**'] };
+    const id = await makeSource('e2e-exclude-drift', before);
+    const beforeFp = computeSourceConfigFingerprint(before);
+    await writeConfigFingerprint(engine, id, beforeFp);
+
+    // Simulate the user mutating sources.config via `gbrain sources add
+    // --exclude`. The gate's next read of (stored, computed-from-current)
+    // detects the drift and forces a re-walk.
+    await engine.executeRaw(
+      `UPDATE sources SET config = $1::text::jsonb WHERE id = $2`,
+      [JSON.stringify(after), id],
+    );
+    const afterFp = computeSourceConfigFingerprint(after);
+    const stored = await readConfigFingerprint(engine, id);
+    expect(stored).toBe(beforeFp);
+    expect(stored).not.toBe(afterFp);
+  });
+
+  test('toggle-and-revert: add then remove same pattern leaves stored matching current', async () => {
+    const original = { exclude_globs: ['Templates/**'] };
+    const id = await makeSource('e2e-toggle', original);
+    const originalFp = computeSourceConfigFingerprint(original);
+    await writeConfigFingerprint(engine, id, originalFp);
+
+    // Add a pattern (drift) then remove it (revert).
+    await engine.executeRaw(
+      `UPDATE sources SET config = $1::text::jsonb WHERE id = $2`,
+      [JSON.stringify({ exclude_globs: ['Templates/**', 'Photos/**'] }), id],
+    );
+    await engine.executeRaw(
+      `UPDATE sources SET config = $1::text::jsonb WHERE id = $2`,
+      [JSON.stringify(original), id],
+    );
+    const revertedFp = computeSourceConfigFingerprint(original);
+    expect(revertedFp).toBe(originalFp);
+    expect(await readConfigFingerprint(engine, id)).toBe(originalFp);
+    // ⇒ Gate compares storedFp (==originalFp) to currentFp (==originalFp): no drift, no force-full.
+  });
+
+  test('include_globs drift detected independently', async () => {
+    const before = { include_globs: ['people/**'] };
+    const after = { include_globs: ['people/**', 'companies/**'] };
+    const id = await makeSource('e2e-include-drift', before);
+    await writeConfigFingerprint(engine, id, computeSourceConfigFingerprint(before));
+    await engine.executeRaw(
+      `UPDATE sources SET config = $1::text::jsonb WHERE id = $2`,
+      [JSON.stringify(after), id],
+    );
+    const stored = await readConfigFingerprint(engine, id);
+    const current = computeSourceConfigFingerprint(after);
+    expect(stored).not.toBe(current);
+  });
+
+  test('strategy drift detected', async () => {
+    const before = { strategy: 'markdown' };
+    const after = { strategy: 'code' };
+    const id = await makeSource('e2e-strategy-drift', before);
+    await writeConfigFingerprint(engine, id, computeSourceConfigFingerprint(before));
+    await engine.executeRaw(
+      `UPDATE sources SET config = $1::text::jsonb WHERE id = $2`,
+      [JSON.stringify(after), id],
+    );
+    expect(await readConfigFingerprint(engine, id))
+      .not.toBe(computeSourceConfigFingerprint(after));
+  });
+
+  test('mutating unrelated config field (federated) does NOT drift', async () => {
+    // The fingerprint hashes ONLY walk-affecting fields. Federation
+    // changes search visibility, not the walk set — must not invalidate
+    // the checkpoint.
+    const id = await makeSource('e2e-federated-toggle', {
+      federated: true,
+      exclude_globs: ['Templates/**'],
+    });
+    await writeConfigFingerprint(
+      engine,
+      id,
+      computeSourceConfigFingerprint({ exclude_globs: ['Templates/**'] }),
+    );
+    await engine.executeRaw(
+      `UPDATE sources SET config = $1::text::jsonb WHERE id = $2`,
+      [
+        JSON.stringify({ federated: false, exclude_globs: ['Templates/**'] }),
+        id,
+      ],
+    );
+    const stored = await readConfigFingerprint(engine, id);
+    const current = computeSourceConfigFingerprint({
+      federated: false,
+      exclude_globs: ['Templates/**'],
+    });
+    expect(stored).toBe(current);
+  });
+
+  test('double-encoded JSONB config (the sources-add stringify bug) hashes equivalently to the parsed object', async () => {
+    // `gbrain sources add` writes `JSON.stringify(config)::jsonb`, which
+    // double-encodes the value into a JSON-string scalar (`"{\"x\":1}"`)
+    // rather than a proper JSONB object. The defensive reader in
+    // postgres-engine.ts:1274 + readSourceConfig parses the string back
+    // before the fingerprint sees it, so a double-encoded row and a
+    // properly-shaped row must fingerprint identically.
+    const cfg = { exclude_globs: ['Templates/**'], strategy: 'markdown' };
+    const direct = computeSourceConfigFingerprint(cfg);
+    // The pure compute fn handles a pre-parsed object; the persistence
+    // layer's job is to deliver a parsed object. We assert that the
+    // round-trip a real read would produce (parse the string scalar)
+    // hashes to the same value.
+    const parsed = JSON.parse(JSON.stringify(cfg));
+    expect(computeSourceConfigFingerprint(parsed)).toBe(direct);
+  });
+});

test/sync-monorepo.test.ts

@@ -355,6 +355,69 @@ describe('sync monorepo subdir-source support (#753/#774)', () => {
     expect(await engine.getPage('wiki/draft-a')).toBeNull();
   });
 
+  // ─────────────────────────────────────────────────────────────────────────
+  // --include: allow-list counterpart (#2156). Same scope-relative anchoring
+  // as --exclude; exclude applies after include.
+  // ─────────────────────────────────────────────────────────────────────────
+
+  test('--include: only matching files import on full sync', async () => {
+    const { performSync } = await import('../src/commands/sync.ts');
+    const result = await performSync(engine, {
+      repoPath,
+      include: ['wiki/**'],
+      noPull: true,
+      noEmbed: true,
+      full: true,
+    });
+    expect(result.status).toBe('first_sync');
+    expect(result.added).toBe(2); // wiki/page1 + wiki/page2; memory/* miss the allow-list
+    expect(await engine.getPage('wiki/page1')).not.toBeNull();
+    expect(await engine.getPage('memory/note1')).toBeNull();
+  });
+
+  test('--include applies to the incremental path too', async () => {
+    const { performSync } = await import('../src/commands/sync.ts');
+    const first = await performSync(engine, {
+      repoPath,
+      include: ['wiki/**'],
+      noPull: true,
+      noEmbed: true,
+      full: true,
+    });
+    expect(first.status).toBe('first_sync');
+
+    writeFileSync(join(repoPath, 'wiki', 'page3.md'), mdPage('Wiki Page 3'));
+    writeFileSync(join(repoPath, 'memory', 'note3.md'), mdPage('Memory Note 3'));
+    gitCommit(repoPath, 'more pages');
+
+    const second = await performSync(engine, {
+      repoPath,
+      include: ['wiki/**'],
+      noPull: true,
+      noEmbed: true,
+    });
+    expect(second.status).toBe('synced');
+    expect(second.added).toBe(1); // wiki/page3 only; memory/note3 misses the allow-list
+    expect(await engine.getPage('wiki/page3')).not.toBeNull();
+    expect(await engine.getPage('memory/note3')).toBeNull();
+  });
+
+  test('--exclude applies after --include (path in both is rejected)', async () => {
+    const { performSync } = await import('../src/commands/sync.ts');
+    const result = await performSync(engine, {
+      repoPath,
+      include: ['wiki/**'],
+      exclude: ['wiki/page2.md'],
+      noPull: true,
+      noEmbed: true,
+      full: true,
+    });
+    expect(result.status).toBe('first_sync');
+    expect(result.added).toBe(1); // page1 only: page2 included then excluded
+    expect(await engine.getPage('wiki/page1')).not.toBeNull();
+    expect(await engine.getPage('wiki/page2')).toBeNull();
+  });
+
   // ─────────────────────────────────────────────────────────────────────────
   // --exclude '**/*' emits warning (NAV-4)
   // ─────────────────────────────────────────────────────────────────────────

test/sync-source-globs.test.ts

@@ -0,0 +1,212 @@
+/**
+ * TODO #3 — `parseGlobList` defensive parse.
+ *
+ * `sources.config` is a JSONB column with no schema. The runtime can find
+ * anything in `config.include_globs` / `config.exclude_globs`:
+ *   - A user `gbrain sources add` wrote `["people/**"]` (the happy path).
+ *   - A stray hand-edit wrote `"people/**"` (string, not array).
+ *   - A future migration's null default.
+ *   - A test fixture that left the column at `{}`.
+ *
+ * The parse must produce `string[] | undefined` so the downstream
+ * `SyncOpts.include` / `SyncOpts.exclude` are either undefined (no filter)
+ * or a non-empty list of usable globs. Returning `[]` would make
+ * `commands/sync.ts:1454` engage the filter loop with an empty allow-list
+ * that classifies every path as `include-glob-miss`.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { parseGlobList, mergeGlobs, computeSourceConfigFingerprint } from '../src/commands/sync.ts';
+
+describe('parseGlobList — JSONB-safe coercion to string[] | undefined', () => {
+  test('happy path: array of strings round-trips identically', () => {
+    expect(parseGlobList(['people/**', 'companies/**'])).toEqual(['people/**', 'companies/**']);
+  });
+
+  test('single-element array returned as-is', () => {
+    expect(parseGlobList(['Templates/**'])).toEqual(['Templates/**']);
+  });
+
+  test('non-array values return undefined (string, object, number, null)', () => {
+    expect(parseGlobList('Templates/**')).toBeUndefined();
+    expect(parseGlobList({ globs: ['Templates/**'] })).toBeUndefined();
+    expect(parseGlobList(42)).toBeUndefined();
+    expect(parseGlobList(null)).toBeUndefined();
+    expect(parseGlobList(undefined)).toBeUndefined();
+  });
+
+  test('empty array returns undefined (no engagement of the filter loop)', () => {
+    // Critical: a literal `[]` must not slip through. Empty `include` in
+    // SyncableOptions silently passes everything (good), but empty
+    // `exclude` is fine too — the real motivation is to keep `SyncOpts`
+    // unset so callers can ignore the field entirely. Symmetric with the
+    // `omitted glob flags leave config untouched` regression guard in
+    // sources.test.ts.
+    expect(parseGlobList([])).toBeUndefined();
+  });
+
+  test('mixed array drops non-string entries and keeps the rest', () => {
+    expect(parseGlobList(['people/**', 42, null, 'companies/**'])).toEqual([
+      'people/**',
+      'companies/**',
+    ]);
+  });
+
+  test('empty strings dropped (a `""` glob would match every path)', () => {
+    expect(parseGlobList(['', 'people/**', ''])).toEqual(['people/**']);
+  });
+
+  test('array of only empty strings collapses to undefined', () => {
+    expect(parseGlobList(['', '', ''])).toBeUndefined();
+  });
+});
+
+describe('mergeGlobs — CLI flags union with persisted source-config globs', () => {
+  test('both sides present: union, deduped, CLI first', () => {
+    expect(mergeGlobs(['a/**', 'b/**'], ['b/**', 'c/**'])).toEqual(['a/**', 'b/**', 'c/**']);
+  });
+
+  test('CLI only', () => {
+    expect(mergeGlobs(['a/**'], undefined)).toEqual(['a/**']);
+  });
+
+  test('persisted only', () => {
+    expect(mergeGlobs([], ['Templates/**'])).toEqual(['Templates/**']);
+  });
+
+  test('neither side: undefined so SyncOpts stays unset', () => {
+    expect(mergeGlobs([], undefined)).toBeUndefined();
+  });
+});
+
+/**
+ * #2157 follow-on (sources_config_fingerprint, migration v125).
+ *
+ * computeSourceConfigFingerprint hashes the walk-affecting fields of
+ * sources.config (strategy + include_globs + exclude_globs) so the
+ * "Already up to date" gate at performSync's git-HEAD equality check
+ * can detect drift and force a re-walk. These cases pin the contract
+ * the gate depends on:
+ *
+ *   - Deterministic over equivalent inputs (order-insensitive,
+ *     defensively-coerced via parseGlobList).
+ *   - Sensitive to each walk-affecting field separately.
+ *   - Insensitive to fields the walker doesn't read (federated,
+ *     unrelated keys).
+ *   - A toggle-and-revert is a no-op (returns to the original hash).
+ *
+ * Without the canonicalization the gate would fire spuriously on
+ * cosmetic changes (e.g. a user re-ordering their exclude list) and
+ * miss real drift (e.g. an add-then-remove that nets to a different
+ * effective set than the stored fingerprint).
+ */
+describe('computeSourceConfigFingerprint — walk-affecting config drift detector', () => {
+  test('empty config produces a stable hash', () => {
+    const a = computeSourceConfigFingerprint({});
+    const b = computeSourceConfigFingerprint({});
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[a-f0-9]{64}$/);
+  });
+
+  test('null / undefined / missing config all hash the same', () => {
+    const empty = computeSourceConfigFingerprint({});
+    expect(computeSourceConfigFingerprint(null)).toBe(empty);
+    expect(computeSourceConfigFingerprint(undefined)).toBe(empty);
+  });
+
+  test('same config → same hash (deterministic)', () => {
+    const cfg = { strategy: 'markdown', exclude_globs: ['Templates/**', 'Photos/**'] };
+    expect(computeSourceConfigFingerprint(cfg)).toBe(computeSourceConfigFingerprint(cfg));
+  });
+
+  test('array order does not affect hash (canonical sort)', () => {
+    const a = computeSourceConfigFingerprint({ exclude_globs: ['a/**', 'b/**', 'c/**'] });
+    const b = computeSourceConfigFingerprint({ exclude_globs: ['c/**', 'a/**', 'b/**'] });
+    expect(a).toBe(b);
+  });
+
+  test('exclude_globs change → different hash', () => {
+    const a = computeSourceConfigFingerprint({ exclude_globs: ['Templates/**'] });
+    const b = computeSourceConfigFingerprint({ exclude_globs: ['Templates/**', 'Photos/**'] });
+    expect(a).not.toBe(b);
+  });
+
+  test('include_globs change → different hash', () => {
+    const a = computeSourceConfigFingerprint({ include_globs: ['people/**'] });
+    const b = computeSourceConfigFingerprint({ include_globs: ['people/**', 'companies/**'] });
+    expect(a).not.toBe(b);
+  });
+
+  test('strategy change → different hash', () => {
+    const a = computeSourceConfigFingerprint({ strategy: 'markdown' });
+    const b = computeSourceConfigFingerprint({ strategy: 'code' });
+    expect(a).not.toBe(b);
+  });
+
+  test('strategy unset vs set differ', () => {
+    const unset = computeSourceConfigFingerprint({});
+    const set = computeSourceConfigFingerprint({ strategy: 'markdown' });
+    expect(unset).not.toBe(set);
+  });
+
+  test('add-then-remove returns to original hash (toggle is a no-op)', () => {
+    const original = computeSourceConfigFingerprint({ exclude_globs: ['Templates/**'] });
+    const added = computeSourceConfigFingerprint({ exclude_globs: ['Templates/**', 'Photos/**'] });
+    const reverted = computeSourceConfigFingerprint({ exclude_globs: ['Templates/**'] });
+    expect(added).not.toBe(original);
+    expect(reverted).toBe(original);
+  });
+
+  test('non-walk-affecting fields are ignored (federated, unrelated keys)', () => {
+    const a = computeSourceConfigFingerprint({ exclude_globs: ['Templates/**'], federated: true });
+    const b = computeSourceConfigFingerprint({ exclude_globs: ['Templates/**'], federated: false });
+    const c = computeSourceConfigFingerprint({ exclude_globs: ['Templates/**'], some_unrelated_key: 'value' });
+    expect(a).toBe(b);
+    expect(a).toBe(c);
+  });
+
+  test('non-string strategy coerced to null (defensive)', () => {
+    // A hand-edited row could leave `strategy: 42` or `strategy: {}` — both
+    // collapse to the same shape as `strategy: undefined` so the fingerprint
+    // doesn't reflect a value the walker can't honor anyway.
+    const empty = computeSourceConfigFingerprint({});
+    expect(computeSourceConfigFingerprint({ strategy: 42 })).toBe(empty);
+    expect(computeSourceConfigFingerprint({ strategy: {} })).toBe(empty);
+    expect(computeSourceConfigFingerprint({ strategy: null })).toBe(empty);
+  });
+
+  test('defensive parsing: mixed-type glob arrays hash same as cleaned arrays', () => {
+    // parseGlobList drops non-string + empty entries; the fingerprint must
+    // reflect what the walker actually uses, not what the raw row says.
+    const dirty = computeSourceConfigFingerprint({
+      exclude_globs: ['Templates/**', 42, null, '', 'Photos/**'],
+    });
+    const clean = computeSourceConfigFingerprint({
+      exclude_globs: ['Templates/**', 'Photos/**'],
+    });
+    expect(dirty).toBe(clean);
+  });
+
+  test('empty array and missing field hash identically', () => {
+    const missing = computeSourceConfigFingerprint({});
+    const emptyArray = computeSourceConfigFingerprint({ exclude_globs: [] });
+    const emptyAfterClean = computeSourceConfigFingerprint({ exclude_globs: ['', '', ''] });
+    expect(emptyArray).toBe(missing);
+    expect(emptyAfterClean).toBe(missing);
+  });
+
+  test('non-array exclude_globs (string, object) hash same as missing', () => {
+    const missing = computeSourceConfigFingerprint({});
+    expect(computeSourceConfigFingerprint({ exclude_globs: 'Templates/**' })).toBe(missing);
+    expect(computeSourceConfigFingerprint({ exclude_globs: { foo: 'bar' } })).toBe(missing);
+  });
+
+  test('SHA-256 output shape: 64 hex characters', () => {
+    const fp = computeSourceConfigFingerprint({
+      strategy: 'markdown',
+      include_globs: ['people/**'],
+      exclude_globs: ['Templates/**', '.git/**'],
+    });
+    expect(fp).toMatch(/^[a-f0-9]{64}$/);
+  });
+});

test/voyage-response-cap.test.ts

@@ -34,7 +34,7 @@ describe('v0.31.8 — voyage Content-Length pre-check + per-item cap', () => {
     expect(source).toMatch(/MAX_VOYAGE_RESPONSE_BYTES\s*=\s*256\s*\*\s*1024\s*\*\s*1024/);
   });
 
-  test('Layer 1: Content-Length pre-check fires BEFORE the body is read (D10 OOM defense)', async () => {
+  test('Layer 1: Content-Length pre-check fires BEFORE resp.clone().json() (D10 OOM defense)', async () => {
     const source = await Bun.file(new URL('../src/core/ai/gateway.ts', import.meta.url)).text();
     // Anchor relative to the post-fetch handler block. The function declaration
     // contains an OUTBOUND request body section earlier; we want to verify
@@ -47,10 +47,8 @@ describe('v0.31.8 — voyage Content-Length pre-check + per-item cap', () => {
     // doesn't pin to comment text.
     const preCheckIdx = inboundBlock.indexOf("resp.headers.get('content-length')");
     // Use the full lvalue assignment so the match doesn't accidentally hit
-    // comment text that mentions the body read for context. (#1610 moved the
-    // read from `resp.clone().json()` to a single `resp.text()` — bun <
-    // 1.1.27 truncates clone()d bodies, oven-sh/bun#6348.)
-    const jsonParseIdx = inboundBlock.indexOf('const bodyText = await resp.text()');
+    // comment text that mentions `await resp.clone().json()` for context.
+    const jsonParseIdx = inboundBlock.indexOf('const json: any = await resp.clone().json()');
     expect(preCheckIdx).toBeGreaterThan(0);
     expect(jsonParseIdx).toBeGreaterThan(0);
     // The pre-check MUST appear before the JSON parse — otherwise the OOM