@threadcrumbs/common 0.1.8 → 0.1.10

package/harnesses/claude-code.mjs

@@ -1,578 +1,578 @@
-/**
- * Harness adapter: Claude Code (Anthropic) — the desktop app and the CLI together.
- *
- * Everything that knows the shape of Claude Code's own files lives in this module and in
- * `../lib/claude-transcript.mjs`, the transcript parser it shares with the telemetry reader.
- * No app's scanner reaches past the adapter interface, so adding another harness
- * means writing a sibling of this file rather than editing a scanner. The contract is
- * written down in `harnesses/README.md`.
- *
- * Read-only, without exception. Nothing here writes to Claude Code's files — see the note on
- * archiving in `harnesses/README.md`.
- *
- * Two stores, deliberately merged rather than picked between:
- *   - the desktop app keeps one JSON record per thread (title, cwd, model, timestamps), and
- *     leaves a marker behind for each thread deleted in it
- *   - the CLI keeps the raw transcript, which is the only source for terminal-started work
- */
-import fsp from 'node:fs/promises'
-import path from 'node:path'
-import os from 'node:os'
-import { SCRATCH_ROOT, claudeDesktopStores, desktopRecordReader, projectOf } from '../lib/claude-desktop.mjs'
-import { awaitedPeers, readLiveSessions, stripNoise, transcriptReader, turnEnding } from '../lib/claude-transcript.mjs'
-import { exists, findExecutable, listDirs, listFiles, num } from '../lib/fsutil.mjs'
-
-const HOME = os.homedir()
-
-/**
- * Both roots take an override, which is how the tests fake an install without touching a real
- * one. `CLAUDE_CONFIG_DIR` is the CLI's own: a shell that sets it has its transcripts written
- * there, so the variable that moves the CLI's home moves where the colony looks for it too.
- * `THREADCRUMBS_CLAUDE_DESKTOP_DIR` names the session store itself, the sibling of Cursor's
- * `THREADCRUMBS_CURSOR_PROJECTS_DIR`.
- */
-/** Where the Claude desktop app keeps one JSON record per thread — one store per app profile. */
-const DESKTOP_STORES = claudeDesktopStores()
-/** The CLI's home: `~/.claude`, unless the CLI itself has been told otherwise. */
-const CLI_HOME = process.env.CLAUDE_CONFIG_DIR || path.join(HOME, '.claude')
-/** Where the CLI keeps the raw transcript: ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl */
-const CLI_PROJECTS = path.join(CLI_HOME, 'projects')
-/** One file per live CLI process: {pid, sessionId, cwd, ...}. Stale files outlive their pid. */
-const CLI_LIVE = path.join(CLI_HOME, 'sessions')
-
-const threadTranscripts = transcriptReader({ skim: true })
-const errandTranscripts = transcriptReader({ skim: true })
-
-/**
- * How recently a session must have done something to count as "active now".
- * A live process on its own is not enough: the desktop app pre-warms idle sessions, so
- * threads untouched for days still hold a CLI process. Measured against real data, the
- * warmed ones sat 16 hours to 3 days idle while genuinely active work was minutes old.
- */
-const ACTIVE_WINDOW_MS = 30 * 60 * 1000
-
-/**
- * How long a subagent's transcript may sit untouched before its errand counts as abandoned.
- * A subagent runs inside its parent's process, so the pid probe the rest of this file uses does
- * not exist for it, and one that is thinking writes nothing for minutes at a time — at two or
- * three minutes they blink out while still working.
- */
-const SUBAGENT_WINDOW_MS = 10 * 60 * 1000
-
-/**
- * Every id this adapter hands out is prefixed. `harnesses/README.md` asks for ids unique
- * across harnesses, and while two UUIDs will not collide, the colony keys its archive list and
- * saved layout on this string — so it is worth being unambiguous rather than merely lucky.
- */
-const ID = (raw) => `claude-code:${raw}`
-
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
-
-/**
- * A title from a prompt, for a thread the desktop app never named: its first line that says
- * anything, and no more of it than every other harness keeps. The fallback used to hand back
- * the whole prompt — a headless orchestrator run opens with three kilobytes of instructions, and six
- * of those were a third of every poll's payload, laid out as a title.
- */
-const TITLE_MAX = 120
-export function titleFromPrompt(prompt) {
-  const line = String(prompt || '')
-    .split('\n')
-    .map((text) => text.replace(/\s+/g, ' ').trim())
-    .find(Boolean)
-  return line ? line.slice(0, TITLE_MAX) : 'Untitled thread'
-}
-
-const DESKTOP_ID = /^local_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
-// The type check matters wherever an id came back from the page: `RegExp.test` stringifies, so a
-// one-element array holding a valid id would pass the pattern and then travel on as an array.
-const isCliId = (v) => typeof v === 'string' && UUID.test(v)
-const isDesktopId = (v) => typeof v === 'string' && DESKTOP_ID.test(v)
-
-/** A prompt as one line of text: the noise gone and every run of whitespace a single space. */
-function cleanPrompt(text) {
-  return stripNoise(text).replace(/\s+/g, ' ').trim()
-}
-
-/**
- * Pull whatever a transcript knows about itself: title, cwd, branch, start time.
- * Mirrors the CLI's own title precedence: custom > ai > summary > first prompt.
- */
-function metaOf(state) {
-  const prompt = state?.firstPrompt || ''
-  return {
-    customTitle: state?.customTitle || '',
-    aiTitle: state?.aiTitle || '',
-    summary: state?.summary || '',
-    firstPrompt: cleanPrompt(prompt),
-    // Taken from the prompt as the transcript has it: `firstPrompt` has its line breaks
-    // collapsed, so a title worked out from that could never find the first line.
-    promptTitle: prompt ? titleFromPrompt(prompt) : '',
-    cwd: state?.firstCwd || '',
-    gitBranch: state?.firstBranch || '',
-    startedAt: state?.startedAt || 0,
-  }
-}
-
-async function readTranscript(entry) {
-  try {
-    return await threadTranscripts.read(entry.file, { size: entry.size })
-  } catch {
-    return null
-  }
-}
-
-/**
- * Best-effort reverse of the encoding used for project folder names: `-Users-you-Some-Dir`
- * on macOS, `C--Users-you-Some-Dir` on Windows, where the drive's colon became a dash too.
- */
-function decodeProjectDir(name) {
-  const drive = /^([A-Za-z])--(.*)$/.exec(name)
-  if (drive) return `${drive[1]}:\\${drive[2].replace(/-/g, '\\')}`
-  return name.startsWith('-') ? '/' + name.slice(1).replace(/-/g, '/') : name
-}
-
-/**
- * Index every CLI transcript on disk, keyed by session id.
- *
- * A session id is only unique *per directory* it has ever run in — resuming it from a git
- * worktree, or any other second checkout, writes a second `<id>.jsonl` under a different
- * `projectDir` rather than moving the first. Without a tiebreaker the later `listDirs` entry
- * would win regardless of which copy is actually live, so a worktree's now-stale copy could
- * overwrite the real one just by sorting after it. The newer file is always the live one: an
- * abandoned copy stops being written to the moment the session moves on.
- */
-async function scanTranscripts() {
-  const byId = new Map()
-  for (const projectDir of await listDirs(CLI_PROJECTS)) {
-    for (const file of await listFiles(projectDir, (n) => n.endsWith('.jsonl'))) {
-      const id = path.basename(file, '.jsonl')
-      let stat
-      try {
-        stat = await fsp.stat(file)
-      } catch {
-        continue
-      }
-      const existing = byId.get(id)
-      if (existing && existing.mtime >= stat.mtimeMs) continue
-      byId.set(id, { id, file, projectDir, size: stat.size, mtime: stat.mtimeMs })
-    }
-  }
-  return byId
-}
-
-/**
- * Whether a transcript ends with the turn handed back to you.
- *
- * A live process is not the same thing as work in progress. The CLI holds its process open while
- * it sits at the prompt, so "the pid exists and the file moved recently" marks a thread that
- * finished four minutes ago and asked you a question as *working* — an astronaut hammering away
- * at a thread whose whole point is that it is waiting.
- *
- * The transcript says which it is. A last assistant message that called a tool is mid-turn; one
- * that called nothing has handed the turn back and the reply is yours. `stop_reason` alone will
- * not do — it is `end_turn` on a main thread's last message and empty on some others — so what
- * the message *called* is the half worth testing.
- *
- * The shared transcript reader keeps that answer up to date as it reads each transcript's new
- * lines, so asking it costs no read of its own.
- */
-const MID_TURN = { handedBack: false, failed: false, onAgents: false }
-
-/**
- * The subagents a session has out right now, keyed by the session that sent them. Their
- * transcripts live one level below the session's own, in
- * `<project>/<sessionId>/subagents/agent-<id>.jsonl`.
- *
- * Only sessions with a live process are walked. Every other session on disk has subagent
- * transcripts too, and all of that work would be thrown away: an errand cannot outlive the
- * process running it.
- */
-async function scanSubagents(livePending) {
-  const byParent = new Map()
-  const live = await livePending
-  const cutoff = Date.now() - SUBAGENT_WINDOW_MS
-  for (const projectDir of live.size ? await listDirs(CLI_PROJECTS) : []) {
-    for (const sessionDir of await listDirs(projectDir)) {
-      const parent = path.basename(sessionDir)
-      if (!live.has(parent)) continue
-      const dir = path.join(sessionDir, 'subagents')
-      for (const file of await listFiles(dir, (n) => n.endsWith('.jsonl'))) {
-        const stat = await fsp.stat(file).catch(() => null)
-        if (!stat || stat.mtimeMs < cutoff) continue
-        // A subagent that has handed its answer back is finished however recently it wrote —
-        // the same question `turnEnding` answers for a thread, put to the errand's own transcript.
-        const state = await errandTranscripts.read(file, stat, { sidechain: true }).catch(() => null)
-        if (turnEnding(state).handedBack) continue
-        const out = byParent.get(parent) || []
-        out.push({
-          id: path.basename(file, '.jsonl'),
-          // The prompt a parent handed its subagent, which is the only thing about an errand
-          // worth showing. A forked subagent opens with a `fork-context-ref` and inherits its
-          // parent's context instead of being briefed, so it has no task text to find.
-          task: cleanPrompt(state?.firstPrompt || ''),
-          lastActivityAt: stat.mtimeMs,
-        })
-        byParent.set(parent, out)
-      }
-    }
-  }
-  // Errands are many and short-lived, so the reader keeps only the transcripts this pass read.
-  errandTranscripts.sweep()
-  return byParent
-}
-
-const readDesktopRecords = desktopRecordReader()
-
-/** Every thread the desktop app has a record for, and the ids of the ones it has deleted. */
-const scanDesktopSessions = () => readDesktopRecords(DESKTOP_STORES)
-
-/**
- * Two desktop records can point at one transcript — resuming a thread that is already
- * open makes the app write a second, untitled record. Keep the richer of the two.
- */
-function mergeThread(existing, next) {
-  const better = (a, b) => (a && a !== 'Untitled thread' ? a : b || a)
-  // The titled record is the real thread; an untitled twin is the import ghost. Point
-  // the canonical id at the real one, but keep both so archiving covers the ghost too.
-  const keepExisting = existing.titled || !next.titled
-  return {
-    ...existing,
-    ...next,
-    title: better(existing.title, next.title),
-    titled: existing.titled || next.titled,
-    preview: existing.preview || next.preview,
-    desktopSessionId: keepExisting ? existing.desktopSessionId : next.desktopSessionId,
-    desktopSessionIds: [...new Set([...existing.desktopSessionIds, ...next.desktopSessionIds])],
-    bridgeSessionId: existing.bridgeSessionId || next.bridgeSessionId,
-    model: existing.model || next.model,
-    effort: existing.effort || next.effort,
-    gitBranch: existing.gitBranch || next.gitBranch,
-    cwd: existing.cwd || next.cwd,
-    createdAt: Math.min(existing.createdAt || Infinity, next.createdAt || Infinity) || 0,
-    lastActivityAt: Math.max(existing.lastActivityAt || 0, next.lastActivityAt || 0),
-    lastFocusedAt: Math.max(existing.lastFocusedAt || 0, next.lastFocusedAt || 0),
-    hasError: existing.hasError || next.hasError,
-    turnOutcome: existing.turnOutcome || next.turnOutcome,
-    hasLiveProcess: existing.hasLiveProcess || next.hasLiveProcess,
-    starred: existing.starred || next.starred,
-    routine: existing.routine || next.routine,
-    prState: existing.prState || next.prState,
-    archived: existing.archived && next.archived,
-    hasTranscript: existing.hasTranscript || next.hasTranscript,
-  }
-}
-
-/**
- * Fold the adapter's private bookkeeping into the shape the rest of the app sees.
- * The session ids stay, but behind `ref` — an opaque blob the browser hands straight
- * back on open/archive, so nothing outside this file has to know what a Claude session
- * id looks like.
- */
-function toThread(t) {
-  const {
-    desktopSessionId, desktopSessionIds, cliSessionId, bridgeSessionId,
-    titled, hasLiveProcess, transcriptFile, recordActivityAt, turnOutcome, ...rest
-  } = t
-  return {
-    ...rest,
-    canOpen: isDesktopId(desktopSessionId) || isCliId(cliSessionId),
-    // The cwd rides along because resuming from a terminal has to happen in the folder the
-    // session ran in — the worktree, not the repo root.
-    ref: { desktopSessionId, desktopSessionIds, cliSessionId, cwd: t.cwd || '' },
-  }
-}
-
-async function scanThreads() {
-  // The subagent walk needs the live set, and waiting for it here would serialise scans the
-  // README says must never block — so it is handed the promise and waits on it itself.
-  const livePending = readLiveSessions(CLI_LIVE)
-  const [{ records: desktop, deleted }, transcripts, live, subagents] = await Promise.all([
-    scanDesktopSessions(),
-    scanTranscripts(),
-    livePending,
-    scanSubagents(livePending),
-  ])
-  const states = new Map()
-  const read = async (entry) => {
-    const state = await readTranscript(entry)
-    if (state) states.set(entry.file, state)
-    return metaOf(state)
-  }
-  const byId = new Map()
-  const add = (thread) => {
-    const existing = byId.get(thread.id)
-    byId.set(thread.id, existing ? mergeThread(existing, thread) : thread)
-  }
-  const claimed = new Set()
-
-  for (const s of desktop) {
-    const cliSessionId = s.cliSessionId || ''
-    const entry = cliSessionId ? transcripts.get(cliSessionId) : null
-    if (entry) claimed.add(cliSessionId)
-
-    const cwd = s.cwd || s.originCwd || ''
-    const { projectPath, project, worktree } = projectOf(cwd, s.originCwd)
-    const meta = entry ? await read(entry) : null
-    const spokeAt = entry ? states.get(entry.file)?.lastAt || 0 : 0
-
-    add({
-      id: ID(cliSessionId || s.sessionId),
-      cliSessionId,
-      desktopSessionId: s.sessionId || '',
-      desktopSessionIds: s.sessionId ? [s.sessionId] : [],
-      titled: Boolean(s.title),
-      bridgeSessionId: (s.bridgeSessionIds && s.bridgeSessionIds[0]) || '',
-      title: s.title || meta?.customTitle || meta?.aiTitle || meta?.summary || meta?.promptTitle || 'Untitled thread',
-      preview: meta?.firstPrompt ? meta.firstPrompt.slice(0, 240) : '',
-      project,
-      projectPath,
-      worktree,
-      cwd,
-      gitBranch: meta?.gitBranch || '',
-      model: s.model || '',
-      effort: s.effort || '',
-      createdAt: num(s.createdAt) || meta?.startedAt || 0,
-      lastActivityAt:
-        spokeAt ||
-        Math.max(
-          num(s.lastActivityAt) || num(s.lastFocusedAt) || num(s.createdAt) || 0,
-          entry?.mtime || 0
-        ),
-      recordActivityAt: num(s.lastActivityAt) || num(s.lastFocusedAt) || num(s.createdAt) || 0,
-      lastFocusedAt: num(s.lastFocusedAt),
-      hasLiveProcess: live.has(cliSessionId),
-      hasError: Boolean(s.error) || s.turnOutcome === 'failed',
-      turnOutcome: s.turnOutcome || '',
-      starred: s.isStarred === true,
-      routine: s.scheduledTaskId || '',
-      prState: s.prState || '',
-      archived: s.isArchived === true || s.isArchived === 'True',
-      hasTranscript: Boolean(entry),
-      sizeBytes: entry?.size || 0,
-      transcriptFile: entry?.file || '',
-      source: 'desktop',
-    })
-  }
-
-  // Transcripts with no desktop record — threads started straight from the terminal, and threads
-  // the app has since deleted.
-  for (const [id, entry] of transcripts) {
-    if (claimed.has(id)) continue
-    const meta = await read(entry)
-    const cwd = meta.cwd || decodeProjectDir(path.basename(entry.projectDir))
-    const { projectPath, project, worktree } = projectOf(cwd, '')
-    add({
-      id: ID(id),
-      cliSessionId: id,
-      desktopSessionId: '',
-      desktopSessionIds: [],
-      titled: Boolean(meta.customTitle || meta.aiTitle),
-      bridgeSessionId: '',
-      title: meta.customTitle || meta.aiTitle || meta.summary || meta.promptTitle || 'Untitled thread',
-      preview: meta.firstPrompt ? meta.firstPrompt.slice(0, 240) : '',
-      project,
-      projectPath,
-      worktree,
-      cwd,
-      gitBranch: meta.gitBranch,
-      model: '',
-      effort: '',
-      createdAt: meta.startedAt || entry.mtime,
-      lastActivityAt: states.get(entry.file)?.lastAt || entry.mtime,
-      lastFocusedAt: 0,
-      hasLiveProcess: live.has(id),
-      hasError: false,
-      turnOutcome: '',
-      starred: false,
-      routine: '',
-      prState: '',
-      // Deleted in the app, and reported the way an archive made there is. `archived` is the
-      // read-only field an adapter has for "gone from the harness's own UI", and the colony sends
-      // the astronaut home for it exactly as it does for an archive of its own — rather than the
-      // thread simply vanishing from one scan to the next. Only a transcript with no record left
-      // qualifies: resuming a deleted thread makes the app write a fresh record while the marker
-      // stays behind, and a record that exists is the newer truth.
-      archived: deleted.has(id),
-      hasTranscript: true,
-      sizeBytes: entry.size,
-      transcriptFile: entry?.file || '',
-      source: 'cli',
-    })
-  }
-
-  const now = Date.now()
-
-  /**
-   * Drop the app's empty bookkeeping records.
-   *
-   * Resuming a thread makes the desktop app write a second record for the same conversation, and
-   * one of the two carries the title and the transcript link while the other carries nothing.
-   * With no `cliSessionId` on the empty one there is no key to merge the pair on, so it survives
-   * as a thread of its own: an untitled entry with no transcript behind it, standing on the map
-   * as a nameless twin of a thread you have already dealt with.
-   *
-   * A record with no transcript, no title and no live process is not a conversation. The age
-   * check keeps a genuinely new session — opened seconds ago, nothing written yet — out of it.
-   */
-  const NEW_SESSION_MS = 10 * 60 * 1000
-  const threads = [...byId.values()].filter(
-    (t) =>
-      t.hasTranscript ||
-      t.titled ||
-      t.hasLiveProcess ||
-      now - (t.lastActivityAt || t.createdAt || 0) < NEW_SESSION_MS
-  )
-
-  // Unread = a reply came back after you last looked at it; never opened counts as unread.
-  // Terminal-only threads have no focus history at all, so "unread" is unknowable — not true.
-  const handedBackAt = (sessionId) => states.get(transcripts.get(sessionId)?.file)?.handedBackAt || 0
-  for (const thread of threads) {
-    const seenAt = handedBackAt(thread.cliSessionId) || (thread.recordActivityAt ?? thread.lastActivityAt)
-    thread.unread = thread.desktopSessionIds.length > 0 && seenAt > thread.lastFocusedAt
-    const fresh = now - thread.lastActivityAt < ACTIVE_WINDOW_MS
-    const reported = live.get(thread.cliSessionId)?.status || ''
-    const errands = subagents.get(thread.cliSessionId)
-    const peers = thread.hasLiveProcess ? awaitedPeers(states.get(thread.transcriptFile), live, handedBackAt) : []
-    const ending =
-      thread.hasLiveProcess && (fresh || errands || peers.length) && thread.transcriptFile && (!reported || reported === 'idle' || (reported === 'busy' && errands))
-        ? turnEnding(states.get(thread.transcriptFile))
-        : MID_TURN
-    const delegating =
-      (Boolean(errands) && (reported === '' || reported === 'busy') && (ending.handedBack || ending.onAgents)) ||
-      (peers.length > 0 && (reported === '' || reported === 'idle') && ending.handedBack)
-    const waiting = thread.hasLiveProcess && fresh && !delegating && (reported ? reported === 'idle' : ending.handedBack)
-    thread.running = thread.hasLiveProcess && fresh && !delegating && (reported ? reported === 'busy' : !ending.handedBack)
-    thread.awaitingSubagents = delegating
-    thread.needsInput = reported === 'waiting' || (!thread.running && !delegating && thread.turnOutcome === 'blocked')
-    if (waiting && ending.failed) thread.hasError = true
-    // A thread that handed the turn back wants you, whether or not the desktop app has ever seen
-    // it — the only way a terminal-only thread can ask for anything at all.
-    if (waiting) thread.unread = true
-    if (errands) thread.subagents = errands
-    if (peers.length) thread.awaiting = peers.map((p) => ({ id: ID(p.sessionId), title: p.name }))
-  }
-  threadTranscripts.sweep()
-  return threads.map(toThread)
-}
-
-/**
- * Where the `claude` CLI is, for a machine that has it but no desktop app to answer the deep
- * link, or a page that would rather have a terminal. PATH first, then the places its installers
- * put it — never inside an application bundle.
- */
-const CLI_DIRS = [
-  path.join(HOME, '.local', 'bin'),
-  path.join(HOME, '.claude', 'local'),
-  '/opt/homebrew/bin',
-  '/usr/local/bin',
-  '/usr/bin',
-]
-const VSCODE_EXTENSION_ID = 'anthropic.claude-code'
-const EXTENSION = Object.freeze({
-  name: 'Claude Code for VS Code',
-  download: 'https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code',
-})
-const VSCODE = Object.freeze({ name: 'VS Code', download: 'https://code.visualstudio.com/download' })
-const APP = Object.freeze({ name: 'Claude', download: 'https://claude.com/download', also: Object.freeze([EXTENSION]) })
-
-const vscodeExtensionsDir = () => process.env.THREADCRUMBS_VSCODE_EXTENSIONS_DIR || path.join(HOME, '.vscode', 'extensions')
-
-async function vscodeExtension() {
-  const root = vscodeExtensionsDir()
-  let installed
-  try {
-    installed = JSON.parse(await fsp.readFile(path.join(root, 'extensions.json'), 'utf8'))
-  } catch {
-    return null
-  }
-  const entry = Array.isArray(installed) ? installed.find((e) => String(e?.identifier?.id).toLowerCase() === VSCODE_EXTENSION_ID) : null
-  const folder = typeof entry?.relativeLocation === 'string' ? path.join(root, path.basename(entry.relativeLocation)) : ''
-  if (!folder || !(await exists(folder))) return null
-  const cli = path.join(folder, 'resources', 'native-binary', process.platform === 'win32' ? 'claude.exe' : 'claude')
-  return { cli: (await exists(cli)) ? cli : null }
-}
-
-const claudeCli = async (extension) => (await findExecutable('claude', CLI_DIRS)) || extension?.cli || null
-
-const vscodeFolder = (dir) => `vscode://file/${encodeURI(dir.replace(/\\/g, '/'))}`
-
-function inVsCode(extension, dir, session) {
-  if (!extension || typeof dir !== 'string' || !path.isAbsolute(dir)) return undefined
-  const open = `vscode://${VSCODE_EXTENSION_ID}/open${session ? `?${new URLSearchParams({ session })}` : ''}`
-  return { app: VSCODE, urls: [vscodeFolder(dir), open], note: "Opened in VS Code's Claude Code panel, since the Claude app isn't installed" }
-}
-
-/**
- * The pid of the live CLI process behind a session, if any. `readLiveSessions` probes each pid
- * before it counts, because the registry's files outlive their pids.
- */
-async function liveSessionPid(sessionId) {
-  return (await readLiveSessions(CLI_LIVE)).get(sessionId)?.pid || 0
-}
-
-/**
- * Hands the thread back to Claude Code. `epitaxy/<local_…>` *navigates* the desktop app
- * to a thread it already has; `resume` *imports* the transcript, which spawns a second
- * untitled session and rewrites the .jsonl — so it is only ever the fallback for threads
- * the app has never seen. Ids are pattern-checked before they reach the opener.
- *
- * A terminal-started thread that is still running gets its live pid handed along too: it
- * already has a window somewhere on this machine, and fronting that window is a better answer
- * than `resume` importing the transcript into the desktop app as a second, untitled session.
- * Whether and how to front it is the app's call — Threadnauts does it in `server/lib/windows.mjs`.
- */
-async function openThread(ref) {
-  const { desktopSessionId, cliSessionId, cwd } = ref || {}
-  let url = ''
-  if (isDesktopId(desktopSessionId)) url = `claude://claude.ai/epitaxy/${desktopSessionId}`
-  else if (isCliId(cliSessionId)) url = `claude://resume?session=${cliSessionId}`
-
-  // Only threads the desktop app has never seen: for the rest the deep link navigates to the
-  // tab the app already has, which is exactly the right window to front.
-  let pid = 0
-  if (!isDesktopId(desktopSessionId) && isCliId(cliSessionId)) pid = await liveSessionPid(cliSessionId)
-
-  let command
-  let fallback
-  if (isCliId(cliSessionId)) {
-    const extension = await vscodeExtension()
-    const bin = await claudeCli(extension)
-    if (bin) command = { argv: [bin, '--resume', cliSessionId], cwd: typeof cwd === 'string' ? cwd : '' }
-    if (!pid) fallback = inVsCode(extension, cwd, cliSessionId)
-  }
-
-  if (!url && !command) return { ok: false, error: 'No openable session id on that thread' }
-  return { ok: true, url, command, pid, app: APP, fallback }
-}
-
-/**
- * A brand new thread rooted in a repo — the same `code/new?folder=` deep link Finder's
- * "New Claude Code Session Here" quick action uses. Nothing is resumed and nothing is
- * written: the desktop app just opens an empty session with that folder as its workspace.
- */
-async function newSession(dir) {
-  // The Scratch plot's folder holds the desktop app's own scratch sessions. A session opened on
-  // it, or the CLI run in it, would work inside the app's data rather than in a repo of yours.
-  if (SCRATCH_ROOT.test(dir)) {
-    return { ok: false, error: 'Scratch threads have no folder of their own; start one in the Claude app' }
-  }
-
-  const url = `claude://code/new?${new URLSearchParams({ folder: dir })}`
-  const extension = await vscodeExtension()
-  const bin = await claudeCli(extension)
-  const command = bin ? { argv: [bin], cwd: dir } : undefined
-  return { ok: true, url, command, app: APP, fallback: inVsCode(extension, dir, '') }
-}
-
-export default {
-  id: 'claude-code',
-  name: 'Claude Code',
-  app: APP,
-  /** Only claim this machine if one of the two stores is actually there. */
-  detect: async () => (await Promise.all(DESKTOP_STORES.map(exists))).some(Boolean) || (await exists(CLI_PROJECTS)),
-  scanThreads,
-  openThread,
-  newSession,
-  paths: { DESKTOP_STORES, CLI_PROJECTS, CLI_LIVE },
-}
+/**
+ * Harness adapter: Claude Code (Anthropic) — the desktop app and the CLI together.
+ *
+ * Everything that knows the shape of Claude Code's own files lives in this module and in
+ * `../lib/claude-transcript.mjs`, the transcript parser it shares with the telemetry reader.
+ * No app's scanner reaches past the adapter interface, so adding another harness
+ * means writing a sibling of this file rather than editing a scanner. The contract is
+ * written down in `harnesses/README.md`.
+ *
+ * Read-only, without exception. Nothing here writes to Claude Code's files — see the note on
+ * archiving in `harnesses/README.md`.
+ *
+ * Two stores, deliberately merged rather than picked between:
+ *   - the desktop app keeps one JSON record per thread (title, cwd, model, timestamps), and
+ *     leaves a marker behind for each thread deleted in it
+ *   - the CLI keeps the raw transcript, which is the only source for terminal-started work
+ */
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { SCRATCH_ROOT, claudeDesktopStores, desktopRecordReader, projectOf } from '../lib/claude-desktop.mjs'
+import { awaitedPeers, readLiveSessions, stripNoise, transcriptReader, turnEnding } from '../lib/claude-transcript.mjs'
+import { exists, findExecutable, listDirs, listFiles, num } from '../lib/fsutil.mjs'
+
+const HOME = os.homedir()
+
+/**
+ * Both roots take an override, which is how the tests fake an install without touching a real
+ * one. `CLAUDE_CONFIG_DIR` is the CLI's own: a shell that sets it has its transcripts written
+ * there, so the variable that moves the CLI's home moves where the colony looks for it too.
+ * `THREADCRUMBS_CLAUDE_DESKTOP_DIR` names the session store itself, the sibling of Cursor's
+ * `THREADCRUMBS_CURSOR_PROJECTS_DIR`.
+ */
+/** Where the Claude desktop app keeps one JSON record per thread — one store per app profile. */
+const DESKTOP_STORES = claudeDesktopStores()
+/** The CLI's home: `~/.claude`, unless the CLI itself has been told otherwise. */
+const CLI_HOME = process.env.CLAUDE_CONFIG_DIR || path.join(HOME, '.claude')
+/** Where the CLI keeps the raw transcript: ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl */
+const CLI_PROJECTS = path.join(CLI_HOME, 'projects')
+/** One file per live CLI process: {pid, sessionId, cwd, ...}. Stale files outlive their pid. */
+const CLI_LIVE = path.join(CLI_HOME, 'sessions')
+
+const threadTranscripts = transcriptReader({ skim: true })
+const errandTranscripts = transcriptReader({ skim: true })
+
+/**
+ * How recently a session must have done something to count as "active now".
+ * A live process on its own is not enough: the desktop app pre-warms idle sessions, so
+ * threads untouched for days still hold a CLI process. Measured against real data, the
+ * warmed ones sat 16 hours to 3 days idle while genuinely active work was minutes old.
+ */
+const ACTIVE_WINDOW_MS = 30 * 60 * 1000
+
+/**
+ * How long a subagent's transcript may sit untouched before its errand counts as abandoned.
+ * A subagent runs inside its parent's process, so the pid probe the rest of this file uses does
+ * not exist for it, and one that is thinking writes nothing for minutes at a time — at two or
+ * three minutes they blink out while still working.
+ */
+const SUBAGENT_WINDOW_MS = 10 * 60 * 1000
+
+/**
+ * Every id this adapter hands out is prefixed. `harnesses/README.md` asks for ids unique
+ * across harnesses, and while two UUIDs will not collide, the colony keys its archive list and
+ * saved layout on this string — so it is worth being unambiguous rather than merely lucky.
+ */
+const ID = (raw) => `claude-code:${raw}`
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * A title from a prompt, for a thread the desktop app never named: its first line that says
+ * anything, and no more of it than every other harness keeps. The fallback used to hand back
+ * the whole prompt — a headless orchestrator run opens with three kilobytes of instructions, and six
+ * of those were a third of every poll's payload, laid out as a title.
+ */
+const TITLE_MAX = 120
+export function titleFromPrompt(prompt) {
+  const line = String(prompt || '')
+    .split('\n')
+    .map((text) => text.replace(/\s+/g, ' ').trim())
+    .find(Boolean)
+  return line ? line.slice(0, TITLE_MAX) : 'Untitled thread'
+}
+
+const DESKTOP_ID = /^local_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+// The type check matters wherever an id came back from the page: `RegExp.test` stringifies, so a
+// one-element array holding a valid id would pass the pattern and then travel on as an array.
+const isCliId = (v) => typeof v === 'string' && UUID.test(v)
+const isDesktopId = (v) => typeof v === 'string' && DESKTOP_ID.test(v)
+
+/** A prompt as one line of text: the noise gone and every run of whitespace a single space. */
+function cleanPrompt(text) {
+  return stripNoise(text).replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Pull whatever a transcript knows about itself: title, cwd, branch, start time.
+ * Mirrors the CLI's own title precedence: custom > ai > summary > first prompt.
+ */
+function metaOf(state) {
+  const prompt = state?.firstPrompt || ''
+  return {
+    customTitle: state?.customTitle || '',
+    aiTitle: state?.aiTitle || '',
+    summary: state?.summary || '',
+    firstPrompt: cleanPrompt(prompt),
+    // Taken from the prompt as the transcript has it: `firstPrompt` has its line breaks
+    // collapsed, so a title worked out from that could never find the first line.
+    promptTitle: prompt ? titleFromPrompt(prompt) : '',
+    cwd: state?.firstCwd || '',
+    gitBranch: state?.firstBranch || '',
+    startedAt: state?.startedAt || 0,
+  }
+}
+
+async function readTranscript(entry) {
+  try {
+    return await threadTranscripts.read(entry.file, { size: entry.size })
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Best-effort reverse of the encoding used for project folder names: `-Users-you-Some-Dir`
+ * on macOS, `C--Users-you-Some-Dir` on Windows, where the drive's colon became a dash too.
+ */
+function decodeProjectDir(name) {
+  const drive = /^([A-Za-z])--(.*)$/.exec(name)
+  if (drive) return `${drive[1]}:\\${drive[2].replace(/-/g, '\\')}`
+  return name.startsWith('-') ? '/' + name.slice(1).replace(/-/g, '/') : name
+}
+
+/**
+ * Index every CLI transcript on disk, keyed by session id.
+ *
+ * A session id is only unique *per directory* it has ever run in — resuming it from a git
+ * worktree, or any other second checkout, writes a second `<id>.jsonl` under a different
+ * `projectDir` rather than moving the first. Without a tiebreaker the later `listDirs` entry
+ * would win regardless of which copy is actually live, so a worktree's now-stale copy could
+ * overwrite the real one just by sorting after it. The newer file is always the live one: an
+ * abandoned copy stops being written to the moment the session moves on.
+ */
+async function scanTranscripts() {
+  const byId = new Map()
+  for (const projectDir of await listDirs(CLI_PROJECTS)) {
+    for (const file of await listFiles(projectDir, (n) => n.endsWith('.jsonl'))) {
+      const id = path.basename(file, '.jsonl')
+      let stat
+      try {
+        stat = await fsp.stat(file)
+      } catch {
+        continue
+      }
+      const existing = byId.get(id)
+      if (existing && existing.mtime >= stat.mtimeMs) continue
+      byId.set(id, { id, file, projectDir, size: stat.size, mtime: stat.mtimeMs })
+    }
+  }
+  return byId
+}
+
+/**
+ * Whether a transcript ends with the turn handed back to you.
+ *
+ * A live process is not the same thing as work in progress. The CLI holds its process open while
+ * it sits at the prompt, so "the pid exists and the file moved recently" marks a thread that
+ * finished four minutes ago and asked you a question as *working* — an astronaut hammering away
+ * at a thread whose whole point is that it is waiting.
+ *
+ * The transcript says which it is. A last assistant message that called a tool is mid-turn; one
+ * that called nothing has handed the turn back and the reply is yours. `stop_reason` alone will
+ * not do — it is `end_turn` on a main thread's last message and empty on some others — so what
+ * the message *called* is the half worth testing.
+ *
+ * The shared transcript reader keeps that answer up to date as it reads each transcript's new
+ * lines, so asking it costs no read of its own.
+ */
+const MID_TURN = { handedBack: false, failed: false, onAgents: false }
+
+/**
+ * The subagents a session has out right now, keyed by the session that sent them. Their
+ * transcripts live one level below the session's own, in
+ * `<project>/<sessionId>/subagents/agent-<id>.jsonl`.
+ *
+ * Only sessions with a live process are walked. Every other session on disk has subagent
+ * transcripts too, and all of that work would be thrown away: an errand cannot outlive the
+ * process running it.
+ */
+async function scanSubagents(livePending) {
+  const byParent = new Map()
+  const live = await livePending
+  const cutoff = Date.now() - SUBAGENT_WINDOW_MS
+  for (const projectDir of live.size ? await listDirs(CLI_PROJECTS) : []) {
+    for (const sessionDir of await listDirs(projectDir)) {
+      const parent = path.basename(sessionDir)
+      if (!live.has(parent)) continue
+      const dir = path.join(sessionDir, 'subagents')
+      for (const file of await listFiles(dir, (n) => n.endsWith('.jsonl'))) {
+        const stat = await fsp.stat(file).catch(() => null)
+        if (!stat || stat.mtimeMs < cutoff) continue
+        // A subagent that has handed its answer back is finished however recently it wrote —
+        // the same question `turnEnding` answers for a thread, put to the errand's own transcript.
+        const state = await errandTranscripts.read(file, stat, { sidechain: true }).catch(() => null)
+        if (turnEnding(state).handedBack) continue
+        const out = byParent.get(parent) || []
+        out.push({
+          id: path.basename(file, '.jsonl'),
+          // The prompt a parent handed its subagent, which is the only thing about an errand
+          // worth showing. A forked subagent opens with a `fork-context-ref` and inherits its
+          // parent's context instead of being briefed, so it has no task text to find.
+          task: cleanPrompt(state?.firstPrompt || ''),
+          lastActivityAt: stat.mtimeMs,
+        })
+        byParent.set(parent, out)
+      }
+    }
+  }
+  // Errands are many and short-lived, so the reader keeps only the transcripts this pass read.
+  errandTranscripts.sweep()
+  return byParent
+}
+
+const readDesktopRecords = desktopRecordReader()
+
+/** Every thread the desktop app has a record for, and the ids of the ones it has deleted. */
+const scanDesktopSessions = () => readDesktopRecords(DESKTOP_STORES)
+
+/**
+ * Two desktop records can point at one transcript — resuming a thread that is already
+ * open makes the app write a second, untitled record. Keep the richer of the two.
+ */
+function mergeThread(existing, next) {
+  const better = (a, b) => (a && a !== 'Untitled thread' ? a : b || a)
+  // The titled record is the real thread; an untitled twin is the import ghost. Point
+  // the canonical id at the real one, but keep both so archiving covers the ghost too.
+  const keepExisting = existing.titled || !next.titled
+  return {
+    ...existing,
+    ...next,
+    title: better(existing.title, next.title),
+    titled: existing.titled || next.titled,
+    preview: existing.preview || next.preview,
+    desktopSessionId: keepExisting ? existing.desktopSessionId : next.desktopSessionId,
+    desktopSessionIds: [...new Set([...existing.desktopSessionIds, ...next.desktopSessionIds])],
+    bridgeSessionId: existing.bridgeSessionId || next.bridgeSessionId,
+    model: existing.model || next.model,
+    effort: existing.effort || next.effort,
+    gitBranch: existing.gitBranch || next.gitBranch,
+    cwd: existing.cwd || next.cwd,
+    createdAt: Math.min(existing.createdAt || Infinity, next.createdAt || Infinity) || 0,
+    lastActivityAt: Math.max(existing.lastActivityAt || 0, next.lastActivityAt || 0),
+    lastFocusedAt: Math.max(existing.lastFocusedAt || 0, next.lastFocusedAt || 0),
+    hasError: existing.hasError || next.hasError,
+    turnOutcome: existing.turnOutcome || next.turnOutcome,
+    hasLiveProcess: existing.hasLiveProcess || next.hasLiveProcess,
+    starred: existing.starred || next.starred,
+    routine: existing.routine || next.routine,
+    prState: existing.prState || next.prState,
+    archived: existing.archived && next.archived,
+    hasTranscript: existing.hasTranscript || next.hasTranscript,
+  }
+}
+
+/**
+ * Fold the adapter's private bookkeeping into the shape the rest of the app sees.
+ * The session ids stay, but behind `ref` — an opaque blob the browser hands straight
+ * back on open/archive, so nothing outside this file has to know what a Claude session
+ * id looks like.
+ */
+function toThread(t) {
+  const {
+    desktopSessionId, desktopSessionIds, cliSessionId, bridgeSessionId,
+    titled, hasLiveProcess, transcriptFile, recordActivityAt, turnOutcome, ...rest
+  } = t
+  return {
+    ...rest,
+    canOpen: isDesktopId(desktopSessionId) || isCliId(cliSessionId),
+    // The cwd rides along because resuming from a terminal has to happen in the folder the
+    // session ran in — the worktree, not the repo root.
+    ref: { desktopSessionId, desktopSessionIds, cliSessionId, cwd: t.cwd || '' },
+  }
+}
+
+async function scanThreads() {
+  // The subagent walk needs the live set, and waiting for it here would serialise scans the
+  // README says must never block — so it is handed the promise and waits on it itself.
+  const livePending = readLiveSessions(CLI_LIVE)
+  const [{ records: desktop, deleted }, transcripts, live, subagents] = await Promise.all([
+    scanDesktopSessions(),
+    scanTranscripts(),
+    livePending,
+    scanSubagents(livePending),
+  ])
+  const states = new Map()
+  const read = async (entry) => {
+    const state = await readTranscript(entry)
+    if (state) states.set(entry.file, state)
+    return metaOf(state)
+  }
+  const byId = new Map()
+  const add = (thread) => {
+    const existing = byId.get(thread.id)
+    byId.set(thread.id, existing ? mergeThread(existing, thread) : thread)
+  }
+  const claimed = new Set()
+
+  for (const s of desktop) {
+    const cliSessionId = s.cliSessionId || ''
+    const entry = cliSessionId ? transcripts.get(cliSessionId) : null
+    if (entry) claimed.add(cliSessionId)
+
+    const cwd = s.cwd || s.originCwd || ''
+    const { projectPath, project, worktree } = projectOf(cwd, s.originCwd)
+    const meta = entry ? await read(entry) : null
+    const spokeAt = entry ? states.get(entry.file)?.lastAt || 0 : 0
+
+    add({
+      id: ID(cliSessionId || s.sessionId),
+      cliSessionId,
+      desktopSessionId: s.sessionId || '',
+      desktopSessionIds: s.sessionId ? [s.sessionId] : [],
+      titled: Boolean(s.title),
+      bridgeSessionId: (s.bridgeSessionIds && s.bridgeSessionIds[0]) || '',
+      title: titleFromPrompt(s.title || meta?.customTitle || meta?.aiTitle || meta?.summary || meta?.promptTitle),
+      preview: meta?.firstPrompt ? meta.firstPrompt.slice(0, 240) : '',
+      project,
+      projectPath,
+      worktree,
+      cwd,
+      gitBranch: meta?.gitBranch || '',
+      model: s.model || '',
+      effort: s.effort || '',
+      createdAt: num(s.createdAt) || meta?.startedAt || 0,
+      lastActivityAt:
+        spokeAt ||
+        Math.max(
+          num(s.lastActivityAt) || num(s.lastFocusedAt) || num(s.createdAt) || 0,
+          entry?.mtime || 0
+        ),
+      recordActivityAt: num(s.lastActivityAt) || num(s.lastFocusedAt) || num(s.createdAt) || 0,
+      lastFocusedAt: num(s.lastFocusedAt),
+      hasLiveProcess: live.has(cliSessionId),
+      hasError: Boolean(s.error) || s.turnOutcome === 'failed',
+      turnOutcome: s.turnOutcome || '',
+      starred: s.isStarred === true,
+      routine: s.scheduledTaskId || '',
+      prState: s.prState || '',
+      archived: s.isArchived === true || s.isArchived === 'True',
+      hasTranscript: Boolean(entry),
+      sizeBytes: entry?.size || 0,
+      transcriptFile: entry?.file || '',
+      source: 'desktop',
+    })
+  }
+
+  // Transcripts with no desktop record — threads started straight from the terminal, and threads
+  // the app has since deleted.
+  for (const [id, entry] of transcripts) {
+    if (claimed.has(id)) continue
+    const meta = await read(entry)
+    const cwd = meta.cwd || decodeProjectDir(path.basename(entry.projectDir))
+    const { projectPath, project, worktree } = projectOf(cwd, '')
+    add({
+      id: ID(id),
+      cliSessionId: id,
+      desktopSessionId: '',
+      desktopSessionIds: [],
+      titled: Boolean(meta.customTitle || meta.aiTitle),
+      bridgeSessionId: '',
+      title: titleFromPrompt(meta.customTitle || meta.aiTitle || meta.summary || meta.promptTitle),
+      preview: meta.firstPrompt ? meta.firstPrompt.slice(0, 240) : '',
+      project,
+      projectPath,
+      worktree,
+      cwd,
+      gitBranch: meta.gitBranch,
+      model: '',
+      effort: '',
+      createdAt: meta.startedAt || entry.mtime,
+      lastActivityAt: states.get(entry.file)?.lastAt || entry.mtime,
+      lastFocusedAt: 0,
+      hasLiveProcess: live.has(id),
+      hasError: false,
+      turnOutcome: '',
+      starred: false,
+      routine: '',
+      prState: '',
+      // Deleted in the app, and reported the way an archive made there is. `archived` is the
+      // read-only field an adapter has for "gone from the harness's own UI", and the colony sends
+      // the astronaut home for it exactly as it does for an archive of its own — rather than the
+      // thread simply vanishing from one scan to the next. Only a transcript with no record left
+      // qualifies: resuming a deleted thread makes the app write a fresh record while the marker
+      // stays behind, and a record that exists is the newer truth.
+      archived: deleted.has(id),
+      hasTranscript: true,
+      sizeBytes: entry.size,
+      transcriptFile: entry?.file || '',
+      source: 'cli',
+    })
+  }
+
+  const now = Date.now()
+
+  /**
+   * Drop the app's empty bookkeeping records.
+   *
+   * Resuming a thread makes the desktop app write a second record for the same conversation, and
+   * one of the two carries the title and the transcript link while the other carries nothing.
+   * With no `cliSessionId` on the empty one there is no key to merge the pair on, so it survives
+   * as a thread of its own: an untitled entry with no transcript behind it, standing on the map
+   * as a nameless twin of a thread you have already dealt with.
+   *
+   * A record with no transcript, no title and no live process is not a conversation. The age
+   * check keeps a genuinely new session — opened seconds ago, nothing written yet — out of it.
+   */
+  const NEW_SESSION_MS = 10 * 60 * 1000
+  const threads = [...byId.values()].filter(
+    (t) =>
+      t.hasTranscript ||
+      t.titled ||
+      t.hasLiveProcess ||
+      now - (t.lastActivityAt || t.createdAt || 0) < NEW_SESSION_MS
+  )
+
+  // Unread = a reply came back after you last looked at it; never opened counts as unread.
+  // Terminal-only threads have no focus history at all, so "unread" is unknowable — not true.
+  const handedBackAt = (sessionId) => states.get(transcripts.get(sessionId)?.file)?.handedBackAt || 0
+  for (const thread of threads) {
+    const seenAt = handedBackAt(thread.cliSessionId) || (thread.recordActivityAt ?? thread.lastActivityAt)
+    thread.unread = thread.desktopSessionIds.length > 0 && seenAt > thread.lastFocusedAt
+    const fresh = now - thread.lastActivityAt < ACTIVE_WINDOW_MS
+    const reported = live.get(thread.cliSessionId)?.status || ''
+    const errands = subagents.get(thread.cliSessionId)
+    const peers = thread.hasLiveProcess ? awaitedPeers(states.get(thread.transcriptFile), live, handedBackAt) : []
+    const ending =
+      thread.hasLiveProcess && (fresh || errands || peers.length) && thread.transcriptFile && (!reported || reported === 'idle' || (reported === 'busy' && errands))
+        ? turnEnding(states.get(thread.transcriptFile))
+        : MID_TURN
+    const delegating =
+      (Boolean(errands) && (reported === '' || reported === 'busy') && (ending.handedBack || ending.onAgents)) ||
+      (peers.length > 0 && (reported === '' || reported === 'idle') && ending.handedBack)
+    const waiting = thread.hasLiveProcess && fresh && !delegating && (reported ? reported === 'idle' : ending.handedBack)
+    thread.running = thread.hasLiveProcess && fresh && !delegating && (reported ? reported === 'busy' : !ending.handedBack)
+    thread.awaitingSubagents = delegating
+    thread.needsInput = reported === 'waiting' || (!thread.running && !delegating && thread.turnOutcome === 'blocked')
+    if (waiting && ending.failed) thread.hasError = true
+    // A thread that handed the turn back wants you, whether or not the desktop app has ever seen
+    // it — the only way a terminal-only thread can ask for anything at all.
+    if (waiting) thread.unread = true
+    if (errands) thread.subagents = errands
+    if (peers.length) thread.awaiting = peers.map((p) => ({ id: ID(p.sessionId), title: p.name }))
+  }
+  threadTranscripts.sweep()
+  return threads.map(toThread)
+}
+
+/**
+ * Where the `claude` CLI is, for a machine that has it but no desktop app to answer the deep
+ * link, or a page that would rather have a terminal. PATH first, then the places its installers
+ * put it — never inside an application bundle.
+ */
+const CLI_DIRS = [
+  path.join(HOME, '.local', 'bin'),
+  path.join(HOME, '.claude', 'local'),
+  '/opt/homebrew/bin',
+  '/usr/local/bin',
+  '/usr/bin',
+]
+const VSCODE_EXTENSION_ID = 'anthropic.claude-code'
+const EXTENSION = Object.freeze({
+  name: 'Claude Code for VS Code',
+  download: 'https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code',
+})
+const VSCODE = Object.freeze({ name: 'VS Code', download: 'https://code.visualstudio.com/download' })
+const APP = Object.freeze({ name: 'Claude', download: 'https://claude.com/download', also: Object.freeze([EXTENSION]) })
+
+const vscodeExtensionsDir = () => process.env.THREADCRUMBS_VSCODE_EXTENSIONS_DIR || path.join(HOME, '.vscode', 'extensions')
+
+async function vscodeExtension() {
+  const root = vscodeExtensionsDir()
+  let installed
+  try {
+    installed = JSON.parse(await fsp.readFile(path.join(root, 'extensions.json'), 'utf8'))
+  } catch {
+    return null
+  }
+  const entry = Array.isArray(installed) ? installed.find((e) => String(e?.identifier?.id).toLowerCase() === VSCODE_EXTENSION_ID) : null
+  const folder = typeof entry?.relativeLocation === 'string' ? path.join(root, path.basename(entry.relativeLocation)) : ''
+  if (!folder || !(await exists(folder))) return null
+  const cli = path.join(folder, 'resources', 'native-binary', process.platform === 'win32' ? 'claude.exe' : 'claude')
+  return { cli: (await exists(cli)) ? cli : null }
+}
+
+const claudeCli = async (extension) => (await findExecutable('claude', CLI_DIRS)) || extension?.cli || null
+
+const vscodeFolder = (dir) => `vscode://file/${encodeURI(dir.replace(/\\/g, '/'))}`
+
+function inVsCode(extension, dir, session) {
+  if (!extension || typeof dir !== 'string' || !path.isAbsolute(dir)) return undefined
+  const open = `vscode://${VSCODE_EXTENSION_ID}/open${session ? `?${new URLSearchParams({ session })}` : ''}`
+  return { app: VSCODE, urls: [vscodeFolder(dir), open], note: "Opened in VS Code's Claude Code panel, since the Claude app isn't installed" }
+}
+
+/**
+ * The pid of the live CLI process behind a session, if any. `readLiveSessions` probes each pid
+ * before it counts, because the registry's files outlive their pids.
+ */
+async function liveSessionPid(sessionId) {
+  return (await readLiveSessions(CLI_LIVE)).get(sessionId)?.pid || 0
+}
+
+/**
+ * Hands the thread back to Claude Code. `epitaxy/<local_…>` *navigates* the desktop app
+ * to a thread it already has; `resume` *imports* the transcript, which spawns a second
+ * untitled session and rewrites the .jsonl — so it is only ever the fallback for threads
+ * the app has never seen. Ids are pattern-checked before they reach the opener.
+ *
+ * A terminal-started thread that is still running gets its live pid handed along too: it
+ * already has a window somewhere on this machine, and fronting that window is a better answer
+ * than `resume` importing the transcript into the desktop app as a second, untitled session.
+ * Whether and how to front it is the app's call — Threadnauts does it in `server/lib/windows.mjs`.
+ */
+async function openThread(ref) {
+  const { desktopSessionId, cliSessionId, cwd } = ref || {}
+  let url = ''
+  if (isDesktopId(desktopSessionId)) url = `claude://claude.ai/epitaxy/${desktopSessionId}`
+  else if (isCliId(cliSessionId)) url = `claude://resume?session=${cliSessionId}`
+
+  // Only threads the desktop app has never seen: for the rest the deep link navigates to the
+  // tab the app already has, which is exactly the right window to front.
+  let pid = 0
+  if (!isDesktopId(desktopSessionId) && isCliId(cliSessionId)) pid = await liveSessionPid(cliSessionId)
+
+  let command
+  let fallback
+  if (isCliId(cliSessionId)) {
+    const extension = await vscodeExtension()
+    const bin = await claudeCli(extension)
+    if (bin) command = { argv: [bin, '--resume', cliSessionId], cwd: typeof cwd === 'string' ? cwd : '' }
+    if (!pid) fallback = inVsCode(extension, cwd, cliSessionId)
+  }
+
+  if (!url && !command) return { ok: false, error: 'No openable session id on that thread' }
+  return { ok: true, url, command, pid, app: APP, fallback }
+}
+
+/**
+ * A brand new thread rooted in a repo — the same `code/new?folder=` deep link Finder's
+ * "New Claude Code Session Here" quick action uses. Nothing is resumed and nothing is
+ * written: the desktop app just opens an empty session with that folder as its workspace.
+ */
+async function newSession(dir) {
+  // The Scratch plot's folder holds the desktop app's own scratch sessions. A session opened on
+  // it, or the CLI run in it, would work inside the app's data rather than in a repo of yours.
+  if (SCRATCH_ROOT.test(dir)) {
+    return { ok: false, error: 'Scratch threads have no folder of their own; start one in the Claude app' }
+  }
+
+  const url = `claude://code/new?${new URLSearchParams({ folder: dir })}`
+  const extension = await vscodeExtension()
+  const bin = await claudeCli(extension)
+  const command = bin ? { argv: [bin], cwd: dir } : undefined
+  return { ok: true, url, command, app: APP, fallback: inVsCode(extension, dir, '') }
+}
+
+export default {
+  id: 'claude-code',
+  name: 'Claude Code',
+  app: APP,
+  /** Only claim this machine if one of the two stores is actually there. */
+  detect: async () => (await Promise.all(DESKTOP_STORES.map(exists))).some(Boolean) || (await exists(CLI_PROJECTS)),
+  scanThreads,
+  openThread,
+  newSession,
+  paths: { DESKTOP_STORES, CLI_PROJECTS, CLI_LIVE },
+}