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
36.4 KB
Raw Blame
/**
 * `o2b brain import-session --status | --discover [--all]`.
 *
 * The verb used to accept only an explicit path, so the operator had to
 * already know where five harnesses keep their logs and import them one
 * at a time. These three flags are the machine-wide half: what is here,
 * what has never been imported, and - only when asked twice - importing
 * exactly that gap.
 *
 * The privacy posture is not re-implemented and is not re-tested from
 * first principles here. It is asserted the only way that can stay true:
 * the discovered import and the explicit-path import must leave
 * byte-identical vault output - every file, not only the inbox - so
 * redaction and the tool-payload exclusion cannot be relaxed on one path
 * without failing on the other. The one thing subtracted from that
 * comparison is the wall clock, which two CLI runs cannot share; see
 * {@link WALL_CLOCK_STAMP} for why that is a subtraction and not a
 * loosening.
 */

import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
  chmodSync,
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  renameSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, relative, sep } from "node:path";

import { 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 { sessionLedgerPath } from "../../src/core/brain/sessions/discover.ts";
import { sessionMiningLedgerPath } from "../../src/core/brain/session-mining-ledger.ts";
import { sessionMiningSurveysPath } from "../../src/core/brain/session-mining-surveys.ts";
import { CHMOD_CANNOT_DENY } from "../helpers/platform.ts";
import { runCli } from "../helpers/run-cli.ts";
import { fakeCredential } from "../helpers/fake-credentials.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);

let tmp: string;
let vault: string;
let home: string;

interface CoverageRow {
  readonly runtime: string;
  readonly found: number;
  readonly imported: number;
  readonly gap: number;
  readonly unparsable: number;
  readonly roots: ReadonlyArray<{ readonly path: string; readonly present: boolean }>;
}

interface MiningRowJson {
  readonly runtime: string;
  readonly distilled: number;
  readonly known_nothing_new: number;
  readonly undistilled: number;
  readonly refused: number;
}

interface MiningCensusJson {
  readonly imported: number;
  readonly distilled: number;
  readonly known_nothing_new: number;
  readonly undistilled: number;
  readonly refused: number;
  readonly by_runtime: ReadonlyArray<MiningRowJson>;
}

interface DiscoveryJson {
  readonly found: number;
  readonly imported: number;
  readonly gap: number;
  readonly by_runtime: ReadonlyArray<CoverageRow>;
  readonly mining?: MiningCensusJson;
  readonly mining_error?: string;
  readonly would_import?: ReadonlyArray<string>;
  readonly files?: ReadonlyArray<{ readonly file: string }>;
}

interface ProposalJson {
  readonly dedup_hash: string;
  readonly topic: string;
  readonly signal: string;
  readonly principle: string;
  readonly scope?: string;
  readonly sessions: ReadonlyArray<string>;
}

interface ProposeBacklogJson {
  readonly undistilled: number;
  readonly proposals: ReadonlyArray<ProposalJson>;
  readonly dropped: ReadonlyArray<{
    readonly session_id: string;
    readonly topic: string;
    readonly dedup_hash: string;
  }>;
  readonly report_only_sessions: ReadonlyArray<string>;
  readonly mining_steps: ReadonlyArray<{
    readonly session_id: string;
    readonly surveyed_turns_hash: string;
    readonly turns_mined: number;
    readonly llm_step: { readonly status: string; readonly prompt: string };
  }>;
  readonly mining_steps_remaining: number;
}

/**
 * A credential in the shape the redactor's `key: value` pass catches, so
 * the byte-identity claim below is about a fixture that actually carries
 * one. The parity test asserted a structural property against a fixture
 * with no secret and no tool call in it, which made its own docstring -
 * "redaction and the tool-payload exclusion cannot be relaxed on one path
 * without failing on the other" - true only by construction.
 */
const FIXTURE_SECRET = fakeCredential("sk-", "live-9f2ba7c1d4e8");

/** A tool INPUT, which no signal may ever carry: a host path. */
const FIXTURE_TOOL_INPUT = "/etc/shadow";

function claudeLine(topic: string, uuid: string): string {
  return (
    [
      JSON.stringify({
        parentUuid: null,
        sessionId: "s",
        entrypoint: "sdk-cli",
        type: "user",
        message: {
          role: "user",
          content:
            `@osb feedback positive topic=${topic} principle="Declare the roots exactly once. ` +
            `Never paste the token: ${FIXTURE_SECRET} into a prompt."`,
        },
        uuid,
        timestamp: "2026-08-16T09:00:00.000Z",
      }),
      JSON.stringify({
        parentUuid: uuid,
        sessionId: "s",
        entrypoint: "sdk-cli",
        type: "assistant",
        message: {
          role: "assistant",
          content: [
            { type: "text", text: "noted" },
            {
              type: "tool_use",
              name: "Read",
              id: `call-${uuid}`,
              input: { path: FIXTURE_TOOL_INPUT },
            },
          ],
        },
        uuid: `a-${uuid}`,
        timestamp: "2026-08-16T09:00:01.000Z",
      }),
    ].join("\n") + "\n"
  );
}

function bootstrapVault(at: string): void {
  const dirs = brainDirs(at);
  for (const d of [
    dirs.brain,
    dirs.inbox,
    dirs.processed,
    dirs.preferences,
    dirs.retired,
    dirs.log,
    dirs.snapshots,
  ]) {
    mkdirSync(d, { recursive: true });
  }
  atomicWriteFileSync(join(dirs.brain, "_brain.yaml"), DEFAULT_BRAIN_CONFIG_YAML);
}

function claudeLog(name: string, topic: string): string {
  const dir = join(home, ".claude", "projects", "-srv-projects-example");
  mkdirSync(dir, { recursive: true });
  const path = join(dir, name);
  writeFileSync(path, claudeLine(topic, `u-${topic}`));
  return path;
}

/**
 * A log whose marker carries no credential-shaped value. The parity
 * fixture above deliberately carries one, but a redacted value mangles
 * the quoted principle (the redactor rewrites the quoted value that
 * follows the credential key, so the principle no longer re-parses from
 * the imported turns and raises no backlog candidate), so the batching
 * tests below use clean markers.
 */
function claudeMarkerLog(name: string, topic: string): string {
  const dir = join(home, ".claude", "projects", "-srv-projects-example");
  mkdirSync(dir, { recursive: true });
  const path = join(dir, name);
  writeFileSync(
    path,
    JSON.stringify({
      parentUuid: null,
      sessionId: "s",
      entrypoint: "sdk-cli",
      type: "user",
      message: {
        role: "user",
        content: `@osb feedback positive topic=${topic} principle="Declare the roots exactly once."`,
      },
      uuid: `u-${topic}`,
      timestamp: "2026-08-16T09:00:00.000Z",
    }) + "\n",
  );
  return path;
}

/** Signal files in the inbox, ignoring the `processed/` subdirectory. */
function inboxSignals(at: string): ReadonlyArray<string> {
  return readdirSync(brainDirs(at).inbox)
    .filter((name) => name.endsWith(".md"))
    .toSorted();
}

/**
 * EVERY file a run left in a vault, keyed by its path relative to the
 * vault root.
 *
 * The parity claim used to be made over `Brain/inbox/` alone, which is
 * the one place a redactor is most likely to have been applied: the log,
 * the processed store and the ledger were all outside the comparison, and
 * a leak on the discovered path would most plausibly land in the log,
 * which records the transcript that was read. Walking the whole vault
 * costs nothing here and cannot be outgrown by a surface added later.
 */
function vaultTree(at: string): Record<string, string> {
  const out: Record<string, string> = {};
  const walk = (dir: string): void => {
    for (const entry of readdirSync(dir, { withFileTypes: true }).toSorted((a, b) =>
      a.name < b.name ? -1 : 1,
    )) {
      const full = join(dir, entry.name);
      if (entry.isDirectory()) walk(full);
      // Keyed `/`-separated on every platform, so the expectations below
      // (`Brain/inbox/...`) name the same file on Windows.
      else out[relative(at, full).split(sep).join("/")] = readFileSync(full, "utf8");
    }
  };
  walk(at);
  return out;
}

/**
 * A wall-clock stamp: `2026-08-16T11:31:51Z` in frontmatter and in the
 * log's JSONL, `11:31:51Z` in the log's markdown heading.
 *
 * The two runs being compared are two CLI invocations, so a stamp taken
 * by each can differ by a second - measured at roughly 7% of runs, which
 * made this test flaky. The repair is NOT to loosen the byte comparison:
 * that would trade a real assertion for a vacuous one. Only the clock is
 * neutralised, and only where its VALUE is the whole match, so any other
 * difference - a leaked token, a path, a field one path writes and the
 * other does not - still survives into the comparison and still fails it.
 *
 * The transcript's own event times (`...T09:00:00.000Z`, with
 * milliseconds) are deliberately NOT matched: they come from the fixture,
 * they are identical on both paths by construction, and normalising them
 * would hide a path that lost them.
 */
const WALL_CLOCK_STAMP = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z|(?<![.\d])\d{2}:\d{2}:\d{2}Z/g;

/**
 * The day log's hash chain (`"h"`, and `"prev"` on every later line) is
 * computed over the whole line, stamp included, so a stamp that straddled
 * a second re-keys the chain too - which failed this test on a loaded CI
 * runner after the stamp itself had been neutralised. The chain fields are
 * neutralised with the clock, for the same reason and no further: the
 * chain has its own end-to-end integrity suites, and what this test
 * asserts is that the two import paths write the same content.
 */
const LOG_CHAIN_HASH = /"(h|prev)":"[0-9a-f]{64}"/g;

/**
 * Today in UTC, which is the date both writers stamp: storage timestamps
 * are canonical UTC everywhere and `present-time.ts` converts only at the
 * presentation boundary, so the signal filename and the daily log carry
 * this date and not the fixture's event date.
 *
 * Derived, not pinned. The literal that stood here was the day the test
 * was written, so the assertion held for one day and failed on every day
 * after it - and it failed on the byte-identity test, whose job is to
 * catch a redactor difference between two import paths.
 *
 * Read at the moment of use rather than at module load, which is as tight
 * as this can be closed: the date is stamped by two CLI SUBPROCESSES and
 * nothing here can hand them a clock. A run that straddles 00:00 UTC is
 * already unsound whatever the expectation says - the two runs would
 * stamp two different dates and the byte-identity comparison would fail
 * on the log filename - so the residual window is the two runs' own
 * span, not this file's.
 */
function todayUtc(): string {
  return new Date().toISOString().slice(0, 10);
}

function withoutWallClock(tree: Record<string, string>): Record<string, string> {
  const out: Record<string, string> = {};
  for (const [name, body] of Object.entries(tree)) {
    out[name] = body.replace(WALL_CLOCK_STAMP, "<clock>").replace(LOG_CHAIN_HASH, '"$1":"<chain>"');
  }
  return out;
}

async function run(
  args: string[],
  env: Record<string, string> = {},
): Promise<{ stdout: string; stderr: string; returncode: number }> {
  return runCli(["brain", "import-session", ...args, "--vault", vault], {
    env: { HOME: home, ...env },
  });
}

/**
 * The log shard both runs must write into.
 *
 * `appendLogEvent` names its files `<date>.<device-id>.md`, and a device
 * id is generated per config home - which `runCli` isolates per
 * invocation. So two runs otherwise identical land in two DIFFERENTLY
 * NAMED log files, and a comparison over the vault tree would report
 * every log as missing on both sides rather than comparing them. Pinned
 * explicitly rather than relying on the suite preload's `O2B_DEVICE_ID=""`,
 * so what this test compares does not depend on a setting made elsewhere.
 */
const PARITY_DEVICE_ID = "parity-device";

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-cli-session-discovery-"));
  vault = join(tmp, "vault");
  home = join(tmp, "home");
  mkdirSync(home, { recursive: true });
  bootstrapVault(vault);
});

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

