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
7.9 KB
Raw Blame
/**
 * Tests for src/core/brain/operator-snapshot.ts - the unified operator
 * status snapshot (O3, t_9f9c5466).
 *
 * A healthy vault snapshots to an all-clear; a vault with detected issues
 * produces problem lines, each carrying the exact next command supplied by
 * the O2 diagnostics-signal registry (never hardcoded in the renderer).
 */

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

import {
  buildOperatorSnapshot,
  renderOperatorSnapshot,
} from "../../src/core/brain/operator-snapshot.ts";
import { resolveSignal } from "../../src/core/brain/diagnostics.ts";
import { brainConfigPath, brainDirs } from "../../src/core/brain/paths.ts";
import { DEFAULT_BRAIN_CONFIG_YAML } from "../../src/core/brain/config-template.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { resolveSearchConfig } from "../../src/core/search/index.ts";

let tmp: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-snapshot-"));
  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 });
});

describe("buildOperatorSnapshot", () => {
  test("a clean vault snapshots to all-clear with no problems", async () => {
    const snap = await buildOperatorSnapshot(tmp, { now: new Date("2026-07-18T12:00:00Z") });
    expect(snap.healthy).toBe(true);
    expect(snap.problems).toEqual([]);
    expect(snap.stateFiles.config).toBe(true);
    const text = renderOperatorSnapshot(snap);
    expect(text).toContain("all clear");
    expect(text).not.toContain("Problems:");
  });

  test("a dangling workrun surfaces a doctor-warning problem with a next command", async () => {
    const runs = join(tmp, "Brain", "log", "dream-runs");
    mkdirSync(runs, { recursive: true });
    writeFileSync(
      join(runs, "run-x.jsonl"),
      JSON.stringify({ phase: "started", at: "2026-07-18T00:00:00.000Z", run_id: "run-x" }) + "\n",
      "utf8",
    );
    const snap = await buildOperatorSnapshot(tmp, { now: new Date("2026-07-18T12:00:00Z") });
    expect(snap.healthy).toBe(false);
    const dw = snap.problems.find((p) => p.code === "doctor-warnings");
    expect(dw).toBeDefined();
    // The hint travels with the signal definition, not the formatter.
    expect(dw!.nextCommand).toBe(resolveSignal("doctor-warnings").nextCommand);
    const text = renderOperatorSnapshot(snap);
    expect(text).toContain("Problems:");
    expect(text).toContain(`-> next: ${dw!.nextCommand}`);
  });

  test("a missing config surfaces a state-file problem", async () => {
    rmSync(brainConfigPath(tmp), { force: true });
    const snap = await buildOperatorSnapshot(tmp, { now: new Date("2026-07-18T12:00:00Z") });
    expect(snap.stateFiles.config).toBe(false);
    const sf = snap.problems.find((p) => p.code === "state-file");
    expect(sf).toBeDefined();
    expect(sf!.nextCommand).toBe("o2b brain init");
  });

  test("every problem line's next command matches its signal definition", async () => {
    const runs = join(tmp, "Brain", "log", "dream-runs");
    mkdirSync(runs, { recursive: true });
    writeFileSync(
      join(runs, "run-y.jsonl"),
      JSON.stringify({ phase: "started", at: "2026-07-18T00:00:00.000Z", run_id: "run-y" }) + "\n",
      "utf8",
    );
    const snap = await buildOperatorSnapshot(tmp, { now: new Date("2026-07-18T12:00:00Z") });
    for (const p of snap.problems) {
      expect(p.nextCommand).toBe(resolveSignal(p.code).nextCommand);
      expect(p.nextCommand.startsWith("o2b ")).toBe(true);
    }
  });
});

