@sema-agent/client-core 0.2.0 → 0.3.0

package/dist/engineAgentPanelStore.d.ts

@@ -0,0 +1,111 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineAgentPanelStore.ts 逐字搬入(零 import;壳侧改 re-export)。
+ * 🔴 同 subagentContentStore:buffer/listener/residentTaskIds 是单实例语义,发布侧(bridge/fleet
+ * 投影)与订阅侧(chrome-agentprogress 的面板 hook)必须同实例,否则事件发进一个副本、面板订另一个。
+ */
+/**
+ * engineAgentPanelStore — dep-free side-channel store bridging ENGINE-side subagent progress
+ * (`task_progress` ticks, design/99 MF-10) to CC's CoordinatorTaskPanel (the footer live-agent panel).
+ *
+ * WHY A STORE (the retryStatusStore / liveQuestionStore pattern): the upstream bridge is a plain
+ * generator with no React/AppState access, while the panel reads `AppState.tasks` — so the bridge
+ * PUBLISHES neutral events here and a sema-owned hook inside chrome-agentprogress.tsx (already mounted
+ * under the footer) SUBSCRIBES and applies them to AppState via registerTask/updateTaskState. CC files
+ * stay verbatim; the AppState write side lives in the sema override that owns the panel.
+ *
+ * WHY THE PANEL (CC-187 parity): a local sync AgentTool renders an inline progress TRAIL from the
+ * subagent's real messages. An engine tick carries ONLY rollup numbers ({toolUses, totalTokens}) — the
+ * exact shape of CC's `AgentProgress` — and CC's own precedent for out-of-process agents (remote agent
+ * tasks) is the TASK PANEL + task-notification, not a synthetic inline trail. Faithful mapping, no
+ * fabricated subagent messages.
+ *
+ * Buffering: ticks published before the panel mounts are buffered (bounded) and replayed to the first
+ * subscriber, so early frames in a fast turn aren't lost to mount timing.
+ */
+export type EngineAgentPanelEvent = {
+    kind: 'tick';
+    taskId: string;
+    /** Subagent display name off the wire tick (redacted upstream); absent ⇒ keep taskId. */
+    name?: string;
+    /** The delegating Task tool_use's `description` (the card title), when the bridge could bind one. */
+    description?: string;
+    /** The delegated prompt off the bound tool_use input, when present. */
+    prompt?: string;
+    /** core 1.262.0 [558]B (service 1.154.0 wire) — the child's most recent tool intent as ONE
+     *  human line ("Bash npm test"), service-redacted. The panel consumer maps it onto the row's
+     *  `progress.summary` (CC's own live-activity display slot); absent ⇒ slot untouched. */
+    currentAction?: string;
+    toolUses: number;
+    totalTokens: number;
+} | {
+    /**
+     * 行帧 lane 投影(2026-07-26 「后台 Agent 子代不进 Background 面板」案)。
+     *
+     * 一手取证(verify/_bgagent-panel-lane-live-pty.mjs 首跑,engine 1.277.4 真机):两个
+     * `run_in_background:true` 的 fork 子代**活跃干活整跑**,`task_progress` tick 探针 **0 条**、
+     * fleet 行帧探针 **24 条** —— 父 turn 秒收口即关 SSE,子代的 tick 根本没有通道到壳;行帧
+     * lane(常开 fleet stream)才是后台子代唯一在场的 lane。面板的 local_agent 行此前**只**由
+     * tick 注册 ⇒ 产品自印的「N background agents launched (↓ to manage)」指向一个看不到它们的
+     * 面板(还顺带让 `ctrl+x ctrl+k … stop all agents` 的渲染门在真产品里永不成立)。
+     *
+     * 为什么是独立事件形而不是复用 'tick':两条 lane 的**可选性**不同 —— tick 的 `toolUses` 是
+     * 必填数,行帧的是**可选**位(server 1.278.0 才有,老引擎没有)。复用 tick 会强迫本 lane 在
+     * 缺席时编一个 0,把前台子代由真 tick 写进去的进度数字每秒清一次。消费端对本事件的规矩:
+     * 只建/只喂**本 lane 亲手建的行**,tick 一到就永久让位(fleetOwnedRowIds 摘除)。
+     */
+    kind: 'fleet-row';
+    taskId: string;
+    /** 行帧 agentType(fleet 行 label 列,如 'fork')→ 行的 agentType。 */
+    name?: string;
+    /** 行帧投影出的任务描述(如 'alpha-probe')→ 行的 description(面板行 label)。 */
+    description?: string;
+    /** core 1.429 → server 1.288([1831]②):子代当前工具的结构化形。`toolName` verbatim
+     *  (查壳工具注册表),`target` 已上游 redact + 300 bound。缺席=旧端或子代从未跑过工具。 */
+    currentTool?: {
+        toolName: string;
+        target?: string;
+    };
+    /** 行帧累计 token。 */
+    totalTokens?: number;
+    /**
+     * server 1.278.0 起行帧也带的**累计**工具调用数(修「后台子代详情页 tool 计数恒 0」)。
+     *
+     * 🔴 三态,别写 `?? 0`:
+     *   · 键在 ⇒ 真值(含真 0 = 引擎说「一个工具都没跑」);
+     *   · 键不在 ⇒ 老引擎没这个位 = **不知道**,消费端如实留空/保留行上已有值,绝不写 0。
+     * 🔴 **累计不是增量**:bg sink 的 usage 是累计口径(与 `turn_end` 的每轮增量相反,后者在
+     *    upstreamBridge 里要累加)——消费端直接赋值,绝不 `+=`。
+     *
+     * ⚠️ 时序差(server 主动提醒,不是接错):1.278.0 只在 **bg lane** 上线;workflow/subagent
+     * 子代走的 `task_progress`(tick lane)的 `usage.toolUses` 在 core 类型里本来就必填、数据一直
+     * 在,只是那条 lane 也没发 —— 已补齐但搭 1.278.0 之后的下一车。所以短期内「有的行有、有的
+     * 行没有」是**预期形**,两条 lane 的接线口径已按同一套三态写好。
+     */
+    toolUses?: number;
+    /**
+     * server 1.278.0 `transcriptId`(= core 铸的子代 childSessionId)—— 转录锚,**不是** prompt。
+     * 委派 prompt 走它:壳侧凭这个 id 去转录读面取首条 user 消息(engineDelegatedPrompt.ts),
+     * 修「详情页 Prompt 段恒空」。缺席 ⇒ 维持现状(诚实留白)。
+     */
+    transcriptId?: string;
+} | {
+    kind: 'end';
+    taskId: string;
+    isError: boolean;
+    /** The subagent's FINAL REPORT — the delegating Task/Agent card's `tool_end.output` text (only the
+     *  explicit close arm carries it; the defensive sweeps settle without one). The consumer persists it
+     *  on the row (task.result) + appends it to a live-viewed transcript (拍1 查看态 seed). */
+    report?: string;
+} | {
+    /** Exception-path safety net (published by seamQuery after every turn, throw or return):
+     *  the consumer settles ALL rows it owns that are still running. Idempotent. */
+    kind: 'sweep';
+};
+export declare function markEnginePanelTaskResident(taskId: string): void;
+export declare function clearEnginePanelTaskResident(taskId: string): void;
+export declare function isEnginePanelTaskResident(taskId: string): boolean;
+type Listener = (ev: EngineAgentPanelEvent) => void;
+export declare function publishEngineAgentPanelEvent(ev: EngineAgentPanelEvent): void;
+/** Single consumer (the panel hook). Replays any buffered events, returns an unsubscribe. */
+export declare function subscribeEngineAgentPanel(fn: Listener): () => void;
+export {};

