@stigmer/react 3.0.9-dev.20260615153829 → 3.1.0

package/src/workflow/__tests__/WorkflowExecutionApprovalCard.test.tsx

@@ -0,0 +1,129 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import { WorkflowExecutionApprovalCard } from "../WorkflowExecutionApprovalCard";
+
+// ApprovalAction enum: 1 = APPROVE, 3 = REJECT.
+const APPROVE = 1;
+const REJECT = 3;
+
+const defaultProps = {
+  prompt: "The agent wants to delete /tmp/x. Approve?",
+  toolCallId: "tc-1",
+  approvers: [] as readonly string[],
+  timeoutSeconds: 0,
+  onSubmitApproval: vi.fn().mockResolvedValue(undefined),
+  isSubmitting: false,
+};
+
+afterEach(cleanup);
+
+describe("WorkflowExecutionApprovalCard", () => {
+  describe("content", () => {
+    it("renders the prompt", () => {
+      render(<WorkflowExecutionApprovalCard {...defaultProps} />);
+      expect(screen.getByText(defaultProps.prompt)).toBeTruthy();
+    });
+
+    it("lists approvers and the timeout when provided", () => {
+      render(
+        <WorkflowExecutionApprovalCard
+          {...defaultProps}
+          approvers={["alice", "bob"]}
+          timeoutSeconds={120}
+        />,
+      );
+      expect(screen.getByText("Approvers: alice, bob")).toBeTruthy();
+      expect(screen.getByText("Expires in 2m")).toBeTruthy();
+    });
+  });
+
+  describe("submission", () => {
+    it("submits APPROVE with the comment", () => {
+      const onSubmitApproval = vi.fn().mockResolvedValue(undefined);
+      render(
+        <WorkflowExecutionApprovalCard {...defaultProps} onSubmitApproval={onSubmitApproval} />,
+      );
+      fireEvent.change(screen.getByPlaceholderText("Comment (optional)"), {
+        target: { value: "ok" },
+      });
+      fireEvent.click(screen.getByRole("button", { name: "Approve" }));
+      expect(onSubmitApproval).toHaveBeenCalledWith("tc-1", APPROVE, "ok");
+    });
+
+    it("submits REJECT with no comment as undefined", () => {
+      const onSubmitApproval = vi.fn().mockResolvedValue(undefined);
+      render(
+        <WorkflowExecutionApprovalCard {...defaultProps} onSubmitApproval={onSubmitApproval} />,
+      );
+      fireEvent.click(screen.getByRole("button", { name: "Reject" }));
+      expect(onSubmitApproval).toHaveBeenCalledWith("tc-1", REJECT, undefined);
+    });
+  });
+
+  describe("quiet chrome & buttons (shared DecisionButton)", () => {
+    it("uses neutral card chrome + warning accent, never the old amber fill", () => {
+      render(<WorkflowExecutionApprovalCard {...defaultProps} />);
+      const card = screen.getByRole("alert");
+      expect(card.className).toContain("border-border-prominent");
+      expect(card.className).toContain("border-l-warning");
+      expect(card.className).not.toContain("bg-warning");
+    });
+
+    it("Approve is the neutral chip (not loud green); Reject is a quiet danger ghost (not a red fill)", () => {
+      render(<WorkflowExecutionApprovalCard {...defaultProps} />);
+      const approve = screen.getByRole("button", { name: "Approve" });
+      expect(approve.className).toContain("bg-accent");
+      expect(approve.className).not.toContain("bg-success");
+
+      const reject = screen.getByRole("button", { name: "Reject" });
+      expect(reject.className).toContain("hover:text-destructive");
+      expect(reject.className).not.toContain("bg-destructive text-destructive-foreground");
+      // No opacity-modifier debt (e.g. the old hover:bg-destructive/10).
+      expect(reject.className).not.toMatch(/\/\d+(?:\s|$)/);
+    });
+  });
+
+  describe("loading state", () => {
+    it("disables both buttons while submitting", () => {
+      render(<WorkflowExecutionApprovalCard {...defaultProps} isSubmitting />);
+      expect(
+        (screen.getByRole("button", { name: "Approve" }) as HTMLButtonElement).disabled,
+      ).toBe(true);
+      expect(
+        (screen.getByRole("button", { name: "Reject" }) as HTMLButtonElement).disabled,
+      ).toBe(true);
+    });
+
+    it("shows the spinner on the clicked button during submission", () => {
+      const { rerender } = render(<WorkflowExecutionApprovalCard {...defaultProps} />);
+      fireEvent.click(screen.getByRole("button", { name: "Reject" }));
+      rerender(<WorkflowExecutionApprovalCard {...defaultProps} isSubmitting />);
+
+      expect(
+        screen.getByRole("button", { name: "Reject" }).querySelector(".animate-spin"),
+      ).toBeTruthy();
+      expect(
+        screen.getByRole("button", { name: "Approve" }).querySelector(".animate-spin"),
+      ).toBeNull();
+    });
+  });
+
+  describe("in-card decision error", () => {
+    it("renders the failure notice beside the actions when error is set", () => {
+      render(
+        <WorkflowExecutionApprovalCard
+          {...defaultProps}
+          error={new Error("gate already resolved")}
+        />,
+      );
+      expect(
+        screen.getByText(/Couldn.t submit decision — gate already resolved/),
+      ).toBeTruthy();
+    });
+
+    it("renders no failure notice when error is null", () => {
+      render(<WorkflowExecutionApprovalCard {...defaultProps} error={null} />);
+      expect(screen.queryByText(/Couldn.t submit decision/)).toBeNull();
+    });
+  });
+});

