feat(dashboard): typed stall pill + Send continue button (#4802) (#4804)

* feat(dashboard): typed stall pill + Send continue button (#4802 Cycle-1.5/1.7)

- Zod StallEventPayloadSchema (api/schemas.ts): mirrors server src/stall-events.ts
  bounded ErrorClass enum + 7 typed fields. Path 2 defensive: all fields
  .optional() with safe defaults. Added 'status.stall.typed' to SSEEventTypes
  enum for the new typed stall event.

- StallBadge (components/session/StallBadge.tsx): renders pill from typed
  payload. Color: amber for transient_5xx, red for others. Sub-label:
  'X/Y (auto-recovering...)' or 'X/Y — intervention required'. Kill-switch
  overlay icon when recoveryDisabled.

- SendContinueButton (components/session/SendContinueButton.tsx): AC3b button
  gated on (1) typed payload present, (2) recovery exhausted (attempt >= max),
  (3) kill-switch NOT engaged. Calls POST /v1/sessions/:id/resume.

- stallClassLabels utility: formatStallClassLabel, isRecoveryExhausted,
  isRecoveryDisabled, formatStallSubLabel, formatStallTooltip.

- useStore: added stallMap + setStallMap + clearStallEntry. Path 2 default
  (empty map) until F-9 wires the typed payload to the SSE bus.

- SessionHeader: added StallBadge next to SessionStateBadge.
- SessionDetailPage: added SendContinueButton after PauseControlBar.

Tests: 44 passing (16 stallClassLabels + 8 StallBadge + 20 schemas).

Closes AC2 (visibility pill) and AC3b (Send continue button, gated on
recoveryExhausted). AC3a (auto-recovery) is Hep's #4803. AC4 (telemetry)
is Hep's #4803. F-9 follow-up wires the typed payload to emit sites;
until then, the renderer falls back to generic 'Stalled' pill (Path 2 default).

Close-format (per issuecomment-4767577518 PM canonical re-anchoring):
  Resolved by PR #4803 + PR #<F-9> + PR <daedalus>

Audit-trail anchors cited in PR body:
  4767501614 (3-PR correction, my self-correction)
  4767516114 (precision follow-up)
  4767577518 (PM canonical re-anchoring, single source of truth)
  4767621205 (PM matrix correction, Option B cell)

* fix(dashboard): StallBadge always-conditional guard (Argus review feedback)

- StallBadge: return null when payload has no useful stall data
  (no errorClass AND no recoveryDisabled AND no recovery counter).
  Mirrors SendContinueButton L36 pattern. Prevents misleading 'Stalled'
  pill from rendering for healthy sessions on every page load.

- SessionHeader: gate at callsite with {stallPayload && <StallBadge .../>}
  in addition to the component guard (defense in depth).

- schemas.ts: inline TODO marking removal point for the
  'as unknown as z.ZodType<SessionSSEEvent>' cast once F-9 lands
  and backend's SessionSSEEvent type includes 'status.stall.typed'.

- Tests: added StallBadge.guard.test.tsx (6 new tests) for the
  always-conditional guard; updated obsolete test in StallBadge.test.tsx
  that expected the old 'render generic Stalled' behavior.

Total: 50 tests passing (was 44).

---------

Co-authored-by: Daedalus <daedalus@aegis.local>

Author: OneStepAt4time

dashboard/src/__tests__/StallBadge.guard.test.tsx

@@ -0,0 +1,56 @@
+/**
+ * __tests__/StallBadge.guard.test.tsx — Issue #4802 (Argus review feedback):
+ * always-conditional component integration guard.
+ *
+ * StallBadge must return null when the payload has no useful stall data,
+ * to prevent a misleading "Stalled" pill from rendering for healthy sessions.
+ * Mirrors the SendContinueButton L36 pattern.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { StallBadge } from '../components/session/StallBadge';
+
+describe('Issue #4802: StallBadge always-conditional guard (Argus review)', () => {
+  it('returns null when payload is empty (no stall data)', () => {
+    const { container } = render(<StallBadge payload={{}} />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('returns null when payload has only undefined fields', () => {
+    const { container } = render(
+      <StallBadge payload={{ errorClass: undefined, recoveryDisabled: undefined }} />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('returns null when all counters are 0 (Path 2 default state)', () => {
+    const { container } = render(
+      <StallBadge
+        payload={{ recoveryAttemptCount: 0, recoveryMaxAttempts: 0, recoveryDisabled: false }}
+      />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders when errorClass is present (Path 2 with typed payload)', () => {
+    const { container } = render(
+      <StallBadge payload={{ errorClass: 'transient_5xx' }} />,
+    );
+    expect(container.firstChild).not.toBeNull();
+  });
+
+  it('renders when recoveryDisabled is true (kill-switch overlay)', () => {
+    const { container } = render(
+      <StallBadge payload={{ recoveryDisabled: true }} />,
+    );
+    expect(container.firstChild).not.toBeNull();
+  });
+
+  it('renders when recovery counter is non-zero', () => {
+    const { container } = render(
+      <StallBadge payload={{ recoveryAttemptCount: 3, recoveryMaxAttempts: 5 }} />,
+    );
+    expect(container.firstChild).not.toBeNull();
+  });
+});

dashboard/src/__tests__/StallBadge.test.tsx

@@ -0,0 +1,93 @@
+/**
+ * __tests__/StallBadge.test.tsx — Issue #4802: typed stall pill.
+ *
+ * Path 2 defensive: tests cover both typed payload (post-F-9) and missing
+ * fields (pre-F-9) scenarios. The badge must render gracefully when the
+ * typed payload isn't yet wired to the SSE bus.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { StallBadge } from '../components/session/StallBadge';
+import type { StallEventPayload } from '../api/schemas';
+
+describe('Issue #4802: StallBadge', () => {
+  it('returns null when payload is empty (always-conditional guard, Argus review feedback)', () => {
+    // Empty payload has no useful stall data: no errorClass, no kill-switch,
+    // no recovery counter. StallBadge must NOT render a misleading
+    // 'Stalled' pill for healthy sessions. Mirrors SendContinueButton L36.
+    const { container } = render(<StallBadge payload={{}} />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders typed errorClass label when present', () => {
+    const payload: Partial<StallEventPayload> = {
+      errorClass: 'transient_5xx',
+    };
+    render(<StallBadge payload={payload} />);
+    expect(screen.getByText('Transient 5xx')).toBeDefined();
+  });
+
+  it('renders JSONL Stall label for jsonl_stall class', () => {
+    const payload: Partial<StallEventPayload> = {
+      errorClass: 'jsonl_stall',
+    };
+    render(<StallBadge payload={payload} />);
+    expect(screen.getByText('JSONL Stall')).toBeDefined();
+  });
+
+  it('renders sub-label "X/Y (auto-recovering…)" when not exhausted', () => {
+    const payload: Partial<StallEventPayload> = {
+      errorClass: 'transient_5xx',
+      recoveryAttemptCount: 3,
+      recoveryMaxAttempts: 5,
+    };
+    render(<StallBadge payload={payload} />);
+    expect(screen.getByText('Transient 5xx')).toBeDefined();
+    expect(screen.getByText('3/5 (auto-recovering…)')).toBeDefined();
+  });
+
+  it('renders sub-label "X/Y — intervention required" when exhausted', () => {
+    const payload: Partial<StallEventPayload> = {
+      errorClass: 'transient_5xx',
+      recoveryAttemptCount: 5,
+      recoveryMaxAttempts: 5,
+    };
+    render(<StallBadge payload={payload} />);
+    expect(screen.getByText('5/5 — intervention required')).toBeDefined();
+  });
+
+  it('hides sub-label when max is 0 (Path 2 default)', () => {
+    const payload: Partial<StallEventPayload> = {
+      errorClass: 'transient_5xx',
+      recoveryAttemptCount: 0,
+      recoveryMaxAttempts: 0,
+    };
+    const { container } = render(<StallBadge payload={payload} />);
+    expect(screen.getByText('Transient 5xx')).toBeDefined();
+    expect(container.textContent).not.toContain('0/0');
+  });
+
+  it('renders kill-switch overlay when recoveryDisabled', () => {
+    const payload: Partial<StallEventPayload> = {
+      errorClass: 'transient_5xx',
+      recoveryAttemptCount: 2,
+      recoveryMaxAttempts: 5,
+      recoveryDisabled: true,
+    };
+    render(<StallBadge payload={payload} />);
+    // Kill-switch icon has aria-label "Auto-recovery paused (operator kill-switch)"
+    expect(screen.getByLabelText('Auto-recovery paused (operator kill-switch)')).toBeDefined();
+  });
+
+  it('marks data-stall-exhausted when cap is reached', () => {
+    const payload: Partial<StallEventPayload> = {
+      errorClass: 'transient_5xx',
+      recoveryAttemptCount: 5,
+      recoveryMaxAttempts: 5,
+    };
+    const { container } = render(<StallBadge payload={payload} />);
+    const badge = container.querySelector('[data-stall-exhausted]');
+    expect(badge).not.toBeNull();
+  });
+});

dashboard/src/__tests__/stallClassLabels.test.ts

@@ -0,0 +1,127 @@
+/**
+ * __tests__/stallClassLabels.test.ts — Issue #4802: stall label + state helpers.
+ *
+ * Path 2 defensive: tests cover both typed payload (post-F-9) and missing
+ * fields (pre-F-9) scenarios. The renderer must degrade gracefully when the
+ * typed payload isn't yet wired to the SSE bus.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  STALL_CLASS_LABELS,
+  STALL_GENERIC_LABEL,
+  formatStallClassLabel,
+  formatStallSubLabel,
+  isRecoveryExhausted,
+  isRecoveryDisabled,
+  formatStallTooltip,
+} from '../utils/stallClassLabels';
+
+describe('Issue #4802: stall label utilities', () => {
+  describe('formatStallClassLabel', () => {
+    it('maps each ErrorClass to a display label', () => {
+      for (const [key, expected] of Object.entries(STALL_CLASS_LABELS)) {
+        expect(formatStallClassLabel(key as never)).toBe(expected);
+      }
+    });
+
+    it('returns generic label for missing errorClass (Path 2 default)', () => {
+      expect(formatStallClassLabel(undefined)).toBe(STALL_GENERIC_LABEL);
+      expect(formatStallClassLabel(null)).toBe(STALL_GENERIC_LABEL);
+    });
+
+    it('returns generic label for unknown string', () => {
+      // Runtime guard at server side rejects these; renderer is defensive.
+      expect(formatStallClassLabel('5xx_529' as never)).toBe(STALL_GENERIC_LABEL);
+    });
+  });
+
+  describe('isRecoveryExhausted', () => {
+    it('returns true when attempt >= max (both > 0)', () => {
+      expect(isRecoveryExhausted({ recoveryAttemptCount: 5, recoveryMaxAttempts: 5 })).toBe(true);
+      expect(isRecoveryExhausted({ recoveryAttemptCount: 6, recoveryMaxAttempts: 5 })).toBe(true);
+    });
+
+    it('returns false when attempt < max', () => {
+      expect(isRecoveryExhausted({ recoveryAttemptCount: 3, recoveryMaxAttempts: 5 })).toBe(false);
+    });
+
+    it('returns false when attempt < max', () => {
+      expect(isRecoveryExhausted({ recoveryAttemptCount: 1, recoveryMaxAttempts: 5 })).toBe(false);
+    });
+
+    it('returns false when max is 0 (Path 2 default — unknown)', () => {
+      expect(isRecoveryExhausted({ recoveryAttemptCount: 0, recoveryMaxAttempts: 0 })).toBe(false);
+      expect(isRecoveryExhausted({})).toBe(false);
+    });
+
+    it('returns false when only max is set, attempt is missing', () => {
+      expect(isRecoveryExhausted({ recoveryMaxAttempts: 5 })).toBe(false);
+    });
+  });
+
+  describe('formatStallSubLabel', () => {
+    it('returns "X/Y (auto-recovering…)" when not exhausted', () => {
+      expect(formatStallSubLabel({ recoveryAttemptCount: 3, recoveryMaxAttempts: 5 })).toBe(
+        '3/5 (auto-recovering…)',
+      );
+    });
+
+    it('returns "X/Y — intervention required" when exhausted', () => {
+      expect(formatStallSubLabel({ recoveryAttemptCount: 5, recoveryMaxAttempts: 5 })).toBe(
+        '5/5 — intervention required',
+      );
+    });
+
+    it('returns null when max is 0 (Path 2 default — sub-label hidden)', () => {
+      expect(formatStallSubLabel({ recoveryAttemptCount: 0, recoveryMaxAttempts: 0 })).toBeNull();
+      expect(formatStallSubLabel({})).toBeNull();
+    });
+  });
+
+  describe('isRecoveryDisabled', () => {
+    it('returns true when recoveryDisabled === true', () => {
+      expect(isRecoveryDisabled({ recoveryDisabled: true })).toBe(true);
+    });
+
+    it('returns false when recoveryDisabled is false or missing (Path 2 default)', () => {
+      expect(isRecoveryDisabled({ recoveryDisabled: false })).toBe(false);
+      expect(isRecoveryDisabled({})).toBe(false);
+    });
+  });
+
+  describe('formatStallTooltip', () => {
+    it('composes metadata-only tooltip (no transcript text)', () => {
+      const tooltip = formatStallTooltip({
+        errorClass: 'transient_5xx',
+        statusCode: 529,
+        lastErrorAt: '2026-06-22T12:00:00.000Z',
+        stallDurationMs: 600000, // 10 minutes
+        recoveryAttemptCount: 3,
+        recoveryMaxAttempts: 5,
+      });
+      expect(tooltip).toContain('Transient 5xx');
+      expect(tooltip).toContain('529');
+      expect(tooltip).toContain('2026-06-22T12:00:00.000Z');
+      expect(tooltip).toContain('10m');
+      expect(tooltip).toContain('3/5');
+      expect(tooltip).not.toContain('detail'); // F-6 redaction discipline
+    });
+
+    it('omits statusCode for non-transient_5xx classes', () => {
+      const tooltip = formatStallTooltip({
+        errorClass: 'jsonl_stall',
+        statusCode: 529, // would be invalid in real payload, but defensive
+        recoveryAttemptCount: 1,
+        recoveryMaxAttempts: 5,
+      });
+      expect(tooltip).toContain('JSONL Stall');
+      expect(tooltip).not.toContain('529');
+    });
+
+    it('handles missing fields gracefully (Path 2 default)', () => {
+      const tooltip = formatStallTooltip({});
+      expect(tooltip).toBe('Stalled'); // just the generic label
+    });
+  });
+});

dashboard/src/api/schemas.ts

@@ -368,9 +368,10 @@ const SSEEventTypes = z.enum([
   'subagent_stop',
   'verification',
   'permission_denied',
+  'status.stall.typed',
 ]);
 
-export const SessionSSEEventDataSchema: z.ZodType<SessionSSEEvent> = z.object({
+export const SessionSSEEventDataSchema = z.object({
   event: SSEEventTypes,
   sessionId: z.string(),
   timestamp: z.string(),
@@ -380,7 +381,15 @@ export const SessionSSEEventDataSchema: z.ZodType<SessionSSEEvent> = z.object({
 }).transform((event) => ({
   ...event,
   data: event.data ?? {},
-}));
+})) as unknown as z.ZodType<SessionSSEEvent>;
+// TODO(#4802 F-9 follow-up): Remove the `as unknown as z.ZodType<SessionSSEEvent>`
+// cast once the backend's `SessionSSEEvent` type (src/api-contracts.ts) includes
+// `'status.stall.typed'` in its `event` field union. At that point, F-9 has
+// wired `buildStallEventPayload()` into the 12 emit sites, the typed stall
+// payload flows in the wire, and the Zod enum in this file matches the
+// backend's TypeScript union. The cast was needed because the new
+// `'status.stall.typed'` event name was added to the local Zod enum
+// ahead of the backend type update (forward-compatibility for the renderer).
 
 // ── Global SSE Event (Issue #410) ──────────────────────────────
 
@@ -440,3 +449,59 @@ export const WsInboundMessageSchema = z.discriminatedUnion('type', [
   WsStreamMessageSchema,
   WsErrorMessageSchema,
 ]);
+
+// ── Stall Event Payload (Issue #4802) ────────────────────────────
+
+/**
+ * Bounded ErrorClass enum mirroring server `src/stall-events.ts`.
+ * Renderer maps these to the dashboard pill label. Adding a new value is a
+ * schema PR that gets reviewed — schema drift cannot grow unchecked.
+ *
+ * Server-side isErrorClass() rejects unknown values, defending against
+ * prompt-injection inputs that try to inject new errorClass values.
+ */
+export const ErrorClassSchema = z.enum([
+  'transient_5xx',
+  'permission_timeout',
+  'jsonl_stall',
+  'thinking_stall',
+  'unknown_stall',
+  'extended_working',
+]);
+
+/** TypeScript type for the ErrorClass bounded enum (derived from ErrorClassSchema). */
+export type ErrorClass = z.infer<typeof ErrorClassSchema>;
+
+/**
+ * Zod schema for StallEventPayload, mirroring server `src/stall-events.ts`.
+ *
+ * Path 2 defensive defaults: all fields are `.optional()` with safe fallbacks.
+ * - Pre-F-9 (typed payload not yet wired to SSE bus): fields are missing, the
+ *   renderer falls back to a generic "Stalled" pill with no sub-label or
+ *   AC3b button. Safe default.
+ * - Post-F-9 (typed payload wired to SSE bus): fields populate, full pill
+ *   (errorClass label + sub-label + AC3b button) renders.
+ *
+ * `recoveryExhausted` is NOT in the server's StallEventPayload yet — the
+ * renderer computes "exhausted" locally from
+ * `recoveryAttemptCount >= recoveryMaxAttempts` (when both > 0).
+ */
+export const StallEventPayloadSchema = z.object({
+  errorClass: ErrorClassSchema.optional(),
+  statusCode: z.number().int().min(100).max(599).optional(),
+  lastErrorAt: z.string().optional(),
+  stallDurationMs: z.number().nonnegative().optional(),
+  recoveryAttemptCount: z.number().int().nonnegative().optional(),
+  recoveryMaxAttempts: z.number().int().nonnegative().optional(),
+  recoveryDisabled: z.boolean().optional(),
+}).transform((p) => ({
+  errorClass: p.errorClass,
+  statusCode: p.statusCode,
+  lastErrorAt: p.lastErrorAt,
+  stallDurationMs: p.stallDurationMs ?? 0,
+  recoveryAttemptCount: p.recoveryAttemptCount ?? 0,
+  recoveryMaxAttempts: p.recoveryMaxAttempts ?? 0,
+  recoveryDisabled: p.recoveryDisabled ?? false,
+}));
+
+export type StallEventPayload = z.infer<typeof StallEventPayloadSchema>;