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
17.6 KB
Raw Blame
/**
 * Tests for src/core/brain/diagnostics.ts - the diagnostics-signal model
 * and the guarded `doctor --repair` driver (O2, t_bd6cc4cb).
 *
 * The model registry, the two fixers (WAL-gap dangling-workrun close and
 * orphaned evidenced_by prune), dry-run preview, apply + typed event, and
 * idempotency each get their own case. Fixtures use the canonical writers
 * so the inputs match what real Brain operations produce; the dangling
 * workrun is written by hand because no public writer leaves one behind.
 */

import { afterEach, 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 {
  applyRepair,
  DIAGNOSTIC_SIGNALS,
  planRepair,
  REPAIR_CODE,
  resolveSignal,
} from "../../src/core/brain/diagnostics.ts";
import { brainConfigPath, brainDirs, dreamWorkrunPath } from "../../src/core/brain/paths.ts";
import { DEFAULT_BRAIN_CONFIG_YAML } from "../../src/core/brain/config-template.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { readLogDay, listLogDates } from "../../src/core/brain/log-jsonl.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";

let tmp: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-diagnostics-"));
  const dirs = brainDirs(tmp);
  for (const d of [
    dirs.brain,
    dirs.inbox,
    dirs.processed,
    dirs.preferences,
    dirs.retired,
    dirs.log,
    dirs.snapshots,
  ]) {
    mkdirSync(d, { recursive: true });
  }
  atomicWriteFileSync(brainConfigPath(tmp), DEFAULT_BRAIN_CONFIG_YAML);
});

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

/** Write a dangling workrun (last phase is neither finalized nor interrupted). */
function writeDanglingWorkrun(runId: string): string {
  const path = dreamWorkrunPath(tmp, runId);
  mkdirSync(join(tmp, "Brain", "log", "dream-runs"), { recursive: true });
  writeFileSync(
    path,
    JSON.stringify({ phase: "started", at: "2026-07-18T00:00:00.000Z", run_id: runId }) +
      "\n" +
      JSON.stringify({ phase: "cluster_complete", at: "2026-07-18T00:00:01.000Z", run_id: runId }) +
      "\n",
    "utf8",
  );
  return path;
}

function countRepairEvents(): number {
  let n = 0;
  for (const date of listLogDates(tmp)) {
    for (const e of readLogDay(tmp, date).entries) {
      if (e.eventType === "doctor-repair") n += 1;
    }
  }
  return n;
}

/** Every logged doctor-repair event, in log order (consent assertions). */
function repairEvents(): Array<{ body: Record<string, string | ReadonlyArray<string>> }> {
  const events: Array<{ body: Record<string, string | ReadonlyArray<string>> }> = [];
  for (const date of listLogDates(tmp)) {
    for (const e of readLogDay(tmp, date).entries) {
      if (e.eventType === "doctor-repair")
        events.push(e as { body: Record<string, string | ReadonlyArray<string>> });
    }
  }
  return events;
}

describe("diagnostics-signal model", () => {
  test("fixer codes are registered as auto-repairable with a next command", () => {
    for (const code of [REPAIR_CODE.walGap, REPAIR_CODE.orphanedReference]) {
      const sig = DIAGNOSTIC_SIGNALS.get(code);
      expect(sig).toBeDefined();
      expect(sig!.autoRepairable).toBe(true);
      expect(sig!.nextCommand.length).toBeGreaterThan(0);
      expect(sig!.nextCommand.startsWith("o2b ")).toBe(true);
    }
  });

  test("resolveSignal falls back to a generic doctor hint for unknown codes", () => {
    const sig = resolveSignal("some-brand-new-lint");
    expect(sig.code).toBe("some-brand-new-lint");
    expect(sig.autoRepairable).toBe(false);
    expect(sig.nextCommand).toBe("o2b brain doctor");
  });

  test("O3 source classes carry their own next-command hint (not hardcoded downstream)", () => {
    expect(resolveSignal("stale-notes").nextCommand).toBe("o2b brain stale");
    expect(resolveSignal("hygiene-findings").nextCommand).toBe("o2b brain hygiene scan");
    expect(resolveSignal("review-queue").nextCommand).toBe("o2b brain dream --dry-run");
  });
});

