fix(cli): pre-set GBRAIN_EVAL_CAPTURE/SCRUB_PII env wins over DB stash

The #1475 stash unconditionally overwrote the env vars from the merged DB
plane, silently clobbering an operator's exported value — inverting the
env-above-config precedence the same code comment advertises. Unlike
GBRAIN_EMBEDDING_MULTIMODAL, these keys have no loadConfig() env mapping,
so file/env-wins in loadConfigWithEngine never covered them. Guard the
stash writes: DB fills the gap only when the env var is unset.

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

README.md

@@ -71,8 +71,8 @@ GBrain is designed to be installed and operated by an AI agent. The fastest path
 
 If you don't already have an AI agent platform running, start with one of these. Both are designed to read GBrain's install protocol and execute it:
 
-- **[OpenClaw](https://github.com/openclawagents/openclaw)** — deploy [AlphaClaw on Render](https://render.com/deploy?repo=https://github.com/chrysb/alphaclaw) (one click, 8GB+ RAM)
-- **[Hermes](https://github.com/openclawagents/hermes)** — deploy on [Railway](https://github.com/praveen-ks-2001/hermes-agent-template) (one click)
+- **[OpenClaw](https://github.com/openclaw/openclaw)** — deploy [AlphaClaw on Render](https://render.com/deploy?repo=https://github.com/chrysb/alphaclaw) (one click, 8GB+ RAM)
+- **[Hermes](https://github.com/NousResearch/hermes-agent)** — deploy on [Railway](https://github.com/praveen-ks-2001/hermes-agent-template) (one click)
 
 Then paste this into your agent:
 

docs/guides/skillpacks-as-scaffolding.md

@@ -131,7 +131,9 @@ into gbrain so other clients can scaffold it. Default behavior:
   `~/.gbrain/harvest-private-patterns.txt` plus built-in defaults
   (canonical private fork name, common email regex, Slack channel pattern). Any
   match → rollback (delete the harvested files) and exit non-zero.
-- `openclaw.plugin.json` updated with the new slug, sorted.
+- `openclaw.plugin.json` updated with the new slug, sorted. Harvest must preserve
+  the top-level OpenClaw-native plugin fields (`id`, `configSchema`, `contracts`)
+  because OpenClaw validates those before it can install the package.
 - `--no-lint` bypasses the linter (after a manual editorial scrub).
 
 Use the `skillpack-harvest` skill (its companion editorial workflow)

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

@@ -233,13 +233,14 @@ 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/best.md` instead, so an optimization pass can never
-silently mutate a skill other people depend on. Two ways to handle that:
+`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:
 
 ```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/best.md (the proposed rewrite), prints its path. Copy what you want.
+# → writes skills/meeting-prep/skillopt/proposed.md, updates best.md, and prints the proposal path.
 
 # Actually rewrite a bundled skill (explicit opt-in + an independent held-out set):
 gbrain skillopt brain-ops --split 1:1:1 --allow-mutate-bundled \

llms-full.txt

@@ -1565,8 +1565,8 @@ GBrain is designed to be installed and operated by an AI agent. The fastest path
 
 If you don't already have an AI agent platform running, start with one of these. Both are designed to read GBrain's install protocol and execute it:
 
-- **[OpenClaw](https://github.com/openclawagents/openclaw)** — deploy [AlphaClaw on Render](https://render.com/deploy?repo=https://github.com/chrysb/alphaclaw) (one click, 8GB+ RAM)
-- **[Hermes](https://github.com/openclawagents/hermes)** — deploy on [Railway](https://github.com/praveen-ks-2001/hermes-agent-template) (one click)
+- **[OpenClaw](https://github.com/openclaw/openclaw)** — deploy [AlphaClaw on Render](https://render.com/deploy?repo=https://github.com/chrysb/alphaclaw) (one click, 8GB+ RAM)
+- **[Hermes](https://github.com/NousResearch/hermes-agent)** — deploy on [Railway](https://github.com/praveen-ks-2001/hermes-agent-template) (one click)
 
 Then paste this into your agent:
 

openclaw.plugin.json

@@ -1,4 +1,5 @@
 {
+  "id": "gbrain-context-engine",
   "name": "gbrain",
   "version": "0.32.3.0",
   "description": "Personal knowledge brain with Postgres + pgvector hybrid search",

skills/skillpack-harvest/SKILL.md

@@ -266,4 +266,5 @@ editorial pass.
   (e.g. `src/commands/<slug>.ts` if the host SKILL.md declares it
   in frontmatter)
 - gbrain's `openclaw.plugin.json` — adds the slug to `skills:`
-  array, sorted alphabetically
+  array, sorted alphabetically, without removing OpenClaw-native plugin fields
+  like `id`, `configSchema`, or `contracts`

skills/testing/SKILL.md

@@ -57,6 +57,8 @@ This mode guarantees:
 - `skills/manifest.json` lists every skill directory
 - `skills/RESOLVER.md` references every skill in the manifest
 - `openclaw.plugin.json` `skills[]` round-trips with both
+- `openclaw.plugin.json` keeps OpenClaw install-required native plugin fields
+  (`id`, object `configSchema`, and `contracts.contextEngines` when applicable)
 - No MECE violations (duplicate triggers across skills)
 
 ### Phases
@@ -72,7 +74,7 @@ This mode guarantees:
 ### Automation
 
 ```bash
-bun test test/skills-conformance.test.ts test/resolver.test.ts
+bun test test/skills-conformance.test.ts test/resolver.test.ts test/openclaw-plugin-manifest.test.ts
 ```
 
 The CI-gated check is the package.json `test` script.

src/cli.ts

@@ -54,7 +54,7 @@ export function bigintToStringReplacer(_key: string, value: unknown): unknown {
 }
 
 // CLI-only commands that bypass the operation layer
-export const CLI_ONLY = new Set(['init', 'reinit-pglite', 'upgrade', 'post-upgrade', 'check-update', 'integrations', 'publish', 'check-backlinks', 'lint', 'report', 'import', 'export', 'files', 'embed', 'serve', 'call', 'config', 'doctor', 'migrate', 'eval', 'sync', 'extract', 'extract-conversation-facts', 'enrich', 'features', 'autopilot', 'graph-query', 'jobs', 'agent', 'apply-migrations', 'skillpack-check', 'skillpack', 'resolvers', 'integrity', 'repair-jsonb', 'orphans', 'sources', 'mounts', 'dream', 'check-resolvable', 'routing-eval', 'skillify', 'smoke-test', 'providers', 'storage', 'repos', 'code-def', 'code-refs', 'reindex', 'reindex-code', 'reindex-frontmatter', 'code-callers', 'code-callees', 'reconcile-links', 'frontmatter', 'auth', 'friction', 'claw-test', 'book-mirror', 'takes', 'think', 'salience', 'anomalies', 'calibration', 'transcripts', 'models', 'remote', 'recall', 'forget', 'edges-backfill', 'cache', 'ze-switch', 'founder', 'brainstorm', 'lsd', 'schema', 'capture', 'onboard', 'conversation-parser', 'status', 'connect', 'skillopt', 'quarantine', 'self-upgrade', 'advisor', 'watch', 'reindex-search-vector']);
+export const CLI_ONLY = new Set(['init', 'reinit-pglite', 'upgrade', 'post-upgrade', 'check-update', 'integrations', 'publish', 'check-backlinks', 'lint', 'report', 'import', 'export', 'files', 'embed', 'serve', 'call', 'config', 'doctor', 'migrate', 'eval', 'bench', 'sync', 'extract', 'extract-conversation-facts', 'enrich', 'features', 'autopilot', 'graph-query', 'jobs', 'agent', 'apply-migrations', 'skillpack-check', 'skillpack', 'resolvers', 'integrity', 'repair-jsonb', 'orphans', 'maintain', 'sources', 'mounts', 'dream', 'check-resolvable', 'routing-eval', 'skillify', 'smoke-test', 'providers', 'storage', 'repos', 'code-def', 'code-refs', 'reindex', 'reindex-code', 'reindex-frontmatter', 'code-callers', 'code-callees', 'reconcile-links', 'frontmatter', 'auth', 'friction', 'claw-test', 'book-mirror', 'takes', 'think', 'salience', 'anomalies', 'calibration', 'transcripts', 'models', 'remote', 'recall', 'forget', 'edges-backfill', 'cache', 'ze-switch', 'founder', 'brainstorm', 'lsd', 'schema', 'capture', 'onboard', 'conversation-parser', 'status', 'connect', 'skillopt', 'quarantine', 'self-upgrade', 'advisor', 'watch', 'reindex-search-vector']);
 // CLI-only commands whose handlers print their own --help text. These are
 // excluded from the generic short-circuit so detailed per-command and
 // per-subcommand usage stays reachable.
@@ -78,6 +78,8 @@ const CLI_ONLY_SELF_HELP = new Set([
   'capture',
   // v0.42 self-upgrade ships its own usage (flags + the agent-skill story).
   'self-upgrade',
+  // maintain (#3015) prints its own usage block (modes + not-auto-applied list).
+  'maintain',
   // v0.43 (#2095): watch ships WATCH_HELP (flags + the stdin-turn protocol).
   'watch',
   // v0.37 fix wave (Lane D.4 + CDX2-12): sync's --no-embed flag was
@@ -104,6 +106,9 @@ const CLI_ONLY_SELF_HELP = new Set([
   // `gbrain connect --help` prints its own usage (flags + examples) from
   // runConnect; route around the generic one-line short-circuit.
   'connect',
+  // #1474: bench-publish ships its own detailed HELP (flags, exit codes,
+  // the export → publish → gate loop). Route around the generic stub.
+  'bench',
 ]);
 
 // v114 (#1941): alias -> operation lookup, kept separate from `cliOps` so
@@ -1427,6 +1432,29 @@ async function handleCliOnly(command: string, args: string[]) {
     return;
   }
 
+  // #1474: `gbrain bench publish` is pure file I/O (reads a captured
+  // eval-candidates NDJSON from `gbrain eval export`, writes a baseline
+  // NDJSON). No DB access; bypass connectEngine entirely so the documented
+  // export → publish → gate loop works on machines without a brain.
+  // The v0.41.1 wave shipped bench-publish.ts + docs/eval-bench.md but this
+  // dispatcher case was never added, so the command hit 'Unknown command'.
+  if (command === 'bench') {
+    if (args[0] === 'publish') {
+      const { runBenchPublish } = await import('./commands/bench-publish.ts');
+      await runBenchPublish(args.slice(1));
+      return;
+    }
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+      const { runBenchPublish } = await import('./commands/bench-publish.ts');
+      await runBenchPublish(['--help']);
+      return;
+    }
+    console.error(`Unknown bench subcommand: ${args[0]}`);
+    console.error('Usage: gbrain bench publish --from <captured.ndjson> --to <baseline.ndjson> [flags]');
+    console.error('  See docs/eval-bench.md for the full loop: eval export → bench publish → eval gate');
+    process.exit(2);
+  }
+
   // v0.42.x (#2390): `gbrain eval chronicle` is deterministic — brings its own
   // in-memory PGLite, no DB/gateway. CI fixture gate runs anywhere.
   if (command === 'eval' && args[0] === 'chronicle') {
@@ -1757,6 +1785,11 @@ async function handleCliOnly(command: string, args: string[]) {
         await runOrphans(engine, args);
         break;
       }
+      case 'maintain': {
+        const { runMaintain } = await import('./commands/maintain.ts');
+        await runMaintain(engine, args);
+        break;
+      }
       // v0.32.7 CJK wave — post-upgrade markdown re-chunk sweep.
       // v0.36 Phase 3 wave — `gbrain reindex --multimodal` re-embeds content_chunks
       // into the unified Voyage multimodal-3 column.
@@ -2217,6 +2250,22 @@ async function connectEngine(opts?: { probeOnly?: boolean }): Promise<BrainEngin
       if (merged.embedding_image_ocr_model !== undefined) {
         process.env.GBRAIN_EMBEDDING_IMAGE_OCR_MODEL = merged.embedding_image_ocr_model;
       }
+      // #1475: stash the merged eval.* flags the same way. The capture gate
+      // (isEvalCaptureEnabled / isEvalScrubEnabled) runs against ctx.config,
+      // which is built from the sync file-plane loadConfig() in both the CLI
+      // op path and MCP dispatch — it never sees the DB plane directly. The
+      // gates consult this stash when the file plane is silent, so
+      // `gbrain config set eval.capture true` actually turns capture on.
+      // A pre-set env value wins over the DB plane (env-above-config, the
+      // incident escape hatch) — unlike GBRAIN_EMBEDDING_MULTIMODAL these
+      // keys have no loadConfig() env mapping, so without this guard the
+      // DB stash would silently clobber an operator's export.
+      if (process.env.GBRAIN_EVAL_CAPTURE === undefined && merged.eval?.capture !== undefined) {
+        process.env.GBRAIN_EVAL_CAPTURE = String(merged.eval.capture);
+      }
+      if (process.env.GBRAIN_EVAL_SCRUB_PII === undefined && merged.eval?.scrub_pii !== undefined) {
+        process.env.GBRAIN_EVAL_SCRUB_PII = String(merged.eval.scrub_pii);
+      }
       // Always re-configure with merged values when DB merge succeeded. The
       // trigger used to be field-name-gated (only when embedding_multimodal_model
       // was set); that coupled the gate to the field set and would silently

src/commands/embed.ts

@@ -581,7 +581,7 @@ async function embedPage(
   for (let j = 0; j < toEmbed.length; j++) {
     embeddingMap.set(toEmbed[j].chunk_index, embeddings[j]);
   }
-  const updated: ChunkInput[] = chunks.map(c => ({
+  const updated: ChunkInput[] = chunks.map(c => preserveCodeMetadata(c, {
     chunk_index: c.chunk_index,
     chunk_text: c.chunk_text,
     chunk_source: c.chunk_source,
@@ -605,6 +605,31 @@ async function embedPage(
   slog(`${slug}: embedded ${toEmbed.length} chunks`);
 }
 
+/**
+ * Carry code-chunk metadata (language, symbol_name, symbol_type, line range,
+ * parent scope, doc comment, qualified name) from a loaded Chunk back into a
+ * ChunkInput destined for upsertChunks.
+ *
+ * Issue #769: every re-embed used to strip these fields, and upsertChunks
+ * overwrites (does not COALESCE) the metadata columns from EXCLUDED, so
+ * each pass clobbered code-def's primary index to NULL. Pulling the
+ * preservation into one helper keeps the three re-embed call sites
+ * (embedPage, embedAll non-stale, embedAllStale) in lock-step.
+ */
+function preserveCodeMetadata(loaded: any, base: ChunkInput): ChunkInput {
+  return {
+    ...base,
+    language: loaded.language ?? undefined,
+    symbol_name: loaded.symbol_name ?? undefined,
+    symbol_type: loaded.symbol_type ?? undefined,
+    start_line: loaded.start_line ?? undefined,
+    end_line: loaded.end_line ?? undefined,
+    parent_symbol_path: loaded.parent_symbol_path ?? undefined,
+    doc_comment: loaded.doc_comment ?? undefined,
+    symbol_name_qualified: loaded.symbol_name_qualified ?? undefined,
+  };
+}
+
 async function embedAll(
   engine: BrainEngine,
   staleOnly: boolean,
@@ -717,8 +742,10 @@ async function embedAll(
       for (let j = 0; j < toEmbed.length; j++) {
         embeddingMap.set(toEmbed[j].chunk_index, embeddings[j]);
       }
-      // Preserve ALL chunks, only update embeddings for stale ones
-      const updated: ChunkInput[] = chunks.map(c => ({
+      // Preserve ALL chunks, only update embeddings for stale ones.
+      // preserveCodeMetadata threads code-chunk metadata (#769) so re-embed
+      // doesn't clobber language/symbol_name/symbol_type to NULL.
+      const updated: ChunkInput[] = chunks.map(c => preserveCodeMetadata(c, {
         chunk_index: c.chunk_index,
         chunk_text: c.chunk_text,
         chunk_source: c.chunk_source,
@@ -1012,7 +1039,10 @@ async function embedAllStale(
           for (let j = 0; j < stale.length; j++) {
             staleIdxToEmbedding.set(stale[j].chunk_index, embeddings[j]);
           }
-          const merged: ChunkInput[] = existing.map(c => ({
+          // preserveCodeMetadata threads code-chunk metadata (#769) so the
+          // autopilot --stale path doesn't clobber language/symbol_name/etc
+          // to NULL on every cycle.
+          const merged: ChunkInput[] = existing.map(c => preserveCodeMetadata(c, {
             chunk_index: c.chunk_index,
             chunk_text: c.chunk_text,
             chunk_source: c.chunk_source,

src/commands/extract.ts

@@ -1651,7 +1651,7 @@ async function extractTimelineFromDB(
  * make re-extraction idempotent). EVERY processed page is stamped, including
  * zero-link pages — they WERE processed.
  */
-async function extractStaleFromDB(
+export async function extractStaleFromDB(
   engine: BrainEngine,
   opts: {
     dryRun: boolean;

src/commands/jobs.ts

@@ -2059,8 +2059,6 @@ export async function registerBuiltinHandlers(
         sourceId,
         windowSeconds,
         brainDir: repoPath,
-        // #2750: worker cancel/timeout/lock-loss propagates into the drain.
-        abortSignal: job.signal,
       });
     } catch (e) {
       if (e instanceof LockUnavailableError) {

src/commands/maintain.ts

@@ -0,0 +1,224 @@
+/**
+ * gbrain maintain — conservative self-healing maintenance.
+ *
+ * This command automates the safe parts of the operator runbook:
+ *   - stale link/timeline extraction
+ *   - stale per-source dream cycles when doctor reports cycle_freshness
+ *
+ * It deliberately does NOT mutate source files, apply schema-pack upgrades, or
+ * invent semantic hub links. Those need review or a separate command with an
+ * auditable proposal surface.
+ */
+
+import { existsSync } from 'fs';
+import type { BrainEngine } from '../core/engine.ts';
+import type { BrainHealth } from '../core/types.ts';
+import { buildChecks, computeDoctorReport, type DoctorReport, type Check } from './doctor.ts';
+import { extractStaleFromDB } from './extract.ts';
+import { runCycle, type CycleReport } from '../core/cycle.ts';
+
+type ActionStatus = 'ok' | 'would_apply' | 'applied' | 'blocked' | 'skipped';
+
+export interface MaintenanceAction {
+  name: string;
+  status: ActionStatus;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface MaintainOptions {
+  json: boolean;
+  safe: boolean;
+  dryRun: boolean;
+  help: boolean;
+}
+
+export interface MaintainReport {
+  mode: 'dry-run' | 'safe';
+  before: {
+    health: BrainHealth;
+    doctor: DoctorReport;
+  };
+  actions: MaintenanceAction[];
+  after: {
+    health: BrainHealth;
+    doctor: DoctorReport;
+  };
+}
+
+export function parseMaintainArgs(args: string[]): MaintainOptions {
+  const safe = args.includes('--safe');
+  return {
+    json: args.includes('--json'),
+    safe,
+    dryRun: args.includes('--dry-run') || !safe,
+    help: args.includes('--help') || args.includes('-h'),
+  };
+}
+
+export function extractCycleFreshnessSourceIds(checks: Check[]): string[] {
+  const ids = new Set<string>();
+  for (const check of checks) {
+    if (check.name !== 'cycle_freshness' || check.status === 'ok') continue;
+    const re = /Source '([^']+)' last cycled/g;
+    for (const match of check.message.matchAll(re)) {
+      const id = match[1]?.trim();
+      if (id) ids.add(id);
+    }
+  }
+  return [...ids].sort();
+}
+
+async function buildDoctorReport(engine: BrainEngine): Promise<DoctorReport> {
+  const checks = await buildChecks(engine, ['--json', '--scope=brain']);
+  return computeDoctorReport(checks);
+}
+
+async function runStaleExtraction(
+  engine: BrainEngine,
+  beforeHealth: BrainHealth,
+  dryRun: boolean,
+): Promise<MaintenanceAction> {
+  if (beforeHealth.stale_pages <= 0) {
+    return { name: 'extract_stale', status: 'ok', message: 'No stale pages.' };
+  }
+
+  if (dryRun) {
+    return {
+      name: 'extract_stale',
+      status: 'would_apply',
+      message: `Would run DB-backed stale extraction for ${beforeHealth.stale_pages} page(s).`,
+      details: { stale_pages: beforeHealth.stale_pages },
+    };
+  }
+
+  const result = await extractStaleFromDB(engine, {
+    dryRun: false,
+    jsonMode: false,
+    includeFrontmatter: false,
+    catchUp: false,
+  });
+
+  return {
+    name: 'extract_stale',
+    status: 'applied',
+    message: `Processed ${result.pagesProcessed} stale page(s); ${result.staleRemaining} remain.`,
+    details: {
+      links_created: result.linksCreated,
+      timeline_created: result.timelineCreated,
+      pages_processed: result.pagesProcessed,
+      stale_remaining: result.staleRemaining,
+    },
+  };
+}
+
+async function runCycleFreshnessMaintenance(
+  engine: BrainEngine,
+  beforeDoctor: DoctorReport,
+  dryRun: boolean,
+): Promise<MaintenanceAction[]> {
+  const sourceIds = extractCycleFreshnessSourceIds(beforeDoctor.checks);
+  if (sourceIds.length === 0) {
+    return [{ name: 'cycle_freshness', status: 'ok', message: 'All sources cycled recently.' }];
+  }
+
+  if (dryRun) {
+    return sourceIds.map((sourceId) => ({
+      name: 'cycle_freshness',
+      status: 'would_apply',
+      message: `Would run source-scoped dream cycle for ${sourceId}.`,
+      details: { source_id: sourceId },
+    }));
+  }
+
+  const sources = await engine.listAllSources();
+  const actions: MaintenanceAction[] = [];
+
+  for (const sourceId of sourceIds) {
+    const source = sources.find((s) => s.id === sourceId);
+    const localPath = source?.local_path ?? null;
+    const brainDir = localPath && existsSync(localPath) ? localPath : null;
+    const report: CycleReport = await runCycle(engine, {
+      brainDir,
+      dryRun: false,
+      pull: false,
+      sourceId,
+    });
+    actions.push({
+      name: 'cycle_freshness',
+      status: report.status === 'failed' ? 'blocked' : 'applied',
+      message: `Ran source-scoped dream cycle for ${sourceId}: ${report.status}.`,
+      details: {
+        source_id: sourceId,
+        brain_dir: brainDir,
+        cycle_status: report.status,
+        phases: report.phases.map((p) => ({ phase: p.phase, status: p.status })),
+      },
+    });
+  }
+
+  return actions;
+}
+
+export async function runMaintain(engine: BrainEngine, args: string[]): Promise<MaintainReport | void> {
+  const opts = parseMaintainArgs(args);
+  if (opts.help) {
+    console.log(`Usage: gbrain maintain [--safe] [--dry-run] [--json]
+
+Conservative self-healing maintenance.
+
+Modes:
+  --dry-run   Preview safe actions without writes. Default when --safe is absent.
+  --safe      Apply safe actions: stale extraction and source cycle freshness.
+  --json      Emit a structured before/action/after report.
+
+Not auto-applied:
+  source-file frontmatter fixes, schema-pack upgrades, atom-pack changes,
+  semantic hub-link guesses, and destructive cleanup.
+`);
+    return;
+  }
+
+  const beforeHealth = await engine.getHealth();
+  const beforeDoctor = await buildDoctorReport(engine);
+  const actions: MaintenanceAction[] = [];
+
+  actions.push(await runStaleExtraction(engine, beforeHealth, opts.dryRun));
+  actions.push(...await runCycleFreshnessMaintenance(engine, beforeDoctor, opts.dryRun));
+
+  const afterHealth = await engine.getHealth();
+  const afterDoctor = await buildDoctorReport(engine);
+  const report: MaintainReport = {
+    mode: opts.dryRun ? 'dry-run' : 'safe',
+    before: { health: beforeHealth, doctor: beforeDoctor },
+    actions,
+    after: { health: afterHealth, doctor: afterDoctor },
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printMaintainReport(report);
+  }
+  return report;
+}
+
+function printMaintainReport(report: MaintainReport): void {
+  console.log(`GBrain maintain (${report.mode})`);
+  console.log(
+    `Before: brain_score=${Math.round(report.before.health.brain_score)}/100 ` +
+    `stale=${report.before.health.stale_pages} islands=${report.before.health.orphan_pages} ` +
+    `doctor=${report.before.doctor.status}`,
+  );
+  for (const action of report.actions) {
+    console.log(`  ${action.status}: ${action.name} — ${action.message}`);
+  }
+  console.log(
+    `After:  brain_score=${Math.round(report.after.health.brain_score)}/100 ` +
+    `stale=${report.after.health.stale_pages} islands=${report.after.health.orphan_pages} ` +
+    `doctor=${report.after.doctor.status}`,
+  );
+  if (report.mode === 'dry-run') {
+    console.log('Run `gbrain maintain --safe` to apply safe actions.');
+  }
+}

src/commands/orphans.ts

@@ -15,6 +15,11 @@
 import type { BrainEngine } from '../core/engine.ts';
 import { createProgress, startHeartbeat } from '../core/progress.ts';
 import { getCliOptions, cliOptsToProgressOptions } from '../core/cli-options.ts';
+import {
+  shouldExcludeFromOrphanReporting,
+  loadOrphanPolicyOverrides,
+  type OrphanPolicyOverrides,
+} from '../core/orphan-policy.ts';
 
 // --- Types ---
 
@@ -32,65 +37,14 @@ export interface OrphanResult {
   excluded: number;
 }
 
-// --- Filter constants ---
-
-/** Slug suffixes that are always auto-generated root files */
-const AUTO_SUFFIX_PATTERNS = ['/_index', '/log'];
-
-/** Page slugs that are pseudo-pages by convention */
-const PSEUDO_SLUGS = new Set(['_atlas', '_index', '_stats', '_orphans', '_scratch', 'claude']);
-
-/** Slug segment that marks raw sources */
-const RAW_SEGMENT = '/raw/';
-
-/** Slug prefixes where no inbound links is expected */
-const DENY_PREFIXES = [
-  'output/',
-  'dashboards/',
-  'scripts/',
-  'templates/',
-  'openclaw/config/',
-];
-
-/** First slug segments where no inbound links is expected */
-const FIRST_SEGMENT_EXCLUSIONS = new Set([
-  'scratch',
-  'thoughts',
-  'catalog',
-  'entities',
-  'raw',
-  'atoms',
-  'skills',
-]);
-
 // --- Filter logic ---
 
 /**
  * Returns true if a slug should be excluded from orphan reporting by default.
  * These are pages where having no inbound links is expected / not a content problem.
  */
-export function shouldExclude(slug: string): boolean {
-  // Pseudo-pages (exact match)
-  if (PSEUDO_SLUGS.has(slug)) return true;
-
-  // Auto-generated suffix patterns
-  for (const suffix of AUTO_SUFFIX_PATTERNS) {
-    if (slug.endsWith(suffix)) return true;
-  }
-
-  // Raw source slugs
-  if (slug.includes(RAW_SEGMENT)) return true;
-
-  // Deny-prefix slugs
-  for (const prefix of DENY_PREFIXES) {
-    if (slug.startsWith(prefix)) return true;
-  }
-
-  // First-segment exclusions
-  const firstSegment = slug.split('/')[0];
-  if (FIRST_SEGMENT_EXCLUSIONS.has(firstSegment)) return true;
-
-  return false;
+export function shouldExclude(slug: string, overrides?: OrphanPolicyOverrides): boolean {
+  return shouldExcludeFromOrphanReporting(slug, overrides);
 }
 
 /**
@@ -156,6 +110,7 @@ export async function findOrphans(
   let allOrphans: { slug: string; title: string; domain: string | null }[];
   let total: number;
   let excludedAll: number;
+  const overrides = includePseudo ? undefined : await loadOrphanPolicyOverrides(engine);
   try {
     allOrphans = await engine.findOrphanPages(
       sourceIds ? { sourceIds } : sourceId ? { sourceId } : undefined,
@@ -184,7 +139,7 @@ export async function findOrphans(
     total = liveRows.length;
     excludedAll = includePseudo
       ? 0
-      : liveRows.reduce((n, r) => n + (shouldExclude(r.slug) ? 1 : 0), 0);
+      : liveRows.reduce((n, r) => n + (shouldExclude(r.slug, overrides) ? 1 : 0), 0);
   } finally {
     stopHb();
     progress.finish();
@@ -192,7 +147,7 @@ export async function findOrphans(
 
   const filtered = includePseudo
     ? allOrphans
-    : allOrphans.filter(row => !shouldExclude(row.slug));
+    : allOrphans.filter(row => !shouldExclude(row.slug, overrides));
 
   const orphans: OrphanPage[] = filtered.map(row => ({
     slug: row.slug,

src/core/config.ts

@@ -816,6 +816,25 @@ export async function loadConfigWithEngine(
     merged.dream = mergedDream;
   }
 
+  // #1475: eval.* DB-plane merge. `gbrain config set eval.capture true`
+  // writes the DB plane (both keys are in KNOWN_CONFIG_KEYS, so `set`
+  // accepts them silently), but the capture gate (isEvalCaptureEnabled)
+  // reads the merged config. Without this merge the DB value was written
+  // and never read — capture only fired via GBRAIN_CONTRIBUTOR_MODE=1.
+  // Sparse per-key merge: file/env wins per key, DB fills the gaps.
+  const dbEvalCapture = await dbBool('eval.capture');
+  const dbEvalScrub = await dbBool('eval.scrub_pii');
+  const mergedEval: NonNullable<GBrainConfig['eval']> = { ...(merged.eval ?? {}) };
+  if (mergedEval.capture === undefined && dbEvalCapture !== undefined) {
+    mergedEval.capture = dbEvalCapture;
+  }
+  if (mergedEval.scrub_pii === undefined && dbEvalScrub !== undefined) {
+    mergedEval.scrub_pii = dbEvalScrub;
+  }
+  if (Object.keys(mergedEval).length > 0) {
+    merged.eval = mergedEval;
+  }
+
   return merged;
 }
 

src/core/contextual-retrieval-service.ts

@@ -54,6 +54,7 @@ import {
 import {
   generatePerChunkSynopsis,
   SYNOPSIS_PROMPT_VERSION,
+  SYNOPSIS_DOC_MAX_CHARS,
   type GeneratePerChunkSynopsisResult,
 } from './page-summary.ts';
 import {
@@ -103,8 +104,17 @@ function getEmbeddingModelTag(): string {
 export function computeCorpusGeneration(args: {
   crMode: CRMode;
   haikuModel: string;
+  /**
+   * Resolved `SYNOPSIS_DOC_MAX_CHARS` for per_chunk_synopsis runs. When
+   * present, folded into the hash so changes to
+   * `GBRAIN_SYNOPSIS_DOC_MAX_CHARS` invalidate the prior cache cleanly.
+   * Omit for `crMode !== 'per_chunk_synopsis'` — title / none modes
+   * don't consult the cap and the field stays out of the hash for
+   * back-compat with pre-cap embeddings.
+   */
+  synopsisDocMaxChars?: number;
 }): string {
-  return createHash('sha256')
+  const h = createHash('sha256')
     .update(args.crMode)
     .update('|')
     .update(String(SYNOPSIS_PROMPT_VERSION))
@@ -113,9 +123,11 @@ export function computeCorpusGeneration(args: {
     .update('|')
     .update(String(TITLE_WRAPPER_VERSION))
     .update('|')
-    .update(getEmbeddingModelTag())
-    .digest('hex')
-    .slice(0, 16);
+    .update(getEmbeddingModelTag());
+  if (args.synopsisDocMaxChars !== undefined) {
+    h.update('|doc_cap=').update(String(args.synopsisDocMaxChars));
+  }
+  return h.digest('hex').slice(0, 16);
 }
 
 /**
@@ -253,7 +265,11 @@ export async function reembedPageWithContextualRetrieval(
       args.pageSlug,
       args.sourceId,
       resolution.mode,
-      computeCorpusGeneration({ crMode: resolution.mode, haikuModel: args.haikuModel ?? DEFAULT_HAIKU_MODEL }),
+      computeCorpusGeneration({
+        crMode: resolution.mode,
+        haikuModel: args.haikuModel ?? DEFAULT_HAIKU_MODEL,
+        synopsisDocMaxChars: resolution.mode === 'per_chunk_synopsis' ? SYNOPSIS_DOC_MAX_CHARS : undefined,
+      }),
     );
     return { kind: 'skipped', reason: 'no_chunks' };
   }
@@ -282,6 +298,7 @@ export async function reembedPageWithContextualRetrieval(
       const corpus_generation = computeCorpusGeneration({
         crMode: attemptMode,
         haikuModel,
+        synopsisDocMaxChars: attemptMode === 'per_chunk_synopsis' ? SYNOPSIS_DOC_MAX_CHARS : undefined,
       });
 
       // ── PHASE 2: single DB transaction ───────────────────────────

src/core/cycle/extract-atoms-drain.ts

@@ -23,10 +23,6 @@
  */
 
 import type { BrainEngine } from '../engine.ts';
-import { anySignal } from '../abort-check.ts';
-
-/** Fresh cleanup budget for the lock release after the window signal fires. */
-const LOCK_RELEASE_GRACE_MS = 5_000;
 
 export interface ExtractAtomsDrainDeps {
   /**
@@ -34,13 +30,13 @@ export interface ExtractAtomsDrainDeps {
    * via `withRefreshingLock`. MUST throw when the lock is held by another
    * process (e.g. `LockUnavailableError`) — the drain lets that propagate so
    * the caller can report `cycle_already_running` and exit, matching the
-   * routine cycle's skip contract. The signal bounds lock acquisition too.
+   * routine cycle's skip contract.
    */
-  withLock: <T>(work: () => Promise<T>, signal: AbortSignal) => Promise<T>;
-  /** Process one batch. The signal fires at the drain wallclock deadline. */
-  runBatch: (signal: AbortSignal) => Promise<{ extracted: number; skipped: number }>;
+  withLock: <T>(work: () => Promise<T>) => Promise<T>;
+  /** Process one bounded batch (rediscovers eligibility). Returns counts. */
+  runBatch: () => Promise<{ extracted: number; skipped: number }>;
   /** Count remaining eligible-but-unextracted pages, or null on query error. */
-  countRemaining: (signal: AbortSignal) => Promise<number | null>;
+  countRemaining: () => Promise<number | null>;
   /** Injectable clock. Production: Date.now. */
   now: () => number;
   /** Optional progress sink (one line per batch). */
@@ -52,8 +48,6 @@ export interface ExtractAtomsDrainOpts {
   windowMs: number;
   /** Hard cap on batches (belt-and-suspenders against a 0-progress loop). Default 1000. */
   maxBatches?: number;
-  /** External caller cancellation (worker timeout / shutdown). */
-  abortSignal?: AbortSignal;
 }
 
 export interface ExtractAtomsDrainResult {
@@ -74,79 +68,35 @@ export async function runExtractAtomsDrain(
   opts: ExtractAtomsDrainOpts,
 ): Promise<ExtractAtomsDrainResult> {
   const maxBatches = opts.maxBatches ?? 1000;
-  const deadline = deps.now() + opts.windowMs;
-  // #2750: the window used to be checked only BETWEEN batches, so one slow
-  // batch (sequential LLM calls) or a hung lock/count/write overran it without
-  // bound (observed window=120s → 282.5s). A real-time deadline signal now
-  // cancels (Postgres) or abandons (PGLite, cooperative) whatever is in
-  // flight; the injected clock still drives loop-boundary checks so the pure
-  // loop stays unit-testable.
-  const signal = anySignal(
-    AbortSignal.timeout(Math.max(1, opts.windowMs)),
-    opts.abortSignal,
-  );
-  const result: ExtractAtomsDrainResult = await deps.withLock(async () => {
+  return deps.withLock(async () => {
+    const deadline = deps.now() + opts.windowMs;
     let extracted = 0;
     let skipped = 0;
     let batches = 0;
     let stopped: ExtractAtomsDrainResult['stopped'] = 'window';
 
-    while (deps.now() < deadline && !signal.aborted) {
+    while (deps.now() < deadline) {
       if (batches >= maxBatches) { stopped = 'max_batches'; break; }
 
-      let before: number | null;
-      try {
-        before = await deps.countRemaining(signal);
-      } catch (err) {
-        if (signal.aborted) break;
-        throw err;
-      }
+      const before = await deps.countRemaining();
       if (before === 0) { stopped = 'drained'; break; }
 
-      // The backlog count consumed the same wallclock budget — re-check so a
-      // slow count can't hand the batch a window that already expired.
-      if (deps.now() >= deadline || signal.aborted) break;
-
-      let r: { extracted: number; skipped: number };
-      try {
-        r = await deps.runBatch(signal);
-      } catch (err) {
-        if (signal.aborted) break;
-        throw err;
-      }
+      const r = await deps.runBatch();
       extracted += r.extracted;
       skipped += r.skipped;
       batches++;
       deps.onBatch?.({ batch: batches, extracted: r.extracted, remaining: before });
 
-      // A deadline abort inside the batch can surface as zero progress;
-      // window exhaustion wins over the generic no_progress label.
-      if (deps.now() >= deadline || signal.aborted) break;
-
       // Stop if a batch made zero forward progress — extraction is failing or
       // everything left is ineligible (e.g. all skipped). Prevents a hot loop
       // that spends budget without draining.
       if (r.extracted === 0 && r.skipped === 0) { stopped = 'no_progress'; break; }
     }
 
-    // After the window elapsed, don't spend more unbounded time on a final
-    // count — report remaining as unknown instead of overrunning further.
-    const windowElapsed = signal.aborted || deps.now() >= deadline;
-    let remaining: number | null = null;
-    if (!windowElapsed) {
-      try {
-        remaining = await deps.countRemaining(signal);
-      } catch (err) {
-        if (!signal.aborted) throw err;
-      }
-    }
+    const remaining = await deps.countRemaining();
     if (remaining === 0) stopped = 'drained';
     return { phase: 'extract_atoms', status: 'ok', extracted, skipped, remaining, batches, stopped };
-  }, signal);
-  // Internal window expiry is a normal partial result. An EXTERNAL abort
-  // (worker cancel/timeout/shutdown) must reject so Minion records the abort.
-  if (opts.abortSignal?.aborted) throw opts.abortSignal.reason;
-  return result;
+  });
 }
 
 // ─── Shared wiring helper (v0.42.x #1685 DECISION 5A) ──────────────────────
@@ -184,8 +134,6 @@ export interface DrainForSourceOpts {
   maxBatches?: number;
   /** Optional per-batch progress sink (stderr line in dream; job progress in the handler). */
   onBatch?: ExtractAtomsDrainDeps['onBatch'];
-  /** Worker cancellation / shutdown signal (Minion `job.signal`). */
-  abortSignal?: AbortSignal;
 }
 
 export async function runExtractAtomsDrainForSource(
@@ -201,17 +149,12 @@ export async function runExtractAtomsDrainForSource(
 
   return runExtractAtomsDrain(
     {
-      withLock: (work, signal) => withRefreshingLock(engine, lockId, work, {
-        ttlMinutes: 5,
-        signal,
-        releaseTimeoutMs: LOCK_RELEASE_GRACE_MS,
-      }),
-      runBatch: async (signal) => {
+      withLock: (work) => withRefreshingLock(engine, lockId, work, { ttlMinutes: 5 }),
+      runBatch: async () => {
         const r = await runPhaseExtractAtoms(engine, {
           sourceId: extractionSourceId,
           dryRun: false,
           brainDir: opts.brainDir,
-          abortSignal: signal,
         });
         const d = (r.details ?? {}) as Record<string, unknown>;
         return {
@@ -219,14 +162,10 @@ export async function runExtractAtomsDrainForSource(
           skipped: Number(d.duplicates_skipped ?? 0),
         };
       },
-      countRemaining: (signal) => countExtractAtomsBacklog(engine, extractionSourceId, signal),
+      countRemaining: () => countExtractAtomsBacklog(engine, extractionSourceId),
       now: Date.now,
       onBatch: opts.onBatch,
     },
-    {
-      windowMs: opts.windowSeconds * 1000,
-      maxBatches: opts.maxBatches,
-      abortSignal: opts.abortSignal,
-    },
+    { windowMs: opts.windowSeconds * 1000, maxBatches: opts.maxBatches },
   );
 }

src/core/cycle/extract-atoms.ts

@@ -58,10 +58,6 @@ import { createHash } from 'crypto';
 import { slugifySegment } from '../sync.ts';
 
 const DEFAULT_BUDGET_USD = 0.3;
-// #2750: fresh wallclock budget for the receipt/rollup bookkeeping writes when
-// the caller's deadline already fired — committed atoms must not lose their
-// cost/receipt trail, but the writes can't be unbounded either.
-const BOOKKEEPING_GRACE_MS = 5_000;
 
 // v0.42+ TODO: read atom_type enum from active pack manifest at runtime.
 const ATOM_TYPES = [
@@ -159,13 +155,6 @@ export interface ExtractAtomsOpts {
    * `heartbeat()` on the passed reporter.
    */
   progress?: ProgressReporter;
-  /**
-   * #2750: caller deadline/cancellation. Forwarded to every gateway call and
-   * DB query/write so the drain window bounds real lifetime, plus a
-   * cooperative between-item check (the PGLite path, where query abort only
-   * abandons the waiter).
-   */
-  abortSignal?: AbortSignal;
 }
 
 interface ExtractedAtom {
@@ -223,7 +212,6 @@ export async function discoverExtractablePages(
   engine: BrainEngine,
   sourceId: string,
   affectedSlugs?: string[],
-  abortSignal?: AbortSignal,
 ): Promise<DiscoveredPage[]> {
   const hasFilter = Array.isArray(affectedSlugs) && affectedSlugs.length > 0;
   const sql = `
@@ -263,16 +251,13 @@ export async function discoverExtractablePages(
       slug: string;
       compiled_truth: string;
       content_hash: string;
-    }>(sql, params, { signal: abortSignal });
+    }>(sql, params);
     return rows.map((r) => ({
       slug: r.slug,
       content: r.compiled_truth,
       contentHash: r.content_hash,
     }));
   } catch (err) {
-    // A deadline abort is not a fail-soft condition — propagate so the
-    // caller stops instead of proceeding with an empty page list.
-    if (abortSignal?.aborted) throw err;
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`[extract_atoms] page-discovery query failed: ${msg}`);
     return []; // fail-soft: transcript path still proceeds
@@ -297,7 +282,6 @@ export async function discoverExtractablePages(
 export async function countExtractAtomsBacklog(
   engine: BrainEngine,
   sourceId?: string,
-  abortSignal?: AbortSignal,
 ): Promise<number | null> {
   try {
     // Two modes: scoped (the phase's per-source `remaining`) vs brain-wide
@@ -337,10 +321,9 @@ export async function countExtractAtomsBacklog(
     const params = scoped
       ? [sourceId, extractableTypes, MIN_PAGE_CHARS_FOR_EXTRACTION]
       : [extractableTypes, MIN_PAGE_CHARS_FOR_EXTRACTION];
-    const rows = await engine.executeRaw<{ cnt: string | number }>(sql, params, { signal: abortSignal });
+    const rows = await engine.executeRaw<{ cnt: string | number }>(sql, params);
     return Number(rows[0]?.cnt ?? 0);
   } catch (err) {
-    if (abortSignal?.aborted) throw err;
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`[extract_atoms] backlog count failed: ${msg}`);
     return null;
@@ -367,7 +350,6 @@ export async function atomsExistingForHashes(
   engine: BrainEngine,
   sourceId: string,
   contentHash16s: string[],
-  abortSignal?: AbortSignal,
 ): Promise<Set<string>> {
   if (contentHash16s.length === 0) return new Set();
   try {
@@ -379,11 +361,9 @@ export async function atomsExistingForHashes(
           AND deleted_at IS NULL
           AND frontmatter->>'source_hash' = ANY($2::text[])`,
       [sourceId, contentHash16s],
-      { signal: abortSignal },
     );
     return new Set(rows.map(r => r.h));
   } catch (err) {
-    if (abortSignal?.aborted) throw err;
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`[extract_atoms] batch idempotency check failed (assuming none extracted): ${msg}`);
     return new Set();
@@ -404,7 +384,6 @@ export async function runPhaseExtractAtoms(
 ): Promise<PhaseResult> {
   const sourceId = opts.sourceId ?? 'default';
   const chat = opts._chat ?? gatewayChat;
-  if (opts.abortSignal?.aborted) throw opts.abortSignal.reason;
 
   // 1a. Get transcripts (test seam OR production discovery).
   //     v0.41.2.1: config loader switched to loadConfigWithEngine() so the
@@ -446,7 +425,7 @@ export async function runPhaseExtractAtoms(
   if (opts._pages !== undefined) {
     pages = opts._pages;
   } else {
-    pages = await discoverExtractablePages(engine, sourceId, opts.affectedSlugs, opts.abortSignal);
+    pages = await discoverExtractablePages(engine, sourceId, opts.affectedSlugs);
   }
 
   // 2. Apply transcript-side source-hash idempotency in ONE batch query
@@ -458,7 +437,7 @@ export async function runPhaseExtractAtoms(
   // Surface a heartbeat before the batch query so even an instant
   // short-circuit shows a sign of life (closes Issue 2 silent-phase pain).
   opts.progress?.heartbeat(`checking existing atoms for ${allHashes16.length} transcripts`);
-  const existingHashes = await atomsExistingForHashes(engine, sourceId, allHashes16, opts.abortSignal);
+  const existingHashes = await atomsExistingForHashes(engine, sourceId, allHashes16);
   for (const t of transcripts) {
     if (existingHashes.has(t.contentHash.slice(0, 16))) {
       duplicatesSkipped++;
@@ -522,7 +501,6 @@ export async function runPhaseExtractAtoms(
   const failures: Array<{ source: string; error: string }> = [];
   let estimatedSpendUsd = 0;
   const budgetCap = DEFAULT_BUDGET_USD;
-  let deadlineAborted = false;
 
   // v0.41.19.0 (T3): throttled yield helper. Fires `opts.yieldDuringPhase`
   // every 30s. Cycle.ts threads `buildYieldDuringPhase(lock, outer)` so
@@ -548,12 +526,6 @@ export async function runPhaseExtractAtoms(
   }
 
   for (const item of work) {
-    // #2750: cooperative between-item abort. Works on every engine — this is
-    // the primary bound on PGLite, where query abort only abandons the waiter.
-    if (opts.abortSignal?.aborted) {
-      deadlineAborted = true;
-      break;
-    }
     await maybeYield();
     if (estimatedSpendUsd >= budgetCap) {
       if (item.kind === 'transcript') transcriptsSkipped++;
@@ -572,22 +544,16 @@ export async function runPhaseExtractAtoms(
           },
         ],
         maxTokens: 2000,
-        abortSignal: opts.abortSignal,
       });
-      // Rough cost estimate — Haiku at ~$0.80/M input + $4/M output.
-      // A completed gateway call is billable even if the deadline fires
-      // immediately afterward, so record usage BEFORE the abort check.
-      estimatedSpendUsd +=
-        (result.usage.input_tokens * 0.8 + result.usage.output_tokens * 4.0) / 1_000_000;
-      if (opts.abortSignal?.aborted) {
-        deadlineAborted = true;
-        break;
-      }
       // Post-await yield: closes the "long LLM call past TTL" hazard
       // codex flagged. The 30s throttle inside maybeYield bounds the
       // actual refresh rate so this is cheap when calls are fast.
       await maybeYield();
 
+      // Rough cost estimate — Haiku at ~$0.80/M input + $4/M output
+      estimatedSpendUsd +=
+        (result.usage.input_tokens * 0.8 + result.usage.output_tokens * 4.0) / 1_000_000;
+
       const atoms = parseAtomsResponse(result.text);
       if (atoms.length === 0) {
         if (item.kind === 'transcript') transcriptsProcessed++;
@@ -626,7 +592,7 @@ export async function runPhaseExtractAtoms(
               },
               timeline: '',
             },
-            { sourceId, signal: opts.abortSignal },
+            { sourceId },
           );
           totalAtomsExtracted++;
         }
@@ -639,11 +605,6 @@ export async function runPhaseExtractAtoms(
       // Reporter rate-limits to ~1 line/sec; safe to tick every iter.
       opts.progress?.tick(1, `${totalAtomsExtracted} atoms / ${duplicatesSkipped} skipped`);
     } catch (err) {
-      // A deadline abort is a partial result, not a per-item failure.
-      if (opts.abortSignal?.aborted) {
-        deadlineAborted = true;
-        break;
-      }
       failures.push({
         source: originLabel,
         error: err instanceof Error ? err.message : String(err),
@@ -654,12 +615,6 @@ export async function runPhaseExtractAtoms(
   // v0.42 Wave B2: write extract receipt + rollup row when the phase
   // actually extracted atoms. Both are best-effort per F-OUT-19 —
   // audit-trail / search-visibility surfaces don't block the phase result.
-  //
-  // #2750: bookkeeping runs on a FRESH short grace signal, never the caller's
-  // work deadline — the deadline may have already fired (partial run) and
-  // committed atoms must not lose their receipt/cost trail; but the writes
-  // stay bounded so the overrun is capped at the grace window.
-  const bookkeepingSignal = opts.dryRun ? undefined : AbortSignal.timeout(BOOKKEEPING_GRACE_MS);
   if (!opts.dryRun && totalAtomsExtracted > 0) {
     const runId = `atoms-${Date.now().toString(36)}-${sourceId.slice(0, 4)}`;
     try {
@@ -674,24 +629,19 @@ export async function runPhaseExtractAtoms(
         summary:
           `Extracted ${totalAtomsExtracted} atoms from ` +
           `${transcriptsProcessed} transcripts + ${pagesProcessed} pages.`,
-      }, { signal: bookkeepingSignal });
+      });
     } catch (err) {
       console.error(`[extract_atoms] receipt write failed: ${(err as Error).message}`);
     }
   }
   if (!opts.dryRun) {
-    try {
-      await upsertExtractRollup(engine, {
-        kind: 'atoms',
-        source_id: sourceId,
-        cost_delta: estimatedSpendUsd,
-        // A deadline-truncated run is not a completed round.
-        round_completed_delta: failures.length === 0 && !deadlineAborted ? 1 : 0,
-        halt_delta: failures.length > 0 ? 1 : 0,
-      }, { signal: bookkeepingSignal });
-    } catch (err) {
-      console.error(`[extract_atoms] rollup write failed: ${(err as Error).message}`);
-    }
+    await upsertExtractRollup(engine, {
+      kind: 'atoms',
+      source_id: sourceId,
+      cost_delta: estimatedSpendUsd,
+      round_completed_delta: failures.length === 0 ? 1 : 0,
+      halt_delta: failures.length > 0 ? 1 : 0,
+    });
   }
 
   return {
@@ -720,7 +670,6 @@ export async function runPhaseExtractAtoms(
       budget_usd: budgetCap,
       source_id: sourceId,
       dry_run: opts.dryRun ?? false,
-      deadline_aborted: deadlineAborted,
     },
   };
 }

src/core/db-lock.ts

@@ -26,8 +26,7 @@ import type { BrainEngine } from './engine.ts';
 
 export interface DbLockHandle {
   id: string;
-  /** Optional signal bounds the release DELETE (deadline-bound callers). */
-  release: (signal?: AbortSignal) => Promise<void>;
+  release: () => Promise<void>;
   refresh: () => Promise<void>;
 }
 
@@ -174,7 +173,6 @@ export async function tryAcquireDbLock(
   engine: BrainEngine,
   lockId: string,
   ttlMinutes: number = DEFAULT_TTL_MINUTES,
-  opts: { signal?: AbortSignal } = {},
 ): Promise<DbLockHandle | null> {
   const pid = process.pid;
   const host = hostname();
@@ -207,26 +205,20 @@ export async function tryAcquireDbLock(
     // `gbrain sync --break-lock --max-age <s>` uses last_refreshed_at (not
     // acquired_at) to identify wedged-but-alive holders without stealing
     // healthy long-running holders that are actively refreshing.
-    // #2750: routed through executeRaw so a deadline-bound caller's signal
-    // can cancel a hung acquire (pool exhaustion). Cancellation is
-    // transactional; in the rare ambiguous-commit case the row's TTL is the
-    // backstop (drain locks use a short 5-minute TTL).
-    const rows = await engine.executeRaw<{ id: string }>(
-      `INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at, last_refreshed_at)
-       VALUES ($1, $2, $3, NOW(), NOW() + $4::interval, NOW())
-       ON CONFLICT (id) DO UPDATE
-         SET holder_pid = $2,
-             holder_host = $3,
-             acquired_at = NOW(),
-             ttl_expires_at = NOW() + $4::interval,
-             last_refreshed_at = NOW()
-         WHERE gbrain_cycle_locks.ttl_expires_at < NOW()
-           AND (gbrain_cycle_locks.last_refreshed_at IS NULL
-                OR gbrain_cycle_locks.last_refreshed_at < NOW() - $5 * INTERVAL '1 second')
-       RETURNING id`,
-      [lockId, pid, host, ttl, stealGraceSeconds],
-      { signal: opts.signal },
-    );
+    const rows: Array<{ id: string }> = await sql`
+      INSERT INTO gbrain_cycle_locks (id, holder_pid, holder_host, acquired_at, ttl_expires_at, last_refreshed_at)
+      VALUES (${lockId}, ${pid}, ${host}, NOW(), NOW() + ${ttl}::interval, NOW())
+      ON CONFLICT (id) DO UPDATE
+        SET holder_pid = ${pid},
+            holder_host = ${host},
+            acquired_at = NOW(),
+            ttl_expires_at = NOW() + ${ttl}::interval,
+            last_refreshed_at = NOW()
+        WHERE gbrain_cycle_locks.ttl_expires_at < NOW()
+          AND (gbrain_cycle_locks.last_refreshed_at IS NULL
+               OR gbrain_cycle_locks.last_refreshed_at < NOW() - ${stealGraceSeconds} * INTERVAL '1 second')
+      RETURNING id
+    `;
     if (rows.length === 0) return null;
     const deregister = registerCleanup(`db-lock:${lockId}`, async () => {
       await sql`
@@ -249,17 +241,12 @@ export async function tryAcquireDbLock(
           [ttl, lockId, pid],
         );
       },
-      release: async (signal?: AbortSignal) => {
+      release: async () => {
         deregister();
-        // Direct session pool (same rationale as refresh, #1794) + optional
-        // signal so a deadline-bound caller's release can't hang forever on
-        // an exhausted pooler. TTL is the backstop if the DELETE is cancelled.
-        await engine.executeRawDirect(
-          `DELETE FROM gbrain_cycle_locks
-            WHERE id = $1 AND holder_pid = $2`,
-          [lockId, pid],
-          { signal },
-        );
+        await sql`
+          DELETE FROM gbrain_cycle_locks
+          WHERE id = ${lockId} AND holder_pid = ${pid}
+        `;
       },
     };
   }
@@ -316,11 +303,6 @@ export async function tryAcquireDbLock(
   const first = await acquireOnce();
   if (first) return first;
 
-  // #2750: deadline-bound callers prefer an honest busy result over the
-  // best-effort same-host takeover below, whose inspect/delete/retry calls
-  // are not signal-bounded. The initial upsert already reclaims expired locks.
-  if (opts.signal) return null;
-
   // v0.42 (#1780 Gap 3): the lock is held and its TTL hasn't expired (the
   // upsert's ON CONFLICT ... WHERE ttl_expires_at < NOW() returned no row).
   // If the holder is on THIS host, provably dead, and past the grace window,
@@ -814,10 +796,6 @@ export interface WithRefreshingLockOpts {
   ttlMinutes?: number;
   /** Heartbeat-fail threshold in ms — abort if SELECT 1 takes longer. Default 30000. */
   heartbeatTimeoutMs?: number;
-  /** #2750: bound lock acquisition with the caller's deadline signal. */
-  signal?: AbortSignal;
-  /** Fresh cleanup budget for the release DELETE when `signal` is set. Default 5000. */
-  releaseTimeoutMs?: number;
 }
 
 /**
@@ -837,7 +815,7 @@ export async function withRefreshingLock<T>(
   // Refresh 6x per TTL window so a missed tick doesn't expire the lock.
   const refreshIntervalMs = Math.max(15000, (ttlMinutes * 60 * 1000) / 6);
 
-  const handle = await tryAcquireDbLock(engine, lockId, ttlMinutes, { signal: opts.signal });
+  const handle = await tryAcquireDbLock(engine, lockId, ttlMinutes);
   if (!handle) throw new LockUnavailableError(lockId);
 
   let healthOk = true;
@@ -876,13 +854,7 @@ export async function withRefreshingLock<T>(
     return await work();
   } finally {
     clearInterval(interval);
-    // #2750: when the caller is deadline-bound, its work signal may already
-    // have fired — release on a FRESH short grace signal so cleanup neither
-    // inherits the spent deadline nor hangs unbounded. TTL is the backstop.
-    const releaseSignal = opts.signal
-      ? AbortSignal.timeout(opts.releaseTimeoutMs ?? 5_000)
-      : undefined;
-    try { await handle.release(releaseSignal); } catch { /* idempotent; TTL backstop */ }
+    try { await handle.release(); } catch { /* idempotent */ }
     if (!healthOk) {
       // Surface that the heartbeat detected backend trouble — caller can
       // log to the connection-events audit if desired.

src/core/engine.ts

@@ -696,16 +696,8 @@ export interface BrainEngine {
    * is included in the INSERT column list so ON CONFLICT (source_id, slug)
    * DO UPDATE actually targets the intended row instead of fabricating a
    * duplicate at (default, slug). Multi-source brains MUST pass sourceId.
-   *
-   * `opts.signal` (#2750): optional cancellation for deadline-bound writers.
-   * Postgres cancels the in-flight statement; PGLite pre-checks only (query
-   * cancellation is not possible in-process — cooperative abort between calls).
    */
-  putPage(
-    slug: string,
-    page: PageInput,
-    opts?: { sourceId?: string; signal?: AbortSignal },
-  ): Promise<Page>;
+  putPage(slug: string, page: PageInput, opts?: { sourceId?: string }): Promise<Page>;
   /**
    * v0.41.13 (#1309) — identity-based dedup pre-check for the import pipeline.
    *

src/core/eval-capture.ts

@@ -251,6 +251,14 @@ registerBackgroundWorkDrainer({
 export function isEvalCaptureEnabled(config: GBrainConfig | null | undefined): boolean {
   if (config?.eval?.capture === true) return true;
   if (config?.eval?.capture === false) return false;
+  // #1475: DB-plane stash. `gbrain config set eval.capture true` lands in the
+  // config table; connectEngine stamps the merged value here because
+  // ctx.config is the sync file-plane load and never sees the DB plane.
+  // Explicit per-key setting (file above, DB here) beats the broad
+  // CONTRIBUTOR_MODE flag, matching how file-plane `false` already wins.
+  // Doubles as a direct operator env knob.
+  if (process.env.GBRAIN_EVAL_CAPTURE === 'true') return true;
+  if (process.env.GBRAIN_EVAL_CAPTURE === 'false') return false;
   return process.env.GBRAIN_CONTRIBUTOR_MODE === '1';
 }
 
@@ -263,5 +271,8 @@ export function isEvalCaptureEnabled(config: GBrainConfig | null | undefined): b
  * have explicit `capture: true`.
  */
 export function isEvalScrubEnabled(config: GBrainConfig | null | undefined): boolean {
-  return config?.eval?.scrub_pii !== false;
+  if (config?.eval?.scrub_pii === false) return false;
+  if (config?.eval?.scrub_pii === true) return true;
+  // #1475: DB-plane stash — see isEvalCaptureEnabled. Default stays true.
+  return process.env.GBRAIN_EVAL_SCRUB_PII !== 'false';
 }

src/core/extract/receipt-writer.ts

@@ -187,7 +187,6 @@ function buildReceiptFrontmatter(input: ExtractReceiptInput): Record<string, unk
 export async function writeReceipt(
   engine: BrainEngine,
   input: ExtractReceiptInput,
-  opts?: { signal?: AbortSignal },
 ): Promise<{ slug: string; page: Page }> {
   const slug = receiptSlug(input);
   const title = `${input.kind} — ${input.round} — ${input.source_id}`;
@@ -202,7 +201,7 @@ export async function writeReceipt(
       compiled_truth,
       frontmatter,
     },
-    { sourceId: input.source_id, signal: opts?.signal },
+    { sourceId: input.source_id },
   );
 
   return { slug, page };

src/core/extract/rollup-writer.ts

@@ -70,7 +70,6 @@ function today(): string {
 export async function upsertExtractRollup(
   engine: BrainEngine,
   input: RollupUpsertInput,
-  opts?: { signal?: AbortSignal },
 ): Promise<{ ok: boolean; error?: string }> {
   const day = input.day ?? today();
   const cost = input.cost_delta ?? 0;
@@ -97,12 +96,9 @@ export async function upsertExtractRollup(
          rollup_write_failures  = extract_rollup_7d.rollup_write_failures  + EXCLUDED.rollup_write_failures,
          updated_at             = now()`,
       [input.kind, input.source_id, day, cost, halts, evalFails, evalPasses, completed, failures],
-      { signal: opts?.signal },
     );
     return { ok: true };
   } catch (err) {
-    // Signal-bounded callers get the abort surfaced, not a swallowed `ok:false`.
-    if (opts?.signal?.aborted) throw err;
     const msg = (err as Error).message || String(err);
     // Don't spam: log once per process per (kind, day) error class.
     rollupErrorLogOnce(input.kind, day, msg);

src/core/import-file.ts

@@ -733,6 +733,11 @@ export async function importFromContent(
       : computeCorpusGeneration({
           crMode: effectiveCRMode,
           haikuModel: 'anthropic:claude-haiku-4-5-20251001',
+          // Inline import-file path never uses per_chunk_synopsis (refuses
+          // upstream); pass undefined so the doc-cap field stays out of
+          // the hash here. Per_chunk_synopsis runs through the Minion
+          // backfill handler which threads SYNOPSIS_DOC_MAX_CHARS through
+          // the service layer.
         });
 
   // Transaction wraps all DB writes. Every per-page tx call carries the

src/core/link-extraction.ts

@@ -489,7 +489,22 @@ export async function extractPageLinks(
       // text inside `[[...]]` before any `|`), NOT the display alias
       // (ref.name = match[2]). `[[struktura|the project]]` must resolve
       // `struktura`, not "the project". The display text is for context only.
-      const matches = await resolver.resolveBasenameMatches(ref.slug);
+      //
+      // The literal may be path-qualified (`[[notes/struktura]]`). The FS
+      // path (resolveSlugAll) strips the dirname before its basename lookup,
+      // but this path passed the raw literal to an index keyed by final
+      // segments only — so every slash-containing wikilink outside
+      // DIR_PATTERN silently resolved to nothing. Query by the final
+      // segment, then use the written path as a disambiguation filter
+      // (the analogue of the FS ancestor walk honoring the written path):
+      // a match must end with the literal, so `[[notes/struktura]]` can
+      // resolve to `vault/notes/struktura` but never to `wiki/struktura`.
+      const slashIdx = ref.slug.lastIndexOf('/');
+      const basename = slashIdx === -1 ? ref.slug : ref.slug.slice(slashIdx + 1);
+      let matches = await resolver.resolveBasenameMatches(basename);
+      if (slashIdx !== -1) {
+        matches = matches.filter(m => m === ref.slug || m.endsWith(`/${ref.slug}`));
+      }
       if (matches.length === 0) continue;
       const idx = content.indexOf(ref.slug);
       const context = idx >= 0 ? excerpt(content, idx, 240) : ref.name;

src/core/orphan-policy.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared orphan-reporting exclusion policy.
+ *
+ * These are pages where "no inbound links" is expected and should not count
+ * against health. Keep this in core so the CLI orphan report and engine health
+ * dashboard cannot drift.
+ *
+ * Defaults are GBrain-wide conventions only. Brain-specific exclusions
+ * (private folder names, one-off fixture slugs) belong in the brain's own
+ * config, not here:
+ *
+ *   gbrain config set orphans.exclude_prefixes "my-private-folder/,archive/"
+ *   gbrain config set orphans.exclude_slugs "some-one-off-page"
+ */
+
+const AUTO_SUFFIX_PATTERNS = ['/_index', '/log'];
+
+const PSEUDO_SLUGS = new Set(['_atlas', '_index', '_stats', '_orphans', '_scratch', 'claude']);
+
+const RAW_SEGMENT = '/raw/';
+
+const DENY_PREFIXES = [
+  'output/',
+  'dashboards/',
+  'scripts/',
+  'templates/',
+  '_templates/',
+  'openclaw/config/',
+  'extracts/',
+];
+
+const FIRST_SEGMENT_EXCLUSIONS = new Set([
+  'scratch',
+  'thoughts',
+  'catalog',
+  'entities',
+  'raw',
+  'atoms',
+  'skills',
+  'dreaming',
+  'daily',
+]);
+
+const ROOT_DATE_SLUG = /^\d{4}-\d{2}-\d{2}(?:-.+)?$/;
+
+function isAgentWorkspaceConvention(slug: string): boolean {
+  if (!slug.startsWith('agents/')) return false;
+  if (slug.includes('/memory/dreaming/')) return true;
+  return /^agents\/[^/]+\/(?:agents|identity|soul|tools|user|heartbeat|dreams|dormant)$/.test(slug);
+}
+
+/** Per-brain additions to the convention defaults (from config). */
+export interface OrphanPolicyOverrides {
+  excludePrefixes?: string[];
+  excludeSlugs?: string[];
+}
+
+/** Config keys for per-brain orphan exclusions (comma-separated values). */
+export const ORPHAN_EXCLUDE_PREFIXES_KEY = 'orphans.exclude_prefixes';
+export const ORPHAN_EXCLUDE_SLUGS_KEY = 'orphans.exclude_slugs';
+
+function parseList(value: string | null): string[] {
+  if (!value) return [];
+  return value.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * Load per-brain orphan exclusions from the brain config table. Callers with
+ * an engine in hand (getHealth, `gbrain orphans`) pass the result as the
+ * second argument to shouldExcludeFromOrphanReporting.
+ */
+export async function loadOrphanPolicyOverrides(
+  engine: { getConfig(key: string): Promise<string | null> },
+): Promise<OrphanPolicyOverrides> {
+  const [prefixes, slugs] = await Promise.all([
+    engine.getConfig(ORPHAN_EXCLUDE_PREFIXES_KEY),
+    engine.getConfig(ORPHAN_EXCLUDE_SLUGS_KEY),
+  ]);
+  return { excludePrefixes: parseList(prefixes), excludeSlugs: parseList(slugs) };
+}
+
+export function shouldExcludeFromOrphanReporting(
+  slug: string,
+  overrides?: OrphanPolicyOverrides,
+): boolean {
+  if (PSEUDO_SLUGS.has(slug)) return true;
+
+  for (const suffix of AUTO_SUFFIX_PATTERNS) {
+    if (slug.endsWith(suffix)) return true;
+  }
+
+  if (slug.includes(RAW_SEGMENT)) return true;
+  if (slug.includes('/daily/')) return true;
+
+  for (const prefix of DENY_PREFIXES) {
+    if (slug.startsWith(prefix)) return true;
+  }
+
+  const firstSegment = slug.split('/')[0];
+  if (FIRST_SEGMENT_EXCLUSIONS.has(firstSegment)) return true;
+
+  if (ROOT_DATE_SLUG.test(slug)) return true;
+
+  if (slug.startsWith('_brain-')) return true;
+
+  if (isAgentWorkspaceConvention(slug)) return true;
+
+  if (overrides) {
+    if (overrides.excludeSlugs?.includes(slug)) return true;
+    for (const prefix of overrides.excludePrefixes ?? []) {
+      if (slug.startsWith(prefix)) return true;
+    }
+  }
+
+  return false;
+}

src/core/page-summary.ts

@@ -44,6 +44,33 @@ const HAIKU_MAX_TOKENS = 200;
 /** Default model when caller doesn't override. Resolves through the gateway. */
 const DEFAULT_SYNOPSIS_MODEL = 'anthropic:claude-haiku-4-5-20251001';
 
+/**
+ * Hard cap on `documentText` length (chars) before send.
+ *
+ * 2026-05-25 fix wave: small local chat models (Gemma 4 E2B, Qwen3 4B) get
+ * dramatically slower on long contexts even with 131K-token windows declared.
+ * A 73K-char page synopsis on Gemma 4 E2B takes 60-120s, exceeding the
+ * worker's default 30s `lockDuration` and tripping `lock-lost` errors.
+ *
+ * Truncate to a budget that fits a small model's effective throughput while
+ * preserving enough document context for the synopsis to be useful. Truncates
+ * the TAIL because the head (title, frontmatter, intro) carries the
+ * document-level anchor the synopsis needs.
+ *
+ * Override per workload via `GBRAIN_SYNOPSIS_DOC_MAX_CHARS`. Default 32768
+ * (~8K tokens at 4 chars/tok) keeps small-model synopsis under ~30s.
+ * Anthropic Haiku is unaffected at this cap; bump higher when running
+ * frontier models if you want richer document anchoring.
+ */
+export const SYNOPSIS_DOC_MAX_CHARS = (() => {
+  const env = process.env.GBRAIN_SYNOPSIS_DOC_MAX_CHARS;
+  if (env && /^\d+$/.test(env)) {
+    const n = parseInt(env, 10);
+    if (n >= 512 && n <= 1_048_576) return n;
+  }
+  return 32768;
+})();
+
 /**
  * Synopsis prompt version. Folded into corpus_generation so prompt edits
  * invalidate prior embeddings via the v0.40.3.0 query_cache.page_generations
@@ -188,11 +215,19 @@ function buildUserPrompt(
   documentText: string,
   chunkText: string,
 ): string {
+  // Tail-truncate `documentText` to `SYNOPSIS_DOC_MAX_CHARS` so small local
+  // chat models don't stall on >100KB pages. Head preserved (title block,
+  // frontmatter, intro paragraphs carry the document-level anchor).
+  let trimmedDoc = documentText;
+  if (documentText.length > SYNOPSIS_DOC_MAX_CHARS) {
+    trimmedDoc = documentText.slice(0, SYNOPSIS_DOC_MAX_CHARS) +
+      `\n\n[... ${documentText.length - SYNOPSIS_DOC_MAX_CHARS} chars truncated for synopsis budget ...]`;
+  }
   return [
     `<page_title>${pageTitle}</page_title>`,
     '',
     '<full_document>',
-    documentText,
+    trimmedDoc,
     '</full_document>',
     '',
     '<chunk>',

src/core/pglite-engine.ts

@@ -57,6 +57,8 @@ import { finalizeLastSeen } from './chronicle/last-seen.ts';
 import { computeAnomaliesFromBuckets } from './cycle/anomaly.ts';
 import { resolveBoostMap, resolveHardExcludes } from './search/source-boost.ts';
 import { buildSourceFactorCase, buildHardExcludeClause, buildVisibilityClause, buildRecencyComponentSql, buildBestPerPagePoolCte, buildOrFallbackWebsearchQuery } from './search/sql-ranking.ts';
+import { shouldExcludeFromOrphanReporting, loadOrphanPolicyOverrides } from './orphan-policy.ts';
+import { LINK_EXTRACTOR_VERSION_TS } from './link-extraction.ts';
 import {
   normalizeEngineColumn,
   buildVectorCastFragment,
@@ -1003,15 +1005,7 @@ export class PGLiteEngine implements BrainEngine {
     return { slug: r.slug, id: Number(r.id) };
   }
 
-  async putPage(
-    slug: string,
-    page: PageInput,
-    opts?: { sourceId?: string; signal?: AbortSignal },
-  ): Promise<Page> {
-    // #2750: PGLite is in-process WASM — no query cancellation. Pre-check so
-    // an already-fired deadline skips the write; abort is cooperative
-    // between calls (same posture as executeRaw's documented gap).
-    if (opts?.signal?.aborted) throw new DOMException('aborted', 'AbortError');
+  async putPage(slug: string, page: PageInput, opts?: { sourceId?: string }): Promise<Page> {
     slug = validateSlug(slug);
     const hash = page.content_hash || contentHash(page);
     const frontmatter = page.frontmatter || {};
@@ -2330,6 +2324,10 @@ export class PGLiteEngine implements BrainEngine {
     // v0.40.3.0 D24 NULL→non-NULL race fix mirrors postgres-engine.ts. Two writers
     // racing on the same chunk previously raced last-write-wins; the fix lets the
     // fresher `embedded_at` win in the text-unchanged branch.
+    //
+    // Code-chunk metadata columns follow the same chunk_text-gated CASE pattern as `embedding`
+    // (#769). Re-chunk trusts EXCLUDED outright; pure re-embed COALESCEs so a caller carrying
+    // only embedding-shaped fields doesn't clobber metadata to NULL.
     await this.db.query(
       `INSERT INTO content_chunks ${cols} VALUES ${rowParts.join(', ')}
        ON CONFLICT (page_id, chunk_index) DO UPDATE SET
@@ -2353,14 +2351,14 @@ export class PGLiteEngine implements BrainEngine {
                 THEN EXCLUDED.embedded_at
            ELSE content_chunks.embedded_at
          END,
-         language = EXCLUDED.language,
-         symbol_name = EXCLUDED.symbol_name,
-         symbol_type = EXCLUDED.symbol_type,
-         start_line = EXCLUDED.start_line,
-         end_line = EXCLUDED.end_line,
-         parent_symbol_path = EXCLUDED.parent_symbol_path,
-         doc_comment = EXCLUDED.doc_comment,
-         symbol_name_qualified = EXCLUDED.symbol_name_qualified,
+         language = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.language ELSE COALESCE(EXCLUDED.language, content_chunks.language) END,
+         symbol_name = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.symbol_name ELSE COALESCE(EXCLUDED.symbol_name, content_chunks.symbol_name) END,
+         symbol_type = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.symbol_type ELSE COALESCE(EXCLUDED.symbol_type, content_chunks.symbol_type) END,
+         start_line = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.start_line ELSE COALESCE(EXCLUDED.start_line, content_chunks.start_line) END,
+         end_line = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.end_line ELSE COALESCE(EXCLUDED.end_line, content_chunks.end_line) END,
+         parent_symbol_path = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.parent_symbol_path ELSE COALESCE(EXCLUDED.parent_symbol_path, content_chunks.parent_symbol_path) END,
+         doc_comment = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.doc_comment ELSE COALESCE(EXCLUDED.doc_comment, content_chunks.doc_comment) END,
+         symbol_name_qualified = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.symbol_name_qualified ELSE COALESCE(EXCLUDED.symbol_name_qualified, content_chunks.symbol_name_qualified) END,
          modality = EXCLUDED.modality,
          embedding_image = COALESCE(EXCLUDED.embedding_image, content_chunks.embedding_image)`,
       params
@@ -5215,15 +5213,10 @@ export class PGLiteEngine implements BrainEngine {
         (SELECT count(*) FROM pages) as page_count,
         (SELECT count(*) FROM content_chunks WHERE embedded_at IS NOT NULL)::float /
           GREATEST((SELECT count(*) FROM content_chunks), 1)::float as embed_coverage,
-        (SELECT count(*) FROM pages p
-         WHERE p.updated_at < (SELECT MAX(te.created_at) FROM timeline_entries te WHERE te.page_id = p.id)
-        ) as stale_pages,
-        -- Bug 11 — orphan = islanded (no inbound AND no outbound).
-        -- See BrainHealth.orphan_pages docstring; docs updated to match this.
-        (SELECT count(*) FROM pages p
-         WHERE NOT EXISTS (SELECT 1 FROM links l WHERE l.to_page_id = p.id)
-           AND NOT EXISTS (SELECT 1 FROM links l WHERE l.from_page_id = p.id)
-        ) as orphan_pages,
+        0 as stale_pages,
+        -- Bug 11 — orphan = islanded (no inbound AND no outbound). The raw
+        -- list is filtered in TS using the shared orphan-reporting policy.
+        0 as orphan_pages,
         (SELECT count(*) FROM links l
          WHERE NOT EXISTS (SELECT 1 FROM pages p WHERE p.id = l.to_page_id)
         ) as dead_links,
@@ -5248,10 +5241,20 @@ export class PGLiteEngine implements BrainEngine {
       LIMIT 5
     `);
 
+    const { rows: islandedRows } = await this.db.query(`
+      SELECT p.slug
+      FROM pages p
+      WHERE NOT EXISTS (SELECT 1 FROM links l WHERE l.to_page_id = p.id)
+        AND NOT EXISTS (SELECT 1 FROM links l WHERE l.from_page_id = p.id)
+    `);
+
     const r = h as Record<string, unknown>;
     const pageCount = Number(r.page_count);
     const embedCoverage = Number(r.embed_coverage);
-    const orphanPages = Number(r.orphan_pages);
+    const stalePages = await this.countStalePagesForExtraction({ versionTs: LINK_EXTRACTOR_VERSION_TS });
+    const orphanOverrides = await loadOrphanPolicyOverrides(this);
+    const orphanPages = (islandedRows as { slug: string }[])
+      .filter(row => !shouldExcludeFromOrphanReporting(row.slug, orphanOverrides)).length;
     const deadLinks = Number(r.dead_links);
     const linkCount = Number(r.link_count);
     const pagesWithTimeline = Number(r.pages_with_timeline);
@@ -5279,7 +5282,7 @@ export class PGLiteEngine implements BrainEngine {
     return {
       page_count: pageCount,
       embed_coverage: embedCoverage,
-      stale_pages: Number(r.stale_pages),
+      stale_pages: stalePages,
       orphan_pages: orphanPages,
       missing_embeddings: Number(r.missing_embeddings),
       brain_score: brainScore,

src/core/postgres-engine.ts

@@ -67,37 +67,13 @@ import { resolveBoostMap, resolveHardExcludes } from './search/source-boost.ts';
 import { buildSourceFactorCase, buildHardExcludeClause, buildVisibilityClause, buildRecencyComponentSql, buildBestPerPagePoolCte, buildOrFallbackWebsearchQuery } from './search/sql-ranking.ts';
 import { DEFAULT_EMBEDDING_MODEL, DEFAULT_EMBEDDING_DIMENSIONS } from './ai/defaults.ts';
 import { DELETE_BATCH_SIZE } from './engine-constants.ts';
+import { shouldExcludeFromOrphanReporting, loadOrphanPolicyOverrides } from './orphan-policy.ts';
+import { LINK_EXTRACTOR_VERSION_TS } from './link-extraction.ts';
 
 function escapeSqlStringLiteral(value: string): string {
   return value.replace(/'/g, "''");
 }
 
-/**
- * #2750: race a promise against an AbortSignal, detaching the listener once
- * settled (long-lived drain signals are reused across many calls, so a bare
- * Promise.race would leak one listener per call). The abandoned promise keeps
- * running; used only for pool-acquisition waits where that is harmless.
- */
-function waitForSignal<T>(work: Promise<T>, signal?: AbortSignal): Promise<T> {
-  if (!signal) return work;
-  if (signal.aborted) return Promise.reject(new DOMException('aborted', 'AbortError'));
-  return new Promise<T>((resolve, reject) => {
-    let settled = false;
-    const finish = (fn: () => void) => {
-      if (settled) return;
-      settled = true;
-      signal.removeEventListener('abort', onAbort);
-      fn();
-    };
-    const onAbort = () => finish(() => reject(new DOMException('aborted', 'AbortError')));
-    signal.addEventListener('abort', onAbort, { once: true });
-    work.then(
-      (value) => finish(() => resolve(value)),
-      (err) => finish(() => reject(err)),
-    );
-  });
-}
-
 export function getPostgresSchema(
   dims: number = DEFAULT_EMBEDDING_DIMENSIONS,
   model: string = DEFAULT_EMBEDDING_MODEL,
@@ -1087,12 +1063,7 @@ export class PostgresEngine implements BrainEngine {
     });
   }
 
-  async putPage(
-    slug: string,
-    page: PageInput,
-    opts?: { sourceId?: string; signal?: AbortSignal },
-  ): Promise<Page> {
-    if (opts?.signal?.aborted) throw new DOMException('aborted', 'AbortError');
+  async putPage(slug: string, page: PageInput, opts?: { sourceId?: string }): Promise<Page> {
     slug = validateSlug(slug);
     const sql = this.sql;
     const hash = page.content_hash || contentHash(page);
@@ -1127,7 +1098,7 @@ export class PostgresEngine implements BrainEngine {
     const sourceUri = page.source_uri ?? null;
     const ingestedVia = page.ingested_via ?? null;
     const ingestedAt = (sourceKind || sourceUri || ingestedVia) ? new Date() : null;
-    const pending = sql`
+    const rows = await sql`
       INSERT INTO pages (source_id, slug, type, page_kind, title, compiled_truth, timeline, frontmatter, content_hash, updated_at, effective_date, effective_date_source, import_filename, chunker_version, source_path, source_kind, source_uri, ingested_via, ingested_at)
       VALUES (${sourceId}, ${slug}, ${page.type}, ${pageKind}, ${page.title}, ${page.compiled_truth}, ${page.timeline || ''}, ${sql.json(frontmatter as Parameters<typeof sql.json>[0])}, ${hash}, now(), ${effectiveDate}, ${effectiveDateSource}, ${importFilename}, COALESCE(${chunkerVersion}::smallint, ${MARKDOWN_CHUNKER_VERSION}), ${sourcePath}, ${sourceKind}, ${sourceUri}, ${ingestedVia}, ${ingestedAt})
       ON CONFLICT (source_id, slug) DO UPDATE SET
@@ -1150,22 +1121,6 @@ export class PostgresEngine implements BrainEngine {
         ingested_at           = COALESCE(EXCLUDED.ingested_at,           pages.ingested_at)
       RETURNING id, source_id, slug, type, title, compiled_truth, timeline, frontmatter, content_hash, created_at, updated_at, effective_date, effective_date_source, import_filename, source_kind, source_uri, ingested_via, ingested_at
     `;
-    // #2750: cancel the in-flight statement when the caller's deadline fires,
-    // same .cancel() wiring as runUnsafe (postgres.js pending queries).
-    if (opts?.signal) {
-      const signal = opts.signal;
-      const onAbort = () => {
-        try { (pending as unknown as { cancel?: () => void }).cancel?.(); } catch { /* best-effort */ }
-      };
-      signal.addEventListener('abort', onAbort, { once: true });
-      try {
-        const rows = await pending;
-        return rowToPage(rows[0]);
-      } finally {
-        signal.removeEventListener('abort', onAbort);
-      }
-    }
-    const rows = await pending;
     return rowToPage(rows[0]);
   }
 
@@ -2520,6 +2475,13 @@ export class PostgresEngine implements BrainEngine {
     //   - new is fresher (embedded_at > existing.embedded_at) → take new
     //   - otherwise → keep existing (slower writer with stale embedding loses)
     // Mirrored in pglite-engine.ts; pinned by test/e2e/concurrent-embed-race.test.ts.
+    //
+    // Code-chunk metadata columns (language / symbol_name / symbol_type / line range /
+    // parent_symbol_path / doc_comment / symbol_name_qualified) follow the SAME chunk_text-gated
+    // CASE pattern as `embedding` (#769). Re-chunk (chunk_text changed) trusts EXCLUDED outright;
+    // pure re-embed (chunk_text unchanged) COALESCEs so a caller that only carries embedding
+    // doesn't clobber metadata to NULL. Without this, every embed --stale pass nuked code-def's
+    // primary index for thousands of chunks at once.
     await sql.unsafe(
       `INSERT INTO content_chunks ${cols} VALUES ${rows.join(', ')}
        ON CONFLICT (page_id, chunk_index) DO UPDATE SET
@@ -2543,14 +2505,14 @@ export class PostgresEngine implements BrainEngine {
                 THEN EXCLUDED.embedded_at
            ELSE content_chunks.embedded_at
          END,
-         language = EXCLUDED.language,
-         symbol_name = EXCLUDED.symbol_name,
-         symbol_type = EXCLUDED.symbol_type,
-         start_line = EXCLUDED.start_line,
-         end_line = EXCLUDED.end_line,
-         parent_symbol_path = EXCLUDED.parent_symbol_path,
-         doc_comment = EXCLUDED.doc_comment,
-         symbol_name_qualified = EXCLUDED.symbol_name_qualified,
+         language = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.language ELSE COALESCE(EXCLUDED.language, content_chunks.language) END,
+         symbol_name = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.symbol_name ELSE COALESCE(EXCLUDED.symbol_name, content_chunks.symbol_name) END,
+         symbol_type = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.symbol_type ELSE COALESCE(EXCLUDED.symbol_type, content_chunks.symbol_type) END,
+         start_line = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.start_line ELSE COALESCE(EXCLUDED.start_line, content_chunks.start_line) END,
+         end_line = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.end_line ELSE COALESCE(EXCLUDED.end_line, content_chunks.end_line) END,
+         parent_symbol_path = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.parent_symbol_path ELSE COALESCE(EXCLUDED.parent_symbol_path, content_chunks.parent_symbol_path) END,
+         doc_comment = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.doc_comment ELSE COALESCE(EXCLUDED.doc_comment, content_chunks.doc_comment) END,
+         symbol_name_qualified = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.symbol_name_qualified ELSE COALESCE(EXCLUDED.symbol_name_qualified, content_chunks.symbol_name_qualified) END,
          modality = EXCLUDED.modality,
          embedding_image = COALESCE(EXCLUDED.embedding_image, content_chunks.embedding_image)`,
       params as Parameters<typeof sql.unsafe>[1],
@@ -5360,11 +5322,9 @@ export class PostgresEngine implements BrainEngine {
   async getHealth(): Promise<BrainHealth> {
     const sql = this.sql;
     // Bug 11 doc-drift fix — orphan_pages means "islanded" (no inbound AND
-    // no outbound links), aligning both engines with the user-facing
-    // definition. The type comment previously said "no inbound" but the
-    // SQL required both — docs now match code so users can trust the
-    // number. A hub page that links out to many but has no back-references
-    // is working as intended, not an orphan.
+    // no outbound links). The raw islanded list is filtered through the same
+    // policy as `gbrain orphans` so convention pages do not count against
+    // dashboard health.
     const [h] = await sql`
       WITH entity_pages AS (
         SELECT id, slug FROM pages WHERE type IN ('person', 'company')
@@ -5373,13 +5333,8 @@ export class PostgresEngine implements BrainEngine {
         (SELECT count(*) FROM pages) as page_count,
         (SELECT count(*) FROM content_chunks WHERE embedded_at IS NOT NULL)::float /
           GREATEST((SELECT count(*) FROM content_chunks), 1)::float as embed_coverage,
-        (SELECT count(*) FROM pages p
-         WHERE p.updated_at < (SELECT MAX(te.created_at) FROM timeline_entries te WHERE te.page_id = p.id)
-        ) as stale_pages,
-        (SELECT count(*) FROM pages p
-         WHERE NOT EXISTS (SELECT 1 FROM links l WHERE l.to_page_id = p.id)
-           AND NOT EXISTS (SELECT 1 FROM links l WHERE l.from_page_id = p.id)
-        ) as orphan_pages,
+        0 as stale_pages,
+        0 as orphan_pages,
         (SELECT count(*) FROM links l
          WHERE NOT EXISTS (SELECT 1 FROM pages p WHERE p.id = l.to_page_id)
         ) as dead_links,
@@ -5403,9 +5358,18 @@ export class PostgresEngine implements BrainEngine {
       LIMIT 5
     `;
 
+    const islandedRows = await sql<{ slug: string }[]>`
+      SELECT p.slug
+      FROM pages p
+      WHERE NOT EXISTS (SELECT 1 FROM links l WHERE l.to_page_id = p.id)
+        AND NOT EXISTS (SELECT 1 FROM links l WHERE l.from_page_id = p.id)
+    `;
+
     const pageCount = Number(h.page_count);
     const embedCoverage = Number(h.embed_coverage);
-    const orphanPages = Number(h.orphan_pages);
+    const stalePages = await this.countStalePagesForExtraction({ versionTs: LINK_EXTRACTOR_VERSION_TS });
+    const orphanOverrides = await loadOrphanPolicyOverrides(this);
+    const orphanPages = islandedRows.filter(row => !shouldExcludeFromOrphanReporting(row.slug, orphanOverrides)).length;
     const deadLinks = Number(h.dead_links);
     const linkCount = Number(h.link_count);
     const pagesWithTimeline = Number(h.pages_with_timeline);
@@ -5433,7 +5397,7 @@ export class PostgresEngine implements BrainEngine {
     return {
       page_count: pageCount,
       embed_coverage: embedCoverage,
-      stale_pages: Number(h.stale_pages),
+      stale_pages: stalePages,
       orphan_pages: orphanPages,
       missing_embeddings: Number(h.missing_embeddings),
       brain_score: brainScore,
@@ -5854,16 +5818,11 @@ export class PostgresEngine implements BrainEngine {
     params?: unknown[],
     opts?: { signal?: AbortSignal },
   ): Promise<T[]> {
-    // #2750: an already-fired signal short-circuits BEFORE any pool routing,
-    // and the direct-pool acquisition itself is signal-bounded — under pooler
-    // exhaustion `ddl()` can stall indefinitely, which used to make even a
-    // "bounded" lock release hang past its caller's deadline.
-    if (opts?.signal?.aborted) throw new DOMException('aborted', 'AbortError');
     // Inside an open transaction, _sql is the reserved tx connection (set via
     // defineProperty in transaction()); never reroute off it.
     const inTransaction = this._sql !== null && this.connectionManager?.peekReadPool() !== this._sql;
     const conn = (!inTransaction && this.connectionManager?.isDualPoolActive())
-      ? await waitForSignal(this.connectionManager.ddl(), opts?.signal)
+      ? await this.connectionManager.ddl()
       : this.sql;
     return this.runUnsafe<T>(conn, sql, params, opts);
   }

src/core/skillopt/orchestrator.ts

@@ -93,7 +93,13 @@ 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, bestPath, revertAllPending, skillPath, writeProposed } from './version-store.ts';
+import {
+  acceptCandidate,
+  proposedPath as proposedFilePath,
+  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';
@@ -702,9 +708,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') {
-    // 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);
+    // writeProposed() emitted both the best pointer and the stable review
+    // artifact in the accept branch. SKILL.md remains untouched.
+    proposedPath = proposedFilePath(skillsDir, skillName);
   } else if (mutateDecision.mutate) {
     mutatedSkillFile = finalOutcome === 'accepted';
   }

src/core/skillopt/version-store.ts

@@ -23,6 +23,7 @@
  *
  *   history.json
  *   best.md
+ *   proposed.md
  *   versions/
  *     v0001_e1_s1.md
  *     v0002_e1_s2.md
@@ -52,6 +53,10 @@ 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');
 }
@@ -171,17 +176,18 @@ export function acceptCandidate(input: AcceptInput): AcceptResult {
 }
 
 /**
- * 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).
+ * 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).
  */
 export function writeProposed(skillsDir: string, skillName: string, candidateText: string): string {
-  const p = bestPath(skillsDir, skillName);
-  fs.mkdirSync(path.dirname(p), { recursive: true });
-  atomicWrite(p, candidateText);
-  return p;
+  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;
 }
 
 /**

src/openclaw-context-engine.ts

@@ -63,25 +63,26 @@ interface PluginCtx {
   [key: string]: unknown;
 }
 
+export function register(api: PluginApi) {
+  api.registerContextEngine(ENGINE_ID, (ctx: PluginCtx) => {
+    const hostResolver =
+      typeof ctx.resolveEntities === 'function'
+        ? ctx.resolveEntities
+        : typeof ctx.brainQuery === 'function'
+          ? ctx.brainQuery
+          : undefined;
+    return createGBrainContextEngine({
+      workspaceDir: ctx.workspaceDir,
+      resolveEntities: hostResolver,
+    });
+  });
+}
+
 const entry: PluginEntry = {
   id: 'gbrain-context-engine',
   name: 'GBrain Context Engine',
   description: 'Deterministic temporal/spatial context injection on every turn',
-
-  register(api: PluginApi) {
-    api.registerContextEngine(ENGINE_ID, (ctx: PluginCtx) => {
-      const hostResolver =
-        typeof ctx.resolveEntities === 'function'
-          ? ctx.resolveEntities
-          : typeof ctx.brainQuery === 'function'
-            ? ctx.brainQuery
-            : undefined;
-      return createGBrainContextEngine({
-        workspaceDir: ctx.workspaceDir,
-        resolveEntities: hostResolver,
-      });
-    });
-  },
+  register,
 };
 
 export default entry;

test/bench-cli-dispatch.test.ts

@@ -0,0 +1,67 @@
+// #1474: the v0.41.1 wave shipped bench-publish.ts + docs/eval-bench.md
+// advertising `gbrain bench publish`, but the cli.ts dispatcher case was never
+// added — the documented command hit 'Unknown command'. These tests spawn the
+// real CLI (no DB needed; bench publish is pure file I/O) and fail on any
+// regression of the dispatcher wiring.
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+function runCli(args: string[]): { stdout: string; stderr: string; code: number } {
+  const result = spawnSync(process.execPath, ['run', 'src/cli.ts', 'bench', ...args], {
+    encoding: 'utf8',
+    cwd: process.cwd(),
+    env: { ...process.env },
+  });
+  return { stdout: result.stdout ?? '', stderr: result.stderr ?? '', code: result.status ?? -1 };
+}
+
+describe('gbrain bench dispatcher (#1474)', () => {
+  test('bench --help reaches bench-publish help without a DB (was: Unknown command)', () => {
+    const { stdout, stderr, code } = runCli(['--help']);
+    expect(stderr).not.toContain('Unknown command');
+    expect(code).toBe(0);
+    expect(stdout).toContain('gbrain bench publish');
+    expect(stdout).toContain('--from');
+  });
+
+  test('unknown bench subcommand exits 2 with usage', () => {
+    const { stderr, code } = runCli(['bogus']);
+    expect(code).toBe(2);
+    expect(stderr).toContain('Unknown bench subcommand');
+    expect(stderr).toContain('bench publish');
+  });
+
+  test('bench publish roundtrip: captured NDJSON in, baseline file out', () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'bench-cli-'));
+    try {
+      const row = {
+        tool_name: 'query',
+        query: 'hello world',
+        retrieved_slugs: ['slug-a'],
+        retrieved_chunk_ids: [1],
+        source_ids: ['default'],
+        expand_enabled: false,
+        detail: 'medium',
+        detail_resolved: 'medium',
+        vector_enabled: true,
+        expansion_applied: false,
+        latency_ms: 100,
+        remote: false,
+        job_id: null,
+        subagent_id: null,
+      };
+      const from = join(tmp, 'captured.ndjson');
+      const to = join(tmp, 'personal.baseline.ndjson');
+      writeFileSync(from, `${JSON.stringify(row)}\n`);
+      const { code, stderr } = runCli(['publish', '--from', from, '--to', to]);
+      expect(stderr).not.toContain('Unknown command');
+      expect(code).toBe(0);
+      expect(existsSync(to)).toBe(true);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

test/cycle/extract-atoms-synthesize-concepts.test.ts

@@ -17,7 +17,6 @@ import { runPhaseExtractAtoms, parseAtomsResponse } from '../../src/core/cycle/e
 import { runPhaseSynthesizeConcepts } from '../../src/core/cycle/synthesize-concepts.ts';
 import { resetPgliteState } from '../helpers/reset-pglite.ts';
 import type { ChatResult, ChatOpts } from '../../src/core/ai/gateway.ts';
-import type { BrainEngine } from '../../src/core/engine.ts';
 
 let engine: PGLiteEngine;
 
@@ -178,180 +177,6 @@ describe('v0.41 T5: runPhaseExtractAtoms via stubbed chat', () => {
     expect((result.details?.failures as unknown[]).length).toBe(1);
   });
 
-  // ── #2750: caller deadline bounds the phase ────────────────────────────
-
-  test('caller deadline aborts a hung chat before processing the next item', async () => {
-    let calls = 0;
-    const chat = async (opts: ChatOpts) => {
-      calls++;
-      return await new Promise<never>((_resolve, reject) => {
-        const signal = opts.abortSignal;
-        if (!signal) return reject(new Error('missing abort signal'));
-        if (signal.aborted) return reject(signal.reason);
-        signal.addEventListener('abort', () => reject(signal.reason), { once: true });
-      });
-    };
-    const started = Date.now();
-    const result = await runPhaseExtractAtoms(engine, {
-      _transcripts: [
-        { filePath: '/hung.txt', content: 'a', contentHash: 'hung-a' },
-        { filePath: '/never.txt', content: 'b', contentHash: 'hung-b' },
-      ],
-      _pages: [],
-      _chat: chat as typeof import('../../src/core/ai/gateway.ts').chat,
-      abortSignal: AbortSignal.timeout(25),
-    });
-    expect(Date.now() - started).toBeLessThan(2_000);
-    expect(calls).toBe(1);
-    expect(result.status).toBe('ok');
-    expect(result.details?.deadline_aborted).toBe(true);
-    expect(result.details?.atoms_extracted).toBe(0);
-    expect(result.details?.failures).toEqual([]);
-  });
-
-  test('billable chat usage is counted when the deadline fires as the response resolves', async () => {
-    const controller = new AbortController();
-    const chat = async (opts: ChatOpts): Promise<ChatResult> => {
-      controller.abort(new DOMException('deadline', 'TimeoutError'));
-      return stubChat(`[{"title":"late","atom_type":"insight","body":"b"}]`, {
-        input_tokens: 1_000,
-        output_tokens: 500,
-      })(opts);
-    };
-    const result = await runPhaseExtractAtoms(engine, {
-      _transcripts: [{ filePath: '/late.txt', content: 'a', contentHash: 'late' }],
-      _pages: [],
-      _chat: chat,
-      abortSignal: controller.signal,
-    });
-    expect(result.details?.deadline_aborted).toBe(true);
-    expect(Number(result.details?.estimated_spend_usd)).toBeGreaterThan(0);
-    expect(result.details?.atoms_extracted).toBe(0);
-  });
-
-  test('deadline after partial progress still writes receipt and incomplete rollup', async () => {
-    const controller = new AbortController();
-    let calls = 0;
-    let notifySecondChat!: () => void;
-    const secondChatStarted = new Promise<void>((resolve) => { notifySecondChat = resolve; });
-    const chat = async (opts: ChatOpts): Promise<ChatResult> => {
-      calls++;
-      if (calls === 1) {
-        return stubChat(`[{"title":"committed","atom_type":"insight","body":"b"}]`)(opts);
-      }
-      notifySecondChat();
-      return await new Promise<never>((_resolve, reject) => {
-        const signal = opts.abortSignal;
-        if (!signal) return reject(new Error('missing abort signal'));
-        signal.addEventListener('abort', () => reject(signal.reason), { once: true });
-      });
-    };
-
-    const pending = runPhaseExtractAtoms(engine, {
-      _transcripts: [
-        { filePath: '/committed.txt', content: 'a', contentHash: 'committed-a' },
-        { filePath: '/hung.txt', content: 'b', contentHash: 'hung-b' },
-      ],
-      _pages: [],
-      _chat: chat,
-      abortSignal: controller.signal,
-    });
-    await secondChatStarted;
-    controller.abort(new DOMException('deadline', 'TimeoutError'));
-    const result = await pending;
-
-    const atoms = await engine.executeRaw<{ n: number }>(
-      `SELECT COUNT(*)::int AS n FROM pages WHERE type = 'atom'`,
-    );
-    const receipts = await engine.executeRaw<{ n: number }>(
-      `SELECT COUNT(*)::int AS n FROM pages WHERE type = 'extract_receipt'`,
-    );
-    const rollups = await engine.executeRaw<{
-      cost_usd: string | number;
-      round_completed_count: string | number;
-    }>(
-      `SELECT cost_usd, round_completed_count
-         FROM extract_rollup_7d
-        WHERE kind = 'atoms' AND source_id = 'default'`,
-    );
-    expect(result.details?.deadline_aborted).toBe(true);
-    expect(atoms[0].n).toBe(1);
-    expect(receipts[0].n).toBe(1);
-    expect(Number(rollups[0].cost_usd)).toBeGreaterThan(0);
-    expect(Number(rollups[0].round_completed_count)).toBe(0);
-  });
-
-  test('bookkeeping runs on a fresh grace signal, not the fired work deadline', async () => {
-    const controller = new AbortController();
-    let putCalls = 0;
-    let receiptSignal: AbortSignal | undefined;
-    let rollupSignal: AbortSignal | undefined;
-    const signalAwareEngine = {
-      executeRaw: async (sql: string, _params?: unknown[], opts?: { signal?: AbortSignal }) => {
-        if (sql.includes('INSERT INTO extract_rollup_7d')) rollupSignal = opts?.signal;
-        return [];
-      },
-      putPage: async (_slug: string, _page: unknown, opts?: { signal?: AbortSignal }) => {
-        putCalls++;
-        if (putCalls === 1) {
-          // Atom write in flight; the work deadline fires before bookkeeping.
-          controller.abort(new DOMException('work deadline', 'TimeoutError'));
-        } else {
-          receiptSignal = opts?.signal;
-        }
-        return {};
-      },
-    } as unknown as BrainEngine;
-
-    const result = await runPhaseExtractAtoms(signalAwareEngine, {
-      _transcripts: [{ filePath: '/one.txt', content: 'a', contentHash: 'one' }],
-      _pages: [],
-      _chat: stubChat(`[{"title":"one","atom_type":"insight","body":"b"}]`),
-      abortSignal: controller.signal,
-    });
-
-    expect(result.details?.atoms_extracted).toBe(1);
-    expect(putCalls).toBe(2); // atom write + receipt write
-    expect(receiptSignal).toBeDefined();
-    expect(receiptSignal).not.toBe(controller.signal);
-    expect(receiptSignal?.aborted).toBe(false);
-    expect(rollupSignal).toBe(receiptSignal);
-  });
-
-  test('caller deadline cancels a hung atom write and stops the phase', async () => {
-    const controller = new AbortController();
-    let notifyWriteStarted!: () => void;
-    const writeStarted = new Promise<void>((resolve) => { notifyWriteStarted = resolve; });
-    let writeCalls = 0;
-    const signalAwareEngine = {
-      executeRaw: async () => [],
-      putPage: async (_slug: string, _page: unknown, opts?: { signal?: AbortSignal }) => {
-        writeCalls++;
-        notifyWriteStarted();
-        return await new Promise<never>((_resolve, reject) => {
-          const signal = opts?.signal;
-          if (!signal) return reject(new Error('missing abort signal'));
-          if (signal.aborted) return reject(signal.reason);
-          signal.addEventListener('abort', () => reject(signal.reason), { once: true });
-        });
-      },
-    } as unknown as BrainEngine;
-
-    const pending = runPhaseExtractAtoms(signalAwareEngine, {
-      _transcripts: [{ filePath: '/hung-write.txt', content: 'a', contentHash: 'hung-write' }],
-      _pages: [],
-      _chat: stubChat(`[{"title":"hung write","atom_type":"insight","body":"b"}]`),
-      abortSignal: controller.signal,
-    });
-    await writeStarted;
-    controller.abort(new DOMException('deadline', 'TimeoutError'));
-    const result = await pending;
-
-    expect(writeCalls).toBe(1);
-    expect(result.details?.deadline_aborted).toBe(true);
-    expect(result.details?.atoms_extracted).toBe(0);
-  });
-
   // v0.41.2.1 regression case (D9 #14 wording): with _pages:[] and same
   // _transcripts, all PRE-EXISTING PhaseResult.details fields match
   // pre-fix values byte-for-byte. The new fields (pages_processed,

test/e2e/global-basename-pglite.test.ts

@@ -172,6 +172,59 @@ describe('issue #972 — DB-source (gbrain extract links --source db)', () => {
     expect(strk!.link_type).toBe('wikilink_basename');
   });
 
+  test('flag ON → path-qualified wikilink outside DIR_PATTERN resolves via DB path', async () => {
+    // `[[notes/struktura]]` — `notes` is not in DIR_PATTERN, so the ref
+    // reaches the generic pass with its dirname intact. Regression: the DB
+    // path queried the basename index with the raw literal (which is keyed
+    // by final segments only), so path-qualified wikilinks outside
+    // DIR_PATTERN silently produced zero edges while the FS path resolved
+    // the identical content.
+    await engine.putPage('notes/struktura', {
+      type: 'concept' as any, title: 'Struktura Notes',
+      compiled_truth: '', timeline: '',
+    });
+    await engine.putPage('concepts/knowledge-graph', {
+      type: 'concept', title: 'Knowledge Graph',
+      compiled_truth: 'Background in [[notes/struktura]].', timeline: '',
+    });
+    await engine.setConfig('link_resolution.global_basename', 'true');
+
+    await runExtract(engine, ['links', '--source', 'db']);
+
+    const outLinks = await engine.getLinks('concepts/knowledge-graph');
+    const strk = outLinks.find(l => l.to_slug === 'notes/struktura');
+    expect(strk).toBeDefined();
+    expect(strk!.link_type).toBe('wikilink_basename');
+    expect(strk!.link_source).toBe('wikilink-resolved');
+  });
+
+  test('path-qualified wikilink never attaches to a basename-only sibling', async () => {
+    // Both notes/struktura and wiki/struktura exist. The author wrote
+    // `[[notes/struktura]]` — the written path must exclude wiki/struktura
+    // (a bare `[[struktura]]` would legitimately match both).
+    await engine.putPage('notes/struktura', {
+      type: 'concept' as any, title: 'Struktura Notes',
+      compiled_truth: '', timeline: '',
+    });
+    await engine.putPage('wiki/struktura', {
+      type: 'concept' as any, title: 'Struktura Wiki',
+      compiled_truth: '', timeline: '',
+    });
+    await engine.putPage('concepts/x', {
+      type: 'concept', title: 'X',
+      compiled_truth: 'See [[notes/struktura]].', timeline: '',
+    });
+    await engine.setConfig('link_resolution.global_basename', 'true');
+
+    await runExtract(engine, ['links', '--source', 'db']);
+
+    const outLinks = await engine.getLinks('concepts/x');
+    const basenameLinks = outLinks
+      .filter(l => l.link_type === 'wikilink_basename')
+      .map(l => l.to_slug);
+    expect(basenameLinks).toEqual(['notes/struktura']);
+  });
+
   test('flag OFF → no basename edges via DB path (back-compat)', async () => {
     await engine.putPage('projects/struktura', {
       type: 'project', title: 'Struktura',

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

@@ -39,6 +39,7 @@ 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';
@@ -741,7 +742,7 @@ describe('skillopt T3 — F11 held-out gate, ablation opts, no-DB-pollution', ()
     } finally { fixture.cleanup(); }
   });
 
-  test('--no-mutate writes proposed.md (best.md), leaves SKILL.md untouched', async () => {
+  test('--no-mutate writes proposed.md and best.md, leaves SKILL.md untouched', async () => {
     const fixture = setupFixture(SKILL_PEOPLE_ONLY, CITATIONS_BENCHMARK);
     try {
       installStub({
@@ -753,10 +754,9 @@ 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).toBeDefined();
-          // proposed.md (best.md) exists and carries the improvement.
-          expect(fs.existsSync(result.proposedPath!)).toBe(true);
+          expect(result.proposedPath).toBe(proposedPath(fixture.skillsDir, SKILL));
           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/embed.serial.test.ts

@@ -803,3 +803,107 @@ describe('embedAllStale --source threading (D7)', () => {
     expect((firstCallOpts as { sourceId?: string }).sourceId).toBe('media-corpus');
   });
 });
+
+// ────────────────────────────────────────────────────────────────
+// Code metadata preservation across re-embed (regression for #769)
+// ────────────────────────────────────────────────────────────────
+//
+// gbrain v0.30.1 and earlier silently clobbered code-chunk metadata
+// (language, symbol_name, symbol_type, start_line, end_line,
+// parent_symbol_path, doc_comment, symbol_name_qualified) on every
+// re-embed pass. The chunker populated those columns at import time,
+// but embed.ts loaded chunks via getChunks then mapped them to a
+// stripped ChunkInput carrying only 5 fields. upsertChunks then
+// OVERWROTE (not COALESCEd) the metadata columns from EXCLUDED, so
+// re-embed wiped them to NULL. End result on a real brain: 4875 code
+// pages, 47866 chunks, all with NULL language/symbol_name/symbol_type;
+// code-def returned 0 hits across every indexed repo.
+//
+// All three runEmbed paths (--stale autopilot, --all, --slugs) must
+// thread metadata through the re-upsert. Tests below assert that the
+// engine.upsertChunks call carries the same metadata it loaded.
+
+describe('runEmbed preserves code-chunk metadata across re-embed (regression for #769)', () => {
+  const fullCodeChunk = {
+    chunk_index: 0,
+    chunk_text: '[Java] foo/Bar.java:10-20 method baz',
+    chunk_source: 'compiled_truth' as const,
+    embedded_at: null,
+    token_count: 12,
+    language: 'java',
+    symbol_name: 'baz',
+    symbol_type: 'function',
+    start_line: 10,
+    end_line: 20,
+    parent_symbol_path: ['Bar'],
+    doc_comment: 'does the thing',
+    symbol_name_qualified: 'Bar.baz',
+  };
+
+  function metadataOf(chunk: any) {
+    return {
+      language: chunk.language,
+      symbol_name: chunk.symbol_name,
+      symbol_type: chunk.symbol_type,
+      start_line: chunk.start_line,
+      end_line: chunk.end_line,
+      parent_symbol_path: chunk.parent_symbol_path,
+      doc_comment: chunk.doc_comment,
+      symbol_name_qualified: chunk.symbol_name_qualified,
+    };
+  }
+
+  test('--stale (autopilot path) carries code metadata into upsertChunks', async () => {
+    const stale = [{
+      slug: 'code-page',
+      chunk_index: 0,
+      chunk_text: fullCodeChunk.chunk_text,
+      chunk_source: 'compiled_truth',
+      model: null,
+      token_count: 12,
+    }];
+    let upsertChunkArgs: any[] | null = null;
+    const engine = mockEngine({
+      countStaleChunks: async () => 1,
+      listStaleChunks: async () => stale,
+      getChunks: async () => [fullCodeChunk],
+      upsertChunks: async (_slug: string, chunks: any[]) => { upsertChunkArgs = chunks; },
+    });
+
+    await runEmbed(engine, ['--stale']);
+
+    expect(upsertChunkArgs).not.toBeNull();
+    expect(upsertChunkArgs!).toHaveLength(1);
+    expect(metadataOf(upsertChunkArgs![0])).toEqual(metadataOf(fullCodeChunk));
+  });
+
+  test('--all (full re-embed) carries code metadata into upsertChunks', async () => {
+    let upsertChunkArgs: any[] | null = null;
+    const engine = mockEngine({
+      listPages: async () => [{ slug: 'code-page' }],
+      getChunks: async () => [fullCodeChunk],
+      upsertChunks: async (_slug: string, chunks: any[]) => { upsertChunkArgs = chunks; },
+    });
+
+    await runEmbed(engine, ['--all']);
+
+    expect(upsertChunkArgs).not.toBeNull();
+    expect(upsertChunkArgs!).toHaveLength(1);
+    expect(metadataOf(upsertChunkArgs![0])).toEqual(metadataOf(fullCodeChunk));
+  });
+
+  test('--slugs (per-page embed) carries code metadata into upsertChunks', async () => {
+    let upsertChunkArgs: any[] | null = null;
+    const engine = mockEngine({
+      getPage: async () => ({ slug: 'code-page', compiled_truth: 'x', timeline: '' }),
+      getChunks: async () => [fullCodeChunk],
+      upsertChunks: async (_slug: string, chunks: any[]) => { upsertChunkArgs = chunks; },
+    });
+
+    await runEmbed(engine, ['--slugs', 'code-page']);
+
+    expect(upsertChunkArgs).not.toBeNull();
+    expect(upsertChunkArgs!).toHaveLength(1);
+    expect(metadataOf(upsertChunkArgs![0])).toEqual(metadataOf(fullCodeChunk));
+  });
+});

test/eval-capture.test.ts

@@ -309,3 +309,62 @@ describe('isEvalCaptureEnabled / isEvalScrubEnabled (CONTRIBUTOR_MODE-gated)', (
     } finally { restore(); }
   });
 });
+
+describe('DB-plane stash (#1475): GBRAIN_EVAL_CAPTURE / GBRAIN_EVAL_SCRUB_PII', () => {
+  // connectEngine stamps `gbrain config set eval.capture` (DB plane) onto
+  // these env vars because ctx.config is the sync file-plane load. Without
+  // the stash check the DB value was written and never read.
+  const origCapture = process.env.GBRAIN_EVAL_CAPTURE;
+  const origScrub = process.env.GBRAIN_EVAL_SCRUB_PII;
+  const origMode = process.env.GBRAIN_CONTRIBUTOR_MODE;
+  const restore = () => {
+    if (origCapture === undefined) delete process.env.GBRAIN_EVAL_CAPTURE;
+    else process.env.GBRAIN_EVAL_CAPTURE = origCapture;
+    if (origScrub === undefined) delete process.env.GBRAIN_EVAL_SCRUB_PII;
+    else process.env.GBRAIN_EVAL_SCRUB_PII = origScrub;
+    if (origMode === undefined) delete process.env.GBRAIN_CONTRIBUTOR_MODE;
+    else process.env.GBRAIN_CONTRIBUTOR_MODE = origMode;
+  };
+
+  test('stash=true turns capture on when file plane is silent (the #1475 repro)', () => {
+    delete process.env.GBRAIN_CONTRIBUTOR_MODE;
+    process.env.GBRAIN_EVAL_CAPTURE = 'true';
+    try {
+      expect(isEvalCaptureEnabled(null)).toBe(true);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const noEval: any = { engine: 'pglite' };
+      expect(isEvalCaptureEnabled(noEval)).toBe(true);
+    } finally { restore(); }
+  });
+
+  test('stash=false wins over CONTRIBUTOR_MODE=1 (explicit per-key beats broad flag)', () => {
+    process.env.GBRAIN_CONTRIBUTOR_MODE = '1';
+    process.env.GBRAIN_EVAL_CAPTURE = 'false';
+    try {
+      expect(isEvalCaptureEnabled(null)).toBe(false);
+    } finally { restore(); }
+  });
+
+  test('file-plane explicit value still wins over the stash', () => {
+    process.env.GBRAIN_EVAL_CAPTURE = 'true';
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const disabled: any = { engine: 'pglite', eval: { capture: false } };
+      expect(isEvalCaptureEnabled(disabled)).toBe(false);
+    } finally { restore(); }
+  });
+
+  test('scrub stash: false disables, file plane wins, default stays true', () => {
+    process.env.GBRAIN_EVAL_SCRUB_PII = 'false';
+    try {
+      expect(isEvalScrubEnabled(null)).toBe(false);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const fileWins: any = { engine: 'pglite', eval: { scrub_pii: true } };
+      expect(isEvalScrubEnabled(fileWins)).toBe(true);
+    } finally { restore(); }
+    delete process.env.GBRAIN_EVAL_SCRUB_PII;
+    try {
+      expect(isEvalScrubEnabled(null)).toBe(true);
+    } finally { restore(); }
+  });
+});

test/extract-atoms-drain.test.ts

@@ -43,135 +43,26 @@ describe('runExtractAtomsDrain (issue #1678)', () => {
     expect(batches).toBe(3);
   });
 
-  it('stops at the wallclock window; remaining is unknown (no post-window count)', async () => {
-    // Each batch consumes 60ms of the 100ms window: two batches fit, the
-    // third boundary check sees 120 ≥ 100 and stops. #2750: after the window
-    // elapses the final countRemaining is SKIPPED (it would overrun the
-    // window), so remaining reports null.
-    let now = 0;
+  it('stops at the wallclock window with remaining > 0', async () => {
+    // SYNC stepping clock: now() #1 sets deadline (0+100=100); the while-check
+    // then sees 50, 50 (two batches), then 999999 → past deadline → stop.
+    const times = [0, 50, 50, 999_999];
+    let ti = 0;
+    const now = () => times[Math.min(ti++, times.length - 1)];
     const result = await runExtractAtomsDrain(
       {
         withLock: passThroughLock,
         countRemaining: async () => 5, // never drains
-        runBatch: async () => {
-          now += 60;
-          return { extracted: 1, skipped: 0 };
-        },
-        now: () => now,
+        runBatch: async () => ({ extracted: 1, skipped: 0 }),
+        now,
       },
       { windowMs: 100 },
     );
     expect(result.stopped).toBe('window');
-    expect(result.remaining).toBeNull();
+    expect(result.remaining).toBe(5);
     expect(result.batches).toBe(2);
   });
 
-  it('passes one drain-level deadline signal into count and batch', async () => {
-    const seen: AbortSignal[] = [];
-    const controller = new AbortController();
-    let now = 0;
-    const result = await runExtractAtomsDrain(
-      {
-        withLock: passThroughLock,
-        countRemaining: async (signal) => {
-          seen.push(signal);
-          return 5;
-        },
-        runBatch: async (signal) => {
-          seen.push(signal);
-          now = 100;
-          return { extracted: 1, skipped: 0 };
-        },
-        now: () => now,
-      },
-      { windowMs: 100, abortSignal: controller.signal },
-    );
-    expect(result.stopped).toBe('window');
-    expect(result.batches).toBe(1);
-    expect(seen.length).toBe(2);
-    expect(seen[0]).toBe(seen[1]);
-    // Combined (timeout + external) signal, not the raw external one.
-    expect(seen[0]).not.toBe(controller.signal);
-  });
-
-  it('aborts a hung backlog count at the window deadline and releases the lock', async () => {
-    let released = false;
-    const result = await runExtractAtomsDrain(
-      {
-        withLock: async (work) => {
-          try { return await work(); }
-          finally { released = true; }
-        },
-        // Hangs until the drain's real-time deadline signal fires (10ms).
-        countRemaining: (signal) => new Promise((_resolve, reject) => {
-          signal.addEventListener('abort', () => reject(signal.reason), { once: true });
-        }),
-        runBatch: async () => ({ extracted: 0, skipped: 0 }),
-        now: () => 0, // injected clock never advances — the SIGNAL must save us
-      },
-      { windowMs: 10 },
-    );
-    expect(result.stopped).toBe('window');
-    expect(result.remaining).toBeNull();
-    expect(released).toBe(true);
-  });
-
-  it('rethrows external cancellation after releasing the lock', async () => {
-    const controller = new AbortController();
-    let released = false;
-    const pending = runExtractAtomsDrain(
-      {
-        withLock: async (work) => {
-          try { return await work(); }
-          finally { released = true; }
-        },
-        countRemaining: (signal) => new Promise((_resolve, reject) => {
-          signal.addEventListener('abort', () => reject(signal.reason), { once: true });
-        }),
-        runBatch: async () => ({ extracted: 0, skipped: 0 }),
-        now: () => 0,
-      },
-      { windowMs: 1_000_000, abortSignal: controller.signal },
-    );
-    controller.abort(new DOMException('worker timeout', 'AbortError'));
-    await expect(pending).rejects.toThrow('worker timeout');
-    expect(released).toBe(true);
-  });
-
-  it('classifies a deadline-exhausted zero-progress batch as window, not no_progress', async () => {
-    let now = 0;
-    const result = await runExtractAtomsDrain(
-      {
-        withLock: passThroughLock,
-        countRemaining: async () => 5,
-        runBatch: async () => {
-          now = 100; // batch consumed the whole window and returned nothing
-          return { extracted: 0, skipped: 0 };
-        },
-        now: () => now,
-      },
-      { windowMs: 100 },
-    );
-    expect(result.stopped).toBe('window');
-    expect(result.batches).toBe(1);
-  });
-
-  it('bounds a hung lock acquisition with the drain deadline signal', async () => {
-    const started = Date.now();
-    await expect(runExtractAtomsDrain(
-      {
-        withLock: (_work, signal) => new Promise((_resolve, reject) => {
-          signal.addEventListener('abort', () => reject(signal.reason), { once: true });
-        }),
-        countRemaining: async () => 1,
-        runBatch: async () => ({ extracted: 0, skipped: 0 }),
-        now: Date.now,
-      },
-      { windowMs: 10 },
-    )).rejects.toThrow();
-    expect(Date.now() - started).toBeLessThan(1_000);
-  });
-
   it('stops on a zero-progress batch (no hot loop)', async () => {
     let batches = 0;
     const result = await runExtractAtomsDrain(
@@ -242,17 +133,4 @@ describe('shared wiring helper holds the cycle lock (5A)', () => {
     expect(src).toContain('cycleLockIdFor(opts.sourceId)');
     expect(src).toContain('withRefreshingLock(engine, lockId');
   });
-
-  // #2750: the deadline signal must reach the phase, the backlog count, AND
-  // the lock wrapper — and the transcript path (brainDir) must stay wired
-  // exactly as the routine callers expect (PR #2752 takeover reverted its
-  // unsanctioned transcript-suppression scope change).
-  it('threads the drain deadline signal through phase, count, and lock', () => {
-    const jobsSrc = readFileSync(join(import.meta.dir, '../src/commands/jobs.ts'), 'utf8');
-    expect(src).toContain('abortSignal: signal');
-    expect(src).toContain('countExtractAtomsBacklog(engine, extractionSourceId, signal)');
-    expect(src).toContain('brainDir: opts.brainDir');
-    expect(src).not.toContain('_transcripts');
-    expect(jobsSrc).toContain('abortSignal: job.signal');
-  });
 });

test/fixtures/supervisor-runner.ts

@@ -24,18 +24,15 @@ import type { BrainEngine } from '../../src/core/engine.ts';
 // Mock engine: healthCheck() calls engine.executeRaw; return empty rows so
 // the query path exercises without needing Postgres.
 //
-// #1849: start() acquires the queue-scoped DB singleton lock via
-// tryAcquireDbLock. #2750 routed the acquire upsert through engine.executeRaw
-// (signal-boundable) and release through engine.executeRawDirect, so the
-// stub returns a single row from the lock upsert (length 1 → acquired) and
-// empty rows everywhere else. Each spawned runner is a fresh process, so
-// there's no cross-test lock state to clean up.
+// #1849: start() now acquires the queue-scoped DB singleton lock via
+// tryAcquireDbLock, which uses the postgres `sql` tagged-template escape hatch.
+// The stub returns a single row from every call so acquire succeeds (length 1
+// → acquired) and refresh/release are no-ops. Each spawned runner is a fresh
+// process, so there's no cross-test lock state to clean up.
 const sqlStub = (..._args: unknown[]) => Promise.resolve([{ id: 'supervisor-lock' }]);
 const mockEngine: Partial<BrainEngine> = {
   kind: 'postgres' as const,
-  executeRaw: async (query: string) =>
-    query.includes('gbrain_cycle_locks') ? [{ id: 'supervisor-lock' }] : [],
-  executeRawDirect: async () => [],
+  executeRaw: async () => [],
   sql: sqlStub,
 } as unknown as BrainEngine;
 

test/link-extraction.test.ts

@@ -403,6 +403,77 @@ describe('extractPageLinks', () => {
     expect(candidates).toEqual([]);
   });
 
+  test('path-qualified wikilink outside DIR_PATTERN queries by final segment', async () => {
+    // `[[notes/struktura]]` (dir not in DIR_PATTERN) falls to the generic
+    // pass. The resolver's basename index is keyed by final path segments,
+    // so the lookup must strip the dirname — mirroring the FS path
+    // (resolveSlugAll). Regression: the raw literal was passed through,
+    // which never matched, so these links silently dropped.
+    const seen: string[] = [];
+    const resolver: SlugResolver = {
+      resolve: async () => null,
+      resolveBasenameMatches: async (name) => {
+        seen.push(name);
+        return name === 'struktura' ? ['notes/struktura'] : [];
+      },
+    };
+    const { candidates } = await extractPageLinks(
+      'concepts/x', 'See [[notes/struktura]].',
+      {}, 'concept', resolver, { globalBasename: true },
+    );
+    expect(seen).toContain('struktura');
+    expect(seen).not.toContain('notes/struktura');
+    expect(candidates.map(c => c.targetSlug)).toEqual(['notes/struktura']);
+    expect(candidates[0].linkType).toBe('wikilink_basename');
+    expect(candidates[0].linkSource).toBe('wikilink-resolved');
+  });
+
+  test('path-qualified wikilink keeps only matches ending with the written path', async () => {
+    // The written path disambiguates: `[[notes/struktura]]` must never
+    // attach to `wiki/struktura` even though both share the basename.
+    const resolver: SlugResolver = {
+      resolve: async () => null,
+      resolveBasenameMatches: async (name) =>
+        name === 'struktura' ? ['notes/struktura', 'wiki/struktura'] : [],
+    };
+    const { candidates } = await extractPageLinks(
+      'concepts/x', 'See [[notes/struktura]].',
+      {}, 'concept', resolver, { globalBasename: true },
+    );
+    expect(candidates.map(c => c.targetSlug)).toEqual(['notes/struktura']);
+  });
+
+  test('path-qualified wikilink matches a deeper real slug by path suffix', async () => {
+    // The page lives at vault/notes/struktura; the author wrote the shorter
+    // tail `[[notes/struktura]]`. Suffix matching connects them, while the
+    // basename-only sibling `wiki/struktura` stays excluded.
+    const resolver: SlugResolver = {
+      resolve: async () => null,
+      resolveBasenameMatches: async (name) =>
+        name === 'struktura' ? ['vault/notes/struktura', 'wiki/struktura'] : [],
+    };
+    const { candidates } = await extractPageLinks(
+      'concepts/x', 'See [[notes/struktura]].',
+      {}, 'concept', resolver, { globalBasename: true },
+    );
+    expect(candidates.map(c => c.targetSlug)).toEqual(['vault/notes/struktura']);
+  });
+
+  test('path-qualified self-link is dropped like the bare form', async () => {
+    // `[[notes/struktura]]` written on notes/struktura itself must not
+    // produce a self-loop (same guard as the bare `[[own-tail]]` case).
+    const resolver: SlugResolver = {
+      resolve: async () => null,
+      resolveBasenameMatches: async (name) =>
+        name === 'struktura' ? ['notes/struktura'] : [],
+    };
+    const { candidates } = await extractPageLinks(
+      'notes/struktura', 'See [[notes/struktura]].',
+      {}, 'concept', resolver, { globalBasename: true },
+    );
+    expect(candidates).toEqual([]);
+  });
+
   test('bare wikilink resolution does not interfere with DIR_PATTERN wikilinks', async () => {
     // 2b refs (people/alice) take the verb-inferred type;
     // 2c refs (struktura) take wikilink_basename. Same call.

test/loadConfig-merge.test.ts

@@ -302,4 +302,29 @@ describe('loadConfigWithEngine (Phase 4 / F3)', () => {
       expect(merged?.engine).toBe('pglite');
     });
   });
+
+  describe('eval.* DB-plane merge (#1475)', () => {
+    test('gbrain config set eval.capture true reaches the merged config', async () => {
+      // The #1475 repro: DB plane has eval.capture=true, file plane silent.
+      // Pre-fix the merge skipped eval.* entirely and capture never fired.
+      const base: GBrainConfig = { engine: 'pglite' };
+      const engine = makeEngine({ 'eval.capture': 'true', 'eval.scrub_pii': 'false' });
+      const merged = await loadConfigWithEngine(engine, base);
+      expect(merged?.eval?.capture).toBe(true);
+      expect(merged?.eval?.scrub_pii).toBe(false);
+    });
+
+    test('file plane wins per key; DB fills only the gaps', async () => {
+      const base: GBrainConfig = { engine: 'pglite', eval: { capture: false } };
+      const engine = makeEngine({ 'eval.capture': 'true', 'eval.scrub_pii': 'false' });
+      const merged = await loadConfigWithEngine(engine, base);
+      expect(merged?.eval?.capture).toBe(false); // file wins
+      expect(merged?.eval?.scrub_pii).toBe(false); // DB fills the gap
+    });
+
+    test('no eval keys anywhere leaves cfg.eval undefined', async () => {
+      const merged = await loadConfigWithEngine(makeEngine({}), { engine: 'pglite' });
+      expect(merged?.eval).toBeUndefined();
+    });
+  });
 });

test/maintain.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  extractCycleFreshnessSourceIds,
+  parseMaintainArgs,
+} from '../src/commands/maintain.ts';
+import type { Check } from '../src/commands/doctor.ts';
+
+describe('maintain args', () => {
+  test('defaults to dry-run unless --safe is explicit', () => {
+    expect(parseMaintainArgs([])).toMatchObject({
+      safe: false,
+      dryRun: true,
+      json: false,
+    });
+  });
+
+  test('--safe enables mutating safe mode', () => {
+    expect(parseMaintainArgs(['--safe', '--json'])).toMatchObject({
+      safe: true,
+      dryRun: false,
+      json: true,
+    });
+  });
+
+  test('--dry-run wins over --safe', () => {
+    expect(parseMaintainArgs(['--safe', '--dry-run'])).toMatchObject({
+      safe: true,
+      dryRun: true,
+    });
+  });
+});
+
+describe('cycle freshness source extraction', () => {
+  test('extracts stale source ids from doctor messages', () => {
+    const checks: Check[] = [
+      {
+        name: 'cycle_freshness',
+        status: 'fail',
+        message: "Source 'brain-sync-remote-teffur' last cycled 40h ago. Run `gbrain dream --source <id>`.",
+      },
+      {
+        name: 'cycle_freshness',
+        status: 'fail',
+        message: "Source 'wiki' last cycled 25h ago. Source 'wiki' last cycled 25h ago.",
+      },
+    ];
+
+    expect(extractCycleFreshnessSourceIds(checks)).toEqual([
+      'brain-sync-remote-teffur',
+      'wiki',
+    ]);
+  });
+
+  test('ignores ok and unrelated checks', () => {
+    const checks: Check[] = [
+      { name: 'cycle_freshness', status: 'ok', message: "Source 'fresh' last cycled recently." },
+      { name: 'frontmatter_integrity', status: 'warn', message: "Source 'wiki' has frontmatter issues." },
+    ];
+
+    expect(extractCycleFreshnessSourceIds(checks)).toEqual([]);
+  });
+});

test/openclaw-plugin-manifest.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'bun:test';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+describe('root OpenClaw plugin manifest', () => {
+  it('declares the id required by OpenClaw plugin installs', () => {
+    const manifest = JSON.parse(readFileSync(join(import.meta.dir, '..', 'openclaw.plugin.json'), 'utf8'));
+    const entrySource = readFileSync(join(import.meta.dir, '..', 'src', 'openclaw-context-engine.ts'), 'utf8');
+    const entryId = entrySource.match(/id:\s*'([^']+)'/)?.[1];
+
+    expect(manifest.id).toBe(entryId);
+    expect(manifest.configSchema).toBeDefined();
+    expect(typeof manifest.configSchema).toBe('object');
+    expect(manifest.contracts?.contextEngines).toContain('gbrain-context');
+    expect(entrySource).toContain('export function register');
+  });
+});

test/orphans-pure-fn.test.ts

@@ -186,11 +186,67 @@ describe('shouldExclude — orphan filter regression (preserve curation)', () =>
     expect(shouldExclude('entities/anonymous')).toBe(true);
     expect(shouldExclude('atoms/fact-123')).toBe(true);
     expect(shouldExclude('skills/gbrain-operations')).toBe(true);
+    expect(shouldExclude('dreaming/light/2026-07-20')).toBe(true);
+    expect(shouldExclude('daily/2026-07-20')).toBe(true);
+    expect(shouldExclude('agent-openclaw/daily/2026-07-20')).toBe(true);
+  });
+
+  test('workspace convention slugs are excluded', () => {
+    expect(shouldExclude('_brain-conventions')).toBe(true);
+    expect(shouldExclude('_templates/decision')).toBe(true);
+    expect(shouldExclude('extracts/2026-06-30/takes.proposed/round-single')).toBe(true);
+    expect(shouldExclude('2026-07-20')).toBe(true);
+    expect(shouldExclude('2026-07-20-qa-sweep')).toBe(true);
+    expect(shouldExclude('agents/arya/identity')).toBe(true);
+    expect(shouldExclude('agents/arya/memory/dreaming/deep/2026-07-20')).toBe(true);
   });
 
   test('regular slugs are NOT excluded', () => {
     expect(shouldExclude('people/alice')).toBe(false);
     expect(shouldExclude('companies/acme')).toBe(false);
     expect(shouldExclude('writing/post-1')).toBe(false);
+    expect(shouldExclude('agents/arya/qa-reports/launch-review')).toBe(false);
+  });
+});
+
+describe('getHealth orphan_pages uses shared exclusion policy', () => {
+  test('excluded convention islands do not count against health', async () => {
+    await engine.putPage('_templates/decision', {
+      type: 'template', title: 'Decision', compiled_truth: 'template', timeline: '', frontmatter: {},
+    });
+    await engine.putPage('skills/arya/source-check', {
+      type: 'concept', title: 'Skill', compiled_truth: 'skill', timeline: '', frontmatter: {},
+    });
+    await engine.putPage('agents/arya/identity', {
+      type: 'note', title: 'Identity', compiled_truth: 'identity', timeline: '', frontmatter: {},
+    });
+    await engine.putPage('people/alice', {
+      type: 'person', title: 'Alice', compiled_truth: 'real island', timeline: '', frontmatter: {},
+    });
+
+    const health = await engine.getHealth();
+
+    expect(health.orphan_pages).toBe(1);
+  });
+
+  test('per-brain config overrides (orphans.exclude_*) also apply to health', async () => {
+    await engine.putPage('my-private-folder/secret-ref', {
+      type: 'note', title: 'Ref', compiled_truth: 'ref', timeline: '', frontmatter: {},
+    });
+    await engine.putPage('one-off-fixture-page', {
+      type: 'note', title: 'Fixture', compiled_truth: 'fixture', timeline: '', frontmatter: {},
+    });
+    await engine.putPage('people/alice', {
+      type: 'person', title: 'Alice', compiled_truth: 'real island', timeline: '', frontmatter: {},
+    });
+
+    expect((await engine.getHealth()).orphan_pages).toBe(3);
+
+    await engine.setConfig('orphans.exclude_prefixes', 'my-private-folder/');
+    await engine.setConfig('orphans.exclude_slugs', 'one-off-fixture-page');
+    expect((await engine.getHealth()).orphan_pages).toBe(1);
+
+    await engine.unsetConfig('orphans.exclude_prefixes');
+    await engine.unsetConfig('orphans.exclude_slugs');
   });
 });

test/orphans.test.ts

@@ -66,6 +66,10 @@ describe('shouldExclude', () => {
     expect(shouldExclude('templates/meeting-note')).toBe(true);
   });
 
+  test('excludes deny-prefix: _templates/', () => {
+    expect(shouldExclude('_templates/meeting-note')).toBe(true);
+  });
+
   test('excludes deny-prefix: openclaw/config/', () => {
     expect(shouldExclude('openclaw/config/agent')).toBe(true);
   });
@@ -86,10 +90,44 @@ describe('shouldExclude', () => {
     expect(shouldExclude('entities/product-hunt')).toBe(true);
   });
 
+  test('excludes first-segment: skills, dreaming, and daily', () => {
+    expect(shouldExclude('skills/arya/source-check')).toBe(true);
+    expect(shouldExclude('dreaming/light/2026-07-20')).toBe(true);
+    expect(shouldExclude('daily/2026-07-20')).toBe(true);
+    expect(shouldExclude('agent-openclaw/daily/2026-07-20')).toBe(true);
+  });
+
+  test('excludes root date logs and agent workspace conventions', () => {
+    expect(shouldExclude('_brain-conventions')).toBe(true);
+    expect(shouldExclude('2026-07-20')).toBe(true);
+    expect(shouldExclude('2026-07-20-qa-sweep')).toBe(true);
+    expect(shouldExclude('agents/arya/identity')).toBe(true);
+    expect(shouldExclude('agents/arya/memory/dreaming/deep/2026-07-20')).toBe(true);
+  });
+
+  test('excludes generated extracts', () => {
+    expect(shouldExclude('extracts/2026-06-30/takes.proposed/round-single')).toBe(true);
+  });
+
+  test('brain-specific exclusions come from config overrides, not global defaults', () => {
+    // No baked-in defaults for these:
+    expect(shouldExclude('my-private-folder/some-secret-ref.md')).toBe(false);
+    expect(shouldExclude('one-off-fixture-page')).toBe(false);
+    // The per-brain config plane (orphans.exclude_prefixes / exclude_slugs):
+    const overrides = {
+      excludePrefixes: ['my-private-folder/'],
+      excludeSlugs: ['one-off-fixture-page'],
+    };
+    expect(shouldExclude('my-private-folder/some-secret-ref.md', overrides)).toBe(true);
+    expect(shouldExclude('one-off-fixture-page', overrides)).toBe(true);
+    expect(shouldExclude('people/jane-doe', overrides)).toBe(false);
+  });
+
   test('does NOT exclude a normal content page', () => {
     expect(shouldExclude('companies/acme')).toBe(false);
     expect(shouldExclude('people/jane-doe')).toBe(false);
     expect(shouldExclude('projects/gbrain')).toBe(false);
+    expect(shouldExclude('agents/arya/qa-reports/launch-review')).toBe(false);
   });
 
   test('does NOT exclude a page ending with log-like text that is not /log', () => {

test/postgres-execute-raw-direct.test.ts

@@ -98,39 +98,14 @@ describe('PostgresEngine.executeRawDirect — routing decision (PR #1816)', () =
   });
 
   test('already-aborted signal short-circuits with AbortError before routing the query', async () => {
-    let unsafeCalls = 0;
-    let ddlCalls = 0;
-    const readConn: FakeSql = { unsafe: async () => { unsafeCalls++; return []; } };
+    const readConn = fakeSql('read');
     const directConn = fakeSql('direct');
     const engine = makeEngine({ dualPoolActive: true, readConn, directConn });
-    const e = engine as unknown as { connectionManager: { ddl: () => Promise<FakeSql> } };
-    e.connectionManager.ddl = async () => { ddlCalls++; return directConn; };
 
     const ac = new AbortController();
     ac.abort();
     await expect(
       engine.executeRawDirect('UPDATE minion_jobs SET x=1', [], { signal: ac.signal }),
     ).rejects.toThrow(/abort/i);
-    // #2750: short-circuits BEFORE pool routing — no ddl(), no unsafe().
-    expect(ddlCalls).toBe(0);
-    expect(unsafeCalls).toBe(0);
-  });
-
-  test('#2750: signal bounds a stalled direct-pool acquisition before unsafe starts', async () => {
-    let unsafeCalls = 0;
-    const readConn: FakeSql = { unsafe: async () => { unsafeCalls++; return []; } };
-    const directConn = fakeSql('direct');
-    const engine = makeEngine({ dualPoolActive: true, readConn, directConn });
-    const e = engine as unknown as { connectionManager: { ddl: () => Promise<FakeSql> } };
-    e.connectionManager.ddl = () => new Promise<FakeSql>(() => {}); // pooler exhausted: never resolves
-
-    const started = Date.now();
-    await expect(engine.executeRawDirect(
-      'DELETE FROM gbrain_cycle_locks',
-      [],
-      { signal: AbortSignal.timeout(10) },
-    )).rejects.toThrow(/abort/i);
-    expect(Date.now() - started).toBeLessThan(1_000);
-    expect(unsafeCalls).toBe(0);
   });
 });

test/progress.test.ts

@@ -218,15 +218,21 @@ describe('progress reporter', () => {
   test('only one process-level signal handler installed across many reporters', () => {
     // Baseline: one handler already installed by prior tests in this file.
     const installedBefore = __signalHandlerInstalledForTest();
+    // liveReporters is process-global: earlier test files in the same shard
+    // can leave a live entry behind (e.g. a production path that skips
+    // finish() on an error branch). Assert NET-zero leak from THIS test's
+    // lifecycles, not an absolute zero we don't control — same tolerance
+    // the handler assertion below already applies via `installedBefore`.
+    const liveBefore = __liveReporterCountForTest();
     const { stream } = sink(false);
     for (let i = 0; i < 50; i++) {
       const p = createProgress({ mode: 'json', stream, minIntervalMs: 0, minItems: 1 });
       p.start(`phase_${i}`, 1);
       p.finish();
     }
-    // After 50 reporter lifecycles, still exactly one handler and zero leaked live entries.
+    // After 50 reporter lifecycles, still exactly one handler and zero NEWLY leaked live entries.
     expect(__signalHandlerInstalledForTest()).toBe(installedBefore || true);
-    expect(__liveReporterCountForTest()).toBe(0);
+    expect(__liveReporterCountForTest()).toBe(liveBefore);
   });
 
   test('startHeartbeat() fires heartbeats and stop() clears', async () => {

test/skillopt/version-store.test.ts

@@ -12,9 +12,11 @@ import {
   bestPath,
   historyPath,
   loadHistory,
+  proposedPath,
   revertAllPending,
   skillPath,
   versionsDir,
+  writeProposed,
 } from '../../src/core/skillopt/version-store.ts';
 
 let tmpDir: string;
@@ -79,6 +81,19 @@ 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);