@threadcrumbs/common 0.0.0-stage → 0.1.1

package/harnesses/codex.mjs

@@ -0,0 +1,419 @@
+/**
+ * Harness adapter: Codex (OpenAI) — the desktop app, the VS Code extension and the CLI together.
+ *
+ * Two stores, deliberately merged rather than picked between, the same shape `claude-code.mjs`
+ * ended up in:
+ *
+ *   - `~/.codex/state_<n>.sqlite` holds one row per thread — title, cwd, branch, model, effort,
+ *     archived — which is everything the colony wants and none of it inferred.
+ *   - `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` holds the transcript, which is the only
+ *     source for how big a thread is and whether it is mid-turn, and the only source at all for
+ *     a session the database has not caught up with.
+ *
+ * They join on the session id, which appears in the row, in the rollout's filename and in its
+ * `session_meta` record. Reading only the database loses transcript size and any CLI session it
+ * has not indexed; reading only the transcripts means reconstructing metadata the database
+ * already has correct.
+ *
+ * Read-only, without exception, and the scan starts no subprocess. The only executable this
+ * module ever names is the `codex` binary on the user's own PATH, handed to the server as an argv
+ * for a terminal — nothing here runs anything. Codex has an archive of its own that only its CLI
+ * can set, so archiving here is recorded in the colony alone — see the note on archiving in
+ * `harnesses/README.md`.
+ */
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { exists, findExecutable, jsonLines, listDirs, listFiles, num, readHead, readTail } from '../lib/fsutil.mjs'
+
+const HOME = os.homedir()
+const CODEX_HOME = process.env.CODEX_HOME || path.join(HOME, '.codex')
+const SESSIONS_DIR = path.join(CODEX_HOME, 'sessions')
+const SESSION_INDEX = path.join(CODEX_HOME, 'session_index.jsonl')
+
+const HEAD_BYTES = 128 * 1024
+const TAIL_BYTES = 64 * 1024
+/** Codex writes nothing when it is killed, so a stale `task_started` needs a time bound too. */
+const ACTIVE_WINDOW_MS = 30 * 60 * 1000
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const STATE_DB = /^state_(\d+)\.sqlite$/
+const ROLLOUT_FILE = /^rollout-.{19}-([0-9a-f-]{36})(?:_[0-9a-f-]{36})?\.jsonl(\.zst)?$/i
+const SPAWNED_SOURCES = new Set(['subagent', 'guardian_review', 'memory_consolidation'])
+const NO_ROWS = { rows: new Map(), hidden: new Set() }
+const NOISE = /<([a-z][\w-]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g
+
+/** Prefixed, per the contract in `harnesses/README.md`. */
+const ID = (raw) => `codex:${raw}`
+
+/**
+ * `node:sqlite` is imported lazily and its absence is survivable.
+ *
+ * It needs Node 22.13, which `package.json` asks for — but asking is not enforcing, and a top
+ * level import would take the whole server down on an older Node rather than costing one
+ * harness. This way the transcript half still works and `diagnostic()` explains the rest.
+ */
+let sqlitePromise
+const sqliteApi = () => (sqlitePromise ??= import('node:sqlite').catch(() => null))
+
+/** The newest schema version, not the most recently touched WAL sibling. */
+async function latestStateDatabase() {
+  let entries
+  try {
+    entries = await fsp.readdir(CODEX_HOME, { withFileTypes: true })
+  } catch {
+    return ''
+  }
+  return (
+    entries
+      .filter((e) => e.isFile() && STATE_DB.test(e.name))
+      .map((e) => ({ file: path.join(CODEX_HOME, e.name), version: Number(e.name.match(STATE_DB)[1]) }))
+      .sort((a, b) => b.version - a.version)[0]?.file || ''
+  )
+}
+
+/**
+ * Every column is probed before it is named.
+ *
+ * This is undocumented private state that changes shape between Codex versions — the filename is
+ * versioned precisely because it does. A `SELECT` naming a column that has gone throws and costs
+ * the whole harness its threads, so every column except `id` and `cwd` is selected only when it exists.
+ */
+const column = (columns, name, fallback = "''") => (columns.has(name) ? `t.${name}` : fallback)
+
+function timeExpr(columns, ms, secs) {
+  if (columns.has(ms) && columns.has(secs)) return `COALESCE(t.${ms}, t.${secs} * 1000)`
+  if (columns.has(ms)) return `t.${ms}`
+  if (columns.has(secs)) return `t.${secs} * 1000`
+  return '0'
+}
+
+/**
+ * The thread index, keyed by session id, and the ids of the threads a task spawned. Both are empty
+ * when there is no readable database.
+ */
+async function databaseRows() {
+  const [file, sqlite] = await Promise.all([latestStateDatabase(), sqliteApi()])
+  if (!file || !sqlite?.DatabaseSync) return NO_ROWS
+
+  let db
+  try {
+    db = new sqlite.DatabaseSync(file, { readOnly: true })
+  } catch {
+    // A WAL database whose shared-memory file cannot be used refuses a read-only open. The
+    // transcripts still answer everything the colony needs to draw something.
+    return NO_ROWS
+  }
+  try {
+    const tables = new Set(
+      db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((r) => r.name)
+    )
+    if (!tables.has('threads')) return NO_ROWS
+    const columns = new Set(db.prepare('PRAGMA table_info(threads)').all().map((r) => r.name))
+    if (!['id', 'cwd'].every((n) => columns.has(n))) return NO_ROWS
+
+    // Threads a task spawned are not conversations anybody had; each would stand on the map as
+    // an astronaut nobody talks to.
+    const children = new Set()
+    if (tables.has('thread_spawn_edges')) {
+      const edge = new Set(db.prepare('PRAGMA table_info(thread_spawn_edges)').all().map((r) => r.name))
+      if (edge.has('child_thread_id')) {
+        for (const r of db.prepare('SELECT child_thread_id FROM thread_spawn_edges').all()) {
+          if (typeof r.child_thread_id === 'string') children.add(r.child_thread_id)
+        }
+      }
+    }
+
+    const unread = new Set()
+    if (tables.has('thread_read_receipts')) {
+      const receipt = new Set(db.prepare('PRAGMA table_info(thread_read_receipts)').all().map((r) => r.name))
+      if (receipt.has('thread_id') && receipt.has('first_unread_turn')) {
+        for (const r of db.prepare('SELECT thread_id FROM thread_read_receipts WHERE first_unread_turn IS NOT NULL').all()) {
+          if (typeof r.thread_id === 'string') unread.add(r.thread_id)
+        }
+      }
+    }
+
+    const rows = db
+      .prepare(`
+        SELECT
+          t.id,
+          t.cwd,
+          ${column(columns, 'name')} AS name,
+          ${column(columns, 'title')} AS title,
+          ${column(columns, 'preview')} AS preview,
+          ${column(columns, 'first_user_message')} AS first_user_message,
+          ${column(columns, 'source')} AS source,
+          ${column(columns, 'thread_source')} AS thread_source,
+          ${column(columns, 'git_branch')} AS git_branch,
+          ${column(columns, 'model')} AS model,
+          ${column(columns, 'reasoning_effort')} AS reasoning_effort,
+          ${column(columns, 'rollout_path')} AS rollout_path,
+          ${column(columns, 'archived', '0')} AS archived,
+          ${timeExpr(columns, 'created_at_ms', 'created_at')} AS created_at_ms,
+          ${timeExpr(columns, 'updated_at_ms', 'updated_at')} AS updated_at_ms
+        FROM threads t
+      `)
+      .all()
+      .filter((r) => UUID.test(r.id || ''))
+    const spawned = (r) => children.has(r.id) || SPAWNED_SOURCES.has(r.thread_source)
+
+    return {
+      rows: new Map(rows.filter((r) => !spawned(r)).map((r) => [r.id, { ...r, unread: unread.has(r.id) }])),
+      hidden: new Set(rows.filter(spawned).map((r) => r.id)),
+    }
+  } catch {
+    return NO_ROWS
+  } finally {
+    try {
+      db.close()
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/** Every rollout transcript on disk, keyed by the session id in its filename. */
+async function scanRollouts() {
+  const byId = new Map()
+  for (const year of await listDirs(SESSIONS_DIR)) {
+    for (const month of await listDirs(year)) {
+      for (const day of await listDirs(month)) {
+        for (const file of await listFiles(day, (n) => ROLLOUT_FILE.test(n))) {
+          const [, id, compressed] = ROLLOUT_FILE.exec(path.basename(file))
+          if (!UUID.test(id)) continue
+          try {
+            const st = await fsp.stat(file)
+            const existing = byId.get(id)
+            if (existing && existing.mtime >= st.mtimeMs) continue
+            byId.set(id, { id, file, size: st.size, mtime: st.mtimeMs, compressed: Boolean(compressed) })
+          } catch {
+            /* vanished between listing and stat */
+          }
+        }
+      }
+    }
+  }
+  return byId
+}
+
+/** `thread_name` per session, when Codex has written one. Optional; transcripts are the truth. */
+async function readIndex() {
+  const out = new Map()
+  try {
+    for (const row of jsonLines(await fsp.readFile(SESSION_INDEX, 'utf8'))) {
+      if (row?.id && UUID.test(row.id)) out.set(row.id, row)
+    }
+  } catch {
+    /* no index — every field it carries has another source */
+  }
+  return out
+}
+
+const clean = (v) => String(v || '').replace(/\s+/g, ' ').trim()
+
+function contentText(content) {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content.map((p) => (typeof p === 'string' ? p : p?.text || p?.input_text || '')).filter(Boolean).join('\n')
+}
+
+function promptText(raw) {
+  const text = clean(String(raw || '').replace(NOISE, ' '))
+  return text && !text.startsWith('<') && !text.startsWith('# AGENTS.md') ? text : ''
+}
+
+/** What the head of a transcript knows about itself, for a session the database has not indexed. */
+function readHeadMeta(records) {
+  const meta = { cwd: '', gitBranch: '', model: '', effort: '', createdAt: 0, prompt: '', typed: '', spawned: false }
+  for (const r of records) {
+    const p = r?.payload
+    if (!p || typeof p !== 'object') continue
+    if (r.type === 'session_meta') {
+      meta.cwd ||= p.cwd || ''
+      meta.gitBranch ||= p.git?.branch || ''
+      meta.createdAt ||= Date.parse(p.timestamp || r.timestamp || '') || 0
+      meta.spawned ||= SPAWNED_SOURCES.has(p.thread_source) || p.source?.subagent != null
+    } else if (r.type === 'turn_context') {
+      meta.cwd = p.cwd || meta.cwd
+      meta.model = p.model || meta.model
+      meta.effort = p.effort || meta.effort
+    } else if (r.type === 'response_item' && p.type === 'message' && p.role === 'user') {
+      meta.prompt ||= promptText(contentText(p.content))
+    } else if (r.type === 'event_msg' && p.type === 'user_message') {
+      meta.typed ||= promptText(p.message)
+    } else if (r.type === 'event_msg' && p.type === 'item_completed' && p.item?.type === 'UserMessage') {
+      meta.typed ||= promptText(contentText(p.item.content))
+    }
+  }
+  meta.prompt = meta.typed || meta.prompt
+  return meta
+}
+
+const TURN_STARTED = new Set(['task_started', 'turn_started'])
+const TURN_ENDED = new Set(['task_complete', 'turn_complete', 'turn_aborted'])
+
+/**
+ * The last lifecycle record. `task_started` with nothing after it is mid-turn; `turn_aborted` is
+ * somebody pressing escape, which is not an error and must not redden an astronaut's eyes.
+ */
+function readLifecycle(records) {
+  let last = null
+  for (const r of records) {
+    const p = r?.payload
+    if (r?.type !== 'event_msg') continue
+    if (TURN_STARTED.has(p?.type)) last = { type: 'task_started', error: false }
+    else if (TURN_ENDED.has(p?.type)) last = { type: p.type === 'turn_aborted' ? 'turn_aborted' : 'task_complete', error: Boolean(p.error) }
+  }
+  return last
+}
+
+/** Parsing is kept against mtime and size, so an unchanged transcript is read once. */
+const parseCache = new Map()
+async function transcriptFacts(entry, needHead) {
+  const cached = parseCache.get(entry.id)
+  if (cached && cached.mtime === entry.mtime && cached.size === entry.size && (cached.head || !needHead)) {
+    return cached.facts
+  }
+  const facts = { lifecycle: null, meta: null }
+  if (entry.compressed) return facts
+  try {
+    facts.lifecycle = readLifecycle(jsonLines(await readTail(entry.file, TAIL_BYTES)))
+    if (needHead) facts.meta = readHeadMeta(jsonLines(await readHead(entry.file, HEAD_BYTES)))
+  } catch {
+    /* mid-write, or gone */
+  }
+  parseCache.set(entry.id, { mtime: entry.mtime, size: entry.size, head: needHead, facts })
+  return facts
+}
+
+function projectOf(cwd) {
+  const dir = typeof cwd === 'string' && path.isAbsolute(cwd) ? cwd : ''
+  return { projectPath: dir, project: dir ? path.basename(dir) : 'unknown' }
+}
+
+async function scanThreads() {
+  const [{ rows, hidden }, rollouts, index] = await Promise.all([databaseRows(), scanRollouts(), readIndex()])
+  const ids = new Set([...rows.keys(), ...rollouts.keys()])
+  const now = Date.now()
+  const out = []
+
+  for (const id of ids) {
+    if (hidden.has(id)) continue
+    const row = rows.get(id)
+    const entry = rollouts.get(id)
+    // The head is only worth reading for a session the database cannot describe.
+    const facts = entry ? await transcriptFacts(entry, !row) : { lifecycle: null, meta: null }
+    const meta = facts.meta || {}
+    if (!row && meta.spawned) continue
+
+    const cwd = row?.cwd || meta.cwd || ''
+    const { projectPath, project } = projectOf(cwd)
+    const prompt = clean(row?.preview || row?.first_user_message || meta.prompt || '')
+    const title = clean(row?.name) || clean(index.get(id)?.thread_name) || clean(row?.title) || prompt || 'Untitled thread'
+    const lastActivityAt = Math.max(num(row?.updated_at_ms), entry?.mtime || 0)
+
+    out.push({
+      id: ID(id),
+      title: title.slice(0, 120),
+      preview: prompt.slice(0, 240),
+      project,
+      projectPath,
+      // Codex has no worktree concept of its own, and guessing one from the path would put a
+      // branch name on a thread that never had one.
+      worktree: '',
+      cwd,
+      gitBranch: row?.git_branch || meta.gitBranch || '',
+      model: row?.model || meta.model || '',
+      effort: row?.reasoning_effort || meta.effort || '',
+      createdAt: num(row?.created_at_ms) || meta.createdAt || entry?.mtime || 0,
+      lastActivityAt,
+      // Codex records no focus history, so "have you looked at this" is unknowable — not false.
+      lastFocusedAt: 0,
+      unread: row?.unread === true,
+      running: facts.lifecycle?.type === 'task_started' && now - lastActivityAt < ACTIVE_WINDOW_MS,
+      hasError: facts.lifecycle?.type === 'task_complete' && facts.lifecycle.error,
+      starred: false,
+      routine: '',
+      prState: '',
+      archived: row?.archived === 1 || row?.archived === true,
+      // Bytes, like every other harness: the field is a shared log scale across the whole map,
+      // and a token count would make Codex buildings taller than Claude ones for the same work.
+      sizeBytes: entry?.size || 0,
+      source: row?.source === 'vscode' ? 'vscode' : 'cli',
+      canOpen: true,
+      ref: { sessionId: id, cwd },
+    })
+  }
+  return out
+}
+
+/**
+ * Where the `codex` CLI is, for a page that would rather have a terminal than the app. PATH
+ * first, then the places `npm i -g` and Homebrew put a binary that a server started from a
+ * launcher would not see — never inside an application bundle.
+ */
+const CLI_DIRS = [
+  path.join(HOME, '.local', 'bin'),
+  path.join(HOME, '.npm-global', 'bin'),
+  '/opt/homebrew/bin',
+  '/usr/local/bin',
+  '/usr/bin',
+]
+const cliBinary = () => findExecutable('codex', CLI_DIRS)
+
+const APP = Object.freeze({ name: 'Codex', download: 'https://developers.openai.com/codex/app' })
+
+/**
+ * `codex://threads/<id>` is registered by the Codex desktop app; the OS opener does the rest.
+ * `codex resume <id>` is the CLI's own way back into the same session, offered alongside for a
+ * page that prefers a terminal. Nothing is run here — the server decides whether it is.
+ */
+async function openThread(ref) {
+  const { sessionId: id, cwd } = ref || {}
+  if (typeof id !== 'string' || !UUID.test(id)) {
+    return { ok: false, error: 'No openable Codex session id on that thread' }
+  }
+  const bin = await cliBinary()
+  const command = bin ? { argv: [bin, 'resume', id], cwd: typeof cwd === 'string' ? cwd : '' } : undefined
+  return { ok: true, url: `codex://threads/${id}`, command, app: APP }
+}
+
+async function newSession(dir) {
+  const bin = await cliBinary()
+  return {
+    ok: true,
+    url: `codex://threads/new?${new URLSearchParams({ path: dir })}`,
+    command: bin ? { argv: [bin], cwd: dir } : undefined,
+    app: APP,
+  }
+}
+
+/** Claim the machine if either store is there — a CLI-only install has no database. */
+async function detect() {
+  return (await exists(SESSIONS_DIR)) || Boolean(await latestStateDatabase())
+}
+
+/**
+ * Why a present Codex might still look thin. Without this the Node case is invisible: the
+ * database is simply skipped, every thread loses its title and model, and nothing says why.
+ */
+async function diagnostic() {
+  if (!(await latestStateDatabase())) return ''
+  if (!(await sqliteApi())?.DatabaseSync) {
+    return `Codex threads need Node 22.13 or newer for their titles and models (running ${process.versions.node})`
+  }
+  return ''
+}
+
+export default {
+  id: 'codex',
+  name: 'Codex',
+  app: APP,
+  detect,
+  diagnostic,
+  scanThreads,
+  openThread,
+  newSession,
+  paths: { CODEX_HOME, SESSIONS_DIR },
+}

package/harnesses/cursor.mjs

@@ -0,0 +1,199 @@
+/**
+ * Harness adapter: Cursor (Anysphere) — agent transcripts.
+ *
+ * Cursor writes one JSONL per agent session at
+ * `~/.cursor/projects/<encoded-cwd>/agent-transcripts/<uuid>/<uuid>.jsonl`. The records are
+ * plainer than most: `{ role, message }` for each turn and, in some versions, a
+ * `{ type: 'turn_ended', status }` marker closing each one. There is no title, no cwd, no model
+ * and no branch anywhere in the file — the encoded directory name and the first user message are
+ * the whole of the metadata.
+ *
+ * Not covered: the composer / sidebar threads. Their bodies are not in these files — the
+ * per-workspace `state.vscdb` holds only pane layout, and the global one is a couple of
+ * gigabytes on a working machine and open read-write by the editor. Reading that on a
+ * five-second poll is its own piece of work, and guessing at its shape would be worse than
+ * leaving it out and saying so.
+ *
+ * Read-only, no subprocess, and nothing is ever read from inside `Cursor.app`.
+ */
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { decodeProjectDir } from '../lib/cursor-folder.mjs'
+import { exists, jsonLines, listDirs, listFiles, readHead, readTail } from '../lib/fsutil.mjs'
+
+export { decodeFolder, encodeFolderName } from '../lib/cursor-folder.mjs'
+
+const HOME = os.homedir()
+const PROJECTS = process.env.THREADCRUMBS_CURSOR_PROJECTS_DIR || path.join(HOME, '.cursor', 'projects')
+const TRANSCRIPTS = 'agent-transcripts'
+
+const HEAD_BYTES = 96 * 1024
+const TAIL_BYTES = 32 * 1024
+/** Cursor writes nothing when it is killed, so an unclosed turn needs a time bound as well. */
+const ACTIVE_WINDOW_MS = 30 * 60 * 1000
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const APP = Object.freeze({ name: 'Cursor', download: 'https://cursor.com/downloads' })
+const FLAT_TRANSCRIPT = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i
+
+/** Prefixed, per the contract in `harnesses/README.md`. */
+const ID = (raw) => `cursor:${raw}`
+
+/**
+ * Cursor wraps a prompt in tags of its own — a timestamp, a note about attached images, the
+ * query itself. Only the query is something a person typed, and it is the only part worth
+ * putting on a card.
+ */
+function userText(record) {
+  const parts = record?.message?.content
+  const raw = Array.isArray(parts)
+    ? parts.map((p) => (typeof p === 'string' ? p : p?.text || '')).join('\n')
+    : String(parts || '')
+  const query = /<user_query>\s*([\s\S]*?)\s*<\/user_query>/.exec(raw)
+  const text = query ? query[1] : raw.replace(/<[a-z_]+>[\s\S]*?<\/[a-z_]+>/gi, ' ')
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+/** `Tuesday, Sep 8, 2026, 4:08 PM (UTC-7)` if the first turn carried one. */
+function stamp(record) {
+  const parts = record?.message?.content
+  const raw = Array.isArray(parts) ? parts.map((p) => p?.text || '').join('\n') : ''
+  const m = /<timestamp>(.*?)<\/timestamp>/.exec(raw)
+  const t = m ? Date.parse(m[1].replace(/\s*\(UTC[^)]*\)\s*$/, '')) : NaN
+  return Number.isNaN(t) ? 0 : t
+}
+
+/** Every transcript on disk, with the project directory it sits under. */
+async function scanTranscripts() {
+  const out = []
+  const add = async (id, file, projectDir) => {
+    try {
+      const st = await fsp.stat(file)
+      if (!st.size) return
+      out.push({ id, file, dirName: path.basename(projectDir), size: st.size, mtime: st.mtimeMs, born: st.birthtimeMs })
+    } catch {
+      /* vanished between listing and stat */
+    }
+  }
+  for (const projectDir of await listDirs(PROJECTS)) {
+    const root = path.join(projectDir, TRANSCRIPTS)
+    for (const sessionDir of await listDirs(root)) {
+      const id = path.basename(sessionDir)
+      if (!UUID.test(id)) continue
+      for (const file of await listFiles(sessionDir, (n) => n.endsWith('.jsonl'))) await add(id, file, projectDir)
+    }
+    for (const file of await listFiles(root, (n) => FLAT_TRANSCRIPT.test(n))) {
+      await add(FLAT_TRANSCRIPT.exec(path.basename(file))[1], file, projectDir)
+    }
+  }
+  return out
+}
+
+/** Parsing is kept against mtime and size, so an unchanged transcript is read once. */
+const cache = new Map()
+async function facts(entry) {
+  const hit = cache.get(entry.id)
+  if (hit && hit.mtime === entry.mtime && hit.size === entry.size) return hit.value
+  const value = { prompt: '', startedAt: 0, closed: true, modern: false, errored: false, modelsTurn: false }
+  try {
+    for (const r of jsonLines(await readHead(entry.file, HEAD_BYTES))) {
+      if (r?.role !== 'user') continue
+      value.prompt = userText(r)
+      value.startedAt = stamp(r)
+      break
+    }
+    const tail = jsonLines(await readTail(entry.file, TAIL_BYTES))
+    // Only some Cursor versions write `turn_ended`. Treating "no marker" as "mid-turn" would light
+    // up every unmarked thread on the map, so a file without markers is judged by its last record.
+    const ended = tail.filter((r) => r?.type === 'turn_ended')
+    value.modern = ended.length > 0
+    const last = tail[tail.length - 1]
+    value.closed = last?.type === 'turn_ended'
+    value.errored = ended.length > 0 && ended[ended.length - 1].status !== 'success'
+    const content = last?.message?.content
+    const calling = Array.isArray(content) && content.some((c) => c?.type === 'tool_use')
+    value.modelsTurn = last?.role === 'user' || (last?.role === 'assistant' && calling)
+  } catch {
+    /* mid-write, or gone */
+  }
+  cache.set(entry.id, { mtime: entry.mtime, size: entry.size, value })
+  return value
+}
+
+async function scanThreads() {
+  const entries = await scanTranscripts()
+  const now = Date.now()
+  const threads = []
+
+  for (const entry of entries) {
+    const f = await facts(entry)
+    const projectPath = await decodeProjectDir(entry.dirName)
+    const prompt = f.prompt
+    const fresh = now - entry.mtime < ACTIVE_WINDOW_MS
+    const running = fresh && (f.modern ? !f.closed : f.modelsTurn)
+    const handedBack = fresh && !running
+    threads.push({
+      id: ID(entry.id),
+      title: (prompt || 'Untitled thread').slice(0, 120),
+      preview: prompt.slice(0, 240),
+      project: path.basename(projectPath) || 'unknown',
+      projectPath,
+      // Cursor records no worktree, and inferring one from the path would put a branch name on
+      // a thread that never had one.
+      worktree: '',
+      cwd: projectPath,
+      gitBranch: '',
+      model: '',
+      effort: '',
+      createdAt: f.startedAt || entry.born || entry.mtime,
+      lastActivityAt: entry.mtime,
+      // No focus history, so "have you read this" is unknowable rather than false.
+      lastFocusedAt: 0,
+      unread: handedBack && !f.errored,
+      running,
+      hasError: f.errored,
+      starred: false,
+      routine: '',
+      prState: '',
+      archived: false,
+      sizeBytes: entry.size,
+      source: 'agent',
+      canOpen: Boolean(projectPath),
+      ref: { sessionId: entry.id, cwd: projectPath },
+    })
+  }
+  return threads
+}
+
+/**
+ * Cursor registers `cursor://`, but only for files and folders — nothing found so far addresses
+ * a single agent thread, and inventing a route would be a link that silently does nothing.
+ * So Open takes you to the repo in Cursor, which is one click from the thread, and the page
+ * is told that is what happened rather than left to wonder why the thread did not appear.
+ */
+function openThread(ref) {
+  const shown = newSession(ref?.cwd)
+  if (!shown.ok) return { ok: false, error: 'Cursor has no link to a single thread, and this one has no folder to open either.' }
+  return { ...shown, note: 'Cursor has no link to a single thread — opened the repo in Cursor; pick it from the agent list.' }
+}
+
+/** `cursor://file/<abs>` is answered by the installed app; the OS opener does the finding. */
+function newSession(dir) {
+  const abs = String(dir || '').replace(/\\/g, '/')
+  if (!abs.startsWith('/')) return { ok: false, error: 'That folder is not somewhere Cursor can open' }
+  return { ok: true, url: `cursor://file${abs.split('/').map(encodeURIComponent).join('/')}`, app: APP }
+}
+
+const detect = () => exists(PROJECTS)
+
+export default {
+  id: 'cursor',
+  name: 'Cursor',
+  app: APP,
+  detect,
+  scanThreads,
+  openThread,
+  newSession,
+  paths: { PROJECTS },
+}