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
39.4 KB
Raw Blame
/**
 * Session-import orchestrator (§16).
 *
 * Public surface:
 *
 *   - {@link importSession} — single-file import. Returns per-file
 *     counters and the resolved adapter id.
 *   - {@link importSessionPath} — convenience wrapper that walks a
 *     directory, calling importSession on every `*.jsonl` inside.
 *     Files whose autodetect fails surface as `warnings` rather than
 *     killing the run; valid files still get processed.
 *
 * Extraction pipeline per turn:
 *
 *   1. `discoverMarkers(turn.text)` → for each marker, build a
 *      payload via {@link computeDedupHash}; create a signal with
 *      `source_type: 'session'` unless the hash already exists in
 *      `Brain/inbox/` or `processed/`.
 *   2. For each `tool_use` block named `brain_feedback`: validate
 *      input via {@link validateBrainFeedbackInput}, compute the
 *      same hash; dedup-check; create signal.
 *
 * Mined mentions (recall-quality, B1) ride the same loop: admitted
 * turns of either role are scanned by {@link mineAndRecordTurn} while
 * the raw text still exists, folding one `session_entity_mention`
 * continuity record per (family, key, session). Provenance-grade only -
 * nothing here writes an entity page.
 *
 * Idempotency: dedup index is built once at the start of each
 * `importSession` run by reading the inbox and processed dirs. A
 * second run on the same file finds every hash already present.
 *
 * Resume (nothing-writes-silently, Unit F). Dedup alone is
 * re-do-and-discard: it makes a second run harmless, not cheap, so an
 * interrupted 50k-turn import re-read and re-hashed every turn to
 * conclude it had nothing to write. An applied run now records the turn
 * boundary it has reached into {@link ./checkpoint.ts} - the sessions
 * lane's extension of the ingest checkpoint substrate, not a second one
 * of its own - and the next run over the same file with the same filters
 * skips straight past those turns. What that saves is the extraction
 * work: the marker scan, the dedup hashing, the fact pass and the writes.
 * The lines themselves are still read, because a JSONL transcript has no
 * index to seek into.
 *
 * Recall is the one thing the boundary does not vouch for, and the resumed
 * run re-collects it. `--recall` accumulates turns in memory and commits
 * them to the recall DAG AFTER the loop, so a run that stopped at the
 * boundary committed none of them; skipping those turns on the resumed run
 * would leave the head of the transcript permanently missing from the DAG
 * while both runs reported success. Re-collection costs nothing extra (the
 * lines are read regardless) and is idempotent, because the recall importer
 * keys every turn on a content dedupe key.
 *
 * Census (same unit). After the run, the dedup hashes of the signals it
 * claims to have written are read back from disk, and the result carries
 * `claimed / found / missing` with the missing hashes NAMED. See
 * {@link ../import-census.ts} for what the census does and does not cover.
 */

import { existsSync, statSync } from "node:fs";
import { basename, resolve } from "node:path";

import { delegatedAgentName } from "../../agent-identity.ts";
import { readSkillOfferId, SKILL_OFFER_ID_KEY } from "../../surface/skill-offer.ts";
import { checkpointingEnabled } from "../checkpoint-store.ts";
import { computeDedupHash, loadDedupIndex, type DedupIndexEntry } from "../dedup-hash.ts";
import { censusSessionSignals, type ImportCensus } from "../import-census.ts";
import { appendContinuityRecord } from "../continuity/store.ts";
import { discoverMarkersDetailed, isFeedbackMarker } from "../inline.ts";
import { writeSignal } from "../signal.ts";
import { stampPromptDerivedLine } from "../provenance/content-class.ts";
import { importSessionRecall } from "../session-recall.ts";
import { isoDate, isoSecond } from "../time.ts";
import { BRAIN_SIGNAL_SOURCE_TYPE } from "../types.ts";
import {
  clearSessionCheckpoint,
  computeSessionHeadHash,
  computeSessionImportId,
  recordSessionProgress,
  resolveSessionResume,
  SESSION_CHECKPOINT_TURN_INTERVAL,
  type SessionResumeDiscard,
} from "./checkpoint.ts";
import { readFirstLine } from "./read-lines.ts";
import { detectAdapter, getAdapter } from "./registry.ts";
import { sessionFilesUnder } from "./session-files.ts";
import {
  SessionImportError,
  type SessionAdapter,
  type SessionAdapterId,
  type SessionToolCall,
  type SessionTurn,
} from "./types.ts";
import { validateBrainFeedbackInput } from "./validate-feedback.ts";
import { buildCaptureBoundary, type SessionCaptureDecision } from "../capture-boundary.ts";
import { emitIngestDedupReport } from "../dedup-telemetry.ts";
import { extractFacts, routeExtractedFacts } from "../fact-extract.ts";
import { mineAndRecordTurn } from "../link-graph/session-mining.ts";
import { readLineageLedger } from "../lineage/ledger.ts";
import { resolveSessionLineage } from "../lineage/resolve.ts";
import type { SessionLineage } from "../lineage/types.ts";

