pi-extensible-workflows 2.0.0 → 3.1.0

package/src/budget.ts

@@ -0,0 +1,75 @@
+import { WorkflowError, type BudgetDimension, type BudgetEvent, type BudgetLimits, type WorkflowBudget, type WorkflowBudgetPatch, type WorkflowBudgetUsage, type AgentAccounting, type RunState } from "./types.js";
+import { fail, object } from "./utils.js";
+
+function nonNegativeInteger(value: unknown): value is number { return Number.isInteger(value) && (value as number) >= 0; }
+function nonNegativeFinite(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+export function validateBudget(value: unknown): WorkflowBudget | undefined {
+  if (value === undefined) return undefined;
+  if (!object(value)) fail("INVALID_METADATA", "budget must be an object");
+  const result: WorkflowBudget = {};
+  for (const [dimension, raw] of Object.entries(value)) {
+    if (!["tokens", "costUsd", "durationMs", "agentLaunches"].includes(dimension)) fail("INVALID_METADATA", `Unknown budget dimension: ${dimension}`);
+    if (!object(raw)) fail("INVALID_METADATA", `${dimension} budget must be an object`);
+    if (Object.keys(raw).some((key) => key !== "soft" && key !== "hard")) fail("INVALID_METADATA", `${dimension} budget has an unknown limit`);
+    const isCost = dimension === "costUsd";
+    for (const key of ["soft", "hard"] as const) if (raw[key] !== undefined && !(isCost ? nonNegativeFinite(raw[key]) : nonNegativeInteger(raw[key]))) fail("INVALID_METADATA", `${dimension}.${key} must be a non-negative ${isCost ? "finite number" : "integer"}`);
+    if (raw.soft !== undefined && raw.soft !== null && raw.hard !== undefined && raw.hard !== null && raw.soft >= raw.hard) fail("INVALID_METADATA", `${dimension}.soft must be less than hard`);
+    const limits: BudgetLimits = {};
+    if (raw.soft !== undefined) limits.soft = raw.soft as number;
+    if (raw.hard !== undefined) limits.hard = raw.hard as number;
+    if (Object.keys(limits).length) (result as Record<string, BudgetLimits>)[dimension] = limits;
+  }
+  return Object.freeze(result);
+}
+export function validateBudgetPatch(value: unknown): WorkflowBudgetPatch {
+  if (!object(value)) fail("INVALID_METADATA", "budget patch must be an object");
+  const result: WorkflowBudgetPatch = {};
+  for (const [dimension, raw] of Object.entries(value)) {
+    if (!["tokens", "costUsd", "durationMs", "agentLaunches"].includes(dimension)) fail("INVALID_METADATA", `Unknown budget dimension: ${dimension}`);
+    if (raw === null) { (result as Record<string, null>)[dimension] = null; continue; }
+    if (!object(raw) || Object.keys(raw).some((key) => key !== "soft" && key !== "hard")) fail("INVALID_METADATA", `${dimension} budget patch must contain only soft and hard`);
+    const limits: { soft?: number | null; hard?: number | null } = {};
+    for (const key of ["soft", "hard"] as const) if (Object.prototype.hasOwnProperty.call(raw, key)) {
+      if (raw[key] === null) limits[key] = null;
+      else { const checked = validateBudget({ [dimension]: { [key]: raw[key] } })?.[dimension as BudgetDimension]; if (checked?.[key] !== undefined) limits[key] = checked[key]; }
+    }
+    if (limits.soft !== null && limits.hard !== null && limits.soft !== undefined && limits.hard !== undefined && limits.soft >= limits.hard) fail("INVALID_METADATA", `${dimension}.soft must be less than hard`);
+    (result as Record<string, { soft?: number | null; hard?: number | null }>)[dimension] = limits;
+  }
+  return result;
+}
+export function budgetUsage(value?: Partial<WorkflowBudgetUsage>): WorkflowBudgetUsage { return { tokens: value?.tokens ?? 0, costUsd: value?.costUsd ?? 0, durationMs: value?.durationMs ?? 0, agentLaunches: value?.agentLaunches ?? 0 }; }
+export class WorkflowBudgetRuntime {
+  readonly #now: () => number;
+  readonly #onChange: (() => void) | undefined;
+  readonly #injected = new Set<string>();
+  readonly #seen = new Set<string>();
+  #active: boolean;
+  #activeSince: number | undefined;
+  #usage: WorkflowBudgetUsage;
+  #events: BudgetEvent[];
+  #turnAccounting?: { input: number; output: number; cost: number };
+  constructor(readonly budget: WorkflowBudget | undefined, readonly version = 1, usage?: Partial<WorkflowBudgetUsage>, events: readonly BudgetEvent[] = [], options: { now?: () => number; onChange?: () => void; active?: boolean } = {}) { this.#now = options.now ?? (() => Date.now()); this.#onChange = options.onChange; this.#active = options.active ?? true; this.#activeSince = this.#active ? this.#now() : undefined; this.#usage = budgetUsage(usage); this.#events = [...events]; for (const event of events) if (event.budgetVersion === version) this.#seen.add(event.type); }
+  get usage(): WorkflowBudgetUsage { this.#syncDuration(); return { ...this.#usage }; }
+  get events(): readonly BudgetEvent[] { return this.#events; }
+  get hardExhausted(): boolean { return this.#events.some((event) => event.type === "hard_exhausted" && event.budgetVersion === this.version); }
+  checkAgentLaunch(): void { this.#checkHard(["agentLaunches"]); }
+  beforeAttempt(): void { this.#checkHard(["agentLaunches"]); this.#usage.agentLaunches += 1; this.#evaluate(); }
+  beforeTurn(): void { this.#syncDuration(); this.#evaluate(); this.#checkHard(["tokens", "costUsd", "durationMs"]); }
+  afterTurn(accounting: AgentAccounting, final: boolean): void { this.#syncDuration(); this.#applyTurn(accounting, final, this.#turnAccounting); this.#turnAccounting = { input: accounting.input, output: accounting.output, cost: accounting.cost }; }
+  #applyTurn(accounting: AgentAccounting, final: boolean, previous = { input: 0, output: 0, cost: 0 }): void { this.#usage.tokens += Math.max(0, accounting.input - previous.input) + Math.max(0, accounting.output - previous.output); this.#usage.costUsd += Math.max(0, accounting.cost - previous.cost); this.#evaluate(); if (!final) this.#checkHard(["tokens", "costUsd", "durationMs"]); }
+  instruction(agentId = "agent"): string | undefined { if (!this.#hasSoftCrossed() || this.#injected.has(agentId)) return undefined; this.#injected.add(agentId); return `The workflow budget soft limit has been reached. Finish the requested output now, preserving any required output schema. Current usage: ${JSON.stringify(this.usage)}. Do not start additional model work unless it is required to produce the final requested result.`; }
+  forAgent(agentId: string) { let attempt = 0; let previous: { input: number; output: number; cost: number } | undefined; return { beforeAttempt: () => { attempt += 1; previous = undefined; this.beforeAttempt(); }, beforeTurn: () => { this.beforeTurn(); }, afterTurn: (accounting: AgentAccounting, final: boolean) => { this.#applyTurn(accounting, final, previous); previous = { input: accounting.input, output: accounting.output, cost: accounting.cost }; }, instruction: () => this.instruction(`${agentId}:${String(attempt + 1)}`) }; }
+  transition(state: RunState): void { const active = state === "running"; if (active === this.#active) return; if (active) { this.#active = true; this.#activeSince = this.#now(); } else { this.#syncDuration(); this.#evaluate(); this.#active = false; this.#activeSince = undefined; } this.#onChange?.(); }
+  #syncDuration(): void { if (this.#active && this.#activeSince !== undefined) { const now = this.#now(); this.#usage.durationMs += Math.max(0, now - this.#activeSince); this.#activeSince = now; } }
+  #hasSoftCrossed(): boolean { return !!this.budget && (Object.entries(this.budget) as [BudgetDimension, BudgetLimits][]).some(([dimension, limits]) => limits.soft !== undefined && this.#usage[dimension] >= limits.soft); }
+  #checkHard(dimensions: readonly BudgetDimension[]): void { const exhausted = dimensions.filter((dimension) => { const hard = this.budget?.[dimension]?.hard; return hard !== undefined && this.#usage[dimension] >= hard; }); if (!exhausted.length) return; this.#record("hard_exhausted", exhausted); const detail = exhausted.map((dimension) => `${dimension} usage=${String(this.#usage[dimension])} hard=${String(this.budget?.[dimension]?.hard)}`).join(", "); throw new WorkflowError("BUDGET_EXHAUSTED", `Budget version ${String(this.version)} exhausted: ${detail}`); }
+  #evaluate(): void { const budget = this.budget; if (!budget) return; const soft = (Object.keys(budget) as BudgetDimension[]).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.soft !== undefined && this.#usage[dimension] >= limits.soft; }); if (soft.length) this.#record("soft_crossed", soft); const overrun = (Object.keys(budget) as BudgetDimension[]).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.hard !== undefined && this.#usage[dimension] > limits.hard; }); if (overrun.length) this.#record("hard_overrun", overrun); }
+  #record(type: BudgetEvent["type"], dimensions: readonly BudgetDimension[]): void { if (this.#seen.has(type)) return; this.#seen.add(type); this.#events.push({ type, budgetVersion: this.version, dimensions: [...dimensions], usage: this.usage, limits: structuredClone(this.budget ?? {}), at: this.#now() }); this.#onChange?.(); }
+  recordEvent(event: BudgetEvent): void { this.#events.push(structuredClone(event)); }
+  snapshot(): { usage: WorkflowBudgetUsage; budgetEvents: readonly BudgetEvent[] } { return { usage: this.usage, budgetEvents: [...this.#events] }; }
+}
+export function mergeBudget(budget: WorkflowBudget | undefined, patch: WorkflowBudgetPatch): WorkflowBudget | undefined { const merged: WorkflowBudget = structuredClone(budget ?? {}); for (const dimension of ["tokens", "costUsd", "durationMs", "agentLaunches"] as const) if (Object.prototype.hasOwnProperty.call(patch, dimension)) { const value = patch[dimension]; if (value === null) { Reflect.deleteProperty(merged, dimension); continue; } const next: BudgetLimits = { ...(merged[dimension] ?? {}) }; for (const key of ["soft", "hard"] as const) if (value && Object.prototype.hasOwnProperty.call(value, key)) { const limit = value[key]; if (limit === null) Reflect.deleteProperty(next, key); else if (limit !== undefined) next[key] = limit; } if (Object.keys(next).length) (merged as Record<string, BudgetLimits>)[dimension] = next; else Reflect.deleteProperty(merged, dimension); } return validateBudget(merged); }
+export function budgetRelaxed(previous: WorkflowBudget | undefined, next: WorkflowBudget | undefined): boolean { for (const dimension of ["tokens", "costUsd", "durationMs", "agentLaunches"] as const) { const oldLimit = previous?.[dimension]; const newLimit = next?.[dimension]; for (const key of ["soft", "hard"] as const) if ((oldLimit?.[key] !== undefined && newLimit?.[key] === undefined) || (oldLimit?.[key] !== undefined && newLimit?.[key] !== undefined && newLimit[key] > oldLimit[key])) return true; } return false; }
+export function exhaustedBudgetDimensions(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): BudgetDimension[] { if (!budget) return []; return (Object.keys(budget) as BudgetDimension[]).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.hard !== undefined && usage[dimension] >= limits.hard; }); }
+export function resumeBudgetAllowed(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): boolean { return exhaustedBudgetDimensions(budget, usage).length === 0; }

package/src/cli.ts

@@ -7,7 +7,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { ProjectTrustStore, SessionManager, SettingsManager, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, hasTrustRequiringProjectResources, type LoadExtensionsResult } from "@earendil-works/pi-coding-agent";
 import { Value } from "typebox/value";
 import { doctor, doctorExitCode, formatDoctorReport, type DoctorOptions } from "./doctor.js";
-import workflowExtension, { formatWorkflowProgress, workflowCatalog, type JsonSchema, type JsonValue } from "./index.js";
+import { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport, type DoctorCleanupOptions } from "./doctor-cleanup.js";
+import workflowExtension, { formatWorkflowProgress, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath, type JsonSchema, type JsonValue, type WorkflowProgressStyles } from "./index.js";
 import { runSessionInspector, transcriptFileLines } from "./session-inspector.js";
 import type { PersistedRun } from "./persistence.js";
 import type { WorkflowCatalogFunction } from "./index.js";
@@ -158,6 +159,26 @@ function launcherHelpLines(): string[] {
 }
 function workflowUsage(): string { return [`Usage: pi-extensible-workflows run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
 function exportUsage(): string { return [`Usage: pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
+export function parseDoctorCleanupArgs(rawArgs: readonly string[]): Required<Pick<DoctorCleanupOptions, "olderThanDays" | "yes">> {
+  let olderThanDays = 90;
+  let yes = false;
+  let seenDays = false;
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const token = rawArgs[index] as string;
+    if (token === "--yes") { yes = true; continue; }
+    const inline = token.startsWith("--older-than-days=") ? token.slice("--older-than-days=".length) : undefined;
+    if (token === "--older-than-days" || inline !== undefined) {
+      if (seenDays) throw new Error("--older-than-days may only be provided once");
+      const raw = inline ?? rawArgs[++index];
+      if (raw === undefined || !/^[1-9]\d*$/.test(raw)) throw new Error("older-than-days must be a positive integer");
+      const parsed = Number(raw);
+      if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error("older-than-days must be a positive integer");
+      olderThanDays = parsed; seenDays = true; continue;
+    }
+    throw new Error(`Unknown cleanup option: ${token}`);
+  }
+  return { olderThanDays, yes };
+}
 function stripTrustOptions(rawArgs: readonly string[]): { args: string[]; trustOverride?: boolean } {
   const args: string[] = [];
   let trustOverride: boolean | undefined;
@@ -233,7 +254,7 @@ async function createWorkflowRuntime(options: WorkflowIo, shutdownHandlers: Shut
   workflowExtension(headlessPi as never, homedir(), undefined, undefined, agentDir);
   const workflowTool = tools.find((tool) => object(tool) && tool.name === "workflow") as HeadlessWorkflowTool | undefined;
   if (!workflowTool) throw new Error("The workflow runtime could not be initialized");
-  return { catalog: workflowCatalog(), services, workflowTool, shutdownHandlers };
+  return { catalog: workflowCatalog({ cwd, projectTrusted: settingsManager.isProjectTrusted(), globalSettingsPath: workflowSettingsPath(agentDir) }), services, workflowTool, shutdownHandlers };
 }
 
 function availableModelInfo(services: WorkflowRuntime["services"], available = false): { provider: string; id: string }[] {
@@ -274,16 +295,25 @@ function writeLauncher(destination: string, workflowName: string, force: boolean
 }
 
 
+function terminalProgressStyles(enabled: boolean): WorkflowProgressStyles {
+  const style = (code: number) => enabled ? (text: string) => `\x1b[${String(code)}m${text}\x1b[0m` : (text: string) => text;
+  return { accent: style(36), success: style(32), error: style(31), warning: style(33), muted: style(90), dim: style(2), bold: style(1) };
+}
 class CliProgress {
   #lastStable = "";
   #lines = 0;
   #frame = 0;
   #run: PersistedRun | undefined;
   #timer: ReturnType<typeof setInterval> | undefined;
-  constructor(private readonly stderr: (text: string) => void, private readonly tty: boolean) {}
+  #interactive: boolean;
+  #styles: WorkflowProgressStyles;
+  constructor(private readonly stderr: (text: string) => void, tty: boolean) {
+    this.#interactive = tty && process.env.NO_COLOR === undefined && process.env.TERM !== "dumb";
+    this.#styles = terminalProgressStyles(this.#interactive);
+  }
   update(run: PersistedRun): void {
-    const stable = formatWorkflowProgress(run, "◇");
-    if (!this.tty) { if (stable !== this.#lastStable) { this.#lastStable = stable; this.stderr(`${stable}\n`); } return; }
+    const stable = formatWorkflowProgress(run, "◇", this.#styles);
+    if (!this.#interactive) { if (stable !== this.#lastStable) { this.#lastStable = stable; this.stderr(`${stable}\n`); } return; }
     this.#run = run;
     this.#timer ??= setInterval(() => { this.render(); }, 80);
     this.#timer.unref();
@@ -293,13 +323,13 @@ class CliProgress {
     if (!this.#run) return;
     const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"][this.#frame++ % 10] ?? "◇";
     const width = process.stderr.columns || 80;
-    const text = formatWorkflowProgress(this.#run, spinner).split("\n").map((line) => line.length <= width ? line : `${line.slice(0, Math.max(0, width - 1))}…`).join("\n");
+    const text = truncateWorkflowProgress(formatWorkflowProgress(this.#run, spinner, this.#styles), width).join("\n");
     this.stderr(`${this.#lines ? `\x1b[${String(this.#lines)}A` : ""}${this.#lines ? "" : "\x1b[?25l"}\x1b[0J${text}\n`);
     this.#lines = text.split("\n").length;
   }
   finish(): void {
     if (this.#timer) { clearInterval(this.#timer); this.#timer = undefined; }
-    if (this.tty && this.#lines) { this.stderr(`\x1b[${String(this.#lines)}A\x1b[0J\x1b[?25h`); this.#lines = 0; }
+    if (this.#interactive && this.#lines) { this.stderr(`\x1b[${String(this.#lines)}A\x1b[0J\x1b[?25h`); this.#lines = 0; }
     this.#run = undefined;
   }
 }
@@ -406,6 +436,16 @@ export async function runCli(args: readonly string[], options: CliOptions = {},
     write(formatDoctorReport(report));
     return doctorExitCode(report);
   }
+  if (args[0] === "doctor" && args[1] === "cleanup") {
+    if (args.slice(2).some((arg) => arg === "--help" || arg === "-h")) { write("Usage: pi-extensible-workflows doctor cleanup [--older-than-days <days>] [--yes]\n"); return 0; }
+    try {
+      const parsed = parseDoctorCleanupArgs(args.slice(2));
+      const cleanupOptions: DoctorCleanupOptions = { ...parsed, ...(options.cwd !== undefined ? { cwd: options.cwd } : {}) };
+      const report = await doctorCleanup(cleanupOptions);
+      write(formatDoctorCleanupReport(report));
+      return doctorCleanupExitCode(report);
+    } catch (error) { stderr(`Error: ${error instanceof Error ? error.message : String(error)}\n`); return 1; }
+  }
   if (args[0] === "inspect" && args.length <= 2) {
     try { await (options.inspect ?? runSessionInspector)(args[1]); return 0; }
     catch (error) { write(`Error: ${error instanceof Error ? error.message : String(error)}\n`); return 1; }

package/src/doctor-cleanup.ts

@@ -0,0 +1,337 @@
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { validateBudget } from "./budget.js";
+import { RUN_STATES, type RunState } from "./types.js";
+import { jsonValue, validateModelAliases } from "./utils.js";
+import { validateSchema } from "./validation.js";
+import { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, RunStore, type PersistedRun, type SessionLease } from "./persistence.js";
+
+const TERMINAL_STATES = new Set<RunState>(["completed", "failed", "stopped"]);
+const DAY_MS = 24 * 60 * 60 * 1000;
+const REQUIRED_RUN_FILES = ["workflow.js", "state.json", "snapshot.json", "journal.json", "ownership.json", "worktrees.json", "borrowed-worktrees.json", "system-prompts.json"] as const;
+const OPTIONAL_RUN_FILES = new Set(["result.json"]);
+const RUN_DIRECTORIES = new Set(["worktrees"]);
+const RUN_FILES = new Set<string>([...REQUIRED_RUN_FILES, ...OPTIONAL_RUN_FILES]);
+const AGENT_STATES = new Set(["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"]);
+const SCHEDULER_STATES = new Set(["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"]);
+const BUDGET_DIMENSIONS = new Set(["tokens", "costUsd", "durationMs", "agentLaunches"]);
+const BUDGET_EVENT_TYPES = new Set(["soft_crossed", "hard_overrun", "hard_exhausted", "adjustment_requested", "adjustment_approved", "adjustment_rejected"]);
+
+export interface DoctorCleanupOptions { cwd?: string; home?: string; olderThanDays?: number; yes?: boolean; now?: number }
+export interface CleanupRunResult { sessionId: string; runId: string; action: "candidate" | "skipped" | "deleted" | "failed"; state: string; stateMtimeMs: number; path: string; reason?: string }
+export interface CleanupFailure { sessionId: string; runId?: string; message: string }
+export interface CleanupSessionReport { sessionId: string; path: string; status: "preview" | "cleaned" | "skipped" | "failed"; reason?: string }
+export interface DoctorCleanupReport { cwd: string; cutoffMs: number; olderThanDays: number; yes: boolean; sessions: readonly CleanupSessionReport[]; candidates: readonly CleanupRunResult[]; skipped: readonly CleanupRunResult[]; deleted: readonly CleanupRunResult[]; failures: readonly CleanupFailure[] }
+
+type StoredRun = { sessionId: string; runId: string; store: RunStore; run: PersistedRun; stateMtimeMs: number; dependencies: readonly string[] };
+type SessionScan = { sessionId: string; path: string; runs: readonly StoredRun[]; liveLease: boolean };
+type SessionPlan = { candidates: readonly StoredRun[]; skipped: readonly CleanupRunResult[] };
+
+function object(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function textError(error: unknown): string { return error instanceof Error ? error.message : String(error); }
+function positiveDays(value: number): number { if (!Number.isSafeInteger(value) || value < 1 || !Number.isFinite(value * DAY_MS)) throw new Error("older-than-days must be a positive integer"); return value; }
+function runItem(entry: StoredRun, action: CleanupRunResult["action"], reason?: string): CleanupRunResult { return { sessionId: entry.sessionId, runId: entry.runId, action, state: entry.run.state, stateMtimeMs: entry.stateMtimeMs, path: entry.store.directory, ...(reason ? { reason } : {}) }; }
+function sameNames(left: readonly string[], right: readonly string[]): boolean { return left.length === right.length && left.every((value, index) => value === right[index]); }
+async function jsonFile(path: string): Promise<unknown> { return JSON.parse(await readFile(path, "utf8")) as unknown; }
+async function requiredFile(path: string): Promise<void> { const info = await lstat(path); if (!info.isFile()) throw new Error(`Required artifact is not a regular file: ${path}`); }
+function stringList(value: unknown, label: string, nonEmpty = false): void { if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || (nonEmpty && !item))) throw new Error(`${label} is invalid`); }
+function optionalString(value: unknown, label: string): void { if (value !== undefined && typeof value !== "string") throw new Error(`${label} is invalid`); }
+function nonNegativeInteger(value: unknown, label: string): void { if (!Number.isSafeInteger(value) || (value as number) < 0) throw new Error(`${label} is invalid`); }
+function positiveInteger(value: unknown, label: string): void { if (!Number.isSafeInteger(value) || (value as number) < 1) throw new Error(`${label} is invalid`); }
+function finiteNumber(value: unknown, label: string): void { if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`${label} is invalid`); }
+function model(value: unknown, label: string): void { if (!object(value) || typeof value.provider !== "string" || !value.provider || typeof value.model !== "string" || !value.model || (value.thinking !== undefined && !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value.thinking as string))) throw new Error(`${label} is invalid`); }
+function accounting(value: unknown, label: string): void { if (!object(value)) throw new Error(`${label} is invalid`); for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost"]) finiteNumber(value[key], `${label}.${key}`); }
+function resourceExclusions(value: unknown, label: string): void { if (value === undefined) return; if (!object(value)) throw new Error(`${label} is invalid`); if (value.skills !== undefined) stringList(value.skills, `${label}.skills`); if (value.extensions !== undefined) stringList(value.extensions, `${label}.extensions`); }
+function agentDefinition(value: unknown, label: string): void { if (!object(value)) throw new Error(`${label} is invalid`); optionalString(value.prompt, `${label}.prompt`); optionalString(value.description, `${label}.description`); optionalString(value.model, `${label}.model`); if (value.thinking !== undefined && !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value.thinking as string)) throw new Error(`${label}.thinking is invalid`); if (value.tools !== undefined) stringList(value.tools, `${label}.tools`); resourceExclusions(value.disabledAgentResources, `${label}.disabledAgentResources`); }
+function validateScheduledOptions(value: unknown, label: string): void { if (!object(value) || typeof value.label !== "string" || !value.label || typeof value.cwd !== "string" || !value.cwd) throw new Error(`${label} is invalid`); optionalString(value.requestedLabel, `${label}.requestedLabel`); optionalString(value.parentBreadcrumb, `${label}.parentBreadcrumb`); stringList(value.tools, `${label}.tools`); optionalString(value.worktreeOwner, `${label}.worktreeOwner`); optionalString(value.model, `${label}.model`); if (value.thinking !== undefined && !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value.thinking as string)) throw new Error(`${label}.thinking is invalid`); optionalString(value.role, `${label}.role`); if (value.schema !== undefined) validateSchema(value.schema, `${label}.schema`); if (value.retries !== undefined) nonNegativeInteger(value.retries, `${label}.retries`); if (value.timeoutMs !== undefined && value.timeoutMs !== null) positiveInteger(value.timeoutMs, `${label}.timeoutMs`); if (value.agentOptions !== undefined && (!object(value.agentOptions) || !jsonValue(value.agentOptions))) throw new Error(`${label}.agentOptions is invalid`); if (value.agentIdentity !== undefined) { if (!object(value.agentIdentity) || !Array.isArray(value.agentIdentity.structuralPath) || value.agentIdentity.structuralPath.some((part) => typeof part !== "string") || typeof value.agentIdentity.callSite !== "string") throw new Error(`${label}.agentIdentity is invalid`); positiveInteger(value.agentIdentity.occurrence, `${label}.agentIdentity.occurrence`); optionalString(value.agentIdentity.parentBreadcrumb, `${label}.agentIdentity.parentBreadcrumb`); optionalString(value.agentIdentity.worktreeOwner, `${label}.agentIdentity.worktreeOwner`); } }
+function validateAgent(value: unknown, label: string): void { if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.name !== "string" || !value.name || typeof value.path !== "string" || !value.path || typeof value.state !== "string" || !AGENT_STATES.has(value.state)) throw new Error(`${label} is invalid`); optionalString(value.label, `${label}.label`); optionalString(value.parentId, `${label}.parentId`); if (value.structuralPath !== undefined) stringList(value.structuralPath, `${label}.structuralPath`); optionalString(value.parentBreadcrumb, `${label}.parentBreadcrumb`); optionalString(value.worktreeOwner, `${label}.worktreeOwner`); optionalString(value.role, `${label}.role`); optionalString(value.requestedModel, `${label}.requestedModel`); model(value.model, `${label}.model`); stringList(value.tools, `${label}.tools`); nonNegativeInteger(value.attempts, `${label}.attempts`); if (value.attemptDetails !== undefined) { if (!Array.isArray(value.attemptDetails)) throw new Error(`${label}.attemptDetails is invalid`); for (const [index, attempt] of value.attemptDetails.entries()) { const at = `${label}.attemptDetails[${String(index)}]`; if (!object(attempt) || !Number.isSafeInteger(attempt.attempt) || Number(attempt.attempt) < 1 || typeof attempt.sessionId !== "string" || !attempt.sessionId || typeof attempt.sessionFile !== "string" || !attempt.sessionFile) throw new Error(`${at} is invalid`); accounting(attempt.accounting, `${at}.accounting`); if (attempt.error !== undefined && (!object(attempt.error) || typeof attempt.error.code !== "string" || typeof attempt.error.message !== "string")) throw new Error(`${at}.error is invalid`); if (attempt.setup !== undefined) { if (!object(attempt.setup) || !Array.isArray(attempt.setup.hookNames) || attempt.setup.hookNames.some((name) => typeof name !== "string") || typeof attempt.setup.cwd !== "string") throw new Error(`${at}.setup is invalid`); model(attempt.setup.model, `${at}.setup.model`); stringList(attempt.setup.tools, `${at}.setup.tools`); resourceExclusions(attempt.setup.disabledAgentResources, `${at}.setup.disabledAgentResources`); } } } if (value.accounting !== undefined) accounting(value.accounting, `${label}.accounting`); if (value.toolCalls !== undefined) { if (!Array.isArray(value.toolCalls)) throw new Error(`${label}.toolCalls is invalid`); for (const call of value.toolCalls) if (!object(call) || typeof call.id !== "string" || typeof call.name !== "string" || !["running", "completed", "failed"].includes(call.state as string)) throw new Error(`${label}.toolCalls is invalid`); } if (value.activity !== undefined && (!object(value.activity) || !["reasoning", "tool", "text"].includes(value.activity.kind as string) || typeof value.activity.text !== "string")) throw new Error(`${label}.activity is invalid`); }
+function validateUsage(value: unknown, label: string): void { if (!object(value)) throw new Error(`${label} is invalid`); for (const key of ["tokens", "costUsd", "durationMs", "agentLaunches"]) finiteNumber(value[key], `${label}.${key}`); }
+function validateBudgetEvents(value: unknown): void { if (value === undefined) return; if (!Array.isArray(value)) throw new Error("Persisted budget events are invalid"); for (const [index, event] of value.entries()) { const label = `budgetEvents[${String(index)}]`; if (!object(event) || typeof event.type !== "string" || !BUDGET_EVENT_TYPES.has(event.type) || !Number.isSafeInteger(event.budgetVersion) || Number(event.budgetVersion) < 1 || !Array.isArray(event.dimensions) || event.dimensions.some((dimension) => typeof dimension !== "string" || !BUDGET_DIMENSIONS.has(dimension)) || typeof event.at !== "number" || !Number.isFinite(event.at) || event.limits === undefined) throw new Error(`${label} is invalid`); validateUsage(event.usage, `${label}.usage`); validateBudget(event.limits); } }
+function validateRunRecord(run: PersistedRun): void {
+  const value = run as unknown;
+  if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.workflowName !== "string" || !value.workflowName || typeof value.cwd !== "string" || !value.cwd || typeof value.sessionId !== "string" || !value.sessionId || !RUN_STATES.includes(value.state as RunState) || !Array.isArray(value.agents) || !Array.isArray(value.nativeSessions)) throw new Error("Persisted run state is invalid");
+  const agents = value.agents as Record<string, unknown>[];
+  agents.forEach((agent, index) => { validateAgent(agent, `agents[${String(index)}]`); });
+  const agentIds = new Set<string>();
+  for (const agent of agents) {
+    const id = agent.id as string;
+    if (agentIds.has(id)) throw new Error(`Duplicate persisted agent ${id}`);
+    agentIds.add(id);
+  }
+  for (const agent of agents) {
+    const parentId = agent.parentId;
+    if (parentId !== undefined && (typeof parentId !== "string" || !agentIds.has(parentId))) throw new Error("Persisted agent has a missing parent");
+    const seen = new Set<string>();
+    let parent = typeof parentId === "string" ? parentId : undefined;
+    while (parent) {
+      if (seen.has(parent)) throw new Error("Persisted agent parent cycle");
+      seen.add(parent);
+      const parentAgent = agents.find((candidate) => candidate.id === parent);
+      parent = typeof parentAgent?.parentId === "string" ? parentAgent.parentId : undefined;
+    }
+  }
+  for (const [index, session] of (value.nativeSessions as unknown[]).entries()) if (!object(session) || typeof session.sessionId !== "string" || !session.sessionId || typeof session.sessionFile !== "string" || !session.sessionFile) throw new Error(`nativeSessions[${String(index)}] is invalid`);
+  optionalString(value.parentRunId, "Persisted parent run");
+  if (value.retry !== undefined) {
+    if (!object(value.retry) || typeof value.retry.sourceRunId !== "string" || !value.retry.sourceRunId || typeof value.retry.lineageRootRunId !== "string" || !value.retry.lineageRootRunId) throw new Error("Persisted retry provenance is invalid");
+    const sourceRunId = value.retry.sourceRunId;
+    stringList(value.retry.completedPaths, "Persisted retry completed paths");
+    stringList(value.retry.incompletePaths, "Persisted retry incomplete paths");
+    stringList(value.retry.namedWorktrees, "Persisted retry named worktrees");
+    if (value.parentRunId !== sourceRunId) throw new Error("Persisted retry parent does not match its source");
+  }
+  optionalString(value.phase, "Persisted phase");
+  if (value.phaseHistory !== undefined) {
+    if (!Array.isArray(value.phaseHistory)) throw new Error("Persisted phase history is invalid");
+    for (const phase of value.phaseHistory) { if (!object(phase) || typeof phase.phase !== "string" || !phase.phase) throw new Error("Persisted phase history is invalid"); nonNegativeInteger(phase.afterAgent, "Persisted phase history afterAgent"); }
+  }
+  if (value.error !== undefined && (!object(value.error) || typeof value.error.code !== "string" || typeof value.error.message !== "string")) throw new Error("Persisted run error is invalid");
+  validateBudget(value.budget);
+  if (value.budgetVersion !== undefined) positiveInteger(value.budgetVersion, "Persisted budget version");
+  if (value.usage !== undefined) validateUsage(value.usage, "Persisted usage");
+  validateBudgetEvents(value.budgetEvents);
+  if (value.events !== undefined) { if (!Array.isArray(value.events)) throw new Error("Persisted run events are invalid"); for (const event of value.events) if (!object(event) || typeof event.type !== "string" || typeof event.message !== "string") throw new Error("Persisted run event is invalid"); }
+}
+function validateSnapshot(snapshot: unknown): void {
+  if (!object(snapshot) || typeof snapshot.script !== "string" || !snapshot.script || !jsonValue(snapshot.args) || !object(snapshot.metadata) || typeof snapshot.metadata.name !== "string" || !snapshot.metadata.name || (snapshot.metadata.description !== undefined && typeof snapshot.metadata.description !== "string") || !object(snapshot.settings) || !Number.isSafeInteger(snapshot.settings.concurrency) || Number(snapshot.settings.concurrency) < 1 || Number(snapshot.settings.concurrency) > 16 || !Array.isArray(snapshot.models) || snapshot.models.some((modelName) => typeof modelName !== "string") || !Array.isArray(snapshot.tools) || snapshot.tools.some((tool) => typeof tool !== "string") || !Array.isArray(snapshot.agentTypes) || snapshot.agentTypes.some((agentType) => typeof agentType !== "string") || !Array.isArray(snapshot.schemas)) throw new Error("Persisted launch snapshot is invalid");
+  if (snapshot.identityVersion !== undefined) positiveInteger(snapshot.identityVersion, "Persisted snapshot identity version");
+  if (snapshot.launchKind !== undefined && !["inline", "function"].includes(snapshot.launchKind as string)) throw new Error("Persisted snapshot launch kind is invalid");
+  if (snapshot.launchKind === "function" && (typeof snapshot.functionName !== "string" || !snapshot.functionName)) throw new Error("Persisted snapshot function name is invalid");
+  optionalString(snapshot.functionName, "Persisted snapshot function name");
+  optionalString(snapshot.settingsPath, "Persisted snapshot settings path");
+  if (snapshot.settingsSources !== undefined) { if (!object(snapshot.settingsSources) || typeof snapshot.settingsSources.concurrency !== "string" || typeof snapshot.settingsSources.modelAliases !== "string" || typeof snapshot.settingsSources.disabledAgentResources !== "string") throw new Error("Persisted snapshot settings sources are invalid"); }
+  validateBudget(snapshot.budget);
+  if (snapshot.modelAliases !== undefined) validateModelAliases(snapshot.modelAliases);
+  if (snapshot.settings.modelAliases !== undefined) validateModelAliases(snapshot.settings.modelAliases);
+  if (snapshot.phases !== undefined) stringList(snapshot.phases, "Persisted snapshot phases");
+  resourceExclusions(snapshot.settings.disabledAgentResources, "Persisted snapshot disabled resources");
+  if (snapshot.roles !== undefined) { if (!object(snapshot.roles)) throw new Error("Persisted snapshot roles are invalid"); for (const [name, definition] of Object.entries(snapshot.roles)) agentDefinition(definition, `Persisted snapshot role ${name}`); }
+  if (snapshot.projectRoles !== undefined) stringList(snapshot.projectRoles, "Persisted snapshot project roles");
+  for (const [index, schema] of snapshot.schemas.entries()) validateSchema(schema, `Persisted snapshot schema[${String(index)}]`);
+}
+function validateJournal(value: unknown): void { if (!object(value) || !object(value.completed) || (value.awaiting !== undefined && !object(value.awaiting)) || (value.decisions !== undefined && !object(value.decisions))) throw new Error("Persisted workflow journal is invalid"); for (const operation of Object.values(value.completed)) if (!object(operation) || typeof operation.path !== "string" || !operation.path || !jsonValue(operation.value)) throw new Error("Persisted completed operation is invalid"); for (const checkpoint of Object.values(value.awaiting ?? {})) if (!object(checkpoint) || typeof checkpoint.path !== "string" || !checkpoint.path || typeof checkpoint.name !== "string" || !checkpoint.name || typeof checkpoint.prompt !== "string" || !jsonValue(checkpoint.context)) throw new Error("Persisted awaiting checkpoint is invalid"); for (const decision of Object.values(value.decisions ?? {})) { if (!object(decision) || decision.kind !== "budget" || typeof decision.proposalId !== "string" || !decision.proposalId || typeof decision.runId !== "string" || !decision.runId || !object(decision.previous) || !object(decision.proposed) || !Number.isSafeInteger(decision.budgetVersion) || Number(decision.budgetVersion) < 1) throw new Error("Persisted budget decision is invalid"); validateUsage(decision.consumed, "Persisted budget decision usage"); validateBudget(decision.previous); validateBudget(decision.proposed); } }
+function validateSystemPrompts(value: unknown): void {
+  if (!object(value) || value.version !== 1 || !Array.isArray(value.entries)) throw new Error("Persisted system prompts are invalid");
+  for (const [index, entry] of value.entries.entries()) {
+    const label = `system-prompts.entries[${String(index)}]`;
+    if (!object(entry) || typeof entry.sessionId !== "string" || !entry.sessionId || !Number.isSafeInteger(entry.attempt) || Number(entry.attempt) < 1 || !Number.isSafeInteger(entry.turn) || Number(entry.turn) < 1 || typeof entry.prompt !== "string" || typeof entry.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(entry.sha256) || createHash("sha256").update(entry.prompt).digest("hex") !== entry.sha256) throw new Error(`${label} is invalid`);
+  }
+}
+async function validateRunDirectory(store: RunStore): Promise<void> {
+  const entries = await readdir(store.directory, { withFileTypes: true });
+  for (const entry of entries) {
+    if (RUN_DIRECTORIES.has(entry.name)) { if (!entry.isDirectory() || entry.isSymbolicLink()) throw new Error(`Run artifact is not a regular directory: ${join(store.directory, entry.name)}`); continue; }
+    if (!RUN_FILES.has(entry.name)) throw new Error(`Run inventory contains an unrecognized artifact: ${join(store.directory, entry.name)}`);
+    if (!entry.isFile() || entry.isSymbolicLink()) throw new Error(`Run artifact is not a regular file: ${join(store.directory, entry.name)}`);
+  }
+}
+async function validateRunArtifacts(store: RunStore, workflowScript: string, state: RunState): Promise<readonly { sourceRunId: string }[]> {
+  await validateRunDirectory(store);
+  for (const name of REQUIRED_RUN_FILES) await requiredFile(join(store.directory, name));
+  if (await readFile(join(store.directory, "workflow.js"), "utf8") !== workflowScript) throw new Error("Persisted workflow source does not match its launch snapshot");
+  validateSystemPrompts(await jsonFile(join(store.directory, "system-prompts.json")));
+  const result = await jsonFile(join(store.directory, "result.json")).catch((error: unknown) => { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; });
+  if (result === undefined && state === "completed") throw new Error("Completed run result is missing");
+  if (result !== undefined && !jsonValue(result)) throw new Error("Persisted workflow result is invalid");
+  validateJournal(await jsonFile(join(store.directory, "journal.json")));
+  const rawOwnership = await jsonFile(join(store.directory, "ownership.json"));
+  if (!Array.isArray(rawOwnership)) throw new Error("Persisted ownership records are invalid");
+  const ownership = rawOwnership as unknown[];
+  const ownershipIds = new Set<string>();
+  for (const [index, record] of ownership.entries()) {
+    const label = `ownership[${String(index)}]`;
+    if (!object(record) || typeof record.id !== "string" || !record.id || ownershipIds.has(record.id) || typeof record.label !== "string" || !record.label || typeof record.state !== "string" || !SCHEDULER_STATES.has(record.state)) throw new Error(`${label} is invalid`);
+    ownershipIds.add(record.id);
+    optionalString(record.parentId, `${label}.parentId`);
+    validateScheduledOptions(record.options, `${label}.options`);
+  }
+  for (const record of ownership) if (object(record) && record.parentId !== undefined && (typeof record.parentId !== "string" || !ownershipIds.has(record.parentId))) throw new Error("Persisted ownership parent is missing");
+  await store.validateDeletionWorktrees();
+  const borrowed = await store.borrowedWorktrees();
+  await store.validateBorrowedWorktrees();
+  return borrowed.map(({ sourceRunId }) => ({ sourceRunId }));
+}
+
+async function sessionEntries(path: string): Promise<readonly import("node:fs").Dirent[]> {
+  const info = await lstat(path);
+  if (!info.isDirectory()) throw new Error(`Session inventory is not a directory: ${path}`);
+  return readdir(path, { withFileTypes: true });
+}
+
+async function scanSession(cwd: string, sessionId: string, home: string, expectedLease?: SessionLease): Promise<SessionScan> {
+  const path = join(projectSessionsDirectory(cwd, home), sessionId);
+  const rootEntries = await sessionEntries(path);
+  const runsEntry = rootEntries.find((entry) => entry.name === "runs");
+  if (!runsEntry || !runsEntry.isDirectory() || runsEntry.isSymbolicLink()) throw new Error(`Session inventory has no regular runs directory: ${path}`);
+  if (rootEntries.some((entry) => entry.name !== "runs")) throw new Error(`Session inventory contains an unrecognized entry: ${path}`);
+  const runsPath = join(path, "runs");
+  const before = await sessionEntries(runsPath);
+  const runEntries = before.filter((entry) => entry.name !== "owner.json");
+  if (before.some((entry) => entry.name === "owner.json" && entry.isSymbolicLink())) throw new Error(`Session ownership lease is not a regular file: ${runsPath}`);
+  for (const entry of runEntries) if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name.startsWith(".")) throw new Error(`Session inventory contains an unrecognized entry: ${join(runsPath, entry.name)}`);
+  const ownerPath = join(runsPath, "owner.json");
+  let liveLease = false;
+  if (expectedLease && expectedLease.path === ownerPath) {
+    const owned = await jsonFile(ownerPath);
+    if (!object(owned) || owned.token !== expectedLease.token) throw new Error("Session ownership lease changed before deletion");
+  } else liveLease = await hasLiveSessionLease(cwd, sessionId, home);
+  const runs: StoredRun[] = [];
+  for (const entry of runEntries) {
+    const runId = entry.name;
+    const store = new RunStore(cwd, sessionId, runId, home);
+    try {
+      const beforeState = await stat(join(store.directory, "state.json"));
+      const loaded = await store.load();
+      validateRunRecord(loaded.run);
+      validateSnapshot(loaded.snapshot);
+      if (loaded.run.parentRunId !== undefined) await store.validateParentRun(loaded.run.parentRunId);
+      if (loaded.run.retry) await store.validateRetrySource();
+      const borrowed = await validateRunArtifacts(store, loaded.snapshot.script, loaded.run.state);
+      const afterState = await stat(join(store.directory, "state.json"));
+      if (beforeState.mtimeMs !== afterState.mtimeMs) throw new Error("Persisted state changed while scanning");
+      const dependencies = new Set<string>();
+      if (loaded.run.parentRunId !== undefined) dependencies.add(loaded.run.parentRunId);
+      if (loaded.run.retry) { dependencies.add(loaded.run.retry.sourceRunId); dependencies.add(loaded.run.retry.lineageRootRunId); }
+      for (const binding of borrowed) dependencies.add(binding.sourceRunId);
+      if (dependencies.has(runId)) throw new Error("Persisted run depends on itself");
+      runs.push({ sessionId, runId, store, run: loaded.run, stateMtimeMs: afterState.mtimeMs, dependencies: [...dependencies] });
+    } catch (error) { throw new Error(`Run ${runId} is corrupt or incomplete: ${textError(error)}`, { cause: error }); }
+  }
+  const after = await sessionEntries(runsPath);
+  const beforeNames = before.map(({ name }) => name).sort();
+  const afterNames = after.map(({ name }) => name).sort();
+  if (!sameNames(beforeNames, afterNames)) throw new Error("Session inventory changed while scanning");
+  const known = new Set(runs.map(({ runId }) => runId));
+  for (const run of runs) for (const dependency of run.dependencies) if (!known.has(dependency)) throw new Error(`Run ${run.runId} depends on missing run ${dependency}`);
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const visit = (runId: string): void => {
+    if (visiting.has(runId)) throw new Error("Persisted run dependency cycle prevents safe cleanup");
+    if (visited.has(runId)) return;
+    visiting.add(runId);
+    const run = runs.find(({ runId: current }) => current === runId);
+    for (const dependency of run?.dependencies ?? []) visit(dependency);
+    visiting.delete(runId);
+    visited.add(runId);
+  };
+  for (const run of runs) visit(run.runId);
+  return { sessionId, path, runs, liveLease };
+}
+
+async function recheckCandidate(entry: StoredRun, cutoffMs: number): Promise<string | undefined> {
+  const before = await stat(join(entry.store.directory, "state.json")).catch(() => undefined);
+  if (!before) return "State record disappeared before deletion";
+  const loaded = await entry.store.load().catch((error: unknown) => { throw new Error(`Candidate could not be reloaded: ${textError(error)}`); });
+  validateRunRecord(loaded.run);
+  if (loaded.run.id !== entry.runId || loaded.run.state !== entry.run.state || !TERMINAL_STATES.has(loaded.run.state)) return "Candidate state changed before deletion";
+  const after = await stat(join(entry.store.directory, "state.json"));
+  if (before.mtimeMs !== after.mtimeMs || after.mtimeMs !== entry.stateMtimeMs) return "Candidate state record changed before deletion";
+  if (after.mtimeMs >= cutoffMs) return "Candidate is no longer older than the cutoff";
+  return undefined;
+}
+
+function planSession(scan: SessionScan, cutoffMs: number): SessionPlan {
+  if (scan.liveLease) return { candidates: [], skipped: scan.runs.map((entry) => runItem(entry, "skipped", "Session has a live ownership lease")) };
+  const oldTerminal = new Set(scan.runs.filter(({ run, stateMtimeMs }) => TERMINAL_STATES.has(run.state) && stateMtimeMs < cutoffMs).map(({ runId }) => runId));
+  const protectedRuns = new Set<string>();
+  const visit = (runId: string) => { if (protectedRuns.has(runId)) return; protectedRuns.add(runId); const entry = scan.runs.find(({ runId: current }) => current === runId); for (const dependency of entry?.dependencies ?? []) visit(dependency); };
+  for (const entry of scan.runs) if (!oldTerminal.has(entry.runId)) for (const dependency of entry.dependencies) visit(dependency);
+  const skipped: CleanupRunResult[] = [];
+  for (const entry of scan.runs) {
+    if (!TERMINAL_STATES.has(entry.run.state)) skipped.push(runItem(entry, "skipped", `Run state ${entry.run.state} is active or resumable`));
+    else if (entry.stateMtimeMs >= cutoffMs) skipped.push(runItem(entry, "skipped", "State record is not older than the cutoff"));
+    else if (protectedRuns.has(entry.runId)) skipped.push(runItem(entry, "skipped", "A retained run depends on this run"));
+  }
+  return { candidates: scan.runs.filter(({ runId }) => oldTerminal.has(runId) && !protectedRuns.has(runId)), skipped };
+}
+
+function deletionOrder(scan: SessionScan, candidates: readonly StoredRun[]): readonly StoredRun[] {
+  const candidateIds = new Set(candidates.map(({ runId }) => runId));
+  const remaining = new Set(candidateIds);
+  const ordered: StoredRun[] = [];
+  while (remaining.size) {
+    const next = candidates.find((entry) => remaining.has(entry.runId) && !candidates.some((child) => remaining.has(child.runId) && child.dependencies.includes(entry.runId)));
+    if (!next) throw new Error("Dependency cycle prevents safe cleanup");
+    ordered.push(next); remaining.delete(next.runId);
+  }
+  return ordered;
+}
+
+async function storedSessionIds(cwd: string, home: string): Promise<readonly string[]> {
+  const path = projectSessionsDirectory(cwd, home);
+  let entries: readonly import("node:fs").Dirent[];
+  try { entries = await sessionEntries(path); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+  if (entries.some((entry) => entry.isSymbolicLink())) throw new Error(`Project session inventory contains a symbolic link: ${path}`);
+  const invalid = entries.find((entry) => !entry.isDirectory());
+  if (invalid) throw new Error(`Project session inventory contains an unrecognized entry: ${join(path, invalid.name)}`);
+  return entries.filter((entry) => entry.isDirectory()).map(({ name }) => name).sort();
+}
+
+function addUnique(items: CleanupRunResult[], item: CleanupRunResult): void { if (!items.some((current) => current.sessionId === item.sessionId && current.runId === item.runId && current.action === item.action)) items.push(item); }
+function addFailure(items: CleanupFailure[], sessionId: string, message: string, runId?: string): void { items.push({ sessionId, ...(runId ? { runId } : {}), message }); }
+
+export async function doctorCleanup(options: DoctorCleanupOptions = {}): Promise<DoctorCleanupReport> {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const home = resolve(options.home ?? homedir());
+  const olderThanDays = positiveDays(options.olderThanDays ?? 90);
+  const yes = options.yes === true;
+  const now = options.now ?? Date.now();
+  if (!Number.isFinite(now)) throw new Error("Cleanup command start time is invalid");
+  const cutoffMs = now - olderThanDays * DAY_MS;
+  if (!Number.isFinite(cutoffMs) || !Number.isFinite(new Date(cutoffMs).getTime())) throw new Error("older-than-days produces an unrepresentable cutoff");
+  const sessions: CleanupSessionReport[] = [];
+  const candidates: CleanupRunResult[] = [];
+  const skipped: CleanupRunResult[] = [];
+  const deleted: CleanupRunResult[] = [];
+  const failures: CleanupFailure[] = [];
+  let sessionIds: readonly string[];
+  try { sessionIds = await storedSessionIds(cwd, home); } catch (error) { addFailure(failures, "(project)", textError(error)); return { cwd, cutoffMs, olderThanDays, yes, sessions, candidates, skipped, deleted, failures }; }
+  for (const sessionId of sessionIds) {
+    let initial: SessionScan;
+    try { initial = await scanSession(cwd, sessionId, home); } catch (error) { sessions.push({ sessionId, path: join(projectSessionsDirectory(cwd, home), sessionId), status: "failed", reason: textError(error) }); addFailure(failures, sessionId, textError(error)); continue; }
+    const initialPlan = planSession(initial, cutoffMs);
+    for (const item of initialPlan.candidates) addUnique(candidates, runItem(item, "candidate"));
+    for (const item of initialPlan.skipped) addUnique(skipped, item);
+    if (!yes || initial.liveLease) { sessions.push({ sessionId, path: initial.path, status: initial.liveLease ? "skipped" : "preview", ...(initial.liveLease ? { reason: "Session has a live ownership lease" } : {}) }); continue; }
+    let lease: SessionLease;
+    try { lease = await acquireSessionLease(cwd, sessionId, home); } catch (error) {
+      const message = textError(error);
+      if (/already owned|active ownership|RUN_OWNED/i.test(message)) { sessions.push({ sessionId, path: initial.path, status: "skipped", reason: "Session has a live ownership lease" }); continue; }
+      sessions.push({ sessionId, path: initial.path, status: "failed", reason: message }); addFailure(failures, sessionId, message); continue;
+    }
+    try {
+      let current: SessionScan;
+      try { current = await scanSession(cwd, sessionId, home, lease); } catch (error) { const message = textError(error); sessions.push({ sessionId, path: initial.path, status: "failed", reason: message }); addFailure(failures, sessionId, message); continue; }
+      let freshPlan = planSession(current, cutoffMs);
+      for (const item of freshPlan.candidates) addUnique(candidates, runItem(item, "candidate"));
+      const freshIds = new Set(freshPlan.candidates.map(({ runId }) => runId));
+      for (const item of initialPlan.candidates) if (!freshIds.has(item.runId)) addUnique(skipped, runItem(item, "skipped", "Candidate changed or is no longer independently eligible"));
+      let clean = true;
+      while (freshPlan.candidates.length) {
+        try { current = await scanSession(cwd, sessionId, home, lease); freshPlan = planSession(current, cutoffMs); for (const item of freshPlan.skipped) addUnique(skipped, item); } catch (error) { const message = textError(error); addFailure(failures, sessionId, message); clean = false; break; }
+        if (!freshPlan.candidates.length) break;
+        let ordered: readonly StoredRun[];
+        try { ordered = deletionOrder(current, freshPlan.candidates); } catch (error) { const message = textError(error); addFailure(failures, sessionId, message); clean = false; break; }
+        const target = ordered[0];
+        if (!target) break;
+        let changed: string | undefined;
+        try { changed = await recheckCandidate(target, cutoffMs); } catch (error) { const message = textError(error); addFailure(failures, sessionId, message, target.runId); clean = false; break; }
+        if (changed) { addUnique(skipped, runItem(target, "skipped", changed)); clean = false; break; }
+        try { await target.store.delete(true); deleted.push(runItem(target, "deleted")); } catch (error) { const message = textError(error); addUnique(skipped, runItem(target, "failed", message)); addFailure(failures, sessionId, message, target.runId); clean = false; break; }
+      }
+      if (clean) sessions.push({ sessionId, path: initial.path, status: "cleaned" });
+      else if (!sessions.some(({ sessionId: currentId }) => currentId === sessionId)) sessions.push({ sessionId, path: initial.path, status: "failed", reason: "Cleanup stopped after a safety recheck or deletion failure" });
+    } finally { try { await lease.release(); } catch (error) { addFailure(failures, sessionId, textError(error)); } }
+  }
+  return { cwd, cutoffMs, olderThanDays, yes, sessions, candidates, skipped, deleted, failures };
+}
+
+export function doctorCleanupExitCode(report: DoctorCleanupReport): 0 | 1 { return report.failures.length ? 1 : 0; }
+function runLine(item: CleanupRunResult): string { return `- [${item.action}] session=${item.sessionId} run=${item.runId} state=${item.state} state-mtime=${new Date(item.stateMtimeMs).toISOString()} path=\`${item.path}\`${item.reason ? `: ${item.reason}` : ""}`; }
+export function formatDoctorCleanupReport(report: DoctorCleanupReport): string {
+  const lines = ["# pi-extensible-workflows doctor cleanup", "", "## Cleanup", `- Project: \`${report.cwd}\``, `- Cutoff: \`${new Date(report.cutoffMs).toISOString()}\` (strictly older than ${String(report.olderThanDays)} day(s))`, `- Mode: ${report.yes ? "confirmed deletion" : "preview only"}`, "", "## Candidates", ...(report.candidates.length ? report.candidates.map(runLine) : ["- None"]), "", "## Skipped", ...(report.skipped.length ? report.skipped.map(runLine) : ["- None"]), "", "## Deleted", ...(report.deleted.length ? report.deleted.map(runLine) : ["- None"]), "", "## Session safety", ...(report.sessions.length ? report.sessions.map((session) => `- [${session.status}] session=${session.sessionId} path=\`${session.path}\`${session.reason ? `: ${session.reason}` : ""}`) : ["- None stored"]), "", "## Failures", ...(report.failures.length ? report.failures.map((failure) => `- session=${failure.sessionId}${failure.runId ? ` run=${failure.runId}` : ""}: ${failure.message}`) : ["- None"]), "", "## Summary", `- ${String(report.candidates.length)} candidate(s), ${String(report.deleted.length)} deleted, ${String(report.skipped.length)} skipped, ${String(report.failures.length)} failure(s)`];
+  if (!report.yes) lines.push("", "No files were changed. Re-run with --yes to confirm deletion.");
+  return `${lines.join("\n")}\n`;
+}