@yaag/extension 0.1.0

package/src/run-settlement.ts

@@ -0,0 +1,64 @@
+/**
+ * The one place a Run's observed settlement and its failure text live, shared by
+ * the blocking, interactive, and background paths of `yaag_run`.
+ */
+import type { RunViewResult } from "@yaag/tui";
+import type { RunRegistry, RunSettlement } from "./run-registry.ts";
+import type { RunOutcome } from "./spawn-run.ts";
+
+/**
+ * The settlement the registry retained for a Run.
+ *
+ * Throws when the Run settled but the registry kept no record, because every
+ * later channel — content, details, usage — reads that record.
+ */
+export async function observedSettlement(
+  id: string,
+  outcome: Promise<RunOutcome>,
+  registry: RunRegistry,
+): Promise<RunSettlement> {
+  try {
+    await outcome;
+  } catch {}
+  const found = registry.lookup(id);
+  if (found.state === "finished") return found.run.outcome;
+  throw new Error(`yaag_run: Run ${id} settled without registry retention`);
+}
+
+/**
+ * The Result region's content for a settled Run, shared by the foreground view
+ * and `/yaag`'s settled background view.
+ */
+export function viewResult(settlement: RunSettlement): RunViewResult {
+  if (settlement.kind === "rejected")
+    return { kind: "failed", error: errorText(settlement.reason) };
+  const { outcome } = settlement;
+  return outcome.code === 0
+    ? { kind: "fulfilled", result: outcome.stdout.trimEnd() }
+    : { kind: "failed", error: failure(outcome.code, ""), stderrTail: outcome.stderr };
+}
+
+/** The failure message of a Run, with the bounded tail of its own stderr. */
+export function failure(code: number | null, stderr: string): string {
+  const tail = stderr.trimEnd();
+  const what = code === null ? "the Run was killed" : `the Run failed (exit ${code})`;
+  return tail === "" ? `yaag_run: ${what}` : `yaag_run: ${what}\n${tail}`;
+}
+
+/**
+ * The message of an arbitrary thrown value, for a channel that shows text.
+ *
+ * Never throws: a non-`Error` reason is stringified.
+ */
+export function errorText(reason: unknown): string {
+  return reason instanceof Error ? reason.message : String(reason);
+}
+
+/**
+ * An arbitrary thrown value as an `Error`, so a rejection keeps one type.
+ *
+ * Never throws: a non-`Error` reason becomes an `Error` with its text.
+ */
+export function toError(reason: unknown): Error {
+  return reason instanceof Error ? reason : new Error(String(reason));
+}

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