describe("--status reports coverage without touching anything", () => {
  test("per runtime it names found, imported and the gap between them", async () => {
    claudeLog("one.jsonl", "alpha");
    claudeLog("two.jsonl", "beta");
    const res = await run(["--status", "--json"]);
    expect(res.returncode).toBe(0);
    const body = JSON.parse(res.stdout) as DiscoveryJson;
    expect(body.found).toBe(2);
    expect(body.imported).toBe(0);
    expect(body.gap).toBe(2);
    const claude = body.by_runtime.find((r) => r.runtime === "claude-code");
    expect({ found: claude?.found, imported: claude?.imported, gap: claude?.gap }).toEqual({
      found: 2,
      imported: 0,
      gap: 2,
    });
    // Where it looked, not only what it found: "found: 0" against an
    // unnamed root is an answer nobody can act on.
    expect(claude?.roots.map((r) => r.path)).toEqual([join(home, ".claude", "projects")]);
    expect(claude?.roots[0]?.present).toBe(true);
  });

  test("it writes no signal and no ledger", async () => {
    claudeLog("one.jsonl", "alpha");
    expect((await run(["--status"])).returncode).toBe(0);
    expect(inboxSignals(vault)).toEqual([]);
    expect(existsSync(sessionLedgerPath(vault))).toBe(false);
  });

  test("the human rendering names every runtime and its three counts", async () => {
    claudeLog("one.jsonl", "alpha");
    const res = await run(["--status"]);
    expect(res.returncode).toBe(0);
    for (const id of ["claude-code", "codex", "cursor", "grok", "opencode"]) {
      expect(`${id} named: ${res.stdout.includes(id)}`).toBe(`${id} named: true`);
    }
    expect(res.stdout).toContain("found: 1");
    expect(res.stdout).toContain("gap: 1");
  });
});

