@stigmer/react 3.0.9-dev.20260616060535 → 3.1.0

package/src/internal/useKeyedSubmission.ts

@@ -0,0 +1,101 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { toError } from "./toError";
+
+/** A stable empty set so an idle hook keeps a constant `submittingKeys` ref. */
+const NO_KEYS: ReadonlySet<string> = new Set();
+/** A stable empty map so an error-free hook keeps a constant `errorsByKey` ref. */
+const NO_ERRORS: ReadonlyMap<string, Error> = new Map();
+
+/** Return value of {@link useKeyedSubmission}. */
+export interface KeyedSubmission<T> {
+  /**
+   * Keys whose operation is currently in flight. A consumer reads
+   * `submittingKeys.has(key)` to drive per-target loading state when several
+   * operations of the same kind can run at once.
+   */
+  readonly submittingKeys: ReadonlySet<string>;
+  /**
+   * Per-key failures, keyed exactly like {@link submittingKeys}. A consumer
+   * reads `errorsByKey.get(key)` to surface the failure beside the one control
+   * it belongs to — a single scalar cannot say which of several concurrent
+   * operations failed. Cleared for a key when that key is retried.
+   */
+  readonly errorsByKey: ReadonlyMap<string, Error>;
+  /**
+   * Run `fn` under the bookkeeping for `key`: clear the key's prior error,
+   * mark it in flight, await, and release it. On failure the error is recorded
+   * in {@link errorsByKey} and then **re-thrown** — the primitive never decides
+   * how the failure propagates, so each caller chooses (mirror to a scalar and
+   * rethrow, swallow to a sentinel, etc.).
+   */
+  readonly run: (key: string, fn: () => Promise<T>) => Promise<T>;
+  /** Reset every recorded error. In-flight tracking is untouched. */
+  readonly clearErrors: () => void;
+}
+
+/**
+ * Tracks per-key in-flight and error state for a family of concurrent async
+ * operations that share one identity space (e.g. approval decisions keyed by
+ * tool-call id, or by task name).
+ *
+ * This is the shared substrate behind every "many gates at once" surface: a
+ * thread or a workflow can hold several pending decisions simultaneously, so a
+ * failure (and the spinner) must be attributable to the *one* gate it belongs
+ * to. A single scalar `error`/`isSubmitting` pair cannot do that; a keyed
+ * `Set`/`Map` pair can. Singleton controls (a header's cancel/pause) do not
+ * need this — they correctly share one scalar.
+ *
+ * `run` re-throws after recording so the propagation policy stays with the
+ * caller: {@link useSubmitApproval} mirrors the failure to a scalar and
+ * rethrows; {@link useWorkflowExecutionActions} swallows it to `null`.
+ *
+ * The return is `useMemo`'d over stable parts (empty-collection sentinels keep
+ * the idle refs constant) so it is safe as a `React.memo` dependency (DD-010).
+ *
+ * @internal Not part of the public API.
+ */
+export function useKeyedSubmission<T = void>(): KeyedSubmission<T> {
+  const [submittingKeys, setSubmittingKeys] =
+    useState<ReadonlySet<string>>(NO_KEYS);
+  const [errorsByKey, setErrorsByKey] =
+    useState<ReadonlyMap<string, Error>>(NO_ERRORS);
+
+  const clearErrors = useCallback(() => setErrorsByKey(NO_ERRORS), []);
+
+  const run = useCallback(async (key: string, fn: () => Promise<T>): Promise<T> => {
+    setSubmittingKeys((prev) => {
+      const next = new Set(prev);
+      next.add(key);
+      return next;
+    });
+    // Clear this key's prior failure so a retry starts clean.
+    setErrorsByKey((prev) => {
+      if (!prev.has(key)) return prev;
+      const next = new Map(prev);
+      next.delete(key);
+      return next;
+    });
+
+    try {
+      return await fn();
+    } catch (err) {
+      const e = toError(err);
+      setErrorsByKey((prev) => new Map(prev).set(key, e));
+      throw err;
+    } finally {
+      setSubmittingKeys((prev) => {
+        if (!prev.has(key)) return prev;
+        const next = new Set(prev);
+        next.delete(key);
+        return next;
+      });
+    }
+  }, []);
+
+  return useMemo(
+    () => ({ submittingKeys, errorsByKey, run, clearErrors }),
+    [submittingKeys, errorsByKey, run, clearErrors],
+  );
+}

