test(dream): conform dream-dir-source-stamp to canonical PGLite isolation pattern

check:test-isolation R3/R4 flagged the new test file: engine was created
in beforeEach (outside beforeAll) and never disconnected in afterAll.
Switch to the canonical shared-engine pattern (beforeAll create,
beforeEach resetPgliteState, afterAll disconnect) per
test/helpers/reset-pglite.ts.

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

src/commands/autopilot-fanout.ts

@@ -186,18 +186,6 @@ export function isSourceStale(src: SourceRow, now = Date.now(), floorMin = FULL_
   return ageMin >= floorMin;
 }
 
-/**
- * #2060: count sources past the per-source cycle freshness floor. Consumed
- * by autopilot's dispatch decision — a stale source forces the fanout path
- * even when the doctor plan is small (score 70–94, plan ≤ 3, est < 300s),
- * so targeted mode can't leave cycle_freshness stale indefinitely.
- * dispatchPerSource's own throttles (skipped_fresh / fanoutMax / failure
- * cooldown) bound the resulting work.
- */
-export function countStaleSources(sources: SourceRow[], now = Date.now(), floorMin = FULL_CYCLE_FLOOR_MIN): number {
-  return sources.filter((s) => isSourceStale(s, now, floorMin)).length;
-}
-
 /**
  * Most recent SUCCESSFUL cycle for a source. Prefers `last_source_cycle_at`
  * (per-source phases, written by the split cycle) and falls back to the legacy

src/commands/autopilot.ts

@@ -38,6 +38,7 @@ import { logSelfUpgrade } from '../core/audit/self-upgrade-audit.ts';
 import { detectInstallMethod } from './upgrade.ts';
 import { evaluateQuietHours } from '../core/minions/quiet-hours.ts';
 import { inspectLock } from '../core/db-lock.ts';
+import { registerCleanup } from '../core/process-cleanup.ts';
 
 /**
  * v0.37.7.0 #1162 — classify autopilot reconnect-loop errors.
@@ -433,6 +434,37 @@ export async function runAutopilot(engine: BrainEngine, args: string[]) {
   let stopping = false;
   let childSupervisor: ChildWorkerSupervisor | null = null;
 
+  // #1872: graceful engine shutdown. On PGLite the cycle steps run INLINE in
+  // this process, so a hard `process.exit` mid-write (systemctl stop →
+  // SIGTERM) kills WASM Postgres with the WAL dirty and can corrupt the
+  // brain. Two exit paths must both close the engine:
+  //   - autopilot's own shutdown() below (owns SIGINT + internal stops like
+  //     max_crashes / cycle-failure-cap), and
+  //   - process-cleanup's SIGTERM handler (installed at cli.ts module load;
+  //     it runs the cleanup registry with a 3s deadline and then exits) —
+  //     which is why closeEngine is ALSO registered there.
+  // closeEngine aborts the in-flight inline cycle (runCycle checks the
+  // signal between phases and threads it into phase sub-work), gives it a
+  // short bounded window to wind down, then disconnects. PGLite's
+  // disconnect() drains the pending query and checkpoints before closing;
+  // a second call is a no-op (disconnect snapshots + nulls the handle), so
+  // both paths firing is safe.
+  const shutdownAbort = new AbortController();
+  let inflightInlineCycle: Promise<unknown> | null = null;
+  const closeEngine = async () => {
+    shutdownAbort.abort(new Error('autopilot shutdown'));
+    if (inflightInlineCycle) {
+      // ponytail: 2s cap keeps us inside process-cleanup's 3s deadline; a
+      // between-phase abort resolves instantly, a mid-phase one may not.
+      await Promise.race([
+        inflightInlineCycle.catch(() => { /* cycle errors already logged by the loop */ }),
+        new Promise((r) => setTimeout(r, 2_000)),
+      ]);
+    }
+    try { await engine.disconnect(); } catch { /* best-effort */ }
+  };
+  const deregisterEngineClose = registerCleanup('autopilot-engine-close', closeEngine);
+
   if (spawnManagedWorker) {
     const cliPath = resolveGbrainCliPath();
     // Cgroup-aware auto-sized RSS watchdog cap (issue #1678). The old flat
@@ -520,6 +552,10 @@ export async function runAutopilot(engine: BrainEngine, args: string[]) {
         childSupervisor.killChild('SIGKILL');
       }
     }