describe("the mining census rides the coverage report", () => {
  test("a recall import with nothing mined yet is undistilled backlog", async () => {
    claudeLog("one.jsonl", "alpha");
    expect((await run(["--discover", "--all", "--recall", "--json"])).returncode).toBe(0);

    const status = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
    const mining = status.mining;
    expect(mining).toBeDefined();
    expect(mining?.imported).toBe(1);
    expect(mining?.undistilled).toBe(1);
    expect(mining?.distilled).toBe(0);
    expect(mining?.known_nothing_new).toBe(0);
    expect(mining?.refused).toBe(0);
    const claude = mining?.by_runtime.find((r) => r.runtime === "claude-code");
    expect(claude?.undistilled).toBe(1);
  });

  test("an import without recall never reaches the backlog, because the plan would refuse it", async () => {
    // Turns reach continuity only through --recall; without them the mining
    // plan refuses the session (zero imported turns), and the census
    // excludes what the plan refuses - it can never be distilled.
    claudeLog("one.jsonl", "alpha");
    expect((await run(["--discover", "--all", "--json"])).returncode).toBe(0);

    const status = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
    expect(status.mining?.imported).toBe(1);
    expect(status.mining?.refused).toBe(1);
    expect(status.mining?.undistilled).toBe(0);
  });

  test("an explicit recall id is recorded, so the census does not read the session as refused", async () => {
    const path = claudeLog("one.jsonl", "alpha");
    expect((await run([path, "--recall", "--recall-session-id", "pinned-one"])).returncode).toBe(0);

    const status = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
    expect(status.mining?.undistilled).toBe(1);
    expect(status.mining?.refused).toBe(0);
  });

  test("a census failure leaves the coverage report standing and names the census unavailable", async () => {
    // A corrupt mining ledger is refused by the census by design; that is
    // a fact about the census, not about what was imported.
    claudeLog("one.jsonl", "alpha");
    expect((await run(["--discover", "--all", "--recall", "--json"])).returncode).toBe(0);
    mkdirSync(dirname(sessionMiningLedgerPath(vault)), { recursive: true });
    writeFileSync(sessionMiningLedgerPath(vault), "{ truncated");

    const json = await run(["--status", "--json"]);
    expect(json.returncode).toBe(0);
    const body = JSON.parse(json.stdout) as DiscoveryJson;
    expect(body.imported).toBe(1);
    expect(body.mining).toBeUndefined();
    expect(body.mining_error).toContain("session mining ledger");

    const text = await run(["--discover"]);
    expect(text.returncode).toBe(0);
    expect(text.stdout).toContain("found: 1");
    expect(text.stdout).toContain("mining: unavailable (");
  });

  test("the human rendering carries the mining lines per runtime", async () => {
    claudeLog("one.jsonl", "alpha");
    expect((await run(["--discover", "--all", "--recall"])).returncode).toBe(0);

    const res = await run(["--status"]);
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain("mining: 0 distilled, 0 known-nothing-new, 1 undistilled");
    expect(res.stdout).toContain("  undistilled: 1");
  });
});

