@yaag/extension 0.2.0 → 0.3.0

package/README.md

@@ -35,12 +35,17 @@ For a throwaway session instead: `pi -e ./packages/extension`.
 
 | Parameter | Type | Meaning |
 |---|---|---|
-| `file` | `string` | Path to the Orchestration Program file |
+| `file` | `string?` | Path to the Orchestration Program file |
+| `script` | `string?` | Orchestration Program source text (Inline Program) |
 | `args` | `string?` | The program's arguments, as a JSON object string |
 | `background` | `boolean?` | Start the Run in the background and return its Run id |
 | `record` | `string?` | Write this Run's Cassette artifact to this path |
 | `resume` | `string?` | Replay a matching Cassette prefix, then continue live |
 
+Give `file` or `script`, and not both; a violation is a parameter error raised
+before any process starts. A `script` program can import `@yaag/runtime` and
+`typebox` only (ADR-0033).
+
 Blocking by default: the call returns when the Run ends, and its content is the
 Run's return value. With `background: true` it returns at once with a short Run
 id (`r1`, `r2`, …) and the result arrives later as a follow-up message that

package/package.json

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

package/src/background-status.ts

@@ -0,0 +1,94 @@
+/**
+ * The footer segment for every live background Run (architecture §9).
+ *
+ * A background Run costs no scrollback and owns no widget: it reports itself in
+ * one cooperative footer segment, `yaag: 2 live · $0.42`, which pi lays out
+ * beside the segments of every other extension. The segment is cleared as soon
+ * as the last background Run ends.
+ */
+import { costText } from "@yaag/tui";
+import type { RunRegistry } from "./run-registry.ts";
+import type { RunTreeStore } from "./run-trees.ts";
+
+/** The one footer key this extension owns. */
+export const STATUS_KEY = "yaag";
+
+/** The only pi capability the footer segment needs. */
+export interface StatusSurface {
+  setStatus(key: string, text: string | undefined): void;
+}
+
+/** What the footer segment reads: the Run registry and the projection store. */
+export interface BackgroundStatusOptions {
+  readonly registry: RunRegistry;
+  readonly store: RunTreeStore;
+}
+
+/** The footer controller: bind it once, then refresh it on every occurrence. */
+export interface BackgroundStatus {
+  /**
+   * Binds the pi UI surface, once the Host Session has one, and writes the
+   * current text. A `StatusSurface.setStatus()` that throws propagates here.
+   */
+  bind(surface: StatusSurface): void;
+  /**
+   * Rewrites the segment; drops the write before `bind`, and skips unchanged
+   * text. A bound `StatusSurface.setStatus()` that throws propagates here.
+   */
+  refresh(): void;
+}
+
+/**
+ * Builds the footer segment over this session's Run registry and projections.
+ *
+ * An unbound controller drops every refresh, and a Run without a projection is
+ * skipped. The controller lives for the whole Host Session, so it never
+ * unsubscribes. Construction itself never throws, but `bind()` and `refresh()`
+ * call the caller's `StatusSurface.setStatus()` and propagate whatever it
+ * throws; the store subscription also propagates it into the `ingest()` that
+ * caused the rewrite.
+ */
+export function createBackgroundStatus(options: BackgroundStatusOptions): BackgroundStatus {
+  let surface: StatusSurface | undefined;
+  let written: string | undefined;
+
+  const refresh = (): void => {
+    if (surface === undefined) return;
+    const text = statusText(options);
+    if (written === text) return;
+    written = text;
+    surface.setStatus(STATUS_KEY, text);
+  };
+
+  options.store.subscribe(() => refresh());
+
+  return {
+    bind(bound: StatusSurface): void {
+      surface = bound;
+      written = undefined;
+      refresh();
+    },
+    refresh,
+  };
+}
+
+/**
+ * The segment text, or undefined when no background Run is live.
+ *
+ * The cost is the sum over every live background Run, and it carries
+ * `+incomplete` when any of those Runs reports its cost as a floor (ADR-0012).
+ */
+function statusText(options: BackgroundStatusOptions): string | undefined {
+  let count = 0;
+  let cost: number | null = null;
+  let incomplete = false;
+  for (const run of options.registry.live) {
+    if (options.store.kind(run.id) !== "background") continue;
+    count += 1;
+    const summary = run.summary;
+    if (summary.cost !== null) cost = (cost ?? 0) + summary.cost;
+    if (summary.incomplete) incomplete = true;
+  }
+  if (count === 0) return undefined;
+  return `${STATUS_KEY}: ${count} live · ${costText(cost, incomplete)}`;
+}

package/src/fake-extension-ui.ts

@@ -1,7 +1,8 @@
 /**
  * A fully typed `ExtensionUIContext` for the tui-mode test context.
  *
- * `custom`, `notify`, `editor`, `setWidget`, and a scripted `select` work;
+ * `custom`, `notify`, `editor`, `setWidget`, `setStatus`, and a scripted
+ * `select` work;
  * every other capability throws, so a dependency a view is not supposed to
  * have fails loudly. The
  * class implements the interface, so pi's UI surface is checked at compile
@@ -54,6 +55,8 @@ export class FakeExtensionUi implements ExtensionUIContext {
   readonly edits: OpenedEditor[] = [];
   /** The latest frame per widget key; `undefined` means the key was cleared. */
   readonly widgets = new Map<string, string[] | undefined>();
+  /** The latest text per footer key; `undefined` means the key was cleared. */
+  readonly statuses = new Map<string, string | undefined>();
   /** Answers `select` in order; an empty queue answers `undefined`, i.e. esc. */
   readonly selections: string[] = [];
   /** The component `custom` opened, once a Run opened one. */
