@pellux/goodvibes-tui 1.0.0 → 1.7.0

package/src/core/approval-alert.ts

@@ -0,0 +1,72 @@
+/**
+ * approval-alert — fires an unfocused-user alert the moment a tool call
+ * becomes a real, user-blocking permission prompt.
+ *
+ * Anchor: `PERMISSION_REQUESTED` (SDK events/permissions.ts) is the wrong
+ * signal — it fires for every policy-evaluation step, including ones
+ * auto-resolved by allow-lists/yolo-mode in milliseconds. The only place a
+ * request becomes an actual user-facing prompt is where main.ts assigns
+ * `permissionPromptRef.requestPermission`. There is no `permissions` feed on
+ * UiRuntimeEvents to subscribe to instead, so this wraps the handler at that
+ * assignment site.
+ *
+ * wrapRequestPermissionWithAlert fires the alert synchronously (before the
+ * wrapped promise settles) so it reflects "a prompt just appeared", not
+ * "a prompt was just resolved".
+ *
+ * PRIVACY: message content is tool name + permission category only — no
+ * args, no file contents, no command strings (mirrors long-task-notifier's
+ * privacy guarantee).
+ */
+import { notifyCompletion } from '@pellux/goodvibes-sdk/platform/utils';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type { WebhookNotifier } from '@pellux/goodvibes-sdk/platform/integrations';
+import type { PermissionRequestHandler, PermissionPromptRequest } from '@pellux/goodvibes-sdk/platform/permissions';
+import type { FocusTracker } from './focus-tracker.ts';
+import { shouldFireAlert, FORCE_NOTIFY_DURATION_MS, type ConfigGet } from './alert-gating.ts';
+
+export interface ApprovalAlertDeps {
+  readonly focusTracker: Pick<FocusTracker, 'shouldAlertWhenUnfocused'>;
+  readonly configGet: ConfigGet;
+  readonly webhookNotifier?: WebhookNotifier | null;
+}
+
+/**
+ * Wrap a PermissionRequestHandler so every call also fires an unfocused-user
+ * alert (subject to the behavior.notifyOnApprovalPending / notifyOnlyWhenUnfocused
+ * gates). The wrapped handler's behavior (what it resolves to) is completely
+ * unchanged — this only adds a side effect at call time.
+ */
+export function wrapRequestPermissionWithAlert(
+  original: PermissionRequestHandler,
+  deps: ApprovalAlertDeps,
+): PermissionRequestHandler {
+  return (request: PermissionPromptRequest) => {
+    fireApprovalAlert(request, deps);
+    return original(request);
+  };
+}
+
+function fireApprovalAlert(request: PermissionPromptRequest, deps: ApprovalAlertDeps): void {
+  if (!shouldFireAlert(deps.focusTracker, deps.configGet, 'behavior.notifyOnApprovalPending')) return;
+
+  const title = 'GoodVibes — approval needed';
+  // PRIVACY: tool name + category only. Never request.args.
+  const message = `${request.tool} (${request.category}) is waiting for approval`;
+
+  try {
+    notifyCompletion(title, message, FORCE_NOTIFY_DURATION_MS);
+  } catch (err) {
+    logger.debug('approval-alert: desktop notify error', { error: String(err) });
+  }
+
+  const webhookNotifier = deps.webhookNotifier;
+  if (webhookNotifier) {
+    const urls = webhookNotifier.getUrls();
+    if (urls.length > 0) {
+      webhookNotifier.send(message).catch((err: unknown) => {
+        logger.debug('approval-alert: webhook send error', { error: String(err) });
+      });
+    }
+  }
+}

package/src/core/budget-breach-notifier.ts

