@winci/local-rag 0.2.1

package/src/cli/commands/search-cmd.ts

@@ -0,0 +1,59 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+import { loadConfig } from "../../config";
+import { search, searchChunks } from "../../search/hybrid";
+
+export async function searchCommand(args: string[], getFlag: (flag: string) => string | undefined) {
+  const query = args[1];
+  if (!query) {
+    console.error("Usage: local-rag search <query> [--top N]");
+    process.exit(1);
+  }
+
+  const dir = resolve(getFlag("--dir") || ".");
+  const db = new RagDB(dir);
+  const config = await loadConfig(dir);
+  const top = parseInt(getFlag("--top") || String(config.searchTopK), 10);
+
+  const results = await search(query, db, top, 0, config.hybridWeight, config.enableReranking);
+
+  if (results.length === 0) {
+    console.log("No results found. Has the directory been indexed?");
+  } else {
+    for (const r of results) {
+      console.log(`${r.score.toFixed(4)}  ${r.path}`);
+      const preview = r.snippets[0]?.slice(0, 120).replace(/\n/g, " ");
+      console.log(`         ${preview}...`);
+      console.log();
+    }
+  }
+  db.close();
+}
+
+export async function readCommand(args: string[], getFlag: (flag: string) => string | undefined) {
+  const query = args[1];
+  if (!query) {
+    console.error("Usage: local-rag read <query> [--top N] [--threshold T] [--dir D]");
+    process.exit(1);
+  }
+
+  const dir = resolve(getFlag("--dir") || ".");
+  const db = new RagDB(dir);
+  const config = await loadConfig(dir);
+  const top = parseInt(getFlag("--top") || "8", 10);
+  const threshold = parseFloat(getFlag("--threshold") || "0.3");
+
+  const results = await searchChunks(query, db, top, threshold, config.hybridWeight, config.enableReranking);
+
+  if (results.length === 0) {
+    console.log("No relevant chunks found. Has the directory been indexed?");
+  } else {
+    for (const r of results) {
+      const entity = r.entityName ? `  •  ${r.entityName}` : "";
+      console.log(`[${r.score.toFixed(2)}] ${r.path}${entity}`);
+      console.log(r.content);
+      console.log("\n---\n");
+    }
+  }
+  db.close();
+}

package/src/cli/commands/serve.ts

@@ -0,0 +1,5 @@
+import { startServer } from "../../server";
+
+export async function serveCommand() {
+  await startServer();
+}

package/src/cli/commands/status.ts

@@ -0,0 +1,13 @@
+import { resolve } from "path";
+import { RagDB } from "../../db";
+
+export async function statusCommand(args: string[]) {
+  const dir = resolve(args[1] && !args[1].startsWith("--") ? args[1] : ".");
+  const db = new RagDB(dir);
+  const status = db.getStatus();
+  console.log(`Index status for ${dir}:`);
+  console.log(`  Files:        ${status.totalFiles}`);
+  console.log(`  Chunks:       ${status.totalChunks}`);
+  console.log(`  Last indexed: ${status.lastIndexed || "never"}`);
+  db.close();
+}

package/src/cli/index.ts

