@wichayutdew/pi-workflows 2.0.1 → 2.2.0

package/dist/index.js

@@ -133,14 +133,17 @@ var DEFAULT_SETTINGS = {
 var PROMPT_VARIABLES = new Set([
   "workflow.input",
   "workflow.id",
+  "workflow.iteration",
   "run.id",
   "step.id",
   "step.title",
   "last.summary",
   "reviewed.artifact",
   "reviewed.feedback",
+  "gate.artifact",
   "gate.feedback",
-  "resume.input"
+  "resume.input",
+  "restart.workspace"
 ]);
 function validatePromptText(text, path) {
   return [...text.matchAll(/\{\{([^{}]+)\}\}/g)].flatMap((match) => {
@@ -660,6 +663,7 @@ var HARNESS_COMMAND_NAMES = [
   "workflow-list",
   "workflow-pause",
   "workflow-reload",
+  "workflow-restart",
   "workflow-resume",
   "workflow-start"
 ];
@@ -1342,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: {
@@ -2946,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";
@@ -3634,6 +3645,7 @@ function registerMainStepLifecycle({
 
 // src/engine/state-types.ts
 var RUN_STATE_VERSION = 1;
+var MAX_GATE_FEEDBACK_CHARS = 50000;
 var MAX_RESUME_INPUT_CHARS = 16000;
 var MAX_STEP_TRACE_TASK_CHARS = 64000;
 var MAX_STEP_TRACE_ATTEMPTS = 16;
@@ -4208,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),
@@ -4472,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,
@@ -4493,6 +4507,7 @@ var createRun = (workflow, input, baselineTools, runId, now, cwd) => {
     ...cwd ? { startCwd: cwd, cwd } : {},
     stepHandoff: "",
     lastSummary: "",
+    gateArtifact: "",
     gateFeedback: ""
   };
 };
@@ -4815,7 +4830,7 @@ function recordCurrentGateDecision(run, decision, now) {
 // src/engine/run-validation.ts
 var isRecord8 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 var isAbsoluteCwd = (value) => typeof value === "string" && value.length > 0 && isAbsolute8(value) && !value.includes("\x00");
-var isGateApproval = (value) => isRecord8(value) && typeof value.requestId === "string" && value.requestId.length > 0 && typeof value.artifact === "string" && value.artifact.trim().length > 0 && typeof value.feedback === "string" && typeof value.stepStructuralDigest === "string" && value.stepStructuralDigest.length > 0;
+var isGateApproval = (value) => isRecord8(value) && typeof value.requestId === "string" && value.requestId.length > 0 && typeof value.artifact === "string" && value.artifact.trim().length > 0 && typeof value.feedback === "string" && value.feedback.length <= MAX_GATE_FEEDBACK_CHARS && typeof value.stepStructuralDigest === "string" && value.stepStructuralDigest.length > 0;
 var isStepAttemptResult = (value) => isRecord8(value) && typeof value.outcome === "string" && typeof value.summary === "string" && value.summary.length <= MAX_STEP_TRACE_SUMMARY_CHARS && (value.summaryTruncated === undefined || value.summaryTruncated === true) && (value.artifact === undefined || typeof value.artifact === "string") && (typeof value.artifact !== "string" || value.artifact.length <= MAX_STEP_TRACE_ARTIFACT_CHARS) && (value.artifactTruncated === undefined || value.artifactTruncated === true) && !(value.artifactTruncated === true && value.artifact === undefined) && (value.workspaceCwd === undefined || isAbsoluteCwd(value.workspaceCwd));
 var isStepGateDecision = (value) => isRecord8(value) && (value.provider === "prompt" || value.provider === "plannotator") && typeof value.requestId === "string" && value.requestId.length > 0 && typeof value.approved === "boolean" && typeof value.feedback === "string" && value.feedback.length <= MAX_STEP_TRACE_SUMMARY_CHARS && (value.feedbackTruncated === undefined || value.feedbackTruncated === true) && typeof value.resolvedAt === "number" && (value.reviewId === undefined || typeof value.reviewId === "string");
 var isSafeTraceIdentityField = (value) => typeof value === "string" && value.length > 0 && !value.includes("\x00") && !value.includes("/") && !value.includes("\\") && value !== "." && value !== "..";
@@ -4862,11 +4877,12 @@ var isStepExecutionAttempts = (value) => Array.isArray(value) && value.length <=
   return value.slice(0, index).every((earlier) => earlier.ordinal === undefined || earlier.ordinal < ordinal);
 });
 var isStepHistoryEntry = (value) => isRecord8(value) && typeof value.stepId === "string" && typeof value.stepDigest === "string" && typeof value.outcome === "string" && typeof value.summary === "string" && (value.workspaceCwd === undefined || isAbsoluteCwd(value.workspaceCwd)) && (value.artifact === undefined || typeof value.artifact === "string") && (value.approval === undefined || isGateApproval(value.approval) && value.artifact === value.approval.artifact) && (value.attempts === undefined || isStepExecutionAttempts(value.attempts)) && (value.omittedAttempts === undefined || Number.isSafeInteger(value.omittedAttempts) && value.omittedAttempts > 0) && typeof value.completedAt === "number";
-var isGateResolution = (value) => isRecord8(value) && typeof value.approved === "boolean" && typeof value.feedback === "string" && typeof value.resolvedAt === "number";
+var isGateResolution = (value) => isRecord8(value) && typeof value.approved === "boolean" && typeof value.feedback === "string" && value.feedback.length <= MAX_GATE_FEEDBACK_CHARS && typeof value.resolvedAt === "number";
 var isPendingGate = (value) => isRecord8(value) && (value.provider === "prompt" || value.provider === "plannotator") && typeof value.requestId === "string" && value.requestId.length > 0 && typeof value.stepId === "string" && typeof value.artifact === "string" && (value.summary === undefined || typeof value.summary === "string") && typeof value.submittedOutcome === "string" && typeof value.requestedAt === "number" && (value.reviewId === undefined || typeof value.reviewId === "string") && (value.resolution === undefined || isGateResolution(value.resolution));
 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;
@@ -4890,15 +4906,18 @@ var hasValidWorkspaceState = (run, history) => {
 var isWorkflowRun = (value) => {
   if (!isRecord8(value))
     return false;
-  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";
+  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) && isOptionalString(value.stepHandoff) && 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
@@ -5081,6 +5100,7 @@ class WorkflowStatusView {
   statusShortcut;
   timer;
   state = initialViewportState();
+  pendingDetailTopKey = false;
   statusShortcutLabel;
   dependencies;
   transcriptCache = new Map;
@@ -5106,7 +5126,9 @@ class WorkflowStatusView {
   }
   invalidate() {}
   handleInput(data) {
-    if (data === "q" || data === "Q" || matchesKey(data, "ctrl+c") || matchesKey(data, "ctrl+d") || matchesKey(data, this.statusShortcut)) {
+    const isDetailHalfPageDown = this.state.mode === "detail" && matchesKey(data, Key.ctrl("d"));
+    const isDetailHalfPageUp = this.state.mode === "detail" && matchesKey(data, Key.ctrl("u"));
+    if (data === "q" || data === "Q" || matchesKey(data, "ctrl+c") || this.state.mode !== "detail" && matchesKey(data, "ctrl+d") || matchesKey(data, this.statusShortcut)) {
       this.close();
       return;
     }
@@ -5119,13 +5141,31 @@ class WorkflowStatusView {
       return;
     }
     const pageSize = Math.max(1, this.state.viewportRows - 2);
+    const contentHeight = Math.max(1, this.state.viewportRows - 1);
+    const halfPageSize = Math.max(1, Math.floor(contentHeight / 2));
     if (this.state.mode === "detail") {
-      if (matchesKey(data, Key.left) || data === "h") {
+      if (data === "gg" || data === "g" && this.pendingDetailTopKey) {
+        this.pendingDetailTopKey = false;
+        this.setScrollOffset(0);
+        return;
+      }
+      if (data === "g") {
+        this.pendingDetailTopKey = true;
+        return;
+      }
+      this.pendingDetailTopKey = false;
+      if (data === "G") {
+        this.setScrollOffset(Number.MAX_SAFE_INTEGER);
+      } else if (matchesKey(data, Key.left) || data === "h") {
         this.showBoard();
       } else if (matchesKey(data, Key.down) || data === "j") {
         this.setScrollOffset(this.state.scrollOffset + 1);
       } else if (matchesKey(data, Key.up) || data === "k") {
         this.setScrollOffset(this.state.scrollOffset - 1);
+      } else if (isDetailHalfPageDown) {
+        this.setScrollOffset(this.state.scrollOffset + halfPageSize);
+      } else if (isDetailHalfPageUp) {
+        this.setScrollOffset(this.state.scrollOffset - halfPageSize);
       } else if (matchesKey(data, Key.pageDown)) {
         this.setScrollOffset(this.state.scrollOffset + pageSize);
       } else if (matchesKey(data, Key.pageUp)) {
@@ -5137,6 +5177,7 @@ class WorkflowStatusView {
       }
       return;
     }
+    this.pendingDetailTopKey = false;
     if (matchesKey(data, Key.down) || data === "j") {
       this.moveSelection(1);
     } else if (matchesKey(data, Key.up) || data === "k") {
@@ -5168,7 +5209,7 @@ class WorkflowStatusView {
       this.ensureSelectedTranscripts(snapshot);
     }
     const rendered = lines.map((line) => padAnsi(truncateToWidth4(line, contentWidth, "…"), viewportWidth));
-    const page = paginateBoard(this.state, rendered, viewportWidth, this.tui.terminal?.rows, this.statusShortcutLabel, this.theme, this.state.mode === "detail" ? "↑/↓ or j/k scroll · PgUp/PgDn · ←/h/Esc back" : "↑/↓ or j/k select · Enter/→/l inspect · PgUp/PgDn");
+    const page = paginateBoard(this.state, rendered, viewportWidth, this.tui.terminal?.rows, this.statusShortcutLabel, this.theme, this.state.mode === "detail" ? "↑↓/jk · Ctrl+D/U half-page · gg/G top/bottom · PgUp/PgDn · ←/h/Esc" : "↑/↓ or j/k select · Enter/→/l inspect · PgUp/PgDn");
     this.state = page.state;
     return page.lines;
   }
@@ -5210,6 +5251,7 @@ class WorkflowStatusView {
     this.normalizeSelection(snapshot);
     if (!selectedStepDetail(snapshot, this.state.selectedIndex))
       return;
+    this.pendingDetailTopKey = false;
     this.state = { ...this.state, mode: "detail", scrollOffset: 0 };
     this.ensureSelectedTranscripts(snapshot);
     this.tui.requestRender(true);
@@ -5217,6 +5259,7 @@ class WorkflowStatusView {
   showBoard() {
     if (this.state.mode === "board")
       return;
+    this.pendingDetailTopKey = false;
     this.state = { ...this.state, mode: "board", scrollOffset: 0 };
     this.tui.requestRender(true);
   }
@@ -5309,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() {
@@ -5316,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
@@ -5373,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);
@@ -5489,397 +5569,134 @@ 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`
-    });
-  }
-  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: each step executes at most ${report.maxStepVisits} time${report.maxStepVisits === 1 ? "" : "s"} before the next attempted entry pauses an uninterrupted run. This bounds graph 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 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;
-  }
-  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");
-  }
-  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 (selected.length === 0) {
-    context.ui.notify(`No workflows loaded from ${catalog.userDirectory}`, catalog.diagnostics.length > 0 ? "warning" : "info");
-    return;
-  }
-  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 (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;
-  }
-  if (!context.isIdle()) {
-    context.abort();
-    await startContext.waitForIdle();
-  }
-  if (!isCurrentSession(this, sessionEpoch)) {
-    context.ui.notify("Workflow start was superseded by a session change", "warning");
-    return;
-  }
-  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 (!isCurrentSession(this, sessionEpoch)) {
-    context.ui.notify("Workflow start was superseded by a session change", "warning");
-    return;
-  }
-  const workflow = this.catalog.workflows.get(workflowId);
-  if (!workflow) {
-    context.ui.notify(`Workflow "${workflowId}" is not loaded`, "error");
-    return;
-  }
-  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);
-}
-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 = {}) => {
-  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,
-      gateFeedback: "",
-      pausedFrom: undefined,
-      pendingGate: undefined,
-      resumeInput: undefined
-    }, now);
-  }
-  if (!workflow.definition.steps[target]) {
-    throw new Error(`transition target "${target}" does not exist`);
-  }
-  const nextVisitCount = (run.visits[target] ?? 0) + 1;
-  const isOverVisitLimit = 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: summary,
-    lastSummary: summary,
-    gateFeedback: "",
-    resumeInput: undefined
-  }, now);
-};
-
-// src/engine/gate-transitions.ts
-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`);
-  }
-  const step = currentStep(workflow, run);
-  if (!step?.gate) {
-    throw new Error(`step "${run.currentStepId}" has no gate`);
-  }
-  if (outcome !== step.gate.submitOutcome) {
-    throw new Error(`gate expects outcome "${step.gate.submitOutcome}"`);
-  }
-  if (!artifact.trim()) {
-    throw new Error("gate submission requires a non-empty artifact");
+  if (!artifact.trim()) {
+    throw new Error("gate submission requires a non-empty artifact");
   }
   if (!summary.trim()) {
     throw new Error("gate submission requires a non-empty summary");
@@ -5907,37 +5724,55 @@ var attachGateReviewId = (run, reviewId, now) => {
   }
   return withRunUpdate(run, { pendingGate: { ...run.pendingGate, reviewId } }, now);
 };
-var failGate = (run, reason, now) => run.pendingGate ? withRunUpdate(run, {
-  status: "running",
-  pendingGate: undefined,
-  gateFeedback: reason,
-  pausedFrom: undefined,
-  pauseReason: undefined,
-  failedStepId: undefined
-}, now) : run;
-var storeGateResolution = (run, resolution, now) => run.pendingGate ? withRunUpdate(run, { pendingGate: { ...run.pendingGate, resolution } }, now) : run;
-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 (run.currentStepId !== pendingGate.stepId) {
-    throw new Error("gate result does not match the current step");
-  }
-  const outcome = resolution.approved ? step.gate.approvedOutcome : step.gate.rejectedOutcome;
-  const stepStructuralDigest = workflow.stepStructuralDigests[pendingGate.stepId] ?? "";
-  if (resolution.approved && !stepStructuralDigest) {
-    throw new Error(`gated step "${pendingGate.stepId}" has no structural digest`);
-  }
-  const summary = resolution.approved ? pendingGate.summary ?? "" : resolution.feedback ? `Gate rejected: ${resolution.feedback}` : "Gate rejected";
-  const decidedRun = recordCurrentGateDecision(run, {
+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`);
+  }
+  if (run.currentStepId !== pendingGate.stepId) {
+    throw new Error("gate result does not match the current step");
+  }
+  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`);
+  }
+  const summary = resolution.approved ? pendingGate.summary ?? "" : gateRejectionSummary(feedback);
+  const decidedRun = recordCurrentGateDecision(run, {
     provider: pendingGate.provider,
     requestId: pendingGate.requestId,
     approved: resolution.approved,
-    feedback: resolution.feedback,
+    feedback,
     resolvedAt: resolution.resolvedAt,
     ...pendingGate.reviewId ? { reviewId: pendingGate.reviewId } : {}
   }, now);
@@ -5946,9 +5781,13 @@ var resolveGate = (workflow, run, resolution, now) => {
     pendingGate: undefined,
     pausedFrom: undefined,
     pauseReason: undefined,
-    gateFeedback: resolution.feedback
+    gateArtifact: resolution.approved ? "" : pendingGate.artifact,
+    gateFeedback: resolution.approved ? "" : feedback
   }, now);
-  const advanced = advanceRun(workflow, runnableRun, outcome, summary, 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,
@@ -5956,7 +5795,7 @@ var resolveGate = (workflow, run, resolution, now) => {
     approval: {
       requestId: pendingGate.requestId,
       artifact: pendingGate.artifact,
-      feedback: resolution.feedback,
+      feedback,
       stepStructuralDigest
     }
   } : entry) : advanced.history;
@@ -5965,12 +5804,21 @@ var resolveGate = (workflow, run, resolution, now) => {
     history,
     ...completedApprovedGate ? {
       reviewedArtifact: pendingGate.artifact,
-      reviewedFeedback: resolution.feedback
+      reviewedFeedback: feedback
     } : {},
-    gateFeedback: resolution.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;
+  }
+  return;
+};
 var allowedOutcomes = (workflow, run) => {
   const step = currentStep(workflow, run);
   if (!step)
@@ -6015,6 +5863,32 @@ var abortRun = (run, reason, now) => withRunUpdate(run, {
   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");
+  }
+  if (!run.startCwd) {
+    throw new Error("the completed workflow has no captured start directory; start a new workflow instead");
+  }
+  const previousIteration = run.iteration ?? 1;
+  if (!Number.isSafeInteger(previousIteration) || previousIteration < 1) {
+    throw new Error("the completed workflow has an invalid iteration number");
+  }
+  if (previousIteration >= Number.MAX_SAFE_INTEGER) {
+    throw new Error("the workflow iteration limit has been reached");
+  }
+  const workspaceCwd = completedWorkspaceCwd(run);
+  if (workspaceCwd && run.cwd !== workspaceCwd) {
+    throw new Error("the completed workflow workspace does not match its recorded binding");
+  }
+  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;
@@ -6155,126 +6029,523 @@ function validateRunWorkflowSemantics(run, workflow) {
     expectedStepId = target;
     expectedVisits[target] = (expectedVisits[target] ?? 0) + 1;
   }
-  if (run.currentStepId !== expectedStepId) {
-    return `current step "${run.currentStepId}" does not match reachable step "${expectedStepId}"`;
+  if (run.currentStepId !== expectedStepId) {
+    return `current step "${run.currentStepId}" does not match reachable step "${expectedStepId}"`;
+  }
+  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 (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" };
+    }
+    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 {
+    changed: true,
+    ...hasCurrentStepChanged ? { restartedStep: run.currentStepId } : {},
+    run: withRunUpdate(reconciledRun, {
+      ...restartChanges,
+      workflowDigest: workflow.digest,
+      currentStepDigest: currentDigest
+    }, 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 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 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 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));
+      }
+    }
+    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")));
+};
+var isCycle = (adjacency, component) => {
+  if (component.length > 1)
+    return true;
+  const [stepId] = component;
+  return Boolean(stepId && adjacency[stepId]?.includes(stepId));
+};
+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 (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 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(", ")}`
+    });
+  }
+  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`
+    });
+  }
+  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 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?.workspaceCwd)
+      continue;
+    const step = workflow.definition.steps[entry.stepId];
+    if (!step?.workspace || !step.workspace.bindOn.includes(entry.outcome)) {
+      throw new Error(`workspace-binding step "${entry.stepId}" no longer matches the completed iteration`);
+    }
+    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");
+  }
+  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}"`,
-        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}"`,
-    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;
@@ -6711,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`.",
@@ -6732,7 +7014,7 @@ function currentStepHandoff(run) {
     "Incoming previous-step handoff:",
     incomingHandoff,
     "",
-    "Latest paused attempt:",
+    "Latest current-step summary:",
     run.lastSummary
   ].join(`
 `);
@@ -6751,14 +7033,17 @@ 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,
     "last.summary": currentStepHandoff(run),
     "reviewed.artifact": run.reviewedArtifact ?? "",
     "reviewed.feedback": run.reviewedFeedback ?? "",
+    "gate.artifact": run.gateArtifact ?? "",
     "gate.feedback": run.gateFeedback,
-    "resume.input": run.resumeInput ?? ""
+    "resume.input": run.resumeInput ?? "",
+    "restart.workspace": run.restartWorkspaceCwd ?? ""
   };
 }
 
@@ -6822,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"}`,
@@ -6833,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",
@@ -6931,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");
@@ -8030,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) {
@@ -8164,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;
@@ -8238,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));
   }
@@ -8293,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) => {
@@ -8310,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,
@@ -8318,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