@stigmer/react 3.1.4 → 3.1.6

package/src/session/useWorkspaceReadRefs.ts

@@ -0,0 +1,118 @@
+"use client";
+
+import { useMemo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { WorkspaceEntry } from "../workspace/useWorkspaceEntries.js";
+
+/**
+ * Pure derivation hook that projects the session's workspace write-backs onto
+ * its workspace entries as per-entry read refs.
+ *
+ * The agent's file changes land on a write-back branch (`stigmer/<id>`), not
+ * the branch the session was configured with — so read-side surfaces (file
+ * viewer, tree listing, name search) pointed at the configured branch would
+ * 404 on agent-created files and silently show stale content for modified
+ * ones. This hook returns the entries with `readRef` set to the latest
+ * write-back commit SHA, which those surfaces resolve in preference to
+ * `gitBranch`. A commit SHA (not the branch name) so reads are immutable-ref
+ * exact, immune to branch eventual-consistency.
+ *
+ * **Ref selection:** the latest write-back with a non-empty `commitSha` wins
+ * per workspace entry, across all executions in chronological order. FAILED
+ * write-back records carry no SHA and never regress the ref.
+ *
+ * **Entry matching** mirrors the runner's `WriteBackCoordinator.resolveEntry`:
+ * single-entry sessions provision with an empty `workspaceEntryName`, so when
+ * the session has exactly one git entry every write-back applies to it;
+ * multi-entry sessions match strictly by name.
+ *
+ * **Reference stability (DD-010):** the decorated array is memoized on the
+ * entries array and a value signature of the derived refs — streaming frames
+ * that don't change any write-back SHA return the identical array, so
+ * downstream listing/content effects never churn.
+ *
+ * @param executions - All executions for the session, in chronological order
+ *   (same input contract as {@link useSessionWriteBacks}).
+ * @param entries - The session's workspace entries. Returned as-is (same
+ *   reference) when no entry derives a ref.
+ *
+ * @example
+ * ```tsx
+ * const surfaceEntries = useWorkspaceReadRefs(flow.allExecutions, flow.workspace.entries);
+ * <WorkspaceSurface entries={surfaceEntries} ... />
+ * ```
+ *
+ * @see useSessionWriteBacks — the write-back list this projection derives from
+ * @see WorkspaceEntry.readRef — the field this hook populates
+ */
+export function useWorkspaceReadRefs(
+  executions: readonly AgentExecution[],
+  entries: readonly WorkspaceEntry[],
+): readonly WorkspaceEntry[] {
+  // Cheap per-render pass; memoizing on `executions` would defeat the point —
+  // its identity changes every streaming frame while the SHAs rarely do. The
+  // signature collapses those frames into a stable memo key.
+  const refByName = collectLatestShas(executions);
+  const signature = [...refByName]
+    .map(([name, sha]) => `${name}\u0001${sha}`)
+    .join("\u0000");
+
+  return useMemo(() => {
+    if (refByName.size === 0) return entries;
+
+    const gitEntries = entries.filter((entry) => entry.type === "git");
+    let decorated = false;
+
+    const next = entries.map((entry) => {
+      const readRef = resolveReadRef(entry, gitEntries.length, refByName);
+      if (!readRef || readRef === entry.readRef) return entry;
+      decorated = true;
+      return { ...entry, readRef };
+    });
+
+    return decorated ? next : entries;
+    // `signature` is the value-equality key for `refByName` (rebuilt each
+    // render); the map itself must stay out of the deps.
+  }, [entries, signature]);
+}
+
+/** Latest non-empty write-back commit SHA per workspace entry name. */
+function collectLatestShas(
+  executions: readonly AgentExecution[],
+): Map<string, string> {
+  const refByName = new Map<string, string>();
+  for (const execution of executions) {
+    for (const wb of execution.status?.workspaceWriteBacks ?? []) {
+      if (wb.commitSha) refByName.set(wb.workspaceEntryName, wb.commitSha);
+    }
+  }
+  return refByName;
+}
+
+/**
+ * The write-back SHA for one entry, honoring the runner's single-entry
+ * convention: with exactly one git entry, any write-back applies to it
+ * (single-entry sessions write back under an empty entry name).
+ */
+function resolveReadRef(
+  entry: WorkspaceEntry,
+  gitEntryCount: number,
+  refByName: ReadonlyMap<string, string>,
+): string | undefined {
+  if (entry.type !== "git") return undefined;
+
+  const byName = refByName.get(entry.name);
+  if (byName) return byName;
+
+  if (gitEntryCount === 1) {
+    // Single-entry sessions write back under an empty entry name; a lone
+    // unambiguous name is equally safe to claim. Anything else (multiple
+    // names against one entry) is malformed status data — decorate nothing
+    // rather than guess.
+    const unnamed = refByName.get("");
+    if (unnamed) return unnamed;
+    if (refByName.size === 1) return refByName.values().next().value;
+  }
+
+  return undefined;
+}

package/src/workflow/picker/__tests__/recents.test.ts

@@ -81,10 +81,10 @@ describe("TaskKindRecentsStore", () => {
 
   it("filters out invalid entries from localStorage", () => {
     const data = [
-      { kind: "valid_kind", timestamp: Date.now() },
-      { kind: 123, timestamp: Date.now() }, // invalid: kind is not string
-      { timestamp: Date.now() }, // invalid: missing kind
-      { kind: "another_valid", timestamp: Date.now() },
+      { kind: "valid_kind", timestamp: 2 },
+      { kind: 123, timestamp: 3 }, // invalid: kind is not string
+      { timestamp: 4 }, // invalid: missing kind
+      { kind: "another_valid", timestamp: 1 },
     ];
     globalThis.localStorage.setItem(TEST_KEY, JSON.stringify(data));
 

package/src/workspace/FileViewer.tsx

@@ -11,14 +11,21 @@ import {
 } from "react";
 import { cn } from "@stigmer/theme";
 import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-import { FileChangeType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  FileChangeCaptureLevel,
+  FileChangeType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { ArtifactContentRenderer } from "../execution/ArtifactContentRenderer.js";
 import { FileChangeDiff } from "../execution/FileChangesView.js";
+import { useFileChangeContent } from "../execution/useFileChangeContent.js";
 import type { RevealTarget } from "../internal/useRevealLine.js";
 import type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
 import { useWorkspaceFileContent } from "./useWorkspaceFileContent.js";
 import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
-import type { WorkspaceFileReader } from "./WorkspaceFileReader.js";
+import {
+  WorkspaceFileNotFoundError,
+  type WorkspaceFileReader,
+} from "./WorkspaceFileReader.js";
 
 /** Line-skeleton widths, mirroring `FileContentStateView` in `ArtifactPreviewModal`. */
 const SKELETON_LINE_WIDTHS = [85, 72, 90, 65, 78, 88, 70, 82] as const;
@@ -218,22 +225,16 @@ export const FileViewer = forwardRef<FileViewerHandle, FileViewerProps>(
             <FileChangeDiff change={change} showFileName={false} showStats />
           </div>
         ) : (
-          <>
-            {change && (
-              <p className="border-b border-border-muted px-4 py-1.5 text-[0.65rem] text-muted-foreground">
-                Live — may differ from the reviewed change.
-              </p>
-            )}
-            <FileViewerBody
-              basename={basename}
-              content={content}
-              isLoading={isLoading}
-              isUnsupported={isUnsupported}
-              error={error}
-              onRetry={refetch}
-              reveal={reveal}
-            />
-          </>
+          <FileViewerBody
+            basename={basename}
+            content={content}
+            isLoading={isLoading}
+            isUnsupported={isUnsupported}
+            error={error}
+            onRetry={refetch}
+            reveal={reveal}
+            change={change}
+          />
         )}
       </div>
     </div>
@@ -328,6 +329,23 @@ function ViewerModeToggle({
 // Body — exactly one state, mirroring FileContentStateView + workspace extras
 // ---------------------------------------------------------------------------
 
+/**
+ * Whether the session captured this change's full after-content — the
+ * precondition for serving it when the live substrate can't (a cloud file not
+ * yet pushed to any readable ref). A DELETE has no after side, and a
+ * HUNK_ONLY capture carries only the diff, never the whole file.
+ */
+function hasCapturedAfterContent(
+  change: FileChange | undefined,
+): change is FileChange {
+  return (
+    change !== undefined &&
+    change.changeType !== FileChangeType.DELETE &&
+    change.captureLevel !== FileChangeCaptureLevel.HUNK_ONLY &&
+    change.after !== undefined
+  );
+}
+
 function FileViewerBody({
   basename,
   content,
@@ -336,6 +354,7 @@ function FileViewerBody({
   error,
   onRetry,
   reveal,
+  change,
 }: {
   readonly basename: string;
   readonly content: ReturnType<typeof useWorkspaceFileContent>["content"];
@@ -344,7 +363,20 @@ function FileViewerBody({
   readonly error: Error | null;
   readonly onRetry: () => void;
   readonly reveal?: RevealTarget;
+  readonly change?: FileChange;
 }) {
+  // A live read that can't be served (unsupported substrate, or the file
+  // isn't at the read ref yet) degrades to the session's captured
+  // after-content when the change carries it — the same bytes the Diff view
+  // renders, so nothing is fabricated. Other errors keep the retry path.
+  const isNotFound = error instanceof WorkspaceFileNotFoundError;
+  const canFallBackToCaptured =
+    (isUnsupported || isNotFound) && hasCapturedAfterContent(change);
+
+  if (canFallBackToCaptured) {
+    return <CapturedFileContent change={change} basename={basename} reveal={reveal} />;
+  }
+
   // Unsupported comes first: a missing reader means there is nothing to load.
   if (isUnsupported) {
     return (
@@ -355,21 +387,25 @@ function FileViewerBody({
   }
 
   if (isLoading) {
+    return <LoadingSkeleton />;
+  }
+
+  if (isNotFound) {
+    // Expected while the agent's write-back is still syncing to the ref —
+    // a calm notice (DD-006), not a failure.
     return (
-      <div
-        role="status"
-        className="space-y-2 p-4"
-        aria-busy="true"
-        aria-label="Loading file"
-      >
-        {SKELETON_LINE_WIDTHS.map((width, i) => (
-          <div
-            key={i}
-            className="h-4 animate-pulse rounded bg-muted"
-            style={{ width: `${width}%` }}
-            aria-hidden="true"
-          />
-        ))}
+      <div className="flex flex-col items-center justify-center gap-2 p-8 text-center">
+        <p className="text-xs text-muted-foreground">
+          This file isn&rsquo;t available in the workspace source yet. The
+          agent&rsquo;s latest changes may still be syncing.
+        </p>
+        <button
+          type="button"
+          onClick={onRetry}
+          className="text-xs font-medium text-foreground underline underline-offset-2 hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:rounded-sm"
+        >
+          Check again
+        </button>
       </div>
     );
   }
@@ -417,12 +453,82 @@ function FileViewerBody({
   }
 
   return (
-    <ArtifactContentRenderer
-      content={content.text}
-      fileName={basename}
-      isTruncated={content.truncated}
-      reveal={reveal}
-    />
+    <>
+      {change && (
+        <p className="border-b border-border-muted px-4 py-1.5 text-[0.65rem] text-muted-foreground">
+          Live — may differ from the reviewed change.
+        </p>
+      )}
+      <ArtifactContentRenderer
+        content={content.text}
+        fileName={basename}
+        isTruncated={content.truncated}
+        reveal={reveal}
+      />
+    </>
+  );
+}
+
+/**
+ * The captured-content fallback: renders a change's after-side text (the
+ * bytes the session already holds — inline or offloaded to artifact storage)
+ * when no live substrate can serve the file. Mounted only when eligible, so
+ * its content fetch never runs for live-served files.
+ */
+function CapturedFileContent({
+  change,
+  basename,
+  reveal,
+}: {
+  readonly change: FileChange;
+  readonly basename: string;
+  readonly reveal?: RevealTarget;
+}) {
+  const { afterText, isBinary, isLoading, error } = useFileChangeContent(change);
+
+  if (isLoading) {
+    return <LoadingSkeleton />;
+  }
+
+  if (isBinary) {
+    return <MessageState>Binary file — not shown.</MessageState>;
+  }
+
+  if (error || afterText === null) {
+    return <MessageState>Content not available for preview.</MessageState>;
+  }
+
+  return (
+    <>
+      <p className="border-b border-border-muted px-4 py-1.5 text-[0.65rem] text-muted-foreground">
+        As of the agent&rsquo;s last change — not yet in the workspace source.
+      </p>
+      <ArtifactContentRenderer
+        content={afterText}
+        fileName={basename}
+        reveal={reveal}
+      />
+    </>
+  );
+}
+
+function LoadingSkeleton() {
+  return (
+    <div
+      role="status"
+      className="space-y-2 p-4"
+      aria-busy="true"
+      aria-label="Loading file"
+    >
+      {SKELETON_LINE_WIDTHS.map((width, i) => (
+        <div
+          key={i}
+          className="h-4 animate-pulse rounded bg-muted"
+          style={{ width: `${width}%` }}
+          aria-hidden="true"
+        />
+      ))}
+    </div>
   );
 }
 

package/src/workspace/WorkspaceFileReader.ts

@@ -32,6 +32,25 @@ export interface WorkspaceFileContent {
   readonly truncated?: boolean;
 }
 
+/**
+ * Thrown by a {@link WorkspaceFileReader} when the requested path does not
+ * exist at the entry's read ref — as opposed to a transport or permission
+ * failure.
+ *
+ * The distinction matters to consumers: a file the agent just created exists
+ * in session state before it exists at any readable ref, so "not found" is a
+ * recoverable, expected condition (the viewer falls back to the session's
+ * captured content), while a network error or 5xx is a genuine failure worth
+ * a retry affordance. Platform builders implementing custom readers should
+ * throw this class for their substrate's not-found condition.
+ */
+export class WorkspaceFileNotFoundError extends Error {
+  constructor(path: string) {
+    super(`"${path}" doesn't exist at the workspace's current ref.`);
+    this.name = "WorkspaceFileNotFoundError";
+  }
+}
+
 /**
  * Platform-injected callback that reads the content of a single workspace file.
  *
@@ -46,6 +65,8 @@ export interface WorkspaceFileContent {
  * - **Throws** on a genuine failure (404, network error, 5xx, unreadable file,
  *   a directory path). Consumers catch this into a distinct error state — a
  *   clicked file that 404s is "failed to load," not "unsupported here."
+ *   A missing path should throw {@link WorkspaceFileNotFoundError} so
+ *   consumers can distinguish "not there yet" from "broken."
  *
  * `path` is repo-relative for git entries and root-relative for local entries —
  * exactly the strings the matching `WorkspaceFileLister` emits, so a file-tree

package/src/workspace/__tests__/FileViewer.test.tsx

@@ -34,9 +34,10 @@ beforeEach(() => {
   };
 });
 import type { WorkspaceEntry } from "../useWorkspaceEntries";
-import type {
-  WorkspaceFileContent,
-  WorkspaceFileReader,
+import {
+  WorkspaceFileNotFoundError,
+  type WorkspaceFileContent,
+  type WorkspaceFileReader,
 } from "../WorkspaceFileReader";
 
 function wholeFileChange(path: string): FileChange {
@@ -346,6 +347,140 @@ describe("FileViewer — diff mode", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Not-found fallback — captured content when the live substrate lacks the file
+// ---------------------------------------------------------------------------
+
+describe("FileViewer — not-found and captured-content fallback", () => {
+  function notFoundReader(): WorkspaceFileReader {
+    return vi.fn(async (_e, path: string) => {
+      throw new WorkspaceFileNotFoundError(path);
+    });
+  }
+
+  it("falls back to the captured after-content when the file isn't at the ref", async () => {
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={notFoundReader()}
+        change={wholeFileChange("notes.md")}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: "File" }));
+
+    // The captured after side ("beta") renders with the provenance caption —
+    // not an error, not the live caption.
+    await waitFor(() =>
+      expect(screen.getByText(/As of the agent.s last change/i)).toBeTruthy(),
+    );
+    expect(screen.getByText("beta")).toBeTruthy();
+    expect(screen.queryByText("Retry")).toBeNull();
+    expect(screen.queryByText(/Live — may differ/i)).toBeNull();
+  });
+
+  it("falls back to captured content when the substrate is unsupported (reader resolves null)", async () => {
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={readerFor(null)}
+        change={wholeFileChange("notes.md")}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: "File" }));
+
+    await waitFor(() =>
+      expect(screen.getByText(/As of the agent.s last change/i)).toBeTruthy(),
+    );
+    expect(screen.getByText("beta")).toBeTruthy();
+  });
+
+  it("shows the calm not-found state (no error styling) when nothing is captured", async () => {
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={notFoundReader()}
+      />,
+    );
+
+    await waitFor(() =>
+      expect(screen.getByText(/isn.t available in the workspace source yet/i)).toBeTruthy(),
+    );
+    // A calm notice, not a failure: retry is offered as "Check again".
+    expect(screen.getByText("Check again")).toBeTruthy();
+    expect(screen.queryByText("Retry")).toBeNull();
+  });
+
+  it("Check again re-reads and renders content once the file lands at the ref", async () => {
+    let attempt = 0;
+    const reader: WorkspaceFileReader = vi.fn(async (_e, path: string) => {
+      attempt += 1;
+      if (attempt === 1) throw new WorkspaceFileNotFoundError(path);
+      return text("now it exists");
+    });
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={reader}
+      />,
+    );
+
+    await waitFor(() => expect(screen.getByText("Check again")).toBeTruthy());
+    fireEvent.click(screen.getByText("Check again"));
+
+    await waitFor(() => expect(screen.getByText("now it exists")).toBeTruthy());
+  });
+
+  it("keeps the not-found state calm for a HUNK_ONLY change (no whole-file capture to serve)", async () => {
+    const hunkOnly = create(FileChangeSchema, {
+      path: "notes.md",
+      changeType: FileChangeType.MODIFY,
+      captureLevel: FileChangeCaptureLevel.HUNK_ONLY,
+      unifiedDiff: "@@ -1 +1 @@\n-alpha\n+beta\n",
+    });
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={notFoundReader()}
+        change={hunkOnly}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: "File" }));
+
+    await waitFor(() =>
+      expect(screen.getByText(/isn.t available in the workspace source yet/i)).toBeTruthy(),
+    );
+    expect(screen.queryByText(/As of the agent.s last change/i)).toBeNull();
+  });
+
+  it("a generic reader error still shows the error state with Retry, never the fallback", async () => {
+    const reader: WorkspaceFileReader = vi.fn(async () => {
+      throw new Error("rate limited (HTTP 429)");
+    });
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "notes.md" }}
+        entries={ENTRIES}
+        reader={reader}
+        change={wholeFileChange("notes.md")}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: "File" }));
+
+    await waitFor(() => expect(screen.getByText(/rate limited/i)).toBeTruthy());
+    expect(screen.getByText("Retry")).toBeTruthy();
+    expect(screen.queryByText(/As of the agent.s last change/i)).toBeNull();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Reveal (jump-to-line) — a line target opens File view and scrolls to it
 // ---------------------------------------------------------------------------

package/src/workspace/__tests__/useWorkspaceFileContent.test.tsx

@@ -172,6 +172,26 @@ describe("useWorkspaceFileContent", () => {
     expect(result.current.content?.text).toBe("FAST");
   });
 
+  it("re-reads when the entry's readRef advances (same id, new write-back push)", async () => {
+    const reader: WorkspaceFileReader = vi.fn(async (e) =>
+      textContent(`at:${e.readRef ?? e.gitBranch}`),
+    );
+    const { result, rerender } = renderHook(
+      (props: { entry: WorkspaceEntry }) =>
+        useWorkspaceFileContent({ entry: props.entry, path: "notes.md", reader }),
+      { initialProps: { entry: gitEntry() } },
+    );
+
+    await waitFor(() => expect(result.current.content?.text).toBe("at:main"));
+
+    // A write-back push advances readRef while entry.id stays stable — the
+    // same path at a new ref is different content and must be re-read.
+    rerender({ entry: { ...gitEntry(), readRef: "sha-2" } });
+
+    await waitFor(() => expect(result.current.content?.text).toBe("at:sha-2"));
+    expect(reader).toHaveBeenCalledTimes(2);
+  });
+
   it("goes idle when the entry is removed (entry -> null)", async () => {
     const reader: WorkspaceFileReader = vi.fn(async () => textContent("x"));
     const { result, rerender } = renderHook(