@yaag/extension 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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.6.0",
-    "@yaag/runtime": "0.6.0",
-    "@yaag/tui": "0.6.0",
+    "@yaag/cli": "0.6.2",
+    "@yaag/runtime": "0.6.2",
+    "@yaag/tui": "0.6.2",
     "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

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";
 
 /**

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

@@ -1,10 +1,10 @@
-import type { EndedRunSummary, RunSummary } from "@yaag/runtime";
-import type { ProcessIdentity } from "./process-liveness.ts";
+import type { RunSummary, RunOutcome as SummaryOutcome } from "@yaag/runtime";
+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 { failedSummary, settledRecord } from "./run-settle-record.ts";
 import type { RunStore } from "./run-store.ts";
-import type { RunOutcome } from "./spawn-run.ts";
 
 export type { RunLaunch } from "./run-record.ts";
 
@@ -149,8 +149,30 @@ export class RunRegistry {
   }
 
   /**
-   * `restoreRecords` already settled every stale `live` record, so this check
-   * can never adopt a Run as live (ADR-0036).
+   * Persists the settled form of a Run read back from disk, and refreshes the
+   * retained entry so the next snapshot of this session shows the verdict.
+   *
+   * Only a `restored` Run settles here: a live Run settles through its own
+   * outcome, and a finished Run is history (ADR-0036), so either is refused
+   * rather than written over. A Run this session never listed stays unlisted —
+   * it is written, but not adopted.
+   */
+  async settleRestored(record: RunRecord, outcome: SummaryOutcome): Promise<RestoredRun> {
+    const known = this.#runs.get(record.id);
+    if (known !== undefined && known.state !== "restored")
+      throw new Error(`RunRegistry: Run ${record.id} is ${known.state}, not a restored Run`);
+    const settled = settledRecord({ record, outcome, now: this.#now() });
+    this.#records.set(settled.id, settled);
+    if (known !== undefined)
+      this.#runs.set(settled.id, { state: "restored", run: restored(settled) });
+    await this.#store?.save(settled);
+    return restored(settled);
+  }
+
+  /**
+   * `restoreRecords` already settled every stale `live` record, and every
+   * `orphaned` record whose process is gone, 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;
@@ -229,7 +251,10 @@ export class RunRegistry {
   reject(id: string, reason: unknown): void {
     const record = this.#runs.get(id);
     if (record === undefined || record.state !== "live") return;
-    this.#settle(id, failedSummary(record.run.summary), { kind: "rejected", reason });
+    this.#settle(id, failedSummary(record.run.summary, this.#now().getTime()), {
+      kind: "rejected",
+      reason,
+    });
   }
 
   /**
@@ -311,9 +336,3 @@ function persistedOutcome(outcome: RunSettlement): RunRecord["outcome"] {
 function errorMessage(reason: unknown): string {
   return reason instanceof Error ? reason.message : String(reason);
 }
-
-function failedSummary(summary: RunSummary): EndedRunSummary {
-  if (summary.runState === "ended")
-    return summary.ok ? { ...summary, outcome: "failed", ok: false } : summary;
-  return { ...summary, runState: "ended", outcome: "failed", ok: false, endedAt: null };
-}

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

@@ -1,5 +1,6 @@
-import { isProcessAlive, type ProcessIdentity } from "./process-liveness.ts";
+import { isProcessAlive, type ProcessIdentity } from "../process/index.ts";
 import type { RunRecord } from "./run-record.ts";
+import { settledRecord } from "./run-settle-record.ts";
 import type { RunStore } from "./run-store.ts";
 
 /** Decides whether the process a record names is still running. */
@@ -19,6 +20,11 @@ export interface RestoreOptions {
  * 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).
+ *
+ * An `orphaned` record is probed again: its child can have ended since the
+ * session that orphaned it, and a dead one settles to `interrupted` with an end
+ * instant and an ended Summary. An orphan that still runs is left as it is, so
+ * a session start does not rewrite every record.
  */
 export async function restoreRecords(options: RestoreOptions): Promise<readonly RunRecord[]> {
   const isAlive = options.isAlive ?? isProcessAlive;
@@ -33,11 +39,12 @@ async function settleStale(
   now: () => Date,
   store: RunStore,
 ): Promise<RunRecord> {
-  if (record.state !== "live") return record;
+  if (record.state !== "live" && record.state !== "orphaned") return record;
   const alive = record.process !== null && isAlive(record.process);
+  if (alive && record.state === "orphaned") return record;
   const settled: RunRecord = alive
     ? { ...record, state: "orphaned" }
-    : { ...record, state: "interrupted", endedAt: now().toISOString() };
+    : settledRecord({ record, outcome: "interrupted", now: now() });
   await store.save(settled);
   return settled;
 }

package/src/record/run-settle-record.ts

@@ -0,0 +1,67 @@
+import type { EndedRunSummary, RunOutcome, RunSummary } from "@yaag/runtime";
+import type { RunRecord } from "./run-record.ts";
+
+/**
+ * Marks a folded Summary ended, keeping every accounting fact it holds.
+ *
+ * An already-ended fold is history and is returned unchanged: a Run keeps the
+ * first outcome observed for it, the invariant the registry keeps when it
+ * retains a settlement. `endedAt` stays null because it is the `run_end.at`
+ * event fact and no such event was seen.
+ */
+export function endedSummary(
+  summary: RunSummary,
+  outcome: RunOutcome,
+  endedAtMs: number,
+): EndedRunSummary {
+  if (summary.runState === "ended") return summary;
+  return {
+    ...summary,
+    runState: "ended",
+    outcome,
+    ok: outcome === "completed",
+    endedAt: null,
+    durationMs: durationOf(summary, endedAtMs),
+  };
+}
+
+/**
+ * The fold never synthesizes a duration from a clock (architecture §8), so the
+ * wall-clock value is supplied here, once, by the caller that settles the Run.
+ * Without it a settled Run reads `0s` instead of how long it really ran.
+ */
+function durationOf(summary: RunSummary, endedAtMs: number): number {
+  if (summary.durationMs !== 0) return summary.durationMs;
+  if (summary.startedAt === null) return 0;
+  return Math.max(0, endedAtMs - summary.startedAt);
+}
+
+/** Marks a fold ended as failed, for a Run whose child rejected. */
+export function failedSummary(summary: RunSummary, endedAtMs: number): EndedRunSummary {
+  if (summary.runState === "ended")
+    return summary.ok ? { ...summary, outcome: "failed", ok: false } : summary;
+  return endedSummary(summary, "failed", endedAtMs);
+}
+
+/**
+ * The settled form of a record no process is attached to any more.
+ *
+ * The persisted state is `interrupted`: no new state member is added, so an
+ * older yaag still reads the record. The verdict lives in the Summary fold —
+ * `stopped` when yaag_stop killed the group, `interrupted` when the process was
+ * already gone. The persisted outcome stays null, because the Run gave no exit
+ * code and no rejection reason.
+ */
+export function settledRecord(options: {
+  readonly record: RunRecord;
+  readonly outcome: RunOutcome;
+  readonly now: Date;
+}): RunRecord {
+  const { record, outcome, now } = options;
+  return {
+    ...record,
+    state: "interrupted",
+    endedAt: now.toISOString(),
+    summary: endedSummary(record.summary, outcome, now.getTime()),
+  };
+}

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,10 +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 { restoredStateText } from "./restored-run-text.ts";
-import { boundedRuns, RUN_LISTING_CAP } from "./run-listing.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)" })),

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, type ProcessIdentity } 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 {
@@ -21,9 +21,22 @@ const DESCRIPTION = [
   "it spent before it stopped.",
   "",
   "An orphaned Run left behind by an earlier Host Session is stopped too: its",
-  "process group is killed, and the report holds its last persisted Summary.",
+  "process group is killed, its record is settled, and the report holds its last",
+  "persisted Summary. If its process already ended, the record is settled too and",
+  "the report says the Run was no longer running.",
 ].join("\n");
 
+/** Seams the tests replace, so no test kills a real process group. */
+export interface StopToolOptions {
+  readonly isAlive?: (identity: ProcessIdentity) => boolean;
+  readonly kill?: (pid: number) => void;
+}
+
+interface StopDeps {
+  readonly isAlive: (identity: ProcessIdentity) => boolean;
+  readonly kill: (pid: number) => void;
+}
+
 /** What a stopped Run got through and what it cost, from the fold (ADR-0006). */
 export function stopReport(id: string, summary: RunSummary): string {
   const agents = Object.keys(summary.agents).length;
@@ -71,18 +84,28 @@ function agentStateReport(agent: RunSummary["agents"][string]): string {
  * 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).
+ *
+ * The record is settled either way: a process that already ended is not an
+ * error, it only means the verdict is `interrupted` instead of `stopped`.
  */
-function stopOrphan(run: RestoredRun): AgentToolResult<StopDetails> {
+async function stopOrphan(
+  run: RestoredRun,
+  registry: RunRegistry,
+  deps: StopDeps,
+): Promise<AgentToolResult<StopDetails>> {
   const { record } = run;
   if (record.state !== "orphaned" || record.process === null)
     throw new Error(`yaag_stop: Run ${record.id} has already finished`);
-  if (!isProcessAlive(record.process))
-    throw new Error(`yaag_stop: Run ${record.id} is no longer running`);
-  killGroup(record.process.pid);
+  const alive = deps.isAlive(record.process);
+  if (alive) deps.kill(record.process.pid);
+  const settled = await registry.settleRestored(record, alive ? "stopped" : "interrupted");
+  const note = alive
+    ? ""
+    : `Run ${record.id} was no longer running; its record is settled as interrupted.\n`;
   return {
-    content: [{ type: "text", text: stopReport(record.id, record.summary) }],
-    details: { summary: record.summary },
-    usage: toUsage(record.summary),
+    content: [{ type: "text", text: `${note}${stopReport(record.id, settled.summary)}` }],
+    details: { summary: settled.summary },
+    usage: toUsage(settled.summary),
   };
 }
 
@@ -111,7 +134,12 @@ function toError(reason: unknown): Error {
  */
 export function createStopTool(
   registry: RunRegistry,
+  options: StopToolOptions = {},
 ): ToolDefinition<typeof parameters, StopDetails> {
+  const deps: StopDeps = {
+    isAlive: options.isAlive ?? isProcessAlive,
+    kill: options.kill ?? killGroup,
+  };
   return {
     name: "yaag_stop",
     label: "Stop Run",
@@ -123,7 +151,7 @@ export function createStopTool(
         case "unknown":
           throw new Error(`yaag_stop: no Run with id ${params.id}`);
         case "restored":
-          return stopOrphan(status.run);
+          return await stopOrphan(status.run, registry, deps);
         case "finished":
           throw new Error(`yaag_stop: Run ${params.id} has already finished`);
         case "live": {

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/{restored-run-text.ts → view/restored-run-text.ts}

@@ -6,7 +6,7 @@
  * I/O.
  */
 import type { RunViewResult } from "@yaag/tui";
-import type { RunRecord } from "./run-record.ts";
+import type { RunRecord } from "../record/index.ts";
 
 /**
  * States the persisted verdict of a Run that no process is attached to.

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/{run-listing.ts → view/run-listing.ts}

@@ -2,7 +2,7 @@
  * 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 "./run-registry.ts";
+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;

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

@@ -3,8 +3,8 @@
  * the list can be tested without a live UI.
  */
 import type { RunSummary } from "@yaag/runtime";
+import type { DatedRun } from "../record/index.ts";
 import { boundedRuns } from "./run-listing.ts";
-import type { DatedRun } from "./run-registry.ts";
 
 /** One Run the picker can open: its id, latest Summary fold, and liveness. */
 export interface PickableRun {

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

@@ -14,10 +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";
 

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;