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

feat: hands-off post-upgrade migration (v0.31.2) (#61)

Sol Aitken6fbab0b553e7
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index d1049238..8c59ead8 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.31.1",
+ "version": "0.31.2",
"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 dffd71f9..2b737c31 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.31.1",
+ "version": "0.31.2",
"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 c5b092da..a083eb84 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,40 @@ 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.31.2] - 2026-06-01
+
+Hands-off post-upgrade migration. After an update, the plugin now brings an
+already-initialised vault current by itself - no manual `o2b search reindex` or
+`o2b brain upgrade`. Completes the "an update must never need manual steps" goal
+started in 0.31.1.
+
+### Fixed
+
+- Search self-heals a stale or missing index on read: instead of throwing
+ `SCHEMA_MISMATCH` / `INDEX_MISSING` (which told the user to run
+ `o2b search reindex` / `o2b search index`), the read path rebuilds the index
+ once and retries.
+
+### Added
+
+- `ensureVaultCurrent`: a state-driven, best-effort maintenance pass run at
+ `o2b mcp` startup (the path Hermes/Claude Code/Codex all spawn) and on the
+ Claude Code `SessionStart` hook. On an already-initialised vault it migrates a
+ stale `_brain.yaml`/`_BRAIN.md` (snapshot-backed, additive) and rebuilds a
+ stale or missing search index in the background. It never throws and never
+ blocks startup.
+
+### Notes
+
+- Migration is **state-driven, not version-stamped**: each step keys off actual
+ on-disk state (index `schema_version`, `_brain.yaml` pending plan, dir
+ existence), so a Syncthing-synced vault cannot let one device mark a migration
+ done and make another skip its own per-device reindex. The behavior is locked
+ by `tests/core/search/self-heal.test.ts` and
+ `tests/core/maintenance/ensure-current.test.ts`.
+- The manual `o2b search reindex` / `o2b brain upgrade` commands remain for
+ explicit use; auto-migration reuses their logic.
+
## [0.31.1] - 2026-06-01
Update-resilience and repair. Plugin updates no longer strand the hooks or
@@ -3745,6 +3779,7 @@ plugin config (vault field)`, and exits with a clear
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[0.31.2]: https://github.com/itechmeat/open-second-brain/compare/v0.31.1...v0.31.2
[0.31.1]: https://github.com/itechmeat/open-second-brain/compare/v0.31.0...v0.31.1
[0.30.0]: https://github.com/itechmeat/open-second-brain/compare/v0.29.0...v0.30.0
[0.29.0]: https://github.com/itechmeat/open-second-brain/compare/v0.28.0...v0.29.0
diff --git a/docs/brainstorm/auto-migrate-on-upgrade/design.md b/docs/brainstorm/auto-migrate-on-upgrade/design.md
new file mode 100644
index 00000000..e3df6946
--- /dev/null
+++ b/docs/brainstorm/auto-migrate-on-upgrade/design.md
@@ -0,0 +1,106 @@
+# Auto-migrate on upgrade - hands-off self-healing after a version bump
+
+**Status:** draft
+**Author:** claude-vps-agent (via feature-release-playbook)
+**Audience:** implementation
+
+## Problem statement
+
+After upgrading the plugin, a user currently has to run manual commands before
+Open Second Brain works correctly again. v0.31.1 fixed the hook/symlink class;
+this completes the job for the rest. A user should never run a maintenance
+command after an update - the plugin must detect that its state is behind the
+running version and bring itself current automatically.
+
+## Manual-after-upgrade steps to eliminate (audited)
+
+- **Search index schema mismatch.** `store.ts` read path throws
+ `SCHEMA_MISMATCH ... Run: o2b search reindex` (and `not initialised ... Run: o2b
+ search index`). Write opens auto-migrate additively, but reads error and an
+ additive migration does not re-chunk content (e.g. the CJK column).
+- **Brain release-owned files.** `_brain.yaml` / `_BRAIN.md` only migrate via the
+ manual `o2b brain upgrade --apply` (additive, snapshot-backed).
+- **Embeddings on model/dimension change.** `ensureEmbeddingModel` auto-clears
+ vectors (lossy); repopulation needs `o2b search reindex --embeddings`.
+- **Missing Brain subdirectories** on vaults created by older versions.
+
+Root cause: no upgrade detection. `SERVER_VERSION` is never compared to any
+persisted state; auto-migration exists only on the search WRITE path.
+
+## Chosen approach
+
+Two complementary, idempotent, best-effort parts.
+
+### A. Lazy search self-heal (removes the user-facing error directly)
+
+In the search read path, on `SCHEMA_MISMATCH` or `not initialised`, transparently
+rebuild the index once and retry instead of throwing. Search then never requires
+a manual `reindex`. First search after an upgrade is slower; subsequent ones are
+normal.
+
+### B. State-driven `ensureVaultCurrent(vault)` at startup
+
+Run a best-effort maintenance pass at a universal entry point (MCP server boot -
+Hermes/Claude Code/Codex all spawn `o2b mcp`; also wired into the SessionStart
+hook). It NEVER throws and NEVER blocks startup on slow work:
+
+1. Ensure required Brain directories exist (idempotent).
+2. Brain managed-file upgrade: if `planUpgrade(vault)` reports pending changes,
+ `applyUpgrade` (snapshot + log; additive; user content untouched). No-op when
+ nothing is pending.
+3. Search: if the index is missing-but-vault-has-content, or its
+ `schema_version` != `LATEST_SCHEMA_VERSION`, trigger a reindex in the
+ BACKGROUND (does not block boot). Embeddings repopulate in the same reindex
+ when semantic search is configured.
+
+### Why state-driven, not a version stamp
+
+The vault is Syncthing-synced across devices, so a stamp written into the vault
+would let one device mark a migration "done" and make another device skip its own
+(per-device) work - most importantly the per-device search reindex. So each step
+keys off ACTUAL state instead:
+- search reindex <- per-device index `index_state.schema_version` (authoritative,
+ per-device);
+- brain upgrade <- `_brain.yaml` pending-changes plan (idempotent across synced
+ devices);
+- dirs <- existence.
+
+These checks are cheap reads (single-digit ms), safe to run on every boot; only a
+real migration does work. This is strictly more correct than a version stamp: it
+also handles interrupted migrations and downgrades. An OPTIONAL per-device version
+note (in `~/.config/open-second-brain/`, never in the vault) may be written for
+logging/telemetry only - never for correctness gating.
+
+## Scope
+
+- `src/core/maintenance/ensure-current.ts` (new): `ensureVaultCurrent(vault, opts)`.
+- Search read path: lazy rebuild-and-retry on `SCHEMA_MISMATCH` / not-initialised.
+- Background reindex helper (non-blocking, single-flight via the existing index lock).
+- Wire `ensureVaultCurrent` into MCP boot (`src/mcp/server.ts`) and the
+ SessionStart hook (`hooks/active-inject.ts`).
+- Docs: `docs/updating.md` - "updates are automatic; no manual reindex/brain upgrade".
+
+## Out of scope
+
+- First-time `o2b init` / plugin config bootstrap (that is install, not upgrade).
+- Changing the manual `o2b brain upgrade` / `o2b search reindex` commands (kept for
+ explicit use); auto-migration reuses their logic.
+
+## Design decisions
+
+- **Never throw, never block.** All maintenance is best-effort; failures log to
+ stderr and the runtime proceeds. Slow work (reindex) runs in the background.
+- **Single-flight.** Concurrent runtimes booting at once must not double-migrate;
+ rely on the search index lock and brain snapshot/upgrade idempotency; skip if a
+ lock is held.
+- **Reuse existing machinery** (`planUpgrade`/`applyUpgrade`, `reindexVault`,
+ `bootstrapBrain` dir creation) rather than reimplementing.
+
+## Risks and open questions
+
+- Auto-applying the brain managed-file upgrade writes to the user's vault on boot.
+ Mitigated by snapshot + log + additive-only merge; matches the chosen hands-off
+ behavior.
+- Background reindex must be fire-and-forget without leaving a half-written index;
+ `reindexVault` already builds atomically (temp + rename) under a lock.
+- MCP boot must not be delayed; the reindex is detached, the cheap checks are sync.
diff --git a/docs/brainstorm/auto-migrate-on-upgrade/plan.md b/docs/brainstorm/auto-migrate-on-upgrade/plan.md
new file mode 100644
index 00000000..244964f2
--- /dev/null
+++ b/docs/brainstorm/auto-migrate-on-upgrade/plan.md
@@ -0,0 +1,38 @@
+# Auto-migrate on upgrade - implementation plan
+
+## Tasks
+
+### Task 1: lazy search self-heal on read
+- **Files**: search read path (`src/core/search/search.ts` / store-open used by `brain_search` + `o2b search`), `src/core/search/store.ts`; tests under `tests/core/search/`.
+- **Acceptance**: a query against an index whose `schema_version` != LATEST (or a missing index over a vault with content) transparently reindexes once and returns results instead of throwing `SCHEMA_MISMATCH` / not-initialised. A genuinely empty vault still returns empty, not an error.
+- **Depends on**: none
+
+### Task 2: ensureVaultCurrent maintenance pass
+- **Files**: `src/core/maintenance/ensure-current.ts` (new); reuse `planUpgrade`/`applyUpgrade`, dir bootstrap, `reindexVault`; tests.
+- **Acceptance**:
+ - ensures Brain dirs exist (idempotent);
+ - applies the brain managed-file upgrade when pending (snapshot + log), no-op otherwise;
+ - detects a stale/missing search index and triggers a background reindex;
+ - never throws; returns a structured report of what it did;
+ - second run is a no-op.
+- **Depends on**: Task 1 (shares the reindex trigger)
+
+### Task 3: background, single-flight reindex trigger
+- **Files**: small helper (detached reindex; skip if index lock held).
+- **Acceptance**: returns immediately; does not block the caller; concurrent callers do not double-build (lock-guarded).
+- **Depends on**: Task 1
+
+### Task 4: wire into entry points
+- **Files**: `src/mcp/server.ts` (boot), `hooks/active-inject.ts` (SessionStart).
+- **Acceptance**: MCP server start invokes `ensureVaultCurrent(vault, { background: true })` best-effort; SessionStart hook does the same; neither delays startup nor throws.
+- **Depends on**: Tasks 2-3
+
+### Task 5: docs
+- **Files**: `docs/updating.md`, `hooks/README.md` note.
+- **Acceptance**: documents that updates are automatic (self-migrate on next start; no manual reindex / brain upgrade), and the state-driven (not synced-stamp) rationale as an invariant.
+- **Depends on**: Tasks 1-4
+
+### Task 6: QA + release
+- `bun run validate` green (hermetic); fmt:check + lint clean.
+- Smoke: stale-schema index -> first `o2b search` returns results; boot with pending brain upgrade -> applied.
+- Version bump + CHANGELOG, PR, release per playbook.
diff --git a/docs/brainstorm/auto-migrate-on-upgrade/variants.md b/docs/brainstorm/auto-migrate-on-upgrade/variants.md
new file mode 100644
index 00000000..6301ec6f
--- /dev/null
+++ b/docs/brainstorm/auto-migrate-on-upgrade/variants.md
@@ -0,0 +1,26 @@
+# Variants and rationale
+
+Orchestrator-decided (constrained robustness fix, not an open design space). The
+investigation (manual-step audit + entry-point map) closed the space.
+
+Approaches considered:
+
+- **A. Version stamp in the vault** (e.g. `Brain/.osb-state.json` or a
+ `_brain.yaml cli_version` key), compared to `SERVER_VERSION`. **Rejected as the
+ correctness mechanism:** the vault is Syncthing-synced across devices, so a
+ device that migrated would mark the work done for every device and make others
+ skip their own per-device steps (search reindex lives in a per-device index).
+- **B. Per-device stamp** in `~/.config/open-second-brain/`. Workable, but a stamp
+ can drift from reality (interrupted migration, downgrade, manual index delete).
+- **C. State-driven checks (chosen).** Each step keys off actual state - index
+ `schema_version` (per-device), `_brain.yaml` pending-changes plan (idempotent),
+ dir existence. Cheap reads on boot; only real migrations do work. Strictly more
+ correct than a stamp and immune to the synced-vault hazard. A per-device stamp
+ may still be written for logs only, never for gating.
+
+- **Reindex timing:** at-boot-blocking (rejected: delays MCP readiness on large
+ vaults) vs lazy-only (rejected alone: first search is slow and nothing is
+ proactive) vs **background kick + lazy self-heal safety net (chosen).**
+
+- **Auto-apply brain upgrade vs warn-only:** operator chose full hands-off, so
+ auto-apply with snapshot + log (additive, user content untouched).
diff --git a/docs/updating.md b/docs/updating.md
index 6a7716de..c75910c6 100644
--- a/docs/updating.md
+++ b/docs/updating.md
@@ -34,6 +34,33 @@ o2b install-cli # idempotent: re-points dangling or stale OSB symlinks
`o2b install-cli` only touches its own (Open Second Brain) symlinks or dangling
links; it never overwrites a real file or a symlink owned by another tool.
+### Vault state migrates itself
+
+You also do **not** need to run `o2b search reindex` or `o2b brain upgrade`
+after an update. On the next start of any runtime (the `o2b mcp` server boot,
+which Hermes/Claude Code/Codex all spawn, and the Claude Code SessionStart
+hook), `ensureVaultCurrent` brings an already-initialised vault current,
+hands-off:
+
+- a stale `_brain.yaml` / `_BRAIN.md` is migrated (snapshot-backed, additive;
+ user content untouched);
+- a stale-schema or missing search index is rebuilt in the **background** (a
+ detached reindex), so startup never blocks; and as a safety net the search
+ read path self-heals a stale/missing index on first query.
+
+It is **state-driven, not version-stamped.** Each step keys off actual on-disk
+state - the search index `schema_version`, the `_brain.yaml` pending-changes
+plan, directory existence - rather than a "last version" marker. This is
+deliberate: a vault is often synced across devices (Syncthing), so a stamp
+written into the vault would let one device mark the work done and make another
+skip its own per-device step (the search index is per-device). State checks are
+cheap reads on every start; only a real migration does work, and the approach
+also handles interrupted migrations and downgrades. Any per-device version note
+lives outside the vault and is for logging only, never for gating.
+
+The manual `o2b search reindex` / `o2b brain upgrade` commands still exist for
+explicit use; auto-migration just reuses their logic.
+
## Why updates used to break (and no longer do)
`hooks/hooks.json` previously invoked the bare `o2b-hook` launcher through a
@@ -70,9 +97,17 @@ version β€” never assume a clean prior state.**
checkout under `/srv/...` shared by Hermes/Codex).
4. **Codex has no plugin-root env var.** Keep the PATH `o2b-hook` fallback so
Codex (and any runtime without `CLAUDE_PLUGIN_ROOT`) still works.
+5. **Post-upgrade migration is state-driven and best-effort.** `ensureVaultCurrent`
+ must key off actual on-disk state (index `schema_version`, `_brain.yaml`
+ pending plan, dir existence), never a stamp written into the (possibly synced)
+ vault. It must never throw and never block startup - slow work (reindex) runs
+ detached in the background. Any new manual-after-upgrade step a future change
+ introduces must be folded into `ensureVaultCurrent` so the user never runs it.
These properties are locked by tests; do not weaken them:
- `tests/hooks/o2b-hook.test.ts` β€” fail-soft + `$CLAUDE_PLUGIN_ROOT`-first resolution.
- `tests/hooks/hooks-json-shape.test.ts` β€” every command is version-current, has a PATH fallback, and ends with `exit 0`.
- `tests/cli/install-cli.test.ts` β€” idempotent reclaim and conservative self-heal.
+- `tests/core/search/self-heal.test.ts` β€” search rebuilds a stale/missing index on read.
+- `tests/core/maintenance/ensure-current.test.ts` β€” state-driven migration, idempotent, never throws.
diff --git a/hooks/active-inject.ts b/hooks/active-inject.ts
index f23368f6..b33407ca 100644
--- a/hooks/active-inject.ts
+++ b/hooks/active-inject.ts
@@ -32,6 +32,7 @@ import { existsSync, readFileSync } from "node:fs";
import { resolveVault } from "../src/core/config.ts";
import { brainActivePath } from "../src/core/brain/paths.ts";
import { healCliSymlinks } from "../src/cli/install-cli.ts";
+import { ensureVaultCurrent } from "../src/core/maintenance/ensure-current.ts";
import { asHookPayload, readHookInput } from "./lib/stdin.ts";
async function main(): Promise<void> {
@@ -71,6 +72,19 @@ async function main(): Promise<void> {
const vault = resolveVault();
if (vault === null) return;
+ // Hands-off post-upgrade maintenance on SessionStart: migrate a stale
+ // _brain.yaml/_BRAIN.md and rebuild a stale/missing search index (the
+ // reindex runs detached so it survives this short-lived hook). Best-effort,
+ // never blocks injection. In background mode the synchronous part (brain
+ // upgrade + spawning the reindex) completes before this awaits.
+ if (hookEventName === "SessionStart") {
+ // Fire-and-forget: never put maintenance on the hook's critical path.
+ // background:true spawns the reindex detached; we do not await the result.
+ void ensureVaultCurrent(vault, { background: true }).catch(() => {
+ // opportunistic; must never disrupt the session
+ });
+ }
+
const activePath = brainActivePath(vault);
if (!existsSync(activePath)) return;
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 83efad13..73251c6a 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.31.1",
+ "version": "0.31.2",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index 26e415d9..70e94d4e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.31.1",
+ "version": "0.31.2",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
diff --git a/plugin.yaml b/plugin.yaml
index d17085fe..326d209b 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.31.1"
+version: "0.31.2"
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 c3d1ef5e..290215d4 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.31.1",
+ "version": "0.31.2",
"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 aa83eea2..99d1bde2 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.31.1"
+version: "0.31.2"
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 fe4dd7c3..a8bfa93e 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.31.1"
+version = "0.31.2"
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/cli/main.ts b/src/cli/main.ts
index 75ea2834..870481a4 100644
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -20,6 +20,7 @@ import {
} from "../core/config.ts";
import { listSecretReferences } from "../core/secret-ref.ts";
import { BRAIN_INDEX_REL } from "../core/brain/paths.ts";
+import { ensureVaultCurrent } from "../core/maintenance/ensure-current.ts";
import { doctor } from "../core/doctor.ts";
import { listVaultPages, writeFrontmatter } from "../core/vault.ts";
import { CliError, parseFlags } from "./argparse.ts";
@@ -435,6 +436,17 @@ async function cmdMcp(argv: string[]): Promise<number> {
const vault = requireVault(flags["vault"] as string | undefined, config);
const repoRoot = (flags["repo"] as string | undefined) ?? null;
+ // Hands-off post-upgrade maintenance: if the vault's on-disk state lags the
+ // running version (stale Brain managed files, stale/missing search index),
+ // bring it current with no user action. Fire-and-forget, full scope only
+ // (the writer server skips it), never blocks or fails server start; a needed
+ // reindex runs detached in the background.
+ if (scope === "full") {
+ void ensureVaultCurrent(vault, { background: true, configPath: config }).catch(() => {
+ // best-effort; the server must come up regardless
+ });
+ }
+
process.stderr.write(
`[mcp] ${serverName} ${SERVER_VERSION} listening on stdio (vault=${vault})\n`,
);
diff --git a/src/core/maintenance/ensure-current.ts b/src/core/maintenance/ensure-current.ts
new file mode 100644
index 00000000..0765a4b9
--- /dev/null
+++ b/src/core/maintenance/ensure-current.ts
@@ -0,0 +1,143 @@
+/**
+ * Hands-off post-upgrade maintenance. After the plugin is updated, the on-disk
+ * state of an already-initialised vault can lag the running version and would
+ * otherwise need manual commands (`o2b search reindex`, `o2b brain upgrade`).
+ * `ensureVaultCurrent` brings it current automatically and is safe to call on
+ * every startup: it NEVER throws, and in `background` mode never blocks the
+ * caller on a slow reindex.
+ *
+ * It is STATE-DRIVEN, not version-stamped: each step keys off actual on-disk
+ * state (search index `schema_version`, `_brain.yaml` pending-changes plan).
+ * This is deliberate - the vault is often synced across devices (e.g.
+ * Syncthing), so a stamp written into the vault would let one device mark a
+ * migration done and make another skip its own per-device work (the search
+ * index is per-device). State checks are cheap reads and also handle
+ * interrupted migrations and downgrades correctly.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Database } from "bun:sqlite";
+
+import { defaultConfigPath } from "../config.ts";
+import { brainConfigPath } from "../brain/paths.ts";
+import { planUpgrade, applyUpgrade } from "../brain/upgrade.ts";
+import { resolveSearchConfig } from "../search/index.ts";
+import { reindexVault } from "../search/indexer.ts";
+import { LATEST_SCHEMA_VERSION, readSchemaVersion } from "../search/schema.ts";
+import type { ResolvedSearchConfig } from "../search/types.ts";
+
+export interface EnsureCurrentResult {
+ /** Vault-relative paths of Brain managed files migrated this run. */
+ readonly brainUpgraded: ReadonlyArray<string>;
+ /** A search reindex was started (background) or completed (foreground). */
+ readonly reindexTriggered: boolean;
+ /** Non-empty when nothing ran, e.g. "not-initialized". */
+ readonly skipped: string;
+ /** Best-effort: per-step failures, never thrown. */
+ readonly errors: ReadonlyArray<string>;
+}
+
+export interface EnsureCurrentOptions {
+ /** When true (default for startup), a needed reindex runs detached and the
+ * call returns immediately. When false, the reindex is awaited (used by
+ * tests and explicit callers). */
+ readonly background?: boolean;
+ /** Plugin config path to resolve search settings from. Defaults to
+ * `defaultConfigPath()`. Threading this ensures the index that is checked and
+ * (re)built matches the one the caller's server actually uses, e.g. under
+ * `o2b mcp --config <custom>`. */
+ readonly configPath?: string;
+}
+
+function message(e: unknown): string {
+ return e instanceof Error ? (e.message ?? String(e)) : String(e);
+}
+
+/** Cheap, read-only check: is the search index absent or on a stale schema? */
+function indexNeedsRebuild(config: ResolvedSearchConfig): boolean {
+ if (!existsSync(config.dbPath)) return true;
+ let db: Database;
+ try {
+ db = new Database(config.dbPath, { readonly: true });
+ } catch {
+ return true; // unreadable -> rebuild
+ }
+ try {
+ return readSchemaVersion(db) !== LATEST_SCHEMA_VERSION;
+ } catch {
+ return true; // corrupt / non-OSB file -> rebuild
+ } finally {
+ db.close();
+ }
+}
+
+/** Path to this checkout's `scripts/o2b` (current plugin version). */
+function o2bScriptPath(): string {
+ // src/core/maintenance/ensure-current.ts -> repo root
+ const repo = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+ return join(repo, "scripts", "o2b");
+}
+
+/**
+ * Start a reindex without blocking. Spawns a detached `o2b search reindex` so
+ * it survives a short-lived caller (e.g. a SessionStart hook process), and
+ * does not tie up a long-lived one (the MCP server). `reindexVault` is
+ * lock-guarded, so a concurrent rebuild is serialised, not duplicated.
+ */
+function spawnDetachedReindex(vault: string, configPath: string): void {
+ const proc = Bun.spawn(
+ [o2bScriptPath(), "search", "reindex", "--vault", vault, "--config", configPath],
+ {
+ stdin: "ignore",
+ stdout: "ignore",
+ stderr: "ignore",
+ },
+ );
+ proc.unref();
+}
+
+export async function ensureVaultCurrent(
+ vault: string,
+ opts: EnsureCurrentOptions = {},
+): Promise<EnsureCurrentResult> {
+ const background = opts.background ?? true;
+ const errors: string[] = [];
+ let brainUpgraded: ReadonlyArray<string> = [];
+ let reindexTriggered = false;
+
+ // Only an already-initialised vault is an upgrade target. A missing
+ // `_brain.yaml` means "not set up yet" - that is `o2b init`'s job, not ours.
+ if (!existsSync(brainConfigPath(vault))) {
+ return { brainUpgraded: [], reindexTriggered: false, skipped: "not-initialized", errors: [] };
+ }
+
+ // 1. Brain managed-file upgrade - idempotent; only when changes are pending
+ // and the plan is clean (a half-mergeable plan is left for the operator).
+ try {
+ const plan = planUpgrade(vault);
+ if (plan.errors === 0 && plan.pending > 0) {
+ brainUpgraded = applyUpgrade(vault).files_updated;
+ }
+ } catch (e) {
+ errors.push(`brain-upgrade: ${message(e)}`);
+ }
+
+ // 2. Search index - rebuild if absent or on a stale schema.
+ try {
+ const configPath = opts.configPath ?? defaultConfigPath();
+ const config = resolveSearchConfig({ vault, configPath });
+ if (indexNeedsRebuild(config)) {
+ reindexTriggered = true;
+ if (background) {
+ spawnDetachedReindex(vault, configPath);
+ } else {
+ await reindexVault(config);
+ }
+ }
+ } catch (e) {
+ errors.push(`search-reindex: ${message(e)}`);
+ }
+
+ return { brainUpgraded, reindexTriggered, skipped: "", errors };
+}
diff --git a/src/core/search/search.ts b/src/core/search/search.ts
index 00d9c632..ad76db05 100644
--- a/src/core/search/search.ts
+++ b/src/core/search/search.ts
@@ -141,6 +141,32 @@ function addStructuredReasons(
});
}
+/**
+ * Open the index for reading, self-healing a stale or absent index. After a
+ * plugin upgrade the on-disk index can be a different schema version
+ * (`SCHEMA_MISMATCH`) or not yet built (`INDEX_MISSING`); rather than forcing
+ * the user to run `o2b search reindex` / `o2b search index`, rebuild once and
+ * retry. `reindexVault` is imported lazily so the hot path never pulls in the
+ * indexer and there is no module cycle.
+ */
+async function openReadOrSelfHeal(config: ResolvedSearchConfig): Promise<Store> {
+ try {
+ return await Store.open(config, { mode: "read" });
+ } catch (e) {
+ if (e instanceof SearchError && (e.code === "INDEX_MISSING" || e.code === "SCHEMA_MISMATCH")) {
+ try {
+ const { reindexVault } = await import("./indexer.ts");
+ await reindexVault(config);
+ } catch {
+ // A concurrent writer may already be rebuilding (INDEX_LOCKED), or the
+ // rebuild failed - fall through and let the retry surface real state.
+ }
+ return await Store.open(config, { mode: "read" });
+ }
+ throw e;
+ }
+}
+
export async function search(
config: ResolvedSearchConfig,
opts: SearchOptions,
@@ -164,7 +190,7 @@ export async function search(
// folded in once they have been derived from the store below.
const basePlan = buildQueryPlan(keywordQuery, [], structured?.intent);
- const store = await Store.open(config, { mode: "read" });
+ const store = await openReadOrSelfHeal(config);
try {
// Persistent query cache (v0.20.0): opt-in. Keyed by the request +
// base plan hash + a config fingerprint, gated by the corpus
diff --git a/tests/cli/search.test.ts b/tests/cli/search.test.ts
index 9fd465c5..255a4fe0 100644
--- a/tests/cli/search.test.ts
+++ b/tests/cli/search.test.ts
@@ -167,12 +167,14 @@ test("search focus set/status/clear steers only the focused query window", async
expect(JSON.parse(clear.stdout).active).toBe(false);
});
-test("search query on missing index fails with exit 1", async () => {
+test("search query on a missing index self-heals (builds it) and exits 0", async () => {
+ // A query used to fail with INDEX_MISSING; the read path now builds the index
+ // on first use so an upgrade never needs a manual `o2b search index`.
const out = await runCli(["search", "nothing-here"], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
- expect(out.returncode).toBe(1);
- expect(out.stderr).toContain("INDEX_MISSING");
+ expect(out.returncode).toBe(0);
+ expect(existsSync(join(vault, ".open-second-brain", "brain.sqlite"))).toBe(true);
});
test("search check reports vault_readable and sqlite_ok on a fresh vault", async () => {
diff --git a/tests/core/maintenance/ensure-current.test.ts b/tests/core/maintenance/ensure-current.test.ts
new file mode 100644
index 00000000..11770b0c
--- /dev/null
+++ b/tests/core/maintenance/ensure-current.test.ts
@@ -0,0 +1,121 @@
+/**
+ * Hands-off post-upgrade maintenance: ensureVaultCurrent must, on an
+ * already-initialised vault, migrate stale Brain managed files and rebuild a
+ * stale/missing search index - idempotently, never throwing, and (in the
+ * foreground mode used here) deterministically.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { ensureVaultCurrent } from "../../../src/core/maintenance/ensure-current.ts";
+import { bootstrapBrain } from "../../../src/core/brain/init.ts";
+import { planUpgrade } from "../../../src/core/brain/upgrade.ts";
+import { brainConfigPath } from "../../../src/core/brain/paths.ts";
+import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
+import { resolveSearchConfig } from "../../../src/core/search/index.ts";
+import { LATEST_SCHEMA_VERSION, readSchemaVersion } from "../../../src/core/search/schema.ts";
+
+let vault: string;
+let configHome: string;
+let configPath: string;
+let prevConfigEnv: string | undefined;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-ensure-vault-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-ensure-cfg-"));
+ configPath = join(configHome, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\n`);
+ // ensureVaultCurrent resolves the config via defaultConfigPath().
+ prevConfigEnv = process.env["OPEN_SECOND_BRAIN_CONFIG"];
+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
+});
+
+afterEach(() => {
+ if (prevConfigEnv === undefined) delete process.env["OPEN_SECOND_BRAIN_CONFIG"];
+ else process.env["OPEN_SECOND_BRAIN_CONFIG"] = prevConfigEnv;
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+function dbPath(): string {
+ return resolveSearchConfig({ vault, configPath }).dbPath;
+}
+function indexSchema(): number {
+ const db = new Database(dbPath(), { readonly: true });
+ try {
+ return readSchemaVersion(db);
+ } finally {
+ db.close();
+ }
+}
+
+describe("ensureVaultCurrent", () => {
+ test("skips an uninitialised vault (no _brain.yaml)", async () => {
+ const r = await ensureVaultCurrent(vault, { background: false });
+ expect(r.skipped).toBe("not-initialized");
+ expect(r.errors).toEqual([]);
+ });
+
+ test("migrates a stale _brain.yaml and rebuilds the (missing) index", async () => {
+ bootstrapBrain(vault, { configPath });
+ // Force a pending brain upgrade: a minimal _brain.yaml missing sections.
+ atomicWriteFileSync(brainConfigPath(vault), "schema_version: 1\n");
+ expect(planUpgrade(vault).pending).toBeGreaterThan(0);
+
+ const r = await ensureVaultCurrent(vault, { background: false });
+
+ expect(r.errors).toEqual([]);
+ expect(r.brainUpgraded.length).toBeGreaterThan(0);
+ expect(planUpgrade(vault).pending).toBe(0); // upgrade applied
+ expect(r.reindexTriggered).toBe(true);
+ expect(existsSync(dbPath())).toBe(true);
+ expect(indexSchema()).toBe(LATEST_SCHEMA_VERSION);
+ });
+
+ test("is a no-op on a second run (idempotent)", async () => {
+ bootstrapBrain(vault, { configPath });
+ await ensureVaultCurrent(vault, { background: false }); // builds index, brain current
+ const r = await ensureVaultCurrent(vault, { background: false });
+ expect(r.brainUpgraded).toEqual([]);
+ expect(r.reindexTriggered).toBe(false);
+ expect(r.errors).toEqual([]);
+ });
+
+ test("rebuilds a stale-schema index", async () => {
+ bootstrapBrain(vault, { configPath });
+ await ensureVaultCurrent(vault, { background: false }); // build a current index
+ const db = new Database(dbPath());
+ db.run("UPDATE index_state SET value = '1' WHERE key = 'schema_version'");
+ db.close();
+
+ const r = await ensureVaultCurrent(vault, { background: false });
+ expect(r.reindexTriggered).toBe(true);
+ expect(indexSchema()).toBe(LATEST_SCHEMA_VERSION);
+ });
+
+ test("honors an explicit configPath for the search index", async () => {
+ bootstrapBrain(vault, { configPath });
+ // A second config pointing the index at a custom path.
+ const altConfig = join(configHome, "alt.yaml");
+ const altDb = join(configHome, "alt-index.sqlite");
+ atomicWriteFileSync(altConfig, `vault: ${vault}\nsearch_db_path: ${altDb}\n`);
+
+ const r = await ensureVaultCurrent(vault, { background: false, configPath: altConfig });
+ expect(r.reindexTriggered).toBe(true);
+ // The index was built at the caller's configured path, not the default one.
+ expect(existsSync(altDb)).toBe(true);
+ expect(existsSync(dbPath())).toBe(false);
+ });
+
+ test("never throws on a malformed _brain.yaml", async () => {
+ bootstrapBrain(vault, { configPath });
+ atomicWriteFileSync(brainConfigPath(vault), ":\n not: [valid\n"); // malformed
+ const r = await ensureVaultCurrent(vault, { background: false });
+ // Brain upgrade is skipped (plan has errors), but the call still succeeds.
+ expect(r.skipped).toBe("");
+ expect(Array.isArray(r.errors)).toBe(true);
+ });
+});
diff --git a/tests/core/search/search.test.ts b/tests/core/search/search.test.ts
index 0602ee5e..8b1148a5 100644
--- a/tests/core/search/search.test.ts
+++ b/tests/core/search/search.test.ts
@@ -300,16 +300,14 @@ test("empty query throws INVALID_INPUT", async () => {
expect(err?.code).toBe("INVALID_INPUT");
});
-test("missing index throws INDEX_MISSING", async () => {
+test("missing index self-heals: search builds it on first use", async () => {
+ // A missing index used to throw INDEX_MISSING; the read path now rebuilds
+ // once and returns results so an upgrade never needs a manual `o2b search
+ // index`. (Dedicated coverage in self-heal.test.ts.)
const cfg = await seedKeyword();
- // skip indexVault
- let err: SearchError | null = null;
- try {
- await search(cfg, { query: "fox" });
- } catch (e) {
- err = e as SearchError;
- }
- expect(err?.code).toBe("INDEX_MISSING");
+ // skip indexVault β€” the search must build the index itself
+ const out = await search(cfg, { query: "fox" });
+ expect(out.results.length).toBeGreaterThan(0);
});
test("hybrid search combines keyword and semantic when both contribute", async () => {
diff --git a/tests/core/search/self-heal.test.ts b/tests/core/search/self-heal.test.ts
new file mode 100644
index 00000000..89a02f0b
--- /dev/null
+++ b/tests/core/search/self-heal.test.ts
@@ -0,0 +1,59 @@
+/**
+ * Lazy self-heal on the search read path: after a plugin upgrade the on-disk
+ * index can be a stale schema (SCHEMA_MISMATCH) or absent (INDEX_MISSING). A
+ * search must transparently rebuild once and return results instead of forcing
+ * the user to run `o2b search reindex` / `o2b search index`.
+ */
+import { test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { existsSync, rmSync } from "node:fs";
+
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { search } from "../../../src/core/search/search.ts";
+import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
+
+let vault: string;
+let dbPath: string;
+let cleanup: () => void;
+
+beforeEach(() => {
+ const v = createTempVault("selfheal");
+ vault = v.vault;
+ dbPath = v.dbPath;
+ cleanup = v.cleanup;
+ writeMd(vault, "Notes/foo.md", "# Foo\n\nThe quick brown fox jumps over the lazy dog.");
+});
+
+afterEach(() => {
+ cleanup();
+});
+
+test("SCHEMA_MISMATCH on read self-heals: search rebuilds and returns results", async () => {
+ const config = makeConfig({ vault, dbPath });
+ await indexVault(config); // valid index at LATEST schema
+
+ // Simulate an index built by an older plugin version.
+ const db = new Database(dbPath);
+ db.run("UPDATE index_state SET value = '1' WHERE key = 'schema_version'");
+ db.close();
+
+ // Without self-heal this throws SCHEMA_MISMATCH; with it, it rebuilds.
+ const outcome = await search(config, { query: "fox" });
+ expect(outcome.results.length).toBeGreaterThan(0);
+});
+
+test("INDEX_MISSING on read self-heals: search builds the index on first use", async () => {
+ const config = makeConfig({ vault, dbPath });
+ expect(existsSync(dbPath)).toBe(false); // never indexed
+
+ const outcome = await search(config, { query: "fox" });
+ expect(outcome.results.length).toBeGreaterThan(0);
+ expect(existsSync(dbPath)).toBe(true); // built by the self-heal
+});
+
+test("a genuinely empty vault returns empty results, not an error", async () => {
+ rmSync(`${vault}/Notes/foo.md`, { force: true });
+ const config = makeConfig({ vault, dbPath });
+ const outcome = await search(config, { query: "fox" });
+ expect(outcome.results.length).toBe(0);
+});
diff --git a/tests/mcp/search.test.ts b/tests/mcp/search.test.ts
index 4c0c1bb7..b89de650 100644
--- a/tests/mcp/search.test.ts
+++ b/tests/mcp/search.test.ts
@@ -264,12 +264,16 @@ test("brain_search rejects path_prefix that escapes vault", async () => {
expect(resp.error.message).toContain("path_prefix");
});
-test("brain_search on missing index surfaces INTERNAL_ERROR with hint", async () => {
+test("brain_search self-heals a missing index instead of erroring", async () => {
+ // A missing index used to surface INTERNAL_ERROR ("not initialised"); the
+ // read path now builds it on first use, so brain_search just works after an
+ // upgrade with no manual `o2b search index`.
+ writeMd("foo.md", "# Foo\n\nThe quick brown fox jumps over the lazy dog.");
const server = makeServer();
await initialize(server);
const resp = (await call(server, "brain_search", { query: "fox" })) as any;
- expect(resp?.error?.code).toBe(-32603); // INTERNAL_ERROR
- expect(resp.error.message).toMatch(/not initialised|index/i);
+ expect(resp.error).toBeUndefined();
+ expect(resp.result).toBeDefined();
});
test("brain_search rejects limit > 50", async () => {