@sema-agent/client-core 0.12.1 → 0.13.0

package/dist/adapter/downstream/terminalToSdkResult.js

@@ -1,5 +1,10 @@
 import { stamp } from '../types.js';
-/** Flatten TaskStats → the CC NonNullableUsage placeholder (z.unknown()). */
+import { toCcModelUsage } from './turnUsageToModelUsage.js';
+/**
+ * Flatten TaskStats → the CC NonNullableUsage placeholder.
+ * 🔴 REF-CC-055(xlate-01):`failedToSdkResult` 此前手抄了一份「五键全零」的字面量,那不是
+ * 另一种形状,就是本函数 `stats === undefined` 的退化输出 —— 现在它也走这里(单一构造点)。
+ */
 function flattenUsage(stats) {
     return {
         inputTokens: stats?.promptTokens ?? 0,
@@ -9,13 +14,6 @@ function flattenUsage(stats) {
         webSearchRequests: 0,
     };
 }
-/**
- * MF-25 — map the wire's per-model usage split (`stats.modelUsage`, an open `{ <modelId>: usage }` map;
- * e.g. `{ "deepseek-v4-pro": {...} }`) into the CC `SDKResult.modelUsage` record (model-id → CC ModelUsage).
- * The wire usage names (`cacheReadTokens`/`cacheWriteTokens`/`costMicroUsd`) are re-pinned to the CC names
- * (`cacheReadInputTokens`/`cacheCreationInputTokens`/`costUSD`, costMicroUsd/1e6 → USD), matching
- * turnUsageToModelUsage. `contextWindow`/`maxOutputTokens` are not on the wire → 0. Returns `{}` when absent.
- */
 /** P1-5 — real elapsed ms since the stream opened (runStream stamps startedAtMs); 0 only pre-stamp. */
 function elapsedMs(ctx) {
     return typeof ctx.startedAtMs === 'number' ? Math.max(0, Date.now() - ctx.startedAtMs) : 0;
@@ -59,36 +57,124 @@ function costOrNull(stats) {
 }
 // 件2a(中断事故修复批 G,2026-07-15,症状2 第一环):参数放宽 TaskStats | undefined + 全链守卫。
 // 409 active-run 拒绝时引擎的 done 帧本体是 {status:'failed', errorMessage, activeTaskId} —— NO stats
-// (ai-agent-service server.ts:1526 同型),此前 :59 裸读 (stats).modelUsage 直接 TypeError,炸穿
-// runStream → seamQuery catch → 误诊 "engine is unreachable"(件2c)。缺 stats 时产出合法空 usage
-// 形状(flattenUsage 本就守卫;这里返回 {},调用方 :98 再按 r.model 合成当前行)。
+// (ai-agent-service server.ts:1526 同型),此前 `mapModelUsage` 裸读 `(stats).modelUsage` 直接
+// TypeError,炸穿 runStream → seamQuery catch → 误诊 "engine is unreachable"(件2c)。缺 stats 时
+// 产出合法空 usage 形状(flattenUsage 本就守卫;这里返回 {},`modelUsageFor` 再按 r.model 合成当前行)。
+//
+// MF-25 — map the wire's per-model usage split (`stats.modelUsage`, an open `{ <modelId>: usage }` map;
+// e.g. `{ "deepseek-v4-pro": {...} }`) into the CC `SDKResult.modelUsage` record (model-id → CC ModelUsage).
+// 🔴 REF-CC-062(xlate-08):八键形状与那套 load-bearing 改名**不在本文件构造** —— 单源 mint 点是
+// `turnUsageToModelUsage.ts` 的 `toCcModelUsage()`(core 3.0.0 的 inputTokens 语义翻转注也钉在那里)。
+// 本函数只负责 wire 边界的窄化:开集 map 的每个值都是 `unknown`,先取出数值位再交给 mint 点。
 function mapModelUsage(stats) {
     const raw = stats?.modelUsage;
-    if (!raw || typeof raw !== 'object')
+    if (raw === undefined || raw === null || typeof raw !== 'object')
         return {};
     const out = {};
+    /** 边界窄化:非数值一律当缺席交给 mint 点(它把缺席与非有限值一并折 0)。 */
+    const numOrAbsent = (v) => (typeof v === 'number' ? v : undefined);
     for (const [modelId, u] of Object.entries(raw)) {
-        if (!u || typeof u !== 'object')
+        if (u === undefined || u === null || typeof u !== 'object')
             continue;
         const m = u;
-        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
-        out[modelId] = {
-            inputTokens: num(m.inputTokens),
-            outputTokens: num(m.outputTokens),
-            cacheReadInputTokens: num(m.cacheReadTokens),
-            cacheCreationInputTokens: num(m.cacheWriteTokens),
-            webSearchRequests: 0,
-            costUSD: microUsdToUsd(m.costMicroUsd) ?? 0, // ⇐ 与 costOrNull 同一个换算口(旧写法 num(...)/1e6 逐值等价)
-            contextWindow: 0,
-            maxOutputTokens: 0,
-        };
+        out[modelId] = toCcModelUsage({
+            inputTokens: numOrAbsent(m.inputTokens),
+            outputTokens: numOrAbsent(m.outputTokens),
+            cacheReadTokens: numOrAbsent(m.cacheReadTokens),
+            cacheWriteTokens: numOrAbsent(m.cacheWriteTokens),
+            costMicroUsd: numOrAbsent(m.costMicroUsd),
+        });
     }
     return out;
 }
+/**
+ * P1-5 — 终帧的 `modelUsage`:优先 wire 的 per-model split;缺席(老引擎 stats 无 MF-25 分表,或
+ * split-less done)时按**当前模型**从扁平 `TaskStats` 合成一行,JSON 消费者才知道这笔 usage 是谁产的。
+ * 🔴 REF-CC-055/062:success 臂与五个 error 臂此前各自持有这段逻辑的结果(合成行只在 success 路径
+ * 算一次、error 臂靠共享局部变量捎带),现在两条路都调本函数 —— 同一输入同一输出,单一构造点。
+ */
+function modelUsageFor(stats, model) {
+    const split = mapModelUsage(stats);
+    if (Object.keys(split).length > 0)
+        return split;
+    if (typeof model !== 'string' || model.length === 0)
+        return split;
+    // 键迁移(见 costOrNull 头注):legacy float `costUsd` → 整数 `costMicroUsd`(/1e6 → USD)。
+    // ⚠️ 这一处**类型门抓不到**:TaskStats 带 `[key: string]: unknown` 开集索引,`typeof
+    // stats?.costUsd === 'number'` 的旧写法在 SDK 1.x 下照样编译得过,只是恒假 ⇒ 合成行的
+    // costUSD 静默恒 0(比报错更隐蔽)。tsc 只红了 6 处直传,这处靠人核 + pure 门的行为钉。
+    return {
+        [model]: toCcModelUsage({
+            inputTokens: stats?.promptTokens,
+            outputTokens: stats?.outputTokens,
+            cacheReadTokens: stats?.cachedTokens,
+            cacheWriteTokens: 0,
+            costMicroUsd: stats?.costMicroUsd,
+        }),
+    };
+}
+/**
+ * TaskResult 五键最小消费批([1543] SDK-M,2026-07-23)之一 —— `degraded` = 模型降级链实录
+ * (from/to/reason/atTurn;多模型网关部署的关键可观测面)。
+ *
+ * 🔴 REF-CC-056(xlate-02):文件头共享注一直写着「success/timeout/blocked/unknown 各终态都可能带,
+ * **恒 additive 附上**」,而实际只有 timeout 与 success 两臂 spread 了它,blocked/park/未知/failed
+ * 四臂全漏 —— 一条经历过降级并最终失败的 run,降级链在终帧上无痕消失,而注释向下一棒承诺它在。
+ * 修法不是再补四处 spread(那是第五、六个构造点),而是把它放进 {@link errorResult} 信封本体:
+ * 「恒 additive 附上」这句话从此是结构,不是散文。
+ *
+ * 边界守门(M1):wire 上的值仍按对象守卫 —— 非对象/缺席一律不 stamp 这个键(诚实缺席)。
+ */
+function degradedOf(r) {
+    const d = r.degraded;
+    return d !== undefined && d !== null && typeof d === 'object' ? d : undefined;
+}
+/**
+ * 🔴 **CC `SDKResultError` 信封的唯一 mint 点**(REF-CC-055 / xlate-01,E1 单源构造)。
+ *
+ * 收编前这 13 个位在**六处**逐字重复:done 的 failed/timeout/blocked/park/未知终态五臂,加上
+ * `failedToSdkResult` —— 后者看着像「另一种信封」,其实是同一信封 `stats === undefined` 的退化
+ * 实例被手抄了一遍(`num_turns: 0` ≡ `stats?.turns ?? 0`、`total_cost_usd: null` ≡ `costOrNull(undefined)`、
+ * 手写五键零 usage ≡ `flattenUsage(undefined)`、`modelUsage: {}` ≡ `mapModelUsage(undefined)`)。
+ * 六份手抄的代价不是行数,是 REF-CC-056 那种**漏配**:给信封加一个位要改六处,漏掉的那几处没有
+ * 任何门会说话。
+ */
+function errorResult(ctx, parts) {
+    return stamp(ctx, {
+        // Explicit (always-undefined) uuid/session_id: stamp() always overwrites session_id from
+        // ctx and falls back to a fresh uuid when body.uuid is nullish, so this is a pure type-level
+        // nudge (zero runtime effect) — without at least one property name in common with stamp's
+        // all-optional constraint, TS's "weak type" detection rejects the call (TS2559/TS2345/TS2353).
+        uuid: undefined,
+        session_id: undefined,
+        type: 'result',
+        subtype: parts.subtype,
+        duration_ms: parts.durationMs, // P1-5 real elapsed (stream-open → terminal)
+        duration_api_ms: parts.durationMs, // engine run == the API call from the shell's view
+        is_error: true,
+        num_turns: parts.stats?.turns ?? 0, // 件2a 同款守卫 —— 缺 stats 不炸
+        stop_reason: null, // dropped (contract 02 §2.10)
+        total_cost_usd: costOrNull(parts.stats), // P1-5: null when unknown, never a fake 0
+        usage: flattenUsage(parts.stats),
+        modelUsage: modelUsageFor(parts.stats, parts.model),
+        permission_denials: [],
+        errors: [...parts.errors],
+        ...(parts.errorCode !== undefined && parts.errorCode.length > 0 ? { errorCode: parts.errorCode } : {}),
+        ...(parts.degraded !== undefined ? { degraded: parts.degraded } : {}),
+        ...(parts.extra ?? {}),
+    });
+}
 /** `done` → SDKResultSuccess (contract 02 §2.10 / 08 CS-10). */
 export function doneToSdkResult(ev, ctx) {
-    const r = ev.result;
-    // 件2a:409/failed 形态的 done 帧不带 stats —— 本函数全链按 undefined 守卫(:97/:121/:145)。
+    // sdk 4.1.0([2395]E 调和):`done.result` 是判别联合 `TaskResult | ActiveRunConflictDoneResult`。
+    // 🔄 全窗复审 ADAPTER-1/-2 收口(2026-08-03):首版接线用 `'stats' in r` 铸 tr 并让 result/model/
+    // degraded 全走 tr?.——把「stats 在不在」错当成了这些键的门控(anchor-on-the-deciding-quantity
+    // 反例):R1b 抢救腿从 run row 合成的 done 帧 stats 可缺席但带答案正文,被投影成空成功;且
+    // `in` 对非对象 result 抛 TypeError(旧码宽读不抛,件2c 事故形)。正解=各键**独立宽读**
+    // (键在就读、缺席 undefined,与拆分前逐键同语义),判别联合只影响类型声明不影响读法。
+    const rRaw = ev.result;
+    const rec = typeof rRaw === 'object' && rRaw !== null ? rRaw : {};
+    const r = rec;
     const stats = r.stats;
     // P1-5 — the terminal frame's session_id must be the ENGINE-AUTHORITATIVE id (done.result.sessionId):
     // on the headless `-p` path ctx was seeded from the REQUEST (historically the mock constant
@@ -97,25 +183,8 @@ export function doneToSdkResult(ev, ctx) {
     const echoedSid = r.sessionId;
     if (typeof echoedSid === 'string' && echoedSid.length > 0)
         ctx.sessionId = echoedSid;
-    // P1-5 — modelUsage: prefer the wire's per-model split; when absent (local engine pre-MF-25 stats or a
-    // split-less done), synthesize the CURRENT model's row from the flat TaskStats so JSON consumers always
-    // see which model produced the run's usage.
-    const usage = flattenUsage(stats);
-    let modelUsage = mapModelUsage(stats);
-    if (Object.keys(modelUsage).length === 0 && typeof r.model === 'string' && r.model.length > 0) {
-        modelUsage = {
-            [r.model]: {
-                ...usage,
-                // 键迁移(见 costOrNull 头注):legacy float `costUsd` → 整数 `costMicroUsd`(/1e6 → USD)。
-                // ⚠️ 这一处**类型门抓不到**:TaskStats 带 `[key: string]: unknown` 开集索引,`typeof
-                // stats?.costUsd === 'number'` 的旧写法在 SDK 1.x 下照样编译得过,只是恒假 ⇒ 合成行的
-                // costUSD 静默恒 0(比报错更隐蔽)。tsc 只红了 6 处直传,这处靠人核。
-                costUSD: microUsdToUsd(stats?.costMicroUsd) ?? 0,
-                contextWindow: 0,
-                maxOutputTokens: 0,
-            },
-        };
-    }
+    // P1-5 — modelUsage/usage 的构造已收敛到 `flattenUsage` / `modelUsageFor`(REF-CC-055/062),
+    // 五个 error 臂经 `errorResult` 信封拿到同一份,success 臂在下方直接调 —— 同一输入同一输出。
     // clay P0 壳半场(黑板 [450],2026-07-05):上游 4xx(如无 vision 模型收到 image)时
     // 引擎的 done 帧本体带 result.status='failed' + errorMessage —— 传播链没吞,断点在这:
     // 此前无条件投影 subtype:'success'/is_error:false,把失败洗成"成功空回复"= 用户看到的
@@ -130,8 +199,15 @@ export function doneToSdkResult(ev, ctx) {
     const rr = r;
     const durationMs = elapsedMs(ctx);
     // [909]B1 — errorCode 透传(additive seam 字段;CC schema 无此键,与 success 臂 `model` 同款超集
-    // 姿势):引擎值原样,绝不铸造。所有 error 臂共用。
-    const errorCodeField = typeof rr.errorCode === 'string' && rr.errorCode.length > 0 ? { errorCode: rr.errorCode } : {};
+    // 姿势):引擎值原样,绝不铸造。所有 error 臂共用(`errorResult` 信封负责 stamp)。
+    const errorCode = typeof rr.errorCode === 'string' && rr.errorCode.length > 0 ? rr.errorCode : undefined;
+    // TaskResult 五键最小消费批([1543] SDK-M,2026-07-23):additive seam 字段——
+    //  · degraded = 模型降级链实录,**各终态恒 additive 附上**(见 `degradedOf` 头注 / REF-CC-056);
+    //  · structuredOutput = outputSchema 任务的结构化产出(success 臂);
+    //  · salvagedOutput = degenerate/timeout 抢救出的最后模型文本(timeout 臂 salvage 回落源)。
+    const degraded = degradedOf(r);
+    /** 五个 error 臂共享的固定位(信封其余 13 位见 `errorResult`)。 */
+    const errorBase = { durationMs, stats, model: r.model, errorCode, degraded };
     if (rr.status === 'failed') {
         // [909]B1 — failed 臂 subtype 语义化(见文件头对表):budget.* → error_max_budget_usd(与
         // failedToSdkResult 事件臂同款分流,此前 done{failed} 恒 error_during_execution);
@@ -146,24 +222,9 @@ export function doneToSdkResult(ev, ctx) {
                 : rr.errorCode === 'output.invalid'
                     ? 'error_max_structured_output_retries'
                     : 'error_during_execution';
-        return stamp(ctx, {
-            // Explicit (always-undefined) uuid/session_id: stamp() always overwrites session_id from
-            // ctx and falls back to a fresh uuid when body.uuid is nullish, so this is a pure type-level
-            // nudge (zero runtime effect) — without at least one property name in common with stamp's
-            // all-optional constraint, TS's "weak type" detection rejects the call (TS2559/TS2345/TS2353).
-            uuid: undefined,
-            session_id: undefined,
-            type: 'result',
+        return errorResult(ctx, {
+            ...errorBase,
             subtype: failedSubtype,
-            duration_ms: durationMs, // P1-5 real elapsed (stream-open → terminal)
-            duration_api_ms: durationMs, // engine run == the API call from the shell's view
-            is_error: true,
-            num_turns: stats?.turns ?? 0,
-            stop_reason: null,
-            total_cost_usd: costOrNull(stats), // P1-5: null when unknown, never a fake 0
-            usage,
-            modelUsage,
-            permission_denials: [],
             // rewind 族错误码透传(server 1.192 [838]③ 实测:stream 腿把 resume_at.before_* /
             // rewind_snapshot.unresolvable 骑在 done{status:"failed"} 帧的 errorCode 上,非 `failed` 帧)——
             // 与 failedToSdkResult 的同款 append 对齐,message 后附 code 便于对账。
@@ -174,7 +235,6 @@ export function doneToSdkResult(ev, ctx) {
                     ? `${rr.errorMessage} (${rr.errorCode})`
                     : (rr.errorMessage ?? 'run failed'),
             ],
-            ...errorCodeField,
         });
     }
     // [909]B1 — timeout 终态:--deadline 配速的受控截止收尾(assemble-result.js:69/88
@@ -183,15 +243,6 @@ export function doneToSdkResult(ev, ctx) {
     // 收尾帧([909]B2 关联半场;帧完整落地由 stdout drain 半场保证)。subtype 选型见文件头对表:
     // CC 词表无 wall-clock 词,唯一 run-limit 族词 = error_max_turns;精确语义靠 errors[] 文案 +
     // errorCode:"limit.timeout" 透传。rc 语义顺出:print.ts gracefulShutdownSync(is_error ? 1 : 0)。
-    // TaskResult 五键最小消费批([1543] SDK-M,2026-07-23):additive seam 字段——
-    //  · degraded = 模型降级链实录(from/to/reason/atTurn;多模型网关部署的关键可观测面)——
-    //    success/timeout/blocked/unknown 各终态都可能带,恒 additive 附上;
-    //  · structuredOutput = outputSchema 任务的结构化产出(success 臂);
-    //  · salvagedOutput = degenerate/timeout 抢救出的最后模型文本(timeout 臂 salvage 回落源)。
-    const degradedField = (() => {
-        const d = r.degraded;
-        return d !== undefined && d !== null && typeof d === 'object' ? { degraded: d } : {};
-    })();
     if (rr.status === 'timeout') {
         const salvagedOutput = r.salvagedOutput;
         const salvaged = typeof r.result === 'string' && r.result.trim().length > 0
@@ -199,10 +250,8 @@ export function doneToSdkResult(ev, ctx) {
             : typeof salvagedOutput === 'string' && salvagedOutput.trim().length > 0
                 ? salvagedOutput
                 : undefined;
-        return stamp(ctx, {
-            uuid: undefined,
-            session_id: undefined,
-            type: 'result',
+        return errorResult(ctx, {
+            ...errorBase,
             // [2084]②a(2026-07-30,repro/cli-walltime-timeout-reported-as-max-turns):此前硬编码
             // error_max_turns(选型理由是「CC 词表唯一 run-limit 族词」),但那让同一帧自相矛盾
             // (errorCode=limit.timeout + num_turns 远小于上限,test 实测 num_turns:2 且根本没设
@@ -211,26 +260,15 @@ export function doneToSdkResult(ev, ctx) {
             // 真实语义仍靠 errorCode:"limit.timeout" + errors[] 文案判别(原设计轴不动)。
             // 副产品:真 limit.max_turns 停(failed 臂)与墙钟停在 subtype 上重新可分。
             subtype: 'error_during_execution',
-            duration_ms: durationMs,
-            duration_api_ms: durationMs,
-            is_error: true,
-            num_turns: stats?.turns ?? 0,
-            stop_reason: null,
-            total_cost_usd: costOrNull(stats),
-            usage,
-            modelUsage,
-            permission_denials: [],
             // [2084]②b:引擎的 cutoff 句承诺「cut off to preserve a write-out window」,但 pre-call
             // throw 路径上写出窗可能零兑现(core dist/brain/stream-engine 五处 throw,载体天生空)。
             // 抢救为空时补诚实尾注——每一层都复述没兑现的承诺,消费者就无从分辨救没救回来。
             errors: [
                 `${rr.errorMessage ?? 'run hit its wall-clock deadline and was finalized by the engine'} (${rr.errorCode ?? 'limit.timeout'})${salvaged === undefined ? ' — no output survived the cutoff' : ''}`,
             ],
-            ...errorCodeField,
             // 写出窗 salvage(additive seam 字段):deadline 前引擎救回的最终文本非空时随帧带出——
             // CC error 帧无 result 键,但静默丢弃已救回的答案对 -p 集成面是净损失(TB qe** 实证)。
-            ...(salvaged !== undefined ? { result: salvaged } : {}),
-            ...degradedField,
+            ...(salvaged !== undefined ? { extra: { result: salvaged } } : {}),
         });
     }
     // [909]B1 — blocked 终态:agent 自报无法推进(assemble-result.js:99,只带 blockedReason 无
@@ -238,26 +276,14 @@ export function doneToSdkResult(ev, ctx) {
     // subtype:success)。≠空成功 → SDKResultError,blockedReason 如实进 errors[]。
     if (rr.status === 'blocked') {
         const blockedReason = r.blockedReason;
-        return stamp(ctx, {
-            uuid: undefined,
-            session_id: undefined,
-            type: 'result',
+        return errorResult(ctx, {
+            ...errorBase,
             subtype: 'error_during_execution',
-            duration_ms: durationMs,
-            duration_api_ms: durationMs,
-            is_error: true,
-            num_turns: stats?.turns ?? 0,
-            stop_reason: null,
-            total_cost_usd: costOrNull(stats),
-            usage,
-            modelUsage,
-            permission_denials: [],
             errors: [
                 typeof blockedReason === 'string' && blockedReason.length > 0
                     ? `Run blocked: ${blockedReason}`
                     : 'Run blocked (the agent reported it cannot proceed)',
             ],
-            ...errorCodeField,
         });
     }
     // [884]A1(TB 公平 P0,2026-07-16):suspended/needs_review park 终帧不许洗成空成功。
@@ -287,49 +313,26 @@ export function doneToSdkResult(ev, ctx) {
         const wayOut = rr.status === 'needs_review'
             ? `Review the plan in the interactive REPL${sid ? ` (sema --resume ${sid})` : ''}.`
             : `Answer it in the interactive REPL${sid ? ` (sema --resume ${sid})` : ''}, or decide the pending approval via the engine approvals API${sid ? ` (POST /v1/approvals/${sid}/decide)` : ''}.`;
-        return stamp(ctx, {
-            uuid: undefined,
-            session_id: undefined,
-            type: 'result',
+        // [909]B1 — needs_review 帧带 review.pending;errorCode 由信封原样透传。
+        return errorResult(ctx, {
+            ...errorBase,
             subtype: 'error_during_execution',
-            duration_ms: durationMs,
-            duration_api_ms: durationMs,
-            is_error: true,
-            num_turns: stats?.turns ?? 0, // 件2a 同款守卫 —— park 帧多数不带 stats,不炸
-            stop_reason: null,
-            total_cost_usd: costOrNull(stats),
-            usage,
-            modelUsage,
-            permission_denials: [],
             errors: [
                 `Turn suspended awaiting ${awaiting} that no one can provide in -p (non-interactive) mode${runId ? ` (run ${runId})` : ''}. ${wayOut}`,
             ],
-            ...errorCodeField, // [909]B1 — needs_review 帧带 review.pending,原样透传
         });
     }
     // [909]B1 — 防御臂:词表外的未知非 completed 终态(core 未来加词/未知 wire 变形)绝不洗成
     // 空成功——error_during_execution + errors[] 如实报出该 status 字面。absent status(mock 车道 /
     // 旧引擎 done 帧不带 status)维持 success 臂,零行为变化。
     if (typeof rr.status === 'string' && rr.status.length > 0 && rr.status !== 'completed') {
-        return stamp(ctx, {
-            uuid: undefined,
-            session_id: undefined,
-            type: 'result',
+        return errorResult(ctx, {
+            ...errorBase,
             subtype: 'error_during_execution',
-            duration_ms: durationMs,
-            duration_api_ms: durationMs,
-            is_error: true,
-            num_turns: stats?.turns ?? 0,
-            stop_reason: null,
-            total_cost_usd: costOrNull(stats),
-            usage,
-            modelUsage,
-            permission_denials: [],
             errors: [
                 rr.errorMessage ??
                     `run ended with terminal status "${rr.status}" (not a success; this CLI predates that status word)`,
             ],
-            ...errorCodeField,
         });
     }
     return stamp(ctx, {
@@ -340,19 +343,19 @@ export function doneToSdkResult(ev, ctx) {
         duration_ms: durationMs, // P1-5 real elapsed (stream-open → terminal); the wire carries none
         duration_api_ms: durationMs, // engine run == the API call from the shell's view
         is_error: false,
-        num_turns: stats?.turns ?? 0, // 件2a:同 :121 —— 缺 stats 不炸
+        num_turns: stats?.turns ?? 0, // 件2a:同 costOrNull 那一路 —— 缺 stats 不炸
         result: r.result ?? '',
-        // TaskResult 五键(additive):outputSchema 任务的结构化产出 + 降级实录(见上方共享注)。
+        // TaskResult 五键(additive):outputSchema 任务的结构化产出 + 降级实录(见 `degradedOf`)。
         ...(() => {
             const so = r.structuredOutput;
             return so !== undefined ? { structuredOutput: so } : {};
         })(),
-        ...degradedField,
+        ...(degraded !== undefined ? { degraded } : {}),
         stop_reason: null, // dropped (contract 02 §2.10)
         total_cost_usd: costOrNull(stats), // P1-5: 零成本 = "unconfigured pricing" → null, never a fake 0
-        usage,
+        usage: flattenUsage(stats),
         // MF-25/P1-5 — the per-model usage split (wire `stats.modelUsage`, or the synthesized current-model row).
-        modelUsage,
+        modelUsage: modelUsageFor(stats, r.model),
         permission_denials: [],
         // MF-25 — the effective served model id (`done.result.model`, e.g. "deepseek-v4-pro"). The CC
         // SDKResultSuccess schema has no `model` field, so this rides as an additive seam field a cost/overview
@@ -368,27 +371,16 @@ export function failedToSdkResult(ev, ctx) {
     const subtype = ev.errorCode === 'budget.exceeded' || ev.errorCode === 'budget.precall'
         ? 'error_max_budget_usd'
         : 'error_during_execution';
-    const durationMs = elapsedMs(ctx);
-    return stamp(ctx, {
-        uuid: undefined,
-        session_id: undefined,
-        type: 'result',
+    // 🔴 REF-CC-055:此臂**不是另一种信封**,是 `errorResult` 在 `stats === undefined` 时的退化实例
+    // (`num_turns: 0` ≡ `stats?.turns ?? 0`、`total_cost_usd: null` ≡ `costOrNull(undefined)`、
+    // 五键零 usage ≡ `flattenUsage(undefined)`、`modelUsage: {}` ≡ `modelUsageFor(undefined, undefined)`)。
+    // `failed` 事件帧本体不带 stats/model/degraded,所以这三个位如实缺席 —— 不是「这里少算了」。
+    return errorResult(ctx, {
         subtype,
-        duration_ms: durationMs, // P1-5 real elapsed (stream-open → terminal)
-        duration_api_ms: durationMs,
-        is_error: true,
-        num_turns: 0,
-        stop_reason: null,
-        total_cost_usd: null, // P1-5: a failed run has no known cost — never a fake 0
-        usage: {
-            inputTokens: 0,
-            outputTokens: 0,
-            cacheReadInputTokens: 0,
-            cacheCreationInputTokens: 0,
-            webSearchRequests: 0,
-        },
-        modelUsage: {},
-        permission_denials: [],
+        durationMs: elapsedMs(ctx),
+        // [909]B1 — errorCode 透传(additive seam 字段;done 臂同款):`failed` 事件的 cancelled/
+        // budget.* 等引擎值原样给集成面。
+        errorCode: ev.errorCode,
         // errorCode + errorMessage flattened into the single CC errors[] string.
         // Rewind-family codes(core 1.292 [833]:resume_at.before_target_not_user /
         // resume_at.before_root_unsupported / rewind_snapshot.unresolvable)透传给用户 —— 这些是
@@ -400,9 +392,6 @@ export function failedToSdkResult(ev, ctx) {
                 ? `${ev.errorMessage} (${ev.errorCode})`
                 : (ev.errorMessage ?? ev.errorCode ?? 'run failed'),
         ],
-        // [909]B1 — errorCode 透传(additive seam 字段;done 臂同款):`failed` 事件的 cancelled/
-        // budget.* 等引擎值原样给集成面。
-        ...(typeof ev.errorCode === 'string' && ev.errorCode.length > 0 ? { errorCode: ev.errorCode } : {}),
     });
 }
 /** Dispatch a terminal AgentEvent to its SDKResult arm. */

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

@@ -36,5 +36,41 @@ export type EngineTurnUsage = NonNullable<Extract<AgentEvent, {
     type: 'turn_end';
 }>['usage']>;
 type TurnUsage = EngineTurnUsage;
+/**
+ * 引擎侧 usage 的**读形**(wire 名,全可选)—— `toCcModelUsage` 的入参。
+ * 全可选是有理由的:本形状同时承接三种来源(`turn_end.usage` 六键必填 / `stats.modelUsage`
+ * 开集 map 里的一行 / 扁平 `TaskStats` 折出来的当前模型行),后两者的键在旧引擎上真的会缺席。
+ * 缺席语义 = **该量在 wire 上没有**,统一折 0(CC `ModelUsage` 的形状不承载 `null`);
+ * 非有限值(NaN/Infinity)同样折 0 —— 见 {@link toCcModelUsage} 头注。
+ */
+export interface EngineUsageLike {
+    readonly inputTokens?: number | undefined;
+    readonly outputTokens?: number | undefined;
+    readonly cacheReadTokens?: number | undefined;
+    readonly cacheWriteTokens?: number | undefined;
+    readonly costMicroUsd?: number | undefined;
+}
+/**
+ * 🔴 **CC `ModelUsage` 八键形状的唯一 mint 点**(REF-CC-062 / xlate-08,E1 单源构造)。
+ *
+ * 收编前本仓有四个构造点(本文件 + `terminalToSdkResult` 的 `mapModelUsage`、合成当前模型行、
+ * `failedToSdkResult` 内联零 usage),四份各写一遍同一套 load-bearing 改名,而 core 3.0.0 的
+ * 语义翻转注只挂在其中一处 —— 「同名不同义」在这种分裂下没有任何一层拦得住([2292] 的 cli HUD
+ * 双算 cache 就是这一族)。收编后:名字映射与语义注都只有这一份。
+ *
+ * 名字映射(**load-bearing,一个字节都别动**):
+ *   inputTokens      → inputTokens
+ *   outputTokens     → outputTokens
+ *   cacheReadTokens  → cacheReadInputTokens
+ *   cacheWriteTokens → cacheCreationInputTokens
+ *   costMicroUsd     → costUSD(/1e6;micro-USD 是 wire 单位,字段名即单位)
+ * DROPPED(wire 无此数,填 0 而不是编一个):webSearchRequests / contextWindow / maxOutputTokens。
+ *
+ * 收编时的**一处语义统一**(REF-CC-062,记在这里以免被读成无意的漂移):cost 的换算此前两份
+ * 写法不同 —— 本文件是裸 `/1e6`(非有限值原样传播出 Infinity/NaN),`terminalToSdkResult` 是
+ * `microUsdToUsd() ?? 0`(非有限即 0)。统一取后者:Infinity 会被下游当成真数字参与求和,把一条
+ * 离谱账静默摊进总计,比 0 更糟(与 SDK `taskCostMicroUsd()` 的规约同义)。
+ */
+export declare function toCcModelUsage(raw: EngineUsageLike): ModelUsage;
 export declare function turnUsageToModelUsage(usage: TurnUsage): ModelUsage;
 export {};

package/dist/adapter/downstream/turnUsageToModelUsage.js

@@ -1,12 +1,40 @@
-export function turnUsageToModelUsage(usage) {
+/** wire 数值 → CC 形状里的数值:非数/非有限一律 0(Infinity 会被当真数字摊进总计,比 0 更糟)。 */
+function finiteOrZero(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+/**
+ * 🔴 **CC `ModelUsage` 八键形状的唯一 mint 点**(REF-CC-062 / xlate-08,E1 单源构造)。
+ *
+ * 收编前本仓有四个构造点(本文件 + `terminalToSdkResult` 的 `mapModelUsage`、合成当前模型行、
+ * `failedToSdkResult` 内联零 usage),四份各写一遍同一套 load-bearing 改名,而 core 3.0.0 的
+ * 语义翻转注只挂在其中一处 —— 「同名不同义」在这种分裂下没有任何一层拦得住([2292] 的 cli HUD
+ * 双算 cache 就是这一族)。收编后:名字映射与语义注都只有这一份。
+ *
+ * 名字映射(**load-bearing,一个字节都别动**):
+ *   inputTokens      → inputTokens
+ *   outputTokens     → outputTokens
+ *   cacheReadTokens  → cacheReadInputTokens
+ *   cacheWriteTokens → cacheCreationInputTokens
+ *   costMicroUsd     → costUSD(/1e6;micro-USD 是 wire 单位,字段名即单位)
+ * DROPPED(wire 无此数,填 0 而不是编一个):webSearchRequests / contextWindow / maxOutputTokens。
+ *
+ * 收编时的**一处语义统一**(REF-CC-062,记在这里以免被读成无意的漂移):cost 的换算此前两份
+ * 写法不同 —— 本文件是裸 `/1e6`(非有限值原样传播出 Infinity/NaN),`terminalToSdkResult` 是
+ * `microUsdToUsd() ?? 0`(非有限即 0)。统一取后者:Infinity 会被下游当成真数字参与求和,把一条
+ * 离谱账静默摊进总计,比 0 更糟(与 SDK `taskCostMicroUsd()` 的规约同义)。
+ */
+export function toCcModelUsage(raw) {
     return {
-        inputTokens: usage.inputTokens ?? 0,
-        outputTokens: usage.outputTokens ?? 0,
-        cacheReadInputTokens: usage.cacheReadTokens ?? 0,
-        cacheCreationInputTokens: usage.cacheWriteTokens ?? 0,
+        inputTokens: finiteOrZero(raw.inputTokens),
+        outputTokens: finiteOrZero(raw.outputTokens),
+        cacheReadInputTokens: finiteOrZero(raw.cacheReadTokens),
+        cacheCreationInputTokens: finiteOrZero(raw.cacheWriteTokens),
         webSearchRequests: 0, // dropped on the wire
-        costUSD: usage.costMicroUsd !== undefined ? usage.costMicroUsd / 1_000_000 : 0,
+        costUSD: finiteOrZero(raw.costMicroUsd) / 1_000_000,
         contextWindow: 0, // dropped on the wire → mock-fill (static per-model table)
         maxOutputTokens: 0, // dropped on the wire → mock-fill
     };
 }
+export function turnUsageToModelUsage(usage) {
+    return toCcModelUsage(usage);
+}

package/dist/adapter/runStream.d.ts

@@ -2,9 +2,11 @@
  * ⇄ B3 批搬迁(2026-07-27,多端改造设计稿 §3 B3 / §2.5 末行):cli `src/seam/adapter/runStream.ts`
  * 整文件搬入。**这个文件是本批的主角** —— 搬迁前它的传递闭包是 **1,571 个文件 / 26 种 Node 内建 /
  * 412 个 react 文件**(实测,设计稿 §5.2 表),整棵 CC 树都在里面;搬迁后是 5 个文件、零 Node
- * 内建、零 react。根因链只有三跳,两条外向边:
- *   · `:215 await import('../../sema/planReviewWire.js')` → `planReviewWire.ts:26 utils/debug` → 整棵树;
- *   · `:140 void import('../../sema/lastTurnUsageStore.js')`(闭包本身干净,但同样是壳内向的边)。
+ * 内建、零 react。根因链只有三跳,两条外向边(REF-CC-063 同款:原文是两个裸行号锚,已改符号锚):
+ *   · 终帧前的 plan-review park 臂 `await import('../../sema/planReviewWire.js')` → 该模块的
+ *     `utils/debug` 值级 import → 整棵树;
+ *   · turn_end 折叠点的 `void import('../../sema/lastTurnUsageStore.js')`(闭包本身干净,但同样
+ *     是壳内向的边)。
  * 本批把这两条边改成 **chrome 事件**(`plan_review_park` / `last_turn_usage`,见 seam.ts 臂注释),
  * 由宿主注入 `ctx.emitChrome` 消费 —— 库侧再也不 import 壳。
  *
@@ -31,6 +33,29 @@
 import type { AgentEvent } from '@sema-agent/sdk';
 import { type SDKMessage, type EmitContext, type ModelUsage } from './types.js';
 import type { EngineTurnUsage } from './downstream/turnUsageToModelUsage.js';
+/** #114/[C65] 单源化:三端共用的 409 active-run 拒收终帧判别(富信号形,包级唯一权威)。
+ *  与壳/desktop 各自照抄件同义——0.13.0 到货后各端换包导入删本地抄件。 */
+export interface ActiveRunBusySignal {
+    /** 占锁 run 的 id;wire 没带 ⇒ null(诚实缺席,绝不铸造)。 */
+    readonly activeTaskId: string | null;
+    /** server 3.21+ 真发的占锁 run 状态;缺席 ⇒ null(由调用方走 runs.get 一级)。 */
+    readonly activeTaskStatus: string | null;
+    /** 409 body 的 pendingGate(wire 给的真路由,不自造);缺席 ⇒ null。 */
+    readonly pendingGate: {
+        readonly kind: string | null;
+        readonly decidePath: string | null;
+    } | null;
+}
+/**
+ * 判别一个**原始 AgentEvent** 是不是 409 active-run 拒收终帧;非 busy ⇒ null。
+ * 判据=结构两腿(canonical `errorCode` 优先 → `activeTaskId` 在场);人话文案腿已随 #117 提货
+ * 退役(§B8 禁按错误文案判别)。两种 wire 真形:
+ *   ① `done{result:{status:'failed', errorCode|activeTaskId,…}}`(交互 tasks/stream 腿,409 骑终帧);
+ *   ② `failed{errorCode|activeTaskId,…}`(任何把它投影成 failed 臂的上游形)。
+ */
+export declare function activeRunBusySignal(ev: unknown): ActiveRunBusySignal | null;
+/** 测试钩:清空「已上报过的臂」去重表(去重是**跨调用**状态,不清就只有第一条用例看得见)。 */
+export declare function _resetDroppedFrameReportForTest(): void;
 export interface RunStreamHandle {
     /** The latest folded turn usage (footer counters); updated on each turn_end. */
     latestUsage?: ModelUsage;
@@ -39,7 +64,7 @@ export interface RunStreamHandle {
      * `totalInputTokens`)。镜像键求和≠总量(仅 cache 族一致时相等),总量消费面吃这份。
      * 旧引擎(core <3.0.0)wire 缺形时为 undefined —— 诚实缺席,不造零值。
      */
-    latestEngineUsage?: EngineTurnUsage;
+    latestEngineUsage?: EngineTurnUsage | undefined;
 }
 export declare function isRunStreamActive(): boolean;
 export declare function runStream(events: AsyncIterable<AgentEvent>, ctx: EmitContext, handle?: RunStreamHandle): AsyncGenerator<SDKMessage>;