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
18.4 KB
Raw Blame
/**
 * The `brain_lifecycle` `correct` action and the `o2b brain lifecycle
 * correct` CLI verb (truth-correctable-time-aware, Task 17).
 *
 * Both surfaces expose the correct-verb sweep core with `dry_run`
 * defaulting to true, a `flatly_wrong` flag, an optional `window_end`,
 * and reach-gated targets: a target the caller may not read is refused
 * as missing before anything is written. The receipt reason codes stay
 * the existing vocabulary, name-aligned with the verb and action
 * (`supersede` for validity_close, `tombstone` for tombstone).
 */

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

import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
import { parseFrontmatter } from "../../src/core/vault.ts";
import { appendClaimEvent, readClaimEvents } from "../../src/core/brain/truth/store.ts";
import {
  buildReachLogFixture,
  reachServer,
  type ReachLogFixture,
} from "../helpers/reach-log-fixture.ts";
import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../src/core/graph/visibility.ts";
import { cmdBrainLifecycle } from "../../src/cli/brain/verbs/lifecycle.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { tempDirs } from "../helpers/temp-dir.ts";

const savedConfig = process.env["OPEN_SECOND_BRAIN_CONFIG"];

afterAll(() => {
  if (savedConfig === undefined) delete process.env["OPEN_SECOND_BRAIN_CONFIG"];
  else process.env["OPEN_SECOND_BRAIN_CONFIG"] = savedConfig;
});

const mkTemp = tempDirs();

let vault: string;
let configHome: string;
let configPath: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-lifecycle-correct-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-lifecycle-correct-cfg-"));
  configPath = join(configHome, "config.yaml");
  atomicWriteFileSync(configPath, `vault: ${vault}\n`);
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
  rmSync(configHome, { recursive: true, force: true });
});

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

async function call(
  server: MCPServer,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const response = (await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 9,
    method: "tools/call",
    params: { name: "brain_lifecycle", arguments: args },
  })) as { result?: { content: ReadonlyArray<{ type: string; text: string }> }; error?: unknown };
  if (response.error !== undefined) return { error: response.error } as Record<string, unknown>;
  return JSON.parse(response.result!.content[0]!.text) as Record<string, unknown>;
}

function seedPair(): { target: string; successor: string } {
  mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
  const target = "Brain/preferences/pref-old.md";
  writeFileSync(
    join(vault, target),
    [
      "---",
      "kind: brain-preference",
      "id: pref-old",
      "_status: confirmed",
      "created_at: 2026-05-01T00:00:00Z",
      "unconfirmed_until: 2026-05-01T00:00:00Z",
      "_confirmed_at: 2026-05-01T00:00:00Z",
      "_evidenced_by: []",
      "tags: [brain, brain/preference]",
      "topic: deploy-timeout",
      "principle: Deploy timeout stays at thirty seconds.",
      "pinned: false",
      "---",
      "",
      "The rule body.",
      "",
    ].join("\n"),
  );
  const successor = "Brain/preferences/pref-new.md";
  writeFileSync(
    join(vault, successor),
    [
      "---",
      "kind: brain-preference",
      "id: pref-new",
      "_status: confirmed",
      "created_at: 2026-06-10T00:00:00Z",
      "unconfirmed_until: 2026-06-10T00:00:00Z",
      "_confirmed_at: 2026-06-10T00:00:00Z",
      "_evidenced_by: []",
      "tags: [brain, brain/preference]",
      "topic: deploy-timeout",
      "principle: Deploy timeout is two minutes.",
      "pinned: false",
      "---",
      "",
      "The corrected rule body.",
      "",
    ].join("\n"),
  );
  appendClaimEvent(vault, {
    ts: "2026-05-02T00:00:00Z",
    agent: "tester",
    entity: "deploy timeout",
    aspect: "limit",
    value: "30s",
    source: "[[Brain/preferences/pref-old.md]]",
  });
  return { target, successor };
}

