🤖 fix: add stream startup breadcrumbs

Add lightweight info-level breadcrumbs around pre-stream startup so hangs can be narrowed to init, runtime checks, tool loading, request preparation, or stream start. Reuse the existing runtime-status event channel so the current startup phase is also visible in the StreamingBarrier UI instead of a generic starting message.

---

_Generated with `mux` • Model: `openai:gpt-5.4` • Thinking: `xhigh` • Cost: `$11.73`_

<!-- mux-attribution: model=openai:gpt-5.4 thinking=xhigh costs=11.73 -->

Author: ammar-agent

src/browser/features/Messages/ChatBarrier/StreamingBarrier.test.tsx

@@ -158,6 +158,19 @@ describe("StreamingBarrier", () => {
     expect(interruptStream).toHaveBeenCalledWith({ workspaceId: "ws-1" });
   });
 
+  test("shows backend startup breadcrumb text while the stream is starting", () => {
+    currentWorkspaceState = createWorkspaceState({
+      canInterrupt: false,
+      pendingStreamStartTime: Date.now(),
+      pendingStreamModel: "openai:gpt-4o-mini",
+      runtimeStatus: { phase: "starting", detail: "Loading tools..." },
+    });
+
+    const view = render(<StreamingBarrier workspaceId="ws-1" />);
+
+    expect(view.getByText("Loading tools...")).toBeTruthy();
+  });
+
   test("shows vim interrupt shortcut when vim mode is enabled", () => {
     currentWorkspaceState = createWorkspaceState({
       canInterrupt: false,

src/browser/features/Messages/ChatBarrier/StreamingBarrier.tsx

@@ -105,7 +105,8 @@ export const StreamingBarrier: React.FC<StreamingBarrierProps> = ({
   const statusText = (() => {
     switch (phase) {
       case "starting":
-        // Show a runtime-specific message if the workspace is still booting (e.g., Coder/devcontainers).
+        // Prefer any backend-provided startup breadcrumb so users can see whether
+        // we're still booting the runtime or doing later prep like loading tools.
         if (runtimeStatus?.phase === "starting" || runtimeStatus?.phase === "waiting") {
           return runtimeStatus.detail ?? "Starting workspace...";
         }

src/browser/features/Messages/ChatBarrier/StreamingBarrierView.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { fn } from "@storybook/test";
+import { lightweightMeta } from "@/browser/stories/meta.js";
+import { StreamingBarrierView } from "./StreamingBarrierView";
+
+const meta = {
+  ...lightweightMeta,
+  title: "App/Chat/Barriers/Streaming",
+  component: StreamingBarrierView,
+  render: (args) => (
+    <div className="bg-background flex min-h-screen items-start p-6">
+      <div className="w-full max-w-3xl rounded-md border border-[var(--color-border-medium)] bg-[var(--color-card)] p-4">
+        <StreamingBarrierView {...args} />
+      </div>
+    </div>
+  ),
+} satisfies Meta<typeof StreamingBarrierView>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Frontend display for the first-init SSH diagnostic state while the workspace
+ * is still waiting for initialization to complete.
+ */
+export const WaitingForWorkspaceInitialization: Story = {
+  args: {
+    statusText: "Waiting for workspace initialization...",
+    cancelText: "hit Esc to cancel",
+    cancelShortcutText: "Esc",
+    onCancel: fn(),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Shows the startup diagnostic users see when an SSH workspace is still in first-init setup and the frontend is waiting for workspace initialization.",
+      },
+    },
+  },
+};
+
+/**
+ * Frontend display for the later startup diagnostic state after runtime
+ * readiness, when the request is still assembling tools.
+ */
+export const LoadingToolsDiagnostic: Story = {
+  args: {
+    statusText: "Loading tools...",
+    cancelText: "hit Esc to cancel",
+    cancelShortcutText: "Esc",
+    onCancel: fn(),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Shows the more specific startup diagnostic text after runtime readiness succeeds but request startup is still blocked on tool assembly.",
+      },
+    },
+  },
+};

src/browser/stores/WorkspaceStore.ts

@@ -102,7 +102,7 @@ export interface WorkspaceState {
   pendingStreamStartTime: number | null;
   // Model used for the pending send (used during "starting" phase)
   pendingStreamModel: string | null;
-  // Runtime status from ensureReady (for Coder workspace starting UX)
+  // Current pre-stream startup breadcrumb (runtime readiness, tool loading, etc.)
   runtimeStatus: RuntimeStatusEvent | null;
   autoRetryStatus: AutoRetryStatus | null;
   // Live streaming stats (updated on each stream-delta)

src/browser/utils/messages/StreamingMessageAggregator.ts

@@ -433,8 +433,9 @@ export class StreamingMessageAggregator {
   // Last observed stream-abort reason (used to gate auto-retry).
   private lastAbortReason: StreamAbortReasonSnapshot | null = null;
 
-  // Current runtime status (set during ensureReady for Coder workspaces)
-  // Used to show "Starting Coder workspace..." in StreamingBarrier
+  // Current pre-stream startup status.
+  // This begins with runtime readiness for Coder, but also carries generic
+  // startup breadcrumbs like "Loading tools..." while the request is preparing.
   private runtimeStatus: RuntimeStatusEvent | null = null;
 
   // Pending compaction request metadata for the next stream (set when user message arrives).
@@ -1178,8 +1179,8 @@ export class StreamingMessageAggregator {
   }
 
   /**
-   * Get the current runtime status (for Coder workspace starting UX).
-   * Returns null if no runtime status is active.
+   * Get the current pre-stream startup status.
+   * Returns null if no startup breadcrumb is active.
    */
   getRuntimeStatus(): RuntimeStatusEvent | null {
     return this.runtimeStatus;
@@ -1210,8 +1211,8 @@ export class StreamingMessageAggregator {
   }
 
   /**
-   * Handle runtime-status event (emitted during ensureReady for Coder workspaces).
-   * Used to show "Starting Coder workspace..." in StreamingBarrier.
+   * Handle runtime-status event.
+   * Used to show both runtime readiness and generic startup breadcrumbs in StreamingBarrier.
    */
   handleRuntimeStatus(status: RuntimeStatusEvent): void {
     // Keep stream lifecycle code focused on when runtime status becomes irrelevant.

src/browser/utils/messages/applyWorkspaceChatEventToAggregator.ts

@@ -229,7 +229,7 @@ export function applyWorkspaceChatEventToAggregator(
     return "immediate";
   }
 
-  // runtime-status events are used for Coder workspace starting UX
+  // runtime-status events drive pre-stream startup breadcrumbs in the barrier UI
   if (isRuntimeStatus(event)) {
     aggregator.handleRuntimeStatus(event);
     return "immediate";

src/common/orpc/schemas/stream.ts

@@ -75,15 +75,18 @@ export const CaughtUpMessageSchema = z.object({
 });
 
 /**
- * Progress event for runtime readiness checks.
- * Used by Coder workspaces to show "Starting Coder workspace..." while ensureReady() blocks.
- * Not used by Docker (start is near-instant) or local runtimes.
+ * Progress event for pre-stream startup work.
+ *
+ * Initially introduced for runtime readiness checks, but now also carries generic
+ * pre-stream breadcrumbs (for example tool loading or request preparation) so the
+ * user can see where startup is currently blocked.
  */
 export const RuntimeStatusEventSchema = z.object({
   type: z.literal("runtime-status"),
   workspaceId: z.string(),
   phase: z.enum(["checking", "starting", "waiting", "ready", "error"]),
   runtimeType: RuntimeModeSchema,
+  source: z.enum(["runtime", "startup"]).optional(),
   detail: z.string().optional(), // Human-readable status like "Starting Coder workspace..."
 });
 

src/common/types/stream.ts

@@ -85,7 +85,7 @@ export type AutoRetryStartingEvent = z.infer<typeof AutoRetryStartingEventSchema
 export type AutoRetryAbandonedEvent = z.infer<typeof AutoRetryAbandonedEventSchema>;
 
 /**
- * Progress event for runtime readiness checks.
- * Used by Coder workspaces to show "Starting Coder workspace..." while ensureReady() blocks.
+ * Progress event for pre-stream startup work.
+ * Used for both runtime readiness and generic startup breadcrumbs in the barrier UI.
  */
 export type RuntimeStatusEvent = z.infer<typeof RuntimeStatusEventSchema>;

src/common/utils/messages/retryEligibility.test.ts

@@ -279,6 +279,54 @@ describe("hasInterruptedStream", () => {
     expect(hasInterruptedStream(messages, null)).toBe(true);
   });
 
+  it("suppresses retry while runtime startup is still in progress", () => {
+    const messages: DisplayedMessage[] = [
+      {
+        type: "user",
+        id: "user-1",
+        historyId: "user-1",
+        content: "Hello",
+        historySequence: 1,
+      },
+    ];
+
+    const runtimeStatus = {
+      type: "runtime-status" as const,
+      workspaceId: "ws-1",
+      phase: "starting" as const,
+      runtimeType: "ssh" as const,
+      source: "runtime" as const,
+      detail: "Starting workspace...",
+    };
+
+    expect(hasInterruptedStream(messages, null, runtimeStatus)).toBe(false);
+    expect(isEligibleForAutoRetry(messages, null, runtimeStatus)).toBe(false);
+  });
+
+  it("keeps retry eligible for non-runtime startup breadcrumbs", () => {
+    const messages: DisplayedMessage[] = [
+      {
+        type: "user",
+        id: "user-1",
+        historyId: "user-1",
+        content: "Hello",
+        historySequence: 1,
+      },
+    ];
+
+    const runtimeStatus = {
+      type: "runtime-status" as const,
+      workspaceId: "ws-1",
+      phase: "starting" as const,
+      runtimeType: "ssh" as const,
+      source: "startup" as const,
+      detail: "Loading tools...",
+    };
+
+    expect(hasInterruptedStream(messages, null, runtimeStatus)).toBe(true);
+    expect(isEligibleForAutoRetry(messages, null, runtimeStatus)).toBe(true);
+  });
+
   it("returns false when message was sent very recently (within grace period)", () => {
     const messages: DisplayedMessage[] = [
       {

src/common/utils/messages/retryEligibility.ts

@@ -159,10 +159,14 @@ function computeHasInterruptedStream(
     return false;
   }
 
-  // Don't show retry barrier if runtime is still starting (e.g., Coder workspace waiting for startup scripts).
-  // The backend's ensureReady() is still running - this happens when reconnecting to a stopped workspace.
-  // runtimeStatus is set during ensureReady() and cleared when ready/error.
-  if (runtimeStatus !== null && lastMessage.type !== "stream-error") {
+  // Don't show retry barrier if runtime bring-up is still in progress (for example a stopped
+  // Coder workspace that is still starting). Generic post-runtime startup breadcrumbs must not
+  // suppress retry UI, or a later stall in tool loading/request prep would hide the interruption.
+  if (
+    runtimeStatus?.source !== "startup" &&
+    runtimeStatus !== null &&
+    lastMessage.type !== "stream-error"
+  ) {
     return false;
   }