@sema-agent/client-core 0.12.1 → 0.13.0

package/dist/cloudConfigWireCaps.js

@@ -7,26 +7,41 @@ const asStr = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
  * Project the registry's mcp domain (`config.mcp.servers`, registry-core McpServerSpec — the CENTER shape
  * with envRefs/headerRefs) → the SDK/core wire `McpServerSpec[]` (real env/header VALUES, resolved from the
  * shell env). Disabled servers are skipped; unknown transport kinds are skipped (never mis-mapped); the
- * result is capped at MCP_CAPS.items exactly like the local `.mcp.json` projection.
+ * result is capped at MCP_CAPS.items exactly like the local `.mcp.json` projection. Every skip is recorded
+ * in `droppedServers` (REF-CC-157) — nothing vanishes from the wire silently.
  */
 export function cloudMcpToSpecs(servers, env) {
     const specs = [];
     const missingEnv = [];
+    const droppedServers = [];
+    const drop = (name, reason) => {
+        droppedServers.push({ ...(name ? { name } : {}), reason });
+    };
     for (const raw of asArr(servers)) {
-        if (specs.length >= MCP_CAPS.items)
-            break;
         const s = asRec(raw);
-        if (!s || s.enabled === false)
+        const name = s ? asStr(s.name) : undefined;
+        // cap first: everything past MCP_CAPS.items is dropped regardless of what it looks like — this is
+        // the reason it never got evaluated, so report it as such (not as a false 'missing-field').
+        if (specs.length >= MCP_CAPS.items) {
+            drop(name, 'capped');
             continue;
-        const name = asStr(s.name);
+        }
+        if (!s || s.enabled === false) {
+            drop(name, s?.enabled === false ? 'disabled' : 'missing-field');
+            continue;
+        }
         const t = asRec(s.transport);
-        if (!name || !t)
+        if (!name || !t) {
+            drop(name, 'missing-field');
             continue;
+        }
         let transport = null;
         if (t.kind === 'stdio') {
             const command = asStr(t.command);
-            if (!command)
+            if (!command) {
+                drop(name, 'missing-field');
                 continue;
+            }
             // envRefs: target ENV key → ENV NAME holding the value (center never stores the secret). Resolve
             // against the shell env — the engine child inherits it, so stdio spawn sees the same values.
             const envOut = {};
@@ -50,8 +65,10 @@ export function cloudMcpToSpecs(servers, env) {
         }
         else if (t.kind === 'http') {
             const url = asStr(t.url);
-            if (!url)
+            if (!url) {
+                drop(name, 'missing-field');
                 continue;
+            }
             const headers = {};
             for (const [headerName, ref] of Object.entries(asRec(t.headerRefs) ?? {})) {
                 const refName = asStr(ref);
@@ -72,7 +89,8 @@ export function cloudMcpToSpecs(servers, env) {
             };
         }
         else {
-            continue; // unknown transport kind — skip, never mis-map (same posture as the local sse/ws skip)
+            drop(name, 'unknown-transport'); // unknown transport kind — skip, never mis-map (same posture as the local sse/ws skip)
+            continue;
         }
         const allowTools = asArr(s.allowTools).filter((a) => typeof a === 'string');
         specs.push({
@@ -82,7 +100,7 @@ export function cloudMcpToSpecs(servers, env) {
             ...(s.elicitation === true ? { elicitation: true } : {}),
         });
     }
-    return { specs, missingEnv: [...new Set(missingEnv)] };
+    return { specs, missingEnv: [...new Set(missingEnv)], droppedServers };
 }
 // ── skills: config.skills.skills (MANIFEST) + bodies → SkillSpec[] ───────────────────────────────────────
 /**
@@ -137,6 +155,26 @@ export function cloudModelsToDoc(models) {
         ...(Array.isArray(m.atModelAllowlist) ? { atModelAllowlist: m.atModelAllowlist } : {}),
     };
 }
+/**
+ * REF-CC-157(midband-05,fix-outright):`config.models.models` 里被 `cloudModelsToDoc` 过滤掉的原始
+ * 条目(缺 `name` 或 `id`)——仿 `skillsMissingBody` 的形状,重扫同一份原始数组产出丢弃清单,让调用方
+ * 能警示用户「你的 model 配置有 N 行没生效」,而不是让一个打错字的字段静默从目录消失。
+ */
+export function cloudModelsDropped(models) {
+    const m = asRec(models);
+    if (!m || !Array.isArray(m.models))
+        return [];
+    const out = [];
+    for (const e of m.models) {
+        const r = asRec(e);
+        if (r && asStr(r.name) && asStr(r.id))
+            continue; // kept by cloudModelsToDoc — not dropped
+        const id = r ? asStr(r.id) : undefined;
+        const name = r ? asStr(r.name) : undefined;
+        out.push({ ...(id ? { id } : {}), ...(name ? { name } : {}) });
+    }
+    return out;
+}
 /** ENABLED model names in a models doc (banner/status display + "did the cloud catalog apply" checks). */
 export function cloudModelNames(doc) {
     if (!doc)
@@ -200,7 +238,7 @@ export function projectEffectiveBody(body, skillBodies, env, rostersValue) {
     const config = asRec(b.config) ?? {};
     const mcpDomain = asRec(config.mcp);
     const skillsDomain = asRec(config.skills);
-    const { specs: mcp, missingEnv: mcpMissing } = cloudMcpToSpecs(mcpDomain?.servers, env);
+    const { specs: mcp, missingEnv: mcpMissing, droppedServers: droppedMcpServers } = cloudMcpToSpecs(mcpDomain?.servers, env);
     const manifest = asArr(skillsDomain?.skills);
     const skills = cloudSkillsToSpecs(manifest, (hash) => skillBodies[hash] ?? null);
     const skillsMissingBody = manifest
@@ -223,6 +261,8 @@ export function projectEffectiveBody(body, skillBodies, env, rostersValue) {
         missingEnv: [...new Set([...mcpMissing, ...cloudModelMissingKeyEnv(modelsDoc, env)])],
         scope: asStr(b.scope) ?? 'global',
         skillsMissingBody,
+        droppedMcpServers,
+        droppedModels: cloudModelsDropped(config.models),
         execution: cloudExecutionToPolicy(config.execution),
     };
 }

package/dist/controlRouter.d.ts

@@ -196,11 +196,17 @@ export declare class ControlRouter {
     }): Promise<RunReceipt | null>;
     private nextId;
 }
-/** Read a normalized error code/status off any SDK error shape variant (errorCode / code / name / status).
- *  design/161 批 A 起导出:错误判型单源 —— 包内新读面(backgroundView 等)一律吃这一口,不再各自手摸
- *  `(e as any).status`。 */
-export declare function errCodes(e: unknown): {
-    code?: unknown;
-    name?: unknown;
-    status?: unknown;
-};
+/** design/161 批 A 起导出:错误判型单源 —— 包内新读面(backgroundView 等)一律吃这一口,不再各自
+ *  手摸 `(e as any).status`。 */
+export interface ErrCodes {
+    code?: string | undefined;
+    name?: string | undefined;
+    status?: number | undefined;
+}
+/**
+ * Read a normalized error code/status off any SDK error shape variant (errorCode / code / name / status).
+ * REF-CC-135(TYPESHAPE-15,P3 wave1 卡C-argv):判型单源此前返回 3 个裸 unknown(B2/B4 违规——调用方
+ * `code === 404`(status 才是数字位)这类拼写型 bug 能编译期全绿恒 false)。窄化成具名 `ErrCodes`,
+ * 非匹配类型一律降到 undefined(而不是把垃圾值原样放行)。
+ */
+export declare function errCodes(e: unknown): ErrCodes;

package/dist/controlRouter.js

@@ -1,3 +1,4 @@
+import { uuid } from './adapter/types.js';
 // ── Errors the router surfaces (fail-closed; never auto-retried) ───────────────
 //
 // Mirrors hitlBridge.HitlSafetyError: every safety-relevant control error is a signal to re-present to the
@@ -60,7 +61,7 @@ export class ControlRouter {
      */
     async submit(text, opts) {
         const req = this.buildTaskRequest(text);
-        const receipt = await this.client.runs.create(req, opts ? { signal: opts.signal } : undefined);
+        const receipt = await this.client.runs.create(req, opts?.signal !== undefined ? { signal: opts.signal } : undefined);
         // Adopt service-minted continuity + latch the in-flight run.
         if (this.sessionId === undefined)
             this.sessionId = receipt.sessionId;
@@ -109,7 +110,7 @@ export class ControlRouter {
         // Raw text, no pre-sanitize (the server fences). `mode` omitted → server default one-at-a-time.
         const body = mode !== undefined ? { text, mode } : { text };
         try {
-            return await this.client.runs.steer(this.taskId, body, opts ? { signal: opts.signal } : undefined);
+            return await this.client.runs.steer(this.taskId, body, opts?.signal !== undefined ? { signal: opts.signal } : undefined);
         }
         catch (e) {
             if (isSteeringNotRunning(e)) {
@@ -147,7 +148,7 @@ export class ControlRouter {
             throw new ControlSafetyError('no run in flight to cancel', 'not_found');
         }
         try {
-            return await this.client.runs.cancel(this.taskId, opts ? { signal: opts.signal } : undefined);
+            return await this.client.runs.cancel(this.taskId, opts?.signal !== undefined ? { signal: opts.signal } : undefined);
         }
         catch (e) {
             if (isCancelSuspendedConflict(e)) {
@@ -206,29 +207,22 @@ export class ControlRouter {
         return `q-${this.seq}-${uuid()}`;
     }
 }
-// ── helpers ───────────────────────────────────────────────────────────────────
-/** A v4-shaped uuid for the local queue handles (never on the wire). Mirrors types.ts/seamQuery's helper. */
-function uuid() {
-    const g = typeof globalThis !== 'undefined'
-        ? globalThis.crypto
-        : undefined;
-    if (g && typeof g.randomUUID === 'function')
-        return g.randomUUID();
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-        const r = (Math.random() * 16) | 0;
-        const v = c === 'x' ? r : (r & 0x3) | 0x8;
-        return v.toString(16);
-    });
-}
-/** Read a normalized error code/status off any SDK error shape variant (errorCode / code / name / status).
- *  design/161 批 A 起导出:错误判型单源 —— 包内新读面(backgroundView 等)一律吃这一口,不再各自手摸
- *  `(e as any).status`。 */
+/**
+ * Read a normalized error code/status off any SDK error shape variant (errorCode / code / name / status).
+ * REF-CC-135(TYPESHAPE-15,P3 wave1 卡C-argv):判型单源此前返回 3 个裸 unknown(B2/B4 违规——调用方
+ * `code === 404`(status 才是数字位)这类拼写型 bug 能编译期全绿恒 false)。窄化成具名 `ErrCodes`,
+ * 非匹配类型一律降到 undefined(而不是把垃圾值原样放行)。
+ */
 export function errCodes(e) {
     if (!e || typeof e !== 'object')
         return {};
     const o = e;
     // [1912] errorCode 恒在(server ≥1.302 canonical)——`?? o.code` 老兜底已清;status 双键保留(HTTP 层形非 wire 键)。
-    return { code: o.errorCode, name: o.name, status: o.status ?? o.statusCode };
+    const code = typeof o.errorCode === 'string' ? o.errorCode : undefined;
+    const name = typeof o.name === 'string' ? o.name : undefined;
+    const rawStatus = o.status ?? o.statusCode;
+    const status = typeof rawStatus === 'number' ? rawStatus : undefined;
+    return { code, name, status };
 }
 /** 409 `steering.not_running` / `SteeringNotRunningError` — the run is suspended/terminal (runs.ts:45). */
 function isSteeringNotRunning(e) {

package/dist/detachWire.d.ts

@@ -46,8 +46,9 @@
  * 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.
+ *  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
@@ -71,9 +72,10 @@ 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 纪律).
+ * 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 纪律).
  */
 export declare function headlessDetachDisabledByEnv(env?: EnvLike): boolean;
 /**
@@ -105,6 +107,14 @@ export declare function resolveHeadlessDetach(baseUrl: string, env?: EnvLike, op
     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";

package/dist/detachWire.js

@@ -46,8 +46,9 @@
  * 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.
+ *  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
@@ -58,6 +59,7 @@
  *  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';
@@ -72,13 +74,13 @@ 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 纪律).
+ * 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 纪律).
  */
 export function headlessDetachDisabledByEnv(env = hostEnv()) {
-    const v = env[HEADLESS_DETACH_ENV]?.trim().toLowerCase();
-    return v === 'false' || v === '0';
+    return envFlagOff(env[HEADLESS_DETACH_ENV]);
 }
 /**
  * Version-gate probe: GET `${baseUrl}/health`, read `version`. Returns FALSE only when the engine is
@@ -135,6 +137,14 @@ export async function resolveHeadlessDetach(baseUrl, env = hostEnv(), opts) {
 // 也无处可查)。壳自 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';

package/dist/effortWire.d.ts

@@ -1,24 +1,3 @@
-/**
- * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/effortWire.ts 逐字搬入(零依赖)。
- */
-/**
- * src/sema/effortWire.ts — the EFFORT/REASONING-STRENGTH ENGINE WIRE (per-turn `/effort` → engine).
- *
- * WHY THIS FILE EXISTS (the parity gap it closes):
- * CC's `/effort` slider sets a per-turn reasoning strength; sema's picker writes it to `AppState.effortValue`
- * (overrides/effort.tsx:302) but the seam's `toTaskRequest` never put it on the wire, so the picked effort
- * reached the UI yet NOT the engine. Grounding (2026-06-29) showed the seam is ALREADY complete downstream:
- *   - core `TaskSpec.thinking: ThinkingLevel` = off|minimal|low|medium|high|xhigh|max (7 档,covers CC effort)
- *     — `core/src/core/types.ts:466`; consumed at `prepare-task.ts:1663` (→brain) / :1471 (xhigh/max→awareness).
- *   - service `reasoningEffort` → `thinking`, UNKNOWN value 400 fail-loud — `server.ts:234/3576`, `main.ts:1270`.
- * So this is a SHELL-only wire: map the picked `EffortValue` → the wire `reasoningEffort` (a core ThinkingLevel)
- * and stamp it on `TaskRequest`. Pure projection here (testable); the AppState read is inline in seamQuery.
- *
- * MAPPING: sema's picker can yield low|medium|high|max (base EffortLevel) + xhigh|ultracode|auto (187 override
- * accept-set) + numeric. The wire `reasoningEffort` accepts a core ThinkingLevel only. So pass a value IFF it
- * is a ThinkingLevel (off|minimal|low|medium|high|xhigh|max); `auto` (let engine default), `ultracode` (a
- * separate mode, future slice), numeric and unset all OMIT — the engine then uses its own default.
- */
 /**
  * The core ThinkingLevel = the service `reasoningEffort` accept-set (`server.ts:3576`) = the SDK
  * `TaskRequest.reasoningEffort` union. Declared as a literal union (not bare `string`) so the projection's

package/dist/effortWire.js

@@ -1,25 +1,11 @@
+const REASONING_EFFORT_TUPLE = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
 /**
- * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/effortWire.ts 逐字搬入(零依赖)。
- */
-/**
- * src/sema/effortWire.ts — the EFFORT/REASONING-STRENGTH ENGINE WIRE (per-turn `/effort` → engine).
- *
- * WHY THIS FILE EXISTS (the parity gap it closes):
- * CC's `/effort` slider sets a per-turn reasoning strength; sema's picker writes it to `AppState.effortValue`
- * (overrides/effort.tsx:302) but the seam's `toTaskRequest` never put it on the wire, so the picked effort
- * reached the UI yet NOT the engine. Grounding (2026-06-29) showed the seam is ALREADY complete downstream:
- *   - core `TaskSpec.thinking: ThinkingLevel` = off|minimal|low|medium|high|xhigh|max (7 档,covers CC effort)
- *     — `core/src/core/types.ts:466`; consumed at `prepare-task.ts:1663` (→brain) / :1471 (xhigh/max→awareness).
- *   - service `reasoningEffort` → `thinking`, UNKNOWN value 400 fail-loud — `server.ts:234/3576`, `main.ts:1270`.
- * So this is a SHELL-only wire: map the picked `EffortValue` → the wire `reasoningEffort` (a core ThinkingLevel)
- * and stamp it on `TaskRequest`. Pure projection here (testable); the AppState read is inline in seamQuery.
- *
- * MAPPING: sema's picker can yield low|medium|high|max (base EffortLevel) + xhigh|ultracode|auto (187 override
- * accept-set) + numeric. The wire `reasoningEffort` accepts a core ThinkingLevel only. So pass a value IFF it
- * is a ThinkingLevel (off|minimal|low|medium|high|xhigh|max); `auto` (let engine default), `ultracode` (a
- * separate mode, future slice), numeric and unset all OMIT — the engine then uses its own default.
+ * 🔴 [2006] B-CC-2(2026-07-29):`new Set<ReasoningEffort>([…])` 只保证「元素合法」,**从不保证
+ * 穷举** —— 往 `ReasoningEffort` 加第八档而这里不跟,编译期一声不吭,运行期那一档被
+ * `effortToReasoningEffort` 当成非法值 OMIT 掉 ⇒ 用户拨到的档位静默到不了引擎。补的就是
+ * 「类型 → 常量」那半边:两个方向的 `Exclude` 都必须塌成 `never`。
+ * `Covers`(REF-CC-145/dup-12,P3 wave1 卡C-argv)改吃共用叶 typePins.ts——四份逐字重复钉之一。
  */
-const REASONING_EFFORT_TUPLE = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
 const _effortPins = [true, true];
 void _effortPins;
 const REASONING_EFFORTS = new Set(REASONING_EFFORT_TUPLE);

package/dist/engineInlineTaskStats.d.ts

@@ -22,6 +22,17 @@
  * ticks by itself. Local (non-engine) AgentTool runs never write here, so the local path is untouched
  * (fallback only consulted when the card id has an entry).
  */
+/**
+ * TYPESHAPE-13:inline task tick 的形状(生产侧 `seam.ts` ChromeEvent 的 `inline_task_stats`/
+ * `op:'tick'` 臂内嵌套 `stats` 字段 ↔ 本文件消费侧 `publishEngineInlineTaskTick` 的 `tick` 形参)
+ * 跨模块内联写了两份逐字相同的形状,抽成具名类型两处共用——漏改一处(比如只给 seam.ts 加
+ * `currentToolName?`)时,两侧编译仍全绿但字段会被静默丢弃,B4 命名 DU 豁免只护直接成员形状,
+ * 不护这种嵌套字段。
+ *
+ * 定义在 `seam.ts`(本包基础词表模块)、这里反向 import——本文件是零依赖的 dep-free store,
+ * seam.ts 反过来依赖它会把层级倒过来。
+ */
+import type { InlineTaskTick } from './seam.js';
 export interface EngineInlineTaskStats {
     /** Cumulative tool uses off the latest tick (frozen at settle). */
     toolUses: number;
@@ -38,12 +49,7 @@ export interface EngineInlineTaskStats {
     isError: boolean;
 }
 /** Bridge write side — latest cumulative tick for the card. No-op once the card settled (frozen finals). */
-export declare function publishEngineInlineTaskTick(cardId: string, tick: {
-    toolUses: number;
-    totalTokens: number;
-    durationMs: number;
-    currentAction?: string;
-}): void;
+export declare function publishEngineInlineTaskTick(cardId: string, tick: InlineTaskTick): void;
 /** Bridge write side — the delegating card closed: freeze the finals. Idempotent. */
 export declare function settleEngineInlineTaskStats(cardId: string, isError: boolean): void;
 /** Turn-end / abort sweep twin — settle every card still live (a subagent never emits a terminal tick). */

package/dist/engineWireSdk.d.ts

@@ -53,6 +53,18 @@ export declare function resolveWireAuth(baseUrl: string | undefined, token?: str
  * 同一函数的两个名字不是两套行为)。新代码一律用 `resolveWireAuth`。
  */
 export declare function wireAuthTokenFor(baseUrl: string, token?: string): WireAuthToken;
+/**
+ * TYPESHAPE-12:「向引擎发一次探测请求需要哪些参数」的共用形状(agentsWireCaps.
+ * engineSupportsTaskAgents ↔ liveInitToolFace.probeScenarioTools 此前各写一份逐字相同的 4 成员
+ * 内联形)。🔴 只统一形状,不统一值:两处 `timeoutMs` 缺省值不同(3000 vs 2000)——这是既有行为
+ * 差异,各自在调用点保留现值,改值属于行为变更,不在本次收编授权内。
+ */
+export type EngineProbeOpts = {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    authToken?: string | undefined;
+    principal?: string | undefined;
+};
 export type EngineWireClientConfig = {
     baseUrl: string;
     /** 真 token 串;缺省经 wireAuthTokenFor 三态解析(loopback-unauthed / 'anon')。 */

package/dist/env/localeGeo.js

@@ -73,7 +73,8 @@ const echo = (v) => (v.length > ECHO_MAX ? `${v.slice(0, ECHO_MAX)}…` : v);
 function localeTag(input) {
     const pick = (v) => (typeof v === 'string' ? v.trim() : '');
     const raw = pick(input.lcAll) || pick(input.lang);
-    const tag = raw.split('.')[0].split('@')[0].trim();
+    const rawNoCodeset = raw.split('.')[0] ?? '';
+    const tag = (rawNoCodeset.split('@')[0] ?? '').trim();
     if (!tag || NEUTRAL_LOCALES.has(tag.toLowerCase()))
         return '';
     return LANGUAGE_TAG_SHAPE.test(tag) ? tag : '';

package/dist/envFlag.d.ts

@@ -0,0 +1,39 @@
+/**
+ * envFlag.ts — single spelling-set source for boolean-shaped `SEMA_*` env knobs (REF-CC-141, P2
+ * 台账 dup-02,wave1 卡B,2026-08-01).
+ *
+ * WHY: ten call sites across nine `*Wire*`/`*WireCaps*` modules each hand-rolled their own
+ * off/on-spelling check for a `SEMA_*` boolean env knob, and the four variants DISAGREED:
+ *   ① 4-word off-set `'0'|'false'|'no'|'off'` (6 copies: forkWireCaps.ts isFalsy,
+ *      selfOrchestrationWireCaps.ts isFalsy, retainBackgroundWireCaps.ts isFalsy,
+ *      ultracodeWireCaps.ts deferOptedOut + lowFreqOptedOut, hooksWireCaps.ts isGoalStopHookWireArmed);
+ *   ② 2-word off-set `'false'|'0'` (2 copies: detachWire.ts headlessDetachDisabledByEnv,
+ *      finalVerifyWire.ts headlessFinalVerifyDisabledByEnv) — `=off` / `=no` silently did nothing;
+ *   ③ 4-word off-set but a DIFFERENT fourth word `'off'|'0'|'false'|'none'`
+ *      (attachmentsWireCaps.ts attachmentsForRequest — accepted "none", not "no");
+ *   ④ 2-word set WITHOUT lowercasing `raw==='true'||raw==='1'` / `raw==='false'||raw==='0'`
+ *      (interactiveToolsWire.ts resolveHeadlessInteractiveTools — `SEMA_HEADLESS_INTERACTIVE_TOOLS=False`
+ *      fell through to the "not a boolean" warn-and-default path instead of being recognized).
+ *
+ * User-visible consequence (dup-02 evidence): the SAME settings.json could have
+ * `SEMA_HEADLESS_DETACH=off` silently ignored (falls back to default-ON) sitting right next to
+ * `SEMA_RETAIN_BACKGROUND=off` which worked — no way for a user to know which spelling their knob
+ * actually honors.
+ *
+ * FIX: one leaf module, one spelling set PER POLARITY, each the UNION across all four prior
+ * variants (only-tightens-never-loosens direction inverted here on purpose — widen everywhere,
+ * never narrow a caller's existing accepted set). Zero dependencies (no `hostEnv`/`EnvLike` import —
+ * operates on the already-extracted string, so it stays trivially portable and unit-testable).
+ */
+/**
+ * True iff `v` is an explicit OFF spelling ({@link OFF_SPELLINGS}: `0`/`false`/`no`/`off`/`none`,
+ * case-insensitive, trimmed). Unset/empty/unrecognized ⇒ `false` — the caller decides what "not
+ * explicitly off" defaults to (many of these knobs are default-ON escape hatches).
+ */
+export declare function envFlagOff(v: string | undefined): boolean;
+/**
+ * True iff `v` is an explicit ON spelling ({@link ON_SPELLINGS}: `1`/`true`/`yes`/`on`,
+ * case-insensitive, trimmed). Unset/empty/unrecognized ⇒ `false` — the caller decides what "not
+ * explicitly on" defaults to.
+ */
+export declare function envFlagOn(v: string | undefined): boolean;

package/dist/envFlag.js

@@ -0,0 +1,51 @@
+/**
+ * envFlag.ts — single spelling-set source for boolean-shaped `SEMA_*` env knobs (REF-CC-141, P2
+ * 台账 dup-02,wave1 卡B,2026-08-01).
+ *
+ * WHY: ten call sites across nine `*Wire*`/`*WireCaps*` modules each hand-rolled their own
+ * off/on-spelling check for a `SEMA_*` boolean env knob, and the four variants DISAGREED:
+ *   ① 4-word off-set `'0'|'false'|'no'|'off'` (6 copies: forkWireCaps.ts isFalsy,
+ *      selfOrchestrationWireCaps.ts isFalsy, retainBackgroundWireCaps.ts isFalsy,
+ *      ultracodeWireCaps.ts deferOptedOut + lowFreqOptedOut, hooksWireCaps.ts isGoalStopHookWireArmed);
+ *   ② 2-word off-set `'false'|'0'` (2 copies: detachWire.ts headlessDetachDisabledByEnv,
+ *      finalVerifyWire.ts headlessFinalVerifyDisabledByEnv) — `=off` / `=no` silently did nothing;
+ *   ③ 4-word off-set but a DIFFERENT fourth word `'off'|'0'|'false'|'none'`
+ *      (attachmentsWireCaps.ts attachmentsForRequest — accepted "none", not "no");
+ *   ④ 2-word set WITHOUT lowercasing `raw==='true'||raw==='1'` / `raw==='false'||raw==='0'`
+ *      (interactiveToolsWire.ts resolveHeadlessInteractiveTools — `SEMA_HEADLESS_INTERACTIVE_TOOLS=False`
+ *      fell through to the "not a boolean" warn-and-default path instead of being recognized).
+ *
+ * User-visible consequence (dup-02 evidence): the SAME settings.json could have
+ * `SEMA_HEADLESS_DETACH=off` silently ignored (falls back to default-ON) sitting right next to
+ * `SEMA_RETAIN_BACKGROUND=off` which worked — no way for a user to know which spelling their knob
+ * actually honors.
+ *
+ * FIX: one leaf module, one spelling set PER POLARITY, each the UNION across all four prior
+ * variants (only-tightens-never-loosens direction inverted here on purpose — widen everywhere,
+ * never narrow a caller's existing accepted set). Zero dependencies (no `hostEnv`/`EnvLike` import —
+ * operates on the already-extracted string, so it stays trivially portable and unit-testable).
+ */
+/** OFF spellings — union of all four prior variants (see file header). Case-insensitive, trimmed. */
+const OFF_SPELLINGS = new Set(['0', 'false', 'no', 'off', 'none']);
+/** ON spellings — union of all prior variants that had an explicit truthy branch (forkWireCaps
+ *  isTruthy `1/true/yes/on`; interactiveToolsWire's narrower `true/1`). Case-insensitive, trimmed. */
+const ON_SPELLINGS = new Set(['1', 'true', 'yes', 'on']);
+function normalize(v) {
+    return typeof v === 'string' ? v.trim().toLowerCase() : '';
+}
+/**
+ * True iff `v` is an explicit OFF spelling ({@link OFF_SPELLINGS}: `0`/`false`/`no`/`off`/`none`,
+ * case-insensitive, trimmed). Unset/empty/unrecognized ⇒ `false` — the caller decides what "not
+ * explicitly off" defaults to (many of these knobs are default-ON escape hatches).
+ */
+export function envFlagOff(v) {
+    return OFF_SPELLINGS.has(normalize(v));
+}
+/**
+ * True iff `v` is an explicit ON spelling ({@link ON_SPELLINGS}: `1`/`true`/`yes`/`on`,
+ * case-insensitive, trimmed). Unset/empty/unrecognized ⇒ `false` — the caller decides what "not
+ * explicitly on" defaults to.
+ */
+export function envFlagOn(v) {
+    return ON_SPELLINGS.has(normalize(v));
+}

package/dist/finalVerifyWire.d.ts

@@ -10,8 +10,9 @@
  * PRECEDENCE(off 优先,任何一条命中即不 stamp;否则默认 true):
  *  a) `--no-final-verify` flag                         → off(一键回上游 2.1.207 严格对齐态:上游
  *     `-p` 全文 0 处 final verification,默认开属超集;上游对应扩展点是 Stop hook)。
- *  b) `SEMA_HEADLESS_FINAL_VERIFY` env('false'/'0')  → off。settings.json `env` 块 → 1a-envseed →
- *     process.env,其它 wire 配置(SEMA_HEADLESS_SCENARIO 等)同一车道。
+ *  b) `SEMA_HEADLESS_FINAL_VERIFY` env(envFlagOff 拼写集,REF-CC-141 dup-02 单源)→ off。
+ *     settings.json `env` 块 → 1a-envseed → process.env,其它 wire 配置(SEMA_HEADLESS_SCENARIO 等)
+ *     同一车道。
  *  c) 用户配置了 Stop hook(settings hooks.Stop,经 hooksForWire 投影)→ off【对抗轮硬性 amendment】:
  *     引擎 finalVerification 分支在 Stop hook 查询之前 return(runtask.js:1430-1443),默认开会把
  *     用户 Stop hook 延迟至多 2 turn——对上游迁移来的 hook 用户是真行为变化,故有 Stop hook 即让位。
@@ -39,9 +40,10 @@ export declare const HEADLESS_FINAL_VERIFY_ENV = "SEMA_HEADLESS_FINAL_VERIFY";
  */
 export declare function parseNoFinalVerifyArgv(argv: string[]): boolean;
 /**
- * The settings-lane off-switch:`SEMA_HEADLESS_FINAL_VERIFY` = 'false' or '0'(case-insensitive)
- * disables the stamp。其它任何值(含空串/'true'/typo)= 默认态 on——fail-soft:一个 settings typo
- * 只会落回默认开,绝不 brick 任何 run(scenarioWire 的 settings-lane 纪律)。
+ * The settings-lane off-switch:`SEMA_HEADLESS_FINAL_VERIFY` 设成 {@link envFlagOff} 拼写集
+ * (REF-CC-141 dup-02 单源:`0`/`false`/`no`/`off`/`none`,大小写不敏感)disables the stamp。
+ * 其它任何值(含空串/'true'/typo)= 默认态 on——fail-soft:一个 settings typo 只会落回默认开,
+ * 绝不 brick 任何 run(scenarioWire 的 settings-lane 纪律)。
  */
 export declare function headlessFinalVerifyDisabledByEnv(env?: EnvLike): boolean;
 /**

package/dist/finalVerifyWire.js

@@ -1,4 +1,5 @@
 import { hostEnv } from './hostEnv.js';
+import { envFlagOff } from './envFlag.js';
 /** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。'false'/'0' = off。 */
 export const HEADLESS_FINAL_VERIFY_ENV = 'SEMA_HEADLESS_FINAL_VERIFY';
 /**
@@ -15,13 +16,13 @@ export function parseNoFinalVerifyArgv(argv) {
     return false;
 }
 /**
- * The settings-lane off-switch:`SEMA_HEADLESS_FINAL_VERIFY` = 'false' or '0'(case-insensitive)
- * disables the stamp。其它任何值(含空串/'true'/typo)= 默认态 on——fail-soft:一个 settings typo
- * 只会落回默认开,绝不 brick 任何 run(scenarioWire 的 settings-lane 纪律)。
+ * The settings-lane off-switch:`SEMA_HEADLESS_FINAL_VERIFY` 设成 {@link envFlagOff} 拼写集
+ * (REF-CC-141 dup-02 单源:`0`/`false`/`no`/`off`/`none`,大小写不敏感)disables the stamp。
+ * 其它任何值(含空串/'true'/typo)= 默认态 on——fail-soft:一个 settings typo 只会落回默认开,
+ * 绝不 brick 任何 run(scenarioWire 的 settings-lane 纪律)。
  */
 export function headlessFinalVerifyDisabledByEnv(env = hostEnv()) {
-    const v = env[HEADLESS_FINAL_VERIFY_ENV]?.trim().toLowerCase();
-    return v === 'false' || v === '0';
+    return envFlagOff(env[HEADLESS_FINAL_VERIFY_ENV]);
 }
 /**
  * 用户 Stop hook 在场判定:hooksForWire() 投影(policy→user→project→local 合并、trust/managed 门后)