agentquad 0.3.0

package/src/templates/claude-hooks/notify.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// quadtodo-hook-version: 2
+/**
+ * AgentQuad Claude Code hook —— 把 PTY 内 Claude Code 的状态事件转推到微信。
+ *
+ * 调用约定：
+ *   - argv[2] = 事件名: stop | notification | session-end
+ *   - stdin = Claude Code 注入的 hook payload（JSON 文本，可空）
+ *   - env: QUADTODO_SESSION_ID  (空 = 非 AgentQuad 启动的 Claude Code，立刻 exit 0)
+ *          QUADTODO_TARGET_USER (微信 peer id)
+ *          QUADTODO_TODO_ID
+ *          QUADTODO_TODO_TITLE
+ *
+ * 故障策略：失败一律静默。这个脚本绝不能阻塞 Claude Code。
+ * - 没注 env → 仍然记日志（"no env"），exit 0
+ * - AgentQuad 没起 / 网络失败 → catch 后记日志，exit 0
+ * - JSON 解析失败 → 当作空 payload 继续
+ *
+ * Debug log: 写到 ~/.agentquad/claude-hooks/hook.log，记每次 fire。
+ * 这样能 100% 区分"hook 没 fire" vs "fire 了但 AgentQuad 没收到"。
+ *
+ * 这个文件是模板源；安装器会拷贝到 ~/.agentquad/claude-hooks/notify.js。
+ * 顶部 `quadtodo-hook-version` 行用于版本比对，升级 AgentQuad 时会自动覆盖旧脚本（带备份）。
+ * 注意：脚本独立运行（不能 import config.js）。LOG_PATH 用 import.meta.url 派生，
+ * 跟随脚本所在目录，自动适配 ~/.agentquad / ~/.quadtodo（legacy）。
+ */
+import { appendFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const LOG_PATH = join(dirname(fileURLToPath(import.meta.url)), 'hook.log')
+
+function logLine(obj) {
+  try {
+    appendFileSync(LOG_PATH, JSON.stringify({ ts: new Date().toISOString(), ...obj }) + '\n', 'utf8')
+  } catch { /* ignore — log 失败也不能阻塞 */ }
+}
+
+const event = (process.argv[2] || 'unknown').toLowerCase()
+const SESSION_ID = process.env.QUADTODO_SESSION_ID
+if (!SESSION_ID) {
+  logLine({ event, status: 'skipped_no_env', argv: process.argv.slice(2) })
+  process.exit(0)
+}
+
+const QUADTODO_URL = process.env.QUADTODO_URL || 'http://127.0.0.1:5677'
+const ENDPOINT = `${QUADTODO_URL}/api/openclaw/hook`
+logLine({ event, status: 'fired', sessionId: SESSION_ID, todoTitle: process.env.QUADTODO_TODO_TITLE })
+
+let raw = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => {
+  raw += chunk
+  // 防止超大 payload 把这个进程占内存
+  if (raw.length > 64 * 1024) raw = raw.slice(0, 64 * 1024)
+})
+process.stdin.on('end', send)
+// 没有 stdin 也要发（例如 SessionEnd 可能不带 payload）
+setTimeout(() => { if (!sent) send() }, 1500).unref?.()
+
+let sent = false
+async function send() {
+  if (sent) return
+  sent = true
+
+  let hookPayload = null
+  if (raw.trim()) {
+    try { hookPayload = JSON.parse(raw) } catch { hookPayload = { _raw: raw.slice(0, 240) } }
+  }
+
+  const body = JSON.stringify({
+    event,
+    sessionId: SESSION_ID,
+    targetUserId: process.env.QUADTODO_TARGET_USER || null,
+    todoId: process.env.QUADTODO_TODO_ID || null,
+    todoTitle: process.env.QUADTODO_TODO_TITLE || null,
+    hookPayload,
+  })
+
+  try {
+    // 30s timeout：openclaw CLI shell-out 实测 4-6s，留足余量；
+    // Claude Code 默认等 hook 60s，所以 30s 安全。
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), 30_000)
+    timer.unref?.()
+    const res = await fetch(ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+      signal: ctrl.signal,
+    })
+    clearTimeout(timer)
+    if (res.ok) {
+      const data = await res.json().catch(() => null)
+      logLine({ event, status: 'sent', sessionId: SESSION_ID, action: data?.action, reason: data?.reason })
+    } else {
+      const text = await res.text().catch(() => '')
+      logLine({ event, status: 'http_error', code: res.status, body: text.slice(0, 200) })
+    }
+  } catch (e) {
+    logLine({ event, status: 'fetch_error', error: e?.message || String(e) })
+  }
+}

