role-os 1.8.0 → 2.0.0

package/src/run.mjs

@@ -0,0 +1,949 @@
+/**
+ * Persistent Run Engine — Phase U (v2.0.0)
+ *
+ * One command from task description to active execution.
+ * Runs persist to disk so sessions can resume.
+ *
+ * `roleos run "<task>"` → entry decision → plan → execute
+ * `roleos resume`       → continue interrupted run
+ * `roleos next`         → show what's next
+ * `roleos explain`      → show current state
+ *
+ * Interventions: reroute, split, escalate, retry, block, reopen
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { decideEntry } from "./entry.mjs";
+import { getMission } from "./mission.mjs";
+import { TEAM_PACKS, getPack } from "./packs.mjs";
+import { ROLE_CATALOG } from "./route.mjs";
+import { ROLE_ARTIFACT_CONTRACTS } from "./artifacts.mjs";
+import { getHandoffContract } from "./artifacts.mjs";
+
+// ── Run directory ────────────────────────────────────────────────────────────
+
+const RUNS_DIR = ".claude/runs";
+
+function runsDir(cwd) {
+  return join(cwd, RUNS_DIR);
+}
+
+function runPath(cwd, id) {
+  return join(runsDir(cwd), `${id}.json`);
+}
+
+// ── Run statuses ─────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {"planning"|"running"|"paused"|"completed"|"partial"|"failed"} RunStatus
+ */
+
+/**
+ * @typedef {"pending"|"active"|"completed"|"partial"|"failed"|"blocked"|"skipped"} StepStatus
+ */
+
+/**
+ * @typedef {Object} RunStep
+ * @property {number} index
+ * @property {string} role
+ * @property {string} produces - artifact type this step should produce
+ * @property {StepStatus} status
+ * @property {string|null} artifact - produced artifact content/reference
+ * @property {string|null} note
+ * @property {string|null} guidance - step-local operator guidance
+ * @property {string|null} startedAt
+ * @property {string|null} completedAt
+ */
+
+/**
+ * @typedef {Object} PersistentRun
+ * @property {string} id
+ * @property {string} taskDescription
+ * @property {"mission"|"pack"|"free-routing"} entryLevel
+ * @property {string|null} missionKey
+ * @property {string|null} packKey
+ * @property {object} entryDecision - full entry decision snapshot
+ * @property {RunStatus} status
+ * @property {RunStep[]} steps
+ * @property {Array<object>} escalations
+ * @property {Array<object>} interventions - operator interventions log
+ * @property {string} createdAt
+ * @property {string|null} pausedAt
+ * @property {string|null} completedAt
+ * @property {object|null} completionReport
+ */
+
+let _counter = 0;
+
+// ── Create a run ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a new persistent run from a task description.
+ * Uses decideEntry() to pick the right level, then builds steps.
+ *
+ * @param {string} taskDescription
+ * @param {string} cwd - working directory (for persistence)
+ * @param {object} [opts]
+ * @param {string} [opts.forceMission] - force a specific mission key
+ * @param {string} [opts.forcePack] - force a specific pack key
+ * @returns {PersistentRun}
+ */
+export function createPersistentRun(taskDescription, cwd, opts = {}) {
+  if (!taskDescription || !taskDescription.trim()) {
+    throw new Error("Task description required");
+  }
+
+  const entry = decideEntry(taskDescription);
+  let level = entry.level;
+  let missionKey = null;
+  let packKey = null;
+  let steps;
+
+  // Force overrides
+  if (opts.forceMission) {
+    const mission = getMission(opts.forceMission);
+    if (!mission) throw new Error(`Mission "${opts.forceMission}" not found`);
+    level = "mission";
+    missionKey = opts.forceMission;
+    steps = buildMissionSteps(opts.forceMission);
+  } else if (opts.forcePack) {
+    const pack = getPack(opts.forcePack);
+    if (!pack) throw new Error(`Pack "${opts.forcePack}" not found`);
+    level = "pack";
+    packKey = opts.forcePack;
+    steps = buildPackSteps(opts.forcePack);
+  } else if (level === "mission" && entry.mission) {
+    missionKey = entry.mission.key;
+    steps = buildMissionSteps(entry.mission.key);
+  } else if (level === "pack" && entry.pack) {
+    packKey = entry.pack.key;
+    steps = buildPackSteps(entry.pack.key);
+  } else {
+    // Free routing — build minimal steps from entry hints
+    steps = buildFreeRoutingSteps(taskDescription);
+  }
+
+  const id = `run-${Date.now()}-${++_counter}`;
+
+  const run = {
+    id,
+    taskDescription: taskDescription.trim(),
+    entryLevel: level,
+    missionKey,
+    packKey,
+    entryDecision: entry,
+    status: "planning",
+    steps,
+    escalations: [],
+    interventions: [],
+    createdAt: new Date().toISOString(),
+    pausedAt: null,
+    completedAt: null,
+    completionReport: null,
+  };
+
+  // Persist
+  saveRun(cwd, run);
+
+  return run;
+}
+
+// ── Step builders ────────────────────────────────────────────────────────────
+
+function buildMissionSteps(missionKey) {
+  const mission = getMission(missionKey);
+  return mission.artifactFlow.map((step, i) => ({
+    index: i,
+    role: step.role,
+    produces: step.produces,
+    status: "pending",
+    artifact: null,
+    note: null,
+    guidance: buildStepGuidance(step.role, step.produces, mission),
+    startedAt: null,
+    completedAt: null,
+  }));
+}
+
+function buildPackSteps(packKey) {
+  const pack = getPack(packKey);
+  const handoff = getHandoffContract(packKey);
+  const roles = pack.chainOrder
+    ? pack.chainOrder.split(" → ")
+    : pack.roles;
+
+  return roles.map((roleName, i) => {
+    const artifact = handoff?.flow?.[i]?.produces || guessArtifact(roleName);
+    return {
+      index: i,
+      role: roleName,
+      produces: artifact,
+      status: "pending",
+      artifact: null,
+      note: null,
+      guidance: buildStepGuidance(roleName, artifact, null),
+      startedAt: null,
+      completedAt: null,
+    };
+  });
+}
+
+function buildFreeRoutingSteps(taskDescription) {
+  // Free routing gets a minimal 3-step chain:
+  // 1. Analysis (best-fit role from catalog)
+  // 2. Execution (operator decides)
+  // 3. Review (Critic Reviewer)
+  return [
+    {
+      index: 0,
+      role: "Repo Researcher",
+      produces: "analysis",
+      status: "pending",
+      artifact: null,
+      note: null,
+      guidance: "Analyze the task, identify affected code/systems, produce a findings report.",
+      startedAt: null,
+      completedAt: null,
+    },
+    {
+      index: 1,
+      role: "Backend Engineer",
+      produces: "implementation",
+      status: "pending",
+      artifact: null,
+      note: null,
+      guidance: "Execute the task based on analysis. Operator may reroute this step to a different role.",
+      startedAt: null,
+      completedAt: null,
+    },
+    {
+      index: 2,
+      role: "Critic Reviewer",
+      produces: "verdict",
+      status: "pending",
+      artifact: null,
+      note: null,
+      guidance: "Review all artifacts. Accept, reject, or block with evidence.",
+      startedAt: null,
+      completedAt: null,
+    },
+  ];
+}
+
+// ── Step guidance ────────────────────────────────────────────────────────────
+
+function buildStepGuidance(roleName, produces, mission) {
+  const contract = ROLE_ARTIFACT_CONTRACTS[roleName];
+  const lines = [];
+
+  lines.push(`Role: ${roleName}`);
+  lines.push(`Produce: ${produces}`);
+
+  if (contract) {
+    if (contract.requiredSections) {
+      lines.push(`Required sections: ${contract.requiredSections.join(", ")}`);
+    }
+    if (contract.completionRule) {
+      lines.push(`Done when: ${contract.completionRule}`);
+    }
+  }
+
+  if (mission?.stopConditions) {
+    lines.push(`Stop conditions: ${mission.stopConditions.join("; ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+function guessArtifact(roleName) {
+  const map = {
+    "Product Strategist": "strategy-brief",
+    "Spec Writer": "implementation-spec",
+    "Backend Engineer": "change-plan",
+    "Frontend Developer": "change-plan",
+    "Test Engineer": "test-package",
+    "Security Reviewer": "security-findings",
+    "Critic Reviewer": "verdict",
+    "Docs Architect": "docs-update",
+    "Repo Researcher": "analysis",
+    "Deployment Verifier": "deploy-check",
+    "Release Engineer": "release-plan",
+    "Launch Strategist": "launch-plan",
+    "Launch Copywriter": "copy-package",
+    "Community Manager": "community-plan",
+    "Competitive Analyst": "competitive-analysis",
+  };
+  return map[roleName] || "artifact";
+}
+
+// ── Step lifecycle ───────────────────────────────────────────────────────────
+
+/**
+ * Start the next pending step in a run.
+ * @param {PersistentRun} run
+ * @param {string} cwd
+ * @returns {RunStep|null}
+ */
+export function startNext(run, cwd) {
+  const next = run.steps.find(s => s.status === "pending");
+  if (!next) return null;
+
+  next.status = "active";
+  next.startedAt = new Date().toISOString();
+  run.status = "running";
+
+  saveRun(cwd, run);
+  return next;
+}
+
+/**
+ * Complete the current active step.
+ * @param {PersistentRun} run
+ * @param {string} artifact
+ * @param {string} [note]
+ * @param {string} cwd
+ * @returns {RunStep}
+ */
+export function completeCurrentStep(run, artifact, note, cwd) {
+  const active = run.steps.find(s => s.status === "active");
+  if (!active) throw new Error("No active step to complete");
+
+  active.status = "completed";
+  active.artifact = artifact;
+  active.note = note || null;
+  active.completedAt = new Date().toISOString();
+
+  // Check if all done
+  const allDone = run.steps.every(s =>
+    s.status === "completed" || s.status === "skipped"
+  );
+  if (allDone) {
+    run.status = "completed";
+    run.completedAt = new Date().toISOString();
+  }
+
+  saveRun(cwd, run);
+  return active;
+}
+
+/**
+ * Fail the current active step.
+ * @param {PersistentRun} run
+ * @param {"partial"|"failed"} status
+ * @param {string} reason
+ * @param {string} cwd
+ * @returns {RunStep}
+ */
+export function failCurrentStep(run, status, reason, cwd) {
+  if (status !== "partial" && status !== "failed") {
+    throw new Error(`Invalid fail status: "${status}"`);
+  }
+
+  const active = run.steps.find(s => s.status === "active");
+  if (!active) throw new Error("No active step to fail");
+
+  active.status = status;
+  active.note = reason;
+  active.completedAt = new Date().toISOString();
+
+  // Block downstream pending steps
+  let foundActive = false;
+  for (const step of run.steps) {
+    if (step === active) { foundActive = true; continue; }
+    if (foundActive && step.status === "pending") {
+      step.status = "blocked";
+      step.note = `Blocked: upstream ${active.role} ${status}`;
+    }
+  }
+
+  run.status = status;
+  run.completedAt = new Date().toISOString();
+
+  saveRun(cwd, run);
+  return active;
+}
+
+/**
+ * Pause a running run (for session resume later).
+ * @param {PersistentRun} run
+ * @param {string} cwd
+ */
+export function pauseRun(run, cwd) {
+  if (run.status !== "running" && run.status !== "planning") return;
+  run.status = "paused";
+  run.pausedAt = new Date().toISOString();
+  saveRun(cwd, run);
+}
+
+/**
+ * Resume a paused run.
+ * @param {PersistentRun} run
+ * @param {string} cwd
+ * @returns {RunStep|null} The active or next step
+ */
+export function resumeRun(run, cwd) {
+  if (run.status !== "paused") {
+    throw new Error(`Cannot resume run in "${run.status}" state`);
+  }
+
+  // Check if there's already an active step
+  const active = run.steps.find(s => s.status === "active");
+  if (active) {
+    run.status = "running";
+    run.pausedAt = null;
+    saveRun(cwd, run);
+    return active;
+  }
+
+  // Otherwise start the next pending step
+  run.status = "running";
+  run.pausedAt = null;
+  const next = run.steps.find(s => s.status === "pending");
+  if (next) {
+    next.status = "active";
+    next.startedAt = new Date().toISOString();
+  }
+  saveRun(cwd, run);
+  return next || null;
+}
+
+// ── Interventions ────────────────────────────────────────────────────────────
+
+/**
+ * Reroute a step to a different role.
+ * @param {PersistentRun} run
+ * @param {number} stepIndex
+ * @param {string} newRole
+ * @param {string} reason
+ * @param {string} cwd
+ */
+export function reroute(run, stepIndex, newRole, reason, cwd) {
+  const step = run.steps[stepIndex];
+  if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
+  if (step.status === "completed") throw new Error("Cannot reroute a completed step");
+  const inCatalog = ROLE_CATALOG.some(r => r.name === newRole);
+  if (!inCatalog) throw new Error(`Role "${newRole}" not in catalog`);
+
+  const oldRole = step.role;
+  step.role = newRole;
+  step.guidance = buildStepGuidance(newRole, step.produces, null);
+
+  run.interventions.push({
+    type: "reroute",
+    stepIndex,
+    from: oldRole,
+    to: newRole,
+    reason,
+    timestamp: new Date().toISOString(),
+  });
+
+  saveRun(cwd, run);
+}
+
+/**
+ * Record an escalation during execution.
+ * @param {PersistentRun} run
+ * @param {string} from
+ * @param {string} to
+ * @param {string} trigger
+ * @param {string} action
+ * @param {string} cwd
+ * @returns {{reopened: boolean, warning: string|null}}
+ */
+export function escalate(run, from, to, trigger, action, cwd) {
+  const escalation = {
+    from, to, trigger, action,
+    timestamp: new Date().toISOString(),
+    reopened: false,
+    warning: null,
+  };
+  run.escalations.push(escalation);
+
+  // Find the LAST matching completed step for the target role
+  let targetStep = null;
+  for (let i = run.steps.length - 1; i >= 0; i--) {
+    if (run.steps[i].role === to && run.steps[i].status === "completed") {
+      targetStep = run.steps[i];
+      break;
+    }
+  }
+
+  if (targetStep) {
+    targetStep.status = "pending";
+    targetStep.artifact = null;
+    targetStep.note = `Re-opened by escalation: ${trigger}`;
+    targetStep.completedAt = null;
+    escalation.reopened = true;
+
+    // Unblock downstream steps that were blocked by this step's absence
+    for (let i = targetStep.index + 1; i < run.steps.length; i++) {
+      if (run.steps[i].status === "blocked") {
+        run.steps[i].status = "pending";
+        run.steps[i].note = `Unblocked: ${to} re-opened for escalation`;
+      }
+    }
+  } else {
+    const inChain = run.steps.some(s => s.role === to);
+    escalation.warning = inChain
+      ? `Role "${to}" has no completed step to re-open.`
+      : `Role "${to}" is not in this run's chain.`;
+  }
+
+  run.interventions.push({
+    type: "escalate",
+    from, to, trigger, action,
+    reopened: escalation.reopened,
+    warning: escalation.warning,
+    timestamp: escalation.timestamp,
+  });
+
+  saveRun(cwd, run);
+  return { reopened: escalation.reopened, warning: escalation.warning };
+}
+
+/**
+ * Retry a failed/partial step.
+ * @param {PersistentRun} run
+ * @param {number} stepIndex
+ * @param {string} cwd
+ */
+export function retry(run, stepIndex, cwd) {
+  const step = run.steps[stepIndex];
+  if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
+  if (step.status !== "failed" && step.status !== "partial") {
+    throw new Error(`Step ${stepIndex} is "${step.status}", not failed/partial`);
+  }
+
+  step.status = "pending";
+  step.artifact = null;
+  step.note = `Retried (was ${step.status})`;
+  step.completedAt = null;
+
+  // Unblock downstream
+  for (let i = stepIndex + 1; i < run.steps.length; i++) {
+    if (run.steps[i].status === "blocked") {
+      run.steps[i].status = "pending";
+      run.steps[i].note = `Unblocked: step ${stepIndex} retried`;
+    }
+  }
+
+  // Reset run status if it was failed/partial
+  if (run.status === "failed" || run.status === "partial") {
+    run.status = "paused";
+    run.completedAt = null;
+  }
+
+  run.interventions.push({
+    type: "retry",
+    stepIndex,
+    role: step.role,
+    timestamp: new Date().toISOString(),
+  });
+
+  saveRun(cwd, run);
+}
+
+/**
+ * Mark a step as blocked with a reason.
+ * @param {PersistentRun} run
+ * @param {number} stepIndex
+ * @param {string} reason
+ * @param {string} cwd
+ */
+export function blockStep(run, stepIndex, reason, cwd) {
+  const step = run.steps[stepIndex];
+  if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
+
+  step.status = "blocked";
+  step.note = reason;
+  step.completedAt = new Date().toISOString();
+
+  run.interventions.push({
+    type: "block",
+    stepIndex,
+    role: step.role,
+    reason,
+    timestamp: new Date().toISOString(),
+  });
+
+  saveRun(cwd, run);
+}
+
+/**
+ * Reopen a completed step (force re-execution).
+ * @param {PersistentRun} run
+ * @param {number} stepIndex
+ * @param {string} reason
+ * @param {string} cwd
+ */
+export function reopenStep(run, stepIndex, reason, cwd) {
+  const step = run.steps[stepIndex];
+  if (!step) throw new Error(`Invalid step index: ${stepIndex}`);
+  if (step.status !== "completed" && step.status !== "partial") {
+    throw new Error(`Step ${stepIndex} is "${step.status}", can only reopen completed/partial`);
+  }
+
+  step.status = "pending";
+  step.artifact = null;
+  step.note = `Re-opened: ${reason}`;
+  step.completedAt = null;
+
+  // Reset run status if it was completed
+  if (run.status === "completed") {
+    run.status = "paused";
+    run.completedAt = null;
+  }
+
+  run.interventions.push({
+    type: "reopen",
+    stepIndex,
+    role: step.role,
+    reason,
+    timestamp: new Date().toISOString(),
+  });
+
+  saveRun(cwd, run);
+}
+
+// ── Introspection ────────────────────────────────────────────────────────────
+
+/**
+ * Get the current position in a run.
+ * @param {PersistentRun} run
+ * @returns {{activeStep: RunStep|null, nextStep: RunStep|null, completedCount: number, totalSteps: number, progress: string}}
+ */
+export function getPosition(run) {
+  const active = run.steps.find(s => s.status === "active");
+  const next = active ? null : run.steps.find(s => s.status === "pending");
+  const completed = run.steps.filter(s => s.status === "completed").length;
+  const total = run.steps.length;
+
+  return {
+    activeStep: active || null,
+    nextStep: next || null,
+    completedCount: completed,
+    totalSteps: total,
+    progress: `${completed}/${total}`,
+  };
+}
+
+/**
+ * Explain the current run state in detail.
+ * @param {PersistentRun} run
+ * @returns {string}
+ */
+export function explainRun(run) {
+  const pos = getPosition(run);
+  const lines = [];
+
+  // Header
+  const levelLabel = run.entryLevel === "mission"
+    ? `Mission: ${getMission(run.missionKey)?.name || run.missionKey}`
+    : run.entryLevel === "pack"
+      ? `Pack: ${getPack(run.packKey)?.name || run.packKey}`
+      : "Free Routing";
+
+  lines.push(`# Run: ${run.id}`);
+  lines.push(`**Task:** ${run.taskDescription}`);
+  lines.push(`**Level:** ${levelLabel}`);
+  lines.push(`**Status:** ${run.status.toUpperCase()} (${pos.progress} steps completed)`);
+  lines.push(`**Created:** ${run.createdAt}`);
+  if (run.pausedAt) lines.push(`**Paused:** ${run.pausedAt}`);
+  if (run.completedAt) lines.push(`**Completed:** ${run.completedAt}`);
+
+  // Steps
+  lines.push("");
+  lines.push("## Steps");
+  for (const step of run.steps) {
+    const icon = step.status === "completed" ? "[x]" :
+                 step.status === "active"    ? "[>]" :
+                 step.status === "partial"   ? "[~]" :
+                 step.status === "failed"    ? "[!]" :
+                 step.status === "blocked"   ? "[-]" :
+                 step.status === "skipped"   ? "[s]" : "[ ]";
+    const artifact = step.artifact ? ` → ${step.produces}` : "";
+    const note = step.note ? ` (${step.note})` : "";
+    lines.push(`  ${icon} ${step.index}. ${step.role}${artifact}${note}`);
+  }
+
+  // Active step guidance
+  if (pos.activeStep) {
+    lines.push("");
+    lines.push("## Current Step Guidance");
+    lines.push(pos.activeStep.guidance || "No specific guidance.");
+  } else if (pos.nextStep) {
+    lines.push("");
+    lines.push("## Next Step");
+    lines.push(`${pos.nextStep.role} → ${pos.nextStep.produces}`);
+    lines.push(pos.nextStep.guidance || "No specific guidance.");
+  }
+
+  // Escalations
+  if (run.escalations.length > 0) {
+    lines.push("");
+    lines.push("## Escalations");
+    for (const esc of run.escalations) {
+      lines.push(`  - ${esc.from} → ${esc.to}: ${esc.trigger}`);
+    }
+  }
+
+  // Interventions
+  if (run.interventions.length > 0) {
+    lines.push("");
+    lines.push("## Interventions");
+    for (const iv of run.interventions) {
+      lines.push(`  - [${iv.type}] ${iv.timestamp}: ${JSON.stringify(iv)}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format a short "what's next" summary.
+ * @param {PersistentRun} run
+ * @returns {string}
+ */
+export function formatNext(run) {
+  const pos = getPosition(run);
+
+  if (run.status === "completed") {
+    return `Run completed (${pos.progress} steps). All done.`;
+  }
+
+  if (run.status === "failed" || run.status === "partial") {
+    const failedStep = run.steps.find(s => s.status === "failed" || s.status === "partial");
+    return `Run ${run.status} at step ${failedStep?.index || "?"} (${failedStep?.role || "?"}). ` +
+           `Use \`roleos retry ${failedStep?.index}\` to retry or \`roleos escalate\` to reroute.`;
+  }
+
+  if (pos.activeStep) {
+    return `Active: step ${pos.activeStep.index} — ${pos.activeStep.role} → ${pos.activeStep.produces}\n` +
+           `Progress: ${pos.progress}\n\n` +
+           (pos.activeStep.guidance || "");
+  }
+
+  if (pos.nextStep) {
+    return `Next: step ${pos.nextStep.index} — ${pos.nextStep.role} → ${pos.nextStep.produces}\n` +
+           `Progress: ${pos.progress}\n` +
+           `Run \`roleos next\` to start this step.\n\n` +
+           (pos.nextStep.guidance || "");
+  }
+
+  return `Run is ${run.status}. No actionable steps.`;
+}
+
+// ── Completion report ────────────────────────────────────────────────────────
+
+/**
+ * Generate a completion report for a finished run.
+ * @param {PersistentRun} run
+ * @returns {object}
+ */
+export function generateReport(run) {
+  const pos = getPosition(run);
+  const artifacts = run.steps
+    .filter(s => s.status === "completed" && s.artifact)
+    .map(s => ({ role: s.role, type: s.produces, artifact: s.artifact }));
+
+  const levelName = run.entryLevel === "mission"
+    ? getMission(run.missionKey)?.name || run.missionKey
+    : run.entryLevel === "pack"
+      ? getPack(run.packKey)?.name || run.packKey
+      : "Free Routing";
+
+  const honestPartial = run.missionKey
+    ? getMission(run.missionKey)?.honestPartial
+    : null;
+
+  const isComplete = run.status === "completed";
+  const isPartial = run.status === "partial";
+  const isFailed = run.status === "failed";
+
+  const report = {
+    runId: run.id,
+    entryLevel: run.entryLevel,
+    levelName,
+    taskDescription: run.taskDescription,
+    outcome: run.status,
+    progress: pos.progress,
+    createdAt: run.createdAt,
+    completedAt: run.completedAt,
+    steps: run.steps.map(s => ({
+      index: s.index,
+      role: s.role,
+      produces: s.produces,
+      status: s.status,
+      hasArtifact: !!s.artifact,
+      note: s.note,
+    })),
+    artifactsProduced: artifacts.length,
+    artifactChain: artifacts,
+    escalationCount: run.escalations.length,
+    interventionCount: run.interventions.length,
+    honestPartial: (isPartial || isFailed) ? honestPartial : null,
+    verdict: isComplete
+      ? "Run completed — all steps passed."
+      : isPartial
+        ? `Run partially completed (${pos.progress}).${honestPartial ? " " + honestPartial : ""}`
+        : isFailed
+          ? `Run failed at step ${run.steps.find(s => s.status === "failed")?.index ?? "?"} ` +
+            `(${run.steps.find(s => s.status === "failed")?.role || "unknown"}).`
+          : `Run still in progress (${pos.progress}).`,
+  };
+
+  run.completionReport = report;
+  return report;
+}
+
+/**
+ * Format a completion report as human-readable text.
+ * @param {object} report
+ * @returns {string}
+ */
+export function formatReport(report) {
+  const lines = [];
+
+  lines.push(`# Run Report: ${report.levelName}`);
+  lines.push("");
+  lines.push(`**Task:** ${report.taskDescription}`);
+  lines.push(`**Entry:** ${report.entryLevel}`);
+  lines.push(`**Outcome:** ${report.outcome.toUpperCase()}`);
+  lines.push(`**Progress:** ${report.progress}`);
+  lines.push(`**Artifacts:** ${report.artifactsProduced}`);
+  if (report.escalationCount > 0) lines.push(`**Escalations:** ${report.escalationCount}`);
+  if (report.interventionCount > 0) lines.push(`**Interventions:** ${report.interventionCount}`);
+
+  lines.push("");
+  lines.push("## Steps");
+  for (const step of report.steps) {
+    const icon = step.status === "completed" ? "[x]" :
+                 step.status === "active"    ? "[>]" :
+                 step.status === "partial"   ? "[~]" :
+                 step.status === "failed"    ? "[!]" :
+                 step.status === "blocked"   ? "[-]" : "[ ]";
+    const artifact = step.hasArtifact ? ` → ${step.produces}` : "";
+    const note = step.note ? ` (${step.note})` : "";
+    lines.push(`  ${icon} ${step.index}. ${step.role}${artifact}${note}`);
+  }
+
+  if (report.honestPartial) {
+    lines.push("");
+    lines.push("## Honest Partial");
+    lines.push(report.honestPartial);
+  }
+
+  lines.push("");
+  lines.push("## Verdict");
+  lines.push(report.verdict);
+
+  return lines.join("\n");
+}
+
+// ── Persistence ──────────────────────────────────────────────────────────────
+
+/**
+ * Save a run to disk.
+ * @param {string} cwd
+ * @param {PersistentRun} run
+ */
+export function saveRun(cwd, run) {
+  const dir = runsDir(cwd);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(runPath(cwd, run.id), JSON.stringify(run, null, 2));
+}
+
+/**
+ * Load a run from disk.
+ * @param {string} cwd
+ * @param {string} id
+ * @returns {PersistentRun|null}
+ */
+export function loadRun(cwd, id) {
+  const p = runPath(cwd, id);
+  if (!existsSync(p)) return null;
+  return JSON.parse(readFileSync(p, "utf-8"));
+}
+
+/**
+ * List all runs in the working directory.
+ * @param {string} cwd
+ * @returns {Array<{id: string, task: string, status: string, level: string, createdAt: string}>}
+ */
+export function listRuns(cwd) {
+  const dir = runsDir(cwd);
+  if (!existsSync(dir)) return [];
+
+  return readdirSync(dir)
+    .filter(f => f.endsWith(".json"))
+    .map(f => {
+      try {
+        const run = JSON.parse(readFileSync(join(dir, f), "utf-8"));
+        return {
+          id: run.id,
+          task: run.taskDescription,
+          status: run.status,
+          level: run.entryLevel,
+          createdAt: run.createdAt,
+        };
+      } catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+
+/**
+ * Find the most recent active (running/paused/planning) run.
+ * @param {string} cwd
+ * @returns {PersistentRun|null}
+ */
+export function findActiveRun(cwd) {
+  const dir = runsDir(cwd);
+  if (!existsSync(dir)) return null;
+
+  const files = readdirSync(dir)
+    .filter(f => f.endsWith(".json"))
+    .sort().reverse(); // newest first by filename (timestamp in ID)
+
+  for (const f of files) {
+    try {
+      const run = JSON.parse(readFileSync(join(dir, f), "utf-8"));
+      if (["running", "paused", "planning", "failed", "partial"].includes(run.status)) {
+        return run;
+      }
+    } catch { /* skip corrupt files */ }
+  }
+
+  return null;
+}
+
+// ── Friction measurement ─────────────────────────────────────────────────────
+
+/**
+ * Measure operator friction for a completed run.
+ * Counts touches (interventions, manual steps, escalations).
+ * @param {PersistentRun} run
+ * @returns {{totalTouches: number, interventions: number, escalations: number, manualSteps: number, stepsWithNotes: number, frictionScore: string}}
+ */
+export function measureFriction(run) {
+  const interventions = run.interventions.length;
+  const escalations = run.escalations.length;
+  const manualSteps = run.steps.length; // all steps require operator for now
+  const stepsWithNotes = run.steps.filter(s => s.note).length;
+  const totalTouches = interventions + escalations + manualSteps;
+
+  let frictionScore;
+  if (totalTouches <= run.steps.length) frictionScore = "low";
+  else if (totalTouches <= run.steps.length * 2) frictionScore = "medium";
+  else frictionScore = "high";
+
+  return {
+    totalTouches,
+    interventions,
+    escalations,
+    manualSteps,
+    stepsWithNotes,
+    frictionScore,
+  };
+}