@sema-agent/client-core 0.6.0 → 0.8.0

package/dist/compensations.js

@@ -0,0 +1,138 @@
+/**
+ * compensations.ts — **补偿层登记表**(B6 引入,设计稿 §2 补偿表 T1–T60 的落码侧账本)。
+ *
+ * ## 为什么要有这张表
+ *
+ * 搬迁把「壳替引擎补的那 60 件事」分成三种命运:整条进包 / **拆两半**(判定归库、执行留宿主)/
+ * 留宿主。前两种里最危险的是**拆**:它天然是 [paired-mechanisms-must-share-premise] 的形状 ——
+ * 库这半以为「宿主会做另一半」,宿主那半以为「库已经处理了」,两半各自都对、组合零结果。
+ * 而且这种失效**不报错**,只是某个面悄悄空掉。
+ *
+ * ⇒ 与 `CHROME_ARMS` / `CLIENT_VERBS` 同一套纪律:**把义务做成数据**,让它可被断言,而不是
+ * 散在注释里。pure 门对本表跑三条:①id 唯一 ②每条 `split` 的 `chromeArm` 必须真在
+ * `CHROME_ARMS` 里 ③而且必须是 `required: true` —— 拆缝对面的义务若是「可选」,那这一刀就等于
+ * 在多端上静默丢行为。
+ *
+ * ## 它不是什么
+ *
+ * 🔴 **不是 `ADAPTER_DIVERGENCES`**。那张表登记的是「adapt() 与 cli `sdkMessagesToCcEvents`
+ * **行为不同**」的地方,差分守卫按它豁免比对。本表里的东西两侧**行为相同**(补偿是从 cli 原样
+ * 搬过来的),登记的是「这条补偿为什么存在、上游到货后什么时候能删」。把回落臂写进 DIVERGENCES
+ * 会让差分表撒谎 —— 那等于宣布两侧在这里不等价,而它们是等价的。
+ *
+ * ## 增长方式
+ *
+ * 每批只登记**这一批处置掉**的条目(B6 = P5 那八条)。不预先把 T1–T60 全填进来:填了但没落码的
+ * 行只会让表看起来完整而实际没有判别力([probe-must-prove-it-speaks])。
+ */
+import { CHROME_ARMS } from './seam.js';
+/**
+ * B6 P5 处置的八条(T32/T34/T47/T48/T49 整条进包 · T35/T36/T44 拆)。
+ *
+ * 🔴 事实核对(B6 余项批实测,不是照抄设计稿):这八条的落码**都发生在 B4**
+ * (`adapt.ts` A 层第 14 臂 `task_progress` 收官那一批),本批做的是**核实 + 登记 + 定案**,
+ * 不是重新搬一遍。核实方式 = 逐条在 `adapt.ts` 找到落码点并配上断言,见 pure 门 B6 段。
+ */
+export const MIGRATED_COMPENSATIONS = [
+    {
+        id: 'T32',
+        what: 'bindTaskCard —— 把引擎子代行绑到它的委派工具卡上(显式父 / FIFO 猜父 / 含糊即 unbound)',
+        disposition: 'in-library',
+        libraryHalf: 'adapt.ts bindTaskCard()',
+        chromeArm: null,
+        hostHalf: null,
+        // 见下方 P1-2 定案段:FIFO 那一臂**不删**,它是 tolerate-absent 的保护臂。
+        retireOn: 'P1-2 到货且达标线 ≥ server 1.290(typed parentToolCallId 在每条 tick 上恒在)后,' +
+            'FIFO 回落臂可删 —— 但只在**确认不再支持老引擎**时删,见 bindTaskCard 的 old-engine fallback 注释',
+    },
+    {
+        id: 'T34',
+        what: '面板行 live / inert / unbound 三态 —— 只 sweep 本 turn 真活绑的行',
+        disposition: 'in-library',
+        libraryHalf: 'adapt.ts liveBoundPanelTasks + settlePanelTasks(cardId===null) 防御 sweep',
+        chromeArm: null,
+        hostHalf: null,
+        retireOn: null, // 长期职责:只要子代不发终态 tick,这个三态就得有
+    },
+    {
+        id: 'T35',
+        what: '壳替引擎 fire SubagentStart/Stop hook —— 双进程下 vendor 的 AgentTool/runAgent 永不跑',
+        disposition: 'split',
+        libraryHalf: 'adapt.ts fireSubagentStart()(类型恒记 + 一生一次去重 + if-started 门)',
+        chromeArm: 'subagent_lifecycle',
+        hostHalf: '真执行用户 hook 进程(浏览器宿主根本不能执行 ⇒ 这一半必须留端)',
+        retireOn: 'G21 / P3a(引擎侧发正式的 subagent 生命周期事件)后,壳替 fire 整条退役',
+    },
+    {
+        id: 'T36',
+        what: '子代永不发终态 tick ⇒ 四处防御 sweep 兜住面板行,不让它们永远转圈',
+        disposition: 'in-library',
+        libraryHalf: 'adapt.ts settlePanelTasks 的四个调用点(tool_end 关卡 / result / turn 末 / abort)',
+        chromeArm: 'inline_task_stats',
+        hostHalf: null,
+        retireOn: 'W6(引擎为每条子代发终态 tick)后,防御 sweep 降为纯兜底',
+    },
+    {
+        id: 'T44',
+        what: '引擎 TaskCreate/TaskUpdate → ctrl+t 任务面板的磁盘 task store',
+        disposition: 'split',
+        libraryHalf: 'adapt.ts E 层 ② —— structured task/task-list 的判定 + 归一',
+        chromeArm: 'task_ledger_sync',
+        hostHalf: '按 toolUseId 幂等落盘(cli engineTaskListSync 的 fs 面;web 宿主落 BFF/本地存储)',
+        retireOn: null, // 长期职责:落盘位置本来就是端决策
+    },
+    {
+        id: 'T47',
+        what: 'workflow lane 三级判据门 —— workflow 子代的 tick 绝不进前台 subagent lane',
+        disposition: 'in-library',
+        libraryHalf: 'adapt.ts task_progress 臂的 workflowRunId / wa-id / workflow-card-parent 三级门',
+        chromeArm: null,
+        hostHalf: null,
+        retireOn: 'P1-2 到货后判据②③(形状嗅探 + 实例台账)可删,只留判据①(帧带 workflowRunId)',
+    },
+    {
+        id: 'T48',
+        what: '判据④ 回植 footerRowBelt —— fleet 双生行按尾段查台账,不再进 footer task 树',
+        disposition: 'split',
+        libraryHalf: 'workflow.ts recordWorkflowAgentTaskId()(写)+ isKnownWorkflowAgentTaskId()(读)',
+        chromeArm: null,
+        hostHalf: 'footer 行过滤 isFooterTaskRow/filterFooterTaskRows —— 含「丢弃所有无 parentId 顶层行」' +
+            '这条**端专属决策**(主 run 头部行由端自己合成渲染),留 TUI',
+        // 🔴 这条的写者与读者**都在库内**(设计稿 §2.4.1-B 已裁):做成 chrome 臂会让「宿主没接线 ⇒
+        //    Set 恒空 ⇒ 判据④ 静默失效」复活,所以 chromeArm 恒 null,拆的是**过滤策略**不是台账。
+        retireOn: 'P1-2 到货后 fleet 行自带 parentToolCallId ⇒ 双生行不需要按尾段查',
+    },
+    {
+        id: 'T49',
+        what: 'subagent alias 只能在 tick 上学 —— content 帧只带 parentToolCallId、没有 taskId',
+        disposition: 'in-library',
+        libraryHalf: 'adapt.ts task_progress 臂 registerSubagentAlias(explicitParent, taskId)',
+        chromeArm: null,
+        hostHalf: null,
+        retireOn: 'P1-2 到货后 content 帧自带 taskId ⇒ alias 学习整条可删',
+    },
+];
+/**
+ * 自检:每条 `split` 的宿主义务(若经 chrome 臂交付)必须真在 `CHROME_ARMS` 里,而且是
+ * `required: true`。返回违规条目;**恒应为空数组**。
+ *
+ * 🔴 判据锚在「决定结果的量」上:拆缝对面若挂在一个 `required:false` 的臂上,宿主可以合法不实现,
+ * 于是这一刀就是「库不做了、端也不做」——正是配对机制两半各自都对、组合零结果的那个形状。
+ */
+export function compensationSplitViolations() {
+    const byKind = new Map(CHROME_ARMS.map(a => [a.kind, a]));
+    const bad = [];
+    for (const c of MIGRATED_COMPENSATIONS) {
+        if (c.chromeArm === null)
+            continue;
+        const arm = byKind.get(c.chromeArm);
+        if (arm === undefined) {
+            bad.push(`${c.id}: chrome 臂 "${c.chromeArm}" 不在 CHROME_ARMS 里(拆缝对面没有交付口)`);
+            continue;
+        }
+        if (!arm.required) {
+            bad.push(`${c.id}: chrome 臂 "${c.chromeArm}" 是 required:false —— 拆缝对面的义务不许是可选的`);
+        }
+    }
+    return bad;
+}

