@stigmer/react 3.1.4 → 3.1.5

package/src/execution/__tests__/message-thread-slots.test.tsx

@@ -0,0 +1,463 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import React, { memo } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  AgentExecutionSpecSchema,
+  ExecutionConfigSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import { TodoItemSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
+import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import {
+  ApprovalAction,
+  ExecutionArtifactKind,
+  ExecutionPhase,
+  InteractionMode,
+  MessageType,
+  TodoStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { MessageThread, type MessageThreadSlots } from "../MessageThread";
+import type { MessageEntryProps } from "../MessageEntry";
+import type { ApprovalCardProps } from "../ApprovalCard";
+import type { TodoCardProps } from "../TodoCard";
+import type { TodoRowProps } from "../TodoList";
+import type { SetupProgressProps } from "../SetupProgress";
+import type { PlanCompletionCardProps } from "../PlanCompletionCard";
+import type { PlanArtifactCardProps } from "../PlanArtifactCard";
+import type { PlanStreamingCardProps } from "../PlanStreamingCard";
+
+// ---------------------------------------------------------------------------
+// Mock react-virtuoso (same pattern as virtualized-thread.test.tsx) so the
+// virtualized path renders its items synchronously in happy-dom.
+// ---------------------------------------------------------------------------
+
+vi.mock("react-virtuoso", () => ({
+  Virtuoso: React.forwardRef(function MockVirtuoso(
+    props: Record<string, unknown>,
+    ref: React.Ref<unknown>,
+  ) {
+    const data = props.data as { key: string }[];
+    const itemContent = props.itemContent as (
+      index: number,
+      item: unknown,
+    ) => React.ReactNode;
+    React.useImperativeHandle(ref, () => ({ scrollToIndex: vi.fn() }));
+    return (
+      <div data-testid="virtuoso-scroller">
+        {data.map((item, i) => (
+          <div key={item.key}>{itemContent(i, item)}</div>
+        ))}
+      </div>
+    );
+  }),
+}));
+
+// ---------------------------------------------------------------------------
+// DOM stubs — useAutoScroll depends on browser APIs not available in happy-dom
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  vi.stubGlobal(
+    "IntersectionObserver",
+    vi.fn(() => ({
+      observe: vi.fn(),
+      unobserve: vi.fn(),
+      disconnect: vi.fn(),
+      takeRecords: vi.fn(() => []),
+      root: null,
+      rootMargin: "",
+      thresholds: [0],
+    })),
+  );
+  vi.stubGlobal(
+    "ResizeObserver",
+    vi.fn(() => ({ observe: vi.fn(), unobserve: vi.fn(), disconnect: vi.fn() })),
+  );
+  vi.stubGlobal(
+    "requestAnimationFrame",
+    vi.fn((cb: FrameRequestCallback) => {
+      cb(performance.now());
+      return 1;
+    }),
+  );
+  vi.stubGlobal("cancelAnimationFrame", vi.fn());
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function makeExecution(opts: {
+  id: string;
+  specMessage?: string;
+  phase?: ExecutionPhase;
+  interactionMode?: InteractionMode;
+  aiContent?: string;
+  todos?: Record<string, { content: string; status: TodoStatus }>;
+  pendingApprovalToolCallId?: string;
+  planArtifactName?: string;
+}): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+
+  const meta = create(ApiResourceMetadataSchema);
+  meta.id = opts.id;
+  exec.metadata = meta;
+
+  const spec = create(AgentExecutionSpecSchema);
+  spec.message = opts.specMessage ?? "Hello";
+  if (opts.interactionMode !== undefined) {
+    const config = create(ExecutionConfigSchema);
+    config.interactionMode = opts.interactionMode;
+    spec.executionConfig = config;
+  }
+  exec.spec = spec;
+
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = opts.phase ?? ExecutionPhase.EXECUTION_COMPLETED;
+
+  const aiMsg = create(AgentMessageSchema);
+  aiMsg.type = MessageType.MESSAGE_AI;
+  aiMsg.content = opts.aiContent ?? "Hi there!";
+  status.messages = [aiMsg];
+
+  if (opts.todos) {
+    for (const [id, todo] of Object.entries(opts.todos)) {
+      status.todos[id] = create(TodoItemSchema, {
+        id,
+        content: todo.content,
+        status: todo.status,
+      });
+    }
+  }
+
+  if (opts.pendingApprovalToolCallId) {
+    status.pendingApprovals = [
+      create(PendingApprovalSchema, {
+        toolCallId: opts.pendingApprovalToolCallId,
+        toolName: "shell_exec",
+        argsPreview: "{}",
+      }),
+    ];
+  }
+
+  if (opts.planArtifactName) {
+    status.artifacts = [
+      create(ExecutionArtifactSchema, {
+        name: opts.planArtifactName,
+        kind: ExecutionArtifactKind.FILE,
+      }),
+    ];
+  }
+
+  exec.status = status;
+  return exec;
+}
+
+// ---------------------------------------------------------------------------
+// Slot overrides — each slot renders in place of its built-in
+// ---------------------------------------------------------------------------
+
+describe("MessageThread slots", () => {
+  it("renders the MessageEntry slot for every message, including the failed-send bubble", () => {
+    const CustomEntry = ({ message }: MessageEntryProps) => (
+      <div data-testid="custom-entry">{message.content}</div>
+    );
+    const slots: MessageThreadSlots = { MessageEntry: CustomEntry };
+
+    render(
+      <MessageThread
+        executions={[makeExecution({ id: "e1", specMessage: "prompt text" })]}
+        pendingUserMessage="failed follow-up"
+        pendingMessageFailed
+        onRetrySend={vi.fn()}
+        slots={slots}
+      />,
+    );
+
+    const entries = screen.getAllByTestId("custom-entry");
+    // Synthesized human bubble + AI message + the failed pending bubble.
+    expect(entries.length).toBe(3);
+    expect(entries.map((e) => e.textContent)).toContain("failed follow-up");
+    // The built-in bubble chrome must not render.
+    expect(screen.queryByRole("article", { name: "User message" })).toBeNull();
+    // The failed-send Retry affordance stays built-in around the slot.
+    expect(screen.getByRole("button", { name: "Retry" })).toBeTruthy();
+  });
+
+  it("renders the ApprovalCard slot with the row's stabilized onSubmit wiring intact", () => {
+    const onApprovalSubmit = vi.fn();
+    const CustomApproval = ({ pendingApproval, onSubmit }: ApprovalCardProps) => (
+      <button
+        type="button"
+        data-testid="custom-approval"
+        onClick={() => onSubmit(ApprovalAction.APPROVE)}
+      >
+        approve {pendingApproval.toolName}
+      </button>
+    );
+
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            phase: ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+            pendingApprovalToolCallId: "tc-1",
+          }),
+        ]}
+        onApprovalSubmit={onApprovalSubmit}
+        slots={{ ApprovalCard: CustomApproval }}
+      />,
+    );
+
+    fireEvent.click(screen.getByTestId("custom-approval"));
+    // The memoized ApprovalCardRow still injects the toolCallId — the slot's
+    // onSubmit contract is identical to the built-in's.
+    expect(onApprovalSubmit).toHaveBeenCalledWith(
+      "tc-1",
+      ApprovalAction.APPROVE,
+      undefined,
+    );
+  });
+
+  it("renders the TodoCard slot with the TodoRow slot forwarded through its props", () => {
+    const forwarded: Array<TodoRowProps["item"]["content"]> = [];
+    const CustomRow = ({ item }: TodoRowProps) => {
+      forwarded.push(item.content);
+      return <li data-testid="custom-row">{item.content}</li>;
+    };
+    const CustomCard = ({ todos, TodoRow }: TodoCardProps) => (
+      <div data-testid="custom-todo-card">
+        <ul>
+          {Object.values(todos).map((item) =>
+            TodoRow ? <TodoRow key={item.id} item={item} /> : null,
+          )}
+        </ul>
+      </div>
+    );
+
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            todos: { t1: { content: "write tests", status: TodoStatus.TODO_IN_PROGRESS } },
+          }),
+        ]}
+        slots={{ TodoCard: CustomCard, TodoRow: CustomRow }}
+      />,
+    );
+
+    expect(screen.getByTestId("custom-todo-card")).toBeTruthy();
+    expect(forwarded).toEqual(["write tests"]);
+  });
+
+  it("renders the TodoRow slot inside the built-in TodoCard when only TodoRow is overridden", () => {
+    const CustomRow = ({ item }: TodoRowProps) => (
+      <li data-testid="custom-row">ROW: {item.content}</li>
+    );
+
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            todos: { t1: { content: "write tests", status: TodoStatus.TODO_IN_PROGRESS } },
+          }),
+        ]}
+        slots={{ TodoRow: CustomRow }}
+      />,
+    );
+
+    // The built-in card chrome (region + disclosure) hosts the custom row —
+    // auto-disclosure opens the card because an item is in progress.
+    expect(screen.getByRole("region", { name: "Agent to-dos" })).toBeTruthy();
+    expect(screen.getByTestId("custom-row").textContent).toBe("ROW: write tests");
+  });
+
+  it("renders the SetupProgress slot for the pre-first-token window", () => {
+    const CustomSetup = ({ isAwaitingResponse }: SetupProgressProps) => (
+      <div data-testid="custom-setup">{isAwaitingResponse ? "waiting" : "setup"}</div>
+    );
+
+    const exec = makeExecution({
+      id: "e-live",
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+    });
+    // No renderable response yet: the setup-progress item is emitted.
+    exec.status!.messages = [];
+
+    render(
+      <MessageThread
+        executions={[]}
+        activeStreamExecution={exec}
+        slots={{ SetupProgress: CustomSetup }}
+      />,
+    );
+
+    expect(screen.getByTestId("custom-setup").textContent).toBe("waiting");
+  });
+
+  it("renders the PlanCompletionCard slot for an artifact-less completed Plan turn", () => {
+    const CustomCompletion = ({ onImplement }: PlanCompletionCardProps) => (
+      <button type="button" data-testid="custom-completion" onClick={onImplement}>
+        custom build
+      </button>
+    );
+    const onBuildFromPlan = vi.fn();
+
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e-plan",
+            phase: ExecutionPhase.EXECUTION_COMPLETED,
+            interactionMode: InteractionMode.PLAN,
+          }),
+        ]}
+        onBuildFromPlan={onBuildFromPlan}
+        slots={{ PlanCompletionCard: CustomCompletion }}
+      />,
+    );
+
+    fireEvent.click(screen.getByTestId("custom-completion"));
+    expect(onBuildFromPlan).toHaveBeenCalledOnce();
+  });
+
+  it("renders the PlanArtifactCard slot for a completed Plan turn with a published artifact", () => {
+    const CustomArtifact = ({ artifact, title }: PlanArtifactCardProps) => (
+      <div data-testid="custom-artifact">
+        {title ?? "Plan"}: {artifact.name}
+      </div>
+    );
+
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e-plan",
+            phase: ExecutionPhase.EXECUTION_COMPLETED,
+            interactionMode: InteractionMode.PLAN,
+            aiContent: "# Rollout Plan\n\n1. First step",
+            planArtifactName: "rollout_abc123.plan.md",
+          }),
+        ]}
+        onBuildFromPlan={vi.fn()}
+        slots={{ PlanArtifactCard: CustomArtifact }}
+      />,
+    );
+
+    expect(screen.getByTestId("custom-artifact").textContent).toBe(
+      "Rollout Plan: rollout_abc123.plan.md",
+    );
+  });
+
+  it("renders the PlanStreamingCard slot while a plan is being written", () => {
+    const CustomStreaming = ({ title }: PlanStreamingCardProps) => (
+      <div data-testid="custom-streaming">writing: {title}</div>
+    );
+
+    render(
+      <MessageThread
+        executions={[]}
+        activeStreamExecution={makeExecution({
+          id: "e-live",
+          phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+          interactionMode: InteractionMode.PLAN,
+          aiContent: "# Rollout Plan\n\n1. First step",
+        })}
+        onOpenPlan={vi.fn()}
+        slots={{ PlanStreamingCard: CustomStreaming }}
+      />,
+    );
+
+    expect(screen.getByTestId("custom-streaming").textContent).toBe(
+      "writing: Rollout Plan",
+    );
+  });
+
+  // -------------------------------------------------------------------------
+  // Backward compatibility and memo guarantees
+  // -------------------------------------------------------------------------
+
+  it("renders every built-in unchanged when slots is omitted", () => {
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            phase: ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+            todos: { t1: { content: "write tests", status: TodoStatus.TODO_IN_PROGRESS } },
+            pendingApprovalToolCallId: "tc-1",
+          }),
+        ]}
+        onApprovalSubmit={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByRole("article", { name: "User message" })).toBeTruthy();
+    expect(screen.getByRole("region", { name: "Agent to-dos" })).toBeTruthy();
+    expect(
+      screen.getByRole("alert", { name: "Approval required for shell_exec" }),
+    ).toBeTruthy();
+  });
+
+  it("renders slot overrides identically under the virtualized path", async () => {
+    const CustomEntry = ({ message }: MessageEntryProps) => (
+      <div data-testid="custom-entry">{message.content}</div>
+    );
+
+    render(
+      <MessageThread
+        executions={[makeExecution({ id: "e1", specMessage: "prompt text" })]}
+        virtualized
+        slots={{ MessageEntry: CustomEntry }}
+      />,
+    );
+
+    // The lazy VirtualizedThread resolves asynchronously.
+    await vi.waitFor(() => {
+      expect(screen.getByTestId("virtuoso-scroller")).toBeTruthy();
+    });
+    const entries = screen.getAllByTestId("custom-entry");
+    expect(entries.length).toBe(2); // synthesized human bubble + AI message
+    expect(screen.queryByRole("article", { name: "User message" })).toBeNull();
+  });
+
+  it("does not re-render a memoized slot when the thread re-renders with identical data", () => {
+    const renderCount = vi.fn();
+    const CustomCard = memo(function CustomCard({ todos }: TodoCardProps) {
+      renderCount();
+      return <div data-testid="custom-todo-card">{Object.keys(todos).length} todos</div>;
+    });
+    const slots: MessageThreadSlots = { TodoCard: CustomCard };
+
+    const exec = makeExecution({
+      id: "e1",
+      todos: { t1: { content: "write tests", status: TodoStatus.TODO_PENDING } },
+    });
+
+    const { rerender } = render(
+      <MessageThread executions={[exec]} slots={slots} />,
+    );
+    rerender(<MessageThread executions={[exec]} slots={slots} />);
+
+    // Same execution reference, same slots object: the renderer must not
+    // manufacture fresh props that defeat the slot's React.memo (DD-010).
+    expect(renderCount).toHaveBeenCalledTimes(1);
+  });
+});