package/dist/engineAgentPanelStore.js

@@ -0,0 +1,93 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineAgentPanelStore.ts 逐字搬入(零 import;壳侧改 re-export)。
+ * 🔴 同 subagentContentStore:buffer/listener/residentTaskIds 是单实例语义,发布侧(bridge/fleet
+ * 投影)与订阅侧(chrome-agentprogress 的面板 hook)必须同实例,否则事件发进一个副本、面板订另一个。
+ */
+/**
+ * engineAgentPanelStore — dep-free side-channel store bridging ENGINE-side subagent progress
+ * (`task_progress` ticks, design/99 MF-10) to CC's CoordinatorTaskPanel (the footer live-agent panel).
+ *
+ * WHY A STORE (the retryStatusStore / liveQuestionStore pattern): the upstream bridge is a plain
+ * generator with no React/AppState access, while the panel reads `AppState.tasks` — so the bridge
+ * PUBLISHES neutral events here and a sema-owned hook inside chrome-agentprogress.tsx (already mounted
+ * under the footer) SUBSCRIBES and applies them to AppState via registerTask/updateTaskState. CC files
+ * stay verbatim; the AppState write side lives in the sema override that owns the panel.
+ *
+ * WHY THE PANEL (CC-187 parity): a local sync AgentTool renders an inline progress TRAIL from the
+ * subagent's real messages. An engine tick carries ONLY rollup numbers ({toolUses, totalTokens}) — the
+ * exact shape of CC's `AgentProgress` — and CC's own precedent for out-of-process agents (remote agent
+ * tasks) is the TASK PANEL + task-notification, not a synthetic inline trail. Faithful mapping, no
+ * fabricated subagent messages.
+ *
+ * Buffering: ticks published before the panel mounts are buffered (bounded) and replayed to the first
+ * subscriber, so early frames in a fast turn aren't lost to mount timing.
+ */
+// ── #6(frame-lane-matrix)session 常驻行台账 ─────────────────────────────────────────────────
+// 行寿命 ≠ turn 寿命:跨 turn 存活的 bg 子代行(tick 绑不到本 turn 开着的卡 = inert/unbound)不该被
+// turn 末防御 sweep(bridge settlePanelTasks(null) / seamQuery 'sweep' 事件)结成假 completed——一旦
+// 假结,消费端 tick 门(status!=='running' ⇒ return prev)会把后续真 tick 全丢,真终态(failed)也
+// 改不动(冻死)。台账 module-level(publisher=bridge 按绑定活性写;两个 sweep 消费点按它跳过;
+// 真终态通知(task_notification 帧 / enqueueBgChildNotification 合成)settle 时摘除)。
+const residentTaskIds = new Set();
+export function markEnginePanelTaskResident(taskId) {
+    residentTaskIds.add(taskId);
+}
+export function clearEnginePanelTaskResident(taskId) {
+    residentTaskIds.delete(taskId);
+}
+export function isEnginePanelTaskResident(taskId) {
+    return residentTaskIds.has(taskId);
+}
+const MAX_BUFFER = 200;
+let listener = null;
+const buffer = [];
+export function publishEngineAgentPanelEvent(ev) {
+    if (listener) {
+        try {
+            listener(ev);
+        }
+        catch {
+            // A consumer render error must never tear down the bridge's stream drain.
+        }
+        return;
+    }
+    // Buffered (panel not mounted yet / temporarily unmounted). Ticks COALESCE per taskId (only the
+    // latest rollup matters — usage is cumulative), so lifecycle events ('end'/'sweep') are never the
+    // ones squeezed out by a long unmount (adversarial review w0zwpa251 #4: dropping a buffered 'end'
+    // left a row running forever).
+    if (ev.kind === 'tick') {
+        const i = buffer.findIndex(b => b.kind === 'tick' && b.taskId === ev.taskId);
+        if (i >= 0) {
+            buffer[i] = ev;
+            return;
+        }
+    }
+    if (buffer.length < MAX_BUFFER)
+        buffer.push(ev);
+    else if (ev.kind !== 'tick') {
+        // Lifecycle events must survive a full buffer: evict the oldest tick to make room.
+        const i = buffer.findIndex(b => b.kind === 'tick');
+        if (i >= 0)
+            buffer.splice(i, 1);
+        buffer.push(ev);
+    }
+}
+/** Single consumer (the panel hook). Replays any buffered events, returns an unsubscribe. */
+export function subscribeEngineAgentPanel(fn) {
+    listener = fn;
+    if (buffer.length > 0) {
+        const pending = buffer.splice(0, buffer.length);
+        for (const ev of pending) {
+            try {
+                fn(ev);
+            }
+            catch {
+                // ignore — same guard as publish
+            }
+        }
+    }
+    return () => {
+        if (listener === fn)
+            listener = null;
+    };
+}

