@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/detachWire.d.ts

@@ -1,108 +1,14 @@
-/**
- * ⇄ 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 = an {@link envFlagOff} spelling (REF-CC-141 dup-02 单源;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` set to an {@link envFlagOff} spelling
- * (REF-CC-141 dup-02 单源:`0`/`false`/`no`/`off`/`none`,大小写不敏感)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 纪律).
- *
- * 🔴 [2393] sweep-F12(2026-08-03 全窗复审)**承诺范围如实**:上面那句话是在 off 集只有
- * `{false,0}` 的时代写的,当时它覆盖 `no`/`off`/`none` 三个拼写(它们落进「任何其它值 ⇒ 默认 ON」)。
- * REF-CC-141 把 off 集扩到五词之后,**这三个拼写现在会**把车道翻成 disconnect-kills-run。
- * 扩集本身是既定方向(用户写 `no`/`off`/`none` 时意图确实是「关」),这里只把范围说清楚:
- * 「typo 绝不静默翻车道」现在指的是 `{false,0,no,off,none}` **之外**的拼写。
- */
 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).
- */
-/** 0.72.13 CC-53:版本闸探测的**三态**读数。`unknown` = /health 答得奇怪(非 2xx / 坏 JSON)或整个不可达 —— 不能证明陈旧,也没证明支持。 */
 export type EngineDetachSupport = 'supported' | 'unsupported' | 'unknown';
-/**
- * 三态读口(0.72.13 CC-53;test 证据帖「异常被吞成健康值」一类):此前只有布尔口,「不可达」与「确认支持」同返 `true`。
- * fail-soft 的**行为**不变(`unknown` 照发 detach 头:头在 wire 上无害,死引擎由随后的流 POST 响亮失败),变的是
- * 调用方现在**分得清**并能把这件事说出来({@link detachSupportDisclosure})。1.5s 预算,永不抛。
- */
 export declare function probeEngineDetachSupport(baseUrl: string, opts?: {
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
 }): Promise<EngineDetachSupport>;
