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
15.7 KB
Raw Blame
/**
 * Spawn-based tests for the Stop hygiene-digest hook
 * (context-injection-pipeline, lane B, task B3).
 *
 * The hook is opt-in (`hygiene_digest_enabled`, default OFF), gated to
 * turns that wrote an artifact, surfaces the default hygiene sweep plus
 * the dangling-link count as ONE line, and emits a given state once per
 * change via the vault-level hash ledger. Every gate and failure path
 * exits 0 silently.
 *
 * The fixture vault holds one contested truth slot, so the default sweep
 * deterministically reports a single `conflicts` finding (severity
 * `warning`) - the smallest eligible population the composer accepts.
 */

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

import { appendClaimEvent } from "../../src/core/brain/truth/store.ts";
import {
  HYGIENE_DIGEST_HASH_FILENAME,
  computeHygieneDigestHash,
  hygieneDigestHashPath,
} from "../../hooks/lib/hygiene-digest-state.ts";
import {
  HYGIENE_DIGEST_POINTER,
  HYGIENE_DIGEST_SEVERITIES,
} from "../../hooks/lib/hygiene-digest-text.ts";
import { homeEnv } from "../helpers/platform.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);

const HOOK = resolve(
  dirname(fileURLToPath(import.meta.url)),
  "..",
  "..",
  "hooks",
  "hygiene-digest.ts",
);

const FLAG_ON = { OPEN_SECOND_BRAIN_HYGIENE_DIGEST_ENABLED: "true" };

/**
 * Modules a flag-off run must never load: the detector sweep and the
 * search index are the whole cost of this hook, so the flag gate must
 * come before they are imported (lazy imports after the gates).
 */
const HEAVY_MODULE_SUFFIXES = [
  "/brain/hygiene/scan.ts",
  "/search/link-ratchet.ts",
  "/search/index.ts",
  "/brain/hygiene/detectors/conflicts.ts",
];

/** Preload that reports every loaded module path on stderr at exit. */
const LOADED_PROBE = `process.on("exit", () => {
  process.stderr.write("LOADED:" + JSON.stringify(Object.keys(require.cache)) + "\\n");
});
`;

let vault: string;
let configHome: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-hygiene-digest-vault-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-hygiene-digest-home-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

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

/** Two contested claims for one slot: one deterministic `conflicts` finding. */
function seedConflict(): void {
  const now = Date.now();
  appendClaimEvent(vault, {
    ts: new Date(now - 48 * 3_600_000).toISOString(),
    agent: "agent-a",
    entity: "Acme Corp",
    aspect: "headquarters",
    value: "Berlin",
    source: "[[note-a]]",
  });
  appendClaimEvent(vault, {
    ts: new Date(now - 24 * 3_600_000).toISOString(),
    agent: "agent-b",
    entity: "Acme Corp",
    aspect: "headquarters",
    value: "Lisbon",
    source: "[[note-b]]",
  });
}

function ccUser(text: string): string {
  return JSON.stringify({
    type: "user",
    message: { role: "user", content: [{ type: "text", text }] },
  });
}

function ccAssistantToolUse(name: string, input: Record<string, unknown> = {}): string {
  return JSON.stringify({
    type: "assistant",
    message: {
      role: "assistant",
      content: [{ type: "tool_use", id: "toolu_" + name, name, input }],
    },
  });
}

function writeTranscript(path: string, lines: readonly string[]): string {
  mkdirSync(dirname(path), { recursive: true });
  writeFileSync(path, lines.join("\n") + "\n", "utf8");
  return path;
}

/** A claudecode-shaped transcript path, under the throwaway home. */
function claudeTranscript(withArtifact: boolean): string {
  const lines = withArtifact
    ? [ccUser("please add a file"), ccAssistantToolUse("Write", { file_path: "/tmp/x.md" })]
    : [ccUser("what is in the README?"), ccAssistantToolUse("Read", { file_path: "/tmp/x.md" })];
  return writeTranscript(join(configHome, ".claude", "projects", "session.jsonl"), lines);
}

