@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/lib/runs-control.ts

@@ -0,0 +1,148 @@
+/**
+ * Async run process control primitives.
+ * Owns: platform signal planning, owned-process signalling, and terminal control markers.
+ */
+
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+import {
+  verifyRunProcessIdentity,
+  type RunProcessIdentity,
+  type RunProcessIdentityResult,
+} from "./runs-process.ts";
+
+export interface RunProcessSignalPlan {
+  args?: string[];
+  command?: string;
+  signalTarget: "processGroup" | "process" | "processTree";
+}
+
+export function getRunProcessSignalPlan(
+  pid: number,
+  signal: NodeJS.Signals,
+  runtimePlatform: NodeJS.Platform = process.platform,
+): RunProcessSignalPlan {
+  if (runtimePlatform === "win32") {
+    return {
+      args: [
+        "/PID",
+        String(pid),
+        "/T",
+        ...(signal === "SIGKILL" ? ["/F"] : []),
+      ],
+      command: "taskkill",
+      signalTarget: "processTree",
+    };
+  }
+  return { signalTarget: "processGroup" };
+}
+
+export interface RunProcessSignalDeps {
+  killProcess?: typeof process.kill;
+  runtimePlatform?: NodeJS.Platform;
+  spawnProcess?: typeof spawnSync;
+  verifyIdentity?: (
+    pid: number,
+    expected: RunProcessIdentity,
+    runtimePlatform: NodeJS.Platform,
+  ) => RunProcessIdentityResult;
+}
+
+export function signalOwnedRunProcess(
+  pid: number,
+  signal: NodeJS.Signals,
+  expectedIdentity?: RunProcessIdentity,
+  deps: RunProcessSignalDeps = {},
+): RunProcessSignalPlan {
+  const runtimePlatform = deps.runtimePlatform ?? process.platform;
+  if (expectedIdentity) {
+    const proof = (deps.verifyIdentity ?? verifyRunProcessIdentity)(
+      pid,
+      expectedIdentity,
+      runtimePlatform,
+    );
+    if (!proof.valid) {
+      throw new Error(
+        `Run process identity changed before signaling: ${proof.status.replaceAll("_", " ")}`,
+      );
+    }
+  }
+  const plan = getRunProcessSignalPlan(pid, signal, runtimePlatform);
+  if (plan.command && plan.args) {
+    const spawnProcess = deps.spawnProcess ?? spawnSync;
+    let result = spawnProcess(plan.command, plan.args, { encoding: "utf8" });
+    if (
+      runtimePlatform === "win32" &&
+      result.status !== 0 &&
+      !plan.args.includes("/F")
+    ) {
+      result = spawnProcess(plan.command, [...plan.args, "/F"], {
+        encoding: "utf8",
+      });
+    }
+    if (result.status !== 0) {
+      if (expectedIdentity) {
+        const finalProof = (deps.verifyIdentity ?? verifyRunProcessIdentity)(
+          pid,
+          expectedIdentity,
+          runtimePlatform,
+        );
+        if (finalProof.status === "dead_pid") return plan;
+      }
+      throw new Error(
+        result.stderr?.trim() ||
+          result.stdout?.trim() ||
+          `${plan.command} failed`,
+      );
+    }
+    return plan;
+  }
+  const killProcess = deps.killProcess ?? process.kill.bind(process);
+  try {
+    killProcess(-pid, signal);
+    return { signalTarget: "processGroup" };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+    if (expectedIdentity) {
+      const fallbackProof = (deps.verifyIdentity ?? verifyRunProcessIdentity)(
+        pid,
+        expectedIdentity,
+        runtimePlatform,
+      );
+      if (!fallbackProof.valid) {
+        throw new Error(
+          `Run process identity changed before pid fallback: ${fallbackProof.status.replaceAll("_", " ")}`,
+        );
+      }
+    }
+    killProcess(pid, signal);
+    return { signalTarget: "process" };
+  }
+}
+
+export function markTerminalHandled(
+  stateDir: string,
+  details: Record<string, unknown>,
+): void {
+  writeJsonAtomic(join(stateDir, "terminal-handled.json"), {
+    ...details,
+    ts: new Date().toISOString(),
+  });
+}
+
+export function buildTerminalProgress(
+  existing: Record<string, unknown> | undefined,
+  phase: "cancelled" | "killed",
+): Record<string, unknown> {
+  const progress = existing ?? {};
+  const { activeSubagents: _activeSubagents, ...rest } = progress;
+  return {
+    ...rest,
+    completed: typeof progress.completed === "number" ? progress.completed : 0,
+    failures: Array.isArray(progress.failures) ? progress.failures : [],
+    phase,
+    updatedAt: new Date().toISOString(),
+  };
+}

