@sema-agent/client-core 0.5.0 → 0.7.0

package/dist/headlessPermissionModeWire.js

@@ -0,0 +1,111 @@
+/**
+ * src/sema/headlessPermissionModeWire.ts — SEMA_HEADLESS_PERMISSION_MODE 部署旋钮
+ * (clay 拍板 2026-07-16:TB/bench 场景 headless `-p` 统一垫 bypassPermissions,对齐 CC bench 实跑的
+ * --dangerously-skip-permissions 姿势;落地形态 = 环境变量部署旋钮,产品缺省语义不动)。
+ *
+ * gap-check 现状(2026-07-16,db3c72f):
+ *   · `--permission-mode <mode>` CLI flag 存在(main.tsx:1042,choices = PERMISSION_MODES + 'manual'),
+ *     `--dangerously-skip-permissions` 亦在;但两者在 headless `-p` 车道【都不进 TaskRequest】——
+ *     seamQueryEngine.ask 自建请求从不 stamp permissionMode(交互 REPL 走 seamQuery →
+ *     permissionWireCaps.permissionModeField,print/headless 从不 stamp = server absent-mode)。
+ *   · 即:今天 `-p` 的权限面全靠 server 对 absent-mode 的缺省解释([830]① server 1.191 五模式解释层,
+ *     absent 不挂门)。core [885] 残余建议:显式垫,防未来缺省变化让 TB 静默变盘。
+ *
+ * 语义(件2 拍板逐字):
+ *   优先级:CLI flag 显式值 > SEMA_HEADLESS_PERMISSION_MODE env > 现状 absent-mode(env 是缺省态的
+ *   垫层,flag 恒赢——flag 在场时 env 完全不看,即使 flag 值不在 wire 词表内)。
+ *   值域 = 壳既有 wire permissionMode 词表(permissionWireCaps.PermissionMode:default / plan /
+ *   acceptEdits / bypassPermissions / auto——分类器批3 [907] server 五模式表,server ≥1.209 认
+ *   "auto")。非法 env 值 ⇒ 一次性 warn + 回落现状,绝不 fail 启动。
+ *   stamp 规则:
+ *     · flag 来源:非 default 的 wire 词直接 stamp(auto 自分类器批3 起入表);`default` 不 stamp
+ *       (= 今天 flag 的实际效果,零行为变化);wire 词表外的 flag 值(dontAsk/manual…是壳内部
+ *       模式,server 不认)不 stamp。
+ *     · env 来源:五词全部显式 stamp(含 `default`——env 是"显式垫层"旋钮,设了就是要显式语义,
+ *       不再依赖 server absent-mode 缺省解释;server 1.191 对显式 "default" 走 manual ask 门解释)。
+ *   车道纪律:本模块只被 seamQueryEngine.ask(headless `-p`)import;交互 REPL(seamQuery)一根毛
+ *   不动——单测有 source-level lane proof(detachWire 同款)。
+ */
+import { permissionModeField } from './permissionWireCaps.js';
+import { hostEnv } from './hostEnv.js';
+/** 部署旋钮 env 键名(settings.json env 块 → 1a-envseed → process.env 同车道)。 */
+export const HEADLESS_PERMISSION_MODE_ENV = 'SEMA_HEADLESS_PERMISSION_MODE';
+/** wire 词表(permissionWireCaps.PermissionMode 的运行时镜像;大小写敏感——与 CC flag choices 一致)。
+ *  'auto'(分类器批3,[907]):server ≥1.209 五模式表认;老 server coerce 未知词 → "default" 只紧不松。 */
+export const HEADLESS_PERMISSION_WIRE_MODES = [
+    'default',
+    'plan',
+    'acceptEdits',
+    'bypassPermissions',
+    'auto',
+];
+/**
+ * argv 里的 `--permission-mode <v>` / `--permission-mode=<v>`(后者/后出现者赢,commander 同语义)与
+ * `--dangerously-skip-permissions`(= bypassPermissions;`--permission-mode` 在场时让位)。
+ * 返回 undefined = flag 车道未显式表态。
+ */
+export function permissionModeFromArgv(argv) {
+    let mode;
+    let dsp = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--permission-mode') {
+            const v = argv[i + 1];
+            if (typeof v === 'string' && !v.startsWith('-')) {
+                mode = v;
+                i++;
+            }
+        }
+        else if (a?.startsWith('--permission-mode=')) {
+            mode = a.slice('--permission-mode='.length);
+        }
+        else if (a === '--dangerously-skip-permissions') {
+            dsp = true;
+        }
+        else if (a === '--') {
+            break; // POSIX 约定:-- 之后不是 flag
+        }
+    }
+    if (mode !== undefined)
+        return mode;
+    if (dsp)
+        return 'bypassPermissions';
+    return undefined;
+}
+// 一次性告警 latch(-p 是 one-shot 进程;测试钩子可重置)
+let warnedInvalidEnv = false;
+/**
+ * 解析 headless `-p` 的 permissionMode stamp。纯函数除告警 latch(同值只警一次)。
+ * 调用方(seamQueryEngine.ask)live-gated:mock/pty 车道永不经过这里。
+ */
+export function resolveHeadlessPermissionMode(argv, env = hostEnv()) {
+    // 1) CLI flag 恒赢:flag 在场(含 wire 词表外的壳内部模式)⇒ env 完全不看。
+    const flagMode = permissionModeFromArgv(argv);
+    if (flagMode !== undefined) {
+        // permissionModeField 只放行 wire 已知的非 default 词;default/壳内部词 ⇒ {}(现状,零变化)。
+        return { fields: permissionModeField(flagMode), source: 'flag' };
+    }
+    // 2) env 垫层。
+    const raw = env[HEADLESS_PERMISSION_MODE_ENV]?.trim();
+    if (raw === undefined || raw === '') {
+        return { fields: {}, source: 'absent' };
+    }
+    if (HEADLESS_PERMISSION_WIRE_MODES.includes(raw)) {
+        // env 是显式垫层:五词全 stamp(含 default——stampDefault 显式垫,不依赖 absent-mode 缺省解释)。
+        return {
+            fields: permissionModeField(raw, { stampDefault: true }),
+            source: 'env',
+        };
+    }
+    // 3) 非法 env 值:一次性 warn + 回落现状(绝不 fail)。
+    const resolution = { fields: {}, source: 'absent' };
+    if (!warnedInvalidEnv) {
+        warnedInvalidEnv = true;
+        resolution.warning = `sema: ${HEADLESS_PERMISSION_MODE_ENV}="${raw}" is not a recognized permission mode (expected one of: ${HEADLESS_PERMISSION_WIRE_MODES.join(', ')}) — ignoring it, this run keeps the default permission behavior`;
+    }
+    return resolution;
+}
+/** 测试钩子:重置一次性告警 latch。 */
+export function _resetHeadlessPermissionModeWireForTest() {
+    warnedInvalidEnv = false;
+}