export interface ImportSessionOptions {
  /** Agent identity stamped on signals when the turn has no own agent. */
  readonly agent: string;
  /** Force a specific adapter, bypassing autodetect. */
  readonly format?: SessionAdapterId;
  /** ISO timestamp — process only turns at or after this. */
  readonly since?: Date;
  /** When true, don't write any signal. Counters still populate. */
  readonly dryRun?: boolean;
  /** Wall clock for stamping `created_at`. Tests pin this. */
  readonly now?: Date;
  /**
   * Optional pre-built dedup index. When importing a directory of
   * session files, the orchestrator builds the index once and
   * threads it through every per-file call so the inbox isn't
   * re-scanned per file. Internal contract; CLI does not pass it.
   */
  readonly dedupIndex?: Map<string, DedupIndexEntry>;
  /**
   * Vault portability suite (v0.22.0). When true, session-imported
   * signals store their raw body through the deterministic codec
   * (`writeSignal({ rawCodec: true })`). Default off -> verbatim bodies.
   */
  readonly rawCodec?: boolean;
  /** When true, also store normalized turns in the continuity-backed session recall DAG. */
  readonly recall?: boolean;
  readonly recallSessionId?: string;
  readonly recallSummaryGroupSize?: number;
  /**
   * Lineage of the imported segment (continuity-hygiene-freshness
   * suite). When omitted, a link persisted in the lineage ledger for
   * the recall session id is used; flat sessions import unchanged.
   */
  readonly recallLineage?: SessionLineage;
  /** Optional ingest scope label stamped into imported signal notes. */
  readonly ingestScope?: string;
  /** Optional role filter for write-side extraction. */
  readonly filterRoles?: ReadonlyArray<SessionTurn["role"]>;
  /** Optional case-insensitive substring filter on turn text. */
  readonly filterTextIncludes?: string;
  /**
   * Per-row event-time backfill (A2 / t_7526e8d3). When true, each
   * emitted signal is stamped with its turn's ORIGINAL
   * `SessionTurn.timestamp` (`created_at` / `recorded_at` / `valid_from`
   * and the filename calendar day) instead of the import wall-clock, so
   * backfilling an old session log stays historically faithful and
   * recency-based reconciliation can trust the timestamps. A turn whose
   * timestamp is absent, unparseable, at/before the Unix epoch (the
   * adapter's "no timestamp" sentinel), or future-dated relative to
   * `now` falls back to `now` deterministically — no throw, no
   * future-dated or epoch signal. Default off → byte-identical to the
   * wall-clock path.
   */
  readonly preserveEventTime?: boolean;
}

/**
 * Resolve the effective stamp instant for an emitted signal under the
 * per-row event-time backfill (A2). Returns whether the instant came
 * from the turn (so the caller stamps the bi-temporal slots) or fell
 * back to `now` (so the file stays byte-identical to the wall-clock
 * path — no `recorded_at` / `valid_from` keys).
 *
 * The usable window is `epoch < ts <= now`: a timestamp at or before the
 * Unix epoch is the adapter's synthesized "no timestamp" sentinel
 * (`new Date(0)`), a future timestamp would mint a nonsensical
 * forward-dated signal during backfill, and an unparseable value is
 * `NaN` — all three fall back to `now`.
 */
export function resolveEventInstant(
  turnTimestamp: string | undefined,
  now: Date,
  preserve: boolean,
): { readonly instant: Date; readonly fromTurn: boolean } {
  if (!preserve || !turnTimestamp) return { instant: now, fromTurn: false };
  const ms = Date.parse(turnTimestamp);
  if (!Number.isFinite(ms) || ms <= 0 || ms > now.getTime()) {
    return { instant: now, fromTurn: false };
  }
  return { instant: new Date(ms), fromTurn: true };
}

/**
 * Whether an import's counters describe writes that HAPPENED or writes it
 * would have made. A dry run's `signals_created` is zero by construction,
 * which is also what a real run over a session with nothing in it reports;
 * without this the two results are the same bytes.
 */
export const IMPORT_WRITE_MODE = Object.freeze({
  applied: "applied",
  dryRun: "dry_run",
} as const);

export type ImportWriteMode = (typeof IMPORT_WRITE_MODE)[keyof typeof IMPORT_WRITE_MODE];

export const IMPORT_WRITE_MODES: ReadonlyArray<ImportWriteMode> = Object.freeze([
  IMPORT_WRITE_MODE.applied,
  IMPORT_WRITE_MODE.dryRun,
]);

export function isImportWriteMode(value: unknown): value is ImportWriteMode {
  return typeof value === "string" && (IMPORT_WRITE_MODES as ReadonlyArray<string>).includes(value);
}

