@sema-agent/client-core 0.4.0 → 0.6.0

package/dist/index.js

@@ -5,6 +5,19 @@
  * 沿革:@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.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 **两条外向边切除**
+ *   (lastTurnUsageStore / planReviewWire ⇒ `last_turn_usage` / `plan_review_park` 两个 chrome 臂)·
+ *   T38 三清第三清 + T40 IDLE-FLUSH + T57 第五处断闸 + T58 iterator cleanup + T59 abort + T60 收尾腿。
+ *   🆕 第三道守卫 `scripts/run-client-core-portability-test.mjs`(内核闭包 1571 文件 → **6 文件**)。
  * 0.4.0 = **B2 批**(设计稿 §3 B2):通知族三文件合并进 notifications.ts(engineTaskNotification 全文 +
  *   taskNotificationErrorSupplement 全文 + hookNoticeStore 判定半场)· 17 个 `*WireCaps` + engineWireSdk +
  *   sseIdleTriage + classifierVerdictWire 判定半场 + controlRouter + 模型面纯逻辑 4 件 + 新写 hostEnv;
@@ -23,8 +36,20 @@
  *   —— B2 新增:notifications.ts(11 个通知台账 + 队列 port + 两个 probe 槽)·
  *   agentsWireCaps.ts(prepare 缓存/投影闭包/一次性告警集)· liveModelCatalog.ts(目录 + refresher)·
  *   sessionModelLatch.ts(三个 latch)· ultracodeWireCaps.ts(sticky preset)。
