trajectories 0.0.0 → 0.1.2

package/legacy/src/watch.ts

@@ -0,0 +1,673 @@
+import {
+  type FSWatcher,
+  existsSync,
+  readdirSync,
+  statSync,
+  watch,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { TrajectoryDb } from "./db.js";
+import { ingestDiscoveredSession, sessionNeedsIngest } from "./ingest.js";
+import { scanSessions } from "./scanner.js";
+import { cursorRoots } from "./native/cursor.js";
+import { grokRoots } from "./native/grok.js";
+import { kimiRoots } from "./native/kimi.js";
+import { openCodeRoots } from "./native/opencode.js";
+import {
+  acquireWriterLease,
+  DEFAULT_WRITER_LEASE_WAIT_MS,
+  describeLeaseHolder,
+  isMemoryStorePath,
+  WriterLeaseBusyError,
+  type WriterLease,
+} from "./writer-lease.js";
+
+const DEFAULT_SOURCES = [
+  "claude-code",
+  "codex",
+  "pi",
+  "omp",
+  "hermes",
+  "letta-code",
+  "openclaw",
+  "droid",
+  "deepagents",
+  "openhands",
+  "cursor",
+  "opencode",
+  "grok",
+  "kimi",
+  "gemini-cli",
+  "copilot-cli",
+];
+
+interface WatchRoot { path: string; recursive: boolean }
+interface WatchRegistration {
+  handle: FSWatcher;
+  recursive: boolean;
+  fallbackTree: boolean;
+  sources: Set<string>;
+  /** Child basenames that should wake this source on a parent-sentinel watch. */
+  expectedChildren: Map<string, Set<string>>;
+}
+const tree = (path: string): WatchRoot => ({ path, recursive: true });
+const shallow = (path: string): WatchRoot => ({ path, recursive: false });
+
+// These inputs mirror trajectory 0.3.0's non-exported OMP listing resolver.
+function ompSessionsPath(): string {
+  const env = process.env;
+  const value = (env.OMP_PROFILE !== undefined ? env.OMP_PROFILE : env.PI_PROFILE)?.trim();
+  const profile = value && value !== "default" && value !== "." && value !== ".." && !value.endsWith(".") &&
+    /^[a-z0-9][a-z0-9._-]{0,63}$/.test(value) && !/^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])(?:\..*)?$/i.test(value)
+    ? value : undefined;
+  const config = join(homedir(), env.PI_CONFIG_DIR || ".omp", ...(profile ? ["profiles", profile] : []));
+  const override = profile ? undefined : env.PI_CODING_AGENT_DIR?.trim() || undefined;
+  if (!override && (process.platform === "linux" || process.platform === "darwin") && env.XDG_DATA_HOME?.trim()) {
+    const data = join(env.XDG_DATA_HOME.trim(), "omp", ...(profile ? ["profiles", profile] : []));
+    if (existsSync(data)) return join(data, "sessions");
+  }
+  return join(override ?? join(config, "agent"), "sessions");
+}
+
+function openClawStatePath(): string {
+  const override = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+  if (override) return override;
+  const current = join(homedir(), ".openclaw");
+  return existsSync(current) ? current : join(homedir(), ".clawdbot");
+}
+
+const DEFAULT_SOURCE_ROOTS: Record<string, () => WatchRoot[]> = {
+  "claude-code": () => [tree(join(homedir(), ".claude", "projects"))],
+  codex: () => [tree(join(homedir(), ".codex", "sessions"))],
+  pi: () => [tree(join(process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent"), "sessions"))],
+  omp: () => [tree(ompSessionsPath())],
+  hermes: () => [shallow(join(homedir(), ".hermes"))],
+  "letta-code": () => [tree(join(homedir(), ".letta", "transcripts"))],
+  openclaw: () => [tree(join(openClawStatePath(), "agents"))],
+  droid: () => [tree(join(homedir(), ".factory", "sessions"))],
+  deepagents: () => [shallow(join(homedir(), ".deepagents"))],
+  openhands: () => [tree(join(homedir(), ".openhands", "sessions"))],
+  // Share source-specific roots with native discovery.
+  cursor: () => cursorRoots().map(tree),
+  opencode: () => openCodeRoots().map(tree),
+  grok: () => grokRoots().map(tree),
+  kimi: () => kimiRoots().map(tree),
+  cline: () => [tree(process.env.CLINE_SESSION_DATA_DIR?.trim() || join(homedir(), ".cline", "data", "sessions"))],
+  fx: () => [tree(join(homedir(), ".fx", "sessions"))],
+  "gemini-cli": () => [tree(join(homedir(), ".gemini", "sessions"))],
+  "copilot-cli": () => [tree(join(homedir(), ".copilot", "session-state")), tree(join(homedir(), ".copilot", "history-session-state"))],
+};
+
+function recursiveUnsupported(error: unknown): boolean {
+  return ["ERR_FEATURE_UNAVAILABLE_ON_PLATFORM", "ENOSYS", "ENOTSUP", "EOPNOTSUPP"]
+    .includes((error as NodeJS.ErrnoException)?.code ?? "");
+}
+
+function cloneExpectedChildren(
+  existing?: Map<string, Set<string>>,
+): Map<string, Set<string>> {
+  const cloned = new Map<string, Set<string>>();
+  if (!existing) return cloned;
+  for (const [source, names] of existing) {
+    cloned.set(source, new Set(names));
+  }
+  return cloned;
+}
+
+function rememberExpectedChild(
+  expectedChildren: Map<string, Set<string>>,
+  source: string,
+  expectedChild?: string,
+): void {
+  if (expectedChild === undefined) {
+    expectedChildren.delete(source);
+    return;
+  }
+  const names = expectedChildren.get(source);
+  if (names) names.add(expectedChild);
+  else expectedChildren.set(source, new Set([expectedChild]));
+}
+
+function sentinelAllows(
+  registration: WatchRegistration,
+  source: string,
+  filename: string | Buffer | null | undefined,
+): boolean {
+  const expected = registration.expectedChildren.get(source);
+  if (!expected || expected.size === 0) return true;
+  if (filename == null) return true;
+  const name = basename(typeof filename === "string" ? filename : filename.toString());
+  return name.length === 0 || expected.has(name);
+}
+
+export interface WatcherEvent {
+  source: string;
+  sessionId?: string;
+  kind: "imported" | "appended" | "deduped" | "skipped" | "deferred" | "tombstoned";
+  sessionsProcessed: number;
+}
+
+export interface WatcherBatchSummary {
+  source: string;
+  imported: number;
+  appended: number;
+  deduped: number;
+  skipped: number;
+  scanned: number;
+}
+
+export interface LedgerWatcherOptions {
+  dbPath: string;
+  sources?: string[];
+  roots?: Record<string, string>;
+  limit?: number;
+  onEvent?: (event: WatcherEvent) => void;
+  onBatch?: (summary: WatcherBatchSummary) => void;
+  debounceMs?: number;
+  verbose?: boolean;
+  /** When false (default), ingest is lexical-only so the watcher cannot stall on embeddings. */
+  embed?: boolean;
+  /** Periodic catch-up. `0` disables start+interval reconcile (tests). */
+  reconcileMs?: number;
+  /** Max sessions per source per tick; shared native stores also rotate prior attempts. */
+  importBudget?: number;
+  /** JSONL record or assembled native-session ceiling; defaults to 64 MiB. */
+  maxRecordBytes?: number;
+}
+
+export class LedgerWatcher {
+  readonly dbPath: string;
+  readonly sources: string[];
+  readonly roots: Record<string, string>;
+  readonly limit?: number;
+  readonly debounceMs: number;
+  readonly verbose: boolean;
+  readonly embed: boolean;
+  readonly reconcileMs: number;
+  readonly importBudget: number;
+  readonly maxRecordBytes?: number;
+
+  private onEvent?: (event: WatcherEvent) => void;
+  private onBatch?: (summary: WatcherBatchSummary) => void;
+
+  private db?: TrajectoryDb;
+  /** Held only while at least one drain is writing; shared by concurrent drains. */
+  private writerLease?: WriterLease;
+  private leaseDrains = 0;
+  private watchers = new Map<string, WatchRegistration>();
+  private recursiveWatchers = new Map<string, WatchRegistration>();
+  private recursiveWatchSupported = true;
+  private debounceTimers = new Map<string, Timer>();
+  private sourceTasks = new Map<string, Promise<void>>();
+  private pendingAfterProcessing = new Set<string>();
+  private isStopped = false;
+  private batchCount = 0;
+  private reconcileTimer?: Timer;
+  private startTask?: Promise<void>;
+  private reconcileTask?: Promise<void>;
+  private stopTask?: Promise<void>;
+
+  constructor(options: LedgerWatcherOptions) {
+    this.dbPath = options.dbPath;
+    this.sources = options.sources && options.sources.length > 0
+      ? options.sources
+      : [...DEFAULT_SOURCES];
+    this.roots = options.roots ?? {};
+    this.limit = options.limit;
+    this.debounceMs = options.debounceMs ?? 2000;
+    this.reconcileMs = options.reconcileMs ?? 60_000;
+    this.verbose = Boolean(options.verbose);
+    this.embed = Boolean(options.embed);
+    this.importBudget = options.importBudget ?? 25;
+    this.maxRecordBytes = options.maxRecordBytes;
+    if (this.maxRecordBytes !== undefined &&
+      (!Number.isSafeInteger(this.maxRecordBytes) || this.maxRecordBytes <= 0)) {
+      throw new Error("maxRecordBytes must be a positive safe integer");
+    }
+    this.onEvent = options.onEvent;
+    this.onBatch = options.onBatch;
+  }
+
+  start(): Promise<void> {
+    if (this.isStopped) {
+      return Promise.reject(new Error("Cannot restart a stopped LedgerWatcher."));
+    }
+    this.startTask ??= this.startWatching();
+    return this.startTask;
+  }
+
+  private async startWatching(): Promise<void> {
+    // The store is opened lazily, inside the first drain that scans: a watcher
+    // with nothing to scan must not create, migrate, or touch it, and a
+    // lease-skipped drain never reaches the store at all. A drain that does scan
+    // is not a pure read — it records that source's coverage — so it opens (and
+    // migrates) the store exactly as a foreground pass does.
+    for (const source of this.sources) {
+      this.attachSourceRoots(source);
+    }
+
+    // Reconcile existing history before reporting startup complete. Filesystem
+    // events only cover changes after watchers attach; without this pass, a
+    // freshly installed daemon can run indefinitely with an empty database.
+    if (this.reconcileMs > 0) {
+      await this.runReconcileTick();
+    }
+
+    // Filesystem events are best-effort on every supported platform. Keep a
+    // periodic reconciliation floor so directories created later, missed events,
+    // and history written while the service was down eventually converge.
+    if (!this.isStopped && this.reconcileMs > 0) {
+      this.reconcileTimer = setInterval(() => {
+        void this.runReconcileTick().catch(() => {
+          console.error("[ledger] reconciliation failed; retrying on the next tick.");
+        });
+      }, this.reconcileMs);
+    }
+  }
+
+  stop(): Promise<void> {
+    if (this.stopTask) return this.stopTask;
+    this.isStopped = true;
+
+    if (this.reconcileTimer) {
+      clearInterval(this.reconcileTimer);
+      this.reconcileTimer = undefined;
+    }
+
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+
+    for (const watcher of this.watchers.values()) {
+      try {
+        watcher.handle.close();
+      } catch {
+        // ignore
+      }
+    }
+    this.watchers.clear();
+    this.recursiveWatchers.clear();
+    this.pendingAfterProcessing.clear();
+
+    // Stop all producers before taking the drain snapshot. Existing ingest may
+    // still write records, vectors, or cursors after its current await resumes.
+    const pending = [this.startTask, this.reconcileTask, ...this.sourceTasks.values()]
+      .filter((task): task is Promise<void> => task !== undefined);
+    this.stopTask = Promise.allSettled(pending).then(() => {
+      try {
+        this.db?.close();
+      } finally {
+        this.db = undefined;
+        // Every drain has settled, so any retained lease is leaked by
+        // definition; it must not outlive the watcher.
+        this.releaseLeaseIfIdle();
+      }
+    });
+    return this.stopTask;
+  }
+
+  /** The watcher's store, opened on first use inside a drain that writes. */
+  private store(): TrajectoryDb {
+    return this.db ??= new TrajectoryDb(this.dbPath);
+  }
+
+  getBatchCount(): number {
+    return this.batchCount;
+  }
+
+  getWatchedPaths(): string[] {
+    return Array.from(this.watchers.keys());
+  }
+
+  private resolveSourceRoots(source: string): WatchRoot[] {
+    const customRoot = this.roots[source];
+    if (customRoot) {
+      if (source === "pi" || source === "omp") return [tree(join(customRoot, "sessions"))];
+      if (source === "openclaw") return [tree(join(customRoot, "agents"))];
+      if (source === "hermes" || source === "deepagents") return [shallow(customRoot.endsWith(".db") ? dirname(customRoot) : customRoot)];
+      if ((source === "cursor" || source === "opencode") && /\.(?:db|vscdb|sqlite|sqlite3)$/i.test(customRoot)) {
+        return [customRoot, `${customRoot}-wal`, `${customRoot}-journal`].map(shallow);
+      }
+      return [tree(customRoot)];
+    }
+    return DEFAULT_SOURCE_ROOTS[source]?.() ?? [];
+  }
+
+  private attachSourceRoots(source: string): void {
+    if (this.isStopped) return;
+    for (const root of this.resolveSourceRoots(source)) {
+      const path = resolve(root.path);
+      // A shallow nearest-parent sentinel observes creation without traversing
+      // agent plugins, worktrees, caches, or configuration directories.
+      let parent = dirname(path);
+      while (!existsSync(parent) && dirname(parent) !== parent) parent = dirname(parent);
+      this.attachWatcher(parent, source, false, false, basename(path));
+      if (root.recursive) this.watchDirectoryTree(path, source);
+      else this.attachWatcher(path, source, false);
+    }
+  }
+
+  private watchDirectoryTree(targetPath: string, source: string): void {
+    if (this.isStopped || !existsSync(targetPath)) return;
+
+    try {
+      const stat = statSync(targetPath);
+      if (!stat.isDirectory()) {
+        this.attachWatcher(targetPath, source, false);
+        return;
+      }
+      if (this.recursiveWatchSupported) {
+        const result = this.attachWatcher(targetPath, source, true);
+        if (result !== "unsupported") return;
+        this.recursiveWatchSupported = false;
+      }
+      if (this.attachWatcher(targetPath, source, false, true) !== "attached") return;
+      for (const entry of readdirSync(targetPath, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          this.watchDirectoryTree(join(targetPath, entry.name), source);
+        }
+      }
+    } catch {
+      // ignore read permission errors
+    }
+  }
+
+  private attachWatcher(
+    targetPath: string,
+    source: string,
+    recursive: boolean,
+    fallbackTree = false,
+    expectedChild?: string,
+  ): "attached" | "unsupported" | "failed" {
+    if (this.isStopped || !existsSync(targetPath)) return "failed";
+    const existing = this.watchers.get(targetPath);
+    if (existing && (existing.recursive || !recursive)) {
+      existing.sources.add(source);
+      existing.fallbackTree ||= fallbackTree;
+      rememberExpectedChild(existing.expectedChildren, source, expectedChild);
+      return "attached";
+    }
+    for (const [path, registration] of this.recursiveWatchers) {
+      if (targetPath.startsWith(path + sep)) {
+        registration.sources.add(source);
+        return "attached";
+      }
+    }
+    try {
+      const sources = new Set(existing?.sources ?? []);
+      sources.add(source);
+      const expectedChildren = cloneExpectedChildren(existing?.expectedChildren);
+      rememberExpectedChild(expectedChildren, source, expectedChild);
+      const registration: WatchRegistration = {
+        handle: watch(targetPath, { recursive }, (_eventType, filename) => {
+          if (this.isStopped) return;
+          for (const subscriber of sources) {
+            if (!recursive) {
+              if (registration.fallbackTree && filename) {
+                const fullPath = join(targetPath, filename);
+                try {
+                  if (statSync(fullPath).isDirectory()) this.watchDirectoryTree(fullPath, subscriber);
+                } catch { /* deleted path or unreadable child */ }
+              } else {
+                if (!sentinelAllows(registration, subscriber, filename)) continue;
+                this.attachSourceRoots(subscriber);
+              }
+            }
+            this.triggerSourceDebounce(subscriber);
+          }
+        }),
+        recursive, fallbackTree, sources, expectedChildren,
+      };
+      existing?.handle.close();
+      this.watchers.set(targetPath, registration);
+      this.recursiveWatchers.delete(targetPath);
+      if (recursive) {
+        this.recursiveWatchers.set(targetPath, registration);
+        for (const [path, covered] of this.watchers) {
+          if (path.startsWith(targetPath + sep)) {
+            for (const subscriber of covered.sources) sources.add(subscriber);
+            covered.handle.close();
+            this.watchers.delete(path);
+            this.recursiveWatchers.delete(path);
+          }
+        }
+      }
+      registration.handle.on("error", () => {
+        registration.handle.close();
+        if (this.watchers.get(targetPath) === registration) {
+          this.watchers.delete(targetPath);
+          this.recursiveWatchers.delete(targetPath);
+        }
+      });
+      return "attached";
+    } catch (error) {
+      return recursive && recursiveUnsupported(error) ? "unsupported" : "failed";
+    }
+  }
+
+  private triggerSourceDebounce(source: string): void {
+    if (this.isStopped) return;
+
+    const existingTimer = this.debounceTimers.get(source);
+    clearTimeout(existingTimer);
+
+    const timer = setTimeout(() => {
+      this.debounceTimers.delete(source);
+      this.withWriterLease(() => this.executeSourceBatch(source)).catch(() => {
+        console.error("[ledger] source batch failed:", JSON.stringify({ source }));
+      });
+    }, this.debounceMs);
+
+    this.debounceTimers.set(source, timer);
+  }
+
+  private async runReconcileTick(): Promise<void> {
+    if (this.isStopped) return;
+    if (this.reconcileTask) return this.reconcileTask;
+    const task = this.withWriterLease(() => this.reconcileAllSources());
+    this.reconcileTask = task;
+    try {
+      await task;
+    } finally {
+      this.reconcileTask = undefined;
+    }
+  }
+
+  /**
+   * Watch holds the writer lease only while a drain writes: one reconcile tick
+   * or one debounced batch, never for the watcher lifetime. Concurrent drains
+   * share one lease (the watcher is a single writer) and it is released by
+   * whichever of them finishes last, so neither can leave the other writing
+   * unleased. A busy store means a foreground verb owns it, so the drain is
+   * skipped with a note and retried on the next tick instead of crashing the
+   * watcher or starving the verb.
+   */
+  private async withWriterLease(drain: () => Promise<void>): Promise<void> {
+    if (isMemoryStorePath(this.dbPath)) return drain();
+    if (this.writerLease) {
+      // Joining is atomic: acquisition is synchronous, so no await intervenes.
+      this.leaseDrains++;
+      try {
+        await drain();
+      } finally {
+        this.leaseDrains--;
+        this.releaseLeaseIfIdle();
+      }
+      return;
+    }
+    let lease: WriterLease;
+    try {
+      lease = acquireWriterLease(this.dbPath, { waitMs: DEFAULT_WRITER_LEASE_WAIT_MS, holder: "watch" });
+    } catch (error) {
+      if (!(error instanceof WriterLeaseBusyError)) throw error;
+      console.error(`[ledger] watch skipped: another writer holds the store (${describeLeaseHolder(error.holder)})`);
+      return;
+    }
+    this.writerLease = lease;
+    this.leaseDrains = 1;
+    try {
+      this.deriveIndexIfPending();
+      await drain();
+    } finally {
+      this.leaseDrains--;
+      this.releaseLeaseIfIdle();
+    }
+  }
+
+  /**
+   * A drain holds the writer lease, so a pending index re-derivation (the
+   * derive-rule counter's one-shot, C2) is the drain's work, exactly as it is a
+   * sync pass's — taken here, before the batch, so the rest of the drain reads
+   * the index it just derived. The watcher is a daemon with no summary to carry
+   * the wall time, so it reports it on stderr; a store with nothing pending
+   * pays one `schema_meta` probe.
+   */
+  private deriveIndexIfPending(): void {
+    const store = this.store();
+    const started = performance.now();
+    if (!store.reindexFts()) return;
+    console.error(
+      `[ledger] index re-derivation: ${Math.round(performance.now() - started)}ms (records_fts and titles_fts rebuilt from this store)`,
+    );
+  }
+
+  /** One release path for every drain: the last one out closes the lease. */
+  private releaseLeaseIfIdle(): void {
+    if (this.leaseDrains > 0) return;
+    const lease = this.writerLease;
+    this.writerLease = undefined;
+    lease?.close();
+  }
+
+  private async reconcileAllSources(): Promise<void> {
+    if (this.isStopped) return;
+    for (const source of this.sources) {
+      if (this.isStopped) break;
+      this.attachSourceRoots(source);
+      try {
+        await this.executeSourceBatch(source, false);
+      } catch {
+        console.error("[ledger] reconciliation failed:", JSON.stringify({ source }));
+      }
+    }
+  }
+
+  private executeSourceBatch(source: string, emitSummary = true): Promise<void> {
+    if (this.isStopped) return Promise.resolve();
+    const current = this.sourceTasks.get(source);
+    if (current) {
+      this.pendingAfterProcessing.add(source);
+      return current;
+    }
+    const task = this.processSourceBatch(source, emitSummary);
+    this.sourceTasks.set(source, task);
+    const finish = () => {
+      this.sourceTasks.delete(source);
+      if (this.pendingAfterProcessing.delete(source) && !this.isStopped) {
+        this.triggerSourceDebounce(source);
+      }
+    };
+    void task.then(finish, finish);
+    return task;
+  }
+
+  private async processSourceBatch(source: string, emitSummary: boolean): Promise<void> {
+    const { sessions: discovered, outcomes } = await scanSessions({
+      sources: [source],
+      roots: this.roots,
+      limit: this.limit,
+      onDiagnostic: diagnostic => {
+        console.error("[ledger] scan warning:", JSON.stringify({ source, ...diagnostic }));
+      },
+    });
+
+    if (this.isStopped) return;
+
+    // A scanning drain is not a pure read: the source's verdict is recorded
+    // under this drain's lease, before the import decision, so a source that is
+    // listable with nothing new (or missing entirely) still refreshes its row.
+    this.store().recordSourceCoverage(outcomes);
+
+    const needed = discovered.filter((item) =>
+      sessionNeedsIngest(this.store(), item, { maxRecordBytes: this.maxRecordBytes }),
+    );
+    // One WAL revision makes multiple sessions eligible. Always choosing the
+    // newest would let a busy session prevent older history from ever importing.
+    const ordered = needed.some(item => item.native)
+      ? needed.map((item, index) => ({
+        item, index, attempted: this.store().getIngestCursor(item.source, item.id, item.path)?.updated_at ?? "",
+      })).sort((a, b) => a.attempted.localeCompare(b.attempted) || a.index - b.index).map(entry => entry.item)
+      : needed;
+    const toImport = ordered.slice(0, this.importBudget);
+    if (toImport.length === 0) return;
+
+    let batchImported = 0;
+    let batchAppended = 0;
+    let batchDeduped = 0;
+    let batchSkipped = 0;
+    let sessionsProcessed = 0;
+
+    for (const item of toImport) {
+      if (this.isStopped) break;
+
+      sessionsProcessed++;
+      const result = await ingestDiscoveredSession(this.store(), item, {
+        embed: this.embed,
+        maxRecordBytes: this.maxRecordBytes,
+      }).catch(() => ({
+        kind: "skipped" as const,
+        sessionId: item.id,
+        warnings: ["Ingestion failed; inspect the source and retry."],
+      }));
+      for (const warning of result.warnings ?? []) {
+        // Warnings contain controlled diagnostics, never raw exception messages
+        // or transcript content. JSON escaping keeps path metadata single-line.
+        console.error("[ledger] ingest warning:", JSON.stringify({ source, sourcePath: item.path, warning }));
+      }
+      if (this.isStopped) break;
+      if (result.kind === "unchanged") continue;
+
+      if (result.kind === "skipped" || result.kind === "deferred" || result.kind === "tombstoned") {
+        // A deletion refusal lands in the batch's skip bucket — nothing was
+        // imported, and the batch summary counts work, not reasons — while the
+        // event and the verbose line keep the reason: `sessionNeedsIngest`
+        // refuses a deleted listing before it is read, so this arrives only for
+        // the shapes that axis cannot name (a group's member file).
+        batchSkipped++;
+      } else if (result.kind === "deduped") {
+        batchDeduped++;
+      } else if (result.kind === "appended") {
+        batchAppended++;
+      } else {
+        batchImported++;
+      }
+
+      if (this.verbose) {
+        console.log(`  [${result.kind.toUpperCase()}] ${item.source}/${item.id}`);
+      }
+      this.onEvent?.({
+        source,
+        sessionId: result.sessionId,
+        kind: result.kind,
+        sessionsProcessed,
+      });
+    }
+
+    if (emitSummary && !this.isStopped) {
+      this.batchCount++;
+
+      const summary: WatcherBatchSummary = {
+        source,
+        imported: batchImported,
+        appended: batchAppended,
+        deduped: batchDeduped,
+        skipped: batchSkipped,
+        scanned: discovered.length,
+      };
+
+      this.onBatch?.(summary);
+    }
+  }
+}