package/src/session/SessionViewer.tsx

@@ -12,6 +12,7 @@ import { SelectionStore } from "../internal/store/selection-store";
 import { ThreadSelectionContext } from "../execution/ThreadSelectionContext";
 import { useSelectedThreadItem } from "../execution/useThreadSelection";
 import { MessageThread } from "../execution/MessageThread";
+import { FileReviewDock } from "../execution/FileReviewDock";
 import { ThreadSkeleton } from "../execution/ThreadSkeleton";
 import { SessionComposer } from "../composer";
 import { SecretFlowErrorGuide, isSecretFlowError } from "../error";
@@ -109,8 +110,8 @@ export interface SessionViewerProps {
  * Owns `useSessionPageFlow` internally and composes:
  * - **Conversation column** (primary): `MessageThread` + error
  *   banners + `SessionComposer`
- * - **SessionInspector** (secondary): tabbed panel with Plan,
- *   Changes, Artifacts, Usage, and Inspect facets
+ * - **SessionInspector** (secondary): tabbed panel with Workspace,
+ *   Config, Changes, Artifacts, Usage, and Inspect facets
  *
  * Connected via `ResizableSplit` with persisted width.
  *
@@ -288,8 +289,12 @@ function ConversationColumn({
   isEndUser,
 }: ConversationColumnProps) {
   const { conv } = flow;
-  const sendError =
-    flow.submitError ?? conv.sendError ?? conv.approvalError ?? conv.stopError;
+  // Approval failures are NOT folded into this banner: they now surface in-card,
+  // beside the exact gate that failed (see MessageThread's approvalErrors →
+  // ApprovalCard), matching the file-review card. A single banner cannot name
+  // which of several concurrent gates failed. The scalar conv.approvalError
+  // stays available for headless/`ink` consumers.
+  const sendError = flow.submitError ?? conv.sendError ?? conv.stopError;
 
   // Retry a terminal-failed execution by resending its originating message
   // through the full submit pipeline (agent override, runtime-env, workspace).
@@ -331,6 +336,8 @@ function ConversationColumn({
         onRetryExecution={onRetryExecution}
         onApprovalSubmit={flow.submitApproval}
         submittingApprovalIds={conv.submittingApprovalIds}
+        approvalErrors={conv.approvalErrors}
+        showFileReviewRecords
         onEditMessage={conv.isStoppable ? handleEditMessage : undefined}
         workspaceEntries={conv.workspaceEntries}
         sandboxWorkspaceRoot={flow.sandboxWorkspaceRoot}
@@ -356,6 +363,16 @@ function ConversationColumn({
         {flow.autoApproveAll && (
           <AutoApproveIndicator onTurnOff={() => flow.setAutoApproveAll(false)} />
         )}
+        {/* Pending file reviews dock here — pinned above the composer so the
+            decision the agent is blocked on can never scroll out of view. The
+            thread renders only observational rows (badges) and read-only
+            settled records; this is the one decision surface. */}
+        <FileReviewDock
+          changeSets={conv.fileChangeSets}
+          onSubmit={conv.submitFileDecision}
+          submittingDecisionKeys={conv.submittingFileDecisionKeys}
+          decisionErrors={conv.fileDecisionErrors}
+        />
         <SessionComposer
           ref={composerRef}
           onSubmit={flow.handleSubmit}

package/src/session/__tests__/SessionViewer-fileReviewDock.test.tsx

@@ -0,0 +1,198 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  CapturedFileChangeSchema,
+  FileChangeSetSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { FileContentSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  DiffCompleteness,
+  FileChangeKind,
+  FileChangeSetStatus,
+  FileDecisionAction,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+// ---------------------------------------------------------------------------
+// Wiring-contract tests for the file-review surfaces on SessionViewer:
+// the pending decision bar renders in the composer-docked FileReviewDock
+// (fed from conv's seam), and the thread is records-only
+// (`showFileReviewRecords`, no decision callbacks). The dock renders REAL —
+// it is the subject; the thread/composer/inspector are prop-capturing probes.
+// ---------------------------------------------------------------------------
+
+type CapturedProps = Record<string, unknown>;
+
+const threadProps: CapturedProps[] = [];
+vi.mock("../../execution/MessageThread", () => ({
+  MessageThread: (props: CapturedProps) => {
+    threadProps.push(props);
+    return <div data-testid="thread-probe" />;
+  },
+}));
+
+vi.mock("../../composer", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../composer")>();
+  return {
+    ...actual,
+    SessionComposer: () => <div data-testid="composer-probe" />,
+  };
+});
+
+vi.mock("../inspector/SessionInspector", () => ({
+  SessionInspector: () => <div data-testid="inspector-probe" />,
+}));
+
+const stubWorkspace = {
+  entries: [],
+  hasEntries: false,
+  toInput: vi.fn().mockReturnValue([]),
+  addGitRepo: vi.fn(),
+  addLocalPath: vi.fn(),
+  removeEntry: vi.fn(),
+  clear: vi.fn(),
+};
+
+function pendingChangeSet(id: string) {
+  return create(FileChangeSetSchema, {
+    id,
+    status: FileChangeSetStatus.AWAITING_REVIEW,
+    aggregateDigest: `agg-${id}`,
+    diffCompleteness: DiffCompleteness.COMPLETE,
+    changes: [
+      create(CapturedFileChangeSchema, {
+        id: `${id}:notes.md`,
+        pathBefore: "notes.md",
+        pathAfter: "notes.md",
+        kind: FileChangeKind.ADD,
+        before: create(FileContentSchema, { body: { case: "inline", value: "" } }),
+        after: create(FileContentSchema, { body: { case: "inline", value: "# Notes\n" } }),
+        fileDigest: "d-notes",
+        diffComplete: true,
+      }),
+    ],
+  });
+}
+
+const stubConv = {
+  session: { spec: {} },
+  isLoading: false,
+  loadError: null,
+  completedExecutions: [],
+  activeStreamExecution: null,
+  activePhase: null,
+  isStreaming: false,
+  isConnecting: false,
+  sendFollowUp: vi.fn(),
+  canSendFollowUp: true,
+  isSending: false,
+  sendError: null,
+  clearSendError: vi.fn(),
+  pendingUserMessage: null,
+  workspaceEntries: [],
+  mcpServerUsages: [],
+  skillRefs: [],
+  pendingApprovals: [],
+  submitApproval: vi.fn(),
+  submittingApprovalIds: new Set<string>(),
+  fileChangeSets: [] as ReturnType<typeof pendingChangeSet>[],
+  submitFileDecision: vi.fn(),
+  submittingFileDecisionKeys: new Set<string>(),
+  fileDecisionErrors: new Map<string, Error>(),
+  streamError: null,
+  reconnectStream: vi.fn(),
+  approvalError: null,
+};
+
+const stubSessionPageFlow = {
+  conv: stubConv,
+  harness: "native" as const,
+  executionTarget: undefined,
+  model: [undefined, vi.fn()] as const,
+  interactionMode: ["agent" as const, vi.fn()] as const,
+  agentRef: { org: "acme", slug: "support-bot" },
+  setAgentRef: vi.fn(),
+  resolution: null,
+  setResolution: vi.fn(),
+  isDefaultAgent: false,
+  mcpServerUsages: [],
+  setMcpServerUsages: vi.fn(),
+  skillRefs: [],
+  setSkillRefs: vi.fn(),
+  workspace: stubWorkspace,
+  sessionVariables: { entries: [], isEmpty: true, clear: vi.fn() },
+  autoApproveAll: false,
+  setAutoApproveAll: vi.fn(),
+  submitApproval: vi.fn(),
+  handleSubmit: vi.fn(),
+  submitError: null as Error | null,
+  displayExecution: null,
+  allExecutions: [],
+  sandboxWorkspaceRoot: undefined,
+};
+vi.mock("../useSessionPageFlow", () => ({
+  useSessionPageFlow: () => stubSessionPageFlow,
+}));
+
+import { SessionViewer } from "../SessionViewer";
+
+beforeEach(() => {
+  threadProps.length = 0;
+  stubConv.fileChangeSets = [];
+  stubConv.submitFileDecision = vi.fn();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe("SessionViewer — file-review dock wiring", () => {
+  it("renders no dock when nothing is pending", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+    expect(
+      document.querySelector('[data-cursor-target="file-review-dock"]'),
+    ).toBeNull();
+  });
+
+  it("docks a pending set above the composer, wired to conv's decision seam", () => {
+    stubConv.fileChangeSets = [pendingChangeSet("cs-1")];
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+
+    const dock = document.querySelector('[data-cursor-target="file-review-dock"]');
+    expect(dock).toBeTruthy();
+    expect(screen.getByText("Review file changes")).toBeTruthy();
+
+    // The dock sits in the fixed strip: a sibling of the composer probe,
+    // ordered before it (pinned directly above the input).
+    const composer = screen.getByTestId("composer-probe");
+    expect(dock!.parentElement).toBe(composer.parentElement);
+    expect(
+      dock!.compareDocumentPosition(composer) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+
+    // A decision routes through conv.submitFileDecision with the set's id.
+    fireEvent.click(
+      document.querySelector<HTMLButtonElement>(
+        '[data-cursor-target="file-review-approve"]',
+      )!,
+    );
+    expect(stubConv.submitFileDecision).toHaveBeenCalledWith(
+      "cs-1",
+      FileDecisionAction.APPROVE,
+      expect.objectContaining({ expectedDigest: "agg-cs-1" }),
+    );
+  });
+
+  it("gives the thread records-only file-review props (no decision callbacks)", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+
+    expect(threadProps.length).toBeGreaterThan(0);
+    const props = threadProps.at(-1)!;
+    expect(props.showFileReviewRecords).toBe(true);
+    // The decision plumbing must not leak back into the thread.
+    expect(props.onFileDecisionSubmit).toBeUndefined();
+    expect(props.submittingFileDecisionKeys).toBeUndefined();
+    expect(props.fileDecisionErrors).toBeUndefined();
+  });
+});

package/src/session/__tests__/audienceWiring.test.tsx

@@ -97,6 +97,10 @@ const stubConv = {
   pendingApprovals: [],
   submitApproval: vi.fn(),
   submittingApprovalIds: new Set<string>(),
+  fileChangeSets: [],
+  submitFileDecision: vi.fn(),
+  submittingFileDecisionKeys: new Set<string>(),
+  fileDecisionErrors: new Map<string, Error>(),
   streamError: null,
   reconnectStream: vi.fn(),
   approvalError: null,

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

@@ -0,0 +1,303 @@
+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 { FileContentSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  CapturedFileChangeSchema,
+  FileChangeSetSchema,
+  FileReviewBaselineCapturedSchema,
+  FileReviewCandidateCapturedSchema,
+  FileReviewEventSchema,
+  FileReviewEventStreamSchema,
+  type CapturedFileChange,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import {
+  ExecutionPhase,
+  FileChangeCaptureLevel,
+  FileChangeKind,
+  FileChangeSetStatus,
+  FileChangeType,
+  FileReviewEventType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { useSessionFileChanges } from "../useSessionFileChanges";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+//
+// Under apply-then-review the hook sources exclusively from the file-review
+// ledger (the live `file_change_sets` projection, or the folded
+// `file_review_event_stream` for a terminal execution). The tool-call-coupled
+// `ToolCall.file_changes` (message.proto field 22) was removed in Phase 5
+// Slice 4, so every fixture here is a CapturedFileChange.
+// ---------------------------------------------------------------------------
+
+function inlineSide(value: string) {
+  return create(FileContentSchema, { body: { case: "inline", value } });
+}
+
+function captured(opts: {
+  id: string;
+  pathBefore?: string;
+  pathAfter?: string;
+  before?: string;
+  after?: string;
+  kind?: FileChangeKind;
+}): CapturedFileChange {
+  const pathBefore = opts.pathBefore ?? opts.pathAfter ?? "";
+  const pathAfter = opts.pathAfter ?? opts.pathBefore ?? "";
+  return create(CapturedFileChangeSchema, {
+    id: opts.id,
+    pathBefore,
+    pathAfter,
+    kind: opts.kind ?? FileChangeKind.MODIFY,
+    before: opts.before !== undefined ? inlineSide(opts.before) : undefined,
+    after: opts.after !== undefined ? inlineSide(opts.after) : undefined,
+    diffComplete: true,
+  });
+}
+
+function execWith(id: string): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  exec.metadata = create(ApiResourceMetadataSchema, { id });
+  exec.status = create(AgentExecutionStatusSchema);
+  return exec;
+}
+
+/** An execution carrying a live server projection of one change set. */
+function execWithProjection(id: string, changes: CapturedFileChange[]): AgentExecution {
+  const exec = execWith(id);
+  exec.status!.fileChangeSets = [
+    create(FileChangeSetSchema, {
+      id: `${id}:0`,
+      status: FileChangeSetStatus.AWAITING_REVIEW,
+      changes,
+    }),
+  ];
+  return exec;
+}
+
+/** A terminal execution: empty projection, changes only in the durable ledger. */
+function execWithLedger(id: string, changes: CapturedFileChange[]): AgentExecution {
+  const exec = execWith(id);
+  exec.status!.phase = ExecutionPhase.EXECUTION_COMPLETED;
+  exec.status!.fileChangeSets = [];
+  const changeSetId = `${id}:0`;
+  exec.status!.fileReviewEventStream = create(FileReviewEventStreamSchema, {
+    executionId: id,
+    events: [
+      create(FileReviewEventSchema, {
+        changeSetId,
+        eventType: FileReviewEventType.BASELINE_CAPTURED,
+        payload: {
+          case: "baselineCaptured",
+          value: create(FileReviewBaselineCapturedSchema, { changeSetId }),
+        },
+      }),
+      create(FileReviewEventSchema, {
+        changeSetId,
+        eventType: FileReviewEventType.CANDIDATE_CAPTURED,
+        payload: {
+          case: "candidateCaptured",
+          value: create(FileReviewCandidateCapturedSchema, { changeSetId, changes }),
+        },
+      }),
+    ],
+  });
+  return exec;
+}
+
+function run(executions: readonly AgentExecution[]) {
+  return renderHook(() => useSessionFileChanges(executions)).result.current;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("useSessionFileChanges", () => {
+  it("returns empty for no executions", () => {
+    const r = run([]);
+    expect(r.hasFileChanges).toBe(false);
+    expect(r.fileChangeCount).toBe(0);
+    expect(r.fileChanges).toEqual([]);
+  });
+
+  it("returns empty when an execution has no file-review changes", () => {
+    const r = run([execWith("e1")]);
+    expect(r.hasFileChanges).toBe(false);
+  });
+
+  it("collects a single change from the live projection", () => {
+    const r = run([
+      execWithProjection("e1", [
+        captured({ id: "fc1", pathAfter: "src/a.ts", before: "a", after: "b" }),
+      ]),
+    ]);
+    expect(r.fileChangeCount).toBe(1);
+    expect(r.fileChanges[0].path).toBe("src/a.ts");
+    expect(r.fileChanges[0].captureLevel).toBe(FileChangeCaptureLevel.WHOLE_FILE);
+  });
+
+  it("collects changes from the durable ledger for a terminal execution", () => {
+    const r = run([
+      execWithLedger("e1", [
+        captured({ id: "fc1", pathAfter: "src/term.ts", before: "a", after: "b" }),
+      ]),
+    ]);
+    expect(r.fileChangeCount).toBe(1);
+    expect(r.fileChanges[0].path).toBe("src/term.ts");
+  });
+
+  it("net-diffs multiple edits to the same path: first.before -> last.after", () => {
+    const r = run([
+      execWithProjection("e1", [
+        captured({ id: "fc1", pathAfter: "src/a.ts", before: "v0", after: "v1" }),
+        captured({ id: "fc2", pathAfter: "src/a.ts", before: "v1", after: "v2" }),
+      ]),
+    ]);
+    expect(r.fileChangeCount).toBe(1);
+    const net = r.fileChanges[0];
+    expect(net.before?.body.case === "inline" && net.before.body.value).toBe("v0");
+    expect(net.after?.body.case === "inline" && net.after.body.value).toBe("v2");
+  });
+
+  it("reconciles create-then-modify on the same path to CREATE", () => {
+    const r = run([
+      execWithProjection("e1", [
+        captured({ id: "fc1", pathAfter: "src/new.ts", after: "first", kind: FileChangeKind.ADD }),
+        captured({ id: "fc2", pathAfter: "src/new.ts", before: "first", after: "second", kind: FileChangeKind.MODIFY }),
+      ]),
+    ]);
+    expect(r.fileChanges[0].changeType).toBe(FileChangeType.CREATE);
+    expect(r.fileChanges[0].after?.body.case === "inline" && r.fileChanges[0].after.body.value).toBe("second");
+  });
+
+  it("reconciles modify-then-delete on the same path to DELETE", () => {
+    const r = run([
+      execWithProjection("e1", [
+        captured({ id: "fc1", pathAfter: "src/x.ts", before: "a", after: "b" }),
+        captured({ id: "fc2", pathBefore: "src/x.ts", pathAfter: "src/x.ts", before: "b", kind: FileChangeKind.DELETE }),
+      ]),
+    ]);
+    expect(r.fileChanges[0].changeType).toBe(FileChangeType.DELETE);
+  });
+
+  it("reconciles create-then-delete on the same path to DELETE (path is not hidden)", () => {
+    const r = run([
+      execWithProjection("e1", [
+        captured({ id: "fc1", pathAfter: "src/tmp.ts", after: "scratch", kind: FileChangeKind.ADD }),
+        captured({ id: "fc2", pathBefore: "src/tmp.ts", pathAfter: "src/tmp.ts", before: "scratch", kind: FileChangeKind.DELETE }),
+      ]),
+    ]);
+    // A file created and removed within one session still surfaces, as a DELETE
+    // anchored on the first change's (empty) before — it is not silently dropped.
+    expect(r.fileChangeCount).toBe(1);
+    expect(r.fileChanges[0].changeType).toBe(FileChangeType.DELETE);
+  });
+
+  it("reconciles rename-then-modify on the same path to RENAME, preserving rename_from", () => {
+    const r = run([
+      execWithProjection("e1", [
+        captured({ id: "fc1", pathBefore: "src/old-name.ts", pathAfter: "src/new-name.ts", before: "a", after: "a", kind: FileChangeKind.RENAME }),
+        captured({ id: "fc2", pathAfter: "src/new-name.ts", before: "a", after: "b", kind: FileChangeKind.MODIFY }),
+      ]),
+    ]);
+    expect(r.fileChanges[0].changeType).toBe(FileChangeType.RENAME);
+    expect(r.fileChanges[0].renameFrom).toBe("src/old-name.ts");
+    expect(r.fileChanges[0].after?.body.case === "inline" && r.fileChanges[0].after.body.value).toBe("b");
+  });
+
+  it("groups changes across change sets by path (the execution-scoped ledger covers sub-agents)", () => {
+    const exec = execWith("e1");
+    exec.status!.fileChangeSets = [
+      create(FileChangeSetSchema, {
+        id: "e1:0",
+        status: FileChangeSetStatus.RECONCILED,
+        changes: [captured({ id: "fc1", pathAfter: "src/shared.ts", before: "v0", after: "v1" })],
+      }),
+      create(FileChangeSetSchema, {
+        id: "e1:1",
+        status: FileChangeSetStatus.AWAITING_REVIEW,
+        changes: [captured({ id: "fc2", pathAfter: "src/shared.ts", before: "v1", after: "v2" })],
+      }),
+    ];
+    const r = run([exec]);
+    expect(r.fileChangeCount).toBe(1);
+    const net = r.fileChanges[0];
+    expect(net.before?.body.case === "inline" && net.before.body.value).toBe("v0");
+    expect(net.after?.body.case === "inline" && net.after.body.value).toBe("v2");
+  });
+
+  it("passes a single change through with its bytes intact (no synthesis)", () => {
+    const r = run([
+      execWithProjection("e1", [
+        captured({ id: "fc1", pathAfter: "src/a.ts", before: "a", after: "b" }),
+      ]),
+    ]);
+    expect(r.fileChangeCount).toBe(1);
+    const only = r.fileChanges[0];
+    expect(only.path).toBe("src/a.ts");
+    expect(only.before?.body.case === "inline" && only.before.body.value).toBe("a");
+    expect(only.after?.body.case === "inline" && only.after.body.value).toBe("b");
+  });
+
+  it("sorts modified before created/renamed before deleted, then alpha", () => {
+    const r = run([
+      execWithProjection("e1", [
+        captured({ id: "fc1", pathBefore: "z-del.ts", pathAfter: "z-del.ts", before: "x", kind: FileChangeKind.DELETE }),
+        captured({ id: "fc2", pathAfter: "a-new.ts", after: "x", kind: FileChangeKind.ADD }),
+        captured({ id: "fc3", pathAfter: "m-mod.ts", before: "x", after: "y", kind: FileChangeKind.MODIFY }),
+        captured({ id: "fc4", pathAfter: "b-mod.ts", before: "x", after: "y", kind: FileChangeKind.MODIFY }),
+      ]),
+    ]);
+    expect(r.fileChanges.map((c) => c.path)).toEqual([
+      "b-mod.ts",
+      "m-mod.ts",
+      "a-new.ts",
+      "z-del.ts",
+    ]);
+  });
+
+  it("net-diffs captures across turns from the ledger", () => {
+    // Two change sets touching the same path: first.before -> last.after.
+    const exec = execWith("e1");
+    exec.status!.fileChangeSets = [
+      create(FileChangeSetSchema, {
+        id: "e1:0",
+        status: FileChangeSetStatus.RECONCILED,
+        changes: [captured({ id: "fc1", pathAfter: "src/a.ts", before: "v0", after: "v1" })],
+      }),
+      create(FileChangeSetSchema, {
+        id: "e1:1",
+        status: FileChangeSetStatus.AWAITING_REVIEW,
+        changes: [captured({ id: "fc2", pathAfter: "src/a.ts", before: "v1", after: "v2" })],
+      }),
+    ];
+    const r = run([exec]);
+    expect(r.fileChangeCount).toBe(1);
+    const net = r.fileChanges[0];
+    expect(net.before?.body.case === "inline" && net.before.body.value).toBe("v0");
+    expect(net.after?.body.case === "inline" && net.after.body.value).toBe("v2");
+  });
+
+  it("preserves referential stability across re-renders for the same executions", () => {
+    const executions = [
+      execWithProjection("e1", [
+        captured({ id: "fc1", pathAfter: "src/a.ts", before: "a", after: "b" }),
+      ]),
+    ];
+    const { result, rerender } = renderHook(
+      (e: readonly AgentExecution[]) => useSessionFileChanges(e),
+      { initialProps: executions },
+    );
+    const first = result.current;
+    rerender(executions);
+    expect(result.current).toBe(first);
+  });
+});

package/src/session/index.ts

@@ -45,6 +45,9 @@ export type {
   UseSessionWriteBacksReturn,
 } from "./useSessionWriteBacks";
 
+export { useSessionFileChanges } from "./useSessionFileChanges";
+export type { UseSessionFileChangesReturn } from "./useSessionFileChanges";
+
 export { useSessionUsage } from "./useSessionUsage";
 export type {
   ModelCostEntry,