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
34.9 KB
Raw Blame
/**
 * `o2b brain import-session`: one path, or the whole machine.
 *
 * The verb took a path and nothing else, which meant an operator had to
 * already know that Claude Code writes under `~/.claude/projects`, that
 * Codex has moved its rollouts between four subdirectories of
 * `$CODEX_HOME`, and that Grok encodes the working directory into a path
 * component - and then run this once per file. `--status` and
 * `--discover` are the machine-wide half, over the roots
 * `src/core/runtime/host-facts.ts` declares.
 *
 * The two modes never blend. A path names exactly one thing to import; a
 * sweep imports what the declared roots hold. Given both, the verb
 * refuses and names both rather than ranking them, because either
 * ranking is a guess about which one the operator meant.
 *
 * `--discover --all` is the only sweeping form that writes, and it writes
 * through the same `importSession` the path form calls - not a second
 * copy of it. That is what keeps the privacy posture identical rather
 * than merely similar: redaction, the tool-payload exclusion and the
 * dedup index are the ones that were already there.
 */

import { statSync } from "node:fs";
import { resolveAgentName, resolveSessionCaptureRoles } from "../../../core/config.ts";
import { buildCaptureBoundary } from "../../../core/brain/capture-boundary.ts";
import { loadDedupIndex, type DedupIndexEntry } from "../../../core/brain/dedup-hash.ts";
import {
  buildBacklogProposals,
  type BacklogCandidate,
} from "../../../core/brain/distill/backlog-proposals.ts";
import { discoverMarkers, isFeedbackMarker } from "../../../core/brain/inline.ts";
import {
  importSession,
  importSessionPath,
  IMPORT_WRITE_MODE,
} from "../../../core/brain/sessions/import.ts";
import {
  discoverSessions,
  discoveryGap,
  recordSessionImports,
  runtimeForPath,
  type RuntimeCoverage,
  type SessionDiscovery,
  type SessionImportRecord,
} from "../../../core/brain/sessions/discover.ts";
import {
  buildMiningCensus,
  minedTurnMaterial,
  type SessionMiningCensus,
} from "../../../core/brain/sessions/mining-census.ts";
import { buildMiningStep } from "../../../core/brain/extract-signals.ts";
import { recordMiningSurvey } from "../../../core/brain/session-mining-surveys.ts";
import type { NeedsLlmStep } from "../../../core/brain/llm-step.ts";
import { minedTurnsHash } from "../../../core/brain/session-mining-ledger.ts";
import {
  buildSessionTurnIndex,
  type SessionTurnIndex,
} from "../../../core/brain/session-recall.ts";
import {
  SESSION_RESUME_DISCARD,
  type SessionResumeDiscard,
} from "../../../core/brain/sessions/checkpoint.ts";
import { SessionImportError, type SessionAdapterId } from "../../../core/brain/sessions/types.ts";
import { serializeImportCensus, type ImportCensus } from "../../../core/brain/import-census.ts";
import {
  createSafeguard,
  OPERATION,
  resolveSafeguardTimeoutMs,
} from "../../../core/brain/safeguard.ts";
import { attachProgress, reportProgressRefusal } from "../../progress-rail.ts";
import {
  isSessionAdapterId,
  sessionAdapterFormatChoices,
} from "../../../core/brain/sessions/registry.ts";
import { appendLogEvent } from "../../../core/brain/log.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../../core/brain/types.ts";
import { isoSecond } from "../../../core/brain/time.ts";
import {
  CliError,
  brainVerbContext,
  fail,
  info,
  normalizeFlagString,
  ok,
  okJson,
  parse,
  parseOptionalIsoDate,
} from "../helpers.ts";

