@sema-agent/client-core 0.12.2 → 0.13.0

package/dist/adapter/downstream/eventToSdkMessage.d.ts

@@ -35,21 +35,62 @@
  */
 import type { AgentEvent, CheckpointGate } from '@sema-agent/sdk';
 import { type SDKMessage, type EmitContext, type ModelUsage } from '../types.js';
+/** 「本切片不投影这条臂」的**如实分类**(REF-CC-058 / xlate-04)。 */
+export type EventProjectionNoneReason = 
+/** `turn_end`:usage 折叠是 run driver 的活(`turnEndUsage`),本层无独立可渲染臂。 */
+'usage_only'
+/** `done`/`failed`:终帧由 `terminalToSdkResult` 投影。 */
+ | 'terminal_delegated'
+/** `suspended`:HITL 登记是 run driver 的活(out of slice)。 */
+ | 'hitl_out_of_slice'
+/** 已在 SDK union 里、但本切片**有意**不投影的臂(逐条理由见各 case 注释)。 */
+ | 'not_in_slice'
 /**
- * Project one durable/live `AgentEvent` into zero-or-one renderable `SDKMessage`.
+ * 臂在本切片内、帧也不畸形,但**载荷筛完是空的**(今天唯一来源:`suggestions` 全被空白过滤掉)。
+ * 单列一档的理由与 REF-CC-058 本身同源:把它并进 `not_in_slice` 会说「这条臂我们不投影」——
+ * 那是假话(我们投影它,只是这一帧没内容);并进 `dropped` 则是把引擎的正常空批诬告成丢帧。
+ */
+ | 'empty_payload';
+/** 「这条臂我看不懂/嫌它坏,丢了」的**如实分类**(REF-CC-057/058)。 */
+export type EventProjectionDropReason = 
+/** 帧在但必填位畸形(非串 runId / 空 files / 空 source …)—— 引擎发了,我们读不动。 */
+'malformed'
+/** 类型面根本不认识这条臂(引擎比本包新)。 */
+ | 'unknown_arm';
+/**
+ * 投影结果三态(REF-CC-058 / xlate-04,A1 禁哨兵值双义 + C6 降级必须可分辨)。
+ *
+ * 收编前返回型是 `SDKMessage | null`,而那个 `null` 在 10 个 return 点上同时承载三种互不相同的
+ * 语义:①设计内无可渲染臂;②帧畸形被丢弃;③未知新臂被吞。调用方拿到 null **无法分辨**「本来
+ * 就没东西渲」和「引擎发了一帧但我看不懂」—— 本文件历史上所有「帧到了没人读」事故(suggestions
+ * 死信、workflow lane 两键被剥)的载体就是这个塌缩。三态命名后,`dropped` 是可被上报的信号,
+ * driver 侧据此闭合 REF-CC-057 的下泄口。
+ */
+export type EventProjection = {
+    kind: 'message';
+    message: SDKMessage;
+} | {
+    kind: 'none';
+    why: EventProjectionNoneReason;
+} | {
+    kind: 'dropped';
+    why: EventProjectionDropReason;
+    type: string;
+};
+/**
+ * Project one durable/live `AgentEvent` into a typed {@link EventProjection}.
  *
  * `tool_end` projects to a NEUTRAL internal `tool_end_result` arm (NOT a CC
  * SDKMessage the renderer reads) carrying the §E1 wire `output` so the bridge can
  * close the open card with the real body.
  *
- * Returns `null` for arms that carry no standalone renderable message in this
- * slice:
- *  - `turn_end` → usage rollup only, surfaced via `turnEndUsage` below;
- *  - `suspended` → HITL registration is the run driver's job (out of slice).
- *
  * Terminal `done`/`failed` are delegated to `terminalToSdkResult`.
+ *
+ * 🔴 BREAKING(REF-CC-058,0.13.0):返回型由 `SDKMessage | null` 改为三态 Result。
+ * 迁移判据一句话:`const p = eventToSdkMessage(ev, ctx); if (p.kind === 'message') …` ——
+ * 旧写法 `if (msg)` 在新返回型上恒真(对象永远 truthy),所以这是**必须点名**的一类改动。
  */