describe("planRepair", () => {
  test("a clean vault plans no fixes and lists no unfixable classes", () => {
    const plan = planRepair(tmp);
    expect(plan.fixes).toEqual([]);
    expect(plan.unfixable).toEqual([]);
  });

  test("detects a dangling workrun as an applicable wal-gap fix", () => {
    writeDanglingWorkrun("run-abc");
    const plan = planRepair(tmp);
    const wal = plan.fixes.filter((f) => f.code === REPAIR_CODE.walGap);
    expect(wal).toHaveLength(1);
    expect(wal[0]!.applicable).toBe(true);
    expect(wal[0]!.target).toContain("run-abc");
  });

  test("detects a dead evidenced_by as an applicable orphaned-reference fix", () => {
    writePreference(tmp, {
      slug: "alpha",
      topic: "alpha",
      principle: "rule",
      created_at: "2026-05-14T10:00:00Z",
      unconfirmed_until: "2026-05-28T10:00:00Z",
      status: "unconfirmed",
      evidenced_by: ["[[sig-never-existed]]"],
    });
    const plan = planRepair(tmp);
    const orphan = plan.fixes.filter((f) => f.code === REPAIR_CODE.orphanedReference);
    expect(orphan).toHaveLength(1);
    expect(orphan[0]!.applicable).toBe(true);
    expect(orphan[0]!.target).toContain("sig-never-existed");
  });

  test("does not prune an evidenced_by link that points outside the Brain id space", () => {
    writePreference(tmp, {
      slug: "beta",
      topic: "beta",
      principle: "rule",
      created_at: "2026-05-14T10:00:00Z",
      unconfirmed_until: "2026-05-28T10:00:00Z",
      status: "unconfirmed",
      evidenced_by: ["[[src/some/code.ts]]"],
    });
    const plan = planRepair(tmp);
    expect(plan.fixes.filter((f) => f.code === REPAIR_CODE.orphanedReference)).toEqual([]);
  });

  test("aggregates detected classes with no fixer as unfixable, each with a hint", () => {
    // A duplicate id is a doctor error with no fixer.
    const dupA = join(brainDirs(tmp).preferences, "pref-dup-a.md");
    const dupB = join(brainDirs(tmp).preferences, "pref-dup-b.md");
    const fm =
      "---\nkind: brain-preference\nid: pref-collide\ncreated_at: 2026-05-14T10:00:00Z\n" +
      "unconfirmed_until: 2026-05-28T10:00:00Z\ntags: []\ntopic: t\nprinciple: p\n" +
      "provenance: observed\n_status: unconfirmed\n---\nbody\n";
    writeFileSync(dupA, fm, "utf8");
    writeFileSync(dupB, fm, "utf8");
    const plan = planRepair(tmp);
    const dup = plan.unfixable.find((u) => u.code === "duplicate-id");
    expect(dup).toBeDefined();
    expect(dup!.nextCommand.startsWith("o2b ")).toBe(true);
  });
});

describe("applyRepair - dry run", () => {
  test("previews fixes and writes nothing (no event, files untouched)", () => {
    const wrPath = writeDanglingWorkrun("run-dry");
    const before = readFileSync(wrPath, "utf8");
    const out = applyRepair(tmp, { dryRun: true, now: new Date("2026-07-18T12:00:00Z") });
    expect(out.dryRun).toBe(true);
    expect(out.applied.length).toBe(1);
    expect(readFileSync(wrPath, "utf8")).toBe(before); // byte-identical
    expect(countRepairEvents()).toBe(0);
  });
});