@@ -0,0 +1,117 @@
+import { initCommand } from "./commands/init";
+import { indexCommand } from "./commands/index-cmd";
+import { searchCommand, readCommand } from "./commands/search-cmd";
+import { statusCommand } from "./commands/status";
+import { removeCommand } from "./commands/remove";
+import { analyticsCommand } from "./commands/analytics";
+import { mapCommand } from "./commands/map";
+import { benchmarkCommand } from "./commands/benchmark";
+import { evalCommand } from "./commands/eval";
+import { conversationCommand } from "./commands/conversation";
+import { checkpointCommand } from "./commands/checkpoint";
+import { serveCommand } from "./commands/serve";
+import { demoCommand } from "./commands/demo";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function usage() {
+  console.log(`local-rag — Local RAG for semantic file search
+
+Usage:
+  local-rag serve                      Start MCP server (stdio)
+  local-rag init [dir]                 Create default .rag/config.json
+  local-rag index [dir] [--patterns ...] Index files in directory
+  local-rag search <query> [--top N]   Search indexed files
+  local-rag read <query> [--top N]     Read relevant chunks (full content)
+              [--threshold T] [--dir D]
+  local-rag status [dir]               Show index stats
+  local-rag remove <file> [dir]        Remove file from index
+  local-rag analytics [dir] [--days N] Show search usage analytics
+  local-rag benchmark <file> [--dir D] Run search quality benchmark
+                       [--top N]
+  local-rag eval <file> [--dir D]      Run A/B eval (with/without RAG)
+                  [--top N] [--out F]
+  local-rag map [dir] [--focus F]      Generate project dependency graph
+                [--zoom file|directory]     (Mermaid format)
+                [--max N]
+  local-rag conversation search <query> Search conversation history
+                [--dir D] [--top N]
+  local-rag conversation sessions      List indexed sessions
+                [--dir D]
+  local-rag conversation index [--dir D] Index all sessions for a project
+  local-rag checkpoint create <type>   Create a checkpoint
+                <title> <summary>
+                [--dir D] [--files f1,f2] [--tags t1,t2]
+  local-rag checkpoint list [--dir D]  List checkpoints
+                [--type T] [--top N]
+  local-rag checkpoint search <query>  Search checkpoints
+                [--dir D] [--type T] [--top N]
+  local-rag demo [dir]                 Run interactive feature demo
+
+Options:
+  dir       Project directory (default: current directory)
+  --top N   Number of results (default: 5)
+  --patterns  Comma-separated glob patterns to include`);
+}
+
+function getFlag(flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  return idx !== -1 ? args[idx + 1] : undefined;
+}
+
+export async function main() {
+  if (!command || command === "--help" || command === "-h") {
+    usage();
+    process.exit(0);
+  }
+
+  switch (command) {
+    case "serve":
+      await serveCommand();
+      break;
+    case "init":
+      await initCommand(args, getFlag);
+      break;
+    case "index":
+      await indexCommand(args, getFlag);
+      break;
+    case "search":
+      await searchCommand(args, getFlag);
+      break;
+    case "read":
+      await readCommand(args, getFlag);
+      break;
+    case "status":
+      await statusCommand(args);
+      break;
+    case "remove":
+      await removeCommand(args);
+      break;
+    case "analytics":
+      await analyticsCommand(args, getFlag);
+      break;
+    case "map":
+      await mapCommand(args, getFlag);
+      break;
+    case "benchmark":
+      await benchmarkCommand(args, getFlag);
+      break;
+    case "eval":
+      await evalCommand(args, getFlag);
+      break;
+    case "conversation":
+      await conversationCommand(args, getFlag);
+      break;
+    case "checkpoint":
+      await checkpointCommand(args, getFlag);
+      break;
+    case "demo":
+      await demoCommand(args);
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      usage();
+      process.exit(1);
+  }
+}

package/src/cli/progress.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI progress callback for indexDirectory.
+ * Transient messages (e.g. batch progress) overwrite the current line.
+ * Persistent messages print on a new line.
+ */
+let lastWasTransient = false;
+
+export function cliProgress(msg: string, opts?: { transient?: boolean }): void {
+  if (opts?.transient) {
+    const cols = process.stdout.columns || 80;
+    const truncated = msg.length > cols - 1 ? msg.slice(0, cols - 4) + "..." : msg;
+    process.stdout.write(`\r${truncated.padEnd(cols - 1)}`);
+    lastWasTransient = true;
+  } else {
+    if (lastWasTransient) {
+      process.stdout.write("\r" + " ".repeat((process.stdout.columns || 80) - 1) + "\r");
+      lastWasTransient = false;
+    }
+    console.log(msg);
+  }
+}

package/src/cli/setup.ts