describe("--propose-backlog batches the distill proposals ask-once", () => {
  test("material the vault no longer holds is proposed, naming its session", async () => {
    claudeMarkerLog("one.jsonl", "alpha");
    expect((await run(["--discover", "--all", "--recall", "--json"])).returncode).toBe(0);
    // The marker's signal is removed from the vault, so its dedup hash
    // leaves the index: the backlog raises material the vault holds
    // nowhere - exactly what the ask-once layer re-proposes.
    rmSync(join(brainDirs(vault).inbox, `sig-${todayUtc()}-alpha.md`));

    const res = await run(["--propose-backlog", "--json"]);
    expect(res.returncode).toBe(0);
    const body = JSON.parse(res.stdout) as ProposeBacklogJson;
    expect(body.undistilled).toBe(1);
    expect(body.proposals.length).toBe(1);
    expect(body.proposals[0]?.topic).toBe("alpha");
    expect(body.proposals[0]?.signal).toBe("positive");
    expect(body.proposals[0]?.sessions).toEqual(["one.jsonl"]);
    expect(body.dropped).toEqual([]);
    expect(body.report_only_sessions).toEqual([]);
  });

  test("material the vault already holds is dropped from the ask and named", async () => {
    // Two sessions raise the SAME marker; the first import writes it and
    // the second is deduped at write time - but without the batching layer
    // the ask would still have raised the same material twice, once per
    // session. Ask-once: zero proposals, two named drops, both sessions
    // reported as already known.
    claudeMarkerLog("one.jsonl", "alpha");
    claudeMarkerLog("two.jsonl", "alpha");
    expect((await run(["--discover", "--all", "--recall", "--json"])).returncode).toBe(0);

    const res = await run(["--propose-backlog", "--json"]);
    expect(res.returncode).toBe(0);
    const body = JSON.parse(res.stdout) as ProposeBacklogJson;
    expect(body.proposals).toEqual([]);
    expect(body.dropped.length).toBe(2);
    expect(body.dropped.map((d) => d.session_id).toSorted()).toEqual(["one.jsonl", "two.jsonl"]);
    expect(body.dropped[0]?.dedup_hash).toBe(body.dropped[1]?.dedup_hash);
    expect(body.report_only_sessions).toEqual(["one.jsonl", "two.jsonl"]);
  });

  test("an undistilled session gets a mining step, and answering it drains the backlog", async () => {
    // The free text a model would mine is what leaves a session
    // undistilled, so the envelope hands out the mining step for it; an
    // extract-signals commit of the answer (empty here) records the
    // session as mined and the backlog drains.
    claudeLog("one.jsonl", "alpha");
    expect((await run(["--discover", "--all", "--recall", "--json"])).returncode).toBe(0);

    const before = JSON.parse(
      (await run(["--propose-backlog", "--json"])).stdout,
    ) as ProposeBacklogJson;
    expect(before.undistilled).toBe(1);
    expect(before.mining_steps.map((s) => s.session_id)).toEqual(["one.jsonl"]);
    expect(before.mining_steps[0]?.llm_step.status).toBe("needs-llm-step");
    expect(before.mining_steps_remaining).toBe(0);

    const commit = await runCli(
      [
        "brain",
        "extract-signals",
        "one.jsonl",
        "--payload",
        JSON.stringify({ items: [] }),
        "--vault",
        vault,
      ],
      { env: { HOME: home } },
    );
    expect(commit.returncode).toBe(0);

    const after = JSON.parse(
      (await run(["--propose-backlog", "--json"])).stdout,
    ) as ProposeBacklogJson;
    expect(after.undistilled).toBe(0);
    expect(after.mining_steps).toEqual([]);
  });

  test("the text form lists the mining steps without a session-placeholder command", async () => {
    claudeLog("one.jsonl", "alpha");
    expect((await run(["--discover", "--all", "--recall", "--json"])).returncode).toBe(0);

    const res = await run(["--propose-backlog"]);
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain("mining steps: 1");
    expect(res.stdout).toContain("mine: one.jsonl");
    expect(res.stdout).toContain(
      "an extract-signals commit of its envelope's payload (--json here hands out the envelopes)",
    );
    expect(res.stdout).not.toContain("o2b brain extract-signals <session>");
    // No envelope was handed out, so no survey is recorded that a barren
    // commit could tombstone unseen turns against.
    expect(existsSync(sessionMiningSurveysPath(vault))).toBe(false);
  });

  test("one session under two paths is one mining step with none remaining", async () => {
    // The census counts import-ledger paths; the same basename imported
    // from two project directories is one session identity, so it gets
    // one step and leaves nothing behind it.
    claudeLog("one.jsonl", "alpha");
    const other = join(home, ".claude", "projects", "-srv-projects-other");
    mkdirSync(other, { recursive: true });
    writeFileSync(join(other, "one.jsonl"), claudeLine("alpha", "u-alpha"));
    expect((await run(["--discover", "--all", "--recall", "--json"])).returncode).toBe(0);

    const body = JSON.parse(
      (await run(["--propose-backlog", "--json"])).stdout,
    ) as ProposeBacklogJson;
    expect(body.undistilled).toBe(2);
    expect(body.mining_steps.map((s) => s.session_id)).toEqual(["one.jsonl"]);
    expect(body.mining_steps_remaining).toBe(0);
  });

  test("an empty backlog is an explicit empty envelope, not a failure", async () => {
    const res = await run(["--propose-backlog", "--json"]);
    expect(res.returncode).toBe(0);
    const body = JSON.parse(res.stdout) as ProposeBacklogJson;
    expect(body.undistilled).toBe(0);
    expect(body.proposals).toEqual([]);
    expect(body.dropped).toEqual([]);
    expect(body.report_only_sessions).toEqual([]);
  });

  test("the human rendering numbers the proposals and names the drops", async () => {
    claudeMarkerLog("one.jsonl", "alpha");
    expect((await run(["--discover", "--all", "--recall", "--json"])).returncode).toBe(0);
    rmSync(join(brainDirs(vault).inbox, `sig-${todayUtc()}-alpha.md`));

    const res = await run(["--propose-backlog"]);
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain("undistilled: 1");
    expect(res.stdout).toContain("proposals: 1");
    expect(res.stdout).toContain("proposal 1: alpha");
    expect(res.stdout).toContain("  signal: positive");
    expect(res.stdout).toContain("  sessions: one.jsonl");
    expect(res.stdout).toContain("dropped as already known: 0");
  });

  test("mode conflicts are refused, naming both halves", async () => {
    const path = claudeMarkerLog("one.jsonl", "alpha");

    const withStatus = await run(["--propose-backlog", "--status"]);
    expect(withStatus.returncode).toBe(1);
    expect(withStatus.stderr).toContain("--propose-backlog");
    expect(withStatus.stderr).toContain("--status");

    const withDiscover = await run(["--propose-backlog", "--discover"]);
    expect(withDiscover.returncode).toBe(1);
    expect(withDiscover.stderr).toContain("--discover");

    const withAll = await run(["--propose-backlog", "--all"]);
    expect(withAll.returncode).toBe(1);
    expect(withAll.stderr).toContain("--all");

    const withPath = await run([path, "--propose-backlog"]);
    expect(withPath.returncode).toBe(1);
    expect(withPath.stderr).toContain(path);
    expect(withPath.stderr).toContain("--propose-backlog");
  }, 20000);
});

