fix(web-shell): stop rendering unrecognized daemon events in transcripts

docs/developers/daemon-ui/README.md

@@ -367,12 +367,47 @@ function toolIcon(event: DaemonUiToolUpdateEvent): React.ReactNode {
 The SDK has a `mcp__<server>__<tool>` naming heuristic fallback — even
 when daemon doesn't explicitly stamp provenance, MCP tools are detectable.
 
+## Debug reason categorization
+
+`DaemonUiStatusEvent.debugReason` is a closed-enum the normalizer stamps
+when it projects a `debug` block instead of a typed event (mirrored onto
+`DaemonStatusTranscriptBlock` for transcript consumers):
+
+```ts
+import type { DaemonUiDebugReason } from '@qwen-code/sdk/daemon';
+// 'unrecognized_event' | 'unrecognized_session_update' | 'malformed_payload'
+```
+
+The canonical list is exported as `DAEMON_UI_DEBUG_REASONS`. Reason names
+are wildcard-named categories: `unrecognized_*` means the daemon sent a
+frame this SDK version has no case for — forward-compat noise, developer
+diagnostics rather than conversation content. `malformed_*` means a frame
+the SDK _does_ know arrived with an unusable payload — a real defect
+signal.
+
+Renderers should branch on `debugReason`, not the debug text — the text
+prefix is diagnostic wording and changes without notice:
+
+```ts
+function hideDebugBlock(reason?: DaemonUiDebugReason): boolean {
+  // Hide forward-compat noise by category so reasons a newer SDK adds are
+  // covered automatically. Defect signals and client-dispatched debug
+  // events (which carry no reason) keep rendering.
+  return reason?.startsWith('unrecognized_') ?? false;
+}
+```
+
+`status` events never carry a `debugReason`, and neither do debug events
+dispatched by clients themselves (e.g. Web Shell's model-switch summary) —
+both must keep rendering.
+
 ## Forward-compat principles
 
 Every layer in the daemon UI SDK follows the **forward-compat principle**:
 unknown values do NOT throw; they degrade gracefully.
 
-- Unknown daemon event types → `debug` event with the raw type name
+- Unknown daemon event types → `debug` event with the raw type name,
+  stamped with an `unrecognized_*` `debugReason` (see above)
 - Unknown tool status → `currentToolCallId` left untouched (no clear)
 - Unknown error kind → `errorKind` undefined (renderer falls back to text)
 - Missing serverTimestamp → falls back to `clientReceivedAt`

packages/sdk-typescript/src/daemon/index.ts

@@ -88,6 +88,7 @@ export {
   createDaemonTranscriptStore,
   DAEMON_GOAL_STATUS_SENTINEL_PREFIX,
   DAEMON_PLAN_TOOL_CALL_ID,
+  DAEMON_UI_DEBUG_REASONS,
   daemonBlockToHtml,
   daemonBlockToMarkdown,
   daemonBlockToPlainText,
@@ -156,6 +157,7 @@ export type {
   DaemonUiAuthDeviceFlowFailedEvent,
   DaemonUiAuthDeviceFlowStartedEvent,
   DaemonUiAuthDeviceFlowThrottledEvent,
+  DaemonUiDebugReason,
   DaemonUiErrorEvent,
   DaemonUiEvent,
   DaemonUiEventBase,

packages/sdk-typescript/src/daemon/ui/index.ts

@@ -59,7 +59,7 @@ export {
   stringifyJson,
   stripOscSequences,
 } from './utils.js';
-export { DAEMON_PLAN_TOOL_CALL_ID } from './types.js';
+export { DAEMON_PLAN_TOOL_CALL_ID, DAEMON_UI_DEBUG_REASONS } from './types.js';
 export type { DaemonUiContentPart } from './utils.js';
 export type {
   DaemonShellTranscriptBlock,
@@ -83,6 +83,7 @@ export type {
   DaemonTranscriptStore,
   // Chat-stream events
   DaemonUiAssistantDoneEvent,
+  DaemonUiDebugReason,
   DaemonUiErrorEvent,
   DaemonUiEvent,
   DaemonUiEventBase,

packages/sdk-typescript/src/daemon/ui/normalizer.ts

@@ -386,9 +386,9 @@ export function normalizeDaemonEvent(
       // unknown event types, the doubled block-consumption rate
       // accelerated `maxBlocks` trimming of real content. The `debug`
       // shape already carries the event-type as a prefix, so the
-      // status block was redundant. Adapters that want a user-visible
-      // banner can pattern-match on `event.type === 'debug'` and the
-      // text prefix.
+      // status block was redundant. Adapters deciding how to present a
+      // debug block must branch on `debugReason` — the text prefix is
+      // diagnostic wording and changes without notice.
       return normalizeUnrecognizedEvent(event, base);
   }
 }
@@ -401,6 +401,7 @@ function normalizeUnrecognizedEvent(
     {
       ...base,
       type: 'debug',
+      debugReason: 'unrecognized_event',
       text: `${event.type} (unrecognized daemon event): ${stringifyRedactedJson(event.data)}`,
     },
   ];
@@ -682,6 +683,7 @@ function normalizeSessionUpdate(
       {
         ...base,
         type: 'debug',
+        debugReason: 'malformed_payload',
         text: `session_update: ${stringifyRedactedJson(event.data)}`,
       },
     ];
@@ -846,6 +848,16 @@ function normalizeSessionUpdate(
         {
           ...base,
           type: 'debug',
+          // `getSessionUpdatePayload` accepts any record, so `kind` is
+          // `undefined` for a payload whose discriminator is missing, empty or
+          // not a string. That is a broken frame, not a kind from a newer
+          // daemon — classifying it as unrecognized would hide the only
+          // diagnostic a malformed `session_update` produces. A whitespace-only
+          // discriminator is truthy but no more usable than an empty one, so
+          // apply the same `trim()` convention `getFirstString` uses.
+          debugReason: kind?.trim()
+            ? 'unrecognized_session_update'
+            : 'malformed_payload',
           text: `${kind ?? 'session_update'}: ${stringifyRedactedJson(update)}`,
         },
       ];
@@ -1135,6 +1147,7 @@ function normalizePermissionRequest(
       {
         ...base,
         type: 'debug',
+        debugReason: 'malformed_payload',
         text: `permission_request: ${stringifyRedactedJson(event.data)}`,
       },
     ];
@@ -1146,6 +1159,7 @@ function normalizePermissionRequest(
       {
         ...base,
         type: 'debug',
+        debugReason: 'malformed_payload',
         text: `permission_request: ${stringifyRedactedJson(event.data)}`,
       },
     ];
@@ -1179,6 +1193,7 @@ function normalizePermissionResolved(
       {
         ...base,
         type: 'debug',
+        debugReason: 'malformed_payload',
         text: `${event.type}: ${stringifyRedactedJson(event.data)}`,
       },
     ];
@@ -1288,6 +1303,7 @@ function fallbackDebug(
     {
       ...base,
       type: 'debug',
+      debugReason: 'malformed_payload',
       text: `${event.type}: ${reason}`,
     },
   ];

packages/sdk-typescript/src/daemon/ui/transcript.ts

@@ -1247,6 +1247,10 @@ function appendStatusBlock(
     event.data !== undefined
       ? { data: event.data }
       : {}),
+    ...((event?.type === 'status' || event?.type === 'debug') &&
+    event.debugReason
+      ? { debugReason: event.debugReason }
+      : {}),
     ...(event?.type === 'session.branched'
       ? {
           source: 'session_branched',

packages/sdk-typescript/src/daemon/ui/types.ts

@@ -273,11 +273,37 @@ export interface DaemonUiModelChangedEvent extends DaemonUiEventBase {
   modelId: string;
 }
 
+/**
+ * Why the normalizer produced a `debug` projection instead of a typed event.
+ *
+ * `unrecognized_*` means the daemon sent a frame this normalizer has no case
+ * for — expected whenever the daemon runs ahead of the client, and the payload
+ * is developer diagnostics rather than conversation content. `malformed_*`
+ * means a frame the normalizer *does* know arrived with an unusable payload,
+ * which signals an actual defect.
+ *
+ * Renderers should branch on this instead of pattern-matching the debug text:
+ * client-dispatched debug events (e.g. Web Shell's model-switch summary) carry
+ * no `debugReason` at all and must keep rendering.
+ */
+export const DAEMON_UI_DEBUG_REASONS = [
+  'unrecognized_event',
+  'unrecognized_session_update',
+  'malformed_payload',
+] as const;
+
+export type DaemonUiDebugReason = (typeof DAEMON_UI_DEBUG_REASONS)[number];
+
 export interface DaemonUiStatusEvent extends DaemonUiEventBase {
   type: 'status' | 'debug';
   text: string;
   source?: string;
   data?: unknown;
+  /**
+   * Set only on normalizer-produced `debug` events. Absent on `status` events
+   * and on debug events dispatched by clients themselves.
+   */
+  debugReason?: DaemonUiDebugReason;
   /**
    * Client-dispatch opt-out: `false` inserts the status block without
    * finalizing the active assistant/thought block, so read-only command
@@ -914,6 +940,8 @@ export interface DaemonStatusTranscriptBlock extends DaemonTranscriptBlockBase {
   errorKind?: DaemonErrorKind;
   source?: string;
   data?: unknown;
+  /** Mirrors `DaemonUiStatusEvent.debugReason`; only set on `debug` blocks. */
+  debugReason?: DaemonUiDebugReason;
 }
 
 export interface DaemonPromptCancelledTranscriptBlock

packages/sdk-typescript/test/unit/daemon-public-surface.test.ts

@@ -134,10 +134,12 @@ import type {
   DaemonWorkspaceVoiceUpdate,
   KnownDaemonEvent,
 } from '../../src/index.js';
+import { DAEMON_UI_DEBUG_REASONS } from '../../src/daemon/index.js';
 import type {
   DaemonChannelStartupAttemptFailure as DaemonEntryChannelStartupAttemptFailure,
   DaemonChannelStartupFailure as DaemonEntryChannelStartupFailure,
   DaemonChannelWorkerStartErrorResponse as DaemonEntryChannelWorkerStartErrorResponse,
+  DaemonUiDebugReason as DaemonEntryUiDebugReason,
 } from '../../src/daemon/index.js';
 
 describe('public SDK entry — typed daemon event surface (#4217)', () => {
@@ -468,3 +470,22 @@ describe('runtime MCP add/remove SDK types', () => {
     expect(res.removed).toBe(true);
   });
 });
+
+describe('daemon UI debug-reason public surface', () => {
+  it('pins the union shipped by @qwen-code/sdk/daemon', () => {
+    // A type-only guard would not hold here: vitest transpiles through
+    // esbuild, which erases `export type` without checking it, and this
+    // package's tsconfig excludes `test/`, so nothing type-checks this file.
+    // The union therefore ships as a closed enum value — matching
+    // DAEMON_ERROR_KINDS and friends — and the runtime assertion below is
+    // what actually fails if the re-export is dropped or the members drift.
+    expect(DAEMON_UI_DEBUG_REASONS).toEqual([
+      'unrecognized_event',
+      'unrecognized_session_update',
+      'malformed_payload',
+    ]);
+    expectTypeOf<DaemonEntryUiDebugReason>().toEqualTypeOf<
+      'unrecognized_event' | 'unrecognized_session_update' | 'malformed_payload'
+    >();
+  });
+});

packages/sdk-typescript/test/unit/daemonUi.test.ts

@@ -2522,6 +2522,118 @@ describe('daemon UI normalizer — Wave 3/4 event coverage (PR-A)', () => {
     expect(events).toEqual([]);
   });
 
+  it('stamps debugReason on unrecognized daemon events', () => {
+    const events = normalizeDaemonEvent(
+      envelopeOf('some_future_event', { sessionId: 's1' }),
+    );
+
+    expect(events).toEqual([
+      expect.objectContaining({
+        type: 'debug',
+        debugReason: 'unrecognized_event',
+      }),
+    ]);
+  });
+
+  it('stamps debugReason on unrecognized session_update kinds', () => {
+    const events = normalizeDaemonEvent(
+      envelopeOf('session_update', {
+        update: { sessionUpdate: 'some_future_kind', payload: { a: 1 } },
+      }),
+    );
+
+    expect(events).toEqual([
+      expect.objectContaining({
+        type: 'debug',
+        debugReason: 'unrecognized_session_update',
+      }),
+    ]);
+  });
+
+  it('classifies a session_update with no usable discriminator as malformed', () => {
+    // `getSessionUpdatePayload` accepts any record, so these reach the default
+    // branch with `kind === undefined`. They are broken frames, not kinds from
+    // a newer daemon — marking them unrecognized would let renderers hide the
+    // only diagnostic they produce.
+    for (const update of [
+      {},
+      { sessionUpdate: 42 },
+      { sessionUpdate: '' },
+      // Truthy but no more usable than an empty string.
+      { sessionUpdate: '   ' },
+    ]) {
+      expect(
+        normalizeDaemonEvent(envelopeOf('session_update', { update })),
+      ).toEqual([
+        expect.objectContaining({
+          type: 'debug',
+          debugReason: 'malformed_payload',
+        }),
+      ]);
+    }
+  });
+
+  it('stamps debugReason on malformed payloads of known events', () => {
+    const events = normalizeDaemonEvent(
+      envelopeOf('memory_changed', { scope: 'not-a-scope' }),
+    );
+
+    expect(events).toEqual([
+      expect.objectContaining({
+        type: 'debug',
+        debugReason: 'malformed_payload',
+      }),
+    ]);
+  });
+
+  it('carries debugReason through the reducer onto the transcript block', () => {
+    // The normalizer tests above inspect events directly and the Web Shell
+    // adapter tests construct blocks by hand, so neither would notice if the
+    // reducer dropped the field on the way across. Production blocks would
+    // then lose their classification and Web Shell would render raw JSON
+    // again with both suites still green.
+    const state = reduceDaemonTranscriptEvents(
+      createDaemonTranscriptState({ now: 1 }),
+      normalizeDaemonEvent(
+        envelopeOf('some_future_event', { sessionId: 's1' }),
+      ),
+    );
+
+    expect(state.blocks).toEqual([
+      expect.objectContaining({
+        kind: 'debug',
+        debugReason: 'unrecognized_event',
+      }),
+    ]);
+  });
+
+  it('leaves client-dispatched debug blocks without a debugReason', () => {
+    // The mirror of the test above, and the invariant that keeps Web Shell's
+    // model-switch summary visible. Without it, defaulting the field in
+    // `appendStatusBlock` (e.g. `event.debugReason ?? 'unrecognized_event'`)
+    // passes every other test in both suites while silently tagging the
+    // summary as unrecognized, which Web Shell then filters out.
+    const state = reduceDaemonTranscriptEvents(
+      createDaemonTranscriptState({ now: 1 }),
+      [
+        {
+          type: 'debug',
+          text: 'Model switched to qwen3-coder-plus',
+          source: 'model_switch_summary',
+        },
+      ],
+    );
+
+    expect(state.blocks).toHaveLength(1);
+    expect(state.blocks[0]).toEqual(
+      expect.objectContaining({
+        kind: 'debug',
+        source: 'model_switch_summary',
+      }),
+    );
+    expect(state.blocks[0]).not.toHaveProperty('debugReason');
+  });
+
   it('normalizes memory_changed with closed-enum scope + mode', () => {
     const events = normalizeDaemonEvent(
       envelopeOf('memory_changed', {