@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/adapters/claude-code/reader.ts

@@ -0,0 +1,639 @@
+import { readFileSync, statSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+import { exists, findFiles, gitInfo, ls, mtime, readJson, readJsonl } from "../../fsutil.ts"
+import type { Attachment, Session, SessionHeader, Turn, Usage } from "../../session/types.ts"
+import { keepImage } from "../../session/attachments.ts"
+import { peekCache } from "../../session/peekcache.ts"
+import { clip, header, iso, lossCounter, noteModel, toolKindOf } from "../../session/util.ts"
+import type { Reader, SessionRef } from "../types.ts"
+import { CHAIN_TYPES, CONTINUED_NOTE, FILE_ATTACHMENTS, HOUSEKEEPING, LABEL, SESSION_FILE, TOOL, projectSlug, projectsDir } from "./records.ts"
+
+// Reads Claude Code transcripts: <home>/.claude/projects/<project>/<session>.jsonl, with subagents in
+// <session>/subagents/ and spilled tool outputs in <session>/tool-results/.
+//
+// A transcript is a tree, not a list: every conversation record has a uuid and a parentUuid, and a file
+// keeps abandoned branches (rewinds, retries) beside the live one. The session is the line from the
+// newest leaf back to the root. Quirks of real files shape the walk: parallel tool results each hang off
+// the record of their own tool_use, so all but the last sit on side branches (and a few carry no parent
+// link at all), so results are re-attached by tool_use id; a few files have a parent that was never
+// written or a loop, where the walk bridges to the record before in the file instead of stopping; and a
+// result can be written before its call, so it waits for the call.
+
+type Row = Record<string, any>
+type Lost = ReturnType<typeof lossCounter>
+
+const HEAD = 64 * 1024
+const TAIL = 256 * 1024
+
+const lastMatch = (text: string, re: RegExp): string | undefined => {
+  let out: string | undefined
+  for (const m of text.matchAll(re)) out = m[1]
+  return out
+}
+const jsonString = (raw: string | undefined): string | undefined => {
+  if (raw === undefined) return undefined
+  try {
+    return JSON.parse(`"${raw}"`) as string
+  } catch {
+    return undefined
+  }
+}
+// Claude Code writes compact JSON, but transcripts written by other programs (which Claude Code resumes
+// just the same) may put spaces around the colon.
+const CWD = /"cwd"\s*:\s*"((?:[^"\\]|\\.)*)"/
+const RELOCATED = /"relocatedCwd"\s*:\s*"((?:[^"\\]|\\.)*)"/g
+const TIMESTAMP = /"timestamp"\s*:\s*"((?:[^"\\]|\\.)*)"/g
+
+/** The title records in a stretch of the file: the newest custom title, else the newest AI title or summary. */
+function titlesIn(text: string): { custom?: string; ai?: string } {
+  const out: { custom?: string; ai?: string } = {}
+  for (const line of text.split("\n")) {
+    if (!line.includes('"customTitle"') && !line.includes('"aiTitle"') && !line.includes('"summary"')) continue
+    let r: Row
+    try {
+      r = JSON.parse(line)
+    } catch {
+      continue
+    }
+    if (r.type === "custom-title" && typeof r.customTitle === "string" && r.customTitle.trim()) out.custom = r.customTitle
+    if (r.type === "ai-title" && typeof r.aiTitle === "string" && r.aiTitle.trim()) out.ai = r.aiTitle
+    if (r.type === "summary" && typeof r.summary === "string" && r.summary.trim()) out.ai = r.summary
+  }
+  return out
+}
+
+/** A file's modified time in ms, or 0 when it is missing. */
+const mtimeMs = (p: string) => {
+  try {
+    return statSync(p).mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+/** Title, cwd and last activity from the start and end of a transcript, without reading the whole file. */
+async function peek(path: string, sessionDir: string): Promise<{ title?: string; cwd?: string; updatedAt?: string } | undefined> {
+  const file = Bun.file(path)
+  const size = file.size
+  const head = await file.slice(0, Math.min(size, HEAD)).text()
+  const tail = size > HEAD ? await file.slice(Math.max(HEAD, size - TAIL)).text() : ""
+  let whole: string | undefined
+  // The session's folder is the one its first record names (the project folder is named after it); later
+  // records name wherever the shell had moved to, so the tail is no substitute when the head has none.
+  // First records can be huge (a pasted file), so a growing prefix is read until one names its cwd.
+  let cwd = jsonString(head.match(CWD)?.[1])
+  for (let n = HEAD * 16, read = Math.min(size, HEAD); !cwd && read < size; n *= 4) {
+    read = Math.min(size, n)
+    const prefix = await file.slice(0, read).text()
+    cwd = jsonString(prefix.match(CWD)?.[1])
+    if (read === size) whole = prefix
+  }
+  // A file with no cwd anywhere has no conversation records (only metadata): nothing to continue.
+  if (!cwd) return undefined
+  // After /cd the session moves to another project folder and says so in `relocated` records. They are
+  // stamped again and again, so the tail nearly always has one; the whole file is searched only when the
+  // folder the session sits in does not match its first cwd.
+  let moved = whole === undefined ? lastMatch(tail, RELOCATED) ?? lastMatch(head, RELOCATED) : lastMatch(whole, RELOCATED)
+  if (!moved && whole === undefined && size > HEAD + TAIL && projectSlug(cwd) !== basename(dirname(path))) moved = lastMatch(await file.text(), RELOCATED)
+  cwd = jsonString(moved) ?? cwd
+  const fromTail = titlesIn(tail)
+  const fromHead = titlesIn(head)
+  const titleFile = readJson<{ customTitle?: string }>(join(sessionDir, "custom-title.json"))?.customTitle
+  const title = fromTail.custom ?? fromHead.custom ?? (titleFile?.trim() ? titleFile : undefined) ?? fromTail.ai ?? fromHead.ai
+  const updatedAt = lastTimestamp(tail || head) ?? mtime(path)
+  return { ...(title ? { title } : {}), cwd, ...(updatedAt ? { updatedAt } : {}) }
+}
+
+/**
+ * The newest record's own timestamp in a stretch of the file. Records written last (file-history snapshots,
+ * cost state) carry timestamps nested inside them that are not activity, so lines are parsed from the end;
+ * a stretch that is one huge partial line falls back to the last timestamp anywhere in it.
+ */
+function lastTimestamp(text: string): string | undefined {
+  const lines = text.split("\n")
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i]!.includes('"timestamp"')) continue
+    try {
+      const when = iso(JSON.parse(lines[i]!).timestamp)
+      if (when) return when
+    } catch {
+      // the stretch's first line is usually cut
+    }
+  }
+  return iso(lastMatch(text, TIMESTAMP))
+}
+
+/**
+ * The live conversation: the records from the newest leaf back to the root, plus the results of its tool
+ * calls wherever they hang, in file order. File order is append order, so a rewound branch written
+ * later wins, and turns before a compaction (reached through logicalParentUuid) come first.
+ */
+export function mainLine(rows: Row[]): Row[] {
+  // Tree records always carry parentUuid (null at a root); a record without the key is not on the tree.
+  const nodes: number[] = []
+  for (let i = 0; i < rows.length; i++) if (typeof rows[i]!.uuid === "string" && "parentUuid" in rows[i]! && CHAIN_TYPES.has(rows[i]!.type)) nodes.push(i)
+  if (!nodes.length) return []
+  const at = new Map<string, number>()
+  for (const i of nodes) at.set(rows[i]!.uuid, i)
+  // A compaction boundary hangs off the conversation it summarised through logicalParentUuid, which is
+  // sometimes a record that was never written. The newest message the compaction kept verbatim (the tail of
+  // its preserved segment) is that same point, when it was written before the boundary.
+  const parentOf = (r: Row, i: number): string | undefined => {
+    if (r.parentUuid) return r.parentUuid
+    if (r.logicalParentUuid === undefined || at.has(r.logicalParentUuid)) return r.logicalParentUuid
+    const cm: Row = r.compactMetadata ?? {}
+    const tail = cm.preservedSegment?.tailUuid ?? (Array.isArray(cm.preservedMessages?.uuids) ? cm.preservedMessages.uuids.at(-1) : undefined)
+    return typeof tail === "string" && (at.get(tail) ?? i) < i ? tail : r.logicalParentUuid
+  }
+  const keep = new Set<number>()
+  let earliest = Number.POSITIVE_INFINITY
+  let cur: number | undefined = nodes[nodes.length - 1]
+  for (;;) {
+    let root = false
+    while (cur !== undefined && !keep.has(cur)) {
+      keep.add(cur)
+      earliest = Math.min(earliest, cur)
+      const r: Row = rows[cur]!
+      const parent = parentOf(r, cur)
+      if (!parent) {
+        // A prompt with no parent is where the conversation (or a rewind to its start) begins; a system or
+        // attachment record with no parent mid-file is not.
+        root = r.type === "user"
+        break
+      }
+      cur = at.get(parent)
+    }
+    if (root) break
+    // Broken link, loop or a stray root: carry on from the nearest earlier record not yet on the line.
+    const before = nodes.filter((i) => i < earliest && !keep.has(i))
+    if (!before.length) break
+    cur = before[before.length - 1]
+  }
+  // The other records of each response on the line: a response is split one block per record, and with
+  // parallel calls the conversation can carry on from an earlier block's result, leaving the later blocks
+  // (and their calls) on a side branch. Claude Code's own loader gathers them by message.id the same way.
+  const responses = new Set<string>()
+  for (const i of keep) if (rows[i]!.type === "assistant" && typeof rows[i]!.message?.id === "string") responses.add(rows[i]!.message.id)
+  for (const i of nodes) if (!keep.has(i) && rows[i]!.type === "assistant" && responses.has(rows[i]!.message?.id)) keep.add(i)
+  // Results for calls on the line, wherever they hang: parallel results sit on side branches, and a few
+  // result records carry no parent link at all. Matched by tool_use id, not by parent.
+  const blocks = (r: Row, type: string): Row[] => (Array.isArray(r.message?.content) ? r.message.content.filter((b: Row) => b?.type === type) : [])
+  const called = new Set<string>()
+  const answered = new Set<string>()
+  for (const i of keep) {
+    for (const b of blocks(rows[i]!, "tool_use")) called.add(b.id)
+    for (const b of blocks(rows[i]!, "tool_result")) answered.add(b.tool_use_id)
+  }
+  for (let i = 0; i < rows.length; i++) {
+    if (keep.has(i) || rows[i]!.type !== "user") continue
+    const ids = blocks(rows[i]!, "tool_result").map((b) => b.tool_use_id).filter((id) => called.has(id) && !answered.has(id))
+    if (!ids.length) continue
+    keep.add(i)
+    for (const id of ids) answered.add(id)
+  }
+  return [...keep].sort((a, b) => a - b).map((i) => rows[i]!)
+}
+
+function usageOf(u: Row | undefined): Usage | undefined {
+  if (!u || typeof u !== "object") return undefined
+  const out: Usage = {}
+  if (typeof u.input_tokens === "number") out.input = u.input_tokens
+  if (typeof u.output_tokens === "number") out.output = u.output_tokens
+  if (typeof u.cache_read_input_tokens === "number") out.cacheRead = u.cache_read_input_tokens
+  if (typeof u.cache_creation_input_tokens === "number") out.cacheWrite = u.cache_creation_input_tokens
+  return Object.keys(out).length ? out : undefined
+}
+
+/** A tool result's content as text; images and documents inside it are counted, not carried. */
+function resultText(content: unknown, lost: Lost): string {
+  if (typeof content === "string") return content
+  if (!Array.isArray(content)) return content === undefined || content === null ? "" : JSON.stringify(content)
+  const parts: string[] = []
+  for (const b of content as Row[]) {
+    if (b?.type === "text" && typeof b.text === "string") parts.push(b.text)
+    else if (b?.type === "image") lost.add("images in tool results")
+    else if (b?.type === "document") lost.add("documents in tool results")
+    else if (b?.type === "tool_reference") parts.push(`[tool loaded: ${b.tool_name}]`)
+    else parts.push(JSON.stringify(b))
+  }
+  return parts.join("\n")
+}
+
+const PERSISTED = /<persisted-output>[\s\S]*?Full output saved to: (\S+)/
+
+/** Where Claude Code spilled a large output: Bash says so in toolUseResult, other tools in a <persisted-output> preview. */
+function spilled(tur: unknown, text: string): { spilled: boolean; path?: string } {
+  const fromResult = tur && typeof tur === "object" ? (tur as Row).persistedOutputPath : undefined
+  const path = typeof fromResult === "string" ? fromResult : text.match(PERSISTED)?.[1]
+  if (!path) return { spilled: false }
+  return exists(path) ? { spilled: true, path } : { spilled: true }
+}
+
+/** Edit and Write results carry the change as hunks; turned into a unified diff. */
+function patchOf(tur: Row): string | undefined {
+  const hunks = Array.isArray(tur.structuredPatch) ? (tur.structuredPatch as Row[]) : []
+  const body = hunks
+    .filter((h) => Array.isArray(h?.lines))
+    .map((h) => `@@ -${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines} @@\n${(h.lines as string[]).join("\n")}`)
+  if (!body.length && tur.type === "create" && typeof tur.content === "string") {
+    const lines = tur.content.split("\n")
+    body.push(`@@ -0,0 +1,${lines.length} @@\n${lines.map((l: string) => `+${l}`).join("\n")}`)
+  }
+  if (!body.length) return undefined
+  return clip(`--- a/${tur.filePath}\n+++ b/${tur.filePath}\n${body.join("\n")}`).text
+}
+
+/** Plain text of a user message's content (string or blocks). */
+const textOf = (c: unknown): string =>
+  typeof c === "string" ? c : Array.isArray(c) ? (c as Row[]).filter((b) => b?.type === "text").map((b) => String(b.text ?? "")).join("\n\n") : ""
+
+/**
+ * Turns for one transcript's records. Fills `h` (project, times, models, version) and counts what is
+ * dropped into `lost`; also returns the sessionId on the first live record, which differs from the file's
+ * own id when the session was forked from another.
+ */
+function convert(rows: Row[], h: SessionHeader, lost: Lost): { turns: Turn[]; firstSessionId?: string } {
+  for (const r of rows) {
+    const t = r.type
+    if (typeof t === "string" && !CHAIN_TYPES.has(t) && !HOUSEKEEPING.has(t)) lost.add(`unknown record type: ${t}`)
+  }
+  const turns: Turn[] = []
+  const calls = new Set<string>()
+  const results = new Set<string>()
+  const textTurn = new Map<string, Extract<Turn, { kind: "assistant" }>>()
+  const usage = new Map<string, Usage>()
+  let lastMessageId: string | undefined
+  let compacting: Row | undefined
+  let lastUser: Extract<Turn, { kind: "user" }> | undefined
+  // Where each record's turns begin, so a compaction can be placed before the messages it kept verbatim.
+  const startOf = new Map<string, number>()
+
+  const user = (text: string, at: string | undefined, attachments: Attachment[] = []) => {
+    const t: Extract<Turn, { kind: "user" }> = { kind: "user", ...(at ? { at } : {}), text, ...(attachments.length ? { attachments } : {}) }
+    turns.push(t)
+    lastUser = t
+  }
+
+  // A result can sit in the file before its call (a response record rewritten later); it waits for the call.
+  const early = new Map<string, { b: Row; tur: unknown; at: string | undefined }>()
+  const result = (b: Row, tur: unknown, at: string | undefined) => {
+    const id = b.tool_use_id
+    if (typeof id !== "string" || results.has(id)) return
+    if (!calls.has(id)) {
+      if (!early.has(id)) early.set(id, { b, tur, at })
+      return
+    }
+    results.add(id)
+    const text = resultText(b.content, lost)
+    const spill = spilled(tur, text)
+    const c = clip(text)
+    turns.push({
+      kind: "tool_result",
+      ...(at ? { at } : {}),
+      callId: id,
+      ok: !b.is_error,
+      output: c.text,
+      ...(c.truncated || spill.spilled ? { truncated: true } : {}),
+      ...(spill.path ? { fullPath: spill.path } : {}),
+    })
+    if (!b.is_error && tur && typeof tur === "object" && typeof (tur as Row).filePath === "string" && "structuredPatch" in (tur as Row)) {
+      const patch = patchOf(tur as Row)
+      turns.push({ kind: "file_edit", ...(at ? { at } : {}), path: (tur as Row).filePath, ...(patch ? { patch } : {}), callId: id })
+    }
+  }
+
+  /** Image and document blocks of a prompt, as attachments; the bytes stay behind and are counted. */
+  const inlineFiles = (c: unknown): Attachment[] => {
+    const out: Attachment[] = []
+    for (const b of (Array.isArray(c) ? c : []) as Row[]) {
+      if (b?.type === "image") {
+        const kept = b.source?.type === "base64" && typeof b.source.data === "string" ? keepImage(b.source.data, b.source.media_type) : undefined
+        if (kept) out.push(kept)
+        else {
+          out.push({ kind: "image", ...(b.source?.media_type ? { mime: b.source.media_type } : {}) })
+          lost.add("inline images")
+        }
+      } else if (b?.type === "document") {
+        out.push({ kind: "file", ...(b.source?.media_type ? { mime: b.source.media_type } : {}) })
+        lost.add("inline documents")
+      }
+    }
+    return out
+  }
+
+  const line = mainLine(rows)
+  for (const r of line) {
+    if (typeof r.uuid === "string") startOf.set(r.uuid, turns.length)
+    const at = iso(r.timestamp)
+    if (at) {
+      h.startedAt ??= at
+      h.updatedAt = at
+    }
+    if (typeof r.version === "string") h.toolVersion = r.version
+    if (!h.project.cwd && typeof r.cwd === "string") h.project.cwd = r.cwd
+    if (typeof r.gitBranch === "string" && r.gitBranch) h.project.gitBranch = r.gitBranch
+    const messageId = r.type === "assistant" && typeof r.message?.id === "string" ? (r.message.id as string) : undefined
+    const sameMessage = messageId !== undefined && messageId === lastMessageId
+    lastMessageId = messageId
+
+    if (r.type === "system") {
+      if (r.subtype === "compact_boundary") compacting = r
+      continue
+    }
+
+    if (r.type === "attachment") {
+      const a: Row = r.attachment ?? {}
+      // A prompt typed while the model was working reaches it as a queued_command attachment, not a user record.
+      if (a.type === "queued_command" && !a.isMeta) {
+        const text = typeof a.prompt === "string" ? a.prompt : textOf(a.prompt)
+        const files = inlineFiles(a.prompt)
+        if (text.trim() || files.length) user(text, at, files)
+      } else if (FILE_ATTACHMENTS.has(a.type) && typeof a.filename === "string" && lastUser) {
+        const list = (lastUser.attachments ??= [])
+        if (!list.some((x) => x.path === a.filename)) {
+          list.push({ kind: "file", path: a.filename, ...(typeof a.displayPath === "string" ? { name: a.displayPath } : {}), ...(a.type === "pdf_reference" ? { mime: "application/pdf" } : {}) })
+        }
+      }
+      continue
+    }
+
+    if (r.type === "assistant") {
+      const m: Row = r.message ?? {}
+      // API errors and local placeholders ("No response requested.") are not the model's words.
+      if (r.isApiErrorMessage || m.model === "<synthetic>") continue
+      noteModel(h, m.model)
+      // One response is split over several records sharing message.id; each repeats usage, the last is final.
+      const u = usageOf(m.usage)
+      if (messageId && u) usage.set(messageId, u)
+      for (const b of (Array.isArray(m.content) ? m.content : []) as Row[]) {
+        switch (b?.type) {
+          case "text": {
+            if (typeof b.text !== "string" || !b.text.trim()) break
+            const own = messageId ? textTurn.get(messageId) : undefined
+            if (sameMessage && own && turns[turns.length - 1] === own) own.text += `\n\n${b.text}`
+            else {
+              const t: Extract<Turn, { kind: "assistant" }> = { kind: "assistant", ...(at ? { at } : {}), text: b.text, ...(m.model ? { model: m.model } : {}) }
+              turns.push(t)
+              if (messageId && !textTurn.has(messageId)) textTurn.set(messageId, t)
+            }
+            break
+          }
+          case "thinking":
+            if (typeof b.thinking === "string" && b.thinking.trim()) turns.push({ kind: "reasoning", ...(at ? { at } : {}), text: b.thinking })
+            else lost.add("signed reasoning")
+            break
+          case "redacted_thinking":
+            lost.add("redacted reasoning")
+            break
+          case "tool_use":
+          case "server_tool_use":
+          case "mcp_tool_use":
+            if (typeof b.id !== "string" || calls.has(b.id)) break
+            calls.add(b.id)
+            turns.push({ kind: "tool_call", ...(at ? { at } : {}), id: b.id, name: String(b.name ?? "unknown"), toolKind: toolKindOf(String(b.name ?? "")), input: b.input ?? {} })
+            if (early.has(b.id)) {
+              const e = early.get(b.id)!
+              early.delete(b.id)
+              result(e.b, e.tur, e.at)
+            }
+            break
+          default:
+            // Server-side tools (web search, fetch) answer inside the assistant message itself.
+            if (typeof b?.type === "string" && b.type.endsWith("_tool_result")) result(b, undefined, at)
+            else lost.add(`unknown content: ${String(b?.type)}`)
+        }
+      }
+      continue
+    }
+
+    if (r.type === "user") {
+      if (r.isMeta) continue
+      const c = r.message?.content
+      if (r.isCompactSummary || compacting) {
+        const boundary = compacting
+        compacting = undefined
+        if (r.isCompactSummary) {
+          // A compaction keeps its newest messages verbatim. Claude Code shows them after the summary, but
+          // they are often written before the boundary, so the summary goes in front of the first of them:
+          // a compaction turn replaces only the turns before it.
+          const cm: Row = boundary?.compactMetadata ?? {}
+          const kept: unknown[] = Array.isArray(cm.preservedMessages?.uuids) ? cm.preservedMessages.uuids : [cm.preservedSegment?.headUuid]
+          const starts = kept.map((u) => startOf.get(u as string)).filter((n): n is number => n !== undefined)
+          const t: Turn = { kind: "compaction", ...(at ? { at } : {}), summary: textOf(c) }
+          if (starts.length) turns.splice(Math.min(...starts), 0, t)
+          else turns.push(t)
+          continue
+        }
+      }
+      if (typeof c === "string") {
+        if (c.trim()) user(c, at)
+        continue
+      }
+      if (!Array.isArray(c)) continue
+      const texts: string[] = []
+      const attachments = inlineFiles(c)
+      const nResults = c.filter((b: Row) => b?.type === "tool_result").length
+      for (const b of c as Row[]) {
+        if (b?.type === "text") {
+          if (typeof b.text === "string" && b.text.trim()) texts.push(b.text)
+        } else if (b?.type === "tool_result") result(b, nResults === 1 ? r.toolUseResult : undefined, at)
+        else if (b?.type !== "image" && b?.type !== "document") lost.add(`unknown content: ${String(b?.type)}`)
+      }
+      if (texts.length || attachments.length) user(texts.join("\n\n"), at, attachments)
+    }
+  }
+  if (early.size) lost.add("tool results without a call", early.size)
+  for (const [id, t] of textTurn) {
+    const u = usage.get(id)
+    if (u) t.usage = u
+  }
+  const sid = line.find((r) => typeof r.sessionId === "string")?.sessionId
+  return { turns, ...(sid ? { firstSessionId: sid as string } : {}) }
+}
+
+function parseLines(text: string): { rows: Row[]; bad: number } {
+  const rows: Row[] = []
+  let bad = 0
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue
+    try {
+      rows.push(JSON.parse(line))
+    } catch {
+      bad++
+    }
+  }
+  return { rows, bad }
+}
+
+/** A transcript's records; subagent transcripts are sometimes gzipped. */
+function records(path: string): { rows: Row[]; bad: number } {
+  if (!path.endsWith(".gz")) return readJsonl(path)
+  return parseLines(new TextDecoder().decode(Bun.gunzipSync(readFileSync(path))))
+}
+
+/** One transcript as a session (children not attached). */
+function sessionOf(rows: Row[], bad: number, sourceId: string, path: string, extra: Partial<SessionHeader> = {}): Session & { firstSessionId?: string } {
+  const h = header(TOOL, sourceId, { sourcePath: path, ...extra })
+  const lost = lossCounter()
+  if (bad) lost.add("unreadable lines", bad)
+  const { turns, firstSessionId } = convert(rows.filter((r) => r && typeof r === "object" && !Array.isArray(r)), h, lost)
+  lost.flush(h)
+  // Titles are written over and over (Claude Desktop rewrites them); the newest wins.
+  let custom: string | undefined
+  let ai: string | undefined
+  let moved: string | undefined
+  for (const r of rows) {
+    if (r?.type === "custom-title" && typeof r.customTitle === "string" && r.customTitle.trim()) custom = r.customTitle
+    if (r?.type === "ai-title" && typeof r.aiTitle === "string" && r.aiTitle.trim()) ai = r.aiTitle
+    if (r?.type === "summary" && typeof r.summary === "string" && r.summary.trim()) ai = r.summary
+    if (r?.type === "relocated" && typeof r.relocatedCwd === "string" && r.relocatedCwd) moved = r.relocatedCwd
+  }
+  // After /cd the session belongs to the folder it moved to (its transcript moves to that project folder).
+  if (moved) h.project.cwd = moved
+  const titleFile = readJson<{ customTitle?: string }>(join(path.replace(/\.jsonl(\.gz)?$/, ""), "custom-title.json"))?.customTitle
+  h.title ??= custom ?? (titleFile?.trim() ? titleFile : undefined) ?? ai
+  // The last activity is the newest timestamp on any record, not only the conversation's.
+  for (let i = rows.length - 1; i >= 0; i--) {
+    const when = iso(rows[i]?.timestamp)
+    if (when) {
+      if (!h.updatedAt || when > h.updatedAt) h.updatedAt = when
+      break
+    }
+  }
+  return { header: h, turns, ...(firstSessionId ? { firstSessionId } : {}) }
+}
+
+interface Child {
+  agentId: string
+  session: Session
+  meta: Row
+}
+
+/** Subagent transcripts under <session>/subagents (workflow agents included), nested by parentAgentId. */
+function children(sessionDir: string, parent: Session, sid: string): Session[] {
+  const dir = join(sessionDir, "subagents")
+  if (!exists(dir)) return []
+  const byAgent = new Map<string, Child>()
+  const files = findFiles(dir, (n) => /^agent-.+\.jsonl(\.gz)?$/.test(n), 6).sort((a, b) => Number(a.endsWith(".gz")) - Number(b.endsWith(".gz")))
+  const lost = lossCounter()
+  for (const file of files) {
+    const agentId = basename(file).replace(/^agent-/, "").replace(/\.jsonl(\.gz)?$/, "")
+    if (byAgent.has(agentId)) continue
+    const meta = readJson<Row>(file.replace(/\.jsonl(\.gz)?$/, ".meta.json")) ?? {}
+    let read: { rows: Row[]; bad: number }
+    try {
+      read = records(file)
+    } catch {
+      lost.add("unreadable subagent transcripts")
+      continue
+    }
+    const session = sessionOf(read.rows, read.bad, `${sid}/agent-${agentId}`, file, {
+      ...(typeof meta.description === "string" ? { title: meta.description } : {}),
+      parent: { id: parent.header.id, kind: "subagent" },
+    })
+    delete session.firstSessionId
+    byAgent.set(agentId, { agentId, session, meta })
+  }
+  lost.flush(parent.header)
+  // Agents spawned by a subagent belong to it; the rest to the session.
+  const top: Child[] = []
+  const under = new Map<string, Child[]>()
+  for (const c of byAgent.values()) {
+    const p = typeof c.meta.parentAgentId === "string" ? byAgent.get(c.meta.parentAgentId) : undefined
+    if (p && p !== c) {
+      c.session.header.parent = { id: p.session.header.id, kind: "subagent" }
+      under.set(p.agentId, [...(under.get(p.agentId) ?? []), c])
+    } else top.push(c)
+  }
+  for (const c of byAgent.values()) attach(c.session, under.get(c.agentId) ?? [])
+  attach(parent, top)
+  return parent.children ?? []
+}
+
+/**
+ * Adds subagent turns: right after the Agent call that spawned each child (meta.toolUseId), or, for
+ * workflow agents that record no call, at the point in time the child started.
+ */
+function attach(s: Session, kids: Child[]) {
+  if (!kids.length) return
+  kids.sort((a, b) => (a.session.header.startedAt ?? "").localeCompare(b.session.header.startedAt ?? ""))
+  const turnFor = (c: Child, callId?: string): Turn => ({
+    kind: "subagent",
+    ...(c.session.header.startedAt ? { at: c.session.header.startedAt } : {}),
+    sessionId: c.session.header.id,
+    ...(callId ? { callId } : {}),
+    ...(typeof c.meta.description === "string" ? { description: c.meta.description } : {}),
+  })
+  const callIds = new Set(s.turns.filter((t) => t.kind === "tool_call").map((t) => (t as Extract<Turn, { kind: "tool_call" }>).id))
+  const afterCall = new Map<string, Turn[]>()
+  const byTime: Turn[] = []
+  for (const c of kids) {
+    const id = c.meta.toolUseId
+    if (typeof id === "string" && callIds.has(id)) afterCall.set(id, [...(afterCall.get(id) ?? []), turnFor(c, id)])
+    else byTime.push(turnFor(c))
+  }
+  const out: Turn[] = []
+  for (const t of s.turns) {
+    while (byTime.length && t.at && byTime[0]!.at && byTime[0]!.at < t.at) out.push(byTime.shift()!)
+    out.push(t)
+    if (t.kind === "tool_call") out.push(...(afterCall.get(t.id) ?? []))
+  }
+  out.push(...byTime)
+  s.turns = out
+  s.children = kids.map((c) => c.session)
+}
+
+export const claudeCodeReader: Reader = {
+  tool: TOOL,
+  label: LABEL,
+
+  async list(home: string): Promise<SessionRef[]> {
+    const root = projectsDir(home)
+    const refs: SessionRef[] = []
+    // Peeking opens every transcript; the result is reused while a file's size and time (and its title file's) are unchanged.
+    const cache = peekCache(home, "claude-peek", 1)
+    for (const project of ls(root)) {
+      const dir = join(root, project)
+      for (const name of ls(dir)) {
+        if (!SESSION_FILE.test(name)) continue
+        const path = join(dir, name)
+        try {
+          const st = statSync(path)
+          if (!st.isFile()) continue
+          const sessionDir = path.slice(0, -".jsonl".length)
+          const titleTime = mtimeMs(join(sessionDir, "custom-title.json"))
+          const p = await cache.get(path, st, titleTime, () => peek(path, sessionDir))
+          if (p) refs.push({ tool: TOOL, sourceId: name.slice(0, -".jsonl".length), path, ...p })
+        } catch {
+          // Deleted or unreadable between listing and peeking: not a session to offer.
+        }
+      }
+    }
+    cache.flush()
+    return refs.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""))
+  },
+
+  async read(ref: SessionRef, _home: string): Promise<Session> {
+    if (!exists(ref.path)) throw new Error(`no Claude Code transcript at ${ref.path}`)
+    const { rows, bad } = readJsonl(ref.path)
+    if (!rows.length) throw new Error(`${ref.path} has no readable records`)
+    const sid = basename(ref.path, ".jsonl")
+    const { firstSessionId, ...s } = sessionOf(rows, bad, sid, ref.path)
+    const h = s.header
+    // brain's note on a continued session is an isMeta record (skipped as a turn); read where it came from from the raw
+    // record. Sessions written before the note was meta carry it as the first user turn: it is ours, not the person's words.
+    const noteRow = rows.find((r) => r.type === "user" && typeof r.message?.content === "string" && CONTINUED_NOTE.test(r.message.content))
+    const continued = (noteRow?.message.content as string | undefined)?.match(CONTINUED_NOTE)?.[1]
+    if (continued) {
+      h.parent = { id: continued, kind: "continued" }
+      const i = s.turns.findIndex((t) => t.kind === "user" && CONTINUED_NOTE.test(t.text))
+      if (i >= 0) s.turns.splice(i, 1)
+    } else if (firstSessionId && firstSessionId !== sid) h.parent = { id: `${TOOL}:${firstSessionId}`, kind: "fork" }
+    if (h.project.cwd) {
+      const remote = gitInfo(h.project.cwd).gitRemote
+      if (remote) h.project.gitRemote = remote
+    }
+    children(ref.path.slice(0, -".jsonl".length), s, sid)
+    return s
+  },
+}