package/src/transcript.js

@@ -0,0 +1,305 @@
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import xtermHeadless from '@xterm/headless'
+import { cursorTranscriptPath } from './pty.js'
+
+const { Terminal } = xtermHeadless
+
+const CLAUDE_PROJECTS_DIR = join(homedir(), '.claude', 'projects')
+const CODEX_SESSIONS_DIR = join(homedir(), '.codex', 'sessions')
+function claudeProjectHash(absPath) {
+  // Claude Code 在写 JSONL 路径时会先规范化 cwd（去掉尾斜杠）
+  // 若不做同样处理，带尾斜杠的 cwd 会被 hash 成比实际路径多一个 '-' 的目录名，导致找不到 JSONL
+  // 回退到 ptylog（"日志降级"）的 UX 退化
+  const normalized = String(absPath).replace(/\/+$/, '') || '/'
+  return normalized.replace(/\//g, '-')
+}
+
+// Replay ANSI byte stream through a headless xterm so cursor motions (CUF/CUP/CHA…)
+// become real spaces rather than being deleted — TUIs like Claude Code render status
+// bars by moving the cursor between words instead of writing ASCII spaces.
+export function renderPtyLogText(raw) {
+  return new Promise((resolve) => {
+    const term = new Terminal({
+      cols: 200,
+      rows: 50,
+      scrollback: 50000,
+      allowProposedApi: true,
+      convertEol: true,
+    })
+    term.write(String(raw), () => {
+      const buf = term.buffer.active
+      const lines = []
+      for (let i = 0; i < buf.length; i++) {
+        const line = buf.getLine(i)
+        lines.push(line ? line.translateToString(true) : '')
+      }
+      while (lines.length && lines[lines.length - 1] === '') lines.pop()
+      term.dispose()
+      resolve(lines.join('\n'))
+    })
+  })
+}
+
+function parseClaudeJsonl(filePath) {
+  const raw = readFileSync(filePath, 'utf8')
+  const turns = []
+  for (const line of raw.split('\n')) {
+    if (!line) continue
+    let obj
+    try { obj = JSON.parse(line) } catch { continue }
+    if (obj.type !== 'user' && obj.message?.role !== 'assistant' && obj.type !== 'assistant') continue
+    const ts = obj.timestamp ? Date.parse(obj.timestamp) : undefined
+    const msg = obj.message
+    if (!msg) continue
+
+    if (obj.type === 'user') {
+      if (typeof msg.content === 'string') {
+        turns.push({ role: 'user', content: msg.content, timestamp: ts })
+      } else if (Array.isArray(msg.content)) {
+        for (const c of msg.content) {
+          if (c.type === 'tool_result') {
+            const text = Array.isArray(c.content)
+              ? c.content.map(x => x.text || '').join('\n')
+              : (typeof c.content === 'string' ? c.content : JSON.stringify(c.content))
+            turns.push({ role: 'tool_result', content: text, toolUseId: c.tool_use_id, timestamp: ts })
+          } else if (c.type === 'text') {
+            turns.push({ role: 'user', content: c.text, timestamp: ts })
+          }
+        }
+      }
+    } else if (msg.role === 'assistant' && Array.isArray(msg.content)) {
+      for (const c of msg.content) {
+        if (c.type === 'text' && c.text) {
+          turns.push({ role: 'assistant', content: c.text, timestamp: ts })
+        } else if (c.type === 'thinking' && c.thinking) {
+          turns.push({ role: 'thinking', content: c.thinking, timestamp: ts })
+        } else if (c.type === 'tool_use') {
+          turns.push({
+            role: 'tool_use',
+            toolName: c.name,
+            toolUseId: c.id,
+            content: typeof c.input === 'string' ? c.input : JSON.stringify(c.input, null, 2),
+            timestamp: ts,
+          })
+        }
+      }
+    }
+  }
+  return turns
+}
+
+function findClaudeFile(cwd, nativeSessionId) {
+  if (!cwd || !nativeSessionId) return null
+  const projDir = join(CLAUDE_PROJECTS_DIR, claudeProjectHash(cwd))
+  const file = join(projDir, `${nativeSessionId}.jsonl`)
+  return existsSync(file) ? file : null
+}
+
+function findCodexFile(nativeSessionId) {
+  if (!nativeSessionId || !existsSync(CODEX_SESSIONS_DIR)) return null
+  // Walk yyyy/mm/dd subdirs
+  const years = readdirSync(CODEX_SESSIONS_DIR).filter(y => /^\d{4}$/.test(y))
+  for (const y of years) {
+    const yDir = join(CODEX_SESSIONS_DIR, y)
+    for (const m of readdirSync(yDir).filter(x => /^\d{2}$/.test(x))) {
+      const mDir = join(yDir, m)
+      for (const d of readdirSync(mDir).filter(x => /^\d{2}$/.test(x))) {
+        const dDir = join(mDir, d)
+        for (const f of readdirSync(dDir)) {
+          if (f.includes(nativeSessionId) && f.endsWith('.jsonl')) {
+            return join(dDir, f)
+          }
+        }
+      }
+    }
+  }
+  return null
+}
+
+function parseCodexJsonl(filePath) {
+  const raw = readFileSync(filePath, 'utf8')
+  const turns = []
+  for (const line of raw.split('\n')) {
+    if (!line) continue
+    let obj
+    try { obj = JSON.parse(line) } catch { continue }
+    if (obj.type !== 'response_item') continue
+    const p = obj.payload
+    if (!p) continue
+    const ts = obj.timestamp ? Date.parse(obj.timestamp) : undefined
+
+    if (p.type === 'message') {
+      if (p.role === 'developer' || p.role === 'system') continue
+      const text = Array.isArray(p.content)
+        ? p.content.map(c => c.text || '').join('\n').trim()
+        : ''
+      if (!text) continue
+      // Filter out environment_context auto-injection
+      if (p.role === 'user' && /^<environment_context>/.test(text)) continue
+      turns.push({
+        role: p.role === 'assistant' ? 'assistant' : 'user',
+        content: text,
+        timestamp: ts,
+      })
+    } else if (p.type === 'function_call') {
+      let inputStr = p.arguments
+      try { inputStr = JSON.stringify(JSON.parse(p.arguments), null, 2) } catch {}
+      turns.push({
+        role: 'tool_use',
+        toolName: p.name,
+        toolUseId: p.call_id,
+        content: inputStr,
+        timestamp: ts,
+      })
+    } else if (p.type === 'function_call_output') {
+      turns.push({
+        role: 'tool_result',
+        toolUseId: p.call_id,
+        content: typeof p.output === 'string' ? p.output : JSON.stringify(p.output),
+        timestamp: ts,
+      })
+    } else if (p.type === 'reasoning') {
+      // Codex reasoning is encrypted by default — skip unless there's visible summary
+      const summary = Array.isArray(p.summary) ? p.summary.map(s => s.text || s).join('\n').trim() : ''
+      if (summary) turns.push({ role: 'thinking', content: summary, timestamp: ts })
+    }
+  }
+  return turns
+}
+
+function findCursorFile(cwd, nativeSessionId) {
+  if (!cwd) return null
+  if (nativeSessionId) {
+    const file = cursorTranscriptPath(cwd, nativeSessionId)
+    if (file && existsSync(file)) return file
+    // nativeSessionId 已知但文件尚不存在（cursor 还没写第一行）→ 返回 null，
+    // 不要 fallback 到 mtime 搜索，否则会展示上一个 cursor 会话的历史内容。
+    return null
+  }
+  // 拿一个临时 chatId 推目录路径，再 dirname 两次 → agent-transcripts 根。
+  // 这样不用复制 encodeCursorCwd 实现，避免和 pty.js 漂移。
+  const probe = cursorTranscriptPath(cwd, '__probe__')
+  if (!probe) return null
+  const transcriptsDir = join(probe, '..', '..')
+  // 兜底：cursor-agent create-chat 偶发失败导致 nativeSessionId 没被存进 DB。
+  // 这种情况下按 mtime 选 cwd 下最近的 chatId 目录，能让正在跑的会话也展示出对话。
+  if (!existsSync(transcriptsDir)) return null
+  let best = null
+  let bestMtime = 0
+  let entries
+  try { entries = readdirSync(transcriptsDir, { withFileTypes: true }) } catch { return null }
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue
+    const chatId = ent.name
+    const file = join(transcriptsDir, chatId, `${chatId}.jsonl`)
+    if (!existsSync(file)) continue
+    let st
+    try { st = statSync(file) } catch { continue }
+    if (st.mtimeMs > bestMtime) { bestMtime = st.mtimeMs; best = file }
+  }
+  return best
+}
+
+// cursor jsonl 格式：每行 {"role":"user|assistant","message":{"content":[{type:'text'|'tool_use'|'tool_result', ...}]}}
+// 没有顶层 timestamp，沿用文件 mtime 作为兜底。
+function parseCursorJsonl(filePath) {
+  const raw = readFileSync(filePath, 'utf8')
+  const ts = (() => { try { return statSync(filePath).mtimeMs } catch { return undefined } })()
+  const turns = []
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue
+    let obj
+    try { obj = JSON.parse(line) } catch { continue }
+    const role = obj.role || obj.message?.role
+    if (!role) continue
+    const content = obj.message?.content
+    if (typeof content === 'string') {
+      if (content.trim()) turns.push({ role, content, timestamp: ts })
+      continue
+    }
+    if (!Array.isArray(content)) continue
+    if (role === 'assistant') {
+      for (const c of content) {
+        if (!c || typeof c !== 'object') continue
+        if (c.type === 'text' && c.text) {
+          turns.push({ role: 'assistant', content: c.text, timestamp: ts })
+        } else if (c.type === 'thinking' && (c.thinking || c.text)) {
+          turns.push({ role: 'thinking', content: c.thinking || c.text, timestamp: ts })
+        } else if (c.type === 'tool_use') {
+          turns.push({
+            role: 'tool_use',
+            toolName: c.name || 'tool',
+            toolUseId: c.id,
+            content: typeof c.input === 'string' ? c.input : JSON.stringify(c.input ?? {}, null, 2),
+            timestamp: ts,
+          })
+        }
+      }
+    } else if (role === 'user') {
+      for (const c of content) {
+        if (!c || typeof c !== 'object') continue
+        if (c.type === 'text' && c.text) {
+          turns.push({ role: 'user', content: c.text, timestamp: ts })
+        } else if (c.type === 'tool_result') {
+          const text = Array.isArray(c.content)
+            ? c.content.map(x => x.text || '').join('\n')
+            : (typeof c.content === 'string' ? c.content : JSON.stringify(c.content ?? ''))
+          turns.push({ role: 'tool_result', content: text, toolUseId: c.tool_use_id, timestamp: ts })
+        }
+      }
+    }
+  }
+  return turns
+}
+
+async function loadFromPtyLog(logDir, sessionId) {
+  if (!logDir || !sessionId) return null
+  const file = join(logDir, `${sessionId}.log`)
+  if (!existsSync(file)) return null
+  const raw = readFileSync(file, 'utf8')
+  const content = await renderPtyLogText(raw)
+  return [{ role: 'raw', content, timestamp: statSync(file).mtimeMs }]
+}
+
+async function loadFromLiveOutputHistory(outputHistory, timestamp) {
+  if (!Array.isArray(outputHistory) || outputHistory.length === 0) return null
+  const raw = outputHistory.join('')
+  if (!raw) return null
+  const content = await renderPtyLogText(raw)
+  return [{ role: 'raw', content, timestamp: timestamp || Date.now() }]
+}
+
+/**
+ * @param {{ tool: 'claude'|'codex', nativeSessionId?: string|null, cwd?: string|null, sessionId: string, logDir?: string|null, liveOutputHistory?: string[]|null, liveTimestamp?: number|null }} opts
+ * @returns {Promise<{ source: 'jsonl'|'ptylog'|'empty', turns: Array<object>, filePath: string|null }>}
+ */
+export async function loadTranscript({ tool, nativeSessionId, cwd, sessionId, logDir, liveOutputHistory, liveTimestamp }) {
+  try {
+    let filePath = null
+    if (tool === 'claude' && nativeSessionId && cwd) {
+      filePath = findClaudeFile(cwd, nativeSessionId)
+      if (filePath) {
+        return { source: 'jsonl', turns: parseClaudeJsonl(filePath), filePath }
+      }
+    } else if (tool === 'codex' && nativeSessionId) {
+      filePath = findCodexFile(nativeSessionId)
+      if (filePath) {
+        return { source: 'jsonl', turns: parseCodexJsonl(filePath), filePath }
+      }
+    } else if (tool === 'cursor' && cwd) {
+      filePath = findCursorFile(cwd, nativeSessionId)
+      if (filePath) {
+        return { source: 'jsonl', turns: parseCursorJsonl(filePath), filePath }
+      }
+    }
+  } catch (e) {
+    console.warn('[transcript] parse failed:', e.message)
+  }
+  const ptyTurns = await loadFromPtyLog(logDir, sessionId)
+  if (ptyTurns) return { source: 'ptylog', turns: ptyTurns, filePath: null }
+  const liveTurns = await loadFromLiveOutputHistory(liveOutputHistory, liveTimestamp)
+  if (liveTurns) return { source: 'ptylog', turns: liveTurns, filePath: null }
+  return { source: 'empty', turns: [], filePath: null }
+}