package/dist/engineCapsCache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineCapsCache.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 **本批刻意不做「三套 caps 缓存收编成一套」**(设计稿 §2.4.1-B 风险点 + census §2.4):收编是
+ * 行为改动,要单独一条测试与单独一批(B1 只搬现行为,不夹带)。selfKnowledge / sideChannel 的
+ * 两套单键探测仍在壳侧,记账给下一批。
+ */
+/**
+ * engineCapsCache — 引擎 /v1/capabilities 的通用 boot-kick 缓存(同步读口)。
+ *
+ * selfKnowledge/sideChannel 各自有单键探测(先行件,语义已钉测试);本模块是后续键的通用面
+ * (首个消费者:compactionModel,[1487]② server 1.243 接线的 cli 半场)。纪律同款:
+ *   · kick 幂等(in-flight 去重),绝不 throw;
+ *   · 判定固化;探测失败不缓存(引擎未起/瞬断 → 下次 kick 再判);
+ *   · 同步读口 boolean(未判 = false = 调用方回落,version-safe)。
+ * 与单键探测不同处:缓存整个 caps 对象(一次探测服务后续所有键),false 不设 TTL——本缓存随
+ * 每次 createLiveConversationClient 构造重 kick(引擎温切重启后新构造自然重探)。
+ */
+/** 构造期 kick(async 幂等);probe = client.capabilities 薄闭包。 */
+export declare function kickEngineCapsProbe(baseUrl: string, probe: () => Promise<unknown>): void;
+/** 同步读口:该 base 的 caps 里 key 是否字面 true(未判/缺键 = false)。 */
+export declare function engineCapTrue(baseUrl: string | undefined, key: string): boolean;
+/**
+ * 同步读口(字符串键):该 base 的 caps 里 key 的字符串值,未判/缺键/非字符串 ⇒ undefined。
+ *
+ * 首个消费者 = `hooksWireCaps` 的 `/goal` CC-Stop 语义判档,它要读 `capabilities.version`
+ * (SDK `Capabilities.version`,server 侧 = `serviceVersion()`,与 `/health.version` 同源)。
+ * 🔴 纪律同 {@link engineCapTrue}:**未判即 undefined**,调用方必须按「探不到 ⇒ 降级」处理 ——
+ * 引擎能力位缺席时任何「假定它有」的分支都是对用户/模型的谎报。
+ */
+export declare function engineCapString(baseUrl: string | undefined, key: string): string | undefined;
+/** 测试钩子。 */
+export declare function __resetEngineCapsCacheForTests(): void;

