dsh-treecom 0.0.0-stage → 1.0.1

package/index.js

@@ -0,0 +1,857 @@
+/**
+ * treecom — Host half.
+ *
+ * A read-only index over the user's conversation family. It does not write to
+ * any session log: the only file it owns is the sidecar with branch labels.
+ *
+ * The index is a tree of TURNS, not of sessions. A DSH fork copies a prefix of
+ * the parent log verbatim, so a turn below `inheritedEventCount` is the same
+ * turn in every descendant. Canonicalising those turns to their owning session
+ * makes the shared trunk appear once and makes a fork a child of the turn it
+ * was cut from. That is the whole data model.
+ *
+ * The client asks for the family of one session, then either clicks a node
+ * (fork at that turn's closing seq) or opens an existing branch. Forking and
+ * archive/unarchive go through the normal Client session services; this route
+ * never creates or mutates a session.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+const ROUTE = '/treecom'
+const STATE_VERSION = 1
+const SNAPSHOT_TTL_MS = 15_000
+const SNAPSHOT_CACHE_MAX = 64
+const TREE_CACHE_MAX = 16
+const LABEL_LIMIT = 120
+const DETAIL_LIMIT = 24_000
+
+export const name = 'treecom'
+export const inject = ['webServer', 'sessionQuery', 'sessions']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: ROUTE,
+    handler: (request, response) => handle(ctx, request, response),
+  }), 'treecom: index route')
+}
+
+/* --------------------------------------------------------------- route -- */
+
+async function handle(ctx, request, response) {
+  try {
+    if (request.method === 'GET') {
+      const url = new URL(request.url ?? ROUTE, 'http://treecom.local')
+      const sessionId = url.searchParams.get('sessionId')
+      if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        respond(response, 400, { error: 'sessionId 必须是非空字符串' })
+        return
+      }
+      const fresh = url.searchParams.get('fresh') === '1'
+      respond(response, 200, await buildTree(ctx, sessionId, fresh))
+      return
+    }
+    if (request.method === 'POST') {
+      const body = await readJson(request)
+      if (body !== null && typeof body === 'object' && body.action === 'label') {
+        const nodeId = typeof body.nodeId === 'string' ? body.nodeId : ''
+        if (nodeId.length === 0) {
+          respond(response, 400, { error: 'nodeId 必须是非空字符串' })
+          return
+        }
+        const label = normalizeLabel(body.label)
+        const state = await updateState((current) => {
+          if (label.length === 0) delete current.labels[nodeId]
+          else current.labels[nodeId] = label
+          return current
+        })
+        respond(response, 200, { ok: true, labels: state.labels })
+        return
+      }
+      if (body !== null && typeof body === 'object' && body.action === 'lineage') {
+        const sessionId = typeof body.sessionId === 'string' ? body.sessionId : ''
+        if (sessionId.length === 0) {
+          respond(response, 400, { error: 'sessionId 必须是非空字符串' })
+          return
+        }
+        respond(response, 200, await buildLineage(ctx, sessionId))
+        return
+      }
+      if (body !== null && typeof body === 'object' && body.action === 'forest') {
+        const sessionId = typeof body.sessionId === 'string' ? body.sessionId : ''
+        if (sessionId.length === 0) {
+          respond(response, 400, { error: 'sessionId 必须是非空字符串' })
+          return
+        }
+        respond(response, 200, await buildForest(ctx, sessionId))
+        return
+      }
+      if (body !== null && typeof body === 'object' && body.action === 'detail') {
+        const nodeId = typeof body.nodeId === 'string' ? body.nodeId : ''
+        if (nodeId.length === 0) {
+          respond(response, 400, { error: 'nodeId 必须是非空字符串' })
+          return
+        }
+        const detail = await buildDetail(ctx, nodeId)
+        if (detail === null) {
+          respond(response, 404, { error: '找不到这个节点' })
+          return
+        }
+        respond(response, 200, { ok: true, detail })
+        return
+      }
+      respond(response, 400, { error: '未知操作' })
+      return
+    }
+    response.writeHead(405)
+    response.end()
+  } catch (error) {
+    respond(response, 500, { error: error instanceof Error ? error.message : String(error) })
+  }
+}
+
+function respond(response, status, value) {
+  response.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  response.end(JSON.stringify(value))
+}
+
+function readJson(request) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    request.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))))
+    request.on('end', () => {
+      try {
+        const text = Buffer.concat(chunks).toString('utf8')
+        resolve(text.length === 0 ? null : JSON.parse(text))
+      } catch (error) {
+        reject(new TypeError('请求体必须是 JSON'))
+      }
+    })
+    request.on('error', reject)
+  })
+}
+
+/* ---------------------------------------------------------------- tree -- */
+
+/** Every catalogue session in the folder, with its root-session identity. */
+async function buildLineage(ctx, sessionId) {
+  const records = await ctx.sessionQuery.listSessions()
+  const byId = new Map(records.map((record) => [record.header.id, record]))
+  let target = byId.get(sessionId)
+  if (target === undefined) {
+    const snapshot = await ctx.sessionQuery.readSession(sessionId)
+    target = { header: snapshot.session }
+  }
+  const cwd = target.header.cwd ?? null
+  const sessions = []
+  for (const record of records) {
+    const header = record.header
+    if (header.origin === 'subagent') continue
+    if (cwd !== null && header.cwd !== cwd) continue
+    const root = rootOf(record, byId)
+    sessions.push({
+      id: header.id,
+      parentId: header.parentSession ?? null,
+      rootId: root.header.id,
+      title: typeof record.title === 'string' && record.title.trim() !== ''
+        ? record.title.trim()
+        : (typeof header.title === 'string' && header.title.trim() !== '' ? header.title.trim() : shortId(header.id)),
+    })
+  }
+  return { ok: true, sessionId, cwd, sessions }
+}
+
+/**
+ * All root sessions that belong to the same folder (cwd) as `sessionId`.
+ * Trees are derived from session ancestry; a promoted tree is a client-side
+ * view root pointing at a node in one of these families.
+ */
+async function buildForest(ctx, sessionId) {
+  const records = await ctx.sessionQuery.listSessions()
+  const byId = new Map(records.map((record) => [record.header.id, record]))
+  let target = byId.get(sessionId)
+  if (target === undefined) {
+    const snapshot = await ctx.sessionQuery.readSession(sessionId)
+    target = { header: snapshot.session }
+  }
+  const cwd = target.header.cwd ?? null
+  const roots = []
+  for (const record of records) {
+    const header = record.header
+    if (header.origin === 'subagent') continue
+    if (cwd !== null && header.cwd !== cwd) continue
+    const parent = header.parentSession
+    if (parent !== undefined && byId.has(parent)) continue
+    roots.push({
+      id: header.id,
+      title: typeof record.title === 'string' && record.title.trim() !== ''
+        ? record.title.trim()
+        : (typeof header.title === 'string' && header.title.trim() !== '' ? header.title.trim() : shortId(header.id)),
+      createdAt: header.createdAt ?? null,
+      active: header.id === sessionId,
+    })
+  }
+  roots.sort((left, right) => (right.createdAt ?? 0) - (left.createdAt ?? 0))
+  const idsByRoot = new Map()
+  for (const record of records) {
+    const header = record.header
+    if (header.origin === 'subagent') continue
+    if (cwd !== null && header.cwd !== cwd) continue
+    const owner = rootOf(record, byId).header.id
+    const list = idsByRoot.get(owner)
+    if (list === undefined) idsByRoot.set(owner, [header.id])
+    else list.push(header.id)
+  }
+  await Promise.all(roots.map(async (root) => {
+    root.sessionIds = idsByRoot.get(root.id) ?? [root.id]
+    root.sessionCount = root.sessionIds.length
+    const record = byId.get(root.id)
+    if (record === undefined) return
+    try {
+      const snapshot = await readSnapshot(ctx, record)
+      const turns = cachedTurns(root.id, snapshot.events)
+      root.title = titleOf(snapshot.events) || firstPrompt(turns) || shortId(root.id)
+    } catch {
+      /* keep the catalogue title / short id */
+    }
+  }))
+  return { ok: true, sessionId, cwd, roots }
+}
+
+function familyRevision(ctx, family, state, archived, sessionId, rootId) {
+  const sessions = family.map((record) => {
+    const live = ctx.sessions.get(record.header.id)
+    const updatedAt = record.updatedAt ?? record.header.updatedAt ?? ''
+    const title = record.title ?? record.header.title ?? ''
+    return `${record.header.id}:${updatedAt}:${title}:${live?.seq ?? ''}:${isRunning(ctx, record.header.id) ? 'r' : '-'}`
+  })
+  return `${sessionId}|${rootId}|${sessions.join('|')}|${JSON.stringify(state.labels)}|${[...archived].sort().join(',')}`
+}
+
+async function buildTree(ctx, sessionId, fresh = false) {
+  const records = await ctx.sessionQuery.listSessions()
+  const byId = new Map(records.map((record) => [record.header.id, record]))
+  let target = byId.get(sessionId)
+  if (target === undefined) {
+    // A freshly forked child can be readable before the catalogue lists it.
+    // Read it once and splice it into this request's family.
+    const snapshot = await ctx.sessionQuery.readSession(sessionId)
+    target = { header: snapshot.session, live: false, persisted: true }
+    records.push(target)
+    byId.set(sessionId, target)
+  }
+
+  const root = rootOf(target, byId)
+  const family = familyOf(root, records)
+  if (!family.some((record) => record.header.id === sessionId)) family.push(target)
+
+  const state = await readState()
+  const archived = new Set(ctx.get?.('workspaceRegistry')?.archivedSessionIds ?? [])
+  const rootId = root.header.id
+  const revision = familyRevision(ctx, family, state, archived, sessionId, rootId)
+  const reliable = family.every((record) => ctx.sessions.get(record.header.id) !== undefined
+    || (record.updatedAt ?? record.header.updatedAt) !== undefined)
+  const cacheTtl = reliable ? Infinity : SNAPSHOT_TTL_MS
+  const cachedTree = fresh ? undefined : treeCache.get(sessionId)
+  if (cachedTree !== undefined && cachedTree.key === revision && Date.now() - cachedTree.at < cachedTree.ttl) {
+    treeCache.delete(sessionId)
+    treeCache.set(sessionId, cachedTree)
+    return cachedTree.payload
+  }
+
+  const snapshots = new Map()
+  const errors = []
+  await Promise.all(family.map(async (record) => {
+    try {
+      const snapshot = await readSnapshot(ctx, record, fresh)
+      snapshots.set(record.header.id, snapshot)
+    } catch (error) {
+      errors.push({ sessionId: record.header.id, message: messageOf(error) })
+    }
+  }))
+  if (!snapshots.has(sessionId)) {
+    const detail = errors.find((entry) => entry.sessionId === sessionId)
+    throw new Error(detail === undefined ? `读不到会话 ${sessionId}` : `读不到会话 ${sessionId}: ${detail.message}`)
+  }
+
+  const turnsBySession = new Map()
+  for (const [id, snapshot] of snapshots) turnsBySession.set(id, cachedTurns(id, snapshot.events))
+
+  const rootSnapshot = snapshots.get(rootId)
+  const treeTitle = rootSnapshot === undefined
+    ? shortId(rootId)
+    : titleOf(rootSnapshot.events) || firstPrompt(turnsBySession.get(rootId) ?? []) || shortId(rootId)
+
+  const nodes = []
+  const nodeById = new Map()
+  const rootNode = {
+    id: `${rootId}:root`,
+    kind: 'root',
+    sessionId: rootId,
+    turn: 0,
+    startSeq: 0,
+    endSeq: 0,
+    parentId: null,
+    label: treeTitle,
+    prompt: '',
+    answer: '',
+    time: root.header.createdAt,
+    order: 0,
+  }
+  nodes.push(rootNode)
+  nodeById.set(rootNode.id, rootNode)
+
+  for (const record of family) {
+    const id = record.header.id
+    const snapshot = snapshots.get(id)
+    if (snapshot === undefined) continue
+    const turns = turnsBySession.get(id) ?? []
+    let previousId = rootNode.id
+    for (const turn of turns) {
+      const owner = ownerOf(id, turn.startSeq, byId, snapshots)
+      const nodeId = `${owner}:${turn.startSeq}`
+      let node = nodeById.get(nodeId)
+      if (node === undefined) {
+        node = {
+          id: nodeId,
+          kind: 'turn',
+          sessionId: owner,
+          turn: turn.turn,
+          startSeq: turn.startSeq,
+          endSeq: turn.endSeq,
+          parentId: previousId,
+          label: turn.prompt === '' ? `第 ${turn.turn} 轮` : turn.prompt,
+          prompt: turn.prompt,
+          answer: turn.answer,
+          contextTokens: turn.contextTokens ?? 0,
+          contextWindow: turn.contextWindow ?? 0,
+          time: turn.time,
+          order: turn.startSeq,
+          ...turn.open === true ? { open: true } : {},
+        }
+        nodes.push(node)
+        nodeById.set(nodeId, node)
+      } else {
+        // A running turn keeps growing; refresh the mutable fields instead of
+        // freezing the first snapshot the panel happened to see.
+        node.endSeq = turn.endSeq
+        node.label = turn.prompt === '' ? `第 ${turn.turn} 轮` : turn.prompt
+        node.prompt = turn.prompt
+        node.answer = turn.answer
+        node.contextTokens = turn.contextTokens ?? 0
+        node.contextWindow = turn.contextWindow ?? 0
+        node.time = turn.time
+        node.open = turn.open === true
+      }
+      previousId = nodeId
+    }
+    const ownTurns = turns.filter((turn) => turn.startSeq >= snapshot.inheritedEventCount)
+    if (ownTurns.length === 0 && id !== rootId) {
+      const stub = blankStub({ record, snapshot, nodes, byId, snapshots, rootNode })
+      if (stub !== null && !nodeById.has(stub.id)) {
+        nodes.push(stub)
+        nodeById.set(stub.id, stub)
+      }
+    }
+  }
+
+  for (const node of nodes) {
+    if (node.kind !== 'root' && typeof state.labels[node.id] === 'string') node.label = state.labels[node.id]
+  }
+
+  const sessions = family
+    .filter((record) => snapshots.has(record.header.id))
+    .map((record) => {
+      const snapshot = snapshots.get(record.header.id)
+      const turns = turnsBySession.get(record.header.id) ?? []
+      return {
+        id: record.header.id,
+        parentSessionId: record.header.parentSession,
+        title: titleOf(snapshot.events) || firstPrompt(turns) || shortId(record.header.id),
+        createdAt: record.header.createdAt,
+        inheritedEventCount: snapshot.inheritedEventCount,
+        turnCount: turns.length,
+        running: isRunning(ctx, record.header.id),
+        blank: turns.length === 0,
+        archived: archived.has(record.header.id),
+        active: record.header.id === sessionId,
+      }
+    })
+
+  const payload = {
+    ok: true,
+    sessionId,
+    rootId,
+    cwd: root.header.cwd ?? null,
+    treeTitle,
+    nodes,
+    sessions,
+    labels: state.labels,
+    archivedSessionIds: [...archived],
+    errors,
+  }
+  if (errors.length === 0) {
+    treeCache.set(sessionId, { key: revision, at: Date.now(), ttl: cacheTtl, payload })
+    while (treeCache.size > TREE_CACHE_MAX) {
+      const oldest = treeCache.keys().next().value
+      if (oldest === undefined) break
+      treeCache.delete(oldest)
+    }
+  }
+  return payload
+}
+
+/** The topmost surviving ancestor. A missing parent ends the walk at the last known session. */
+function rootOf(target, byId) {
+  let current = target
+  const seen = new Set()
+  while (current.header.parentSession !== undefined) {
+    if (seen.has(current.header.id)) break
+    seen.add(current.header.id)
+    const parent = byId.get(current.header.parentSession)
+    if (parent === undefined) break
+    current = parent
+  }
+  return current
+}
+
+/** Root and every non-subagent descendant, parents before children. */
+function familyOf(root, records) {
+  const children = new Map()
+  for (const record of records) {
+    const parent = record.header.parentSession
+    if (parent === undefined) continue
+    const list = children.get(parent) ?? []
+    list.push(record)
+    children.set(parent, list)
+  }
+  const family = []
+  const seen = new Set()
+  const queue = [root]
+  while (queue.length > 0) {
+    const record = queue.shift()
+    if (seen.has(record.header.id)) continue
+    seen.add(record.header.id)
+    if (record.header.origin === 'subagent') continue
+    family.push(record)
+    for (const child of children.get(record.header.id) ?? []) queue.push(child)
+  }
+  return family
+}
+
+/**
+ * The session that actually owns one event seq. Below `inheritedEventCount`
+ * the child's events are a verbatim copy of the parent's, so the owner is the
+ * first ancestor whose own log still contains that seq.
+ */
+function ownerOf(sessionId, seq, byId, snapshots) {
+  let current = sessionId
+  const seen = new Set()
+  for (;;) {
+    if (seen.has(current)) return current
+    seen.add(current)
+    const snapshot = snapshots.get(current)
+    const parentId = byId.get(current)?.header.parentSession
+    if (snapshot === undefined || seq >= snapshot.inheritedEventCount) return current
+    if (parentId === undefined || !byId.has(parentId) || !snapshots.has(parentId)) return current
+    current = parentId
+  }
+}
+
+/**
+ * A forked child that has not asked anything yet is still a branch. Hang it
+ * under the turn it was cut from, so the panel can show "新分支 · 等待提问".
+ */
+function blankStub({ record, snapshot, nodes, byId, snapshots, rootNode }) {
+  const cut = snapshot.inheritedEventCount
+  let parentNode = rootNode
+  for (let index = cut - 1; index >= 0; index--) {
+    const event = snapshot.events[index]
+    if (event?.type !== 'turn/end') continue
+    const owner = ownerOf(record.header.id, event.seq, byId, snapshots)
+    const candidate = nodes.find((node) => node.sessionId === owner && node.endSeq === event.seq)
+    if (candidate !== undefined) {
+      parentNode = candidate
+      break
+    }
+  }
+  const ownPrompt = firstOwnPrompt(snapshot.events, cut)
+  const last = snapshot.events.at(-1)
+  return {
+    id: `${record.header.id}:blank`,
+    kind: 'blank',
+    sessionId: record.header.id,
+    turn: 0,
+    startSeq: cut,
+    endSeq: typeof last?.seq === 'number' ? last.seq : cut,
+    parentId: parentNode.id,
+    label: ownPrompt === '' ? '新分支' : ownPrompt,
+    prompt: ownPrompt,
+    answer: '',
+    contextTokens: parentNode.contextTokens ?? 0,
+    contextWindow: parentNode.contextWindow ?? 0,
+    time: last?.time ?? record.header.createdAt,
+    order: typeof last?.seq === 'number' ? last.seq : cut,
+    blank: true,
+    ...ownPrompt === '' ? {} : { open: true },
+  }
+}
+
+const turnCache = new Map()
+
+/** Parse once per log revision; the tree panel polls while a branch is open. */
+function cachedTurns(sessionId, events) {
+  const last = events.at(-1)?.seq ?? -1
+  const hit = turnCache.get(sessionId)
+  if (hit !== undefined && hit.last === last) return hit.turns
+  const turns = turnsOf(events)
+  turnCache.set(sessionId, { last, turns })
+  return turns
+}
+
+/** Extract completed and open turns from one log. Prompts are human-authored only. */
+function turnsOf(events) {
+  const turns = []
+  let current = null
+  let contextWindow = 0
+  let lastUsage = null
+  let lastUsageTokens = 0
+  for (const event of events) {
+    if (event.type === 'request/context') {
+      const value = Number(event.data?.contextWindow)
+      if (Number.isFinite(value) && value > 0) {
+        contextWindow = value
+        if (current !== null) current.contextWindow = value
+      }
+      continue
+    }
+    if (event.type === 'turn/start') {
+      current = {
+        turn: event.data.turn,
+        startSeq: event.seq,
+        endSeq: null,
+        time: event.time,
+        prompt: '',
+        promptFull: '',
+        answer: '',
+        answerFull: '',
+        usage: null,
+        contextTokens: lastUsageTokens,
+        contextWindow,
+        open: true,
+      }
+      continue
+    }
+    if (current === null) continue
+    if (event.type === 'user/message') {
+      if (current.prompt === '' && event.data?.source?.kind === 'user') {
+        const full = rawTextOf(event.data.content)
+        current.prompt = preview(full, 140)
+        current.promptFull = limitText(full, DETAIL_LIMIT)
+      }
+      continue
+    }
+    if (event.type === 'assistant/message') {
+      const usage = normalizeUsage(event.data?.usage ?? event.data?.message?.usage)
+      if (usage !== null) {
+        current.usage = usage
+        lastUsage = usage
+        lastUsageTokens = usage.totalTokens
+        current.contextTokens = usage.totalTokens
+      }
+      const full = rawTextOf(event.data?.message?.content)
+      if (full !== '') {
+        current.answer = preview(full, 220)
+        current.answerFull = limitText(full, DETAIL_LIMIT)
+      }
+      continue
+    }
+    if (event.type === 'turn/end' && event.data?.turn === current.turn) {
+      current.endSeq = event.seq
+      current.time = event.time
+      current.open = false
+      turns.push(current)
+      current = null
+    }
+  }
+  if (current !== null) {
+    current.endSeq = events.at(-1)?.seq ?? current.startSeq
+    turns.push(current)
+  }
+  if (contextWindow > 0) {
+    for (const turn of turns) {
+      if (!Number.isFinite(turn.contextWindow) || turn.contextWindow <= 0) turn.contextWindow = contextWindow
+    }
+  }
+  return turns
+}
+
+function normalizeUsage(value) {
+  if (value === null || typeof value !== 'object') return null
+  const inputTokens = Number(value.inputTokens)
+  const outputTokens = Number(value.outputTokens)
+  const cacheReadTokens = Number(value.cacheReadTokens)
+  const cacheWriteTokens = Number(value.cacheWriteTokens ?? 0)
+  const total = Number(value.totalTokens)
+  if (![inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens].every(Number.isFinite)) return null
+  return {
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    totalTokens: Number.isFinite(total) && total > 0 ? total : inputTokens + outputTokens + cacheReadTokens,
+  }
+}
+
+function firstOwnPrompt(events, cut) {
+  for (const event of events) {
+    if (event.seq < cut || event.type !== 'user/message') continue
+    if (event.data?.source?.kind !== 'user') continue
+    const text = preview(textOf(event.data.content), 140)
+    if (text !== '') return text
+  }
+  return ''
+}
+function firstOwnPromptFull(events, cut) {
+  for (const event of events) {
+    if (event.seq < cut || event.type !== 'user/message') continue
+    if (event.data?.source?.kind !== 'user') continue
+    const text = limitText(rawTextOf(event.data.content), DETAIL_LIMIT)
+    if (text !== '') return text
+  }
+  return ''
+}
+
+async function readSessionView(ctx, sessionId) {
+  let record = null
+  try {
+    const records = await ctx.sessionQuery.listSessions()
+    record = records.find((candidate) => candidate.header.id === sessionId) ?? null
+  } catch {
+    record = null
+  }
+  if (record !== null) {
+    try {
+      return { record, snapshot: await readSnapshot(ctx, record) }
+    } catch {
+      /* fall through to the single-session read */
+    }
+  }
+  try {
+    const snapshot = await ctx.sessionQuery.readSession(sessionId)
+    return {
+      record: { header: snapshot.session, live: false, persisted: true },
+      snapshot,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Full Q/A text for the hover card, read on demand. The tree payload only
+ * carries previews, so a long answer never inflates every poll.
+ */
+async function buildDetail(ctx, nodeId) {
+  if (nodeId.endsWith(':root')) return null
+  if (nodeId.endsWith(':blank')) {
+    const sessionId = nodeId.slice(0, -':blank'.length)
+    const view = await readSessionView(ctx, sessionId)
+    if (view === null) return null
+    const { record, snapshot } = view
+    const turns = cachedTurns(sessionId, snapshot.events)
+    const lastTurn = turns.at(-1) ?? null
+    const last = snapshot.events.at(-1)
+    const prompt = firstOwnPromptFull(snapshot.events, snapshot.inheritedEventCount)
+    return {
+      nodeId,
+      kind: 'blank',
+      sessionId,
+      turn: 0,
+      startSeq: snapshot.inheritedEventCount,
+      endSeq: typeof last?.seq === 'number' ? last.seq : snapshot.inheritedEventCount,
+      prompt,
+      answer: '',
+      time: last?.time ?? record.header.createdAt,
+      contextTokens: lastTurn?.contextTokens ?? 0,
+      contextWindow: lastTurn?.contextWindow ?? 0,
+      truncated: prompt.length >= DETAIL_LIMIT,
+    }
+  }
+  const separator = nodeId.lastIndexOf(':')
+  if (separator <= 0) return null
+  const sessionId = nodeId.slice(0, separator)
+  const startSeq = Number(nodeId.slice(separator + 1))
+  if (!Number.isSafeInteger(startSeq) || startSeq < 0) return null
+  const view = await readSessionView(ctx, sessionId)
+  if (view === null) return null
+  const turns = cachedTurns(sessionId, view.snapshot.events)
+  const turn = turns.find((candidate) => candidate.startSeq === startSeq)
+  if (turn === undefined) return null
+  const prompt = turn.promptFull === '' ? turn.prompt : turn.promptFull
+  return {
+    nodeId,
+    kind: 'turn',
+    sessionId,
+    turn: turn.turn,
+    startSeq: turn.startSeq,
+    endSeq: turn.endSeq,
+    prompt,
+    answer: turn.answerFull,
+    time: turn.time,
+    contextTokens: turn.contextTokens ?? 0,
+    contextWindow: turn.contextWindow ?? 0,
+    truncated: (turn.promptFull !== undefined && turn.promptFull.length >= DETAIL_LIMIT)
+      || (turn.answerFull !== undefined && turn.answerFull.length >= DETAIL_LIMIT),
+  }
+}
+
+function limitText(text, limit) {
+  const value = String(text).trim()
+  return value.length <= limit ? value : `${value.slice(0, limit - 1)}…`
+}
+
+function rawTextOf(content) {
+  if (!Array.isArray(content)) return ''
+  const parts = []
+  for (const block of content) {
+    if (block?.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+  }
+  return parts.join('\n').trim()
+}
+
+function firstPrompt(turns) {
+  for (const turn of turns) if (turn.prompt !== '') return turn.prompt
+  return ''
+}
+
+function titleOf(events) {
+  for (let index = events.length - 1; index >= 0; index--) {
+    const event = events[index]
+    if (event.type === 'session/title' && typeof event.data?.title === 'string' && event.data.title.trim() !== '') {
+      return event.data.title.trim()
+    }
+  }
+  return ''
+}
+
+function textOf(content) {
+  if (!Array.isArray(content)) return ''
+  const parts = []
+  for (const block of content) {
+    if (block?.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+  }
+  return collapse(parts.join(' '))
+}
+
+function collapse(text) {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+function preview(text, limit) {
+  const value = collapse(text)
+  return value.length <= limit ? value : `${value.slice(0, limit - 1)}…`
+}
+
+function shortId(id) {
+  return String(id).replace(/^session-/, '').slice(0, 8)
+}
+
+function isRunning(ctx, sessionId) {
+  try {
+    const agent = ctx.get?.('agents')?.get(sessionId)
+    return agent?.phase?.kind === 'running'
+  } catch {
+    return false
+  }
+}
+
+/* ---------------------------------------------------------- snapshots -- */
+
+const snapshotCache = new Map()
+const treeCache = new Map()
+
+async function readSnapshot(ctx, record, force = false) {
+  const id = record.header.id
+  const live = ctx.sessions.get(id)
+  const updatedAt = record.updatedAt ?? record.header.updatedAt
+  const key = live === undefined
+    ? `persisted:${updatedAt ?? 'unknown'}`
+    : `live:${live.seq}`
+  const ttl = live === undefined && updatedAt === undefined ? SNAPSHOT_TTL_MS : Infinity
+  const cached = snapshotCache.get(id)
+  if (force !== true && cached !== undefined && cached.key === key && Date.now() - cached.at < ttl) {
+    snapshotCache.delete(id)
+    snapshotCache.set(id, cached)
+    return cached.snapshot
+  }
+  const snapshot = live === undefined
+    ? await ctx.sessionQuery.readSession(id)
+    : {
+        session: live.header,
+        header: live.header,
+        inheritedEventCount: live.inheritedEventCount,
+        events: live.snapshotEvents(),
+      }
+  snapshotCache.set(id, { key, at: Date.now(), snapshot })
+  while (snapshotCache.size > SNAPSHOT_CACHE_MAX) {
+    const oldest = snapshotCache.keys().next().value
+    if (oldest === undefined) break
+    snapshotCache.delete(oldest)
+  }
+  return snapshot
+}
+
+/* -------------------------------------------------------------- state -- */
+
+let stateQueue = Promise.resolve()
+
+function stateFile() {
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  return join(home, 'storages', 'treecom', 'state.json')
+}
+
+async function readState() {
+  try {
+    const parsed = JSON.parse(await readFile(stateFile(), 'utf8'))
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return emptyState()
+    const labels = parsed.labels !== null && typeof parsed.labels === 'object' && !Array.isArray(parsed.labels)
+      ? parsed.labels
+      : {}
+    return { version: STATE_VERSION, labels }
+  } catch {
+    return emptyState()
+  }
+}
+
+function emptyState() {
+  return { version: STATE_VERSION, labels: {} }
+}
+
+function updateState(mutate) {
+  const run = stateQueue.then(async () => {
+    const current = await readState()
+    const next = mutate(current)
+    const file = stateFile()
+    await mkdir(dirname(file), { recursive: true })
+    await writeFile(file, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+    return next
+  })
+  stateQueue = run.catch(() => {})
+  return run
+}
+
+function normalizeLabel(value) {
+  if (typeof value !== 'string') return ''
+  return collapse(value).slice(0, LABEL_LIMIT)
+}
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}