export interface ImportSessionResult {
  readonly file: string;
  /** Id of the adapter that parsed the file; a registry key, not a union. */
  readonly format: string;
  /** Whether the counters below describe writes made or writes forecast. */
  readonly write_mode: ImportWriteMode;
  readonly turns_scanned: number;
  readonly signals_created: number;
  /**
   * Signals a dry run would have written. Always 0 under
   * {@link IMPORT_WRITE_MODE.applied} - a real run writes instead of
   * withholding - so the pair (`signals_created`, `signals_withheld`) says
   * which run this was and what it did in one reading.
   */
  readonly signals_withheld: number;
  readonly signals_deduped: number;
  readonly tool_replays: number;
  /** Per-skill invocations captured as skill_invoked continuity records. */
  readonly skill_invocations: number;
  readonly malformed: number;
  readonly filtered_turns: number;
  /** Capture-boundary verdict for this file (Memory Integrity Suite). */
  readonly boundary_decision: SessionCaptureDecision;
  /** Turns whose text was suppressed before any extraction. */
  readonly suppressed_turns: number;
  readonly facts_extracted: number;
  /** Facts a dry run would have written. Always 0 on an applied run. */
  readonly facts_withheld: number;
  readonly facts_deduped: number;
  /**
   * Facts the ambient extraction lane withheld whole captures of, because
   * `guardrails.ambient_writeback: false` is in force (Task 11). Each
   * suppressed capture also logs one `ambient-withheld` event carrying the
   * same count, so a consent-off import reports 0 facts written AND the
   * count it declined to capture - never a silent zero.
   */
  readonly facts_ambient_withheld: number;
  /**
   * Mined-mention records the session-mining lane wrote (recall-quality,
   * B1): one continuity record per (family, key, sessionRef), folded
   * across the run. Provenance-grade only - nothing here mints an entity
   * page; promotion is a separate, explicit step.
   */
  readonly mined_extracted: number;
  /** Mentions already folded for this (family, key, session) this run. */
  readonly mined_deduped: number;
  /** Mentions a dry run would have written. Always 0 on an applied run. */
  readonly mined_withheld: number;
  /** Secret-shaped candidates (credential URLs, token forms) refused. */
  readonly mined_secret_refused: number;
  /** Turns carrying a private region, withheld whole from mining. */
  readonly mined_private_withheld: number;
  /**
   * Mentions whose ledger append THREW this run - the miner's telemetry-grade
   * tolerance keeps the import alive, and this slot carries the failure past
   * `mineAndRecordTurn`'s `ledgerFailed` outcome so no import surface can
   * report a clean run over a ledger it could not write. A failed mention
   * stays unseen, so the next import re-folds it.
   */
  readonly mined_ledger_failed: number;
  /**
   * Mentions dropped because a session already holds the miner's
   * `MAX_MINED_KEYS_PER_SESSION` (512) distinct keys - the cap
   * `mineAndRecordTurn` enforces, surfaced here through its `capOverflow`
   * outcome so an over-cap import reports the overflow instead of a quietly
   * truncated mention set.
   */
  readonly mined_cap_overflow: number;
  readonly recall_turns_imported: number;
  readonly recall_summary_nodes: number;
  /**
   * Turns a checkpoint from an earlier, interrupted run let this one skip.
   * Always 0 on a first run, a dry run, and a run with checkpointing opted
   * out. `turns_scanned` still counts every turn the adapter yielded, so the
   * pair says how much of the file was re-read and how little was re-worked.
   */
  readonly turns_resumed: number;
  /**
   * Why a checkpoint that existed was NOT resumed from, or `null` when none
   * was refused. A boundary silently ignored is a full re-import nobody was
   * told about, which is the class of quiet this unit removes.
   */
  readonly resume_discarded: SessionResumeDiscard | null;
  /**
   * Read-back census of the signals this run claims to have written:
   * `attempted / found / missing`, with the missing dedup hashes named. A
   * dry run claims nothing and censuses zero.
   */
  readonly census: ImportCensus;
  readonly errors: ReadonlyArray<{ path: string; message: string }>;
}

export interface ImportSessionPathResult {
  readonly files: ReadonlyArray<ImportSessionResult>;
  /** Per-file warnings (autodetect failures, IO errors). */
  readonly warnings: ReadonlyArray<{ path: string; message: string }>;
}

/**
 * Portable session identity for provenance refs (Vault portability suite).
 *
 * A session file's absolute path is machine-local, so persisting it into a
 * synced signal's `source` / `session_ref` bakes in a host path (e.g.
 * `/root/vault/...` vs a Mac/Android home) that no Syncthing peer can
 * resolve. We key provenance by the session file's basename instead — the
 * same identity the recall DAG uses — so signal provenance and recall
 * records join on one portable id. An explicit `recallSessionId` wins so a
 * caller can pin a stable logical id.
 */
export function sessionRefIdentity(absPath: string, recallSessionId?: string): string {
  const explicit = recallSessionId?.trim();
  return explicit && explicit.length > 0 ? explicit : basename(absPath);
}

