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
/**
* `o2b brain doctor` names its exits (no-dead-ends, task 4).
*
* The doctor is the densest diagnosis surface in the product and, until
* this task, the only consumer of {@link DIAGNOSTIC_SIGNALS} it was NOT:
* it printed `[WARN] <code>: <message>` and stopped, leaving the caller
* to re-derive the repair. Every reported issue now goes through the
* advisory rail, so the human surface prints the structural command and
* the JSON surface carries it as a field.
*
* Three obligations are pinned here. A registered code names its command
* on both surfaces. An unregistered code names nothing on either - the
* doctor must be able to report an issue it has no exit for without
* inventing one. And a clean vault is byte-for-byte what it was before,
* because a surface that gained a line when it had nothing to say would
* be chrome, not a next step.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { DIAGNOSTIC_SIGNALS } from "../../src/core/brain/diagnostics.ts";
import { DOCTOR_EXIT_EXCLUSIONS } from "../../src/core/brain/doctor-exits.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { runCli } from "../helpers/run-cli.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);
/** Two registered doctor codes that share one structural command. */
const REPAIR_COMMAND = DIAGNOSTIC_SIGNALS.get("broken-wikilink")!.nextCommand;
/** A registered doctor code with a command of its own. */
const BACKLINKS_COMMAND = DIAGNOSTIC_SIGNALS.get("broken-backlinks")!.nextCommand;
let tmp: string;
let vault: string;
let config: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-doctor-next-step-"));
vault = join(tmp, "vault");
config = join(tmp, "config.yaml");
writeFileSync(config, `vault: ${vault}\nagent_name: test-agent\n`);
bootstrapBrain(vault, { configPath: config });
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
/**
* Seed two registered warning classes that resolve to the SAME command
* (`broken-wikilink` from the dead evidence pointer, `dangling-workrun`
* from the unterminated journal) plus one that resolves to a different
* one (`broken-backlinks`, raised by the same dead pointer).
*/
function seedRegisteredIssues(): void {
const runs = join(vault, "Brain", "log", "dream-runs");
mkdirSync(runs, { recursive: true });
writeFileSync(
join(runs, "run-next-step.jsonl"),
JSON.stringify({ phase: "started", at: "2026-07-18T00:00:00.000Z", run_id: "run-next-step" }) +
"\n",
"utf8",
);
writePreference(vault, {
slug: "dead-pointer",
topic: "dead-pointer",
principle: "a rule whose evidence pointer went missing",
created_at: "2026-05-14T10:00:00Z",
unconfirmed_until: "2026-05-28T10:00:00Z",
status: "unconfirmed",
evidenced_by: ["[[sig-does-not-exist]]"],
});
}
/**
* Seed `status-folder-mismatch`: a real doctor code with no registry
* entry, and the only issue in the vault. The status is rewritten after
* the write because the writer refuses to emit a folder-inconsistent
* one - which is the point of the lint.
*/
function seedUnregisteredIssue(): void {
writePreference(vault, {
slug: "mismatch",
topic: "mismatch",
principle: "a rule filed under the wrong folder",
created_at: "2026-05-14T10:00:00Z",
unconfirmed_until: "2026-05-28T10:00:00Z",
status: "unconfirmed",
evidenced_by: [],
});
const path = join(vault, "Brain", "preferences", "pref-mismatch.md");
writeFileSync(
path,
readFileSync(path, "utf8").replace("_status: unconfirmed", "_status: retired"),
"utf8",
);
}
/** Every `next:` line in `stdout`, in order. */
function nextLines(stdout: string): string[] {
return stdout.split("\n").filter((line) => line.startsWith("next: "));
}
describe("brain doctor - the human surface names the command", () => {
test("a registered code prints its structural next command", async () => {
seedRegisteredIssues();
const r = await runCli(["brain", "doctor", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
expect(r.stdout).toContain("[WARN] broken-wikilink:");
expect(nextLines(r.stdout)).toContain(`next: ${REPAIR_COMMAND}`);
expect(nextLines(r.stdout)).toContain(`next: ${BACKLINKS_COMMAND}`);
});
test("two codes sharing one command print that command once", async () => {
seedRegisteredIssues();
const r = await runCli(["brain", "doctor", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
// `broken-wikilink` and `dangling-workrun` both exit through the
// repair verb. Two identical lines would be noise, not a next step.
expect(r.stdout).toContain("[WARN] broken-wikilink:");
expect(r.stdout).toContain("[WARN] dangling-workrun:");
const repeated = nextLines(r.stdout).filter((line) => line === `next: ${REPAIR_COMMAND}`);
expect(repeated).toHaveLength(1);
});
test("an unregistered code prints no next step at all", async () => {
seedUnregisteredIssue();
const r = await runCli(["brain", "doctor", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
expect(r.stdout).toContain("[WARN] status-folder-mismatch:");
// The seeded legacy tree has something to move, so the store-migration
// advice prints its own next step exactly once; the unregistered code
// adds none.
expect(nextLines(r.stdout)).toEqual(["next: o2b brain migrate-store --dry-run"]);
});
});
describe("brain doctor --json - the field, never the line", () => {
test("a registered issue carries next_command and stdout still parses", async () => {
seedRegisteredIssues();
const r = await runCli(["brain", "doctor", "--vault", vault, "--json"], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
expect(r.stdout).not.toContain("next: ");
const payload = JSON.parse(r.stdout) as {
warnings: ReadonlyArray<{ code: string; next_command?: string }>;
};
const wikilink = payload.warnings.find((w) => w.code === "broken-wikilink");
expect(wikilink?.next_command).toBe(REPAIR_COMMAND);
const backlinks = payload.warnings.find((w) => w.code === "broken-backlinks");
expect(backlinks?.next_command).toBe(BACKLINKS_COMMAND);
});
test("an unregistered issue carries no next_command key", async () => {
seedUnregisteredIssue();
const r = await runCli(["brain", "doctor", "--vault", vault, "--json"], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
const payload = JSON.parse(r.stdout) as {
warnings: ReadonlyArray<Record<string, unknown>>;
};
const mismatch = payload.warnings.find((w) => w["code"] === "status-folder-mismatch");
expect(mismatch).toBeDefined();
expect(Object.hasOwn(mismatch!, "next_command")).toBe(false);
});
});
describe("brain doctor - silence is explained, not merely silent", () => {
test("a code with no exit says so, with the published reason", async () => {
seedUnregisteredIssue();
const r = await runCli(["brain", "doctor", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
expect(r.stdout).toContain(
`no exit: status-folder-mismatch - ${DOCTOR_EXIT_EXCLUSIONS.get("status-folder-mismatch")!}`,
);
});
test("a registered code contributes no explanation - it has a command instead", async () => {
seedRegisteredIssues();
const r = await runCli(["brain", "doctor", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.stdout).not.toContain("no exit: broken-wikilink");
});
test("--json carries the reasons once per code, off the issue records", async () => {
seedUnregisteredIssue();
const r = await runCli(["brain", "doctor", "--vault", vault, "--json"], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.stdout).not.toContain("no exit: ");
const payload = JSON.parse(r.stdout) as {
no_exit?: Record<string, string>;
warnings: ReadonlyArray<Record<string, unknown>>;
};
expect(payload.no_exit?.["status-folder-mismatch"]).toBe(
DOCTOR_EXIT_EXCLUSIONS.get("status-folder-mismatch")!,
);
// The reason rides once, beside the streams - never repeated per issue.
const mismatch = payload.warnings.find((w) => w["code"] === "status-folder-mismatch");
expect(Object.hasOwn(mismatch!, "no_exit")).toBe(false);
});
});
describe("brain doctor - byte-identical when there is nothing to point at", () => {
test("a clean vault prints exactly what it printed before", async () => {
const r = await runCli(["brain", "doctor", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
expect(r.stdout).toBe("brain doctor: clean\n");
});
test("a clean vault's JSON payload carries no findings and the count-only archive section", async () => {
const r = await runCli(["brain", "doctor", "--vault", vault, "--json"], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
// The answer-trust wave adds one informational, count-only archive
// section to the doctor's JSON payload, and its key is deliberately
// ALWAYS present (the capture_scope field pattern: a caller never
// infers the section's existence from a missing key). What the
// byte-identical promise continues to guard is the finding surface: a
// clean vault carries no warnings, no errors, and none of the
// next-command or no-exit noise - and the human-readable path stays
// fully byte-identical (the test above).
expect(r.stdout).toBe(
JSON.stringify(
{
warnings: [],
errors: [],
archives: { entries: 0, totalBytes: 0, missing: 0, mismatched: 0, uncited: 0 },
},
null,
2,
) + "\n",
);
});
});