+    // #1872: abort the in-flight inline cycle and close the engine BEFORE
+    // process.exit — a hard exit mid-write corrupts PGLite's WASM Postgres.
+    await closeEngine();
+    deregisterEngineClose();
     try { unlinkSync(lockPath); } catch { /* already gone */ }
     process.exit(0);
   };
@@ -901,27 +937,13 @@ export async function runAutopilot(engine: BrainEngine, args: string[]) {
         const FULL_CYCLE_FLOOR_MIN = 60;
         const minutesSinceLastFull = (Date.now() - lastFullCycleAt) / 60000;
 
-        // #2060: stale per-source cycle freshness is a dispatch input. Without
-        // it, a brain sitting at score 70–94 with a small targeted plan (≤3
-        // steps, <300s) stays in targeted mode indefinitely and no per-source
-        // cycle is ever dispatched — cycle_freshness never advances. A stale
-        // source forces the fanout path; dispatchPerSource's throttles
-        // (skipped_fresh / fanoutMax / failure cooldown) bound the work.
-        // Fail-open to 0: a read failure must not block dispatch.
-        let staleCycleSources = 0;
-        try {
-          const { countStaleSources } = await import('./autopilot-fanout.ts');
-          staleCycleSources = countStaleSources(await engine.listAllSources({ localPathOnly: true }));
-        } catch { /* fail-open: freshness is a dispatch hint, not a gate */ }
-
         const shouldFullCycle =
           (score >= 95 && plan.length === 0 && minutesSinceLastFull >= FULL_CYCLE_FLOOR_MIN) ||
           plan.length > 3 ||
           estTotal >= 300 ||
-          score < 70 ||
-          staleCycleSources > 0;
+          score < 70;
 
-        const shouldSleep = score >= 95 && plan.length === 0 && minutesSinceLastFull < FULL_CYCLE_FLOOR_MIN && staleCycleSources === 0;
+        const shouldSleep = score >= 95 && plan.length === 0 && minutesSinceLastFull < FULL_CYCLE_FLOOR_MIN;
 
         if (shouldSleep) {
           if (jsonMode) {
@@ -1022,16 +1044,21 @@ export async function runAutopilot(engine: BrainEngine, args: string[]) {
       // path's phase set). Now both converge on the same primitive.
       try {
         const { runCycle } = await import('../core/cycle.ts');
-        const report = await runCycle(engine, {
+        // #1872: track the promise so closeEngine can drain it on shutdown,
+        // and pass the abort signal so the cycle winds down between phases.
+        const cyclePromise = runCycle(engine, {
           brainDir: repoPath,
           // Autopilot daemon path: pulls by default (matches
           // pre-v0.17 autopilot behavior). CLI dream defaults false
           // for cron safety; that choice is scoped to dream only.
           pull: true,
+          signal: shutdownAbort.signal,
           yieldBetweenPhases: async () => {
             await new Promise(r => setImmediate(r));
           },
         });
+        inflightInlineCycle = cyclePromise;
+        const report = await cyclePromise.finally(() => { inflightInlineCycle = null; });
         // Only 'failed' (every attempted phase failed) trips the autopilot
         // circuit breaker. 'partial' means at least one phase warned or
         // failed while others ran — that's a soft signal, not a fatal

src/commands/dream.ts

@@ -26,6 +26,7 @@
 import type { BrainEngine } from '../core/engine.ts';
 import {
   runCycle,
+  resolveSourceForDir,
   ALL_PHASES,
   type CyclePhase,
   type CycleReport,
@@ -380,9 +381,9 @@ Options:
 
   --source <id>       Scope the cycle to one source so doctor's
                       cycle_freshness check sees a fresh stamp on
-                      completion. Without this, gbrain dream's
-                      timestamp never lands and federated brains
-                      see "stale cycle" forever.
+                      completion. When omitted, gbrain derives the
+                      source from --dir / the configured checkout
+                      when it matches a source's local_path (#1869).
   --source-id <id>    Alias for --source. Matches the v0.37.7.0+
                       naming used by import/extract/graph-query.
 
@@ -634,6 +635,25 @@ export async function runDream(engine: BrainEngine | null, args: string[]): Prom
     );
     process.exit(1);
   }
+
+  // #1869: a path-scoped run (--dir, or the configured sync.repo_path) whose
+  // directory matches a registered source's local_path IS that source's cycle
+  // — derive the source id so runCycle writes last_source_cycle_at /
+  // last_full_cycle_at on success and doctor's cycle_freshness check stops
+  // reading perpetually stale. Explicit --source still wins (resolved above).
+  // Fixed here at the command level, NOT in runCycle's stamp gate, so legacy
+  // global callers (autopilot-global-maintenance runs GLOBAL_PHASES with a
+  // brainDir and no sourceId) can't falsely stamp per-source freshness.
+  // A derived match on an archived source is skipped silently (falls back to
+  // legacy unscoped behavior) — stamping it would mask staleness on restore,
+  // mirroring the explicit --source archived guard above.
+  if (resolvedSourceId === undefined && engine !== null && brainDir !== null) {
+    const derived = await resolveSourceForDir(engine, brainDir);
+    if (derived !== undefined) {
+      const src = await fetchSource(engine, derived);
+      if (src?.archived !== true) resolvedSourceId = derived;
+    }
+  }
   // ─── issue #1678: bounded single-hold extract_atoms drain ──────────
   if (opts.drain) {
     if (engine === null) {

src/core/cycle.ts

@@ -854,12 +854,17 @@ interface SyncPhaseResult extends PhaseResult {
 /**
  * Resolve the source id for a brain directory by looking up the sources
  * table. Returns undefined when no registered source matches (falls back
- * to pre-v0.18 global config.sync.* keys) OR when MORE than one source
- * claims the path — an ambiguous match must not scope phases or stamp
- * last_full_cycle_at for an arbitrarily-picked source (the "freshness
- * stamp that lies" this resolution exists to prevent).
+ * to pre-v0.18 global config.sync.* keys).
+ *
+ * Exported for dream.ts (#1869): a `gbrain dream --dir <path>` run whose
+ * path matches a registered source's local_path is a per-source cycle in
+ * everything but name, so dream derives the source id up front and passes
+ * it as opts.sourceId — landing the freshness stamp without changing
+ * runCycle's stamp/lock semantics for legacy global callers (the
+ * autopilot-global-maintenance handler runs GLOBAL_PHASES with a brainDir
+ * and MUST NOT stamp per-source freshness; see rejected PR #2549).
  */
-async function resolveSourceForDir(
+export async function resolveSourceForDir(
   engine: BrainEngine,
   brainDir: string | null,
 ): Promise<string | undefined> {
@@ -868,10 +873,10 @@ async function resolveSourceForDir(
   if (brainDir === null) return undefined;
   try {
     const rows = await engine.executeRaw<{ id: string }>(
-      `SELECT id FROM sources WHERE local_path = $1 LIMIT 2`,
+      `SELECT id FROM sources WHERE local_path = $1 LIMIT 1`,
       [brainDir],
     );
-    return rows.length === 1 ? rows[0]!.id : undefined;
+    return rows[0]?.id;
   } catch {
     // sources table might not exist on very old brains — fall through.
     return undefined;
@@ -2368,23 +2373,17 @@ export async function runCycle(
   }
 
   // v0.38 (codex r1 P0-5): persist per-source cycle completion timestamp
-  // when the cycle ran successfully against a resolvable source. Read by
-  // autopilot's per-source freshness gate next tick.
-  //
-  // #1993: keyed off `cycleSourceId` (opts.sourceId ?? the source resolved
-  // from brainDir) — the SAME id the cycle locked + scoped its phases to —
-  // NOT raw opts.sourceId. The autopilot's inline cycle sets brainDir but
-  // passes no explicit sourceId, so keying off opts.sourceId alone never
-  // advanced last_full_cycle_at and cycle_freshness stayed stale even while
-  // the autopilot cycled every interval. Skipped when:
-  //   - no source resolves (engine null, or no checkout AND no opts.sourceId)
+  // when the cycle ran successfully against an explicit source. Read by
+  // autopilot's per-source freshness gate next tick. Skipped when:
+  //   - opts.sourceId is unset (legacy callers — autopilot still here)
+  //   - engine is null (no-DB path)
   //   - status is 'failed' or 'skipped' (don't mark a non-run as fresh)
   //   - dryRun (writes are out of scope)
   //
   // Best-effort: a write failure does NOT change the CycleReport status.
   // The cost of writing the wrong timestamp post-failure is higher than
   // the cost of missing a successful write (next cycle will redo work).
-  if (cycleSourceId && engine && !dryRun && !aborted && (status === 'ok' || status === 'clean' || status === 'partial')) {
+  if (opts.sourceId && engine && !dryRun && !aborted && (status === 'ok' || status === 'clean' || status === 'partial')) {
     try {
       const nowIso = new Date().toISOString();
       // #2194 fix #3 (the cycle split): `last_source_cycle_at` is the NEW gate
@@ -2394,13 +2393,13 @@ export async function runCycle(
       // phases (those gate on autopilot.last_global_at), so writing it on a
       // source-only cycle does not re-introduce the freshness poisoning codex
       // flagged in the rejected skip-based design.
-      await engine.updateSourceConfig(cycleSourceId, {
+      await engine.updateSourceConfig(opts.sourceId, {
         last_source_cycle_at: nowIso,
         last_full_cycle_at: nowIso,
       });
     } catch (e) {
       // Best-effort; cycle already succeeded by the time we get here.
-      console.warn(`[cycle] failed to write last_source_cycle_at for source ${cycleSourceId}: ${e instanceof Error ? e.message : String(e)}`);
+      console.warn(`[cycle] failed to write last_source_cycle_at for source ${opts.sourceId}: ${e instanceof Error ? e.message : String(e)}`);
     }
   }
 

test/autopilot-fanout-wiring.test.ts

@@ -54,20 +54,6 @@ describe('autopilot.ts ↔ dispatchPerSource wiring', () => {
     expect(AUTOPILOT_SRC).toMatch(/lastFullCycleAt\s*=\s*Date\.now\(\)/);
   });
 
-  test('stale per-source cycle freshness is a shouldFullCycle input (#2060)', () => {
-    // Targeted mode (score 70–94, plan ≤3, est <300s) must not be able to
-    // starve per-source cycle dispatch: a stale source (per countStaleSources
-    // over listAllSources) forces the fanout path, and the sleep gate must
-    // not fire while stale sources exist. Without these terms, cycle
-    // freshness never advances for a brain that always lands in targeted mode.
-    expect(AUTOPILOT_SRC).toMatch(/countStaleSources/);
-    const fullCycleDeclIdx = AUTOPILOT_SRC.indexOf('const shouldFullCycle');
-    expect(fullCycleDeclIdx).toBeGreaterThan(-1);
-    const decl = AUTOPILOT_SRC.slice(fullCycleDeclIdx, fullCycleDeclIdx + 700);
-    expect(decl).toMatch(/staleCycleSources\s*>\s*0/);
-    expect(decl).toMatch(/const shouldSleep[^;]*staleCycleSources\s*===\s*0/);
-  });
-
   test('does NOT regress to the single-job dispatch on the full-cycle path', () => {
     // Pre-PR: the shouldFullCycle branch did:
     //   const job = await queue.add('autopilot-cycle', { repoPath }, {

test/autopilot-fanout.test.ts

@@ -14,7 +14,6 @@ import { describe, test, expect } from 'bun:test';
 import {
   readLastFullCycleAt,
   isSourceStale,
-  countStaleSources,
   selectSourcesForDispatch,
   resolveFanoutMax,
   dispatchPerSource,
@@ -75,23 +74,6 @@ describe('isSourceStale', () => {
   });
 });
 
-describe('countStaleSources (#2060 dispatch-decision input)', () => {
-  const NOW = Date.parse('2026-05-22T12:00:00.000Z');
-  test('counts never-cycled + past-floor sources, ignores fresh', () => {
-    const sources = [
-      src('never-cycled'), // stale (null)
-      src('old', new Date(NOW - 2 * 60 * 60_000).toISOString()), // stale (2h)
-      src('fresh', new Date(NOW - 30 * 60_000).toISOString()), // fresh (30min)
-    ];
-    expect(countStaleSources(sources, NOW)).toBe(2);
-  });
-  test('returns 0 for all-fresh and for empty list', () => {
-    const fresh = src('a', new Date(NOW - 10 * 60_000).toISOString());
-    expect(countStaleSources([fresh], NOW)).toBe(0);
-    expect(countStaleSources([], NOW)).toBe(0);
-  });
-});
-
 describe('selectSourcesForDispatch', () => {
   const NOW = Date.parse('2026-05-22T12:00:00.000Z');
   const fresh = (id: string, agoMin: number) =>

test/autopilot-shutdown-engine-close.test.ts

@@ -0,0 +1,63 @@
+/**
+ * #1872 — autopilot SIGTERM/SIGINT must close the engine before exit.
+ *
+ * On PGLite the cycle steps run INLINE in the autopilot process, so a hard
+ * `process.exit` mid-write (systemctl stop → SIGTERM) kills WASM Postgres
+ * with the WAL dirty and can corrupt the brain. Two exit paths must both
+ * close the engine:
+ *
+ *   - autopilot's own shutdown() (owns SIGINT + internal stops like
+ *     max_crashes / cycle-failure-cap), and
+ *   - process-cleanup's SIGTERM handler (installed at cli.ts module load,
+ *     which exits within its 3s cleanup deadline) — reached via the
+ *     registered 'autopilot-engine-close' cleanup callback.
+ *
+ * Because the shutdown path is deep inside `runAutopilot()` (a long-running
+ * daemon loop that ends in process.exit), a behavioral test would have to
+ * spawn + signal a real daemon. Following the established precedent
+ * (test/autopilot-supervisor-wiring.test.ts, test/autopilot-fanout-wiring.test.ts),
+ * these static-shape regressions pin the load-bearing wiring instead.
+ */
+import { describe, expect, it } from 'bun:test';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+const AUTOPILOT_SRC = readFileSync(
+  join(import.meta.dir, '..', 'src', 'commands', 'autopilot.ts'),
+  'utf8',
+);
+
+describe('autopilot.ts graceful engine shutdown (#1872)', () => {
+  it('registers an engine-close callback in the process-cleanup registry (SIGTERM path)', () => {
+    // process-cleanup owns SIGTERM (installed at cli.ts:10) and hard-exits
+    // after its cleanup pass; without this registration the engine is never
+    // closed on `systemctl stop`.
+    expect(AUTOPILOT_SRC).toContain(
+      "import { registerCleanup } from '../core/process-cleanup.ts';",
+    );
+    expect(AUTOPILOT_SRC).toContain(
+      "registerCleanup('autopilot-engine-close', closeEngine)",
+    );
+  });
+
+  it('closeEngine aborts the in-flight inline cycle then disconnects the engine', () => {
+    // Abort first (runCycle checks the signal between phases and threads it
+    // into phase sub-work), bounded drain, then disconnect.
+    expect(AUTOPILOT_SRC).toMatch(
+      /const closeEngine = async \(\) => \{[\s\S]{0,900}shutdownAbort\.abort\([\s\S]{0,900}engine\.disconnect\(\)/,
+    );
+  });
+
+  it('the inline runCycle call carries the shutdown abort signal and is tracked as in-flight', () => {
+    // PGLite / --inline path: the cycle runs in-process, so shutdown must be
+    // able to (a) signal it to wind down and (b) await it before closing.
+    expect(AUTOPILOT_SRC).toMatch(/signal:\s*shutdownAbort\.signal/);
+    expect(AUTOPILOT_SRC).toMatch(/inflightInlineCycle\s*=\s*cyclePromise/);
+  });
+
+  it('shutdown() awaits closeEngine() before process.exit(0) (SIGINT + internal-stop path)', () => {
+    expect(AUTOPILOT_SRC).toMatch(
+      /await closeEngine\(\);[\s\S]{0,400}process\.exit\(0\)/,
+    );
+  });
+});

test/cycle-last-full-cycle-at.test.ts

@@ -3,10 +3,8 @@
  * cycles. Closes codex round-1 P0-5 (write site for last_full_cycle_at
  * was unspecified pre-PR).
  *
- * Conditions for write (keyed off `cycleSourceId` = opts.sourceId ?? the
- * source resolved from brainDir, so the autopilot's inline cycle — brainDir
- * set, no explicit sourceId — also advances the timestamp, #1993):
- *   - a source resolves (explicit sourceId, or brainDir matches a source)
+ * Conditions for write:
+ *   - opts.sourceId is set (legacy callers without sourceId skip the write)
  *   - engine is non-null (no-DB path skips)
  *   - status is 'ok' | 'clean' | 'partial' (failed/skipped don't mark fresh)
  *   - dryRun is false
@@ -92,45 +90,17 @@ describe('runCycle last_full_cycle_at exit hook', () => {
     });
   });
 
-  test('no explicit sourceId but brainDir resolves a source → writes the resolved source timestamp', async () => {
+  test('legacy caller (no sourceId) does NOT write any source timestamp', async () => {
     await withEnv({ GBRAIN_HOME: gbrainHome }, async () => {
-      // The autopilot's inline cycle sets brainDir but passes no sourceId.
-      // runCycle resolves the source from brainDir (local_path match) into
-      // cycleSourceId and stamps last_full_cycle_at for it — otherwise
-      // cycle_freshness reports the brain stale even while the autopilot
-      // cycles every interval (#1993).
-      await seedSource('resolved-from-dir'); // local_path = brainDir
-      expect(await readLastFullCycleAt('resolved-from-dir')).toBeNull();
-
-      const t0 = Date.now();
-      const report = await runCycle(engine, {
-        brainDir,
-        phases: ['lint'],
-      });
-      expect(['ok', 'clean']).toContain(report.status);
-
-      const after = await readLastFullCycleAt('resolved-from-dir');
-      expect(after).not.toBeNull();
-      expect(new Date(after!).getTime()).toBeGreaterThanOrEqual(t0);
-    });
-  });
-
-  test('no sourceId and brainDir matches no source → does not write', async () => {
-    await withEnv({ GBRAIN_HOME: gbrainHome }, async () => {
-      // A source exists but its local_path does NOT match brainDir, so
-      // resolveSourceForDir returns undefined, cycleSourceId is undefined,
-      // and no per-source timestamp is written.
-      await engine.executeRaw(
-        `INSERT INTO sources (id, name, local_path, config, archived, created_at)
-         VALUES ('unmatched', 'unmatched', '/no/such/repo', '{}'::jsonb, false, NOW())
-         ON CONFLICT (id) DO UPDATE SET local_path = EXCLUDED.local_path`,
-        [],
-      );
+      await seedSource('default-like');
+      // No sourceId passed; should remain untouched.
       await runCycle(engine, {
         brainDir,
         phases: ['lint'],
       });
-      expect(await readLastFullCycleAt('unmatched')).toBeNull();
+      // No per-source write happens; default source's config stays empty.
+      const after = await readLastFullCycleAt('default-like');
+      expect(after).toBeNull();
     });
   });
 

test/dream-dir-source-stamp.test.ts

@@ -0,0 +1,99 @@
+/**
+ * #1869 — `gbrain dream --dir <path>` stamps cycle freshness when the path
+ * matches a registered source's local_path.
+ *
+ * Pre-fix, only `--source <id>` runs wrote last_source_cycle_at /
+ * last_full_cycle_at (runCycle's stamp gate reads opts.sourceId, and dream
+ * never derived one from --dir), so a path-scoped brain showed doctor's
+ * cycle_freshness as perpetually stale.
+ *
+ * The fix lives in dream.ts (derive the source id from the resolved brain
+ * dir via resolveSourceForDir), NOT in runCycle's stamp gate — a runCycle-
+ * wide change would make the autopilot-global-maintenance handler (global
+ * phases, brainDir set, no sourceId) falsely stamp per-source freshness
+ * (the #2194 poisoning class; see rejected PR #2549).
+ *
+ * Same real-PGLite/no-mocks discipline as test/dream.test.ts; same
+ * GBRAIN_HOME isolation as test/cycle-last-full-cycle-at.test.ts (the
+ * cycle's PGLite file lock lives under ~/.gbrain).
+ */
+import { describe, test, expect, beforeAll, afterAll, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { resetPgliteState } from './helpers/reset-pglite.ts';
+import { runDream } from '../src/commands/dream.ts';
+import { withEnv } from './helpers/with-env.ts';
+
+let engine: PGLiteEngine;
+let brainDir: string;
+let gbrainHome: string;
+
+beforeAll(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({});
+  await engine.initSchema();
+}, 60_000);
+
+afterAll(async () => {
+  await engine.disconnect();
+});
+
+beforeEach(async () => {
+  await resetPgliteState(engine);
+  brainDir = mkdtempSync(join(tmpdir(), 'gbrain-dream-stamp-'));
+  gbrainHome = mkdtempSync(join(tmpdir(), 'gbrain-dream-stamp-home-'));
+}, 60_000);
+
+afterEach(() => {
+  rmSync(brainDir, { recursive: true, force: true });
+  rmSync(gbrainHome, { recursive: true, force: true });
+});
+
+async function seedSource(id: string, archived = false): Promise<void> {
+  await engine.executeRaw(
+    `INSERT INTO sources (id, name, local_path, config, archived, created_at)
+     VALUES ($1, $2, $3, '{}'::jsonb, $4, NOW())`,
+    [id, id, brainDir, archived],
+  );
+}
+
+async function readLastFullCycleAt(sourceId: string): Promise<string | null> {
+  const rows = await engine.executeRaw<{ config: Record<string, unknown> | null }>(
+    `SELECT config FROM sources WHERE id = $1`,
+    [sourceId],
+  );
+  const raw = rows[0]?.config?.last_full_cycle_at;
+  return typeof raw === 'string' ? raw : null;
+}
+
+describe('gbrain dream --dir <path> freshness stamp (#1869)', () => {
+  test('--dir matching a source local_path stamps last_full_cycle_at', async () => {
+    await withEnv({ GBRAIN_HOME: gbrainHome }, async () => {
+      await seedSource('path-scoped');
+      expect(await readLastFullCycleAt('path-scoped')).toBeNull();
+
+      const report = await runDream(engine, ['--dir', brainDir, '--phase', 'lint', '--json']);
+      expect(report).toBeTruthy();
+      if (report) expect(['ok', 'clean']).toContain(report.status);
+
+      // Pre-fix this stays null forever: dream never passed a sourceId, so
+      // runCycle's stamp gate skipped the write.
+      expect(await readLastFullCycleAt('path-scoped')).not.toBeNull();
+    });
+  }, 60_000);
+
+  test('--dir matching an ARCHIVED source does not stamp it', async () => {
+    await withEnv({ GBRAIN_HOME: gbrainHome }, async () => {
+      await seedSource('mothballed', true);
+
+      const report = await runDream(engine, ['--dir', brainDir, '--phase', 'lint', '--json']);
+      expect(report).toBeTruthy();
+
+      // Stamping an archived source would mask data staleness when it is
+      // later restored (mirrors the explicit --source archived guard).
+      expect(await readLastFullCycleAt('mothballed')).toBeNull();
+    });
+  }, 60_000);
+});

test/dream.test.ts

@@ -562,12 +562,22 @@ describe('runDream — --source / --source-id (v0.41.13)', () => {
 
   // ─── Back-compat: bare `gbrain dream` does NOT write per-source stamp ─
 
-  test('gbrain dream (no --source) leaves all sources untouched (back-compat regression)', async () => {
-    await seedSource('alpha');
-    await seedSource('beta');
+  test('gbrain dream (no --source) stamps only the source whose local_path matches --dir (#1869)', async () => {
+    // Pre-#1869 this asserted NO source was ever stamped without an explicit
+    // --source — which is exactly the bug: a path-scoped `gbrain dream --dir`
+    // run never landed a freshness stamp and doctor's cycle_freshness stayed
+    // stale forever. New truth: the source whose local_path matches the
+    // resolved brain dir is derived and stamped; unrelated sources stay
+    // untouched (cross-source isolation).
+    await seedSource('alpha'); // local_path = repo → derived + stamped
+    await engine.executeRaw(
+      `INSERT INTO sources (id, name, local_path, config, archived, created_at)
+       VALUES ($1, $2, $3, '{}'::jsonb, false, NOW())`,
+      ['beta', 'beta', '/somewhere/else'],
+    );
     const report = await runDream(engine, ['--dir', repo, '--phase', 'lint', '--json']);
     expect(report).toBeTruthy();
-    expect(await readLastFullCycleAt('alpha')).toBeNull();
+    expect(await readLastFullCycleAt('alpha')).not.toBeNull();
     expect(await readLastFullCycleAt('beta')).toBeNull();
   }, 60_000);