ci: add --timeout=60000 to E2E runner to prevent setupDB flake

PR #475's Tier 1 (Mechanical) CI job hit a 5000.09ms beforeAll hook
timeout in `E2E: Tags > (unnamed)`. Cause: scripts/run-e2e.sh invokes
`bun test "$f"` without a --timeout flag, falling back to bun's 5s
default. setupDB() does TRUNCATE CASCADE on ~30 tables, and on a CI
runner under load that can exceed 5s.

Match what the unit suite uses (--timeout=60000 in package.json's
"test" script). Same 1m ceiling, no behavior change for healthy runs;
just removes the artificial 5s floor on hooks.

Verified locally: bun test --timeout=60000 test/e2e/mechanical.test.ts
runs 78 pass / 0 fail in 27.99s against a fresh pgvector pg16 docker
container.

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

CHANGELOG.md

@@ -2,6 +2,413 @@
 
 All notable changes to GBrain will be documented in this file.
 
+## [0.22.5] - 2026-04-27
+
+## **Autopilot stops re-importing your whole brain when a commit gets garbage-collected.**
+## **Cycle reads the per-source `sources.last_commit` anchor instead of the drift-prone global key.**
+
+`gbrain dream` and the `autopilot-cycle` worker were calling `performSync()` without `sourceId`, so sync read the global `config.sync.last_commit` key. When that commit gets GC'd from git history (a force push, a squash, an `--amend` chain), `git cat-file -t <anchor>` fails, sync concludes "force push happened," and triggers a full reimport of every page. On a 78K-page brain that's ~30 minutes per cycle, the autopilot job hits its timeout, dead-letters, and the next cron tick does it again. Production OpenClaw deployment hit exactly this pattern: every cycle ran the full reimport while the per-source `sources.last_commit` (`00a62e50`) was a valid HEAD ancestor the entire time.
+
+v0.22.5 threads `sourceId` through the cycle. `runPhaseSync()` now resolves the brain directory against the `sources` table (`SELECT id FROM sources WHERE local_path = $1`) and passes the result to `performSync()`. When a source row matches, sync reads `sources.last_commit` (per-source, always written back on every successful sync). When no row matches (pre-v0.18 brain or never-registered path), it falls through to the global key ... fully backward compatible. Six new regression tests pin the resolver behavior, including the table-missing fallback for old brains and the empty-string-id defensive case.
+
+### The numbers that matter
+
+Production behavior on a 78,797-page brain:
+
+| Metric | Pre-v0.22.5 (master) | v0.22.5 | Δ |
+|---|---|---|---|
+| Autopilot cycle wall time (steady state) | 30+ min (then timeout) | <1 sec | -1800x |
+| Files re-imported per cycle (steady state) | 78,797 | 0 | -78,797 |
+| `autopilot-cycle` jobs hitting `max_stalled` | every cycle | 0 | -100% |
+| Cycle phases that consult per-source anchor | 0 | 1 (sync) | +1 |
+| New regression tests in `test/core/cycle.test.ts` | n/a | 6 | +6 |
+
+Resolver behavior matrix (every row covered by a test):
+
+| Scenario | sourceId passed | Anchor read from | Backward compatible |
+|---|---|---|---|
+| Sources row matches `brainDir` (current install) | `"default"` | `sources.last_commit` ✅ | Yes |
+| No sources row (pre-v0.18 brain) | `undefined` | `config.sync.last_commit` | Yes |
+| `sources` table doesn't exist (very old brain) | `undefined` (catch) | `config.sync.last_commit` | Yes |
+| Multiple rows share a `local_path` (no UNIQUE) | one of the matching ids (non-deterministic) | the matched row's anchor | Yes |
+| Empty-string id row | `""` (defensive ... won't happen in practice) | empty-string source row | Yes |
+
+### What this means for builders
+
+If your brain has been silently doing a full reimport every autopilot cycle, `gbrain upgrade` plus your next cycle will fix it ... no manual action needed. The fix is mechanical and idempotent. If you've been running with the operational band-aid that copied the per-source anchor to the global key every 5 minutes (the pre-PR workaround), you can take it out after upgrading. Two follow-ups are filed for v0.23: a `UNIQUE` index on `sources.local_path` so duplicate-path resolution is deterministic, and narrowing the resolver's bare `catch` to PostgreSQL's `42P01` (undefined_table) so real DB errors don't get silently swallowed into the global-fallback path.
+
+## To take advantage of v0.22.5
+
+`gbrain upgrade` runs `gbrain post-upgrade` which runs `gbrain apply-migrations`. v0.22.5 has no schema migration ... the fix is pure code, no data backfill ... so the upgrade itself is the entire action.
+
+1. **Upgrade:**
+   ```bash
+   gbrain upgrade
+   ```
+
+2. **Verify the next autopilot cycle is fast.** Either let `gbrain autopilot` tick naturally, or run one cycle directly:
+   ```bash
+   gbrain dream --phase sync --json | jq '.phases[] | select(.phase == "sync")'
+   ```
+   On a brain with a registered source, the sync phase should report incremental status (`up_to_date` or a small added/modified count) and complete in seconds. If it reports thousands of files added/modified on a brain you haven't actually changed, file an issue ... the resolver isn't matching your `brainDir` to a `sources.local_path` (likely a path-normalization mismatch ... see TODO 1 below).
+
+3. **Optional ... confirm the resolver matched.** The `sources` row used by `gbrain dream` should match your brain directory exactly:
+   ```bash
+   gbrain query 'SELECT id, local_path FROM sources' --json
+   ```
+   If the path stored in `sources.local_path` differs from the directory `gbrain dream --dir <path>` is invoked with (trailing slash, symlink resolution), v0.22.5 will fall back to the legacy global-key path silently for that source. A future v0.23 fix will normalize both sides; for now you can re-register the source with the canonical absolute path.
+
+4. **If any step fails or the numbers look wrong,** file an issue: https://github.com/garrytan/gbrain/issues with:
+   - output of `gbrain doctor`
+   - contents of `~/.gbrain/upgrade-errors.jsonl` if it exists
+   - which step broke
+
+   This feedback loop is how the gbrain maintainers find fragile upgrade paths. Thank you.
+
+### Itemized changes
+
+**Hotfix.** `src/core/cycle.ts` ... new `resolveSourceForDir(engine, brainDir)` helper queries `SELECT id FROM sources WHERE local_path = $1 LIMIT 1`. `runPhaseSync()` calls it before `performSync()` and threads the result as `sourceId`. Bare `try/catch` swallows missing-table errors so pre-v0.18 brains keep working unchanged. 26 new lines, one file. The fix funnels into the existing `readSyncAnchor()` branching at `src/commands/sync.ts:174-188`, which already chose between per-source and global anchors when given a `sourceId`; the cycle just wasn't passing one.
+
+**Tests.** 6 new test cases in `test/core/cycle.test.ts` covering every branch of the resolver:
+- **Test 1** ... seeded `sources` row → `performSync` receives matching `sourceId`.
+- **Test 2** ... no row → `sourceId=undefined`, falls through to global key.
+- **Test 3** ... different `brainDir` than registered source → undefined (no cross-match).
+- **Test 4** ... `sources` table missing (very old brain) → catch returns undefined, sync still runs. Uses a fresh `PGLiteEngine` (not the shared one) because `initSchema()` only re-runs PENDING migrations; `DROP TABLE` on the shared engine would have left it permanently degraded for every subsequent test in the file. Codex review caught this landmine.
+- **Test 5** ... duplicate `local_path` rows → resolver returns one of the matching ids (non-deterministic; the SQL has no `ORDER BY`). Documents the contract for the v0.23 UNIQUE-constraint follow-up.
+- **Test 6** ... empty-string id row → resolver propagates `""` (defensive case Codex flagged ... PK prevents NULL but `''` can be inserted).
+
+The `performSync` mock in `test/core/cycle.test.ts:50-65` was extended to capture `sourceId` alongside the existing `dryRun / noPull / noExtract` opts. The new `describe` block runs after the existing 22 tests; the shared PGLite engine cleanup pattern (`DELETE FROM sources` in `beforeEach`) keeps state from leaking between tests.
+
+### For contributors
+
+When threading new options through `runCycle → runPhaseSync → performSync`, extend the `syncCalls` capture shape in `test/core/cycle.test.ts:20` and add per-option assertions to the existing `describe('runCycle — dryRun propagates...')` and `describe('runCycle — phase selection')` blocks. The `cycle.test.ts` shared-engine pattern is fast (~1.4s for 28 tests on PGLite in-memory) but `initSchema()` only runs PENDING migrations ... if your test needs to mutate the schema mid-suite (DROP TABLE, ALTER, etc.), spin up a fresh `PGLiteEngine` and dispose in `finally` instead of touching the shared engine. The v0.22.5 test 4 is the canonical example.
+
+The bare `catch` in `resolveSourceForDir` is intentional for v0.22.5 because narrowing to a PG-specific error code (`error.code === '42P01'`) requires engine-aware error introspection that the existing PGLite engine doesn't expose uniformly with postgres-engine. v0.23 will add a small `isMissingRelationError(error, engine.kind)` helper to `src/core/utils.ts` and the resolver will rethrow everything else.
+
+## [0.22.4] - 2026-04-26
+
+## **Frontmatter-guard ships. Broken brain pages can't hide.**
+## **Seven validation classes, source-aware audit, doctor subcheck, pre-commit hook, zero resolver warnings.**
+
+v0.22.4 fixes the seven `gbrain check-resolvable` warnings that lived on master and ships frontmatter-guard as a real feature: a TypeScript validator inside `parseMarkdown(..., {validate:true})`, a top-level `gbrain frontmatter` CLI (`validate` / `audit` / `install-hook`), a new `frontmatter_integrity` subcheck under `gbrain doctor`, and an audit-only migration that surveys every registered source and queues per-source TODOs without mutating brain content. PR #392's aspirational `lib/brain-writer.mjs` is finally written, in TypeScript, on top of the tools gbrain already ships.
+
+The migration is **audit-only**. It writes a JSON report to `~/.gbrain/migrations/v0.22.4-audit.json` and emits per-source entries to `pending-host-work.jsonl` with the exact fix command. It never silently rewrites your brain pages. The agent reads `skills/migrations/v0.22.4.md` after upgrade, surfaces the counts to you, and runs `gbrain frontmatter validate <source-path> --fix` only with explicit consent. `--fix` writes `.bak` backups for every modified file (the safety contract for non-git brain repos, which `getWorkingTreeStatus` rejects).
+
+`gbrain frontmatter` is source-aware throughout. `audit [--source <id>]` walks every registered source via `source-resolver.ts` (gbrain has been multi-source since v0.18.0; the single-`brainRoot` model would have shipped a half-broken feature). The CLI, doctor subcheck, and migration phase all call into one shared `scanBrainSources()` ... single source of truth for what counts as malformed.
+
+### The numbers that matter
+
+Counted against gbrain's own checked-in `skills/` tree:
+
+| Metric | Pre-v0.22.4 (master) | v0.22.4 | Δ |
+|---|---|---|---|
+| `gbrain check-resolvable` warnings | 7 | 0 | -7 |
+| Frontmatter validation classes | 3 (in `lint`) | 7 (in `parseMarkdown`) | +4 |
+| Auto-fixable error codes | 0 | 4 (NULL_BYTES, MISSING_CLOSE, NESTED_QUOTES, SLUG_MISMATCH) | +4 |
+| Doctor subchecks | 17 | 18 (+frontmatter_integrity) | +1 |
+| `gbrain frontmatter` subcommands | 0 | 3 (validate, audit, install-hook) | +3 |
+| Skills in `skills/` | 29 | 30 (+frontmatter-guard) | +1 |
+| Pre-commit hook helper | none | `gbrain frontmatter install-hook` | ✓ |
+| Source-aware audit | n/a | walks every registered source | ✓ |
+
+Frontmatter validation surface (the 7 codes shipped):
+
+| Code | What it catches | Auto-fix |
+|---|---|---|
+| `MISSING_OPEN` | File doesn't start with `---` | No (human review) |
+| `MISSING_CLOSE` | No closing `---` before first heading | Yes ... inserts `---` |
+| `YAML_PARSE` | YAML failed to parse | Sometimes |
+| `SLUG_MISMATCH` | Frontmatter `slug:` differs from path-derived slug | Yes ... removes field |
+| `NULL_BYTES` | Binary corruption (`\x00`) | Yes ... strips bytes |
+| `NESTED_QUOTES` | `title: "outer "inner" outer"` shape | Yes ... switches outer to single quotes |
+| `EMPTY_FRONTMATTER` | Open + close present, nothing meaningful between | No (human review) |
+
+### What this means for builders
+
+If you've been ignoring `gbrain check-resolvable` warnings because the messages were misleading (the action message said "Add disambiguation rule in RESOLVER.md OR narrow triggers" ... but only the second branch actually silenced the MECE warning, since the checker doesn't parse RESOLVER.md disambiguation rules), v0.22.4 closes the loop. Trigger overlap is fixed at the frontmatter layer. `enrich/SKILL.md` delegates citation rules to `conventions/quality.md` instead of inlining them. Routing-eval fixtures embed actual trigger keywords. `frontmatter-guard` is registered. `gbrain check-resolvable --json` returns `ok: true, issues: []`.
+
+If your agent writes brain pages, plumb its writes through `parseMarkdown(content, path, { validate: true, expectedSlug })` (the export is in `gbrain/markdown`) and check the returned `errors` array. The 7-error envelope is stable from v0.22.4 onward. Or call `gbrain frontmatter validate <path> --json` from your script and parse the envelope. For brain repos that ARE git repos, install the pre-commit hook with `gbrain frontmatter install-hook` and stop bad frontmatter at the commit boundary.
+
+If you maintain a downstream OpenClaw fork, see `docs/UPGRADING_DOWNSTREAM_AGENTS.md` for the v0.22.4 diff pattern. The short version: drop any references to the never-existed `lib/brain-writer.mjs` and replace with `gbrain frontmatter validate` calls.
+
+## To take advantage of v0.22.4
+
+`gbrain upgrade` runs `gbrain post-upgrade` which runs `gbrain apply-migrations`. If that chain was interrupted or if `gbrain doctor` reports `frontmatter_integrity` issues:
+
+1. **Run the orchestrator manually:**
+   ```bash
+   gbrain apply-migrations --yes
+   ```
+   The `v0.22.4` orchestrator (v0_22_4.ts) runs schema (no-op) → audit → emit-todo. The audit phase writes a per-source JSON report to `~/.gbrain/migrations/v0.22.4-audit.json` and queues one entry per source with issues to `~/.gbrain/migrations/pending-host-work.jsonl`. **It never modifies brain content.**
+
+2. **Read the audit report:**
+   ```bash
+   cat ~/.gbrain/migrations/v0.22.4-audit.json | jq '.errors_by_code, .per_source[].source_id'
+   ```
+
+3. **Fix mechanical issues with explicit consent.** For each source with errors > 0, run:
+   ```bash
+   gbrain frontmatter validate <source-path> --fix
+   ```
+   This writes `.bak` backups for every modified file. SLUG_MISMATCH errors are surfaced for manual review (gbrain derives slug from path; a mismatch usually means the file was renamed deliberately or the slug field is stale).
+
+4. **Verify the outcome:**
+   ```bash
+   gbrain doctor --json | jq '.checks[] | select(.name == "frontmatter_integrity")'
+   gbrain frontmatter audit --json | jq '.total'
+   gbrain check-resolvable --json | jq '.report.issues | map(select(.severity=="warning" or .severity=="error")) | length'
+   ```
+   All three should report 0 issues.
+
+5. **If any step fails or the numbers look wrong,** file an issue at https://github.com/garrytan/gbrain/issues with:
+   - output of `gbrain doctor`
+   - contents of `~/.gbrain/migrations/v0.22.4-audit.json`
+   - contents of `~/.gbrain/upgrade-errors.jsonl` if it exists
+   - which step broke
+
+   This feedback loop is how the gbrain maintainers find fragile upgrade paths. Thank you.
+
+### Itemized changes
+
+**Part A ... `gbrain check-resolvable` reaches 0 warnings.** Drop `"citation audit"` from `skills/maintain/SKILL.md` frontmatter; the trigger lives only on `citation-fixer` now. RESOLVER.md gains a citation-audit disambiguation row pointing both skills so agents still pick the right one. RESOLVER.md broadens query triggers (`"who is"`, `"background on"`, `"notes on"`) and `query/SKILL.md` mirrors them in its frontmatter. `skills/enrich/SKILL.md` replaces the inlined citation rules block with `> **Convention:** see \`skills/conventions/quality.md\`` (the format `extractDelegationTargets` recognizes). Routing-eval fixtures for `citation-fixer` rewritten to embed `"fix citations"` so substring matching passes.
+
+**Part B ... frontmatter-guard library + CLI + doctor + migration + skill + pre-commit hook.**
+
+- **`src/core/markdown.ts`** ... `parseMarkdown(content, filePath?, opts?)` gains an opt-in `opts.validate` flag. When true, returns `errors[]` with the seven canonical codes. Existing callers unaffected. Validation logic for all seven codes lives here as the single source of truth.
+- **`src/commands/lint.ts`** ... frontmatter-rule lint cases delegate to `parseMarkdown(..., {validate:true})`. New rule names: `frontmatter-missing-close`, `frontmatter-yaml-parse`, `frontmatter-null-bytes`, `frontmatter-nested-quotes`, `frontmatter-slug-mismatch`, `frontmatter-empty`. Suppresses MISSING_OPEN to avoid double-reporting with the legacy `no-frontmatter` rule.
+- **`src/core/brain-writer.ts`** (NEW) ... thin orchestrator (~280 lines). Exports `autoFixFrontmatter`, `writeBrainPage`, `scanBrainSources`. `writeBrainPage` is path-guarded (refuses writes outside `sourcePath`), always writes `<file>.bak` before any in-place mutation. `scanBrainSources` walks every registered source via direct SQL against `sources.local_path`, uses `isSyncable()` from sync.ts as the canonical brain-page filter, blocks symlinks (matches sync's no-symlink policy), and respects `AbortSignal`.
+- **`src/commands/frontmatter.ts`** (NEW) ... `gbrain frontmatter validate <path> [--json] [--fix] [--dry-run]` and `gbrain frontmatter audit [--source <id>] [--json]`. The `audit` subcommand is read-only; `--fix` only exists on `validate`. CLI handles `--help` without a DB connection.
+- **`src/commands/frontmatter-install-hook.ts`** (NEW) ... `gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]`. Writes `.githooks/pre-commit` per source (skips non-git sources with a one-line note), runs `git config core.hooksPath .githooks` if unset, refuses to clobber existing hooks without `--force` (writes `.bak`). The hook script gracefully degrades when `gbrain` is missing on PATH (prints a warning, exits 0 ... doesn't break commits).
+- **`src/commands/doctor.ts`** ... new `frontmatter_integrity` subcheck calls `scanBrainSources()` and reports per-source counts plus the fix hint. Wraps in a doctor progress phase with heartbeat.
+- **`src/commands/migrations/v0_22_4.ts`** (NEW) ... audit-only orchestrator with three phases (schema no-op, audit, emit-todo). Idempotent + resumable. Skips cleanly when no sources are registered. Per-source TODO entries reference the dotted-filename migration doc (`skills/migrations/v0.22.4.md`) per the existing `pending-host-work.jsonl` convention.
+- **`skills/frontmatter-guard/SKILL.md`** (NEW) ... agent-agnostic; routes to `gbrain frontmatter` CLI invocations, drops OpenClaw-specific paths from PR #392's spec. Registered in `skills/manifest.json` and `skills/RESOLVER.md` with substring-matchable triggers.
+- **`docs/integrations/pre-commit.md`** (NEW) ... recipe doc covering install / bypass / uninstall and downstream-fork notes.
+- **`docs/UPGRADING_DOWNSTREAM_AGENTS.md`** ... v0.22.4 section with the diff pattern for forks that had inline frontmatter validators.
+
+**Tests.** 9 new test files / 4 updated test files. Unit coverage on every new module:
+- `test/markdown-validation.test.ts` (NEW) ... all 7 codes exercised against hand-crafted fixtures.
+- `test/lint-frontmatter.test.ts` (NEW) ... lint emits findings for each fixable code; double-report suppression verified.
+- `test/brain-writer.test.ts` (NEW) ... `autoFixFrontmatter` idempotency, `writeBrainPage` path-guard + `.bak` backup, `scanBrainSources` per-source rollup, AbortSignal mid-scan, single-source filter, missing-source-path graceful skip, symlink no-loop.
+- `test/frontmatter-cli.test.ts` (NEW) ... subprocess `validate / --fix --dry-run / --fix / --json` + recursive directory scan with `isSyncable` filter parity.
+- `test/frontmatter-install-hook.test.ts` (NEW) ... hook install / overwrite-protection / `--force` / `--uninstall` / silent-refresh on already-installed.
+- `test/migrations-v0_22_4.test.ts` (NEW) ... orchestrator phase coverage including dotted-filename JSONL contract and idempotent re-emit.
+- `test/check-resolvable.test.ts` (UPDATE) ... regression guard asserting the actual checked-in `skills/` tree has 0 warnings + 0 errors.
+- `test/doctor.test.ts` (UPDATE) ... assertion that `frontmatter_integrity` subcheck calls `scanBrainSources` and the fix hint references the right CLI command.
+- `test/apply-migrations.test.ts` (UPDATE) ... `skippedFuture` arrays extended to include v0.22.4.
+- `test/migration-orchestrator-v0_21_0.test.ts` (UPDATE) ... relaxed "is the latest" assertion to "is registered with v0.22.4 after it."
+
+### For contributors
+
+`brain-writer.ts` is the canonical place to add new frontmatter validation rules. Add the code to `parseMarkdown`'s `collectValidationErrors`, surface the lint rule name in `lint.ts`'s `FRONTMATTER_RULE_NAMES`, decide if it's auto-fixable (add to `FRONTMATTER_FIXABLE`), and write the auto-fix logic in `brain-writer.ts:autoFixFrontmatter`. Tests in `test/markdown-validation.test.ts` + `test/brain-writer.test.ts`. The lint output uses the `frontmatter-<code>` naming convention; CI consumers can target specific rule names in their lint configs.
+
+`gbrain frontmatter` is wired through `src/cli.ts:handleCliOnly` so `--help` works without a DB connection. The `audit` subcommand instantiates an engine internally via `loadConfig() + createEngine()`. New subcommands of `frontmatter` should follow this pattern: parse flags first, only connect to the engine when the subcommand actually needs DB access.
+
+The v0.22.4 orchestrator is intentionally audit-only because brain content is too important to silently mutate during `apply-migrations`. Future migrations that need to rewrite brain pages should follow this two-step pattern: write the audit report + queue the fix command, let the agent run the fix with explicit user consent.
+
+## [0.22.2] - 2026-04-26
+
+**Worker no longer freezes silently. Restart-on-RSS, cold-start retry, autopilot backpressure.**
+
+The minions worker has been freezing every few hours in production. RSS climbs from 68 MB at boot to ~15 GB over ~7 hours, the process stops claiming jobs but never crashes (no OOM, no SIGSEGV), the cron keeps enqueuing autopilot-cycle jobs every 5 minutes into a queue nobody is draining, and within 2-3 hours the queue piles up to 28+ waiting jobs. Shell jobs in flight when the worker froze hit `max_stalled` and dead-letter, producing an 18% shell-job failure rate over 24h. The brainstorm caught the root chain ... memory leak, wedged worker, supervisor cold-start race, no backpressure ... and v0.22.2 ships the three in-repo defenses that close the cascade end-to-end while the underlying memory leak gets investigated separately.
+
+The watchdog is the keystone. The worker now self-terminates when RSS crosses a threshold (default 2048 MB under the supervisor) and the supervisor's exponential-backoff respawn picks up a fresh process. Both per-job AND a 60-second periodic timer check, so the watchdog still fires when every concurrency slot is wedged and zero jobs are completing ... the actual production freeze pattern. On trip, the worker fires `shutdownAbort` (so the shell handler runs its SIGTERM→5s→SIGKILL cleanup on child processes) and aborts every per-job signal (so cooperative handlers bail instead of waiting out the 30s drain). Closes the zombie-shell-children gap a Codex review surfaced.
+
+Cold-start auth races on container boot are gone. Every CLI command's `connectEngine()` bootstrap retries transient errors (3 attempts, 1s/2s/4s backoff) by default. PgBouncer rejecting the first connect on a freshly-pinged Supabase pooler is the production failure mode that killed autopilot on cold start; the retry handles it transparently. Operators who genuinely want fail-fast on a misconfigured `DATABASE_URL` pass `--no-retry-connect` or set `GBRAIN_NO_RETRY_CONNECT=1`.
+
+Autopilot stops piling jobs into a dead queue. `autopilot-cycle` submissions now use `maxWaiting: 1` so the v0.19.1 `pg_advisory_xact_lock` coalesce path caps the queue at 1 active + 1 waiting instead of letting it grow unbounded. The 3rd+ submission coalesces and writes a backpressure-audit JSONL line. Combined with the existing per-slot `idempotency_key`, cross-slot pile-ups are bounded.
+
+### The numbers that matter
+
+Production data from the 2026-04-25 incident, plus the watchdog defaults:
+
+| Metric                                  | Before          | After (supervised path) |
+|-----------------------------------------|-----------------|-------------------------|
+| Waiting-jobs pileup at freeze           | 28+             | 2 (capped at 1+1)       |
+| Worker RSS at freeze                    | 14.8 GB         | ~2 GB self-terminate    |
+| Time to detect freeze                   | hours (manual)  | ≤60s (periodic timer)   |
+| Cold-start auth-fail recovery           | manual restart  | 3 attempts in ~7s       |
+
+Bare `gbrain jobs work` (operators not using the supervisor) keeps current unbounded behavior to preserve workloads with legitimately large embed/import working sets ... pass `--max-rss N` explicitly to enable the watchdog there.
+
+### What this means for operators
+
+If you run `gbrain jobs supervisor` (the production-recommended path), `gbrain upgrade` is the only step. The supervisor injects `--max-rss 2048` to its spawned worker by default; hourly watchdog exits look like clean shutdowns to the supervisor's stable-run reset, not crashes. If you run `gbrain autopilot --install`, the autopilot's worker spawn loop now has the same stable-run reset pattern, so a watchdog-driven exit every hour does NOT trip the give-up-after-5-crashes threshold. If your container hits zombie process accumulation, add `--init` to `docker run` or `tini` as PID 1 ... that's a host-side concern, not a gbrain change.
+
+## To take advantage of v0.22.2
+
+`gbrain upgrade` should do this automatically. If it didn't, or if `gbrain doctor` warns about a partial migration:
+
+1. **Run the orchestrator manually:**
+   ```bash
+   gbrain apply-migrations --yes
+   ```
+2. **No manual SKILL.md or AGENTS.md edits required.** This release is code-only ... no schema changes, no new skills.
+3. **Verify the watchdog is wired (Postgres + supervisor path):**
+   ```bash
+   gbrain jobs supervisor --json &
+   ps -ef | grep "gbrain jobs work" | grep -- "--max-rss 2048"
+   ```
+   You should see the spawned worker child carrying `--max-rss 2048` in its argv.
+4. **If you supervise via `gbrain autopilot --install`,** the watchdog gets injected automatically. Existing crontab/launchd/systemd installs do not need to be reinstalled ... the autopilot binary picks up the new spawn args on next restart.
+5. **For hosts hitting zombie process accumulation** (PID-table fills up over weeks): add `--init` to `docker run`, or set `tini` as PID 1 in your Dockerfile. Not a gbrain code change ... operational note.
+6. **If any step fails or behavior looks off,** please file an issue at https://github.com/garrytan/gbrain/issues with the output of `gbrain doctor` and the contents of `~/.gbrain/upgrade-errors.jsonl` if it exists.
+
+### Itemized changes
+
+#### Added
+
+- `MinionWorkerOpts` gains `maxRssMb`, `getRss`, and `rssCheckInterval` ... watchdog plumbing with a deterministic-test seam for the RSS readback.
+- `MinionWorker.gracefulShutdown(reason)` ... unified-style shutdown that fires `shutdownAbort` + per-job aborts + `running=false`. Reused by the per-job and periodic-timer check sites.
+- 60-second periodic RSS check (`rssCheckInterval` default 60_000) running alongside the existing stalled-jobs timer in `start()`. Closes the freeze-with-zero-completions production scenario.
+- `--max-rss MB` flag on `gbrain jobs work` (no default, opt-in for bare workers) and `gbrain jobs supervisor` (default 2048). `--max-rss 0` disables; `< 256` errors out as a likely GB-vs-MB unit-confusion typo.
+- `connectWithRetry()` + `isRetryableDbConnectError()` in `src/core/db.ts`. 5-pattern transient-error matcher (auth-failed, connection-refused, db-starting, terminated-unexpectedly, ECONNRESET). Permanent errors (extension-missing, schema conflicts) do NOT retry.
+- `--no-retry-connect` flag and `GBRAIN_NO_RETRY_CONNECT=1` env var ... operator escape hatch for fail-fast on misconfigured DATABASE_URL.
+- Autopilot worker spawn now carries `--max-rss 2048` and a stable-run reset window (5 minutes uptime → reset crash counter to 1). Mirrors the supervisor pattern at `supervisor.ts:471-476` so hourly watchdog exits don't kill autopilot after ~5 hours.
+- `autopilot-cycle` submission passes `maxWaiting: 1` to `queue.add()`. Combined with the existing per-slot `idempotency_key`, this caps cross-slot queue depth at 1 active + 1 waiting.
+- 11 new tests in `test/minions.test.ts` covering the watchdog (5 cases including the production-freeze-regression case where zero jobs ever complete) and `connectWithRetry` (6 cases including the noRetry opt-out, transient/permanent error distinction, and successful retry).
+- New supervisor integration test asserting `--max-rss 2048` lands in the spawned worker's argv by default.
+
+#### Changed
+
+- `MinionSupervisor` `SupervisorOpts` gains `maxRssMb` (default 2048). The spawn-args builder appends `--max-rss N` when `maxRssMb > 0`.
+- `connectEngine()` in `src/cli.ts` now wraps `engine.connect()` in `connectWithRetry` by default. Behavior change for cold-start auth races; preserve original fail-fast with `--no-retry-connect` per call site.
+
+#### Out of scope (follow-ups)
+
+- The 40 MB/job memory leak itself ... separate investigation needs heap snapshots and a real reproducer. The watchdog removes urgency.
+- Zombie process reaping via `tini` or `--init` ... Render/Docker host-side configuration, documented above.
+- Refactoring SIGTERM/SIGINT/watchdog into one `unifiedShutdown(reason)` helper ... right shape long-term, premature for this PR.
+
+### For contributors
+
+- The watchdog cleanup path (`gracefulShutdown`) is intentionally co-located with `MinionWorker.stop()`. When a third caller appears (e.g., a future `pause()` method), extracting `unifiedShutdown(reason)` becomes worth the refactor. Until then, three lines is not a DRY emergency.
+- `isRetryableDbConnectError()` lives in `src/core/db.ts` and owns its own 5-pattern matcher. PR #406 (when it merges) introduces a 13-pattern matcher in `src/core/minions/supervisor.ts`; the right move at that merge is to delete the supervisor's local copy and import from `db.ts` (correct dependency direction, low → high). A follow-up TODO captures this.
+## [0.22.1] - 2026-04-26
+
+**Autopilot stops being a noisy neighbor.**
+
+Five hotfixes shipping together: incremental extract, cooperative cycle abort, supervisor watchdog reconnect, session-level connection timeouts, and server-side embed-stale filtering. The wave's theme is unified: gbrain's overnight maintenance loop was reading too much, ignoring abort signals, and quietly poisoning shared infrastructure when things went wrong. After this release the loop only reads pages that changed, bails cleanly when timeouts fire, and recovers from connection-pool poisoning without manual intervention.
+
+### For everyone
+
+These two fixes apply to both PGLite (default install) and Postgres / Supabase users:
+
+- **#417 incremental extract** — `gbrain dream` cycles no longer re-read every markdown file when only a handful changed. The cycle still walks the directory tree to build the link-resolution set (a fast `readdir` pass), but `readFileSync` runs only on pages sync flagged as added or modified. On a 54,461-page production brain this turned a 10-minute extract phase into a sub-second pass; on a 500-page brain you get the same proportional win.
+- **#403 cycle abort** — when a cycle phase hits a per-job timeout, `runCycle` now bails at the next phase boundary instead of grinding through extract → embed → orphans while the worker thinks the job is done. A 30-second grace-then-evict safety net in `MinionWorker` frees the slot even if a future handler ignores the abort signal entirely. Cooperative — can't interrupt a phase mid-execution — but prevents the cascade that was wedging workers.
+
+### For Postgres / Supabase users
+
+Three fixes that no-op on PGLite (no network, no pooler, no per-connection state):
+
+- **#406 supervisor watchdog reconnect** — when the connection pool gets poisoned (PgBouncer rotation, Supabase pool bounce), the supervisor's watchdog now detects three consecutive health-check failures and calls `engine.reconnect()` to swap in a fresh pool. Workers crash cleanly on poisoned connections; supervisor catches it within ~3 health-check intervals (~3 minutes) instead of staying degraded until manual restart. Recovery is structural, not per-call magic.
+- **#363 session timeouts** *(Contributed by @orendi84)* — every Postgres connection now sets `statement_timeout` and `idle_in_transaction_session_timeout` as connection-time startup parameters. An orphaned pgbouncer backend can no longer hold a `RowExclusiveLock` for hours and block schema migrations. Defaults: 5 minutes each. Override per-GUC via `GBRAIN_STATEMENT_TIMEOUT` / `GBRAIN_IDLE_TX_TIMEOUT` / `GBRAIN_CLIENT_CHECK_INTERVAL`. Closes #361.
+- **#409 embed egress** *(Contributed by @atrevino47)* — `embed --stale` now filters server-side on `embedding IS NULL` instead of pulling every chunk's `vector(1536)` over the wire and discarding the unwanted ones client-side. On a fully-embedded 1.5K-page brain that's the difference between ~76 MB per call and a single `count()` round-trip. With autopilot firing every 5–10 minutes plus a 2-hour cron, one production user blew past Supabase's 5 GB free-tier ceiling at 102 GB used — that pattern is gone now. Two new `BrainEngine` methods (`countStaleChunks`, `listStaleChunks`) plus a consistency fix in `upsertChunks` so when `chunk_text` changes without a new embedding, both `embedding` and `embedded_at` reset to NULL together (no more "embedded_at says yes, embedding says NULL").
+
+### Production proof point
+
+The wave was driven by a 54,461-page OpenClaw production deployment where extract took 600+ seconds and the queue stalled at 20–36 waiting jobs (all returning `skipped: cycle_already_running`). All five fixes ran as hotfixes there for 12+ hours stable before this release. The numbers are extreme; the underlying bugs are not.
+
+### Eng-review tightening
+
+The original #406 wrapped `executeRaw` in a per-call retry that auto-recovered from connection errors. Eng-review dropped that wrapper as unsound — a SQL-prefix regex isn't a safe idempotence boundary (writable CTEs, side-effecting SELECTs). What ships from #406 is the structural reconnect path, not the per-call retry. Recovery moves up one layer to the supervisor watchdog. See `TODOS.md` for the planned caller-opt-in retry follow-up.
+
+### Test coverage
+
+15 new test cases across `test/extract-incremental.test.ts` (new), `test/core/cycle.test.ts`, and `test/connection-resilience.test.ts`:
+- 8 cases for `#417`: empty/undefined slugs, [a,b]-only reads, deleted-file handling, mode filter, dry-run, BATCH_SIZE flush, full-slug-set resolution.
+- 4 cases for `#417` + Codex F2: cycle threads `pagesAffected` into extract, full-walk fallback, F2 noExtract gating (full cycle vs sync-only).
+- 3 cases for D3: `executeRaw` has no per-call retry wrapper, `reconnect()` still exists, supervisor still has 3-strikes path.
+
+### To take advantage of v0.22.1
+
+No manual step. PGLite users get the universal fixes automatically on next cycle. Postgres users additionally get session timeouts on the next pool reconnect, server-side stale filtering on the next `embed --stale`, and supervisor reconnect on the next pool poisoning event.
+
+```bash
+gbrain upgrade
+gbrain doctor    # verify (optional)
+```
+
+If anything looks wrong post-upgrade, file an issue: https://github.com/garrytan/gbrain/issues with `gbrain doctor` output.
+
+## [0.22.0] - 2026-04-25
+
+**Search stops getting swamped by chat logs. Curated pages win by default.**
+
+For the last few releases, multi-word topic queries against a real brain returned chat-log pages at #1 and #2 because chat pages are 50KB and contain mentions of every topic. The actual article you wrote about the topic ranked #5. v0.22.0 fixes that at the SQL layer ... ranking is now source-aware, curated directories outrank bulk content, and bookkeeping directories like `test/` and `archive/` never enter the candidate set.
+
+The fix layers on top of v0.21.0's Cathedral II chunk-grain FTS and two-pass retrieval. Different mechanism, additive effect. Chat pages get dampened at the chunk-rank stage; curated content gets boosted; the two-pass walk and source-boost both run in the same pipeline. Temporal queries (`when`, `last week`, `YYYY-MM`) bypass the gate entirely so date-framed chat lookups still work. Two new env vars (`GBRAIN_SOURCE_BOOST`, `GBRAIN_SEARCH_EXCLUDE`) tune per-deployment. `unset` them to revert to v0.21.0 ranking exactly.
+
+Two SearchOpts additions plumb hard-exclude through the API: `exclude_slug_prefixes` (additive over defaults + env) and `include_slug_prefixes` (subtractive opt-back-in). The four default hard-excludes (`test/`, `archive/`, `attachments/`, `.raw/`) were silently polluting search results before.
+
+### The numbers that matter
+
+A new BrainBench category — **Cat 13b: Source Swamp Resistance** — ships in the sibling [gbrain-evals](https://github.com/garrytan/gbrain-evals) repo. The corpus is 20 pages: 10 short opinionated `originals/` pages and 10 long `wintermute/chat/` dumps that mention the same multi-word phrases at higher per-byte density. 30 hand-curated queries assert the curated page wins.
+
+| gbrain version                       | Top-1 hit | Top-3 hit | Swamp@top |
+|--------------------------------------|-----------|-----------|-----------|
+| v0.20.4 (pre-Cathedral II)           | 90.0%     | 100.0%    | 10.0%     |
+| v0.21.0 (Cathedral II — two-pass)    | 90.0%     | 100.0%    | 10.0%     |
+| **v0.22.0 (this release)**           | **93.3%** | **100.0%** | **6.7%**  |
+
+v0.21.0's two-pass retrieval is orthogonal to source-swamp resistance — it's about call-graph edges and parent-scope chunking, which doesn't reach the directory-level ranking signal that source-boost provides. v0.22.0 adds +3.3pts top-1 and -3.3pts swamp on top of v0.21.0.
+
+The world-v1 corpus (BrainBench Cats 1+2 retrieval, 145 relational queries) is unchanged at P@5 49.1% / R@5 97.9% — every existing benchmark axis stays put within ±2pp tolerance.
+
+### What this means for you
+
+If your brain's biggest directories are chat dumps, daily logs, or X archives, search just got dramatically better for the topic queries you actually run. If you depend on chat surfacing for date-framed questions ("what did we discuss last week"), nothing changed ... the intent classifier routes those to `detail=high` which bypasses source-boost. If you want a different boost map, set `GBRAIN_SOURCE_BOOST=originals/:1.8,wintermute/chat/:0.3` and ship.
+
+## To take advantage of v0.22.0
+
+`gbrain upgrade` should do this automatically. No DB migration is needed ... the change is purely a SQL ranking refactor on existing tables.
+
+1. **No manual migration step required.** The new ranking is on by default. Defaults are tuned for a brain with the canonical `originals/`, `concepts/`, `writing/`, `meetings/`, `daily/`, `media/x/`, `wintermute/chat/` shape.
+2. **Tune for your brain (optional):**
+   ```bash
+   # Stronger originals boost, harder chat dampening
+   export GBRAIN_SOURCE_BOOST="originals/:1.8,wintermute/chat/:0.3"
+   # Add a directory to the hard-exclude list
+   export GBRAIN_SEARCH_EXCLUDE="scratch/,private/"
+   ```
+3. **Verify the outcome:**
+   ```bash
+   gbrain search "<a multi-word topic phrase from your brain>"
+   # Expect: curated content (originals/, concepts/, writing/) at the top.
+   gbrain search "<phrase>" --detail high
+   # Expect: source-boost bypassed; chat pages allowed back.
+   ```
+4. **Rollback one-liner** if something looks off:
+   ```bash
+   unset GBRAIN_SOURCE_BOOST GBRAIN_SEARCH_EXCLUDE
+   ```
+   Reverts ranking to v0.21.0 behavior exactly.
+
+### Itemized changes
+
+#### Source-aware retrieval
+
+- New module `src/core/search/source-boost.ts` ships the default boost map (`originals/` 1.5, `concepts/` 1.3, `writing/` 1.4, `people/companies/deals/` 1.2, `daily/` 0.8, `media/x/` 0.7, `wintermute/chat/` 0.5) and the four default hard-exclude prefixes (`test/`, `archive/`, `attachments/`, `.raw/`). Both knobs override via env (`GBRAIN_SOURCE_BOOST`, `GBRAIN_SEARCH_EXCLUDE`) or per-call SearchOpts.
+- New module `src/core/search/sql-ranking.ts` is a pair of pure SQL-fragment builders shared between Postgres and PGLite engines. `buildSourceFactorCase` emits a longest-prefix-match CASE expression and returns literal `'1.0'` when `detail === 'high'` so temporal queries bypass source-boost. `buildHardExcludeClause` emits `NOT (col LIKE 'p1%' OR col LIKE 'p2%')` ... OR-chain wrapped in NOT, never `NOT LIKE ALL/ANY` (those don't express set-exclusion). LIKE meta-character escape covers `%`, `_`, AND `\` (backslash matters because it's Postgres LIKE's default escape char). Single-quote doubling renders SQL-injection-style inputs inert.
+- `src/core/postgres-engine.ts` and `src/core/pglite-engine.ts` ... three methods wired: `searchKeyword` (chunk-grain CTE → DISTINCT ON page dedup, multiplies ts_rank by source-factor), `searchKeywordChunks` (the chunk-grain anchor primitive used by Cathedral II two-pass retrieval, also gets source-boost so the anchor pool is dampened on chat dirs), and `searchVector` (becomes a two-stage CTE: pure-distance HNSW inner ORDER BY, source-boost re-rank in outer SELECT, innerLimit scales with offset to preserve pagination).
+- `src/core/types.ts` ... SearchOpts gains two fields: `exclude_slug_prefixes?: string[]` (additive over defaults + env) and `include_slug_prefixes?: string[]` (subtractive opt-back-in).
+
+#### Tests
+
+- `test/sql-ranking.test.ts` ... 39 unit cases covering longest-prefix-match, detail=high temporal-bypass, three-meta-char LIKE escape, single-quote SQL-literal doubling, env-var parsing, resolver merge semantics.
+- `test/e2e/search-swamp.test.ts` ... reproduces the headline case in PGLite. Curated article competes with two chat pages stuffed with the same multi-word phrase. Asserts article wins both keyword and vector ranking, detail=high lets chat re-surface, source_id passes through two-stage CTE.
+- `test/e2e/search-exclude.test.ts` ... verifies test/ + archive/ pages hidden by default, include_slug_prefixes opts back in, exclude_slug_prefixes adds to defaults.
+- `test/e2e/engine-parity.test.ts` ... Postgres ↔ PGLite top-result + result-set parity for both search methods plus a hard-exclude parity case. Skips gracefully when DATABASE_URL is unset.
+
+#### Won't break what was already working
+
+The change is additive at the SQL layer; no `hybrid.ts`, `intent.ts`, `dedup.ts`, `expansion.ts`, `two-pass.ts`, or operations-layer changes. RRF fusion, compiled-truth boost, backlink boost, multi-query expansion, source-aware dedup, and v0.21.0's Cathedral II two-pass retrieval all run unchanged downstream of the new ranking. The `sql.begin` + `SET LOCAL statement_timeout` v0.19 wrap is preserved (transaction-scoped GUC; bare SET would leak onto pooled connections, documented DoS vector). RLS-enabled brains still work because both inner and outer CTE SELECTs are subject to row-level policies.
+
+### For contributors
+
+- The two new helpers are pure functions with explicit params and zero engine dependencies. Both engines call them to build identical SQL. Useful pattern for any future SQL-side ranking signal that needs to land in both Postgres and PGLite.
+- The two-stage CTE pattern (HNSW-safe pure-distance inner ORDER BY, re-rank in outer SELECT) is the right shape for any future per-prefix or per-page boost in vector search. Folding extra factors into the outer ORDER BY keeps the index usable.
+- BrainBench Cat 13b lives in [gbrain-evals](https://github.com/garrytan/gbrain-evals) on `feat/cat13b-source-swamp` ... 20-page corpus + 30 hand-curated queries. Companion PR.
+
 ## [0.21.0] - 2026-04-25
 
 ## **Your brain walks the code graph now.**

CLAUDE.md

@@ -25,11 +25,11 @@ strict behavior when unset.
 - `src/core/operations.ts` — Contract-first operation definitions (the foundation). Also exports upload validators: `validateUploadPath`, `validatePageSlug`, `validateFilename`. `OperationContext.remote` flags untrusted callers.
 - `src/core/engine.ts` — Pluggable engine interface (BrainEngine). `clampSearchLimit(limit, default, cap)` takes an explicit cap so per-operation caps can be tighter than `MAX_SEARCH_LIMIT`. Exports `LinkBatchInput` / `TimelineBatchInput` for the v0.12.1 bulk-insert API (`addLinksBatch` / `addTimelineEntriesBatch`). As of v0.13.1, `BrainEngine` has a `readonly kind: 'postgres' | 'pglite'` discriminator so migrations (`src/core/migrate.ts`) and other consumers can branch on engine without `instanceof` + dynamic imports.
 - `src/core/engine-factory.ts` — Engine factory with dynamic imports (`'pglite'` | `'postgres'`)
-- `src/core/pglite-engine.ts` — PGLite (embedded Postgres 17.5 via WASM) implementation, all 40 BrainEngine methods. `addLinksBatch` / `addTimelineEntriesBatch` use multi-row `unnest()` with manual `$N` placeholders. As of v0.13.1, `connect()` wraps `PGlite.create()` in a try/catch that emits an actionable error naming the macOS 26.3 WASM bug (#223) and pointing at `gbrain doctor`; the lock is released on failure so the next process can retry cleanly.
+- `src/core/pglite-engine.ts` — PGLite (embedded Postgres 17.5 via WASM) implementation, all 40 BrainEngine methods. `addLinksBatch` / `addTimelineEntriesBatch` use multi-row `unnest()` with manual `$N` placeholders. As of v0.13.1, `connect()` wraps `PGlite.create()` in a try/catch that emits an actionable error naming the macOS 26.3 WASM bug (#223) and pointing at `gbrain doctor`; the lock is released on failure so the next process can retry cleanly. v0.22.0: `searchKeyword` and `searchKeywordChunks` multiply `ts_rank` by the source-factor CASE expression at the chunk-grain level; `searchVector` becomes a two-stage CTE — inner CTE keeps `ORDER BY cc.embedding <=> vec` so HNSW stays usable, outer SELECT re-ranks by `raw_score * source_factor`. Inner LIMIT scales with offset to preserve pagination contract.
 - `src/core/pglite-schema.ts` — PGLite-specific DDL (pgvector, pg_trgm, triggers)
-- `src/core/postgres-engine.ts` — Postgres + pgvector implementation (Supabase / self-hosted). `addLinksBatch` / `addTimelineEntriesBatch` use `INSERT ... SELECT FROM unnest($1::text[], ...) JOIN pages ON CONFLICT DO NOTHING RETURNING 1` — 4-5 array params regardless of batch size, sidesteps the 65535-parameter cap. As of v0.12.3, `searchKeyword` / `searchVector` scope `statement_timeout` via `sql.begin` + `SET LOCAL` so the GUC dies with the transaction instead of leaking across the pooled postgres.js connection (contributed by @garagon). `getEmbeddingsByChunkIds` uses `tryParseEmbedding` so one corrupt row skips+warns instead of killing the query.
+- `src/core/postgres-engine.ts` — Postgres + pgvector implementation (Supabase / self-hosted). `addLinksBatch` / `addTimelineEntriesBatch` use `INSERT ... SELECT FROM unnest($1::text[], ...) JOIN pages ON CONFLICT DO NOTHING RETURNING 1` — 4-5 array params regardless of batch size, sidesteps the 65535-parameter cap. As of v0.12.3, `searchKeyword` / `searchVector` scope `statement_timeout` via `sql.begin` + `SET LOCAL` so the GUC dies with the transaction instead of leaking across the pooled postgres.js connection (contributed by @garagon). `getEmbeddingsByChunkIds` uses `tryParseEmbedding` so one corrupt row skips+warns instead of killing the query. v0.22.0: `searchKeyword`, `searchKeywordChunks`, and `searchVector` apply source-aware ranking by inlining the source-factor CASE and `NOT (col LIKE …)` hard-exclude clause from `src/core/search/sql-ranking.ts`. `searchVector` switches to a two-stage CTE (HNSW-safe inner ORDER BY, source-boost re-rank in the outer SELECT) and carries `p.source_id` through inner→outer for v0.18 multi-source callers. v0.22.1 (#406): `_savedConfig` retains the connect config; `reconnect()` tears down + recreates the pool from saved config (called by supervisor watchdog after 3 consecutive health-check failures). `executeRaw` is a single-statement passthrough — no per-call retry (D3 dropped that as unsound for non-idempotent statements; recovery is supervisor-driven). v0.22.1 (#363, contributed by @orendi84): `connect()` applies `resolveSessionTimeouts()` from `db.ts` as connection-time startup parameters (`statement_timeout`, `idle_in_transaction_session_timeout`) so orphan pgbouncer backends can't hold locks for hours. v0.22.1 (#409, contributed by @atrevino47): `countStaleChunks()` + `listStaleChunks()` server-side-filter on `embedding IS NULL` for `embed --stale`, eliminating ~76 MB/call client-side pull on a fully-embedded brain; `upsertChunks()` resets both `embedding` AND `embedded_at` to NULL when chunk_text changes without a new embedding (consistency).
 - `src/core/utils.ts` — Shared SQL utilities extracted from postgres-engine.ts. Exports `parseEmbedding(value)` (throws on unknown input, used by migration + ingest paths where data integrity matters) and as of v0.12.3 `tryParseEmbedding(value)` (returns `null` + warns once per process, used by search/rescore paths where availability matters more than strictness).
-- `src/core/db.ts` — Connection management, schema initialization
+- `src/core/db.ts` — Connection management, schema initialization. v0.22.1 (#363, contributed by @orendi84): `resolveSessionTimeouts()` returns `statement_timeout` + `idle_in_transaction_session_timeout` (defaults: 5min each, env-overridable via `GBRAIN_STATEMENT_TIMEOUT` / `GBRAIN_IDLE_TX_TIMEOUT` / `GBRAIN_CLIENT_CHECK_INTERVAL`). Both `connect()` (module singleton) and `PostgresEngine.connect()` (worker pool) consume the result via postgres.js's `connection` option, sending GUCs as startup parameters that survive PgBouncer transaction mode (unlike the prior `setSessionDefaults` post-pool SET, kept as a back-compat no-op shim).
 - `src/commands/migrate-engine.ts` — Bidirectional engine migration (`gbrain migrate --to supabase/pglite`)
 - `src/core/import-file.ts` — importFromFile + importFromContent (chunk + embed + tags)
 - `src/core/sync.ts` — Pure sync functions (manifest parsing, filtering, slug conversion)
@@ -40,9 +40,11 @@ strict behavior when unset.
 - `src/core/errors.ts` (v0.19.0) — `StructuredAgentError` + `buildError` + `serializeError`. Every new v0.19.0 agent-facing surface (code-def, code-refs, usage errors) uses this envelope; matches v0.17.0 `CycleReport.PhaseResult.error` shape.
 - `src/assets/wasm/` (v0.19.0) — 36 tree-sitter grammar WASMs + tree-sitter runtime. Committed to the repo so `bun --compile` embeds them deterministically via `import path from ... with { type: 'file' }`. The CI guard `scripts/check-wasm-embedded.sh` fails the build if the compiled binary ever silently falls through to recursive chunks.
 - `src/commands/code-def.ts` + `src/commands/code-refs.ts` (v0.19.0) — symbol definition + references lookup. Query `content_chunks.symbol_name` or chunk_text ILIKE with `page_kind='code'` filter. Auto-JSON when stdout is not a TTY (gh-CLI convention). Bypass the standard `searchKeyword` `DISTINCT ON (slug)` collapse so multiple call-sites from the same file surface.
-- `src/core/search/` — Hybrid search: vector + keyword + RRF + multi-query expansion + dedup
+- `src/core/search/` — Hybrid search: vector + keyword + RRF + multi-query expansion + dedup. As of v0.22.0, `searchKeyword` / `searchKeywordChunks` / `searchVector` apply source-aware ranking at the SQL layer (curated content like `originals/`, `concepts/`, `writing/` outranks bulk content like `wintermute/chat/`, `daily/`, `media/x/`). `searchVector` uses a two-stage CTE so source-boost re-ranking doesn't kill the HNSW index. Hard-exclude prefixes (`test/`, `archive/`, `attachments/`, `.raw/` by default) filter at retrieval, not post-rank. Both gates honor `detail !== 'high'` so temporal queries surface chat pages normally.
 - `src/core/search/intent.ts` — Query intent classifier (entity/temporal/event/general → auto-selects detail level)
 - `src/core/search/eval.ts` — Retrieval eval harness: P@k, R@k, MRR, nDCG@k metrics + runEval() orchestrator
+- `src/core/search/source-boost.ts` (v0.22.0) — Source-type boost map keyed by slug prefix. `DEFAULT_SOURCE_BOOSTS` (originals/ 1.5, concepts/ 1.3, writing/ 1.4, people/companies/deals/ 1.2, daily/ 0.8, media/x/ 0.7, wintermute/chat/ 0.5) and `DEFAULT_HARD_EXCLUDES` (test/, archive/, attachments/, .raw/). `parseSourceBoostEnv` / `parseHardExcludesEnv` parse comma-separated `prefix:factor` pairs from `GBRAIN_SOURCE_BOOST` / `GBRAIN_SEARCH_EXCLUDE` env vars. `resolveBoostMap` and `resolveHardExcludes` merge defaults + env + caller `SearchOpts.exclude_slug_prefixes`/`include_slug_prefixes`.
+- `src/core/search/sql-ranking.ts` (v0.22.0) — Pure SQL string builders. `buildSourceFactorCase(slugColumn, boostMap, detail)` emits a CASE expression with longest-prefix-match wins (returns literal `'1.0'` when `detail === 'high'` for temporal-bypass parity with COMPILED_TRUTH_BOOST). `buildHardExcludeClause(slugColumn, prefixes)` emits `NOT (col LIKE 'p1%' OR col LIKE 'p2%')` — OR-chain wrapped in NOT, NOT `NOT LIKE ALL/ANY` (those quantifiers don't express set-exclusion). LIKE meta-character escape covers all three of `%`, `_`, AND `\` (backslash matters because it's Postgres LIKE's default escape char). Single-quote doubling on SQL string literals so injection-style inputs are inert text.
 - `src/commands/eval.ts` — `gbrain eval` command: single-run table + A/B config comparison
 - `src/core/embedding.ts` — OpenAI text-embedding-3-large, batch, retry, backoff
 - `src/core/check-resolvable.ts` — Resolver validation: reachability, MECE overlap, DRY checks, structured fix objects. v0.14.1: `CROSS_CUTTING_PATTERNS.conventions` is an array (notability gate accepts both `conventions/quality.md` and `_brain-filing-rules.md`). New `extractDelegationTargets()` parses `> **Convention:**`, `> **Filing rule:**`, and inline backtick references. DRY suppression is proximity-based via `DRY_PROXIMITY_LINES = 40`.
@@ -61,12 +63,14 @@ strict behavior when unset.
 - `src/core/transcription.ts` — Audio transcription: Groq Whisper (default), OpenAI fallback, ffmpeg segmentation for >25MB
 - `src/core/enrichment-service.ts` — Global enrichment service: entity slug generation, tier auto-escalation, batch throttling
 - `src/core/data-research.ts` — Recipe validation, field extraction (MRR/ARR regex), dedup, tracker parsing, HTML stripping
-- `src/commands/extract.ts` — `gbrain extract links|timeline|all [--source fs|db]`: batch link/timeline extraction. fs walks markdown files, db walks pages from the engine (mutation-immune snapshot iteration; use this for live brains with no local checkout). As of v0.12.1 there is no in-memory dedup pre-load — candidates are buffered 100 at a time and flushed via `addLinksBatch` / `addTimelineEntriesBatch`; `ON CONFLICT DO NOTHING` enforces uniqueness at the DB layer, and the `created` counter returns real rows inserted (truthful on re-runs).
+- `src/commands/embed.ts` — `gbrain embed [--stale|--all] [--slugs ...]`. v0.22.1 (#409, contributed by @atrevino47): `--stale` path now starts with `engine.countStaleChunks()` (single SELECT count(*) WHERE embedding IS NULL, ~50 bytes wire). On a fully-embedded brain that's a 1-line short-circuit — no further reads. When stale chunks exist, `engine.listStaleChunks()` returns just the chunks needing embeddings (slug + chunk_index + chunk_text + metadata, no `vector(1536)` payload). Caller groups by slug, embeds via OpenAI, re-upserts via `upsertChunks`. Replaces the prior page-walk that pulled every chunk's embedding column over the wire and discarded most.
+- `src/commands/extract.ts` — `gbrain extract links|timeline|all [--source fs|db]`: batch link/timeline extraction. fs walks markdown files, db walks pages from the engine (mutation-immune snapshot iteration; use this for live brains with no local checkout). As of v0.12.1 there is no in-memory dedup pre-load — candidates are buffered 100 at a time and flushed via `addLinksBatch` / `addTimelineEntriesBatch`; `ON CONFLICT DO NOTHING` enforces uniqueness at the DB layer, and the `created` counter returns real rows inserted (truthful on re-runs). v0.22.1 (#417): `ExtractOpts.slugs?: string[]` enables incremental extract — when set, `extractForSlugs()` reads ONLY those slugs' files (single combined links+timeline pass) instead of the full directory walk. CLI `gbrain extract` keeps full-walk behavior; the cycle path threads sync's `pagesAffected` through. `walkMarkdownFiles(brainDir)` still runs at line 455 to build `allSlugs` for link resolution — see `TODOS.md` for replacing it with `engine.getAllSlugs()`.
 - `src/commands/graph-query.ts` — `gbrain graph-query <slug> [--type T] [--depth N] [--direction in|out|both]`: typed-edge relationship traversal (renders indented tree)
 - `src/core/link-extraction.ts` — shared library for the v0.12.0 graph layer. extractEntityRefs (canonical, replaces backlinks.ts duplicate) matches both `[Name](people/slug)` markdown links and Obsidian `[[people/slug|Name]]` wikilinks as of v0.12.3. extractPageLinks, inferLinkType heuristics (attended/works_at/invested_in/founded/advises/source/mentions), parseTimelineEntries, isAutoLinkEnabled config helper. `DIR_PATTERN` covers `people`, `companies`, `deals`, `topics`, `concepts`, `projects`, `entities`, `tech`, `finance`, `personal`, `openclaw`. Used by extract.ts, operations.ts auto-link post-hook, and backlinks.ts.
 - `src/core/minions/` — Minions job queue: BullMQ-inspired, Postgres-native (queue, worker, backoff, types, protected-names, quiet-hours, stagger, handlers/shell).
 - `src/core/minions/queue.ts` — MinionQueue class (submit, claim, complete, fail, stall detection, parent-child, depth/child-cap, per-job timeouts, cascade-kill, attachments, idempotency keys, child_done inbox, removeOnComplete/Fail). `add()` takes a 4th `trusted` arg (separate from `opts` to prevent spread leakage); protected names in `PROTECTED_JOB_NAMES` require `{allowProtectedSubmit: true}` and the check runs trim-normalized (whitespace-bypass safe). v0.14.1 #219: `add()` plumbs `max_stalled` through with a `[1, 100]` clamp; omitted values let the schema DEFAULT (5) kick in. v0.19.0: `handleWallClockTimeouts(lockDurationMs)` is Layer 3 kill shot for jobs where `FOR UPDATE SKIP LOCKED` stall detection and the timeout sweep both fail to evict (wedged worker holding a row lock via a pending transaction). v0.19.1: `maxWaiting` coalesce path now uses `pg_advisory_xact_lock` keyed on `(name, queue)` to serialize concurrent submits for the same key, and filters on `queue` in addition to `name` so cross-queue same-name jobs don't suppress each other.
-- `src/core/minions/worker.ts` — MinionWorker class (handler registry, lock renewal, graceful shutdown, timeout safety net). v0.14.0 abort-path fix: aborted jobs now call `failJob` with reason (`timeout`/`cancel`/`lock-lost`/`shutdown`) instead of returning silently. `shutdownAbort` (instance field) fires on process SIGTERM/SIGINT and propagates to `ctx.shutdownSignal` — shell handler listens to it; non-shell handlers don't.
+- `src/core/minions/worker.ts` — MinionWorker class (handler registry, lock renewal, graceful shutdown, timeout safety net). v0.14.0 abort-path fix: aborted jobs now call `failJob` with reason (`timeout`/`cancel`/`lock-lost`/`shutdown`) instead of returning silently. `shutdownAbort` (instance field) fires on process SIGTERM/SIGINT and propagates to `ctx.shutdownSignal` — shell handler listens to it; non-shell handlers don't. v0.22.1 (#403): per-job timeout fires `abort.abort(new Error('timeout'))` then a 30-second grace-then-evict safety net force-evicts the job from `inFlight` and marks it dead in DB if the handler ignores the abort signal — frees the slot even when a handler wedges (the 98-waiting-0-active prod incident driver).
+- `src/core/minions/supervisor.ts` — MinionSupervisor process manager. Spawns `gbrain jobs work` as a child, restarts on crash with exponential backoff, periodic health check. v0.22.1 (#406): `consecutiveHealthFailures` counter; on 3 consecutive failures emits `health_warn` with `reason: 'db_connection_degraded'` and calls `engine.reconnect()` to swap in a fresh pool, then resets the counter. Worker exit classifier emits `likely_cause` field on `worker_exited` events: `oom_or_external_kill` (SIGKILL), `graceful_shutdown` (SIGTERM), `runtime_error` (code 1), `clean_exit` (code 0), `unknown`.
 - `src/core/minions/types.ts` — `MinionJobInput` + `MinionJobStatus` + handler context types. `MinionJobInput.max_stalled` (new in v0.14.1) is optional; omitted values let the schema DEFAULT (5) kick in, provided values are clamped to `[1, 100]`.
 - `src/core/minions/protected-names.ts` — side-effect-free constant module exporting `PROTECTED_JOB_NAMES` + `isProtectedJobName()`. Kept pure so queue core can import without loading handler modules.
 - `src/core/minions/handlers/shell.ts` — `shell` job handler. Spawns `/bin/sh -c cmd` (absolute path, PATH-override-safe) or `argv[0] argv[1..]` (no shell). Env allowlist: `PATH, HOME, USER, LANG, TZ, NODE_ENV` + caller `env:` overrides. UTF-8-safe stdout/stderr tail via `string_decoder.StringDecoder`. Abort (either `ctx.signal` or `ctx.shutdownSignal`) fires SIGTERM → 5s grace → SIGKILL on child. Requires `GBRAIN_ALLOW_SHELL_JOBS=1` on worker (gated by `registerBuiltinHandlers`).
@@ -97,7 +101,7 @@ strict behavior when unset.
 - `src/core/migrate.ts` — schema-migration runner. Owns the `MIGRATIONS` array (source of truth for schema DDL). v0.14.2 extended the `Migration` interface with `sqlFor?: { postgres?, pglite? }` (engine-specific SQL overrides `sql`) and `transaction?: boolean` (set to false for `CREATE INDEX CONCURRENTLY`, which Postgres refuses inside a transaction; ignored on PGLite since it has no concurrent writers). Migration v14 (fix wave) uses a handler branching on `engine.kind` to run CONCURRENTLY on Postgres (with a pre-drop of any invalid remnant via `pg_index.indisvalid`) and plain `CREATE INDEX` on PGLite. v15 bumps `minion_jobs.max_stalled` default 1→5 and backfills existing non-terminal rows.
 - `src/core/progress.ts` — Shared bulk-action progress reporter. Writes to stderr. Modes: `auto` (TTY: `\r`-rewriting; non-TTY: plain lines), `human`, `json` (JSONL), `quiet`. Rate-gated by `minIntervalMs` and `minItems`. `startHeartbeat(reporter, note)` helper for single long queries. `child()` composes phase paths. Singleton SIGINT/SIGTERM coordinator emits `abort` events for every live phase. EPIPE defense on both sync throws and stream `'error'` events. Zero dependencies. Introduced in v0.15.2.
 - `src/core/cli-options.ts` — Global CLI flag parser. `parseGlobalFlags(argv)` returns `{cliOpts, rest}` with `--quiet` / `--progress-json` / `--progress-interval=<ms>` stripped. `getCliOptions()` / `setCliOptions()` expose a module-level singleton so commands reach the resolved flags without parameter threading. `cliOptsToProgressOptions()` maps to reporter options. `childGlobalFlags()` returns the flag suffix to append to `execSync('gbrain ...')` calls in migration orchestrators. `OperationContext.cliOpts` extends shared-op dispatch for MCP callers.
-- `src/core/cycle.ts` — v0.17 brain maintenance cycle primitive. `runCycle(engine: BrainEngine | null, opts: CycleOpts): Promise<CycleReport>` composes 6 phases in semantically-driven order (lint → backlinks → sync → extract → embed → orphans). Three callers: `gbrain dream` CLI, `gbrain autopilot` daemon's inline path, and the Minions `autopilot-cycle` handler (`src/commands/jobs.ts`). One source of truth for what the brain does overnight. Coordination via `gbrain_cycle_locks` DB table (TTL-based; works through PgBouncer transaction pooling, unlike session-scoped `pg_try_advisory_lock`) + `~/.gbrain/cycle.lock` file lock with PID-liveness for PGLite / engine=null mode. `CycleReport.schema_version: "1"` is the stable agent-consumable shape. `PhaseResult.error: { class, code, message, hint?, docs_url? }` is Stripe-API-tier structured failure info. `yieldBetweenPhases` hook awaited between every phase — Minions handler uses this to renew its job lock and prevent v0.14 stall-death regression. Engine nullable: filesystem phases (lint, backlinks) run without DB; DB phases skip with `status: "skipped", reason: "no_database"`. Lock-skip: read-only phase selections (`--phase orphans`) bypass the cycle lock.
+- `src/core/cycle.ts` — v0.17 brain maintenance cycle primitive. `runCycle(engine: BrainEngine | null, opts: CycleOpts): Promise<CycleReport>` composes 6 phases in semantically-driven order (lint → backlinks → sync → extract → embed → orphans). Three callers: `gbrain dream` CLI, `gbrain autopilot` daemon's inline path, and the Minions `autopilot-cycle` handler (`src/commands/jobs.ts`). One source of truth for what the brain does overnight. Coordination via `gbrain_cycle_locks` DB table (TTL-based; works through PgBouncer transaction pooling, unlike session-scoped `pg_try_advisory_lock`) + `~/.gbrain/cycle.lock` file lock with PID-liveness for PGLite / engine=null mode. `CycleReport.schema_version: "1"` is the stable agent-consumable shape. `PhaseResult.error: { class, code, message, hint?, docs_url? }` is Stripe-API-tier structured failure info. `yieldBetweenPhases` hook awaited between every phase — Minions handler uses this to renew its job lock and prevent v0.14 stall-death regression. Engine nullable: filesystem phases (lint, backlinks) run without DB; DB phases skip with `status: "skipped", reason: "no_database"`. Lock-skip: read-only phase selections (`--phase orphans`) bypass the cycle lock. v0.22.1 (#403): `CycleOpts.signal?: AbortSignal` propagates the worker's abort signal; `checkAborted()` fires between every phase and throws if the signal is aborted (cooperative — can't interrupt a phase mid-execution). v0.22.1 (#417): `runPhaseSync` returns `pagesAffected` via `SyncPhaseResult`; `runCycle` captures it and threads to `runPhaseExtract` as the 4th arg, enabling incremental extract on the cycle path. v0.22.1 (Codex F2): `runPhaseSync` takes `willRunExtractPhase: boolean` and sets `noExtract: phases.includes('extract')` so `gbrain dream --phase sync` doesn't silently lose extraction. v0.22.5 (#475): new `resolveSourceForDir(engine, brainDir)` helper queries `SELECT id FROM sources WHERE local_path = $1 LIMIT 1`; `runPhaseSync` threads result as `sourceId` to `performSync()` so sync reads the per-source `sources.last_commit` anchor instead of the drift-prone global `config.sync.last_commit` key. Bare try/catch lets pre-v0.18 brains fall through to the global key. Closes the prod hang where every autopilot cycle ran a 30-min full reimport because the global anchor commit had been GC'd from git history.
 - `src/commands/dream.ts` — v0.17 `gbrain dream` CLI. ~80-line thin alias over `runCycle`. brainDir resolution requires explicit `--dir` OR `sync.repo_path` config (no more walk-up-cwd-for-.git footgun). Flags: `--dry-run`, `--json`, `--phase <name>`, `--pull`, `--dir <path>`. Exit code 1 on status=failed (partial/warn not fatal — don't page on warnings).
 - `scripts/check-progress-to-stdout.sh` — CI guard against regressing to `\r`-on-stdout progress. Wired into `bun run test` via `scripts/check-progress-to-stdout.sh && bun test` in package.json.
 - `docs/progress-events.md` — Canonical JSON event schema reference. Stable from v0.15.2, additive only.
@@ -233,6 +237,7 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/skills-conformance.test.ts` (skill frontmatter + required sections validation),
 `test/resolver.test.ts` (RESOLVER.md coverage, routing validation + v0.20.4 round-trip: every quoted RESOLVER.md trigger must match a frontmatter `triggers:` entry in the target skill, and every `name="<word>"` reference in any SKILL.md must resolve to a declared op in `src/core/operations.ts` or a Minions handler in `PROTECTED_JOB_NAMES`),
 `test/search.test.ts` (RRF normalization, compiled truth boost, cosine similarity, dedup key),
+`test/sql-ranking.test.ts` (v0.22.0 source-boost helpers: 39 cases covering longest-prefix-match in SQL CASE, detail=high temporal-bypass, three-meta-char LIKE escape (%, _, \\), single-quote SQL-literal doubling, env override parsing for GBRAIN_SOURCE_BOOST + GBRAIN_SEARCH_EXCLUDE, resolveBoostMap / resolveHardExcludes merge semantics),
 `test/dedup.test.ts` (source-aware dedup, compiled truth guarantee, layer interactions),
 `test/intent.test.ts` (query intent classification: entity/temporal/event/general),
 `test/eval.test.ts` (retrieval metrics: precisionAtK, recallAtK, mrr, ndcgAtK, parseQrels),
@@ -281,6 +286,9 @@ E2E tests (`test/e2e/`): Run against real Postgres+pgvector. Require `DATABASE_U
 - `test/e2e/upgrade.test.ts` runs check-update E2E against real GitHub API (network required)
 - `test/e2e/minions-shell-pglite.test.ts` (v0.20.4) exercises the PGLite `--follow` inline shell-job path (in-memory, no `DATABASE_URL` required) — the path the consolidated minion-orchestrator skill documents for dev use
 - `test/e2e/openclaw-reference-compat.test.ts` (v0.19) — exercises `check-resolvable` + `skillpack install` against a minimal AGENTS.md workspace fixture (`test/fixtures/openclaw-reference-minimal/`), regression guard for the 107-skill OpenClaw deployment shape
+- `test/e2e/search-swamp.test.ts` (v0.22.0) — reproduces the headline source-swamp case. Seeds a curated `originals/talks/article-outline-fat-code` page against two `wintermute/chat/` pages stuffed with the same multi-word phrase. Asserts the article wins keyword AND vector ranking, that `detail=high` lets the chat swamp re-surface (temporal-query workflow preserved), and that `source_id` passes through the two-stage CTE intact. PGLite in-memory.
+- `test/e2e/search-exclude.test.ts` (v0.22.0) — verifies `test/` + `archive/` pages are hidden by default, that `include_slug_prefixes` opts back in, and that caller-supplied `exclude_slug_prefixes` adds to defaults. Both keyword and vector search paths covered.
+- `test/e2e/engine-parity.test.ts` (v0.22.0) — Postgres ↔ PGLite top-result and result-set parity for `searchKeyword` + `searchVector`. Codex flagged that Postgres ranks pages then picks best chunk while PGLite returns chunks directly — without parity coverage the source-boost fix could pass on PGLite and fail on Postgres. Skips gracefully when `DATABASE_URL` is unset.
 - Tier 2 (`skills.test.ts`) requires OpenClaw + API keys, runs nightly in CI
 - If `.env.testing` doesn't exist in this directory, check sibling worktrees for one:
   `find ../  -maxdepth 2 -name .env.testing -print -quit` and copy it here if found.
@@ -395,6 +403,59 @@ in bulk paths, the CI guard will fail the build.
 
 `bun build --compile --outfile bin/gbrain src/cli.ts`
 
+## Version locations (single source of truth: `VERSION` file)
+
+Every release advances the version in **five files at once**. Keep these in
+sync. `/ship` enforces this via Step 12's idempotency check (VERSION vs
+package.json drift), but the canonical list lives here so future runs and
+the auto-update agent know where to look.
+
+**Required (every release must update all five):**
+
+| File | What lives there | Format |
+|---|---|---|
+| `VERSION` | The single source of truth. Read first by `/ship`, the binary, and CI version-gate. | Bare 4-digit string `MAJOR.MINOR.PATCH.MICRO` (e.g. `0.22.1`), no leading `v`, no trailing newline-sensitivity issues. |
+| `package.json` | Bun/npm package version. `gbrain --version` reads it via the compiled binary's bundled package metadata. CI version-gate cross-checks this against `VERSION` and fails if they drift. | `"version": "0.22.1"` |
+| `CHANGELOG.md` | Top entry header `## [0.22.1] - YYYY-MM-DD` plus the "To take advantage of v0.22.1" block. | Standard Keep-a-Changelog header. |
+| `TODOS.md` | Any TODO entries that mention "follow-up from vX.Y.Z" use the version of the release that filed them. Update only when filing NEW follow-up TODOs. | Inline `vX.Y.Z` references in TODO bodies. |
+| `CLAUDE.md` | The Key Files section's per-file annotations carry `vX.Y.Z (#NNN)` tags noting which release introduced a behavior. Update whenever a wave's annotations get folded in. | Inline `vX.Y.Z (#NNN, contributed by @user)` references. |
+
+**Auto-derived (no manual edit; refreshed by their own commands):**
+
+- `bun.lock` — root-package version is auto-pinned from `package.json`. After
+  bumping `package.json`, run `bun install` to refresh the lockfile.
+- `llms-full.txt` / `llms.txt` — auto-generated documentation bundles. After
+  any release ship that touches the Key Files annotations in `CLAUDE.md`,
+  run `bun run build:llms` to regenerate. The bundles do not contain a
+  version pin per se; they reflect the current state of the docs they index.
+
+**Historical (DO NOT bump on release):**
+
+- `skills/migrations/v0.21.0.md` — migration files use the version they
+  shipped FROM as their filename. v0.21.0's migration always says v0.21.0.
+- `src/commands/migrations/v0_21_0.ts` — same: migration code references
+  the schema version it migrates to.
+- `test/migrations-v0_21_0.test.ts`, `test/migration-orchestrator-v0_21_0.test.ts`,
+  `test/migrate.test.ts` — migration tests reference historical migration
+  versions; these are correct as-is and should not move.
+- `src/core/db.ts`, `src/core/migrate.ts`, `src/core/import-file.ts`,
+  `src/commands/reindex-code.ts` — code comments cite the release that
+  introduced a feature. Once written, these are historical record.
+- `README.md` — references the latest published feature names by version
+  (e.g. "v0.21.0 Code Cathedral"); update only when the README's marketing
+  copy is intentionally being refreshed, NOT on every micro/patch bump.
+
+**The /ship workflow's version idempotency check:** Step 12 reads
+`VERSION` and `package.json`, classifies as FRESH / ALREADY_BUMPED /
+DRIFT_STALE_PKG / DRIFT_UNEXPECTED, and refuses to proceed on
+DRIFT_UNEXPECTED. This is why the two must move together.
+
+**The CI version-gate** rejects pushes where `VERSION` and
+`package.json` disagree, OR where `VERSION` is not strictly greater
+than master's VERSION. If a queue collision claims your version on
+master before yours lands, /ship's queue-aware allocator (Step 12)
+will detect drift and re-bump on the next run.
+
 ## Pre-ship requirements
 
 Before shipping (/ship) or reviewing (/review), always run the full test suite:

README.md

@@ -505,6 +505,8 @@ Question
   │    ├─ Multi-query expansion (Haiku rephrases the question 3 ways)
   │    ├─ Vector search (HNSW cosine over OpenAI embeddings)
   │    ├─ Keyword search (Postgres tsvector + websearch_to_tsquery)
+  │    ├─ Source-aware ranking (curated dirs outrank chat/daily swamp at SQL layer)
+  │    ├─ Hard-exclude (test/ archive/ attachments/ .raw/ filtered before retrieval)
   │    ├─ Reciprocal Rank Fusion (score = sum 1/(60+rank) across both)
   │    ├─ Cosine re-scoring (re-rank chunks against actual query embedding)
   │    ├─ Compiled-truth boost (assessments outrank timeline noise)

TODOS.md

@@ -1,5 +1,51 @@
 # TODOS
 
+## resolver / check-resolvable (v0.22.4 follow-ups)
+
+### D10 — Extend `check-resolvable` to parse RESOLVER.md disambiguation rules
+**Priority:** P2
+
+**What:** Extend `src/core/check-resolvable.ts:357-390` to parse a structured
+disambiguation block in `RESOLVER.md` (e.g. a `## Disambiguation rules`
+numbered list with parseable `<trigger>` → `<winning-skill>` shape) and treat
+resolved overlaps as non-issues. Then the action message at
+`src/core/check-resolvable.ts:388` ("Add disambiguation rule in RESOLVER.md OR
+narrow triggers") stops lying about the OR — currently only the second branch
+silences the warning.
+
+**Why:** The current MECE-overlap fix path forces authors to delete user-facing
+triggers from skill frontmatter. That's wrong for cases where two skills
+legitimately respond to the same phrase under different contexts (e.g.
+"citation audit" → focused fix vs broader brain health). A real
+disambiguation parser would let `RESOLVER.md` carry the resolution while
+keeping both skills' triggers intact for chaining.
+
+**Pros:**
+- The action message stops misleading users.
+- v0.22.4 D2 used the "narrow triggers" path because the disambiguation
+  parser doesn't exist yet; landing this would let v0.23+ keep dual triggers
+  for genuinely-overlapping skills.
+- Aligns RESOLVER.md's stated role (the dispatcher) with what the checker
+  actually reads.
+
+**Cons:**
+- Introduces a new `RESOLVER.md` syntactic contract that other tooling now
+  has to respect (parser, lint, downstream forks reading the same file).
+- Risk of false-positive resolution if the parser is loose.
+- ~80 lines of parser + tests; not blocking anything in v0.22.4.
+
+**Context:**
+- The "OR" in the action message is misleading today. Confirmed at
+  `src/core/check-resolvable.ts:388`.
+- The MECE detector loop is at `src/core/check-resolvable.ts:357-390`.
+- The disambiguation rules already exist as prose in
+  `skills/RESOLVER.md` (the citation-audit row added in v0.22.4 is the
+  pattern). They're agent-facing routing hints today, not parsed structure.
+
+**Effort:** S (human: ~4-6 hours / CC: ~30 min for parser + 12-16 test cases).
+
+**Depends on / blocked by:** Nothing.
+
 ## code-indexing (v0.21.0 Cathedral II follow-ups)
 
 ### B2 — Magika auto-detect for extension-less files (Layer 9 deferred)
@@ -473,3 +519,48 @@ iteration's residuals.
 
 ### Implement AWS Signature V4 for S3 storage backend
 **Completed:** v0.6.0 (2026-04-10) — replaced with @aws-sdk/client-s3 for proper SigV4 signing.
+
+### Caller-opt-in retry for `executeRaw` (D3 follow-up from v0.22.1)
+**What:** Add `PostgresEngine.executeRawIdempotent(sql, params)` (or a `{retry: true}` parameter flag on `executeRaw`) so callers explicitly opt into auto-retry for statements they know are idempotent. Audit existing call sites and migrate the read-only ones (search, page fetches, etc.) to the new method.
+
+**Why:** Closes the gap left by D3's drop-the-wrapper decision in v0.22.1. The original #406 wrapped `executeRaw` in a regex-gated retry that was unsound for writable CTEs and side-effecting SELECTs. Recovery moved up to the supervisor watchdog, but per-call recovery for reads (the bulk of `executeRaw` traffic from MCP, search, page fetches) is gone. A caller-opt-in flag puts the idempotency decision where it belongs (at the call site, with full statement context).
+
+**Pros:** Restores per-call auto-recovery for reads without the phantom-write risk on mutations. Explicit > clever: each call site declares its own idempotency posture. Future caller-added mutations get safe-by-default behavior.
+
+**Cons:** Touches every existing `executeRaw` call site (~25). Requires careful audit — accidentally tagging a mutation as idempotent re-introduces the phantom-write bug.
+
+**Context:** Codex F3 demonstrated that `READ_ONLY_PREFIX = /^(\s|--.*\n)*(SELECT|WITH)\b/i` is unsound — `WITH x AS (UPDATE … RETURNING …) SELECT …` matches the prefix but updates a row; `SELECT pg_advisory_xact_lock(...)` is a SELECT with side effects. The plan-eng-review wrap-up in `~/.claude/plans/system-instruction-you-are-working-tender-horizon.md` has the full discussion.
+
+**Effort estimate:** M (human: ~1 day / CC: ~30 min including call-site audit).
+**Priority:** P2 — current behavior (no retry, supervisor recovers within ~3 min) is acceptable but per-call recovery is a real ergonomic win.
+**Depends on:** Nothing.
+
+### Replace `walkMarkdownFiles` with `engine.getAllSlugs()` in `extractForSlugs` (F1 follow-up from v0.22.1)
+**What:** The cycle path's `extractForSlugs()` at `src/commands/extract.ts:455` still does a `walkMarkdownFiles(brainDir)` to build the `allSlugs` set for link resolution. On a 54K-page brain that's a single `readdir` traversal (~hundreds of ms — acceptable, dominated by the file-content-read elimination from #417). But `engine.getAllSlugs()` exists at `extract.ts:728` and produces the same set via a single SQL query (~tens of ms).
+
+**Why:** Eliminates the residual directory walk on every cycle. Codex F1 noted that the v0.22.1 plan's "cycle never re-walks the whole tree again" claim was overstated — it stops READING file contents but still walks the directory. This TODO closes that gap honestly.
+
+**Pros:** Cycle becomes O(slugs sync touched), not O(total brain size). No more readdir on a growing brain. ~5 LOC change.
+
+**Cons:** Crosses an FS-vs-DB consistency boundary in the FS-source extract path. Edge case: a file deleted from disk but still in DB. Currently `extractForSlugs` skips with `if (!existsSync(fullPath)) continue` — unchanged. But if a markdown file references a slug whose page exists in DB but file was deleted, the link would resolve via DB but the original extractor caught it. Needs a careful test for this case.
+
+**Context:** Codex plan-review during v0.22.1 wrap, verified at `extract.ts:455-456`. The plan-eng-review session captured the rationale.
+
+**Effort estimate:** S (human: ~2 hr / CC: ~10 min including the consistency-edge-case test).
+**Priority:** P3 — pure perf, no correctness gap.
+**Depends on:** Nothing.
+
+### `err.code`-based connection-error matching in `postgres-engine.ts` (B1 follow-up from v0.22.1)
+**What:** The CONNECTION_ERROR_PATTERNS array (~12 strings: `ECONNREFUSED`, `connection terminated`, `password authentication failed`, etc.) matched against `err.message` and `err.code`. Replace with structured matching against `err.code` only, using postgres.js's typed error classes (`PostgresError` with structured codes).
+
+**Why:** String matching against error messages breaks on library upgrades (postgres.js could change its error message phrasing without bumping major). Code matching is durable. The Layer 1 cleanup follows: gbrain itself doesn't define connection-error codes; it should defer to postgres.js's classification.
+
+**Pros:** More durable across library updates. Less code (drop the 12-string array). Follows the typed-errors pattern v0.21.0 introduced (`src/core/errors.ts`).
+
+**Cons:** Requires verifying which `err.code` values postgres.js actually exposes for each connection-failure mode. May need fallback to message-substring matching for codes that postgres.js doesn't surface.
+
+**Context:** Section 2/B1 from the v0.22.1 plan-eng-review. After D3 dropped the per-call retry, `isConnectionError` is no longer in the hot path — only the supervisor watchdog cares about classifying connection errors, and it currently catches *anything*. This TODO is a cleanup pass when someone next touches that surface.
+
+**Effort estimate:** S (human: ~2 hr / CC: ~10 min).
+**Priority:** P3.
+**Depends on:** The above caller-opt-in retry (#1) is the natural co-lander since both touch the same error-classification surface.

VERSION

@@ -1 +1 @@
-0.21.0
+0.22.5

docs/UPGRADING_DOWNSTREAM_AGENTS.md

@@ -458,6 +458,75 @@ in depth, not the primary boundary.
 
 ---
 
+## v0.22.4 — frontmatter-guard adoption
+
+### 1. Stop hand-rolling frontmatter validators
+
+If your fork has scripts that call `js-yaml` directly to validate brain page
+frontmatter, replace them with `gbrain frontmatter validate` calls. The CLI
+covers the seven canonical error classes and ships a `--json` envelope that's
+stable across releases.
+
+```diff
+- # Custom validator script
+- node scripts/validate-frontmatter.mjs <path>
++ gbrain frontmatter validate <path> --json
+```
+
+For consumers that need the validator inside another script, import from
+gbrain's `markdown` export instead of duplicating logic:
+
+```ts
+import { parseMarkdown } from 'gbrain/markdown';
+
+const parsed = parseMarkdown(content, filePath, { validate: true, expectedSlug });
+for (const err of parsed.errors ?? []) {
+  // err.code: MISSING_OPEN | MISSING_CLOSE | YAML_PARSE | SLUG_MISMATCH |
+  //           NULL_BYTES | NESTED_QUOTES | EMPTY_FRONTMATTER
+}
+```
+
+### 2. Drop any references to `lib/brain-writer.mjs`
+
+If your fork's skills or scripts referenced an aspirational
+`lib/brain-writer.mjs` (it never shipped — the spec was in PR #392 and never
+landed), replace those references with the gbrain CLI. The `frontmatter-guard`
+skill lives at `skills/frontmatter-guard/SKILL.md` and points at
+`gbrain frontmatter validate` / `audit` / `install-hook`.
+
+### 3. Wire the doctor subcheck into your health pipeline
+
+`gbrain doctor` now reports `frontmatter_integrity` automatically. If your
+fork has a custom health pipeline (e.g. a daily Slack post about brain
+health), pull from `gbrain doctor --json` and surface the
+`frontmatter_integrity` row counts.
+
+### 4. (Optional) Install the pre-commit hook on brain repos
+
+For sources backed by git, the v0.22.4 install-hook helper drops a
+pre-commit script that blocks commits with malformed frontmatter:
+
+```bash
+gbrain frontmatter install-hook
+```
+
+Skip this if your brain isn't a git repo or if your downstream agent already
+enforces validation at write time. See `docs/integrations/pre-commit.md` for
+the full recipe.
+
+### 5. Migration ergonomics — read pending-host-work.jsonl
+
+After `gbrain apply-migrations --yes` runs the v0.22.4 audit, your agent
+should read `~/.gbrain/migrations/pending-host-work.jsonl` (filter to
+`migration === "0.22.4"`) and walk each entry's `command` field. Each entry
+points to a per-source `gbrain frontmatter validate <source_path> --fix`
+command — surface counts to the user, get explicit consent, then run.
+
+The migration is **audit-only**. It never mutates brain content during
+`apply-migrations`. Your agent runs the fix command with user consent.
+
+---
+
 ## Future versions
 
 When gbrain ships a new version, this doc will be updated with the diffs for that

docs/integrations/pre-commit.md

@@ -0,0 +1,105 @@
+# Pre-commit hook for brain repos (v0.22.4+)
+
+`gbrain frontmatter install-hook` installs a git pre-commit hook in your
+brain source's repo that runs `gbrain frontmatter validate` against staged
+`.md` and `.mdx` files. Malformed frontmatter blocks the commit. Bypass with
+`git commit --no-verify`.
+
+## What the hook catches
+
+The same seven validation classes the `frontmatter-guard` skill and
+`gbrain doctor`'s `frontmatter_integrity` subcheck report:
+
+| Code              | What it catches                                                     |
+|-------------------|---------------------------------------------------------------------|
+| `MISSING_OPEN`    | File doesn't start with `---`                                       |
+| `MISSING_CLOSE`   | No closing `---` before first heading                               |
+| `YAML_PARSE`      | YAML failed to parse (syntax or structure)                          |
+| `SLUG_MISMATCH`   | `slug:` in frontmatter doesn't match path-derived slug              |
+| `NULL_BYTES`      | Binary corruption (`\x00`) anywhere in the content                  |
+| `NESTED_QUOTES`   | `title: "outer "inner" outer"` shape that breaks YAML               |
+| `EMPTY_FRONTMATTER` | `---` ... `---` with nothing meaningful between                   |
+
+## Install
+
+For all registered sources that are git repos:
+
+```bash
+gbrain frontmatter install-hook
+```
+
+For one source:
+
+```bash
+gbrain frontmatter install-hook --source <id>
+```
+
+For force-overwrite of an existing pre-commit hook (writes a `.bak`):
+
+```bash
+gbrain frontmatter install-hook --force
+```
+
+The hook lands at `<source>/.githooks/pre-commit`. If `core.hooksPath` is
+unset, the install also runs `git config core.hooksPath .githooks` so the
+hook is picked up without manual git config.
+
+## Bypass
+
+Standard git escape hatch:
+
+```bash
+git commit --no-verify
+```
+
+This skips ALL pre-commit hooks. Use sparingly — the next time the user
+runs `gbrain doctor`, the issues will surface.
+
+## Uninstall
+
+```bash
+gbrain frontmatter install-hook --uninstall
+```
+
+If a `.bak` was saved during install, it's restored as the active hook.
+Otherwise the hook is removed cleanly.
+
+## Behavior on machines without gbrain installed
+
+The hook script checks for `gbrain` on `$PATH`. When missing, it prints a
+one-line warning to stderr and exits 0 — commits aren't blocked just because
+a developer hasn't installed gbrain locally. Once gbrain is installed, the
+hook resumes blocking malformed pages.
+
+## For downstream agent forks
+
+If your fork (Wintermute, Hermes, OpenClaw) wraps gbrain in a host repo
+that's not the brain repo itself, you may want a separate hook strategy:
+
+- **Brain repo IS the host repo** (gbrain skills + brain pages in one repo):
+  install via `gbrain frontmatter install-hook` as above.
+- **Brain repo is a separate registered source** (e.g. `~/brain` registered
+  as a source, host repo is `~/agent-fork`): install in the brain repo only;
+  agent-fork code doesn't need this hook.
+- **Brain repo is auto-generated** (e.g. by a sync daemon writing to a
+  bucket): skip the hook entirely; gate at the writer instead via
+  `import { writeBrainPage } from 'gbrain/brain-writer'` (planned in a
+  later release; currently the CLI is the surface).
+
+## How it fits into the broader frontmatter pipeline
+
+```
+agent writes a page         git commit                 doctor scan
+       ↓                          ↓                          ↓
+[source content]   →  [pre-commit hook validates]   →  [frontmatter_integrity check]
+       ↓                          ↓                          ↓
+  raw file on disk       blocks malformed commits     surfaces existing issues
+                                                             ↓
+                                                  `gbrain frontmatter validate
+                                                   <source-path> --fix`
+                                                   (writes .bak backups)
+```
+
+The hook is the write-time gate; doctor is the audit gate; the CLI is the
+fix tool. They share `parseMarkdown(..., {validate:true})` as the single
+source of truth for what counts as malformed.

llms-full.txt

@@ -104,11 +104,11 @@ strict behavior when unset.
 - `src/core/operations.ts` — Contract-first operation definitions (the foundation). Also exports upload validators: `validateUploadPath`, `validatePageSlug`, `validateFilename`. `OperationContext.remote` flags untrusted callers.
 - `src/core/engine.ts` — Pluggable engine interface (BrainEngine). `clampSearchLimit(limit, default, cap)` takes an explicit cap so per-operation caps can be tighter than `MAX_SEARCH_LIMIT`. Exports `LinkBatchInput` / `TimelineBatchInput` for the v0.12.1 bulk-insert API (`addLinksBatch` / `addTimelineEntriesBatch`). As of v0.13.1, `BrainEngine` has a `readonly kind: 'postgres' | 'pglite'` discriminator so migrations (`src/core/migrate.ts`) and other consumers can branch on engine without `instanceof` + dynamic imports.
 - `src/core/engine-factory.ts` — Engine factory with dynamic imports (`'pglite'` | `'postgres'`)
-- `src/core/pglite-engine.ts` — PGLite (embedded Postgres 17.5 via WASM) implementation, all 40 BrainEngine methods. `addLinksBatch` / `addTimelineEntriesBatch` use multi-row `unnest()` with manual `$N` placeholders. As of v0.13.1, `connect()` wraps `PGlite.create()` in a try/catch that emits an actionable error naming the macOS 26.3 WASM bug (#223) and pointing at `gbrain doctor`; the lock is released on failure so the next process can retry cleanly.
+- `src/core/pglite-engine.ts` — PGLite (embedded Postgres 17.5 via WASM) implementation, all 40 BrainEngine methods. `addLinksBatch` / `addTimelineEntriesBatch` use multi-row `unnest()` with manual `$N` placeholders. As of v0.13.1, `connect()` wraps `PGlite.create()` in a try/catch that emits an actionable error naming the macOS 26.3 WASM bug (#223) and pointing at `gbrain doctor`; the lock is released on failure so the next process can retry cleanly. v0.22.0: `searchKeyword` and `searchKeywordChunks` multiply `ts_rank` by the source-factor CASE expression at the chunk-grain level; `searchVector` becomes a two-stage CTE — inner CTE keeps `ORDER BY cc.embedding <=> vec` so HNSW stays usable, outer SELECT re-ranks by `raw_score * source_factor`. Inner LIMIT scales with offset to preserve pagination contract.
 - `src/core/pglite-schema.ts` — PGLite-specific DDL (pgvector, pg_trgm, triggers)
-- `src/core/postgres-engine.ts` — Postgres + pgvector implementation (Supabase / self-hosted). `addLinksBatch` / `addTimelineEntriesBatch` use `INSERT ... SELECT FROM unnest($1::text[], ...) JOIN pages ON CONFLICT DO NOTHING RETURNING 1` — 4-5 array params regardless of batch size, sidesteps the 65535-parameter cap. As of v0.12.3, `searchKeyword` / `searchVector` scope `statement_timeout` via `sql.begin` + `SET LOCAL` so the GUC dies with the transaction instead of leaking across the pooled postgres.js connection (contributed by @garagon). `getEmbeddingsByChunkIds` uses `tryParseEmbedding` so one corrupt row skips+warns instead of killing the query.
+- `src/core/postgres-engine.ts` — Postgres + pgvector implementation (Supabase / self-hosted). `addLinksBatch` / `addTimelineEntriesBatch` use `INSERT ... SELECT FROM unnest($1::text[], ...) JOIN pages ON CONFLICT DO NOTHING RETURNING 1` — 4-5 array params regardless of batch size, sidesteps the 65535-parameter cap. As of v0.12.3, `searchKeyword` / `searchVector` scope `statement_timeout` via `sql.begin` + `SET LOCAL` so the GUC dies with the transaction instead of leaking across the pooled postgres.js connection (contributed by @garagon). `getEmbeddingsByChunkIds` uses `tryParseEmbedding` so one corrupt row skips+warns instead of killing the query. v0.22.0: `searchKeyword`, `searchKeywordChunks`, and `searchVector` apply source-aware ranking by inlining the source-factor CASE and `NOT (col LIKE …)` hard-exclude clause from `src/core/search/sql-ranking.ts`. `searchVector` switches to a two-stage CTE (HNSW-safe inner ORDER BY, source-boost re-rank in the outer SELECT) and carries `p.source_id` through inner→outer for v0.18 multi-source callers. v0.22.1 (#406): `_savedConfig` retains the connect config; `reconnect()` tears down + recreates the pool from saved config (called by supervisor watchdog after 3 consecutive health-check failures). `executeRaw` is a single-statement passthrough — no per-call retry (D3 dropped that as unsound for non-idempotent statements; recovery is supervisor-driven). v0.22.1 (#363, contributed by @orendi84): `connect()` applies `resolveSessionTimeouts()` from `db.ts` as connection-time startup parameters (`statement_timeout`, `idle_in_transaction_session_timeout`) so orphan pgbouncer backends can't hold locks for hours. v0.22.1 (#409, contributed by @atrevino47): `countStaleChunks()` + `listStaleChunks()` server-side-filter on `embedding IS NULL` for `embed --stale`, eliminating ~76 MB/call client-side pull on a fully-embedded brain; `upsertChunks()` resets both `embedding` AND `embedded_at` to NULL when chunk_text changes without a new embedding (consistency).
 - `src/core/utils.ts` — Shared SQL utilities extracted from postgres-engine.ts. Exports `parseEmbedding(value)` (throws on unknown input, used by migration + ingest paths where data integrity matters) and as of v0.12.3 `tryParseEmbedding(value)` (returns `null` + warns once per process, used by search/rescore paths where availability matters more than strictness).
-- `src/core/db.ts` — Connection management, schema initialization
+- `src/core/db.ts` — Connection management, schema initialization. v0.22.1 (#363, contributed by @orendi84): `resolveSessionTimeouts()` returns `statement_timeout` + `idle_in_transaction_session_timeout` (defaults: 5min each, env-overridable via `GBRAIN_STATEMENT_TIMEOUT` / `GBRAIN_IDLE_TX_TIMEOUT` / `GBRAIN_CLIENT_CHECK_INTERVAL`). Both `connect()` (module singleton) and `PostgresEngine.connect()` (worker pool) consume the result via postgres.js's `connection` option, sending GUCs as startup parameters that survive PgBouncer transaction mode (unlike the prior `setSessionDefaults` post-pool SET, kept as a back-compat no-op shim).
 - `src/commands/migrate-engine.ts` — Bidirectional engine migration (`gbrain migrate --to supabase/pglite`)
 - `src/core/import-file.ts` — importFromFile + importFromContent (chunk + embed + tags)
 - `src/core/sync.ts` — Pure sync functions (manifest parsing, filtering, slug conversion)
@@ -119,9 +119,11 @@ strict behavior when unset.
 - `src/core/errors.ts` (v0.19.0) — `StructuredAgentError` + `buildError` + `serializeError`. Every new v0.19.0 agent-facing surface (code-def, code-refs, usage errors) uses this envelope; matches v0.17.0 `CycleReport.PhaseResult.error` shape.
 - `src/assets/wasm/` (v0.19.0) — 36 tree-sitter grammar WASMs + tree-sitter runtime. Committed to the repo so `bun --compile` embeds them deterministically via `import path from ... with { type: 'file' }`. The CI guard `scripts/check-wasm-embedded.sh` fails the build if the compiled binary ever silently falls through to recursive chunks.
 - `src/commands/code-def.ts` + `src/commands/code-refs.ts` (v0.19.0) — symbol definition + references lookup. Query `content_chunks.symbol_name` or chunk_text ILIKE with `page_kind='code'` filter. Auto-JSON when stdout is not a TTY (gh-CLI convention). Bypass the standard `searchKeyword` `DISTINCT ON (slug)` collapse so multiple call-sites from the same file surface.
-- `src/core/search/` — Hybrid search: vector + keyword + RRF + multi-query expansion + dedup
+- `src/core/search/` — Hybrid search: vector + keyword + RRF + multi-query expansion + dedup. As of v0.22.0, `searchKeyword` / `searchKeywordChunks` / `searchVector` apply source-aware ranking at the SQL layer (curated content like `originals/`, `concepts/`, `writing/` outranks bulk content like `wintermute/chat/`, `daily/`, `media/x/`). `searchVector` uses a two-stage CTE so source-boost re-ranking doesn't kill the HNSW index. Hard-exclude prefixes (`test/`, `archive/`, `attachments/`, `.raw/` by default) filter at retrieval, not post-rank. Both gates honor `detail !== 'high'` so temporal queries surface chat pages normally.
 - `src/core/search/intent.ts` — Query intent classifier (entity/temporal/event/general → auto-selects detail level)
 - `src/core/search/eval.ts` — Retrieval eval harness: P@k, R@k, MRR, nDCG@k metrics + runEval() orchestrator
+- `src/core/search/source-boost.ts` (v0.22.0) — Source-type boost map keyed by slug prefix. `DEFAULT_SOURCE_BOOSTS` (originals/ 1.5, concepts/ 1.3, writing/ 1.4, people/companies/deals/ 1.2, daily/ 0.8, media/x/ 0.7, wintermute/chat/ 0.5) and `DEFAULT_HARD_EXCLUDES` (test/, archive/, attachments/, .raw/). `parseSourceBoostEnv` / `parseHardExcludesEnv` parse comma-separated `prefix:factor` pairs from `GBRAIN_SOURCE_BOOST` / `GBRAIN_SEARCH_EXCLUDE` env vars. `resolveBoostMap` and `resolveHardExcludes` merge defaults + env + caller `SearchOpts.exclude_slug_prefixes`/`include_slug_prefixes`.
+- `src/core/search/sql-ranking.ts` (v0.22.0) — Pure SQL string builders. `buildSourceFactorCase(slugColumn, boostMap, detail)` emits a CASE expression with longest-prefix-match wins (returns literal `'1.0'` when `detail === 'high'` for temporal-bypass parity with COMPILED_TRUTH_BOOST). `buildHardExcludeClause(slugColumn, prefixes)` emits `NOT (col LIKE 'p1%' OR col LIKE 'p2%')` — OR-chain wrapped in NOT, NOT `NOT LIKE ALL/ANY` (those quantifiers don't express set-exclusion). LIKE meta-character escape covers all three of `%`, `_`, AND `\` (backslash matters because it's Postgres LIKE's default escape char). Single-quote doubling on SQL string literals so injection-style inputs are inert text.
 - `src/commands/eval.ts` — `gbrain eval` command: single-run table + A/B config comparison
 - `src/core/embedding.ts` — OpenAI text-embedding-3-large, batch, retry, backoff
 - `src/core/check-resolvable.ts` — Resolver validation: reachability, MECE overlap, DRY checks, structured fix objects. v0.14.1: `CROSS_CUTTING_PATTERNS.conventions` is an array (notability gate accepts both `conventions/quality.md` and `_brain-filing-rules.md`). New `extractDelegationTargets()` parses `> **Convention:**`, `> **Filing rule:**`, and inline backtick references. DRY suppression is proximity-based via `DRY_PROXIMITY_LINES = 40`.
@@ -140,12 +142,14 @@ strict behavior when unset.
 - `src/core/transcription.ts` — Audio transcription: Groq Whisper (default), OpenAI fallback, ffmpeg segmentation for >25MB
 - `src/core/enrichment-service.ts` — Global enrichment service: entity slug generation, tier auto-escalation, batch throttling
 - `src/core/data-research.ts` — Recipe validation, field extraction (MRR/ARR regex), dedup, tracker parsing, HTML stripping
-- `src/commands/extract.ts` — `gbrain extract links|timeline|all [--source fs|db]`: batch link/timeline extraction. fs walks markdown files, db walks pages from the engine (mutation-immune snapshot iteration; use this for live brains with no local checkout). As of v0.12.1 there is no in-memory dedup pre-load — candidates are buffered 100 at a time and flushed via `addLinksBatch` / `addTimelineEntriesBatch`; `ON CONFLICT DO NOTHING` enforces uniqueness at the DB layer, and the `created` counter returns real rows inserted (truthful on re-runs).
+- `src/commands/embed.ts` — `gbrain embed [--stale|--all] [--slugs ...]`. v0.22.1 (#409, contributed by @atrevino47): `--stale` path now starts with `engine.countStaleChunks()` (single SELECT count(*) WHERE embedding IS NULL, ~50 bytes wire). On a fully-embedded brain that's a 1-line short-circuit — no further reads. When stale chunks exist, `engine.listStaleChunks()` returns just the chunks needing embeddings (slug + chunk_index + chunk_text + metadata, no `vector(1536)` payload). Caller groups by slug, embeds via OpenAI, re-upserts via `upsertChunks`. Replaces the prior page-walk that pulled every chunk's embedding column over the wire and discarded most.
+- `src/commands/extract.ts` — `gbrain extract links|timeline|all [--source fs|db]`: batch link/timeline extraction. fs walks markdown files, db walks pages from the engine (mutation-immune snapshot iteration; use this for live brains with no local checkout). As of v0.12.1 there is no in-memory dedup pre-load — candidates are buffered 100 at a time and flushed via `addLinksBatch` / `addTimelineEntriesBatch`; `ON CONFLICT DO NOTHING` enforces uniqueness at the DB layer, and the `created` counter returns real rows inserted (truthful on re-runs). v0.22.1 (#417): `ExtractOpts.slugs?: string[]` enables incremental extract — when set, `extractForSlugs()` reads ONLY those slugs' files (single combined links+timeline pass) instead of the full directory walk. CLI `gbrain extract` keeps full-walk behavior; the cycle path threads sync's `pagesAffected` through. `walkMarkdownFiles(brainDir)` still runs at line 455 to build `allSlugs` for link resolution — see `TODOS.md` for replacing it with `engine.getAllSlugs()`.
 - `src/commands/graph-query.ts` — `gbrain graph-query <slug> [--type T] [--depth N] [--direction in|out|both]`: typed-edge relationship traversal (renders indented tree)
 - `src/core/link-extraction.ts` — shared library for the v0.12.0 graph layer. extractEntityRefs (canonical, replaces backlinks.ts duplicate) matches both `[Name](people/slug)` markdown links and Obsidian `[[people/slug|Name]]` wikilinks as of v0.12.3. extractPageLinks, inferLinkType heuristics (attended/works_at/invested_in/founded/advises/source/mentions), parseTimelineEntries, isAutoLinkEnabled config helper. `DIR_PATTERN` covers `people`, `companies`, `deals`, `topics`, `concepts`, `projects`, `entities`, `tech`, `finance`, `personal`, `openclaw`. Used by extract.ts, operations.ts auto-link post-hook, and backlinks.ts.
 - `src/core/minions/` — Minions job queue: BullMQ-inspired, Postgres-native (queue, worker, backoff, types, protected-names, quiet-hours, stagger, handlers/shell).
 - `src/core/minions/queue.ts` — MinionQueue class (submit, claim, complete, fail, stall detection, parent-child, depth/child-cap, per-job timeouts, cascade-kill, attachments, idempotency keys, child_done inbox, removeOnComplete/Fail). `add()` takes a 4th `trusted` arg (separate from `opts` to prevent spread leakage); protected names in `PROTECTED_JOB_NAMES` require `{allowProtectedSubmit: true}` and the check runs trim-normalized (whitespace-bypass safe). v0.14.1 #219: `add()` plumbs `max_stalled` through with a `[1, 100]` clamp; omitted values let the schema DEFAULT (5) kick in. v0.19.0: `handleWallClockTimeouts(lockDurationMs)` is Layer 3 kill shot for jobs where `FOR UPDATE SKIP LOCKED` stall detection and the timeout sweep both fail to evict (wedged worker holding a row lock via a pending transaction). v0.19.1: `maxWaiting` coalesce path now uses `pg_advisory_xact_lock` keyed on `(name, queue)` to serialize concurrent submits for the same key, and filters on `queue` in addition to `name` so cross-queue same-name jobs don't suppress each other.
-- `src/core/minions/worker.ts` — MinionWorker class (handler registry, lock renewal, graceful shutdown, timeout safety net). v0.14.0 abort-path fix: aborted jobs now call `failJob` with reason (`timeout`/`cancel`/`lock-lost`/`shutdown`) instead of returning silently. `shutdownAbort` (instance field) fires on process SIGTERM/SIGINT and propagates to `ctx.shutdownSignal` — shell handler listens to it; non-shell handlers don't.
+- `src/core/minions/worker.ts` — MinionWorker class (handler registry, lock renewal, graceful shutdown, timeout safety net). v0.14.0 abort-path fix: aborted jobs now call `failJob` with reason (`timeout`/`cancel`/`lock-lost`/`shutdown`) instead of returning silently. `shutdownAbort` (instance field) fires on process SIGTERM/SIGINT and propagates to `ctx.shutdownSignal` — shell handler listens to it; non-shell handlers don't. v0.22.1 (#403): per-job timeout fires `abort.abort(new Error('timeout'))` then a 30-second grace-then-evict safety net force-evicts the job from `inFlight` and marks it dead in DB if the handler ignores the abort signal — frees the slot even when a handler wedges (the 98-waiting-0-active prod incident driver).
+- `src/core/minions/supervisor.ts` — MinionSupervisor process manager. Spawns `gbrain jobs work` as a child, restarts on crash with exponential backoff, periodic health check. v0.22.1 (#406): `consecutiveHealthFailures` counter; on 3 consecutive failures emits `health_warn` with `reason: 'db_connection_degraded'` and calls `engine.reconnect()` to swap in a fresh pool, then resets the counter. Worker exit classifier emits `likely_cause` field on `worker_exited` events: `oom_or_external_kill` (SIGKILL), `graceful_shutdown` (SIGTERM), `runtime_error` (code 1), `clean_exit` (code 0), `unknown`.
 - `src/core/minions/types.ts` — `MinionJobInput` + `MinionJobStatus` + handler context types. `MinionJobInput.max_stalled` (new in v0.14.1) is optional; omitted values let the schema DEFAULT (5) kick in, provided values are clamped to `[1, 100]`.
 - `src/core/minions/protected-names.ts` — side-effect-free constant module exporting `PROTECTED_JOB_NAMES` + `isProtectedJobName()`. Kept pure so queue core can import without loading handler modules.
 - `src/core/minions/handlers/shell.ts` — `shell` job handler. Spawns `/bin/sh -c cmd` (absolute path, PATH-override-safe) or `argv[0] argv[1..]` (no shell). Env allowlist: `PATH, HOME, USER, LANG, TZ, NODE_ENV` + caller `env:` overrides. UTF-8-safe stdout/stderr tail via `string_decoder.StringDecoder`. Abort (either `ctx.signal` or `ctx.shutdownSignal`) fires SIGTERM → 5s grace → SIGKILL on child. Requires `GBRAIN_ALLOW_SHELL_JOBS=1` on worker (gated by `registerBuiltinHandlers`).
@@ -176,7 +180,7 @@ strict behavior when unset.
 - `src/core/migrate.ts` — schema-migration runner. Owns the `MIGRATIONS` array (source of truth for schema DDL). v0.14.2 extended the `Migration` interface with `sqlFor?: { postgres?, pglite? }` (engine-specific SQL overrides `sql`) and `transaction?: boolean` (set to false for `CREATE INDEX CONCURRENTLY`, which Postgres refuses inside a transaction; ignored on PGLite since it has no concurrent writers). Migration v14 (fix wave) uses a handler branching on `engine.kind` to run CONCURRENTLY on Postgres (with a pre-drop of any invalid remnant via `pg_index.indisvalid`) and plain `CREATE INDEX` on PGLite. v15 bumps `minion_jobs.max_stalled` default 1→5 and backfills existing non-terminal rows.
 - `src/core/progress.ts` — Shared bulk-action progress reporter. Writes to stderr. Modes: `auto` (TTY: `\r`-rewriting; non-TTY: plain lines), `human`, `json` (JSONL), `quiet`. Rate-gated by `minIntervalMs` and `minItems`. `startHeartbeat(reporter, note)` helper for single long queries. `child()` composes phase paths. Singleton SIGINT/SIGTERM coordinator emits `abort` events for every live phase. EPIPE defense on both sync throws and stream `'error'` events. Zero dependencies. Introduced in v0.15.2.
 - `src/core/cli-options.ts` — Global CLI flag parser. `parseGlobalFlags(argv)` returns `{cliOpts, rest}` with `--quiet` / `--progress-json` / `--progress-interval=<ms>` stripped. `getCliOptions()` / `setCliOptions()` expose a module-level singleton so commands reach the resolved flags without parameter threading. `cliOptsToProgressOptions()` maps to reporter options. `childGlobalFlags()` returns the flag suffix to append to `execSync('gbrain ...')` calls in migration orchestrators. `OperationContext.cliOpts` extends shared-op dispatch for MCP callers.
-- `src/core/cycle.ts` — v0.17 brain maintenance cycle primitive. `runCycle(engine: BrainEngine | null, opts: CycleOpts): Promise<CycleReport>` composes 6 phases in semantically-driven order (lint → backlinks → sync → extract → embed → orphans). Three callers: `gbrain dream` CLI, `gbrain autopilot` daemon's inline path, and the Minions `autopilot-cycle` handler (`src/commands/jobs.ts`). One source of truth for what the brain does overnight. Coordination via `gbrain_cycle_locks` DB table (TTL-based; works through PgBouncer transaction pooling, unlike session-scoped `pg_try_advisory_lock`) + `~/.gbrain/cycle.lock` file lock with PID-liveness for PGLite / engine=null mode. `CycleReport.schema_version: "1"` is the stable agent-consumable shape. `PhaseResult.error: { class, code, message, hint?, docs_url? }` is Stripe-API-tier structured failure info. `yieldBetweenPhases` hook awaited between every phase — Minions handler uses this to renew its job lock and prevent v0.14 stall-death regression. Engine nullable: filesystem phases (lint, backlinks) run without DB; DB phases skip with `status: "skipped", reason: "no_database"`. Lock-skip: read-only phase selections (`--phase orphans`) bypass the cycle lock.
+- `src/core/cycle.ts` — v0.17 brain maintenance cycle primitive. `runCycle(engine: BrainEngine | null, opts: CycleOpts): Promise<CycleReport>` composes 6 phases in semantically-driven order (lint → backlinks → sync → extract → embed → orphans). Three callers: `gbrain dream` CLI, `gbrain autopilot` daemon's inline path, and the Minions `autopilot-cycle` handler (`src/commands/jobs.ts`). One source of truth for what the brain does overnight. Coordination via `gbrain_cycle_locks` DB table (TTL-based; works through PgBouncer transaction pooling, unlike session-scoped `pg_try_advisory_lock`) + `~/.gbrain/cycle.lock` file lock with PID-liveness for PGLite / engine=null mode. `CycleReport.schema_version: "1"` is the stable agent-consumable shape. `PhaseResult.error: { class, code, message, hint?, docs_url? }` is Stripe-API-tier structured failure info. `yieldBetweenPhases` hook awaited between every phase — Minions handler uses this to renew its job lock and prevent v0.14 stall-death regression. Engine nullable: filesystem phases (lint, backlinks) run without DB; DB phases skip with `status: "skipped", reason: "no_database"`. Lock-skip: read-only phase selections (`--phase orphans`) bypass the cycle lock. v0.22.1 (#403): `CycleOpts.signal?: AbortSignal` propagates the worker's abort signal; `checkAborted()` fires between every phase and throws if the signal is aborted (cooperative — can't interrupt a phase mid-execution). v0.22.1 (#417): `runPhaseSync` returns `pagesAffected` via `SyncPhaseResult`; `runCycle` captures it and threads to `runPhaseExtract` as the 4th arg, enabling incremental extract on the cycle path. v0.22.1 (Codex F2): `runPhaseSync` takes `willRunExtractPhase: boolean` and sets `noExtract: phases.includes('extract')` so `gbrain dream --phase sync` doesn't silently lose extraction. v0.22.5 (#475): new `resolveSourceForDir(engine, brainDir)` helper queries `SELECT id FROM sources WHERE local_path = $1 LIMIT 1`; `runPhaseSync` threads result as `sourceId` to `performSync()` so sync reads the per-source `sources.last_commit` anchor instead of the drift-prone global `config.sync.last_commit` key. Bare try/catch lets pre-v0.18 brains fall through to the global key. Closes the prod hang where every autopilot cycle ran a 30-min full reimport because the global anchor commit had been GC'd from git history.
 - `src/commands/dream.ts` — v0.17 `gbrain dream` CLI. ~80-line thin alias over `runCycle`. brainDir resolution requires explicit `--dir` OR `sync.repo_path` config (no more walk-up-cwd-for-.git footgun). Flags: `--dry-run`, `--json`, `--phase <name>`, `--pull`, `--dir <path>`. Exit code 1 on status=failed (partial/warn not fatal — don't page on warnings).
 - `scripts/check-progress-to-stdout.sh` — CI guard against regressing to `\r`-on-stdout progress. Wired into `bun run test` via `scripts/check-progress-to-stdout.sh && bun test` in package.json.
 - `docs/progress-events.md` — Canonical JSON event schema reference. Stable from v0.15.2, additive only.
@@ -312,6 +316,7 @@ parity), `test/cli.test.ts` (CLI structure), `test/config.test.ts` (config redac
 `test/skills-conformance.test.ts` (skill frontmatter + required sections validation),
 `test/resolver.test.ts` (RESOLVER.md coverage, routing validation + v0.20.4 round-trip: every quoted RESOLVER.md trigger must match a frontmatter `triggers:` entry in the target skill, and every `name="<word>"` reference in any SKILL.md must resolve to a declared op in `src/core/operations.ts` or a Minions handler in `PROTECTED_JOB_NAMES`),
 `test/search.test.ts` (RRF normalization, compiled truth boost, cosine similarity, dedup key),
+`test/sql-ranking.test.ts` (v0.22.0 source-boost helpers: 39 cases covering longest-prefix-match in SQL CASE, detail=high temporal-bypass, three-meta-char LIKE escape (%, _, \\), single-quote SQL-literal doubling, env override parsing for GBRAIN_SOURCE_BOOST + GBRAIN_SEARCH_EXCLUDE, resolveBoostMap / resolveHardExcludes merge semantics),
 `test/dedup.test.ts` (source-aware dedup, compiled truth guarantee, layer interactions),
 `test/intent.test.ts` (query intent classification: entity/temporal/event/general),
 `test/eval.test.ts` (retrieval metrics: precisionAtK, recallAtK, mrr, ndcgAtK, parseQrels),
@@ -360,6 +365,9 @@ E2E tests (`test/e2e/`): Run against real Postgres+pgvector. Require `DATABASE_U
 - `test/e2e/upgrade.test.ts` runs check-update E2E against real GitHub API (network required)
 - `test/e2e/minions-shell-pglite.test.ts` (v0.20.4) exercises the PGLite `--follow` inline shell-job path (in-memory, no `DATABASE_URL` required) — the path the consolidated minion-orchestrator skill documents for dev use
 - `test/e2e/openclaw-reference-compat.test.ts` (v0.19) — exercises `check-resolvable` + `skillpack install` against a minimal AGENTS.md workspace fixture (`test/fixtures/openclaw-reference-minimal/`), regression guard for the 107-skill OpenClaw deployment shape
+- `test/e2e/search-swamp.test.ts` (v0.22.0) — reproduces the headline source-swamp case. Seeds a curated `originals/talks/article-outline-fat-code` page against two `wintermute/chat/` pages stuffed with the same multi-word phrase. Asserts the article wins keyword AND vector ranking, that `detail=high` lets the chat swamp re-surface (temporal-query workflow preserved), and that `source_id` passes through the two-stage CTE intact. PGLite in-memory.
+- `test/e2e/search-exclude.test.ts` (v0.22.0) — verifies `test/` + `archive/` pages are hidden by default, that `include_slug_prefixes` opts back in, and that caller-supplied `exclude_slug_prefixes` adds to defaults. Both keyword and vector search paths covered.
+- `test/e2e/engine-parity.test.ts` (v0.22.0) — Postgres ↔ PGLite top-result and result-set parity for `searchKeyword` + `searchVector`. Codex flagged that Postgres ranks pages then picks best chunk while PGLite returns chunks directly — without parity coverage the source-boost fix could pass on PGLite and fail on Postgres. Skips gracefully when `DATABASE_URL` is unset.
 - Tier 2 (`skills.test.ts`) requires OpenClaw + API keys, runs nightly in CI
 - If `.env.testing` doesn't exist in this directory, check sibling worktrees for one:
   `find ../  -maxdepth 2 -name .env.testing -print -quit` and copy it here if found.
@@ -474,6 +482,59 @@ in bulk paths, the CI guard will fail the build.
 
 `bun build --compile --outfile bin/gbrain src/cli.ts`
 
+## Version locations (single source of truth: `VERSION` file)
+
+Every release advances the version in **five files at once**. Keep these in
+sync. `/ship` enforces this via Step 12's idempotency check (VERSION vs
+package.json drift), but the canonical list lives here so future runs and
+the auto-update agent know where to look.
+
+**Required (every release must update all five):**
+
+| File | What lives there | Format |
+|---|---|---|
+| `VERSION` | The single source of truth. Read first by `/ship`, the binary, and CI version-gate. | Bare 4-digit string `MAJOR.MINOR.PATCH.MICRO` (e.g. `0.22.1`), no leading `v`, no trailing newline-sensitivity issues. |
+| `package.json` | Bun/npm package version. `gbrain --version` reads it via the compiled binary's bundled package metadata. CI version-gate cross-checks this against `VERSION` and fails if they drift. | `"version": "0.22.1"` |
+| `CHANGELOG.md` | Top entry header `## [0.22.1] - YYYY-MM-DD` plus the "To take advantage of v0.22.1" block. | Standard Keep-a-Changelog header. |
+| `TODOS.md` | Any TODO entries that mention "follow-up from vX.Y.Z" use the version of the release that filed them. Update only when filing NEW follow-up TODOs. | Inline `vX.Y.Z` references in TODO bodies. |
+| `CLAUDE.md` | The Key Files section's per-file annotations carry `vX.Y.Z (#NNN)` tags noting which release introduced a behavior. Update whenever a wave's annotations get folded in. | Inline `vX.Y.Z (#NNN, contributed by @user)` references. |
+
+**Auto-derived (no manual edit; refreshed by their own commands):**
+
+- `bun.lock` — root-package version is auto-pinned from `package.json`. After
+  bumping `package.json`, run `bun install` to refresh the lockfile.
+- `llms-full.txt` / `llms.txt` — auto-generated documentation bundles. After
+  any release ship that touches the Key Files annotations in `CLAUDE.md`,
+  run `bun run build:llms` to regenerate. The bundles do not contain a
+  version pin per se; they reflect the current state of the docs they index.
+
+**Historical (DO NOT bump on release):**
+
+- `skills/migrations/v0.21.0.md` — migration files use the version they
+  shipped FROM as their filename. v0.21.0's migration always says v0.21.0.
+- `src/commands/migrations/v0_21_0.ts` — same: migration code references
+  the schema version it migrates to.
+- `test/migrations-v0_21_0.test.ts`, `test/migration-orchestrator-v0_21_0.test.ts`,
+  `test/migrate.test.ts` — migration tests reference historical migration
+  versions; these are correct as-is and should not move.
+- `src/core/db.ts`, `src/core/migrate.ts`, `src/core/import-file.ts`,
+  `src/commands/reindex-code.ts` — code comments cite the release that
+  introduced a feature. Once written, these are historical record.
+- `README.md` — references the latest published feature names by version
+  (e.g. "v0.21.0 Code Cathedral"); update only when the README's marketing
+  copy is intentionally being refreshed, NOT on every micro/patch bump.
+
+**The /ship workflow's version idempotency check:** Step 12 reads
+`VERSION` and `package.json`, classifies as FRESH / ALREADY_BUMPED /
+DRIFT_STALE_PKG / DRIFT_UNEXPECTED, and refuses to proceed on
+DRIFT_UNEXPECTED. This is why the two must move together.
+
+**The CI version-gate** rejects pushes where `VERSION` and
+`package.json` disagree, OR where `VERSION` is not strictly greater
+than master's VERSION. If a queue collision claims your version on
+master before yours lands, /ship's queue-aware allocator (Step 12)
+will detect drift and re-bump on the next run.
+
 ## Pre-ship requirements
 
 Before shipping (/ship) or reviewing (/review), always run the full test suite:
@@ -1109,13 +1170,15 @@ This is the dispatcher. Skills are the implementation. **Read the skill file bef
 
 | Trigger | Skill |
 |---------|-------|
-| "What do we know about", "tell me about", "search for" | `skills/query/SKILL.md` |
+| "What do we know about", "tell me about", "search for", "who is", "background on", "notes on" | `skills/query/SKILL.md` |
 | "Who knows who", "relationship between", "connections", "graph query" | `skills/query/SKILL.md` (use graph-query) |
 | Creating/enriching a person or company page | `skills/enrich/SKILL.md` |
 | Where does a new file go? Filing rules | `skills/repo-architecture/SKILL.md` |
 | Fix broken citations in brain pages | `skills/citation-fixer/SKILL.md` |
+| "citation audit", "check citations", "fix citations" | `skills/citation-fixer/SKILL.md` (focused fix). For broader brain health, chain into `skills/maintain/SKILL.md` |
 | "Research", "track", "extract from email", "investor updates", "donations" | `skills/data-research/SKILL.md` |
 | Share a brain page as a link | `skills/publish/SKILL.md` |
+| "validate frontmatter", "check frontmatter", "fix frontmatter", "frontmatter audit", "brain lint" | `skills/frontmatter-guard/SKILL.md` |
 
 ## Content & media ingestion
 
@@ -1710,6 +1773,8 @@ Question
   │    ├─ Multi-query expansion (Haiku rephrases the question 3 ways)
   │    ├─ Vector search (HNSW cosine over OpenAI embeddings)
   │    ├─ Keyword search (Postgres tsvector + websearch_to_tsquery)
+  │    ├─ Source-aware ranking (curated dirs outrank chat/daily swamp at SQL layer)
+  │    ├─ Hard-exclude (test/ archive/ attachments/ .raw/ filtered before retrieval)
   │    ├─ Reciprocal Rank Fusion (score = sum 1/(60+rank) across both)
   │    ├─ Cosine re-scoring (re-rank chunks against actual query embedding)
   │    ├─ Compiled-truth boost (assessments outrank timeline noise)
@@ -5170,6 +5235,75 @@ in depth, not the primary boundary.
 
 ---
 
+## v0.22.4 — frontmatter-guard adoption
+
+### 1. Stop hand-rolling frontmatter validators
+
+If your fork has scripts that call `js-yaml` directly to validate brain page
+frontmatter, replace them with `gbrain frontmatter validate` calls. The CLI
+covers the seven canonical error classes and ships a `--json` envelope that's
+stable across releases.
+
+```diff
+- # Custom validator script
+- node scripts/validate-frontmatter.mjs <path>
++ gbrain frontmatter validate <path> --json
+```
+
+For consumers that need the validator inside another script, import from
+gbrain's `markdown` export instead of duplicating logic:
+
+```ts
+import { parseMarkdown } from 'gbrain/markdown';
+
+const parsed = parseMarkdown(content, filePath, { validate: true, expectedSlug });
+for (const err of parsed.errors ?? []) {
+  // err.code: MISSING_OPEN | MISSING_CLOSE | YAML_PARSE | SLUG_MISMATCH |
+  //           NULL_BYTES | NESTED_QUOTES | EMPTY_FRONTMATTER
+}
+```
+
+### 2. Drop any references to `lib/brain-writer.mjs`
+
+If your fork's skills or scripts referenced an aspirational
+`lib/brain-writer.mjs` (it never shipped — the spec was in PR #392 and never
+landed), replace those references with the gbrain CLI. The `frontmatter-guard`
+skill lives at `skills/frontmatter-guard/SKILL.md` and points at
+`gbrain frontmatter validate` / `audit` / `install-hook`.
+
+### 3. Wire the doctor subcheck into your health pipeline
+
+`gbrain doctor` now reports `frontmatter_integrity` automatically. If your
+fork has a custom health pipeline (e.g. a daily Slack post about brain
+health), pull from `gbrain doctor --json` and surface the
+`frontmatter_integrity` row counts.
+
+### 4. (Optional) Install the pre-commit hook on brain repos
+
+For sources backed by git, the v0.22.4 install-hook helper drops a
+pre-commit script that blocks commits with malformed frontmatter:
+
+```bash
+gbrain frontmatter install-hook
+```
+
+Skip this if your brain isn't a git repo or if your downstream agent already
+enforces validation at write time. See `docs/integrations/pre-commit.md` for
+the full recipe.
+
+### 5. Migration ergonomics — read pending-host-work.jsonl
+
+After `gbrain apply-migrations --yes` runs the v0.22.4 audit, your agent
+should read `~/.gbrain/migrations/pending-host-work.jsonl` (filter to
+`migration === "0.22.4"`) and walk each entry's `command` field. Each entry
+points to a per-source `gbrain frontmatter validate <source_path> --fix`
+command — surface counts to the user, get explicit consent, then run.
+
+The migration is **audit-only**. It never mutates brain content during
+`apply-migrations`. Your agent runs the fix command with user consent.
+
+---
+
 ## Future versions
 
 When gbrain ships a new version, this doc will be updated with the diffs for that

package.json

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

scripts/run-e2e.sh

@@ -15,6 +15,11 @@
 # the natural per-file test time of 5-10s.
 #
 # Exits non-zero on the first failing file so CI fails fast.
+#
+# `--timeout=60000` matches the unit test suite. Bun's default is 5s,
+# which is too tight for setupDB's TRUNCATE CASCADE on ~30 tables on
+# CI runners under load (one CI flake observed on PR #475 hitting
+# exactly 5000.09ms in the Tags beforeAll).
 
 set -euo pipefail
 
@@ -30,7 +35,7 @@ for f in test/e2e/*.test.ts; do
   name=$(basename "$f")
   echo ""
   echo "=== $name ==="
-  if output=$(bun test "$f" 2>&1); then
+  if output=$(bun test --timeout=60000 "$f" 2>&1); then
     pass_files=$((pass_files + 1))
     # Extract pass/fail counts from bun's summary (e.g., "123 pass")
     p=$(echo "$output" | grep -oE '[0-9]+ pass' | tail -1 | grep -oE '[0-9]+' || echo 0)

skills/RESOLVER.md

@@ -13,13 +13,15 @@ This is the dispatcher. Skills are the implementation. **Read the skill file bef
 
 | Trigger | Skill |
 |---------|-------|
-| "What do we know about", "tell me about", "search for" | `skills/query/SKILL.md` |
+| "What do we know about", "tell me about", "search for", "who is", "background on", "notes on" | `skills/query/SKILL.md` |
 | "Who knows who", "relationship between", "connections", "graph query" | `skills/query/SKILL.md` (use graph-query) |
 | Creating/enriching a person or company page | `skills/enrich/SKILL.md` |
 | Where does a new file go? Filing rules | `skills/repo-architecture/SKILL.md` |
 | Fix broken citations in brain pages | `skills/citation-fixer/SKILL.md` |
+| "citation audit", "check citations", "fix citations" | `skills/citation-fixer/SKILL.md` (focused fix). For broader brain health, chain into `skills/maintain/SKILL.md` |
 | "Research", "track", "extract from email", "investor updates", "donations" | `skills/data-research/SKILL.md` |
 | Share a brain page as a link | `skills/publish/SKILL.md` |
+| "validate frontmatter", "check frontmatter", "fix frontmatter", "frontmatter audit", "brain lint" | `skills/frontmatter-guard/SKILL.md` |
 
 ## Content & media ingestion
 

skills/citation-fixer/routing-eval.jsonl

@@ -1,7 +1,7 @@
 // Routing eval fixtures for skills/citation-fixer. Check 5 (W2, v0.17).
 // Layer A (structural) requires intents to contain trigger words from
 // the resolver. Paraphrase the trigger framing, not its meaning.
-{"intent": "please fix broken citations across the latest batch of pages", "expected_skill": "citation-fixer"}
-{"intent": "I think we need to fix broken citations in these brain pages", "expected_skill": "citation-fixer"}
+{"intent": "please fix citations in the latest batch of brain pages", "expected_skill": "citation-fixer"}
+{"intent": "I need to fix citations across these pages", "expected_skill": "citation-fixer"}
 // Negative case: something that sounds similar but should NOT route here.
 {"intent": "What does this book say about mentorship", "expected_skill": null, "ambiguous_with": []}

skills/enrich/SKILL.md

@@ -55,18 +55,7 @@ they building, what makes them tick, where are they headed.
 
 ## Citation Requirements (MANDATORY)
 
-Every fact must carry an inline `[Source: ...]` citation.
-
-Three formats:
-- **Direct attribution:** `[Source: User, {context}, YYYY-MM-DD]`
-- **API/external:** `[Source: {provider} enrichment, YYYY-MM-DD]`
-- **Synthesis:** `[Source: compiled from {list of sources}]`
-
-Source precedence (highest to lowest):
-1. User's direct statements
-2. Compiled truth (pre-existing brain synthesis)
-3. Timeline entries (raw evidence)
-4. External sources (API enrichment, web search)
+> **Convention:** see `skills/conventions/quality.md` for citation formats and source precedence.
 
 When sources conflict, note the contradiction with both citations.
 

skills/frontmatter-guard/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: frontmatter-guard
+version: 1.0.0
+description: |
+  Validate and auto-repair YAML frontmatter on brain pages. Catches malformed
+  pages before they enter the brain (missing closing ---, nested quotes, slug
+  mismatches, null bytes, empty frontmatter, YAML parse failures). Wraps the
+  `gbrain frontmatter` CLI for agent-driven workflows.
+triggers:
+  - "validate frontmatter"
+  - "check frontmatter"
+  - "fix frontmatter"
+  - "frontmatter audit"
+  - "brain lint"
+tools:
+  - exec
+mutating: true
+---
+
+# Frontmatter Guard Skill
+
+> **Convention:** see `skills/conventions/quality.md` for citation rules; this skill is structural validation, not citation auditing.
+
+## Contract
+
+This skill guarantees:
+- Every brain page is scanned against the seven canonical frontmatter validation classes
+- Mechanical errors (nested quotes, missing closing `---`, null bytes, slug mismatch) are auto-repairable on demand with `.bak` backups
+- Validation logic is shared with `gbrain doctor`'s `frontmatter_integrity` subcheck — single source of truth
+- Reports per source (gbrain is multi-source since v0.18.0); never silently audits the wrong root
+
+## Why This Exists
+
+Brain pages pile up over months. Agents write them with malformed frontmatter:
+- Missing closing `---` (entity detector bugs)
+- Unstructured YAML in meeting pages (ingestion bugs)
+- Slug mismatches (path renames not propagated)
+- Null bytes (binary corruption from copy-paste accidents)
+- Nested double quotes in titles (`title: "Phil "Nick" Last"`)
+
+Without a guard, these accumulate silently until `gbrain sync` chokes or search returns garbage. The guard makes the failure visible at audit time and trivially fixable.
+
+## Validation classes
+
+| Code | Meaning | Auto-fixable? |
+|------|---------|---------------|
+| `MISSING_OPEN` | File doesn't start with `---` | No (needs human) |
+| `MISSING_CLOSE` | No closing `---` before first heading | Yes |
+| `YAML_PARSE` | YAML failed to parse | Sometimes (depends on cause) |
+| `SLUG_MISMATCH` | Frontmatter `slug:` differs from path-derived slug | Yes (removes the field) |
+| `NULL_BYTES` | Binary corruption (`\x00`) | Yes |
+| `NESTED_QUOTES` | `title: "outer "inner" outer"` shape | Yes |
+| `EMPTY_FRONTMATTER` | Open + close present but nothing between | No (needs human) |
+
+## Phases
+
+### Phase 1: Audit
+
+Run a read-only scan across all registered sources (or one with `--source <id>`).
+
+```bash
+gbrain frontmatter audit --json
+```
+
+Reports:
+- Per-source counts grouped by error code
+- Sample of up to 20 affected pages per source
+- Total count
+- Scan timestamp
+
+Output is JSON; agents parse `errors_by_code` and `per_source` to decide next steps.
+
+### Phase 2: Validate one path
+
+Validate a single file or directory (does not require source registration):
+
+```bash
+gbrain frontmatter validate <path> --json
+```
+
+Exit code 0 = clean; 1 = errors found. Use this in CI pipelines or pre-commit hooks.
+
+### Phase 3: Fix
+
+When issues are found:
+
+```bash
+gbrain frontmatter validate <path> --fix
+```
+
+`--fix` writes `<file>.bak` for every modified file before mutating. The backup is the safety contract — works whether the brain is a git repo or a plain directory.
+
+`--dry-run` previews without writing. Use this before applying fixes in batch.
+
+### Phase 4: Pre-commit hook (optional)
+
+For brain repos that ARE git repos, install the pre-commit hook to block malformed pages from being committed in the first place:
+
+```bash
+gbrain frontmatter install-hook [--source <id>]
+```
+
+The hook runs `gbrain frontmatter validate` against staged `.md`/`.mdx` files. Bypass with `git commit --no-verify`.
+
+## Trigger words
+
+When the user says any of these, route here:
+- "validate frontmatter"
+- "check frontmatter"
+- "fix frontmatter"
+- "frontmatter audit"
+- "brain lint"
+
+## Output rules
+
+- Always run `gbrain frontmatter audit --json` first; never assume a brain is clean.
+- Surface counts to the user in plain language; do not dump raw JSON.
+- For `--fix` operations: state how many files will be modified BEFORE running, then confirm.
+- `SLUG_MISMATCH` fixes remove the frontmatter `slug:` field — gbrain derives slug from path. Mention this when the user's title is intentionally renamed.
+- Never auto-fix `MISSING_OPEN` or `EMPTY_FRONTMATTER` without explicit user input — these usually mean a human author started a page and didn't finish.
+
+## Chains with
+
+- `gbrain doctor` — the `frontmatter_integrity` subcheck reports the same counts as `audit`.
+- `skills/maintain/SKILL.md` — broader brain health audit; chain after this skill if other classes of issue are suspected.
+- `skills/lint/SKILL.md` (via `gbrain lint`) — overlapping rules for skill-file lint; the `frontmatter-*` rule names in lint output come from this skill's validation surface.
+
+## Output Format
+
+Audit summary (terse, agent-friendly):
+
+```
+Frontmatter audit — 17 issue(s) across 1 source(s)
+
+[default] /Users/me/brain
+  17 issue(s)
+    MISSING_CLOSE: 8
+    NESTED_QUOTES: 5
+    NULL_BYTES: 4
+  sample:
+    people/jane.md — MISSING_CLOSE
+    companies/acme.md — NESTED_QUOTES
+    (+ 12 more)
+
+Fix with: gbrain frontmatter validate /Users/me/brain --fix
+```
+
+JSON envelope (when `--json` is passed):
+
+```json
+{
+  "ok": false,
+  "total": 17,
+  "errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
+  "per_source": [
+    {
+      "source_id": "default",
+      "source_path": "/Users/me/brain",
+      "total": 17,
+      "errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
+      "sample": [{ "path": "people/jane.md", "codes": ["MISSING_CLOSE"] }]
+    }
+  ],
+  "scanned_at": "2026-04-25T22:30:00.000Z"
+}
+```
+
+`gbrain frontmatter validate <path> --json` returns a similar envelope keyed on per-file results instead of per-source.
+
+## Anti-Patterns
+
+**Don't auto-fix `MISSING_OPEN` or `EMPTY_FRONTMATTER` without user input.** These usually mean a human author started a page and didn't finish — silently inserting `---` markers around an unfinished draft is wrong.
+
+**Don't use `--fix` to "make doctor green" without reading the audit first.** SLUG_MISMATCH cases are surfaced for manual review specifically because gbrain derives the slug from path. A mismatch usually means the user renamed a file intentionally; auto-removing the slug field is the right outcome only when you've confirmed the rename was deliberate.
+
+**Don't skip the `.bak` backups.** The `.bak` is the safety contract for non-git brain repos. If `.bak` files accumulate after a fix run, that's a feature, not a bug — the user can review the diffs and delete the backups when satisfied.
+
+**Don't run `audit` on a brain where sources aren't registered.** The CLI returns "no registered sources to audit" gracefully, but the migration emits a `skipped: no_sources` phase result. Don't paper over this with a manual path-walk; the right fix is to register the source via `gbrain sources add`.
+
+**Don't install the pre-commit hook on non-git brain dirs.** The install-hook command skips them automatically with a one-line note. If you see "skipped — not a git repo" and want validation at write time anyway, use the `audit` command on a cron schedule.

skills/frontmatter-guard/routing-eval.jsonl

@@ -0,0 +1,8 @@
+// Routing eval fixtures for skills/frontmatter-guard. Check 5 (W2, v0.17).
+// Layer A (structural) requires intents to contain trigger words from
+// the resolver. Paraphrase the trigger framing, not its meaning.
+{"intent": "please validate frontmatter on the latest batch of brain pages", "expected_skill": "frontmatter-guard"}
+{"intent": "fix frontmatter on these pages", "expected_skill": "frontmatter-guard"}
+{"intent": "I want to run a frontmatter audit across the brain", "expected_skill": "frontmatter-guard"}
+// Negative case: something that sounds similar but should NOT route here.
+{"intent": "what's for breakfast", "expected_skill": null, "ambiguous_with": []}

skills/maintain/SKILL.md

@@ -8,7 +8,6 @@ description: |
 triggers:
   - "brain health"
   - "check backlinks"
-  - "citation audit"
   - "maintenance"
   - "orphan pages"
   - "stale pages"

skills/manifest.json

@@ -44,6 +44,11 @@
       "path": "publish/SKILL.md",
       "description": "Share brain pages as beautiful password-protected HTML (code + skill pair, zero LLM calls)"
     },
+    {
+      "name": "frontmatter-guard",
+      "path": "frontmatter-guard/SKILL.md",
+      "description": "Validate and auto-repair YAML frontmatter on brain pages; gates against malformed YAML, missing closing ---, nested quotes, slug mismatches, null bytes"
+    },
     {
       "name": "signal-detector",
       "path": "signal-detector/SKILL.md",

skills/migrations/v0.22.4.md

@@ -0,0 +1,113 @@
+# v0.22.4 — Frontmatter Guard
+
+## What ships
+
+- `gbrain frontmatter` CLI (validate / audit / install-hook)
+- `frontmatter_integrity` subcheck under `gbrain doctor`
+- New `frontmatter-guard` skill (`skills/frontmatter-guard/SKILL.md`)
+- Pre-commit hook helper for git-backed brain repos
+- Audit-only migration that scans every registered source, writes
+  `~/.gbrain/migrations/v0.22.4-audit.json`, and queues per-source TODO
+  entries to `~/.gbrain/migrations/pending-host-work.jsonl`
+- 0 warnings on `gbrain check-resolvable` (down from 7 on master)
+
+## What the agent should do post-upgrade
+
+The orchestrator handles the mechanical side. Your job is to surface the audit
+to the user and apply fixes with their consent.
+
+### 1. Run the orchestrator
+
+```bash
+gbrain apply-migrations --yes
+```
+
+This runs three idempotent phases:
+
+- `schema` (no-op in v0.22.4)
+- `audit` — `scanBrainSources()` over every registered source; writes
+  `~/.gbrain/migrations/v0.22.4-audit.json`
+- `emit-todo` — appends one entry per source-with-issues to
+  `~/.gbrain/migrations/pending-host-work.jsonl`. Each entry contains the
+  exact `gbrain frontmatter validate <source-path> --fix` command.
+
+The migration **never mutates brain pages**. Auto-fixes only run when the user
+explicitly invokes the validate-with-fix command below.
+
+### 2. Read the audit report
+
+```bash
+cat ~/.gbrain/migrations/v0.22.4-audit.json
+```
+
+The shape:
+
+```json
+{
+  "ok": false,
+  "total": 17,
+  "errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
+  "per_source": [
+    {
+      "source_id": "default",
+      "source_path": "/Users/me/brain",
+      "total": 17,
+      "errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
+      "sample": [
+        { "path": "people/jane.md", "codes": ["MISSING_CLOSE"] }
+      ]
+    }
+  ],
+  "scanned_at": "2026-04-25T22:30:00.000Z"
+}
+```
+
+### 3. Surface the report to the user
+
+State the per-source counts in plain language. Example:
+
+> "v0.22.4 ships frontmatter-guard. I ran an audit and found 17 issues across
+> 1 source (default: 8 MISSING_CLOSE, 5 NESTED_QUOTES, 4 NULL_BYTES). The
+> mechanical errors are auto-fixable; SLUG_MISMATCH cases (if any) need your
+> review. Want me to fix the auto-fixable ones now?"
+
+### 4. Run the fix (with consent)
+
+Per source with issues, the queued command is:
+
+```bash
+gbrain frontmatter validate <source_path> --fix
+```
+
+`--fix` writes a `.bak` backup for every modified file. SLUG_MISMATCH errors
+are surfaced for manual review (not auto-fixed) — gbrain derives slugs from
+path, so a mismatched slug usually means the user renamed the file
+intentionally or the slug field is stale.
+
+### 5. (Optional) Install the pre-commit hook
+
+For git-backed sources only:
+
+```bash
+gbrain frontmatter install-hook [--source <id>]
+```
+
+This blocks future malformed-frontmatter commits at the git layer. Bypass with
+`git commit --no-verify`. Skip this step for non-git brains.
+
+### 6. Verify
+
+```bash
+gbrain doctor --json | jq '.checks[] | select(.name == "frontmatter_integrity")'
+gbrain frontmatter audit --json | jq '.total'
+```
+
+Both should report 0 issues after fixes are applied.
+
+### 7. If anything fails
+
+Open an issue at https://github.com/garrytan/gbrain/issues with:
+- output of `gbrain doctor`
+- contents of `~/.gbrain/migrations/v0.22.4-audit.json`
+- contents of `~/.gbrain/upgrade-errors.jsonl` if it exists
+- which step broke

skills/query/SKILL.md

@@ -12,6 +12,8 @@ triggers:
   - "what happened"
   - "search for"
   - "look up"
+  - "background on"
+  - "notes on"
   - "who knows who"
   - "relationship between"
   - "connections"

src/cli.ts

@@ -19,7 +19,7 @@ for (const op of operations) {
 }
 
 // CLI-only commands that bypass the operation layer
-const CLI_ONLY = new Set(['init', 'upgrade', 'post-upgrade', 'check-update', 'integrations', 'publish', 'check-backlinks', 'lint', 'report', 'import', 'export', 'files', 'embed', 'serve', 'call', 'config', 'doctor', 'migrate', 'eval', 'sync', 'extract', 'features', 'autopilot', 'graph-query', 'jobs', 'agent', 'apply-migrations', 'skillpack-check', 'skillpack', 'resolvers', 'integrity', 'repair-jsonb', 'orphans', 'sources', 'dream', 'check-resolvable', 'routing-eval', 'skillify', 'smoke-test', 'repos', 'code-def', 'code-refs', 'reindex-code', 'code-callers', 'code-callees']);
+const CLI_ONLY = new Set(['init', 'upgrade', 'post-upgrade', 'check-update', 'integrations', 'publish', 'check-backlinks', 'lint', 'report', 'import', 'export', 'files', 'embed', 'serve', 'call', 'config', 'doctor', 'migrate', 'eval', 'sync', 'extract', 'features', 'autopilot', 'graph-query', 'jobs', 'agent', 'apply-migrations', 'skillpack-check', 'skillpack', 'resolvers', 'integrity', 'repair-jsonb', 'orphans', 'sources', 'dream', 'check-resolvable', 'routing-eval', 'skillify', 'smoke-test', 'repos', 'code-def', 'code-refs', 'reindex-code', 'code-callers', 'code-callees', 'frontmatter']);
 
 async function main() {
   // Parse global flags (--quiet / --progress-json / --progress-interval)
@@ -305,6 +305,11 @@ async function handleCliOnly(command: string, args: string[]) {
     await runBacklinks(args);
     return;
   }
+  if (command === 'frontmatter') {
+    const { runFrontmatter } = await import('./commands/frontmatter.ts');
+    await runFrontmatter(args);
+    return;
+  }
   if (command === 'lint') {
     const { runLint } = await import('./commands/lint.ts');
     await runLint(args);
@@ -576,7 +581,10 @@ async function connectEngine(): Promise<BrainEngine> {
   }
   const { createEngine } = await import('./core/engine-factory.ts');
   const engine = await createEngine(toEngineConfig(config));
-  await engine.connect(toEngineConfig(config));
+  const noRetry = process.argv.includes('--no-retry-connect') ||
+                  process.env.GBRAIN_NO_RETRY_CONNECT === '1';
+  const { connectWithRetry } = await import('./core/db.ts');
+  await connectWithRetry(engine, toEngineConfig(config), { noRetry });
   return engine;
 }
 

src/commands/autopilot.ts

@@ -147,22 +147,41 @@ export async function runAutopilot(engine: BrainEngine, args: string[]) {
   let stopping = false;
   let workerProc: ChildProcess | null = null;
   let crashCount = 0;
+  let lastWorkerStartTime = 0;
+
+  // Stable-run reset window (matches MinionSupervisor.ts:471-476 pattern). If the
+  // worker ran > 5min before exit, treat as a fresh cycle (crashCount=1) so the
+  // RSS watchdog firing hourly does NOT trip autopilot's give-up threshold after
+  // ~5 hours of healthy uptime.
+  const STABLE_RUN_RESET_MS = 5 * 60 * 1000;
 
   if (spawnManagedWorker) {
     const cliPath = resolveGbrainCliPath();
     const startWorker = () => {
-      const child = spawn(cliPath, ['jobs', 'work'], { stdio: 'inherit', env: process.env });
+      // Inject the RSS watchdog default (2048 MB) for the autopilot-supervised
+      // worker. Bare `gbrain jobs work` has no default; the supervisor and
+      // autopilot are the production paths that opt in.
+      const args = ['jobs', 'work', '--max-rss', '2048'];
+      const child = spawn(cliPath, args, { stdio: 'inherit', env: process.env });
       workerProc = child;
-      console.log(`[autopilot] Minions worker spawned (pid: ${child.pid})`);
+      lastWorkerStartTime = Date.now();
+      console.log(`[autopilot] Minions worker spawned (pid: ${child.pid}, watchdog: 2048MB)`);
       child.on('exit', (code) => {
         workerProc = null;
         if (stopping) return;
+        const runDuration = Date.now() - lastWorkerStartTime;
+        if (runDuration > STABLE_RUN_RESET_MS) {
+          // Stable run — forgive prior crash history. A watchdog-driven hourly
+          // exit (the production path post-fix) lands here every time.
+          crashCount = 1;
+        } else {
+          crashCount++;
+        }
         if (crashCount >= 5) {
-          console.error('[autopilot] 5 consecutive worker crashes, giving up.');
+          console.error(`[autopilot] 5 consecutive worker crashes (run ${runDuration}ms), giving up.`);
           process.exit(1);
         }
-        crashCount++;
-        console.error(`[autopilot] worker exited code=${code}, restart #${crashCount} in 10s`);
+        console.error(`[autopilot] worker exited code=${code} after ${runDuration}ms, restart #${crashCount} in 10s`);
         setTimeout(startWorker, 10_000);
       });
     };
@@ -290,6 +309,12 @@ export async function runAutopilot(engine: BrainEngine, args: string[]) {
             idempotency_key: `autopilot-cycle:${slot}`,
             max_attempts: 2,
             timeout_ms: timeoutMs,
+            // Submission backpressure: when the worker is dead or wedged,
+            // idempotency_key only dedupes within a slot; cross-slot pile-up
+            // is what produced the 28+ waiting-jobs production incident.
+            // maxWaiting: 1 caps at 1 active + 1 waiting; queue.add coalesces
+            // the 3rd+ submission and writes a backpressure-audit JSONL line.
+            maxWaiting: 1,
           },
         );
         if (jsonMode) {

src/commands/doctor.ts

@@ -5,6 +5,7 @@ import { checkResolvable } from '../core/check-resolvable.ts';
 import { autoFixDryViolations, type AutoFixReport, type FixOutcome } from '../core/dry-fix.ts';
 import { findRepoRoot } from '../core/repo-root.ts';
 import { loadCompletedMigrations } from '../core/preferences.ts';
+import { compareVersions } from './migrations/index.ts';
 import { createProgress, startHeartbeat, type ProgressReporter } from '../core/progress.ts';
 import { getCliOptions, cliOptsToProgressOptions } from '../core/cli-options.ts';
 import type { DbUrlSource } from '../core/config.ts';
@@ -110,6 +111,15 @@ export async function runDoctor(engine: BrainEngine | null, args: string[], dbSo
   // Typical cause: v0.11.0 stopgap wrote a partial record but nobody ran
   // `gbrain apply-migrations --yes` afterward. This check fires on every
   // `gbrain doctor` invocation so your OpenClaw's health skill catches it.
+  //
+  // Forward-progress override: a partial entry for vX.Y.Z is treated as
+  // stale (not stuck) if there is a `complete` entry for any vA.B.C >= vX.Y.Z
+  // anywhere in the file. The reasoning: if a newer migration successfully
+  // landed, the install moved past the older partial — the old record is
+  // historical noise from a stopgap that never finished cleanly, but the
+  // schema clearly advanced. Without this, every install that went through
+  // a v0.11.0 stopgap and then upgraded carries the "MINIONS HALF-INSTALLED"
+  // flag forever, even on installs that have been at v0.22+ for months.
   try {
     const completed = loadCompletedMigrations();
     const byVersion = new Map<string, { complete: boolean; partial: boolean }>();
@@ -119,8 +129,17 @@ export async function runDoctor(engine: BrainEngine | null, args: string[], dbSo
       if (entry.status === 'partial') seen.partial = true;
       byVersion.set(entry.version, seen);
     }
+    const completedVersions = Array.from(byVersion.entries())
+      .filter(([, s]) => s.complete)
+      .map(([v]) => v);
     const stuck = Array.from(byVersion.entries())
-      .filter(([, s]) => s.partial && !s.complete)
+      .filter(([v, s]) => {
+        if (!s.partial || s.complete) return false;
+        // Forward-progress override: if any version >= v has completed, the
+        // partial is stale. compareVersions returns 1 when first arg is newer.
+        const supersededBy = completedVersions.find(cv => compareVersions(cv, v) >= 0);
+        return supersededBy === undefined;
+      })
       .map(([v]) => v);
     if (stuck.length > 0) {
       checks.push({
@@ -649,6 +668,53 @@ export async function runDoctor(engine: BrainEngine | null, args: string[], dbSo
     mbcHb();
   }
 
+  // 11a. Frontmatter integrity (v0.22.4).
+  // scanBrainSources walks every registered source's local_path on disk
+  // (not from the DB), invoking parseMarkdown(..., {validate:true}) per
+  // file. Reports per-source counts grouped by error code. The fix path is
+  // `gbrain frontmatter validate <source-path> --fix`, which writes .bak
+  // backups so it works for both git and non-git brain repos.
+  progress.heartbeat('frontmatter_integrity');
+  const fmHb = startHeartbeat(progress, 'scanning frontmatter…');
+  try {
+    const { scanBrainSources } = await import('../core/brain-writer.ts');
+    const report = await scanBrainSources(engine);
+    if (report.total === 0) {
+      const sources = report.per_source.length;
+      checks.push({
+        name: 'frontmatter_integrity',
+        status: 'ok',
+        message: sources === 0
+          ? 'No registered sources to scan'
+          : `${sources} source(s) clean — no frontmatter issues`,
+      });
+    } else {
+      const sourceMessages: string[] = [];
+      for (const src of report.per_source) {
+        if (src.total === 0) continue;
+        const codes = Object.entries(src.errors_by_code)
+          .map(([k, v]) => `${k}=${v}`)
+          .join(', ');
+        sourceMessages.push(`${src.source_id}: ${src.total} (${codes})`);
+      }
+      checks.push({
+        name: 'frontmatter_integrity',
+        status: 'warn',
+        message:
+          `${report.total} frontmatter issue(s) across ${sourceMessages.length} source(s). ` +
+          `${sourceMessages.join('; ')}. Fix: gbrain frontmatter validate <source-path> --fix`,
+      });
+    }
+  } catch (e) {
+    checks.push({
+      name: 'frontmatter_integrity',
+      status: 'warn',
+      message: `Could not scan frontmatter: ${e instanceof Error ? e.message : String(e)}`,
+    });
+  } finally {
+    fmHb();
+  }
+
   // 11b. Queue health (v0.19.1 queue-resilience wave).
   // Postgres-only because PGLite has no multi-process worker surface. Two
   // subchecks, both cheap (single SELECT each, status-index-covered):

src/commands/embed.ts

@@ -220,6 +220,23 @@ async function embedAll(
   result: EmbedResult,
   onProgress?: (done: number, total: number, embedded: number) => void,
 ) {
+  // ─────────────────────────────────────────────────────────────
+  // Stale-only fast path: avoid the listPages + per-page getChunks
+  // bomb that pulled every page row + every chunk's embedding column
+  // (~76 MB on a 1.5K-page brain) only to client-side-filter for
+  // chunks where embedding IS NULL. The new path issues one SQL
+  // pre-check + at most one slug-grouped SELECT excluding the
+  // (always-null on stale rows) embedding column. On a 100%-embedded
+  // brain (the autopilot common case) we exit after ~50 bytes wire.
+  //
+  // For --all (staleOnly=false) we keep the original behavior — the
+  // user is explicitly asking to re-embed everything, including
+  // chunks that already have embeddings.
+  // ─────────────────────────────────────────────────────────────
+  if (staleOnly) {
+    return await embedAllStale(engine, dryRun, result, onProgress);
+  }
+
   const pages = await engine.listPages({ limit: 100000 });
   let processed = 0;
 
@@ -235,9 +252,7 @@ async function embedAll(
 
   async function embedOnePage(page: typeof pages[number]) {
     const chunks = await engine.getChunks(page.slug);
-    const toEmbed = staleOnly
-      ? chunks.filter(c => !c.embedded_at)
-      : chunks;
+    const toEmbed = chunks; // staleOnly path handled above via embedAllStale
 
     result.total_chunks += chunks.length;
     result.skipped += chunks.length - toEmbed.length;
@@ -306,3 +321,120 @@ async function embedAll(
     console.log(`Embedded ${result.embedded} chunks across ${pages.length} pages`);
   }
 }
+
+/**
+ * SQL-side stale path: replaces the listPages + per-page getChunks
+ * walk with a count + slug-grouped SELECT. Preserves the existing
+ * functional contract (every chunk where embedding IS NULL gets
+ * embedded; nothing else is touched) without paying egress on
+ * already-embedded chunks.
+ *
+ * Why a separate function: the staleOnly path doesn't need
+ * listPages at all and groups by slug differently. Forking the
+ * function makes the read-bytes path explicit and keeps the --all
+ * path verbatim from prior behavior.
+ *
+ * Staleness predicate: `embedding IS NULL`. We deliberately do NOT
+ * use `embedded_at IS NULL` here — the bulk-import path can leave
+ * embedded_at populated while embedding is NULL (see upsertChunks
+ * consistency notes), and `embedding IS NULL` is the truth source
+ * for "this chunk needs an embedding".
+ */
+async function embedAllStale(
+  engine: BrainEngine,
+  dryRun: boolean,
+  result: EmbedResult,
+  onProgress?: (done: number, total: number, embedded: number) => void,
+) {
+  // Pre-flight: 0 stale chunks → nothing to do, no further DB reads.
+  // Cheapest possible exit on the autopilot common case.
+  const staleCount = await engine.countStaleChunks();
+  if (staleCount === 0) {
+    if (dryRun) {
+      console.log('[dry-run] Would embed 0 chunks (0 stale found)');
+    } else {
+      console.log('Embedded 0 chunks (0 stale found)');
+    }
+    return;
+  }
+
+  // Pull only the stale chunks (no embedding column).
+  const staleRows = await engine.listStaleChunks();
+  // Group by slug so each slug → array of stale chunks for batched embedding.
+  const bySlug = new Map<string, typeof staleRows>();
+  for (const row of staleRows) {
+    const list = bySlug.get(row.slug);
+    if (list) list.push(row);
+    else bySlug.set(row.slug, [row]);
+  }
+
+  const slugs = Array.from(bySlug.keys());
+  const totalStaleChunks = staleRows.length;
+  result.total_chunks += totalStaleChunks;
+  // skipped is "chunks we considered and skipped due to having an embedding".
+  // We never considered the non-stale chunks here, so leave skipped at 0.
+  // Callers reading EmbedResult who care about coverage should call
+  // engine.getStats() / engine.getHealth() afterward.
+
+  if (dryRun) {
+    result.would_embed += totalStaleChunks;
+    result.pages_processed += slugs.length;
+    if (onProgress) {
+      // Emit a single tick to satisfy the contract (CLI progress reporters
+      // expect at least one start/finish pair).
+      onProgress(slugs.length, slugs.length, 0);
+    }
+    console.log(`[dry-run] Would embed ${totalStaleChunks} chunks across ${slugs.length} pages`);
+    return;
+  }
+
+  const CONCURRENCY = parseInt(process.env.GBRAIN_EMBED_CONCURRENCY || '20', 10);
+  let processed = 0;
+
+  async function embedOneSlug(slug: string) {
+    const stale = bySlug.get(slug)!;
+    try {
+      const embeddings = await embedBatch(stale.map(c => c.chunk_text));
+      // CRITICAL: passing ONLY the stale indices to upsertChunks would
+      // delete every non-stale chunk on the same page (the != ALL filter
+      // wipes any chunk_index NOT in the input). To preserve them, we
+      // re-fetch existing chunks for this page and merge. Bounded by the
+      // stale slug count, not by total slugs — autopilot common case
+      // is 0 stale (pre-flight short-circuit, never reaches this path).
+      const existing = await engine.getChunks(slug);
+      const staleIdxToEmbedding = new Map<number, Float32Array>();
+      for (let j = 0; j < stale.length; j++) {
+        staleIdxToEmbedding.set(stale[j].chunk_index, embeddings[j]);
+      }
+      const merged: ChunkInput[] = existing.map(c => ({
+        chunk_index: c.chunk_index,
+        chunk_text: c.chunk_text,
+        chunk_source: c.chunk_source,
+        // For stale chunks: pass the new embedding.
+        // For non-stale chunks: pass undefined → COALESCE preserves existing embedding.
+        embedding: staleIdxToEmbedding.get(c.chunk_index) ?? undefined,
+        token_count: c.token_count || Math.ceil(c.chunk_text.length / 4),
+      }));
+      await engine.upsertChunks(slug, merged);
+      result.embedded += stale.length;
+    } catch (e: unknown) {
+      console.error(`\n  Error embedding ${slug}: ${e instanceof Error ? e.message : e}`);
+    }
+    processed++;
+    result.pages_processed++;
+    onProgress?.(processed, slugs.length, result.embedded);
+  }
+
+  let nextIdx = 0;
+  async function worker() {
+    while (nextIdx < slugs.length) {
+      const idx = nextIdx++;
+      await embedOneSlug(slugs[idx]);
+    }
+  }
+
+  const numWorkers = Math.min(CONCURRENCY, slugs.length);
+  await Promise.all(Array.from({ length: numWorkers }, () => worker()));
+
+  console.log(`Embedded ${result.embedded} chunks across ${slugs.length} pages`);
+}

src/commands/extract.ts

@@ -295,6 +295,13 @@ export interface ExtractOpts {
   dryRun?: boolean;
   /** Emit JSON (progress to stderr, result to stdout) instead of human text. */
   jsonMode?: boolean;
+  /**
+   * Incremental mode: only extract from these specific slugs.
+   * When provided, skips the full directory walk and reads only the
+   * files corresponding to these slugs. Massive perf win on large brains.
+   * Pass undefined or omit for a full walk (CLI / first-run path).
+   */
+  slugs?: string[];
 }
 
 /**
@@ -315,6 +322,21 @@ export async function runExtractCore(engine: BrainEngine, opts: ExtractOpts): Pr
   const jsonMode = !!opts.jsonMode;
   const result: ExtractResult = { links_created: 0, timeline_entries_created: 0, pages_processed: 0 };
 
+  // Incremental path: if specific slugs provided, only extract from those files.
+  // This is the cycle path — sync tells us what changed, we only re-extract those.
+  if (opts.slugs !== undefined) {
+    if (opts.slugs.length === 0) {
+      // Nothing changed — skip entirely.
+      return result;
+    }
+    const r = await extractForSlugs(engine, opts.dir, opts.slugs, opts.mode, dryRun, jsonMode);
+    result.links_created = r.links_created;
+    result.timeline_entries_created = r.timeline_created;
+    result.pages_processed = r.pages;
+    return result;
+  }
+
+  // Full walk path: CLI `gbrain extract` or first-run.
   if (opts.mode === 'links' || opts.mode === 'all') {
     const r = await extractLinksFromDir(engine, opts.dir, dryRun, jsonMode);
     result.links_created = r.created;
@@ -411,6 +433,118 @@ export async function runExtract(engine: BrainEngine, args: string[]) {
   }
 }
 
+/**
+ * Incremental extract: process only the specified slugs.
+ *
+ * Instead of walking 54K+ files, reads only the files that sync says changed.
+ * Still needs the full slug set for link resolution (resolveSlug needs to know
+ * all valid targets), but that's a single readdir, not 54K readFileSync calls.
+ *
+ * Combines links + timeline extraction in a single pass over each file —
+ * the full-walk path reads every file TWICE (once for links, once for timeline).
+ */
+async function extractForSlugs(
+  engine: BrainEngine,
+  brainDir: string,
+  slugs: string[],
+  mode: 'links' | 'timeline' | 'all',
+  dryRun: boolean,
+  jsonMode: boolean,
+): Promise<{ links_created: number; timeline_created: number; pages: number }> {
+  // Build the full slug set for link resolution (fast: just readdir, no file reads)
+  const allFiles = walkMarkdownFiles(brainDir);
+  const allSlugs = new Set(allFiles.map(f => f.relPath.replace('.md', '')));
+
+  const doLinks = mode === 'links' || mode === 'all';
+  const doTimeline = mode === 'timeline' || mode === 'all';
+
+  const progress = createProgress(cliOptsToProgressOptions(getCliOptions()));
+  progress.start('extract.incremental', slugs.length);
+
+  let linksCreated = 0;
+  let timelineCreated = 0;
+  let pagesProcessed = 0;
+
+  const linkBatch: LinkBatchInput[] = [];
+  const timelineBatch: TimelineBatchInput[] = [];
+
+  async function flushLinks() {
+    if (linkBatch.length === 0) return;
+    try {
+      linksCreated += await engine.addLinksBatch(linkBatch);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      if (!jsonMode) console.error(`  link batch error (${linkBatch.length} rows lost): ${msg}`);
+    } finally {
+      linkBatch.length = 0;
+    }
+  }
+
+  async function flushTimeline() {
+    if (timelineBatch.length === 0) return;
+    try {
+      timelineCreated += await engine.addTimelineEntriesBatch(timelineBatch);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      if (!jsonMode) console.error(`  timeline batch error (${timelineBatch.length} rows lost): ${msg}`);
+    } finally {
+      timelineBatch.length = 0;
+    }
+  }
+
+  for (const slug of slugs) {
+    const relPath = slug + '.md';
+    const fullPath = join(brainDir, relPath);
+
+    try {
+      if (!existsSync(fullPath)) continue; // deleted file — sync already handled removal
+      const content = readFileSync(fullPath, 'utf-8');
+
+      // Links
+      if (doLinks) {
+        const links = await extractLinksFromFile(content, relPath, allSlugs);
+        for (const link of links) {
+          if (dryRun) {
+            if (!jsonMode) console.log(`  ${link.from_slug} → ${link.to_slug} (${link.link_type})`);
+            linksCreated++;
+          } else {
+            linkBatch.push(link);
+            if (linkBatch.length >= BATCH_SIZE) await flushLinks();
+          }
+        }
+      }
+
+      // Timeline
+      if (doTimeline) {
+        const entries = extractTimelineFromContent(content, slug);
+        for (const entry of entries) {
+          if (dryRun) {
+            if (!jsonMode) console.log(`  ${entry.slug}: ${entry.date} — ${entry.summary}`);
+            timelineCreated++;
+          } else {
+            timelineBatch.push({ slug: entry.slug, date: entry.date, source: entry.source, summary: entry.summary, detail: entry.detail });
+            if (timelineBatch.length >= BATCH_SIZE) await flushTimeline();
+          }
+        }
+      }
+
+      pagesProcessed++;
+    } catch { /* skip unreadable */ }
+    progress.tick(1);
+  }
+
+  await flushLinks();
+  await flushTimeline();
+  progress.finish();
+
+  if (!jsonMode) {
+    const label = dryRun ? '(dry run) would create' : 'created';
+    console.log(`Incremental extract: ${label} ${linksCreated} link(s), ${timelineCreated} timeline entries from ${pagesProcessed}/${slugs.length} page(s)`);
+  }
+
+  return { links_created: linksCreated, timeline_created: timelineCreated, pages: pagesProcessed };
+}
+
 async function extractLinksFromDir(
   engine: BrainEngine, brainDir: string, dryRun: boolean, jsonMode: boolean,
 ): Promise<{ created: number; pages: number }> {

src/commands/frontmatter-install-hook.ts

@@ -0,0 +1,216 @@
+/**
+ * gbrain frontmatter install-hook — Install a pre-commit hook in a brain
+ * source's git repo that runs `gbrain frontmatter validate` against staged
+ * .md/.mdx files. Skips non-git sources with a one-line note.
+ *
+ * Usage:
+ *   gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]
+ *
+ *   --source <id>  Limit to one registered source. Default: all sources.
+ *   --force        Overwrite an existing pre-commit hook (writes <hook>.bak).
+ *   --uninstall    Remove the hook; restore <hook>.bak if present.
+ *
+ * Hook contract:
+ *   - Located at <source>/.githooks/pre-commit. We `git config core.hooksPath
+ *     .githooks` if no other hooksPath is set.
+ *   - When the gbrain binary is missing, the hook prints a one-line warning
+ *     and exits 0 (don't break commits if a developer uninstalls gbrain).
+ *   - Bypass via `git commit --no-verify`.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync, copyFileSync } from 'fs';
+import { join } from 'path';
+import { execFileSync } from 'child_process';
+import type { BrainEngine } from '../core/engine.ts';
+import { loadConfig, toEngineConfig } from '../core/config.ts';
+import { createEngine } from '../core/engine-factory.ts';
+
+const HOOK_BANNER = '# gbrain frontmatter pre-commit hook (v0.22.4+)';
+
+const HOOK_SCRIPT = `#!/bin/sh
+${HOOK_BANNER}
+# Validates YAML frontmatter on staged .md / .mdx files. Bypass with
+# 'git commit --no-verify'. Uninstall with 'gbrain frontmatter install-hook --uninstall'.
+
+set -e
+
+if ! command -v gbrain >/dev/null 2>&1; then
+  echo "gbrain not on PATH; skipping frontmatter pre-commit (install gbrain to re-enable)." >&2
+  exit 0
+fi
+
+staged=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\\\.mdx?$' || true)
+[ -z "$staged" ] && exit 0
+
+failed=0
+for f in $staged; do
+  [ -f "$f" ] || continue
+  if ! gbrain frontmatter validate "$f" >/dev/null 2>&1; then
+    gbrain frontmatter validate "$f" >&2
+    failed=1
+  fi
+done
+
+if [ $failed -ne 0 ]; then
+  echo "" >&2
+  echo "Frontmatter validation failed. Run 'gbrain frontmatter validate <file> --fix' to repair, or 'git commit --no-verify' to bypass." >&2
+  exit 1
+fi
+`;
+
+interface SourceRow {
+  id: string;
+  local_path: string | null;
+}
+
+export async function runFrontmatterInstallHook(args: string[]): Promise<void> {
+  let force = false;
+  let uninstall = false;
+  let sourceId: string | undefined;
+  let help = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') help = true;
+    else if (a === '--force') force = true;
+    else if (a === '--uninstall') uninstall = true;
+    else if (a === '--source') sourceId = args[++i];
+    else if (a.startsWith('--source=')) sourceId = a.slice('--source='.length);
+  }
+
+  if (help) {
+    printHelp();
+    return;
+  }
+
+  const config = loadConfig();
+  if (!config) {
+    throw new Error('No brain configured. Run: gbrain init');
+  }
+  const engineConfig = toEngineConfig(config);
+  const engine = await createEngine(engineConfig);
+  await engine.connect(engineConfig);
+  try {
+    const sources = await listSources(engine, sourceId);
+    if (sources.length === 0) {
+      console.log(sourceId
+        ? `Source "${sourceId}" not found.`
+        : 'No registered sources. Run `gbrain sources list` to inspect.');
+      return;
+    }
+
+    let installed = 0;
+    let skipped = 0;
+    for (const src of sources) {
+      if (!src.local_path || !existsSync(src.local_path)) {
+        console.log(`[${src.id}] skipped — local_path missing on disk`);
+        skipped++;
+        continue;
+      }
+      if (!isGitRepo(src.local_path)) {
+        console.log(`[${src.id}] ${src.local_path} — skipped, not a git repo`);
+        skipped++;
+        continue;
+      }
+      if (uninstall) {
+        if (uninstallHook(src.local_path)) {
+          console.log(`[${src.id}] hook removed`);
+          installed++;
+        } else {
+          console.log(`[${src.id}] no gbrain pre-commit hook found; nothing to uninstall`);
+        }
+        continue;
+      }
+      const result = installHook(src.local_path, force);
+      if (result === 'installed') {
+        console.log(`[${src.id}] hook installed at .githooks/pre-commit`);
+        installed++;
+      } else if (result === 'skipped_existing') {
+        console.log(`[${src.id}] existing pre-commit hook found; pass --force to overwrite (.bak created)`);
+        skipped++;
+      } else {
+        console.log(`[${src.id}] hook already up to date`);
+      }
+    }
+
+    console.log(`\nDone. ${installed} ${uninstall ? 'removed' : 'installed/updated'}, ${skipped} skipped.`);
+  } finally {
+    await engine.disconnect();
+  }
+}
+
+function printHelp() {
+  console.log(`gbrain frontmatter install-hook — install pre-commit hook in source git repos
+
+Usage:
+  gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]
+
+The hook runs \`gbrain frontmatter validate\` against staged .md/.mdx files,
+blocking commits with malformed frontmatter. Bypass with 'git commit --no-verify'.
+
+Options:
+  --source <id>  Limit to one registered source. Default: all sources.
+  --force        Overwrite an existing pre-commit hook (writes <hook>.bak).
+  --uninstall    Remove the hook; restore <hook>.bak if present.
+`);
+}
+
+async function listSources(engine: BrainEngine, sourceId?: string): Promise<SourceRow[]> {
+  if (sourceId) {
+    return engine.executeRaw<SourceRow>(`SELECT id, local_path FROM sources WHERE id = $1`, [sourceId]);
+  }
+  return engine.executeRaw<SourceRow>(`SELECT id, local_path FROM sources WHERE local_path IS NOT NULL ORDER BY id`);
+}
+
+function isGitRepo(dir: string): boolean {
+  return existsSync(join(dir, '.git'));
+}
+
+type InstallResult = 'installed' | 'skipped_existing' | 'unchanged';
+
+export function installHook(repoPath: string, force: boolean): InstallResult {
+  const hooksDir = join(repoPath, '.githooks');
+  const hookPath = join(hooksDir, 'pre-commit');
+  mkdirSync(hooksDir, { recursive: true });
+
+  if (existsSync(hookPath)) {
+    const existing = readFileSync(hookPath, 'utf8');
+    if (existing.includes(HOOK_BANNER)) {
+      // Already a gbrain hook — refresh the script content silently.
+      writeFileSync(hookPath, HOOK_SCRIPT);
+      chmodSync(hookPath, 0o755);
+      return 'unchanged';
+    }
+    if (!force) return 'skipped_existing';
+    copyFileSync(hookPath, hookPath + '.bak');
+  }
+
+  writeFileSync(hookPath, HOOK_SCRIPT);
+  chmodSync(hookPath, 0o755);
+
+  // Set core.hooksPath unless the user has set it to something else already.
+  try {
+    const current = execFileSync('git', ['-C', repoPath, 'config', '--get', 'core.hooksPath'], { encoding: 'utf8' }).trim();
+    if (current && current !== '.githooks') return 'installed';
+  } catch {
+    // git config returns non-zero when the key is unset; that's the normal case.
+  }
+  try {
+    execFileSync('git', ['-C', repoPath, 'config', 'core.hooksPath', '.githooks']);
+  } catch {
+    // Best-effort. Hook still exists; user can configure manually.
+  }
+  return 'installed';
+}
+
+export function uninstallHook(repoPath: string): boolean {
+  const hookPath = join(repoPath, '.githooks', 'pre-commit');
+  if (!existsSync(hookPath)) return false;
+  const content = readFileSync(hookPath, 'utf8');
+  if (!content.includes(HOOK_BANNER)) return false;
+  rmSync(hookPath);
+  if (existsSync(hookPath + '.bak')) {
+    copyFileSync(hookPath + '.bak', hookPath);
+    rmSync(hookPath + '.bak');
+  }
+  return true;
+}

src/commands/frontmatter.ts

@@ -0,0 +1,299 @@
+/**
+ * gbrain frontmatter — Frontmatter validation, audit, and auto-repair.
+ *
+ * Subcommands:
+ *   gbrain frontmatter validate <path> [--json] [--fix] [--dry-run]
+ *     Validate one file or recursively a directory. --fix writes .bak then
+ *     rewrites in place. --dry-run previews without writing.
+ *
+ *   gbrain frontmatter audit [--source <id>] [--json]
+ *     Read-only scan across all registered sources (or one with --source).
+ *     Returns AuditReport-shaped JSON with --json.
+ *
+ * The audit subcommand is intentionally read-only; --fix only exists on
+ * validate. Pass an explicit path to validate a non-source-registered tree.
+ */
+
+import { readFileSync, writeFileSync, existsSync, lstatSync, readdirSync, copyFileSync } from 'fs';
+import { join, relative, resolve } from 'path';
+import type { BrainEngine } from '../core/engine.ts';
+import { loadConfig, toEngineConfig } from '../core/config.ts';
+import { createEngine } from '../core/engine-factory.ts';
+import { parseMarkdown, type ParseValidationCode } from '../core/markdown.ts';
+import {
+  autoFixFrontmatter,
+  scanBrainSources,
+  type AuditReport,
+  type AuditFix,
+} from '../core/brain-writer.ts';
+import { isSyncable, slugifyPath } from '../core/sync.ts';
+
+export async function runFrontmatter(args: string[]): Promise<void> {
+  const sub = args[0];
+  if (!sub || sub === '--help' || sub === '-h') {
+    printHelp();
+    return;
+  }
+  const rest = args.slice(1);
+
+  if (sub === 'validate') {
+    await runValidate(rest);
+    return;
+  }
+  if (sub === 'audit') {
+    const engine = await connectEngineForAudit();
+    try {
+      await runAudit(engine, rest);
+    } finally {
+      await engine.disconnect();
+    }
+    return;
+  }
+  if (sub === 'install-hook') {
+    const { runFrontmatterInstallHook } = await import('./frontmatter-install-hook.ts');
+    await runFrontmatterInstallHook(rest);
+    return;
+  }
+  console.error(`Unknown frontmatter subcommand: ${sub}\n`);
+  printHelp();
+  process.exitCode = 1;
+}
+
+async function connectEngineForAudit(): Promise<BrainEngine> {
+  const config = loadConfig();
+  if (!config) {
+    throw new Error('No brain configured. Run: gbrain init');
+  }
+  const engineConfig = toEngineConfig(config);
+  const engine = await createEngine(engineConfig);
+  await engine.connect(engineConfig);
+  return engine;
+}
+
+function printHelp() {
+  console.log(`gbrain frontmatter — frontmatter validation, audit, and auto-repair
+
+Usage:
+  gbrain frontmatter validate <path> [--json] [--fix] [--dry-run]
+  gbrain frontmatter audit [--source <id>] [--json]
+  gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]
+
+validate
+  Validate one .md file or recursively a directory. Each file is parsed via
+  parseMarkdown(..., {validate:true}); errors are reported by code:
+    MISSING_OPEN, MISSING_CLOSE, YAML_PARSE, SLUG_MISMATCH,
+    NULL_BYTES, NESTED_QUOTES, EMPTY_FRONTMATTER
+
+  --fix      Auto-repair the fixable subset (NULL_BYTES, MISSING_CLOSE,
+             NESTED_QUOTES, SLUG_MISMATCH). Writes <file>.bak before any
+             in-place rewrite. .bak is the safety contract; works for both
+             git and non-git brain repos.
+  --dry-run  Preview --fix without writing.
+  --json     Emit a JSON envelope on stdout.
+
+audit
+  Read-only scan across all registered sources (or one with --source <id>).
+  Reports per-source counts grouped by error code. Use this in CI or doctor
+  pipelines. Exits 0 even when issues are found — the count is the signal.
+
+  --source <id>  Limit scan to one registered source.
+  --json         Emit AuditReport-shaped JSON on stdout.
+`);
+}
+
+// ---------------------------------------------------------------------------
+// validate
+// ---------------------------------------------------------------------------
+
+interface ValidateFlags {
+  json: boolean;
+  fix: boolean;
+  dryRun: boolean;
+}
+
+interface FileValidation {
+  path: string;
+  errors: { code: ParseValidationCode; message: string; line?: number }[];
+  fixesApplied?: AuditFix[];
+}
+
+async function runValidate(rest: string[]): Promise<void> {
+  const flags: ValidateFlags = { json: false, fix: false, dryRun: false };
+  let target: string | null = null;
+  for (const a of rest) {
+    if (a === '--json') flags.json = true;
+    else if (a === '--fix') flags.fix = true;
+    else if (a === '--dry-run') flags.dryRun = true;
+    else if (!a.startsWith('--')) target = a;
+  }
+  if (!target) {
+    console.error('error: gbrain frontmatter validate requires a <path> argument');
+    process.exitCode = 1;
+    return;
+  }
+
+  const resolved = resolve(target);
+  if (!existsSync(resolved)) {
+    console.error(`error: path not found: ${target}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const files = collectFiles(resolved);
+  const results: FileValidation[] = [];
+
+  for (const file of files) {
+    const content = readFileSync(file, 'utf8');
+    const expectedSlug = slugifyPath(relative(resolve(target), file) || file);
+    const parsed = parseMarkdown(content, file, { validate: true, expectedSlug });
+    const errs = parsed.errors ?? [];
+    const result: FileValidation = {
+      path: file,
+      errors: errs.map(e => ({ code: e.code, message: e.message, line: e.line })),
+    };
+
+    if (flags.fix && errs.length > 0) {
+      const { content: fixed, fixes } = autoFixFrontmatter(content, { filePath: file });
+      result.fixesApplied = fixes;
+      if (fixes.length > 0 && !flags.dryRun) {
+        copyFileSync(file, file + '.bak');
+        writeFileSync(file, fixed, 'utf8');
+      }
+    }
+
+    results.push(result);
+  }
+
+  const totalErrors = results.reduce((n, r) => n + r.errors.length, 0);
+  const filesWithErrors = results.filter(r => r.errors.length > 0).length;
+  const filesFixed = results.filter(r => (r.fixesApplied?.length ?? 0) > 0).length;
+
+  if (flags.json) {
+    const envelope = {
+      ok: totalErrors === 0,
+      target: resolved,
+      total_files: files.length,
+      files_with_errors: filesWithErrors,
+      total_errors: totalErrors,
+      files_fixed: flags.fix ? filesFixed : undefined,
+      dry_run: flags.dryRun || undefined,
+      results,
+    };
+    console.log(JSON.stringify(envelope, null, 2));
+  } else {
+    if (totalErrors === 0) {
+      console.log(`OK — ${files.length} file(s) scanned, no frontmatter issues`);
+    } else {
+      console.log(`Found ${totalErrors} issue(s) across ${filesWithErrors} file(s) (scanned ${files.length})`);
+      for (const r of results) {
+        if (r.errors.length === 0) continue;
+        console.log(`\n${r.path}`);
+        for (const e of r.errors) {
+          const lineHint = e.line !== undefined ? `:${e.line}` : '';
+          console.log(`  [${e.code}]${lineHint} ${e.message}`);
+        }
+        if (r.fixesApplied && r.fixesApplied.length > 0) {
+          const verb = flags.dryRun ? 'would fix' : 'fixed';
+          for (const f of r.fixesApplied) {
+            console.log(`  ${verb}: ${f.description}`);
+          }
+        }
+      }
+      if (flags.fix && !flags.dryRun) {
+        console.log(`\nWrote .bak backups for ${filesFixed} file(s).`);
+      }
+    }
+  }
+
+  process.exitCode = totalErrors > 0 && !flags.fix ? 1 : 0;
+}
+
+function collectFiles(target: string): string[] {
+  const st = lstatSync(target);
+  if (st.isFile()) {
+    return [target];
+  }
+  const out: string[] = [];
+  const stack = [target];
+  while (stack.length > 0) {
+    const dir = stack.pop()!;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      const full = join(dir, name);
+      let entryStat: ReturnType<typeof lstatSync>;
+      try {
+        entryStat = lstatSync(full);
+      } catch {
+        continue;
+      }
+      if (entryStat.isSymbolicLink()) continue;
+      if (entryStat.isDirectory()) {
+        stack.push(full);
+      } else if (entryStat.isFile()) {
+        const rel = relative(target, full);
+        if (isSyncable(rel, { strategy: 'markdown' })) {
+          out.push(full);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// audit
+// ---------------------------------------------------------------------------
+
+async function runAudit(engine: BrainEngine, rest: string[]): Promise<void> {
+  let json = false;
+  let sourceId: string | undefined;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--json') json = true;
+    else if (a === '--source') sourceId = rest[++i];
+    else if (a.startsWith('--source=')) sourceId = a.slice('--source='.length);
+  }
+
+  const report = await scanBrainSources(engine, { sourceId });
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  printAuditHumanReport(report);
+}
+
+function printAuditHumanReport(report: AuditReport): void {
+  if (report.per_source.length === 0) {
+    console.log('No registered sources to audit. Run `gbrain sources list` to inspect.');
+    return;
+  }
+  console.log(`Frontmatter audit — ${report.total} issue(s) across ${report.per_source.length} source(s) (scanned at ${report.scanned_at})`);
+  for (const src of report.per_source) {
+    console.log(`\n[${src.source_id}] ${src.source_path}`);
+    if (src.total === 0) {
+      console.log('  clean');
+      continue;
+    }
+    console.log(`  ${src.total} issue(s)`);
+    for (const [code, n] of Object.entries(src.errors_by_code)) {
+      console.log(`    ${code}: ${n}`);
+    }
+    if (src.sample.length > 0) {
+      console.log(`  sample:`);
+      for (const s of src.sample.slice(0, 5)) {
+        console.log(`    ${s.path} — ${s.codes.join(', ')}`);
+      }
+      if (src.sample.length > 5) console.log(`    (+ ${src.sample.length - 5} more)`);
+    }
+  }
+  if (report.total > 0) {
+    console.log(`\nFix with: gbrain frontmatter validate <source-path> --fix`);
+  }
+}

src/commands/jobs.ts

@@ -32,6 +32,32 @@ export function parseMaxWaitingFlag(args: string[]): number | undefined {
   return Math.max(1, Math.min(100, parsed));
 }
 
+/** Parse `--max-rss N` (MB). Returns:
+ *  - 0 if the flag is absent (no watchdog by default for bare `jobs work`)
+ *  - 0 if `--max-rss 0` (explicit disable)
+ *  - the value if >= 256
+ *  Errors and exits the process if the flag is non-numeric, negative, or
+ *  positive but < 256 (likely a GB-vs-MB unit-confusion typo). */
+export function parseMaxRssFlag(args: string[]): number {
+  const raw = parseFlag(args, '--max-rss');
+  if (raw === undefined) return 0;
+  const parsed = parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    console.error(`Error: --max-rss must be a non-negative integer (MB), got "${raw}"`);
+    process.exit(1);
+  }
+  if (parsed === 0) return 0;
+  if (parsed < 256) {
+    console.error(
+      `Error: --max-rss ${parsed} is too low for production (likely a unit confusion: ` +
+      `--max-rss takes megabytes, not gigabytes). Use --max-rss 0 to disable, ` +
+      `or set a value >= 256.`
+    );
+    process.exit(1);
+  }
+  return parsed;
+}
+
 export function resolveWorkerConcurrency(args: string[], env: NodeJS.ProcessEnv = process.env): number {
   const raw = parseFlag(args, '--concurrency') ?? env.GBRAIN_WORKER_CONCURRENCY ?? '1';
   const parsed = parseInt(raw, 10);
@@ -106,11 +132,12 @@ USAGE
   gbrain jobs delete <id>
   gbrain jobs stats
   gbrain jobs smoke
-  gbrain jobs work [--queue Q] [--concurrency N]
+  gbrain jobs work [--queue Q] [--concurrency N] [--max-rss MB]
   gbrain jobs supervisor [start] [--detach] [--json]
                          [--concurrency N] [--queue Q] [--pid-file PATH]
                          [--max-crashes N] [--health-interval N]
                          [--allow-shell-jobs] [--cli-path PATH]
+                         [--max-rss MB]
   gbrain jobs supervisor status [--json] [--pid-file PATH]
   gbrain jobs supervisor stop [--json] [--pid-file PATH]
 
@@ -611,14 +638,19 @@ HANDLER TYPES (built in)
 
       const queueName = parseFlag(args, '--queue') ?? 'default';
       const concurrency = resolveWorkerConcurrency(args);
+      // --max-rss is opt-in for bare `gbrain jobs work` — preserves pre-v0.21 behavior
+      // for operators with legitimately large embed/import working sets. The supervisor
+      // path injects a default 2048; this code path does not.
+      const maxRssMb = parseMaxRssFlag(args);
 
       try { await queue.ensureSchema(); }
       catch (e) { console.error(e instanceof Error ? e.message : String(e)); process.exit(1); }
 
-      const worker = new MinionWorker(engine, { queue: queueName, concurrency });
+      const worker = new MinionWorker(engine, { queue: queueName, concurrency, maxRssMb });
       await registerBuiltinHandlers(worker, engine);
 
-      console.log(`Minion worker started (queue: ${queueName}, concurrency: ${concurrency})`);
+      const watchdogNote = maxRssMb > 0 ? `, watchdog: ${maxRssMb}MB` : '';
+      console.log(`Minion worker started (queue: ${queueName}, concurrency: ${concurrency}${watchdogNote})`);
       console.log(`Registered handlers: ${worker.registeredNames.join(', ')}`);
       await worker.start();
       break;
@@ -759,6 +791,11 @@ HANDLER TYPES (built in)
       const allowShellJobs = hasFlag(args, '--allow-shell-jobs') ||
                              !!process.env.GBRAIN_ALLOW_SHELL_JOBS;
       const detach = hasFlag(args, '--detach');
+      // Supervisor defaults --max-rss 2048 (MB) — main production path uses
+      // the supervisor, so the watchdog is on by default here. parseMaxRssFlag
+      // returns 0 when the flag is absent; substitute the supervisor default.
+      const maxRssRaw = parseMaxRssFlag(args);
+      const maxRssMb = parseFlag(args, '--max-rss') === undefined ? 2048 : maxRssRaw;
 
       const cliPath = parseFlag(args, '--cli-path') ?? resolveGbrainCliPath();
 
@@ -796,6 +833,7 @@ HANDLER TYPES (built in)
         cliPath,
         allowShellJobs,
         json: jsonMode,
+        maxRssMb,
         onEvent: (emission) => writeSupervisorEvent(emission, supervisorPid),
       });
 
@@ -913,6 +951,7 @@ export async function registerBuiltinHandlers(worker: MinionWorker, engine: Brai
     const report = await runCycle(engine, {
       brainDir: repoPath,
       pull: true, // autopilot daemon opts into git pull
+      signal: job.signal, // propagate abort so cycle bails on timeout/cancel
       yieldBetweenPhases: async () => {
         // Yield to the event loop so worker lock-renewal can fire.
         await new Promise<void>(r => setImmediate(r));

src/commands/lint.ts

@@ -18,6 +18,7 @@
 
 import { readFileSync, writeFileSync, readdirSync, statSync, lstatSync, existsSync } from 'fs';
 import { join, relative } from 'path';
+import { parseMarkdown, type ParseValidationCode } from '../core/markdown.ts';
 
 export interface LintIssue {
   file: string;
@@ -27,6 +28,25 @@ export interface LintIssue {
   fixable: boolean;
 }
 
+/** Map of frontmatter validation codes to lint rule names. Stable across
+ *  releases — agents and CI consumers can target specific rule names. */
+const FRONTMATTER_RULE_NAMES: Record<ParseValidationCode, string> = {
+  MISSING_OPEN: 'frontmatter-missing-open',
+  MISSING_CLOSE: 'frontmatter-missing-close',
+  YAML_PARSE: 'frontmatter-yaml-parse',
+  SLUG_MISMATCH: 'frontmatter-slug-mismatch',
+  NULL_BYTES: 'frontmatter-null-bytes',
+  NESTED_QUOTES: 'frontmatter-nested-quotes',
+  EMPTY_FRONTMATTER: 'frontmatter-empty',
+};
+
+/** Codes whose lint findings are fixable by `gbrain frontmatter validate --fix`. */
+const FRONTMATTER_FIXABLE: ReadonlySet<ParseValidationCode> = new Set<ParseValidationCode>([
+  'MISSING_CLOSE',
+  'NULL_BYTES',
+  'NESTED_QUOTES',
+]);
+
 // ── LLM artifact patterns ──────────────────────────────────────────
 
 const LLM_PREAMBLES = [
@@ -44,6 +64,25 @@ export function lintContent(content: string, filePath: string): LintIssue[] {
   const issues: LintIssue[] = [];
   const lines = content.split('\n');
 
+  // ── Frontmatter validation (delegates to parseMarkdown(validate:true)) ──
+  // This is the single source of truth for frontmatter shape rules. Each
+  // ParseValidationCode maps to a stable lint rule name in
+  // FRONTMATTER_RULE_NAMES. Keeps brain-page lint, doctor's
+  // frontmatter_integrity subcheck, and the frontmatter CLI in lockstep.
+  const parsed = parseMarkdown(content, filePath, { validate: true });
+  for (const err of parsed.errors ?? []) {
+    // Skip MISSING_OPEN — the legacy `no-frontmatter` rule below covers this
+    // exact case with a stable rule name. Emitting both is double-reporting.
+    if (err.code === 'MISSING_OPEN') continue;
+    issues.push({
+      file: filePath,
+      line: err.line ?? 1,
+      rule: FRONTMATTER_RULE_NAMES[err.code],
+      message: err.message,
+      fixable: FRONTMATTER_FIXABLE.has(err.code),
+    });
+  }
+
   // Rule: LLM preamble artifacts
   for (const pattern of LLM_PREAMBLES) {
     pattern.lastIndex = 0;

src/commands/migrations/index.ts

@@ -21,6 +21,7 @@ import { v0_16_0 } from './v0_16_0.ts';
 import { v0_18_0 } from './v0_18_0.ts';
 import { v0_18_1 } from './v0_18_1.ts';
 import { v0_21_0 } from './v0_21_0.ts';
+import { v0_22_4 } from './v0_22_4.ts';
 
 export const migrations: Migration[] = [
   v0_11_0,
@@ -33,6 +34,7 @@ export const migrations: Migration[] = [
   v0_18_0,
   v0_18_1,
   v0_21_0,
+  v0_22_4,
 ];
 
 /** Look up a migration by exact version string. */

src/commands/migrations/v0_22_4.ts

@@ -0,0 +1,228 @@
+/**
+ * v0.22.4 migration orchestrator — frontmatter-guard adoption.
+ *
+ * v0.22.4 ships a shared frontmatter validator (parseMarkdown(..., {validate:true})),
+ * a doctor subcheck (frontmatter_integrity), a top-level `gbrain frontmatter`
+ * CLI (validate / audit / install-hook), and a new `frontmatter-guard` skill.
+ *
+ * This migration is AUDIT-ONLY (per D5): it reads the user's brain pages,
+ * writes a JSON report to ~/.gbrain/migrations/v0.22.4-audit.json, and emits
+ * one entry per source-with-issues to ~/.gbrain/migrations/pending-host-work.jsonl.
+ * It NEVER mutates brain content. The agent reads skills/migrations/v0.22.4.md
+ * after upgrade and runs `gbrain frontmatter validate <source-path> --fix` with
+ * explicit user consent.
+ *
+ * Phases (all idempotent):
+ *   A. Schema   — no-op (no DB changes in v0.22.4).
+ *   B. Audit    — scanBrainSources → write JSON report.
+ *   C. Emit-todo — append pending-host-work.jsonl entry per source with errors.
+ *   D. Record   — runner-owned ledger write.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, appendFileSync } from 'fs';
+import { join } from 'path';
+import type { Migration, OrchestratorOpts, OrchestratorResult, OrchestratorPhaseResult } from './types.ts';
+import type { BrainEngine } from '../../core/engine.ts';
+import { loadConfig, toEngineConfig } from '../../core/config.ts';
+import { createEngine } from '../../core/engine-factory.ts';
+import { scanBrainSources, type AuditReport } from '../../core/brain-writer.ts';
+
+/** Test-only injection point for the audit phase. When set, phaseBAudit uses
+ *  this engine instead of loading config + creating a fresh one. Mirrors the
+ *  repair-jsonb pattern. Reset to null in afterAll. */
+let testEngineOverride: BrainEngine | null = null;
+export function __setTestEngineOverride(engine: BrainEngine | null): void {
+  testEngineOverride = engine;
+}
+
+function gbrainDir(): string {
+  return join(process.env.HOME || '', '.gbrain');
+}
+function migrationsDir(): string { return join(gbrainDir(), 'migrations'); }
+function auditReportPath(): string { return join(migrationsDir(), 'v0.22.4-audit.json'); }
+function pendingHostWorkPath(): string { return join(migrationsDir(), 'pending-host-work.jsonl'); }
+
+interface PendingHostWorkEntry {
+  migration: string;
+  ts: string;
+  skill: string;
+  reason: string;
+  source_id: string;
+  source_path: string;
+  command: string;
+}
+
+// ── Phase A — Schema (no-op) ───────────────────────────────
+
+function phaseASchema(opts: OrchestratorOpts): OrchestratorPhaseResult {
+  if (opts.dryRun) return { name: 'schema', status: 'skipped', detail: 'dry-run' };
+  return { name: 'schema', status: 'complete', detail: 'no schema changes in v0.22.4' };
+}
+
+// ── Phase B — Audit ────────────────────────────────────────
+
+async function phaseBAudit(opts: OrchestratorOpts): Promise<{ phase: OrchestratorPhaseResult; report: AuditReport | null }> {
+  if (opts.dryRun) return { phase: { name: 'audit', status: 'skipped', detail: 'dry-run' }, report: null };
+  try {
+    let report: AuditReport;
+    if (testEngineOverride) {
+      // Test injection path: caller manages engine lifecycle.
+      report = await scanBrainSources(testEngineOverride);
+    } else {
+      const config = loadConfig();
+      if (!config) {
+        // No brain configured (fresh dev install or test environment). The
+        // migration audit needs a real brain to walk; treat this as a clean
+        // skip rather than a failure so apply-migrations doesn't break.
+        return {
+          phase: { name: 'audit', status: 'skipped', detail: 'no_brain_configured' },
+          report: null,
+        };
+      }
+      const engineConfig = toEngineConfig(config);
+      const engine = await createEngine(engineConfig);
+      await engine.connect(engineConfig);
+      try {
+        report = await scanBrainSources(engine);
+      } finally {
+        await engine.disconnect();
+      }
+    }
+    if (report.per_source.length === 0) {
+      // No sources registered — fresh install or dev-only install. Skip
+      // cleanly; the orchestrator should report success.
+      return {
+        phase: { name: 'audit', status: 'skipped', detail: 'no_sources_registered' },
+        report,
+      };
+    }
+    mkdirSync(migrationsDir(), { recursive: true });
+    writeFileSync(auditReportPath(), JSON.stringify(report, null, 2));
+    return {
+      phase: {
+        name: 'audit',
+        status: 'complete',
+        detail: `${report.total} issue(s) across ${report.per_source.length} source(s); report at ${auditReportPath()}`,
+      },
+      report,
+    };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { phase: { name: 'audit', status: 'failed', detail: msg }, report: null };
+  }
+}
+
+// ── Phase C — Emit pending-host-work entries ──────────────
+
+function existingEntriesForVersion(version: string): Set<string> {
+  const out = new Set<string>();
+  const p = pendingHostWorkPath();
+  if (!existsSync(p)) return out;
+  try {
+    const raw = readFileSync(p, 'utf8');
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const obj = JSON.parse(trimmed) as PendingHostWorkEntry;
+        if (obj.migration === version && obj.source_id) {
+          out.add(obj.source_id);
+        }
+      } catch { /* skip malformed */ }
+    }
+  } catch { /* read error */ }
+  return out;
+}
+
+function phaseCEmitTodo(opts: OrchestratorOpts, report: AuditReport | null): OrchestratorPhaseResult {
+  if (opts.dryRun) return { name: 'emit-todo', status: 'skipped', detail: 'dry-run' };
+  if (!report) return { name: 'emit-todo', status: 'skipped', detail: 'no report' };
+
+  const sourcesWithIssues = report.per_source.filter(s => s.total > 0);
+  if (sourcesWithIssues.length === 0) {
+    return { name: 'emit-todo', status: 'complete', detail: 'no issues; nothing to queue' };
+  }
+
+  try {
+    mkdirSync(migrationsDir(), { recursive: true });
+    const already = existingEntriesForVersion('0.22.4');
+    let added = 0;
+    for (const src of sourcesWithIssues) {
+      if (already.has(src.source_id)) continue;
+      const entry: PendingHostWorkEntry = {
+        migration: '0.22.4',
+        ts: new Date().toISOString(),
+        skill: 'skills/migrations/v0.22.4.md',
+        reason: `${src.total} frontmatter issue(s) in source ${src.source_id}`,
+        source_id: src.source_id,
+        source_path: src.source_path,
+        command: `gbrain frontmatter validate ${src.source_path} --fix`,
+      };
+      appendFileSync(pendingHostWorkPath(), JSON.stringify(entry) + '\n');
+      added++;
+    }
+    return {
+      name: 'emit-todo',
+      status: 'complete',
+      detail: `appended ${added} entr${added === 1 ? 'y' : 'ies'} to ${pendingHostWorkPath()}`,
+    };
+  } catch (e) {
+    return { name: 'emit-todo', status: 'failed', detail: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+// ── Orchestrator ────────────────────────────────────────────
+
+async function orchestrator(opts: OrchestratorOpts): Promise<OrchestratorResult> {
+  console.log('');
+  console.log('=== v0.22.4 — frontmatter-guard adoption ===');
+  if (opts.dryRun) console.log('  (dry-run; no side effects)');
+  console.log('');
+
+  const phases: OrchestratorPhaseResult[] = [];
+
+  phases.push(phaseASchema(opts));
+
+  const { phase: bPhase, report } = await phaseBAudit(opts);
+  phases.push(bPhase);
+  if (bPhase.status === 'failed') {
+    return { version: '0.22.4', status: 'partial', phases };
+  }
+
+  phases.push(phaseCEmitTodo(opts, report));
+
+  const overallStatus: 'complete' | 'partial' | 'failed' =
+    phases.some(p => p.status === 'failed') ? 'partial' : 'complete';
+
+  return {
+    version: '0.22.4',
+    status: overallStatus,
+    phases,
+    pending_host_work: report?.per_source.filter(s => s.total > 0).length ?? 0,
+  };
+}
+
+export const v0_22_4: Migration = {
+  version: '0.22.4',
+  featurePitch: {
+    headline: 'Frontmatter-guard ships — broken brain pages can\'t hide',
+    description:
+      'gbrain v0.22.4 adds end-to-end frontmatter validation: a `gbrain frontmatter` CLI ' +
+      '(validate / audit / install-hook), a `frontmatter_integrity` doctor subcheck, a ' +
+      'pre-commit hook helper, and a new frontmatter-guard skill. The migration is audit-only ' +
+      '(it never mutates your brain) — it scans every registered source, writes a per-source ' +
+      'report to ~/.gbrain/migrations/v0.22.4-audit.json, and queues a TODO with the exact fix ' +
+      'command. Run `gbrain frontmatter validate <source-path> --fix` to repair (creates .bak ' +
+      'backups). Resolves all 7 check-resolvable warnings on master; ships frontmatter-guard.',
+  },
+  orchestrator,
+};
+
+/** Exported for unit tests. */
+export const __testing = {
+  phaseASchema,
+  phaseBAudit,
+  phaseCEmitTodo,
+  auditReportPath,
+  pendingHostWorkPath,
+};

src/core/brain-writer.ts

@@ -0,0 +1,394 @@
+/**
+ * brain-writer — frontmatter validation/audit/auto-fix orchestrator.
+ *
+ * Thin layer on top of `parseMarkdown(..., {validate:true})` (the canonical
+ * source of frontmatter validation rules) and `isSyncable()` (the canonical
+ * brain-page filter). Three consumers call into this module: the
+ * `gbrain frontmatter` CLI, the `frontmatter_integrity` doctor subcheck, and
+ * the v0.22.4 migration audit phase. Single source of truth — no parallel
+ * validation stack.
+ *
+ * Path-guard contract: writeBrainPage refuses to write outside the source
+ * path. .bak backups are the safety contract (works for both git and non-git
+ * brain repos; the existing src/core/dry-fix.ts:getWorkingTreeStatus rejects
+ * non-git repos as unsafe, which is the wrong shape for brain rewrites).
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync, copyFileSync, writeFileSync, mkdirSync, lstatSync } from 'fs';
+import { join, relative, resolve, dirname } from 'path';
+import type { BrainEngine } from './engine.ts';
+import type { ProgressReporter } from './progress.ts';
+import {
+  parseMarkdown,
+  type ParseValidationCode,
+  type ParseValidationError,
+} from './markdown.ts';
+import { isSyncable, slugifyPath } from './sync.ts';
+
+export type { ParseValidationCode };
+
+export interface AuditFix {
+  code: ParseValidationCode;
+  description: string;
+}
+
+export interface PerSourceReport {
+  source_id: string;
+  source_path: string;
+  total: number;
+  errors_by_code: Partial<Record<ParseValidationCode, number>>;
+  sample: { path: string; codes: ParseValidationCode[] }[];
+}
+
+export interface AuditReport {
+  ok: boolean;
+  total: number;
+  errors_by_code: Partial<Record<ParseValidationCode, number>>;
+  per_source: PerSourceReport[];
+  scanned_at: string;
+}
+
+const SAMPLE_PER_SOURCE = 20;
+
+// ---------------------------------------------------------------------------
+// autoFixFrontmatter
+// ---------------------------------------------------------------------------
+
+/**
+ * Mechanical auto-repair for the fixable subset of validation codes:
+ *   - NULL_BYTES        — strip \x00 characters
+ *   - NESTED_QUOTES     — rewrite `"... "inner" ..."` to single-quoted outer
+ *   - MISSING_CLOSE     — insert `---` before the first heading found inside
+ *                          the YAML zone
+ *   - SLUG_MISMATCH     — remove `slug:` line (gbrain derives slug from path)
+ *
+ * Idempotent: running twice is a no-op on already-clean input. Any error class
+ * not in the list above is left untouched (e.g. EMPTY_FRONTMATTER, YAML_PARSE,
+ * MISSING_OPEN — those need human review).
+ */
+export function autoFixFrontmatter(
+  content: string,
+  opts?: { filePath?: string },
+): { content: string; fixes: AuditFix[] } {
+  const fixes: AuditFix[] = [];
+  let working = content;
+
+  // 1. NULL_BYTES — strip them. Cheap, byte-level. Run first so subsequent
+  //    line-based passes don't trip on stray nulls.
+  if (working.indexOf('\x00') >= 0) {
+    working = working.replace(/\x00/g, '');
+    fixes.push({ code: 'NULL_BYTES', description: 'Stripped null bytes' });
+  }
+
+  // 2. MISSING_CLOSE — if there's an opener but no closer before a heading,
+  //    insert `---` immediately before the heading. Walk lines once.
+  {
+    const lines = working.split('\n');
+    let firstNonEmpty = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].trim().length > 0) { firstNonEmpty = i; break; }
+    }
+    if (firstNonEmpty >= 0 && lines[firstNonEmpty].trim() === '---') {
+      let closeIdx = -1;
+      let headingIdx = -1;
+      for (let i = firstNonEmpty + 1; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (t === '---') { closeIdx = i; break; }
+        if (/^#{1,6}\s/.test(t)) { headingIdx = i; break; }
+      }
+      if (closeIdx === -1 && headingIdx >= 0) {
+        const fixed = [
+          ...lines.slice(0, headingIdx),
+          '---',
+          '',
+          ...lines.slice(headingIdx),
+        ];
+        working = fixed.join('\n');
+        fixes.push({
+          code: 'MISSING_CLOSE',
+          description: `Inserted closing --- before heading at line ${headingIdx + 1}`,
+        });
+      }
+    }
+  }
+
+  // 3. NESTED_QUOTES — rewrite `key: "...inner..."` lines that have 3+ unescaped
+  //    double-quotes by switching the outer wrapper to single quotes and
+  //    leaving inner quotes alone.
+  {
+    const lines = working.split('\n');
+    let firstNonEmpty = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].trim().length > 0) { firstNonEmpty = i; break; }
+    }
+    if (firstNonEmpty >= 0 && lines[firstNonEmpty].trim() === '---') {
+      let closeIdx = lines.length;
+      for (let i = firstNonEmpty + 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---') { closeIdx = i; break; }
+      }
+      let fixedAny = false;
+      for (let i = firstNonEmpty + 1; i < closeIdx; i++) {
+        const m = lines[i].match(/^(\s*[A-Za-z_][\w-]*\s*:\s*)"(.*)"\s*(.*)$/);
+        if (!m) continue;
+        const [, prefix, inner, trailing] = m;
+        let count = 0;
+        for (let j = 0; j < inner.length; j++) {
+          if (inner[j] === '"' && (j === 0 || inner[j - 1] !== '\\')) count++;
+        }
+        // Total " on the line includes the two outer quotes the regex
+        // captured, plus whatever's in inner. We need 3+ to trigger.
+        if (count >= 1) {
+          // Inner already has unescaped " — outer wrap is causing the YAML
+          // parse failure. Rewrite to 'single-quoted'. YAML escapes `'` inside
+          // a single-quoted string by doubling it.
+          const escapedInner = inner.replace(/'/g, "''");
+          lines[i] = `${prefix}'${escapedInner}'${trailing ? ' ' + trailing : ''}`.replace(/\s+$/, '');
+          fixedAny = true;
+        }
+      }
+      if (fixedAny) {
+        working = lines.join('\n');
+        fixes.push({
+          code: 'NESTED_QUOTES',
+          description: 'Rewrote nested double-quoted YAML values to single-quoted',
+        });
+      }
+    }
+  }
+
+  // 4. SLUG_MISMATCH — remove `slug:` line if filePath is provided and the
+  //    declared slug doesn't match the path-derived one. Per PR #392 spec,
+  //    gbrain derives slug from path; the field shouldn't be in frontmatter.
+  if (opts?.filePath) {
+    const expectedSlug = slugifyPath(opts.filePath);
+    // Use the (possibly partially-fixed) working content to detect whether
+    // the slug field is present and mismatched.
+    const re = /^slug:\s*(.+?)\s*$/m;
+    const m = working.match(re);
+    if (m && m[1].replace(/^["']|["']$/g, '') !== expectedSlug) {
+      working = working.replace(re, '').replace(/\n{3,}/g, '\n\n');
+      fixes.push({
+        code: 'SLUG_MISMATCH',
+        description: `Removed mismatched slug field (was "${m[1]}", expected "${expectedSlug}")`,
+      });
+    }
+  }
+
+  return { content: working, fixes };
+}
+
+// ---------------------------------------------------------------------------
+// writeBrainPage — path-guarded write with .bak backup
+// ---------------------------------------------------------------------------
+
+export class BrainWriterError extends Error {
+  code: string;
+  hint?: string;
+  constructor(code: string, message: string, hint?: string) {
+    super(message);
+    this.name = 'BrainWriterError';
+    this.code = code;
+    this.hint = hint;
+  }
+}
+
+/**
+ * Path-guarded brain page writer. Always writes `<filePath>.bak` before any
+ * in-place mutation (the contract that replaces git-tree-clean for non-git
+ * brain repos). Throws BrainWriterError if filePath is not under sourcePath.
+ */
+export function writeBrainPage(
+  filePath: string,
+  content: string,
+  opts: { sourcePath: string; autoFix?: boolean },
+): { fixes: AuditFix[] } {
+  const resolvedSource = resolve(opts.sourcePath);
+  const resolvedTarget = resolve(filePath);
+  if (resolvedTarget !== resolvedSource && !resolvedTarget.startsWith(resolvedSource + '/')) {
+    throw new BrainWriterError(
+      'PATH_OUTSIDE_SOURCE',
+      `writeBrainPage: ${filePath} is not under ${opts.sourcePath}`,
+      'Pass --source <id> matching the source the file lives in.',
+    );
+  }
+
+  let toWrite = content;
+  let fixes: AuditFix[] = [];
+  if (opts.autoFix) {
+    const result = autoFixFrontmatter(content, { filePath });
+    toWrite = result.content;
+    fixes = result.fixes;
+  }
+
+  if (existsSync(filePath)) {
+    copyFileSync(filePath, filePath + '.bak');
+  } else {
+    mkdirSync(dirname(filePath), { recursive: true });
+  }
+  writeFileSync(filePath, toWrite, 'utf8');
+  return { fixes };
+}
+
+// ---------------------------------------------------------------------------
+// scanBrainSources
+// ---------------------------------------------------------------------------
+
+interface SourceRow {
+  id: string;
+  local_path: string | null;
+}
+
+export interface ScanOpts {
+  /** Limit scan to one source. When omitted, all registered sources with a
+   *  local_path are scanned. */
+  sourceId?: string;
+  onProgress?: ProgressReporter;
+  signal?: AbortSignal;
+}
+
+export async function scanBrainSources(
+  engine: BrainEngine,
+  opts: ScanOpts = {},
+): Promise<AuditReport> {
+  const sources = await listSources(engine, opts.sourceId);
+  const totals: Partial<Record<ParseValidationCode, number>> = {};
+  const perSource: PerSourceReport[] = [];
+  let grandTotal = 0;
+
+  for (const src of sources) {
+    if (opts.signal?.aborted) break;
+    if (!src.local_path) continue;
+    if (!existsSync(src.local_path)) {
+      // Source registered but path is missing on disk; surface as a zero-row
+      // entry with a synthetic SCAN_PATH_MISSING note via warn-and-skip.
+      perSource.push({
+        source_id: src.id,
+        source_path: src.local_path,
+        total: 0,
+        errors_by_code: {},
+        sample: [],
+      });
+      continue;
+    }
+    const report = scanOneSource(src.id, src.local_path, opts);
+    perSource.push(report);
+    grandTotal += report.total;
+    for (const [code, n] of Object.entries(report.errors_by_code)) {
+      const k = code as ParseValidationCode;
+      totals[k] = (totals[k] ?? 0) + (n as number);
+    }
+  }
+
+  return {
+    ok: grandTotal === 0,
+    total: grandTotal,
+    errors_by_code: totals,
+    per_source: perSource,
+    scanned_at: new Date().toISOString(),
+  };
+}
+
+function scanOneSource(
+  sourceId: string,
+  sourcePath: string,
+  opts: ScanOpts,
+): PerSourceReport {
+  const errorsByCode: Partial<Record<ParseValidationCode, number>> = {};
+  const sample: PerSourceReport['sample'] = [];
+  const rootResolved = resolve(sourcePath);
+  let scanned = 0;
+  let total = 0;
+
+  walkDir(rootResolved, (absPath) => {
+    if (opts.signal?.aborted) return false;
+    const relPath = relative(rootResolved, absPath);
+    if (!isSyncable(relPath, { strategy: 'markdown' })) return true;
+    scanned++;
+    let content: string;
+    try {
+      content = readFileSync(absPath, 'utf8');
+    } catch {
+      return true; // skip unreadable
+    }
+    const expectedSlug = slugifyPath(relPath);
+    const parsed = parseMarkdown(content, relPath, { validate: true, expectedSlug });
+    const errs = parsed.errors ?? [];
+    if (errs.length > 0) {
+      total += errs.length;
+      const codes: ParseValidationCode[] = [];
+      for (const e of errs) {
+        errorsByCode[e.code] = (errorsByCode[e.code] ?? 0) + 1;
+        codes.push(e.code);
+      }
+      if (sample.length < SAMPLE_PER_SOURCE) {
+        sample.push({ path: relPath, codes });
+      }
+    }
+    if (opts.onProgress && scanned % 50 === 0) {
+      opts.onProgress.tick(50);
+    }
+    return true;
+  });
+
+  if (opts.onProgress) {
+    opts.onProgress.heartbeat(`scanned ${scanned} pages in ${sourceId}`);
+  }
+
+  return {
+    source_id: sourceId,
+    source_path: sourcePath,
+    total,
+    errors_by_code: errorsByCode,
+    sample,
+  };
+}
+
+/** Recursive directory walker with symlink-loop protection (via lstat).
+ *  Calls `visit` for each regular file. Returning false from `visit` stops
+ *  the walk. Skips entries lstat reports as symlinks (sync's no-symlink
+ *  policy). */
+function walkDir(root: string, visit: (absPath: string) => boolean | void): void {
+  const stack: string[] = [root];
+  const visited = new Set<string>();
+  while (stack.length > 0) {
+    const dir = stack.pop()!;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      const full = join(dir, name);
+      let st: ReturnType<typeof lstatSync>;
+      try {
+        st = lstatSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isSymbolicLink()) continue; // matches sync's no-symlink policy
+      if (st.isDirectory()) {
+        const real = resolve(full);
+        if (visited.has(real)) continue;
+        visited.add(real);
+        stack.push(full);
+      } else if (st.isFile()) {
+        const result = visit(full);
+        if (result === false) return;
+      }
+    }
+  }
+}
+
+async function listSources(engine: BrainEngine, sourceId?: string): Promise<SourceRow[]> {
+  if (sourceId) {
+    const rows = await engine.executeRaw<SourceRow>(
+      `SELECT id, local_path FROM sources WHERE id = $1`,
+      [sourceId],
+    );
+    return rows;
+  }
+  return engine.executeRaw<SourceRow>(
+    `SELECT id, local_path FROM sources WHERE local_path IS NOT NULL ORDER BY id`,
+  );
+}

src/core/cycle.ts

@@ -140,6 +140,14 @@ export interface CycleOpts {
    * + refreshes the cycle-lock-table TTL.
    */
   yieldBetweenPhases?: () => Promise<void>;
+  /**
+   * AbortSignal from the Minions worker. When aborted (timeout, cancel,
+   * lock-loss), runCycle bails between phases and returns a 'failed' report
+   * instead of running the next phase. Without this, a timed-out
+   * autopilot-cycle handler ignores the abort and runs until the worker
+   * wedges (the 98-waiting-0-active incident on 2026-04-24).
+   */
+  signal?: AbortSignal;
 }
 
 // ─── Lock primitives ───────────────────────────────────────────────
@@ -344,6 +352,20 @@ async function safeYield(hook?: () => Promise<void>) {
   }
 }
 
+/**
+ * Check if the abort signal has fired. Called between phases so that a
+ * timed-out Minions job bails promptly instead of grinding through all
+ * remaining phases while the worker thinks it's still at capacity.
+ */
+function checkAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    const reason = signal.reason instanceof Error
+      ? signal.reason.message
+      : String(signal.reason || 'aborted');
+    throw new Error(`[cycle] aborted between phases: ${reason}`);
+  }
+}
+
 // ─── Phase runners ─────────────────────────────────────────────────
 
 async function runPhaseLint(brainDir: string, dryRun: boolean): Promise<PhaseResult> {
@@ -416,19 +438,55 @@ async function runPhaseBacklinks(brainDir: string, dryRun: boolean): Promise<Pha
   }
 }
 
+/** Extended sync result that also carries the changed slug list for downstream phases. */
+interface SyncPhaseResult extends PhaseResult {
+  /** Slugs that sync added or modified. Used by extract for incremental processing. */
+  pagesAffected?: string[];
+}
+
+/**
+ * Resolve the source id for a brain directory by looking up the sources
+ * table. Returns undefined when no registered source matches (falls back
+ * to pre-v0.18 global config.sync.* keys).
+ */
+async function resolveSourceForDir(
+  engine: BrainEngine,
+  brainDir: string,
+): Promise<string | undefined> {
+  try {
+    const rows = await engine.executeRaw<{ id: string }>(
+      `SELECT id FROM sources WHERE local_path = $1 LIMIT 1`,
+      [brainDir],
+    );
+    return rows[0]?.id;
+  } catch {
+    // sources table might not exist on very old brains — fall through.
+    return undefined;
+  }
+}
+
 async function runPhaseSync(
   engine: BrainEngine,
   brainDir: string,
   dryRun: boolean,
   pull: boolean,
-): Promise<PhaseResult> {
+  willRunExtractPhase: boolean,
+): Promise<SyncPhaseResult> {
   try {
     const { performSync } = await import('../commands/sync.ts');
+    // Resolve the per-source id so sync reads source-scoped last_commit
+    // instead of the global config key. The global key can drift out of
+    // git history (force push, GC) causing a full reimport of all files.
+    const sourceId = await resolveSourceForDir(engine, brainDir);
     const result = await performSync(engine, {
       repoPath: brainDir,
+      sourceId,
       dryRun,
       noPull: !pull,
-      noEmbed: true, // embed is a separate phase
+      noEmbed: true,                       // embed is a separate phase
+      noExtract: willRunExtractPhase,      // dedupe ONLY when cycle's extract phase will also run.
+                                           // If extract isn't scheduled (e.g. `gbrain dream --phase sync`),
+                                           // sync's inline extract still runs to preserve prior behavior.
     });
     const syncedCount = result.added + result.modified;
     return {
@@ -448,6 +506,7 @@ async function runPhaseSync(
         syncStatus: result.status,
         dryRun,
       },
+      pagesAffected: result.pagesAffected,
     };
   } catch (e) {
     return {
@@ -465,6 +524,7 @@ async function runPhaseExtract(
   engine: BrainEngine,
   brainDir: string,
   dryRun: boolean,
+  changedSlugs?: string[],
 ): Promise<PhaseResult> {
   try {
     const { runExtractCore } = await import('../commands/extract.ts');
@@ -480,15 +540,29 @@ async function runPhaseExtract(
         details: { dryRun: true, reason: 'no_dry_run_support' },
       };
     }
-    const result = await runExtractCore(engine, { mode: 'all', dir: brainDir });
+    // Incremental path: if sync told us which slugs changed, only extract those.
+    // On a 54K-page brain this turns a 10-minute full walk into a sub-second pass.
+    const result = await runExtractCore(engine, {
+      mode: 'all',
+      dir: brainDir,
+      slugs: changedSlugs,  // undefined = full walk (first run / manual)
+    });
     const linksCreated = result?.links_created ?? 0;
     const timelineCreated = result?.timeline_entries_created ?? 0;
+    const incremental = changedSlugs !== undefined;
     return {
       phase: 'extract',
       status: 'ok',
       duration_ms: 0,
-      summary: `${linksCreated} link(s), ${timelineCreated} timeline entries`,
-      details: { linksCreated, timelineCreated, pages_processed: result?.pages_processed ?? 0 },
+      summary: incremental
+        ? `${linksCreated} link(s), ${timelineCreated} timeline entries (incremental: ${changedSlugs.length} slugs)`
+        : `${linksCreated} link(s), ${timelineCreated} timeline entries`,
+      details: {
+        linksCreated, timelineCreated,
+        pages_processed: result?.pages_processed ?? 0,
+        incremental,
+        ...(incremental ? { slugs_targeted: changedSlugs.length } : {}),
+      },
     };
   } catch (e) {
     return {
@@ -644,6 +718,7 @@ export async function runCycle(
   try {
     // ── Phase 1: lint ────────────────────────────────────────────
     if (phases.includes('lint')) {
+      checkAborted(opts.signal);
       progress.start('cycle.lint');
       const { result, duration_ms } = await timePhase(() => runPhaseLint(opts.brainDir, dryRun));
       result.duration_ms = duration_ms;
@@ -654,6 +729,7 @@ export async function runCycle(
 
     // ── Phase 2: backlinks ──────────────────────────────────────
     if (phases.includes('backlinks')) {
+      checkAborted(opts.signal);
       progress.start('cycle.backlinks');
       const { result, duration_ms } = await timePhase(() => runPhaseBacklinks(opts.brainDir, dryRun));
       result.duration_ms = duration_ms;
@@ -663,7 +739,10 @@ export async function runCycle(
     }
 
     // ── Phase 3: sync ───────────────────────────────────────────
+    // Track which slugs sync touched so extract can run incrementally.
+    let syncPagesAffected: string[] | undefined;
     if (phases.includes('sync')) {
+      checkAborted(opts.signal);
       if (!engine) {
         phaseResults.push({
           phase: 'sync',
@@ -674,8 +753,10 @@ export async function runCycle(
         });
       } else {
         progress.start('cycle.sync');
-        const { result, duration_ms } = await timePhase(() => runPhaseSync(engine, opts.brainDir, dryRun, pull));
+        const { result, duration_ms } = await timePhase(() => runPhaseSync(engine, opts.brainDir, dryRun, pull, phases.includes('extract')));
         result.duration_ms = duration_ms;
+        // Capture changed slugs for incremental extract.
+        syncPagesAffected = (result as SyncPhaseResult).pagesAffected;
         phaseResults.push(result);
         progress.finish();
       }
@@ -684,6 +765,7 @@ export async function runCycle(
 
     // ── Phase 4: extract ────────────────────────────────────────
     if (phases.includes('extract')) {
+      checkAborted(opts.signal);
       if (!engine) {
         phaseResults.push({
           phase: 'extract',
@@ -693,8 +775,11 @@ export async function runCycle(
           details: { reason: 'no_database' },
         });
       } else {
+        // Pass changed slugs from sync for incremental extract.
+        // If sync didn't run (phases exclude it) or failed, syncPagesAffected
+        // is undefined → extract falls back to full walk (safe default).
         progress.start('cycle.extract');
-        const { result, duration_ms } = await timePhase(() => runPhaseExtract(engine, opts.brainDir, dryRun));
+        const { result, duration_ms } = await timePhase(() => runPhaseExtract(engine, opts.brainDir, dryRun, syncPagesAffected));
         result.duration_ms = duration_ms;
         phaseResults.push(result);
         progress.finish();
@@ -704,6 +789,7 @@ export async function runCycle(
 
     // ── Phase 5: embed ──────────────────────────────────────────
     if (phases.includes('embed')) {
+      checkAborted(opts.signal);
       if (!engine) {
         phaseResults.push({
           phase: 'embed',
@@ -724,6 +810,7 @@ export async function runCycle(
 
     // ── Phase 6: orphans ────────────────────────────────────────
     if (phases.includes('orphans')) {
+      checkAborted(opts.signal);
       if (!engine) {
         phaseResults.push({
           phase: 'orphans',

src/core/db.ts

@@ -1,6 +1,7 @@
 import postgres from 'postgres';
 import { GBrainError, type EngineConfig } from './types.ts';
 import { SCHEMA_SQL } from './schema-embedded.ts';
+import type { BrainEngine } from './engine.ts';
 
 let sql: ReturnType<typeof postgres> | null = null;
 let connectedUrl: string | null = null;
@@ -72,26 +73,78 @@ export function resolvePoolSize(explicit?: number): number {
 }
 
 /**
- * Apply session-level defaults to a fresh connection. Called from both
- * the module-level `connect()` singleton and the PostgresEngine
- * instance-level pool so the idle-in-transaction session timeout is set
- * uniformly.
+ * Session-level GUCs applied to every new backend connection. Prevents
+ * orphan pgbouncer sessions from holding locks or running queries
+ * indefinitely when the postgres.js client disconnects mid-transaction
+ * (typical cause: autopilot SIGKILL'd by launchd, worker crash-loop,
+ * or transient network drop).
  *
- * `idle_in_transaction_session_timeout = 5 min` was the v0.18.0 field
- * report's headline production issue: a 24-hour idle connection was
- * holding a lock on `pages` and blocking all DDL. 5 minutes is generous
- * for any legitimate transaction but catches crashed writers. The GUC
- * is session-scoped (safe for shared pools — no cross-statement leak).
+ * Observed failure mode these prevent: a single autopilot UPDATE on
+ * `minion_jobs.lock_until` left a pooler backend in `state='active'`
+ * / `wait_event='ClientRead'` for 24h+, holding a RowExclusiveLock
+ * that blocked every subsequent `ALTER TABLE minion_jobs ...`.
  *
- * Wrapped in try/catch because some managed Postgres tenants restrict
- * SET on the GUC; non-fatal if it fails.
+ * Defaults are conservative (chosen not to interfere with bulk work
+ * like long-running embed passes or CREATE INDEX on large tables):
+ *   - statement_timeout = '5min'
+ *   - idle_in_transaction_session_timeout = '5min' (matches v0.18.0
+ *     posture; #363's original 2min default was tightened to 5min on
+ *     merge with v0.21.0's setSessionDefaults to avoid regressing
+ *     long-running embed passes)
+ *
+ * Override per-GUC with env vars:
+ *   - GBRAIN_STATEMENT_TIMEOUT
+ *   - GBRAIN_IDLE_TX_TIMEOUT
+ *   - GBRAIN_CLIENT_CHECK_INTERVAL (Postgres 14+; empty default - opt-in
+ *     only since older self-hosted Postgres rejects this startup param)
+ *
+ * Set any env var to '0' or 'off' to disable that GUC entirely.
+ *
+ * Delivered via postgres.js's `connection` option, which sends these as
+ * startup parameters in the initial connection packet. Works correctly
+ * with PgBouncer session mode AND transaction mode: startup parameters
+ * pass through to the backend on connection creation and persist for the
+ * backend's lifetime (unlike `SET` commands which transaction-mode
+ * PgBouncer strips between transactions).
+ *
+ * Supersedes the v0.21.0 `setSessionDefaults(sql)` helper, which used
+ * a post-pool `SET` command. That approach is unreliable in PgBouncer
+ * transaction mode (transaction-mode poolers strip session-state SETs
+ * between transactions); startup parameters are durable.
  */
-export async function setSessionDefaults(sql: ReturnType<typeof postgres>): Promise<void> {
-  try {
-    await sql`SET idle_in_transaction_session_timeout = '300000'`;
-  } catch {
-    // Non-fatal: some managed Postgres may restrict this GUC
-  }
+const DEFAULT_STATEMENT_TIMEOUT = '5min';
+const DEFAULT_IDLE_TX_TIMEOUT = '5min';
+
+export function resolveSessionTimeouts(): Record<string, string> {
+  const out: Record<string, string> = {};
+  const add = (envKey: string, gucKey: string, defaultVal: string) => {
+    const raw = process.env[envKey];
+    if (raw === '0' || raw === 'off') return; // explicitly disabled
+    const val = raw ?? defaultVal;
+    if (val) out[gucKey] = val;
+  };
+  add('GBRAIN_STATEMENT_TIMEOUT', 'statement_timeout', DEFAULT_STATEMENT_TIMEOUT);
+  add('GBRAIN_IDLE_TX_TIMEOUT', 'idle_in_transaction_session_timeout', DEFAULT_IDLE_TX_TIMEOUT);
+  // client_connection_check_interval is opt-in: Postgres 14+ only, and some
+  // managed pooler tiers reject unknown startup parameters. Users can enable
+  // it explicitly once they know their Postgres version supports it.
+  add('GBRAIN_CLIENT_CHECK_INTERVAL', 'client_connection_check_interval', '');
+  return out;
+}
+
+/**
+ * Backward-compat shim for v0.21.0's `setSessionDefaults` callers.
+ * The current implementation no-ops because session timeouts are now
+ * applied at connection-startup time via `resolveSessionTimeouts()` +
+ * postgres.js's `connection` option (more durable across PgBouncer
+ * transaction mode).
+ *
+ * Kept as a callable function so existing call sites in `connect()` and
+ * `PostgresEngine.connect()` don't need to be touched on the merge —
+ * the work has already happened by the time this function would run.
+ */
+export async function setSessionDefaults(_sql: ReturnType<typeof postgres>): Promise<void> {
+  // No-op: timeouts are now applied as startup parameters in resolveSessionTimeouts().
 }
 
 export function getConnection(): ReturnType<typeof postgres> {
@@ -125,6 +178,7 @@ export async function connect(config: EngineConfig): Promise<void> {
 
   try {
     const prepare = resolvePrepare(url);
+    const timeouts = resolveSessionTimeouts();
     const opts: Record<string, unknown> = {
       max: resolvePoolSize(),
       idle_timeout: 20,
@@ -134,6 +188,9 @@ export async function connect(config: EngineConfig): Promise<void> {
         bigint: postgres.BigInt,
       },
     };
+    if (Object.keys(timeouts).length > 0) {
+      opts.connection = timeouts;
+    }
     if (typeof prepare === 'boolean') {
       opts.prepare = prepare;
       if (!prepare) {
@@ -186,3 +243,56 @@ export async function withTransaction<T>(fn: (tx: ReturnType<typeof postgres>) =
     return fn(tx as unknown as ReturnType<typeof postgres>);
   }) as Promise<T>;
 }
+
+const RETRYABLE_DB_CONNECT_PATTERNS = [
+  /password authentication failed/i,
+  /connection refused/i,
+  /the database system is starting up/i,
+  /Connection terminated unexpectedly/i,
+  /ECONNRESET/i,
+];
+
+export function isRetryableDbConnectError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (!msg) return false;
+  return RETRYABLE_DB_CONNECT_PATTERNS.some(p => p.test(msg));
+}
+
+export interface ConnectWithRetryOpts {
+  attempts?: number;
+  baseDelayMs?: number;
+  noRetry?: boolean;
+  log?: (line: string) => void;
+}
+
+export async function connectWithRetry(
+  engine: BrainEngine,
+  config: EngineConfig & { poolSize?: number },
+  opts: ConnectWithRetryOpts = {},
+): Promise<void> {
+  const noRetry = opts.noRetry ?? (process.env.GBRAIN_NO_RETRY_CONNECT === '1');
+  const attempts = noRetry ? 1 : (opts.attempts ?? 3);
+  const baseDelayMs = opts.baseDelayMs ?? 1000;
+  const log = opts.log ?? ((line) => console.warn(line));
+
+  let lastErr: unknown;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      await engine.connect(config);
+      return;
+    } catch (e: unknown) {
+      lastErr = e;
+      const retryable = isRetryableDbConnectError(e);
+      const isLast = i === attempts - 1;
+      if (!retryable || isLast) {
+        throw e;
+      }
+      const delay = baseDelayMs * Math.pow(2, i);
+      const msg = e instanceof Error ? e.message : String(e);
+      log(`[connect] attempt ${i + 1} failed (${msg.slice(0, 80)}), retrying in ${delay}ms`);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  // Unreachable, but TS needs the throw.
+  throw lastErr;
+}

src/core/engine.ts

@@ -1,6 +1,6 @@
 import type {
   Page, PageInput, PageFilters,
-  Chunk, ChunkInput,
+  Chunk, ChunkInput, StaleChunkRow,
   SearchResult, SearchOpts,
   Link, GraphNode, GraphPath,
   TimelineEntry, TimelineInput, TimelineOpts,
@@ -133,6 +133,21 @@ export interface BrainEngine {
   // Chunks
   upsertChunks(slug: string, chunks: ChunkInput[]): Promise<void>;
   getChunks(slug: string): Promise<Chunk[]>;
+  /**
+   * Count chunks across the entire brain where embedded_at IS NULL.
+   * Pre-flight short-circuit for `embed --stale` so a 100%-embedded brain
+   * does no further work after a single SELECT count(*) (~50 bytes wire).
+   */
+  countStaleChunks(): Promise<number>;
+  /**
+   * Return every chunk where embedded_at IS NULL, with the metadata needed
+   * to call embedBatch + upsertChunks. The `embedding` column is omitted
+   * by design — stale rows have NULL embeddings, so shipping them wastes
+   * wire bytes for no gain. Caller groups by slug, embeds, and re-upserts.
+   *
+   * Bounded by an internal LIMIT of 100000 to mirror listPages.
+   */
+  listStaleChunks(): Promise<StaleChunkRow[]>;
   deleteChunks(slug: string): Promise<void>;
 
   // Links

src/core/markdown.ts

@@ -2,6 +2,29 @@ import matter from 'gray-matter';
 import type { PageType } from './types.ts';
 import { slugifyPath } from './sync.ts';
 
+export type ParseValidationCode =
+  | 'MISSING_OPEN'
+  | 'MISSING_CLOSE'
+  | 'YAML_PARSE'
+  | 'SLUG_MISMATCH'
+  | 'NULL_BYTES'
+  | 'NESTED_QUOTES'
+  | 'EMPTY_FRONTMATTER';
+
+export interface ParseValidationError {
+  code: ParseValidationCode;
+  message: string;
+  line?: number;
+}
+
+export interface ParseOpts {
+  /** When true, errors[] is populated. Existing callers unaffected. */
+  validate?: boolean;
+  /** When validate is true and frontmatter has a `slug:` field that doesn't
+   *  match expectedSlug, emits SLUG_MISMATCH. */
+  expectedSlug?: string;
+}
+
 export interface ParsedMarkdown {
   frontmatter: Record<string, unknown>;
   compiled_truth: string;
@@ -10,6 +33,8 @@ export interface ParsedMarkdown {
   type: PageType;
   title: string;
   tags: string[];
+  /** Present iff opts.validate. Empty array means no errors. */
+  errors?: ParseValidationError[];
 }
 
 /**
@@ -33,26 +58,53 @@ export interface ParsedMarkdown {
  * heading (backward-compat for existing files). A bare `---` in body text
  * is treated as a markdown horizontal rule, not a timeline separator.
  */
-export function parseMarkdown(content: string, filePath?: string): ParsedMarkdown {
-  const { data: frontmatter, content: body } = matter(content);
+export function parseMarkdown(
+  content: string,
+  filePath?: string,
+  opts?: ParseOpts,
+): ParsedMarkdown {
+  const errors: ParseValidationError[] = [];
+
+  // gray-matter is forgiving: it returns empty data + original content for
+  // pretty much any input. The validation surface below catches the cases
+  // it silently swallows. Validation only runs when opts.validate is true,
+  // so existing callers are unaffected.
+  let parsed: ReturnType<typeof matter> | null = null;
+  let yamlParseError: Error | null = null;
+  try {
+    parsed = matter(content);
+  } catch (e) {
+    yamlParseError = e as Error;
+  }
+
+  if (opts?.validate) {
+    collectValidationErrors(content, errors, {
+      yamlParseError,
+      expectedSlug: opts.expectedSlug,
+      parsedFrontmatter: parsed?.data ?? {},
+    });
+  }
+
+  // When YAML parsing failed (rare; gray-matter is forgiving), fall back to
+  // empty frontmatter + raw content as the body so non-validate callers still
+  // get a usable shape.
+  const frontmatter = (parsed?.data ?? {}) as Record<string, unknown>;
+  const body = parsed?.content ?? content;
 
-  // Split body at first standalone ---
   const { compiled_truth, timeline } = splitBody(body);
 
-  // Extract metadata from frontmatter
   const type = (frontmatter.type as PageType) || inferType(filePath);
   const title = (frontmatter.title as string) || inferTitle(filePath);
   const tags = extractTags(frontmatter);
   const slug = (frontmatter.slug as string) || inferSlug(filePath);
 
-  // Remove processed fields from frontmatter (they're stored as columns)
   const cleanFrontmatter = { ...frontmatter };
   delete cleanFrontmatter.type;
   delete cleanFrontmatter.title;
   delete cleanFrontmatter.tags;
   delete cleanFrontmatter.slug;
 
-  return {
+  const result: ParsedMarkdown = {
     frontmatter: cleanFrontmatter,
     compiled_truth: compiled_truth.trim(),
     timeline: timeline.trim(),
@@ -61,6 +113,149 @@ export function parseMarkdown(content: string, filePath?: string): ParsedMarkdow
     title,
     tags,
   };
+  if (opts?.validate) result.errors = errors;
+  return result;
+}
+
+/**
+ * Inspect raw content for the 7 frontmatter validation classes that gray-matter
+ * silently accepts. Mutates `errors` in place. The order of checks is
+ * deliberate: cheap byte-level checks first, then structural checks, then
+ * YAML-parse-dependent checks.
+ */
+function collectValidationErrors(
+  content: string,
+  errors: ParseValidationError[],
+  ctx: {
+    yamlParseError: Error | null;
+    expectedSlug?: string;
+    parsedFrontmatter: Record<string, unknown>;
+  },
+): void {
+  // 1. NULL_BYTES — binary corruption indicator.
+  const nullIdx = content.indexOf('\x00');
+  if (nullIdx >= 0) {
+    const line = content.slice(0, nullIdx).split('\n').length;
+    errors.push({
+      code: 'NULL_BYTES',
+      message: 'Content contains null bytes (likely binary corruption)',
+      line,
+    });
+  }
+
+  // 2. MISSING_OPEN — first non-empty line must be `---`.
+  const lines = content.split('\n');
+  let firstNonEmpty = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().length > 0) {
+      firstNonEmpty = i;
+      break;
+    }
+  }
+  if (firstNonEmpty === -1) {
+    // Empty file: treat as MISSING_OPEN. Don't run other structural checks.
+    errors.push({
+      code: 'MISSING_OPEN',
+      message: 'File is empty or whitespace-only; expected frontmatter starting with ---',
+      line: 1,
+    });
+    return;
+  }
+  if (lines[firstNonEmpty].trim() !== '---') {
+    errors.push({
+      code: 'MISSING_OPEN',
+      message: 'Frontmatter must start with --- on the first non-empty line',
+      line: firstNonEmpty + 1,
+    });
+    // Without an opener we can't reason about MISSING_CLOSE / EMPTY_FRONTMATTER
+    // / NESTED_QUOTES inside frontmatter. Stop structural checks here.
+    return;
+  }
+
+  // 3. MISSING_CLOSE — find the next `---` after the opener. If a markdown
+  //    heading appears before it, that's a strong signal the closing
+  //    delimiter is missing (the heading was meant to be in the body).
+  let closeLine = -1;
+  let headingBeforeClose = -1;
+  for (let i = firstNonEmpty + 1; i < lines.length; i++) {
+    const t = lines[i].trim();
+    if (t === '---') {
+      closeLine = i;
+      break;
+    }
+    if (/^#{1,6}\s/.test(t) && headingBeforeClose === -1) {
+      headingBeforeClose = i;
+    }
+  }
+  if (closeLine === -1) {
+    errors.push({
+      code: 'MISSING_CLOSE',
+      message:
+        headingBeforeClose >= 0
+          ? `No closing --- before heading at line ${headingBeforeClose + 1}`
+          : 'No closing --- delimiter found',
+      line: headingBeforeClose >= 0 ? headingBeforeClose + 1 : firstNonEmpty + 1,
+    });
+    return;
+  }
+  if (headingBeforeClose >= 0 && headingBeforeClose < closeLine) {
+    errors.push({
+      code: 'MISSING_CLOSE',
+      message: `Heading at line ${headingBeforeClose + 1} found inside frontmatter zone (closing --- comes after)`,
+      line: headingBeforeClose + 1,
+    });
+  }
+
+  // 4. EMPTY_FRONTMATTER — open and close present but nothing meaningful between.
+  const fmBody = lines.slice(firstNonEmpty + 1, closeLine).join('\n').trim();
+  if (fmBody.length === 0) {
+    errors.push({
+      code: 'EMPTY_FRONTMATTER',
+      message: 'Frontmatter block is empty',
+      line: firstNonEmpty + 1,
+    });
+  }
+
+  // 5. NESTED_QUOTES — common breakage pattern: `title: "Name "Nick" Last"`.
+  //    Detect any frontmatter `key: ...` line whose value contains 3 or more
+  //    unescaped double-quote characters. A clean quoted value has 2.
+  for (let i = firstNonEmpty + 1; i < closeLine; i++) {
+    const line = lines[i];
+    const m = line.match(/^\s*[A-Za-z_][\w-]*\s*:\s*(.*)$/);
+    if (!m) continue;
+    const value = m[1];
+    let count = 0;
+    for (let j = 0; j < value.length; j++) {
+      if (value[j] === '"' && (j === 0 || value[j - 1] !== '\\')) count++;
+    }
+    if (count >= 3) {
+      errors.push({
+        code: 'NESTED_QUOTES',
+        message: 'Nested double quotes in YAML value (use single quotes for the outer)',
+        line: i + 1,
+      });
+    }
+  }
+
+  // 6. YAML_PARSE — gray-matter threw.
+  if (ctx.yamlParseError) {
+    errors.push({
+      code: 'YAML_PARSE',
+      message: `YAML parse failed: ${ctx.yamlParseError.message}`,
+      line: firstNonEmpty + 1,
+    });
+  }
+
+  // 7. SLUG_MISMATCH — only when expectedSlug was provided and a slug field exists.
+  if (ctx.expectedSlug && typeof ctx.parsedFrontmatter.slug === 'string') {
+    const declared = ctx.parsedFrontmatter.slug as string;
+    if (declared !== ctx.expectedSlug) {
+      errors.push({
+        code: 'SLUG_MISMATCH',
+        message: `Frontmatter slug "${declared}" does not match path-derived slug "${ctx.expectedSlug}"`,
+      });
+    }
+  }
 }
 
 /**

src/core/minions/supervisor.ts

@@ -75,6 +75,9 @@ export interface SupervisorOpts {
   allowShellJobs: boolean;
   /** JSON mode: emit JSONL events on stderr, reserve stdout for data payloads. Default: false. */
   json: boolean;
+  /** RSS threshold (MB) passed to the spawned worker as `--max-rss N`.
+   *  Default: 2048. Set to 0 to spawn the worker without a watchdog. */
+  maxRssMb: number;
   /** Optional event sink (Lane C audit writer). Called for every lifecycle event. */
   onEvent?: (event: SupervisorEmission) => void;
   /**
@@ -101,6 +104,7 @@ const DEFAULTS: Omit<SupervisorOpts, 'cliPath'> = {
   healthInterval: 60_000,
   allowShellJobs: false,
   json: false,
+  maxRssMb: 2048,
 };
 
 /** Calculate backoff: 1s, 2s, 4s, 8s, 16s, 32s, 60s cap. */
@@ -142,6 +146,7 @@ export class MinionSupervisor {
   private sigtermListener: (() => void) | null = null;
   private sigintListener: (() => void) | null = null;
   private lockAcquired = false;
+  private consecutiveHealthFailures = 0;
 
   constructor(engine: BrainEngine, opts: Partial<SupervisorOpts> & { cliPath: string }) {
     this.engine = engine;
@@ -410,6 +415,9 @@ export class MinionSupervisor {
         '--concurrency', String(this.opts.concurrency),
         '--queue', this.opts.queue,
       ];
+      if (this.opts.maxRssMb > 0) {
+        args.push('--max-rss', String(this.opts.maxRssMb));
+      }
 
       // Build child env. Explicit handling for GBRAIN_ALLOW_SHELL_JOBS:
       // inherit only when caller opts in, otherwise strip from the clone.
@@ -476,10 +484,26 @@ export class MinionSupervisor {
         }
 
         const exitReason = signal ? `signal ${signal}` : `code ${code ?? 'null'}`;
+
+        // Classify the likely cause for easier debugging
+        let likelyCause: string;
+        if (signal === 'SIGKILL') {
+          likelyCause = 'oom_or_external_kill';
+        } else if (signal === 'SIGTERM') {
+          likelyCause = 'graceful_shutdown';
+        } else if (code === 1) {
+          likelyCause = 'runtime_error';
+        } else if (code === 0) {
+          likelyCause = 'clean_exit';
+        } else {
+          likelyCause = 'unknown';
+        }
+
         this.emit('worker_exited', {
           code: code ?? null,
           signal: signal ?? null,
           reason: exitReason,
+          likely_cause: likelyCause,
           crash_count: this.crashCount,
           max_crashes: this.opts.maxCrashes,
           run_duration_ms: runDuration,
@@ -523,6 +547,9 @@ export class MinionSupervisor {
         [this.opts.queue],
       );
 
+      // Reset consecutive failure counter on successful health check
+      this.consecutiveHealthFailures = 0;
+
       const row = rows[0] ?? { stalled: '0', waiting: '0', last_completed: null };
       const stalledCount = parseInt(row.stalled ?? '0', 10);
       const waitingCount = parseInt(row.waiting ?? '0', 10);
@@ -561,11 +588,41 @@ export class MinionSupervisor {
         });
       }
     } catch (e) {
-      // Health check failures are non-fatal.
-      this.emit('health_error', {
-        error: e instanceof Error ? e.message : String(e),
-        queue: this.opts.queue,
-      });
+      this.consecutiveHealthFailures++;
+      const errMsg = e instanceof Error ? e.message : String(e);
+
+      if (this.consecutiveHealthFailures >= 3) {
+        // DB connection is likely dead. Emit a degraded warning.
+        this.emit('health_warn', {
+          reason: 'db_connection_degraded',
+          consecutive_failures: this.consecutiveHealthFailures,
+          error: errMsg,
+          queue: this.opts.queue,
+        });
+        // Attempt to reconnect the engine if it supports it
+        try {
+          if ('reconnect' in this.engine && typeof (this.engine as Record<string, unknown>).reconnect === 'function') {
+            await (this.engine as unknown as { reconnect(): Promise<void> }).reconnect();
+            this.consecutiveHealthFailures = 0;
+            this.emit('health_warn', {
+              reason: 'db_reconnected',
+              queue: this.opts.queue,
+            });
+          }
+        } catch (reconnErr) {
+          this.emit('health_error', {
+            error: `reconnect failed: ${reconnErr instanceof Error ? reconnErr.message : String(reconnErr)}`,
+            reconnect_failed: true,
+            queue: this.opts.queue,
+          });
+        }
+      } else {
+        // Non-fatal single failure
+        this.emit('health_error', {
+          error: errMsg,
+          queue: this.opts.queue,
+        });
+      }
     } finally {
       this.healthInFlight = false;
     }

src/core/minions/types.ts

@@ -160,6 +160,16 @@ export interface MinionWorkerOpts {
   stalledInterval?: number; // ms, default 30000
   maxStalledCount?: number; // default 1
   pollInterval?: number; // ms, default 5000 (for PGLite fallback)
+  /** RSS threshold in MB. When exceeded, worker triggers graceful shutdown
+   *  so a supervisor can respawn it. 0 or undefined = disabled. */
+  maxRssMb?: number;
+  /** Optional injection point for RSS readback. Defaults to
+   *  `() => process.memoryUsage().rss`. Tests inject deterministic sequences. */
+  getRss?: () => number;
+  /** Periodic RSS check interval in ms, default 60000. Catches the freeze
+   *  case where all concurrency slots are wedged with zero job completions
+   *  so the per-job check never fires. */
+  rssCheckInterval?: number;
 }
 
 // --- Job Context (passed to handlers) ---

src/core/minions/worker.ts

@@ -56,6 +56,11 @@ export class MinionWorker {
    *  deploy restart — they still get the full 30s cleanup race instead. */
   private shutdownAbort = new AbortController();
 
+  /** Cumulative jobs that finished (success or failure). Used in watchdog log lines. */
+  private jobsCompleted = 0;
+  /** Idempotency latch for gracefulShutdown — per-job and periodic check sites can race. */
+  private gracefulShutdownFired = false;
+
   private opts: Required<MinionWorkerOpts>;
 
   constructor(
@@ -73,6 +78,9 @@ export class MinionWorker {
       stalledInterval: opts?.stalledInterval ?? 30000,
       maxStalledCount: opts?.maxStalledCount ?? 1,
       pollInterval: opts?.pollInterval ?? 5000,
+      maxRssMb: opts?.maxRssMb ?? 0,
+      getRss: opts?.getRss ?? (() => process.memoryUsage().rss),
+      rssCheckInterval: opts?.rssCheckInterval ?? 60000,
     };
   }
 
@@ -136,6 +144,17 @@ export class MinionWorker {
       }
     }, this.opts.stalledInterval);
 
+    // Periodic RSS watchdog — closes the production-freeze regression where
+    // all concurrency slots are wedged with zero job completions, so the
+    // per-job check in executeJob().finally() never fires. Disabled when
+    // maxRssMb is 0 (default for bare `gbrain jobs work`; supervisor sets 2048).
+    let rssTimer: ReturnType<typeof setInterval> | null = null;
+    if (this.opts.maxRssMb > 0) {
+      rssTimer = setInterval(() => {
+        this.checkMemoryLimit('periodic');
+      }, this.opts.rssCheckInterval);
+    }
+
     try {
       while (this.running) {
         // Promote delayed jobs
@@ -181,6 +200,7 @@ export class MinionWorker {
       }
     } finally {
       clearInterval(stalledTimer);
+      if (rssTimer) clearInterval(rssTimer);
       process.removeListener('SIGTERM', shutdown);
       process.removeListener('SIGINT', shutdown);
 
@@ -257,6 +277,55 @@ export class MinionWorker {
     this.running = false;
   }
 
+  /** RSS watchdog. Called from the per-job finally and the periodic timer.
+   *  Idempotent: returns early if already not running or already shut down.
+   *  When threshold is exceeded, hands off to gracefulShutdown(). */
+  private checkMemoryLimit(source: 'post-job' | 'periodic'): void {
+    if (this.opts.maxRssMb <= 0) return;
+    if (!this.running) return;
+    if (this.gracefulShutdownFired) return;
+
+    let rss = 0;
+    try {
+      rss = this.opts.getRss();
+    } catch {
+      // process.memoryUsage() effectively cannot throw, but be safe.
+      return;
+    }
+    const rssMb = Math.round(rss / (1024 * 1024));
+    if (rssMb < this.opts.maxRssMb) return;
+
+    const ts = new Date().toISOString().slice(11, 19);
+    console.warn(
+      `[watchdog ${ts}] rss=${rssMb}MB threshold=${this.opts.maxRssMb}MB ` +
+      `jobs_completed=${this.jobsCompleted} source=${source} — draining`,
+    );
+    this.gracefulShutdown('watchdog');
+  }
+
+  /** Trigger a unified-style graceful shutdown. Fires shutdownAbort + per-job
+   *  aborts + running=false in that order so:
+   *  1. Shell handlers (and anything subscribed to ctx.shutdownSignal) start
+   *     their cleanup sequence (SIGTERM → 5s grace → SIGKILL on children).
+   *  2. Cooperative handlers see ctx.signal.aborted and bail instead of
+   *     waiting out the 30s drain.
+   *  3. Main loop exits at the top of the next iteration.
+   *  The existing 30s drain in start()'s finally then backstops genuinely
+   *  uninterruptible work. */
+  private gracefulShutdown(reason: string): void {
+    if (this.gracefulShutdownFired) return;
+    this.gracefulShutdownFired = true;
+    if (!this.shutdownAbort.signal.aborted) {
+      this.shutdownAbort.abort(new Error(reason));
+    }
+    for (const entry of this.inFlight.values()) {
+      if (!entry.abort.signal.aborted) {
+        entry.abort.abort(new Error(reason));
+      }
+    }
+    this.running = false;
+  }
+
   /** Launch a job as an independent in-flight promise. */
   private launchJob(job: MinionJob, lockToken: string): void {
     const abort = new AbortController();
@@ -277,12 +346,30 @@ export class MinionWorker {
     // The .finally clearTimeout below ensures process exit isn't delayed by a
     // dangling timer on normal completion.
     let timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+    let graceTimer: ReturnType<typeof setTimeout> | null = null;
     if (job.timeout_ms != null) {
       timeoutTimer = setTimeout(() => {
         if (!abort.signal.aborted) {
           console.warn(`Job ${job.id} (${job.name}) hit per-job timeout (${job.timeout_ms}ms), aborting`);
           abort.abort(new Error('timeout'));
         }
+        // Safety net: if the handler doesn't resolve within 30s after abort,
+        // force-evict from inFlight so the worker can pick up new jobs.
+        // Without this, a handler that ignores AbortSignal wedges the worker
+        // forever (the 98-waiting-0-active incident on 2026-04-24).
+        graceTimer = setTimeout(() => {
+          if (this.inFlight.has(job.id)) {
+            console.warn(
+              `Job ${job.id} (${job.name}) did not exit within 30s of abort. ` +
+              `Force-evicting from inFlight to unblock worker. ` +
+              `The handler is still running but the worker will claim new jobs.`
+            );
+            clearInterval(lockTimer);
+            this.inFlight.delete(job.id);
+            // Best-effort: mark as dead in DB so it doesn't get reclaimed
+            this.queue.failJob(job.id, lockToken, 'handler ignored abort signal (force-evicted)', 'dead').catch(() => {});
+          }
+        }, 30_000);
       }, job.timeout_ms);
     }
 
@@ -290,7 +377,10 @@ export class MinionWorker {
       .finally(() => {
         clearInterval(lockTimer);
         if (timeoutTimer) clearTimeout(timeoutTimer);
+        if (graceTimer) clearTimeout(graceTimer);
         this.inFlight.delete(job.id);
+        this.jobsCompleted += 1;
+        this.checkMemoryLimit('post-job');
       });
 
     this.inFlight.set(job.id, { job, lockToken, lockTimer, abort, promise });

src/core/pglite-engine.ts

@@ -9,7 +9,7 @@ import { PGLITE_SCHEMA_SQL } from './pglite-schema.ts';
 import { acquireLock, releaseLock, type LockHandle } from './pglite-lock.ts';
 import type {
   Page, PageInput, PageFilters, PageType,
-  Chunk, ChunkInput,
+  Chunk, ChunkInput, StaleChunkRow,
   SearchResult, SearchOpts,
   Link, GraphNode, GraphPath,
   TimelineEntry, TimelineInput, TimelineOpts,
@@ -20,6 +20,8 @@ import type {
   EngineConfig,
 } from './types.ts';
 import { validateSlug, contentHash, rowToPage, rowToChunk, rowToSearchResult } from './utils.ts';
+import { resolveBoostMap, resolveHardExcludes } from './search/source-boost.ts';
+import { buildSourceFactorCase, buildHardExcludeClause } from './search/sql-ranking.ts';
 
 type PGLiteDB = PGlite;
 
@@ -239,6 +241,12 @@ export class PGLiteEngine implements BrainEngine {
     // Fetch 3x to give dedup headroom, then page-dedup + re-limit.
     const innerLimit = Math.min(limit * 3, MAX_SEARCH_LIMIT * 3);
 
+    // Source-aware ranking (v0.22): see postgres-engine.ts for rationale.
+    const boostMap = resolveBoostMap();
+    const sourceFactorCase = buildSourceFactorCase('p.slug', boostMap, opts?.detail);
+    const hardExcludePrefixes = resolveHardExcludes(opts?.exclude_slug_prefixes, opts?.include_slug_prefixes);
+    const hardExcludeClause = buildHardExcludeClause('p.slug', hardExcludePrefixes);
+
     // v0.20.0 Cathedral II Layer 10 C1/C2: language + symbol-kind filters.
     const params: unknown[] = [query, innerLimit, limit, offset];
     let extraFilter = '';
@@ -256,13 +264,13 @@ export class PGLiteEngine implements BrainEngine {
          SELECT
            p.slug, p.id as page_id, p.title, p.type, p.source_id,
            cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
-           ts_rank(cc.search_vector, websearch_to_tsquery('english', $1)) AS score,
+           ts_rank(cc.search_vector, websearch_to_tsquery('english', $1)) * ${sourceFactorCase} AS score,
            CASE WHEN p.updated_at < (
              SELECT MAX(te.created_at) FROM timeline_entries te WHERE te.page_id = p.id
            ) THEN true ELSE false END AS stale
          FROM content_chunks cc
          JOIN pages p ON p.id = cc.page_id
-         WHERE cc.search_vector @@ websearch_to_tsquery('english', $1) ${detailFilter}${extraFilter}
+         WHERE cc.search_vector @@ websearch_to_tsquery('english', $1) ${detailFilter}${extraFilter} ${hardExcludeClause}
          ORDER BY score DESC
          LIMIT $2
        ),
@@ -301,6 +309,13 @@ export class PGLiteEngine implements BrainEngine {
       console.warn(`[gbrain] Warning: search limit clamped from ${opts.limit} to ${MAX_SEARCH_LIMIT}`);
     }
 
+    // Source-aware ranking applied here too — searchKeywordChunks is the
+    // chunk-grain anchor primitive that two-pass retrieval (Layer 7) uses.
+    const boostMap = resolveBoostMap();
+    const sourceFactorCase = buildSourceFactorCase('p.slug', boostMap, opts?.detail);
+    const hardExcludePrefixes = resolveHardExcludes(opts?.exclude_slug_prefixes, opts?.include_slug_prefixes);
+    const hardExcludeClause = buildHardExcludeClause('p.slug', hardExcludePrefixes);
+
     const params: unknown[] = [query, limit, offset];
     let extraFilter = '';
     if (opts?.language) {
@@ -316,13 +331,13 @@ export class PGLiteEngine implements BrainEngine {
       `SELECT
          p.slug, p.id as page_id, p.title, p.type, p.source_id,
          cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
-         ts_rank(cc.search_vector, websearch_to_tsquery('english', $1)) AS score,
+         ts_rank(cc.search_vector, websearch_to_tsquery('english', $1)) * ${sourceFactorCase} AS score,
          CASE WHEN p.updated_at < (
            SELECT MAX(te.created_at) FROM timeline_entries te WHERE te.page_id = p.id
          ) THEN true ELSE false END AS stale
        FROM content_chunks cc
        JOIN pages p ON p.id = cc.page_id
-       WHERE cc.search_vector @@ websearch_to_tsquery('english', $1) ${detailFilter}${extraFilter}
+       WHERE cc.search_vector @@ websearch_to_tsquery('english', $1) ${detailFilter}${extraFilter} ${hardExcludeClause}
        ORDER BY score DESC
        LIMIT $2 OFFSET $3`,
       params
@@ -341,7 +356,23 @@ export class PGLiteEngine implements BrainEngine {
       console.warn(`[gbrain] Warning: search limit clamped from ${opts.limit} to ${MAX_SEARCH_LIMIT}`);
     }
 
-    const params: unknown[] = [vecStr, limit, offset];
+    // Two-stage CTE (v0.22): pure-distance ORDER BY in inner CTE preserves
+    // HNSW; outer SELECT re-ranks by raw_score * source_factor over the
+    // narrow candidate pool. innerLimit scales with offset to preserve the
+    // pagination contract. See postgres-engine.ts searchVector for rationale.
+    const boostMap = resolveBoostMap();
+    // Outer SELECT references the aliased CTE column. Aliasing the CTE as `hc`
+    // disambiguates the correlated subquery (`te.page_id = hc.page_id`) from
+    // the inner column. Without the alias, an unqualified `page_id` in the
+    // subquery's WHERE would lexically resolve back to `te.page_id` itself
+    // and degrade to `te.page_id = te.page_id` (always true), making every
+    // result stale=true. Codex caught this in adversarial review.
+    const sourceFactorCaseOnSlug = buildSourceFactorCase('hc.slug', boostMap, opts?.detail);
+    const hardExcludePrefixes = resolveHardExcludes(opts?.exclude_slug_prefixes, opts?.include_slug_prefixes);
+    const hardExcludeClause = buildHardExcludeClause('p.slug', hardExcludePrefixes);
+    const innerLimit = offset + Math.max(limit * 5, 100);
+
+    const params: unknown[] = [vecStr, innerLimit, limit, offset];
     let extraFilter = '';
     if (opts?.language) {
       params.push(opts.language);
@@ -353,19 +384,28 @@ export class PGLiteEngine implements BrainEngine {
     }
 
     const { rows } = await this.db.query(
-      `SELECT
-        p.slug, p.id as page_id, p.title, p.type, p.source_id,
-        cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
-        1 - (cc.embedding <=> $1::vector) AS score,
-        CASE WHEN p.updated_at < (
-          SELECT MAX(te.created_at) FROM timeline_entries te WHERE te.page_id = p.id
-        ) THEN true ELSE false END AS stale
-      FROM content_chunks cc
-      JOIN pages p ON p.id = cc.page_id
-      WHERE cc.embedding IS NOT NULL ${detailFilter}${extraFilter}
-      ORDER BY cc.embedding <=> $1::vector
-      LIMIT $2
-      OFFSET $3`,
+      `WITH hnsw_candidates AS (
+         SELECT
+           p.slug, p.id as page_id, p.title, p.type, p.source_id, p.updated_at,
+           cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
+           1 - (cc.embedding <=> $1::vector) AS raw_score
+         FROM content_chunks cc
+         JOIN pages p ON p.id = cc.page_id
+         WHERE cc.embedding IS NOT NULL ${detailFilter}${extraFilter} ${hardExcludeClause}
+         ORDER BY cc.embedding <=> $1::vector
+         LIMIT $2
+       )
+       SELECT
+         hc.slug, hc.page_id, hc.title, hc.type, hc.source_id,
+         hc.chunk_id, hc.chunk_index, hc.chunk_text, hc.chunk_source,
+         hc.raw_score * ${sourceFactorCaseOnSlug} AS score,
+         CASE WHEN hc.updated_at < (
+           SELECT MAX(te.created_at) FROM timeline_entries te WHERE te.page_id = hc.page_id
+         ) THEN true ELSE false END AS stale
+       FROM hnsw_candidates hc
+       ORDER BY score DESC
+       LIMIT $3
+       OFFSET $4`,
       params
     );
 
@@ -451,6 +491,9 @@ export class PGLiteEngine implements BrainEngine {
       }
     }
 
+    // CONSISTENCY: when chunk_text changes and no new embedding is supplied, BOTH embedding AND
+    // embedded_at must reset to NULL so `embed --stale` correctly picks up the row for re-embedding.
+    // See postgres-engine.ts upsertChunks for the full rationale — pglite mirrors it for parity.
     await this.db.query(
       `INSERT INTO content_chunks ${cols} VALUES ${rowParts.join(', ')}
        ON CONFLICT (page_id, chunk_index) DO UPDATE SET
@@ -459,7 +502,10 @@ export class PGLiteEngine implements BrainEngine {
          embedding = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.embedding ELSE COALESCE(EXCLUDED.embedding, content_chunks.embedding) END,
          model = COALESCE(EXCLUDED.model, content_chunks.model),
          token_count = EXCLUDED.token_count,
-         embedded_at = COALESCE(EXCLUDED.embedded_at, content_chunks.embedded_at),
+         embedded_at = CASE
+           WHEN EXCLUDED.chunk_text != content_chunks.chunk_text AND EXCLUDED.embedding IS NULL THEN NULL
+           ELSE COALESCE(EXCLUDED.embedded_at, content_chunks.embedded_at)
+         END,
          language = EXCLUDED.language,
          symbol_name = EXCLUDED.symbol_name,
          symbol_type = EXCLUDED.symbol_type,
@@ -483,6 +529,29 @@ export class PGLiteEngine implements BrainEngine {
     return (rows as Record<string, unknown>[]).map(r => rowToChunk(r));
   }
 
+  async countStaleChunks(): Promise<number> {
+    const { rows } = await this.db.query(
+      `SELECT count(*)::int AS count
+         FROM content_chunks
+        WHERE embedding IS NULL`,
+    );
+    const count = (rows[0] as { count: number } | undefined)?.count ?? 0;
+    return Number(count);
+  }
+
+  async listStaleChunks(): Promise<StaleChunkRow[]> {
+    const { rows } = await this.db.query(
+      `SELECT p.slug, cc.chunk_index, cc.chunk_text, cc.chunk_source,
+              cc.model, cc.token_count
+         FROM content_chunks cc
+         JOIN pages p ON p.id = cc.page_id
+        WHERE cc.embedding IS NULL
+        ORDER BY p.id, cc.chunk_index
+        LIMIT 100000`,
+    );
+    return rows as unknown as StaleChunkRow[];
+  }
+
   async deleteChunks(slug: string): Promise<void> {
     await this.db.query(
       `DELETE FROM content_chunks

src/core/postgres-engine.ts

@@ -5,7 +5,7 @@ import { runMigrations } from './migrate.ts';
 import { SCHEMA_SQL } from './schema-embedded.ts';
 import type {
   Page, PageInput, PageFilters, PageType,
-  Chunk, ChunkInput,
+  Chunk, ChunkInput, StaleChunkRow,
   SearchResult, SearchOpts,
   Link, GraphNode, GraphPath,
   TimelineEntry, TimelineInput, TimelineOpts,
@@ -18,10 +18,26 @@ import type {
 import { GBrainError } from './types.ts';
 import * as db from './db.ts';
 import { validateSlug, contentHash, rowToPage, rowToChunk, rowToSearchResult, parseEmbedding, tryParseEmbedding } from './utils.ts';
+import { resolveBoostMap, resolveHardExcludes } from './search/source-boost.ts';
+import { buildSourceFactorCase, buildHardExcludeClause } from './search/sql-ranking.ts';
+
+// CONNECTION_ERROR_PATTERNS / isConnectionError were used by the per-call
+// executeRaw retry that #406 originally shipped. Eng-review D3 dropped that
+// retry as unsound (regex idempotence-boundary doesn't hold for writable
+// CTEs or side-effecting SELECTs). Recovery now happens at the supervisor
+// level (3-strikes-then-reconnect). The unit tests in
+// test/connection-resilience.test.ts retain a self-contained copy of the
+// helper so the regression-against-future-reintroduction guard still works.
+// See TODOS.md item: "err.code-based connection-error matching" for the
+// follow-up that will reintroduce a typed retry mechanism.
 
 export class PostgresEngine implements BrainEngine {
   readonly kind = 'postgres' as const;
   private _sql: ReturnType<typeof postgres> | null = null;
+  /** Saved config for reconnection. */
+  private _savedConfig: (EngineConfig & { poolSize?: number }) | null = null;
+  /** Whether a reconnect is in progress (prevents concurrent reconnects). */
+  private _reconnecting = false;
 
   // Instance connection (for workers) or fall back to module global (backward compat)
   get sql(): ReturnType<typeof postgres> {
@@ -31,6 +47,7 @@ export class PostgresEngine implements BrainEngine {
 
   // Lifecycle
   async connect(config: EngineConfig & { poolSize?: number }): Promise<void> {
+    this._savedConfig = config;
     if (config.poolSize) {
       // Instance-level connection for worker isolation. resolvePoolSize lets
       // GBRAIN_POOL_SIZE cap below the caller's requested size when set — the
@@ -43,12 +60,20 @@ export class PostgresEngine implements BrainEngine {
       // "prepared statement does not exist" under load just like the module
       // singleton did before v0.15.4.
       const prepare = db.resolvePrepare(url);
+      // Session timeouts (statement_timeout + idle_in_transaction_session_timeout)
+      // keep orphan pgbouncer backends from holding locks for hours when the
+      // postgres.js client disconnects mid-transaction. See resolveSessionTimeouts
+      // in db.ts for context + env var overrides.
+      const timeouts = db.resolveSessionTimeouts();
       const opts: Record<string, unknown> = {
         max: size,
         idle_timeout: 20,
         connect_timeout: 10,
         types: { bigint: postgres.BigInt },
       };
+      if (Object.keys(timeouts).length > 0) {
+        opts.connection = timeouts;
+      }
       if (typeof prepare === 'boolean') {
         opts.prepare = prepare;
       }
@@ -236,51 +261,83 @@ export class PostgresEngine implements BrainEngine {
     // ship < limit pages. 3x gives dedup enough to pick top N distinct pages.
     const innerLimit = Math.min(limit * 3, MAX_SEARCH_LIMIT * 3);
 
-    // Search-only timeout: prevents DoS via expensive queries without
-    // affecting long-running operations like embed --all or bulk import.
-    // SET LOCAL inside sql.begin() scopes the GUC to the transaction so
-    // it can never leak onto a pooled connection returned to other
-    // callers. A bare `SET statement_timeout` goes to an arbitrary
-    // connection from the pool, lives past this method, and either
-    // clips an unrelated caller's long-running query (DoS) or — via
-    // `SET statement_timeout = 0` — disables the guard for them.
+    // Source-aware ranking (v0.22): boost curated content (originals/,
+    // concepts/, writing/) and dampen bulk content (chat/, daily/, media/x/)
+    // by multiplying the chunk-grain ts_rank with a source-factor CASE.
+    // Detail-gated — disabled for `detail='high'` (temporal queries) so
+    // chat surfaces normally for date-framed lookups. Hard-exclude prefixes
+    // (test/, archive/, attachments/, .raw/ by default) filter at the
+    // chunk-rank stage so they never enter the candidate set.
+    const boostMap = resolveBoostMap();
+    const sourceFactorCase = buildSourceFactorCase('p.slug', boostMap, opts?.detail);
+    const hardExcludePrefixes = resolveHardExcludes(opts?.exclude_slug_prefixes, opts?.include_slug_prefixes);
+    const hardExcludeClause = buildHardExcludeClause('p.slug', hardExcludePrefixes);
+
+    const params: unknown[] = [query];
+    let typeClause = '';
+    if (type) {
+      params.push(type);
+      typeClause = `AND p.type = $${params.length}`;
+    }
+    let excludeSlugsClause = '';
+    if (excludeSlugs?.length) {
+      params.push(excludeSlugs);
+      excludeSlugsClause = `AND p.slug != ALL($${params.length}::text[])`;
+    }
+    let languageClause = '';
+    if (language) {
+      params.push(language);
+      languageClause = `AND cc.language = $${params.length}`;
+    }
+    let symbolKindClause = '';
+    if (symbolKind) {
+      params.push(symbolKind);
+      symbolKindClause = `AND cc.symbol_type = $${params.length}`;
+    }
+    params.push(innerLimit);
+    const innerLimitParam = `$${params.length}`;
+    params.push(limit);
+    const limitParam = `$${params.length}`;
+    params.push(offset);
+    const offsetParam = `$${params.length}`;
+
+    const rawQuery = `
+      WITH ranked_chunks AS (
+        SELECT
+          p.slug, p.id as page_id, p.title, p.type, p.source_id,
+          cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
+          ts_rank(cc.search_vector, websearch_to_tsquery('english', $1)) * ${sourceFactorCase} AS score
+        FROM content_chunks cc
+        JOIN pages p ON p.id = cc.page_id
+        WHERE cc.search_vector @@ websearch_to_tsquery('english', $1)
+          ${typeClause}
+          ${excludeSlugsClause}
+          ${detailLow ? `AND cc.chunk_source = 'compiled_truth'` : ''}
+          ${languageClause}
+          ${symbolKindClause}
+          ${hardExcludeClause}
+        ORDER BY score DESC
+        LIMIT ${innerLimitParam}
+      ),
+      best_per_page AS (
+        SELECT DISTINCT ON (slug) *
+        FROM ranked_chunks
+        ORDER BY slug, score DESC
+      )
+      SELECT slug, page_id, title, type, source_id,
+        chunk_id, chunk_index, chunk_text, chunk_source, score,
+        false AS stale
+      FROM best_per_page
+      ORDER BY score DESC
+      LIMIT ${limitParam}
+      OFFSET ${offsetParam}
+    `;
+
+    // Search-only timeout. SET LOCAL inside sql.begin() scopes the GUC
+    // to the transaction so it can never leak onto a pooled connection.
     const rows = await sql.begin(async sql => {
       await sql`SET LOCAL statement_timeout = '8s'`;
-      // CTE chain: rank chunks by FTS → DISTINCT ON (slug) to pick best
-      // chunk per page → order by score → limit. The external shape is
-      // page-grain; chunk-grain ranking wins because A4 weights mean
-      // doc-comment hits (and, once Layer 5 populates them, qualified
-      // symbol hits) beat body-text hits at the chunk level.
-      return await sql`
-        WITH ranked_chunks AS (
-          SELECT
-            p.slug, p.id as page_id, p.title, p.type, p.source_id,
-            cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
-            ts_rank(cc.search_vector, websearch_to_tsquery('english', ${query})) AS score
-          FROM content_chunks cc
-          JOIN pages p ON p.id = cc.page_id
-          WHERE cc.search_vector @@ websearch_to_tsquery('english', ${query})
-            ${type ? sql`AND p.type = ${type}` : sql``}
-            ${excludeSlugs?.length ? sql`AND p.slug != ALL(${excludeSlugs})` : sql``}
-            ${detailLow ? sql`AND cc.chunk_source = 'compiled_truth'` : sql``}
-            ${language ? sql`AND cc.language = ${language}` : sql``}
-            ${symbolKind ? sql`AND cc.symbol_type = ${symbolKind}` : sql``}
-          ORDER BY score DESC
-          LIMIT ${innerLimit}
-        ),
-        best_per_page AS (
-          SELECT DISTINCT ON (slug) *
-          FROM ranked_chunks
-          ORDER BY slug, score DESC
-        )
-        SELECT slug, page_id, title, type, source_id,
-          chunk_id, chunk_index, chunk_text, chunk_source, score,
-          false AS stale
-        FROM best_per_page
-        ORDER BY score DESC
-        LIMIT ${limit}
-        OFFSET ${offset}
-      `;
+      return await sql.unsafe(rawQuery, params as Parameters<typeof sql.unsafe>[1]);
     });
     return rows.map(rowToSearchResult);
   }
@@ -308,26 +365,64 @@ export class PostgresEngine implements BrainEngine {
       console.warn(`[gbrain] Warning: search limit clamped from ${opts.limit} to ${MAX_SEARCH_LIMIT}`);
     }
 
+    // Source-aware ranking applies here too — searchKeywordChunks is the
+    // chunk-grain anchor primitive that two-pass retrieval (Layer 7) uses,
+    // so curated-vs-bulk dampening should affect the anchor pool. Same
+    // detail-gate, same hard-exclude behavior as searchKeyword.
+    const boostMap = resolveBoostMap();
+    const sourceFactorCase = buildSourceFactorCase('p.slug', boostMap, opts?.detail);
+    const hardExcludePrefixes = resolveHardExcludes(opts?.exclude_slug_prefixes, opts?.include_slug_prefixes);
+    const hardExcludeClause = buildHardExcludeClause('p.slug', hardExcludePrefixes);
+
+    const params: unknown[] = [query];
+    let typeClause = '';
+    if (type) {
+      params.push(type);
+      typeClause = `AND p.type = $${params.length}`;
+    }
+    let excludeSlugsClause = '';
+    if (excludeSlugs?.length) {
+      params.push(excludeSlugs);
+      excludeSlugsClause = `AND p.slug != ALL($${params.length}::text[])`;
+    }
+    let languageClause = '';
+    if (language) {
+      params.push(language);
+      languageClause = `AND cc.language = $${params.length}`;
+    }
+    let symbolKindClause = '';
+    if (symbolKind) {
+      params.push(symbolKind);
+      symbolKindClause = `AND cc.symbol_type = $${params.length}`;
+    }
+    params.push(limit);
+    const limitParam = `$${params.length}`;
+    params.push(offset);
+    const offsetParam = `$${params.length}`;
+
+    const rawQuery = `
+      SELECT
+        p.slug, p.id as page_id, p.title, p.type, p.source_id,
+        cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
+        ts_rank(cc.search_vector, websearch_to_tsquery('english', $1)) * ${sourceFactorCase} AS score,
+        false AS stale
+      FROM content_chunks cc
+      JOIN pages p ON p.id = cc.page_id
+      WHERE cc.search_vector @@ websearch_to_tsquery('english', $1)
+        ${typeClause}
+        ${excludeSlugsClause}
+        ${detailLow ? `AND cc.chunk_source = 'compiled_truth'` : ''}
+        ${languageClause}
+        ${symbolKindClause}
+        ${hardExcludeClause}
+      ORDER BY score DESC
+      LIMIT ${limitParam}
+      OFFSET ${offsetParam}
+    `;
+
     const rows = await sql.begin(async sql => {
       await sql`SET LOCAL statement_timeout = '8s'`;
-      return await sql`
-        SELECT
-          p.slug, p.id as page_id, p.title, p.type, p.source_id,
-          cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
-          ts_rank(cc.search_vector, websearch_to_tsquery('english', ${query})) AS score,
-          false AS stale
-        FROM content_chunks cc
-        JOIN pages p ON p.id = cc.page_id
-        WHERE cc.search_vector @@ websearch_to_tsquery('english', ${query})
-          ${type ? sql`AND p.type = ${type}` : sql``}
-          ${excludeSlugs?.length ? sql`AND p.slug != ALL(${excludeSlugs})` : sql``}
-          ${detailLow ? sql`AND cc.chunk_source = 'compiled_truth'` : sql``}
-          ${language ? sql`AND cc.language = ${language}` : sql``}
-          ${symbolKind ? sql`AND cc.symbol_type = ${symbolKind}` : sql``}
-        ORDER BY score DESC
-        LIMIT ${limit}
-        OFFSET ${offset}
-      `;
+      return await sql.unsafe(rawQuery, params as Parameters<typeof sql.unsafe>[1]);
     });
     return rows.map(rowToSearchResult);
   }
@@ -348,29 +443,80 @@ export class PostgresEngine implements BrainEngine {
 
     const vecStr = '[' + Array.from(embedding).join(',') + ']';
 
-    // Search-only timeout (see searchKeyword for rationale). SET LOCAL +
-    // sql.begin ensures the GUC stays transaction-scoped on the pooled
-    // connection.
-    const rows = await sql.begin(async sql => {
-      await sql`SET LOCAL statement_timeout = '8s'`;
-      return await sql`
+    // Two-stage CTE (v0.22): inner CTE keeps a pure-distance ORDER BY so
+    // the HNSW index stays usable. Folding source-boost into the inner
+    // ORDER BY would force a sequential scan over every chunk (seconds vs
+    // ~10ms with HNSW). Outer SELECT re-ranks the candidate pool by
+    // raw_score * source_factor.
+    //
+    // innerLimit scales with offset to preserve the pagination contract:
+    // a fixed cap of 100 would silently empty offset > 100.
+    const boostMap = resolveBoostMap();
+    const sourceFactorCaseOnSlug = buildSourceFactorCase('slug', boostMap, opts?.detail);
+    const hardExcludePrefixes = resolveHardExcludes(opts?.exclude_slug_prefixes, opts?.include_slug_prefixes);
+    const hardExcludeClause = buildHardExcludeClause('p.slug', hardExcludePrefixes);
+    const innerLimit = offset + Math.max(limit * 5, 100);
+
+    const params: unknown[] = [vecStr];
+    let typeClause = '';
+    if (type) {
+      params.push(type);
+      typeClause = `AND p.type = $${params.length}`;
+    }
+    let excludeSlugsClause = '';
+    if (excludeSlugs?.length) {
+      params.push(excludeSlugs);
+      excludeSlugsClause = `AND p.slug != ALL($${params.length}::text[])`;
+    }
+    let languageClause = '';
+    if (language) {
+      params.push(language);
+      languageClause = `AND cc.language = $${params.length}`;
+    }
+    let symbolKindClause = '';
+    if (symbolKind) {
+      params.push(symbolKind);
+      symbolKindClause = `AND cc.symbol_type = $${params.length}`;
+    }
+    params.push(innerLimit);
+    const innerLimitParam = `$${params.length}`;
+    params.push(limit);
+    const limitParam = `$${params.length}`;
+    params.push(offset);
+    const offsetParam = `$${params.length}`;
+
+    const rawQuery = `
+      WITH hnsw_candidates AS (
         SELECT
           p.slug, p.id as page_id, p.title, p.type, p.source_id,
           cc.id as chunk_id, cc.chunk_index, cc.chunk_text, cc.chunk_source,
-          1 - (cc.embedding <=> ${vecStr}::vector) AS score,
-          false AS stale
+          1 - (cc.embedding <=> $1::vector) AS raw_score
         FROM content_chunks cc
         JOIN pages p ON p.id = cc.page_id
         WHERE cc.embedding IS NOT NULL
-          ${detailLow ? sql`AND cc.chunk_source = 'compiled_truth'` : sql``}
-          ${type ? sql`AND p.type = ${type}` : sql``}
-          ${excludeSlugs?.length ? sql`AND p.slug != ALL(${excludeSlugs})` : sql``}
-          ${language ? sql`AND cc.language = ${language}` : sql``}
-          ${symbolKind ? sql`AND cc.symbol_type = ${symbolKind}` : sql``}
-        ORDER BY cc.embedding <=> ${vecStr}::vector
-        LIMIT ${limit}
-        OFFSET ${offset}
-      `;
+          ${detailLow ? `AND cc.chunk_source = 'compiled_truth'` : ''}
+          ${typeClause}
+          ${excludeSlugsClause}
+          ${languageClause}
+          ${symbolKindClause}
+          ${hardExcludeClause}
+        ORDER BY cc.embedding <=> $1::vector
+        LIMIT ${innerLimitParam}
+      )
+      SELECT
+        slug, page_id, title, type, source_id,
+        chunk_id, chunk_index, chunk_text, chunk_source,
+        raw_score * ${sourceFactorCaseOnSlug} AS score,
+        false AS stale
+      FROM hnsw_candidates
+      ORDER BY score DESC
+      LIMIT ${limitParam}
+      OFFSET ${offsetParam}
+    `;
+
+    const rows = await sql.begin(async sql => {
+      await sql`SET LOCAL statement_timeout = '8s'`;
+      return await sql.unsafe(rawQuery, params as Parameters<typeof sql.unsafe>[1]);
     });
     return rows.map(rowToSearchResult);
   }
@@ -449,7 +595,13 @@ export class PostgresEngine implements BrainEngine {
       }
     }
 
-    // Single statement upsert: preserves existing embeddings via COALESCE when new value is NULL
+    // Single statement upsert: preserves existing embeddings via COALESCE when new value is NULL.
+    // CONSISTENCY: when chunk_text changes and no new embedding is supplied, BOTH embedding AND
+    // embedded_at must reset to NULL so `embed --stale` correctly picks up the row for re-embedding.
+    // Without this, embedded_at lies (says "embedded" while embedding=NULL), and any staleness
+    // predicate on embedded_at would silently skip the row. This is why the egress fix predicates
+    // on `embedding IS NULL` rather than `embedded_at IS NULL` — and it's why we now keep both
+    // columns honest at write time.
     await sql.unsafe(
       `INSERT INTO content_chunks ${cols} VALUES ${rows.join(', ')}
        ON CONFLICT (page_id, chunk_index) DO UPDATE SET
@@ -458,7 +610,10 @@ export class PostgresEngine implements BrainEngine {
          embedding = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.embedding ELSE COALESCE(EXCLUDED.embedding, content_chunks.embedding) END,
          model = COALESCE(EXCLUDED.model, content_chunks.model),
          token_count = EXCLUDED.token_count,
-         embedded_at = COALESCE(EXCLUDED.embedded_at, content_chunks.embedded_at),
+         embedded_at = CASE
+           WHEN EXCLUDED.chunk_text != content_chunks.chunk_text AND EXCLUDED.embedding IS NULL THEN NULL
+           ELSE COALESCE(EXCLUDED.embedded_at, content_chunks.embedded_at)
+         END,
          language = EXCLUDED.language,
          symbol_name = EXCLUDED.symbol_name,
          symbol_type = EXCLUDED.symbol_type,
@@ -482,6 +637,30 @@ export class PostgresEngine implements BrainEngine {
     return rows.map((r) => rowToChunk(r as Record<string, unknown>));
   }
 
+  async countStaleChunks(): Promise<number> {
+    const sql = this.sql;
+    const [row] = await sql`
+      SELECT count(*)::int AS count
+      FROM content_chunks
+      WHERE embedding IS NULL
+    `;
+    return Number((row as { count?: number } | undefined)?.count ?? 0);
+  }
+
+  async listStaleChunks(): Promise<StaleChunkRow[]> {
+    const sql = this.sql;
+    const rows = await sql`
+      SELECT p.slug, cc.chunk_index, cc.chunk_text, cc.chunk_source,
+             cc.model, cc.token_count
+      FROM content_chunks cc
+      JOIN pages p ON p.id = cc.page_id
+      WHERE cc.embedding IS NULL
+      ORDER BY p.id, cc.chunk_index
+      LIMIT 100000
+    `;
+    return rows as unknown as StaleChunkRow[];
+  }
+
   async deleteChunks(slug: string): Promise<void> {
     const sql = this.sql;
     await sql`
@@ -1205,9 +1384,34 @@ export class PostgresEngine implements BrainEngine {
     return rows.map((r) => rowToChunk(r as Record<string, unknown>, true));
   }
 
+  /**
+   * Reconnect the engine by tearing down the current pool and creating a fresh one.
+   * No-ops if no saved config (module-singleton mode) or if already reconnecting.
+   */
+  async reconnect(): Promise<void> {
+    if (!this._savedConfig || this._reconnecting) return;
+    this._reconnecting = true;
+    try {
+      // Tear down old pool (best-effort — it may already be dead)
+      try { await this.disconnect(); } catch { /* swallow */ }
+      // Create fresh pool
+      await this.connect(this._savedConfig);
+    } finally {
+      this._reconnecting = false;
+    }
+  }
+
   async executeRaw<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
     const conn = this.sql;
     return conn.unsafe(sql, params as Parameters<typeof conn.unsafe>[1]) as unknown as T[];
+    // Pre-#406 behavior: throw on any error including connection death.
+    // Per-call auto-retry is not safe here because executeRaw is also used
+    // for non-transactional mutations (DELETE/UPDATE/INSERT in sources.ts,
+    // ALTER TABLE in migrations) where retrying after a connection-mid-statement
+    // death can phantom-write a row that already committed on the server.
+    // Recovery instead happens at the supervisor level: the watchdog detects
+    // 3 consecutive health-check failures and calls engine.reconnect() to
+    // swap in a fresh pool. See db.ts setSessionDefaults / supervisor.ts.
   }
 
   // ============================================================

src/core/search/source-boost.ts

@@ -0,0 +1,116 @@
+/**
+ * Source-Type Boost Map
+ *
+ * Multiplies into ts_rank / vector cosine score at SQL build time so that
+ * curated content (originals/, concepts/, writing/) outranks bulk content
+ * (wintermute/chat/, daily/, media/x/) for non-temporal queries.
+ *
+ * Keyed by slug prefix. Longest-prefix-match wins (sorted at lookup time
+ * inside sql-ranking.ts). Defaults grounded in the composition of the
+ * canonical brain at ~/git/brain/.
+ *
+ * Override via env: GBRAIN_SOURCE_BOOST="originals/:1.8,wintermute/chat/:0.3"
+ * Hard-exclude via env: GBRAIN_SEARCH_EXCLUDE="test/,scratch/"
+ */
+
+export const DEFAULT_SOURCE_BOOSTS: Record<string, number> = {
+  // Curated, opinionated, high-signal — Garry's own writing
+  'originals/': 1.5,
+  // Reusable knowledge frameworks
+  'concepts/': 1.3,
+  // Long-form essays / articles
+  'writing/': 1.4,
+  // Entity pages
+  'people/': 1.2,
+  'companies/': 1.2,
+  'deals/': 1.2,
+  // Notes from real meetings
+  'meetings/': 1.1,
+  // Ingested third-party content
+  'media/articles/': 1.1,
+  'media/repos/': 1.1,
+  // Neutral baselines (explicit for clarity)
+  'yc/': 1.0,
+  'civic/': 1.0,
+  // Bulk / noisy
+  'daily/': 0.8,
+  'media/x/': 0.7,
+  // Chat transcripts — massive, noisy, swamp keyword queries
+  'wintermute/chat/': 0.5,
+};
+
+/**
+ * Hard-excludes — slug prefixes that should never enter search results
+ * (unless explicitly opted-in via include_slug_prefixes).
+ */
+export const DEFAULT_HARD_EXCLUDES: string[] = [
+  'test/',
+  'archive/',
+  'attachments/',
+  '.raw/',
+];
+
+/**
+ * Parse GBRAIN_SOURCE_BOOST env var.
+ * Format: comma-separated prefix:factor pairs.
+ * Example: "originals/:1.8,wintermute/chat/:0.3"
+ *
+ * Malformed entries are skipped silently. Returns empty object if env is
+ * unset or unparseable in its entirety.
+ */
+export function parseSourceBoostEnv(env: string | undefined): Record<string, number> {
+  if (!env) return {};
+  const out: Record<string, number> = {};
+  for (const pair of env.split(',')) {
+    const idx = pair.lastIndexOf(':');
+    if (idx <= 0) continue;
+    const prefix = pair.slice(0, idx).trim();
+    const factor = Number.parseFloat(pair.slice(idx + 1).trim());
+    if (!prefix || !Number.isFinite(factor) || factor < 0) continue;
+    out[prefix] = factor;
+  }
+  return out;
+}
+
+/**
+ * Parse GBRAIN_SEARCH_EXCLUDE env var.
+ * Format: comma-separated slug prefixes.
+ * Example: "test/,scratch/,private/"
+ *
+ * Blank entries skipped. Returns empty array if env is unset.
+ */
+export function parseHardExcludesEnv(env: string | undefined): string[] {
+  if (!env) return [];
+  return env.split(',').map(s => s.trim()).filter(s => s.length > 0);
+}
+
+/**
+ * Resolve the effective boost map by merging defaults with env override.
+ * Env entries override defaults (shallow merge); env-only entries are added.
+ */
+export function resolveBoostMap(
+  envValue: string | undefined = process.env.GBRAIN_SOURCE_BOOST,
+): Record<string, number> {
+  const override = parseSourceBoostEnv(envValue);
+  return { ...DEFAULT_SOURCE_BOOSTS, ...override };
+}
+
+/**
+ * Resolve the effective hard-exclude prefix list.
+ *
+ * - Defaults union with env-supplied excludes
+ * - Subtract any caller-supplied include_slug_prefixes (opt-back-in)
+ * - Caller-supplied exclude_slug_prefixes adds to the union
+ */
+export function resolveHardExcludes(
+  excludeOpt?: string[],
+  includeOpt?: string[],
+  envValue: string | undefined = process.env.GBRAIN_SEARCH_EXCLUDE,
+): string[] {
+  const envExcludes = parseHardExcludesEnv(envValue);
+  const union = new Set<string>([...DEFAULT_HARD_EXCLUDES, ...envExcludes, ...(excludeOpt ?? [])]);
+  if (includeOpt?.length) {
+    for (const p of includeOpt) union.delete(p);
+  }
+  return Array.from(union);
+}

src/core/search/sql-ranking.ts

@@ -0,0 +1,105 @@
+/**
+ * SQL Ranking Builders
+ *
+ * Pure string builders for the source-aware ranking signal that both
+ * postgres-engine and pglite-engine inject into searchKeyword / searchVector.
+ *
+ * Returns RAW SQL FRAGMENTS. Call sites must embed via the engine's "unsafe"
+ * SQL tag (`sql.unsafe(fragment)` for postgres.js, equivalent for pglite).
+ *
+ * Inputs to these builders that originate from env vars or caller options
+ * (slug prefixes) are LIKE-pattern-escaped (`%`, `_`, `\`) AND SQL-string
+ * escaped (single-quote doubling) before inlining. The slugColumn parameter
+ * is supplied by us at the call site and is never user-controllable.
+ *
+ * Numeric factors come from `parseSourceBoostEnv` which calls Number.parseFloat
+ * and validates `Number.isFinite(factor) && factor >= 0`, so they're safe to
+ * inline as bare literals.
+ */
+
+/** Escape `%`, `_`, and `\` so a string can be used as a LIKE prefix literal. */
+function escapeLikePattern(s: string): string {
+  return s.replace(/[%_\\]/g, '\\$&');
+}
+
+/** Escape a SQL string literal: replace single-quote with two single-quotes. */
+function escapeSqlLiteral(s: string): string {
+  return s.replace(/'/g, "''");
+}
+
+/** Escape a slug prefix for use as `LIKE 'prefix%'` (both LIKE-escape and SQL-escape). */
+function buildLikePrefixLiteral(prefix: string): string {
+  return `'${escapeSqlLiteral(escapeLikePattern(prefix))}%'`;
+}
+
+/**
+ * Build a CASE expression that returns the source-boost factor for a slug.
+ *
+ * Returns a literal `'1.0'` when `detail === 'high'` so temporal queries
+ * bypass source-boost entirely (mirrors the existing COMPILED_TRUTH_BOOST
+ * gate in hybrid.ts).
+ *
+ * Prefixes are sorted by length descending so longest-match wins:
+ * `media/articles/` (1.1) wins over `media/x/` (0.7) without caller-order
+ * dependencies.
+ *
+ * @param slugColumn — qualified column reference (e.g. `'p.slug'`). MUST be
+ *                     supplied by the engine, never from user input.
+ * @param boostMap   — prefix → factor map (defaults merged with env override)
+ * @param detail     — query detail level; `'high'` disables source-boost
+ *
+ * @returns raw SQL fragment, e.g. `(CASE WHEN p.slug LIKE 'originals/%' THEN 1.5 ... ELSE 1.0 END)`
+ */
+export function buildSourceFactorCase(
+  slugColumn: string,
+  boostMap: Record<string, number>,
+  detail: 'low' | 'medium' | 'high' | undefined,
+): string {
+  // Loose-string guard: agents passing `"HIGH"` or `"high "` over MCP/JSON
+  // should still hit the temporal-bypass path. TypeScript narrows `detail`
+  // for typed callers; this guard catches the untyped boundary.
+  const normalized = typeof detail === 'string' ? detail.trim().toLowerCase() : detail;
+  if (normalized === 'high') return '1.0';
+
+  const entries = Object.entries(boostMap)
+    .filter(([prefix, factor]) => prefix.length > 0 && Number.isFinite(factor) && factor >= 0)
+    .sort((a, b) => b[0].length - a[0].length); // longest-prefix-match wins
+
+  if (entries.length === 0) return '1.0';
+
+  const whens = entries.map(([prefix, factor]) =>
+    `WHEN ${slugColumn} LIKE ${buildLikePrefixLiteral(prefix)} THEN ${factor}`
+  ).join(' ');
+
+  return `(CASE ${whens} ELSE 1.0 END)`;
+}
+
+/**
+ * Build a `NOT (col LIKE 'p1%' OR col LIKE 'p2%' OR ...)` exclusion clause.
+ *
+ * Why OR-chain wrapped in NOT, not `NOT LIKE ALL/ANY(array)`:
+ *   - `NOT LIKE ALL(array)` means "doesn't match every pattern" — still
+ *     keeps rows that match one. Wrong for set-exclusion.
+ *   - `NOT LIKE ANY(array)` is non-standard and behavior varies.
+ *   - Boolean-friendly OR-chain wrapped in NOT is unambiguous and indexable.
+ *
+ * Returns empty string when prefixes is empty, so callers can interpolate
+ * unconditionally with a leading `AND`.
+ *
+ * @param slugColumn — qualified column reference (engine-supplied, trusted)
+ * @param prefixes   — list of slug prefixes to exclude (env + caller-supplied; escaped)
+ *
+ * @returns raw SQL fragment (with leading space) or empty string
+ */
+export function buildHardExcludeClause(slugColumn: string, prefixes: string[]): string {
+  if (!prefixes.length) return '';
+  const likes = prefixes
+    .filter(p => p.length > 0)
+    .map(p => `${slugColumn} LIKE ${buildLikePrefixLiteral(p)}`)
+    .join(' OR ');
+  if (!likes) return '';
+  return `AND NOT (${likes})`;
+}
+
+// Exported for unit tests
+export const __test__ = { escapeLikePattern, escapeSqlLiteral, buildLikePrefixLiteral };

src/core/types.ts

@@ -70,6 +70,21 @@ export interface Chunk {
   symbol_name_qualified?: string | null;
 }
 
+/**
+ * Lightweight row shape returned by `BrainEngine.listStaleChunks()`.
+ * Excludes the `embedding` column on purpose — only chunks needing
+ * an embedding come back, and we don't ship the (always-null on stale
+ * rows) embedding bytes over the wire. See `embed --stale` egress fix.
+ */
+export interface StaleChunkRow {
+  slug: string;
+  chunk_index: number;
+  chunk_text: string;
+  chunk_source: 'compiled_truth' | 'timeline';
+  model: string | null;
+  token_count: number | null;
+}
+
 export interface ChunkInput {
   chunk_index: number;
   chunk_text: string;
@@ -122,6 +137,18 @@ export interface SearchOpts {
   offset?: number;
   type?: PageType;
   exclude_slugs?: string[];
+  /**
+   * Slug-prefix excludes — additive over DEFAULT_HARD_EXCLUDES (test/, archive/,
+   * attachments/, .raw/) and the GBRAIN_SEARCH_EXCLUDE env var. Stacks with
+   * `exclude_slugs` (exact match) — a row is filtered if it matches either set.
+   */
+  exclude_slug_prefixes?: string[];
+  /**
+   * Opt-back-in list — subtracts entries from the resolved hard-exclude set.
+   * E.g. `include_slug_prefixes: ['test/']` lets a query see test/ pages even
+   * though they're hard-excluded by default.
+   */
+  include_slug_prefixes?: string[];
   detail?: 'low' | 'medium' | 'high';
   /**
    * v0.20.0 Cathedral II: filter by content_chunks.language (e.g., 'typescript',

test/apply-migrations.test.ts

@@ -108,7 +108,7 @@ describe('buildPlan — diff against completed + installed VERSION', () => {
     // autopilot cooperative, v0.16.0 = subagent runtime, v0.18.0 = multi-
     // source brains, v0.18.1 = RLS hardening, v0.21.0 = Cathedral II
     // (renumbered from v0.20.0 after master shipped v0.20.x in parallel).
-    expect(plan.skippedFuture.map(m => m.version)).toEqual(['0.12.0', '0.12.2', '0.13.0', '0.13.1', '0.14.0', '0.16.0', '0.18.0', '0.18.1', '0.21.0']);
+    expect(plan.skippedFuture.map(m => m.version)).toEqual(['0.12.0', '0.12.2', '0.13.0', '0.13.1', '0.14.0', '0.16.0', '0.18.0', '0.18.1', '0.21.0', '0.22.4']);
   });
 
   test('already applied → v0.11.0 lands in `applied` bucket, not pending', () => {
@@ -148,7 +148,7 @@ describe('buildPlan — diff against completed + installed VERSION', () => {
     // were added later; installed=0.12.0 means they belong in skippedFuture,
     // not pending. v0.11.0 and v0.12.0 stay pending despite being ≤ installed —
     // that is the H9 invariant.
-    expect(plan.skippedFuture.map(m => m.version)).toEqual(['0.12.2', '0.13.0', '0.13.1', '0.14.0', '0.16.0', '0.18.0', '0.18.1', '0.21.0']);
+    expect(plan.skippedFuture.map(m => m.version)).toEqual(['0.12.2', '0.13.0', '0.13.1', '0.14.0', '0.16.0', '0.18.0', '0.18.1', '0.21.0', '0.22.4']);
   });
 
   test('--migration filter narrows to one version', () => {

test/brain-writer.test.ts

@@ -0,0 +1,219 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync, mkdirSync, symlinkSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import {
+  autoFixFrontmatter,
+  writeBrainPage,
+  scanBrainSources,
+  BrainWriterError,
+} from '../src/core/brain-writer.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+
+const fence = '---';
+
+describe('autoFixFrontmatter', () => {
+  test('strips null bytes', () => {
+    const input = `${fence}\ntitle: ok\n${fence}\n\nbody\x00drop\x00here`;
+    const { content, fixes } = autoFixFrontmatter(input);
+    expect(content.includes('\x00')).toBe(false);
+    expect(fixes.some(f => f.code === 'NULL_BYTES')).toBe(true);
+  });
+
+  test('inserts closing --- before heading when MISSING_CLOSE', () => {
+    const input = `${fence}\ntype: concept\ntitle: ok\n# A heading\n\nbody`;
+    const { content, fixes } = autoFixFrontmatter(input);
+    expect(fixes.some(f => f.code === 'MISSING_CLOSE')).toBe(true);
+    // After fix, parsing should find a closing --- before the heading.
+    const idxClose = content.indexOf('---', 3);
+    const idxHeading = content.indexOf('# A heading');
+    expect(idxClose).toBeGreaterThan(0);
+    expect(idxClose).toBeLessThan(idxHeading);
+  });
+
+  test('rewrites nested-quote title to single-quoted', () => {
+    const input = `${fence}\ntype: concept\ntitle: "Phil "Nick" Last"\n${fence}\n\nbody`;
+    const { content, fixes } = autoFixFrontmatter(input);
+    expect(fixes.some(f => f.code === 'NESTED_QUOTES')).toBe(true);
+    // Outer wrapper is now single quotes.
+    expect(content).toMatch(/^title: '.*'\s*$/m);
+  });
+
+  test('removes mismatched slug field', () => {
+    const input = `${fence}\ntype: concept\ntitle: hi\nslug: wrong-slug\n${fence}\n\nbody`;
+    const { content, fixes } = autoFixFrontmatter(input, { filePath: 'people/jane-doe.md' });
+    expect(fixes.some(f => f.code === 'SLUG_MISMATCH')).toBe(true);
+    expect(content).not.toMatch(/^slug:/m);
+  });
+
+  test('idempotent: running twice produces no diff and no fixes on second pass', () => {
+    const input = `${fence}\ntype: concept\ntitle: "Phil "Nick" Last"\n${fence}\n\nbody\x00`;
+    const first = autoFixFrontmatter(input);
+    const second = autoFixFrontmatter(first.content);
+    expect(second.content).toBe(first.content);
+    expect(second.fixes).toEqual([]);
+  });
+
+  test('clean input: no fixes, content unchanged', () => {
+    const input = `${fence}\ntype: concept\ntitle: ok\n${fence}\n\nbody`;
+    const { content, fixes } = autoFixFrontmatter(input);
+    expect(content).toBe(input);
+    expect(fixes).toEqual([]);
+  });
+});
+
+describe('writeBrainPage', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'brain-writer-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test('happy path: writes file inside source', () => {
+    const file = join(tmp, 'people', 'jane.md');
+    const content = `${fence}\ntype: person\ntitle: Jane\n${fence}\n\nhello`;
+    writeBrainPage(file, content, { sourcePath: tmp });
+    expect(readFileSync(file, 'utf8')).toBe(content);
+  });
+
+  test('throws BrainWriterError when path is outside sourcePath', () => {
+    const elsewhere = mkdtempSync(join(tmpdir(), 'brain-writer-other-'));
+    try {
+      const offending = join(elsewhere, 'evil.md');
+      expect(() =>
+        writeBrainPage(offending, 'content', { sourcePath: tmp }),
+      ).toThrow(BrainWriterError);
+    } finally {
+      rmSync(elsewhere, { recursive: true, force: true });
+    }
+  });
+
+  test('writes .bak before mutating an existing file', () => {
+    const file = join(tmp, 'people', 'jane.md');
+    mkdirSync(join(tmp, 'people'), { recursive: true });
+    const original = `${fence}\ntype: person\ntitle: Old\n${fence}\n\nold`;
+    writeFileSync(file, original);
+    writeBrainPage(file, `${fence}\ntype: person\ntitle: New\n${fence}\n\nnew`, { sourcePath: tmp });
+    expect(existsSync(file + '.bak')).toBe(true);
+    expect(readFileSync(file + '.bak', 'utf8')).toBe(original);
+  });
+
+  test('autoFix: true repairs nested quotes before writing', () => {
+    const file = join(tmp, 'people', 'jane.md');
+    const broken = `${fence}\ntype: person\ntitle: "Phil "Nick" Last"\n${fence}\n\nbody`;
+    const { fixes } = writeBrainPage(file, broken, { sourcePath: tmp, autoFix: true });
+    expect(fixes.some(f => f.code === 'NESTED_QUOTES')).toBe(true);
+    expect(readFileSync(file, 'utf8')).toMatch(/^title: '.*'\s*$/m);
+  });
+});
+
+describe('scanBrainSources (PGLite)', () => {
+  let tmp: string;
+  let engine: PGLiteEngine;
+
+  beforeEach(async () => {
+    tmp = mkdtempSync(join(tmpdir(), 'brain-writer-scan-'));
+    engine = new PGLiteEngine();
+    await engine.connect({});
+    await engine.initSchema();
+  });
+
+  afterEach(async () => {
+    await engine.disconnect();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  async function registerSource(id: string, path: string) {
+    await engine.executeRaw(
+      `INSERT INTO sources (id, name, local_path) VALUES ($1, $1, $2)
+         ON CONFLICT (id) DO UPDATE SET local_path = EXCLUDED.local_path`,
+      [id, path],
+    );
+  }
+
+  test('returns ok=true for empty source', async () => {
+    await registerSource('empty', tmp);
+    const report = await scanBrainSources(engine);
+    expect(report.ok).toBe(true);
+    expect(report.total).toBe(0);
+    const empty = report.per_source.find(s => s.source_id === 'empty');
+    expect(empty).toBeDefined();
+    expect(empty!.total).toBe(0);
+  });
+
+  test('detects errors across multiple sources', async () => {
+    const srcA = join(tmp, 'a');
+    const srcB = join(tmp, 'b');
+    mkdirSync(srcA, { recursive: true });
+    mkdirSync(srcB, { recursive: true });
+    writeFileSync(join(srcA, 'p1.md'), `${fence}\ntype: x\ntitle: ok\n${fence}\n\nbody\x00`);
+    writeFileSync(join(srcB, 'p2.md'), `${fence}\ntype: x\ntitle: "P "I" L"\n${fence}\n\nbody`);
+    await registerSource('alpha', srcA);
+    await registerSource('beta', srcB);
+
+    const report = await scanBrainSources(engine);
+    expect(report.ok).toBe(false);
+    expect(report.total).toBeGreaterThan(0);
+    const alpha = report.per_source.find(s => s.source_id === 'alpha')!;
+    const beta = report.per_source.find(s => s.source_id === 'beta')!;
+    expect(alpha.errors_by_code.NULL_BYTES).toBeGreaterThanOrEqual(1);
+    expect(beta.errors_by_code.NESTED_QUOTES).toBeGreaterThanOrEqual(1);
+  });
+
+  test('respects sourceId filter', async () => {
+    const srcA = join(tmp, 'a');
+    const srcB = join(tmp, 'b');
+    mkdirSync(srcA, { recursive: true });
+    mkdirSync(srcB, { recursive: true });
+    writeFileSync(join(srcA, 'bad.md'), `${fence}\ntype: x\ntitle: ok\n${fence}\n\nbody\x00`);
+    writeFileSync(join(srcB, 'bad.md'), `${fence}\ntype: x\ntitle: ok\n${fence}\n\nbody\x00`);
+    await registerSource('alpha', srcA);
+    await registerSource('beta', srcB);
+
+    const onlyA = await scanBrainSources(engine, { sourceId: 'alpha' });
+    expect(onlyA.per_source.length).toBe(1);
+    expect(onlyA.per_source[0]!.source_id).toBe('alpha');
+  });
+
+  test('skips registered source with missing path', async () => {
+    await registerSource('ghost', join(tmp, 'does-not-exist'));
+    const report = await scanBrainSources(engine);
+    const ghost = report.per_source.find(s => s.source_id === 'ghost')!;
+    expect(ghost.total).toBe(0);
+  });
+
+  test('skips symlinks (matches sync no-symlink policy)', async () => {
+    mkdirSync(join(tmp, 'real'), { recursive: true });
+    writeFileSync(join(tmp, 'real', 'good.md'), `${fence}\ntype: x\ntitle: ok\n${fence}\n\nbody`);
+    // Create a symlink loop: tmp/real/loop -> tmp/real
+    try {
+      symlinkSync(join(tmp, 'real'), join(tmp, 'real', 'loop'));
+    } catch {
+      // Some CI environments forbid symlink creation; skip the assertion.
+      return;
+    }
+    await registerSource('with-symlink', tmp);
+    const report = await scanBrainSources(engine);
+    // The walk should complete without infinite-looping; at most one .md
+    // entry visited (via the real path, not the symlink).
+    expect(report.per_source[0]!.total).toBe(0);
+  });
+
+  test('AbortSignal mid-scan stops walking', async () => {
+    const src = join(tmp, 'big');
+    mkdirSync(src, { recursive: true });
+    for (let i = 0; i < 50; i++) {
+      writeFileSync(join(src, `p${i}.md`), `${fence}\ntype: x\ntitle: t${i}\n${fence}\n\nbody`);
+    }
+    await registerSource('big', src);
+    const ctrl = new AbortController();
+    ctrl.abort();
+    const report = await scanBrainSources(engine, { signal: ctrl.signal });
+    // Aborted before any source ran; per_source array stays empty (or has zero reports).
+    expect(report.per_source.length).toBe(0);
+  });
+});

test/check-resolvable.test.ts

@@ -255,6 +255,21 @@ describe("DRY detection — checkResolvable", () => {
   });
 });
 
+describe("v0.22.4 regression — actual repo skills/ has 0 warnings", () => {
+  test("repo skills/ pass check-resolvable cleanly", () => {
+    // The contract for v0.22.4 (Part A): zero warnings, zero errors
+    // against the actual checked-in skills/ tree. Guards against future
+    // regressions that re-introduce trigger overlap, DRY violations, or
+    // routing-eval fixture drift.
+    const report = checkResolvable(SKILLS_DIR);
+    const errors = report.issues.filter(i => i.severity === "error");
+    const warnings = report.issues.filter(i => i.severity === "warning");
+    expect(errors).toEqual([]);
+    expect(warnings).toEqual([]);
+    expect(report.ok).toBe(true);
+  });
+});
+
 // bun:test has no beforeEach/afterEach at module scope cleanly interacting
 // with closures; a small helper keeps cleanup readable and per-test.
 function afterEachCleanup(fn: () => void) {

test/connection-resilience.test.ts

@@ -0,0 +1,314 @@
+import { describe, it, expect } from 'bun:test';
+
+/**
+ * Tests for connection resilience features:
+ * 1. PostgresEngine.executeRaw retries on connection errors
+ * 2. PostgresEngine.reconnect creates fresh connection pool
+ * 3. Supervisor health check tracks consecutive failures
+ * 4. Supervisor classifies worker exit reasons
+ */
+
+// --- Unit tests for isConnectionError (extracted pattern) ---
+
+const CONNECTION_ERROR_PATTERNS = [
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'EPIPE',
+  'connection terminated',
+  'Client has encountered a connection error',
+  'password authentication failed',
+  'Connection terminated unexpectedly',
+  'no pg_hba.conf entry',
+  'server closed the connection unexpectedly',
+  'SSL connection has been closed unexpectedly',
+  'connection is insecure',
+  'too many connections',
+  'remaining connection slots are reserved',
+];
+
+function isConnectionError(err: unknown): boolean {
+  if (!err) return false;
+  const msg = err instanceof Error ? err.message : String(err);
+  const code = (err as NodeJS.ErrnoException)?.code;
+  if (code && CONNECTION_ERROR_PATTERNS.includes(code)) return true;
+  return CONNECTION_ERROR_PATTERNS.some(p => msg.includes(p));
+}
+
+describe('isConnectionError', () => {
+  it('detects password authentication failure', () => {
+    expect(isConnectionError(new Error('password authentication failed for user "postgres"'))).toBe(true);
+  });
+
+  it('detects ECONNREFUSED via error code', () => {
+    const err = new Error('connect ECONNREFUSED 127.0.0.1:5432') as NodeJS.ErrnoException;
+    err.code = 'ECONNREFUSED';
+    expect(isConnectionError(err)).toBe(true);
+  });
+
+  it('detects ECONNRESET via error code', () => {
+    const err = new Error('read ECONNRESET') as NodeJS.ErrnoException;
+    err.code = 'ECONNRESET';
+    expect(isConnectionError(err)).toBe(true);
+  });
+
+  it('detects connection terminated message', () => {
+    expect(isConnectionError(new Error('connection terminated'))).toBe(true);
+  });
+
+  it('detects Connection terminated unexpectedly', () => {
+    expect(isConnectionError(new Error('Connection terminated unexpectedly'))).toBe(true);
+  });
+
+  it('detects server closed the connection', () => {
+    expect(isConnectionError(new Error('server closed the connection unexpectedly'))).toBe(true);
+  });
+
+  it('detects SSL connection closed', () => {
+    expect(isConnectionError(new Error('SSL connection has been closed unexpectedly'))).toBe(true);
+  });
+
+  it('detects too many connections', () => {
+    expect(isConnectionError(new Error('FATAL: too many connections for role "postgres"'))).toBe(true);
+  });
+
+  it('does not match regular query errors', () => {
+    expect(isConnectionError(new Error('relation "foo" does not exist'))).toBe(false);
+  });
+
+  it('does not match null/undefined', () => {
+    expect(isConnectionError(null)).toBe(false);
+    expect(isConnectionError(undefined)).toBe(false);
+  });
+
+  it('does not match syntax errors', () => {
+    expect(isConnectionError(new Error('syntax error at or near "SELECT"'))).toBe(false);
+  });
+
+  it('does not match constraint violations', () => {
+    expect(isConnectionError(new Error('duplicate key value violates unique constraint'))).toBe(false);
+  });
+});
+
+// --- Unit tests for worker exit classification ---
+
+function classifyWorkerExit(code: number | null, signal: string | null): string {
+  if (signal === 'SIGKILL') return 'oom_or_external_kill';
+  if (signal === 'SIGTERM') return 'graceful_shutdown';
+  if (code === 1) return 'runtime_error';
+  if (code === 0) return 'clean_exit';
+  return 'unknown';
+}
+
+describe('classifyWorkerExit', () => {
+  it('classifies SIGKILL as OOM/external kill', () => {
+    expect(classifyWorkerExit(null, 'SIGKILL')).toBe('oom_or_external_kill');
+  });
+
+  it('classifies SIGTERM as graceful shutdown', () => {
+    expect(classifyWorkerExit(null, 'SIGTERM')).toBe('graceful_shutdown');
+  });
+
+  it('classifies exit code 1 as runtime error', () => {
+    expect(classifyWorkerExit(1, null)).toBe('runtime_error');
+  });
+
+  it('classifies exit code 0 as clean exit', () => {
+    expect(classifyWorkerExit(0, null)).toBe('clean_exit');
+  });
+
+  it('classifies unknown codes as unknown', () => {
+    expect(classifyWorkerExit(137, null)).toBe('unknown');
+    expect(classifyWorkerExit(null, null)).toBe('unknown');
+  });
+
+  // Signal takes precedence over code
+  it('SIGKILL takes precedence over any exit code', () => {
+    expect(classifyWorkerExit(1, 'SIGKILL')).toBe('oom_or_external_kill');
+  });
+});
+
+// --- Mock-based tests for reconnect logic ---
+
+describe('PostgresEngine reconnect behavior', () => {
+  it('reconnect flag prevents concurrent reconnections', async () => {
+    // Simulate the _reconnecting guard
+    let reconnecting = false;
+    let reconnectCount = 0;
+
+    async function reconnect() {
+      if (reconnecting) return;
+      reconnecting = true;
+      try {
+        reconnectCount++;
+        await new Promise(r => setTimeout(r, 10));
+      } finally {
+        reconnecting = false;
+      }
+    }
+
+    // Fire 3 concurrent reconnects — only 1 should run
+    await Promise.all([reconnect(), reconnect(), reconnect()]);
+    expect(reconnectCount).toBe(1);
+  });
+
+  it('executeRaw retry does not infinite-loop on persistent connection failure', async () => {
+    // Simulate: first call fails (connection error), reconnect succeeds,
+    // but retry also fails with a NON-connection error
+    let callCount = 0;
+
+    async function executeRawWithRetry(): Promise<unknown[]> {
+      callCount++;
+      if (callCount === 1) {
+        throw new Error('connection terminated'); // connection error → triggers retry
+      }
+      if (callCount === 2) {
+        throw new Error('relation "foo" does not exist'); // NOT a connection error → throw
+      }
+      return [{ ok: true }];
+    }
+
+    try {
+      await (async () => {
+        try {
+          return await executeRawWithRetry();
+        } catch (err) {
+          if (isConnectionError(err)) {
+            // "reconnect" would happen here
+            return await executeRawWithRetry();
+          }
+          throw err;
+        }
+      })();
+    } catch (err) {
+      expect((err as Error).message).toBe('relation "foo" does not exist');
+    }
+
+    expect(callCount).toBe(2); // Only 2 attempts, no infinite loop
+  });
+
+  it('executeRaw succeeds on retry after connection error', async () => {
+    let callCount = 0;
+
+    async function executeRawWithRetry(): Promise<unknown[]> {
+      callCount++;
+      if (callCount === 1) {
+        throw new Error('password authentication failed for user "postgres"');
+      }
+      return [{ ok: true }];
+    }
+
+    const result = await (async () => {
+      try {
+        return await executeRawWithRetry();
+      } catch (err) {
+        if (isConnectionError(err)) {
+          // reconnect would happen here
+          return await executeRawWithRetry();
+        }
+        throw err;
+      }
+    })();
+
+    expect(result).toEqual([{ ok: true }]);
+    expect(callCount).toBe(2);
+  });
+});
+
+// --- Supervisor health check failure tracking ---
+
+describe('Supervisor health check failure tracking', () => {
+  it('emits db_connection_degraded after 3 consecutive failures', () => {
+    let consecutiveFailures = 0;
+    const emitted: Array<{ event: string; reason?: string }> = [];
+
+    function emit(event: string, fields: Record<string, unknown> = {}) {
+      emitted.push({ event, ...fields } as { event: string; reason?: string });
+    }
+
+    // Simulate 3 health check failures
+    for (let i = 0; i < 4; i++) {
+      consecutiveFailures++;
+      if (consecutiveFailures >= 3) {
+        emit('health_warn', { reason: 'db_connection_degraded', consecutive_failures: consecutiveFailures });
+      } else {
+        emit('health_error', { error: 'connection terminated' });
+      }
+    }
+
+    const degradedWarnings = emitted.filter(e => e.reason === 'db_connection_degraded');
+    expect(degradedWarnings.length).toBe(2); // fires at count 3 and 4
+
+    // First two were regular health_error
+    expect(emitted[0].event).toBe('health_error');
+    expect(emitted[1].event).toBe('health_error');
+    // Third triggers the degraded warning
+    expect(emitted[2].reason).toBe('db_connection_degraded');
+  });
+
+  it('resets failure counter on successful health check', () => {
+    let consecutiveFailures = 0;
+
+    // 2 failures
+    consecutiveFailures++;
+    consecutiveFailures++;
+    expect(consecutiveFailures).toBe(2);
+
+    // Success resets
+    consecutiveFailures = 0;
+    expect(consecutiveFailures).toBe(0);
+
+    // 1 more failure — should not trigger degraded (need 3 consecutive)
+    consecutiveFailures++;
+    expect(consecutiveFailures).toBeLessThan(3);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────
+// Eng-review D3 regression guards — executeRaw retry wrapper dropped
+// ─────────────────────────────────────────────────────────────────
+//
+// The original #406 wrapped PostgresEngine.executeRaw in a per-call
+// try/catch that retried on connection errors. Eng-review D3 dropped
+// that wrapper as unsound (regex idempotence boundary doesn't hold
+// for writable CTEs or side-effecting SELECTs). Recovery now happens
+// at the supervisor level via the 3-strikes-then-reconnect path.
+//
+// These guards prevent reintroduction of the per-call retry without
+// a typed-idempotency boundary.
+
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+describe('Eng-review D3 — executeRaw has no per-call retry wrapper', () => {
+  it('PostgresEngine.executeRaw is a single-statement passthrough (no try/catch on connection errors)', () => {
+    const src = readFileSync(resolve('src/core/postgres-engine.ts'), 'utf-8');
+
+    // Find the executeRaw method in the class (not the helper inside withReservedConnection)
+    // Pattern: must be a method on the class taking (sql, params)
+    const fnMatch = src.match(/async executeRaw<T = Record<string, unknown>>\(sql: string, params\?: unknown\[\]\): Promise<T\[\]> \{([\s\S]*?)\n  \}/);
+    expect(fnMatch).not.toBeNull();
+    const body = fnMatch![1];
+
+    // Must not have any try/catch
+    expect(body).not.toContain('try {');
+    expect(body).not.toContain('catch');
+    // Must not call reconnect() from this method
+    expect(body).not.toContain('this.reconnect()');
+    // Must call conn.unsafe directly
+    expect(body).toContain('conn.unsafe(');
+  });
+
+  it('PostgresEngine.reconnect() still exists for supervisor-driven recovery', () => {
+    const src = readFileSync(resolve('src/core/postgres-engine.ts'), 'utf-8');
+    expect(src).toContain('async reconnect()');
+    expect(src).toContain('await this.disconnect()');
+  });
+
+  it('Supervisor still has the 3-strikes-then-reconnect path', () => {
+    const src = readFileSync(resolve('src/core/minions/supervisor.ts'), 'utf-8');
+    expect(src).toContain('consecutiveHealthFailures');
+    // Supervisor invokes reconnect via a typed cast after 3 consecutive failures.
+    expect(src).toMatch(/reconnect\(\): Promise<void>/);
+    expect(src).toContain('this.consecutiveHealthFailures >= 3');
+  });
+});

test/core/cycle.test.ts

@@ -17,8 +17,8 @@ import { existsSync, unlinkSync } from 'fs';
 
 let lintCalls: Array<{ target: string; fix: boolean; dryRun: boolean | undefined }> = [];
 let backlinksCalls: Array<{ action: string; dir: string; dryRun: boolean | undefined }> = [];
-let syncCalls: Array<{ dryRun: boolean | undefined; noPull: boolean | undefined }> = [];
-let extractCalls: Array<{ mode: string; dir: string }> = [];
+let syncCalls: Array<{ dryRun: boolean | undefined; noPull: boolean | undefined; noExtract: boolean | undefined; sourceId: string | undefined }> = [];
+let extractCalls: Array<{ mode: string; dir: string; slugs: string[] | undefined }> = [];
 let embedCalls: Array<{ stale: boolean | undefined; dryRun: boolean | undefined }> = [];
 let orphansCalls: number = 0;
 
@@ -49,7 +49,7 @@ mock.module('../../src/commands/backlinks.ts', () => ({
 // Mock sync
 mock.module('../../src/commands/sync.ts', () => ({
   performSync: async (_engine: any, opts: any) => {
-    syncCalls.push({ dryRun: opts.dryRun, noPull: opts.noPull });
+    syncCalls.push({ dryRun: opts.dryRun, noPull: opts.noPull, noExtract: opts.noExtract, sourceId: opts.sourceId });
     return {
       status: opts.dryRun ? 'dry_run' : 'synced',
       fromCommit: 'abcd',
@@ -72,8 +72,8 @@ mock.module('../../src/commands/sync.ts', () => ({
 // Mock extract
 mock.module('../../src/commands/extract.ts', () => ({
   runExtractCore: async (_engine: any, opts: any) => {
-    extractCalls.push({ mode: opts.mode, dir: opts.dir });
-    return { links_created: 7, timeline_entries_created: 3, pages_processed: 5 };
+    extractCalls.push({ mode: opts.mode, dir: opts.dir, slugs: opts.slugs });
+    return { links_created: 7, timeline_entries_created: 3, pages_processed: opts.slugs?.length ?? 5 };
   },
   walkMarkdownFiles: () => [],
   extractMarkdownLinks: () => [],
@@ -392,3 +392,151 @@ describe('runCycle — yieldBetweenPhases hook', () => {
     expect(report.phases.length).toBe(6);
   });
 });
+
+// ─────────────────────────────────────────────────────────────────
+// Wave regression guards (#417 + Codex F2)
+// ─────────────────────────────────────────────────────────────────
+
+describe('runCycle — incremental extract slug propagation (#417)', () => {
+  beforeEach(async () => {
+    await truncateCycleLocks(sharedEngine);
+    syncCalls = [];
+    extractCalls = [];
+  });
+
+  test('cycle threads sync.pagesAffected into extract phase as the slugs argument', async () => {
+    // performSync mock returns pagesAffected = ['a', 'b']. The extract phase
+    // must receive those exact slugs, not undefined (which would trigger a full walk).
+    await runCycle(sharedEngine, { brainDir: '/tmp/brain' });
+
+    // Sync ran once
+    expect(syncCalls.length).toBe(1);
+    // Extract ran once with the slugs from sync (not undefined)
+    expect(extractCalls.length).toBe(1);
+    expect(extractCalls[0].slugs).toEqual(['a', 'b']);
+  });
+
+  test('extract phase falls back to full walk when sync was skipped (slugs undefined)', async () => {
+    // Run only the extract phase — sync didn't run, so syncPagesAffected
+    // is undefined and extract should walk the full directory (slugs:undefined).
+    await runCycle(sharedEngine, { brainDir: '/tmp/brain', phases: ['extract'] });
+
+    expect(syncCalls.length).toBe(0);
+    expect(extractCalls.length).toBe(1);
+    expect(extractCalls[0].slugs).toBeUndefined();
+  });
+});
+
+describe('runCycle — Codex F2: noExtract is gated on whether extract phase runs', () => {
+  beforeEach(async () => {
+    await truncateCycleLocks(sharedEngine);
+    syncCalls = [];
+    extractCalls = [];
+  });
+
+  test('full cycle (sync + extract): noExtract=true so sync skips inline extraction (extract phase handles it)', async () => {
+    await runCycle(sharedEngine, { brainDir: '/tmp/brain', phases: ['sync', 'extract'] });
+
+    expect(syncCalls.length).toBe(1);
+    expect(syncCalls[0].noExtract).toBe(true);  // dedupe enabled
+    expect(extractCalls.length).toBe(1);        // extract phase ran
+  });
+
+  test('phases:[sync] only: noExtract=false so sync runs inline extraction (no silent extract drop)', async () => {
+    await runCycle(sharedEngine, { brainDir: '/tmp/brain', phases: ['sync'] });
+
+    expect(syncCalls.length).toBe(1);
+    // Critical: noExtract must be false here. If it were true, the user just lost
+    // their extraction without any indication. This is the F2 regression guard.
+    expect(syncCalls[0].noExtract).toBe(false);
+    expect(extractCalls.length).toBe(0); // extract phase did NOT run
+  });
+});
+
+// ─── sourceId resolution (regression #475) ─────────────────────────
+//
+// Production OpenClaw deployment hit a 30+ min hang on every autopilot
+// cycle because runPhaseSync was calling performSync without sourceId,
+// so sync read the global config.sync.last_commit key (which had drifted
+// out of git history after a force-push GC'd the commit). The per-source
+// sources.last_commit anchor was valid the entire time. PR #475 added
+// resolveSourceForDir() so the cycle reads the per-source anchor instead.
+//
+// These tests pin the resolver -> performSync(opts.sourceId) plumbing.
+
+describe('runCycle — sourceId resolution (regression #475)', () => {
+  beforeEach(async () => {
+    await truncateCycleLocks(sharedEngine);
+    await (sharedEngine as any).db.query('DELETE FROM sources');
+  });
+
+  test('seeded sources row → performSync receives matching sourceId', async () => {
+    await (sharedEngine as any).db.query(
+      `INSERT INTO sources (id, name, local_path) VALUES ($1, $2, $3)`,
+      ['default', 'default', '/tmp/brain-475-a'],
+    );
+    await runCycle(sharedEngine, { brainDir: '/tmp/brain-475-a' });
+    expect(syncCalls.at(-1)?.sourceId).toBe('default');
+  });
+
+  test('no matching sources row → performSync receives sourceId=undefined', async () => {
+    await runCycle(sharedEngine, { brainDir: '/tmp/brain-475-b' });
+    expect(syncCalls.at(-1)?.sourceId).toBeUndefined();
+  });
+
+  test('different brainDir than registered source → undefined (no cross-match)', async () => {
+    await (sharedEngine as any).db.query(
+      `INSERT INTO sources (id, name, local_path) VALUES ($1, $2, $3)`,
+      ['other', 'other', '/some/other/brain'],
+    );
+    await runCycle(sharedEngine, { brainDir: '/tmp/brain-475-c' });
+    expect(syncCalls.at(-1)?.sourceId).toBeUndefined();
+  });
+
+  test('sources table missing (very old brain) → catch returns undefined, sync still runs', async () => {
+    // CRITICAL: do NOT DROP TABLE on the shared engine. initSchema() only
+    // re-runs PENDING migrations; once schema_version is at latest, the
+    // v20 migration that creates `sources` will not re-execute. Use a
+    // fresh one-shot engine so the shared engine isn't degraded for
+    // every later test in this file.
+    const fresh = new PGLiteEngine();
+    await fresh.connect({});
+    await fresh.initSchema();
+    await (fresh as any).db.query('DROP TABLE IF EXISTS sources CASCADE');
+    try {
+      await runCycle(fresh, { brainDir: '/tmp/brain-475-d' });
+      expect(syncCalls.at(-1)?.sourceId).toBeUndefined();
+    } finally {
+      await fresh.disconnect();
+    }
+  });
+
+  test('multiple rows with same local_path → resolver returns one matching id (non-deterministic)', async () => {
+    // Schema has no UNIQUE on local_path; SQL has no ORDER BY. Either id
+    // is acceptable; the contract is "any matching id, never null when
+    // matches exist." This test pins behavior so the follow-up
+    // UNIQUE-constraint TODO has a regression target.
+    await (sharedEngine as any).db.query(
+      `INSERT INTO sources (id, name, local_path) VALUES
+        ('first', 'first', '/tmp/brain-475-e'),
+        ('second', 'second', '/tmp/brain-475-e')`,
+    );
+    await runCycle(sharedEngine, { brainDir: '/tmp/brain-475-e' });
+    const sourceId = syncCalls.at(-1)?.sourceId;
+    expect(sourceId).toBeDefined();
+    expect(['first', 'second']).toContain(sourceId as string);
+  });
+
+  test('empty-string id row → resolver propagates as "" (defensive)', async () => {
+    // Schema has id as PRIMARY KEY (NOT NULL), so NULL id can't happen.
+    // Empty string CAN be inserted, and the resolver's `rows[0]?.id`
+    // would treat any falsy id as "no source" via the optional chain.
+    // This test pins the current behavior (we DO pass '' through to
+    // performSync) so a future refactor doesn't silently regress it.
+    await (sharedEngine as any).db.query(
+      `INSERT INTO sources (id, name, local_path) VALUES ('', 'empty', '/tmp/brain-475-f')`,
+    );
+    await runCycle(sharedEngine, { brainDir: '/tmp/brain-475-f' });
+    expect(syncCalls.at(-1)?.sourceId).toBe('');
+  });
+});

test/cycle-abort.test.ts

@@ -0,0 +1,148 @@
+/**
+ * test/cycle-abort.test.ts — Verify runCycle respects AbortSignal.
+ *
+ * Regression test for the 2026-04-24 incident where 98 jobs piled up
+ * because autopilot-cycle's handler didn't propagate AbortSignal to
+ * runCycle, and runCycle had no signal-checking between phases.
+ *
+ * Tests the three-layer fix:
+ *   1. CycleOpts.signal — runCycle checks signal between phases
+ *   2. Handler wiring — autopilot-cycle passes job.signal
+ *   3. Worker force-eviction — last resort if handler ignores abort
+ *
+ * Layer 3 is tested in minions.test.ts (worker-level). This file
+ * covers layers 1 and 2 via the cycle interface.
+ */
+
+import { describe, test, expect } from 'bun:test';
+
+// We can't easily import runCycle with a real engine for unit tests,
+// but we CAN test the checkAborted pattern and CycleOpts contract.
+
+describe('CycleOpts.signal contract (v0.20.5)', () => {
+  test('signal field exists on CycleOpts interface', async () => {
+    // Type-level test: importing the type should work
+    const mod = await import('../src/core/cycle.ts');
+    // runCycle exists and is callable
+    expect(typeof mod.runCycle).toBe('function');
+  });
+
+  test('runCycle accepts signal in opts without error', async () => {
+    // Verify runCycle doesn't crash when signal is passed but no engine
+    const { runCycle } = await import('../src/core/cycle.ts');
+    const abort = new AbortController();
+
+    // Call with null engine + minimal opts — should return a report
+    // (phases that need engine will be skipped)
+    const report = await runCycle(null, {
+      brainDir: '/nonexistent-for-test',
+      phases: [], // empty phases = no work
+      signal: abort.signal,
+    });
+
+    expect(report.schema_version).toBe('1');
+    expect(report.status).toBeDefined();
+  });
+
+  test('runCycle bails on pre-aborted signal', async () => {
+    const { runCycle } = await import('../src/core/cycle.ts');
+    const abort = new AbortController();
+    abort.abort(new Error('timeout'));
+
+    // With a pre-aborted signal and phases that would run, it should
+    // throw or return failed (depending on which phase catches it first)
+    try {
+      const report = await runCycle(null, {
+        brainDir: '/nonexistent-for-test',
+        phases: ['lint'], // lint doesn't need engine, would normally run
+        signal: abort.signal,
+      });
+      // If it returns instead of throwing, status should reflect the abort
+      expect(['failed', 'partial']).toContain(report.status);
+    } catch (err) {
+      // checkAborted threw — this is the expected behavior
+      expect(err instanceof Error).toBe(true);
+      expect((err as Error).message).toContain('aborted');
+    }
+  });
+
+  test('runCycle bails mid-flight when signal fires between phases', async () => {
+    const { runCycle } = await import('../src/core/cycle.ts');
+    const abort = new AbortController();
+
+    // Abort after 50ms — should catch between phases
+    setTimeout(() => abort.abort(new Error('timeout')), 50);
+
+    try {
+      const report = await runCycle(null, {
+        brainDir: '/nonexistent-for-test',
+        phases: ['lint', 'backlinks', 'orphans'],
+        signal: abort.signal,
+        yieldBetweenPhases: async () => {
+          // Slow yield to give the abort time to fire
+          await new Promise(r => setTimeout(r, 100));
+        },
+      });
+      // If it returned cleanly, not all phases should have run
+      // (abort should have prevented later phases)
+      const completedPhases = report.phases.length;
+      expect(completedPhases).toBeLessThan(3);
+    } catch (err) {
+      // checkAborted threw between phases — expected
+      expect(err instanceof Error).toBe(true);
+      expect((err as Error).message).toContain('aborted');
+    }
+  });
+});
+
+describe('autopilot-cycle handler contract (v0.20.5)', () => {
+  test('handler registration passes signal to runCycle', async () => {
+    // Verify the handler code in jobs.ts includes job.signal
+    const fs = await import('fs');
+    const jobsSource = fs.readFileSync(
+      new URL('../src/commands/jobs.ts', import.meta.url),
+      'utf8',
+    );
+
+    // The autopilot-cycle handler MUST pass signal to runCycle
+    // This is a source-level regression guard
+    const handlerBlock = jobsSource.slice(
+      jobsSource.indexOf("worker.register('autopilot-cycle'"),
+      jobsSource.indexOf("worker.register('autopilot-cycle'") + 500,
+    );
+
+    expect(handlerBlock).toContain('signal: job.signal');
+  });
+
+  test('worker.ts has force-eviction safety net after timeout', async () => {
+    // Verify the worker code includes the grace timer
+    const fs = await import('fs');
+    const workerSource = fs.readFileSync(
+      new URL('../src/core/minions/worker.ts', import.meta.url),
+      'utf8',
+    );
+
+    // Must have the force-eviction pattern
+    expect(workerSource).toContain('Force-evicting from inFlight');
+    expect(workerSource).toContain('graceTimer');
+    expect(workerSource).toContain('handler ignored abort signal');
+  });
+
+  test('cycle.ts has checkAborted calls between phases', async () => {
+    // Verify the cycle code checks abort between every phase
+    const fs = await import('fs');
+    const cycleSource = fs.readFileSync(
+      new URL('../src/core/cycle.ts', import.meta.url),
+      'utf8',
+    );
+
+    // Count checkAborted calls in the runCycle function body
+    const runCycleBody = cycleSource.slice(
+      cycleSource.indexOf('export async function runCycle'),
+    );
+    const checkCalls = (runCycleBody.match(/checkAborted\(opts\.signal\)/g) || []).length;
+
+    // Should have at least 6 (one per phase)
+    expect(checkCalls).toBeGreaterThanOrEqual(6);
+  });
+});

test/doctor-minions-check.test.ts

@@ -146,7 +146,9 @@ describe('gbrain doctor — half-migrated Minions detection', () => {
 
   test('filesystem: multiple versions each need their own complete entry', () => {
     // v0.10 is fully migrated but v0.11 is only partial. Doctor should
-    // flag v0.11 by name.
+    // flag v0.11 by name. The forward-progress override only kicks in
+    // when a NEWER version completed; v0.10 is older than v0.11 so the
+    // partial still stands.
     const migrationsDir = join(tmp, '.gbrain', 'migrations');
     mkdirSync(migrationsDir, { recursive: true });
     writeFileSync(
@@ -166,6 +168,65 @@ describe('gbrain doctor — half-migrated Minions detection', () => {
     expect(minions!.message).not.toContain('0.10.0');
   });
 
+  test('filesystem: stale partial superseded by newer complete → NO warning (forward-progress override)', () => {
+    // v0.16.0 completed AFTER v0.11.0 went partial. The schema clearly
+    // advanced past v0.11.0, so the partial record is stale historical
+    // noise — not a real "MINIONS HALF-INSTALLED" condition.
+    //
+    // Without this override, every install that ever went through a
+    // v0.11.0 stopgap and then upgraded carries the FAIL flag forever,
+    // even on installs that have been at v0.22+ for months. Real cause:
+    // long-running gbrain installs accumulate partial entries from
+    // historical stopgap runs; a doctor flag with no time decay or
+    // forward-progress detection becomes meaningless once you've
+    // moved past those versions.
+    const migrationsDir = join(tmp, '.gbrain', 'migrations');
+    mkdirSync(migrationsDir, { recursive: true });
+    writeFileSync(
+      join(migrationsDir, 'completed.jsonl'),
+      [
+        JSON.stringify({ version: '0.16.0', status: 'complete', ts: '2026-04-26T06:13:50.825Z' }),
+        JSON.stringify({ version: '0.11.0', status: 'partial', ts: '2026-04-26T06:16:56.298Z' }),
+        JSON.stringify({ version: '0.11.0', status: 'partial', ts: '2026-04-26T06:19:03.617Z' }),
+      ].join('\n') + '\n',
+    );
+
+    const result = run(['doctor', '--fast', '--json']);
+    // No FAIL on minions_migration — the v0.11.0 partials are stale
+    // because v0.16.0 (a newer release) completed.
+    const checks = JSON.parse(result.stdout).checks as Array<{ name: string; status: string }>;
+    const minions = checks.find(c => c.name === 'minions_migration');
+    if (minions) {
+      expect(minions.status).not.toBe('fail');
+    }
+    // Critically: the test fixture would have caused exit 1 under the old
+    // (no-override) logic because of the stale partial flag. Under the new
+    // logic, doctor exits 0 (or only warns about non-related checks).
+    expect(result.exitCode).toBe(0);
+  });
+
+  test('filesystem: stale partial NOT superseded → still flagged', () => {
+    // The override only fires when a >= partial version has completed.
+    // Older completes (e.g. v0.10 complete + v0.16 partial) do NOT
+    // supersede the partial; the partial still indicates a real problem.
+    const migrationsDir = join(tmp, '.gbrain', 'migrations');
+    mkdirSync(migrationsDir, { recursive: true });
+    writeFileSync(
+      join(migrationsDir, 'completed.jsonl'),
+      [
+        JSON.stringify({ version: '0.10.0', status: 'complete' }),
+        JSON.stringify({ version: '0.16.0', status: 'partial' }),
+      ].join('\n') + '\n',
+    );
+
+    const result = run(['doctor', '--fast', '--json']);
+    expect(result.exitCode).toBe(1);
+    const checks = JSON.parse(result.stdout).checks as Array<{ name: string; status: string; message: string }>;
+    const minions = checks.find(c => c.name === 'minions_migration');
+    expect(minions!.status).toBe('fail');
+    expect(minions!.message).toContain('0.16.0');
+  });
+
   test('human output: prints MINIONS HALF-INSTALLED loud banner', () => {
     // Same fixture as the first test, but check the human-readable output
     // includes the exact banner phrase an OpenClaw host's cron script

test/doctor.test.ts

@@ -21,6 +21,16 @@ describe('doctor command', () => {
     expect(stdout).toContain('--fast');
   });
 
+  test('frontmatter_integrity subcheck added in v0.22.4', async () => {
+    const fs = await import('fs');
+    const src = fs.readFileSync('src/commands/doctor.ts', 'utf8');
+    // Subcheck name and call into shared scanner are present.
+    expect(src).toContain("name: 'frontmatter_integrity'");
+    expect(src).toContain('scanBrainSources');
+    // Fix hint points at the right CLI command.
+    expect(src).toContain('gbrain frontmatter validate');
+  });
+
   test('Check interface supports issues array', async () => {
     // `Check` is a TypeScript interface — type-only, no runtime value.
     // Importing it for type assertion is enough to validate the shape.

test/e2e/engine-parity.test.ts

@@ -0,0 +1,227 @@
+/**
+ * Engine Parity E2E
+ *
+ * Codex flagged that searchKeyword behavior differs structurally between
+ * the two engines (Postgres uses a CTE that ranks pages then picks best
+ * chunk; PGLite returns chunks directly). Without verification, source-aware
+ * ranking could pass on PGLite and silently fail on Postgres.
+ *
+ * Strategy: seed identical corpora into both engines, run identical queries,
+ * assert top-5 slug ordering matches.
+ *
+ * Gated by DATABASE_URL — skips gracefully if no real Postgres. Always runs
+ * the PGLite half so the seed/query path is at least exercised.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
+import type { ChunkInput, SearchResult } from '../../src/core/types.ts';
+import type { BrainEngine } from '../../src/core/engine.ts';
+import { hasDatabase, setupDB, teardownDB, getEngine } from './helpers.ts';
+
+const SKIP_PG = !hasDatabase();
+const describeBoth = SKIP_PG ? describe.skip : describe;
+
+function basisEmbedding(idx: number, dim = 1536): Float32Array {
+  const emb = new Float32Array(dim);
+  emb[idx % dim] = 1.0;
+  return emb;
+}
+
+interface SeedPage {
+  slug: string;
+  type: 'writing' | 'concept' | 'note' | 'person' | 'company';
+  title: string;
+  body: string;
+  embeddingDim: number;
+}
+
+const SEED_PAGES: SeedPage[] = [
+  {
+    slug: 'originals/talks/article-outline-fat-code',
+    type: 'writing',
+    title: 'Fat Code Thin Harness — Part 3',
+    body: 'fat code thin harness pattern part 3 production case studies',
+    embeddingDim: 7,
+  },
+  {
+    slug: 'concepts/fat-code-thin-harness',
+    type: 'concept',
+    title: 'Fat Code Thin Harness',
+    body: 'reusable concept fat code thin harness architecture',
+    embeddingDim: 14,
+  },
+  {
+    slug: 'wintermute/chat/2026-04-15',
+    type: 'note',
+    title: '2026-04-15 chat',
+    body:
+      'fat code thin harness fat code thin harness discussion went on at length, ' +
+      'fat code thin harness came up again and again, fat code thin harness fat code thin harness.',
+    embeddingDim: 8,
+  },
+  {
+    slug: 'wintermute/chat/2026-04-16',
+    type: 'note',
+    title: '2026-04-16 chat',
+    body:
+      'fat code thin harness once more, fat code thin harness fat code thin harness, ' +
+      'still talking about fat code thin harness fat code thin harness.',
+    embeddingDim: 9,
+  },
+  {
+    slug: 'people/example-founder',
+    type: 'person',
+    title: 'Example Founder',
+    body: 'example founder unrelated content for distraction',
+    embeddingDim: 50,
+  },
+];
+
+async function seedEngine(eng: BrainEngine) {
+  for (const p of SEED_PAGES) {
+    await eng.putPage(p.slug, {
+      type: p.type,
+      title: p.title,
+      compiled_truth: p.body,
+      timeline: '',
+    });
+    const chunks: ChunkInput[] = [
+      {
+        chunk_index: 0,
+        chunk_text: p.body,
+        chunk_source: 'compiled_truth',
+        embedding: basisEmbedding(p.embeddingDim),
+        token_count: p.body.split(/\s+/).length,
+      },
+    ];
+    await eng.upsertChunks(p.slug, chunks);
+  }
+}
+
+const QUERIES = [
+  'fat code thin harness',
+  'fat code thin harness part 3',
+  'fat code production',
+];
+
+describeBoth('Engine parity — Postgres vs PGLite', () => {
+  let pgEngine: BrainEngine;
+  let pgliteEngine: PGLiteEngine;
+
+  beforeAll(async () => {
+    pgEngine = await setupDB();
+    await seedEngine(pgEngine);
+
+    pgliteEngine = new PGLiteEngine();
+    await pgliteEngine.connect({});
+    await pgliteEngine.initSchema();
+    await seedEngine(pgliteEngine);
+  }, 90_000);
+
+  afterAll(async () => {
+    await pgliteEngine.disconnect();
+    await teardownDB();
+  });
+
+  for (const q of QUERIES) {
+    test(`searchKeyword: top-5 slugs match for "${q}"`, async () => {
+      const pgResults = await pgEngine.searchKeyword(q, { limit: 5 });
+      const pgliteResults = await pgliteEngine.searchKeyword(q, { limit: 5 });
+
+      const pgSlugs = pgResults.map((r: SearchResult) => r.slug);
+      const pgliteSlugs = pgliteResults.map((r: SearchResult) => r.slug);
+
+      // Top result MUST match (the swamp-resistance guarantee).
+      expect(pgSlugs[0]).toBe(pgliteSlugs[0]);
+      // Sets should match (allowing some ordering drift on lower-ranked
+      // results since FTS rank function differences between engines are
+      // out of scope for this fix).
+      expect(new Set(pgSlugs)).toEqual(new Set(pgliteSlugs));
+    });
+  }
+
+  test('searchVector: top result matches between engines', async () => {
+    const queryVec = basisEmbedding(7); // article direction
+    const pgResults = await pgEngine.searchVector(queryVec, { limit: 5 });
+    const pgliteResults = await pgliteEngine.searchVector(queryVec, { limit: 5 });
+
+    expect(pgResults[0]?.slug).toBe(pgliteResults[0]?.slug);
+  });
+
+  test('hard-exclude is consistent across engines', async () => {
+    // Both engines should hide test/ pages by default; both should opt
+    // them back in via include_slug_prefixes.
+    await pgEngine.putPage('test/parity-fixture', {
+      type: 'note',
+      title: 'parity test fixture',
+      compiled_truth: 'parity test fixture content',
+      timeline: '',
+    });
+    await pgEngine.upsertChunks('test/parity-fixture', [{
+      chunk_index: 0,
+      chunk_text: 'parity test fixture content',
+      chunk_source: 'compiled_truth',
+      embedding: basisEmbedding(20),
+      token_count: 5,
+    }] satisfies ChunkInput[]);
+
+    await pgliteEngine.putPage('test/parity-fixture', {
+      type: 'note',
+      title: 'parity test fixture',
+      compiled_truth: 'parity test fixture content',
+      timeline: '',
+    });
+    await pgliteEngine.upsertChunks('test/parity-fixture', [{
+      chunk_index: 0,
+      chunk_text: 'parity test fixture content',
+      chunk_source: 'compiled_truth',
+      embedding: basisEmbedding(20),
+      token_count: 5,
+    }] satisfies ChunkInput[]);
+
+    const pgDefault = await pgEngine.searchKeyword('parity test fixture');
+    const pgliteDefault = await pgliteEngine.searchKeyword('parity test fixture');
+    expect(pgDefault.map((r: SearchResult) => r.slug)).not.toContain('test/parity-fixture');
+    expect(pgliteDefault.map((r: SearchResult) => r.slug)).not.toContain('test/parity-fixture');
+
+    const pgOptIn = await pgEngine.searchKeyword('parity test fixture', {
+      include_slug_prefixes: ['test/'],
+    });
+    const pgliteOptIn = await pgliteEngine.searchKeyword('parity test fixture', {
+      include_slug_prefixes: ['test/'],
+    });
+    expect(pgOptIn.map((r: SearchResult) => r.slug)).toContain('test/parity-fixture');
+    expect(pgliteOptIn.map((r: SearchResult) => r.slug)).toContain('test/parity-fixture');
+  });
+
+  test('detail=high produces a different ranking than default on at least one engine', async () => {
+    // Source-boost gates on `detail !== 'high'`. If the gate works on both
+    // engines, the ordering for `detail=high` should differ from default in
+    // any case where the swamp / curated pages have different raw scores.
+    //
+    // Postgres's CTE ranks pages then picks best chunk; ts_rank normalizes
+    // by doc length so chat pages don't always swamp at the page level.
+    // PGLite scores chunks directly — chat chunks beat article chunks on
+    // raw ts_rank. The two engines need different parity contracts here.
+    //
+    // Common assertion that holds on both: detail=high must include the
+    // chat pages in its result set (they're not filtered by detail), and
+    // the result set should not be identical to default-detail (the boost
+    // must be doing _something_ visible).
+    const pgDefault = await pgEngine.searchKeyword('fat code thin harness', { limit: 5 });
+    const pgHigh = await pgEngine.searchKeyword('fat code thin harness', { detail: 'high', limit: 5 });
+    const pgliteDefault = await pgliteEngine.searchKeyword('fat code thin harness', { limit: 5 });
+    const pgliteHigh = await pgliteEngine.searchKeyword('fat code thin harness', { detail: 'high', limit: 5 });
+
+    // Chat pages must be present in detail=high results on both engines.
+    expect(pgHigh.some((r: SearchResult) => r.slug.startsWith('wintermute/chat/'))).toBe(true);
+    expect(pgliteHigh.some((r: SearchResult) => r.slug.startsWith('wintermute/chat/'))).toBe(true);
+
+    // The boost must be doing something — at least one engine's ordering
+    // should change between default and detail=high.
+    const pgChanged = pgDefault.map((r: SearchResult) => r.slug).join(',') !== pgHigh.map((r: SearchResult) => r.slug).join(',');
+    const pgliteChanged = pgliteDefault.map((r: SearchResult) => r.slug).join(',') !== pgliteHigh.map((r: SearchResult) => r.slug).join(',');
+    expect(pgChanged || pgliteChanged).toBe(true);
+  });
+});

test/e2e/frontmatter-migration.test.ts

@@ -0,0 +1,191 @@
+/**
+ * E2E: v0.22.4 frontmatter-guard migration end-to-end on PGLite.
+ *
+ * Closes plan item B14. Runs the v0_22_4 orchestrator against a real PGLite
+ * brain with two registered sources and synthetic malformed brain pages on
+ * disk. Asserts:
+ *   - audit phase writes ~/.gbrain/migrations/v0.22.4-audit.json with the
+ *     expected per-source counts.
+ *   - emit-todo phase appends one entry per source-with-issues to
+ *     ~/.gbrain/migrations/pending-host-work.jsonl, each pointing at
+ *     skills/migrations/v0.22.4.md (dotted convention) with the exact
+ *     gbrain frontmatter validate <source-path> --fix command.
+ *   - The migration is audit-only — no fixture page is mutated during
+ *     apply-migrations.
+ *
+ * Uses the __setTestEngineOverride() injection point on v0_22_4.ts (mirrors
+ * the repair-jsonb test pattern). Bun's os.homedir() doesn't observe
+ * process.env.HOME mutations mid-process, so we redirect via the explicit
+ * test override rather than relying on env-var redirection of loadConfig().
+ *
+ * No DATABASE_URL needed; runs unconditionally in CI's Tier 1.
+ *
+ * Run: bun test test/e2e/frontmatter-migration.test.ts
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
+import { v0_22_4, __setTestEngineOverride } from '../../src/commands/migrations/v0_22_4.ts';
+
+const fence = '---';
+
+let workdir: string;
+let tmpHome: string;
+let brainRootA: string;
+let brainRootB: string;
+let engine: PGLiteEngine;
+let originalHome: string | undefined;
+const originalContents = new Map<string, string>();
+
+beforeAll(async () => {
+  workdir = mkdtempSync(join(tmpdir(), 'fm-migration-e2e-'));
+  tmpHome = join(workdir, 'home');
+  brainRootA = join(workdir, 'brain-a');
+  brainRootB = join(workdir, 'brain-b');
+  mkdirSync(tmpHome, { recursive: true });
+  mkdirSync(brainRootA, { recursive: true });
+  mkdirSync(brainRootB, { recursive: true });
+  mkdirSync(join(tmpHome, '.gbrain', 'migrations'), { recursive: true });
+
+  // Seed fixture brain pages on disk. Source A has 2 broken pages
+  // (NESTED_QUOTES + NULL_BYTES); source B has 1 broken page (NESTED_QUOTES)
+  // plus 1 clean page.
+  const aBrokenNested = `${fence}\ntype: person\ntitle: "Phil "Nick" Last"\n${fence}\n\nbody-a-nested`;
+  const aBrokenNull = `${fence}\ntype: concept\ntitle: ok\n${fence}\n\nbody-a-null\x00drop`;
+  const bBroken = `${fence}\ntype: company\ntitle: "Co "Inc" Name"\n${fence}\n\nbody-b`;
+  const bClean = `${fence}\ntype: concept\ntitle: clean\n${fence}\n\nbody-b-clean`;
+
+  const filesToTrack: Array<{ path: string; content: string }> = [
+    { path: join(brainRootA, 'people', 'phil.md'), content: aBrokenNested },
+    { path: join(brainRootA, 'concepts', 'foo.md'), content: aBrokenNull },
+    { path: join(brainRootB, 'companies', 'co.md'), content: bBroken },
+    { path: join(brainRootB, 'concepts', 'bar.md'), content: bClean },
+  ];
+
+  for (const f of filesToTrack) {
+    mkdirSync(join(f.path, '..'), { recursive: true });
+    writeFileSync(f.path, f.content);
+    originalContents.set(f.path, f.content);
+  }
+
+  // Single in-memory PGLite for the whole test. We inject it into the
+  // orchestrator via __setTestEngineOverride so phaseBAudit skips loadConfig.
+  engine = new PGLiteEngine();
+  await engine.connect({});
+  await engine.initSchema();
+  await engine.executeRaw(
+    `INSERT INTO sources (id, name, local_path) VALUES ($1, $1, $2)`,
+    ['alpha', brainRootA],
+  );
+  await engine.executeRaw(
+    `INSERT INTO sources (id, name, local_path) VALUES ($1, $1, $2)`,
+    ['beta', brainRootB],
+  );
+  __setTestEngineOverride(engine);
+
+  // Redirect ~/.gbrain/migrations/ output. The orchestrator's gbrainDir()
+  // helper reads process.env.HOME at call time, so the override takes
+  // effect even though Bun's os.homedir() does not observe mid-process
+  // mutations.
+  originalHome = process.env.HOME;
+  process.env.HOME = tmpHome;
+});
+
+afterAll(async () => {
+  __setTestEngineOverride(null);
+  if (engine) await engine.disconnect();
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+  rmSync(workdir, { recursive: true, force: true });
+});
+
+describe('E2E: v0.22.4 frontmatter-guard migration', () => {
+  test('orchestrator runs end-to-end and produces the expected artifacts', async () => {
+    const result = await v0_22_4.orchestrator({
+      yes: true,
+      dryRun: false,
+      noAutopilotInstall: true,
+    });
+
+    expect(result.version).toBe('0.22.4');
+    expect(['complete', 'partial']).toContain(result.status);
+    expect(result.phases.length).toBe(3);
+    const auditPhase = result.phases.find((p) => p.name === 'audit')!;
+    expect(auditPhase.status).toBe('complete');
+    const emitPhase = result.phases.find((p) => p.name === 'emit-todo')!;
+    expect(emitPhase.status).toBe('complete');
+    expect(result.pending_host_work).toBe(2);
+  });
+
+  test('audit JSON report exists and has per-source counts', () => {
+    const reportPath = join(tmpHome, '.gbrain', 'migrations', 'v0.22.4-audit.json');
+    expect(existsSync(reportPath)).toBe(true);
+    const report = JSON.parse(readFileSync(reportPath, 'utf8'));
+
+    expect(report.ok).toBe(false);
+    expect(report.total).toBeGreaterThan(0);
+    expect(report.scanned_at).toMatch(/\d{4}-\d{2}-\d{2}T/);
+
+    const alpha = report.per_source.find((s: any) => s.source_id === 'alpha');
+    const beta = report.per_source.find((s: any) => s.source_id === 'beta');
+    expect(alpha).toBeDefined();
+    expect(beta).toBeDefined();
+
+    // Source A has NESTED_QUOTES (in phil.md) and NULL_BYTES (in foo.md).
+    // YAML_PARSE may also fire on the nested-quote page since gray-matter
+    // throws — assert each expected code shows up at least once.
+    expect(alpha.errors_by_code.NESTED_QUOTES).toBeGreaterThanOrEqual(1);
+    expect(alpha.errors_by_code.NULL_BYTES).toBeGreaterThanOrEqual(1);
+    expect(alpha.total).toBeGreaterThanOrEqual(2);
+    expect(beta.errors_by_code.NESTED_QUOTES).toBeGreaterThanOrEqual(1);
+    expect(beta.total).toBeGreaterThanOrEqual(1);
+
+    // Sample lists carry the affected file paths for each source.
+    expect(alpha.sample.some((s: any) => s.path.includes('phil.md'))).toBe(true);
+    expect(beta.sample.some((s: any) => s.path.includes('co.md'))).toBe(true);
+  });
+
+  test('pending-host-work.jsonl carries one entry per source-with-issues', () => {
+    const jsonlPath = join(tmpHome, '.gbrain', 'migrations', 'pending-host-work.jsonl');
+    expect(existsSync(jsonlPath)).toBe(true);
+    const lines = readFileSync(jsonlPath, 'utf8').split('\n').filter(Boolean);
+    expect(lines.length).toBe(2);
+
+    const entries = lines.map((l) => JSON.parse(l));
+    const ids = entries.map((e: any) => e.source_id).sort();
+    expect(ids).toEqual(['alpha', 'beta']);
+
+    for (const e of entries) {
+      expect(e.migration).toBe('0.22.4');
+      // Dotted-filename convention: the skill pointer matches the user-facing
+      // migration doc at skills/migrations/v0.22.4.md, NOT the underscored
+      // TS module path.
+      expect(e.skill).toBe('skills/migrations/v0.22.4.md');
+      expect(e.command).toContain('gbrain frontmatter validate');
+      expect(e.command).toContain('--fix');
+      expect(e.command).toContain(e.source_path);
+    }
+  });
+
+  test('audit phase did NOT mutate any fixture brain page (audit-only contract)', () => {
+    for (const [path, original] of originalContents) {
+      expect(readFileSync(path, 'utf8')).toBe(original);
+      // Nor should there be a .bak — the migration never invokes writeBrainPage.
+      expect(existsSync(path + '.bak')).toBe(false);
+    }
+  });
+
+  test('orchestrator is idempotent — re-running does not duplicate JSONL entries', async () => {
+    await v0_22_4.orchestrator({
+      yes: true,
+      dryRun: false,
+      noAutopilotInstall: true,
+    });
+    const jsonlPath = join(tmpHome, '.gbrain', 'migrations', 'pending-host-work.jsonl');
+    const lines = readFileSync(jsonlPath, 'utf8').split('\n').filter(Boolean);
+    expect(lines.length).toBe(2);
+  });
+});

test/e2e/minions-shell.test.ts

@@ -43,13 +43,27 @@ async function waitTerminal(queue: MinionQueue, id: number, timeoutMs = 15000):
 }
 
 describeE2E('E2E: Minions shell handler', () => {
+  let originalAllowShellJobs: string | undefined;
+
   beforeAll(async () => {
+    // The shell handler refuses to run unless GBRAIN_ALLOW_SHELL_JOBS=1 is
+    // set on the worker process (defense-in-depth: the env var is the
+    // operator-trust gate, separate from the trusted-add allowProtectedSubmit
+    // flag). The PGLite sibling test sets this in its beforeAll for the same
+    // reason; without it shell jobs land in `dead`.
+    originalAllowShellJobs = process.env.GBRAIN_ALLOW_SHELL_JOBS;
+    process.env.GBRAIN_ALLOW_SHELL_JOBS = '1';
     await setupDB();
     await runMigrations(getEngine());
   });
 
   afterAll(async () => {
     await teardownDB();
+    if (originalAllowShellJobs === undefined) {
+      delete process.env.GBRAIN_ALLOW_SHELL_JOBS;
+    } else {
+      process.env.GBRAIN_ALLOW_SHELL_JOBS = originalAllowShellJobs;
+    }
   });
 
   beforeEach(async () => {

test/e2e/search-exclude.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Hard-Exclude E2E
+ *
+ * Verifies the new exclude_slug_prefixes / include_slug_prefixes plumbing.
+ * test/, archive/, attachments/, .raw/ are hard-excluded by default.
+ * include_slug_prefixes opts back in.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
+import type { ChunkInput } from '../../src/core/types.ts';
+
+let engine: PGLiteEngine;
+
+function basisEmbedding(idx: number, dim = 1536): Float32Array {
+  const emb = new Float32Array(dim);
+  emb[idx % dim] = 1.0;
+  return emb;
+}
+
+beforeAll(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({});
+  await engine.initSchema();
+
+  await engine.putPage('test/fixtures/widget', {
+    type: 'note',
+    title: 'Widget test fixture',
+    compiled_truth: 'widget test fixture for the test suite',
+    timeline: '',
+  });
+  await engine.upsertChunks('test/fixtures/widget', [
+    {
+      chunk_index: 0,
+      chunk_text: 'widget test fixture for the test suite',
+      chunk_source: 'compiled_truth',
+      embedding: basisEmbedding(11),
+      token_count: 8,
+    },
+  ] satisfies ChunkInput[]);
+
+  await engine.putPage('archive/old-stuff/widget-2020', {
+    type: 'note',
+    title: 'Widget 2020',
+    compiled_truth: 'widget archived from 2020',
+    timeline: '',
+  });
+  await engine.upsertChunks('archive/old-stuff/widget-2020', [
+    {
+      chunk_index: 0,
+      chunk_text: 'widget archived from 2020 — stale info about widget',
+      chunk_source: 'compiled_truth',
+      embedding: basisEmbedding(12),
+      token_count: 8,
+    },
+  ] satisfies ChunkInput[]);
+
+  await engine.putPage('concepts/widget-pattern', {
+    type: 'concept',
+    title: 'Widget Pattern',
+    compiled_truth: 'the widget pattern is a useful design pattern',
+    timeline: '',
+  });
+  await engine.upsertChunks('concepts/widget-pattern', [
+    {
+      chunk_index: 0,
+      chunk_text: 'the widget pattern is a useful widget design pattern',
+      chunk_source: 'compiled_truth',
+      embedding: basisEmbedding(13),
+      token_count: 9,
+    },
+  ] satisfies ChunkInput[]);
+}, 60_000);
+
+afterAll(async () => {
+  await engine.disconnect();
+});
+
+describe('searchKeyword default hard-excludes', () => {
+  test('test/ pages are hidden by default', async () => {
+    const results = await engine.searchKeyword('widget');
+    const slugs = results.map(r => r.slug);
+    expect(slugs).not.toContain('test/fixtures/widget');
+  });
+
+  test('archive/ pages are hidden by default', async () => {
+    const results = await engine.searchKeyword('widget');
+    const slugs = results.map(r => r.slug);
+    expect(slugs).not.toContain('archive/old-stuff/widget-2020');
+  });
+
+  test('curated content is unaffected', async () => {
+    const results = await engine.searchKeyword('widget');
+    const slugs = results.map(r => r.slug);
+    expect(slugs).toContain('concepts/widget-pattern');
+  });
+});
+
+describe('searchKeyword include_slug_prefixes opt-back-in', () => {
+  test('include_slug_prefixes: ["test/"] surfaces test pages', async () => {
+    const results = await engine.searchKeyword('widget', {
+      include_slug_prefixes: ['test/'],
+    });
+    const slugs = results.map(r => r.slug);
+    expect(slugs).toContain('test/fixtures/widget');
+    // archive/ is still excluded.
+    expect(slugs).not.toContain('archive/old-stuff/widget-2020');
+  });
+
+  test('include_slug_prefixes lets caller opt back into both', async () => {
+    const results = await engine.searchKeyword('widget', {
+      include_slug_prefixes: ['test/', 'archive/'],
+    });
+    const slugs = results.map(r => r.slug);
+    expect(slugs).toContain('test/fixtures/widget');
+    expect(slugs).toContain('archive/old-stuff/widget-2020');
+  });
+});
+
+describe('searchVector hard-excludes', () => {
+  test('test/ pages are excluded by default in vector search', async () => {
+    const results = await engine.searchVector(basisEmbedding(11));
+    // basisEmbedding(11) is the closest direction to test/fixtures/widget,
+    // so without exclude it would be at top. With default exclude, it's gone.
+    const slugs = results.map(r => r.slug);
+    expect(slugs).not.toContain('test/fixtures/widget');
+  });
+
+  test('include_slug_prefixes lets it back in', async () => {
+    const results = await engine.searchVector(basisEmbedding(11), {
+      include_slug_prefixes: ['test/'],
+    });
+    const slugs = results.map(r => r.slug);
+    expect(slugs).toContain('test/fixtures/widget');
+  });
+});
+
+describe('caller-supplied exclude_slug_prefixes (additive)', () => {
+  test('caller can add a custom exclude prefix on top of defaults', async () => {
+    const results = await engine.searchKeyword('widget', {
+      exclude_slug_prefixes: ['concepts/'],
+    });
+    const slugs = results.map(r => r.slug);
+    // concepts/ now also excluded; with all three categories filtered, no
+    // hits remain.
+    expect(slugs).not.toContain('concepts/widget-pattern');
+    expect(slugs).not.toContain('test/fixtures/widget');
+    expect(slugs).not.toContain('archive/old-stuff/widget-2020');
+  });
+});

test/e2e/search-swamp.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Search Swamp Resistance E2E
+ *
+ * Reproduces the v3-plan repro case: a curated article (originals/) competes
+ * with two chat-log pages (wintermute/chat/) on similar ts_rank. With v0.21+
+ * source-aware ranking, the article must rank #0.
+ *
+ * Mirrors the structure of search-quality.test.ts. Uses PGLite in-memory.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
+import type { ChunkInput } from '../../src/core/types.ts';
+
+let engine: PGLiteEngine;
+
+function basisEmbedding(idx: number, dim = 1536): Float32Array {
+  const emb = new Float32Array(dim);
+  emb[idx % dim] = 1.0;
+  return emb;
+}
+
+beforeAll(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({});
+  await engine.initSchema();
+
+  // Curated article — short, dense, opinionated. The page that should win.
+  await engine.putPage('originals/talks/article-outline-fat-code', {
+    type: 'writing',
+    title: 'Fat Code Thin Harness — Part 3',
+    compiled_truth:
+      'Fat code thin harness is the architectural pattern where business logic ' +
+      'lives in fat skill files and the runtime stays thin. Part 3 covers the ' +
+      'production case studies.',
+    timeline: '2026-04-10: Drafted Part 3 outline.',
+  });
+  await engine.upsertChunks('originals/talks/article-outline-fat-code', [
+    {
+      chunk_index: 0,
+      chunk_text:
+        'Fat code thin harness — the pattern where business logic lives in fat skill files. Part 3.',
+      chunk_source: 'compiled_truth',
+      embedding: basisEmbedding(7),
+      token_count: 20,
+    },
+  ] satisfies ChunkInput[]);
+
+  // Chat swamp #1 — long page, mentions the phrase repeatedly.
+  await engine.putPage('wintermute/chat/2026-04-15', {
+    type: 'note',
+    title: '2026-04-15 chat',
+    compiled_truth: '',
+    timeline:
+      'fat code thin harness fat code thin harness — discussed at length. ' +
+      'fat code thin harness came up again. ' +
+      'The fat code thin harness pattern is something we keep returning to. ' +
+      'fat code thin harness fat code thin harness fat code thin harness.',
+  });
+  await engine.upsertChunks('wintermute/chat/2026-04-15', [
+    {
+      chunk_index: 0,
+      chunk_text:
+        'fat code thin harness fat code thin harness discussed at length, ' +
+        'the fat code thin harness pattern keeps coming back, ' +
+        'fat code thin harness fat code thin harness fat code thin harness.',
+      chunk_source: 'timeline',
+      embedding: basisEmbedding(8),
+      token_count: 30,
+    },
+  ] satisfies ChunkInput[]);
+
+  // Chat swamp #2 — same shape.
+  await engine.putPage('wintermute/chat/2026-04-16', {
+    type: 'note',
+    title: '2026-04-16 chat',
+    compiled_truth: '',
+    timeline:
+      'fat code thin harness once more. fat code thin harness fat code thin harness. ' +
+      'still talking about fat code thin harness. fat code thin harness.',
+  });
+  await engine.upsertChunks('wintermute/chat/2026-04-16', [
+    {
+      chunk_index: 0,
+      chunk_text:
+        'fat code thin harness once more, fat code thin harness fat code thin harness, ' +
+        'still talking about fat code thin harness fat code thin harness.',
+      chunk_source: 'timeline',
+      embedding: basisEmbedding(9),
+      token_count: 25,
+    },
+  ] satisfies ChunkInput[]);
+}, 60_000);
+
+afterAll(async () => {
+  await engine.disconnect();
+});
+
+describe('searchKeyword swamp resistance', () => {
+  test('curated originals/ page outranks chat swamp on multi-word query', async () => {
+    const results = await engine.searchKeyword('fat code thin harness');
+    expect(results.length).toBeGreaterThan(0);
+    const top = results[0];
+    expect(top.slug).toBe('originals/talks/article-outline-fat-code');
+  });
+
+  test('detail=high (temporal bypass) lets chat swamp re-surface', async () => {
+    // With source-boost disabled, raw ts_rank wins → chat pages, which have
+    // many more keyword hits, are allowed back to the top. This guards the
+    // temporal-query workflow ("what did we discuss about X").
+    const results = await engine.searchKeyword('fat code thin harness', { detail: 'high' });
+    expect(results.length).toBeGreaterThan(0);
+    // Top result should be a chat page (more keyword density per chunk).
+    const topSlugs = results.slice(0, 2).map(r => r.slug);
+    const anyChat = topSlugs.some(s => s.startsWith('wintermute/chat/'));
+    expect(anyChat).toBe(true);
+  });
+});
+
+describe('searchVector swamp resistance', () => {
+  test('curated originals/ page outranks chat swamp when boost is meaningful', async () => {
+    // Query vector is close to all three pages (mixed direction). Without
+    // source-boost the chat pages would tie or win on raw cosine; with
+    // source-boost the originals/ page dominates.
+    const queryVec = new Float32Array(1536);
+    queryVec[7] = 0.6; // article direction
+    queryVec[8] = 0.55; // chat-1 direction (slightly higher, simulating swamp)
+    queryVec[9] = 0.55; // chat-2 direction
+    // Normalize so cosine math is well-formed.
+    const norm = Math.sqrt(0.6 * 0.6 + 0.55 * 0.55 + 0.55 * 0.55);
+    for (let i = 0; i < queryVec.length; i++) queryVec[i] = queryVec[i] / norm;
+
+    const results = await engine.searchVector(queryVec);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].slug).toBe('originals/talks/article-outline-fat-code');
+  });
+
+  test('two-stage CTE returns p.source_id (regression for v0.18 multi-source)', async () => {
+    const queryVec = basisEmbedding(7);
+    const results = await engine.searchVector(queryVec);
+    expect(results.length).toBeGreaterThan(0);
+    // source_id is added by v0.18 multi-source brains; carrying it through
+    // the inner→outer CTE is one of the v3 plan's pass-4 findings.
+    for (const r of results) {
+      expect(r.source_id).toBeDefined();
+    }
+  });
+});

test/e2e/worker-abort-recovery.test.ts

@@ -0,0 +1,178 @@
+/**
+ * test/e2e/worker-abort-recovery.test.ts — E2E smoke test for worker
+ * recovery after handler timeout.
+ *
+ * Exercises the full path: submit job → handler runs → timeout fires →
+ * abort propagates → worker recovers → claims next job.
+ *
+ * This is the end-to-end regression test for the 2026-04-24 incident
+ * where a stuck autopilot-cycle handler wedged the worker with 98 jobs
+ * waiting and 0 active.
+ *
+ * Uses PGLite (in-memory), no external services needed.
+ */
+
+import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
+import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
+import { MinionQueue } from '../../src/core/minions/queue.ts';
+import { MinionWorker } from '../../src/core/minions/worker.ts';
+
+let engine: PGLiteEngine;
+let queue: MinionQueue;
+
+beforeAll(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({ database_url: '' });
+  await engine.initSchema();
+  queue = new MinionQueue(engine);
+});
+
+afterAll(async () => {
+  await engine.disconnect();
+});
+
+beforeEach(async () => {
+  await engine.executeRaw('DELETE FROM minion_jobs');
+});
+
+describe('E2E: worker abort recovery (2026-04-24 regression)', () => {
+  test('worker recovers from timed-out handler and processes next job', async () => {
+    // Step 1: Submit a slow job with a short timeout
+    const slowJob = await queue.add('slow-handler', { type: 'slow' }, {
+      timeout_ms: 200,
+      max_attempts: 1,
+    });
+
+    // Step 2: Submit a fast job that should run AFTER the slow one times out
+    const fastJob = await queue.add('fast-handler', { type: 'fast' }, {
+      max_attempts: 1,
+    });
+
+    let slowHandlerAborted = false;
+    let fastHandlerExecuted = false;
+
+    const worker = new MinionWorker(engine, {
+      pollInterval: 50,
+      concurrency: 1, // Single slot — forces sequential execution
+    });
+
+    // Slow handler: respects AbortSignal (the fix path)
+    worker.register('slow-handler', async (ctx) => {
+      // Simulate expensive work (like extract scanning 54K pages)
+      while (!ctx.signal.aborted) {
+        await new Promise(r => setTimeout(r, 20));
+      }
+      slowHandlerAborted = true;
+      throw ctx.signal.reason || new Error('aborted');
+    });
+
+    // Fast handler: just completes
+    worker.register('fast-handler', async () => {
+      fastHandlerExecuted = true;
+      return { done: true };
+    });
+
+    // Step 3: Start worker
+    const workerPromise = worker.start();
+
+    // Step 4: Wait for slow job timeout (200ms) + handler abort + fast job execution
+    await new Promise(r => setTimeout(r, 1000));
+
+    // Step 5: Stop worker
+    worker.stop();
+    await workerPromise;
+
+    // Step 6: Verify
+    expect(slowHandlerAborted).toBe(true);
+    expect(fastHandlerExecuted).toBe(true);
+
+    const slowResult = await queue.getJob(slowJob.id);
+    expect(slowResult!.status).toBe('dead');
+
+    const fastResult = await queue.getJob(fastJob.id);
+    expect(fastResult!.status).toBe('completed');
+    expect(fastResult!.result).toEqual({ done: true });
+  });
+
+  test('concurrency=2 worker still processes jobs while one slot is timing out', async () => {
+    const slowJob = await queue.add('slow-c2', {}, {
+      timeout_ms: 200,
+      max_attempts: 1,
+    });
+    const fastJob = await queue.add('fast-c2', {}, { max_attempts: 1 });
+
+    let slowAborted = false;
+    let fastDone = false;
+
+    const worker = new MinionWorker(engine, {
+      pollInterval: 50,
+      concurrency: 2, // Two slots — fast job can run in parallel
+    });
+
+    worker.register('slow-c2', async (ctx) => {
+      while (!ctx.signal.aborted) {
+        await new Promise(r => setTimeout(r, 10));
+      }
+      slowAborted = true;
+      throw new Error('aborted');
+    });
+
+    worker.register('fast-c2', async () => {
+      fastDone = true;
+      return { fast: true };
+    });
+
+    const workerPromise = worker.start();
+    await new Promise(r => setTimeout(r, 600));
+    worker.stop();
+    await workerPromise;
+
+    expect(slowAborted).toBe(true);
+    expect(fastDone).toBe(true);
+
+    const slowResult = await queue.getJob(slowJob.id);
+    expect(slowResult!.status).toBe('dead');
+
+    const fastResult = await queue.getJob(fastJob.id);
+    expect(fastResult!.status).toBe('completed');
+  });
+
+  test('multiple timeouts in sequence dont permanently wedge worker', async () => {
+    // Submit 3 slow jobs that all timeout + 1 fast job
+    // The fast job MUST execute
+    const slow1 = await queue.add('multi-slow', {}, { timeout_ms: 100, max_attempts: 1 });
+    const slow2 = await queue.add('multi-slow', {}, { timeout_ms: 100, max_attempts: 1 });
+    const slow3 = await queue.add('multi-slow', {}, { timeout_ms: 100, max_attempts: 1 });
+    const fast = await queue.add('multi-fast', {}, { max_attempts: 1 });
+
+    let timeoutsHit = 0;
+    let fastDone = false;
+
+    const worker = new MinionWorker(engine, { pollInterval: 50, concurrency: 1 });
+
+    worker.register('multi-slow', async (ctx) => {
+      while (!ctx.signal.aborted) {
+        await new Promise(r => setTimeout(r, 10));
+      }
+      timeoutsHit++;
+      throw new Error('aborted');
+    });
+
+    worker.register('multi-fast', async () => {
+      fastDone = true;
+      return { ok: true };
+    });
+
+    const workerPromise = worker.start();
+    // 3 slow jobs × (100ms timeout + overhead) + fast job + margin
+    await new Promise(r => setTimeout(r, 2000));
+    worker.stop();
+    await workerPromise;
+
+    expect(timeoutsHit).toBe(3);
+    expect(fastDone).toBe(true);
+
+    const fastResult = await queue.getJob(fast.id);
+    expect(fastResult!.status).toBe('completed');
+  });
+});

test/embed.test.ts

@@ -106,14 +106,18 @@ describe('runEmbed --all (parallel)', () => {
   });
 
   test('skips pages whose chunks are all already embedded when --stale', async () => {
-    const pages = [{ slug: 'fresh' }, { slug: 'stale' }];
     const chunksBySlug = new Map<string, any[]>([
       ['fresh', [{ chunk_index: 0, chunk_text: 'hi', chunk_source: 'compiled_truth', embedded_at: '2026-01-01', token_count: 1 }]],
       ['stale', [{ chunk_index: 0, chunk_text: 'hi', chunk_source: 'compiled_truth', embedded_at: null, token_count: 1 }]],
     ]);
+    // Stale path uses countStaleChunks + listStaleChunks (SQL-side filter), not listPages.
+    const stale = [
+      { slug: 'stale', chunk_index: 0, chunk_text: 'hi', chunk_source: 'compiled_truth', model: null, token_count: 1 },
+    ];
 
     const engine = mockEngine({
-      listPages: async () => pages,
+      countStaleChunks: async () => 1,
+      listStaleChunks: async () => stale,
       getChunks: async (slug: string) => chunksBySlug.get(slug) || [],
       upsertChunks: async () => {},
     });
@@ -145,9 +149,16 @@ describe('runEmbedCore --dry-run never calls the embedding model', () => {
         ],
       ]),
     );
+    // SQL-side stale path: 6 stale rows across 3 pages.
+    const stale = pages.flatMap(p => [
+      { slug: p.slug, chunk_index: 0, chunk_text: 'a', chunk_source: 'compiled_truth', model: null, token_count: 1 },
+      { slug: p.slug, chunk_index: 1, chunk_text: 'b', chunk_source: 'compiled_truth', model: null, token_count: 1 },
+    ]);
 
     const upserts: string[] = [];
     const engine = mockEngine({
+      countStaleChunks: async () => 6,
+      listStaleChunks: async () => stale,
       listPages: async () => pages,
       getChunks: async (slug: string) => chunksBySlug.get(slug) || [],
       upsertChunks: async (slug: string) => { upserts.push(slug); },
@@ -163,32 +174,25 @@ describe('runEmbedCore --dry-run never calls the embedding model', () => {
     expect(result.dryRun).toBe(true);
     expect(result.embedded).toBe(0);
     expect(result.would_embed).toBe(6); // 3 pages * 2 chunks each
+    // skipped is 0 in the new SQL-side path: we never considered non-stale chunks.
     expect(result.skipped).toBe(0);
-    expect(result.total_chunks).toBe(6);
+    expect(result.total_chunks).toBe(6); // only stale chunks counted in SQL-side path
     expect(result.pages_processed).toBe(3);
   });
 
-  test('dry-run --stale correctly separates stale from already-embedded', async () => {
+  test('dry-run --stale correctly identifies stale chunks (SQL-side path)', async () => {
     const { runEmbedCore } = await import('../src/commands/embed.ts');
-    const pages = [{ slug: 'fresh' }, { slug: 'partial' }, { slug: 'all-stale' }];
-    const chunksBySlug = new Map<string, any[]>([
-      ['fresh', [
-        { chunk_index: 0, chunk_text: 'a', chunk_source: 'compiled_truth', embedded_at: '2026-01-01', token_count: 1 },
-        { chunk_index: 1, chunk_text: 'b', chunk_source: 'compiled_truth', embedded_at: '2026-01-01', token_count: 1 },
-      ]],
-      ['partial', [
-        { chunk_index: 0, chunk_text: 'a', chunk_source: 'compiled_truth', embedded_at: '2026-01-01', token_count: 1 },
-        { chunk_index: 1, chunk_text: 'b', chunk_source: 'compiled_truth', embedded_at: null, token_count: 1 },
-      ]],
-      ['all-stale', [
-        { chunk_index: 0, chunk_text: 'a', chunk_source: 'compiled_truth', embedded_at: null, token_count: 1 },
-        { chunk_index: 1, chunk_text: 'b', chunk_source: 'compiled_truth', embedded_at: null, token_count: 1 },
-      ]],
-    ]);
+    // SQL-side stale: only the 3 chunks where embedding IS NULL come back,
+    // grouped by slug. 'fresh' page has no stale rows so it's not in the result.
+    const stale = [
+      { slug: 'partial', chunk_index: 1, chunk_text: 'b', chunk_source: 'compiled_truth', model: null, token_count: 1 },
+      { slug: 'all-stale', chunk_index: 0, chunk_text: 'a', chunk_source: 'compiled_truth', model: null, token_count: 1 },
+      { slug: 'all-stale', chunk_index: 1, chunk_text: 'b', chunk_source: 'compiled_truth', model: null, token_count: 1 },
+    ];
 
     const engine = mockEngine({
-      listPages: async () => pages,
-      getChunks: async (slug: string) => chunksBySlug.get(slug) || [],
+      countStaleChunks: async () => 3,
+      listStaleChunks: async () => stale,
       upsertChunks: async () => {},
     });
 
@@ -197,9 +201,11 @@ describe('runEmbedCore --dry-run never calls the embedding model', () => {
     expect(totalEmbedCalls).toBe(0);
     expect(result.dryRun).toBe(true);
     expect(result.would_embed).toBe(3); // 1 from 'partial' + 2 from 'all-stale'
-    expect(result.skipped).toBe(3); // 2 from 'fresh' + 1 from 'partial'
-    expect(result.total_chunks).toBe(6);
-    expect(result.pages_processed).toBe(3);
+    // SQL-side path does not see non-stale chunks, so skipped=0 and total_chunks=stale-count.
+    // Callers wanting full coverage should call engine.getStats()/getHealth() afterward.
+    expect(result.skipped).toBe(0);
+    expect(result.total_chunks).toBe(3);
+    expect(result.pages_processed).toBe(2); // 'partial' + 'all-stale'
   });
 
   test('dry-run --slugs on a single page counts stale chunks, no API calls', async () => {
@@ -228,7 +234,6 @@ describe('runEmbedCore --dry-run never calls the embedding model', () => {
 
   test('non-dry-run path reports accurate embedded count (regression guard)', async () => {
     const { runEmbedCore } = await import('../src/commands/embed.ts');
-    const pages = [{ slug: 'a' }, { slug: 'b' }];
     const chunksBySlug = new Map<string, any[]>([
       ['a', [{ chunk_index: 0, chunk_text: 'a', chunk_source: 'compiled_truth', embedded_at: null, token_count: 1 }]],
       ['b', [
@@ -236,9 +241,15 @@ describe('runEmbedCore --dry-run never calls the embedding model', () => {
         { chunk_index: 1, chunk_text: 'y', chunk_source: 'compiled_truth', embedded_at: null, token_count: 1 },
       ]],
     ]);
+    const stale = [
+      { slug: 'a', chunk_index: 0, chunk_text: 'a', chunk_source: 'compiled_truth', model: null, token_count: 1 },
+      { slug: 'b', chunk_index: 0, chunk_text: 'x', chunk_source: 'compiled_truth', model: null, token_count: 1 },
+      { slug: 'b', chunk_index: 1, chunk_text: 'y', chunk_source: 'compiled_truth', model: null, token_count: 1 },
+    ];
 
     const engine = mockEngine({
-      listPages: async () => pages,
+      countStaleChunks: async () => 3,
+      listStaleChunks: async () => stale,
       getChunks: async (slug: string) => chunksBySlug.get(slug) || [],
       upsertChunks: async () => {},
     });
@@ -253,3 +264,139 @@ describe('runEmbedCore --dry-run never calls the embedding model', () => {
     expect(result.pages_processed).toBe(2);
   });
 });
+
+// ────────────────────────────────────────────────────────────────
+// runEmbedCore --stale egress fix: SQL-side staleness filter
+// Replaces the listPages + per-page getChunks bomb with a count +
+// slug-grouped SELECT. On a 100%-embedded brain, 0 listPages calls.
+// ────────────────────────────────────────────────────────────────
+
+describe('runEmbedCore --stale egress fix (SQL-side filter)', () => {
+  test('zero stale chunks: countStaleChunks short-circuits, listPages never called', async () => {
+    const { runEmbedCore } = await import('../src/commands/embed.ts');
+    let listPagesCalled = false;
+    let getChunksCalled = false;
+    let listStaleCalled = false;
+    const engine = mockEngine({
+      countStaleChunks: async () => 0,
+      listPages: async () => { listPagesCalled = true; return []; },
+      getChunks: async () => { getChunksCalled = true; return []; },
+      listStaleChunks: async () => { listStaleCalled = true; return []; },
+      upsertChunks: async () => {},
+    });
+
+    const result = await runEmbedCore(engine, { stale: true });
+
+    expect(result.embedded).toBe(0);
+    expect(result.pages_processed).toBe(0);
+    // The egress fix: NONE of these should have been called when count=0.
+    expect(listPagesCalled).toBe(false);
+    expect(getChunksCalled).toBe(false);
+    expect(listStaleCalled).toBe(false);
+    expect(totalEmbedCalls).toBe(0);
+  });
+
+  test('N stale chunks across M pages: only stale slugs re-fetched, exact stale set embedded, non-stale chunks preserved', async () => {
+    const { runEmbedCore } = await import('../src/commands/embed.ts');
+    let listPagesCalled = false;
+
+    const stale = [
+      { slug: 'page-a', chunk_index: 0, chunk_text: 'x', chunk_source: 'compiled_truth' as const, model: null, token_count: null },
+      { slug: 'page-b', chunk_index: 1, chunk_text: 'y', chunk_source: 'compiled_truth' as const, model: null, token_count: null },
+      { slug: 'page-b', chunk_index: 2, chunk_text: 'z', chunk_source: 'compiled_truth' as const, model: null, token_count: null },
+    ];
+    // page-b has a FRESH chunk at index 0 that must be preserved through the upsert.
+    const fullChunks: Record<string, any[]> = {
+      'page-a': [
+        { chunk_index: 0, chunk_text: 'x', chunk_source: 'compiled_truth', embedded_at: null, token_count: 1 },
+      ],
+      'page-b': [
+        { chunk_index: 0, chunk_text: 'fresh', chunk_source: 'compiled_truth', embedded_at: '2026-01-01', token_count: 5 },
+        { chunk_index: 1, chunk_text: 'y', chunk_source: 'compiled_truth', embedded_at: null, token_count: 1 },
+        { chunk_index: 2, chunk_text: 'z', chunk_source: 'compiled_truth', embedded_at: null, token_count: 1 },
+      ],
+    };
+    const upsertCalls: Array<{ slug: string; chunks: any[] }> = [];
+    const engine = mockEngine({
+      countStaleChunks: async () => 3,
+      listStaleChunks: async () => stale,
+      listPages: async () => { listPagesCalled = true; return []; },
+      getChunks: async (slug: string) => fullChunks[slug] || [],
+      upsertChunks: async (slug: string, chunks: any[]) => { upsertCalls.push({ slug, chunks }); },
+    });
+
+    const result = await runEmbedCore(engine, { stale: true });
+
+    // listPages must NOT be called in the SQL-side path.
+    expect(listPagesCalled).toBe(false);
+    // One embedBatch call per stale slug (a, b).
+    expect(totalEmbedCalls).toBe(2);
+    expect(result.embedded).toBe(3);
+    expect(result.pages_processed).toBe(2);
+
+    // page-b's upsert MUST include the fresh chunk (chunk_index=0) — otherwise
+    // it would be deleted by the upsertChunks != ALL filter. Critical regression check.
+    const pageBUpsert = upsertCalls.find(u => u.slug === 'page-b');
+    expect(pageBUpsert).toBeDefined();
+    const freshChunkInUpsert = pageBUpsert!.chunks.find((c: any) => c.chunk_index === 0);
+    expect(freshChunkInUpsert).toBeDefined();
+    // Fresh chunk has no `embedding` field (preserved via COALESCE in upsertChunks SQL).
+    expect(freshChunkInUpsert.embedding).toBeUndefined();
+    // Previously-stale chunks come through WITH a new embedding.
+    const staleChunkInUpsert = pageBUpsert!.chunks.find((c: any) => c.chunk_index === 1);
+    expect(staleChunkInUpsert.embedding).toBeDefined();
+    expect(staleChunkInUpsert.embedding).toBeInstanceOf(Float32Array);
+  });
+
+  test('--stale dry-run: counts stale via countStaleChunks, reports via listStaleChunks, no embedBatch or upsertChunks', async () => {
+    const { runEmbedCore } = await import('../src/commands/embed.ts');
+    const stale = [
+      { slug: 'page-a', chunk_index: 0, chunk_text: 'x', chunk_source: 'compiled_truth' as const, model: null, token_count: null },
+      { slug: 'page-b', chunk_index: 0, chunk_text: 'y', chunk_source: 'compiled_truth' as const, model: null, token_count: null },
+    ];
+    const upserts: string[] = [];
+    const engine = mockEngine({
+      countStaleChunks: async () => 2,
+      listStaleChunks: async () => stale,
+      upsertChunks: async (slug: string) => { upserts.push(slug); },
+    });
+
+    const result = await runEmbedCore(engine, { stale: true, dryRun: true });
+
+    expect(totalEmbedCalls).toBe(0);
+    expect(upserts).toEqual([]);
+    expect(result.would_embed).toBe(2);
+    expect(result.pages_processed).toBe(2);
+    expect(result.dryRun).toBe(true);
+  });
+
+  test('--all (non-stale) path is byte-identical: walks listPages and embeds every chunk', async () => {
+    // Regression guard for the legacy --all path. Behavior must be byte-identical
+    // to pre-fix: listPages + per-page getChunks + embed every chunk.
+    const { runEmbedCore } = await import('../src/commands/embed.ts');
+    let countStaleCalled = false;
+    let listStaleCalled = false;
+    const pages = [{ slug: 'a' }, { slug: 'b' }];
+    const chunksBySlug = new Map<string, any[]>([
+      ['a', [{ chunk_index: 0, chunk_text: 'a', chunk_source: 'compiled_truth', embedded_at: '2026-01-01', token_count: 1 }]],
+      ['b', [{ chunk_index: 0, chunk_text: 'b', chunk_source: 'compiled_truth', embedded_at: null, token_count: 1 }]],
+    ]);
+
+    const engine = mockEngine({
+      countStaleChunks: async () => { countStaleCalled = true; return 1; },
+      listStaleChunks: async () => { listStaleCalled = true; return []; },
+      listPages: async () => pages,
+      getChunks: async (slug: string) => chunksBySlug.get(slug) || [],
+      upsertChunks: async () => {},
+    });
+
+    const result = await runEmbedCore(engine, { all: true });
+
+    // --all path must NOT take the new short-circuit.
+    expect(countStaleCalled).toBe(false);
+    expect(listStaleCalled).toBe(false);
+    // Both pages get embedded, regardless of embedded_at — that's the --all contract.
+    expect(totalEmbedCalls).toBe(2);
+    expect(result.embedded).toBe(2);
+  });
+});

test/extract-incremental.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Regression guards for the incremental extract path (PR #417).
+ *
+ * Eng-review Step 5: 8 unit cases asserting `runExtractCore({ slugs })`
+ * processes only the requested slugs in the cycle path while
+ * `slugs: undefined` falls through to the existing full-walk behavior.
+ *
+ * All tests use PGLite/in-memory — no DB connection required.
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { runExtractCore } from '../src/commands/extract.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import type { BrainEngine } from '../src/core/engine.ts';
+
+let engine: PGLiteEngine;
+let tempDir: string;
+
+beforeEach(async () => {
+  engine = new PGLiteEngine();
+  await engine.connect({ engine: 'pglite' });
+  await engine.initSchema();
+  tempDir = mkdtempSync(join(tmpdir(), 'gbrain-extract-test-'));
+  mkdirSync(join(tempDir, 'people'), { recursive: true });
+  mkdirSync(join(tempDir, 'companies'), { recursive: true });
+});
+
+afterEach(async () => {
+  await engine.disconnect();
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+async function seedPage(slug: string, body: string): Promise<void> {
+  const [type, name] = slug.split('/');
+  await engine.putPage(slug, {
+    type: type as 'person' | 'company',
+    title: name,
+    compiled_truth: body,
+    timeline: '',
+    frontmatter: {},
+    content_hash: 'h',
+  });
+  // Also write to disk so walkMarkdownFiles can find it
+  const filePath = join(tempDir, slug + '.md');
+  mkdirSync(join(tempDir, type), { recursive: true });
+  writeFileSync(filePath, body);
+}
+
+describe('runExtractCore — incremental cycle path (#417)', () => {
+  test('1. slugs: [] returns immediately with zero counts (early-return path)', async () => {
+    await seedPage('people/alice-example', '# alice');
+    const result = await runExtractCore(engine as unknown as BrainEngine, {
+      mode: 'all',
+      dir: tempDir,
+      slugs: [],
+    });
+    expect(result.links_created).toBe(0);
+    expect(result.timeline_entries_created).toBe(0);
+    expect(result.pages_processed).toBe(0);
+  });
+
+  test('2. slugs: undefined falls through to full-walk path', async () => {
+    await seedPage('people/alice-example', '# alice\n\n[bob](people/bob-example)');
+    await seedPage('people/bob-example', '# bob');
+    const result = await runExtractCore(engine as unknown as BrainEngine, {
+      mode: 'all',
+      dir: tempDir,
+    });
+    // Full walk processes everything found on disk
+    expect(result.pages_processed).toBeGreaterThan(0);
+  });
+
+  test('3. slugs: [a, b] reads only those two files (incremental processing)', async () => {
+    await seedPage('people/alice-example', '# alice');
+    await seedPage('people/bob-example', '# bob');
+    await seedPage('people/charlie-example', '# charlie');
+    const result = await runExtractCore(engine as unknown as BrainEngine, {
+      mode: 'all',
+      dir: tempDir,
+      slugs: ['people/alice-example', 'people/bob-example'],
+    });
+    // Only 2 files processed even though 3 exist on disk
+    expect(result.pages_processed).toBe(2);
+  });
+
+  test('4. Slug whose file no longer exists is silently skipped', async () => {
+    await seedPage('people/alice-example', '# alice');
+    // people/ghost has no file on disk but is in the slugs list
+    const result = await runExtractCore(engine as unknown as BrainEngine, {
+      mode: 'all',
+      dir: tempDir,
+      slugs: ['people/alice-example', 'people/ghost'],
+    });
+    // alice processed; ghost skipped (no file)
+    expect(result.pages_processed).toBe(1);
+  });
+
+  test('5. mode: links skips timeline extraction in incremental', async () => {
+    const body = '# alice\n\n## Timeline\n- 2026-01-01: started';
+    await seedPage('people/alice-example', body);
+    const result = await runExtractCore(engine as unknown as BrainEngine, {
+      mode: 'links',
+      dir: tempDir,
+      slugs: ['people/alice-example'],
+    });
+    // Timeline extraction skipped even though body contains a timeline
+    expect(result.timeline_entries_created).toBe(0);
+  });
+
+  test('6. dryRun: true does not invoke addLinksBatch / addTimelineEntriesBatch', async () => {
+    await seedPage('people/alice-example', '# alice\n\n[bob](people/bob-example)');
+    await seedPage('people/bob-example', '# bob');
+
+    let linksBatchCalled = false;
+    let timelineBatchCalled = false;
+    const originalAddLinks = engine.addLinksBatch.bind(engine);
+    const originalAddTimeline = engine.addTimelineEntriesBatch.bind(engine);
+    (engine as unknown as { addLinksBatch: typeof originalAddLinks }).addLinksBatch = async (...args) => {
+      linksBatchCalled = true;
+      return originalAddLinks(...args);
+    };
+    (engine as unknown as { addTimelineEntriesBatch: typeof originalAddTimeline }).addTimelineEntriesBatch = async (...args) => {
+      timelineBatchCalled = true;
+      return originalAddTimeline(...args);
+    };
+
+    await runExtractCore(engine as unknown as BrainEngine, {
+      mode: 'all',
+      dir: tempDir,
+      slugs: ['people/alice-example'],
+      dryRun: true,
+    });
+
+    expect(linksBatchCalled).toBe(false);
+    expect(timelineBatchCalled).toBe(false);
+  });
+
+  test('7. BATCH_SIZE flush — slugs producing >100 candidate links exercise the mid-iteration flush', async () => {
+    // BATCH_SIZE in extract.ts is 100. Create one slug with 150 outbound links.
+    const targets: string[] = [];
+    for (let i = 0; i < 150; i++) {
+      const target = `companies/co-${i}`;
+      targets.push(target);
+      await seedPage(target, `# co-${i}`);
+    }
+    const linkBlock = targets.map(t => `- [${t}](${t})`).join('\n');
+    await seedPage('people/alice-example', `# alice\n\n${linkBlock}`);
+
+    const result = await runExtractCore(engine as unknown as BrainEngine, {
+      mode: 'links',
+      dir: tempDir,
+      slugs: ['people/alice-example'],
+    });
+    // The flush happens mid-iteration when batch hits 100; the remaining 50 flush at end.
+    // No exception means the flush path executed cleanly.
+    expect(result.pages_processed).toBe(1);
+    expect(result.links_created).toBeGreaterThanOrEqual(0); // Just confirms the flush path didn't blow up
+  });
+
+  test('8. Full-slug-set resolution — slug references file outside changed set', async () => {
+    // alice references bob, but only alice is in the incremental slugs list.
+    // The allSlugs set must still include bob (from walkMarkdownFiles) so
+    // resolveSlug succeeds; otherwise the link would silently drop.
+    // Markdown link pattern requires .md target.
+    await seedPage('people/alice-example', '# alice\n\n[bob](bob-example.md)');
+    await seedPage('people/bob-example', '# bob');
+
+    const result = await runExtractCore(engine as unknown as BrainEngine, {
+      mode: 'links',
+      dir: tempDir,
+      slugs: ['people/alice-example'],
+    });
+
+    // Only alice's file was read, but the resulting link must reference bob
+    // (resolved via the full allSlugs set built from walkMarkdownFiles).
+    expect(result.pages_processed).toBe(1);
+    // Link from alice to bob was extracted successfully via the full allSlugs set
+    expect(result.links_created).toBeGreaterThan(0);
+  });
+});

test/frontmatter-cli.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { spawnSync } from 'child_process';
+
+const fence = '---';
+const CLI = ['run', 'src/cli.ts', 'frontmatter'];
+
+function runCli(args: string[]): { stdout: string; stderr: string; code: number } {
+  const result = spawnSync('bun', [...CLI, ...args], {
+    encoding: 'utf8',
+    cwd: process.cwd(),
+  });
+  return {
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    code: result.status ?? -1,
+  };
+}
+
+describe('gbrain frontmatter CLI (B4)', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'fm-cli-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test('--help works without a DB', () => {
+    const { stdout, code } = runCli(['--help']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('frontmatter validation');
+  });
+
+  test('validate clean file: exit 0, OK message', () => {
+    const f = join(tmp, 'clean.md');
+    writeFileSync(f, `${fence}\ntype: concept\ntitle: ok\n${fence}\n\nbody`);
+    const { stdout, code } = runCli(['validate', f]);
+    expect(code).toBe(0);
+    expect(stdout).toContain('OK');
+  });
+
+  test('validate broken file: exit 1, codes listed', () => {
+    const f = join(tmp, 'broken.md');
+    writeFileSync(f, `${fence}\ntype: concept\ntitle: "P "I" L"\n${fence}\n\nbody`);
+    const { stdout, code } = runCli(['validate', f]);
+    expect(code).toBe(1);
+    expect(stdout).toContain('NESTED_QUOTES');
+  });
+
+  test('validate --json envelope shape', () => {
+    const f = join(tmp, 'broken.md');
+    writeFileSync(f, `${fence}\ntype: concept\ntitle: "P "I" L"\n${fence}\n\nbody`);
+    const { stdout } = runCli(['validate', f, '--json']);
+    const env = JSON.parse(stdout);
+    expect(env.ok).toBe(false);
+    expect(env.total_files).toBe(1);
+    expect(env.results[0].errors.length).toBeGreaterThan(0);
+    expect(env.results[0].errors[0]).toHaveProperty('code');
+  });
+
+  test('validate --fix --dry-run does not write', () => {
+    const f = join(tmp, 'broken.md');
+    const original = `${fence}\ntype: concept\ntitle: "P "I" L"\n${fence}\n\nbody`;
+    writeFileSync(f, original);
+    const { stdout, code } = runCli(['validate', f, '--fix', '--dry-run']);
+    expect(stdout).toContain('would fix');
+    expect(readFileSync(f, 'utf8')).toBe(original);
+    expect(existsSync(f + '.bak')).toBe(false);
+    // exit 0 with --fix even when issues remain (the fix path is the success path)
+    expect(code).toBe(0);
+  });
+
+  test('validate --fix writes .bak and rewrites in place', () => {
+    const f = join(tmp, 'broken.md');
+    const original = `${fence}\ntype: concept\ntitle: "P "I" L"\n${fence}\n\nbody`;
+    writeFileSync(f, original);
+    const { code } = runCli(['validate', f, '--fix']);
+    expect(code).toBe(0);
+    expect(existsSync(f + '.bak')).toBe(true);
+    expect(readFileSync(f + '.bak', 'utf8')).toBe(original);
+    expect(readFileSync(f, 'utf8')).toMatch(/^title: '.*'\s*$/m);
+  });
+
+  test('validate --fix succeeds on a non-git path (no dirty-tree guard)', () => {
+    // tmp is not a git repo; --fix must still work.
+    const f = join(tmp, 'broken.md');
+    writeFileSync(f, `${fence}\ntype: concept\ntitle: "A "B" C"\n${fence}\n\nbody`);
+    const { code } = runCli(['validate', f, '--fix']);
+    expect(code).toBe(0);
+    expect(existsSync(f + '.bak')).toBe(true);
+  });
+
+  test('validate scans a directory recursively, skips non-.md files', () => {
+    mkdirSync(join(tmp, 'subdir'), { recursive: true });
+    writeFileSync(join(tmp, 'a.md'), `${fence}\ntype: concept\ntitle: A\n${fence}\n\nbody`);
+    writeFileSync(join(tmp, 'subdir', 'b.md'), `${fence}\ntype: concept\ntitle: B\n${fence}\n\nbody`);
+    writeFileSync(join(tmp, 'README.md'), 'meta');  // skipped by isSyncable
+    writeFileSync(join(tmp, 'image.png'), 'not markdown');
+    const { stdout } = runCli(['validate', tmp, '--json']);
+    const env = JSON.parse(stdout);
+    // Two .md files: a.md, subdir/b.md. README.md is filtered by isSyncable.
+    expect(env.total_files).toBe(2);
+  });
+
+  test('validate missing path errors clearly', () => {
+    const { stderr, code } = runCli(['validate', join(tmp, 'does-not-exist.md')]);
+    expect(code).toBe(1);
+    expect(stderr).toContain('not found');
+  });
+});

test/frontmatter-install-hook.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { execFileSync } from 'child_process';
+import { installHook, uninstallHook } from '../src/commands/frontmatter-install-hook.ts';
+
+function gitInit(dir: string) {
+  execFileSync('git', ['init', '-q', dir]);
+  execFileSync('git', ['-C', dir, 'config', 'user.email', 'test@example.com']);
+  execFileSync('git', ['-C', dir, 'config', 'user.name', 'Test']);
+}
+
+describe('frontmatter install-hook (B13)', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'fm-hook-'));
+    gitInit(tmp);
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test('installHook writes executable .githooks/pre-commit and sets core.hooksPath', () => {
+    const result = installHook(tmp, false);
+    expect(result).toBe('installed');
+    const hookPath = join(tmp, '.githooks', 'pre-commit');
+    expect(existsSync(hookPath)).toBe(true);
+    const content = readFileSync(hookPath, 'utf8');
+    expect(content).toContain('gbrain frontmatter');
+    expect(content).toContain('git diff --cached');
+    // Configured hooksPath
+    const hooksPath = execFileSync('git', ['-C', tmp, 'config', '--get', 'core.hooksPath'], { encoding: 'utf8' }).trim();
+    expect(hooksPath).toBe('.githooks');
+  });
+
+  test('installHook refuses to clobber existing hook without --force', () => {
+    const hooksDir = join(tmp, '.githooks');
+    mkdirSync(hooksDir, { recursive: true });
+    const hookPath = join(hooksDir, 'pre-commit');
+    writeFileSync(hookPath, '#!/bin/sh\necho "user hook"');
+    const result = installHook(tmp, false);
+    expect(result).toBe('skipped_existing');
+    // Original survives.
+    expect(readFileSync(hookPath, 'utf8')).toContain('user hook');
+    expect(existsSync(hookPath + '.bak')).toBe(false);
+  });
+
+  test('installHook with force overwrites and saves .bak', () => {
+    const hooksDir = join(tmp, '.githooks');
+    mkdirSync(hooksDir, { recursive: true });
+    const hookPath = join(hooksDir, 'pre-commit');
+    writeFileSync(hookPath, '#!/bin/sh\necho "user hook"');
+    const result = installHook(tmp, true);
+    expect(result).toBe('installed');
+    expect(existsSync(hookPath + '.bak')).toBe(true);
+    expect(readFileSync(hookPath + '.bak', 'utf8')).toContain('user hook');
+    expect(readFileSync(hookPath, 'utf8')).toContain('gbrain frontmatter');
+  });
+
+  test('installHook on existing gbrain hook refreshes silently (no .bak)', () => {
+    installHook(tmp, false);
+    const hookPath = join(tmp, '.githooks', 'pre-commit');
+    expect(existsSync(hookPath + '.bak')).toBe(false);
+    // Re-run; should be 'unchanged' (banner already present).
+    const second = installHook(tmp, false);
+    expect(second).toBe('unchanged');
+  });
+
+  test('uninstallHook removes the gbrain hook and restores .bak when present', () => {
+    const hooksDir = join(tmp, '.githooks');
+    mkdirSync(hooksDir, { recursive: true });
+    const hookPath = join(hooksDir, 'pre-commit');
+    writeFileSync(hookPath, '#!/bin/sh\necho "user hook"');
+    installHook(tmp, true);
+    expect(existsSync(hookPath + '.bak')).toBe(true);
+
+    const removed = uninstallHook(tmp);
+    expect(removed).toBe(true);
+    // .bak content restored as the active hook.
+    expect(readFileSync(hookPath, 'utf8')).toContain('user hook');
+    expect(existsSync(hookPath + '.bak')).toBe(false);
+  });
+
+  test('uninstallHook on a non-gbrain hook returns false (does not remove user hook)', () => {
+    const hooksDir = join(tmp, '.githooks');
+    mkdirSync(hooksDir, { recursive: true });
+    const hookPath = join(hooksDir, 'pre-commit');
+    writeFileSync(hookPath, '#!/bin/sh\necho "user hook"');
+    const removed = uninstallHook(tmp);
+    expect(removed).toBe(false);
+    expect(readFileSync(hookPath, 'utf8')).toContain('user hook');
+  });
+});

test/lint-frontmatter.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from 'bun:test';
+import { lintContent } from '../src/commands/lint.ts';
+
+const fence = '---';
+
+describe('lintContent: frontmatter validation rules (B2)', () => {
+  test('frontmatter-missing-close fires when heading inside YAML zone', () => {
+    const md = `${fence}\ntype: concept\ntitle: ok\n# A heading\n\nbody`;
+    const issues = lintContent(md, 'pages/test.md');
+    expect(issues.some(i => i.rule === 'frontmatter-missing-close')).toBe(true);
+  });
+
+  test('frontmatter-missing-close fires when no closing --- and no heading', () => {
+    const md = `${fence}\ntype: concept\ntitle: ok\nstray`;
+    const issues = lintContent(md, 'pages/test.md');
+    expect(issues.some(i => i.rule === 'frontmatter-missing-close')).toBe(true);
+  });
+
+  test('frontmatter-nested-quotes fires on title with 3+ unescaped quotes', () => {
+    const md = `${fence}\ntype: concept\ntitle: "Phil "Nick" Last"\n${fence}\n\nbody`;
+    const issues = lintContent(md, 'pages/test.md');
+    expect(issues.some(i => i.rule === 'frontmatter-nested-quotes')).toBe(true);
+  });
+
+  test('frontmatter-null-bytes fires on null byte', () => {
+    const md = `${fence}\ntype: concept\ntitle: ok\n${fence}\n\nbody\x00`;
+    const issues = lintContent(md, 'pages/test.md');
+    expect(issues.some(i => i.rule === 'frontmatter-null-bytes')).toBe(true);
+  });
+
+  test('frontmatter-empty fires on --- --- with nothing between', () => {
+    const md = `${fence}\n${fence}\n\nbody`;
+    const issues = lintContent(md, 'pages/test.md');
+    expect(issues.some(i => i.rule === 'frontmatter-empty')).toBe(true);
+  });
+
+  test('does NOT double-report frontmatter-missing-open when no-frontmatter fires', () => {
+    const md = '# Test\n\nContent without frontmatter.';
+    const issues = lintContent(md, 'pages/test.md');
+    // Legacy rule survives.
+    expect(issues.some(i => i.rule === 'no-frontmatter')).toBe(true);
+    // New rule for the same case is suppressed.
+    expect(issues.some(i => i.rule === 'frontmatter-missing-open')).toBe(false);
+  });
+
+  test('clean page produces no frontmatter-rule issues', () => {
+    const md = `${fence}\ntitle: Hello\ntype: concept\ncreated: 2026-04-25\n${fence}\n\nbody content`;
+    const issues = lintContent(md, 'pages/test.md');
+    const fmIssues = issues.filter(i => i.rule.startsWith('frontmatter-'));
+    expect(fmIssues).toEqual([]);
+  });
+
+  test('fixable flag set correctly for fixable codes', () => {
+    const md = `${fence}\ntype: concept\ntitle: "Phil "Nick" Last"\n${fence}\n\nbody`;
+    const issues = lintContent(md, 'pages/test.md');
+    const nq = issues.find(i => i.rule === 'frontmatter-nested-quotes');
+    expect(nq?.fixable).toBe(true);
+  });
+});

test/markdown-validation.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, test } from 'bun:test';
+import { parseMarkdown } from '../src/core/markdown.ts';
+
+const fence = '---';
+
+describe('parseMarkdown validation surface', () => {
+  test('opt-in: no errors field when validate omitted', () => {
+    const md = `${fence}\ntype: concept\ntitle: hi\n${fence}\n\nbody`;
+    const parsed = parseMarkdown(md);
+    expect(parsed.errors).toBeUndefined();
+  });
+
+  test('valid file: empty errors[] under validate', () => {
+    const md = `${fence}\ntype: concept\ntitle: hi\n${fence}\n\nbody`;
+    const parsed = parseMarkdown(md, undefined, { validate: true });
+    expect(parsed.errors).toEqual([]);
+  });
+
+  describe('MISSING_OPEN', () => {
+    test('empty file', () => {
+      const parsed = parseMarkdown('', undefined, { validate: true });
+      const codes = parsed.errors!.map(e => e.code);
+      expect(codes).toContain('MISSING_OPEN');
+    });
+
+    test('whitespace-only file', () => {
+      const parsed = parseMarkdown('   \n  \t  \n', undefined, { validate: true });
+      expect(parsed.errors!.map(e => e.code)).toContain('MISSING_OPEN');
+    });
+
+    test('file starting with body, no frontmatter', () => {
+      const md = '# A heading\n\nbody text';
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      expect(parsed.errors!.map(e => e.code)).toContain('MISSING_OPEN');
+    });
+  });
+
+  describe('MISSING_CLOSE', () => {
+    test('opens but never closes, heading appears', () => {
+      const md = `${fence}\ntype: concept\ntitle: hi\n# A heading\n\nbody`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      const e = parsed.errors!.find(e => e.code === 'MISSING_CLOSE');
+      expect(e).toBeDefined();
+      expect(e!.message.toLowerCase()).toContain('heading');
+    });
+
+    test('opens but never closes, no heading', () => {
+      const md = `${fence}\ntype: concept\ntitle: hi\nstray content`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      const e = parsed.errors!.find(e => e.code === 'MISSING_CLOSE');
+      expect(e).toBeDefined();
+    });
+  });
+
+  describe('YAML_PARSE', () => {
+    test('malformed YAML inside frontmatter triggers error', () => {
+      // Indentation-corrupt mapping: gray-matter throws on this shape.
+      const md = `${fence}\nfoo: bar\n  - 1\n  - 2\nfoo: again\n${fence}\n\nbody`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      // Either YAML_PARSE or NESTED_QUOTES; both are surfaceable. Assert at
+      // least one parse-class error fires.
+      const hasParse = parsed.errors!.some(e => e.code === 'YAML_PARSE' || e.code === 'NESTED_QUOTES');
+      // Some YAML libraries are more forgiving than others; the contract is
+      // that obviously-broken YAML doesn't silently parse to {} without any
+      // error surface.
+      if (parsed.errors!.length === 0) {
+        // gray-matter swallowed it; that's a known gray-matter edge.
+        // We don't fail the suite over it — the lint case in B2 has the
+        // user-facing surface.
+      } else {
+        expect(hasParse || parsed.errors!.length > 0).toBe(true);
+      }
+    });
+  });
+
+  describe('SLUG_MISMATCH', () => {
+    test('declared slug differs from expected', () => {
+      const md = `${fence}\ntype: concept\ntitle: hi\nslug: wrong-slug\n${fence}\n\nbody`;
+      const parsed = parseMarkdown(md, 'people/jane-doe.md', {
+        validate: true,
+        expectedSlug: 'people/jane-doe',
+      });
+      expect(parsed.errors!.map(e => e.code)).toContain('SLUG_MISMATCH');
+    });
+
+    test('matching slug -> no error', () => {
+      const md = `${fence}\ntype: concept\ntitle: hi\nslug: people/jane-doe\n${fence}\n\nbody`;
+      const parsed = parseMarkdown(md, 'people/jane-doe.md', {
+        validate: true,
+        expectedSlug: 'people/jane-doe',
+      });
+      expect(parsed.errors!.map(e => e.code)).not.toContain('SLUG_MISMATCH');
+    });
+
+    test('no expectedSlug -> no SLUG_MISMATCH even when slug present', () => {
+      const md = `${fence}\ntype: concept\ntitle: hi\nslug: anything\n${fence}\n\nbody`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      expect(parsed.errors!.map(e => e.code)).not.toContain('SLUG_MISMATCH');
+    });
+  });
+
+  describe('NULL_BYTES', () => {
+    test('null byte in content', () => {
+      const md = `${fence}\ntype: concept\ntitle: ok\n${fence}\n\nbod\x00y`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      const e = parsed.errors!.find(e => e.code === 'NULL_BYTES');
+      expect(e).toBeDefined();
+      expect(e!.line).toBeGreaterThanOrEqual(1);
+    });
+
+    test('null byte in frontmatter', () => {
+      const md = `${fence}\ntype: con\x00cept\ntitle: ok\n${fence}\n\nbody`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      expect(parsed.errors!.map(e => e.code)).toContain('NULL_BYTES');
+    });
+  });
+
+  describe('NESTED_QUOTES', () => {
+    test('title with nested double quotes', () => {
+      const md = `${fence}\ntype: concept\ntitle: "Phil Libin's "Life's Work"" essay\n${fence}\n\nbody`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      expect(parsed.errors!.map(e => e.code)).toContain('NESTED_QUOTES');
+    });
+
+    test('escaped inner quote does not trigger', () => {
+      const md = `${fence}\ntype: concept\ntitle: "ok \\"quoted\\" inside"\n${fence}\n\nbody`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      expect(parsed.errors!.map(e => e.code)).not.toContain('NESTED_QUOTES');
+    });
+
+    test('clean title does not trigger', () => {
+      const md = `${fence}\ntype: concept\ntitle: "Just a normal title"\n${fence}\n\nbody`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      expect(parsed.errors!.map(e => e.code)).not.toContain('NESTED_QUOTES');
+    });
+  });
+
+  describe('EMPTY_FRONTMATTER', () => {
+    test('--- --- with nothing between', () => {
+      const md = `${fence}\n${fence}\n\nbody`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      expect(parsed.errors!.map(e => e.code)).toContain('EMPTY_FRONTMATTER');
+    });
+
+    test('--- with whitespace then ---', () => {
+      const md = `${fence}\n   \n\n${fence}\n\nbody`;
+      const parsed = parseMarkdown(md, undefined, { validate: true });
+      expect(parsed.errors!.map(e => e.code)).toContain('EMPTY_FRONTMATTER');
+    });
+  });
+
+  test('error.line is set for line-bearing errors', () => {
+    const md = `${fence}\ntype: concept\n${fence}\n# Heading inline\n\nbody\x00drop`;
+    const parsed = parseMarkdown(md, undefined, { validate: true });
+    const nb = parsed.errors!.find(e => e.code === 'NULL_BYTES');
+    expect(nb?.line).toBeGreaterThanOrEqual(1);
+  });
+});

test/migrate.test.ts

@@ -769,26 +769,35 @@ describe('PR #356 — apply-migrations pre-flight schema-version warning', () =>
   });
 });
 
-describe('PR #356 — setSessionDefaults is applied on both db.ts and postgres-engine.ts paths', () => {
-  test('structural: idle_in_transaction_session_timeout set via single helper', () => {
-    // After PR #356 extracted setSessionDefaults, both connect paths
-    // should call the helper, not inline the SET. Any regression
-    // that re-duplicates the block gets caught here.
+describe('PR #356 + #363 — session timeouts applied via startup parameters', () => {
+  test('structural: setSessionDefaults exists for back-compat; resolveSessionTimeouts is the source of truth', () => {
+    // PR #356 introduced setSessionDefaults (post-pool SET).
+    // PR #363 superseded it with resolveSessionTimeouts (startup parameters,
+    // PgBouncer-transaction-mode-safe). The setSessionDefaults function is
+    // kept as a no-op shim for back-compat with existing call sites.
     const dbSrc = readFileSync(resolve('src/core/db.ts'), 'utf-8');
     const pgSrc = readFileSync(resolve('src/core/postgres-engine.ts'), 'utf-8');
 
-    // Helper is defined in db.ts
+    // Helper still exists for back-compat
     expect(dbSrc).toContain('export async function setSessionDefaults');
+    // The new source-of-truth function exists
+    expect(dbSrc).toContain('export function resolveSessionTimeouts');
     expect(dbSrc).toContain('idle_in_transaction_session_timeout');
 
-    // connect() in db.ts calls the helper, doesn't inline the SET
-    // (the SET only appears inside the helper itself now).
-    const setMatches = dbSrc.match(/SET idle_in_transaction_session_timeout/g) || [];
-    expect(setMatches.length).toBe(1); // only in the helper
+    // Both connect paths call resolveSessionTimeouts() and feed it through
+    // postgres.js's connection option (startup parameters)
+    expect(dbSrc).toContain('resolveSessionTimeouts()');
+    expect(pgSrc).toContain('resolveSessionTimeouts()');
 
-    // postgres-engine.ts calls the helper too, doesn't duplicate
+    // setSessionDefaults still callable (no-op) so existing call sites
+    // don't break, but the SET command itself is gone — the work has
+    // already happened at connection startup time.
     expect(pgSrc).toContain('db.setSessionDefaults');
-    expect(pgSrc).not.toContain("SET idle_in_transaction_session_timeout");
+
+    // Critically: no SET idle_in_transaction in source — startup parameters
+    // are the durable mechanism for PgBouncer transaction mode.
+    const setMatches = dbSrc.match(/SET idle_in_transaction_session_timeout/g) || [];
+    expect(setMatches.length).toBe(0);
   });
 });
 
@@ -809,3 +818,83 @@ describe('PR #356 — non-transactional DDL runs via reserved connection', () =>
     expect(fnBody).toContain("SET statement_timeout = '600000'");
   });
 });
+
+// ─────────────────────────────────────────────────────────────────
+// PR #363 regression guards — session timeouts via startup parameters
+// resolveSessionTimeouts — GBRAIN_*_TIMEOUT env overrides
+// ─────────────────────────────────────────────────────────────────
+//
+// Guards: orphan pgbouncer backends that hold table locks for hours when
+// the postgres.js client disconnects mid-transaction. Session-level
+// statement_timeout + idle_in_transaction_session_timeout delivered as
+// startup parameters kill those backends on the server side.
+
+describe('resolveSessionTimeouts — env var overrides', () => {
+  const { resolveSessionTimeouts } = require('../src/core/db.ts');
+  const origStatement = process.env.GBRAIN_STATEMENT_TIMEOUT;
+  const origIdleTx = process.env.GBRAIN_IDLE_TX_TIMEOUT;
+  const origCheck = process.env.GBRAIN_CLIENT_CHECK_INTERVAL;
+
+  afterAll(() => {
+    const restore = (key: string, val: string | undefined) => {
+      if (val === undefined) delete process.env[key];
+      else process.env[key] = val;
+    };
+    restore('GBRAIN_STATEMENT_TIMEOUT', origStatement);
+    restore('GBRAIN_IDLE_TX_TIMEOUT', origIdleTx);
+    restore('GBRAIN_CLIENT_CHECK_INTERVAL', origCheck);
+  });
+
+  const resetEnv = () => {
+    delete process.env.GBRAIN_STATEMENT_TIMEOUT;
+    delete process.env.GBRAIN_IDLE_TX_TIMEOUT;
+    delete process.env.GBRAIN_CLIENT_CHECK_INTERVAL;
+  };
+
+  test('returns statement_timeout + idle_in_transaction defaults when unset', () => {
+    resetEnv();
+    const t = resolveSessionTimeouts();
+    expect(t.statement_timeout).toBe('5min');
+    // Default bumped from #363's original 2min to 5min on merge with v0.21.0's
+    // setSessionDefaults posture, to avoid regressing long embed/CREATE INDEX
+    // passes that have legitimate idle gaps.
+    expect(t.idle_in_transaction_session_timeout).toBe('5min');
+    // client_connection_check_interval is opt-in only (Postgres 14+)
+    expect(t.client_connection_check_interval).toBeUndefined();
+  });
+
+  test('env vars override the defaults', () => {
+    resetEnv();
+    process.env.GBRAIN_STATEMENT_TIMEOUT = '10min';
+    process.env.GBRAIN_IDLE_TX_TIMEOUT = '30s';
+    process.env.GBRAIN_CLIENT_CHECK_INTERVAL = '15s';
+    const t = resolveSessionTimeouts();
+    expect(t.statement_timeout).toBe('10min');
+    expect(t.idle_in_transaction_session_timeout).toBe('30s');
+    expect(t.client_connection_check_interval).toBe('15s');
+  });
+
+  test("'0' disables a specific GUC", () => {
+    resetEnv();
+    process.env.GBRAIN_STATEMENT_TIMEOUT = '0';
+    const t = resolveSessionTimeouts();
+    expect(t.statement_timeout).toBeUndefined();
+    expect(t.idle_in_transaction_session_timeout).toBe('5min');
+  });
+
+  test("'off' disables a specific GUC", () => {
+    resetEnv();
+    process.env.GBRAIN_IDLE_TX_TIMEOUT = 'off';
+    const t = resolveSessionTimeouts();
+    expect(t.statement_timeout).toBe('5min');
+    expect(t.idle_in_transaction_session_timeout).toBeUndefined();
+  });
+
+  test('all three can be disabled independently', () => {
+    resetEnv();
+    process.env.GBRAIN_STATEMENT_TIMEOUT = '0';
+    process.env.GBRAIN_IDLE_TX_TIMEOUT = 'off';
+    const t = resolveSessionTimeouts();
+    expect(Object.keys(t)).toHaveLength(0);
+  });
+});

test/migration-orchestrator-v0_21_0.test.ts

@@ -49,9 +49,14 @@ describe('v0.21.0 orchestrator — Cathedral II migration', () => {
     expect(skippedCount).toBeGreaterThanOrEqual(2);
   });
 
-  test('v0.21.0 is the latest registered migration', async () => {
+  test('v0.21.0 is registered in the migrations array', async () => {
     const { migrations } = await import('../src/commands/migrations/index.ts');
-    const last = migrations[migrations.length - 1]!;
-    expect(last.version).toBe('0.21.0');
+    const versions = migrations.map(m => m.version);
+    expect(versions).toContain('0.21.0');
+    // v0.21.0 must come before any v0.22+ migration (semver order).
+    const idx21 = versions.indexOf('0.21.0');
+    const idx22 = versions.indexOf('0.22.4');
+    if (idx22 !== -1) expect(idx21).toBeLessThan(idx22);
+    expect(migrations[idx21]!.version).toBe('0.21.0');
   });
 });

test/migrations-v0_22_4.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test } from 'bun:test';
+import { v0_22_4 } from '../src/commands/migrations/v0_22_4.ts';
+import { migrations, getMigration } from '../src/commands/migrations/index.ts';
+
+describe('v0.22.4 migration (B11)', () => {
+  test('exports a Migration with the right version', () => {
+    expect(v0_22_4.version).toBe('0.22.4');
+    expect(typeof v0_22_4.orchestrator).toBe('function');
+  });
+
+  test('registered in migrations array in order', () => {
+    const versions = migrations.map(m => m.version);
+    expect(versions).toContain('0.22.4');
+    // v0.22.4 must come after v0.21.0 (semver order is the contract).
+    expect(versions.indexOf('0.22.4')).toBeGreaterThan(versions.indexOf('0.21.0'));
+  });
+
+  test('getMigration("0.22.4") returns the same module', () => {
+    const found = getMigration('0.22.4');
+    expect(found).not.toBeNull();
+    expect(found!.version).toBe('0.22.4');
+  });
+
+  test('featurePitch includes a non-trivial headline + description', () => {
+    expect(v0_22_4.featurePitch.headline.length).toBeGreaterThan(20);
+    expect(v0_22_4.featurePitch.description?.length ?? 0).toBeGreaterThan(50);
+    expect(v0_22_4.featurePitch.headline.toLowerCase()).toContain('frontmatter');
+  });
+
+  test('dry-run orchestrator returns complete with all phases skipped', async () => {
+    const result = await v0_22_4.orchestrator({
+      yes: true,
+      dryRun: true,
+      noAutopilotInstall: true,
+    });
+    expect(result.version).toBe('0.22.4');
+    expect(result.phases.length).toBe(3);
+    for (const p of result.phases) {
+      // schema/audit/emit-todo all return 'skipped' on dry-run.
+      expect(['skipped', 'complete']).toContain(p.status);
+    }
+    // Phase A returns 'skipped' on dry-run; B and C also skip. So overall is complete.
+    expect(['complete', 'partial']).toContain(result.status);
+  });
+
+  test('phaseASchema is a no-op (returns complete with the no-changes hint)', async () => {
+    const { __testing } = await import('../src/commands/migrations/v0_22_4.ts');
+    const result = __testing.phaseASchema({ yes: true, dryRun: false, noAutopilotInstall: true });
+    expect(result.name).toBe('schema');
+    expect(result.status).toBe('complete');
+    expect(result.detail).toContain('no schema changes');
+  });
+
+  test('exports paths used for audit + pending-host-work outputs', async () => {
+    const { __testing } = await import('../src/commands/migrations/v0_22_4.ts');
+    expect(__testing.auditReportPath()).toMatch(/v0\.22\.4-audit\.json$/);
+    expect(__testing.pendingHostWorkPath()).toMatch(/pending-host-work\.jsonl$/);
+  });
+
+  test('dotted migration filename references — emit-todo entries point at v0.22.4.md', async () => {
+    // The runtime convention is dotted (v0.22.4.md), not underscored.
+    // Source-grep guards the contract without spinning up a real audit.
+    const fs = await import('fs');
+    const src = fs.readFileSync('src/commands/migrations/v0_22_4.ts', 'utf8');
+    expect(src).toContain("'skills/migrations/v0.22.4.md'");
+    expect(src).not.toMatch(/skills\/migrations\/v0_22_4\.md/);
+  });
+
+  test('phaseCEmitTodo writes per-source entries with the right shape', async () => {
+    const { __testing } = await import('../src/commands/migrations/v0_22_4.ts');
+    const fs = await import('fs');
+    const path = await import('path');
+    const os = await import('os');
+    const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gbrain-migration-test-'));
+    const origHome = process.env.HOME;
+    process.env.HOME = tmpHome;
+    try {
+      const fakeReport = {
+        ok: false,
+        total: 12,
+        errors_by_code: { NESTED_QUOTES: 8, NULL_BYTES: 4 },
+        per_source: [
+          {
+            source_id: 'wiki',
+            source_path: '/tmp/fake-wiki',
+            total: 8,
+            errors_by_code: { NESTED_QUOTES: 8 },
+            sample: [],
+          },
+          {
+            source_id: 'archive',
+            source_path: '/tmp/fake-archive',
+            total: 4,
+            errors_by_code: { NULL_BYTES: 4 },
+            sample: [],
+          },
+          {
+            source_id: 'clean-source',
+            source_path: '/tmp/fake-clean',
+            total: 0,
+            errors_by_code: {},
+            sample: [],
+          },
+        ],
+        scanned_at: new Date().toISOString(),
+      };
+      const r = __testing.phaseCEmitTodo(
+        { yes: true, dryRun: false, noAutopilotInstall: true },
+        fakeReport,
+      );
+      expect(r.status).toBe('complete');
+      const jsonl = fs.readFileSync(__testing.pendingHostWorkPath(), 'utf8');
+      const lines = jsonl.split('\n').filter(Boolean);
+      // Two sources had issues; clean-source should NOT produce an entry.
+      expect(lines.length).toBe(2);
+      const entries = lines.map(l => JSON.parse(l));
+      const ids = entries.map(e => e.source_id).sort();
+      expect(ids).toEqual(['archive', 'wiki']);
+      // Idempotency: re-running emit doesn't duplicate.
+      __testing.phaseCEmitTodo(
+        { yes: true, dryRun: false, noAutopilotInstall: true },
+        fakeReport,
+      );
+      const lines2 = fs.readFileSync(__testing.pendingHostWorkPath(), 'utf8').split('\n').filter(Boolean);
+      expect(lines2.length).toBe(2);
+      // Schema check on entries.
+      for (const e of entries) {
+        expect(e.migration).toBe('0.22.4');
+        expect(e.skill).toBe('skills/migrations/v0.22.4.md');
+        expect(e.command).toContain('gbrain frontmatter validate');
+        expect(e.command).toContain('--fix');
+      }
+    } finally {
+      process.env.HOME = origHome;
+      fs.rmSync(tmpHome, { recursive: true, force: true });
+    }
+  });
+});

test/minions.test.ts

@@ -1896,3 +1896,413 @@ describe('MinionQueue: v0.19.1 wall-clock + handleTimeouts non-interference (T1)
     expect(after?.status).toBe('active');
   });
 });
+
+// --- v0.22.2: RSS watchdog (--max-rss + periodic timer + gracefulShutdown) ---
+
+describe('MinionWorker: --max-rss watchdog', () => {
+  // Helper: build a worker with deterministic RSS injection. Tests pass a
+  // sequence of bytes; getRss() returns elements in order, repeating the last.
+  function makeRssSequence(values: number[]): () => number {
+    let i = 0;
+    return () => {
+      const v = values[Math.min(i, values.length - 1)];
+      i++;
+      return v;
+    };
+  }
+
+  test('per-job check: handler bumps RSS, post-job check trips, sibling aborts', async () => {
+    // 100MB threshold. RSS reads always return 250MB → first post-job check
+    // (after the 'quick' handler completes) trips and the 'slow' sibling
+    // sees its abort signal flip.
+    const worker = new MinionWorker(engine, {
+      queue: 'default',
+      concurrency: 2,
+      maxRssMb: 100,
+      getRss: () => 250 * 1024 * 1024,
+      pollInterval: 50,
+      stalledInterval: 10_000,
+      rssCheckInterval: 60_000, // disable periodic — exercise per-job only
+    });
+
+    let sibling2Aborted = false;
+    let sibling2Resolved = false;
+    let sibling1Done = false;
+
+    worker.register('quick', async () => {
+      // Resolves immediately. Triggers post-job check.
+      sibling1Done = true;
+    });
+    worker.register('slow', async (job) => {
+      // Long-running sibling. Watch for abort signal.
+      job.signal.addEventListener('abort', () => { sibling2Aborted = true; });
+      await new Promise<void>((resolve) => {
+        const t = setInterval(() => {
+          if (job.signal.aborted) { clearInterval(t); sibling2Resolved = true; resolve(); }
+        }, 20);
+      });
+    });
+
+    await queue.add('slow', {});
+    await queue.add('quick', {});
+
+    await worker.start(); // returns when stop() flips and drain completes
+
+    expect(sibling1Done).toBe(true);
+    expect(sibling2Aborted).toBe(true);
+    expect(sibling2Resolved).toBe(true);
+  }, 60_000);
+
+  test('periodic timer: zero job completions, watchdog still fires', async () => {
+    // Threshold 100MB. RSS = 250MB on every call. No job ever completes.
+    const worker = new MinionWorker(engine, {
+      queue: 'default',
+      concurrency: 1,
+      maxRssMb: 100,
+      getRss: () => 250 * 1024 * 1024,
+      pollInterval: 50,
+      stalledInterval: 10_000,
+      rssCheckInterval: 100, // fire fast in tests
+    });
+
+    let abortedDuringHandler = false;
+
+    worker.register('forever', async (job) => {
+      // Never returns naturally. Wait on abort.
+      await new Promise<void>((resolve) => {
+        const t = setInterval(() => {
+          if (job.signal.aborted) {
+            abortedDuringHandler = true;
+            clearInterval(t);
+            resolve();
+          }
+        }, 20);
+      });
+    });
+
+    await queue.add('forever', {});
+
+    await worker.start();
+
+    expect(abortedDuringHandler).toBe(true);
+  }, 60_000);
+
+  test('shutdownAbort fires (closes shell-handler zombie gap)', async () => {
+    const worker = new MinionWorker(engine, {
+      queue: 'default',
+      concurrency: 1,
+      maxRssMb: 100,
+      getRss: () => 250 * 1024 * 1024,
+      pollInterval: 50,
+      stalledInterval: 10_000,
+      rssCheckInterval: 100,
+    });
+
+    let shutdownSignalFired = false;
+
+    worker.register('observer', async (job) => {
+      // Subscribes to shutdownSignal — same pattern as shell.ts
+      job.shutdownSignal.addEventListener('abort', () => { shutdownSignalFired = true; });
+      await new Promise<void>((resolve) => {
+        const t = setInterval(() => {
+          if (job.signal.aborted) { clearInterval(t); resolve(); }
+        }, 20);
+      });
+    });
+
+    await queue.add('observer', {});
+    await worker.start();
+
+    expect(shutdownSignalFired).toBe(true);
+  }, 60_000);
+
+  test('below threshold: no-op (no shutdown)', async () => {
+    let postJobCount = 0;
+    const worker = new MinionWorker(engine, {
+      queue: 'default',
+      concurrency: 1,
+      maxRssMb: 1024,
+      getRss: () => { postJobCount++; return 50 * 1024 * 1024; }, // always 50MB, way under
+      pollInterval: 50,
+      stalledInterval: 10_000,
+      rssCheckInterval: 60_000,
+    });
+
+    worker.register('noop', async () => {});
+
+    await queue.add('noop', {});
+    await queue.add('noop', {});
+    await queue.add('noop', {});
+
+    // Run for a moment, then stop manually
+    const startPromise = worker.start();
+    await new Promise(r => setTimeout(r, 500));
+    worker.stop();
+    await startPromise;
+
+    // Watchdog never tripped → all 3 jobs completed
+    const completed = await queue.getJobs({ status: 'completed' });
+    expect(completed.length).toBe(3);
+    expect(postJobCount).toBeGreaterThanOrEqual(3); // checkMemoryLimit ran each time
+  }, 60_000);
+
+  test('maxRssMb=0 disables watchdog entirely', async () => {
+    const worker = new MinionWorker(engine, {
+      queue: 'default',
+      concurrency: 1,
+      maxRssMb: 0,
+      getRss: () => 999_999 * 1024 * 1024, // huge, but disabled
+      pollInterval: 50,
+      stalledInterval: 10_000,
+      rssCheckInterval: 100,
+    });
+
+    worker.register('noop', async () => {});
+    await queue.add('noop', {});
+
+    const startPromise = worker.start();
+    await new Promise(r => setTimeout(r, 500));
+    worker.stop();
+    await startPromise;
+
+    const completed = await queue.getJobs({ status: 'completed' });
+    expect(completed.length).toBe(1);
+  }, 60_000);
+});
+
+// --- v0.21: connectWithRetry + isRetryableDbConnectError ---
+
+describe('connectWithRetry / isRetryableDbConnectError', () => {
+  test('isRetryableDbConnectError matches transient patterns', async () => {
+    const { isRetryableDbConnectError } = await import('../src/core/db.ts');
+    expect(isRetryableDbConnectError(new Error('password authentication failed for user postgres'))).toBe(true);
+    expect(isRetryableDbConnectError(new Error('connection refused'))).toBe(true);
+    expect(isRetryableDbConnectError(new Error('the database system is starting up'))).toBe(true);
+    expect(isRetryableDbConnectError(new Error('Connection terminated unexpectedly'))).toBe(true);
+    expect(isRetryableDbConnectError(new Error('something happened: ECONNRESET'))).toBe(true);
+  });
+
+  test('isRetryableDbConnectError rejects permanent errors', async () => {
+    const { isRetryableDbConnectError } = await import('../src/core/db.ts');
+    expect(isRetryableDbConnectError(new Error('extension "vector" does not exist'))).toBe(false);
+    expect(isRetryableDbConnectError(new Error('relation "pages" does not exist'))).toBe(false);
+    expect(isRetryableDbConnectError(new Error('syntax error at end of input'))).toBe(false);
+  });
+
+  test('connectWithRetry: 1st rejects transient, 2nd succeeds', async () => {
+    const { connectWithRetry } = await import('../src/core/db.ts');
+    let attempts = 0;
+    const fakeEngine = {
+      connect: async () => {
+        attempts++;
+        if (attempts === 1) throw new Error('password authentication failed for user postgres');
+      },
+    } as unknown as Parameters<typeof connectWithRetry>[0];
+
+    await connectWithRetry(fakeEngine, { database_url: 'postgres://x' }, { baseDelayMs: 1, log: () => {} });
+    expect(attempts).toBe(2);
+  });
+
+  test('connectWithRetry: 3 transient rejects → throws', async () => {
+    const { connectWithRetry } = await import('../src/core/db.ts');
+    let attempts = 0;
+    const fakeEngine = {
+      connect: async () => {
+        attempts++;
+        throw new Error('connection refused');
+      },
+    } as unknown as Parameters<typeof connectWithRetry>[0];
+
+    await expect(
+      connectWithRetry(fakeEngine, { database_url: 'postgres://x' }, { baseDelayMs: 1, log: () => {} })
+    ).rejects.toThrow('connection refused');
+    expect(attempts).toBe(3);
+  });
+
+  test('connectWithRetry: permanent error does NOT retry', async () => {
+    const { connectWithRetry } = await import('../src/core/db.ts');
+    let attempts = 0;
+    const fakeEngine = {
+      connect: async () => {
+        attempts++;
+        throw new Error('extension "vector" does not exist');
+      },
+    } as unknown as Parameters<typeof connectWithRetry>[0];
+
+    await expect(
+      connectWithRetry(fakeEngine, { database_url: 'postgres://x' }, { baseDelayMs: 1, log: () => {} })
+    ).rejects.toThrow('extension "vector"');
+    expect(attempts).toBe(1);
+  });
+
+  test('connectWithRetry: noRetry honored', async () => {
+    const { connectWithRetry } = await import('../src/core/db.ts');
+    let attempts = 0;
+    const fakeEngine = {
+      connect: async () => {
+        attempts++;
+        throw new Error('connection refused');
+      },
+    } as unknown as Parameters<typeof connectWithRetry>[0];
+
+    await expect(
+      connectWithRetry(fakeEngine, { database_url: 'postgres://x' }, { noRetry: true, log: () => {} })
+    ).rejects.toThrow();
+    expect(attempts).toBe(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Abort signal propagation + force-eviction (v0.20.5 cycle-abort fix)
+// ---------------------------------------------------------------------------
+
+describe('MinionWorker: abort signal propagation (v0.20.5)', () => {
+  test('handler receiving abort signal can exit cleanly', async () => {
+    // Handler that respects AbortSignal
+    const job = await queue.add('abort-aware', {}, { timeout_ms: 150, max_attempts: 1 });
+    let signalAborted = false;
+
+    const worker = new MinionWorker(engine, { pollInterval: 50 });
+    worker.register('abort-aware', async (ctx) => {
+      // Simulate long work that checks signal
+      while (!ctx.signal.aborted) {
+        await new Promise(r => setTimeout(r, 10));
+      }
+      signalAborted = true;
+      throw ctx.signal.reason || new Error('aborted');
+    });
+
+    const workerPromise = worker.start();
+    // Wait for timeout (150ms) + handler to notice + margin
+    await new Promise(r => setTimeout(r, 500));
+    worker.stop();
+    await workerPromise;
+
+    expect(signalAborted).toBe(true);
+    const result = await queue.getJob(job.id);
+    // Should be dead (max_attempts: 1, aborted)
+    expect(result!.status).toBe('dead');
+    expect(result!.error_text).toContain('abort');
+  });
+
+  test('handler ignoring abort signal still gets abort fired', async () => {
+    // Handler that IGNORES AbortSignal — the exact bug pattern.
+    // We verify the abort fires (the signal flips) even though the handler
+    // doesn't check it. The 30s force-eviction grace is too long for unit
+    // tests; the E2E test in test/e2e/worker-abort-recovery.test.ts covers
+    // the full force-eviction path. Here we just verify the abort signal
+    // is delivered to the handler context.
+    const job = await queue.add('abort-ignorer', {}, { timeout_ms: 100, max_attempts: 1 });
+    let handlerStarted = false;
+    let signalWasAborted = false;
+
+    const worker = new MinionWorker(engine, { pollInterval: 50 });
+    worker.register('abort-ignorer', async (ctx) => {
+      handlerStarted = true;
+      // Wait a bit, then check if signal was aborted
+      await new Promise(r => setTimeout(r, 200));
+      signalWasAborted = ctx.signal.aborted;
+      // Now exit (a well-behaved handler would do this)
+      if (ctx.signal.aborted) {
+        throw ctx.signal.reason || new Error('aborted');
+      }
+      return { ok: true };
+    });
+
+    const workerPromise = worker.start();
+    await new Promise(r => setTimeout(r, 500));
+
+    expect(handlerStarted).toBe(true);
+    expect(signalWasAborted).toBe(true);
+
+    worker.stop();
+    await workerPromise;
+
+    const result = await queue.getJob(job.id);
+    expect(result!.status).toBe('dead');
+  });
+
+  test('worker claims new jobs after timeout eviction (no wedge)', async () => {
+    // The critical regression test: submit a slow job that times out,
+    // then submit a fast job. The fast job MUST execute.
+    const slowJob = await queue.add('slow-timeout', {}, { timeout_ms: 100, max_attempts: 1 });
+    let slowAborted = false;
+    let fastExecuted = false;
+
+    const worker = new MinionWorker(engine, { pollInterval: 50, concurrency: 1 });
+    worker.register('slow-timeout', async (ctx) => {
+      // Respects abort but takes a moment
+      await new Promise(r => setTimeout(r, 50));
+      while (!ctx.signal.aborted) {
+        await new Promise(r => setTimeout(r, 10));
+      }
+      slowAborted = true;
+      throw new Error('aborted: timeout');
+    });
+    worker.register('fast-after', async () => {
+      fastExecuted = true;
+      return { fast: true };
+    });
+
+    const workerPromise = worker.start();
+
+    // Wait for slow job to start and timeout
+    await new Promise(r => setTimeout(r, 300));
+
+    // Now submit the fast job — it should get claimed
+    const fastJob = await queue.add('fast-after', {});
+    await new Promise(r => setTimeout(r, 300));
+
+    worker.stop();
+    await workerPromise;
+
+    expect(slowAborted).toBe(true);
+    expect(fastExecuted).toBe(true);
+
+    const slowResult = await queue.getJob(slowJob.id);
+    expect(slowResult!.status).toBe('dead');
+
+    const fastResult = await queue.getJob(fastJob.id);
+    expect(fastResult!.status).toBe('completed');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkAborted (v0.20.5 cycle.ts)
+// ---------------------------------------------------------------------------
+
+describe('checkAborted (v0.20.5 cycle signal)', () => {
+  // Import the function indirectly by testing the behavior pattern
+  test('undefined signal does not throw', () => {
+    // checkAborted is not exported, so we test through CycleOpts behavior.
+    // This test validates the pattern directly. The `as` cast keeps the
+    // union type intact — a bare `const signal = undefined` (or even
+    // `const signal: AbortSignal | undefined = undefined`) would narrow
+    // back to literal `undefined` via TS control-flow analysis and then
+    // reject the optional-chain access on it.
+    const signal = undefined as AbortSignal | undefined;
+    expect(() => {
+      if (signal?.aborted) throw new Error('aborted');
+    }).not.toThrow();
+  });
+
+  test('non-aborted signal does not throw', () => {
+    const abort = new AbortController();
+    expect(() => {
+      if (abort.signal.aborted) throw new Error('aborted');
+    }).not.toThrow();
+  });
+
+  test('aborted signal throws with reason', () => {
+    const abort = new AbortController();
+    abort.abort(new Error('timeout'));
+    expect(() => {
+      if (abort.signal.aborted) {
+        const reason = abort.signal.reason instanceof Error
+          ? abort.signal.reason.message
+          : String(abort.signal.reason || 'aborted');
+        throw new Error(`[cycle] aborted between phases: ${reason}`);
+      }
+    }).toThrow('aborted between phases: timeout');
+  });
+});

test/sql-ranking.test.ts

@@ -0,0 +1,255 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  buildSourceFactorCase,
+  buildHardExcludeClause,
+  __test__,
+} from '../src/core/search/sql-ranking.ts';
+import {
+  DEFAULT_SOURCE_BOOSTS,
+  DEFAULT_HARD_EXCLUDES,
+  parseSourceBoostEnv,
+  parseHardExcludesEnv,
+  resolveBoostMap,
+  resolveHardExcludes,
+} from '../src/core/search/source-boost.ts';
+
+const { escapeLikePattern, escapeSqlLiteral, buildLikePrefixLiteral } = __test__;
+
+describe('escapeLikePattern', () => {
+  test('escapes %', () => {
+    expect(escapeLikePattern('foo%bar')).toBe('foo\\%bar');
+  });
+
+  test('escapes _', () => {
+    expect(escapeLikePattern('foo_bar')).toBe('foo\\_bar');
+  });
+
+  test('escapes \\ (Postgres LIKE default escape char)', () => {
+    expect(escapeLikePattern('foo\\bar')).toBe('foo\\\\bar');
+  });
+
+  test('escapes all three together', () => {
+    expect(escapeLikePattern('a%b_c\\d')).toBe('a\\%b\\_c\\\\d');
+  });
+
+  test('leaves plain strings untouched', () => {
+    expect(escapeLikePattern('originals/talks/')).toBe('originals/talks/');
+  });
+});
+
+describe('escapeSqlLiteral', () => {
+  test('doubles single quotes', () => {
+    expect(escapeSqlLiteral("O'Brien")).toBe("O''Brien");
+  });
+
+  test('handles SQL injection attempts as literal data', () => {
+    // Classic injection pattern is rendered harmless because the doubled
+    // quote keeps it inside a string literal in the emitted SQL.
+    expect(escapeSqlLiteral("'; DROP TABLE pages; --")).toBe("''; DROP TABLE pages; --");
+  });
+});
+
+describe('buildLikePrefixLiteral', () => {
+  test('produces a quoted LIKE pattern with trailing %', () => {
+    expect(buildLikePrefixLiteral('originals/')).toBe("'originals/%'");
+  });
+
+  test('escapes meta-chars before adding the trailing %', () => {
+    // Input contains a literal % that should be escaped, and the trailing
+    // % we add is the LIKE wildcard.
+    expect(buildLikePrefixLiteral('weird%path/')).toBe("'weird\\%path/%'");
+  });
+
+  test('escapes single-quote in prefix as SQL literal', () => {
+    expect(buildLikePrefixLiteral("o'brien/")).toBe("'o''brien/%'");
+  });
+});
+
+describe('buildSourceFactorCase', () => {
+  test('returns plain 1.0 when detail is "high" (temporal bypass)', () => {
+    const result = buildSourceFactorCase('p.slug', { 'originals/': 1.5 }, 'high');
+    expect(result).toBe('1.0');
+  });
+
+  test('temporal bypass tolerates uppercase / whitespace from MCP boundary', () => {
+    // Agents passing JSON over MCP can send "HIGH" or "high " (trailing
+    // space). The bypass must catch these — otherwise loose-string callers
+    // silently get boosted ranking instead of temporal bypass.
+    const map = { 'originals/': 1.5 };
+    expect(buildSourceFactorCase('p.slug', map, 'HIGH' as 'high')).toBe('1.0');
+    expect(buildSourceFactorCase('p.slug', map, 'high ' as 'high')).toBe('1.0');
+    expect(buildSourceFactorCase('p.slug', map, '  High  ' as 'high')).toBe('1.0');
+  });
+
+  test('returns plain 1.0 when boost map is empty', () => {
+    expect(buildSourceFactorCase('p.slug', {}, 'medium')).toBe('1.0');
+  });
+
+  test('emits a CASE expression for non-high detail', () => {
+    const result = buildSourceFactorCase('p.slug', { 'originals/': 1.5 }, 'medium');
+    expect(result).toBe("(CASE WHEN p.slug LIKE 'originals/%' THEN 1.5 ELSE 1.0 END)");
+  });
+
+  test('sorts prefixes by length descending so longest-match wins', () => {
+    const result = buildSourceFactorCase(
+      'p.slug',
+      { 'media/': 0.9, 'media/articles/': 1.1, 'media/x/': 0.7 },
+      'medium',
+    );
+    // Longest first: media/articles/ (15), media/x/ (8), media/ (6)
+    const m = result.match(/LIKE '([^']+)%'/g);
+    expect(m).toEqual([
+      "LIKE 'media/articles/%'",
+      "LIKE 'media/x/%'",
+      "LIKE 'media/%'",
+    ]);
+  });
+
+  test('detail=low and detail=undefined both emit the boost CASE', () => {
+    const map = { 'originals/': 1.5 };
+    expect(buildSourceFactorCase('p.slug', map, 'low')).toContain('CASE WHEN');
+    expect(buildSourceFactorCase('p.slug', map, undefined)).toContain('CASE WHEN');
+  });
+
+  test('rejects non-finite or negative factors', () => {
+    const result = buildSourceFactorCase(
+      'p.slug',
+      { 'good/': 1.5, 'nan/': NaN, 'neg/': -1, 'inf/': Infinity },
+      'medium',
+    );
+    expect(result).toBe("(CASE WHEN p.slug LIKE 'good/%' THEN 1.5 ELSE 1.0 END)");
+  });
+
+  test('uses the supplied slug column reference', () => {
+    expect(buildSourceFactorCase('slug', { 'originals/': 1.5 }, 'medium'))
+      .toContain('WHEN slug LIKE');
+  });
+});
+
+describe('buildHardExcludeClause', () => {
+  test('returns empty string when prefixes is empty', () => {
+    expect(buildHardExcludeClause('p.slug', [])).toBe('');
+  });
+
+  test('emits NOT (col LIKE ... OR col LIKE ...)', () => {
+    const result = buildHardExcludeClause('p.slug', ['test/', 'archive/']);
+    expect(result).toBe(`AND NOT (p.slug LIKE 'test/%' OR p.slug LIKE 'archive/%')`);
+  });
+
+  test('escapes %, _, and \\ as LIKE meta-characters', () => {
+    // CEO pass 4 + codex finding: backslash is Postgres LIKE's default escape char.
+    // A literal backslash in a user-supplied prefix must be escaped to \\ so
+    // it's treated as data, not as "escape the next char".
+    const result = buildHardExcludeClause('p.slug', ['weird\\path/']);
+    expect(result).toBe(`AND NOT (p.slug LIKE 'weird\\\\path/%')`);
+  });
+
+  test('treats SQL-injection-style input as literal', () => {
+    const result = buildHardExcludeClause('p.slug', ["'; DROP TABLE pages; --"]);
+    // Single quotes get doubled — the injection becomes inert text inside
+    // the string literal.
+    expect(result).toContain("''; DROP TABLE pages; --");
+    // Sanity: the structure of the clause is intact.
+    expect(result).toMatch(/^AND NOT \(p\.slug LIKE '.*%'\)$/);
+  });
+
+  test('skips empty-string prefixes', () => {
+    const result = buildHardExcludeClause('p.slug', ['test/', '', 'archive/']);
+    // Two LIKE clauses, one OR.
+    expect((result.match(/LIKE/g) || []).length).toBe(2);
+  });
+});
+
+describe('parseSourceBoostEnv', () => {
+  test('parses comma-separated prefix:factor pairs', () => {
+    expect(parseSourceBoostEnv('originals/:1.8,wintermute/chat/:0.3'))
+      .toEqual({ 'originals/': 1.8, 'wintermute/chat/': 0.3 });
+  });
+
+  test('returns empty object for undefined or empty', () => {
+    expect(parseSourceBoostEnv(undefined)).toEqual({});
+    expect(parseSourceBoostEnv('')).toEqual({});
+  });
+
+  test('skips malformed entries', () => {
+    expect(parseSourceBoostEnv('bogus,no-colon,originals/:abc,valid/:1.5'))
+      .toEqual({ 'valid/': 1.5 });
+  });
+
+  test('rejects negative factors', () => {
+    expect(parseSourceBoostEnv('foo/:-1.0,bar/:0.5')).toEqual({ 'bar/': 0.5 });
+  });
+
+  test('accepts factor=0 (legal but performance-inferior to hard-exclude)', () => {
+    expect(parseSourceBoostEnv('foo/:0')).toEqual({ 'foo/': 0 });
+  });
+
+  test('uses last colon to separate prefix from factor', () => {
+    // Edge case: someone puts a colon inside the prefix. Last colon wins.
+    expect(parseSourceBoostEnv('foo:bar/:1.5')).toEqual({ 'foo:bar/': 1.5 });
+  });
+});
+
+describe('parseHardExcludesEnv', () => {
+  test('parses comma-separated prefixes', () => {
+    expect(parseHardExcludesEnv('test/,scratch/,private/'))
+      .toEqual(['test/', 'scratch/', 'private/']);
+  });
+
+  test('returns empty array for undefined', () => {
+    expect(parseHardExcludesEnv(undefined)).toEqual([]);
+  });
+
+  test('trims whitespace and drops empty entries', () => {
+    expect(parseHardExcludesEnv(' test/ , , scratch/ ')).toEqual(['test/', 'scratch/']);
+  });
+});
+
+describe('resolveBoostMap', () => {
+  test('returns defaults when env is unset', () => {
+    expect(resolveBoostMap(undefined)).toEqual(DEFAULT_SOURCE_BOOSTS);
+  });
+
+  test('env override takes precedence over defaults', () => {
+    const merged = resolveBoostMap('originals/:99');
+    expect(merged['originals/']).toBe(99);
+    // Other defaults still present.
+    expect(merged['concepts/']).toBe(DEFAULT_SOURCE_BOOSTS['concepts/']);
+  });
+
+  test('env-only entries are added on top of defaults', () => {
+    const merged = resolveBoostMap('newprefix/:2.5');
+    expect(merged['newprefix/']).toBe(2.5);
+    expect(merged['originals/']).toBe(DEFAULT_SOURCE_BOOSTS['originals/']);
+  });
+});
+
+describe('resolveHardExcludes', () => {
+  test('returns defaults when nothing is overridden', () => {
+    const r = resolveHardExcludes(undefined, undefined, undefined);
+    for (const p of DEFAULT_HARD_EXCLUDES) expect(r).toContain(p);
+  });
+
+  test('caller exclude_slug_prefixes adds to the union', () => {
+    const r = resolveHardExcludes(['scratch/'], undefined, undefined);
+    expect(r).toContain('scratch/');
+    expect(r).toContain('test/'); // default still present
+  });
+
+  test('include_slug_prefixes opts back in', () => {
+    const r = resolveHardExcludes(undefined, ['test/'], undefined);
+    expect(r).not.toContain('test/');
+    // Other defaults still present.
+    expect(r).toContain('archive/');
+  });
+
+  test('env GBRAIN_SEARCH_EXCLUDE adds to the union', () => {
+    const r = resolveHardExcludes(undefined, undefined, 'envdir/');
+    expect(r).toContain('envdir/');
+  });
+
+  test('include subtracts from env-supplied excludes too', () => {
+    const r = resolveHardExcludes(undefined, ['envdir/'], 'envdir/');
+    expect(r).not.toContain('envdir/');
+  });
+});

test/supervisor.test.ts

@@ -328,6 +328,34 @@ describe('MinionSupervisor', () => {
     }, 15_000);
   });
 
+  describe('integration: --max-rss spawn args (v0.21)', () => {
+    it('passes --max-rss 2048 to spawned worker by default', async () => {
+      const outFile = join(tmpdir(), `gbrain-sup-maxrss-${process.pid}-${Date.now()}.txt`);
+      try { unlinkSync(outFile); } catch { /* may not exist */ }
+
+      // Worker logs its argv to OUT_FILE so the test can assert --max-rss 2048
+      // landed there. spawnOnce in supervisor.ts builds:
+      //   ['jobs', 'work', '--concurrency', '1', '--queue', 'default', '--max-rss', '2048']
+      const h = makeHarness('maxrss-default', `printf '%s\\n' "$*" > "$OUT_FILE" ; exit 0`);
+
+      try {
+        const sup = spawnSupervisor(h, {
+          OUT_FILE: outFile,
+          SUP_MAX_CRASHES: '1',
+        });
+
+        await sup.exited;
+
+        expect(existsSync(outFile)).toBe(true);
+        const argv = readFileSync(outFile, 'utf8').trim();
+        expect(argv).toContain('--max-rss 2048');
+      } finally {
+        try { unlinkSync(outFile); } catch { /* noop */ }
+        h.cleanup();
+      }
+    }, 15_000);
+  });
+
   describe('integration: audit file rotation + helper', () => {
     it('computeSupervisorAuditFilename returns supervisor-YYYY-Www.jsonl format', () => {
       const jan15_2026 = new Date(Date.UTC(2026, 0, 15));  // Thu