@@ -0,0 +1,106 @@
+/**
+ * budget-breach-notifier — fires an unfocused-user alert the moment session
+ * cost crosses the configured budget threshold (behavior.budgetAlertUsd).
+ *
+ * One-shot semantics: fires exactly once on the false→true edge (crossing
+ * into breach), never again while still over budget on every subsequent
+ * turn. The "already notified" latch resets when the session drops back
+ * under budget (so a later re-breach can fire again) or when the threshold
+ * itself changes (raising, lowering, or clearing the budget re-arms it
+ * against the new value).
+ *
+ * Delivery mirrors long-task-notifier.ts: desktop notification
+ * (notifyCompletion) + outbound webhook (WebhookNotifier), both gated by
+ * the shared focus/config gating in alert-gating.ts. Skips evaluation
+ * entirely when the session model is unpriced — a $0 placeholder cost must
+ * never be reported as a real breach (mirrors CostTrackerPanel's "unpriced"
+ * display convention).
+ *
+ * PRIVACY: message text is built from cost/threshold numbers and the
+ * session id prefix only — no conversation content.
+ */
+import { notifyCompletion } from '@pellux/goodvibes-sdk/platform/utils';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+import type { WebhookNotifier } from '@pellux/goodvibes-sdk/platform/integrations';
+import { calcSessionCost, computeBudgetBreach, isModelPriced } from '../export/cost-utils.ts';
+import type { FocusTracker } from './focus-tracker.ts';
+import { shouldFireAlert, FORCE_NOTIFY_DURATION_MS, type ConfigGet } from './alert-gating.ts';
+
+export interface BudgetBreachUsageSnapshot {
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+}
+
+export interface BudgetBreachNotifierDeps {
+  readonly focusTracker: Pick<FocusTracker, 'shouldAlertWhenUnfocused'>;
+  readonly configGet: ConfigGet;
+  readonly webhookNotifier?: WebhookNotifier | null;
+  readonly sessionId: string;
+}
+
+/** Stateful edge-trigger checker — construct once per session, call on every TURN_COMPLETED. */
+export interface BudgetBreachNotifier {
+  /**
+   * Evaluate current usage against the configured threshold and fire an
+   * alert on the false→true breach edge. Returns true when an alert was
+   * fired this call (for tests / observability), false otherwise.
+   */
+  check(usage: BudgetBreachUsageSnapshot, sessionModel: string, budgetThresholdUsd: number): boolean;
+}
+
+export function createBudgetBreachNotifier(deps: BudgetBreachNotifierDeps): BudgetBreachNotifier {
+  let lastThreshold: number | null = null;
+  let notified = false;
+
+  return {
+    check(usage, sessionModel, budgetThresholdUsd) {
+      if (budgetThresholdUsd !== lastThreshold) {
+        // Threshold raised, lowered, or cleared since the last check — re-arm
+        // the latch so a breach against the new threshold can fire again.
+        lastThreshold = budgetThresholdUsd;
+        notified = false;
+      }
+
+      if (budgetThresholdUsd <= 0) return false; // disabled
+      if (!isModelPriced(sessionModel)) return false; // cost would be a placeholder, not real
+
+      const sessionCost = calcSessionCost(usage.input, usage.output, usage.cacheRead, usage.cacheWrite, sessionModel);
+      const breached = computeBudgetBreach(sessionCost, budgetThresholdUsd);
+
+      if (!breached) {
+        notified = false; // dropped back under budget — can re-fire on the next crossing
+        return false;
+      }
+      if (notified) return false; // already alerted for this crossing
+
+      notified = true;
+      fireBudgetBreachAlert(deps, sessionCost, budgetThresholdUsd);
+      return true;
+    },
+  };
+}
+
+function fireBudgetBreachAlert(deps: BudgetBreachNotifierDeps, sessionCost: number, budgetThresholdUsd: number): void {
+  if (!shouldFireAlert(deps.focusTracker, deps.configGet, 'behavior.notifyOnBudgetBreach')) return;
+
+  const title = 'GoodVibes — budget breach';
+  const message = `session cost $${sessionCost.toFixed(2)} exceeded budget $${budgetThresholdUsd.toFixed(2)}  ·  session ${deps.sessionId.slice(0, 8)}`;
+
+  try {
+    notifyCompletion(title, message, FORCE_NOTIFY_DURATION_MS);
+  } catch (err) {
+    logger.debug('budget-breach-notifier: desktop notify error', { error: String(err) });
+  }
+
+  const webhookNotifier = deps.webhookNotifier;
+  if (webhookNotifier) {
+    const urls = webhookNotifier.getUrls();
+    if (urls.length > 0) {
+      webhookNotifier.send(message).catch((err: unknown) => {
+        logger.debug('budget-breach-notifier: webhook send error', { error: String(err) });
+      });
+    }
+  }
+}

