@yaag/extension 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,14 +19,15 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "for file in src/*.test.ts; do bun test \"$file\" || exit 1; done",
-    "test:e2e": "bun test e2e"
+    "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/runtime": "workspace:*",
-    "@yaag/tui": "workspace:*",
-    "@yaag/cli": "workspace:*"
+    "@yaag/cli": "0.2.0",
+    "@yaag/runtime": "0.2.0",
+    "@yaag/tui": "0.2.0",
+    "nanoid": "^6.0.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/cli-child.ts

@@ -22,6 +22,8 @@ export interface CliChildOptions {
 export interface CliChild {
   readonly outcome: Promise<CliChildOutcome>;
   readonly events: Readable | undefined;
+  /** The child's pid, and the group id its reap ladder signals. */
+  readonly pid?: number | undefined;
   stop(): void;
 }
 
@@ -38,6 +40,7 @@ export function startCliChild(options: CliChildOptions): CliChild {
   });
   const stderr = new StderrTail();
   const exited = observeExit(child);
+  releasePipesAfterExit(child);
   const target: ReapTarget = {
     exited,
     endStdin: () => endStdin(child.stdin),
@@ -52,6 +55,7 @@ export function startCliChild(options: CliChildOptions): CliChild {
   const eventStream = options.events === true ? child.stdio[3] : undefined;
   return {
     outcome,
+    pid: child.pid,
     events: isReadable(eventStream) ? eventStream : undefined,
     stop: () => void reap(target),
   };
@@ -91,7 +95,30 @@ async function drain(stream: Readable | null, onChunk: (chunk: string) => void):
 
 function observeExit(child: ReturnType<typeof spawn>): Promise<void> {
   return new Promise((resolve, reject) => {
-    child.on("close", () => resolve());
+    // "exit" (process death), not "close": "close" additionally waits for every
+    // stdio pipe to end, and a lost pipe EOF would park the Run forever.
+    child.on("exit", () => resolve());
     child.on("error", reject);
   });
 }
+
+/** How long an exited child's pipes may take to deliver buffered data and EOF. */
+const PIPE_EOF_GRACE_MS = 2_000;
+
+/**
+ * Failsafe for a lost pipe EOF: once the child process is dead, any of its
+ * pipes (stdout, stderr, the fd 3 Lifecycle Event stream) that has not ended
+ * within a bounded grace is destroyed, so the iterators that drain them finish
+ * instead of parking the Run's outcome — and the test process — forever.
+ */
+function releasePipesAfterExit(child: ReturnType<typeof spawn>): void {
+  child.once("exit", () => {
+    const timer = setTimeout(() => {
+      for (const stream of [child.stdout, child.stderr, child.stdio[3]]) {
+        if (isReadable(stream) && !stream.destroyed) stream.destroy();
+      }
+    }, PIPE_EOF_GRACE_MS);
+    // A housekeeping timer must never keep the host process alive.
+    timer.unref();
+  });
+}

package/src/index.ts

@@ -6,6 +6,7 @@ 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";
@@ -31,8 +32,10 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   const cli = resolveCliEntry();
   const report = statusReport(bun, cli);
 
-  // One registry per session retains every foreground and background Run.
-  const registry = new RunRegistry();
+  // 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 one combined inline widget both live for
   // the session, beside the registry, so a background Run keeps a tree.
   const store = new RunTreeStore();

package/src/process-liveness.ts

@@ -0,0 +1,51 @@
+import { readFileSync } from "node:fs";
+
+/** What a Run record remembers about the process that carried it. */
+export interface ProcessIdentity {
+  readonly pid: number;
+  /** Kernel start time of that pid, when the platform exposes it. */
+  readonly startedAt: string | null;
+}
+
+/**
+ * Reads the start time of a live pid, so a later session can tell the original
+ * process from an unrelated one that inherited the pid. Linux exposes it as
+ * field 22 of `/proc/<pid>/stat`; every other platform returns `null` and the
+ * liveness probe falls back to the pid alone.
+ */
+export function readProcessStart(pid: number): string | null {
+  if (process.platform !== "linux") return null;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // The second field is the executable name in parentheses and may itself
+    // contain spaces and parentheses, so fields are counted after the last ")".
+    const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    return fields[19] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reports whether the exact process a record names is still running. A pid that
+ * exists but reports a different start time is a reused pid, and is treated as
+ * dead: killing it would end an unrelated process.
+ */
+export function isProcessAlive(identity: ProcessIdentity): boolean {
+  if (!Number.isInteger(identity.pid) || identity.pid <= 0) return false;
+  try {
+    process.kill(identity.pid, 0);
+  } catch (error) {
+    // EPERM means the process exists but belongs to another user.
+    return isPermissionError(error);
+  }
+  if (identity.startedAt === null) return true;
+  const current = readProcessStart(identity.pid);
+  return current === null || current === identity.startedAt;
+}
+
+function isPermissionError(error: unknown): boolean {
+  if (typeof error !== "object" || error === null || !("code" in error)) return false;
+  const { code } = error;
+  return code === "EPERM";
+}

package/src/run-details.ts

@@ -43,7 +43,8 @@ function isRunSummary(value: unknown): value is RunSummary {
     value.runState === "ended" &&
     isOutcome(value.outcome) &&
     typeof value.ok === "boolean" &&
-    nullableNumber(value.endedAt)
+    nullableNumber(value.endedAt) &&
+    optionalString(value.checkpointLost)
   );
 }
 
@@ -207,7 +208,8 @@ function isEvent(value: unknown): value is LifecycleEvent {
         number(value.cost) &&
         nullableTokens(value.tokens) &&
         typeof value.incomplete === "boolean" &&
-        natural(value.worstFrameGapMs)
+        natural(value.worstFrameGapMs) &&
+        optionalString(value.checkpointLost)
       );
     default:
       return false;

package/src/run-id.ts

@@ -0,0 +1,24 @@
+import { customAlphabet } from "nanoid";
+
+/**
+ * Lowercase letters and digits only: a Run id is typed back by a human into
+ * `yaag_status` and `yaag_stop`, so the alphabet holds no case distinction and
+ * no punctuation.
+ */
+const ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+
+/** Nine random characters over 36 symbols; the `r` prefix is not random. */
+const ID_LENGTH = 9;
+
+const nanoid = customAlphabet(ALPHABET, ID_LENGTH);
+
+/**
+ * Mints one globally unique Run id.
+ *
+ * The id must stay unique across Host Sessions, because Run records outlive the
+ * session that started them (ticket 02); a per-session counter would collide
+ * with every earlier session's `r1`.
+ */
+export function mintRunId(): string {
+  return `r${nanoid()}`;
+}

package/src/run-record.ts

@@ -0,0 +1,91 @@
+import { initialSummary, type RunSummary } from "@yaag/runtime";
+import type { ProcessIdentity } from "./process-liveness.ts";
+
+/**
+ * The durable state of a Run.
+ *
+ * `live` and `finished` are written by the session that owns the Run.
+ * `interrupted` and `orphaned` are written by a later session that found a
+ * `live` record its own memory knows nothing about: the child is dead, or the
+ * child is still running without an owner (ticket 02).
+ */
+export type PersistedRunState = "live" | "finished" | "interrupted" | "orphaned";
+
+/** How a Run ended, reduced to values that survive JSON. */
+export type PersistedOutcome =
+  | { readonly kind: "fulfilled"; readonly code: number | null; readonly result: string }
+  | { readonly kind: "rejected"; readonly reason: string };
+
+/** What starting a Run said about it; enough to describe it in a later session. */
+export interface RunLaunch {
+  readonly file: string;
+  readonly args?: string;
+  readonly record?: string;
+  readonly resume?: string;
+}
+
+/** One Run as stored on disk, at `<runs dir>/<id>.json`. */
+export interface RunRecord {
+  readonly id: string;
+  readonly launch: RunLaunch;
+  readonly process: ProcessIdentity | null;
+  readonly startedAt: string;
+  readonly endedAt: string | null;
+  readonly state: PersistedRunState;
+  readonly summary: RunSummary;
+  readonly outcome: PersistedOutcome | null;
+}
+
+/**
+ * Narrows an untrusted parsed JSON value to a {@link RunRecord}.
+ *
+ * A record may have been written by an older yaag, or truncated by a crash, so
+ * every field the extension reads is checked here and a record that fails is
+ * dropped rather than repaired.
+ */
+export function isRunRecord(value: unknown): value is RunRecord {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate: Record<string, unknown> = { ...value };
+  return (
+    typeof candidate["id"] === "string" &&
+    typeof candidate["startedAt"] === "string" &&
+    isState(candidate["state"]) &&
+    isLaunch(candidate["launch"]) &&
+    isSummary(candidate["summary"])
+  );
+}
+
+/** A Run record for a Run that has just started. */
+export function startedRecord(options: {
+  readonly id: string;
+  readonly launch: RunLaunch;
+  readonly process: ProcessIdentity | null;
+  readonly now: string;
+}): RunRecord {
+  return {
+    id: options.id,
+    launch: options.launch,
+    process: options.process,
+    startedAt: options.now,
+    endedAt: null,
+    state: "live",
+    summary: initialSummary(),
+    outcome: null,
+  };
+}
+
+function isState(value: unknown): value is PersistedRunState {
+  return (
+    value === "live" || value === "finished" || value === "interrupted" || value === "orphaned"
+  );
+}
+
+function isLaunch(value: unknown): value is RunLaunch {
+  return (
+    typeof value === "object" && value !== null && "file" in value && typeof value.file === "string"
+  );
+}
+
+function isSummary(value: unknown): value is RunSummary {
+  return typeof value === "object" && value !== null && "runState" in value;
+}

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

@@ -12,6 +12,8 @@ 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";
@@ -122,7 +124,7 @@ 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);
       // Attached before start(): the Ask ledger folds from events, so a state
@@ -224,7 +226,6 @@ function registeredRun(options: {
   /** 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 +234,33 @@ 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/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);
+}

package/src/spawn-run.ts

@@ -38,6 +38,8 @@ export interface SpawnRunOptions extends StartRunOptions {
 export interface RunHandle {
   readonly outcome: Promise<RunOutcome>;
   readonly stop: () => void;
+  /** The child's pid, when the spawn produced one. */
+  readonly pid?: number | undefined;
 }
 
 /**
@@ -65,7 +67,7 @@ export function startRun(options: StartRunOptions): RunHandle {
           options.onProgress?.(summary, event, sequence);
         }),
   ]).then(([ended]) => ({ ...ended, summary }));
-  return { outcome, stop: child.stop };
+  return { outcome, stop: child.stop, pid: child.pid };
 }
 
 /**

package/src/status-tool.ts

@@ -2,7 +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 { RegisteredRun, RunRegistry } from "./run-registry.ts";
+import type { PersistedRunState } from "./run-record.ts";
+import type { RegisteredRun, RestoredRun, RunRegistry } from "./run-registry.ts";
 import { toUsage } from "./usage.ts";
 
 const parameters = Type.Object({
@@ -25,10 +26,15 @@ export interface StatusToolOptions {
 }
 
 const DESCRIPTION = [
-  "Show a snapshot of a Run started in this Host Session.",
+  "Show a snapshot of a Run started by yaag_run.",
   "",
   "With an id, returns that Run's live snapshot or its retained final snapshot.",
-  "Without an id, lists every Run started this session in registration order.",
+  "Run records outlive the Host Session, so an id from an earlier session still",
+  "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.",
 ].join("\n");
 
 /**
@@ -50,7 +56,7 @@ export function createStatusTool(
     parameters,
     async execute(_id, params) {
       if (params.id === undefined) return overview(registry.runs, now, width);
-      const found = registry.lookup(params.id);
+      const found = await registry.recall(params.id);
       if (found.state === "unknown") throw unknownId(params.id, registry.knownIds);
       const details = detailsFor(found);
       return {
@@ -85,6 +91,7 @@ function overview(
 
 function detailsFor(run: RegisteredRun): SnapshotDetails {
   if (run.state === "live") return { id: run.run.id, summary: run.run.summary };
+  if (run.state === "restored") return restoredDetails(run.run);
   const { outcome } = run.run;
   return {
     id: run.run.id,
@@ -95,6 +102,34 @@ 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).
+ */
+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.state, run.summary.artifact)}`;
+  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). The Run
+ * republishes it at each Ask boundary, so it exists whenever the Run reached
+ * one, for a dead Run and for a still-running orphan alike.
+ */
+function resumeHint(state: PersistedRunState, artifact: string | null): string {
+  if (artifact === null) return "";
+  if (state !== "interrupted" && state !== "orphaned") return "";
+  return ` Resume it from its checkpoint: ${artifact}.`;
+}
+
 function snapshot(
   details: SnapshotDetails,
   now: () => number,

package/src/stop-tool.ts

@@ -1,7 +1,8 @@
-import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { RunSummary } from "@yaag/runtime";
 import { Type } from "typebox";
-import type { RunRegistry } from "./run-registry.ts";
+import { isProcessAlive } from "./process-liveness.ts";
+import type { RestoredRun, RunRegistry } from "./run-registry.ts";
 import { toUsage } from "./usage.ts";
 
 /** What the stop result carries for rendering — never shown to the model. */
@@ -18,6 +19,9 @@ const DESCRIPTION = [
   "",
   "The Run's Agents are reaped, and the report says what it got through and what",
   "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.",
 ].join("\n");
 
 /** What a stopped Run got through and what it cost, from the fold (ADR-0006). */
@@ -62,6 +66,38 @@ 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
+ * (ADR-0008). The pid is re-probed first, because a record can name a pid that
+ * a different process has since inherited (ticket 02).
+ */
+function stopOrphan(run: RestoredRun): 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);
+  return {
+    content: [{ type: "text", text: stopReport(record.id, record.summary) }],
+    details: { summary: record.summary },
+    usage: toUsage(record.summary),
+  };
+}
+
+function killGroup(pid: number): void {
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // The process ended between the liveness probe and the signal.
+    }
+  }
+}
+
 function toError(reason: unknown): Error {
   return reason instanceof Error ? reason : new Error(String(reason));
 }
@@ -82,10 +118,12 @@ export function createStopTool(
     description: DESCRIPTION,
     parameters,
     async execute(_id, params) {
-      const status = registry.lookup(params.id);
+      const status = await registry.recall(params.id);
       switch (status.state) {
         case "unknown":
           throw new Error(`yaag_stop: no Run with id ${params.id}`);
+        case "restored":
+          return stopOrphan(status.run);
         case "finished":
           throw new Error(`yaag_stop: Run ${params.id} has already finished`);
         case "live": {