nodedex 0.1.0

package/adapters/claude-code-watcher.mjs

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+// claude-code-watcher.mjs — capture Claude Code turns into NodeDex by reading Claude Code's
+// own session transcripts (~/.claude/projects/<project>/<session>.jsonl). Zero cooperation
+// needed from the host: no hooks to wire, no config in Claude Code itself — every session is
+// already persisted line-by-line as it happens; we tail it.
+//
+// WHAT IT IS
+//   A thin, host-specific shim over the shared capture core (nodedex-capture-core.mjs), the
+//   same architecture as hermes-statedb-watcher.mjs. All it adds is "how Claude Code hands me
+//   a turn": tail the JSONL files, assemble whole turns, call captureTurn().
+//
+// THE HARD PART — turn ASSEMBLY (what one logical turn looks like in the JSONL)
+//   One turn spans many lines:
+//     user(text) → assistant(thinking|text|tool_use)* → user(tool_result)* → … → assistant(text)
+//   There is NO explicit end-of-turn marker. A turn CLOSES when:
+//     • the NEXT real user prompt arrives in that session (the reliable boundary), or
+//     • the file has been idle past idleFlushMs with a complete buffered turn (the last turn
+//       of a session would otherwise never emit).
+//   Mapping (mirrors the Hermes watcher: narration → response, raw traces → thinking):
+//     agent_response = the assistant's TEXT blocks across the turn (preambles + final answer)
+//     user_message   = the user prompt(s) that opened the turn (system tags stripped)
+//     agent_thinking = thinking blocks + tool_use/tool_result previews (recorded, not extracted)
+//   Skipped lines: isSidechain (subagent chatter), isMeta, and non-user/assistant types
+//   (queue-operation, attachment, file-history-snapshot, ai-title, system, mode, …).
+//
+// WATERMARK (why turnNumber = a byte offset)
+//   Same anchoring trick as Hermes (turn_number = state.db stop-id): the turn's identity lives
+//   in the HOST's own log, not in a drift-prone private counter. Here that identity is the byte
+//   offset where the turn's opening user line starts — stable across restarts, monotonic per
+//   file, so (agent_id, turn_number) is idempotent and the extraction range IS a watermark.
+//
+// SAFETY
+//   • READ-ONLY — opens transcripts with plain reads; never writes to ~/.claude.
+//   • Privacy filter: only project dirs in the allow-list are read (default "*" = all — the
+//     TUI consent step is where the user scopes this). Sub-agent sidechains are never captured.
+//   • Fresh start captures FORWARD only (cursor = current EOF) — no history replay.
+//
+// CONFIG (read live each poll from ~/.nodedex/config.json → claudeCapture):
+//   { enabled, projects: string[], pollMs, idleFlushMs, projectsDir }   (all optional)
+//
+// RUN
+//   node server/adapters/claude-code-watcher.mjs             # poll forever
+//   node server/adapters/claude-code-watcher.mjs --dry-run   # print assembled turns, POST nothing
+//   node server/adapters/claude-code-watcher.mjs --once      # one pass then exit (testing)
+//   node server/adapters/claude-code-watcher.mjs --backfill  # also capture ALL pre-existing turns
+//   node server/adapters/claude-code-watcher.mjs --last 50   # bounded backfill: only the last N
+//                                                              turns per file (the "see your memory
+//                                                              in 2 minutes" onboarding path)
+//   node server/adapters/claude-code-watcher.mjs --newest    # only the newest session per project
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, openSync, readSync, closeSync, createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { join, basename } from "node:path";
+import { captureTurn } from "./nodedex-capture-core.mjs";
+
+const HOME = join(homedir(), ".nodedex");
+const CONFIG_FILE = join(HOME, "config.json");
+const CURSOR_FILE = join(HOME, "claude-code-capture-cursor.json");
+
+const args = new Set(process.argv.slice(2));
+const DRY_RUN = args.has("--dry-run");
+const ONCE = args.has("--once");
+const BACKFILL = args.has("--backfill");
+const NEWEST = args.has("--newest");
+const LAST = (() => {
+  const i = process.argv.indexOf("--last");
+  return i >= 0 ? Math.max(1, Number(process.argv[i + 1]) || 0) : 0;
+})();
+
+const TOOL_PREVIEW = 240; // truncate each tool result/args inside the thinking trace
+
+// ─── config (re-read each poll so TUI changes apply without a restart) ────────────────────────
+function defaultProjectsDir() {
+  return join(homedir(), ".claude", "projects");
+}
+function loadCaptureConfig() {
+  let raw = {};
+  try { raw = JSON.parse(readFileSync(CONFIG_FILE, "utf8"))?.claudeCapture ?? {}; } catch { /* none */ }
+  const projects = Array.isArray(raw.projects) && raw.projects.length ? raw.projects.map(String) : ["*"];
+  return {
+    enabled: raw.enabled !== false,
+    projects,
+    allowAll: projects.includes("*"),
+    pollMs: Number.isFinite(raw.pollMs) && raw.pollMs >= 1000 ? raw.pollMs : 5000,
+    idleFlushMs: Number.isFinite(raw.idleFlushMs) && raw.idleFlushMs >= 15000 ? raw.idleFlushMs : 120000,
+    projectsDir: raw.projectsDir || defaultProjectsDir(),
+  };
+}
+const projectAllowed = (cfg, dirName) => cfg.allowAll || cfg.projects.includes(dirName);
+
+// ─── cursor: file → byte offset of the CURRENT (still-buffering) turn's opening line ──────────
+// We persist the offset where the pending turn STARTS, not EOF — so a restart re-reads and
+// re-buffers the in-flight turn instead of losing it. Emitted turns are idempotent via
+// turnNumber (= that same offset), so a re-emit after restart dedups server-side.
+function loadCursors() {
+  try { return JSON.parse(readFileSync(CURSOR_FILE, "utf8"))?.files ?? {}; } catch { return {}; }
+}
+function saveCursors(files) {
+  try { mkdirSync(HOME, { recursive: true }); writeFileSync(CURSOR_FILE, JSON.stringify({ files }, null, 2)); }
+  catch { /* read-only home → memory-only cursors */ }
+}
+
+// ─── line classification ───────────────────────────────────────────────────────────────────────
+const clean = (s) => String(s ?? "").replace(/\s+/g, " ").trim();
+const truncate = (s, n) => { const t = String(s ?? ""); return t.length > n ? t.slice(0, n) + "…" : t; };
+
+// System-injected user texts that are NOT a human prompt. Stripped from prompts; a user line
+// that is ONLY these never opens a turn.
+const SYSTEM_TEXT = /^\s*(<command-name>|<local-command-stdout>|<local-command-caveat>|<ide_|<system-reminder>|Caveat: The messages below)/;
+
+/** Real prompt text from a user line ("" when it's tool results / meta / system tags only). */
+function userPromptText(msg) {
+  const c = msg?.content;
+  const parts = [];
+  if (typeof c === "string") { if (!SYSTEM_TEXT.test(c)) parts.push(c); }
+  else if (Array.isArray(c)) {
+    for (const item of c) {
+      if (item?.type === "text" && typeof item.text === "string" && !SYSTEM_TEXT.test(item.text)) parts.push(item.text);
+    }
+  }
+  return clean(parts.join("\n"));
+}
+
+/** Tool-result previews from a user line (the feedback half of tool use). */
+function toolResultPreviews(msg) {
+  const out = [];
+  const c = msg?.content;
+  if (!Array.isArray(c)) return out;
+  for (const item of c) {
+    if (item?.type !== "tool_result") continue;
+    const inner = typeof item.content === "string"
+      ? item.content
+      : Array.isArray(item.content) ? item.content.map((x) => (x?.type === "text" ? x.text : "")).join(" ") : "";
+    const t = clean(inner);
+    if (t) out.push(`[result] ${truncate(t, TOOL_PREVIEW)}`);
+  }
+  return out;
+}
+
+// ─── bounded backfill: find where the Nth-from-last turn STARTS ────────────────────────────────
+// Streams the file once (memory-light even on multi-hundred-MB transcripts), recording the byte
+// offset of every line that opens a turn (a real user prompt), and returns the offset to start
+// from so exactly the last N turns are captured. The cheap `includes` pre-filter skips JSON.parse
+// on the ~90% of lines that can't be user prompts.
+async function offsetOfNthLastPrompt(filePath, n) {
+  const offsets = [];
+  let offset = 0;
+  const rl = createInterface({ input: createReadStream(filePath), crlfDelay: Infinity });
+  for await (const line of rl) {
+    const lineBytes = Buffer.byteLength(line, "utf8") + 1;
+    if (line.includes('"type":"user"')) {
+      try {
+        const j = JSON.parse(line);
+        if (j?.type === "user" && !j.isMeta && !j.isSidechain && userPromptText(j.message)) offsets.push(offset);
+      } catch { /* garbled line → skip */ }
+    }
+    offset += lineBytes;
+  }
+  return offsets[Math.max(0, offsets.length - n)] ?? 0;
+}
+
+// ─── per-file turn assembly state ──────────────────────────────────────────────────────────────
+/** files: path → { offset, pendingStart, buf, partial, lastGrowth, sessionId, project } */
+const state = new Map();
+
+function newBuffer() {
+  return { user: [], response: [], thinking: [], openedAt: 0 };
+}
+
+function emitReady(fileState) {
+  const b = fileState.buf;
+  return b && b.user.length > 0 && b.response.length > 0;
+}
+
+async function emitTurn(fileState, filePath) {
+  const b = fileState.buf;
+  const sid = fileState.sessionId || basename(filePath, ".jsonl");
+  const turn = {
+    agentResponse: b.response.join("\n"),
+    userMessage: b.user.join("\n"),
+    reasoning: b.thinking.join("\n"),
+    // #agent-id convention: host-prefixed + per-session → one arc per Claude Code session,
+    // and provenance in the graph reads as "this came from Claude Code".
+    agentId: `claude-code-${String(sid).slice(0, 8)}`,
+    turnNumber: b.openedAt, // byte offset of the turn's opening line — the file-anchored watermark
+    turnName: `cc-${fileState.project.slice(0, 20)}-${b.openedAt}`,
+    hint: "discovery",
+  };
+  if (DRY_RUN) {
+    console.log("─".repeat(72));
+    console.log(`TURN  project=${fileState.project}  session=${String(sid).slice(0, 8)}  at=${b.openedAt}`);
+    console.log(`  user:      ${truncate(turn.userMessage.replace(/\n/g, " ⏎ "), 160)}`);
+    console.log(`  response:  ${truncate(clean(turn.agentResponse), 200)}  (${turn.agentResponse.length} ch)`);
+    console.log(`  thinking:  ${truncate(turn.reasoning.replace(/\n/g, " · "), 200)}  (${turn.reasoning.length} ch)`);
+  } else {
+    const status = await captureTurn(turn);
+    console.log(`[claude-code-watcher] captured ${fileState.project}/${String(sid).slice(0, 8)}@${b.openedAt} → ${status}`);
+  }
+}
+
+/** Feed one parsed JSONL line into the file's buffer. Returns "opened" when a new turn began. */
+async function feedLine(fileState, filePath, lineStartOffset, j) {
+  if (!j || j.isSidechain === true || j.isMeta === true) return;
+  if (j.sessionId && !fileState.sessionId) fileState.sessionId = j.sessionId;
+
+  if (j.type === "user") {
+    const prompt = userPromptText(j.message);
+    if (prompt) {
+      // A real user prompt = the boundary. Emit the buffered turn, then open a new one here.
+      if (emitReady(fileState)) await emitTurn(fileState, filePath);
+      if (!fileState.buf || fileState.buf.response.length > 0 || fileState.buf.user.length === 0) {
+        fileState.buf = newBuffer();
+        fileState.buf.openedAt = lineStartOffset;
+        fileState.pendingStart = lineStartOffset;
+      }
+      fileState.buf.user.push(prompt);
+      return;
+    }
+    // tool results ride the CURRENT turn's thinking trace
+    if (fileState.buf) fileState.buf.thinking.push(...toolResultPreviews(j.message));
+    return;
+  }
+
+  if (j.type === "assistant" && fileState.buf) {
+    const c = j.message?.content;
+    if (!Array.isArray(c)) return;
+    for (const item of c) {
+      if (item?.type === "text" && item.text) fileState.buf.response.push(clean(item.text));
+      else if (item?.type === "thinking" && item.thinking) fileState.buf.thinking.push(truncate(clean(item.thinking), 2000));
+      else if (item?.type === "tool_use") fileState.buf.thinking.push(`[tool] ${item.name || "?"}(${truncate(JSON.stringify(item.input ?? {}), TOOL_PREVIEW)})`);
+    }
+  }
+}
+
+// ─── one pass over one file: read appended bytes, feed complete lines ──────────────────────────
+async function passFile(fileState, filePath, cfg) {
+  const size = statSync(filePath).size;
+  if (size < fileState.offset) fileState.offset = size; // truncated? resync forward-only
+  if (size > fileState.offset) {
+    const fd = openSync(filePath, "r");
+    try {
+      const len = size - fileState.offset;
+      const buf = Buffer.alloc(Math.min(len, 8 * 1024 * 1024)); // cap one pass at 8MB
+      const read = readSync(fd, buf, 0, buf.length, fileState.offset);
+      const chunk = buf.toString("utf8", 0, read);
+      // Only COMPLETE lines advance the offset (summed in exact bytes per line, so a
+      // trailing partial line — or a mid-multibyte-char cut — is simply re-read next
+      // pass once its newline lands; no in-memory carry, no byte drift).
+      let text = chunk;
+      let lineStart = fileState.offset;
+      let consumed = 0;
+      let idx;
+      while ((idx = text.indexOf("\n")) >= 0) {
+        const line = text.slice(0, idx);
+        const lineBytes = Buffer.byteLength(line, "utf8") + 1;
+        if (line.trim()) {
+          let j = null; try { j = JSON.parse(line); } catch { /* garbled line → skip */ }
+          if (j) await feedLine(fileState, filePath, lineStart, j);
+        }
+        lineStart += lineBytes;
+        consumed += lineBytes;
+        text = text.slice(idx + 1);
+      }
+      fileState.offset += consumed;
+      fileState.lastGrowth = Date.now();
+    } finally { closeSync(fd); }
+  } else if (emitReady(fileState) && Date.now() - fileState.lastGrowth > cfg.idleFlushMs) {
+    // idle flush: the session went quiet with a complete turn buffered (the session's last turn)
+    await emitTurn(fileState, filePath);
+    fileState.buf = newBuffer();
+    fileState.pendingStart = fileState.offset;
+  }
+}
+
+// ─── one pass: discover files, tail each, persist cursors ─────────────────────────────────────
+async function pass(cfg) {
+  let dirs = [];
+  try { dirs = readdirSync(cfg.projectsDir, { withFileTypes: true }).filter((d) => d.isDirectory()); } catch { return; }
+  for (const dir of dirs) {
+    if (!projectAllowed(cfg, dir.name)) continue;
+    let files = [];
+    try { files = readdirSync(join(cfg.projectsDir, dir.name)).filter((f) => f.endsWith(".jsonl")); } catch { continue; }
+    if (NEWEST && files.length > 1) {
+      files = [files
+        .map((f) => ({ f, m: (() => { try { return statSync(join(cfg.projectsDir, dir.name, f)).mtimeMs; } catch { return 0; } })() }))
+        .sort((a, b) => b.m - a.m)[0].f];
+    }
+    for (const f of files) {
+      const filePath = join(cfg.projectsDir, dir.name, f);
+      let fs_ = state.get(filePath);
+      if (!fs_) {
+        // New file: forward-only unless --backfill / --last N (an explicit bound wins
+        // over a persisted cursor so a bounded backfill run is deterministic).
+        const persisted = loadCursors()[filePath];
+        let startAt;
+        if (LAST > 0) {
+          startAt = await offsetOfNthLastPrompt(filePath, LAST);
+          console.log(`[claude-code-watcher] ${basename(filePath)}: --last ${LAST} → starting at byte ${startAt}`);
+        } else if (BACKFILL) startAt = 0;
+        else startAt = persisted?.offset ?? statSync(filePath).size;
+        fs_ = { offset: startAt, pendingStart: startAt, buf: newBuffer(), lastGrowth: Date.now(), sessionId: null, project: dir.name };
+        state.set(filePath, fs_);
+      }
+      try { await passFile(fs_, filePath, cfg); } catch (e) { console.error(`[claude-code-watcher] ${basename(filePath)}: ${e?.message ?? e}`); }
+    }
+  }
+  if (!DRY_RUN) {
+    const files = {};
+    for (const [p, s] of state) { if (existsSync(p)) files[p] = { offset: s.pendingStart }; }
+    saveCursors(files);
+  }
+}
+
+// ─── main loop ─────────────────────────────────────────────────────────────────────────────────
+async function main() {
+  const boot = loadCaptureConfig();
+  console.log(`[claude-code-watcher] ${DRY_RUN ? "DRY-RUN " : ""}watching ${boot.projectsDir}`);
+  console.log(`[claude-code-watcher] projects=${boot.allowAll ? "* (all)" : boot.projects.join(",")}  poll=${boot.pollMs}ms${BACKFILL ? "  (backfill)" : ""}`);
+  let warnedMissing = false;
+  do {
+    const cfg = loadCaptureConfig();
+    if (cfg.enabled) {
+      if (!existsSync(cfg.projectsDir)) {
+        if (!warnedMissing) { console.log(`[claude-code-watcher] waiting — no Claude Code projects dir at ${cfg.projectsDir} yet`); warnedMissing = true; }
+      } else {
+        if (warnedMissing) { console.log(`[claude-code-watcher] projects dir appeared — starting capture`); warnedMissing = false; }
+        try { await pass(cfg); } catch (e) { console.error(`[claude-code-watcher] pass error: ${e?.message ?? e}`); }
+      }
+    }
+    if (ONCE) break;
+    await new Promise((r) => setTimeout(r, cfg.pollMs));
+  } while (true);
+}
+
+main().catch((e) => { console.error(`[claude-code-watcher] fatal: ${e?.message ?? e}`); process.exit(1); });

