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
18.6 KB
Raw Blame
/**
 * `o2b brain dead-letters <list|show|recover>` - the dead-letter surface
 * (one-command recovery, t_50794f57, task C3).
 *
 * A dead letter is the durable record of a multi-artifact write that
 * failed part way (`src/core/brain/dead-letter.ts`). Until now it was a
 * fact without an exit: the file sat in
 * `<vault>/.open-second-brain/dead-letters/` and every reader worked out
 * alone what to do. This verb is the exit. `list` (the default) renders
 * every letter with its classification and the exact copy-paste command
 * that resolves it; `show <id>` prints one letter in full; `recover <id>`
 * re-runs a schema-2 letter's frozen payload through the extraction
 * commit at CURRENT vault state - the capture boundary, the dedup index
 * and the staging lane are re-derived at call time, so already-written
 * items dedup away, an item the session re-delivered by re-extracting is
 * left out (its frozen wording is stale), and nothing stale is ever
 * replayed.
 *
 * The frozen payload is handled per surface: `show --json` carries it
 * (the freeze redacts the free-text fields, and an operator inspecting
 * one letter locally may need the items); `list --json` carries only
 * `has_payload`, because the listing is the surface agents and cron logs
 * read in bulk.
 *
 * The consent ladder is the house one for a write that has a preview:
 * recover is dry-run by default, and `--apply` requires `--yes` under
 * `--json` or a non-TTY stdin (the `brain lint --apply` /
 * `brain doctor --repair --apply` rule). The record id is itself the pin
 * - no second confirmation phrase, exactly as `brain writes revert
 * --apply <digest>`.
 *
 * RETENTION is preserved: nothing here deletes a letter. A successful
 * recovery reports success and names the file the operator may delete BY
 * HAND once the payload is reconciled - the letter is the only surviving
 * evidence of the partial write, and no tool sweeps it.
 *
 * Exit codes: 0 on success (a listing is a report, whatever it says);
 * 1 on an operational failure - a refused apply, a non-recoverable
 * letter asked to recover, a frozen vault, a letter the store refuses to
 * read (corrupt JSON, an unknown schema_version); 2 on usage errors,
 * including a named-but-unknown record id and a `--dry-run` beside an
 * `--apply`.
 */

import { existsSync } from "node:fs";

import {
  type DeadLetterRecord,
  DeadLetterError,
  deadLetterPath,
  listDeadLetters,
  readDeadLetter,
} from "../../../core/brain/dead-letter.ts";
import {
  DEAD_LETTER_ITEM_VERDICT,
  type DeadLetterRecoveryItemVerdict,
  DeadLetterRecoveryError,
  applyRecovery,
  classifyDeadLetter,
  planRecovery,
} from "../../../core/brain/dead-letter-recovery.ts";
import { VaultFrozenError } from "../../../core/brain/freeze-marker.ts";
import { assertVaultIdentityForWrite } from "../../../core/brain/vault-identity.ts";
import {
  brainVerbContext,
  fail,
  ok,
  okJson,
  parse,
  resolveBrainAgent,
  usageError,
} from "../helpers.ts";

const USAGE =
  "usage: o2b brain dead-letters [list] [--vault <path>] [--json]\n" +
  "       o2b brain dead-letters show <id> [--vault <path>] [--json]\n" +
  "       o2b brain dead-letters recover <id> [--dry-run | --apply] [--yes] [--agent <name>]\n" +
  "                        [--vault <path>] [--json]";

/** The three subcommand names, for the usage error. */
const SUBCOMMANDS = "list | show <id> | recover <id>";

export async function cmdBrainDeadLetters(argv: string[]): Promise<number> {
  const first = argv[0];
  // The bare verb IS the listing: a first word that is a flag (`--vault`,
  // `--json`) is the list invocation, not a subcommand. A first word that
  // is neither a known subcommand nor a flag is a usage error rather than
  // a surprise listing of the vault.
  const known = first === "list" || first === "show" || first === "recover";
  const rest = known ? argv.slice(1) : argv;
  if (!known && first !== undefined && !first.startsWith("-")) {
    return usageError(`brain dead-letters requires a subcommand: ${SUBCOMMANDS}`);
  }
  switch (first) {
    case "show":
      return deadLettersShow(rest);
    case "recover":
      return deadLettersRecover(rest);
    default:
      return deadLettersList(rest);
  }
}

// ----- Shared rendering -----------------------------------------------------

/** The classification and exit of one letter, read against current vault state. */
interface RowView {
  readonly record: DeadLetterRecord;
  readonly category: string;
  readonly reason: string;
  readonly command: string | null;
}

