@stigmer/react 3.0.9-dev.20260616060535 → 3.1.0

package/src/version-history/diff-hunks.ts

@@ -0,0 +1,63 @@
+import type { StructuredPatchHunk } from "diff";
+import type { DiffHunk, DiffLine } from "./types";
+
+/**
+ * Maps the `diff` library's structured-patch hunks into our presentation
+ * {@link DiffHunk} shape, assigning running old/new line numbers per line.
+ *
+ * This is the single source of truth for the hunk mapping, shared by
+ * {@link computeDiff} (which feeds it `structuredPatch` output computed from
+ * before/after text) and `parseUnifiedDiff` (which feeds it `parsePatch` output
+ * parsed from a unified-diff string). Both functions in the `diff` library emit
+ * the identical {@link StructuredPatchHunk} shape, so one mapper serves both and
+ * the two diff sources can never drift in how a `+`/`-`/context line becomes a
+ * {@link DiffLine}.
+ *
+ * `` markers are skipped: they are diff metadata, not
+ * content, and would otherwise be mis-rendered as a spurious context line.
+ *
+ * Pure function — no side effects, safe to call outside React.
+ */
+export function mapPatchHunks(
+  hunks: readonly StructuredPatchHunk[],
+): readonly DiffHunk[] {
+  return hunks.map((hunk) => {
+    const lines: DiffLine[] = [];
+    let oldLine = hunk.oldStart;
+    let newLine = hunk.newStart;
+
+    for (const raw of hunk.lines) {
+      // "" is a metadata marker, not a real line.
+      if (raw.startsWith("\\")) continue;
+
+      const prefix = raw[0];
+      const content = raw.slice(1);
+
+      if (prefix === "+") {
+        lines.push({ type: "added", content, newLineNumber: newLine });
+        newLine++;
+      } else if (prefix === "-") {
+        lines.push({ type: "removed", content, oldLineNumber: oldLine });
+        oldLine++;
+      } else {
+        // A context line (leading space) or an empty raw line.
+        lines.push({
+          type: "context",
+          content,
+          oldLineNumber: oldLine,
+          newLineNumber: newLine,
+        });
+        oldLine++;
+        newLine++;
+      }
+    }
+
+    return {
+      oldStart: hunk.oldStart,
+      oldLines: hunk.oldLines,
+      newStart: hunk.newStart,
+      newLines: hunk.newLines,
+      lines,
+    };
+  });
+}

package/src/version-history/index.ts

@@ -9,6 +9,7 @@ export type { DiffSummaryProps } from "./DiffSummary";
 export { MultiFileDiffView } from "./MultiFileDiffView";
 export type { MultiFileDiffViewProps } from "./MultiFileDiffView";
 export { computeDiff } from "./computeDiff";
