@sema-agent/client-core 0.67.2 → 0.68.1

package/dist/adapter/activeRunSelfHeal.js

@@ -173,6 +173,53 @@ function readStatus(record) {
     const st = record?.status;
     return typeof st === 'string' && st.length > 0 ? st : null;
 }
+/**
+ * 「这条 run 还占着会话吗」的**直接读数**(0.68.0 / L-230;server 7.73.0 S-122 P-45:
+ * `GET /v1/runs/:id` 上的 `heldBy`)。
+ *
+ * 三态,**刻意不是布尔**:
+ *  · `'held'`     —— `heldBy` 是一个非空串 = **有一条 run 名字在上面**,它确实还占着;
+ *  · `'released'` —— `heldBy` 显式是 `null` = 一句**正面事实**:会话已经交出来了;
+ *  · `'unknown'`  —— 这一位**整键缺席**(老引擎 / 不发这一位的部署),或者形不对
+ *    (非串非 null)⇒ 读不出,**绝不**当成 released。
+ *
+ * 🔴 `null` 与「键不在」必须分开,这是本读器存在的全部理由:
+ *    把两者都读成「释放了」,老引擎上每一次探测都会当场答「已释放」并立刻重发那条消息 ——
+ *    而它可能一头撞回一个还锁着的会话(再吃一个 409,正是这条腿存在的理由);
+ *    把两者都读成「还占着」,新引擎上那句正面事实白给了,窗要一直等到点。
+ * 🔴 判据用 `Object.hasOwn`:`{heldBy: undefined}` 与 `{}` 在这里是**同一件事**(都读不出),
+ *    而 `null` 必须与它们分开 —— 靠 `?? ` / `!= null` 一类写法分不出来。
+ */
+function readClaimHolder(record) {
+    if (record === null || typeof record !== 'object')
+        return 'unknown';
+    if (!Object.hasOwn(record, 'heldBy'))
+        return 'unknown';
+    const v = record.heldBy;
+    if (v === null)
+        return 'released';
+    if (typeof v === 'string' && v.length > 0)
+        return 'held';
+    // 空串 / 数 / 对象:形不对 ⇒ 读不出(失效方向在保守那一侧:不宣告释放)。
+    return 'unknown';
+}
+/**
+ * cancel 回执(202 体)/ run 行上的 `cancelRequested`(0.68.0 / L-230;server 7.73.0 S-122 P-45)。
+ *
+ * 🔴 **三态**同上:`true` / `false` 都是真读数,**读不出 ⇒ `undefined`**(老引擎不发这一位)。
+ *    绝不折 `false` —— 「没请求过取消」与「不知道有没有请求过」对下一步的含义不同:前者可以放心
+ *    再发一次 cancel,后者再发就可能是第二枪。
+ * 🔴 它**不是**「已经取消了」:上游逐字是 *requested*,一次**已受理的请求**,不是终局。
+ *    会话有没有交出来仍然只由 {@link readClaimHolder} 与 {@link CLAIM_RELEASED_STATES} 回答。
+ */
+export function readCancelRequested(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        return undefined;
+    if (!Object.hasOwn(body, 'cancelRequested'))
+        return undefined;
+    const v = body.cancelRequested;
+    return typeof v === 'boolean' ? v : undefined;
+}
 /** 重开判决 → 结局(真呈现回执消费点:`presented === false` 时 reopened 断言不成立)。 */
 function reopenDelivered(verdict) {
     return verdict.reopened === true && verdict.presented !== false;
@@ -339,28 +386,33 @@ export async function waitForClaimRelease(taskId, deps) {
     const isAborted = () => deps.signal?.aborted === true;
     let delay = CANCEL_POLL_START_MS;
     let lastStatus = null;
+    // 🔴 0.68.0 / L-230:`heldBy` 的三态与 `lastStatus` **同律** —— 只记最近一次**有回答**的探测。
+    let lastHolder = 'unknown';
     for (;;) {
         if (isAborted())
-            return { released: false, waitedMs: waited(), aborted: true, lastStatus };
+            return { released: false, waitedMs: waited(), aborted: true, lastStatus, lastHolder };
         const remaining = deadline - now();
         if (remaining <= 0)
-            return { released: false, waitedMs: waited(), aborted: false, lastStatus };
+            return { released: false, waitedMs: waited(), aborted: false, lastStatus, lastHolder };
         await sleep(Math.min(delay, remaining), deps.signal);
         if (isAborted())
-            return { released: false, waitedMs: waited(), aborted: true, lastStatus };
+            return { released: false, waitedMs: waited(), aborted: true, lastStatus, lastHolder };
         delay = Math.min(Math.round(delay * 1.5), CANCEL_POLL_MAX_MS);
         let status;
+        let holder;
         const lease = claimProbeLease(deps.signal, deadline - now());
         try {
-            status = readStatus(await deps.get(taskId, {
+            const record = await deps.get(taskId, {
                 signal: lease.signal,
                 ...(deps.session !== undefined ? { session: deps.session } : {}),
-            }));
+            });
+            status = readStatus(record);
+            holder = readClaimHolder(record);
         }
         catch {
             lease.release();
             if (isAborted())
-                return { released: false, waitedMs: waited(), aborted: true, lastStatus };
+                return { released: false, waitedMs: waited(), aborted: true, lastStatus, lastHolder };
             // 🔴 本发是被**窗自己的截止**掐掉的(lease 到点;caller 未中止)⇒ 没有读到任何回答 ——
             // 既不是释放证据,也不是「读不出来」的新证据,上一发**完成了的**读数保持在座(#244 F1
             // 换装批 G-c 尾竞态定谳:R2 [medium] 的「只记最近一次」指最近一次**有回答**的探测 ——
@@ -371,6 +423,7 @@ export async function waitForClaimRelease(taskId, deps) {
             // 这一发**有回答但读不出**(404/传输错)⇒ 最新证据是「不知道」,陈旧的成功读数当场作废
             // (见 lastStatus 头注)。
             lastStatus = null;
+            lastHolder = 'unknown';
             // 🔴 **404 也只是「读不到」,不是「释放了」**(二次评审 [high] 处置,2026-08-14):这个读口的
             // 404 在 SDK 契约上是 `not_found.run` —— 「这条 run 不存在」与「它不是你的」**共用同一个码,
             // 且是刻意设计的不可分辨**(跨租户不给存在性预言机)。凭它断言「那条 run 已经不占着会话」,
@@ -381,10 +434,22 @@ export async function waitForClaimRelease(taskId, deps) {
         }
         lease.release(); // 🔴 定时器必清:这只是**普通**定时器(见 claimProbeLease),不清就把进程多拖活一拍
         lastStatus = status; // 奇形记录(读不出 status)同样把陈旧读数清掉 —— 最新证据仍是「不知道」
+        lastHolder = holder;
+        // ── 🔴 0.68.0 / L-230(server 7.73.0 S-122 P-45 读面消费)—— **两条释放证据,取并** ────────
+        // ① `heldBy === null` —— 引擎**直说**会话交出来了。这是本批新接的那条,而且它比 ② 强:
+        //    ② 是拿「run 走到了某个终态词」去**推断**锁没了,而锁与 run 的生命周期不是同一件事
+        //    (park 态保留 claim 正是这条推断会踩的坑,也是 `CLAIM_RELEASED_STATES` 是白名单而不是
+        //    「running 之外的一切」的原因)。有直接证据就别再推断。
+        // ② `status ∈ CLAIM_RELEASED_STATES` —— 老引擎不发 `heldBy`(读出 `'unknown'`)时的**既有路**,
+        //    一字未动。⇒ 本件对老引擎**零行为变化**;对新引擎多了一条更早、更硬的收口证据。
+        // 🔴 `'unknown'` 绝不当成释放:缺席不是证据(与本文件 404 那一格逐字同一条纪律)。
+        if (holder === 'released') {
+            return { released: true, waitedMs: waited(), aborted: false, lastStatus: status, lastHolder: holder };
+        }
         // status 读不出(奇形记录)/ 还在跑 / park / 没想过的新词 ⇒ 都不算释放,继续等到点(保守方向:
         // 宁可不重发)。判据见 {@link CLAIM_RELEASED_STATES}。
         if (status !== null && CLAIM_RELEASED_STATES.includes(status)) {
-            return { released: true, waitedMs: waited(), aborted: false, lastStatus: status };
+            return { released: true, waitedMs: waited(), aborted: false, lastStatus: status, lastHolder: holder };
         }
     }
 }
@@ -800,7 +865,13 @@ async function cancelAndConfirmRelease(taskId, durable, durableGet, deps) {
         outcome: 'timeout',
         waitedMs: verdict.waitedMs,
         aborted: verdict.aborted,
-        confirmedHeld: verdict.lastStatus !== null && CLAIM_HELD_STATES.includes(verdict.lastStatus),
+        // 🔴 0.68.0 / L-230:**两条持锁证据取并**,直接证据优先 ——
+        //    ① `heldBy` 读出 `'held'` = 引擎**直说**那条 run 还占着(server 7.73.0 S-122 P-45 读面);
+        //    ② 老引擎不发那一位(`'unknown'`)⇒ 回落既有的按状态词推断({@link CLAIM_HELD_STATES})。
+        //    🔴 `'released'` 在这里到不了(released 的判决在上面就 return 了),`'unknown'` 不算证据 ——
+        //    两条都答不出时仍然收口成 `false` = 「确认不了」,文案绝不说「它还占着」。
+        confirmedHeld: verdict.lastHolder === 'held' ||
+            (verdict.lastStatus !== null && CLAIM_HELD_STATES.includes(verdict.lastStatus)),
     };
 }
 /**

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

@@ -235,7 +235,24 @@ export interface WiringManifestMcpEntry {
  * CS-7 §2.7 — turn_end usage → CC `ModelUsage` (pinned name mapping;
  * costMicroUsd/1e6 → costUSD). Surfaced separately because the slice has no
  * standalone usage SDKMessage arm; the run driver folds it into the footer /
- * terminal rollup. Returns `undefined` when the optional `usage` is absent.
+ * terminal rollup.
+ *
+ * ── 🔴 0.68.0 BREAKING(core 7.17.0 #711;异源对抗复审轮三实抓的**第五处**)──────────────────
+ * 返回 `undefined` 的含义从「`usage` 这一格缺席」收窄成 **「这一轮的账不知道」**,两种入形都答它:
+ *   ① `ev.usage` 整个缺席 —— #711 之后这**不再是一条合法形**(契约违约;`runStream` 那一层另有
+ *      响亮留痕,本读器只如实答「不知道」);
+ *   ② `usageMissing: true` **且六格全是 0** —— 那正是 core 的**占位**
+ *      (`rs.turn.turnUsage ?? {六个 0}`,`run-harness-handlers.js:289-293`)。
+ * 🔴 为什么必须改:#711 之前,「这一轮没量出账」这件事在 wire 上的形是**不发 usage** ⇒ 本函数答
+ *    `undefined`;#711 之后同一件事的形变成六个 0,而本函数是**公面导出** —— 不改的话,同一个真实
+ *    情形在引擎升级前后由同一个公开读器给出两个相反的答案(「不知道」变成「这一轮恰好花了 0」),
+ *    而调用方**一个字都没改**。收窄之后跨引擎升级的答案**逐字不变**。
+ * 🔴 **非零照交**:`usageMissing` 并不保证六格是零(core 在同一轮里可能已攒到真数字而另一次调用
+ *    报了缺账 ⇒ 判别位与真数字同帧并存)。占位恒为全零,所以**任何一格非零**都说明这一轮真的量到过
+ *    ⇒ 照交镜像(那些数字是**下界**,而「是不是下界」由帧上的 `usageMissing` / 终帧的
+ *    `_sema_usage_lower_bound` 回答,不由本函数回答)。
+ * ⚠️ 要**原样**的 wire 镜像(不做任何判断)请直接调 {@link turnUsageToModelUsage} —— 那一只是
+ *    纯映射,本函数是**带缺席语义的读器**,两者刻意分开。
  */
 export declare function turnEndUsage(ev: Extract<AgentEvent, {
     type: 'turn_end';

package/dist/adapter/downstream/eventToSdkMessage.js

@@ -877,8 +877,14 @@ export function eventToSdkMessage(ev, ctx) {
  *
  * ── 这是什么 ────────────────────────────────────────────────────────────────────────────────
  * 「assistant 的这一段散文写完了」—— 模型关掉了那个 text content block,而它的字节刚刚以
- * `text_delta` 流过。core 的臂注逐字:`content` = **该段的权威全文**(与那一段 delta 的拼接逐字节
- * 相等,取自 brain 自己的累加),消费方**据它提交这一段**,而不是信自己的 delta 缝合。
+ * `text_delta` 流过。core 的臂注逐字:`content` = **该段的权威全文**(取自 brain 自己的累加),
+ * 消费方**据它提交这一段**,而不是信自己的 delta 缝合。
+ *
+ * 🔴 **「与 delta 拼接逐字节相等」这句自 server 7.75.3 起不再成立**(L-310,0.68.1 订正;此前本注
+ *    照抄 core 臂注的那半句):`text_end.content` 与 `result`/账本走**同一只脱敏器**,而 `text_delta`
+ *    仍逐字(跨 chunk 的凭据无法就地判,流式脱敏是独立设计件)⇒ 含凭据形的段上两者**字节不同**。
+ *    server `ASSISTANT-WIRE-CONTRACT` §5.1 live 面逐字要求消费端「在 `text_end` 到达时以它**整段
+ *    替换**已攒的 delta,而不是只当段界信号」。
  *
  * 🔴 **它的存在意义 = 让消费方撤掉 idle-flush 启发式**(core 臂注点名的那件事)。本包的
  * `adapt/textStream.ts` 至今用「静默 1.5s + 句末/段末边界 + 每段一刀」猜段边界(#323 症状① 的止血
@@ -893,11 +899,15 @@ export function eventToSdkMessage(ev, ctx) {
  *    信号(段边界 + 权威全文),静默丢 = 把一个真实能力缺口做成 fail-open,正是本文件对
  *    `approval_request` 那段头注点名的病形。⇒ 投中性内部臂,宿主(壳 REPL 桥 / web / desktop 座位层)
  *    在臂上读它、决定何时提交段。
- *  · 📋 **本包内的接线如实留白**(不在本批做):要让 `adapt/textStream.ts` 真的**撤掉** idle-flush,
- *    得先答一个行为面问题 —— core 臂注明写这是「诚实缺席」的位(只有会报块结束的 brain 才发它,
- *    自定义 brain 可能整条流一帧都没有),所以消费方必须按**每条流**判「这条流带不带边界帧」再决定
- *    退不退启发式。那是一条带状态的策略,属行为面改动,按宪法三问单独走,不在本提货批里顺手加。
- *    本批只把信号送到宿主手上(壳侧接线是下一棒),缺口写在这里,不留白。
+ *  · **包内接线**(0.68.1 / L-310 起):`adapt/arms.ts` 的 `textSegmentEndArm` 拿这条内部臂调
+ *    `adapt/textStream.ts` 的 `replaceAnswerSegment(content, frame)` —— **整段替换**段缓冲与活体尾巴,
+ *    再把 `diverged` / `committedPrefixDiverged` / `committedPrefixLen` 三个 never-false 键挂到
+ *    chrome `text_segment_end` 上交给宿主。
+ *  · 📋 **仍然留白的那一件**:让 `textStream` 真的**撤掉** idle-flush 启发式。core 臂注明写这是
+ *    「诚实缺席」的位(只有会报块结束的 brain 才发它,自定义 brain 可能整条流一帧都没有),所以
+ *    消费方必须按**每条流**判「这条流带不带边界帧」再决定退不退启发式 —— 那是一条带状态的策略,
+ *    属行为面改动,按宪法三问单独走。权威替换**兼容**启发式(半段已被 flush 那一形由两个前缀键
+ *    如实交代),不是它的继任。
  *
  * ── 畸形与空段(fail-closed 方向 + 对位 core 的「空段无帧」)────────────────────────────────
  *  · `content` **非串** ⇒ `malformed`:承重位读不动(wire 是 JSON,SDK 只 JSON.parse 不校型)。
@@ -1198,10 +1208,41 @@ function humanInputProjection(ev, ctx) {
  * CS-7 §2.7 — turn_end usage → CC `ModelUsage` (pinned name mapping;
  * costMicroUsd/1e6 → costUSD). Surfaced separately because the slice has no
  * standalone usage SDKMessage arm; the run driver folds it into the footer /
- * terminal rollup. Returns `undefined` when the optional `usage` is absent.
+ * terminal rollup.
+ *
+ * ── 🔴 0.68.0 BREAKING(core 7.17.0 #711;异源对抗复审轮三实抓的**第五处**)──────────────────
+ * 返回 `undefined` 的含义从「`usage` 这一格缺席」收窄成 **「这一轮的账不知道」**,两种入形都答它:
+ *   ① `ev.usage` 整个缺席 —— #711 之后这**不再是一条合法形**(契约违约;`runStream` 那一层另有
+ *      响亮留痕,本读器只如实答「不知道」);
+ *   ② `usageMissing: true` **且六格全是 0** —— 那正是 core 的**占位**
+ *      (`rs.turn.turnUsage ?? {六个 0}`,`run-harness-handlers.js:289-293`)。
+ * 🔴 为什么必须改:#711 之前,「这一轮没量出账」这件事在 wire 上的形是**不发 usage** ⇒ 本函数答
+ *    `undefined`;#711 之后同一件事的形变成六个 0,而本函数是**公面导出** —— 不改的话,同一个真实
+ *    情形在引擎升级前后由同一个公开读器给出两个相反的答案(「不知道」变成「这一轮恰好花了 0」),
+ *    而调用方**一个字都没改**。收窄之后跨引擎升级的答案**逐字不变**。
+ * 🔴 **非零照交**:`usageMissing` 并不保证六格是零(core 在同一轮里可能已攒到真数字而另一次调用
+ *    报了缺账 ⇒ 判别位与真数字同帧并存)。占位恒为全零,所以**任何一格非零**都说明这一轮真的量到过
+ *    ⇒ 照交镜像(那些数字是**下界**,而「是不是下界」由帧上的 `usageMissing` / 终帧的
+ *    `_sema_usage_lower_bound` 回答,不由本函数回答)。
+ * ⚠️ 要**原样**的 wire 镜像(不做任何判断)请直接调 {@link turnUsageToModelUsage} —— 那一只是
+ *    纯映射,本函数是**带缺席语义的读器**,两者刻意分开。
  */
 export function turnEndUsage(ev) {
-    return ev.usage ? turnUsageToModelUsage(ev.usage) : undefined;
+    // 🔴 **成形判据不是 `!raw`**(异源复审轮四同族):wire 是 JSON、SSE 解析原样透传 ⇒ `usage: null` /
+    //    `usage: 7` 这类形真到得了这里。`null` 会让映射在读字段时抛;标量更坏 —— 它会被映射成一份
+    //    **看起来已测量**的全零账(`toCcModelUsage(7)` 逐格读不出、逐格折 0)。坏形与缺席同义:
+    //    **这一轮的账不知道**。
+    const rawValue = ev.usage;
+    if (typeof rawValue !== 'object' || rawValue === null || Array.isArray(rawValue))
+        return undefined;
+    const raw = rawValue;
+    const unknown = ev.usageMissing === true;
+    // 占位判据 = **六格全零**(不是「有 usageMissing 就算占位」)。逐格按值判,非有限值当 0 看待
+    // (那一格本来就读不出,它不构成「量到过」的证据)。
+    const placeholder = unknown &&
+        [raw.inputTokens, raw.totalInputTokens, raw.outputTokens, raw.cacheReadTokens, raw.cacheWriteTokens, raw.costMicroUsd]
+            .every((v) => !(typeof v === 'number' && Number.isFinite(v) && v !== 0));
+    return placeholder ? undefined : turnUsageToModelUsage(raw);
 }
 /**
  * Defensive open-set read of a `suspended` gate kind for the run driver's HITL

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

@@ -304,6 +304,35 @@ export interface MutableSubagentUsageRow {
      */
     keyFromParentFallback?: true;
 }
+/**
+ * 子代用量面的**下界判别位键名**(`_sema_subagent_usage_partial`)。
+ *
+ * 🔴 它与终帧的 `_sema_usage_lower_bound` **刻意不同名**(见上段):两者答的是两个问题,
+ *    一个消费面同时拿到两者时必须分得出来。
+ * 🔴 本包**不在任何 wire 帧上铸它** —— 它是**渲染面**的位(端把一行子代用量交给自己的视图时用)。
+ *    包给名与判据,是为了三端零自拼(同 `gateIdentity` 的三条身份键字面同一条纪律)。
+ */
+export declare 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 declare function subagentUsageIsPartial(row: {
+    readonly usageMissing?: unknown;
+    readonly keyCollision?: unknown;
+} | null | undefined, opts?: {
+    readonly tablePartial?: boolean;
+}): boolean;
 /** 终帧两个超集键的产物形(见 {@link nestedUsageByTaskParts})。 */
 export interface SemaNestedUsageByTask {
     readonly rows: Readonly<Record<string, SemaSubagentUsageRow>>;

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;
@@ -319,6 +309,47 @@ function costFactParts(stats, observed) {
         //    (本位在上面与流内观测取并后已铸;这里不再重复。)
     };
 }
+// ══ 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 点**(成功臂与错误信封共用)。
  *

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>;