-/** `unknown` 时给用户 / 日志的一句披露(单源);另两态 ⇒ `undefined`(没什么要披露的)。 */
 export declare function detachSupportDisclosure(support: EngineDetachSupport): string | undefined;
 export declare function engineSupportsDetach(baseUrl: string, opts?: {
     fetchImpl?: typeof fetch;
@@ -115,58 +21,22 @@ export type DetachResolution = {
     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>;
-/**
- * 🟢 B8 ALLOW 清单登记(REF-CC-域词表-05,属主=client-core 规范重构轮,到期复议=server 契约文案
- * 变更时或 2026-Q4 复审以先到者为准):文本匹配 + 非文本结构性合取前置(`isDetachArmed()` +
- * `status===400`),不是散点裸字面量。同批同表的另两处:`classifierVerdictWire.ts`
- * `CLASSIFIER_DENY_SIGNATURE`(core lockstep 机器签名)、`subagent/engineTaskHandleWire.ts`
- * `STOP_CONFLICT_CODES`(SDK typed 缺席时的 code-in-text 回落)——三处互指,理由逐条写在各自
- * 站点,不共享一份文案(判错方向、前置合取各不相同)。
- */
-/** 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';
     };
-    /** SDK Principal。缺席(undefined)=消费方不发 x-agent-principal 头(owner-null 单机形)——
-     *  与 SDK 6.11 Transport 的值检查删头语义一致;绝不在此铸哨兵值。 */
     principal: string | undefined;
-    /** 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

@@ -1,98 +1,13 @@
-/**
- * ⇄ 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 = an {@link envFlagOff} spelling (REF-CC-141 dup-02 单源;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 { envFlagOff } from './envFlag.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` set to an {@link envFlagOff} spelling
- * (REF-CC-141 dup-02 单源:`0`/`false`/`no`/`off`/`none`,大小写不敏感)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 纪律).
- *
- * 🔴 [2393] sweep-F12(2026-08-03 全窗复审)**承诺范围如实**:上面那句话是在 off 集只有
- * `{false,0}` 的时代写的,当时它覆盖 `no`/`off`/`none` 三个拼写(它们落进「任何其它值 ⇒ 默认 ON」)。
- * REF-CC-141 把 off 集扩到五词之后,**这三个拼写现在会**把车道翻成 disconnect-kills-run。
- * 扩集本身是既定方向(用户写 `no`/`off`/`none` 时意图确实是「关」),这里只把范围说清楚:
- * 「typo 绝不静默翻车道」现在指的是 `{false,0,no,off,none}` **之外**的拼写。
- */
 export function headlessDetachDisabledByEnv(env = hostEnv()) {
     return envFlagOff(env[HEADLESS_DETACH_ENV]);
 }
-/**
- * 三态读口(0.72.13 CC-53;test 证据帖「异常被吞成健康值」一类):此前只有布尔口,「不可达」与「确认支持」同返 `true`。
- * fail-soft 的**行为**不变(`unknown` 照发 detach 头:头在 wire 上无害,死引擎由随后的流 POST 响亮失败),变的是
- * 调用方现在**分得清**并能把这件事说出来({@link detachSupportDisclosure})。1.5s 预算,永不抛。
- */
 export async function probeEngineDetachSupport(baseUrl, opts) {
     const fetchImpl = opts?.fetchImpl ?? fetch;
     const controller = new AbortController();
@@ -105,13 +20,11 @@ export async function probeEngineDetachSupport(baseUrl, opts) {
         if (!res.ok)
             return 'unknown';
         const body = await res.json();
-        // 回体必须是对象:null / 数组 / 标量 = 答得奇怪 ⇒ unknown(异源对抗复审:此前折成 unsupported,消费者据此关掉 detach)。
         if (body === null || typeof body !== 'object' || Array.isArray(body))
             return 'unknown';
         if (!('version' in body))
-            return 'unsupported'; // 健康回体、无 version 键 = pre-1.96 引擎(确证陈旧)
+            return 'unsupported';
         const version = body.version;
-        // version 在场但不是可解析的 x.y.z 串 ⇒ unknown(不拿读不懂的值当「陈旧」证据)
         if (typeof version !== 'string' || !/^\d+\.\d+\.\d+/.test(version))
             return 'unknown';
         if (versionSupportsDetach(version))
@@ -125,58 +38,25 @@ export async function probeEngineDetachSupport(baseUrl, opts) {
         clearTimeout(timer);
     }
 }
-/** `unknown` 时给用户 / 日志的一句披露(单源);另两态 ⇒ `undefined`(没什么要披露的)。 */
 export function detachSupportDisclosure(support) {
     if (support !== 'unknown')
         return undefined;
     return 'could not confirm whether this engine supports detach (its /health did not answer usably); sending the detach header anyway — it is harmless on the wire, and a dead engine fails the request loudly';
 }
 export async function engineSupportsDetach(baseUrl, opts) {
-    // 布尔口 = 三态口的薄封装(保留给既有调用方):只有**确证陈旧**才不发;`unknown` 仍 fail-soft 发。
     return (await probeEngineDetachSupport(baseUrl, opts)) !== 'unsupported';
 }
-/**
- * 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 行字面保留)。
-/**
- * 🟢 B8 ALLOW 清单登记(REF-CC-域词表-05,属主=client-core 规范重构轮,到期复议=server 契约文案
- * 变更时或 2026-Q4 复审以先到者为准):文本匹配 + 非文本结构性合取前置(`isDetachArmed()` +
- * `status===400`),不是散点裸字面量。同批同表的另两处:`classifierVerdictWire.ts`
- * `CLASSIFIER_DENY_SIGNATURE`(core lockstep 机器签名)、`subagent/engineTaskHandleWire.ts`
- * `STOP_CONFLICT_CODES`(SDK typed 缺席时的 code-in-text 回落)——三处互指,理由逐条写在各自
- * 站点,不共享一份文案(判错方向、前置合取各不相同)。
- */
-/** 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;
@@ -189,27 +69,18 @@ export function detachDurableOffHint(err) {
     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/deviceExecutorManagementCapability.d.ts

@@ -1,53 +1,20 @@
-/**
- * deviceExecutorManagementCapability — `GET /v1/capabilities.deviceExecutor.management`(server ≥7.88.0;契约附录 B.1
- * `deviceExecutor` 行 + §14)的三端共用读面(0.74.2;与 sql / writeProtection / webSearch.backend / executionLane /
- * approvalsStreamLive 五只兄弟同一套四态词汇)。sdk 9.7.1 对该位无型 ⇒ 按契约结构读;9.8.x 起声明 `management?: boolean`(0.75.0 CC-81 对表:读器不改,门钉声明形)。
- *
- * ── 这一位答的是哪一个问题 ────────────────────────────────────────────────────────────────
- * 「`/v1/devices/*` 的管理动词在这台 server 上在不在」(present-iff:与该族 501 判据逐字同源)。它挂在 `deviceExecutor`
- * 对象里:`deviceExecutor === false` = 本部署**没有 device 车道**(管理面无从谈起,六动词一律 501 `capability.device_lane_required`);
- * 对象在场但 `management` 键缺席 = 7.88.0 之前的 server,**判不出**,只能按 501 试探。
- *
- * ── 🔴 读法 ─────────────────────────────────────────────────────────────────────────────────
- *  ① `management` **键缺席 ≠ false**(真字节:7.87.3 车道真开而无此键)⇒ `not_reported`;`deviceExecutor` 键整个不存在
- *     (更老 server)同样 `not_reported`(判别子 `why` 分开记,后者只有夹具、无真版本见证)。
- *  ② `deviceExecutor: false` 是**键在、值为布尔 false**(不是键被省掉)⇒ `lane_absent`;判在场用 `hasOwn`,不用 `in` 判真值。
- *  ③ `management` 严格布尔;`null` / 串 / 数 / 数组 / 对象 ⇒ 畸形(删格 ⇒ `unobserved`);`deviceExecutor` 非 false 非对象同畸形。
- *  ④ 「管理动词能不能用」的判据归包:{@link deviceManagementVerbsAvailable} —— 只有 present ∧ true 才 `'yes'`;
- *     present ∧ false 与 `lane_absent` ⇒ `'no'`(明确的否);其余 ⇒ `'unknown'`(别当 no,也别当 yes)。
- */
-/** 四态读数。`unobserved` 由读口在这一格空缺时铸,不由投影铸。 */
 export type DeviceExecutorManagementReading = {
     kind: 'unobserved';
-}
-/** `why`:`capability_absent` = `deviceExecutor` 键整个不存在(更老 server);`management_absent` = 车道对象在场、位缺席(7.88.0 之前)。 */
- | {
+} | {
     kind: 'not_reported';
     why: 'capability_absent' | 'management_absent';
-}
-/** `deviceExecutor === false`:本部署没有 device 车道。 */
- | {
+} | {
     kind: 'lane_absent';
 } | {
     kind: 'present';
     management: boolean;
 };
-/** caps 回体 → 本格读数;畸形一律 `undefined`(= 这一格不写 ⇒ 读口答 `unobserved`)。 */
 export declare function projectDeviceExecutorManagementCapability(caps: unknown): DeviceExecutorManagementReading | undefined;
-/** 宿主 caps probe 的读面 tee 落点(与五只兄弟并列)。绝不 throw;畸形 ⇒ 删格;`opts.generation` 关掉旧探测覆盖新读数的竞态。 */
 export declare function noteEngineCapsForDeviceExecutorManagement(baseUrl: string, caps: unknown, opts?: {
     generation?: number;
 }): void;
-/** 本进程观测到的读数;这一格空缺 ⇒ `{kind:'unobserved'}`。 */
 export declare function observedDeviceExecutorManagement(baseUrl?: string | undefined): DeviceExecutorManagementReading;
-/**
- * 「`/v1/devices/*` 管理动词能不能用」的判据单源(三态):只有引擎明说在场(present ∧ true)才 `'yes'`;
- * 明说不在(present ∧ false)或没有 device 车道 ⇒ `'no'`;老 server / 从没观测 ⇒ `'unknown'`(端按 501 试探,不预判)。
- */
 export declare function deviceManagementVerbsAvailable(reading: DeviceExecutorManagementReading): 'yes' | 'no' | 'unknown';
-/** doctor 那一行的 detail 串,唯一措辞真源。🔴 `not_reported` 句不许暗示「没有管理面」。 */
 export declare function deviceExecutorManagementDoctorDetail(reading: DeviceExecutorManagementReading): string;
-/** 换代失效口(引擎温切成功后调):清成未观测。空串 ⇒ no-op;绝不 throw。 */
 export declare function forgetDeviceExecutorManagementReading(baseUrl: string | undefined): void;
-/** 测试钩子。 */
 export declare function __resetDeviceExecutorManagementReadingsForTests(): void;

package/dist/deviceExecutorManagementCapability.js

@@ -1,32 +1,11 @@
-/**
- * deviceExecutorManagementCapability — `GET /v1/capabilities.deviceExecutor.management`(server ≥7.88.0;契约附录 B.1
- * `deviceExecutor` 行 + §14)的三端共用读面(0.74.2;与 sql / writeProtection / webSearch.backend / executionLane /
- * approvalsStreamLive 五只兄弟同一套四态词汇)。sdk 9.7.1 对该位无型 ⇒ 按契约结构读;9.8.x 起声明 `management?: boolean`(0.75.0 CC-81 对表:读器不改,门钉声明形)。
- *
- * ── 这一位答的是哪一个问题 ────────────────────────────────────────────────────────────────
- * 「`/v1/devices/*` 的管理动词在这台 server 上在不在」(present-iff:与该族 501 判据逐字同源)。它挂在 `deviceExecutor`
- * 对象里:`deviceExecutor === false` = 本部署**没有 device 车道**(管理面无从谈起,六动词一律 501 `capability.device_lane_required`);
- * 对象在场但 `management` 键缺席 = 7.88.0 之前的 server,**判不出**,只能按 501 试探。
- *
- * ── 🔴 读法 ─────────────────────────────────────────────────────────────────────────────────
- *  ① `management` **键缺席 ≠ false**(真字节:7.87.3 车道真开而无此键)⇒ `not_reported`;`deviceExecutor` 键整个不存在
- *     (更老 server)同样 `not_reported`(判别子 `why` 分开记,后者只有夹具、无真版本见证)。
- *  ② `deviceExecutor: false` 是**键在、值为布尔 false**(不是键被省掉)⇒ `lane_absent`;判在场用 `hasOwn`,不用 `in` 判真值。
- *  ③ `management` 严格布尔;`null` / 串 / 数 / 数组 / 对象 ⇒ 畸形(删格 ⇒ `unobserved`);`deviceExecutor` 非 false 非对象同畸形。
- *  ④ 「管理动词能不能用」的判据归包:{@link deviceManagementVerbsAvailable} —— 只有 present ∧ true 才 `'yes'`;
- *     present ∧ false 与 `lane_absent` ⇒ `'no'`(明确的否);其余 ⇒ `'unknown'`(别当 no,也别当 yes)。
- */
 import { engineWireTarget } from './engineWireTarget.js';
 import { createEngineCapReader } from './engineCapReader.js';
-/** caps 回体 → 本格读数;畸形一律 `undefined`(= 这一格不写 ⇒ 读口答 `unobserved`)。 */
 export function projectDeviceExecutorManagementCapability(caps) {
     if (caps === null || typeof caps !== 'object' || Array.isArray(caps))
-        return undefined; // 0.77.0 整族同律:数组不是能力表
+        return undefined;
     const c = caps;
     if (!Object.hasOwn(c, 'deviceExecutor'))
         return { kind: 'not_reported', why: 'capability_absent' };
-    // 🔴 外层也只读一次(0.74.2 补审 [medium]):hasOwn 之后 `deviceExecutor` 读进局部量,undefined / false / 对象三判都对同一次读;
-    //    此前 undefined 判与取值各读一次,变化的 getter 会把第一次观测到的「车道缺席」丢掉。
     const d = c.deviceExecutor;
     if (d === undefined)
         return { kind: 'not_reported', why: 'capability_absent' };
@@ -37,7 +16,6 @@ export function projectDeviceExecutorManagementCapability(caps) {
     const o = d;
     if (!Object.hasOwn(o, 'management'))
         return { kind: 'not_reported', why: 'management_absent' };
-    // 🔴 只读一次(异源对抗复审 R1):校验与返回若各读一次,变化的 getter 会让校验读到布尔、返回读到串。
     const mgmt = o.management;
     if (mgmt === undefined)
         return { kind: 'not_reported', why: 'management_absent' };
@@ -45,28 +23,17 @@ export function projectDeviceExecutorManagementCapability(caps) {
         return undefined;
     return { kind: 'present', management: mgmt };
 }
-/**
- * 本格的 per-baseUrl 读账 + tee / 读口 / 失效口 / 测试钩四口 —— 各只能力位读器**共用同一份实现**
- * ({@link createEngineCapReader});本文件只留这一格真正不同的部分:投影函数 {@link projectDeviceExecutorManagementCapability}、doctor 措辞表,以及本位自己的判据助手(如有)。
- * 🔴 Map 在工厂闭包里,**一只读器一张**:收到读不懂的回体只删自己这一格,绝不连坐别的能力面。
- */
 const reader = createEngineCapReader({
     name: 'deviceExecutor.management',
     project: projectDeviceExecutorManagementCapability,
     makeUnobserved: () => ({ kind: 'unobserved' }),
 });
-/** 宿主 caps probe 的读面 tee 落点(与五只兄弟并列)。绝不 throw;畸形 ⇒ 删格;`opts.generation` 关掉旧探测覆盖新读数的竞态。 */
 export function noteEngineCapsForDeviceExecutorManagement(baseUrl, caps, opts) {
     reader.note(baseUrl, caps, opts);
 }
-/** 本进程观测到的读数;这一格空缺 ⇒ `{kind:'unobserved'}`。 */
 export function observedDeviceExecutorManagement(baseUrl = engineWireTarget()?.baseUrl) {
     return reader.observed(baseUrl);
 }
-/**
- * 「`/v1/devices/*` 管理动词能不能用」的判据单源(三态):只有引擎明说在场(present ∧ true)才 `'yes'`;
- * 明说不在(present ∧ false)或没有 device 车道 ⇒ `'no'`;老 server / 从没观测 ⇒ `'unknown'`(端按 501 试探,不预判)。
- */
 export function deviceManagementVerbsAvailable(reading) {
     if (reading.kind === 'present')
         return reading.management ? 'yes' : 'no';
@@ -74,7 +41,6 @@ export function deviceManagementVerbsAvailable(reading) {
         return 'no';
     return 'unknown';
 }
-/** doctor 那一行的 detail 串,唯一措辞真源。🔴 `not_reported` 句不许暗示「没有管理面」。 */
 export function deviceExecutorManagementDoctorDetail(reading) {
     switch (reading.kind) {
         case 'unobserved':
@@ -91,11 +57,9 @@ export function deviceExecutorManagementDoctorDetail(reading) {
                 : 'device lane on but the /v1/devices management verbs are off on this deployment';
     }
 }
-/** 换代失效口(引擎温切成功后调):清成未观测。空串 ⇒ no-op;绝不 throw。 */
 export function forgetDeviceExecutorManagementReading(baseUrl) {
     reader.forget(baseUrl);
 }
-/** 测试钩子。 */
 export function __resetDeviceExecutorManagementReadingsForTests() {
     reader.__resetForTests();
 }

package/dist/diagnostics.d.ts

@@ -1,11 +1,3 @@
-/**
- * diagnostics.ts — 引擎 LSP `diagnostics` 帧 → CC `diagnostics` attachment 载荷(PURE)。
- * cli upstreamBridge case 'diagnostics' 的等价搬运(design/121):
- *  · wire severity 是 LSP 数字(1=Error 2=Warning 3=Info 4=Hint)→ CC 字符串枚举;
- *    缺席/越界 → 'Error'(可见胜过隐身);
- *  · range 缺席 → 零 range 占位(渲染器必读字段);source/code 存在才铸(且一律 String 化);
- *  · 只留 `file://` 前缀且有诊断项的文件;全滤光 ⇒ 返回 null(宿主不渲空行)。
- */
 declare const SEV: readonly ["Error", "Warning", "Info", "Hint"];
 export interface DiagnosticsAttachment {
     type: 'diagnostics';

package/dist/diagnostics.js

@@ -1,11 +1,3 @@
-/**
- * diagnostics.ts — 引擎 LSP `diagnostics` 帧 → CC `diagnostics` attachment 载荷(PURE)。
- * cli upstreamBridge case 'diagnostics' 的等价搬运(design/121):
- *  · wire severity 是 LSP 数字(1=Error 2=Warning 3=Info 4=Hint)→ CC 字符串枚举;
- *    缺席/越界 → 'Error'(可见胜过隐身);
- *  · range 缺席 → 零 range 占位(渲染器必读字段);source/code 存在才铸(且一律 String 化);
- *  · 只留 `file://` 前缀且有诊断项的文件;全滤光 ⇒ 返回 null(宿主不渲空行)。
- */
 const SEV = ['Error', 'Warning', 'Info', 'Hint'];
 export function projectDiagnosticsFrame(frame) {
     const zeroRange = { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } };

package/dist/diff/patch.d.ts

@@ -1,23 +1,6 @@
-/**
- * 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;

package/dist/diff/patch.js

@@ -1,20 +1,6 @@
-/**
- * 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) {
@@ -23,12 +9,7 @@ function escapeForDiff(s) {
 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));