package/src/core/conversation-rendering.ts

@@ -3,6 +3,7 @@ import { renderMarkdownTracked } from '../renderer/markdown.ts';
 import { renderDiffView } from '../renderer/diff-view.ts';
 import { DARK_THEME } from '../renderer/theme.ts';
 import { renderToolCallBlock } from '../renderer/tool-call.ts';
+import type { ToolCall } from '@pellux/goodvibes-sdk/platform/types';
 import { renderThinkingBlock } from '../renderer/thinking.ts';
 import { renderSystemMessage } from '../renderer/system-message.ts';
 import { createEmptyLine, type Line, type Cell } from '../types/grid.ts';
@@ -402,3 +403,21 @@ export function logConversationText(
   const lines = text.split('\n').map((line) => UIFactory.stringToLine(indent + line, width, style));
   context.history.addLines(lines);
 }
+
+/**
+ * logConversationToolResult - Append a single tool-call-style result line to the
+ * display history only, reusing renderToolCallBlock so a display-only render (e.g.
+ * a slash command's subprocess result) is visually indistinguishable from the
+ * model's own tool-call results. Display-only: never touches message history.
+ */
+export function logConversationToolResult(
+  context: Pick<ConversationRenderContext, 'history'>,
+  width: number,
+  toolCall: ToolCall,
+  status: 'done' | 'error',
+  resultSummary: string,
+  durationMs: number,
+  errorMsg?: string,
+): void {
+  context.history.addLines(renderToolCallBlock(toolCall, status, resultSummary, width, durationMs, errorMsg));
+}

package/src/core/conversation.ts