package/src/workflow/__tests__/WorkflowFileReviewList.test.tsx

@@ -0,0 +1,129 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import { FileChangeSetStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+// Mock the child execution stream: each child id maps to a canned execution.
+const mockExecutions: Record<string, any> = {};
+vi.mock("../../execution/useExecutionStream", () => ({
+  useExecutionStream: (id: string | null) => ({
+    execution: id ? (mockExecutions[id] ?? null) : null,
+  }),
+}));
+
+// Stub FileReviewCard to a minimal control that surfaces its wiring, so the test
+// exercises the container's mapping/forwarding — not the card's diff rendering.
+vi.mock("../../execution/FileReviewCard", () => ({
+  FileReviewCard: (props: any) => (
+    <button
+      data-testid={`card-${props.fileChangeSet.id}`}
+      onClick={() => props.onSubmit(1 /* APPROVE */, { expectedDigest: "d" })}
+    >
+      review {props.fileChangeSet.id}
+    </button>
+  ),
+}));
+
+import { WorkflowFileReviewList } from "../WorkflowFileReviewList";
+
+function awaitingSet(id: string) {
+  return { id, status: FileChangeSetStatus.AWAITING_REVIEW, changes: [{ id: "fc" }] };
+}
+
+beforeEach(() => {
+  for (const k of Object.keys(mockExecutions)) delete mockExecutions[k];
+});
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("WorkflowFileReviewList", () => {
+  it("renders nothing when there are no references", () => {
+    const { container } = render(
+      <WorkflowFileReviewList pendingFileReviews={[]} onSubmitFileDecision={vi.fn()} />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("renders a card for a referenced AWAITING_REVIEW set and forwards the decision with child routing", () => {
+    mockExecutions["aex-1"] = { status: { fileChangeSets: [awaitingSet("fcs-1")] } };
+    const onSubmit = vi.fn();
+
+    render(
+      <WorkflowFileReviewList
+        pendingFileReviews={[{ childAgentExecutionId: "aex-1", changeSetId: ["fcs-1"] } as any]}
+        onSubmitFileDecision={onSubmit}
+      />,
+    );
+
+    const card = screen.getByTestId("card-fcs-1");
+    fireEvent.click(card);
+    expect(onSubmit).toHaveBeenCalledWith("aex-1", "fcs-1", 1, { expectedDigest: "d" });
+  });
+
+  it("does not render a set that is not in the surfaced reference", () => {
+    // Child has an AWAITING set fcs-2, but the parent only surfaced fcs-1.
+    mockExecutions["aex-1"] = {
+      status: { fileChangeSets: [awaitingSet("fcs-1"), awaitingSet("fcs-2")] },
+    };
+
+    render(
+      <WorkflowFileReviewList
+        pendingFileReviews={[{ childAgentExecutionId: "aex-1", changeSetId: ["fcs-1"] } as any]}
+        onSubmitFileDecision={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByTestId("card-fcs-1")).toBeTruthy();
+    expect(screen.queryByTestId("card-fcs-2")).toBeNull();
+  });
+
+  it("does not render a referenced set that is no longer AWAITING_REVIEW", () => {
+    mockExecutions["aex-1"] = {
+      status: { fileChangeSets: [{ id: "fcs-1", status: FileChangeSetStatus.DECIDED, changes: [{ id: "fc" }] }] },
+    };
+
+    render(
+      <WorkflowFileReviewList
+        pendingFileReviews={[{ childAgentExecutionId: "aex-1", changeSetId: ["fcs-1"] } as any]}
+        onSubmitFileDecision={vi.fn()}
+      />,
+    );
+
+    expect(screen.queryByTestId("card-fcs-1")).toBeNull();
+  });
+
+  it("renders reviews for multiple parallel children independently", () => {
+    mockExecutions["aex-1"] = { status: { fileChangeSets: [awaitingSet("fcs-1")] } };
+    mockExecutions["aex-2"] = { status: { fileChangeSets: [awaitingSet("fcs-2")] } };
+
+    render(
+      <WorkflowFileReviewList
+        pendingFileReviews={[
+          { childAgentExecutionId: "aex-1", changeSetId: ["fcs-1"] } as any,
+          { childAgentExecutionId: "aex-2", changeSetId: ["fcs-2"] } as any,
+        ]}
+        onSubmitFileDecision={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByTestId("card-fcs-1")).toBeTruthy();
+    expect(screen.getByTestId("card-fcs-2")).toBeTruthy();
+  });
+
+  it("shows a deep-link affordance when onNavigateToAgentExecution is provided", () => {
+    mockExecutions["aex-1"] = { status: { fileChangeSets: [awaitingSet("fcs-1")] } };
+    const onNavigate = vi.fn();
+
+    render(
+      <WorkflowFileReviewList
+        pendingFileReviews={[{ childAgentExecutionId: "aex-1", changeSetId: ["fcs-1"] } as any]}
+        onSubmitFileDecision={vi.fn()}
+        onNavigateToAgentExecution={onNavigate}
+      />,
+    );
+
+    fireEvent.click(screen.getByText("View agent execution"));
+    expect(onNavigate).toHaveBeenCalledWith("aex-1");
+  });
+});

package/src/workflow/__tests__/WorkflowTaskApprovalCard.test.tsx

@@ -37,14 +37,19 @@ describe("WorkflowTaskApprovalCard", () => {
     });
   });
 
-  describe("button variants", () => {
-    it("first outcome gets primary variant (success colors)", () => {
+  // The buttons now share the quiet, token-only DecisionButton primitive:
+  // first outcome = neutral chip (`primary`), reject/deny or the trailing of two
+  // = ghost-`danger`, middle outcomes = neutral `ghost`. No loud success/destructive
+  // fills, and no `bg-token/NN` opacity modifiers.
+  describe("button variants (quiet hierarchy)", () => {
+    it("first outcome is the neutral chip (primary), never the loud success green", () => {
       render(<WorkflowTaskApprovalCard {...defaultProps} />);
       const btn = screen.getByRole("button", { name: "Approve" });
-      expect(btn.className).toContain("bg-success");
+      expect(btn.className).toContain("bg-accent");
+      expect(btn.className).not.toContain("bg-success");
     });
 
-    it('outcome named "reject" gets destructive variant', () => {
+    it('outcome named "reject" is a quiet danger ghost (no red fill)', () => {
       const outcomes: TaskOutcome[] = [
         { name: "approve", label: "Approve" },
         { name: "reject", label: "Reject" },
@@ -52,10 +57,11 @@ describe("WorkflowTaskApprovalCard", () => {
       ];
       render(<WorkflowTaskApprovalCard {...defaultProps} outcomes={outcomes} />);
       const btn = screen.getByRole("button", { name: "Reject" });
-      expect(btn.className).toContain("bg-destructive");
+      expect(btn.className).toContain("hover:text-destructive");
+      expect(btn.className).not.toContain("bg-destructive text-destructive-foreground");
     });
 
-    it('outcome named "deny" gets destructive variant', () => {
+    it('outcome named "deny" is a quiet danger ghost (no red fill)', () => {
       const outcomes: TaskOutcome[] = [
         { name: "approve", label: "Approve" },
         { name: "deny", label: "Deny" },
@@ -63,20 +69,21 @@ describe("WorkflowTaskApprovalCard", () => {
       ];
       render(<WorkflowTaskApprovalCard {...defaultProps} outcomes={outcomes} />);
       const btn = screen.getByRole("button", { name: "Deny" });
-      expect(btn.className).toContain("bg-destructive");
+      expect(btn.className).toContain("hover:text-destructive");
+      expect(btn.className).not.toContain("bg-destructive text-destructive-foreground");
     });
 
-    it("second of two outcomes gets destructive variant (binary fallback)", () => {
+    it("second of two outcomes is the danger ghost (binary fallback)", () => {
       const outcomes: TaskOutcome[] = [
         { name: "accept", label: "Accept" },
         { name: "decline", label: "Decline" },
       ];
       render(<WorkflowTaskApprovalCard {...defaultProps} outcomes={outcomes} />);
       const btn = screen.getByRole("button", { name: "Decline" });
-      expect(btn.className).toContain("bg-destructive");
+      expect(btn.className).toContain("hover:text-destructive");
     });
 
-    it("middle outcomes in 3+ get secondary variant", () => {
+    it("middle outcomes in 3+ are neutral ghosts (no resting fill)", () => {
       const outcomes: TaskOutcome[] = [
         { name: "approve", label: "Approve" },
         { name: "defer", label: "Defer" },
@@ -84,7 +91,16 @@ describe("WorkflowTaskApprovalCard", () => {
       ];
       render(<WorkflowTaskApprovalCard {...defaultProps} outcomes={outcomes} />);
       const btn = screen.getByRole("button", { name: "Defer" });
-      expect(btn.className).toContain("bg-background");
+      expect(btn.className).toContain("text-muted-foreground");
+      expect(btn.className).not.toMatch(/(?:^|\s)bg-/);
+    });
+
+    it("the card uses neutral chrome + warning accent, never the old amber fill", () => {
+      render(<WorkflowTaskApprovalCard {...defaultProps} />);
+      const card = screen.getByRole("form");
+      expect(card.className).toContain("border-border-prominent");
+      expect(card.className).toContain("border-l-warning");
+      expect(card.className).not.toContain("bg-warning");
     });
   });
 
@@ -232,6 +248,22 @@ describe("WorkflowTaskApprovalCard", () => {
     });
   });
 
+  describe("in-card decision error", () => {
+    it("renders the failure notice beside the outcomes when error is set", () => {
+      render(
+        <WorkflowTaskApprovalCard {...defaultProps} error={new Error("signal failed")} />,
+      );
+      expect(
+        screen.getByText(/Couldn.t submit decision — signal failed/),
+      ).toBeTruthy();
+    });
+
+    it("renders no failure notice when error is null", () => {
+      render(<WorkflowTaskApprovalCard {...defaultProps} error={null} />);
+      expect(screen.queryByText(/Couldn.t submit decision/)).toBeNull();
+    });
+  });
+
   describe("accessibility", () => {
     it('root element has role="form"', () => {
       render(<WorkflowTaskApprovalCard {...defaultProps} />);

package/src/workflow/__tests__/useWorkflowExecutionActions.test.tsx

@@ -23,6 +23,7 @@ const mockResume = vi.fn();
 const mockRecover = vi.fn();
 const mockSubmitApproval = vi.fn();
 const mockSubmitWorkflowTaskApproval = vi.fn();
+const mockSubmitFileDecision = vi.fn();
 
 function makeMockClient(): Stigmer {
   return {
@@ -34,6 +35,7 @@ function makeMockClient(): Stigmer {
       recover: mockRecover,
       submitApproval: mockSubmitApproval,
       submitWorkflowTaskApproval: mockSubmitWorkflowTaskApproval,
+      submitFileDecision: mockSubmitFileDecision,
     },
   } as unknown as Stigmer;
 }
@@ -278,3 +280,277 @@ describe("onSuccess callback", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Per-gate approval state (keyed; separate from the lifecycle scalar)
+// ---------------------------------------------------------------------------
+
+describe("per-gate approval state", () => {
+  it("tracks an in-flight tool approval keyed by toolCallId, not the lifecycle scalar", async () => {
+    let resolve!: (v: unknown) => void;
+    mockSubmitApproval.mockReturnValueOnce(new Promise((r) => (resolve = r)));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let pending: Promise<unknown>;
+    act(() => {
+      pending = result.current.submitApproval("tc-1", 1 as any);
+    });
+
+    expect(result.current.approvalSubmittingToolCallIds.has("tc-1")).toBe(true);
+    // The lifecycle scalar is untouched by an approval.
+    expect(result.current.isSubmitting).toBe(false);
+
+    await act(async () => {
+      resolve(makeExecution());
+      await pending;
+    });
+
+    expect(result.current.approvalSubmittingToolCallIds.size).toBe(0);
+  });
+
+  it("records a failed tool approval in the keyed map, not the lifecycle scalar, and resolves null", async () => {
+    mockSubmitApproval.mockRejectedValueOnce(new Error("gate already resolved"));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.submitApproval("tc-1", 1 as any);
+    });
+
+    expect(returned).toBeNull();
+    expect(result.current.approvalErrorsByToolCallId.get("tc-1")?.message).toBe(
+      "gate already resolved",
+    );
+    // The lifecycle scalar (header banner) must NOT pick up an approval failure.
+    expect(result.current.error).toBeNull();
+    expect(result.current.isSubmitting).toBe(false);
+  });
+
+  it("records a failed task approval keyed by taskName, not the lifecycle scalar", async () => {
+    mockSubmitWorkflowTaskApproval.mockRejectedValueOnce(new Error("signal failed"));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.submitTaskApproval("review_task", "approved");
+    });
+
+    expect(returned).toBeNull();
+    expect(result.current.taskApprovalErrorsByTaskName.get("review_task")?.message).toBe(
+      "signal failed",
+    );
+    expect(result.current.error).toBeNull();
+  });
+
+  it("keeps tool and task approval errors in separate keyed spaces", async () => {
+    mockSubmitApproval.mockRejectedValueOnce(new Error("tool fail"));
+    mockSubmitWorkflowTaskApproval.mockRejectedValueOnce(new Error("task fail"));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.submitApproval("tc-1", 1 as any);
+    });
+    await act(async () => {
+      await result.current.submitTaskApproval("review_task", "approved");
+    });
+
+    expect(result.current.approvalErrorsByToolCallId.get("tc-1")?.message).toBe("tool fail");
+    expect(result.current.taskApprovalErrorsByTaskName.get("review_task")?.message).toBe("task fail");
+    // Neither keyed failure crosses into the other space or the scalar.
+    expect(result.current.approvalErrorsByToolCallId.has("review_task")).toBe(false);
+    expect(result.current.taskApprovalErrorsByTaskName.has("tc-1")).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("keeps a failed lifecycle action in the scalar, never in the keyed approval maps", async () => {
+    mockCancel.mockRejectedValueOnce(new Error("temporal down"));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.cancel();
+    });
+
+    expect(result.current.error?.message).toBe("temporal down");
+    expect(result.current.approvalErrorsByToolCallId.size).toBe(0);
+    expect(result.current.taskApprovalErrorsByTaskName.size).toBe(0);
+  });
+
+  it("null executionId returns null without recording keyed state", async () => {
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions(null),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.submitApproval("tc-1", 1 as any);
+    });
+
+    expect(returned).toBeNull();
+    expect(mockSubmitApproval).not.toHaveBeenCalled();
+    expect(result.current.approvalSubmittingToolCallIds.size).toBe(0);
+    expect(result.current.approvalErrorsByToolCallId.size).toBe(0);
+  });
+
+  it("keeps a stable return reference across renders when nothing changes", () => {
+    const { result, rerender } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Per-gate file-decision state (forwarding + keyed like FileReviewCard)
+// ---------------------------------------------------------------------------
+
+describe("submitFileDecision (workflow-parent file review)", () => {
+  it("forwards a CHANGE_SET decision with explicit child routing", async () => {
+    mockSubmitFileDecision.mockResolvedValueOnce(makeExecution());
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.submitFileDecision("aex-child", "fcs-1", 1 /* APPROVE */ as any, {
+        expectedDigest: "sha256:agg",
+      });
+    });
+
+    expect(mockSubmitFileDecision).toHaveBeenCalledTimes(1);
+    const input = mockSubmitFileDecision.mock.calls[0][0];
+    expect(input.executionId).toBe("wex-001");
+    expect(input.childAgentExecutionId).toBe("aex-child");
+    expect(input.changeSetId).toBe("fcs-1");
+    expect(input.scope).toBe(1 /* CHANGE_SET */);
+    expect(input.fileChangeId).toBe("");
+    expect(input.action).toBe(1 /* APPROVE */);
+    expect(input.expectedDigest).toBe("sha256:agg");
+  });
+
+  it("derives FILE scope when a fileChangeId is supplied", async () => {
+    mockSubmitFileDecision.mockResolvedValueOnce(makeExecution());
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.submitFileDecision("aex-child", "fcs-1", 2 /* REJECT */ as any, {
+        fileChangeId: "fc-9",
+        expectedDigest: "sha256:file",
+      });
+    });
+
+    const input = mockSubmitFileDecision.mock.calls[0][0];
+    expect(input.scope).toBe(2 /* FILE */);
+    expect(input.fileChangeId).toBe("fc-9");
+    expect(input.action).toBe(2 /* REJECT */);
+  });
+
+  it("tracks in-flight state keyed like FileReviewCard (changeSetId, then changeSetId:fileChangeId)", async () => {
+    let resolve!: (v: unknown) => void;
+    mockSubmitFileDecision.mockReturnValueOnce(new Promise((r) => (resolve = r)));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let pending: Promise<unknown>;
+    act(() => {
+      pending = result.current.submitFileDecision("aex-child", "fcs-1", 1 as any);
+    });
+
+    expect(result.current.fileDecisionSubmittingKeys.has("fcs-1")).toBe(true);
+    expect(result.current.isSubmitting).toBe(false); // lifecycle scalar untouched
+
+    await act(async () => {
+      resolve(makeExecution());
+      await pending;
+    });
+
+    expect(result.current.fileDecisionSubmittingKeys.size).toBe(0);
+  });
+
+  it("records a failed decision in the keyed map (not the scalar) and resolves null", async () => {
+    mockSubmitFileDecision.mockRejectedValueOnce(new Error("expected_digest mismatch"));
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001"),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.submitFileDecision("aex-child", "fcs-1", 1 as any, {
+        fileChangeId: "fc-9",
+      });
+    });
+
+    expect(returned).toBeNull();
+    expect(result.current.fileDecisionErrorsByKey.get("fcs-1:fc-9")?.message).toBe(
+      "expected_digest mismatch",
+    );
+    expect(result.current.error).toBeNull(); // header banner unaffected
+  });
+
+  it("does not fire onSuccess", async () => {
+    mockSubmitFileDecision.mockResolvedValueOnce(makeExecution());
+    const onSuccess = vi.fn();
+
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions("wex-001", { onSuccess }),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    await act(async () => {
+      await result.current.submitFileDecision("aex-child", "fcs-1", 1 as any);
+    });
+
+    expect(onSuccess).not.toHaveBeenCalled();
+  });
+
+  it("null executionId returns null without calling the SDK", async () => {
+    const { result } = renderHook(
+      () => useWorkflowExecutionActions(null),
+      { wrapper: createWrapper(makeMockClient()) },
+    );
+
+    let returned: any;
+    await act(async () => {
+      returned = await result.current.submitFileDecision("aex-child", "fcs-1", 1 as any);
+    });
+
+    expect(returned).toBeNull();
+    expect(mockSubmitFileDecision).not.toHaveBeenCalled();
+    expect(result.current.fileDecisionSubmittingKeys.size).toBe(0);
+  });
+});