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
29.4 KB
Raw Blame
/**
 * `o2b brain dead-letters` CLI surface (one-command recovery,
 * t_50794f57, task C3). Claims pinned here:
 *
 *  1. `list` (the default) renders every letter with its classification
 *     and the exact copy-paste recovery command, and exits 0 - a listing
 *     is a report, never a failure. An empty vault says so and exits 0.
 *  2. `show <id>` prints one letter in full detail; an unknown id is a
 *     typed usage error (exit 2), never a silent no-op.
 *  3. `recover <id>` is dry-run by default and previews the per-item
 *     verdicts; `--apply` performs the re-run.
 *  4. `--apply` without `--yes` under `--json` or a non-TTY stdin refuses
 *     typed, writes nothing, and names the consent rule.
 *  5. A frozen vault refuses the apply by name (exit 1) and points at
 *     `o2b brain unfreeze`.
 *  6. Nothing ever deletes the letter: after a successful recovery the
 *     record is still on disk, and the verb says the removal is the
 *     operator's hand action.
 *  7. The verb is wired: the router dispatches it, the manifest carries
 *     it (so the derived help surfaces list it), and the write error's
 *     diagnostic entry resolves to the verb.
 */

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

import {
  deadLetterDir,
  deadLetterPath,
  listDeadLetters,
  recordDeadLetter,
  type DeadLetterEnvelopeIdentity,
} from "../../src/core/brain/dead-letter.ts";
import { DEAD_LETTER_ITEM_VERDICT } from "../../src/core/brain/dead-letter-recovery.ts";
import { verdictText } from "../../src/cli/brain/verbs/dead-letters.ts";
import { resolveNextStep } from "../../src/core/brain/next-step.ts";
import { freezeVault } from "../../src/core/brain/freeze.ts";
import { resetFreezeMarkerCache } from "../../src/core/brain/freeze-marker.ts";
import { resetVaultIdentityPins } from "../../src/core/brain/vault-identity.ts";
import { importSessionRecall } from "../../src/core/brain/session-recall.ts";
import {
  commitExtractedSignals,
  type ExtractedSignalItem,
} from "../../src/core/brain/extract-signals.ts";
import { buildReconciliationReport } from "../../src/core/reconciliation-report.ts";
import { sessionMiningLedgerPath } from "../../src/core/brain/session-mining-ledger.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);

const NOW = new Date("2026-08-23T10:15:00Z");
const SESSION = "sess-cli-recover";
const AGENT = "tester";

let tmp: string;
let vault: string;
let configPath: string;

function item(overrides: Partial<ExtractedSignalItem> = {}): ExtractedSignalItem {
  return {
    topic: "release-notes-style",
    signal: "positive",
    principle: "Name the release theme in the heading, never the ticket id.",
    confidence: 0.9,
    ...overrides,
  };
}

const ENVELOPE: DeadLetterEnvelopeIdentity = Object.freeze({
  lane: "extract-signals",
  step: "extract-signals",
  reference: SESSION,
  target: "Brain/inbox",
});

/** A schema-2 letter over `items` naming `missingKeys`, as the commit writes it. */
function v2Letter(
  items: ReadonlyArray<ExtractedSignalItem>,
  missingKeys: ReadonlyArray<string>,
): ReturnType<typeof recordDeadLetter> {
  return recordDeadLetter(vault, {
    envelope: ENVELOPE,
    report: buildReconciliationReport({
      attempted: items.length,
      found: items.length - missingKeys.length,
      missing: missingKeys,
    }),
    firstError: "EIO: i/o error",
    now: NOW,
    payload: { items: [...items] },
  });
}

function run(args: ReadonlyArray<string>) {
  return runCli(["brain", "dead-letters", ...args, "--vault", vault], {
    env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
  });
}

/** Corrupt the session mining ledger the way a truncated write leaves it. */
function corruptMiningLedger(): void {
  mkdirSync(dirname(sessionMiningLedgerPath(vault)), { recursive: true });
  writeFileSync(sessionMiningLedgerPath(vault), "{ truncated");
}

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-cli-dead-letters-"));
  vault = join(tmp, "vault");
  mkdirSync(join(vault, "Brain"), { recursive: true });
  configPath = join(tmp, "config.yaml");
  writeFileSync(configPath, `vault: ${vault}\n`);
  importSessionRecall(vault, {
    sessionId: SESSION,
    turns: [
      {
        turnId: "t1",
        timestamp: "2026-08-22T09:01:00Z",
        role: "user",
        text: "Always name the release theme in the heading.",
      },
    ],
    createdAt: "2026-08-22T10:00:00Z",
  });
});

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