function stopPayload(transcriptPath: string, extra: Record<string, unknown> = {}): unknown {
  return {
    hook_event_name: "Stop",
    transcript_path: transcriptPath,
    stop_hook_active: false,
    ...extra,
  };
}

interface RunResult {
  readonly stdout: string;
  readonly stderr: string;
  readonly exit: number;
}

async function runHook(
  payload: unknown,
  env: Record<string, string> = {},
  preload: ReadonlyArray<string> = [],
): Promise<RunResult> {
  const proc = Bun.spawn(["bun", "run", ...preload, HOOK], {
    stdin: "pipe",
    stdout: "pipe",
    stderr: "pipe",
    cwd: configHome,
    env: {
      PATH: process.env["PATH"] ?? "",
      ...homeEnv(configHome),
      VAULT_DIR: vault,
      ...env,
    },
  });
  proc.stdin.write(JSON.stringify(payload));
  await proc.stdin.end();
  const [stdout, stderr] = await Promise.all([
    new Response(proc.stdout).text(),
    new Response(proc.stderr).text(),
  ]);
  const exit = await proc.exited;
  return { stdout, stderr, exit };
}

describe("hygiene-digest hook", () => {
  test("flag off: no stdout, no ledger write, and the scan is never invoked", async () => {
    seedConflict();
    const probe = join(configHome, "loaded-probe.ts");
    writeFileSync(probe, LOADED_PROBE, "utf8");
    const transcript = claudeTranscript(true);
    const r = await runHook(stopPayload(transcript), {}, ["--preload", probe]);
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
    expect(existsSync(hygieneDigestHashPath(vault))).toBe(false);
    const line = r.stderr.split("\n").find((l) => l.startsWith("LOADED:"));
    expect(line).toBeDefined();
    const loaded = (JSON.parse(line!.slice("LOADED:".length)) as string[]).map((path) =>
      path.replaceAll("\\", "/"),
    );
    expect(loaded.some((path) => path.endsWith("/hooks/hygiene-digest.ts"))).toBe(true);
    for (const suffix of HEAVY_MODULE_SUFFIXES) {
      expect(loaded.filter((path) => path.endsWith(suffix))).toEqual([]);
    }
  });

  test("flag on, eligible findings, artifact-writing turn: exactly one line and the ledger is written", async () => {
    seedConflict();
    const transcript = claudeTranscript(true);
    const r = await runHook(stopPayload(transcript), FLAG_ON);
    expect(r.exit).toBe(0);
    expect(r.stdout.endsWith("\n")).toBe(true);
    expect(r.stdout.trim()).not.toBe("");
    const parsed = JSON.parse(r.stdout) as {
      hookSpecificOutput: { hookEventName: string; additionalContext: string };
    };
    expect(parsed.hookSpecificOutput.hookEventName).toBe("Stop");
    const line = parsed.hookSpecificOutput.additionalContext;
    expect(line.includes("\n")).toBe(false);
    expect(line.startsWith("Open Second Brain hygiene:")).toBe(true);
    expect(line).toContain("1 conflicts");
    expect(line.endsWith(HYGIENE_DIGEST_POINTER)).toBe(true);
    const hashPath = hygieneDigestHashPath(vault);
    expect(existsSync(hashPath)).toBe(true);
    expect(readFileSync(hashPath, "utf8").trim()).toMatch(/^[0-9a-f]{64}$/);
  });

  /**
   * The eligible findings a fresh in-process sweep reports for the
   * fixture vault, the same population the hook just hashed: one
   * deterministic `conflicts` warning.
   */
  async function fixtureEligibleFindings() {
    const { runHygieneScan } = await import("../../src/core/brain/hygiene/scan.ts");
    const findings = runHygieneScan(vault, { now: new Date() }).findings;
    expect(
      findings.filter((f) => HYGIENE_DIGEST_SEVERITIES.includes(f.severity)).map((f) => f.detector),
    ).toEqual(["conflicts"]);
    return findings;
  }

  test("a vault with no search index records the null-dangling hash, never a zero-flattened one", async () => {
    seedConflict();
    const transcript = claudeTranscript(true);
    const r = await runHook(stopPayload(transcript), FLAG_ON);
    expect(r.exit).toBe(0);
    expect(r.stdout).not.toBe("");
    const findings = await fixtureEligibleFindings();
    const recorded = readFileSync(hygieneDigestHashPath(vault), "utf8").trim();
    // The index is absent, so the count is UNMEASURED: the recorded state
    // keeps `danglingLinks: null` and is never flattened into a zero.
    expect(recorded).toBe(computeHygieneDigestHash({ findings, danglingLinks: null }));
    expect(recorded).not.toBe(computeHygieneDigestHash({ findings, danglingLinks: 0 }));
  });

  test("a throwing search config degrades to an unmeasured dangling count and the digest still emits", async () => {
    seedConflict();
    const transcript = claudeTranscript(true);
    // An out-of-range env twin makes resolveSearchConfig throw before the
    // measurement runs; the digest must survive it with the count omitted.
    const r = await runHook(stopPayload(transcript), {
      ...FLAG_ON,
      OPEN_SECOND_BRAIN_SEARCH_CHUNK_SIZE: "0",
    });
    expect(r.exit).toBe(0);
    expect(r.stdout).not.toBe("");
    const parsed = JSON.parse(r.stdout) as {
      hookSpecificOutput: { additionalContext: string };
    };
    const line = parsed.hookSpecificOutput.additionalContext;
    expect(line).toContain("1 conflicts");
    // The pointer names the dangling-links surface, so the segment check
    // is numeric: no "<n> dangling links" count may appear.
    expect(line).not.toMatch(/\d dangling links/);
    const findings = await fixtureEligibleFindings();
    const recorded = readFileSync(hygieneDigestHashPath(vault), "utf8").trim();
    expect(recorded).toBe(computeHygieneDigestHash({ findings, danglingLinks: null }));
  });

  test("a stdout write that fails records no ledger hash: the emit lands before the ledger", async () => {
    seedConflict();
    const payloadPath = join(configHome, "payload.json");
    writeFileSync(payloadPath, JSON.stringify(stopPayload(claudeTranscript(true))), "utf8");
    // A completed run cannot tell a landed emit from a lost one, so the
    // hook is driven with a stdout pipe that is already closed: `head
    // -c0` exits before the hook starts and its single write hits EPIPE
    // in a real process (the stdout-epipe-guard precedent). The delay
    // makes the close deterministic; bash's pipefail carries the hook's
    // own exit past head.
    const script =
      "set -o pipefail; sleep 0.3; " +
      `bun run ${JSON.stringify(HOOK)} < ${JSON.stringify(payloadPath)}` +
      " | head -c0 >/dev/null";
    const proc = Bun.spawn(["bash", "-c", script], {
      stdout: "pipe",
      stderr: "pipe",
      env: {
        PATH: process.env["PATH"] ?? "",
        ...homeEnv(configHome),
        VAULT_DIR: vault,
        ...FLAG_ON,
      },
    });
    const [stderr, exit] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
    // The hook never deadlocks on its own failure: the write error is
    // silenced by the fail-soft catch and exits 0.
    expect(stderr).toBe("");
    expect(exit).toBe(0);
    // The line never landed: recording the hash here would silence this
    // exact state until the findings change, so the ledger stays empty
    // and the next eligible turn re-emits (lose-not-duplicate).
    expect(existsSync(hygieneDigestHashPath(vault))).toBe(false);
  }, 20_000);

  test("an immediate second identical run is silent", async () => {
    seedConflict();
    const transcript = claudeTranscript(true);
    const first = await runHook(stopPayload(transcript), FLAG_ON);
    expect(first.stdout).not.toBe("");
    const hashPath = hygieneDigestHashPath(vault);
    const recorded = readFileSync(hashPath, "utf8");
    const second = await runHook(stopPayload(transcript), FLAG_ON);
    expect(second.exit).toBe(0);
    expect(second.stdout).toBe("");
    expect(readFileSync(hashPath, "utf8")).toBe(recorded);
  });

  test("stop_hook_active is silent", async () => {
    seedConflict();
    const transcript = claudeTranscript(true);
    const r = await runHook(stopPayload(transcript, { stop_hook_active: true }), FLAG_ON);
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
    expect(existsSync(hygieneDigestHashPath(vault))).toBe(false);
  });

  test("a turn without an artifact write is silent", async () => {
    seedConflict();
    const transcript = claudeTranscript(false);
    const r = await runHook(stopPayload(transcript), FLAG_ON);
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
    expect(existsSync(hygieneDigestHashPath(vault))).toBe(false);
  });

  test("a missing vault is silent", async () => {
    seedConflict();
    const transcript = claudeTranscript(true);
    // No VAULT_DIR and a throwaway home with no config: resolution falls
    // through every source and returns null. The cwd is the throwaway
    // home, so the project-pointer walk-up finds no pointer either.
    const r = await runHook(stopPayload(transcript), { VAULT_DIR: "" });
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
  });

  test("a scan with nothing eligible emits nothing and writes no ledger", async () => {
    // Fresh vault: the default sweep runs (flag on, artifact turn) and
    // finds nothing eligible, so the composer answers null.
    const transcript = claudeTranscript(true);
    const r = await runHook(stopPayload(transcript), FLAG_ON);
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
    expect(existsSync(hygieneDigestHashPath(vault))).toBe(false);
  });

  test("claudecode gets the Stop shape; every other runtime stays silent", async () => {
    seedConflict();
    // M5: a codex-shaped Stop must be probed BEFORE the claudecode run
    // below writes the hash ledger - under the old per-runtime shape the
    // codex probe emitted decision:block, and on those runtimes a Stop
    // block is a forced continuation turn. The digest is opt-in, so a
    // runtime without a non-blocking channel stays silent instead.
    const codex = writeTranscript(join(configHome, ".codex", "sessions", "codex-session.jsonl"), [
      ccUser("please add a file"),
      ccAssistantToolUse("apply_patch", { input: "*** Begin Patch\n+new line\n*** End Patch" }),
    ]);
    const codexRun = await runHook(stopPayload(codex), FLAG_ON);
    expect(codexRun.exit).toBe(0);
    expect(codexRun.stdout).toBe("");
    expect(existsSync(hygieneDigestHashPath(vault))).toBe(false);

    // The claudecode transcript path is what earns the non-blocking
    // channel; its line rides hookSpecificOutput.additionalContext.
    const claude = await runHook(stopPayload(claudeTranscript(true)), FLAG_ON);
    expect(claude.exit).toBe(0);
    const claudeParsed = JSON.parse(claude.stdout) as {
      hookSpecificOutput: { hookEventName: string; additionalContext: string } | undefined;
      decision: string | undefined;
    };
    expect(claudeParsed.hookSpecificOutput).toBeDefined();
    expect(claudeParsed.hookSpecificOutput!.hookEventName).toBe("Stop");
    expect(claudeParsed.decision).toBeUndefined();

    // An unrecognised runtime has no non-blocking channel either: same
    // silence, and the emitted state is never recorded for it.
    rmSync(hygieneDigestHashPath(vault), { force: true });
    const plain = writeTranscript(join(configHome, "plain-session.jsonl"), [
      ccUser("please add a file"),
      ccAssistantToolUse("Write", { file_path: "/tmp/x.md" }),
    ]);
    const unknown = await runHook(stopPayload(plain), FLAG_ON);
    expect(unknown.exit).toBe(0);
    expect(unknown.stdout).toBe("");
    expect(existsSync(hygieneDigestHashPath(vault))).toBe(false);
  });

  test(`the ledger file is named ${HYGIENE_DIGEST_HASH_FILENAME} beside hook-state, never inside it`, () => {
    expect(HYGIENE_DIGEST_HASH_FILENAME).toBe("hygiene-digest.hash");
    expect(hygieneDigestHashPath("/v").replaceAll("\\", "/")).toBe(
      "/v/.open-second-brain/hygiene-digest.hash",
    );
  });
});