+export { parseUnifiedDiff } from "./parseUnifiedDiff";
 export { computeMultiFileDiff } from "./computeMultiFileDiff";
 export type {
   VersionEntry,

package/src/version-history/parseUnifiedDiff.ts

@@ -0,0 +1,34 @@
+import { parsePatch } from "diff";
+import { mapPatchHunks } from "./diff-hunks";
+import type { DiffHunk } from "./types";
+
+/**
+ * Parses a unified-diff patch *string* into presentation {@link DiffHunk}s.
+ *
+ * This is the bridge that lets a harness which only emits a ready unified diff
+ * (the Cursor harness's `diffString` -> `view.unifiedDiff` / `FileChange.
+ * unifiedDiff`) render through the same accessible {@link DiffViewer} table as a
+ * computed before/after diff — instead of being dumped as a raw `<pre>` with the
+ * `--- /dev/null`, `+++ b/...`, `@@` preamble and inline `+`/`-` prefixes.
+ *
+ * The `---`/`+++` file headers parse into metadata and are discarded; only the
+ * hunks survive, mapped through the shared {@link mapPatchHunks}. A diff input is
+ * a single file's patch, but `parsePatch` can return multiple file entries, so
+ * their hunks are flattened defensively.
+ *
+ * Returns `[]` for an empty or unparseable patch, so callers can fall back to a
+ * truthful raw rendering rather than showing a misleading "No changes".
+ *
+ * Pure function — no side effects, safe to call outside React.
+ */
+export function parseUnifiedDiff(patch: string): readonly DiffHunk[] {
+  if (!patch) return [];
+
+  try {
+    return parsePatch(patch).flatMap((file) => mapPatchHunks(file.hunks));
+  } catch {
+    // parsePatch can throw on a badly malformed patch; degrade to "no hunks" so
+    // the caller renders its raw fallback instead of crashing the thread.
+    return [];
+  }
+}

package/src/workflow/WorkflowExecutionApprovalCard.tsx

@@ -1,8 +1,10 @@
 "use client";
 
-import { memo, useCallback, useState } from "react";
+import { memo, useCallback, useEffect, useState } from "react";
 import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
+import { DecisionButton } from "../internal/DecisionButton";
+import { InCardDecisionError } from "../internal/InCardDecisionError";
 
 /** Props for {@link WorkflowExecutionApprovalCard}. */
 export interface WorkflowExecutionApprovalCardProps {
@@ -20,8 +22,15 @@ export interface WorkflowExecutionApprovalCardProps {
     action: ApprovalAction,
     comment?: string,
   ) => Promise<unknown>;
-  /** `true` while a submission is in flight. */
+  /** `true` while this gate's submission is in flight. */
   readonly isSubmitting: boolean;
+  /**
+   * This gate's last failed decision, or `null`. Surfaced in-card beside the
+   * actions (via the shared {@link InCardDecisionError}) — supply
+   * {@link useWorkflowExecutionActions}'s `approvalErrorsByToolCallId` for this
+   * `toolCallId`.
+   */
+  readonly error?: Error | null;
   /** Additional CSS class names. */
   readonly className?: string;
 }
@@ -40,16 +49,26 @@ export const WorkflowExecutionApprovalCard = memo(function WorkflowExecutionAppr
   timeoutSeconds,
   onSubmitApproval,
   isSubmitting,
+  error,
   className,
 }: WorkflowExecutionApprovalCardProps) {
   const [comment, setComment] = useState("");
+  // Which action is in flight, so the spinner lands on the clicked button —
+  // matching ApprovalCard / WorkflowTaskApprovalCard. Reset once the RPC settles.
+  const [active, setActive] = useState<"approve" | "reject" | null>(null);
+
+  useEffect(() => {
+    if (!isSubmitting) setActive(null);
+  }, [isSubmitting]);
 
   // ApprovalAction enum values: 0=UNSPECIFIED, 1=APPROVE, 2=SKIP, 3=REJECT
   const handleApprove = useCallback(() => {
+    setActive("approve");
     onSubmitApproval(toolCallId, 1 as ApprovalAction, comment || undefined);
   }, [toolCallId, comment, onSubmitApproval]);
 
   const handleReject = useCallback(() => {
+    setActive("reject");
     onSubmitApproval(toolCallId, 3 as ApprovalAction, comment || undefined);
   }, [toolCallId, comment, onSubmitApproval]);
 
@@ -57,8 +76,10 @@ export const WorkflowExecutionApprovalCard = memo(function WorkflowExecutionAppr
     <div
       role="alert"
       aria-label="Approval required"
+      // Neutral card + 2px warning left accent — the quiet Cursor-grade chrome
+      // shared with ApprovalCard. (Replaces the old amber `bg-warning/5` fill.)
       className={cn(
-        "my-1 rounded-lg border border-warning/30 bg-warning/5 p-3",
+        "my-1 rounded-lg border border-border-prominent border-l-2 border-l-warning p-3",
         className,
       )}
     >
@@ -92,30 +113,34 @@ export const WorkflowExecutionApprovalCard = memo(function WorkflowExecutionAppr
       </div>
 
       <div className="mt-2 flex gap-2">
-        <button
-          type="button"
+        <DecisionButton
+          label="Approve"
+          variant="primary"
           onClick={handleApprove}
-          disabled={isSubmitting}
-          className={cn(
-            "rounded px-3 py-1 text-xs font-medium",
-            "bg-success text-success-foreground",
-            "hover:bg-success/90 disabled:pointer-events-none disabled:opacity-50",
-          )}
-        >
-          Approve
-        </button>
-        <button
-          type="button"
+          isActive={active === "approve"}
+          isSubmitting={isSubmitting}
+        />
+        <DecisionButton
+          label="Reject"
+          variant="danger"
           onClick={handleReject}
-          disabled={isSubmitting}
-          className={cn(
-            "rounded border border-destructive/30 px-3 py-1 text-xs font-medium text-destructive",
-            "hover:bg-destructive/10 disabled:pointer-events-none disabled:opacity-50",
-          )}
-        >
-          Reject
-        </button>
+          isActive={active === "reject"}
+          isSubmitting={isSubmitting}
+        />
       </div>
+
+      {/* A failed decision surfaces HERE, beside this gate's actions — not in the
+          viewer's lifecycle banner. A workflow can hold many gates at once, so a
+          failure must name the one it belongs to; the optimistic spinner has
+          already reverted, and this explains the snap-back. Shared with the
+          agent ApprovalCard / FileReviewCard via InCardDecisionError. */}
+      {error && (
+        <InCardDecisionError
+          error={error}
+          leadIn="submit decision"
+          cursorTarget="wf-approval-error"
+        />
+      )}
     </div>
   );
 });

