@sema-agent/client-core 0.14.0 → 0.16.0

package/dist/fleetAgentPanelProjection.js

@@ -51,7 +51,20 @@ import { DEFAULT_SESSION_KEY } from './sessionSlot.js';
 export const ABSENT_SETTLE_MS = 30_000;
 /** REF-CC-045(fleet2-07):settled 条目的回收期 —— settle 后这么久仍未再被投影 ⇒ 台账整条
  *  delete,给 `fleetAgentProjectionSizeFor()` 一个上界(此前 `seen` 只增不减,长会话里每个
- *  跑过的 bg 子代永久占一条)。settle 事件已经发过,消费端 settle 幂等,delete 对外无事件。 */
+ *  跑过的 bg 子代永久占一条)。settle 事件已经发过,消费端 settle 幂等,delete 对外无事件。
+ *
+ *  🔴 [2393] notif-F13 / sweep-F7(2026-08-03 全窗复审)**两处纠**(判据换轴 + 范围如实):
+ *   (a) 回收判据从 `lastSeenAt` 换成 **`settledAtMs`**(settle 那一刻的钟)。上一版 ③ 缺席兜底
+ *       把条目标 `settled:true` 时**保留旧的 lastSeenAt**,紧接着 ④ 在**同一次调用**里用
+ *       `nowMs - lastSeenAt > 120s` 判回收 ⇒ 面板卸载超过 120s 再挂回来时,那条行「刚被 settle
+ *       就立刻被删」,而 `prev?.settled` 正是「终态 end 只发一次」的**唯一**判据 —— 去重记号随
+ *       条目一起消失,同 taskId 的迟到终态帧会再发一次 `fleet-row`+`end`。
+ *       换轴之后「settle 后至少保留一个回收期」成为真的。
+ *   (b) 回收只对**本次投影里已不在场**的条目成立(`!present.has(taskId)`)。仍在场的终态行不删:
+ *       删了它下一拍 `prev === undefined` 会**重发 end**,每拍一次,比不删坏得多。
+ *       ⇒ 上界的如实表述:**不再被投影的条目会被回收**;仍被持续投影的终态行由投影集自身定界
+ *       (它的大小是引擎/宿主列出来的行数,不是本台账的无界累积)。ledger 里 REF-CC-045 的问题
+ *       陈述「只增不减」覆盖的正是前半场,后半场此前被说成也已解决,那句话不成立。 */
 const SETTLED_RETENTION_MS = ABSENT_SETTLE_MS * 4;
 /** currentTool 判等键(POST-MERGE 行每秒重发同值,只有键变了才算变化)。 */
 function currentToolKeyOf(ct) {
@@ -157,6 +170,8 @@ export function projectFleetAgentRowsFor(sessionKey, rows, nowMs = Date.now()) {
                 currentToolKey: currentToolKey !== undefined ? currentToolKey : prev?.currentToolKey,
                 lastSeenAt: nowMs,
                 settled: true,
+                // notif-F13:settle 时刻只在**首次** settle 时铸(重复投影的终态行不许一路续命回收期)。
+                settledAtMs: prev?.settled ? prev.settledAtMs : nowMs,
             });
             continue;
         }
@@ -195,6 +210,7 @@ export function projectFleetAgentRowsFor(sessionKey, rows, nowMs = Date.now()) {
             currentToolKey: currentToolKey !== undefined ? currentToolKey : prev?.currentToolKey,
             lastSeenAt: nowMs,
             settled: false,
+            settledAtMs: undefined, // 又活了 ⇒ 回收钟归零(重新 settle 时重铸)
         });
     }
     // ③ 缺席兜底 —— 必须在【本次在场行全部刷完 lastSeen 之后】判,否则 footer 长时间卸载后重挂
@@ -205,12 +221,18 @@ export function projectFleetAgentRowsFor(sessionKey, rows, nowMs = Date.now()) {
         if (nowMs - s.lastSeenAt <= ABSENT_SETTLE_MS)
             continue;
         publishEngineAgentPanelEvent({ kind: 'end', taskId, isError: false });
-        seenMap.set(taskId, { ...s, settled: true });
+        seenMap.set(taskId, { ...s, settled: true, settledAtMs: nowMs }); // notif-F13:settle 时刻按**现在**铸
     }
     // ④ REF-CC-045(fleet2-07):settled 条目回收 —— 给台账一个上界(此前只增不减)。settle 已发过
     //    事件,delete 对外无事件,消费端 settle 本身幂等。
+    //    [2393] notif-F13/sweep-F7 两处纠(判据见 SETTLED_RETENTION_MS 头注):
+    //      · 锚 `settledAtMs`(settle 那一刻)而不是 `lastSeenAt`(最后一次被投影);
+    //      · 只回收**已不在场**的条目 —— 仍在场的终态行删了会每拍重发 end。
     for (const [taskId, s] of seenMap) {
-        if (s.settled && nowMs - s.lastSeenAt > SETTLED_RETENTION_MS)
+        if (!s.settled || present.has(taskId))
+            continue;
+        const settledAt = s.settledAtMs ?? s.lastSeenAt;
+        if (nowMs - settledAt > SETTLED_RETENTION_MS)
             seenMap.delete(taskId);
     }
     if (seenMap.size === 0)

package/dist/index.d.ts

@@ -223,5 +223,7 @@ export * from './seatContract.js';
 export * from './agentSession/contract.js';
 export * from './agentSession/backgroundView.js';
 export * from './model/catalog.js';
+export * from './model/catalogLoader.js';
+export * from './model/providerAuth.js';
 export * from './websearch/searchProviderPresets.js';
 export * from './env/localeGeo.js';

package/dist/index.js

@@ -153,6 +153,16 @@ export * from './fleetTaskDesc.js';
 // 通知族(engineTaskNotification + taskNotificationErrorSupplement + hookNoticeStore 判定半场)
 // 已并入 notifications.js,不需要新增导出行。
 export * from './hostEnv.js';
