@sema-agent/client-core 0.36.0 → 0.38.0

package/dist/model/modelSupplyRules.js

@@ -0,0 +1,149 @@
+/**
+ * modelSupplyRules.ts — **Model Hub 供给面的三端公共判定**(#318 件③ 上收,cli [4752] 预告的
+ * 「resolveEntryVision / computeDeleteBlockers / computeDeleteWarnings 三纯函数」)。
+ *
+ * ── 为什么在这里 ────────────────────────────────────────────────────────────────────────────
+ * 三端(TUI / web / desktop)的 Model Hub 要回答同样的三个问题:
+ *   ① 这条模型档的 `vision` **生效值**是什么、**出处**是哪(自己表态 / 家族缺省 / 没人说过);
+ *   ② 删这条档会不会**断链**(该拒删,并指路);
+ *   ③ 删这条档会不会**悄悄改语义**(该照删,但确认屏必须逐条说出后果)。
+ * 判定放在库里、装配与呈现留端 —— 三端各写一遍的话,三个 Hub 会对「同一条档能不能删」给出三个
+ * 答案,而其中两个是在用户按下 y 之后才被发现的。
+ *
+ * ── 🔴 零 IO(本模块的立身之本)──────────────────────────────────────────────────────────────
+ * 三个函数**只吃已读好的数据**,不碰文件系统、不认识 `models.json` 在哪、不持锁。读盘那半场留在
+ * 各端(壳 = `modelChannels.poolDeleteBlockers` / `poolDeleteWarnings`,它们读完再调这里)。
+ * 分层的判据在 cli 侧成文:`doc === null` 的两义**在调用方分流** —— 本模块只认「已读到的文档」,
+ * 读不出来时由调用方自己产 `unreadable` 阻断(那一刻并不知道谁指着它,fail-closed 拒删比
+ * 「猜没人指着」安全)。
+ *
+ * ── ⚠️ 上收差分(逐条,行为零改动)────────────────────────────────────────────────────────
+ *  · `resolveEntryVision` 的返回型从**内联匿名对象**改为具名 {@link EntryVisionResolution}
+ *    —— 本仓 typeshape 门对导出面的内联匿名形有棘轮(B4)。**结构逐字相同**,壳侧剪切时零适配。
+ *  · `inferFamily` 的来源从壳内 re-export 改为同包 `./providerPresets.js` 直取(壳那份本来就是
+ *    本包的 re-export)。⚠️ 与 #318 件③ 的**分层遮蔽修同批**:修前 `inferFamily(deepseek-*)?.vision`
+ *    结构性恒 `undefined`,所以 `source:'family'` 这一档对 deepseek 族**从来没走到过**;修后才真的
+ *    走得到。上收与修同批落地是刻意的 —— 只上收不修,等于把一条死分支原样搬进三端。
+ *  · `isPlainObject` 在壳里是文件级私有,这里同形自持(不新增公面导出)。
+ */
+import { inferFamily } from './providerPresets.js';
+/** 局部判据:普通对象(非 null、非数组)。与壳侧 `modelChannels.isPlainObject` 同形。 */
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * 解析一条 entry 的 vision **生效值 + 来源**。纯函数(只吃 modelId/vision 两位,零 IO)。
+ *
+ * 🔴 [honest-absence]:家族与 entry 都不表态时给 `undefined`(未知),**不**给 `false`。
+ * ⚠️ 「未知」只是**客户端这一层**诚实:引擎侧 registry-core `ModelEntry.vision` 是
+ * `z.boolean().default(false)`,键缺席在那边就等于 false。**呈现层必须把这个后果一起说出来**,
+ * 别让用户以为「未知」= 引擎会自己去问供应商。
+ */
+export function resolveEntryVision(entry) {
+    if (typeof entry.vision === 'boolean')
+        return { value: entry.vision, source: 'entry' };
+    const fam = inferFamily(entry.modelId)?.vision;
+    if (typeof fam === 'boolean')
+        return { value: fam, source: 'family' };
+    return { value: undefined, source: 'unknown' };
+}
+/**
+ * 纯判定:删这条 entry 会带来哪些**语义变化**(不阻断)。
+ *
+ * 两格,都是「链不断但意思变了」:
+ *   ① `atModelAllowlist` 的**有效名单**会被删空 ⇒ 按 registry-core 语义**全部启用模型都可 @**
+ *      —— 一次静默的权限放宽,必须说;名单里还有别人 ⇒ 只是缩小名单,不用说。
+ *   ② `semaTierGroups` 里有绑定指着它 ⇒ 删完那条绑定悬空 ⇒ 下次按档位解析会落到**另一个模型**上
+ *      (而不是报错),用户会以为「我明明配了 pro 档」。
+ */
+export function computeDeleteWarnings(input) {
+    const { id, doc, tierGroups, survivingIds } = input;
+    const out = [];
+    const allow = doc?.atModelAllowlist;
+    if (Array.isArray(allow)) {
+        // 🔴 判据锚在**有效名单**上,不锚「字面上是不是只有它一个」:落盘闸口会把**所有悬空名**一起
+        // 滤掉,所以 `['victim','already-dangling']` 这种名单删掉 victim 之后有效名单同样变空 = 同样
+        // 放宽到「全部启用模型都可 @」,而 `every(n => n === id)` 那条旧判据对它一声不吭 = 承诺给用户
+        // 的权限提示上的**假阴**。
+        const declared = allow.filter((x) => typeof x === 'string');
+        const effectiveBefore = declared.filter(n => n === id || survivingIds.includes(n));
+        const effectiveAfter = declared.filter(n => n !== id && survivingIds.includes(n));
+        if (effectiveBefore.length > 0 && effectiveAfter.length === 0) {
+            out.push({
+                kind: 'allowlist-empties',
+                consequence: 'it is the last usable model on your @-mention allowlist — deleting it empties the list, which means EVERY enabled model becomes @-mentionable',
+            });
+        }
+    }
+    // 档位绑定的取值序与写路径同源:settings 现值优先,settings 没有档位组时回落 models.json 文件里
+    // 那份投影(只扫 settings 会漏掉「settings 无档位组、models.json 自带 tierGroups」那一格 ——
+    // 那份绑定同样会在写路径被 byId 静默滤掉)。
+    const groups = tierGroups
+        ? Object.entries(tierGroups.groups).map(([g, def]) => [g, def?.tiers ?? {}])
+        : Array.isArray(doc?.tierGroups)
+            ? doc.tierGroups.flatMap(g => isPlainObject(g) && typeof g.name === 'string' && isPlainObject(g.tiers)
+                ? [[g.name, g.tiers]]
+                : [])
+            : [];
+    for (const [group, tiers] of groups) {
+        for (const [tier, ref] of Object.entries(tiers)) {
+            if (ref !== id)
+                continue;
+            out.push({
+                kind: 'tier-binding',
+                consequence: `tier group "${group}" binds the ${tier} tier to it — that binding goes dangling and the ${tier} tier will resolve to a different model`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * 纯判定:这条 entry 现在被哪些**断链类**引用挡着。空数组 = 可以删。
+ *
+ * 🔴 `doc === null` 的两义**在调用方分流**:这里只认「已读到的文档」;读不出来时调用方自己产
+ * `unreadable` 阻断 —— 那一刻我们并不知道谁指着它,fail-closed 拒删比「猜没人指着」安全。
+ */
+export function computeDeleteBlockers(input) {
+    const { id, doc, rosters } = input;
+    const out = [];
+    if (doc && typeof doc.default === 'string' && doc.default === id) {
+        out.push({
+            kind: 'default',
+            where: 'models.json `default`',
+            fix: 'point another model at the default first (Model Hub: select it and press u), then delete this one',
+        });
+    }
+    if (doc && isPlainObject(doc.roles)) {
+        for (const [role, target] of Object.entries(doc.roles)) {
+            // `{ select }` 形是**按 tier/needs 现选**,不是 catalog 引用 —— 删模型影响不到它,不拦。
+            if (!isPlainObject(target) || typeof target.model !== 'string')
+                continue;
+            if (target.model !== id)
+                continue;
+            out.push({
+                kind: 'roles',
+                where: `models.json roles.${role}`,
+                fix: `reassign the "${role}" role to another model first, then delete this one`,
+            });
+        }
+    }
+    if (rosters) {
+        for (const [name, def] of Object.entries(rosters.rosters)) {
+            if (!def || typeof def !== 'object' || !def.slots)
+                continue;
+            for (const [slot, ref] of Object.entries(def.slots)) {
+                if (ref !== id)
+                    continue;
+                // 分阶段(未激活)组同样是真引用:它一被 switchRoster 激活就要按 slot 解析池,指着已删的
+                // entry = 激活当场断链。只看 active.slots 的实现会把分阶段组整个漏掉。
+                const isActive = name === rosters.active;
+                out.push({
+                    kind: 'roster',
+                    where: `roster "${name}" slot ${slot}${isActive ? ' (active)' : ' (staged)'}`,
+                    fix: `point that slot at another model first (/config → Models → rosters), then delete this one`,
+                });
+            }
+        }
+    }
+    return out;
+}

package/dist/model/providerPresets.js

@@ -64,6 +64,47 @@ function presetIndex() {
     presetIndexCache = { exact, stems };
     return presetIndexCache;
 }
+/**
+ * family 表(第④层)的**唯一**匹配器 —— anchored 优先、再 unanchored 兜底。
+ *
+ * 提出来的理由不是整洁,是**单源**:`vision` 位只住在这张表上,而第①/②/③ 层命中时也要能读到它
+ * (见 {@link visionFromFamilyTable})。若两处各写一遍两趟正则,「这个 id 属哪个家族」在同一个函数
+ * 里就会有两个答案。
+ */
+function familyFromTable(id) {
+    for (const fam of MODEL_FAMILIES) {
+        if (fam.match && new RegExp(fam.match, 'i').test(id))
+            return fam;
+    }
+    for (const fam of MODEL_FAMILIES) {
+        if (fam.match && new RegExp(fam.match.replace(/\^/g, ''), 'i').test(id))
+            return fam;
+    }
+    return undefined;
+}
+/**
+ * 🔴 **#318 件③(cli [4752] 自领缺口1)—— `vision` 的分层遮蔽修**。
+ *
+ * 病(修前的真行为,不是假设):`vision` 位只写在 `modelFamilies.json` 上,而那张表只有**第④层**
+ * 读。可是任何真实的 `deepseek-*` id 在**第①层**(preset 大表精确)或**第③层**(家族主干包含)
+ * 就已经命中并 return 了,而这两层的构造器 `hitOf` **不带 vision 位** ⇒ 第④层对它们**结构性不可达**
+ * ⇒ `deepseek4` 行的 `vision: false` **永远读不出来**,壳的 `MODEL_VISION=false` stamp 恒不发生
+ * (下游两处注释自述的行为是死的)。
+ *
+ * 修的形:把 `vision` 从「第④层的一个字段」提成**与 ctx/maxTokens 证据层正交的一次独立查表**。
+ * 判据分工从此是两条轴,各自单源:
+ *   · **容量轴**(contextWindow / maxTokens / perModelCap)= 四层证据,强者先赢 —— 一字不动;
+ *   · **vision 轴** = 恒查 family 表(本函数),与哪一层命中**无关**。
+ * 为什么正交是对的:preset 大表(第①层)根本没有 vision 列,主干匹配(第③层)拿的是**别的模型**
+ * 的行 —— 两者都不是「这个 id 能不能看图」的证据。唯一有这个事实的地方就是 family 表。
+ *
+ * 🔴 **诚实缺席**:表上没标(键缺席)⇒ 返回 `undefined` ⇒ 调用方**不 stamp 这个键**。
+ * 「没人说过这个模型能不能看图」与「确认它不能看图」是两件事,后者会永久封死一个真能力。
+ */
+function visionFromFamilyTable(id) {
+    const fam = familyFromTable(id);
+    return typeof fam?.vision === 'boolean' ? fam.vision : undefined;
+}
 function normalizeId(raw) {
     let id = raw.trim().toLowerCase();
     const slash = id.lastIndexOf('/');
@@ -98,9 +139,23 @@ export function inferFamily(modelId) {
         };
     }
     const id = normalizeId(raw);
+    // vision 轴:与容量证据层**正交**的一次独立查表(#318 件③ 分层遮蔽修,推导见 visionFromFamilyTable)。
+    // 恒按**完整归一 id** 查(不按主干):family 的 match 是锚在 id 上的前缀正则,拿主干去查会把
+    // `deepseek-chat` 的证据换成 `deepseek` 的证据 —— 同族时同解,不同族时是另一个答案。
+    const vision = visionFromFamilyTable(id);
     // ① preset 大表精确(含剥变体尾巴后再试)——精确命中才带 perModelCap(F2 裁决封顶① 证据位;
     //   ③ 层主干匹配拿的是家族参考行,不是该模型的确证 cap)
-    const hitOf = (m, exact = false) => ({ id: m.famId, name: m.famId, match: '', contextWindow: m.contextWindow, maxTokens: m.maxTokens, ...(exact ? { perModelCap: m.maxTokens } : {}) });
+    const hitOf = (m, exact = false) => ({
+        id: m.famId,
+        name: m.famId,
+        match: '',
+        contextWindow: m.contextWindow,
+        maxTokens: m.maxTokens,
+        // 🔴 诚实缺席:表上没标就**不 stamp 键**(`exactOptionalPropertyTypes` 下 `vision: undefined`
+        //    与键缺席不是一回事,消费方读的正是「键在不在」这个三态)。
+        ...(vision !== undefined ? { vision } : {}),
+        ...(exact ? { perModelCap: m.maxTokens } : {}),
+    });
     const exact = idx.exact.get(id);
     if (exact)
         return hitOf(exact, true);
@@ -116,7 +171,16 @@ export function inferFamily(modelId) {
         const n = Number(inline[1]);
         if ((inline[2] === 'k' && n >= 8) || inline[2] === 'm') {
             const ctx = inline[2] === 'm' ? n * 1000000 : n * 1024;
-            return { id: 'inline-cap', name: 'capacity in id', match: '', contextWindow: ctx, maxTokens: Math.min(ctx, 65536) };
+            // vision 轴同样正交透出(`deepseek-v3-128k` 这类 id 在这一层就 return,不透 = 同一个遮蔽病
+            // 换个层复发)。
+            return {
+                id: 'inline-cap',
+                name: 'capacity in id',
+                match: '',
+                contextWindow: ctx,
+                maxTokens: Math.min(ctx, 65536),
+                ...(vision !== undefined ? { vision } : {}),
+            };
         }
     }
     // ③ 家族主干:候选主干=preset model id 剥变体尾;主干出现在待匹配 id 中,取最长主干
@@ -135,16 +199,8 @@ export function inferFamily(modelId) {
     }
     if (best)
         return hitOf(best);
-    // ④ family 表前缀(anchored → unanchored)
-    for (const fam of MODEL_FAMILIES) {
-        if (fam.match && new RegExp(fam.match, 'i').test(id))
-            return fam;
-    }
-    for (const fam of MODEL_FAMILIES) {
-        if (fam.match && new RegExp(fam.match.replace(/\^/g, ''), 'i').test(id))
-            return fam;
-    }
-    return undefined;
+    // ④ family 表前缀(anchored → unanchored)—— 与 vision 轴共用同一个匹配器(单源,见 familyFromTable)
+    return familyFromTable(id);
 }
 /** Format token counts like "1m" / "384k". */
 export function fmtTokens(n) {

package/dist/request/taskRequest.js

@@ -59,7 +59,7 @@ export const REQUEST_FIELD_MATRIX = [
     { field: 'reasoningEffort', lanes: ['interactive'], live: false, why: '`/effort` 拨盘存在 AppState,print 无 AppState', gap: true },
     { field: 'model', lanes: ['interactive'], live: false, why: '`/model` 中途换模型读 toolUseContext.options.mainLoopModel;print 的模型走 MODEL_ID/--model 另一条路', gap: true },
     { field: 'images', lanes: ['interactive'], live: false, why: '贴图提交是交互动作,`-p` 的 stdin 没有图片块' },
-    // ⚠️ 四键一条(0.34.1 补第四键 `resumeAtMode`):它是 `rewindWireCaps` 的 `SeamRewindSpec` 真 wire 键,
+    // ⚠️ 四键一条(0.35.0 补第四键 `resumeAtMode`):它是 `rewindWireCaps` 的 `SeamRewindSpec` 真 wire 键,
     //    且 `rewindSpecForMode` 的 `both` / `conversation` 两臂**恒返**它(排他截语义 —— 回到目标消息
     //    **之前**)。修前合写项只列三键 ⇒ 真 `/rewind` 还原 turn 上 `unregisteredRequestKeys` 会点名
     //    `resumeAtMode`,而那正是「本层不许有未登记键」这条判据的误报,会教端去白名单化真键。
@@ -129,7 +129,7 @@ const shapeTag = (v) => {
 /**
  * plain object 判别 —— 按 **prototype** 判,不按 `Object.prototype.toString` 的标签判。
  *
- * 🔴 标签判法是**假的**(0.34.1 codex 对抗复审 [high] 采纳):`[object Object]` 对**普通类实例**同样
+ * 🔴 标签判法是**假的**(0.35.0 codex 对抗复审 [high] 采纳):`[object Object]` 对**普通类实例**同样
  * 成立,而 `Symbol.toStringTag` 还能让任意载体自报这个标签。放它过去之后,下面的摊开用的是
  * `Object.entries`(**只取自有可枚举键**)—— 于是一个把 `permissions.deny/ask` 挂在**原型 getter**
  * 上的载体会摊出一个**空快照**,请求照发 = 权限静默变宽,正是本节要堵的那个 fail-open 形。
@@ -139,7 +139,7 @@ const shapeTag = (v) => {
  * `Map` / `Date` / boxed 包装对象 / 数组一律拒 —— 它们要么内容不在自有键上,要么摊开就是垃圾键;
  * 「上游产出坏了」比「悄悄发一个更宽的权限面」更该被人看见。
  *
- * 🔴 判据 **realm 无关**(0.34.1 codex 对抗复审第八轮 [medium] 采纳):不拿「**本** realm 的
+ * 🔴 判据 **realm 无关**(0.35.0 codex 对抗复审第八轮 [medium] 采纳):不拿「**本** realm 的
  * `Object.prototype`」做身份比较 —— iframe / `node:vm` / 另一个渲染进程里的对象字面量各有**自己的**
  * `Object.prototype`,身份比较会把这些**完全合法、JSON 忠实**的载体误判成异形,在 web / desktop 宿主
  * 上变成提交前的硬失败。
@@ -242,7 +242,7 @@ const materializeJsonFaithful = (v, path, seen = new Set()) => {
             }
             return { value: items }; // 重建:原数组(可能是子类/带访问器/带覆盖方法)不出门
         }
-        // 🔴 重建成**无原型**记录(0.34.1 codex 对抗复审第七轮 [high] 的可采半场):
+        // 🔴 重建成**无原型**记录(0.35.0 codex 对抗复审第七轮 [high] 的可采半场):
         //   ① 忠实 —— 源本来就允许 `Object.create(null)` 字典,重建成 `{}` 等于把载体形换掉了;
         //   ② 少一条改写面 —— 无原型记录不会继承任何**事后**装到 `Object.prototype` 上的 `toJSON`。
         //   ⚠️ 但这只关掉了 record 那一半:重建出来的**数组**必须是真数组(`Array.isArray` / 序列化成
@@ -264,7 +264,7 @@ const materializeJsonFaithful = (v, path, seen = new Set()) => {
             //    `Object.prototype` 的 setter 上:键整个丢掉、还顺手换了目标对象的原型。
             Object.defineProperty(rec, k, { value: r.value, enumerable: true, writable: true, configurable: true });
         }
-        // 🔴 判据的读法**一律排在捕获之后**(0.34.1 codex 对抗复审第十二轮 [high] 采纳):`toJSON` 走属性
+        // 🔴 判据的读法**一律排在捕获之后**(0.35.0 codex 对抗复审第十二轮 [high] 采纳):`toJSON` 走属性
         //    查找、`isPlainRecord` 走 `getPrototypeOf`/`constructor` —— 这三种读法**都可以带副作用**
         //    (`getPrototypeOf` 陷阱在被问的那一刻把 `deny` 清空),而**原生 `JSON.stringify` 从不问原型**。
         //    校在捕获之前 = 本层自己的读法成了丢内容的那一环(比被动撒谎更糟:那是我们引入的丢失面)。
@@ -281,7 +281,7 @@ const materializeJsonFaithful = (v, path, seen = new Set()) => {
 /**
  * 快照 → 摊开成 `settings` 子键前的两道处理:**具名通道让位** + **畸形响亮拒**。
  *
- * ## ① 具名通道管着的键一律让位(0.34.1)
+ * ## ① 具名通道管着的键一律让位(0.35.0)
  *
  * 快照是**开放集 spread**(子键原样就是 wire 键),所以它天生是一条**第二通道**。0.34.0 只剥了
  * 「车道异名」键(表里那行的 lanes 不含本车道),于是**两条车道都登记**的具名键剥不到 ——
@@ -296,7 +296,7 @@ const materializeJsonFaithful = (v, path, seen = new Set()) => {
  * 🔴 剥得**窄**:只剥表里点名的具名子键。快照**表外**的子键(permissions / env / model / …)
  * 原样摊开 —— 那是开放集的全部意义;`outputStyle` 没有车道行(它是 live 兜底层的位)故不受影响。
  *
- * ## ② 畸形快照响亮拒(0.34.1,fail-closed)
+ * ## ② 畸形快照响亮拒(0.35.0,fail-closed)
  *
  * `undefined` / `null` = **合法缺席**(端没解析出快照;老写法拿 null 当空快照传),照旧降空对象。
  * 其余非 plain-object 形(数组 / 原始值 / boxed 包装对象 / Map / **类实例**…)= **上游产出坏了**:
@@ -305,11 +305,11 @@ const materializeJsonFaithful = (v, path, seen = new Set()) => {
  * `TypeError` 带形状描述(合法载体的判据见 {@link isPlainRecord} —— 「摊得全」是它的全部理由)。
  * (本包是发出去的 npm 公开面:JS 调用方与版本偏斜的宿主都到得了这里,型面拦不住。)
  *
- * ## ③ 权限面**子树**同样要摊得全(0.34.1 codex 对抗复审第二轮 [high] 采纳)
+ * ## ③ 权限面**子树**同样要摊得全(0.35.0 codex 对抗复审第二轮 [high] 采纳)
  *
  * 只校最外层是不够的:`{ permissions: new Map([['deny',['Write']]]) }` 的外层是合法字面量,可
  * `JSON.stringify` 把那只 Map 序列化成 `"permissions":{}` —— deny 规则**静默消失**,与 ② 要堵的
- * 是同一个权限变宽形,只是深了一层。所以 `permissions` 子树递归过 {@link jsonFaithfulPath}:
+ * 是同一个权限变宽形,只是深了一层。所以 `permissions` 子树递归过 {@link materializeJsonFaithful}:
  * plain record / 数组 / JSON 原始值才算摊得全,`Map`/`Set`/类实例/boxed/环一律拒。
  *
  * 🔴 **射程刻意只到 `permissions`**,不做整份请求体的深净化:那是「包级 wire 载荷 JSON-safe
@@ -335,7 +335,7 @@ const resolvedSnapshotForWire = (resolved) => {
     //    当场物化成脱钩副本),原件的形状判据留到最后;校不过就整体拒,拒绝面一字未变。
     const named = namedSettingsSubKeys();
     const out = {};
-    // 🔴 **键先捕获、值逐个即读即处理**(0.34.1 codex 对抗复审第六轮 [high]):`Object.entries(resolved)`
+    // 🔴 **键先捕获、值逐个即读即处理**(0.35.0 codex 对抗复审第六轮 [high]):`Object.entries(resolved)`
     //    会把**所有兄弟键**的值先读齐 —— 于是一个 `env`/`model` 位上的 getter 能在 `permissions` 被
     //    重建**之前**把它的 deny 数组清空(拿到的是同一个引用)。这与内层那条(见
     //    {@link materializeJsonFaithful} 第五条)是同一个病、只是高一层:两层都必须按 stringify 的
@@ -410,7 +410,7 @@ export function buildTaskRequest(input, lane) {
     // resolved 两车道都进表(#292 P1)——它是**开放集 spread**(子键即 wire 键),所以走
     // `laneHas + live` 而不是 `on()`:`on()` 判的是「这个键值非空」,而这里要判的是「这份快照要不要
     // 摊开」。
-    // 🔴 具名通道**赢过快照**这件事不靠下面的合并序(0.34.1):合并序只在具名通道**有值**时管用,
+    // 🔴 具名通道**赢过快照**这件事不靠下面的合并序(0.35.0):合并序只在具名通道**有值**时管用,
     //    而具名门否决时的表现恰恰是**没值**(端不给这个键)。让位改由 `resolvedSnapshotForWire`
     //    做**结构剥离** —— 具名通道管着的子键快照一概不产,顺序此后只是可读性,不再是安全依据。
     const s = input.settings ?? {};

package/dist/retryStatus.d.ts

@@ -9,7 +9,8 @@
  *   recovered    → null     → 覆盖层摘掉(重试**成功**,不是错误 —— 见下)
  *   gave_up      → error+terminal → '✻ <detail>'(重试用尽的终态;与 recovered 反向。**打 terminal 位**,
  *                                    渲染面据此不得再接「· Retrying in Ns」——已经没有下一次了)
- * 绝不捏造 attempt 计数——只用引擎真给的 phase / detail / retryInSec / retryInMs / attempt / maxRetries。
+ * 绝不捏造 attempt 计数——只用引擎真给的 phase / detail / retryInSec / retryInMs / attempt /
+ * maxRetries / errClass(core 5.43.0 起七键)。
  *
  * 🔴 员数与字段补全(2026-08-08,#3004 跟修批)。此前本文件只列 4 相 + 3 字段,而引擎侧
  * (core `BrainStatusPhase` / `BrainStatus`,dist/core/types.d.ts)是 **6 相 + 6 字段**,server 两腿的
@@ -30,11 +31,15 @@ export type RetryStatus =
     deadline: number;
     attempt?: number;
     maxRetries?: number;
+    /** 见 {@link BrainStatusPayload.errClass}(引擎给了才在场;本层只透传,措辞是壳半场)。 */
+    errClass?: BrainRetryErrClass | (string & {});
 } | {
     kind: 'error';
     deadline: number;
     attempt?: number;
     maxRetries?: number;
+    /** 见 {@link BrainStatusPayload.errClass}(引擎给了才在场;本层只透传,措辞是壳半场)。 */
+    errClass?: BrainRetryErrClass | (string & {});
     /**
      * 🔴 **终态位**(2026-08-08 对抗复审命中):`true` ⇔ 引擎**不会再重试了**(`gave_up` 相)。
      * 缺席 = 仍在重试循环里(retrying / rate_limited / circuit_open)。
@@ -65,7 +70,23 @@ export type RetryStatus =
  */
 export declare const BRAIN_STATUS_PHASES: readonly ["rate_limited", "retrying", "reconnecting", "circuit_open", "recovered", "gave_up"];
 export type BrainStatusPhase = (typeof BRAIN_STATUS_PHASES)[number];
-/** wire 上 `status` 臂的载荷(= core `BrainStatus`;server 两腿白名单原样转发这 6 键)。 */
+/**
+ * core `BrainRetryErrClass`(5.43.0)的**类型面镜像** —— 一次重试等待的**原因分桶**,
+ * provider 中立(绝不是 HTTP 状态码 / syscall code / provider 分类法;那些不许过这条通道):
+ *   · `connect_refused` 目标本身给了确定否定(该地址没人 accept / 名字无地址)—— 短梯队服务的那一类;
+ *   · `transport`       其余传输层失败(connect 超时 / reset / 流中断 / 流停滞)—— 全梯队;
+ *   · `rate_limit`      provider 要求放慢;
+ *   · `server`          provider 自报自己这边出错;
+ *   · `http`            状态谓词判终态、但 provider 自己的显式重试裁定说重试;
+ *   · `output_cap`      根本不是连接失败:provider 报上下文超限后按更低 output cap 重发(无退避)。
+ *
+ * 🔴 **刻意没有运行期值镜像**(与 {@link BRAIN_STATUS_PHASES} 不同):本包对 errClass **零分支**
+ * (纯透传),少一个成员没有任何行为后果 —— 开集读会把不认得的桶原样带过去。而 phase 是有 switch
+ * 分支的,少一相会落 default 臂被渲成错话,所以那张表才需要运行期镜像 + engine-vocab 等值门。
+ * 判据锚在「真正决定结果的量」上:决定结果的是有没有分支,不是有没有一张表。
+ */
+export type BrainRetryErrClass = 'connect_refused' | 'transport' | 'rate_limit' | 'server' | 'http' | 'output_cap';
+/** wire 上 `status` 臂的载荷(= core `BrainStatus`;server 两腿白名单原样转发这 7 键)。 */
 export interface BrainStatusPayload {
     /** 闭集 + `(string & {})`:未知相仍可携带(开集读),不必先改类型再解析。 */
     phase: BrainStatusPhase | (string & {});
@@ -79,13 +100,27 @@ export interface BrainStatusPayload {
     attempt?: number;
     /** 引擎这一轮的重试上限。与 `attempt` 一起才能渲「2/5」。 */
     maxRetries?: number;
+    /**
+     * core 5.43.0(#307 双扫 S44,2026-08-19;ADDITIVE)——**这次等待的原因分桶**
+     * (core `BrainRetryErrClass`,provider 中立闭集)。与 `phase`(引擎正在**做什么**)互补:
+     * 本键说的是**为什么**。只在**重试等待帧**上在场且引擎分得出类;`recovered`/`gave_up` 两个终态帧
+     * 与 `circuit_open`(本地快失败,不是观测到的失败)上刻意缺席。
+     *
+     * 🔴 **闭集 + `(string & {})`,读时按开集处理**,与 `phase` 同款纪律:一个部署可以在自己的通道上
+     * 冒出别的桶,认得的照走、认不得的原样带过去 —— 绝不因为「不认得」就把这次等待的原因抹成缺席
+     * (那是把引擎真给的量在本层剥掉,#3004 那批修的正是这一类)。
+     * 缺席 = 引擎没分类,**不得**被渲成某个默认桶。
+     *
+     * 分工:本包只负责让这个事实到得了壳(投影/透传保真),措辞与是否上屏是壳半场。
+     */
+    errClass?: BrainRetryErrClass | (string & {});
 }
 /**
  * 上面那个 interface 的**运行期键镜像**(照 `TOOL_APPROVAL_FRAME_KEYS_MIRROR` 先例):
  * engine-vocab 门 G2-c 拿它与 core `BrainStatus` 的键集逐元素比 ⇒ 引擎 additive 增键当天红。
  * 下面两个类型钉保证镜像与 interface 之间不可能漂移(少键/多键都是编译错)。
  */
-export declare const BRAIN_STATUS_PAYLOAD_KEYS: readonly ["phase", "detail", "retryInSec", "retryInMs", "attempt", "maxRetries"];
+export declare const BRAIN_STATUS_PAYLOAD_KEYS: readonly ["phase", "detail", "retryInSec", "retryInMs", "attempt", "maxRetries", "errClass"];
 /**
  * BrainStatus 载荷 → spinner 行状态。
  *

package/dist/retryStatus.js

@@ -9,7 +9,8 @@
  *   recovered    → null     → 覆盖层摘掉(重试**成功**,不是错误 —— 见下)
  *   gave_up      → error+terminal → '✻ <detail>'(重试用尽的终态;与 recovered 反向。**打 terminal 位**,
  *                                    渲染面据此不得再接「· Retrying in Ns」——已经没有下一次了)
- * 绝不捏造 attempt 计数——只用引擎真给的 phase / detail / retryInSec / retryInMs / attempt / maxRetries。
+ * 绝不捏造 attempt 计数——只用引擎真给的 phase / detail / retryInSec / retryInMs / attempt /
+ * maxRetries / errClass(core 5.43.0 起七键)。
  *
  * 🔴 员数与字段补全(2026-08-08,#3004 跟修批)。此前本文件只列 4 相 + 3 字段,而引擎侧
  * (core `BrainStatusPhase` / `BrainStatus`,dist/core/types.d.ts)是 **6 相 + 6 字段**,server 两腿的
@@ -46,6 +47,8 @@ export const BRAIN_STATUS_PAYLOAD_KEYS = [
     'retryInMs',
     'attempt',
     'maxRetries',
+    // core 5.43.0 跟车一键(#307 双扫 S44,2026-08-19):engine-vocab G2-c 对实装 core 逐键对账。
+    'errClass',
 ];
 const _brainStatusKeyPin = [true, true];
 void _brainStatusKeyPin;
@@ -64,19 +67,26 @@ export function mapBrainStatusToRetry(p, nowMs) {
         ...(typeof p.attempt === 'number' ? { attempt: p.attempt } : {}),
         ...(typeof p.maxRetries === 'number' ? { maxRetries: p.maxRetries } : {}),
     };
+    /**
+     * 原因桶(#307 S44):引擎真给的**非空串**才落位。缺席 / 空串 / 非串 ⇒ 键不 stamp
+     * ——「不知道为什么等」渲成缺席,绝不折成某个默认桶。开集:不认得的桶原样带过去
+     * (本层零分支,认不得也没有可落错的臂)。
+     */
+    const cause = typeof p.errClass === 'string' && p.errClass.length > 0 ? { errClass: p.errClass } : {};
     switch (p.phase) {
         // 🔴 引擎直报「恢复」:摘行。绝不落 error 臂 —— 那是把成功渲成失败。
         case 'recovered':
             return null;
         case 'reconnecting':
-            return { kind: 'stalled', deadline, ...counts };
+            return { kind: 'stalled', deadline, ...counts, ...cause };
         case 'rate_limited':
-            return { kind: 'error', deadline, ...counts, error: { formatted: '', rateLimits: {} } };
+            return { kind: 'error', deadline, ...counts, ...cause, error: { formatted: '', rateLimits: {} } };
         case 'circuit_open':
             return {
                 kind: 'error',
                 deadline,
                 ...counts,
+                ...cause,
                 error: { formatted: p.detail ?? 'Service temporarily unavailable', isNetworkDown: true },
             };
         // 重试用尽:仍是错误行(与 recovered 反向,绝不许一起归成「结束了 ⇒ 清行」),但**打终态位** ——
@@ -84,9 +94,9 @@ export function mapBrainStatusToRetry(p, nowMs) {
         // retrying'),既没有计数也没有 retryIn*,所以「不会再重试了」这件事**只能**由本位表达;
         // 靠 attempt===maxRetries 去推是错的(供给方根本不发那两位)。
         case 'gave_up':
-            return { kind: 'error', deadline, terminal: true, ...counts, error: { formatted: p.detail ?? '' } };
+            return { kind: 'error', deadline, terminal: true, ...counts, ...cause, error: { formatted: p.detail ?? '' } };
         case 'retrying':
         default:
-            return { kind: 'error', deadline, ...counts, error: { formatted: '' } };
+            return { kind: 'error', deadline, ...counts, ...cause, error: { formatted: '' } };
     }
 }

package/dist/seam.d.ts

@@ -389,7 +389,54 @@ export type ChromeEvent = {
  * `actor.hostAsserted` 是消费端唯一能判「这个署名可信吗」的位:渲署名而不渲这个位 = 把一个
  * 未经验证的名字渲成可信的(core 自己的 `[from …]` 渲染就是靠它决定加不加 `(unverified)`)。
  */
- | HumanInputChromeEvent;
+ | HumanInputChromeEvent | EngineNoticeChromeEvent;
+/**
+ * {@link ChromeEvent} 的 `engine_notice` 臂(#310 / #318 件①,server ≥7.36;契约 = server
+ * `ASSISTANT-WIRE-CONTRACT` 附录 D)——「**引擎想让这条会话的人知道一件事**」。
+ *
+ * 为什么**不走 `attachment` 臂**(与 `human_input` 同因):attachment 三条是要在转录流里渲一行的
+ * 东西,而通告是**会话级披露**、且 live/durable 两腿都会到(重放会再看到)⇒ 它需要一个带幂等键、
+ * 带结构化事实的独立臂,塞进 attachment 会逼消费端从一行文案里反解 code。
+ *
+ * 🔴 **宿主消费义务**(全部可选、fail-soft;本臂存在的第一价值 = 帧不再落 `unknown_arm` 被丢弃):
+ *  ① **按 `code` + `detail` 渲染,`message` 只作 fallback**。core 明写
+ *     `memory.session_polluted` 的 message 随 `memoryProvenance` 模式变文 ⇒ **按 message 文本匹配必碎**。
+ *  ② **`code` 是开集,认不得也不许丢**:认得的码渲专用呈现,认不得的码用 `message` 兜底展示。
+ *     库侧**一个码都不硬编**,所以「认不认得」这张表由渲染面自己持有 —— 但它只能决定**怎么渲**,
+ *     不能决定**渲不渲**。
+ *  ③ **幂等消费**:durable 腿重放会再送同一条(与 `workspace_changed` 同纪律),按 `eventId`
+ *     (在场时)或 `code+ts` 去重,别按到达次数计数。
+ *  ④ 🔴 `memory.harvest_quarantined` 的 `moved` 与 `escalated` **不可相减**(就地墓碑同时计入两者,
+ *     core 顶注)—— 两个数各自读、并列呈现,任何减法都会得出一个不存在的量。
+ *  ⑤ 🔴 **缺席不可反推**:server 对非白名单码 / 缺 `sessionId` 的通告**如实不投**(宁缺席不串台),
+ *     全族那一份只在 server 的运维日志里。所以「没收到通告」**不等于**「没发生」,渲染面不许把
+ *     本臂的缺席说成「一切正常」。
+ * 缺席(宿主不接本臂)= 引擎的这类披露在该宿主上看不见,**不是**报错。
+ */
+export interface EngineNoticeChromeEvent {
+    kind: 'engine_notice';
+    laneProof: LaneProof;
+    /** 稳定机器码,点分命名空间(`memory.session_polluted` …)。**开集**——见臂注 ②。 */
+    code: string;
+    /** core 铸的人话行。🔴 **仅 fallback 展示,不是匹配键**;wire 上非串时本位是空串。 */
+    message: string;
+    /** 机器可读事实(逐码不同,开集)。server 已脱敏 + 尺寸 bound,**仍按外部串处理**。 */
+    detail: Record<string, unknown>;
+    /** 归属会话(server 从 `detail` 提升为顶层)。畸形/缺席 ⇒ 本键不在场。 */
+    sessionId?: string;
+    /** **server 观察时刻**(ms epoch),**不是**引擎铸造时刻 —— `EngineNotice` 自身不带时间戳。 */
+    ts?: number;
+    /** durable 重放的稳定身份键 —— **core 铸的事件身份**(uuidv7 形)。wire 今天未必带。 */
+    eventId?: string;
+    /**
+     * durable 重放的**第二层**身份 —— SDK 从 SSE `id:` 字段 stamp 上来的 per-task 序号
+     * (= `task_event.seq`)。对「同一条账本行」稳定,重放会带同一个值。
+     * 🔴 与 {@link EngineNoticeChromeEvent.eventId} 是**两个命名空间**(全局身份 vs per-task 序号),
+     * 绝不互相顶替。消费端幂等序:`eventId` > `eventSeq` > 两者都缺才退 `code+ts`
+     * (最后那一档是有损的:`ts` 是 server 观察时刻(ms),同毫秒同码的两条会被折成一条)。
+     */
+    eventSeq?: string;
+}
 /**
  * `human_input` 臂的署名(core `ActorAssertion` 的投影;server 已 redact 后上帧)。
  * 🔴 `hostAsserted` 是消费端**唯一**能判「这个署名可信吗」的位 —— 渲 `id` 而不渲它,

package/dist/seam.js

@@ -41,6 +41,13 @@ const CHROME_ARM_TABLE = {
         required: false,
         duty: '可选:记进会话审计/时间线(谁把什么喂进了这条 run)。绝不铸 transcript 行(本帧不带正文);渲署名必须跟渲 actor.hostAsserted 的可信度标注',
     },
+    // #318 件①:引擎结构化通告。`required:false` —— 不接 = 这类披露在该宿主上看不见(一个可选的
+    // 披露面),不属「已发生的行为丢失」那一档。🔴 但一旦接,四条硬约束(code+detail 渲 / 未知码
+    // 不许丢 / 重放幂等 / moved-escalated 禁相减)在臂注释里是**真源**,duty 这行只是索引。
+    engine_notice: {
+        required: false,
+        duty: '可选:渲引擎通告(按 code+detail,message 仅 fallback;未知 code 也必须渲不许丢;durable 重放按 eventId 幂等;harvest 的 moved/escalated 并列呈现绝不相减)',
+    },
 };
 /**
  * chrome 臂**覆盖率断言出口**(§8-1 裁决的一半:client-core 定接口不定实现)。

package/dist/subagent/engineSubagentResume.d.ts

@@ -37,6 +37,11 @@
  * `resume.cap` / `resume.session_not_found`(留存失效)/ `steering.still_running`(**它还在跑,
  * 该 steer 不该 resume**)/ `steering.not_running`(本副本无匹配 / run 已 settle)。
  * 判据是 `errorCode` 串(机器轴,开集),**不按 HTTP 数字分支**;未知码原样透传落诚实兜底臂。
+ * ⚠️ **0.38.0(#318 件④)补第七、八格**:`resume.row_recycling`(行正在被裁决 —— **窗口自清,
+ * 过一会儿再发就成**)/ `resume.row_gone`(行已被终态 GC 收走 —— **等也没用,重开新 agent**)。
+ * 这两码在 core 侧早已在铸,是 [4743] #323「completed bg 子代跨重启 SendMessage 复活」把复活裁决
+ * 腿变成常走路径之后才真正会被用户撞见;此前它们双双落进开集兜底,两个不同的下一步被压成一句
+ * 泛泛失败。
  *
  * ── UNTRUSTED ───────────────────────────────────────────────────────────────────────────────
  * 收据 `note` 是 server 铸的文案(引擎会把子代名字拼进去,名字是 spawning model 的自由文本)——
@@ -80,6 +85,19 @@ export type SubagentResumeFailureKind =
  | 'not-resumable'
 /** `steering.ambiguous_target` —— 按名取址撞上同名多员(取址口径本身可分,是唯一「换个地址就成」的一格)。 */
  | 'ambiguous-target'
+/**
+ * `resume.row_recycling`(#318 件④ / [4743] SendMessage 复活语义半场)—— registry 行**正在被裁决**
+ * (另一个复活 claim 或一次 reap sweep 正持着它)。
+ * 🔴 与 `not-resumable` **禁合并**:core 铸文逐字「this clears on its own; send again in a moment」——
+ * 窗口自清,**同一条命令过一会儿就成**。渲成「不可复活」会把一个自愈的瞬时窗说成终局。
+ */
+ | 'row-contended'
+/**
+ * `resume.row_gone`(同上)—— registry 行**已经不存在**(终态 GC 收走了)。
+ * 🔴 与 `row-contended` **禁合并**:这一格**等也没用**,core 给的下一步是「relaunch a new agent」。
+ * 两码合并 = 一半用户白等、另一半白重开。
+ */
+ | 'row-gone'
 /** 404 —— 未知 run / 非属主(**无存在性谕示**,两者同形)。 */
  | 'not-found'
 /** 400 —— 空 content 等入参问题。 */

package/dist/subagent/engineSubagentResume.js

@@ -59,6 +59,13 @@ export function classifySubagentResumeFailure(e) {
         return { reason: 'not-resumable', detail: message };
     if (errorCode === 'steering.ambiguous_target')
         return { reason: 'ambiguous-target', detail: message };
+    // #318 件④([4743] SendMessage 复活语义)—— 复活裁决腿的两码。此前它们双双落进末尾的开集兜底
+    // `error`,于是 core 明明给了**两个不同的下一步**(等一会儿再发 / 重开一个新 agent),到客户端
+    // 只剩一句泛泛失败。判定归包、文案归端:这里只分格,不写出路文案。
+    if (errorCode === 'resume.row_recycling')
+        return { reason: 'row-contended', detail: message };
+    if (errorCode === 'resume.row_gone')
+        return { reason: 'row-gone', detail: message };
     if (errorCode === undefined && status === 404)
         return { reason: 'not-found', detail: message };
     if (errorCode === undefined && status === 400)

package/dist/toolResult.d.ts

@@ -8,6 +8,14 @@ import { type ModelFallbackReason } from './engineErrorCodes.js';
  * 反过来,一个 `{type:'something-else'}` 或裸对象**不算** structured 在场 —— 宁可回落到正则,
  * 也不许把「有个对象」当成「引擎发了结构化」(判据锚在决定结果的量上:决定的是「该不该信正则」)。
  * ⚠️ 与设计稿的口径差:任务书写「29 项」,[1840] 清单逐条数是 **30 项**(见交接报告「设计稿错漏」)。
+ *
+ * 🔴 **本表是 core `CC_DETAIL_TYPES` 的镜像,不是本包自铸的词表**(core
+ * `dist/core/runner/tool-output-projection.js`)。等值由 `scripts/run-engine-vocab-floor-test.mjs` ⑤ 段
+ * 对**实装 core** 双向钉(漏一词 / 多一词都红),对账物 = 本仓 devDep `@sema-agent/core`。
+ * ⇒ **core 提货窗必须跟车对表**:每次抬 devDep core 版本,先跑 engine-vocab 门看这张表红不红,
+ * 红了按 core 那一版的铸点逐词补/删,别改门去迁就表。历史上两次恒绿(5.10 前停 devDep 5.1、
+ * 5.43 前停 devDep 5.20)的病根都不在表本身,在**对账物没跟着抬** —— 表漏一词的实际后果是
+ * 那一类卡永远退回正则解模型面文本,而任何一层都不会响。
  */
 export declare const STRUCTURED_DETAIL_TYPES: ReadonlySet<string>;
 /** structured 在场判别:顶层 `type` ∈ 白名单 ⇒ 返回该 type,否则 undefined(= 不在场)。 */