describe("--discover reports what would import and imports nothing", () => {
  test("it lists the gap and leaves the inbox empty", async () => {
    const path = claudeLog("one.jsonl", "alpha");
    const res = await run(["--discover", "--json"]);
    expect(res.returncode).toBe(0);
    const body = JSON.parse(res.stdout) as DiscoveryJson;
    expect(body.would_import).toEqual([path]);
    expect(body.files).toBeUndefined();
    expect(inboxSignals(vault)).toEqual([]);
  });

  test("--discover --all imports the gap and the next status reports it closed", async () => {
    claudeLog("one.jsonl", "alpha");
    const imported = await run(["--discover", "--all", "--json"]);
    expect(imported.returncode).toBe(0);
    const body = JSON.parse(imported.stdout) as DiscoveryJson;
    expect(body.files?.length).toBe(1);
    expect(inboxSignals(vault).length).toBe(1);

    const after = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
    expect(after.found).toBe(1);
    expect(after.imported).toBe(1);
    expect(after.gap).toBe(0);
  });

  test("a second --discover --all imports nothing, because nothing changed", async () => {
    claudeLog("one.jsonl", "alpha");
    expect((await run(["--discover", "--all"])).returncode).toBe(0);
    const before = inboxSignals(vault).length;
    const again = JSON.parse(
      (await run(["--discover", "--all", "--json"])).stdout,
    ) as DiscoveryJson;
    expect(again.files).toEqual([]);
    expect(inboxSignals(vault).length).toBe(before);
  });

  test("an explicit-path import is recorded, so discovery stops offering it", async () => {
    const path = claudeLog("one.jsonl", "alpha");
    expect((await run([path])).returncode).toBe(0);
    const body = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
    expect(body.imported).toBe(1);
    expect(body.gap).toBe(0);
  });

  test("a dry run is not an import, and does not close the gap", async () => {
    const path = claudeLog("one.jsonl", "alpha");
    expect((await run([path, "--dry-run"])).returncode).toBe(0);
    const body = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
    expect(body.gap).toBe(1);
  });
});

