mixdog 0.9.2 → 0.9.4

package/src/runtime/memory/lib/recall-format.mjs

@@ -0,0 +1,238 @@
+import { cleanMemoryText } from './memory.mjs'
+
+// Recall query/format helpers extracted verbatim from index.mjs
+// (behavior-preserving). Pure string/date logic plus row rendering.
+
+export function parsePeriod(period, hasQuery) {
+  if (!period && hasQuery) period = '30d'
+  if (!period) return null
+  if (period === 'all') return null
+  if (period === 'last') return { mode: 'last' }
+  // Calendar-day windows: 'today' anchors at local midnight rather than
+  // rolling 24h. Without this, a query asking 'today' at 01:30 would silently
+  // include yesterday's last 22.5h of activity, mislabelling them as
+  // 'today's work'. 'yesterday' is the previous calendar day.
+  if (period === 'today') {
+    const start = new Date()
+    start.setHours(0, 0, 0, 0)
+    return { startMs: start.getTime(), endMs: Date.now() }
+  }
+  if (period === 'yesterday') {
+    const start = new Date()
+    start.setDate(start.getDate() - 1)
+    start.setHours(0, 0, 0, 0)
+    const end = new Date(start)
+    end.setHours(23, 59, 59, 999)
+    return { startMs: start.getTime(), endMs: end.getTime() }
+  }
+  if (period === 'this_week' || period === 'last_week') {
+    // R6 P9: calendar Mon-Sun previous/current week. Mon-start ISO
+    // convention. Replaces R5 rolling 7-14d range which was empty for
+    // sessions where "last week" decisions actually fell on Mon (4/27) of
+    // this week. Precise calendar bounds match natural-language intuition.
+    const d = new Date()
+    d.setHours(0, 0, 0, 0)
+    const dayOfWeek = d.getDay()
+    const daysSinceMon = (dayOfWeek + 6) % 7
+    const thisWeekMon = new Date(d)
+    thisWeekMon.setDate(d.getDate() - daysSinceMon)
+    if (period === 'this_week') {
+      return { startMs: thisWeekMon.getTime(), endMs: Date.now() }
+    }
+    const lastWeekMon = new Date(thisWeekMon)
+    lastWeekMon.setDate(thisWeekMon.getDate() - 7)
+    const lastWeekSunEnd = new Date(thisWeekMon.getTime() - 1)
+    return { startMs: lastWeekMon.getTime(), endMs: lastWeekSunEnd.getTime() }
+  }
+  const relMatch = period.match(/^(\d+)(m|h|d)$/)
+  if (relMatch) {
+    const n = parseInt(relMatch[1])
+    const unit = relMatch[2]
+    const now = new Date()
+    if (unit === 'm') {
+      // Minute granularity is for "resume from the previous turn / pick
+      // up where we left off" style recall — sub-hour windows where 1h
+      // is too coarse. n=0 is invalid (the regex requires \d+ which
+      // matches "0" but a zero-width window returns no rows; leave that
+      // as caller-supplied no-op).
+      const start = new Date(now.getTime() - n * 60_000)
+      return { startMs: start.getTime(), endMs: now.getTime() }
+    }
+    if (unit === 'h') {
+      const start = new Date(now.getTime() - n * 3600_000)
+      return { startMs: start.getTime(), endMs: now.getTime() }
+    }
+    const start = new Date(now)
+    start.setDate(start.getDate() - n)
+    return { startMs: start.getTime(), endMs: now.getTime() }
+  }
+  const rangeMatch = period.match(/^(\d{4}-\d{2}-\d{2})~(\d{4}-\d{2}-\d{2})$/)
+  if (rangeMatch) {
+    return {
+      startMs: Date.parse(rangeMatch[1] + 'T00:00:00'),
+      endMs:   Date.parse(rangeMatch[2] + 'T23:59:59.999'),
+    }
+  }
+  // Time-of-day windows: 'HH:MM~HH:MM' (today) or 'YYYY-MM-DD HH:MM~HH:MM'
+  // (specific day). Covers "this afternoon 12:00-14:00" style recall that the
+  // day-granular date/range forms cannot express. End is inclusive to the
+  // minute (:59.999). An end at or before start returns null (invalid window)
+  // rather than guessing an overnight wrap.
+  const todMatch = period.match(/^(?:(\d{4}-\d{2}-\d{2})[ T])?(\d{1,2}):(\d{2})~(\d{1,2}):(\d{2})$/)
+  if (todMatch) {
+    const [, day, h1, m1, h2, m2] = todMatch
+    const base = day ? new Date(day + 'T00:00:00') : new Date()
+    if (Number.isNaN(base.getTime())) return null
+    const sh = Number(h1), sm = Number(m1), eh = Number(h2), em = Number(m2)
+    if (sh > 23 || eh > 23 || sm > 59 || em > 59) return null
+    const start = new Date(base); start.setHours(sh, sm, 0, 0)
+    const end = new Date(base); end.setHours(eh, em, 59, 999)
+    if (end.getTime() <= start.getTime()) return null
+    return { startMs: start.getTime(), endMs: end.getTime(), exact: true }
+  }
+  const dateMatch = period.match(/^(\d{4}-\d{2}-\d{2})$/)
+  if (dateMatch) {
+    return {
+      startMs: Date.parse(dateMatch[1] + 'T00:00:00'),
+      endMs:   Date.parse(dateMatch[1] + 'T23:59:59.999'),
+      exact: true,
+    }
+  }
+  return null
+}
+
+export function formatTs(tsMs) {
+  const n = Number(tsMs)
+  if (Number.isFinite(n) && n > 1e12) {
+    return new Date(n).toLocaleString('sv-SE').slice(0, 16)
+  }
+  return String(tsMs ?? '').slice(0, 16)
+}
+
+export const CORE_RECALL_STOPWORDS = new Set([
+  'about', 'after', 'again', 'before', 'check', 'color', 'decision', 'decided',
+  'earlier', 'memory', 'previous', 'routing', 'stored', 'tell', 'what',
+])
+
+export function coreRecallTerms(query) {
+  return [...new Set(String(query || '').toLowerCase().match(/[\p{L}\p{N}_-]{4,}/gu) || [])]
+    .filter((term) => !CORE_RECALL_STOPWORDS.has(term))
+    .slice(0, 8)
+}
+
+export function normalizeRecallProjectScope(projectScope) {
+  const raw = String(projectScope || 'common').trim()
+  if (!raw || raw.toLowerCase() === 'common') return null
+  if (raw.toLowerCase() === 'all') return '*'
+  return raw
+}
+
+export function sessionRecallTerms(query) {
+  return [...new Set(String(query || '').toLowerCase().match(/[\p{L}\p{N}_./:-]{2,}/gu) || [])]
+    .filter((term) => !CORE_RECALL_STOPWORDS.has(term))
+    .slice(0, 12)
+}
+
+export function interleaveRawRows(hybridRows, rawRows) {
+  if (!Array.isArray(rawRows) || rawRows.length === 0) return hybridRows
+  const out = []
+  const stride = Math.max(1, Math.round(hybridRows.length / (rawRows.length + 1)))
+  let rawIdx = 0
+  for (let i = 0; i < hybridRows.length; i += 1) {
+    out.push(hybridRows[i])
+    if ((i + 1) % stride === 0 && rawIdx < rawRows.length) {
+      out.push(rawRows[rawIdx])
+      rawIdx += 1
+    }
+  }
+  while (rawIdx < rawRows.length) out.push(rawRows[rawIdx++])
+  return out
+}
+
+export function renderEntryLines(rows) {
+  if (!rows || rows.length === 0) return '(no results)'
+  const lines = []
+  // Bound total emitted lines (roots x members) so a many-member recall can't
+  // inject unbounded output. Per-line content is already capped at 1000 chars;
+  // this caps the line COUNT. Narrow the query (limit/period/projectScope) for more.
+  const RECALL_LINE_CAP = 200
+  let _capped = false
+  outer:
+  for (const r of rows) {
+    const hasMembers = Array.isArray(r.members) && r.members.length > 0
+    if (hasMembers) {
+      // Chunks present: emit each member as its own line. Root row is a
+      // grouping artifact for retrieval — the caller wants the chunk
+      // content (cycle1 raw), not the cycle2-compressed summary.
+      for (const m of r.members) {
+        if (lines.length >= RECALL_LINE_CAP) { _capped = true; break outer }
+        const mTs = formatTs(m.ts)
+        const role = m.role === 'user' ? 'u' : m.role === 'assistant' ? 'a' : (m.role || '?')
+        const content = cleanMemoryText(String(m.content ?? '')).slice(0, 1000)
+        lines.push(`[${mTs}] ${role}: ${content} #${m.id}`)
+      }
+    } else {
+      if (lines.length >= RECALL_LINE_CAP) { _capped = true; break }
+      // No chunks (root not yet chunked by cycle1, or orphan leaf): emit
+      // the row itself in the same shape. element/summary fall back to
+      // raw content when both are absent.
+      const ts = formatTs(r.ts)
+      const element = r.element ?? ''
+      const summary = r.summary ?? ''
+      // Standalone leaf rows (is_root=0, no parent chunks_root resolved
+      // into a `members` list) carry their u/a role just like inline
+      // chunk members — surface it so the format stays consistent across
+      // the two emission paths.
+      const rolePrefix = r.is_root === 0 && r.role
+        ? (r.role === 'user' ? 'u: ' : r.role === 'assistant' ? 'a: ' : `${r.role}: `)
+        : ''
+      const body = element || summary
+        ? `${element}${summary ? ' — ' + summary : ''}`
+        : cleanMemoryText(String(r.content ?? '')).slice(0, 1000)
+      // Unchunked raw leaf (cycle1 hasn't classified it yet): mark it so
+      // callers can tell fresh-but-unprocessed rows from chunked memory.
+      const pendingMark = (r.is_root === 0 && r.chunk_root == null) ? ' [pending]' : ''
+      lines.push(`[${ts}] ${rolePrefix}${body.slice(0, 1000)}${pendingMark} #${r.id}`)
+    }
+  }
+  if (_capped) lines.push(`[recall truncated — showing first ${RECALL_LINE_CAP} lines; narrow the query (limit/period/projectScope) for the rest]`)
+  return lines.join('\n')
+}
+
+// Compact session label for group headers: keep short ids verbatim, shorten
+// long ones to a recognizable tail (ids are typically unique in the suffix —
+// timestamp/counter — not the prefix).
+function shortSessionLabel(sid) {
+  const s = String(sid || '').trim()
+  if (s.length <= 20) return s
+  return `…${s.slice(-16)}`
+}
+
+// Session-grouped rendering for the GLOBAL query-less browse ("what did we
+// work on recently") when the window spans multiple sessions. A flat ts-desc
+// list interleaves sessions into one indistinguishable stream and lets one
+// chatty session crowd the page; grouping keeps each work-unit readable.
+// Group order = newest activity first (rows arrive ts-desc, first-seen wins).
+// The caller's own session (currentSessionId hint) is marked "(current)".
+// Single-session (or session-less) result sets fall through to the flat
+// renderer — no headers when grouping adds nothing.
+export function renderSessionGroupedLines(rows, { currentSessionId } = {}) {
+  if (!rows || rows.length === 0) return '(no results)'
+  const groups = new Map()
+  for (const r of rows) {
+    const sid = String(r?.session_id || '').trim()
+    const key = sid || '(no session)'
+    if (!groups.has(key)) groups.set(key, [])
+    groups.get(key).push(r)
+  }
+  if (groups.size <= 1) return renderEntryLines(rows)
+  const current = String(currentSessionId || '').trim()
+  const parts = []
+  for (const [sid, groupRows] of groups) {
+    const mark = current && sid === current ? ' (current)' : ''
+    const label = sid === '(no session)' ? sid : `session ${shortSessionLabel(sid)}`
+    parts.push(`## ${label}${mark}`)
+    parts.push(renderEntryLines(groupRows))
+  }
+  return parts.join('\n')
+}