package/node_modules/@llblab/pi-actors/lib/runs-controls.ts

@@ -0,0 +1,282 @@
+/**
+ * Run Control journal.
+ * Zones: durable records, atomic admission, claims, transitions, compaction
+ * Owns Run-local Control persistence; lifecycle authorization and transport stay in adapters.
+ */
+
+import { randomUUID } from "node:crypto";
+import { closeSync, fstatSync, openSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import * as Control from "./control.ts";
+import { acquireFileMutationLock, writeTextAtomic } from "./file-state.ts";
+import * as Limits from "./limits.ts";
+import {
+  classifyRunControlRecord, computeRunControlCapacity, decideRunControlAdmission,
+  runControlStatusTimestamp, type RunControlAdmissionErrorDetails,
+  type RunControlAdmissionIntegrity, type RunControlStatus,
+} from "./run-evidence-policy.ts";
+import type { JsonlReadResult, StateReadDiagnostic } from "./state-readers.ts";
+
+export { RUN_CONTROL_TERMINAL_LIMIT } from "./limits.ts";
+export type { RunControlStatus } from "./run-evidence-policy.ts";
+export interface RunControlRecord {
+  id: string;
+  run_instance_id: string;
+  action: string;
+  input?: unknown;
+  status: RunControlStatus;
+  queued_at: string;
+  delivered_at?: string;
+  claimed_at?: string;
+  handled_at?: string;
+  failed_at?: string;
+  error?: string;
+}
+export interface ProcessRunControlsResult {
+  claimed: number; failed: number; handled: number;
+}
+function admissionError(details: RunControlAdmissionErrorDetails): Error {
+  return Object.assign(new Error(details.reason === "control_backpressure"
+    ? `Run Control admission backpressured: pending=${details.pending}/${details.limit}`
+    : `Run Control journal integrity failed: ${details.integrity_reason ?? "unknown"}`), details);
+}
+
+const STATUSES = new Set<RunControlStatus>([
+  "queued", "delivered", "claimed", "handled", "failed",
+]);
+export function runControlsFile(stateDir: string): string {
+  return join(stateDir, "controls.jsonl");
+}
+export function readRunControlJournalFromStateDir(stateDir: string): JsonlReadResult<unknown> {
+  const path = runControlsFile(stateDir);
+  let fd: number;
+  try { fd = openSync(path, "r"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { diagnostics: [], records: [] };
+    return { diagnostics: [{ message: String(error), path }], records: [] };
+  }
+  try {
+    const bytes = fstatSync(fd).size;
+    if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+      return { diagnostics: [{ message: "Run Control journal exceeds bounded read limit", path }], records: [] };
+    }
+    const buffer = Buffer.allocUnsafe(bytes);
+    let consumed = 0;
+    while (consumed < bytes) {
+      const count = readSync(fd, buffer, consumed, bytes - consumed, consumed);
+      if (count === 0) return { diagnostics: [{ message: "Run Control journal changed during bounded read", path }], records: [] };
+      consumed += count;
+    }
+    if (fstatSync(fd).size !== bytes) return { diagnostics: [{ message: "Run Control journal changed during bounded read", path }], records: [] };
+    const records: unknown[] = [];
+    const diagnostics: StateReadDiagnostic[] = [];
+    for (const [index, line] of buffer.toString("utf8").split("\n").entries()) {
+      if (!line.trim()) continue;
+      try { records.push(JSON.parse(line)); }
+      catch (error) { diagnostics.push({ line: index + 1, message: String(error), path }); }
+    }
+    return { diagnostics, records };
+  } catch (error) {
+    return { diagnostics: [{ message: String(error), path }], records: [] };
+  } finally { closeSync(fd); }
+}
+export function readRunControlsFromStateDir(stateDir: string): RunControlRecord[] {
+  return readRunControlJournalFromStateDir(stateDir).records as RunControlRecord[];
+}
+function acquireRunControlsLock(stateDir: string): () => void {
+  return acquireFileMutationLock(runControlsFile(stateDir));
+}
+
+function compactRunControls(records: RunControlRecord[]): RunControlRecord[] {
+  const active = records.filter((record) => classifyRunControlRecord(record) !== "terminal");
+  const terminal = records.filter((record) => classifyRunControlRecord(record) === "terminal")
+    .slice(-Limits.RUN_CONTROL_TERMINAL_LIMIT);
+  const retained = new Set([...active, ...terminal]);
+  return records.filter((record) => retained.has(record)).map((record) =>
+    typeof record.error === "string" && Buffer.byteLength(record.error) > Limits.RUN_CONTROL_ERROR_MAX_BYTES
+      ? { ...record, error: boundedControlError(record.error) } : record);
+}
+function encodeRunControls(records: RunControlRecord[]): string {
+  return records.length ? `${records.map((record) => JSON.stringify(record)).join("\n")}\n` : "";
+}
+function boundedControlError(value: string): string {
+  if (Buffer.byteLength(value) <= Limits.RUN_CONTROL_ERROR_MAX_BYTES) return value;
+  const suffix = "… [truncated]";
+  const limit = Limits.RUN_CONTROL_ERROR_MAX_BYTES - Buffer.byteLength(suffix);
+  const bytes = Buffer.from(value);
+  let end = limit;
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end -= 1;
+  return `${bytes.subarray(0, end).toString("utf8")}${suffix}`;
+}
+function writeRunControls(stateDir: string, records: RunControlRecord[]): void {
+  const encoded = encodeRunControls(compactRunControls(records));
+  if (Buffer.byteLength(encoded) > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+    throw new Error("Run Control journal transition exceeds bounded byte limit");
+  }
+  writeTextAtomic(runControlsFile(stateDir), encoded);
+}
+function readMutableRunControls(
+  stateDir: string, runInstanceId?: string,
+): RunControlRecord[] | undefined {
+  const journal = readRunControlJournalFromStateDir(stateDir);
+  if (journal.diagnostics.length) return undefined;
+  const records = journal.records as RunControlRecord[];
+  if (runInstanceId && records.some((record) => controlIntegrity(record, runInstanceId) !== "valid"))
+    return undefined;
+  return records;
+}
+function controlIntegrity(value: unknown, runInstanceId: string): RunControlAdmissionIntegrity {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "invalid_record";
+  const record = value as Record<string, unknown>;
+  if (typeof record.id !== "string" || !record.id ||
+      typeof record.run_instance_id !== "string" || !record.run_instance_id ||
+      typeof record.status !== "string" || !STATUSES.has(record.status as RunControlStatus) ||
+      (record.error !== undefined && typeof record.error !== "string")) return "invalid_record";
+  try {
+    Control.normalizeControlAction(record.action);
+    if (record.input !== undefined) Control.normalizeControlInput(record.input);
+  } catch { return "invalid_record"; }
+  const timestamp = runControlStatusTimestamp(record, record.status as RunControlStatus);
+  if (typeof timestamp !== "string" || !Number.isFinite(Date.parse(timestamp)))
+    return "invalid_status_timestamp";
+  if (classifyRunControlRecord(record) === "pending" &&
+      record.run_instance_id !== runInstanceId) return "generation_mismatch";
+  return "valid";
+}
+export function appendRunControlInStateDir(
+  stateDir: string, request: { run_instance_id: string; action: string; input?: unknown },
+): RunControlRecord {
+  const action = Control.normalizeControlAction(request.action);
+  const input = request.input === undefined ? undefined : Control.normalizeControlInput(request.input);
+  const record: RunControlRecord = {
+    id: randomUUID(),
+    run_instance_id: request.run_instance_id,
+    action,
+    ...(input !== undefined ? { input } : {}),
+    status: "queued",
+    queued_at: new Date().toISOString(),
+  };
+  const encodedRecordBytes = Buffer.byteLength(`${JSON.stringify(record)}\n`);
+  const releaseLock = acquireRunControlsLock(stateDir);
+  try {
+    const path = runControlsFile(stateDir);
+    let bytes = 0;
+    try { bytes = statSync(path).size; }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") bytes = Number.MAX_SAFE_INTEGER;
+    }
+    const journal = bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES
+      ? { diagnostics: [], records: [] } : readRunControlJournalFromStateDir(stateDir);
+    let integrity: RunControlAdmissionIntegrity = bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES
+      ? "journal_bytes"
+      : journal.diagnostics.some((item) => item.line !== undefined)
+        ? "malformed"
+        : journal.diagnostics.length ? "unreadable" : "valid";
+    for (const value of journal.records) {
+      if (integrity !== "valid") break;
+      integrity = controlIntegrity(value, request.run_instance_id);
+    }
+    const records = journal.records as RunControlRecord[];
+    const retained = encodeRunControls(compactRunControls(records));
+    const decision = decideRunControlAdmission({
+      integrity,
+      journalBytes: bytes,
+      newRecordBytes: encodedRecordBytes,
+      records,
+      retainedJournalBytes: Buffer.byteLength(retained),
+      runInstanceId: request.run_instance_id,
+      capacity: computeRunControlCapacity(records),
+    });
+    if (!decision.admitted) throw admissionError(decision.error);
+    writeTextAtomic(path, `${retained}${JSON.stringify(record)}\n`);
+    return record;
+  } finally {
+    releaseLock();
+  }
+}
+export function updateRunControlStatusInStateDir(
+  stateDir: string, id: string, nextStatus: RunControlStatus,
+  metadata: Pick<RunControlRecord, "error"> = {},
+  expectedStatuses?: readonly RunControlStatus[],
+): boolean {
+  const releaseLock = acquireRunControlsLock(stateDir);
+  try {
+    const records = readMutableRunControls(stateDir);
+    if (!records) return false;
+    const index = records.findIndex((record) => record.id === id);
+    if (index < 0) return false;
+    const record = records[index]!;
+    if (records.some((value) => controlIntegrity(value, record.run_instance_id) !== "valid")) return false;
+    if (expectedStatuses && !expectedStatuses.includes(record.status)) return false;
+    if (record.status === nextStatus) return false;
+    const timestamp = new Date().toISOString();
+    if (nextStatus === "delivered") {
+      if (record.delivered_at) return false;
+      records[index] = { ...record, delivered_at: timestamp,
+        ...(record.status === "queued" ? { status: "delivered" as const } : {}) };
+    } else {
+      if (classifyRunControlRecord(record) === "terminal" || nextStatus === "queued") return false;
+      if ((nextStatus === "claimed" && record.status !== "queued" &&
+          record.status !== "delivered") ||
+          (nextStatus === "handled" && record.status !== "claimed")) return false;
+      records[index] = { ...record,
+        ...(metadata.error !== undefined ? { error: boundedControlError(metadata.error) } : {}),
+        [`${nextStatus}_at`]: timestamp, status: nextStatus };
+    }
+    writeRunControls(stateDir, records);
+    return true;
+  } finally {
+    releaseLock();
+  }
+}
+function claimRunControl(
+  stateDir: string, runInstanceId: string, controlId?: string,
+): RunControlRecord | undefined {
+  const releaseLock = acquireRunControlsLock(stateDir);
+  try {
+    const records = readMutableRunControls(stateDir, runInstanceId);
+    if (!records) return undefined;
+    const index = records.findIndex((record) =>
+      (controlId === undefined || record.id === controlId) &&
+      record.run_instance_id === runInstanceId &&
+      (record.status === "queued" || record.status === "delivered"));
+    if (index < 0) return undefined;
+    const claimed: RunControlRecord = {
+      ...records[index]!, claimed_at: new Date().toISOString(), status: "claimed" };
+    records[index] = claimed;
+    writeRunControls(stateDir, records);
+    return claimed;
+  } finally { releaseLock(); }
+}
+export function claimRunControlInStateDir(
+  stateDir: string, runInstanceId: string,
+): RunControlRecord | undefined {
+  return claimRunControl(stateDir, runInstanceId);
+}
+export function claimRunControlByIdInStateDir(
+  stateDir: string, runInstanceId: string, controlId: string,
+): RunControlRecord | undefined {
+  return claimRunControl(stateDir, runInstanceId, controlId);
+}
+export async function processRunControlsInStateDir(
+  stateDir: string, runInstanceId: string,
+  handler: (control: RunControlRecord) => Promise<void> | void, limit = 1,
+): Promise<ProcessRunControlsResult> {
+  const result: ProcessRunControlsResult = { claimed: 0, failed: 0, handled: 0 };
+  for (let index = 0; index < Math.max(1, limit); index += 1) {
+    const control = claimRunControlInStateDir(stateDir, runInstanceId);
+    if (!control) break;
+    result.claimed += 1;
+    try {
+      await handler(control);
+      if (updateRunControlStatusInStateDir(stateDir, control.id, "handled", {}, ["claimed"]))
+        result.handled += 1;
+    } catch (error) {
+      if (updateRunControlStatusInStateDir(stateDir, control.id, "failed",
+        { error: error instanceof Error ? error.message : String(error) }, ["claimed"]))
+        result.failed += 1;
+    }
+  }
+  return result;
+}