describe("the ledger records what happened, and only what happened", () => {
  test("a directory import records the files it imported, not the files it found", async () => {
    // `importSessionPath` collects a per-file failure into `warnings` and
    // carries on, while the verb recorded every `*.jsonl` under the path
    // as imported. So an unrecognised transcript left the ledger at its
    // current bytes and vanished from `--status` and `--discover` - the
    // "silently report everything as imported" direction this surface
    // exists to rule out - and would stay invisible even after a later
    // release shipped an adapter that could read it.
    const dir = join(home, ".claude", "projects", "-srv-projects-example");
    claudeLog("good.jsonl", "alpha");
    mkdirSync(dir, { recursive: true });
    writeFileSync(join(dir, "bad.jsonl"), JSON.stringify({ not: "a transcript" }) + "\n");

    const res = await run([dir]);
    expect(res.returncode).toBe(0);
    expect(res.stderr + res.stdout).toContain("bad.jsonl");

    const status = JSON.parse((await run(["--status", "--json"])).stdout) as DiscoveryJson;
    expect(status.found).toBe(2);
    expect(status.imported).toBe(1);
    expect(status.gap).toBe(1);

    const ledger = JSON.parse(readFileSync(sessionLedgerPath(vault), "utf8")) as {
      entries: Record<string, unknown>;
    };
    expect(Object.keys(ledger.entries)).toEqual([join(dir, "good.jsonl")]);
  });

  test("a ledger failure after a successful import is reported as itself", async () => {
    // The ledger write sat inside the verb's big `try`, ahead of the
    // report. A corrupt ledger therefore printed `import-session failed`,
    // exited 1 and emitted no JSON - for a run whose signal was already on
    // disk and whose log event was already appended.
    const path = claudeLog("one.jsonl", "alpha");
    mkdirSync(dirname(sessionLedgerPath(vault)), { recursive: true });
    writeFileSync(sessionLedgerPath(vault), "{ this is not json", "utf8");

    const res = await run([path, "--json"]);
    expect(res.returncode).toBe(1);
    // The report is emitted, because the import is what it reports on.
    const body = JSON.parse(res.stdout) as DiscoveryJson;
    expect(body.files?.length).toBe(1);
    // And the signal really is there.
    expect(inboxSignals(vault).length).toBe(1);
    // The failure names itself rather than the import.
    expect(res.stderr).toContain("the import completed");
    expect(res.stderr).toContain("ledger");
    expect(res.stderr).not.toContain("import-session failed");
  });

  // Root, and any user on Windows, writes a 0o500 directory anyway.
  test.skipIf(CHMOD_CANNOT_DENY)(
    "a sweep whose ledger write fails still reports what it imported",
    async () => {
      // The same defect one function over, and it was not even in a `try`:
      // `--discover --all` imported the gap and then took the whole run's
      // report down with the ledger write. A read-only derived store is the
      // cheapest real cause - the ledger's lock file cannot be created -
      // and stands in for the lock timeout and the read-only vault.
      claudeLog("one.jsonl", "alpha");
      const derived = dirname(sessionLedgerPath(vault));
      mkdirSync(derived, { recursive: true });
      chmodSync(derived, 0o500);
      try {
        const res = await run(["--discover", "--all", "--json"]);
        expect(res.returncode).toBe(1);
        const body = JSON.parse(res.stdout) as DiscoveryJson;
        expect(body.files?.length).toBe(1);
        expect(inboxSignals(vault).length).toBe(1);
        expect(res.stderr).toContain("the import completed");
      } finally {
        chmodSync(derived, 0o700);
      }
    },
  );

  test("an entry whose file has been renamed away is pruned on the next write", async () => {
    // Entries were dropped only when the vanished path was re-submitted,
    // which is the one moment a ledger never hears about a renamed file.
    // So a rotated transcript left a dead key in the ledger forever.
    const first = claudeLog("one.jsonl", "alpha");
    expect((await run([first])).returncode).toBe(0);
    renameSync(first, join(dirname(first), "rotated.jsonl"));

    const second = claudeLog("two.jsonl", "beta");
    expect((await run([second])).returncode).toBe(0);

    const ledger = JSON.parse(readFileSync(sessionLedgerPath(vault), "utf8")) as {
      entries: Record<string, unknown>;
    };
    expect(Object.keys(ledger.entries)).toEqual([second]);
  });
});