export async function cmdBrainImportSession(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    format: { type: "string" },
    since: { type: "string" },
    "dry-run": { type: "boolean" },
    agent: { type: "string" },
    recall: { type: "boolean" },
    "recall-session-id": { type: "string" },
    "recall-summary-group-size": { type: "string" },
    "ingest-scope": { type: "string" },
    "filter-role": { type: "string-array" },
    "filter-text": { type: "string" },
    "preserve-event-time": { type: "boolean" },
    discover: { type: "boolean" },
    status: { type: "boolean" },
    all: { type: "boolean" },
    "propose-backlog": { type: "boolean" },
    progress: { type: "boolean" },
    json: { type: "boolean" },
  });
  const discover = flags["discover"] === true;
  const status = flags["status"] === true;
  const importAll = flags["all"] === true;
  const proposeBacklog = flags["propose-backlog"] === true;
  const sessionPath = positional[0] ?? null;
  assertOneMode(sessionPath, discover, status, importAll, proposeBacklog);
  const { config, vault } = brainVerbContext(flags);
  const explicitAgent = normalizeFlagString(flags["agent"]);
  if (flags["agent"] !== undefined && explicitAgent === null) {
    return fail("--agent must be a non-empty string when provided");
  }
  const agent = explicitAgent ?? resolveAgentName(config);
  const recallSessionId = normalizeFlagString(flags["recall-session-id"]);
  if (flags["recall-session-id"] !== undefined && recallSessionId === null) {
    return fail("--recall-session-id must be a non-empty string when provided");
  }
  const recallSummaryGroupSize = parsePositiveIntegerFlag(
    flags["recall-summary-group-size"],
    "--recall-summary-group-size",
  );
  const ingestScope = normalizeFlagString(flags["ingest-scope"] as string | undefined);
  const explicitRoles = normalizeRoleFilter(flags["filter-role"] as string[] | undefined);
  // Config-level default (t_e2346fe9): session_capture_roles applies
  // only when no explicit --filter-role flag is given; flag wins.
  let filterRoles = explicitRoles;
  if (explicitRoles.length === 0) {
    try {
      filterRoles = resolveSessionCaptureRoles(config) ?? [];
    } catch (err) {
      return fail((err as Error).message);
    }
  }
  const filterText = normalizeFlagString(flags["filter-text"] as string | undefined);
  const preserveEventTime = Boolean(flags["preserve-event-time"]);
  const formatRaw = flags["format"] as string | undefined;
  let format: SessionAdapterId | undefined;
  if (formatRaw !== undefined && formatRaw !== "auto") {
    if (!isSessionAdapterId(formatRaw))
      return fail(`--format must be one of ${sessionAdapterFormatChoices()}; got ${formatRaw}`);
    format = formatRaw;
  }

  const { value: since, error: sinceErr } = parseOptionalIsoDate(flags, "since");
  if (sinceErr) return fail(sinceErr);

  const dryRun = Boolean(flags["dry-run"]);
  const recall = Boolean(flags["recall"]);
  const asJson = flags["json"] === true;

  // Built once and handed to every import this invocation performs, so a
  // discovered import and a named-path import cannot diverge in what they
  // filter, what they stamp, or what they withhold.
  const importOptions = {
    agent,
    ...(format ? { format } : {}),
    ...(since ? { since } : {}),
    dryRun,
    recall,
    ...(recallSessionId !== null ? { recallSessionId } : {}),
    ...(recallSummaryGroupSize !== undefined ? { recallSummaryGroupSize } : {}),
    ...(ingestScope !== null ? { ingestScope } : {}),
    ...(filterRoles.length > 0 ? { filterRoles } : {}),
    ...(filterText !== null ? { filterTextIncludes: filterText } : {}),
    ...(preserveEventTime ? { preserveEventTime } : {}),
  };

  if (sessionPath === null) {
    if (proposeBacklog) return proposeBacklogEnvelope({ vault, config, asJson });
    return await sweep({
      vault,
      config,
      agent,
      asJson,
      recall,
      dryRun,
      discover,
      importAll,
      progress: flags["progress"] === true,
      importOptions,
    });
  }

  let stat;
  try {
    stat = statSync(sessionPath);
  } catch (err) {
    return fail(`cannot stat ${sessionPath}: ${(err as Error).message ?? err}`);
  }

  let result: Awaited<ReturnType<typeof importSessionPath>>;
  try {
    result = stat.isDirectory()
      ? await importSessionPath(vault, sessionPath, importOptions)
      : { files: [await importSession(vault, sessionPath, importOptions)], warnings: [] };
  } catch (exc) {
    return reportImportFailure(exc);
  }

  // Past this line the import HAPPENED: signals are on disk. Everything
  // that follows is bookkeeping about it, and a bookkeeping failure is
  // reported as itself rather than as a failed import. The ledger write
  // used to sit inside the same `try` as the import above, so a corrupt
  // ledger printed `import-session failed: …`, exited 1 and emitted no
  // report at all - for a run whose signals had already been written and
  // whose log events had already been appended.
  let ledgerError: string | null = null;
  if (!dryRun) {
    logImports(vault, agent, result.files);
    try {
      // A named path is still coverage. Recording it is what stops a
      // later `--status` from reporting a log the operator has already
      // imported by hand as outstanding - the exact false gap this whole
      // surface exists to remove.
      //
      // The files that were actually IMPORTED, not the files that were
      // found. `importSessionPath` collects a per-file failure into
      // `warnings` and carries on, so walking the directory again here
      // recorded the ones that failed as imported: they left the ledger
      // at their current bytes, vanished from `--status` and `--discover`
      // until something edited them, and would stay invisible even after
      // a later release shipped an adapter that could read them.
      recordUnderDeclaredRoots(
        vault,
        result.files.map((f) => f.file),
        recallSessionId,
      );
    } catch (exc) {
      ledgerError = (exc as Error).message ?? String(exc);
    }
  }

  emitImportReport(result, { asJson, recall });
  if (ledgerError !== null) return reportLedgerFailure(ledgerError);
  return 0;
}

