@yaag/tui 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/tui",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,6 +19,6 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.8.2"
+    "@yaag/runtime": "0.9.0"
   }
 }

package/src/index.ts

@@ -52,11 +52,13 @@ export {
   scrollBy,
   type TranscriptOverlayOptions,
 } from "./overlay/index.ts";
+export type { BackgroundToken, StyleToken, TreeStyler } from "./style/index.ts";
 export {
   activityText,
   clampToWidth,
   costText,
   durationText,
+  modelText,
   sanitizeTerminalLine,
   sanitizeTerminalText,
   tokensText,
@@ -114,6 +116,8 @@ export {
   compactAgentLine,
   createRunTreeView,
   type InlineRenderOptions,
+  type LiveTicker,
+  type LiveTickerOptions,
   livePhase,
   type RunPhase,
   type RunTreeView,
@@ -130,4 +134,6 @@ export {
   resultText,
   type SnapshotRenderOptions,
   STDERR_TAIL_LINES,
+  startLiveTicker,
+  type TickerSchedule,
 } from "./view/index.ts";

package/src/style/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Public surface of the `style/` module: the styling seam of the renderers.
+ * Files inside this directory import each other directly.
+ */
+export { renderStyledLine, type Span, type StyledLineOptions } from "./styled-line.ts";
+export {
+  type BackgroundToken,
+  identityStyler,
+  type StyleToken,
+  type TreeStyler,
+} from "./styler.ts";

package/src/style/styled-line.ts

@@ -0,0 +1,42 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { clampToWidth, columnLimit } from "../text/index.ts";
+import type { BackgroundToken, StyleToken, TreeStyler } from "./styler.ts";
+
+/** One run of already sanitized plain text, with the role it draws in. */
+export interface Span {
+  readonly text: string;
+  readonly token?: StyleToken;
+}
+
+/** How one line of spans is clamped and coloured. */
+export interface StyledLineOptions {
+  readonly width: number;
+  readonly styler: TreeStyler;
+  /** Pads the clamped line to `width` and fills it with this background. */
+  readonly background?: BackgroundToken;
+}
+
+/**
+ * Joins the spans, clamps the plain result to `width`, then colours each span.
+ *
+ * Clamping happens before styling, so no escape byte is ever measured as a
+ * display column. With {@link identityStyler} and no background the result
+ * equals `clampToWidth(spans.map((span) => span.text).join(""), width)` byte
+ * for byte.
+ */
+export function renderStyledLine(spans: readonly Span[], options: StyledLineOptions): string {
+  const clamped = clampToWidth(spans.map((span) => span.text).join(""), options.width);
+  const remainder = [...clamped];
+  let cursor = 0;
+  let line = "";
+  for (const span of spans) {
+    const length = [...span.text].length;
+    const text = remainder.slice(cursor, cursor + length).join("");
+    cursor = Math.min(cursor + length, remainder.length);
+    if (text === "") continue;
+    line += span.token === undefined ? text : options.styler.fg(span.token, text);
+  }
+  if (options.background === undefined) return line;
+  const pad = Math.max(0, columnLimit(options.width) - visibleWidth(clamped));
+  return options.styler.bg(options.background, line + " ".repeat(pad));
+}

package/src/style/styler.ts

@@ -0,0 +1,34 @@
+/**
+ * The styling seam of the tree renderer (spec D10).
+ *
+ * The renderer composes plain text and clamps it; a styler applies colour to
+ * the parts afterwards. The tokens named here belong to this package: a host
+ * maps them onto its own theme, so `@yaag/tui` depends on no theme library.
+ */
+
+/** A foreground role one span of a rendered line can carry. */
+export type StyleToken = "accent" | "running" | "failed" | "exited" | "idle" | "muted";
+
+/** A background role a whole rendered line can carry. */
+export type BackgroundToken = "selected";
+
+/**
+ * Colours a rendered line.
+ *
+ * Both members must be pure, must keep the visible width of their argument
+ * unchanged, and must add no newline. A styler that breaks one of the three
+ * breaks the width clamp of every surface that uses it.
+ */
+export interface TreeStyler {
+  fg(token: StyleToken, text: string): string;
+  bg(token: BackgroundToken, line: string): string;
+}
+
+/**
+ * The default styler: it returns the text unchanged, so a surface that passes
+ * no styler gets byte-identical plain lines.
+ */
+export const identityStyler: TreeStyler = {
+  fg: (_token: StyleToken, text: string): string => text,
+  bg: (_token: BackgroundToken, line: string): string => line,
+};

package/src/text/index.ts

@@ -5,5 +5,11 @@
 export { costText, tokensText } from "./accounting-text.ts";
 export { activityText } from "./activity-text.ts";
 export { durationText } from "./duration-text.ts";
-export { clampToWidth, sanitizeTerminalLine, sanitizeTerminalText } from "./terminal-text.ts";
+export { modelText } from "./model-text.ts";
+export {
+  clampToWidth,
+  columnLimit,
+  sanitizeTerminalLine,
+  sanitizeTerminalText,
+} from "./terminal-text.ts";
 export { wrapLines } from "./wrap-text.ts";

package/src/text/model-text.ts

@@ -0,0 +1,10 @@
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+
+/**
+ * One row fact for a concrete model. The text is the model identity exactly as
+ * the Run reported it — never a fallback pattern — so the caller decides only
+ * where the fact sits on the row.
+ */
+export function modelText(model: string): string {
+  return sanitizeTerminalLine(model);
+}

package/src/text/terminal-text.ts

@@ -48,7 +48,9 @@ export function sanitizeTerminalLine(value: string): string {
  * degrades to one column instead of throwing or returning an unbounded line.
  *
  * pi-tui's `truncateToWidth` is deliberately not used: it appends a colour
- * reset sequence, and this package emits unstyled lines only.
+ * reset sequence. This package composes plain text, clamps it here, and applies
+ * style afterwards through the `style/` seam, so no value measured here holds
+ * an escape byte.
  */
 export function clampToWidth(value: string, width: number): string {
   const limit = columnLimit(width);
@@ -64,7 +66,15 @@ export function clampToWidth(value: string, width: number): string {
   return `${text}…`;
 }
 
-function columnLimit(width: number): number {
+/**
+ * The display columns one line may use at this width: the same rule
+ * {@link clampToWidth} cuts by, so a caller that pads a clamped line to the
+ * full width measures against one policy, not a copy of it.
+ *
+ * A width that is not a finite number cannot be measured against, so it
+ * degrades to one column.
+ */
+export function columnLimit(width: number): number {
   if (!Number.isFinite(width)) return 1;
   return Math.max(1, Math.floor(width));
 }

package/src/tree/agent-timers.ts

@@ -0,0 +1,62 @@
+import type { AgentInfo } from "@yaag/runtime";
+import { type AskLedger, askDwellMs } from "./ask-ledger.ts";
+
+/** The two clocks an Agent row shows: time spent inside Asks, and the rest of its lifetime. */
+export interface AgentTimers {
+  readonly activeMs: number;
+  readonly idleMs: number;
+}
+
+/** The part of an Agent the split reads: its state, that state's stamp, and its live Ask. */
+export type TimedAgent = Pick<AgentInfo, "state" | "stateChangedAt" | "askIndex" | "askStartedAt">;
+
+/** Everything the split needs; `now` keeps the calculation clock-free. */
+export interface AgentTimersInput {
+  readonly agent: TimedAgent;
+  readonly ledger: AskLedger;
+  /** The Agent's spawn instant, or null when neither a spawn event nor a Run start was observed. */
+  readonly spawnedAt: number | null;
+  readonly now: number;
+}
+
+/**
+ * Splits an Agent's lifetime into Ask time (`activeMs`) and the remainder
+ * (`idleMs`).
+ *
+ * Both clocks freeze when the Agent exits: an exited Agent measures up to its
+ * exit stamp instead of `now`, so repeated renders give the same pair. Two
+ * edges do not freeze exactly. An exit that carries no stamp
+ * (`stateChangedAt === null`) measures up to `now` and keeps growing, because
+ * there is no instant to freeze at. A second, later exit event replaces the
+ * stamp in the Summary (`canReplaceExit`), which moves the frozen pair forward
+ * once.
+ *
+ * Idle is clamped at zero, because an Ask settled after the exit stamp, or a
+ * missing spawn stamp, can push active past the lifetime.
+ *
+ * The Ask ledger is the source of the active total. A Summary-only state
+ * (`TreeState.fromSummary`, so `yaag_status`, a stored Run in `/yaag`) holds no
+ * ledger: there the live Ask still counts, through `askStartedAt`, but the
+ * Asks that already settled do not, so the active total of such an Agent is a
+ * lower bound and its idle time an over-estimate.
+ */
+export function agentTimers(input: AgentTimersInput): AgentTimers {
+  const { agent, ledger, spawnedAt, now } = input;
+  const until = agent.state === "exited" ? (agent.stateChangedAt ?? now) : now;
+  let activeMs = ledger.prunedActiveMs;
+  for (const row of ledger.rows) activeMs += askDwellMs(row, until);
+  activeMs += liveAskMs(agent, ledger, until);
+  const lifetimeMs = spawnedAt === null ? activeMs : Math.max(0, until - spawnedAt);
+  return { activeMs, idleMs: Math.max(0, lifetimeMs - activeMs) };
+}
+
+/**
+ * The live Ask the Summary reports but the ledger never saw, so a Summary-only
+ * Agent that is asking does not report `active 0s`. Zero when the ledger
+ * already holds that Ask, which keeps it counted exactly once.
+ */
+function liveAskMs(agent: TimedAgent, ledger: AskLedger, until: number): number {
+  if (agent.state !== "asking" || agent.askStartedAt === null) return 0;
+  if (ledger.rows.some((row) => row.index === agent.askIndex)) return 0;
+  return Math.max(0, until - agent.askStartedAt);
+}

package/src/tree/ask-ledger.ts

@@ -15,24 +15,53 @@ export interface AskRow {
   readonly endedAt: number | null;
   readonly ok: boolean | null;
   readonly replayed: boolean;
+  /** Duration the settlement reported, the fallback when the start was never observed. */
+  readonly durationMs: number | null;
+  /**
+   * The concrete model the Agent ran when the Ask started, restamped by a
+   * mid-Ask model swap that landed, and frozen at settlement (ADR-0041).
+   */
+  readonly model: string | null;
 }
 
 /** One Agent's bounded Ask history, oldest settled Asks rolled into a counter. */
 export interface AskLedger {
   readonly rows: readonly AskRow[];
   readonly settledPruned: number;
+  /** Elapsed time of the settled rows this ledger dropped, so an Agent's active total survives pruning. */
+  readonly prunedActiveMs: number;
+}
+
+/**
+ * One Ask row's elapsed time. A live row grows until `until`; a settled row
+ * measures its own stamps, and falls back to the duration the settlement
+ * reported when the observer never saw the Ask start.
+ */
+export function askDwellMs(row: AskRow, until: number): number {
+  if (row.endedAt !== null) {
+    if (row.startedAt === null) return Math.max(0, row.durationMs ?? 0);
+    return Math.max(0, row.endedAt - row.startedAt);
+  }
+  if (row.startedAt === null) return 0;
+  return Math.max(0, until - row.startedAt);
 }
 
 /** The ledger of an Agent that has started no Ask. */
 export function emptyLedger(): AskLedger {
-  return { rows: [], settledPruned: 0 };
+  return { rows: [], settledPruned: 0, prunedActiveMs: 0 };
 }
 
 /**
- * Records one Ask start. A repeated start for an index already present keeps
- * the first-seen row, so a redraw cannot duplicate an Ask row.
+ * Records one Ask start. `model` is the concrete model the Agent runs now; it
+ * becomes the new row's stamp. A repeated start for an index already present
+ * keeps the first-seen row and does not restamp it, so a redraw cannot
+ * duplicate an Ask row or rewrite its model.
  */
-export function applyAskStart(ledger: AskLedger, event: AskStartEvent): AskLedger {
+export function applyAskStart(
+  ledger: AskLedger,
+  event: AskStartEvent,
+  model: string | null,
+): AskLedger {
   if (ledger.rows.some((row) => row.index === event.index)) return ledger;
   const row: AskRow = {
     index: event.index,
@@ -41,15 +70,25 @@ export function applyAskStart(ledger: AskLedger, event: AskStartEvent): AskLedge
     endedAt: null,
     ok: null,
     replayed: event.replayed === true,
+    durationMs: null,
+    model,
   };
-  return prune({ rows: [...ledger.rows, row], settledPruned: ledger.settledPruned });
+  return prune({ ...ledger, rows: [...ledger.rows, row] });
 }
 
 /**
  * Records one Ask settlement. A settlement for an index the ledger never saw
  * start still records a row, so a late observer keeps the Ask count honest.
+ *
+ * `model` stamps that never-observed row alone. A row the ledger already holds
+ * keeps its own model, which a landed swap restamped while the row was live,
+ * so the settled row states the model that settled it.
  */
-export function applyAskEnd(ledger: AskLedger, event: AskEndEvent): AskLedger {
+export function applyAskEnd(
+  ledger: AskLedger,
+  event: AskEndEvent,
+  model: string | null,
+): AskLedger {
   const index = ledger.rows.findIndex((row) => row.index === event.index);
   if (index === -1) {
     const row: AskRow = {
@@ -59,13 +98,33 @@ export function applyAskEnd(ledger: AskLedger, event: AskEndEvent): AskLedger {
       endedAt: event.at,
       ok: event.ok,
       replayed: false,
+      durationMs: event.durationMs,
+      model,
     };
-    return prune({ rows: [...ledger.rows, row], settledPruned: ledger.settledPruned });
+    return prune({ ...ledger, rows: [...ledger.rows, row] });
   }
   const rows = ledger.rows.map((row, position) =>
-    position === index ? { ...row, endedAt: event.at, ok: event.ok } : row,
+    position === index
+      ? { ...row, endedAt: event.at, ok: event.ok, durationMs: event.durationMs }
+      : row,
   );
-  return prune({ rows, settledPruned: ledger.settledPruned });
+  return prune({ ...ledger, rows });
+}
+
+/**
+ * Restamps every live row of one Agent with the concrete model it runs now.
+ * A settled row keeps the model that settled it. The same ledger comes back
+ * when no live row changes, so a redraw keeps its identity.
+ */
+export function stampLiveModel(ledger: AskLedger, model: string): AskLedger {
+  let changed = false;
+  const rows = ledger.rows.map((row) => {
+    if (row.endedAt !== null || row.model === model) return row;
+    changed = true;
+    return { ...row, model };
+  });
+  if (!changed) return ledger;
+  return { ...ledger, rows };
 }
 
 function prune(ledger: AskLedger): AskLedger {
@@ -73,13 +132,20 @@ function prune(ledger: AskLedger): AskLedger {
   const excess = ledger.rows.length - AGENT_ASK_LEDGER_MAX;
   const kept: AskRow[] = [];
   let pruned = 0;
+  let prunedMs = 0;
   for (const row of ledger.rows) {
     if (row.endedAt !== null && pruned < excess) {
       pruned += 1;
+      prunedMs += askDwellMs(row, row.endedAt);
+      // A settled row ignores `until`; its own stamps bound it.
       continue;
     }
     kept.push(row);
   }
   if (pruned === 0) return ledger;
-  return { rows: kept, settledPruned: ledger.settledPruned + pruned };
+  return {
+    rows: kept,
+    settledPruned: ledger.settledPruned + pruned,
+    prunedActiveMs: ledger.prunedActiveMs + prunedMs,
+  };
 }

package/src/tree/details-pane.ts

@@ -1,11 +1,14 @@
+import { identityStyler, renderStyledLine, type TreeStyler } from "../style/index.ts";
 import { clampToWidth, sanitizeTerminalLine } from "../text/index.ts";
-import { stateGlyph } from "./tree-glyphs.ts";
+import { stateGlyph, stateToken } from "./tree-glyphs.ts";
 import type { TreeNode } from "./tree-node.ts";
 
 /** The bounded last-output lines the pane draws under the selected node. */
 export interface DetailsPaneOptions {
   readonly width: number;
   readonly outputTail: readonly string[];
+  /** Colours the header's state glyph; defaults to identity (spec D10). */
+  readonly styler?: TreeStyler;
 }
 
 /**
@@ -19,7 +22,13 @@ export function renderDetailsPane(
 ): readonly string[] {
   if (node === undefined) return [];
   const lines = [
-    clampToWidth(`${stateGlyph(node.state)} ${sanitizeTerminalLine(node.path)}`, options.width),
+    renderStyledLine(
+      [
+        { text: stateGlyph(node.state), token: stateToken(node.state) },
+        { text: ` ${sanitizeTerminalLine(node.path)}` },
+      ],
+      { width: options.width, styler: options.styler ?? identityStyler },
+    ),
   ];
   if (node.activityGist !== null)
     lines.push(clampToWidth(`  ${sanitizeTerminalLine(node.activityGist)}`, options.width));

package/src/tree/tree-glyphs.ts

@@ -1,3 +1,4 @@
+import type { StyleToken } from "../style/index.ts";
 import type { TreeNodeState } from "./tree-node.ts";
 
 /** The glyphs the normative tree mockup uses (`.scratch/run-tree-tui/assets`). */
@@ -26,6 +27,20 @@ export function stateGlyph(state: TreeNodeState): string {
   }
 }
 
+/** The style token a row's state glyph and leading state word carry. */
+export function stateToken(state: TreeNodeState): StyleToken {
+  switch (state) {
+    case "running":
+      return "running";
+    case "exited":
+      return "exited";
+    case "failed":
+      return "failed";
+    case "idle":
+      return "idle";
+  }
+}
+
 /** The fold glyph one tree row draws: expanded, collapsed, or nothing for a leaf. */
 export function foldGlyph(hasChildren: boolean, expanded: boolean): string {
   if (!hasChildren) return " ";

package/src/tree/tree-model.ts

@@ -3,10 +3,12 @@ import {
   activityText,
   costText,
   durationText,
+  modelText,
   sanitizeTerminalLine,
   tokensText,
 } from "../text/index.ts";
-import type { AskRow } from "./ask-ledger.ts";
+import { type AgentTimers, agentTimers } from "./agent-timers.ts";
+import { type AskRow, askDwellMs } from "./ask-ledger.ts";
 import { graftNestedNodes } from "./tree-nested.ts";
 import type { TreeNode } from "./tree-node.ts";
 import type { TreeState } from "./tree-state.ts";
@@ -39,7 +41,12 @@ function agentNode(state: TreeState, name: string, agent: AgentInfo, now: number
   const nested = graftNestedNodes(name, agent.nodes, now);
   const gist = agent.activity === null ? null : activityText(agent.activity);
   const children: TreeNode[] = ledger.rows.map((row) =>
-    askNode(name, row, nested.get(row.index) ?? [], now, gist),
+    askNode(row, nested.get(row.index) ?? [], {
+      agent: name,
+      now,
+      activityGist: gist,
+      agentModel: agent.model,
+    }),
   );
   const finished = agent.finishedNodesPruned + ledger.settledPruned;
   if (finished > 0) children.push(rollup(`${name}#pruned`, `and ${finished} more finished`));
@@ -48,23 +55,32 @@ function agentNode(state: TreeState, name: string, agent: AgentInfo, now: number
     kind: "agent",
     label: sanitizeTerminalLine(name),
     state: agentState(agent),
-    facts: agentFacts(agent, state.settledAsks(name), now),
+    facts: agentFacts(
+      agent,
+      state.settledAsks(name),
+      agentTimers({ agent, ledger, spawnedAt: state.spawnedAt(name), now }),
+    ),
     children,
     activityGist: gist,
     startedAt: agent.stateChangedAt,
   };
 }
 
-function askNode(
-  agent: string,
-  row: AskRow,
-  children: readonly TreeNode[],
-  now: number,
-  activityGist: string | null,
-): TreeNode {
+/** Render-time inputs one Ask row needs beyond the row itself. */
+interface AskNodeOptions {
+  readonly agent: string;
+  readonly now: number;
+  readonly activityGist: string | null;
+  /** Fallback stamp for a live row whose `agent_model` occurrence was dropped. */
+  readonly agentModel: string | null;
+}
+
+function askNode(row: AskRow, children: readonly TreeNode[], options: AskNodeOptions): TreeNode {
+  const { agent, now, activityGist } = options;
   const live = row.endedAt === null;
-  const dwell = live ? now - (row.startedAt ?? now) : row.endedAt - (row.startedAt ?? row.endedAt);
-  const facts = [durationText(dwell)];
+  const model = row.model ?? (live ? options.agentModel : null);
+  const facts = [durationText(askDwellMs(row, now))];
+  if (model !== null) facts.push(modelText(model));
   if (row.replayed) facts.push("replayed");
   return {
     path: `${sanitizeTerminalLine(agent)}:${row.index}`,
@@ -96,16 +112,22 @@ function agentState(agent: AgentInfo): TreeNode["state"] {
   return agent.state === "asking" ? "running" : "idle";
 }
 
-function agentFacts(agent: AgentInfo, settled: number, now: number): readonly string[] {
+/**
+ * The Agent row's facts. The headline fact keeps the Agent's state and both
+ * timers in one string, because the compact and inline frames render only the
+ * first fact.
+ */
+function agentFacts(agent: AgentInfo, settled: number, timers: AgentTimers): readonly string[] {
+  const clocks = `active ${durationText(timers.activeMs)} · idle ${durationText(timers.idleMs)}`;
   const facts: string[] = [];
-  if (agent.state === "asking")
-    facts.push(`ask #${agent.askIndex + 1} · ${durationText(now - (agent.askStartedAt ?? now))}`);
+  if (agent.state === "asking") facts.push(`ask #${agent.askIndex + 1} · ${clocks}`);
   else if (agent.state === "exited")
-    facts.push(`exited · ${settled} ask${settled === 1 ? "" : "s"}`);
-  else facts.push(`idle · ${durationText(now - (agent.stateChangedAt ?? now))}`);
+    facts.push(`exited · ${settled} ask${settled === 1 ? "" : "s"} · ${clocks}`);
+  else facts.push(clocks);
   facts.push(
     `${costText(agent.cost, agent.incomplete)} · ${tokensText(agent.tokens?.total ?? null)}`,
   );
+  if (agent.model !== null) facts.push(modelText(agent.model));
   const last = agent.modelFallbacks.at(-1);
   if (last !== undefined) {
     facts.push(sanitizeTerminalLine(`fallback · ${last.failedModel} → ${last.resolvedModel}`));

package/src/tree/tree-render.ts

@@ -1,4 +1,5 @@
 import { agentOfPath } from "../node/index.ts";
+import type { TreeStyler } from "../style/index.ts";
 import { clampToWidth, costText, durationText, sanitizeTerminalLine } from "../text/index.ts";
 import { renderDetailsPane } from "./details-pane.ts";
 import { emptyFold, type FoldState, type VisibleRow, visibleRows } from "./tree-fold.ts";
@@ -30,17 +31,26 @@ export interface TreeRenderOptions {
    * It defaults to `true`.
    */
   readonly interactive?: boolean;
+  /**
+   * Colours the tree. Defaults to identity, so a surface that passes none —
+   * the transcript component, the snapshot, the CLI — gets byte-identical
+   * plain lines. A styler also turns on the selected row's full-width
+   * background fill: without a background colour the fill is only trailing
+   * whitespace (spec D10).
+   */
+  readonly styler?: TreeStyler;
 }
 
 /**
  * Renders the four-region frame — header, tree, details pane, key footer — plus
- * the Result of a settled Run, as unstyled terminal lines, every line truncated
- * to `width`. `interactive: false` drops the regions a surface that takes no
+ * the Result of a settled Run, every line truncated to `width` as plain text
+ * and coloured afterwards through the optional styler seam. `interactive: false` drops the regions a surface that takes no
  * input has no use for. A tree that has rows keeps the rule above it and the
  * rule below it; the Result is then the last region, and it gets no rule below
  * it.
  *
- * Pure over the state: two calls with the same state and options return equal
+ * Pure over the state: a styler is a pure pair, so two calls with the same
+ * state, options and styler return equal
  * arrays. Every untrusted string passes `sanitizeTerminalLine` first, so a
  * hostile gist or path can neither add a line nor emit an escape byte.
  */
@@ -57,6 +67,7 @@ export function renderTree(state: TreeState, options: TreeRenderOptions): readon
   const details = renderDetailsPane(selected, {
     width: options.width,
     outputTail: selected === undefined ? [] : state.outputTail(agentOfPath(selected.path)),
+    ...(options.styler === undefined ? {} : { styler: options.styler }),
   });
   if (details.length > 0) lines.push(...details, rule);
   const result = options.result ?? state.result;
@@ -75,7 +86,11 @@ export function renderTree(state: TreeState, options: TreeRenderOptions): readon
 function treeLines(rows: readonly VisibleRow[], options: TreeRenderOptions): readonly string[] {
   const shown = rows.slice(0, MAX_TREE_ROWS);
   const lines = shown.flatMap((row) =>
-    renderRow(row, { width: options.width, selectedPath: options.selectedPath }),
+    renderRow(row, {
+      width: options.width,
+      ...(options.selectedPath === undefined ? {} : { selectedPath: options.selectedPath }),
+      ...(options.styler === undefined ? {} : { styler: options.styler }),
+    }),
   );
   const hidden = rows.length - shown.length;
   if (hidden > 0) lines.push(clampToWidth(` and ${hidden} more running`, options.width));

package/src/tree/tree-rows.ts

@@ -1,11 +1,18 @@
-import { clampToWidth, sanitizeTerminalLine } from "../text/index.ts";
+import { identityStyler, renderStyledLine, type Span, type TreeStyler } from "../style/index.ts";
+import { sanitizeTerminalLine } from "../text/index.ts";
 import type { VisibleRow } from "./tree-fold.ts";
-import { foldGlyph, GLYPHS, stateGlyph } from "./tree-glyphs.ts";
+import { foldGlyph, GLYPHS, stateGlyph, stateToken } from "./tree-glyphs.ts";
 
 /** Marks the selected row in the drawn tree, matched by node path. */
 export interface TreeRowOptions {
   readonly width: number;
   readonly selectedPath?: string;
+  /**
+   * Colours the row. Without one the row stays plain, and the selected row
+   * gets no full-width fill: a fill with no background colour is only
+   * trailing whitespace (spec D10).
+   */
+  readonly styler?: TreeStyler;
 }
 
 /**
@@ -13,26 +20,69 @@ export interface TreeRowOptions {
  * current tool-call gist when the row draws no children of its own.
  *
  * Every untrusted string is sanitized to one line first, so a hostile gist
- * cannot forge an extra row, and the result is truncated to `width`.
+ * cannot forge an extra row, and the result is truncated to `width` as plain
+ * text before any colour is applied.
  */
 export function renderRow(row: VisibleRow, options: TreeRowOptions): readonly string[] {
   const prefix = ancestryPrefix(row);
   const selected = options.selectedPath === row.node.path;
-  const facts = row.node.facts.map(sanitizeTerminalLine).join(" · ");
-  const head = `${selected ? "❯" : " "}${prefix}${foldGlyph(row.hasChildren, row.expanded)} ${stateGlyph(row.node.state)} ${sanitizeTerminalLine(row.node.label)}`;
-  const lines = [clampToWidth(facts === "" ? head : `${head}   ${facts}`, options.width)];
+  const styler = options.styler ?? identityStyler;
+  const fill = selected && options.styler !== undefined;
+  const lines = [
+    renderStyledLine(headSpans(row, prefix, selected), {
+      width: options.width,
+      styler,
+      ...(fill ? { background: "selected" as const } : {}),
+    }),
+  ];
   const gist = row.node.activityGist;
   if (gist !== null && !row.expanded) {
     lines.push(
-      clampToWidth(
-        ` ${prefix}  ${GLYPHS.branch} ${GLYPHS.running} ${sanitizeTerminalLine(gist)}`,
-        options.width,
+      renderStyledLine(
+        [
+          { text: ` ${prefix}  ${GLYPHS.branch} ` },
+          { text: GLYPHS.running, token: "running" },
+          { text: ` ${sanitizeTerminalLine(gist)}` },
+        ],
+        { width: options.width, styler },
       ),
     );
   }
   return lines;
 }
 
+function headSpans(row: VisibleRow, prefix: string, selected: boolean): readonly Span[] {
+  const node = row.node;
+  return [
+    { text: `${selected ? "❯" : " "}${prefix}${foldGlyph(row.hasChildren, row.expanded)} ` },
+    { text: stateGlyph(node.state), token: stateToken(node.state) },
+    { text: " " },
+    {
+      text: sanitizeTerminalLine(node.label),
+      ...(node.kind === "agent" ? { token: "accent" as const } : {}),
+    },
+    ...factSpans(row),
+  ];
+}
+
+/**
+ * The facts tail. Its leading word is the node's own state (`running 22s`,
+ * `exited · 2 asks · …`), so that word carries the state colour and the rest
+ * of the tail stays plain.
+ */
+function factSpans(row: VisibleRow): readonly Span[] {
+  const facts = row.node.facts.map(sanitizeTerminalLine).join(" · ");
+  if (facts === "") return [];
+  const state = row.node.state;
+  if (facts.startsWith(state))
+    return [
+      { text: "   " },
+      { text: state, token: stateToken(state) },
+      { text: facts.slice(state.length) },
+    ];
+  return [{ text: `   ${facts}` }];
+}
+
 function ancestryPrefix(row: VisibleRow): string {
   let prefix = "";
   for (let depth = 0; depth < row.depth; depth += 1) {

package/src/tree/tree-state.ts

@@ -1,6 +1,12 @@
 import { applyEvent, initialSummary, type LifecycleEvent, type RunSummary } from "@yaag/runtime";
 import { sanitizeTerminalText } from "../text/index.ts";
-import { type AskLedger, applyAskEnd, applyAskStart, emptyLedger } from "./ask-ledger.ts";
+import {
+  type AskLedger,
+  applyAskEnd,
+  applyAskStart,
+  emptyLedger,
+  stampLiveModel,
+} from "./ask-ledger.ts";
 
 const MAX_TAIL_CHARS = 2_048;
 const TAIL_LINES = 2;
@@ -30,6 +36,7 @@ export class TreeState {
   readonly #order: string[];
   readonly #ledgers = new Map<string, AskLedger>();
   readonly #tails = new Map<string, OutputTail>();
+  readonly #spawnedAt = new Map<string, number>();
   #highestSequence: number | undefined;
   #id: string | undefined;
   #result: string | undefined;
@@ -121,6 +128,19 @@ export class TreeState {
     return Math.max(settled, settledFromSummary(this.#summary.agents[agent]));
   }
 
+  /**
+   * The instant an Agent's lifetime starts: its observed spawn, else the Run's
+   * start, because an Agent cannot predate its Run. Null when neither is known.
+   *
+   * A Summary-only state (a stored Run record, `yaag_status`) holds no spawn
+   * event, so a late-spawned Agent falls back to the Run start and its idle
+   * time is an over-estimate. Such a state also holds no Ask ledger, so its
+   * active total counts the live Ask alone (see `agentTimers`).
+   */
+  spawnedAt(agent: string): number | null {
+    return this.#spawnedAt.get(agent) ?? this.#summary.startedAt ?? null;
+  }
+
   /** The bounded, sanitized two-line output tail for an Agent's live Ask. */
   outputTail(agent: string): readonly string[] {
     const tail = this.#tails.get(agent);
@@ -154,19 +174,44 @@ export class TreeState {
 
   #project(event: LifecycleEvent): void {
     switch (event.type) {
+      case "agent_spawn": {
+        const seen = this.#spawnedAt.get(event.agent);
+        this.#spawnedAt.set(event.agent, seen === undefined ? event.at : Math.min(seen, event.at));
+        break;
+      }
       case "ask_start":
-        this.#ledgers.set(event.agent, applyAskStart(this.ledger(event.agent), event));
+        this.#ledgers.set(
+          event.agent,
+          applyAskStart(this.ledger(event.agent), event, this.#modelOf(event.agent)),
+        );
         this.#tails.set(event.agent, { index: event.index, text: "" });
         break;
       case "ask_output":
         this.#appendOutput(event);
         break;
       case "ask_end":
-        this.#ledgers.set(event.agent, applyAskEnd(this.ledger(event.agent), event));
+        this.#ledgers.set(
+          event.agent,
+          applyAskEnd(this.ledger(event.agent), event, this.#modelOf(event.agent)),
+        );
+        break;
+      case "agent_model":
+        // The event, not the Summary, is authoritative here: the fold skips an
+        // exited Agent (ADR-0041), while the ledger restamps live rows only.
+        this.#ledgers.set(event.agent, stampLiveModel(this.ledger(event.agent), event.model));
         break;
     }
   }
 
+  /**
+   * The concrete model an Agent runs now. Both `apply()` and `ingest()` settle
+   * the Summary before they project, so this read is current for the event
+   * being projected.
+   */
+  #modelOf(agent: string): string | null {
+    return this.#summary.agents[agent]?.model ?? null;
+  }
+
   #rememberAgent(event: LifecycleEvent): void {
     if ("agent" in event && !this.#order.includes(event.agent)) this.#order.push(event.agent);
   }

package/src/view/index.ts

@@ -4,6 +4,12 @@
  */
 export { type CompactRenderOptions, compactAgentLine, renderCompact } from "./compact-render.ts";
 export { type InlineRenderOptions, renderInlineRun } from "./inline-render.ts";
+export {
+  type LiveTicker,
+  type LiveTickerOptions,
+  startLiveTicker,
+  type TickerSchedule,
+} from "./live-ticker.ts";
 export {
   createRunTreeView,
   type RunTreeView,

package/src/view/live-ticker.ts

@@ -0,0 +1,55 @@
+/**
+ * The redraw seam an interactive surface runs while a Run is live (spec D11).
+ *
+ * Timers in the tree come from `now` at render time only, so a live Run needs a
+ * redraw each second for its times to advance. Nothing here reads the clock,
+ * and no timer state enters the tree model.
+ */
+
+/**
+ * How often an interactive surface redraws a live Run (spec D11).
+ *
+ * It stays internal: every surface runs the same second, so no caller chooses
+ * an interval.
+ */
+const TICK_MS = 1000;
+
+/** Wakes `tick` every `intervalMs` ms; returns the cancel. Tests inject a fake. */
+export type TickerSchedule = (tick: () => void, intervalMs: number) => () => void;
+
+/** What a live ticker needs to exist. */
+export interface LiveTickerOptions {
+  readonly tick: () => void;
+  /** The interval seam; defaults to a real `setInterval`. Tests inject a fake. */
+  readonly schedule?: TickerSchedule;
+}
+
+/** A running ticker; `stop()` is idempotent and no tick lands after it. */
+export interface LiveTicker {
+  stop(): void;
+}
+
+/** A real interval that never keeps the Host Session or the CLI alive. */
+const defaultSchedule: TickerSchedule = (tick, intervalMs) => {
+  const timer = setInterval(tick, intervalMs);
+  timer.unref?.();
+  return () => clearInterval(timer);
+};
+
+/** Starts a ticker that wakes `tick` until `stop()`. */
+export function startLiveTicker(options: LiveTickerOptions): LiveTicker {
+  const schedule = options.schedule ?? defaultSchedule;
+  let stopped = false;
+  const cancel = schedule(() => {
+    // A tick queued in the same turn as `stop()` must draw nothing.
+    if (stopped) return;
+    options.tick();
+  }, TICK_MS);
+  return {
+    stop(): void {
+      if (stopped) return;
+      stopped = true;
+      cancel();
+    },
+  };
+}

package/src/view/run-tree-view.ts

@@ -15,15 +15,20 @@
  *   level, so a Host Session may consume the byte before this component sees
  *   it; `ctrl+q` is the gesture to document to users.
  *
- * The view owns no clock and no I/O of its own: every capability, including the
- * reap-ladder stop, arrives through `RunTreeViewHost`.
+ * The view reads no clock into the tree model and owns no I/O of its own: every
+ * capability, including the reap-ladder stop, arrives through
+ * `RunTreeViewHost`. `now` enters at render time only; while the Run is live a
+ * 1-second ticker asks the host for a redraw, so the rendered times advance
+ * between fd 3 frames (spec D11). The ticker stops on settle and on dispose.
  */
 import { DrillController, type DrillHost, routeDrillKey, routeMenuKey } from "../drill/index.ts";
 import { renderStopPrompt, STOP_PROMPT_CHOICES } from "../overlay/index.ts";
+import type { TreeStyler } from "../style/index.ts";
 import { clampToWidth } from "../text/index.ts";
 import { routeSessionKey } from "../transcript/index.ts";
 import type { TreeState } from "../tree/index.ts";
 import { buildTree, renderTree, TreeNavigator } from "../tree/index.ts";
+import { startLiveTicker, type TickerSchedule } from "./live-ticker.ts";
 import { type RunViewResult, resultText } from "./run-view-result.ts";
 import {
   applyRunViewAction,
@@ -57,6 +62,16 @@ export interface RunTreeViewOptions {
   readonly host: RunTreeViewHost;
   /** The Run id, e.g. `r1`; heads the tree. */
   readonly label?: string;
+  /**
+   * Colours the tree: `/yaag` passes an adapter over pi's `Theme`, the CLI
+   * passes none and stays plain (spec D10).
+   */
+  readonly styler?: TreeStyler;
+  /**
+   * The interval seam of the live ticker; defaults to a real 1-second
+   * `setInterval`. Tests inject a fake.
+   */
+  readonly schedule?: TickerSchedule;
   now?(): number;
 }
 
@@ -101,6 +116,12 @@ export function createRunTreeView(options: RunTreeViewOptions): RunTreeView {
   let phase: RunPhase = livePhase();
   let result: RunViewResult | undefined;
   let exited = false;
+  // A live Run redraws each second, so its times advance without an event
+  // (spec D11); `apply` stops the ticker as soon as the phase settles.
+  const ticker = startLiveTicker({
+    tick: () => host.requestRender(),
+    ...(options.schedule === undefined ? {} : { schedule: options.schedule }),
+  });
 
   const perform = (effect: RunViewEffect): void => {
     switch (effect) {
@@ -123,6 +144,7 @@ export function createRunTreeView(options: RunTreeViewOptions): RunTreeView {
     const transition = applyRunViewAction(phase, action);
     const changed = transition.phase !== phase;
     phase = transition.phase;
+    if (phase.kind === "settled") ticker.stop();
     if (transition.effect !== undefined) perform(transition.effect);
     if (changed || transition.effect !== undefined) host.requestRender();
   };
@@ -159,6 +181,7 @@ export function createRunTreeView(options: RunTreeViewOptions): RunTreeView {
           ...(options.label === undefined ? {} : { label: options.label }),
           ...(navigator.selectedPath === undefined ? {} : { selectedPath: navigator.selectedPath }),
           fold: navigator.fold,
+          ...(options.styler === undefined ? {} : { styler: options.styler }),
           ...(result === undefined ? {} : { result: resultText(result) }),
         }),
       ];
@@ -191,7 +214,9 @@ export function createRunTreeView(options: RunTreeViewOptions): RunTreeView {
       drill.handleInput(data);
     },
     invalidate(): void {},
-    dispose(): void {},
+    dispose(): void {
+      ticker.stop();
+    },
     settle(settled: RunViewResult): void {
       result = settled;
       // `apply` requests the redraw for the phase change; one settlement is one