@huynle/hub 0.6.0 → 0.7.1

package/src/spoke/taskboard.ts

@@ -0,0 +1,243 @@
+// The voice agent's task board: its background workers (child sessions) with their state, last activity and
+// how long, built from the OpenCode events this process sees. The context hook adds the rendered board to every
+// voice turn, so the agent can answer "what's running?" or "how's the deploy going?" without a tool call, and
+// the stop tool (hub_task_stop) checks with it that a worker belongs to the session asking. Pure: time is
+// passed in.
+import { summarizeToolInput } from "../protocol"
+
+/** Tasks shown on the board, and the longest line. */
+export const TASK_BOARD_MAX = 8
+export const TASK_LINE_MAX = 200
+/** Tasks remembered in this process (finished ones are forgotten first). */
+const TASK_LIMIT = 300
+const TITLE_MAX = 60
+const TEXT_MAX = 160
+/** Tool call IDs remembered per task to name their activity. */
+const TOOL_NAMES_MAX = 20
+
+export type TaskState = "working" | "blocked" | "done" | "failed" | "stopped"
+
+export interface Task {
+  readonly id: string
+  readonly parentID: string
+  readonly title: string
+  readonly state: TaskState
+  /** ms epoch the current run started. */
+  readonly started: number
+  /** ms epoch the run ended (done, failed, stopped). */
+  readonly ended?: number
+  /** Since when it waits for the user (blocked). */
+  readonly blockedAt?: number
+  /** The latest tool it ran ("shell · bun test"). */
+  readonly activity?: string
+  /** Its latest assistant text (the result once done). */
+  readonly result?: string
+  readonly error?: string
+  /** Why it is blocked ("needs permission: …", "has a question: …"). */
+  readonly blocker?: string
+}
+
+interface Entry {
+  id: string
+  parentID: string
+  title: string
+  running: boolean
+  outcome?: "done" | "failed" | "stopped"
+  started: number
+  ended?: number
+  activity?: string
+  result?: string
+  error?: string
+  /** Pending permission / form ID → its description, in order. */
+  blockers: Map<string, { text: string; at: number }>
+  tools: Map<string, string>
+}
+
+const record = (v: unknown): Record<string, any> => (typeof v === "object" && v !== null ? (v as Record<string, any>) : {})
+const str = (v: unknown) => (typeof v === "string" && v ? v : undefined)
+const oneLine = (text: string, max: number) => {
+  const flat = text.replace(/\s+/g, " ").trim()
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat
+}
+
+const LIVE = (e: Entry) => e.running || e.blockers.size > 0
+
+export class TaskBoard {
+  private readonly entries = new Map<string, Entry>()
+  private readonly limit: number
+
+  constructor({ limit = TASK_LIMIT }: { limit?: number } = {}) {
+    this.limit = limit
+  }
+
+  observe(event: { type: string; data?: unknown }, now: number): void {
+    const data = record(event.data)
+    const sessionID = str(data.sessionID) ?? str(record(data.form).sessionID)
+    if (!sessionID) return
+    if (event.type === "session.created") {
+      const parentID = str(data.parentID)
+      if (!parentID) return
+      this.entries.delete(sessionID)
+      this.entries.set(sessionID, {
+        id: sessionID,
+        parentID,
+        title: oneLine(str(data.title) ?? str(data.agent) ?? "worker", TITLE_MAX),
+        running: false,
+        started: now,
+        blockers: new Map(),
+        tools: new Map(),
+      })
+      this.prune()
+      return
+    }
+    const entry = this.entries.get(sessionID)
+    if (!entry) return
+    switch (event.type) {
+      case "session.renamed":
+        if (str(data.title)) entry.title = oneLine(data.title, TITLE_MAX)
+        return
+      case "session.deleted":
+        this.entries.delete(sessionID)
+        return
+      case "session.execution.started":
+        if (!entry.running) entry.started = now
+        entry.running = true
+        entry.outcome = entry.ended = entry.error = undefined
+        return
+      case "session.execution.succeeded":
+      case "session.execution.failed":
+      case "session.execution.interrupted":
+        entry.running = false
+        entry.ended = now
+        entry.blockers.clear()
+        entry.outcome = event.type.endsWith("succeeded") ? "done" : event.type.endsWith("failed") ? "failed" : "stopped"
+        if (entry.outcome === "failed") entry.error = oneLine(str(record(data.error).message) ?? "failed", TEXT_MAX)
+        return
+      case "session.tool.input.started": {
+        const id = str(data.id)
+        const name = str(data.name)
+        if (!id || !name) return
+        entry.tools.set(id, name)
+        if (entry.tools.size > TOOL_NAMES_MAX) entry.tools.delete(entry.tools.keys().next().value!)
+        entry.activity = name
+        return
+      }
+      case "session.tool.called": {
+        const name = entry.tools.get(str(data.id) ?? "") ?? str(data.name) ?? "tool"
+        const summary = str(data.summary) ?? summarizeToolInput(data.input)
+        entry.activity = oneLine(summary ? `${name} · ${summary}` : name, TEXT_MAX)
+        return
+      }
+      case "session.text.ended":
+        if (str(data.text)?.trim()) entry.result = oneLine(data.text, TEXT_MAX)
+        return
+      case "permission.asked": {
+        const id = str(data.id)
+        if (!id) return
+        const what = [str(data.action), Array.isArray(data.resources) ? data.resources.filter((r: unknown) => typeof r === "string").join(", ") : ""].filter(Boolean).join(": ")
+        entry.blockers.set(`per ${id}`, { text: oneLine(what ? `needs permission: ${what}` : "needs permission", TEXT_MAX), at: now })
+        return
+      }
+      case "permission.replied":
+        entry.blockers.delete(`per ${str(data.requestID)}`)
+        return
+      case "form.created": {
+        const form = record(data.form)
+        const id = str(form.id)
+        if (!id) return
+        entry.blockers.set(`frm ${id}`, { text: oneLine(str(form.title) ? `has a question: ${form.title}` : "has a question", TEXT_MAX), at: now })
+        return
+      }
+      case "form.replied":
+      case "form.cancelled":
+        entry.blockers.delete(`frm ${str(data.id) ?? str(record(data.form).id)}`)
+        return
+    }
+  }
+
+  /** The workers a session started: live ones first (newest first), then finished ones (latest first). */
+  children(parentID: string): Task[] {
+    const mine = [...this.entries.values()].filter((e) => e.parentID === parentID)
+    const live = mine.filter(LIVE).sort((a, b) => b.started - a.started)
+    const finished = mine.filter((e) => !LIVE(e)).sort((a, b) => (b.ended ?? b.started) - (a.ended ?? a.started))
+    return [...live, ...finished].map(view)
+  }
+
+  get(id: string): Task | undefined {
+    const entry = this.entries.get(id)
+    return entry && view(entry)
+  }
+
+  /** The session that started a known worker. */
+  parentOf(id: string): string | undefined {
+    return this.entries.get(id)?.parentID
+  }
+
+  private prune(): void {
+    while (this.entries.size > this.limit) {
+      const finished = [...this.entries.values()].filter((e) => !LIVE(e)).sort((a, b) => (a.ended ?? a.started) - (b.ended ?? b.started))[0]
+      this.entries.delete(finished?.id ?? this.entries.keys().next().value!)
+    }
+  }
+}
+
+function view(entry: Entry): Task {
+  const blocker = [...entry.blockers.values()][0]
+  const state: TaskState = blocker ? "blocked" : entry.running ? "working" : (entry.outcome ?? "working")
+  return {
+    id: entry.id,
+    parentID: entry.parentID,
+    title: entry.title,
+    state,
+    started: entry.started,
+    ...(entry.ended !== undefined && !entry.running ? { ended: entry.ended } : {}),
+    ...(blocker ? { blocker: blocker.text, blockedAt: blocker.at } : {}),
+    ...(entry.activity ? { activity: entry.activity } : {}),
+    ...(entry.result ? { result: entry.result } : {}),
+    ...(entry.error ? { error: entry.error } : {}),
+  }
+}
+
+/** "45s", "2m 10s", "1h 5m". */
+export function duration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000))
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  if (m < 60) return s % 60 ? `${m}m ${s % 60}s` : `${m}m`
+  return m % 60 ? `${Math.floor(m / 60)}h ${m % 60}m` : `${Math.floor(m / 60)}h`
+}
+
+function line(task: Task, now: number): string {
+  const head = `- "${task.title}" (sessionID ${task.id}): `
+  let rest: string
+  switch (task.state) {
+    case "blocked":
+      rest = `blocked ${duration(now - (task.blockedAt ?? task.started))}, ${task.blocker}`
+      break
+    case "working":
+      rest = `working ${duration(now - task.started)}${task.activity ? `, last: ${task.activity}` : ""}`
+      break
+    case "done":
+      rest = `done ${duration(now - (task.ended ?? now))} ago (took ${duration((task.ended ?? now) - task.started)})${task.result ? `: ${task.result}` : ""}`
+      break
+    case "failed":
+      rest = `failed ${duration(now - (task.ended ?? now))} ago${task.error ? `: ${task.error}` : ""}`
+      break
+    case "stopped":
+      rest = `stopped ${duration(now - (task.ended ?? now))} ago`
+      break
+  }
+  const text = head + rest
+  return text.length > TASK_LINE_MAX ? `${text.slice(0, TASK_LINE_MAX - 1)}…` : text
+}
+
+/** The board for the voice agent's system prompt; undefined when it started no workers. */
+export function renderTaskBoard(tasks: readonly Task[], now: number, { max = TASK_BOARD_MAX }: { max?: number } = {}): string | undefined {
+  if (!tasks.length) return undefined
+  const shown = tasks.slice(0, max)
+  return [
+    "Task board: your background workers right now (live; answer questions about them from this, no tool call needed; use a sessionID to continue or stop that worker):",
+    ...shown.map((task) => line(task, now)),
+    ...(tasks.length > shown.length ? [`(${tasks.length - shown.length} older tasks not shown)`] : []),
+  ].join("\n")
+}