/**
 * The import landed and the coverage ledger did not.
 *
 * Non-zero, because something the operator asked for did not happen - but
 * named as what it is. The repair is different from a failed import (the
 * signals are already in the vault; re-running would only re-import work
 * dedup will suppress), and the consequence is bounded and worth stating:
 * the next sweep offers these files again.
 */
function reportLedgerFailure(detail: string): number {
  process.stderr.write(
    `error: the import completed and its signals were written, but the session import ledger ` +
      `could not be updated: ${detail}. A later --status or --discover will offer these files ` +
      "again; re-importing them is safe, because dedup suppresses the writes.\n",
  );
  return 1;
}

/**
 * Refuse a combination rather than rank it.
 *
 * Each message names BOTH halves of the conflict and says what each one
 * does, because the operator asked for two things and the repair is
 * choosing between them - a message that named only the flag it dropped
 * would leave them guessing which behaviour they still have.
 */
function assertOneMode(
  sessionPath: string | null,
  discover: boolean,
  status: boolean,
  importAll: boolean,
  proposeBacklog: boolean,
): void {
  if (discover && status) {
    throw new CliError(
      "--discover and --status ask two different questions of one sweep: --status reports the " +
        "per-runtime found/imported/gap counts, --discover lists the files it would import. " +
        "Pass one.",
    );
  }
  if (importAll && !discover) {
    throw new CliError(
      "--all only means something alongside --discover: it turns the discovery report into an " +
        "import of the gap it just listed. Pass --discover --all.",
    );
  }
  if (proposeBacklog && (discover || status || importAll)) {
    throw new CliError(
      `--propose-backlog and ${discover ? "--discover" : status ? "--status" : "--all"} cannot ` +
        "both be given: --propose-backlog batches the distill proposals the ALREADY IMPORTED " +
        "backlog raises, while the sweep flags report on or import what is on disk. Pass one.",
    );
  }
  if (sessionPath !== null && (discover || status || proposeBacklog)) {
    throw new CliError(
      `${sessionPath} and ${
        discover ? "--discover" : status ? "--status" : "--propose-backlog"
      } cannot both be given: a path ` +
        "imports exactly that path, and the sweep works over the session roots this build " +
        "declares. Drop one.",
    );
  }
  if (sessionPath === null && !discover && !status && !proposeBacklog) {
    throw new CliError(
      "brain import-session requires a <path> argument, or --discover / --status to sweep the " +
        "session stores this machine declares.",
    );
  }
}

interface SweepRequest {
  readonly vault: string;
  readonly config: string | null;
  readonly agent: string;
  readonly asJson: boolean;
  readonly recall: boolean;
  readonly dryRun: boolean;
  readonly discover: boolean;
  readonly importAll: boolean;
  readonly progress: boolean;
  readonly importOptions: Parameters<typeof importSession>[2];
}