describe("applyRepair - apply", () => {
  test("closes a dangling workrun and logs one typed event", () => {
    const wrPath = writeDanglingWorkrun("run-apply");
    const out = applyRepair(tmp, { dryRun: false, now: new Date("2026-07-18T12:00:00Z") });
    expect(out.dryRun).toBe(false);
    expect(out.applied.some((f) => f.code === REPAIR_CODE.walGap)).toBe(true);
    // Terminal marker now present -> no longer dangling.
    expect(readFileSync(wrPath, "utf8")).toContain("interrupted");
    expect(countRepairEvents()).toBe(1);
    // Idempotent: a second apply finds nothing and logs nothing new.
    const again = applyRepair(tmp, { dryRun: false, now: new Date("2026-07-18T12:05:00Z") });
    expect(again.applied).toEqual([]);
    expect(countRepairEvents()).toBe(1);
  });

  test("prunes a dead evidenced_by and logs one typed event per fix", () => {
    writePreference(tmp, {
      slug: "gamma",
      topic: "gamma",
      principle: "rule",
      created_at: "2026-05-14T10:00:00Z",
      unconfirmed_until: "2026-05-28T10:00:00Z",
      status: "unconfirmed",
      evidenced_by: ["[[sig-never-existed]]"],
    });
    const out = applyRepair(tmp, { dryRun: false, now: new Date("2026-07-18T12:00:00Z") });
    expect(out.applied.some((f) => f.code === REPAIR_CODE.orphanedReference)).toBe(true);
    expect(countRepairEvents()).toBe(1);
    // The dead reference is gone from both the frontmatter and the body
    // Origin prose; re-running is a no-op.
    const prefFile = join(brainDirs(tmp).preferences, "pref-gamma.md");
    expect(readFileSync(prefFile, "utf8")).not.toContain("sig-never-existed");
    const again = applyRepair(tmp, { dryRun: false, now: new Date("2026-07-18T12:05:00Z") });
    expect(again.applied).toEqual([]);
    expect(countRepairEvents()).toBe(1);
  });

  test("a broken structural retired_by link is reported needs-review, never applied", () => {
    // A retired record whose retired_by points at a missing preference.
    const retDir = brainDirs(tmp).retired;
    const path = join(retDir, "ret-old.md");
    const fm =
      "---\nkind: brain-retired\nid: ret-old\ncreated_at: 2026-05-14T10:00:00Z\n" +
      "tags: []\ntopic: t\nprinciple: p\nprovenance: observed\n" +
      "retired_at: 2026-06-01T10:00:00Z\nretired_by: '[[pref-vanished]]'\n" +
      "retired_reason: superseded-by-context\n_status: retired\n_evidenced_by: []\n---\nbody\n";
    writeFileSync(path, fm, "utf8");
    const out = applyRepair(tmp, { dryRun: false });
    expect(out.needsReview.some((f) => f.target.includes("retired_by"))).toBe(true);
    expect(out.applied).toEqual([]);
    expect(existsSync(path)).toBe(true);
    expect(readFileSync(path, "utf8")).toContain("pref-vanished"); // untouched
  });

  test("the apply skips a fix the approved preview did not name (M6)", () => {
    // The interactive ladder previews, the operator answers y, and the
    // apply re-plans. A finding that appeared in between (the mutation
    // between preview and apply) must not be written behind an approval
    // that never showed it: only the approved targets land.
    writeDanglingWorkrun("run-seen");
    const preview = applyRepair(tmp, { dryRun: true, now: new Date("2026-07-18T12:00:00Z") });
    expect(preview.applied.length).toBe(1);
    const seenPath = preview.applied[0]!.target;

    // The mutation: a second dangling workrun appears while the prompt
    // waits. A fresh plan names both; the approval names one.
    const unseenPath = writeDanglingWorkrun("run-unseen");

    const out = applyRepair(tmp, {
      dryRun: false,
      consent: "interactive-yes",
      approvedTargets: [seenPath],
      now: new Date("2026-07-18T12:00:05Z"),
    });
    // The approved fix landed; the unseen one did not.
    expect(out.applied.length).toBe(1);
    expect(out.applied[0]!.target).toBe(seenPath);
    expect(readFileSync(unseenPath, "utf8")).not.toContain("interrupted");
    expect(countRepairEvents()).toBe(1);

    // A later run without the pin picks the straggler up - skipping is
    // deferral, not deletion.
    const next = applyRepair(tmp, { dryRun: false, now: new Date("2026-07-18T12:00:10Z") });
    expect(next.applied.length).toBe(1);
    expect(readFileSync(unseenPath, "utf8")).toContain("interrupted");
  });
});

