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
39.4 KB
Raw Blame
/**
 * MCP integration tests for the six Brain tools.
 *
 * These exercise the full handler path (`MCPServer.handleRequest →
 * tools/call → handler → core/brain/*`). We rely on the existing
 * `MCPServer` plumbing — no direct handler imports — so a regression in
 * tool registration or argument coercion is caught here too.
 *
 * Each test stands up a fresh tmp vault, initialises the Brain layer
 * via `bootstrapBrain` (mirrors what `o2b brain init` would do), and
 * tears down at the end. Wall-clock-sensitive cases pin time via the
 * tool's own `now` argument.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
import { buildToolTable } from "../../src/mcp/tools.ts";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import {
  brainDirs,
  brainPinnedPath,
  logJsonlPath,
  logPath,
  preferencePath,
} from "../../src/core/brain/paths.ts";
import { writeSignal } from "../../src/core/brain/signal.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { vaultRelativeSafe } from "../../src/mcp/brain-tools.ts";
import { findingRefs } from "../../src/mcp/brain/hygiene-tools.ts";
import { useUnshardedLegacyLog } from "../helpers/device-id.ts";

// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();

let tmp: string;
let vault: string;
let configHome: string;
let configPath: string;
const savedEnv: Record<string, string | undefined> = {};

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-brain-"));
  vault = join(tmp, "vault");
  configHome = mkdtempSync(join(tmpdir(), "o2b-mcp-brain-cfg-"));
  configPath = join(configHome, "config.yaml");
  for (const k of ["VAULT_AGENT_NAME", "VAULT_TIMEZONE", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG"]) {
    savedEnv[k] = process.env[k];
    delete process.env[k];
  }
  // Isolate from any system-wide plugin config — the project's own
  // dev config on the developer's machine would otherwise leak through.
  process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
  atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
  bootstrapBrain(vault, { configPath });
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
  rmSync(configHome, { recursive: true, force: true });
  for (const [k, v] of Object.entries(savedEnv)) {
    if (v === undefined) delete process.env[k];
    else process.env[k] = v;
  }
});

async function initialize(server: MCPServer): Promise<void> {
  await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: PROTOCOL_VERSION,
      capabilities: {},
      clientInfo: { name: "brain-test", version: "0" },
    },
  });
  await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    method: "notifications/initialized",
  });
}

async function call(
  server: MCPServer,
  name: string,
  args: Record<string, unknown> = {},
): Promise<any> {
  return server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 99,
    method: "tools/call",
    params: { name, arguments: args },
  });
}

function makeServer(): MCPServer {
  // The operator's own shell: a real dream pass runs at local reach only.
  return new MCPServer({ vault, configPath }, { reach: TRANSPORT_REACH.local });
}

// ---------------------------------------------------------------------------
// brain_feedback
// ---------------------------------------------------------------------------

describe("vaultRelativeSafe", () => {
  test("returns the original target unchanged when target is outside the vault", () => {
    // Cross-platform regression: the prior implementation used a
    // hard-coded `/` separator and a prefix-match. On Windows it would
    // misbehave for `C:\Users\...`-style absolute paths. Using
    // `path.relative` / `path.isAbsolute` is the correct shape.
    const outOfVault = "/tmp/somewhere-else/file.md";
    expect(vaultRelativeSafe(vault, outOfVault)).toBe(outOfVault);
  });

  test("returns vault-relative path for an in-vault target", () => {
    const inVault = join(vault, "Brain", "inbox", "sig-x.md");
    const rel = vaultRelativeSafe(vault, inVault);
    // The answer is the vault's POSIX identity on every host, never the
    // host's separator (`Brain\\inbox\\...` on Windows).
    expect(rel).toBe("Brain/inbox/sig-x.md");
    // The returned path must NOT be absolute — that's the property
    // every downstream consumer (digest, JSON output) relies on.
    expect(rel.startsWith("/")).toBe(false);
  });

  test("returns empty string when target equals the vault root", () => {
    expect(vaultRelativeSafe(vault, vault)).toBe("");
  });
});

describe("hygiene findingRefs", () => {
  test("an absolute page path is rendered vault-relative on every host", () => {
    // A leading-`/` test let a Windows page path (`C:\\...`) through as a
    // host path; `isAbsolute` recognises both spellings.
    const refs = findingRefs(vault, {
      id: "freshness:x",
      detector: "freshness",
      severity: "action",
      title: "t",
      targets: [join(vault, "Brain", "pages", "x.md"), "pref-abc", "entity#aspect"],
      proposed_action: "recompile",
      evidence: {},
    });
    expect(refs).toEqual(["Brain/pages/x.md", "pref-abc", "entity#aspect"]);
  });
});

describe("brain_feedback tool schema", () => {
  test("force_confirmed description reflects the alongside-signal behaviour", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await server.handleRequest({
      jsonrpc: JSONRPC_VERSION,
      id: 50,
      method: "tools/list",
    });
    const tools = (r as any).result.tools as ReadonlyArray<{
      name: string;
      inputSchema: { properties?: Record<string, { description?: string }> };
    }>;
    const feedback = tools.find((t) => t.name === "brain_feedback");
    expect(feedback).toBeDefined();
    const fcDesc = feedback!.inputSchema.properties?.["force_confirmed"]?.description ?? "";
    // The handler ALWAYS writes the inbox signal; with force_confirmed
    // it additionally materialises a confirmed preference. The earlier
    // "instead of an inbox signal" wording was incorrect.
    expect(fcDesc).toContain("alongside");
    expect(fcDesc).not.toMatch(/instead of an inbox signal/i);
  });
});

describe("brain_feedback", () => {
  test("writes a signal under Brain/inbox/ and returns path + id", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_feedback", {
      topic: "no-internal-abbrev",
      signal: "negative",
      principle: "Expand internal abbreviations on first use.",
      scope: "writing",
      source: ["[[Daily/2026.05.14]]"],
      raw: "Sergey pointed out OSB appeared without explanation.",
    });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.kind).toBe("signal");
    expect(s.id).toMatch(/^sig-\d{4}-\d{2}-\d{2}-no-internal-abbrev$/);
    expect(s.path).toMatch(/^Brain\/inbox\/sig-.*\.md$/);
    expect(s.agent).toBe("claude");
    const file = join(vault, s.path);
    expect(existsSync(file)).toBe(true);
    const text = readFileSync(file, "utf8");
    expect(text).toContain("kind: brain-signal");
    expect(text).toContain("signal: negative");
    expect(text).toContain("topic: no-internal-abbrev");
    expect(text).toContain("Sergey pointed out OSB appeared");
  });

  test("force_confirmed: true creates a preference directly", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_feedback", {
      topic: "imperative-prompts",
      signal: "positive",
      principle: "Write prompts in imperative voice.",
      scope: "process",
      source: ["[[Daily/2026.05.14#prompts]]"],
      force_confirmed: true,
    });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.kind).toBe("preference");
    expect(s.id).toBe("pref-imperative-prompts");
    const prefFile = preferencePath(vault, "imperative-prompts");
    expect(existsSync(prefFile)).toBe(true);
    const text = readFileSync(prefFile, "utf8");
    expect(text).toContain("status: confirmed");
    expect(text).toContain("topic: imperative-prompts");
  });

  test("write-conflict advisory: names a confirmed same-scope preference and the write still proceeds", async () => {
    const server = makeServer();
    await initialize(server);
    // Seed a confirmed same-scope preference.
    await call(server, "brain_feedback", {
      topic: "tabs-rule",
      signal: "positive",
      principle: "always indent source with tabs not spaces",
      scope: "coding",
      force_confirmed: true,
    });
    // A near-duplicate incoming signal in the same scope.
    const r = await call(server, "brain_feedback", {
      topic: "tabs-again",
      signal: "negative",
      principle: "always indent source with tabs not spaces",
      scope: "coding",
    });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    // The write always proceeds.
    expect(s.signal_id).toMatch(/^sig-/);
    // The advisory names the confirmed preference.
    expect(s.advisory).toBeDefined();
    expect(s.advisory.conflicts.map((c: { pref_id: string }) => c.pref_id)).toContain(
      "pref-tabs-rule",
    );
  });

  test("no advisory field for a non-conflicting write", async () => {
    const server = makeServer();
    await initialize(server);
    await call(server, "brain_feedback", {
      topic: "tabs-rule",
      signal: "positive",
      principle: "always indent source with tabs not spaces",
      scope: "coding",
      force_confirmed: true,
    });
    const r = await call(server, "brain_feedback", {
      topic: "semantic-html",
      signal: "positive",
      principle: "prefer semantic HTML over generic containers",
      scope: "coding",
    });
    expect(r.result.isError).toBe(false);
    expect(r.result.structuredContent.advisory).toBeUndefined();
  });

  test("INVALID_PARAMS when required field missing", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_feedback", {
      // topic missing
      signal: "positive",
      principle: "x",
    });
    expect(r.error.code).toBe(-32602);
  });

  test("INVALID_PARAMS for invalid signal value", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_feedback", {
      topic: "x-rule",
      signal: "neutral",
      principle: "y",
    });
    expect(r.error.code).toBe(-32602);
  });
});

describe("brain_feedback — default_scope", () => {
  function setDefaultScope(scope: string): void {
    const yamlPath = join(vault, "Brain", "_brain.yaml");
    const existing = readFileSync(yamlPath, "utf8");
    atomicWriteFileSync(yamlPath, `${existing}\nfeedback:\n  default_scope: ${scope}\n`);
  }

  test("applies the default scope when none is passed", async () => {
    setDefaultScope("coding");
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_feedback", {
      topic: "default-applies",
      signal: "positive",
      principle: "Inherit the default scope.",
    });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    const text = readFileSync(join(vault, s.path), "utf8");
    expect(text).toContain("scope: coding");
    expect(text).toContain("brain/scope/coding");
  });

  test("explicit scope overrides the default", async () => {
    setDefaultScope("coding");
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_feedback", {
      topic: "explicit-overrides",
      signal: "positive",
      principle: "Explicit scope wins.",
      scope: "docs",
    });
    const s = r.result.structuredContent;
    const text = readFileSync(join(vault, s.path), "utf8");
    expect(text).toContain("scope: docs");
    expect(text).not.toContain("scope: coding");
  });

  test("no default + no explicit scope omits the scope frontmatter", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_feedback", {
      topic: "scopeless",
      signal: "positive",
      principle: "Stay scope-less.",
    });
    const s = r.result.structuredContent;
    const text = readFileSync(join(vault, s.path), "utf8");
    expect(text).not.toContain("scope:");
    expect(text).not.toContain("brain/scope/");
  });

  test("force_confirmed preference inherits the default scope", async () => {
    setDefaultScope("coding");
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_feedback", {
      topic: "fc-default",
      signal: "positive",
      principle: "Force-confirmed inherits default scope.",
      force_confirmed: true,
    });
    const s = r.result.structuredContent;
    expect(s.kind).toBe("preference");
    const prefFile = preferencePath(vault, "fc-default");
    const text = readFileSync(prefFile, "utf8");
    expect(text).toContain("scope: coding");
  });
});

// ---------------------------------------------------------------------------
// brain_dream
// ---------------------------------------------------------------------------

describe("brain_dream", () => {
  test("no-op on empty vault returns changed=false", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_dream", {});
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.changed).toBe(false);
    expect(s.new_unconfirmed).toEqual([]);
    expect(s.confirmed).toEqual([]);
    expect(s.retired).toEqual([]);
    // No snapshot or log file should be written when nothing changed.
    expect(s.snapshot_path).toBeNull();
    expect(s.log_path).toBeNull();
  });

  test("promotes a cluster after 3 same-sign signals", async () => {
    // Seed three signals for the same topic so dream promotes them.
    for (let i = 0; i < 3; i++) {
      writeSignal(vault, {
        topic: "no-tabs-in-md",
        signal: "negative",
        agent: "claude",
        principle: "Use spaces, not tabs, in Markdown.",
        created_at: `2026-05-${10 + i}T10:00:00Z`,
        date: `2026-05-${10 + i}`,
        slug: `no-tabs-in-md-${i}`,
        scope: "writing",
      });
    }

    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_dream", {
      now: "2026-05-14T10:00:00Z",
    });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.changed).toBe(true);
    expect(s.new_unconfirmed).toContain("pref-no-tabs-in-md");
    expect(s.moved_to_processed.length).toBe(3);
    expect(typeof s.run_id).toBe("string");
    expect(s.log_path).not.toBeNull();
    expect(s.snapshot_path).not.toBeNull();
  });

  test("dry_run computes plan without writing", async () => {
    for (let i = 0; i < 3; i++) {
      writeSignal(vault, {
        topic: "dry-run-rule",
        signal: "positive",
        agent: "claude",
        principle: "Dry-run test.",
        created_at: `2026-05-${10 + i}T10:00:00Z`,
        date: `2026-05-${10 + i}`,
        slug: `dry-run-rule-${i}`,
      });
    }
    const server = makeServer();
    await initialize(server);
    const dirs = brainDirs(vault);
    const inboxBefore = readdirSync(dirs.inbox).filter((n) => n.endsWith(".md")).length;
    const prefsBefore = readdirSync(dirs.preferences).filter((n) => n.endsWith(".md")).length;

    const r = await call(server, "brain_dream", {
      dry_run: true,
      now: "2026-05-14T10:00:00Z",
    });
    expect(r.result.isError).toBe(false);
    expect(r.result.structuredContent.dry_run).toBe(true);

    // Files unchanged on disk after a dry-run.
    const inboxAfter = readdirSync(dirs.inbox).filter((n) => n.endsWith(".md")).length;
    const prefsAfter = readdirSync(dirs.preferences).filter((n) => n.endsWith(".md")).length;
    expect(inboxAfter).toBe(inboxBefore);
    expect(prefsAfter).toBe(prefsBefore);
  });
});

// ---------------------------------------------------------------------------
// brain_apply_evidence
// ---------------------------------------------------------------------------

describe("brain_apply_evidence", () => {
  function seedPref(slug: string): void {
    writePreference(vault, {
      slug,
      topic: slug,
      principle: `Rule for ${slug}`,
      created_at: "2026-05-14T10:00:00Z",
      unconfirmed_until: "2026-05-28T10:00:00Z",
      status: "unconfirmed",
      evidenced_by: [`[[sig-2026-05-14-${slug}]]`],
      confirmed_at: null,
      scope: "writing",
    });
  }

  test("happy path appends to today's log and returns logged_at", async () => {
    seedPref("no-internal-abbrev");
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_apply_evidence", {
      pref_id: "pref-no-internal-abbrev",
      artifact: "[[Daily/2026.05.14#blog]]",
      result: "applied",
      note: "Expanded OSB on first use.",
    });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.logged_at).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
    expect(s.log_path.startsWith("Brain/log/")).toBe(true);
    expect(s.agent).toBe("claude");
    const file = join(vault, s.log_path);
    const text = readFileSync(file, "utf8");
    expect(text).toContain("[[pref-no-internal-abbrev|");
    expect(text).toContain("applied");
    expect(text).toContain("Expanded OSB on first use.");
  });

  test("missing preference returns tool-level error (isError true)", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_apply_evidence", {
      pref_id: "pref-does-not-exist",
      artifact: "[[somewhere]]",
      result: "applied",
    });
    // Per design doc §9.2: "not an error condition" — surface a
    // friendly tool-level error envelope, not a JSON-RPC protocol error.
    expect(r.error).toBeUndefined();
    expect(r.result.isError).toBe(true);
    expect(r.result.content[0].text).toContain("preference not found");
  });

  test("INVALID_PARAMS for invalid result value", async () => {
    seedPref("x-rule");
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_apply_evidence", {
      pref_id: "pref-x-rule",
      artifact: "[[x]]",
      result: "maybe",
    });
    expect(r.error.code).toBe(-32602);
  });
});

// ---------------------------------------------------------------------------
// brain_digest
// ---------------------------------------------------------------------------

describe("brain_brief view=digest", () => {
  test("empty vault returns 'no changes' markdown", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_brief", { view: "digest" });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.empty).toBe(true);
    expect(s.format).toBe("markdown");
    expect(s.content).toContain("no changes");
  });

  test("with confirmed prefs renders Markdown sections", async () => {
    // Seed a confirmed preference inside the digest window.
    writePreference(vault, {
      slug: "confirmed-rule",
      topic: "confirmed-rule",
      principle: "Confirmed test rule.",
      created_at: "2026-05-14T09:00:00Z",
      unconfirmed_until: "2026-05-14T09:00:00Z",
      status: "confirmed",
      evidenced_by: [],
      confirmed_at: "2026-05-14T09:00:00Z",
      applied_count: 1,
      scope: "process",
    });
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_brief", {
      view: "digest",
      since: "2026-05-14T00:00:00Z",
      until: "2026-05-14T23:59:59Z",
    });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.empty).toBe(false);
    expect(s.content).toContain("Brain digest");
    expect(s.content).toContain("Confirmed");
  });

  test("uses configured markdown link output in Markdown digest", async () => {
    atomicWriteFileSync(
      configPath,
      `vault: ${vault}\nagent_name: claude\nlink_output_format: markdown\n`,
    );
    writePreference(vault, {
      slug: "confirmed-rule",
      topic: "confirmed-rule",
      principle: "Confirmed test rule.",
      created_at: "2026-05-14T09:00:00Z",
      unconfirmed_until: "2026-05-14T09:00:00Z",
      status: "confirmed",
      evidenced_by: [],
      confirmed_at: "2026-05-14T09:00:00Z",
      applied_count: 1,
      scope: "process",
    });
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_brief", {
      view: "digest",
      since: "2026-05-14T00:00:00Z",
      until: "2026-05-14T23:59:59Z",
    });
    const s = r.result.structuredContent;
    expect(s.content).toContain("[Confirmed test rule.](Brain/preferences/pref-confirmed-rule.md)");
    expect(s.content).not.toContain("[[pref-confirmed-rule|Confirmed test rule.]]");
  });

  test("format=json returns valid JSON content", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_brief", { view: "digest", format: "json" });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.format).toBe("json");
    // Content must parse as JSON with the design-doc shape.
    const parsed = JSON.parse(s.content);
    expect(parsed.schema_version).toBe(1);
    expect(parsed.summary).toBeDefined();
    expect(parsed.summary.empty).toBe(true);
  });
});

// ---------------------------------------------------------------------------
// brain_query
// ---------------------------------------------------------------------------

describe("brain_query", () => {
  function seedPref(slug: string): void {
    writePreference(vault, {
      slug,
      topic: slug,
      principle: `Rule for ${slug}`,
      created_at: "2026-05-14T10:00:00Z",
      unconfirmed_until: "2026-05-28T10:00:00Z",
      status: "unconfirmed",
      evidenced_by: [`[[sig-2026-05-14-${slug}]]`],
      confirmed_at: null,
      scope: "writing",
    });
  }

  test("by preference returns preference + evidence", async () => {
    seedPref("query-pref");
    // Append an apply-evidence event so the trail is non-empty.
    const server = makeServer();
    await initialize(server);
    await call(server, "brain_apply_evidence", {
      pref_id: "pref-query-pref",
      artifact: "[[doc]]",
      result: "applied",
    });
    const r = await call(server, "brain_query", {
      preference: "pref-query-pref",
    });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.mode).toBe("preference");
    expect(s.preference.id).toBe("pref-query-pref");
    expect(s.evidence.length).toBe(1);
    expect(s.evidence[0].event_type).toBe("apply-evidence");
  });

  test("by topic returns signals + preference + log events", async () => {
    // Seed both a signal and a preference on the same topic.
    writeSignal(vault, {
      topic: "topic-query-rule",
      signal: "positive",
      agent: "claude",
      principle: "Whatever.",
      created_at: "2026-05-14T10:00:00Z",
      date: "2026-05-14",
      slug: "topic-query-rule",
    });
    seedPref("topic-query-rule");
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_query", {
      topic: "topic-query-rule",
    });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.mode).toBe("topic");
    expect(s.topic).toBe("topic-query-rule");
    expect(s.signals.length).toBe(1);
    expect(s.preference).not.toBeNull();
    expect(s.preference.id).toBe("pref-topic-query-rule");
  });

  test("by since returns log events from the cutoff onward", async () => {
    seedPref("since-rule");
    const server = makeServer();
    await initialize(server);
    await call(server, "brain_apply_evidence", {
      pref_id: "pref-since-rule",
      artifact: "[[a]]",
      result: "applied",
    });
    const r = await call(server, "brain_query", {
      since: "1970-01-01T00:00:00Z",
    });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.mode).toBe("since");
    expect(s.events.length).toBeGreaterThanOrEqual(1);
    expect(s.events[0].event_type).toBe("apply-evidence");
  });

  test("requires exactly one selector", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_query", {});
    expect(r.error.code).toBe(-32602);

    const r2 = await call(server, "brain_query", {
      preference: "pref-x",
      topic: "y",
    });
    expect(r2.error.code).toBe(-32602);
  });

  test("unknown preference yields tool-level error (isError true)", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_query", {
      preference: "pref-not-here",
    });
    expect(r.error).toBeUndefined();
    expect(r.result.isError).toBe(true);
    expect(r.result.content[0].text).toContain("no preference");
  });
});

// ---------------------------------------------------------------------------
// brain_doctor
// ---------------------------------------------------------------------------

describe("brain_doctor", () => {
  test("clean vault returns ok=true with no issues", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_doctor", {});
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.ok).toBe(true);
    expect(s.errors).toEqual([]);
    expect(s.warnings).toEqual([]);
  });

  test("corrupted preference file surfaces as a doctor issue", async () => {
    // Write a preference file with broken YAML to trip a parse error.
    const dirs = brainDirs(vault);
    atomicWriteFileSync(
      join(dirs.preferences, "pref-broken.md"),
      "---\nkind: brain-preference\nid: pref-broken\n---\n# garbage with no required fields\n",
    );
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_doctor", { strict: true });
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    // At least one issue must be surfaced — either a warning or an error.
    expect(s.errors.length + s.warnings.length).toBeGreaterThan(0);
  });

  test("v0.10.15 surfaces suggested_actions alongside errors/warnings", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_doctor", {});
    const s = r.result.structuredContent;
    expect(Array.isArray(s.suggested_actions)).toBe(true);
    // Empty vault → empty actions array, but the field is always
    // present so MCP clients can rely on the shape.
  });

  test("repair:true previews a WAL-gap fix without writing; apply performs it", async () => {
    // Plant a dangling dream workrun (WAL gap).
    const runs = join(vault, "Brain", "log", "dream-runs");
    mkdirSync(runs, { recursive: true });
    const wr = join(runs, "run-mcp.jsonl");
    writeFileSync(
      wr,
      JSON.stringify({ phase: "started", at: "2026-07-18T00:00:00.000Z", run_id: "run-mcp" }) +
        "\n",
      "utf8",
    );
    const before = readFileSync(wr, "utf8");

    const server = makeServer();
    await initialize(server);

    const preview = await call(server, "brain_doctor", { repair: true });
    expect(preview.result.isError).toBe(false);
    const p = preview.result.structuredContent;
    expect(p.repair.dryRun).toBe(true);
    expect(p.repair.applied.length).toBe(1);
    expect(readFileSync(wr, "utf8")).toBe(before); // nothing written

    const applied = await call(server, "brain_doctor", { repair: true, apply: true });
    const a = applied.result.structuredContent;
    expect(a.repair.dryRun).toBe(false);
    expect(a.repair.applied.length).toBe(1);
    expect(readFileSync(wr, "utf8")).toContain("interrupted");
  });
});

// ---------------------------------------------------------------------------
// brain_status
// ---------------------------------------------------------------------------

describe("brain_status", () => {
  test("clean vault reports healthy with no problems", async () => {
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_status", {});
    expect(r.result.isError).toBe(false);
    const s = r.result.structuredContent;
    expect(s.healthy).toBe(true);
    expect(s.problems).toEqual([]);
  });

  test("a dangling workrun surfaces a problem carrying a next command", async () => {
    const runs = join(vault, "Brain", "log", "dream-runs");
    mkdirSync(runs, { recursive: true });
    writeFileSync(
      join(runs, "run-status.jsonl"),
      JSON.stringify({ phase: "started", at: "2026-07-18T00:00:00.000Z", run_id: "run-status" }) +
        "\n",
      "utf8",
    );
    const server = makeServer();
    await initialize(server);
    const r = await call(server, "brain_status", {});
    const s = r.result.structuredContent;
    expect(s.healthy).toBe(false);
    expect(s.problems.length).toBeGreaterThan(0);
    for (const p of s.problems) {
      expect(typeof p.nextCommand).toBe("string");
      expect(p.nextCommand.startsWith("o2b ")).toBe(true);
    }
  });
});

// ---------------------------------------------------------------------------
// Advertised-tool deprecation guard
// ---------------------------------------------------------------------------

describe("deprecated MCP tools — advertised list", () => {
  test("`event_log_append` and `second_brain_capture` are NOT in the registry", () => {
    const names = new Set(buildToolTable().map((t) => t.name));
    expect(names.has("event_log_append")).toBe(false);
    expect(names.has("second_brain_capture")).toBe(false);
  });

  test("all Brain tools are advertised", () => {
    const names = new Set(buildToolTable().map((t) => t.name));
    for (const expected of [
      "brain_feedback",
      "brain_dream",
      "brain_apply_evidence",
      "brain_brief",
      "brain_query",
      "brain_doctor",
      "brain_backlinks",
    ]) {
      expect(names.has(expected)).toBe(true);
    }
  });
});

// ---------------------------------------------------------------------------
// brain_backlinks
// ---------------------------------------------------------------------------

describe("brain_backlinks", () => {
  test("returns inbound refs for a referenced preference", async () => {
    const server = makeServer();
    await initialize(server);
    writePreference(vault, {
      slug: "tgt",
      topic: "t",
      principle: "target rule",
      created_at: "2026-05-01T00:00:00Z",
      unconfirmed_until: "2026-05-30T00:00:00Z",
      status: "unconfirmed",
      evidenced_by: [],
    });
    writePreference(vault, {
      slug: "src",
      topic: "s",
      principle: "source rule",
      created_at: "2026-05-01T00:00:00Z",
      unconfirmed_until: "2026-05-30T00:00:00Z",
      status: "unconfirmed",
      evidenced_by: ["[[pref-tgt]]"],
    });

    const r = (await call(server, "brain_backlinks", { id: "pref-tgt" })) as any;
    const s = r.result.structuredContent;
    expect(s.id).toBe("pref-tgt");
    // pref-src references pref-tgt once (evidenced_by). The pref body
    // mirrors evidenced_by under `## Origin`, but the index dedupes
    // by (source, target) so the count is exactly 1.
    expect(s.count).toBe(1);
    const sources = s.refs.map((x: any) => x.source);
    expect(sources).toContain("pref-src");
  });

  test("count is zero when nobody references the id", async () => {
    const server = makeServer();
    await initialize(server);
    const r = (await call(server, "brain_backlinks", { id: "pref-orphan" })) as any;
    const s = r.result.structuredContent;
    expect(s.id).toBe("pref-orphan");
    expect(s.count).toBe(0);
    expect(s.refs).toEqual([]);
  });

  test("missing id raises an INVALID_PARAMS error envelope", async () => {
    const server = makeServer();
    await initialize(server);
    const r = (await call(server, "brain_backlinks", {})) as any;
    // Missing required arg is INVALID_PARAMS at the JSON-RPC layer
    // (the handler throws MCPError before producing a tool result).
    expect(r.error).toBeDefined();
    expect(r.error.message).toContain("id");
  });
});

// ---------------------------------------------------------------------------
// brain_note (§32B, v0.10.8)
// ---------------------------------------------------------------------------

function logFilesForLoggedAt(vaultDir: string, loggedAt: string): { md: string; jsonl: string } {
  // Derive the date from the tool's own `logged_at` payload instead
  // of `new Date()`. This avoids a flake if the test happens to cross
  // `00:00:00Z` between the `brain_note` call and the file lookup.
  const day = loggedAt.slice(0, 10);
  return {
    md: logPath(vaultDir, day),
    jsonl: logJsonlPath(vaultDir, day),
  };
}

describe("brain_note", () => {
  test("appends a note event to both markdown and JSONL", async () => {
    const server = makeServer();
    await initialize(server);
    const r = (await call(server, "brain_note", {
      text: "v0.10.7 shipped",
    })) as any;

    const payload = JSON.parse(r.result.content[0].text);
    expect(payload.agent).toBe("claude");
    expect(typeof payload.logged_at).toBe("string");

    const paths = logFilesForLoggedAt(vault, payload.logged_at);
    expect(existsSync(paths.md)).toBe(true);
    expect(existsSync(paths.jsonl)).toBe(true);
    const md = readFileSync(paths.md, "utf8");
    expect(md).toMatch(/— note$/m);
    expect(md).toContain("text: v0.10.7 shipped");
    expect(md).toContain("agent: claude");

    const jsonlLines = readFileSync(paths.jsonl, "utf8").trim().split("\n");
    const last = JSON.parse(jsonlLines[jsonlLines.length - 1]!);
    expect(last.kind).toBe("note");
    expect(last.payload.text).toBe("v0.10.7 shipped");
    expect(last.payload.agent).toBe("claude");
  });

  test("redacts secret-shaped tokens before writing", async () => {
    const server = makeServer();
    await initialize(server);
    const r = (await call(server, "brain_note", {
      text: "deployed api_key=sk-abc123 to prod",
    })) as any;
    const payload = JSON.parse(r.result.content[0].text);

    const paths = logFilesForLoggedAt(vault, payload.logged_at);
    const md = readFileSync(paths.md, "utf8");
    expect(md).toContain("***REDACTED***");
    expect(md).not.toContain("sk-abc123");
  });

  test("collapses multi-line input to one space-joined line", async () => {
    const server = makeServer();
    await initialize(server);
    const r = (await call(server, "brain_note", {
      text: "line one\nline two",
    })) as any;
    const payload = JSON.parse(r.result.content[0].text);

    const paths = logFilesForLoggedAt(vault, payload.logged_at);
    const md = readFileSync(paths.md, "utf8");
    expect(md).toContain("text: line one line two");
  });

  test("respects the agent override", async () => {
    const server = makeServer();
    await initialize(server);
    const r = (await call(server, "brain_note", {
      text: "shipped X",
      agent: "explicit-bot",
    })) as any;
    const payload = JSON.parse(r.result.content[0].text);
    expect(payload.agent).toBe("explicit-bot");
  });

  test("rejects whitespace-only text", async () => {
    const server = makeServer();
    await initialize(server);
    const r = (await call(server, "brain_note", { text: "   " })) as any;
    // The shared `coerceStr` helper treats whitespace as missing
    // before the handler's own check fires — same shape as every
    // other "required string field" rejection.
    expect(r.error).toBeDefined();
    expect(r.error.message).toMatch(/missing required argument: text|text is required/);
  });

  test("rejects missing text", async () => {
    const server = makeServer();
    await initialize(server);
    const r = (await call(server, "brain_note", {})) as any;
    expect(r.error).toBeDefined();
  });
});

describe("brain_note tool schema visibility", () => {
  test("brain_note is advertised in the full tool list", async () => {
    const server = makeServer();
    await initialize(server);
    const r = (await server.handleRequest({
      jsonrpc: JSONRPC_VERSION,
      id: 51,
      method: "tools/list",
    })) as any;
    const names = (r.result.tools as Array<{ name: string }>).map((t) => t.name);
    expect(names).toContain("brain_note");
  });

  test("brain_note belongs to the writer tool scope", () => {
    const writer = buildToolTable("writer").map((t) => t.name);
    expect(writer).toEqual(
      expect.arrayContaining([
        "brain_feedback",
        "brain_apply_evidence",
        "brain_note",
        "brain_pinned_context",
        // v0.10.10 added the `brain_context` reader to the same scope
        // so runtimes without a SessionStart hook can fetch active.md
        // without going through ToolSearch.
        "brain_context",
      ]),
    );
    expect(writer).toHaveLength(5);
  });
});

describe("brain_pinned_context", () => {
  test("reads missing pinned context as an empty payload", async () => {
    const server = makeServer();
    await initialize(server);
    const r = (await call(server, "brain_pinned_context", { operation: "read" })) as any;
    expect(r.result.isError).toBe(false);
    const pinned = r.result.structuredContent;
    expect(pinned.operation).toBe("read");
    expect(pinned.present).toBe(false);
    expect(pinned.content).toBe("");
    expect(pinned.path).toBe("Brain/pinned.md");
    expect(pinned.absolute_path).toBe(brainPinnedPath(vault));
  });

  test("writes, appends, and clears pinned context", async () => {
    const server = makeServer();
    await initialize(server);

    const written = (await call(server, "brain_pinned_context", {
      operation: "write",
      content: "Remember api_key=abc <private>hidden</private>",
    })) as any;
    expect(written.result.structuredContent.content).toContain("api_key=***REDACTED***");
    expect(written.result.structuredContent.content).toContain("***PRIVATE***");
    expect(written.result.structuredContent.content).not.toContain("hidden");

    const appended = (await call(server, "brain_pinned_context", {
      operation: "append",
      content: "Second fact",
    })) as any;
    expect(appended.result.structuredContent.content).toContain("\n\nSecond fact");

    const cleared = (await call(server, "brain_pinned_context", { operation: "clear" })) as any;
    expect(cleared.result.structuredContent.content).toBe("");
    expect(readFileSync(brainPinnedPath(vault), "utf8")).toBe("");
  });

  test("brain_context includes pinned content as structured data and text", async () => {
    const server = makeServer();
    await initialize(server);
    await call(server, "brain_pinned_context", {
      operation: "write",
      content: "Current task: fix MCP boundary tests.",
    });

    const r = (await call(server, "brain_context", {})) as any;
    const context = r.result.structuredContent;
    expect(context.pinned).toEqual({
      present: true,
      path: "Brain/pinned.md",
      absolute_path: brainPinnedPath(vault),
      content: "Current task: fix MCP boundary tests.",
    });
    expect(context.content).toContain("## Pinned context");
    expect(context.content).toContain("Current task: fix MCP boundary tests.");
  });
});