/** The machine-wide half: `--status`, `--discover`, and `--discover --all`. */
async function sweep(req: SweepRequest): Promise<number> {
  // Progress is opt-in: attaching a sink by default would change the
  // stderr of every existing invocation. The rail decides whether the
  // stream can carry it at all.
  const observation = req.progress
    ? attachProgress({ command: "brain", argv: ["import-session"], jsonRequested: req.asJson })
    : null;
  reportProgressRefusal(observation);

  let discovery: SessionDiscovery;
  try {
    discovery = discoverSessions(req.vault, {
      safeguard: createSafeguard({
        operation: OPERATION.sessions,
        timeoutMs: resolveSafeguardTimeoutMs(OPERATION.sessions, req.config ?? undefined),
      }),
      ...(observation?.sink !== undefined ? { onProgress: observation.sink } : {}),
    });
  } catch (exc) {
    return fail(`session discovery failed: ${(exc as Error).message ?? exc}`);
  }

  if (!req.importAll) {
    // The distillation census is vault-side (the two ledgers plus the
    // continuity turns the mining lane itself reads), so it rides the
    // coverage report without re-hashing a single source log. Its own
    // deadline is fresh: discovery's safeguard was spent on the sweep. A
    // census failure (a corrupt mining ledger, a deadline) is a fact about
    // the census, not about import coverage: the coverage the operator
    // asked for is still reported, with the census named unavailable.
    let mining: SessionMiningCensus | { readonly error: string };
    try {
      mining = buildMiningCensus(req.vault, {
        safeguard: createSafeguard({
          operation: OPERATION.sessions,
          timeoutMs: resolveSafeguardTimeoutMs(OPERATION.sessions, req.config ?? undefined),
        }),
      });
    } catch (exc) {
      mining = { error: (exc as Error).message ?? String(exc) };
    }
    emitCoverage(discovery, mining, { asJson: req.asJson, listGap: req.discover });
    return 0;
  }

  const gap = discoveryGap(discovery);
  const files: Awaited<ReturnType<typeof importSession>>[] = [];
  const failures: Array<{ path: string; message: string }> = [];
  const imported: SessionImportRecord[] = [];
  for (const entry of gap) {
    try {
      // Sequential on purpose: `importSession` builds and consults one
      // dedup index per call, and two concurrent imports would each miss
      // the other's writes.
      // oxlint-disable-next-line no-await-in-loop
      files.push(await importSession(req.vault, entry.path, req.importOptions));
      const pinned = req.importOptions.recallSessionId;
      imported.push(pinned !== undefined ? { ...entry, sessionId: pinned } : entry);
    } catch (exc) {
      // One unreadable log must not lose the rest of the sweep; the
      // failure is named and the run carries on.
      failures.push({ path: entry.path, message: (exc as Error).message ?? String(exc) });
    }
  }

  // Same ordering as the path form, for the same reason: the imports have
  // landed, so a lock timeout or a read-only vault in the ledger write is
  // a bookkeeping failure and must not swallow the report of what was
  // imported. This call was not in a `try` at all, so it took the whole
  // run's report down with it.
  let ledgerError: string | null = null;
  if (!req.dryRun) {
    logImports(req.vault, req.agent, files);
    if (imported.length > 0) {
      try {
        recordSessionImports(req.vault, imported);
      } catch (exc) {
        ledgerError = (exc as Error).message ?? String(exc);
      }
    }
  }

  emitImportReport({ files, warnings: [] }, { asJson: req.asJson, recall: req.recall, failures });
  if (ledgerError !== null) return reportLedgerFailure(ledgerError);
  return failures.length > 0 ? 1 : 0;
}

/**
 * How many undistilled sessions one `--propose-backlog` call hands out as
 * mining steps. Each step embeds the session's user turns, so the batch is
 * bounded; answered steps leave the backlog and the next call continues.
 */
const BACKLOG_MINING_BATCH = 5;

interface ProposeBacklogRequest {
  readonly vault: string;
  readonly config: string | null;
  readonly asJson: boolean;
}

/**
 * The ask-once half: `--propose-backlog`.
 *
 * Batches the distill proposals the ALREADY IMPORTED undistilled backlog
 * raises into one envelope for the calling agent to present: candidates
 * whose dedup hash already exists in the vault are dropped from the ask
 * (each named), the rest collapse to one proposal per distinct hash across
 * sessions. The kernel runs no interactive loop - it emits the batch, and
 * the presenting agent asks. An empty backlog is an explicit empty
 * envelope and exits 0; it is an answer, not a failure.
 *
 * The marker candidates are the feedback markers in the sessions' mined
 * turn material (the same material the mining plan embeds) - the one
 * candidate form the kernel can see without a model. Import already writes
 * every marker it sees, so a marker proposal surfaces only material that
 * was removed from the vault after import. The dedup index is the shared
 * vault-wide one, so proposals cross-deduplicate against every capture
 * path exactly as the write-time gate does.
 *
 * What actually leaves a session undistilled is the free text a model
 * would mine, so the envelope also carries the mining steps for the first
 * {@link BACKLOG_MINING_BATCH} undistilled sessions: the same
 * needs-llm-step a `brain extract-signals` plan returns, per session. The
 * agent answers each with an `extract-signals` commit, which dedups
 * against the vault (so a fact a second session raises again is written
 * once) and records the session in the mining ledger - so every answered
 * step leaves the backlog, and the next call batches the next sessions.
 */