package/dist/headlessReconnectWire.d.ts

@@ -0,0 +1,96 @@
+/**
+ * src/sema/headlessReconnectWire.ts — 重连腿 M2 · R1 换车道续收(design/HEADLESS-RECONNECT-DESIGN.md
+ * §3 R1 + §6 M2,2026-07-16)。M1(detachWire 头 + 信号 cancel 兜底,2545900)已发运;本模块把
+ * engine-alive-idle 判死升级为「先重连、耗尽才判死」——但只在 headless `-p` detach 车道。
+ *
+ * 触发点(design §3,四条同时成立才进重连分支):
+ *   ① tasks/stream 以 SseIdleError 收场(流静默超 grace)——其它失败形态(engine-down/restarted/
+ *      4xx/断连 reset)原样穿透,现行路径一字不动;
+ *   ② headless `-p` ∧ detach 头已随首次 POST 发出——本 wrapper 只在 liveClient.tasks.stream 的
+ *      opts.headers 携带 x-detach-on-disconnect: 'true' 时套上(唯一 set 头的调用方 =
+ *      seamQueryEngine.ask;交互 REPL(seamQuery)与 headless-bg worker 都不传 headers ⇒ 源码级
+ *      证明这两条车道一根毛不动,断连=取消语义保持,铁律 5);
+ *   ③ durableTaskId 已捕获(X-Task-Id 早捕获,liveClient onResponse)——没有 id 无从换道,原样抛;
+ *   ④ 每次重连前置 probeEngineAlive(批 D /health 探针复用)——引擎死了绝不空等,原样抛走
+ *      现行 engine-down 判死。
+ *
+ * 铁律对表:
+ *   · signal.aborted 恒先行(铁律 3,seamQuery.ts:1073 契约):重试环每一轮入口先查 aborted,
+ *     用户中止绝不进重连分支(连探活都不做);续收中途 aborted → 干净 return(镜像 SDK parseSse
+ *     的 abort 语义),上游 print.ts 的 SIGINT 处置(M1 cancel 兜底)全权接管。
+ *   · 有界(铁律 5/任务 §4):每 run 最多 HEADLESS_RECONNECT_MAX=2 次壳级重连;耗尽 → 重抛
+ *     【原始】SseIdleError(对象恒原件,后续 diagnoseSseIdleTear 打 engine-alive-idle 标 →
+ *     seamQueryEngine 现行诚实判死文案,字节不变)。
+ *   · 15min STREAM_MAX_DURATION 硬顶(任务 §3):runs.events 车道被 cap 断开时,SDK sse.js
+ *     parseSse 自带 Last-Event-ID 立即重连(frame.id 锁存 → 重开带 lastEventId;无进展 5 连败
+ *     才放弃)——cap 重连发生在【同一次】openEvents 调用内部,计入同一次重连预算(不额外扣),
+ *     铁律 4「不动 SDK」同时满足:runs.events 消费面已有,本模块零 SDK 改动。
+ *   · 与 headless-bg 有界重发腿(bgTearResends)互斥:重发腿在 seamQuery.query(REPL 形 worker),
+ *     其触发词表本就只含 restarted/engine-down(seamQuery.ts:1143),engine-alive-idle 从不重发;
+ *     本重连腿只在 -p detach 车道。两腿车道 + 词表双重不相交,结构性互斥。
+ *
+ * ── R1 去重锚选型(任务书要求写明选型与理由)────────────────────────────────────────────────
+ * runs.events 车道:server streamRunEvents 把账本 seq 写成 SSE `id:` 行(formatEvent id: ev.seq),
+ * SDK sse.js 把 frame.id 回贴到 ev.id ⇒ 每个续收帧带单调递增数字 seq。锚 = lastSeenSeq:
+ *   a) 跨壳级 attempt 续传:第二次 openEvents 传 Last-Event-ID=lastSeenSeq(server 从其后回放);
+ *   b) 防双投:丢弃 seq ≤ lastSeenSeq 的重放帧(server 从头回放/416 回卷都兜住)。
+ * 首次换道(tasks/stream → runs.events):tasks/stream 帧无 id(SDK tasks.js 不回贴 frame.id,
+ * server sync 腿也不写 id: 行)⇒ 无从定位,只能从起点(不带 Last-Event-ID)拉。防双投依据 =
+ * server 实证(1.205/1.209 dist 逐行核对):sync /v1/tasks/stream 腿【不】逐事件落账(runs.js 的
+ * appendEvent 只在 async runs 腿与 resume 腿;sync 腿只 createRun + setTerminal(finalResult))⇒
+ * sync 腿 run 的账本在终局前恒空,从起点拉不存在「重放已消费帧」面;将来 server 若开始 sync 腿
+ * 落账,守卫 = ①终帧唯一(本 wrapper 首终帧即 return + adapter runStream 首终帧 return + 批 B
+ * 双帧守卫「恰一条 result」)②seq 锚(首帧起锁存,attempt 间绝不回放)③gap-check 记账:换道前
+ * 已消费的 delta 与账本聚合 text 事件无逐字节对齐关系,真正的精确锚需要 server 给 tasks/stream
+ * 帧发 id(引擎侧诉求,走黑板,非壳侧可解)。
+ *
+ * ── 账本空(现役 server sync 腿)时的续收降级(R1b)────────────────────────────────────────
+ * 同一实证的另一面:detach 后 run 后台跑完,账本无事件行,runs.events 只会心跳保活直到 run row
+ * 落终局,然后无终帧地收流(SDK 无进展 5 连败抛错)。此时 run 的终局【已在】run row 里
+ * (GET /v1/runs/:id → RunRecord.result = TaskResult,含完整最终文本)——续收环的 catch 里查
+ * run row:已终局 → 合成终帧(done{result} / failed)喂回同一消费管线,turn 以 rc=0 正常收尾,
+ * 最终答案全量保真(-p 的 result 面 = done.result.result 字符串,非增量拼接);未终局(还在跑/
+ * suspended)→ 计预算继续重试,耗尽才判死。中途 delta 的全帧保真(R1a 环)在账本有事件行时
+ * (resume 腿 run / 将来 sync 腿落账的 server)自动生效——两形态由同一环处理,帧结构差异
+ * (text/reasoning 聚合事件 vs *_delta)由 adapter eventToSdkMessage 既有 case 'text'/'reasoning'
+ * 消费面兜住。
+ */
+import type { AgentEvent } from '@sema-agent/sdk';
+/** 每 run 壳级重连预算(design 铁律 5)。cap/416 的 SDK 内部续传不计入(同一次 openEvents)。 */
+export declare const HEADLESS_RECONNECT_MAX = 2;
+/** GET /v1/runs/:id 的 run row 终局子集(SDK RunRecord;字段防御性读)。 */
+export interface RunRowLike {
+    status?: string;
+    result?: unknown;
+    errorCode?: string;
+    error?: string;
+}
+export interface HeadlessReconnectDeps {
+    /** 引擎 baseUrl(探活用;凭证不经本模块——openEvents/getRun 闭包自带)。 */
+    baseUrl: string;
+    /** X-Task-Id 早捕获读数(liveClient onResponse 闭包);null = 未捕获 ⇒ 不换道。 */
+    getTaskId: () => string | null;
+    /** runs.events 换道开流(liveClient 闭包 → client.runs.events;lastEventId = 去重锚续传)。 */
+    openEvents: (taskId: string, lastEventId?: string) => AsyncGenerator<AgentEvent>;
+    /** run row 终局读数(R1b 降级捞终局;失败返回 null,永不抛)。 */
+    getRun: (taskId: string) => Promise<RunRowLike | null>;
+    signal?: AbortSignal;
+    /** 测试注入位;缺省 = 批 D probeEngineAlive(/health,2s 预算)。 */
+    probeAlive?: (baseUrl: string) => Promise<boolean>;
+}
+/** run row → 合成终帧(R1b)。带 result 对象的引擎终态(全词表)合成 done{result}——与
+ *  tasks/stream 终帧字节同构,adapter terminalToSdkResult 全枚举分流([909]B1)原样生效
+ *  (timeout→error_max_turns、blocked→error_during_execution、park→[884]A1 臂);裸 failed
+ *  (无 result)合成 failed 事件。running / 无 result 的 park(可能还会被 approvals 解锁)null
+ *  —— 计预算继续重试,耗尽才判死。 */
+export declare function terminalEventFromRunRow(row: RunRowLike | null): AgentEvent | null;
+/**
+ * withHeadlessR1Reconnect(live, deps) — the M2 R1 lane-switch wrapper.
+ *
+ * 位置:liveClient.tasks.stream 管线【最内层】(demux/HITL 桥/captureSessionId/normalizeToolNames/
+ * diagnoseSseIdleTear 之内)——续收帧与合成终帧流经与 live 帧完全相同的下游包装(工具名规整、
+ * sessionId 捕获、HITL 桥、批 B 守卫),零特殊路径。重连成功 → 生成器以终帧正常 return ⇒
+ * diagnoseSseIdleTear/tearVerdict 永不介入,turn 正常收尾;耗尽/不可换道 → 重抛原始 SseIdleError,
+ * 外层打标 + 现行判死文案,字节不变。
+ */
+export declare function withHeadlessR1Reconnect(live: AsyncGenerator<AgentEvent>, deps: HeadlessReconnectDeps): AsyncGenerator<AgentEvent>;