@@ -0,0 +1,126 @@
+import { dirname, join } from "node:path";
+import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { BackgroundWidget } from "./background-widget.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 { createStopTool, type StopDetails } from "./stop-tool.ts";
+import { TestExtensionContext } from "./test-extension-context.ts";
+
+const cli = resolveCliEntry();
+const bun = await resolveBun();
+if (bun === null) throw new Error("these tests need bun on PATH");
+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 args?: string;
+  readonly background?: boolean;
+}
+
+export interface Sent {
+  readonly content: unknown;
+  readonly details: unknown;
+  readonly options: Parameters<SendMessage>[1];
+  readonly hasUsage: boolean;
+}
+
+export async function run(
+  params: RunParams,
+  opts: {
+    readonly bun?: string | null;
+    readonly signal?: AbortSignal;
+    readonly onUpdate?: (partial: AgentToolResult<RunDetails>) => void;
+    readonly registry?: RunRegistry;
+    readonly sent?: Sent[];
+    readonly start?: (options: import("./spawn-run.ts").StartRunOptions) => RunHandle;
+    /** A tui-mode context, for the interactive foreground path. */
+    readonly ctx?: ExtensionContext;
+    readonly store?: RunTreeStore;
+    readonly widget?: BackgroundWidget;
+  } = {},
+): Promise<{
+  readonly text: string;
+  readonly details: RunDetails;
+  readonly result: AgentToolResult<RunDetails>;
+}> {
+  const tool = createRunTool({
+    bun: opts.bun === undefined ? bun : opts.bun,
+    cli,
+    registry: opts.registry ?? new RunRegistry(),
+    ...(opts.start === undefined ? {} : { start: opts.start }),
+    ...(opts.store === undefined ? {} : { store: opts.store }),
+    ...(opts.widget === undefined ? {} : { widget: opts.widget }),
+    sendMessage: (message, options) =>
+      void opts.sent?.push({
+        content: message.content,
+        details: message.details,
+        options,
+        hasUsage: Object.hasOwn(message, "usage"),
+      }),
+  });
+  const result = await tool.execute("call-1", params, opts.signal, opts.onUpdate, opts.ctx ?? ctx);
+  const first = result.content[0];
+  return { text: first?.type === "text" ? first.text : "", details: result.details, result };
+}
+
+export async function stop(
+  registry: RunRegistry,
+  id: string,
+): Promise<{
+  readonly text: string;
+  readonly details: StopDetails;
+  readonly result: AgentToolResult<StopDetails>;
+}> {
+  const result = await createStopTool(registry).execute(
+    "call-2",
+    { id },
+    undefined,
+    undefined,
+    ctx,
+  );
+  const first = result.content[0];
+  return { text: first?.type === "text" ? first.text : "", details: result.details, result };
+}
+
+/**
+ * Narrows a caught value to `Error` with a runtime check.
+ *
+ * Throws when the value is not an `Error`, so a test that asserts on a message
+ * fails at the boundary instead of hiding a non-Error rejection behind a cast.
+ */
+export function asError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  throw new TypeError(`expected an Error, got ${typeof value}: ${String(value)}`);
+}
+
+export async function until(predicate: () => Promise<boolean>, ms = 10_000): Promise<boolean> {
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+    if (await predicate()) return true;
+    await Bun.sleep(50);
+  }
+  return false;
+}
+
+export async function running(pattern: string): Promise<boolean> {
+  const found = Bun.spawn({ cmd: ["pgrep", "-f", pattern], stdout: "pipe", stderr: "ignore" });
+  const output = await new Response(found.stdout).text();
+  await found.exited;
+  return output.trim() !== "";
+}
+
+export function toolDescription(): string {
+  return createRunTool({
+    bun,
+    cli,
+    registry: new RunRegistry(),
+    sendMessage: () => undefined,
+  }).description;
+}

package/src/run-tool.ts

