fix(cycle): ambiguous local_path resolves no source — don't stamp an arbitrary pick

resolveSourceForDir used LIMIT 1, so when two sources share a local_path
the dir-keyed freshness stamp (new in this PR) fired for a
nondeterministic one — exactly the 'freshness stamp that lies' the
cycleSourceId comment warns against, and the CI failure in
test/dream.test.ts ('gbrain dream (no --source) leaves all sources
untouched'). Require exactly one match; ambiguous or no match falls back
to the pre-v0.18 behavior (undefined), same as before this PR for the
no-match case.

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

docs/tutorials/improving-skills-with-skillopt.md

@@ -233,14 +233,13 @@ keep it or `git checkout` to throw it away. Nothing is committed for you.
 
 **For a skill that ships with gbrain** (anything under the gbrain repo's own
 `skills/`): SkillOpt refuses to overwrite it by default and writes the winner to
-`skills/<name>/skillopt/proposed.md` instead (while keeping `best.md` as the
-optimizer's current-best pointer), so an optimization pass can never silently
-mutate a skill other people depend on. Two ways to handle that:
+`skills/<name>/skillopt/best.md` instead, so an optimization pass can never
+silently mutate a skill other people depend on. Two ways to handle that:
 
 ```bash
 # See the proposed improvement without touching SKILL.md (works for ANY skill):
 gbrain skillopt meeting-prep --split 1:1:1 --no-mutate
-# → writes skills/meeting-prep/skillopt/proposed.md, updates best.md, and prints the proposal path.
+# → writes skills/meeting-prep/skillopt/best.md (the proposed rewrite), prints its path. Copy what you want.
 
 # Actually rewrite a bundled skill (explicit opt-in + an independent held-out set):
 gbrain skillopt brain-ops --split 1:1:1 --allow-mutate-bundled \

src/commands/autopilot-fanout.ts

@@ -186,6 +186,18 @@ 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

@@ -901,13 +901,27 @@ 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;
+          score < 70 ||
+          staleCycleSources > 0;
 
-        const shouldSleep = score >= 95 && plan.length === 0 && minutesSinceLastFull < FULL_CYCLE_FLOOR_MIN;
+        const shouldSleep = score >= 95 && plan.length === 0 && minutesSinceLastFull < FULL_CYCLE_FLOOR_MIN && staleCycleSources === 0;
 
         if (shouldSleep) {
           if (jsonMode) {

src/core/cycle.ts

@@ -854,7 +854,10 @@ 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).
+ * 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).
  */
 async function resolveSourceForDir(
   engine: BrainEngine,
@@ -865,10 +868,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 1`,
+      `SELECT id FROM sources WHERE local_path = $1 LIMIT 2`,
       [brainDir],
     );
-    return rows[0]?.id;
+    return rows.length === 1 ? rows[0]!.id : undefined;
   } catch {
     // sources table might not exist on very old brains — fall through.
     return undefined;
@@ -2365,17 +2368,23 @@ export async function runCycle(
   }
 
   // v0.38 (codex r1 P0-5): persist per-source cycle completion timestamp
-  // 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)
+  // 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)
   //   - 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 (opts.sourceId && engine && !dryRun && !aborted && (status === 'ok' || status === 'clean' || status === 'partial')) {
+  if (cycleSourceId && 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
@@ -2385,13 +2394,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(opts.sourceId, {
+      await engine.updateSourceConfig(cycleSourceId, {
         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 ${opts.sourceId}: ${e instanceof Error ? e.message : String(e)}`);
+      console.warn(`[cycle] failed to write last_source_cycle_at for source ${cycleSourceId}: ${e instanceof Error ? e.message : String(e)}`);
     }
   }
 

src/core/skillopt/orchestrator.ts

@@ -93,13 +93,7 @@ import { resolveLrSchedule } from './lr-schedule.ts';
 import { preflight, formatPreflightReport } from './preflight.ts';
 import { isRejected, loadRejectedBuffer, makeRejectedEntry, saveRejectedBuffer } from './rejected-buffer.ts';
 import { runReflect, runOneShotRewrite, describeJudges } from './reflect.ts';
-import {
-  acceptCandidate,
-  proposedPath as proposedFilePath,
-  revertAllPending,
-  skillPath,
-  writeProposed,
-} from './version-store.ts';
+import { acceptCandidate, bestPath, revertAllPending, skillPath, writeProposed } from './version-store.ts';
 import { runValidationGate, scoreSkillOnTasks } from './validate-gate.ts';
 import { ROLLOUT_SUCCESS_THRESHOLD } from './types.ts';
 import type { SkillOptOpts, EditOp, RunReceipt, BenchmarkTask } from './types.ts';
@@ -708,9 +702,9 @@ async function runOptimizationLoop(
   // to the catch's assignment values only (it can't prove the async callback ran).
   const finalOutcome = outcome as 'accepted' | 'no_improvement' | 'aborted' | 'errored';
   if (!mutateDecision.mutate && finalOutcome === 'accepted') {
-    // writeProposed() emitted both the best pointer and the stable review
-    // artifact in the accept branch. SKILL.md remains untouched.
-    proposedPath = proposedFilePath(skillsDir, skillName);
+    // best.md was written by writeProposed() in the accept branch (no-mutate
+    // path); it doubles as proposed.md for human review. SKILL.md untouched.
+    proposedPath = bestPath(skillsDir, skillName);
   } else if (mutateDecision.mutate) {
     mutatedSkillFile = finalOutcome === 'accepted';
   }

src/core/skillopt/version-store.ts

@@ -23,7 +23,6 @@
  *
  *   history.json
  *   best.md
- *   proposed.md
  *   versions/
  *     v0001_e1_s1.md
  *     v0002_e1_s2.md
@@ -53,10 +52,6 @@ export function bestPath(skillsDir: string, skillName: string): string {
   return path.join(skilloptDir(skillsDir, skillName), 'best.md');
 }
 
-export function proposedPath(skillsDir: string, skillName: string): string {
-  return path.join(skilloptDir(skillsDir, skillName), 'proposed.md');
-}
-
 export function skillPath(skillsDir: string, skillName: string): string {
   return path.join(skillsDir, skillName, 'SKILL.md');
 }
@@ -176,18 +171,17 @@ export function acceptCandidate(input: AcceptInput): AcceptResult {
 }
 
 /**
- * Write the candidate to both `best.md` and `proposed.md` WITHOUT touching
- * SKILL.md or the history ledger. `best.md` remains the optimizer's current
- * best pointer; `proposed.md` is the stable human-review artifact promised by
- * `--no-mutate`. Returns the proposal path. Each write is atomic (.tmp + rename).
+ * Write the candidate to `best.md` (which doubles as `proposed.md`) WITHOUT
+ * touching SKILL.md or the history ledger. Used by the `--no-mutate` /
+ * bundled-without-allow paths: the optimizer found a better candidate but the
+ * caller opted out of in-place mutation, so we surface it for human review.
+ * Returns the path written. Atomic (.tmp + rename).
  */
 export function writeProposed(skillsDir: string, skillName: string, candidateText: string): string {
-  const best = bestPath(skillsDir, skillName);
-  const proposed = proposedPath(skillsDir, skillName);
-  fs.mkdirSync(path.dirname(best), { recursive: true });
-  atomicWrite(best, candidateText);
-  atomicWrite(proposed, candidateText);
-  return proposed;
+  const p = bestPath(skillsDir, skillName);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  atomicWrite(p, candidateText);
+  return p;
 }
 
 /**

test/autopilot-fanout-wiring.test.ts

@@ -54,6 +54,20 @@ 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,6 +14,7 @@ import { describe, test, expect } from 'bun:test';
 import {
   readLastFullCycleAt,
   isSourceStale,
+  countStaleSources,
   selectSourcesForDispatch,
   resolveFanoutMax,
   dispatchPerSource,
@@ -74,6 +75,23 @@ 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/cycle-last-full-cycle-at.test.ts

@@ -3,8 +3,10 @@
  * cycles. Closes codex round-1 P0-5 (write site for last_full_cycle_at
  * was unspecified pre-PR).
  *
- * Conditions for write:
- *   - opts.sourceId is set (legacy callers without sourceId skip the write)
+ * 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)
  *   - engine is non-null (no-DB path skips)
  *   - status is 'ok' | 'clean' | 'partial' (failed/skipped don't mark fresh)
  *   - dryRun is false
@@ -90,17 +92,45 @@ describe('runCycle last_full_cycle_at exit hook', () => {
     });
   });
 
-  test('legacy caller (no sourceId) does NOT write any source timestamp', async () => {
+  test('no explicit sourceId but brainDir resolves a source → writes the resolved source timestamp', async () => {
     await withEnv({ GBRAIN_HOME: gbrainHome }, async () => {
-      await seedSource('default-like');
-      // No sourceId passed; should remain untouched.
+      // 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 runCycle(engine, {
         brainDir,
         phases: ['lint'],
       });
-      // No per-source write happens; default source's config stays empty.
-      const after = await readLastFullCycleAt('default-like');
-      expect(after).toBeNull();
+      expect(await readLastFullCycleAt('unmatched')).toBeNull();
     });
   });
 

test/e2e/skillopt-loop.serial.test.ts

@@ -39,7 +39,6 @@ import { runSkillOpt } from '../../src/core/skillopt/orchestrator.ts';
 import {
   bestPath,
   loadHistory,
-  proposedPath,
   skillPath,
 } from '../../src/core/skillopt/version-store.ts';
 import { loadRejectedBuffer } from '../../src/core/skillopt/rejected-buffer.ts';
@@ -742,7 +741,7 @@ describe('skillopt T3 — F11 held-out gate, ablation opts, no-DB-pollution', ()
     } finally { fixture.cleanup(); }
   });
 
-  test('--no-mutate writes proposed.md and best.md, leaves SKILL.md untouched', async () => {
+  test('--no-mutate writes proposed.md (best.md), leaves SKILL.md untouched', async () => {
     const fixture = setupFixture(SKILL_PEOPLE_ONLY, CITATIONS_BENCHMARK);
     try {
       installStub({
@@ -754,9 +753,10 @@ describe('skillopt T3 — F11 held-out gate, ablation opts, no-DB-pollution', ()
           const result = await runOnce(fixture, { noMutate: true });
           expect(result.outcome).toBe('accepted');
           expect(result.mutatedSkillFile).toBe(false);
-          expect(result.proposedPath).toBe(proposedPath(fixture.skillsDir, SKILL));
+          expect(result.proposedPath).toBeDefined();
+          // proposed.md (best.md) exists and carries the improvement.
+          expect(fs.existsSync(result.proposedPath!)).toBe(true);
           expect(fs.readFileSync(result.proposedPath!, 'utf8')).toContain('## Citations');
-          expect(fs.readFileSync(bestPath(fixture.skillsDir, SKILL), 'utf8')).toContain('## Citations');
           // SKILL.md on disk is UNCHANGED (still People-only).
           const skill = fs.readFileSync(skillPath(fixture.skillsDir, SKILL), 'utf8');
           expect(skill).not.toContain('## Citations');

test/skillopt/version-store.test.ts

@@ -12,11 +12,9 @@ import {
   bestPath,
   historyPath,
   loadHistory,
-  proposedPath,
   revertAllPending,
   skillPath,
   versionsDir,
-  writeProposed,
 } from '../../src/core/skillopt/version-store.ts';
 
 let tmpDir: string;
@@ -81,19 +79,6 @@ describe('acceptCandidate (D8 two-phase commit)', () => {
   });
 });
 
-describe('writeProposed', () => {
-  test('writes distinct best and proposed artifacts without mutating SKILL.md (#2635)', () => {
-    const candidate = '---\nname: test\n---\nproposed body\n';
-
-    const written = writeProposed(tmpDir, SKILL, candidate);
-
-    expect(written).toBe(proposedPath(tmpDir, SKILL));
-    expect(fs.readFileSync(bestPath(tmpDir, SKILL), 'utf8')).toBe(candidate);
-    expect(fs.readFileSync(proposedPath(tmpDir, SKILL), 'utf8')).toBe(candidate);
-    expect(fs.readFileSync(skillPath(tmpDir, SKILL), 'utf8')).toContain('baseline body');
-  });
-});
-
 describe('revertAllPending (D8 crash recovery)', () => {
   test('no-op when no pending rows', () => {
     const reverted = revertAllPending(tmpDir, SKILL);