@sema-agent/client-core 0.45.0 → 0.47.0

package/dist/interactiveHalt.js

@@ -0,0 +1,131 @@
+/**
+ * interactiveHalt — 交互 **Esc** 的停止判定层(#363 件③,0.47.0;三端公共判定上收)。
+ *
+ * ── 收的是哪一件事 ────────────────────────────────────────────────────────────────────────
+ * 「用户按 Esc ⇒ 先发 **turn 级 halt**;升级成 **run 级 cancel** 恰有**两格**:
+ *   ① 引擎自己回了升级闭集里的 **409**(它在说「这里没有在飞 turn 可切,run 级停止请用 cancel」);
+ *   ② 这一发**连判决都没拿到**(传输失败/超时/未武装)**且**屏上确实挂着审批卡(`parked`)。
+ * 其余一律不升级。」—— 这条判定 TUI / desktop / web **三端都要**(三端都会 Esc、都会撞
+ * 同一个 parked 格),此前整条住在 cli 壳里(`src/sema/seamQuery.ts` 的 `bestEffortInteractiveHalt`
+ * + `src/sema/interruptWire.ts` 的 `needsRunLevelStop`)。本模块把**判据**搬进来;
+ * **发射**(裸 fetch / SDK verb)、台账、留痕、UI 反馈仍归各端。
+ * ⚠️ 别把①漏掉(异源复审 [medium] 采纳的原文歧义):只写「拿不到判决且 parked 才升级」的话,
+ *    端会漏接**引擎明确指路**那一格 —— parked run 的会话锁不放,下一条消息照样撞「Session busy」。
+ *
+ * ── 两个动词各自唯一能做到的格(**cancel 绝不删**,本模块存在的前提)──────────────────────
+ *   · `interrupt`(turn 级,bare 形 = core `stream.halt()`「切 + 停」)—— 需要一条**活的、在飞的
+ *     turn**。这是 Esc 的正题:切掉这一轮,run 在边界上终局、同 session 下一 submit 照常续。
+ *   · `cancel`(run 级)—— 显式整 run 终局手势,而且它是**唯一**能把一条停在审批门上的
+ *     `suspended`/`needs_review` run 就地终态化、把会话锁放开的动词(server [868] 起的语义)。
+ * ⇒ 无条件把 cancel 换成 interrupt = 审批卡挂着按 Esc 的主场景当场回归成「Session busy」病;
+ *   无条件补 cancel = 同一条 run 上别的在飞工具(后台 bash 等)被连坐拆掉(#324 的病形)。
+ *   本判定就是这两条之间那道**不对称**的闸。
+ *
+ * ── 🔴 不对称是刻意的(方向安全,两条代价不等价)────────────────────────────────────────
+ * 判**不**升级的代价 = 用户退回既有的「Session busy」卡,自己再选一次(**可恢复**);
+ * 判**错**升级的代价 = 拆掉一条其实还活着的 run,连坐它身上所有在飞工具(**不可恢复**)。
+ * ⇒ 闸往严的一侧设,宁可少升一次;凡「证不出来」一律落**不升级**侧。
+ *
+ * ── 判据锚在哪 ────────────────────────────────────────────────────────────────────────────
+ *   · 升级的**第一判据 = 引擎自己的机器码**({@link RUN_LEVEL_STOP_ERROR_CODES} × 409),
+ *     不是壳对 UI 状态的猜测([anchor-on-the-deciding-quantity]);
+ *   · 只有当**引擎连判决都没给**(传输失败/超时/根本没武装)时,才轮到壳自己独立知道的那个
+ *     事实(`parked` = 这一拍屏上确实挂着审批卡 ⇒ 那条 run 停在 pending 决断上 ⇒ 本来就没有
+ *     在飞 turn 可切 ⇒ 补 cancel 不构成连坐)。
+ *
+ * 🔴 **纯判定**:零 IO、零 import、零 module 级状态,同一入参恒同一出参。
+ */
+/**
+ * server 在 interrupt 腿上表达「**这条 run 已经 parked、没有在飞 turn 可切**」的 409 机器码
+ * (engine 7.52.0 `dist/http/routes/runs.js` 真字节,`sendNoLiveTurn` 的 `isParkedRunStatus` 分支)。
+ *   · `interrupt.nothing_in_flight` —— run 停在 pending 决断上。**审批卡挂着按 Esc 的主场景就是
+ *     这一格**,server 的原话直接指路 steer/cancel。
+ *
+ * 🔴 **闭集只收这一员**,另外两个 409 都刻意在外:
+ *   · `interrupt.not_held` —— **不收**。语义是「**本副本**手上没有可切的 live turn face」,而 server
+ *     自己的两条原话把它拆得很清楚:一条是「run is live on **another replica**」,另一条是
+ *     verify/cascade 车道不暴露 live stream。**两条都不证明「全局没有在飞 turn」** —— 尤其第一条,
+ *     那条 run 正在别的副本上跑得好好的。对它升级 = 把 **turn 级** Esc 放大成**整 run 终止**。
+ *     server 提示「run-level stop 可用 cancel」是在告诉你**有这个动词**,不等于用户授权了 run 级停止。
+ *   · `steering.not_running` —— 不收。run 已终局,没有任何东西要停,补一发 cancel 是纯噪声。
+ * ⇒ 只有「引擎结构化地证明了 run 已 parked」这一格才允许升级。等上游给出 owner/parked 判别位
+ *   (或跨副本路由)之后,`not_held` 才谈得上有安全的处置。
+ *
+ * 🔴 **为什么是 `Object.freeze` 的数组而不是 `ReadonlySet`**(异源复审 [high] 采纳,真病):
+ * `ReadonlySet<string>` 只在**类型面**只读 —— 运行期它就是一只普通 `Set`,而判定查的是**同一个
+ * 实例**。任何 JS 消费者(或本包将来某处的一行手滑)`.add('interrupt.not_held')` 之后,同一份入参
+ * 就会从 `none` 变成 `escalate-cancel`,把一条**还活着**的 run 不可恢复地拆掉 —— 这正是本模块整段
+ * 头注在防的那个方向,却被自己的导出形留了后门;而「纯判定、零 module 级可变态」那句承诺也当场
+ * 变成假话。冻结数组在**运行期**真的改不动(ESM 恒 strict:`push`/下标赋值直接抛),于是「公开
+ * 面」与「判定源」可以安全地是同一个物,不必铸第二份(两份才会漂)。
+ * ⚠️ 判据形随之从 `.has()` 改成 `.includes()` —— 与同仓 `parkResolver.GATE_FAILURE_CODES` 的
+ *    `as const` 数组 + `includes` 逐字同姿势。闭集只有一员,查找成本不是这里的量。
+ */
+export const RUN_LEVEL_STOP_ERROR_CODES = Object.freeze([
+    'interrupt.nothing_in_flight',
+]);
+/** 升级闭集的码在 wire 上**只以 409 出现**(engine 7.52.0 `sendNoLiveTurn` 两分支逐字)。 */
+const RUN_LEVEL_STOP_STATUS = 409;
+/**
+ * 这一发 interrupt 的结局是不是在说「**改用 run 级停止**」。
+ *
+ * 判据 = **码闭集({@link RUN_LEVEL_STOP_ERROR_CODES})与 409 状态的合取**,两个条件都必要:
+ * · 只认码不认状态 ⇒ 一只 5xx(引擎内部错、代理改写体、老版本复用同名码)只要正文里带上那个码,
+ *   就能把我们骗去打一发 **run 级 cancel** —— 那是**破坏性**动作,而它当时其实没有任何判决依据。
+ * · 只认 409 不认码 ⇒ `steering.not_running`(run 已终局)也会被升级,对着一条已经结束的 run 补枪。
+ */
+function enginePointsToRunLevelStop(outcome) {
+    const o = outcome;
+    return (o?.kind === 'refused' &&
+        o.status === RUN_LEVEL_STOP_STATUS &&
+        typeof o.errorCode === 'string' &&
+        RUN_LEVEL_STOP_ERROR_CODES.includes(o.errorCode));
+}
+/**
+ * Esc 停止弧的**唯一判定口**。
+ *
+ * ── 分支表(逐条 = 一条行为承诺)──────────────────────────────────────────────────────────
+ * | `interruptOutcome`                         | `parked` | 判决              | reason |
+ * |--------------------------------------------|----------|-------------------|--------|
+ * | 缺席(还没打)                              | 任意     | `interrupt`       | `first-shot` |
+ * | `halted`                                    | 任意     | `none`            | `halted` |
+ * | `refused` + 409 + 升级闭集码                 | 任意     | `escalate-cancel` | `engine-says-run-level` |
+ * | `refused`(其余:非 409 / 码不在闭集 / 码缺席)| 任意     | `none`            | `refused-no-escalation` |
+ * | `transport` / `unarmed`                     | `true`   | `escalate-cancel` | `no-verdict-on-parked-card` |
+ * | `transport` / `unarmed`                     | 其余     | `none`            | `no-verdict-not-parked` |
+ * | 认不得的形                                   | 任意     | `none`            | `unknown-outcome` |
+ *
+ * 🔴 **`parked` 只在「没有判决」那两格被读**:引擎给了判决时,判决说了算 —— 壳的 UI 状态不许覆盖
+ *    引擎的结构化答复(反过来也一样:引擎说 parked 时,`parked=false` 不阻止升级)。
+ * 🔴 **首发无条件**:`first-shot` 那一格刻意不看 `parked`。审批卡挂着时首发 interrupt 会吃一个
+ *    409,那正是升级闸要的**判决**;为了省一次往返而直接跳到 cancel,等于把判据从引擎搬回壳里猜。
+ * 🔴 **顺序契约(端必读,不是本函数能保证的那半)**:这一发必须排在「撕 SSE」**之前**。交互车道零
+ *    `x-detach-on-disconnect`,先撕流 = server 按断连语义当场收尾那条 run,随后落地的 interrupt
+ *    只会拿到 409 `steering.not_running`(cli L-11 真机实测:同步撕流形每一轮都是它)。
+ */
+export function planInteractiveHalt(input) {
+    const outcome = input.interruptOutcome;
+    // 首发恒行:一发都还没打的时候,没有任何东西需要判。
+    // 🔴 `null` 与 `undefined` **同判「还没打」**(两种缺席形;宿主用哪一种写「没有结局」都算数)——
+    //    而不是落 fail-closed 的 `unknown-outcome`:那会让 Esc 一发都不打(interrupt 是**非破坏性**
+    //    动词,把它扣下来比多打一发更坏)。fail-closed 守的是**升级**那一侧,不是首发。
+    if (outcome === undefined || outcome === null)
+        return { action: 'interrupt', reason: 'first-shot' };
+    // 防御读:wire/宿主形在运行期不存在类型(M0/M1),`kind` 可能是新词、可能压根不是对象。
+    const kind = outcome.kind;
+    if (kind === 'halted')
+        return { action: 'none', reason: 'halted' };
+    if (kind === 'refused') {
+        return enginePointsToRunLevelStop(outcome)
+            ? { action: 'escalate-cancel', reason: 'engine-says-run-level' }
+            : { action: 'none', reason: 'refused-no-escalation' };
+    }
+    if (kind === 'transport' || kind === 'unarmed') {
+        // 没拿到判决。只有壳能**独立证明** parked 的那一格才升级(理由见顶注的不对称段)。
+        return input.parked === true
+            ? { action: 'escalate-cancel', reason: 'no-verdict-on-parked-card' }
+            : { action: 'none', reason: 'no-verdict-not-parked' };
+    }
+    // 宿主传了本模块认不得的形(新 kind / 坏对象)。fail-closed:不对一个读不懂的结局动手。
+    return { action: 'none', reason: 'unknown-outcome' };
+}