package/adapters/hermes-statedb-watcher.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+// hermes-statedb-watcher.mjs — capture Hermes/Owl turns into NodeDex by reading Hermes's own
+// state.db. This is the ONLY working capture path for Hermes: the model proxy is ignored
+// (Hermes hardcodes its OpenRouter endpoint) and shell hooks are registered but never invoked.
+// Hermes persists every turn to state.db itself, so we read it — zero Hermes cooperation needed.
+//
+// WHAT IT IS
+//   A thin, host-specific shim over the shared capture core (nodedex-capture-core.mjs). All it
+//   adds is "how Hermes hands me a turn": it polls the messages table read-only, assembles whole
+//   turns, and calls captureTurn(). Finding the live server + POSTing is the core's job.
+//
+// THE HARD PART — turn ASSEMBLY (why a naive row-pair is wrong)
+//   One logical agent turn spans many rows:
+//     user → assistant(tool_calls) → tool → assistant(tool_calls) → tool → … → assistant(stop)
+//   Hermes marks the END of a turn with finish_reason='stop'; every intermediate assistant row is
+//   finish_reason='tool_calls' (a "let me check…" preamble). So:
+//     • agent_response  = the agent's whole NARRATION across the turn — the tool-call preambles
+//                         AND the final answer, joined — so extraction (v2 COMPREHEND reads
+//                         user+response) sees the tool-driven investigation (dead-ends,
+//                         decisions), not just the closing summary.
+//     • user_message    = the user row(s) that opened the turn
+//     • agent_thinking  = the raw tool RESULTS + any reasoning_content — recorded to the turn
+//                         but NOT fed to extraction (raw tool JSON there adds noise / over-seg).
+//   Pairing "each assistant with the preceding user" would instead emit garbage fragments.
+//
+// SAFETY
+//   • READ-ONLY (mode=ro&immutable=1) — never opens the live DB for write; cannot corrupt it.
+//   • Privacy filter: only captures sessions whose `source` is in the allow-list (default ["tui"]),
+//     so telegram/discord/other sources are never read into the graph. Configurable in the TUI.
+//   • In-flight turns (no closing stop yet) are deferred until their stop row appears.
+//   • Fresh start captures FORWARD only (cursor = current max id) — it does not replay all history.
+//
+// CONFIG (read live each poll from ~/.nodedex/config.json → hermesCapture):
+//   { enabled, sources: string[], pollMs, stateDbPath }   (all optional; sane defaults below)
+//
+// RUN
+//   node server/adapters/hermes-statedb-watcher.mjs            # poll forever
+//   node server/adapters/hermes-statedb-watcher.mjs --dry-run  # print assembled turns, POST nothing
+//   node server/adapters/hermes-statedb-watcher.mjs --once     # one pass then exit (testing)
+//   node server/adapters/hermes-statedb-watcher.mjs --backfill # also capture pre-existing turns
+
+import { createRequire } from "node:module";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { captureTurn } from "./nodedex-capture-core.mjs";
+
+// better-sqlite3 lives in server/node_modules; resolve it relative to THIS file so the watcher
+// runs from any cwd (TUI spawns it with cwd=server, but a manual run shouldn't have to).
+const require = createRequire(import.meta.url);
+const Database = require("better-sqlite3");
+
+// Open Hermes's live DB strictly READ-ONLY. better-sqlite3 (unlike Python/node-sqlite3) does NOT
+// support `file:…?mode=ro` URIs — pass the OS path + { readonly:true }. We deliberately do NOT use
+// immutable mode: the file IS changing (Hermes writes every turn), and immutable would risk stale
+// reads. readonly gives a consistent SQLite snapshot without ever writing the main db.
+const openRO = (path) => new Database(path, { readonly: true });
+
+const HOME = join(homedir(), ".nodedex");
+const CONFIG_FILE = join(HOME, "config.json");
+const CURSOR_FILE = join(HOME, "hermes-capture-cursor.json");
+
+const args = new Set(process.argv.slice(2));
+const DRY_RUN = args.has("--dry-run");
+const ONCE = args.has("--once");
+const BACKFILL = args.has("--backfill");
+
+const TOOL_PREVIEW = 240; // truncate each tool result inside the reasoning trace
+
+// ─── config (re-read each poll so TUI changes apply without a restart) ────────────────────────
+function defaultStateDbPath() {
+  if (platform() === "win32" && process.env.LOCALAPPDATA) {
+    return join(process.env.LOCALAPPDATA, "hermes", "state.db");
+  }
+  // mac/linux Hermes (best-effort default; override via config.stateDbPath)
+  return join(homedir(), ".local", "share", "hermes", "state.db");
+}
+function loadCaptureConfig() {
+  let raw = {};
+  try { raw = JSON.parse(readFileSync(CONFIG_FILE, "utf8"))?.hermesCapture ?? {}; } catch { /* none */ }
+  const sources = Array.isArray(raw.sources) && raw.sources.length ? raw.sources.map(String) : ["tui"];
+  return {
+    enabled: raw.enabled !== false,                 // present-but-not-false → on (the watcher only runs when started)
+    sources,                                         // [] or ["*"] handled by sourceAllowed()
+    allowAll: sources.includes("*"),
+    pollMs: Number.isFinite(raw.pollMs) && raw.pollMs >= 500 ? raw.pollMs : 4000,
+    stateDbPath: raw.stateDbPath || defaultStateDbPath(),
+  };
+}
+const sourceAllowed = (cfg, source) => cfg.allowAll || cfg.sources.includes(String(source ?? ""));
+
+// ─── cursor (last stop-row id we've emitted a turn for) ───────────────────────────────────────
+function loadCursor() {
+  try { return Number(JSON.parse(readFileSync(CURSOR_FILE, "utf8"))?.lastStopId) || 0; } catch { return 0; }
+}
+function saveCursor(lastStopId) {
+  try { mkdirSync(HOME, { recursive: true }); writeFileSync(CURSOR_FILE, JSON.stringify({ lastStopId }, null, 2)); }
+  catch { /* read-only home → no persistence; we just re-process from memory cursor */ }
+}
+
+// ─── turn assembly ────────────────────────────────────────────────────────────────────────────
+const clean = (s) => String(s ?? "").replace(/\s+/g, " ").trim();
+const truncate = (s, n) => { const t = String(s ?? ""); return t.length > n ? t.slice(0, n) + "…" : t; };
+
+/** Build one turn from the rows in [prevStopId+1 .. stop.id] of a session. null if no user prompt. */
+function assembleTurn(db, sid, prevStopId, stop) {
+  const rows = db.prepare(
+    `SELECT id, role, content, tool_name, finish_reason, reasoning_content
+       FROM messages WHERE session_id = ? AND id > ? AND id <= ? ORDER BY id`
+  ).all(sid, prevStopId, stop.id);
+
+  const userParts = [];
+  const agentParts = [];                                  // agent narration across the turn (preambles + final answer) → response
+  const toolTrace = [];                                   // raw tool outputs → thinking (recorded, not extracted)
+  for (const r of rows) {
+    if (r.role === "user") { const c = clean(r.content); if (c) userParts.push(c); }
+    else if (r.role === "assistant") { const c = clean(r.content); if (c) agentParts.push(c); }          // incl. the final 'stop' row
+    else if (r.role === "tool") { const c = clean(r.content); if (c) toolTrace.push(`[${r.tool_name || "tool"}] ${truncate(c, TOOL_PREVIEW)}`); }
+  }
+  if (!userParts.length || !agentParts.length) return null;   // no prompt or no agent text → skip (orphan)
+
+  const stopThinking = clean(stop.reasoning_content);     // thinking-model reasoning on the final row
+  if (stopThinking) toolTrace.unshift(stopThinking);
+
+  // turn_number = the state.db message id of this turn's closing 'stop' row — the turn's identity
+  // in HERMES'S OWN log, NOT a private ordinal. Anchoring to it means NodeDex never keeps a
+  // drift-prone copy of "what's extracted": the extraction RANGE bounds ARE state.db ids
+  // (conversation_turn_ranges.end_turn_number = the last extracted stop-id = a watermark), so
+  // "extracted vs not" is just `state.db stop.id <= watermark`. Globally unique + monotonic.
+  // agent_id is PER-SESSION ("owl-<sid>") so each conversation is its own arc (turns don't bleed
+  // across sessions into one range).
+  const turnNumber = stop.id;
+
+  return {
+    agentResponse: agentParts.join("\n"),
+    userMessage: userParts.join("\n"),
+    reasoning: toolTrace.join("\n"),
+    agentId: `owl-${String(sid)}`,                  // per-session → one arc per Hermes conversation
+    turnNumber,                                      // = state.db stop-row id (the state-anchored watermark unit)
+    turnName: `hermes-${String(sid).slice(0, 15)}-${stop.id}`,
+    hint: "discovery",
+  };
+}
+
+// ─── one pass: find new completed turns, assemble, capture ────────────────────────────────────
+async function pass(cfg, cursor) {
+  const db = openRO(cfg.stateDbPath);
+  try {
+    // Completed turns since the cursor = assistant rows with finish_reason='stop' and id > cursor.
+    const stops = db.prepare(
+      `SELECT m.id, m.session_id, m.content, m.reasoning_content, s.source
+         FROM messages m JOIN sessions s ON s.id = m.session_id
+        WHERE m.role = 'assistant' AND m.finish_reason = 'stop' AND m.id > ?
+        ORDER BY m.id`
+    ).all(cursor);
+
+    let lastStopId = cursor;
+    for (const stop of stops) {
+      const sid = stop.session_id;
+      // walk back to the previous stop in THIS session (the window start), else session start (0)
+      const prevStopId = db.prepare(
+        `SELECT MAX(id) AS p FROM messages
+          WHERE session_id = ? AND role = 'assistant' AND finish_reason = 'stop' AND id < ?`
+      ).get(sid, stop.id)?.p ?? 0;
+
+      if (!sourceAllowed(cfg, stop.source)) { lastStopId = stop.id; continue; }   // privacy skip, still advance
+
+      const turn = assembleTurn(db, sid, prevStopId, stop);
+      if (turn) {
+        if (DRY_RUN) {
+          console.log("─".repeat(72));
+          console.log(`TURN  session=${sid}  stop_id=${stop.id}  source=${stop.source}`);
+          console.log(`  user:      ${truncate(turn.userMessage.replace(/\n/g, " ⏎ "), 160)}`);
+          console.log(`  response:  ${truncate(clean(turn.agentResponse), 200)}  (${turn.agentResponse.length} ch)`);
+          console.log(`  thinking:  ${truncate(turn.reasoning.replace(/\n/g, " · "), 220)}  (${turn.reasoning.length} ch)`);
+        } else {
+          const status = await captureTurn(turn);
+          console.log(`[hermes-watcher] captured stop_id=${stop.id} session=${String(sid).slice(0, 15)} → ${status}`);
+        }
+      }
+      lastStopId = stop.id;
+    }
+    return lastStopId;
+  } finally {
+    db.close();
+  }
+}
+
+// ─── main loop ────────────────────────────────────────────────────────────────────────────────
+async function main() {
+  const boot = loadCaptureConfig();
+  console.log(`[hermes-watcher] ${DRY_RUN ? "DRY-RUN " : ""}watching ${boot.stateDbPath}`);
+  console.log(`[hermes-watcher] sources=${boot.allowAll ? "* (all)" : boot.sources.join(",")}  poll=${boot.pollMs}ms${BACKFILL ? "  (backfill)" : ""}`);
+
+  // --backfill starts at 0; else the persisted cursor wins. If neither, DEFER picking the start
+  // point until state.db first appears, then start forward-only (current max stop-id). This lets a
+  // default-on watcher start BEFORE Hermes exists without crashing or later replaying all history.
+  let cursor = BACKFILL ? 0 : loadCursor();
+  let cursorReady = BACKFILL || cursor > 0;
+  let warnedMissing = false;
+
+  do {
+    const cfg = loadCaptureConfig();              // re-read each pass → TUI changes apply live
+    if (cfg.enabled) {
+      if (!existsSync(cfg.stateDbPath)) {
+        // Default-on, but no Hermes turn-log yet (or Hermes not installed). Wait — never crash;
+        // a harmless idle poll until it appears (or the user toggles capture off in the TUI).
+        if (!warnedMissing) { console.log(`[hermes-watcher] waiting — no Hermes state.db at ${cfg.stateDbPath} yet`); warnedMissing = true; }
+      } else {
+        if (warnedMissing) { console.log(`[hermes-watcher] state.db appeared — starting capture`); warnedMissing = false; }
+        if (!cursorReady) {
+          const db = openRO(cfg.stateDbPath);
+          try { cursor = db.prepare(`SELECT MAX(id) AS m FROM messages WHERE role='assistant' AND finish_reason='stop'`).get()?.m ?? 0; }
+          finally { db.close(); }
+          cursorReady = true;
+          console.log(`[hermes-watcher] capturing forward from cursor=${cursor}`);
+        }
+        try {
+          const next = await pass(cfg, cursor);
+          if (next > cursor) { cursor = next; if (!DRY_RUN) saveCursor(cursor); }
+        } catch (e) {
+          console.error(`[hermes-watcher] pass error: ${e?.message ?? e}`);
+        }
+      }
+    }
+    if (ONCE) break;
+    await new Promise((r) => setTimeout(r, loadCaptureConfig().pollMs));
+  } while (!ONCE);
+}
+
+main().catch((e) => { console.error(`[hermes-watcher] fatal: ${e?.message ?? e}`); process.exit(1); });
+
+export { assembleTurn, sourceAllowed, loadCaptureConfig }; // for testing