@sema-agent/client-core 0.16.1 → 0.17.0

package/dist/finalVerifyWire.js

@@ -1,5 +1,5 @@
 import { hostEnv } from './hostEnv.js';
-import { envFlagOff } from './envFlag.js';
+import { envFlagOff, envFlagOn } from './envFlag.js';
 /** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。'false'/'0' = off。 */
 export const HEADLESS_FINAL_VERIFY_ENV = 'SEMA_HEADLESS_FINAL_VERIFY';
 /**
@@ -15,6 +15,20 @@ export function parseNoFinalVerifyArgv(argv) {
     }
     return false;
 }
+/**
+ * Parse the explicit opt-in `--final-verify` out of an argv slice(同 `--no-final-verify` 的扫描
+ * 纪律:bare `--` 后是 positionals)。默认关时代的唯一 flag 开口;`--no-final-verify` 恒赢它
+ * (off 优先纪律)。壳侧 commander 需在 0.17.x 提货时注册本 flag(提货单点名)。
+ */
+export function parseFinalVerifyArgv(argv) {
+    for (const a of argv) {
+        if (a === '--')
+            break; // positionals — never flags
+        if (a === '--final-verify')
+            return true;
+    }
+    return false;
+}
 /**
  * The settings-lane off-switch:`SEMA_HEADLESS_FINAL_VERIFY` 设成 {@link envFlagOff} 拼写集
  * (REF-CC-141 dup-02 单源:`0`/`false`/`no`/`off`/`none`,大小写不敏感)disables the stamp。
@@ -39,28 +53,30 @@ export function hasUserStopHook(wireHooks) {
     return Array.isArray(groups) && groups.length > 0;
 }
 /**
- * Resolve the finalVerification stamp for a headless `-p` submit:默认 true;
- * `--no-final-verify` flag / SEMA_HEADLESS_FINAL_VERIFY=false|0 / 用户 Stop hook 在场 → false。
+ * Resolve the finalVerification stamp for a headless `-p` submit:**默认 false**(clay 裁定
+ * 2026-08-04,头注案情);仅显式 `--final-verify` / env ON 拼写才可能 on,且 Stop hook 仍让位。
  * 调用点必须 live-gate(SEMA_LIVE_BASEURL)——mock/offline 形状不变。
  */
 export function resolveHeadlessFinalVerify(argv, env = hostEnv(), wireHooks) {
     return resolveHeadlessFinalVerifyDetail(argv, env, wireHooks).on;
 }
 /**
- * #106 裁 B(clay 2026-07-26):让位维持 + 诚实告知。detail 形暴露 off 原因供调用点分诊 ——
- * flag/env 关闭是用户显式意愿(不聒噪);`stop-hook` 让位是用户**没显式要求**的关闭
- * (Stop hook 可能来自 /goal 自注册或 settings hook),必须告知(修前静默,用户不知道自己
- * 失去了终验)。方向注记:finalVerification 后续默认关(CC Stop hook 机制同,不叠超集)——
- * 见记忆 final-verification-direction;届时本函数的默认臂翻转,detail 形不动。
+ * #106 裁 B(clay 2026-07-26)让位+告知维持,但默认臂已按 2026-08-04 裁定翻转(头注案情):
+ * 默认 off 且**无 offReason**(静默——没开过的东西无从让位,告知只在显式 on 被 Stop hook
+ * 压下时出现);flag/env 显式关同样不聒噪。detail 形不动(offReason 词表原样)。
  */
 export function resolveHeadlessFinalVerifyDetail(argv, env = hostEnv(), wireHooks) {
     if (parseNoFinalVerifyArgv(argv))
         return { on: false, offReason: 'flag' };
     if (headlessFinalVerifyDisabledByEnv(env))
         return { on: false, offReason: 'env' };
-    if (hasUserStopHook(wireHooks))
-        return { on: false, offReason: 'stop-hook' };
-    return { on: true };
+    const explicitOn = parseFinalVerifyArgv(argv) || envFlagOn(env[HEADLESS_FINAL_VERIFY_ENV]);
+    if (explicitOn) {
+        if (hasUserStopHook(wireHooks))
+            return { on: false, offReason: 'stop-hook' };
+        return { on: true };
+    }
+    return { on: false }; // 默认关(clay 裁定 2026-08-04):无 offReason = 静默缺省态
 }
 /**
  * stop-hook 让位的告知文案(单一措辞源;stderr 一行)。措辞纪律与 hook_notice 同族:

package/dist/index.d.ts

@@ -155,6 +155,7 @@ export * from './controlRouter.js';
 export * from './sseIdleTriage.js';
 export * from './engineWireSdk.js';
 export * from './classifierVerdictWire.js';
+export * from './engineErrorCodes.js';
 export * from './agentsWireCaps.js';
 export * from './attachmentsWireCaps.js';
 export * from './clientContextWireCaps.js';

package/dist/index.js

@@ -171,6 +171,10 @@ export * from './controlRouter.js';
 export * from './sseIdleTriage.js';
 export * from './engineWireSdk.js';
 export * from './classifierVerdictWire.js';
+// G1 去字面化(2026-08-04,core 5.10.0 / sdk 6.2.0 消费半场):引擎 `errorCode` 词表的单一真源。
+// 进公面是**有意**的(与 envFlag 那条包内叶相反):壳/web/desktop 三端都要按同一批码分臂,
+// 三端各抄一份字面正是本文件要根治的病;开集纪律与闭集唯一例外见该文件头注。
+export * from './engineErrorCodes.js';
 // caps / wire 门族(17 个 *WireCaps。B2 时 hooksWireCaps / scratchpadWireCaps 因宿主耦合未搬;
 // B4 已搬 scratchpadWireCaps(走 FsPort),hooksWireCaps 仍在壳里等 SettingsPort 接线 —— 见交接报告)
 export * from './agentsWireCaps.js';

package/dist/interactiveToolsWire.d.ts

@@ -11,6 +11,16 @@
  * 该工具)= [909]A3(headless EnterPlanMode→park 弃 86% 预算)类事故的根治,比 [884]A1 的
  * park→error 终帧防御纵深更靠前(现在根本不 park)。
  *
+ * 🆕 **core 5.10.0 把这一 stamp 的作用域从「本 run」扩到「本 run 及其全部委派子代」**
+ * ([2575] 消费端自查④,委托继承收窄五座之②):此前子代 roster 是「**恒无** AskUserQuestion」,
+ * 5.10.0 起改成「**父面允许才有**」——`onQuestion` 在 prepare 期解析一次并**原样**传给子代
+ * (父子共用同一个函数对象)。对本模块是**净收益且零改动**:`-p` stamp `false` 之后,硬 headless
+ * 父的子代**压根不挂** AskUserQuestion,而不是挂了再靠子代自己的判断兜。同族一并单向收紧的还有
+ * `handsReadOnly`(只读父 ⇒ 子代无写手)与 `oneShot`(true 向传播)。
+ * 🔴 给下一棒的判据纪律:因此**别再用闭包身份判「谁在问」** —— 父子是同一个 `onQuestion` 函数对象,
+ * 闭包身份在 5.10.0 上不再有判别力;判身要读 `AskQuestionRequest.sourceTaskId` / `principal`
+ * (本包 hitl 面已是这个姿势,见 `hitl/toolApprovalWire.ts` 的 `sourceTaskId` 位)。
+ *
  * 语义(headlessPermissionModeWire 同点同型 wire):
  *   · 仅 headless `-p` 车道(本模块只被 seamQueryEngine.ask import;交互 REPL 一根毛不动);
  *   · 显式交互意图恒赢:CLI 无 --interactive-tools 类旗(gap-check 2026-07-16:上游 CC 2.1.207

package/dist/interactiveToolsWire.js

@@ -11,6 +11,16 @@
  * 该工具)= [909]A3(headless EnterPlanMode→park 弃 86% 预算)类事故的根治,比 [884]A1 的
  * park→error 终帧防御纵深更靠前(现在根本不 park)。
  *
+ * 🆕 **core 5.10.0 把这一 stamp 的作用域从「本 run」扩到「本 run 及其全部委派子代」**
+ * ([2575] 消费端自查④,委托继承收窄五座之②):此前子代 roster 是「**恒无** AskUserQuestion」,
+ * 5.10.0 起改成「**父面允许才有**」——`onQuestion` 在 prepare 期解析一次并**原样**传给子代
+ * (父子共用同一个函数对象)。对本模块是**净收益且零改动**:`-p` stamp `false` 之后,硬 headless
+ * 父的子代**压根不挂** AskUserQuestion,而不是挂了再靠子代自己的判断兜。同族一并单向收紧的还有
+ * `handsReadOnly`(只读父 ⇒ 子代无写手)与 `oneShot`(true 向传播)。
+ * 🔴 给下一棒的判据纪律:因此**别再用闭包身份判「谁在问」** —— 父子是同一个 `onQuestion` 函数对象,
+ * 闭包身份在 5.10.0 上不再有判别力;判身要读 `AskQuestionRequest.sourceTaskId` / `principal`
+ * (本包 hitl 面已是这个姿势,见 `hitl/toolApprovalWire.ts` 的 `sourceTaskId` 位)。
+ *
  * 语义(headlessPermissionModeWire 同点同型 wire):
  *   · 仅 headless `-p` 车道(本模块只被 seamQueryEngine.ask import;交互 REPL 一根毛不动);
  *   · 显式交互意图恒赢:CLI 无 --interactive-tools 类旗(gap-check 2026-07-16:上游 CC 2.1.207

package/dist/limitsWire.d.ts

@@ -6,7 +6,8 @@
  * `limits` 是**唯一预算面,默认全空 = 无限制**。本模块拼的三个键都骑 5.8.0 的新词表:
  *   · `maxWalltimeMs`(**毫秒**;5.7 的 `limits.timeoutSec` 已删,单位一并变)
  *   · `maxTurns`
- *   · `maxTokens`(5.8.0 的**主限**——time 退出任务轴之后,token 是首选的预算旋钮)
+ *   · `maxOutputTokens`(5.8.0 的**主限**——time 退出任务轴之后,token 是首选的预算旋钮;
+ *     wire 键名自 5.7 起一直是 maxOutputTokens,core 内部才叫 maxTokens——[2569] 案订正)
  * 到限语义也换了:**没有配速机器了**。5.8.0 删掉了 deadlineNudge / callCapByDeadline /
  * gracefulFinalize 那一套(以及引擎侧 1000 轮安全网、fork 200、session-bg 30min 暗注等全部隐式
  * 默认),走到 `maxWalltimeMs` 不再是「引擎自己减速然后优雅收尾」,而是**响亮终局**:
@@ -28,7 +29,8 @@
  *    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
+ *  · `--max-tokens <n>`   → limits.maxOutputTokens(5.8.0 主限;wire 键名见接口注——绝不直发
+ *    core 内部键 maxTokens,[2569] 案)。Upstream CC 2.1.207 has no run-level
  *    token budget flag → SUPERSET.
  *
  * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
@@ -57,9 +59,10 @@
  *   · 第一地板 `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` 会被**静默无视**。
+ *     也就是第一个认识 `maxWalltimeMs` 的版本(5.7 只认 `timeoutSec`/`maxOutputTokens`/`maxTurns`,
+ *     未知键静默丢弃)。**[2569] 案订正**:`maxOutputTokens` 自 5.7 就在 wire 词表,本模块此前
+ *     直发 core 内部键 `maxTokens` 才是被静默无视的那个(server 6.3.0 起 400);对 1.196.0 ≤
+ *     version < 6.0.0 的引擎,`maxTurns`/`maxOutputTokens` 生效而 `maxWalltimeMs` 被静默无视。
  *     之所以过去写不出这条:/health 自报的是 server 版本,而键名代际取决于它捆的 core 版本,当时
  *     两者没有可从 wire 读出的映射;6.0.0 这班车把映射钉死了(6.0.0 ⇒ core ≥5.8),这条地板才成立。
  *   · 本文件的运行期探针目前只对第一地板发声(warn, don't block);第二地板先落成契约事实写在这里,
@@ -97,8 +100,12 @@ export interface HeadlessLimits {
     maxWalltimeMs?: number;
     /** 轮数预算。到限 ⇒ failed + `limits.max_turns_exceeded`。 */
     maxTurns?: number;