describe("brain_lifecycle correct", () => {
  test("dry_run defaults to true and writes nothing", async () => {
    const { target } = seedPair();
    const before = readFileSync(join(vault, target), "utf8");
    const eventsBefore = readClaimEvents(vault).events.length;

    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const res = await call(server, {
      action: "correct",
      target,
      value: "two minutes",
      successor: "pref-new",
      reason: "the timeout changed",
    });

    expect(res["dry_run"]).toBe(true);
    const blast = res["blast_radius"] as Record<string, unknown>;
    expect(blast["target"]).toBe(target);
    expect(Array.isArray(blast["claims"])).toBe(true);
    expect((blast["claims"] as unknown[]).length).toBe(1);
    expect(readFileSync(join(vault, target), "utf8")).toBe(before);
    expect(readClaimEvents(vault).events.length).toBe(eventsBefore);
  });

  test("an applied validity-close retires with the supersede reason code", async () => {
    const { target } = seedPair();
    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const res = await call(server, {
      action: "correct",
      target,
      value: "two minutes",
      successor: "pref-new",
      reason: "the timeout changed",
      dry_run: false,
    });

    expect(res["dry_run"]).toBe(false);
    const retirements = res["retirements"] as ReadonlyArray<Record<string, unknown>>;
    expect(retirements.length).toBe(1);
    expect(retirements[0]!["end_state"]).toBe("validity_close");
    expect(retirements[0]!["reason_code"]).toBe("supersede");

    const meta = parseFrontmatter(join(vault, target))[0] as Record<string, unknown>;
    expect(meta["_status"]).toBe("confirmed");
    // The wall clock owns the close instant; the pin is its canonical
    // ISO-8601 UTC second shape, not which instant it names.
    expect(meta["valid_until"]).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
    expect(meta["superseded_by"]).toBe("[[pref-new]]");

    const receipts = res["receipts"] as ReadonlyArray<Record<string, unknown>>;
    expect(receipts.every((r) => r["appended"] === true)).toBe(true);
  });

  test("a flatly-wrong correction tombstones with the tombstone reason code", async () => {
    const { target } = seedPair();
    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const res = await call(server, {
      action: "correct",
      target,
      value: "the number was never thirty seconds",
      successor: "pref-new",
      flatly_wrong: true,
      reason: "fabricated figure",
      dry_run: false,
    });

    const retirements = res["retirements"] as ReadonlyArray<Record<string, unknown>>;
    expect(retirements[0]!["end_state"]).toBe("tombstone");
    expect(retirements[0]!["reason_code"]).toBe("tombstone");
    expect(retirements[0]!["valid_until"]).toBeNull();
    const meta = parseFrontmatter(join(vault, target))[0] as Record<string, unknown>;
    expect(meta["_status"]).toBe("tombstoned");
  });

  test("an optional window_end closes validity there", async () => {
    const { target } = seedPair();
    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const res = await call(server, {
      action: "correct",
      target,
      successor: "pref-new",
      window_end: "2026-07-01T00:00:00Z",
      reason: "the timeout changed",
      dry_run: false,
    });
    const retirements = res["retirements"] as ReadonlyArray<Record<string, unknown>>;
    expect(retirements[0]!["valid_until"]).toBe("2026-07-01T00:00:00Z");
  });

  test("a malformed window_end is refused before anything is written", async () => {
    const { target } = seedPair();
    const before = readFileSync(join(vault, target), "utf8");
    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const res = await call(server, {
      action: "correct",
      target,
      window_end: "soon after the incident",
      dry_run: false,
    });
    expect(res["error"]).toBeDefined();
    expect(readFileSync(join(vault, target), "utf8")).toBe(before);
  });

  test("a target below the caller's reach is refused as missing", async () => {
    const base = mkTemp("o2b-lifecycle-correct-reach-");
    const f: ReachLogFixture = buildReachLogFixture(base, true);
    const withheld = join(f.vault, "Brain", "preferences", "pref-withheld.md");
    writeFileSync(
      withheld,
      [
        "---",
        `visibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]`,
        "kind: brain-preference",
        "id: pref-withheld",
        "_status: confirmed",
        "created_at: 2026-05-01T00:00:00Z",
        "unconfirmed_until: 2026-05-01T00:00:00Z",
        "tags: [brain, brain/preference]",
        "topic: withheld-topic",
        "principle: Withheld from remote callers.",
        "pinned: false",
        "---",
        "",
        "Withheld body.",
        "",
      ].join("\n"),
    );
    const bytesBefore = readFileSync(withheld, "utf8");
    try {
      const server = reachServer(f, "remote");
      await initialize(server);
      const res = await call(server, {
        action: "correct",
        target: "Brain/preferences/pref-withheld.md",
        value: "two minutes",
        reason: "the timeout changed",
        dry_run: false,
      });
      expect(JSON.stringify(res)).toContain("does not exist");
      expect(readFileSync(withheld, "utf8")).toBe(bytesBefore);
    } finally {
      rmSync(base, { recursive: true, force: true });
    }
  });

  test("a remote dry run does not name a withheld mentioning page in retarget", async () => {
    const base = mkTemp("o2b-lifecycle-correct-retarget-dry-");
    const f: ReachLogFixture = buildReachLogFixture(base, true);
    try {
      const target = "Brain/preferences/pref-public.md";
      mkdirSync(join(f.vault, "Brain", "preferences"), { recursive: true });
      writeFileSync(
        join(f.vault, target),
        [
          "---",
          "kind: brain-preference",
          "id: pref-public",
          "_status: confirmed",
          "created_at: 2026-05-01T00:00:00Z",
          "unconfirmed_until: 2026-05-08T00:00:00Z",
          "tags: [brain, brain/preference]",
          "topic: public-topic",
          "principle: Readable at remote reach.",
          "pinned: false",
          "---",
          "",
          "Public body.",
          "",
        ].join("\n"),
      );
      const withheld = "Brain/inbox/sig-hidden.md";
      mkdirSync(join(f.vault, "Brain", "inbox"), { recursive: true });
      writeFileSync(
        join(f.vault, withheld),
        [
          "---",
          `visibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]`,
          "kind: brain-preference",
          "id: sig-hidden",
          "_status: confirmed",
          "created_at: 2026-05-01T00:00:00Z",
          "unconfirmed_until: 2026-05-08T00:00:00Z",
          "tags: [brain, brain/preference]",
          "topic: hidden-topic",
          "principle: Mentions [[pref-public]] while withheld.",
          "pinned: false",
          "---",
          "",
          "Hidden body referencing [[pref-public]].",
          "",
        ].join("\n"),
      );
      const server = reachServer(f, "remote");
      await initialize(server);
      const res = await call(server, { action: "correct", target });
      const retarget = res["retarget"] as Record<string, unknown>;
      expect(retarget["matched"] as ReadonlyArray<string>).not.toContain(withheld);
      expect(
        (retarget["failed"] as ReadonlyArray<Record<string, unknown>>).map((f) => f["path"]),
      ).not.toContain(withheld);
      // No response key discloses the withheld page.
      expect(JSON.stringify(res)).not.toContain("sig-hidden");
    } finally {
      rmSync(base, { recursive: true, force: true });
    }
  });

  test("a remote applied run does not rewrite a withheld mentioning page", async () => {
    const base = mkTemp("o2b-lifecycle-correct-retarget-apply-");
    const f: ReachLogFixture = buildReachLogFixture(base, true);
    try {
      const target = "Brain/preferences/pref-public.md";
      mkdirSync(join(f.vault, "Brain", "preferences"), { recursive: true });
      writeFileSync(
        join(f.vault, target),
        [
          "---",
          "kind: brain-preference",
          "id: pref-public",
          "_status: confirmed",
          "created_at: 2026-05-01T00:00:00Z",
          "unconfirmed_until: 2026-05-08T00:00:00Z",
          "tags: [brain, brain/preference]",
          "topic: public-topic",
          "principle: Readable at remote reach.",
          "pinned: false",
          "---",
          "",
          "Public body.",
          "",
        ].join("\n"),
      );
      const peer = "Brain/preferences/pref-peer.md";
      writeFileSync(
        join(f.vault, peer),
        [
          "---",
          "kind: brain-preference",
          "id: pref-peer",
          "_status: confirmed",
          "created_at: 2026-05-01T00:00:00Z",
          "unconfirmed_until: 2026-05-08T00:00:00Z",
          "tags: [brain, brain/preference]",
          "topic: peer-topic",
          "principle: Mentions [[pref-public]] in reach.",
          "pinned: false",
          "---",
          "",
          "See [[pref-public]] for the old rule.",
          "",
        ].join("\n"),
      );
      const withheld = "Brain/inbox/sig-hidden.md";
      mkdirSync(join(f.vault, "Brain", "inbox"), { recursive: true });
      writeFileSync(
        join(f.vault, withheld),
        [
          "---",
          `visibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]`,
          "kind: brain-preference",
          "id: sig-hidden",
          "_status: confirmed",
          "created_at: 2026-05-01T00:00:00Z",
          "unconfirmed_until: 2026-05-08T00:00:00Z",
          "tags: [brain, brain/preference]",
          "topic: hidden-topic",
          "principle: Mentions [[pref-public]] while withheld.",
          "pinned: false",
          "---",
          "",
          "Hidden body referencing [[pref-public]].",
          "",
        ].join("\n"),
      );
      const bytesBefore = readFileSync(join(f.vault, withheld), "utf8");
      const server = reachServer(f, "remote");
      await initialize(server);
      const res = await call(server, {
        action: "correct",
        target,
        successor: "pref-public-2",
        dry_run: false,
      });
      const retarget = res["retarget"] as Record<string, unknown>;
      expect(retarget["rewritten"] as ReadonlyArray<string>).not.toContain(withheld);
      expect(retarget["matched"] as ReadonlyArray<string>).not.toContain(withheld);
      expect(
        (retarget["failed"] as ReadonlyArray<Record<string, unknown>>).map((f) => f["path"]),
      ).not.toContain(withheld);
      // The withheld page's bytes are unchanged: no content injection.
      expect(readFileSync(join(f.vault, withheld), "utf8")).toBe(bytesBefore);
      // In-reach mentions are still retargeted.
      expect(retarget["rewritten"] as ReadonlyArray<string>).toContain(peer);
      expect(readFileSync(join(f.vault, peer), "utf8")).toContain("[[pref-public-2]]");
    } finally {
      rmSync(base, { recursive: true, force: true });
    }
  });
});

