@stigmer/react 3.1.4 → 3.1.5

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(

package/src/workspace/__tests__/workspaceListingCache.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { WorkspaceEntry } from "../useWorkspaceEntries";
+import type { WorkspaceFileEntry, WorkspaceFileLister } from "../WorkspaceFileLister";
+import {
+  loadEntryFiles,
+  peekEntryListing,
+  __clearWorkspaceListingCache,
+} from "../workspaceListingCache";
+
+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 listerFor(files: readonly WorkspaceFileEntry[]): WorkspaceFileLister {
+  return vi.fn(async () => [...files]);
+}
+
+describe("workspaceListingCache", () => {
+  beforeEach(() => {
+    __clearWorkspaceListingCache();
+  });
+
+  it("caches a listing and serves it without re-calling the lister", async () => {
+    const lister = listerFor([{ path: "a.ts", isDirectory: false }]);
+    const entry = gitEntry();
+
+    await loadEntryFiles(entry, lister);
+    await loadEntryFiles(entry, lister);
+
+    expect(lister).toHaveBeenCalledTimes(1);
+    expect(peekEntryListing(entry)?.files).toHaveLength(1);
+  });
+
+  it("treats a readRef advance as a different listing (stale-tree regression)", async () => {
+    // The write-back pushed a commit that added notes.md; the pre-push listing
+    // must not be served for the post-push ref.
+    const prePush = gitEntry(); // reads at gitBranch
+    const postPush = gitEntry({ readRef: "sha-after-push" });
+
+    const lister = vi.fn(async (entry: WorkspaceEntry) =>
+      entry.readRef
+        ? [
+            { path: "a.ts", isDirectory: false },
+            { path: "notes.md", isDirectory: false },
+          ]
+        : [{ path: "a.ts", isDirectory: false }],
+    );
+
+    const before = await loadEntryFiles(prePush, lister);
+    expect(before?.files.map((f) => f.path)).toEqual(["a.ts"]);
+
+    // Same entry.id, advanced ref — must re-fetch, not serve the stale tree.
+    const after = await loadEntryFiles(postPush, lister);
+    expect(lister).toHaveBeenCalledTimes(2);
+    expect(after?.files.map((f) => f.path)).toContain("notes.md");
+
+    // Both snapshots remain independently peekable at their own refs.
+    expect(peekEntryListing(prePush)?.files).toHaveLength(1);
+    expect(peekEntryListing(postPush)?.files).toHaveLength(2);
+  });
+
+  it("keys by entry id as well — two entries at the same ref never collide", async () => {
+    const one = gitEntry({ id: "ws-1" });
+    const two = gitEntry({ id: "ws-2", name: "acme/web", gitUrl: "https://github.com/acme/web" });
+
+    await loadEntryFiles(one, listerFor([{ path: "one.ts", isDirectory: false }]));
+    await loadEntryFiles(two, listerFor([{ path: "two.ts", isDirectory: false }]));
+
+    expect(peekEntryListing(one)?.files[0].path).toBe("one.ts");
+    expect(peekEntryListing(two)?.files[0].path).toBe("two.ts");
+  });
+
+  it("bustCache re-calls the lister for the same entry and ref", async () => {
+    const lister = listerFor([{ path: "a.ts", isDirectory: false }]);
+    const entry = gitEntry();
+
+    await loadEntryFiles(entry, lister);
+    await loadEntryFiles(entry, lister, { bustCache: true });
+
+    expect(lister).toHaveBeenCalledTimes(2);
+  });
+
+  it("never caches a null (unsupported) result", async () => {
+    const lister: WorkspaceFileLister = vi.fn(async () => null);
+    const entry = gitEntry();
+
+    expect(await loadEntryFiles(entry, lister)).toBeNull();
+    expect(peekEntryListing(entry)).toBeUndefined();
+
+    // A later, supporting lister must get its chance.
+    await loadEntryFiles(entry, listerFor([{ path: "a.ts", isDirectory: false }]));
+    expect(peekEntryListing(entry)?.files).toHaveLength(1);
+  });
+
+  it("collapses advisory notice entries into the truncated flag", async () => {
+    const lister = listerFor([
+      { path: "a.ts", isDirectory: false },
+      { path: "... (tree truncated)", isDirectory: false, notice: true },
+    ]);
+    const entry = gitEntry();
+
+    const listing = await loadEntryFiles(entry, lister);
+
+    expect(listing?.truncated).toBe(true);
+    expect(listing?.files.map((f) => f.path)).toEqual(["a.ts"]);
+  });
+});

package/src/workspace/index.ts

@@ -7,7 +7,10 @@ export type {
   WorkspaceFileEntry,
   WorkspaceFileLister,
 } from "./WorkspaceFileLister.js";
-export { MAX_WORKSPACE_FILE_READ_BYTES } from "./WorkspaceFileReader.js";
+export {
+  MAX_WORKSPACE_FILE_READ_BYTES,
+  WorkspaceFileNotFoundError,
+} from "./WorkspaceFileReader.js";
 export type {
   WorkspaceFileContent,
   WorkspaceFileReader,

package/src/workspace/useWorkspaceEntries.ts

@@ -33,6 +33,17 @@ export interface WorkspaceEntry {
   readonly gitUrl?: string;
   /** Branch to clone. Set when `type` is `"git"`. */
   readonly gitBranch?: string;
+  /**
+   * The git ref (branch or commit SHA) at which read-side operations —
+   * file content, tree listing, name search — resolve. Defaults to
+   * `gitBranch` when absent.
+   *
+   * Never user-configured: a session derives it from the latest workspace
+   * write-back so viewers read the agent's pushed commit instead of the
+   * stale base branch (see `useWorkspaceReadRefs`). A read-side projection
+   * only — never persisted, never part of the session input.
+   */
+  readonly readRef?: string;
   /** Absolute filesystem path. Set when `type` is `"local"`. */
   readonly localPath?: string;
 }

package/src/workspace/useWorkspaceFileContent.ts

@@ -105,7 +105,10 @@ export function useWorkspaceFileContent({
         ? () => reader(entry, path).then((c) => ({ content: c }))
         : null,
       // Identity deps: a change to any of these is a different file to read.
-      [entry?.id ?? null, path ?? null, reader],
+      // The read ref participates because the same path at a different ref is
+      // different content — a write-back push advances `readRef` while
+      // `entry.id` stays stable.
+      [entry?.id ?? null, entry?.readRef ?? null, path ?? null, reader],
       EMPTY_CONTENT,
     );
 

package/src/workspace/useWorkspaceFileSearch.ts

@@ -82,11 +82,16 @@ export function useWorkspaceFileSearch({
 }: UseWorkspaceFileSearchOptions): UseWorkspaceFileSearchReturn {
   const [states, setStates] = useState<Record<string, EntryListingState>>({});
 
-  // Latest entries read inside the effect without widening its dependency to the
-  // (possibly per-render) array identity — the effect keys on the id set instead.
+  // Latest entries read inside the effect without widening its dependency to
+  // the (possibly per-render) array identity — the effect keys on the set of
+  // (id, readRef) pairs instead. The ref participates because a listing is a
+  // snapshot of one ref: when a write-back advances an entry's readRef, its
+  // listing must be re-fetched even though the id set is unchanged.
   const entriesRef = useRef(entries);
   entriesRef.current = entries;
-  const entriesKey = entries.map((entry) => entry.id).join("\u0000");
+  const entriesKey = entries
+    .map((entry) => `${entry.id}\u0001${entry.readRef ?? ""}`)
+    .join("\u0000");
 
   // Ignore resolutions from a superseded entry set (id set or lister changed).
   const generationRef = useRef(0);

package/src/workspace/useWorkspaceFiles.ts

@@ -43,7 +43,8 @@ const EMPTY_TREE: readonly TreeNode[] = [];
  *   {@link loadEntryFiles} cache) when the
  *   entry changes.
  * - Reads the shared listing cache so tab switches, re-expands, and the search
- *   surface are instant without re-fetching (one cache, keyed by `entry.id`).
+ *   surface are instant without re-fetching (one cache, keyed by `entry.id` +
+ *   effective read ref — a ref advance is a cache miss by design).
  * - Returns an empty tree and skips the call when `lister` is
  *   `undefined` (graceful degradation — DD-011 opt-in).
  * - Memoizes the return value for referential stability (DD-010).
@@ -72,7 +73,7 @@ export function useWorkspaceFiles({
       if (!lister) return;
 
       if (!bustCache) {
-        const cached = peekEntryListing(target.id);
+        const cached = peekEntryListing(target);
         if (cached) {
           setTree(cached.tree);
           setTruncated(cached.truncated);