@yaag/extension 0.1.4 → 0.2.1

package/src/run-registry.ts

@@ -1,6 +1,12 @@
 import type { EndedRunSummary, RunSummary } from "@yaag/runtime";
+import type { ProcessIdentity } from "./process-liveness.ts";
+import { type RunLaunch, type RunRecord, startedRecord } from "./run-record.ts";
+import { restoreRecords } from "./run-restore.ts";
+import type { RunStore } from "./run-store.ts";
 import type { RunOutcome } from "./spawn-run.ts";
 
+export type { RunLaunch } from "./run-record.ts";
+
 /** A Run in flight, including its stop capability and latest Summary fold. */
 export interface LiveRun {
   readonly id: string;
@@ -21,30 +27,51 @@ export interface FinishedRun {
   readonly outcome: RunSettlement;
 }
 
+/** A Run read back from disk, started by an earlier Host Session. */
+export interface RestoredRun {
+  readonly id: string;
+  readonly summary: RunSummary;
+  readonly record: RunRecord;
+}
+
 /** The retained state of a registered Run. */
 export type RegisteredRun =
   | { readonly state: "live"; readonly run: LiveRun }
-  | { readonly state: "finished"; readonly run: FinishedRun };
+  | { readonly state: "finished"; readonly run: FinishedRun }
+  | { readonly state: "restored"; readonly run: RestoredRun };
 
 /** What the registry knows about an id. */
 export type RunStatus = RegisteredRun | { readonly state: "unknown" };
 
+/** How often a Run's latest Summary is persisted while it runs. */
+export const SUMMARY_WRITE_INTERVAL_MS = 2_000;
+
+export interface RunRegistryOptions {
+  /** Durable mirror; omit it and the registry stays memory-only. */
+  readonly store?: RunStore;
+  readonly now?: () => Date;
+}
+
 /**
- * Per-session source of truth for every Run started by the Host Session.
+ * Source of truth for every Run the Host Session can address.
  *
- * It mints monotonically increasing ids, retains live stop capabilities, and
- * preserves final outcomes for the rest of the session. Concurrent Runs remain
- * independently controllable (ADR-0008).
+ * It retains live stop capabilities and final outcomes in memory, and mirrors
+ * each Run to a {@link RunStore} so a restart of the Host Session does not lose
+ * the id (ticket 02). Concurrent Runs remain independently controllable
+ * (ADR-0008).
  */
 export class RunRegistry {
-  #counter = 0;
   readonly #live = new Map<string, LiveRun>();
   readonly #runs = new Map<string, RegisteredRun>();
-
-  /** The next Run id for this session; it is never reused. */
-  mint(): string {
-    this.#counter += 1;
-    return `r${this.#counter}`;
+  readonly #records = new Map<string, RunRecord>();
+  readonly #lastWrite = new Map<string, number>();
+  readonly #trailing = new Map<string, ReturnType<typeof setTimeout>>();
+  readonly #store: RunStore | undefined;
+  readonly #now: () => Date;
+
+  constructor(options: RunRegistryOptions = {}) {
+    this.#store = options.store;
+    this.#now = options.now ?? (() => new Date());
   }
 
   /** Every currently-live Run, in registration order. */
@@ -52,31 +79,72 @@ export class RunRegistry {
     return [...this.#live.values()];
   }
 
-  /** Every registered Run, live and finished, in registration order. */
+  /** Every addressable Run: this session's Runs, plus unaccounted earlier ones. */
   get runs(): readonly RegisteredRun[] {
     return [...this.#runs.values()];
   }
 
-  /** Every registered Run id, in registration order. */
+  /** Every addressable Run id, in registration order. */
   get knownIds(): readonly string[] {
     return [...this.#runs.keys()];
   }
 
+  /**
+   * Loads persisted Runs, settles the ones an earlier session left `live`, and
+   * seeds the still-unaccounted ones. Finished Runs of earlier sessions stay on
+   * disk and are reachable through {@link recall} by id.
+   */
+  async restore(): Promise<void> {
+    if (this.#store === undefined) return;
+    const records = await restoreRecords({ store: this.#store, now: this.#now });
+    for (const record of records) {
+      if (record.state !== "orphaned" && record.state !== "interrupted") continue;
+      this.#runs.set(record.id, { state: "restored", run: restored(record) });
+    }
+  }
+
   /** Registers a newly-started Run and synchronously observes its settlement. */
-  add(run: LiveRun): void {
+  add(run: LiveRun, launch?: RunLaunch, identity?: ProcessIdentity | null): void {
     this.#live.set(run.id, run);
     this.#runs.set(run.id, { state: "live", run });
+    if (launch !== undefined) this.#persistStart(run.id, launch, identity ?? null);
     void run.outcome.then(
       (outcome) => this.finish(run.id, outcome),
       (reason: unknown) => this.reject(run.id, reason),
     );
   }
 
+  /** Records the latest fold for a live Run and persists it at a bounded rate. */
+  progress(id: string, summary: RunSummary): void {
+    const run = this.#live.get(id);
+    if (run === undefined) return;
+    run.summary = summary;
+    const record = this.#records.get(id);
+    if (record === undefined) return;
+    this.#records.set(id, { ...record, summary });
+    const waited = this.#now().getTime() - (this.#lastWrite.get(id) ?? 0);
+    if (waited < SUMMARY_WRITE_INTERVAL_MS) {
+      this.#scheduleTrailing(id, waited);
+      return;
+    }
+    this.#persist(id);
+  }
+
   /** Looks up a live capability or the retained completed Run. */
   lookup(id: string): RunStatus {
     return this.#runs.get(id) ?? { state: "unknown" };
   }
 
+  /** Reads a Run this session never started back from the store, by id. */
+  async recall(id: string): Promise<RunStatus> {
+    const known = this.lookup(id);
+    if (known.state !== "unknown" || this.#store === undefined) return known;
+    const record = (await this.#store.load()).find((entry) => entry.id === id);
+    return record === undefined
+      ? { state: "unknown" }
+      : { state: "restored", run: restored(record) };
+  }
+
   /**
    * Retains a Run's first observed final outcome and removes only its live
    * capability. Repeated observers are harmless and cannot overwrite history.
@@ -88,16 +156,85 @@ export class RunRegistry {
   /** Retains a rejected child outcome with its latest terminal accounting projection. */
   reject(id: string, reason: unknown): void {
     const record = this.#runs.get(id);
-    if (record === undefined || record.state === "finished") return;
+    if (record === undefined || record.state !== "live") return;
     this.#settle(id, failedSummary(record.run.summary), { kind: "rejected", reason });
   }
 
+  /**
+   * Persists the latest Summary when the interval ends. Without it, everything
+   * folded inside one interval would be lost if the Host Session died before
+   * the next write (ticket 02).
+   */
+  #scheduleTrailing(id: string, waited: number): void {
+    if (this.#trailing.has(id)) return;
+    const timer = setTimeout(() => {
+      this.#trailing.delete(id);
+      if (this.#live.has(id)) this.#persist(id);
+    }, SUMMARY_WRITE_INTERVAL_MS - waited);
+    // Housekeeping must never keep the Host Session alive.
+    timer.unref();
+    this.#trailing.set(id, timer);
+  }
+
   #settle(id: string, summary: RunSummary, outcome: RunSettlement): void {
     const record = this.#runs.get(id);
-    if (record === undefined || record.state === "finished") return;
+    if (record === undefined || record.state !== "live") return;
     this.#live.delete(id);
+    const trailing = this.#trailing.get(id);
+    if (trailing !== undefined) clearTimeout(trailing);
+    this.#trailing.delete(id);
     this.#runs.set(id, { state: "finished", run: { id, summary, outcome } });
+    this.#persistEnd(id, summary, outcome);
+  }
+
+  #persistStart(id: string, launch: RunLaunch, identity: ProcessIdentity | null): void {
+    if (this.#store === undefined) return;
+    const store = this.#store;
+    this.#records.set(
+      id,
+      startedRecord({ id, launch, process: identity, now: this.#now().toISOString() }),
+    );
+    this.#persist(id);
+    void store.prune();
+  }
+
+  #persistEnd(id: string, summary: RunSummary, outcome: RunSettlement): void {
+    const record = this.#records.get(id);
+    if (record === undefined) return;
+    this.#records.set(id, {
+      ...record,
+      state: "finished",
+      endedAt: this.#now().toISOString(),
+      summary,
+      outcome: persistedOutcome(outcome),
+    });
+    this.#persist(id);
   }
+
+  #persist(id: string): void {
+    const record = this.#records.get(id);
+    if (record === undefined || this.#store === undefined) return;
+    this.#lastWrite.set(id, this.#now().getTime());
+    void this.#store.save(record);
+  }
+}
+
+function restored(record: RunRecord): RestoredRun {
+  return { id: record.id, summary: record.summary, record };
+}
+
+function persistedOutcome(outcome: RunSettlement): RunRecord["outcome"] {
+  if (outcome.kind === "rejected")
+    return { kind: "rejected", reason: errorMessage(outcome.reason) };
+  return {
+    kind: "fulfilled",
+    code: outcome.outcome.code,
+    result: outcome.outcome.stdout.trimEnd(),
+  };
+}
+
+function errorMessage(reason: unknown): string {
+  return reason instanceof Error ? reason.message : String(reason);
 }
 
 function failedSummary(summary: RunSummary): EndedRunSummary {

package/src/run-restore.ts

@@ -0,0 +1,43 @@
+import { isProcessAlive, type ProcessIdentity } from "./process-liveness.ts";
+import type { RunRecord } from "./run-record.ts";
+import type { RunStore } from "./run-store.ts";
+
+/** Decides whether the process a record names is still running. */
+export type LivenessProbe = (identity: ProcessIdentity) => boolean;
+
+export interface RestoreOptions {
+  readonly store: RunStore;
+  readonly isAlive?: LivenessProbe;
+  readonly now?: () => Date;
+}
+
+/**
+ * Reads every persisted Run and settles the ones a previous Host Session left
+ * behind.
+ *
+ * A `live` record can only be stale here, because the session that owned it is
+ * gone: its child is dead and the Run is `interrupted`, or its child still runs
+ * without an owner and the Run is `orphaned`. Both re-writes are persisted, so
+ * the verdict survives this session too (ticket 02).
+ */
+export async function restoreRecords(options: RestoreOptions): Promise<readonly RunRecord[]> {
+  const isAlive = options.isAlive ?? isProcessAlive;
+  const now = options.now ?? (() => new Date());
+  const records = await options.store.load();
+  return Promise.all(records.map((record) => settleStale(record, isAlive, now, options.store)));
+}
+
+async function settleStale(
+  record: RunRecord,
+  isAlive: LivenessProbe,
+  now: () => Date,
+  store: RunStore,
+): Promise<RunRecord> {
+  if (record.state !== "live") return record;
+  const alive = record.process !== null && isAlive(record.process);
+  const settled: RunRecord = alive
+    ? { ...record, state: "orphaned" }
+    : { ...record, state: "interrupted", endedAt: now().toISOString() };
+  await store.save(settled);
+  return settled;
+}

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-store.ts

@@ -0,0 +1,103 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isRunRecord, type RunRecord } from "./run-record.ts";
+import { resolveRunsDirectory } from "./runs-dir.ts";
+
+/** How many finished records are kept before the oldest ones are pruned. */
+export const FINISHED_RECORD_CAP = 200;
+
+export interface RunStoreOptions {
+  readonly directory?: string;
+  readonly cap?: number;
+}
+
+/**
+ * The durable side of the Run registry: one JSON file per Run.
+ *
+ * Every method is best-effort and never throws — a Host Session must keep
+ * working when the state directory is read-only or full. Writes go to a temp
+ * file and are renamed into place, so a reader never sees a half-written record
+ * (ADR-0021).
+ */
+export class RunStore {
+  readonly #directory: string;
+  readonly #cap: number;
+  #chain: Promise<void> = Promise.resolve();
+
+  constructor(options: RunStoreOptions = {}) {
+    this.#directory = options.directory ?? resolveRunsDirectory();
+    this.#cap = options.cap ?? FINISHED_RECORD_CAP;
+  }
+
+  get directory(): string {
+    return this.#directory;
+  }
+
+  /** Queues one record write; later writes for any Run never overtake earlier ones. */
+  save(record: RunRecord): Promise<void> {
+    this.#chain = this.#chain.then(() => this.#write(record));
+    return this.#chain;
+  }
+
+  /** Resolves once every queued write has been attempted. */
+  async settled(): Promise<void> {
+    await this.#chain;
+  }
+
+  /** Every readable record, oldest start first. Unreadable records are skipped. */
+  async load(): Promise<readonly RunRecord[]> {
+    let entries: readonly string[];
+    try {
+      entries = await readdir(this.#directory);
+    } catch {
+      return [];
+    }
+    const records = await Promise.all(
+      entries.filter((entry) => entry.endsWith(".json")).map((entry) => this.#read(entry)),
+    );
+    return records
+      .filter((record): record is RunRecord => record !== null)
+      .sort((left, right) => left.startedAt.localeCompare(right.startedAt));
+  }
+
+  /**
+   * Removes the oldest finished records above the cap. `live`, `orphaned`, and
+   * `interrupted` records are never pruned: they are the only trace of a Run
+   * nobody accounted for.
+   */
+  async prune(): Promise<void> {
+    const finished = (await this.load()).filter((record) => record.state === "finished");
+    const excess = finished.slice(0, Math.max(0, finished.length - this.#cap));
+    await Promise.all(excess.map((record) => this.remove(record.id)));
+  }
+
+  async remove(id: string): Promise<void> {
+    try {
+      await unlink(join(this.#directory, `${id}.json`));
+    } catch {
+      // Already gone, or never written; nothing to report.
+    }
+  }
+
+  async #write(record: RunRecord): Promise<void> {
+    const target = join(this.#directory, `${record.id}.json`);
+    const temp = `${target}.${randomUUID()}.tmp`;
+    try {
+      await mkdir(this.#directory, { recursive: true });
+      await writeFile(temp, JSON.stringify(record), "utf8");
+      await rename(temp, target);
+    } catch {
+      await unlink(temp).catch(() => {});
+    }
+  }
+
+  async #read(entry: string): Promise<RunRecord | null> {
+    try {
+      const value: unknown = JSON.parse(await readFile(join(this.#directory, entry), "utf8"));
+      return isRunRecord(value) ? value : null;
+    } catch {
+      return null;
+    }
+  }
+}

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

@@ -1,6 +1,6 @@
 import { dirname, join } from "node:path";
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { BackgroundWidget } from "./background-widget.ts";
+import type { BackgroundStatus } from "./background-status.ts";
 import { resolveBun } from "./resolve-bun.ts";
 import { resolveCliEntry } from "./resolve-cli.ts";
 import type { RunDetails } from "./run-details.ts";
@@ -40,10 +40,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 +56,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

@@ -4,14 +4,16 @@ import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-age
 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 { mintRunId } from "./run-id.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";
@@ -48,8 +50,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 = [
@@ -88,7 +90,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",
@@ -122,13 +124,12 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
         throw new Error(`yaag_run: no such Orchestration Program: ${file}`);
       }
 
-      const id = registry.mint();
+      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,
@@ -140,33 +141,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),
       });
     },
   };
@@ -195,11 +191,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>(
@@ -221,10 +217,7 @@ 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 {
-  let run: LiveRun;
   const handle = options.start({
     bun: options.bun,
     cli: options.cli,
@@ -233,17 +226,32 @@ function registeredRun(options: {
     record: options.record,
     resume: options.resume,
     onProgress: (summary, event, sequence) => {
-      run.summary = summary;
+      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?.();
     },
   });
-  run = { id: options.id, stop: handle.stop, outcome: handle.outcome, summary: initialSummary() };
-  options.registry.add(run);
+  const run: LiveRun = {
+    id: options.id,
+    stop: handle.stop,
+    outcome: handle.outcome,
+    summary: initialSummary(),
+  };
+  const launch = {
+    file: options.file,
+    ...(options.args === undefined ? {} : { args: options.args }),
+    ...(options.record === undefined ? {} : { record: options.record }),
+    ...(options.resume === undefined ? {} : { resume: options.resume }),
+  };
+  options.registry.add(run, launch, processIdentity(handle.pid));
   return run;
 }
 
+/** A pid alone cannot be trusted after a restart, so its start time goes with it. */
+function processIdentity(pid: number | undefined): ProcessIdentity | null {
+  return pid === undefined ? null : { pid, startedAt: readProcessStart(pid) };
+}
+
 function completionContent(id: string, settlement: RunSettlement): string {
   if (settlement.kind === "rejected") return `Run ${id} failed: ${errorText(settlement.reason)}`;
   const { outcome } = settlement;

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/runs-dir.ts

@@ -0,0 +1,18 @@
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+const RUNS_SUFFIX = join("yaag", "runs");
+
+/**
+ * Resolves where Run records are stored: `YAAG_RUNS_DIR`, then an absolute
+ * `XDG_STATE_HOME`, then `$HOME/.local/state`. A relative `XDG_STATE_HOME` is
+ * ignored (XDG spec). Same conventions as the checkpoint directory (ADR-0021).
+ */
+export function resolveRunsDirectory(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env["YAAG_RUNS_DIR"];
+  if (override !== undefined && override !== "") return override;
+  const xdg = env["XDG_STATE_HOME"];
+  if (xdg !== undefined && isAbsolute(xdg)) return join(xdg, RUNS_SUFFIX);
+  const home = env["HOME"] !== undefined && env["HOME"] !== "" ? env["HOME"] : homedir();
+  return join(home, ".local", "state", RUNS_SUFFIX);
+}