@pixelbyte-software/pixcode 1.42.1 → 1.42.3

package/server/modules/orchestration/workflows/workflow-replay.ts

@@ -0,0 +1,254 @@
+import type {
+  Workflow,
+  WorkflowNode,
+  WorkflowNodeRun,
+  WorkflowRun,
+} from '@/modules/orchestration/workflows/workflow.types.js';
+import { redactTraceText } from '@/modules/orchestration/workflows/workflow-trace.js';
+
+export const PIXCODE_REPLAY_PROTOCOL = 'pixcode.workflow-replay.v1';
+
+export type WorkflowReplayScope = 'run' | 'node';
+export type WorkflowReplaySafetyKind = 'file-write' | 'shell' | 'network';
+
+export interface WorkflowReplayOperation {
+  kind: WorkflowReplaySafetyKind;
+  nodeId?: string;
+  summary: string;
+}
+
+export interface WorkflowReplayPlan {
+  protocol: typeof PIXCODE_REPLAY_PROTOCOL;
+  sourceRunId: string;
+  sourceWorkflowId: string;
+  scope: WorkflowReplayScope;
+  fromNodeId?: string;
+  selectedNodeIds: string[];
+  requiresApproval: boolean;
+  approvalReasons: string[];
+  destructiveOperations: WorkflowReplayOperation[];
+  limitations: string[];
+  input: string;
+  workflow: Workflow;
+  metadata: Record<string, unknown>;
+}
+
+function safeNodeId(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_]+/g, '_').slice(0, 48) || 'node';
+}
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : undefined;
+}
+
+function visibleNodes(run: WorkflowRun): WorkflowNodeRun[] {
+  return run.nodeRuns.filter((node) => !node.internal);
+}
+
+function defaultReplayNode(run: WorkflowRun): WorkflowNodeRun | undefined {
+  return visibleNodes(run).find((node) => node.status === 'failed')
+    ?? [...visibleNodes(run)].reverse().find((node) => node.status !== 'skipped')
+    ?? visibleNodes(run)[0];
+}
+
+function selectReplayNodes(run: WorkflowRun, scope: WorkflowReplayScope, fromNodeId?: string): WorkflowNodeRun[] {
+  const nodes = visibleNodes(run);
+  if (scope === 'run') return nodes;
+
+  const requested = fromNodeId
+    ? nodes.find((node) => node.nodeId === fromNodeId)
+    : defaultReplayNode(run);
+  return requested ? [requested] : [];
+}
+
+function compact(value: string | undefined, run: WorkflowRun, maxLength = 1_200): string | undefined {
+  return redactTraceText(value, run, maxLength);
+}
+
+function nodeTraceSummary(run: WorkflowRun, node: WorkflowNodeRun): string {
+  const artifactTypes = (node.artifacts ?? []).map((artifact) => artifact.type).filter(Boolean);
+  return [
+    `Step: ${node.agentLabel || node.nodeId}`,
+    `Node id: ${node.nodeId}`,
+    `Status: ${node.status}`,
+    node.stage ? `Stage: ${node.stage}` : undefined,
+    node.adapterId ? `Adapter: ${node.adapterId}` : undefined,
+    node.model ? `Model: ${node.model}` : undefined,
+    node.error ? `Error: ${compact(node.error, run, 800)}` : undefined,
+    artifactTypes.length > 0 ? `Artifacts: ${artifactTypes.join(', ')}` : undefined,
+    node.outputText ? `Output excerpt:\n${compact(node.outputText, run)}` : undefined,
+  ].filter(Boolean).join('\n');
+}
+
+function replayTraceSummary(run: WorkflowRun, nodes: WorkflowNodeRun[]): string {
+  return nodes.map((node) => nodeTraceSummary(run, node)).join('\n\n---\n\n');
+}
+
+function pushOperation(
+  operations: WorkflowReplayOperation[],
+  kind: WorkflowReplaySafetyKind,
+  nodeId: string | undefined,
+  summary: string,
+): void {
+  if (operations.some((operation) =>
+    operation.kind === kind && operation.nodeId === nodeId && operation.summary === summary,
+  )) {
+    return;
+  }
+  operations.push({ kind, nodeId, summary });
+}
+
+function detectReplayOperations(run: WorkflowRun, nodes: WorkflowNodeRun[]): WorkflowReplayOperation[] {
+  const operations: WorkflowReplayOperation[] = [];
+
+  for (const node of nodes) {
+    for (const artifact of node.artifacts ?? []) {
+      if (artifact.type === 'file-diff') {
+        pushOperation(operations, 'file-write', node.nodeId, 'Prior step produced a file diff artifact.');
+      }
+      if (artifact.type === 'command-output') {
+        pushOperation(operations, 'shell', node.nodeId, 'Prior step produced command output.');
+      }
+      const text = [artifact.text, artifact.data ? JSON.stringify(artifact.data) : undefined]
+        .filter(Boolean)
+        .join('\n')
+        .toLocaleLowerCase('en');
+      if (/https?:\/\/|curl |wget |gh |npm publish|npm install|git push|ssh /u.test(text)) {
+        pushOperation(operations, 'network', node.nodeId, 'Prior artifact references a network-capable operation.');
+      }
+    }
+
+    const text = [node.outputText, node.error, node.promptPreview].filter(Boolean).join('\n').toLocaleLowerCase('en');
+    if (/apply_patch|write file|file write|modified files|changed files/u.test(text)) {
+      pushOperation(operations, 'file-write', node.nodeId, 'Prior step text references file-write activity.');
+    }
+    if (/shell|command|terminal|npm run|node |python |php |go test|cargo |make |exit code/u.test(text)) {
+      pushOperation(operations, 'shell', node.nodeId, 'Prior step text references shell execution.');
+    }
+    if (/https?:\/\/|curl |wget |gh |npm publish|npm install|git push|ssh |network/u.test(text)) {
+      pushOperation(operations, 'network', node.nodeId, 'Prior step text references a network-capable operation.');
+    }
+  }
+
+  return operations;
+}
+
+function replayNodeFromRunNode(
+  node: WorkflowNodeRun,
+  index: number,
+  previousReplayNodeId: string | undefined,
+  traceSummary: string,
+  limitations: string[],
+  requiresApproval: boolean,
+): WorkflowNode {
+  const replayNodeId = `replay_${index + 1}_${safeNodeId(node.nodeId)}`;
+  return {
+    id: replayNodeId,
+    adapterId: node.adapterId || 'claude-code',
+    agentInstanceId: node.agentInstanceId,
+    agentLabel: node.agentLabel ? `${node.agentLabel} Replay` : 'Replay agent',
+    assignment: node.assignment ? `Replay: ${node.assignment}` : `Replay source node ${node.nodeId}`,
+    stage: node.stage ? `replay_${node.stage}` : 'replay',
+    model: node.model,
+    permissionMode: node.permissionMode === 'bypassPermissions' ? 'default' : node.permissionMode,
+    timeoutMs: node.timeoutMs,
+    inputs: previousReplayNodeId ? [previousReplayNodeId] : [],
+    output: 'both',
+    onFail: 'abort',
+    prompt: [
+      'This is a Pixcode workflow replay run.',
+      `Replay protocol: ${PIXCODE_REPLAY_PROTOCOL}`,
+      `Source node: ${node.nodeId}`,
+      requiresApproval
+        ? 'Replay safety review found prior shell, network, or file-write activity. Do not repeat any such action unless the current CLI permission flow asks for and receives user approval.'
+        : 'Replay safety review did not find prior shell, network, or file-write artifacts, but still avoid destructive actions unless they are required and approved.',
+      'Use the trace summary to continue from the failure or inspect the run. Do not expose secrets, local-only paths, raw tool protocol, or irrelevant logs.',
+      `Known limitations:\n- ${limitations.join('\n- ')}`,
+      `Trace summary:\n${traceSummary}`,
+      `Original step prompt:\n${node.promptPreview || '(No source prompt was stored.)'}`,
+    ].join('\n\n'),
+  };
+}
+
+export function buildWorkflowReplayPlan(
+  run: WorkflowRun,
+  options: {
+    scope?: WorkflowReplayScope;
+    fromNodeId?: string;
+  } = {},
+): WorkflowReplayPlan {
+  const scope = options.scope ?? 'node';
+  const nodes = selectReplayNodes(run, scope, options.fromNodeId);
+  if (nodes.length === 0) {
+    throw new Error('No replayable workflow steps were found.');
+  }
+
+  const limitations = [
+    'Replay uses stored run traces, prompt previews, messages, and artifacts; it cannot reproduce hidden provider state.',
+    'Replay reconstructs selected steps as a new workflow run instead of mutating the source run.',
+    'Shell, network, and file-write actions stay under the current CLI permission flow and require explicit replay approval when detected.',
+  ];
+  const destructiveOperations = detectReplayOperations(run, nodes);
+  const requiresApproval = destructiveOperations.length > 0;
+  const traceSummary = replayTraceSummary(run, nodes);
+  const replayNodes = nodes.reduce<WorkflowNode[]>((accumulator, node, index) => {
+    const previousReplayNodeId = accumulator[accumulator.length - 1]?.id;
+    accumulator.push(replayNodeFromRunNode(
+      node,
+      index,
+      scope === 'run' ? previousReplayNodeId : undefined,
+      traceSummary,
+      limitations,
+      requiresApproval,
+    ));
+    return accumulator;
+  }, []);
+  const settings = readRecord(run.metadata?.settings) ?? {};
+  const replayMetadata = {
+    protocol: PIXCODE_REPLAY_PROTOCOL,
+    sourceRunId: run.id,
+    sourceWorkflowId: run.workflowId,
+    scope,
+    fromNodeId: options.fromNodeId,
+    selectedNodeIds: nodes.map((node) => node.nodeId),
+    requiresApproval,
+    destructiveOperations,
+    limitations,
+    createdAt: Date.now(),
+  };
+
+  return {
+    protocol: PIXCODE_REPLAY_PROTOCOL,
+    sourceRunId: run.id,
+    sourceWorkflowId: run.workflowId,
+    scope,
+    fromNodeId: options.fromNodeId,
+    selectedNodeIds: nodes.map((node) => node.nodeId),
+    requiresApproval,
+    approvalReasons: destructiveOperations.map((operation) =>
+      `${operation.kind}${operation.nodeId ? ` in ${operation.nodeId}` : ''}: ${operation.summary}`,
+    ),
+    destructiveOperations,
+    limitations,
+    input: [
+      `Replay ${scope === 'run' ? 'full workflow run' : 'workflow step'} from source run ${run.id}.`,
+      run.input ? `Original request:\n${compact(run.input, run, 2_000)}` : undefined,
+    ].filter(Boolean).join('\n\n'),
+    workflow: {
+      id: `${run.workflowId}_replay`,
+      name: `Replay ${run.workflowId}`,
+      description: 'Replay generated from stored Pixcode workflow trace data.',
+      trigger: 'manual',
+      nodes: replayNodes,
+    },
+    metadata: {
+      ...run.metadata,
+      workflowName: `Replay: ${String(run.metadata?.workflowName ?? run.workflowId)}`,
+      replay: replayMetadata,
+      settings: {
+        ...settings,
+        replayMode: true,
+      },
+    },
+  };
+}