async function proposeBacklogEnvelope(req: ProposeBacklogRequest): Promise<number> {
  let census: SessionMiningCensus;
  let turnIndex: SessionTurnIndex;
  try {
    turnIndex = buildSessionTurnIndex(req.vault);
    census = buildMiningCensus(req.vault, {
      safeguard: createSafeguard({
        operation: OPERATION.sessions,
        timeoutMs: resolveSafeguardTimeoutMs(OPERATION.sessions, req.config ?? undefined),
      }),
      turns: turnIndex,
    });
  } catch (exc) {
    return fail(`session mining census failed: ${(exc as Error).message ?? exc}`);
  }

  const boundary = buildCaptureBoundary(req.vault);
  const candidates: BacklogCandidate[] = [];
  const miningSteps: Array<{
    readonly sessionId: string;
    readonly surveyedTurnsHash: string;
    readonly turnsMined: number;
    readonly llmStep: NeedsLlmStep;
  }> = [];
  // The census counts import-ledger PATHS, and one session identity can
  // sit under several paths or runtimes; the steps are per identity, so
  // the backlog walks each identity once and counts the minable ones
  // itself - the number the remaining-steps figure is measured against.
  const seen = new Set<string>();
  let minable = 0;
  for (const row of census.byRuntime) {
    for (const sessionId of row.undistilledSessionIds) {
      if (seen.has(sessionId)) continue;
      seen.add(sessionId);
      const material = minedTurnMaterial(req.vault, sessionId, boundary, turnIndex);
      // A census undistilled row is minable by construction; the null arm
      // is the boundary changing between the two reads, and contributes
      // no candidates rather than a guess.
      if (material === null) continue;
      minable += 1;
      if (miningSteps.length < BACKLOG_MINING_BATCH) {
        miningSteps.push({
          sessionId,
          surveyedTurnsHash: minedTurnsHash(material),
          turnsMined: material.length,
          llmStep: buildMiningStep(sessionId, material),
        });
      }
      for (const turn of material) {
        for (const marker of discoverMarkers(turn.text)) {
          if (!isFeedbackMarker(marker)) continue;
          candidates.push({
            sessionId,
            topic: marker.topic,
            signal: marker.signal,
            principle: marker.principle,
            ...(marker.scope !== undefined && marker.scope !== "" ? { scope: marker.scope } : {}),
          });
        }
      }
    }
  }

  let dedupIndex: Map<string, DedupIndexEntry>;
  try {
    dedupIndex = await loadDedupIndex(req.vault);
  } catch (exc) {
    return fail(`backlog proposal dedup index failed: ${(exc as Error).message ?? exc}`);
  }

  const envelope = buildBacklogProposals(candidates, dedupIndex);
  const remaining = Math.max(0, minable - miningSteps.length);

  if (req.asJson) {
    // The JSON form hands out the envelopes, so each step records its
    // survey the way an extract-signals plan does: a barren commit that
    // answers it without relaying the hash can then still tell whether the
    // session changed in between. A failed record is named on its step.
    const surveyFailures = new Map<string, string>();
    for (const step of miningSteps) {
      try {
        recordMiningSurvey(req.vault, step.sessionId, step.surveyedTurnsHash);
      } catch (exc) {
        surveyFailures.set(step.sessionId, exc instanceof Error ? exc.message : String(exc));
      }
    }
    okJson({
      undistilled: census.undistilled,
      proposals: envelope.proposals.map((p) => ({
        dedup_hash: p.dedupHash,
        topic: p.topic,
        signal: p.signal,
        principle: p.principle,
        ...(p.scope !== undefined ? { scope: p.scope } : {}),
        sessions: p.sessions,
      })),
      dropped: envelope.dropped.map((d) => ({
        session_id: d.sessionId,
        topic: d.topic,
        dedup_hash: d.dedupHash,
      })),
      report_only_sessions: envelope.reportOnlySessions,
      mining_steps: miningSteps.map((step) => ({
        session_id: step.sessionId,
        surveyed_turns_hash: step.surveyedTurnsHash,
        turns_mined: step.turnsMined,
        llm_step: step.llmStep,
        ...(surveyFailures.has(step.sessionId)
          ? { survey_record_failure: surveyFailures.get(step.sessionId) }
          : {}),
      })),
      mining_steps_remaining: remaining,
    });
    return 0;
  }

  ok(`undistilled: ${census.undistilled}`);
  ok(`proposals: ${envelope.proposals.length}`);
  let number = 1;
  for (const proposal of envelope.proposals) {
    ok(`proposal ${number}: ${proposal.topic}`);
    ok(`  signal: ${proposal.signal}`);
    ok(`  principle: ${proposal.principle}`);
    if (proposal.scope !== undefined) ok(`  scope: ${proposal.scope}`);
    ok(`  sessions: ${proposal.sessions.join(", ")}`);
    number += 1;
  }
  ok(`dropped as already known: ${envelope.dropped.length}`);
  for (const drop of envelope.dropped) info(`  ${drop.sessionId}: ${drop.topic}`);
  ok(`sessions with nothing new: ${envelope.reportOnlySessions.length}`);
  for (const sessionId of envelope.reportOnlySessions) info(`  ${sessionId}`);
  ok(`mining steps: ${miningSteps.length}`);
  for (const step of miningSteps) {
    ok(`  mine: ${step.sessionId} (${step.turnsMined} user turn(s))`);
  }
  if (miningSteps.length > 0) {
    // This form hands out no envelope, so it records no survey: a barren
    // commit drains a session only over material a plan really offered.
    ok(
      "  answer each with an extract-signals commit of its envelope's payload " +
        "(--json here hands out the envelopes); an empty answer to an envelope drains the session",
    );
  }
  if (remaining > 0) ok(`undistilled sessions after this batch: ${remaining}`);
  return 0;
}