package/dist/headlessReconnectWire.js

@@ -0,0 +1,141 @@
+import { isSseIdleError, probeEngineAlive } from './sseIdleTriage.js';
+import { hostEnv } from './hostEnv.js';
+/** 每 run 壳级重连预算(design 铁律 5)。cap/416 的 SDK 内部续传不计入(同一次 openEvents)。 */
+export const HEADLESS_RECONNECT_MAX = 2;
+/** SEMA_DEBUG 探针(headless `-p` 车道 Ink 未挂载,stderr 可用;绝不带凭证/帧内容)。 */
+function debugLog(msg) {
+    if (hostEnv().SEMA_DEBUG) {
+        // eslint-disable-next-line no-console
+        console.error(`[sema] headless reconnect: ${msg}`);
+    }
+}
+/** 引擎终态词表全集(core 1.298 TaskStatus;server runs.js setTerminal(taskId, safe.status, …)
+ *  把引擎 status【原样】写进 run row ⇒ row.status 可以是全部 6 词,不只 completed/failed)。
+ *  [909]B3 复核发现的真缺口:此前只认 completed/failed,timeout/blocked 终局的 run row 永不
+ *  合成终帧 → 续收环重试到预算耗尽 → 假判死(终局明明就在 row 里)。 */
+const RUN_ROW_TERMINAL_STATUSES = new Set([
+    'completed',
+    'failed',
+    'timeout',
+    'blocked',
+    'suspended',
+    'needs_review',
+]);
+/** run row → 合成终帧(R1b)。带 result 对象的引擎终态(全词表)合成 done{result}——与
+ *  tasks/stream 终帧字节同构,adapter terminalToSdkResult 全枚举分流([909]B1)原样生效
+ *  (timeout→error_max_turns、blocked→error_during_execution、park→[884]A1 臂);裸 failed
+ *  (无 result)合成 failed 事件。running / 无 result 的 park(可能还会被 approvals 解锁)null
+ *  —— 计预算继续重试,耗尽才判死。 */
+export function terminalEventFromRunRow(row) {
+    if (!row || typeof row.status !== 'string')
+        return null;
+    if (RUN_ROW_TERMINAL_STATUSES.has(row.status)) {
+        if (row.result && typeof row.result === 'object') {
+            // sync 腿 setTerminal 存的就是终帧的 TaskResult(status 含 failed/timeout/blocked 形)——
+            // 与 tasks/stream 终帧 done{result} 字节同构,terminalToSdkResult 文案线原样生效。
+            return { type: 'done', result: row.result };
+        }
+        if (row.status === 'failed') {
+            return {
+                type: 'failed',
+                ...(row.errorCode ? { errorCode: row.errorCode } : {}),
+                errorMessage: row.error ?? 'run failed',
+            };
+        }
+    }
+    return null;
+}
+/**
+ * withHeadlessR1Reconnect(live, deps) — the M2 R1 lane-switch wrapper.
+ *
+ * 位置:liveClient.tasks.stream 管线【最内层】(demux/HITL 桥/captureSessionId/normalizeToolNames/
+ * diagnoseSseIdleTear 之内)——续收帧与合成终帧流经与 live 帧完全相同的下游包装(工具名规整、
+ * sessionId 捕获、HITL 桥、批 B 守卫),零特殊路径。重连成功 → 生成器以终帧正常 return ⇒
+ * diagnoseSseIdleTear/tearVerdict 永不介入,turn 正常收尾;耗尽/不可换道 → 重抛原始 SseIdleError,
+ * 外层打标 + 现行判死文案,字节不变。
+ */
+export async function* withHeadlessR1Reconnect(live, deps) {
+    let originalTearErr;
+    try {
+        for await (const ev of live) {
+            yield ev;
+            const t = ev?.type;
+            if (t === 'done' || t === 'failed')
+                return; // 终帧已到 —— 首终帧即收官(批 B 双帧守卫同侧)
+        }
+        return; // 流干净收尾(mock 车道/abort return)——无终帧也不由本腿补,现行行为不变
+    }
+    catch (e) {
+        originalTearErr = e;
+    }
+    // ── 重试环:每轮入口按铁律顺序分诊,非命中一律重抛【原始】错误(现行失败路径字节不变)──
+    let attempts = 0;
+    let lastSeenSeq; // R1 去重锚(runs.events SSE id = 账本 seq;见模块头选型)
+    const probe = deps.probeAlive ?? probeEngineAlive;
+    for (;;) {
+        if (deps.signal?.aborted)
+            throw originalTearErr; // 铁律 3:用户中止恒先行,绝不进重连分支
+        if (!isSseIdleError(originalTearErr))
+            throw originalTearErr; // 只救 engine-alive-idle 的静默撕裂形
+        const taskId = deps.getTaskId();
+        if (!taskId)
+            throw originalTearErr; // X-Task-Id 未捕获(首轮早期窗)——无从换道,接受
+        if (attempts >= HEADLESS_RECONNECT_MAX) {
+            debugLog(`budget exhausted (${attempts}/${HEADLESS_RECONNECT_MAX}) — falling to the honest death path`);
+            throw originalTearErr; // 耗尽 → 现行 engine-alive-idle 判死(文案已诚实,M1)
+        }
+        attempts++;
+        if (!(await probe(deps.baseUrl)))
+            throw originalTearErr; // 铁律 5:引擎死 → 现行 engine-down 路径
+        debugLog(`attempt ${attempts}/${HEADLESS_RECONNECT_MAX} — switching to runs.events(${taskId}${lastSeenSeq !== undefined ? `, Last-Event-ID ${lastSeenSeq}` : ''})`);
+        try {
+            const cont = deps.openEvents(taskId, lastSeenSeq !== undefined ? String(lastSeenSeq) : undefined);
+            for await (const ev of cont) {
+                if (deps.signal?.aborted)
+                    return; // 中止 → 干净收流(print.ts SIGINT 处置 + M1 cancel 兜底接管)
+                const rec = ev;
+                const t = rec?.type;
+                if (t === undefined)
+                    continue; // 心跳帧(data:{})——车道保活杂音,不进消费管线
+                if (t === 'error') {
+                    // STREAM_MAX_DURATION cap 帧(server streamSseLog):SDK parseSse 已锁存 Last-Event-ID
+                    // 并自动重开(同一次 openEvents 内部,计入同一次预算)——本帧是车道协议杂音,不下发。
+                    debugLog(`runs.events lane frame type=error code=${String(rec?.code ?? '')} — SDK resumes with Last-Event-ID internally`);
+                    continue;
+                }
+                const seq = typeof rec?.id === 'string' && /^\d+$/.test(rec.id) ? Number(rec.id) : undefined;
+                if (seq !== undefined) {
+                    if (lastSeenSeq !== undefined && seq <= lastSeenSeq)
+                        continue; // 重放帧 → seq 锚去重(防双投)
+                    lastSeenSeq = seq;
+                }
+                // 终帧日志必须在 yield 之前:下游(adapter runStream)拿到首终帧即 return 弃养本生成器,
+                // yield 之后的语句不再执行(受控腿 leg 1 实测)。return 语义不受影响(弃养即收官)。
+                if (t === 'done' || t === 'failed')
+                    debugLog(`resumed to terminal (${String(t)}) after ${attempts} reconnect(s)`); // 判死解除
+                yield ev;
+                if (t === 'done' || t === 'failed')
+                    return;
+            }
+            // 无终帧收流(SDK 只在 signal.aborted 时干净 return;防御分支)——按撕裂再走一轮预算
+            if (deps.signal?.aborted)
+                return;
+            debugLog('runs.events continuation ended without a terminal frame');
+        }
+        catch (contErr) {
+            // 续收环失败。现役 server sync 腿账本为空 ⇒ run 落终局后 SDK 以「无进展 5 连败」收场
+            // ——这不是死刑:终局已在 run row(R1b),查得到就合成终帧收官。
+            debugLog(`runs.events continuation failed: ${contErr instanceof Error ? contErr.message : String(contErr)}`);
+            if (deps.signal?.aborted)
+                throw originalTearErr; // 铁律 3:中止后不捞终局,交给上游中止处置
+            const row = await deps.getRun(taskId).catch(() => null);
+            const terminal = terminalEventFromRunRow(row);
+            if (terminal) {
+                debugLog(`run row terminal (${String(row?.status)}) — synthesizing the terminal frame (R1b)`);
+                yield terminal;
+                return;
+            }
+            // run 还在跑 / suspended / row 读不到 —— 计预算继续重试(环顶做 aborted/预算/探活分诊)
+        }
+    }
+}