describe("the privacy posture is the one importSession already holds", () => {
  test("the discovered import and the explicit-path import write identical bytes everywhere but the clock", async () => {
    const path = claudeLog("one.jsonl", "alpha");
    const today = todayUtc();

    const explicit = join(tmp, "explicit-vault");
    bootstrapVault(explicit);
    const direct = await runCli(["brain", "import-session", path, "--vault", explicit], {
      env: { HOME: home, O2B_DEVICE_ID: PARITY_DEVICE_ID },
    });
    expect(direct.returncode).toBe(0);

    expect(
      (await run(["--discover", "--all"], { O2B_DEVICE_ID: PARITY_DEVICE_ID })).returncode,
    ).toBe(0);

    // The floor. Two imports that wrote nothing are byte-identical, and
    // an equality with nothing on either side of it proves nothing about
    // a redactor - so what each run produced is pinned before the two are
    // compared.
    expect(inboxSignals(vault)).toEqual([`sig-${today}-alpha.md`]);
    expect(inboxSignals(explicit)).toEqual(inboxSignals(vault));
    const sweptTree = vaultTree(vault);
    const explicitTree = vaultTree(explicit);
    const namesOf = (tree: Record<string, string>): ReadonlyArray<string> =>
      Object.keys(tree).toSorted();
    expect(namesOf(sweptTree)).toEqual(namesOf(explicitTree));
    // Named rather than counted: each of these is a surface the earlier
    // inbox-only comparison could not see, and the log is where a leak on
    // the discovered path would most plausibly land, because the log is
    // what records the transcript that was read.
    for (const required of [
      `Brain/inbox/sig-${today}-alpha.md`,
      `Brain/log/${today}.${PARITY_DEVICE_ID}.md`,
      `Brain/log/${today}.${PARITY_DEVICE_ID}.jsonl`,
      relative(vault, sessionLedgerPath(vault)).split(sep).join("/"),
    ]) {
      expect(`${required} written: ${namesOf(sweptTree).includes(required)}`).toBe(
        `${required} written: true`,
      );
    }

    // The whole vault, byte for byte, with the wall clock - and only the
    // wall clock - neutralised. See WALL_CLOCK_STAMP.
    expect(withoutWallClock(sweptTree)).toEqual(withoutWallClock(explicitTree));

    // And the bytes both paths wrote are bytes the posture actually acted
    // on. Byte-identity between two paths that both leaked would pass just
    // as happily, so the fixture carries a credential and a tool payload
    // and both are checked over everything either path wrote.
    for (const tree of [sweptTree, explicitTree]) {
      const all = Object.values(tree).join("");
      expect(all.length).toBeGreaterThan(0);
      expect(all).not.toContain(FIXTURE_SECRET);
      expect(all).toContain("***REDACTED***");
      expect(all).not.toContain(FIXTURE_TOOL_INPUT);
    }
  });
});