/**
 * Pick an adapter — by explicit format, or autodetect.
 *
 * Autodetect needs exactly one line, and `readFirstLine` stops at the first
 * newline: the file used to be read whole here and then read a second time by
 * `adapter.iterate`. An explicit `--format` reads nothing at all - hence the
 * lazy `readHead`, shared with the resume checkpoint's file-identity probe so
 * the head line is read at most once per import and not at all when neither
 * caller needs it.
 */
async function chooseAdapter(
  path: string,
  readHead: () => Promise<string>,
  format?: SessionAdapterId,
): Promise<SessionAdapter> {
  if (format !== undefined) {
    return getAdapter(format);
  }
  const first = await readHead();
  const a = detectAdapter(first);
  if (!a) {
    throw new SessionImportError(
      "DETECT_FAIL",
      `could not autodetect session format for ${path}; pass --format to override`,
    );
  }
  return a;
}

export async function importSession(
  vault: string,
  path: string,
  opts: ImportSessionOptions,
): Promise<ImportSessionResult> {
  if (!existsSync(path)) {
    throw new SessionImportError("IO", `session file does not exist: ${path}`);
  }
  let headLine: string | null = null;
  const readHead = async (): Promise<string> => (headLine ??= await readFirstLine(path));
  const adapter = await chooseAdapter(path, readHead, opts.format);
  // Reuse the caller-supplied index when present (directory walk lifts
  // the build out of the per-file loop). Otherwise build our own.
  const dedup = opts.dedupIndex ?? (await loadDedupIndex(vault));

  const now = opts.now ?? new Date();
  const sinceMs = opts.since ? opts.since.getTime() : undefined;
  const absPath = resolve(path);
  // Portable provenance key for signal/fact `source` + `session_ref` and the
  // recall DAG id — never the machine-local `absPath`. See sessionRefIdentity.
  const sessionKey = sessionRefIdentity(absPath, opts.recallSessionId);
  const errors: { path: string; message: string }[] = [];

  const writeMode = opts.dryRun === true ? IMPORT_WRITE_MODE.dryRun : IMPORT_WRITE_MODE.applied;
  let turnsScanned = 0;
  let signalsCreated = 0;
  let signalsWithheld = 0;
  let signalsDeduped = 0;
  let toolReplays = 0;
  let skillInvocations = 0;
  let malformed = 0;
  let filteredTurns = 0;
  let suppressedTurns = 0;
  let factsExtracted = 0;
  let factsWithheld = 0;
  let factsDeduped = 0;
  let factsAmbientWithheld = 0;
  let minedExtracted = 0;
  let minedDeduped = 0;
  let minedWithheld = 0;
  let minedSecretRefused = 0;
  let minedPrivateWithheld = 0;
  let minedLedgerFailed = 0;
  let minedCapOverflow = 0;
  /**
   * The run's mined-mention dedupe set, keyed at (family, key,
   * sessionRef) - owned here across turns so one session folds to one
   * record per (family, key).
   */
  const minedSeen = new Set<string>();
  /**
   * Hashes a dry run has already forecast. The dedup index only learns a
   * hash when a signal actually lands, so without this a marker repeated
   * inside one rehearsal would be forecast twice where the real run counts
   * one write and one dedup.
   */
  const withheldHashes = new Set<string>();
  /**
   * Dedup hashes of the signals this run actually wrote - the claim the
   * post-import census reads back against the vault.
   */
  const createdHashes: string[] = [];
  const recallTurns: SessionTurn[] = [];
  const filterRoles =
    opts.filterRoles && opts.filterRoles.length > 0 ? new Set(opts.filterRoles) : null;
  const filterNeedle = opts.filterTextIncludes?.trim().toLowerCase() ?? null;

  // Inline helper that wraps the writeSignal call with the consistent
  // shape every session-imported signal shares.
  const emit = (input: {
    topic: string;
    signal: "positive" | "negative";
    principle: string;
    scope?: string;
    agent: string;
    note?: string;
    turnId: string;
    /** Origin turn's ISO timestamp; used for per-row event-time backfill. */
    eventTimestamp?: string;
    dedupHash: string;
  }): void => {
    if (dedup.has(input.dedupHash)) {
      signalsDeduped++;
      return;
    }
    if (opts.dryRun) {
      // Nothing is written, and the result says so: `signals_created` stays
      // 0 and the forecast lands in `signals_withheld` instead.
      if (withheldHashes.has(input.dedupHash)) {
        signalsDeduped++;
        return;
      }
      withheldHashes.add(input.dedupHash);
      signalsWithheld++;
      return;
    }
    const sessionRef = `${sessionKey}#${input.turnId}`;
    // Per-row event-time (A2): stamp the turn's original instant when
    // preservation is on and the timestamp is usable; otherwise fall
    // back to `now` and emit NO bi-temporal slots (byte-identical path).
    const { instant, fromTurn } = resolveEventInstant(
      input.eventTimestamp,
      now,
      opts.preserveEventTime === true,
    );
    try {
      const res = writeSignal(vault, {
        topic: input.topic,
        signal: input.signal,
        agent: input.agent,
        principle: input.principle,
        created_at: isoSecond(instant),
        date: isoDate(instant),
        slug: input.topic,
        ...(fromTurn
          ? {
              recorded_at: isoSecond(instant),
              valid_from: isoSecond(instant),
              // Conversation chronology (S1): carry the turn instant as
              // the authoring time so the search layer can expose it and
              // break exact hybrid-score ties toward more recent turns.
              authored_at: isoSecond(instant),
            }
          : {}),
        ...(input.scope ? { scope: input.scope } : {}),
        source: [`[[${sessionRef}]]`],
        source_type: BRAIN_SIGNAL_SOURCE_TYPE.session,
        dedup_hash: input.dedupHash,
        session_ref: sessionRef,
        ...(input.note || opts.ingestScope
          ? {
              raw: [opts.ingestScope ? `[ingest_scope:${opts.ingestScope}]` : "", input.note ?? ""]
                .filter((chunk) => chunk.length > 0)
                .join("\n"),
            }
          : {}),
        ...(opts.rawCodec === true ? { rawCodec: true } : {}),
      });
      // A session-replayed signal is prompt-derived material by
      // definition - it is a turn of an agent conversation - so the
      // content-class stamp rides the same run that wrote it (F5). The
      // signal writer composes its own frontmatter and exposes no
      // extension point, so the stamp lands as a line insert on the
      // bytes this call just wrote; a deduped write (empty path) has
      // nothing new to stamp. The stamp failing never loses the signal:
      // the error surfaces by name in this import's errors, separate
      // from the writeSignal arm so neither stage can be mistaken for
      // the other.
      if (res.path !== "") {
        try {
          stampPromptDerivedLine(res.path);
        } catch (err) {
          // The row names `res.path` - the signal page the failure is
          // about - never `absPath`, which is the transcript this import
          // only read. An operator following the row must land on the
          // page that went unstamped.
          errors.push({
            path: res.path,
            message: `content-class stamp failed: ${(err as Error).message ?? String(err)}`,
          });
        }
      }
      dedup.set(input.dedupHash, { id: res.id, path: res.path });
      createdHashes.push(input.dedupHash);
      signalsCreated++;
    } catch (err) {
      errors.push({
        path: absPath,
        message: `writeSignal failed: ${(err as Error).message ?? String(err)}`,
      });
    }
  };

  // Capture boundary (Memory Integrity Suite): classify the session
  // FIRST. An ignored file imports nothing; a stateless file is
  // scanned read-only (no signals, no recall records, no facts).
  const boundary = buildCaptureBoundary(vault);
  const boundaryDecision = boundary.sessionDecision(opts.recallSessionId, absPath);
  const mayWrite = boundaryDecision === "capture";
  const emptyResult = (): ImportSessionResult =>
    Object.freeze({
      file: absPath,
      format: adapter.id,
      write_mode: writeMode,
      turns_scanned: 0,
      signals_created: 0,
      signals_withheld: 0,
      signals_deduped: 0,
      tool_replays: 0,
      skill_invocations: 0,
      malformed: 0,
      filtered_turns: 0,
      boundary_decision: boundaryDecision,
      suppressed_turns: 0,
      facts_extracted: 0,
      facts_withheld: 0,
      facts_deduped: 0,
      facts_ambient_withheld: 0,
      mined_extracted: 0,
      mined_deduped: 0,
      mined_withheld: 0,
      mined_secret_refused: 0,
      mined_private_withheld: 0,
      mined_ledger_failed: 0,
      mined_cap_overflow: 0,
      recall_turns_imported: 0,
      recall_summary_nodes: 0,
      turns_resumed: 0,
      resume_discarded: null,
      census: censusSessionSignals(vault, []),
      errors: Object.freeze([]),
    });
  if (boundaryDecision === "ignore") return emptyResult();

  // Resume (Unit F). Only an APPLIED capture run checkpoints: a dry run
  // writes nothing to resume, and a stateless/ignored file is scanned
  // read-only. The id folds the import's filters in, so a differently
  // filtered run never inherits this one's boundary.
  const checkpointActive = opts.dryRun !== true && mayWrite && checkpointingEnabled();
  const importId = computeSessionImportId(absPath, opts);
  let resumeFrom = 0;
  let resumeDiscarded: SessionResumeDiscard | null = null;
  let turnsResumed = 0;
  let fileIdentity = { headHash: "", bytes: 0 };
  if (checkpointActive) {
    fileIdentity = {
      headHash: computeSessionHeadHash(await readHead()),
      bytes: statSync(absPath).size,
    };
    const decision = resolveSessionResume(vault, importId, fileIdentity);
    resumeFrom = decision.turns;
    resumeDiscarded = decision.discarded;
  }

  /**
   * Whether a turn belongs to this run's question, and which counter says
   * so when it does not. One function because the resumed prefix has to ask
   * the same question the main body does - a filter applied on one path and
   * not the other would put a turn in the recall DAG that the run's own
   * filters exclude.
   */
  const admitTurn = (turn: SessionTurn): "admit" | "before_since" | "filtered" | "suppressed" => {
    if (sinceMs !== undefined) {
      const t = Date.parse(turn.timestamp);
      if (Number.isFinite(t) && t < sinceMs) return "before_since";
    }
    if (filterRoles !== null && !filterRoles.has(turn.role)) return "filtered";
    if (filterNeedle !== null) {
      const haystack = turn.text?.toLowerCase() ?? "";
      if (!haystack.includes(filterNeedle)) return "filtered";
    }
    // Message-level boundary: suppressed text never reaches marker or
    // fact extraction (and is not stored for recall).
    if (turn.text && boundary.suppressMessage(turn.text)) return "suppressed";
    return "admit";
  };

  for await (const turn of adapter.iterate(path)) {
    turnsScanned++;
    // Past the boundary an earlier run recorded: the extraction, the
    // hashing and the writes for these turns already happened. The lines
    // are still read because a JSONL transcript cannot be seeked into.
    if (turnsScanned <= resumeFrom) {
      turnsResumed++;
      // Recall is the one thing the boundary does NOT vouch for. It is
      // accumulated in memory and committed after this loop, so the run
      // that stopped at the boundary committed none of it - skipping these
      // turns would leave the head of the transcript permanently absent
      // from the recall DAG while the run reported success. Re-collecting
      // them is cheap (the lines are read either way) and idempotent (the
      // recall importer keys each turn on a content dedupe key).
      if (opts.recall === true && mayWrite && admitTurn(turn) === "admit") recallTurns.push(turn);
      continue;
    }
    // Everything before THIS turn is done, so the boundary is recorded
    // here rather than at the foot of the loop - the body has several
    // early `continue`s, and a turn skipped by a filter needs no re-work
    // either.
    const completedTurns = turnsScanned - 1;
    if (
      checkpointActive &&
      completedTurns > resumeFrom &&
      completedTurns % SESSION_CHECKPOINT_TURN_INTERVAL === 0
    ) {
      recordSessionProgress(
        vault,
        importId,
        {
          sessionFile: absPath,
          headHash: fileIdentity.headHash,
          bytes: fileIdentity.bytes,
          turnsCompleted: completedTurns,
        },
        now,
      );
    }
    const admission = admitTurn(turn);
    if (admission === "filtered") {
      filteredTurns++;
      continue;
    }
    if (admission === "suppressed") {
      suppressedTurns++;
      continue;
    }
    if (admission === "before_since") continue;
    if (opts.recall === true && mayWrite) recallTurns.push(turn);

    // Facts from USER turns only (the HANDOFF carve-out's conservative
    // core: bare assistant output is never auto-extracted).
    if (mayWrite && turn.text && turn.role === "user") {
      const routed = routeExtractedFacts(vault, {
        facts: extractFacts(turn.text),
        agent: agentLabelForTurn(turn, opts.agent),
        now,
        sessionRef: `${sessionKey}#${turn.turnId}`,
        dedup,
        ...(opts.dryRun === true ? { dryRun: true } : {}),
      });
      factsExtracted += routed.created;
      factsWithheld += routed.withheld;
      factsDeduped += routed.deduped;
      factsAmbientWithheld += routed.ambientWithheld;
    }

    // Mined mentions (recall-quality, B1): provenance-grade, from BOTH
    // roles, here in the loop where the raw turn text predates payload
    // externalization. A dry run forecasts; a stateless scan never gets
    // here (mayWrite is capture-only). Secret-shaped candidates are
    // refused and counted inside the miner.
    if (mayWrite && turn.text) {
      const mined = mineAndRecordTurn(vault, {
        vault,
        text: turn.text,
        sessionRef: sessionKey,
        turnId: turn.turnId,
        turnTimestamp: turn.timestamp,
        now,
        seen: minedSeen,
        ...(opts.dryRun === true ? { dryRun: true } : {}),
      });
      minedExtracted += mined.extracted;
      minedDeduped += mined.deduped;
      minedWithheld += mined.withheld;
      minedSecretRefused += mined.secretRefused;
      minedPrivateWithheld += mined.privateWithheld;
      minedLedgerFailed += mined.ledgerFailed;
      minedCapOverflow += mined.capOverflow;
    }

    // Path A — markers in text.
    if (mayWrite && turn.text && (turn.role === "user" || turn.role === "assistant")) {
      const discovery = discoverMarkersDetailed(turn.text);
      malformed += discovery.malformed;
      const markers = discovery.markers;
      for (const m of markers) {
        // Feedback markers only: loop / set markers are never imported
        // as signals (loops live-derive, set markers apply via write-back).
        if (!isFeedbackMarker(m)) continue;
        const hash = computeDedupHash({
          topic: m.topic,
          signal: m.signal,
          principle: m.principle,
          ...(m.scope ? { scope: m.scope } : {}),
        });
        emit({
          topic: m.topic,
          signal: m.signal,
          principle: m.principle,
          ...(m.scope ? { scope: m.scope } : {}),
          agent: m.agent ?? agentLabelForTurn(turn, opts.agent),
          ...(m.note ? { note: m.note } : {}),
          turnId: turn.turnId,
          eventTimestamp: turn.timestamp,
          dedupHash: hash,
        });
      }
    }

    // Path B — brain_feedback tool_use replay.
    if (!mayWrite) continue;
    for (const call of turn.toolCalls ?? []) {
      // Per-skill invocation telemetry (t_56a12bde): count real skill
      // invocations across runtimes as append-only skill_invoked records.
      // Deterministic and idempotent across re-imports (the source ref keys on
      // the session + call id + skill, so re-running dedupes rather than
      // double-counts). Skipped on a dry run.
      const invokedSkill = resolveInvokedSkill(call);
      if (invokedSkill !== null && opts.dryRun !== true) {
        // Offer provenance (t_ccb05134): when the call cites the offer that
        // produced it, the id rides onto the record so the invocation can be
        // joined back to that offer. A call citing none is stamped exactly as
        // before - the key is omitted, never defaulted, so "no offer was
        // cited" can never be read as "offer unknown-but-present".
        const citedOffer = readSkillOfferId(call.input);
        try {
          appendContinuityRecord(vault, {
            kind: "skill_invoked",
            createdAt: invocationTimestamp(turn.timestamp, now),
            sourceRefs: [{ id: `${sessionKey}:${call.id ?? turn.turnId}:${invokedSkill}` }],
            payload: {
              skill: invokedSkill,
              agent: agentLabelForTurn(turn, opts.agent),
              tool: call.name,
              runtime: adapter.id,
              ...(citedOffer !== null ? { [SKILL_OFFER_ID_KEY]: citedOffer } : {}),
            },
          });
          skillInvocations++;
        } catch {
          // Telemetry is best-effort; a failed append never fails the import.
        }
      }
      if (call.name !== "brain_feedback") continue;
      const validated = validateBrainFeedbackInput(call.input);
      if (!validated.ok) {
        malformed++;
        continue;
      }
      const v = validated.value;
      const hash = computeDedupHash({
        topic: v.topic,
        signal: v.signal,
        principle: v.principle,
        ...(v.scope ? { scope: v.scope } : {}),
      });
      toolReplays++;
      emit({
        topic: v.topic,
        signal: v.signal,
        principle: v.principle,
        ...(v.scope ? { scope: v.scope } : {}),
        agent: v.agent ?? agentLabelForTurn(turn, opts.agent),
        ...(v.raw ? { note: v.raw } : {}),
        turnId: call.id ?? turn.turnId,
        eventTimestamp: turn.timestamp,
        dedupHash: hash,
      });
    }
  }

  let recallTurnsImported = 0;
  let recallSummaryNodes = 0;
  if (opts.recall === true && opts.dryRun !== true && recallTurns.length > 0) {
    try {
      // Same portable identity used for signal/fact provenance above, so
      // the recall DAG and the emitted signals key this session identically.
      const recallSessionId = sessionKey;
      // Persisted-link resolution only: without a clock the crutch
      // never infers a new link, so an unknown session imports flat.
      const lineage =
        opts.recallLineage ??
        resolveSessionLineage({ sessionId: recallSessionId }, { ledger: readLineageLedger(vault) });
      const recalled = importSessionRecall(vault, {
        sessionId: recallSessionId,
        turns: recallTurns,
        createdAt: isoSecond(now),
        ...(opts.recallSummaryGroupSize !== undefined
          ? { summaryGroupSize: opts.recallSummaryGroupSize }
          : {}),
        ...(lineage.source !== "flat" ? { lineage } : {}),
      });
      recallTurnsImported = recalled.rawTurns.length;
      recallSummaryNodes = recalled.summaryNodes.length;
    } catch (err) {
      errors.push({
        path: absPath,
        message: `importSessionRecall failed: ${(err as Error).message ?? String(err)}`,
      });
    }
  }

  // Dedup observability (Unit F): one record per import run that actually
  // dropped something, keyed by the portable session identity this import
  // stamps on every signal it writes. A dry run reports its count and
  // writes nothing.
  if (opts.dryRun !== true) {
    emitIngestDedupReport(vault, {
      surface: "session_import",
      sources: [{ ref: sessionKey, exactDeduped: signalsDeduped + factsDeduped }],
      createdAt: now.toISOString(),
    });
  }

  // The run drained the file, so its resume point has nothing left to say -
  // the same settle the ingest lane performs on a fully drained plan, after
  // which the dedup index is the authoritative final state.
  if (checkpointActive) clearSessionCheckpoint(vault, importId);

  return Object.freeze({
    file: absPath,
    format: adapter.id,
    write_mode: writeMode,
    turns_scanned: turnsScanned,
    signals_created: signalsCreated,
    signals_withheld: signalsWithheld,
    signals_deduped: signalsDeduped,
    tool_replays: toolReplays,
    skill_invocations: skillInvocations,
    malformed,
    boundary_decision: boundaryDecision,
    suppressed_turns: suppressedTurns,
    facts_extracted: factsExtracted,
    facts_withheld: factsWithheld,
    facts_deduped: factsDeduped,
    facts_ambient_withheld: factsAmbientWithheld,
    mined_extracted: minedExtracted,
    mined_deduped: minedDeduped,
    mined_withheld: minedWithheld,
    mined_secret_refused: minedSecretRefused,
    mined_private_withheld: minedPrivateWithheld,
    mined_ledger_failed: minedLedgerFailed,
    mined_cap_overflow: minedCapOverflow,
    filtered_turns: filteredTurns,
    recall_turns_imported: recallTurnsImported,
    recall_summary_nodes: recallSummaryNodes,
    turns_resumed: turnsResumed,
    resume_discarded: resumeDiscarded,
    // Read back AFTER every write this run makes, including the recall
    // import above: the point is to ask the disk, not the run's own belief.
    census: censusSessionSignals(vault, createdHashes),
    errors: Object.freeze(errors),
  });
}