function rowView(vault: string, record: DeadLetterRecord): RowView {
  const c = classifyDeadLetter(vault, record);
  return {
    record,
    category: c.category,
    reason: c.reason,
    command: c.command,
  };
}

/**
 * One row's JSON. The frozen payload rides only when `includePayload` is
 * set: `list --json` is the machine-read bulk surface - agents and cron
 * logs read it - so the payload never rides on a listing, not even
 * redacted (`has_payload` still says the letter carries one). `show
 * --json` keeps it: 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 fields at write
 * time, so what show prints is the redacted form for every letter this
 * build recorded.
 */
function rowJson(
  view: RowView,
  opts: { readonly includePayload: boolean },
): Record<string, unknown> {
  const r = view.record;
  return {
    id: r.id,
    schema_version: r.schema_version,
    lane: r.lane,
    step: r.step,
    reference: r.reference,
    target: r.target,
    attempted: r.attempted,
    found: r.found,
    missing: [...r.missing],
    ...(opts.includePayload && r.payload !== undefined ? { payload: r.payload } : {}),
    has_payload: r.payload !== undefined,
    outcome: r.outcome,
    first_error: r.first_error,
    recorded_at: r.recorded_at,
    category: view.category,
    reason: view.reason,
    command: view.command,
  };
}

// ----- list ------------------------------------------------------------------

function deadLettersList(argv: string[]): number {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
  });
  const { vault } = brainVerbContext(flags);
  const asJson = flags["json"] === true;

  // A letter on disk this build cannot read is a hard error by the
  // store's own contract (`listDeadLetters` refuses rather than skips) -
  // a listing that under-reports is the failure this surface exists to
  // prevent. Refused like `show` and `recover` refuse the same fault:
  // a typed exit 1, never an uncaught crash.
  let views: ReturnType<typeof rowView>[];
  try {
    views = listDeadLetters(vault).map((record) => rowView(vault, record));
  } catch (err) {
    if (err instanceof DeadLetterError) return refused(err.message, asJson);
    throw err;
  }

  if (asJson) {
    okJson({
      ok: true,
      total: views.length,
      letters: views.map((v) => rowJson(v, { includePayload: false })),
    });
    return 0;
  }
  if (views.length === 0) {
    ok("no dead letters in this vault");
    return 0;
  }
  for (const view of views) {
    const r = view.record;
    ok(`${r.id}  [${r.lane}]  ${view.category}`);
    ok(
      `  session ${r.reference} -> ${r.target}, attempted ${r.attempted}, ` +
        `found ${r.found}, missing ${r.missing.length}`,
    );
    if (r.missing.length > 0) ok(`  missing: ${r.missing.join(", ")}`);
    ok(`  reason: ${view.reason}`);
    if (view.command !== null) ok(`  next: ${view.command}`);
  }
  return 0;
}

// ----- show ------------------------------------------------------------------

function deadLettersShow(argv: string[]): number {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
  });
  if (positional.length < 1) {
    return usageError(`brain dead-letters show requires an <id> argument\n${USAGE}`);
  }
  const { vault } = brainVerbContext(flags);
  const asJson = flags["json"] === true;
  const id = positional[0]!;

  let record: DeadLetterRecord | null;
  try {
    record = readDeadLetterQuietly(vault, id);
  } catch (err) {
    // The store refused to read the letter (corrupt JSON, an unknown
    // schema_version): the named error at exit 1, never the unknown-id
    // usage shape at exit 2 - a letter this build cannot read exists,
    // and saying otherwise under-reports it.
    if (err instanceof DeadLetterError) return refused(err.message, asJson);
    throw err;
  }
  if (record === null) {
    return unknownId(id);
  }
  const view = rowView(vault, record);

  if (asJson) {
    okJson({ ok: true, letter: rowJson(view, { includePayload: true }) });
    return 0;
  }
  const r = view.record;
  ok(`${r.id}  [${r.lane}]  ${view.category}`);
  ok(`  schema: ${r.schema_version}${r.payload !== undefined ? " (payload frozen)" : ""}`);
  ok(`  step: ${r.step}`);
  ok(`  session: ${r.reference}`);
  ok(`  target: ${r.target}`);
  ok(`  attempted: ${r.attempted}, found: ${r.found}, missing: ${r.missing.length}`);
  for (const key of r.missing) ok(`  missing: ${key}`);
  if (r.payload !== undefined) {
    const items = r.payload["items"];
    if (Array.isArray(items)) {
      for (const item of items) {
        const topic = (item as { topic?: unknown })["topic"];
        if (typeof topic === "string") ok(`  payload item: ${topic}`);
      }
    }
  }
  ok(`  outcome: ${r.outcome}`);
  ok(`  first error: ${r.first_error}`);
  ok(`  recorded: ${r.recorded_at}`);
  ok(`  reason: ${view.reason}`);
  if (view.command !== null) ok(`  next: ${view.command}`);
  return 0;
}