package/src/runtime/memory/lib/runtime-fetcher.mjs

@@ -75,13 +75,18 @@ function isUsableAsset(asset) {
 // ---------------------------------------------------------------------------
 
 async function loadManifest(dataDir) {
+  // Bundled manifest FIRST: it always matches the installed mixdog version.
+  // A cached <dataDir>/runtime/manifest.json from an older install must never
+  // shadow it — stale caches caused sha256 mismatches on already-installed
+  // machines after an upgrade. The cache is only a fallback for the rare case
+  // where the bundled file is missing (e.g. a stripped checkout).
+  if (existsSync(BUNDLED_MANIFEST_PATH)) {
+    return JSON.parse(readFileSync(BUNDLED_MANIFEST_PATH, 'utf8'))
+  }
   const runtimeManifestPath = join(dataDir, 'runtime', 'manifest.json')
   if (existsSync(runtimeManifestPath)) {
     try { return JSON.parse(readFileSync(runtimeManifestPath, 'utf8')) } catch {}
   }
-  if (existsSync(BUNDLED_MANIFEST_PATH)) {
-    return JSON.parse(readFileSync(BUNDLED_MANIFEST_PATH, 'utf8'))
-  }
   const res = await fetch(MANIFEST_URL, { signal: AbortSignal.timeout(30_000) })
   if (!res.ok) throw new Error(`[runtime-fetcher] manifest fetch failed: ${res.status} ${res.statusText}`)
   const manifest = await res.json()

package/src/runtime/memory/lib/transcript-ingest.mjs

@@ -0,0 +1,425 @@
+// Transcript ingest cluster, extracted from index.mjs (pass 2).
+//
+// Owns: transcript offset load/persist, JSONL tail ingestion, cwd extraction,
+// timestamp coercion, and the cross-platform transcript watcher. Everything
+// that touched module-level state in index.mjs (db handle, mainConfig-derived
+// data dir, the _transcriptOffsets / _ingestTranscriptTails maps, the persist
+// tail promise) is now closed over inside createTranscriptIngest via injected
+// accessors, so index.mjs keeps ownership of the live db/config lifecycle and
+// this module stays a pure factory with no import-time side effects.
+import fs from 'node:fs'
+import path from 'node:path'
+
+// Pure: coerce a transcript timestamp (seconds, ms, or ISO string) to ms.
+export function parseTsToMs(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value < 1e12 ? value * 1000 : value
+  const parsed = Date.parse(String(value))
+  return Number.isFinite(parsed) ? parsed : Date.now()
+}
+
+// Pure: extract cwd from the transcript file's JSONL rows. Mixdog embeds the
+// session cwd as a top-level `cwd` field on every message row, so scanning the
+// first few lines is reliable on all platforms without slug-decoding ambiguity.
+// Returns undefined when no cwd is found or the extracted path does not exist
+// on disk (falls back to COMMON).
+export function cwdFromTranscriptPath(fp) {
+  let fd
+  try {
+    fd = fs.openSync(fp, 'r')
+    const buf = Buffer.alloc(Math.min(fs.fstatSync(fd).size, 100 * 1024))
+    fs.readSync(fd, buf, 0, buf.length, 0)
+    fs.closeSync(fd)
+    fd = undefined
+    const lines = buf.toString('utf8').split('\n')
+    for (let i = 0; i < Math.min(lines.length, 5); i++) {
+      const line = lines[i].trim()
+      if (!line) continue
+      try {
+        const obj = JSON.parse(line)
+        if (typeof obj.cwd === 'string' && obj.cwd) {
+          const candidate = obj.cwd
+          try { if (fs.statSync(candidate).isDirectory()) return candidate } catch {}
+        }
+      } catch {}
+    }
+  } catch {} finally {
+    if (fd != null) { try { fs.closeSync(fd) } catch {} }
+  }
+  return undefined
+}
+
+// Factory. All live-state coupling is injected:
+//   getDb()            -> current pg-shim db handle (or null pre-init)
+//   loadMeta()         -> Promise<string> raw transcript-offsets meta value
+//   persistMeta(json)  -> Promise<void> writes serialized offsets to meta
+//   projectsRoot()     -> string, mixdogHome()/projects
+//   resolveProjectId(cwd) -> project id | null
+//   firstTextContent / cleanMemoryText -> shared ingest text helpers
+//   log(msg)           -> stderr logger
+//
+// Returns the same surface index.mjs previously exposed as module functions,
+// plus resetOffsets() for stop()'s teardown.
+export function createTranscriptIngest({
+  getDb,
+  loadMeta,
+  persistMeta,
+  projectsRoot,
+  resolveProjectId,
+  firstTextContent,
+  cleanMemoryText,
+  log = () => {},
+}) {
+  let _transcriptOffsets = new Map()
+  /** @type {Map<string, Promise<unknown>>} */
+  const _ingestTranscriptTails = new Map()
+  let _transcriptOffsetsPersistTail = Promise.resolve()
+
+  async function loadTranscriptOffsets() {
+    try {
+      const raw = await loadMeta()
+      const obj = JSON.parse(raw)
+      _transcriptOffsets = new Map(Object.entries(obj))
+    } catch {
+      _transcriptOffsets = new Map()
+    }
+  }
+
+  async function persistTranscriptOffsets() {
+    const run = _transcriptOffsetsPersistTail.catch(() => {}).then(async () => {
+      try {
+        const obj = Object.fromEntries(_transcriptOffsets)
+        await persistMeta(JSON.stringify(obj))
+      } catch (e) {
+        log(`[memory] persist transcript offsets failed: ${e.message}\n`)
+      }
+    })
+    _transcriptOffsetsPersistTail = run.catch(() => {})
+    return run
+  }
+
+  function runTranscriptIngestSerialized(transcriptPath, fn) {
+    const key = path.resolve(transcriptPath)
+    const prev = _ingestTranscriptTails.get(key) ?? Promise.resolve()
+    const run = prev.catch(() => {}).then(fn)
+    _ingestTranscriptTails.set(key, run.catch(() => {}))
+    return run
+  }
+
+  function snapshotTranscriptOffset(transcriptPath) {
+    const stored = _transcriptOffsets.get(transcriptPath)
+    if (!stored) return { bytes: 0, lineIndex: 0 }
+    return { bytes: Number(stored.bytes) || 0, lineIndex: Number(stored.lineIndex) || 0 }
+  }
+
+  async function ingestTranscriptFileImpl(transcriptPath, { cwd } = {}) {
+    const db = getDb()
+    let stat
+    try { stat = await fs.promises.stat(transcriptPath) } catch { return 0 }
+    const sessionUuid = path.basename(transcriptPath, '.jsonl')
+    const prev = snapshotTranscriptOffset(transcriptPath)
+    if (stat.size < prev.bytes) {
+      prev.bytes = 0
+      prev.lineIndex = 0
+    }
+    if (stat.size <= prev.bytes) return 0
+
+    const fh = await fs.promises.open(transcriptPath, 'r')
+    const buf = Buffer.alloc(stat.size - prev.bytes)
+    try {
+      await fh.read(buf, 0, buf.length, prev.bytes)
+    } finally {
+      await fh.close()
+    }
+    const text = buf.toString('utf8')
+
+    const resolvedCwd = typeof cwd === 'string' && cwd ? cwd : cwdFromTranscriptPath(transcriptPath)
+    // No cwd resolved -> classify as COMMON (project_id NULL). Falling back to
+    // process.cwd() would misclassify rows under the service/plugin cwd.
+    const projectId = resolvedCwd ? resolveProjectId(resolvedCwd) : null
+
+    let count = 0
+    let index = prev.lineIndex
+    // Track the byte boundary of the LAST line we fully consumed (parsed +
+    // either inserted or intentionally skipped). On parse failure or
+    // transient insert error we stop and leave the boundary untouched so the
+    // next sweep retries from the same position. This prevents malformed
+    // trailing JSONL (mid-write partial lines) and DB hiccups from being
+    // silently consumed forever.
+    let lastGoodBytes = prev.bytes
+    let lastGoodLineIndex = prev.lineIndex
+    let cursor = 0
+    while (cursor < text.length) {
+      const nl = text.indexOf('\n', cursor)
+      // No trailing newline -> partial line still being written; stop here
+      // without advancing so the rest is re-read once the writer flushes.
+      if (nl === -1) break
+      const rawLine = text.slice(cursor, nl)
+      const consumedBytes = Buffer.byteLength(rawLine, 'utf8') + 1
+      cursor = nl + 1
+      const line = rawLine.replace(/\r$/, '')
+      if (!line) {
+        lastGoodBytes += consumedBytes
+        continue
+      }
+      index += 1
+      let parsed
+      try { parsed = JSON.parse(line) } catch {
+        // Malformed line: do not advance past it; retry on next sweep.
+        index -= 1
+        break
+      }
+      // Transcript lines carry the role either as message.role (legacy) or
+      // as the top-level `type` field ({"type":"assistant","message":{...}}
+      // — the current session-runtime writer). Reading only message.role
+      // silently skipped EVERY line of current-format transcripts, so the
+      // background watcher ingested 0 rows forever.
+      const role = parsed.message?.role
+        ?? ((parsed.type === 'user' || parsed.type === 'assistant') ? parsed.type : undefined)
+      if (role !== 'user' && role !== 'assistant') {
+        lastGoodBytes += consumedBytes
+        lastGoodLineIndex = index
+        continue
+      }
+      const content = firstTextContent(parsed.message?.content)
+      if (!content || !content.trim()) {
+        lastGoodBytes += consumedBytes
+        lastGoodLineIndex = index
+        continue
+      }
+      const cleaned = cleanMemoryText(content)
+      if (!cleaned) {
+        lastGoodBytes += consumedBytes
+        lastGoodLineIndex = index
+        continue
+      }
+      const tsMs = parseTsToMs(parsed.timestamp ?? parsed.ts ?? Date.now())
+      const sourceRef = `transcript:${sessionUuid}#${index}`
+      try {
+        const result = await db.query(
+          `INSERT INTO entries(ts, role, content, source_ref, session_id, source_turn, project_id)
+           VALUES ($1, $2, $3, $4, $5, $6, $7)
+           ON CONFLICT DO NOTHING`,
+          [tsMs, role, cleaned, sourceRef, sessionUuid, index, projectId]
+        )
+        if (Number(result.rowCount ?? result.affectedRows ?? 0) > 0) count += 1
+        lastGoodBytes += consumedBytes
+        lastGoodLineIndex = index
+      } catch (e) {
+        log(`[transcript-watch] insert error (${sourceRef}): ${e.message}\n`)
+        // Transient insert failure: leave the boundary before this line so
+        // the next sweep retries it. Roll back the line counter too.
+        index -= 1
+        break
+      }
+    }
+    _transcriptOffsets.set(transcriptPath, {
+      bytes: lastGoodBytes,
+      lineIndex: lastGoodLineIndex,
+    })
+    await persistTranscriptOffsets()
+    return count
+  }
+
+  async function ingestTranscriptFile(transcriptPath, options = {}) {
+    return runTranscriptIngestSerialized(transcriptPath, () => ingestTranscriptFileImpl(transcriptPath, options))
+  }
+
+  function getOffset(fp) {
+    return _transcriptOffsets.get(fp)
+  }
+
+  function resetOffsets() {
+    _transcriptOffsets = new Map()
+  }
+
+  function initTranscriptWatcher() {
+    const root = projectsRoot()
+    const SAFETY_POLL_MS = 5 * 60_000
+    const DEBOUNCE_MS = 500
+    const watchedFiles = new Map()
+    const pendingByFile = new Map()
+    const watchers = []
+    const intervals = []
+    const polledFiles = new Set()
+    let safetySweepTimeout = null
+
+    function isWatchable(relOrBase) {
+      const base = path.basename(relOrBase)
+      if (!base.endsWith('.jsonl') || base.startsWith('agent-')) return false
+      if (relOrBase.includes('tmp') || relOrBase.includes('cache') || relOrBase.includes('plugins')) return false
+      return true
+    }
+
+    async function ingestOne(fp) {
+      try {
+        if (!fs.existsSync(fp)) return
+        const stat = fs.statSync(fp)
+        const mtime = stat.mtimeMs
+        const prev = watchedFiles.get(fp)
+        if (prev && prev >= mtime) return
+        const n = await ingestTranscriptFile(fp, { cwd: cwdFromTranscriptPath(fp) })
+        // Only mark this mtime as 'consumed' once the persisted offset has
+        // fully advanced past the observed file size. On a transient insert
+        // error (or a malformed trailing line) ingestTranscriptFile leaves
+        // the persisted offset before the failed line for retry; caching
+        // the new mtime unconditionally would suppress the next sweep until
+        // the file mutated again, losing the retry. Leave the cache
+        // untouched on partial advance so the next sweep re-ingests.
+        const off = _transcriptOffsets.get(fp)
+        if (off && off.bytes >= stat.size) {
+          watchedFiles.set(fp, mtime)
+        }
+        if (n > 0) {
+          log(`[transcript-watch] ingested ${n} entries from ${path.basename(fp)}\n`)
+        }
+      } catch (e) {
+        log(`[transcript-watch] ingest error: ${e.message}\n`)
+      }
+    }
+
+    function scheduleIngest(fp) {
+      const existing = pendingByFile.get(fp)
+      if (existing) clearTimeout(existing)
+      const timer = setTimeout(() => {
+        pendingByFile.delete(fp)
+        ingestOne(fp)
+      }, DEBOUNCE_MS)
+      pendingByFile.set(fp, timer)
+    }
+
+    async function discoverActiveTranscripts() {
+      let topLevel
+      try { topLevel = await fs.promises.readdir(root) }
+      catch { return [] }
+      const files = []
+      for (const d of topLevel) {
+        if (d.includes('tmp') || d.includes('cache') || d.includes('plugins')) continue
+        const full = path.join(root, d)
+        let inner
+        try { inner = await fs.promises.readdir(full) } catch { continue }
+        for (const f of inner) {
+          if (!f.endsWith('.jsonl') || f.startsWith('agent-')) continue
+          const fp = path.join(full, f)
+          try {
+            const stat = await fs.promises.stat(fp)
+            files.push({ path: fp, mtime: stat.mtimeMs })
+          } catch {}
+        }
+      }
+      const cutoff = Date.now() - 30 * 60_000
+      return files.filter(f => f.mtime > cutoff)
+    }
+
+    async function safetySweep() {
+      try {
+        const active = await discoverActiveTranscripts()
+        for (const { path: fp } of active) ingestOne(fp)
+      } catch (e) {
+        log(`[transcript-watch] safety sweep error: ${e.message}\n`)
+      }
+    }
+
+    safetySweepTimeout = setTimeout(safetySweep, 3_000)
+
+    // fs.watch({recursive}) is only reliable on win32.
+    // darwin: recursive option unreliable — use flat watch per-entry (glob dirs at start).
+    // linux/WSL: recursive not supported — use fs.watchFile polling per file found via
+    //   the safety sweep, or fall back entirely to safety sweep.
+    if (process.platform === 'win32') {
+      try {
+        const watcher = fs.watch(root, { recursive: true, persistent: true }, (_event, filename) => {
+          if (!filename) return
+          if (!isWatchable(filename)) return
+          const fp = path.join(root, filename)
+          scheduleIngest(fp)
+        })
+        watcher.on('error', (err) => {
+          log(`[transcript-watch] fs.watch error: ${err.message}\n`)
+        })
+        watchers.push(watcher)
+        log(`[transcript-watch] fs.watch(recursive) active on ${root}\n`)
+      } catch (e) {
+        log(`[transcript-watch] fs.watch setup failed: ${e.message} — relying on safety sweep only\n`)
+      }
+      intervals.push(setInterval(safetySweep, SAFETY_POLL_MS))
+    } else if (process.platform === 'darwin') {
+      // Flat watch: register a non-recursive watcher on each immediate subdirectory.
+      // New subdirs are picked up on the next safety sweep cycle.
+      try {
+        const registerFlat = (dir) => {
+          try {
+            const w = fs.watch(dir, { persistent: true }, (_event, filename) => {
+              if (!filename) return
+              const fp = path.join(dir, filename)
+              if (!isWatchable(fp)) return
+              scheduleIngest(fp)
+            })
+            w.on('error', () => { /* ignore individual dir errors */ })
+            watchers.push(w)
+          } catch { /* dir may not exist yet */ }
+        }
+        registerFlat(root)
+        try {
+          for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+            if (entry.isDirectory()) registerFlat(path.join(root, entry.name))
+          }
+        } catch { /* best effort */ }
+        log(`[transcript-watch] flat fs.watch active on ${root} (darwin)\n`)
+      } catch (e) {
+        log(`[transcript-watch] flat watch setup failed: ${e.message} — relying on safety sweep only\n`)
+      }
+      intervals.push(setInterval(safetySweep, SAFETY_POLL_MS))
+    } else {
+      // linux/WSL: fs.watch recursive is unsupported. Use fs.watchFile polling for
+      // individual files surfaced by the safety sweep, in addition to the sweep itself.
+      log(`[transcript-watch] linux/WSL — using safety sweep + fs.watchFile polling (no recursive watch)\n`)
+      // Wrap by reassigning the closure-captured reference is not possible here;
+      // instead, register watchFile inside the safety sweep callback by intercepting
+      // active file list after each sweep.  The interval already calls safetySweep
+      // which calls ingestOne; watchFile additions happen as a side-effect of the sweep.
+      const _patchedSweep = async () => {
+        try {
+          const active = await discoverActiveTranscripts()
+          for (const { path: fp } of active) {
+            if (!polledFiles.has(fp)) {
+              polledFiles.add(fp)
+              fs.watchFile(fp, { persistent: false, interval: 2000 }, () => {
+                if (isWatchable(fp)) scheduleIngest(fp)
+              })
+            }
+            ingestOne(fp)
+          }
+        } catch (e) {
+          log(`[transcript-watch] linux sweep error: ${e.message}\n`)
+        }
+      }
+      // Replace the safety sweep interval with the patched version.
+      intervals.push(setInterval(_patchedSweep, SAFETY_POLL_MS))
+    }
+
+    return {
+      stop() {
+        if (safetySweepTimeout) { clearTimeout(safetySweepTimeout); safetySweepTimeout = null }
+        for (const t of pendingByFile.values()) { try { clearTimeout(t) } catch {} }
+        pendingByFile.clear()
+        for (const i of intervals) { try { clearInterval(i) } catch {} }
+        intervals.length = 0
+        for (const w of watchers) { try { w.close() } catch {} }
+        watchers.length = 0
+        for (const fp of polledFiles) { try { fs.unwatchFile(fp) } catch {} }
+        polledFiles.clear()
+      },
+    }
+  }
+
+  return {
+    loadTranscriptOffsets,
+    persistTranscriptOffsets,
+    ingestTranscriptFile,
+    cwdFromTranscriptPath,
+    parseTsToMs,
+    initTranscriptWatcher,
+    getOffset,
+    resetOffsets,
+  }
+}