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.jsonindex 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.jsonindex 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.mdindex 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-01Update-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.0diff --git a/docs/brainstorm/auto-migrate-on-upgrade/design.md b/docs/brainstorm/auto-migrate-on-upgrade/design.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 danglinglinks; 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 soCodex (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.tsindex 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.jsonindex 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.jsonindex 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.yamlindex 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: standalonediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 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.yamlindex 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: standalonediff --git a/pyproject.toml b/pyproject.tomlindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 corpusdiff --git a/tests/cli/search.test.ts b/tests/cli/search.test.tsindex 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", asyncexpect(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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 () => {