package/dist/engineCapsCache.js

@@ -0,0 +1,64 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineCapsCache.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 **本批刻意不做「三套 caps 缓存收编成一套」**(设计稿 §2.4.1-B 风险点 + census §2.4):收编是
+ * 行为改动,要单独一条测试与单独一批(B1 只搬现行为,不夹带)。selfKnowledge / sideChannel 的
+ * 两套单键探测仍在壳侧,记账给下一批。
+ */
+/**
+ * engineCapsCache — 引擎 /v1/capabilities 的通用 boot-kick 缓存(同步读口)。
+ *
+ * selfKnowledge/sideChannel 各自有单键探测(先行件,语义已钉测试);本模块是后续键的通用面
+ * (首个消费者:compactionModel,[1487]② server 1.243 接线的 cli 半场)。纪律同款:
+ *   · kick 幂等(in-flight 去重),绝不 throw;
+ *   · 判定固化;探测失败不缓存(引擎未起/瞬断 → 下次 kick 再判);
+ *   · 同步读口 boolean(未判 = false = 调用方回落,version-safe)。
+ * 与单键探测不同处:缓存整个 caps 对象(一次探测服务后续所有键),false 不设 TTL——本缓存随
+ * 每次 createLiveConversationClient 构造重 kick(引擎温切重启后新构造自然重探)。
+ */
+const capsByBase = new Map();
+const inFlight = new Set();
+/** 构造期 kick(async 幂等);probe = client.capabilities 薄闭包。 */
+export function kickEngineCapsProbe(baseUrl, probe) {
+    if (!baseUrl || capsByBase.has(baseUrl) || inFlight.has(baseUrl))
+        return;
+    inFlight.add(baseUrl);
+    void (async () => {
+        try {
+            const caps = await probe();
+            if (caps && typeof caps === 'object') {
+                capsByBase.set(baseUrl, caps);
+            }
+        }
+        catch {
+            // 失败不缓存:下次 kick 再判
+        }
+        finally {
+            inFlight.delete(baseUrl);
+        }
+    })();
+}
+/** 同步读口:该 base 的 caps 里 key 是否字面 true(未判/缺键 = false)。 */
+export function engineCapTrue(baseUrl, key) {
+    if (!baseUrl)
+        return false;
+    return capsByBase.get(baseUrl)?.[key] === true;
+}
+/**
+ * 同步读口(字符串键):该 base 的 caps 里 key 的字符串值,未判/缺键/非字符串 ⇒ undefined。
+ *
+ * 首个消费者 = `hooksWireCaps` 的 `/goal` CC-Stop 语义判档,它要读 `capabilities.version`
+ * (SDK `Capabilities.version`,server 侧 = `serviceVersion()`,与 `/health.version` 同源)。
+ * 🔴 纪律同 {@link engineCapTrue}:**未判即 undefined**,调用方必须按「探不到 ⇒ 降级」处理 ——
+ * 引擎能力位缺席时任何「假定它有」的分支都是对用户/模型的谎报。
+ */
+export function engineCapString(baseUrl, key) {
+    if (!baseUrl)
+        return undefined;
+    const v = capsByBase.get(baseUrl)?.[key];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** 测试钩子。 */
+export function __resetEngineCapsCacheForTests() {
+    capsByBase.clear();
+    inFlight.clear();
+}

package/dist/engineInlineTaskStats.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineInlineTaskStats.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 单实例语义:写方 = bridge 的 task_progress tick,读方 = 行内 group 行的 useSyncExternalStore。
+ */
+/**
+ * engineInlineTaskStats — dep-free side-channel store bridging ENGINE-side subagent progress
+ * (`task_progress` ticks) to the INLINE transcript group row ("Running N agents…" / AgentProgressLine).
+ *
+ * WHY (clay dogfood 2026-07-03): in engine mode the shell AgentTool's call() never runs, so the inline
+ * group row's per-agent stats (tool uses / tokens) and status line — both computed from LOCAL
+ * ProgressMessages (overrides/agent.tsx calculateAgentStats / extractLastToolInfo) — stay frozen at
+ * `0 tool uses` / `Initializing…` for the whole run and after completion. The engine's `task_progress`
+ * ticks DO carry the rollup ({toolUses, totalTokens, durationMs}) and the bridge already binds each
+ * tick to its delegating tool_use card (bindTaskCard, P1② explicit parentToolCallId) — but only fed
+ * the FOOTER panel store. This store is the inline twin: keyed by the delegating tool_use id (cardId),
+ * latest cumulative tick per card, frozen on the card's close (tool_end) / turn-end sweep so the
+ * finished group row keeps the final values.
+ *
+ * Same pattern as engineAgentPanelStore (module-level, no React/AppState deps on the write side); the
+ * read side is a useSyncExternalStore hook inside the sema-owned AgentProgressLine override — a
+ * subscription, NOT a render-time map read, because the memoized transcript tree won't re-render on
+ * 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).
+ */
+export interface EngineInlineTaskStats {
+    /** Cumulative tool uses off the latest tick (frozen at settle). */
+    toolUses: number;
+    /** Cumulative tokens off the latest tick (frozen at settle). */
+    totalTokens: number;
+    /** Cumulative run duration off the latest tick — feeds the "Working…" status line. */
+    durationMs: number;
+    /** core 1.262.0 [558]B (service 1.154.0 wire) — the child's most recent tool intent as ONE human
+     *  line ("Bash npm test"), service-redacted. Replaces the generic "Working…" status line while the
+     *  card is live; absent on old engines ⇒ the status line is unchanged. */
+    currentAction?: string;
+    /** The card closed (tool_end or turn-end sweep): values above are final. */
+    done: boolean;
+    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;
+/** 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). */
+export declare function settleAllEngineInlineTaskStats(): void;
+/** Read side — reference-stable snapshot per card (object replaced only on update). */
+export declare function getEngineInlineTaskStats(cardId: string): EngineInlineTaskStats | undefined;
+/**
+ * Read side, id-less — the SOLE live (un-settled) card's stats, or undefined when 0 or ≥2 are live.
+ *
+ * WHY (#64 B 面 pty 实测,2026-07-11): the SINGLE-card in-flight render path
+ * (overrides/agent.tsx renderToolUseProgressMessage, zero local progressMessages in engine mode)
+ * has NO toolUseID in scope — the CC Tool-interface method signature doesn't carry it, and the
+ * call-site wrapper (AssistantToolUseMessage.tsx) is CC-verbatim. Attribution without an id is only
+ * safe when it is unambiguous, so this returns the stats ONLY when exactly one live card exists
+ * (the adversarial-review posture of bindTaskCard: better honest-generic than bound wrong; with ≥2
+ * live engine subagents the row keeps today's Initializing…). Reference-stable (returns the same
+ * per-card snapshot object the keyed getter hands out).
+ */
+export declare function getSoleLiveEngineInlineTaskStats(): EngineInlineTaskStats | undefined;
+export declare function subscribeEngineInlineTaskStats(fn: () => void): () => void;

package/dist/engineInlineTaskStats.js

@@ -0,0 +1,97 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineInlineTaskStats.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 单实例语义:写方 = bridge 的 task_progress tick,读方 = 行内 group 行的 useSyncExternalStore。
+ */
+/**
+ * engineInlineTaskStats — dep-free side-channel store bridging ENGINE-side subagent progress
+ * (`task_progress` ticks) to the INLINE transcript group row ("Running N agents…" / AgentProgressLine).
+ *
+ * WHY (clay dogfood 2026-07-03): in engine mode the shell AgentTool's call() never runs, so the inline
+ * group row's per-agent stats (tool uses / tokens) and status line — both computed from LOCAL
+ * ProgressMessages (overrides/agent.tsx calculateAgentStats / extractLastToolInfo) — stay frozen at
+ * `0 tool uses` / `Initializing…` for the whole run and after completion. The engine's `task_progress`
+ * ticks DO carry the rollup ({toolUses, totalTokens, durationMs}) and the bridge already binds each
+ * tick to its delegating tool_use card (bindTaskCard, P1② explicit parentToolCallId) — but only fed
+ * the FOOTER panel store. This store is the inline twin: keyed by the delegating tool_use id (cardId),
+ * latest cumulative tick per card, frozen on the card's close (tool_end) / turn-end sweep so the
+ * finished group row keeps the final values.
+ *
+ * Same pattern as engineAgentPanelStore (module-level, no React/AppState deps on the write side); the
+ * read side is a useSyncExternalStore hook inside the sema-owned AgentProgressLine override — a
+ * subscription, NOT a render-time map read, because the memoized transcript tree won't re-render on
+ * 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).
+ */
+const statsByCardId = new Map();
+const listeners = new Set();
+function emit() {
+    for (const fn of listeners) {
+        try {
+            fn();
+        }
+        catch {
+            // a consumer render error must never disturb the bridge's stream drain
+        }
+    }
+}
+/** Bridge write side — latest cumulative tick for the card. No-op once the card settled (frozen finals). */
+export function publishEngineInlineTaskTick(cardId, tick) {
+    const prev = statsByCardId.get(cardId);
+    if (prev?.done)
+        return;
+    statsByCardId.set(cardId, { ...tick, done: false, isError: false });
+    emit();
+}
+/** Bridge write side — the delegating card closed: freeze the finals. Idempotent. */
+export function settleEngineInlineTaskStats(cardId, isError) {
+    const prev = statsByCardId.get(cardId);
+    if (!prev || prev.done)
+        return;
+    statsByCardId.set(cardId, { ...prev, done: true, isError });
+    emit();
+}
+/** Turn-end / abort sweep twin — settle every card still live (a subagent never emits a terminal tick). */
+export function settleAllEngineInlineTaskStats() {
+    let changed = false;
+    for (const [cardId, s] of statsByCardId) {
+        if (s.done)
+            continue;
+        statsByCardId.set(cardId, { ...s, done: true, isError: false });
+        changed = true;
+    }
+    if (changed)
+        emit();
+}
+/** Read side — reference-stable snapshot per card (object replaced only on update). */
+export function getEngineInlineTaskStats(cardId) {
+    return statsByCardId.get(cardId);
+}
+/**
+ * Read side, id-less — the SOLE live (un-settled) card's stats, or undefined when 0 or ≥2 are live.
+ *
+ * WHY (#64 B 面 pty 实测,2026-07-11): the SINGLE-card in-flight render path
+ * (overrides/agent.tsx renderToolUseProgressMessage, zero local progressMessages in engine mode)
+ * has NO toolUseID in scope — the CC Tool-interface method signature doesn't carry it, and the
+ * call-site wrapper (AssistantToolUseMessage.tsx) is CC-verbatim. Attribution without an id is only
+ * safe when it is unambiguous, so this returns the stats ONLY when exactly one live card exists
+ * (the adversarial-review posture of bindTaskCard: better honest-generic than bound wrong; with ≥2
+ * live engine subagents the row keeps today's Initializing…). Reference-stable (returns the same
+ * per-card snapshot object the keyed getter hands out).
+ */
+export function getSoleLiveEngineInlineTaskStats() {
+    let sole;
+    for (const s of statsByCardId.values()) {
+        if (s.done)
+            continue;
+        if (sole !== undefined)
+            return undefined; // ≥2 live — ambiguous, stay honest
+        sole = s;
+    }
+    return sole;
+}
+export function subscribeEngineInlineTaskStats(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}

package/dist/engineToolLabelStore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineToolLabelStore.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ */
+/**
+ * src/sema/engineToolLabelStore.ts — core 工具**展示名**(`tool_start.label` / `tool_end.label`)的
+ * 壳侧侧信道(sema-owned 新文件,零 CC 基座改动)。
+ *
+ * 为什么是侧信道而不是把 label 留在 tool_use block 上(P0-2 的关键判断):
+ *   tool_use content block 会**进壳 transcript**(jsonl 持久 + /compact 时原样直发 provider)。
+ *   Anthropic/OpenAI 两侧对 tool_use block 都是严格形 `{type,id,name,input}`,多一个 `label` 键
+ *   = 400 invalid_request —— 这正是「件1 中断事故批 G」踩过的坑(裸对象 content 落 transcript,
+ *   /compact 直发 ark/volces 400)。所以 bridge 在渲染前把 label 从 block 上摘掉(同
+ *   eventId/parentToolCallId 待遇),存到这里,渲染面按 toolCallId 查。
+ *
+ * 消费面:components/messages/AssistantToolUseMessage.tsx 的 **unknown-tool fallback** ——
+ * 也只在那里消费。已注册工具(壳本地 registry 命中)的卡标题恒走 CC 的 `tool.userFacingName()`,
+ * 绝不被引擎 label 覆盖(CC 逐字对齐优先;core label 与 CC 的 MCP 卡形 `server - tool (MCP)` 不同形,
+ * 覆盖 = 制造分叉)。
+ *
+ * 今天的真实命中面(2026-07-26 直连钉版 core 1.416 实测):core 只在 `label !== name` 时才上 wire
+ * (runtask.js:1406),而唯一这样的一族是 **MCP 远端工具** —— `name = mcp__<server>__<tool>`、
+ * `label = <server>:<tool>`(core/mcp.js:902)。即:引擎侧连着、壳侧没连的那台 MCP server 的工具,
+ * 修前卡头是裸 `mcp__foo__bar`,修后是 core 的展示名 `foo:bar`。
+ *
+ * 生命周期:按 toolCallId 键的有界 Map(FIFO 淘汰),纯 chrome 数据,不持久、不回喂模型。
+ */
+/** 登记一个 tool call 的 core 展示名(空/非串忽略)。 */
+export declare function recordEngineToolLabel(toolCallId: unknown, label: unknown): void;
+/** 读一个 tool call 的 core 展示名(未登记 ⇒ undefined,调用方回落原有形状)。 */
+export declare function engineToolLabel(toolCallId: unknown): string | undefined;
+/** 测试用:清空台账。 */
+export declare function resetEngineToolLabels(): void;

package/dist/engineToolLabelStore.js

@@ -0,0 +1,55 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineToolLabelStore.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ */
+/**
+ * src/sema/engineToolLabelStore.ts — core 工具**展示名**(`tool_start.label` / `tool_end.label`)的
+ * 壳侧侧信道(sema-owned 新文件,零 CC 基座改动)。
+ *
+ * 为什么是侧信道而不是把 label 留在 tool_use block 上(P0-2 的关键判断):
+ *   tool_use content block 会**进壳 transcript**(jsonl 持久 + /compact 时原样直发 provider)。
+ *   Anthropic/OpenAI 两侧对 tool_use block 都是严格形 `{type,id,name,input}`,多一个 `label` 键
+ *   = 400 invalid_request —— 这正是「件1 中断事故批 G」踩过的坑(裸对象 content 落 transcript,
+ *   /compact 直发 ark/volces 400)。所以 bridge 在渲染前把 label 从 block 上摘掉(同
+ *   eventId/parentToolCallId 待遇),存到这里,渲染面按 toolCallId 查。
+ *
+ * 消费面:components/messages/AssistantToolUseMessage.tsx 的 **unknown-tool fallback** ——
+ * 也只在那里消费。已注册工具(壳本地 registry 命中)的卡标题恒走 CC 的 `tool.userFacingName()`,
+ * 绝不被引擎 label 覆盖(CC 逐字对齐优先;core label 与 CC 的 MCP 卡形 `server - tool (MCP)` 不同形,
+ * 覆盖 = 制造分叉)。
+ *
+ * 今天的真实命中面(2026-07-26 直连钉版 core 1.416 实测):core 只在 `label !== name` 时才上 wire
+ * (runtask.js:1406),而唯一这样的一族是 **MCP 远端工具** —— `name = mcp__<server>__<tool>`、
+ * `label = <server>:<tool>`(core/mcp.js:902)。即:引擎侧连着、壳侧没连的那台 MCP server 的工具,
+ * 修前卡头是裸 `mcp__foo__bar`,修后是 core 的展示名 `foo:bar`。
+ *
+ * 生命周期:按 toolCallId 键的有界 Map(FIFO 淘汰),纯 chrome 数据,不持久、不回喂模型。
+ */
+/** 上界:一个长会话里 tool call 无限增长,标签只是渲染辅助,超界按 FIFO 淘汰最旧的。 */
+const MAX_ENTRIES = 500;
+const labels = new Map();
+/** 登记一个 tool call 的 core 展示名(空/非串忽略)。 */
+export function recordEngineToolLabel(toolCallId, label) {
+    if (typeof toolCallId !== 'string' || toolCallId.length === 0)
+        return;
+    if (typeof label !== 'string' || label.trim().length === 0)
+        return;
+    // 已有值不覆盖:tool_start 先到,tool_end 只是补位(两者同源同值)。
+    if (labels.has(toolCallId))
+        return;
+    if (labels.size >= MAX_ENTRIES) {
+        const oldest = labels.keys().next();
+        if (!oldest.done)
+            labels.delete(oldest.value);
+    }
+    labels.set(toolCallId, label.trim());
+}
+/** 读一个 tool call 的 core 展示名(未登记 ⇒ undefined,调用方回落原有形状)。 */
+export function engineToolLabel(toolCallId) {
+    if (typeof toolCallId !== 'string' || toolCallId.length === 0)
+        return undefined;
+    return labels.get(toolCallId);
+}
+/** 测试用:清空台账。 */
+export function resetEngineToolLabels() {
+    labels.clear();
+}

package/dist/fleetAgentPanelProjection.d.ts

@@ -0,0 +1,31 @@
+/** 行帧投影后的最小 agent 行形(fleet-tree 的 FleetTask 是它的超集)。 */
+export interface FleetAgentRowLike {
+    id: string;
+    /** fleet 行 label 列 = agent identity(agentName ?? agentType),如 'fork'。 */
+    name?: string;
+    /** fleet 行描述列 = 任务描述,如 'alpha-probe'(面板行 label 用它)。 */
+    description?: string;
+    status?: string;
+    tokens?: number;
+    /** server 1.278.0 `toolUses` —— 子代**累计**工具调用数。🔴 三态:有键真值(含真 0)/无键
+     *  `undefined`=老引擎不知道。绝不在本层 `?? 0`(那等于把「不知道」冒充成「跑了 0 个」)。 */
+    toolUses?: number;
+    /** server 1.278.0 `transcriptId`(子代 childSessionId)—— 委派 prompt 的取件锚,不是 prompt 本身。 */
+    transcriptId?: string;
+    /** server 1.288.0 / core 1.429.0([1831]②)—— 子代当前工具的结构化形。缺席=旧端或从未跑过工具。 */
+    currentTool?: {
+        toolName: string;
+        target?: string;
+    };
+}
+/** 行从投影集消失多久之后按 completed 兜底 settle(重连空窗 / snapshot 清表远小于此)。 */
+export declare const ABSENT_SETTLE_MS = 30000;
+/** 测试钩:清投影台账。 */
+export declare function resetFleetAgentPanelProjection(): void;
+/** 台账读面(测试/诊断):当前记着的行数。 */
+export declare function fleetAgentProjectionSize(): number;
+/**
+ * 把一次 fleet 投影(已经过 own 判别 + workflow belt 的 FleetTask[])喂给面板事件流。
+ * 幂等、无副作用地重复调用安全 —— 每秒被 footer 调用两次就是常态。
+ */
+export declare function projectFleetAgentRows(rows: readonly FleetAgentRowLike[], nowMs?: number): void;

package/dist/fleetTaskDesc.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/fleetTaskDesc.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ */
+/**
+ * src/sema/fleetTaskDesc.ts — footer fleet 行「label/描述列」纯投影助手(零依赖,从 fleetClient.ts 提出
+ * 供单测直取——fleetClient 拖 SDK/appState/notification 重图,无法轻量 bundle;行为与提出前逐字同源)。
+ */
+/** collapse a wire label to a single trimmed line (drops embedded newlines/runs). 187 row labels are always
+ *  one short line; the <FleetTree/> column (Math.min(28,…) + wrap="truncate") does the visible ellipsis, so we
+ *  only normalize here — no double-ellipsis, faithful to the 187 render. */
+export declare function collapseLabel(s: string): string;
+/** CC row-body fallback(CC 真身锚 2026-07-20 人类剧本帧:`◯ general-purpose  t1calc`——row body 从第一帧
+ *  起就是 Agent 工具的 description)。引擎子行帧不带 `description` 字段,任务描述只在 `name` 里,且有两形
+ *  (07-24 D2 wire 实证,engine 1.271.0 帧 dump):
+ *    ① 出生帧:name = `${agentType}: ${description}` 合成形(如 "fork: t1calc")→ 剥前缀复原;
+ *    ② 后续帧:引擎把 name 重写为【裸任务描述】(如 "t1calc",无前缀)→ 直接按描述投影——
+ *      修前只认①,②一到描述列即塌空(footer 只剩 `◯ fork`,D2 症状)。
+ *  防重复列 belt:裸 name 恰为 identity 回声(=agentType 或 =agentName)时不当描述(label 列已渲它)。
+ *  纯投影非双源;真进度(last tool name)到帧后仍然优先(调用侧 projectDescription 先行)。 */
+export declare function taskDescFromName(name: string | undefined, agentType: string | undefined, agentName?: string): string;

package/dist/fleetTaskDesc.js

@@ -0,0 +1,35 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/fleetTaskDesc.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ */
+/**
+ * src/sema/fleetTaskDesc.ts — footer fleet 行「label/描述列」纯投影助手(零依赖,从 fleetClient.ts 提出
+ * 供单测直取——fleetClient 拖 SDK/appState/notification 重图,无法轻量 bundle;行为与提出前逐字同源)。
+ */
+/** collapse a wire label to a single trimmed line (drops embedded newlines/runs). 187 row labels are always
+ *  one short line; the <FleetTree/> column (Math.min(28,…) + wrap="truncate") does the visible ellipsis, so we
+ *  only normalize here — no double-ellipsis, faithful to the 187 render. */
+export function collapseLabel(s) {
+    return s.replace(/\s+/g, ' ').trim();
+}
+/** CC row-body fallback(CC 真身锚 2026-07-20 人类剧本帧:`◯ general-purpose  t1calc`——row body 从第一帧
+ *  起就是 Agent 工具的 description)。引擎子行帧不带 `description` 字段,任务描述只在 `name` 里,且有两形
+ *  (07-24 D2 wire 实证,engine 1.271.0 帧 dump):
+ *    ① 出生帧:name = `${agentType}: ${description}` 合成形(如 "fork: t1calc")→ 剥前缀复原;
+ *    ② 后续帧:引擎把 name 重写为【裸任务描述】(如 "t1calc",无前缀)→ 直接按描述投影——
+ *      修前只认①,②一到描述列即塌空(footer 只剩 `◯ fork`,D2 症状)。
+ *  防重复列 belt:裸 name 恰为 identity 回声(=agentType 或 =agentName)时不当描述(label 列已渲它)。
+ *  纯投影非双源;真进度(last tool name)到帧后仍然优先(调用侧 projectDescription 先行)。 */
+export function taskDescFromName(name, agentType, agentName) {
+    if (!name || !agentType)
+        return '';
+    const prefix = `${agentType}: `;
+    if (name.startsWith(prefix))
+        return collapseLabel(name.slice(prefix.length));
+    const collapsed = collapseLabel(name);
+    if (collapsed &&
+        collapsed !== collapseLabel(agentType) &&
+        collapsed !== collapseLabel(agentName ?? '')) {
+        return collapsed;
+    }
+    return '';
+}