@stigmer/react 3.1.2 → 3.1.4

package/src/session/facets/__tests__/ArtifactsTab.test.tsx

@@ -9,7 +9,8 @@ import {
   ExecutionPhase,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { StigmerContext } from "../../../context";
-import { ArtifactsTab } from "../ArtifactsTab";
+import { ArtifactsTab, type ArtifactsTabProps } from "../ArtifactsTab";
+import type { SessionArtifactEntry } from "../../useSessionArtifacts";
 
 function artifact(name: string) {
   return create(ExecutionArtifactSchema, {
@@ -38,86 +39,149 @@ function createStigmerMock(): Stigmer {
   } as unknown as Stigmer;
 }
 
-function renderTab(
-  onImplementPlan?: () => void,
-  onOpenPlan?: (executionId: string) => void,
-) {
+function renderTab(props: Partial<ArtifactsTabProps> = {}) {
   return render(
     <StigmerContext.Provider value={createStigmerMock()}>
-      <ArtifactsTab
-        executions={[execution]}
-        org="acme"
-        onImplementPlan={onImplementPlan}
-        onOpenPlan={onOpenPlan}
-      />
+      <ArtifactsTab executions={[execution]} org="acme" {...props} />
     </StigmerContext.Provider>,
   );
 }
 
-function openPreviewFor(name: string) {
-  const row = screen.getByText(name).closest("[role='listitem']") as HTMLElement;
-  fireEvent.click(within(row).getByText("Preview"));
+/** Click the open target of a row by its artifact name. */
+function openRow(name: string) {
+  fireEvent.click(screen.getByText(name));
+}
+
+/** Double-click the open target of a row by its artifact name (the pin gesture). */
+function activateRow(name: string) {
+  fireEvent.doubleClick(screen.getByText(name));
 }
 
 afterEach(cleanup);
 
-describe("ArtifactsTab — plan 'Build from plan' wiring", () => {
-  it("shows 'Build from plan' in the preview of a plan.md artifact", () => {
-    renderTab(vi.fn());
+describe("ArtifactsTab — dense row list", () => {
+  it("renders one row per artifact with a Download control (no old 'Preview' button)", () => {
+    renderTab({ onOpenArtifact: vi.fn() });
 
-    openPreviewFor("plan.md");
+    expect(screen.getAllByRole("listitem")).toHaveLength(2);
+    expect(screen.getByText("plan.md")).toBeTruthy();
+    expect(screen.getByText("notes.md")).toBeTruthy();
+    expect(screen.queryByText("Preview")).toBeNull();
+    expect(screen.getByLabelText("Download plan.md")).toBeTruthy();
+    expect(screen.getByLabelText("Download notes.md")).toBeTruthy();
+  });
 
-    const dialog = document.querySelector("dialog")!;
-    expect(within(dialog).getByText("Build from plan")).toBeTruthy();
+  it("renders the empty state with no artifacts", () => {
+    render(
+      <StigmerContext.Provider value={createStigmerMock()}>
+        <ArtifactsTab executions={[]} org="acme" />
+      </StigmerContext.Provider>,
+    );
+    expect(screen.getByText(/No artifacts yet/)).toBeTruthy();
   });
+});
 
-  it("does not show 'Build from plan' in the preview of a non-plan artifact", () => {
-    renderTab(vi.fn());
+describe("ArtifactsTab — open routing", () => {
+  it("routes a non-plan artifact to onOpenArtifact (no modal) when provided", () => {
+    const onOpenArtifact = vi.fn<(entry: SessionArtifactEntry) => void>();
+    renderTab({ onOpenArtifact, onOpenPlan: vi.fn() });
 
-    openPreviewFor("notes.md");
+    openRow("notes.md");
 
-    const dialog = document.querySelector("dialog")!;
-    expect(within(dialog).queryByText("Build from plan")).toBeNull();
+    expect(onOpenArtifact).toHaveBeenCalledTimes(1);
+    expect(onOpenArtifact.mock.calls[0][0].artifact.name).toBe("notes.md");
+    expect(document.querySelector("dialog")).toBeNull();
   });
 
-  it("invokes onImplementPlan when 'Build from plan' is clicked for a plan", () => {
-    const onImplementPlan = vi.fn();
-    renderTab(onImplementPlan);
+  it("routes plan.md to onOpenPlan (never onOpenArtifact) when both are provided", () => {
+    const onOpenArtifact = vi.fn();
+    const onOpenPlan = vi.fn();
+    renderTab({ onOpenArtifact, onOpenPlan });
 
-    openPreviewFor("plan.md");
-    const dialog = document.querySelector("dialog")!;
-    fireEvent.click(within(dialog).getByText("Build from plan"));
+    openRow("plan.md");
 
-    expect(onImplementPlan).toHaveBeenCalledTimes(1);
+    expect(onOpenPlan).toHaveBeenCalledWith("aex_1");
+    expect(onOpenArtifact).not.toHaveBeenCalled();
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("falls back to the modal for a non-plan artifact when onOpenArtifact is omitted", () => {
+    renderTab({ onOpenPlan: vi.fn() });
+
+    openRow("notes.md");
+
+    expect(document.querySelector("dialog")).toBeTruthy();
+  });
+
+  it("falls back to the modal for plan.md when neither onOpenPlan nor onOpenArtifact is provided", () => {
+    renderTab();
+
+    openRow("plan.md");
+
+    expect(document.querySelector("dialog")).toBeTruthy();
   });
 });
 
-describe("ArtifactsTab — plan routes to the plan document tab", () => {
-  it("routes a plan.md preview to onOpenPlan (no modal) when provided", () => {
+describe("ArtifactsTab — pin (double-click) routing", () => {
+  it("routes a non-plan double-click to onActivateArtifact (pin)", () => {
+    const onActivateArtifact = vi.fn<(entry: SessionArtifactEntry) => void>();
+    renderTab({ onOpenArtifact: vi.fn(), onActivateArtifact, onOpenPlan: vi.fn() });
+
+    activateRow("notes.md");
+
+    expect(onActivateArtifact).toHaveBeenCalledTimes(1);
+    expect(onActivateArtifact.mock.calls[0][0].artifact.name).toBe("notes.md");
+  });
+
+  it("routes a plan.md double-click to onOpenPlan (its tab is already pinned), never onActivateArtifact", () => {
+    const onActivateArtifact = vi.fn();
     const onOpenPlan = vi.fn();
-    renderTab(vi.fn(), onOpenPlan);
+    renderTab({ onOpenArtifact: vi.fn(), onActivateArtifact, onOpenPlan });
 
-    openPreviewFor("plan.md");
+    activateRow("plan.md");
 
     expect(onOpenPlan).toHaveBeenCalledWith("aex_1");
-    expect(document.querySelector("dialog")).toBeNull();
+    expect(onActivateArtifact).not.toHaveBeenCalled();
   });
 
-  it("keeps the modal for non-plan artifacts even when onOpenPlan is provided", () => {
-    const onOpenPlan = vi.fn();
-    renderTab(vi.fn(), onOpenPlan);
+  it("binds no double-click when onActivateArtifact is omitted (panel-less host) — a double-click is harmless", () => {
+    const onOpenArtifact = vi.fn();
+    renderTab({ onOpenArtifact });
 
-    openPreviewFor("notes.md");
+    // With no pin handler the row binds no onDoubleClick, so a dblclick fires
+    // nothing (in a real browser the leading single-clicks still preview).
+    expect(() => activateRow("notes.md")).not.toThrow();
+    expect(onOpenArtifact).not.toHaveBeenCalled();
+  });
+});
 
-    expect(onOpenPlan).not.toHaveBeenCalled();
-    expect(document.querySelector("dialog")).toBeTruthy();
+describe("ArtifactsTab — modal fallback plan 'Build' wiring", () => {
+  it("shows 'Build' in the modal preview of a plan.md artifact (panel-less host)", () => {
+    renderTab({ onImplementPlan: vi.fn() });
+
+    openRow("plan.md");
+
+    const dialog = document.querySelector("dialog")!;
+    expect(within(dialog).getByText("Build")).toBeTruthy();
   });
 
-  it("keeps the modal for plan.md when onOpenPlan is omitted (hosts without the plan tab)", () => {
-    renderTab(vi.fn());
+  it("does not show 'Build' in the modal preview of a non-plan artifact", () => {
+    renderTab({ onImplementPlan: vi.fn() });
 
-    openPreviewFor("plan.md");
+    openRow("notes.md");
 
-    expect(document.querySelector("dialog")).toBeTruthy();
+    const dialog = document.querySelector("dialog")!;
+    expect(within(dialog).queryByText("Build")).toBeNull();
+  });
+
+  it("invokes onImplementPlan when 'Build' is clicked for a plan", () => {
+    const onImplementPlan = vi.fn();
+    renderTab({ onImplementPlan });
+
+    openRow("plan.md");
+    const dialog = document.querySelector("dialog")!;
+    fireEvent.click(within(dialog).getByText("Build"));
+
+    expect(onImplementPlan).toHaveBeenCalledTimes(1);
   });
 });

package/src/session/index.ts

@@ -33,7 +33,7 @@ export type {
   UseSessionConversationReturn,
 } from "./useSessionConversation.js";
 
-export { useSessionArtifacts } from "./useSessionArtifacts.js";
+export { useSessionArtifacts, artifactKey } from "./useSessionArtifacts.js";
 export type {
   SessionArtifactEntry,
   UseSessionArtifactsReturn,
@@ -127,6 +127,10 @@ export {
   PLAN_DOCUMENT_PATH,
 } from "./plan-document.js";
 
+// Artifact document — the editor-area rendering of an execution artifact
+// (mounted as an artifact-family virtual document) and the identity of its tabs.
+export { ARTIFACT_DOCUMENT_ENTRY_ID } from "./artifact-document.js";
+
 // Selection types (for platform builders composing their own Inspect facet)
 export type { SelectedThreadItem } from "../internal/store/selection-store.js";
 

package/src/session/plan-document.ts

@@ -6,7 +6,6 @@
 // their module graph (DD-003 headless-first).
 
 import { virtualEntryId } from "../internal/store/index.js";
-import { PLAN_ARTIFACT_NAME } from "../library/detect-plan-artifact.js";
 
 /**
  * Virtual entry id of the plan document tab. One tab per session — the host
@@ -15,5 +14,17 @@ import { PLAN_ARTIFACT_NAME } from "../library/detect-plan-artifact.js";
  */
 export const PLAN_DOCUMENT_ENTRY_ID = virtualEntryId("plan");
 
-/** The plan tab's path — doubles as its tab label, matching the artifact name. */
-export const PLAN_DOCUMENT_PATH = PLAN_ARTIFACT_NAME;
+/**
+ * The plan tab's path — doubles as its tab label.
+ *
+ * Deliberately plan-AGNOSTIC ("Plan"), not the artifact's filename. The
+ * workspace surface identifies a virtual document's tab by
+ * `editorKey(entryId, path)`, so `path` is part of the tab's IDENTITY — and the
+ * session keeps exactly ONE plan tab that swaps which plan it shows (latest
+ * editable, or a superseded plan read-only). Now that plans carry unique,
+ * title-derived filenames (`<slug>_<id>.plan.md`), binding this label to any one
+ * plan's name would mint a new tab identity per plan and shatter the
+ * single-tab design. A stable, generic label is therefore required, not a
+ * stylistic choice — do not "fix" it to track the filename.
+ */
+export const PLAN_DOCUMENT_PATH = "Plan";

package/src/session/usePlanDraft.ts

@@ -32,7 +32,7 @@ export interface PlanDraftController {
   /**
    * Snapshot reader for submit-time consumers: returns the current draft (or
    * `null`) without the caller depending on draft state. Referentially stable
-   * for the lifetime of the component (DD-010) — "Build from plan" reads the
+   * for the lifetime of the component (DD-010) — the "Build" action reads the
    * draft through this at click time, so per-keystroke draft updates never
    * re-bind the build callback or re-render the conversation column.
    */

package/src/session/useSessionArtifacts.ts

@@ -41,11 +41,22 @@ export interface UseSessionArtifactsReturn {
 }
 
 /**
- * Returns the dedup key for an artifact. Uses `sandbox_path` when
- * available (stable filesystem identity within the session sandbox),
- * falling back to `name` for older artifacts that predate the field.
+ * The stable identity of an artifact within a session. Uses `sandbox_path`
+ * when available (the artifact's filesystem identity within the session
+ * sandbox), falling back to `name` for older artifacts that predate the field.
+ *
+ * This is the SINGLE source of truth for artifact identity across three sites
+ * that must agree or a tab could fail to resolve its artifact:
+ * 1. deduplication here (latest execution wins per key),
+ * 2. the virtual-document tab `path` when an artifact opens in the editor area
+ *    (see `SessionViewer` / `useSessionPanel.openArtifact`), and
+ * 3. the `artifactKey → entry` lookup that renders the open tab's document.
+ *
+ * Its basename doubles as the editor tab's label (paths render as their last
+ * `/` segment in `EditorTabs`), so `sandbox_path` gives a natural filename
+ * label with cross-directory disambiguation for free.
  */
-function dedupKey(artifact: ExecutionArtifact): string {
+export function artifactKey(artifact: ExecutionArtifact): string {
   return artifact.sandboxPath || artifact.name;
 }
 
@@ -102,7 +113,7 @@ export function useSessionArtifacts(
       const terminal = isTerminalPhase(phase);
 
       for (const artifact of execution.status?.artifacts ?? []) {
-        const key = dedupKey(artifact);
+        const key = artifactKey(artifact);
         entryMap.set(key, {
           artifact,
           executionId,

package/src/session/useSessionConversation.ts

@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
-import type { FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import type { FileChangeProgress, FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
 import { ApprovalAction, ExecutionPhase, FileChangeSetStatus, FileDecisionAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import type { McpServerUsage as ProtoMcpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
@@ -97,7 +97,7 @@ export interface SendFollowUpOptions {
    */
   readonly interactionMode?: "agent" | "plan";
   /**
-   * Marks this execution as a "Build from plan" turn.
+   * Marks this execution as a Build-from-plan turn.
    *
    * @see {@link CreateAgentExecutionInput.buildFromPlan}
    */
@@ -117,6 +117,15 @@ export interface SendFollowUpOptions {
    * @see {@link CreateAgentExecutionInput.workspaceFileRefs}
    */
   readonly workspaceFileRefs?: string[];
+  /**
+   * ID of the execution this follow-up supersedes (edit-and-resubmit).
+   *
+   * The conversation read model hides the superseded execution so the
+   * edited message replaces the original in place.
+   *
+   * @see {@link CreateAgentExecutionInput.supersedesExecutionId}
+   */
+  readonly supersedesExecutionId?: string;
 }
 
 /**
@@ -129,7 +138,14 @@ export interface SendFollowUpOptions {
 export interface UseSessionConversationReturn {
   /** The session object, or null while loading. */
   readonly session: Session | null;
-  /** Executions in terminal phases, in chronological order. */
+  /**
+   * Executions in terminal phases, in chronological order.
+   *
+   * Excludes turns replaced via edit-and-resubmit (an execution whose id
+   * appears as another execution's `supersedesExecutionId`) — the edited
+   * message stands in the original's place. Superseded records remain in
+   * execution history surfaces; only the conversation view hides them.
+   */
   readonly completedExecutions: readonly AgentExecution[];
   /** Currently streaming execution (stream or fetch fallback), or null. */
   readonly activeStreamExecution: AgentExecution | null;
@@ -222,6 +238,13 @@ export interface UseSessionConversationReturn {
 
   /** Captured change sets awaiting file review on the active execution, empty when none. */
   readonly fileChangeSets: readonly FileChangeSet[];
+  /**
+   * Mid-run live capture (DD-32): the transient, non-authoritative snapshot of the
+   * workspace delta accumulating during the active turn ("N files changed so far").
+   * Undefined when no turn is currently capturing. Never decidable — the reviewed
+   * diff is {@link fileChangeSets}.
+   */
+  readonly fileChangeProgress: FileChangeProgress | undefined;
   /** Submit a file-review decision for a change set. The executionId is managed internally. */
   readonly submitFileDecision: (
     changeSetId: string,
@@ -484,12 +507,37 @@ export function useSessionConversation(
     }
   }, [activeExecutionId, stream.phase, refetch]);
 
+  // Executions replaced via edit-and-resubmit. The successor carries
+  // `spec.supersedes_execution_id`; hiding the superseded turn makes the
+  // edited message read as a single corrected exchange (in-place replace).
+  // The link must also be read off the live stream copy — right after a
+  // resubmit, the successor streams before the list refetch delivers it.
+  // Display-only: the raw `executions` list (and therefore active-id
+  // resolution above) is never filtered.
+  //
+  // Dep is the scalar link, NOT stream.execution: the stream object changes
+  // reference every frame, and rebuilding the Set per frame would hand
+  // MessageThread a fresh executions array mid-stream, defeating its
+  // memoization (DD-010).
+  const streamSupersededId =
+    stream.execution?.spec?.supersedesExecutionId || null;
+  const supersededIds = useMemo(() => {
+    const ids = new Set<string>();
+    for (const e of executions) {
+      const superseded = e.spec?.supersedesExecutionId;
+      if (superseded) ids.add(superseded);
+    }
+    if (streamSupersededId) ids.add(streamSupersededId);
+    return ids;
+  }, [executions, streamSupersededId]);
+
   const completedExecutions = useMemo(() => {
-    if (!activeExecutionId) return executions;
-    return executions.filter(
-      (e) => (e.metadata?.id ?? "") !== activeExecutionId,
-    );
-  }, [executions, activeExecutionId]);
+    return executions.filter((e) => {
+      const id = e.metadata?.id ?? "";
+      if (activeExecutionId && id === activeExecutionId) return false;
+      return !supersededIds.has(id);
+    });
+  }, [executions, activeExecutionId, supersededIds]);
 
   const fetchedActiveExecution = useMemo(() => {
     if (!activeExecutionId) return null;
@@ -554,7 +602,14 @@ export function useSessionConversation(
       // Capture for retry and clear any prior failure before the new attempt.
       lastSendRef.current = { message, options };
       setSendError(null);
-      setPendingUserMessage(message);
+      // A Build-from-plan turn shows no optimistic bubble: its message is a
+      // machine-written label, not user prose, and the thread hides the turn
+      // entirely (the plan card's "Starting build…" state covers the send
+      // window). It is still set on FAILURE below, so a failed build send
+      // renders the failed-with-retry bubble instead of vanishing.
+      if (!options?.buildFromPlan) {
+        setPendingUserMessage(message);
+      }
 
       try {
         const needsSessionUpdate =
@@ -590,13 +645,17 @@ export function useSessionConversation(
           buildFromPlan: options?.buildFromPlan,
           autoApproveAll: options?.autoApproveAll,
           workspaceFileRefs: options?.workspaceFileRefs,
+          supersedesExecutionId: options?.supersedesExecutionId,
         });
         setPendingExecutionId(result.executionId);
         refetch();
       } catch (err) {
         // Surface the failure and KEEP the user's message visible (do not clear
         // pendingUserMessage) so the turn renders as failed-with-retry instead
-        // of vanishing. Covers both the update() and create() paths.
+        // of vanishing. Covers both the update() and create() paths. For a
+        // build turn this is the FIRST time the message is set — failure is
+        // the one case where its label must become visible.
+        setPendingUserMessage(message);
         setSendError(toError(err));
         if (process.env.NODE_ENV !== "production") {
           console.error("[useSessionConversation] sendFollowUp failed:", err);
@@ -641,6 +700,16 @@ export function useSessionConversation(
     [activeStreamExecution],
   );
 
+  // Mid-run live capture (DD-32): the transient, non-authoritative "N files
+  // changed so far" snapshot for the active turn. The server clears it once the
+  // turn's change set leaves CAPTURING, so its mere presence means a turn is
+  // still accumulating changes. Reference-stable per DD-010 (it rides the
+  // structurally-shared live status).
+  const fileChangeProgress = useMemo<FileChangeProgress | undefined>(
+    () => activeStreamExecution?.status?.fileChangeProgress,
+    [activeStreamExecution],
+  );
+
   const submitFileDecision = useCallback(
     async (
       changeSetId: string,
@@ -685,6 +754,7 @@ export function useSessionConversation(
     clearApprovalError,
 
     fileChangeSets,
+    fileChangeProgress,
     submitFileDecision,
     submittingFileDecisionKeys: submittingDecisionKeys,
     fileDecisionErrors,

package/src/session/useSessionPageFlow.ts

@@ -410,6 +410,7 @@ export function useSessionPageFlow(
         // not from the composer (the pre-arm toggle was removed).
         autoApproveAll: autoApproveAll || undefined,
         workspaceFileRefs: context?.workspaceFileRefs,
+        supersedesExecutionId: context?.supersedesExecutionId,
       });
 
       sessionVariables.clear();

package/src/session/useSessionPanel.ts

@@ -2,6 +2,7 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import { isTerminalPhase } from "../execution/execution-phases.js";
 import type { SelectedThreadItem } from "../internal/store/selection-store.js";
 import {
@@ -10,6 +11,8 @@ import {
   type WorkspaceEditorsStore,
 } from "../internal/store/index.js";
 import { PLAN_DOCUMENT_ENTRY_ID, PLAN_DOCUMENT_PATH } from "./plan-document.js";
+import { ARTIFACT_DOCUMENT_ENTRY_ID } from "./artifact-document.js";
+import { artifactKey } from "./useSessionArtifacts.js";
 
 /** Options for {@link useSessionPanel}. */
 export interface UseSessionPanelOptions {
@@ -118,6 +121,25 @@ export interface SessionPanelController {
    * both when a plan STARTS STREAMING and when it publishes (see `planKey`).
    */
   readonly openPlanDocument: () => void;
+  /**
+   * Open (or focus) an artifact as an editor-pane document tab and expand the
+   * panel. Uses the PREVIEW slot — like files and content-search hits, casual
+   * artifact browsing reuses one tab (single-click), and double-clicking the
+   * tab pins it. Distinct from `openPlanDocument`, which pins its single tab: a
+   * plan is the turn's deliverable, artifacts are browsable outputs. The
+   * artifact's {@link artifactKey} is the tab identity, shared with the
+   * `SurfaceVirtualDocument` the viewer builds for the open tab.
+   */
+  readonly openArtifact: (artifact: ExecutionArtifact) => void;
+  /**
+   * Pin an artifact's tab (clear its preview state) — the double-click half of
+   * the open/activate split, the encapsulated sibling of {@link openArtifact}.
+   * Delegates to the editors store's generic `pin`, exactly as the file tree
+   * pins via `pinEditor`: the leading single-click of the double-click has
+   * already opened the preview tab, so this promotes it to a persistent tab. A
+   * no-op if the artifact is not open.
+   */
+  readonly pinArtifact: (artifact: ExecutionArtifact) => void;
   /**
    * Report the current thread-item selection. Called from an effect inside the
    * panel subtree (the level that subscribes to the selection store), keeping
@@ -224,6 +246,21 @@ export function useSessionPanel({
     [editorsStore],
   );
 
+  const openArtifact = useCallback(
+    (artifact: ExecutionArtifact) => {
+      editorsStore.openPreview(ARTIFACT_DOCUMENT_ENTRY_ID, artifactKey(artifact));
+      setIsOpen(true);
+    },
+    [editorsStore],
+  );
+
+  const pinArtifact = useCallback(
+    (artifact: ExecutionArtifact) => {
+      editorsStore.pin(ARTIFACT_DOCUMENT_ENTRY_ID, artifactKey(artifact));
+    },
+    [editorsStore],
+  );
+
   const activateEditor = useCallback(
     (entryId: string, path: string) => editorsStore.activate(entryId, path),
     [editorsStore],
@@ -268,6 +305,8 @@ export function useSessionPanel({
       pinEditor,
       closeEditor,
       openPlanDocument,
+      openArtifact,
+      pinArtifact,
       notifySelection,
     }),
     [
@@ -282,6 +321,8 @@ export function useSessionPanel({
       pinEditor,
       closeEditor,
       openPlanDocument,
+      openArtifact,
+      pinArtifact,
       notifySelection,
     ],
   );

package/src/session/useSessionRailViews.tsx

@@ -6,7 +6,10 @@ import type { SurfaceRailView } from "../workspace/WorkspaceSurface.js";
 import type { SelectedThreadItem } from "../internal/store/selection-store.js";
 import type { ApplyResourceResult } from "../library/useApplyResource.js";
 import { useSessionWriteBacks } from "./useSessionWriteBacks.js";
-import { useSessionArtifacts } from "./useSessionArtifacts.js";
+import {
+  useSessionArtifacts,
+  type SessionArtifactEntry,
+} from "./useSessionArtifacts.js";
 import { SetupTab, type SetupTabProps } from "./facets/SetupTab.js";
 import { ChangesTab } from "./facets/ChangesTab.js";
 import { ArtifactsTab } from "./facets/ArtifactsTab.js";
@@ -33,6 +36,17 @@ export interface UseSessionRailViewsOptions {
    * of the preview modal.
    */
   readonly onOpenPlan?: (executionId: string) => void;
+  /**
+   * Open a (non-plan) artifact as an editor-pane document tab. Routed to the
+   * Artifacts facet so clicking an artifact opens it in the editor area (VS
+   * Code "each file is a tab") instead of the preview modal.
+   */
+  readonly onOpenArtifact?: (entry: SessionArtifactEntry) => void;
+  /**
+   * Pin a (non-plan) artifact's document tab — the double-click half of the
+   * Artifacts facet's open/activate split. Routed through to the facet's rows.
+   */
+  readonly onActivateArtifact?: (entry: SessionArtifactEntry) => void;
   /**
    * Whether to offer the execution-derived facets (Changes / Artifacts /
    * Usage). The launcher passes `false` — before a session exists there are no
@@ -60,6 +74,8 @@ export function useSessionRailViews({
   onApplied,
   onImplementPlan,
   onOpenPlan,
+  onOpenArtifact,
+  onActivateArtifact,
   includeExecutionFacets = true,
 }: UseSessionRailViewsOptions): readonly SurfaceRailView[] {
   const { hasWriteBacks, writeBackCount } = useSessionWriteBacks(allExecutions);
@@ -101,6 +117,8 @@ export function useSessionRailViews({
               onApplied={onApplied}
               onImplementPlan={onImplementPlan}
               onOpenPlan={onOpenPlan}
+              onOpenArtifact={onOpenArtifact}
+              onActivateArtifact={onActivateArtifact}
             />
           ),
         });
@@ -136,6 +154,8 @@ export function useSessionRailViews({
     onApplied,
     onImplementPlan,
     onOpenPlan,
+    onOpenArtifact,
+    onActivateArtifact,
     selectedItem,
   ]);
 }