@@ -0,0 +1,192 @@
+import { existsSync } from "fs";
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join, resolve } from "path";
+import { createInterface } from "readline";
+import { writeDefaultConfig } from "../config";
+
+const MARKER = "<!-- local-rag -->";
+
+const INSTRUCTIONS_BLOCK = `## Using local-rag tools
+
+This project has a local RAG index (local-rag). Use these MCP tools:
+
+- **\`search\`**: Discover which files are relevant to a topic. Returns file paths
+  with snippet previews — use this when you need to know *where* something is.
+- **\`read_relevant\`**: Get the actual content of relevant semantic chunks —
+  individual functions, classes, or markdown sections — ranked by relevance.
+  Results include exact line ranges (\`src/db.ts:42-67\`) so you can navigate
+  directly to the edit location. Use this instead of \`search\` + \`Read\` when
+  you need the content itself. Two chunks from the same file can both appear
+  (no file deduplication).
+- **\`project_map\`**: When you need to understand how files relate to each other,
+  generate a dependency graph. Use \`focus\` to zoom into a specific file's
+  neighborhood. This is faster than reading import statements across many files.
+- **\`search_conversation\`**: Search past conversation history to recall previous
+  decisions, discussions, and tool outputs. Use this before re-investigating
+  something that may have been discussed in an earlier session.
+- **\`create_checkpoint\`**: Mark important moments — decisions, milestones,
+  blockers, direction changes. Do this liberally: after completing any feature
+  or task, after adding/modifying tools, after key technical decisions, before
+  and after large refactors, or when changing direction. If in doubt, create one.
+- **\`list_checkpoints\`** / **\`search_checkpoints\`**: Review or search past
+  checkpoints to understand project history and prior decisions.
+- **\`index_files\`**: If you've created or modified files and want them searchable,
+  re-index the project directory.
+- **\`search_analytics\`**: Check what queries return no results or low-relevance
+  results — this reveals documentation gaps.
+- **\`search_symbols\`**: When you know a symbol name (function, class, type, etc.),
+  find it directly by name instead of using semantic search.
+- **\`find_usages\`**: Before changing a function or type, find all its call sites.
+  Use this to understand the blast radius of a rename or API change. Faster and
+  more reliable than semantic search for finding usages.
+- **\`git_context\`**: At the start of a session (or any time you need orientation),
+  call this to see what files have already been modified, recent commits, and
+  which changed files are in the index. Avoids redundant searches and conflicting
+  edits on already-modified files.
+- **\`annotate\`**: Attach a persistent note to a file or symbol — "known race
+  condition", "don't refactor until auth rewrite lands", etc. Notes appear as
+  \`[NOTE]\` blocks inline in \`read_relevant\` results automatically.
+- **\`get_annotations\`**: Retrieve all notes for a file, or search semantically
+  across all annotations to find relevant caveats before editing.
+- **\`write_relevant\`**: Before adding new code or docs, find the best insertion
+  point — returns the most semantically appropriate file and anchor.`;
+
+const MDC_BLOCK = `${MARKER}
+---
+description: local-rag tool usage instructions
+alwaysApply: true
+---
+
+${INSTRUCTIONS_BLOCK}`;
+
+const MARKDOWN_BLOCK = `${MARKER}
+${INSTRUCTIONS_BLOCK}`;
+
+export interface SetupResult {
+  actions: string[];
+}
+
+export async function ensureConfig(projectDir: string): Promise<string | null> {
+  const configPath = join(projectDir, ".rag", "config.json");
+  if (existsSync(configPath)) return null;
+  await writeDefaultConfig(projectDir);
+  return "Created .rag/config.json";
+}
+
+export async function ensureGitignore(projectDir: string): Promise<string | null> {
+  const gitignorePath = join(projectDir, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    await writeFile(gitignorePath, "# local-rag index\n.rag/\n");
+    return "Created .gitignore with .rag/";
+  }
+  const content = await readFile(gitignorePath, "utf-8");
+  if (content.split("\n").some(line => line.trim() === ".rag/" || line.trim() === ".rag")) {
+    return null;
+  }
+  await writeFile(gitignorePath, content.trimEnd() + "\n\n# local-rag index\n.rag/\n");
+  return "Added .rag/ to .gitignore";
+}
+
+async function injectMarkdown(filePath: string, block: string): Promise<string | null> {
+  if (existsSync(filePath)) {
+    const content = await readFile(filePath, "utf-8");
+    if (content.includes(MARKER)) return null;
+    await writeFile(filePath, content.trimEnd() + "\n\n" + block + "\n");
+    return `Updated ${filePath}`;
+  }
+  await writeFile(filePath, block + "\n");
+  return `Created ${filePath}`;
+}
+
+async function injectMdc(filePath: string, dir: string): Promise<string | null> {
+  if (!existsSync(dir)) return null;
+  if (existsSync(filePath)) {
+    const content = await readFile(filePath, "utf-8");
+    if (content.includes(MARKER)) return null;
+  }
+  await mkdir(dir, { recursive: true });
+  await writeFile(filePath, MDC_BLOCK + "\n");
+  return `Created ${filePath}`;
+}
+
+export async function ensureAgentInstructions(projectDir: string): Promise<string[]> {
+  const actions: string[] = [];
+
+  // Claude Code — always create/update
+  const claudeAction = await injectMarkdown(join(projectDir, "CLAUDE.md"), MARKDOWN_BLOCK);
+  if (claudeAction) actions.push(claudeAction);
+
+  // Cursor — only if .cursor/ exists
+  const cursorAction = await injectMdc(
+    join(projectDir, ".cursor", "rules", "local-rag.mdc"),
+    join(projectDir, ".cursor")
+  );
+  if (cursorAction) actions.push(cursorAction);
+
+  // Windsurf — only if .windsurf/ exists
+  const windsurfAction = await injectMdc(
+    join(projectDir, ".windsurf", "rules", "local-rag.mdc"),
+    join(projectDir, ".windsurf")
+  );
+  if (windsurfAction) actions.push(windsurfAction);
+
+  // GitHub Copilot — only if .github/ exists
+  if (existsSync(join(projectDir, ".github"))) {
+    const copilotAction = await injectMarkdown(
+      join(projectDir, ".github", "copilot-instructions.md"),
+      MARKDOWN_BLOCK
+    );
+    if (copilotAction) actions.push(copilotAction);
+  }
+
+  return actions;
+}
+
+export function mcpConfigSnippet(projectDir: string): string {
+  const abs = resolve(projectDir);
+  return JSON.stringify({
+    "local-rag": {
+      command: "bunx",
+      args: ["@winci/local-rag@latest"],
+      env: { RAG_PROJECT_DIR: abs },
+    },
+  }, null, 2);
+}
+
+export function detectAgentHints(projectDir: string): string[] {
+  const hints: string[] = [];
+  if (existsSync(join(projectDir, ".mcp.json")))
+    hints.push("Claude Code:  add to .mcp.json → mcpServers");
+  if (existsSync(join(projectDir, ".cursor")))
+    hints.push("Cursor:       add to .cursor/mcp.json → mcpServers");
+  if (existsSync(join(projectDir, ".windsurf")))
+    hints.push("Windsurf:     add to .windsurf/mcp.json → mcpServers");
+  if (hints.length === 0)
+    hints.push("Add to your agent's MCP config under mcpServers:");
+  return hints;
+}
+
+export function confirm(question: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((res) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      res(answer.trim().toLowerCase() !== "n");
+    });
+  });
+}
+
+export async function runSetup(projectDir: string): Promise<SetupResult> {
+  const actions: string[] = [];
+
+  const configAction = await ensureConfig(projectDir);
+  if (configAction) actions.push(configAction);
+
+  const instructionActions = await ensureAgentInstructions(projectDir);
+  actions.push(...instructionActions);
+
+  const gitignoreAction = await ensureGitignore(projectDir);
+  if (gitignoreAction) actions.push(gitignoreAction);
+
+  return { actions };
+}

