@stigmer/react 3.0.8-dev.20260613041848 → 3.0.8-dev.20260613051837

package/src/internal/store/__tests__/conversation-store.test.ts

@@ -190,6 +190,67 @@ describe("ConversationStore", () => {
     });
   });
 
+  describe("watchdog signals", () => {
+    it("connectTimedOut: defaults false, notifies only on change", () => {
+      const store = new ConversationStore();
+      expect(store.getConnectTimedOut()).toBe(false);
+
+      const listener = vi.fn();
+      store.subscribe(listener);
+
+      store.setConnectTimedOut(true);
+      expect(store.getConnectTimedOut()).toBe(true);
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      store.setConnectTimedOut(true);
+      expect(listener).toHaveBeenCalledTimes(1); // no-op on same value
+
+      store.setConnectTimedOut(false);
+      expect(store.getConnectTimedOut()).toBe(false);
+      expect(listener).toHaveBeenCalledTimes(2);
+    });
+
+    it("isSlow: defaults false, notifies only on change", () => {
+      const store = new ConversationStore();
+      expect(store.getSlow()).toBe(false);
+
+      const listener = vi.fn();
+      store.subscribe(listener);
+
+      store.setSlow(true);
+      expect(store.getSlow()).toBe(true);
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      store.setSlow(true);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("reset clears both watchdog signals", () => {
+      const store = new ConversationStore();
+      store.setConnectTimedOut(true);
+      store.setSlow(true);
+
+      const listener = vi.fn();
+      store.subscribe(listener);
+
+      store.reset();
+      expect(store.getConnectTimedOut()).toBe(false);
+      expect(store.getSlow()).toBe(false);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("reset notifies when only a watchdog signal was set", () => {
+      const store = new ConversationStore();
+      store.setSlow(true);
+
+      const listener = vi.fn();
+      store.subscribe(listener);
+
+      store.reset();
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe("reset", () => {
     it("clears execution and stream state", () => {
       const store = new ConversationStore();

package/src/internal/store/conversation-store.ts

@@ -51,6 +51,8 @@ type Listener = () => void;
 export class ConversationStore {
   private _execution: AgentExecution | null = null;
   private _streamState: StreamState = IDLE_STATE;
+  private _connectTimedOut = false;
+  private _isSlow = false;
   private _listeners = new Set<Listener>();
 
   // -- Ingestion -----------------------------------------------------------
@@ -77,16 +79,47 @@ export class ConversationStore {
     this._notify();
   }
 
+  /**
+   * Set the hard connect-timeout signal — the stream opened but no first
+   * snapshot arrived within the watchdog window even after a silent retry.
+   *
+   * Orthogonal to {@link setStreamState}: the stream may still be live, so
+   * this is **not** a lifecycle stage and deliberately does not touch the
+   * `error` stage (that is auto-reconnect's domain). Booleans are stable by
+   * value, so no snapshot caching is needed; listeners fire only on change.
+   */
+  setConnectTimedOut(value: boolean): void {
+    if (this._connectTimedOut === value) return;
+    this._connectTimedOut = value;
+    this._notify();
+  }
+
+  /**
+   * Set the soft slow-stall hint — the stream is non-terminal but has gone
+   * silent past the watchdog window. Purely informational ("still working,
+   * taking longer than usual"); cleared by the next snapshot. Never aborts.
+   */
+  setSlow(value: boolean): void {
+    if (this._isSlow === value) return;
+    this._isSlow = value;
+    this._notify();
+  }
+
   /**
    * Reset to initial state. Used when the session identity changes
    * or the hook unmounts.
    */
   reset(): void {
-    const wasIdle =
-      this._execution === null && this._streamState.stage === "idle";
+    const wasClean =
+      this._execution === null &&
+      this._streamState.stage === "idle" &&
+      !this._connectTimedOut &&
+      !this._isSlow;
     this._execution = null;
     this._streamState = IDLE_STATE;
-    if (!wasIdle) this._notify();
+    this._connectTimedOut = false;
+    this._isSlow = false;
+    if (!wasClean) this._notify();
   }
 
   // -- useSyncExternalStore contract ---------------------------------------
@@ -112,6 +145,16 @@ export class ConversationStore {
     return this._streamState;
   };
 
+  /** Stable snapshot selector for the hard connect-timeout signal. */
+  getConnectTimedOut = (): boolean => {
+    return this._connectTimedOut;
+  };
+
+  /** Stable snapshot selector for the soft slow-stall hint. */
+  getSlow = (): boolean => {
+    return this._isSlow;
+  };
+
   // -- Internal ------------------------------------------------------------
 
   private _notify(): void {

package/src/internal/stream-controller.ts

@@ -14,6 +14,20 @@ import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 
 const IDLE: StreamState = { stage: "idle" };
 
+/**
+ * Hard connect-timeout: time the stream may stay `connecting` (no first
+ * snapshot) before the watchdog acts. Sized well above a healthy connect
+ * (the server sends the initial snapshot in ~1 RTT) yet short enough that a
+ * silent hang surfaces an affordance within a few seconds, not minutes.
+ */
+export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+/**
+ * Soft slow-stall threshold: a non-terminal stream that produces no new
+ * snapshot for this long flips an informational "still working" hint. Long
+ * enough that ordinary model thinking-time never trips it.
+ */
+export const DEFAULT_SLOW_THRESHOLD_MS = 60_000;
+
 /**
  * Callback interface for the stream controller to communicate with
  * its host (the React hook). All mutations to external state go
@@ -24,6 +38,27 @@ export interface StreamControllerSink {
   ingestSnapshot(snapshot: AgentExecution): void;
   /** Transition the store's stream lifecycle state. */
   setStreamState(state: StreamState): void;
+  /**
+   * The hard connect-timeout elapsed while still `connecting`. The host owns
+   * the self-heal-once-then-surface policy (it holds the `connectKey` reconnect
+   * counter and the per-subscription guard that survives a reconnect, which
+   * the controller — reset on every teardown — cannot).
+   */
+  onConnectTimeout(): void;
+  /** Set or clear the soft slow-stall hint signal. */
+  setSlow(value: boolean): void;
+}
+
+/**
+ * Injectable watchdog configuration. Timers default to `setTimeout`/
+ * `clearTimeout`; tests pass fakes so the watchdog is exercised without real
+ * time. Mirrors the existing `scheduleFlush`/`cancelFlush` injection idiom.
+ */
+export interface StreamControllerWatchdog {
+  readonly setTimer?: (cb: () => void, ms: number) => number;
+  readonly clearTimer?: (id: number) => void;
+  readonly connectTimeoutMs?: number;
+  readonly slowThresholdMs?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -52,6 +87,14 @@ export class StreamController {
   private _scheduleFlush: (cb: () => void) => number;
   private _cancelFlush: (id: number) => void;
 
+  // -- Watchdog ------------------------------------------------------------
+  private _setTimer: (cb: () => void, ms: number) => number;
+  private _clearTimer: (id: number) => void;
+  private _connectTimeoutMs: number;
+  private _slowThresholdMs: number;
+  private _connectTimerId: number | null = null;
+  private _slowTimerId: number | null = null;
+
   constructor(
     sink: StreamControllerSink,
     scheduleFlush: (cb: () => void) => number = typeof requestAnimationFrame !== "undefined"
@@ -60,10 +103,19 @@ export class StreamController {
     cancelFlush: (id: number) => void = typeof cancelAnimationFrame !== "undefined"
       ? (id: number) => cancelAnimationFrame(id)
       : (id: number) => clearTimeout(id),
+    watchdog?: StreamControllerWatchdog,
   ) {
     this._sink = sink;
     this._scheduleFlush = scheduleFlush;
     this._cancelFlush = cancelFlush;
+    this._setTimer =
+      watchdog?.setTimer ??
+      ((cb, ms) => setTimeout(cb, ms) as unknown as number);
+    this._clearTimer = watchdog?.clearTimer ?? ((id) => clearTimeout(id));
+    this._connectTimeoutMs =
+      watchdog?.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    this._slowThresholdMs =
+      watchdog?.slowThresholdMs ?? DEFAULT_SLOW_THRESHOLD_MS;
   }
 
   /** Current FSM state (read-only). */
@@ -78,6 +130,11 @@ export class StreamController {
   start(executionId: string): void {
     this._cancelPendingFlush();
     this._bufferedSnapshot = null;
+    // Arm both watchdogs the moment we begin connecting. The connect-timeout
+    // guards the first snapshot; the slow-stall hint guards every quiet stretch
+    // thereafter. Both are reset by the next snapshot and cleared on any exit.
+    this._armConnectTimer();
+    this._armSlowTimer();
     this._transition({ stage: "connecting", executionId });
   }
 
@@ -95,13 +152,19 @@ export class StreamController {
     const terminal = isTerminalPhase(phase);
 
     if (terminal) {
+      this._cancelWatchdogs();
+      this._sink.setSlow(false);
       this._cancelPendingFlush();
       this._bufferedSnapshot = null;
       this._sink.ingestSnapshot(snapshot);
       this._transition({ stage: "complete", executionId });
     } else {
-      // A snapshot proves the (re)connection is healthy: advance from either
-      // the initial `connecting` or a `reconnecting` retry into `streaming`.
+      // A snapshot proves the (re)connection is healthy: the connect-timeout no
+      // longer applies, and the slow-stall window restarts from now.
+      this._cancelConnectTimer();
+      this._armSlowTimer();
+      // Advance from either the initial `connecting` or a `reconnecting` retry
+      // into `streaming`.
       if (
         this._state.stage === "connecting" ||
         this._state.stage === "reconnecting"
@@ -123,6 +186,12 @@ export class StreamController {
   handleReconnecting(attempt: number, error: Error): void {
     const executionId = this._activeExecutionId();
     if (!executionId) return;
+    // Auto-reconnect (#174) has taken over with its own visible affordance and
+    // bounded attempt budget, so the silence watchdogs stand down — they exist
+    // for the case where the stream stalls *without* a drop. The slow hint is
+    // cleared so "reconnecting" and "slow" never show at once.
+    this._cancelWatchdogs();
+    this._sink.setSlow(false);
     this._transition({ stage: "reconnecting", executionId, attempt, error });
   }
 
@@ -134,6 +203,8 @@ export class StreamController {
     const executionId = this._activeExecutionId();
     if (!executionId) return;
 
+    this._cancelWatchdogs();
+    this._sink.setSlow(false);
     this._flushBuffer();
     if (this._state.stage !== "complete") {
       this._transition({ stage: "complete", executionId });
@@ -148,13 +219,17 @@ export class StreamController {
     const executionId = this._activeExecutionId();
     if (!executionId) return;
 
+    this._cancelWatchdogs();
+    this._sink.setSlow(false);
     this._cancelPendingFlush();
     this._flushBuffer();
     this._transition({ stage: "error", executionId, error });
   }
 
-  /** Reset to idle. Cancels any pending flush. */
+  /** Reset to idle. Cancels any pending flush and watchdog timers. */
   reset(): void {
+    this._cancelWatchdogs();
+    this._sink.setSlow(false);
     this._cancelPendingFlush();
     this._bufferedSnapshot = null;
     if (this._state.stage !== "idle") {
@@ -203,4 +278,49 @@ export class StreamController {
       this._rafId = null;
     }
   }
+
+  // -- Watchdog timers ------------------------------------------------------
+
+  private _armConnectTimer(): void {
+    this._cancelConnectTimer();
+    this._connectTimerId = this._setTimer(() => {
+      this._connectTimerId = null;
+      // Only meaningful while still awaiting the first snapshot; any later
+      // stage has its own handling and has already cleared this timer.
+      if (this._state.stage !== "connecting") return;
+      this._sink.onConnectTimeout();
+    }, this._connectTimeoutMs);
+  }
+
+  private _armSlowTimer(): void {
+    this._cancelSlowTimer();
+    // Re-arming means activity just resumed (or is starting), so a prior slow
+    // hint no longer holds — clear it before counting the next quiet stretch.
+    this._sink.setSlow(false);
+    this._slowTimerId = this._setTimer(() => {
+      this._slowTimerId = null;
+      if (this._state.stage !== "connecting" && this._state.stage !== "streaming")
+        return;
+      this._sink.setSlow(true);
+    }, this._slowThresholdMs);
+  }
+
+  private _cancelConnectTimer(): void {
+    if (this._connectTimerId !== null) {
+      this._clearTimer(this._connectTimerId);
+      this._connectTimerId = null;
+    }
+  }
+
+  private _cancelSlowTimer(): void {
+    if (this._slowTimerId !== null) {
+      this._clearTimer(this._slowTimerId);
+      this._slowTimerId = null;
+    }
+  }
+
+  private _cancelWatchdogs(): void {
+    this._cancelConnectTimer();
+    this._cancelSlowTimer();
+  }
 }

package/src/internal/useFetch.ts

@@ -15,6 +15,14 @@ export interface UseFetchOptions {
    */
   readonly refetchInterval?: number | false;
 
+  /**
+   * Re-fetch when the window regains focus or the tab becomes visible
+   * again. Covers the app-relaunch / tab-switch case where data may have
+   * gone stale while the app was backgrounded. A focus refetch is skipped
+   * while a fetch is already in flight. Defaults to `false`.
+   */
+  readonly refetchOnWindowFocus?: boolean;
+
   /**
    * Stable string key for cross-mount caching.
    *
@@ -183,6 +191,24 @@ export function useFetch<T>(
     return () => clearInterval(id);
   }, [refetchInterval, fetchFn, refetch]);
 
+  const refetchOnWindowFocus = options?.refetchOnWindowFocus;
+  useEffect(() => {
+    if (!refetchOnWindowFocus || !fetchFn) return;
+    if (typeof window === "undefined") return;
+    const onActive = () => {
+      if (!isFetchingRef.current) refetch();
+    };
+    const onVisible = () => {
+      if (document.visibilityState === "visible") onActive();
+    };
+    window.addEventListener("focus", onActive);
+    document.addEventListener("visibilitychange", onVisible);
+    return () => {
+      window.removeEventListener("focus", onActive);
+      document.removeEventListener("visibilitychange", onVisible);
+    };
+  }, [refetchOnWindowFocus, fetchFn, refetch]);
+
   const isLoading = isFetching && !hasDataRef.current;
   const isRefetching = isFetching && hasDataRef.current;
 

package/src/session/SessionViewer.tsx

@@ -290,12 +290,24 @@ function ConversationColumn({
   const { conv } = flow;
   const sendError = flow.submitError ?? conv.sendError ?? conv.approvalError;
 
+  // Retry a terminal-failed execution by resending its originating message
+  // through the full submit pipeline (agent override, runtime-env, workspace).
+  const onRetryExecution = useCallback(
+    (message: string) => {
+      void flow.handleSubmit(message);
+    },
+    [flow.handleSubmit],
+  );
+
   return (
     <div className="flex h-full min-w-0 flex-col">
       <MessageThread
         executions={conv.completedExecutions}
         activeStreamExecution={conv.activeStreamExecution}
         pendingUserMessage={conv.pendingUserMessage}
+        pendingMessageFailed={!!conv.sendError && !!conv.pendingUserMessage}
+        onRetrySend={conv.retryLastSend}
+        onRetryExecution={onRetryExecution}
         onApprovalSubmit={flow.submitApproval}
         submittingApprovalIds={conv.submittingApprovalIds}
         workspaceEntries={conv.workspaceEntries}
@@ -308,6 +320,10 @@ function ConversationColumn({
       />
       <div className="mx-auto w-full max-w-3xl">
         {conv.isReconnecting && <ReconnectingIndicator />}
+        {conv.connectTimedOut && (
+          <ConnectTimedOutBanner onRetry={conv.reconnectStream} />
+        )}
+        {conv.isSlow && !conv.connectTimedOut && <SlowIndicator />}
         {conv.streamError && (
           <StreamErrorBanner
             error={conv.streamError}
@@ -573,6 +589,52 @@ function ReconnectingIndicator() {
   );
 }
 
+/**
+ * Actionable banner for the connect-timeout watchdog: the stream opened but
+ * never delivered a first snapshot — the agent hasn't started. Mirrors
+ * {@link StreamErrorBanner}'s shape (message + Retry) since both resolve via
+ * the same `reconnect()` path, but its copy names the specific failure.
+ */
+function ConnectTimedOutBanner({ onRetry }: { onRetry: () => void }) {
+  return (
+    <div role="alert" className="flex items-center gap-3 border-t border-border bg-muted px-4 py-2.5">
+      <p className="min-w-0 flex-1 truncate text-sm text-muted-foreground">
+        The agent hasn&rsquo;t started yet.
+      </p>
+      <button
+        type="button"
+        onClick={onRetry}
+        className="inline-flex shrink-0 items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs font-medium hover:bg-card"
+      >
+        Retry
+      </button>
+    </div>
+  );
+}
+
+/**
+ * Low-weight informational hint for the slow-stall watchdog: a live stream has
+ * gone quiet longer than usual. Never an error and offers no action — the
+ * stream is still expected to resume on its own.
+ */
+function SlowIndicator() {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="flex items-center gap-2 border-t border-border-muted px-4 py-1.5 text-xs text-muted-foreground"
+    >
+      <span className="relative flex h-2 w-2 shrink-0" aria-hidden="true">
+        <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-muted-foreground opacity-75 motion-reduce:animate-none" />
+        <span className="relative inline-flex h-2 w-2 rounded-full bg-muted-foreground" />
+      </span>
+      <span className="min-w-0 flex-1 truncate">
+        Still working — this is taking longer than usual.
+      </span>
+    </div>
+  );
+}
+
 function StreamErrorBanner({
   error,
   onReconnect,

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

@@ -306,6 +306,59 @@ describe("useSessionConversation", () => {
     });
   });
 
+  it("preserves the message and surfaces sendError when the send fails", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+    methods.executionCreate.mockRejectedValue(new Error("create boom"));
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.sendFollowUp("keep me");
+    });
+
+    // The failure is surfaced and the user's text is NOT lost.
+    expect(result.current.sendError?.message).toBe("create boom");
+    expect(result.current.pendingUserMessage).toBe("keep me");
+  });
+
+  it("retryLastSend resubmits the same message after a failure", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+    methods.executionCreate.mockRejectedValueOnce(new Error("boom"));
+    const retried = makeExecution("e-retry", ExecutionPhase.EXECUTION_PENDING);
+    retried.metadata!.id = "e-retry";
+    methods.executionCreate.mockResolvedValue(retried);
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.sendFollowUp("retry me");
+    });
+    expect(result.current.sendError).not.toBeNull();
+
+    await act(async () => {
+      result.current.retryLastSend();
+    });
+
+    await waitFor(() =>
+      expect(methods.executionCreate).toHaveBeenCalledTimes(2),
+    );
+    expect(methods.executionCreate).toHaveBeenLastCalledWith(
+      expect.objectContaining({ message: "retry me" }),
+    );
+    // The retry cleared the prior failure for the new attempt.
+    expect(result.current.sendError).toBeNull();
+  });
+
   it("full follow-up lifecycle: active execution completes → canSendFollowUp → sendFollowUp succeeds", async () => {
     // Start with one IN_PROGRESS execution (simulates a Cursor execution running)
     const activeExec = makeExecution("exec-1", ExecutionPhase.EXECUTION_IN_PROGRESS);