/**
 * Compose the `agent` field for a session-imported signal. Order of
 * preference, highest first:
 *
 *   1. the marker / tool-input's explicit agent (handled by the caller,
 *      not here);
 *   2. the DELEGATED identity, when the turn carries the host's sub-agent
 *      id - a sidechain turn was written by a different agent than the one
 *      that opened the session, and a sub-agent transcript reuses the
 *      parent's session id, so this is the only place the boundary
 *      survives;
 *   3. `opts.agent` - `--agent` when the operator passed one, otherwise the
 *      server-resolved identity.
 *
 * There is no per-adapter constant below that any more. It sat at the TOP
 * of this order while being non-empty in every shipped adapter, so
 * `opts.agent` was unreachable and `--agent` was validated and discarded;
 * and the three constants it stamped - `claude`, `codex`, `hermes` - are
 * strings `normalizeAgentArgument` rejects as placeholders on every other
 * surface, so imported memory was attributed to a name no writer could
 * have named itself.
 */
function agentLabelForTurn(turn: SessionTurn, fallback: string): string {
  return turn.agentId !== undefined ? delegatedAgentName(fallback, turn.agentId) : fallback;
}

/**
 * Extract the invoked skill name from a tool call, or null when the call is
 * not a skill invocation. Counts an actual skill fetch (`get_skill`, however
 * namespaced by the runtime) and the host-native `Skill` tool; discovery
 * (`list_skills`) and per-turn relevance scoring (`skills_attach`) are not
 * invocations and are ignored.
 */
