@migor/agentia 0.9.4 → 0.10.0

package/dist/container/container.js

@@ -86,6 +86,27 @@ export class Container {
         finally {
             this.resolving.pop();
         }
+        // Promise 检测（外部深评 K4；判据 2026-09-29 收紧 —— 外部深评 D1）：容器是**同步**解析的 ——
+        // `async` 工厂返回的 Promise 会原样被当成「值」缓存，下游注入到的是 Promise 本身：
+        // 首次属性访问全 `undefined`、零报错、`tsc` 也看不出来（类型断言成 T 了）。这类
+        // 「静默给错东西」必须在解析期响亮失败。
+        //
+        // ⚠️ 判据是 `instanceof Promise`，**不是**「有 `then`」（或「有 `then` + `catch`」）：后者会
+        // 误伤一大类**同步**对象 —— knex / mongoose 的 query builder、各类 chainable 为实现
+        // 「可被 await」都带 `then`，而 knex / mongoose 连 `catch` 都有（2026-09-29 查两家源码实证），
+        // 它们是完全合法的注入值。「忘了 await」的产物**恒为原生 Promise**（async 函数语义），
+        // 故 `instanceof` 精确命中本意、不误伤 builder。
+        // 如实边界：**跨 realm** 的 Promise（`vm` / 其他上下文产物）`instanceof` 会漏 —— 装配期
+        // 几乎不出现，真要注入本体请走下面的逃逸口。
+        //
+        // ⚠️ 检测器**就地写**、不从别处 import：`container` 是纯叶子（`layering.test.ts` 里
+        // `container: []`，不许引内部任何模块），为几行逻辑破叶子边界不值得。
+        // 逃逸口：确实要注入 Promise **本体**，包一层即可（`useValue: { promise }`）。
+        if (value instanceof Promise) {
+            throw new TypeError(`provider "${token}" 解析出的是 Promise：容器同步解析，它会被原样缓存成「值」，` +
+                '下游拿到 Promise 而非 await 过的结果（首次属性访问全 undefined、且零报错）。' +
+                '异步初始化请在装配前 await 好再用 useValue 注入；确实要注入 Promise 本体，包一层：useValue: { promise }');
+        }
         this.cache.set(token, value);
         return value;
     }

package/dist/container/container.js.map

@@ -1 +1 @@
-{"version":3,"file":"container.js","sourceRoot":"","sources":["../../src/container/container.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../../src/container/container.ts"],"names":[],"mappings":"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"}

package/dist/core/limits.d.ts

@@ -59,7 +59,14 @@ export type BadValuePolicy =
 /** 一律视为「不限」（旧行为），不报错 */
  | 'coerced-to-unlimited'
 /** 无校验（该旋钮只做算术，坏值无处可藏） */