- * 🔴 **宿主装配**(B2 起本包有必须由宿主注入才完整的口):`installNotificationQueuePort()` ——
+ *   —— B4 新增:scratchpadWireCaps.ts(`ensured` 建目录闩)· host.ts(宿主口装配 + miss 计数);
+ *   适配器**实例级**(非 module 级)新增 `firedSubagentStartHookTaskIds`——cli 那份是 module 级,
+ *   本包放实例级是**有意的**(多 session 宿主上 module 形会让两个会话互吞 SubagentStart,见 DIVERGENCE-6)。
+ *   —— B3 新增:adapter/runStream.ts(`inFlightTurns` 计数,读口 `isRunStreamActive()`;
+ *   两份实例 = 引擎滚动升级门恒读 false ⇒ **turn 中途热换引擎**,正是它当初要防的事)。
+ * 🔴 **宿主装配**——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`
+ *   (T40 IDLE-FLUSH,不给 = 长工具参数生成期已生成内容仍押到下一帧才上屏)· `ctx.signal`
+ *   (Esc 中断)· `ctx.log` / `ctx.probe`(诊断面)。
  */
 export * from './seam.js';
 export * from './workflow.js';
@@ -51,8 +76,8 @@ export * from './controlRouter.js';
 export * from './sseIdleTriage.js';
 export * from './engineWireSdk.js';
 export * from './classifierVerdictWire.js';
-// caps / wire 门族(17 个 *WireCaps —— 壳侧 hooksWireCaps / scratchpadWireCaps 因宿主耦合未搬,
-// 见 README 的 B2 记账)
+// caps / wire 门族(17 个 *WireCaps。B2 时 hooksWireCaps / scratchpadWireCaps 因宿主耦合未搬;
+// B4 已搬 scratchpadWireCaps(走 FsPort),hooksWireCaps 仍在壳里等 SettingsPort 接线 —— 见交接报告)
 export * from './agentsWireCaps.js';
 export * from './attachmentsWireCaps.js';
 export * from './clientContextWireCaps.js';
@@ -74,3 +99,22 @@ export * from './liveModelCatalog.js';
 export * from './modelBudgetRule.js';
 export * from './sessionModelLatch.js';
 export * from './effortWire.js';
+// ── B3 批:适配内核(增量合并 + 计量 + 流驱动)(2026-07-27)──────────────────────────────────
+// M/adapter 的 downstream 三件 + types 运行时半场 + runStream 整搬(设计稿 §3 B3)。
+// 🔴 runStream.ts 持 module 级 `inFlightTurns` 计数(isRunStreamActive 的读口)——单例清单新增项:
+//    写方=runStream 自己,读方=壳的引擎滚动升级门(turn 中途绝不热换引擎)。两份实例 = 门恒读 false。
+export * from './adapter/types.js';
+export * from './adapter/downstream/turnUsageToModelUsage.js';
+export * from './adapter/downstream/eventToSdkMessage.js';
+export * from './adapter/downstream/terminalToSdkResult.js';
+export * from './adapter/runStream.js';
+// ── B4 批:A 层帧分派收官 + 请求面合一 + 构造点收编(2026-07-27)────────────────────────────────
+// 请求面:三个构造器(seamQuery.toTaskRequest / seamQueryEngine / liveClient.toLiveRequest)
+// 的**字段集与合并语义**收成一份;车道差异做成 REQUEST_FIELD_MATRIX 数据表(gap:true = 判为漏)。
+export * from './request/taskRequest.js';
+export * from './clientSlice.js';
+// 包级宿主装配(per-turn 的 AdapterContext 之外的那一层:settings / fs / queue / timers)。
+// 🔴 `installNotificationQueuePort` 仍是队列的真源出口,`installHost({queue})` 只是直通它。
+export * from './host.js';
+// B2 判给 B4 的宿主耦合件之一(小的那件,同时是 FsPort 的端到端证明)。
+export * from './scratchpadWireCaps.js';

package/dist/request/taskRequest.d.ts

@@ -0,0 +1,135 @@
+/**
+ * request/taskRequest.ts — **请求面合一**(B4,多端改造设计稿 §3 B4 第二件 + §8-5 裁决)。
+ *
+ * ## 它解决的是什么
+ *
+ * 搬迁前壳里有 **三个**独立的请求构造器,谁也不知道对方长什么样:
+ *   · `S/seamQuery.toTaskRequest`(:535-869)—— 交互 REPL 车道;
+ *   · `S/seamQueryEngine`(:546-578)—— headless `-p` 车道,**自己另拼一份**;
+ *   · `S/liveClient.toLiveRequest`(:322-448)—— 两条车道共用的 live 兜底层。
+ *
+ * census §3.4 实测的漂移(B4 复核确认,逐字段见 `REQUEST_FIELD_MATRIX`):
+ *   · **print 独有** `finalVerification` / `limits` / `interactiveTools`;
+ *   · **TUI 独有** `ultracode` / `systemPrompt` / `reasoningEffort` / `images` / `model` /
+ *     rewind 三件 / `clientContext` / `scratchpadDir` / 已解析 settings。
+ * 这不是「两条车道本来就该不同」——里面**一部分是有理由的,一部分纯粹是漏了**。合一的目的不是
+ * 把它们抹平(那是行为改动),而是把「谁有谁没有、为什么」变成**一张表**:再漏就会在 diff 里显形。
+ *
+ * ## 分工铁律
+ *
+ * 🔴 本模块**零 env、零全局状态、零 IO**——所有值由端解析好之后放进 `TaskRequestInput`。
+ * 壳读 `process.env` / `getAppState()` / `getSessionId()` / `process.argv`,web 读 BFF 下发的配置,
+ * 桌面读主进程。包只负责三件**端无关**的事:
+ *   ① **字段集**:哪条车道 stamp 哪些字段(`REQUEST_FIELD_MATRIX`,带逐条理由);
+ *   ② **合并语义**:`settings` 四源合并、objective 的一次性装饰序、sessionId 三态;
+ *   ③ **live 门**:一个 `input.live` 布尔,替掉壳里散落的 20 处 `process.env.SEMA_LIVE_BASEURL` 判读。
+ */
+import type { TaskRequest } from '@sema-agent/sdk';
+/** 请求车道(§8-5:print lane 收编进来,但 stderr 分诊文案与 PrintStreamProjector 留壳)。 */
+export type RequestLane = 'interactive' | 'print';
+/** `TaskRequest` 的可写投影(包内按结构操作;SDK 型只做出口约束)。 */
+export type TaskRequestLike = Record<string, unknown>;
+/**
+ * 字段矩阵的一条 —— **这就是「不许静默统一」的载体**。
+ *
+ * `lanes` 是**事实**(今天哪条车道 stamp 它),`why` 是**理由**(为什么另一条没有)。
+ * 两者分开写:`lanes` 变了会被下面的自洽断言逮住,`why` 让下一棒知道该不该补齐。
+ * `gap:true` = 这条差异**没有正当理由,是漏的**(候补齐;补齐是行为改动,要单独一条测试)。
+ */
+export interface RequestFieldSpec {
+    field: string;
+    lanes: readonly RequestLane[];
+    /** 仅在 live 车道 stamp(mock/pty fixture 车道请求形状恒不变)。 */
+    live: boolean;
+    why: string;
+    gap?: true;
+}
+/**
+ * 逐字段对照表(B4 从三个构造器**逐行**读出来的,不是设计出来的)。
+ *
+ * 读法:`lanes` 只有一条 = 今天的漂移面;`gap:true` = 我判它是**漏**而不是**设计**。
+ * 🔴 `gap` 是【判断】不是【事实】——补齐任何一条都要按宪法三问单独立项,别当 B4 的收尾顺手做。
+ */
+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 interface TaskRequestInput {
+    /** 本 turn 的模型面输入(已含 slash-skill 正文 / 注入式 meta / 历史种子等端侧组装)。 */
+    objective: string;
+    /** 壳会话 id(单命名空间);print 非 live 车道传 mock 常量。 */
+    sessionId: string;
+    /** live 车道(= 壳的 `process.env.SEMA_LIVE_BASEURL` 判真)。false ⇒ 全部 live-gated 字段不 stamp。 */
+    live: boolean;
+    scenario?: string;
+    systemPrompt?: string;
+    reasoningEffort?: string;
+    model?: string;
+    images?: readonly unknown[];
+    skills?: unknown;
+    mcpServers?: unknown;
+    agents?: unknown;
+    clientContext?: Record<string, unknown>;
+    scratchpadDir?: string;
+    sandboxImageProfile?: string;
+    permissionMode?: string;
+    selfOrchestration?: boolean;
+    deferTools?: readonly string[];
+    retainBackgroundProcesses?: boolean;
+    promptProfile?: string;
+    enableFork?: boolean;
+    attachments?: Record<string, unknown>;
+    finalVerification?: boolean;
+    limits?: Record<string, unknown>;
+    interactiveTools?: false;
+    /** rewind 三件(E18);端自己判空。 */
+    rewind?: Record<string, unknown>;
+    /** `settings` 的四个来源(端各自解析;本模块只负责合并序与「全空则不 stamp」)。 */
+    settings?: {
+        resolved?: Record<string, unknown>;
+        webSearch?: Record<string, unknown>;
+        ultracode?: boolean;
+        hooks?: Record<string, unknown>;
+        outputStyle?: string;
+    };
+}
+/**
+ * 合一后的请求构造器 —— **按车道出两形**,字段集差异全部由 `REQUEST_FIELD_MATRIX` 决定。
+ *
+ * 🔴 行为纪律:本函数**不做任何统一**。print 没有 `ultracode` 就是没有(表里 `gap:true` 记着账),
+ * 补齐要另立项 —— 在这里顺手加一行,就是把「合一」偷换成「行为改动」。
+ */
+export declare function buildTaskRequest(input: TaskRequestInput, lane: RequestLane): TaskRequestLike;
+/** `applyLiveRequestDefaults` 的宿主输入(端解析好的值,同样零取值方式)。 */
+export interface LiveDefaultsInput {
+    cwd?: string;
+    additionalDirectories?: readonly string[];
+    agents?: unknown;
+    /** 引擎 caps 判真 ⇒ 走 `appendSystemPrompt` 一等位;否则借道 `settings.outputStyle`。 */
+    appendSystemPromptCapable: boolean;
+    /** 自我认知块的合并结果(端把既有值传进来,包只决定落哪个位)。 */
+    selfKnowledge?: {
+        forAppend: string;
+        forOutputStyle: string;
+    };
+    /** E12 opt-in(缺省关 —— 开着 = 每个 completed run 后端多跑一次 LLM pass)。 */
+    suggestNextPrompts?: boolean;
+    /** 三重门都过之后的 cheap 槽模型名;端负责 caps + 配置 + 目录同步校验。 */
+    compactionModel?: string;
+    /** 前一 turn 捕获的引擎 session id(连续性最高优先)。 */
+    capturedSessionId?: string;
+    /** 端的 mock session 常量(命中 ⇒ 删 sessionId 让引擎新铸)。 */
+    mockSessionIdConstant?: string;
+    /** 需要从 scenario 位剔除的 mock 关键字。 */
+    mockScenarioKeys?: ReadonlySet<string>;
+}
+/**
+ * live 兜底层(cli `liveClient.toLiveRequest` 的**包内半场**)—— 两条车道共用。
+ *
+ * 🔴 与 cli 的差分记账:cli 版在函数体里直接读 `process.cwd()` / `getAppStateStoreRef()` /
+ * `getLiveModelCatalog()` / `engineCapTrue()`。这些是**取值方式**,全部上移到 `LiveDefaultsInput`。
+ * 「调用方已带值就不覆盖」的语义(cli 每条都是 `if (out.X === undefined)`)在这里逐条保留。
+ */
+export declare function applyLiveRequestDefaults(req: TaskRequestLike, host: LiveDefaultsInput): TaskRequestLike;
+/** 出口约束:构造结果确实是一个 `TaskRequest`(型只在这里碰 SDK,运行时零依赖)。 */
+export type BuiltTaskRequest = TaskRequest;

package/dist/request/taskRequest.js

@@ -0,0 +1,176 @@
+/**
+ * 逐字段对照表(B4 从三个构造器**逐行**读出来的,不是设计出来的)。
+ *
+ * 读法:`lanes` 只有一条 = 今天的漂移面;`gap:true` = 我判它是**漏**而不是**设计**。
+ * 🔴 `gap` 是【判断】不是【事实】——补齐任何一条都要按宪法三问单独立项,别当 B4 的收尾顺手做。
+ */
+export const REQUEST_FIELD_MATRIX = [
+    // ── 两条车道都有 ────────────────────────────────────────────────────────────────────────────
+    { field: 'objective', lanes: ['interactive', 'print'], live: false, why: '本 turn 的真实输入,两条车道都必需' },
+    { field: 'sessionId', lanes: ['interactive', 'print'], live: false, why: '单命名空间(TP-A Step 2):壳 id 即引擎 session id;print 在非 live 下保留 mock 常量' },
+    { field: 'scenario', lanes: ['interactive', 'print'], live: false, why: 'TUI 走 selectScenario(objective) 嗅探,print 走 --scenario/SEMA_HEADLESS_SCENARIO 显式值' },
+    { field: 'sandboxImageProfile', lanes: ['interactive', 'print'], live: true, why: '[686]② 显式 profile;auto 档只在 TUI 有(一次性 advisory 进 objective)' },
+    { field: 'permissionMode', lanes: ['interactive', 'print'], live: true, why: 'TUI 读 AppState.toolPermissionContext(带 stampDefault 门),print 读 flag>env(headlessPermissionModeWire)' },
+    { field: 'selfOrchestration', lanes: ['interactive', 'print'], live: true, why: 'SEMA_SELF_ORCHESTRATION opt-in → core 挂 run_workflow' },
+    { field: 'deferTools', lanes: ['interactive', 'print'], live: true, why: '[1052]① Workflow 延迟披露;selfOrchestration 前置门' },
+    { field: 'retainBackgroundProcesses', lanes: ['interactive', 'print'], live: true, why: '缺省 ON(clay 2026-07-26 翻转);SEMA_RETAIN_BACKGROUND=0 逃生' },
+    { field: 'promptProfile', lanes: ['interactive', 'print'], live: true, why: 'core 1.328 呈现轴 A/B 口,缺省不 stamp = 引擎缺省 simple' },
+    { field: 'enableFork', lanes: ['interactive', 'print'], live: true, why: '显式布尔才 stamp([503]② fail-OPEN 教训:off 必须显式)' },
+    { field: 'attachments', lanes: ['interactive', 'print'], live: true, why: 'design/133 + G1 缺省开的 turn 边界 attachment' },
+    { field: 'skills', lanes: ['interactive', 'print'], live: true, why: '本地 .claude/skills 投影;两条车道都由 launchRepl 载入面注入' },
+    { field: 'mcpServers', lanes: ['interactive', 'print'], live: true, why: '本地 .mcp.json 投影;service 单用户门决定是否兑现' },
+    { field: 'settings.webSearch', lanes: ['interactive', 'print'], live: true, why: 'SEMA_WEBSEARCH_* / settings.json;per-request 配置赢过部署 env' },
+    { field: 'settings.hooks', lanes: ['interactive', 'print'], live: true, why: '[495]① 用户 settings 文件 hooks 逐字上 wire' },
+    // ── print 独有(§8-5 认定的**有理由**的差异)──────────────────────────────────────────────
+    { field: 'finalVerification', lanes: ['print'], live: true, why: 'P1-1 终验:无人值守车道才需要引擎自证;交互 REPL 由人当场看结果。#106 裁 B(让位+告知)后交互面默认关' },
+    { field: 'limits', lanes: ['print'], live: true, why: 'P2-3-b:`-p` 的预算护栏(--max-* flag 族),交互 REPL 由人随时 Esc' },
+    { field: 'interactiveTools', lanes: ['print'], live: true, why: '[909]B 件3:无人值守 stamp false,从 roster 源头灭掉 AskUserQuestion/plan 门。交互车道 stamp false 等于自废武功' },
+    // ── TUI 独有 ────────────────────────────────────────────────────────────────────────────────
+    { field: 'settings.ultracode', lanes: ['interactive'], live: true, why: 'design/111:sticky `/effort ultracode` 拨盘 + 当轮关键词嗅探,两个来源都只在交互面存在', gap: true },
+    { field: 'systemPrompt', lanes: ['interactive'], live: false, why: 'CC QueryParams.systemPrompt;print 腿的 params 没有这一位' },
+    { field: 'reasoningEffort', lanes: ['interactive'], live: false, why: '`/effort` 拨盘存在 AppState,print 无 AppState', gap: true },
+    { field: 'model', lanes: ['interactive'], live: false, why: '`/model` 中途换模型读 toolUseContext.options.mainLoopModel;print 的模型走 MODEL_ID/--model 另一条路', gap: true },
+    { field: 'images', lanes: ['interactive'], live: false, why: '贴图提交是交互动作,`-p` 的 stdin 没有图片块' },
+    { field: 'resumeAt/rewindFiles/rewindFilesTo', lanes: ['interactive'], live: false, why: 'E18 `/rewind` 是交互命令' },
+    { field: 'clientContext', lanes: ['interactive'], live: false, why: 'IANA 时区 + 可选邮箱 → core 本地化 `# Environment` 的 today;print 同样跑在用户机器上,缺席让引擎误标 (UTC)', gap: true },
+    { field: 'scratchpadDir', lanes: ['interactive'], live: true, why: '[816]③ per-session 暂存目录;print 也有 session,缺席让 `-p` 的工具写不进 exemptDir', gap: true },
+    { field: 'settings.<resolved>', lanes: ['interactive'], live: true, why: 'settings resolver 的 effective 快照(hooks/env/model + 已解析权限);print 只带 webSearch+hooks 两键', gap: true },
+];
+/** live 兜底层(`toLiveRequest`)追加的字段 —— 两条车道**都**经过,故不进上表。 */
+export const LIVE_DEFAULT_FIELDS = [
+    'cwd',
+    'additionalDirectories',
+    'forwardSubagentEvents',
+    'retainSubagentSessions',
+    'agents',
+    'appendSystemPrompt|settings.outputStyle',
+    'suggestNextPrompts',
+    'compactionModel',
+    'sessionId(三态解析)',
+];
+const laneHas = (field, lane) => REQUEST_FIELD_MATRIX.find(f => f.field === field)?.lanes.includes(lane) ?? false;
+/**
+ * 合一后的请求构造器 —— **按车道出两形**,字段集差异全部由 `REQUEST_FIELD_MATRIX` 决定。
+ *
+ * 🔴 行为纪律:本函数**不做任何统一**。print 没有 `ultracode` 就是没有(表里 `gap:true` 记着账),
+ * 补齐要另立项 —— 在这里顺手加一行,就是把「合一」偷换成「行为改动」。
+ */
+export function buildTaskRequest(input, lane) {
+    const live = input.live;
+    /** stamp 门:字段在本车道的表里 ∧(非 live-gated ∨ 本次是 live 车道)∧ 值非空。 */
+    const on = (field, value) => {
+        if (value === undefined || value === null)
+            return false;
+        const spec = REQUEST_FIELD_MATRIX.find(f => f.field === field);
+        if (spec === undefined)
+            return false;
+        if (!spec.lanes.includes(lane))
+            return false;
+        if (spec.live && !live)
+            return false;
+        return true;
+    };
+    // settings 四源合并(cli 原式:任一存在则 stamp,全缺则整个 `settings` 键都不出现)。
+    // ultracode 只在交互车道进表 ⇒ print 传了也不 stamp(表说了算,不是调用方说了算)。
+    const s = input.settings ?? {};
+    const settingsOut = {
+        ...(laneHas('settings.<resolved>', lane) && live ? (s.resolved ?? {}) : {}),
+        ...(on('settings.webSearch', s.webSearch) ? { webSearch: s.webSearch } : {}),
+        ...(on('settings.ultracode', s.ultracode) ? { ultracode: s.ultracode } : {}),
+        ...(on('settings.hooks', s.hooks) ? { hooks: s.hooks } : {}),
+        ...(s.outputStyle !== undefined ? { outputStyle: s.outputStyle } : {}),
+    };
+    const out = {
+        objective: input.objective,
+        sessionId: input.sessionId,
+        ...(on('scenario', input.scenario) ? { scenario: input.scenario } : {}),
+        ...(on('systemPrompt', input.systemPrompt) ? { systemPrompt: input.systemPrompt } : {}),
+        ...(on('reasoningEffort', input.reasoningEffort) ? { reasoningEffort: input.reasoningEffort } : {}),
+        ...(on('model', input.model) ? { model: input.model } : {}),
+        ...(on('images', input.images) && (input.images?.length ?? 0) > 0 ? { images: input.images } : {}),
+        ...(on('skills', input.skills) ? { skills: input.skills } : {}),
+        ...(on('mcpServers', input.mcpServers) ? { mcpServers: input.mcpServers } : {}),
+        ...(on('resumeAt/rewindFiles/rewindFilesTo', input.rewind) ? input.rewind : {}),
+        ...(on('permissionMode', input.permissionMode) ? { permissionMode: input.permissionMode } : {}),
+        ...(on('sandboxImageProfile', input.sandboxImageProfile)
+            ? { sandboxImageProfile: input.sandboxImageProfile }
+            : {}),
+        ...(on('selfOrchestration', input.selfOrchestration) ? { selfOrchestration: input.selfOrchestration } : {}),
+        ...(on('deferTools', input.deferTools) ? { deferTools: input.deferTools } : {}),
+        ...(on('retainBackgroundProcesses', input.retainBackgroundProcesses)
+            ? { retainBackgroundProcesses: input.retainBackgroundProcesses }
+            : {}),
+        ...(on('promptProfile', input.promptProfile) ? { promptProfile: input.promptProfile } : {}),
+        ...(on('enableFork', input.enableFork) ? { enableFork: input.enableFork } : {}),
+        ...(on('attachments', input.attachments) ? { attachments: input.attachments } : {}),
+        ...(on('clientContext', input.clientContext) ? { clientContext: input.clientContext } : {}),
+        ...(on('scratchpadDir', input.scratchpadDir) ? { scratchpadDir: input.scratchpadDir } : {}),
+        ...(on('finalVerification', input.finalVerification)
+            ? { finalVerification: input.finalVerification }
+            : {}),
+        ...(on('limits', input.limits) ? { limits: input.limits } : {}),
+        ...(on('interactiveTools', input.interactiveTools) && input.interactiveTools === false
+            ? { interactiveTools: false }
+            : {}),
+        ...(Object.keys(settingsOut).length > 0 ? { settings: settingsOut } : {}),
+    };
+    return out;
+}
+/**
+ * live 兜底层(cli `liveClient.toLiveRequest` 的**包内半场**)—— 两条车道共用。
+ *
+ * 🔴 与 cli 的差分记账:cli 版在函数体里直接读 `process.cwd()` / `getAppStateStoreRef()` /
+ * `getLiveModelCatalog()` / `engineCapTrue()`。这些是**取值方式**,全部上移到 `LiveDefaultsInput`。
+ * 「调用方已带值就不覆盖」的语义(cli 每条都是 `if (out.X === undefined)`)在这里逐条保留。
+ */
+export function applyLiveRequestDefaults(req, host) {
+    const out = { ...req };
+    if (out.cwd == null && host.cwd !== undefined)
+        out.cwd = host.cwd;
+    if (out.additionalDirectories === undefined && (host.additionalDirectories?.length ?? 0) > 0) {
+        out.additionalDirectories = [...(host.additionalDirectories ?? [])];
+    }
+    // C1 / design/144:交互与 headless 都常开 —— 不开则引擎不建 SubagentRetainLedger,
+    // 后台子代 SendMessage 唤醒直接 "session was not retained" 拒绝。老引擎按 body→spec 白名单
+    // 忽略未知字段,version-safe。
+    if (out.forwardSubagentEvents === undefined)
+        out.forwardSubagentEvents = true;
+    if (out.retainSubagentSessions === undefined)
+        out.retainSubagentSessions = true;
+    if (out.agents === undefined && host.agents !== undefined)
+        out.agents = host.agents;
+    if (typeof out.scenario === 'string' && host.mockScenarioKeys?.has(out.scenario)) {
+        delete out.scenario;
+    }
+    // 自我认知块双臂([1487]/[1478] R1 终形):caps 判真走一等位,否则借道 outputStyle。
+    // 两臂同一合并序(知识块恒前、调用方块恒后)——序由端在 selfKnowledge 里拼好,包只选位。
+    if (host.selfKnowledge !== undefined) {
+        if (host.appendSystemPromptCapable) {
+            out.appendSystemPrompt = host.selfKnowledge.forAppend;
+        }
+        else {
+            const settings = (out.settings ?? {});
+            out.settings = { ...settings, outputStyle: host.selfKnowledge.forOutputStyle };
+        }
+    }
+    // E12:与 verify/cascade 互斥(那两个返 result 非 streamed run ⇒ 400)。
+    if (out.suggestNextPrompts === undefined &&
+        out.verify === undefined &&
+        out.cascade === undefined &&
+        host.suggestNextPrompts === true) {
+        out.suggestNextPrompts = true;
+    }
+    if (out.compactionModel === undefined && host.compactionModel !== undefined) {
+        out.compactionModel = host.compactionModel;
+    }
+    // 单命名空间三态(cli 逐字):① 已捕获的引擎 session 赢(连续性 —— 引擎 session 绝不在
+    // 会话中途被换掉);③ 还带着 mock 常量 ⇒ 删掉让引擎新铸;② 其余保留(首 turn 壳 id 直传)。
+    if (host.capturedSessionId) {
+        out.sessionId = host.capturedSessionId;
+    }
+    else if (host.mockSessionIdConstant !== undefined &&
+        out.sessionId === host.mockSessionIdConstant) {
+        delete out.sessionId;
+    }
+    return out;
+}