package/dist/printToolResultFrame.js

@@ -27,7 +27,12 @@ import { flattenWireOutput } from './adapt/wireShapes.js';
 function bashExitCodeFailed(toolName, text, structured) {
     if (typeof toolName !== 'string' || toolName.toLowerCase() !== 'bash')
         return false;
-    const ec = structured?.exitCode;
+    const st = structured;
+    // 良性非零退出注记在场(grep/rg 无命中族)⇒ 非错——CC 同款:interpretation 形走 data
+    // 路径非 error 路径(pretty223:394251);与 toolResult.ts T11 同判别量(2026-08-27)。
+    if (typeof st?.returnCodeInterpretation === 'string' && st.returnCodeInterpretation.length > 0)
+        return false;
+    const ec = st?.exitCode;
     if (typeof ec === 'number')
         return ec !== 0;
     const m = /^exit code: (\d+)\b/.exec(text);

package/dist/toolResult.js

@@ -386,7 +386,14 @@ export function wireOutputToBody(toolName, output, isError, truncated, flatten,
             }
             : parseModelFacingBash(text);
         if (slots) {
-            const failed = isError || (slots.exitCode != null && slots.exitCode !== 0);
+            // 良性非零退出注记(2026-08-27,1.0.93 现网案):引擎对 grep/rg 无命中族显式给
+            // isError:false + structured.returnCodeInterpretation('No matches found')。注记在场 ⇒
+            // 非零退出不再翻 failed(CC 同款:interpretation 形走 data 路径非 error 路径,
+            // pretty223:394251/815147 直证)。[1948] 裁定不动:无注记的非零退出照旧按退出码补位。
+            const benignInterp = typeof s?.returnCodeInterpretation === 'string' && s.returnCodeInterpretation.length > 0
+                ? s.returnCodeInterpretation
+                : undefined;
+            const failed = isError || (slots.exitCode != null && slots.exitCode !== 0 && benignInterp === undefined);
             if (failed) {
                 // 失败卡走 UserToolErrorMessage,它读 BLOCK content 且非字符串会被吞成
                 // "Tool execution failed" —— 失败路径必须给字符串(cli 同,对抗复审 d126727#3)。
@@ -397,6 +404,15 @@ export function wireOutputToBody(toolName, output, isError, truncated, flatten,
                 if (slots.exitCode === 137) {
                     body += `\nCommand was killed (exit 137 — possibly out-of-memory; consider lowering build parallelism e.g. make -j2)`;
                 }
+                // [5601]/#362(2026-08-29,live 帧直证 core 5.65.0):「跑过然后被掐」家族
+                // (timeout/aborted/callback_error)铸 isError:true + 三槽 {stdout:'',stderr:'',exitCode:null}
+                // + output 正文带完整说明——重建体在这形上恒为空串,引擎正文整段被丢,下游渲
+                // 「no error detail」空卡。回退判据锚**决定量本身**(重建 body 空而正文有话),
+                // 不锚 timedOut 等键名:同家族零输出三臂一次覆盖,且 exitCode 在场时 body 至少含
+                // `Exit code N` 恒非空 ⇒ 回退结构上只在 exitCode===null 且双槽空触发,权威臂地位不动。
+                // 双空(正文也空)⇒ 如实返回空串,消费端「no error detail」兜底句保持可达。
+                if (body.trim() === '' && text.trim() !== '')
+                    body = text;
                 return { content: truncated ? `${body}\n…(truncated)` : body, isError: true };
             }
             const stdout = truncated ? `${slots.stdout}\n…(truncated)` : slots.stdout;
@@ -404,7 +420,14 @@ export function wireOutputToBody(toolName, output, isError, truncated, flatten,
             return {
                 content: [processedStdout, slots.stderr.trim()].filter(Boolean).join('\n'),
                 isError: false,
-                toolUseResult: { stdout, stderr: slots.stderr, interrupted: false },
+                // 注记过境:BashToolResultMessage 蓝本在零输出分支渲 returnCodeInterpretation
+                // (『No matches found』而非『(No output)』),缺席时行为不变。
+                toolUseResult: {
+                    stdout,
+                    stderr: slots.stderr,
+                    interrupted: false,
+                    ...(benignInterp !== undefined ? { returnCodeInterpretation: benignInterp } : {}),
+                },
             };
         }
         const stdout = truncated ? `${text}\n…(truncated)` : text;
@@ -518,13 +541,18 @@ modelText) {
             if (typeof s.stdout !== 'string' && typeof s.stderr !== 'string')
                 return null;
             const exitCode = typeof s.exitCode === 'number' ? s.exitCode : null;
+            // 良性非零退出注记同臂(与 wireOutputToBody T11 同判别量,CC pretty223:394251 同源)。
+            const benignInterp = typeof s.returnCodeInterpretation === 'string' && s.returnCodeInterpretation.length > 0
+                ? s.returnCodeInterpretation
+                : undefined;
             return {
                 toolUseResult: {
                     stdout: typeof s.stdout === 'string' ? s.stdout : '',
                     stderr: typeof s.stderr === 'string' ? s.stderr : '',
                     interrupted: false,
+                    ...(benignInterp !== undefined ? { returnCodeInterpretation: benignInterp } : {}),
                 },
-                ...(exitCode !== null && exitCode !== 0 ? { isError: true } : {}),
+                ...(exitCode !== null && exitCode !== 0 && benignInterp === undefined ? { isError: true } : {}),
             };
         }
         case 'edit': {

package/dist/wireErrorTriage.d.ts

@@ -49,6 +49,47 @@ export declare function isPreStreamDrainingReject(err: unknown): boolean;
  * #166 — `resume_at.*` 错误码族:提交带的 resumeAt 锚服务端不认(Esc 杀锚未持久化的典型形)。
  * 🔴 刻意**不**用 `isRewindFamilyCode`(那是含 `rewind_snapshot.` 的宽形):去锚自动重发的安全性
  * 论证只对 resume_at 族做过,放宽属行为变更(RESUME_AT_ERROR_CODE_PREFIX 头注)。
+ *
+ * ## #355 D1 —— 两条载体腿(2026-08-27)
+ * 同一个语义在 wire 上有**两种形**,此前只认第一种:
+ *   · **机读形**(既有腿,一字未动):core prepare-throw 经 `resumeAtHttpStatus` 落 4xx,
+ *     `errorCode` **原样透传**真子码(`resume_at.not_found` / `resume_at.before_target_not_user` …)
+ *     ⇒ 前缀命中。
+ *   · **包装形**(本腿新增):server 的**预检腿**在 core 之前就 4xx —— `boot/resolve-spec.ts`
+ *     抛 `HttpError(404, "resumeAt: no such message in this session (resume_at.unknown_event)")`
+ *     且**不带** `code`,于是 `http/send.ts` 的 `httpErrorCode(404)` 盖上按状态码派生的粗码
+ *     `not_found.resource`,真子码**只活在人话里**。SDK `classifyApiError` 把 body 的 `error`
+ *     原样搬进 `APIError.message`(scrub 只动 Bearer/presigned),所以壳收到的是
+ *     `{status:404, errorCode:'not_found.resource', message:'…(resume_at.unknown_event)'}`。
+ *     旧判据 false ⇒ #166 去锚重发整臂跳过 ⇒ 会话每条消息秒死 404、永久死锁(1.0.93 现网案)。
+ *
+ * ## 放宽的论证(engineErrorCodes `RESUME_AT_ERROR_CODE_PREFIX` 头注要求「放宽须论证」)
+ * 本腿放宽的是**载体**(码位 → 码位∪人话),不是**族**:
+ *   ① 三重合取收敛误触面:`status === 404`(引擎真应答了,不是网络/内部错)+ 人话里出现
+ *      **同一个族前缀**字面 + 调用点自己的 `req.resumeAt !== undefined`(seamQuery #166 臂)
+ *      —— 没带锚的提交压根进不来,与「404 里恰好出现 `resume_at.` 字样」撞车要三件同时成立。
+ *   ② 族边界一字未松,而且文本腿收成**闭集**:只认 `RESUME_AT_TEXT_COMPAT` 里那两对
+ *      「状态 × 括号收尾子码」——`404 × (resume_at.unknown_event)` 与
+ *      `422 × (resume_at.no_session)`,正是 `boot/resolve-spec.ts` 两处**不带 `code`** 的 throw。
+ *      `rewind_snapshot.` / `rewind_files_to.` 邻族不入内(邻族的自动重发安全性没论证过);
+ *      开集形与裸子串形都已被异源复审证伪(token 边界 + 回显注入两条,论证见
+ *      {@link RESUME_AT_TEXT_COMPAT})。带 code 的那一路(core prepare-throw 经 `resumeAtHttpStatus`
+ *      落 4xx)`errorCode` 原样透传,早被 ① 接住,压根不经过这里。
+ *   ③ 422 那一支不是「顺手放宽」:它与 404 支同为预检腿的 codeless throw,处置也同款 —— 去锚重发在
+ *      `no_session` 上不但安全、而且**正是正解**(没有可分支的 session,新起一轮本来就是对的)。
+ *      原形把它留在门外、负控还把「422 恒 false」钉成期望值 —— 那不是负控,是把残余固化成契约。
+ *   ④ 误触的代价上界很低而漏判的代价是死锁:误命中最多多发一次**去锚的**同一条提交(pre-stream
+ *      零副作用,与 draining 同一铁律边界)+ 一行人话;漏判 = 会话再也发不出消息。
+ *   ⑤ 刻意**不**加「粗码必须等于 `request.unprocessable` / `not_found.resource`」这层收窄:那张
+ *      状态码→粗码表是 server `http/send.ts` 的实现细节(会随版本增删),把判据押在它上面等于给自己
+ *      种一颗静默失效的雷;判别力已由 ② 的闭集承担。
+ *
+ * 🔴 根治在发端、且**已经落地**:server 给那四条拒绝子码补上了结构化 `code` 参,新 worker 一律走
+ * 机读腿 ①。本腿因此是**对已发布旧 server 的过渡垫片**(1.0.93 现网用户跑的正是那些),不是长期形;
+ * 等最低 server 版本推过去之后可以整条退役。
+ *
+ * 🔴 只影响本函数的判定,`RESUME_AT_ERROR_CODE_PREFIX` 常量与它的另一个消费点
+ * `isRewindFamilyCode`(rewind 可自解族的**码**判别)一字未动。
  */
 export declare function isResumeAtRejection(err: unknown): boolean;
 /**

package/dist/wireErrorTriage.js

@@ -87,14 +87,101 @@ export function isPreStreamDrainingReject(err) {
     const e = err;
     return typeof e?.status === 'number' && e.status === 503 && e.errorCode === DRAINING_ERROR_CODE;
 }
+/**
+ * #355 D1 文本兼容腿认的**闭集**:server 预检腿两处 codeless throw 的「状态 × 子码」配对,
+ * 且必须以 server 自己那种**括号收尾**的形出现(`…(resume_at.unknown_event)`)。
+ *
+ * 🔴 为什么是闭集而不是开集(异源复审第四轮 [medium] 真病修):这条腿的定位是「**已发布**的旧
+ * server 的兼容垫片」——一个**历史封闭**的集合。新码一律带结构化 `errorCode`(server 已在发端补齐
+ * 四条子码的 `code` 参),走前缀腿 ① 直接命中,根本不经过这里。开集在这里换不来任何前瞻性,却把
+ * 判据暴露在**回显注入**下。
+ *
+ * 🔴 回显注入是真事(亲读 server `config.ts:formatUnmatchableToolNames`):它把**用户送来的**工具名
+ * 逐字拼进错误文本(`… names tool(s) …: <用户的名字> → <guidance>`,多条以 `; ` 连接),再由
+ * `resolve-spec` 翻成一个**普通 codeless 422**。于是「任意 422 + 文本里出现 resume_at.<任意成员>」
+ * 这种开集判据,可以被一条名叫 `resume_at.foo` 的权限规则触发 —— 而那一拍用户的 `resumeAt` 锚是
+ * **有效**的,后果是:壳把有效锚删掉、渲一行「恢复点失效」(与事实不符 = 编造归因)、再重发一次。
+ *
+ * 堵法是**闭集 + 串尾锚**两件一起:
+ *   · 闭集挡住 `resume_at.<任意成员>`;
+ *   · 串尾锚(消费点用 `endsWith`)挡住「用户把整串 `(resume_at.no_session)` 连括号写进权限名」——
+ *     那一形里回显内容后面必然还跟着 ` → guidance`,永远到不了串尾。少了串尾锚,闭集单独是漏的
+ *     (异源复审第五轮实测反证)。
+ * 串尾成立的依据是实证不是假设:7.42.0–7.50.0 七份已发布 server 产物里,这两句的码后面紧跟的就是
+ * 字符串字面量的结束引号。
+ *
+ * 字面单源:两枚子码由 {@link RESUME_AT_ERROR_CODE_PREFIX} 拼出,常量改了这里自动跟。
+ * 认不出 ⇒ 退化成「不自动去锚重发」= 修这一批之前的行为,绝不会更坏。
+ */
+const RESUME_AT_TEXT_COMPAT = [
+    { status: 404, marker: `(${RESUME_AT_ERROR_CODE_PREFIX}unknown_event)` },
+    { status: 422, marker: `(${RESUME_AT_ERROR_CODE_PREFIX}no_session)` },
+];
 /**
  * #166 — `resume_at.*` 错误码族:提交带的 resumeAt 锚服务端不认(Esc 杀锚未持久化的典型形)。
  * 🔴 刻意**不**用 `isRewindFamilyCode`(那是含 `rewind_snapshot.` 的宽形):去锚自动重发的安全性
  * 论证只对 resume_at 族做过,放宽属行为变更(RESUME_AT_ERROR_CODE_PREFIX 头注)。
+ *
+ * ## #355 D1 —— 两条载体腿(2026-08-27)
+ * 同一个语义在 wire 上有**两种形**,此前只认第一种:
+ *   · **机读形**(既有腿,一字未动):core prepare-throw 经 `resumeAtHttpStatus` 落 4xx,
+ *     `errorCode` **原样透传**真子码(`resume_at.not_found` / `resume_at.before_target_not_user` …)
+ *     ⇒ 前缀命中。
+ *   · **包装形**(本腿新增):server 的**预检腿**在 core 之前就 4xx —— `boot/resolve-spec.ts`
+ *     抛 `HttpError(404, "resumeAt: no such message in this session (resume_at.unknown_event)")`
+ *     且**不带** `code`,于是 `http/send.ts` 的 `httpErrorCode(404)` 盖上按状态码派生的粗码
+ *     `not_found.resource`,真子码**只活在人话里**。SDK `classifyApiError` 把 body 的 `error`
+ *     原样搬进 `APIError.message`(scrub 只动 Bearer/presigned),所以壳收到的是
+ *     `{status:404, errorCode:'not_found.resource', message:'…(resume_at.unknown_event)'}`。
+ *     旧判据 false ⇒ #166 去锚重发整臂跳过 ⇒ 会话每条消息秒死 404、永久死锁(1.0.93 现网案)。
+ *
+ * ## 放宽的论证(engineErrorCodes `RESUME_AT_ERROR_CODE_PREFIX` 头注要求「放宽须论证」)
+ * 本腿放宽的是**载体**(码位 → 码位∪人话),不是**族**:
+ *   ① 三重合取收敛误触面:`status === 404`(引擎真应答了,不是网络/内部错)+ 人话里出现
+ *      **同一个族前缀**字面 + 调用点自己的 `req.resumeAt !== undefined`(seamQuery #166 臂)
+ *      —— 没带锚的提交压根进不来,与「404 里恰好出现 `resume_at.` 字样」撞车要三件同时成立。
+ *   ② 族边界一字未松,而且文本腿收成**闭集**:只认 `RESUME_AT_TEXT_COMPAT` 里那两对
+ *      「状态 × 括号收尾子码」——`404 × (resume_at.unknown_event)` 与
+ *      `422 × (resume_at.no_session)`,正是 `boot/resolve-spec.ts` 两处**不带 `code`** 的 throw。
+ *      `rewind_snapshot.` / `rewind_files_to.` 邻族不入内(邻族的自动重发安全性没论证过);
+ *      开集形与裸子串形都已被异源复审证伪(token 边界 + 回显注入两条,论证见
+ *      {@link RESUME_AT_TEXT_COMPAT})。带 code 的那一路(core prepare-throw 经 `resumeAtHttpStatus`
+ *      落 4xx)`errorCode` 原样透传,早被 ① 接住,压根不经过这里。
+ *   ③ 422 那一支不是「顺手放宽」:它与 404 支同为预检腿的 codeless throw,处置也同款 —— 去锚重发在
+ *      `no_session` 上不但安全、而且**正是正解**(没有可分支的 session,新起一轮本来就是对的)。
+ *      原形把它留在门外、负控还把「422 恒 false」钉成期望值 —— 那不是负控,是把残余固化成契约。
+ *   ④ 误触的代价上界很低而漏判的代价是死锁:误命中最多多发一次**去锚的**同一条提交(pre-stream
+ *      零副作用,与 draining 同一铁律边界)+ 一行人话;漏判 = 会话再也发不出消息。
+ *   ⑤ 刻意**不**加「粗码必须等于 `request.unprocessable` / `not_found.resource`」这层收窄:那张
+ *      状态码→粗码表是 server `http/send.ts` 的实现细节(会随版本增删),把判据押在它上面等于给自己
+ *      种一颗静默失效的雷;判别力已由 ② 的闭集承担。
+ *
+ * 🔴 根治在发端、且**已经落地**:server 给那四条拒绝子码补上了结构化 `code` 参,新 worker 一律走
+ * 机读腿 ①。本腿因此是**对已发布旧 server 的过渡垫片**(1.0.93 现网用户跑的正是那些),不是长期形;
+ * 等最低 server 版本推过去之后可以整条退役。
+ *
+ * 🔴 只影响本函数的判定,`RESUME_AT_ERROR_CODE_PREFIX` 常量与它的另一个消费点
+ * `isRewindFamilyCode`(rewind 可自解族的**码**判别)一字未动。
  */
 export function isResumeAtRejection(err) {
     const e = err;
-    return typeof e?.errorCode === 'string' && e.errorCode.startsWith(RESUME_AT_ERROR_CODE_PREFIX);
+    if (typeof e?.errorCode === 'string' && e.errorCode.startsWith(RESUME_AT_ERROR_CODE_PREFIX))
+        return true;
+    // 文本兼容腿:只认闭集里那两对「状态 × 括号收尾子码」(见 {@link RESUME_AT_TEXT_COMPAT})。
+    const marker = RESUME_AT_TEXT_COMPAT.find((c) => c.status === e?.status)?.marker;
+    if (marker === undefined)
+        return false;
+    // 两个人话载体**各自独立判**(异源复审 [medium] 真病修:原形取「第一个非空」,而 SDK
+    // `classifyApiError` 的 `message` 恒非空(缺席时回落 `HTTP <status>`)⇒ `errorMessage` 那条腿在
+    // 「泛化 message + 细节在 errorMessage」的包装形下恒不可达 = 死腿)。
+    //   · `message` = SDK `APIError` 的正身(壳 seamQuery catch 到的就是它,生产真形);
+    //   · `errorMessage` = 同一句话在 wire 体 / `TaskResult` 上的键位(轮询腿把体直接当错误对象抛时的形)。
+    // 结构读不 instanceof:三端共用面,desktop IPC / web 跨 bundle 的同名错误是 plain object。
+    // 🔴 `endsWith` 而不是 `includes`(异源复审第五轮 [medium] 真病修):server 自己那两句**以码收尾**
+    //    (亲验 7.42.0–7.50.0 七份已发布产物,码后紧跟的就是字符串字面量的结束引号);而回显形里用户内容
+    //    后面必然还跟着 ` → guidance`。只认串尾 ⇒ 用户就算把整串 `(resume_at.no_session)` 连括号一起
+    //    写进权限名,它在错误文本里也永远不在串尾,注入这条路彻底堵死。
+    return [e?.message, e?.errorMessage].some((t) => typeof t === 'string' && t.endsWith(marker));
 }
 /**
  * 第 `attempt`(0-based)次 draining 重试前的等待:`err.retryAfterMs`(SDK 若带)封顶优先