@hicaru/pi-rlm 0.3.8 → 0.3.13

package/src/tool/subcall-render.ts

@@ -1,30 +1,19 @@
 /**
- * Shared sub-call tree rendering for RLM tools (rlm + repl).
+ * Card scaffolding for RLM tool results (rlm + repl).
  *
- * Both tools accumulate RlmSubcall[] arrays with parentId links. This module
- * provides the collapsed ASCII tree and expanded Container-based tree rendering
- * used by their renderResult() implementations.
+ * The chat transcript renders ONE line per call — status glyph, title, stats —
+ * plus the expand hint. Agent trees are NOT rendered here: the live tree
+ * widget and agent modal (ui/tree/, ui/modal/) own all agent visualization.
  */
 
-import { Container, Text, type Component } from "@earendil-works/pi-tui";
+import { Text } from "@earendil-works/pi-tui";
 import { keyText } from "@earendil-works/pi-coding-agent";
-import type { RlmSubcall, SubcallStatus } from "./rlm-details.ts";
-import { formatCost, formatDuration, formatTokens, spinnerFrame } from "../ui/theme.ts";
-import { previewText } from "../text/preview.ts";
+import type { SubcallStatus } from "./rlm-details.ts";
+import { formatTokens, spinnerFrame } from "../ui/theme.ts";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
-/** Preview budgets for the expanded tree (args are terse, results get more room). */
-const ARGS_PREVIEW_CHARS = 80;
-const RESULT_PREVIEW_CHARS = 120;
-
 // ── Glyphs ──
 
