@yaag/extension 0.5.2 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "publishConfig": {
     "access": "public"
   },
@@ -19,14 +19,14 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "for file in src/*.test.ts; do bun test --timeout 30000 \"$file\" || exit 1; done",
+    "test": "for file in src/*/*.test.ts; do bun test --timeout 30000 \"$file\" || exit 1; done",
     "test:e2e": "bun test --timeout 30000 e2e"
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.5.2",
-    "@yaag/runtime": "0.5.2",
-    "@yaag/tui": "0.5.2",
+    "@yaag/cli": "0.6.1",
+    "@yaag/runtime": "0.6.1",
+    "@yaag/tui": "0.6.1",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/index.ts

@@ -1,22 +1,25 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createBackgroundStatus } from "./background-status.ts";
-import { createDescribeTool } from "./describe-tool.ts";
-import { findProgramDirectories } from "./program-directories.ts";
-import { resolveBun } from "./resolve-bun.ts";
-import { resolveCliEntry } from "./resolve-cli.ts";
-import { createRunCompleteRenderer } from "./run-complete-renderer.ts";
-import { RunRegistry } from "./run-registry.ts";
-import { RunStore } from "./run-store.ts";
-import { createRunTool } from "./run-tool.ts";
-import { RunTreeStore } from "./run-trees.ts";
-import { createSetupWorkspaceExecutor } from "./setup-workspace.ts";
-import { createSetupWorkspaceCommand } from "./setup-workspace-command.ts";
-import { createSetupWorkspaceTool } from "./setup-workspace-tool.ts";
-import { statusReport } from "./status.ts";
-import { createStatusTool } from "./status-tool.ts";
-import { createStopTool } from "./stop-tool.ts";
-import { createSystemPromptAppender } from "./system-prompt-append.ts";
-import { createYaagCommand } from "./yaag-command.ts";
+import { resolveBun, resolveCliEntry, statusReport } from "./process/index.ts";
+import { RunRegistry, RunStore } from "./record/index.ts";
+import {
+  createDescribeTool,
+  createRunTool,
+  createStatusTool,
+  createStopTool,
+  createSystemPromptAppender,
+} from "./tool/index.ts";
+import {
+  createBackgroundStatus,
+  createRunCompleteRenderer,
+  createYaagCommand,
+  RunTreeStore,
+} from "./view/index.ts";
+import {
+  createSetupWorkspaceCommand,
+  createSetupWorkspaceExecutor,
+  createSetupWorkspaceTool,
+  findProgramDirectories,
+} from "./workspace/index.ts";
 
 /**
  * The yaag pi extension. Loaded by pi through jiti, in Node — nothing here may
@@ -35,7 +38,6 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   // One registry per session, mirrored to a durable store so a restart of this
   // Host Session keeps every Run id addressable (ticket 02).
   const registry = new RunRegistry({ store: new RunStore() });
-  await registry.restore();
   // 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();
@@ -56,9 +58,13 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   const appendYaagPrompt = createSystemPromptAppender(() => findProgramDirectories(process.cwd()));
   pi.on("before_agent_start", (event) => appendYaagPrompt(event));
 
-  pi.on("session_start", (_event, ctx) => {
+  pi.on("session_start", async (_event, ctx) => {
     if (bun === null) ctx.ui.notify(report, "error");
     if (ctx.hasUI) status.bind(ctx.ui);
+    // The pi session id is knowable only here, and `/resume` rebinds this
+    // extension and fires the same id, which is what re-adopts this session's
+    // Runs. A fork arrives with a new id and adopts nothing (ADR-0036).
+    await registry.restore(ctx.sessionManager.getSessionId());
   });
 
   // Commands and tools have separate namespaces: this CLI-resolution command

package/src/process/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Public surface of the `process/` module: child-process plumbing and the Bun-CLI bridge.
+ * Files inside this directory import each other directly.
+ */
+export {
+  type CliChild,
+  type CliChildOptions,
+  type CliChildOutcome,
+  startCliChild,
+} from "./cli-child.ts";
+export { isProcessAlive, type ProcessIdentity, readProcessStart } from "./process-liveness.ts";
+export { resolveBun } from "./resolve-bun.ts";
+export { resolveCliEntry } from "./resolve-cli.ts";
+export type { ProgramTarget } from "./run-argv.ts";
+export { type RunHandle, type RunOutcome, type StartRunOptions, startRun } from "./spawn-run.ts";
+export { statusReport } from "./status.ts";

package/src/record/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Public surface of the `record/` module: the Run record registry, store, restore, and resume.
+ * Files inside this directory import each other directly.
+ */
+export { resolveProgramParams } from "./resume-source.ts";
+export { mintRunId } from "./run-id.ts";
+export {
+  confirmProgramTarget,
+  type ProgramParams,
+  programExpansion,
+  programLabel,
+  programTarget,
+} from "./run-program-param.ts";
+export type { RunLaunch, RunRecord } from "./run-record.ts";
+export {
+  type DatedRun,
+  type LiveRun,
+  type RegisteredRun,
+  type RestoredRun,
+  RunRegistry,
+  type RunSettlement,
+} from "./run-registry.ts";
+export { errorText, failure, observedSettlement, toError, viewResult } from "./run-settlement.ts";
+export { RunStore } from "./run-store.ts";