describe("o2b brain lifecycle correct", () => {
  test("dry run is the default and reports the blast radius without writing", async () => {
    const { target } = seedPair();
    const before = readFileSync(join(vault, target), "utf8");
    const eventsBefore = readClaimEvents(vault).events.length;

    const out: string[] = [];
    const originalWrite = process.stdout.write.bind(process.stdout);
    process.stdout.write = (chunk: string | Uint8Array): boolean => {
      out.push(String(chunk));
      return true;
    };
    let exit: number;
    try {
      exit = await cmdBrainLifecycle([
        "correct",
        target,
        "--value",
        "two minutes",
        "--successor",
        "pref-new",
        "--reason",
        "the timeout changed",
        "--config",
        configPath,
        "--json",
      ]);
    } finally {
      process.stdout.write = originalWrite;
    }
    expect(exit).toBe(0);
    const payload = JSON.parse(out.join("")) as Record<string, unknown>;
    expect(payload["dry_run"]).toBe(true);
    expect(readFileSync(join(vault, target), "utf8")).toBe(before);
    expect(readClaimEvents(vault).events.length).toBe(eventsBefore);
  });

  test("an applied run retires the target and reports the bundle", async () => {
    const { target } = seedPair();
    const out: string[] = [];
    const originalWrite = process.stdout.write.bind(process.stdout);
    process.stdout.write = (chunk: string | Uint8Array): boolean => {
      out.push(String(chunk));
      return true;
    };
    let exit: number;
    try {
      exit = await cmdBrainLifecycle([
        "correct",
        target,
        "--value",
        "two minutes",
        "--successor",
        "pref-new",
        "--reason",
        "the timeout changed",
        "--apply",
        "--config",
        configPath,
        "--json",
      ]);
    } finally {
      process.stdout.write = originalWrite;
    }
    expect(exit).toBe(0);
    const payload = JSON.parse(out.join("")) as Record<string, unknown>;
    expect(payload["dry_run"]).toBe(false);
    const bundleId = payload["bundle_id"] as string;
    expect(typeof bundleId).toBe("string");
    const retirements = payload["retirements"] as ReadonlyArray<Record<string, unknown>>;
    expect(retirements[0]!["reason_code"]).toBe("supersede");
    const meta = parseFrontmatter(join(vault, target))[0] as Record<string, unknown>;
    // The wall clock owns the close instant; the pin is its canonical
    // ISO-8601 UTC second shape, not which instant it names.
    expect(meta["valid_until"]).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
    expect(existsSync(join(vault, target))).toBe(true);
  });

  test("the correct verb requires a target", async () => {
    const exit = await cmdBrainLifecycle(["correct", "--config", configPath]);
    expect(exit).toBe(2);
  });
});