@sema-agent/client-core 0.12.1 → 0.13.0

package/dist/sandboxWire.d.ts

@@ -1,29 +1,3 @@
-/**
- * src/sema/sandboxWire.ts — [686]② `--sandbox` TRI-STATE flag (clay 拍, 2026-07-13): the CLI face of the
- * per-task SANDBOX IMAGE PROFILE the server already ships end-to-end (`TaskRequest.sandboxImageProfile`
- * per-task binding + the model-facing `SelectEnvironment` tool + the `GET /v1/images` catalog).
- *
- * TRI-STATE (clay 口径):
- *  a) DEFAULT (no flag)      → NO `sandboxImageProfile` on the POST body — the worker's default image runs.
- *  b) `--sandbox <profile>`  → EXPLICIT: stamp `sandboxImageProfile` (SDK types.ts:115 → service
- *     main.ts:2316 resolves profile→digest FAIL-CLOSED with the caller's principal — we only ever send the
- *     PROFILE, never a digest). Vocabulary = the live catalog (`sema cloud images list` / GET /v1/images) —
- *     the shell does NOT pre-validate against it (fail-closed admission is the server's job; a typo comes
- *     back as an honest 404, mapped to a hint by sandboxDegradeHint below).
- *  c) `--sandbox auto`       → ADVISORY: the submit carries NO profile; instead the FIRST live turn's
- *     objective is prefixed with an advisory block asking the model to drive the `SelectEnvironment` tool
- *     itself (list → pick → report `Sandbox: <profile> — <reason>` in its reply, so the choice + reason are
- *     visible on the run card and correctable by the user). NOT a hard route — server keeps zero new
- *     endpoints; the tool's session binding takes effect from the NEXT task boundary ([440] F3 contract).
- *
- * LANE HONESTY (诚实不撒谎 UI, [686] constraint): the profile only works on the k8s sandbox lane — an
- * e2b/host-lane worker (including the local TOC self-spawned engine) 400s the submit honestly
- * (service main.ts:2323 "sandboxImageProfile is only supported on the k8s sandbox backend"). The shell does
- * NOT pre-judge the lane (no caps sniffing before submit — per [686]: "不预判 lane,收到 400 再提示");
- * it maps the server's honest reject into a degradation hint (sandboxDegradeHint) rendered on the error row.
- * So on the local self-spawned engine `--sandbox <profile>` = a LOUD per-turn failure with an actionable
- * hint — never a silent ignore (silently dropping the user's explicit environment choice would be lying).
- */
 export type SandboxSelection = {
     mode: 'default';
 } | {
@@ -45,7 +19,7 @@ export type SandboxParseResult = {
  * Missing value / flag-shaped value / empty / over-long ⇒ fail-LOUD parse error (never a silent default —
  * a mis-typed environment choice must not quietly run on the wrong image).
  */
-export declare function parseSandboxArgv(argv: string[]): SandboxParseResult;
+export declare function parseSandboxArgv(argv: readonly string[]): SandboxParseResult;
 /** The request-body stamp for a selection: EXPLICIT ⇒ `{sandboxImageProfile}`, default/auto ⇒ nothing
  *  (auto is advisory-by-prompt — the submit itself never carries a profile, per clay's c) 口径). */
 export declare function sandboxRequestFields(sel: SandboxSelection | undefined): {
@@ -65,11 +39,15 @@ export declare function sandboxRequestFields(sel: SandboxSelection | undefined):
 export declare const AUTO_SANDBOX_ADVISORY: string;
 /** Prefix an objective with the auto-select advisory (one-shot — the caller owns the latch). */
 export declare function wrapObjectiveWithAutoSandboxAdvisory(objective: string): string;
+export declare const SANDBOX_K8S_ONLY_400_ANCHOR = "only supported on the k8s sandbox backend";
+export declare const SANDBOX_NO_IMAGE_INDEX_400_ANCHOR = "requires the image index";
+export declare const SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR = "no published sandbox image for profile";
+export declare const SANDBOX_CASCADE_CONFLICT_400_ANCHOR = "not supported together with cascade/verify";
 /**
  * Map a submit failure → the sandbox DEGRADATION HINT, or undefined when the error is not sandbox-shaped.
- * Keys on the server's honest reject texts (ai-agent-service main.ts:2323-2330, per-task-image.ts:52,
- * server.ts:4651/4670) — status+substring, the same recognize-by-wire-shape idiom the quota/scenario
- * copy modules use. The caller renders it under the raw "API Error: …" row (original message preserved —
- * the hint supplements, never masks, the server's own words).
+ * Keys on the server's honest reject texts (the four `SANDBOX_*_ANCHOR` constants above) — status+substring,
+ * the same recognize-by-wire-shape idiom the quota/scenario copy modules use. The caller renders it under
+ * the raw "API Error: …" row (original message preserved — the hint supplements, never masks, the server's
+ * own words).
  */
 export declare function sandboxDegradeHint(err: unknown): string | undefined;

package/dist/sandboxWire.js

@@ -24,6 +24,7 @@
  * So on the local self-spawned engine `--sandbox <profile>` = a LOUD per-turn failure with an actionable
  * hint — never a silent ignore (silently dropping the user's explicit environment choice would be lying).
  */
+import { lastFlagValue } from './argvFlagValue.js';
 /** Mirror of the server's own body validation (server.ts:4651): non-empty, ≤128 chars. Validating locally
  *  just converts a guaranteed 400 into an immediate CLI error — same rule, earlier and cheaper. */
 const MAX_PROFILE_LEN = 128;
@@ -38,49 +39,38 @@ const USAGE_HINT = "sema: --sandbox expects a profile name or 'auto'.\n" +
  * a mis-typed environment choice must not quietly run on the wrong image).
  */
 export function parseSandboxArgv(argv) {
-    let sel = { mode: 'default' };
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === '--')
-            break; // positionals — never flags
-        let raw;
-        if (a === '--sandbox') {
-            const nxt = argv[i + 1];
-            if (nxt === undefined || nxt.startsWith('-')) {
-                return { ok: false, error: USAGE_HINT };
-            }
-            raw = nxt;
-            i++; // consume the value token
-        }
-        else if (a.startsWith('--sandbox=')) {
-            raw = a.slice('--sandbox='.length);
-        }
-        else {
-            continue;
-        }
-        const v = raw.trim();
-        if (v.length === 0)
-            return { ok: false, error: USAGE_HINT };
-        // audit #17: a bare `--sandbox` EATS the following positional — `-p --sandbox 'say hi'`
-        // consumed the prompt as the profile, then died on an unrelated "Input must be provided…"
-        // error. Profile names never contain whitespace; a value that does is almost certainly the
-        // user's prompt — say exactly that instead of silently mis-parsing.
-        if (/\s/.test(v)) {
-            return {
-                ok: false,
-                error: `Invalid sandbox profile "${v}". Profile names cannot contain spaces — if you meant it as the prompt, ` +
-                    `pass --sandbox a profile name (or 'auto') first, or omit --sandbox to use the worker default image.\n` +
-                    USAGE_HINT,
-            };
-        }
-        if (v.length > MAX_PROFILE_LEN) {
-            return {
-                ok: false,
-                error: `sema: --sandbox profile must be at most ${MAX_PROFILE_LEN} characters (same rule the server enforces).`,
-            };
-        }
-        sel = v === 'auto' ? { mode: 'auto' } : { mode: 'explicit', profile: v };
+    // REF-CC-143(dup-07)收编:extraction 改吃共用 lastFlagValue(argvFlagValue.ts)——scan-all-then-
+    // validate-once, matching this module's own documented "Repeated flag ⇒ LAST wins" contract (the
+    // former per-occurrence eager-validate loop actually violated that contract: an earlier INVALID
+    // occurrence overridden by a later VALID one used to fail-loud on the earlier one instead of
+    // honoring the later value — fixed as a side effect of the consolidation, not a logic rewrite).
+    const flag = lastFlagValue(argv, '--sandbox');
+    if (!flag.present)
+        return { ok: true, sel: { mode: 'default' } };
+    if (flag.raw === undefined)
+        return { ok: false, error: USAGE_HINT };
+    const v = flag.raw.trim();
+    if (v.length === 0)
+        return { ok: false, error: USAGE_HINT };
+    // audit #17: a bare `--sandbox` EATS the following positional — `-p --sandbox 'say hi'`
+    // consumed the prompt as the profile, then died on an unrelated "Input must be provided…"
+    // error. Profile names never contain whitespace; a value that does is almost certainly the
+    // user's prompt — say exactly that instead of silently mis-parsing.
+    if (/\s/.test(v)) {
+        return {
+            ok: false,
+            error: `Invalid sandbox profile "${v}". Profile names cannot contain spaces — if you meant it as the prompt, ` +
+                `pass --sandbox a profile name (or 'auto') first, or omit --sandbox to use the worker default image.\n` +
+                USAGE_HINT,
+        };
     }
+    if (v.length > MAX_PROFILE_LEN) {
+        return {
+            ok: false,
+            error: `sema: --sandbox profile must be at most ${MAX_PROFILE_LEN} characters (same rule the server enforces).`,
+        };
+    }
+    const sel = v === 'auto' ? { mode: 'auto' } : { mode: 'explicit', profile: v };
     return { ok: true, sel };
 }
 /** The request-body stamp for a selection: EXPLICIT ⇒ `{sandboxImageProfile}`, default/auto ⇒ nothing
@@ -108,30 +98,41 @@ export const AUTO_SANDBOX_ADVISORY = '<sandbox-auto-select>\n' +
 export function wrapObjectiveWithAutoSandboxAdvisory(objective) {
     return `${AUTO_SANDBOX_ADVISORY}\n\n${objective}`;
 }
+// ── REF-CC-124(域词表-03,P3 wave1 卡C-argv):四条拒绝 hint 判别锚常量化 ─────────────────────────
+// ALLOW 登记(与 detachWire.DETACH_DURABLE_OFF_400_ANCHOR 同形):这四条锚的是**另一个仓**
+// (ai-agent-service)当下的拒绝原文(main.ts SelectEnvironment 校验分支 / per-task-image.ts 镜像
+// 索引缺席分支 / server.ts submit 校验分支)——只留文件名+分支语义,不锚外仓行号(它们会腐烂,
+// wave1 回炉 advisory 修:server 改字即静默失效,失效方向只丢 hint、不误伤,是本族里后果最轻的
+// 一处,故过渡期常量化而非阻断发车)。
+// 候 server 5.0.0 errorCode 换轨,#117(上游到货后这四条整族改吃 errorCode,判别不再靠字符串锚)。
+export const SANDBOX_K8S_ONLY_400_ANCHOR = 'only supported on the k8s sandbox backend';
+export const SANDBOX_NO_IMAGE_INDEX_400_ANCHOR = 'requires the image index';
+export const SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR = 'no published sandbox image for profile';
+export const SANDBOX_CASCADE_CONFLICT_400_ANCHOR = 'not supported together with cascade/verify';
 /**
  * Map a submit failure → the sandbox DEGRADATION HINT, or undefined when the error is not sandbox-shaped.
- * Keys on the server's honest reject texts (ai-agent-service main.ts:2323-2330, per-task-image.ts:52,
- * server.ts:4651/4670) — status+substring, the same recognize-by-wire-shape idiom the quota/scenario
- * copy modules use. The caller renders it under the raw "API Error: …" row (original message preserved —
- * the hint supplements, never masks, the server's own words).
+ * Keys on the server's honest reject texts (the four `SANDBOX_*_ANCHOR` constants above) — status+substring,
+ * the same recognize-by-wire-shape idiom the quota/scenario copy modules use. The caller renders it under
+ * the raw "API Error: …" row (original message preserved — the hint supplements, never masks, the server's
+ * own words).
  */
 export function sandboxDegradeHint(err) {
     const e = err;
     if (typeof e?.status !== 'number' || typeof e?.message !== 'string')
         return undefined;
     const msg = e.message;
-    if (e.status === 400 && msg.includes('only supported on the k8s sandbox backend')) {
+    if (e.status === 400 && msg.includes(SANDBOX_K8S_ONLY_400_ANCHOR)) {
         return ('--sandbox <profile> only applies on k8s-lane workers; this engine runs a host/e2b sandbox lane, so the request was honestly rejected.\n' +
             'Re-run without --sandbox (worker default image), or point the shell at a k8s-lane worker (sema cloud engine connect <url>).');
     }
-    if (e.status === 400 && msg.includes('requires the image index')) {
+    if (e.status === 400 && msg.includes(SANDBOX_NO_IMAGE_INDEX_400_ANCHOR)) {
         return ('This worker has no sandbox image index configured (sema-registry backend absent), so per-task profiles cannot resolve.\n' +
             'Re-run without --sandbox, or use a worker with the image index enabled.');
     }
-    if (e.status === 404 && msg.includes('no published sandbox image for profile')) {
+    if (e.status === 404 && msg.includes(SANDBOX_NO_PUBLISHED_IMAGE_404_ANCHOR)) {
         return 'No published image matches that profile for your principal. List what you can use: sema cloud images list';
     }
-    if (e.status === 400 && msg.includes('not supported together with cascade/verify')) {
+    if (e.status === 400 && msg.includes(SANDBOX_CASCADE_CONFLICT_400_ANCHOR)) {
         return '--sandbox cannot combine with cascade/verify submits in v1 (the per-task image would not bind to the sub-runs). Drop one of the two.';
     }
     return undefined;

package/dist/scenarioWire.d.ts

@@ -47,7 +47,7 @@ export type ScenarioParseResult = {
  * fail-LOUD parse error (never a silent default — a mis-typed routing choice must not quietly run on
  * the wrong tool surface; same stance as `--sandbox`).
  */
-export declare function parseScenarioArgv(argv: string[]): ScenarioParseResult;
+export declare function parseScenarioArgv(argv: readonly string[]): ScenarioParseResult;
 /**
  * The settings-lane default (`SEMA_HEADLESS_SCENARIO`). FAIL-SOFT on a bad value (stderr warning +
  * no stamp): a settings-file typo must not hard-brick every headless run the way an explicit flag

package/dist/scenarioWire.js

@@ -29,6 +29,7 @@
  * deliberately NOT reused here: it selects offline mock transcripts, not live engine routing.
  */
 import { hostEnv } from './hostEnv.js';
+import { lastFlagValue } from './argvFlagValue.js';
 /** Mirror of the server's scenario NAME shape (ai-agent-service scenarios.ts:318). */
 export const SCENARIO_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
 /** Settings-lane env knob (settings.json `env` block → 1a-envseed → process.env). */
@@ -45,43 +46,31 @@ const USAGE_HINT = "sema: --scenario expects a scenario name (lowercase letters/
  * the wrong tool surface; same stance as `--sandbox`).
  */
 export function parseScenarioArgv(argv) {
-    let scenario;
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === '--')
-            break; // positionals — never flags
-        let raw;
-        if (a === '--scenario') {
-            const nxt = argv[i + 1];
-            if (nxt === undefined || nxt.startsWith('-')) {
-                return { ok: false, error: USAGE_HINT };
-            }
-            raw = nxt;
-            i++; // consume the value token
-        }
-        else if (a.startsWith('--scenario=')) {
-            raw = a.slice('--scenario='.length);
-        }
-        else {
-            continue;
-        }
-        const v = raw.trim();
-        // sandboxWire audit #17 lesson: a bare `--scenario` EATS the following positional — a value with
-        // whitespace is almost certainly the user's prompt; say exactly that instead of mis-parsing.
-        if (/\s/.test(v)) {
-            return {
-                ok: false,
-                error: `sema: --scenario got "${v.length > 48 ? `${v.slice(0, 48)}…` : v}" — that looks like your prompt, not a scenario name.\n` +
-                    'Put the flag AFTER the value form (--scenario=<name>) or keep the name and prompt as separate tokens.\n' +
-                    USAGE_HINT,
-            };
-        }
-        if (!SCENARIO_NAME_RE.test(v)) {
-            return { ok: false, error: USAGE_HINT };
-        }
-        scenario = v;
+    // REF-CC-143(dup-07)收编:extraction 改吃共用 lastFlagValue(argvFlagValue.ts)——scan-all-then-
+    // validate-once, matching this function's own documented "Repeated flag ⇒ LAST wins" contract (the
+    // former per-occurrence eager-validate loop actually violated that contract the same way sandboxWire's
+    // did: an earlier INVALID occurrence overridden by a later VALID one used to fail-loud on the earlier
+    // one instead of honoring the later value — fixed as a side effect of the consolidation).
+    const flag = lastFlagValue(argv, '--scenario');
+    if (!flag.present)
+        return { ok: true };
+    if (flag.raw === undefined)
+        return { ok: false, error: USAGE_HINT };
+    const v = flag.raw.trim();
+    // sandboxWire audit #17 lesson: a bare `--scenario` EATS the following positional — a value with
+    // whitespace is almost certainly the user's prompt; say exactly that instead of mis-parsing.
+    if (/\s/.test(v)) {
+        return {
+            ok: false,
+            error: `sema: --scenario got "${v.length > 48 ? `${v.slice(0, 48)}…` : v}" — that looks like your prompt, not a scenario name.\n` +
+                'Put the flag AFTER the value form (--scenario=<name>) or keep the name and prompt as separate tokens.\n' +
+                USAGE_HINT,
+        };
     }
-    return { ok: true, ...(scenario ? { scenario } : {}) };
+    if (!SCENARIO_NAME_RE.test(v)) {
+        return { ok: false, error: USAGE_HINT };
+    }
+    return { ok: true, scenario: v };
 }
 /**
  * The settings-lane default (`SEMA_HEADLESS_SCENARIO`). FAIL-SOFT on a bad value (stderr warning +

package/dist/seam.d.ts

@@ -22,6 +22,25 @@ export interface AbortSignalLike {
 export type TimerHandle = unknown;
 /** `ctx.log` 的级别词表(cli utils/debug logForDebugging 的等价面)。 */
 export type AdapterLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * TYPESHAPE-13:inline task tick 的形状——本文件(seam.ts,ChromeEvent 的 `inline_task_stats`/
+ * `op:'tick'` 臂内嵌套 `stats` 字段)与 `engineInlineTaskStats.ts`(`publishEngineInlineTaskTick`
+ * 的 `tick` 形参)两处逐字相同的形状,抽成具名类型两处共用——漏改一处(比如只给这里加
+ * `currentToolName?`)时,两侧编译仍全绿但字段会被静默丢弃,B4 命名 DU 豁免只护直接成员形状,
+ * 不护这种嵌套字段。
+ *
+ * 🔴 [P1 回炉,opus advisory⑤] 定义搬到这里(此前在 `engineInlineTaskStats.ts` 反向 import 进
+ * seam.ts):seam.ts 是本包基础词表模块,`engineInlineTaskStats.ts` 改前是零 import 文件——原先
+ * 由「零 import 的边缘文件」定义、被「基础词表模块」反向导入,层级是倒的。现在改为
+ * `engineInlineTaskStats.ts` 从这里 `import type`,方向回正;`index.ts` 的 barrel 不重复导出
+ * (只有这里 `export`,避免两处 `export *` 撞同名)。
+ */
+export interface InlineTaskTick {
+    toolUses: number;
+    totalTokens: number;
+    durationMs: number;
+    currentAction?: string;
+}
 /**
  * 宿主注入的适配上下文(时钟/铸号可测,B 形跨端确定性)。
  *
@@ -234,12 +253,7 @@ export type ChromeEvent = {
     op: 'tick';
     /** 委派 tool_use id(渲染面订阅键)。 */
     cardId: string;
-    stats: {
-        toolUses: number;
-        totalTokens: number;
-        durationMs: number;
-        currentAction?: string;
-    };
+    stats: InlineTaskTick;
 } | {
     kind: 'inline_task_stats';
     laneProof: LaneProof;
@@ -368,6 +382,9 @@ export type ChromeArmKind = ChromeEvent['kind'];
  * `required` 判据:**不实现会让已发生的行为丢失**(转录/模型输入/hook/去重)⇒ true;
  * 只影响可选装饰(spinner 计量、活体预览、chips)⇒ false。
  * `duty` = 一句话义务(完整义务在上方每臂的注释里,那里是真源)。
+ *
+ * 数组形对外形状不变(消费方逐字沿用 `CHROME_ARMS.map/find/filter`)——真源是上面
+ * {@link CHROME_ARM_TABLE},本表只是它的 `Object.entries` 派生投影。
  */
 export declare const CHROME_ARMS: readonly {
     kind: ChromeArmKind;

package/dist/seam.js

@@ -1,46 +1,56 @@
 /**
- * chrome 臂**覆盖率断言出口**(§8-1 裁决的一半:client-core 定接口不定实现)。
- *
- * 用途:任何宿主(TUI / web / 桌面)在自检里遍历本表,对 `required:true` 的臂断言"我实现了消费口"。
- * 不实现 = 该 UI 面在那个宿主上是**哑的**(不是报错,是静默没有)—— 这正是多端最容易漏的一类,
- * 所以把义务做成**数据**而不是散落在注释里。
+ * chrome 臂**覆盖率断言出口**的编译期底座(REF-CC-154,midband-02,gate)。
  *
- * `required` 判据:**不实现会让已发生的行为丢失**(转录/模型输入/hook/去重)⇒ true;
- * 只影响可选装饰(spinner 计量、活体预览、chips)⇒ false。
- * `duty` = 一句话义务(完整义务在上方每臂的注释里,那里是真源)。
+ * 🔴 为什么是 `Record<ChromeArmKind, …>` 不是数组字面量:此前 `CHROME_ARMS` 直接手写成数组,
+ * `ChromeEvent` 新增一个判别值时,漏补这张表**编译期零信号**——18 个判别值与表项手数对齐纯靠
+ * 人工核对。`Record` 强制**每个** `ChromeArmKind` 成员都有一条目,少一个 = tsc 报错,新臂想不进表
+ * 都不行(§B5「union 加成员必须打红全部消费 switch」的同族纪律)。
  */
-export const CHROME_ARMS = [
-    { kind: 'retry_status', required: false, duty: '渲/清 spinner 的重试覆盖层' },
-    { kind: 'panel_task', required: true, duty: 'publishEngineAgentPanelEvent(event) 原样转发' },
-    { kind: 'bgshell_settle', required: true, duty: '后台 shell 面板行落终态(含 outputPath)' },
-    { kind: 'bgshell_register', required: true, duty: '后台 shell 面板行建行 + 登记「句柄→宿主 run」' },
-    { kind: 'tasks_expand', required: false, duty: '展开 ctrl+t 任务面板' },
-    { kind: 'thinking_activity', required: false, duty: '开/收活体 "∴ Thinking…" 行' },
-    { kind: 'request_start', required: false, duty: 'spinner 置 requesting 态' },
-    { kind: 'stream_delta', required: false, duty: '渲活体预览 + 推进 responseLength' },
-    { kind: 'response_metrics', required: false, duty: '驱动 responseLength reducer(ttft/对账)' },
-    { kind: 'attachment', required: false, duty: '渲 attachment 行(必须带 default 臂)' },
-    { kind: 'notification_terminal', required: false, duty: '可选 UI 提示(记账已由库自持)' },
-    { kind: 'subagent_lifecycle', required: true, duty: 'fire SubagentStart/Stop hooks(去重已由库解)' },
-    {
-        kind: 'workflow_notification_enqueue',
+const CHROME_ARM_TABLE = {
+    retry_status: { required: false, duty: '渲/清 spinner 的重试覆盖层' },
+    panel_task: { required: true, duty: 'publishEngineAgentPanelEvent(event) 原样转发' },
+    bgshell_settle: { required: true, duty: '后台 shell 面板行落终态(含 outputPath)' },
+    bgshell_register: { required: true, duty: '后台 shell 面板行建行 + 登记「句柄→宿主 run」' },
+    tasks_expand: { required: false, duty: '展开 ctrl+t 任务面板' },
+    thinking_activity: { required: false, duty: '开/收活体 "∴ Thinking…" 行' },
+    request_start: { required: false, duty: 'spinner 置 requesting 态' },
+    stream_delta: { required: false, duty: '渲活体预览 + 推进 responseLength' },
+    response_metrics: { required: false, duty: '驱动 responseLength reducer(ttft/对账)' },
+    attachment: { required: false, duty: '渲 attachment 行(必须带 default 臂)' },
+    notification_terminal: { required: false, duty: '可选 UI 提示(记账已由库自持)' },
+    subagent_lifecycle: { required: true, duty: 'fire SubagentStart/Stop hooks(去重已由库解)' },
+    workflow_notification_enqueue: {
         required: true,
         // 门/notified 记账/cardEnqueued 记号三件已由库在发臂前做完 ⇒ 宿主只投递,且必须用**裸入队**口。
         duty: 'message 裸入完成通知队列(不要用自带去重门的老函数),idle 时喂模型;门与两条记号归库',
     },
-    {
-        kind: 'task_ledger_sync',
+    task_ledger_sync: {
         required: true,
         // 🔴 **两个 source 都要接**(B6 核实:同一张任务卡实测出两条)——`tool_use` 是卡刚开时的
         // 乐观建行(旧引擎只有它),`structured` 是引擎回来的权威全量态(带真实 id/状态)。
         // 只接前者 ⇒ 引擎真实 id 永不回填;只接后者 ⇒ 面板要等工具跑完才出现。幂等键 = toolUseId。
         duty: '按 toolUseId 幂等落 TaskCreate/TaskUpdate —— source 的 tool_use(乐观建行)与 structured(权威全量态)两条都要接',
     },
-    { kind: 'inline_task_stats', required: true, duty: 'tick/settle/settle_all 转发给 engineInlineTaskStats' },
-    { kind: 'prompt_suggestions', required: false, duty: '推 composer 上方 chips(绝不回喂模型)' },
-    { kind: 'last_turn_usage', required: true, duty: '落最近一次 turn 真 usage(statusline 回落源)' },
-    { kind: 'plan_review_park', required: true, duty: '弹 plan 审批卡(fail-soft,不挡后续终态帧)' },
-];
+    inline_task_stats: { required: true, duty: 'tick/settle/settle_all 转发给 engineInlineTaskStats' },
+    prompt_suggestions: { required: false, duty: '推 composer 上方 chips(绝不回喂模型)' },
+    last_turn_usage: { required: true, duty: '落最近一次 turn 真 usage(statusline 回落源)' },
+    plan_review_park: { required: true, duty: '弹 plan 审批卡(fail-soft,不挡后续终态帧)' },
+};
+/**
+ * chrome 臂**覆盖率断言出口**(§8-1 裁决的一半:client-core 定接口不定实现)。
+ *
+ * 用途:任何宿主(TUI / web / 桌面)在自检里遍历本表,对 `required:true` 的臂断言"我实现了消费口"。
+ * 不实现 = 该 UI 面在那个宿主上是**哑的**(不是报错,是静默没有)—— 这正是多端最容易漏的一类,
+ * 所以把义务做成**数据**而不是散落在注释里。
+ *
+ * `required` 判据:**不实现会让已发生的行为丢失**(转录/模型输入/hook/去重)⇒ true;
+ * 只影响可选装饰(spinner 计量、活体预览、chips)⇒ false。
+ * `duty` = 一句话义务(完整义务在上方每臂的注释里,那里是真源)。
+ *
+ * 数组形对外形状不变(消费方逐字沿用 `CHROME_ARMS.map/find/filter`)——真源是上面
+ * {@link CHROME_ARM_TABLE},本表只是它的 `Object.entries` 派生投影。
+ */
+export const CHROME_ARMS = Object.entries(CHROME_ARM_TABLE).map(([kind, d]) => ({ kind, required: d.required, duty: d.duty }));
 /**
  * transcript id 确定性派生([1653] 定案):稳定键优先序 = 帧 id > seq > toolCallId;
  * 全缺才用 ctx.uuid()。同流重放 ⇒ 同 id 序列(往返守卫钉此不变量)。