describe("applyRepair - consent receipt (t_b6bcd984)", () => {
  test("the doctor-repair event body carries the consent verdict", () => {
    writeDanglingWorkrun("run-consent");
    const out = applyRepair(tmp, {
      dryRun: false,
      consent: "yes-flag",
      now: new Date("2026-07-18T12:00:00Z"),
    });
    expect(out.applied.length).toBe(1);
    const events = repairEvents();
    expect(events.length).toBe(1);
    expect(events[0]!.body["consent"]).toBe("yes-flag");
  });

  test("the MCP provenance value records as caller-apply", () => {
    writeDanglingWorkrun("run-caller");
    applyRepair(tmp, {
      dryRun: false,
      consent: "caller-apply",
      now: new Date("2026-07-18T12:00:00Z"),
    });
    expect(repairEvents()[0]!.body["consent"]).toBe("caller-apply");
  });

  test("a dry run records nothing, with or without a verdict", () => {
    writeDanglingWorkrun("run-dry-consent");
    const out = applyRepair(tmp, {
      dryRun: true,
      consent: "yes-flag",
      now: new Date("2026-07-18T12:00:00Z"),
    });
    expect(out.dryRun).toBe(true);
    expect(countRepairEvents()).toBe(0);
  });

  test("the apply outcome carries the consent verdict (M4)", () => {
    writeDanglingWorkrun("run-outcome-consent");
    const out = applyRepair(tmp, {
      dryRun: false,
      consent: "yes-flag",
      now: new Date("2026-07-18T12:00:00Z"),
    });
    expect(out.applied.length).toBe(1);
    expect(out.consent).toBe("yes-flag");
  });

  test("a no-op apply downgrades the verdict to unchanged (M3/M4)", () => {
    writeDanglingWorkrun("run-noop-consent");
    // First apply closes the gap. The idempotent second apply has nothing
    // to do, so no consent was consumed: the outcome reports `unchanged`
    // rather than the caller's verdict.
    const first = applyRepair(tmp, {
      dryRun: false,
      consent: "interactive-yes",
      now: new Date("2026-07-18T12:00:00Z"),
    });
    expect(first.applied.length).toBe(1);
    const again = applyRepair(tmp, {
      dryRun: false,
      consent: "interactive-yes",
      now: new Date("2026-07-18T12:05:00Z"),
    });
    expect(again.applied).toEqual([]);
    expect(again.consent).toBe("unchanged");
  });
});

