@sema-agent/client-core 0.61.0 → 0.62.0

package/dist/sqlEngineCapability.js

@@ -38,10 +38,10 @@
  *
  * ── 🔴 UNTRUSTED-for-display ──────────────────────────────────────────────────────────────
  * `isolation` 是从**数据库服务器**变量里回读的串(`@@transaction_isolation` 一族),不是引擎铸的
- * 闭词;三座一律只渲染、绝不参与任何判定,呈现前过本包的单行消毒单源
- * ({@link escapeDisplayControlChars})。
+ * 闭词;三座一律只渲染、绝不参与任何判定,呈现前过本包的单行消毒 + 封长单源
+ * ({@link capForDisplay}:先转义、后按转义结果封长)。
  */
-import { escapeDisplayControlChars } from './fleetTaskDesc.js';
+import { capForDisplay } from './fleetTaskDesc.js';
 import { engineWireTarget } from './engineWireTarget.js';
 import { engineCapsGeneration } from './engineCapsCache.js';
 /**
@@ -131,21 +131,20 @@ export function observedSqlEngine(baseUrl = engineWireTarget()?.baseUrl) {
 /** 单行 UNTRUSTED 座的展示上限(UTF-16 单元;与壳侧那份同值)。 */
 const SQL_DETAIL_MAX = 40;
 /**
- * 单行 UNTRUSTED 座的呈前规整:**先按 {@link SQL_DETAIL_MAX} 截原字节,再过单行消毒**。
+ * 单行 UNTRUSTED 座的呈前规整:**先转义、后按转义结果封长**({@link capForDisplay})。
  *
- * 🔴 顺序刻意与壳那份相反,理由是两侧消毒器的**输出形不同**:壳那份用 `.` 占位(1:1,先截后清
- *    与先清后截等价),本包的单源 {@link escapeDisplayControlChars} 用**可见转义** `\uXXXX`
- *    (1:6)—— 先清后截会把一个转义序列拦腰截断,屏上留下 `\u20` 这种既不是字符也不是转义的残片。
- *    先截后清则至多让**渲染宽度**超出上限,而语义完整;截点劈开的代理对由消毒器自己收
- *    (孤代理项在它的字符集里)。
+ * 🔴 0.62.0 改了顺序,理由记全(此前这里刻意写的是先截后转义):旧注释担心的是「先清后截会把一个
+ *    转义序列拦腰截断,屏上留下 `\u20` 这种既不是字符也不是转义的残片」—— 那个顾虑是对的,但它的
+ *    解法不是把顺序反过来,而是**截点避让**:共用铸点在截点落进一枚 `\uXXXX` 中间时回退到该 token
+ *    之前(合法代理对同理回退一位)。两个毛病只能同时消掉一次:先截后转义留下的是**预算失守**
+ *    (纯控制字符的 40 字符原文转义后占 240 个显示字符,是承诺列宽的六倍),那是比残片更硬的一条。
  * ⚠️ **与壳那份的已知呈现差分**(换装时随批裁一次):壳 `sqlEngineDoctorDetail` 走的是
- *    `cleanUntrustedForDisplay`(`.` 占位形),而壳自己的 `untrustedDisplayText` 头注写着
- *    「单行字段(路径/URL/参数键值)**必须**用 cleanUntrustedScalar」(可见转义形)——
- *    三座正是单行标量。本包按那条规则实现,所以对**正常读数**(`tidb` / `REPEATABLE-READ` /
- *    `pessimistic`)两侧逐字节相同,只有含控制符的病态值渲染形不同。
+ *    `.` 占位形消毒器(1:1,先截后清与先清后截等价),而壳自己的头注写着「单行字段(路径/URL/
+ *    参数键值)**必须**用可见转义形」—— 三座正是单行标量。本包按那条规则实现,所以对**正常读数**
+ *    (`tidb` / `REPEATABLE-READ` / `pessimistic`)两侧逐字节相同,只有含控制符的病态值渲染形不同。
  */
 function cleanSqlDetailScalar(v) {
-    return escapeDisplayControlChars(v.slice(0, SQL_DETAIL_MAX));
+    return capForDisplay(v, SQL_DETAIL_MAX);
 }
 /**
  * 四态 → doctor 那一行的 detail 串。**唯一措辞真源**(三端共用一句话;别在各端的行装配里另写

package/dist/subagentContentStore.d.ts

@@ -10,6 +10,9 @@
  *
  * WIRE FACTS: with `forwardSubagentEvents: true` on the task request, the live stream carries the
  * subagent's text_delta / reasoning_delta / tool_start / tool_end stamped with EventIdentity
+ * —— 🔴 **durable 腿(重放)送的是同一段的聚合形** `text` / `reasoning`(整段全文,同样带
+ * EventIdentity)。两类都要收:只收增量的话,续听重放尾的宿主整条子代转录都是空的
+ * (0.62.0 补;两类的处置**不同**,见 {@link publishSubagentContentEvent} 的吸收规则)
  * (§E1 redact upstream; §E2 identity). 🔴 EventIdentity 的键是 `eventId` / `parentToolCallId`
  * (+ LIVE 白名单四臂上的 `sourceTaskId` / `bgAgentId`)—— **没有 `taskId`**(sdk `events.d.ts` 的
  * `interface EventIdentity` 直证;`taskId` 只长在 `meta` 首帧上)。所以内容帧到不了「自带引擎
@@ -46,6 +49,19 @@ export type SubagentContentItem = {
  | {
     kind: 'echo';
     text: string;
+}
+/**
+ * **截尾留痕**(0.62.0):字节预算把这条子代早先的内容丢掉了多少。恒**排在 items 最前**、
+ * 每条子代**至多一条**(丢一次加一条会把账本自己撑爆),随后续丢弃**原地更新**。
+ *
+ * 🔴 它存在的唯一理由是「不许无声消失」:没有它,用户读到的转录比真实发生的少一截而毫无提示,
+ *    而那正是本包在别处反复记账的那类静默失败。渲染端该把它渲成一行可见的省略说明。
+ * 🔴 本记录**自身不计入预算**(它是关于预算的元信息,不是内容)。
+ */
+ | {
+    kind: 'truncated';
+    droppedBytes: number;
+    keptFrom: number;
 };
 /**
  * 🔴 [2393] sweep-F15(2026-08-03 全窗复审)**记一笔口径分叉**(裁定:留 `| undefined`,写明为什么):
@@ -61,10 +77,22 @@ export type SubagentContentItem = {
  * (那时两种口径就不能再共存了)。
  */
 export interface SubagentContentEvent {
-    type: 'text_delta' | 'reasoning_delta' | 'tool_start' | 'tool_end';
+    /**
+     * 🔴 六臂,两类语义(0.62.0 加 `text` / `reasoning` 两个**聚合**臂):
+     *   · `*_delta` = **增量**,语义是「往缓冲里追加」;
+     *   · `text` / `reasoning` = 一段的**权威全文**(durable 重放腿送的就是这一形),语义是
+     *     「这一段最终是这样」—— 处置**不是追加**,见 {@link publishSubagentContentEvent} 的吸收规则。
+     * 两类必须分得开:把聚合帧折成一发 `*_delta` 会让「活体流过 + 重放聚合」变成**双份**。
+     */
+    type: 'text_delta' | 'reasoning_delta' | 'text' | 'reasoning' | 'tool_start' | 'tool_end';
     taskId: string;
     parentToolCallId: string;
     delta?: string | undefined;
+    /** 聚合两臂(`text` / `reasoning`)的**整段全文**。刻意不复用 `delta` 位:同名不同义会让
+     *  「这一位是增量还是全文」变成读者要靠 `type` 去反推的事,而反推错的代价是内容重复上屏。 */
+    text?: string | undefined;
+    /** wire 上那一帧的**事件身份**(聚合两臂的幂等键;缺席 ⇒ 退回内容判据,见 publish 的两道闸)。 */
+    eventId?: string | undefined;
     toolCallId?: string | undefined;
     toolName?: string | undefined;
     args?: unknown;
@@ -104,6 +132,38 @@ export interface SubagentContentEvent {
  *   动本函数的块数组分支 ⇒ 同批看那条断言。
  */
 export declare function coerceOutput(v: unknown): string | undefined;
+/**
+ * 本账本的**字节预算**。此前只有条数帽(每条子代 ≤ 200 条 item、≤ 32 条子代),而条数帽对
+ * 「一条工具结果里的一整个 base64 附件」「一段几 MB 的模型输出」**零判别力** —— 200 条的上限在
+ * **单条无上限**的前提下根本不是一个预算,实测面上一个子代槽位吃到十几 MB 常驻是可复现的。
+ *
+ * 🔴 单位是 **UTF-8 字节**(不是 JS 串长度):账本里装的是引擎送来的文本,而「多少内存 / 多少屏」
+ *    这两件事都跟编码后的体量走;按串长度算会让一段 CJK 的真实占用是名义值的三倍。
+ * 🔴 缺省值的来历(如实):对标产品的语料里**没有**对应的「子代转录字节预算」可对齐(查过),
+ *    所以这两个数不假称是 parity —— 它们来自 web 端探针实测的「单槽十几 MB」这一观测:总帽取
+ *    16 MiB(把整本账本按住在那个量级),每子代帽取总帽的 1/8 = 2 MiB(一条子代吃满也留得下
+ *    另外七条的位置)。端可以按自己的宿主改配,这两个数只是「不配时不至于无界」。
+ */
+export interface SubagentContentStoreConfig {
+    /** 单条子代**保留**的内容字节上限。超出 ⇒ 从最早的内容开始丢,并留一条 `truncated` 记录。 */
+    maxBytesPerTask: number;
+    /** 整本账本保留的内容字节上限。超出 ⇒ 整条**最久未用**的子代账本被清掉(不是无差别清空)。 */
+    maxBytesTotal: number;
+}
+/** 不配时生效的两位(理由见 {@link SubagentContentStoreConfig} 顶注)。 */
+export declare const SUBAGENT_CONTENT_STORE_DEFAULTS: Readonly<SubagentContentStoreConfig>;
+/**
+ * 配字节预算(宿主启动时调一次;两位可分开配,只给一位时另一位保持现值)。
+ *
+ * 🔴 **fail-loud**:0 / 负数 / 非有限数 / 非整数一律 `throw` —— 一个被**静默忽略**的预算配置正是
+ *    这本账本要消灭的那类失败(宿主以为配上了,而账本还在按缺省无声地丢或不丢)。
+ * 🔴 拒绝是**原子**的:任何一位不合法就整只拒,既有配置一个字节不动(半套配置比不配更坏)。
+ */
+export declare function configureSubagentContentStore(next: Partial<SubagentContentStoreConfig>): void;
+/** 当前生效的两位(**快照**:改返回值不影响账本)。 */
+export declare function subagentContentStoreConfig(): SubagentContentStoreConfig;
+/** 测试钩:把预算复位到缺省。 */
+export declare function __resetSubagentContentStoreConfigForTests(): void;
 /**
  * **内容归账那一半**(`parentToolCallId → taskId`,多对一):把停在 parent 键下的内容迁到 canonical
  * task 键,并让后续内容帧的 `canonicalKey` 解析到 task。**不写** `taskToParent`。
@@ -157,6 +217,13 @@ export type SubagentViewSlot = {
     kind: 'echo';
     slot: string;
     text: string;
+}
+/** 截尾留痕(0.62.0):渲染端渲一行「更早的 N 字节输出已被预算丢弃」类说明。 */
+ | {
+    kind: 'truncated';
+    slot: string;
+    droppedBytes: number;
+    keptFrom: number;
 } | {
     kind: 'tool';
     slot: string;

package/dist/subagentContentStore.js

@@ -10,6 +10,9 @@
  *
  * WIRE FACTS: with `forwardSubagentEvents: true` on the task request, the live stream carries the
  * subagent's text_delta / reasoning_delta / tool_start / tool_end stamped with EventIdentity
+ * —— 🔴 **durable 腿(重放)送的是同一段的聚合形** `text` / `reasoning`(整段全文,同样带
+ * EventIdentity)。两类都要收:只收增量的话,续听重放尾的宿主整条子代转录都是空的
+ * (0.62.0 补;两类的处置**不同**,见 {@link publishSubagentContentEvent} 的吸收规则)
  * (§E1 redact upstream; §E2 identity). 🔴 EventIdentity 的键是 `eventId` / `parentToolCallId`
  * (+ LIVE 白名单四臂上的 `sourceTaskId` / `bgAgentId`)—— **没有 `taskId`**(sdk `events.d.ts` 的
  * `interface EventIdentity` 直证;`taskId` 只长在 `meta` 首帧上)。所以内容帧到不了「自带引擎
@@ -89,7 +92,241 @@ export function coerceOutput(v) {
 const MAX_ITEMS_PER_TASK = 200;
 const MAX_TASKS = 32;
 const NOTIFY_COALESCE_MS = 250;
+/** 不配时生效的两位(理由见 {@link SubagentContentStoreConfig} 顶注)。 */
+export const SUBAGENT_CONTENT_STORE_DEFAULTS = Object.freeze({
+    maxBytesPerTask: 2 * 1024 * 1024,
+    maxBytesTotal: 16 * 1024 * 1024,
+});
+let storeConfig = { ...SUBAGENT_CONTENT_STORE_DEFAULTS };
+/**
+ * 配字节预算(宿主启动时调一次;两位可分开配,只给一位时另一位保持现值)。
+ *
+ * 🔴 **fail-loud**:0 / 负数 / 非有限数 / 非整数一律 `throw` —— 一个被**静默忽略**的预算配置正是
+ *    这本账本要消灭的那类失败(宿主以为配上了,而账本还在按缺省无声地丢或不丢)。
+ * 🔴 拒绝是**原子**的:任何一位不合法就整只拒,既有配置一个字节不动(半套配置比不配更坏)。
+ */
+export function configureSubagentContentStore(next) {
+    const check = (name, v) => {
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0) {
+            throw new TypeError(`configureSubagentContentStore: \`${name}\` must be a positive integer number of bytes (got ${String(v)})`);
+        }
+        return v;
+    };
+    const perTask = check('maxBytesPerTask', next.maxBytesPerTask);
+    const total = check('maxBytesTotal', next.maxBytesTotal);
+    // 🔴 两位的**关系**也要验(车内异源复审逼出:两位各自合法、合起来自相矛盾)。每子代帽大于总帽时,
+    //    单条子代可以合法地涨到每子代帽 —— 而总帽淘汰**不动当期那条**(它正在写),于是那一条就整只
+    //    越过了总帽,总帽从此形同虚设。判的是**落值之后**的那一对,不是这次传进来的那一位:只配一位
+    //    时另一位保持现值,矛盾同样可能是这次配出来的。
+    const nextPerTask = perTask ?? storeConfig.maxBytesPerTask;
+    const nextTotal = total ?? storeConfig.maxBytesTotal;
+    if (nextPerTask > nextTotal) {
+        throw new RangeError(`configureSubagentContentStore: \`maxBytesPerTask\` (${String(nextPerTask)}) must not exceed ` +
+            `\`maxBytesTotal\` (${String(nextTotal)}) — a per-task budget above the total is unreachable by ` +
+            'construction, and the total stops bounding anything.');
+    }
+    // 两位都验完才落 —— 第二位不合法时第一位也不许生效。
+    storeConfig.maxBytesPerTask = nextPerTask;
+    storeConfig.maxBytesTotal = nextTotal;
+}
+/** 当前生效的两位(**快照**:改返回值不影响账本)。 */
+export function subagentContentStoreConfig() {
+    return { ...storeConfig };
+}
+/** 测试钩:把预算复位到缺省。 */
+export function __resetSubagentContentStoreConfigForTests() {
+    storeConfig = { ...SUBAGENT_CONTENT_STORE_DEFAULTS };
+}
 const tasks = new Map();
+/** 整本账本当下保留的内容字节(逐次增删维护;总帽读它)。 */
+let totalBytes = 0;
+/**
+ * 一段文本的 **UTF-8 字节数**,不做编码分配。
+ *
+ * 🔴 为什么不用 `TextEncoder`:它每次都要**分配**一个字节数组,而这条路是逐 token 的热路径
+ *    (实测 ~23 帧/s 的增量流)。算术形零分配、结果逐字节相同。
+ * 🔴 为什么不按 `str.length`(UTF-16 单元)算:账本里装的是引擎送来的文本,一段 CJK 的真实占用
+ *    是串长度的三倍 —— 按串长度算等于把预算对中文内容放宽两倍。
+ */
+function utf8Len(str) {
+    let n = 0;
+    for (let i = 0; i < str.length; i++) {
+        const c = str.charCodeAt(i);
+        if (c < 0x80)
+            n += 1;
+        else if (c < 0x800)
+            n += 2;
+        else if (c >= 0xd800 && c <= 0xdbff && i + 1 < str.length) {
+            // 合法代理对 = 一个 4 字节码位(高位后面不是低位时按 3 字节的孤代理项算,与编码器同)
+            const next = str.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                n += 4;
+                i++;
+            }
+            else
+                n += 3;
+        }
+        else
+            n += 3;
+    }
+    return n;
+}
+/**
+ * 把 `chunk` 追加到 `prev` 之后,**字节账真正增加了多少**。
+ *
+ * 🔴 不能直接用 `utf8Len(chunk)`(车内异源复审逼出的真病):一对代理对被上游拆成**两帧**送来时,
+ *    前一帧尾部那枚高位代理项按孤代理项算 3 字节、后一帧首部那枚低位代理项也算 3 字节,合计 6;
+ *    而拼起来之后它是一个 4 字节码位。每拆一次就虚高 2 字节,而段闭合时是按**拼接后的串**扣账
+ *    —— 加 6 扣 4,差额永久留在账上。长流里这个漂移会一路把总账推高,最后把还在用的账本淘汰掉。
+ * ⇒ 只在**拼接边界**上修正一次(O(1)),不重扫整条缓冲(缓冲能有 MB 级,而这是逐 token 的热路径)。
+ */
+function appendBytes(prev, chunk) {
+    const add = utf8Len(chunk);
+    if (prev.length === 0 || chunk.length === 0)
+        return add;
+    const lastPrev = prev.charCodeAt(prev.length - 1);
+    const firstNew = chunk.charCodeAt(0);
+    const joinsPair = lastPrev >= 0xd800 && lastPrev <= 0xdbff && firstNew >= 0xdc00 && firstNew <= 0xdfff;
+    return joinsPair ? add - 2 : add;
+}
+/** 一条 item 的字节账(`truncated` 是关于预算的元信息,自身不计)。 */
+function itemBytesOf(it) {
+    switch (it.kind) {
+        case 'text':
+        case 'thinking':
+        case 'echo':
+            return utf8Len(it.text);
+        case 'tool': {
+            let n = utf8Len(it.name) + utf8Len(it.output ?? '');
+            // 工具参数是**开集** `unknown`:序列化一次算体量(每张卡只算一次,不在增量热路径上)。
+            try {
+                if (it.input !== undefined)
+                    n += utf8Len(JSON.stringify(it.input) ?? '');
+            }
+            catch {
+                // 循环引用/不可序列化 ⇒ 这一位按 0 计(它进不了展示面,也就占不了这本账的预算)
+            }
+            return n;
+        }
+        case 'truncated':
+            return 0;
+    }
+}
+/** 从串**头部**裁掉至少 `want` 字节;返回剩下的尾巴与真正裁掉的字节数(不劈开合法代理对)。 */
+function trimHeadBytes(str, want) {
+    let removed = 0;
+    let i = 0;
+    while (i < str.length && removed < want) {
+        const c = str.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff && i + 1 < str.length) {
+            const next = str.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                removed += 4;
+                i += 2;
+                continue;
+            }
+        }
+        removed += c < 0x80 ? 1 : c < 0x800 ? 2 : 3;
+        i += 1;
+    }
+    return { rest: str.slice(i), removed };
+}
+/** 字节账的唯一增减口(两本账同拍走,永不分叉)。 */
+function addBytes(s, n) {
+    s.bytes += n;
+    totalBytes += n;
+}
+/** 记一次丢弃:更新/建立留痕记录(每条子代恒一条,恒排在最前)。 */
+function noteDropped(s, dropped) {
+    if (dropped <= 0)
+        return;
+    s.droppedBytes += dropped;
+    const head = s.items[0];
+    if (head?.kind === 'truncated') {
+        head.droppedBytes = s.droppedBytes;
+        head.keptFrom = s.droppedBytes;
+        return;
+    }
+    s.items.unshift({ kind: 'truncated', droppedBytes: s.droppedBytes, keptFrom: s.droppedBytes });
+    s.itemBytes.unshift(0);
+    rebuildOpenTools(s);
+}
+/** items 被增删之后重建「开着的工具卡 → 下标」表(下标随 splice/unshift 整体漂移)。 */
+function rebuildOpenTools(s) {
+    s.openTools.clear();
+    s.items.forEach((it, i) => {
+        if (it.kind === 'tool' && it.output === undefined)
+            s.openTools.set(it.id, i);
+    });
+}
+/**
+ * 每子代帽:超出就**从最早的内容开始丢**,丢不动了再从缓冲头部裁。
+ *
+ * 🔴 顺序是「先 item 后缓冲」而不是反过来:缓冲是**活体尾巴**(用户正在看的那一段),item 是更早
+ *    的历史。反过来做会把用户眼前正在流的字丢掉,而屏上更早那一段完好无损 —— 那是错的一头。
+ * 🔴 留痕记录自身不参与丢弃(它是关于预算的元信息;丢掉它等于把「有东西被丢了」这件事也丢了)。
+ */
+function enforceTaskCap(s) {
+    const cap = storeConfig.maxBytesPerTask;
+    if (s.bytes <= cap)
+        return false;
+    let dropped = 0;
+    const first = () => (s.items[0]?.kind === 'truncated' ? 1 : 0);
+    while (s.bytes > cap && s.items.length > first()) {
+        const idx = first();
+        const b = s.itemBytes[idx] ?? 0;
+        s.items.splice(idx, 1);
+        s.itemBytes.splice(idx, 1);
+        addBytes(s, -b);
+        dropped += b;
+    }
+    if (s.bytes > cap) {
+        const cut = trimHeadBytes(s.thinkBuf, s.bytes - cap);
+        s.thinkBuf = cut.rest;
+        addBytes(s, -cut.removed);
+        dropped += cut.removed;
+    }
+    if (s.bytes > cap) {
+        const cut = trimHeadBytes(s.textBuf, s.bytes - cap);
+        s.textBuf = cut.rest;
+        addBytes(s, -cut.removed);
+        dropped += cut.removed;
+    }
+    if (dropped > 0) {
+        rebuildOpenTools(s);
+        noteDropped(s, dropped);
+        return true;
+    }
+    return false;
+}
+/**
+ * 总帽:整条**最久未用**的子代账本被清掉(`tasks` 的迭代序就是 LRU 序,活跃项每次访问都会重插)。
+ * 🔴 刻意不动**当期**那条(它正在写),也刻意不做「每条各裁一点」——半截的转录比一条整齐的缺席更难读。
+ */
+function enforceTotalCap(currentKey) {
+    while (totalBytes > storeConfig.maxBytesTotal) {
+        let victim;
+        for (const k of tasks.keys()) {
+            if (k !== currentKey) {
+                victim = k;
+                break;
+            }
+        }
+        if (victim === undefined)
+            return; // 只剩当期那条:它已被每子代帽按住,这是能做到的最好结果
+        dropTask(victim);
+    }
+}
+/** 删一条子代账本并把它的字节从总账里扣掉(唯一删除口)。 */
+function dropTask(key) {
+    const s = tasks.get(key);
+    if (!s)
+        return;
+    totalBytes -= s.bytes;
+    tasks.delete(key);
+}
 // parentToolCallId ↔ engine taskId aliasing: CONTENT events carry ONLY {eventId, parentToolCallId}
 // (EventIdentity — no taskId on the wire), while the panel rows / 查看态 lookups key by the ENGINE task id
 // (task_progress carries BOTH). Content arriving before the first tick parks under the parent key and is
