Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

v0.12.0 - Brain Integrity Suite: typed collision detection, content-hash drift, durable dream workruns (#36)

Sol Aitken84886d1b9fa2
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index add6018a..0b33f282 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.11.0",
+ "version": "0.12.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 6c9a653e..57455fd8 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.11.0",
+ "version": "0.12.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"hooks": "./hooks/hooks.json",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 56d27a66..e64791a2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,77 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.12.0] - 2026-05-26
+
+Brain Integrity Suite: the write path for confirmed preferences is now
+auditable, gated, and survivable. Promotion to `confirmed` stamps a
+content-hash so the doctor can detect silent hand-edits. Every brain
+write goes through `writePreferenceTxn`, a sync chokepoint that wraps
+`fs.openSync(target + '.lock', 'wx')` for cross-process safety and a
+chain of typed-error expectations (`StaleUpdate`, `UnsafeShrink`,
+`SourceLock`, `DuplicateWrite`). Dream pass invocations open a durable
+JSONL workrun so a crash mid-run leaves an inspectable trail. A new
+`brain_review_candidates` MCP tool projects the next dream invocation
+without mutating anything. The destructive-from-confirmed retire gate
+refuses to retire a high-evidence confirmed pref through a single
+weak signal when the operator opts in via config.
+
+### Added
+
+- `src/core/brain/sync-lockfile.ts` (`acquireLockSync`, `scanStaleLocks`)
+ - a sync exclusive-create primitive for the brain write path. Pay
+ Memory keeps its async `proper-lockfile` recipe; the brain ships
+ its own sync variant to avoid migrating every caller signature.
+- `src/core/brain/preference-txn.ts` (`writePreferenceTxn`,
+ `BrainCollisionError`, `BRAIN_COLLISION_KIND`, plus three
+ expectation factories: `expectRevision`, `noUnsafeShrink`,
+ `noDuplicateWriteWithin`). Single chokepoint for every preference
+ write. Auto-stamps `_revision` and (on confirmed promotions)
+ `_content_hash` for callers that opt in.
+- `src/core/brain/content-hash.ts` (`computeContentHash`,
+ `verifyContentHash`). sha256 over the trimmed `(principle, scope)`
+ pair, neutral when no stored hash is available.
+- `_revision: number` and `_content_hash: string` optional fields on
+ `BrainPreference`. Both emitted only when the writer supplies them;
+ pre-v0.12.0 fixtures and the starter bundle stay byte-identical.
+- `src/core/brain/dream-workrun.ts` (`openWorkrun`,
+ `scanDanglingWorkruns`, `WORKRUN_PHASE`). One JSONL workrun at
+ `Brain/log/dream-runs/<run-id>.jsonl` per mutation-path dream
+ invocation; phase markers at `started`, `cluster_complete`,
+ `promote_complete`, `retire_complete`, `finalized` (or
+ `interrupted` on caught crash). Dry-runs skip workrun emission.
+- `DreamRunSummary.gated_retires` carrying `DreamGatedRetireEntry`
+ records for retires the destructive-from-confirmed gate skipped.
+- `DreamGatedRetireEntry` interface exposing `pref_id`, `topic`,
+ `applied_count`, `violated_count`, `threshold`, `attempted_reason`.
+- `shouldGateRetireFromConfirmed` exported pure decision helper.
+- `retire.confirmed_evidence_min_threshold?: number` optional config
+ field on `BrainRetireConfig`. Default-off; when set, the dream
+ pass refuses to retire a confirmed (unpinned) pref whose
+ `applied_count + violated_count` is below the threshold.
+- New `brain_doctor` checks: `content-hash-drift` (warning when the
+ stored hash diverges from the recomputed hash of a confirmed
+ pref's live principle / scope) and `dangling-workrun` (warning
+ for workrun files whose last phase is neither `finalized` nor
+ `interrupted`).
+- `brain_review_candidates` MCP tool, a read-only projection over
+ `dream({ dryRun: true })`. Returns `would_create`,
+ `would_promote`, `would_retire`, `would_supersede`,
+ `clusters_below_threshold`, `gated_retires`. No state mutates.
+- Path helpers `dreamRunsDir(vault)` and `dreamWorkrunPath(vault,
+ runId)` in `src/core/brain/paths.ts`.
+
+### Changed
+
+- `dream()` routes its two `writePreference` call sites through
+ `writePreferenceTxn`. Promotion writes now produce `_content_hash`
+ automatically; refresh writes auto-stamp `_revision` only when the
+ proposed bytes would change (idempotent dream reruns stay
+ byte-identical with the existing `wouldRewritePreference` shortcut).
+- `DreamRunSummary.retired` is filtered to exclude entries that the
+ destructive-from-confirmed gate skipped. The public summary now
+ matches what actually landed on disk.
+
## [0.11.0] - 2026-05-26
Brain-centric vault layout. The agent now owns one top-level
@@ -2884,6 +2955,7 @@ Hermes / Claude Code / Codex / OpenClaw configurations do not change.
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[0.12.0]: https://github.com/itechmeat/open-second-brain/compare/v0.11.0...v0.12.0
[0.10.9]: https://github.com/itechmeat/open-second-brain/compare/v0.10.8...v0.10.9
[0.10.8]: https://github.com/itechmeat/open-second-brain/compare/v0.10.7...v0.10.8
[0.10.7]: https://github.com/itechmeat/open-second-brain/compare/v0.10.6...v0.10.7
diff --git a/README.md b/README.md
index 2dfb1fa8..b2473d74 100644
--- a/README.md
+++ b/README.md
@@ -112,7 +112,7 @@ The capabilities you actually feel day to day:
| 9 | Full-text search across the whole vault | `o2b search "<query>" --property type=decision --property status=open` β€” SQLite + FTS5 plus frontmatter property filters. Faster and more precise than Obsidian's built-in search when you need to grep across thousands of notes. |
| 10 | Pay Memory β€” audit every paid action | When the agent spends money (Solana-Foundation `pay`, third-party APIs) every receipt lands in `Brain/payments/<date>/`. Spending policy, approval gate, daily Telegram report. The agent never holds wallet keys. |
-These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron, cross-project pointers for shared vaults, the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, and an operator dashboard. Browse [`docs/cli-reference.md`](docs/cli-reference.md) for every verb and [`docs/how-it-works.md`](docs/how-it-works.md) for the mental model.
+These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron, cross-project pointers for shared vaults, the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, an operator dashboard, the v0.12.0 Brain Integrity Suite (content-hash drift detection, durable workrun checkpoints, destructive-from-confirmed retire gate, and the `brain_review_candidates` MCP tool that previews what the next dream pass would do without writing anything). Browse [`docs/cli-reference.md`](docs/cli-reference.md) for every verb and [`docs/how-it-works.md`](docs/how-it-works.md) for the mental model.
## CLI
diff --git a/docs/brainstorm/brain-integrity-suite/cli-output/claude.md b/docs/brainstorm/brain-integrity-suite/cli-output/claude.md
new file mode 100644
index 00000000..bd3c5a50
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-suite/cli-output/claude.md
@@ -0,0 +1,35 @@
+### Variant 1: Bottom-up primitives, feature-by-feature wiring
+- **Approach**: Implement the three shared primitives as small standalone modules (`integrity.ts` for hash + revision compute, `workrun.ts` for JSONL phase log, and a thin re-export of the existing `dream({dryRun:true})` path). Each of the five features then ships as its own commit that imports the primitives and modifies the existing call sites directly β€” collision checks added inline at `writePreference`, gates added inline at the dream promote/retire steps, workrun calls scattered through `scanBrain` phases, doctor gets a new check appended, `brain_review_candidates` added next to `toolBrainDream`.
+- **Trade-offs**:
+ - Pro: minimal new abstraction; matches the existing pure-function, `scan β†’ compute β†’ apply` style of the codebase.
+ - Pro: each feature has a tight, isolated blast radius β€” easy to write a failing test per file in `tests/core/brain/<feature>.test.ts`.
+ - Pro: lowest review burden per commit; reviewers see exactly which call site changed.
+ - Con: integrity logic gets sprinkled across `writePreference` and dream's promote/retire β€” the same "compare expected vs actual" idea expressed in two places.
+ - Con: if a sixth gate is added later, both call sites need parallel edits; drift between the two paths is possible.
+- **Complexity**: medium
+- **Risk**: low
+
+### Variant 2: Single transactional write-path chokepoint
+- **Approach**: Refactor `writePreference` into a thin faΓ§ade over a new `writePreferenceTxn(vault, input, expectations, options)` that wraps `proper-lockfile` (mirroring `transitionRequest` from `approval.ts:361`): acquire lock β†’ re-read current frontmatter β†’ run all gates as ordered checks (revision/staleness, content-hash drift observer, shrink, duplicate-window, source-lock) β†’ mutate β†’ `writeFrontmatterAtomic` β†’ release. Dream's promote and retire steps call into the same txn with feature-specific expectations (shrink-gate and retire-from-confirmed gate become two more `expectations` predicates). Workrun stays a separate concern β€” a small context object threaded through dream phases β€” and `brain_review_candidates` is a thin MCP wrapper over the existing `dryRun` path.
+- **Trade-offs**:
+ - Pro: every collision/gate mode lives in one auditable function; one place to add a future gate, one place to read for invariants.
+ - Pro: direct writes via `writePreference` and indirect writes via dream share enforcement guarantees identically β€” no skew possible.
+ - Pro: the lockfile recipe is already proven in-tree; reusing it keeps "no new external deps" trivially true.
+ - Con: requires up-front refactor of `writePreference` and all its callers before tests can be made green; first commit is heavier.
+ - Con: the txn signature grows (an `expectations` object) β€” slightly more API surface to learn than the current `(vault, input, options)`.
+- **Complexity**: medium
+- **Risk**: medium
+
+### Variant 3: Validator-chain pipeline
+- **Approach**: Model every mutation as a `PreferenceIntent` flowing through `validate β†’ check β†’ apply` stages. Each gate (StaleUpdate, UnsafeShrink, SourceLock, DuplicateWrite, ShrinkGate, RetireFromConfirmedGate, drift observer) becomes a pure validator returning `ok | block | warn`. Workrun becomes a pipeline observer that records phase transitions; `brain_review_candidates` is the same pipeline with the `apply` stage swapped for `report`. The dream pass is rewritten to feed intents through the pipeline rather than calling `writePreference` directly.
+- **Trade-offs**:
+ - Pro: maximally extensible; each validator is independently testable as a pure function.
+ - Pro: a single mental model β€” projection, enforcement, and observation all derived from the same chain.
+ - Con: introduces a framework the codebase does not have today; conflicts with the "no premature abstraction" stance and the recent v0.11.0 cleanup that retired pre-1.0 shims.
+ - Con: reviewers must understand the framework before they can review any feature; the diff balloons and the first commit no longer maps cleanly to one user-visible feature.
+ - Con: dream's scan/compute/apply structure has to be inverted into a push-style pipeline β€” bigger blast radius than the task warrants.
+- **Complexity**: large
+- **Risk**: medium-high
+
+### Recommended: Variant 2
+**Rationale**: Variant 2 centralises every collision and gate on the one place the project already needs to harden β€” the preference write path β€” and reuses the proper-lockfile recipe already proven in `transitionRequest`, so it adds no new abstraction the codebase has to learn. Workrun and `brain_review_candidates` stay as small, independent pieces alongside the txn rather than being folded into a unified framework, which keeps the diff legible while still giving the five features a single chokepoint they can share. Variant 1 risks drift between the two write paths and Variant 3 invents a pipeline framework the v0.11.0 line explicitly avoided.
diff --git a/docs/brainstorm/brain-integrity-suite/cli-output/prompt.md b/docs/brainstorm/brain-integrity-suite/cli-output/prompt.md
new file mode 100644
index 00000000..8cbc3ded
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-suite/cli-output/prompt.md
@@ -0,0 +1,111 @@
+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.
+
+# Task
+
+The Open Second Brain ("OSB") codebase needs a **Brain Integrity Suite** that bundles five Brain-side improvements into one PR. All five live inside the same write path (`src/core/brain/preference.ts`, `src/core/brain/dream.ts`, `src/core/brain/policy.ts`, `src/mcp/brain-tools.ts`) and share three primitives that the brainstorm must shape:
+
+1. A revision/hash field on preference frontmatter.
+2. A pre-write check that compares expected-vs-actual revision/length/status.
+3. A read-only "what would dream do" projection over the existing dream pipeline.
+
+The five user-visible features:
+
+## Feature 1: Content-hash drift detection on confirmed preferences
+
+On promotion to `_status: confirmed`, write `_content_hash: sha256(principle + scope)` into frontmatter. On every read of a confirmed preference (`brain_query`, `brain_search`, `dream` rescan), recompute the hash and compare. Mismatch fires a `drift_detected` event into `Brain/log/<today>.md` (plus JSONL sidecar) and surfaces in `brain_doctor` as a warning. Hand-edits remain legal - the goal is **observability**, not enforcement.
+
+## Feature 2: Structured write-collision detection on preference writes
+
+`writePreference` currently goes through `writeFrontmatterAtomic` (no version check). Four collision modes need typed errors instead of silent last-writer-wins:
+- `StaleUpdate` - writer holds an outdated read (compare `_revision` counter or `_last_evidence_at`).
+- `UnsafeShrink` - new principle is < N% of existing principle's length (configurable).
+- `SourceLock` - signal-lock conflict (a preference is currently being mutated by another in-flight call).
+- `DuplicateWrite` - same payload arrives twice from different agents within a short window.
+
+Build on the existing `proper-lockfile`-based `transitionRequest` pattern from `src/core/pay-memory/approval.ts:361` (lock acquire -> re-load inside lock -> verify expected state -> mutate -> writeFrontmatterAtomic -> release).
+
+## Feature 3: Destructive-proof gate on confirmed preferences
+
+Two sub-gates wrapping the dream pass's promotion/retirement logic:
+- **Shrink-gate**: if `dream` is about to overwrite a `_status: confirmed` preference's `principle` with text < N% of the existing length, the write is held back and emits a `requires_explicit_replace` quarantine entry instead.
+- **Retire-from-confirmed gate**: retiring a `_status: confirmed` preference requires either an explicit operator action (already exists via CLI verb), or an evidence count higher than the default retirement threshold (e.g. 3x). Single-signal retirement of a multi-evidence confirmed pref is rejected.
+
+Both gates emit `brain_note` events when they fire (observable, not blocking-silent).
+
+## Feature 4: Durable workrun checkpoints for dream pass
+
+Today `dream(vault, opts)` runs synchronously, returns `DreamRunSummary`. If the process crashes mid-pass, there is no on-disk trace of progress. Add a JSONL workrun file per dream invocation:
+- Path: `Brain/log/dream-runs/<YYYY-MM-DD>-<run-id>.jsonl`
+- One line per phase transition. Phases: `started`, `cluster_complete`, `promote_complete`, `retire_complete`, `finalized | interrupted`.
+- On dream startup, scan `dream-runs/` for incomplete files. If found, emit `recovered: <run_id>` event into the regular log and either resume (when safe) or skip (and add a `dangling_workrun` check to `brain_doctor`).
+
+## Feature 5: `brain_review_candidates` - read-only dream-pass projection
+
+A new MCP tool that surfaces what the next `brain_dream` invocation *would* do, without applying anything. Backed by the existing `dream(vault, { dryRun: true })` path (which already exists but is not exposed as a separate tool). Output shape:
+```json
+{ "would_promote": [], "would_retire": [], "would_supersede": [], "clusters_below_threshold": [] }
+```
+Pure projection over current inbox + active preferences + retired/. No persistent state added.
+
+## Cross-cutting constraints
+
+- **No Python**. TypeScript with Bun runtime.
+- **No new external dependencies** (proper-lockfile is already vendored). sqlite-vec is an optional dep; do not add anything else.
+- **Backward compatibility** is NOT required - the codebase explicitly cleared every pre-1.0 shim in v0.11.0 (no public users yet). New frontmatter fields are additive but readers may treat absent-as-default.
+- **Atomicity**: every write keeps going through `writeFrontmatterAtomic` from `src/core/vault.ts:151`. New collision detection wraps that, doesn't replace it.
+- **All five features must commit on the same feature branch and ship in one PR** (multi-task epic pattern from the feature-release-playbook).
+- **No hardcoded human-language strings** for user-facing text. Error names and event codes stay machine-friendly (`StaleUpdate`, `drift_detected`, etc.).
+- **TDD-first**: every code change must have a failing-first test in `tests/core/brain/`.
+
+# Project context
+
+**Project:** Open Second Brain - second brain for AI agents using Obsidian-compatible Markdown vaults. TypeScript + Bun. v0.11.0.
+
+**Top files in scope (verified via codegraph):**
+
+| Symbol | Location | Shape |
+|---|---|---|
+| `dream` | `src/core/brain/dream.ts:191` | `(vault: string, opts: DreamOptions = {}): DreamRunSummary` (sync). Already has `dryRun?: boolean` field. |
+| `DreamOptions` | `src/core/brain/dream.ts:134` | Interface; has `dryRun`, `agentName`, etc. |
+| `DreamRunSummary` | `src/core/brain/dream.ts:96` | Final summary; has `confirmed`, `retired`, `new_unconfirmed` arrays. |
+| `scanBrain` | `src/core/brain/dream.ts:574` | One-pass scan of all topics; no checkpoint emission today. |
+| `writePreference` | `src/core/brain/preference.ts:200` | `(vault, input, options): WritePreferenceResult`, sync. Validates fields and calls `writeFrontmatterAtomic`. |
+| `preferenceFrontmatter` | `src/core/brain/preference.ts:293` | Builds the FrontmatterMap. Uses `_`-prefix convention for derived fields. |
+| `writeFrontmatterAtomic` | `src/core/vault.ts:151` | Atomic file write via temp+rename. The bottom primitive. |
+| `transitionRequest` | `src/core/pay-memory/approval.ts:361` | Reference lockfile pattern - `lockfile.lock(target, {retries: {retries:30, factor:1.2, minTimeout:30, maxTimeout:500}, stale:10_000})`, re-load inside lock, mutate, release. |
+| `toolBrain*` | `src/mcp/brain-tools.ts` | MCP tool handlers: `(ctx, args) => Promise<Record<string,unknown>>`. Patterns: `toolBrainDream:231`, `toolBrainQuery:479`, `toolBrainNote:340`, `toolBrainDoctor:570`. |
+| `brain_note` writer | called via `noteAppend` into `Brain/log/<today>.md` + JSONL sidecar | Existing event-recording surface. |
+
+**Preference frontmatter convention (verified):** Identity fields stay unprefixed (`kind`, `id`, `created_at`, `unconfirmed_until`, `topic`, `principle`, `scope`, `tags`, `aliases`, `supersedes`, `pinned`). Derived/dream-owned fields use `_` prefix (`_status`, `_confirmed_at`, `_evidenced_by`, `_applied_count`, `_violated_count`, `_last_evidence_at`, `_confidence`, `_confidence_value`, `_lifecycle`). New fields from this suite (`_content_hash`, `_revision`) follow the `_` convention.
+
+**Test layout:** `tests/core/brain/<feature>.test.ts` - one file per feature; `bun test` is the harness.
+
+**Conventions from CHANGELOG (v0.10.x - v0.11.0):**
+- Pure functions where possible; the dream pipeline is heavy on `scan -> compute -> apply` separation.
+- Numeric thresholds configurable via `Brain/_brain.yaml` and surfaced through `loadBrainConfig`.
+- Every observable event goes through the log writer (Markdown + JSONL sidecar).
+- `brain_doctor` is the operator's invariant check; new checks plug in there.
+
+**Constraints from playbook:**
+- One PR per CHANGELOG version (v0.12.0).
+- Conventional commits, atomic per feature.
+- Mermaid diagrams in PR description must render server-side.
+
+# Required output format
+
+Produce exactly 3 distinct architectural variants. For each variant:
+
+## Variant N: <short name>
+
+- **Approach**: 2-3 sentences describing the variant.
+- **Trade-offs**: bullet list of pros and cons.
+- **Complexity**: small | medium | large
+- **Risk**: low | medium | high
+
+After the three variants, add exactly one recommendation:
+
+## Recommended: Variant N
+
+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.
+
+Output nothing outside of these sections.
diff --git a/docs/brainstorm/brain-integrity-suite/design.md b/docs/brainstorm/brain-integrity-suite/design.md
new file mode 100644
index 00000000..30de5459
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-suite/design.md
@@ -0,0 +1,91 @@
+# Brain Integrity Suite - design
+
+**Status:** draft
+**Author:** orchestrator (via feature-release-playbook)
+**Audience:** implementation
+
+## Problem statement
+
+Open Second Brain's preference write path has three structural gaps. First, confirmed preferences can be silently mutated outside the dream-pass promotion/retirement flow (hand edits, write races, errant agents) with no observable trace. Second, the existing `writePreference` atomic write prevents torn writes but does not prevent stale-update, unsafe-shrink, source-lock, or duplicate-write collisions - the last writer wins silently. Third, the dream pass runs as a single synchronous pipeline with no on-disk progress trace, and there is no read-only way for an operator (or another agent) to inspect what `brain_dream` would do before invoking it.
+
+This release bundles five features that close all three gaps inside one cohesive PR.
+
+## Scope
+
+- **F1: Content-hash drift detection on confirmed preferences.** On promotion, write `_content_hash: sha256(principle + scope)` into frontmatter. Reads recompute and compare; mismatch logs a `drift_detected` event and surfaces in `brain_doctor`.
+- **F2: Structured write-collision detection.** Four typed collision modes (`StaleUpdate`, `UnsafeShrink`, `SourceLock`, `DuplicateWrite`) wrapping the write path via a new `writePreferenceTxn` chokepoint that builds on the `proper-lockfile` pattern already proven in `src/core/pay-memory/approval.ts:361`.
+- **F3: Destructive-proof gate on confirmed preferences.** Two sub-gates inside the dream pass: shrink-gate (new principle < threshold% of existing length quarantines the candidate); retire-from-confirmed gate (single-signal retirement of a multi-evidence confirmed preference is rejected without operator action or evidence above a higher threshold).
+- **F4: Durable workrun checkpoints for dream pass.** Per-invocation JSONL workrun at `Brain/log/dream-runs/<YYYY-MM-DD>-<run-id>.jsonl` with one line per phase transition. Recovery scan on startup; `brain_doctor` check for dangling files.
+- **F5: `brain_review_candidates` MCP tool.** Read-only projection over `dream(vault, { dryRun: true })`, exposed as a new MCP tool returning `{ would_promote, would_retire, would_supersede, clusters_below_threshold }`.
+
+## Out of scope
+
+- Per-preference edit-history audit trail (`t_9f452292`) - separate sibling task, not in this PR.
+- Cross-vault locking or multi-vault coordination - Pay Memory's lockfile is single-vault.
+- Schema migration for existing v0.11.0 preferences - additive fields with absent-as-default reader semantics. No `o2b brain migrate-*` verb.
+- Changes to `dedup-hash.ts` (signal/import dedup) - different concern, untouched.
+
+## Chosen approach
+
+**Variant 2: Single transactional write-path chokepoint.**
+
+Refactor `writePreference` into a thin faΓ§ade over a new `writePreferenceTxn(vault, input, expectations, options)` that wraps `proper-lockfile`: acquire lock on the preference file path, re-read current frontmatter inside the lock, run an ordered chain of `expectations` checks (revision, content-hash drift observer, shrink, duplicate-window, source-lock), mutate via `writeFrontmatterAtomic`, release. Dream's promotion and retirement paths call into the same txn with feature-specific expectations (shrink-gate and retire-from-confirmed gate are two predicates plugged into the same expectations chain).
+
+`brain_review_candidates` is a thin MCP wrapper over the already-existing `dream(vault, { dryRun: true })` path. Workrun checkpoints live in a separate small context object threaded through dream phases - they observe transitions but do not own the write semantics.
+
+Variant 1 (bottom-up primitives) was rejected because integrity logic would drift across `writePreference` and dream's promote/retire call sites - two parallel implementations of the same idea. Variant 3 (validator-chain pipeline) was rejected because it invents a framework the codebase explicitly avoids (v0.11.0 removed pre-1.0 shims; the project is the opposite of framework-heavy).
+
+## Design decisions
+
+- **One chokepoint, multiple expectations.** `writePreferenceTxn` is the single function that writes to a preference file. Direct writes from CLI/MCP and indirect writes from dream both go through it; the expectations parameter carries feature-specific predicates (shrink-gate, retire-gate, revision check). This is the SOLID open/closed principle: new gates plug in as expectations without modifying the txn body.
+- **Lockfile recipe verbatim from Pay Memory.** Same `retries: { retries: 30, factor: 1.2, minTimeout: 30, maxTimeout: 500 }, stale: 10_000, realpath: false` parameters as `transitionRequest:361`. Single source of truth for the lock semantics; if Pay Memory ever tunes them, the brain mirrors.
+- **Hash is opt-in via status.** `_content_hash` is written only when promoting to `confirmed`. Unconfirmed and quarantine preferences do not get the field - they are mutable by design.
+- **Drift detection is observation, not enforcement.** A mismatch logs a `drift_detected` event into `Brain/log/<today>.md` (and the JSONL sidecar) and surfaces in `brain_doctor` as a warning. The read still returns the live content; hand-edits remain legal. The operator chooses how to react.
+- **Revision counter is monotonic.** `_revision: <integer>` starts at 0 on creation, increments on every txn write. `StaleUpdate` fires when the writer's `expected_revision` does not match the current. Absent field reads as 0 for backward compatibility.
+- **Shrink threshold is config-driven, not hardcoded.** New field under `Brain/_brain.yaml`'s existing `confidence` block: `confidence.unsafe_shrink_min_ratio` (default 0.5). Anything below half of the existing principle length triggers UnsafeShrink.
+- **Workrun phases are deterministic.** Five phase markers in fixed order: `started`, `cluster_complete`, `promote_complete`, `retire_complete`, `finalized`. A sixth marker `interrupted` may replace `finalized` on caught crash. Recovery on dream startup is non-resuming: if a workrun is incomplete, log `recovered` (informational), do not auto-resume - the next dream invocation processes the inbox fresh. `brain_doctor` surfaces dangling files as a warning.
+- **`brain_review_candidates` is pure projection.** The MCP handler calls `dream(vault, { dryRun: true })` and returns its plan. No new persistent state, no log events, no inbox mutations. Same signature as other read-only tools: `(ctx, args) => Promise<Record<string, unknown>>`.
+- **Error class hierarchy.** A new `BrainCollisionError extends Error` with a `kind: 'StaleUpdate' | 'UnsafeShrink' | 'SourceLock' | 'DuplicateWrite'` discriminant. Error names are machine-friendly identifiers; no human-language strings hardcoded.
+- **Sync lockfile primitive instead of `proper-lockfile`.** The consultant's Variant 2 recommendation cited the Pay Memory `proper-lockfile` recipe, but Pay Memory is async while the entire brain write path is sync (`writePreference`, `dream`, `moveToRetired`, `writeFrontmatterAtomic`, all callers). `proper-lockfile` v4 has no `lockSync`. Migrating the brain to async would touch 30+ caller files (CLI verbs, MCP handlers, internal call sites) for a feature whose only async-only ingredient is one lock acquire. The right cost is the opposite: write a tiny sync primitive in `src/core/brain/sync-lockfile.ts` that uses `fs.openSync(target + '.lock', 'wx')` for atomic exclusive create. Single-attempt semantics: `EEXIST` raises `BrainCollisionError` with `kind: 'SourceLock'`, no retry loop. Real-world contention in OSB is rare (single operator, single MCP server, dream runs from cron) so the retry/backoff machinery of `proper-lockfile` would be dead code. Pay Memory keeps its async recipe untouched - the two subsystems have different concurrency profiles.
+
+## File changes
+
+**New files:**
+- `src/core/brain/preference-txn.ts` - the `writePreferenceTxn` chokepoint, `BrainCollisionError` class, expectations types.
+- `src/core/brain/content-hash.ts` - hash computation helper for `principle + scope`.
+- `src/core/brain/dream-workrun.ts` - JSONL workrun writer + reader + recovery scan.
+- `src/core/brain/review-candidates.ts` - core builder behind `brain_review_candidates` (calls `dream` in dry-run mode and projects the summary).
+- `tests/core/brain/preference-txn.test.ts` - txn behaviour, lock semantics.
+- `tests/core/brain/content-hash.test.ts` - hash compute + drift detection.
+- `tests/core/brain/preference-collision.test.ts` - StaleUpdate, UnsafeShrink, SourceLock, DuplicateWrite.
+- `tests/core/brain/dream-destructive-gate.test.ts` - shrink-gate + retire-from-confirmed gate.
+- `tests/core/brain/dream-workrun.test.ts` - workrun emission, recovery scan, dangling check.
+- `tests/core/brain/review-candidates.test.ts` - projection shape, dry-run isolation.
+- `tests/mcp/brain-review-candidates.test.ts` - MCP tool wiring.
+
+**Modified files:**
+- `src/core/brain/preference.ts` - `writePreference` delegates to `writePreferenceTxn` with empty expectations.
+- `src/core/brain/types.ts` - new optional fields on `BrainPreference` (`_revision`, `_content_hash`).
+- `src/core/brain/dream.ts` - workrun emission at phase boundaries; promotion/retirement calls go through txn with gate expectations.
+- `src/core/brain/policy.ts` - new config fields `confidence.unsafe_shrink_min_ratio` and `retire.confirmed_evidence_multiplier`.
+- `src/core/brain/doctor.ts` - new checks for drift, dangling workrun.
+- `src/core/brain/query.ts`, `src/core/brain/search.ts` (if separate) - drift verification on read.
+- `src/mcp/brain-tools.ts` - new `toolBrainReviewCandidates` handler.
+- `src/mcp/tools.ts` - tool registration.
+- `src/mcp/instructions.ts` - tool description.
+- `CHANGELOG.md` - v0.12.0 entry.
+- `README.md` - updated MCP tool table.
+- `package.json` - version bump to 0.12.0.
+- `scripts/sync-version.ts` and friends pick up the new version automatically.
+
+Estimated diff: ~55-70 files including tests.
+
+## Risks and open questions
+
+- **Lock contention on hot preferences.** Pay Memory's lockfile config (max 30 retries, ~500ms total) is sized for human-operator pace. The dream pass may write many preferences in rapid succession in one run. Verify in implementation that lock acquire latency stays bounded; consider a single in-process mutex sufficient for the same-run case rather than serialising through the filesystem lockfile for each preference.
+- **Lock cleanup on crash.** A sync lockfile leaves a `.lock` file on disk if the process aborts between acquire and release. Mitigation: a `process.on('exit', ...)` cleanup hook unlinks every still-held lock during normal exit; for hard crashes (`SIGKILL`, OOM), the next acquire on the same target sees EEXIST and fails with `SourceLock`. The doctor check surfaces stale `.lock` files via `scanStaleLocks(vault)`. Operators can rm them by hand. Pay Memory's `proper-lockfile` has the same class of issue (its `stale: 10_000` timer is for that case); we accept the same hazard with a simpler recovery path.
+- **Sync lockfile primitive scope.** New file `src/core/brain/sync-lockfile.ts` (~50 lines). Tests in `tests/core/brain/sync-lockfile.test.ts`. Doctor integration in `src/core/brain/doctor.ts`. Total deltas on the brain write surface: `preference.ts`, `dream.ts`, the new `preference-txn.ts` wrapping both. No caller signatures change.
+- **Hash stability across encoding variations.** `sha256(principle + scope)` is sensitive to leading/trailing whitespace and Unicode normalization. Decision: hash the trimmed `principle.trim() + "\n" + (scope ?? "").trim()`, no NFD/NFC normalization (the codebase already does not normalize elsewhere). Document in `content-hash.ts` so a future refactor does not silently invalidate every existing hash.
+- **Dream dry-run + workrun interaction.** Dry-run must not write a workrun file - the workrun is part of the durable side-effect surface. Implementation: skip workrun emission when `opts.dryRun === true`.
+- **Backward compat for existing v0.11.0 vaults.** All new frontmatter fields are optional; readers fall back to defaults (`_revision` absent reads as 0; missing `_content_hash` on confirmed pref reads as "never hashed yet, hash on next write"). No migration verb.
+- **Test data isolation.** Tests need disposable vaults under `os.tmpdir()` per the existing tests/helpers/ pattern; verify `proper-lockfile` cleans up on process exit during a `bun test` interrupt.
diff --git a/docs/brainstorm/brain-integrity-suite/plan.md b/docs/brainstorm/brain-integrity-suite/plan.md
new file mode 100644
index 00000000..fdc7cf42
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-suite/plan.md
@@ -0,0 +1,79 @@
+# Brain Integrity Suite - implementation plan
+
+Seven atomic tasks, all TDD-driven. Each task = failing test first, see fail, minimal code, see green, refactor, atomic conventional commit on `feat/brain-integrity-suite`.
+
+## Tasks
+
+### Task 1: Sync lockfile primitive + `writePreferenceTxn` chokepoint + expectations chain
+
+- **Files**:
+ - new `src/core/brain/sync-lockfile.ts` - `acquireLockSync(target): LockHandle`, `LockHandle.release()`, `scanStaleLocks(vault): string[]`, process-exit cleanup hook for held locks. Single-attempt exclusive create via `fs.openSync(target + '.lock', 'wx')`.
+ - new `src/core/brain/preference-txn.ts` - `writePreferenceTxn(vault, input, expectations, options): WritePreferenceResult` (sync), `BrainCollisionError extends Error` with `kind` discriminant, `WritePreferenceExpectations` type.
+ - modified `src/core/brain/preference.ts` - `writePreference` delegates to `writePreferenceTxn` with an empty expectations array; public signature unchanged.
+ - new `tests/core/brain/sync-lockfile.test.ts` - acquire success, EEXIST collision, release, exit-cleanup.
+ - new `tests/core/brain/preference-txn.test.ts` - txn flow (lock acquire, re-read, expectations chain, mutate, lock release), expectations chain ordering, error class kind discriminant.
+- **Acceptance**: existing `writePreference` tests stay green (no caller signature changes); txn path passes the full lock-acquire / re-read / mutate flow; `BrainCollisionError` exposes `.kind` field with one of four string values; the sync lockfile creates the `.lock` file then removes it on release; `bun test` clean.
+- **Depends on**: none (foundation).
+
+### Task 2: `_revision` counter + `_content_hash` frontmatter fields
+
+- **Files**:
+ - modified `src/core/brain/types.ts` - add optional `_revision: number`, `_content_hash: string` to `BrainPreference`.
+ - modified `src/core/brain/preference.ts` - `WritePreferenceInput` gains optional `revision`, `content_hash`; `preferenceFrontmatter` emits `_revision` (defaults to 0) and `_content_hash` (only when status is `confirmed`).
+ - new `src/core/brain/content-hash.ts` - `computeContentHash(principle: string, scope?: string): string`.
+ - new `tests/core/brain/content-hash.test.ts` - hash determinism, whitespace handling, scope optional.
+ - modified `tests/core/brain/preference.test.ts` or new test file - frontmatter shape with new fields.
+- **Acceptance**: `_revision` defaults to 0, increments on each write; `_content_hash` present only on `_status: confirmed`; hash is deterministic for same `(principle, scope)`.
+- **Depends on**: Task 1.
+
+### Task 3: Collision-detection expectations (StaleUpdate, UnsafeShrink, SourceLock, DuplicateWrite)
+
+- **Files**:
+ - modified `src/core/brain/preference-txn.ts` - four expectations: `expectRevision(n)`, `noUnsafeShrink(minRatio)`, `sourceLockGuard`, `noDuplicateWrite(window)`.
+ - modified `src/core/brain/policy.ts` - config fields `confidence.unsafe_shrink_min_ratio` (default 0.5) and `retire.confirmed_evidence_multiplier` (default 3).
+ - new `tests/core/brain/preference-collision.test.ts` - one describe-block per collision kind, each with red-then-green case.
+- **Acceptance**: each collision mode raises `BrainCollisionError` with correct `kind`; lock acquisition timeout maps to `SourceLock`; config defaults loadable via `loadBrainConfig`.
+- **Depends on**: Task 1, Task 2.
+
+### Task 4: Drift detection on confirmed-preference reads
+
+- **Files**:
+ - modified `src/core/brain/content-hash.ts` - `verifyContentHash(pref): { ok: boolean; observed?: string; expected?: string }`.
+ - modified `src/core/brain/query.ts` (or wherever `brain_query` reads preferences) - on `_status: confirmed` reads, call `verifyContentHash`, emit `drift_detected` event via existing log writer when mismatch.
+ - modified `src/core/brain/doctor.ts` - new `BrainDoctorCheck` for drift summary.
+ - new event code constant `BRAIN_EVENT.driftDetected` in the same place other event codes live.
+ - new `tests/core/brain/content-hash-drift.test.ts` - mutate principle on disk, read, assert event emitted.
+- **Acceptance**: hand-editing a confirmed preference's `principle` triggers exactly one `drift_detected` event per read (not per byte); `brain_doctor` surfaces a count of drifted preferences; mismatch does not block the read.
+- **Depends on**: Task 2.
+
+### Task 5: Destructive-proof gates in dream pass
+
+- **Files**:
+ - modified `src/core/brain/dream.ts` - promotion path passes `noUnsafeShrink` expectation when target is `_status: confirmed`; retirement path passes `requireEvidenceCountAbove(threshold)` when source is `_status: confirmed`.
+ - modified `src/core/brain/types.ts` - new `DreamQuarantinedEntry` reason codes `unsafe_shrink`, `retire_evidence_below_threshold`.
+ - new `tests/core/brain/dream-destructive-gate.test.ts` - feed dream a single-signal retirement against multi-evidence confirmed pref; assert quarantine entry returned, pref unchanged on disk.
+- **Acceptance**: dream's `DreamRunSummary.retired` does not include a confirmed pref when evidence count is below multiplier; `quarantined` array carries the rejected attempt with the relevant `failed_gates` code; existing dream tests stay green.
+- **Depends on**: Task 3.
+
+### Task 6: Durable workrun checkpoints for dream pass
+
+- **Files**:
+ - new `src/core/brain/dream-workrun.ts` - `openWorkrun(vault, runId): WorkrunHandle`, `WorkrunHandle.checkpoint(phase)`, `WorkrunHandle.finalize()`, `WorkrunHandle.interrupt()`, `scanDanglingWorkruns(vault): string[]`.
+ - modified `src/core/brain/dream.ts` - phase markers at the four transition points; skipped when `opts.dryRun === true`.
+ - modified `src/core/brain/paths.ts` - `dreamRunsDir(vault)`, `dreamWorkrunPath(vault, runId)` path helpers.
+ - modified `src/core/brain/doctor.ts` - check `scanDanglingWorkruns` and surface as warning.
+ - new `tests/core/brain/dream-workrun.test.ts` - emission ordering, recovery scan, dry-run skip.
+- **Acceptance**: a full dream pass writes exactly one workrun file with five JSONL lines (`started`, `cluster_complete`, `promote_complete`, `retire_complete`, `finalized`); a crashed run (test simulates) leaves a workrun without `finalized` and is picked up by the doctor check.
+- **Depends on**: none structurally, but Task 5 should land first so dream's promote/retire phases are stable.
+
+### Task 7: `brain_review_candidates` MCP tool
+
+- **Files**:
+ - new `src/core/brain/review-candidates.ts` - `buildReviewCandidates(vault): ReviewCandidatesReport`, internally calls `dream(vault, { dryRun: true })` and projects.
+ - modified `src/mcp/brain-tools.ts` - `toolBrainReviewCandidates(ctx, args)` handler matching the existing tool signature.
+ - modified `src/mcp/tools.ts` - tool registration entry.
+ - modified `src/mcp/instructions.ts` - tool description for the agent-facing surface.
+ - new `tests/core/brain/review-candidates.test.ts` - shape and dry-run isolation (no files mutated).
+ - new `tests/mcp/brain-review-candidates.test.ts` - MCP tool wiring + arg shape.
+- **Acceptance**: the tool returns `{ would_promote, would_retire, would_supersede, clusters_below_threshold }`; invoking it twice in a row produces the same result without writing any new files; the tool is discoverable through the MCP server's tool list.
+- **Depends on**: Task 6 (so the workrun does not fire on dry-run is exercised together).
diff --git a/docs/brainstorm/brain-integrity-suite/pr-body.md b/docs/brainstorm/brain-integrity-suite/pr-body.md
new file mode 100644
index 00000000..13fcf1e9
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-suite/pr-body.md
@@ -0,0 +1,69 @@
+## Summary
+
+Adds the **Brain Integrity Suite** to the Open Second Brain preference write path: every confirmed preference now carries a content hash, every dream write goes through a typed-collision chokepoint, and every dream invocation leaves a durable on-disk workrun. The destructive-from-confirmed retire gate and the read-only `brain_review_candidates` MCP tool round out the bundle. Eight atomic features, one cohesive PR.
+
+## Why this matters
+
+```mermaid
+flowchart LR
+ A[Agent or operator<br/>edits a preference] --> B{Where does the write land?}
+ B -->|pre-v0.12.0| C[writeFrontmatterAtomic]
+ C --> D[On-disk file<br/>no audit, no gates]
+ D --> E[Silent drift / race / shrink]
+
+ B -->|v0.12.0| F[writePreferenceTxn]
+ F --> G[Lock acquire<br/>sync .lock file]
+ G --> H[Expectations chain<br/>StaleUpdate / UnsafeShrink / DuplicateWrite]
+ H --> I[Smart defaults<br/>_revision bump + _content_hash on confirmed]
+ I --> J[writeFrontmatterAtomic]
+ J --> K[Durable workrun JSONL<br/>+ doctor surfaces]
+ K --> L[Inspectable history]
+```
+
+The pre-v0.12.0 write path could not tell a legitimate edit apart from a write race or a silent shrink; the v0.12.0 path surfaces every category as a typed error or a doctor warning.
+
+## Concrete benefits
+
+- **Drift becomes observable.** Hand-edits to a confirmed preference produce a `content-hash-drift` warning in `brain_doctor` instead of going silent.
+- **Crash forensics.** A dream pass killed mid-execution leaves a `dream-runs/<run-id>.jsonl` with phases up to the killpoint. The next pass scans for dangling workruns and surfaces them.
+- **Destructive-proof retires.** When `retire.confirmed_evidence_min_threshold` is set, the dream pass refuses to retire a confirmed (unpinned) preference whose accumulated evidence is below the floor. Skipped retires surface in `DreamRunSummary.gated_retires`.
+- **Pre-flight visibility.** `brain_review_candidates` lets an agent or operator ask "what would the next dream pass do?" without touching disk.
+- **Single chokepoint for future gates.** New collision modes plug into `writePreferenceTxn` as expectation functions; no parallel patches across `preference.ts` and `dream.ts`.
+
+## What ships
+
+| Module | Role |
+|---|---|
+| `src/core/brain/sync-lockfile.ts` | Single-attempt sync exclusive-create primitive. EEXIST -> `Error.code = 'ELOCKED'`. |
+| `src/core/brain/preference-txn.ts` | `writePreferenceTxn` chokepoint, `BrainCollisionError` with four typed `kind` discriminants, three expectation factories. |
+| `src/core/brain/content-hash.ts` | `computeContentHash` and `verifyContentHash` over the canonical trimmed `(principle, scope)` pair. |
+| `src/core/brain/dream-workrun.ts` | JSONL workrun writer + scanner. Recovery is non-resuming; the doctor surfaces dangling files. |
+| `src/core/brain/review-candidates.ts` | Read-only projection over `dream({ dryRun: true })`. |
+| `src/core/brain/dream.ts` | Promotion + refresh writes routed through the txn; destructive-from-confirmed retire gate wired into the retires loop. |
+| `src/core/brain/doctor.ts` | New checks: `content-hash-drift` and `dangling-workrun`. |
+| `src/mcp/brain-tools.ts` + `instructions.ts` | New MCP tool `brain_review_candidates`. |
+
+## Test plan
+
+- [x] `bun test` - 2379 pass / 0 fail / 5937 expects across the full suite (including 64 new tests across 11 new test files).
+- [x] `bun run typecheck` - clean.
+- [x] `bun run sync-version:check` - canonical 0.12.0 across seven manifests.
+- [x] Integration coverage: a fresh dream pass that promotes an unconfirmed pref to confirmed writes `_content_hash` matching the canonical hash on disk (`tests/core/brain/dream-content-hash-promotion.test.ts`).
+- [x] Idempotency invariant: a second dream pass on the same vault state produces byte-identical preference files (`tests/core/brain.dream.test.ts:512`).
+- [x] Starter bundle no-op: `dream` on the curated starter at a fixed `--now` returns `changed: false` (`tests/core/brain/starter.test.ts:158`).
+- [x] Doctor drift: writing a confirmed pref with a stale `_content_hash` surfaces exactly one `content-hash-drift` warning (`tests/core/brain/doctor-drift.test.ts`).
+- [x] Workrun lifecycle: phases recorded in order, dry-run skips emission, `scanDanglingWorkruns` returns paths of unfinalised files (`tests/core/brain/dream-workrun.test.ts`).
+- [x] Destructive-gate pure decision: nine branches of `shouldGateRetireFromConfirmed` covered (`tests/core/brain/dream-destructive-gate.test.ts`).
+- [x] MCP wiring: `brain_review_candidates` registered in `BRAIN_TOOLS`, returns six fields all empty on a fresh vault (`tests/mcp/brain-review-candidates.test.ts`). Tool count 31 -> 32.
+
+## Design and decision trail
+
+- `docs/brainstorm/brain-integrity-suite/design.md` - the chosen approach and rejected alternatives.
+- `docs/brainstorm/brain-integrity-suite/plan.md` - the per-task implementation plan.
+- `docs/brainstorm/brain-integrity-suite/variants.md` - audit trail of the three architectural variants the consultant produced.
+
+## Notes
+
+- Default-off rollout for the destructive-from-confirmed gate (`retire.confirmed_evidence_min_threshold`) keeps every pre-v0.12.0 dream behaviour byte-identical until the operator opts in via `Brain/_brain.yaml`.
+- `proper-lockfile` remains a runtime dep for Pay Memory; the brain write path uses its own sync primitive to avoid migrating every caller signature to async. Decision rationale captured in the design doc.
+- The `drift-detected` log event kind was planned but is not emitted in v0.12.0; the doctor warning is the surface. The enum entry is intentionally absent rather than promised-and-unmet.
diff --git a/docs/brainstorm/brain-integrity-suite/variants.md b/docs/brainstorm/brain-integrity-suite/variants.md
new file mode 100644
index 00000000..02663721
--- /dev/null
+++ b/docs/brainstorm/brain-integrity-suite/variants.md
@@ -0,0 +1,59 @@
+# Brain Integrity Suite - brainstorm audit trail
+
+This file records the architectural variants the consultant produced for the Brain Integrity Suite and the orchestrator's final rationale. It is intentionally verbose - future readers should see the options that lost and why.
+
+The prompt fed to the consultant is at `cli-output/prompt.md`. The raw consultant transcript is at `cli-output/claude.md`.
+
+## Consultant: Claude Code
+
+Invocation: `claude -p "$(cat cli-output/prompt.md)" 2>&1 | tee cli-output/claude.md`
+
+### Variant 1: Bottom-up primitives, feature-by-feature wiring
+
+- **Approach**: Implement the three shared primitives as small standalone modules (`integrity.ts` for hash + revision compute, `workrun.ts` for JSONL phase log, and a thin re-export of the existing `dream({dryRun:true})` path). Each of the five features then ships as its own commit that imports the primitives and modifies the existing call sites directly - collision checks added inline at `writePreference`, gates added inline at the dream promote/retire steps, workrun calls scattered through `scanBrain` phases, doctor gets a new check appended, `brain_review_candidates` added next to `toolBrainDream`.
+- **Trade-offs**:
+ - Pro: minimal new abstraction; matches the existing pure-function, `scan to compute to apply` style of the codebase.
+ - Pro: each feature has a tight, isolated blast radius - easy to write a failing test per file in `tests/core/brain/<feature>.test.ts`.
+ - Pro: lowest review burden per commit; reviewers see exactly which call site changed.
+ - Con: integrity logic gets sprinkled across `writePreference` and dream's promote/retire - the same "compare expected vs actual" idea expressed in two places.
+ - Con: if a sixth gate is added later, both call sites need parallel edits; drift between the two paths is possible.
+- **Complexity**: medium
+- **Risk**: low
+
+### Variant 2: Single transactional write-path chokepoint
+
+- **Approach**: Refactor `writePreference` into a thin faΓ§ade over a new `writePreferenceTxn(vault, input, expectations, options)` that wraps `proper-lockfile` (mirroring `transitionRequest` from `approval.ts:361`): acquire lock then re-read current frontmatter then run all gates as ordered checks (revision/staleness, content-hash drift observer, shrink, duplicate-window, source-lock) then mutate then `writeFrontmatterAtomic` then release. Dream's promote and retire steps call into the same txn with feature-specific expectations (shrink-gate and retire-from-confirmed gate become two more `expectations` predicates). Workrun stays a separate concern - a small context object threaded through dream phases - and `brain_review_candidates` is a thin MCP wrapper over the existing `dryRun` path.
+- **Trade-offs**:
+ - Pro: every collision/gate mode lives in one auditable function; one place to add a future gate, one place to read for invariants.
+ - Pro: direct writes via `writePreference` and indirect writes via dream share enforcement guarantees identically - no skew possible.
+ - Pro: the lockfile recipe is already proven in-tree; reusing it keeps "no new external deps" trivially true.
+ - Con: requires up-front refactor of `writePreference` and all its callers before tests can be made green; first commit is heavier.
+ - Con: the txn signature grows (an `expectations` object) - slightly more API surface to learn than the current `(vault, input, options)`.
+- **Complexity**: medium
+- **Risk**: medium
+
+### Variant 3: Validator-chain pipeline
+
+- **Approach**: Model every mutation as a `PreferenceIntent` flowing through `validate to check to apply` stages. Each gate (StaleUpdate, UnsafeShrink, SourceLock, DuplicateWrite, ShrinkGate, RetireFromConfirmedGate, drift observer) becomes a pure validator returning `ok | block | warn`. Workrun becomes a pipeline observer that records phase transitions; `brain_review_candidates` is the same pipeline with the `apply` stage swapped for `report`. The dream pass is rewritten to feed intents through the pipeline rather than calling `writePreference` directly.
+- **Trade-offs**:
+ - Pro: maximally extensible; each validator is independently testable as a pure function.
+ - Pro: a single mental model - projection, enforcement, and observation all derived from the same chain.
+ - Con: introduces a framework the codebase does not have today; conflicts with the "no premature abstraction" stance and the recent v0.11.0 cleanup that retired pre-1.0 shims.
+ - Con: reviewers must understand the framework before they can review any feature; the diff balloons and the first commit no longer maps cleanly to one user-visible feature.
+ - Con: dream's scan/compute/apply structure has to be inverted into a push-style pipeline - bigger blast radius than the task warrants.
+- **Complexity**: large
+- **Risk**: medium-high
+
+### Consultant recommendation: Variant 2
+
+> Variant 2 centralises every collision and gate on the one place the project already needs to harden - the preference write path - and reuses the proper-lockfile recipe already proven in `transitionRequest`, so it adds no new abstraction the codebase has to learn. Workrun and `brain_review_candidates` stay as small, independent pieces alongside the txn rather than being folded into a unified framework, which keeps the diff legible while still giving the five features a single chokepoint they can share. Variant 1 risks drift between the two write paths and Variant 3 invents a pipeline framework the v0.11.0 line explicitly avoided.
+
+## Orchestrator decision: Variant 2 (agree with consultant)
+
+The consultant's rationale matches the project context. Reinforcing reasons specific to OSB:
+
+1. **DRY across two write paths.** CLI/MCP writes (via `writePreference`) and dream-internal writes (via `dream.ts`'s promotion/retirement) are today two parallel paths through the same primitive (`writeFrontmatterAtomic`). Variant 1 would entrench the parallelism; Variant 2 collapses both into one chokepoint. The project's own CHANGELOG entry for v0.11.0 explicitly removed dual-shape parsers and lift-only overlays - the spirit of "one path, no overlay" pushes toward Variant 2.
+2. **`proper-lockfile` is already a runtime dep.** Adding Variant 2's lockfile gate costs zero new dependencies. The Pay Memory reference implementation (`approval.ts:361`) is a 30-line recipe to copy.
+3. **Workrun and review-candidates do not benefit from the txn abstraction.** They are pure observers / pure projections. Variant 3's "everything through the validator chain" would force them into the wrong shape.
+
+Variant 3 is explicitly rejected on cultural grounds: this project removed framework-y abstractions in v0.11.0; reintroducing one for five features that fit naturally as a chokepoint plus two helpers is the opposite direction.
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 8af74050..ae45a58b 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "0.11.0",
+ "version": "0.12.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index c6c0d2a9..7caa9ac7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.11.0",
+ "version": "0.12.0",
"type": "module",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
diff --git a/plugin.yaml b/plugin.yaml
index c2efaf38..67a9c180 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.11.0"
+version: "0.12.0"
description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index ee83dcef..f6623579 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.11.0",
+ "version": "0.12.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index bd7e2b65..ce053274 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.11.0"
+version: "0.12.0"
description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/pyproject.toml b/pyproject.toml
index e75ab3f4..aa28018c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
# CLI entry points (those moved to `package.json` `bin`).
[project]
name = "open-second-brain"
-version = "0.11.0"
+version = "0.12.0"
description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/src/core/brain/content-hash.ts b/src/core/brain/content-hash.ts
new file mode 100644
index 00000000..17937cfd
--- /dev/null
+++ b/src/core/brain/content-hash.ts
@@ -0,0 +1,83 @@
+/**
+ * Content-hash helper for confirmed preferences.
+ *
+ * On promotion to `_status: confirmed`, the dream pass writes
+ * `_content_hash: sha256(principle + scope)` into the frontmatter via
+ * {@link computeContentHash}. Every subsequent read of a confirmed
+ * preference recomputes the hash; {@link verifyContentHash} compares
+ * stored vs. recomputed and tells the caller whether the on-disk
+ * content has drifted away from what dream last sealed.
+ *
+ * Hand-editing a confirmed preference stays legal - drift detection
+ * is observability, not enforcement. A mismatch surfaces as a
+ * `drift_detected` event in `Brain/log/<today>.md` and as a counter
+ * in `brain_doctor`. The read returns the live content unchanged.
+ *
+ * Normalisation rules baked into the digest input:
+ * - principle and scope are trimmed of leading/trailing whitespace
+ * - absent / empty / undefined scope normalises to the empty string
+ *
+ * Both rules keep the hash stable across the frontmatter round-trip
+ * and across the writer's "skip emit for blank scope" semantic.
+ */
+
+import { createHash } from "node:crypto";
+
+const SEPARATOR = "\n";
+
+/**
+ * Compute the canonical content hash for a preference's
+ * (principle, scope) pair. Returns a 64-char lowercase hex sha256.
+ */
+export function computeContentHash(principle: string, scope?: string): string {
+ const normalisedPrinciple = (principle ?? "").trim();
+ const normalisedScope = (scope ?? "").trim();
+ const payload = `${normalisedPrinciple}${SEPARATOR}${normalisedScope}`;
+ return createHash("sha256").update(payload, "utf8").digest("hex");
+}
+
+/**
+ * Input shape for {@link verifyContentHash}. A pared-down view of
+ * {@link BrainPreference} that takes only the three fields the hash
+ * compares - so the helper can be called either with a parsed
+ * `BrainPreference` (with the matching field names) or with a fresh
+ * `{principle, scope, content_hash}` synthesised from elsewhere.
+ */
+export interface ContentHashInput {
+ readonly principle: string;
+ readonly scope?: string;
+ readonly content_hash?: string;
+}
+
+export interface ContentHashVerification {
+ /**
+ * `true` when stored hash matches recomputed, OR when the stored
+ * hash is absent (legacy preference written before this field
+ * existed - we cannot detect drift, so we do not lie about it).
+ */
+ readonly ok: boolean;
+ /** Recomputed hash; undefined when the input had no stored hash to compare against. */
+ readonly expected?: string;
+ /** Stored hash from frontmatter; undefined when the input had none. */
+ readonly observed?: string;
+}
+
+/**
+ * Compare the stored `_content_hash` against the recomputed hash of
+ * the live (principle, scope) pair. When the stored value is absent
+ * the result is neutral (`ok: true`, no expected/observed) - the
+ * caller MUST NOT log a drift event in that case.
+ */
+export function verifyContentHash(
+ input: ContentHashInput,
+): ContentHashVerification {
+ if (!input.content_hash) {
+ return { ok: true };
+ }
+ const expected = computeContentHash(input.principle, input.scope);
+ return {
+ ok: expected === input.content_hash,
+ expected,
+ observed: input.content_hash,
+ };
+}
diff --git a/src/core/brain/doctor.ts b/src/core/brain/doctor.ts
index 78e09c44..2d01d985 100644
--- a/src/core/brain/doctor.ts
+++ b/src/core/brain/doctor.ts
@@ -42,6 +42,8 @@ import { join } from "node:path";
import { extractWikilinks, listVaultBasenames, parseFrontmatter } from "../vault.ts";
import { resolveVaultScope } from "../vault-scope/index.ts";
import { buildBacklinkIndex } from "./backlinks.ts";
+import { verifyContentHash } from "./content-hash.ts";
+import { scanDanglingWorkruns } from "./dream-workrun.ts";
import { parseLogDay } from "./log.ts";
import {
BRAIN_CONFIG_SUPPORTED_VERSIONS,
@@ -282,6 +284,21 @@ export function runDoctor(
checkPinnedWithoutRecentEvidence(prefRecords, issues, cfg, now);
} catch { /* doctor never throws */ }
}
+ // v0.12.0 Brain Integrity Suite: surface preferences whose live
+ // (principle, scope) does not hash to the value stored in
+ // `_content_hash`. Hand-edits remain legal; the warning makes them
+ // observable.
+ try {
+ checkContentHashDrift(prefRecords, issues);
+ } catch { /* doctor never throws */ }
+ // v0.12.0 Brain Integrity Suite: surface every dream workrun file
+ // whose last phase is neither `finalized` nor `interrupted`. A
+ // dangling workrun is forensic evidence that a previous dream
+ // invocation crashed - the operator can inspect the file to see
+ // how far the run got.
+ try {
+ checkDanglingWorkruns(vault, issues);
+ } catch { /* doctor never throws */ }
try {
checkMalformedEvidenceRange(logRecords, issues);
} catch { /* doctor never throws */ }
@@ -910,6 +927,69 @@ function checkPinnedWithoutRecentEvidence(
}
}
+/**
+ * `content-hash-drift` (v0.12.0, Brain Integrity Suite): walks every
+ * confirmed preference, recomputes the content hash from the live
+ * `(principle, scope)`, and surfaces a warning whenever the stored
+ * `_content_hash` no longer matches. Legacy preferences without a
+ * stored hash are silent - drift detection is opt-in via the
+ * promotion-time hash write.
+ *
+ * Hand-edits stay legal: this is observability, not enforcement. The
+ * operator sees the divergence and decides whether to re-promote the
+ * preference (which writes a fresh hash) or accept the drift.
+ */
+function checkContentHashDrift(
+ prefs: ReadonlyArray<PreferenceRecord>,
+ issues: DoctorIssue[],
+): void {
+ for (const { path, pref } of prefs) {
+ if (pref.status !== BRAIN_PREFERENCE_STATUS.confirmed) continue;
+ if (!pref.content_hash) continue;
+ const v = verifyContentHash({
+ principle: pref.principle,
+ scope: pref.scope,
+ content_hash: pref.content_hash,
+ });
+ if (!v.ok) {
+ issues.push({
+ severity: "warning",
+ code: "content-hash-drift",
+ path,
+ message:
+ `content-hash drift on ${pref.id}: stored ${v.observed} ` +
+ `does not match recomputed ${v.expected}`,
+ });
+ }
+ }
+}
+
+/**
+ * `dangling-workrun` (v0.12.0, Brain Integrity Suite): surfaces every
+ * dream-pass workrun JSONL whose last event is neither `finalized`
+ * nor `interrupted`. A non-empty result means at least one previous
+ * dream invocation died before it could declare a terminal phase,
+ * usually because the host process was killed mid-run. The next
+ * dream pass starts fresh - this check is purely observational so
+ * the operator notices the failed run.
+ */
+function checkDanglingWorkruns(
+ vault: string,
+ issues: DoctorIssue[],
+): void {
+ for (const path of scanDanglingWorkruns(vault)) {
+ issues.push({
+ severity: "warning",
+ code: "dangling-workrun",
+ path,
+ message:
+ `dream-pass workrun did not reach a terminal phase: ${path}. ` +
+ "A previous dream run was likely killed mid-execution; " +
+ "subsequent dream invocations will continue normally.",
+ });
+ }
+}
+
/**
* `malformed-evidence-range`: walks every `apply-evidence` event,
* runs the artifact wikilink through {@link parseArtifactRef}, and
diff --git a/src/core/brain/dream-workrun.ts b/src/core/brain/dream-workrun.ts
new file mode 100644
index 00000000..2d289994
--- /dev/null
+++ b/src/core/brain/dream-workrun.ts
@@ -0,0 +1,155 @@
+/**
+ * Durable workrun checkpoints for the dream pass (Brain Integrity
+ * Suite Feature 4).
+ *
+ * Each dream invocation opens a JSONL workrun file under
+ * `Brain/log/dream-runs/<run-id>.jsonl` and records one line per
+ * phase transition (`started`, `cluster_complete`, `promote_complete`,
+ * `retire_complete`, `finalized` | `interrupted`). A crash mid-pass
+ * leaves an inspectable trail; the next invocation calls
+ * {@link scanDanglingWorkruns} on startup to find any run that did
+ * not reach `finalized` / `interrupted`. Recovery is non-resuming -
+ * the next dream pass processes the inbox fresh; the dangling file
+ * serves as forensic evidence, not a resumable state machine.
+ *
+ * Dry-run never opens a workrun: dryRun must not mutate disk.
+ *
+ * Writes use `appendFileSync` on the same file. The OS guarantees
+ * `O_APPEND` is atomic for small writes (under PIPE_BUF, 4096 bytes
+ * on Linux); each JSONL line is ~120 bytes so a partial write would
+ * be deeply pathological. We do not fsync per phase - a crash that
+ * loses the last phase line is acceptable (the file is still flagged
+ * dangling on the next scan).
+ */
+
+import {
+ appendFileSync,
+ existsSync,
+ lstatSync,
+ mkdirSync,
+ readFileSync,
+ readdirSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+import {
+ dreamRunsDir,
+ dreamWorkrunPath,
+} from "./paths.ts";
+
+/**
+ * Canonical phase identifiers. Five forward-progress phases plus the
+ * sticky `interrupted` terminal. The dream pass emits them in the
+ * order declared; readers MUST tolerate unknown future phases.
+ */
+export const WORKRUN_PHASE = Object.freeze({
+ started: "started",
+ clusterComplete: "cluster_complete",
+ promoteComplete: "promote_complete",
+ retireComplete: "retire_complete",
+ finalized: "finalized",
+ interrupted: "interrupted",
+} as const);
+
+export type WorkrunPhase =
+ (typeof WORKRUN_PHASE)[keyof typeof WORKRUN_PHASE];
+
+export interface WorkrunHandle {
+ /** Path of the underlying JSONL file. */
+ readonly path: string;
+ /** Append one checkpoint line. Silent no-op after finalize/interrupt. */
+ checkpoint(phase: WorkrunPhase, payload?: Record<string, unknown>): void;
+ /** Append the terminal `finalized` line. Idempotent. */
+ finalize(): void;
+ /** Append a terminal `interrupted` line with optional reason. Idempotent. */
+ interrupt(reason?: string): void;
+}
+
+/**
+ * Open a workrun for `runId`, immediately writing the `started`
+ * phase. Creates the workrun directory on demand.
+ */
+export function openWorkrun(vault: string, runId: string): WorkrunHandle {
+ const path = dreamWorkrunPath(vault, runId);
+ mkdirSync(dirname(path), { recursive: true });
+ let closed = false;
+ const append = (phase: WorkrunPhase, extra: Record<string, unknown> = {}): void => {
+ const line = JSON.stringify({
+ phase,
+ at: new Date().toISOString(),
+ run_id: runId,
+ ...extra,
+ }) + "\n";
+ appendFileSync(path, line, "utf8");
+ };
+ append(WORKRUN_PHASE.started);
+ return {
+ path,
+ checkpoint(phase: WorkrunPhase, payload: Record<string, unknown> = {}): void {
+ if (closed) return;
+ append(phase, payload);
+ },
+ finalize(): void {
+ if (closed) return;
+ closed = true;
+ append(WORKRUN_PHASE.finalized);
+ },
+ interrupt(reason?: string): void {
+ if (closed) return;
+ closed = true;
+ append(
+ WORKRUN_PHASE.interrupted,
+ reason !== undefined ? { reason } : {},
+ );
+ },
+ };
+}
+
+/**
+ * Walk `Brain/log/dream-runs/` and return the paths of every workrun
+ * whose last event is neither `finalized` nor `interrupted`. A
+ * corrupt / unparseable file is treated as dangling so the operator
+ * sees it.
+ */
+export function scanDanglingWorkruns(vault: string): string[] {
+ const dir = dreamRunsDir(vault);
+ if (!existsSync(dir)) return [];
+ const out: string[] = [];
+ for (const name of readdirSync(dir)) {
+ if (!name.endsWith(".jsonl")) continue;
+ const path = join(dir, name);
+ // Skip non-regular files (a directory named `*.jsonl` would
+ // otherwise be reported as dangling on the very first readFileSync
+ // failure). lstat ignores symlinks the same way.
+ try {
+ if (!lstatSync(path).isFile()) continue;
+ } catch {
+ continue;
+ }
+ try {
+ const text = readFileSync(path, "utf8");
+ const lines = text.split("\n").filter((l) => l.trim().length > 0);
+ if (lines.length === 0) {
+ out.push(path);
+ continue;
+ }
+ const last = lines[lines.length - 1]!;
+ let parsed: { phase?: unknown };
+ try {
+ parsed = JSON.parse(last) as { phase?: unknown };
+ } catch {
+ out.push(path);
+ continue;
+ }
+ if (
+ parsed.phase !== WORKRUN_PHASE.finalized &&
+ parsed.phase !== WORKRUN_PHASE.interrupted
+ ) {
+ out.push(path);
+ }
+ } catch {
+ out.push(path);
+ }
+ }
+ return out;
+}
diff --git a/src/core/brain/dream.ts b/src/core/brain/dream.ts
index 10af4c13..13759494 100644
--- a/src/core/brain/dream.ts
+++ b/src/core/brain/dream.ts
@@ -39,7 +39,13 @@ import { basename, join } from "node:path";
import { parseFrontmatter } from "../vault.ts";
import { regenerateActiveQuiet } from "./active.ts";
+import {
+ openWorkrun,
+ WORKRUN_PHASE,
+ type WorkrunHandle,
+} from "./dream-workrun.ts";
import { collectEvidenceForSlug } from "./evidence.ts";
+import { writePreferenceTxn } from "./preference-txn.ts";
import {
appendLogEvent,
parseLogDay,
@@ -49,7 +55,6 @@ import {
moveToRetired,
parsePreference,
wouldRewritePreference,
- writePreference,
} from "./preference.ts";
import { parseSignal } from "./signal.ts";
import { isPinned } from "./pin.ts";
@@ -134,6 +139,25 @@ export interface DreamQuarantinedEntry {
readonly failed_gates: ReadonlyArray<string>;
}
+/**
+ * Brain Integrity Suite (v0.12.0). Entry for a retire that the dream
+ * pass declined because `retire.confirmed_evidence_min_threshold` was
+ * set and the source preference's accumulated evidence count fell
+ * below it. The pref stays in `preferences/`; the operator can lift
+ * the gate by raising the evidence count, lowering the threshold, or
+ * running `o2b brain reject` explicitly.
+ */
+export interface DreamGatedRetireEntry {
+ readonly pref_id: string;
+ readonly topic: string;
+ readonly applied_count: number;
+ readonly violated_count: number;
+ /** Configured threshold the pref's evidence count fell below. */
+ readonly threshold: number;
+ /** The retire reason the plan computed before the gate fired. */
+ readonly attempted_reason: BrainRetiredReason;
+}
+
export interface DreamRunSummary {
/** `dream-YYYY-MM-DD-HHMMSS`. */
readonly run_id: string;
@@ -177,6 +201,13 @@ export interface DreamRunSummary {
* match pre-v0.10.16 behaviour.
*/
readonly quarantined: ReadonlyArray<DreamQuarantinedEntry>;
+ /**
+ * Brain Integrity Suite (v0.12.0). Retires the dream pass planned
+ * but declined to execute because the source preference's evidence
+ * count fell below `retire.confirmed_evidence_min_threshold`. Empty
+ * when the config field is absent (the default).
+ */
+ readonly gated_retires: ReadonlyArray<DreamGatedRetireEntry>;
/** Snapshot file (absent on a no-op run). */
readonly snapshot_path?: string;
/** Log file the run summary landed in (absent on a no-op run). */
@@ -332,6 +363,7 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
warnings: Object.freeze([...warnings]),
uncertain: Object.freeze([] as ReadonlyArray<DreamUncertainEntry>),
quarantined: Object.freeze([...plan.quarantined]),
+ gated_retires: Object.freeze([] as ReadonlyArray<DreamGatedRetireEntry>),
...(dryRun ? { dry_run: true } : {}),
} satisfies DreamRunSummary);
}
@@ -358,13 +390,32 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
// 5. Emit log entries (noted-redundant, retain-pinned,
// skip-corrupted-frontmatter, dream summary).
const moved: string[] = [];
+ // v0.12.0 Brain Integrity Suite: declined retires accumulate here.
+ // Always declared (even when no gate is configured) so the eventual
+ // DreamRunSummary.gated_retires field is consistently an array.
+ const gatedRetires: DreamGatedRetireEntry[] = [];
+
+ // v0.12.0 Brain Integrity Suite: durable workrun for the dream pass.
+ // Opened lazily on the mutation path (no workrun on dry-run or
+ // no-op early-return). The handle is null until the exec branch
+ // claims it; `finally` finalises if non-null.
+ let workrun: WorkrunHandle | null = null;
+ if (!dryRun) {
+ workrun = openWorkrun(vault, runId);
+ workrun.checkpoint(WORKRUN_PHASE.clusterComplete);
+ }
if (!dryRun) {
for (const np of plan.newUnconfirmed) {
// Fresh pref has no apply-evidence yet; recentApplied/recentViolated
// start empty and stay so until the next dream pass after the
// first `brain_apply_evidence` event.
- writePreference(
+ // v0.12.0 Brain Integrity Suite: route every dream-pass write
+ // through writePreferenceTxn so _revision auto-stamps and
+ // _content_hash lands automatically on confirmed promotions.
+ // Empty expectations array - dream's plan-time logic has
+ // already decided to proceed; the txn just owns the bookkeeping.
+ writePreferenceTxn(
vault,
{
slug: np.slug,
@@ -386,6 +437,7 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
...(np.scope ? { scope: np.scope } : {}),
...(np.supersedes ? { supersedes: np.supersedes } : {}),
},
+ [],
{ overwrite: false },
);
}
@@ -398,7 +450,9 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
const ev = collectEvidenceForSlug(vault, update.slug, {
sinceIso: update.created_at,
});
- writePreference(
+ // Same txn route as the newUnconfirmed loop: auto-stamps
+ // _revision (existing+1) and _content_hash on confirmed status.
+ writePreferenceTxn(
vault,
{
slug: update.slug,
@@ -419,6 +473,7 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
recentViolated: ev.violated,
...(update.scope ? { scope: update.scope } : {}),
},
+ [],
{ overwrite: true },
);
}
@@ -426,6 +481,31 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
for (const r of plan.retires) {
const fromPath = preferencePath(vault, r.slug);
if (!existsSync(fromPath)) continue;
+ // v0.12.0 Brain Integrity Suite: destructive-from-confirmed gate.
+ // When the operator has set retire.confirmed_evidence_min_threshold,
+ // refuse to retire a confirmed (unpinned) pref whose accumulated
+ // evidence count is below the configured floor. Operator-initiated
+ // retires bypass.
+ const gateThreshold = cfg.retire.confirmed_evidence_min_threshold;
+ if (gateThreshold !== undefined && gateThreshold > 0) {
+ try {
+ const existing = parsePreference(fromPath);
+ if (shouldGateRetireFromConfirmed(existing, r.reason, gateThreshold)) {
+ gatedRetires.push({
+ pref_id: existing.id,
+ topic: existing.topic,
+ applied_count: existing.applied_count,
+ violated_count: existing.violated_count,
+ threshold: gateThreshold,
+ attempted_reason: r.reason,
+ });
+ continue;
+ }
+ } catch {
+ // Parse failure - fall through to the normal retire path
+ // (moveToRetired will surface the error through stderr below).
+ }
+ }
try {
moveToRetired(vault, fromPath, r.reason, {
now,
@@ -463,6 +543,24 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
for (const sig of plan.signalsToMove.values()) moved.push(sig.id);
}
+ // v0.12.0 Brain Integrity Suite: mark promote + retire phases. The
+ // dream.ts execution loop runs promote (writePreference) then retire
+ // (moveToRetired) sequentially; one checkpoint covers both
+ // mutations so the workrun stays compact yet recovery-meaningful.
+ if (workrun !== null) {
+ workrun.checkpoint(WORKRUN_PHASE.promoteComplete);
+ workrun.checkpoint(WORKRUN_PHASE.retireComplete);
+ }
+
+ // v0.12.0 Brain Integrity Suite: build the gated-slug set once so the
+ // log body and the DreamRunSummary stay consistent β€” both views must
+ // exclude retires the destructive-from-confirmed gate skipped, or
+ // the next dream pass would parse a `pref-foo` log claiming the
+ // pref was retired while the file is still in `preferences/`.
+ const gatedSlugs = new Set(
+ gatedRetires.map((g) => g.pref_id.replace(/^pref-/, "")),
+ );
+
// Emit log entries: skip-corrupted-frontmatter first (chronological
// sense: corruption was detected during planning), then per-topic
// events (noted-redundant), then run summary last.
@@ -547,10 +645,12 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
?? "",
}),
);
- const retiredEntries = plan.retires.map(
- (r) =>
- `${renderPrefLink({ id: `ret-${r.slug}`, principle: r.principle })} (${r.reason})`,
- );
+ const retiredEntries = plan.retires
+ .filter((r) => !gatedSlugs.has(r.slug))
+ .map(
+ (r) =>
+ `${renderPrefLink({ id: `ret-${r.slug}`, principle: r.principle })} (${r.reason})`,
+ );
const summaryBody: Record<string, string | ReadonlyArray<string>> = {
run_id: runId,
};
@@ -610,12 +710,20 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
regenerateActiveQuiet(vault, { now });
}
+ // v0.12.0 Brain Integrity Suite: finalise the durable workrun
+ // immediately before constructing the summary. Any crash building
+ // the summary leaves the workrun dangling for the next pass to
+ // spot. `workrun` is null on dry-run / pre-mutation paths.
+ workrun?.finalize();
+
return Object.freeze({
run_id: runId,
changed: true,
new_unconfirmed: plan.newUnconfirmed.map((p) => `pref-${p.slug}`),
confirmed: Array.from(refresh.confirmed.values()).map((s) => `pref-${s}`),
- retired: plan.retires.map((r) => ({ id: `ret-${r.slug}`, reason: r.reason })),
+ retired: plan.retires
+ .filter((r) => !gatedSlugs.has(r.slug))
+ .map((r) => ({ id: `ret-${r.slug}`, reason: r.reason })),
contradictions: Array.from(plan.contradictionTopics),
moved_to_processed: moved,
suppressed: plan.signalsSuppressed.map((s) =>
@@ -624,6 +732,7 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
warnings: Object.freeze([...warnings]),
uncertain: Object.freeze([] as ReadonlyArray<DreamUncertainEntry>),
quarantined: Object.freeze([...plan.quarantined]),
+ gated_retires: Object.freeze([...gatedRetires]),
...(snapshotPathStr ? { snapshot_path: snapshotPathStr } : {}),
...(dryRun
? { dry_run: true }
@@ -631,6 +740,30 @@ export function dream(vault: string, opts: DreamOptions = {}): DreamRunSummary {
} satisfies DreamRunSummary);
}
+/**
+ * Brain Integrity Suite (v0.12.0). Pure decision function for the
+ * destructive-from-confirmed gate. Exported so the gate logic can be
+ * unit-tested without driving a full dream run.
+ *
+ * Returns `true` when the candidate retire MUST be held back. The
+ * caller is responsible for recording a {@link DreamGatedRetireEntry}
+ * and skipping the actual `moveToRetired` call.
+ */
+export function shouldGateRetireFromConfirmed(
+ existing: BrainPreference,
+ reason: BrainRetiredReason,
+ threshold: number | undefined,
+): boolean {
+ if (threshold === undefined || threshold <= 0) return false;
+ if (reason === BRAIN_RETIRED_REASON.userRejected) return false;
+ if (reason === BRAIN_RETIRED_REASON.mergedInto) return false;
+ if (existing.status !== BRAIN_PREFERENCE_STATUS.confirmed) return false;
+ if (existing.pinned) return false;
+ const evidenceCount =
+ (existing.applied_count ?? 0) + (existing.violated_count ?? 0);
+ return evidenceCount < threshold;
+}
+
// ----- Scan ---------------------------------------------------------------
function scanBrain(vault: string): ScanResult {
@@ -1492,6 +1625,24 @@ function planRefresh(
...prospective,
recentApplied: ev2.applied,
recentViolated: ev2.violated,
+ // v0.12.0 Brain Integrity Suite: feed the existing
+ // _revision and _content_hash into the pre-flight render
+ // so the byte comparison matches the writePreferenceTxn
+ // no-op semantic. Otherwise a refreshed pref written by a
+ // prior pass (with _revision: N stamped) would look like
+ // "needs rewrite" against a prospective render that omits
+ // those fields, flipping changed=false runs into spurious
+ // updates.
+ // parsePreference defaults absent _revision to 0; treat 0
+ // the same as "absent" for the pre-flight render so the
+ // bytes-compare matches existing legacy starter files that
+ // never had the field on disk.
+ ...(rec.pref.revision !== undefined && rec.pref.revision > 0
+ ? { revision: rec.pref.revision }
+ : {}),
+ ...(rec.pref.content_hash !== undefined
+ ? { content_hash: rec.pref.content_hash }
+ : {}),
})
) {
// Counters and body both unchanged β€” true no-op for this pref.
diff --git a/src/core/brain/paths.ts b/src/core/brain/paths.ts
index e565f1a7..3ed62421 100644
--- a/src/core/brain/paths.ts
+++ b/src/core/brain/paths.ts
@@ -186,6 +186,26 @@ export function logJsonlPath(vault: string, date: string): string {
return ensureInsideVault(join(brainDirs(vault).log, `${d}.jsonl`), vault);
}
+/**
+ * Brain Integrity Suite (v0.12.0). Workrun directory used by the
+ * durable dream-pass checkpoint surface: `Brain/log/dream-runs/`.
+ * Lives under the log dir so backups already include it.
+ */
+export function dreamRunsDir(vault: string): string {
+ return join(brainDirs(vault).log, "dream-runs");
+}
+
+/**
+ * Brain Integrity Suite (v0.12.0). Durable workrun JSONL for a
+ * single dream invocation: `Brain/log/dream-runs/<run-id>.jsonl`.
+ * The run id is validated through {@link validateRunId} so it stays
+ * inside the canonical directory.
+ */
+export function dreamWorkrunPath(vault: string, runId: string): string {
+ const id = validateRunId(runId);
+ return ensureInsideVault(join(dreamRunsDir(vault), `${id}.jsonl`), vault);
+}
+
/** Snapshots directory: `Brain/.snapshots/`. */
export function snapshotsDir(vault: string): string {
return brainDirs(vault).snapshots;
diff --git a/src/core/brain/preference-txn.ts b/src/core/brain/preference-txn.ts
new file mode 100644
index 00000000..14fa27a5
--- /dev/null
+++ b/src/core/brain/preference-txn.ts
@@ -0,0 +1,285 @@
+/**
+ * `writePreferenceTxn` - single chokepoint for every preference write.
+ *
+ * Direct writes via {@link writePreference} and indirect writes via the
+ * dream pass (promotion / retirement) both flow through this function.
+ * That gives the brain integrity suite one place to bolt on every
+ * collision check and gate (drift, stale-update, unsafe-shrink,
+ * destructive replacement, ...) without sprinkling parallel checks
+ * across `preference.ts` and `dream.ts`.
+ *
+ * Shape:
+ *
+ * 1. Compute target path from `input.slug`.
+ * 2. Acquire the sync lockfile (`<path>.lock`). EEXIST -> `SourceLock`
+ * collision error (typed).
+ * 3. Re-read the existing preference inside the lock, if the file
+ * already exists. The expectations chain sees this snapshot
+ * verbatim - any check that depends on "current vs. proposed"
+ * reads it from `ctx.existing`.
+ * 4. Run the expectations chain in order. The first one that throws
+ * `BrainCollisionError` aborts the txn; subsequent expectations
+ * do not run.
+ * 5. Delegate the write to {@link writePreference} (which handles
+ * validation, frontmatter rendering, content-equality shortcut,
+ * and the atomic write itself).
+ * 6. Release the lock in a `finally` block so the lock is freed
+ * regardless of whether the write or an expectation threw.
+ */
+
+import { existsSync } from "node:fs";
+
+import { computeContentHash } from "./content-hash.ts";
+import {
+ preferencePath,
+ validateSlug,
+} from "./paths.ts";
+import {
+ parsePreference,
+ writePreference,
+ wouldRewritePreference,
+ type WritePreferenceInput,
+ type WritePreferenceOptions,
+ type WritePreferenceResult,
+} from "./preference.ts";
+import { acquireLockSync } from "./sync-lockfile.ts";
+import {
+ BRAIN_PREFERENCE_STATUS,
+ type BrainPreference,
+} from "./types.ts";
+
+/**
+ * Machine-friendly discriminants for the four collision modes covered
+ * by the brain integrity suite. No human-language strings: the names
+ * surface as `.kind` on {@link BrainCollisionError} and as event codes
+ * in `Brain/log/`. Languages-of-output stay out of the rule itself.
+ */
+export const BRAIN_COLLISION_KIND = Object.freeze({
+ staleUpdate: "StaleUpdate",
+ unsafeShrink: "UnsafeShrink",
+ sourceLock: "SourceLock",
+ duplicateWrite: "DuplicateWrite",
+} as const);
+
+export type BrainCollisionKind =
+ (typeof BRAIN_COLLISION_KIND)[keyof typeof BRAIN_COLLISION_KIND];
+
+/**
+ * Typed error surfaced by every txn collision mode. `kind` is the
+ * machine-readable discriminant; the message carries human prose only
+ * for log/console rendering.
+ */
+export class BrainCollisionError extends Error {
+ readonly kind: BrainCollisionKind;
+
+ constructor(kind: BrainCollisionKind, message: string) {
+ super(message);
+ this.name = "BrainCollisionError";
+ this.kind = kind;
+ }
+}
+
+/**
+ * Context passed to every expectation. Carries the resolved path, the
+ * existing preference (if any), and the proposed input. Expectations
+ * must be pure relative to the txn's own state - they can throw
+ * {@link BrainCollisionError} but must not mutate `ctx`.
+ */
+export interface WritePreferenceContext {
+ readonly vault: string;
+ readonly path: string;
+ readonly existing: BrainPreference | null;
+ readonly input: WritePreferenceInput;
+}
+
+/**
+ * One expectation in the chain. Synchronous, runs inside the lock
+ * after the existing preference (if any) has been re-read. Throws
+ * {@link BrainCollisionError} to abort the write; returning normally
+ * signals "ok, keep going".
+ */
+export type WritePreferenceExpectation = (
+ ctx: WritePreferenceContext,
+) => void;
+
+/**
+ * Write a preference under an exclusive sync lock, running the
+ * expectations chain before the mutation. {@link writePreference}'s
+ * own validation + rendering + atomic-write still runs - the txn just
+ * gates it.
+ *
+ * Callers without collision checks pass an empty expectations array;
+ * the txn then behaves identically to `writePreference(vault, input,
+ * options)` aside from the lock acquire/release pair (which is cheap
+ * when uncontended).
+ */
+export function writePreferenceTxn(
+ vault: string,
+ input: WritePreferenceInput,
+ expectations: ReadonlyArray<WritePreferenceExpectation>,
+ options: WritePreferenceOptions = {},
+): WritePreferenceResult {
+ const slug = validateSlug(input.slug);
+ const path = preferencePath(vault, slug);
+
+ let handle: ReturnType<typeof acquireLockSync>;
+ try {
+ handle = acquireLockSync(path);
+ } catch (err) {
+ const e = err as NodeJS.ErrnoException;
+ if (e.code === "ELOCKED") {
+ throw new BrainCollisionError(
+ BRAIN_COLLISION_KIND.sourceLock,
+ `preference write blocked by active lock: ${path}`,
+ );
+ }
+ throw err;
+ }
+
+ try {
+ const existing = existsSync(path) ? parsePreference(path) : null;
+ const ctx: WritePreferenceContext = Object.freeze({
+ vault,
+ path,
+ existing,
+ input,
+ });
+ for (const expectation of expectations) {
+ expectation(ctx);
+ }
+ // Brain Integrity Suite smart defaults (v0.12.0). The txn owns
+ // two pieces of bookkeeping for callers that opt in:
+ //
+ // - `_content_hash` lands automatically on promotion to
+ // `confirmed` so the doctor's drift check has something to
+ // compare against. Skipped when the caller supplies a hash
+ // of their own.
+ // - `_revision` is a monotonic write counter that increments
+ // ONLY when the proposed content would actually change the
+ // on-disk bytes. A dream-pass no-op rerun must stay
+ // byte-identical, so the txn pre-renders the would-be write
+ // with the existing revision and bumps only when
+ // `wouldRewritePreference` says the file would change.
+ //
+ // Callers that bypass the txn keep pre-v0.12.0 semantics.
+ const autoHash =
+ input.content_hash === undefined
+ && input.status === BRAIN_PREFERENCE_STATUS.confirmed
+ ? { content_hash: computeContentHash(input.principle, input.scope) }
+ : {};
+ const candidate: WritePreferenceInput = {
+ ...input,
+ ...autoHash,
+ revision: input.revision ?? (existing?.revision ?? 0),
+ };
+ const willChange =
+ input.revision !== undefined
+ || existing === null
+ || wouldRewritePreference(vault, candidate);
+ const inputWithDefaults: WritePreferenceInput = willChange
+ ? {
+ ...candidate,
+ revision: input.revision ?? ((existing?.revision ?? 0) + 1),
+ }
+ : candidate;
+ return writePreference(vault, inputWithDefaults, options);
+ } finally {
+ handle.release();
+ }
+}
+
+// ----- Expectation factories -----------------------------------------------
+//
+// Each factory returns a {@link WritePreferenceExpectation} ready to be
+// dropped into the txn's expectations array. Callers compose them
+// declaratively at the call site; the txn runs them in order under the
+// lock, before delegating to {@link writePreference}.
+
+/**
+ * StaleUpdate gate. The writer must declare which revision it read;
+ * the txn rejects the write if the on-disk revision has moved.
+ *
+ * Treats a missing on-disk `_revision` field as 0 - the absent-as-zero
+ * convention from {@link BrainPreference.revision}'s reader.
+ */
+export function expectRevision(
+ expected: number,
+): WritePreferenceExpectation {
+ return (ctx) => {
+ const current = ctx.existing?.revision ?? 0;
+ if (current !== expected) {
+ throw new BrainCollisionError(
+ BRAIN_COLLISION_KIND.staleUpdate,
+ `stale update: expected revision ${expected}, found ${current} (path=${ctx.path})`,
+ );
+ }
+ };
+}
+
+/**
+ * UnsafeShrink gate. The new principle's length must stay at or above
+ * `minRatio * existingPrinciple.length`. A first-time write (no
+ * existing preference) is always allowed.
+ *
+ * `minRatio` should be a value in `(0, 1]`. The dream pass passes
+ * `cfg.confidence.unsafe_shrink_min_ratio` here when promoting or
+ * refreshing a confirmed preference.
+ */
+export function noUnsafeShrink(minRatio: number): WritePreferenceExpectation {
+ if (!Number.isFinite(minRatio) || minRatio <= 0 || minRatio > 1) {
+ throw new RangeError(
+ `noUnsafeShrink(minRatio) expects a finite value in (0, 1]; got ${String(minRatio)}`,
+ );
+ }
+ return (ctx) => {
+ if (!ctx.existing) return;
+ const existingLen = ctx.existing.principle.length;
+ if (existingLen <= 0) return;
+ const newLen = ctx.input.principle.length;
+ const ratio = newLen / existingLen;
+ if (ratio < minRatio) {
+ throw new BrainCollisionError(
+ BRAIN_COLLISION_KIND.unsafeShrink,
+ `unsafe shrink: new principle ${newLen} chars is below ${minRatio} * ${existingLen} (ratio=${ratio.toFixed(3)})`,
+ );
+ }
+ };
+}
+
+/**
+ * DuplicateWrite gate. Triggers when the proposed content's
+ * {@link computeContentHash} matches the existing `content_hash`
+ * AND the existing `last_evidence_at` is within `windowMs` of `now()`.
+ *
+ * Use case: an agent re-fires a `dream` refresh for the same pref
+ * while a previous write is still settling. The gate stays silent on
+ * legacy preferences (no `content_hash`) so backfills are never
+ * mis-classified as duplicates.
+ *
+ * `now` is injectable so tests do not depend on wall-clock.
+ */
+export function noDuplicateWriteWithin(
+ windowMs: number,
+ now: () => Date = () => new Date(),
+): WritePreferenceExpectation {
+ return (ctx) => {
+ const existing = ctx.existing;
+ if (!existing) return;
+ const existingHash = existing.content_hash;
+ if (!existingHash) return;
+ const proposedHash = computeContentHash(
+ ctx.input.principle,
+ ctx.input.scope,
+ );
+ if (existingHash !== proposedHash) return;
+ const lastEv = existing.last_evidence_at;
+ if (!lastEv) return;
+ const ageMs = now().getTime() - new Date(lastEv).getTime();
+ if (ageMs >= 0 && ageMs < windowMs) {
+ throw new BrainCollisionError(
+ BRAIN_COLLISION_KIND.duplicateWrite,
+ `duplicate write: identical content hash within ${windowMs}ms window (age=${ageMs}ms)`,
+ );
+ }
+ };
+}
diff --git a/src/core/brain/preference.ts b/src/core/brain/preference.ts
index f0c46249..a109863a 100644
--- a/src/core/brain/preference.ts
+++ b/src/core/brain/preference.ts
@@ -128,6 +128,21 @@ export interface WritePreferenceInput {
*/
readonly tier?: PageTier;
readonly pinned?: boolean;
+ /**
+ * Brain Integrity Suite (v0.12.0). Optional monotonic write counter
+ * persisted as `_revision`. `writePreferenceTxn` auto-stamps the
+ * next value when callers omit. Direct `writePreference` callers
+ * that omit the field skip the emission entirely - legacy fixtures
+ * stay byte-identical (the reader treats absent as `0`).
+ */
+ readonly revision?: number;
+ /**
+ * Brain Integrity Suite (v0.12.0). Optional sha256 of the canonical
+ * `(principle, scope)` pair persisted as `_content_hash`. Dream
+ * supplies on promotion to `confirmed`; emitted verbatim when
+ * supplied, omitted otherwise.
+ */
+ readonly content_hash?: string;
readonly supersedes?: string;
readonly aliases?: ReadonlyArray<string>;
/** Optional extra tags merged after the canonical set. */
@@ -334,6 +349,12 @@ function preferenceFrontmatter(
_confidence_value: confidenceValueField,
pinned,
};
+ // Brain Integrity Suite additive fields. Both follow the
+ // `_lifecycle` precedent: emit only when the caller supplies a
+ // value so legacy fixtures and the starter bundle stay
+ // byte-identical with absent-as-default reader semantics.
+ if (input.revision !== undefined) metadata["_revision"] = input.revision;
+ if (input.content_hash) metadata["_content_hash"] = input.content_hash;
if (input.scope?.trim()) metadata["scope"] = input.scope.trim();
if (input.supersedes?.trim()) metadata["supersedes"] = input.supersedes.trim();
if (input.aliases && input.aliases.length > 0) {
@@ -459,6 +480,8 @@ export const DERIVED_FIELDS: ReadonlyArray<string> = Object.freeze([
"evidenced_by",
"contradicted_by",
"lifecycle",
+ "revision",
+ "content_hash",
]);
/**
@@ -553,6 +576,10 @@ export function parsePreference(path: string): BrainPreference {
confidence: parseConfidence(meta, path),
confidence_value: parseConfidenceValue(meta, path),
pinned: parsePinned(meta),
+ revision: optionalNumber(meta, "revision", 0),
+ ...(optionalScalarString(meta, "content_hash") !== undefined
+ ? { content_hash: optionalScalarString(meta, "content_hash") }
+ : {}),
...(optionalScalarString(meta, "scope") !== undefined
? { scope: optionalScalarString(meta, "scope") }
: {}),
diff --git a/src/core/brain/review-candidates.ts b/src/core/brain/review-candidates.ts
new file mode 100644
index 00000000..b991f410
--- /dev/null
+++ b/src/core/brain/review-candidates.ts
@@ -0,0 +1,111 @@
+/**
+ * Brain Integrity Suite (v0.12.0) - `brain_review_candidates`.
+ *
+ * Read-only projection over what the next `dream` invocation would
+ * do. Calls `dream(vault, { dryRun: true })` and reshapes the
+ * summary into a focused agent-facing report. No persistent state
+ * is mutated; the underlying dry-run dream pass also skips the
+ * workrun emission.
+ *
+ * The shape is intentionally narrow - just the fields an operator or
+ * agent needs to decide "should I do anything before the dream pass
+ * runs?". Callers that want the full DreamRunSummary should call
+ * `brain_dream` with `dry_run: true` directly.
+ */
+
+import { dream } from "./dream.ts";
+import { BRAIN_RETIRED_REASON, type BrainRetiredReason } from "./types.ts";
+
+export interface ReviewCandidatesReport {
+ /** `pref-<slug>` ids that the dream pass would create new. */
+ readonly would_create: ReadonlyArray<string>;
+ /** `pref-<slug>` ids transitioning unconfirmed -> confirmed. */
+ readonly would_promote: ReadonlyArray<string>;
+ /** Retire entries (id + reason). */
+ readonly would_retire: ReadonlyArray<{
+ readonly id: string;
+ readonly reason: BrainRetiredReason;
+ }>;
+ /** Subset of `would_retire` whose reason is `superseded-by-context`. */
+ readonly would_supersede: ReadonlyArray<{
+ readonly id: string;
+ readonly reason: BrainRetiredReason;
+ }>;
+ /**
+ * Signal clusters held back by the self-approval guardrail. Mirror
+ * of `DreamRunSummary.quarantined` plus a one-shot
+ * `failed_gates` list.
+ */
+ readonly clusters_below_threshold: ReadonlyArray<{
+ readonly topic: string;
+ readonly signal_count: number;
+ readonly distinct_agents: number;
+ readonly age_days: number;
+ readonly failed_gates: ReadonlyArray<string>;
+ }>;
+ /**
+ * Retires the destructive-from-confirmed gate would skip. Mirror
+ * of `DreamRunSummary.gated_retires`.
+ */
+ readonly gated_retires: ReadonlyArray<{
+ readonly pref_id: string;
+ readonly topic: string;
+ readonly applied_count: number;
+ readonly violated_count: number;
+ readonly threshold: number;
+ readonly attempted_reason: BrainRetiredReason;
+ }>;
+}
+
+export interface BuildReviewCandidatesOptions {
+ /** Wall clock for the underlying dream pass. */
+ readonly now?: Date;
+}
+
+export function buildReviewCandidates(
+ vault: string,
+ opts: BuildReviewCandidatesOptions = {},
+): ReviewCandidatesReport {
+ const summary = dream(vault, {
+ dryRun: true,
+ ...(opts.now ? { now: opts.now } : {}),
+ });
+
+ return Object.freeze({
+ would_create: Object.freeze([...summary.new_unconfirmed]),
+ would_promote: Object.freeze([...summary.confirmed]),
+ would_retire: Object.freeze(
+ summary.retired.map((r) =>
+ Object.freeze({ id: r.id, reason: r.reason }),
+ ),
+ ),
+ would_supersede: Object.freeze(
+ summary.retired
+ .filter((r) => r.reason === BRAIN_RETIRED_REASON.supersededByContext)
+ .map((r) => Object.freeze({ id: r.id, reason: r.reason })),
+ ),
+ clusters_below_threshold: Object.freeze(
+ summary.quarantined.map((q) =>
+ Object.freeze({
+ topic: q.topic,
+ signal_count: q.signal_count,
+ distinct_agents: q.distinct_agents,
+ age_days: q.age_days,
+ failed_gates: Object.freeze([...q.failed_gates]),
+ }),
+ ),
+ ),
+ gated_retires: Object.freeze(
+ summary.gated_retires.map((g) =>
+ Object.freeze({
+ pref_id: g.pref_id,
+ topic: g.topic,
+ applied_count: g.applied_count,
+ violated_count: g.violated_count,
+ threshold: g.threshold,
+ attempted_reason: g.attempted_reason,
+ }),
+ ),
+ ),
+ } satisfies ReviewCandidatesReport);
+}
diff --git a/src/core/brain/sync-lockfile.ts b/src/core/brain/sync-lockfile.ts
new file mode 100644
index 00000000..e6636d5c
--- /dev/null
+++ b/src/core/brain/sync-lockfile.ts
@@ -0,0 +1,168 @@
+/**
+ * Synchronous lockfile primitive for the brain write path.
+ *
+ * Pay Memory locks through `proper-lockfile` (async). The brain write
+ * path is sync end-to-end (`writePreference`, `dream`, `moveToRetired`,
+ * `writeFrontmatterAtomic`) and migrating it to async would touch every
+ * caller signature for one async-only ingredient. Instead, this module
+ * provides a tiny single-attempt sync lock built on `fs.openSync(target
+ * + '.lock', 'wx')`. EEXIST surfaces as `Error` with
+ * `.code === 'ELOCKED'`; the brain txn layer maps that to a
+ * `BrainCollisionError({ kind: 'SourceLock' })`.
+ *
+ * No retry/backoff. Contention in OSB is rare (single operator, single
+ * MCP server, dream runs from cron). When it does happen, we prefer a
+ * loud typed error over a silent retry-then-still-fail loop.
+ *
+ * Stale-lock recovery: on normal process exit the cleanup hook unlinks
+ * any still-held locks. On hard crash (SIGKILL, OOM) the `.lock` file
+ * stays on disk and the next acquire fails with ELOCKED; the brain
+ * doctor surfaces these via {@link scanStaleLocks} so an operator can
+ * remove them by hand.
+ */
+
+import {
+ closeSync,
+ mkdirSync,
+ openSync,
+ readdirSync,
+ unlinkSync,
+ writeSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface LockHandle {
+ /** Filesystem path to the underlying `.lock` file. */
+ readonly path: string;
+ /** Release the lock. Idempotent: a second call is a no-op. */
+ release(): void;
+}
+
+const LOCK_SUFFIX = ".lock";
+
+// Held locks, tracked at module scope so the exit hook can clean up.
+const heldLocks = new Set<string>();
+let exitHookInstalled = false;
+
+function ensureExitHook(): void {
+ if (exitHookInstalled) return;
+ exitHookInstalled = true;
+ process.on("exit", () => {
+ for (const lockPath of heldLocks) {
+ try {
+ unlinkSync(lockPath);
+ } catch {
+ // best-effort; the next acquire will see ELOCKED and surface it
+ }
+ }
+ heldLocks.clear();
+ });
+}
+
+/**
+ * Acquire an exclusive lock for `target`. Returns a handle whose
+ * {@link LockHandle.release} method unlinks the underlying `.lock`
+ * file. Throws `Error & { code: 'ELOCKED' }` if the lock is already
+ * held.
+ *
+ * The target file itself does NOT need to exist - first-time writes
+ * acquire the lock before creating the target. The parent directory
+ * is created on demand.
+ */
+export function acquireLockSync(target: string): LockHandle {
+ ensureExitHook();
+ const lockPath = target + LOCK_SUFFIX;
+ mkdirSync(dirname(lockPath), { recursive: true });
+
+ let fd: number;
+ try {
+ fd = openSync(lockPath, "wx", 0o644);
+ } catch (err) {
+ const e = err as NodeJS.ErrnoException;
+ if (e.code === "EEXIST") {
+ const collision: NodeJS.ErrnoException = new Error(
+ `lock busy: ${lockPath}`,
+ );
+ collision.code = "ELOCKED";
+ collision.path = lockPath;
+ throw collision;
+ }
+ throw err;
+ }
+
+ // Stamp pid + timestamp into the lock body. The contents are
+ // purely diagnostic - the doctor surface reads them when reporting
+ // stale locks. Failure to write is non-fatal: the lock semantics
+ // come from the exclusive create, not from the body.
+ try {
+ const stamp = Buffer.from(
+ `${process.pid}\n${new Date().toISOString()}\n`,
+ "utf8",
+ );
+ writeSync(fd, stamp, 0, stamp.byteLength);
+ } catch {
+ // ignore; diagnostic-only payload
+ } finally {
+ try {
+ closeSync(fd);
+ } catch {
+ // ignore
+ }
+ }
+
+ heldLocks.add(lockPath);
+ let released = false;
+ return {
+ path: lockPath,
+ release(): void {
+ if (released) return;
+ released = true;
+ heldLocks.delete(lockPath);
+ try {
+ unlinkSync(lockPath);
+ } catch {
+ // already gone (race with exit hook or manual cleanup); ignore
+ }
+ },
+ };
+}
+
+/**
+ * Walk `root` recursively and return every `.lock` file path. Used by
+ * `brain_doctor` to surface stale locks left behind by a crashed
+ * process.
+ */
+export function scanStaleLocks(root: string): string[] {
+ const out: string[] = [];
+ walkLocks(root, out);
+ return out;
+}
+
+function walkLocks(dir: string, out: string[]): void {
+ let entries;
+ try {
+ entries = readdirSync(dir, { withFileTypes: true });
+ } catch {
+ return;
+ }
+ for (const entry of entries) {
+ const full = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ walkLocks(full, out);
+ continue;
+ }
+ if (!entry.isFile()) continue;
+ if (entry.name.endsWith(LOCK_SUFFIX)) {
+ out.push(full);
+ }
+ }
+}
+
+/**
+ * Test-only: clear the held-locks tracking set without unlinking. Used
+ * to keep cross-test state from leaking when a test deliberately
+ * leaves a lock on disk for the next test to discover.
+ */
+export function _resetHeldLocksForTests(): void {
+ heldLocks.clear();
+}
diff --git a/src/core/brain/types.ts b/src/core/brain/types.ts
index 97152b45..a9ca9ded 100644
--- a/src/core/brain/types.ts
+++ b/src/core/brain/types.ts
@@ -330,6 +330,22 @@ export interface BrainPreference {
* to `false`.
*/
readonly pinned: boolean;
+ /**
+ * Brain Integrity Suite: monotonic write counter (v0.12.0). Starts
+ * at 0; incremented by `writePreferenceTxn` on every mutation.
+ * `StaleUpdate` collision fires when a writer's `expected_revision`
+ * does not match this on-disk value. Absent on pre-v0.12.0 files;
+ * readers must tolerate `undefined` and coerce to `0`.
+ */
+ readonly revision?: number;
+ /**
+ * Brain Integrity Suite: sha256 of the canonical `(principle,
+ * scope)` pair (v0.12.0). Written on promotion to `confirmed`;
+ * absent for unconfirmed and quarantine preferences. Recomputed on
+ * read by {@link verifyContentHash}; a mismatch surfaces as a
+ * `drift_detected` event in the log.
+ */
+ readonly content_hash?: string;
/** Optional wikilink to a retired pref this one replaces. */
readonly supersedes?: string;
readonly aliases?: ReadonlyArray<string>;
@@ -631,6 +647,18 @@ export interface BrainDreamConfig {
export interface BrainRetireConfig {
/** Days without evidence after which a confirmed pref retires. */
readonly stale_evidence_days: number;
+ /**
+ * Brain Integrity Suite (v0.12.0). Destructive-from-confirmed gate.
+ * When set to a positive integer, the dream pass refuses to retire
+ * a confirmed (and unpinned) preference whose accumulated
+ * `applied_count + violated_count` is below this threshold. Skipped
+ * retires surface in `DreamRunSummary.gated_retires` and stay in
+ * `preferences/`. Operator-initiated retires (`user-rejected`,
+ * `merged-into`) are never gated. `undefined` (default) preserves
+ * pre-v0.12.0 behaviour where any retire that the plan computed
+ * lands on disk.
+ */
+ readonly confirmed_evidence_min_threshold?: number;
}
export interface BrainConfidenceConfig {
diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.ts
index 932b56f5..c1ebfcc7 100644
--- a/src/mcp/brain-tools.ts
+++ b/src/mcp/brain-tools.ts
@@ -76,6 +76,7 @@ import {
type DigestFormat,
} from "../core/brain/digest.ts";
import { dream } from "../core/brain/dream.ts";
+import { buildReviewCandidates } from "../core/brain/review-candidates.ts";
import { runDoctor } from "../core/brain/doctor.ts";
import { buildOperatorSummary } from "../core/brain/trust/operator-summary.ts";
import { BRAIN_ROLES } from "../core/brain/trust/role.ts";
@@ -299,6 +300,45 @@ async function toolBrainDream(
};
}
+// ----- brain_review_candidates --------------------------------------------
+
+async function toolBrainReviewCandidates(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const nowDate = coerceIsoDate(args, "now");
+ const report = buildReviewCandidates(ctx.vault, {
+ ...(nowDate ? { now: nowDate } : {}),
+ });
+ return {
+ would_create: [...report.would_create],
+ would_promote: [...report.would_promote],
+ would_retire: report.would_retire.map((r) => ({
+ id: r.id,
+ reason: r.reason,
+ })),
+ would_supersede: report.would_supersede.map((r) => ({
+ id: r.id,
+ reason: r.reason,
+ })),
+ clusters_below_threshold: report.clusters_below_threshold.map((c) => ({
+ topic: c.topic,
+ signal_count: c.signal_count,
+ distinct_agents: c.distinct_agents,
+ age_days: c.age_days,
+ failed_gates: [...c.failed_gates],
+ })),
+ gated_retires: report.gated_retires.map((g) => ({
+ pref_id: g.pref_id,
+ topic: g.topic,
+ applied_count: g.applied_count,
+ violated_count: g.violated_count,
+ threshold: g.threshold,
+ attempted_reason: g.attempted_reason,
+ })),
+ };
+}
+
// ----- brain_apply_evidence ------------------------------------------------
async function toolBrainApplyEvidence(
@@ -1428,6 +1468,23 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
},
handler: toolBrainDream,
},
+ {
+ name: "brain_review_candidates",
+ description:
+ "Read-only preview of what the next `brain_dream` invocation would do. Returns `would_create`, `would_promote`, `would_retire`, `would_supersede`, `clusters_below_threshold`, and `gated_retires` without mutating any files. Useful for agents that want to be deliberate before triggering the learning pass, or for operators inspecting the dream pass intent.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ now: {
+ type: "string",
+ description:
+ "Optional ISO-8601 timestamp used as the wall clock for the dry-run (testing / replay).",
+ },
+ },
+ additionalProperties: false,
+ },
+ handler: toolBrainReviewCandidates,
+ },
{
name: "brain_apply_evidence",
description:
diff --git a/src/mcp/instructions.ts b/src/mcp/instructions.ts
index 6b5723e4..587dff8b 100644
--- a/src/mcp/instructions.ts
+++ b/src/mcp/instructions.ts
@@ -78,6 +78,12 @@ export function buildInstructions(opts: BuildInstructionsOpts | string): string
" - brain_dream β€” runs the deterministic learning pass " +
"(clusters signals, promotes preferences, retires stale rules). " +
"Usually scheduled via cron, not invoked interactively.\n" +
+ " - brain_review_candidates β€” read-only preview of what the " +
+ "next `brain_dream` invocation would do. Returns `would_create`, " +
+ "`would_promote`, `would_retire`, `would_supersede`, " +
+ "`clusters_below_threshold`, and `gated_retires` without mutating " +
+ "any files. Use it when you want to be deliberate before " +
+ "triggering the learning pass.\n" +
" - brain_digest β€” read-only summary of the last activity " +
"window. Default format is Markdown; pass `format: \"json\"` for " +
"programmatic use.\n" +
diff --git a/tests/core/brain/content-hash.test.ts b/tests/core/brain/content-hash.test.ts
new file mode 100644
index 00000000..71cc1104
--- /dev/null
+++ b/tests/core/brain/content-hash.test.ts
@@ -0,0 +1,96 @@
+/**
+ * Content-hash helper for confirmed preferences. The hash is written
+ * into `_content_hash` on promotion and recomputed at read time; a
+ * mismatch surfaces as a `drift_detected` event (Task 4).
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+ computeContentHash,
+ verifyContentHash,
+} from "../../../src/core/brain/content-hash.ts";
+
+describe("computeContentHash", () => {
+ test("returns a 64-char lowercase hex sha256 digest", () => {
+ const hash = computeContentHash("do the right thing", "coding");
+ expect(hash).toMatch(/^[0-9a-f]{64}$/);
+ });
+
+ test("is deterministic for the same (principle, scope)", () => {
+ const a = computeContentHash("do the right thing", "coding");
+ const b = computeContentHash("do the right thing", "coding");
+ expect(a).toBe(b);
+ });
+
+ test("differs when principle differs", () => {
+ const a = computeContentHash("do A", "coding");
+ const b = computeContentHash("do B", "coding");
+ expect(a).not.toBe(b);
+ });
+
+ test("differs when scope differs", () => {
+ const a = computeContentHash("do A", "coding");
+ const b = computeContentHash("do A", "writing");
+ expect(a).not.toBe(b);
+ });
+
+ test("treats absent and empty scope the same way (both normalise to empty)", () => {
+ // The frontmatter writer never emits an empty `scope`; absent means
+ // "no scope". Hash must reflect this so a parser later reading the
+ // file (which sees scope as undefined) recomputes the same digest.
+ const a = computeContentHash("do A");
+ const b = computeContentHash("do A", "");
+ const c = computeContentHash("do A", undefined);
+ expect(a).toBe(b);
+ expect(a).toBe(c);
+ });
+
+ test("trims leading and trailing whitespace from principle and scope", () => {
+ // Frontmatter round-trips can introduce whitespace; the hash must be
+ // stable across " text " and "text" so a no-op rewrite does not
+ // appear as drift.
+ const a = computeContentHash("the rule", "scope");
+ const b = computeContentHash(" the rule ", " scope ");
+ expect(a).toBe(b);
+ });
+});
+
+describe("verifyContentHash", () => {
+ test("returns ok=true when the stored hash matches the recomputed hash", () => {
+ const principle = "explain the why, not the what";
+ const scope = "writing";
+ const stored = computeContentHash(principle, scope);
+ const result = verifyContentHash({ principle, scope, content_hash: stored });
+ expect(result.ok).toBe(true);
+ expect(result.expected).toBe(stored);
+ expect(result.observed).toBe(stored);
+ });
+
+ test("returns ok=false when the stored hash diverges from the recomputed hash", () => {
+ const result = verifyContentHash({
+ principle: "altered principle after a hand edit",
+ scope: "coding",
+ content_hash: "0".repeat(64),
+ });
+ expect(result.ok).toBe(false);
+ expect(result.expected).toBe(computeContentHash(
+ "altered principle after a hand edit",
+ "coding",
+ ));
+ expect(result.observed).toBe("0".repeat(64));
+ });
+
+ test("returns ok=true with neutral output when content_hash is absent (legacy)", () => {
+ const result = verifyContentHash({
+ principle: "p",
+ scope: "s",
+ content_hash: undefined,
+ });
+ expect(result.ok).toBe(true);
+ // No expected/observed when no hash to compare against - the caller
+ // must not log a drift event in this case.
+ expect(result.expected).toBeUndefined();
+ expect(result.observed).toBeUndefined();
+ });
+});
diff --git a/tests/core/brain/doctor-drift.test.ts b/tests/core/brain/doctor-drift.test.ts
new file mode 100644
index 00000000..823a121d
--- /dev/null
+++ b/tests/core/brain/doctor-drift.test.ts
@@ -0,0 +1,149 @@
+/**
+ * `brain_doctor` content-hash drift surface. The integrity suite's
+ * Feature 1 reads each confirmed preference, recomputes the hash, and
+ * surfaces a `content-hash-drift` warning when the stored hash diverges
+ * from the recomputed value. Legacy preferences without `_content_hash`
+ * are silent (no false positives), and non-confirmed preferences are
+ * skipped entirely.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { computeContentHash } from "../../../src/core/brain/content-hash.ts";
+import { runDoctor } from "../../../src/core/brain/doctor.ts";
+import { brainDirs } from "../../../src/core/brain/paths.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-doctor-drift-"));
+ // Minimal Brain skeleton: _brain.yaml + _BRAIN.md + preferences/.
+ const dirs = brainDirs(vault);
+ mkdirSync(dirs.brain, { recursive: true });
+ mkdirSync(dirs.preferences, { recursive: true });
+ mkdirSync(dirs.log, { recursive: true });
+ writeFileSync(
+ join(dirs.brain, "_brain.yaml"),
+ `schema_version: 1
+primary_agent: null
+dream:
+ candidate_threshold: 2
+ unconfirmed_window_days: 7
+ contradiction_window_days: 14
+retire:
+ stale_evidence_days: 90
+confidence:
+ low_max_applied: 2
+ medium_min: 0.4
+ high_min: 0.7
+snapshots:
+ retention_count: 10
+`,
+ "utf8",
+ );
+ writeFileSync(
+ join(dirs.brain, "_BRAIN.md"),
+ "---\ntitle: Brain\n---\n",
+ "utf8",
+ );
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function writeConfirmedPref(
+ slug: string,
+ opts: {
+ principle: string;
+ scope?: string;
+ content_hash?: string;
+ },
+): string {
+ const dirs = brainDirs(vault);
+ const path = join(dirs.preferences, `pref-${slug}.md`);
+ const lines = [
+ "---",
+ "kind: brain-preference",
+ `id: pref-${slug}`,
+ 'created_at: "2026-05-01T00:00:00Z"',
+ '_confirmed_at: "2026-05-02T00:00:00Z"',
+ 'unconfirmed_until: "2026-05-08T00:00:00Z"',
+ "tags: [brain, brain/preference, brain/topic/writing]",
+ "topic: writing",
+ "_status: confirmed",
+ `principle: ${opts.principle}`,
+ "_evidenced_by: []",
+ "_applied_count: 1",
+ "_violated_count: 0",
+ '_last_evidence_at: "2026-05-02T00:00:00Z"',
+ "_confidence: high",
+ "_confidence_value: 0.8",
+ "pinned: false",
+ ];
+ if (opts.scope) lines.push(`scope: ${opts.scope}`);
+ if (opts.content_hash) lines.push(`_content_hash: ${opts.content_hash}`);
+ lines.push("---", "");
+ writeFileSync(path, lines.join("\n"), "utf8");
+ return path;
+}
+
+describe("runDoctor content-hash drift detection", () => {
+ test("emits no drift warning when stored hash matches the live principle", () => {
+ const principle = "the in-sync principle text";
+ const hash = computeContentHash(principle, undefined);
+ writeConfirmedPref("clean", { principle, content_hash: hash });
+ const result = runDoctor(vault);
+ const drift = result.warnings.filter(
+ (i) => i.code === "content-hash-drift",
+ );
+ expect(drift).toEqual([]);
+ });
+
+ test("emits a content-hash-drift warning when the stored hash diverges", () => {
+ const principle = "edited after hand modification";
+ // Stored hash is for a DIFFERENT principle.
+ const staleHash = computeContentHash("the original frozen principle", undefined);
+ const path = writeConfirmedPref("drifted", {
+ principle,
+ content_hash: staleHash,
+ });
+ const result = runDoctor(vault);
+ const drift = result.warnings.filter(
+ (i) => i.code === "content-hash-drift",
+ );
+ expect(drift).toHaveLength(1);
+ expect(drift[0]?.path).toBe(path);
+ expect(drift[0]?.message).toContain("drift");
+ });
+
+ test("does not warn on preferences without _content_hash (legacy / unconfirmed)", () => {
+ writeConfirmedPref("legacy", {
+ principle: "no hash stored at all",
+ // content_hash intentionally omitted
+ });
+ const result = runDoctor(vault);
+ const drift = result.warnings.filter(
+ (i) => i.code === "content-hash-drift",
+ );
+ expect(drift).toEqual([]);
+ });
+
+ test("scope changes are detected as drift", () => {
+ const principle = "rule with scope";
+ // Stored hash includes scope=writing; live scope is coding.
+ const staleHash = computeContentHash(principle, "writing");
+ writeConfirmedPref("scope-drift", {
+ principle,
+ scope: "coding",
+ content_hash: staleHash,
+ });
+ const result = runDoctor(vault);
+ const drift = result.warnings.filter(
+ (i) => i.code === "content-hash-drift",
+ );
+ expect(drift).toHaveLength(1);
+ });
+});
diff --git a/tests/core/brain/dream-content-hash-promotion.test.ts b/tests/core/brain/dream-content-hash-promotion.test.ts
new file mode 100644
index 00000000..d4b5bcaf
--- /dev/null
+++ b/tests/core/brain/dream-content-hash-promotion.test.ts
@@ -0,0 +1,96 @@
+/**
+ * Integration coverage for the Brain Integrity Suite Critical fix
+ * surfaced during code review: dream's promotion path must produce
+ * an on-disk `_content_hash` for every confirmed preference, so the
+ * doctor's drift detection has something to compare against.
+ *
+ * The proof is end-to-end: drive a fresh dream run that promotes an
+ * unconfirmed pref to confirmed, then read the resulting file and
+ * assert the field is present and matches the canonical hash of the
+ * live (principle, scope).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { appendApplyEvidence } from "../../../src/core/brain/apply-evidence.ts";
+import { computeContentHash } from "../../../src/core/brain/content-hash.ts";
+import { dream } from "../../../src/core/brain/dream.ts";
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { preferencePath } from "../../../src/core/brain/paths.ts";
+import { parsePreference } from "../../../src/core/brain/preference.ts";
+import { writeSignal } from "../../../src/core/brain/signal.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+
+let vault: string;
+let configHome: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-promo-hash-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-promo-hash-cfg-"));
+ const configPath = join(configHome, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+describe("dream content_hash on promotion", () => {
+ test("an unconfirmed -> confirmed transition writes _content_hash matching the live principle", () => {
+ // Three positive signals on the same topic clear the candidate
+ // threshold; dream creates an unconfirmed pref.
+ const topic = "no-magic-numbers";
+ const principle = "Replace magic numbers with named constants in production code.";
+ for (let i = 0; i < 3; i++) {
+ writeSignal(vault, {
+ topic,
+ signal: "positive",
+ agent: "claude",
+ principle,
+ created_at: `2026-05-12T0${i + 1}:00:00Z`,
+ date: "2026-05-12",
+ slug: `seed-${i}`,
+ scope: "coding",
+ });
+ }
+ const first = dream(vault, { now: new Date("2026-05-12T10:00:00Z") });
+ expect(first.new_unconfirmed).toContain(`pref-${topic}`);
+
+ // Record an apply-evidence for the new pref; the next dream pass
+ // observes the applied event and flips the pref to confirmed.
+ appendApplyEvidence(
+ vault,
+ {
+ pref_id: `pref-${topic}`,
+ artifact: "[[src/lib/example.ts]]",
+ result: "applied",
+ agent: "claude",
+ },
+ { now: new Date("2026-05-12T11:00:00Z") },
+ );
+
+ const second = dream(vault, { now: new Date("2026-05-12T12:00:00Z") });
+ expect(second.confirmed).toContain(`pref-${topic}`);
+
+ // Now the on-disk pref must carry _content_hash matching the
+ // canonical hash of (principle, scope). Without this fix the
+ // doctor's drift detection has nothing to compare against and
+ // Feature 1 silently no-ops on every real vault.
+ const path = preferencePath(vault, topic);
+ const text = readFileSync(path, "utf8");
+ expect(text).toContain("_content_hash:");
+ const parsed = parsePreference(path);
+ expect(parsed.status).toBe("confirmed");
+ expect(parsed.content_hash).toBe(
+ computeContentHash(parsed.principle, parsed.scope),
+ );
+ });
+});
diff --git a/tests/core/brain/dream-destructive-gate.test.ts b/tests/core/brain/dream-destructive-gate.test.ts
new file mode 100644
index 00000000..b32a85e1
--- /dev/null
+++ b/tests/core/brain/dream-destructive-gate.test.ts
@@ -0,0 +1,186 @@
+/**
+ * Brain Integrity Suite (v0.12.0) destructive-from-confirmed gate.
+ *
+ * Two layers of coverage:
+ *
+ * - `shouldGateRetireFromConfirmed` pure decision: every branch of
+ * the gate logic exercised in isolation. No vault, no I/O.
+ * - `dream()` smoke: when the config field is absent, the new
+ * `gated_retires` field on `DreamRunSummary` exists and reads as
+ * an empty array. This preserves the pre-v0.12.0 contract for
+ * every consumer that did not opt in to the gate.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ dream,
+ shouldGateRetireFromConfirmed,
+} from "../../../src/core/brain/dream.ts";
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import {
+ BRAIN_PREFERENCE_STATUS,
+ BRAIN_RETIRED_REASON,
+ type BrainPreference,
+} from "../../../src/core/brain/types.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+
+const pref = (overrides: Partial<BrainPreference> = {}): BrainPreference => ({
+ kind: "brain-preference",
+ id: "pref-gate-test",
+ created_at: "2026-01-01T00:00:00Z",
+ confirmed_at: "2026-01-02T00:00:00Z",
+ unconfirmed_until: "2026-01-08T00:00:00Z",
+ tags: [],
+ topic: "gating",
+ status: BRAIN_PREFERENCE_STATUS.confirmed,
+ principle: "the gated principle",
+ evidenced_by: [],
+ applied_count: 1,
+ violated_count: 0,
+ last_evidence_at: "2026-01-02T00:00:00Z",
+ confidence: "high",
+ confidence_value: 0.9,
+ pinned: false,
+ ...overrides,
+});
+
+describe("shouldGateRetireFromConfirmed", () => {
+ test("returns false when threshold is undefined (default-off)", () => {
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref(),
+ BRAIN_RETIRED_REASON.staleNoEvidence,
+ undefined,
+ ),
+ ).toBe(false);
+ });
+
+ test("returns false when threshold is 0 or negative", () => {
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref(),
+ BRAIN_RETIRED_REASON.staleNoEvidence,
+ 0,
+ ),
+ ).toBe(false);
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref(),
+ BRAIN_RETIRED_REASON.staleNoEvidence,
+ -1,
+ ),
+ ).toBe(false);
+ });
+
+ test("returns true when confirmed + unpinned + evidence below threshold", () => {
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref({ applied_count: 1, violated_count: 0 }),
+ BRAIN_RETIRED_REASON.staleNoEvidence,
+ 3,
+ ),
+ ).toBe(true);
+ });
+
+ test("returns false when accumulated evidence meets or exceeds threshold", () => {
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref({ applied_count: 3, violated_count: 0 }),
+ BRAIN_RETIRED_REASON.staleNoEvidence,
+ 3,
+ ),
+ ).toBe(false);
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref({ applied_count: 2, violated_count: 1 }),
+ BRAIN_RETIRED_REASON.staleNoEvidence,
+ 3,
+ ),
+ ).toBe(false);
+ });
+
+ test("never gates an operator-initiated user-rejected retire", () => {
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref({ applied_count: 0, violated_count: 0 }),
+ BRAIN_RETIRED_REASON.userRejected,
+ 10,
+ ),
+ ).toBe(false);
+ });
+
+ test("never gates a merge-driven retire", () => {
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref({ applied_count: 0, violated_count: 0 }),
+ BRAIN_RETIRED_REASON.mergedInto,
+ 10,
+ ),
+ ).toBe(false);
+ });
+
+ test("never gates a non-confirmed source (unconfirmed / quarantine)", () => {
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref({
+ status: BRAIN_PREFERENCE_STATUS.unconfirmed,
+ applied_count: 0,
+ violated_count: 0,
+ }),
+ BRAIN_RETIRED_REASON.expiredUnconfirmed,
+ 10,
+ ),
+ ).toBe(false);
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref({
+ status: BRAIN_PREFERENCE_STATUS.quarantine,
+ applied_count: 0,
+ violated_count: 0,
+ }),
+ BRAIN_RETIRED_REASON.quarantineViolated,
+ 10,
+ ),
+ ).toBe(false);
+ });
+
+ test("never gates a pinned preference", () => {
+ expect(
+ shouldGateRetireFromConfirmed(
+ pref({ pinned: true, applied_count: 0, violated_count: 0 }),
+ BRAIN_RETIRED_REASON.staleNoEvidence,
+ 10,
+ ),
+ ).toBe(false);
+ });
+});
+
+describe("dream() gated_retires field", () => {
+ let vault: string;
+ let configHome: string;
+
+ beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-gate-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-gate-cfg-"));
+ const configPath = join(configHome, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+ });
+ afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+ });
+
+ test("a fresh-bootstrap dream run returns gated_retires as an empty array", () => {
+ const summary = dream(vault, {
+ now: new Date("2026-05-27T12:00:00Z"),
+ dryRun: true,
+ });
+ expect(Array.isArray(summary.gated_retires)).toBe(true);
+ expect(summary.gated_retires).toEqual([]);
+ });
+});
diff --git a/tests/core/brain/dream-workrun.test.ts b/tests/core/brain/dream-workrun.test.ts
new file mode 100644
index 00000000..a688f225
--- /dev/null
+++ b/tests/core/brain/dream-workrun.test.ts
@@ -0,0 +1,165 @@
+/**
+ * Durable workrun checkpoints for the dream pass (Brain Integrity
+ * Suite, Feature 4). Each dream invocation writes a JSONL workrun
+ * file under `Brain/log/dream-runs/<run-id>.jsonl`; the file records
+ * phase transitions so a crash mid-pass leaves an inspectable trail.
+ *
+ * Recovery is non-resuming: `scanDanglingWorkruns(vault)` returns the
+ * paths of every file whose last event is neither `finalized` nor
+ * `interrupted`. The next dream pass logs a `recovered` event and the
+ * brain_doctor surfaces the dangling files as warnings.
+ *
+ * Dry-run never emits a workrun - the workrun is part of the
+ * durable side-effect surface and dry-runs must not mutate disk.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ openWorkrun,
+ scanDanglingWorkruns,
+ WORKRUN_PHASE,
+} from "../../../src/core/brain/dream-workrun.ts";
+import {
+ dreamRunsDir,
+ dreamWorkrunPath,
+} from "../../../src/core/brain/paths.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-workrun-"));
+ mkdirSync(join(vault, "Brain", "log"), { recursive: true });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function parseJsonl(path: string): Array<Record<string, unknown>> {
+ const text = readFileSync(path, "utf8");
+ return text
+ .split("\n")
+ .filter((l) => l.trim().length > 0)
+ .map((l) => JSON.parse(l) as Record<string, unknown>);
+}
+
+describe("WORKRUN_PHASE", () => {
+ test("exposes the five canonical phase strings + interrupted", () => {
+ expect(WORKRUN_PHASE.started).toBe("started");
+ expect(WORKRUN_PHASE.clusterComplete).toBe("cluster_complete");
+ expect(WORKRUN_PHASE.promoteComplete).toBe("promote_complete");
+ expect(WORKRUN_PHASE.retireComplete).toBe("retire_complete");
+ expect(WORKRUN_PHASE.finalized).toBe("finalized");
+ expect(WORKRUN_PHASE.interrupted).toBe("interrupted");
+ });
+});
+
+describe("openWorkrun + checkpoint + finalize", () => {
+ test("creates a JSONL file under Brain/log/dream-runs/ with a started line", () => {
+ const runId = "dream-2026-05-27-120000";
+ const handle = openWorkrun(vault, runId);
+ expect(handle.path).toBe(dreamWorkrunPath(vault, runId));
+ expect(existsSync(handle.path)).toBe(true);
+ const lines = parseJsonl(handle.path);
+ expect(lines).toHaveLength(1);
+ expect(lines[0]?.phase).toBe("started");
+ expect(lines[0]?.run_id).toBe(runId);
+ expect(typeof lines[0]?.at).toBe("string");
+ handle.finalize();
+ });
+
+ test("checkpoint appends one line per phase, in invocation order", () => {
+ const runId = "dream-2026-05-27-120001";
+ const handle = openWorkrun(vault, runId);
+ handle.checkpoint(WORKRUN_PHASE.clusterComplete);
+ handle.checkpoint(WORKRUN_PHASE.promoteComplete);
+ handle.checkpoint(WORKRUN_PHASE.retireComplete);
+ handle.finalize();
+ const lines = parseJsonl(handle.path);
+ expect(lines.map((l) => l.phase)).toEqual([
+ "started",
+ "cluster_complete",
+ "promote_complete",
+ "retire_complete",
+ "finalized",
+ ]);
+ });
+
+ test("finalize is idempotent (second call is a no-op)", () => {
+ const handle = openWorkrun(vault, "dream-2026-05-27-120002");
+ handle.finalize();
+ handle.finalize();
+ const lines = parseJsonl(handle.path);
+ expect(lines.filter((l) => l.phase === "finalized")).toHaveLength(1);
+ });
+
+ test("interrupt records an interrupted line with optional reason", () => {
+ const handle = openWorkrun(vault, "dream-2026-05-27-120003");
+ handle.interrupt("test crash");
+ const lines = parseJsonl(handle.path);
+ const last = lines[lines.length - 1];
+ expect(last?.phase).toBe("interrupted");
+ expect(last?.reason).toBe("test crash");
+ });
+
+ test("checkpoint after finalize is rejected (silent no-op)", () => {
+ const handle = openWorkrun(vault, "dream-2026-05-27-120004");
+ handle.finalize();
+ handle.checkpoint(WORKRUN_PHASE.promoteComplete);
+ const lines = parseJsonl(handle.path);
+ // started + finalized, nothing else
+ expect(lines.map((l) => l.phase)).toEqual(["started", "finalized"]);
+ });
+});
+
+describe("scanDanglingWorkruns", () => {
+ test("returns empty when no workruns directory exists", () => {
+ expect(scanDanglingWorkruns(vault)).toEqual([]);
+ });
+
+ test("returns empty when every workrun file ends in finalized", () => {
+ const a = openWorkrun(vault, "dream-2026-05-27-200001");
+ a.finalize();
+ const b = openWorkrun(vault, "dream-2026-05-27-200002");
+ b.checkpoint(WORKRUN_PHASE.clusterComplete);
+ b.finalize();
+ expect(scanDanglingWorkruns(vault)).toEqual([]);
+ });
+
+ test("returns empty when a workrun ends in interrupted", () => {
+ const handle = openWorkrun(vault, "dream-2026-05-27-200003");
+ handle.checkpoint(WORKRUN_PHASE.clusterComplete);
+ handle.interrupt("test");
+ expect(scanDanglingWorkruns(vault)).toEqual([]);
+ });
+
+ test("returns paths of files whose last line is neither finalized nor interrupted", () => {
+ const a = openWorkrun(vault, "dream-2026-05-27-200004");
+ a.checkpoint(WORKRUN_PHASE.clusterComplete);
+ // no finalize -> dangling
+
+ const b = openWorkrun(vault, "dream-2026-05-27-200005");
+ b.finalize();
+
+ const dangling = scanDanglingWorkruns(vault).sort();
+ expect(dangling).toEqual([a.path]);
+ });
+
+ test("tolerates malformed lines (a corrupt workrun is treated as dangling)", () => {
+ mkdirSync(dreamRunsDir(vault), { recursive: true });
+ const corruptPath = join(dreamRunsDir(vault), "dream-2026-05-27-9.jsonl");
+ writeFileSync(corruptPath, "not json at all\n", "utf8");
+ const dangling = scanDanglingWorkruns(vault);
+ expect(dangling).toContain(corruptPath);
+ });
+});
diff --git a/tests/core/brain/preference-collision.test.ts b/tests/core/brain/preference-collision.test.ts
new file mode 100644
index 00000000..a5a91cac
--- /dev/null
+++ b/tests/core/brain/preference-collision.test.ts
@@ -0,0 +1,261 @@
+/**
+ * Collision-detection expectations for `writePreferenceTxn`. Three
+ * factory functions cover the typed collision modes that depend on
+ * proposed-vs-existing state. `SourceLock` lives inside the lock
+ * acquire itself and is exercised in `preference-txn.test.ts`.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { computeContentHash } from "../../../src/core/brain/content-hash.ts";
+import {
+ brainDirs,
+ preferencePath,
+} from "../../../src/core/brain/paths.ts";
+import { writePreference } from "../../../src/core/brain/preference.ts";
+import {
+ BRAIN_COLLISION_KIND,
+ BrainCollisionError,
+ expectRevision,
+ noDuplicateWriteWithin,
+ noUnsafeShrink,
+ writePreferenceTxn,
+} from "../../../src/core/brain/preference-txn.ts";
+import {
+ BRAIN_PREFERENCE_STATUS,
+} from "../../../src/core/brain/types.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-pref-collision-"));
+ mkdirSync(brainDirs(vault).preferences, { recursive: true });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+const baseInput = (overrides: Record<string, unknown> = {}) => ({
+ slug: "collision-rule",
+ topic: "test-topic",
+ principle: "the original long-form principle text that has plenty of length",
+ created_at: "2026-05-26T12:00:00Z",
+ unconfirmed_until: "2026-06-02T12:00:00Z",
+ status: BRAIN_PREFERENCE_STATUS.confirmed,
+ confirmed_at: "2026-05-27T12:00:00Z",
+ evidenced_by: [] as ReadonlyArray<string>,
+ ...overrides,
+});
+
+describe("expectRevision", () => {
+ test("passes when stored revision matches expected", () => {
+ writePreferenceTxn(vault, baseInput({ revision: 3 }), [], {});
+ // Same revision -> ok.
+ writePreferenceTxn(
+ vault,
+ baseInput({
+ revision: 4,
+ principle: "the original long-form principle text revised slightly",
+ }),
+ [expectRevision(3)],
+ { overwrite: true },
+ );
+ const text = readFileSync(preferencePath(vault, "collision-rule"), "utf8");
+ expect(text).toContain("_revision: 4");
+ });
+
+ test("raises BrainCollisionError(StaleUpdate) when stored revision differs", () => {
+ writePreferenceTxn(vault, baseInput({ revision: 5 }), [], {});
+ let caught: unknown;
+ try {
+ writePreferenceTxn(
+ vault,
+ baseInput({ revision: 6 }),
+ [expectRevision(2)],
+ { overwrite: true },
+ );
+ } catch (err) {
+ caught = err;
+ }
+ expect(caught).toBeInstanceOf(BrainCollisionError);
+ expect((caught as BrainCollisionError).kind).toBe("StaleUpdate");
+ });
+
+ test("expectRevision treats a writePreference-baseline file (no revision stamp) as 0", () => {
+ // Bypass the txn for the baseline so the smart-default auto-stamp
+ // does not kick in. This mirrors a legacy preference written by a
+ // pre-v0.12.0 dream pass.
+ writePreference(vault, baseInput({}));
+ writePreferenceTxn(
+ vault,
+ baseInput({
+ revision: 1,
+ principle:
+ "edited principle text after the no-revision baseline",
+ }),
+ [expectRevision(0)],
+ { overwrite: true },
+ );
+ const text = readFileSync(preferencePath(vault, "collision-rule"), "utf8");
+ expect(text).toContain("_revision: 1");
+ });
+});
+
+describe("noUnsafeShrink", () => {
+ test("passes when there is no existing preference (first write)", () => {
+ writePreferenceTxn(
+ vault,
+ baseInput({ slug: "fresh", principle: "short" }),
+ [noUnsafeShrink(0.5)],
+ {},
+ );
+ expect(
+ require("node:fs").existsSync(preferencePath(vault, "fresh")),
+ ).toBe(true);
+ });
+
+ test("passes when new principle is the same length or longer", () => {
+ writePreferenceTxn(vault, baseInput({}), [], {});
+ writePreferenceTxn(
+ vault,
+ baseInput({
+ principle:
+ "the original long-form principle text that has plenty of length, now with an extension",
+ }),
+ [noUnsafeShrink(0.5)],
+ { overwrite: true },
+ );
+ });
+
+ test("raises BrainCollisionError(UnsafeShrink) when new principle drops below the ratio", () => {
+ writePreferenceTxn(vault, baseInput({}), [], {});
+ let caught: unknown;
+ try {
+ writePreferenceTxn(
+ vault,
+ baseInput({ principle: "tiny" }),
+ [noUnsafeShrink(0.5)],
+ { overwrite: true },
+ );
+ } catch (err) {
+ caught = err;
+ }
+ expect(caught).toBeInstanceOf(BrainCollisionError);
+ expect((caught as BrainCollisionError).kind).toBe("UnsafeShrink");
+ });
+
+ test("the existing on-disk content is not modified when the shrink gate fires", () => {
+ const r = writePreferenceTxn(vault, baseInput({}), [], {});
+ const before = readFileSync(r.path, "utf8");
+ try {
+ writePreferenceTxn(
+ vault,
+ baseInput({ principle: "x" }),
+ [noUnsafeShrink(0.5)],
+ { overwrite: true },
+ );
+ } catch {
+ // expected
+ }
+ const after = readFileSync(r.path, "utf8");
+ expect(after).toBe(before);
+ });
+});
+
+describe("noDuplicateWriteWithin", () => {
+ test("passes when the existing preference has no content_hash (legacy)", () => {
+ writePreferenceTxn(vault, baseInput({}), [], {});
+ writePreferenceTxn(
+ vault,
+ baseInput({
+ principle: "the original long-form principle text that has plenty of length",
+ last_evidence_at: "2026-05-26T12:00:00Z",
+ }),
+ [noDuplicateWriteWithin(60_000, () => new Date("2026-05-26T12:00:30Z"))],
+ { overwrite: true },
+ );
+ });
+
+ test("raises BrainCollisionError(DuplicateWrite) when content_hash matches AND last evidence is within the window", () => {
+ const principle = "the original long-form principle text that has plenty of length";
+ const hash = computeContentHash(principle, undefined);
+ writePreferenceTxn(
+ vault,
+ baseInput({
+ principle,
+ content_hash: hash,
+ last_evidence_at: "2026-05-26T12:00:00Z",
+ }),
+ [],
+ {},
+ );
+
+ let caught: unknown;
+ try {
+ writePreferenceTxn(
+ vault,
+ baseInput({
+ principle,
+ content_hash: hash,
+ last_evidence_at: "2026-05-26T12:00:00Z",
+ }),
+ [noDuplicateWriteWithin(60_000, () => new Date("2026-05-26T12:00:30Z"))],
+ { overwrite: true },
+ );
+ } catch (err) {
+ caught = err;
+ }
+ expect(caught).toBeInstanceOf(BrainCollisionError);
+ expect((caught as BrainCollisionError).kind).toBe("DuplicateWrite");
+ });
+
+ test("passes when the window has elapsed even if content_hash matches", () => {
+ const principle = "the original long-form principle text that has plenty of length";
+ const hash = computeContentHash(principle, undefined);
+ writePreferenceTxn(
+ vault,
+ baseInput({
+ principle,
+ content_hash: hash,
+ last_evidence_at: "2026-05-26T12:00:00Z",
+ }),
+ [],
+ {},
+ );
+
+ writePreferenceTxn(
+ vault,
+ baseInput({
+ principle,
+ content_hash: hash,
+ last_evidence_at: "2026-05-26T13:00:00Z",
+ }),
+ [
+ noDuplicateWriteWithin(
+ 60_000,
+ // 70s elapsed since the existing last_evidence_at
+ () => new Date("2026-05-26T12:01:10Z"),
+ ),
+ ],
+ { overwrite: true },
+ );
+ });
+});
+
+describe("BRAIN_COLLISION_KIND completeness", () => {
+ test("all four discriminants are covered by either lock acquire or an expectation factory", () => {
+ // Sanity assertion - guards against silent renames of the kind table.
+ const expected = [
+ "DuplicateWrite",
+ "SourceLock",
+ "StaleUpdate",
+ "UnsafeShrink",
+ ] as const;
+ const actual = [...Object.values(BRAIN_COLLISION_KIND)].sort();
+ const expectedSorted = [...expected].sort();
+ expect(actual).toEqual(expectedSorted);
+ });
+});
diff --git a/tests/core/brain/preference-integrity-fields.test.ts b/tests/core/brain/preference-integrity-fields.test.ts
new file mode 100644
index 00000000..d50c2b94
--- /dev/null
+++ b/tests/core/brain/preference-integrity-fields.test.ts
@@ -0,0 +1,156 @@
+/**
+ * Frontmatter emission + parse coverage for the two integrity fields
+ * added by the brain integrity suite:
+ *
+ * - `_revision` (always emitted; defaults to 0 when caller omits)
+ * - `_content_hash` (only emitted when caller supplies one, which
+ * dream does on every promotion to `confirmed`)
+ *
+ * Round-trip invariant: `parsePreference(writePreference(input))` must
+ * surface the same `revision` and `content_hash` values the writer
+ * received.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { computeContentHash } from "../../../src/core/brain/content-hash.ts";
+import {
+ parsePreference,
+ writePreference,
+ type WritePreferenceInput,
+} from "../../../src/core/brain/preference.ts";
+import {
+ BRAIN_CONFIDENCE,
+ BRAIN_PREFERENCE_STATUS,
+} from "../../../src/core/brain/types.ts";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-pref-integrity-"));
+ mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function basePref(
+ slug: string,
+ overrides: Partial<WritePreferenceInput> = {},
+): WritePreferenceInput {
+ return {
+ slug,
+ topic: "writing",
+ principle: `Principle for ${slug}`,
+ created_at: "2026-05-26T12:00:00Z",
+ unconfirmed_until: "2026-06-02T12:00:00Z",
+ status: BRAIN_PREFERENCE_STATUS.unconfirmed,
+ evidenced_by: [],
+ pinned: false,
+ confidence: BRAIN_CONFIDENCE.low,
+ ...overrides,
+ };
+}
+
+describe("writePreference - _revision emission", () => {
+ test("does NOT emit _revision when caller omits the field (legacy byte-identical)", () => {
+ const res = writePreference(vault, basePref("rev-default"));
+ const text = readFileSync(res.path, "utf8");
+ expect(text).not.toContain("_revision:");
+ });
+
+ test("emits the supplied revision when caller provides one", () => {
+ const res = writePreference(
+ vault,
+ basePref("rev-supplied", { revision: 7 }),
+ );
+ const text = readFileSync(res.path, "utf8");
+ expect(text).toContain("_revision: 7");
+ });
+
+ test("parsePreference reads _revision back as a number", () => {
+ const res = writePreference(
+ vault,
+ basePref("rev-roundtrip", { revision: 12 }),
+ );
+ const parsed = parsePreference(res.path);
+ expect(parsed.revision).toBe(12);
+ });
+
+ test("parsePreference defaults revision to 0 when the field is absent on disk", () => {
+ // Hand-write a frontmatter without _revision to simulate a legacy
+ // file - the reader must not crash and must report 0.
+ const path = join(vault, "Brain", "preferences", "pref-legacy.md");
+ require("node:fs").writeFileSync(
+ path,
+ `---
+kind: brain-preference
+id: pref-legacy
+created_at: 2026-01-01T00:00:00Z
+_confirmed_at: "null"
+unconfirmed_until: 2026-01-08T00:00:00Z
+tags: [brain, brain/preference, brain/topic/writing]
+topic: writing
+_status: unconfirmed
+principle: legacy principle
+_evidenced_by: []
+_applied_count: 0
+_violated_count: 0
+_last_evidence_at: "null"
+_confidence: low
+_confidence_value: "null"
+pinned: false
+---
+`,
+ "utf8",
+ );
+ const parsed = parsePreference(path);
+ expect(parsed.revision).toBe(0);
+ });
+});
+
+describe("writePreference - _content_hash emission", () => {
+ test("does NOT emit _content_hash when caller omits the field", () => {
+ const res = writePreference(vault, basePref("hash-absent"));
+ const text = readFileSync(res.path, "utf8");
+ expect(text).not.toContain("_content_hash:");
+ });
+
+ test("emits the supplied _content_hash verbatim", () => {
+ const hash = computeContentHash("Principle for hash-present", undefined);
+ const res = writePreference(
+ vault,
+ basePref("hash-present", {
+ status: BRAIN_PREFERENCE_STATUS.confirmed,
+ confirmed_at: "2026-05-26T13:00:00Z",
+ content_hash: hash,
+ }),
+ );
+ const text = readFileSync(res.path, "utf8");
+ expect(text).toContain(`_content_hash: ${hash}`);
+ });
+
+ test("parsePreference reads _content_hash back as a string", () => {
+ const hash = computeContentHash("Principle for hash-roundtrip", "writing");
+ const res = writePreference(
+ vault,
+ basePref("hash-roundtrip", {
+ scope: "writing",
+ status: BRAIN_PREFERENCE_STATUS.confirmed,
+ confirmed_at: "2026-05-26T13:00:00Z",
+ content_hash: hash,
+ }),
+ );
+ const parsed = parsePreference(res.path);
+ expect(parsed.content_hash).toBe(hash);
+ });
+
+ test("parsePreference leaves content_hash undefined when the field is absent on disk", () => {
+ const res = writePreference(vault, basePref("hash-missing"));
+ const parsed = parsePreference(res.path);
+ expect(parsed.content_hash).toBeUndefined();
+ });
+});
diff --git a/tests/core/brain/preference-txn.test.ts b/tests/core/brain/preference-txn.test.ts
new file mode 100644
index 00000000..13800e60
--- /dev/null
+++ b/tests/core/brain/preference-txn.test.ts
@@ -0,0 +1,222 @@
+/**
+ * `writePreferenceTxn` - the single chokepoint that wraps every
+ * preference write. Acquires the sync lock, re-reads the current
+ * file state, runs an expectations chain that can raise typed
+ * `BrainCollisionError`, then mutates via `writeFrontmatterAtomic`.
+ */
+
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ brainDirs,
+ preferencePath,
+} from "../../../src/core/brain/paths.ts";
+import { parsePreference } from "../../../src/core/brain/preference.ts";
+import {
+ BrainCollisionError,
+ BRAIN_COLLISION_KIND,
+ writePreferenceTxn,
+ type WritePreferenceExpectation,
+} from "../../../src/core/brain/preference-txn.ts";
+import { acquireLockSync } from "../../../src/core/brain/sync-lockfile.ts";
+import { BRAIN_PREFERENCE_STATUS } from "../../../src/core/brain/types.ts";
+
+let tmpRoot: string;
+let vault: string;
+
+beforeEach(() => {
+ tmpRoot = mkdtempSync(join(tmpdir(), "osb-pref-txn-"));
+ vault = tmpRoot;
+ // Ensure Brain/preferences/ exists so the writer can drop the file.
+ require("node:fs").mkdirSync(brainDirs(vault).preferences, {
+ recursive: true,
+ });
+});
+
+afterAll(() => {
+ if (tmpRoot) rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+const baseInput = (overrides: Record<string, unknown> = {}) => ({
+ slug: "test-rule",
+ topic: "test-topic",
+ principle: "do the right thing in production code",
+ created_at: "2026-05-26T12:00:00Z",
+ unconfirmed_until: "2026-06-02T12:00:00Z",
+ status: BRAIN_PREFERENCE_STATUS.unconfirmed,
+ evidenced_by: [] as ReadonlyArray<string>,
+ ...overrides,
+});
+
+describe("BRAIN_COLLISION_KIND", () => {
+ test("exposes the four discriminant string values", () => {
+ expect(BRAIN_COLLISION_KIND.staleUpdate).toBe("StaleUpdate");
+ expect(BRAIN_COLLISION_KIND.unsafeShrink).toBe("UnsafeShrink");
+ expect(BRAIN_COLLISION_KIND.sourceLock).toBe("SourceLock");
+ expect(BRAIN_COLLISION_KIND.duplicateWrite).toBe("DuplicateWrite");
+ });
+});
+
+describe("BrainCollisionError", () => {
+ test("kind field is preserved on instances", () => {
+ const err = new BrainCollisionError(
+ BRAIN_COLLISION_KIND.staleUpdate,
+ "test message",
+ );
+ expect(err).toBeInstanceOf(Error);
+ expect(err.kind).toBe("StaleUpdate");
+ expect(err.name).toBe("BrainCollisionError");
+ expect(err.message).toBe("test message");
+ });
+});
+
+describe("writePreferenceTxn", () => {
+ test("with empty expectations writes a preference identical to writePreference", () => {
+ const result = writePreferenceTxn(vault, baseInput(), [], {});
+ expect(result.id).toBe("pref-test-rule");
+ expect(existsSync(result.path)).toBe(true);
+ // Lock file must be cleaned up after the txn returns.
+ expect(existsSync(result.path + ".lock")).toBe(false);
+ const parsed = parsePreference(result.path);
+ expect(parsed.principle).toBe("do the right thing in production code");
+ expect(parsed.topic).toBe("test-topic");
+ });
+
+ test("raises BrainCollisionError(SourceLock) when the lock is already held", () => {
+ const path = preferencePath(vault, "held-rule");
+ const handle = acquireLockSync(path);
+ try {
+ let caught: unknown;
+ try {
+ writePreferenceTxn(vault, baseInput({ slug: "held-rule" }), [], {});
+ } catch (err) {
+ caught = err;
+ }
+ expect(caught).toBeInstanceOf(BrainCollisionError);
+ expect((caught as BrainCollisionError).kind).toBe("SourceLock");
+ } finally {
+ handle.release();
+ }
+ });
+
+ test("runs expectations chain in order; first failure short-circuits", () => {
+ // First write to seed the on-disk state.
+ writePreferenceTxn(vault, baseInput({ slug: "chain-rule" }), [], {});
+
+ const calls: string[] = [];
+ const ok: WritePreferenceExpectation = () => {
+ calls.push("ok");
+ };
+ const fail: WritePreferenceExpectation = () => {
+ calls.push("fail");
+ throw new BrainCollisionError(
+ BRAIN_COLLISION_KIND.staleUpdate,
+ "deliberate failure",
+ );
+ };
+ const never: WritePreferenceExpectation = () => {
+ calls.push("never");
+ };
+
+ let caught: unknown;
+ try {
+ writePreferenceTxn(
+ vault,
+ baseInput({
+ slug: "chain-rule",
+ principle: "updated principle text",
+ }),
+ [ok, fail, never],
+ { overwrite: true },
+ );
+ } catch (err) {
+ caught = err;
+ }
+ expect(caught).toBeInstanceOf(BrainCollisionError);
+ expect((caught as BrainCollisionError).kind).toBe("StaleUpdate");
+ expect(calls).toEqual(["ok", "fail"]); // `never` was not invoked
+ });
+
+ test("releases the lock even when an expectation throws", () => {
+ writePreferenceTxn(vault, baseInput({ slug: "release-rule" }), [], {});
+ const failingExpectation: WritePreferenceExpectation = () => {
+ throw new BrainCollisionError(
+ BRAIN_COLLISION_KIND.duplicateWrite,
+ "blocked",
+ );
+ };
+
+ let caught: unknown;
+ try {
+ writePreferenceTxn(
+ vault,
+ baseInput({ slug: "release-rule" }),
+ [failingExpectation],
+ { overwrite: true },
+ );
+ } catch (err) {
+ caught = err;
+ }
+ expect(caught).toBeInstanceOf(BrainCollisionError);
+
+ // Lock must be released even though the write was aborted.
+ const lockPath = preferencePath(vault, "release-rule") + ".lock";
+ expect(existsSync(lockPath)).toBe(false);
+
+ // A follow-up write with empty expectations must succeed.
+ const ok = writePreferenceTxn(
+ vault,
+ baseInput({ slug: "release-rule" }),
+ [],
+ { overwrite: true },
+ );
+ expect(existsSync(ok.path)).toBe(true);
+ });
+
+ test("expectation receives the existing preference when overwriting", () => {
+ writePreferenceTxn(
+ vault,
+ baseInput({ slug: "ctx-rule", principle: "original principle text" }),
+ [],
+ {},
+ );
+
+ const observed: { principle: string | null } = { principle: null };
+ const inspect: WritePreferenceExpectation = (ctx) => {
+ observed.principle = ctx.existing?.principle ?? null;
+ };
+
+ writePreferenceTxn(
+ vault,
+ baseInput({ slug: "ctx-rule", principle: "replacement principle text" }),
+ [inspect],
+ { overwrite: true },
+ );
+ expect(observed.principle).toBe("original principle text");
+ });
+
+ test("expectation context shows existing=null on first write", () => {
+ const observed: { existing: unknown } = { existing: "unset" };
+ const inspect: WritePreferenceExpectation = (ctx) => {
+ observed.existing = ctx.existing;
+ };
+ writePreferenceTxn(vault, baseInput({ slug: "first-rule" }), [inspect], {});
+ expect(observed.existing).toBeNull();
+ });
+
+ test("file bytes match what writePreference would have produced (no txn overhead)", () => {
+ const result = writePreferenceTxn(
+ vault,
+ baseInput({ slug: "bytewise-rule", principle: "exact bytes please" }),
+ [],
+ {},
+ );
+ const text = readFileSync(result.path, "utf8");
+ expect(text).toContain("principle: exact bytes please");
+ expect(text).toContain("kind: brain-preference");
+ expect(text).toContain("_status: unconfirmed");
+ });
+});
diff --git a/tests/core/brain/review-candidates.test.ts b/tests/core/brain/review-candidates.test.ts
new file mode 100644
index 00000000..df036521
--- /dev/null
+++ b/tests/core/brain/review-candidates.test.ts
@@ -0,0 +1,68 @@
+/**
+ * `buildReviewCandidates` - read-only projection over what the next
+ * dream pass would do. The helper drives `dream({ dryRun: true })`
+ * so no persistent state mutates between invocations.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { dreamRunsDir } from "../../../src/core/brain/paths.ts";
+import { buildReviewCandidates } from "../../../src/core/brain/review-candidates.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+
+let vault: string;
+let configHome: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-rc-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-rc-cfg-"));
+ const configPath = join(configHome, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+describe("buildReviewCandidates", () => {
+ test("returns a frozen report with all six top-level fields", () => {
+ const r = buildReviewCandidates(vault, { now: new Date("2026-05-27T12:00:00Z") });
+ expect(Object.isFrozen(r)).toBe(true);
+ expect(Array.isArray(r.would_create)).toBe(true);
+ expect(Array.isArray(r.would_promote)).toBe(true);
+ expect(Array.isArray(r.would_retire)).toBe(true);
+ expect(Array.isArray(r.would_supersede)).toBe(true);
+ expect(Array.isArray(r.clusters_below_threshold)).toBe(true);
+ expect(Array.isArray(r.gated_retires)).toBe(true);
+ });
+
+ test("returns empty arrays on a fresh-bootstrap vault", () => {
+ const r = buildReviewCandidates(vault, { now: new Date("2026-05-27T12:00:00Z") });
+ expect(r.would_create).toEqual([]);
+ expect(r.would_promote).toEqual([]);
+ expect(r.would_retire).toEqual([]);
+ expect(r.would_supersede).toEqual([]);
+ expect(r.clusters_below_threshold).toEqual([]);
+ expect(r.gated_retires).toEqual([]);
+ });
+
+ test("does NOT create a workrun file (dry-run path)", () => {
+ buildReviewCandidates(vault, { now: new Date("2026-05-27T12:00:00Z") });
+ const dir = dreamRunsDir(vault);
+ if (existsSync(dir)) {
+ const entries = readdirSync(dir);
+ expect(entries).toEqual([]);
+ }
+ });
+
+ test("invoked twice in a row produces identical output (idempotent)", () => {
+ const a = buildReviewCandidates(vault, { now: new Date("2026-05-27T12:00:00Z") });
+ const b = buildReviewCandidates(vault, { now: new Date("2026-05-27T12:00:00Z") });
+ expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+ });
+});
diff --git a/tests/core/brain/sync-lockfile.test.ts b/tests/core/brain/sync-lockfile.test.ts
new file mode 100644
index 00000000..9fa27f55
--- /dev/null
+++ b/tests/core/brain/sync-lockfile.test.ts
@@ -0,0 +1,118 @@
+/**
+ * Sync lockfile primitive for the brain write path. Single-attempt
+ * exclusive create via `fs.openSync(target + '.lock', 'wx')`. Collisions
+ * surface as a regular Error with `.code === 'ELOCKED'`; the brain
+ * txn layer maps that to a `BrainCollisionError({ kind: 'SourceLock' })`.
+ */
+
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ acquireLockSync,
+ scanStaleLocks,
+} from "../../../src/core/brain/sync-lockfile.ts";
+
+let tmpRoot: string;
+
+beforeEach(() => {
+ tmpRoot = mkdtempSync(join(tmpdir(), "osb-sync-lock-"));
+});
+
+afterAll(() => {
+ if (tmpRoot) rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("acquireLockSync", () => {
+ test("creates a .lock sibling file and release removes it", () => {
+ const target = join(tmpRoot, "pref-foo.md");
+ writeFileSync(target, "---\nkind: brain-preference\n---\n");
+
+ const handle = acquireLockSync(target);
+ expect(handle.path).toBe(target + ".lock");
+ expect(existsSync(target + ".lock")).toBe(true);
+
+ handle.release();
+ expect(existsSync(target + ".lock")).toBe(false);
+ });
+
+ test("throws Error with code ELOCKED when the lock is already held", () => {
+ const target = join(tmpRoot, "pref-bar.md");
+ writeFileSync(target, "---\nkind: brain-preference\n---\n");
+
+ const first = acquireLockSync(target);
+ try {
+ let caught: unknown;
+ try {
+ acquireLockSync(target);
+ } catch (err) {
+ caught = err;
+ }
+ expect(caught).toBeInstanceOf(Error);
+ expect((caught as NodeJS.ErrnoException).code).toBe("ELOCKED");
+ } finally {
+ first.release();
+ }
+ });
+
+ test("after release, target is acquirable again", () => {
+ const target = join(tmpRoot, "pref-baz.md");
+ writeFileSync(target, "---\n---\n");
+
+ const first = acquireLockSync(target);
+ first.release();
+ const second = acquireLockSync(target);
+ expect(existsSync(target + ".lock")).toBe(true);
+ second.release();
+ });
+
+ test("release is idempotent (second call is a no-op)", () => {
+ const target = join(tmpRoot, "pref-idem.md");
+ writeFileSync(target, "");
+ const handle = acquireLockSync(target);
+ handle.release();
+ handle.release(); // must not throw
+ expect(existsSync(target + ".lock")).toBe(false);
+ });
+
+ test("acquire creates the lock even when the target file does not exist", () => {
+ // The brain txn path needs to be able to lock the target before the
+ // file is created (first-time write). The lock primitive must not
+ // require the target to exist.
+ const target = join(tmpRoot, "pref-new.md");
+ const handle = acquireLockSync(target);
+ try {
+ expect(existsSync(target + ".lock")).toBe(true);
+ expect(existsSync(target)).toBe(false);
+ } finally {
+ handle.release();
+ }
+ });
+});
+
+describe("scanStaleLocks", () => {
+ test("returns paths of every .lock file under the given root", () => {
+ const a = join(tmpRoot, "pref-a.md");
+ const b = join(tmpRoot, "sub", "pref-b.md");
+ writeFileSync(a, "");
+ const ha = acquireLockSync(a);
+ // Manually drop a lock under a subdirectory to exercise the walk.
+ const subDir = join(tmpRoot, "sub");
+ require("node:fs").mkdirSync(subDir, { recursive: true });
+ writeFileSync(b + ".lock", "");
+
+ const found = scanStaleLocks(tmpRoot).sort();
+ expect(found).toContain(a + ".lock");
+ expect(found).toContain(b + ".lock");
+
+ ha.release();
+ require("node:fs").unlinkSync(b + ".lock");
+ });
+
+ test("returns an empty array when no locks exist", () => {
+ const found = scanStaleLocks(tmpRoot);
+ expect(found).toEqual([]);
+ });
+});
diff --git a/tests/mcp/brain-review-candidates.test.ts b/tests/mcp/brain-review-candidates.test.ts
new file mode 100644
index 00000000..6fc394f5
--- /dev/null
+++ b/tests/mcp/brain-review-candidates.test.ts
@@ -0,0 +1,58 @@
+/**
+ * `brain_review_candidates` MCP tool wiring. Exercises the tool
+ * through the same path the MCP server uses: tool lookup, handler
+ * invocation, response shape.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { BRAIN_TOOLS } from "../../src/mcp/brain-tools.ts";
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+
+let vault: string;
+let configHome: string;
+// Minimal shape - the brain_review_candidates handler only reads
+// `ctx.vault`. We construct a structural match and cast to the
+// handler's parameter type at the call site.
+let ctx: { vault: string; configPath: string };
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-rc-mcp-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-rc-mcp-cfg-"));
+ const configPath = join(configHome, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+ ctx = { vault, configPath };
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+describe("brain_review_candidates MCP tool", () => {
+ test("is registered in BRAIN_TOOLS", () => {
+ const tool = BRAIN_TOOLS.find((t) => t.name === "brain_review_candidates");
+ expect(tool).toBeDefined();
+ expect(tool?.description).toContain("preview");
+ expect(tool?.inputSchema).toBeDefined();
+ });
+
+ test("returns the six fields, all empty on a fresh vault", async () => {
+ const tool = BRAIN_TOOLS.find((t) => t.name === "brain_review_candidates");
+ expect(tool).toBeDefined();
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const out = (await tool!.handler(ctx as any, {
+ now: "2026-05-27T12:00:00Z",
+ })) as Record<string, unknown>;
+ expect(out["would_create"]).toEqual([]);
+ expect(out["would_promote"]).toEqual([]);
+ expect(out["would_retire"]).toEqual([]);
+ expect(out["would_supersede"]).toEqual([]);
+ expect(out["clusters_below_threshold"]).toEqual([]);
+ expect(out["gated_retires"]).toEqual([]);
+ });
+});
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index 0cc6eba8..716e0eea 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -165,6 +165,7 @@ describe("tool listing", () => {
// brain_daily_brief / brain_weekly_synthesis added in v0.10.18).
"brain_feedback",
"brain_dream",
+ "brain_review_candidates",
"brain_apply_evidence",
"brain_note",
"brain_context",
@@ -381,11 +382,12 @@ describe("stdio loop", () => {
const list = JSON.parse(lines[1]!);
expect(init.id).toBe(1);
expect(list.id).toBe(2);
- // v0.10.18: 3 core + 19 Brain (brain_timeline /
+ // v0.12.0: 3 core + 20 Brain (brain_review_candidates added in
+ // v0.12.0 Brain Integrity Suite, brain_timeline /
// brain_belief_evolution / brain_stale_scan / brain_daily_brief /
// brain_weekly_synthesis added v0.10.18)
- // + 8 Pay Memory + 1 Search = 31.
- expect(list.result.tools.length).toBe(31);
+ // + 8 Pay Memory + 1 Search = 32.
+ expect(list.result.tools.length).toBe(32);
});
test("returns parse error for invalid JSON", async () => {