@stigmer/react 3.1.4 → 3.1.6

package/src/github/useGitHubTreeLister.ts

@@ -38,7 +38,8 @@ const TRUNCATION_MARKER: WorkspaceFileEntry = {
  * Creates a {@link WorkspaceFileLister} backed by the GitHub Trees API.
  *
  * Uses the existing client-side OAuth token (same one that powers
- * `GitHubRepoPicker`) to call `GET /repos/{owner}/{repo}/git/trees/{branch}?recursive=1`.
+ * `GitHubRepoPicker`) to call `GET /repos/{owner}/{repo}/git/trees/{ref}?recursive=1`,
+ * where the ref is the entry's `readRef` (write-back commit) or `gitBranch`.
  *
  * Returns `null` for:
  * - Non-git workspace entries
@@ -64,8 +65,11 @@ export function useGitHubTreeLister(
       const parsed = parseGitUrl(entry.gitUrl);
       if (!parsed) return null;
 
-      const branch = entry.gitBranch || "main";
-      const url = `${GITHUB_TREES_API}/${parsed.owner}/${parsed.repo}/git/trees/${encodeURIComponent(branch)}?recursive=1`;
+      // readRef (the session's write-back commit SHA, when one exists) wins
+      // over the configured branch, so the tree includes agent-created files.
+      // The Trees API accepts a branch name or a commit SHA interchangeably.
+      const ref = entry.readRef || entry.gitBranch || "main";
+      const url = `${GITHUB_TREES_API}/${parsed.owner}/${parsed.repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`;
 
       const resp = await fetch(url, {
         headers: { Authorization: `Bearer ${token}` },

package/src/index.ts

@@ -71,6 +71,7 @@ export {
   useWorkspaceContentSearch,
   useWorkspaceSources,
   MAX_WORKSPACE_FILE_READ_BYTES,
+  WorkspaceFileNotFoundError,
   WorkspaceEditor,
   WorkspaceFileSearch,
   WorkspaceContentSearch,
@@ -131,6 +132,7 @@ export {
   useSessionArtifacts,
   artifactKey,
   useSessionWriteBacks,
+  useWorkspaceReadRefs,
   useSessionFileChanges,
   useSessionUsage,
   useAgentRefFromSession,
@@ -233,6 +235,7 @@ export {
   deriveEffectiveVerdicts,
   changeForRowPath,
   fileReviewRowState,
+  fileReviewRowChange,
   foldFileReviewEventStream,
   displayFileChangeSets,
   toDisplayFileChange,
@@ -290,6 +293,7 @@ export {
   useApproval,
   FileReviewContext,
   useFileReviewRowState,
+  useFileReviewRowChange,
   ArtifactRow,
   ArtifactContentRenderer,
   ArtifactContentBody,

package/src/internal/VirtualizedThread.tsx

@@ -15,6 +15,7 @@ import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 import {
   ThreadItemRenderer,
   threadContentColumnClass,
+  type MessageThreadSlots,
   type ThreadItem,
   type ThreadContentColumn,
 } from "../execution/MessageThread.js";
@@ -55,6 +56,7 @@ export interface VirtualizedThreadProps {
   readonly onRetrySend?: () => void;
   readonly onRetryExecution?: (message: string) => void;
   readonly onEditMessage?: (text: string) => void;
+  readonly slots?: MessageThreadSlots;
 }
 
 // ---------------------------------------------------------------------------
@@ -124,6 +126,7 @@ export function VirtualizedThread({
   onRetrySend,
   onRetryExecution,
   onEditMessage,
+  slots,
 }: VirtualizedThreadProps) {
   const virtuosoRef = useRef<VirtuosoHandle>(null);
   const scrollerRef = useRef<HTMLDivElement | null>(null);
@@ -161,8 +164,9 @@ export function VirtualizedThread({
       onRetrySend,
       onRetryExecution,
       onEditMessage,
+      slots,
     }),
-    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, approvalErrors, onBuildFromPlan, onOpenPlan, org, planActionsDisabled, planBuildPending, onRetrySend, onRetryExecution, onEditMessage],
+    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, approvalErrors, onBuildFromPlan, onOpenPlan, org, planActionsDisabled, planBuildPending, onRetrySend, onRetryExecution, onEditMessage, slots],
   );
 
   return (

package/src/session/SessionViewer.tsx

@@ -24,7 +24,8 @@ import { SelectionStore } from "../internal/store/selection-store.js";
 import { useWorkspaceEditors, isVirtualEntryId } from "../internal/store/index.js";
 import { ThreadSelectionContext } from "../execution/ThreadSelectionContext.js";
 import { useSelectedThreadItem } from "../execution/useThreadSelection.js";
-import { MessageThread } from "../execution/MessageThread.js";
+import { isTerminalPhase } from "../execution/execution-phases.js";
+import { MessageThread, type MessageThreadSlots } from "../execution/MessageThread.js";
 import { FileChangeProgressBar } from "../execution/FileChangeProgressBar.js";
 import { FileReviewDock } from "../execution/FileReviewDock.js";
 import {
@@ -53,6 +54,7 @@ import { useSessionRailViews } from "./useSessionRailViews.js";
 import { useSessionPanel, type SessionPanelController } from "./useSessionPanel.js";
 import { SessionPanelChip } from "./SessionPanelChip.js";
 import { useSessionWriteBacks } from "./useSessionWriteBacks.js";
+import { useWorkspaceReadRefs } from "./useWorkspaceReadRefs.js";
 import {
   useSessionArtifacts,
   artifactKey,
@@ -228,6 +230,15 @@ export interface SessionViewerProps {
   readonly accessSlot?: ReactNode;
   /** Called after a resource is applied from the Artifacts tab. */
   readonly onApplied?: (result: ApplyResourceResult) => void;
+  /**
+   * Component overrides for the conversation thread's chrome (message
+   * bubbles, approval card, to-dos card, plan cards, thinking indicator) —
+   * forwarded to the inner {@link MessageThread}. See
+   * {@link MessageThreadSlots}. Define the object and its components at
+   * module level (or memoize) so thread rows keep their streaming
+   * re-render guarantees.
+   */
+  readonly threadSlots?: MessageThreadSlots;
   /** Additional CSS classes for the root container. */
   readonly className?: string;
 }
@@ -289,6 +300,7 @@ export function SessionViewer({
   headerActions,
   accessSlot,
   onApplied,
+  threadSlots,
   className,
 }: SessionViewerProps) {
   const flow = useSessionPageFlow({ sessionId, org, getRuntimeEnv });
@@ -572,6 +584,7 @@ export function SessionViewer({
               onDismissPlanAttachFailed={() => setPlanAttachFailed(false)}
               onFilePathClick={handleTranscriptFilePathClick}
               isEndUser={isEndUser}
+              threadSlots={threadSlots}
             />
           }
           secondary={
@@ -637,6 +650,7 @@ interface ConversationColumnProps {
    */
   readonly onFilePathClick: (path: string) => boolean;
   readonly isEndUser: boolean;
+  readonly threadSlots?: MessageThreadSlots;
 }
 
 const ConversationColumn = memo(function ConversationColumn({
@@ -658,6 +672,7 @@ const ConversationColumn = memo(function ConversationColumn({
   onDismissPlanAttachFailed,
   onFilePathClick,
   isEndUser,
+  threadSlots,
 }: ConversationColumnProps) {
   const { conv } = flow;
   // Approval failures are NOT folded into this banner: they now surface in-card,
@@ -770,6 +785,7 @@ const ConversationColumn = memo(function ConversationColumn({
         planActionsDisabled={!conv.canSendFollowUp || isBuildingFromPlan}
         planBuildPending={isBuildingFromPlan}
         contentColumn="center"
+        slots={threadSlots}
         className="flex-1"
       />
       <div className={CONVERSATION_COLUMN_CLASS}>
@@ -1111,6 +1127,18 @@ function SessionPanelRegion({
     ],
   );
 
+  // Cloud sessions with a git workspace push approved changes back to a
+  // branch/PR, so the Changes facet is offered from the start with an honest
+  // pre-push state. Deliberately NOT for local sessions: local mode edits the
+  // user's own working tree and never writes back (the runner configures no
+  // push credentials there) — promising a PR would be a lie.
+  const expectsWriteBack =
+    flow.executionTarget === "cloud" &&
+    flow.workspace.entries.some((entry) => entry.type === "git");
+  const displayPhase =
+    flow.displayExecution?.status?.phase ??
+    ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+
   // The session facets (Config / Changes / Artifacts / Usage / Inspect) as
   // injected rail views — the full inspector feature set inside one panel.
   const railViews = useSessionRailViews({
@@ -1123,6 +1151,8 @@ function SessionPanelRegion({
     onOpenPlan,
     onOpenArtifact,
     onActivateArtifact,
+    expectsWriteBack,
+    changesSettled: isTerminalPhase(displayPhase),
   });
 
   // Explorer-footer folder attach (desktop only — needs the native picker).
@@ -1133,9 +1163,19 @@ function SessionPanelRegion({
     if (path) flow.workspace.addLocalPath(path);
   }, [onBrowseLocalFolder, flow.workspace.addLocalPath]);
 
+  // Entries decorated with per-entry read refs (the latest write-back commit
+  // SHA), so the surface's read-side capabilities — file viewer, tree listing,
+  // name search — resolve at the ref the agent's changes actually live on. A
+  // read-side projection only: `flow.workspace.entries` stays undecorated for
+  // setup and session input.
+  const surfaceEntries = useWorkspaceReadRefs(
+    flow.allExecutions,
+    flow.workspace.entries,
+  );
+
   return (
     <WorkspaceSurface
-      entries={flow.workspace.entries}
+      entries={surfaceEntries}
       lister={workspaceFileLister}
       reader={workspaceFileReader}
       searcher={workspaceContentSearcher}

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

@@ -80,6 +80,18 @@ describe("useSessionRailViews", () => {
     ]);
   });
 
+  it("offers Changes pre-push when a write-back is expected, without a zero badge", () => {
+    const { result } = renderViews({ expectsWriteBack: true });
+    const changes = result.current.find((v) => v.id === "changes");
+    expect(changes, "cloud git sessions get the facet before any push").toBeTruthy();
+    expect(changes?.badge).toBeUndefined();
+  });
+
+  it("hides Changes when no write-back exists and none is expected", () => {
+    const { result } = renderViews({ expectsWriteBack: false });
+    expect(result.current.some((v) => v.id === "changes")).toBe(false);
+  });
+
   it("surfaces Artifacts with a count badge", () => {
     artifactsState.hasArtifacts = true;
     artifactsState.artifactCount = 4;

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

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

package/src/session/facets/ChangesTab.tsx

@@ -6,20 +6,42 @@ import { WriteBackCard } from "../../execution/WriteBackCard.js";
 
 export interface ChangesTabProps {
   readonly executions: readonly AgentExecution[];
+  /**
+   * Whether this session is expected to push its approved changes back to a
+   * git remote — a CLOUD session with at least one git workspace entry (local
+   * sessions edit the user's own working tree and never write back). Enables
+   * the pre-write-back states below, so the facet answers "where does my work
+   * go?" before any push exists. Defaults to `false`: a bare `ChangesTab`
+   * stays the pure write-back list it always was.
+   */
+  readonly expectsWriteBack?: boolean;
+  /**
+   * Whether the session's latest execution is settled (terminal). Selects
+   * between the pre-write-back states: a live turn shows the "will be pushed
+   * here" promise, a settled one shows the honest "nothing pushed yet".
+   * Only consulted when {@link expectsWriteBack} is set and no write-back
+   * exists yet.
+   */
+  readonly isSettled?: boolean;
 }
 
 /**
- * Changes facet for the session panel — the session's git write-backs
- * (branch/commit/PR), one `WriteBackCard` per entry.
+ * Changes facet for the session panel — the definitive "where did my work go"
+ * surface: the session's git write-backs (branch/commit/PR), one
+ * `WriteBackCard` per entry, with honest pre-push states for cloud git
+ * sessions whose write-back hasn't happened yet.
  *
  * Local file changes deliberately do NOT render here: they live in the
  * transcript, where each stamped edit row shows its diff in place and the
  * per-turn decision bar carries the review controls and file list
- * (`FileReviewCard`). Duplicating them in a side panel gave the same change a
- * third rendering with no added authority. The facet therefore only surfaces
- * once a write-back exists (see `useSessionRailViews`).
+ * (`FileReviewCard`). This facet is exclusively the git OUTCOME surface —
+ * what was reviewed there lands here as a branch and pull request.
  */
-export function ChangesTab({ executions }: ChangesTabProps) {
+export function ChangesTab({
+  executions,
+  expectsWriteBack = false,
+  isSettled = false,
+}: ChangesTabProps) {
   const { writeBacks, hasWriteBacks } = useSessionWriteBacks(executions);
 
   if (hasWriteBacks) {
@@ -34,6 +56,21 @@ export function ChangesTab({ executions }: ChangesTabProps) {
     );
   }
 
+  if (expectsWriteBack) {
+    return (
+      <div className="flex flex-col items-center justify-center px-4 py-8 text-center">
+        <p className="text-xs text-muted-foreground">
+          {isSettled
+            ? "No changes have been pushed yet. When the agent changes files " +
+              "and you approve them, they are pushed to a branch and pull " +
+              "request here."
+            : "Changes stay in the session workspace while you review them. " +
+              "Approved changes are pushed to a branch and pull request here."}
+        </p>
+      </div>
+    );
+  }
+
   return (
     <div className="flex flex-col items-center justify-center px-4 py-8 text-center">
       <p className="text-xs text-muted-foreground">

package/src/session/facets/__tests__/ChangesTab.test.tsx

@@ -35,4 +35,27 @@ describe("ChangesTab", () => {
     expect(screen.getByText(/no changes yet/i)).toBeTruthy();
     expect(screen.getByText(/pull requests/i)).toBeTruthy();
   });
+
+  // Pre-push states for a session expected to write back (cloud + git):
+  // live turns promise where approved work will land; a settled execution
+  // reports honestly that nothing was pushed.
+  it("renders the in-review promise while a write-back is expected and the session is live", () => {
+    render(<ChangesTab executions={[]} expectsWriteBack isSettled={false} />);
+    expect(screen.getByText(/stay in the session workspace/i)).toBeTruthy();
+    expect(screen.getByText(/pushed to a branch and pull request here/i)).toBeTruthy();
+  });
+
+  it("renders the nothing-pushed state when expected but the execution settled without a push", () => {
+    render(<ChangesTab executions={[]} expectsWriteBack isSettled />);
+    expect(screen.getByText(/no changes have been pushed yet/i)).toBeTruthy();
+  });
+
+  it("write-backs take precedence over the pre-push states", () => {
+    writeBacksReturn.writeBacks = [{ writeBack: { workspaceEntryName: "w1" } }];
+    writeBacksReturn.hasWriteBacks = true;
+
+    render(<ChangesTab executions={[]} expectsWriteBack />);
+    expect(screen.getByTestId("write-back-card")).toBeTruthy();
+    expect(screen.queryByText(/no changes/i)).toBeNull();
+  });
 });

package/src/session/index.ts

@@ -45,6 +45,8 @@ export type {
   UseSessionWriteBacksReturn,
 } from "./useSessionWriteBacks.js";
 
+export { useWorkspaceReadRefs } from "./useWorkspaceReadRefs.js";
+
 export { useSessionFileChanges } from "./useSessionFileChanges.js";
 export type { UseSessionFileChangesReturn } from "./useSessionFileChanges.js";
 

package/src/session/useSessionRailViews.tsx

@@ -54,6 +54,21 @@ export interface UseSessionRailViewsOptions {
    * @default true
    */
   readonly includeExecutionFacets?: boolean;
+  /**
+   * Whether the session is expected to push approved changes to a git remote
+   * (a cloud session with git workspace entries). When `true` the Changes
+   * facet is offered from the start — with an honest pre-push state — instead
+   * of only materializing once a write-back exists, so "where does my work
+   * go?" always has an answer. See {@link ChangesTabProps.expectsWriteBack}.
+   * @default false
+   */
+  readonly expectsWriteBack?: boolean;
+  /**
+   * Whether the session's latest execution is settled (terminal) — forwarded
+   * to the Changes facet's pre-push states. See {@link ChangesTabProps.isSettled}.
+   * @default false
+   */
+  readonly changesSettled?: boolean;
 }
 
 /**
@@ -77,6 +92,8 @@ export function useSessionRailViews({
   onOpenArtifact,
   onActivateArtifact,
   includeExecutionFacets = true,
+  expectsWriteBack = false,
+  changesSettled = false,
 }: UseSessionRailViewsOptions): readonly SurfaceRailView[] {
   const { hasWriteBacks, writeBackCount } = useSessionWriteBacks(allExecutions);
   const { hasArtifacts, artifactCount } = useSessionArtifacts(allExecutions);
@@ -94,13 +111,22 @@ export function useSessionRailViews({
     }
 
     if (includeExecutionFacets) {
-      if (hasWriteBacks) {
+      // Offered when a write-back exists OR the session is expected to
+      // produce one — the facet then carries an honest pre-push state
+      // instead of being invisible until the first push.
+      if (hasWriteBacks || expectsWriteBack) {
         views.push({
           id: "changes",
           label: "Changes",
           icon: <ChangesIcon />,
-          badge: writeBackCount,
-          content: <ChangesTab executions={allExecutions} />,
+          badge: writeBackCount > 0 ? writeBackCount : undefined,
+          content: (
+            <ChangesTab
+              executions={allExecutions}
+              expectsWriteBack={expectsWriteBack}
+              isSettled={changesSettled}
+            />
+          ),
         });
       }
 
@@ -145,6 +171,8 @@ export function useSessionRailViews({
   }, [
     sessionConfig,
     includeExecutionFacets,
+    expectsWriteBack,
+    changesSettled,
     hasWriteBacks,
     writeBackCount,
     hasArtifacts,