@@ -115,9 +352,20 @@ function stateFor(taskId, parentToolCallId) {
         if (tasks.size >= MAX_TASKS) {
             const oldest = tasks.keys().next().value;
             if (oldest !== undefined)
-                tasks.delete(oldest);
+                dropTask(oldest); // 条数淘汰同样要把字节从总账里扣掉
         }
-        s = { items: [], textBuf: '', thinkBuf: '', openTools: new Map(), parentToolCallId };
+        s = {
+            items: [],
+            itemBytes: [],
+            textBuf: '',
+            thinkBuf: '',
+            openTools: new Map(),
+            parentToolCallId,
+            bytes: 0,
+            droppedBytes: 0,
+            seenAggregateIds: new Set(),
+            recordedSegments: new Set(),
+        };
         tasks.set(taskId, s);
     }
     else {
@@ -126,25 +374,57 @@ function stateFor(taskId, parentToolCallId) {
     return s;
 }
 function pushItem(s, item) {
+    const b = itemBytesOf(item);
     s.items.push(item);
+    s.itemBytes.push(b);
+    addBytes(s, b);
     if (s.items.length > MAX_ITEMS_PER_TASK) {
-        s.items.splice(0, s.items.length - MAX_ITEMS_PER_TASK);
+        const cut = s.items.length - MAX_ITEMS_PER_TASK;
+        let freed = 0;
+        for (let i = 0; i < cut; i++)
+            freed += s.itemBytes[i] ?? 0;
+        s.items.splice(0, cut);
+        s.itemBytes.splice(0, cut);
+        addBytes(s, -freed);
+        // 条数帽丢掉的同样是**内容**,同样要留痕(此前这条路是无声的)。
+        noteDropped(s, freed);
         // open-tool indexes shifted — rebuild from the surviving items
-        s.openTools.clear();
-        s.items.forEach((it, i) => {
-            if (it.kind === 'tool' && it.output === undefined)
-                s.openTools.set(it.id, i);
-        });
+        rebuildOpenTools(s);
     }
 }
 /** Close out streaming buffers into items (segment boundary: a tool starts, or the run settles). */
 function flushBuffers(s) {
-    if (s.thinkBuf.trim())
-        pushItem(s, { kind: 'thinking', text: s.thinkBuf });
+    // 🔴 缓冲的字节此前已经计过账;搬进 item 时先扣掉缓冲那一份,再由 pushItem 计 item 那一份
+    //    (纯空白段被丢弃时同样要扣 —— 少扣一次,总账就会一路虚高到把别人的账本淘汰掉)。
+    addBytes(s, -utf8Len(s.thinkBuf));
+    const think = s.thinkBuf;
     s.thinkBuf = '';
-    if (s.textBuf.trim())
-        pushItem(s, { kind: 'text', text: s.textBuf });
+    if (think.trim()) {
+        pushItem(s, { kind: 'thinking', text: think });
+        rememberSegment(s, think);
+    }
+    addBytes(s, -utf8Len(s.textBuf));
+    const text = s.textBuf;
     s.textBuf = '';
+    if (text.trim()) {
+        pushItem(s, { kind: 'text', text });
+        rememberSegment(s, text);
+    }
+}
+/** 有界 FIFO 记号(两本小账共用;只用来做幂等判定,不参与预算)。 */
+const MAX_REPLAY_KEYS = 64;
+function remember(set, key) {
+    if (set.has(key))
+        return;
+    if (set.size >= MAX_REPLAY_KEYS) {
+        const oldest = set.values().next().value;
+        if (oldest !== undefined)
+            set.delete(oldest);
+    }
+    set.add(key);
+}
+function rememberSegment(s, text) {
+    remember(s.recordedSegments, text);
 }
 function scheduleNotify(taskId) {
     pendingNotify.add(taskId);
@@ -196,6 +476,9 @@ function aliasContentKey(parentToolCallId, taskId) {
         pendingNotify.add(taskId);
     const parked = tasks.get(parentToolCallId);
     if (parked && !tasks.has(taskId)) {
+        // 🔴 这是**换键**不是删除:同一本账换个键继续用,内容一个字节都没走 ⇒ 这里**不许**走
+        //    {@link dropTask}(那一口会把它的字节从总账里扣掉,而字节还在)。扣了之后总账会一路虚低,
+        //    总帽从此形同虚设。删除只有三个口:clearSubagentContent / 条数淘汰 / 总帽淘汰。
         tasks.delete(parentToolCallId);
         tasks.set(taskId, parked);
         scheduleNotify(taskId);
@@ -211,6 +494,51 @@ export function registerSubagentAlias(parentToolCallId, taskId) {
         return;
     taskToParent.set(taskId, parentToolCallId);
 }
+/**
+ * 这一条**聚合帧**是不是「已经收下过的那一条」(durable 重放的两道闸;命中 ⇒ 整帧丢弃)。
+ *
+ * 为什么光靠缓冲前缀吸收不够(车内异源复审逼出的真病):吸收规则只认**当前缓冲**那一段。一条
+ * 跨过工具边界的 turn,早先那些段早就段闭合成 item、缓冲已空 —— 重放时它们的聚合帧再来一遍,
+ * `''` 是任何串的前缀,于是整段被当成新内容塞回缓冲,而且塞在**后面那段**之后(顺序也是错的)。
+ *
+ * 两道闸,顺序刻意如此:
+ *   ① **事件身份**(`eventId`)—— 精确、无损:同一条账本帧重放多少次都只收一次。
+ *   ② **整段内容**(`recordedSegments`)—— 兜底:上游没给身份、或本进程这条流是重连后新起的
+ *      (身份没在这本账上留过),内容判据仍拦得住「这一段已经上过屏」。
+ * 📋 **如实留白**:闸 ② 的代价是——一条 turn 里出现**两段逐字节相同**的正文时,durable 腿上只会
+ *    留下一段。取舍是明写的:每次重连都把整轮正文再渲一遍是**必然**发生的用户可见损坏,而
+ *    「同一条 turn 里说了两遍一模一样的话」是罕见形,且活体腿上两段都在。
+ */
+function replaySeen(s, ev) {
+    const id = ev.eventId;
+    if (typeof id === 'string' && id.length > 0) {
+        if (s.seenAggregateIds.has(id))
+            return true;
+        remember(s.seenAggregateIds, id);
+    }
+    const body = ev.text;
+    if (typeof body === 'string' && s.recordedSegments.has(body))
+        return true;
+    return false;
+}
+/**
+ * 聚合帧对当前缓冲的**吸收判定**(两个聚合臂共用一份;`null` = 这一帧整只丢弃)。
+ *
+ * 三形,顺序刻意如此:
+ *   ① 缓冲是全文的**前缀**(缓冲为空时同样成立)⇒ 换成全文 —— 活体已流过的那半段被这一份接管,
+ *      同一条帧重复送达因此**幂等**(全文以自己为前缀)。
+ *   ② 缓冲是全文被**预算裁过**的尾巴(全文以缓冲结尾)⇒ **丢弃这一帧**。没有这一条,一段已经被
+ *      裁掉头部的正文,每重放一次就会被整只追加回来:内容重复、顺序错乱,而且截尾统计会一路虚涨
+ *      (裁掉的字节被反复重算)——「丢了多少」那个数会变成一句假话。
+ *   ③ 两者都不是 ⇒ 真分岔,退回**追加**、两段都留下(少渲一段比替引擎判定「哪一段才算数」更坏)。
+ */
+function absorbAggregate(buf, agg) {
+    if (agg.startsWith(buf))
+        return agg;
+    if (buf.length > 0 && agg.endsWith(buf))
+        return null;
+    return buf + agg;
+}
 function canonicalKey(ev) {
     // the wire's content events carry no taskId — runStream passes parentToolCallId in both slots
     if (ev.taskId !== ev.parentToolCallId)
@@ -222,12 +550,47 @@ export function publishSubagentContentEvent(ev) {
     const s = stateFor(key, ev.parentToolCallId);
     switch (ev.type) {
         case 'text_delta':
-            if (typeof ev.delta === 'string')
+            if (typeof ev.delta === 'string') {
+                // 🔴 增量按**拼接边界**记账(见 appendBytes:代理对被拆成两帧时按 chunk 单算会永久虚高)。
+                addBytes(s, appendBytes(s.textBuf, ev.delta));
                 s.textBuf += ev.delta;
+            }
             break;
         case 'reasoning_delta':
-            if (typeof ev.delta === 'string')
+            if (typeof ev.delta === 'string') {
+                addBytes(s, appendBytes(s.thinkBuf, ev.delta));
                 s.thinkBuf += ev.delta;
+            }
+            break;
+        // ── 聚合两臂(durable 重放腿:一段的权威全文)──────────────────────────────────────────
+        // 🔴 **吸收**而不是追加:活体已经流过的那一段是这一段全文的**前缀**,追加会让同一段内容
+        //    上屏两遍(缝前的事件序号去重管不到这一形——聚合帧与那串增量帧是不同的事件身份)。
+        //    · 全文以当前缓冲为前缀 ⇒ 缓冲整体换成全文(活体流过 0 字节时同样成立,`''` 是任何串的前缀);
+        //      同一条聚合帧重复送达时因此是**幂等**的(全文以自己为前缀)。
+        //    · 前缀对不上(理论上不该发生:同段的两次不同陈述)⇒ 退回**追加**的老语义并把两段都留下,
+        //      少渲一段比替引擎判定「哪一段才算数」更诚实。
+        // 🔴 不在这里段闭合:段边界仍由 tool_start / settle 给,与活体腿逐字同一条 —— 在这里 flush
+        //    会让「同一段的第二次重放」落成第二个 item(缓冲已空,吸收规则就没有前缀可比了)。
+        case 'text':
+            if (typeof ev.text === 'string' && ev.text.length > 0 && !replaySeen(s, ev)) {
+                const next = absorbAggregate(s.textBuf, ev.text);
+                if (next !== null) {
+                    // 吸收/追加两形都可能改变缓冲长度 ⇒ 按**差额**记账(不是按帧长度加)。
+                    const before = utf8Len(s.textBuf);
+                    s.textBuf = next;
+                    addBytes(s, utf8Len(s.textBuf) - before);
+                }
+            }
+            break;
+        case 'reasoning':
+            if (typeof ev.text === 'string' && ev.text.length > 0 && !replaySeen(s, ev)) {
+                const next = absorbAggregate(s.thinkBuf, ev.text);
+                if (next !== null) {
+                    const before = utf8Len(s.thinkBuf);
+                    s.thinkBuf = next;
+                    addBytes(s, utf8Len(s.thinkBuf) - before);
+                }
+            }
             break;
         case 'tool_start': {
             flushBuffers(s);
@@ -243,6 +606,10 @@ export function publishSubagentContentEvent(ev) {
                 const it = s.items[idx];
                 it.output = ev.output ?? '';
                 it.isError = ev.isError === true;
+                // 结果正文是**这一刻**才落到已在账的那条 item 上的 ⇒ 补记它的字节。
+                const add = utf8Len(it.output);
+                s.itemBytes[idx] = (s.itemBytes[idx] ?? 0) + add;
+                addBytes(s, add);
                 if (id !== undefined)
                     s.openTools.delete(id);
             }
@@ -260,6 +627,9 @@ export function publishSubagentContentEvent(ev) {
             break;
         }
     }
+    // 两道帽在**每一次写入之后**执行(不是定时扫):越限那一刻就丢,账本永远不会先胀起来再回落。
+    enforceTaskCap(s);
+    enforceTotalCap(key);
     scheduleNotify(key);
 }
 /** 查看态 composer echo (C2 steer optimistic display) — segment-closes the buffers first so the echo
@@ -269,6 +639,8 @@ export function pushSubagentLocalEcho(taskId, text) {
     const s = stateFor(taskId, tasks.get(taskId)?.parentToolCallId ?? '');
     flushBuffers(s);
     pushItem(s, { kind: 'echo', text });
+    enforceTaskCap(s);
+    enforceTotalCap(taskId);
     scheduleNotify(taskId);
 }
 export function getSubagentContentSnapshot(taskId) {
@@ -310,6 +682,9 @@ export function planSubagentViewSlots(taskId) {
         else if (it.kind === 'thinking') {
             out.push({ kind: 'thinking', slot: `k${i}`, text: it.text });
         }
+        else if (it.kind === 'truncated') {
+            out.push({ kind: 'truncated', slot: `x${i}`, droppedBytes: it.droppedBytes, keptFrom: it.keptFrom });
+        }
         else {
             out.push({ kind: 'echo', slot: `e${i}`, text: it.text });
         }
@@ -336,7 +711,7 @@ export function settleSubagentContent(taskId) {
     scheduleNotify(taskId);
 }
 export function clearSubagentContent(taskId) {
-    tasks.delete(taskId);
+    dropTask(taskId); // 唯一删除口:字节同拍从总账里扣掉
 }
 const bgFacts = new Map();
 export function recordBgTerminalFacts(taskId, facts) {

package/dist/writeProtectionCapability.d.ts

@@ -123,6 +123,10 @@ export declare function writeProtectionDoctorDetail(reading: WriteProtectionRead
 /**
  * operator 面读数 → 一行 detail(行名是 UNTRUSTED 自由文本 ⇒ 呈前**逐条**消毒 + 封长)。
  *
+ * 🔴 消毒与封长的顺序 = **先转义、后按转义结果封长**({@link capForDisplay},0.62.0 起本包该族的
+ *    唯一实现)。此前这三处是反的(先按原文 `slice` 再转义),一段纯控制字符的 40 字符原文转义后
+ *    能占 240 个显示字符 —— 承诺的列宽预算成了名义值的六倍。同形存量另有 SQL 姿态行一处,同批同改。
+ *
  * 🔴 只给**行数与来源**加上「头几行的名字」,不整表倾泻:一行诊断不是一个表格,而 operator 面的
  *    真表读法是那个端点本身。
  * 🔴 `rows: []` 渲的是**显式无表**这句正面事实,不是「读不出」。