@sema-agent/client-core 0.67.1 → 0.68.0

package/dist/adapter/downstream/terminalToSdkResult.js

@@ -1,4 +1,5 @@
 import { stamp } from '../types.js';
+import { putOwnKey } from '../../ownKey.js';
 // 0.60.0(engine ≥7.64.0 / sdk 8.4.0):终局读数的**单一读器**(两代字节 → 一个带标因由)。
 import { isReviewPark, readRunTerminal, runTerminalCode, runTerminalGateToolName, } from '../../runTerminal.js';
 import { toCcModelUsage } from './turnUsageToModelUsage.js';
@@ -160,22 +161,11 @@ function permissionDenialParts(stats) {
 }
 /**
  * 0.67.1 —— **以 wire 给的 id / 键名当对象键**时的唯一落键姿势(`__proto__` 陷阱)。
- *
- * 🔴 `Object.prototype.__proto__` 是一个 **accessor**:在一只普通对象上写 `o["__proto__"] = v`
- * 走的是那只 setter ——**不产生自有属性**(v 是对象时还顺手改了 `o` 的原型),于是那一行在
- * `Object.keys` / `JSON.stringify` 里**整条消失**,连行数都少一。而本文件这几张表的键全都来自
- * wire(taskId / modelId / core 开集的 costBreakdown 键名),没有任何一条保证它们不等于这个字面。
- * ⇒ 落键一律走 `defineProperty`,与本包 `hitl/crashConverged.ts` 交付快照时的处置**同一条**
- * (那里逐字:「落键仍走 `defineProperty`(`__proto__` 同理)」)。
- *
- * 🔴 **不改成 null 原型对象交付**:端拿到的仍是一只正常对象(`hasOwnProperty` / `toString` 都在),
- * 本修只改「落键」这一步,不改交付形 —— 换原型会在宿主侧造出一类新的 `TypeError`。
- * 描述符与普通赋值**逐位相同**(`writable/enumerable/configurable` 三真),所以除了 `__proto__`
- * 这一个字面,其余每一个键的行为一个字节都没变。
+ * 🔴 0.68.0 / L-246 B2:实现**下沉到 `src/ownKey.ts`**(单源)—— 修前本文件与
+ *    `hitl/parkResolver.ts` 各持一份同形实现,理由、陷阱与「不改成 null 原型交付」的取舍都在
+ *    那个模块的头注里。本别名保留是为了本文件三十余处调用点零改动。
  */