describe("the refusals name what they refuse", () => {
  // Exit 1, not 2: `o2b brain` maps every `CliError` to 1, and the two
  // exit codes this verb reserves for 2 are the adapter ones
  // (`DETECT_FAIL`, `UNKNOWN_FORMAT`). A usage refusal that exited 2 here
  // would be the only brain verb that did.
  test("a path and --discover cannot both be given", async () => {
    const path = claudeLog("one.jsonl", "alpha");
    const res = await run([path, "--discover"]);
    expect(res.returncode).toBe(1);
    expect(res.stderr).toContain("--discover");
    expect(res.stderr).toContain(path);
  });

  test("a path and --status cannot both be given", async () => {
    const path = claudeLog("one.jsonl", "alpha");
    const res = await run([path, "--status"]);
    expect(res.returncode).toBe(1);
    expect(res.stderr).toContain("--status");
  });

  test("--all is refused on its own, naming the flag that gives it meaning", async () => {
    const res = await run(["--all"]);
    expect(res.returncode).toBe(1);
    expect(res.stderr).toContain("--discover");
  });

  test("--discover and --status together are refused rather than silently ranked", async () => {
    const res = await run(["--discover", "--status"]);
    expect(res.returncode).toBe(1);
    expect(res.stderr).toContain("--status");
  });

  test("no path and no sweep flag still names the missing argument", async () => {
    const res = await run([]);
    expect(res.returncode).toBe(1);
    expect(res.stderr).toContain("--discover");
  });
});

describe("the surface is advertised where an operator looks", () => {
  test("the manifest declares every flag the parser accepts", async () => {
    const res = await runCli(["help", "--json"]);
    expect(res.returncode).toBe(0);
    const root = JSON.parse(res.stdout) as {
      commands: Array<{
        name: string;
        commands?: Array<{ name: string; flags?: Array<{ name: string }> }>;
      }>;
    };
    const brain = root.commands.find((c) => c.name === "brain");
    const verb = brain?.commands?.find((c) => c.name === "import-session");
    const declared = (verb?.flags ?? []).map((f) => f.name).toSorted();
    expect(declared).toEqual(
      [
        "agent",
        "all",
        "discover",
        "dry-run",
        "filter-role",
        "filter-text",
        "format",
        "ingest-scope",
        "json",
        "preserve-event-time",
        "progress",
        "propose-backlog",
        "recall",
        "recall-session-id",
        "recall-summary-group-size",
        "since",
        "status",
        "vault",
      ].toSorted(),
    );
  });
});