@sema-agent/client-core 0.30.1 → 0.30.3

package/dist/hitl/persistedRulesWire.js

@@ -0,0 +1,236 @@
+import { engineCapTrue } from '../engineCapsCache.js';
+import { hostLog } from '../host.js';
+import { readToolApprovalRespondAck } from './toolApprovalWire.js';
+// ── 能力位 gate ──────────────────────────────────────────────────────────────────────────────
+/** 规则车道在不在(四口 501 同源谓词)。未判/缺键/base 缺席 = false = 整面藏。 */
+export function persistedRulesLaneAvailable(baseUrl) {
+    return engineCapTrue(baseUrl, 'permissionRules');
+}
+/**
+ * 治理面(list + revoke)在不在。**两段合取**:
+ *  · `permissionRulesRevoke` 在场 = 撤销面路由已铸(缺席 = worker 比撤销面老 ⇒ 藏);
+ *  · `permissionRules` 为真 = 车道真答话(店 + 旋钮)。
+ * 只查前者会在「7.11.0 且规则店在」的 worker 上渲出一个恒 404 的治理入口。
+ */
+export function persistedRulesGovernanceAvailable(baseUrl) {
+    return engineCapTrue(baseUrl, 'permissionRulesRevoke') && engineCapTrue(baseUrl, 'permissionRules');
+}
+function errShape(e) {
+    const o = (e ?? {});
+    return {
+        ...(typeof o.status === 'number' ? { status: o.status } : {}),
+        ...(typeof o.errorCode === 'string' ? { errorCode: o.errorCode } : {}),
+        message: typeof o.message === 'string' && o.message !== '' ? o.message : String(e),
+    };
+}
+/** `Retry-After` 秒数(SDK 把它折进 `retryAfterMs`)。非数/负数 ⇒ 缺席。 */
+function retryAfterSecOf(e) {
+    const ms = e.retryAfterMs;
+    if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0)
+        return undefined;
+    return Math.ceil(ms / 1000);
+}
+export function classifyRulesFailure(e) {
+    const { status, errorCode, message } = errShape(e);
+    if (status === 501 || errorCode === 'capability.rule_store_required') {
+        return { kind: 'lane-unavailable', message };
+    }
+    if (status === 404) {
+        // 🔴 两个 404 是**不同处置**(SDK 头注):route 缺席 = 版本太老(藏面);rule_ticket = 票没了
+        // (丢票重来)。其余 404 一律按通用错误 —— 绝不按成因猜。
+        if (errorCode === 'not_found.route')
+            return { kind: 'route-missing', message };
+        if (errorCode === 'not_found.rule_ticket')
+            return { kind: 'ticket-dead', message };
+        return { kind: 'error', message };
+    }
+    if (errorCode === 'state.rule_import_retry') {
+        const sec = retryAfterSecOf(e);
+        return { kind: 'retry-same-ticket', message, ...(sec !== undefined ? { retryAfterSec: sec } : {}) };
+    }
+    if (errorCode === 'state.rule_remove_failed')
+        return { kind: 'retryable', message };
+    if (status === 400 && errorCode === 'request.query_invalid')
+        return { kind: 'cursor-stale', message };
+    if (status === 413)
+        return { kind: 'too-many-candidates', message };
+    if (status === 403 && errorCode === 'auth.operator_only')
+        return { kind: 'forbidden', message };
+    return { kind: 'error', message };
+}
+/** 一页要多少条。**必须显式给**(codex 对抗复审 [medium] 实撞):server 缺省是 **50**,而页帽
+ *  按「200/页」算 ⇒ 真实上界只有 1250 条,一位规则多于 1250 的 principal 会恒拿到「翻不完」的
+ *  失败、整个治理面打不开,而注释还写着 5000。夹取语义在 server(非数/越界夹进 1..200),所以给
+ *  上限最省往返、也让页帽的算术与现实一致。 */
+const PAGE_LIMIT = 200;
+/** 页数硬帽:server 恒给 nextCursor 的坏形不该让治理面无限翻(PAGE_LIMIT × 25 = 5000 条)。 */
+const MAX_PAGES = 25;
+/**
+ * 列全一位 principal 名下活着的规则。
+ *
+ * 🔴 **翻页要翻完**:`nextCursor` 缺席才是终点 —— 半途停下拿到的是一份不全的清单,而治理视图
+ * 恰恰最不能拿不全的清单当全量。所以这里 drain 到底,任何一页失败都不交部分结果。
+ * 🔴 **游标绑 `(rev, principal, scope)`**:两页之间有人加/删了规则 ⇒ 第二页 400
+ * `request.query_invalid`。处置 = **丢游标从头列一次**(静默重置成「接着上一页」会得到一份既漏行
+ * 又重行的清单);从头再撞一次 ⇒ 如实报 cursor-stale,由调用方(人按 r 刷新)决定。
+ * 🔴 **调用方 cursor 不收**(codex F2 对抗复审 [medium]):类型上剔掉 `cursor` 还不够 —— JS
+ * 调用方仍能塞进来,而首页的 `...params` 会把它原样送出 ⇒ 「列全」从**中途**开始却报 `ok:true`
+ * 完整清单(治理面据此藏掉仍然生效的规则)。运行期显式剥除 + 留痕:drain 恒从第一页起,
+ * 「接着别人的 keyset」证明不了完整性,与本函数的契约(rules 恒完整)结构性冲突。
+ */
+export async function listAllPersistedRules(facade, params = {}, opts) {
+    const { cursor: callerCursor, ...cleanParams } = params;
+    if (callerCursor !== undefined) {
+        hostLog('debug', 'persistedRulesWire: caller-supplied cursor ignored by listAllPersistedRules — a drain that starts mid-keyset cannot prove completeness, so it always starts from the top');
+    }
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const rules = [];
+        let cursor;
+        let rev = null;
+        let restart = false;
+        for (let page = 0; page < MAX_PAGES; page++) {
+            let res;
+            try {
+                // limit 显式给:①页帽的算术要与真实页大小一致(见 PAGE_LIMIT);②keyset 游标绑的是
+                // 一份确定的翻页参数,页大小在两页之间变会让「接着上一页」失去意义。调用方可覆盖。
+                res = await facade.list({ limit: PAGE_LIMIT, ...cleanParams, ...(cursor !== undefined ? { cursor } : {}) }, opts);
+            }
+            catch (e) {
+                const failure = classifyRulesFailure(e);
+                if (failure.kind === 'cursor-stale' && cursor !== undefined && attempt === 0) {
+                    hostLog('debug', 'persistedRulesWire: rule list cursor was minted on another rev/principal/scope — dropping it and re-listing from the top (never resuming a stale keyset)');
+                    restart = true;
+                    break;
+                }
+                return { ok: false, failure };
+            }
+            // 🔴 页体 fail-closed 窄化(codex F2 轮二 [high]):SDK 传输层只 JSON.parse,不做运行期
+            // schema 校验 —— 一个 2xx 的 `{rev:9}`(无 rules 数组)在旧读法下会被认证成「完整的空清单」
+            // (`ok:true, rules:[]`),治理面据此宣称「没有持久规则」而活规则不可见、无法撤销
+            // (版本偏斜/后端降级下静默发生)。坏形页 = 判不出,绝不当「读到了空的」:
+            //   · `rules` 必须是数组、`rev` 必须是有限数(SDK `RuleListResult` 两键皆必填);
+            //   · `nextCursor` 只有两种合法形:**缺席**(= 终页)或**非空字符串**(= 还有下一页);
+            //     `''`/null/数字等坏形不许被折成「到头了」—— 猜终点与猜续点同罪。
+            if (typeof res !== 'object' ||
+                res === null ||
+                !Array.isArray(res.rules) ||
+                typeof res.rev !== 'number' ||
+                !Number.isFinite(res.rev)) {
+                return {
+                    ok: false,
+                    failure: {
+                        kind: 'error',
+                        message: 'rule list page was malformed (missing/ill-typed rules array or rev on a 2xx) — refusing to certify it as a complete governance list',
+                    },
+                };
+            }
+            // 🔴 跨页 rev 钉(codex F2 轮三 [high]):游标契约上绑 rev —— 清单变了,续页**该** 400
+            // cursor-stale。一个 2xx 却换了 rev 的续页 = server 违约或降级形,拼起来是**混合快照**;
+            // 认证它为完整清单,比 400 那条腿(丢游标重列)更坏 —— 这里不猜不修补,如实 failure。
+            if (rev !== null && res.rev !== rev) {
+                return {
+                    ok: false,
+                    failure: {
+                        kind: 'error',
+                        message: `rule list rev changed mid-drain (page rev ${res.rev} ≠ first page rev ${rev}) on a 2xx — refusing to stitch a mixed snapshot into one governance list`,
+                    },
+                };
+            }
+            // 🔴 行级窄化(同轮):撤销承重的两键(`rule` / `scope`,revoke 的按内容身份对)必须是
+            // 非空串 —— `rules:[null]` / 缺 scope 的行被展进 `PersistedRule[]`,下游要么渲空白治理项、
+            // 要么按 undefined 撤销(什么都对不上)。坏行 = 坏页(丢行会把活规则藏起来,正是本函数
+            // 拒绝的病);其余展示键(tool/match/command/adds)不在此过度收紧 —— server additive 演进
+            // 不该把整面打红,消费端对展示键自有坏形容忍。
+            for (const r of res.rules) {
+                const rr = r;
+                if (rr === null ||
+                    typeof rr !== 'object' ||
+                    typeof rr.rule !== 'string' ||
+                    rr.rule === '' ||
+                    typeof rr.scope !== 'string' ||
+                    rr.scope === '') {
+                    return {
+                        ok: false,
+                        failure: {
+                            kind: 'error',
+                            message: 'rule list page carried a malformed rule row (missing/ill-typed rule or scope) — refusing to present a list that hides or garbles live rules',
+                        },
+                    };
+                }
+            }
+            rev = res.rev;
+            rules.push(...res.rules);
+            const next = res.nextCursor;
+            if (next === undefined)
+                return { ok: true, rules, rev };
+            if (typeof next !== 'string' || next === '') {
+                return {
+                    ok: false,
+                    failure: {
+                        kind: 'error',
+                        message: 'rule list page carried a malformed nextCursor (neither absent nor a non-empty string) — refusing to guess where the list ends',
+                    },
+                };
+            }
+            cursor = next;
+        }
+        if (!restart) {
+            return {
+                ok: false,
+                failure: {
+                    kind: 'error',
+                    message: `rule list did not terminate within ${MAX_PAGES} pages — refusing to present a partial governance list`,
+                },
+            };
+        }
+    }
+    return { ok: false, failure: { kind: 'cursor-stale', message: 'rule list kept changing under the cursor — try again' } };
+}
+// ── skipped.reason 分类 ─────────────────────────────────────────────────────────────────────
+/**
+ * `skipped[].reason` 的分类。**只按第一个 `:` 前缀**,且必须容得下**没有前缀**的两种真值形
+ * (整层 JSON 解不开 / 条目不是串)——SDK 头注逐字:reason 是给人看的散文,不是机读码,
+ * 全串等值匹配与「裸码」两种读法都会漂。
+ * 前缀形判据刻意保守(`RuleRejectCode` 形:小写 + 点/下划线),防把散文里的第一个冒号误读成码。
+ */
+export function classifySkippedReason(reason) {
+    const text = typeof reason === 'string' ? reason : String(reason);
+    const idx = text.indexOf(':');
+    if (idx <= 0)
+        return { text };
+    const head = text.slice(0, idx);
+    if (!/^[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$/.test(head))
+        return { text };
+    return { code: head, text };
+}
+/**
+ * respond 回执上「不再询问到底存上了没」的**结构化读口**。
+ *
+ * 🔴 **单一台账**(A-028.14 收口本体):`rulePersisted` / `ruleRefusal` 的结构窄化只有
+ * {@link readToolApprovalRespondAck} 这一份 —— 本函数不对 wire 原料二次开读,ack 过不了包内
+ * 结构门(缺 `delivery:'applied'` / `approvalId` / 三词闭集 `decision`)⇒ **`unknown`**:
+ * 一张连回执身份都不成形的 ack,不配驱动一行「已保存」的用户告知(诚实缺席优先)。
+ * 收口前 cli 的裸读会把 `{rulePersisted:true}` 这类半形对象读成 `persisted` —— 那正是双份台账
+ * 各漂各的形,常驻套对这一格有反向钉。
+ *
+ * 🔴 `rulePersisted` 缺席 ≠ `false`(未带 persistRule 的回决 / 旧 server ⇒ 字段省略);
+ * 🔴 规则没存上**从不翻转裁决** —— 200 + `rulePersisted:false` + `ruleRefusal` 是诚实形,
+ * 宿主只说「这次放行了,但『不再询问』没存上」,绝不渲成整次审批失败。
+ * 🔴 `rule_lane_unavailable` **四种成因共用一格、两种是本卡局限** ⇒ 禁据一帧判断整台部署的车道
+ * 在不在(那要看能力位)。
+ */
+export function readRulePersistOutcome(ack) {
+    const parsed = readToolApprovalRespondAck(ack);
+    if (parsed === undefined)
+        return { state: 'unknown' };
+    if (parsed.rulePersisted === true)
+        return { state: 'persisted' };
+    if (parsed.rulePersisted === false) {
+        // 空串/非串已在 readToolApprovalRespondAck 降缺席(单一台账),这里只剩「在场即带」。
+        return {
+            state: 'refused',
+            ...(typeof parsed.ruleRefusal === 'string' ? { reason: parsed.ruleRefusal } : {}),
+        };
+    }
+    return { state: 'unknown' };
+}

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';
@@ -228,6 +231,8 @@ export * from './hitl/parkRowBirthWait.js';
 export * from './hitl/approvalDecisionNoteAudit.js';
 export * from './hitl/askParkRowRouting.js';
 export * from './hitl/resumeRunningCard.js';
+export * from './hitl/persistedRulesWire.js';
+export * from './hitl/localAllowRule.js';
 export * from './hitl/approvalsFeed.js';
 export * from './compensations.js';
 export * from './request/printNotification.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';
@@ -340,6 +350,19 @@ export * from './hitl/parkRowBirthWait.js';
 export * from './hitl/approvalDecisionNoteAudit.js';
 export * from './hitl/askParkRowRouting.js';
 export * from './hitl/resumeRunningCard.js';
+// ── A-028.14 / #244 F2(2026-08-14):HITL 规则侧上收 —— 持久规则车道通用判定半场 + durable 腿
+//    本地落规则判定骨架(源形 = cli persistedRulesWire / localAllowRuleWrite 的纯判定面)。
+// · persistedRulesWire:能力位双段 gate(permissionRules / permissionRulesRevoke 合取)、
+//   RulesFailure 处置分类(404 两支绝不共用一格)、keyset 翻页收口(游标失效重列 + 页数硬帽)、
+//   skipped.reason 前缀分类、persist-ack 三态读口 —— 读口与 `readToolApprovalRespondAck`
+//   **合成一处**(census top-08 #1 的双份台账收口本体);CC settings 三层 fs 读、SDK facade
+//   装配、通知呈现留宿主。
+// · localAllowRule:parseLocalAllowRule 窄化五步(①整工具拒/②工具名对齐/③字面锚/⑤裸解释器
+//   前缀/⑤b canonical 危险谓词)骨架;危险谓词与规则语法经 `LocalAllowRuleDeps` 注入
+//   (parkOwnership deps 同形)—— 谓词表本体(BARE_SHELL_PREFIXES / dangerousPatterns)留宿主,
+//   包内绝不自建第二份名单。🔴 安全面等值契约:拒绝集文案是三端可观察行为,cli 常驻套逐字锚。
+export * from './hitl/persistedRulesWire.js';
+export * from './hitl/localAllowRule.js';
 // B7 ③(census G20,**行为改动**不是搬迁):pending-approvals 推送 feed(stream 优先 / 断流回落
 // 轮询 / 定期再试)。🔴 它**不替换** D-1 的取件 —— 那三处必须继续走权威 `list()`(见文件头)。
 export * from './hitl/approvalsFeed.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;