+// 🔴 [2393] sweep-F14(2026-08-03 全窗复审)**补理由**(裁定:留在公面,不撤回):同一条 P2「I 族」
+// 裁定抽出的三个内部叶里,`envFlag.ts` 明确不出 barrel、`abortableSleep.ts` 明确撤回(见下方两处
+// 说明),只有 `unrefTimer` 在公面上而没写为什么 —— 复审点名的正是这处「同级三件、两撤一留、留的
+// 那个无理由」。理由(补记,不是事后合理化):
+//   ① 它与另两件**不同级**:另两件是纯包内实现叶(消费者全在包内,门也改吃 dist 单文件);
+//      `unrefTimer` 守的是**跨宿主可移植性不变量**(「浏览器/桌面渲染进程没有 unref 也不炸」),
+//      而定时器是宿主自己也会建的东西 —— 三端宿主(cli/web/desktop)自建保活定时器时需要同一份
+//      判断,让它们各写各的 `(t as any).unref?.()` 正是本函数收编掉的那五份手抄的来源。
+//   ② 它已经在 `public-export-baseline.json` 里(0.14.0 起随包发出),撤回 = 公面 BREAKING;
+//      而①说明它本就该公开 ⇒ 没有为一个「本该公开的东西」付破坏性代价的理由。
 export * from './unrefTimer.js';
 // REF-CC-141 dup-02(wave1 卡B,2026-08-01):envFlag.ts 是十处 SEMA_* 布尔 env 旋钮拼写集
 // 单源叶模块,但只被十个已在闭包里的模块值级 import 消费,不需要经 barrel 发到 npm 公面
@@ -324,6 +334,19 @@ export * from './agentSession/backgroundView.js';
 // 🔴 绝不半解析:schemaVersion 超区间/任一行形状坏 ⇒ 整份弃用走兜底(端渲「内置版本(离线)」
 //    靠 `source` + `online.reason`,所以「静默用兜底」在本层是可观测的)。
 export * from './model/catalog.js';
+// ── design/166(2026-08-04):目录客户端消费链 —— 候选链 loader + 供应商凭证双轨 seam ──────────
+// 🔴 `model/catalogLoader.ts` 是 catalog.ts 的**宿主面**,不是第二个解析器:候选链遍历 +
+//    传输硬门(https + 域白名单,**重定向目标过同一道门**)+ `catalog.sha256` 旁签 + 缓存信封,
+//    载荷判决(schemaVersion/逐行形状/整份弃)全部委托 `resolveModelCatalog`,一行不重写。
+// 🔴 缓存**落盘**走注入口 `CatalogCachePort`(本包 index 闭包零 Node 内建是机械门守着的硬法;
+//    tmp+rename 的原子性是实现方的契约,参考实现在 catalogLoader.ts 的类型注释里)。
+export * from './model/catalogLoader.js';
+// 🔴 `model/providerAuth.ts` 与 registry SSO(cloudAuth)**物理分文件、零共享代码**
+//    ([reuse-single-sso-no-parallel-auth]:它是模型供应商凭证轨,不是 sema 登录轨)。
+//    `DEVICE_AUTH_PROVIDERS` 今天是**空表**(宁空勿假:没有我们自己名下的 client_id 之前,
+//    填别的编辑器插件的 app id = 冒用,与 §6 判 C 档出局同一条判据),因此
+//    `supportsDeviceCodeAuth` 对每一家如实返回 false、UI 不显示该选项 —— 注册一家 = 加一行。
+export * from './model/providerAuth.js';
 // ── 搜索 provider 目录 + 地域预选(2026-07-31)──────────────────────────────────────────────────
 // `websearch/searchProviderPresets` = model 目录的**同形不同表**姊妹件:数据在 json、类型与查询
 // 在 ts。它编译出来的不是模型目录而是**引擎部署 env**(`WEB_SEARCH_*`)。

package/dist/interactiveToolsWire.d.ts

@@ -19,7 +19,12 @@
  *   · SEMA_HEADLESS_INTERACTIVE_TOOLS 部署旋钮(settings env 车道,拼写集 = envFlagOn/envFlagOff、
  *     REF-CC-141 dup-02 单源):真值拼写 = 不 stamp(回引擎缺省判据),假值拼写 = 显式 stamp false
  *     (与缺省同效,显式垫);非法值一次性 warn + 回缺省;
- *   · 缺省 = stamp false(无人值守正解);
+ *     🔴 [2393] sweep-F9(2026-08-03 全窗复审)**记一笔默认翻面**:dup-02 单源化把真值拼写集从
+ *     `{true,1}` 扩到 `{true,1,yes,on}`(假值集同批扩到 `{false,0,no,off,none}`)。收编**前**
+ *     `SEMA_HEADLESS_INTERACTIVE_TOOLS=yes` 落进 warn 分支 ⇒ `{interactiveTools:false}` = **显式 OFF**;
+ *     收编**后**它命中真值拼写 ⇒ `{}` = **不 stamp = 由引擎缺省决定**。方向说得通(用户写 yes 就是
+ *     要交互工具),但这是 headless `-p` 车道上一次真实的默认翻面,不能只活在拼写集的 diff 里。
+ *   · 缺省(env 缺席/空串)= stamp false(无人值守正解);
  *   · 旧 server 白名单 fail-soft:server resolveSpec 逐字段白名单拼 TaskSpec,未知 body 字段静默
  *     忽略(limits wire 同款勘察结论)——本字段发了白发不炸。gap-check 实拆 server 1.210.0 dist:
  *     resolveSpec(main.js:1233-)【不】读 body.interactiveTools ⇒ 需 server 半场补一行白名单,

package/dist/interactiveToolsWire.js