describe("dead-letters list", () => {
  test("an empty vault is a clean, zero-exit report", async () => {
    const r = await run([]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("no dead letters");
  });

  test("the default renders the classification and the exact recovery command per row", async () => {
    const letter = v2Letter([item(), item({ topic: "module-names" })], ["items[1]:module-names"]);
    const r = await run([]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain(letter.id);
    expect(r.stdout).toContain("recover");
    expect(r.stdout).toContain(`o2b brain dead-letters recover ${letter.id} --apply --yes`);
    expect(r.stdout).toContain(SESSION);
    expect(r.stdout).toContain("items[1]:module-names");
  });

  test("a resolved row renders no command and names why", async () => {
    const items = [item(), item({ topic: "module-names" })];
    commitExtractedSignals(vault, SESSION, { items }, { agent: AGENT, now: NOW });
    v2Letter(items, ["items[0]:release-notes-style", "items[1]:module-names"]);
    const r = await run([]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("resolved");
    expect(r.stdout).toContain("now on disk");
    expect(r.stdout).not.toContain("--apply");
  });

  test("--json carries the per-row category, reason and command", async () => {
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    const r = await run(["--json"]);
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      ok: boolean;
      total: number;
      letters: Array<{
        id: string;
        lane: string;
        reference: string;
        missing: string[];
        category: string;
        reason: string;
        command: string | null;
      }>;
    };
    expect(payload.ok).toBe(true);
    expect(payload.total).toBe(1);
    const row = payload.letters[0]!;
    expect(row.id).toBe(letter.id);
    expect(row.lane).toBe("extract-signals");
    expect(row.reference).toBe(SESSION);
    expect(row.missing).toEqual(["items[0]:release-notes-style"]);
    expect(row.category).toBe("recover");
    expect(row.command).toBe(`o2b brain dead-letters recover ${letter.id} --apply --yes`);
  });

  test("a non-recoverable row is still exit 0 - a listing reports, it does not fail", async () => {
    v2Letter([item()], ["items[0]:release-notes-style"]);
    // A second letter for a session the ledger does not know.
    recordDeadLetter(vault, {
      envelope: { ...ENVELOPE, reference: "sess-nowhere" },
      report: buildReconciliationReport({ attempted: 1, found: 0, missing: ["items[0]:x"] }),
      firstError: "disk full",
      now: NOW,
      payload: { items: [item({ topic: "x" })] },
    });
    const r = await run([]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("not_recoverable");
    expect(r.stdout).toContain("sess-nowhere");
  });

  test("list --json carries has_payload but never the payload itself", async () => {
    // The listing is the machine-read bulk surface - agents and cron logs
    // read it - so the frozen items never ride on it, not even redacted.
    // `show` is the one-letter inspection surface and keeps them.
    expect(() =>
      commitExtractedSignals(
        vault,
        SESSION,
        {
          items: [
            {
              topic: "release-notes-style",
              signal: "positive",
              principle: "Use token password=hunter2secret when scraping.",
              confidence: 0.9,
            },
            // A colon is not a legal slug character: the write refuses and
            // the commit records the letter, frozen payload and all.
            {
              topic: "module:names",
              signal: "positive",
              principle: "Never abbreviate a module name.",
              confidence: 0.9,
            },
          ],
        },
        { agent: AGENT, now: NOW },
      ),
    ).toThrow(/failed to write extracted signal/);
    expect(listDeadLetters(vault)).toHaveLength(1);
    const r = await run(["--json"]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).not.toContain("hunter2secret");
    const payload = JSON.parse(r.stdout) as {
      letters: Array<Record<string, unknown> & { has_payload: boolean }>;
    };
    const row = payload.letters[0]!;
    expect(row["payload"]).toBeUndefined();
    expect(row.has_payload).toBe(true);
  });

  test("show --json keeps the frozen payload for the one-letter inspection, redacted as frozen", async () => {
    expect(() =>
      commitExtractedSignals(
        vault,
        SESSION,
        {
          items: [
            {
              topic: "release-notes-style",
              signal: "positive",
              principle: "Use token password=hunter2secret when scraping.",
              confidence: 0.9,
            },
            {
              topic: "module:names",
              signal: "positive",
              principle: "Never abbreviate a module name.",
              confidence: 0.9,
            },
          ],
        },
        { agent: AGENT, now: NOW },
      ),
    ).toThrow(/failed to write extracted signal/);
    const letter = listDeadLetters(vault)[0]!;
    const r = await run(["show", letter.id, "--json"]);
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      letter: { payload?: { items: Array<Record<string, unknown>> } };
    };
    // An operator inspecting ONE letter locally may need the frozen items
    // - they are the only record of what the failed commit was writing -
    // and the freeze redacts the free text already.
    expect(payload.letter.payload).toBeDefined();
    expect(JSON.stringify(payload.letter.payload)).not.toContain("hunter2secret");
    expect(payload.letter.payload?.items[0]?.["dedup_hash"]).toBeTypeOf("string");
  });
});

describe("dead-letters show", () => {
  test("one letter renders in full detail, missing keys named", async () => {
    const letter = v2Letter([item(), item({ topic: "module-names" })], ["items[1]:module-names"]);
    const r = await run(["show", letter.id]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain(letter.id);
    expect(r.stdout).toContain("items[1]:module-names");
    expect(r.stdout).toContain("EIO: i/o error");
    expect(r.stdout).toContain("module-names");
  });

  test("show --json carries the frozen payload's items", async () => {
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    const r = await run(["show", letter.id, "--json"]);
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      ok: boolean;
      letter: { id: string; payload?: { items: Array<{ topic: string }> } };
    };
    expect(payload.ok).toBe(true);
    expect(payload.letter.id).toBe(letter.id);
    expect(payload.letter.payload?.items[0]?.topic).toBe("release-notes-style");
  });

  test("an unknown id is a typed usage error, not a silent no-op", async () => {
    const r = await run(["show", "extract-signals-0123456789ab"]);
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("extract-signals-0123456789ab");
  });

  test("an unknown id under --json stays a plain-text usage error on stderr", async () => {
    // Usage errors are exit 2 plain text on stderr in BOTH modes; the
    // { ok: false } envelope is reserved for operational refusals (exit
    // 1), so a misquoted id must not mint one on stdout.
    for (const subcommand of ["show", "recover"] as const) {
      const r = await run([subcommand, "extract-signals-0123456789ab", "--json"]);
      expect(r.returncode).toBe(2);
      expect(r.stderr).toContain("no dead letter with id");
      expect(r.stdout).toBe("");
    }
  });

  test("a missing id argument is a usage error", async () => {
    const r = await run(["show"]);
    expect(r.returncode).toBe(2);
  });

  test("a malformed id reads as unknown too - nothing was ever written under it", async () => {
    const r = await run(["show", "garbage"]);
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("no dead letter with id");
  });
});

describe("a letter the store refuses to parse is exit 1, never unknown-id", () => {
  // A letter whose bytes this build cannot read is a hard error by the
  // store's own contract (`dead-letter.ts`: reading refuses rather than
  // skips) - a surface that turned it into "no dead letter with id" would
  // under-report the exact failure the store exists to prevent.
  const CORRUPT_ID = "extract-signals-001122334455";
  const UNKNOWN_VERSION_ID = "extract-signals-ff0011223344";

  function writeCorruptLetter(): void {
    mkdirSync(deadLetterDir(vault), { recursive: true });
    writeFileSync(deadLetterPath(vault, CORRUPT_ID), "{ not json");
  }

  function writeUnknownVersionLetter(): void {
    mkdirSync(deadLetterDir(vault), { recursive: true });
    writeFileSync(
      deadLetterPath(vault, UNKNOWN_VERSION_ID),
      `${JSON.stringify(
        {
          schema_version: 99,
          id: UNKNOWN_VERSION_ID,
          lane: "extract-signals",
          step: "extract-signals",
          reference: SESSION,
          target: "Brain/inbox",
          attempted: 1,
          found: 0,
          missing: ["items[0]:x"],
          outcome: "partial",
          first_error: "disk full",
          recorded_at: "2026-08-23T10:15:00Z",
        },
        null,
        2,
      )}\n`,
    );
  }

  test("show names the store's corrupt-JSON error at exit 1", async () => {
    writeCorruptLetter();
    const r = await run(["show", CORRUPT_ID]);
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("corrupt");
    expect(r.stderr).not.toContain("no dead letter with id");
  });

  test("show --json refuses typed at exit 1", async () => {
    writeCorruptLetter();
    const r = await run(["show", CORRUPT_ID, "--json"]);
    expect(r.returncode).toBe(1);
    const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
    expect(payload.ok).toBe(false);
    expect(payload.message).toContain("corrupt");
  });

  test("list names the store's refusal at exit 1 instead of crashing", async () => {
    writeCorruptLetter();
    const r = await run([]);
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("corrupt");
    // A typed refusal, never an uncaught stack: the listing under-reports
    // nothing and the operator gets the same sentence show gives. The
    // frame shape is matched, not the substring "at " - a refusal
    // sentence that happens to contain " at " is not a stack trace.
    expect(r.stderr).not.toMatch(/^\s+at\s/m);
  });

  test("list --json refuses typed at exit 1", async () => {
    writeUnknownVersionLetter();
    const r = await run(["--json"]);
    expect(r.returncode).toBe(1);
    const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
    expect(payload.ok).toBe(false);
    expect(payload.message).toContain("schema_version");
    expect(payload.message).toContain("parses 1 and 2");
  });

  test("show names an unsupported schema_version at exit 1", async () => {
    writeUnknownVersionLetter();
    const r = await run(["show", UNKNOWN_VERSION_ID]);
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("schema_version");
    expect(r.stderr).not.toContain("no dead letter with id");
  });

  test("recover names the store's refusal at exit 1 and writes nothing", async () => {
    writeCorruptLetter();
    const r = await run(["recover", CORRUPT_ID, "--apply", "--yes"]);
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("corrupt");
    expect(existsSync(join(vault, "Brain", "inbox"))).toBe(false);
  });
});

describe("dead-letters recover", () => {
  test("dry-run is the default and previews the per-item verdicts, writing nothing", async () => {
    commitExtractedSignals(vault, SESSION, { items: [item()] }, { agent: AGENT, now: NOW });
    const letter = v2Letter(
      [item(), item({ topic: "module-names" })],
      ["items[0]:release-notes-style", "items[1]:module-names"],
    );
    const r = await run(["recover", letter.id]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("dry-run");
    expect(r.stdout).toContain("release-notes-style");
    expect(r.stdout).toContain("module-names");
    expect(r.stdout).toMatch(/dedup|already on disk/);
    expect(r.stdout).toContain("--apply");
    // Nothing was written.
    expect(listDeadLetters(vault).length).toBe(1);
    expect(r.stdout).not.toContain("wrote");
  });

  test("recover --json dry-run labels the mode and lists the verdicts", async () => {
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    const r = await run(["recover", letter.id, "--json"]);
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      ok: boolean;
      id: string;
      mode: string;
      items: Array<{ topic: string; verdict: string }>;
    };
    expect(payload.ok).toBe(true);
    expect(payload.id).toBe(letter.id);
    expect(payload.mode).toBe("dry-run");
    expect(payload.items).toEqual([{ topic: "release-notes-style", verdict: "write" }]);
  });

  test("--apply without --yes under --json refuses typed and writes nothing", async () => {
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    const r = await run(["recover", letter.id, "--apply", "--json"]);
    expect(r.returncode).toBe(1);
    const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
    expect(payload.ok).toBe(false);
    expect(payload.message).toContain("--yes");
    expect(listDeadLetters(vault).length).toBe(1);
  });

  test("--apply without --yes in plain non-TTY mode refuses too", async () => {
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    const r = await run(["recover", letter.id, "--apply"]);
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("--yes");
  });

  test("--dry-run and --apply together refuse as a usage error and write nothing", async () => {
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    const r = await run(["recover", letter.id, "--dry-run", "--apply", "--yes"]);
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("--dry-run");
    expect(r.stderr).toContain("--apply");
    // The refusal precedes every write: the letter's item never reached
    // the inbox, and no new letter was recorded either.
    expect(existsSync(join(vault, "Brain", "inbox"))).toBe(false);
    expect(listDeadLetters(vault).length).toBe(1);
  });

  test("--apply --yes re-runs the payload; already-written items dedup away", async () => {
    commitExtractedSignals(vault, SESSION, { items: [item()] }, { agent: AGENT, now: NOW });
    const letter = v2Letter(
      [item(), item({ topic: "module-names" })],
      ["items[0]:release-notes-style", "items[1]:module-names"],
    );
    const r = await run(["recover", letter.id, "--apply", "--yes", "--json"]);
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      ok: boolean;
      mode: string;
      written: Array<{ topic: string }>;
      deduped: number;
      letter_retained: boolean;
    };
    expect(payload.ok).toBe(true);
    expect(payload.mode).toBe("apply");
    expect(payload.written.map((w) => w.topic)).toEqual(["module-names"]);
    expect(payload.deduped).toBe(1);
    expect(payload.letter_retained).toBe(true);
  });

  test("a mining-ledger failure on a written apply rides the JSON output by name", async () => {
    // The commit result's contract (`extract-signals.ts`): the failure
    // "rides here by name, and on both surface outputs" - a recovery that
    // wrote its signals but lost the mining record must never read as a
    // clean run.
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    corruptMiningLedger();
    const r = await run(["recover", letter.id, "--apply", "--yes", "--json"]);
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      ok: boolean;
      mining_ledger_failure?: string;
    };
    expect(payload.ok).toBe(true);
    expect(payload.mining_ledger_failure).toContain("session mining ledger is corrupted JSON");
  });

  test("the same failure prints on the human-readable apply output", async () => {
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    corruptMiningLedger();
    const r = await run(["recover", letter.id, "--apply", "--yes"]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("mining ledger not updated:");
    expect(r.stdout).toContain("session mining ledger is corrupted JSON");
  });

  test("a clean apply carries no mining_ledger_failure key", async () => {
    // Absent-when-empty: a recovery whose mining record landed names no
    // failure, so the JSON shape stays what it always was.
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    const r = await run(["recover", letter.id, "--apply", "--yes", "--json"]);
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as { mining_ledger_failure?: string };
    expect(payload.mining_ledger_failure).toBeUndefined();
  });

  test("nothing ever deletes the letter, and the verb says the removal is by hand", async () => {
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    const r = await run(["recover", letter.id, "--apply", "--yes"]);
    expect(r.returncode).toBe(0);
    const after = listDeadLetters(vault);
    expect(after.length).toBe(1);
    expect(readFileSync(deadLetterPath(vault, letter.id), "utf8")).toContain(letter.id);
    expect(r.stdout).toContain("retained");
    expect(deadLetterDir(vault)).toBeTruthy();
  });

  test("recover refuses a letter that is not recoverable, naming the category", async () => {
    // A letter for a session the ledger does not know.
    const letter = recordDeadLetter(vault, {
      envelope: { ...ENVELOPE, reference: "sess-nowhere" },
      report: buildReconciliationReport({ attempted: 1, found: 0, missing: ["items[0]:x"] }),
      firstError: "disk full",
      now: NOW,
      payload: { items: [item({ topic: "x" })] },
    });
    const r = await run(["recover", letter.id, "--apply", "--yes", "--json"]);
    expect(r.returncode).toBe(1);
    const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
    expect(payload.ok).toBe(false);
    expect(payload.message).toContain("not_recoverable");
  });

  test("a denylist-refused letter refuses the apply at exit 1, naming the gate", async () => {
    // The item never reaches disk, so the letter used to read `recover`
    // forever and every apply reported success over zero writes. The
    // classifier answers not_recoverable and the verb refuses - on the
    // first apply and on every one after it.
    const letter = v2Letter(
      [item({ topic: "scratch-pad", principle: "temporary scratch note" })],
      ["items[0]:scratch-pad"],
    );
    const r = await runCli(
      [
        "brain",
        "dead-letters",
        "recover",
        letter.id,
        "--apply",
        "--yes",
        "--json",
        "--vault",
        vault,
      ],
      {
        env: {
          OPEN_SECOND_BRAIN_CONFIG: configPath,
          OPEN_SECOND_BRAIN_DURABILITY_DENYLIST: "scratch",
        },
      },
    );
    expect(r.returncode).toBe(1);
    const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
    expect(payload.ok).toBe(false);
    expect(payload.message).toContain("durability");
    expect(payload.message).toContain("denylisted");
    // The refused item was never written.
    expect(existsSync(join(vault, "Brain", "inbox"))).toBe(false);
  });

  test("an apply that delivers nothing exits 1 naming the reason", async () => {
    // A hand-edited letter whose missing list is empty: the classifier's
    // recover promise has nothing behind it and the re-run delivers
    // nothing - which used to print `wrote 0 signal(s)` and exit 0. The
    // verb refuses the empty success instead of reporting it.
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    const path = deadLetterPath(vault, letter.id);
    const body = JSON.parse(readFileSync(path, "utf8")) as { missing: string[] };
    body.missing = [];
    writeFileSync(path, `${JSON.stringify(body, null, 2)}\n`);
    const r = await run(["recover", letter.id, "--apply", "--yes", "--json"]);
    expect(r.returncode).toBe(1);
    const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
    expect(payload.ok).toBe(false);
    expect(payload.message).toContain("nothing was delivered");
    expect(existsSync(join(vault, "Brain", "inbox"))).toBe(false);
  });

  test("a reworded re-extract reads as resolved: the apply exits 1 and writes nothing", async () => {
    // The review's scenario: the letter misses release-theme; the session
    // was mined again and a REWORDED release-theme signal landed. The
    // letter reads resolved, the apply refuses, and the inbox keeps ONE
    // release-theme page instead of gaining the stale wording back.
    commitExtractedSignals(
      vault,
      SESSION,
      {
        items: [
          item({ topic: "release-theme", principle: "Lead every release note with the theme." }),
        ],
      },
      { agent: AGENT, now: NOW },
    );
    const letter = v2Letter(
      [item({ topic: "release-theme", principle: "Name the release theme in the heading." })],
      ["items[0]:release-theme"],
    );
    const listing = await run([]);
    expect(listing.stdout).toContain("resolved");
    expect(listing.stdout).not.toContain("--apply");
    const r = await run(["recover", letter.id, "--apply", "--yes", "--json"]);
    expect(r.returncode).toBe(1);
    const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
    expect(payload.ok).toBe(false);
    expect(payload.message).toContain("resolved");
    const inbox = join(vault, "Brain", "inbox");
    const pages = readdirSync(inbox).filter((p) => p.includes("release-theme"));
    expect(pages).toHaveLength(1);
  });

  test("a frozen vault refuses the apply and points at unfreeze", async () => {
    const letter = v2Letter([item()], ["items[0]:release-notes-style"]);
    freezeVault(vault, { agent: "@operator", reason: "migrating the fleet" });
    resetFreezeMarkerCache();
    resetVaultIdentityPins();
    const r = await run(["recover", letter.id, "--apply", "--yes", "--json"]);
    expect(r.returncode).toBe(1);
    const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
    expect(payload.ok).toBe(false);
    expect(payload.message).toContain("frozen");
    expect(payload.message).toContain("o2b brain unfreeze");
    // The letter's items were not written.
    expect(listDeadLetters(vault).length).toBe(1);
  });

  test("an unknown id is a typed usage error", async () => {
    const r = await run(["recover", "extract-signals-0123456789ab"]);
    expect(r.returncode).toBe(2);
  });

  test("a missing id argument is a usage error", async () => {
    const r = await run(["recover"]);
    expect(r.returncode).toBe(2);
  });
});

describe("the dry-run verdict rendering", () => {
  test("every known verdict renders its own words; an unknown one refuses by name", () => {
    // Enumerated against the vocabulary constant: a verdict joining
    // DEAD_LETTER_ITEM_VERDICT must be given its own words here, never
    // silently rendered as another verdict's - "quarantined" reading as
    // "refused" would tell the operator the wrong thing.
    expect(verdictText(DEAD_LETTER_ITEM_VERDICT.write)).toBe("will write");
    expect(verdictText(DEAD_LETTER_ITEM_VERDICT.staged)).toBe("will stage for approval");
    expect(verdictText(DEAD_LETTER_ITEM_VERDICT.dedup)).toBe("already on disk (dedup)");
    expect(verdictText(DEAD_LETTER_ITEM_VERDICT.refused)).toBe("refused");
    expect(() => verdictText("quarantined")).toThrow(/quarantined/);
  });
});

describe("wiring", () => {
  test("an unknown subcommand is a usage error naming the three forms", async () => {
    const r = await run(["frobnicate"]);
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("list");
    expect(r.stderr).toContain("show");
    expect(r.stderr).toContain("recover");
  });

  test("--help prints the verb's own usage", async () => {
    const r = await runCli(["brain", "dead-letters", "--help"], {
      env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout.startsWith("usage:")).toBe(true);
    expect(r.stdout).toContain("o2b brain dead-letters");
  });

  test("the manifest carries the verb, so the derived help surfaces list it", async () => {
    const help = await runCli(["help"], { env: { OPEN_SECOND_BRAIN_CONFIG: configPath } });
    expect(help.returncode).toBe(0);
    expect(help.stdout).toContain("dead-letters");
  });

  test("the write error's diagnostic entry resolves to the verb", () => {
    const step = resolveNextStep("extract-signals-dead-letter");
    expect(step).not.toBeNull();
    expect(step?.nextCommand).toBe("o2b brain dead-letters");
  });
});