// ----- recover ---------------------------------------------------------------

function deadLettersRecover(argv: string[]): number {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    agent: { type: "string" },
    "dry-run": { type: "boolean" },
    apply: { type: "boolean" },
    yes: { type: "boolean" },
    json: { type: "boolean" },
  });
  if (positional.length < 1) {
    return usageError(`brain dead-letters recover requires an <id> argument\n${USAGE}`);
  }
  const asJson = flags["json"] === true;
  const apply = flags["apply"] === true;
  // The two flags name opposite modes - an explicit `--dry-run` beside an
  // explicit `--apply` is a caller mistake, refused as a usage error
  // rather than resolved in favor of whichever the verb felt like: a
  // write that ignored the caller's dry-run request would be exactly the
  // dishonesty this verb exists to prevent.
  if (flags["dry-run"] === true && apply) {
    return usageError(
      "brain dead-letters recover: --dry-run and --apply are mutually exclusive " +
        "(dry-run is the default; drop one of the two flags)",
    );
  }
  // Dry-run is the default; --apply is the write. The headless consent
  // rule is the `brain lint --apply` one: no prompts under --json or a
  // non-TTY stdin, so --yes is the only consent that can be given there.
  if (apply && flags["yes"] !== true && (asJson || !process.stdin.isTTY)) {
    const message =
      "brain dead-letters recover --apply requires --yes in non-interactive mode " +
      "(dry-run is the default; --apply re-runs the recorded payload)";
    if (asJson) {
      okJson({ ok: false, message });
      return 1;
    }
    return fail(message);
  }
  const { config, vault } = brainVerbContext(flags);
  const id = positional[0]!;

  let record: DeadLetterRecord | null;
  try {
    record = readDeadLetterQuietly(vault, id);
  } catch (err) {
    // The store refused to read the letter: the named error at exit 1,
    // never the unknown-id usage shape - same contract as `show`.
    if (err instanceof DeadLetterError) return refused(err.message, asJson);
    throw err;
  }
  if (record === null) {
    return unknownId(id);
  }

  try {
    if (!apply) {
      const plan = planRecovery(vault, record);
      if (asJson) {
        okJson({
          ok: true,
          id: record.id,
          mode: "dry-run",
          category: plan.classification.category,
          reason: plan.classification.reason,
          items: plan.items.map((i) => ({
            topic: i.topic,
            verdict: i.verdict,
            ...(i.reason !== undefined ? { reason: i.reason } : {}),
          })),
        });
      } else {
        ok(`dry-run recovery plan for ${record.id} (${plan.classification.category})`);
        ok(`  reason: ${plan.classification.reason}`);
        for (const i of plan.items) {
          ok(
            `  ${i.topic}: ${verdictText(i.verdict)}${i.reason !== undefined ? ` (${i.reason})` : ""}`,
          );
        }
        ok("nothing written; re-run with --apply --yes to write");
      }
      return 0;
    }

    // The apply is a content write: the same vault guards every content
    // writer passes - the freeze and the vault identity - refuse here
    // FIRST, before anything is written (the freeze names `o2b brain
    // unfreeze` as its exit).
    assertVaultIdentityForWrite(vault);
    const res = applyRecovery(vault, record, {
      agent: resolveBrainAgent(flags, config),
      now: new Date(),
    });
    const letterPath = deadLetterPath(vault, record.id);
    // The module's own promise: never report success over a re-run that
    // delivered nothing. The classifier refuses the states it can see
    // (every undelivered item gate-refused, every missing item already
    // delivered); an apply that still comes back with zero writes and
    // zero staging - the vault changing between the classification and
    // the commit is the shape this catches - is refused here with the
    // accounting named, instead of printed as a green `wrote 0
    // signal(s)`.
    if (res.written.length + res.staged === 0) {
      const refusedItems = res.rejected.map((r) => `${r.topic}: ${r.reason}`).join("; ");
      const message =
        `nothing was delivered while recovering ${record.id}: wrote 0 signal(s) and staged 0 ` +
        `(deduped ${res.deduped}, durability-rejected ${res.durabilityRejected}` +
        (refusedItems !== "" ? `; ${refusedItems}` : "") +
        `); the letter is retained at ${letterPath}`;
      return refused(message, asJson);
    }
    if (asJson) {
      okJson({
        ok: true,
        id: record.id,
        mode: "apply",
        written: res.written.map((w) => ({ id: w.id, path: w.path, topic: w.topic })),
        staged: res.staged,
        deduped: res.deduped,
        durability_rejected: res.durabilityRejected,
        rejected: res.rejected.map((r) => ({ topic: r.topic, reason: r.reason })),
        letter_retained: true,
        letter_path: letterPath,
        // The commit result's contract: the failure rides here by name,
        // absent when the mining record landed.
        ...(res.miningLedgerFailure !== undefined
          ? { mining_ledger_failure: res.miningLedgerFailure }
          : {}),
      });
    } else {
      ok(
        `recovered ${record.id}: wrote ${res.written.length} signal(s), ` +
          `deduped ${res.deduped}, durability-rejected ${res.durabilityRejected}` +
          (res.staged > 0 ? `, staged ${res.staged} for approval` : ""),
      );
      for (const r of res.rejected) ok(`  rejected: ${r.topic} (${r.reason})`);
      if (res.miningLedgerFailure !== undefined) {
        ok(`mining ledger not updated: ${res.miningLedgerFailure}`);
      }
      ok(
        `the dead letter is retained at ${letterPath}; ` +
          "delete it by hand once the payload is reconciled",
      );
    }
    return 0;
  } catch (err) {
    if (err instanceof VaultFrozenError) {
      return refused(err.message, asJson);
    }
    if (err instanceof DeadLetterRecoveryError) {
      return refused(err.message, asJson);
    }
    const message = `brain dead-letters recover failed: ${(err as Error).message ?? String(err)}`;
    if (asJson) {
      okJson({ ok: false, message });
      return 1;
    }
    return fail(message);
  }
}