- | 'none';
+ | 'none'
+/**
+ * 只拒 `NaN`（2026-09-29 盘点 C5b）：`NaN` 是唯一让「实际值 > 上限」恒假、**闸静默失效**的
+ * 坏值（方向与「设了个上限」相反）；`0` / 负数 / `±Infinity` 都还有可辩护的读法（全停 / 不限），
+ * 照旧放行。需要独立一类，是因为现有三类都表达不了它 —— `throws` 会把负数的合法读法一起拒掉，
+ * `coerced-to-unlimited` / `none` 又不会拒 `NaN`。
+ */
+ | 'rejects-nan';
 export interface LimitSemantic {
     /** 稳定标识（用例按它建表；改名 = 用例红，故意的） */
     readonly knob: string;
@@ -86,7 +93,7 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zero: 'unlimited';
     readonly zeroClause: '0 = 不限';
     readonly badValue: 'throws';
-    readonly note: 'NaN/Infinity 会被 setTimeout 钳到 1ms ⇒ 每个任务立即「超时」失败，且 NaN 会绕过 `< 0` 静默通过；所以要「不限」必须显式传 0。';
+    readonly note: 'NaN/Infinity 会被 setTimeout 钳到 1ms ⇒ 每个任务立即「超时」失败，且 NaN 会绕过 `< 0` 静默通过；所以要「不限」必须显式传 0。⚠️ 2026-09-28 补上界：**超过 2^31-1ms（约 24.86 天）同样会被钳到 1ms**，构造期一并拒掉 —— 此前只查「非负有限」，于是「配 30 天超时 = 每个任务立即超时」这种配置合法、行为相反的坑能静默上线（上限单源在 core/timeout.ts）。';
 }, {
     readonly knob: 'AsyncRunner.approvalTimeoutMs';
     readonly where: 'transport/async.ts';
@@ -95,6 +102,14 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zeroClause: '0 = 不限';
     readonly badValue: 'throws';
     readonly note: '同 runTimeoutMs：非有限数会让「已挂起多久」的比较静默失效或立即超时。';
+}, {
+    readonly knob: 'AsyncRunner.maxQueued';
+    readonly where: 'transport/async.ts';
+    readonly unit: 'count';
+    readonly zero: 'unlimited';
+    readonly zeroClause: '0 = 不限（不设排队上限）';
+    readonly badValue: 'throws';
+    readonly note: '2026-09-28 外部深评 T5 补登的**新旋钮**，也刻意是「数量 + 0 = 不限」的**第二个**样本（第一个是 `mapWithConcurrency.limit`）。⚠️ 它必须登记的理由不是形式：`maxQueued: 0` 的直觉读法是「一条都不许排」（= `disabled`），而**那样读的后果正是本旋钮要防的反面** —— 并发一满，每个提交都 503。所以 0 = 不限是**刻意选的**（缺省行为与加本旋钮之前逐字一致），探针必须把这两种读法分开：`concurrency: 1` + `maxQueued: 0` 下灌 3 条，断言**都受理**且都跑完（若读成 disabled，第 2 条就抛）。';
 }, {
     readonly knob: 'AsyncRunner.drain.timeoutMs';
     readonly where: 'transport/drain-gate.ts';
@@ -102,7 +117,7 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zero: 'unlimited';
     readonly zeroClause: '非正 = 一直等';
     readonly badValue: 'none';
-    readonly note: '**历史事故现场**：`http.ts` 的优雅停机把剩余预算算成 `timeoutMs - elapsed` 再交给它，deadline 已过时算出 1 或 0 ⇒ 旧读法（`0` = 已到点）让它跨过 deadline 后**永不返回**。现在 `http.ts` 自己先判「已到点就认账」，不把 0 交给下游去猜。';
+    readonly note: '**历史事故现场**：`http.ts` 的优雅停机把剩余预算算成 `timeoutMs - elapsed` 再交给它，deadline 已过时算出 1 或 0 ⇒ 旧读法（`0` = 已到点）让它跨过 deadline 后**永不返回**。现在 `http.ts` 自己先判「已到点就认账」，不把 0 交给下游去猜。⚠️ 2026-09-28：`NaN` 与超过 2^31-1ms 的预算在闸口拒掉（超上限会被钳到 1ms ⇒「等 30 天排空」变成「1ms 后返回 false」，而 `false` 的语义是「宿主必须退出」，静默拿到它代价很高）。';
 }, {
     readonly knob: 'mapWithConcurrency.limit';
     readonly where: 'engine/concurrency.ts';
@@ -149,8 +164,8 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly unit: 'ms';
     readonly zero: 'disabled';
     readonly zeroClause: '非正 = 不设超时（原样透传）';
-    readonly badValue: 'none';
-    readonly note: '`toolTimeoutMs` 的底座。⚠️ 漏透传这个值不是「少一层保险」而是**反的**：`withTimeout(p, 0)` 直接返回原 promise = 永不超时，同时 MCP 桥找不到引擎预算又起自己的 60s 兜底 ⇒ 双计时器、双账本（`toolkit/subagent.ts` / `skill.ts` 的透传注释指的就是这条）。';
+    readonly badValue: 'throws';
+    readonly note: '`toolTimeoutMs` 的底座。⚠️ 漏透传这个值不是「少一层保险」而是**反的**：`withTimeout(p, 0)` 直接返回原 promise = 永不超时，同时 MCP 桥找不到引擎预算又起自己的 60s 兜底 ⇒ 双计时器、双账本（`toolkit/subagent.ts` / `skill.ts` 的透传注释指的就是这条）。⚠️ 2026-09-28 起 `NaN` 与超过 2^31-1ms 的值在入口拒掉（`assertTimerDelay`）：`NaN` 会**静默**落进上面那句「非正 = 不设超时」（判据是 `!(x > 0)`，NaN 满足），与「我设了个预算」的预期正好相反；超上限则被钳到 1ms ⇒ 每个工具调用立即超时。`0` / 负数仍是合法的「不设超时」。';
 }, {
     readonly knob: 'TaskEventStreams.retainTerminal';
     readonly where: 'transport/task-events.ts';
@@ -159,14 +174,22 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zeroClause: '0 = 不留终态流（终态即忘）';
     readonly badValue: 'throws';
     readonly note: '判定是 `excess <= 0 提前返回` ⇒ NaN 恒假、**全部**无订阅者的终态流被清空（保留机制静默失效，方向与 maxEvents 的「闸失效」相反、同族）。⚠️ 只跳过「还有订阅者」的终态流 —— 那是还没被读完的流，丢了下游会莫名断在半路。';
+}, {
+    readonly knob: 'TaskEventStreams.nonTerminalBuffers';
+    readonly where: 'transport/task-events.ts';
+    readonly unit: 'count';
+    readonly zero: 'disabled';
+    readonly zeroClause: '0 = 不为没人读的非终态流保留回放缓冲（有订阅者的照旧留着）';
+    readonly badValue: 'throws';
+    readonly note: '判定是 `buffered <= quota 提前返回` ⇒ NaN 恒假 ⇒ **每条**非终态流的回放缓冲都被立刻回收（回放历史静默全没，与 retainTerminal 那条「保留机制失效」同族、方向相反）。⚠️ 回收的是**缓冲**不是**表项**：`has()` 仍为真、序号接着走，缺口由 `firstAvailable` 明示（读者先收一帧 `stream.truncated`）—— 连表项一起删会让恢复段的序号从 1 重来，拿 `Last-Event-ID` 续订的读者从此静默收不到东西。⚠️ 只跳过「还有订阅者」的流（正在被读的不抽走）⇒ 被实时读的流不受配额约束。';
 }, {
     readonly knob: 'interruptibleSleep.ms';
     readonly where: 'core/timeout.ts';
     readonly unit: 'ms';
     readonly zero: 'immediate';
     readonly zeroClause: '非正 = 不睡';
-    readonly badValue: 'none';
-    readonly note: '⚠️ 这一判**先于** aborted 检查 —— 别把它「修」成「已中止就该 reject」。2026-09-19 外部复核把它当一致性缺口改反过一次，被 `tests/core/timeout.test.ts` + `tests/core/sse-text-stats.test.ts` 拦住。';
+    readonly badValue: 'throws';
+    readonly note: '⚠️ 这一判**先于** aborted 检查 —— 别把它「修」成「已中止就该 reject」。2026-09-19 外部复核把它当一致性缺口改反过一次，被 `tests/core/timeout.test.ts` + `tests/core/sse-text-stats.test.ts` 拦住。⚠️ 2026-09-28 起 `NaN` 与超 2^31-1ms 在入口拒掉（`assertTimerDelay`，判在「非正」**之前** —— `NaN <= 0` 是 false，不先挡就会穿透直落 `setTimeout(NaN)`，被钳成 1ms ⇒「退避」变成「立刻重试」）。上游给的荒谬 `Retry-After` 不走这条：它在 `backoffMs` 里被**夹**到上限（外部数据不该把一次 429 升级成硬失败）。';
 }, {
     readonly knob: 'metricsSink.intervalMs';
     readonly where: 'integrations/metrics.ts';
@@ -175,12 +198,52 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zeroClause: '0 = 立即导出';
     readonly badValue: 'none';
     readonly note: '⚠️ **同名反义**：`Scheduler.every` 的 `intervalMs: 0` 是**配置错误**（抛错），这里却是「关掉定时器、每次累加后立即导出」。两个同名旋钮两种读法 —— 改任何一个之前先看这张表。';
+}, {
+    readonly knob: 'BudgetGuardOptions.maxTotalTokens';
+    readonly where: 'engine/budget.ts（createBudgetGuard；由 RunAgentOptions.maxTotalTokens 传进来）';
+    readonly unit: 'count';
+    readonly zero: 'immediate';
+    readonly zeroClause: '0 = 第一次记账就超预算（等价于「任何用量都不许」）';
+    readonly badValue: 'rejects-nan';
+    readonly note: '闸门判据是 `totalTokens > maxTotalTokens`（**严格大于**）：0 时任何非零用量立刻撞线；负数同理（`> -1` 恒真）。对 `0` / 负数**刻意不抛错** —— 预算是运行期累计量，配成 0 是「这次 run 一条都别花」的合法意图（与 `maxIterations: 0` 同档），不是坏配置。⚠️ **但 `NaN` 必须构造期拒**（2026-09-29 盘点 C5b）：`totalTokens > NaN` **恒 false** ⇒ 闸永不触发、**静默失效**，方向与「设了个上限」正好相反；`createBudgetGuard` 对 `NaN` 抛 `RangeError`（`0` / 负数 / `±Infinity` 照旧）。⚠️ 与 `maxCostUsd` 是两个独立闸，**tokens 先判、撞了就返回**（不再看 cost）。⚠️ 2026-09-28 补登：这两个旋钮自 v0.5.0 起就存在，却一直没进这张表（「改 0 的读法不改表就构建红」这条纪律对它们曾是空的）。';
+}, {
+    readonly knob: 'BudgetGuardOptions.maxCostUsd';
+    readonly where: 'engine/budget.ts（createBudgetGuard；由 RunAgentOptions.maxCostUsd 传进来）';
+    readonly unit: 'n/a';
+    readonly zero: 'immediate';
+    readonly zeroClause: '0 = 第一笔成本就超预算（等价于「一分钱都不许花」）';
+    readonly badValue: 'rejects-nan';
+    readonly note: '判据 `costUsd > maxCostUsd`，而 `costUsd` 取 `usage.costEstimate ?? 0` ⇒ **模型不在价格表内时它恒为 0**，这个闸对未定价模型**永不触发**（静默失效；要无条件兜底请用 `maxTotalTokens`）。这一句在 `BudgetGuardOptions` 的注释里已如实写着，这里登记是为了让「0 的读法」也有单一真源。⚠️ 同 `maxTotalTokens`：`NaN`（2026-09-29 盘点 C5b）会让 `costUsd > NaN` 恒 false ⇒ 闸静默失效，`createBudgetGuard` 对 `NaN` 构造期抛 `RangeError`。';
+}, {
+    readonly knob: 'metricsSink.maxCapabilities';
+    readonly where: 'integrations/metrics.ts（metricsSink）';
+    readonly unit: 'count';
+    readonly zero: 'invalid';
+    readonly zeroClause: '0 = 一个能力都认不下（配置错误）';
+    readonly badValue: 'throws';
+    readonly note: '与 `maxModels` / `maxScores` / `maxLabelValues` / `maxLabelCombos` 同族：都是**基数封顶**，0 会让所有条目折进同一个桶 ⇒ 看板看起来「只剩一个能力」，而没有任何报错。2026-09-28 补登（这三个此前不在表里 —— 与 `BudgetGuardOptions` 那两个同一种漏登记）。';
+}, {
+    readonly knob: 'metricsSink.maxModels';
+    readonly where: 'integrations/metrics.ts（metricsSink）';
+    readonly unit: 'count';
+    readonly zero: 'invalid';
+    readonly zeroClause: '0 = 一个模型都认不下（配置错误）';
+    readonly badValue: 'throws';
+    readonly note: '同 `maxCapabilities`（该组同款判据、同款文案）。';
+}, {
+    readonly knob: 'metricsSink.maxScores';
+    readonly where: 'integrations/metrics.ts（metricsSink）';
+    readonly unit: 'count';
+    readonly zero: 'invalid';
+    readonly zeroClause: '0 = 一个分数都认不下（配置错误）';
+    readonly badValue: 'throws';
+    readonly note: '同 `maxCapabilities`。';
 }, {
     readonly knob: 'AsyncRunner.concurrency';
     readonly where: 'transport/async.ts';
     readonly unit: 'count';
     readonly zero: 'invalid';
-    readonly zeroClause: '必须为正数（0 = 没有 worker）';
+    readonly zeroClause: '0 = 没有 worker';
     readonly badValue: 'throws';
     readonly note: '0 个 worker 的池子会让每个任务永远排在队列里（既不跑也不失败）。';
 }, {
@@ -188,7 +251,7 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly where: 'transport/scheduler.ts';
     readonly unit: 'count';
     readonly zero: 'invalid';
-    readonly zeroClause: '必须为正数（Infinity = 关闸门；0 = 没有在飞名额，周期任务永不派发）';
+    readonly zeroClause: 'Infinity = 关闸门；0 = 没有在飞名额，周期任务永不派发';
     readonly badValue: 'throws';
     readonly note: '与 `AsyncRunner.concurrency` **同族**（「在飞名额」数量旋钮）：闸门判据是 `inFlight.size >= maxInFlight`，0 时恒真 ⇒ 每次 tick 都跳过，周期任务**既不跑也不失败**（探针实测 60ms 内派发 0 次、无任何报错/日志；负数同理）。⚠️ 旧实现 `opts.maxInFlight ?? 1` 把 0 静默留下，而写成 `||` 又会把它静默抬成 1 —— **两个方向都在替使用者改配置**（与 `streamBufferEvents` 记的旧 `Math.max(1, …)` 是同一个反模式）。';
 }, {
@@ -196,15 +259,23 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly where: 'transport/http.ts（createHttpHandler）';
     readonly unit: 'bytes';
     readonly zero: 'invalid';
-    readonly zeroClause: '必须为正数（0 = 每个带 body 的请求都 413）';
+    readonly zeroClause: '0 = 每个带 body 的请求都 413';
     readonly badValue: 'throws';
     readonly note: "与**同一个选项接口里**的 `maxConcurrentRuns` 同款 —— 那条写着「0 / 负数则全部 503 —— 都是配置错误，宁可在构造期响亮失败」，这条是同一形状：`readBody` 的判据是 `size > maxBytes`，0 时**任何字节**都超限 ⇒ `POST /run` / `POST /tasks` / 审批全部 413（实测 3 条 POST 全 413），服务器看着在跑却收不了任何输入。⚠️ 还挡一类事故：`Number('') === 0` —— 从**空的环境变量**读出来的配置会静默变成「拒绝一切」。要「不限」用 `Infinity`（`size > Infinity` 恒假），**别用 0**。";
+}, {
+    readonly knob: 'HttpHandlerOptions.maxConcurrentRuns';
+    readonly where: 'transport/http.ts（createHttpHandler）';
+    readonly unit: 'count';
+    readonly zero: 'invalid';
+    readonly zeroClause: 'Infinity = 无上限（0 = 全部 503）';
+    readonly badValue: 'throws';
+    readonly note: '闸门判据是 `inFlightRuns >= maxConcurrentRuns`：0 / 负数时恒真 ⇒ 每个 `POST /run` 都 503（服务器看着在跑却一个 run 都不收）；NaN 让它恒假 ⇒ 闸门静默失效。它是**存量旋钮**（校验早就有），2026-09-27 复核时发现始终没登记进这张表（文案也没走 `zeroClauseOf`），补登。';
 }, {
     readonly knob: 'SseWriterOptions.maxBufferedBytes';
     readonly where: 'transport/sse.ts（sseWriter）+ transport/http.ts（createHttpHandler 的 sseMaxBufferedBytes 透传）';
     readonly unit: 'bytes';
     readonly zero: 'invalid';
-    readonly zeroClause: '必须为正数（0 = 流活不过一帧；Infinity = 不限）';
+    readonly zeroClause: '0 = 流活不过一帧';
     readonly badValue: 'throws';
     readonly note: '判据是**写入前**的 `pending > limitBytes` ⇒ 0 时第 1 帧照写（pending 还是 0），**第 2 帧必收口**（实测：`closed=true` / `ended=true` / `onBackpressure` 回调 1 次）—— 流活不过一帧，没有任何正当用法：这个旋钮的定位是「只拦连上但不读的病态消费者」，而 0 会让**每个**消费者都被判成病态。要「关掉」用 `Infinity`。';
 }, {
@@ -222,7 +293,7 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zero: 'invalid';
     readonly zeroClause: '必须为正有限数（0 会空转）';
     readonly badValue: 'throws';
-    readonly note: '`setInterval(0)` 退化成「尽快重复」的空转循环（Node 钳到 1ms，仍是每毫秒一轮忙轮询）；超过 2^31-1ms 会被**静默**钳到 1ms，同款失败。';
+    readonly note: '`setInterval(0)` 退化成「尽快重复」的空转循环（Node 钳到 1ms，仍是每毫秒一轮忙轮询）；超过 2^31-1ms 的延迟**不会被遵守**（Node 只在 stderr 留一行 `TimeoutOverflowWarning`，随后钳到 1ms），同款失败。上限单源 2026-09-28 上提到 core/timeout.ts，与其余五处直喂 `setTimeout` 的站点共用。';
 }, {
     readonly knob: 'createAnthropicClient.timeout';
     readonly where: 'integrations/anthropic.ts';
@@ -230,15 +301,31 @@ export declare const LIMIT_SEMANTICS: readonly [{
     readonly zero: 'invalid';
     readonly zeroClause: '不设 = 不限；0 = 非法';
     readonly badValue: 'throws';
-    readonly note: '「不限」的表达方式是**不传**，不是传 0 —— 与 `runTimeoutMs` 的读法**相反**（那个要求显式传 0）。';
+    readonly note: '「不限」的表达方式是**不传**，不是传 0 —— 与 `runTimeoutMs` 的读法**相反**（那个要求显式传 0）。⚠️ 2026-09-28 补上界：超过 2^31-1ms 的值同样被钳到 1ms ⇒「30 天超时」变成「每个请求立即超时」，构造期一并拒掉。';
 }, {
     readonly knob: 'metricsSink.windowSize';
     readonly where: 'integrations/metrics.ts';
     readonly unit: 'count';
     readonly zero: 'invalid';
-    readonly zeroClause: '必须为正数（0 = 窗口里什么都没有）';
+    readonly zeroClause: '0 = 窗口里什么都没有';
     readonly badValue: 'throws';
     readonly note: '同款的还有 `maxCapabilities` / `maxModels` / `maxScores` —— 都是「必须为正数」。';
+}, {
+    readonly knob: 'metricsSink.maxLabelValues';
+    readonly where: 'integrations/metrics.ts';
+    readonly unit: 'count';
+    readonly zero: 'invalid';
+    readonly zeroClause: '0 = 一个标签值都认不下';
+    readonly badValue: 'throws';
+    readonly note: '归因标签（R8-P4）的基数上限，与 `maxCapabilities` / `maxModels` / `maxScores` 同族。0 时**每个**值都折叠进 `__other__` —— 「opt-in 了标签维度却一个值都区分不开」没有正当读法，是配置错误；且这道上限刻意不可关（opt-in 挡不住「明知几千租户偏要上」，内存不变量要求每个新基数维度都有 cap）。';
+}, {
+    readonly knob: 'metricsSink.maxLabelCombos';
+    readonly where: 'integrations/metrics.ts';
+    readonly unit: 'count';
+    readonly zero: 'invalid';
+    readonly zeroClause: '0 = 一个标签组合都认不下，全折进一个桶';
+    readonly badValue: 'throws';
+    readonly note: '**组合数**上限（2026-09-27 ⑧ 补的第四条基数上限）。`maxLabelValues` 只封每个键的**值域**，而进内存的是组合，数量是叉乘 `(maxLabelValues+1)^labelKeys.length` —— 缺省 100 × 3 键就是一百万条，且每键的 dropped 计数看不见它。与另外三道同款：超限折进一个全 `__other__` 的桶（量不丢），折叠数见 `droppedLabelCombos` / `dropped_keys{kind="label:combos"}`。';
 }];
 /** 表里全部旋钮的标识（用例按它建穷尽表：少一项 `typecheck:tests` 就红） */
 export type LimitKnob = (typeof LIMIT_SEMANTICS)[number]['knob'];

package/dist/core/limits.js

@@ -48,7 +48,7 @@ export const LIMIT_SEMANTICS = [
         zero: 'unlimited',
         zeroClause: '0 = 不限',
         badValue: 'throws',
-        note: 'NaN/Infinity 会被 setTimeout 钳到 1ms ⇒ 每个任务立即「超时」失败，且 NaN 会绕过 `< 0` 静默通过；所以要「不限」必须显式传 0。',
+        note: 'NaN/Infinity 会被 setTimeout 钳到 1ms ⇒ 每个任务立即「超时」失败，且 NaN 会绕过 `< 0` 静默通过；所以要「不限」必须显式传 0。⚠️ 2026-09-28 补上界：**超过 2^31-1ms（约 24.86 天）同样会被钳到 1ms**，构造期一并拒掉 —— 此前只查「非负有限」，于是「配 30 天超时 = 每个任务立即超时」这种配置合法、行为相反的坑能静默上线（上限单源在 core/timeout.ts）。',
     },
     {
         knob: 'AsyncRunner.approvalTimeoutMs',
@@ -59,6 +59,15 @@ export const LIMIT_SEMANTICS = [
         badValue: 'throws',
         note: '同 runTimeoutMs：非有限数会让「已挂起多久」的比较静默失效或立即超时。',
     },
+    {
+        knob: 'AsyncRunner.maxQueued',
+        where: 'transport/async.ts',
+        unit: 'count',
+        zero: 'unlimited',
+        zeroClause: '0 = 不限（不设排队上限）',
+        badValue: 'throws',
+        note: '2026-09-28 外部深评 T5 补登的**新旋钮**，也刻意是「数量 + 0 = 不限」的**第二个**样本（第一个是 `mapWithConcurrency.limit`）。⚠️ 它必须登记的理由不是形式：`maxQueued: 0` 的直觉读法是「一条都不许排」（= `disabled`），而**那样读的后果正是本旋钮要防的反面** —— 并发一满，每个提交都 503。所以 0 = 不限是**刻意选的**（缺省行为与加本旋钮之前逐字一致），探针必须把这两种读法分开：`concurrency: 1` + `maxQueued: 0` 下灌 3 条，断言**都受理**且都跑完（若读成 disabled，第 2 条就抛）。',
+    },
     {
         knob: 'AsyncRunner.drain.timeoutMs',
         where: 'transport/drain-gate.ts',
@@ -66,7 +75,7 @@ export const LIMIT_SEMANTICS = [
         zero: 'unlimited',
         zeroClause: '非正 = 一直等',
         badValue: 'none',
-        note: '**历史事故现场**：`http.ts` 的优雅停机把剩余预算算成 `timeoutMs - elapsed` 再交给它，deadline 已过时算出 1 或 0 ⇒ 旧读法（`0` = 已到点）让它跨过 deadline 后**永不返回**。现在 `http.ts` 自己先判「已到点就认账」，不把 0 交给下游去猜。',
+        note: '**历史事故现场**：`http.ts` 的优雅停机把剩余预算算成 `timeoutMs - elapsed` 再交给它，deadline 已过时算出 1 或 0 ⇒ 旧读法（`0` = 已到点）让它跨过 deadline 后**永不返回**。现在 `http.ts` 自己先判「已到点就认账」，不把 0 交给下游去猜。⚠️ 2026-09-28：`NaN` 与超过 2^31-1ms 的预算在闸口拒掉（超上限会被钳到 1ms ⇒「等 30 天排空」变成「1ms 后返回 false」，而 `false` 的语义是「宿主必须退出」，静默拿到它代价很高）。',
     },
     {
         knob: 'mapWithConcurrency.limit',
@@ -120,8 +129,8 @@ export const LIMIT_SEMANTICS = [
         unit: 'ms',
         zero: 'disabled',
         zeroClause: '非正 = 不设超时（原样透传）',
-        badValue: 'none',
-        note: '`toolTimeoutMs` 的底座。⚠️ 漏透传这个值不是「少一层保险」而是**反的**：`withTimeout(p, 0)` 直接返回原 promise = 永不超时，同时 MCP 桥找不到引擎预算又起自己的 60s 兜底 ⇒ 双计时器、双账本（`toolkit/subagent.ts` / `skill.ts` 的透传注释指的就是这条）。',
+        badValue: 'throws',
+        note: '`toolTimeoutMs` 的底座。⚠️ 漏透传这个值不是「少一层保险」而是**反的**：`withTimeout(p, 0)` 直接返回原 promise = 永不超时，同时 MCP 桥找不到引擎预算又起自己的 60s 兜底 ⇒ 双计时器、双账本（`toolkit/subagent.ts` / `skill.ts` 的透传注释指的就是这条）。⚠️ 2026-09-28 起 `NaN` 与超过 2^31-1ms 的值在入口拒掉（`assertTimerDelay`）：`NaN` 会**静默**落进上面那句「非正 = 不设超时」（判据是 `!(x > 0)`，NaN 满足），与「我设了个预算」的预期正好相反；超上限则被钳到 1ms ⇒ 每个工具调用立即超时。`0` / 负数仍是合法的「不设超时」。',
     },
     {
         knob: 'TaskEventStreams.retainTerminal',
@@ -132,6 +141,15 @@ export const LIMIT_SEMANTICS = [
         badValue: 'throws',
         note: '判定是 `excess <= 0 提前返回` ⇒ NaN 恒假、**全部**无订阅者的终态流被清空（保留机制静默失效，方向与 maxEvents 的「闸失效」相反、同族）。⚠️ 只跳过「还有订阅者」的终态流 —— 那是还没被读完的流，丢了下游会莫名断在半路。',
     },
+    {
+        knob: 'TaskEventStreams.nonTerminalBuffers',
+        where: 'transport/task-events.ts',
+        unit: 'count',
+        zero: 'disabled',
+        zeroClause: '0 = 不为没人读的非终态流保留回放缓冲（有订阅者的照旧留着）',
+        badValue: 'throws',
+        note: '判定是 `buffered <= quota 提前返回` ⇒ NaN 恒假 ⇒ **每条**非终态流的回放缓冲都被立刻回收（回放历史静默全没，与 retainTerminal 那条「保留机制失效」同族、方向相反）。⚠️ 回收的是**缓冲**不是**表项**：`has()` 仍为真、序号接着走，缺口由 `firstAvailable` 明示（读者先收一帧 `stream.truncated`）—— 连表项一起删会让恢复段的序号从 1 重来，拿 `Last-Event-ID` 续订的读者从此静默收不到东西。⚠️ 只跳过「还有订阅者」的流（正在被读的不抽走）⇒ 被实时读的流不受配额约束。',
+    },
     // ── 0 = 立即执行（等待预算为 0 ⇒ 这次等待不存在）─────────────────────────
     {
         knob: 'interruptibleSleep.ms',
@@ -139,8 +157,8 @@ export const LIMIT_SEMANTICS = [
         unit: 'ms',
         zero: 'immediate',
         zeroClause: '非正 = 不睡',
-        badValue: 'none',
-        note: '⚠️ 这一判**先于** aborted 检查 —— 别把它「修」成「已中止就该 reject」。2026-09-19 外部复核把它当一致性缺口改反过一次，被 `tests/core/timeout.test.ts` + `tests/core/sse-text-stats.test.ts` 拦住。',
+        badValue: 'throws',
+        note: '⚠️ 这一判**先于** aborted 检查 —— 别把它「修」成「已中止就该 reject」。2026-09-19 外部复核把它当一致性缺口改反过一次，被 `tests/core/timeout.test.ts` + `tests/core/sse-text-stats.test.ts` 拦住。⚠️ 2026-09-28 起 `NaN` 与超 2^31-1ms 在入口拒掉（`assertTimerDelay`，判在「非正」**之前** —— `NaN <= 0` 是 false，不先挡就会穿透直落 `setTimeout(NaN)`，被钳成 1ms ⇒「退避」变成「立刻重试」）。上游给的荒谬 `Retry-After` 不走这条：它在 `backoffMs` 里被**夹**到上限（外部数据不该把一次 429 升级成硬失败）。',
     },
     {
         knob: 'metricsSink.intervalMs',
@@ -151,13 +169,58 @@ export const LIMIT_SEMANTICS = [
         badValue: 'none',
         note: '⚠️ **同名反义**：`Scheduler.every` 的 `intervalMs: 0` 是**配置错误**（抛错），这里却是「关掉定时器、每次累加后立即导出」。两个同名旋钮两种读法 —— 改任何一个之前先看这张表。',
     },
+    {
+        knob: 'BudgetGuardOptions.maxTotalTokens',
+        where: 'engine/budget.ts（createBudgetGuard；由 RunAgentOptions.maxTotalTokens 传进来）',
+        unit: 'count',
+        zero: 'immediate',
+        zeroClause: '0 = 第一次记账就超预算（等价于「任何用量都不许」）',
+        badValue: 'rejects-nan',
+        note: '闸门判据是 `totalTokens > maxTotalTokens`（**严格大于**）：0 时任何非零用量立刻撞线；负数同理（`> -1` 恒真）。对 `0` / 负数**刻意不抛错** —— 预算是运行期累计量，配成 0 是「这次 run 一条都别花」的合法意图（与 `maxIterations: 0` 同档），不是坏配置。⚠️ **但 `NaN` 必须构造期拒**（2026-09-29 盘点 C5b）：`totalTokens > NaN` **恒 false** ⇒ 闸永不触发、**静默失效**，方向与「设了个上限」正好相反；`createBudgetGuard` 对 `NaN` 抛 `RangeError`（`0` / 负数 / `±Infinity` 照旧）。⚠️ 与 `maxCostUsd` 是两个独立闸，**tokens 先判、撞了就返回**（不再看 cost）。⚠️ 2026-09-28 补登：这两个旋钮自 v0.5.0 起就存在，却一直没进这张表（「改 0 的读法不改表就构建红」这条纪律对它们曾是空的）。',
+    },
+    {
+        knob: 'BudgetGuardOptions.maxCostUsd',
+        where: 'engine/budget.ts（createBudgetGuard；由 RunAgentOptions.maxCostUsd 传进来）',
+        unit: 'n/a',
+        zero: 'immediate',
+        zeroClause: '0 = 第一笔成本就超预算（等价于「一分钱都不许花」）',
+        badValue: 'rejects-nan',
+        note: '判据 `costUsd > maxCostUsd`，而 `costUsd` 取 `usage.costEstimate ?? 0` ⇒ **模型不在价格表内时它恒为 0**，这个闸对未定价模型**永不触发**（静默失效；要无条件兜底请用 `maxTotalTokens`）。这一句在 `BudgetGuardOptions` 的注释里已如实写着，这里登记是为了让「0 的读法」也有单一真源。⚠️ 同 `maxTotalTokens`：`NaN`（2026-09-29 盘点 C5b）会让 `costUsd > NaN` 恒 false ⇒ 闸静默失效，`createBudgetGuard` 对 `NaN` 构造期抛 `RangeError`。',
+    },
+    {
+        knob: 'metricsSink.maxCapabilities',
+        where: 'integrations/metrics.ts（metricsSink）',
+        unit: 'count',
+        zero: 'invalid',
+        zeroClause: '0 = 一个能力都认不下（配置错误）',
+        badValue: 'throws',
+        note: '与 `maxModels` / `maxScores` / `maxLabelValues` / `maxLabelCombos` 同族：都是**基数封顶**，0 会让所有条目折进同一个桶 ⇒ 看板看起来「只剩一个能力」，而没有任何报错。2026-09-28 补登（这三个此前不在表里 —— 与 `BudgetGuardOptions` 那两个同一种漏登记）。',
+    },
+    {
+        knob: 'metricsSink.maxModels',
+        where: 'integrations/metrics.ts（metricsSink）',
+        unit: 'count',
+        zero: 'invalid',
+        zeroClause: '0 = 一个模型都认不下（配置错误）',
+        badValue: 'throws',
+        note: '同 `maxCapabilities`（该组同款判据、同款文案）。',
+    },
+    {
+        knob: 'metricsSink.maxScores',
+        where: 'integrations/metrics.ts（metricsSink）',
+        unit: 'count',
+        zero: 'invalid',
+        zeroClause: '0 = 一个分数都认不下（配置错误）',
+        badValue: 'throws',
+        note: '同 `maxCapabilities`。',
+    },
     // ── 0 = 非法配置（响亮失败）─────────────────────────────────────────────
     {
         knob: 'AsyncRunner.concurrency',
         where: 'transport/async.ts',
         unit: 'count',
         zero: 'invalid',
-        zeroClause: '必须为正数（0 = 没有 worker）',
+        zeroClause: '0 = 没有 worker',
         badValue: 'throws',
         note: '0 个 worker 的池子会让每个任务永远排在队列里（既不跑也不失败）。',
     },
@@ -166,7 +229,7 @@ export const LIMIT_SEMANTICS = [
         where: 'transport/scheduler.ts',
         unit: 'count',
         zero: 'invalid',
-        zeroClause: '必须为正数（Infinity = 关闸门；0 = 没有在飞名额，周期任务永不派发）',
+        zeroClause: 'Infinity = 关闸门；0 = 没有在飞名额，周期任务永不派发',
         badValue: 'throws',
         note: '与 `AsyncRunner.concurrency` **同族**（「在飞名额」数量旋钮）：闸门判据是 `inFlight.size >= maxInFlight`，0 时恒真 ⇒ 每次 tick 都跳过，周期任务**既不跑也不失败**（探针实测 60ms 内派发 0 次、无任何报错/日志；负数同理）。⚠️ 旧实现 `opts.maxInFlight ?? 1` 把 0 静默留下，而写成 `||` 又会把它静默抬成 1 —— **两个方向都在替使用者改配置**（与 `streamBufferEvents` 记的旧 `Math.max(1, …)` 是同一个反模式）。',
     },
@@ -175,16 +238,25 @@ export const LIMIT_SEMANTICS = [
         where: 'transport/http.ts（createHttpHandler）',
         unit: 'bytes',
         zero: 'invalid',
-        zeroClause: '必须为正数（0 = 每个带 body 的请求都 413）',
+        zeroClause: '0 = 每个带 body 的请求都 413',
         badValue: 'throws',
         note: "与**同一个选项接口里**的 `maxConcurrentRuns` 同款 —— 那条写着「0 / 负数则全部 503 —— 都是配置错误，宁可在构造期响亮失败」，这条是同一形状：`readBody` 的判据是 `size > maxBytes`，0 时**任何字节**都超限 ⇒ `POST /run` / `POST /tasks` / 审批全部 413（实测 3 条 POST 全 413），服务器看着在跑却收不了任何输入。⚠️ 还挡一类事故：`Number('') === 0` —— 从**空的环境变量**读出来的配置会静默变成「拒绝一切」。要「不限」用 `Infinity`（`size > Infinity` 恒假），**别用 0**。",
     },
+    {
+        knob: 'HttpHandlerOptions.maxConcurrentRuns',
+        where: 'transport/http.ts（createHttpHandler）',
+        unit: 'count',
+        zero: 'invalid',
+        zeroClause: 'Infinity = 无上限（0 = 全部 503）',
+        badValue: 'throws',
+        note: '闸门判据是 `inFlightRuns >= maxConcurrentRuns`：0 / 负数时恒真 ⇒ 每个 `POST /run` 都 503（服务器看着在跑却一个 run 都不收）；NaN 让它恒假 ⇒ 闸门静默失效。它是**存量旋钮**（校验早就有），2026-09-27 复核时发现始终没登记进这张表（文案也没走 `zeroClauseOf`），补登。',
+    },
     {
         knob: 'SseWriterOptions.maxBufferedBytes',
         where: 'transport/sse.ts（sseWriter）+ transport/http.ts（createHttpHandler 的 sseMaxBufferedBytes 透传）',
         unit: 'bytes',
         zero: 'invalid',
-        zeroClause: '必须为正数（0 = 流活不过一帧；Infinity = 不限）',
+        zeroClause: '0 = 流活不过一帧',
         badValue: 'throws',
         note: '判据是**写入前**的 `pending > limitBytes` ⇒ 0 时第 1 帧照写（pending 还是 0），**第 2 帧必收口**（实测：`closed=true` / `ended=true` / `onBackpressure` 回调 1 次）—— 流活不过一帧，没有任何正当用法：这个旋钮的定位是「只拦连上但不读的病态消费者」，而 0 会让**每个**消费者都被判成病态。要「关掉」用 `Infinity`。',
     },
@@ -204,7 +276,7 @@ export const LIMIT_SEMANTICS = [
         zero: 'invalid',
         zeroClause: '必须为正有限数（0 会空转）',
         badValue: 'throws',
-        note: '`setInterval(0)` 退化成「尽快重复」的空转循环（Node 钳到 1ms，仍是每毫秒一轮忙轮询）；超过 2^31-1ms 会被**静默**钳到 1ms，同款失败。',
+        note: '`setInterval(0)` 退化成「尽快重复」的空转循环（Node 钳到 1ms，仍是每毫秒一轮忙轮询）；超过 2^31-1ms 的延迟**不会被遵守**（Node 只在 stderr 留一行 `TimeoutOverflowWarning`，随后钳到 1ms），同款失败。上限单源 2026-09-28 上提到 core/timeout.ts，与其余五处直喂 `setTimeout` 的站点共用。',
     },
     {
         knob: 'createAnthropicClient.timeout',
@@ -213,17 +285,35 @@ export const LIMIT_SEMANTICS = [
         zero: 'invalid',
         zeroClause: '不设 = 不限；0 = 非法',
         badValue: 'throws',
-        note: '「不限」的表达方式是**不传**，不是传 0 —— 与 `runTimeoutMs` 的读法**相反**（那个要求显式传 0）。',
+        note: '「不限」的表达方式是**不传**，不是传 0 —— 与 `runTimeoutMs` 的读法**相反**（那个要求显式传 0）。⚠️ 2026-09-28 补上界：超过 2^31-1ms 的值同样被钳到 1ms ⇒「30 天超时」变成「每个请求立即超时」，构造期一并拒掉。',
     },
     {
         knob: 'metricsSink.windowSize',
         where: 'integrations/metrics.ts',
         unit: 'count',
         zero: 'invalid',
-        zeroClause: '必须为正数（0 = 窗口里什么都没有）',
+        zeroClause: '0 = 窗口里什么都没有',
         badValue: 'throws',
         note: '同款的还有 `maxCapabilities` / `maxModels` / `maxScores` —— 都是「必须为正数」。',
     },
+    {
+        knob: 'metricsSink.maxLabelValues',
+        where: 'integrations/metrics.ts',
+        unit: 'count',
+        zero: 'invalid',
+        zeroClause: '0 = 一个标签值都认不下',
+        badValue: 'throws',
+        note: '归因标签（R8-P4）的基数上限，与 `maxCapabilities` / `maxModels` / `maxScores` 同族。0 时**每个**值都折叠进 `__other__` —— 「opt-in 了标签维度却一个值都区分不开」没有正当读法，是配置错误；且这道上限刻意不可关（opt-in 挡不住「明知几千租户偏要上」，内存不变量要求每个新基数维度都有 cap）。',
+    },
+    {
+        knob: 'metricsSink.maxLabelCombos',
+        where: 'integrations/metrics.ts',
+        unit: 'count',
+        zero: 'invalid',
+        zeroClause: '0 = 一个标签组合都认不下，全折进一个桶',
+        badValue: 'throws',
+        note: '**组合数**上限（2026-09-27 ⑧ 补的第四条基数上限）。`maxLabelValues` 只封每个键的**值域**，而进内存的是组合，数量是叉乘 `(maxLabelValues+1)^labelKeys.length` —— 缺省 100 × 3 键就是一百万条，且每键的 dropped 计数看不见它。与另外三道同款：超限折进一个全 `__other__` 的桶（量不丢），折叠数见 `droppedLabelCombos` / `dropped_keys{kind="label:combos"}`。',
+    },
 ];
 /** 按旋钮取那行（拼错旋钮名 = 编译期报错，不是运行期 undefined） */
 export function limitSemanticOf(knob) {

package/dist/core/limits.js.map

@@ -1 +1 @@
-{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/core/limits.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/core/limits.ts"],"names":[],"mappings":"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"}

package/dist/core/line-framing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Agentia —— 换行分隔 JSON-RPC 的**分帧缓冲上限**（两条 MCP 桥**共用一份**）。
+ *
+ * 为什么要有这个文件：两个方向的桥各自攒一个字符串缓冲按 `\n` 切帧 ——
+ *   ① 正向连接器 `integrations/mcp-stdio.ts` 读**子进程 stdout**；
+ *   ② 反向桥 `engine/mcp-server-stdio.ts` 读**宿主 stdin**。
+ * 两份都是 `buf += chunk` 然后找换行，**没有任何长度上限**（2026-09-28 外部深评 S6）：
+ * 对端只要一直吐不带换行的字节（坏 server / 坏宿主 / 一条 5GB 的「一行」），缓冲区就无界
+ * 增长 ⇒ 先 OOM 再谈协议。这不是「罕见输入」：stdout 里混日志的 MCP server 本来就常见
+ * （连接器那条的注释已认下这点），而**一个不换行的日志行**就是这形态。
+ *
+ * 为什么两份共用一份常量而不是各写一个：这正是本仓反复吃过的「同一契约两份实现」的坑
+ * （见 `docs/guards.md`）—— 两侧上限漂了不会有任何症状，直到某天一侧先 OOM。
+ * 放 `core` 是因为 `integrations` 与 `engine` 都只许依赖 `core`（分层守卫），
+ * 谁也不能把常量挂在对方身上。
+ *
+ * ⚠️ 单位是 **UTF-16 码元**（`string.length`），不是字节。为什么不按字节：两侧的缓冲都是
+ * `setEncoding('utf8')` 之后的**字符串**，逐块算 `Buffer.byteLength` 要么每次重算整段
+ * （O(n²)），要么另维护一个字节计数器（同一段缓冲两套长度，迟早漂）。码元长度是现成的、
+ * 单调递增的，做**上限**足够 —— 而且它是**保守**的：每个码元在内存里最少占 2 字节，
+ * 所以真实内存占用 ≤ 2× 这个值，不会低估到危险。
+ *
+ * 取值口径：**远大于任何合法报文，远小于能让进程 OOM**。MCP 的单条报文里可能装着工具结果
+ * （整份文件、整段日志），给小了会把正常调用打成协议错 —— 那比 OOM 更难查（症状是「偶发
+ * 失败」）。800 万码元是「一次性工具结果」的宽裕上界，同时上千个并发连接各自缓冲一份也仍
+ * 在几 GB 量级之外。
+ *
+ * ⚠️ 这是**硬上限，不是旋钮**：它没有「0 = 不限」的读法，所以不进 `core/limits.ts` 的旋钮表
+ * （那张表管的是「使用者能设的旋钮，0 是什么意思」）。要改它只能改代码 + 两侧用例。
+ */
+export declare const MAX_FRAME_CHARS: number;
+/**
+ * 上限的人类可读说法（两条桥的报错文案共用 —— 免得一处写「8 MiB」一处写「8388608」）。
+ * 数值与 `MAX_FRAME_CHARS` 同源，改上限不会让文案漂。
+ */
+export declare function frameLimitText(): string;

package/dist/core/line-framing.js

@@ -0,0 +1,39 @@
+/**
+ * Agentia —— 换行分隔 JSON-RPC 的**分帧缓冲上限**（两条 MCP 桥**共用一份**）。
+ *
+ * 为什么要有这个文件：两个方向的桥各自攒一个字符串缓冲按 `\n` 切帧 ——
+ *   ① 正向连接器 `integrations/mcp-stdio.ts` 读**子进程 stdout**；
+ *   ② 反向桥 `engine/mcp-server-stdio.ts` 读**宿主 stdin**。
+ * 两份都是 `buf += chunk` 然后找换行，**没有任何长度上限**（2026-09-28 外部深评 S6）：
+ * 对端只要一直吐不带换行的字节（坏 server / 坏宿主 / 一条 5GB 的「一行」），缓冲区就无界
+ * 增长 ⇒ 先 OOM 再谈协议。这不是「罕见输入」：stdout 里混日志的 MCP server 本来就常见
+ * （连接器那条的注释已认下这点），而**一个不换行的日志行**就是这形态。
+ *
+ * 为什么两份共用一份常量而不是各写一个：这正是本仓反复吃过的「同一契约两份实现」的坑
+ * （见 `docs/guards.md`）—— 两侧上限漂了不会有任何症状，直到某天一侧先 OOM。
+ * 放 `core` 是因为 `integrations` 与 `engine` 都只许依赖 `core`（分层守卫），
+ * 谁也不能把常量挂在对方身上。
+ *
+ * ⚠️ 单位是 **UTF-16 码元**（`string.length`），不是字节。为什么不按字节：两侧的缓冲都是
+ * `setEncoding('utf8')` 之后的**字符串**，逐块算 `Buffer.byteLength` 要么每次重算整段
+ * （O(n²)），要么另维护一个字节计数器（同一段缓冲两套长度，迟早漂）。码元长度是现成的、
+ * 单调递增的，做**上限**足够 —— 而且它是**保守**的：每个码元在内存里最少占 2 字节，
+ * 所以真实内存占用 ≤ 2× 这个值，不会低估到危险。
+ *
+ * 取值口径：**远大于任何合法报文，远小于能让进程 OOM**。MCP 的单条报文里可能装着工具结果
+ * （整份文件、整段日志），给小了会把正常调用打成协议错 —— 那比 OOM 更难查（症状是「偶发
+ * 失败」）。800 万码元是「一次性工具结果」的宽裕上界，同时上千个并发连接各自缓冲一份也仍
+ * 在几 GB 量级之外。
+ *
+ * ⚠️ 这是**硬上限，不是旋钮**：它没有「0 = 不限」的读法，所以不进 `core/limits.ts` 的旋钮表
+ * （那张表管的是「使用者能设的旋钮，0 是什么意思」）。要改它只能改代码 + 两侧用例。
+ */
+export const MAX_FRAME_CHARS = 8 * 1024 * 1024;
+/**
+ * 上限的人类可读说法（两条桥的报错文案共用 —— 免得一处写「8 MiB」一处写「8388608」）。
+ * 数值与 `MAX_FRAME_CHARS` 同源，改上限不会让文案漂。
+ */
+export function frameLimitText() {
+    return `${MAX_FRAME_CHARS} 码元（约 ${MAX_FRAME_CHARS / (1024 * 1024)} MiB）`;
+}
+//# sourceMappingURL=line-framing.js.map

package/dist/core/line-framing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-framing.js","sourceRoot":"","sources":["../../src/core/line-framing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/C;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,GAAG,eAAe,SAAS,eAAe,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC;AAC3E,CAAC"}

package/dist/core/message.d.ts

@@ -134,6 +134,17 @@ export interface MessageUsage {
     output_tokens: number;
     cache_creation_input_tokens?: number | null;
     cache_read_input_tokens?: number | null;
+    /**
+     * 上游**根本没回报 usage**（整条流 / 整个响应都没带计量）时为 `true` ——
+     * 此时上面那些 `0` 是**替身值**，不是读数（2026-09-28 外部深评 S2）。
+     * 缺省 `undefined` = 上游真的回报了。
+     *
+     * 为什么必须显式标出来：`0` 与「不知道」在数值上无法区分，而成本估算拿到的就是
+     * 这个 `0` —— 于是 `maxCostUsd` 这条护栏**静默失效**（花销看起来恒为 0），
+     * 连「算不出成本」的信号都没有。引擎侧据此在 llm.turn span 上记 `usage.missing`
+     * 事件（见 `engine/turn.ts` 的 `recordTurnUsage`），报告与指标各有一处出声。
+     */
+    unreported?: true;
 }
 /** 一次模型往返的最终响应（`ModelClient.messages.stream().finalMessage()` 的产物） */
 export interface Message {