package/dist/host.d.ts

@@ -0,0 +1,90 @@
+/**
+ * host.ts — **包级宿主装配**(B4;B3 交接报告的建议件 + 设计稿 §5.4 「web 宿主的最小接入面」)。
+ *
+ * ## 两种口,别混
+ *
+ * · `AdapterContext`(seam.ts)= **per-turn 切片** —— 时钟、铸号、signal、定时器、攒批节拍。
+ *   它随每个 `adapt()` 调用传进来,因为这些东西**每个 turn 可以不一样**(比如这一 turn 可中断)。
+ * · `installHost()`(本文件)= **进程/端级装配** —— settings 读取、fs、通知队列。
+ *   它们在会话开始之前就该在位,而且被**请求构造期**的代码调用(`hooksForWire()` /
+ *   `scratchpadDirField()`),那时候根本没有 `ctx` 可传。
+ *
+ * ⇒ 判据:**这个能力是不是每 turn 会变?** 会 ⇒ ctx;不会 ⇒ installHost。
+ *
+ * ## 缺席语义(与 AdapterContext 同一条纪律)
+ *
+ * 🔴 缺席 = **该能力不启用**,不是报错、更不是「换个方式偷偷做」。库绝不 `require('fs')`、
+ * 绝不 `console.log`、绝不读 `process.env` 兜底 —— 那正是搬迁要切掉的东西。
+ * 但「静默不启用」有个已知的失败形:**宿主漏装了,而症状是某个面悄悄空掉**。所以每个口都带
+ * miss 计数(`hostPortMisses()`),宿主自检断言它恒为 0 —— 与 `notificationQueuePortMisses()`
+ * 同一套姿势([probe-must-prove-it-speaks]:不能让「什么都没有」看起来像「一切正常」)。
+ */
+import type { AdapterLogLevel } from './seam.js';
+import { type NotificationQueuePort } from './notifications.js';
+/**
+ * settings 口 —— 用户 settings 文件的读取面(壳=三层合并后的文件读;web=center 下发;桌面=主进程)。
+ *
+ * 🔴 `shouldSkipHookDueToTrust` 是**安全门**不是取值:未受信目录的 hook 绝不上 wire。
+ * 端必须真实现它;不实现(端返回恒 false)= 把信任门拆了。所以它在 required 清单里。
+ */
+export interface SettingsPort {
+    /** 按来源取 settings(cli `utils/settings/settings.ts` 的 `getSettingsForSource`)。 */
+    getSettingsForSource(source: string): unknown;
+    /** 信任门:该 hook 是否因来源不受信而跳过。**返回 true = 跳过**。 */
+    shouldSkipHookDueToTrust(hook: unknown): boolean;
+}
+/**
+ * fs 口 —— scratchpad 目录族(cli `utils/permissions/filesystem.ts`)。
+ * `ensureScratchpadDir` 是**真 IO**(mkdir);浏览器宿主整个口省略即可(⇒ 不 stamp scratchpadDir,
+ * additive 字段缺席对引擎无害)。
+ */
+export interface FsPort {
+    getScratchpadDir(): string | undefined;
+    isScratchpadEnabled(): boolean;
+    /** 🔴 壳侧真身是 **async**(mkdir 0o700);端可返 void 或 Promise,库两种都吞(fire-and-forget)。 */
+    ensureScratchpadDir(): void | Promise<void>;
+}
+/** 定时器口(进程级默认;`ctx.setTimer` 仍可按 turn 覆盖)。 */
+export interface TimersPort {
+    setTimer(ms: number, fn: () => void): unknown;
+    clearTimer(handle: unknown): void;
+}
+/** `installHost` 的入参 —— 全部可选,缺席即该能力不启用。 */
+export interface HostPorts {
+    log?(level: AdapterLogLevel, msg: string, data?: unknown): void;
+    probe?(channel: string, line: string): void;
+    /** 通知队列(B2 引入)。经本口装 == 直接调 `installNotificationQueuePort`,单一真源不分裂。 */
+    queue?: NotificationQueuePort | null;
+    timers?: TimersPort;
+    settings?: SettingsPort;
+    fs?: FsPort;
+}
+/**
+ * 装配宿主口。**可多次调用做增量装配**(只覆盖本次给出的键),便于分模块装。
+ * 传 `queue` 会直通 `installNotificationQueuePort` —— 队列的真源仍在 notifications.ts,
+ * 本文件不另存一份([paired-mechanisms-must-share-premise]:两处各存一份 = 装了 A 读了 B)。
+ * 返回一个还原函数(测试/热重载用)。
+ */
+export declare function installHost(ports: HostPorts): () => void;
+/** 日志(缺席 = 静默,**不计 miss**:诊断面本就是可选的)。 */
+export declare function hostLog(level: AdapterLogLevel, msg: string, data?: unknown): void;
+/** 行式探针(缺席 = 静默,不计 miss:同上)。 */
+export declare function hostProbe(channel: string, line: string): void;
+/** settings 口(缺席 = undefined + 计 miss:漏装会让 hooks 整条 wire 静默空掉)。 */
+export declare function hostSettings(): SettingsPort | undefined;
+/** fs 口(缺席 = undefined + 计 miss)。 */
+export declare function hostFs(): FsPort | undefined;
+/** 定时器口(缺席 = undefined,不计 miss:T40 竞速本就允许不启用)。 */
+export declare function hostTimers(): TimersPort | undefined;
+/**
+ * 🔴 宿主自检出口 —— 恒应为空对象。非空 = 有口漏装,**对应的面已经在静默失效**。
+ * 含通知队列的 miss(从 notifications.ts 汇过来,宿主只需看这一个数)。
+ */
+export declare function hostPortMisses(): Record<string, number>;
+/**
+ * 测试钩:清空装配与计数。
+ * 🔴 队列那一路必须走 `_resetNotificationQueuePortForTest()` 而不是 `installNotificationQueuePort(null)`
+ * —— 后者只卸口、**不清 miss 计数**,于是 `hostPortMisses()` 会带着上一段测试的历史 miss,
+ * 让「未装配时 misses 为空」这类断言恒假(B4 首写时就撞上了)。
+ */
+export declare function _resetHostForTest(): void;