/** `path -> the runtime whose declared root contains it`, recorded in the ledger. */
function recordUnderDeclaredRoots(
  vault: string,
  paths: ReadonlyArray<string>,
  recallSessionId: string | null,
): void {
  const records: SessionImportRecord[] = [];
  for (const path of paths) {
    const runtime = runtimeForPath(path);
    if (runtime !== null) {
      records.push({
        path,
        runtime,
        ...(recallSessionId !== null ? { sessionId: recallSessionId } : {}),
      });
    }
  }
  if (records.length > 0) recordSessionImports(vault, records);
}

/** Append one `import-session` log event per imported file, fail-soft. */
function logImports(
  vault: string,
  agent: string,
  files: ReadonlyArray<Awaited<ReturnType<typeof importSession>>>,
): void {
  for (const f of files) {
    try {
      appendLogEvent(
        vault,
        {
          timestamp: isoSecond(new Date()),
          eventType: BRAIN_LOG_EVENT_KIND.importSession,
          body: {
            agent,
            file: `[[${f.file}]]`,
            format: f.format,
            turns_scanned: String(f.turns_scanned),
            signals_created: String(f.signals_created),
            signals_deduped: String(f.signals_deduped),
            tool_replays: String(f.tool_replays),
            malformed: String(f.malformed),
          },
        },
        { failOpen: true },
      );
    } catch (err) {
      process.stderr.write(
        `warning: append import-session log failed: ${(err as Error).message}\n`,
      );
    }
  }
}

/** One coverage row, as the JSON surface serialises it. */
function coverageJson(row: RuntimeCoverage): Record<string, unknown> {
  return {
    runtime: row.runtime,
    found: row.found,
    imported: row.imported,
    gap: row.gap,
    unparsable: row.unparsable,
    roots: row.roots.map((root) => ({
      id: root.id,
      path: root.path,
      present: root.present,
      adapter: root.adapter,
      format: root.format,
    })),
  };
}

/** One mining row, as the JSON surface serialises it. */
function miningRowJson(row: SessionMiningCensus["byRuntime"][number]): Record<string, unknown> {
  return {
    runtime: row.runtime,
    distilled: row.distilled,
    known_nothing_new: row.knownNothingNew,
    undistilled: row.undistilled,
    refused: row.refused,
  };
}

/** The distillation census, as the JSON surface serialises it. */
function miningJson(census: SessionMiningCensus): Record<string, unknown> {
  return {
    imported: census.imported,
    distilled: census.distilled,
    known_nothing_new: census.knownNothingNew,
    undistilled: census.undistilled,
    refused: census.refused,
    by_runtime: census.byRuntime.map(miningRowJson),
  };
}

