@sema-agent/client-core 0.30.2 → 0.30.4

package/CHANGELOG.md

@@ -16,6 +16,69 @@
 > 🔴 **互链**(web [C166]⑦):各版「已知局限」段只记**该版新增**;接入面已知局限的完整台账在
 > `docs/INTEGRATION-CLIENTS.md` §6e/§7 —— **只读其一会漏**,两处都过。
 
+## 0.30.4
+
+- **#280 移交两件:probeCause 随卡透传 + tail meta 帧发布口(additive,零 BREAKING)**(2026-08-15;
+  红先绿后,常驻钉 = durable-card-display-keys ⑧ 段 10 checks + pure B7 probeCause 八钉 / B6
+  tail-meta 六钉(含 fail-soft 两钉:sink 同步抛错不撕裂 tail / async 拒绝有界观察零
+  unhandledRejection —— codex 复审 [high] 采纳);壳 #280 围栏 T6 现状锁候本批包透传落地
+  翻红接线):
+  - **件1 `ApprovalCardRequest.probeCause` 透传**(server ≥7.21.0-rc #253 的结构化探针因由,
+    `{code, roots:{shown,total}, further?}`):0.30.3 的两处「帧→卡入参」显式挑键把上游键丢弃 ——
+    活帧腿(`surfaceToolApprovalFrameAndRespond` 的卡入参)与 durable 行腿
+    (`surfaceFsApprovalAndDecide`,载体 = `PendingCheckpoint.riskDescriptor.probeCause`,server 对
+    riskDescriptor 整体透传与活帧同值)。本批两腿共用一把**载体形**判(`isProbeCauseCarrier`:
+    非 null 非数组对象)+ 原样搬运;🔴 内部结构(code/roots/further)**刻意不校** —— 结构校验归
+    呈卡端窄读器(壳 `probeCauseNote.readProbeCauseKey`),包只搬运,unknown 开集类型
+    (`ToolApprovalFrame.probeCause` / `ApprovalCardRequest.probeCause` 两位,agent-types 无现成形)。
+    帧键镜像 15→16 键;`probeCause` **领先** sdk 6.17.2 运行期锚一代 ⇒ 对账门 AHEAD_OF_ANCHOR
+    带退出条件登记(#144 persistedRuleShadowed 同形先例)。超集台账 `docs/type-superset.json`
+    补 `cc-counterpart-addition` 一条(CC 近邻 = `CanUseTool` options 的 `decisionReason`/
+    `blockedPath` 散文/标量位,差在结构化)。
+  - **件2 tail `event: meta` 帧发布口**(`engineSubagentTail.ts`):0.30.3 消费循环
+    `ev.event !== 'forward'` continue 把 meta 帧结构性 skip ⇒ `contentFrames` 供给形判别位
+    (server e439a6c,闭集 {on, progress_only, unknown} ——「内容永远不会来 vs 还没来」的唯一
+    诚实依据)到不了端。本批循环改帧分类闸(switch):meta 经新可装口
+    `installSubagentTailMetaSink`(载荷 `SubagentTailMeta = {taskId, meta}`,meta 为帧开集原文,
+    判别位窄读归消费端)发布后仍不进内容面;🔴 开闸范围**只放 meta**,heartbeat/未来非 forward
+    帧维持 skip。不装 sink = 0.30.3 现状字节不变。公面 +3 名
+    (`installSubagentTailMetaSink` 运行期导出 + `SubagentTailMeta`/`SubagentTailMetaSink` 类型),
+    baseline 706→707;singleton 台账补 `tailMetaSink`(high,ceiling 89→90 成文理由)。
+  - 已知局限(本版新增):meta 判别位的**消费臂在端上**(壳 #280 围栏 T6 翻红后接线);
+    `riskDescriptor.probeCause` 与 `shadowedRule` 同样不在 SDK `PendingCheckpoint.riskDescriptor`
+    声明里(类型半场候 SDK 班车,durable 腿为结构视图读)。
+
+## 0.30.3
+
+- **#244 F3 wire/会话判定上收 · 包半场(A-028.9/.10/.11/.12/.13/.15 族E;新三件
+  `principalWire.ts` / `wireErrorTriage.ts` / `sessionMap.ts`,+14 公面运行期导出)**(2026-08-15;
+  常驻钉 = `run-client-core-pure-test.mjs` F3E 段 58 checks):
+  - 🔴 **BEHAVIOR CHANGE(A-028.10,cli 主会话裁定)**:`engineWireTargetFor()` 的 principal
+    在场性判定从裸 truthy 收编为 **trim 判**(新原语 `normalizeWirePrincipal`)——
+    **全空白** `SEMA_LIVE_PRINCIPAL`(env 臂)与全空白 `installed.principal`(显式装配臂)
+    从「发出全空白 `x-agent-principal` 头」改为「键缺席=不发头(owner-null)」。
+    理由:F-011 停发纪律([3279])的语义是「缺席=不发头,绝不铸哨兵值」,全空白值是垃圾值
+    伪装在场 —— 壳 `livePrincipal.ts` 早已按 trim 判(裁定=壳语义为正),包侧对齐消除两侧
+    判定相反的分脑。同批 `makeEngineWireClient` 的 `!== ''` 判升级为同一把 trim 尺
+    (全空白 principal 同罪归缺席)。非空白实值(含空白包围形如 `' alice '`)一字不动。
+  - **`wireErrorTriage.ts`(A-028.11/.13 新件)**:turn 错误分型判定半场
+    (`classifyTurnWireError` 四臂:http / stream-ended-without-terminal / transport / internal;
+    `isWireTransportError` / `isPreStreamDrainingReject` / `isResumeAtRejection` /
+    `drainingRetryDelayMs` / `WIRE_NETWORK_ERROR_PATTERN`)+ scenario 拒绝判型
+    (`scenarioDenyFromError`,allowlist 防御过滤单源)。语义 = cli `seamQuery` /
+    `engineTarget.isEngineTransportError` / `scenarioNotAllowedCopy` 逐字,人话文案与渲染归端;
+    web `turn-error-classify.ts` 第二实现与逐 token 跨仓 parity 门的退役半场归 web(发布帖点名)。
+  - **`sessionMap.ts`(A-028.12 新件)**:「客户端会话 id ↔ 引擎会话 id」映射的单一键形
+    (`SessionMapRecord` / `EngineSessionEntry`,壳形为正)+ `engineNamespaceKeyFor` +
+    两个纯 merge 判定(`mergeSessionMapRecord` / `mergeEngineEntry`,拒写带 reason 出境)+
+    `SessionMapStorePort`(存储归端:cli 文件锁/原子写,web localStorage)。
+  - **`engineErrorCodes.ts` +3 常量**:`DRAINING_ERROR_CODE` / `SCENARIO_NOT_ALLOWED_ERROR_CODE` /
+    `RESUME_AT_ERROR_CODE_PREFIX`(`REWIND_ERROR_CODE_PREFIXES[0]` 改引同源;resume_at 窄形
+    刻意不并入 rewind 宽形 —— 自动重发安全性论证只对 resume_at 族成立)。
+  - **`applyLiveRequestDefaults` 补 `additionalReadDirectories` 位(A-028.9)**:壳独有真行为
+    (#257 配置目录+tmp 族只读宽根)上收 —— 值(广度闸/realpath 判决)归端算,包做
+    「缺席时补位」;`LIVE_DEFAULT_FIELDS` 九件→十件,`unregisteredRequestKeys` 门随表跟上。
+
 ## 0.30.2
 
 - **#244 F2 HITL 规则侧上收 · 包半场(A-028.14 + parseLocalAllowRule 硬排期件;hitl/ 新两件,

package/README.md

@@ -35,7 +35,7 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-**Version:** 0.30.2
+**Version:** 0.30.4
 
 - **Today** — the adapter seam, the whole `adapt()` pipeline (all 14 A-layer arms plus the
   B/D/E tool-card layers), the notification/caps/model families, the adapter kernel (stream driver

package/dist/engineErrorCodes.d.ts

@@ -88,6 +88,13 @@ export declare const STOP_PARKED = "stop.parked";
 export declare const STOP_CONFLICT_CODES: readonly ["stop.park_arbiter_unreachable", "stop.park_resume_won", "stop.not_landed", "stop.not_local", "stop.parked"];
 /** `outputSchema` 任务在重试上限内没能产出合法结构化输出(语义字面就是 CC 那个 subtype 的话)。 */
 export declare const OUTPUT_INVALID = "output.invalid";
+/**
+ * `resume_at.*` 单族前缀(A-028.11 单源化,#244 族E):壳 `isResumeAtRejection`(Esc 杀锚后的
+ * 一次性去锚自动重发判型)此前持裸字面 `'resume_at.'` —— 收编到本表。🔴 它**刻意窄于**
+ * {@link REWIND_ERROR_CODE_PREFIXES}(不含 `rewind_snapshot.`):自动重发的安全性论证只对
+ * resume_at 族做过(pre-stream 零副作用),扩到全 rewind 族属行为变更,须另立项。
+ */
+export declare const RESUME_AT_ERROR_CODE_PREFIX = "resume_at.";
 /**
  * 用户**可自解**的操作性错误的码前缀(选错回退目标 / 回退过根 / 快照缺失)。
  * 消费点把 code 附在 message 后便于对账 —— 这一族是「你的操作有问题」,不是「引擎坏了」。
@@ -96,6 +103,16 @@ export declare const OUTPUT_INVALID = "output.invalid";
 export declare const REWIND_ERROR_CODE_PREFIXES: readonly ["resume_at.", "rewind_snapshot."];
 /** 该码是否属 rewind/resume 可自解族。缺席 ⇒ false。 */
 export declare function isRewindFamilyCode(code: string | undefined): boolean;
+/**
+ * server 温切 drain 门的 pre-stream 拒收码(503 + `errorCode:"draining"`;server 侧
+ * `error:"draining"` 是冻结契约,SDK toApiError 盖成 `errorCode`)。此前壳/包注释各持裸字面。
+ */
+export declare const DRAINING_ERROR_CODE = "draining";
+/**
+ * 场景执法拒绝码(service gateScenarioRequest 的 400;SDK `ScenarioNotAllowedError`)。
+ * 判型半场见 wireErrorTriage.scenarioDenyFromError;allowlist 渲染归各端。
+ */
+export declare const SCENARIO_NOT_ALLOWED_ERROR_CODE = "scenario_not_allowed";
 /**
  * 15 分钟流帽(server `src/http/sse-log.ts`)。
  * 🔴 **到达 ≠ run 死了** —— 帧自己就说「run 仍然活着」。正确处置 = 按 `Last-Event-ID` 重连续读

package/dist/engineErrorCodes.js

@@ -121,16 +121,34 @@ export const STOP_CONFLICT_CODES = [
 /** `outputSchema` 任务在重试上限内没能产出合法结构化输出(语义字面就是 CC 那个 subtype 的话)。 */
 export const OUTPUT_INVALID = 'output.invalid';
 // ── rewind / resume 族(core 1.292 [833])────────────────────────────────────────────────────
+/**
+ * `resume_at.*` 单族前缀(A-028.11 单源化,#244 族E):壳 `isResumeAtRejection`(Esc 杀锚后的
+ * 一次性去锚自动重发判型)此前持裸字面 `'resume_at.'` —— 收编到本表。🔴 它**刻意窄于**
+ * {@link REWIND_ERROR_CODE_PREFIXES}(不含 `rewind_snapshot.`):自动重发的安全性论证只对
+ * resume_at 族做过(pre-stream 零副作用),扩到全 rewind 族属行为变更,须另立项。
+ */
+export const RESUME_AT_ERROR_CODE_PREFIX = 'resume_at.';
 /**
  * 用户**可自解**的操作性错误的码前缀(选错回退目标 / 回退过根 / 快照缺失)。
  * 消费点把 code 附在 message 后便于对账 —— 这一族是「你的操作有问题」,不是「引擎坏了」。
  * 前缀形(不是成员形)= 开集:这一族里每加一个新码,判别自动跟上。
  */
-export const REWIND_ERROR_CODE_PREFIXES = ['resume_at.', 'rewind_snapshot.'];
+export const REWIND_ERROR_CODE_PREFIXES = [RESUME_AT_ERROR_CODE_PREFIX, 'rewind_snapshot.'];
 /** 该码是否属 rewind/resume 可自解族。缺席 ⇒ false。 */
 export function isRewindFamilyCode(code) {
     return typeof code === 'string' && REWIND_ERROR_CODE_PREFIXES.some((p) => code.startsWith(p));
 }
+// ── drain / 场景执法族(A-028.11/.13 单源化,#244 族E,2026-08-15)────────────────────────────
+/**
+ * server 温切 drain 门的 pre-stream 拒收码(503 + `errorCode:"draining"`;server 侧
+ * `error:"draining"` 是冻结契约,SDK toApiError 盖成 `errorCode`)。此前壳/包注释各持裸字面。
+ */
+export const DRAINING_ERROR_CODE = 'draining';
+/**
+ * 场景执法拒绝码(service gateScenarioRequest 的 400;SDK `ScenarioNotAllowedError`)。
+ * 判型半场见 wireErrorTriage.scenarioDenyFromError;allowlist 渲染归各端。
+ */
+export const SCENARIO_NOT_ALLOWED_ERROR_CODE = 'scenario_not_allowed';
 // ── 流控族(SDK 6.2.0 CB-1/TR-6 的 `error` 臂)───────────────────────────────────────────────
 /**
  * 15 分钟流帽(server `src/http/sse-log.ts`)。

package/dist/engineWireSdk.js

@@ -22,6 +22,7 @@
  * principal 时省略该头,迁移后恒出示,对 requirePrincipal 部署是 fail-open 改善,已记账。
  */
 import { AgentClient } from '@sema-agent/sdk';
+import { normalizeWirePrincipal } from './principalWire.js';
 /** loopback 判定(engineTarget.isLoopbackEngineUrl 逐字镜像;解析失败=非 loopback)。 */
 export function isLoopbackWireUrl(url) {
     try {
@@ -72,10 +73,12 @@ export function wireAuthTokenFor(baseUrl, token) {
  */
 export function makeEngineWireClient(cfg) {
     try {
+        const principal = normalizeWirePrincipal(cfg.principal);
         const base = {
             baseUrl: cfg.baseUrl,
             // F-011 停发:缺席/空串=不给键(SDK 6.11 缺席=不发 x-agent-principal 头,owner-null)。
-            ...(cfg.principal !== undefined && cfg.principal !== '' ? { principal: cfg.principal } : {}),
+            // A-028.10(0.30.3):空串判升级为 trim 判(principalWire 同尺)——全空白值同罪,归缺席。
+            ...(principal !== undefined ? { principal } : {}),
             ...(cfg.timeoutMs !== undefined ? { timeoutMs: cfg.timeoutMs } : {}),
             maxRetries: cfg.maxRetries ?? 0,
             ...(cfg.fetchImpl ? { fetch: cfg.fetchImpl } : {}),

package/dist/engineWireTarget.d.ts

@@ -1,7 +1,9 @@
 export interface EngineWireTarget {
     baseUrl: string;
     token?: string;
-    /** 缺席=不发 x-agent-principal 头(owner-null,F-011 停发);显式装配/env 值恒赢。 */
+    /** 缺席=不发 x-agent-principal 头(owner-null,F-011 停发);显式装配/env 值恒赢。
+     *  A-028.10(0.30.3):在场性按 trim 判(principalWire 原语)——全空白值在**读出口**归缺席,
+     *  绝不发全空白头(裁定=壳 livePrincipal trim 语义为正)。 */
     principal?: string;
 }
 /** 装/卸引擎 wire 目标。传 null 卸回 env 派生。返回还原函数。 */

package/dist/engineWireTarget.js

@@ -19,6 +19,7 @@
  */
 import { hostEnv } from './hostEnv.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from './sessionSlot.js';
+import { normalizeWirePrincipal } from './principalWire.js';
 /** 显式装配(非 Node 宿主唯一的入口;装了就**优先于** env,便于桌面/web 一页多引擎)。
  *  W1(design/161):sessionKey → 注册表;零参 API = DEFAULT_SESSION_KEY 兼容层。 */
 const installedByKey = createSessionSlot();
@@ -47,19 +48,29 @@ export function engineWireTarget() {
  */
 export function engineWireTargetFor(sessionKey) {
     const installed = installedByKey.get(sessionKey) ?? null;
-    if (installed !== null)
-        return installed;
+    // A-028.10 显式装配臂(0.30.3 BEHAVIOR CHANGE):装配值里全空白 principal 在读出口归缺席
+    // (键不出现)——与 env 臂同一把 trim 尺;其余键原样。非空白值(含带空白包围的实值)一字不动。
+    if (installed !== null) {
+        const p = normalizeWirePrincipal(installed.principal);
+        if (p === installed.principal)
+            return installed;
+        const { principal: _dropped, ...rest } = installed;
+        return rest;
+    }
     const env = hostEnv();
     const baseUrl = env.SEMA_LIVE_BASEURL;
     if (!baseUrl)
         return null;
+    // principal must match the run's owner (stamped by the live stream) — the owner-gated routes answer
+    // 404 for non-owners (no existence oracle). F-011 停发([3279]):缺席=不发头,owner-null 两侧
+    // 对齐(server 7.8.1 读写面窄互认盖存量);显式 SEMA_LIVE_PRINCIPAL 恒赢,绝不铸哨兵值。
+    // A-028.10(0.30.3 BEHAVIOR CHANGE):裸 truthy → trim 判定 —— 全空白 env 值此前会发出
+    // 全空白 x-agent-principal 头(垃圾值伪装在场),现归缺席(键不出现),与壳 livePrincipal 同尺。
+    const envPrincipal = normalizeWirePrincipal(env.SEMA_LIVE_PRINCIPAL);
     return {
         baseUrl,
-        // principal must match the run's owner (stamped by the live stream) — the owner-gated routes answer
-        // 404 for non-owners (no existence oracle). F-011 停发([3279]):缺席=不发头,owner-null 两侧
-        // 对齐(server 7.8.1 读写面窄互认盖存量);显式 SEMA_LIVE_PRINCIPAL 恒赢,绝不铸哨兵值。
         ...(env.SEMA_LIVE_TOKEN ? { token: env.SEMA_LIVE_TOKEN } : {}),
-        ...(env.SEMA_LIVE_PRINCIPAL ? { principal: env.SEMA_LIVE_PRINCIPAL } : {}),
+        ...(envPrincipal !== undefined ? { principal: envPrincipal } : {}),
     };
 }
 /** 诊断开关(壳侧 `process.env.SEMA_DEBUG` 的等价读;本包零 process)。 */

package/dist/hitl/toolApprovalWire.d.ts

@@ -238,6 +238,18 @@ export interface ApprovalCardRequest {
      * 压根没有规则命中(缺席),而命中且清掉了的那些根本不会变成卡。
      */
     persistedRuleShadowed?: string;
+    /**
+     * 结构化探针因由(#280 件1,0.30.4;server ≥7.21.0-rc #253)——**双源合流**
+     * ({@link governanceForced} 同形,两腿在场性可以不一致):
+     *   · **活卡帧腿**:{@link ToolApprovalFrame.probeCause} 原样;
+     *   · **durable park 行腿**:`PendingCheckpoint.riskDescriptor.probeCause`(server 对
+     *     riskDescriptor 整体透传,与活帧同值 —— core `buildRiskDescriptor` 铸)。
+     * 🔴 **开集(unknown),包只搬运**:载体形判(非 null 非数组对象)之外零校验零改写 ——
+     * 内部结构(code/roots/further)的窄读、消毒与呈现全部归端(壳 `probeCauseNote` 窄读器:
+     * 形不合整只按缺席,呈现走 wireNote 车道)。缺席 = 无因由/老引擎/坏载体形(三者同形,不猜),
+     * 卡形字节不变。UNTRUSTED-for-display:code/roots 是工具作文面,只渲染绝不回喂模型/工具入参。
+     */
+    probeCause?: unknown;
 }
 /**
  * 🔴 **拆缝口** —— 弹「三选卡」并等人的决断。壳 = vendored CC `PermissionRequest`;
@@ -352,6 +364,28 @@ export interface ToolApprovalFrame {
      * 耐久对偶仍未消费——那一路是独立的一件,不在本键的施工面内。
      */
     persistedRuleShadowed?: string;
+    /**
+     * server ≥7.21.0-rc(#253 件 G1,core 5.33.0 backlog #239;**ADDITIVE**,`"tool_approval"` only。
+     * 真发直证 = engine 7.22.0 fixture `@sema-agent/server/dist/tool-approval.d.ts` 同名键)——
+     * 这只 ask **为什么**被收紧的**结构化探针因由**:被拦工具自声明 `reversibilityProbe` 且判不出
+     * 可回滚时,引擎在 maybe 档收紧点铸;wire 契约形 = `{ code, roots:{shown,total},
+     * further?:{shown,total} }`(server `ProbeCauseSchema` `.strict()`,活卡帧与 durable `card_json`
+     * 经同一 `readProbeCause` 单点铸造 ⇒ 两面结构性同值)。
+     *
+     * 🔴 **本包刻意不拥有这个形**(类型 = unknown 开集;#280 件1,0.30.4):内部结构(code/roots/
+     * further)的校验与呈现归呈卡端的窄读器(壳 `probeCauseNote.readProbeCauseKey` 同款「形不合整只
+     * 按缺席」纪律),包只做**载体形**判(非 null 非数组对象)+ 原样搬运 —— 两层各校一遍会让
+     * 「谁把键窄没的」在排障时说不清,且包侧校严一档就把上游 additive 内键挡在边界外。
+     * 🔴 **缺席 ≠「没有原因」**:只有 maybe 档收紧且探针真给了 cause 的 ask 才有它(工具 opt-in
+     * 供给,非常驻字段 —— [3980] test 定谳的负控:mandate 路径 ask 帧不带)。
+     * 🔴 本键**领先** SDK 运行期锚一代(sdk 6.17.2 的 `TOOL_APPROVAL_FRAME_KEYS` 尚无)⇒ 对账门
+     * (run-approval-frame-keys-test.mjs)AHEAD_OF_ANCHOR 带退出条件登记,#144
+     * `persistedRuleShadowed` 同形先例:SDK 锚补上当天登记自红逼删。
+     * 耐久路对偶 = `PendingCheckpoint.riskDescriptor.probeCause`(同值;server 对 riskDescriptor
+     * 整体透传),由 {@link surfaceFsApprovalAndDecide} 的行 → 卡重铸处消费。
+     * UNTRUSTED-for-display:code/roots 是工具作文面(server 已 redact),端呈前消毒,只渲染绝不回喂。
+     */
+    probeCause?: unknown;
 }
 /** {@link ToolApprovalFrame.delegation} 的形(命名形,不用内联匿名 —— typeshape 门 B4 棘轮口径)。 */
 export interface ToolApprovalDelegation {
@@ -367,7 +401,7 @@ export interface ToolApprovalDelegation {
  * `TOOL_APPROVAL_FRAME_KEYS` 比对——SDK additive 增键时对账当天红,不再人肉追平。
  * 下面两个类型钉保证镜像与 interface 本身不可能漂移(少键/多键都是编译错)。
  */
-export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "persistedRuleShadowed", "delegation", "outcome"];
+export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "persistedRuleShadowed", "probeCause", "delegation", "outcome"];
 /** 子代帧判别:显式键 fromSubagent(core 1.378 RB-39②)优先;缺席退 sourceTaskId 在场性权宜式
  *  (server 1.258 [1549]①3,旧代际兼容)。 */
 export declare function isFromSubagent(frame: ToolApprovalFrame): boolean;

package/dist/hitl/toolApprovalWire.js

@@ -255,6 +255,11 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
     // 合形窄化,落**只读键**(红线见 ApprovalCardRequest.ruleSuggestionsReadOnly 顶注:/decide
     // 无规则位,落可兑付位=假 affordance)。
     const ruleSuggestionsReadOnly = readRuleSuggestions(pending.ruleSuggestions);
+    // #280 件1(0.30.4):durable 行腿的探针因由载体 = `riskDescriptor.probeCause`(server 对
+    // riskDescriptor 整体透传,与活卡帧同值)。SDK 6.17.2 的 riskDescriptor 声明尚无此键 ⇒ 结构
+    // 视图读(与 caps 防御读同款姿势),类型半场候 SDK 班车;载体形不合 ⇒ 不铸键(内部结构不校,
+    // 归呈卡端窄读器 —— isProbeCauseCarrier 顶注)。
+    const durableProbeCause = pending.riskDescriptor?.probeCause;
     const card = await surfaceApprovalCard({
         toolName,
         args,
@@ -262,6 +267,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
         ...(signal ? { signal } : {}),
         ...(pending.governanceForced === true ? { governanceForced: true } : {}),
         ...(ruleSuggestionsReadOnly !== undefined ? { ruleSuggestionsReadOnly } : {}),
+        ...(isProbeCauseCarrier(durableProbeCause) ? { probeCause: durableProbeCause } : {}),
     });
     switch (card.kind) {
         case 'failed':
@@ -347,6 +353,11 @@ export const TOOL_APPROVAL_FRAME_KEYS_MIRROR = [
     // (sdk 6.14.0/6.15.0 的 TOOL_APPROVAL_FRAME_KEYS 都还没有它)⇒ 对账门里有一条**带退出条件**的
     // 领先登记(AHEAD_OF_ANCHOR):SDK 锚一旦补上,那条登记当场红,逼人删登记而不是让豁免长住。
     'persistedRuleShadowed',
+    // #280 件1(client-core 0.30.4):server 7.21.0-rc(#253)起真发 `probeCause`(直证 = engine
+    // 7.22.0 fixture 的 `@sema-agent/server/dist/tool-approval.d.ts`)。⚠️ 本键**领先** SDK 运行期锚
+    // 一代(sdk 6.17.2 尚无)⇒ 对账门里有一条带退出条件的领先登记(AHEAD_OF_ANCHOR),SDK 锚一旦
+    // 补上,那条登记当场红,逼人删登记回到逐元素相等 —— #144 persistedRuleShadowed 同形先例。
+    'probeCause',
     'delegation',
     'outcome',
 ];
@@ -458,6 +469,16 @@ function pathFromGateMessage(message) {
  * 渲一个按下去必被 server 拒的选项。上限 8 条(server 端候选本就 ≤2,超长=坏形,截不留痕会
  * 掩盖注入,整体降缺席)。
  */
+/**
+ * `probeCause` 的**载体形**判(#280 件1):非 null 非数组对象才搬运(wire 契约的载体就是对象,
+ * 串/数/数组/null 是坏载体不是「另一种因由」)。刻意只判到这一层 —— 内部结构(code/roots/further)
+ * 校验归呈卡端窄读器(server `readProbeCause` 的消费端对偶,壳 `probeCauseNote.readProbeCauseKey`),
+ * 包内校严一档就会把上游 additive 内键挡在边界外,还让「谁把键窄没的」在排障时多一层嫌疑。
+ * 两条决断腿(活帧/durable 行)共用这一把,判词绝不各写各的。
+ */
+function isProbeCauseCarrier(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
 function readRuleSuggestions(v) {
     if (!Array.isArray(v))
         return undefined;
@@ -570,6 +591,9 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         ...(typeof frame.persistedRuleShadowed === 'string' && frame.persistedRuleShadowed.trim() !== ''
             ? { persistedRuleShadowed: frame.persistedRuleShadowed }
             : {}),
+        // #280 件1(0.30.4):探针因由随卡透传 —— 载体形判之外零校验零改写(内部结构归呈卡端窄读器,
+        // isProbeCauseCarrier 顶注);缺席/坏载体 ⇒ 键不 stamp,卡形字节不变。
+        ...(isProbeCauseCarrier(frame.probeCause) ? { probeCause: frame.probeCause } : {}),
     });
     const decision = card.kind === 'allow' ? (card.allowSession ? 'allow_session' : 'allow') : 'deny';
     if (card.kind === 'failed') {

package/dist/index.d.ts

@@ -208,6 +208,9 @@ export * from './subagent/engineCompactWire.js';
 export * from './subagent/engineSubagentTail.js';
 export * from './engineSessionParam.js';
 export * from './engineWireTarget.js';
+export * from './principalWire.js';
+export * from './wireErrorTriage.js';
+export * from './sessionMap.js';
 export * from './detachWire.js';
 export * from './workflowMonitor.js';
 export * from './workflowClient.js';

package/dist/index.js

@@ -269,6 +269,16 @@ export * from './subagent/engineCompactWire.js';
 export * from './subagent/engineSubagentTail.js';
 export * from './engineSessionParam.js';
 export * from './engineWireTarget.js';
+// ── A-028 族E(#244 F3,2026-08-15)────────────────────────────────────────────────────────────
+// · principalWire:principal 在场性 trim 原语(A-028.10 裁定=壳语义为正;engineWireTarget 两臂 +
+//   makeEngineWireClient 同尺,壳 livePrincipal 闸口消费同一原语)。
+export * from './principalWire.js';
+// · wireErrorTriage:turn 错误分型判定半场(A-028.11;文案/渲染归端)+ scenario 拒绝判型
+//   (A-028.13;web 逐字节同形过滤行的正主)。码字面引 engineErrorCodes。
+export * from './wireErrorTriage.js';
+// · sessionMap:「客户端会话 id ↔ 引擎会话 id」映射单一键形 + merge 判定(A-028.12;存储经
+//   SessionMapStorePort 归端 —— cli 文件锁/原子写,web localStorage)。
+export * from './sessionMap.js';
 // B6 余项①:headless detach wire(**拆**:判定+cancel-arm 台账进包,信号路径裸 fetch 发射留宿主
 // —— 设计稿 §3 表脚注「`:221` 裸 cancel = TUI 留」;宿主取件口 = `detachCancelArm()`)。
 export * from './detachWire.js';

package/dist/principalWire.d.ts

@@ -0,0 +1,18 @@
+/**
+ * principalWire.ts — principal 在场性判定的**唯一原语**(A-028.10,#244 族E,2026-08-15)。
+ *
+ * 裁定背景(cli 主会话裁,census top-07 §2):壳 `livePrincipal.ts` 与本包
+ * `engineWireTarget.engineWireTargetFor()` 各持一条 principal 解析,且**语义相反**:壳判
+ * `v && v.trim() !== ''`(全空白=缺席),包侧裸 truthy(全空白=在场)⇒ `SEMA_LIVE_PRINCIPAL='   '`
+ * 会发出一个全空白的 `x-agent-principal` 头 —— 垃圾值伪装在场,破坏 F-011 停发纪律
+ * ([3279]:缺席=不发头,owner-null;绝不铸哨兵值)。裁定=壳 trim 语义为正,包侧两臂
+ * (env 派生臂 + 显式装配臂)都收编本原语。
+ *
+ * 🔴 语义逐字(壳 `resolveLivePrincipal` 的判定半场):
+ *   · undefined / '' / 全空白 ⇒ undefined(键缺席,不发头);
+ *   · 其余 ⇒ **原值原样返回**(不 trim 改写 —— ` alice ` 照发 ` alice `,在场性判定与值改写
+ *     是两件事,本原语只做前者)。
+ * env 的读取方式留在端上(壳读 `process.env`,包内经 `hostEnv()`)——本原语零 IO 零 env。
+ */
+/** principal 在场性判定:全空白=缺席(undefined);实值原样返回(绝不改写)。 */
+export declare function normalizeWirePrincipal(v: string | undefined): string | undefined;

package/dist/principalWire.js

@@ -0,0 +1,20 @@
+/**
+ * principalWire.ts — principal 在场性判定的**唯一原语**(A-028.10,#244 族E,2026-08-15)。
+ *
+ * 裁定背景(cli 主会话裁,census top-07 §2):壳 `livePrincipal.ts` 与本包
+ * `engineWireTarget.engineWireTargetFor()` 各持一条 principal 解析,且**语义相反**:壳判
+ * `v && v.trim() !== ''`(全空白=缺席),包侧裸 truthy(全空白=在场)⇒ `SEMA_LIVE_PRINCIPAL='   '`
+ * 会发出一个全空白的 `x-agent-principal` 头 —— 垃圾值伪装在场,破坏 F-011 停发纪律
+ * ([3279]:缺席=不发头,owner-null;绝不铸哨兵值)。裁定=壳 trim 语义为正,包侧两臂
+ * (env 派生臂 + 显式装配臂)都收编本原语。
+ *
+ * 🔴 语义逐字(壳 `resolveLivePrincipal` 的判定半场):
+ *   · undefined / '' / 全空白 ⇒ undefined(键缺席,不发头);
+ *   · 其余 ⇒ **原值原样返回**(不 trim 改写 —— ` alice ` 照发 ` alice `,在场性判定与值改写
+ *     是两件事,本原语只做前者)。
+ * env 的读取方式留在端上(壳读 `process.env`,包内经 `hostEnv()`)——本原语零 IO 零 env。
+ */
+/** principal 在场性判定:全空白=缺席(undefined);实值原样返回(绝不改写)。 */
+export function normalizeWirePrincipal(v) {
+    return v !== undefined && v.trim() !== '' ? v : undefined;
+}

package/dist/request/taskRequest.d.ts

@@ -52,7 +52,7 @@ export interface RequestFieldSpec {
  */
 export declare const REQUEST_FIELD_MATRIX: readonly RequestFieldSpec[];
 /** live 兜底层(`toLiveRequest`)追加的字段 —— 两条车道**都**经过,故不进上表。 */
-export declare const LIVE_DEFAULT_FIELDS: readonly ["cwd", "additionalDirectories", "forwardSubagentEvents", "retainSubagentSessions", "agents", "appendSystemPrompt|settings.outputStyle", "suggestNextPrompts", "compactionModel", "sessionId(三态解析)"];
+export declare const LIVE_DEFAULT_FIELDS: readonly ["cwd", "additionalDirectories", "additionalReadDirectories", "forwardSubagentEvents", "retainSubagentSessions", "agents", "appendSystemPrompt|settings.outputStyle", "suggestNextPrompts", "compactionModel", "sessionId(三态解析)"];
 /** 端解析好的输入 —— 每一项都是**值**,不是取值方式(取值方式属端)。 */
 export interface TaskRequestInput {
     /** 本 turn 的模型面输入(已含 slash-skill 正文 / 注入式 meta / 历史种子等端侧组装)。 */
@@ -121,6 +121,10 @@ export declare function buildTaskRequest(input: TaskRequestInput, lane: RequestL
 export interface LiveDefaultsInput {
     cwd?: string;
     additionalDirectories?: readonly string[];
+    /** 只读面宽根(A-028.9 补位,壳 #257 真行为上收):配置目录 + tmp 族等**主机自身姿态**的
+     *  read-boundary 根。值(广度闸/realpath 判决)归端算,包只做「缺席时补位」。
+     *  🔴 只宽读不宽写:与 `additionalDirectories`(/add-dir 用户显式写授权)是分开的两个口。 */
+    additionalReadDirectories?: readonly string[];
     agents?: unknown;
     /** 引擎 caps 判真 ⇒ 走 `appendSystemPrompt` 一等位;否则借道 `settings.outputStyle`。 */
     appendSystemPromptCapable: boolean;

package/dist/request/taskRequest.js

@@ -60,6 +60,7 @@ export const REQUEST_FIELD_MATRIX = [
 export const LIVE_DEFAULT_FIELDS = [
     'cwd',
     'additionalDirectories',
+    'additionalReadDirectories',
     'forwardSubagentEvents',
     'retainSubagentSessions',
     'agents',
@@ -166,6 +167,11 @@ export function applyLiveRequestDefaults(req, host) {
     if (out.additionalDirectories === undefined && (host.additionalDirectories?.length ?? 0) > 0) {
         out.additionalDirectories = [...(host.additionalDirectories ?? [])];
     }
+    // A-028.9:只读面宽根(壳 cli 逐字:`if (roots.length > 0) out.additionalReadDirectories = roots`,
+    // 「已带值不覆盖」的守卫同其余各条)。
+    if (out.additionalReadDirectories === undefined && (host.additionalReadDirectories?.length ?? 0) > 0) {
+        out.additionalReadDirectories = [...(host.additionalReadDirectories ?? [])];
+    }
     // C1 / design/144:交互与 headless 都常开 —— 不开则引擎不建 SubagentRetainLedger,
     // 后台子代 SendMessage 唤醒直接 "session was not retained" 拒绝。老引擎按 body→spec 白名单
     // 忽略未知字段,version-safe。

package/dist/sessionMap.d.ts

@@ -0,0 +1,95 @@
+/**
+ * sessionMap.ts — 「客户端会话 id ↔ 引擎会话 id」映射的**单一键形与 merge 判定**
+ * (A-028.12,#244 族E,2026-08-15)。
+ *
+ * ## 收编前的形(census top-10 §2)
+ * 同一概念两端各持一份、**键名零重合**:
+ *   · 壳 `sessionIdMapping.ts`:`{shellSessionId, engineSessionId, lastEngineTaskId, engines{}}`,
+ *     `.session-map.json` 侧车(lock + temp→fsync→rename 原子写);
+ *   · web `engine-history-wire.ts`:`{uiId:{s:engineId,t:activeTaskId}}`,localStorage。
+ * 与 B18 seatContract 修的「同一契约两份声明、编译器永不告警」同形。本件定**单一键形**
+ * (壳形为正:显式键名 + per-engine 命名空间,web 缩写形迁移归 web 半场)+ 两个纯 merge 判定;
+ * 存储经 {@link SessionMapStorePort} 归端(cli = lock+原子写两进程纪律,web = localStorage)。
+ *
+ * 🔴 merge 语义 = 壳 `persist`/`persistEngineEntry` 传给 lockedReadMergeWrite 的那两个闭包**逐字**:
+ * `partial ?? prior` 逐字段让位、`engines[key]` 命名空间不互相覆盖、身份键缺席=拒写(skip 判定
+ * 带 reason 出境,落日志的措辞归端)。
+ */
+/**
+ * ONE engine's continuity record, keyed inside {@link SessionMapRecord.engines} by the engine
+ * NAMESPACE key ({@link engineNamespaceKeyFor}): task ids / sync watermarks minted by DIFFERENT
+ * engines must never overwrite each other (a cloud taskId fed to the local engine on resume =
+ * the id-collision this namespace exists to prevent). `instanceId` is the engine's /health
+ * identity stamp — a redeployed engine at the same origin stays distinguishable.
+ */
+export interface EngineSessionEntry {
+    /** Engine session id ON THAT ENGINE(single-namespace 裁定下与 shell id 同值,仍显式持久)。 */
+    engineSessionId: string;
+    /** Engine /health `instanceId` at record time (precise engine identity, not just the origin). */
+    instanceId?: string;
+    /** Last `done.result.taskId` observed FROM THIS ENGINE. */
+    lastEngineTaskId?: string;
+    /** The session leafId at the last successful sync push/pull against this engine (sync watermark). */
+    lastSyncedLeafId?: string;
+    updatedAt: string;
+}
+export interface SessionMapRecord {
+    /** Shell/client (transcript) sessionId — the primary key / namespace anchor. */
+    shellSessionId: string;
+    /** Engine session id(LEGACY/current-engine view:写入时活跃引擎的值;跨引擎消费读 engines)。 */
+    engineSessionId?: string;
+    /** Last `done.result.taskId` observed for this session(rewind/resume continuity;同上注意)。 */
+    lastEngineTaskId?: string;
+    /** Per-engine continuity, keyed by {@link engineNamespaceKeyFor}(baseUrl)('local' | origin). */
+    engines?: Record<string, EngineSessionEntry>;
+    /** auto-sync per-session 覆盖:true/false 覆盖项目开关,undefined = 跟随。 */
+    autoSync?: boolean;
+    /** 冲突 pause:fork/stale 后停 auto 转手动;手动 push 成功 / sync on 清除。 */
+    autoSyncPaused?: {
+        reason: string;
+        at: string;
+    };
+    updatedAt: string;
+}
+/**
+ * The engine NAMESPACE key for a CONNECTED engine target's base url: the lowercased origin
+ * (scheme+host+port — TOFU 同粒度). ⚠️ ROLE decides the namespace, not the url shape: the
+ * SELF-SPAWNED engine is always keyed `'local'` (callers pass no url — its port can drift across
+ * boots, one logical engine), while a `connect`ed target is keyed by origin EVEN when loopback
+ * (a second local engine on another port is a DIFFERENT engine with a different data root).
+ * Pure; never throws. A malformed non-empty url falls back to the raw lowercased string
+ * (honest separation beats aliasing it onto another namespace).
+ */
+export declare function engineNamespaceKeyFor(baseUrl: string | undefined): string;
+/** merge 判定的出境形:拒写带 reason(措辞/日志归端),成写带整份下一记录。 */
+export type SessionMapMergeVerdict = {
+    ok: true;
+    record: SessionMapRecord;
+} | {
+    ok: false;
+    reason: 'no-shell-session-id' | 'no-engine-session-id';
+};
+/**
+ * 顶层记录 merge(壳 `persist` 闭包逐字):`shellSessionId` 取 `partial ?? prior`,两处都缺 =
+ * 拒写;成写 = `{...prior, ...partial, shellSessionId, updatedAt: now()}`。
+ */
+export declare function mergeSessionMapRecord(prior: SessionMapRecord | undefined, partial: Partial<SessionMapRecord> & {
+    shellSessionId?: string;
+}, now?: () => string): SessionMapMergeVerdict;
+/**
+ * per-engine entry merge(壳 `persistEngineEntry` 闭包逐字):`engines[key]` 内
+ * `partial ?? priorEntry` 让位;`prior.engines` 作 spread 基底 —— 未被本次改动的其它 engine key
+ * 原样保留(两个不同 key 的并发写互不覆盖的**判定半场**;「基底必须是锁内新鲜读」的进程纪律
+ * 归端的存储实现)。拒写序:先 engineSessionId 后 shellSessionId(与壳日志序一致)。
+ */
+export declare function mergeEngineEntry(prior: SessionMapRecord | undefined, key: string, partial: Partial<EngineSessionEntry>, shellSessionId?: string, now?: () => string): SessionMapMergeVerdict;
+/**
+ * 存储端口(端注入):cli = per-session 文件 + proper-lockfile + temp→fsync→rename(REPL 单例与
+ * one-shot CLI 两个 OS 进程共写,`readMergeWrite` 的 prior 必须是**临界区内**的新鲜读);
+ * web = localStorage(单线程,直读直写即满足契约)。`build` 返回 undefined = 本次没有可写的
+ * 记录(身份键缺席)—— 实现方跳过写并返回 undefined。
+ */
+export interface SessionMapStorePort {
+    read(): SessionMapRecord | undefined;
+    readMergeWrite(build: (prior: SessionMapRecord | undefined) => SessionMapRecord | undefined): SessionMapRecord | undefined;
+}

package/dist/sessionMap.js

@@ -0,0 +1,73 @@
+/**
+ * sessionMap.ts — 「客户端会话 id ↔ 引擎会话 id」映射的**单一键形与 merge 判定**
+ * (A-028.12,#244 族E,2026-08-15)。
+ *
+ * ## 收编前的形(census top-10 §2)
+ * 同一概念两端各持一份、**键名零重合**:
+ *   · 壳 `sessionIdMapping.ts`:`{shellSessionId, engineSessionId, lastEngineTaskId, engines{}}`,
+ *     `.session-map.json` 侧车(lock + temp→fsync→rename 原子写);
+ *   · web `engine-history-wire.ts`:`{uiId:{s:engineId,t:activeTaskId}}`,localStorage。
+ * 与 B18 seatContract 修的「同一契约两份声明、编译器永不告警」同形。本件定**单一键形**
+ * (壳形为正:显式键名 + per-engine 命名空间,web 缩写形迁移归 web 半场)+ 两个纯 merge 判定;
+ * 存储经 {@link SessionMapStorePort} 归端(cli = lock+原子写两进程纪律,web = localStorage)。
+ *
+ * 🔴 merge 语义 = 壳 `persist`/`persistEngineEntry` 传给 lockedReadMergeWrite 的那两个闭包**逐字**:
+ * `partial ?? prior` 逐字段让位、`engines[key]` 命名空间不互相覆盖、身份键缺席=拒写(skip 判定
+ * 带 reason 出境,落日志的措辞归端)。
+ */
+/**
+ * The engine NAMESPACE key for a CONNECTED engine target's base url: the lowercased origin
+ * (scheme+host+port — TOFU 同粒度). ⚠️ ROLE decides the namespace, not the url shape: the
+ * SELF-SPAWNED engine is always keyed `'local'` (callers pass no url — its port can drift across
+ * boots, one logical engine), while a `connect`ed target is keyed by origin EVEN when loopback
+ * (a second local engine on another port is a DIFFERENT engine with a different data root).
+ * Pure; never throws. A malformed non-empty url falls back to the raw lowercased string
+ * (honest separation beats aliasing it onto another namespace).
+ */
+export function engineNamespaceKeyFor(baseUrl) {
+    if (!baseUrl)
+        return 'local';
+    try {
+        return new URL(baseUrl).origin.toLowerCase();
+    }
+    catch {
+        return baseUrl.toLowerCase();
+    }
+}
+/** 缺省时钟(可注入 —— 测试与「同一批双写同刻」的端语义都经它)。 */
+const isoNow = () => new Date().toISOString();
+/**
+ * 顶层记录 merge(壳 `persist` 闭包逐字):`shellSessionId` 取 `partial ?? prior`,两处都缺 =
+ * 拒写;成写 = `{...prior, ...partial, shellSessionId, updatedAt: now()}`。
+ */
+export function mergeSessionMapRecord(prior, partial, now = isoNow) {
+    const shellSessionId = partial.shellSessionId ?? prior?.shellSessionId;
+    if (!shellSessionId)
+        return { ok: false, reason: 'no-shell-session-id' };
+    return { ok: true, record: { ...prior, ...partial, shellSessionId, updatedAt: now() } };
+}
+/**
+ * per-engine entry merge(壳 `persistEngineEntry` 闭包逐字):`engines[key]` 内
+ * `partial ?? priorEntry` 让位;`prior.engines` 作 spread 基底 —— 未被本次改动的其它 engine key
+ * 原样保留(两个不同 key 的并发写互不覆盖的**判定半场**;「基底必须是锁内新鲜读」的进程纪律
+ * 归端的存储实现)。拒写序:先 engineSessionId 后 shellSessionId(与壳日志序一致)。
+ */
+export function mergeEngineEntry(prior, key, partial, shellSessionId, now = isoNow) {
+    const priorEntry = prior?.engines?.[key];
+    const engineSessionId = partial.engineSessionId ?? priorEntry?.engineSessionId;
+    if (!engineSessionId)
+        return { ok: false, reason: 'no-engine-session-id' };
+    const sid = shellSessionId ?? prior?.shellSessionId;
+    if (!sid)
+        return { ok: false, reason: 'no-shell-session-id' };
+    const entry = { ...priorEntry, ...partial, engineSessionId, updatedAt: now() };
+    return {
+        ok: true,
+        record: {
+            ...prior,
+            shellSessionId: sid,
+            engines: { ...prior?.engines, [key]: entry },
+            updatedAt: now(),
+        },
+    };
+}

package/dist/subagent/engineSubagentTail.d.ts

@@ -20,6 +20,26 @@ export interface SubagentActivity {
 export type SubagentActivitySink = (a: SubagentActivity) => void;
 /** 装/卸 Progress 段落点。传 null 卸。返回还原函数。 */
 export declare function installSubagentActivitySink(sink: SubagentActivitySink | null): () => void;
+/**
+ * 一帧 tail `event: meta` 的发布载荷(#280 件2,0.30.4)。`meta` 是连接语义帧(server 建连即发:
+ * `{version, runId, target, status, seq?, contentFrames?, …}`),**不进内容面** —— 但其中的
+ * **供给形判别位 `contentFrames`**(server e439a6c,闭集 {on | progress_only | unknown})是端
+ * 区分「内容帧**永远不会来**(forward 缺席宿主,结构性无内容)vs **还没来**」的唯一诚实依据;
+ * 0.30.3 及之前它被消费循环的 forward-only 过滤整类 skip,端结构性到不了。
+ * 🔴 `meta` 为**开集原文**(SDK subagentStream 产物 `Record<string, unknown>` 原样):判别位的
+ * 窄读(闭集判词/缺席处置)归消费端,包只搬运 —— additive 上游往 meta 里加键零施工。
+ * ⚠️ 供给形登记随句柄终态在 server 侧撤销(SubagentTailBus.forgetHandleContentMode)⇒ 判别位
+ * 要在子代存活窗内消费,终态后重开的 tail 读到 `unknown` 不是回归。
+ */
+export interface SubagentTailMeta {
+    taskId: string;
+    /** meta 帧原文(开集;`contentFrames` 等判别位的窄读归消费端)。 */
+    meta: Record<string, unknown>;
+}
+/** 端装的 meta 帧落点(#280 件2)。不装 ⇒ 判别位不达端(不是错误态,该面不启用;0.30.3 现状字节不变)。 */
+export type SubagentTailMetaSink = (m: SubagentTailMeta) => void;
+/** 装/卸 tail meta 帧落点。传 null 卸。返回还原函数。 */
+export declare function installSubagentTailMetaSink(sink: SubagentTailMetaSink | null): () => void;
 /**
  * tail 是否正对该行开着 —— **两源互斥判别口**(行帧 `currentTool` 臂在 tail 活跃时让位:
  * tail 的 tool_start 带真 args,渲染更细;两源同录 = 每步双行)。

package/dist/subagent/engineSubagentTail.js

@@ -84,6 +84,15 @@ export function installSubagentActivitySink(sink) {
         activitySink = prev;
     };
 }
+let tailMetaSink = null;
+/** 装/卸 tail meta 帧落点。传 null 卸。返回还原函数。 */
+export function installSubagentTailMetaSink(sink) {
+    const prev = tailMetaSink;
+    tailMetaSink = sink;
+    return () => {
+        tailMetaSink = prev;
+    };
+}
 /* `coerceOutput`(tool_end.output 的字符串化口)**已搬到 `subagentContentStore.ts`**
  * (#158 移交① / [3674](d) 姊妹病,2026-08-12):喂那个 store 的是两条腿(本 tail 腿 + seam
  * 适配器的 C1 分流臂),字符串化口必须只有一份,故跟着它服务的那个位走。公面导出名不变
@@ -143,8 +152,35 @@ export function tailEngineSubagent(taskId) {
                     // 连接分界线:meta 帧即到 = SSE 建连成功(与「子代此刻恰好在跑长工具、没内容可发」区分开)
                     hostLog('debug', `[subagent-tail] ${taskId} stream connected +${Date.now() - openedAt}ms`);
                 }
-                if (ev.event !== 'forward')
-                    continue; // meta/heartbeat:连接语义帧,不进内容面
+                // #280 件2(0.30.4):帧分类闸 —— `meta` 经发布口出去(`contentFrames` 判别位在其中,
+                // 见 SubagentTailMeta 顶注),`forward` 进内容面,其余(heartbeat / 未来新连接语义帧)
+                // 维持 skip。🔴 开闸范围**只放 meta**(最小化):放宽 default 臂 = 把未知帧灌进发布口,
+                // 消费端会把连接杂音当判别位读。
+                switch (ev.event) {
+                    case 'meta':
+                        // 连接语义帧,不进内容面;不装 sink = 现状。🔴 消费端 sink 失败**绝不撕裂 tail**
+                        //(本文件头注铁律「一切失败 fail-soft…绝不 throw」;runStream onDroppedFrame
+                        // 「sink 抛错绝不打断流且痕迹落回」同族)——两臂都要:同步 throw 由 try/catch 兜,
+                        // **异步拒绝**(类型虽 void,宿主传 async 函数合法)也要有界观察 —— 不观察 =
+                        // unhandledRejection = Node 缺省整进程崩,TUI 宿主最坏形。痕迹留 hostLog,内容帧照常消费。
+                        try {
+                            const out = tailMetaSink?.({ taskId, meta: ev.data });
+                            if (out !== null && typeof out === 'object' && typeof out.then === 'function') {
+                                ;
+                                out.then(undefined, (e) => {
+                                    hostLog('debug', `[subagent-tail] ${taskId} meta sink rejected: ${String(e).slice(0, 160)}`);
+                                });
+                            }
+                        }
+                        catch (e) {
+                            hostLog('debug', `[subagent-tail] ${taskId} meta sink threw: ${String(e).slice(0, 160)}`);
+                        }
+                        continue;
+                    case 'forward':
+                        break;
+                    default:
+                        continue; // heartbeat 等连接语义帧,不进内容面
+                }
                 const d = ev.data;
                 const t = d.type;
                 frames += 1;

package/dist/wireErrorTriage.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 网络/传输层失败的词面基表(壳 seamQuery「件2c transport 收窄」的那条正则逐字)。
+ * 判据变更义务:加词=各端跟批;删词/改形=先与消费端对表(web 叠加宿主词的半场见其
+ * turn-error-classify 头注)。
+ */
+export declare const WIRE_NETWORK_ERROR_PATTERN: RegExp;
+/** turn 错误的结构化分型判决(渲染/文案归端;门与遥测按 kind 对账)。 */
+export type TurnWireErrorVerdict = 
+/** 引擎应答了非 2xx(reachable)。`errorCode` 只认活键([2055]);缺席=不带。 */
+{
+    kind: 'http';
+    status: number;
+    errorCode?: string;
+    message: string;
+}
+/** SDK typed park 信号:流结束但 run 未达终态(多半 suspended 候人决断)—— 不是故障。 */
+ | {
+    kind: 'stream-ended-without-terminal';
+}
+/** 真网络/传输层失败(引擎压根没应答)。detail = cause 原话 > message > String(err)。 */
+ | {
+    kind: 'transport';
+    detail: string;
+}
+/** 分类不明(多半是客户端自己的 bug)—— 如实报,绝不指去查引擎/网络。 */
+ | {
+    kind: 'internal';
+    name: string;
+    detail: string;
+};
+/**
+ * turn 错误分型(模块头②节的四臂;臂序=壳 `semaApiErrorContent` 逐字:http → park 信号 →
+ * transport/internal)。纯判定,永不抛。
+ */
+export declare function classifyTurnWireError(err: unknown): TurnWireErrorVerdict;
+/**
+ * 真·网络/传输层失败判(壳 `engineTarget.isEngineTransportError` 逐字语义):typed HTTP error
+ * (numeric `status` 在场 = 引擎应答了)恒 false —— 死端点分诊绝不误挂在活引擎的业务错误上。
+ * 消费面:headless `-p` 死 pin 提示 / 审批提交腿的重试判型(approvalSubmitRetry)。
+ */
+export declare function isWireTransportError(err: unknown): boolean;
+/**
+ * 判型:server drain 门的 pre-stream 拒收(503 + `errorCode:"draining"`)。结构判读不
+ * instanceof(mock/包装错误同判);机器码单腿(sdk 4.0.0 起 message 腿退役)。
+ * 消费面的重试铁律(严格限定 pre-stream、有界)归壳 seamQuery 的重试环。
+ */
+export declare function isPreStreamDrainingReject(err: unknown): boolean;
+/**
+ * #166 — `resume_at.*` 错误码族:提交带的 resumeAt 锚服务端不认(Esc 杀锚未持久化的典型形)。
+ * 🔴 刻意**不**用 `isRewindFamilyCode`(那是含 `rewind_snapshot.` 的宽形):去锚自动重发的安全性
+ * 论证只对 resume_at 族做过,放宽属行为变更(RESUME_AT_ERROR_CODE_PREFIX 头注)。
+ */
+export declare function isResumeAtRejection(err: unknown): boolean;
+/**
+ * 第 `attempt`(0-based)次 draining 重试前的等待:`err.retryAfterMs`(SDK 若带)封顶优先
+ * (上限 15s = server drain 门现值,防把一个 turn park 到分钟级),缺席走退避梯
+ * (默认 1s/2s/4s = 壳 S4-P0 实测值;超出梯长取末档)。`opts.ladder` = 端的测试钩子注入口
+ * (壳 `setDrainingBackoffForTest` 经此透传)。纯函数,零模块状态(singleton 门口径)。
+ */
+export declare function drainingRetryDelayMs(err: unknown, attempt: number, opts?: {
+    ladder?: readonly number[];
+    retryAfterCapMs?: number;
+}): number;
+/** 结构化拒绝字段(与 SDK `ScenarioNotAllowedError` 同形;判定层不依赖 SDK 类型面)。 */
+export interface ScenarioDenyDetail {
+    /** The principal's allowed scenario names (defensively filtered; may be empty). */
+    allowlist: string[];
+}
+/**
+ * 从一个被 catch 的错误判定「场景不在指派列表」并提取结构化 detail。
+ * duck-typed(不 instanceof — bundle 下跨包类标识可能双实例):`status===400 &&
+ * errorCode===SCENARIO_NOT_ALLOWED_ERROR_CODE` 即命中;allowlist 缺席/非数组/畸形项 → 逐项
+ * 防御过滤成空数组(兜底文案契约归端)。非该 code 的 400 / 其他错误 → null(绝不误吃普通 400)。
+ * 🔴 键位([2055] 死键纪律):只认 `errorCode`,退役 `code` 键不做兼容(clean-cut)。
+ */
+export declare function scenarioDenyFromError(err: unknown): ScenarioDenyDetail | null;

package/dist/wireErrorTriage.js

@@ -0,0 +1,130 @@
+/**
+ * wireErrorTriage.ts — turn 错误分型的**判定半场**(A-028.11/.13,#244 族E,2026-08-15)。
+ *
+ * ## 收编前的形(census top-10 §1/§3)
+ * 同一套「turn 失败 → 分型 → 处置类」判定跑着**两份半**:
+ *   · 壳 `seamQuery.semaApiErrorContent` 的判型内联(typed HTTP / 网络词面 / internal 三分支)
+ *     + `isPreStreamDrainingReject` / `isResumeAtRejection` / `drainingRetryDelayMs`;
+ *   · 壳 `engineTarget.isEngineTransportError`(注释自陈「两处判据变更须同步」的第二份 inline);
+ *   · web `turn-error-classify.ts`(580 行第二实现,靠跨仓逐 token 读壳源码的 parity 门硬撑)。
+ * 本件把**纯判定**收成一份:错误对象 → 结构化分型判决。人话文案与渲染(Ink 行 / web 卡)
+ * 按 §8-5 归各端 —— 本件绝不铸一句面向用户的话。
+ *
+ * ## 判定语义(壳侧逐字,行为面零变化)
+ *   ① `typeof err.status === 'number'` ⇒ **http**(引擎真的应答了):机器码只认 `errorCode`
+ *      ([2055] 死键纪律:退役 `code` 槽不作兼容);
+ *   ② `err.name === 'StreamEndedWithoutTerminalError'`(#156/[2669] SDK typed park 信号,name 判
+ *      别 —— 跨包 instanceof 不可靠)⇒ **stream-ended-without-terminal**(run 多半 suspended
+ *      候人决断,绝不谎报网络/壳 bug);
+ *   ③ 网络词面命中或 undici `cause` 在场 ⇒ **transport**(真网络层;detail 取 cause 原话优先);
+ *   ④ 其余 ⇒ **internal**(分类不明如实说,不编造网络原因 —— 编一个具体原因比说不知道坏得多)。
+ *
+ * ## 词面表的跨端义务
+ * {@link WIRE_NETWORK_ERROR_PATTERN} 是壳/web 共用的**基表**(web 侧另有浏览器 fetch 的四种说法
+ * `failed to fetch`/`networkerror`/`network error`/`load failed`,那是宿主词,由 web 在自己那半场
+ * 叠加)。web 的 run-error-table-parity-test(逐 token 读壳源码)随本件退役为「共用同一 import」。
+ */
+import { DRAINING_ERROR_CODE, RESUME_AT_ERROR_CODE_PREFIX, SCENARIO_NOT_ALLOWED_ERROR_CODE, } from './engineErrorCodes.js';
+/**
+ * 网络/传输层失败的词面基表(壳 seamQuery「件2c transport 收窄」的那条正则逐字)。
+ * 判据变更义务:加词=各端跟批;删词/改形=先与消费端对表(web 叠加宿主词的半场见其
+ * turn-error-classify 头注)。
+ */
+export const WIRE_NETWORK_ERROR_PATTERN = /fetch failed|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|EPIPE|socket hang up|UND_ERR|terminated|other side closed/i;
+/** 传输失败 detail 的取值序(undici `.cause` 的精确 host:port 优先)。包内共用,不出公面。 */
+function wireErrorDetail(err) {
+    const e = err;
+    const cause = e?.cause;
+    return ((typeof cause?.message === 'string' && cause.message.length > 0 && cause.message) ||
+        (typeof e?.message === 'string' && e.message.length > 0 && e.message) ||
+        String(err));
+}
+/**
+ * turn 错误分型(模块头②节的四臂;臂序=壳 `semaApiErrorContent` 逐字:http → park 信号 →
+ * transport/internal)。纯判定,永不抛。
+ */
+export function classifyTurnWireError(err) {
+    const e = err;
+    if (typeof e?.status === 'number') {
+        const errorCode = typeof e.errorCode === 'string' && e.errorCode.length > 0 ? e.errorCode : undefined;
+        const message = typeof e.message === 'string' && e.message.length > 0 ? e.message : String(err);
+        return { kind: 'http', status: e.status, ...(errorCode !== undefined ? { errorCode } : {}), message };
+    }
+    // park 判别按 `name` **结构读**,不附加 instanceof Error(codex F3 [medium] 真病修):壳源形的
+    // `err instanceof Error &&` 合取在单进程壳里恒真无害,但本件是三端共用面 —— desktop IPC 序列化 /
+    // web 跨 bundle 的同名错误是 plain object,instanceof 合取会把「候人决断」误诊成「客户端 bug +
+    // 建议重跑」(重跑=重复 turn,且掩盖真待决态)。壳注释自陈的意图本就是「name 判别(跨包
+    // instanceof 不可靠)」—— 这里把实现对齐到意图(更强形,park 臂只宽不窄)。
+    const errName = typeof err === 'object' && err !== null && typeof err.name === 'string'
+        ? err.name
+        : undefined;
+    if (errName === 'StreamEndedWithoutTerminalError') {
+        return { kind: 'stream-ended-without-terminal' };
+    }
+    const detail = wireErrorDetail(err);
+    const isNetwork = e?.cause !== undefined || WIRE_NETWORK_ERROR_PATTERN.test(detail);
+    if (isNetwork)
+        return { kind: 'transport', detail };
+    return { kind: 'internal', name: err instanceof Error ? err.name : typeof err, detail };
+}
+/**
+ * 真·网络/传输层失败判(壳 `engineTarget.isEngineTransportError` 逐字语义):typed HTTP error
+ * (numeric `status` 在场 = 引擎应答了)恒 false —— 死端点分诊绝不误挂在活引擎的业务错误上。
+ * 消费面:headless `-p` 死 pin 提示 / 审批提交腿的重试判型(approvalSubmitRetry)。
+ */
+export function isWireTransportError(err) {
+    const e = err;
+    if (typeof e?.status === 'number')
+        return false;
+    return e?.cause !== undefined || WIRE_NETWORK_ERROR_PATTERN.test(wireErrorDetail(err));
+}
+/**
+ * 判型:server drain 门的 pre-stream 拒收(503 + `errorCode:"draining"`)。结构判读不
+ * instanceof(mock/包装错误同判);机器码单腿(sdk 4.0.0 起 message 腿退役)。
+ * 消费面的重试铁律(严格限定 pre-stream、有界)归壳 seamQuery 的重试环。
+ */
+export function isPreStreamDrainingReject(err) {
+    const e = err;
+    return typeof e?.status === 'number' && e.status === 503 && e.errorCode === DRAINING_ERROR_CODE;
+}
+/**
+ * #166 — `resume_at.*` 错误码族:提交带的 resumeAt 锚服务端不认(Esc 杀锚未持久化的典型形)。
+ * 🔴 刻意**不**用 `isRewindFamilyCode`(那是含 `rewind_snapshot.` 的宽形):去锚自动重发的安全性
+ * 论证只对 resume_at 族做过,放宽属行为变更(RESUME_AT_ERROR_CODE_PREFIX 头注)。
+ */
+export function isResumeAtRejection(err) {
+    const e = err;
+    return typeof e?.errorCode === 'string' && e.errorCode.startsWith(RESUME_AT_ERROR_CODE_PREFIX);
+}
+/**
+ * 第 `attempt`(0-based)次 draining 重试前的等待:`err.retryAfterMs`(SDK 若带)封顶优先
+ * (上限 15s = server drain 门现值,防把一个 turn park 到分钟级),缺席走退避梯
+ * (默认 1s/2s/4s = 壳 S4-P0 实测值;超出梯长取末档)。`opts.ladder` = 端的测试钩子注入口
+ * (壳 `setDrainingBackoffForTest` 经此透传)。纯函数,零模块状态(singleton 门口径)。
+ */
+export function drainingRetryDelayMs(err, attempt, opts) {
+    const ra = err?.retryAfterMs;
+    if (typeof ra === 'number' && Number.isFinite(ra) && ra >= 0) {
+        return Math.min(ra, opts?.retryAfterCapMs ?? 15_000);
+    }
+    const ladder = opts?.ladder && opts.ladder.length > 0 ? opts.ladder : [1_000, 2_000, 4_000];
+    return ladder[Math.min(attempt, ladder.length - 1)] ?? 1_000;
+}
+/**
+ * 从一个被 catch 的错误判定「场景不在指派列表」并提取结构化 detail。
+ * duck-typed(不 instanceof — bundle 下跨包类标识可能双实例):`status===400 &&
+ * errorCode===SCENARIO_NOT_ALLOWED_ERROR_CODE` 即命中;allowlist 缺席/非数组/畸形项 → 逐项
+ * 防御过滤成空数组(兜底文案契约归端)。非该 code 的 400 / 其他错误 → null(绝不误吃普通 400)。
+ * 🔴 键位([2055] 死键纪律):只认 `errorCode`,退役 `code` 键不做兼容(clean-cut)。
+ */
+export function scenarioDenyFromError(err) {
+    if (typeof err !== 'object' || err === null)
+        return null;
+    const e = err;
+    if (e.status !== 400 || e.errorCode !== SCENARIO_NOT_ALLOWED_ERROR_CODE)
+        return null;
+    const allowlist = Array.isArray(e.allowlist)
+        ? e.allowlist.filter((x) => typeof x === 'string' && x.length > 0)
+        : [];
+    return { allowlist };
+}

package/docs/INTEGRATION-CLIENTS.md

@@ -23,7 +23,7 @@
 | peer:wire 契约 | `@sema-agent/sdk` **>=6.17.2**(value-level,非 type-only) | `package.json` `peerDependencies` |
 | peer:会话词汇表 | `@sema-agent/agent-types` **>=0.2.0**(type-only,零运行时) | 同上 |
 | runtime dep | `diff` ^9.0.0(**唯一**一条;portability 门按**等值**钉死) | `package.json` `dependencies` |
-| 公开导出面 | **692** 个运行期符号(+ 33 个测试钩) | `scripts/public-export-baseline.json` 的 `count` / `testHookCount` —— **别手抄进别处,以该文件为准** |
+| 公开导出面 | **707** 个运行期符号(+ 33 个测试钩) | `scripts/public-export-baseline.json` 的 `count` / `testHookCount` —— **别手抄进别处,以该文件为准** |
 | 常驻门 | 以 `scripts/gates-manifest.json` 的 `suites` 长度为准(**本档不抄这个数**) | `scripts/gates-manifest.json`;`npm test` 的名单等值门与它逐名对账 |
 | 沿革档 | 0.29.0 起建 `CHANGELOG.md`;更早批次记账在 `src/index.ts` 文件头 + `docs/REFACTOR-LEDGER.md` | — |
 
@@ -99,7 +99,7 @@ SDK 核对「本包 import 的每个值级符号仍然导出」「`TaskStats.cos
 
 ## §2 公共导出面地图(按域)
 
-> 全集真源 = `scripts/public-export-baseline.json` 的 `names`(**692** 项)。
+> 全集真源 = `scripts/public-export-baseline.json` 的 `names`(**707** 项)。
 > 本节**不逐名抄**,只给「域 → 承重导出 → 用途 → 实现锚」。承重导出 = 一个端为了让这个域干活
 > **必须**直接调到的那几个符号;其余是它们的类型、变体与辅助位。
 > 单一入口:`import { … } from '@sema-agent/client-core'`(`exports` 只有 `.` 一个;
@@ -109,28 +109,28 @@ SDK 核对「本包 import 的每个值级符号仍然导出」「`TaskStats.cos
 
 `public-export-baseline.json` 由 **`dist/index.js` 的运行期导出**生成(生成口径自述见
 `scripts/run-client-core-typeshape-test.mjs`,双向精确集合门在 `scripts/run-public-surface-test.mjs`)。
-实测:692 项 **100% 是运行期导出,零 type-only**。
+实测:707 项 **100% 是运行期导出,零 type-only**。
 
 **推论(端必须知道)**:
-- barrel 导出的**类型**面比 692 大得多,且**不被这道门看守** —— `AdapterContext` / `SeamEvent` /
+- barrel 导出的**类型**面比 707 大得多,且**不被这道门看守** —— `AdapterContext` / `SeamEvent` /
   `ChromeEvent` / `HostPorts` / `ApprovalCardPort` / `HitlHostSurface` / `ClientSliceLike` /
   `LocalSessionEvent` / `SeatMethodName` / `ModelCatalog` 全在公面上、全**不在**基线里。
   端依赖这些类型是合法的,但**不要**拿基线 diff 当"类型面没变"的证据。
 - `src/agentSession/contract.ts` 对基线贡献 **0** 项(纯类型模块,`export *` 在 dist 里是空转发)。
 
-692 项的内部构成(帮助端估读表大小):**206** 项是 `SCREAMING_SNAKE` 常量数据表/词汇表
+707 项的内部构成(帮助端估读表大小):**210** 项是 `SCREAMING_SNAKE` 常量数据表/词汇表
 (矩阵、键集、env 名、锚串)而非可调用物;**4** 项是 PascalCase 运行期值
 (`ControlRouter` / `ControlSafetyError` / `HitlBridge` / `HitlSafetyError`);
-**38** 项是 `*For(sessionKey, …)` 的 per-session 变体(§6)。
+**39** 项是 `*For(sessionKey, …)` 的 per-session 变体(§6;其中 `engineNamespaceKeyFor` 是命名巧合 —— 参数是 baseUrl 不是 sessionKey,见域 14)。
 
-### 2b. 域图(16 域,逐域计数之和 = 692)
+### 2b. 域图(16 域,逐域计数之和 = 707)
 
 | # | 域 | 名数 | 承重导出 | 用途 | 实现锚 |
 |---|---|---|---|---|---|
 | 1 | **适配内核(下行主链)** | 29 | `adapt` · `createWireToCcAdapter` · `runStream` · `eventToSdkMessage` · `terminalToSdkResult` · `turnUsageToModelUsage` · `isRunStreamActive` · `ADAPTER_DIVERGENCES` | 引擎 SSE `AgentEvent` → 端要渲的**双面输出**:transcript(`SDKMessage`)+ chrome(瞬态 `ChromeEvent`)。**本包存在的理由** | `src/adapt.ts`、`src/adapt/{arms,wireShapes,panelTasks}.ts`(经 `adapt.ts` 再导出)、`src/adapter/runStream.ts`、`src/adapter/downstream/*`、`src/adapter/types.ts` |
 | 2 | **seam 公共契约** | 2(其余为 type-only) | `CHROME_ARMS` · `deriveTranscriptId` | 公共词汇 + **id 确定性不变量**(同一条流重放 ⇒ 同一串 id)。`CHROME_ARMS` = 端「我要消费哪些 chrome 臂」的对照清单 | `src/seam.ts` |
 | 3 | **HITL 决断卡链**(§4/§5 主战场) | 119 | `makeHitlCanUseTool` · `HitlBridge` · `findPendingForTask` · `HitlSafetyError` · `bridgeAskUserQuestionGates` · `surfaceToolApprovalFrameAndRespond` / `surfaceFsApprovalAndDecide` · `readToolApprovalRespondAck` · `installApprovalCardPort(For)` · `installHitlHostSurface(For)` · `armPlanReviewApproval` · `reopenPlanReviewCard` · `decidePlanReview` · `startApprovalsFeed` · `pendingRowIsOwnedByThisSession` · `approvalCallKey`/`liveFrameCallKey`/`planReviewQuestionId` · `registerArmedGateFor`/`wasGateArmedFor`/`clearArmedGateFor` · `waitForGateArmed(For)`/`onGateArmed(For)`/`gateArmedWaitMs`(#244 F1 呈现回执事件源) · `planReviewArmedKey(For)`/`notePlanReviewAnswered(For)`/`notePlanReviewAnsweredIfDecisive(For)`(A-024.4 plan 呈现分代) · `toolEndOutputText` · `isAskTool` · `waitForParkRowBirth` · `classifyAskParkRows` / `askParkRowArm` / `classifyAskParkChainFailure` · `readDecisionNoteAudit` / `decisionNoteAuditLine` · `resumeRunningOptions` / `resumeChoiceFromLabels` · `persistedRulesLaneAvailable`/`persistedRulesGovernanceAvailable` · `classifyRulesFailure` · `listAllPersistedRules` · `classifySkippedReason` · `readRulePersistOutcome`(#244 F2:persist-ack 读口与 `readToolApprovalRespondAck` 合成一处) · `parseLocalAllowRule`(durable 腿本地落规则窄化骨架,谓词经 `LocalAllowRuleDeps` 注入) | suspended→decide→resume 环。🔴 **D-1 两元组 verbatim 回显**是字节级断言的安全不变量,端**不许重实现它的任何一段**。🔴 键空间边界(web [C1] d3 拦截):`gateIdentity` 四常量两函数只覆盖 HITL questionId/callKey 空间;seat 的 `TOOL_PERMISSION_REQUEST_ID_DOMAINS`(`plan:` 等)是另一键空间,**两者绝不合并**(合并=座位校验器静默拒全部 plan-review 卡) | `src/hitl/hitlBridge.ts`、`toolApprovalWire.ts`、`askGateWire.ts`、`planReviewWire.ts`、`hitlHostSurface.ts`、`gateIdentity.ts`、`armedGateRegistry.ts`、`parkOwnership.ts`、`parkResolver.ts`、`approvalsFeed.ts`、`frameRouter.ts`(**只挑名导出** `toolEndOutputText`/`ENGINE_ABORT_TOOL_RESULT`/`isAskTool`/`HITL_REJECT_MESSAGE`)、`parkRowBirthWait.ts`、`approvalDecisionNoteAudit.ts`、`askParkRowRouting.ts`、`resumeRunningCard.ts`(#265 上收的判定层)、`persistedRulesWire.ts`、`localAllowRule.ts`(#244 F2 规则侧) |
-| 4 | **子代 wire + 面板侧信道台账** | 68 | `tailEngineSubagent` · `installSubagentActivitySink` · `stopEngineTask` + `classifyTaskStopConflict` · `fetchEngineSubagentReport` · `steerEngineSubagent` · `subscribeSubagentContent` · `subscribeEngineAgentPanel` · `publishQuestionFrame` / `respondToQuestion` | 驱动与观测委派子代;经 module 级台账喂活体 agent/task 面板。全部**能力位 gate**(§5b) | `src/subagent/*.ts`、`src/subagentContentStore.ts`、`src/engineAgentPanelStore.ts`、`src/engineInlineTaskStats.ts`、`src/engineToolLabelStore.ts`、`src/liveQuestionStore.ts` |
+| 4 | **子代 wire + 面板侧信道台账** | 69 | `tailEngineSubagent` · `installSubagentActivitySink` · `installSubagentTailMetaSink`(#280 件2:tail meta 帧发布口,`contentFrames` 判别位载体)· `stopEngineTask` + `classifyTaskStopConflict` · `fetchEngineSubagentReport` · `steerEngineSubagent` · `subscribeSubagentContent` · `subscribeEngineAgentPanel` · `publishQuestionFrame` / `respondToQuestion` | 驱动与观测委派子代;经 module 级台账喂活体 agent/task 面板。全部**能力位 gate**(§5b) | `src/subagent/*.ts`、`src/subagentContentStore.ts`、`src/engineAgentPanelStore.ts`、`src/engineInlineTaskStats.ts`、`src/engineToolLabelStore.ts`、`src/liveQuestionStore.ts` |
 | 5 | **fleet 投影** | 43 | `createFleetLedger` · `projectTasks` · `projectWorkflows` · `projectFleetAgentRows` · `readEngineActiveBgTasks` · `FLEET_TASK_VIEW_KEYS` | 老 `fleetClient` 那一刀的成品:**帧体归库、连接归端** —— 端持 SSE 连接,库做行投影 + 保留台账 | `src/fleet/fleetProjection.ts`、`src/fleet/fleetLedger.ts`、`src/fleetAgentPanelProjection.ts`、`src/fleetTaskDesc.ts` |
 | 6 | **请求装配(上行唯一构造口)** | 8 | `buildTaskRequest` · `REQUEST_FIELD_MATRIX` · `unregisteredRequestKeys` · `applyLiveRequestDefaults` · `taskNotificationToPrintFrame` | 两条车道(`interactive`/`print`)出站请求的**唯一**构造器;`unregisteredRequestKeys` 是可执行门 —— 端偷带一个未登记键上 wire 就红 | `src/request/taskRequest.ts`、`src/request/printNotification.ts` |
 | 7 | **通知与 outstanding 台账** | 37 | `installNotificationQueuePort` · `normalizeTaskNotification` · `taskNotificationDedupKeyFromWire` · `registerOutstandingBgTask` / `registerOutstandingWorkflowRun` · `notificationQueuePortMisses` · `subscribeOutstandingWorkflows` · `outstandingDeliverableWorkflowCount` | `task_notification` 归一 + 去重 + 投递进宿主命令队列的**一把闸**;`outstandingDeliverableWorkflowCount()` 是 headless `-p` 的**退出门** | `src/notifications.ts`(11 个 module 台账) |
@@ -140,9 +140,9 @@ SDK 核对「本包 import 的每个值级符号仍然导出」「`TaskStats.cos
 | 11 | **模型目录与预算** | 52 | `resolveModelCatalog` · `loadCatalogWithSources` · `PROVIDER_PRESETS` / `MODEL_FAMILIES` · `defaultMaxTokensFor` · `getLiveModelCatalog` / `setLiveModelCatalogRefresher` · `providerAuthMethods` / `beginDeviceCodeAuth` | 三层 provider 目录解析(线上 URL → 包内预设 → 用户覆盖)+ per-model `maxTokens` 封顶。线上腿需注入 `CatalogFetchJson`,缺席 ⇒ 整条不启用(`online.reason='no-fetch-port'`);缓存落盘经 `CatalogCachePort` | `src/model/{catalog,catalogLoader,providerAuth,providerPresets}.ts`、`src/liveModelCatalog.ts`、`src/modelBudgetRule.ts`、`src/sessionModelLatch.ts`、`src/effortWire.ts` |
 | 12 | **workflow 与后台工作视图** | 15 | `projectWorkflowRun` · `createLiveWorkflowSource` · `createBackgroundView` · `projectBackgroundView` · `recordWorkflowAgentTaskId` · `agentDisplayStatus` | 活过一个 turn 的长任务读面:workflow run + 跨 session 后台任务归一表(`assistant.tasks` 与 fleet SSE **两源独立降级**) | `src/workflow.ts`、`src/workflowClient.ts`、`src/workflowMonitor.ts`、`src/agentSession/backgroundView.ts`(+ 纯类型 `src/agentSession/contract.ts`) |
 | 13 | **座位 IPC 契约** | 33 | `LOCAL_SESSIONS_SPEC` · `SEAT_METHOD_NAMES` · `SEAT_EVENT_TYPES` · `isLocalSessionEvent` · `isToolPermissionRequest` · `toolPermissionRequestId` · `SEAT_VALIDATOR_KEY_COVERAGE` | desktop↔web 座位 IPC 契约的**单一真源**(此前两边各一份、名字零重合 ⇒ 编译器永远不会告诉你它们漂了)。🔴 加 verb 忘了加 `LOCAL_SESSIONS_SPEC` **不报错**:preload 不注册 channel、渲染端读到 `undefined` | `src/seatContract.ts`(**零 import**,纯类型 + 常量 + 纯谓词) |
-| 14 | **宿主端口与会话槽** | 18 | `installHost` · `installHostFor` · `hostPortMisses(For)` · `DEFAULT_SESSION_KEY` · `hostEnv` · `unrefTimer` | 进程/端级装配层(settings/fs/queue/timers/session/log/probe),与 per-turn 的 `AdapterContext` **分层**。头注的判定规则:**这个能力每 turn 都会变吗?** 会 ⇒ `ctx`;不会 ⇒ `installHost` | `src/host.ts`、`src/hostEnv.ts`、`src/sessionSlot.ts`、`src/unrefTimer.ts`、`src/env/localeGeo.ts` |
-| 15 | **控制面与传输** | 60 | `ControlRouter`(+ `ControlSafetyError`)· `makeEngineWireClient` + `resolveWireAuth` · `installEngineWireTarget` · `diagnoseSseIdleTear` / `isSseIdleError` · `attemptActiveRunSelfHeal` + `activeRunBusySignal` + `activeRunSelfHealRow` / `activeRunBusyHeadlessRow` · `kickEngineCapsProbe` / `engineCapTrue` · `mapBrainStatusToRetry` · `waitForClaimRelease` + `CLAIM_RELEASED_STATES` / `CLAIM_HELD_STATES` · `atMostOnceFailureClass` / `readSteerDelivery` · `INTERACTIVE_WAY_OUT`(默认出路串单源) | 上行通道的**监管**半场(submit / steer / kill / 队列命令定序)+ 传输构造、caps 探测、SSE 断流分诊、**409 active-run 自愈** | `src/controlRouter.ts`、`steering.ts`、`sseIdleTriage.ts`、`retryStatus.ts`、`diagnostics.ts`、`engineWireSdk.ts`、`engineWireTarget.ts`、`engineSessionParam.ts`、`engineCapsCache.ts`、`liveInitToolFace.ts`、`adapter/activeRunSelfHeal.ts` |
-| 16 | **引擎词汇表与包自检** | 36 | `CONFIG_REFUSAL_CODES` / `isConfigRefusalCode` · `STOP_CONFLICT_CODES` · `isInterruptedToolEndCode` · `isRewindFamilyCode` · `CLIENT_VERBS` · `compensationSplitViolations` | 三端分臂共用的**去字面化** `errorCode` 词表(病根正是三端各抄一份字面);编译期 verb 闭合门;搬迁补偿登记表 | `src/engineErrorCodes.ts`(29 项)、`src/classifierVerdictWire.ts`、`src/compensations.ts`、`src/clientSlice.ts` |
+| 14 | **宿主端口与会话槽** | 21 | `installHost` · `installHostFor` · `hostPortMisses(For)` · `DEFAULT_SESSION_KEY` · `hostEnv` · `unrefTimer` · `engineNamespaceKeyFor` / `mergeSessionMapRecord` / `mergeEngineEntry`(A-028.12:会话 id 映射单一键形 + merge 判定;存储经 `SessionMapStorePort` 归端 —— cli 文件锁/原子写,web localStorage)| 进程/端级装配层(settings/fs/queue/timers/session/log/probe),与 per-turn 的 `AdapterContext` **分层**。头注的判定规则:**这个能力每 turn 都会变吗?** 会 ⇒ `ctx`;不会 ⇒ `installHost` | `src/host.ts`、`src/hostEnv.ts`、`src/sessionSlot.ts`、`src/unrefTimer.ts`、`src/env/localeGeo.ts`、`src/sessionMap.ts` |
+| 15 | **控制面与传输** | 68 | `ControlRouter`(+ `ControlSafetyError`)· `makeEngineWireClient` + `resolveWireAuth` · `installEngineWireTarget` · `diagnoseSseIdleTear` / `isSseIdleError` · `attemptActiveRunSelfHeal` + `activeRunBusySignal` + `activeRunSelfHealRow` / `activeRunBusyHeadlessRow` · `kickEngineCapsProbe` / `engineCapTrue` · `mapBrainStatusToRetry` · `waitForClaimRelease` + `CLAIM_RELEASED_STATES` / `CLAIM_HELD_STATES` · `atMostOnceFailureClass` / `readSteerDelivery` · `INTERACTIVE_WAY_OUT`(默认出路串单源)· `normalizeWirePrincipal`(A-028.10:principal 在场性 trim 原语 —— 全空白=缺席不发头,engineWireTarget 两臂/makeEngineWireClient/壳 livePrincipal 同尺)· `classifyTurnWireError` / `isWireTransportError` / `isPreStreamDrainingReject` / `isResumeAtRejection` / `drainingRetryDelayMs` / `scenarioDenyFromError` + `WIRE_NETWORK_ERROR_PATTERN`(A-028.11/.13:turn 错误分型判定半场,人话文案与渲染归端) | 上行通道的**监管**半场(submit / steer / kill / 队列命令定序)+ 传输构造、caps 探测、SSE 断流分诊、**409 active-run 自愈** | `src/controlRouter.ts`、`steering.ts`、`sseIdleTriage.ts`、`retryStatus.ts`、`diagnostics.ts`、`engineWireSdk.ts`、`engineWireTarget.ts`、`src/principalWire.ts`、`src/wireErrorTriage.ts`、`engineSessionParam.ts`、`engineCapsCache.ts`、`liveInitToolFace.ts`、`adapter/activeRunSelfHeal.ts` |
+| 16 | **引擎词汇表与包自检** | 39 | `CONFIG_REFUSAL_CODES` / `isConfigRefusalCode` · `STOP_CONFLICT_CODES` · `isInterruptedToolEndCode` · `isRewindFamilyCode` · `CLIENT_VERBS` · `compensationSplitViolations` | 三端分臂共用的**去字面化** `errorCode` 词表(病根正是三端各抄一份字面);编译期 verb 闭合门;搬迁补偿登记表 | `src/engineErrorCodes.ts`(32 项;A-028.11/.13 补 `DRAINING_ERROR_CODE`/`SCENARIO_NOT_ALLOWED_ERROR_CODE`/`RESUME_AT_ERROR_CODE_PREFIX`)、`src/classifierVerdictWire.ts`、`src/compensations.ts`、`src/clientSlice.ts` |
 
 🔴 **`engineErrorCodes` 的开集纪律**(该文件头注逐字):这些 `ReadonlySet` / 前缀谓词一律是**识别表**,
 回答的是「我认不认得这个码」,**绝不是**「合法码只有这些」。消费点 `switch` **必须留 `default`**,
@@ -414,6 +414,7 @@ durable park 腿走 `HitlBridge.decideTool(outcome, toolUseID, opts, preResolved
 | `installHitlHostSurface(For)` | `src/hitl/hitlHostSurface.ts` | 通知不上屏(与壳原文 `if (!store) return` 同语义) | **是**(`hitlHostSurfaceMisses()` 恒应为 0) | §4a 的两条**安全告知**(remember-not-applied / edit-not-forwarded)+ cancel-by-deny warn + Recent Denials 记账**全丢** |
 | `installEngineWireTarget(For)` | `src/engineWireTarget.ts` | 回落 env 派生 | — | 🔴 **非 Node 宿主(web / desktop 渲染进程)没有 env** ⇒ 根本拿不到引擎目标。对它们这是**唯一**入口(设了就压过 env);不装 ⇒ `engineRowStopGate` 等按 `baseUrl` 查 caps 的门恒判假。⚠️ **凭证面有边界**:`EngineWireTarget.token` 今天是 `string`,**装不进** `{ mode: 'same-origin-relay' }` —— 浏览器同源宿主必读 **§5d** 与缺口 **P-28** |
 | `installSubagentActivitySink` | `src/subagent/engineSubagentTail.ts` | Subagent Progress 段无数据 | 否 | 明确**不是**错误态:那个面就是没启用 |
+| `installSubagentTailMetaSink` | `src/subagent/engineSubagentTail.ts`(#280 件2,0.30.4) | tail `event: meta` 帧不发布(0.30.3 现状) | 否 | `contentFrames` 供给形判别位(闭集 {on, progress_only, unknown})不达端 ⇒ 端把「结构性无内容(forward 缺席宿主)」误读成「还没来」永远空挂。载荷 = `{taskId, meta}`(meta 为帧**开集原文**,判别位窄读归端);⚠️ 判别位要在子代存活窗内消费(server 侧登记随句柄终态撤销,终态后 tail 读到 `unknown` 不是回归) |
 | `installWorkflowStatusProbe` | `src/notifications.ts` | watcher 没有带对 baseUrl/token/principal 的 `workflows.get` | — | **workflow 完成通知永远不落地** |
 | `installBgTaskStatusProbe` | `src/notifications.ts` | bg 状态 watcher 空转 | — | **后台子代完成通知永远不落地**(这个 watcher 存在的理由正是 idle 期推送不可靠) |
 | `CatalogFetchJson`(注入,非 install) | `src/model/catalog.ts` | 线上腿**整条不启用**(`online.reason = 'no-fetch-port'`) | — | 目录只走包内兜底(端可据 `source` + `online.reason` 诚实渲「内置版本(离线)」) |
@@ -786,6 +787,7 @@ reason 里写明「枚举器盲区形」。已知两形:
 - [ ] `kickEngineCapsProbe(baseUrl, probe)`(caps 门的数据源)
 - [ ] `installWorkflowStatusProbe` / `installBgTaskStatusProbe` —— 不装 = **workflow / 后台子代的完成通知永远不落地**
 - [ ] `installSubagentActivitySink`(可选:Subagent Progress 段的数据源;不装不是错误态)
+- [ ] `installSubagentTailMetaSink`(可选,0.30.4 #280 件2:tail meta 帧的 `contentFrames` 判别位数据源;不装不是错误态,但查看态会把「结构性无内容」渲成永远的「还没来」)
 - [ ] **启动校验用存在性读口**(§5a 的 (a) 表,🔴 **哨兵逐口不同,逐个照抄别推广**;多会话宿主用 `*For` 那一支):`hasApprovalCardPort() === true` · `hasApprovalCardPortFor(key) === true` · **`hitlHostSurfaceFor(key) !== null`**(哨兵是 `null`,写 `!== undefined` **恒真** = 假绿) · `hostSettings() !== undefined` · `hostSettingsFor(key) !== undefined` · `hostFs() !== undefined` · `hostFsFor(key) !== undefined` · `hostSession() !== undefined` · `hostSessionFor(key) !== undefined` · `engineWireTarget() !== null` · `engineWireTargetFor(key) !== null`(`hostTimers()` / `hostTimersFor(key)` 同为 `!== undefined`,按你真装的挑)
 - [ ] **miss 计数当回归探针,不当装配自检**(#252 复审 R3/R4,§5a (b) / 缺口 **P-29**):`hostPortMisses()` 空 / `notificationQueuePortMisses() === 0` / `approvalCardPortMisses() === 0` / `hitlHostSurfaceMisses() === 0` / `compensationSplitViolations()` 空 —— 🔴 **这几个数初值就是 0/空**,「完全没装口 + 还没发生任何调用」时它们照样全绿,**启动瞬间的断言证明不了装配**。正确用法 = 跑过**一轮真流量**之后再断言它们仍为 0。⚠️ **通知队列口今天没有存在性读口**(P-29),那一条只能靠你自己记得调过
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.30.2",
+  "version": "0.30.4",
   "description": "Client-side session runtime shared by every sema human client (TUI / web / desktop): sema wire frames (AgentEvent) -> CC session vocabulary (SDKMessage) with dual-plane output (transcript/chrome), deterministic transcript ids, lane discipline as a type, and the notification/dedup ledgers. Every CC-skin shape is collected here so the wire itself stays neutral. Blackboard [1832] design axioms; [1651]/[1652]/[1653] signed seam design. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",