-export declare function eventToSdkMessage(ev: AgentEvent, ctx: EmitContext): SDKMessage | null;
+export declare function eventToSdkMessage(ev: AgentEvent, ctx: EmitContext): EventProjection;
 /**
  * CS-7 §2.7 — turn_end usage → CC `ModelUsage` (pinned name mapping;
  * costMicroUsd/1e6 → costUSD). Surfaced separately because the slice has no
@@ -67,12 +108,13 @@ export declare function turnEndUsage(ev: Extract<AgentEvent, {
  * ⚠️ DEAD CODE — 不是「HITL 分支漏接」(2026-07-26 全树核查,task #81 顺带件):
  *   · 全树(src/ + mock/ + build/ + 测试)**零调用点**,adapter facade(src/seam/adapter/index.ts)
  *     也没把它再导出去 —— 没有任何一处「本该调它却没调」。
- *   · 它想服务的那条 HITL 分支**已经接好了**,只是没走这个函数:
- *       - `suspended` 事件臂 → `src/seam/adapter/upstream/hitlBridge.ts:162-168` 的 `observe()`
- *         就地做了**同款**防御回落(`ev.gate ? ev.gate : { kind: 'human' }`),而且 latch 的是整个
- *         CheckpointGate 对象,壳侧 `currentGate()` 自己 branch `gate.kind`;
- *       - `done{status:'suspended', checkpointGate}` 终帧 → `liveHitlAskWire.ts:89-118` /
- *         `terminalToSdkResult.ts:296-311` 各自读 `checkpointGate.kind` **和** `.toolName`。
+ *   · 它想服务的那条 HITL 分支**已经接好了**,只是没走这个函数(REF-CC-063:此处原为四个行号锚,
+ *     今天全部已腐,改符号锚):
+ *       - `suspended` 事件臂 → `hitl/hitlBridge.ts` 的 `HitlBridge.observe()` 就地做了**同款**防御
+ *         回落(`ev.gate ? ev.gate : { kind: 'human' }`),而且 latch 的是整个 CheckpointGate 对象,
+ *         壳侧 `currentGate()` 自己 branch `gate.kind`;
+ *       - `done{status:'suspended', checkpointGate}` 终帧 → `liveHitlAskWire.ts` 的 ask 合成口 /
+ *         `terminalToSdkResult.ts` 的 park 臂各自读 `checkpointGate.kind` **和** `.toolName`。
  *   · 关键:每个真实消费方都同时需要 `toolName`(挑 Ask overlay vs fs 写门三选卡),而本函数只吐
  *     一个 kind 字符串 —— 签名比任何真实需求都窄,接进去反而要再读一次 gate。
  *   结论 = 可删的死码(留档不擅删,按 task #81 口径只标记);真要收,连同 `CheckpointGate` 的

package/dist/adapter/downstream/eventToSdkMessage.js

@@ -11,6 +11,14 @@ import { turnUsageToModelUsage } from './turnUsageToModelUsage.js';
 function armBody(body) {
     return body;
 }
+/**
+ * `suggestions` 批的防御性上界(REF-CC-061 / xlate-07,A3 魔数命名)。UI 面的界,不是模型面 ——
+ * 这条臂的文本**绝不回喂模型**(见 `case 'suggestions'` 头注)。
+ * 命名的意义不只是可读:裸字面量对域词表门是隐形的,而这两个数决定「用户少看见几条建议」。
+ */
+const SUGGESTION_BATCH_CAP = 8;
+/** 单条建议的字符上界;超出截断并留可见痕迹(尾部 `…`)。 */
+const SUGGESTION_CHARS_CAP = 200;
 /** Wrap neutral content blocks in the CC `assistant` message envelope. */
 function assistantArm(ctx, content) {
     return stamp(ctx, armBody({
@@ -31,120 +39,74 @@ function streamEventArm(ctx, event) {
         parent_tool_use_id: null,
     }));
 }
+const projected = (message) => ({ kind: 'message', message });
+const nothing = (why) => ({ kind: 'none', why });
+const dropped = (why, type) => ({ kind: 'dropped', why, type });
+/**
+ * B5 穷举卫兵:union 加成员必须在**编译期**打红这个 switch,而不是让新臂在用户面静默丢帧。
+ * 运行期仍会走到这里 —— wire 是 JSON,引擎完全可能比本包的类型新一版(那正是 `unknown_arm`)。
+ */
+function assertNeverArm(_ev) {
+    /* 类型面穷举断言;运行期由调用点返回 typed dropped */
+}
 /**
- * Project one durable/live `AgentEvent` into zero-or-one renderable `SDKMessage`.
+ * Project one durable/live `AgentEvent` into a typed {@link EventProjection}.
  *
  * `tool_end` projects to a NEUTRAL internal `tool_end_result` arm (NOT a CC
  * SDKMessage the renderer reads) carrying the §E1 wire `output` so the bridge can
  * close the open card with the real body.
  *
- * Returns `null` for arms that carry no standalone renderable message in this
- * slice:
- *  - `turn_end` → usage rollup only, surfaced via `turnEndUsage` below;
- *  - `suspended` → HITL registration is the run driver's job (out of slice).
- *
  * Terminal `done`/`failed` are delegated to `terminalToSdkResult`.
+ *
+ * 🔴 BREAKING(REF-CC-058,0.13.0):返回型由 `SDKMessage | null` 改为三态 Result。
+ * 迁移判据一句话:`const p = eventToSdkMessage(ev, ctx); if (p.kind === 'message') …` ——
+ * 旧写法 `if (msg)` 在新返回型上恒真(对象永远 truthy),所以这是**必须点名**的一类改动。
  */
 export function eventToSdkMessage(ev, ctx) {
     // service 1.75 — `workflow_complete`: an out-of-band background-workflow completion push, ridden onto
-    // the session's next stream open (BEFORE the run's own events). SDK ≥0.0.108 已入 union(注记过时
-    // 已修;G8 的收敛方向候 P1-3);raw 读形保留待 B4 帧分派批统一 typed 化。 Projects to a
-    // NEUTRAL internal arm; the upstream bridge turns it into CC's `<task-notification>` injection.
+    // the session's next stream open (BEFORE the run's own events). Projects to a NEUTRAL internal arm;
+    // the upstream bridge turns it into CC's `<task-notification>` injection.
+    // 🔴 REF-CC-060(xlate-06)真码核对:P1 镜头按注释判「五条 raw 臂里四条已入 union」,逐字核
+    // `@sema-agent/sdk` 3.0.0 的 `AgentEvent` 后**部分证伪** —— task_notification / diagnostics /
+    // steering_injected / workspace_changed 四条确已入 union(已搬进下方 switch 成为正式 case),
+    // 而 `workflow_complete` **至今不在 union 里**(与那几条注释自称的相反)。故本臂是**唯一**
+    // 保留的 raw 预分派臂,`raw` 变量也随之收窄到这一条。到期复核:每次 SDK major 提货时重查
+    // (判据 = SDK d.ts 里出现 `type: "workflow_complete"`),入 union 当天搬进 switch。
     const raw = ev;
     if (raw.type === 'workflow_complete') {
         if (typeof raw.runId !== 'string')
-            return null;
-        return stamp(ctx, armBody({
+            return dropped('malformed', 'workflow_complete');
+        return projected(stamp(ctx, armBody({
             type: 'workflow_complete',
             runId: raw.runId,
             status: raw.status === 'failed' ? 'failed' : 'completed',
             summary: typeof raw.summary === 'string' ? raw.summary : '',
-        }));
-    }
-    // core 1.204 G2b — `task_notification` (background-bash/workflow completion, TaskNotificationPayload
-    // rides on `notification`). SDK ≥0.0.108 已入 union(注记过时已修);raw 读形保留待 B4 帧分派批统一 typed 化. Projects to a NEUTRAL
-    // internal arm: the REPL bridge drops it (the ENGINE already steer-injects the model-facing XML), the
-    // print-mode `ask` converts it to CC's `system/task_notification` SDK frame.
-    if (raw.type === 'task_notification') {
-        const n = (raw.notification ?? raw);
-        if (typeof n.task_id !== 'string')
-            return null;
-        return stamp(ctx, armBody({
-            type: 'task_notification',
-            notification: n,
-        }));
-    }
-    // core 1.220 design/121 — engine LSP `diagnostics` frame ({files:[{uri,diagnostics}], isNew}, service
-    // §E1 redacted, TOC host lane default ON). SDK ≥0.0.108 已入 union(注记过时已修);raw 读形保留待 B4 帧分派批统一 typed 化. Projects to
-    // a NEUTRAL internal arm; the REPL bridge maps it into the CC `diagnostics` attachment row
-    // (DiagnosticsDisplay renders it, zero new UI). parentToolCallId rides through so the bridge can keep
-    // a sub-flow's diagnostics off the leader transcript.
-    if (raw.type === 'diagnostics') {
-        if (!Array.isArray(raw.files) || raw.files.length === 0)
-            return null;
-        return stamp(ctx, armBody({
-            type: 'diagnostics',
-            files: raw.files,
-            isNew: raw.isNew === true,
-            ...(typeof raw.parentToolCallId === 'string' ? { parentToolCallId: raw.parentToolCallId } : {}),
-        }));
-    }
-    // core 1.251 design/133 ([479] ask-1) + 1.253 G1 ([482]/[487]②) — `steering_injected`: the engine
-    // echoed a SYSTEM steering injection ({source, preview:first-220-chars}, echo-only — the model-facing
-    // message is server-side). Sources are an OPEN SET (deadline_nudge/finalize + todo_reminder/
-    // task_reminder/changed_files/plan_mode + background_tasks/tools_delta today; core may extend). Not in
-    // the SDK union yet — raw defensive read; projects to a NEUTRAL internal arm the REPL bridge maps into
-    // renderable attachments (steeringAttachments.ts). parentToolCallId rides through so a sub-flow's echo
-    // stays off the leader transcript (same rule as diagnostics).
-    if (raw.type === 'steering_injected') {
-        if (typeof raw.source !== 'string' || raw.source.length === 0)
-            return null;
-        return stamp(ctx, armBody({
-            type: 'steering_injected',
-            source: raw.source,
-            preview: typeof raw.preview === 'string' ? raw.preview : '',
-            ...(typeof raw.parentToolCallId === 'string' ? { parentToolCallId: raw.parentToolCallId } : {}),
-        }));
-    }
-    // core design/99 §E13([1559]二/[1564]4 提货)— `workspace_changed`: the engine moved its logical
-    // cwd (bash `cd` / EnterWorktree), frame carries the NEW cwd (RAW form). Display-only echo — the
-    // engine already runs against the new cwd. NOT persistent state: resets to the session root across
-    // suspend/resume(core 口径,勿当持久态渲染)。SDK ≥0.0.108 已入 union(注记过时已修);raw 读形保留待 B4 帧分派批统一 typed 化;
-    // projects to a NEUTRAL arm the REPL bridge maps into a dim transcript row. server 透传候班车
-    // ([1557]三处置),帧到即亮。
-    if (raw.type === 'workspace_changed') {
-        if (typeof raw.cwd !== 'string' || raw.cwd.length === 0)
-            return null;
-        return stamp(ctx, armBody({
-            type: 'workspace_changed',
-            cwd: raw.cwd,
-            ...(typeof raw.parentToolCallId === 'string' ? { parentToolCallId: raw.parentToolCallId } : {}),
-        }));
+        })));
     }
     switch (ev.type) {
         // CS-1 §2.2 — turn-aggregated answer text (durable). Drop raw block array.
         case 'text':
-            return assistantArm(ctx, [{ type: 'text', text: ev.text }]);
+            return projected(assistantArm(ctx, [{ type: 'text', text: ev.text }]));
         // CS-3 §2.1 — turn-aggregated thinking (durable). Distinct collapsible block.
         case 'reasoning':
-            return assistantArm(ctx, [{ type: 'thinking', thinking: ev.text }]);
+            return projected(assistantArm(ctx, [{ type: 'thinking', thinking: ev.text }]));
         // CS-2 §2.4 — per-token answer fragment (live only). Typewriter append.
         case 'text_delta':
-            return streamEventArm(ctx, { type: 'text_delta', delta: ev.delta });
+            return projected(streamEventArm(ctx, { type: 'text_delta', delta: ev.delta }));
         // CS-4 §2.3 — per-token thinking fragment (live only). Drop signature_delta.
         // §E2 identity (service 1.78 unblanked parentToolCallId on the wire, blackboard dogfood #2): thread it
         // so the bridge can EXCLUDE a sub-flow's reasoning (orchestration/subagent) from the LEADER's spinner
         // counter + thinking preview — the "134k tokens" overcount root cause (upstreamBridge TODO #9).
         case 'reasoning_delta':
-            return streamEventArm(ctx, {
+            return projected(streamEventArm(ctx, {
                 type: 'thinking_delta',
                 delta: ev.delta,
                 ...(ev.parentToolCallId !== undefined ? { parentToolCallId: ev.parentToolCallId } : {}),
-            });
+            }));
         // CS-5 §2.5 — action-card open. args is `unknown`: render generically.
         // §E2 — thread the wire eventId (+ parentToolCallId) so the bridge stamps it (SB-2).
         case 'tool_start':
-            return assistantArm(ctx, [
+            return projected(assistantArm(ctx, [
                 {
                     type: 'tool_use',
                     id: ev.toolCallId,
@@ -158,14 +120,14 @@ export function eventToSdkMessage(ev, ctx) {
                         ? { parentToolCallId: ev.parentToolCallId }
                         : {}),
                 },
-            ]);
+            ]));
         // CS-8 §2.8 — compaction divider. tokensBefore ⇐ pre_tokens. trigger rides through when the
         // engine sends it (core 1.156 manual verb → "manual"; absent ⇒ 'auto'). core 1.219
         // (attachWorkingFiles default ON): `attachedFiles:[{path,chars,truncated}]` rides through raw so
         // the bridge can project the CC post-compact "Read {path}" attachment rows (blackboard ask ②).
         case 'compacted': {
             const attachedFiles = ev.attachedFiles;
-            return stamp(ctx, armBody({
+            return projected(stamp(ctx, armBody({
                 type: 'system',
                 subtype: 'compact_boundary',
                 compact_metadata: {
@@ -173,7 +135,7 @@ export function eventToSdkMessage(ev, ctx) {
                     pre_tokens: ev.tokensBefore ?? 0,
                 },
                 ...(Array.isArray(attachedFiles) && attachedFiles.length > 0 ? { attachedFiles } : {}),
-            }));
+            })));
         }
         // CS-6 §2.6 — tool_end now carries the §E1 model-facing `output` (the action-card
         // BODY) + isError + the §E2 eventId. Emit a NEUTRAL internal arm the bridge correlates
@@ -186,7 +148,7 @@ export function eventToSdkMessage(ev, ctx) {
             // AgentToolResult.details on the wire; not yet in the SDK tool_end arm — raw defensive read).
             // Rides the neutral arm so the bridge can render the REAL rich card (diff / stdout panels).
             const structured = ev.structured;
-            return stamp(ctx, armBody({
+            return projected(stamp(ctx, armBody({
                 type: 'tool_end_result',
                 toolCallId: ev.toolCallId,
                 toolName: ev.toolName,
@@ -202,7 +164,7 @@ export function eventToSdkMessage(ev, ctx) {
                 ...(ev.parentToolCallId !== undefined
                     ? { parentToolCallId: ev.parentToolCallId }
                     : {}),
-            }));
+            })));
         }
         // §E3/§E10 — BrainStatus liveness (events.d.ts:44/:80 — rate_limited/retrying/reconnecting/
         // circuit_open). LIVE-only + EPHEMERAL (never persisted/replayed). Project to a NEUTRAL internal
@@ -212,12 +174,12 @@ export function eventToSdkMessage(ev, ctx) {
         // `afa(agentId).retryStatus` app-state analog, ui-modules/0157_036_ui_Klo.js:31). The seam stays a
         // dumb forwarder: the provider-neutral→UI-shape mapping is the renderer layer's job (retryStatusStore).
         case 'status':
-            return stamp(ctx, armBody({
+            return projected(stamp(ctx, armBody({
                 type: 'retry_status',
                 phase: ev.phase,
                 ...(ev.detail !== undefined ? { detail: ev.detail } : {}),
                 ...(ev.retryInSec !== undefined ? { retryInSec: ev.retryInSec } : {}),
-            }));
+            })));
         // MF-10 (design/99, events.d.ts task_progress) — a SUBAGENT PROGRESS TICK: the delegated sub-run's
         // CUMULATIVE usage at each turn boundary (LIVE/EPHEMERAL, never persisted/replayed). Project to a
         // NEUTRAL internal `task_progress` arm — NOT a renderable CC SDKMessage. The upstream bridge binds it
@@ -228,7 +190,7 @@ export function eventToSdkMessage(ev, ctx) {
         // richer core-side arm.
         case 'task_progress': {
             if (typeof ev.taskId !== 'string')
-                return null;
+                return dropped('malformed', 'task_progress');
             // core 1.262.0 [558]B / service 1.154.0 [579] — `currentAction`: the child's most recent tool
             // intent as ONE human line ("Bash npm test"), derived from the child's tool_start (tool name +
             // argument head) and service-redacted. SDK ≥0.0.108 已定型(events.d.ts task_progress 臂),
@@ -241,7 +203,7 @@ export function eventToSdkMessage(ev, ctx) {
             // 仍剥这两键(server a76bd77 才修,黑板 [1619])——真 wire 于 1.273+ 才带,此处先备好通路。
             const workflowRunId = ev.workflowRunId;
             const workflowAgentLabel = ev.workflowAgentLabel;
-            return stamp(ctx, armBody({
+            return projected(stamp(ctx, armBody({
                 type: 'task_progress',
                 taskId: ev.taskId,
                 ...(ev.name !== undefined ? { name: ev.name } : {}),
@@ -258,7 +220,72 @@ export function eventToSdkMessage(ev, ctx) {
                 ...(ev.parentToolCallId !== undefined
                     ? { parentToolCallId: ev.parentToolCallId }
                     : {}),
-            }));
+            })));
+        }
+        // ── REF-CC-060(xlate-06):以下四臂**已在 SDK union 里**,从 switch 之前的手搓 raw 预分派
+        //    搬进来成为正式 case。搬之前它们永远到不了 switch,`ev.type` 的穷举性对它们失效 ——
+        //    也就是说 union 给这四臂新增/改名任何位,编译期一声不响。防御读(`typeof`/`Array.isArray`)
+        //    一条不减:wire 是 JSON,类型不在运行期存在(M0/M1)。
+        //
+        // core 1.204 G2b — `task_notification` (background-bash/workflow completion, TaskNotificationPayload
+        // rides on `notification`). Projects to a NEUTRAL internal arm: the REPL bridge drops it (the ENGINE
+        // already steer-injects the model-facing XML), the print-mode `ask` converts it to CC's
+        // `system/task_notification` SDK frame.
+        case 'task_notification': {
+            // 载荷两形:嵌在 `notification` 里(server 早期形)或直接摊在帧上(今天的 union 形)。
+            const nested = ev.notification;
+            const n = (nested ?? ev);
+            if (typeof n.task_id !== 'string')
+                return dropped('malformed', 'task_notification');
+            return projected(stamp(ctx, armBody({
+                type: 'task_notification',
+                notification: n,
+            })));
+        }
+        // core 1.220 design/121 — engine LSP `diagnostics` frame ({files:[{uri,diagnostics}], isNew}, service
+        // §E1 redacted, TOC host lane default ON). Projects to a NEUTRAL internal arm; the REPL bridge maps it
+        // into the CC `diagnostics` attachment row (DiagnosticsDisplay renders it, zero new UI).
+        // parentToolCallId rides through so the bridge can keep a sub-flow's diagnostics off the leader transcript.
+        case 'diagnostics': {
+            if (!Array.isArray(ev.files) || ev.files.length === 0)
+                return dropped('malformed', 'diagnostics');
+            return projected(stamp(ctx, armBody({
+                type: 'diagnostics',
+                files: ev.files,
+                isNew: ev.isNew === true,
+                ...(typeof ev.parentToolCallId === 'string' ? { parentToolCallId: ev.parentToolCallId } : {}),
+            })));
+        }
+        // core 1.251 design/133 ([479] ask-1) + 1.253 G1 ([482]/[487]②) — `steering_injected`: the engine
+        // echoed a SYSTEM steering injection ({source, preview:first-220-chars}, echo-only — the model-facing
+        // message is server-side). Sources are an OPEN SET (deadline_nudge/finalize + todo_reminder/
+        // task_reminder/changed_files/plan_mode + background_tasks/tools_delta today; core may extend).
+        // Projects to a NEUTRAL internal arm the REPL bridge maps into renderable attachments
+        // (steeringAttachments.ts). parentToolCallId rides through so a sub-flow's echo stays off the leader
+        // transcript (same rule as diagnostics).
+        case 'steering_injected': {
+            if (typeof ev.source !== 'string' || ev.source.length === 0)
+                return dropped('malformed', 'steering_injected');
+            return projected(stamp(ctx, armBody({
+                type: 'steering_injected',
+                source: ev.source,
+                preview: typeof ev.preview === 'string' ? ev.preview : '',
+                ...(typeof ev.parentToolCallId === 'string' ? { parentToolCallId: ev.parentToolCallId } : {}),
+            })));
+        }
+        // core design/99 §E13([1559]二/[1564]4 提货)— `workspace_changed`: the engine moved its logical
+        // cwd (bash `cd` / EnterWorktree), frame carries the NEW cwd (RAW form). Display-only echo — the
+        // engine already runs against the new cwd. NOT persistent state: resets to the session root across
+        // suspend/resume(core 口径,勿当持久态渲染);projects to a NEUTRAL arm the REPL bridge maps into
+        // a dim transcript row.
+        case 'workspace_changed': {
+            if (typeof ev.cwd !== 'string' || ev.cwd.length === 0)
+                return dropped('malformed', 'workspace_changed');
+            return projected(stamp(ctx, armBody({
+                type: 'workspace_changed',
+                cwd: ev.cwd,
+                ...(typeof ev.parentToolCallId === 'string' ? { parentToolCallId: ev.parentToolCallId } : {}),
+            })));
         }
         // P0-1([1725] 清单A)— E12 `suggestions`:run 跑完(status:"completed")后 core 一次 LLM pass 产的
         // 「下一步可问什么」建议**批**。此前这个臂掉进 `default: return null` ⇒ 全链死信。
@@ -273,28 +300,60 @@ export function eventToSdkMessage(ev, ctx) {
         // tasks/stream ⇒ 这条通路今天只在 durable 车道(runs.create + runs.events:Ctrl+B/`/background`/
         // ControlRouter)活。防御性上界:批量截 8 条、单条截 200 字(UI 面,不是模型面)。
         case 'suggestions': {
-            const list = (Array.isArray(ev.suggestions) ? ev.suggestions : [])
-                .filter((s) => typeof s === 'string' && s.trim().length > 0)
-                .slice(0, 8)
-                .map((s) => (s.length > 200 ? `${s.slice(0, 200)}…` : s));
+            const filtered = (Array.isArray(ev.suggestions) ? ev.suggestions : []).filter((s) => typeof s === 'string' && s.trim().length > 0);
+            const list = filtered
+                .slice(0, SUGGESTION_BATCH_CAP)
+                .map((s) => (s.length > SUGGESTION_CHARS_CAP ? `${s.slice(0, SUGGESTION_CHARS_CAP)}…` : s));
             if (list.length === 0)
-                return null;
-            return stamp(ctx, armBody({
+                return nothing('empty_payload');
+            return projected(stamp(ctx, armBody({
                 type: 'prompt_suggestions',
                 suggestions: list,
-            }));
+                // 🔴 REF-CC-061(xlate-07,H2 无声上限零容忍):**单条**截断本来就是诚实的(尾部 `…` 是
+                // 可见痕迹),**批量**截断此前不是 —— 引擎给 12 条时第 9-12 条无声蒸发,臂上没有任何位
+                // 说出「还有更多」。additive 位,与本文件 tool_end 臂的 `truncated` 同款姿势;渲不渲是
+                // 渲染面的决定,数据面必须先说出来。
+                ...(filtered.length > list.length ? { truncatedCount: filtered.length - list.length } : {}),
+            })));
         }
-        // §2.7 — turn_end is usage-only. §2.9 — suspended is HITL registration.
+        // §2.7 — turn_end is usage-only(usage 由 `turnEndUsage` 单独出口,run driver 折叠)。
         case 'turn_end':
+            return nothing('usage_only');
+        // §2.9 — suspended 的 HITL 登记是 run driver 的活(hitlBridge.observe),本层不投影。
         case 'suspended':
-            return null;
+            return nothing('hitl_out_of_slice');
         // CS-10 / CS-11 — terminals are projected by terminalToSdkResult.
         case 'done':
         case 'failed':
-            return null;
+            return nothing('terminal_delegated');
+        // ── 已入 SDK union、本切片**有意**不投影的臂(REF-CC-060:进 switch 才受穷举保护)────────
+        // `meta`:流首帧的 taskId/sessionId 一等信号 —— 身份面由 SDK/传输层自己消费(runStream 只按
+        //   `eventSeq` 去重),没有可渲染内容。
+        case 'meta':
+        // `file_link` / `prompt_assembled` / `model_usage` / `context_usage` / `config_assembled` /
+        // `message_committed`:引擎的可观测/审计面帧,本切片(CC transcript 投影)无对位渲染物;
+        //   消费它们的是 fleet/审计面而不是会话转录。
+        case 'file_link':
+        case 'prompt_assembled':
+        case 'model_usage':
+        case 'context_usage':
+        case 'config_assembled':
+        case 'message_committed':
+        // `needs_review`:plan-review park 的**事件**形;壳消费的是 done{status:'needs_review'} 终帧
+        //   (runStream 的 plan_review_park chrome 臂),事件形在本切片重复且更早,故不投影。
+        case 'needs_review':
+        // `compaction_outcome`(sdk 4.0.1 新臂,[2373]A-2 三腿同源):压缩**非 compacted 结局**报告
+        //   (mooted/failed 等)。CC transcript 无对位物(compact_boundary 只对成功压缩,由 `compacted`
+        //   臂投)——本切片不投影。⚠️ 「压缩失败让用户看见」是 chrome/HUD 面的活,今天两端都还没接
+        //   (adapt 臂表同样无此臂),缺口记 0.13.0 候选,不许由本切片顺手编一个假 transcript 形。
+        case 'compaction_outcome':
+            return nothing('not_in_slice');
         default:
-            // Forward-compat: log+skip an arm this slice predates (contract 02 §3).
-            return null;
+            // B5 穷举:SDK union 加成员必须在**编译期**打红这一行(而不是让新臂在用户面静默丢帧)。
+            assertNeverArm(ev);
+            // 运行期:wire 是 JSON,引擎完全可能比本包的类型新一版 —— 如实报 dropped,由 run driver
+            // 上报(REF-CC-057:此处此前写着 `log+skip` 而全函数零 log,那句承诺在码里根本不存在)。
+            return dropped('unknown_arm', String(ev.type ?? 'unknown'));
     }
 }
 /**
@@ -314,12 +373,13 @@ export function turnEndUsage(ev) {
  * ⚠️ DEAD CODE — 不是「HITL 分支漏接」(2026-07-26 全树核查,task #81 顺带件):
  *   · 全树(src/ + mock/ + build/ + 测试)**零调用点**,adapter facade(src/seam/adapter/index.ts)
  *     也没把它再导出去 —— 没有任何一处「本该调它却没调」。
- *   · 它想服务的那条 HITL 分支**已经接好了**,只是没走这个函数:
- *       - `suspended` 事件臂 → `src/seam/adapter/upstream/hitlBridge.ts:162-168` 的 `observe()`
- *         就地做了**同款**防御回落(`ev.gate ? ev.gate : { kind: 'human' }`),而且 latch 的是整个
- *         CheckpointGate 对象,壳侧 `currentGate()` 自己 branch `gate.kind`;
- *       - `done{status:'suspended', checkpointGate}` 终帧 → `liveHitlAskWire.ts:89-118` /
- *         `terminalToSdkResult.ts:296-311` 各自读 `checkpointGate.kind` **和** `.toolName`。
+ *   · 它想服务的那条 HITL 分支**已经接好了**,只是没走这个函数(REF-CC-063:此处原为四个行号锚,
+ *     今天全部已腐,改符号锚):
+ *       - `suspended` 事件臂 → `hitl/hitlBridge.ts` 的 `HitlBridge.observe()` 就地做了**同款**防御
+ *         回落(`ev.gate ? ev.gate : { kind: 'human' }`),而且 latch 的是整个 CheckpointGate 对象,
+ *         壳侧 `currentGate()` 自己 branch `gate.kind`;
+ *       - `done{status:'suspended', checkpointGate}` 终帧 → `liveHitlAskWire.ts` 的 ask 合成口 /
+ *         `terminalToSdkResult.ts` 的 park 臂各自读 `checkpointGate.kind` **和** `.toolName`。
  *   · 关键:每个真实消费方都同时需要 `toolName`(挑 Ask overlay vs fs 写门三选卡),而本函数只吐
  *     一个 kind 字符串 —— 签名比任何真实需求都窄,接进去反而要再读一次 gate。
  *   结论 = 可删的死码(留档不擅删,按 task #81 口径只标记);真要收,连同 `CheckpointGate` 的