@stigmer/react 3.1.3 → 3.1.5

package/src/session/__tests__/useWorkspaceReadRefs.test.ts

@@ -0,0 +1,245 @@
+import { describe, it, expect } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import {
+  WorkspaceWriteBackSchema,
+  WorkspaceWriteBackPhase,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+import type { WorkspaceEntry } from "../../workspace/useWorkspaceEntries";
+import { useWorkspaceReadRefs } from "../useWorkspaceReadRefs";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function gitEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
+  return {
+    id: "ws-1",
+    name: "acme/api",
+    type: "git",
+    gitUrl: "https://github.com/acme/api",
+    gitBranch: "main",
+    ...overrides,
+  };
+}
+
+function localEntry(): WorkspaceEntry {
+  return {
+    id: "ws-local",
+    name: "dev/project",
+    type: "local",
+    localPath: "/Users/dev/project",
+  };
+}
+
+function execWithWriteBacks(
+  id: string,
+  writeBacks: ReadonlyArray<{
+    entryName: string;
+    commitSha: string;
+    phase?: WorkspaceWriteBackPhase;
+  }>,
+): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  exec.metadata = create(ApiResourceMetadataSchema, { id });
+  exec.status = create(AgentExecutionStatusSchema);
+  exec.status.workspaceWriteBacks = writeBacks.map((wb) =>
+    create(WorkspaceWriteBackSchema, {
+      workspaceEntryName: wb.entryName,
+      commitSha: wb.commitSha,
+      phase: wb.phase ?? WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_PUSHED,
+    }),
+  );
+  return exec;
+}
+
+// ---------------------------------------------------------------------------
+// useWorkspaceReadRefs
+// ---------------------------------------------------------------------------
+
+describe("useWorkspaceReadRefs", () => {
+  it("returns the same entries reference when there are no write-backs", () => {
+    const entries = [gitEntry()];
+    const { result } = renderHook(() => useWorkspaceReadRefs([], entries));
+    expect(result.current).toBe(entries);
+  });
+
+  it("decorates a single git entry from a write-back with a matching name", () => {
+    const entries = [gitEntry({ name: "acme/api" })];
+    const executions = [
+      execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-1" }]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBe("sha-1");
+  });
+
+  it("applies an empty-name write-back to the lone git entry (single-entry convention)", () => {
+    // Single-entry sessions provision with entryName "" — the runner's
+    // WriteBackCoordinator writes back under that empty name.
+    const entries = [gitEntry()];
+    const executions = [
+      execWithWriteBacks("e1", [{ entryName: "", commitSha: "sha-solo" }]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBe("sha-solo");
+  });
+
+  it("claims a lone mismatched name for a lone git entry, but never for multiple entries", () => {
+    const solo = renderHook(() =>
+      useWorkspaceReadRefs(
+        [execWithWriteBacks("e1", [{ entryName: "other-name", commitSha: "sha-x" }])],
+        [gitEntry()],
+      ),
+    );
+    expect(solo.result.current[0].readRef).toBe("sha-x");
+
+    // With two git entries an unmatched name is ambiguous — decorate nothing.
+    const multi = renderHook(() =>
+      useWorkspaceReadRefs(
+        [execWithWriteBacks("e1", [{ entryName: "other-name", commitSha: "sha-x" }])],
+        [
+          gitEntry({ id: "ws-1", name: "acme/api" }),
+          gitEntry({ id: "ws-2", name: "acme/web" }),
+        ],
+      ),
+    );
+    expect(multi.result.current[0].readRef).toBeUndefined();
+    expect(multi.result.current[1].readRef).toBeUndefined();
+  });
+
+  it("the latest non-empty SHA wins across executions in order", () => {
+    const entries = [gitEntry({ name: "acme/api" })];
+    const executions = [
+      execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-old" }]),
+      execWithWriteBacks("e2", [{ entryName: "acme/api", commitSha: "sha-new" }]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBe("sha-new");
+  });
+
+  it("a FAILED write-back with no SHA never regresses an earlier successful ref", () => {
+    const entries = [gitEntry({ name: "acme/api" })];
+    const executions = [
+      execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-good" }]),
+      execWithWriteBacks("e2", [
+        {
+          entryName: "acme/api",
+          commitSha: "",
+          phase: WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_FAILED,
+        },
+      ]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBe("sha-good");
+  });
+
+  it("returns entries unchanged when only FAILED no-SHA write-backs exist", () => {
+    const entries = [gitEntry()];
+    const executions = [
+      execWithWriteBacks("e1", [
+        {
+          entryName: "",
+          commitSha: "",
+          phase: WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_FAILED,
+        },
+      ]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current).toBe(entries);
+  });
+
+  it("matches strictly by name in multi-entry sessions", () => {
+    const entries = [
+      gitEntry({ id: "ws-1", name: "frontend" }),
+      gitEntry({ id: "ws-2", name: "backend" }),
+    ];
+    const executions = [
+      execWithWriteBacks("e1", [
+        { entryName: "frontend", commitSha: "sha-fe" },
+        { entryName: "backend", commitSha: "sha-be" },
+      ]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBe("sha-fe");
+    expect(result.current[1].readRef).toBe("sha-be");
+  });
+
+  it("never decorates local entries", () => {
+    const entries = [localEntry()];
+    const executions = [
+      execWithWriteBacks("e1", [{ entryName: "", commitSha: "sha-1" }]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBeUndefined();
+    expect(result.current).toBe(entries);
+  });
+
+  it("returns a stable array across streaming frames that change no SHA (DD-010)", () => {
+    const entries = [gitEntry({ name: "acme/api" })];
+    const { result, rerender } = renderHook(
+      (props: { executions: readonly AgentExecution[] }) =>
+        useWorkspaceReadRefs(props.executions, entries),
+      {
+        initialProps: {
+          executions: [
+            execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-1" }]),
+          ] as readonly AgentExecution[],
+        },
+      },
+    );
+
+    const first = result.current;
+    expect(first[0].readRef).toBe("sha-1");
+
+    // A new executions array (fresh identity, e.g. a streaming frame) with the
+    // same SHA must return the identical decorated array.
+    rerender({
+      executions: [
+        execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-1" }]),
+      ],
+    });
+    expect(result.current).toBe(first);
+
+    // Advancing the SHA produces a new decoration.
+    rerender({
+      executions: [
+        execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-2" }]),
+      ],
+    });
+    expect(result.current[0].readRef).toBe("sha-2");
+  });
+});

package/src/session/artifact-document.ts

@@ -0,0 +1,23 @@
+// Identity of the session's artifact document tabs in the workspace surface's
+// editor group.
+//
+// Kept in its own module (not in ArtifactDocument.tsx) so behavior-only
+// consumers — useSessionPanel opens an artifact tab, SessionViewer routes to it
+// — depend on the identity without pulling the component (and its content
+// renderer) into their module graph (DD-003 headless-first). Mirrors
+// plan-document.ts.
+
+import { virtualEntryId } from "../internal/store/index.js";
+
+/**
+ * Virtual entry id of the artifact document FAMILY. Unlike the plan (one tab
+ * per session), artifacts are many: every opened artifact shares this one
+ * entry id and is distinguished by its {@link artifactKey}-derived `path`, so
+ * `editorKey(ARTIFACT_DOCUMENT_ENTRY_ID, path)` yields one tab per artifact —
+ * the VS Code "each file is a tab" model. The NUL-namespaced virtual id can
+ * never alias a real workspace entry, and its distinct `"artifact"` kind can
+ * never collide with the plan tab's `"plan"` kind.
+ *
+ * @see artifactKey — the `path` component (an artifact's stable identity)
+ */
+export const ARTIFACT_DOCUMENT_ENTRY_ID = virtualEntryId("artifact");

package/src/session/facets/ArtifactsTab.tsx

@@ -4,10 +4,11 @@ import { useCallback, useState } from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import {
   useSessionArtifacts,
+  artifactKey,
   type SessionArtifactEntry,
 } from "../useSessionArtifacts.js";
-import { ArtifactCard } from "../../execution/ArtifactCard.js";
 import { ArtifactPreviewModal } from "../../execution/ArtifactPreviewModal.js";
+import { ArtifactRow } from "../../execution/ArtifactRow.js";
 import { isPlanArtifact } from "../../library/detect-plan-artifact.js";
 import type { ApplyResourceResult } from "../../library/useApplyResource.js";
 
@@ -29,14 +30,39 @@ export interface ArtifactsTabProps {
    * every artifact.
    */
   readonly onOpenPlan?: (executionId: string) => void;
+  /**
+   * Open an artifact as an editor-pane document (the session panel's
+   * artifact-family virtual-document tab — the VS Code "each file is a tab"
+   * model). When provided, clicking a non-plan artifact routes here instead of
+   * the preview modal. When omitted (panel-less hosts) the modal remains the
+   * open mechanism. Plan artifacts always defer to {@link onOpenPlan} first.
+   */
+  readonly onOpenArtifact?: (entry: SessionArtifactEntry) => void;
+  /**
+   * Pin a non-plan artifact's document tab — the double-click half of the
+   * open/activate split (mirrors the file tree's `onOpenFile`/`onActivateFile`).
+   * When provided, each row binds a double-click that promotes the preview the
+   * single click opened. Omit in panel-less/modal hosts: with no handler the
+   * row binds no double-click, so a double-click is just two harmless single
+   * clicks. Plans always route to {@link onOpenPlan} (their tab is already
+   * pinned), so double-click == single-click for a plan.
+   */
+  readonly onActivateArtifact?: (entry: SessionArtifactEntry) => void;
 }
 
 /**
  * Artifacts facet for the session panel (a `useSessionRailViews` rail view).
  *
- * Wraps `useSessionArtifacts` → `ArtifactCard` list with
- * `ArtifactPreviewModal` — the same content as `ArtifactsWidget`
- * without the section heading.
+ * A VS Code-style dense file list of the session's outputs: one compact
+ * {@link ArtifactRow} per artifact (shared file-type icon + name + size, with a
+ * hover/focus Download). Clicking a row opens the artifact — a `plan.md` in the
+ * plan document tab ({@link onOpenPlan}), any other artifact in an editor-pane
+ * document ({@link onOpenArtifact}), or, for panel-less hosts that inject
+ * neither, the {@link ArtifactPreviewModal} popup fallback.
+ *
+ * Deliberately metadata-only: rows do NOT fetch content for resource detection
+ * (that would be one request per artifact on open) — detection and the
+ * Apply/Push action live in the opened document/modal instead.
  */
 export function ArtifactsTab({
   executions,
@@ -44,20 +70,41 @@ export function ArtifactsTab({
   onApplied,
   onImplementPlan,
   onOpenPlan,
+  onOpenArtifact,
+  onActivateArtifact,
 }: ArtifactsTabProps) {
   const { artifacts, hasArtifacts } = useSessionArtifacts(executions);
   const [previewEntry, setPreviewEntry] = useState<SessionArtifactEntry | null>(null);
 
-  const handlePreview = useCallback(
+  const handleOpen = useCallback(
     (entry: SessionArtifactEntry) => {
-      // The plan opens as a document (the panel's plan tab), never a popup.
+      // A plan is a first-class document — it opens in the dedicated plan tab,
+      // never as a generic artifact or a popup.
       if (onOpenPlan && isPlanArtifact(entry.artifact)) {
         onOpenPlan(entry.executionId);
         return;
       }
+      // Editor-pane document when the host injected it; otherwise the modal.
+      if (onOpenArtifact) {
+        onOpenArtifact(entry);
+        return;
+      }
       setPreviewEntry(entry);
     },
-    [onOpenPlan],
+    [onOpenPlan, onOpenArtifact],
+  );
+
+  const handleActivate = useCallback(
+    (entry: SessionArtifactEntry) => {
+      // A plan's tab is always pinned, so double-click matches single-click:
+      // route to the plan tab, never pin a generic artifact.
+      if (onOpenPlan && isPlanArtifact(entry.artifact)) {
+        onOpenPlan(entry.executionId);
+        return;
+      }
+      onActivateArtifact?.(entry);
+    },
+    [onOpenPlan, onActivateArtifact],
   );
 
   const handleClosePreview = useCallback(() => {
@@ -76,19 +123,20 @@ export function ArtifactsTab({
 
   return (
     <>
-      <div role="list" className="space-y-2">
+      <ul role="list" className="flex flex-col">
         {artifacts.map((entry) => (
-          <div key={entry.artifact.sandboxPath || entry.artifact.name} role="listitem">
-            <ArtifactCard
-              artifact={entry.artifact}
-              executionId={entry.executionId}
-              org={org}
-              hasNameCollision={entry.hasNameCollision}
-              onPreview={() => handlePreview(entry)}
-            />
-          </div>
+          <ArtifactRow
+            key={artifactKey(entry.artifact)}
+            artifact={entry.artifact}
+            executionId={entry.executionId}
+            hasNameCollision={entry.hasNameCollision}
+            onOpen={() => handleOpen(entry)}
+            onActivate={
+              onActivateArtifact ? () => handleActivate(entry) : undefined
+            }
+          />
         ))}
-      </div>
+      </ul>
 
       {previewEntry && (
         <ArtifactPreviewModal

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' wiring", () => {
-  it("shows 'Build' 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")).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' 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")).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' 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"));
+    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,
@@ -45,6 +45,8 @@ export type {
   UseSessionWriteBacksReturn,
 } from "./useSessionWriteBacks.js";
 
+export { useWorkspaceReadRefs } from "./useWorkspaceReadRefs.js";
+
 export { useSessionFileChanges } from "./useSessionFileChanges.js";
 export type { UseSessionFileChangesReturn } from "./useSessionFileChanges.js";
 
@@ -127,6 +129,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/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,