package/dist/host.js

@@ -0,0 +1,84 @@
+import { _resetNotificationQueuePortForTest, installNotificationQueuePort, notificationQueuePortMisses, } from './notifications.js';
+let host = {};
+const misses = Object.create(null);
+const warned = new Set();
+function miss(name) {
+    misses[name] = (misses[name] ?? 0) + 1;
+    if (!warned.has(name)) {
+        warned.add(name);
+        // eslint-disable-next-line no-console
+        console.error(`[client-core] host port "${name}" NOT installed — the surface it drives is silently inert. ` +
+            'Host must call installHost({ ' +
+            name +
+            ': … }) at startup (see host.ts).');
+    }
+    return undefined;
+}
+/**
+ * 装配宿主口。**可多次调用做增量装配**(只覆盖本次给出的键),便于分模块装。
+ * 传 `queue` 会直通 `installNotificationQueuePort` —— 队列的真源仍在 notifications.ts,
+ * 本文件不另存一份([paired-mechanisms-must-share-premise]:两处各存一份 = 装了 A 读了 B)。
+ * 返回一个还原函数(测试/热重载用)。
+ */
+export function installHost(ports) {
+    const prev = { ...host };
+    if ('log' in ports)
+        host.log = ports.log;
+    if ('probe' in ports)
+        host.probe = ports.probe;
+    if ('timers' in ports)
+        host.timers = ports.timers;
+    if ('settings' in ports)
+        host.settings = ports.settings;
+    if ('fs' in ports)
+        host.fs = ports.fs;
+    if ('queue' in ports)
+        installNotificationQueuePort(ports.queue ?? null);
+    return () => {
+        host = prev;
+    };
+}
+/** 日志(缺席 = 静默,**不计 miss**:诊断面本就是可选的)。 */
+export function hostLog(level, msg, data) {
+    host.log?.(level, msg, data);
+}
+/** 行式探针(缺席 = 静默,不计 miss:同上)。 */
+export function hostProbe(channel, line) {
+    host.probe?.(channel, line);
+}
+/** settings 口(缺席 = undefined + 计 miss:漏装会让 hooks 整条 wire 静默空掉)。 */
+export function hostSettings() {
+    return host.settings ?? miss('settings');
+}
+/** fs 口(缺席 = undefined + 计 miss)。 */
+export function hostFs() {
+    return host.fs ?? miss('fs');
+}
+/** 定时器口(缺席 = undefined,不计 miss:T40 竞速本就允许不启用)。 */
+export function hostTimers() {
+    return host.timers;
+}
+/**
+ * 🔴 宿主自检出口 —— 恒应为空对象。非空 = 有口漏装,**对应的面已经在静默失效**。
+ * 含通知队列的 miss(从 notifications.ts 汇过来,宿主只需看这一个数)。
+ */
+export function hostPortMisses() {
+    const out = { ...misses };
+    const q = notificationQueuePortMisses();
+    if (q > 0)
+        out.queue = q;
+    return out;
+}
+/**
+ * 测试钩:清空装配与计数。
+ * 🔴 队列那一路必须走 `_resetNotificationQueuePortForTest()` 而不是 `installNotificationQueuePort(null)`
+ * —— 后者只卸口、**不清 miss 计数**,于是 `hostPortMisses()` 会带着上一段测试的历史 miss,
+ * 让「未装配时 misses 为空」这类断言恒假(B4 首写时就撞上了)。
+ */
+export function _resetHostForTest() {
+    host = {};
+    for (const k of Object.keys(misses))
+        delete misses[k];
+    warned.clear();
+    _resetNotificationQueuePortForTest();
+}

