@sema-agent/client-core 0.30.2 → 0.30.3

package/CHANGELOG.md

@@ -16,6 +16,37 @@
 > 🔴 **互链**(web [C166]⑦):各版「已知局限」段只记**该版新增**;接入面已知局限的完整台账在
 > `docs/INTEGRATION-CLIENTS.md` §6e/§7 —— **只读其一会漏**,两处都过。
 
+## 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.3
 
 - **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/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/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` —— **别手抄进别处,以该文件为准** |
+| 公开导出面 | **706** 个运行期符号(+ 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`(**706** 项)。
 > 本节**不逐名抄**,只给「域 → 承重导出 → 用途 → 实现锚」。承重导出 = 一个端为了让这个域干活
 > **必须**直接调到的那几个符号;其余是它们的类型、变体与辅助位。
 > 单一入口:`import { … } from '@sema-agent/client-core'`(`exports` 只有 `.` 一个;
@@ -109,21 +109,21 @@ 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**。
+实测:706 项 **100% 是运行期导出,零 type-only**。
 
 **推论(端必须知道)**:
-- barrel 导出的**类型**面比 692 大得多,且**不被这道门看守** —— `AdapterContext` / `SeamEvent` /
+- barrel 导出的**类型**面比 706 大得多,且**不被这道门看守** —— `AdapterContext` / `SeamEvent` /
   `ChromeEvent` / `HostPorts` / `ApprovalCardPort` / `HitlHostSurface` / `ClientSliceLike` /
   `LocalSessionEvent` / `SeatMethodName` / `ModelCatalog` 全在公面上、全**不在**基线里。
   端依赖这些类型是合法的,但**不要**拿基线 diff 当"类型面没变"的证据。
 - `src/agentSession/contract.ts` 对基线贡献 **0** 项(纯类型模块,`export *` 在 dist 里是空转发)。
 
-692 项的内部构成(帮助端估读表大小):**206** 项是 `SCREAMING_SNAKE` 常量数据表/词汇表
+706 项的内部构成(帮助端估读表大小):**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 域,逐域计数之和 = 706)
 
 | # | 域 | 名数 | 承重导出 | 用途 | 实现锚 |
 |---|---|---|---|---|---|
@@ -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`**,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.30.2",
+  "version": "0.30.3",
   "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",