package/node_modules/@llblab/pi-actors/lib/runs-identity.ts

@@ -0,0 +1,14 @@
+/**
+ * Async run identity helpers.
+ * Owns: run id normalization shared by run lifecycle and retention paths.
+ */
+
+export function safeRunId(value: string | undefined): string {
+  const run = (value || `run-${Date.now()}`).trim();
+  if (!/^[A-Za-z0-9_.-]+$/.test(run)) {
+    throw new Error(
+      "Run id may contain only letters, numbers, dot, underscore, and dash.",
+    );
+  }
+  return run;
+}

package/node_modules/@llblab/pi-actors/lib/runs-index.ts

@@ -0,0 +1,192 @@
+/**
+ * Async run state index.
+ * Owns: recursive run-state discovery, index rebuild/read, and status filtering.
+ */
+
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+
+export interface RunStateIndexEntry {
+  ownerId?: string;
+  recipe?: string;
+  run: string;
+  state_dir: string;
+  status: string;
+  tool?: string;
+  updated_at?: string;
+}
+
+export type RunStatusReader = (runOrDir: string) => Record<string, unknown>;
+
+function matchesStatusFilter(
+  status: unknown,
+  filter: string | undefined,
+): boolean {
+  if (!filter || filter === "all") return true;
+  if (filter === "active") return status === "running";
+  if (filter === "terminal") return status !== "running";
+  return status === filter;
+}
+
+export interface RunStateDiscoveryIssue {
+  path: string;
+  reason: "depth_truncated" | "unreadable";
+}
+
+export interface RunStateDiscoveryResult {
+  issues: RunStateDiscoveryIssue[];
+  stateDirs: string[];
+}
+
+export function discoverRunStateDirs(
+  stateRoot: string,
+  maxDepth = 8,
+): RunStateDiscoveryResult {
+  const issues: RunStateDiscoveryIssue[] = [];
+  const stateDirs: string[] = [];
+  const seen = new Set<string>();
+  const visit = (directory: string, depth: number): void => {
+    const canonical = resolve(directory);
+    if (!existsSync(directory) || seen.has(canonical)) return;
+    seen.add(canonical);
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = readdirSync(directory, { withFileTypes: true });
+    } catch {
+      issues.push({ path: directory, reason: "unreadable" });
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const child = join(directory, entry.name);
+      if (existsSync(join(child, "run.json"))) stateDirs.push(child);
+      if (depth + 1 < maxDepth) visit(child, depth + 1);
+      else {
+        try {
+          if (
+            readdirSync(child, { withFileTypes: true }).some((item) =>
+              item.isDirectory(),
+            )
+          ) {
+            issues.push({ path: child, reason: "depth_truncated" });
+          }
+        } catch {
+          issues.push({ path: child, reason: "unreadable" });
+        }
+      }
+    }
+  };
+  visit(stateRoot, 0);
+  return {
+    issues: issues.sort((left, right) => left.path.localeCompare(right.path)),
+    stateDirs: [...new Set(stateDirs)].sort(),
+  };
+}
+
+export function listRunStateDirs(stateRoot: string): string[] {
+  return discoverRunStateDirs(stateRoot).stateDirs;
+}
+
+function runIndexPath(stateRoot: string): string {
+  return join(stateRoot, "index.json");
+}
+
+function indexEntryFromStatus(
+  status: Record<string, unknown>,
+): RunStateIndexEntry {
+  const progress =
+    status.progress && typeof status.progress === "object"
+      ? (status.progress as Record<string, unknown>)
+      : {};
+  return {
+    ...(typeof status.ownerId === "string" ? { ownerId: status.ownerId } : {}),
+    ...(typeof status.recipe === "string" ? { recipe: status.recipe } : {}),
+    run: String(status.run),
+    state_dir: String(status.state_dir),
+    status: String(status.status),
+    ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
+    updated_at:
+      typeof progress.updatedAt === "string"
+        ? progress.updatedAt
+        : typeof status.createdAt === "string"
+          ? status.createdAt
+          : new Date(0).toISOString(),
+  };
+}
+
+export function rebuildRunStateIndex(
+  stateRoot: string,
+  getRunStatus: RunStatusReader,
+): RunStateIndexEntry[] {
+  mkdirSync(stateRoot, { recursive: true });
+  const entries = listRunStateDirs(stateRoot)
+    .flatMap((stateDir) => {
+      try {
+        return [indexEntryFromStatus(getRunStatus(stateDir))];
+      } catch {
+        return [];
+      }
+    })
+    .sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? ""));
+  writeJsonAtomic(runIndexPath(stateRoot), {
+    entries,
+    rebuilt_at: new Date().toISOString(),
+  });
+  return entries;
+}
+
+export function readRunStateIndex(
+  stateRoot: string,
+  readJson: (path: string) => Record<string, unknown> | undefined,
+): RunStateIndexEntry[] | undefined {
+  const index = readJson(runIndexPath(stateRoot));
+  if (!index || typeof index !== "object") return undefined;
+  const entries = (index as Record<string, unknown>).entries;
+  if (!Array.isArray(entries)) return undefined;
+  const valid = entries.filter((entry): entry is RunStateIndexEntry => {
+    const record =
+      entry && typeof entry === "object"
+        ? (entry as Record<string, unknown>)
+        : {};
+    return (
+      typeof record.run === "string" &&
+      typeof record.state_dir === "string" &&
+      typeof record.status === "string"
+    );
+  });
+  if (valid.some((entry) => !existsSync(join(entry.state_dir, "run.json"))))
+    return undefined;
+  const indexedDirs = new Set(valid.map((entry) => resolve(entry.state_dir)));
+  const stateDirs = listRunStateDirs(stateRoot).map((stateDir) =>
+    resolve(stateDir),
+  );
+  if (stateDirs.some((stateDir) => !indexedDirs.has(stateDir)))
+    return undefined;
+  return valid;
+}
+
+function compactIndexEntry(entry: RunStateIndexEntry): Record<string, unknown> {
+  return {
+    run: entry.run,
+    state_dir: entry.state_dir,
+    status: entry.status,
+    ...(entry.tool ? { tool: entry.tool } : {}),
+    ...(entry.recipe ? { recipe: entry.recipe } : {}),
+  };
+}
+
+export function listRuns(
+  stateRoot: string,
+  getRunStatus: RunStatusReader,
+  readJson: (path: string) => Record<string, unknown> | undefined,
+  statusFilter?: string,
+): Array<Record<string, unknown>> {
+  if (!existsSync(stateRoot)) return [];
+  const indexed = readRunStateIndex(stateRoot, readJson);
+  const entries = indexed ?? rebuildRunStateIndex(stateRoot, getRunStatus);
+  return entries
+    .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
+    .map(compactIndexEntry);
+}