/** Report what the sweep found, without importing anything. */
function emitCoverage(
  discovery: SessionDiscovery,
  censusOrError: SessionMiningCensus | { readonly error: string },
  opts: { asJson: boolean; listGap: boolean },
): void {
  const miningError = "error" in censusOrError ? censusOrError.error : null;
  const mining = "error" in censusOrError ? null : censusOrError;
  if (opts.asJson) {
    okJson({
      found: discovery.found,
      imported: discovery.imported,
      gap: discovery.gap,
      unparsable: discovery.unparsable,
      unreadable: discovery.unreadable,
      by_runtime: discovery.byRuntime.map(coverageJson),
      ...(mining !== null ? { mining: miningJson(mining) } : { mining_error: miningError }),
      ...(opts.listGap
        ? { would_import: discovery.byRuntime.flatMap((row) => [...row.gapPaths]) }
        : {}),
    });
    return;
  }
  ok(`found: ${discovery.found}`);
  ok(`imported: ${discovery.imported}`);
  ok(`gap: ${discovery.gap}`);
  if (discovery.unparsable > 0) ok(`unparsable: ${discovery.unparsable}`);
  if (miningError !== null) ok(`mining: unavailable (${miningError})`);
  if (mining !== null && mining.imported > 0) {
    ok(
      `mining: ${mining.distilled} distilled, ${mining.knownNothingNew} known-nothing-new, ` +
        `${mining.undistilled} undistilled`,
    );
  }
  for (const row of discovery.byRuntime) {
    ok(`runtime: ${row.runtime}`);
    ok(`  found: ${row.found}`);
    ok(`  imported: ${row.imported}`);
    ok(`  gap: ${row.gap}`);
    if (row.unparsable > 0) ok(`  unparsable: ${row.unparsable}`);
    const minedRow = mining?.byRuntime.find((m) => m.runtime === row.runtime);
    if (minedRow !== undefined) {
      ok(`  distilled: ${minedRow.distilled}`);
      ok(`  known-nothing-new: ${minedRow.knownNothingNew}`);
      ok(`  undistilled: ${minedRow.undistilled}`);
      if (minedRow.refused > 0) ok(`  refused: ${minedRow.refused}`);
    }
    // Where it looked. "found: 0" without the root it looked under is an
    // answer an operator cannot act on or disbelieve.
    for (const root of row.roots) {
      ok(`  root: ${root.path} (${root.present ? "present" : "absent"})`);
    }
    if (opts.listGap) for (const path of row.gapPaths) ok(`  would import: ${path}`);
  }
  for (const line of discovery.unreadable) info(`  unreadable: ${line}`);
}

/**
 * What each discard reason means, in one clause. Keyed by the vocabulary so
 * a member added without a sentence fails to compile - the alternative was
 * one sentence about the session log that was already wrong for a reason
 * that is about the checkpoint's own bytes.
 */
const RESUME_DISCARD_EXPLANATION: Readonly<Record<SessionResumeDiscard, string>> = Object.freeze({
  [SESSION_RESUME_DISCARD.headChanged]:
    "the session log is not the one the boundary was taken against",
  [SESSION_RESUME_DISCARD.fileShrank]:
    "the session log has shrunk since the boundary was taken, so the boundary is past its end",
  [SESSION_RESUME_DISCARD.payloadInvalid]:
    "the checkpoint on disk carries a turn boundary this build could not have written",
});

