@stigmer/react 3.12.1 → 3.12.2

package/src/workflow/__tests__/useWorkflowExecutionPanel.test.ts

@@ -16,6 +16,7 @@ import {
 import {
   useWorkflowExecutionPanel,
   workflowArtifactTabPath,
+  type UseWorkflowExecutionPanelOptions,
 } from "../useWorkflowExecutionPanel";
 
 function artifact(id: string, displayName: string) {
@@ -238,3 +239,102 @@ describe("useWorkflowExecutionPanel openDiagnosis", () => {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// The controlled/observable open-state seam — the #651 contract mirrored from
+// useSessionPanel (#654). The panel opens ITSELF (Diagnose, artifact/change
+// opens), so onOpenChange fires in BOTH modes; controlled mode surfaces
+// requests without applying them, and a declined request stays re-fireable.
+// ---------------------------------------------------------------------------
+
+function renderSeamPanel(initial?: UseWorkflowExecutionPanelOptions) {
+  return renderHook(
+    (opts: UseWorkflowExecutionPanelOptions) => useWorkflowExecutionPanel(opts),
+    { initialProps: { ...initial } as UseWorkflowExecutionPanelOptions },
+  );
+}
+
+describe("useWorkflowExecutionPanel — observed open state (uncontrolled + onOpenChange)", () => {
+  it("reports the chip toggle without taking control", () => {
+    const seen: boolean[] = [];
+    const { result } = renderSeamPanel({ onOpenChange: (o) => seen.push(o) });
+    act(() => result.current.openPanel());
+    expect(result.current.isOpen).toBe(true);
+    act(() => result.current.closePanel());
+    expect(result.current.isOpen).toBe(false);
+    expect(seen).toEqual([true, false]);
+  });
+
+  it("reports internal open intents (openDiagnosis, openArtifact), once per actual transition", () => {
+    const seen: boolean[] = [];
+    const { result } = renderSeamPanel({ onOpenChange: (o) => seen.push(o) });
+    act(() => result.current.openDiagnosis());
+    // Already open — further open intents are not transitions.
+    act(() => result.current.openArtifact(artifact("art_1", "report.json")));
+    act(() => result.current.openPanel());
+    expect(seen).toEqual([true]);
+  });
+
+  it("starts open when defaultOpen is set, without a spurious notification", () => {
+    const seen: boolean[] = [];
+    const { result } = renderSeamPanel({
+      defaultOpen: true,
+      onOpenChange: (o) => seen.push(o),
+    });
+    expect(result.current.isOpen).toBe(true);
+    expect(seen).toEqual([]);
+  });
+});
+
+describe("useWorkflowExecutionPanel — controlled open state", () => {
+  it("follows the host's open value and ignores defaultOpen", () => {
+    const { result, rerender } = renderSeamPanel({ open: false, defaultOpen: true });
+    expect(result.current.isOpen).toBe(false);
+    rerender({ open: true, defaultOpen: true });
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("surfaces intents through onOpenChange without flipping state itself", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result, rerender } = renderSeamPanel({ open: false, onOpenChange });
+    act(() => result.current.openPanel());
+    expect(seen).toEqual([true]);
+    expect(result.current.isOpen).toBe(false);
+    // The host grants the request.
+    rerender({ open: true, onOpenChange });
+    expect(result.current.isOpen).toBe(true);
+    act(() => result.current.closePanel());
+    expect(seen).toEqual([true, false]);
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("re-fires a declined request (once per request, not per transition)", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result } = renderSeamPanel({ open: false, onOpenChange });
+    act(() => result.current.openArtifact(artifact("art_1", "a.json")));
+    // The host declined (open stayed false) — a later intent must re-fire,
+    // not be swallowed by a stale "already requested" memory.
+    act(() => result.current.openFileChange(fileChange("src/a.ts")));
+    expect(seen).toEqual([true, true]);
+  });
+
+  it("Diagnose is reported, not applied — but the tab is pinned and ready", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result } = renderSeamPanel({ open: false, onOpenChange });
+    act(() => result.current.openDiagnosis());
+    expect(seen).toEqual([true]);
+    expect(result.current.isOpen).toBe(false);
+    // Tab state stays SDK-owned: the diagnosis tab is pinned regardless, so
+    // the moment the host opens the panel the conversation greets the user.
+    expect(result.current.editorsStore.getSnapshot().editors).toEqual([
+      {
+        entryId: DIAGNOSIS_DOCUMENT_ENTRY_ID,
+        path: DIAGNOSIS_DOCUMENT_PATH,
+        preview: false,
+      },
+    ]);
+  });
+});

package/src/workflow/execution-comparison/ExecutionComparisonPicker.tsx

@@ -6,6 +6,7 @@ import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecu
 import { useWorkflowExecutionList } from "../useWorkflowExecutionList.js";
 import { WorkflowExecutionPhaseBadge } from "../WorkflowExecutionPhaseBadge.js";
 import { formatDuration } from "../format-utils.js";
+import { formatRelativeTime } from "../../activity/format-relative-time.js";
 
 /** Props for {@link ExecutionComparisonPicker}. */
 export interface ExecutionComparisonPickerProps {
@@ -119,7 +120,7 @@ export const ExecutionComparisonPicker = memo(function ExecutionComparisonPicker
       ref={dialogRef}
       className={cn(
         "stgm stg:m-auto stg:max-h-[70vh] stg:w-full stg:max-w-md stg:rounded-lg stg:border stg:border-[var(--stgm-border,#e5e5e5)] stg:bg-[var(--stgm-background,#fff)] stg:p-0 stg:shadow-xl",
-        "stg:backdrop:bg-black/40",
+        "stg:backdrop:bg-backdrop",
       )}
       onClick={handleBackdropClick}
       aria-label="Select execution to compare"
@@ -183,7 +184,7 @@ export const ExecutionComparisonPicker = memo(function ExecutionComparisonPicker
                     {name}
                   </span>
                   <span className="stg:text-[10px] stg:text-[var(--stgm-muted-foreground,#737373)]">
-                    {startedAt ? formatRelative(startedAt) : "—"}
+                    {startedAt ? formatStartedAt(startedAt) : "—"}
                     {durationMs != null && ` · ${formatDuration(durationMs)}`}
                   </span>
                 </div>
@@ -228,13 +229,8 @@ function getDurationMs(startedAt: string | undefined, completedAt: string | unde
   return e - s;
 }
 
-function formatRelative(iso: string): string {
-  const d = new Date(iso);
-  if (Number.isNaN(d.getTime())) return iso;
-  const now = Date.now();
-  const diff = now - d.getTime();
-  if (diff < 60_000) return "just now";
-  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)}m ago`;
-  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}h ago`;
-  return d.toLocaleDateString(undefined, { month: "short", day: "numeric" });
+/** ISO wire value → the shared compact stamp; unparseable renders as absent. */
+function formatStartedAt(iso: string): string {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? "—" : formatRelativeTime(date);
 }

package/src/workflow/execution-history/ExecutionHistoryTable.tsx

@@ -12,6 +12,7 @@ import {
 } from "./derive-execution-row.js";
 import { Tooltip, TooltipContent, TooltipTrigger } from "../../internal/tooltip.js";
 import { TruncatedText } from "../../internal/truncated-text.js";
+import { formatRelativeTime } from "../../activity/format-relative-time.js";
 
 // ---------------------------------------------------------------------------
 // Column definitions
@@ -436,28 +437,3 @@ function LoadingSkeleton({
     </div>
   );
 }
-
-// ---------------------------------------------------------------------------
-// Relative time formatter
-// ---------------------------------------------------------------------------
-
-function formatRelativeTime(date: Date): string {
-  const now = Date.now();
-  const diff = now - date.getTime();
-
-  if (diff < 0) return date.toLocaleString();
-  if (diff < 60_000) return "just now";
-  if (diff < 3_600_000) {
-    const mins = Math.floor(diff / 60_000);
-    return `${mins}m ago`;
-  }
-  if (diff < 86_400_000) {
-    const hours = Math.floor(diff / 3_600_000);
-    return `${hours}h ago`;
-  }
-  if (diff < 604_800_000) {
-    const days = Math.floor(diff / 86_400_000);
-    return `${days}d ago`;
-  }
-  return date.toLocaleDateString();
-}

package/src/workflow/index.ts

@@ -177,6 +177,7 @@ export {
 export {
   WorkflowExecutionViewer,
   type WorkflowExecutionViewerProps,
+  type WorkflowExecutionPanelMode,
 } from "./WorkflowExecutionViewer.js";
 
 export {

package/src/workflow/instance/CreateWorkflowInstanceDialog.tsx

@@ -115,7 +115,7 @@ export function CreateWorkflowInstanceDialog({
       onClose={handleClose}
       className={cn(
         "stg:fixed stg:inset-0 stg:m-auto stg:w-full stg:max-w-lg stg:rounded-xl stg:border stg:border-border stg:bg-popover stg:p-0 stg:shadow-xl",
-        "stg:backdrop:bg-black/50",
+        "stg:backdrop:bg-backdrop",
       )}
       aria-labelledby={titleId}
     >

package/src/workflow/instance/WorkflowInstanceDetailPanel.tsx

@@ -296,7 +296,8 @@ export function WorkflowInstanceDetailPanel({
             ) : (
               <div className="stg:space-y-2 stg:rounded-md stg:border stg:border-destructive/30 stg:p-3 stg:bg-destructive/5">
                 <p className="stg:text-xs stg:text-destructive stg:font-medium">
-                  This will permanently delete this instance and all its execution history.
+                  This permanently removes the instance and its environment bindings. Executions
+                  already run against it are preserved in the workflow&apos;s execution history.
                   This action cannot be undone.
                 </p>
                 {deleteError && (

package/src/workflow/picker/BranchAddPopover.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { memo, useState, useCallback, useRef, useEffect } from "react";
+import { memo, useState, useCallback, useId, useRef, useEffect } from "react";
 import { Popover } from "@base-ui/react/popover";
 import { cn } from "@stigmer/theme";
 import { useStigmerPortalContainer } from "../../portal-container.js";
@@ -76,6 +76,7 @@ export const BranchAddPopover = memo(function BranchAddPopover({
   side = "bottom",
   align = "start",
 }: BranchAddPopoverProps) {
+  const errorId = useId();
   const portalContainer = useStigmerPortalContainer();
   const config = MODE_CONFIG[mode];
   const nameRef = useRef<HTMLInputElement>(null);
@@ -175,11 +176,11 @@ export const BranchAddPopover = memo(function BranchAddPopover({
                       nameError ? "stg:border-[var(--stgm-destructive,#ef4444)]" : "stg:border-border",
                     )}
                     aria-invalid={!!nameError}
-                    aria-describedby={nameError ? "branch-name-error" : undefined}
+                    aria-describedby={nameError ? errorId : undefined}
                   />
                   {nameError && (
                     <p
-                      id="branch-name-error"
+                      id={errorId}
                       className="stg:mt-0.5 stg:text-[10px] stg:text-[var(--stgm-destructive,#ef4444)]"
                     >
                       {nameError}

package/src/workflow/templates/WorkflowTemplatePreview.tsx

@@ -83,7 +83,7 @@ export function WorkflowTemplatePreview({
       ref={dialogRef}
       className={cn(
         "stgm stg:m-auto stg:max-h-[85vh] stg:w-full stg:max-w-3xl stg:rounded-lg stg:border stg:border-border stg:bg-background stg:p-0 stg:shadow-lg",
-        "stg:backdrop:bg-black/50",
+        "stg:backdrop:bg-backdrop",
       )}
     >
       <div className="stg:flex stg:flex-col">

package/src/workflow/useApprovalBoundary.ts

@@ -29,7 +29,7 @@ export interface ApprovalBoundaryCrossing {
  * the decision surface (the panel's Inspect Approval tab) is never hidden
  * while the run is blocked.
  *
- * Same diffing shape as {@link useExecutionAnnouncements} (prev-map ref,
+ * Same diffing shape as `useExecutionAnnouncements` (prev-map ref,
  * diff on each map commit). A task first observed already in
  * `waiting_approval` counts as entered — with rAF-coalesced commits the
  * running→waiting transition can collapse into the task's first appearance.

package/src/workflow/useWorkflowCanvas.ts

@@ -7,6 +7,7 @@ import type {
   Edge,
   OnNodesChange,
   OnEdgesChange,
+  OnNodeDrag,
   Connection,
   IsValidConnection,
 } from "@xyflow/react";
@@ -67,6 +68,20 @@ import type { LayoutEngine } from "./layout/index.js";
 import { serializeSelection, pasteClipboard } from "./clipboard.js";
 import type { ClipboardEntry } from "./clipboard.js";
 
+/**
+ * Serializes a graph model to canonical YAML, or `null` if serialization
+ * fails. graphToYaml is total on models produced by yamlToGraph (its sort is
+ * cycle-protected and unknown kinds fall back to `unknown_N`), so `null` is
+ * a defensive outcome, not an expected one.
+ */
+function serializeGraphOrNull(model: WorkflowGraphModel): string | null {
+  try {
+    return graphToYaml(model);
+  } catch {
+    return null;
+  }
+}
+
 /** Selection state for the canvas inspector. */
 export interface CanvasSelection {
   readonly type: "node" | "edge";
@@ -90,6 +105,10 @@ export interface UseWorkflowCanvasReturn {
   readonly edges: Edge[];
   readonly onNodesChange: OnNodesChange;
   readonly onEdgesChange: OnEdgesChange;
+  /** Marks the model snapshot an in-flight drag started from. */
+  readonly onNodeDragStart: OnNodeDrag;
+  /** Records a completed node drag into the command history (oss#602). */
+  readonly onNodeDragStop: OnNodeDrag;
   readonly onConnect: (connection: Connection) => void;
   readonly isValidConnection: IsValidConnection;
   readonly onDrop: (event: React.DragEvent) => void;
@@ -175,6 +194,10 @@ export function useWorkflowCanvas(
   const [error, setError] = useState<string | null>(null);
   const [selection, setSelection] = useState<CanvasSelection | null>(null);
   const initialModelRef = useRef<WorkflowGraphModel | null>(null);
+  // Serialized form of the baseline model, kept in lockstep with
+  // initialModelRef. Dirty tracking compares serializations, not references —
+  // see the "Dirty tracking" section below for why.
+  const initialYamlRef = useRef<string | null>(null);
 
   const [nodes, setNodes, onNodesChangeRaw] = useNodesState([] as Node[]);
   const [edges, setEdges, onEdgesChangeRaw] = useEdgesState([] as Edge[]);
@@ -201,6 +224,7 @@ export function useWorkflowCanvas(
       setNodes([]);
       setEdges([]);
       initialModelRef.current = null;
+      initialYamlRef.current = null;
       return;
     }
 
@@ -209,6 +233,10 @@ export function useWorkflowCanvas(
       const laidOut = applyDagreLayout(parsed);
       history.reset(laidOut);
       initialModelRef.current = laidOut;
+      // Baseline is the canonical re-serialization, not the incoming string:
+      // dirty comparisons must be canonical-vs-canonical, immune to cosmetic
+      // formatting differences in host-provided YAML.
+      initialYamlRef.current = serializeGraphOrNull(laidOut);
       setError(null);
 
       const elements = toReactFlowElements(laidOut);
@@ -219,6 +247,7 @@ export function useWorkflowCanvas(
       setNodes([]);
       setEdges([]);
       initialModelRef.current = null;
+      initialYamlRef.current = null;
     }
   }, [yaml]);
 
@@ -252,6 +281,63 @@ export function useWorkflowCanvas(
     [onNodesChangeRaw],
   );
 
+  // During a drag, React Flow streams position changes into RF state only
+  // (via onNodesChange above); the model still holds the pre-drag
+  // positions. At drag stop, the completed gesture is recorded as ONE
+  // MoveNodesCommand — the auto-layout precedent — so drags survive
+  // later syncFromModel calls and are undoable (oss#602).
+  //
+  // The ref detects mid-drag model mutations: the keyboard undo listener
+  // and the host's YAML prop are both reachable while the mouse is down,
+  // and either one rebuilds the canvas from a model this drag never saw —
+  // recording the drag on top of that would fight the mutation.
+  const dragStartModelRef = useRef<WorkflowGraphModel | null>(null);
+
+  const onNodeDragStart: OnNodeDrag = useCallback(() => {
+    dragStartModelRef.current = history.currentModel;
+  }, [history.currentModel]);
+
+  const onNodeDragStop: OnNodeDrag = useCallback(
+    (_event, _node, draggedNodes) => {
+      const model = history.currentModel;
+      const startModel = dragStartModelRef.current;
+      dragStartModelRef.current = null;
+      if (!startModel || model !== startModel) return;
+
+      const oldPositions: { id: string; x: number; y: number }[] = [];
+      const newPositions: { id: string; x: number; y: number }[] = [];
+      for (const dragged of draggedNodes) {
+        const modelNode = model.nodes.find((n) => n.id === dragged.id);
+        if (!modelNode) continue;
+        oldPositions.push({
+          id: modelNode.id,
+          x: modelNode.position.x,
+          y: modelNode.position.y,
+        });
+        newPositions.push({
+          id: dragged.id,
+          x: dragged.position.x,
+          y: dragged.position.y,
+        });
+      }
+
+      const hasChanges = newPositions.some((np, i) => {
+        const op = oldPositions[i];
+        return Math.abs(op.x - np.x) > 0.5 || Math.abs(op.y - np.y) > 0.5;
+      });
+      if (!hasChanges) return;
+
+      // Record-only dispatch — deliberately NOT the syncing dispatch().
+      // React Flow already renders the dragged positions, so here the
+      // model catches up to the canvas (everywhere else the model leads
+      // and syncFromModel makes the canvas follow). Rebuilding the node
+      // array would be a visual no-op that wipes React Flow's `selected`
+      // flags at the end of every drag, breaking consecutive group drags.
+      history.dispatch(new MoveNodesCommand(oldPositions, newPositions));
+    },
+    [history.currentModel, history.dispatch],
+  );
+
   const onEdgesChange: OnEdgesChange = useCallback(
     (changes) => {
       onEdgesChangeRaw(changes);
@@ -387,6 +473,7 @@ export function useWorkflowCanvas(
         };
         history.reset(bootstrapModel);
         initialModelRef.current = bootstrapModel;
+        initialYamlRef.current = serializeGraphOrNull(bootstrapModel);
 
         const autoEdge = {
           id: generateEdgeId(),
@@ -1096,20 +1183,33 @@ export function useWorkflowCanvas(
   }, [history.redo, syncFromModel]);
 
   // ---------------------------------------------------------------------------
-  // Dirty tracking: model reference comparison
+  // Dirty tracking: serialization comparison (oss#609)
+  //
+  // Dirty means "saving would change the document". Node positions are not
+  // part of the serialized YAML (dagre recomputes them on every load), so a
+  // position-only edit session (drags, auto-layout) must NOT read as dirty:
+  // its save would round-trip byte-identical YAML, and because hosts reset
+  // the baseline by feeding saved YAML back through the `yaml` prop (whose
+  // re-parse effect is string-change gated), a reference-based flag could
+  // never clear afterwards — an armed Save button that saving cannot disarm.
+  // graphToYaml is total on parsed models (cycle-protected sort, unknown-kind
+  // fallback) and O(nodes+edges), cheap enough to compare per model change.
   // ---------------------------------------------------------------------------
 
   const graph = history.currentModel.nodes.length > 0 ? history.currentModel : null;
-  const isDirty = initialModelRef.current !== null && graph !== initialModelRef.current;
+  const currentYaml = useMemo(
+    () => (graph ? serializeGraphOrNull(graph) : null),
+    [graph],
+  );
+  // Reference comparison remains as the fallback for the defensive case where
+  // serialization failed (null); failing dirty-side keeps Save reachable.
+  const isDirty =
+    initialModelRef.current !== null &&
+    (currentYaml !== null && initialYamlRef.current !== null
+      ? currentYaml !== initialYamlRef.current
+      : graph !== initialModelRef.current);
 
-  const serializeToYaml = useCallback((): string | null => {
-    if (!graph) return null;
-    try {
-      return graphToYaml(graph);
-    } catch {
-      return null;
-    }
-  }, [graph]);
+  const serializeToYaml = useCallback((): string | null => currentYaml, [currentYaml]);
 
   return useMemo(
     () => ({
@@ -1117,6 +1217,8 @@ export function useWorkflowCanvas(
       edges,
       onNodesChange,
       onEdgesChange,
+      onNodeDragStart,
+      onNodeDragStop,
       onConnect,
       isValidConnection,
       onDrop,
@@ -1174,7 +1276,8 @@ export function useWorkflowCanvas(
       getSelectedNodeIds,
     }),
     [
-      nodes, edges, onNodesChange, onEdgesChange, onConnect,
+      nodes, edges, onNodesChange, onEdgesChange, onNodeDragStart,
+      onNodeDragStop, onConnect,
       isValidConnection, onDrop, onDragOver, onNodesDelete, onEdgesDelete,
       selection, selectNode, selectEdge, clearSelection, autoLayout,
       undo, redo, history.canUndo, history.canRedo, isDirty, graph, error,

package/src/workflow/useWorkflowExecutionPanel.ts

@@ -3,7 +3,7 @@
 // State + actions for the workflow execution viewer's WorkspaceSurface panel.
 // Domain: workflow (the lean analog of session/useSessionPanel).
 
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import type { Artifact } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
 import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import {
@@ -50,7 +50,11 @@ export function workflowArtifactTabPath(artifact: Artifact): string {
 export interface WorkflowExecutionPanelController {
   /** The open-editor group store; subscribe with `useWorkspaceEditors`. */
   readonly editorsStore: WorkspaceEditorsStore;
-  /** Whether the panel is expanded or collapsed to the chip. */
+  /**
+   * Whether the panel is expanded or collapsed to the chip. In controlled
+   * mode ({@link UseWorkflowExecutionPanelOptions.open}) this mirrors the
+   * host's value.
+   */
   readonly isOpen: boolean;
   /** The active rail view id (an injected facet — `"artifacts"` today). */
   readonly view: string;
@@ -119,6 +123,38 @@ export interface UseWorkflowExecutionPanelOptions {
    * @default "artifacts"
    */
   readonly defaultView?: string;
+  /**
+   * Controlled open state. When provided, the host owns whether the panel is
+   * expanded: internal open intents (the chip toggle, Diagnose, an
+   * artifact/file-change/file open) no longer flip state themselves — they
+   * surface through {@link UseWorkflowExecutionPanelOptions.onOpenChange}
+   * and the panel follows this value. Leave `undefined` for the
+   * self-managing default. The same seam `useSessionPanel` carries (#651);
+   * kept domain-local, like the controllers themselves.
+   */
+  readonly open?: boolean;
+  /**
+   * Initial open state in uncontrolled mode. Ignored when
+   * {@link UseWorkflowExecutionPanelOptions.open} is provided.
+   *
+   * @default false
+   */
+  readonly defaultOpen?: boolean;
+  /**
+   * Called on every effective open/close transition — in BOTH modes,
+   * matching `useSessionPanel`'s convention (and departing from
+   * `useDetailTabs`'s DD-T05A-001 for the same principled reason): this
+   * panel opens ITSELF (`openDiagnosis`, `openArtifact`, `openFileChange`,
+   * `openFile` all expand a collapsed panel), and an embedding host that
+   * must react to those moments — widen a dock, make room for a diagnosis
+   * conversation — has no other seam. Passing only this callback observes
+   * the panel without controlling it.
+   *
+   * In controlled mode this fires once per open/close REQUEST (the host may
+   * decline by not updating `open` — a later identical request re-fires); in
+   * uncontrolled mode it fires once per actual transition.
+   */
+  readonly onOpenChange?: (open: boolean) => void;
 }
 
 /**
@@ -126,13 +162,59 @@ export interface UseWorkflowExecutionPanelOptions {
  */
 export function useWorkflowExecutionPanel({
   defaultView = "artifacts",
+  open,
+  defaultOpen = false,
+  onOpenChange,
 }: UseWorkflowExecutionPanelOptions = {}): WorkflowExecutionPanelController {
   const editorsStore = useWorkspaceEditorsStoreRef();
-  const [isOpen, setIsOpen] = useState(false);
+
+  // Uncontrolled-by-default / controlled-when-`open`-is-provided (React's own
+  // value/defaultValue convention — presence of the value prop decides, so an
+  // observe-only host can pass just `onOpenChange`). Same shape as
+  // `useSessionPanel`; re-transcribed rather than extracted because the
+  // controllers are deliberately not shared (see the interface doc above).
+  const isControlled = open !== undefined;
+  const [internalIsOpen, setInternalIsOpen] = useState(defaultOpen);
+  const isOpen = isControlled ? open : internalIsOpen;
+
+  // Latest-ref idiom: the host's callback and the mode/value mirrors live in
+  // refs so `requestOpenChange` — and every action callback built on it —
+  // stays referentially stable regardless of how the host authored
+  // `onOpenChange` (DD-010: an inline lambda must not churn the memoized
+  // controller and re-render the panel subtree).
+  const onOpenChangeRef = useRef(onOpenChange);
+  onOpenChangeRef.current = onOpenChange;
+  const isControlledRef = useRef(isControlled);
+  isControlledRef.current = isControlled;
+  const isOpenRef = useRef(isOpen);
+  isOpenRef.current = isOpen;
+
+  // The single seam every open/close intent routes through — the chip
+  // toggle, Diagnose, artifact/file-change/file opens, and the surface's
+  // collapse affordance. Uncontrolled: apply + notify (the ref is updated
+  // eagerly so two same-tick intents produce one notification). Controlled:
+  // notify only — the host owns the state, and the panel follows the `open`
+  // prop; the ref is NOT updated, so a declined request stays re-fireable.
+  const requestOpenChange = useCallback((next: boolean) => {
+    if (isOpenRef.current === next) return;
+    if (!isControlledRef.current) {
+      isOpenRef.current = next;
+      setInternalIsOpen(next);
+    }
+    onOpenChangeRef.current?.(next);
+  }, []);
+
   const [view, setViewState] = useState(defaultView);
 
-  const openPanel = useCallback(() => setIsOpen(true), []);
-  const closePanel = useCallback(() => setIsOpen(false), []);
+  const openPanel = useCallback(
+    () => requestOpenChange(true),
+    [requestOpenChange],
+  );
+
+  const closePanel = useCallback(
+    () => requestOpenChange(false),
+    [requestOpenChange],
+  );
 
   const setView = useCallback((viewId: string) => setViewState(viewId), []);
 
@@ -141,15 +223,15 @@ export function useWorkflowExecutionPanel({
       DIAGNOSIS_DOCUMENT_ENTRY_ID,
       DIAGNOSIS_DOCUMENT_PATH,
     );
-    setIsOpen(true);
-  }, [editorsStore]);
+    requestOpenChange(true);
+  }, [editorsStore, requestOpenChange]);
 
   const openFile = useCallback(
     (entryId: string, path: string, options?: OpenFileOptions) => {
       editorsStore.openPreview(entryId, path, options);
-      setIsOpen(true);
+      requestOpenChange(true);
     },
-    [editorsStore],
+    [editorsStore, requestOpenChange],
   );
 
   const openArtifact = useCallback(
@@ -158,9 +240,9 @@ export function useWorkflowExecutionPanel({
         ARTIFACT_DOCUMENT_ENTRY_ID,
         workflowArtifactTabPath(artifact),
       );
-      setIsOpen(true);
+      requestOpenChange(true);
     },
-    [editorsStore],
+    [editorsStore, requestOpenChange],
   );
 
   const pinArtifact = useCallback(
@@ -179,9 +261,9 @@ export function useWorkflowExecutionPanel({
         FILE_CHANGE_DOCUMENT_ENTRY_ID,
         fileChangeTabPath(change),
       );
-      setIsOpen(true);
+      requestOpenChange(true);
     },
-    [editorsStore],
+    [editorsStore, requestOpenChange],
   );
 
   const pinFileChange = useCallback(