package/dist/index.d.ts

@@ -5,6 +5,22 @@
  * 沿革:@sema-agent/wire-cc-adapter 0.1.0 = seam 类型 + id 确定性派生 + 首批踩坑纯函数;
  * 0.1.2(#52a)= adapt() 管线首批(纯投影臂全落 + 壳态耦合臂投影成 ChromeEvent + 差分守卫);
  * 0.2.0 = 迁入 sema-client-core 独立仓并改名(旧 npm 名 deprecate 指本包);
+ * 0.7.0 = **B5 批**(设计稿 §3 B5):① **配对台账折回**([1857] —— 0.6.0 把 `notifiedRuns`/
+ *   `cardEnqueuedRuns` 放适配器实例,与清账/记账的另一半不共享前提 = 双卡/UI 零显示/模型二收,
+ *   本批整体折回 notifications.ts 的 module 台账);② **B/D/E 层搬入**(`toolResult.ts`:
+ *   structuredToToolUseResult 14 case + wireOutputToBody 3 臂 + E 层 4 臂),`adapt()` 从此
+ *   自己铸 `tool_result` 卡与两处开卡兜底;③ **structured 白名单吃现货**([1840]§一 30 项 ——
+ *   在场则 T11/T14 正则退位、T24 的 B 层惰性退位,缺席保回落,退位由**调用计数器**钉死);
+ *   ④ **T7 诚实缺席**(§8-4:不搬 mock 合成器,改 `_sema_degraded:'wire_carried_no_output'`)与
+ *   **T20 diff hunks 进包**(`diff/patch.ts`,本包**第一个** runtime dep `diff`)。
+ *   🆕 两个 chrome 臂:`bgshell_register`(#117a 判定在库、执行留宿主)· `task_ledger_sync{source:'structured'}`。
+ * 0.6.0 = **B4 批**(设计稿 §3 B4):A 层帧分派**收官**(第 14 臂 `task_progress` + 行绑定/
+ *   inline stats/alias/#6 常驻台账/SubagentStart/workflow lane 三级门 + `settlePanelTasks` 三处 sweep
+ *   全接线)· P0-2 tool label 侧信道补漏(0.5.0 真缺口)· **请求面合一**(`request/taskRequest.ts`:
+ *   三个构造器的字段集与合并语义收成一份,车道差异做成 `REQUEST_FIELD_MATRIX` 数据表)·
+ *   §8-2 构造点收编(`resolveWireAuth`)· §8-1 verb 门面接口定型(`ClientSliceLike` + `CLIENT_VERBS`,
+ *   **编译期**双向闭合门)· `CHROME_ARMS` 覆盖率出口 · 包级宿主装配 `installHost()`(settings/fs/
+ *   queue/timers 四口 + `hostPortMisses()` 自检)· `scratchpadWireCaps` 搬入(FsPort 端到端证明)。
  * 0.5.0 = **B3 批**(设计稿 §3 B3):`AdapterContext` 扩容(log/probe/signal/setTimer/clearTimer/
  *   coalesceIntervalMs,**只加可选位 = minor 不 BREAKING**)· 适配内核搬入(`adapter/types` 运行时
  *   半场 + `adapter/downstream` 三件 + `adapter/runStream`)· runStream **两条外向边切除**
@@ -29,9 +45,15 @@
  *   —— B2 新增:notifications.ts(11 个通知台账 + 队列 port + 两个 probe 槽)·
  *   agentsWireCaps.ts(prepare 缓存/投影闭包/一次性告警集)· liveModelCatalog.ts(目录 + refresher)·
  *   sessionModelLatch.ts(三个 latch)· ultracodeWireCaps.ts(sticky preset)。
+ *   —— B4 新增:scratchpadWireCaps.ts(`ensured` 建目录闩)· host.ts(宿主口装配 + miss 计数);
+ *   适配器**实例级**(非 module 级)新增 `firedSubagentStartHookTaskIds`——cli 那份是 module 级,
+ *   本包放实例级是**有意的**(多 session 宿主上 module 形会让两个会话互吞 SubagentStart,见 DIVERGENCE-6)。
  *   —— B3 新增:adapter/runStream.ts(`inFlightTurns` 计数,读口 `isRunStreamActive()`;
  *   两份实例 = 引擎滚动升级门恒读 false ⇒ **turn 中途热换引擎**,正是它当初要防的事)。
- * 🔴 **宿主装配**(B2 起本包有必须由宿主注入才完整的口):`installNotificationQueuePort()` ——
+ * 🔴 **宿主装配**——B4 起总入口是 `installHost({log,probe,queue,timers,settings,fs})`
+ *   (`installNotificationQueuePort()` 仍是队列的真源出口,`installHost({queue})` 直通它,两者不分裂);
+ *   自检口 `hostPortMisses()` 恒应为空对象,非空 = 有口漏装、对应的面已在静默失效。
+ *   —— B2 起的既有说明:`installNotificationQueuePort()` ——
  *   不装 = task-notification 投递静默丢失(`notificationQueuePortMisses()` 恒应为 0)。
  *   —— B3 新增(可选口,缺席 = 对应 UI 面在该宿主上是哑的,不是报错):`ctx.emitChrome`
  *   (runStream 的两条切边:statusline 真 usage / plan-review 审批卡)· `ctx.setTimer`
@@ -85,3 +107,16 @@ export * from './adapter/downstream/turnUsageToModelUsage.js';
 export * from './adapter/downstream/eventToSdkMessage.js';
 export * from './adapter/downstream/terminalToSdkResult.js';
 export * from './adapter/runStream.js';
+export * from './request/taskRequest.js';
+export * from './clientSlice.js';
+export * from './host.js';
+export * from './scratchpadWireCaps.js';
+export * from './toolResult.js';
+export * from './diff/patch.js';
+export * from './sandboxWire.js';
+export * from './scenarioWire.js';
+export * from './finalVerifyWire.js';
+export * from './limitsWire.js';
+export * from './interactiveToolsWire.js';
+export * from './headlessPermissionModeWire.js';
+export * from './headlessReconnectWire.js';