package/src/workflow/WorkflowExecutionTimeline.tsx

@@ -23,8 +23,17 @@ export interface WorkflowExecutionTimelineProps {
     formData?: Record<string, unknown>,
     comment?: string,
   ) => Promise<unknown>;
-  /** True while a task approval submission is in flight. */
-  readonly isSubmittingApproval?: boolean;
+  /**
+   * Task names whose human_input approval is currently in flight, keyed by
+   * `taskName` so deciding one gate never spins another. Supply
+   * {@link useWorkflowExecutionActions}'s `taskApprovalSubmittingTaskNames`.
+   */
+  readonly taskApprovalSubmittingTaskNames?: ReadonlySet<string>;
+  /**
+   * Per-gate human_input approval failures, keyed by `taskName`. Supply
+   * {@link useWorkflowExecutionActions}'s `taskApprovalErrorsByTaskName`.
+   */
+  readonly taskApprovalErrorsByTaskName?: ReadonlyMap<string, Error>;
   /** Additional CSS class names. */
   readonly className?: string;
 }
@@ -47,7 +56,8 @@ export const WorkflowExecutionTimeline = memo(function WorkflowExecutionTimeline
   onNavigateToAgentExecution,
   taskStates,
   onSubmitTaskApproval,
-  isSubmittingApproval,
+  taskApprovalSubmittingTaskNames,
+  taskApprovalErrorsByTaskName,
   className,
 }: WorkflowExecutionTimelineProps) {
   const scrollRef = useRef<HTMLDivElement>(null);
@@ -112,7 +122,8 @@ export const WorkflowExecutionTimeline = memo(function WorkflowExecutionTimeline
           onNavigateToAgentExecution={onNavigateToAgentExecution}
           taskStates={taskStates}
           onSubmitTaskApproval={onSubmitTaskApproval}
-          isSubmittingApproval={isSubmittingApproval}
+          taskApprovalSubmittingTaskNames={taskApprovalSubmittingTaskNames}
+          taskApprovalErrorsByTaskName={taskApprovalErrorsByTaskName}
         />
       ))}
 

package/src/workflow/WorkflowExecutionTimelineEvent.tsx

@@ -19,7 +19,10 @@ interface TimelineEventProps {
     formData?: Record<string, unknown>,
     comment?: string,
   ) => Promise<unknown>;
