@yaag/extension 0.8.3 → 0.10.0

package/docs/authoring.md

@@ -113,3 +113,27 @@ rules. ADR-0022 plans the human-in-the-loop verbs; they are not available yet.
 program again and replays the recorded Asks. A resume needs the program too,
 because a Cassette holds the history of a Run and never the program. See
 [Examples](examples.md#05--record-and-resume).
+
+## Lineage
+
+`parent` names the Agent a spawn belongs under. It is data only: it sets the
+Agent's place in the Run tree, so the TUI and the Run Summary draw the child
+under its parent. It opens no channel between the two Agents, and it ends no
+lifetime — every Agent still dies with the Run.
+
+`parent` takes a Handle a previous spawn in this Run returned, and it works the
+same way as an override on a definition: `ctx.spawn(reviewer, { parent })`. A
+parent that already exited stays a valid parent.
+
+An Agent cannot spawn. It can *ask* for a helper through `outputSchema`, and
+the program decides:
+
+<!-- embed: docs/examples/06-lineage.ts -->
+
+```ts
+    for (const helper of wish.helpers) {
+      if (!ALLOWED_ROLES.has(helper.role)) continue;
+      const agent = await ctx.spawn({ name: helper.role, parent: implementer });
+      reports.push(await agent.ask(prompt`Review this report: ${wish.report}`));
+    }
+```

package/docs/cli.md

@@ -60,6 +60,53 @@ Runs an Orchestration Program. It maps to `yaag run`.
 | `config` | `--config <file>` | Reads one more config file for this Run. |
 | `noConfig` | `--no-config` | Ignores the global config and the project config. |
 
+### The Run block in a pi session
+
+A `yaag_run` call is two lines in the transcript. The first line reads
+`yaag_run(inline:review)  ... (ctrl+o to expand)`, and the second reads
+`r1 · running 1m14s`.
+
+The first line is the call. A file Run shows the path of its program. An inline
+Run shows `inline`, or `inline:<name>` when the Run told yaag the name that the
+program declares. The name comes from the Run, not from the source text.
+
+The second line is the state of the Run: its Run id, its status, and the time.
+The five statuses are:
+
+| status | meaning |
+|---|---|
+| `running` | The Run is live and the call waits for it. |
+| `started` | The Run is in the background and the call returned. |
+| `finished` | The Run ended and its program completed. |
+| `failed` | The Run failed, or the call itself failed. |
+| `interrupted` | The Run stopped, paused, or died before its program ended. |
+
+The hint at the end of the call line names the key that expands the block.
+pi binds `ctrl+o` by default. The hint is not shown when the key is not bound.
+
+The time of a Run that did not end is the time from its start to the last draw
+of the block. The time of a Run that ended is the time the Run took.
+
+The expanded block shows each parameter that the call gives, one on each line,
+and then the full Run tree. A parameter that the call does not give is not
+shown. `script` shows the full program source. A very large source is cut, and
+the block then shows the marker `… (truncated, N bytes total)`. The error
+output of a failed Run is also shown in the expanded block only.
+
+Each Agent row of the Run tree shows two times: `active` and `idle`. The active
+time is the sum of the times of the Asks of the Agent, and it includes the Ask
+that runs now. The idle time is the remainder of the life of the Agent. The two
+times stop when the Agent exits.
+
+The times move each second in the interactive Run tree of `/yaag`, and in the
+inline frame of a blocking Run. In the tool block of the transcript they move
+when a new progress frame comes in. The times stop when the Run ends.
+
+A tree that yaag builds from a stored Run — the tree of `yaag_status`, and the
+tree of a Run that ended before the view opened — keeps no record of each Ask.
+The active time of such a tree counts only the Ask that runs now, so it is a
+minimum, and the idle time is then too large.
+
 ### yaag_status
 
 Reports the Runs of the session, or one Run.

package/docs/examples/06-lineage.ts

@@ -0,0 +1,33 @@
+/**
+ * Mediated autonomy. The implementer reports which helpers it wants; the
+ * program is the gate that decides, spawns them, and places them in the tree
+ * under the implementer with `parent`.
+ */
+import { defineRun, prompt } from "@yaag/runtime";
+import { Type } from "typebox";
+
+const ALLOWED_ROLES = new Set(["reviewer", "summarizer"]);
+
+const Wish = Type.Object({
+  report: Type.String(),
+  helpers: Type.Array(Type.Object({ role: Type.String(), reason: Type.String() })),
+});
+
+export default defineRun({
+  name: "lineage",
+  description: "Spawns the helpers an implementer asks for, under the implementer.",
+  async run(ctx) {
+    const implementer = await ctx.spawn({ name: "implementer" });
+    const wish = await implementer.ask(
+      prompt`Report one paragraph about this repository, and the helper roles you want.`,
+      { outputSchema: Wish },
+    );
+    const reports: string[] = [];
+    for (const helper of wish.helpers) {
+      if (!ALLOWED_ROLES.has(helper.role)) continue;
+      const agent = await ctx.spawn({ name: helper.role, parent: implementer });
+      reports.push(await agent.ask(prompt`Review this report: ${wish.report}`));
+    }
+    return [wish.report, ...reports].join("\n\n");
+  },
+});

package/docs/examples.md

@@ -100,3 +100,20 @@ holds it.
 Full file: [`examples/05-record-resume.ts`](examples/05-record-resume.ts). Run
 it with `yaag run examples/05-record-resume.ts --record run.json`, then resume
 it with `yaag run examples/05-record-resume.ts --resume run.json`.
+
+## 06 — lineage
+
+`parent` places an Agent under another Agent in the Run tree. Here the
+implementer reports the helper roles it wants, and the program decides which of
+them to spawn. The helpers become a subtree of the implementer, and no Agent
+ever spawns anything itself.
+
+<!-- embed: docs/examples/06-lineage.ts -->
+
+```ts
+      const agent = await ctx.spawn({ name: helper.role, parent: implementer });
+      reports.push(await agent.ask(prompt`Review this report: ${wish.report}`));
+```
+
+Full file: [`examples/06-lineage.ts`](examples/06-lineage.ts). Run it with
+`yaag run examples/06-lineage.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.8.3",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -25,9 +25,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.8.3",
-    "@yaag/runtime": "0.8.3",
-    "@yaag/tui": "0.8.3",
+    "@yaag/cli": "0.10.0",
+    "@yaag/runtime": "0.10.0",
+    "@yaag/tui": "0.10.0",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/docs/docs-root.ts

@@ -18,13 +18,14 @@ export const DOC_PAGES = [
   "troubleshooting.md",
 ] as const;
 
-/** The five shipped example programs, in reading order. */
+/** The shipped example programs, in reading order. */
 export const EXAMPLE_FILES = [
   "01-minimal.ts",
   "02-args.ts",
   "03-fan-out.ts",
   "04-controlled-ask.ts",
   "05-record-resume.ts",
+  "06-lineage.ts",
 ] as const;
 
 /** Absolute path of one shipped doc file, named relative to the docs root. */

package/src/record/index.ts

@@ -10,6 +10,7 @@ export {
   programExpansion,
   programLabel,
   programTarget,
+  type RunCallParams,
 } from "./run-program-param.ts";
 export type { RunLaunch, RunRecord } from "./run-record.ts";
 export {

package/src/record/run-program-param.ts

@@ -15,6 +15,15 @@ export interface ProgramParams {
   readonly resume?: string;
 }
 
+/** Every `yaag_run` parameter, as the expanded call view lists them. */
+export interface RunCallParams extends ProgramParams {
+  readonly args?: string;
+  readonly background?: boolean;
+  readonly record?: string;
+  readonly config?: string;
+  readonly noConfig?: boolean;
+}
+
 /** The expanded view keeps at most this many source lines. */
 const EXPANSION_LINES = 200;
 /** The expanded view keeps at most this many source bytes. */
@@ -94,30 +103,34 @@ export async function confirmProgramTarget(target: ProgramTarget): Promise<Progr
  * The label never quotes the source. `yaag_run` has no approval gate, so any
  * text taken from an Inline Program would be a trust-bearing string the model
  * chose — a comment or an unrelated `name:` could name a program that is not
- * the one that runs. The Inline Program branch states only what the extension
- * measured: its kind and its size in bytes. The source itself is shown, whole,
- * in the expanded view ({@link programExpansion}).
+ * the one that runs. An Inline Program is therefore `inline`, and `inline:<name>`
+ * only when `name` is given: the caller reads that name from the Run's own
+ * `run_start` event, so it is the name the program that actually ran declared.
+ * The source itself is shown, whole, in the expanded view ({@link programExpansion}).
  *
- * The two caller-controlled branches — a file path and a Checkpoint path — are
+ * Every caller-controlled branch — a file path and a program name — is
  * sanitized to one line and clamped to {@link LABEL_WIDTH} columns, so a
- * hostile path can neither emit an escape byte nor overflow the call line. The
- * clamp covers the whole `Inline Program from …` text, prefix included.
+ * hostile path can neither emit an escape byte nor overflow the call line.
  */
-export function programLabel(params: ProgramParams): string {
+export function programLabel(params: ProgramParams, name?: string): string {
   const { file, script } = params;
   if (file !== undefined && script !== undefined) return "(invalid call)";
   if (script !== undefined) {
     if (script.trim() === "") return "(empty script)";
-    const bytes = byteCount(script);
-    return `Inline Program, ${bytes} ${bytes === 1 ? "byte" : "bytes"}`;
+    return inlineLabel(name);
   }
   if (file !== undefined) return safeLabel(file);
   // A resume with no file and no script is a valid call: the source comes from
-  // the Run record, and the label names the Checkpoint the source belongs to.
-  if (params.resume !== undefined) return safeLabel(`Inline Program from ${params.resume}`);
+  // the Run record, so the label names the Inline Program, and the Checkpoint
+  // path is one of the parameters the expanded view lists.
+  if (params.resume !== undefined) return inlineLabel(name);
   return "(invalid call)";
 }
 
+function inlineLabel(name: string | undefined): string {
+  return name === undefined || name.trim() === "" ? "inline" : safeLabel(`inline:${name}`);
+}
+
 function safeLabel(value: string): string {
   return clampToWidth(sanitizeTerminalLine(value), LABEL_WIDTH);
 }

package/src/record/run-summary-parse.ts

@@ -150,6 +150,10 @@ function parseAgent(value: unknown): AgentInfo | null {
     nodes,
     finishedNodesPruned: stored.finishedNodesPruned,
     modelFallbacks: fallbacks,
+    // Lineage is tolerant for the same reason as the counters: a record written
+    // before the Parent Link carries neither field.
+    parent: isNullableString(stored.parent) ? stored.parent : null,
+    origin: stored.origin === "fork" ? ("fork" as const) : ("spawn" as const),
     // Tolerant for the same reason as the Run-level counter.
     modelFallbacksPruned:
       typeof stored.modelFallbacksPruned === "number" ? stored.modelFallbacksPruned : 0,

package/src/testing/fake-extension-ui.ts

@@ -1,6 +1,10 @@
 /**
  * A fully typed `ExtensionUIContext` for the tui-mode test context.
  *
+ * `custom` mirrors pi's interactive mode: when the component resolves `done`,
+ * the view closes and `component.dispose?.()` runs, so a test sees the same
+ * teardown a Host Session gives.
+ *
  * `custom`, `notify`, `setWidget`, `setStatus`, and a scripted `select` work;
  * every other capability throws, so a dependency a view is not supposed to
  * have fails loudly. The
@@ -69,20 +73,32 @@ export class FakeExtensionUi implements ExtensionUIContext {
       done: (result: T) => void,
     ) => (Component & { dispose?(): void }) | Promise<Component & { dispose?(): void }>,
   ): Promise<T> {
+    let closed = false;
+    let component: (Component & { dispose?(): void }) | undefined;
     let resolve: (value: T) => void = () => {};
     const promise = new Promise<T>((settle) => {
-      resolve = settle;
+      resolve = (value) => {
+        if (closed) return;
+        closed = true;
+        // Pi disposes the component when the view closes; the fake must not
+        // diverge, or a leak test would pass falsely.
+        component?.dispose?.();
+        settle(value);
+      };
     });
     // Synchronous on purpose: a test drives the component right after the call,
     // with no scheduling of its own.
-    const component = factory(this.#tui, this.theme, loadPiKeybindings(), resolve);
-    if (component instanceof Promise) {
+    const opened = factory(this.#tui, this.theme, loadPiKeybindings(), resolve);
+    if (opened instanceof Promise) {
       throw new TypeError("FakeExtensionUi.custom: the factory must return a component directly");
     }
+    component = opened;
+    // A factory that resolved `done` before it returned closed the view already.
+    if (closed) opened.dispose?.();
     const tui = this.#tui;
     this.opened = {
-      render: (width) => component.render(width),
-      input: (data) => component.handleInput?.(data),
+      render: (width) => opened.render(width),
+      input: (data) => opened.handleInput?.(data),
       get renders() {
         return tui.renders;
       },

package/src/testing/fake-theme.ts

@@ -5,7 +5,7 @@
  * context needs one. The table is written out in full: TypeScript checks it
  * against `ThemeColor`/`ThemeBg`, which keeps the double honest without a cast.
  */
-import { Theme } from "@earendil-works/pi-coding-agent";
+import { Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
 
 /** Default 256-colour indexes; every colour renders as plain text. */
 const FOREGROUND = {
@@ -66,7 +66,12 @@ const BACKGROUND = {
   toolErrorBg: 0,
 } as const satisfies Record<string, number>;
 
-/** Builds the test theme. Colours are inert, so frames stay comparable. */
-export function fakeTheme(): Theme {
-  return new Theme(FOREGROUND, BACKGROUND, "256color", { name: "test" });
+/**
+ * Builds the test theme. Colours are inert, so frames stay comparable.
+ *
+ * `overrides` gives single colours a distinct index, for a test that asserts
+ * two theme colours differ.
+ */
+export function fakeTheme(overrides: Partial<Record<ThemeColor, number>> = {}): Theme {
+  return new Theme({ ...FOREGROUND, ...overrides }, BACKGROUND, "256color", { name: "test" });
 }

package/src/testing/index.ts

@@ -4,7 +4,15 @@
  */
 export { fakeStart } from "./fake-run-start.ts";
 export { loadPiKeybindings } from "./pi-keybindings.ts";
-export { renderCallLabel, renderCallLines } from "./run-call-render.ts";
+export {
+  type RenderedBlock,
+  type RunParams,
+  renderBlock,
+  renderBlockLines,
+  renderCallLabel,
+  renderCallLines,
+  renderResultLines,
+} from "./run-call-render.ts";
 export {
   asError,
   fixture,

package/src/testing/run-call-render.ts

@@ -1,7 +1,15 @@
+/**
+ * Render seams for the `yaag_run` transcript block: the call render, the result
+ * render, and the two together through one shared row state, in pi's own order.
+ */
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
 import { stripTerminalSequences } from "@earendil-works/pi-tui";
+import { initialSummary } from "@yaag/runtime";
 import { resolveBun, resolveCliEntry } from "../process/index.ts";
 import { RunRegistry } from "../record/index.ts";
 import { createRunTool } from "../tool/index.ts";
+import type { RunDetails } from "../view/index.ts";
 import { fakeTheme } from "./fake-theme.ts";
 
 const cli = resolveCliEntry();
@@ -20,40 +28,149 @@ export interface RunParams {
   readonly noConfig?: boolean;
 }
 
-function renderCallComponent(params: RunParams, expanded: boolean) {
-  const tool = createRunTool({
+/** How one render pass sees the row. */
+export interface RenderView {
+  readonly expanded?: boolean;
+  readonly isPartial?: boolean;
+  readonly isError?: boolean;
+  /** The result's text content. */
+  readonly content?: string;
+}
+
+function tool() {
+  return createRunTool({
     bun,
     cli,
     registry: new RunRegistry(),
     sendMessage: () => undefined,
   });
-  const component = tool.renderCall?.(params, fakeTheme(), {
+}
+
+interface Row {
+  readonly state: Record<string, unknown>;
+  invalidate: () => void;
+}
+
+function context(params: RunParams, view: RenderView, row: Row, last?: Component) {
+  return {
     args: params,
     toolCallId: "call-1",
-    invalidate: () => {},
-    lastComponent: undefined,
-    state: undefined,
+    invalidate: () => row.invalidate(),
+    lastComponent: last,
+    state: row.state,
     cwd: process.cwd(),
     executionStarted: false,
     argsComplete: true,
-    isPartial: false,
-    expanded,
+    isPartial: view.isPartial ?? false,
+    expanded: view.expanded ?? false,
     showImages: false,
-    isError: false,
-  });
-  return component;
+    isError: view.isError ?? false,
+  };
+}
+
+function newRow(): Row {
+  return { state: {}, invalidate: () => {} };
+}
+
+/**
+ * The result pi hands a render. A result restored from a transcript, and an
+ * errored call, carry no `details` at all: the key is removed rather than set
+ * to undefined, which is the shape the render meets at run time.
+ */
+function toolResult(details: RunDetails | undefined, text: string): AgentToolResult<RunDetails> {
+  const content = [{ type: "text" as const, text }];
+  const summary: RunDetails = details ?? { summary: initialSummary() };
+  const result: AgentToolResult<RunDetails> = { content, details: summary };
+  if (details === undefined) Reflect.deleteProperty(result, "details");
+  return result;
+}
+
+function lines(component: { render: (width: number) => string[] } | undefined): string[] {
+  return (component?.render(80) ?? []).map(stripTerminalSequences);
 }
 
 /** The call line, stripped of styling, as the collapsed transcript shows it. */
 export function renderCallLabel(params: RunParams): string {
-  return stripTerminalSequences(renderCallComponent(params, false)?.render(80)[0] ?? "");
+  return lines(tool().renderCall?.(params, fakeTheme(), context(params, {}, newRow())))[0] ?? "";
 }
 
 /** Every rendered line of the call, stripped of styling. */
-export function renderCallLines(
-  params: RunParams,
-  options: { readonly expanded?: boolean } = {},
+export function renderCallLines(params: RunParams, view: RenderView = {}): readonly string[] {
+  return lines(tool().renderCall?.(params, fakeTheme(), context(params, view, newRow())));
+}
+
+/** Every rendered line of the result block, stripped of styling. */
+export function renderResultLines(
+  details: RunDetails | undefined,
+  view: RenderView = {},
 ): readonly string[] {
-  const component = renderCallComponent(params, options.expanded ?? false);
-  return (component?.render(80) ?? []).map(stripTerminalSequences);
+  const result = toolResult(details, view.content ?? "");
+  const options = { expanded: view.expanded ?? false, isPartial: view.isPartial ?? false };
+  return lines(tool().renderResult?.(result, options, fakeTheme(), context({}, view, newRow())));
+}
+
+/** What one replay of pi's row rendering produced. */
+export interface RenderedBlock {
+  /** Every line the row's children draw, in order and stripped of styling. */
+  readonly lines: readonly string[];
+  /** The components the row container holds; pi clears it on each pass. */
+  readonly children: number;
+}
+
+/**
+ * Replays pi's own `ToolExecutionComponent.updateDisplay()`: the row container
+ * is cleared, the call renderer runs, then the result renderer, each with the
+ * component it returned last time. `invalidate()` re-runs the whole pass, the
+ * way pi's does, so a renderer that invalidates from inside a pass shows up
+ * here as a second child rather than as a silent extra frame.
+ *
+ * The returned promise settles after the pending microtasks, which is where a
+ * deferred `invalidate()` lands.
+ */
+export async function renderBlock(
+  params: RunParams,
+  details: RunDetails | undefined,
+  view: RenderView = {},
+): Promise<RenderedBlock> {
+  const definition = tool();
+  const result = toolResult(details, view.content ?? "");
+  const options = { expanded: view.expanded ?? false, isPartial: view.isPartial ?? false };
+  let call: Component | undefined;
+  let block: Component | undefined;
+  let children: Component[] = [];
+  const row: Row = { state: {}, invalidate: () => pass() };
+
+  function pass(): void {
+    children = [];
+    call = definition.renderCall?.(params, fakeTheme(), context(params, view, row, call));
+    if (call !== undefined) children.push(call);
+    block = definition.renderResult?.(
+      result,
+      options,
+      fakeTheme(),
+      context(params, view, row, block),
+    );
+    if (block !== undefined) children.push(block);
+  }
+
+  pass();
+  await flushMicrotasks();
+  return { lines: children.flatMap((child) => lines(child)), children: children.length };
+}
+
+/**
+ * Lets every pending microtask run, which is where a deferred `invalidate()`
+ * lands, and any pass it starts in turn.
+ */
+async function flushMicrotasks(): Promise<void> {
+  for (let round = 0; round < 4; round += 1) await Promise.resolve();
+}
+
+/** Every line of the whole transcript block, stripped of styling. */
+export async function renderBlockLines(
+  params: RunParams,
+  details: RunDetails | undefined,
+  view: RenderView = {},
+): Promise<readonly string[]> {
+  return (await renderBlock(params, details, view)).lines;
 }

package/src/tool/run-tool.ts

@@ -11,7 +11,7 @@ import {
   foregroundInline,
   foregroundResult,
   inlineAvailable,
-  RunTreeComponent,
+  RunBlockComponent,
   RunTreeStore,
 } from "../view/index.ts";
 
@@ -161,18 +161,32 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
     renderCall(params, theme, context) {
       const text =
         context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-      text.setText(callBody({ params, theme, expanded: context.expanded }));
+      const name = programNameOf(context.state);
+      text.setText(
+        callBody({
+          params,
+          theme,
+          expanded: context.expanded,
+          ...(name === undefined ? {} : { name }),
+        }),
+      );
       return text;
     },
-    renderResult(result, _options, _theme, context) {
+    renderResult(result, options, _theme, context) {
       const details = result.details;
-      if (details === undefined) return new Text(contentText(result), 0, 0);
-      const tree =
-        context.lastComponent instanceof RunTreeComponent
+      const block =
+        context.lastComponent instanceof RunBlockComponent
           ? context.lastComponent
-          : new RunTreeComponent(details);
-      tree.update(details);
-      return tree;
+          : new RunBlockComponent();
+      const text = contentText(result);
+      block.update(details, {
+        expanded: options.expanded,
+        isPartial: options.isPartial,
+        isError: context.isError,
+        ...(text === "" ? {} : { errorText: text }),
+      });
+      publishProgramName(block.programName(), context);
+      return block;
     },
     async execute(_id, params, signal, onUpdate, ctx) {
       // Shape only, before the Bun check: an exactly-one-of violation, an empty
@@ -232,6 +246,42 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
   };
 }
 
+/**
+ * The declared program name the result render left in pi's per-row state, which
+ * pi types loosely; the call render reads it back through a real guard.
+ */
+function programNameOf(state: unknown): string | undefined {
+  if (!isRowState(state)) return undefined;
+  const name = state.programName;
+  return typeof name === "string" ? name : undefined;
+}
+
+/**
+ * Writes the name into the shared row state and asks pi to draw the row again,
+ * because the call render of this pass already ran without the name.
+ *
+ * The redraw is deferred off this pass: pi's `invalidate()` re-runs the row's
+ * `updateDisplay()` at once (pi
+ * `dist/modes/interactive/components/tool-execution.js`, `invalidate()` and
+ * `updateDisplay()`), which clears the row container and renders the call and
+ * the result again, so a call from inside the result render would add a second
+ * result component to the same row. The state is written first, so the deferred
+ * pass finds the name already published and stops there.
+ */
+function publishProgramName(
+  name: string | undefined,
+  context: { readonly state: unknown; readonly invalidate: () => void },
+): void {
+  if (name === undefined || !isRowState(context.state)) return;
+  if (context.state.programName === name) return;
+  context.state.programName = name;
+  queueMicrotask(() => context.invalidate());
+}
+
+function isRowState(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /**
  * Cassette and config paths are `resolve`d here; the CLI owns every rule about
  * them — combinations, validation, refusals — and its own message surfaces on

package/src/view/index.ts

@@ -19,7 +19,14 @@ export {
   inlineAvailable,
 } from "./run-foreground.ts";
 export { boundedRuns, RUN_LISTING_CAP } from "./run-listing.ts";
+export { RunBlockComponent, type RunBlockView } from "./run-result-block.ts";
+export {
+  type RunBlockStatus,
+  runBlockStatus,
+  runStatusLine,
+} from "./run-status-line.ts";
 export { RunTreeComponent } from "./run-tree-component.ts";
 export { RunTreeStore } from "./run-trees.ts";
+export { themeStyler } from "./theme-styler.ts";
 export { toUsage } from "./usage.ts";
 export { createYaagCommand } from "./yaag-command.ts";

package/src/view/run-call-body.ts

@@ -1,42 +1,49 @@
 /**
- * The text of one `yaag_run` call, as the transcript shows it: the call head,
- * and under it either the Inline Program source or the hint that names the key
- * which shows that source.
+ * The text of one `yaag_run` call, as the transcript shows it: the call head
+ * alone when the row is collapsed, and the head over every parameter the call
+ * passed when it is expanded.
+ *
+ * The call render stays parameter-only: the Run id, the status and the tree
+ * belong to the result render (`run-result-block.ts`).
  */
 import { keyText, type Theme } from "@earendil-works/pi-coding-agent";
-import { type ProgramParams, programExpansion, programLabel } from "../record/index.ts";
+import { programLabel, type RunCallParams } from "../record/index.ts";
+import { callParamLines } from "./run-call-params.ts";
 
 /** What the call render needs: the call itself, its styling, and its state. */
 export interface CallBodyOptions {
-  readonly params: ProgramParams;
+  readonly params: RunCallParams;
   readonly theme: Theme;
-  /** True while pi shows the call expanded, where the source replaces the hint. */
+  /** True while pi shows the row expanded, where the parameter listing appears. */
   readonly expanded: boolean;
+  /** The declared name of the program that ran, when the result render knows it. */
+  readonly name?: string;
 }
 
 /**
- * The head alone, the head over the program source, or the head over the expand
- * hint. A call with no source to show gets no hint, because the hint would
- * promise an empty view.
+ * The head, with the expand hint appended while the row is collapsed, so the
+ * collapsed block stays exactly one call line over one status line. Expanded,
+ * the head carries the parameter listing under it.
  */
 export function callBody(options: CallBodyOptions): string {
   const { params, theme } = options;
   const head =
-    theme.fg("toolTitle", theme.bold("yaag_run")) + theme.fg("muted", `(${programLabel(params)})`);
-  const expansion = programExpansion(params);
-  if (expansion === "") return head;
-  if (options.expanded) return `${head}\n${theme.fg("muted", expansion)}`;
-  const hint = expandHint(theme);
-  return hint === "" ? head : `${head}\n${hint}`;
+    theme.fg("toolTitle", theme.bold("yaag_run")) +
+    theme.fg("muted", `(${programLabel(params, options.name)})`);
+  if (!options.expanded) {
+    const hint = expandHint(theme);
+    return hint === "" ? head : `${head}  ${hint}`;
+  }
+  const lines = callParamLines(params);
+  return lines.length === 0 ? head : `${head}\n${theme.fg("muted", lines.join("\n"))}`;
 }
 
 /**
- * The muted second line that tells the reader which key shows the program
- * source. It reads the bound key, so a rebound keymap stays correct, and it is
- * empty when the action has no key at all, because a hint that names no key
- * tells the reader nothing.
+ * The muted hint that tells the reader which key expands the row. It reads the
+ * bound key, so a rebound keymap stays correct, and it is empty when the action
+ * has no key at all, because a hint that names no key tells the reader nothing.
  *
- * The caller's `Theme` styles the whole line `muted`. pi's own `keyHint` (pi
+ * The caller's `Theme` styles the whole hint `muted`. pi's own `keyHint` (pi
  * `docs/extensions.md`, keybinding hints) styles the key `dim` and the
  * description `muted` from a module-global theme instead, which a Host Session
  * installs but a test does not.

package/src/view/run-call-params.ts

@@ -0,0 +1,36 @@
+/**
+ * The parameter listing of an expanded `yaag_run` call: one line per parameter
+ * the caller actually passed, in a fixed order, with the Inline Program source
+ * last. A parameter that was not passed prints nothing — the view never invents
+ * a default the call did not state.
+ */
+import { clampToWidth, sanitizeTerminalLine } from "@yaag/tui";
+import { programExpansion, type RunCallParams } from "../record/index.ts";
+
+/** The widest a listed parameter value may be, in display columns. */
+const VALUE_WIDTH = 100;
+
+/**
+ * The listing, without styling. `script` is rendered as `script:` over the whole
+ * program source, which {@link programExpansion} caps for transcript volume.
+ */
+export function callParamLines(params: RunCallParams): string[] {
+  const lines: string[] = [];
+  if (params.file !== undefined) lines.push(valueLine("file", params.file));
+  if (params.args !== undefined) lines.push(valueLine("args", params.args));
+  if (params.background !== undefined) lines.push(valueLine("background", `${params.background}`));
+  if (params.record !== undefined) lines.push(valueLine("record", params.record));
+  if (params.resume !== undefined) lines.push(valueLine("resume", params.resume));
+  if (params.config !== undefined) lines.push(valueLine("config", params.config));
+  if (params.noConfig !== undefined) lines.push(valueLine("noConfig", `${params.noConfig}`));
+  if (params.script !== undefined) {
+    lines.push("  script:");
+    const source = programExpansion(params);
+    if (source !== "") lines.push(...source.split("\n").map((line) => `  ${line}`));
+  }
+  return lines;
+}
+
+function valueLine(name: string, value: string): string {
+  return `  ${name}: ${clampToWidth(sanitizeTerminalLine(value), VALUE_WIDTH)}`;
+}

package/src/view/run-details.ts

@@ -82,6 +82,8 @@ function normalizeAgents(value: RunSummary): RunSummary {
       finishedNodesPruned: agent.finishedNodesPruned ?? 0,
       modelFallbacks: agent.modelFallbacks ?? [],
       modelFallbacksPruned: agent.modelFallbacksPruned ?? 0,
+      parent: agent.parent ?? null,
+      origin: normalizeOrigin(agent.origin),
     };
   }
   return { ...value, agents, modelFallbacks: value.modelFallbacks ?? 0 };
@@ -166,10 +168,23 @@ function isAgentBase(value: Record<string, unknown>): boolean {
     optionalNodes(value.nodes) &&
     (value.finishedNodesPruned === undefined || natural(value.finishedNodesPruned)) &&
     optionalFallbacks(value.modelFallbacks) &&
-    (value.modelFallbacksPruned === undefined || natural(value.modelFallbacksPruned))
+    (value.modelFallbacksPruned === undefined || natural(value.modelFallbacksPruned)) &&
+    // Lineage is tolerated as absent: a details blob persisted before the
+    // Parent Link carries neither field.
+    (value.parent === undefined || nullableString(value.parent)) &&
+    (value.origin === undefined || typeof value.origin === "string")
   );
 }
 
+/**
+ * An origin a newer CLI may not have shipped yet reads as "spawn", the same way
+ * a stored Run record treats it. A value outside the contract must never drop
+ * the whole details blob and blank the Run view.
+ */
+function normalizeOrigin(value: unknown): "spawn" | "fork" {
+  return value === "fork" ? "fork" : "spawn";
+}
+
 function optionalEvent(value: unknown): value is LifecycleEvent | undefined {
   return value === undefined || isEvent(value);
 }
@@ -183,7 +198,9 @@ function isEvent(value: unknown): value is LifecycleEvent {
       return (
         strings(value.agent, value.model, value.cwd) &&
         optionalString(value.branch) &&
-        optionalString(value.sessionFile)
+        optionalString(value.sessionFile) &&
+        optionalString(value.parent) &&
+        (value.origin === undefined || typeof value.origin === "string")
       );
     case "ask_start":
       return (
@@ -221,6 +238,8 @@ function isEvent(value: unknown): value is LifecycleEvent {
         natural(value.attempt) &&
         isReason(value.reason)
       );
+    case "agent_model":
+      return strings(value.agent, value.model);
     case "agent_usage":
       return strings(value.agent) && isTokens(value.tokens) && number(value.cost);
     case "agent_exit":
@@ -285,8 +304,15 @@ function isTokens(value: unknown): value is TokenBreakdown {
   );
 }
 
+/** Every member of `RunOutcome`; `interrupted` marks a Run that died mid-flight. */
 function isOutcome(value: unknown): boolean {
-  return value === "completed" || value === "failed" || value === "stopped" || value === "paused";
+  return (
+    value === "completed" ||
+    value === "failed" ||
+    value === "stopped" ||
+    value === "paused" ||
+    value === "interrupted"
+  );
 }
 
 function optionalString(value: unknown): value is string | undefined {

package/src/view/run-foreground.ts

@@ -7,7 +7,7 @@
  * keeps its input loop while the tool call blocks.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { renderInlineRun, type TreeState } from "@yaag/tui";
+import { renderInlineRun, startLiveTicker, type TickerSchedule, type TreeState } from "@yaag/tui";
 import type { LiveRun, RunRegistry, RunSettlement } from "../record/index.ts";
 import { failure, observedSettlement, toError } from "../record/index.ts";
 import type { RunDetails } from "./run-details.ts";
@@ -64,6 +64,13 @@ export interface InlineOptions extends ForegroundOptions {
   readonly store: RunTreeStore;
   /** Registers the `yaag-run-complete` follow-up; called only on detach. */
   announce(): void;
+  /**
+   * The interval seam of the 1-second redraw (spec D11); defaults to a real
+   * `setInterval`. Tests inject a fake.
+   */
+  readonly schedule?: TickerSchedule;
+  /** The frame's clock; defaults to `Date.now`. Tests inject a fake. */
+  now?(): number;
 }
 
 /** Whether this call may draw the inline frame; tui mode only (architecture §9). */
@@ -102,7 +109,7 @@ export async function foregroundResult(options: ForegroundOptions): Promise<Fore
  */
 export async function foregroundInline(options: InlineOptions): Promise<ForegroundResult> {
   const { run, registry, signal, ctx } = options;
-  const frame = createFrame(ctx, run.id, options.state);
+  const frame = createFrame(ctx, run.id, options.state, options.now ?? Date.now);
   let detached = false;
   // Resolved by the detach itself, so the abort needs no second listener and
   // leaves nothing registered on a signal the tool call outlives.
@@ -122,6 +129,13 @@ export async function foregroundInline(options: InlineOptions): Promise<Foregrou
     if (id === run.id && !detached) frame.draw();
   });
   frame.draw();
+  // While the Run runs, the frame redraws each second, so its times advance
+  // between fd 3 frames (spec D11); the `finally` stops it on settle, on detach
+  // and on abort.
+  const ticker = startLiveTicker({
+    tick: frame.draw,
+    ...(options.schedule === undefined ? {} : { schedule: options.schedule }),
+  });
   try {
     if (signal?.aborted === true) detach();
     if (detached) return detachedResult(run);
@@ -141,6 +155,7 @@ export async function foregroundInline(options: InlineOptions): Promise<Foregrou
     }
     return finalResult(run.id, settlement);
   } finally {
+    ticker.stop();
     signal?.removeEventListener("abort", detach);
     unsubscribe();
     frame.clear();
@@ -153,7 +168,12 @@ interface InlineFrame {
   clear(): void;
 }
 
-function createFrame(ctx: ExtensionContext, id: string, state: TreeState): InlineFrame {
+function createFrame(
+  ctx: ExtensionContext,
+  id: string,
+  state: TreeState,
+  now: () => number,
+): InlineFrame {
   const key = foregroundWidgetKey(id);
   let cleared = false;
   let drawn: readonly string[] | undefined;
@@ -161,7 +181,7 @@ function createFrame(ctx: ExtensionContext, id: string, state: TreeState): Inlin
     draw(): void {
       if (cleared) return;
       const lines = renderInlineRun(state, {
-        now: Date.now(),
+        now: now(),
         width: WIDGET_WIDTH,
         label: id,
         maxLines: WIDGET_MAX_LINES,

package/src/view/run-result-block.ts

@@ -0,0 +1,117 @@
+/**
+ * The `yaag_run` result block: one status line when the transcript row is
+ * collapsed, and the status line over the whole Run tree when it is expanded.
+ *
+ * It delegates to `RunTreeComponent` rather than extending it: the tree owns the
+ * projection, this component owns what the row shows of it.
+ */
+import { clampToWidth, sanitizeTerminalText } from "@yaag/tui";
+import type { RunDetails } from "./run-details.ts";
+import { type RunBlockStatus, runBlockStatus, runStatusLine } from "./run-status-line.ts";
+import { RunTreeComponent } from "./run-tree-component.ts";
+
+/** The runtime's fallback program name; it names no program, so it is not shown. */
+const DEFAULT_PROGRAM = "program";
+
+/** Injection points for the block; all optional. */
+export interface RunBlockComponentOptions {
+  /** The clock the block reads for elapsed times; defaults to `Date.now`. */
+  readonly now?: () => number;
+}
+
+/** What pi's render context tells the block about this row. */
+export interface RunBlockView {
+  readonly expanded: boolean;
+  readonly isPartial: boolean;
+  readonly isError: boolean;
+  /** The result's own text: the tail of the Run's error output when it failed. */
+  readonly errorText?: string;
+}
+
+/** A pi component: the status line, and the Run tree behind the expand key. */
+export class RunBlockComponent {
+  readonly #now: () => number;
+  #tree: RunTreeComponent | undefined;
+  #details: RunDetails | undefined;
+  #view: RunBlockView = { expanded: false, isPartial: false, isError: false };
+
+  constructor(options: RunBlockComponentOptions = {}) {
+    this.#now = options.now ?? Date.now;
+  }
+
+  /**
+   * Folds one result or progress frame. A render with no details keeps the last
+   * ones, so a Run that fails after it streamed still shows its id and status.
+   */
+  update(details: RunDetails | undefined, view: RunBlockView): void {
+    this.#view = view;
+    if (details === undefined) return;
+    this.#details = details;
+    this.#tree = this.#tree ?? new RunTreeComponent(details, { now: this.#now });
+    this.#tree.update(details);
+  }
+
+  /**
+   * The declared name of the program that ran, for the call label.
+   *
+   * It is the name the executed program declared (`run_start.program`), never
+   * text scraped from the source. The label itself sanitizes and clamps it
+   * (`run-program-param.ts`), so this component states the fact only.
+   */
+  programName(): string | undefined {
+    const name = this.#details?.summary.program ?? "";
+    return name === "" || name === DEFAULT_PROGRAM ? undefined : name;
+  }
+
+  /**
+   * Collapsed, the block is exactly one status line, whatever the Run did: the
+   * error output of a failed Run belongs behind the expand key, where it cannot
+   * push the next tool call off the screen. A block that has no Run to describe
+   * — a call that failed before it started — shows the error text instead.
+   *
+   * Expanded, the error output follows the tree, and only for a failed Run: the
+   * tree already draws the Result region of a Run that ended well, so the same
+   * text under it would say everything twice.
+   */
+  render(width: number): string[] {
+    const details = this.#details;
+    if (details === undefined) return this.#errorLines(width);
+    const lines = [this.#statusLine(details)];
+    if (!this.#view.expanded) return lines;
+    if (this.#tree !== undefined) lines.push(...this.#tree.render(width));
+    return this.#view.isError ? [...lines, ...this.#errorLines(width)] : lines;
+  }
+
+  invalidate(): void {
+    this.#tree?.invalidate();
+  }
+
+  /**
+   * The result text, sanitized and clamped line by line: it carries the tail of
+   * the Run's own error output, which no Host Session may print unfiltered.
+   * `sanitizeTerminalText` keeps the newlines and strips every other control
+   * sequence, so each line only has to be clamped to the width.
+   */
+  #errorLines(width: number): string[] {
+    const text = this.#view.errorText;
+    if (text === undefined || text === "") return [];
+    return sanitizeTerminalText(text)
+      .replace(/\n+$/, "")
+      .split("\n")
+      .map((line) => clampToWidth(line, width));
+  }
+
+  #statusLine(details: RunDetails): string {
+    const status: RunBlockStatus = runBlockStatus({
+      summary: details.summary,
+      isPartial: this.#view.isPartial,
+      isError: this.#view.isError,
+    });
+    return runStatusLine({
+      ...(details.id === undefined ? {} : { id: details.id }),
+      summary: details.summary,
+      status,
+      now: this.#now(),
+    });
+  }
+}

package/src/view/run-status-line.ts

@@ -0,0 +1,76 @@
+/**
+ * The one status line the collapsed `yaag_run` block shows under its call line:
+ * `<run id> · <status> <elapsed>`. Pure, with the clock injected, so a test
+ * states an elapsed time instead of waiting for one.
+ */
+import type { RunSummary } from "@yaag/runtime";
+import { clampToWidth, durationText, sanitizeTerminalLine } from "@yaag/tui";
+
+/** What the block says a Run is doing, in the transcript's own vocabulary. */
+export type RunBlockStatus = "running" | "started" | "finished" | "failed" | "interrupted";
+
+/** The widest a Run id may be on the status line, in display columns. */
+const ID_WIDTH = 24;
+
+/** What the status classification reads: the Summary and the render's own flags. */
+export interface RunBlockStatusOptions {
+  readonly summary: RunSummary;
+  /** True while pi still streams this result; a live foreground Run. */
+  readonly isPartial: boolean;
+  /** True when the tool call itself threw. */
+  readonly isError: boolean;
+}
+
+/**
+ * Classifies one Run for the status line.
+ *
+ * A Run that still runs is `running` while pi streams the result, and `started`
+ * once the call returned — that is the background acknowledgement. A settled
+ * Run reads its outcome: `stopped`, `paused` and `interrupted` all say
+ * `interrupted`, because each one names a Run that ended before its program did.
+ */
+export function runBlockStatus(options: RunBlockStatusOptions): RunBlockStatus {
+  const { summary } = options;
+  if (summary.runState === "running") {
+    if (options.isError) return "failed";
+    return options.isPartial ? "running" : "started";
+  }
+  if (options.isError || summary.outcome === "failed") return "failed";
+  return summary.outcome === "completed" ? "finished" : "interrupted";
+}
+
+/** What one status line needs: the id, the Run, its status, and the clock. */
+export interface RunStatusLineOptions {
+  readonly id?: string;
+  readonly summary: RunSummary;
+  readonly status: RunBlockStatus;
+  /** The current time, in epoch milliseconds. */
+  readonly now: number;
+}
+
+/**
+ * `<id> · <status> <elapsed>`; the id and its separator are dropped when the
+ * block knows no Run id, because a bare separator names nothing.
+ *
+ * The id is read back from a persisted transcript, so it is sanitized to one
+ * line and clamped before it is printed: no stored value may forge a second
+ * line or overflow the status line.
+ */
+export function runStatusLine(options: RunStatusLineOptions): string {
+  const body = `${options.status} ${durationText(elapsedMs(options))}`;
+  if (options.id === undefined) return body;
+  const id = clampToWidth(sanitizeTerminalLine(options.id), ID_WIDTH);
+  return id === "" ? body : `${id} · ${body}`;
+}
+
+/**
+ * A settled Run reports the duration its own Summary measured. A live Run has
+ * no duration yet, so the line counts from its start; a background Run
+ * therefore reports how long it has run, on each redraw of its row.
+ */
+function elapsedMs(options: RunStatusLineOptions): number {
+  const { summary } = options;
+  if (summary.runState === "ended") return summary.durationMs;
+  if (summary.startedAt === null) return summary.durationMs;
+  return options.now - summary.startedAt;
+}

package/src/view/theme-styler.ts

@@ -0,0 +1,34 @@
+/**
+ * Maps the tui styling tokens onto pi's `Theme` (spec D10).
+ *
+ * pi's `fg` resets the foreground only (`\x1b[39m`) and `bg` resets the
+ * background only (`\x1b[49m`), so a background wrapped around already
+ * foregrounded spans survives to the end of the line. That is how pi paints
+ * its own selected line (`modes/interactive/components/session-selector`).
+ */
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { BackgroundToken, StyleToken, TreeStyler } from "@yaag/tui";
+
+/** The four state colours are distinct, and none of them is `accent`. */
+const FOREGROUND: Readonly<Record<StyleToken, ThemeColor>> = Object.freeze({
+  accent: "accent",
+  running: "warning",
+  exited: "success",
+  failed: "error",
+  idle: "dim",
+  muted: "muted",
+});
+
+// `ThemeBg` is not exported from pi's package root, so the table borrows the
+// parameter type of `Theme["bg"]` instead of casting.
+const BACKGROUND: Readonly<Record<BackgroundToken, Parameters<Theme["bg"]>[0]>> = Object.freeze({
+  selected: "selectedBg",
+});
+
+/** Builds the styler the `/yaag` view passes into the tree renderer. */
+export function themeStyler(theme: Theme): TreeStyler {
+  return {
+    fg: (token: StyleToken, text: string): string => theme.fg(FOREGROUND[token], text),
+    bg: (token: BackgroundToken, line: string): string => theme.bg(BACKGROUND[token], line),
+  };
+}

package/src/view/yaag-command.ts

@@ -13,13 +13,21 @@ import type {
   ExtensionUIContext,
   RegisteredCommand,
 } from "@earendil-works/pi-coding-agent";
-import { createRunTreeView, type RunTreeViewHost, type RunViewResult, TreeState } from "@yaag/tui";
+import {
+  createRunTreeView,
+  type RunTreeView,
+  type RunTreeViewHost,
+  type RunViewResult,
+  type TickerSchedule,
+  TreeState,
+} from "@yaag/tui";
 import type { RunRegistry, RunSettlement } from "../record/index.ts";
 import { observedSettlement, viewResult } from "../record/index.ts";
 import { restoredViewResult } from "./restored-run-text.ts";
 import { type PickableRun, pickableRuns, runFromLabel, runPickerLabel } from "./run-picker.ts";
 import { createRunTreeHost } from "./run-tree-host.ts";
 import type { RunTreeStore } from "./run-trees.ts";
+import { themeStyler } from "./theme-styler.ts";
 
 type CommandOptions = Omit<RegisteredCommand, "name" | "sourceInfo">;
 
@@ -29,6 +37,11 @@ const DESCRIPTION = "Open the interactive Run tree for a Run of this session";
 export interface YaagCommandOptions {
   readonly registry: RunRegistry;
   readonly store: RunTreeStore;
+  /**
+   * The interval seam of the view's 1-second redraw (spec D11); defaults to a
+   * real `setInterval`. Tests inject a fake.
+   */
+  readonly schedule?: TickerSchedule;
 }
 
 /** Everything `/yaag` needs from its pi context, and nothing more. */
@@ -96,12 +109,15 @@ async function openRun(
       ? TreeState.fromSummary(run.summary)
       : (options.store.get(run.id) ?? TreeState.fromSummary(run.summary));
   let unsubscribe: (() => void) | undefined;
+  // Held outside the factory, so the close path stops the view's ticker even
+  // when `ui.custom` rejects rather than closing the view itself.
+  let view: RunTreeView | undefined;
   // The observer below outlives no more than the `ctx.ui.custom()` call: once
   // the view exits or the UI call rejects, a later settlement must touch
   // neither the view nor the renderer.
   let live = true;
   try {
-    await ctx.ui.custom<void>((tui, _theme, keybindings, done) => {
+    await ctx.ui.custom<void>((tui, theme, keybindings, done) => {
       const host: RunTreeViewHost = {
         ...createRunTreeHost({ ui: ctx.ui, tui, keybindings, state }),
         // A restored orphan is never re-attached, so there is nothing to stop
@@ -113,23 +129,26 @@ async function openRun(
         // hand over, because a Run of this session is already addressable.
         done: () => done(),
       };
-      const view = createRunTreeView({
+      const opened = createRunTreeView({
         state,
         host,
         label: found.state === "restored" ? `${run.id} (restored)` : run.id,
+        styler: themeStyler(theme),
+        ...(options.schedule === undefined ? {} : { schedule: options.schedule }),
       });
-      if (found.state === "restored") view.settle(restoredViewResult(found.run.record));
+      view = opened;
+      if (found.state === "restored") opened.settle(restoredViewResult(found.run.record));
       else if (found.state === "finished")
-        settle(state, view, found.run.outcome, options.registry, run.id);
+        settle(state, opened, found.run.outcome, options.registry, run.id);
       else if (found.state === "live") {
         unsubscribe = options.store.subscribe((id) => {
-          if (id === run.id && live) view.touch();
+          if (id === run.id && live) opened.touch();
         });
         // A view opened while live must reach the settled phase itself, or `esc`
         // would keep live behavior after the Run ended (ADR-0008).
         const onSettled = (settlement: RunSettlement): void => {
           if (!live) return;
-          settle(state, view, settlement, options.registry, run.id);
+          settle(state, opened, settlement, options.registry, run.id);
         };
         void observedSettlement(run.id, found.run.outcome, options.registry)
           .then(onSettled, (reason: unknown) => {
@@ -138,11 +157,13 @@ async function openRun(
           // A throwing view or renderer must not become an unhandled rejection.
           .catch(() => {});
       }
-      return view;
+      return opened;
     });
   } finally {
     live = false;
     unsubscribe?.();
+    // `dispose` is idempotent, so the call pi already made costs nothing here.
+    view?.dispose();
   }
 }