@@ -19,7 +19,12 @@
  *   · SEMA_HEADLESS_INTERACTIVE_TOOLS 部署旋钮(settings env 车道,拼写集 = envFlagOn/envFlagOff、
  *     REF-CC-141 dup-02 单源):真值拼写 = 不 stamp(回引擎缺省判据),假值拼写 = 显式 stamp false
  *     (与缺省同效,显式垫);非法值一次性 warn + 回缺省;
- *   · 缺省 = stamp false(无人值守正解);
+ *     🔴 [2393] sweep-F9(2026-08-03 全窗复审)**记一笔默认翻面**:dup-02 单源化把真值拼写集从
+ *     `{true,1}` 扩到 `{true,1,yes,on}`(假值集同批扩到 `{false,0,no,off,none}`)。收编**前**
+ *     `SEMA_HEADLESS_INTERACTIVE_TOOLS=yes` 落进 warn 分支 ⇒ `{interactiveTools:false}` = **显式 OFF**;
+ *     收编**后**它命中真值拼写 ⇒ `{}` = **不 stamp = 由引擎缺省决定**。方向说得通(用户写 yes 就是
+ *     要交互工具),但这是 headless `-p` 车道上一次真实的默认翻面,不能只活在拼写集的 diff 里。
+ *   · 缺省(env 缺席/空串)= stamp false(无人值守正解);
  *   · 旧 server 白名单 fail-soft:server resolveSpec 逐字段白名单拼 TaskSpec,未知 body 字段静默
  *     忽略(limits wire 同款勘察结论)——本字段发了白发不炸。gap-check 实拆 server 1.210.0 dist:
  *     resolveSpec(main.js:1233-)【不】读 body.interactiveTools ⇒ 需 server 半场补一行白名单,

package/dist/limitsWire.d.ts