package/dist/scratchpadWireCaps.d.ts

@@ -0,0 +1,16 @@
+export interface ScratchpadDirField {
+    scratchpadDir?: string;
+}
+/**
+ * Per-turn scratchpadDir stamp。gate off(tengu_scratch)⇒ 空对象(请求形状不变,mock parity)。
+ * 路径 per-session 稳定(sessionId 定 getScratchpadDir),重复调用幂等。
+ *
+ * 与 cli 的差分记账:
+ *  · `ensureScratchpadDir` 在壳里是 async(mkdir 0o700),这里 **两种返回都吞**(端可给同步实现);
+ *    建失败只影响引擎首写时自建(server 半场也建),**不阻 turn** —— 与 cli 逐字同语义。
+ *  · fs 口缺席(浏览器宿主)⇒ 返回空对象 = 不 stamp。additive 字段缺席对引擎无害,
+ *    但会计一次 `hostPortMisses().fs`,让「Node 宿主漏装」与「浏览器本就没有」在自检里可区分。
+ */
+export declare function scratchpadDirField(): ScratchpadDirField;
+/** 测试钩:复位 module 级建目录闩。 */
+export declare function _resetScratchpadEnsuredForTest(): void;

package/dist/scratchpadWireCaps.js

@@ -0,0 +1,65 @@
+/**
+ * ⇄ B4 批搬迁(2026-07-27,多端改造设计稿 §3 B4 第五件):cli `src/sema/scratchpadWireCaps.ts` 搬入。
+ * 拆缝 = 两条外向边换 host port:`utils/permissions/filesystem`(getScratchpadDir /
+ * isScratchpadEnabled / ensureScratchpadDir)→ `hostFs()`;`utils/debug.logForDebugging` → `hostLog()`。
+ * 本文件是 B2 判给 B4 的两件「宿主耦合 WireCaps」里的**小的那件**,同时充当 `FsPort` 的端到端证明。
+ */
+/**
+ * scratchpad 域的 wire 半场([816] 壳侧承诺③ / [819]④ / [820]③,2026-07-14)。
+ *
+ * 链路:core `TaskSpec.envFacts.scratchpadDir` 字段 + 提示词消费链(buildScratchpadSection)1.257.3
+ * 起全在;server 半场 = buildEnvFacts 填字段 + 建目录 + 塞进 createFsWriteGatePolicy 的 exemptDirs。
+ * 客户端把 getScratchpadDir()(CC 同型:`/tmp/claude-{uid}/{sanitized-cwd}/{sessionId}/scratchpad`)
+ * stamp 到 `TaskRequest.scratchpadDir` —— server 半场没到时字段发了引擎忽略 = 无害(additive 铁律);
+ * 到货后 server 以客户端带的路径为准(本机 TOC 引擎与壳同 fs,壳造的目录引擎直接可写),或自造(TOB 远端)。
+ *
+ * 🔴 [1840] 勘误:G3 `scratchpadDir` **不是死键** —— server 已把「死键」的说法收回改接单
+ * ([816]③/[820]③ additive 预挂)。别再按「没人读」把这条 stamp 删掉。
+ *
+ * 🔴 单实例纪律:本模块持 module 级 `ensured` 闩(整进程只 fire-and-forget 建一次目录)。
+ * 两份实例 = 建两次(幂等无害),但与本包其余台账同理,壳侧必须只解析到一份。
+ */
+import { hostFs, hostLog } from './host.js';
+let ensured = false;
+/**
+ * Per-turn scratchpadDir stamp。gate off(tengu_scratch)⇒ 空对象(请求形状不变,mock parity)。
+ * 路径 per-session 稳定(sessionId 定 getScratchpadDir),重复调用幂等。
+ *
+ * 与 cli 的差分记账:
+ *  · `ensureScratchpadDir` 在壳里是 async(mkdir 0o700),这里 **两种返回都吞**(端可给同步实现);
+ *    建失败只影响引擎首写时自建(server 半场也建),**不阻 turn** —— 与 cli 逐字同语义。
+ *  · fs 口缺席(浏览器宿主)⇒ 返回空对象 = 不 stamp。additive 字段缺席对引擎无害,
+ *    但会计一次 `hostPortMisses().fs`,让「Node 宿主漏装」与「浏览器本就没有」在自检里可区分。
+ */
+export function scratchpadDirField() {
+    try {
+        const fs = hostFs();
+        if (fs === undefined)
+            return {};
+        if (!fs.isScratchpadEnabled())
+            return {};
+        const dir = fs.getScratchpadDir();
+        if (!ensured) {
+            ensured = true;
+            try {
+                const r = fs.ensureScratchpadDir();
+                if (r !== undefined && typeof r.catch === 'function') {
+                    void r.catch((e) => {
+                        hostLog('debug', `scratchpadWireCaps: ensureScratchpadDir failed (non-fatal): ${String(e)}`);
+                    });
+                }
+            }
+            catch (e) {
+                hostLog('debug', `scratchpadWireCaps: ensureScratchpadDir threw (non-fatal): ${String(e)}`);
+            }
+        }
+        return dir !== undefined ? { scratchpadDir: dir } : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** 测试钩:复位 module 级建目录闩。 */
+export function _resetScratchpadEnsuredForTest() {
+    ensured = false;
+}