package/src/execution/file-review-status.ts

@@ -177,6 +177,30 @@ export function changeForRowPath(
   return null;
 }
 
+/**
+ * The captured change a stamped transcript row should render as its inline
+ * diff, or `null` to keep the row's own content view. The row-diff sibling of
+ * {@link fileReviewRowState}: both resolve through {@link changeForRowPath},
+ * so the badge and the diff can never disagree about which file a row refers
+ * to. What renders is the set's captured NET change for the file — the same
+ * artifact the badge's verdict applies to.
+ *
+ * `null` follows the badge's honest-degradation discipline, plus one rule of
+ * its own: a non-`reviewable` change ({@link fileReviewability} — binary,
+ * secret-withheld, size-elided) resolves to `null` so the row falls back to
+ * showing the tool's own args content rather than a diff that cannot honestly
+ * render.
+ */
+export function fileReviewRowChange(
+  set: FileChangeSet | undefined,
+  rowPath: string | null,
+): CapturedFileChange | null {
+  if (!set || !rowPath) return null;
+  const change = changeForRowPath(set, rowPath);
+  if (!change) return null;
+  return fileReviewability(change).kind === "reviewable" ? change : null;
+}
+
 /**
  * The review state a stamped transcript row should badge — how this file edit
  * stands in its change set's review lifecycle. `null` means "show no badge",

package/src/execution/index.ts

@@ -169,7 +169,11 @@ export { MessageEntry } from "./MessageEntry.js";
 export type { MessageEntryProps } from "./MessageEntry.js";
 
 export { MessageThread } from "./MessageThread.js";
-export type { MessageThreadProps, ThreadContentColumn } from "./MessageThread.js";
+export type {
+  MessageThreadProps,
+  MessageThreadSlots,
+  ThreadContentColumn,
+} from "./MessageThread.js";
 
 export { ThreadSkeleton } from "./ThreadSkeleton.js";
 export type { ThreadSkeletonProps } from "./ThreadSkeleton.js";
@@ -182,11 +186,12 @@ export type { ExecutionProgressProps } from "./ExecutionProgress.js";
 
 export {
   TodoList,
+  TodoRow,
   TodoInProgressIcon,
   findActiveTodo,
   todoCompletionSummary,
 } from "./TodoList.js";
-export type { TodoListProps } from "./TodoList.js";
+export type { TodoListProps, TodoRowProps } from "./TodoList.js";
 
 export { TodoCard } from "./TodoCard.js";
 export type { TodoCardProps } from "./TodoCard.js";
@@ -204,6 +209,7 @@ export {
   deriveEffectiveVerdicts,
   changeForRowPath,
   fileReviewRowState,
+  fileReviewRowChange,
 } from "./file-review-status.js";
 export type {
   FileReviewability,
@@ -239,7 +245,11 @@ export type { FileChangeProgressBarProps } from "./FileChangeProgressBar.js";
 export { ApprovalContext, useApproval } from "./ApprovalContext.js";
 export type { ApprovalContextValue, UseApprovalResult } from "./ApprovalContext.js";
 
-export { FileReviewContext, useFileReviewRowState } from "./FileReviewContext.js";
+export {
+  FileReviewContext,
+  useFileReviewRowState,
+  useFileReviewRowChange,
+} from "./FileReviewContext.js";
 export type { FileReviewContextValue } from "./FileReviewContext.js";
 
 export { ArtifactRow } from "./ArtifactRow.js";

package/src/github/__tests__/useGitHubFileReader.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { renderHook } from "@testing-library/react";
 import { useGitHubFileReader } from "../useGitHubFileReader";
+import { WorkspaceFileNotFoundError } from "../../workspace/WorkspaceFileReader";
 import type { WorkspaceEntry } from "../../workspace/useWorkspaceEntries";
 
 function gitEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
@@ -120,11 +121,43 @@ describe("useGitHubFileReader", () => {
     );
   });
 
-  it("throws on a non-OK response (404 = failed to load, not unsupported)", async () => {
+  it("throws the typed WorkspaceFileNotFoundError on a 404", async () => {
     vi.mocked(globalThis.fetch).mockResolvedValue(new Response("nope", { status: 404 }));
 
     const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
-    await expect(result.current!(gitEntry(), "missing.ts")).rejects.toThrow("HTTP 404");
+    await expect(result.current!(gitEntry(), "missing.ts")).rejects.toThrow(
+      WorkspaceFileNotFoundError,
+    );
+  });
+
+  it("throws a generic error (not the typed not-found) on other non-OK responses", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(new Response("boom", { status: 500 }));
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const error = await result.current!(gitEntry(), "src/index.ts").then(
+      () => null,
+      (e: unknown) => e,
+    );
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain("HTTP 500");
+    expect(error).not.toBeInstanceOf(WorkspaceFileNotFoundError);
+  });
+
+  it("reads at readRef in preference to gitBranch when both are set", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      jsonResponse({ encoding: "base64", size: 1, content: b64("x"), sha: "s1" }),
+    );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    await result.current!(
+      gitEntry({ gitBranch: "main", readRef: "abc123def456" }),
+      "notes.md",
+    );
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      expect.stringContaining("?ref=abc123def456"),
+      expect.anything(),
+    );
   });
 
   it("throws when the path is a directory (Contents API returns an array)", async () => {

package/src/github/__tests__/useGitHubTreeLister.test.ts

@@ -148,6 +148,20 @@ describe("useGitHubTreeLister", () => {
     );
   });
 
+  it("lists at readRef in preference to gitBranch when both are set", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      new Response(JSON.stringify(SAMPLE_TREE_RESPONSE), { status: 200 }),
+    );
+
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    await result.current!(gitEntry({ gitBranch: "main", readRef: "abc123def456" }));
+
+    expect(vi.mocked(globalThis.fetch)).toHaveBeenCalledWith(
+      expect.stringContaining("/git/trees/abc123def456?"),
+      expect.anything(),
+    );
+  });
+
   it("encodes branch names with special characters", async () => {
     vi.mocked(globalThis.fetch).mockResolvedValue(
       new Response(JSON.stringify(SAMPLE_TREE_RESPONSE), { status: 200 }),

package/src/github/useGitHubFileReader.ts

@@ -2,9 +2,10 @@
 
 import { useCallback } from "react";
 import type { WorkspaceEntry } from "../workspace/useWorkspaceEntries.js";
-import type {
-  WorkspaceFileContent,
-  WorkspaceFileReader,
+import {
+  WorkspaceFileNotFoundError,
+  type WorkspaceFileContent,
+  type WorkspaceFileReader,
 } from "../workspace/WorkspaceFileReader.js";
 import { base64ToBytes, normalizeGitHubContent } from "./decodeGitHubContent.js";
 import { parseGitUrl } from "./parseGitUrl.js";
@@ -58,7 +59,9 @@ function encodePath(path: string): string {
  *   (non-git entry, missing/unparseable URL) — the "unsupported here" state.
  * - **Throws** on a real failure: a non-OK response, or a directory path
  *   (which the Contents API returns as a JSON array). Consumers surface these
- *   as an error, distinct from the null "unsupported" state.
+ *   as an error, distinct from the null "unsupported" state. A 404 throws the
+ *   typed {@link WorkspaceFileNotFoundError} so consumers can fall back to
+ *   session-captured content for files not yet pushed to the ref.
  *
  * @example
  * ```tsx
@@ -80,14 +83,24 @@ export function useGitHubFileReader(
       const parsed = parseGitUrl(entry.gitUrl);
       if (!parsed) return null;
 
-      const branch = entry.gitBranch || "main";
+      // readRef (the session's write-back commit SHA, when one exists) wins
+      // over the configured branch: agent-created files live on the pushed
+      // write-back commit, not the base branch. The Contents API accepts a
+      // branch name or a commit SHA interchangeably as `ref`.
+      const ref = entry.readRef || entry.gitBranch || "main";
       const url =
         `${GITHUB_API}/${parsed.owner}/${parsed.repo}/contents/${encodePath(path)}` +
-        `?ref=${encodeURIComponent(branch)}`;
+        `?ref=${encodeURIComponent(ref)}`;
 
       const resp = await fetch(url, {
         headers: { Authorization: `Bearer ${token}` },
       });
+      // 404 is typed: a file that isn't at this ref (yet) is an expected,
+      // recoverable state — e.g. an agent-created file whose write-back
+      // hasn't pushed — that consumers handle differently from a failure.
+      if (resp.status === 404) {
+        throw new WorkspaceFileNotFoundError(path);
+      }
       if (!resp.ok) {
         throw new Error(
           `GitHub content fetch failed for ${path} (HTTP ${resp.status})`,