package/src/config/index.ts

@@ -0,0 +1,101 @@
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+import { existsSync } from "fs";
+import { z } from "zod";
+import { log } from "../utils/log";
+
+const RagConfigSchema = z.object({
+  include: z.array(z.string()).default([]),
+  exclude: z.array(z.string()).default([]),
+  chunkSize: z.number().int().min(64).default(512),
+  chunkOverlap: z.number().int().min(0).default(50),
+  hybridWeight: z.number().min(0).max(1).default(0.7),
+  searchTopK: z.number().int().min(1).default(5),
+  indexBatchSize: z.number().int().min(1).optional(),
+  indexThreads: z.number().int().min(1).optional(),
+  enableReranking: z.boolean().default(true),
+  benchmarkTopK: z.number().int().min(1).default(5),
+  benchmarkMinRecall: z.number().min(0).max(1).default(0.8),
+  benchmarkMinMrr: z.number().min(0).max(1).default(0.6),
+});
+
+export type RagConfig = z.infer<typeof RagConfigSchema>;
+
+const DEFAULT_CONFIG: RagConfig = {
+  include: [
+    // Markdown & plain text
+    "**/*.md", "**/*.txt",
+    // Build / task runners (no extension or prefix-named)
+    "**/Makefile", "**/makefile", "**/GNUmakefile",
+    "**/Dockerfile", "**/Dockerfile.*",
+    "**/Jenkinsfile", "**/Jenkinsfile.*",
+    "**/Vagrantfile", "**/Gemfile", "**/Rakefile",
+    "**/Brewfile", "**/Procfile",
+    // Structured data & config
+    "**/*.yaml", "**/*.yml",
+    "**/*.json",
+    "**/*.toml",
+    "**/*.xml",
+    // Shell & scripting
+    "**/*.sh", "**/*.bash", "**/*.zsh",
+    // Infrastructure / schema languages
+    "**/*.tf",
+    "**/*.proto",
+    "**/*.graphql", "**/*.gql",
+    "**/*.sql",
+    "**/*.mod",
+    "**/*.bru",
+    "**/*.css", "**/*.scss", "**/*.less",
+  ],
+  exclude: ["node_modules/**", ".git/**", "dist/**", ".rag/**"],
+  chunkSize: 512,
+  chunkOverlap: 50,
+  hybridWeight: 0.7,
+  searchTopK: 5,
+  enableReranking: true,
+  indexBatchSize: 50,
+  benchmarkTopK: 5,
+  benchmarkMinRecall: 0.8,
+  benchmarkMinMrr: 0.6,
+};
+
+/**
+ * Load config from .rag/config.json, merged with defaults.
+ * Note: array fields (include, exclude) from user config *replace* the defaults
+ * entirely — they are not merged. This lets users fully control which files are indexed.
+ */
+export async function loadConfig(projectDir: string): Promise<RagConfig> {
+  const configPath = join(projectDir, ".rag", "config.json");
+
+  if (!existsSync(configPath)) {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  const raw = await readFile(configPath, "utf-8");
+  let userConfig: unknown;
+  try {
+    userConfig = JSON.parse(raw);
+  } catch {
+    log.warn(`Invalid JSON in ${configPath}, using defaults`, "config");
+    return { ...DEFAULT_CONFIG };
+  }
+
+  const merged = { ...DEFAULT_CONFIG, ...(userConfig as Record<string, unknown>) };
+  const result = RagConfigSchema.safeParse(merged);
+
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ");
+    log.warn(`Config validation: ${issues}. Using defaults for invalid fields.`, "config");
+    return { ...DEFAULT_CONFIG };
+  }
+
+  return result.data;
+}
+
+export async function writeDefaultConfig(projectDir: string): Promise<string> {
+  const ragDir = join(projectDir, ".rag");
+  await mkdir(ragDir, { recursive: true });
+  const configPath = join(ragDir, "config.json");
+  await writeFile(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+  return configPath;
+}

package/src/conversation/indexer.ts

@@ -0,0 +1,147 @@
+import { watch, statSync } from "fs";
+import { readJSONL, parseTurns, buildTurnText, type ParsedTurn } from "./parser";
+import { chunkText } from "../indexing/chunker";
+import { embedBatch } from "../embeddings/embed";
+import { type RagDB } from "../db";
+import { type Watcher } from "../indexing/watcher";
+
+const TAIL_DEBOUNCE_MS = 1500;
+
+/**
+ * Index all turns from a JSONL transcript file.
+ * Returns the number of new turns indexed and the final byte offset.
+ */
+export async function indexConversation(
+  jsonlPath: string,
+  sessionId: string,
+  db: RagDB,
+  fromOffset = 0,
+  startTurnIndex = 0,
+  onProgress?: (msg: string) => void
+): Promise<{ turnsIndexed: number; newOffset: number; totalTokens: number }> {
+  const { entries, newOffset } = readJSONL(jsonlPath, fromOffset);
+
+  if (entries.length === 0) {
+    return { turnsIndexed: 0, newOffset: fromOffset, totalTokens: 0 };
+  }
+
+  const turns = parseTurns(entries, sessionId, startTurnIndex);
+
+  let turnsIndexed = 0;
+  let totalTokens = 0;
+
+  for (const turn of turns) {
+    const indexed = await indexTurn(turn, db);
+    if (indexed) {
+      turnsIndexed++;
+      onProgress?.(`Indexed turn ${turn.turnIndex} (${turn.toolsUsed.join(", ") || "no tools"})`);
+    }
+    totalTokens += turn.tokenCost;
+  }
+
+  // Update session tracking
+  const existingSession = db.getSession(sessionId);
+  const totalTurnCount = (existingSession?.turnCount || 0) + turnsIndexed;
+  const stat = statSync(jsonlPath);
+
+  db.upsertSession(sessionId, jsonlPath, turns[0]?.timestamp || new Date().toISOString(), stat.mtimeMs, newOffset);
+  db.updateSessionStats(sessionId, totalTurnCount, totalTokens, newOffset);
+
+  return { turnsIndexed, newOffset, totalTokens };
+}
+
+/**
+ * Index a single parsed turn: chunk the text, embed chunks, store in DB.
+ */
+async function indexTurn(turn: ParsedTurn, db: RagDB): Promise<boolean> {
+  const text = buildTurnText(turn);
+  if (!text.trim()) return false;
+
+  // Chunk the turn text (use .md extension for paragraph-style splitting)
+  const textChunks = await chunkText(text, ".md", 512, 50);
+
+  // Embed all chunks in one batch
+  const embeddings = await embedBatch(textChunks.map(c => c.text));
+  const embeddedChunks = textChunks.map((chunk, i) => ({
+    snippet: chunk.text,
+    embedding: embeddings[i],
+  }));
+
+  // Store in DB — returns 0 if this turn was already indexed (duplicate)
+  const turnId = db.insertTurn(
+    turn.sessionId,
+    turn.turnIndex,
+    turn.timestamp,
+    turn.userText,
+    turn.assistantText,
+    turn.toolsUsed,
+    turn.filesReferenced,
+    turn.tokenCost,
+    turn.summary,
+    embeddedChunks
+  );
+
+  return turnId !== 0;
+}
+
+/**
+ * Start tailing a JSONL file for live conversation indexing.
+ * Watches for file changes and indexes new turns as they appear.
+ */
+export function startConversationTail(
+  jsonlPath: string,
+  sessionId: string,
+  db: RagDB,
+  onEvent?: (msg: string) => void
+): Watcher {
+  let currentOffset = 0;
+  let currentTurnIndex = 0;
+  let pending: NodeJS.Timeout | null = null;
+
+  // Load existing state
+  const session = db.getSession(sessionId);
+  if (session) {
+    currentOffset = session.readOffset;
+    currentTurnIndex = session.turnCount;
+  }
+
+  async function processNewData() {
+    try {
+      const result = await indexConversation(
+        jsonlPath,
+        sessionId,
+        db,
+        currentOffset,
+        currentTurnIndex,
+        onEvent
+      );
+
+      if (result.turnsIndexed > 0) {
+        currentOffset = result.newOffset;
+        currentTurnIndex += result.turnsIndexed;
+        onEvent?.(`Conversation: ${result.turnsIndexed} new turns indexed (total: ${currentTurnIndex})`);
+      }
+    } catch (err) {
+      onEvent?.(`Conversation index error: ${(err as Error).message}`);
+    }
+  }
+
+  const watcher = watch(jsonlPath, () => {
+    if (pending) clearTimeout(pending);
+    pending = setTimeout(() => {
+      pending = null;
+      processNewData();
+    }, TAIL_DEBOUNCE_MS);
+  });
+
+  // Do initial index
+  processNewData();
+
+  onEvent?.(`Tailing conversation: ${jsonlPath}`);
+  return {
+    close() {
+      if (pending) { clearTimeout(pending); pending = null; }
+      watcher.close();
+    },
+  };
+}