package/src/{run-program-param.ts → record/run-program-param.ts}

@@ -1,7 +1,7 @@
 import { access } from "node:fs/promises";
 import { resolve } from "node:path";
 import { clampToWidth, sanitizeTerminalLine, sanitizeTerminalText } from "@yaag/tui";
-import type { ProgramTarget } from "./run-argv.ts";
+import type { ProgramTarget } from "../process/index.ts";
 
 /**
  * The `yaag_run` parameters that name the program; exactly one is given.

package/src/{run-record.ts → record/run-record.ts}

@@ -1,5 +1,5 @@
 import { initialSummary, type RunSummary } from "@yaag/runtime";
-import type { ProcessIdentity } from "./process-liveness.ts";
+import type { ProcessIdentity } from "../process/index.ts";
 import { parseRunSummary } from "./run-summary-parse.ts";
 
 /**
@@ -40,6 +40,12 @@ export type RunLaunch =
 /** One Run as stored on disk, at `<runs dir>/<id>.json`. */
 export interface RunRecord {
   readonly id: string;
+  /**
+   * The pi session that started the Run. `null` for a record an older yaag
+   * wrote, or an unbound registry; such a record belongs to no session
+   * (ADR-0036).
+   */
+  readonly sessionId: string | null;
   readonly launch: RunLaunch;
   readonly process: ProcessIdentity | null;
   readonly startedAt: string;
@@ -81,6 +87,7 @@ export function parseRunRecord(value: unknown): RunRecord | null {
   // field a consumer reads has the type this parser proved (rule 0001 §3).
   return {
     id: candidate["id"],
+    sessionId: typeof candidate["sessionId"] === "string" ? candidate["sessionId"] : null,
     launch,
     process: identity,
     startedAt: candidate["startedAt"],
@@ -97,9 +104,11 @@ export function startedRecord(options: {
   readonly launch: RunLaunch;
   readonly process: ProcessIdentity | null;
   readonly now: string;
+  readonly sessionId?: string | null;
 }): RunRecord {
   return {
     id: options.id,
+    sessionId: options.sessionId ?? null,
     launch: options.launch,
     process: options.process,
     startedAt: options.now,

package/src/{run-registry.ts → record/run-registry.ts}

@@ -1,10 +1,9 @@
 import type { EndedRunSummary, RunSummary } from "@yaag/runtime";
-import type { ProcessIdentity } from "./process-liveness.ts";
+import type { ProcessIdentity, RunOutcome } from "../process/index.ts";
 import { pickInlineResumeSource } from "./resume-source.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";
 
@@ -44,6 +43,12 @@ export type RegisteredRun =
 /** What the registry knows about an id. */
 export type RunStatus = RegisteredRun | { readonly state: "unknown" };
 
+/** A registered Run plus the start instant that orders a bounded listing. */
+export interface DatedRun {
+  readonly startedAt: string;
+  readonly entry: RegisteredRun;
+}
+
 /** How often a Run's latest Summary is persisted while it runs. */
 export const SUMMARY_WRITE_INTERVAL_MS = 2_000;
 
@@ -67,8 +72,11 @@ export class RunRegistry {
   readonly #records = new Map<string, RunRecord>();
   readonly #lastWrite = new Map<string, number>();
   readonly #trailing = new Map<string, ReturnType<typeof setTimeout>>();
+  readonly #startedAt = new Map<string, string>();
   readonly #store: RunStore | undefined;
   readonly #now: () => Date;
+  #sessionId: string | null = null;
+  #restoredFor: string | null | undefined = undefined;
 
   constructor(options: RunRegistryOptions = {}) {
     this.#store = options.store;
@@ -90,25 +98,72 @@ export class RunRegistry {
     return [...this.#runs.keys()];
   }
 
+  /** Every addressable Run with its start instant, in registration order. */
+  get datedRuns(): readonly DatedRun[] {
+    return [...this.#runs.entries()].map(([id, entry]) => ({
+      startedAt: this.#startedAt.get(id) ?? "",
+      entry,
+    }));
+  }
+
   /**
-   * 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.
+   * Binds this Host Session's pi session id, settles the Runs an earlier
+   * session left `live`, and adopts the ones this session owns (ADR-0036).
+   *
+   * Idempotent per session id: a second `session_start` with the same id (a
+   * `/reload`) adopts nothing again. A fork carries a new id and therefore
+   * adopts nothing; the parent's Runs stay reachable through {@link recall}.
    */
-  async restore(): Promise<void> {
+  async restore(sessionId?: string): Promise<void> {
+    const bound = sessionId ?? null;
+    if (this.#restoredFor === bound) return;
+    this.#sessionId = bound;
+    this.#restoredFor = bound;
     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;
+      // A Run of this process is never shadowed by its own persisted record.
+      if (this.#runs.has(record.id)) continue;
+      if (!this.#adoptable(record)) continue;
       this.#runs.set(record.id, { state: "restored", run: restored(record) });
+      this.#startedAt.set(record.id, record.startedAt);
     }
   }
 
+  /** Persisted Runs this overview does not list; addressable by id only. */
+  async unlistedRunCount(listed: readonly string[]): Promise<number> {
+    if (this.#store === undefined) return 0;
+    const shown = new Set(listed);
+    return (await this.#store.load()).filter((record) => !shown.has(record.id)).length;
+  }
+
+  /** Persisted finished Runs that another pi session owns. */
+  async finishedElsewhereCount(): Promise<number> {
+    if (this.#store === undefined) return 0;
+    return (await this.#store.load()).filter(
+      (record) =>
+        record.state === "finished" &&
+        (this.#sessionId === null || record.sessionId !== this.#sessionId),
+    ).length;
+  }
+
+  /**
+   * `restoreRecords` already settled every stale `live` record, so this check
+   * can never adopt a Run as live (ADR-0036).
+   */
+  #adoptable(record: RunRecord): boolean {
+    if (record.state === "orphaned" || record.state === "interrupted") return true;
+    return this.#sessionId !== null && record.sessionId === this.#sessionId;
+  }
+
   /** Registers a newly-started Run and synchronously observes its settlement. */
   add(run: LiveRun, launch?: RunLaunch, identity?: ProcessIdentity | null): void {
+    const startedAt = this.#now().toISOString();
+    this.#startedAt.set(run.id, startedAt);
     this.#live.set(run.id, run);
     this.#runs.set(run.id, { state: "live", run });
-    if (launch !== undefined) this.#persistStart(run.id, launch, identity ?? null);
+    if (launch !== undefined)
+      this.#persistStart({ id: run.id, launch, process: identity ?? null, now: startedAt });
     void run.outcome.then(
       (outcome) => this.finish(run.id, outcome),
       (reason: unknown) => this.reject(run.id, reason),
@@ -203,13 +258,16 @@ export class RunRegistry {
     this.#persistEnd(id, summary, outcome);
   }
 
-  #persistStart(id: string, launch: RunLaunch, identity: ProcessIdentity | null): void {
+  #persistStart(options: {
+    readonly id: string;
+    readonly launch: RunLaunch;
+    readonly process: ProcessIdentity | null;
+    readonly now: string;
+  }): void {
     if (this.#store === undefined) return;
     const store = this.#store;
-    this.#records.set(
-      id,
-      startedRecord({ id, launch, process: identity, now: this.#now().toISOString() }),
-    );
+    const id = options.id;
+    this.#records.set(id, startedRecord({ ...options, sessionId: this.#sessionId }));
     this.#persist(id);
     void store.prune();
   }

package/src/{run-restore.ts → record/run-restore.ts}

@@ -1,4 +1,4 @@
-import { isProcessAlive, type ProcessIdentity } from "./process-liveness.ts";
+import { isProcessAlive, type ProcessIdentity } from "../process/index.ts";
 import type { RunRecord } from "./run-record.ts";
 import type { RunStore } from "./run-store.ts";
 

package/src/{run-settlement.ts → record/run-settlement.ts}

@@ -3,8 +3,8 @@
  * the blocking, interactive, and background paths of `yaag_run`.
  */
 import type { RunViewResult } from "@yaag/tui";
+import type { RunOutcome } from "../process/index.ts";
 import type { RunRegistry, RunSettlement } from "./run-registry.ts";
-import type { RunOutcome } from "./spawn-run.ts";
 
 /**
  * The settlement the registry retained for a Run.

package/src/{fake-run-start.ts → testing/fake-run-start.ts}

@@ -1,5 +1,5 @@
 import { initialSummary } from "@yaag/runtime";
-import type { RunHandle, StartRunOptions } from "./spawn-run.ts";
+import type { RunHandle, StartRunOptions } from "../process/index.ts";
 
 /** A start seam that never spawns: it captures its options and ends the Run at once. */
 export function fakeStart(stdout = "{}"): {

package/src/testing/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Public surface of the `testing/` module: package-spanning test helpers and fakes.
+ * Files inside this directory import each other directly.
+ */
+export { fakeStart } from "./fake-run-start.ts";
+export { loadPiKeybindings } from "./pi-keybindings.ts";
+export { renderCallLabel, renderCallLines } from "./run-call-render.ts";
+export {
+  asError,
+  fixture,
+  run,
+  running,
+  type Sent,
+  stop,
+  toolDescription,
+  until,
+} from "./run-tool-test-support.ts";
+export { TestExtensionContext } from "./test-extension-context.ts";
+export { TestTuiContext } from "./test-tui-context.ts";

package/src/{run-call-render.ts → testing/run-call-render.ts}

@@ -1,9 +1,8 @@
 import { stripTerminalSequences } from "@earendil-works/pi-tui";
+import { resolveBun, resolveCliEntry } from "../process/index.ts";
+import { RunRegistry } from "../record/index.ts";
+import { createRunTool } from "../tool/index.ts";
 import { fakeTheme } from "./fake-theme.ts";
-import { resolveBun } from "./resolve-bun.ts";
-import { resolveCliEntry } from "./resolve-cli.ts";
-import { RunRegistry } from "./run-registry.ts";
-import { createRunTool } from "./run-tool.ts";
 
 const cli = resolveCliEntry();
 const bun = await resolveBun();

package/src/{run-tool-test-support.ts → testing/run-tool-test-support.ts}

@@ -1,15 +1,16 @@
 import { dirname, join } from "node:path";
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { BackgroundStatus } from "./background-status.ts";
-import { resolveBun } from "./resolve-bun.ts";
-import { resolveCliEntry } from "./resolve-cli.ts";
+import type { RunHandle } from "../process/index.ts";
+import { resolveBun, resolveCliEntry } from "../process/index.ts";
+import { RunRegistry } from "../record/index.ts";
+import {
+  createRunTool,
+  createStopTool,
+  type SendMessage,
+  type StopDetails,
+} from "../tool/index.ts";
+import type { BackgroundStatus, RunDetails, RunTreeStore } from "../view/index.ts";
 import type { RunParams } from "./run-call-render.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();
@@ -34,7 +35,7 @@ export async function run(
     readonly onUpdate?: (partial: AgentToolResult<RunDetails>) => void;
     readonly registry?: RunRegistry;
     readonly sent?: Sent[];
-    readonly start?: (options: import("./spawn-run.ts").StartRunOptions) => RunHandle;
+    readonly start?: (options: import("../process/index.ts").StartRunOptions) => RunHandle;
     /** A tui-mode context, for the inline foreground path. */
     readonly ctx?: ExtensionContext;
     readonly store?: RunTreeStore;

package/src/{describe-tool.ts → tool/describe-tool.ts}

@@ -1,8 +1,7 @@
 import { resolve } from "node:path";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { startCliChild } from "./cli-child.ts";
-import { statusReport } from "./status.ts";
+import { startCliChild, statusReport } from "../process/index.ts";
 
 const parameters = Type.Object({
   file: Type.String({ description: "Path to the Orchestration Program file" }),

package/src/tool/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Public surface of the `tool/` module: the pi tools the extension registers.
+ * Files inside this directory import each other directly.
+ */
+export { createDescribeTool } from "./describe-tool.ts";
+export { createRunTool, type RunDetails, type SendMessage } from "./run-tool.ts";
+export { createStatusTool } from "./status-tool.ts";
+export { createStopTool, type StopDetails } from "./stop-tool.ts";
+export { createSystemPromptAppender } from "./system-prompt-append.ts";

package/src/{run-tool.ts → tool/run-tool.ts}

@@ -3,25 +3,40 @@ 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 BackgroundStatus, createBackgroundStatus } from "./background-status.ts";
-import { callBody } from "./run-call-body.ts";
-import type { RunDetails } from "./run-details.ts";
-import { foregroundInline, foregroundResult, inlineAvailable } from "./run-foreground.ts";
-import { RunTreeComponent } from "./run-tree-component.ts";
-import { RunTreeStore } from "./run-trees.ts";
+import type { RunDetails } from "../view/index.ts";
+import {
+  type BackgroundStatus,
+  callBody,
+  createBackgroundStatus,
+  foregroundInline,
+  foregroundResult,
+  inlineAvailable,
+  RunTreeComponent,
+  RunTreeStore,
+} from "../view/index.ts";
 
-export type { RunDetails } from "./run-details.ts";
+export type { RunDetails } from "../view/index.ts";
 
-import { type ProcessIdentity, readProcessStart } from "./process-liveness.ts";
-import { resolveProgramParams } from "./resume-source.ts";
-import type { ProgramTarget } from "./run-argv.ts";
-import { mintRunId } from "./run-id.ts";
-import { confirmProgramTarget, programTarget } from "./run-program-param.ts";
-import type { RunLaunch } from "./run-record.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";
+import type { ProgramTarget } from "../process/index.ts";
+import {
+  type ProcessIdentity,
+  type RunHandle,
+  type RunOutcome,
+  readProcessStart,
+  type StartRunOptions,
+  startRun,
+  statusReport,
+} from "../process/index.ts";
+import type { LiveRun, RunLaunch, RunRegistry, RunSettlement } from "../record/index.ts";
+import {
+  confirmProgramTarget,
+  errorText,
+  failure,
+  mintRunId,
+  observedSettlement,
+  programTarget,
+  resolveProgramParams,
+} from "../record/index.ts";
 
 const parameters = Type.Object({
   file: Type.Optional(

package/src/{status-tool.ts → tool/status-tool.ts}

@@ -2,9 +2,8 @@ import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-
 import type { RunSummary } from "@yaag/runtime";
 import { renderSnapshot, TreeState } from "@yaag/tui";
 import { Type } from "typebox";
-import type { RunRecord } from "./run-record.ts";
-import type { RegisteredRun, RestoredRun, RunRegistry } from "./run-registry.ts";
-import { toUsage } from "./usage.ts";
+import type { RegisteredRun, RestoredRun, RunRegistry } from "../record/index.ts";
+import { boundedRuns, RUN_LISTING_CAP, restoredStateText, toUsage } from "../view/index.ts";
 
 const parameters = Type.Object({
   id: Type.Optional(Type.String({ description: "The Run id returned by yaag_run (e.g. r1)" })),
@@ -33,18 +32,22 @@ const DESCRIPTION = [
   "resolves: a Run whose process died is reported as interrupted, and a Run whose",
   "process is still alive is reported as orphaned.",
   "",
-  "Without an id, lists this session's Runs plus every orphaned or interrupted",
-  "Run left by an earlier session.",
+  "Without an id, this tool lists the Runs of this session, and the orphaned or",
+  "interrupted Runs another session left. The list is bounded: it holds every",
+  `live Run, and then the newest Runs up to a total of ${RUN_LISTING_CAP}. An older Run stays`,
+  "on disk, and the last line of the list counts the Runs on disk. Give an id to",
+  "see one of them.",
   "",
   "An interrupted inline Run resumes with `resume` alone: yaag reads the program",
   "source from its own Run record.",
 ].join("\n");
 
 /**
- * The `yaag_status` tool renders session-local Run snapshots for the model.
+ * The `yaag_status` tool renders Run snapshots for the model.
  *
- * Throws if an id was not started in this session; finished Runs remain
- * queryable and are never restarted or controlled by this tool.
+ * An id resolves through {@link RunRegistry.recall}, so a Run of any session is
+ * queryable while its record is on disk; only an id no record holds throws.
+ * The tool never restarts or controls a Run.
  */
 export function createStatusTool(
   registry: RunRegistry,
@@ -58,7 +61,7 @@ export function createStatusTool(
     description: DESCRIPTION,
     parameters,
     async execute(_id, params) {
-      if (params.id === undefined) return overview(registry.runs, now, width);
+      if (params.id === undefined) return await overview(registry, now, width);
       const found = await registry.recall(params.id);
       if (found.state === "unknown") throw unknownId(params.id, registry.knownIds);
       const details = detailsFor(found);
@@ -71,25 +74,40 @@ export function createStatusTool(
   };
 }
 
-function overview(
-  runs: readonly RegisteredRun[],
+/**
+ * Lists the Runs of this session, bounded by {@link RUN_LISTING_CAP}.
+ *
+ * The disk counts are read on each call: the store holds dozens of small files
+ * and a stale count would name Runs that no longer exist (ADR-0036).
+ */
+async function overview(
+  registry: RunRegistry,
   now: () => number,
   width: number,
-): AgentToolResult<StatusDetails> {
-  if (runs.length === 0)
-    return {
-      content: [{ type: "text", text: "No Runs started this session." }],
-      details: { summary: undefined },
-    };
-  return {
-    content: [
-      {
-        type: "text",
-        text: runs.map((run) => snapshot(detailsFor(run), now, width, true)).join("\n"),
-      },
-    ],
-    details: { summary: undefined },
-  };
+): Promise<AgentToolResult<StatusDetails>> {
+  const shown = boundedRuns(registry.datedRuns);
+  if (shown.length === 0) return text(emptyOverview(await registry.finishedElsewhereCount()));
+  const lines = shown.map((run) => snapshot(detailsFor(run), now, width, true));
+  const unlisted = await registry.unlistedRunCount(shown.map((run) => run.run.id));
+  if (unlisted > 0) lines.push(overflowLine(shown.length, unlisted));
+  return text(lines.join("\n"));
+}
+
+function text(value: string): AgentToolResult<StatusDetails> {
+  return { content: [{ type: "text", text: value }], details: { summary: undefined } };
+}
+
+/** The confirmed empty-overview copy of the specification, with its count. */
+function emptyOverview(elsewhere: number): string {
+  if (elsewhere === 0) return "No Runs in this session.";
+  const runs = elsewhere === 1 ? "Run" : "Runs";
+  const verb = elsewhere === 1 ? "is" : "are";
+  return `No Runs in this session. ${elsewhere} finished ${runs} from other sessions ${verb} on disk; query one with yaag_status({ id }).`;
+}
+
+/** The confirmed overflow copy of the specification, with its two counts. */
+function overflowLine(shown: number, unlisted: number): string {
+  return `${shown} shown; ${unlisted} more on disk \u2014 query one with yaag_status({ id })`;
 }
 
 function detailsFor(run: RegisteredRun): SnapshotDetails {
@@ -106,51 +124,19 @@ function detailsFor(run: RegisteredRun): SnapshotDetails {
 }
 
 /**
- * A Run of an earlier Host Session. Its persisted state is stated in the
- * Result region, because the folded Summary alone cannot say that nobody owns
- * the Run any more (ticket 02).
+ * A Run read back from its record: this session may own it again, but nothing
+ * is attached to it. Its persisted state is stated in the Result region,
+ * because the folded Summary alone cannot say that the snapshot is final and
+ * that no process feeds it (ticket 02, ADR-0036).
  */
 function restoredDetails(run: RestoredRun): SnapshotDetails {
   const { record } = run;
-  const state = `Run ${record.id} is ${record.state} (started ${record.startedAt}).`;
-  const alive =
-    record.state === "orphaned" && record.process !== null
-      ? ` Its process ${record.process.pid} is still running; stop it with yaag_stop.`
-      : "";
-  const detail = `${alive}${resumeHint(record)}`;
   const result = record.outcome?.kind === "fulfilled" ? `\n${record.outcome.result}` : "";
-  return { id: record.id, summary: run.summary, result: `${state}${detail}${result}` };
-}
-
-/**
- * Names the Checkpoint an unowned Run left behind (ADR-0031), and the call that
- * resumes it. The Run republishes the Checkpoint at each Ask boundary, so it
- * exists whenever the Run reached one, for a dead Run and for a still-running
- * orphan alike.
- *
- * The hint names the Checkpoint path and never the stored program source: the
- * path is enough, because yaag reads the source back from the Run record
- * (ADR-0033). A whole source here would flood the transcript and repeat a
- * private text the record already holds.
- */
-function resumeHint(record: RunRecord): string {
-  const artifact = record.summary.artifact;
-  if (artifact === null || artifact === undefined) return "";
-  if (record.state !== "interrupted" && record.state !== "orphaned") return "";
-  // Each path becomes a JSON string literal: a path can hold a quote, a
-  // backslash, or a newline, and the hint must stay a call the model can copy.
-  const resume = JSON.stringify(artifact);
-  const { launch } = record;
-  switch (launch.kind) {
-    case "inline":
-      return ` Resume it with yaag_run({ resume: ${resume} }) and no file and no script; yaag reuses the program source it stored.`;
-    case "file":
-      return ` Resume it with yaag_run({ file: ${JSON.stringify(launch.file)}, resume: ${resume} }).`;
-    default: {
-      const never: never = launch;
-      return never;
-    }
-  }
+  return {
+    id: record.id,
+    summary: run.summary,
+    result: `${restoredStateText(record)}${result}`,
+  };
 }
 
 function snapshot(

package/src/{stop-tool.ts → tool/stop-tool.ts}

@@ -1,9 +1,9 @@
 import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { RunSummary } from "@yaag/runtime";
 import { Type } from "typebox";
-import { isProcessAlive } from "./process-liveness.ts";
-import type { RestoredRun, RunRegistry } from "./run-registry.ts";
-import { toUsage } from "./usage.ts";
+import { isProcessAlive } from "../process/index.ts";
+import type { RestoredRun, RunRegistry } from "../record/index.ts";
+import { toUsage } from "../view/index.ts";
 
 /** What the stop result carries for rendering — never shown to the model. */
 export interface StopDetails {
@@ -67,8 +67,8 @@ function agentStateReport(agent: RunSummary["agents"][string]): string {
 }
 
 /**
- * Ends a Run nobody owns any more. There is no reap ladder to run — its pipes
- * belong to a dead Host Session — so the process group is killed outright
+ * Ends a Run no process is attached to. There is no reap ladder to run — its
+ * pipes belong to a dead Host Session — so the process group is killed outright
  * (ADR-0008). The pid is re-probed first, because a record can name a pid that
  * a different process has since inherited (ticket 02).
  */

package/src/{background-status.ts → view/background-status.ts}

@@ -7,7 +7,7 @@
  * as the last background Run ends.
  */
 import { costText } from "@yaag/tui";
-import type { RunRegistry } from "./run-registry.ts";
+import type { RunRegistry } from "../record/index.ts";
 import type { RunTreeStore } from "./run-trees.ts";
 
 /** The one footer key this extension owns. */

package/src/view/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Public surface of the `view/` module: TUI views, renderers, and the /yaag command.
+ * Files inside this directory import each other directly.
+ */
+export {
+  type BackgroundStatus,
+  createBackgroundStatus,
+  STATUS_KEY,
+  type StatusSurface,
+} from "./background-status.ts";
+export { restoredStateText } from "./restored-run-text.ts";
+export { callBody } from "./run-call-body.ts";
+export { createRunCompleteRenderer } from "./run-complete-renderer.ts";
+export type { RunDetails } from "./run-details.ts";
+export {
+  foregroundInline,
+  foregroundResult,
+  foregroundWidgetKey,
+  inlineAvailable,
+} from "./run-foreground.ts";
+export { boundedRuns, RUN_LISTING_CAP } from "./run-listing.ts";
+export { RunTreeComponent } from "./run-tree-component.ts";
+export { RunTreeStore } from "./run-trees.ts";
+export { toUsage } from "./usage.ts";
+export { createYaagCommand } from "./yaag-command.ts";

package/src/view/restored-run-text.ts

@@ -0,0 +1,77 @@
+/**
+ * The words a Run read back from its record gets, shared by `yaag_status` and
+ * the `/yaag` snapshot view (ADR-0036). A resumed session owns such a Run again
+ * when the record names it, but no session is attached to it: there is no event
+ * stream and no renderer projection, only the persisted Summary. Pure text, no
+ * I/O.
+ */
+import type { RunViewResult } from "@yaag/tui";
+import type { RunRecord } from "../record/index.ts";
+
+/**
+ * States the persisted verdict of a Run that no process is attached to.
+ *
+ * The folded Summary alone cannot say that the Run stopped without an owner
+ * process, or that a Checkpoint of it can be resumed (ticket 02), so the state,
+ * the surviving process, and the resume call are stated here.
+ */
+export function restoredStateText(record: RunRecord): string {
+  const state = `Run ${record.id} is ${record.state} (started ${record.startedAt}).`;
+  const alive =
+    record.state === "orphaned" && record.process !== null
+      ? ` Its process ${record.process.pid} is still running; stop it with yaag_stop.`
+      : "";
+  return `${state}${alive}${resumeHint(record)}`;
+}
+
+/**
+ * The frozen Result region of a restored Run, for the read-only `/yaag` view.
+ *
+ * Every restored Run states its persisted verdict first, whatever its outcome:
+ * the reader opened a snapshot of a record, which no live Run feeds any more,
+ * and the value or the error alone does not say so (ADR-0036).
+ */
+export function restoredViewResult(record: RunRecord): RunViewResult {
+  const state = restoredStateText(record);
+  const { outcome } = record;
+  if (outcome?.kind === "fulfilled")
+    return { kind: "fulfilled", result: joinText(state, outcome.result) };
+  if (outcome?.kind === "rejected")
+    return { kind: "failed", error: joinText(state, outcome.reason) };
+  return { kind: "failed", error: state };
+}
+
+function joinText(state: string, detail: string): string {
+  return detail.trim() === "" ? state : `${state}\n${detail}`;
+}
+
+/**
+ * Names the Checkpoint an unowned Run left behind (ADR-0031), and the call that
+ * resumes it. The Run republishes the Checkpoint at each Ask boundary, so it
+ * exists whenever the Run reached one, for a dead Run and for a still-running
+ * orphan alike.
+ *
+ * The hint names the Checkpoint path and never the stored program source: the
+ * path is enough, because yaag reads the source back from the Run record
+ * (ADR-0033). A whole source here would flood the transcript and repeat a
+ * private text the record already holds.
+ */
+function resumeHint(record: RunRecord): string {
+  const artifact = record.summary.artifact;
+  if (artifact === null || artifact === undefined) return "";
+  if (record.state !== "interrupted" && record.state !== "orphaned") return "";
+  // Each path becomes a JSON string literal: a path can hold a quote, a
+  // backslash, or a newline, and the hint must stay a call the model can copy.
+  const resume = JSON.stringify(artifact);
+  const { launch } = record;
+  switch (launch.kind) {
+    case "inline":
+      return ` Resume it with yaag_run({ resume: ${resume} }) and no file and no script; yaag reuses the program source it stored.`;
+    case "file":
+      return ` Resume it with yaag_run({ file: ${JSON.stringify(launch.file)}, resume: ${resume} }).`;
+    default: {
+      const never: never = launch;
+      return never;
+    }
+  }
+}

package/src/{run-call-body.ts → view/run-call-body.ts}

@@ -4,7 +4,7 @@
  * which shows that source.
  */
 import { keyText, type Theme } from "@earendil-works/pi-coding-agent";
-import { type ProgramParams, programExpansion, programLabel } from "./run-program-param.ts";
+import { type ProgramParams, programExpansion, programLabel } from "../record/index.ts";
 
 /** What the call render needs: the call itself, its styling, and its state. */
 export interface CallBodyOptions {

package/src/{run-foreground.ts → view/run-foreground.ts}

@@ -8,9 +8,9 @@
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { renderInlineRun, type TreeState } from "@yaag/tui";
+import type { LiveRun, RunRegistry, RunSettlement } from "../record/index.ts";
+import { failure, observedSettlement, toError } from "../record/index.ts";
 import type { RunDetails } from "./run-details.ts";
-import type { LiveRun, RunRegistry, RunSettlement } from "./run-registry.ts";
-import { failure, observedSettlement, toError } from "./run-settlement.ts";
 import type { RunTreeStore } from "./run-trees.ts";
 import { toUsage } from "./usage.ts";
 

package/src/view/run-listing.ts

@@ -0,0 +1,33 @@
+/**
+ * The one bound both Run listings share: the `/yaag` picker and the
+ * `yaag_status` overview must agree on which Runs exist (ADR-0036).
+ */
+import type { DatedRun, RegisteredRun } from "../record/index.ts";
+
+/** How many Runs the `/yaag` picker and the `yaag_status` overview list. */
+export const RUN_LISTING_CAP = 5;
+
+/**
+ * The newest `cap` Runs, newest first, plus every live Run whatever its age.
+ *
+ * A live Run is exempt from the cap: the session must always see and stop what
+ * it runs (ADR-0036). Runs that start at the same instant keep registration
+ * order.
+ */
+export function boundedRuns(
+  runs: readonly DatedRun[],
+  cap: number = RUN_LISTING_CAP,
+): readonly RegisteredRun[] {
+  const newestFirst = [...runs.entries()].sort(compareNewestFirst).map(([, run]) => run);
+  return newestFirst
+    .filter((run, rank) => rank < cap || run.entry.state === "live")
+    .map((run) => run.entry);
+}
+
+function compareNewestFirst(
+  left: readonly [number, DatedRun],
+  right: readonly [number, DatedRun],
+): number {
+  if (left[1].startedAt === right[1].startedAt) return left[0] - right[0];
+  return left[1].startedAt < right[1].startedAt ? 1 : -1;
+}

package/src/{run-picker.ts → view/run-picker.ts}

@@ -3,21 +3,28 @@
  * the list can be tested without a live UI.
  */
 import type { RunSummary } from "@yaag/runtime";
-import type { RegisteredRun } from "./run-registry.ts";
+import type { DatedRun } from "../record/index.ts";
+import { boundedRuns } from "./run-listing.ts";
 
 /** One Run the picker can open: its id, latest Summary fold, and liveness. */
 export interface PickableRun {
   readonly id: string;
   readonly summary: RunSummary;
   readonly live: boolean;
+  /** A Run an earlier session started; the view of it is a frozen snapshot. */
+  readonly restored: boolean;
 }
 
-/** Every registered Run, live and finished, in registration order. */
-export function pickableRuns(runs: readonly RegisteredRun[]): readonly PickableRun[] {
-  return runs.map((run) => ({
+/**
+ * The Runs the picker lists: the bounded listing the `yaag_status` overview
+ * uses, so both surfaces agree on which Runs exist (ADR-0036).
+ */
+export function pickableRuns(runs: readonly DatedRun[]): readonly PickableRun[] {
+  return boundedRuns(runs).map((run) => ({
     id: run.run.id,
     summary: run.run.summary,
     live: run.state === "live",
+    restored: run.state === "restored",
   }));
 }
 

package/src/{yaag-command.ts → view/yaag-command.ts}

@@ -14,9 +14,10 @@ import type {
   RegisteredCommand,
 } from "@earendil-works/pi-coding-agent";
 import { createRunTreeView, type RunTreeViewHost, type RunViewResult, TreeState } from "@yaag/tui";
+import type { RunRegistry, RunSettlement } from "../record/index.ts";
+import { observedSettlement, viewResult } from "../record/index.ts";
+import { restoredViewResult } from "./restored-run-text.ts";
 import { type PickableRun, pickableRuns, runFromLabel, runPickerLabel } from "./run-picker.ts";
-import type { RunRegistry, RunSettlement } from "./run-registry.ts";
-import { observedSettlement, viewResult } from "./run-settlement.ts";
 import { createRunTreeHost } from "./run-tree-host.ts";
 import type { RunTreeStore } from "./run-trees.ts";
 
@@ -53,9 +54,9 @@ export function createYaagCommand(options: YaagCommandOptions): CommandOptions {
  * not the TUI, or when the reader cancels the picker.
  */
 export async function runYaagCommand(ctx: YaagContext, options: YaagCommandOptions): Promise<void> {
-  const runs = pickableRuns(options.registry.runs);
+  const runs = pickableRuns(options.registry.datedRuns);
   if (runs.length === 0) {
-    ctx.ui.notify("yaag: no Runs started this session.", "info");
+    ctx.ui.notify("yaag: no Runs in this session.", "info");
     return;
   }
   if (ctx.mode !== "tui") {
@@ -87,8 +88,13 @@ async function openRun(
   run: PickableRun,
   options: YaagCommandOptions,
 ): Promise<void> {
-  const state = options.store.get(run.id) ?? TreeState.fromSummary(run.summary);
   const found = options.registry.lookup(run.id);
+  // A Run of an earlier session has no projection here, so its view is built
+  // from the persisted Summary alone (ADR-0036).
+  const state =
+    found.state === "restored"
+      ? TreeState.fromSummary(run.summary)
+      : (options.store.get(run.id) ?? TreeState.fromSummary(run.summary));
   let unsubscribe: (() => void) | undefined;
   // The observer below outlives no more than the `ctx.ui.custom()` call: once
   // the view exits or the UI call rejects, a later settlement must touch
@@ -98,6 +104,8 @@ async function openRun(
     await ctx.ui.custom<void>((tui, _theme, keybindings, done) => {
       const host: RunTreeViewHost = {
         ...createRunTreeHost({ ui: ctx.ui, tui, keybindings, state }),
+        // A restored orphan is never re-attached, so there is nothing to stop
+        // from here; `yaag_stop` ends it (ADR-0036).
         stop: () => {
           if (found.state === "live") found.run.stop();
         },
@@ -105,8 +113,13 @@ async function openRun(
         // hand over, because a Run of this session is already addressable.
         done: () => done(),
       };
-      const view = createRunTreeView({ state, host, label: run.id });
-      if (found.state === "finished")
+      const view = createRunTreeView({
+        state,
+        host,
+        label: found.state === "restored" ? `${run.id} (restored)` : run.id,
+      });
+      if (found.state === "restored") view.settle(restoredViewResult(found.run.record));
+      else if (found.state === "finished")
         settle(state, view, found.run.outcome, options.registry, run.id);
       else if (found.state === "live") {
         unsubscribe = options.store.subscribe((id) => {

package/src/workspace/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public surface of the `workspace/` module: workspace setup and Program Directory discovery.
+ * Files inside this directory import each other directly.
+ */
+export { findProgramDirectories } from "./program-directories.ts";
+export { createSetupWorkspaceExecutor } from "./setup-workspace.ts";
+export { createSetupWorkspaceCommand } from "./setup-workspace-command.ts";
+export { createSetupWorkspaceTool } from "./setup-workspace-tool.ts";

package/src/{setup-workspace.ts → workspace/setup-workspace.ts}

@@ -1,5 +1,9 @@
-import { type CliChild, type CliChildOptions, startCliChild } from "./cli-child.ts";
-import { statusReport } from "./status.ts";
+import {
+  type CliChild,
+  type CliChildOptions,
+  startCliChild,
+  statusReport,
+} from "../process/index.ts";
 
 /** Injectable boundary for starting the Bun CLI child. */
 export type StartCliChild = (options: CliChildOptions) => CliChild;