/** The per-file import report, shared by the path form and the sweep. */
function emitImportReport(
  result: {
    files: ReadonlyArray<Awaited<ReturnType<typeof importSession>>>;
    warnings: ReadonlyArray<{ path: string; message: string }>;
  },
  opts: {
    asJson: boolean;
    recall: boolean;
    failures?: ReadonlyArray<{ path: string; message: string }>;
  },
): void {
  const failures = opts.failures ?? [];
  if (opts.asJson) {
    okJson({
      files: result.files.map((f) => ({
        file: f.file,
        format: f.format,
        write_mode: f.write_mode,
        turns_scanned: f.turns_scanned,
        signals_created: f.signals_created,
        signals_withheld: f.signals_withheld,
        signals_deduped: f.signals_deduped,
        facts_extracted: f.facts_extracted,
        facts_withheld: f.facts_withheld,
        facts_ambient_withheld: f.facts_ambient_withheld,
        tool_replays: f.tool_replays,
        malformed: f.malformed,
        filtered_turns: f.filtered_turns,
        recall_turns_imported: f.recall_turns_imported,
        recall_summary_nodes: f.recall_summary_nodes,
        turns_resumed: f.turns_resumed,
        resume_discarded: f.resume_discarded,
        census: serializeImportCensus(f.census),
        errors: f.errors,
      })),
      warnings: result.warnings,
      ...(failures.length > 0 ? { failed: failures } : {}),
    });
    return;
  }
  for (const f of result.files) {
    ok(`file: ${f.file}`);
    ok(`  format: ${f.format}`);
    ok(`  write_mode: ${f.write_mode}`);
    ok(`  turns_scanned: ${f.turns_scanned}`);
    ok(`  signals_created: ${f.signals_created}`);
    // Printed only on a rehearsal, where it is the whole answer; an
    // applied run's withheld count is zero by construction.
    if (f.write_mode === IMPORT_WRITE_MODE.dryRun) {
      ok(`  signals_withheld: ${f.signals_withheld}`);
      ok(`  facts_withheld: ${f.facts_withheld}`);
    }
    ok(`  signals_deduped: ${f.signals_deduped}`);
    // Printed only when consent actually withheld something: with the lane
    // on the count is zero by construction, and a first import's output is
    // unchanged. Without this line a consent-off import reported 0 facts
    // and no reason - the count is what tells the operator the lane is off.
    if (f.facts_ambient_withheld > 0) ok(`  facts_ambient_withheld: ${f.facts_ambient_withheld}`);
    ok(`  tool_replays: ${f.tool_replays}`);
    ok(`  filtered_turns: ${f.filtered_turns}`);
    // Printed only when a checkpoint actually changed what the run did, so a
    // first import's output is unchanged.
    if (f.turns_resumed > 0) ok(`  turns_resumed: ${f.turns_resumed}`);
    if (f.resume_discarded !== null) {
      info(
        `  resume checkpoint discarded (${f.resume_discarded}): ${RESUME_DISCARD_EXPLANATION[f.resume_discarded]}, ` +
          "so the file was re-imported from the start.",
      );
    }
    emitCensus(f.census);
    if (opts.recall) {
      ok(`  recall_turns_imported: ${f.recall_turns_imported}`);
      ok(`  recall_summary_nodes: ${f.recall_summary_nodes}`);
    }
    if (f.malformed > 0) ok(`  malformed: ${f.malformed}`);
    for (const e of f.errors) info(`  error: ${e.path}: ${e.message}`);
  }
  for (const w of result.warnings) info(`  warning: ${w.path}: ${w.message}`);
  for (const f of failures) process.stderr.write(`error: ${f.path}: ${f.message}\n`);
}

/**
 * The post-import read-back census, printed only when it has something to
 * say: a run that wrote nothing has nothing to reconcile, and a clean census
 * is one line rather than a list. A shortfall NAMES its hashes - the count
 * alone is what this line exists not to be.
 */
function emitCensus(census: ImportCensus): void {
  if (census.attempted === 0) return;
  ok(`  census: ${census.found}/${census.attempted} written signals read back (${census.outcome})`);
  for (const hash of census.missing) info(`    not found on disk: ${hash}`);
}

/** Map a session-import throw onto this verb's exit codes. */
function reportImportFailure(exc: unknown): number {
  if (exc instanceof SessionImportError) {
    process.stderr.write(`error: ${exc.message}\n`);
    if (exc.code === "DETECT_FAIL" || exc.code === "UNKNOWN_FORMAT") return 2;
    return 1;
  }
  return fail(`import-session failed: ${(exc as Error).message ?? exc}`);
}

function normalizeRoleFilter(
  raw: string[] | undefined,
): Array<"user" | "assistant" | "system" | "tool" | "meta"> {
  if (!raw || raw.length === 0) return [];
  const allowed = new Set(["user", "assistant", "system", "tool", "meta"] as const);
  const out: Array<"user" | "assistant" | "system" | "tool" | "meta"> = [];
  for (const value of raw) {
    const normalized = value.trim().toLowerCase() as
      | "user"
      | "assistant"
      | "system"
      | "tool"
      | "meta";
    if (!allowed.has(normalized)) {
      throw new CliError(`--filter-role contains unsupported value: ${value}`);
    }
    out.push(normalized);
  }
  return [...new Set(out)];
}

function parsePositiveIntegerFlag(
  value: string | boolean | string[] | undefined,
  flag: string,
): number | undefined {
  if (value === undefined) return undefined;
  if (typeof value !== "string" || !/^[0-9]+$/.test(value)) {
    throw new CliError(`${flag} must be a positive integer`);
  }
  const parsed = Number.parseInt(value, 10);
  if (parsed < 1) throw new CliError(`${flag} must be a positive integer`);
  return parsed;
}