package/server/modules/orchestration/workflows/workflow-runner.ts

@@ -16,6 +16,11 @@ import {
   buildWorkflowContextPacket,
   formatContextPacketForPrompt,
 } from '@/modules/orchestration/workflows/context-packet.js';
+import {
+  type WorkflowFallbackTrigger,
+  classifyWorkflowFailure,
+  resolveWorkflowFallbackDecision,
+} from '@/modules/orchestration/workflows/workflow-fallback-policy.js';
 import {
   type ResolvedWorkspaceTarget,
   resolveWorkflowWorkspace,
@@ -23,6 +28,7 @@ import {
   workspaceTargetMetadata,
 } from '@/modules/orchestration/workflows/workspace-target.js';
 import { workflowStore } from '@/modules/orchestration/workflows/workflow-store.js';
+import { orchestrationTaskService } from '@/modules/orchestration/tasks/orchestration-task.service.js';
 // @ts-ignore — plain-JS service
 import {
   getDefaultProviderModel,
@@ -1123,6 +1129,8 @@ function nodeRunFromNode(node: WorkflowNode): WorkflowNodeRun {
     timeoutMs: node.timeoutMs,
     stage: node.stage,
     internal: node.internal,
+    fallbackTrigger: node.fallbackTrigger,
+    fallbackSourceNodeId: node.fallbackSourceNodeId,
     status: 'queued',
   };
 }
@@ -1208,7 +1216,7 @@ class WorkflowRunner {
     const runtimeWorkflow = expandWorkflowForRun(workflow, metadata);
     validateWorkflow(runtimeWorkflow);
     const workspaceTarget = resolveWorkflowWorkspace(metadata);
-    const runMetadata = {
+    const runMetadata: Record<string, unknown> = {
       ...metadata,
       projectPath: workspaceTarget.projectPath,
       selectedProjectPath: workspaceTarget.selectedProjectPath,
@@ -1225,6 +1233,10 @@ class WorkflowRunner {
       metadata: runMetadata,
     };
     workflowStore.setRun(run);
+    const orchestrationTaskId = readString(runMetadata.orchestrationTaskId);
+    if (orchestrationTaskId) {
+      orchestrationTaskService.linkWorkflowRun(orchestrationTaskId, run);
+    }
     void this.execute(runtimeWorkflow, run);
     return run;
   }
@@ -1276,7 +1288,12 @@ class WorkflowRunner {
     return readAgentAssignments(run.metadata).find((agent) => agent.instanceId === fallbackAgentInstanceId);
   }
 
-  private createFallbackNode(node: WorkflowNode, fallbackAgent: AgentAssignment, reason: string): WorkflowNode {
+  private createFallbackNode(
+    node: WorkflowNode,
+    fallbackAgent: AgentAssignment,
+    reason: string,
+    fallbackTrigger: WorkflowFallbackTrigger,
+  ): WorkflowNode {
     const fallbackSuffix = safeNodeId(fallbackAgent.instanceId, 'fallback');
     return {
       ...node,
@@ -1289,9 +1306,12 @@ class WorkflowRunner {
       model: fallbackAgent.model,
       permissionMode: fallbackAgent.permissionMode,
       toolsSettings: fallbackAgent.toolsSettings,
+      fallbackTrigger,
+      fallbackSourceNodeId: node.id,
       prompt: [
         'The previous CLI agent failed on this orchestration step.',
         `Failed step: ${node.agentLabel || node.id}`,
+        `Fallback trigger: ${fallbackTrigger}`,
         `Failure: ${reason}`,
         'Take over the same assignment as the backup CLI. Use the original goal and upstream context.',
         'Do not repeat unrelated work; complete the failed step and report what you did.',
@@ -1301,6 +1321,32 @@ class WorkflowRunner {
     };
   }
 
+  private recordFallbackSkipped(
+    run: WorkflowRun,
+    node: WorkflowNode,
+    reason: string,
+    fallbackTrigger: WorkflowFallbackTrigger,
+    skippedReason: string,
+  ): void {
+    const fallbackSkippedEvents = Array.isArray(run.metadata?.fallbackSkippedEvents)
+      ? run.metadata.fallbackSkippedEvents
+      : [];
+    run.metadata = {
+      ...run.metadata,
+      fallbackSkippedEvents: [
+        ...fallbackSkippedEvents,
+        {
+          nodeId: node.id,
+          trigger: fallbackTrigger,
+          reason,
+          skippedReason,
+          createdAt: Date.now(),
+        },
+      ],
+    };
+    workflowStore.setRun(run);
+  }
+
   private async runFallbackAfterFailure(
     node: WorkflowNode,
     workflow: Workflow,
@@ -1309,9 +1355,29 @@ class WorkflowRunner {
     started: Set<string>,
     completed: Set<string>,
     reason: string,
+    trigger?: WorkflowFallbackTrigger,
   ): Promise<boolean> {
+    const fallbackTrigger = classifyWorkflowFailure(reason, trigger);
     const fallbackAgent = this.fallbackAgentFor(run, node);
     if (!fallbackAgent) {
+      this.recordFallbackSkipped(run, node, reason, fallbackTrigger, 'No fallback agent is configured for this run.');
+      return false;
+    }
+    const decision = resolveWorkflowFallbackDecision({
+      run,
+      node,
+      reason,
+      trigger: fallbackTrigger,
+      fallbackAgentInstanceId: fallbackAgent.instanceId,
+    });
+    if (!decision.shouldFallback) {
+      this.recordFallbackSkipped(
+        run,
+        node,
+        reason,
+        decision.trigger,
+        decision.skippedReason ?? 'Fallback policy skipped this failure.',
+      );
       return false;
     }
     if (workflow.nodes.length + 1 > 64) {
@@ -1323,7 +1389,7 @@ class WorkflowRunner {
       return false;
     }
 
-    let fallbackNode = this.createFallbackNode(node, fallbackAgent, reason);
+    let fallbackNode = this.createFallbackNode(node, fallbackAgent, reason, decision.trigger);
     let collision = 1;
     while (workflow.nodes.some((candidate) => candidate.id === fallbackNode.id)) {
       collision += 1;
@@ -1357,6 +1423,8 @@ class WorkflowRunner {
           nodeId: node.id,
           fallbackNodeId: fallbackNode.id,
           fallbackAgentInstanceId: fallbackAgent.instanceId,
+          trigger: decision.trigger,
+          policy: decision.policy,
           reason,
           startedAt: Date.now(),
         },
@@ -1528,6 +1596,7 @@ class WorkflowRunner {
     } finally {
       run.finishedAt = run.finishedAt ?? Date.now();
       workflowStore.setRun(run);
+      orchestrationTaskService.updateFromWorkflowRun(run);
       notifyWorkflowRunFinished(run);
       this.cancelingRuns.delete(run.id);
     }
@@ -1658,7 +1727,16 @@ class WorkflowRunner {
         workflowStore.setRun(run);
         return;
       }
-      if (await this.runFallbackAfterFailure(node, workflow, run, outputs, started, completed, nodeRun.error)) {
+      if (await this.runFallbackAfterFailure(
+        node,
+        workflow,
+        run,
+        outputs,
+        started,
+        completed,
+        nodeRun.error,
+        'provider_failure',
+      )) {
         return;
       }
       if (node.onFail === 'continue') {
@@ -1710,7 +1788,16 @@ class WorkflowRunner {
         workflowStore.setRun(run);
         return;
       }
-      if (await this.runFallbackAfterFailure(node, workflow, run, outputs, started, completed, nodeRun.error)) {
+      if (await this.runFallbackAfterFailure(
+        node,
+        workflow,
+        run,
+        outputs,
+        started,
+        completed,
+        nodeRun.error,
+        'timeout',
+      )) {
         return;
       }
       if (node.onFail === 'continue') {
@@ -1744,7 +1831,16 @@ class WorkflowRunner {
           nodeRun.status = 'failed';
           nodeRun.error = visibleHandoffError;
           workflowStore.setRun(run);
-          if (await this.runFallbackAfterFailure(node, workflow, run, outputs, started, completed, visibleHandoffError)) {
+          if (await this.runFallbackAfterFailure(
+            node,
+            workflow,
+            run,
+            outputs,
+            started,
+            completed,
+            visibleHandoffError,
+            'invalid_output',
+          )) {
             return;
           }
           if (node.onFail === 'continue') {
@@ -1783,7 +1879,16 @@ class WorkflowRunner {
       workflowStore.setRun(run);
       return;
     }
-    if (await this.runFallbackAfterFailure(node, workflow, run, outputs, started, completed, nodeRun.error)) {
+    if (await this.runFallbackAfterFailure(
+      node,
+      workflow,
+      run,
+      outputs,
+      started,
+      completed,
+      nodeRun.error,
+      classifyWorkflowFailure(`${nodeRun.error}\n${nodeRun.outputText ?? ''}`),
+    )) {
       return;
     }
     if (node.onFail === 'continue') {

package/server/modules/orchestration/workflows/workflow-trace.ts

@@ -22,6 +22,10 @@ function readString(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim() ? value : undefined;
 }
 
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : undefined;
+}
+
 function redactionValues(run: WorkflowRun): string[] {
   const metadata = run.metadata ?? {};
   const workspaceTarget = metadata.workspaceTarget && typeof metadata.workspaceTarget === 'object'
@@ -140,6 +144,78 @@ export function buildWorkflowTrace(run: WorkflowRun): WorkflowTraceEvent[] {
     },
   });
 
+  const replay = readRecord(run.metadata?.replay);
+  if (replay) {
+    pushEvent(events, {
+      id: traceId([run.id, 'replay']),
+      type: 'run',
+      severity: replay.requiresApproval ? 'warning' : 'info',
+      status: run.status,
+      timestamp: run.startedAt + 0.25,
+      actor: 'Pixcode',
+      title: 'Workflow replay prepared',
+      titleKey: 'workflow.trace.replay',
+      summary: redactTraceText([
+        `Source run: ${readString(replay.sourceRunId) ?? 'unknown'}`,
+        `Scope: ${readString(replay.scope) ?? 'unknown'}`,
+        Array.isArray(replay.selectedNodeIds) ? `Selected steps: ${replay.selectedNodeIds.join(', ')}` : undefined,
+        replay.requiresApproval ? 'Replay required approval for prior shell, network, or file-write activity.' : undefined,
+      ].filter(Boolean).join('\n'), run),
+      metadata: replay,
+    });
+  }
+
+  const fallbackEvents = Array.isArray(run.metadata?.fallbackEvents)
+    ? run.metadata.fallbackEvents
+    : [];
+  fallbackEvents.forEach((event, index) => {
+    const record = readRecord(event);
+    if (!record) return;
+    pushEvent(events, {
+      id: traceId([run.id, 'fallback', index]),
+      type: 'node',
+      severity: 'warning',
+      status: 'submitted',
+      timestamp: typeof record.startedAt === 'number' ? record.startedAt : run.startedAt + 0.5 + index,
+      actor: 'Pixcode',
+      nodeId: readString(record.nodeId),
+      title: 'Fallback agent started',
+      titleKey: 'workflow.trace.fallback',
+      summary: redactTraceText([
+        `Trigger: ${readString(record.trigger) ?? 'unknown'}`,
+        `Source node: ${readString(record.nodeId) ?? 'unknown'}`,
+        `Fallback node: ${readString(record.fallbackNodeId) ?? 'unknown'}`,
+        readString(record.reason) ? `Reason: ${readString(record.reason)}` : undefined,
+      ].filter(Boolean).join('\n'), run),
+      metadata: record,
+    });
+  });
+
+  const fallbackSkippedEvents = Array.isArray(run.metadata?.fallbackSkippedEvents)
+    ? run.metadata.fallbackSkippedEvents
+    : [];
+  fallbackSkippedEvents.forEach((event, index) => {
+    const record = readRecord(event);
+    if (!record) return;
+    pushEvent(events, {
+      id: traceId([run.id, 'fallback-skipped', index]),
+      type: 'node',
+      severity: 'info',
+      status: 'skipped',
+      timestamp: typeof record.createdAt === 'number' ? record.createdAt : run.startedAt + 0.75 + index,
+      actor: 'Pixcode',
+      nodeId: readString(record.nodeId),
+      title: 'Fallback skipped',
+      titleKey: 'workflow.trace.fallback',
+      summary: redactTraceText([
+        `Trigger: ${readString(record.trigger) ?? 'unknown'}`,
+        `Skipped: ${readString(record.skippedReason) ?? 'policy did not allow fallback'}`,
+        readString(record.reason) ? `Reason: ${readString(record.reason)}` : undefined,
+      ].filter(Boolean).join('\n'), run),
+      metadata: record,
+    });
+  });
+
   run.nodeRuns.forEach((node, index) => {
     const base = eventBase(node);
     const timestamp = nodeTimestamp(run, node, index);

package/server/modules/orchestration/workflows/workflow.routes.ts

@@ -2,6 +2,10 @@ import type { Router } from 'express';
 import express from 'express';
 
 import { workflowRunner } from '@/modules/orchestration/workflows/workflow-runner.js';
+import {
+  type WorkflowReplayScope,
+  buildWorkflowReplayPlan,
+} from '@/modules/orchestration/workflows/workflow-replay.js';
 import { workflowStore } from '@/modules/orchestration/workflows/workflow-store.js';
 import { buildWorkflowTrace } from '@/modules/orchestration/workflows/workflow-trace.js';
 import { findPixcodeAppRoot } from '@/modules/orchestration/workflows/workspace-target.js';
@@ -45,6 +49,30 @@ function readRequestUserId(req: express.Request): string | number | null {
   return user?.id ?? user?.userId ?? null;
 }
 
+function readReplayScope(value: unknown): WorkflowReplayScope {
+  return value === 'run' ? 'run' : 'node';
+}
+
+function readOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readBooleanFlag(value: unknown): boolean {
+  return value === true || value === 'true' || value === '1';
+}
+
+function replayOptions(req: express.Request): {
+  scope: WorkflowReplayScope;
+  fromNodeId?: string;
+  approveReplay: boolean;
+} {
+  return {
+    scope: readReplayScope(req.body?.scope ?? req.query.scope),
+    fromNodeId: readOptionalString(req.body?.fromNodeId ?? req.query.fromNodeId),
+    approveReplay: readBooleanFlag(req.body?.approveReplay ?? req.query.approveReplay),
+  };
+}
+
 function sendRunSnapshot(res: express.Response, runId: string): boolean {
   const run = workflowStore.getRun(runId);
   if (!run) {
@@ -134,6 +162,85 @@ export function createWorkflowRouter(): Router {
     });
   });
 
+  router.get('/workflows/runs/:runId/replay-plan', (req, res) => {
+    const run = workflowStore.getRun(req.params.runId);
+    if (!run) {
+      res.status(404).json({ error: { code: 'RUN_NOT_FOUND', message: req.params.runId } });
+      return;
+    }
+
+    try {
+      const options = replayOptions(req);
+      res.json({
+        replayPlan: buildWorkflowReplayPlan(run, {
+          scope: options.scope,
+          fromNodeId: options.fromNodeId,
+        }),
+      });
+    } catch (error) {
+      res.status(400).json({
+        error: {
+          code: 'REPLAY_PLAN_INVALID',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  });
+
+  router.post('/workflows/runs/:runId/replay', (req, res) => {
+    const run = workflowStore.getRun(req.params.runId);
+    if (!run) {
+      res.status(404).json({ error: { code: 'RUN_NOT_FOUND', message: req.params.runId } });
+      return;
+    }
+
+    try {
+      const options = replayOptions(req);
+      const replayPlan = buildWorkflowReplayPlan(run, {
+        scope: options.scope,
+        fromNodeId: options.fromNodeId,
+      });
+
+      if (replayPlan.requiresApproval && !options.approveReplay) {
+        res.status(409).json({
+          error: {
+            code: 'REPLAY_APPROVAL_REQUIRED',
+            message: 'Replay requires explicit approval because prior shell, network, or file-write activity was detected.',
+          },
+          replayPlan,
+        });
+        return;
+      }
+
+      const replayRun = workflowRunner.start(
+        replayPlan.workflow,
+        replayPlan.input,
+        {
+          ...replayPlan.metadata,
+          userId: readRequestUserId(req) ?? run.metadata?.userId,
+          replay: {
+            ...(replayPlan.metadata.replay && typeof replayPlan.metadata.replay === 'object'
+              ? replayPlan.metadata.replay as Record<string, unknown>
+              : {}),
+            approved: options.approveReplay,
+            approvedAt: options.approveReplay ? Date.now() : undefined,
+          },
+        },
+      );
+      res.status(202).json({
+        run: replayRun,
+        replayPlan,
+      });
+    } catch (error) {
+      res.status(400).json({
+        error: {
+          code: 'REPLAY_START_FAILED',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  });
+
   router.get('/workflows/runs/:runId', (req, res) => {
     const run = workflowStore.getRun(req.params.runId);
     if (!run) {