trajectories 0.0.0 → 0.1.1

package/legacy/src/cli.ts

@@ -0,0 +1,1293 @@
+import { readFileSync } from "node:fs";
+import { SessionNotFoundError, StoreNotInitializedError, TrajectoryDb } from "./db.js";
+import { aggregateIngestDiagnostics } from "./diagnostics.js";
+import {
+  DEFAULT_MODEL_NAME,
+  pullModel,
+  setEmbeddingProvider,
+} from "./embeddings.js";
+import {
+  GeminiEmbeddingProvider,
+  resolveGeminiKey,
+} from "./gemini_embeddings.js";
+import { ledgerId } from "./identity.js";
+import { DEFAULT_INGEST_RECORD_BYTES, ingestDiscoveredSession, nativeIngestCatchResult } from "./ingest.js";
+import { normalizeDiscoveredSession } from "./normalizer.js";
+import { FTS_SYNTAX_FALLBACK_REASON, openReadOnlyStore, ReaderError, TrajectoryReader } from "./reader.js";
+import { SCHEMA_VERSION } from "./schema.js";
+import { scanSessions } from "./scanner.js";
+import { readStoreStatus, StoreStatusError } from "./store-status.js";
+import { executeSyncMaintenanceStdio, executeSyncWorkerStdio, executeSyncPreparationStdio, SyncPreparationError, runSync } from "./sync.js";
+import type { BuildSummary, DiscoveredSession, QueryResult, ScanOutcome, TombstoneRecord } from "./types.js";
+import { LedgerWatcher } from "./watch.js";
+import {
+  acquireWriterLease,
+  DEFAULT_WRITER_LEASE_WAIT_MS,
+  describeLeaseHolder,
+  isMemoryStorePath,
+  WriterLeaseBusyError,
+} from "./writer-lease.js";
+
+const VERSION: string = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+
+/** The provider a `--embedding` value names; an absent flag asks for local, a bare `--embedding` asks for Gemini. */
+function requestedEmbedding(value: string | boolean | undefined): string {
+  return value === true ? "gemini" : typeof value === "string" ? value : "local";
+}
+
+/**
+ * The one place that decides which `--embedding` values exist. The flag parser
+ * runs it for every verb — a verb that never embeds still has to reject a typo
+ * rather than accept a provider it will ignore — and the wiring below runs it
+ * again before selecting a provider, so neither site can drift.
+ */
+function assertKnownEmbedding(value: string | boolean | undefined): void {
+  const requested = requestedEmbedding(value);
+  if (requested !== "local" && requested !== "gemini" && requested !== "none") {
+    throw new Error(`Unknown embedding provider: ${requested} (use local|gemini|none)`);
+  }
+}
+
+function applyEmbeddingProvider(
+  flags: Record<string, string | boolean>,
+  isRobot: boolean,
+): void {
+  assertKnownEmbedding(flags.embedding);
+  // Local embedding is the privacy-safe default. Cloud embedding is enabled
+  // only when the caller explicitly asks for Gemini.
+  if (requestedEmbedding(flags.embedding) !== "gemini") return;
+  if (resolveGeminiKey()) {
+    setEmbeddingProvider(new GeminiEmbeddingProvider());
+    return;
+  }
+  const warn = "No Gemini API key found; falling back to local MiniLM embeddings.";
+  if (isRobot) console.error(warn);
+  else console.warn(warn);
+}
+
+/** Options that distinguish the canonical `ledger` executable from legacy entrypoints. */
+export interface CliOptions {
+  /** Name used in help, version, and error strings (default: "traj-bridge"). */
+  programName?: string;
+  /** Help-text suffix describing the default database resolution. */
+  dbHelpNote?: string;
+}
+
+export async function runCli(argv: string[], options: CliOptions = {}): Promise<void> {
+  const isRobot = argv.includes("--robot");
+  const programName = options.programName ?? "traj-bridge";
+  const dbHelpNote = options.dbHelpNote ?? " (default: ledger.sqlite)";
+
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    if (isRobot && argv.length === 0) {
+      emitRobotError(
+        "MISSING_COMMAND",
+        "Please specify a command (search, recent, sync, status, scan, build, watch, models).",
+      );
+    }
+    printHelp(programName, dbHelpNote);
+    return;
+  }
+
+  if (argv.includes("--version") || argv.includes("-v")) {
+    if (programName === "trajectories") {
+      if (isRobot) {
+        console.log(JSON.stringify({ version: VERSION, name: "trajectories" }));
+      } else {
+        console.log(`Trajectories v${VERSION}`);
+      }
+      return;
+    }
+    if (isRobot) {
+      console.log(JSON.stringify({ version: VERSION, name: "traj-bridge" }));
+    } else {
+      console.log(`traj-bridge v${VERSION}`);
+    }
+    return;
+  }
+
+  const firstArg = argv[0];
+
+  try {
+    if (firstArg === "scan") {
+      await handleScan(argv.slice(1), isRobot);
+    } else if (firstArg === "sync") {
+      await handleSync(argv.slice(1), isRobot);
+    } else if (firstArg === "build") {
+      await handleBuild(argv.slice(1), isRobot);
+    } else if (firstArg === "search" || firstArg === "query") {
+      await handleQuery(argv.slice(1), isRobot, programName);
+    } else if (firstArg === "recent" || firstArg === "last") {
+      await handleLast(argv.slice(1), isRobot);
+    } else if (firstArg === "status") {
+      await handleStatus(argv.slice(1), isRobot);
+    } else if (firstArg === "delete") {
+      await handleDelete(argv.slice(1), isRobot);
+    } else if (firstArg === "watch") {
+      await handleWatch(argv.slice(1), isRobot);
+    } else if (firstArg === "models") {
+      await handleModels(argv.slice(1), isRobot);
+    } else if (firstArg === "__sync-prepare") {
+      await executeSyncPreparationStdio();
+    } else if (firstArg === "__sync-worker") {
+      // Private verb: this process IS the spawned worker child, so it writes on
+      // its parent's lease authority rather than trusting the transport marker.
+      await executeSyncWorkerStdio({ workerChild: true });
+    } else if (firstArg === "__sync-maintenance") {
+      await executeSyncMaintenanceStdio({ workerChild: true });
+    } else {
+      if (isRobot) {
+        emitRobotError("UNKNOWN_COMMAND", `Unknown command: ${firstArg}`);
+      }
+      console.error(`Unknown command: ${firstArg}\n`);
+      printHelp(programName, dbHelpNote);
+      process.exit(1);
+    }
+  } catch (err: unknown) {
+    if (err instanceof ReaderError) {
+      // A read verb's typed refusal: the store is missing, unreadable, or too
+      // new for this build. It never creates, upgrades, or repairs anything.
+      if (isRobot) {
+        emitRobotError(err.code, err.message);
+      }
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    if (err instanceof SyncPreparationError) {
+      if (isRobot) emitRobotError(err.code, err.message);
+      throw err;
+    }
+    if (err instanceof WriterLeaseBusyError) {
+      // Another writer owns the store: a typed, actionable refusal instead of
+      // silently blocking on SQLite's busy_timeout.
+      if (isRobot) {
+        emitRobotError(err.code, err.message);
+      }
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    if (err instanceof SessionNotFoundError) {
+      // `delete`'s typed refusal: the store does not hold the session the user
+      // named, so there is nothing to record. A tombstone for a session that was
+      // never ingested would be an exclusion rule, which this store does not
+      // have (db.ts).
+      if (isRobot) {
+        emitRobotError(err.code, err.message);
+      }
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    if (isRobot) {
+      const message = err instanceof Error ? err.message : String(err);
+      const code = message.includes("schema version") ? "SCHEMA_MISMATCH" : "RUNTIME_ERROR";
+      emitRobotError(code, message);
+    }
+    throw err;
+  }
+}
+
+function emitRobotError(code: string, message: string, exitCode = 1): never {
+  console.log(JSON.stringify({ error: { code, message } }));
+  process.exit(exitCode);
+}
+
+function printHelp(programName: string, dbHelpNote: string): void {
+  console.log(`Trajectories CLI v${VERSION} — invoked as ${programName}
+
+Canonical daily commands:
+  search <query>        Search normalized sessions and records using SQLite FTS5
+  recent                List most recently updated sessions
+  sync                  Run one bounded lexical ingestion pass and exit
+  status                Report store path, schema version, and counts (read-only)
+
+Advanced commands:
+  scan                  Scan and list available sessions across local coding-agent stores
+  build                 Normalize all local sessions and store in hash-deduped SQLite DB
+  watch                 Watch session stores for new/modified sessions and auto-import
+  models pull           Download the local embedding model for semantic/hybrid search
+  delete <session>      Delete one session: stop serving it and refuse to re-import it
+
+Usage:
+  ${programName} search <query> [options]
+  ${programName} recent [options]
+  ${programName} sync [options]
+  ${programName} status [options]
+  ${programName} scan [options]
+  ${programName} build [options]
+  ${programName} watch [options]
+  ${programName} models pull [options]
+  ${programName} delete <session-id> --reason <text> [--hard] [options]
+  ${programName} delete --list [options]
+
+Aliases: query = search; last = recent. The canonical executable is \`trajectories\`;
+traj-bridge and ledger-core are compatibility entrypoints for the same CLI.
+
+Options:
+  --db <path>            Path to SQLite database${dbHelpNote}
+  --sources <list>       Comma-separated list of sources (e.g. codex,pi,claude-code,hermes)
+  --source <name>        Filter search/recent results to a single source adapter
+  --embedding <provider> Embedding provider: local (default), gemini, or none (build)
+  --debounce <ms>        Debounce interval in milliseconds for batch processing (default: 2000)
+  --limit <num>          Limit number of sessions per source (default: 1000)
+  --embed                Generate embeddings during watch (off by default)
+  --reconcile-ms <ms>    Watch catch-up interval (default: 60000; 0 disables)
+  --import-budget <num>  Max sessions to normalize per source per watch tick (default: 25)
+  --max-record-bytes <n> Max JSONL record bytes during sync/watch (default: 67108864)
+  --session-budget <n>   Max distinct queued sessions per sync run (default: 25)
+  --source-byte-budget <n> Max source bytes read per sync run (default: 67108864)
+  --wall-ms <n>          Sync wall-time budget in milliseconds (default: 120000)
+  --retry-budget <n>     Failed worker allowance per sync run (default: 3)
+  --attempts-per-session <n> Max chunks per session per sync run (default: 8)
+  --read-bytes-per-second <n> Source read-rate ceiling (default: 8388608)
+  --worker-ms <n>        Per-worker deadline in milliseconds (default: 30000)
+  --workers <n>          Max concurrent session workers (default: 2)
+  --fresh-session-budget <n> Reserved recent sessions per sync run (default: 5)
+  --fresh-window-ms <n>  Recent-session window in milliseconds (default: 3600000)
+  --sync-chunk-bytes <n> Cold-rebuild chunk size (default: 1048576)
+  --pressure <mode>      Adaptive Linux pressure control: auto|off (default: auto)
+  --maintenance-ms <n>  Disposable maintenance deadline; 0 disables (default: 5000)
+  --fts-merge-pages <n>  FTS pages merged per maintenance pass; 0 disables (default: 64)
+  --json                 Output results as JSON
+  --robot                Machine-readable JSONL on stdout; human status on stderr
+  --reason <text>        Why the session is deleted; what the store's audit row records (delete)
+  --hard                 Remove the records as well, not only serving and admission (delete)
+  --list                 List the deletions this store records instead of deleting (delete)
+  --output-version <n>   Search/query robot format: 1 (legacy default) or 2 (metadata)
+  --semantic             Vector semantic search (search)
+  --hybrid               Hybrid FTS5 + semantic search via RRF (search)
+  --verbose              Show detailed progress during normalization
+  -h, --help             Show help
+  -v, --version          Show version
+`);
+}
+
+const BOOLEAN_FLAGS = new Set(["robot", "json", "verbose", "semantic", "hybrid", "embed", "hard", "list"]);
+
+function parseFlags(args: string[]): {
+  positionals: string[];
+  flags: Record<string, string | boolean>;
+} {
+  const positionals: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      const key = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+      if (eq !== -1) {
+        // --flag=value form (e.g. --db=PATH); an empty value stays a string.
+        flags[key] = arg.slice(eq + 1);
+      } else if (BOOLEAN_FLAGS.has(key)) {
+        flags[key] = true;
+      } else if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+        flags[key] = args[i + 1];
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (arg.startsWith("-")) {
+      const key = arg.slice(1);
+      flags[key] = true;
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  // Every verb that parses flags gets the same answer for a nonsense provider,
+  // whether or not it embeds: silently ignoring a typo is how `--embedding
+  // gemini` on a lexical verb, or `--embedding bogus` on any verb, becomes a
+  // search that only looks semantic. Cheap, and before any verb body runs.
+  assertKnownEmbedding(flags.embedding);
+
+  return { positionals, flags };
+}
+
+/**
+ * One operator-facing line per source that could not be listed. Human scan and
+ * verbose build share it so the same failure reads the same in both verbs.
+ */
+function formatScanOutcome(outcome: ScanOutcome): string {
+  const root = outcome.root ? ` (root ${outcome.root})` : "";
+  return `note: source ${outcome.source}: ${outcome.status}${root}${outcome.detail ? ` - ${outcome.detail}` : ""}`;
+}
+
+async function handleScan(args: string[], isRobot: boolean): Promise<void> {
+  const { flags } = parseFlags(args);
+  const sources = typeof flags.sources === "string" ? flags.sources.split(",") : undefined;
+  const limit = typeof flags.limit === "string" ? parseInt(flags.limit, 10) : undefined;
+
+  if (isRobot) {
+    console.error("Scanning local agent session stores...");
+  } else {
+    console.log("Scanning local agent session stores...");
+  }
+  const { sessions: discovered, outcomes } = await scanSessions({ sources, limit });
+
+  const bySource: Record<string, number> = {};
+  for (const s of discovered) {
+    bySource[s.source] = (bySource[s.source] ?? 0) + 1;
+  }
+
+  if (isRobot) {
+    if (flags.json) {
+      console.log(JSON.stringify({ total: discovered.length, bySource, sessions: discovered, outcomes }));
+    } else {
+      // The outcomes line leads, like search_meta: a consumer that filters
+      // sessions still learns which sources were covered.
+      console.log(JSON.stringify({ type: "scan_outcomes", outcomes }));
+      for (const s of discovered) {
+        console.log(
+          JSON.stringify({
+            id: s.id,
+            source: s.source,
+            path: s.path,
+            updatedAt: s.updatedAt,
+            sizeBytes: s.sizeBytes,
+          }),
+        );
+      }
+    }
+    return;
+  }
+
+  // A source that is simply not installed is the normal case, not news: only
+  // anomalies reach stderr. Robots still get every row, including missing_root.
+  for (const outcome of outcomes) {
+    if (outcome.status === "listable" || outcome.status === "missing_root") continue;
+    console.error(formatScanOutcome(outcome));
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify({ total: discovered.length, bySource, sessions: discovered, outcomes }, null, 2));
+    return;
+  }
+
+  console.log(`\nDiscovered ${discovered.length} sessions across ${Object.keys(bySource).length} sources:\n`);
+  for (const [source, count] of Object.entries(bySource).sort((a, b) => b[1] - a[1])) {
+    console.log(`  - ${source.padEnd(16)}: ${count} sessions`);
+  }
+
+  console.log(`\nTotal: ${discovered.length} sessions`);
+}
+
+async function handleBuild(args: string[], isRobot: boolean): Promise<void> {
+  const { flags } = parseFlags(args);
+  // "none" builds lexical-only: no provider wiring at all, so a quota-limited
+  // host needs neither the Gemini key nor the local ONNX download (issue #4).
+  // Any other value wires the global provider as before; buildStore only
+  // consults the mode for the none shortcut.
+  const embedMode = requestedEmbedding(flags.embedding) === "none" ? "none" : "provider";
+  if (embedMode !== "none") applyEmbeddingProvider(flags, isRobot);
+  const dbPath = typeof flags.db === "string" ? flags.db : "ledger.sqlite";
+  // The lease attaches before any store handle exists: a refused build must
+  // leave the database exactly as it found it.
+  const lease = isMemoryStorePath(dbPath)
+    ? null
+    : acquireWriterLease(dbPath, { waitMs: DEFAULT_WRITER_LEASE_WAIT_MS, holder: "build" });
+  try {
+    await buildStore(dbPath, isRobot, {
+      sources: typeof flags.sources === "string" ? flags.sources.split(",") : undefined,
+      limit: typeof flags.limit === "string" ? parseInt(flags.limit, 10) : undefined,
+      verbose: Boolean(flags.verbose),
+      embedMode,
+    });
+  } finally {
+    lease?.close();
+  }
+}
+
+interface BuildOptions {
+  sources?: string[];
+  limit?: number;
+  verbose: boolean;
+  /** `none` builds lexical-only; `provider` defers to the wired global provider. */
+  embedMode: "provider" | "none";
+}
+
+async function buildStore(dbPath: string, isRobot: boolean, options: BuildOptions): Promise<void> {
+  const { sources, limit, verbose, embedMode } = options;
+
+  const logProse = isRobot ? console.error : console.log;
+
+  logProse(`Building SQLite store at ${dbPath}...`);
+  const { sessions: discovered, outcomes } = await scanSessions({ sources, limit });
+  logProse(`Discovered ${discovered.length} candidate sessions to import.`);
+  if (verbose) {
+    for (const outcome of outcomes) {
+      if (outcome.status === "listable" || outcome.status === "missing_root") continue;
+      if (isRobot) console.log(JSON.stringify({ type: "scan_outcome", ...outcome }));
+      else console.log(`  ${formatScanOutcome(outcome)}`);
+    }
+  }
+
+  const db = new TrajectoryDb(dbPath);
+  try {
+    // The build holds the lease for this whole verb, so a pending index
+    // re-derivation (derive-rule counter, C2) is this verb's one-shot too — the
+    // same work `sync` runs, taken before the import loop so the rest of the build
+    // reads the index it just derived. Without it an upgraded store would keep
+    // answering from an index derived under other rules until some other pass ran.
+    const deriveStarted = performance.now();
+    const deriveMs = db.reindexFts() ? performance.now() - deriveStarted : 0;
+
+    // The build holds the lease for this whole verb, so the scan verdicts land
+    // durably here too — the same single choke point sync uses, under the store
+    // handle the pass already migrated.
+    db.recordSourceCoverage(outcomes);
+
+    const summary: BuildSummary = {
+      scanned: discovered.length,
+      imported: 0,
+      deduped: 0,
+      failed: 0,
+      unembedded: 0,
+      embedding_skipped: 0,
+      embedding_failed: 0,
+      tombstoned: 0,
+      totalRecords: 0,
+      sources: {},
+    };
+
+    const CHUNK_SIZE = 16;
+  // One place that counts and reports a refused listing, so the two axes
+  // (refused before the read, refused by the store's own guard inside ingest)
+  // cannot be counted differently or reported in different words.
+  const countTombstoned = (item: DiscoveredSession, tombstone: TombstoneRecord): void => {
+    summary.tombstoned++;
+    summary.sources[item.source].tombstoned++;
+    if (!verbose) return;
+    if (isRobot) {
+      console.log(JSON.stringify({
+        type: "session", action: "tombstoned", source: item.source, id: item.id,
+        mode: tombstone.mode, deleted_at: tombstone.deleted_at,
+      }));
+    } else {
+      console.log(`  [TOMBSTONED] ${item.source}/${item.id} (${tombstone.mode}; deleted ${tombstone.deleted_at})`);
+    }
+  };
+  for (let i = 0; i < discovered.length; i += CHUNK_SIZE) {
+    const chunk = discovered.slice(i, i + CHUNK_SIZE);
+    const normalizedChunk = await Promise.all(
+      chunk.map(async (item) => {
+        // The deletion's listing axis, first because it is the cheap one and the
+        // one that saves the most work: a listing whose native id names a deleted
+        // session is refused before its file is opened. The committed id is
+        // checked in the loop below, after normalization, for the sources that
+        // group several files under one session id.
+        if (db.tombstoneForListing(item)) return { item, norm: null };
+        // Native stores must be read at commit time, not retained across earlier embeddings.
+        const norm = item.native ? null : await normalizeDiscoveredSession(item);
+        return { item, norm };
+      }),
+    );
+
+    for (const { item, norm } of normalizedChunk) {
+      if (!summary.sources[item.source]) {
+        summary.sources[item.source] = { scanned: 0, imported: 0, deduped: 0, failed: 0, tombstoned: 0 };
+      }
+      summary.sources[item.source].scanned++;
+
+      // The deletion's two axes, in one verdict: the listing's native id (the
+      // same probe that kept the file from being read above, and the one that
+      // covers a re-scan or a copy at another path) and, for a source that
+      // groups files under a group id, the committed session id.
+      const tombstone = db.tombstoneForListing(item) ?? (norm ? db.getTombstone(norm.session.id) : null);
+      if (tombstone) {
+        countTombstoned(item, tombstone);
+        continue;
+      }
+
+      let session = norm?.session;
+      let records = norm?.records;
+      let updated = false;
+      let deduped = false;
+      if (item.native) {
+        const existed = db.getSession(ledgerId(item.source, item.id)) !== null;
+        const result = await ingestDiscoveredSession(db, item, {
+          maxRecordBytes: DEFAULT_INGEST_RECORD_BYTES,
+        }).catch((error: unknown) => nativeIngestCatchResult(error, item.id));
+        const cachedFailure = result.kind === "unchanged" &&
+          db.getIngestCursor(item.source, item.id, item.path)?.status === "failed";
+        const warnings = cachedFailure
+          ? ["Native ingestion previously failed; the unchanged source remains skipped."]
+          : result.warnings ?? [];
+        for (const warning of warnings) {
+          console.error("[ledger] ingest warning:", JSON.stringify({ source: item.source, sourcePath: item.path, warning }));
+        }
+        if (result.kind === "tombstoned") {
+          // The store's own guard refused the commit: a source grouped this
+          // listing under a session id the pass could not name before the read,
+          // or the session was deleted while the pass held it. The refusal names
+          // the session, so the audit row is reachable from here.
+          const refused = db.tombstoneForListing(item) ?? (result.sessionId ? db.getTombstone(result.sessionId) : null);
+          if (refused) countTombstoned(item, refused);
+          continue;
+        }
+        if (result.kind !== "skipped" && !cachedFailure && result.sessionId) {
+          session = db.getSession(result.sessionId) ?? undefined;
+          records = session ? db.getSessionRecords(session.id) : undefined;
+          updated = existed;
+          deduped = result.kind === "deduped" || result.kind === "unchanged";
+        }
+      } else if (norm) {
+        ({ updated, deduped } = db.saveSession(
+          norm.session, norm.records, aggregateIngestDiagnostics(norm.diagnostics),
+        ));
+      }
+
+      if (!session || !records) {
+          summary.failed++;
+          summary.sources[item.source].failed++;
+          if (item.native && verbose) {
+            if (isRobot) console.log(JSON.stringify({ type: "session", action: "skip", source: item.source, id: item.id }));
+            else console.log(`  [SKIP] ${item.source}/${item.id}`);
+          }
+          continue;
+        }
+
+        if (embedMode === "none") {
+          summary.embedding_skipped++;
+        } else if (!deduped || !db.hasSessionEmbeddings(session.id)) {
+          try {
+            await db.embedSessionRecords(session.id, records);
+          } catch (err) {
+            // Embeddings are enrichment. Persisted canonical records remain valid
+            // and later build/watch runs can retry the missing vectors.
+            summary.embedding_failed++;
+            if (verbose) {
+              if (isRobot) {
+                console.log(JSON.stringify({ type: "session", action: "unembedded", source: item.source, id: session.id }));
+              } else {
+                console.log(`  [UNEMBED] ${item.source}/${session.id}`);
+              }
+            }
+            // Stderr is the human-progress channel in robot mode too: stdout
+            // stays data-only, but the outage must not be silent.
+            console.error(`[ledger] embedding failed for ${item.source}/${session.id}:`, err);
+          }
+        }
+        // Work skipped/failing is not proof that previously stored vectors vanished.
+        if (!db.hasStoredSessionEmbeddings(session.id)) summary.unembedded++;
+        if (deduped) {
+          summary.deduped++;
+          summary.sources[item.source].deduped++;
+          if (verbose) {
+            if (isRobot) {
+              console.log(JSON.stringify({ type: "session", action: "dedup", source: item.source, id: item.id }));
+            } else {
+              console.log(`  [DEDUP] ${item.source}/${item.id}`);
+            }
+          }
+        } else {
+          summary.imported++;
+          summary.totalRecords += records.length;
+          summary.sources[item.source].imported++;
+          if (verbose) {
+            if (isRobot) {
+              console.log(
+                JSON.stringify({
+                  type: "session",
+                  action: updated ? "update" : "import",
+                  source: item.source,
+                  id: item.id,
+                  records: records.length,
+                }),
+              );
+            } else {
+              console.log(`  [${updated ? "UPDATE" : "IMPORT"}] ${item.source}/${item.id} (${records.length} records)`);
+            }
+          }
+        }
+      }
+    }
+
+    if (isRobot) {
+      console.log(
+        JSON.stringify({
+          type: "summary",
+          scanned: summary.scanned,
+          imported: summary.imported,
+          deduped: summary.deduped,
+          failed: summary.failed,
+          unembedded: summary.unembedded,
+          embedding_skipped: summary.embedding_skipped,
+          embedding_failed: summary.embedding_failed,
+          tombstoned: summary.tombstoned,
+          totalRecords: summary.totalRecords,
+          deriveMs,
+          sources: summary.sources,
+        }),
+      );
+    } else {
+      console.log("\nBuild complete:");
+      console.log(`  Sessions in DB : ${db.getSessionCount()}`);
+      console.log(`  Records in DB  : ${db.getRecordCount()}`);
+      console.log(`  Imported       : ${summary.imported}`);
+      console.log(`  Deduped        : ${summary.deduped}`);
+      console.log(`  Skipped/Empty  : ${summary.failed}`);
+      if (summary.unembedded > 0) {
+        console.log(`  Unembedded     : ${summary.unembedded} (vectors absent; later builds retry)`);
+      }
+      if (summary.embedding_skipped) console.log(`  Embedding skipped: ${summary.embedding_skipped}`);
+      if (summary.embedding_failed) console.log(`  Embedding failed : ${summary.embedding_failed} (coverage may be partial)`);
+      if (summary.tombstoned > 0) {
+        console.log(`  Tombstoned     : ${summary.tombstoned} (deleted by the user; not re-imported, see \`delete --list\`)`);
+      }
+      if (deriveMs > 0) {
+        console.log(
+          `  Re-derived     : ${Math.round(deriveMs)}ms (records_fts and titles_fts rebuilt from this store; no source was re-read)`,
+        );
+      }
+      console.log("\nBreakdown by source:");
+      for (const [source, stats] of Object.entries(summary.sources)) {
+        console.log(
+          `  - ${source.padEnd(14)}: ${stats.imported} imported, ${stats.deduped} deduped, ${stats.failed} skipped` +
+            `${stats.tombstoned ? `, ${stats.tombstoned} tombstoned` : ""} (from ${stats.scanned} scanned)`,
+        );
+      }
+    }
+  } finally { db.close(); }
+}
+
+function numericFlag(flags: Record<string, string | boolean>, name: string): number | undefined {
+  const value = flags[name];
+  return value === undefined ? undefined : typeof value === "string" ? Number(value) : NaN;
+}
+
+async function handleSync(args: string[], isRobot: boolean): Promise<void> {
+  const { flags } = parseFlags(args);
+  const dbPath = typeof flags.db === "string" ? flags.db : "ledger.sqlite";
+  const sources = typeof flags.sources === "string" ? flags.sources.split(",").filter(Boolean) : undefined;
+  const pressureMode = flags.pressure === undefined ? undefined
+    : flags.pressure === "auto" || flags.pressure === "off" ? flags.pressure
+      : (() => { throw new Error("--pressure must be auto or off"); })();
+  const summary = await runSync({
+    dbPath,
+    sources,
+    scanLimit: numericFlag(flags, "limit"),
+    maxRecordBytes: numericFlag(flags, "max-record-bytes"),
+    budgets: {
+      sessions: numericFlag(flags, "session-budget"),
+      sourceBytes: numericFlag(flags, "source-byte-budget"),
+      wallMs: numericFlag(flags, "wall-ms"),
+      retries: numericFlag(flags, "retry-budget"),
+      attemptsPerSession: numericFlag(flags, "attempts-per-session"),
+      readBytesPerSecond: numericFlag(flags, "read-bytes-per-second"),
+      workerMs: numericFlag(flags, "worker-ms"),
+      workers: numericFlag(flags, "workers"),
+      freshSessions: numericFlag(flags, "fresh-session-budget"),
+      freshWindowMs: numericFlag(flags, "fresh-window-ms"),
+      chunkBytes: numericFlag(flags, "sync-chunk-bytes"),
+      maintenanceMs: numericFlag(flags, "maintenance-ms"),
+      ftsMergePages: numericFlag(flags, "fts-merge-pages"),
+    },
+    pressureMode,
+  });
+  if (isRobot || flags.json) {
+    console.log(JSON.stringify(summary, null, flags.json === true && !isRobot ? 2 : undefined));
+    return;
+  }
+  if (summary.skipped) {
+    console.log(
+      `Trajectories sync skipped: another writer holds the store (${describeLeaseHolder(summary.skipped.holder)}).`,
+    );
+    return;
+  }
+  console.log(`Trajectories sync ${summary.outcome}: ${summary.completed} completed, ${summary.pending.total} pending.`);
+  if (summary.outcome === "wall_budget_exceeded") {
+    console.log("Wall budget reached: the pass stopped there, and pending sessions stay queued for the next run.");
+  }
+  console.log(`Workers: ${summary.worker_processes} processes / ${summary.worker_attempts} attempts; source read: ${summary.work.source_bytes_read} bytes; elapsed: ${Math.round(summary.elapsed_ms)}ms.`);
+  // A pass that re-derived the index spent a one-shot inside it; saying so is
+  // what separates a 20-second upgrade from an unexplained stall.
+  if (summary.timing.derive_ms > 0) {
+    console.log(`Index re-derivation: ${Math.round(summary.timing.derive_ms)}ms (records_fts and titles_fts rebuilt from this store; no source was re-read).`);
+  }
+  if (summary.budgets.exhausted.length) console.log(`Budget boundary: ${summary.budgets.exhausted.join(", ")}.`);
+}
+
+async function handleQuery(args: string[], isRobot: boolean, programName: string): Promise<void> {
+  const { positionals, flags } = parseFlags(args);
+  const outputVersion = flags["output-version"] ?? "1";
+  const outputVersionError = flags["output-version"] !== undefined && !isRobot
+    ? "--output-version requires --robot."
+    : outputVersion !== "1" && outputVersion !== "2"
+      ? "--output-version requires a version: 1 or 2."
+      : null;
+  if (outputVersionError) {
+    if (isRobot) emitRobotError("INVALID_ARGUMENT", outputVersionError);
+    console.error(`Error: INVALID_ARGUMENT: ${outputVersionError}`);
+    process.exit(1);
+  }
+  applyEmbeddingProvider(flags, isRobot);
+  const queryText = positionals.join(" ").trim();
+
+  if (!queryText) {
+    if (isRobot) {
+      emitRobotError("MISSING_QUERY", "Please provide a search query.");
+    }
+    console.error("Error: Please provide a search query.");
+    console.error(`Example: ${programName} search "artifacts hosting subdomain"`);
+    process.exit(1);
+  }
+
+  const dbPath = typeof flags.db === "string" ? flags.db : "ledger.sqlite";
+
+  const limit = typeof flags.limit === "string" ? parseInt(flags.limit, 10) : 20;
+  const sourceFilter = typeof flags.source === "string" ? flags.source : undefined;
+
+  const isSemantic = flags.semantic === true;
+  const isHybrid = flags.hybrid === true;
+
+  const db = new TrajectoryReader(dbPath);
+  let result: QueryResult;
+  const parentTitles = new Map<string, string | null>();
+  let coverageSignal: ReturnType<TrajectoryReader["getSourceCoverageSummary"]>;
+  let discoverySignal: ReturnType<TrajectoryReader["getDiscoverySummary"]>;
+  try {
+    if (isSemantic) {
+      result = await db.querySemantic(queryText, { limit, source: sourceFilter });
+    } else if (isHybrid) {
+      result = await db.queryHybrid(queryText, { limit, source: sourceFilter });
+    } else {
+      result = db.query(queryText, { limit, source: sourceFilter });
+    }
+
+    for (const hit of result.hits) {
+      const parentId = hit.parent_session_id;
+      if (!parentId || parentTitles.has(parentId)) continue;
+      parentTitles.set(parentId, db.getSession(parentId)?.title ?? null);
+    }
+    // The durable coverage signal rides the v2 envelope (issue #37); read it
+    // while the reader handle is open — the connection is short-lived by design.
+    coverageSignal = db.getSourceCoverageSummary();
+    discoverySignal = db.getDiscoverySummary();
+  } finally { db.close(); }
+
+  if ((isRobot && outputVersion === "1") || (!isRobot && !flags.json)) {
+    if (result.meta.widened?.applied) {
+      console.error(`note: 0 phrase matches; widened to prefix terms (${result.meta.widened.widened_hits} hits)`);
+    } else if (isRobot && result.meta.widened?.skip_reason) {
+      console.error(`note: prefix widening not applied (${result.meta.widened.skip_reason})`);
+    }
+    if (result.meta.fallback_reason === FTS_SYNTAX_FALLBACK_REASON) {
+      console.error(`note: fts syntax fallback used (${result.meta.fallback_reason})`);
+    } else if (result.meta.fallback_reason) {
+      // A different reason means a different thing happened -- an unavailable
+      // embedding provider, not an unparsable FTS expression.
+      console.error(`note: answered lexically (${result.meta.fallback_reason})`);
+    }
+  }
+
+  if (isRobot) {
+    const robotHits = result.hits.map((hit) => ({
+      session_id: hit.session_id,
+      source: hit.source,
+      title: hit.title,
+      cwd: hit.cwd,
+      timestamp: hit.started_at,
+      score: typeof hit.rank === "number" ? hit.rank : 0,
+      snippet: hit.snippet.slice(0, 240),
+      parent_session_id: hit.parent_session_id ?? null,
+      parent_title: hit.parent_session_id
+        ? parentTitles.get(hit.parent_session_id) ?? null
+        : null,
+      agent_nickname: hit.agent_nickname ?? null,
+      thread_role: hit.thread_role ?? null,
+      ...(outputVersion === "2" ? { match_type: hit.match_type } : {}),
+    }));
+
+    // V1 preserves the pre-PR20 hit stream/array, including empty results.
+    // V2 adds the envelope and per-hit provenance for agents that opt in.
+    const searchMeta = outputVersion === "2" ? {
+      type: "search_meta",
+      ...result.meta,
+      total_hits: result.totalHits,
+      sessions_count: result.sessionsCount,
+      ...(coverageSignal ? { coverage: coverageSignal } : {}),
+      ...(discoverySignal ? { discovery: discoverySignal } : {}),
+    } : null;
+
+    if (flags.json) {
+      console.log(JSON.stringify(searchMeta ? { search_meta: searchMeta, hits: robotHits } : robotHits));
+    } else {
+      if (searchMeta) console.log(JSON.stringify(searchMeta));
+      for (const hit of robotHits) {
+        console.log(JSON.stringify(hit));
+      }
+    }
+    return;
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`Found ${result.totalHits} matching records across ${result.sessionsCount} sessions for: "${queryText}"\n`);
+
+  if (result.hits.length === 0) {
+    console.log("No matching records found.");
+    return;
+  }
+
+  const widenedSuffix = result.meta.widened?.applied ? " [widened]" : "";
+  for (let i = 0; i < result.hits.length; i++) {
+    const hit = result.hits[i];
+    const header = `[${i + 1}] [${hit.source}] Session: ${hit.session_id} (${hit.started_at ?? "unknown date"})${widenedSuffix}`;
+    console.log(header);
+    if (hit.title) {
+      console.log(`    Title: ${hit.title}`);
+    }
+    if (hit.cwd) {
+      console.log(`    Cwd:   ${hit.cwd}`);
+    }
+    if (hit.parent_session_id) {
+      const nick = hit.agent_nickname ? ` (${hit.agent_nickname})` : "";
+      console.log(`    Parent:${nick} ${hit.parent_session_id}`);
+    }
+    console.log(`    Role:  ${hit.record_type}`);
+    console.log(`    Match: ${hit.snippet}`);
+    console.log();
+  }
+}
+
+async function handleLast(args: string[], isRobot: boolean): Promise<void> {
+  const { flags } = parseFlags(args);
+  const dbPath = typeof flags.db === "string" ? flags.db : "ledger.sqlite";
+
+  const limit = typeof flags.limit === "string" ? parseInt(flags.limit, 10) : 20;
+  const sourceFilter = typeof flags.source === "string" ? flags.source : undefined;
+
+  const db = new TrajectoryReader(dbPath);
+  const sessions = db.getLastSessions({ limit, source: sourceFilter });
+  const formattedSessions = sessions.map((s) => {
+    const parent = s.parent_session_id ? db.getSession(s.parent_session_id) : null;
+    return {
+      session_id: s.id,
+      source: s.source,
+      title: s.title,
+      cwd: s.cwd,
+      started_at: s.started_at,
+      ended_at: s.ended_at,
+      updated_at: s.updated_at,
+      timestamp: s.updated_at ?? s.started_at,
+      record_count: s.record_count,
+      model: s.model,
+      parent_session_id: s.parent_session_id ?? null,
+      parent_title: parent?.title ?? null,
+      parent_tool_use_id: s.parent_tool_use_id ?? null,
+      agent_nickname: s.agent_nickname ?? null,
+      thread_role: s.thread_role ?? null,
+    };
+  });
+  db.close();
+
+  if (isRobot) {
+    if (flags.json) {
+      console.log(JSON.stringify(formattedSessions));
+    } else {
+      for (const s of formattedSessions) {
+        console.log(JSON.stringify(s));
+      }
+    }
+    return;
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(formattedSessions, null, 2));
+    return;
+  }
+
+  console.log(`Recent sessions (limit ${limit}${sourceFilter ? `, source: ${sourceFilter}` : ""}):\n`);
+  if (formattedSessions.length === 0) {
+    console.log("No sessions found.");
+    return;
+  }
+
+  for (let i = 0; i < formattedSessions.length; i++) {
+    const s = formattedSessions[i];
+    console.log(`[${i + 1}] [${s.source}] Session: ${s.session_id} (${s.updated_at || s.started_at || "unknown date"})`);
+    if (s.title) {
+      console.log(`    Title:   ${s.title.replace(/\n/g, " ").slice(0, 100)}`);
+    }
+    if (s.cwd) {
+      console.log(`    Cwd:     ${s.cwd}`);
+    }
+    if (s.parent_session_id) {
+      const label = s.agent_nickname ? `${s.agent_nickname} → ` : "";
+      const parentLabel = s.parent_title
+        ? `${s.parent_title.replace(/\n/g, " ").slice(0, 80)} (${s.parent_session_id})`
+        : s.parent_session_id;
+      console.log(`    Parent:  ${label}${parentLabel}`);
+    }
+    console.log(`    Records: ${s.record_count}`);
+    console.log();
+  }
+}
+
+/**
+ * `trajectories delete <session-id>` — the store's one deletion verb, and the only
+ * caller of the store's tombstone API.
+ *
+ * The verb names a session, records why, and either closes the session to
+ * serving and admission (the default) or removes its records as well (`--hard`).
+ * It takes the writer lease like every other verb that writes: a deletion
+ * racing a sync pass would otherwise interleave with the pass that is
+ * re-admitting the same session, and the lease is this repository's answer to
+ * that (writer-lease.ts). `--list` reports the deletions the store records,
+ * which is the audit readout — the reason a deletion stores is worth nothing if
+ * nothing can read it back.
+ *
+ * The policy half of deletion is deliberately absent: who may delete, how long
+ * a record may be kept, and whether a deletion must be explained are open
+ * questions (docs/research/2026-09-16-c7-tombstones.md). What the verb fixes is
+ * what the store *does* once asked — and that only a user asking can make it do
+ * it.
+ */
+async function handleDelete(args: string[], isRobot: boolean): Promise<void> {
+  const { positionals, flags } = parseFlags(args);
+  const dbPath = typeof flags.db === "string" ? flags.db : "ledger.sqlite";
+  const listAudit = flags.list === true;
+  const sessionId = positionals[0];
+  const reason = typeof flags.reason === "string" ? flags.reason.trim() : "";
+
+  const usageError =
+    listAudit && sessionId !== undefined
+      ? "--list takes no session id."
+      : listAudit && flags.hard === true
+        ? "--list deletes nothing, so --hard has no meaning with it."
+          : !listAudit && !sessionId
+          ? "Please provide a session id to delete."
+          : !listAudit && !reason
+            ? "Please say why: --reason <text>. The reason is what the stored deletion records."
+            : null;
+  if (usageError) {
+    if (isRobot) emitRobotError("INVALID_ARGUMENT", usageError);
+    console.error(`Error: INVALID_ARGUMENT: ${usageError}`);
+    process.exit(1);
+  }
+
+  // A deletion needs a store to act on, and this verb must not create or adopt
+  // one: a writer open initializes an empty or foreign file — that is what
+  // `sync` and `build` are for — and conjuring a database to delete from is not a
+  // deletion. Two guards, because they answer different questions: the read gate
+  // classifies the store and refuses it with the read verbs' own codes and
+  // wording, and the writer open below is told not to initialize one, which is
+  // the invariant even if the file changes between the two statements.
+  if (!isMemoryStorePath(dbPath)) openReadOnlyStore(dbPath).close();
+
+  // The lease attaches before any store handle exists, as `build`'s does: a
+  // refused deletion must leave the database exactly as it found it.
+  const lease = isMemoryStorePath(dbPath)
+    ? null
+    : acquireWriterLease(dbPath, { waitMs: DEFAULT_WRITER_LEASE_WAIT_MS, holder: "delete" });
+  try {
+    let db: TrajectoryDb;
+    try {
+      db = new TrajectoryDb(dbPath, { requireExisting: true });
+    } catch (error) {
+      // The store vanished (or was replaced by something that is not one)
+      // between the classification above and this open. The refusal is the
+      // classification's own wording, and nothing has been created.
+      if (error instanceof StoreNotInitializedError) {
+        throw new ReaderError(
+          "STORE_NOT_INITIALIZED",
+          `${error.message} There is nothing to delete; run \`trajectories sync\` or \`trajectories build\` first.`,
+        );
+      }
+      throw error;
+    }
+    try {
+      if (listAudit) {
+        const tombstones = db.listTombstones();
+        if (isRobot || flags.json) {
+          const rows = tombstones.map((row) => ({ type: "tombstone", ...row }));
+          if (flags.json === true && !isRobot) {
+            console.log(JSON.stringify(rows, null, 2));
+          } else {
+            // Robot mode is JSONL: one row per line, and an empty stream when the
+            // store records no deletion — which is the honest answer, not an error.
+            for (const row of rows) console.log(JSON.stringify(row));
+          }
+          return;
+        }
+        if (tombstones.length === 0) {
+          console.log("No deletions recorded in this store.");
+          return;
+        }
+        console.log(`${tombstones.length} deletion${tombstones.length === 1 ? "" : "s"} recorded:\n`);
+        for (const row of tombstones) {
+          console.log(`  ${row.session_id}  [${row.mode}]  ${row.deleted_at}`);
+          console.log(`    ${row.reason}`);
+        }
+        return;
+      }
+
+      // A refusal (no such session) propagates to the CLI's typed-error handler,
+      // so the lease and the store handle are released before the process exits.
+      const outcome = db.tombstoneSession(sessionId, { reason, hard: flags.hard === true });
+      const { tombstone, created, escalated, recordsRemoved } = outcome;
+      if (isRobot || flags.json) {
+        console.log(
+          JSON.stringify(
+            {
+              type: "tombstone",
+              session_id: tombstone.session_id,
+              source: tombstone.source,
+              native_id: tombstone.native_id,
+              source_path: tombstone.source_path,
+              mode: tombstone.mode,
+              reason: tombstone.reason,
+              record_count: tombstone.record_count,
+              records_removed: recordsRemoved,
+              deleted_at: tombstone.deleted_at,
+              created,
+              escalated,
+            },
+            null,
+            flags.json === true && !isRobot ? 2 : undefined,
+          ),
+        );
+        return;
+      }
+
+      const headline = !created && !escalated
+        ? `Already deleted: ${tombstone.session_id} (${tombstone.mode})`
+        : tombstone.mode === "hard"
+          ? `Deleted ${tombstone.session_id} (hard: ${recordsRemoved} records removed from this store)`
+          : `Deleted ${tombstone.session_id} (${tombstone.record_count} records stay in the store, withheld from search and reads)`;
+      console.log(headline);
+      console.log(`  reason:     ${tombstone.reason}`);
+      console.log(`  deleted_at: ${tombstone.deleted_at}`);
+      if (!created && !escalated) {
+        console.log("  Nothing changed; use --hard to remove the records as well.");
+      } else if (escalated) {
+        console.log("  The same deletion, carried through to the records: the reason and timestamp above are the ones first given.");
+      } else if (tombstone.mode === "hard") {
+        console.log("  The tombstone is all that is left of it; no later scan can re-import this session.");
+      } else {
+        console.log("  The records stay as evidence and no scan can re-import this session; --hard removes them.");
+      }
+    } finally {
+      db.close();
+    }
+  } finally {
+    lease?.close();
+  }
+}
+
+async function handleStatus(args: string[], isRobot: boolean): Promise<void> {
+  const { flags } = parseFlags(args);
+  const dbPath = typeof flags.db === "string" ? flags.db : "ledger.sqlite";
+
+  let status;
+  try {
+    status = readStoreStatus(dbPath);
+  } catch (err: unknown) {
+    if (err instanceof StoreStatusError) {
+      if (isRobot) {
+        emitRobotError(err.code, err.message);
+      }
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  const payload = {
+    path: status.path,
+    initialized: status.initialized,
+    schema_version: status.schemaVersion,
+    supported_schema_version: SCHEMA_VERSION,
+    sessions: status.sessions,
+    records: status.records,
+    echo_filtered: status.echoFiltered,
+    tombstones: status.tombstones,
+    tombstoned_records: status.tombstonedRecords,
+    diagnostics: status.diagnostics,
+    coverage: status.coverage,
+    ...(status.discovery ? { discovery: status.discovery } : {}),
+  };
+
+  if (isRobot || flags.json) {
+    console.log(JSON.stringify(payload, null, flags.json === true && !isRobot ? 2 : undefined));
+    return;
+  }
+
+  console.log(`Trajectories store: ${status.path}`);
+  if (!status.initialized) {
+    console.log("Initialized: no (no store found at this path)");
+    return;
+  }
+  console.log(`Initialized: yes`);
+  console.log(`Schema version: ${status.schemaVersion} (supported: ${SCHEMA_VERSION})`);
+  console.log(`Sessions: ${status.sessions}`);
+  console.log(`Records: ${status.records}`);
+  console.log(
+    status.echoFiltered === null
+      ? "Echo filtered: unknown (not derived under this build's rules yet; the next writer pass derives it)"
+      : `Echo filtered: ${status.echoFiltered} records (agent lookups of this store; never searchable)`,
+  );
+  // Holdings are reported as they are, tombstones included (the counts above
+  // name what the store keeps); this line says how much of that is withheld.
+  console.log(
+    status.tombstones
+      ? `Tombstones: ${status.tombstones} session${status.tombstones === 1 ? "" : "s"} deleted by the user; ` +
+        `${status.tombstonedRecords} of the records above are held back from search and reads`
+      : "Tombstones: none (no session has been deleted by the user)",
+  );
+  const diagnostics = status.diagnostics;
+  if (!diagnostics) {
+    console.log("Diagnostics: unknown (store predates diagnostics schema)");
+  } else if (!diagnostics.byCode.length) {
+    console.log("Diagnostics: none");
+  } else {
+    console.log(
+      `Diagnostics: ${diagnostics.totalOccurrences} occurrences in ${diagnostics.totalSessions} sessions`,
+    );
+    for (const { code, sessions, occurrences } of diagnostics.byCode.slice(0, 5)) {
+      console.log(`  ${code}: ${occurrences} occurrences in ${sessions} sessions`);
+    }
+    if (diagnostics.byCode.length > 5) {
+      console.log(`  ... ${diagnostics.byCode.length - 5} more codes (see --robot)`);
+    }
+  }
+  if (status.discovery) {
+    const { pending_sources, unknown_sources, exhausted_sources } = status.discovery;
+    console.log(`Discovery: ${exhausted_sources} exhausted, ${pending_sources} pending, ${unknown_sources} unknown (observed sweeps, not archive completeness)`);
+  }
+  const coverage = status.coverage;
+  if (!coverage) {
+    console.log("Coverage: unknown (store predates source coverage schema)");
+  } else if (!coverage.length) {
+    console.log("Coverage: none (no pass has scanned this store)");
+  } else {
+    const listable = coverage.filter((row) => row.status === "listable").length;
+    const missing = coverage.filter((row) => row.status === "missing_root").length;
+    console.log(
+      `Coverage: ${listable}/${coverage.length} sources listable${missing ? `, ${missing} missing` : ""}`,
+    );
+    // An uninstalled source is not news, the same rule the scan notes use — it
+    // is counted above and stays quiet here. Everything else that could not be
+    // listed is an anomaly and reads exactly as the scan would have said it.
+    for (const row of coverage) {
+      if (row.status === "listable" || row.status === "missing_root") continue;
+      console.log(`  ${formatScanOutcome(row)}`);
+    }
+  }
+}
+
+async function handleWatch(args: string[], isRobot: boolean): Promise<void> {
+  const { flags } = parseFlags(args);
+  const embed = Boolean(flags.embed);
+  if (embed) applyEmbeddingProvider(flags, isRobot);
+  const dbPath = typeof flags.db === "string" ? flags.db : "ledger.sqlite";
+  const sources = typeof flags.sources === "string" ? flags.sources.split(",") : undefined;
+  const debounceMs = typeof flags.debounce === "string" ? parseInt(flags.debounce, 10) : 2000;
+  const limit = typeof flags.limit === "string" ? parseInt(flags.limit, 10) : undefined;
+  const reconcileMs =
+    typeof flags["reconcile-ms"] === "string"
+      ? parseInt(flags["reconcile-ms"], 10)
+      : 60000;
+  const importBudget =
+    typeof flags["import-budget"] === "string"
+      ? parseInt(flags["import-budget"], 10)
+      : 25;
+  const maxRecordBytes = flags["max-record-bytes"] === undefined
+    ? undefined
+    : typeof flags["max-record-bytes"] === "string"
+      ? Number(flags["max-record-bytes"])
+      : NaN;
+  const verbose = Boolean(flags.verbose);
+
+  const logProse = isRobot ? console.error : console.log;
+  logProse("Watching local agent session stores...");
+  logProse(`  Database : ${dbPath}`);
+  logProse(`  Sources  : ${sources ? sources.join(", ") : "all detected"}`);
+  logProse(`  Debounce : ${debounceMs}ms`);
+  logProse(`  Embed    : ${embed ? "on" : "off (lexical)"}`);
+  logProse(`  Reconcile: ${reconcileMs}ms`);
+  logProse(`  Budget   : ${importBudget} sessions/source/tick`);
+
+  const watcher = new LedgerWatcher({
+    dbPath,
+    sources,
+    debounceMs,
+    limit,
+    verbose,
+    embed,
+    reconcileMs,
+    importBudget,
+    maxRecordBytes,
+    onBatch: (summary) => {
+      if (isRobot) {
+        console.log(
+          JSON.stringify({
+            type: "watch_status",
+            source: summary.source,
+            imported: summary.imported,
+            appended: summary.appended,
+            deduped: summary.deduped,
+            skipped: summary.skipped,
+            scanned: summary.scanned,
+          }),
+        );
+      } else {
+        console.log(
+          `[watch] ${summary.source}: ${summary.imported} imported, ${summary.appended} appended, ${summary.deduped} deduped, ${summary.skipped} skipped (from ${summary.scanned} scanned)`,
+        );
+      }
+    },
+  });
+
+  const { promise: exitPromise, resolve: exitResolve } = Promise.withResolvers<void>();
+  const shutdown = () => {
+    void watcher.stop().then(exitResolve, () => {
+      console.error("[ledger] watcher shutdown failed.");
+      process.exitCode = 1;
+      exitResolve();
+    });
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  try {
+    await watcher.start();
+    await exitPromise;
+  } finally {
+    await watcher.stop();
+    process.off("SIGINT", shutdown);
+    process.off("SIGTERM", shutdown);
+  }
+}
+
+async function handleModels(args: string[], isRobot: boolean): Promise<void> {
+  const { positionals } = parseFlags(args);
+  const subCmd = positionals[0];
+  if (subCmd === "pull") {
+    const { modelPath, vocabPath } = await pullModel({ verbose: !isRobot });
+    if (isRobot) {
+      console.log(
+        JSON.stringify({
+          type: "models_pull",
+          model: DEFAULT_MODEL_NAME,
+          modelPath,
+          vocabPath,
+          status: "ok",
+        }),
+      );
+    } else {
+      console.log(`Model ${DEFAULT_MODEL_NAME} pulled successfully to ${modelPath}`);
+    }
+    return;
+  }
+
+  if (isRobot) {
+    emitRobotError("UNKNOWN_COMMAND", `Unknown models subcommand: ${subCmd}`);
+  }
+  console.error(`Unknown models subcommand: ${subCmd}\nUsage: trajectories models pull`);
+  process.exit(1);
+}