-  readonly isSubmittingApproval?: boolean;
+  /** Task names whose human_input approval is in flight, keyed by `taskName`. */
+  readonly taskApprovalSubmittingTaskNames?: ReadonlySet<string>;
+  /** Per-gate human_input approval failures, keyed by `taskName`. */
+  readonly taskApprovalErrorsByTaskName?: ReadonlyMap<string, Error>;
 }
 
 /**
@@ -37,7 +40,8 @@ export const WorkflowExecutionTimelineEvent = memo(function WorkflowExecutionTim
   onNavigateToAgentExecution,
   taskStates,
   onSubmitTaskApproval,
-  isSubmittingApproval,
+  taskApprovalSubmittingTaskNames,
+  taskApprovalErrorsByTaskName,
 }: TimelineEventProps) {
   const timestamp = formatTimestamp(event.occurredAt);
   const p = event.payload;
@@ -277,7 +281,8 @@ export const WorkflowExecutionTimelineEvent = memo(function WorkflowExecutionTim
                 ? (p.value.formSchema as unknown as Record<string, unknown>)
                 : undefined}
               onSubmit={onSubmitTaskApproval}
-              isSubmitting={isSubmittingApproval ?? false}
+              isSubmitting={taskApprovalSubmittingTaskNames?.has(event.taskName) ?? false}
+              error={taskApprovalErrorsByTaskName?.get(event.taskName) ?? null}
             />
           )}
         </EventRow>

package/src/workflow/WorkflowExecutionViewer.tsx

@@ -20,7 +20,8 @@ import { ExecutionInspector } from "./execution-inspector";
 import { ExecutionComparisonPicker } from "./execution-comparison/ExecutionComparisonPicker";
 import { ExecutionComparisonView } from "./execution-comparison/ExecutionComparisonView";
 import { WorkflowExecutionApprovalCard } from "./WorkflowExecutionApprovalCard";
-import type { WorkflowPendingApproval } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowFileReviewList, type WorkflowFileDecisionSubmit } from "./WorkflowFileReviewList";
+import type { WorkflowPendingApproval, WorkflowPendingFileReview } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
 import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { ResizableSplit } from "../internal/ResizableSplit";
 
@@ -287,7 +288,9 @@ export const WorkflowExecutionViewer = memo(function WorkflowExecutionViewer({
         onClose={handleCloseComparePicker}
       />
 
-      {/* Action error banner (lifecycle actions: cancel, pause, recover, etc.) */}
+      {/* Action error banner — lifecycle actions only (cancel/terminate/pause/
+          resume/recover). Approval failures are per-gate and surface in-card on
+          the failing approval card, never here. */}
       {actions.error && (
         <div className="flex items-center gap-2 border-b border-destructive/20 bg-destructive/5 px-4 py-2">
           <p className="flex-1 text-xs text-destructive">{actions.error.message}</p>
@@ -365,9 +368,11 @@ export const WorkflowExecutionViewer = memo(function WorkflowExecutionViewer({
                     onNavigateToAgentExecution={onNavigateToAgentExecution}
                     pendingApprovals={execution?.status?.pendingApprovals}
                     onSubmitApproval={actions.submitApproval}
-                    isSubmittingApproval={actions.isSubmitting}
+                    approvalSubmittingToolCallIds={actions.approvalSubmittingToolCallIds}
+                    approvalErrorsByToolCallId={actions.approvalErrorsByToolCallId}
                     onSubmitTaskApproval={actions.submitTaskApproval}
-                    isSubmittingTaskApproval={actions.isSubmitting}
+                    taskApprovalSubmittingTaskNames={actions.taskApprovalSubmittingTaskNames}
+                    taskApprovalErrorsByTaskName={actions.taskApprovalErrorsByTaskName}
                     className="min-h-0 flex-1"
                   />
 
@@ -403,9 +408,16 @@ export const WorkflowExecutionViewer = memo(function WorkflowExecutionViewer({
           onNavigateToAgentExecution={onNavigateToAgentExecution}
           taskStates={effectiveTaskStates}
           onSubmitTaskApproval={actions.submitTaskApproval}
-          isSubmittingApproval={actions.isSubmitting}
+          taskApprovalSubmittingTaskNames={actions.taskApprovalSubmittingTaskNames}
+          taskApprovalErrorsByTaskName={actions.taskApprovalErrorsByTaskName}
           pendingApprovals={execution?.status?.pendingApprovals}
           onSubmitApproval={actions.submitApproval}
+          approvalSubmittingToolCallIds={actions.approvalSubmittingToolCallIds}
+          approvalErrorsByToolCallId={actions.approvalErrorsByToolCallId}
+          pendingFileReviews={execution?.status?.pendingFileReviews}
+          onSubmitFileDecision={actions.submitFileDecision}
+          fileDecisionSubmittingKeys={actions.fileDecisionSubmittingKeys}
+          fileDecisionErrorsByKey={actions.fileDecisionErrorsByKey}
         />
       </div>
       </>
@@ -449,9 +461,16 @@ function ExecutionBottomPanel({
   onNavigateToAgentExecution,
   taskStates,
   onSubmitTaskApproval,
-  isSubmittingApproval,
+  taskApprovalSubmittingTaskNames,
+  taskApprovalErrorsByTaskName,
   pendingApprovals,
   onSubmitApproval,
+  approvalSubmittingToolCallIds,
+  approvalErrorsByToolCallId,
+  pendingFileReviews,
+  onSubmitFileDecision,
+  fileDecisionSubmittingKeys,
+  fileDecisionErrorsByKey,
 }: {
   events: WorkflowExecutionTimelineProps["events"];
   streamState: WorkflowExecutionTimelineProps["streamState"];
@@ -462,28 +481,39 @@ function ExecutionBottomPanel({
   onNavigateToAgentExecution?: (id: string) => void;
   taskStates: ReadonlyMap<string, DerivedTaskState>;
   onSubmitTaskApproval: WorkflowExecutionTimelineProps["onSubmitTaskApproval"];
-  isSubmittingApproval: boolean;
+  taskApprovalSubmittingTaskNames: ReadonlySet<string>;
+  taskApprovalErrorsByTaskName: ReadonlyMap<string, Error>;
   pendingApprovals?: readonly WorkflowPendingApproval[];
   onSubmitApproval?: (toolCallId: string, action: ApprovalAction, comment?: string) => Promise<unknown>;
+  approvalSubmittingToolCallIds: ReadonlySet<string>;
+  approvalErrorsByToolCallId: ReadonlyMap<string, Error>;
+  pendingFileReviews?: readonly WorkflowPendingFileReview[];
+  onSubmitFileDecision: WorkflowFileDecisionSubmit;
+  fileDecisionSubmittingKeys: ReadonlySet<string>;
+  fileDecisionErrorsByKey: ReadonlyMap<string, Error>;
 }) {
   const [collapsed, setCollapsed] = useState(false);
   const [activeTab, setActiveTab] = useState<BottomTab>("waterfall");
-  const prevApprovalCountRef = useRef(0);
+  const prevHitlCountRef = useRef(0);
 
   const approvalCount = pendingApprovals?.length ?? 0;
-  const hasApprovals = approvalCount > 0;
+  const fileReviewCount = pendingFileReviews?.length ?? 0;
+  // Both HITL kinds (tool approvals + file reviews) share the one "Approvals" tab.
+  const hitlCount = approvalCount + fileReviewCount;
+  const hasHitl = hitlCount > 0;
 
-  // Auto-switch to Approvals tab when new approvals arrive
+  // Auto-switch to the Approvals tab when a new HITL gate (approval or file
+  // review) arrives; leave it when everything is resolved.
   useEffect(() => {
-    if (approvalCount > prevApprovalCountRef.current && approvalCount > 0) {
+    if (hitlCount > prevHitlCountRef.current && hitlCount > 0) {
       setActiveTab("approvals");
       setCollapsed(false);
     }
-    if (approvalCount === 0 && activeTab === "approvals") {
+    if (hitlCount === 0 && activeTab === "approvals") {
       setActiveTab("waterfall");
     }
-    prevApprovalCountRef.current = approvalCount;
-  }, [approvalCount, activeTab]);
+    prevHitlCountRef.current = hitlCount;
+  }, [hitlCount, activeTab]);
 
   return (
     <div className="border-t border-[var(--stgm-border,#e5e5e5)]">
@@ -516,9 +546,9 @@ function ExecutionBottomPanel({
           isActive={activeTab === "events"}
           onClick={() => { setActiveTab("events"); setCollapsed(false); }}
         />
-        {hasApprovals && (
+        {hasHitl && (
           <TabButton
-            label={`Approvals (${approvalCount})`}
+            label={`Approvals (${hitlCount})`}
             isActive={activeTab === "approvals"}
             onClick={() => { setActiveTab("approvals"); setCollapsed(false); }}
           />
@@ -546,24 +576,38 @@ function ExecutionBottomPanel({
               onNavigateToAgentExecution={onNavigateToAgentExecution}
               taskStates={taskStates}
               onSubmitTaskApproval={onSubmitTaskApproval}
-              isSubmittingApproval={isSubmittingApproval}
+              taskApprovalSubmittingTaskNames={taskApprovalSubmittingTaskNames}
+              taskApprovalErrorsByTaskName={taskApprovalErrorsByTaskName}
               className="h-full"
             />
           )}
-          {activeTab === "approvals" && pendingApprovals && onSubmitApproval && (
+          {activeTab === "approvals" && (
             <div className="h-full overflow-y-auto px-4 py-3">
               <div className="space-y-3">
-                {pendingApprovals.map((pa) => (
-                  <WorkflowExecutionApprovalCard
-                    key={pa.approval?.toolCallId ?? pa.childAgentExecutionId}
-                    prompt={pa.approval?.message || `Tool "${pa.approval?.toolName}" requires approval`}
-                    toolCallId={pa.approval?.toolCallId ?? ""}
-                    approvers={[]}
-                    timeoutSeconds={0}
-                    onSubmitApproval={onSubmitApproval}
-                    isSubmitting={isSubmittingApproval}
+                {pendingApprovals && onSubmitApproval && pendingApprovals.map((pa) => {
+                  const toolCallId = pa.approval?.toolCallId ?? "";
+                  return (
+                    <WorkflowExecutionApprovalCard
+                      key={toolCallId || pa.childAgentExecutionId}
+                      prompt={pa.approval?.message || `Tool "${pa.approval?.toolName}" requires approval`}
+                      toolCallId={toolCallId}
+                      approvers={[]}
+                      timeoutSeconds={0}
+                      onSubmitApproval={onSubmitApproval}
+                      isSubmitting={approvalSubmittingToolCallIds.has(toolCallId)}
+                      error={approvalErrorsByToolCallId.get(toolCallId) ?? null}
+                    />
+                  );
+                })}
+                {pendingFileReviews && pendingFileReviews.length > 0 && (
+                  <WorkflowFileReviewList
+                    pendingFileReviews={pendingFileReviews}
+                    onSubmitFileDecision={onSubmitFileDecision}
+                    submittingDecisionKeys={fileDecisionSubmittingKeys}
+                    decisionErrors={fileDecisionErrorsByKey}
+                    onNavigateToAgentExecution={onNavigateToAgentExecution}
                   />
-                ))}
+                )}
               </div>
             </div>
           )}

package/src/workflow/WorkflowFileReviewList.tsx

@@ -0,0 +1,152 @@
+"use client";
+
+import { useMemo } from "react";
+import {
+  FileChangeSetStatus,
+  type FileDecisionAction,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { WorkflowPendingFileReview } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { displayFileChangeSets } from "@stigmer/sdk";
+import { cn } from "@stigmer/theme";
+import { FileReviewCard } from "../execution/FileReviewCard";
+import type { FileDecisionOptions } from "../execution/useFileReview";
+import { useExecutionStream } from "../execution/useExecutionStream";
+
+/**
+ * Submit handler for a workflow-level file decision, matching
+ * `useWorkflowExecutionActions().submitFileDecision`. The child id is bound per
+ * card so the surface only needs the card-level `(action, options)`.
+ */
+export type WorkflowFileDecisionSubmit = (
+  childAgentExecutionId: string,
+  changeSetId: string,
+  action: FileDecisionAction,
+  options?: FileDecisionOptions,
+) => void;
+
+/** Props for {@link WorkflowFileReviewList}. */
+export interface WorkflowFileReviewListProps {
+  /**
+   * The parent workflow's surfaced file-review references
+   * (`status.pending_file_reviews`) — one entry per child agent execution.
+   */
+  readonly pendingFileReviews: readonly WorkflowPendingFileReview[];
+  /** Forwards a decision to the child (see {@link WorkflowFileDecisionSubmit}). */
+  readonly onSubmitFileDecision: WorkflowFileDecisionSubmit;
+  /** In-flight decision keys (pass `fileDecisionSubmittingKeys` straight through). */
+  readonly submittingDecisionKeys?: ReadonlySet<string>;
+  /** Per-decision failures (pass `fileDecisionErrorsByKey` straight through). */
+  readonly decisionErrors?: ReadonlyMap<string, Error>;
+  /**
+   * Optional deep-link to open the child agent execution in its own view. When
+   * provided, each child's review renders a "View agent execution" affordance.
+   * Routing is the host's responsibility (DD-004).
+   */
+  readonly onNavigateToAgentExecution?: (agentExecutionId: string) => void;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Renders the child agent file reviews surfaced on a parent WorkflowExecution.
+ *
+ * Reference-only, derive-from-child: the parent status carries only
+ * {@link WorkflowPendingFileReview} references (child id + change set ids). This
+ * list mounts one {@link WorkflowChildFileReview} per referenced child, which
+ * streams that child's execution and reuses the agent-level {@link FileReviewCard}
+ * to render the actual diff — the heavy content stays single-sourced on the child.
+ * A decision is forwarded to the child via `WorkflowExecution.submitFileDecision`.
+ *
+ * This is the file-review sibling of the workflow tool-approval surface
+ * (`WorkflowExecutionApprovalCard`). Empty `pendingFileReviews` renders nothing.
+ */
+export function WorkflowFileReviewList({
+  pendingFileReviews,
+  onSubmitFileDecision,
+  submittingDecisionKeys,
+  decisionErrors,
+  onNavigateToAgentExecution,
+  className,
+}: WorkflowFileReviewListProps): React.ReactElement | null {
+  if (pendingFileReviews.length === 0) return null;
+
+  return (
+    <div className={cn("stgm space-y-3", className)}>
+      {pendingFileReviews.map((ref) => (
+        <WorkflowChildFileReview
+          key={ref.childAgentExecutionId}
+          reference={ref}
+          onSubmitFileDecision={onSubmitFileDecision}
+          submittingDecisionKeys={submittingDecisionKeys}
+          decisionErrors={decisionErrors}
+          onNavigateToAgentExecution={onNavigateToAgentExecution}
+        />
+      ))}
+    </div>
+  );
+}
+
+interface WorkflowChildFileReviewProps {
+  readonly reference: WorkflowPendingFileReview;
+  readonly onSubmitFileDecision: WorkflowFileDecisionSubmit;
+  readonly submittingDecisionKeys?: ReadonlySet<string>;
+  readonly decisionErrors?: ReadonlyMap<string, Error>;
+  readonly onNavigateToAgentExecution?: (agentExecutionId: string) => void;
+}
+
+/**
+ * Streams a single referenced child agent execution and renders its
+ * AWAITING_REVIEW change sets (intersected with the parent's surfaced reference,
+ * so a decision always targets a gate the workflow has actually surfaced).
+ */
+function WorkflowChildFileReview({
+  reference,
+  onSubmitFileDecision,
+  submittingDecisionKeys,
+  decisionErrors,
+  onNavigateToAgentExecution,
+}: WorkflowChildFileReviewProps): React.ReactElement | null {
+  const childId = reference.childAgentExecutionId;
+  const { execution } = useExecutionStream(childId);
+
+  const changeSets = useMemo(() => {
+    const referenced = new Set(reference.changeSetId);
+    return displayFileChangeSets(execution?.status).filter(
+      (cs) =>
+        cs.status === FileChangeSetStatus.AWAITING_REVIEW &&
+        referenced.has(cs.id) &&
+        cs.changes.length > 0,
+    );
+  }, [execution?.status, reference.changeSetId]);
+
+  // Nothing to show yet (child still loading, or its projection has not caught up
+  // to the reference). The parent list already signals "review pending" for this
+  // child by virtue of the reference existing.
+  if (changeSets.length === 0) return null;
+
+  return (
+    <div className="space-y-2">
+      {onNavigateToAgentExecution && (
+        <button
+          type="button"
+          onClick={() => onNavigateToAgentExecution(childId)}
+          className="text-xs text-muted-foreground hover:text-foreground underline underline-offset-2"
+        >
+          View agent execution
+        </button>
+      )}
+      {changeSets.map((changeSet) => (
+        <FileReviewCard
+          key={changeSet.id}
+          fileChangeSet={changeSet}
+          interactive
+          submittingDecisionKeys={submittingDecisionKeys}
+          decisionErrors={decisionErrors}
+          onSubmit={(action, options) =>
+            onSubmitFileDecision(childId, changeSet.id, action, options)
+          }
+        />
+      ))}
+    </div>
+  );
+}