describe("applyRepair - dry-run diff preview (t_b6bcd984)", () => {
  test("the preview carries a unified diff of the fixable file", () => {
    const wrPath = writeDanglingWorkrun("run-diff");
    const before = readFileSync(wrPath, "utf8");
    const out = applyRepair(tmp, { dryRun: true, now: new Date("2026-07-18T12:00:00Z") });
    expect(out.applied.length).toBe(1);
    const diff = out.applied[0]!.diff!;
    expect(diff).toContain("---");
    expect(diff).toContain("+++");
    // The appended terminal marker is the change the preview shows; the
    // untouched lines are summarized as matching context, not repeated
    // (no removal line - the header's `---` is not a removal).
    expect(diff).toContain("+ ");
    expect(diff.split("\n").some((l) => l.startsWith("- "))).toBe(false);
    // A preview writes nothing.
    expect(readFileSync(wrPath, "utf8")).toBe(before);
  });

  test("the evidence-prune preview diffs the pruned frontmatter", () => {
    writePreference(tmp, {
      slug: "delta",
      topic: "delta",
      principle: "rule",
      created_at: "2026-05-14T10:00:00Z",
      unconfirmed_until: "2026-05-28T10:00:00Z",
      status: "unconfirmed",
      evidenced_by: ["[[sig-never-existed]]"],
    });
    const out = applyRepair(tmp, { dryRun: true, now: new Date("2026-07-18T12:00:00Z") });
    const fix = out.applied.find((f) => f.code === REPAIR_CODE.orphanedReference);
    expect(fix).toBeDefined();
    expect(fix!.diff).toBeDefined();
    expect(fix!.diff).toContain("---");
    // The dead evidence entry is what the diff removes.
    expect(fix!.diff).toMatch(/-\s+.*sig-never-existed/);
  });

  test("the evidence-prune preview shows the normalization the write performs (M5)", () => {
    // A non-canonical page: the topic scalar is quoted and the body sits
    // directly after the closing fence. The write re-renders the whole
    // file through formatFrontmatter, which de-quotes the scalar and
    // inserts the blank line - so the preview must diff the RAW bytes
    // against the formatted result, or the operator approves a one-line
    // change and the write lands a third. The page starts canonical (the
    // writer's shape, so the doctor detects it) and is then
    // de-canonicalized at the byte level.
    writePreference(tmp, {
      slug: "noncanon",
      topic: "noncanon",
      principle: "rule",
      created_at: "2026-05-14T10:00:00Z",
      unconfirmed_until: "2026-05-28T10:00:00Z",
      status: "unconfirmed",
      evidenced_by: ["[[sig-never-existed]]"],
    });
    const page = join(brainDirs(tmp).preferences, "pref-noncanon.md");
    const canonical = readFileSync(page, "utf8");
    const noncanonical = canonical
      .replace("topic: noncanon", 'topic: "noncanon"')
      .replace("---\n\n", "---\n");
    expect(noncanonical).not.toBe(canonical);
    writeFileSync(page, noncanonical, "utf8");
    const rawBefore = readFileSync(page, "utf8");
    const out = applyRepair(tmp, { dryRun: true, now: new Date("2026-07-18T12:00:00Z") });
    const fix = out.applied.find((f) => f.code === REPAIR_CODE.orphanedReference);
    expect(fix).toBeDefined();
    const diff = fix!.diff!;
    // The normalization the write performs is IN the diff: the quoted
    // scalar round-trips to a bare one (the before side quotes, the
    // after side does not - the old formatted-vs-formatted diff hid
    // this line entirely).
    expect(diff).toContain('- topic: "noncanon"');
    expect(diff).toContain("+ topic: noncanon");

    // Landing exactly the preview: the write normalized what the preview
    // showed, pruned what it removed - and a follow-up preview finds
    // nothing left to do, so the bytes on disk ARE the state the diff
    // described.
    applyRepair(tmp, {
      dryRun: false,
      consent: "yes-flag",
      now: new Date("2026-07-18T12:00:05Z"),
    });
    const landed = readFileSync(page, "utf8");
    expect(landed).toContain("topic: noncanon");
    expect(landed).not.toContain('topic: "noncanon"');
    expect(landed).not.toContain("sig-never-existed");
    expect(landed).toContain("---\n\n## Origin");
    const settled = applyRepair(tmp, { dryRun: true, now: new Date("2026-07-18T12:00:10Z") });
    expect(settled.applied).toEqual([]);
    expect(landed).not.toBe(rawBefore);
  });
});