-    /** token 预算(5.8.0 主限)。到限 ⇒ failed + `limits.max_tokens_exceeded`(result 带已产出正文)。 */
-    maxTokens?: number;
+    /** token 预算(5.8.0 主限)。到限 ⇒ failed + `limits.max_tokens_exceeded`(result 带已产出正文)。
+     *  🔴 wire 键=**maxOutputTokens**(sdk 6.2.0 types.d.ts:472 实测词表;[2569] 案定谳):
+     *  `maxTokens` 是 core TaskSpec 内部键,server 从未从 wire 采纳它(此前 200 静默空转,
+     *  6.3.0 起对 limits.maxTokens 直接 400)。用户面 `--max-tokens`/`SEMA_HEADLESS_MAX_TOKENS`
+     *  名称不变——变的只是上 wire 的键名。[same-name-different-meaning-crosses-layers] 同族。 */
+    maxOutputTokens?: number;
 }
 export type LimitsParseResult = {
     ok: true;
@@ -117,11 +124,21 @@ export type LimitsParseResult = {
  */
 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: a settings typo must neither brick nor spam every headless run).
- * SEMA_DEBUG surfaces the drop.
+ * The settings-lane defaults. FAIL-LOUD on a bad value (#132 / test [2508],2026-08-04,推翻旧
+ * batch-E「静默降级」形):设置了 SEMA_HEADLESS_* 却是非法值时,旧行为=不开 SEMA_DEBUG 完全无声、
+ * 按「无限期限」跑——用户以为设了预算,实际什么都没设,这正是 [honest-absence] 禁的那类静默谎报。
+ * 现与 flag 路径同拍响亮拒(同文案形,caller exit 1):配置错了要在第一次跑就知道,而不是在一个
+ * 本该 300s 停的任务跑了一夜之后。返回判别联合;唯一消费者是下面的 limitsForPrint(仓际零外部
+ * 消费,干净切不设兼容)。
  */
-export declare function headlessLimitsFromEnv(env?: EnvLike): HeadlessLimits | undefined;
+export type HeadlessEnvLimitsResult = {
+    ok: true;
+    limits: HeadlessLimits | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function headlessLimitsFromEnv(env?: EnvLike): HeadlessEnvLimitsResult;
 /**
  * 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

package/dist/limitsWire.js

@@ -6,7 +6,8 @@
  * `limits` 是**唯一预算面,默认全空 = 无限制**。本模块拼的三个键都骑 5.8.0 的新词表:
  *   · `maxWalltimeMs`(**毫秒**;5.7 的 `limits.timeoutSec` 已删,单位一并变)
  *   · `maxTurns`
- *   · `maxTokens`(5.8.0 的**主限**——time 退出任务轴之后,token 是首选的预算旋钮)
+ *   · `maxOutputTokens`(5.8.0 的**主限**——time 退出任务轴之后,token 是首选的预算旋钮;
+ *     wire 键名自 5.7 起一直是 maxOutputTokens,core 内部才叫 maxTokens——[2569] 案订正)
  * 到限语义也换了:**没有配速机器了**。5.8.0 删掉了 deadlineNudge / callCapByDeadline /
  * gracefulFinalize 那一套(以及引擎侧 1000 轮安全网、fork 200、session-bg 30min 暗注等全部隐式
  * 默认),走到 `maxWalltimeMs` 不再是「引擎自己减速然后优雅收尾」,而是**响亮终局**:
@@ -28,7 +29,8 @@
  *    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
+ *  · `--max-tokens <n>`   → limits.maxOutputTokens(5.8.0 主限;wire 键名见接口注——绝不直发
+ *    core 内部键 maxTokens,[2569] 案)。Upstream CC 2.1.207 has no run-level
  *    token budget flag → SUPERSET.
  *
  * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
@@ -57,9 +59,10 @@
  *   · 第一地板 `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` 会被**静默无视**。
+ *     也就是第一个认识 `maxWalltimeMs` 的版本(5.7 只认 `timeoutSec`/`maxOutputTokens`/`maxTurns`,
+ *     未知键静默丢弃)。**[2569] 案订正**:`maxOutputTokens` 自 5.7 就在 wire 词表,本模块此前
+ *     直发 core 内部键 `maxTokens` 才是被静默无视的那个(server 6.3.0 起 400);对 1.196.0 ≤
+ *     version < 6.0.0 的引擎,`maxTurns`/`maxOutputTokens` 生效而 `maxWalltimeMs` 被静默无视。
  *     之所以过去写不出这条:/health 自报的是 server 版本,而键名代际取决于它捆的 core 版本,当时
  *     两者没有可从 wire 读出的映射;6.0.0 这班车把映射钉死了(6.0.0 ⇒ core ≥5.8),这条地板才成立。
  *   · 本文件的运行期探针目前只对第一地板发声(warn, don't block);第二地板先落成契约事实写在这里,
@@ -122,7 +125,7 @@ function parseIntInDomain(raw, min, max) {
 }
 /** 三个键任一在场 ⇒ 值得 stamp(空对象绝不上 wire —— 那是「配了个空预算」不是「没配」)。 */
 function hasAnyLimit(l) {
-    return l.maxWalltimeMs !== undefined || l.maxTurns !== undefined || l.maxTokens !== undefined;
+    return l.maxWalltimeMs !== undefined || l.maxTurns !== undefined || l.maxOutputTokens !== undefined;
 }
 /**
  * Parse `--deadline` + `--max-turns` + `--max-tokens` out of an argv slice. No flags ⇒ `{ok:true}`
@@ -156,7 +159,7 @@ export function parseLimitsArgv(argv) {
         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;
+        limits.maxOutputTokens = n;
         flaggedFlags.push('--max-tokens');
     }
     return {
@@ -165,44 +168,36 @@ export function parseLimitsArgv(argv) {
         flaggedFlags,
     };
 }
-/**
- * The settings-lane defaults. SILENT degrade on a bad value (batch-E triage shape — stricter than
- * 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 = {};
     const dl = env[HEADLESS_DEADLINE_ENV]?.trim();
     if (dl) {
         const n = parseIntInDomain(dl, DEADLINE_SEC_MIN, DEADLINE_SEC_MAX);
-        if (n !== null)
-            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`);
+        if (n === null) {
+            return {
+                ok: false,
+                error: `Error: ${HEADLESS_DEADLINE_ENV}="${dl}" is not an integer in ${DEADLINE_SEC_MIN}..${DEADLINE_SEC_MAX} (seconds). Fix or unset it.`,
+            };
         }
+        out.maxWalltimeMs = n * SEC_TO_MS; // env 面同样是秒(变量名带 _SEC),换算同一口
     }
     const mt = env[HEADLESS_MAX_TURNS_ENV]?.trim();
     if (mt) {
         const n = parseIntInDomain(mt, MAX_TURNS_MIN, MAX_TURNS_MAX);
-        if (n !== null)
-            out.maxTurns = n;
-        else if (env.SEMA_DEBUG) {
-            // eslint-disable-next-line no-console
-            console.error(`[sema] ${HEADLESS_MAX_TURNS_ENV}="${mt}" is not a positive integer — ignoring the settings default`);
+        if (n === null) {
+            return { ok: false, error: `Error: ${HEADLESS_MAX_TURNS_ENV}="${mt}" is not a positive integer. Fix or unset it.` };
         }
+        out.maxTurns = n;
     }
     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`);
+        if (n === null) {
+            return { ok: false, error: `Error: ${HEADLESS_MAX_TOKENS_ENV}="${mk}" is not a positive integer. Fix or unset it.` };
         }
+        out.maxOutputTokens = n;
     }
-    return hasAnyLimit(out) ? out : undefined;
+    return { ok: true, limits: hasAnyLimit(out) ? out : undefined };
 }
 /**
  * Resolve the limits for a headless `-p` submit: explicit flags > settings env defaults > none
@@ -213,8 +208,11 @@ export function limitsForPrint(argv, env = hostEnv()) {
     const parsed = parseLimitsArgv(argv);
     if (!parsed.ok)
         return parsed;
+    // #132:env 面非法值与 flag 同拍响亮拒(见 headlessLimitsFromEnv 头注)。
     const fromEnv = headlessLimitsFromEnv(env);
-    const merged = { ...(fromEnv ?? {}), ...(parsed.limits ?? {}) };
+    if (!fromEnv.ok)
+        return { ok: false, error: fromEnv.error };
+    const merged = { ...(fromEnv.limits ?? {}), ...(parsed.limits ?? {}) };
     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. */

package/dist/subagent/engineTaskHandleWire.d.ts

@@ -86,6 +86,14 @@ export type EngineTaskStopOutcome =
  * 照样带原始 `code`),绝不塌进任何一个已知形 —— 塌进去就等于替 server 编了一个它没说的原因。
  */
 export declare function classifyTaskStopConflict(e: unknown): EngineTaskStopOutcome;
+/**
+ * 🟢 B8 ALLOW 清单登记(REF-CC-域词表-05,属主=client-core 规范重构轮,到期复议=SDK typed 错误类
+ * 覆盖全部 `stop.*` 码后或 2026-Q4 复审以先到者为准):兜底字面认码,前置合取 = typed
+ * `TaskStopConflictError` 缺席时才落到这里(见 `stopEngineTask` 的 `if (e instanceof
+ * TaskStopConflictError || status === 409)`)。同批同表的另两处:`detachWire.ts`
+ * `DETACH_DURABLE_OFF_400_ANCHOR`(server 契约话)、`classifierVerdictWire.ts`
+ * `CLASSIFIER_DENY_SIGNATURE`(core lockstep 机器签名)——三处互指,理由逐条写在各自站点。
+ */
 /** 停一个引擎侧任务句柄(新面 B)。只有 ok:true(=HTTP 200)算停了。绝不 throw。 */
 export declare function stopEngineTask(handle: string, opts?: {
     signal?: AbortSignal;

package/dist/subagent/engineTaskHandleWire.js

@@ -47,6 +47,9 @@ import { engineTaskHandlesCapable } from './engineRowStopGate.js';
 // REF-CC-域词表-06 提单源:spool 全量/增量判读的单一真源现在在 toolResult.ts(它也消费同一份
 // 协议标记表 PROTOCOL_MARKERS)—— 本文件不再自己 `.includes()` 抄一份判读。
 import { spoolMarkerOf } from '../toolResult.js';
+// G1 去字面化(2026-08-04):`stop.*` 五形的码字面收编进 `engineErrorCodes.ts` 单一真源。
+// 顺序敏感的兜底认码数组也一并搬过去(顺序即语义,见那边的头注),本文件只 import。
+import { STOP_CONFLICT_CODES, STOP_NOT_LANDED, STOP_NOT_LOCAL, STOP_PARKED, STOP_PARK_ARBITER_UNREACHABLE, STOP_PARK_RESUME_WON, } from '../engineErrorCodes.js';
 // 能力门同步读口:真源在零依赖叶 `engineRowStopGate`(batch-stop 同步分类不拉本模块 SDK 图)。
 // ⚠️ 此处**不再 re-export**——它与原定义同进 index.ts 的 `export *` barrel 会构成双出口,
 // esbuild 对 star-export 歧义直接 build 失败(tsc 同源 symbol 不报=假绿;0.8.0 壳收批实撞,
@@ -153,15 +156,15 @@ export function classifyTaskStopConflict(e) {
         ? raw
         : (STOP_CONFLICT_CODES.find(c => detail.includes(c)) ?? '');
     switch (code) {
-        case 'stop.not_local':
+        case STOP_NOT_LOCAL:
             return { ok: false, reason: 'not_local', detail };
-        case 'stop.parked':
+        case STOP_PARKED:
             return { ok: false, reason: 'parked', detail };
-        case 'stop.park_resume_won':
+        case STOP_PARK_RESUME_WON:
             return { ok: false, reason: 'park_resume_won', detail };
-        case 'stop.park_arbiter_unreachable':
+        case STOP_PARK_ARBITER_UNREACHABLE:
             return { ok: false, reason: 'park_arbiter_unreachable', detail };
-        case 'stop.not_landed':
+        case STOP_NOT_LANDED:
             return { ok: false, reason: 'not_landed', detail };
         default:
             // 开集:未知/未来 `stop.*`(以及 code 完全缺席的残破形)。诚实说「有冲突但我不认识它」,
@@ -177,14 +180,8 @@ export function classifyTaskStopConflict(e) {
  * `DETACH_DURABLE_OFF_400_ANCHOR`(server 契约话)、`classifierVerdictWire.ts`
  * `CLASSIFIER_DENY_SIGNATURE`(core lockstep 机器签名)——三处互指,理由逐条写在各自站点。
  */
-/** 兜底字面认码用的已知集(顺序 = 长码优先,避免 `stop.parked` 抢走 `stop.park_resume_won`)。 */
-const STOP_CONFLICT_CODES = [
-    'stop.park_arbiter_unreachable',
-    'stop.park_resume_won',
-    'stop.not_landed',
-    'stop.not_local',
-    'stop.parked',
-];
+/* 兜底字面认码用的已知集(顺序 = 长码优先,避免 `stop.parked` 抢走 `stop.park_resume_won`)
+ * 已随 G1 去字面化搬到 `engineErrorCodes.ts` 的 `STOP_CONFLICT_CODES` —— 顺序即语义那条注也在那边。 */
 /** 停一个引擎侧任务句柄(新面 B)。只有 ok:true(=HTTP 200)算停了。绝不 throw。 */
 export async function stopEngineTask(handle, opts) {
     const cfg = engineWireTarget();

package/dist/toolResult.d.ts

@@ -1,3 +1,5 @@
+import type { TaskResult, TaskStats } from '@sema-agent/sdk';
+import { type ModelFallbackReason } from './engineErrorCodes.js';
 /**
  * 引擎会在 `tool_end.structured` 顶层 `type` 上发的**全部**取值。
  * 用途**不是**「只处理这些」——下面的 switch 只认得其中一部分,认不得的照旧走 text 回落;
@@ -197,3 +199,87 @@ export declare function todoWriteToolUseResult(rawInput: unknown, oldTodos: unkn
 export declare function reportFindingsToolUseResult(structured: unknown, rawInput: unknown): {
     toolUseResult: unknown;
 } | null;
+/**
+ * 子代**完成着陆报告**卡(core `agents/subagent.ts#completedAgentCard` 的 wire 形)。
+ *
+ * 沿革:5.10.0 之前这张卡被 core 的投影白名单在上 wire 前整张丢掉 —— `tool_end.structured` 自己的
+ * 契约点名了它,而实际只有 `async_launched` 回执到得了消费方。5.10.0 修好了那条白名单,于是
+ * `type:"agent"` 从「只有一形」变成「两形按 `status` 分」({@link structuredToToolUseResult} 的
+ * `case 'agent'` 头注写了为什么本包不把它投成 CC 卡)。
+ *
+ * 🔴 **本读口只做窄化,不做解释**:每个键要么原样带出,要么(类型不符时)当缺席。绝不为缺席的量
+ *    造零值([honest-absence-not-fabricated-zero])—— `stats` 取不到就是 `undefined`,不是 `{}`。
+ * 🔴 **白名单不是闭集断言**:core 明写这张卡是「显式字段白名单」而非 spread(`checkpointToken` /
+ *    `checkpointGate` 这两个**能力**位永不上 wire)。未来 core 往卡上加字段时,本读口读不到它们 ——
+ *    那是**加一个字段**的跟车工单,不是错误;宿主要原始全量随时可读 `structured` 本身。
+ */
+export interface CompletedAgentCard {
+    /** 子代**真实终态**(`completed` / `failed` / `blocked` / `suspended.*` …)。判别位;开集。 */
+    readonly status: string;
+    /** 子代任务 id(注意:完成卡是 camelCase `taskId`,启动回执是 snake_case `task_id`)。 */
+    readonly taskId: string;
+    /** 子代 transcript 句柄 —— 查询键,**不是**能力(续跑要部署侧的 resume 句柄)。 */
+    readonly sessionId?: string;
+    /** 子代类型名(roster 上的名字)。 */
+    readonly subagentType?: string;
+    /** 着陆报告正文 = 子代最终助手文本,**不含**模型面那层导向尾注。 */
+    readonly result?: string;
+    /** 到限截断时抢救出的最后模型文本。 */
+    readonly salvagedOutput?: string;
+    /** `outputSchema` 任务的结构化产出(不解释,原样)。 */
+    readonly structuredOutput?: unknown;
+    /** 失败归因三件之一:agent 自报无法推进的理由。 */
+    readonly blockedReason?: string;
+    /** 失败归因三件之二:人话。 */
+    readonly errorMessage?: string;
+    /** 失败归因三件之三:机器码(开集;词表见 `engineErrorCodes.ts`)。 */
+    readonly errorCode?: string;
+    /**
+     * 🆕 core 5.10.0 —— `errorCode` 的**机器可执行配对**:refusal 什么时候解除。
+     * 🔴 与 `retryable` 是**两个不同的问题**,可能同时出现且看起来矛盾(core 亲注):
+     *    `retryable` = 「现在原样重发行不行」(`usage.window_exhausted` 上它是 false,且是对的);
+     *    `retryAfterMs` = 「什么时候不再被拒」。调度器读前者+后者,立即重发的决策只读 `retryable`。
+     *    在场条件 = `usage.window_exhausted` 终局;**别拿它的在场性去判别的事**([2575] 自查③)。
+     */
+    readonly retryAfterMs?: number;
+    /**
+     * 🆕 core 5.10.0 —— 降级实录(from/to/reason/atTurn)。形状与 `TaskResult.degraded` **同一个**
+     * (core 把子代 TaskResult 的这一位原样搬上卡),故直接借 SDK 的类型而不是再开一个 `unknown` 出口。
+     * 窄化 = 对象守卫(与 `terminalToSdkResult.degradedOf` 同一姿势):非对象一律当缺席。
+     */
+    readonly degraded?: NonNullable<TaskResult['degraded']>;
+    /** 失败分类:错误种类。 */
+    readonly errorKind?: string;
+    /** 失败分类:原样重发是否可行(见 `retryAfterMs` 的配对说明)。 */
+    readonly retryable?: boolean;
+    /**
+     * run 总账(CC `AgentToolCompletedOutput` 对位)。同 `degraded`:core 搬的就是子代
+     * `TaskResult.stats`,所以借 SDK 的 `TaskStats`(它自带 `[key: string]: unknown` 开集索引,
+     * 新键不会因此被类型面挡住)。数值重算是渲染层的活,本层只窄化不解释。
+     */
+    readonly stats?: TaskStats;
+    /** 实际服务该子代的模型 id(与 `resolvedModel` 同值,core 两个键都发)。 */
+    readonly model?: string;
+    /** 同上 —— core 的显式别名键;两键择一读即可,本读口都带出以免宿主二次猜。 */
+    readonly resolvedModel?: string;
+    /**
+     * 🆕 core 5.10.0 / [2577] —— **闭集单成员**:请求的模型词没绑上,子代跑在继承来的默认模型上。
+     * 🔴 **这不是错误**(回落行为本身没变,只是现在说出来了);缺席 = 正常绑定或压根没请求过词。
+     *    渲染建议(core 给的语义,UI 语言各端自裁):在生效 model 旁加「requested word did not bind /
+     *    inherited」注记,**不因它的在场性改变别的渲染**。加成员 = BREAKING,见 {@link ModelFallbackReason}。
+     */
+    readonly modelFallback?: ModelFallbackReason;
+    /** 子代跑在哪个 worktree(`isolation:'worktree'` 时)。 */
+    readonly worktreePath?: string;
+    /** 子代的逐工具调用统计。原样带出。 */
+    readonly toolStats?: unknown;
+}
+/**
+ * 把一张 `tool_end.structured` 窄化成 {@link CompletedAgentCard} —— **仅当**它是 `type:"agent"` 的
+ * **完成**臂时。不是 agent 卡 / 是 `async_launched` 回执 / 缺 `status` 或 `taskId` ⇒ `null`。
+ *
+ * 🔴 分臂判据 = `status`(core 原话:"Branch on `status`, never on which keys are present")。
+ *    本函数是那条纪律在包内的**单一实现点**:三端(TUI / web / desktop)按同一份窄化读,
+ *    而不是各自抄一遍键名与 `!== 'async_launched'`。
+ */
+export declare function readCompletedAgentCard(structured: unknown): CompletedAgentCard | null;

package/dist/toolResult.js

@@ -27,6 +27,7 @@
 import { convertLeadingTabsToSpaces, getPatchFromContents } from './diff/patch.js';
 import { markEngineWorkflowNotified, registerOutstandingBgTask, registerOutstandingWorkflowRun, } from './notifications.js';
 import { parseWorkflowPollEnvelope, projectWorkflowTaskOutput } from './workflow.js';
+import { asModelFallbackReason } from './engineErrorCodes.js';
 // ══════════════════════════════════════════════════════════════════════════════════════════════
 // ① structured 白名单(core design/116 的 details 顶层 `type` 集;[1840]§一 清单逐字)
 // ══════════════════════════════════════════════════════════════════════════════════════════════
@@ -41,7 +42,6 @@ import { parseWorkflowPollEnvelope, projectWorkflowTaskOutput } from './workflow
  */
 export const STRUCTURED_DETAIL_TYPES = new Set([
     'edit',
-    'multiedit',
     'create',
     'update',
     'bash',
@@ -59,7 +59,6 @@ export const STRUCTURED_DETAIL_TYPES = new Set([
     'task',
     'task-list',
     'task-output',
-    'memory-saved',
     'workflow-run',
     'web-fetch',
     'web-search',
@@ -70,7 +69,6 @@ export const STRUCTURED_DETAIL_TYPES = new Set([
     'image',
     'task-stop',
     'tool-search',
-    'memory-recall',
     'repo-map',
     'fork',
     'enter-plan-mode',
@@ -82,7 +80,29 @@ export const STRUCTURED_DETAIL_TYPES = new Set([
     'worktree',
     'monitor-start',
     'path_not_in_root',
+    // ── core 5.10.0 词表换代(2026-08-04 提货批;engine-vocab 等值门对 5.10.0 实装物直证)──────
+    // 5.10.0 的 structured-card 审计把这张表变成**双向契约**(每个铸点都登记 / 每个登记词都真被产出)。
+    // 新登记 7 词 —— 它们的工具**一直**在铸卡,漏的只是登记,于是这 7 类卡从来没上过 wire:
+    //   · `report-findings` 最坏(ReportFindings 的模型面被**故意**压成「N findings reported.」,
+    //     卡又丢了 ⇒ findings 模型看不到、宿主也看不到,两头落空);
+    //   · `readonly_out_of_root` 与既有 `path_not_in_root` 是同一份「按字段数拒绝次数」契约的两半
+    //     (一个在 shell 面、一个在 fs 面);
+    //   · `schedule-wakeup` / `send-message` / `agent-transcript` / `a2a` / `document` 同理。
+    'readonly_out_of_root',
+    'report-findings',
+    'schedule-wakeup',
+    'send-message',
+    'agent-transcript',
+    'a2a',
+    'document',
 ]);
+// 🔴 同批**删三词**(core 5.10.0 BREAKING「幽灵卡」清仓):`multiedit` / `memory-saved` /
+//    `memory-recall` —— 全树零铸点(MultiEdit/批量重放铸的是 `type:"edit"` 带 `edits[]`;core
+//    根本不挂 memory 工具,memory 引擎是 runner 面子系统,没有工具面)。它们是「一个没人能兑现的
+//    承诺」:按闭集分支的消费者为它们留了永不执行的臂。core 明写**不是**预留位——将来哪个工具
+//    铸这种卡,和那个工具同一批加回来。
+//    ⚠️ 对本表的实际后果:这三个词此前会让 `structuredDetailType()` 判「structured 在场」⇒ 正则
+//    退位。既然引擎从来不发它们,删掉是**零行为影响**的诚实化(不是收窄)。
 /** structured 在场判别:顶层 `type` ∈ 白名单 ⇒ 返回该 type,否则 undefined(= 不在场)。 */
 export function structuredDetailType(structured) {
     if (typeof structured !== 'object' || structured === null)
@@ -686,6 +706,21 @@ modelText) {
         case 'agent': {
             // Agent 异步启动(core 1.272+ [666] 默认后台化主路径)。outputFile 是 schema 必填但 live lane
             // 没有本地文件 ⇒ '' + canReadOutputFile:false(渲染文本因此省掉 file-tail 分支,与引擎模型面一致)。
+            //
+            // 🔴 **`type:"agent"` 自 core 5.10.0 起是两形一卡**([2575] 消费端自查②):`status` 是判别位 ——
+            //    `"async_launched"` = 本臂的启动回执;**其它任何值** = 子代的**完成着陆报告**
+            //    (`completedAgentCard`,core `agents/subagent.ts`;5.10.0 之前它被投影白名单在上 wire 前丢掉,
+            //    所以「`type:"agent"` ⇒ 后台启动回执」这个等式当时恰好成立,现在不成立了)。
+            // 🔴 **按 `status` 分臂,绝不按键集分臂** —— 这是 core 的原话,也是本行 `!==` 的全部理由。
+            //    键集判别在两形共有 `taskId`/`status`/`prompt`-无 的现实下必然错分。
+            // 🔴 完成卡**本批不投 CC 卡**(如实留白,不假装搬完):壳的 `AgentTool.outputSchema` 完成臂
+            //    (`agentToolResultSchema` + `status:'completed'`)要 `content`/`totalToolUseCount`/
+            //    `totalDurationMs`/`totalTokens`/`usage`/`prompt` 六件,而完成卡上**没有 `prompt`**、
+            //    `status` 是子代真实终态(可能是 `failed`/`blocked`/`suspended.*`,壳的 zod 会当场拒),
+            //    统计也要从 `stats`/`toolStats` 重算 —— 那是**行为面**改动(要先答「失败的子代该渲成什么」),
+            //    按宪法三问单独走。返回 null ⇒ 回落模型面 text 路径,与 5.10.0 之前逐字同形,零回归。
+            //    ⚠️ 完成卡本身**没有被吞**:`eventToSdkMessage` 的 `tool_end_result` 臂把 `structured`
+            //    原样透传给宿主,typed 读口见本文件的 {@link readCompletedAgentCard}。
             if (s.status !== 'async_launched')
                 return null;
             const agentId = typeof s.task_id === 'string' ? s.task_id : undefined;
@@ -853,3 +888,56 @@ export function reportFindingsToolUseResult(structured, rawInput) {
         },
     };
 }
+/**
+ * 把一张 `tool_end.structured` 窄化成 {@link CompletedAgentCard} —— **仅当**它是 `type:"agent"` 的
+ * **完成**臂时。不是 agent 卡 / 是 `async_launched` 回执 / 缺 `status` 或 `taskId` ⇒ `null`。
+ *
+ * 🔴 分臂判据 = `status`(core 原话:"Branch on `status`, never on which keys are present")。
+ *    本函数是那条纪律在包内的**单一实现点**:三端(TUI / web / desktop)按同一份窄化读,
+ *    而不是各自抄一遍键名与 `!== 'async_launched'`。
+ */
+export function readCompletedAgentCard(structured) {
+    if (structured === null || typeof structured !== 'object')
+        return null;
+    const s = structured;
+    if (s.type !== 'agent')
+        return null;
+    const status = s.status;
+    // 分臂:`async_launched` 是回执臂(归 `structuredToToolUseResult` 的 `case 'agent'`),不是本臂。
+    if (typeof status !== 'string' || status.length === 0 || status === 'async_launched')
+        return null;
+    const taskId = s.taskId;
+    // 身份缺席 ⇒ 这不是一张可用的完成卡(诚实拒,不铸空 id)。
+    if (typeof taskId !== 'string' || taskId.length === 0)
+        return null;
+    const str = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+    return {
+        status,
+        taskId,
+        ...(str(s.sessionId) !== undefined ? { sessionId: str(s.sessionId) } : {}),
+        ...(str(s.subagent_type) !== undefined ? { subagentType: str(s.subagent_type) } : {}),
+        // `result` 允许空串(子代没产出正文是一个诚实的事实),故这里不用 `str` 的非空过滤。
+        ...(typeof s.result === 'string' ? { result: s.result } : {}),
+        ...(typeof s.salvagedOutput === 'string' ? { salvagedOutput: s.salvagedOutput } : {}),
+        ...(s.structuredOutput !== undefined ? { structuredOutput: s.structuredOutput } : {}),
+        ...(str(s.blockedReason) !== undefined ? { blockedReason: str(s.blockedReason) } : {}),
+        ...(str(s.errorMessage) !== undefined ? { errorMessage: str(s.errorMessage) } : {}),
+        ...(str(s.errorCode) !== undefined ? { errorCode: str(s.errorCode) } : {}),
+        ...(num(s.retryAfterMs) !== undefined ? { retryAfterMs: num(s.retryAfterMs) } : {}),
+        // 对象守卫(与 terminalToSdkResult.degradedOf 同姿势):非对象/null 一律当缺席,不硬塞。
+        ...(typeof s.degraded === 'object' && s.degraded !== null
+            ? { degraded: s.degraded }
+            : {}),
+        ...(str(s.error_kind) !== undefined ? { errorKind: str(s.error_kind) } : {}),
+        ...(typeof s.retryable === 'boolean' ? { retryable: s.retryable } : {}),
+        ...(typeof s.stats === 'object' && s.stats !== null ? { stats: s.stats } : {}),
+        ...(str(s.model) !== undefined ? { model: str(s.model) } : {}),
+        ...(str(s.resolvedModel) !== undefined ? { resolvedModel: str(s.resolvedModel) } : {}),
+        ...(asModelFallbackReason(s.modelFallback) !== undefined
+            ? { modelFallback: asModelFallbackReason(s.modelFallback) }
+            : {}),
+        ...(str(s.worktreePath) !== undefined ? { worktreePath: str(s.worktreePath) } : {}),
+        ...(s.toolStats !== undefined ? { toolStats: s.toolStats } : {}),
+    };
+}