@wichayutdew/pi-workflows 2.1.0 → 2.3.0

package/dist/index.js

@@ -133,6 +133,7 @@ var DEFAULT_SETTINGS = {
 var PROMPT_VARIABLES = new Set([
   "workflow.input",
   "workflow.id",
+  "workflow.iteration",
   "run.id",
   "step.id",
   "step.title",
@@ -141,7 +142,8 @@ var PROMPT_VARIABLES = new Set([
   "reviewed.feedback",
   "gate.artifact",
   "gate.feedback",
-  "resume.input"
+  "resume.input",
+  "restart.workspace"
 ]);
 function validatePromptText(text, path) {
   return [...text.matchAll(/\{\{([^{}]+)\}\}/g)].flatMap((match) => {
@@ -661,6 +663,7 @@ var HARNESS_COMMAND_NAMES = [
   "workflow-list",
   "workflow-pause",
   "workflow-reload",
+  "workflow-restart",
   "workflow-resume",
   "workflow-start"
 ];
@@ -1343,6 +1346,13 @@ function createHarnessCommands(controller) {
       }
     },
     createStartCommand(controller),
+    {
+      name: "workflow-restart",
+      options: {
+        description: "Restart the completed workflow in its worktree: /workflow-restart [input]",
+        handler: async (input, context) => controller.restart(input.trim(), context)
+      }
+    },
     {
       name: "workflow-pause",
       options: {
@@ -2947,7 +2957,7 @@ function parseAvailableSkills(systemPrompt) {
 
 // src/harness/dependencies.ts
 import { randomBytes, randomUUID } from "node:crypto";
-import { constants as constants3, mkdtempSync, writeFileSync } from "node:fs";
+import { constants as constants3, mkdtempSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { lstat as lstat3, open as open3, rm } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
 import { join as join5 } from "node:path";
@@ -4210,6 +4220,7 @@ function renderSummaryLines(theme, snapshot, width) {
       ...keyValueLines(theme, "about", workflow.definition.description, width)
     ] : [],
     ...keyValueLines(theme, "run", run.runId, width),
+    ...run.iteration && run.iteration > 1 ? [...keyValueLines(theme, "iteration", String(run.iteration), width)] : [],
     ...keyValueLines(theme, "status", statusLabel(run.status), width, statusColor(run.status)),
     ...keyValueLines(theme, "current", formatStepName(stepTitle(workflow, run.currentStepId), run.currentStepId), width),
     ...keyValueLines(theme, "visit", String(Math.max(1, run.visits[run.currentStepId] ?? 1)), width),
@@ -4474,10 +4485,11 @@ import { lstat as lstat2, open as open2, realpath as realpath3 } from "node:fs/p
 import { isAbsolute as isAbsolute9, relative as relative5, resolve as resolve9, sep as sep4 } from "node:path";
 
 // src/engine/create-run.ts
-var createRun = (workflow, input, baselineTools, runId, now, cwd) => {
+var createRun = (workflow, input, baselineTools, runId, now, cwd, iteration = 1) => {
   const startStepId = workflow.definition.start;
   return {
     stateVersion: RUN_STATE_VERSION,
+    iteration,
     runId,
     workflowId: workflow.definition.id,
     workflowDigest: workflow.digest,
@@ -4870,6 +4882,7 @@ var isPendingGate = (value) => isRecord8(value) && (value.provider === "prompt"
 var isVisitCounts = (value) => isRecord8(value) && Object.values(value).every((count) => typeof count === "number" && Number.isInteger(count) && count >= 0);
 var isOptionalString = (value) => value === undefined || typeof value === "string";
 var isOptionalResumeInput = (value) => value === undefined || typeof value === "string" && value.length <= MAX_RESUME_INPUT_CHARS;
+var isOptionalIteration = (value) => value === undefined || Number.isSafeInteger(value) && value >= 1;
 var isWorkflowRunStatus = (value) => value === "running" || value === "paused" || value === "awaiting-gate" || value === "completed" || value === "aborted";
 var hasValidPauseState = (run) => run.status === "paused" ? run.pausedFrom === "running" || run.pausedFrom === "awaiting-gate" : run.pausedFrom === undefined;
 var hasValidFailureState = (run) => run.failedStepId === undefined || run.status === "paused" && run.failedStepId === run.currentStepId;
@@ -4896,12 +4909,15 @@ var isWorkflowRun = (value) => {
   const hasValidRequiredFields = value.stateVersion === RUN_STATE_VERSION && typeof value.runId === "string" && typeof value.workflowId === "string" && typeof value.workflowDigest === "string" && typeof value.input === "string" && isWorkflowRunStatus(value.status) && typeof value.currentStepId === "string" && typeof value.currentStepDigest === "string" && Array.isArray(value.baselineTools) && value.baselineTools.every((tool) => typeof tool === "string") && Array.isArray(value.history) && value.history.every(isStepHistoryEntry) && (value.currentStepAttempts === undefined || isStepExecutionAttempts(value.currentStepAttempts)) && (value.currentStepOmittedAttempts === undefined || Number.isSafeInteger(value.currentStepOmittedAttempts) && value.currentStepOmittedAttempts > 0) && isVisitCounts(value.visits) && typeof value.startedAt === "number" && typeof value.updatedAt === "number" && typeof value.lastSummary === "string" && typeof value.gateFeedback === "string" && value.gateFeedback.length <= MAX_GATE_FEEDBACK_CHARS;
   if (!hasValidRequiredFields)
     return false;
-  const hasValidOptionalFields = isOptionalString(value.reviewedArtifact) && isOptionalString(value.reviewedFeedback) && (typeof value.reviewedFeedback !== "string" || value.reviewedFeedback.length <= MAX_GATE_FEEDBACK_CHARS) && isOptionalString(value.stepHandoff) && isOptionalString(value.gateArtifact) && isOptionalResumeInput(value.resumeInput) && isOptionalString(value.pauseReason) && isOptionalString(value.failedStepId) && (value.pausedFrom === undefined || value.pausedFrom === "running" || value.pausedFrom === "awaiting-gate");
+  const hasValidOptionalFields = isOptionalIteration(value.iteration) && isOptionalString(value.reviewedArtifact) && isOptionalString(value.reviewedFeedback) && (typeof value.reviewedFeedback !== "string" || value.reviewedFeedback.length <= MAX_GATE_FEEDBACK_CHARS) && isOptionalString(value.stepHandoff) && isOptionalString(value.gateArtifact) && (value.restartWorkspaceCwd === undefined || isAbsoluteCwd(value.restartWorkspaceCwd)) && isOptionalResumeInput(value.resumeInput) && isOptionalString(value.pauseReason) && isOptionalString(value.failedStepId) && (value.pausedFrom === undefined || value.pausedFrom === "running" || value.pausedFrom === "awaiting-gate");
   if (!hasValidOptionalFields)
     return false;
   const pendingGate = value.pendingGate;
   if (pendingGate !== undefined && !isPendingGate(pendingGate))
     return false;
+  if (value.restartWorkspaceCwd !== undefined && value.history.some((entry) => entry.workspaceCwd !== undefined)) {
+    return false;
+  }
   return workflowTraceChars(value) <= MAX_WORKFLOW_TRACE_CHARS && hasValidWorkspaceState(value, value.history) && hasValidPauseState(value) && hasValidFailureState(value) && hasValidGateState(value, pendingGate);
 };
 // src/workflow-status/transcript-reader.ts
@@ -5336,6 +5352,42 @@ function resolveWorkspaceDirectory({
   return canonicalCwd;
 }
 
+// src/harness/session-persistence.ts
+import { existsSync, writeFileSync } from "node:fs";
+var isAlreadyPersisted = (error) => error instanceof Error && ("code" in error) && error.code === "EEXIST";
+function getAdoptableSession(session) {
+  const adoptable = session;
+  if (typeof adoptable.setSessionFile !== "function") {
+    throw new Error("This Pi runtime cannot adopt a materialized workflow session file");
+  }
+  return adoptable;
+}
+function flushUnwrittenSession(session) {
+  const sessionFile = session.getSessionFile();
+  const header = session.getHeader();
+  if (!sessionFile || !header)
+    return false;
+  if (existsSync(sessionFile))
+    return false;
+  const adoptable = getAdoptableSession(session);
+  const serialized = [header, ...session.getEntries()].map((entry) => JSON.stringify(entry)).join(`
+`);
+  try {
+    writeFileSync(sessionFile, `${serialized}
+`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 384
+    });
+    adoptable.setSessionFile(sessionFile);
+    return true;
+  } catch (error) {
+    if (isAlreadyPersisted(error))
+      return false;
+    throw error;
+  }
+}
+
 // src/harness/dependencies.ts
 var MAX_DELEGATED_RESULT_BYTES = 1024 * 1024;
 function createDelegationWorkspace() {
@@ -5343,7 +5395,7 @@ function createDelegationWorkspace() {
   const capabilityPath = join5(resultDirectory, "capability");
   const capabilityToken = randomBytes(32).toString("hex");
   const resultPath = join5(resultDirectory, "result.json");
-  writeFileSync(capabilityPath, capabilityToken, {
+  writeFileSync2(capabilityPath, capabilityToken, {
     encoding: "utf8",
     flag: "wx",
     mode: 384
@@ -5400,6 +5452,7 @@ var DEFAULT_DEPENDENCIES3 = {
   createSubagentClient: (pi) => createSubagentDelegationClient(pi.events),
   createMainStepRuntime: (pi) => createMainStepRuntime({ pi }),
   createMutationQueue: createSerialTaskQueue,
+  flushUnwrittenSession,
   scheduleInterval: (operation, intervalMs) => setInterval(operation, intervalMs),
   cancelInterval: (timer) => {
     clearInterval(timer);
@@ -5516,831 +5569,983 @@ function createStatusActions() {
   };
 }
 
-// src/workflow-doctor.ts
-var lexical = (left, right) => left < right ? -1 : left > right ? 1 : 0;
-var internalTargets = (step) => [
-  ...new Set(Object.values(step.transitions).filter((target) => target !== "$done" && target !== "$pause"))
-].sort(lexical);
-var adjacencyFor = (definition) => Object.fromEntries(Object.entries(definition.steps).sort(([left], [right]) => lexical(left, right)).map(([stepId, step]) => [stepId, internalTargets(step)]));
-var reachableSteps = (definition, adjacency) => {
-  const reachable = new Set;
-  const pending = [definition.start];
-  while (pending.length > 0) {
-    const stepId = pending.pop();
-    if (!stepId || reachable.has(stepId))
-      continue;
-    if (!definition.steps[stepId])
-      continue;
-    reachable.add(stepId);
-    pending.push(...adjacency[stepId] ?? []);
+// src/engine/transition-helpers.ts
+var currentStep = (workflow, run) => workflow.definition.steps[run.currentStepId];
+var withRunUpdate = (run, changes, now) => ({ ...run, ...changes, updatedAt: now });
+
+// src/engine/run-advance.ts
+var completedStep = (run, outcome, summary, now, effects) => ({
+  stepId: run.currentStepId,
+  stepDigest: run.currentStepDigest,
+  outcome,
+  summary,
+  ...effects.workspaceCwd ? { workspaceCwd: effects.workspaceCwd } : {},
+  ...run.currentStepAttempts?.length ? { attempts: run.currentStepAttempts } : {},
+  ...run.currentStepOmittedAttempts ? { omittedAttempts: run.currentStepOmittedAttempts } : {},
+  completedAt: now
+});
+var advanceRun = (workflow, run, outcome, summary, now, effects = {}, options = {}) => {
+  if (run.status !== "running") {
+    throw new Error(`workflow is ${run.status}; only a running workflow can advance`);
   }
-  return reachable;
-};
-var stepsThatCanComplete = (definition, adjacency) => {
-  const canComplete = new Set(Object.entries(definition.steps).filter(([, step]) => Object.values(step.transitions).includes("$done")).map(([stepId]) => stepId));
-  const reverse = new Map;
-  for (const [source, targets] of Object.entries(adjacency)) {
-    for (const target of targets) {
-      reverse.set(target, [...reverse.get(target) ?? [], source]);
-    }
+  const step = currentStep(workflow, run);
+  if (!step) {
+    throw new Error(`current step "${run.currentStepId}" no longer exists`);
   }
-  const pending = [...canComplete].sort(lexical);
-  while (pending.length > 0) {
-    const stepId = pending.pop();
-    if (!stepId)
-      continue;
-    for (const predecessor of (reverse.get(stepId) ?? []).sort(lexical)) {
-      if (canComplete.has(predecessor))
-        continue;
-      canComplete.add(predecessor);
-      pending.push(predecessor);
-    }
+  if (step.gate?.submitOutcome === outcome) {
+    throw new Error(`outcome "${outcome}" must be submitted through the configured gate`);
   }
-  return canComplete;
-};
-var stronglyConnectedComponents = (definition, adjacency) => {
-  let nextIndex = 0;
-  const indexes = new Map;
-  const lowLinks = new Map;
-  const stack = [];
-  const onStack = new Set;
-  const components = [];
-  const visit = (stepId) => {
-    indexes.set(stepId, nextIndex);
-    lowLinks.set(stepId, nextIndex);
-    nextIndex += 1;
-    stack.push(stepId);
-    onStack.add(stepId);
-    for (const target of adjacency[stepId] ?? []) {
-      if (!indexes.has(target)) {
-        visit(target);
-        lowLinks.set(stepId, Math.min(lowLinks.get(stepId) ?? 0, lowLinks.get(target) ?? 0));
-      } else if (onStack.has(target)) {
-        lowLinks.set(stepId, Math.min(lowLinks.get(stepId) ?? 0, indexes.get(target) ?? 0));
-      }
+  const target = step.transitions[outcome];
+  if (!target) {
+    throw new Error(`outcome "${outcome}" is not valid for step "${run.currentStepId}"`);
+  }
+  const shouldBindWorkspace = step.workspace?.bindOn.includes(outcome) ?? false;
+  if (shouldBindWorkspace !== Boolean(effects.workspaceCwd)) {
+    throw new Error(shouldBindWorkspace ? `outcome "${outcome}" requires a validated workspace binding` : `outcome "${outcome}" cannot bind a workspace`);
+  }
+  if (shouldBindWorkspace && run.restartWorkspaceCwd !== undefined && effects.workspaceCwd !== run.restartWorkspaceCwd) {
+    throw new Error(`restarted workflow must rebind workspace "${run.restartWorkspaceCwd}"`);
+  }
+  if (target === "$pause") {
+    return withRunUpdate(run, {
+      status: "paused",
+      pausedFrom: "running",
+      pauseReason: summary || `Step "${run.currentStepId}" requested a pause`,
+      lastSummary: summary,
+      resumeInput: undefined
+    }, now);
+  }
+  const completed = completedStep(run, outcome, summary, now, effects);
+  const cwd = effects.workspaceCwd ?? run.cwd;
+  if (target === "$done") {
+    if (run.restartWorkspaceCwd !== undefined) {
+      throw new Error(`restarted workflow completed before rebinding workspace "${run.restartWorkspaceCwd}"`);
     }
-    if (lowLinks.get(stepId) !== indexes.get(stepId))
-      return;
-    const component = [];
-    let member;
-    do {
-      member = stack.pop();
-      if (!member)
-        break;
-      onStack.delete(member);
-      component.push(member);
-    } while (member !== stepId);
-    components.push(component.sort(lexical));
-  };
-  for (const stepId of Object.keys(definition.steps).sort(lexical)) {
-    if (!indexes.has(stepId))
-      visit(stepId);
+    return withRunUpdate(run, {
+      status: "completed",
+      history: [...run.history, completed],
+      currentStepAttempts: undefined,
+      currentStepOmittedAttempts: undefined,
+      ...cwd ? { cwd } : {},
+      ...effects.workspaceCwd ? { restartWorkspaceCwd: undefined } : {},
+      stepHandoff: summary,
+      lastSummary: summary,
+      gateArtifact: "",
+      gateFeedback: "",
+      pausedFrom: undefined,
+      pendingGate: undefined,
+      resumeInput: undefined
+    }, now);
   }
-  return components.sort((left, right) => lexical(left.join("\x00"), right.join("\x00")));
+  if (!workflow.definition.steps[target]) {
+    throw new Error(`transition target "${target}" does not exist`);
+  }
+  const preservesGateRevisionContext = target === run.currentStepId && (options.sameStepHumanGateRevision || Boolean(run.gateArtifact));
+  const nextVisitCount = (run.visits[target] ?? 0) + 1;
+  const isOverVisitLimit = !options.sameStepHumanGateRevision && nextVisitCount > workflow.definition.maxStepVisits;
+  const visitLimitChanges = isOverVisitLimit ? {
+    status: "paused",
+    pausedFrom: "running",
+    pauseReason: `Step "${target}" exceeded maxStepVisits (${workflow.definition.maxStepVisits})`,
+    failedStepId: target
+  } : {
+    status: "running",
+    pausedFrom: undefined,
+    pauseReason: undefined,
+    failedStepId: undefined
+  };
+  return withRunUpdate(run, {
+    ...visitLimitChanges,
+    currentStepId: target,
+    currentStepDigest: workflow.stepDigests[target] ?? "",
+    visits: { ...run.visits, [target]: nextVisitCount },
+    history: [...run.history, completed],
+    currentStepAttempts: undefined,
+    currentStepOmittedAttempts: undefined,
+    ...cwd ? { cwd } : {},
+    ...effects.workspaceCwd ? { restartWorkspaceCwd: undefined } : {},
+    stepHandoff: preservesGateRevisionContext ? run.stepHandoff : summary,
+    lastSummary: summary,
+    gateArtifact: preservesGateRevisionContext ? run.gateArtifact : "",
+    gateFeedback: preservesGateRevisionContext ? run.gateFeedback : "",
+    resumeInput: undefined
+  }, now);
 };
-var isCycle = (adjacency, component) => {
-  if (component.length > 1)
-    return true;
-  const [stepId] = component;
-  return Boolean(stepId && adjacency[stepId]?.includes(stepId));
+
+// src/engine/gate-transitions.ts
+var GATE_FEEDBACK_TRUNCATION_SUFFIX = `
+… [gate feedback truncated by Pi Workflows]`;
+var MAX_GATE_REJECTION_SUMMARY_CHARS = 500;
+var boundedGateFeedback = (feedback) => feedback.length <= MAX_GATE_FEEDBACK_CHARS ? feedback : `${feedback.slice(0, MAX_GATE_FEEDBACK_CHARS - GATE_FEEDBACK_TRUNCATION_SUFFIX.length)}${GATE_FEEDBACK_TRUNCATION_SUFFIX}`;
+var gateRejectionSummary = (feedback) => {
+  const compact = feedback.trim().replace(/\s+/g, " ");
+  if (!compact)
+    return "Gate rejected";
+  const summary = `Gate rejected: ${compact}`;
+  return summary.length <= MAX_GATE_REJECTION_SUMMARY_CHARS ? summary : `${summary.slice(0, MAX_GATE_REJECTION_SUMMARY_CHARS - 1)}…`;
 };
-function analyzeWorkflow(definition) {
-  const adjacency = adjacencyFor(definition);
-  const reachable = reachableSteps(definition, adjacency);
-  const canComplete = stepsThatCanComplete(definition, adjacency);
-  const issues = [];
-  const stranded = [...reachable].filter((stepId) => !canComplete.has(stepId)).sort(lexical);
-  if (!canComplete.has(definition.start)) {
-    issues.push({
-      level: "error",
-      code: "no-completion-path",
-      steps: [definition.start],
-      message: `start step ${definition.start} cannot reach $done`
-    });
+var beginGate = (workflow, run, outcome, artifact, requestId, now, summary) => {
+  if (run.status !== "running") {
+    throw new Error(`workflow is ${run.status}; gate submission requires a running workflow`);
   }
-  if (stranded.length > 0) {
-    issues.push({
-      level: "error",
-      code: "reachable-step-cannot-reach-done",
-      steps: stranded,
-      message: `reachable step${stranded.length === 1 ? "" : "s"} ${stranded.join(", ")} cannot reach $done`
-    });
+  const step = currentStep(workflow, run);
+  if (!step?.gate) {
+    throw new Error(`step "${run.currentStepId}" has no gate`);
   }
-  const unreachable = Object.keys(definition.steps).filter((stepId) => !reachable.has(stepId)).sort(lexical);
-  if (unreachable.length > 0) {
-    issues.push({
-      level: "warning",
-      code: "unreachable-steps",
-      steps: unreachable,
-      message: `unreachable step${unreachable.length === 1 ? "" : "s"}: ${unreachable.join(", ")}`
-    });
+  if (outcome !== step.gate.submitOutcome) {
+    throw new Error(`gate expects outcome "${step.gate.submitOutcome}"`);
   }
-  for (const component of stronglyConnectedComponents(definition, adjacency)) {
-    if (!isCycle(adjacency, component))
-      continue;
-    const componentIsReachable = component.some((stepId) => reachable.has(stepId));
-    const componentCanReachDone = component.some((stepId) => canComplete.has(stepId));
-    issues.push({
-      level: "warning",
-      code: "cycle",
-      steps: component,
-      reachable: componentIsReachable,
-      canReachDone: componentCanReachDone,
-      message: `${componentIsReachable ? "reachable" : "unreachable"} cyclic component: ${component.join(", ")}; ${componentCanReachDone ? "an exit can reach $done" : "no member can reach $done"}; maxStepVisits=${definition.maxStepVisits} bounds uninterrupted graph cycling`
-    });
+  if (!artifact.trim()) {
+    throw new Error("gate submission requires a non-empty artifact");
   }
-  return {
-    workflowId: definition.id,
-    maxStepVisits: definition.maxStepVisits,
-    reachableSteps: [...reachable].sort(lexical),
-    issues
-  };
-}
-var escapeMarkdown = (value) => value.replaceAll("\\", "\\\\").replaceAll("|", "\\|");
-function formatWorkflowDoctor(reports) {
-  const lines = ["# Workflow doctor", ""];
-  for (const report of reports) {
-    const errors = report.issues.filter((issue) => issue.level === "error");
-    const warnings = report.issues.filter((issue) => issue.level === "warning");
-    lines.push(`## ${report.workflowId}`, "", `Result: ${errors.length > 0 ? "ERROR" : warnings.length > 0 ? "WARNING" : "PASS"}`, "", `Runtime loop guard: automatic graph advancement enters each step at most ${report.maxStepVisits} time${report.maxStepVisits === 1 ? "" : "s"} before the next attempted entry pauses the run. An explicit human rejection back to the same gated step bypasses that check for its transition because every revision awaits another decision; the visit is still recorded. This bounds unattended cycling; it does not guarantee $done or bound time spent inside a step or gate.`, "");
-    if (report.issues.length === 0) {
-      lines.push("- No liveness issues found.", "");
-      continue;
-    }
-    lines.push(...report.issues.map((issue) => `- ${issue.level.toUpperCase()} \`${issue.code}\`: ${escapeMarkdown(issue.message)}`), "");
+  if (!summary.trim()) {
+    throw new Error("gate submission requires a non-empty summary");
   }
-  return lines.join(`
-`).trimEnd();
-}
-
-// src/workflow-list.ts
-function escapeMarkdownTableCell(value) {
-  return value.replaceAll("\\", "\\\\").replaceAll("|", "\\|").replace(/\r\n|\r|\n/g, " ");
-}
-function formatWorkflowList(workflows) {
-  return [
-    "| Workflow | Command | Description |",
-    "| --- | --- | --- |",
-    ...workflows.map((workflow) => `| \`${workflow.id}\` | \`/${workflow.command}\` | ${escapeMarkdownTableCell(workflow.description)} |`)
-  ].join(`
-`);
-}
-
-// src/harness/start-actions.ts
-function isCurrentSession(session, sessionEpoch) {
-  return session.isSessionActive && session.sessionEpoch === sessionEpoch;
-}
-async function listWorkflows(context) {
-  const workflows = [...this.catalog.workflows.values()].sort((left, right) => left.definition.id.localeCompare(right.definition.id));
-  if (workflows.length === 0) {
-    context.ui.notify(`No workflows loaded from ${this.catalog.userDirectory}`, this.catalog.diagnostics.length > 0 ? "warning" : "info");
-    return;
+  if (!requestId)
+    throw new Error("gate submission requires a request id");
+  return withRunUpdate(run, {
+    status: "awaiting-gate",
+    pendingGate: {
+      provider: step.gate.provider,
+      requestId,
+      stepId: run.currentStepId,
+      artifact,
+      summary,
+      submittedOutcome: outcome,
+      requestedAt: now
+    }
+  }, now);
+};
+var attachGateReviewId = (run, reviewId, now) => {
+  if (!run.pendingGate)
+    throw new Error("workflow has no pending gate");
+  if (run.pendingGate.provider !== "plannotator") {
+    throw new Error("only a Plannotator gate can have a review id");
   }
-  this.pi.sendMessage({
-    customType: "workflow-list",
-    content: formatWorkflowList(workflows.map((workflow) => workflow.definition)),
-    display: true
-  });
-}
-async function doctorWorkflows(workflowId, context) {
-  const catalog = await this.dependencies.loadCatalog({
-    cwd: context.cwd,
-    projectTrusted: context.isProjectTrusted()
-  });
-  if (catalog.diagnostics.some((diagnostic) => diagnostic.level === "error")) {
-    context.ui.notify(`Workflow configuration errors:
-${formatCatalogDiagnostics(catalog)}`, "warning");
+  return withRunUpdate(run, { pendingGate: { ...run.pendingGate, reviewId } }, now);
+};
+var failGate = (run, reason, now) => {
+  if (!run.pendingGate)
+    return run;
+  return withRunUpdate(run, {
+    status: "running",
+    pendingGate: undefined,
+    gateArtifact: run.pendingGate.artifact,
+    gateFeedback: boundedGateFeedback(reason),
+    pausedFrom: undefined,
+    pauseReason: undefined,
+    failedStepId: undefined
+  }, now);
+};
+var storeGateResolution = (run, resolution, now) => {
+  if (!run.pendingGate)
+    return run;
+  return withRunUpdate(run, {
+    pendingGate: {
+      ...run.pendingGate,
+      resolution: {
+        ...resolution,
+        feedback: boundedGateFeedback(resolution.feedback)
+      }
+    }
+  }, now);
+};
+var resolveGate = (workflow, run, resolution, now) => {
+  const pendingGate = run.pendingGate;
+  if (!pendingGate)
+    throw new Error("workflow has no pending gate");
+  const step = workflow.definition.steps[pendingGate.stepId];
+  if (!step?.gate) {
+    throw new Error(`gated step "${pendingGate.stepId}" no longer exists`);
   }
-  const selected = workflowId ? [catalog.workflows.get(workflowId)].filter((workflow) => workflow !== undefined) : [...catalog.workflows.values()].sort((left, right) => left.definition.id.localeCompare(right.definition.id));
-  if (workflowId && selected.length === 0) {
-    context.ui.notify(`Workflow "${workflowId}" is not loaded`, "error");
-    return;
+  if (run.currentStepId !== pendingGate.stepId) {
+    throw new Error("gate result does not match the current step");
   }
-  if (selected.length === 0) {
-    context.ui.notify(`No workflows loaded from ${catalog.userDirectory}`, catalog.diagnostics.length > 0 ? "warning" : "info");
-    return;
+  const outcome = resolution.approved ? step.gate.approvedOutcome : step.gate.rejectedOutcome;
+  const feedback = boundedGateFeedback(resolution.feedback);
+  const stepStructuralDigest = workflow.stepStructuralDigests[pendingGate.stepId] ?? "";
+  if (resolution.approved && !stepStructuralDigest) {
+    throw new Error(`gated step "${pendingGate.stepId}" has no structural digest`);
   }
-  this.pi.sendMessage({
-    customType: "workflow-doctor",
-    content: formatWorkflowDoctor(selected.map((workflow) => analyzeWorkflow(workflow.definition))),
-    display: true
+  const summary = resolution.approved ? pendingGate.summary ?? "" : gateRejectionSummary(feedback);
+  const decidedRun = recordCurrentGateDecision(run, {
+    provider: pendingGate.provider,
+    requestId: pendingGate.requestId,
+    approved: resolution.approved,
+    feedback,
+    resolvedAt: resolution.resolvedAt,
+    ...pendingGate.reviewId ? { reviewId: pendingGate.reviewId } : {}
+  }, now);
+  const runnableRun = withRunUpdate(decidedRun, {
+    status: "running",
+    pendingGate: undefined,
+    pausedFrom: undefined,
+    pauseReason: undefined,
+    gateArtifact: resolution.approved ? "" : pendingGate.artifact,
+    gateFeedback: resolution.approved ? "" : feedback
+  }, now);
+  const isSameStepHumanRevision = !resolution.approved && step.transitions[outcome] === pendingGate.stepId;
+  const advanced = advanceRun(workflow, runnableRun, outcome, summary, now, {}, {
+    sameStepHumanGateRevision: isSameStepHumanRevision
   });
-}
-async function startNow(workflowId, input, startContext, sessionEpoch) {
-  const { context } = startContext;
-  if (this.activeDelegation) {
-    context.ui.notify(`Cannot start a workflow while subagent "${this.activeDelegation.agent}" is still cancelling`, "warning");
-    return;
-  }
-  if (this.run && this.run.status !== "completed" && this.run.status !== "aborted") {
-    context.ui.notify(`Workflow "${this.run.workflowId}" is ${this.run.status}; resume or abort it first`, "warning");
-    return;
+  const completedApprovedGate = resolution.approved && advanced.history.length > runnableRun.history.length;
+  const history = completedApprovedGate ? advanced.history.map((entry, index) => index === advanced.history.length - 1 ? {
+    ...entry,
+    artifact: pendingGate.artifact,
+    approval: {
+      requestId: pendingGate.requestId,
+      artifact: pendingGate.artifact,
+      feedback,
+      stepStructuralDigest
+    }
+  } : entry) : advanced.history;
+  return {
+    ...advanced,
+    history,
+    ...completedApprovedGate ? {
+      reviewedArtifact: pendingGate.artifact,
+      reviewedFeedback: feedback
+    } : {},
+    gateArtifact: resolution.approved ? "" : pendingGate.artifact,
+    gateFeedback: resolution.approved ? "" : feedback
+  };
+};
+// src/engine/run-lifecycle.ts
+var completedWorkspaceCwd = (run) => {
+  for (let index = run.history.length - 1;index >= 0; index -= 1) {
+    const workspaceCwd = run.history[index]?.workspaceCwd;
+    if (workspaceCwd)
+      return workspaceCwd;
   }
-  if (!context.isIdle()) {
-    context.abort();
-    await startContext.waitForIdle();
+  return;
+};
+var allowedOutcomes = (workflow, run) => {
+  const step = currentStep(workflow, run);
+  if (!step)
+    return [];
+  const gateResolutionOutcomes = step.gate ? new Set([step.gate.approvedOutcome, step.gate.rejectedOutcome]) : undefined;
+  return [
+    ...Object.keys(step.transitions).filter((outcome) => !gateResolutionOutcomes?.has(outcome)),
+    ...step.gate ? [step.gate.submitOutcome] : []
+  ];
+};
+var pauseRun = (run, reason, now) => {
+  if (run.status !== "running" && run.status !== "awaiting-gate") {
+    return withRunUpdate(run, { pauseReason: reason || run.pauseReason }, now);
   }
-  if (!isCurrentSession(this, sessionEpoch)) {
-    context.ui.notify("Workflow start was superseded by a session change", "warning");
-    return;
+  return withRunUpdate(run, {
+    status: "paused",
+    pausedFrom: run.status,
+    pauseReason: reason || `Paused during step "${run.currentStepId}"`,
+    failedStepId: undefined
+  }, now);
+};
+var failRun = (run, reason, now) => {
+  const pausedRun = pauseRun(run, reason, now);
+  return pausedRun.status === "paused" ? { ...pausedRun, failedStepId: pausedRun.currentStepId } : pausedRun;
+};
+var resumeRun = (run, now) => {
+  if (run.status !== "paused")
+    return run;
+  return withRunUpdate(run, {
+    status: run.pausedFrom ?? (run.pendingGate ? "awaiting-gate" : "running"),
+    pauseReason: undefined,
+    pausedFrom: undefined,
+    failedStepId: undefined
+  }, now);
+};
+var setResumeInput = (run, input, now) => withRunUpdate(run, { resumeInput: input.trim() || undefined }, now);
+var abortRun = (run, reason, now) => withRunUpdate(run, {
+  status: "aborted",
+  pauseReason: reason || "Aborted by user",
+  pausedFrom: undefined,
+  failedStepId: undefined,
+  pendingGate: undefined,
+  resumeInput: undefined
+}, now);
+var restartRun = (workflow, run, input, baselineTools, now) => {
+  if (run.status !== "completed") {
+    throw new Error("only a completed workflow can be restarted");
   }
-  this.captureSkills(startContext.skills());
-  if (!await this.reloadCatalog(context, false)) {
-    context.ui.notify("Workflow start was superseded by a newer configuration load", "warning");
-    return;
+  if (!run.startCwd) {
+    throw new Error("the completed workflow has no captured start directory; start a new workflow instead");
   }
-  if (!isCurrentSession(this, sessionEpoch)) {
-    context.ui.notify("Workflow start was superseded by a session change", "warning");
-    return;
+  const previousIteration = run.iteration ?? 1;
+  if (!Number.isSafeInteger(previousIteration) || previousIteration < 1) {
+    throw new Error("the completed workflow has an invalid iteration number");
   }
-  const workflow = this.catalog.workflows.get(workflowId);
-  if (!workflow) {
-    context.ui.notify(`Workflow "${workflowId}" is not loaded`, "error");
-    return;
+  if (previousIteration >= Number.MAX_SAFE_INTEGER) {
+    throw new Error("the workflow iteration limit has been reached");
   }
-  const livenessErrors = analyzeWorkflow(workflow.definition).issues.filter((issue) => issue.level === "error");
-  if (livenessErrors.length > 0) {
-    context.ui.notify(`Cannot start workflow; run /workflow-doctor ${workflowId}:
-${livenessErrors.map((issue) => issue.message).join(`
-`)}`, "error");
-    return;
+  const workspaceCwd = completedWorkspaceCwd(run);
+  if (workspaceCwd && run.cwd !== workspaceCwd) {
+    throw new Error("the completed workflow workspace does not match its recorded binding");
   }
-  const preflightErrors = this.preflight(workflow, workflow.definition.start);
-  if (preflightErrors.length > 0) {
-    context.ui.notify(`Cannot start workflow:
-${preflightErrors.join(`
-`)}`, "error");
-    return;
-  }
-  let canonicalStartCwd;
-  try {
-    canonicalStartCwd = this.dependencies.resolveWorkspaceDirectory({
-      candidateCwd: context.cwd,
-      startCwd: context.cwd,
-      allowedRoots: ["."]
-    });
-  } catch (error) {
-    context.ui.notify(`Cannot capture workflow working directory: ${error instanceof Error ? error.message : String(error)}`, "error");
-    return;
-  }
-  this.run = createRun(workflow, input.trim(), this.pi.getActiveTools(), this.dependencies.createRequestId(), this.dependencies.now(), canonicalStartCwd);
-  this.persist();
-  this.isolateMainSessionTools();
-  this.updateStatus();
-  this.launchCurrentStep(workflow);
-}
-async function reloadNow(context) {
-  if (this.run && (this.run.status === "running" || this.run.status === "awaiting-gate")) {
-    context.ui.notify("Pause the workflow before reloading its configuration", "warning");
-    return;
-  }
-  this.captureSkills(context.getSystemPromptOptions().skills);
-  await this.reloadCatalog(context, true);
-}
-function createStartActions() {
-  return { listWorkflows, doctorWorkflows, startNow, reloadNow };
-}
-
-// src/engine/transition-helpers.ts
-var currentStep = (workflow, run) => workflow.definition.steps[run.currentStepId];
-var withRunUpdate = (run, changes, now) => ({ ...run, ...changes, updatedAt: now });
-
-// src/engine/run-advance.ts
-var completedStep = (run, outcome, summary, now, effects) => ({
-  stepId: run.currentStepId,
-  stepDigest: run.currentStepDigest,
-  outcome,
-  summary,
-  ...effects.workspaceCwd ? { workspaceCwd: effects.workspaceCwd } : {},
-  ...run.currentStepAttempts?.length ? { attempts: run.currentStepAttempts } : {},
-  ...run.currentStepOmittedAttempts ? { omittedAttempts: run.currentStepOmittedAttempts } : {},
-  completedAt: now
-});
-var advanceRun = (workflow, run, outcome, summary, now, effects = {}, options = {}) => {
-  if (run.status !== "running") {
-    throw new Error(`workflow is ${run.status}; only a running workflow can advance`);
-  }
-  const step = currentStep(workflow, run);
-  if (!step) {
-    throw new Error(`current step "${run.currentStepId}" no longer exists`);
-  }
-  if (step.gate?.submitOutcome === outcome) {
-    throw new Error(`outcome "${outcome}" must be submitted through the configured gate`);
-  }
-  const target = step.transitions[outcome];
-  if (!target) {
-    throw new Error(`outcome "${outcome}" is not valid for step "${run.currentStepId}"`);
-  }
-  const shouldBindWorkspace = step.workspace?.bindOn.includes(outcome) ?? false;
-  if (shouldBindWorkspace !== Boolean(effects.workspaceCwd)) {
-    throw new Error(shouldBindWorkspace ? `outcome "${outcome}" requires a validated workspace binding` : `outcome "${outcome}" cannot bind a workspace`);
-  }
-  if (target === "$pause") {
-    return withRunUpdate(run, {
-      status: "paused",
-      pausedFrom: "running",
-      pauseReason: summary || `Step "${run.currentStepId}" requested a pause`,
-      lastSummary: summary,
-      resumeInput: undefined
-    }, now);
-  }
-  const completed = completedStep(run, outcome, summary, now, effects);
-  const cwd = effects.workspaceCwd ?? run.cwd;
-  if (target === "$done") {
-    return withRunUpdate(run, {
-      status: "completed",
-      history: [...run.history, completed],
-      currentStepAttempts: undefined,
-      currentStepOmittedAttempts: undefined,
-      ...cwd ? { cwd } : {},
-      stepHandoff: summary,
-      lastSummary: summary,
-      gateArtifact: "",
-      gateFeedback: "",
-      pausedFrom: undefined,
-      pendingGate: undefined,
-      resumeInput: undefined
-    }, now);
+  const restarted = createRun(workflow, input, baselineTools, run.runId, now, run.startCwd, previousIteration + 1);
+  return {
+    ...restarted,
+    stepHandoff: run.lastSummary,
+    lastSummary: run.lastSummary,
+    ...workspaceCwd ? { restartWorkspaceCwd: workspaceCwd } : {}
+  };
+};
+// src/engine/reconciliation-history.ts
+var isApprovedGateEntry = (workflow, entry) => {
+  const gate = workflow.definition.steps[entry.stepId]?.gate;
+  return gate !== undefined && entry.outcome === gate.approvedOutcome;
+};
+var latestApprovedGateEntry = (workflow, history) => {
+  for (let index = history.length - 1;index >= 0; index -= 1) {
+    const entry = history[index];
+    if (entry && isApprovedGateEntry(workflow, entry))
+      return { entry, index };
   }
-  if (!workflow.definition.steps[target]) {
-    throw new Error(`transition target "${target}" does not exist`);
+  return;
+};
+var rebuildVisits = (history, currentStepId) => {
+  const visitedStepIds = [
+    ...history.map((entry) => entry.stepId),
+    currentStepId
+  ];
+  return visitedStepIds.reduce((visits, stepId) => ({
+    ...visits,
+    [stepId]: (visits[stepId] ?? 0) + 1
+  }), {});
+};
+var retainedWorkspaceCwd = (run, history) => {
+  for (let index = history.length - 1;index >= 0; index -= 1) {
+    const cwd = history[index]?.workspaceCwd;
+    if (cwd)
+      return cwd;
   }
-  const preservesGateRevisionContext = target === run.currentStepId && (options.sameStepHumanGateRevision || Boolean(run.gateArtifact));
-  const nextVisitCount = (run.visits[target] ?? 0) + 1;
-  const isOverVisitLimit = !options.sameStepHumanGateRevision && nextVisitCount > workflow.definition.maxStepVisits;
-  const visitLimitChanges = isOverVisitLimit ? {
-    status: "paused",
-    pausedFrom: "running",
-    pauseReason: `Step "${target}" exceeded maxStepVisits (${workflow.definition.maxStepVisits})`,
-    failedStepId: target
-  } : {
-    status: "running",
-    pausedFrom: undefined,
-    pauseReason: undefined,
-    failedStepId: undefined
-  };
-  return withRunUpdate(run, {
-    ...visitLimitChanges,
-    currentStepId: target,
-    currentStepDigest: workflow.stepDigests[target] ?? "",
-    visits: { ...run.visits, [target]: nextVisitCount },
-    history: [...run.history, completed],
-    currentStepAttempts: undefined,
-    currentStepOmittedAttempts: undefined,
-    ...cwd ? { cwd } : {},
-    stepHandoff: preservesGateRevisionContext ? run.stepHandoff : summary,
-    lastSummary: summary,
-    gateArtifact: preservesGateRevisionContext ? run.gateArtifact : "",
-    gateFeedback: preservesGateRevisionContext ? run.gateFeedback : "",
-    resumeInput: undefined
-  }, now);
+  return run.startCwd ?? run.cwd;
+};
+var retainedReviewedApproval = (workflow, history) => {
+  const retainedApproval = latestApprovedGateEntry(workflow, history);
+  const approval = retainedApproval?.entry.approval;
+  return approval ? { artifact: approval.artifact, feedback: approval.feedback } : undefined;
+};
+var refreshApprovedGateHistory = (run, workflow) => {
+  const history = run.history.map((entry) => {
+    const gate = workflow.definition.steps[entry.stepId]?.gate;
+    const currentDigest = workflow.stepDigests[entry.stepId];
+    const currentStructuralDigest = workflow.stepStructuralDigests[entry.stepId];
+    const shouldRefresh = gate !== undefined && typeof currentDigest === "string" && currentDigest.length > 0 && typeof currentStructuralDigest === "string" && currentStructuralDigest.length > 0 && entry.outcome === gate.approvedOutcome && entry.approval?.stepStructuralDigest === currentStructuralDigest && entry.stepDigest !== currentDigest;
+    return shouldRefresh ? { ...entry, stepDigest: currentDigest } : entry;
+  });
+  const hasChanged = history.some((entry, index) => entry !== run.history[index]);
+  return hasChanged ? { ...run, history } : run;
 };
 
-// src/engine/gate-transitions.ts
-var GATE_FEEDBACK_TRUNCATION_SUFFIX = `
-… [gate feedback truncated by Pi Workflows]`;
-var MAX_GATE_REJECTION_SUMMARY_CHARS = 500;
-var boundedGateFeedback = (feedback) => feedback.length <= MAX_GATE_FEEDBACK_CHARS ? feedback : `${feedback.slice(0, MAX_GATE_FEEDBACK_CHARS - GATE_FEEDBACK_TRUNCATION_SUFFIX.length)}${GATE_FEEDBACK_TRUNCATION_SUFFIX}`;
-var gateRejectionSummary = (feedback) => {
-  const compact = feedback.trim().replace(/\s+/g, " ");
-  if (!compact)
-    return "Gate rejected";
-  const summary = `Gate rejected: ${compact}`;
-  return summary.length <= MAX_GATE_REJECTION_SUMMARY_CHARS ? summary : `${summary.slice(0, MAX_GATE_REJECTION_SUMMARY_CHARS - 1)}…`;
+// src/engine/run-workflow-validation.ts
+var sameVisitCounts = (actual, expected) => {
+  const actualEntries = Object.entries(actual).sort(([left], [right]) => left.localeCompare(right));
+  const expectedEntries = Object.entries(expected).sort(([left], [right]) => left.localeCompare(right));
+  return actualEntries.length === expectedEntries.length && actualEntries.every(([stepId, count], index) => expectedEntries[index]?.[0] === stepId && expectedEntries[index][1] === count);
 };
-var beginGate = (workflow, run, outcome, artifact, requestId, now, summary) => {
-  if (run.status !== "running") {
-    throw new Error(`workflow is ${run.status}; gate submission requires a running workflow`);
+var validateHistoryMetadata = (workflow, step, entry) => {
+  const shouldBind = step.workspace?.bindOn.includes(entry.outcome) === true;
+  if (shouldBind !== (entry.workspaceCwd !== undefined)) {
+    return shouldBind ? `history step "${entry.stepId}" is missing its workspace binding` : `history step "${entry.stepId}" has an unauthorized workspace binding`;
   }
-  const step = currentStep(workflow, run);
-  if (!step?.gate) {
-    throw new Error(`step "${run.currentStepId}" has no gate`);
+  const isApprovedGate = step.gate !== undefined && entry.outcome === step.gate.approvedOutcome;
+  if (isApprovedGate && !entry.approval) {
+    return `history step "${entry.stepId}" is missing authoritative gate approval`;
   }
-  if (outcome !== step.gate.submitOutcome) {
-    throw new Error(`gate expects outcome "${step.gate.submitOutcome}"`);
+  if (isApprovedGate && entry.artifact !== entry.approval?.artifact) {
+    return `history step "${entry.stepId}" approval artifact is inconsistent`;
   }
-  if (!artifact.trim()) {
-    throw new Error("gate submission requires a non-empty artifact");
+  if (!isApprovedGate && (entry.approval || entry.artifact !== undefined)) {
+    return `history step "${entry.stepId}" has approval data for a non-approved outcome`;
   }
-  if (!summary.trim()) {
-    throw new Error("gate submission requires a non-empty summary");
+  if (isApprovedGate && entry.approval?.stepStructuralDigest !== workflow.stepStructuralDigests[entry.stepId]) {
+    return `history step "${entry.stepId}" approval does not match its configured structure`;
   }
-  if (!requestId)
-    throw new Error("gate submission requires a request id");
-  return withRunUpdate(run, {
-    status: "awaiting-gate",
-    pendingGate: {
-      provider: step.gate.provider,
-      requestId,
-      stepId: run.currentStepId,
-      artifact,
-      summary,
-      submittedOutcome: outcome,
-      requestedAt: now
-    }
-  }, now);
+  return;
 };
-var attachGateReviewId = (run, reviewId, now) => {
-  if (!run.pendingGate)
-    throw new Error("workflow has no pending gate");
-  if (run.pendingGate.provider !== "plannotator") {
-    throw new Error("only a Plannotator gate can have a review id");
+var validatePendingGate = (run, step) => {
+  const pending = run.pendingGate;
+  if (!pending)
+    return;
+  if (!step.gate || pending.stepId !== run.currentStepId || pending.provider !== step.gate.provider || pending.submittedOutcome !== step.gate.submitOutcome) {
+    return "pending gate does not match the current workflow step";
   }
-  return withRunUpdate(run, { pendingGate: { ...run.pendingGate, reviewId } }, now);
-};
-var failGate = (run, reason, now) => {
-  if (!run.pendingGate)
-    return run;
-  return withRunUpdate(run, {
-    status: "running",
-    pendingGate: undefined,
-    gateArtifact: run.pendingGate.artifact,
-    gateFeedback: boundedGateFeedback(reason),
-    pausedFrom: undefined,
-    pauseReason: undefined,
-    failedStepId: undefined
-  }, now);
+  if (pending.provider === "prompt" && pending.reviewId !== undefined) {
+    return "built-in prompt gate cannot carry a Plannotator review id";
+  }
+  return;
 };
-var storeGateResolution = (run, resolution, now) => {
-  if (!run.pendingGate)
-    return run;
-  return withRunUpdate(run, {
-    pendingGate: {
-      ...run.pendingGate,
-      resolution: {
-        ...resolution,
-        feedback: boundedGateFeedback(resolution.feedback)
+function validateRunWorkflowSemantics(run, workflow) {
+  const sameWorkflowDigest = run.workflowDigest === workflow.digest;
+  let expectedStepId = workflow.definition.start;
+  let reachedDone = false;
+  let boundWorkspaceCwd;
+  let latestApproval;
+  const expectedVisits = { [expectedStepId]: 1 };
+  for (let index = 0;index < run.history.length; index += 1) {
+    const entry = run.history[index];
+    if (!entry)
+      continue;
+    if (reachedDone) {
+      return "workflow history continues after a $done transition";
+    }
+    if (entry.stepId !== expectedStepId) {
+      return `history step "${entry.stepId}" is not reachable after "${expectedStepId}"`;
+    }
+    const step = workflow.definition.steps[entry.stepId];
+    const configuredDigest = workflow.stepDigests[entry.stepId];
+    if (!step || entry.stepDigest !== configuredDigest) {
+      return sameWorkflowDigest ? `history step "${entry.stepId}" does not match the active workflow digest` : undefined;
+    }
+    const metadataError = validateHistoryMetadata(workflow, step, entry);
+    if (metadataError)
+      return metadataError;
+    if (entry.workspaceCwd) {
+      if (boundWorkspaceCwd !== undefined && boundWorkspaceCwd !== entry.workspaceCwd) {
+        return "workflow history attempts to replace an existing workspace binding";
       }
+      boundWorkspaceCwd = entry.workspaceCwd;
     }
-  }, now);
-};
-var resolveGate = (workflow, run, resolution, now) => {
-  const pendingGate = run.pendingGate;
-  if (!pendingGate)
-    throw new Error("workflow has no pending gate");
-  const step = workflow.definition.steps[pendingGate.stepId];
-  if (!step?.gate) {
-    throw new Error(`gated step "${pendingGate.stepId}" no longer exists`);
+    if (entry.approval) {
+      latestApproval = {
+        artifact: entry.approval.artifact,
+        feedback: entry.approval.feedback
+      };
+    }
+    const target = step.transitions[entry.outcome];
+    if (!target) {
+      return `history outcome "${entry.outcome}" is not configured for step "${entry.stepId}"`;
+    }
+    if (target === "$pause") {
+      return `history step "${entry.stepId}" records a non-completing $pause transition`;
+    }
+    if (target === "$done") {
+      if (index !== run.history.length - 1) {
+        return "workflow history continues after a $done transition";
+      }
+      reachedDone = true;
+      continue;
+    }
+    expectedStepId = target;
+    expectedVisits[target] = (expectedVisits[target] ?? 0) + 1;
   }
-  if (run.currentStepId !== pendingGate.stepId) {
-    throw new Error("gate result does not match the current step");
+  if (run.currentStepId !== expectedStepId) {
+    return `current step "${run.currentStepId}" does not match reachable step "${expectedStepId}"`;
   }
-  const outcome = resolution.approved ? step.gate.approvedOutcome : step.gate.rejectedOutcome;
-  const feedback = boundedGateFeedback(resolution.feedback);
-  const stepStructuralDigest = workflow.stepStructuralDigests[pendingGate.stepId] ?? "";
-  if (resolution.approved && !stepStructuralDigest) {
-    throw new Error(`gated step "${pendingGate.stepId}" has no structural digest`);
+  if (reachedDone !== (run.status === "completed")) {
+    return reachedDone ? "a workflow that reached $done must be completed" : "a completed workflow has no $done transition in its history";
   }
-  const summary = resolution.approved ? pendingGate.summary ?? "" : gateRejectionSummary(feedback);
-  const decidedRun = recordCurrentGateDecision(run, {
-    provider: pendingGate.provider,
-    requestId: pendingGate.requestId,
-    approved: resolution.approved,
-    feedback,
-    resolvedAt: resolution.resolvedAt,
-    ...pendingGate.reviewId ? { reviewId: pendingGate.reviewId } : {}
-  }, now);
-  const runnableRun = withRunUpdate(decidedRun, {
-    status: "running",
-    pendingGate: undefined,
-    pausedFrom: undefined,
-    pauseReason: undefined,
-    gateArtifact: resolution.approved ? "" : pendingGate.artifact,
-    gateFeedback: resolution.approved ? "" : feedback
-  }, now);
-  const isSameStepHumanRevision = !resolution.approved && step.transitions[outcome] === pendingGate.stepId;
-  const advanced = advanceRun(workflow, runnableRun, outcome, summary, now, {}, {
-    sameStepHumanGateRevision: isSameStepHumanRevision
-  });
-  const completedApprovedGate = resolution.approved && advanced.history.length > runnableRun.history.length;
-  const history = completedApprovedGate ? advanced.history.map((entry, index) => index === advanced.history.length - 1 ? {
-    ...entry,
-    artifact: pendingGate.artifact,
-    approval: {
-      requestId: pendingGate.requestId,
-      artifact: pendingGate.artifact,
-      feedback,
-      stepStructuralDigest
+  if (run.status === "completed" && run.currentStepDigest !== run.history.at(-1)?.stepDigest) {
+    return "completed workflow current-step digest does not match its terminal history";
+  }
+  if (!sameVisitCounts(run.visits, expectedVisits)) {
+    return "workflow visit counts do not match its execution history";
+  }
+  const reviewedArtifact = run.reviewedArtifact ?? "";
+  const reviewedFeedback = run.reviewedFeedback ?? "";
+  if (reviewedArtifact !== (latestApproval?.artifact ?? "") || reviewedFeedback !== (latestApproval?.feedback ?? "")) {
+    return "reviewed artifact and feedback do not match authoritative approval history";
+  }
+  const currentStep2 = workflow.definition.steps[run.currentStepId];
+  if (!currentStep2) {
+    return `current step "${run.currentStepId}" is missing from the workflow`;
+  }
+  const currentStepChanged = run.currentStepDigest !== workflow.stepDigests[run.currentStepId];
+  if (sameWorkflowDigest && currentStepChanged) {
+    return `current step "${run.currentStepId}" does not match the active workflow digest`;
+  }
+  if (boundWorkspaceCwd && !currentStep2.subagent) {
+    return `bound workflow current step "${run.currentStepId}" must use a subagent`;
+  }
+  if (currentStepChanged)
+    return;
+  return validatePendingGate(run, currentStep2);
+}
+
+// src/engine/run-reconciliation.ts
+var reconcileRun = (run, workflow, now) => {
+  if (run.workflowId !== workflow.definition.id) {
+    return {
+      changed: false,
+      error: `run belongs to "${run.workflowId}", not "${workflow.definition.id}"`
+    };
+  }
+  const reconciledRun = run.workflowDigest === workflow.digest ? run : refreshApprovedGateHistory(run, workflow);
+  const changedHistoryIndex = run.workflowDigest === workflow.digest ? -1 : reconciledRun.history.findIndex((entry) => workflow.stepDigests[entry.stepId] !== entry.stepDigest);
+  const changedHistoryEntry = changedHistoryIndex >= 0 ? reconciledRun.history[changedHistoryIndex] : undefined;
+  if (changedHistoryEntry && !workflow.definition.steps[changedHistoryEntry.stepId]) {
+    return {
+      changed: true,
+      error: "a completed step was removed; abort or restore the configuration"
+    };
+  }
+  if (changedHistoryIndex < 0 && !workflow.definition.steps[run.currentStepId]) {
+    return {
+      changed: true,
+      error: `current step "${run.currentStepId}" was removed; abort or restore the configuration`
+    };
+  }
+  const semanticError = validateRunWorkflowSemantics(reconciledRun, workflow);
+  if (semanticError) {
+    return {
+      changed: run.workflowDigest !== workflow.digest,
+      error: `workflow checkpoint is inconsistent: ${semanticError}`
+    };
+  }
+  if (run.workflowDigest === workflow.digest) {
+    return { run, changed: false };
+  }
+  if (changedHistoryIndex >= 0) {
+    const changedEntry = changedHistoryEntry;
+    if (!changedEntry) {
+      return { changed: true, error: "changed history entry is unavailable" };
     }
-  } : entry) : advanced.history;
+    const retainedHistory = reconciledRun.history.slice(0, changedHistoryIndex);
+    const restartedStep = changedEntry.stepId;
+    const stepHandoff = retainedHistory.at(-1)?.summary ?? "";
+    const reviewedApproval = retainedReviewedApproval(workflow, retainedHistory);
+    return {
+      changed: true,
+      restartedStep,
+      run: withRunUpdate(reconciledRun, {
+        workflowDigest: workflow.digest,
+        status: "paused",
+        currentStepId: restartedStep,
+        currentStepDigest: workflow.stepDigests[restartedStep] ?? "",
+        history: retainedHistory,
+        currentStepAttempts: changedEntry.attempts,
+        currentStepOmittedAttempts: changedEntry.omittedAttempts,
+        visits: rebuildVisits(retainedHistory, restartedStep),
+        cwd: retainedWorkspaceCwd(reconciledRun, retainedHistory),
+        reviewedArtifact: reviewedApproval?.artifact ?? "",
+        reviewedFeedback: reviewedApproval?.feedback ?? "",
+        stepHandoff,
+        lastSummary: stepHandoff,
+        pendingGate: undefined,
+        pausedFrom: "running",
+        failedStepId: undefined,
+        pauseReason: `Configuration changed; restarted step "${restartedStep}"`,
+        gateArtifact: "",
+        gateFeedback: ""
+      }, now)
+    };
+  }
+  const currentDigest = workflow.stepDigests[run.currentStepId] ?? "";
+  const hasCurrentStepChanged = currentDigest !== reconciledRun.currentStepDigest;
+  const restartChanges = hasCurrentStepChanged ? {
+    status: "paused",
+    pendingGate: undefined,
+    pausedFrom: "running",
+    failedStepId: undefined,
+    pauseReason: `Configuration changed; restarted step "${run.currentStepId}"`,
+    gateArtifact: "",
+    gateFeedback: ""
+  } : {};
   return {
-    ...advanced,
-    history,
-    ...completedApprovedGate ? {
-      reviewedArtifact: pendingGate.artifact,
-      reviewedFeedback: feedback
-    } : {},
-    gateArtifact: resolution.approved ? "" : pendingGate.artifact,
-    gateFeedback: resolution.approved ? "" : feedback
+    changed: true,
+    ...hasCurrentStepChanged ? { restartedStep: run.currentStepId } : {},
+    run: withRunUpdate(reconciledRun, {
+      ...restartChanges,
+      workflowDigest: workflow.digest,
+      currentStepDigest: currentDigest
+    }, now)
   };
 };
-// src/engine/run-lifecycle.ts
-var allowedOutcomes = (workflow, run) => {
-  const step = currentStep(workflow, run);
-  if (!step)
-    return [];
-  const gateResolutionOutcomes = step.gate ? new Set([step.gate.approvedOutcome, step.gate.rejectedOutcome]) : undefined;
-  return [
-    ...Object.keys(step.transitions).filter((outcome) => !gateResolutionOutcomes?.has(outcome)),
-    ...step.gate ? [step.gate.submitOutcome] : []
-  ];
-};
-var pauseRun = (run, reason, now) => {
-  if (run.status !== "running" && run.status !== "awaiting-gate") {
-    return withRunUpdate(run, { pauseReason: reason || run.pauseReason }, now);
+// src/workflow-doctor.ts
+var lexical = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+var internalTargets = (step) => [
+  ...new Set(Object.values(step.transitions).filter((target) => target !== "$done" && target !== "$pause"))
+].sort(lexical);
+var adjacencyFor = (definition) => Object.fromEntries(Object.entries(definition.steps).sort(([left], [right]) => lexical(left, right)).map(([stepId, step]) => [stepId, internalTargets(step)]));
+var reachableSteps = (definition, adjacency) => {
+  const reachable = new Set;
+  const pending = [definition.start];
+  while (pending.length > 0) {
+    const stepId = pending.pop();
+    if (!stepId || reachable.has(stepId))
+      continue;
+    if (!definition.steps[stepId])
+      continue;
+    reachable.add(stepId);
+    pending.push(...adjacency[stepId] ?? []);
   }
-  return withRunUpdate(run, {
-    status: "paused",
-    pausedFrom: run.status,
-    pauseReason: reason || `Paused during step "${run.currentStepId}"`,
-    failedStepId: undefined
-  }, now);
-};
-var failRun = (run, reason, now) => {
-  const pausedRun = pauseRun(run, reason, now);
-  return pausedRun.status === "paused" ? { ...pausedRun, failedStepId: pausedRun.currentStepId } : pausedRun;
-};
-var resumeRun = (run, now) => {
-  if (run.status !== "paused")
-    return run;
-  return withRunUpdate(run, {
-    status: run.pausedFrom ?? (run.pendingGate ? "awaiting-gate" : "running"),
-    pauseReason: undefined,
-    pausedFrom: undefined,
-    failedStepId: undefined
-  }, now);
-};
-var setResumeInput = (run, input, now) => withRunUpdate(run, { resumeInput: input.trim() || undefined }, now);
-var abortRun = (run, reason, now) => withRunUpdate(run, {
-  status: "aborted",
-  pauseReason: reason || "Aborted by user",
-  pausedFrom: undefined,
-  failedStepId: undefined,
-  pendingGate: undefined,
-  resumeInput: undefined
-}, now);
-// src/engine/reconciliation-history.ts
-var isApprovedGateEntry = (workflow, entry) => {
-  const gate = workflow.definition.steps[entry.stepId]?.gate;
-  return gate !== undefined && entry.outcome === gate.approvedOutcome;
+  return reachable;
 };
-var latestApprovedGateEntry = (workflow, history) => {
-  for (let index = history.length - 1;index >= 0; index -= 1) {
-    const entry = history[index];
-    if (entry && isApprovedGateEntry(workflow, entry))
-      return { entry, index };
+var stepsThatCanComplete = (definition, adjacency) => {
+  const canComplete = new Set(Object.entries(definition.steps).filter(([, step]) => Object.values(step.transitions).includes("$done")).map(([stepId]) => stepId));
+  const reverse = new Map;
+  for (const [source, targets] of Object.entries(adjacency)) {
+    for (const target of targets) {
+      reverse.set(target, [...reverse.get(target) ?? [], source]);
+    }
   }
-  return;
-};
-var rebuildVisits = (history, currentStepId) => {
-  const visitedStepIds = [
-    ...history.map((entry) => entry.stepId),
-    currentStepId
-  ];
-  return visitedStepIds.reduce((visits, stepId) => ({
-    ...visits,
-    [stepId]: (visits[stepId] ?? 0) + 1
-  }), {});
-};
-var retainedWorkspaceCwd = (run, history) => {
-  for (let index = history.length - 1;index >= 0; index -= 1) {
-    const cwd = history[index]?.workspaceCwd;
-    if (cwd)
-      return cwd;
+  const pending = [...canComplete].sort(lexical);
+  while (pending.length > 0) {
+    const stepId = pending.pop();
+    if (!stepId)
+      continue;
+    for (const predecessor of (reverse.get(stepId) ?? []).sort(lexical)) {
+      if (canComplete.has(predecessor))
+        continue;
+      canComplete.add(predecessor);
+      pending.push(predecessor);
+    }
   }
-  return run.startCwd ?? run.cwd;
-};
-var retainedReviewedApproval = (workflow, history) => {
-  const retainedApproval = latestApprovedGateEntry(workflow, history);
-  const approval = retainedApproval?.entry.approval;
-  return approval ? { artifact: approval.artifact, feedback: approval.feedback } : undefined;
+  return canComplete;
 };
-var refreshApprovedGateHistory = (run, workflow) => {
-  const history = run.history.map((entry) => {
-    const gate = workflow.definition.steps[entry.stepId]?.gate;
-    const currentDigest = workflow.stepDigests[entry.stepId];
-    const currentStructuralDigest = workflow.stepStructuralDigests[entry.stepId];
-    const shouldRefresh = gate !== undefined && typeof currentDigest === "string" && currentDigest.length > 0 && typeof currentStructuralDigest === "string" && currentStructuralDigest.length > 0 && entry.outcome === gate.approvedOutcome && entry.approval?.stepStructuralDigest === currentStructuralDigest && entry.stepDigest !== currentDigest;
-    return shouldRefresh ? { ...entry, stepDigest: currentDigest } : entry;
-  });
-  const hasChanged = history.some((entry, index) => entry !== run.history[index]);
-  return hasChanged ? { ...run, history } : run;
+var stronglyConnectedComponents = (definition, adjacency) => {
+  let nextIndex = 0;
+  const indexes = new Map;
+  const lowLinks = new Map;
+  const stack = [];
+  const onStack = new Set;
+  const components = [];
+  const visit = (stepId) => {
+    indexes.set(stepId, nextIndex);
+    lowLinks.set(stepId, nextIndex);
+    nextIndex += 1;
+    stack.push(stepId);
+    onStack.add(stepId);
+    for (const target of adjacency[stepId] ?? []) {
+      if (!indexes.has(target)) {
+        visit(target);
+        lowLinks.set(stepId, Math.min(lowLinks.get(stepId) ?? 0, lowLinks.get(target) ?? 0));
+      } else if (onStack.has(target)) {
+        lowLinks.set(stepId, Math.min(lowLinks.get(stepId) ?? 0, indexes.get(target) ?? 0));
+      }
+    }
+    if (lowLinks.get(stepId) !== indexes.get(stepId))
+      return;
+    const component = [];
+    let member;
+    do {
+      member = stack.pop();
+      if (!member)
+        break;
+      onStack.delete(member);
+      component.push(member);
+    } while (member !== stepId);
+    components.push(component.sort(lexical));
+  };
+  for (const stepId of Object.keys(definition.steps).sort(lexical)) {
+    if (!indexes.has(stepId))
+      visit(stepId);
+  }
+  return components.sort((left, right) => lexical(left.join("\x00"), right.join("\x00")));
 };
-
-// src/engine/run-workflow-validation.ts
-var sameVisitCounts = (actual, expected) => {
-  const actualEntries = Object.entries(actual).sort(([left], [right]) => left.localeCompare(right));
-  const expectedEntries = Object.entries(expected).sort(([left], [right]) => left.localeCompare(right));
-  return actualEntries.length === expectedEntries.length && actualEntries.every(([stepId, count], index) => expectedEntries[index]?.[0] === stepId && expectedEntries[index][1] === count);
+var isCycle = (adjacency, component) => {
+  if (component.length > 1)
+    return true;
+  const [stepId] = component;
+  return Boolean(stepId && adjacency[stepId]?.includes(stepId));
 };
-var validateHistoryMetadata = (workflow, step, entry) => {
-  const shouldBind = step.workspace?.bindOn.includes(entry.outcome) === true;
-  if (shouldBind !== (entry.workspaceCwd !== undefined)) {
-    return shouldBind ? `history step "${entry.stepId}" is missing its workspace binding` : `history step "${entry.stepId}" has an unauthorized workspace binding`;
-  }
-  const isApprovedGate = step.gate !== undefined && entry.outcome === step.gate.approvedOutcome;
-  if (isApprovedGate && !entry.approval) {
-    return `history step "${entry.stepId}" is missing authoritative gate approval`;
-  }
-  if (isApprovedGate && entry.artifact !== entry.approval?.artifact) {
-    return `history step "${entry.stepId}" approval artifact is inconsistent`;
+function analyzeWorkflow(definition) {
+  const adjacency = adjacencyFor(definition);
+  const reachable = reachableSteps(definition, adjacency);
+  const canComplete = stepsThatCanComplete(definition, adjacency);
+  const issues = [];
+  const stranded = [...reachable].filter((stepId) => !canComplete.has(stepId)).sort(lexical);
+  if (!canComplete.has(definition.start)) {
+    issues.push({
+      level: "error",
+      code: "no-completion-path",
+      steps: [definition.start],
+      message: `start step ${definition.start} cannot reach $done`
+    });
   }
-  if (!isApprovedGate && (entry.approval || entry.artifact !== undefined)) {
-    return `history step "${entry.stepId}" has approval data for a non-approved outcome`;
+  if (stranded.length > 0) {
+    issues.push({
+      level: "error",
+      code: "reachable-step-cannot-reach-done",
+      steps: stranded,
+      message: `reachable step${stranded.length === 1 ? "" : "s"} ${stranded.join(", ")} cannot reach $done`
+    });
   }
-  if (isApprovedGate && entry.approval?.stepStructuralDigest !== workflow.stepStructuralDigests[entry.stepId]) {
-    return `history step "${entry.stepId}" approval does not match its configured structure`;
+  const unreachable = Object.keys(definition.steps).filter((stepId) => !reachable.has(stepId)).sort(lexical);
+  if (unreachable.length > 0) {
+    issues.push({
+      level: "warning",
+      code: "unreachable-steps",
+      steps: unreachable,
+      message: `unreachable step${unreachable.length === 1 ? "" : "s"}: ${unreachable.join(", ")}`
+    });
   }
-  return;
-};
-var validatePendingGate = (run, step) => {
-  const pending = run.pendingGate;
-  if (!pending)
-    return;
-  if (!step.gate || pending.stepId !== run.currentStepId || pending.provider !== step.gate.provider || pending.submittedOutcome !== step.gate.submitOutcome) {
-    return "pending gate does not match the current workflow step";
+  for (const component of stronglyConnectedComponents(definition, adjacency)) {
+    if (!isCycle(adjacency, component))
+      continue;
+    const componentIsReachable = component.some((stepId) => reachable.has(stepId));
+    const componentCanReachDone = component.some((stepId) => canComplete.has(stepId));
+    issues.push({
+      level: "warning",
+      code: "cycle",
+      steps: component,
+      reachable: componentIsReachable,
+      canReachDone: componentCanReachDone,
+      message: `${componentIsReachable ? "reachable" : "unreachable"} cyclic component: ${component.join(", ")}; ${componentCanReachDone ? "an exit can reach $done" : "no member can reach $done"}; maxStepVisits=${definition.maxStepVisits} bounds uninterrupted graph cycling`
+    });
   }
-  if (pending.provider === "prompt" && pending.reviewId !== undefined) {
-    return "built-in prompt gate cannot carry a Plannotator review id";
+  return {
+    workflowId: definition.id,
+    maxStepVisits: definition.maxStepVisits,
+    reachableSteps: [...reachable].sort(lexical),
+    issues
+  };
+}
+var escapeMarkdown = (value) => value.replaceAll("\\", "\\\\").replaceAll("|", "\\|");
+function formatWorkflowDoctor(reports) {
+  const lines = ["# Workflow doctor", ""];
+  for (const report of reports) {
+    const errors = report.issues.filter((issue) => issue.level === "error");
+    const warnings = report.issues.filter((issue) => issue.level === "warning");
+    lines.push(`## ${report.workflowId}`, "", `Result: ${errors.length > 0 ? "ERROR" : warnings.length > 0 ? "WARNING" : "PASS"}`, "", `Runtime loop guard: automatic graph advancement enters each step at most ${report.maxStepVisits} time${report.maxStepVisits === 1 ? "" : "s"} before the next attempted entry pauses the run. An explicit human rejection back to the same gated step bypasses that check for its transition because every revision awaits another decision; the visit is still recorded. This bounds unattended cycling; it does not guarantee $done or bound time spent inside a step or gate.`, "");
+    if (report.issues.length === 0) {
+      lines.push("- No liveness issues found.", "");
+      continue;
+    }
+    lines.push(...report.issues.map((issue) => `- ${issue.level.toUpperCase()} \`${issue.code}\`: ${escapeMarkdown(issue.message)}`), "");
   }
-  return;
-};
-function validateRunWorkflowSemantics(run, workflow) {
-  const sameWorkflowDigest = run.workflowDigest === workflow.digest;
-  let expectedStepId = workflow.definition.start;
-  let reachedDone = false;
-  let boundWorkspaceCwd;
-  let latestApproval;
-  const expectedVisits = { [expectedStepId]: 1 };
-  for (let index = 0;index < run.history.length; index += 1) {
+  return lines.join(`
+`).trimEnd();
+}
+
+// src/workflow-list.ts
+function escapeMarkdownTableCell(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll("|", "\\|").replace(/\r\n|\r|\n/g, " ");
+}
+function formatWorkflowList(workflows) {
+  return [
+    "| Workflow | Command | Description |",
+    "| --- | --- | --- |",
+    ...workflows.map((workflow) => `| \`${workflow.id}\` | \`/${workflow.command}\` | ${escapeMarkdownTableCell(workflow.description)} |`)
+  ].join(`
+`);
+}
+
+// src/harness/start-actions.ts
+function isCurrentSession(session, sessionEpoch) {
+  return session.isSessionActive && session.sessionEpoch === sessionEpoch;
+}
+function completedWorkspaceBinding(run, workflow) {
+  for (let index = run.history.length - 1;index >= 0; index -= 1) {
     const entry = run.history[index];
-    if (!entry)
+    if (!entry?.workspaceCwd)
       continue;
-    if (reachedDone) {
-      return "workflow history continues after a $done transition";
-    }
-    if (entry.stepId !== expectedStepId) {
-      return `history step "${entry.stepId}" is not reachable after "${expectedStepId}"`;
-    }
     const step = workflow.definition.steps[entry.stepId];
-    const configuredDigest = workflow.stepDigests[entry.stepId];
-    if (!step || entry.stepDigest !== configuredDigest) {
-      return sameWorkflowDigest ? `history step "${entry.stepId}" does not match the active workflow digest` : undefined;
-    }
-    const metadataError = validateHistoryMetadata(workflow, step, entry);
-    if (metadataError)
-      return metadataError;
-    if (entry.workspaceCwd) {
-      if (boundWorkspaceCwd !== undefined && boundWorkspaceCwd !== entry.workspaceCwd) {
-        return "workflow history attempts to replace an existing workspace binding";
-      }
-      boundWorkspaceCwd = entry.workspaceCwd;
-    }
-    if (entry.approval) {
-      latestApproval = {
-        artifact: entry.approval.artifact,
-        feedback: entry.approval.feedback
-      };
-    }
-    const target = step.transitions[entry.outcome];
-    if (!target) {
-      return `history outcome "${entry.outcome}" is not configured for step "${entry.stepId}"`;
-    }
-    if (target === "$pause") {
-      return `history step "${entry.stepId}" records a non-completing $pause transition`;
-    }
-    if (target === "$done") {
-      if (index !== run.history.length - 1) {
-        return "workflow history continues after a $done transition";
-      }
-      reachedDone = true;
-      continue;
+    if (!step?.workspace || !step.workspace.bindOn.includes(entry.outcome)) {
+      throw new Error(`workspace-binding step "${entry.stepId}" no longer matches the completed iteration`);
     }
-    expectedStepId = target;
-    expectedVisits[target] = (expectedVisits[target] ?? 0) + 1;
+    return {
+      cwd: entry.workspaceCwd,
+      allowedRoots: step.workspace.allowedRoots
+    };
+  }
+  return;
+}
+async function listWorkflows(context) {
+  const workflows = [...this.catalog.workflows.values()].sort((left, right) => left.definition.id.localeCompare(right.definition.id));
+  if (workflows.length === 0) {
+    context.ui.notify(`No workflows loaded from ${this.catalog.userDirectory}`, this.catalog.diagnostics.length > 0 ? "warning" : "info");
+    return;
+  }
+  this.pi.sendMessage({
+    customType: "workflow-list",
+    content: formatWorkflowList(workflows.map((workflow) => workflow.definition)),
+    display: true
+  });
+}
+async function doctorWorkflows(workflowId, context) {
+  const catalog = await this.dependencies.loadCatalog({
+    cwd: context.cwd,
+    projectTrusted: context.isProjectTrusted()
+  });
+  if (catalog.diagnostics.some((diagnostic) => diagnostic.level === "error")) {
+    context.ui.notify(`Workflow configuration errors:
+${formatCatalogDiagnostics(catalog)}`, "warning");
   }
-  if (run.currentStepId !== expectedStepId) {
-    return `current step "${run.currentStepId}" does not match reachable step "${expectedStepId}"`;
+  const selected = workflowId ? [catalog.workflows.get(workflowId)].filter((workflow) => workflow !== undefined) : [...catalog.workflows.values()].sort((left, right) => left.definition.id.localeCompare(right.definition.id));
+  if (workflowId && selected.length === 0) {
+    context.ui.notify(`Workflow "${workflowId}" is not loaded`, "error");
+    return;
   }
-  if (reachedDone !== (run.status === "completed")) {
-    return reachedDone ? "a workflow that reached $done must be completed" : "a completed workflow has no $done transition in its history";
+  if (selected.length === 0) {
+    context.ui.notify(`No workflows loaded from ${catalog.userDirectory}`, catalog.diagnostics.length > 0 ? "warning" : "info");
+    return;
   }
-  if (run.status === "completed" && run.currentStepDigest !== run.history.at(-1)?.stepDigest) {
-    return "completed workflow current-step digest does not match its terminal history";
+  this.pi.sendMessage({
+    customType: "workflow-doctor",
+    content: formatWorkflowDoctor(selected.map((workflow) => analyzeWorkflow(workflow.definition))),
+    display: true
+  });
+}
+async function startNow(workflowId, input, startContext, sessionEpoch) {
+  const { context } = startContext;
+  if (this.activeDelegation) {
+    context.ui.notify(`Cannot start a workflow while subagent "${this.activeDelegation.agent}" is still cancelling`, "warning");
+    return;
   }
-  if (!sameVisitCounts(run.visits, expectedVisits)) {
-    return "workflow visit counts do not match its execution history";
+  if (this.run && this.run.status !== "completed" && this.run.status !== "aborted") {
+    context.ui.notify(`Workflow "${this.run.workflowId}" is ${this.run.status}; resume or abort it first`, "warning");
+    return;
   }
-  const reviewedArtifact = run.reviewedArtifact ?? "";
-  const reviewedFeedback = run.reviewedFeedback ?? "";
-  if (reviewedArtifact !== (latestApproval?.artifact ?? "") || reviewedFeedback !== (latestApproval?.feedback ?? "")) {
-    return "reviewed artifact and feedback do not match authoritative approval history";
+  if (!context.isIdle()) {
+    context.abort();
+    await startContext.waitForIdle();
   }
-  const currentStep2 = workflow.definition.steps[run.currentStepId];
-  if (!currentStep2) {
-    return `current step "${run.currentStepId}" is missing from the workflow`;
+  if (!isCurrentSession(this, sessionEpoch)) {
+    context.ui.notify("Workflow start was superseded by a session change", "warning");
+    return;
   }
-  const currentStepChanged = run.currentStepDigest !== workflow.stepDigests[run.currentStepId];
-  if (sameWorkflowDigest && currentStepChanged) {
-    return `current step "${run.currentStepId}" does not match the active workflow digest`;
+  this.captureSkills(startContext.skills());
+  if (!await this.reloadCatalog(context, false)) {
+    context.ui.notify("Workflow start was superseded by a newer configuration load", "warning");
+    return;
   }
-  if (boundWorkspaceCwd && !currentStep2.subagent) {
-    return `bound workflow current step "${run.currentStepId}" must use a subagent`;
+  if (!isCurrentSession(this, sessionEpoch)) {
+    context.ui.notify("Workflow start was superseded by a session change", "warning");
+    return;
   }
-  if (currentStepChanged)
+  const workflow = this.catalog.workflows.get(workflowId);
+  if (!workflow) {
+    context.ui.notify(`Workflow "${workflowId}" is not loaded`, "error");
     return;
-  return validatePendingGate(run, currentStep2);
+  }
+  const livenessErrors = analyzeWorkflow(workflow.definition).issues.filter((issue) => issue.level === "error");
+  if (livenessErrors.length > 0) {
+    context.ui.notify(`Cannot start workflow; run /workflow-doctor ${workflowId}:
+${livenessErrors.map((issue) => issue.message).join(`
+`)}`, "error");
+    return;
+  }
+  const preflightErrors = this.preflight(workflow, workflow.definition.start);
+  if (preflightErrors.length > 0) {
+    context.ui.notify(`Cannot start workflow:
+${preflightErrors.join(`
+`)}`, "error");
+    return;
+  }
+  let canonicalStartCwd;
+  try {
+    canonicalStartCwd = this.dependencies.resolveWorkspaceDirectory({
+      candidateCwd: context.cwd,
+      startCwd: context.cwd,
+      allowedRoots: ["."]
+    });
+  } catch (error) {
+    context.ui.notify(`Cannot capture workflow working directory: ${error instanceof Error ? error.message : String(error)}`, "error");
+    return;
+  }
+  this.run = createRun(workflow, input.trim(), this.pi.getActiveTools(), this.dependencies.createRequestId(), this.dependencies.now(), canonicalStartCwd);
+  this.persist();
+  this.isolateMainSessionTools();
+  this.updateStatus();
+  this.launchCurrentStep(workflow);
 }
-
-// src/engine/run-reconciliation.ts
-var reconcileRun = (run, workflow, now) => {
-  if (run.workflowId !== workflow.definition.id) {
-    return {
-      changed: false,
-      error: `run belongs to "${run.workflowId}", not "${workflow.definition.id}"`
-    };
+async function restartNow(input, startContext, sessionEpoch) {
+  const { context } = startContext;
+  const completedRun = this.run;
+  if (!completedRun || completedRun.status !== "completed") {
+    context.ui.notify("Only a completed workflow can be restarted", "warning");
+    return;
   }
-  const reconciledRun = run.workflowDigest === workflow.digest ? run : refreshApprovedGateHistory(run, workflow);
-  const changedHistoryIndex = run.workflowDigest === workflow.digest ? -1 : reconciledRun.history.findIndex((entry) => workflow.stepDigests[entry.stepId] !== entry.stepDigest);
-  const changedHistoryEntry = changedHistoryIndex >= 0 ? reconciledRun.history[changedHistoryIndex] : undefined;
-  if (changedHistoryEntry && !workflow.definition.steps[changedHistoryEntry.stepId]) {
-    return {
-      changed: true,
-      error: "a completed step was removed; abort or restore the configuration"
-    };
+  if (this.activeDelegation) {
+    context.ui.notify(`Cannot restart while subagent "${this.activeDelegation.agent}" is still cancelling`, "warning");
+    return;
   }
-  if (changedHistoryIndex < 0 && !workflow.definition.steps[run.currentStepId]) {
-    return {
-      changed: true,
-      error: `current step "${run.currentStepId}" was removed; abort or restore the configuration`
-    };
+  if (!completedRun.startCwd) {
+    context.ui.notify("Cannot restart this workflow on the same worktree because its original start directory was not captured; start a new workflow instead", "error");
+    return;
   }
-  const semanticError = validateRunWorkflowSemantics(reconciledRun, workflow);
-  if (semanticError) {
-    return {
-      changed: run.workflowDigest !== workflow.digest,
-      error: `workflow checkpoint is inconsistent: ${semanticError}`
-    };
+  if (!context.isIdle()) {
+    context.abort();
+    await startContext.waitForIdle();
   }
-  if (run.workflowDigest === workflow.digest) {
-    return { run, changed: false };
+  if (!isCurrentSession(this, sessionEpoch) || this.run !== completedRun) {
+    context.ui.notify("Workflow restart was superseded by a session or workflow change", "warning");
+    return;
   }
-  if (changedHistoryIndex >= 0) {
-    const changedEntry = changedHistoryEntry;
-    if (!changedEntry) {
-      return { changed: true, error: "changed history entry is unavailable" };
+  this.captureSkills(startContext.skills());
+  if (!await this.reloadCatalog(context, false)) {
+    context.ui.notify("Workflow restart was superseded by a newer configuration load", "warning");
+    return;
+  }
+  if (!isCurrentSession(this, sessionEpoch) || this.run !== completedRun) {
+    context.ui.notify("Workflow restart was superseded by a session or workflow change", "warning");
+    return;
+  }
+  const workflow = this.catalog.workflows.get(completedRun.workflowId);
+  if (!workflow) {
+    context.ui.notify(`Workflow "${completedRun.workflowId}" is no longer loaded`, "error");
+    return;
+  }
+  const livenessErrors = analyzeWorkflow(workflow.definition).issues.filter((issue) => issue.level === "error");
+  if (livenessErrors.length > 0) {
+    context.ui.notify(`Cannot restart workflow; run /workflow-doctor ${workflow.definition.id}:
+${livenessErrors.map((issue) => issue.message).join(`
+`)}`, "error");
+    return;
+  }
+  const preflightErrors = this.preflight(workflow, workflow.definition.start);
+  if (preflightErrors.length > 0) {
+    context.ui.notify(`Cannot restart workflow:
+${preflightErrors.join(`
+`)}`, "error");
+    return;
+  }
+  let canonicalStartCwd;
+  let canonicalSessionCwd;
+  try {
+    canonicalStartCwd = this.dependencies.resolveWorkspaceDirectory({
+      candidateCwd: completedRun.startCwd,
+      startCwd: completedRun.startCwd,
+      allowedRoots: ["."]
+    });
+    canonicalSessionCwd = this.dependencies.resolveWorkspaceDirectory({
+      candidateCwd: context.cwd,
+      startCwd: context.cwd,
+      allowedRoots: ["."]
+    });
+  } catch (error) {
+    context.ui.notify(`Cannot restart workflow on its captured worktree: ${error instanceof Error ? error.message : String(error)}`, "error");
+    return;
+  }
+  if (canonicalStartCwd !== completedRun.startCwd || canonicalSessionCwd !== canonicalStartCwd) {
+    context.ui.notify("Current session cwd does not match the captured workflow start directory", "error");
+    return;
+  }
+  try {
+    const binding = completedWorkspaceBinding(completedRun, workflow);
+    if (binding) {
+      const canonicalWorkspaceCwd = this.dependencies.resolveWorkspaceDirectory({
+        candidateCwd: binding.cwd,
+        startCwd: canonicalStartCwd,
+        allowedRoots: binding.allowedRoots
+      });
+      if (canonicalWorkspaceCwd !== binding.cwd) {
+        throw new Error("previous workspace no longer resolves to its captured canonical directory");
+      }
     }
-    const retainedHistory = reconciledRun.history.slice(0, changedHistoryIndex);
-    const restartedStep = changedEntry.stepId;
-    const stepHandoff = retainedHistory.at(-1)?.summary ?? "";
-    const reviewedApproval = retainedReviewedApproval(workflow, retainedHistory);
-    return {
-      changed: true,
-      restartedStep,
-      run: withRunUpdate(reconciledRun, {
-        workflowDigest: workflow.digest,
-        status: "paused",
-        currentStepId: restartedStep,
-        currentStepDigest: workflow.stepDigests[restartedStep] ?? "",
-        history: retainedHistory,
-        currentStepAttempts: changedEntry.attempts,
-        currentStepOmittedAttempts: changedEntry.omittedAttempts,
-        visits: rebuildVisits(retainedHistory, restartedStep),
-        cwd: retainedWorkspaceCwd(reconciledRun, retainedHistory),
-        reviewedArtifact: reviewedApproval?.artifact ?? "",
-        reviewedFeedback: reviewedApproval?.feedback ?? "",
-        stepHandoff,
-        lastSummary: stepHandoff,
-        pendingGate: undefined,
-        pausedFrom: "running",
-        failedStepId: undefined,
-        pauseReason: `Configuration changed; restarted step "${restartedStep}"`,
-        gateArtifact: "",
-        gateFeedback: ""
-      }, now)
-    };
+    this.run = restartRun(workflow, completedRun, input.trim() || completedRun.input, this.pi.getActiveTools(), this.dependencies.now());
+  } catch (error) {
+    context.ui.notify(`Cannot restart workflow on the same worktree: ${error instanceof Error ? error.message : String(error)}`, "error");
+    return;
   }
-  const currentDigest = workflow.stepDigests[run.currentStepId] ?? "";
-  const hasCurrentStepChanged = currentDigest !== reconciledRun.currentStepDigest;
-  const restartChanges = hasCurrentStepChanged ? {
-    status: "paused",
-    pendingGate: undefined,
-    pausedFrom: "running",
-    failedStepId: undefined,
-    pauseReason: `Configuration changed; restarted step "${run.currentStepId}"`,
-    gateArtifact: "",
-    gateFeedback: ""
-  } : {};
-  return {
-    changed: true,
-    ...hasCurrentStepChanged ? { restartedStep: run.currentStepId } : {},
-    run: withRunUpdate(reconciledRun, {
-      ...restartChanges,
-      workflowDigest: workflow.digest,
-      currentStepDigest: currentDigest
-    }, now)
-  };
-};
+  this.persist();
+  this.isolateMainSessionTools();
+  this.updateStatus();
+  this.launchCurrentStep(workflow);
+}
+async function reloadNow(context) {
+  if (this.run && (this.run.status === "running" || this.run.status === "awaiting-gate")) {
+    context.ui.notify("Pause the workflow before reloading its configuration", "warning");
+    return;
+  }
+  this.captureSkills(context.getSystemPromptOptions().skills);
+  await this.reloadCatalog(context, true);
+}
+function createStartActions() {
+  return { listWorkflows, doctorWorkflows, startNow, restartNow, reloadNow };
+}
+
 // src/harness/step-reporting.ts
 var WORKFLOW_STEP_SUMMARY_MESSAGE_TYPE = "workflow-step-summary";
 var MAX_POSTED_STEP_SUMMARY_CHARS = 4000;
@@ -6777,6 +6982,17 @@ function buildDelegatedHandoffSection(handoff) {
     ""
   ];
 }
+function buildRestartWorkspaceSection(workspaceCwd) {
+  if (!workspaceCwd)
+    return [];
+  return [
+    "## Restart workspace constraint",
+    "",
+    `This iteration must reuse and rebind exactly this existing workspace: ${workspaceCwd}`,
+    "Do not create or substitute another workspace. If it cannot be safely reused, complete with a configured non-binding outcome that pauses the workflow.",
+    ""
+  ];
+}
 function buildDelegatedCompletionInstructions() {
   return [
     "This child is non-interactive. Never call `contact_supervisor`, `subagent_supervisor`, or `intercom`.",
@@ -6817,6 +7033,7 @@ function createTemplateValues({
   return {
     "workflow.input": run.input,
     "workflow.id": workflow.definition.id,
+    "workflow.iteration": String(run.iteration ?? 1),
     "run.id": run.runId,
     "step.id": run.currentStepId,
     "step.title": step.title,
@@ -6825,7 +7042,8 @@ function createTemplateValues({
     "reviewed.feedback": run.reviewedFeedback ?? "",
     "gate.artifact": run.gateArtifact ?? "",
     "gate.feedback": run.gateFeedback,
-    "resume.input": run.resumeInput ?? ""
+    "resume.input": run.resumeInput ?? "",
+    "restart.workspace": run.restartWorkspaceCwd ?? ""
   };
 }
 
@@ -6889,6 +7107,7 @@ function buildStepTask(options) {
     "",
     `Workflow: ${workflow.definition.id}`,
     `Run: ${run.runId}`,
+    `Iteration: ${run.iteration ?? 1}`,
     `Step: ${run.currentStepId} (${step.title})`,
     ...isDelegated ? [
       `Agent profile: ${step.subagent?.agent ?? "generalist"}`,
@@ -6900,6 +7119,7 @@ function buildStepTask(options) {
     prompt,
     "",
     ...isDelegated ? buildDelegatedHandoffSection(handoff) : [],
+    ...buildRestartWorkspaceSection(run.restartWorkspaceCwd),
     ...buildResumeInputSection(run, RESUME_INPUT_PLACEHOLDER.test(promptTemplate)),
     ...buildResourceSection({ execution, step }),
     "## Completion contract",
@@ -6998,9 +7218,17 @@ function registerLifecycle() {
     this.restoreFromSession(context);
     this.isSessionActive = true;
   });
-  this.pi.on("session_shutdown", async () => {
+  this.pi.on("session_shutdown", async (_event, context) => {
     this.sessionEpoch += 1;
     this.isSessionActive = false;
+    if (this.run) {
+      this.latestContext = context;
+      try {
+        this.persist();
+      } catch (error) {
+        context.ui.notify(`Workflow checkpoint could not be saved before shutdown: ${error instanceof Error ? error.message : String(error)}`, "error");
+      }
+    }
     this.cancelPromptReview();
     this.mainSteps.deactivate();
     await this.cancelActiveDelegation("Pi session shut down");
@@ -8097,6 +8325,9 @@ function enqueueMutation(context, operation) {
 function persist() {
   if (this.run) {
     this.pi.appendEntry(STATE_ENTRY_TYPE, structuredClone(this.run));
+    const session = this.latestContext?.sessionManager;
+    if (session)
+      this.dependencies.flushUnwrittenSession(session);
   }
 }
 function restoreFromSession(context) {
@@ -8231,6 +8462,7 @@ class WorkflowHarness {
   listWorkflows = START_ACTIONS.listWorkflows;
   doctorWorkflows = START_ACTIONS.doctorWorkflows;
   startNow = START_ACTIONS.startNow;
+  restartNow = START_ACTIONS.restartNow;
   reloadNow = START_ACTIONS.reloadNow;
   pauseNow = PAUSE_ACTIONS.pauseNow;
   abortNow = PAUSE_ACTIONS.abortNow;
@@ -8305,6 +8537,13 @@ class WorkflowHarness {
       waitForIdle: () => context.waitForIdle()
     }, sessionEpoch));
   }
+  restart(input, context) {
+    return this.enqueueMutation(context, (sessionEpoch) => this.restartNow(input, {
+      context,
+      skills: () => context.getSystemPromptOptions().skills,
+      waitForIdle: () => context.waitForIdle()
+    }, sessionEpoch));
+  }
   pause(reason, context) {
     return this.enqueueMutation(context, () => this.pauseNow(reason, context));
   }
@@ -8360,14 +8599,14 @@ var parseChildStructuredResult = ({
 // src/integrations/subagents/child-runtime-dependencies.ts
 import { randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
 import {
-  existsSync,
+  existsSync as existsSync2,
   lstatSync,
   readFileSync,
   realpathSync as realpathSync2,
   renameSync,
   statSync as statSync2,
   unlinkSync,
-  writeFileSync as writeFileSync2
+  writeFileSync as writeFileSync3
 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
 var tokensAreEqual = (actual, expected) => {
@@ -8377,7 +8616,7 @@ var tokensAreEqual = (actual, expected) => {
 };
 var DEFAULT_CHILD_RUNTIME_DEPENDENCIES = {
   fileSystem: {
-    exists: existsSync,
+    exists: existsSync2,
     inspect: lstatSync,
     readText: (path) => readFileSync(path, "utf8"),
     realPath: realpathSync2,
@@ -8385,7 +8624,7 @@ var DEFAULT_CHILD_RUNTIME_DEPENDENCIES = {
     stat: statSync2,
     unlink: unlinkSync,
     writeExclusive: (path, content) => {
-      writeFileSync2(path, content, {
+      writeFileSync3(path, content, {
         encoding: "utf8",
         flag: "wx",
         mode: 384