package/dist/detachWire.d.ts

@@ -0,0 +1,141 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/detachWire.ts` **拆**搬 —— 判定半场 +
+ *    cancel-arm 台账进包,**信号路径的裸 fetch 发射留宿主**(设计稿 §3 表 `S/detachWire.ts` 那条
+ *    脚注:`:221` 裸 cancel = TUI 留,宪法例外 census C1-4)。
+ *
+ * 🔴 **拆缝画在哪、为什么**:`fireBestEffortDetachCancel` 是**信号处理器**里同步 DISPATCH 的
+ *    fire-and-forget —— 它成立的前提是「进程正在被 SIGINT/SIGTERM 拆掉,不能 await、不能构造重对象」。
+ *    这套前提是 **Node 进程模型**的,浏览器/桌面渲染进程根本没有信号;而且它有意**绕开 SDK verb**
+ *    (`AgentClient.runs.cancel` 是 await 型,包一层 void+catch 反而把纪律面弄模糊)——那是壳的
+ *    宪法例外,不该被搬成「库里有一处裸 fetch」。⇒ 发射留宿主,库出**台账 + 读口**。
+ *
+ * 🔴 **模块级状态与读写口同包**([multiclient-migration-batch-discipline]):`cancelArm` 一份,
+ *    写口 `armDetachCancel`(seamQueryEngine.ask 在头真拼上请求时调)、读口 `isDetachArmed`
+ *    (`detachDurableOffHint` 的第一道门)/ `detachedTaskId`(分诊文案)/ `detachCancelArm`
+ *    (**宿主发射腿**唯一取件口)全在本文件。壳侧 shim 的 `fireBestEffortDetachCancel` 从
+ *    `detachCancelArm()` 取件 ⇒ 仍然只有一份台账;壳若自己再存一份 = 头发了但 hint 判不出、
+ *    Ctrl+C 取消不掉(两个静默失效各一半)。
+ *
+ * 🔴 env 读取走 `hostEnv()`(本包零 `process`,portability 门盯着);Node 下同一对象 ⇒ 壳侧
+ *    「不传 env 参数」的调用点行为一字节不变。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * detachWire — headless `-p` detach-on-disconnect wire (重连腿 M1 壳半场, 2026-07-15,
+ * design/HEADLESS-RECONNECT-DESIGN.md §6 M1; mirrors finalVerifyWire/limitsWire in shape).
+ *
+ * WHY: the `/v1/tasks/stream` lane ABORTS the run on client disconnect by design (anti token-burn —
+ * this is also the interactive cancel mechanism). server ≥1.196 accepts an opt-in escape hatch: the
+ * `x-detach-on-disconnect: true` REQUEST HEADER makes a disconnect DETACH the run instead — it keeps
+ * running to its terminal and lands in the durable run ledger (`GET /v1/runs/:id`; a deployment with
+ * no durable ledger 400s fail-loud — the shell's self-spawned engine always sets DB_BACKEND=local,
+ * so the ledger is always there on that lane). M1 = header + cancel fallback ONLY; reconnect/resume
+ * (R1 runs.events lane-switch / R2 idempotent re-POST) is M2/M3 — NOT here.
+ *
+ * 铁律 1 (design §2.1): the header is stamped ONLY on the headless `-p` lane (seamQueryEngine.ask),
+ * live-gated on SEMA_LIVE_BASEURL exactly like finalVerifyWire — the interactive REPL lane
+ * (seamQuery.ts) never imports this module, so Esc/interrupt keeps its disconnect==cancel semantics
+ * verbatim, and the mock/pty lanes never see the header (offline projection byte-identical).
+ *
+ * 铁律 2 (design §2.2): once detach is on, a USER abort must carry an explicit best-effort cancel —
+ * a detached run would otherwise burn tokens to completion in the background after Ctrl+C. The
+ * cancel-arm half of this module (armDetachCancel / the host's fireBestEffortDetachCancel) is
+ * consumed by the `-p` SIGINT handler and the SIGTERM/SIGHUP tail-frame handler (cli/print.ts):
+ * fire-and-forget `POST /v1/runs/:id/cancel` (the SDK RunsResource.cancel verb, runs.js — verified:
+ * no body), never awaited on the signal path. taskId not yet captured (pre X-Task-Id window) ⇒
+ * ACCEPTED uncancellable window — detach's inherent cost, no waiting introduced (design §2.2 记账).
+ *
+ * PRECEDENCE (off wins; otherwise DEFAULT ON):
+ *  a) `SEMA_HEADLESS_DETACH` env = 'false'/'0' (settings env lane, fail-soft — any other value
+ *     including typos stays default-on, finalVerifyWire discipline)          → off.
+ *  b) VERSION GATE: SEMA_ENGINE_URL in play (user-supplied external engine) and `/health` CONFIRMS
+ *     version <1.196.0 (or no version field = pre-1.96)                      → off + SEMA_DEBUG log.
+ *     Unlike limitsWire (warn-and-send: an old server drops an unknown BODY field server-side), here
+ *     we GATE: an old server silently ignores the unknown HEADER, so a disconnect still kills the
+ *     run — sending it would only manufacture a false "detached" belief downstream (判死文案 would
+ *     lie). Probe unreachable / unparsable response ⇒ fail-soft SEND (can't confirm staleness; the
+ *     stream POST itself fails loudly if the engine is truly down).
+ *  c) self-spawn lane (no SEMA_ENGINE_URL): release-pinned ≥1.197.0 — trusted, no probe, header on.
+ */
+import { type EnvLike } from './hostEnv.js';
+/** The server ≥1.196 opt-in header: disconnect ⇒ detach (run continues to durable terminal). */
+export declare const DETACH_HEADER = "x-detach-on-disconnect";
+/** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。'false'/'0' = off。 */
+export declare const HEADLESS_DETACH_ENV = "SEMA_HEADLESS_DETACH";
+/**
+ * First server version that honors the detach header — 1.196.0, the SAME floor as the limits wire
+ * (both landed in the [857] batch), so the version predicate is limitsWire.versionSupportsLimits
+ * re-exported under the detach name (one comparator, two wires — 抽共用 per design).
+ */
+export declare const DETACH_WIRE_MIN_ENGINE: readonly [number, number, number];
+/** True when the engine version string satisfies the detach-wire minimum (≥1.196.0). Unparsable ⇒ false. */
+export declare const versionSupportsDetach: (v: string | undefined) => boolean;
+/**
+ * The settings-lane off-switch: `SEMA_HEADLESS_DETACH` = 'false' or '0' (case-insensitive) disables
+ * the header. Any other value (empty/'true'/typo) = default ON — fail-soft, a settings typo never
+ * flips the lane silently to the strict-alignment (disconnect-kills-run) mode (finalVerifyWire 纪律).
+ */
+export declare function headlessDetachDisabledByEnv(env?: EnvLike): boolean;
+/**
+ * Version-gate probe: GET `${baseUrl}/health`, read `version`. Returns FALSE only when the engine is
+ * CONFIRMED older than 1.196.0 (parsable old version, or a healthy response with no version field =
+ * pre-1.96). Unreachable / timeout / non-2xx / unparsable JSON ⇒ TRUE (fail-soft: can't confirm
+ * staleness — the header is harmless on the wire, and the stream POST fails loudly on a dead engine).
+ * Same probe shape as limitsWire.engineLimitsSupportWarning (1.5s budget, never throws).
+ */
+export declare function engineSupportsDetach(baseUrl: string, opts?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<boolean>;
+export type DetachResolution = {
+    on: true;
+    reason: 'default-on';
+} | {
+    on: false;
+    reason: 'env-off' | 'old-engine';
+};
+/**
+ * Resolve the detach header for a headless `-p` submit. DEFAULT ON; `SEMA_HEADLESS_DETACH`=false|0
+ * ⇒ off (env-off); SEMA_ENGINE_URL external engine confirmed <1.196.0 ⇒ off (old-engine — the caller
+ * SEMA_DEBUG-logs it). Self-spawn lane (no SEMA_ENGINE_URL) never probes (pin ≥1.197 trusted).
+ * The caller MUST live-gate on SEMA_LIVE_BASEURL (finalVerifyWire 同款) — mock/pty lanes never
+ * reach this resolver, so they never see the header.
+ */
+export declare function resolveHeadlessDetach(baseUrl: string, env?: EnvLike, opts?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<DetachResolution>;
+/** server 400 body 判别锚(server.ts sendJson 原文:"x-detach-on-disconnect requires a durable run
+ *  (a run store + sessionId) — without one the detached result would be unqueryable")。 */
+export declare const DETACH_DURABLE_OFF_400_ANCHOR = "x-detach-on-disconnect requires a durable run";
+/**
+ * detach 头引发的 durable-off 400 → 人话提示行;其它错误(非 400 / 非该 body / 头没发过)恒 null
+ * (绝不误伤其它 400 —— sandboxImageProfile 400 等各有自己的 hint)。判别三重:头确已发出
+ * (isDetachArmed —— armDetachCancel 只在头拼上请求时调)+ SDK APIError.status===400 + message 含
+ * server 原文锚(sdk errors.js toApiError: msg = body.error 原文)。
+ */
+export declare function detachDurableOffHint(err: unknown): string | null;
+export interface DetachCancelArm {
+    baseUrl: string;
+    /** 真 token 串,或 loopback 显式免鉴权(#118:cancel 兜底同样零 Authorization 头,绝不伪造 'anon')。 */
+    authToken: string | {
+        mode: 'loopback-unauthed';
+    };
+    principal: string;
+    /** Reads the durable taskId early-captured off the X-Task-Id response header; null before capture. */
+    getTaskId: () => string | null;
+}
+/** Arm the signal-path cancel fallback (called by ask when the detach header is actually sent). */
+export declare function armDetachCancel(arm: DetachCancelArm): void;
+/** Whether this process sent the detach header on its `-p` stream (the 判死文案 upgrade gate). */
+export declare function isDetachArmed(): boolean;
+/** The detached run's durable taskId, when already captured (X-Task-Id) — for the triage copy. */
+export declare function detachedTaskId(): string | null;
+/**
+ * 🔴 **宿主发射腿的唯一取件口**(拆缝的库这一侧)。宿主的 `fireBestEffortDetachCancel` 必须从这里
+ * 取 arm,**不许自己再存一份** —— 台账两份 = 头发了但 hint 判不出 / Ctrl+C 取消不掉。
+ * null = 没 arm 过(detach 关 / 版本门挡下 / mock 车道)⇒ 宿主零动作、零行为变化。
+ */
+export declare function detachCancelArm(): DetachCancelArm | null;
+/** Test-only reset (module state is process-lifetime; `-p` is a one-shot). */
+export declare function _resetDetachWireForTest(): void;

package/dist/detachWire.js

@@ -0,0 +1,182 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/detachWire.ts` **拆**搬 —— 判定半场 +
+ *    cancel-arm 台账进包,**信号路径的裸 fetch 发射留宿主**(设计稿 §3 表 `S/detachWire.ts` 那条
+ *    脚注:`:221` 裸 cancel = TUI 留,宪法例外 census C1-4)。
+ *
+ * 🔴 **拆缝画在哪、为什么**:`fireBestEffortDetachCancel` 是**信号处理器**里同步 DISPATCH 的
+ *    fire-and-forget —— 它成立的前提是「进程正在被 SIGINT/SIGTERM 拆掉,不能 await、不能构造重对象」。
+ *    这套前提是 **Node 进程模型**的,浏览器/桌面渲染进程根本没有信号;而且它有意**绕开 SDK verb**
+ *    (`AgentClient.runs.cancel` 是 await 型,包一层 void+catch 反而把纪律面弄模糊)——那是壳的
+ *    宪法例外,不该被搬成「库里有一处裸 fetch」。⇒ 发射留宿主,库出**台账 + 读口**。
+ *
+ * 🔴 **模块级状态与读写口同包**([multiclient-migration-batch-discipline]):`cancelArm` 一份,
+ *    写口 `armDetachCancel`(seamQueryEngine.ask 在头真拼上请求时调)、读口 `isDetachArmed`
+ *    (`detachDurableOffHint` 的第一道门)/ `detachedTaskId`(分诊文案)/ `detachCancelArm`
+ *    (**宿主发射腿**唯一取件口)全在本文件。壳侧 shim 的 `fireBestEffortDetachCancel` 从
+ *    `detachCancelArm()` 取件 ⇒ 仍然只有一份台账;壳若自己再存一份 = 头发了但 hint 判不出、
+ *    Ctrl+C 取消不掉(两个静默失效各一半)。
+ *
+ * 🔴 env 读取走 `hostEnv()`(本包零 `process`,portability 门盯着);Node 下同一对象 ⇒ 壳侧
+ *    「不传 env 参数」的调用点行为一字节不变。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * detachWire — headless `-p` detach-on-disconnect wire (重连腿 M1 壳半场, 2026-07-15,
+ * design/HEADLESS-RECONNECT-DESIGN.md §6 M1; mirrors finalVerifyWire/limitsWire in shape).
+ *
+ * WHY: the `/v1/tasks/stream` lane ABORTS the run on client disconnect by design (anti token-burn —
+ * this is also the interactive cancel mechanism). server ≥1.196 accepts an opt-in escape hatch: the
+ * `x-detach-on-disconnect: true` REQUEST HEADER makes a disconnect DETACH the run instead — it keeps
+ * running to its terminal and lands in the durable run ledger (`GET /v1/runs/:id`; a deployment with
+ * no durable ledger 400s fail-loud — the shell's self-spawned engine always sets DB_BACKEND=local,
+ * so the ledger is always there on that lane). M1 = header + cancel fallback ONLY; reconnect/resume
+ * (R1 runs.events lane-switch / R2 idempotent re-POST) is M2/M3 — NOT here.
+ *
+ * 铁律 1 (design §2.1): the header is stamped ONLY on the headless `-p` lane (seamQueryEngine.ask),
+ * live-gated on SEMA_LIVE_BASEURL exactly like finalVerifyWire — the interactive REPL lane
+ * (seamQuery.ts) never imports this module, so Esc/interrupt keeps its disconnect==cancel semantics
+ * verbatim, and the mock/pty lanes never see the header (offline projection byte-identical).
+ *
+ * 铁律 2 (design §2.2): once detach is on, a USER abort must carry an explicit best-effort cancel —
+ * a detached run would otherwise burn tokens to completion in the background after Ctrl+C. The
+ * cancel-arm half of this module (armDetachCancel / the host's fireBestEffortDetachCancel) is
+ * consumed by the `-p` SIGINT handler and the SIGTERM/SIGHUP tail-frame handler (cli/print.ts):
+ * fire-and-forget `POST /v1/runs/:id/cancel` (the SDK RunsResource.cancel verb, runs.js — verified:
+ * no body), never awaited on the signal path. taskId not yet captured (pre X-Task-Id window) ⇒
+ * ACCEPTED uncancellable window — detach's inherent cost, no waiting introduced (design §2.2 记账).
+ *
+ * PRECEDENCE (off wins; otherwise DEFAULT ON):
+ *  a) `SEMA_HEADLESS_DETACH` env = 'false'/'0' (settings env lane, fail-soft — any other value
+ *     including typos stays default-on, finalVerifyWire discipline)          → off.
+ *  b) VERSION GATE: SEMA_ENGINE_URL in play (user-supplied external engine) and `/health` CONFIRMS
+ *     version <1.196.0 (or no version field = pre-1.96)                      → off + SEMA_DEBUG log.
+ *     Unlike limitsWire (warn-and-send: an old server drops an unknown BODY field server-side), here
+ *     we GATE: an old server silently ignores the unknown HEADER, so a disconnect still kills the
+ *     run — sending it would only manufacture a false "detached" belief downstream (判死文案 would
+ *     lie). Probe unreachable / unparsable response ⇒ fail-soft SEND (can't confirm staleness; the
+ *     stream POST itself fails loudly if the engine is truly down).
+ *  c) self-spawn lane (no SEMA_ENGINE_URL): release-pinned ≥1.197.0 — trusted, no probe, header on.
+ */
+import { hostEnv } from './hostEnv.js';
+import { versionSupportsLimits } from './limitsWire.js';
+/** The server ≥1.196 opt-in header: disconnect ⇒ detach (run continues to durable terminal). */
+export const DETACH_HEADER = 'x-detach-on-disconnect';
+/** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。'false'/'0' = off。 */
+export const HEADLESS_DETACH_ENV = 'SEMA_HEADLESS_DETACH';
+/**
+ * First server version that honors the detach header — 1.196.0, the SAME floor as the limits wire
+ * (both landed in the [857] batch), so the version predicate is limitsWire.versionSupportsLimits
+ * re-exported under the detach name (one comparator, two wires — 抽共用 per design).
+ */
+export const DETACH_WIRE_MIN_ENGINE = [1, 196, 0];
+/** True when the engine version string satisfies the detach-wire minimum (≥1.196.0). Unparsable ⇒ false. */
+export const versionSupportsDetach = versionSupportsLimits;
+/**
+ * The settings-lane off-switch: `SEMA_HEADLESS_DETACH` = 'false' or '0' (case-insensitive) disables
+ * the header. Any other value (empty/'true'/typo) = default ON — fail-soft, a settings typo never
+ * flips the lane silently to the strict-alignment (disconnect-kills-run) mode (finalVerifyWire 纪律).
+ */
+export function headlessDetachDisabledByEnv(env = hostEnv()) {
+    const v = env[HEADLESS_DETACH_ENV]?.trim().toLowerCase();
+    return v === 'false' || v === '0';
+}
+/**
+ * Version-gate probe: GET `${baseUrl}/health`, read `version`. Returns FALSE only when the engine is
+ * CONFIRMED older than 1.196.0 (parsable old version, or a healthy response with no version field =
+ * pre-1.96). Unreachable / timeout / non-2xx / unparsable JSON ⇒ TRUE (fail-soft: can't confirm
+ * staleness — the header is harmless on the wire, and the stream POST fails loudly on a dead engine).
+ * Same probe shape as limitsWire.engineLimitsSupportWarning (1.5s budget, never throws).
+ */
+export async function engineSupportsDetach(baseUrl, opts) {
+    const fetchImpl = opts?.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 1500);
+    try {
+        const res = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}/health`, {
+            method: 'GET',
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return true; // engine answered oddly — can't confirm staleness, fail-soft send
+        const body = (await res.json());
+        const version = typeof body?.version === 'string' ? body.version : undefined;
+        // No version field = pre-1.96 engine — definitely older than 1.196.0: gate the header.
+        return versionSupportsDetach(version);
+    }
+    catch {
+        return true; // unreachable/timeout — cannot confirm staleness, fail-soft send
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Resolve the detach header for a headless `-p` submit. DEFAULT ON; `SEMA_HEADLESS_DETACH`=false|0
+ * ⇒ off (env-off); SEMA_ENGINE_URL external engine confirmed <1.196.0 ⇒ off (old-engine — the caller
+ * SEMA_DEBUG-logs it). Self-spawn lane (no SEMA_ENGINE_URL) never probes (pin ≥1.197 trusted).
+ * The caller MUST live-gate on SEMA_LIVE_BASEURL (finalVerifyWire 同款) — mock/pty lanes never
+ * reach this resolver, so they never see the header.
+ */
+export async function resolveHeadlessDetach(baseUrl, env = hostEnv(), opts) {
+    if (headlessDetachDisabledByEnv(env))
+        return { on: false, reason: 'env-off' };
+    if (env.SEMA_ENGINE_URL) {
+        // user-supplied external engine — the only lane where an old server is possible
+        const ok = await engineSupportsDetach(baseUrl, opts);
+        if (!ok)
+            return { on: false, reason: 'old-engine' };
+    }
+    return { on: true, reason: 'default-on' };
+}
+// ── durable-off 400 的人话分诊([862]④,1.0.5 小件5) ─────────────────────────────────────────────────
+//
+// server ≥1.196 对带 detach 头但无 durable 账本(无 runStore / 无 sessionId)的 submit 判 400 fail-loud
+// (server http/server.ts [854]①b:静默忽略 = 断连仍杀 run,与 caller 声明语义相反;detach 成功了结果
+// 也无处可查)。壳自 spawn 引擎恒 DB_BACKEND=local 永不命中;命中面 = SEMA_ENGINE_URL 外接引擎显式关
+// durable。裸 `sema: API Error: 400 · x-detach-on-disconnect requires a durable run …` 是 server 视角
+// 的契约话,用户不知道下一步 —— 追加一行人话(supplement, never mask:API Error 行字面保留)。
+/** server 400 body 判别锚(server.ts sendJson 原文:"x-detach-on-disconnect requires a durable run
+ *  (a run store + sessionId) — without one the detached result would be unqueryable")。 */
+export const DETACH_DURABLE_OFF_400_ANCHOR = 'x-detach-on-disconnect requires a durable run';
+/**
+ * detach 头引发的 durable-off 400 → 人话提示行;其它错误(非 400 / 非该 body / 头没发过)恒 null
+ * (绝不误伤其它 400 —— sandboxImageProfile 400 等各有自己的 hint)。判别三重:头确已发出
+ * (isDetachArmed —— armDetachCancel 只在头拼上请求时调)+ SDK APIError.status===400 + message 含
+ * server 原文锚(sdk errors.js toApiError: msg = body.error 原文)。
+ */
+export function detachDurableOffHint(err) {
+    if (!isDetachArmed())
+        return null;
+    const e = err;
+    if (e?.status !== 400)
+        return null;
+    const msg = typeof e?.message === 'string' ? e.message : '';
+    if (!msg.includes(DETACH_DURABLE_OFF_400_ANCHOR))
+        return null;
+    return 'engine has durable runs disabled — detach-on-disconnect unavailable; interrupted turns will abort (SEMA_HEADLESS_DETACH=false to silence)';
+}
+let cancelArm = null;
+/** Arm the signal-path cancel fallback (called by ask when the detach header is actually sent). */
+export function armDetachCancel(arm) {
+    cancelArm = arm;
+}
+/** Whether this process sent the detach header on its `-p` stream (the 判死文案 upgrade gate). */
+export function isDetachArmed() {
+    return cancelArm !== null;
+}
+/** The detached run's durable taskId, when already captured (X-Task-Id) — for the triage copy. */
+export function detachedTaskId() {
+    return cancelArm?.getTaskId() ?? null;
+}
+/**
+ * 🔴 **宿主发射腿的唯一取件口**(拆缝的库这一侧)。宿主的 `fireBestEffortDetachCancel` 必须从这里
+ * 取 arm,**不许自己再存一份** —— 台账两份 = 头发了但 hint 判不出 / Ctrl+C 取消不掉。
+ * null = 没 arm 过(detach 关 / 版本门挡下 / mock 车道)⇒ 宿主零动作、零行为变化。
+ */
+export function detachCancelArm() {
+    return cancelArm;
+}
+/** Test-only reset (module state is process-lifetime; `-p` is a one-shot). */
+export function _resetDetachWireForTest() {
+    cancelArm = null;
+}

package/dist/diff/patch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * src/diff/patch.ts — T20:**diff hunks 在客户端算**(core 已裁定归客户端,零上游依赖)。
+ *
+ * 为什么必须进本包:core 明确「引擎发 originalFile(客户端永远重建不出来的那一半),hunks 由客户端
+ * 算」—— 那么每个端(TUI/web/桌面)各算一遍就是三份实现三种 hunk;进包之后是**一份**。
+ * 搬自 cli `src/utils/diff.ts:81 getPatchFromContents` + `src/utils/file.ts:137
+ * convertLeadingTabsToSpaces`,**逐字**(含 & / $ 转义 token 与 CONTEXT_LINES/TIMEOUT 常量),
+ * 只丢掉宿主侧的 analytics / LOC 计数副作用(那两条在 cli 里也不在本函数内)。
+ *
+ * 🔴 唯一的运行时依赖 `diff`(jsdiff 9,零传递依赖、纯 JS、浏览器可用)—— 本包第一个 runtime dep。
+ * 判据:它不是「顺手拉进来的 hub」,而是 T20 这条能力**本身**;不引它就只能把能力退回各端。
+ * portability 门的 ALLOWED_PACKAGES 因此显式登记 `diff` 一条(登记 = 可审计,不是放行一切)。
+ */
+import { type StructuredPatchHunk } from 'diff';
+export declare const CONTEXT_LINES = 3;
+export declare const DIFF_TIMEOUT_MS = 5000;
+/**
+ * 渲染前把**行首** tab 折成两空格 —— CC 自己的 Edit 卡在 structuredPatch 之前做同一件事
+ * (FileEditTool/utils.ts),不做的话 tab 缩进文件两边算出来的 hunk 对不上。
+ */
+export declare function convertLeadingTabsToSpaces(content: string): string;
+export declare function getPatchFromContents({ filePath, oldContent, newContent, ignoreWhitespace, singleHunk, }: {
+    filePath: string;
+    oldContent: string;
+    newContent: string;
+    ignoreWhitespace?: boolean;
+    singleHunk?: boolean;
+}): StructuredPatchHunk[];
+export type { StructuredPatchHunk };

package/dist/diff/patch.js

@@ -0,0 +1,45 @@
+/**
+ * src/diff/patch.ts — T20:**diff hunks 在客户端算**(core 已裁定归客户端,零上游依赖)。
+ *
+ * 为什么必须进本包:core 明确「引擎发 originalFile(客户端永远重建不出来的那一半),hunks 由客户端
+ * 算」—— 那么每个端(TUI/web/桌面)各算一遍就是三份实现三种 hunk;进包之后是**一份**。
+ * 搬自 cli `src/utils/diff.ts:81 getPatchFromContents` + `src/utils/file.ts:137
+ * convertLeadingTabsToSpaces`,**逐字**(含 & / $ 转义 token 与 CONTEXT_LINES/TIMEOUT 常量),
+ * 只丢掉宿主侧的 analytics / LOC 计数副作用(那两条在 cli 里也不在本函数内)。
+ *
+ * 🔴 唯一的运行时依赖 `diff`(jsdiff 9,零传递依赖、纯 JS、浏览器可用)—— 本包第一个 runtime dep。
+ * 判据:它不是「顺手拉进来的 hub」,而是 T20 这条能力**本身**;不引它就只能把能力退回各端。
+ * portability 门的 ALLOWED_PACKAGES 因此显式登记 `diff` 一条(登记 = 可审计,不是放行一切)。
+ */
+import { structuredPatch } from 'diff';
+export const CONTEXT_LINES = 3;
+export const DIFF_TIMEOUT_MS = 5_000;
+// cli 原注:`&` 会让 diff 库犯迷糊,先换成 token、算完再换回来。`$` 同理(替换模式转义位)。
+const AMPERSAND_TOKEN = '<<:AMPERSAND_TOKEN:>>';
+const DOLLAR_TOKEN = '<<:DOLLAR_TOKEN:>>';
+function escapeForDiff(s) {
+    return s.replaceAll('&', AMPERSAND_TOKEN).replaceAll('$', DOLLAR_TOKEN);
+}
+function unescapeFromDiff(s) {
+    return s.replaceAll(AMPERSAND_TOKEN, '&').replaceAll(DOLLAR_TOKEN, '$');
+}
+/**
+ * 渲染前把**行首** tab 折成两空格 —— CC 自己的 Edit 卡在 structuredPatch 之前做同一件事
+ * (FileEditTool/utils.ts),不做的话 tab 缩进文件两边算出来的 hunk 对不上。
+ */
+export function convertLeadingTabsToSpaces(content) {
+    // 无 tab 的常见情形直接短路(/gm 正则会逐行扫)。
+    if (!content.includes('\t'))
+        return content;
+    return content.replace(/^\t+/gm, _ => '  '.repeat(_.length));
+}
+export function getPatchFromContents({ filePath, oldContent, newContent, ignoreWhitespace = false, singleHunk = false, }) {
+    const result = structuredPatch(filePath, filePath, escapeForDiff(oldContent), escapeForDiff(newContent), undefined, undefined, {
+        ignoreWhitespace,
+        context: singleHunk ? 100_000 : CONTEXT_LINES,
+        timeout: DIFF_TIMEOUT_MS,
+    });
+    if (!result)
+        return [];
+    return result.hunks.map(_ => ({ ..._, lines: _.lines.map(unescapeFromDiff) }));
+}

package/dist/engineSessionParam.d.ts

@@ -0,0 +1,11 @@
+/** 当前会话的 session 参数值;undefined = 端未装 SessionPort,或端自己也还没有值。 */
+export declare function engineSessionParam(): string | undefined;
+/** spread 便捷形:`{ ...engineSessionParamSpread() }` → `{ session: '<sid>' }` 或 `{}`。 */
+export declare function engineSessionParamSpread(): {
+    session?: string;
+};
+/**
+ * 当前活跃引擎 run 的 id(壳 = `engineToolDetach.getActiveEngineTaskId()`)。
+ * 库内多处 durable 动词要「宿主 run」做寻址第一跳,统一从这里取,不各自 import 端模块。
+ */
+export declare function activeEngineRunId(): string | undefined;

package/dist/engineSessionParam.js

@@ -0,0 +1,41 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,多端改造设计稿 §3 B6 + B4「四残件」之 session-id port):
+ *    cli `src/sema/engineSessionParam.ts` 搬入,唯一改动 = **取值源换 port**。
+ *
+ * engineSessionParam — durable run 面 `?session=` 参数的统一派生([1501]§三,server 1.246 起
+ * legacy 八面软拍纪律:带了且不匹配=404,没带=warn-once 放行,二拍将把「没带」也 404;新面
+ * A/B(taskOutput/taskStop)与 subagentOutput 则出生即强制)。
+ *
+ * 取值语义 = run 绑定的会话(本端所有 durable 动词的目标 run 都是本会话自有 run)。
+ *
+ * 🔴 **搬迁的唯一差分**:壳里这里是「`getLiveSessionId()`(引擎捕获值)优先,退
+ * `bootstrap/state.getSessionId()`(壳 boot-time id),后者靠动态 import 落地」——**两级优先与
+ * 那个动态 import 都是宿主生命周期资产**,整体上移到 `SessionPort.currentSessionId()`
+ * (壳侧 shim 里原样保留那两级 + 动态 import,行为一字节不变)。库这边只剩「取一个值 + 空串归一」。
+ *
+ * 🔴 [1501] 空串陷阱:`?session=`(空值)按「带了且不匹配」处理=404 —— 本 helper 恒不返回
+ * 空串:要么真值要么 undefined(调用方 spread 姿势 `...(s ? { session: s } : {})`)。
+ *
+ * 🔴 端漏装 SessionPort 的后果**不是**「少个查询参数」:session-bound run 的 taskOutput /
+ * taskStop / subagentOutput 三面一律 404 fail-closed ⇒ 子代读面整条静默哑掉。所以
+ * `hostSession()` 计 miss,宿主自检 `hostPortMisses()` 恒应为空。
+ */
+import { hostSession } from './host.js';
+/** 当前会话的 session 参数值;undefined = 端未装 SessionPort,或端自己也还没有值。 */
+export function engineSessionParam() {
+    const sid = hostSession()?.currentSessionId();
+    return typeof sid === 'string' && sid.length > 0 ? sid : undefined;
+}
+/** spread 便捷形:`{ ...engineSessionParamSpread() }` → `{ session: '<sid>' }` 或 `{}`。 */
+export function engineSessionParamSpread() {
+    const s = engineSessionParam();
+    return s ? { session: s } : {};
+}
+/**
+ * 当前活跃引擎 run 的 id(壳 = `engineToolDetach.getActiveEngineTaskId()`)。
+ * 库内多处 durable 动词要「宿主 run」做寻址第一跳,统一从这里取,不各自 import 端模块。
+ */
+export function activeEngineRunId() {
+    const id = hostSession()?.activeRunId();
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}

package/dist/engineWireTarget.d.ts

@@ -0,0 +1,14 @@
+export interface EngineWireTarget {
+    baseUrl: string;
+    token?: string;
+    principal: string;
+}
+/** 装/卸引擎 wire 目标。传 null 卸回 env 派生。返回还原函数。 */
+export declare function installEngineWireTarget(t: EngineWireTarget | null): () => void;
+/**
+ * 当前引擎 wire 目标。null = 无 wire(离线/mock/浏览器未装)—— 调用方走各自的回落路径,
+ * **不是**错误态。
+ */
+export declare function engineWireTarget(): EngineWireTarget | null;
+/** 诊断开关(壳侧 `process.env.SEMA_DEBUG` 的等价读;本包零 process)。 */
+export declare function engineWireDebugEnabled(): boolean;