package/src/transcripts/blocks.js

@@ -0,0 +1,56 @@
+/**
+ * Shared content-block helpers for Claude / Codex transcript renderers.
+ *
+ * 历史上 src/claude-transcript.js (Stop hook 用) 和 src/transcripts/scanner.js (历史会话找回的索引/预览用)
+ * 各写了一份 block→text 逻辑，scanner 那一份只挑 text 字段，遇到 tool_use / tool_result 就静默丢失整轮，
+ * 导致预览里看不到夹在工具调用之间的 user 输入。这里把渲染逻辑统一到一处，两边共用。
+ */
+
+/** 把 message.content 拍平成 array<block>，无论它是 string、array 还是缺省。 */
+export function normalizeContent(content) {
+  if (!content) return []
+  if (typeof content === 'string') return [{ type: 'text', text: content }]
+  if (Array.isArray(content)) return content
+  return []
+}
+
+/** 把单个 content block 渲染成人类可读文本。 */
+export function blockToText(block, opts = {}) {
+  if (!block || typeof block !== 'object') return ''
+  if (block.type === 'text') return String(block.text || '')
+  // codex 的 message.content 块可能是 {type:'input_text'|'output_text', text} 或裸 {text}
+  if (block.type === 'input_text' || block.type === 'output_text') return String(block.text || '')
+  if (!block.type && typeof block.text === 'string') return String(block.text)
+  if (block.type === 'tool_use') {
+    if (opts.includeToolUse === false) return ''
+    const name = block.name || 'tool'
+    const input = block.input
+    let summary = ''
+    if (input && typeof input === 'object') {
+      const cmd = input.command || input.cmd
+      const fp = input.file_path || input.path || input.filePath
+      const url = input.url
+      const pat = input.pattern || input.query
+      const desc = input.description
+      if (cmd) summary = String(cmd).slice(0, 200)
+      else if (fp) summary = String(fp).slice(0, 200)
+      else if (url) summary = String(url).slice(0, 200)
+      else if (pat) summary = String(pat).slice(0, 200)
+      else if (desc) summary = String(desc).slice(0, 120)
+      else summary = JSON.stringify(input).slice(0, 200)
+    }
+    return `🔧 ${name}${summary ? ': ' + summary : ''}`
+  }
+  if (block.type === 'tool_result') {
+    if (!opts.includeToolResult) return ''
+    const c = block.content
+    let text = ''
+    if (typeof c === 'string') text = c
+    else if (Array.isArray(c)) text = c.map((b) => b?.text || JSON.stringify(b)).join('\n')
+    const max = opts.toolResultMaxChars || 300
+    if (text.length > max) text = text.slice(0, max) + ` …(${text.length - max} more chars)`
+    return `📋 result: ${text}`
+  }
+  if (block.type === 'thinking') return ''
+  return ''
+}

