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
6.5 KB
Raw Blame
/**
 * `o2b brain orphan-repair` (t_6cc80627). The verb is the only door to
 * the detach repair: dry-run is the default and writes nothing; --apply
 * requires the exact --confirm phrase; a rerun converges to zero writes.
 *
 * The last describe pins the boundary the design states rather than
 * discovers: the doctor pass REPORTS the orphan and never repairs it,
 * and the verb is not wired into the pass - the repair is reachable only
 * by an operator typing the command.
 */

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

import { runCli } from "../helpers/run-cli.ts";
import { ORPHAN_SESSION_REPAIR_COMMAND } from "../../src/core/brain/doctor/orphan-session-check.ts";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { signalPath as brainSignalPath } from "../../src/core/brain/paths.ts";
import { writeSignal } from "../../src/core/brain/signal.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

/** Event date and slug of the single fixture signal; the production
 * path builder composes the same file name from them. */
const FIXTURE_DATE = "2026-06-01";
const FIXTURE_SLUG = "orphan";

let tmp: string;
let vault: string;
let config: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-orphan-repair-cli-"));
  vault = join(tmp, "vault");
  config = join(tmp, "config.yaml");
  writeFileSync(config, `vault: "${vault}"\n`);
  bootstrapBrain(vault, { configPath: config });
  writeOrphan();
});

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

function signalPath(): string {
  // The production path builder derives the exact file name from the
  // date and slug the fixture writes with. Walking the inbox would be
  // fragile: readdirSync order is filesystem-defined, and the bootstrap
  // also places the `archived/` and `processed/` sibling directories
  // there, so on some filesystems the first entry is a directory.
  return brainSignalPath(vault, FIXTURE_DATE, FIXTURE_SLUG);
}

function writeOrphan(): void {
  // The canonical writer, so the doctor's own record check parses the
  // fixture cleanly and the only finding in play is the orphan itself.
  writeSignal(vault, {
    topic: FIXTURE_SLUG,
    signal: "positive",
    agent: "tester",
    principle: "observations keep their provenance",
    created_at: "2026-06-01T00:00:00Z",
    date: FIXTURE_DATE,
    slug: FIXTURE_SLUG,
    source_type: "session",
    source: ["[[session:sess-gone#turn-1]]"],
    session_ref: "session:sess-gone#turn-1",
    raw: "the observation body",
  });
}

const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: config });

test("dry-run reports the detach and writes nothing", async () => {
  const before = readFileSync(signalPath(), "utf8");
  const res = await runCli(["brain", "orphan-repair", "--json"], { env: env() });
  expect(res.returncode).toBe(0);
  const report = JSON.parse(res.stdout) as { mode: string; detached: number; decisions: unknown[] };
  expect(report.mode).toBe("dry-run");
  expect(report.detached).toBe(1);
  expect(report.decisions.length).toBe(1);
  expect(readFileSync(signalPath(), "utf8")).toBe(before);
});

test("apply without the exact confirmation phrase is refused", async () => {
  const res = await runCli(["brain", "orphan-repair", "--apply", "--confirm", "nope"], {
    env: env(),
  });
  expect(res.returncode).not.toBe(0);
  expect(readFileSync(signalPath(), "utf8")).toContain("session_ref:");
});

test("a refused apply under --json emits a JSON error envelope, not plain text", async () => {
  const res = await runCli(["brain", "orphan-repair", "--apply", "--confirm", "nope", "--json"], {
    env: env(),
  });
  expect(res.returncode).toBe(1);
  const parsed = JSON.parse(res.stdout) as { ok: boolean; message: string };
  expect(parsed.ok).toBe(false);
  expect(parsed.message).toContain("confirmation phrase");
});

test("apply with the exact phrase detaches the reference, and a rerun is a no-op", async () => {
  const applied = await runCli(
    ["brain", "orphan-repair", "--apply", "--confirm", "apply orphan repair", "--json"],
    { env: env() },
  );
  expect(applied.returncode).toBe(0);
  const first = JSON.parse(applied.stdout) as { detached: number };
  expect(first.detached).toBe(1);
  const after = readFileSync(signalPath(), "utf8");
  expect(after).not.toContain("session_ref:");
  expect(after).toContain("the observation body");

  const rerun = await runCli(
    ["brain", "orphan-repair", "--apply", "--confirm", "apply orphan repair", "--json"],
    { env: env() },
  );
  const second = JSON.parse(rerun.stdout) as { detached: number };
  expect(second.detached).toBe(0);
  expect(readFileSync(signalPath(), "utf8")).toBe(after);
});

test("the doctor pass reports the orphan and never repairs it", async () => {
  const before = readFileSync(signalPath(), "utf8");
  const res = await runCli(["brain", "doctor", "--json"], { env: env() });
  expect(res.returncode).toBe(0);
  const report = JSON.parse(res.stdout) as { warnings: Array<{ code: string; fix?: string }> };
  const orphan = report.warnings.filter((w) => w.code === "orphan-session-ref");
  expect(orphan.length).toBe(1);
  expect(orphan[0]!.fix).toBe(ORPHAN_SESSION_REPAIR_COMMAND);
  // The pass is read-only: the dangling reference is still on disk after
  // the doctor ran, and the repair it names is the verb's to make.
  expect(readFileSync(signalPath(), "utf8")).toBe(before);
});

test("the repair is not wired into the doctor pass", () => {
  // A source-level boundary: no doctor module may import the repair or
  // reach the verb, so a future refactor cannot make `runDoctor` mutate.
  const doctorDir = join(import.meta.dir, "..", "..", "src", "core", "brain", "doctor");
  const modules = [join(doctorDir, "..", "doctor.ts")];
  for (const entry of readdirSync(doctorDir)) {
    if (entry.endsWith(".ts")) modules.push(join(doctorDir, entry));
  }
  // A module path containing the repair, on a `from` clause - never
  // prose: the check module's docblock names the repair module as the
  // write half it must not become, and must stay free to do so.
  const IMPORT_RE = /^[^\n]*\bfrom\s+"[^"]*orphan-repair[^"]*";/m;
  for (const path of modules) {
    const source = readFileSync(path, "utf8");
    expect(`${path} imports repair: ${IMPORT_RE.test(source)}`).toBe(
      `${path} imports repair: false`,
    );
  }
});