describe("buildOperatorSnapshot store group (t_cfe2ce5d)", () => {
  /** The search index path the snapshot's own probe reads, for lock staging. */
  function dbPath(): string {
    return resolveSearchConfig({ vault: tmp }).dbPath;
  }

  /**
   * The lock directory `proper-lockfile` takes: `mkdirSync(`${dbPath}.lock`)`,
   * the exact shape `lockfile.lockSync` creates (getLockFile in
   * proper-lockfile/lib/lockfile.js).
   */
  function takeWriterLock(): string {
    const lockDir = `${dbPath()}.lock`;
    mkdirSync(lockDir, { recursive: true });
    return lockDir;
  }

  test("no lock directory reads free", async () => {
    const snap = await buildOperatorSnapshot(tmp, { now: new Date("2026-07-18T12:00:00Z") });
    expect(snap.store.writerLock).toBe("free");
    expect(snap.store.writerLockReason).toBeNull();
    expect(snap.store.writerLockAgeMs).toBeNull();
    expect(snap.store.writerLockPath).toBe(dbPath());
    expect(snap.store.thisCaller).toBe("read-only");
  });

  test("a lock directory created the way proper-lockfile takes the lock reads held with a non-negative age", async () => {
    takeWriterLock();
    const snap = await buildOperatorSnapshot(tmp, { now: new Date("2026-07-18T12:00:00Z") });
    expect(snap.store.writerLock).toBe("held");
    expect(snap.store.writerLockAgeMs).not.toBeNull();
    expect(snap.store.writerLockAgeMs!).toBeGreaterThanOrEqual(0);
    // v1 truth: the lock record is a bare directory carrying no identity,
    // so the owner field reads null rather than inventing a holder.
    expect(snap.store.writerLockOwner).toBeNull();
  });

  test("an injected throw reads unknown with the errno in the reason", async () => {
    const failure = Object.assign(new Error("permission denied"), { code: "EACCES" });
    const snap = await buildOperatorSnapshot(tmp, {
      now: new Date("2026-07-18T12:00:00Z"),
      writerLockHeldAt: () => {
        throw failure;
      },
    });
    expect(snap.store.writerLock).toBe("unknown");
    expect(snap.store.writerLockReason).toContain("EACCES");
    expect(snap.store.writerLockAgeMs).toBeNull();
  });

  test("a held lock is a live writer, not a fault: healthy stays true and problems are unchanged", async () => {
    const before = await buildOperatorSnapshot(tmp, { now: new Date("2026-07-18T12:00:00Z") });
    takeWriterLock();
    const held = await buildOperatorSnapshot(tmp, { now: new Date("2026-07-18T12:00:00Z") });
    expect(held.healthy).toBe(true);
    expect(held.problems).toEqual(before.problems);
  });

  test("the renderer prints the store line on both branches", async () => {
    const clear = await buildOperatorSnapshot(tmp, { now: new Date("2026-07-18T12:00:00Z") });
    expect(renderOperatorSnapshot(clear)).toContain("store: writer lock free");

    takeWriterLock();
    const held = await buildOperatorSnapshot(tmp, { now: new Date("2026-07-18T12:00:00Z") });
    const heldText = renderOperatorSnapshot(held);
    expect(heldText).toContain("store: writer lock held");
    // The owner's absence is a stated measurement, not a gap.
    expect(heldText).toContain("carries no identity");
    // The refusal is scoped to what the lock actually gates - index
    // writers only. The brain lane serializes on its own lock files, so
    // an unscoped "a write now would refuse" told every agent reading
    // this card that a memory write would fail when it would not (M8).
    expect(heldText).toContain(
      "an index write (o2b search index / reindex) would refuse with INDEX_LOCKED",
    );
    expect(heldText).toContain("vault and memory writes are not gated by this lock");
    expect(heldText).toContain("this caller read-only");

    const unclear = await buildOperatorSnapshot(tmp, {
      now: new Date("2026-07-18T12:00:00Z"),
      writerLockHeldAt: () => {
        throw Object.assign(new Error("permission denied"), { code: "EACCES" });
      },
    });
    const unclearText = renderOperatorSnapshot(unclear);
    expect(unclearText).toContain("store: writer lock state unknown");
    expect(unclearText).toContain("EACCES");
    expect(unclearText).toContain("this caller read-only");
  });
});