-export function subcallStatusGlyph(sc: Pick<RlmSubcall, "status">, theme: Theme): string {
-  if (sc.status === "running") return theme.fg("warning", "⏳");
-  if (sc.status === "error") return theme.fg("error", "✗");
-  return theme.fg("success", "✓");
-}
-
 export function headlineStatusGlyph(status: SubcallStatus | "aborted" | "done", theme: Theme): string {
   switch (status) {
     case "done": return theme.fg("success", "✓");
@@ -36,40 +25,24 @@ export function headlineStatusGlyph(status: SubcallStatus | "aborted" | "done",
 
 // ── Stats formatting ──
 
-export function subcallStatsLine(sc: Pick<RlmSubcall, "costUsd" | "tokens" | "endedAt" | "startedAt">): string {
-  const parts: string[] = [];
-  if (sc.costUsd > 0) parts.push(formatCost(sc.costUsd));
-  if (sc.tokens > 0) parts.push(`${formatTokens(sc.tokens)} tok`);
-  // Explicit undefined checks: a 0 timestamp is falsy but legitimate (fixtures, epoch clocks).
-  if (sc.endedAt !== undefined && sc.startedAt !== undefined) parts.push(formatDuration(sc.endedAt - sc.startedAt));
-  return parts.join(" · ");
-}
-
-// ── Shared card scaffolding (rlm + repl render the same shape) ──
-
-/** The `$0.0123 · 4.2k tok · 812ms` run of a card header. Omits any zero component. */
+/** The `4.2k tok · 812ms` run of a card header. Omits any zero component. */
 export function cardStatsLine(
-  totals: { readonly costUsd: number; readonly tokens: number },
+  totals: { readonly tokens: number },
   theme: Theme,
   extra?: string,
   backgroundPending?: number,
 ): string {
-  const parts: string[] = [formatCost(totals.costUsd)];
+  const parts: string[] = [];
   if (totals.tokens > 0) parts.push(`${formatTokens(totals.tokens)} tok`);
   if (extra) parts.push(extra);
   const line = theme.fg("dim", parts.join(" · "));
-  // The one thing no tree can show: spawned work that may outlive this block.
+  // The one thing no single line can show: spawned work that may outlive this block.
   return backgroundPending !== undefined && backgroundPending > 0
     ? `${line} ${theme.fg("warning", `↯${backgroundPending} bg`)}`
     : line;
 }
 
-/** Detached nodes carry BackgroundTasks' "bg" id prefix (RlmEmitter("bg")). */
-function backgroundTag(sc: RlmSubcall, theme: Theme): string {
-  return sc.id.startsWith("bg") ? ` ${theme.fg("warning", "↯bg")}` : "";
-}
-
-/** `<glyph> <TITLE> <stats>` — the first line of both tools' collapsed and expanded views. */
+/** `<glyph> <TITLE> <stats>` — the card's single header line. */
 export function cardHeader(
   title: string,
   status: SubcallStatus | "aborted" | "done",
@@ -93,101 +66,13 @@ function expandHint(theme: Theme): string {
   return theme.fg("muted", key ? `${key} to expand` : "to expand");
 }
 
-/** The collapsed card: header, the sub-call tree, and the expand hint. */
+/** The collapsed card: header line, then the expand hint once settled. */
 export function renderCollapsedCard(
   title: string,
   status: SubcallStatus | "aborted" | "done",
   stats: string,
-  subcalls: readonly RlmSubcall[],
   theme: Theme,
 ): Text {
-  const body = subcalls.length > 0 ? `\n${renderCollapsedSubcallTree(subcalls, theme)}` : "";
   const hint = status === "running" ? "" : `\n${expandHint(theme)}`;
-  return new Text(`${cardHeader(title, status, stats, theme)}${body}${hint}`, 0, 0);
-}
-
-// ── Tree building ──
-
-function buildParentMap(subcalls: readonly RlmSubcall[]): Map<string | undefined, RlmSubcall[]> {
-  const map = new Map<string | undefined, RlmSubcall[]>();
-  for (const sc of subcalls) {
-    const list = map.get(sc.parentId) ?? [];
-    list.push(sc);
-    map.set(sc.parentId, list);
-  }
-  return map;
-}
-
-// ── Collapsed tree (ASCII) ──
-
-export function renderCollapsedSubcallTree(
-  subcalls: readonly RlmSubcall[],
-  theme: Theme,
-): string {
-  if (subcalls.length === 0) return "";
-
-  const byParent = buildParentMap(subcalls);
-
-  function walk(parentId: string | undefined, prefix: string): string[] {
-    const lines: string[] = [];
-    const direct = byParent.get(parentId) ?? [];
-    for (let i = 0; i < direct.length; i++) {
-      const sc = direct[i];
-      if (!sc) continue;
-      const isLast = i === direct.length - 1;
-      const branch = isLast ? "└─" : "├─";
-      const gGlyph = subcallStatusGlyph(sc, theme);
-      const gStats = subcallStatsLine(sc);
-      const gBg = backgroundTag(sc, theme);
-      lines.push(`${prefix}${branch} ${sc.label}  ${gGlyph}  ${gStats}${gBg}`);
-      const childPrefix = prefix + (isLast ? "   " : "│  ");
-      lines.push(...walk(sc.id, childPrefix));
-    }
-    return lines;
-  }
-
-  return walk(undefined, "  ").join("\n");
-}
-
-// ── Expanded tree (Container) ──
-
-export function renderExpandedSubcallTree(
-  subcalls: readonly RlmSubcall[],
-  theme: Theme,
-): Component {
-  const container = new Container();
-  if (subcalls.length === 0) return container;
-
-  const byParent = buildParentMap(subcalls);
-
-  function renderNode(sc: RlmSubcall, indent: number): void {
-    const pad = "  ".repeat(indent);
-    const sGlyph = subcallStatusGlyph(sc, theme);
-    const sKind = theme.fg("muted", sc.label);
-    const sModel = sc.model ? theme.fg("dim", ` ${sc.model}`) : "";
-    const sStats = sc.endedAt ? `  ${theme.fg("dim", subcallStatsLine(sc))}` : "";
-    const sBg = backgroundTag(sc, theme);
-    let line = `${pad}${sGlyph} ${sKind}${sModel}${sStats}${sBg}`;
-
-    if (sc.args) {
-      line += `\n${pad}  ${theme.fg("dim", previewText(sc.args, ARGS_PREVIEW_CHARS))}`;
-    }
-    if (sc.status === "error" && sc.detail) {
-      line += `\n${pad}  ${theme.fg("error", `✗ ${sc.detail}`)}`;
-    } else if (sc.resultPreview) {
-      line += `\n${pad}  ${theme.fg("toolOutput", previewText(sc.resultPreview, RESULT_PREVIEW_CHARS))}`;
-    }
-
-    container.addChild(new Text(line, 0, 0));
-
-    for (const child of (byParent.get(sc.id) ?? [])) {
-      renderNode(child, indent + 1);
-    }
-  }
-
-  for (const sc of (byParent.get(undefined) ?? [])) {
-    renderNode(sc, 1);
-  }
-
-  return container;
+  return new Text(`${cardHeader(title, status, stats, theme)}${hint}`, 0, 0);
 }

package/src/tool/subcall-store.ts

@@ -25,6 +25,8 @@ export class SubcallStore extends EmitterListener {
 
   private totalCostUsd = 0;
   private totalTokens = 0;
+  private rootCostUsd = 0;
+  private rootTokens = 0;
 
   constructor(emitter: RlmEmitter, private readonly onChange?: () => void) {
     super();
@@ -61,6 +63,7 @@ export class SubcallStore extends EmitterListener {
       sc.status = event.status;
       if (event.status !== "running") sc.endedAt = Date.now();
     }
+    if (event.phase !== undefined) sc.phase = event.phase;
     if (event.detail !== undefined) sc.detail = event.detail;
     if (event.args !== undefined) sc.args = event.args;
     if (event.resultPreview !== undefined) sc.resultPreview = event.resultPreview;
@@ -93,7 +96,7 @@ export class SubcallStore extends EmitterListener {
    * from the running totals so the caller can add them without double-counting.
    *
    * A root whose subtree still has a running node stays put. That matters because
-   * `renderCollapsedSubcallTree` walks down from `parentId === undefined`: a subcall handed
+   * The tree model (`ui/tree/tree-model.ts`) walks down from `parentId === undefined`: a subcall handed
    * over without its parent has no path from a root and is silently dropped from the tree.
    * Handing over whole subtrees is what keeps adopted nodes renderable.
    */
@@ -144,5 +147,12 @@ export class SubcallStore extends EmitterListener {
   addRootUsage(costUsd: number, tokens: number): void {
     this.totalCostUsd += costUsd;
     this.totalTokens += tokens;
+    this.rootCostUsd += costUsd;
+    this.rootTokens += tokens;
+  }
+
+  /** Root engine's OWN spend (driver-model turns only) — never blends sub-call models. */
+  getRootUsage(): SubcallTotals {
+    return { costUsd: this.rootCostUsd, tokens: this.rootTokens };
   }
 }

package/src/ui/intro.ts

@@ -2,7 +2,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { RlmController } from "../mode/rlm-mode.ts";
-import { formatRlmStateLine } from "./status.ts";
+import { modelLabel } from "./status.ts";
 
 export const RLM_GUIDE = `# RLM mode
 
@@ -11,10 +11,19 @@ export const RLM_GUIDE = `# RLM mode
 ## Commands
 
 - \`/rlm\` — toggle RLM mode (shortcut: Ctrl+Shift+R). Turning it OFF also stops a running query.
-- \`/rlm-config\` — choose models, reasoning, and run limits
-- \`/rlm-stop\` — cancel the current run but stay in RLM mode (use /rlm or Ctrl+Shift+R to leave)`;
+- \`/rlm-llm\` — pin the LLM model for llm_query / llm_batch / map_files
+- \`/rlm-rlm\` — pin the model for rlm_query / rlm_batch child engines (default: session model)
+- \`/rlm-config\` — run limits and engine settings
+- \`/rlm-stop\` — cancel the current run but stay in RLM mode (use /rlm or Ctrl+Shift+R to leave)
+
+## Live tree
+
+While agents run, a tree shows below the editor — Ctrl+R focuses it, Enter opens an agent's timeline.`;
 
 export function postRlmGuide(pi: ExtensionAPI, controller: RlmController): void {
-  const content = RLM_GUIDE.replace("{state}", formatRlmStateLine(controller));
+  const state = controller.enabled
+    ? `● RLM ON — llm=${modelLabel(controller.llmModel, controller.savedLlmRef ?? "cheapest")} · rlm=${modelLabel(controller.rlmModel, controller.savedRlmRef ?? "session")}`
+    : "○ RLM OFF";
+  const content = RLM_GUIDE.replace("{state}", state);
   pi.sendMessage({ customType: "rlm-intro", content, display: true });
 }

package/src/ui/modal/agent-modal.ts

@@ -0,0 +1,104 @@
+/**
+ * agent-modal — focused overlay showing one agent's live detail.
+ *
+ * Opened via ctx.ui.custom (pi's overlay API): pi routes keyboard input to the
+ * component until done() fires. This class holds only view state (scroll
+ * offset, subscription); every line is built by the pure modal-view builder.
+ * Live updates: any registry change triggers a re-render, so the timeline
+ * scrolls itself while the agent works.
+ */
+
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { RunEntry, RunRegistry } from "../panel/run-registry.ts";
+import { buildModalLines, MODAL_LAYOUT, type AgentViewData } from "./modal-view.ts";
+
+const OVERLAY_OPTIONS = Object.freeze({ width: "70%" as const, maxHeight: "70%" as const, anchor: "center" as const });
+
+export function openAgentModal(ctx: ExtensionContext, registry: RunRegistry, runId: string, nodeId: string): Promise<void> {
+  return ctx.ui.custom<void>(
+    (tui, theme, _keybindings, done) => new AgentModalComponent(tui, theme, registry, runId, nodeId, done),
+    { overlay: true, overlayOptions: OVERLAY_OPTIONS },
+  );
+}
+
+class AgentModalComponent implements Component {
+  private scroll = 0;
+  private timelineLength = 0;
+  private readonly unsubscribe: () => void;
+
+  constructor(
+    private readonly tui: TUI,
+    private readonly theme: Theme,
+    private readonly registry: RunRegistry,
+    private readonly runId: string,
+    private readonly nodeId: string,
+    private readonly done: (result: void) => void,
+  ) {
+    this.unsubscribe = registry.onChange(() => this.tui.requestRender());
+  }
+
+  render(width: number): string[] {
+    const data = this.collect();
+    if (data === undefined) {
+      return ["┌─ agent ─────────────────────┐", "│ run ended — data unavailable │", "│ esc close                    │", "└──────────────────────────────┘"];
+    }
+    this.timelineLength = data.timeline.length;
+    return buildModalLines(data, this.scroll, width, this.theme);
+  }
+
+  handleInput(data: string): void {
+    if (data === "\x1b" || data === "q") {
+      this.dispose();
+      this.done();
+      return;
+    }
+    if (data === "\x1b[A") this.scroll = Math.max(0, this.scroll - 1);
+    else if (data === "\x1b[B") this.scroll = Math.min(Math.max(0, this.timelineLength - MODAL_LAYOUT.timelineVisible), this.scroll + 1);
+    this.tui.requestRender();
+  }
+
+  /** No cached render state — every render rebuilds from the live registry. */
+  invalidate(): void {}
+
+  dispose(): void {
+    this.unsubscribe();
+  }
+
+  /** Snapshot the node (or the run root) as view data; undefined once the run unregisters. */
+  private collect(): AgentViewData | undefined {
+    const run = this.registry.find(this.runId);
+    if (run === undefined) return undefined;
+    return this.nodeId === this.runId ? rootView(run) : nodeView(run, this.nodeId);
+  }
+}
+
+function rootView(run: RunEntry): AgentViewData {
+  const status = run.rootStatus();
+  return {
+    label: run.label,
+    icon: status === "aborted" ? "error" : status,
+    phase: run.rootPhase(),
+    depth: 0,
+    tokens: run.totals().tokens,
+    turns: run.turns(),
+    timeline: run.timeline.forNode(run.runId),
+  };
+}
+
+function nodeView(run: RunEntry, nodeId: string): AgentViewData | undefined {
+  const node = run.subcalls().find((sc) => sc.id === nodeId);
+  if (node === undefined) return undefined;
+  return {
+    label: node.label,
+    icon: node.status,
+    phase: node.phase,
+    depth: node.depth,
+    model: node.model,
+    tokens: node.tokens,
+    elapsedMs: (node.endedAt ?? Date.now()) - node.startedAt,
+    detail: node.detail,
+    args: node.args,
+    timeline: run.timeline.forNode(nodeId),
+  };
+}

package/src/ui/modal/modal-view.ts

@@ -0,0 +1,132 @@
+/**
+ * modal-view — pure line builder for the agent detail modal.
+ *
+ * Takes an immutable AgentViewData + scroll offset, returns bordered lines.
+ * No TUI state, no side effects — the stateful wrapper lives in agent-modal.ts.
+ * All assembly is segment arrays + join; ANSI-safe width math via pi-tui.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { formatDuration, formatTokens, spinnerFrame } from "../theme.ts";
+import { modelShort } from "../tree/tree-rows.ts";
+import type { SubcallPhase, SubcallStatus } from "../../tool/rlm-details.ts";
+import type { TimelineEntry, TimelineIcon } from "./timeline-store.ts";
+
+export const MODAL_LAYOUT = Object.freeze({
+  /** Timeline rows visible at once (scroll window). */
+  timelineVisible: 10,
+  /** Prompt section line budget. */
+  promptLines: 3,
+  minWidth: 44,
+} as const);
+
+export interface AgentViewData {
+  readonly label: string;
+  readonly icon: SubcallStatus;
+  readonly phase?: SubcallPhase;
+  readonly depth: number;
+  readonly model?: string;
+  readonly tokens: number;
+  /** Root rows only — omitted for subcall nodes. */
+  readonly turns?: { readonly current: number; readonly max: number };
+  readonly elapsedMs?: number;
+  readonly detail?: string;
+  readonly args?: string;
+  readonly timeline: readonly TimelineEntry[];
+}
+
+const TIMELINE_GLYPHS: Readonly<Record<TimelineIcon, string>> = Object.freeze({
+  spawn: "▸",
+  phase: "◌",
+  done: "✓",
+  error: "✗",
+  note: "·",
+  turn: "↻",
+});
+
+function statusGlyph(icon: SubcallStatus, theme: Theme): string {
+  switch (icon) {
+    case "done": return theme.fg("success", "✓");
+    case "error": return theme.fg("error", "✗");
+    default: return theme.fg("warning", spinnerFrame());
+  }
+}
+
+/** "┌─ title ───────┐" at exactly width columns. */
+function topBorder(title: string, width: number, theme: Theme): string {
+  const head = `┌─ ${title} `;
+  const fill = Math.max(0, width - visibleWidth(head) - 1);
+  return theme.fg("border", `${head}${"─".repeat(fill)}┐`);
+}
+
+/** "│ content … │" padded to width; content pre-truncated to the inner width. */
+function row(content: string, width: number): string {
+  const inner = width - 4;
+  const cut = truncateToWidth(content, inner);
+  const pad = Math.max(0, inner - visibleWidth(cut));
+  return `│ ${cut}${" ".repeat(pad)} │`;
+}
+
+function timelineLine(entry: TimelineEntry, theme: Theme): string {
+  const glyph = TIMELINE_GLYPHS[entry.icon];
+  const colored = entry.icon === "error" ? theme.fg("error", glyph) : entry.icon === "done" ? theme.fg("success", glyph) : theme.fg("dim", glyph);
+  return `${colored} ${entry.text}`;
+}
+
+export function buildModalLines(data: AgentViewData, scroll: number, width: number, theme: Theme): string[] {
+  const w = Math.max(width, MODAL_LAYOUT.minWidth);
+  const inner = w - 4;
+  const lines: string[] = [];
+
+  lines.push(topBorder(data.label, w, theme));
+
+  // Status row: "⠸ running · thinking   depth 1   model gpt-5-mini"
+  const statusParts = [`${statusGlyph(data.icon, theme)} ${data.icon}`];
+  if (data.phase !== undefined && data.icon === "running") statusParts.push(`· ${data.phase}`);
+  const stats: string[] = [`depth ${data.depth}`];
+  if (data.model !== undefined) stats.push(`model ${modelShort(data.model)}`);
+  lines.push(row(`${statusParts.join(" ")}   ${theme.fg("dim", stats.join("   "))}`, w));
+
+  // Stats row: "tokens 4.3k   turn 3/25   elapsed 12.0s"
+  const metricParts = [`tokens ${formatTokens(data.tokens)}`];
+  if (data.turns !== undefined && data.turns.max > 0) metricParts.push(`turn ${data.turns.current}/${data.turns.max}`);
+  if (data.elapsedMs !== undefined) metricParts.push(`elapsed ${formatDuration(data.elapsedMs)}`);
+  lines.push(row(theme.fg("dim", metricParts.join("   ")), w));
+  lines.push(row("", w));
+
+  // Prompt section: detail first, args as fallback, capped to the line budget.
+  const prompt = data.detail ?? data.args ?? "";
+  lines.push(row(theme.fg("accent", "prompt"), w));
+  if (prompt.length === 0) {
+    lines.push(row(theme.fg("dim", "(none)"), w));
+  } else {
+    const words = prompt.split(" ");
+    const wrapped: string[] = [];
+    let line = "";
+    for (const word of words) {
+      const next = line.length === 0 ? word : `${line} ${word}`;
+      if (visibleWidth(next) > inner - 2) { wrapped.push(line); line = word; } else { line = next; }
+      if (wrapped.length >= MODAL_LAYOUT.promptLines) break;
+    }
+    if (wrapped.length < MODAL_LAYOUT.promptLines && line.length > 0) wrapped.push(line);
+    for (const part of wrapped.slice(0, MODAL_LAYOUT.promptLines)) lines.push(row(` ${part}`, w));
+  }
+  lines.push(row("", w));
+
+  // Timeline window.
+  const total = data.timeline.length;
+  const maxScroll = Math.max(0, total - MODAL_LAYOUT.timelineVisible);
+  const at = Math.min(scroll, maxScroll);
+  const hint = total > MODAL_LAYOUT.timelineVisible ? `timeline ${at + 1}–${Math.min(total, at + MODAL_LAYOUT.timelineVisible)}/${total} · ↑↓ scroll` : "timeline";
+  lines.push(row(theme.fg("accent", hint), w));
+  const windowed = data.timeline.slice(at, at + MODAL_LAYOUT.timelineVisible);
+  for (const entry of windowed) lines.push(row(` ${timelineLine(entry, theme)}`, w));
+  // Stable height: pad unused timeline rows.
+  for (let i = windowed.length; i < MODAL_LAYOUT.timelineVisible; i++) lines.push(row("", w));
+
+  lines.push(row("", w));
+  lines.push(row(theme.fg("dim", "esc close"), w));
+  lines.push(theme.fg("border", `└${"─".repeat(Math.max(0, w - 2))}┘`));
+  return lines;
+}

package/src/ui/modal/timeline-store.ts

@@ -0,0 +1,85 @@
+/**
+ * TimelineStore — per-run ring buffer of notable events for the agent modal.
+ *
+ * Subscribes to the same emitter as SubcallStore (via the shared EmitterListener
+ * base) but records HISTORY instead of latest state: spawns, phase transitions,
+ * settlements, turn ticks. Bounded — oldest entries drop off past TIMELINE_CAP.
+ * The modal filters by nodeId, so one store serves every agent of the run.
+ */
+
+import type {
+  RlmEmitter,
+  RootPhaseEvent,
+  SubcallCreatedEvent,
+  SubcallUpdatedEvent,
+  TurnEvent,
+} from "../../tool/rlm-events.ts";
+import { EmitterListener } from "../../tool/emitter-listener.ts";
+
+export const TIMELINE_CAP = 200;
+
+export type TimelineIcon = "spawn" | "phase" | "done" | "error" | "note" | "turn";
+
+export interface TimelineEntry {
+  readonly at: number;
+  /** Node the entry belongs to: the subcall it describes; spawns attach to the PARENT. */
+  readonly nodeId: string;
+  readonly icon: TimelineIcon;
+  readonly text: string;
+}
+
+export class TimelineStore extends EmitterListener {
+  private entries: TimelineEntry[] = [];
+
+  constructor(emitter: RlmEmitter, private readonly runId: string) {
+    super();
+    this.trackAll([
+      emitter.onSubcallCreated((e) => this.handleCreated(e)),
+      emitter.onSubcallUpdated((e) => this.handleUpdated(e)),
+      emitter.onTurn((e) => this.handleTurn(e)),
+      emitter.onRootPhase((e) => this.handleRootPhase(e)),
+    ]);
+  }
+
+  /** Entries about a node, oldest first. Allocates — call from modal render only. */
+  forNode(nodeId: string): readonly TimelineEntry[] {
+    return this.entries.filter((e) => e.nodeId === nodeId);
+  }
+
+  private handleCreated(event: SubcallCreatedEvent): void {
+    this.push({
+      at: Date.now(),
+      nodeId: event.parentId ?? this.runId,
+      icon: "spawn",
+      text: `spawned ${event.kind}: ${event.label}`,
+    });
+  }
+
+  private handleUpdated(event: SubcallUpdatedEvent): void {
+    if (event.phase !== undefined) {
+      this.push({ at: Date.now(), nodeId: event.id, icon: "phase", text: event.phase });
+    }
+    if (event.detail !== undefined) {
+      this.push({ at: Date.now(), nodeId: event.id, icon: "note", text: event.detail });
+    }
+    if (event.status === "done") {
+      this.push({ at: Date.now(), nodeId: event.id, icon: "done", text: "settled" });
+    } else if (event.status === "error") {
+      this.push({ at: Date.now(), nodeId: event.id, icon: "error", text: event.detail ?? "failed" });
+    }
+  }
+
+  private handleTurn(event: TurnEvent): void {
+    this.push({ at: Date.now(), nodeId: this.runId, icon: "turn", text: `turn ${event.current}/${event.max}` });
+  }
+
+  private handleRootPhase(event: RootPhaseEvent): void {
+    this.push({ at: Date.now(), nodeId: this.runId, icon: "phase", text: event.phase });
+  }
+
+  private push(entry: TimelineEntry): void {
+    // Ring semantics: at cap, the oldest entry goes. Cap is small (200), shift is fine.
+    if (this.entries.length >= TIMELINE_CAP) this.entries.shift();
+    this.entries.push(entry);
+  }
+}