package/src/spoke/timeline.ts

@@ -1,4 +1,5 @@
-import { PROMPT_IMAGE_MIMES, type PromptImage } from "../protocol"
+import { DELIVER_ID_MAX, MESSAGE_KINDS, PROMPT_IMAGE_MIMES, type MessageKind, type PromptImage, type TimelineMessageItem } from "../protocol"
+import { PROMPT_SOURCE } from "./conversation"
 
 /** An attachment of a user message: its position in the message's files (for timelineFile), type and name. */
 export interface TimelineFile {
@@ -12,46 +13,223 @@ export interface TimelineItem {
   readonly messageID: string
   readonly partID?: string
   readonly sessionID: string
-  readonly kind: "user" | "assistant" | "reasoning" | "tool"
+  /** "message": a hub message delivered to the session (TimelineMessageItem). */
+  readonly kind: "user" | "assistant" | "reasoning" | "tool" | "message"
   readonly text?: string
   readonly name?: string
   readonly state?: "running" | "done" | "failed"
   readonly at?: number
   readonly completed?: number
   readonly files?: readonly TimelineFile[]
+  /**
+   * Ordering position: rows sort by it (never by `at`, whose clocks differ between parts). It follows the order
+   * of the session's messages and of the parts within a message, and depends only on the message's own creation
+   * time and its predecessors' (so it stays the same while history pages or the context window move).
+   */
+  readonly pos?: number
+  /** Tool rows: the tool call ID (live activity items use it as their ID). */
+  readonly callID?: string
+  /** Subagent (subagent/task) tool rows: the child session it runs in. */
+  readonly childSessionID?: string
+  /** Subagent tool rows: the task's short description. */
+  readonly title?: string
+  /** Assistant text rows: which text part of the message this is (0, 1, …), as in live text deltas. */
+  readonly ordinal?: number
+  /** Message rows: always "in" here (the hub adds the session's sent messages). */
+  readonly direction?: TimelineMessageItem["direction"]
+  /** Message rows: who sent it, how it was addressed, what it answers. */
+  readonly message?: TimelineMessageItem["message"]
 }
 
+/** Parts of one message a position leaves room for (later parts share the last slot). */
+const POS_PARTS = 1000
+const SUBAGENT_TOOLS = new Set(["subagent", "task"])
+const TITLE_MAX = 160
+
 const record = (value: unknown): Record<string, any> => value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {}
 
 /** Projects OpenCode messages into stable, ordered, payload-light phone timeline rows. */
 export function timelineItems(sessionID: string, messages: readonly unknown[]): TimelineItem[] {
   const out: TimelineItem[] = []
+  let previous = -Infinity
   for (const raw of messages) {
     const message = record(raw)
     if (typeof message.id !== "string") continue
     const at = typeof message.time?.created === "number" ? message.time.created : undefined
+    // Messages keep the session's order even when one was created earlier than the one before it (a queued prompt).
+    const start = Math.max(at === undefined ? -Infinity : at * POS_PARTS, previous + POS_PARTS)
+    const first = (previous = Number.isFinite(start) ? start : 0)
+    const pos = (index: number) => first + Math.min(index, POS_PARTS - 1)
     if (message.type === "user") {
       const text = typeof message.text === "string" ? message.text : Array.isArray(message.content) ? message.content.filter((p: any) => p?.type === "text").map((p: any) => p.text).join("") : ""
       const files = userFiles(message.files)
-      if (text || files.length) out.push({ key: `${message.id}:text`, messageID: message.id, sessionID, kind: "user", text, ...(at === undefined ? {} : { at }), ...(files.length ? { files } : {}) })
+      if (text || files.length) out.push({ key: `${message.id}:text`, messageID: message.id, sessionID, kind: "user", text, ...(at === undefined ? {} : { at }), ...(files.length ? { files } : {}), pos: pos(0) })
+      continue
+    }
+    if (message.type === "synthetic") {
+      const row = hubMessageRow(sessionID, message, at, pos(0))
+      if (row) out.push(row)
       continue
     }
     if (message.type !== "assistant" || !Array.isArray(message.content)) continue
+    let texts = 0
     message.content.forEach((part: any, index: number) => {
       if (!part || typeof part !== "object") return
       const partID = String(index)
-      const base = { key: `${message.id}:${partID}`, messageID: message.id, partID, sessionID, ...(at === undefined ? {} : { at }) }
-      if (part.type === "text" && typeof part.text === "string" && part.text) out.push({ ...base, kind: "assistant", text: part.text })
+      const base = { key: `${message.id}:${partID}`, messageID: message.id, partID, sessionID, ...(at === undefined ? {} : { at }), pos: pos(index) }
+      if (part.type === "text" && typeof part.text === "string") {
+        const ordinal = texts++
+        if (part.text) out.push({ ...base, kind: "assistant", text: part.text, ordinal })
+      }
       if (part.type === "reasoning") out.push({ ...base, kind: "reasoning", text: String(part.text ?? ""), state: part.time?.completed === undefined ? "running" : "done", ...(typeof part.time?.created === "number" ? { at: part.time.created } : {}), ...(typeof part.time?.completed === "number" ? { completed: part.time.completed } : {}) })
       if (part.type === "tool") {
         const status = part.state?.status
-        out.push({ ...base, kind: "tool", name: String(part.name ?? "tool"), state: status === "error" ? "failed" : status === "completed" ? "done" : "running", ...(typeof part.time?.created === "number" ? { at: part.time.created } : {}), ...(typeof part.time?.completed === "number" ? { completed: part.time.completed } : {}) })
+        const name = String(part.name ?? "tool")
+        const spawn = SUBAGENT_TOOLS.has(name) ? subagentOf(part.state) : {}
+        out.push({
+          ...base,
+          kind: "tool",
+          name,
+          state: status === "error" ? "failed" : status === "completed" ? "done" : "running",
+          ...(typeof part.id === "string" && part.id ? { callID: part.id } : {}),
+          ...spawn,
+          ...(typeof part.time?.created === "number" ? { at: part.time.created } : {}),
+          ...(typeof part.time?.completed === "number" ? { completed: part.time.completed } : {}),
+        })
       }
     })
   }
   return out
 }
 
+/** A message the hub delivered (synthetic, with deliverMetadata): a "message" row; other synthetic messages: none. */
+function hubMessageRow(sessionID: string, message: Record<string, any>, at: number | undefined, pos: number): TimelineMessageItem | undefined {
+  const meta = record(message.metadata)
+  const id = meta.messageID
+  if (meta.source !== PROMPT_SOURCE || !isID(id) || !MESSAGE_KINDS.includes(meta.kind) || !isID(meta.from) || !isID(meta.to)) return undefined
+  const text = typeof message.text === "string" ? message.text : ""
+  return {
+    key: `${message.id}:message`,
+    messageID: id,
+    sessionID,
+    kind: "message",
+    text: meta.kind === "primer" ? text : messageBody(text, id),
+    ...(at === undefined ? {} : { at }),
+    pos,
+    direction: "in",
+    message: { kind: meta.kind as MessageKind, from: meta.from, to: meta.to, ...(isID(meta.replyTo) ? { replyTo: meta.replyTo } : {}) },
+  }
+}
+
+const isID = (value: unknown): value is string => typeof value === "string" && value.length > 0 && value.length <= DELIVER_ID_MAX
+
+/** A line of the envelope body escaped by renderEnvelope (a leading backslash before a header-like line). */
+const ESCAPED = /^(\s*)\\(\\*(?:\[hub\]|-{3,}|↩))/i
+
+/**
+ * The body of a hub envelope (packages/sdk/src/envelope.ts renderEnvelope): the lines between its boundaries,
+ * unescaped. Text without boundaries (a reminder) shows its first line without the "[hub]" tag.
+ */
+function messageBody(text: string, id: string): string {
+  const lines = text.split("\n")
+  const boundary = `----- ${id} -----`
+  const start = lines.indexOf(boundary)
+  const end = lines.lastIndexOf(boundary)
+  if (start < 0 || end <= start) return lines[0]!.replace(/^\[hub\]\s*/i, "")
+  return lines
+    .slice(start + 1, end)
+    .map((line) => line.replace(ESCAPED, "$1$2"))
+    .join("\n")
+}
+
+const CHILD_SESSION = /sessionID:?\s*"?(ses_[A-Za-z0-9]+)/
+
+/** The child session (from the tool's metadata, else its output) and description of a subagent tool call. */
+function subagentOf(rawState: unknown): { childSessionID?: string; title?: string } {
+  const state = record(rawState)
+  const description = typeof state.input?.description === "string" ? state.input.description.trim().split("\n")[0]!.slice(0, TITLE_MAX) : ""
+  let child = typeof state.metadata?.sessionID === "string" && state.metadata.sessionID.startsWith("ses_") ? (state.metadata.sessionID as string) : undefined
+  if (!child) {
+    const outputs = [state.output, state.error, ...(Array.isArray(state.content) ? state.content.map((c: any) => c?.text) : [])]
+    for (const text of outputs) {
+      const match = typeof text === "string" ? CHILD_SESSION.exec(text) : null
+      if (match) {
+        child = match[1]
+        break
+      }
+    }
+  }
+  return { ...(child ? { childSessionID: child } : {}), ...(description ? { title: description } : {}) }
+}
+
+/** A newest-first timeline page: rows in chronological order, and the cursor of the rows before them. */
+export interface NewestPage {
+  readonly items: TimelineItem[]
+  /** Pass as `before` for the next older page; absent at the beginning of the conversation. */
+  readonly older?: string
+}
+
+/**
+ * The `limit` rows just before the row keyed `before` (the newest rows without it). The cursor is the key of
+ * the oldest row returned, so it stays valid while new messages arrive (an offset would shift). A page starts
+ * at a message boundary when the message fits in twice the limit; larger messages are split.
+ */
+export function newestPage(items: readonly TimelineItem[], limit: number, before?: string): NewestPage {
+  const end = before === undefined ? items.length : items.findIndex((item) => item.key === before)
+  if (end < 0) throw new Error("Invalid timeline cursor")
+  let start = Math.max(0, end - limit)
+  const cap = Math.max(0, end - limit * 2)
+  while (start > cap && items[start - 1]!.messageID === items[start]!.messageID) start--
+  const page = items.slice(start, end)
+  return { items: page, ...(start > 0 && page.length ? { older: page[0]!.key } : {}) }
+}
+
+/**
+ * Short-lived per-session timeline rows, so paging through a history reads OpenCode's whole history once rather
+ * than once per page. Entries expire after `ttlMs` and are dropped when the session changes (invalidate).
+ */
+export class TimelineCache {
+  private readonly entries = new Map<string, { items: TimelineItem[]; at: number }>()
+  /** Bumped on invalidation: a load started before it is not stored. */
+  private readonly generations = new Map<string, number>()
+  private readonly ttlMs: number
+  private readonly max: number
+  private readonly now: () => number
+
+  constructor(options: { ttlMs?: number; max?: number; now?: () => number } = {}) {
+    this.ttlMs = options.ttlMs ?? 30_000
+    this.max = options.max ?? 20
+    this.now = options.now ?? Date.now
+  }
+
+  get size(): number {
+    return this.entries.size
+  }
+
+  /** The cached rows of `sessionID`, else (or with `fresh`) loaded and cached. */
+  async get(sessionID: string, load: () => Promise<TimelineItem[]>, fresh = false): Promise<TimelineItem[]> {
+    const cached = this.entries.get(sessionID)
+    if (!fresh && cached && this.now() - cached.at < this.ttlMs) {
+      this.entries.delete(sessionID)
+      this.entries.set(sessionID, cached)
+      return cached.items
+    }
+    const generation = this.generations.get(sessionID) ?? 0
+    const items = await load()
+    if ((this.generations.get(sessionID) ?? 0) !== generation) return items
+    this.entries.delete(sessionID)
+    this.entries.set(sessionID, { items, at: this.now() })
+    while (this.entries.size > this.max) this.entries.delete(this.entries.keys().next().value!)
+    return items
+  }
+
+  invalidate(sessionID: string): void {
+    this.entries.delete(sessionID)
+    if (this.generations.size > 1000) this.generations.clear()
+    this.generations.set(sessionID, (this.generations.get(sessionID) ?? 0) + 1)
+  }
+}
+
 /** Attachment metadata (never the bytes) of a user message's files. */
 function userFiles(raw: unknown): TimelineFile[] {
   if (!Array.isArray(raw)) return []

package/src/spoke/tracker.ts

@@ -1,7 +1,7 @@
 // Sessions this OpenCode process knows about, built from the events it sees, plus which of them
 // are exposed to the central server (by mode). Pure: time is passed in.
 import type { Mode } from "../config"
-import { FORWARDED_EVENTS, type SessionInfo, type TerminalInfo } from "../protocol"
+import { compactActivity, FORWARDED_EVENTS, type JobInfo, type SessionInfo, type TerminalInfo } from "../protocol"
 
 /** A session is "owned" by this process while it viewed or ran it within this window. */
 export const OWNED_WINDOW_MS = 30 * 60 * 1000
@@ -58,6 +58,9 @@ export function eventSessionID(event: EventLike): string | undefined {
   return undefined
 }
 
+/** Shells and terminals remembered (for the session of their exit). */
+const JOBS_KNOWN = 1000
+
 const RUN_END = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"])
 
 export class SessionTracker {
@@ -66,6 +69,10 @@ export class SessionTracker {
   private readonly running = new Set<string>()
   /** Pending permission or form ID → its session. */
   private readonly waiting = new Map<string, string>()
+  /** Sessions OpenCode reports busy or retrying (session.status). */
+  private readonly busy = new Set<string>()
+  /** Shell or terminal ID → its session, while known (running or exited, until deleted). */
+  private readonly jobs = new Map<string, { sessionID: string; running: boolean }>()
 
   /** Applies an event seen in this process. Returns true when the snapshot may have changed. */
   observe(event: EventLike, now: number): boolean {
@@ -94,6 +101,8 @@ export class SessionTracker {
       }
       case "session.deleted":
         this.running.delete(id)
+        this.busy.delete(id)
+        for (const [jobID, job] of this.jobs) if (job.sessionID === id) this.jobs.delete(jobID)
         for (const [key, sessionID] of this.waiting) if (sessionID === id) this.waiting.delete(key)
         return this.entries.delete(id)
       default: {
@@ -178,18 +187,73 @@ export class SessionTracker {
     return true
   }
 
-  /** Root sessions with a run in progress or a pending permission or form somewhere in their tree. */
+  /**
+   * Root sessions with a run in progress, a busy or retrying status, a running shell or terminal, or a pending
+   * permission or form somewhere in their tree.
+   */
   active(): string[] {
     const roots = new Set<string>()
-    for (const id of [...this.running, ...this.waiting.values()]) roots.add(this.rootOf(id))
+    const jobs = [...this.jobs.values()].filter((j) => j.running).map((j) => j.sessionID)
+    for (const id of [...this.running, ...this.busy, ...jobs, ...this.waiting.values()]) roots.add(this.rootOf(id))
     return [...roots]
   }
 
+  /** Sessions OpenCode reported busy or retrying, or with a running shell or terminal (not their roots). */
+  working(): string[] {
+    const jobs = [...this.jobs.values()].filter((j) => j.running).map((j) => j.sessionID)
+    return [...new Set([...this.busy, ...jobs])]
+  }
+
+  /** Directories of known sessions (where to list shells), most recently updated first. */
+  directories(max: number): string[] {
+    const sorted = [...this.entries.values()].filter((e) => e.directory.startsWith("/")).sort((a, b) => b.updated - a.updated)
+    return [...new Set(sorted.map((e) => e.directory))].slice(0, max)
+  }
+
+  /** The session a shell or terminal belongs to, while known. */
+  jobSession(jobID: string): string | undefined {
+    return this.jobs.get(jobID)?.sessionID
+  }
+
+  /** Replaces a session's status and running jobs with a snapshot (fetched at startup or after a reconnect). */
+  seed(sessionID: string, snapshot: { readonly status: "idle" | "busy" | "retry"; readonly jobs: readonly JobInfo[] }): void {
+    if (snapshot.status === "idle") this.busy.delete(sessionID)
+    else this.busy.add(sessionID)
+    for (const [jobID, job] of this.jobs) if (job.sessionID === sessionID && job.running) this.jobs.delete(jobID)
+    for (const job of snapshot.jobs) this.setJob(job.id, sessionID, job.status === "running")
+  }
+
+  /** Session status and shells/terminals (compacted so the session of an exit is resolved). */
+  private trackJobs(event: EventLike): void {
+    if (event.type !== "session.status" && !event.type.startsWith("shell.") && !event.type.startsWith("pty.") && !event.type.startsWith("session.shell.")) return
+    const compact = compactActivity({ type: event.type, data: record(event.data) }, (id) => this.jobSession(id))
+    if (!compact) return
+    const data = compact.data as Record<string, any>
+    const sessionID = data.sessionID as string
+    if (compact.type === "session.status") {
+      if (data.status.type === "idle") this.busy.delete(sessionID)
+      else this.busy.add(sessionID)
+    } else if (compact.type.endsWith(".deleted")) this.jobs.delete(data.id)
+    else if (typeof data.id === "string" && typeof data.status === "string") this.setJob(data.id, sessionID, data.status === "running")
+  }
+
+  /** Remembers a job, keeping at most JOBS_KNOWN (oldest dropped). */
+  private setJob(id: string, sessionID: string, running: boolean): void {
+    this.jobs.delete(id)
+    this.jobs.set(id, { sessionID, running })
+    if (this.jobs.size > JOBS_KNOWN) this.jobs.delete(this.jobs.keys().next().value!)
+  }
+
   private trackActive(event: EventLike): void {
+    this.trackJobs(event)
     const data = record(event.data)
     const sessionID = eventSessionID(event)
     if (event.type === "session.execution.started" && sessionID) this.running.add(sessionID)
-    else if (RUN_END.has(event.type) && sessionID) this.running.delete(sessionID)
+    else if (RUN_END.has(event.type) && sessionID) {
+      this.running.delete(sessionID)
+      // OpenCode v2 sends no idle status: a run's end ends a busy status (seeded or reported) too.
+      this.busy.delete(sessionID)
+    }
     else if (event.type === "permission.asked" && sessionID && typeof data.id === "string") this.waiting.set(`per ${data.id}`, sessionID)
     else if (event.type === "permission.replied" && typeof data.requestID === "string") this.waiting.delete(`per ${data.requestID}`)
     else if (event.type === "form.created" && sessionID && typeof record(data.form).id === "string") this.waiting.set(`frm ${record(data.form).id}`, sessionID)
@@ -198,6 +262,17 @@ export class SessionTracker {
     }
   }
 
+  /** The session itself has a run in progress or OpenCode reports it busy or retrying. */
+  isBusy(sessionID: string): boolean {
+    return this.running.has(sessionID) || this.busy.has(sessionID)
+  }
+
+  /** A form (question) is open in the session itself. */
+  formOpenIn(sessionID: string): boolean {
+    for (const [key, id] of this.waiting) if (id === sessionID && key.startsWith("frm ")) return true
+    return false
+  }
+
   /** A form (question) this process saw asked and not yet replied or cancelled. */
   formPending(formID: string): boolean {
     return this.waiting.has(`frm ${formID}`)