/**
 * The dry-run verdict text, in the operator's words, enumerated per known
 * verdict: the table's exhaustive key type makes a verdict joining
 * `DEAD_LETTER_ITEM_VERDICT` a compile error until it is given its own
 * words here, so a future verdict can never silently render as another
 * verdict's - "quarantined" reading as "refused" would tell the operator
 * the wrong thing.
 */
const VERDICT_TEXT: Readonly<Record<DeadLetterRecoveryItemVerdict, string>> = Object.freeze({
  [DEAD_LETTER_ITEM_VERDICT.write]: "will write",
  [DEAD_LETTER_ITEM_VERDICT.staged]: "will stage for approval",
  [DEAD_LETTER_ITEM_VERDICT.dedup]: "already on disk (dedup)",
  [DEAD_LETTER_ITEM_VERDICT.refused]: "refused",
});

/**
 * The text for one verdict, refusing an unknown one by name. Unreachable
 * through the typed plan in this build; the named refusal is the guard
 * for a verdict that reaches this surface unrendered.
 */
export function verdictText(verdict: string): string {
  const text = VERDICT_TEXT[verdict as DeadLetterRecoveryItemVerdict];
  if (text === undefined) {
    throw new Error(`dead-letters: unknown recovery item verdict ${JSON.stringify(verdict)}`);
  }
  return text;
}

/** An operational refusal: the message on the error channel, exit 1. */
function refused(message: string, asJson: boolean): number {
  if (asJson) {
    okJson({ ok: false, message });
    return 1;
  }
  return fail(message);
}

// ----- Shared refusal paths --------------------------------------------------

/**
 * The unknown-id refusal. The id was NAMED by the caller, so this is a
 * usage error (exit 2) rather than an empty report - a silent no-op would
 * read as "nothing to do" for a letter the caller misquoted. A usage
 * error is plain text on stderr in both modes: the `{ ok: false }`
 * envelope is reserved for operational refusals (exit 1).
 */
function unknownId(id: string): number {
  return usageError(`brain dead-letters: no dead letter with id ${JSON.stringify(id)}`);
}

/**
 * Read one letter for the `show`/`recover` reads, mapping a malformed id
 * to the unknown-id refusal shape: `deadLetterPath` throws on an id that
 * does not match the `<lane>-<digest>` shape, and a malformed id is one
 * nothing was ever written under.
 *
 * EVERY other store refusal propagates: a corrupt file or an unknown
 * `schema_version` is a hard error by the store's own contract
 * (`dead-letter.ts`: reading refuses rather than skips), and a caller
 * hearing "no dead letter with id" for an unreadable record would be
 * told the partial write does not exist - the under-report this surface
 * exists to prevent. The store's error reaches the operator at exit 1
 * through the shared refusal path each subcommand renders it with.
 */
function readDeadLetterQuietly(vault: string, id: string): DeadLetterRecord | null {
  let path: string;
  try {
    path = deadLetterPath(vault, id);
  } catch {
    return null;
  }
  if (!existsSync(path)) return null;
  return readDeadLetter(vault, id);
}