function resolveInvokedSkill(call: SessionToolCall): string | null {
  const input = call.input ?? {};
  const pick = (key: string): string | null => {
    const value = input[key];
    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
  };
  const name = call.name;
  if (name === "get_skill" || name.endsWith("__get_skill")) {
    return pick("name") ?? pick("skill");
  }
  if (name === "Skill") {
    return pick("command") ?? pick("skill") ?? pick("name");
  }
  return null;
}

/** ISO-second timestamp for an invocation: the turn's own time when valid. */
function invocationTimestamp(turnTimestamp: string | undefined, now: Date): string {
  if (turnTimestamp) {
    const ms = Date.parse(turnTimestamp);
    if (Number.isFinite(ms) && ms > 0 && ms <= now.getTime()) return isoSecond(new Date(ms));
  }
  return isoSecond(now);
}

export async function importSessionPath(
  vault: string,
  path: string,
  opts: ImportSessionOptions,
): Promise<ImportSessionPathResult> {
  const stat = statSync(path);
  if (stat.isFile()) {
    const res = await importSession(vault, path, opts);
    return Object.freeze({
      files: Object.freeze([res]),
      warnings: Object.freeze([]),
    });
  }
  // Directory walk: build the dedup index ONCE and thread it through
  // every per-file `importSession` call. emit() mutates the shared map
  // as new signals are written, so cross-file dedup happens too.
  const files: ImportSessionResult[] = [];
  const warnings: { path: string; message: string }[] = [];
  // Shared with the transcript dataset export, so both agree on what a
  // session log is and neither can quietly widen the rule alone.
  const queue = sessionFilesUnder(path);

  const sharedDedup = opts.dedupIndex ?? (await loadDedupIndex(vault));
  const perFileOpts: ImportSessionOptions = {
    ...opts,
    dedupIndex: sharedDedup,
  };

  // Sequential — writes go to the same Brain/inbox/ and share the
  // dedup map; parallelising would race on both.
  for (const file of queue) {
    try {
      const res = await importSession(vault, file, perFileOpts);
      files.push(res);
    } catch (err) {
      if (err instanceof SessionImportError) {
        warnings.push({ path: file, message: err.message });
        continue;
      }
      throw err;
    }
  }
  return Object.freeze({
    files: Object.freeze(files),
    warnings: Object.freeze(warnings),
  });
}