@@ -0,0 +1,276 @@
+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 { RunDetails } from "./run-details.ts";
+import { foregroundInteractive, foregroundResult, interactiveAvailable } 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 { 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" }),
+  args: Type.Optional(
+    Type.String({ description: "The program's arguments, as a JSON object string" }),
+  ),
+  background: Type.Optional(
+    Type.Boolean({ description: "Start the Run in the background and return its Run id" }),
+  ),
+  record: Type.Optional(
+    Type.String({ description: "Write the Run's Cassette artifact to this path" }),
+  ),
+  resume: Type.Optional(
+    Type.String({
+      description:
+        "Resume from this Cassette: matching Asks replay free, then the Run continues live",
+    }),
+  ),
+});
+
+/** pi's own message channel, narrowed to what a background Run needs. */
+export type SendMessage = ExtensionAPI["sendMessage"];
+
+export interface RunToolOptions {
+  readonly bun: string | null;
+  readonly cli: string;
+  readonly registry: RunRegistry;
+  readonly sendMessage: SendMessage;
+  /** Test seam for a controlled child Run handle. */
+  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;
+}
+
+const DESCRIPTION = [
+  "Run an Orchestration Program and return its result.",
+  "",
+  "An Orchestration Program is a user-authored TypeScript file that exports a run",
+  "definition as its default export; programs live in a Program Directory — a",
+  "directory containing `.yaag/`. Use your file tools to find a program — yaag_describe describes",
+  "one known path and does not list programs.",
+  "",
+  "Use yaag_describe({ file }) to discover a program's declared arguments instead",
+  "of reading its source. `args` is passed through untouched as a JSON object string.",
+  "Programs declaring an args schema reject invalid arguments before any Agent is spawned.",
+  "The call blocks until the Run ends and returns the Run's value.",
+  "",
+  "Set `background: true` for a long Run: the call returns at once with a short",
+  "Run id (r1, r2, …), progress keeps streaming, and the result arrives as a",
+  "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 })`.",
+  "",
+  "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",
+  "the retry too (to a different path) to keep every attempt resumable.",
+].join("\n");
+
+/**
+ * The `yaag_run` tool: runs one Orchestration Program through the Bun CLI and
+ * returns its value (ADR-0005).
+ *
+ * `execute` throws on any failure — a missing Bun, a path that is not there, a
+ * Run that failed — which is how pi marks a tool result as an error. On failure
+ * the message carries the tail of the CLI's own error output.
+ */
+export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof parameters, RunDetails> {
+  const { bun, cli, registry, sendMessage } = deps;
+  const start = deps.start ?? startRun;
+  const store = deps.store ?? new RunTreeStore();
+  const widget = deps.widget ?? createBackgroundWidget({ registry, store });
+  return {
+    name: "yaag_run",
+    label: "Run",
+    description: DESCRIPTION,
+    parameters,
+    renderCall(params, theme, context) {
+      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})`),
+      );
+      return text;
+    },
+    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
+          ? context.lastComponent
+          : new RunTreeComponent(details);
+      tree.update(details);
+      return tree;
+    },
+    async execute(_id, params, signal, onUpdate, ctx) {
+      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 = registry.mint();
+      const background = params.background === true;
+      const interactive = interactiveAvailable(ctx, background);
+      // Attached before start(): the Ask ledger folds from events, so a state
+      // created when a view opens would miss every early Ask.
+      const state = store.attach(id, background ? "background" : "foreground");
+      const tree = interactive ? state : undefined;
+      const run = registeredRun({
+        bun,
+        cli,
+        file,
+        args: params.args,
+        ...cassetteOptions(params),
+        id,
+        registry,
+        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();
+        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({
+        run,
+        registry,
+        signal,
+        ctx,
+        state: tree,
+        store,
+        announce: () => void announce(id, run.outcome, registry, sendMessage, widget),
+        onOpen: (opened) => {
+          view = opened;
+        },
+      });
+    },
+  };
+}
+
+/**
+ * Cassette paths resolved like `file`; the CLI owns every rule about them —
+ * combinations, validation, refusals — and its own message surfaces on failure.
+ */
+function cassetteOptions(params: { readonly record?: string; readonly resume?: string }): {
+  record?: string;
+  resume?: string;
+} {
+  return {
+    ...(params.record === undefined ? {} : { record: resolve(params.record) }),
+    ...(params.resume === undefined ? {} : { resume: resolve(params.resume) }),
+  };
+}
+
+/**
+ * Waits for a background Run and delivers its end as a follow-up message that
+ * triggers a turn, so the model sees the result without being asked (ADR-0005).
+ */
+async function announce(
+  id: string,
+  outcome: Promise<RunOutcome>,
+  registry: RunRegistry,
+  sendMessage: SendMessage,
+  widget: BackgroundWidget,
+): Promise<void> {
+  const settlement = await observedSettlement(id, outcome, registry);
+  // The Run left `registry.live`, so its widget entry must go with it.
+  widget.refresh();
+  const content = completionContent(id, settlement);
+  const details = completionDetails(id, settlement, registry);
+  await sendMessage<RunDetails>(
+    { customType: "yaag-run-complete", content, display: true, details },
+    { deliverAs: "followUp", triggerTurn: true },
+  );
+}
+
+function registeredRun(options: {
+  readonly bun: string;
+  readonly cli: string;
+  readonly file: string;
+  readonly args?: string;
+  readonly record?: string;
+  readonly resume?: string;
+  readonly id: string;
+  readonly registry: RunRegistry;
+  readonly start: (options: StartRunOptions) => RunHandle;
+  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 {
+  let run: LiveRun;
+  const handle = options.start({
+    bun: options.bun,
+    cli: options.cli,
+    file: options.file,
+    args: options.args,
+    record: options.record,
+    resume: options.resume,
+    onProgress: (summary, event, sequence) => {
+      run.summary = summary;
+      options.store.ingest(options.id, { summary, event, sequence, id: options.id });
+      options.onUpdate?.({ content: [], details: { summary, event, sequence, id: options.id } });
+      options.onIngest?.();
+    },
+  });
+  run = { id: options.id, stop: handle.stop, outcome: handle.outcome, summary: initialSummary() };
+  options.registry.add(run);
+  return run;
+}
+
+function completionContent(id: string, settlement: RunSettlement): string {
+  if (settlement.kind === "rejected") return `Run ${id} failed: ${errorText(settlement.reason)}`;
+  const { outcome } = settlement;
+  return outcome.code === 0
+    ? `Run ${id} finished.\n${outcome.stdout.trimEnd()}`
+    : `Run ${id}: ${failure(outcome.code, outcome.stderr)}`;
+}
+
+function completionDetails(
+  id: string,
+  settlement: RunSettlement,
+  registry: RunRegistry,
+): RunDetails {
+  const found = registry.lookup(id);
+  if (found.state !== "finished") throw new Error(`yaag_run: Run ${id} is not retained`);
+  return {
+    summary: found.run.summary,
+    id,
+    ...(settlement.kind === "fulfilled" && settlement.outcome.code === 0
+      ? { result: settlement.outcome.stdout.trimEnd() }
+      : {}),
+  };
+}
+
+function contentText(result: { readonly content: readonly { readonly type: string }[] }): string {
+  return result.content
+    .filter((content) => content.type === "text" && "text" in content)
+    .map((content) => ("text" in content ? String(content.text) : ""))
+    .join("\n");
+}

package/src/run-tree-component.ts

@@ -0,0 +1,50 @@
+/**
+ * The Host Session details component: the Run tree rendered wherever pi shows a
+ * `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`.
+ */
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { renderTree, TreeState } from "@yaag/tui";
+import type { RunDetails } from "./run-details.ts";
+
+/** Injection points for the details component; all optional. */
+export interface RunTreeComponentOptions {
+  /** The clock the tree reads for durations; defaults to `Date.now`. */
+  readonly now?: () => number;
+}
+
+/**
+ * A pi component backed by `TreeState`'s bounded, sequence-keyed projection.
+ *
+ * It ingests each fd 3 occurrence exactly once, so a redraw at any terminal
+ * width can neither count an Ask twice nor show an output tail twice (spec §5).
+ */
+export class RunTreeComponent {
+  readonly #state: TreeState;
+  readonly #now: () => number;
+
+  constructor(details: RunDetails, options: RunTreeComponentOptions = {}) {
+    this.#state = TreeState.fromSummary(details.summary);
+    this.#now = options.now ?? Date.now;
+    this.#state.ingest(details);
+  }
+
+  /** Folds one tool result or details-only progress frame. */
+  update(details: RunDetails): void {
+    this.#state.ingest(details);
+  }
+
+  /** Renders the four-region tree, plus the Result region once the Run settled. */
+  render(width: number): string[] {
+    const id = this.#state.runId;
+    return renderTree(this.#state, {
+      now: this.#now(),
+      width,
+      ...(id === undefined ? {} : { label: id }),
+    }).map((line) => truncateToWidth(line, width));
+  }
+
+  invalidate(): void {}
+}

package/src/run-tree-host.ts

@@ -0,0 +1,56 @@
+/**
+ * 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`.
+ */
+import { readFile } from "node:fs/promises";
+import { copyToClipboard, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import type { AgentInfo } from "@yaag/runtime";
+import type { NamedKeybindings, RunTreeViewHost, TreeState } from "@yaag/tui";
+
+/** The pi services one open view holds. */
+export interface RunTreeHostOptions {
+  readonly ui: Pick<ExtensionUIContext, "notify" | "editor">;
+  readonly tui: TUI;
+  readonly keybindings: NamedKeybindings;
+  /** The Run's projection; the host only reads it. */
+  readonly state: TreeState;
+}
+
+/** The read-only capabilities every Run view shares. */
+export type ReadOnlyRunTreeHost = Omit<RunTreeViewHost, "stop" | "detach" | "done">;
+
+/** Builds the read-only host; it never writes to an Agent or to the Run. */
+export function createRunTreeHost(options: RunTreeHostOptions): ReadOnlyRunTreeHost {
+  const { state, tui, ui } = options;
+  return {
+    keybindings: options.keybindings,
+    agentInfo: (agent) => state.summary.agents[agent],
+    readSession: (agent) => readSession(state.summary.agents[agent]),
+    sessionPath: (agent) => state.summary.agents[agent]?.sessionFile ?? null,
+    copyPath: (text) => copyToClipboard(text),
+    openEditor: async (title, body) => {
+      await ui.editor(title, body);
+    },
+    notify: (message, level) => ui.notify(message, level),
+    requestRender: () => tui.requestRender(),
+    rows: () => Math.max(1, tui.terminal.rows - 1),
+  };
+}
+
+/** Reads an Agent's session file, or null when it is missing or unreadable. */
+async function readSession(info: AgentInfo | undefined): Promise<string | null> {
+  const path = info?.sessionFile;
+  if (path === undefined || path === null) return null;
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    // The file does not exist until the first Ask completes (ADR-0012), and a
+    // Cassette-playback Agent never had one; both degrade to the labelled stub.
+    return null;
+  }
+}

package/src/run-trees.ts

@@ -0,0 +1,91 @@
+/**
+ * The per-session store of renderer projections, one `TreeState` per Run.
+ *
+ * `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
+ * `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. */
+export type RunKind = "foreground" | "background";
+
+interface Entry {
+  readonly state: TreeState;
+  kind: RunKind;
+}
+
+/** Notified with the Run id after each ingested occurrence, and on adopt. */
+export type RunTreeListener = (id: string) => void;
+
+/**
+ * The per-session projection store: one bounded `TreeState` per Run.
+ *
+ * Every method for an unknown Run id is a no-op or returns `undefined`.
+ * Ingest is exactly-once per fd 3 occurrence sequence, so a replayed
+ * occurrence cannot duplicate an Ask fact.
+ *
+ * Failure mode: `adopt()` and `ingest()` invoke subscriber callbacks, and a
+ * throwing subscriber propagates out of that call. Every other method throws
+ * nothing.
+ */
+export class RunTreeStore {
+  readonly #entries = new Map<string, Entry>();
+  readonly #listeners = new Set<RunTreeListener>();
+
+  /**
+   * Creates the projection for a Run before it starts, so no early Ask is
+   * missed. Re-attaching a known id returns the existing state untouched.
+   */
+  attach(id: string, kind: RunKind): TreeState {
+    const found = this.#entries.get(id);
+    if (found !== undefined) return found.state;
+    const state = new TreeState();
+    this.#entries.set(id, { state, kind });
+    return state;
+  }
+
+  /**
+   * 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.
+   */
+  adopt(id: string): void {
+    const found = this.#entries.get(id);
+    if (found === undefined) return;
+    found.kind = "background";
+    this.#notify(id);
+  }
+
+  /** Folds one occurrence into the Run's state, then notifies subscribers. */
+  ingest(id: string, update: TreeUpdate): void {
+    const found = this.#entries.get(id);
+    if (found === undefined) return;
+    found.state.ingest(update);
+    this.#notify(id);
+  }
+
+  /** The Run's projection, or undefined for a Run that carried none. */
+  get(id: string): TreeState | undefined {
+    return this.#entries.get(id)?.state;
+  }
+
+  /** Which surface owns the Run, or undefined for an unknown Run. */
+  kind(id: string): RunKind | undefined {
+    return this.#entries.get(id)?.kind;
+  }
+
+  /** Subscribes to every ingest; the returned function unsubscribes. */
+  subscribe(listener: RunTreeListener): () => void {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+
+  #notify(id: string): void {
+    for (const listener of this.#listeners) listener(id);
+  }
+}