@@ -18,6 +18,7 @@ import {
   addConversationSplashScreen,
   conversationTextToLines,
   logConversationText,
+  logConversationToolResult,
   renderConversationAssistantMessage,
   renderConversationSystemMessage,
   renderConversationToolMessage,
@@ -49,6 +50,46 @@ export type { BlockMeta };
 import type { ConversationMessageSnapshot } from '@pellux/goodvibes-sdk/platform/core';
 type Message = ConversationMessageSnapshot;
 
+/** Matches Orchestrator.usage's shape (SDK platform/core/orchestrator.ts). Not
+ * exported by the SDK as a standalone type, so mirrored here. */
+export interface OrchestratorUsageTotals {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/**
+ * sumConversationUsage - Fold every assistant message's per-turn usage into
+ * running totals, plus the *last* assistant message's own input-token figure
+ * (context-window occupancy — not a running sum).
+ *
+ * TUI-side counterpart to SDK Orchestrator.usage: after a session resume
+ * replays historical messages into a freshly-constructed Orchestrator (whose
+ * `usage` starts at all zeros — bootstrap.ts always constructs a fresh
+ * instance, see W0.9), this lets the caller hydrate the footer's token
+ * counters from messages that already carry real usage data instead of
+ * waiting for the first new turn to populate them.
+ */
+export function sumConversationUsage(
+  messages: readonly ConversationMessageSnapshot[],
+): { usage: OrchestratorUsageTotals; lastInputTokens: number } {
+  const usage: OrchestratorUsageTotals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  let lastInputTokens = 0;
+  for (const message of messages) {
+    if (message.role !== 'assistant' || !message.usage) continue;
+    usage.input += message.usage.inputTokens;
+    usage.output += message.usage.outputTokens;
+    usage.cacheRead += message.usage.cacheReadTokens ?? 0;
+    usage.cacheWrite += message.usage.cacheWriteTokens ?? 0;
+    // Context-window occupancy tracks the most recent turn only, not a sum.
+    lastInputTokens = message.usage.inputTokens
+      + (message.usage.cacheReadTokens ?? 0)
+      + (message.usage.cacheWriteTokens ?? 0);
+  }
+  return { usage, lastInputTokens };
+}
+
 export class ConversationManager extends SdkConversationManager {
   public history = new InfiniteBuffer();
   private _getWidth: () => number;
@@ -687,6 +728,23 @@ export class ConversationManager extends SdkConversationManager {
     logConversationText(this.renderingContext(), this._getWidth(), text, style, indent);
   }
 
+  /**
+   * logToolResultBlock - Append a single tool-call-styled result line to the display
+   * history only (never touches the LLM message list), so a slash command's subprocess
+   * result (e.g. /test) renders visually identical to a real tool-call result without
+   * leaking into model context.
+   */
+  public logToolResultBlock(
+    toolCall: ToolCall,
+    status: 'done' | 'error',
+    resultSummary: string,
+    durationMs: number,
+    errorMsg?: string,
+  ): void {
+    logConversationToolResult(this.renderingContext(), this._getWidth(), toolCall, status, resultSummary, durationMs, errorMsg);
+    this.markDirty();
+  }
+
   /**
    * clearDisplay - Clear the visual history buffer without touching the LLM context messages.
    * The next render will show a blank conversation area. Subsequent message additions

package/src/core/focus-tracker.ts

@@ -0,0 +1,41 @@
+/**
+ * focus-tracker — tracks whether the terminal window currently has OS-level
+ * input focus, using the terminal focus-reporting protocol (DECSET ?1004h,
+ * enabled at terminal setup in main.ts). The SDK's InputTokenizer already
+ * parses the resulting `\x1b[I` (focus-in) / `\x1b[O` (focus-out) sequences
+ * into `{ type: 'focus', action }` tokens (platform/core/tokenizer.ts); this
+ * module is the single place those tokens land (consumed in
+ * src/input/handler-feed.ts's feedInputTokens()).
+ *
+ * Honest degradation: a terminal that does not implement focus reporting
+ * (or a multiplexer that swallows the sequences) never sends focus tokens.
+ * In that case `isFocused()` stays `null` forever — "unknown", never a
+ * guessed `true`/`false`. Callers that gate a user-facing behavior on focus
+ * (e.g. the unfocused-alert notifiers in this directory) must treat `null`
+ * the same as "not focused" per the fallback rule: alerts fire when the
+ * terminal is definitely unfocused OR when focus state was never observed.
+ */
+export class FocusTracker {
+  private focused: boolean | null = null;
+
+  /** True/false once at least one focus token has arrived; null if none ever has. */
+  isFocused(): boolean | null {
+    return this.focused;
+  }
+
+  /** Called from the input pipeline on every focus token. */
+  setFocused(value: boolean): void {
+    this.focused = value;
+  }
+
+  /**
+   * The alert-gating rule shared by every unfocused-alert notifier: fire
+   * when the terminal is known to be unfocused, or when focus was never
+   * observed (honest fallback — never silently suppress on an unknown
+   * terminal). Only `isFocused() === true` (a real, observed focus-in with
+   * no observed focus-out since) suppresses an alert.
+   */
+  shouldAlertWhenUnfocused(): boolean {
+    return this.focused !== true;
+  }
+}

package/src/core/long-task-notifier.ts

@@ -18,15 +18,21 @@
  * When neither target is available the function is an honest no-op (debug log
  * only; no user-facing error spam).
  *
- * Focus tracking: terminal focus state is not tracked anywhere in the TUI.
- * Notifications therefore fire regardless of whether the terminal window is
- * focused. A future implementation may suppress notifications when the TUI is
- * in the foreground by reading a focus-state ref. // seam: wire focus ref here.
+ * Focus tracking (W2.3): when `focusTracker` is supplied, notifications are
+ * gated the same way as the other unfocused-user alert classes (see
+ * alert-gating.ts) — they fire when the terminal is unfocused or focus state
+ * was never observed, and are suppressed when it's known to be focused,
+ * unless `behavior.notifyOnlyWhenUnfocused` is turned off. `focusTracker` is
+ * optional and defaults to "always fire" (the pre-W2.3 behavior) when
+ * omitted, so existing callers that don't have a FocusTracker in scope are
+ * unaffected.
  */
 
 import { notifyCompletion } from '@pellux/goodvibes-sdk/platform/utils';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import type { WebhookNotifier } from '@pellux/goodvibes-sdk/platform/integrations';
+import type { FocusTracker } from './focus-tracker.ts';
+import { readNotifyOnlyWhenUnfocused, type ConfigGet } from './alert-gating.ts';
 
 /** Default threshold in seconds. Turns shorter than this do not notify. */
 export const NOTIFY_AFTER_SECONDS_DEFAULT = 60;
@@ -74,6 +80,18 @@ export interface MaybeNotifyLongTaskOptions {
    * skipped silently.
    */
   readonly webhookNotifier?: WebhookNotifier | null;
+
+  /**
+   * Terminal focus tracker (W2.3). When supplied together with `configGet`,
+   * the notification additionally respects behavior.notifyOnlyWhenUnfocused
+   * (default on): suppressed when the terminal is known to be focused, fires
+   * when unfocused or when focus was never observed. Omit both to preserve
+   * pre-W2.3 behavior (always fire once the threshold is met).
+   */
+  readonly focusTracker?: Pick<FocusTracker, 'shouldAlertWhenUnfocused'> | null;
+
+  /** Config reader used only for the notifyOnlyWhenUnfocused gate above. */
+  readonly configGet?: ConfigGet;
 }
 
 /**
@@ -81,13 +99,14 @@ export interface MaybeNotifyLongTaskOptions {
  * exceeds the configured threshold.
  *
  * Returns true when at least one delivery was attempted, false when the
- * call was a no-op (threshold not reached, or off-state).
+ * call was a no-op (threshold not reached, off-state, or focus-gated off —
+ * see `focusTracker`/`configGet` above).
  *
  * PRIVACY: builds message text from structural metadata only (kind, elapsed,
  * status, sessionId). Never includes conversation content.
  */
 export function maybeNotifyLongTask(opts: MaybeNotifyLongTaskOptions): boolean {
-  const { elapsedMs, status, kind, sessionId, thresholdSeconds, webhookNotifier } = opts;
+  const { elapsedMs, status, kind, sessionId, thresholdSeconds, webhookNotifier, focusTracker, configGet } = opts;
 
   // Off-state: 0 disables notifications entirely.
   if (thresholdSeconds === NOTIFY_AFTER_SECONDS_OFF) {
@@ -102,6 +121,14 @@ export function maybeNotifyLongTask(opts: MaybeNotifyLongTaskOptions): boolean {
     return false;
   }
 
+  // Focus gate (W2.3): only applied when both a tracker and a config reader
+  // are supplied. Absent either one, behavior is unchanged from pre-W2.3
+  // (always fire once the threshold is met).
+  if (focusTracker && configGet && readNotifyOnlyWhenUnfocused(configGet) && !focusTracker.shouldAlertWhenUnfocused()) {
+    logger.debug('long-task-notifier: suppressed — terminal focused');
+    return false;
+  }
+
   // Build concise, metadata-only message. No conversation text.
   const statusLabel = status === 'ok' ? 'completed' : 'failed';
   const title = `GoodVibes — ${kind} ${statusLabel}`;

package/src/core/stream-event-wiring.ts

@@ -23,6 +23,29 @@ export interface StreamMetrics {
   activeToolStartedAtMs: number | undefined;
   /** Name of the currently executing tool; cleared when execution completes. */
   activeToolName: string | undefined;
+  /**
+   * Epoch ms of the most recent STREAM_START or STREAM_DELTA; undefined when
+   * idle (no turn in flight). Read every render frame — not just on the
+   * watchdog's one-shot hint — so "ms since last byte" can be computed even
+   * when no new SDK event has arrived at all (a no-delta stall watchdog for
+   * the render loop itself, independent of the low-priority system message).
+   */
+  lastDeltaAtMs: number | undefined;
+  /**
+   * 1-based count of stall episodes the watchdog has fired for the current
+   * turn; 0 = no stall yet. Increments each time a fresh silence (after a
+   * recovery) crosses the stall threshold.
+   */
+  stallEpisode: number;
+  /**
+   * Populated from the SDK's STREAM_RETRY event when present. SDK 0.35.0 (the
+   * pinned dependency) has no such event on the TurnEvent union yet — these
+   * fields are consumed structurally (see looseTurnsFeed below) and stay
+   * undefined until a future SDK version emits it. Cleared on STREAM_DELTA
+   * (a byte arriving means the reconnect, if any, succeeded).
+   */
+  reconnectAttempt: number | undefined;
+  reconnectMaxAttempts: number | undefined;
 }
 
 /** Minimal orchestrator surface required for stream token-speed calculation. */
@@ -60,6 +83,33 @@ interface StreamSystemMessageRouter {
   low(message: string): void;
 }
 
+/**
+ * Loosely-typed variant of the turns event feed, used only to subscribe to
+ * event names not yet present in the SDK's TurnEvent union (STREAM_RETRY,
+ * STREAM_STALL — see the structural-consumption comment at the subscription
+ * site below). `events.turns.on` itself stays fully typed against the real
+ * TurnEvent union everywhere else in this file.
+ */
+interface LooseTurnEventFeed {
+  on(type: string, listener: (payload: unknown) => void): () => void;
+}
+
+/** Payload shape expected from a future SDK STREAM_RETRY event. */
+interface StreamRetryLikePayload {
+  readonly attempt: number;
+  readonly maxAttempts: number;
+}
+
+/** Runtime guard validating an unknown STREAM_RETRY-like payload's shape. */
+function isStreamRetryLikePayload(payload: unknown): payload is StreamRetryLikePayload {
+  return (
+    typeof payload === 'object' &&
+    payload !== null &&
+    typeof (payload as Record<string, unknown>).attempt === 'number' &&
+    typeof (payload as Record<string, unknown>).maxAttempts === 'number'
+  );
+}
+
 /**
  * Minimal cost lookup surface for attaching cost-delta information to failover notices.
  * Returns USD-per-1M-token pricing for the given model ID.
@@ -197,10 +247,19 @@ export function wireStreamEventMetrics(
     metrics.tokenSpeed = 0;
     metrics.ttftMs = undefined;
     metrics.ttftRecorded = false;
+    metrics.lastDeltaAtMs = Date.now();
+    metrics.stallEpisode = 0;
+    metrics.reconnectAttempt = undefined;
+    metrics.reconnectMaxAttempts = undefined;
   }));
 
   unsubs.push(events.turns.on('STREAM_DELTA', () => {
     metrics.deltaCount++;
+    metrics.lastDeltaAtMs = Date.now();
+    // A byte arrived: any in-flight reconnect (if the SDK reported one)
+    // has succeeded.
+    metrics.reconnectAttempt = undefined;
+    metrics.reconnectMaxAttempts = undefined;
     const elapsed = (Date.now() - metrics.startTime) / 1000;
     // Record TTFT on the first delta of each turn.
     if (!metrics.ttftRecorded) {
@@ -296,10 +355,16 @@ export function wireStreamEventMetrics(
     render();
   }));
 
-  // --- Stream stall watchdog: emit one low hint if STREAM_START has no delta within 30s ---
+  // --- Stream stall watchdog: emit a low hint each time a no-delta gap (at
+  // start of turn OR mid-stream, after a re-arm) crosses 30s. The transient
+  // system message below is the initial alert; streamMetrics.stallEpisode
+  // (read every render frame) drives the persistent "stalled Ns" indicator
+  // in the thinking fragment, so the two coexist rather than conflict — the
+  // message announces the stall, the indicator tracks it ongoing.
   const stallWatchdog = createStreamStallWatchdog({
     events: events.turns,
-    onStall: (providerName) => {
+    onStall: (providerName, episode) => {
+      metrics.stallEpisode = episode;
       systemMessageRouter.low(`Still waiting on ${providerName}… Ctrl+C to cancel`);
       render();
     },
@@ -308,22 +373,59 @@ export function wireStreamEventMetrics(
   });
   unsubs.push(() => stallWatchdog.dispose());
 
+  // --- Structural consumption of STREAM_RETRY / STREAM_STALL ---
+  // Neither event exists on the pinned SDK's (0.35.0) TurnEvent union today —
+  // both are proposed additions for the transport-level withRetry() callback
+  // (see the stall-honesty audit brief). The typed `events.turns.on` feed
+  // rejects unknown event names at compile time, so this casts the feed to a
+  // loosely-typed variant and validates each payload with a runtime guard
+  // instead of importing a type name that doesn't exist yet — same pattern
+  // used elsewhere in this codebase for settings pending SDK schema additions
+  // (see src/input/settings-modal-data.ts). Compiles today against 0.35.0;
+  // lights up automatically once the SDK adds the real event.
+  const looseTurnsFeed = events.turns as unknown as LooseTurnEventFeed;
+  unsubs.push(looseTurnsFeed.on('STREAM_RETRY', (payload) => {
+    if (!isStreamRetryLikePayload(payload)) return;
+    metrics.reconnectAttempt = payload.attempt;
+    metrics.reconnectMaxAttempts = payload.maxAttempts;
+    render();
+  }));
+  unsubs.push(looseTurnsFeed.on('STREAM_STALL', () => {
+    // Informational only: the TUI's own createStreamStallWatchdog above is
+    // the authoritative no-delta detector and already drives the visible
+    // indicator via streamMetrics.stallEpisode. This subscription exists so
+    // the SDK's own signal (once it lands) is observed rather than silently
+    // dropped, without duplicating or fighting the local watchdog.
+    render();
+  }));
+
   unsubs.push(events.tools.on('TOOL_EXECUTING', (ev) => {
     metrics.activeToolStartedAtMs = ev.startedAt;
     metrics.activeToolName = ev.tool;
     render();
   }));
+  // On every tool-completion path, reset lastDeltaAtMs to "now" so the
+  // post-tool silence window starts fresh. Tool execution suppresses stall
+  // detection at the render call site (see main.ts), but lastDeltaAtMs itself
+  // keeps its pre-tool value the whole time the tool runs — without this
+  // reset, the instant a tool completes (potentially long after the last real
+  // delta), the very next frame would read msSinceLastDelta as the full
+  // tool-execution duration and immediately report a stall, even though the
+  // model hasn't had a chance to resume producing tokens yet.
   unsubs.push(events.tools.on('TOOL_SUCCEEDED', () => {
     metrics.activeToolStartedAtMs = undefined;
     metrics.activeToolName = undefined;
+    metrics.lastDeltaAtMs = Date.now();
   }));
   unsubs.push(events.tools.on('TOOL_FAILED', () => {
     metrics.activeToolStartedAtMs = undefined;
     metrics.activeToolName = undefined;
+    metrics.lastDeltaAtMs = Date.now();
   }));
   unsubs.push(events.tools.on('TOOL_CANCELLED', () => {
     metrics.activeToolStartedAtMs = undefined;
     metrics.activeToolName = undefined;
+    metrics.lastDeltaAtMs = Date.now();
   }));
 
   let _errorSurfacedCb: ((exhausted: boolean) => void) | undefined;

package/src/core/stream-stall-watchdog.ts

@@ -1,15 +1,26 @@
 /**
- * StreamStallWatchdog — detects STREAM_START events where no STREAM_DELTA
- * arrives within a configurable threshold, and emits a single low-priority
- * hint to the user.
+ * StreamStallWatchdog — detects gaps of silence (no STREAM_DELTA) longer than
+ * a configurable threshold, whether the gap is at the start of a turn or in
+ * the middle of an otherwise-flowing stream, and emits a low-priority hint
+ * each time a gap crosses the threshold.
  *
  * Design:
- *   - Arm on STREAM_START: set a timeout for STALL_THRESHOLD_MS.
- *   - Disarm on STREAM_DELTA: clear the pending timeout (stream is alive).
+ *   - Arm on STREAM_START: reset the episode counter, set a timeout for
+ *     STALL_THRESHOLD_MS.
+ *   - Re-arm on STREAM_DELTA: every byte received resets the no-delta clock,
+ *     so a stall that begins mid-stream (after tokens were already flowing)
+ *     is caught just as reliably as a stall at turn start. This is the fix
+ *     for the "silence after the first delta never re-triggers" gap: the
+ *     previous behaviour disarmed permanently on the first STREAM_DELTA,
+ *     which meant a multi-minute stall after output had already started
+ *     produced zero indication.
  *   - Disarm on STREAM_END / TURN_COMPLETED / TURN_ERROR / TURN_CANCEL:
  *     clear the timeout (turn finished normally or with error).
- *   - If the timeout fires: emit ONE hint, do NOT repeat until the next turn.
- *   - Re-arm only on the next STREAM_START (next turn).
+ *   - If the timeout fires: emit ONE hint for that episode (do not repeat
+ *     while the same gap continues), then wait for the gap to close (another
+ *     STREAM_DELTA/STREAM_START) before a further silence can fire again —
+ *     each such re-arm-then-timeout cycle is a new "stall episode" and the
+ *     episode counter passed to onStall increments each time.
  *   - dispose(): clears all subscriptions and any pending timeout.
  *
  * @module
@@ -32,10 +43,13 @@ export interface StreamStallWatchdogOptions {
   /** The turns event surface to subscribe on. */
   events: WatchdogTurnEvents;
   /**
-   * Called once per turn when the stall threshold is exceeded.
-   * Receives the provider display name for the hint message.
+   * Called once per stall episode when the no-delta threshold is exceeded.
+   * Receives the provider display name and a 1-based episode counter that
+   * increments each time a new silence (after a re-arm) crosses the
+   * threshold within the same turn — so a second mid-stream stall after a
+   * recovery is distinguishable from the first.
    */
-  onStall: (providerName: string) => void;
+  onStall: (providerName: string, episode: number) => void;
   /**
    * Provides the current provider display name at the moment the hint fires.
    * Optional — defaults to 'provider' when not supplied.
@@ -63,17 +77,19 @@ export function createStreamStallWatchdog(opts: StreamStallWatchdogOptions): Str
   const { events, onStall, getProviderName, thresholdMs = STALL_THRESHOLD_MS } = opts;
 
   let stallTimer: ReturnType<typeof setTimeout> | null = null;
-  let hintFiredForTurn = false;
+  let hintFiredForEpisode = false;
+  let episodeCount = 0;
 
   function arm(): void {
     disarm();
-    hintFiredForTurn = false;
+    hintFiredForEpisode = false;
     stallTimer = setTimeout(() => {
       stallTimer = null;
-      if (!hintFiredForTurn) {
-        hintFiredForTurn = true;
+      if (!hintFiredForEpisode) {
+        hintFiredForEpisode = true;
+        episodeCount++;
         const provider = getProviderName ? getProviderName() : 'provider';
-        onStall(provider);
+        onStall(provider, episodeCount);
       }
     }, thresholdMs);
   }
@@ -85,9 +101,17 @@ export function createStreamStallWatchdog(opts: StreamStallWatchdogOptions): Str
     }
   }
 
+  function onStreamStart(): void {
+    episodeCount = 0;
+    arm();
+  }
+
   const unsubs: Array<() => void> = [
-    events.on('STREAM_START', arm),
-    events.on('STREAM_DELTA', disarm),
+    events.on('STREAM_START', onStreamStart),
+    // Re-arm (not disarm) on every delta: the no-delta clock must reset on
+    // each byte so a stall that starts mid-stream is still caught, not just
+    // a stall before the first byte.
+    events.on('STREAM_DELTA', arm),
     events.on('STREAM_END', disarm),
     events.on('TURN_COMPLETED', disarm),
     events.on('TURN_ERROR', disarm),