@@ -1,28 +1,49 @@
 /**
- * src/sema/limitsWire.ts — headless `-p` run-limits wire (TB2.0 反馈批 E · P2-3-b, 2026-07-15):
- * expose the engine's REQUEST-LEVEL pacing limits on the headless `-p` path via `TaskRequest.limits`.
- * The server accepts `limits:{timeoutSec?,maxOutputTokens?,maxTurns?}` since 1.196.0 (positive-integer
- * 400 gate, board [857]) and feeds the EXISTING pacing machinery (deadlineNudge / callCapByDeadline /
- * gracefulFinalize) — the shell simply never stamped the field. This module is the CLI face.
+ * src/limitsWire.ts — headless `-p` run-limits wire: expose the engine's TASK-LEVEL budget face on
+ * the headless `-p` path via `TaskRequest.limits`.
  *
- * TWO FLAGS, TWO ALIGNMENT BUCKETS:
- *  · `--deadline <sec>`   → limits.timeoutSec. Upstream CC 2.1.207 has NO deadline flag (nearest kin:
- *    --max-turns / --task-budget / --max-budget-usd) → SUPERSET, help copy says so.
+ * ── core 5.8.0 词表迁移(黑板 [2489],2026-08-04)────────────────────────────────────────────
+ * `limits` 是**唯一预算面,默认全空 = 无限制**。本模块拼的三个键都骑 5.8.0 的新词表:
+ *   · `maxWalltimeMs`(**毫秒**;5.7 的 `limits.timeoutSec` 已删,单位一并变)
+ *   · `maxTurns`
+ *   · `maxTokens`(5.8.0 的**主限**——time 退出任务轴之后,token 是首选的预算旋钮)
+ * 到限语义也换了:**没有配速机器了**。5.8.0 删掉了 deadlineNudge / callCapByDeadline /
+ * gracefulFinalize 那一套(以及引擎侧 1000 轮安全网、fork 200、session-bg 30min 暗注等全部隐式
+ * 默认),走到 `maxWalltimeMs` 不再是「引擎自己减速然后优雅收尾」,而是**响亮终局**:
+ * `status:'failed'` + `errorCode:'limits.max_walltime_exceeded'`(`status:'timeout'` 这个词整体退役)。
+ * 四个新码 `limits.max_{tokens,cost,turns,walltime}_exceeded` 的下游投影见
+ * `adapter/downstream/terminalToSdkResult.ts`。
+ *
+ * ✅ **窗口期已关闭(退役批,2026-08-04)**:交付时点壳的引擎是 server 5.14.0(捆 core 5.7),它
+ * **不认识** `maxWalltimeMs`/`maxTokens`(5.7 只认 `timeoutSec`/`maxOutputTokens`/`maxTurns`,未知键
+ * 静默丢弃),所以那段时间三个键里只有 `maxTurns` 真的生效。**server 6.0.0 已捆 core 5.8.0 发车**
+ * ⇒ 新键集在班车上生效,读面的双代兜底(`adapter/downstream/terminalToSdkResult.ts`)本批一并退役。
+ * 写面从头到尾是**单一新形**,不做两代并发(同时发 `timeoutSec` + `maxWalltimeMs` 会在 5.8 引擎上撞
+ * `config.limit_unknown_key` 当场失败,那是拿窗口期的一次静默无视换班车到货后的确定性失败)。
+ *
+ * THREE FLAGS, THREE ALIGNMENT BUCKETS:
+ *  · `--deadline <sec>`   → limits.maxWalltimeMs(用户面仍是**秒**,拼 wire 时 ×1000)。Upstream
+ *    CC 2.1.207 has NO deadline flag → SUPERSET, help copy says so.
  *  · `--max-turns <n>`    → limits.maxTurns. Upstream CC 2.1.207 HAS `--max-turns` (source 199676 /
  *    793380) → ALIGNMENT-GAP fill: the flag was already registered (main.tsx CC-inherited surface) and
  *    drove the local query loop, but the seam path executes turns ENGINE-side — this wire finally
  *    carries the cap to where the turns actually run.
+ *  · `--max-tokens <n>`   → limits.maxTokens(5.8.0 主推键)。Upstream CC 2.1.207 has no run-level
+ *    token budget flag → SUPERSET.
  *
  * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
  *  a) explicit flag                                   → strict validation, FAIL-LOUD on an invalid
- *     value (integer domain below; a mis-typed pacing bound must not quietly run unbounded).
+ *     value (integer domain below; a mis-typed budget bound must not quietly run unbounded).
  *  b) settings env lane (settings.json `env` block → 1a-envseed → process.env):
- *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` → SILENT degrade on an invalid value
- *     (spec'd 静默降级 — a settings typo must never brick every headless run; unlike scenarioWire we
- *     don't even warn, per the batch-E triage shape. SEMA_DEBUG surfaces the drop for diagnosis).
+ *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` / `SEMA_HEADLESS_MAX_TOKENS`
+ *     → SILENT degrade on an invalid value (spec'd 静默降级 — a settings typo must never brick every
+ *     headless run; unlike scenarioWire we don't even warn, per the batch-E triage shape. SEMA_DEBUG
+ *     surfaces the drop for diagnosis).
  *  c) neither                                          → NO stamp = today's behaviour, verbatim.
  *
- * DOMAINS (integer, inclusive): timeoutSec 30..86400 · maxTurns 1..1000.
+ * DOMAINS (integer, inclusive): deadline 30..86400 **秒**(→ 30_000..86_400_000 ms 上 wire)·
+ * maxTurns / maxTokens = **正整数**(上界 = JS 安全整数)。maxTurns 此前钉 1..1000,那个上界抄的是
+ * 引擎侧 1000 轮安全网;5.8.0 把该安全网整体退役了,壳再替它守一个不存在的墙就是凭空拒绝合法配置。
  *
  * VERSION GATE (triage risk ③ — an OLD server SILENTLY SWALLOWS unknown body fields, worse than not
  * shipping): the self-spawned engine is release-pinned ≥1.197.0 so the dev/release lanes are safe by
@@ -31,21 +52,53 @@
  * probes `${baseUrl}/health` (the engine self-describes `version` since 1.96) and prints ONE honest
  * stderr line when version <1.196.0 — the request still goes out unchanged (warn, don't block).
  * Unreachable /health or an unparsable version stays silent (can't confirm staleness — fail-soft).
+ *
+ * 📐 **两道地板,守的不是同一件事**(退役批补记,2026-08-04):
+ *   · 第一地板 `LIMITS_WIRE_MIN_ENGINE = 1.196.0` = 「`limits` 这个**字段**存不存在」(server 1.196.0
+ *     起接受 body.limits);低于它,整个预算面被丢。
+ *   · 第二地板 **server ≥ 6.0.0** = 「**新键集**认不认」。6.0.0 是第一个捆 core 5.8.0 的 server 版本,
+ *     也就是第一个认识 `maxWalltimeMs`/`maxTokens` 的版本(5.7 只认 `timeoutSec`/`maxOutputTokens`,
+ *     未知键静默丢弃 —— `config.limit_unknown_key` 那种响亮拒是 5.8.0 才有的)。所以对 1.196.0 ≤
+ *     version < 6.0.0 的引擎,`maxTurns` 生效而 `maxWalltimeMs`/`maxTokens` 会被**静默无视**。
+ *     之所以过去写不出这条:/health 自报的是 server 版本,而键名代际取决于它捆的 core 版本,当时
+ *     两者没有可从 wire 读出的映射;6.0.0 这班车把映射钉死了(6.0.0 ⇒ core ≥5.8),这条地板才成立。
+ *   · 本文件的运行期探针目前只对第一地板发声(warn, don't block);第二地板先落成契约事实写在这里,
+ *     要不要给它也配一条 stderr 提示是**行为面**决定,按宪法三问单独走,不在退役批里顺手加。
  */
 import { type EnvLike } from './hostEnv.js';
 /** Settings-lane env knobs (settings.json `env` block → 1a-envseed → process.env). */
 export declare const HEADLESS_DEADLINE_ENV = "SEMA_HEADLESS_DEADLINE_SEC";
 export declare const HEADLESS_MAX_TURNS_ENV = "SEMA_HEADLESS_MAX_TURNS";
-/** Integer domains (inclusive). timeoutSec: 30s..24h; maxTurns: 1..1000. */
+export declare const HEADLESS_MAX_TOKENS_ENV = "SEMA_HEADLESS_MAX_TOKENS";
+/** `--deadline` 的**用户面**整数域(秒;30s..24h)。上 wire 前 ×1000 换成 `maxWalltimeMs`。 */
 export declare const DEADLINE_SEC_MIN = 30;
 export declare const DEADLINE_SEC_MAX = 86400;
+/**
+ * `maxTurns` / `maxTokens` 的整数域 = **正整数**(上界只到 JS 安全整数,再大就不是「一个精确的
+ * 轮数/token 数」而是浮点近似了 —— 那种值静默夹取比拒绝更坏)。
+ *
+ * `MAX_TURNS_MAX` 此前是 `1_000`,抄的是引擎侧的 1000 轮安全网;core 5.8.0 把那张网**整体退役**
+ * (「零配置任务现在没有任何任务级兜底」,[2489]),壳再守它 = 替一堵不存在的墙拒绝合法配置。
+ * 常量名保留(它仍然是这个域的上界,只是值换成了真上界),消费者的 help 文案请按「正整数」写。
+ */
 export declare const MAX_TURNS_MIN = 1;
-export declare const MAX_TURNS_MAX = 1000;
+export declare const MAX_TURNS_MAX: number;
+export declare const MAX_TOKENS_MIN = 1;
+export declare const MAX_TOKENS_MAX: number;
 /** First server version whose /v1/tasks|/v1/tasks/stream accept body.limits (board [857]). */
 export declare const LIMITS_WIRE_MIN_ENGINE: readonly [number, number, number];