-function putOwn(table, key, value) {
-    Object.defineProperty(table, key, { value, enumerable: true, writable: true, configurable: true });
-}
+const putOwn = putOwnKey;
 /** 有限数窄化(非数 / 非有限 ⇒ 缺席;`0` 是事实不是缺席)。 */
 function finiteOrAbsent(v) {
     return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
@@ -185,21 +175,26 @@ function finiteOrAbsent(v) {
  *
  * 🔴 它为什么必须是一只函数、而不是两处各写一遍的表达式:下界位有**两个来源**——
  *   · `stats.usageMissing`:只在带得出 `TaskResult` 的终帧上有;
- *   · `ctx.usageMissingObserved`:流内观测(`failed` 事件帧 / 409 拒绝信封 / park 体**没有 stats**,
+ *   · **本条流**的流内观测(`failed` 事件帧 / 409 拒绝信封 / park 体**没有 stats**,
  *     只读 stats 的话一条已经观测到缺口的 run 会在终帧上被读成「每一轮都报了 usage」)。
  * 修前取并只包在**终帧**那一面({@link costFactParts}),而 chrome 对账臂的铸点直接展开
  * `readRunCostFacts(stats).reconcile` ⇒ 「流内观测到缺口、终局 stats 对此缄默」那一形上两面各说
  * 各的(终帧铸了 `_sema_usage_lower_bound`、同一拍的臂上没有 `usageLowerBound`)——
  * [paired-mechanisms-must-share-premise] 的教科书形。⇒ 取并**下沉到这里**,两面共用。
  *
+ * 🔴 **第二参是「这一条流」的观测快照,不是一个跨流留存的状态**(0.67.2 / 车 I 件 I-1):它此前住在
+ * `EmitContext` 上、只写 `true` 永不清,而 ctx 是调用方的对象、可以复用给多条流 ⇒ 上一条流的缺口
+ * 会把下一条账数得全的流标成下界(顺序复用),或两条并发流互相串。现在由 `runStream` 按流持有、
+ * 终局**按值**交给两个投影口;端自建管线同样是**按次调用**传入。
+ *
  * 🔴 **严格 true 才认**(core 契约:`true` 或缺席,恒不写 `false`/`null`);`stats` 不是可读对象时
  * 它那一半读作「没说」,而流内观测那一半**照旧成立**。
  */
-function usageLowerBoundOf(stats, ctx) {
+function usageLowerBoundOf(stats, observed) {
     const statsSaid = stats !== null && typeof stats === 'object' && !Array.isArray(stats)
         ? stats.usageMissing === true
         : false;
-    return statsSaid || ctx?.usageMissingObserved === true;
+    return statsSaid || observed?.usageMissingObserved === true;
 }
 /**
  * D-3 / B-068 · L-198 —— 终局成本事实的**唯一读器**(终帧超集键与 chrome 对账臂共用)。
@@ -207,13 +202,15 @@ function usageLowerBoundOf(stats, ctx) {
  * 🔴 `stats` 不是可读对象(409 拒绝信封 / park 体 / `failed` 事件帧)⇒ 返 `undefined` =
  * **这条帧没有账**,调用方据此「不说话」(不发臂、不铸键),而不是发一条全缺席的空账。
  *
- * 🔴 **第二参 `ctx`(0.67.1 / B-091,additive)**:流内观测面。给了它,对账段上的
+ * 🔴 **第二参 `observed`(0.67.1 / B-091,additive)**:**这一条流**的流内观测快照。给了它,对账段上的
  * {@link RunCostReconcile.usageLowerBound} 就是**取并后**的读数(见 {@link usageLowerBoundOf});
  * 不给(旧签名)⇒ 只读 `stats` 那一半,既有端逐位不变。
  * ⚠️ 包内的两个调用点(`costFactParts` 与 `runStream` 的 `run_cost_reconciled` 铸点)**都必须**
  * 传它 —— 少传一处就是把本件修的那条不对称原样种回去。
+ * 🔴 0.67.2 / 车 I 件 I-1:它是**按次调用的入参**,不再是 `EmitContext` 上的一格 —— 共享 ctx 被复用
+ * 给多条流时,那一格会把别的流的缺口串进这一条(见 {@link usageLowerBoundOf} 的第三段 🔴)。
  */
-export function readRunCostFacts(stats, ctx) {
+export function readRunCostFacts(stats, observed) {
     // 数组也不是「一份账」:`typeof [] === 'object'` 会把一条畸形载体放进来,然后它的每一格都读不出
     // ⇒ 发出一条「own 没定价」的臂,而真相是**这条帧根本没有账**(两句话又折成一句)。
     if (stats === null || typeof stats !== 'object' || Array.isArray(stats))
@@ -260,7 +257,7 @@ export function readRunCostFacts(stats, ctx) {
     // 0.67.0(core 7.14.0):usage 下界位。**严格 true 才铸**(core 契约:`true` 或缺席,恒不写
     // `false`/`null`;认宽了就会把一个 falsy 值渲成「数得不全」)。它与成本三段正交,所以读在这里、
     // 与三段同一只读器出 —— 两面(终帧超集键 / chrome 对账臂)因此永远不会各算各的。
-    const usageLowerBound = usageLowerBoundOf(stats, ctx);
+    const usageLowerBound = usageLowerBoundOf(stats, observed);
     const reconcile = {
         ...(ownMicroUsd !== undefined ? { ownMicroUsd } : { costAbsent: true }),
         ...(usageLowerBound ? { usageLowerBound: true } : {}),
@@ -283,8 +280,8 @@ export function readRunCostFacts(stats, ctx) {
  * (超集键纪律:CC 形上已有的位不许塞我们自己的含义)。「fully-reconciled spend」由消费方按
  * 这两个超集键自己加 —— 包给的是**可对账的事实**,不是一个改了口径的数。
  */
-function costFactParts(stats, ctx) {
-    const facts = readRunCostFacts(stats, ctx);
+function costFactParts(stats, observed) {
+    const facts = readRunCostFacts(stats, observed);
     // 🔴 **下界位与成本三段分开算**(异源对抗复审 [medium] 实抓):`stats` 读不出(`failed` 事件帧 /
     //    409 拒绝信封 / park 体)时**成本**那三段确实没有账、一条都不该说;但「这条流观测到过一轮
     //    没有 usage」这件事**照旧成立**,而那种终帧的 `usage` 恰恰是 `flattenUsage(undefined)` 的
@@ -293,7 +290,7 @@ function costFactParts(stats, ctx) {
     // 🔴 0.67.1 / B-091:取并本身已经**下沉**到 {@link usageLowerBoundOf} —— 这里与读器内部、与
     //    chrome 对账臂读的是**同一只函数**,三面不会各算各的(`facts === undefined` 时读器整只不
     //    返回,所以这一行必须自己再调一次那只判据,而不是回头读 `facts`)。
-    const lowerBound = usageLowerBoundOf(stats, ctx);
+    const lowerBound = usageLowerBoundOf(stats, observed);
     const lowerBoundPart = lowerBound ? { _sema_usage_lower_bound: true } : {};
     if (facts === undefined)
         return lowerBoundPart;
@@ -312,6 +309,47 @@ function costFactParts(stats, ctx) {
         //    (本位在上面与流内观测取并后已铸;这里不再重复。)
     };
 }
+// ══ 0.68.0(L-244 包侧半场)—— 子代用量「这笔账是下界」的**自有位**,与终帧那一位**分名** ══
+//
+// ── 病形(三重复审 A4/B10 在壳上实抓)──────────────────────────────────────────────────────
+// 壳的子代用量 store 把「这一行还没收口(`partial`)」∪「这一轮引擎没报账(`usageMissing`)」两件事
+// 铸成了一个**与终帧同名**的键 `_sema_usage_lower_bound`。两者是**同名异义**:
+//   · 终帧那一位答的是「**这条 run 的合计**是下界」(来源 = `stats.usageMissing` ∪ 流内观测);
+//   · 子代面那一位答的是「**这一只子代的这一行**现在还不是最终数」(来源 = 行还没收口 / 那一轮没报账)。
+// 同名的代价是消费面分不出自己读到的是哪一个:一个按键名做聚合的面(把所有 `_sema_usage_lower_bound`
+// 收起来渲一句「本次会话的账是下界」)会把一条**只是还没收口的子代行**算成整条 run 的账不可信。
+//
+// ⇒ 包侧给出**自有名**与**唯一判据**,壳/web/desktop 三端照它渲,谁都不再自己拼一个键名:
+/**
+ * 子代用量面的**下界判别位键名**(`_sema_subagent_usage_partial`)。
+ *
+ * 🔴 它与终帧的 `_sema_usage_lower_bound` **刻意不同名**(见上段):两者答的是两个问题,
+ *    一个消费面同时拿到两者时必须分得出来。
+ * 🔴 本包**不在任何 wire 帧上铸它** —— 它是**渲染面**的位(端把一行子代用量交给自己的视图时用)。
+ *    包给名与判据,是为了三端零自拼(同 `gateIdentity` 的三条身份键字面同一条纪律)。
+ */
+export const SEMA_SUBAGENT_USAGE_PARTIAL_KEY = '_sema_subagent_usage_partial';
+/**
+ * 一行子代用量的数字**是不是下界**({@link SEMA_SUBAGENT_USAGE_PARTIAL_KEY} 该不该立)。
+ *
+ * 三个来源**取并**,每一条都能独立让这一行的数字不是最终数:
+ *  · `row.usageMissing` —— 这只子代**至少有一轮**引擎没报账(数字照累加,但它是下界);
+ *  · `row.keyCollision` —— 两个命名空间的 id 撞了字面,这一行是**几只子代的账并起来的**;
+ *  · `opts.tablePartial` —— 整张表对不上引擎的权威合计(`_sema_nested_usage_by_task_partial`)⇒
+ *    表里**每一行**都不可证完整。
+ *
+ * 🔴 **`false` 不是「这一行是最终数」的证据**:它只说「本端没有任何一条理由认为它是下界」。
+ *    行本身还没收口(端自己的 store 知道,包不知道)时,端要自己把那一条并进来 —— 所以这只谓词
+ *    收一个 `opts`,而不是假装它掌握全部真相。
+ * 🔴 非对象 / 缺席入参 ⇒ `false`(答不出,不是断言);坏形位(非 `true` 的值)不当真。
+ */
+export function subagentUsageIsPartial(row, opts) {
+    if (opts?.tablePartial === true)
+        return true;
+    if (typeof row !== 'object' || row === null)
+        return false;
+    return row.usageMissing === true || row.keyCollision === true;
+}
 /**
  * L-228 —— 流内子代分表 → 终帧两个超集键的**唯一 mint 点**(成功臂与错误信封共用)。
  *
@@ -332,31 +370,74 @@ function costFactParts(stats, ctx) {
  *    本判据只会**多**铸 partial(把一张其实完整的表说成不完整),**永远不会**把一张残表说成完整。
  * 🔴 **两个键不互证、也不相加**:`_sema_nested_usage`(合计,引擎报的)与本表(流内看见的)是
  *    两份独立的账;`partial` 在场时两者**本来就该不等**,消费方不许拿其中一份去「修正」另一份。
+ * 🔴 **0.67.2(车 I 件 I-2)身份键碰撞**:累加表的键按出身隔离(`s:` / `p:`),交付面按裸 id 归并 ——
+ *    跨命名空间的同字面合并成一行、立 {@link SemaSubagentUsageRow.keyCollision},并让 `partial` 恒立。
+ * 🔴 **0.67.2(车 I 件 I-2b)这张表是「本流快照」,不再从 `EmitContext` 上读**(与件 I-1 逐字同形的
+ *    同形存量,轮二异源复审实抓):流结束后它此前**留在调用方对象上**,而本文件这三只终帧投影器是
+ *    **公面导出** —— 端「A 走 runStream、B 直调终帧投影」共用一个 ctx 时,B 的终帧会带出 **A 的**分表;
+ *    B 的 `nested` 计数若恰好与那张表对得上(`tasks`/`turns` 相等),`partial` 还不铸 = 一张属于别人的
+ *    表被标成「可证完整」。⇒ 表随终帧那一拍**按值**传进来;没传 ⇒ 两个键都不铸(诚实缺席:这次投影
+ *    一条子流都没看见),**绝不**回头读残留。
  */
 function nestedUsageByTaskParts(stats, rollup) {
     // 🔴 一行都没有 ⇒ **什么都不说**:空表会被读成「这条 run 一个子代都没委派」,而真相可能是
     //    「委派了,但这条流没看见任何一轮」(重连车道)。两句话不许折成一句。
     if (rollup === undefined || rollup.size === 0)
         return {};
-    const rows = {};
     let turnsSeen = 0;
     // 🔴 0.67.1:行键的**出身**统计(见 {@link MutableSubagentUsageRow.keyFromParentFallback})。
-    //    出身按行是均匀的 —— 一行的键要么恒是 `sourceTaskId`、要么恒是回落的父调用 id
-    //    (`taskId = sourceTaskId ?? parent`:真身份在场时永远不会落到回落键那一行上)。
+    //    出身按行是均匀的 —— 0.67.2 起这件事由**键空间**保证:累加表的键带 `s:` / `p:` 前缀,所以
+    //    一行的每一轮必然来自同一个命名空间(修前靠的是「`taskId = sourceTaskId ?? parent`」那条推理,
+    //    而那条推理在两个空间撞字面时不成立)。
     let fallbackKeyedRows = 0;
     let sourceKeyedRows = 0;
-    for (const [taskId, r] of rollup) {
+    // ── 🔴 0.67.2(车 I 件 I-2)—— 交付面按**裸 id** 归并,跨命名空间的同字面 = **碰撞** ──────────
+    // 交付面的键必须是裸 id(端零改),而累加表的键带出身前缀 ⇒ 两个命名空间里字面相同的两行会在这里
+    // 落到同一个交付键上。本层**没有任何读数**能把它们拆回去(core 的合同不保证两个命名空间互斥),
+    // 于是:合并数字(不偷偷丢一边)+ 立 `keyCollision`(如实说这一行是混的)+ `partial` 恒立
+    // (证不出逐任务归属就不许说完整)。
+    // 🔴 为什么不「两行分列」:交付形是 `Record<taskId, row>`,同一个裸 id 不可能占两格 —— 要分列就得
+    //    改交付键的形(把出身前缀推到 wire 上),那是三端 BREAKING,而且把本层的内部编码变成端要解的
+    //    身份语义。合并 + 显式标记是**同一批事实**下唯一不撒谎的交付形。
+    const merged = new Map();
+    for (const r of rollup.values()) {
         turnsSeen += r.turns;
         if (r.keyFromParentFallback === true)
             fallbackKeyedRows += 1;
         else
             sourceKeyedRows += 1;
+        const prev = merged.get(r.taskId);
+        if (prev === undefined) {
+            merged.set(r.taskId, {
+                turns: r.turns,
+                inputTokens: r.inputTokens,
+                outputTokens: r.outputTokens,
+                ...(r.cacheReadTokens !== undefined ? { cacheReadTokens: r.cacheReadTokens } : {}),
+                ...(r.usageMissing === true ? { usageMissing: true } : {}),
+            });
+            continue;
+        }
+        prev.turns += r.turns;
+        prev.inputTokens += r.inputTokens;
+        prev.outputTokens += r.outputTokens;
+        // `cacheReadTokens` 的缺席语义在合并处也守住:两边都没报过 ⇒ 键仍不铸(0 会被读成「零命中」)。
+        if (r.cacheReadTokens !== undefined)
+            prev.cacheReadTokens = (prev.cacheReadTokens ?? 0) + r.cacheReadTokens;
+        if (r.usageMissing === true)
+            prev.usageMissing = true;
+        prev.keyCollision = true;
+    }
+    const keyCollisions = [...merged.values()].filter((v) => v.keyCollision === true).length;
+    const rows = {};
+    for (const [taskId, v] of merged) {
+        // 🔴 落键仍走 `putOwn`(`__proto__` 陷阱):合并臂不是绕过那条纪律的第二条路(见 `putOwn` 头注)。
         putOwn(rows, taskId, {
-            turns: r.turns,
-            inputTokens: r.inputTokens,
-            outputTokens: r.outputTokens,
-            ...(r.cacheReadTokens !== undefined ? { cacheReadTokens: r.cacheReadTokens } : {}),
-            ...(r.usageMissing === true ? { usageMissing: true } : {}),
+            turns: v.turns,
+            inputTokens: v.inputTokens,
+            outputTokens: v.outputTokens,
+            ...(v.cacheReadTokens !== undefined ? { cacheReadTokens: v.cacheReadTokens } : {}),
+            ...(v.usageMissing === true ? { usageMissing: true } : {}),
+            ...(v.keyCollision === true ? { keyCollision: true } : {}),
         });
     }
     const nested = stats !== null && typeof stats === 'object' && !Array.isArray(stats)
@@ -369,7 +450,11 @@ function nestedUsageByTaskParts(stats, rollup) {
     //    出身一致时既有两条对账才是充分的:全真身份 ⇒ 一行一任务;全回落 ⇒ 多任务共父会让行数 <
     //    `nested.tasks`,那一格自己会翻。失效方向仍是安全的那一侧(只会**多**铸 partial)。
     const mixedKeyOrigin = fallbackKeyedRows > 0 && sourceKeyedRows > 0;
-    const complete = !mixedKeyOrigin && authTurns !== undefined && authTasks !== undefined &&
+    // 🔴 0.67.2:碰撞也单独挡一格。按构造 `keyCollisions > 0 ⇒ mixedKeyOrigin`(同一个命名空间里的键
+    //    本来就唯一,撞字面只能跨空间发生),所以这一格今天是**冗余的第二道**;留着是因为两条判据问的
+    //    不是同一件事(「这条流上有两种出身」vs「这一行里混了两种出身」),而上游哪天再加一个身份来源
+    //    时,前者的判法要改、后者不用。
+    const complete = !mixedKeyOrigin && keyCollisions === 0 && authTurns !== undefined && authTasks !== undefined &&
         authTurns === turnsSeen && authTasks === Object.keys(rows).length;
     return {
         _sema_nested_usage_by_task: rows,
@@ -628,10 +713,10 @@ function errorResult(ctx, parts) {
         // D-1 / L-192①:两句话不再折成一句 —— 清单 + 「有没有这本账」的判别位,见 permissionDenialParts。
         ...permissionDenialParts(parts.stats),
         // D-3 / B-068:失败/到限/park 的 run 一样花过钱,账不因结局不好就不报。
-        ...costFactParts(parts.stats, ctx),
+        ...costFactParts(parts.stats, parts.observed),
         // L-228(0.67.0):流内 per-subagent 分表的收口快照(判据本体在 `nestedUsageByTaskParts`)。
         // 🔴 与成本三段同理 —— 失败的 run 一样委派过,账不因结局不好就不报。
-        ...nestedUsageByTaskParts(parts.stats, ctx.nestedUsageByTask),
+        ...nestedUsageByTaskParts(parts.stats, parts.observed?.nestedUsageByTask),
         errors: [...parts.errors],
         ...(parts.errorCode !== undefined && parts.errorCode.length > 0 ? { errorCode: parts.errorCode } : {}),
         ...(parts.degraded !== undefined ? { degraded: parts.degraded } : {}),
@@ -641,7 +726,13 @@ function errorResult(ctx, parts) {
     });
 }
 /** `done` → SDKResultSuccess (contract 02 §2.10 / 08 CS-10). */
-export function doneToSdkResult(ev, ctx) {
+export function doneToSdkResult(ev, ctx, 
+/**
+ * 0.67.2:**这一条流**的收口快照 —— usage 缺口观测(见 {@link usageLowerBoundOf})与 per-subagent
+ * 累加表(见 {@link nestedUsageByTaskParts})。两格都是 per-stream 的事实,缺席 ⇒ 这次投影没有流内面
+ * (只读 `stats` 那一半、两个分表键都不铸),**绝不**回头去读调用方对象上可能残留的上一条流。
+ */
+observed) {
     // 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
@@ -693,7 +784,7 @@ export function doneToSdkResult(ev, ctx) {
     //    failed + limits.max_{tokens,walltime}_exceeded 两族共用)。
     const degraded = degradedOf(r);
     /** 四个 error 臂共享的固定位(信封其余 13 位见 `errorResult`)。 */
-    const errorBase = { durationMs, stats, model: r.model, errorCode, degraded };
+    const errorBase = { durationMs, stats, model: r.model, errorCode, degraded, observed };
     if (terminal?.kind === 'failed') {
         // [909]B1 — failed 臂 subtype 语义化(见文件头对表);core 5.8.0([2489])起到限码全部改名,
         // 映射本身已收进单点 `subtypeForErrorCode`(退役批后只认新码)。
@@ -824,10 +915,10 @@ export function doneToSdkResult(ev, ctx) {
         // D-1 / L-192①:同形第二处 —— 与错误信封共用**同一个** mint 点(修前两处各一个字面量 [])。
         ...permissionDenialParts(stats),
         // D-3 / B-068:成本明细与子代那本账(micro-USD 原值);`total_cost_usd` 语义一字不动。
-        ...costFactParts(stats, ctx),
+        ...costFactParts(stats, observed),
         // L-228(0.67.0):流内 per-subagent 分表的收口快照;与 `_sema_nested_usage`(引擎报的合计)
         // 是**两份独立的账**,不相加、不互证(见 `nestedUsageByTaskParts` 顶注)。
-        ...nestedUsageByTaskParts(stats, ctx.nestedUsageByTask),
+        ...nestedUsageByTaskParts(stats, observed?.nestedUsageByTask),
         // 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
         // consumer reads (it is ALSO surfaced as the `modelUsage` key). Omitted when the wire didn't carry it.
@@ -835,7 +926,9 @@ export function doneToSdkResult(ev, ctx) {
     });
 }
 /** `failed` → SDKResultError (contract 02 §2.11 / 08 CS-11). */
-export function failedToSdkResult(ev, ctx) {
+export function failedToSdkResult(ev, ctx, 
+/** 0.67.2:同 {@link doneToSdkResult} 的第三参。 */
+observed) {
     // Flatten the 4 CC error subtypes onto the single neutral errorCode.
     // error_max_budget_usd is a non-error "budget exceeded" notice, not a crash
     // (contract 02 §2.11) — the renderer branches on subtype.
@@ -851,6 +944,7 @@ export function failedToSdkResult(ev, ctx) {
     // `failed` 事件帧本体不带 stats/model/degraded,所以这三个位如实缺席 —— 不是「这里少算了」。
     return errorResult(ctx, {
         subtype,
+        observed,
         durationMs: elapsedMs(ctx),
         // [909]B1 — errorCode 透传(additive seam 字段;done 臂同款):`failed` 事件的 cancelled/
         // limits.* 等引擎值原样给集成面。
@@ -866,7 +960,13 @@ export function failedToSdkResult(ev, ctx) {
         ],
     });
 }
-/** Dispatch a terminal AgentEvent to its SDKResult arm. */
-export function terminalToSdkResult(ev, ctx) {
-    return ev.type === 'done' ? doneToSdkResult(ev, ctx) : failedToSdkResult(ev, ctx);
+/**
+ * Dispatch a terminal AgentEvent to its SDKResult arm.
+ *
+ * 🔴 第三参(0.67.2 / 车 I 件 I-1):**这一条流**的 usage 观测快照。`runStream` 在终帧那一拍**按值**
+ * 交给它与 `run_cost_reconciled` 铸臂 —— 两个投影口读的是**同一份本流快照**,而不是一个可能被别的流
+ * 写过的共享位。缺席(端直调)⇒ 与 0.67.1 的旧签名逐位同行为。
+ */
+export function terminalToSdkResult(ev, ctx, observed) {
+    return ev.type === 'done' ? doneToSdkResult(ev, ctx, observed) : failedToSdkResult(ev, ctx, observed);
 }

package/dist/adapter/runStream.d.ts

@@ -32,7 +32,7 @@
  */
 import type { AgentEvent } from '@sema-agent/sdk';
 import { type SDKMessage, type EmitContext, type ModelUsage } from './types.js';
-import type { EngineTurnUsage } from './downstream/turnUsageToModelUsage.js';
+import { type EngineTurnUsage } from './downstream/turnUsageToModelUsage.js';
 /**
  * 409 body 的 pendingGate 材料(A-028.1,2026-08-12 具名化并补 `governanceForced` 位 ——
  * 此前包侧只有 {kind, decidePath} 两位,壳侧抄件已多出该位 = 同一 wire 位两份解析器形不同,
@@ -178,14 +178,34 @@ export declare function _resetDroppedFrameReportForTest(): void;
  *  证不了「表有没有涨」;两者在到顶之后恰好分道扬镳,所以必须直接读表)。 */
 export declare function _droppedFrameMemoSizeForTest(): number;
 export interface RunStreamHandle {
-    /** The latest folded turn usage (footer counters); updated on each turn_end. */
+    /**
+     * The latest folded turn usage (footer counters).
+     *
+     * 🔴 **0.68.0 收窄成「最近一次**已测量**的 turn」**(core 7.17.0 #711 的跟车修;异源对抗复审实抓):
+     *    #711 之后,一轮没量出账时引擎发的是**六个 0 + `usageMissing:true`**(不再是「不发 usage」)。
+     *    修前这里是无条件覆盖 ⇒ 那种轮会把一份**占位全零**盖进来,而本形上**没有任何判别位** ——
+     *    只吃这个出口的 footer 于是把「不知道」渲成一笔精确的零账(消息臂与 chrome 臂上的判别位
+     *    保护不到这个出口)。⇒ 未测量的那一轮**不覆盖**(保留上一次真读数,与 #711 之前的行为逐字
+     *    相同),并由 {@link latestUsageMissing} 说出「最新那一轮没测出账」。
+     */
     latestUsage?: ModelUsage;
     /**
      * [2295] 裁 ② 逐字通道:与 latestUsage 同拍更新的引擎 `turn_end.usage` **原形**(六键含
      * `totalInputTokens`)。镜像键求和≠总量(仅 cache 族一致时相等),总量消费面吃这份。
      * 旧引擎(core <3.0.0)wire 缺形时为 undefined —— 诚实缺席,不造零值。
+     * 🔴 0.68.0:与 {@link latestUsage} **同拍同律** —— 未测量的轮不覆盖。
      */
     latestEngineUsage?: EngineTurnUsage | undefined;
+    /**
+     * 🔴 0.68.0 —— **最新那一轮的账知不知道**。在场(恒 `true`)= 最近走过的那个 `turn_end`
+     * **没测出账**(`usageMissing:true`),或者它是一条**契约违约**帧(连 usage 都没有);
+     * 此时上面两份读数属于**更早的**那一轮,别当成最新那一轮的账。
+     *
+     * 🔴 **never false**:测量到账的那一轮**把这一位删掉**(键不在场 ⇔ 上面两份就是最新那一轮的账)。
+     *    它是**逐轮**的判别位,不是「这条流上曾经有过缺口」的单调位 —— 后者在终帧上
+     *    (`_sema_usage_lower_bound`),两者答的是两个问题。
+     */
+    latestUsageMissing?: true;
 }
 export declare function isRunStreamActive(): boolean;
 export declare function runStream(events: AsyncIterable<AgentEvent>, ctx: EmitContext, handle?: RunStreamHandle): AsyncGenerator<SDKMessage>;