package/src/transcripts/index.js

@@ -0,0 +1,222 @@
+import fs from 'node:fs'
+import { listTranscriptFiles, parseTranscriptFile, DEFAULT_CLAUDE_DIR, DEFAULT_CODEX_DIR, DEFAULT_CURSOR_DIR } from './scanner.js'
+import { indexFile } from './indexer.js'
+import { collectOrphans, autoMatch } from './matcher.js'
+
+export { DEFAULT_CLAUDE_DIR, DEFAULT_CODEX_DIR, DEFAULT_CURSOR_DIR }
+
+export function createTranscriptsService({ db, listTodos, updateTodo, dirs = {} } = {}) {
+  const claudeDir = dirs.claude || DEFAULT_CLAUDE_DIR
+  const codexDir = dirs.codex || DEFAULT_CODEX_DIR
+  // 默认只在生产路径下（caller 没有 override claude/codex）才扫 ~/.cursor/projects；
+  // 测试里都传了 fixture 目录，cursor 自动跟随 disabled，避免把用户真实数据吃进来。
+  const cursorDir = dirs.cursor !== undefined
+    ? dirs.cursor
+    : (dirs.claude || dirs.codex ? null : DEFAULT_CURSOR_DIR)
+
+  function applyBindingToTodo(todoId, { nativeId, tool, startedAt, endedAt }, sessionIdHint) {
+    const todo = listTodos().find(t => t.id === todoId)
+    if (!todo) return null
+    const sessions = Array.isArray(todo.aiSessions) ? [...todo.aiSessions] : []
+
+    // Remove any existing session on this todo that already holds this native id (dedup)
+    const filtered = sessions.filter(s => !(s?.nativeSessionId === nativeId && s?.tool === tool))
+
+    let targetIdx = -1
+    if (sessionIdHint) targetIdx = filtered.findIndex(s => s?.sessionId === sessionIdHint)
+    if (targetIdx === -1) targetIdx = filtered.findIndex(s => !s?.nativeSessionId && s?.tool === tool)
+
+    const baseTs = startedAt || Date.now()
+    const newSession = targetIdx >= 0 ? { ...filtered[targetIdx] } : {
+      sessionId: `imported-${nativeId}`,
+      tool,
+      status: 'done',
+      startedAt: baseTs,
+      prompt: '',
+      label: '',
+    }
+    newSession.nativeSessionId = nativeId
+    newSession.tool = tool
+    newSession.source = 'imported'
+    if (!newSession.startedAt) newSession.startedAt = baseTs
+    if (!newSession.completedAt) newSession.completedAt = endedAt || baseTs
+    if (!newSession.status || newSession.status === 'running' || newSession.status === 'idle' || newSession.status === 'pending_confirm') {
+      newSession.status = 'done'
+    }
+
+    if (targetIdx >= 0) filtered[targetIdx] = newSession
+    else filtered.push(newSession)
+
+    updateTodo(todoId, { aiSessions: filtered })
+    return newSession.sessionId
+  }
+
+  function removeBindingFromTodo(todoId, nativeId, tool) {
+    const todo = listTodos().find(t => t.id === todoId)
+    if (!todo) return
+    const sessions = Array.isArray(todo.aiSessions) ? todo.aiSessions : []
+    const next = sessions.map(s => {
+      if (s?.nativeSessionId === nativeId && s?.tool === tool) {
+        if (s.source === 'imported') return null
+        return { ...s, nativeSessionId: null }
+      }
+      return s
+    }).filter(Boolean)
+    updateTodo(todoId, { aiSessions: next })
+  }
+
+  async function scanFull() {
+    return scan({ mode: 'full' })
+  }
+
+  async function scanIncremental() {
+    return scan({ mode: 'incremental' })
+  }
+
+  async function scan({ mode }) {
+    if (db.raw && db.raw.open === false) return { newFiles: 0, indexed: 0, autoBound: 0, unbound: 0 }
+    const disk = listTranscriptFiles({ claudeDir, codexDir, cursorDir: cursorDir || undefined })
+    const diskByPath = new Map(disk.map(f => [f.jsonlPath, f]))
+    const dbFiles = db.listTranscriptFilesMeta()
+    const dbByPath = new Map(dbFiles.map(r => [r.jsonl_path, r]))
+
+    // delete missing files
+    for (const r of dbFiles) {
+      if (!diskByPath.has(r.jsonl_path)) db.deleteTranscriptFile(r.jsonl_path)
+    }
+
+    let indexed = 0
+    let newFiles = 0
+    for (const f of disk) {
+      const existing = dbByPath.get(f.jsonlPath)
+      const missingUsage = existing && existing.input_tokens == null && existing.output_tokens == null
+      const dirty = mode === 'full' || !existing || existing.size !== f.size || existing.mtime !== f.mtime || missingUsage
+      if (!dirty) continue
+      if (!existing) newFiles++
+      const row = await indexFile(db, f)
+      if (row) indexed++
+    }
+
+    const autoBound = await autoBindUnbound()
+    const unbound = db.countUnboundTranscripts()
+    return { newFiles, indexed, autoBound, unbound }
+  }
+
+  async function autoBindUnbound() {
+    const unbound = db.listUnboundTranscriptFiles()
+    if (!unbound.length) return 0
+    const todos = listTodos()
+
+    // Pass 1（直连）：transcript_files.native_id 直接命中 todo.aiSessions[].nativeSessionId
+    // AgentQuad 启动的会话都走这条，避免依赖 cwd+time+prompt 的模糊匹配
+    const nativeToTodo = new Map()
+    for (const t of todos) {
+      for (const s of (t.aiSessions || [])) {
+        if (s?.nativeSessionId && s?.tool) {
+          nativeToTodo.set(`${s.tool}:${s.nativeSessionId}`, t.id)
+        }
+      }
+    }
+    const remaining = []
+    let directBound = 0
+    for (const f of unbound) {
+      const hit = f.native_id ? nativeToTodo.get(`${f.tool}:${f.native_id}`) : null
+      if (hit) {
+        db.setTranscriptBound(f.id, hit)
+        directBound++
+      } else {
+        remaining.push(f)
+      }
+    }
+
+    // Pass 2（fuzzy）：历史遗留、外部工具启动的会话没有 nativeSessionId 记到 todo 上，才走 cwd+time+prompt
+    const orphans = collectOrphans(todos)
+    let fuzzyBound = 0
+    if (orphans.length && remaining.length) {
+      const pairs = autoMatch(remaining, orphans)
+      for (const p of pairs) {
+        const file = db.getTranscriptFile(p.fileId)
+        if (!file) continue
+        applyBindingToTodo(p.todoId, {
+          nativeId: p.nativeId,
+          tool: file.tool,
+          startedAt: file.started_at,
+          endedAt: file.ended_at,
+        }, p.sessionId)
+        db.setTranscriptBound(p.fileId, p.todoId)
+        fuzzyBound++
+      }
+    }
+    return directBound + fuzzyBound
+  }
+
+  function search(opts) {
+    return db.searchTranscripts(opts || {})
+  }
+
+  async function preview(fileId, { offset = 0, limit = 200 } = {}) {
+    const f = db.getTranscriptFile(fileId)
+    if (!f) return null
+    // preview 模式：包含 tool_use / tool_result 摘要，过滤 isMeta（保留 isSidechain，
+    // 否则 subagent transcript 文件会变成空预览）。
+    // index 模式（默认）保持纯文本以避免污染 FTS。
+    const parsed = await parseTranscriptFile(f.tool, f.jsonl_path, { preview: true })
+    return {
+      file: f,
+      turns: parsed.turns.slice(offset, offset + limit),
+      totalTurns: parsed.turns.length,
+    }
+  }
+
+  function bind(fileId, todoId, { force = false } = {}) {
+    const file = db.getTranscriptFile(fileId)
+    if (!file) return { ok: false, code: 'NOT_FOUND' }
+    if (!file.native_id) return { ok: false, code: 'NO_NATIVE_ID' }
+
+    // uniqueness: check if another transcript_files row has the same native_id+tool already bound elsewhere
+    const twin = db.findTranscriptByNative(file.native_id, file.tool)
+    // also check todo-side: any other todo already hosts this nativeId
+    const todos = listTodos()
+    const existingHost = todos.find(t => t.id !== todoId && (t.aiSessions || []).some(s => s?.tool === file.tool && s?.nativeSessionId === file.native_id))
+
+    if ((file.bound_todo_id && file.bound_todo_id !== todoId) || existingHost) {
+      if (!force) {
+        return { ok: false, code: 'ALREADY_BOUND', currentTodoId: file.bound_todo_id || existingHost?.id || null }
+      }
+      const prevTodoId = file.bound_todo_id || existingHost?.id
+      if (prevTodoId) removeBindingFromTodo(prevTodoId, file.native_id, file.tool)
+    }
+
+    applyBindingToTodo(todoId, {
+      nativeId: file.native_id,
+      tool: file.tool,
+      startedAt: file.started_at,
+      endedAt: file.ended_at,
+    })
+    db.setTranscriptBound(fileId, todoId)
+    return { ok: true }
+  }
+
+  function unbind(fileId) {
+    const file = db.getTranscriptFile(fileId)
+    if (!file) return { ok: false, code: 'NOT_FOUND' }
+    if (file.bound_todo_id) {
+      removeBindingFromTodo(file.bound_todo_id, file.native_id, file.tool)
+      db.setTranscriptBound(fileId, null)
+    }
+    return { ok: true }
+  }
+
+  return {
+    scanFull,
+    scanIncremental,
+    search,
+    preview,
+    bind,
+    unbind,
+    getStats: () => ({ unboundCount: db.countUnboundTranscripts() }),
+    getFile: (id) => db.getTranscriptFile(id),
+    // exposed for tests
+    _applyBindingToTodo: applyBindingToTodo,
+  }
+}