+/**
+ * `TaskRequest.limits` 的壳侧子集(core 5.8.0 词表)。引擎那份还有
+ * `maxCostUsd`/`maxOutputTokens`/`approachNotice`/`degrade`/… —— 本模块只拼 CLI flag 暴露的三个键,
+ * 其余键由别的配置面负责,别在这里悄悄补默认值(默认全空 = 无限制,是 5.8.0 的显式设计)。
+ */
 export interface HeadlessLimits {
-    timeoutSec?: number;
+    /** 墙钟预算,**毫秒**(用户面 `--deadline` 是秒)。到限 ⇒ failed + `limits.max_walltime_exceeded`。 */
+    maxWalltimeMs?: number;
+    /** 轮数预算。到限 ⇒ failed + `limits.max_turns_exceeded`。 */
     maxTurns?: number;
+    /** token 预算(5.8.0 主限)。到限 ⇒ failed + `limits.max_tokens_exceeded`(result 带已产出正文)。 */
+    maxTokens?: number;
 }
 export type LimitsParseResult = {
     ok: true;
@@ -56,22 +109,23 @@ export type LimitsParseResult = {
     error: string;
 };
 /**
- * Parse `--deadline` + `--max-turns` out of an argv slice. No flags ⇒ `{ok:true}` with no limits.
- * Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer / out-of-domain ⇒
- * fail-LOUD parse error (never a silent default — same stance as `--scenario`/`--sandbox`).
- * `flaggedFlags` names the flags that EXPLICITLY contributed (the version-gate probe trigger).
+ * Parse `--deadline` + `--max-turns` + `--max-tokens` out of an argv slice. No flags ⇒ `{ok:true}`
+ * with no limits. Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer /
+ * out-of-domain ⇒ fail-LOUD parse error (never a silent default — same stance as
+ * `--scenario`/`--sandbox`). `flaggedFlags` names the flags that EXPLICITLY contributed (the
+ * version-gate probe trigger).
  */
 export declare function parseLimitsArgv(argv: string[]): LimitsParseResult;
 /**
  * The settings-lane defaults. SILENT degrade on a bad value (batch-E triage shape — stricter than
- * scenarioWire's warn-and-ignore: these are pacing hints, and a settings typo must neither brick nor
- * spam every headless run). SEMA_DEBUG surfaces the drop.
+ * scenarioWire's warn-and-ignore: a settings typo must neither brick nor spam every headless run).
+ * SEMA_DEBUG surfaces the drop.
  */
 export declare function headlessLimitsFromEnv(env?: EnvLike): HeadlessLimits | undefined;
 /**
  * Resolve the limits for a headless `-p` submit: explicit flags > settings env defaults > none
  * (= no stamp, today's behaviour). Merge is PER-KNOB: `--deadline 300` + SEMA_HEADLESS_MAX_TURNS=50
- * yields {timeoutSec:300, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
+ * yields {maxWalltimeMs:300000, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
  */
 export declare function limitsForPrint(argv: string[], env?: EnvLike): LimitsParseResult;
 /** True when the engine version string satisfies the limits-wire minimum (≥1.196.0). Unparsable ⇒ false. */

package/dist/limitsWire.js

@@ -1,28 +1,49 @@
 /**
- * src/sema/limitsWire.ts — headless `-p` run-limits wire (TB2.0 反馈批 E · P2-3-b, 2026-07-15):
- * expose the engine's REQUEST-LEVEL pacing limits on the headless `-p` path via `TaskRequest.limits`.
- * The server accepts `limits:{timeoutSec?,maxOutputTokens?,maxTurns?}` since 1.196.0 (positive-integer
- * 400 gate, board [857]) and feeds the EXISTING pacing machinery (deadlineNudge / callCapByDeadline /
- * gracefulFinalize) — the shell simply never stamped the field. This module is the CLI face.
+ * src/limitsWire.ts — headless `-p` run-limits wire: expose the engine's TASK-LEVEL budget face on
+ * the headless `-p` path via `TaskRequest.limits`.
  *
- * TWO FLAGS, TWO ALIGNMENT BUCKETS:
- *  · `--deadline <sec>`   → limits.timeoutSec. Upstream CC 2.1.207 has NO deadline flag (nearest kin:
- *    --max-turns / --task-budget / --max-budget-usd) → SUPERSET, help copy says so.
+ * ── core 5.8.0 词表迁移(黑板 [2489],2026-08-04)────────────────────────────────────────────
+ * `limits` 是**唯一预算面,默认全空 = 无限制**。本模块拼的三个键都骑 5.8.0 的新词表:
+ *   · `maxWalltimeMs`(**毫秒**;5.7 的 `limits.timeoutSec` 已删,单位一并变)
+ *   · `maxTurns`
+ *   · `maxTokens`(5.8.0 的**主限**——time 退出任务轴之后,token 是首选的预算旋钮)
+ * 到限语义也换了:**没有配速机器了**。5.8.0 删掉了 deadlineNudge / callCapByDeadline /
+ * gracefulFinalize 那一套(以及引擎侧 1000 轮安全网、fork 200、session-bg 30min 暗注等全部隐式
+ * 默认),走到 `maxWalltimeMs` 不再是「引擎自己减速然后优雅收尾」,而是**响亮终局**:
+ * `status:'failed'` + `errorCode:'limits.max_walltime_exceeded'`(`status:'timeout'` 这个词整体退役)。
+ * 四个新码 `limits.max_{tokens,cost,turns,walltime}_exceeded` 的下游投影见
+ * `adapter/downstream/terminalToSdkResult.ts`。
+ *
+ * ✅ **窗口期已关闭(退役批,2026-08-04)**:交付时点壳的引擎是 server 5.14.0(捆 core 5.7),它
+ * **不认识** `maxWalltimeMs`/`maxTokens`(5.7 只认 `timeoutSec`/`maxOutputTokens`/`maxTurns`,未知键
+ * 静默丢弃),所以那段时间三个键里只有 `maxTurns` 真的生效。**server 6.0.0 已捆 core 5.8.0 发车**
+ * ⇒ 新键集在班车上生效,读面的双代兜底(`adapter/downstream/terminalToSdkResult.ts`)本批一并退役。
+ * 写面从头到尾是**单一新形**,不做两代并发(同时发 `timeoutSec` + `maxWalltimeMs` 会在 5.8 引擎上撞
+ * `config.limit_unknown_key` 当场失败,那是拿窗口期的一次静默无视换班车到货后的确定性失败)。
+ *
+ * THREE FLAGS, THREE ALIGNMENT BUCKETS:
+ *  · `--deadline <sec>`   → limits.maxWalltimeMs(用户面仍是**秒**,拼 wire 时 ×1000)。Upstream
+ *    CC 2.1.207 has NO deadline flag → SUPERSET, help copy says so.
  *  · `--max-turns <n>`    → limits.maxTurns. Upstream CC 2.1.207 HAS `--max-turns` (source 199676 /
  *    793380) → ALIGNMENT-GAP fill: the flag was already registered (main.tsx CC-inherited surface) and
  *    drove the local query loop, but the seam path executes turns ENGINE-side — this wire finally
  *    carries the cap to where the turns actually run.
+ *  · `--max-tokens <n>`   → limits.maxTokens(5.8.0 主推键)。Upstream CC 2.1.207 has no run-level
+ *    token budget flag → SUPERSET.
  *
  * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
  *  a) explicit flag                                   → strict validation, FAIL-LOUD on an invalid
- *     value (integer domain below; a mis-typed pacing bound must not quietly run unbounded).
+ *     value (integer domain below; a mis-typed budget bound must not quietly run unbounded).
  *  b) settings env lane (settings.json `env` block → 1a-envseed → process.env):
- *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` → SILENT degrade on an invalid value
- *     (spec'd 静默降级 — a settings typo must never brick every headless run; unlike scenarioWire we
- *     don't even warn, per the batch-E triage shape. SEMA_DEBUG surfaces the drop for diagnosis).
+ *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` / `SEMA_HEADLESS_MAX_TOKENS`
+ *     → SILENT degrade on an invalid value (spec'd 静默降级 — a settings typo must never brick every
+ *     headless run; unlike scenarioWire we don't even warn, per the batch-E triage shape. SEMA_DEBUG
+ *     surfaces the drop for diagnosis).
  *  c) neither                                          → NO stamp = today's behaviour, verbatim.
  *
- * DOMAINS (integer, inclusive): timeoutSec 30..86400 · maxTurns 1..1000.
+ * DOMAINS (integer, inclusive): deadline 30..86400 **秒**(→ 30_000..86_400_000 ms 上 wire)·
+ * maxTurns / maxTokens = **正整数**(上界 = JS 安全整数)。maxTurns 此前钉 1..1000,那个上界抄的是
+ * 引擎侧 1000 轮安全网;5.8.0 把该安全网整体退役了,壳再替它守一个不存在的墙就是凭空拒绝合法配置。
  *
  * VERSION GATE (triage risk ③ — an OLD server SILENTLY SWALLOWS unknown body fields, worse than not
  * shipping): the self-spawned engine is release-pinned ≥1.197.0 so the dev/release lanes are safe by
@@ -31,34 +52,63 @@
  * probes `${baseUrl}/health` (the engine self-describes `version` since 1.96) and prints ONE honest
  * stderr line when version <1.196.0 — the request still goes out unchanged (warn, don't block).
  * Unreachable /health or an unparsable version stays silent (can't confirm staleness — fail-soft).
+ *
+ * 📐 **两道地板,守的不是同一件事**(退役批补记,2026-08-04):
+ *   · 第一地板 `LIMITS_WIRE_MIN_ENGINE = 1.196.0` = 「`limits` 这个**字段**存不存在」(server 1.196.0
+ *     起接受 body.limits);低于它,整个预算面被丢。
+ *   · 第二地板 **server ≥ 6.0.0** = 「**新键集**认不认」。6.0.0 是第一个捆 core 5.8.0 的 server 版本,
+ *     也就是第一个认识 `maxWalltimeMs`/`maxTokens` 的版本(5.7 只认 `timeoutSec`/`maxOutputTokens`,
+ *     未知键静默丢弃 —— `config.limit_unknown_key` 那种响亮拒是 5.8.0 才有的)。所以对 1.196.0 ≤
+ *     version < 6.0.0 的引擎,`maxTurns` 生效而 `maxWalltimeMs`/`maxTokens` 会被**静默无视**。
+ *     之所以过去写不出这条:/health 自报的是 server 版本,而键名代际取决于它捆的 core 版本,当时
+ *     两者没有可从 wire 读出的映射;6.0.0 这班车把映射钉死了(6.0.0 ⇒ core ≥5.8),这条地板才成立。
+ *   · 本文件的运行期探针目前只对第一地板发声(warn, don't block);第二地板先落成契约事实写在这里,
+ *     要不要给它也配一条 stderr 提示是**行为面**决定,按宪法三问单独走,不在退役批里顺手加。
  */
 import { hostEnv } from './hostEnv.js';
 import { lastFlagValue } from './argvFlagValue.js';
 /** Settings-lane env knobs (settings.json `env` block → 1a-envseed → process.env). */
 export const HEADLESS_DEADLINE_ENV = 'SEMA_HEADLESS_DEADLINE_SEC';
 export const HEADLESS_MAX_TURNS_ENV = 'SEMA_HEADLESS_MAX_TURNS';
-/** Integer domains (inclusive). timeoutSec: 30s..24h; maxTurns: 1..1000. */
+export const HEADLESS_MAX_TOKENS_ENV = 'SEMA_HEADLESS_MAX_TOKENS';
+/** `--deadline` 的**用户面**整数域(秒;30s..24h)。上 wire 前 ×1000 换成 `maxWalltimeMs`。 */
 export const DEADLINE_SEC_MIN = 30;
 export const DEADLINE_SEC_MAX = 86_400;
+/**
+ * `maxTurns` / `maxTokens` 的整数域 = **正整数**(上界只到 JS 安全整数,再大就不是「一个精确的
+ * 轮数/token 数」而是浮点近似了 —— 那种值静默夹取比拒绝更坏)。
+ *
+ * `MAX_TURNS_MAX` 此前是 `1_000`,抄的是引擎侧的 1000 轮安全网;core 5.8.0 把那张网**整体退役**
+ * (「零配置任务现在没有任何任务级兜底」,[2489]),壳再守它 = 替一堵不存在的墙拒绝合法配置。
+ * 常量名保留(它仍然是这个域的上界,只是值换成了真上界),消费者的 help 文案请按「正整数」写。
+ */
 export const MAX_TURNS_MIN = 1;
-export const MAX_TURNS_MAX = 1_000;
+export const MAX_TURNS_MAX = Number.MAX_SAFE_INTEGER;
+export const MAX_TOKENS_MIN = 1;
+export const MAX_TOKENS_MAX = Number.MAX_SAFE_INTEGER;
+/** 用户面秒 → wire 毫秒(core 5.8.0 `limits.maxWalltimeMs` 的单位)。 */
+const SEC_TO_MS = 1_000;
 /** First server version whose /v1/tasks|/v1/tasks/stream accept body.limits (board [857]). */
 export const LIMITS_WIRE_MIN_ENGINE = [1, 196, 0];
 const DEADLINE_USAGE = `sema: --deadline expects a whole number of seconds between ${DEADLINE_SEC_MIN} and ${DEADLINE_SEC_MAX}.\n` +
-    '  --deadline <sec>     soft wall-clock budget for this run (sema superset — no upstream equivalent):\n' +
-    '                       the engine paces itself (nudges + call caps) and finalizes gracefully near the deadline\n' +
-    '  (no flag)            no deadline — today\'s behaviour';
-const MAX_TURNS_USAGE = `sema: --max-turns expects a whole number of turns between ${MAX_TURNS_MIN} and ${MAX_TURNS_MAX}.\n` +
+    '  --deadline <sec>     wall-clock budget for this run (sema superset — no upstream equivalent):\n' +
+    '                       reaching it ends the run LOUDLY (failed / limits.max_walltime_exceeded)\n' +
+    '  (no flag)            no wall-clock budget — today\'s behaviour';
+const MAX_TURNS_USAGE = 'sema: --max-turns expects a positive whole number of turns.\n' +
     '  --max-turns <n>      maximum number of agentic turns for this run (upstream-aligned flag,\n' +
     '                       enforced engine-side on the sema seam)\n' +
     '  (no flag)            no turn cap — today\'s behaviour';
+const MAX_TOKENS_USAGE = 'sema: --max-tokens expects a positive whole number of tokens.\n' +
+    '  --max-tokens <n>     token budget for this run (sema superset — no upstream equivalent;\n' +
+    '                       the engine\'s primary run-level budget knob since core 5.8.0)\n' +
+    '  (no flag)            no token budget — today\'s behaviour';
 /** STRICT integer shape for explicit flag values: ASCII digits only (no sign/decimal/exponent/space). */
 const INT_RE = /^\d+$/;
 // `lastFlagValue` (the `--name <v>`/`--name=<v>`/repeated-flag-last-wins scan) now lives in
 // argvFlagValue.ts (REF-CC-143/dup-07, P3 wave1 卡C-argv, 2026-08-01) — this was the fullest of five
 // hand-rolled copies (present/raw/valueMissing three-state) and is the one the shared leaf was cribbed
-// from verbatim; see that file's header for the shared 缺值 contract. `--deadline`/`--max-turns` are
-// both all-positive domains, so a NEGATIVE number (which looks flag-shaped to the scanner) correctly
+// from verbatim; see that file's header for the shared 缺值 contract. All three flags are
+// all-positive domains, so a NEGATIVE number (which looks flag-shaped to the scanner) correctly
 // falls into the same fail-loud usage-hint path as a genuinely missing value below.
 /** Validate a RAW flag value against an inclusive integer domain. Returns the number or null. */
 function parseIntInDomain(raw, min, max) {
@@ -70,11 +120,16 @@ function parseIntInDomain(raw, min, max) {
         return null;
     return n;
 }
+/** 三个键任一在场 ⇒ 值得 stamp(空对象绝不上 wire —— 那是「配了个空预算」不是「没配」)。 */
+function hasAnyLimit(l) {
+    return l.maxWalltimeMs !== undefined || l.maxTurns !== undefined || l.maxTokens !== undefined;
+}
 /**
- * Parse `--deadline` + `--max-turns` out of an argv slice. No flags ⇒ `{ok:true}` with no limits.
- * Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer / out-of-domain ⇒
- * fail-LOUD parse error (never a silent default — same stance as `--scenario`/`--sandbox`).
- * `flaggedFlags` names the flags that EXPLICITLY contributed (the version-gate probe trigger).
+ * Parse `--deadline` + `--max-turns` + `--max-tokens` out of an argv slice. No flags ⇒ `{ok:true}`
+ * with no limits. Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer /
+ * out-of-domain ⇒ fail-LOUD parse error (never a silent default — same stance as
+ * `--scenario`/`--sandbox`). `flaggedFlags` names the flags that EXPLICITLY contributed (the
+ * version-gate probe trigger).
  */
 export function parseLimitsArgv(argv) {
     const limits = {};
@@ -84,7 +139,8 @@ export function parseLimitsArgv(argv) {
         const n = dl.raw !== undefined ? parseIntInDomain(dl.raw, DEADLINE_SEC_MIN, DEADLINE_SEC_MAX) : null;
         if (n === null)
             return { ok: false, error: DEADLINE_USAGE };
-        limits.timeoutSec = n;
+        // 用户面是秒,wire 面是毫秒(core 5.8.0 `maxWalltimeMs`)—— 换算只在这一个方向、这一个点做。
+        limits.maxWalltimeMs = n * SEC_TO_MS;
         flaggedFlags.push('--deadline');
     }
     const mt = lastFlagValue(argv, '--max-turns');
@@ -95,6 +151,14 @@ export function parseLimitsArgv(argv) {
         limits.maxTurns = n;
         flaggedFlags.push('--max-turns');
     }
+    const mk = lastFlagValue(argv, '--max-tokens');
+    if (mk.present) {
+        const n = mk.raw !== undefined ? parseIntInDomain(mk.raw, MAX_TOKENS_MIN, MAX_TOKENS_MAX) : null;
+        if (n === null)
+            return { ok: false, error: MAX_TOKENS_USAGE };
+        limits.maxTokens = n;
+        flaggedFlags.push('--max-tokens');
+    }
     return {
         ok: true,
         ...(flaggedFlags.length > 0 ? { limits } : {}),
@@ -103,8 +167,8 @@ export function parseLimitsArgv(argv) {
 }
 /**
  * The settings-lane defaults. SILENT degrade on a bad value (batch-E triage shape — stricter than
- * scenarioWire's warn-and-ignore: these are pacing hints, and a settings typo must neither brick nor
- * spam every headless run). SEMA_DEBUG surfaces the drop.
+ * scenarioWire's warn-and-ignore: a settings typo must neither brick nor spam every headless run).
+ * SEMA_DEBUG surfaces the drop.
  */
 export function headlessLimitsFromEnv(env = hostEnv()) {
     const out = {};
@@ -112,7 +176,7 @@ export function headlessLimitsFromEnv(env = hostEnv()) {
     if (dl) {
         const n = parseIntInDomain(dl, DEADLINE_SEC_MIN, DEADLINE_SEC_MAX);
         if (n !== null)
-            out.timeoutSec = n;
+            out.maxWalltimeMs = n * SEC_TO_MS; // env 面同样是秒(变量名带 _SEC),换算同一口
         else if (env.SEMA_DEBUG) {
             // eslint-disable-next-line no-console
             console.error(`[sema] ${HEADLESS_DEADLINE_ENV}="${dl}" is not an integer in ${DEADLINE_SEC_MIN}..${DEADLINE_SEC_MAX} — ignoring the settings default`);
@@ -125,15 +189,25 @@ export function headlessLimitsFromEnv(env = hostEnv()) {
             out.maxTurns = n;
         else if (env.SEMA_DEBUG) {
             // eslint-disable-next-line no-console
-            console.error(`[sema] ${HEADLESS_MAX_TURNS_ENV}="${mt}" is not an integer in ${MAX_TURNS_MIN}..${MAX_TURNS_MAX} — ignoring the settings default`);
+            console.error(`[sema] ${HEADLESS_MAX_TURNS_ENV}="${mt}" is not a positive integer — ignoring the settings default`);
+        }
+    }
+    const mk = env[HEADLESS_MAX_TOKENS_ENV]?.trim();
+    if (mk) {
+        const n = parseIntInDomain(mk, MAX_TOKENS_MIN, MAX_TOKENS_MAX);
+        if (n !== null)
+            out.maxTokens = n;
+        else if (env.SEMA_DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error(`[sema] ${HEADLESS_MAX_TOKENS_ENV}="${mk}" is not a positive integer — ignoring the settings default`);
         }
     }
-    return out.timeoutSec !== undefined || out.maxTurns !== undefined ? out : undefined;
+    return hasAnyLimit(out) ? out : undefined;
 }
 /**
  * Resolve the limits for a headless `-p` submit: explicit flags > settings env defaults > none
  * (= no stamp, today's behaviour). Merge is PER-KNOB: `--deadline 300` + SEMA_HEADLESS_MAX_TURNS=50
- * yields {timeoutSec:300, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
+ * yields {maxWalltimeMs:300000, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
  */
 export function limitsForPrint(argv, env = hostEnv()) {
     const parsed = parseLimitsArgv(argv);
@@ -141,8 +215,7 @@ export function limitsForPrint(argv, env = hostEnv()) {
         return parsed;
     const fromEnv = headlessLimitsFromEnv(env);
     const merged = { ...(fromEnv ?? {}), ...(parsed.limits ?? {}) };
-    const any = merged.timeoutSec !== undefined || merged.maxTurns !== undefined;
-    return { ok: true, ...(any ? { limits: merged } : {}), flaggedFlags: parsed.flaggedFlags };
+    return { ok: true, ...(hasAnyLimit(merged) ? { limits: merged } : {}), flaggedFlags: parsed.flaggedFlags };
 }
 /** True when the engine version string satisfies the limits-wire minimum (≥1.196.0). Unparsable ⇒ false. */
 export function versionSupportsLimits(v) {
@@ -180,7 +253,7 @@ export async function engineLimitsSupportWarning(baseUrl, flaggedFlags, opts) {
         // No version field = pre-1.96 engine — definitely older than 1.196.0, warn honestly.
         if (versionSupportsLimits(version))
             return undefined;
-        const flags = flaggedFlags.length > 0 ? flaggedFlags.join('/') : '--deadline/--max-turns';
+        const flags = flaggedFlags.length > 0 ? flaggedFlags.join('/') : '--deadline/--max-turns/--max-tokens';
         return `[sema] engine ${version ?? '(unversioned, pre-1.96)'} does not support ${flags} (needs ≥1.196.0); the flag will be ignored by the engine`;
     }
     catch {