@@ -116,8 +119,8 @@ export class FakeExtensionUi implements ExtensionUIContext {
   onTerminalInput(): () => void {
     return unavailable("ui.onTerminalInput");
   }
-  setStatus(): void {
-    unavailable("ui.setStatus");
+  setStatus(key: string, text: string | undefined): void {
+    this.statuses.set(key, text);
   }
   setWorkingMessage(): void {
     unavailable("ui.setWorkingMessage");

package/src/fake-tui.ts

@@ -1,7 +1,7 @@
 /**
  * Fully typed `TUI` and `Terminal` doubles for the tui-mode test context.
  *
- * The foreground Run view uses three capabilities only: `terminal.rows`,
+ * The Run view uses three capabilities only: `terminal.rows`,
  * `terminal.columns`, and `requestRender()`. Every other member of `Terminal`
  * and `TUI` — fields and getters included — throws on access, so a component
  * that starts to depend on the terminal fails loudly in the test instead of

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createBackgroundWidget } from "./background-widget.ts";
+import { createBackgroundStatus } from "./background-status.ts";
 import { createDescribeTool } from "./describe-tool.ts";
 import { findProgramDirectories } from "./program-directories.ts";
 import { resolveBun } from "./resolve-bun.ts";
@@ -36,12 +36,12 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   // Host Session keeps every Run id addressable (ticket 02).
   const registry = new RunRegistry({ store: new RunStore() });
   await registry.restore();
-  // The renderer projections and the one combined inline widget both live for
+  // The renderer projections and the background footer segment both live for
   // the session, beside the registry, so a background Run keeps a tree.
   const store = new RunTreeStore();
-  const widget = createBackgroundWidget({ registry, store });
+  const status = createBackgroundStatus({ registry, store });
   pi.registerTool(
-    createRunTool({ bun, cli, registry, store, widget, sendMessage: pi.sendMessage.bind(pi) }),
+    createRunTool({ bun, cli, registry, store, status, sendMessage: pi.sendMessage.bind(pi) }),
   );
   pi.registerTool(createStatusTool(registry));
   pi.registerMessageRenderer("yaag-run-complete", createRunCompleteRenderer());
@@ -58,7 +58,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 
   pi.on("session_start", (_event, ctx) => {
     if (bun === null) ctx.ui.notify(report, "error");
-    if (ctx.hasUI) widget.bind(ctx.ui);
+    if (ctx.hasUI) status.bind(ctx.ui);
   });
 
   // Commands and tools have separate namespaces: this CLI-resolution command

package/src/run-argv.ts

@@ -0,0 +1,34 @@
+/** What a Run runs: a program file, or Inline Program source text (ADR-0033). */
+export type ProgramTarget =
+  | { readonly kind: "file"; readonly file: string }
+  | { readonly kind: "inline"; readonly source: string };
+
+/** The parts of a Run the CLI argv carries. */
+export interface RunArgvOptions {
+  readonly program: ProgramTarget;
+  /** Opaque JSON, forwarded untouched: the program validates it (ADR-0010). */
+  readonly args?: string;
+  /** Cassette path to write, forwarded as `--record` (ADR-0013). */
+  readonly record?: string;
+  /** Cassette path to resume from, forwarded as `--resume` (ADR-0014). */
+  readonly resume?: string;
+  /** The descriptor Run Lifecycle Events travel on; 3 by default (ADR-0016). */
+  readonly eventsFd?: number;
+}
+
+/**
+ * Builds the CLI argv for one Run.
+ *
+ * An Inline Program travels as one `--eval` argument holding the source text
+ * verbatim (ADR-0033); this function never quotes, escapes or validates it —
+ * the CLI owns the closed import contract.
+ */
+export function runArgv(options: RunArgvOptions): readonly string[] {
+  const { program } = options;
+  const argv = program.kind === "file" ? ["run", program.file] : ["run", "--eval", program.source];
+  argv.push("--events-fd", String(options.eventsFd ?? 3));
+  if (options.args !== undefined) argv.push("--args", options.args);
+  if (options.record !== undefined) argv.push("--record", options.record);
+  if (options.resume !== undefined) argv.push("--resume", options.resume);
+  return argv;
+}

package/src/run-foreground.ts

@@ -1,19 +1,36 @@
 /**
- * The two blocking `yaag_run` paths (spec §4): the details-only stream every
- * client gets, and the interactive tree a tui-mode Host Session gets.
+ * The two blocking `yaag_run` paths (architecture §9): the details-only stream every
+ * client gets, and the inline frame a tui-mode Host Session also draws.
  *
- * Both return the same model-visible contract, so opening the interactive view
- * changes nothing the model can see.
+ * Both return the same model-visible contract, so drawing the frame changes
+ * nothing the model can see, and neither path opens a modal: the Host Session
+ * keeps its input loop while the tool call blocks.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { TreeState } from "@yaag/tui";
+import { renderInlineRun, type TreeState } from "@yaag/tui";
 import type { RunDetails } from "./run-details.ts";
-import { openRunTreeView } from "./run-foreground-view.ts";
 import type { LiveRun, RunRegistry, RunSettlement } from "./run-registry.ts";
-import { failure, observedSettlement, toError, viewResult } from "./run-settlement.ts";
+import { failure, observedSettlement, toError } from "./run-settlement.ts";
 import type { RunTreeStore } from "./run-trees.ts";
 import { toUsage } from "./usage.ts";
 
+/**
+ * The pi widget key one blocking Run draws under.
+ *
+ * The key carries the Run id, because pi executes sibling tool calls
+ * concurrently: two blocking Runs keep two frames, and each one clears only
+ * its own.
+ */
+export function foregroundWidgetKey(id: string): string {
+  return `yaag-run:${id}`;
+}
+
+/** Line budget for the inline frame; pi truncates a widget past 10 lines. */
+const WIDGET_MAX_LINES = 10;
+
+/** Width the inline frame is clamped to; pi wraps nothing for a widget. */
+const WIDGET_WIDTH = 100;
+
 /** What `execute` returns for a blocking Run. */
 export interface ForegroundResult {
   content: { type: "text"; text: string }[];
@@ -34,25 +51,23 @@ export interface ForegroundOptions {
 }
 
 /**
- * `ForegroundOptions` plus what opening the interactive tree needs.
+ * `ForegroundOptions` plus what drawing the inline frame needs.
  *
- * Only valid when `interactiveAvailable()` is true; `ctx.ui` is touched on no
- * other path.
+ * Only valid when `inlineAvailable()` is true; `ctx.ui` is touched on no other
+ * path.
  */
-export interface InteractiveOptions extends ForegroundOptions {
+export interface InlineOptions extends ForegroundOptions {
   readonly ctx: ExtensionContext;
-  /** Ingested from Run start, so the tree misses no early Ask. */
+  /** Ingested from Run start by the caller, so the frame misses no early Ask. */
   readonly state: TreeState;
-  /** Detaching hands the Run to the combined inline widget. */
+  /** Detaching hands the Run to the footer segment. */
   readonly store: RunTreeStore;
   /** Registers the `yaag-run-complete` follow-up; called only on detach. */
   announce(): void;
-  /** Receives the redraw handle, so a pushed fd 3 update can reach the view. */
-  onOpen?(view: { touch(): void }): void;
 }
 
-/** Whether this call may open the interactive tree (spec §4: tui mode only). */
-export function interactiveAvailable(ctx: ExtensionContext, background: boolean): boolean {
+/** Whether this call may draw the inline frame; tui mode only (architecture §9). */
+export function inlineAvailable(ctx: ExtensionContext, background: boolean): boolean {
   return !background && ctx.mode === "tui" && ctx.hasUI;
 }
 
@@ -77,63 +92,95 @@ export async function foregroundResult(options: ForegroundOptions): Promise<Fore
 }
 
 /**
- * The interactive path: the reader watches the tree while the Run executes, then
- * dismisses it or detaches the Run.
+ * The inline path: a read-only frame of the Run tree is drawn beside the chat
+ * while the tool call blocks, and the frame is cleared when the call returns.
  *
- * Dismissal returns exactly what `foregroundResult` returns, throw included.
- * Detach returns an acknowledgement and leaves the Run executing as `rN`, with
- * its completion delivered by the `yaag-run-complete` follow-up. Every path
- * closes the view, so `ctx.ui.custom()` cannot outlive the tool call.
+ * `esc` aborts the tool call, and an abort detaches rather than stops: the Run
+ * becomes a background Run, joins the footer segment, and its completion
+ * arrives through the `yaag-run-complete` follow-up. Stopping a Run is `/yaag`
+ * → `ctrl+q` → Stop Run (ADR-0008).
  */
-export async function foregroundInteractive(
-  options: InteractiveOptions,
-): Promise<ForegroundResult> {
+export async function foregroundInline(options: InlineOptions): Promise<ForegroundResult> {
   const { run, registry, signal, ctx } = options;
-  const view = openRunTreeView({
-    ctx,
-    state: options.state,
-    id: run.id,
-    stop: run.stop,
-    onDetach: () => options.store.adopt(run.id),
+  const frame = createFrame(ctx, run.id, options.state);
+  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.
+  let onDetached: () => void = () => {};
+  const detaching = new Promise<undefined>((resolve) => {
+    onDetached = () => resolve(undefined);
   });
-  options.onOpen?.(view);
-  const abort = (): void => {
-    run.stop();
-    view.close("dismissed");
+  const detach = (): void => {
+    if (detached) return;
+    detached = true;
+    options.store.adopt(run.id);
+    options.announce();
+    onDetached();
   };
-  signal?.addEventListener("abort", abort, { once: true });
-  if (signal?.aborted === true) abort();
+  signal?.addEventListener("abort", detach, { once: true });
+  const unsubscribe = options.store.subscribe((id) => {
+    if (id === run.id && !detached) frame.draw();
+  });
+  frame.draw();
   try {
-    // Kept as a settled-shaped promise so a detach — which leaves this promise
-    // pending — cannot surface as an unhandled rejection.
+    if (signal?.aborted === true) detach();
+    if (detached) return detachedResult(run);
     const settled = observedSettlement(run.id, run.outcome, registry).then(
-      (settlement): SettledRace => ({ kind: "settled", settlement }),
-      (reason): SettledRace => ({ kind: "settled", settlement: { kind: "rejected", reason } }),
+      (settlement): RunSettlement => settlement,
+      (reason): RunSettlement => ({ kind: "rejected", reason }),
     );
-    const first = await Promise.race([
-      settled,
-      view.exit.then((exit) => ({ kind: "exit", exit }) as const),
-    ]);
-    if (first.kind === "exit" && first.exit === "detached") {
-      options.announce();
+    // The detach resolves this race, so the tool call returns while the Run
+    // keeps executing; `settled` stays a handled promise either way.
+    const settlement = await Promise.race([settled, detaching]);
+    // `detached` is checked beside the settlement: an abort that lands in the
+    // same synchronous stretch as the settlement already announced the Run, and
+    // returning its value here would report the same Run to the model twice.
+    if (settlement === undefined || detached) {
+      detach();
       return detachedResult(run);
     }
-    if (first.kind === "settled") view.settle(viewResult(first.settlement));
-    const exit = await view.exit;
-    if (exit === "detached") {
-      options.announce();
-      return detachedResult(run);
-    }
-    if (signal?.aborted === true) throw new Error("yaag_run: cancelled");
-    return finalResult(run.id, await settled.then(({ settlement }) => settlement));
+    return finalResult(run.id, settlement);
   } finally {
-    signal?.removeEventListener("abort", abort);
-    view.close("dismissed");
-    view.dispose();
+    signal?.removeEventListener("abort", detach);
+    unsubscribe();
+    frame.clear();
   }
 }
 
-type SettledRace = { readonly kind: "settled"; readonly settlement: RunSettlement };
+/** One inline frame: a redraw and a clear, both idempotent after the clear. */
+interface InlineFrame {
+  draw(): void;
+  clear(): void;
+}
+
+function createFrame(ctx: ExtensionContext, id: string, state: TreeState): InlineFrame {
+  const key = foregroundWidgetKey(id);
+  let cleared = false;
+  let drawn: readonly string[] | undefined;
+  return {
+    draw(): void {
+      if (cleared) return;
+      const lines = renderInlineRun(state, {
+        now: Date.now(),
+        width: WIDGET_WIDTH,
+        label: id,
+        maxLines: WIDGET_MAX_LINES,
+      });
+      if (drawn !== undefined && sameLines(drawn, lines)) return;
+      drawn = lines;
+      ctx.ui.setWidget(key, [...lines]);
+    },
+    clear(): void {
+      if (cleared) return;
+      cleared = true;
+      ctx.ui.setWidget(key, undefined);
+    },
+  };
+}
+
+function sameLines(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((line, index) => line === right[index]);
+}
 
 function finalResult(id: string, settlement: RunSettlement): ForegroundResult {
   if (settlement.kind === "rejected") throw toError(settlement.reason);

package/src/run-program-param.ts

@@ -0,0 +1,64 @@
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { sanitizeTerminalLine } from "@yaag/tui";
+import type { ProgramTarget } from "./run-argv.ts";
+
+/** The `yaag_run` parameters that name the program; exactly one is given. */
+export interface ProgramParams {
+  readonly file?: string;
+  readonly script?: string;
+}
+
+const LABEL_LIMIT = 60;
+
+/**
+ * Resolves the program the caller named to a {@link ProgramTarget}.
+ *
+ * `file` and `script` are exactly-one-of (ADR-0033): a violation throws a
+ * parameter error, so the refusal happens before any process starts. A `script`
+ * touches no filesystem; the CLI writes and owns its temp module.
+ */
+export async function resolveProgramTarget(params: ProgramParams): Promise<ProgramTarget> {
+  const { file, script } = params;
+  if (file !== undefined && script !== undefined) {
+    throw new Error("yaag_run: give file or script, and not both");
+  }
+  if (script !== undefined) {
+    if (script.trim() === "") throw new Error("yaag_run: script is empty");
+    return { kind: "inline", source: script };
+  }
+  if (file === undefined) throw new Error("yaag_run: give file or script");
+  const resolved = resolve(file);
+  try {
+    await access(resolved);
+  } catch {
+    throw new Error(`yaag_run: no such Orchestration Program: ${resolved}`);
+  }
+  return { kind: "file", file: resolved };
+}
+
+/**
+ * A one-line label for the call render. Total by design: the render runs before
+ * `execute` validates, so an invalid parameter pair must still produce a label.
+ *
+ * An Inline Program shows its declared name, else its first line — never a temp
+ * path, which exists only inside the CLI.
+ */
+export function programLabel(params: ProgramParams): string {
+  const { file, script } = params;
+  if (file !== undefined && script !== undefined) return "(invalid call)";
+  if (script !== undefined) return truncate(inlineLabel(script));
+  if (file !== undefined) return file;
+  return "(invalid call)";
+}
+
+function inlineLabel(source: string): string {
+  const declared = /name:\s*["'`]([^"'`]+)/.exec(source);
+  const line = declared?.[1] ?? source.split("\n").find((one) => one.trim() !== "") ?? "";
+  return sanitizeTerminalLine(line).replace(/\s+/g, " ").trim();
+}
+
+function truncate(label: string): string {
+  if (label === "") return "(empty script)";
+  return label.length <= LABEL_LIMIT ? label : `${label.slice(0, LABEL_LIMIT)}…`;
+}

package/src/run-record.ts

@@ -18,7 +18,14 @@ export type PersistedOutcome =
 
 /** What starting a Run said about it; enough to describe it in a later session. */
 export interface RunLaunch {
-  readonly file: string;
+  /**
+   * Exactly one of `file` and `script` is present: `file` for a program file,
+   * `script` for an Inline Program (ADR-0033). The pair stays a tolerant
+   * optional pair rather than a union, because a record written by an older
+   * yaag must still narrow.
+   */
+  readonly file?: string;
+  readonly script?: string;
   readonly args?: string;
   readonly record?: string;
   readonly resume?: string;
@@ -82,7 +89,10 @@ function isState(value: unknown): value is PersistedRunState {
 
 function isLaunch(value: unknown): value is RunLaunch {
   return (
-    typeof value === "object" && value !== null && "file" in value && typeof value.file === "string"
+    typeof value === "object" &&
+    value !== null &&
+    (("file" in value && typeof value.file === "string") ||
+      ("script" in value && typeof value.script === "string"))
   );
 }
 

package/src/run-settlement.ts

@@ -26,7 +26,7 @@ export async function observedSettlement(
 }
 
 /**
- * The Result region's content for a settled Run, shared by the foreground view
+ * The Result region's content for a settled Run, shared by the `/yaag` view
  * and `/yaag`'s settled background view.
  */
 export function viewResult(settlement: RunSettlement): RunViewResult {

package/src/run-tool-test-support.ts

@@ -1,13 +1,16 @@
 import { dirname, join } from "node:path";
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { BackgroundWidget } from "./background-widget.ts";
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+import { initialSummary } from "@yaag/runtime";
+import type { BackgroundStatus } from "./background-status.ts";
+import { fakeTheme } from "./fake-theme.ts";
 import { resolveBun } from "./resolve-bun.ts";
 import { resolveCliEntry } from "./resolve-cli.ts";
 import type { RunDetails } from "./run-details.ts";
 import { RunRegistry } from "./run-registry.ts";
 import { createRunTool, type SendMessage } from "./run-tool.ts";
 import type { RunTreeStore } from "./run-trees.ts";
-import type { RunHandle } from "./spawn-run.ts";
+import type { RunHandle, StartRunOptions } from "./spawn-run.ts";
 import { createStopTool, type StopDetails } from "./stop-tool.ts";
 import { TestExtensionContext } from "./test-extension-context.ts";
 
@@ -19,9 +22,60 @@ const ctx = new TestExtensionContext(dirname(cli));
 export const fixture = (name: string): string => join(dirname(cli), "fixtures", `${name}.ts`);
 
 export interface RunParams {
-  readonly file: string;
+  readonly file?: string;
+  readonly script?: string;
   readonly args?: string;
   readonly background?: boolean;
+  readonly record?: string;
+  readonly resume?: string;
+}
+
+/** Renders the tool's call line, stripped of styling, as the transcript shows it. */
+export function renderCallLabel(params: RunParams): string {
+  const tool = createRunTool({
+    bun,
+    cli,
+    registry: new RunRegistry(),
+    sendMessage: () => undefined,
+  });
+  const component = tool.renderCall?.(params, fakeTheme(), {
+    args: params,
+    toolCallId: "call-1",
+    invalidate: () => {},
+    lastComponent: undefined,
+    state: undefined,
+    cwd: process.cwd(),
+    executionStarted: false,
+    argsComplete: true,
+    isPartial: false,
+    expanded: false,
+    showImages: false,
+    isError: false,
+  });
+  return stripTerminalSequences(component?.render(80)[0] ?? "");
+}
+
+/** A start seam that never spawns: it captures its options and ends the Run at once. */
+export function fakeStart(stdout = "{}"): {
+  readonly start: (options: StartRunOptions) => RunHandle;
+  readonly seen: StartRunOptions[];
+} {
+  const seen: StartRunOptions[] = [];
+  return {
+    seen,
+    start: (options) => {
+      seen.push(options);
+      return {
+        stop: () => {},
+        outcome: Promise.resolve({
+          code: 0,
+          stdout,
+          stderr: "",
+          summary: initialSummary(),
+        }),
+      };
+    },
+  };
 }
 
 export interface Sent {
@@ -40,10 +94,10 @@ export async function run(
     readonly registry?: RunRegistry;
     readonly sent?: Sent[];
     readonly start?: (options: import("./spawn-run.ts").StartRunOptions) => RunHandle;
-    /** A tui-mode context, for the interactive foreground path. */
+    /** A tui-mode context, for the inline foreground path. */
     readonly ctx?: ExtensionContext;
     readonly store?: RunTreeStore;
-    readonly widget?: BackgroundWidget;
+    readonly status?: BackgroundStatus;
   } = {},
 ): Promise<{
   readonly text: string;
@@ -56,7 +110,7 @@ export async function run(
     registry: opts.registry ?? new RunRegistry(),
     ...(opts.start === undefined ? {} : { start: opts.start }),
     ...(opts.store === undefined ? {} : { store: opts.store }),
-    ...(opts.widget === undefined ? {} : { widget: opts.widget }),
+    ...(opts.status === undefined ? {} : { status: opts.status }),
     sendMessage: (message, options) =>
       void opts.sent?.push({
         content: message.content,

package/src/run-tool.ts

@@ -1,26 +1,37 @@
-import { access } from "node:fs/promises";
 import { resolve } from "node:path";
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { initialSummary } from "@yaag/runtime";
 import { Type } from "typebox";
-import { type BackgroundWidget, createBackgroundWidget } from "./background-widget.ts";
+import { type BackgroundStatus, createBackgroundStatus } from "./background-status.ts";
 import type { RunDetails } from "./run-details.ts";
-import { foregroundInteractive, foregroundResult, interactiveAvailable } from "./run-foreground.ts";
+import { foregroundInline, foregroundResult, inlineAvailable } from "./run-foreground.ts";
 import { RunTreeComponent } from "./run-tree-component.ts";
 import { RunTreeStore } from "./run-trees.ts";
 
 export type { RunDetails } from "./run-details.ts";
 
 import { type ProcessIdentity, readProcessStart } from "./process-liveness.ts";
+import type { ProgramTarget } from "./run-argv.ts";
 import { mintRunId } from "./run-id.ts";
+import { programLabel, resolveProgramTarget } from "./run-program-param.ts";
 import type { LiveRun, RunRegistry, RunSettlement } from "./run-registry.ts";
 import { errorText, failure, observedSettlement } from "./run-settlement.ts";
 import { type RunHandle, type RunOutcome, type StartRunOptions, startRun } from "./spawn-run.ts";
 import { statusReport } from "./status.ts";
 
 const parameters = Type.Object({
-  file: Type.String({ description: "Path to the Orchestration Program file" }),
+  file: Type.Optional(
+    Type.String({
+      description: "Path to the Orchestration Program file; use script instead for inline source",
+    }),
+  ),
+  script: Type.Optional(
+    Type.String({
+      description:
+        'The Orchestration Program source text; it can import "@yaag/runtime" and "typebox" only',
+    }),
+  ),
   args: Type.Optional(
     Type.String({ description: "The program's arguments, as a JSON object string" }),
   ),
@@ -50,8 +61,8 @@ export interface RunToolOptions {
   readonly start?: (options: StartRunOptions) => RunHandle;
   /** Per-session renderer projections; defaulted so a test may omit it. */
   readonly store?: RunTreeStore;
-  /** The combined inline widget; defaulted so a test may omit it. */
-  readonly widget?: BackgroundWidget;
+  /** The background footer segment; defaulted so a test may omit it. */
+  readonly status?: BackgroundStatus;
 }
 
 const DESCRIPTION = [
@@ -72,6 +83,17 @@ const DESCRIPTION = [
   "later message. Every Run gets an id and can be inspected with `yaag_status`;",
   "background Runs may overlap and each is stopped with `yaag_stop({ id })`.",
   "",
+  "`script` runs a program that you give as source text. It needs no file.",
+  "Give `file` or `script`. Do not give both. A call with both, or with neither,",
+  "fails before yaag starts the Run.",
+  "A `script` program has the same shape as a file program. It default-exports",
+  "`defineRun(...)`.",
+  'A `script` program can import "@yaag/runtime" and "typebox" only. Make a file',
+  "program if the program needs other modules.",
+  "`args`, `background`, `record` and `resume` work the same way for `script`.",
+  "Give the same script when you resume a recorded `script` Run.",
+  "`yaag_describe` reads a file only.",
+  "",
   "Set `record` to write the Run's Cassette artifact. If a recorded Run fails,",
   "pass its artifact as `resume` on the retry: Asks that already succeeded",
   "replay instantly and free, and the Run goes live where it diverges. Record",
@@ -90,7 +112,7 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
   const { bun, cli, registry, sendMessage } = deps;
   const start = deps.start ?? startRun;
   const store = deps.store ?? new RunTreeStore();
-  const widget = deps.widget ?? createBackgroundWidget({ registry, store });
+  const status = deps.status ?? createBackgroundStatus({ registry, store });
   return {
     name: "yaag_run",
     label: "Run",
@@ -100,7 +122,8 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
       const text =
         context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
       text.setText(
-        theme.fg("toolTitle", theme.bold("yaag_run")) + theme.fg("muted", `(${params.file})`),
+        theme.fg("toolTitle", theme.bold("yaag_run")) +
+          theme.fg("muted", `(${programLabel(params)})`),
       );
       return text;
     },
@@ -115,26 +138,21 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
       return tree;
     },
     async execute(_id, params, signal, onUpdate, ctx) {
+      // Parameter validation precedes the Bun check, so an exactly-one-of
+      // violation is refused identically with or without Bun (ADR-0033).
+      const program = await resolveProgramTarget(params);
       if (bun === null) throw new Error(statusReport(null, cli));
 
-      const file = resolve(params.file);
-      try {
-        await access(file);
-      } catch {
-        throw new Error(`yaag_run: no such Orchestration Program: ${file}`);
-      }
-
       const id = mintRunId();
       const background = params.background === true;
-      const interactive = interactiveAvailable(ctx, background);
+      const inline = inlineAvailable(ctx, background);
       // Attached before start(): the Ask ledger folds from events, so a state
-      // created when a view opens would miss every early Ask.
+      // created when the frame is first drawn would miss every early Ask.
       const state = store.attach(id, background ? "background" : "foreground");
-      const tree = interactive ? state : undefined;
       const run = registeredRun({
         bun,
         cli,
-        file,
+        program,
         args: params.args,
         ...cassetteOptions(params),
         id,
@@ -142,33 +160,28 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
         start,
         onUpdate,
         store,
-        onIngest: () => view?.touch(),
       });
-      let view: { touch(): void } | undefined;
 
       if (background) {
         // Attached before returning, so a Run that ends immediately still
         // announces itself (ADR-0005).
-        void announce(id, run.outcome, registry, sendMessage, widget);
-        widget.refresh();
+        void announce(id, run.outcome, registry, sendMessage, status);
+        status.refresh();
         return {
           content: [{ type: "text", text: `Run ${id} started in the background.` }],
           details: { summary: run.summary, id },
         };
       }
 
-      if (tree === undefined) return await foregroundResult({ run, registry, signal });
-      return await foregroundInteractive({
+      if (!inline) return await foregroundResult({ run, registry, signal });
+      return await foregroundInline({
         run,
         registry,
         signal,
         ctx,
-        state: tree,
+        state,
         store,
-        announce: () => void announce(id, run.outcome, registry, sendMessage, widget),
-        onOpen: (opened) => {
-          view = opened;
-        },
+        announce: () => void announce(id, run.outcome, registry, sendMessage, status),
       });
     },
   };
@@ -197,11 +210,11 @@ async function announce(
   outcome: Promise<RunOutcome>,
   registry: RunRegistry,
   sendMessage: SendMessage,
-  widget: BackgroundWidget,
+  status: BackgroundStatus,
 ): Promise<void> {
   const settlement = await observedSettlement(id, outcome, registry);
-  // The Run left `registry.live`, so its widget entry must go with it.
-  widget.refresh();
+  // The Run left `registry.live`, so the footer segment must drop it.
+  status.refresh();
   const content = completionContent(id, settlement);
   const details = completionDetails(id, settlement, registry);
   await sendMessage<RunDetails>(
@@ -213,7 +226,7 @@ async function announce(
 function registeredRun(options: {
   readonly bun: string;
   readonly cli: string;
-  readonly file: string;
+  readonly program: ProgramTarget;
   readonly args?: string;
   readonly record?: string;
   readonly resume?: string;
@@ -223,13 +236,11 @@ function registeredRun(options: {
   readonly onUpdate?: (partial: { readonly content: []; readonly details: RunDetails }) => void;
   /** The projection store; it ingests each occurrence exactly once. */
   readonly store: RunTreeStore;
-  /** Redraw request for the pushed path: fd 3 fold → ingest → requestRender. */
-  readonly onIngest?: () => void;
 }): LiveRun {
   const handle = options.start({
     bun: options.bun,
     cli: options.cli,
-    file: options.file,
+    program: options.program,
     args: options.args,
     record: options.record,
     resume: options.resume,
@@ -237,7 +248,6 @@ function registeredRun(options: {
       options.registry.progress(options.id, summary);
       options.store.ingest(options.id, { summary, event, sequence, id: options.id });
       options.onUpdate?.({ content: [], details: { summary, event, sequence, id: options.id } });
-      options.onIngest?.();
     },
   });
   const run: LiveRun = {
@@ -247,7 +257,9 @@ function registeredRun(options: {
     summary: initialSummary(),
   };
   const launch = {
-    file: options.file,
+    ...(options.program.kind === "file"
+      ? { file: options.program.file }
+      : { script: options.program.source }),
     ...(options.args === undefined ? {} : { args: options.args }),
     ...(options.record === undefined ? {} : { record: options.record }),
     ...(options.resume === undefined ? {} : { resume: options.resume }),

package/src/run-tree-component.ts

@@ -3,7 +3,8 @@
  * `yaag_run` tool result or its details-only progress frames.
  *
  * It is not interactive — the rpc-mode and details-only path has no input focus
- * (spec §4). The interactive foreground view is `run-foreground-view.ts`.
+ * (architecture §9). The inline frame a blocking Run draws is `run-foreground.ts`, and
+ * the interactive view is `/yaag` (`yaag-command.ts`).
  */
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import { renderTree, TreeState } from "@yaag/tui";

package/src/run-tree-host.ts

@@ -1,10 +1,9 @@
 /**
  * The read-only half of `RunTreeViewHost`, adapted from a pi context.
  *
- * Both Run surfaces — the blocking foreground view and `/yaag` — compose it,
- * so the property that a Peek observes and never sends is asserted in one
- * place: nothing here can prompt an Agent. The caller adds `stop`, `detach`,
- * and `done`.
+ * `/yaag` composes it, so the property that a Peek observes and never sends is
+ * asserted in one place: nothing here can prompt an Agent. The caller adds
+ * `stop` and `done`.
  */
 import { readFile } from "node:fs/promises";
 import { copyToClipboard, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
@@ -22,7 +21,7 @@ export interface RunTreeHostOptions {
 }
 
 /** The read-only capabilities every Run view shares. */
-export type ReadOnlyRunTreeHost = Omit<RunTreeViewHost, "stop" | "detach" | "done">;
+export type ReadOnlyRunTreeHost = Omit<RunTreeViewHost, "stop" | "done">;
 
 /** Builds the read-only host; it never writes to an Agent or to the Run. */
 export function createRunTreeHost(options: RunTreeHostOptions): ReadOnlyRunTreeHost {

package/src/run-trees.ts

@@ -3,13 +3,13 @@
  *
  * `RunRegistry` stays the domain record — ids, stop capabilities, outcomes —
  * and this store holds the bounded renderer-only fold beside it, so the inline
- * widget and `/yaag` read the same state the foreground view reads. A
+ * frame of a blocking Run and `/yaag` read the same state. A
  * `TreeState` is bounded on every axis (node cap, Ask-ledger pruning, 2-line
  * output tails), so keeping one per Run for the session is bounded memory.
  */
 import { TreeState, type TreeUpdate } from "@yaag/tui";
 
-/** Which surface owns a Run: the blocking tool call, or the widget. */
+/** Which surface owns a Run: the blocking tool call, or the background. */
 export type RunKind = "foreground" | "background";
 
 interface Entry {
@@ -49,8 +49,8 @@ export class RunTreeStore {
 
   /**
    * Converts a foreground Run to a background Run after a detach, then
-   * notifies subscribers so the combined inline widget picks the Run up at
-   * once, without waiting for a later Lifecycle Event.
+   * notifies subscribers so the footer segment counts the Run at once, without
+   * waiting for a later Lifecycle Event.
    */
   adopt(id: string): void {
     const found = this.#entries.get(id);

package/src/spawn-run.ts

@@ -1,6 +1,9 @@
 import { applyEvent, initialSummary, type LifecycleEvent, type RunSummary } from "@yaag/runtime";
 import { startCliChild } from "./cli-child.ts";
 import { readEvents } from "./event-reader.ts";
+import { type ProgramTarget, runArgv } from "./run-argv.ts";
+
+export type { ProgramTarget } from "./run-argv.ts";
 
 /** Everything one Run of the CLI produced, once the child has exited. */
 export interface RunOutcome {
@@ -15,7 +18,8 @@ export interface RunOutcome {
 export interface StartRunOptions {
   readonly bun: string;
   readonly cli: string;
-  readonly file: string;
+  /** A program file, or an Inline Program that travels as `--eval` (ADR-0033). */
+  readonly program: ProgramTarget;
   /** Opaque JSON, forwarded untouched: the program validates it (ADR-0010). */
   readonly args?: string;
   /** Cassette path to write, forwarded as `--record` (ADR-0013). */
@@ -50,10 +54,12 @@ export interface RunHandle {
  * outcome; callers choose how that failure reaches the Host Session.
  */
 export function startRun(options: StartRunOptions): RunHandle {
-  const argv = ["run", options.file, "--events-fd", "3"];
-  if (options.args !== undefined) argv.push("--args", options.args);
-  if (options.record !== undefined) argv.push("--record", options.record);
-  if (options.resume !== undefined) argv.push("--resume", options.resume);
+  const argv = runArgv({
+    program: options.program,
+    ...(options.args === undefined ? {} : { args: options.args }),
+    ...(options.record === undefined ? {} : { record: options.record }),
+    ...(options.resume === undefined ? {} : { resume: options.resume }),
+  });
   const child = startCliChild({ bun: options.bun, cli: options.cli, argv, events: true });
   let summary: RunSummary = initialSummary();
   let sequence = 0;

package/src/test-tui-context.ts

@@ -1,5 +1,6 @@
 /**
- * A tui-mode ExtensionContext double for the interactive foreground view.
+ * A tui-mode ExtensionContext double for the `/yaag` view and the inline
+ * frames of a blocking Run.
  *
  * `ui.custom` invokes the factory synchronously against a fake TUI, so a test
  * can feed key bytes and read rendered frames. `TestExtensionContext` still
@@ -62,6 +63,11 @@ export class TestTuiContext implements ExtensionContext {
     return this.ui.widgets;
   }
 
+  /** The latest footer segment text per key. */
+  get statuses(): ReadonlyMap<string, string | undefined> {
+    return this.ui.statuses;
+  }
+
   /** Scripted answers for `ui.select`, consumed in order. */
   get selections(): string[] {
     return this.ui.selections;

package/src/yaag-command.ts

@@ -1,26 +1,19 @@
 /**
- * The `/yaag` command (spec §4): pick a Run of this session and open the same
- * interactive tree the foreground `yaag_run` opens, over the background
- * surface.
+ * The `/yaag` command (ADR-0008): pick a Run of this session and open the
+ * interactive tree over it.
  *
  * It replaces `/yaag-peek`'s Run→Agent→menu picker chain: every surviving
  * action lives in the tree's per-node menu, and the view stays read-only apart
- * from the Run's own reap-ladder stop. In a settled view `esc` closes it; in a
- * live view `q` opens the three-way prompt, where `Detach (keep running)`
- * means "close the view, the Run keeps running".
+ * from the Run's own reap-ladder stop. `esc` at tree level closes the view,
+ * live or settled, and a live Run keeps executing after that; `ctrl+q` opens
+ * the two-way Stop Run prompt.
  */
 import type {
   ExtensionContext,
   ExtensionUIContext,
   RegisteredCommand,
 } from "@earendil-works/pi-coding-agent";
-import {
-  createRunTreeView,
-  type RunTreeViewHost,
-  type RunViewExit,
-  type RunViewResult,
-  TreeState,
-} from "@yaag/tui";
+import { createRunTreeView, type RunTreeViewHost, type RunViewResult, TreeState } from "@yaag/tui";
 import { type PickableRun, pickableRuns, runFromLabel, runPickerLabel } from "./run-picker.ts";
 import type { RunRegistry, RunSettlement } from "./run-registry.ts";
 import { observedSettlement, viewResult } from "./run-settlement.ts";
@@ -102,17 +95,17 @@ async function openRun(
   // neither the view nor the renderer.
   let live = true;
   try {
-    await ctx.ui.custom<RunViewExit>((tui, _theme, keybindings, done) => {
+    await ctx.ui.custom<void>((tui, _theme, keybindings, done) => {
       const host: RunTreeViewHost = {
         ...createRunTreeHost({ ui: ctx.ui, tui, keybindings, state }),
         stop: () => {
           if (found.state === "live") found.run.stop();
         },
-        // The Run is already a background Run: leaving the view is the detach.
-        detach: () => {},
-        done,
+        // The Run keeps executing after the view closes; there is nothing to
+        // hand over, because a Run of this session is already addressable.
+        done: () => done(),
       };
-      const view = createRunTreeView({ state, host, label: run.id, surface: "background" });
+      const view = createRunTreeView({ state, host, label: run.id });
       if (found.state === "finished")
         settle(state, view, found.run.outcome, options.registry, run.id);
       else if (found.state === "live") {
@@ -120,7 +113,7 @@ async function openRun(
           if (id === run.id && live) view.touch();
         });
         // A view opened while live must reach the settled phase itself, or `esc`
-        // would keep live behavior after the Run ended (spec §4).
+        // 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);

package/src/background-widget.ts

@@ -1,107 +0,0 @@
-/**
- * The single combined inline widget for every live background Run (spec §1).
- *
- * One pi widget key holds every Run, so a Run starting or ending costs no
- * extra scrollback. The frame is a `string[]`, which pi never routes input to,
- * so the widget consumes no key by construction.
- */
-import { renderRunsWidget, type WidgetRun } from "@yaag/tui";
-import type { RunRegistry } from "./run-registry.ts";
-import type { RunTreeStore } from "./run-trees.ts";
-
-/** The one pi widget key; every Run shares it. */
-export const WIDGET_KEY = "yaag-runs";
-
-/** The only pi capability the widget needs. */
-export interface WidgetSurface {
-  setWidget(key: string, lines: string[] | undefined): void;
-}
-
-/**
- * What the combined widget needs: the Run registry it reads live Runs from,
- * the projection store it reads their `TreeState` from, and the render budget.
- */
-export interface BackgroundWidgetOptions {
-  readonly registry: RunRegistry;
-  readonly store: RunTreeStore;
-  readonly now?: () => number;
-  readonly width?: number;
-  readonly maxLines?: number;
-}
-
-/** The widget controller: bind it once, then refresh it on every occurrence. */
-export interface BackgroundWidget {
-  /**
-   * Binds the pi UI surface, once the Host Session has one, and draws the
-   * current frame. A `WidgetSurface.setWidget()` that throws propagates here.
-   */
-  bind(surface: WidgetSurface): void;
-  /**
-   * Redraws the frame; drops the redraw before `bind`, and skips an unchanged
-   * frame. A bound `WidgetSurface.setWidget()` that throws propagates here.
-   */
-  refresh(): void;
-  /**
-   * Unsubscribes from the store and clears the widget. A bound
-   * `WidgetSurface.setWidget()` that throws propagates here.
-   */
-  dispose(): void;
-}
-
-/**
- * Builds the combined widget over this session's Run registry and projections.
- *
- * An unbound controller drops every refresh, and a Run without a projection is
- * skipped. Construction itself never throws, but `bind()`, `refresh()`, and
- * `dispose()` call the caller's `WidgetSurface.setWidget()` and propagate
- * whatever it throws; the store subscription also propagates it into the
- * `ingest()` that caused the redraw.
- */
-export function createBackgroundWidget(options: BackgroundWidgetOptions): BackgroundWidget {
-  const now = options.now ?? Date.now;
-  const width = options.width ?? 100;
-  let surface: WidgetSurface | undefined;
-  let drawn: readonly string[] | undefined;
-
-  const entries = (): readonly WidgetRun[] => {
-    const runs: WidgetRun[] = [];
-    for (const run of options.registry.live) {
-      if (options.store.kind(run.id) !== "background") continue;
-      const state = options.store.get(run.id);
-      if (state !== undefined) runs.push({ id: run.id, state });
-    }
-    return runs;
-  };
-
-  const refresh = (): void => {
-    if (surface === undefined) return;
-    const lines = renderRunsWidget(entries(), {
-      now: now(),
-      width,
-      ...(options.maxLines === undefined ? {} : { maxLines: options.maxLines }),
-    });
-    if (drawn !== undefined && sameLines(drawn, lines)) return;
-    drawn = lines;
-    surface.setWidget(WIDGET_KEY, lines.length === 0 ? undefined : [...lines]);
-  };
-
-  const unsubscribe = options.store.subscribe(() => refresh());
-
-  return {
-    bind(bound: WidgetSurface): void {
-      surface = bound;
-      drawn = undefined;
-      refresh();
-    },
-    refresh,
-    dispose(): void {
-      unsubscribe();
-      surface?.setWidget(WIDGET_KEY, undefined);
-      surface = undefined;
-    },
-  };
-}
-
-function sameLines(left: readonly string[], right: readonly string[]): boolean {
-  return left.length === right.length && left.every((line, index) => line === right[index]);
-}

package/src/run-foreground-view.ts

@@ -1,95 +0,0 @@
-/**
- * Opens the interactive Run tree for a blocking `yaag_run` in tui mode
- * (spec §4), and adapts the Host Session's capabilities to
- * `RunTreeViewHost`.
- *
- * The host surface is read-only except for the Run's own reap-ladder stop and
- * the detach request: nothing here can prompt an Agent (ADR — a Peek observes,
- * it never sends).
- */
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import {
-  createRunTreeView,
-  type RunTreeView,
-  type RunTreeViewHost,
-  type RunViewExit,
-  type TreeState,
-} from "@yaag/tui";
-import { createRunTreeHost } from "./run-tree-host.ts";
-
-/**
- * What `openRunTreeView` needs to adapt one Run to the interactive view.
- *
- * The caller must supply a tui-mode `ctx` with UI; `openRunTreeView` throws
- * when `ctx.ui` is absent, because there is no surface to open.
- */
-export interface OpenRunTreeViewOptions {
-  readonly ctx: ExtensionContext;
-  /** Created and ingested from Run start, so no early Ask is missed. */
-  readonly state: TreeState;
-  readonly id: string;
-  /** Runs the reap ladder for this Run (ADR-0008). */
-  stop(): void;
-  /** Converts the Run to a background Run. */
-  onDetach(): void;
-}
-
-/** The opened view: its exit promise, plus the handles the tool drives. */
-export interface OpenedRunTreeView {
-  /** Resolves when the reader dismisses or detaches the view. */
-  readonly exit: Promise<RunViewExit>;
-  /** The Run settled; freeze the tree and show the Result region. */
-  settle(result: Parameters<RunTreeView["settle"]>[0]): void;
-  /** A pushed fd 3 update landed in the TreeState; redraw. */
-  touch(): void;
-  /** Closes the view from the host's side, e.g. on an abort. */
-  close(exit: RunViewExit): void;
-  dispose(): void;
-}
-
-/**
- * Opens the view through `ctx.ui.custom()`.
- *
- * The returned `exit` promise always settles: the reader's `q`/detach resolves
- * it, and `close` resolves it for a host-side abort, so a tool call can never
- * hang on the view.
- */
-export function openRunTreeView(options: OpenRunTreeViewOptions): OpenedRunTreeView {
-  const state = options.state;
-  let view: RunTreeView | undefined;
-  let finish: ((exit: RunViewExit) => void) | undefined;
-  let pendingExit: RunViewExit | undefined;
-  let pendingSettle: Parameters<RunTreeView["settle"]>[0] | undefined;
-
-  const exit = options.ctx.ui.custom<RunViewExit>((tui, _theme, keybindings, done) => {
-    finish = done;
-    const host: RunTreeViewHost = {
-      ...createRunTreeHost({ ui: options.ctx.ui, tui, keybindings, state }),
-      stop: options.stop,
-      detach: options.onDetach,
-      done,
-    };
-    view = createRunTreeView({ state, host, label: options.id, surface: "foreground" });
-    if (pendingSettle !== undefined) view.settle(pendingSettle);
-    if (pendingExit !== undefined) done(pendingExit);
-    return view;
-  });
-
-  return {
-    exit,
-    settle(result): void {
-      if (view === undefined) pendingSettle = result;
-      else view.settle(result);
-    },
-    touch(): void {
-      view?.touch();
-    },
-    close(kind): void {
-      if (finish === undefined) pendingExit = kind;
-      else finish(kind);
-    },
-    dispose(): void {
-      view?.dispose();
-    },
-  };
-}