@sema-agent/client-core 0.7.0 → 0.8.1

package/dist/subagent/engineSubagentOutput.js

@@ -0,0 +1,98 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineSubagentOutput.ts` 整搬。
+ *
+ * 🔴 搬迁三处差分(全部是「端资产上移到 port」,行为一字节不变):
+ *   · `wireConfig()`(六份手抄之一)→ `engineWireTarget()`;
+ *   · `getActiveEngineTaskId()`(engineToolDetach,pty 绑定的活跃 run)→ `activeEngineRunId()`
+ *     (SessionPort.activeRunId);
+ *   · `logForDebugging` → `hostLog('debug', …)`。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * engineSubagentOutput — 后台子代终报读面消费(server 1.244 / SDK 0.0.65 提货,提货单 [1488]③(b))。
+ *
+ * Wire: `GET /v1/runs/:runId/subagents/:handle/output` → {taskId, target, content, output:{status,…}}
+ *   · content = 子代最终 assistant 正文(终态)或诚实 running 状态文本;
+ *   · runId = spawn 该子代的 run(registry access 从 run 行推导——寻址映射由 fleet 行 parentId /
+ *     bg_notification.parentTaskId 喂 subagentContentStore.recordBgParentRun);
+ *   · a… 域(background_agent)专用——wa… 观测行恒 404(workflow journal 是那边的读面),调用方
+ *     按 null 回落 bg 事实渲染,fail-soft;
+ *   · caps 探测 capabilities.subagentOutput(selfKnowledge caps 同款纪律:true 固化/false TTL/
+ *     探测失败不缓存)。老引擎(<1.244)= caps 无该键 → 恒走回落,version-safe。
+ *
+ * 副本域注意([1491]④):TaskRegistry 是进程内存态——引擎重启后 handle 消失(404),按 null 回落,
+ * 绝不把 404 当异常上抛。
+ *
+ * session 作用域([1498]③,server 1.245.0 / SDK 0.0.66):session-bound run 的 subagentOutput
+ * 必须带匹配的 `?session=`,否则 404 fail-closed(这个读面正是 [1493]② 双开串扰的读侧入口,
+ * server 侧已把它闩死)。端无条件带 session 即双版本兼容——1.244 忽略该参数,1.245 起必需。
+ * 🔴 端漏装 SessionPort ⇒ `engineSessionParam()` 恒 undefined ⇒ 本读面对 session-bound run
+ * 一律 404 ⇒ 整条子代终报静默哑掉(所以 `hostSession()` 计 miss,见 host.ts)。
+ */
+import { hostLog } from '../host.js';
+import { makeEngineWireClient } from '../engineWireSdk.js';
+import { engineWireTarget } from '../engineWireTarget.js';
+import { getBgParentRun } from '../subagentContentStore.js';
+import { activeEngineRunId, engineSessionParam } from '../engineSessionParam.js';
+// ── caps 探测(true 固化 / false TTL / 失败不缓存)────────────────────────────────────────────
+const capByBase = new Map();
+const CAP_FALSE_RETRY_TTL_MS = 5 * 60_000;
+async function subagentOutputCapable(client, baseUrl, signal) {
+    const hit = capByBase.get(baseUrl);
+    if (hit && (hit.ok || Date.now() - hit.at < CAP_FALSE_RETRY_TTL_MS))
+        return hit.ok;
+    try {
+        // SDK 0.0.77 起 capabilities() 有真型(Capabilities 开集)——宽形 cast 已撤;键仍防御读。
+        const caps = await client.capabilities({ ...(signal ? { signal } : {}) });
+        const ok = caps.subagentOutput === true;
+        capByBase.set(baseUrl, { ok, at: Date.now() });
+        return ok;
+    }
+    catch {
+        return false; // 探测失败不缓存(引擎瞬断):本次回落,下次再判
+    }
+}
+/** 测试钩:清 caps 缓存。 */
+export function __resetSubagentOutputCapCacheForTests() {
+    capByBase.clear();
+}
+/**
+ * 拉取一个后台子代的终报正文。null = 读不到(无 wire / caps 缺 / 404 域外或副本重启 / 网错)——
+ * 调用方回落 bg 事实渲染。绝不 throw。
+ */
+export async function fetchEngineSubagentReport(taskId, opts) {
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return null;
+    const runId = getBgParentRun(taskId) ?? activeEngineRunId();
+    if (!runId)
+        return null;
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return null;
+    if (!(await subagentOutputCapable(client, cfg.baseUrl, opts?.signal)))
+        return null;
+    try {
+        // [1498]③:无条件带 session(1.244 忽略/1.245 必需,双版本兼容);缺席时(端未装 SessionPort /
+        // 端自己还没有值)不带——1.245 对 session-bound run 会 404,按既有 null 回落,下次重试自然带上。
+        const session = engineSessionParam();
+        const r = await client.runs.subagentOutput(runId, taskId, {
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+            ...(session ? { session } : {}),
+        });
+        const content = typeof r?.content === 'string' ? r.content : '';
+        if (!content.trim())
+            return null;
+        const status = typeof r?.output?.status === 'string' ? r.output.status : undefined;
+        return { content, ...(status !== undefined ? { status } : {}) };
+    }
+    catch (e) {
+        const status = e?.status;
+        hostLog('debug', `[subagent-output] ${taskId} via run ${runId}: ${typeof status === 'number' ? status : String(e).slice(0, 160)}`);
+        return null;
+    }
+}

package/dist/subagent/engineSubagentSteer.d.ts

@@ -0,0 +1,10 @@
+export type SubagentSteerOutcome = {
+    ok: true;
+    receipt: string;
+} | {
+    ok: false;
+    reason: 'no-wire' | 'no-run' | 'not-running' | 'error';
+    detail?: string;
+};
+/** Steer a running engine subagent (target = its parentToolCallId, or agentName). */
+export declare function steerEngineSubagent(target: string, text: string): Promise<SubagentSteerOutcome>;

package/dist/subagent/engineSubagentSteer.js

@@ -0,0 +1,68 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineSubagentSteer.ts` 整搬。
+ *
+ * 🔴 搬迁三处差分(端资产上移到 port,行为一字节不变):`wireConfig()`(六份手抄之一,而且
+ *    **这一份的 token 读法与另外五份不同步** —— 收编前它是 `token: process.env.SEMA_LIVE_TOKEN`
+ *    直挂而非 `...(cfg.token ? … )` spread,漂移已实际发生)→ `engineWireTarget()`;
+ *    `getActiveEngineTaskId()` → `activeEngineRunId()`;`logForDebugging` → `hostLog`。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * engineSubagentSteer — C2 (service 1.89): direct steer to a RUNNING engine subagent.
+ *
+ * Wire: `POST /v1/runs/:runId/subagents/:target/steer` (SubagentSteerRegistry, three-legged onSubagentSpawn;
+ * target = parentToolCallId or agentName — the client always has the parentToolCallId from the diverted C1
+ * content events / progress binding). SDK 宪法迁移批:SDK 0.0.52 有 runs.steerSubagent verb(同 wire 同
+ * encodeURIComponent 同 body {content}),raw fetch 退役 —— 改走 engineWireSdk 工厂 client;auth
+ * (Bearer SEMA_LIVE_TOKEN)+ x-agent-principal(owner-gated route — must match the run's stamped
+ * principal)姿势 = Transport buildHeaders,与原手抄同三头。
+ *
+ * Semantics (CC AGe parity): the message drains at the subagent's next tool round; the service echoes CC's
+ * verbatim receipt "Message queued for delivery…". 409 = subagent not running (settled/unknown) — surfaced
+ * honestly so the caller can fall back (steer the lead) or tell the user the agent already ended.
+ * 迁移差分记账:原 raw POST 无超时 → SDK 缺省 60s 上界(steer 是入队即回的 verb,纯上界改善);
+ * 'not-running' 的 detail 从「响应体原文」→「APIError.message(server body.error 原文)」——该 detail
+ * 只进 debug 日志(REPL 对 not-running 显示固定文案),error 形语义不劣化。
+ */
+import { hostLog } from '../host.js';
+import { makeEngineWireClient } from '../engineWireSdk.js';
+import { engineWireTarget } from '../engineWireTarget.js';
+import { activeEngineRunId, engineSessionParamSpread } from '../engineSessionParam.js';
+/** Steer a running engine subagent (target = its parentToolCallId, or agentName). */
+export async function steerEngineSubagent(target, text) {
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return { ok: false, reason: 'no-wire' };
+    const runId = activeEngineRunId();
+    if (!runId)
+        return { ok: false, reason: 'no-run' };
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return { ok: false, reason: 'no-wire' };
+    try {
+        // service 1.89 receipt shape: { note: "Message queued for delivery to <name> …", delivery, … }
+        const body = await client.runs.steerSubagent(runId, target, { content: text }, engineSessionParamSpread());
+        let receipt = 'Message queued for delivery at the next tool round.';
+        const copy = body?.note ?? body?.message;
+        if (typeof copy === 'string' && copy.length > 0)
+            receipt = copy;
+        return { ok: true, receipt };
+    }
+    catch (e) {
+        const status = e?.status;
+        if (typeof status === 'number') {
+            const detail = e instanceof Error ? e.message : String(e);
+            hostLog('debug', `engineSubagentSteer: ${status} ${detail.slice(0, 200)}`);
+            if (status === 409 || status === 404) {
+                return { ok: false, reason: 'not-running', detail };
+            }
+            return { ok: false, reason: 'error', detail: `${status}` };
+        }
+        hostLog('debug', `engineSubagentSteer: fetch failed ${String(e)}`);
+        return { ok: false, reason: 'error', detail: String(e) };
+    }
+}

package/dist/subagent/engineSubagentTail.d.ts

@@ -0,0 +1,40 @@
+/** 测试钩:清 caps 缓存。 */
+export declare function __resetSubagentStreamCapCacheForTests(): void;
+/**
+ * 一次子代工具活动(详情页 `Progress` 段的数据面,CC 2.1.220 `Zja` 的 recentActivities)。
+ *
+ * 🔴 `toolName` 必须是**真工具名**、`args` 必须是**真参数** —— 端的 `renderToolActivity` 拿
+ * `toolName` 去工具注册表查、再用工具自己的 `userFacingName(input)` 渲染。把 `currentAction`
+ * 那类自由文本塞进 `toolName` 只会走 `!tool` 回落分支把原文吐出来,是「看起来能显示」的假绑定。
+ * 自由文本只能进 `activityDescription` 展示位。
+ */
+export interface SubagentActivity {
+    taskId: string;
+    toolName: string;
+    /** `tool_start.args` 原样(非对象由端归一;端会拿它过工具 schema 的 safeParse)。 */
+    args: unknown;
+    /** UNTRUSTED 展示文本(server 已 redact+bound);绝不冒充结构化 args。 */
+    activityDescription?: string;
+}
+/** 端装的活动落点(执行半场)。不装 ⇒ Progress 段无数据(不是错误态,只是该面不启用)。 */
+export type SubagentActivitySink = (a: SubagentActivity) => void;
+/** 装/卸 Progress 段落点。传 null 卸。返回还原函数。 */
+export declare function installSubagentActivitySink(sink: SubagentActivitySink | null): () => void;
+/** tool_end.output 经 server redactDeep,原型不保 string——渲染面统一字符串化(对象走 JSON)。 */
+export declare function coerceOutput(v: unknown): string | undefined;
+/**
+ * tail 是否正对该行开着 —— **两源互斥判别口**(行帧 `currentTool` 臂在 tail 活跃时让位:
+ * tail 的 tool_start 带真 args,渲染更细;两源同录 = 每步双行)。
+ */
+export declare function isEngineSubagentTailActive(taskId: string): boolean;
+/**
+ * 打开一个后台子代的 live tail(幂等:已开着的同 id 直接返回)。内容帧进 subagentContentStore,
+ * 渲染由既有 C1 notify 链接管。绝不 throw;开不了(无 wire/caps 缺/寻址失败)= 静默维持现状。
+ */
+export declare function tailEngineSubagent(taskId: string): void;
+/** 关闭一个子代的 tail(幂等;查看态退出/终态/行消失时调)。 */
+export declare function stopEngineSubagentTail(taskId: string): void;
+/** 在飞判别([1543]① 重开路用):true = 该子代已有 tail 挂着。 */
+export declare function hasActiveSubagentTail(taskId: string): boolean;
+/** 测试钩:在飞 tail 数。 */
+export declare function __activeTailCountForTests(): number;

package/dist/subagent/engineSubagentTail.js

@@ -0,0 +1,241 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineSubagentTail.ts` 的**流消费半场**。
+ *
+ * ── 拆缝(T35/T36/T44 同一条原则:判定半场进包、执行半场留宿主)────────────────────────────────
+ * **进包**:caps 探测 · tail 台账(每 taskId 至多一条)· SSE 消费循环 · 帧 → subagentContentStore
+ *   的四条投影 · `coerceOutput` · settle 收口 · 诊断锚 · 两源互斥判别口 `isEngineSubagentTailActive`。
+ * **留宿主**:`recordSubagentActivity` / `recordFleetCurrentTool` 里对
+ *   `AppState.tasks[taskId].progress.recentActivities` 的读改写 —— 那是**端的任务状态形状**
+ *   (`LocalAgentTaskState` / `ToolActivity`),web/桌面各有各的形。
+ *   本包改为在 `tool_start` 上调 `SubagentActivitySink`(下面的可装口),壳侧 shim 装一个
+ *   把原 `recordSubagentActivity` 逐字搬过去的 sink ⇒ 行为一字节不变。
+ *
+ * 🔴 单实例纪律:`activeTails` 是 module 级 Map。写者 = 本文件;读者 = **两源互斥判别**
+ *   (行帧 `currentTool` 臂在 tail 活跃时必须让位)与查看态 watcher 的「重开」判别。
+ *   两份实例 ⇒ 让位判别恒读 false ⇒ tail 与行帧两源同时录 Progress 段 = 每步双行
+ *   ([new-data-source-systemic-checks]「两臂共写台账要整臂让位」)。
+ *
+ * 🔴 搬迁差分:`wireConfig()`(六份手抄的第六份,至此**全部收编**)→ `engineWireTarget()`;
+ *   `getActiveEngineTaskId()` → `activeEngineRunId()`;`logForDebugging` → `hostLog`。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * engineSubagentTail — 后台子代 live tail(A2,server 1.251 subagentStream 提货;1.253 起
+ * probe→subscribe 竞态已修([1524] HIGH-2 → [1526] 即修),接线以 1.253+ 为期望域)。
+ *
+ * Wire: `GET /v1/runs/:runId/subagents/:handle/stream`(SSE)——SDK runs.subagentStream 消费:
+ *   · `event: meta`  {version:1, runId, target, status, seq?, …}:status 非 running/pending 时
+ *     server 立即收流(终态无 tail,回放面=subagentOutput);
+ *   · `event: forward` = projectTailFrame 投影帧:text_delta/reasoning_delta {delta,…}、
+ *     tool_start {toolCallId,toolName,args,label?}、tool_end {toolCallId,toolName,isError,output?}、
+ *     task_progress {…}(rollup,面板已有 task_progress 腿,这里不重复消费)、
+ *     task_settled {taskId,status,seq?,summary?} = 收口帧(server 随即 end);
+ *   · `event: heartbeat` {} 每 15s(连接活性由 server 保障,端侧无需 idle timer)。
+ *
+ * 消费面:帧 → subagentContentStore.publishSubagentContentEvent(C1 同一 store)——既有
+ * notify→重组链零改动接管渲染;running 查看态的「live transcript pending engine wire」占位行在
+ * 首个内容项落地时自然消失。
+ *
+ * 防双注入:task_settled → settleSubagentContent(flush 流式尾巴)后关流;终报正文不从
+ * tail 合成——终态渲染仍走既有 subagentOutput 读面 / bg 事实臂,臂序(content prefix → report)
+ * 保证两面不重复。
+ *
+ * 生命周期:查看态进入开,退出/终态/行消失关;每 taskId 至多一条(幂等);caps 探测
+ * capabilities.subagentStream(true 固化/false TTL/失败不缓存,engineSubagentOutput 同纪律);
+ * 寻址 runId=getBgParentRun ?? 活跃 run、无条件带 `?session=`(同 [1498]③ 纪律)。
+ * 一切失败 fail-soft:tail 断=回到占位行现状,绝不 throw。
+ */
+import { hostLog } from '../host.js';
+import { makeEngineWireClient } from '../engineWireSdk.js';
+import { engineWireTarget } from '../engineWireTarget.js';
+import { activeEngineRunId, engineSessionParam } from '../engineSessionParam.js';
+import { getBgParentRun, parentToolCallIdOf, publishSubagentContentEvent, settleSubagentContent, } from '../subagentContentStore.js';
+// ── caps 探测(true 固化 / false TTL / 失败不缓存)────────────────────────────────────────────
+const capByBase = new Map();
+const CAP_FALSE_RETRY_TTL_MS = 5 * 60_000;
+async function subagentStreamCapable(client, baseUrl, signal) {
+    const hit = capByBase.get(baseUrl);
+    if (hit && (hit.ok || Date.now() - hit.at < CAP_FALSE_RETRY_TTL_MS))
+        return hit.ok;
+    try {
+        // SDK 0.0.77 起 capabilities() 有真型(Capabilities 开集)——宽形 cast 已撤;键仍防御读。
+        const caps = await client.capabilities({ ...(signal ? { signal } : {}) });
+        const ok = caps.subagentStream === true;
+        capByBase.set(baseUrl, { ok, at: Date.now() });
+        return ok;
+    }
+    catch {
+        return false; // 探测失败不缓存(引擎瞬断):本次不开,下次再判
+    }
+}
+/** 测试钩:清 caps 缓存。 */
+export function __resetSubagentStreamCapCacheForTests() {
+    capByBase.clear();
+}
+// ── tail 台账(每 taskId 至多一条)──────────────────────────────────────────────────────────────
+const activeTails = new Map();
+let activitySink = null;
+/** 装/卸 Progress 段落点。传 null 卸。返回还原函数。 */
+export function installSubagentActivitySink(sink) {
+    const prev = activitySink;
+    activitySink = sink;
+    return () => {
+        activitySink = prev;
+    };
+}
+/** tool_end.output 经 server redactDeep,原型不保 string——渲染面统一字符串化(对象走 JSON)。 */
+export function coerceOutput(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v === 'string')
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+/**
+ * tail 是否正对该行开着 —— **两源互斥判别口**(行帧 `currentTool` 臂在 tail 活跃时让位:
+ * tail 的 tool_start 带真 args,渲染更细;两源同录 = 每步双行)。
+ */
+export function isEngineSubagentTailActive(taskId) {
+    return activeTails.has(taskId);
+}
+/**
+ * 打开一个后台子代的 live tail(幂等:已开着的同 id 直接返回)。内容帧进 subagentContentStore,
+ * 渲染由既有 C1 notify 链接管。绝不 throw;开不了(无 wire/caps 缺/寻址失败)= 静默维持现状。
+ */
+export function tailEngineSubagent(taskId) {
+    if (activeTails.has(taskId))
+        return;
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return;
+    const runId = getBgParentRun(taskId) ?? activeEngineRunId();
+    if (!runId)
+        return;
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return;
+    const ac = new AbortController();
+    activeTails.set(taskId, ac);
+    // [1568] 诊断锚(SEMA_DEBUG 才落盘,量有界:每条 tail 一行首帧 + 一行收尾统计)——查看态
+    // 「慢/稀疏」类报障必须能把【数据面到端】与【端渲染】分层归因,首帧时延是那条分界线。
+    const openedAt = Date.now();
+    let frames = 0;
+    let connectLogged = false;
+    let firstContentLogged = false;
+    void (async () => {
+        try {
+            if (!(await subagentStreamCapable(client, cfg.baseUrl, ac.signal)))
+                return;
+            const session = engineSessionParam();
+            // SDK 0.0.77 起 runs.subagentStream 有真型([1547]① 候发版即消费兑现)——宽形 cast 已撤。
+            const stream = client.runs.subagentStream(runId, taskId, {
+                signal: ac.signal,
+                ...(session ? { session } : {}),
+            });
+            hostLog('debug', `[subagent-tail] open ${taskId} via run ${runId}`);
+            const parentKey = () => parentToolCallIdOf(taskId) ?? taskId;
+            for await (const ev of stream) {
+                if (ac.signal.aborted)
+                    break;
+                if (!connectLogged) {
+                    connectLogged = true;
+                    // 连接分界线:meta 帧即到 = SSE 建连成功(与「子代此刻恰好在跑长工具、没内容可发」区分开)
+                    hostLog('debug', `[subagent-tail] ${taskId} stream connected +${Date.now() - openedAt}ms`);
+                }
+                if (ev.event !== 'forward')
+                    continue; // meta/heartbeat:连接语义帧,不进内容面
+                const d = ev.data;
+                const t = d.type;
+                frames += 1;
+                if (!firstContentLogged &&
+                    (t === 'text_delta' || t === 'reasoning_delta' || t === 'tool_start')) {
+                    firstContentLogged = true;
+                    hostLog('debug', `[subagent-tail] ${taskId} first content frame +${Date.now() - openedAt}ms (${String(t)})`);
+                }
+                if (t === 'text_delta' || t === 'reasoning_delta') {
+                    if (typeof d.delta === 'string' && d.delta.length > 0) {
+                        publishSubagentContentEvent({
+                            type: t,
+                            taskId,
+                            parentToolCallId: parentKey(),
+                            delta: d.delta,
+                        });
+                    }
+                }
+                else if (t === 'tool_start') {
+                    publishSubagentContentEvent({
+                        type: 'tool_start',
+                        taskId,
+                        parentToolCallId: parentKey(),
+                        ...(typeof d.toolCallId === 'string' ? { toolCallId: d.toolCallId } : {}),
+                        ...(typeof d.toolName === 'string' ? { toolName: d.toolName } : {}),
+                        args: d.args,
+                    });
+                    // 详情页 `Progress` 段的数据面(执行半场在端,见 SubagentActivitySink)。
+                    // 只有真拿到工具名才记 —— 无名帧不编。
+                    if (typeof d.toolName === 'string' && d.toolName.length > 0) {
+                        activitySink?.({ taskId, toolName: d.toolName, args: d.args });
+                    }
+                }
+                else if (t === 'tool_end') {
+                    const out = coerceOutput(d.output);
+                    publishSubagentContentEvent({
+                        type: 'tool_end',
+                        taskId,
+                        parentToolCallId: parentKey(),
+                        ...(typeof d.toolCallId === 'string' ? { toolCallId: d.toolCallId } : {}),
+                        ...(typeof d.toolName === 'string' ? { toolName: d.toolName } : {}),
+                        ...(out !== undefined ? { output: out } : {}),
+                        ...(d.isError === true ? { isError: true } : {}),
+                    });
+                }
+                else if (t === 'task_settled') {
+                    // 收口:flush 流式尾巴;终报/结局事实由既有 hydrate/bg 事实臂渲染,不从 tail 合成。
+                    // [1543]①:seq 骑帧(core 1.373 UnifiedTaskOutput.seq;1.377 起 live 臂同键全域投影,
+                    // [1548]——settle 世代口径 spawn=1/复活承袭 claim 周期号)——≥2 = 复活周期(S3c revive)
+                    // 的 settle。tail 台账按周期关流;重开由查看态 watcher 兜(viewing 行回 running 且无
+                    // 在飞 tail 即重开,revive/断线同一恢复路)。
+                    settleSubagentContent(taskId);
+                    hostLog('debug', `[subagent-tail] ${taskId} settled (${String(d.status)}${typeof d.seq === 'number' ? ` seq=${d.seq}` : ''}${typeof d.summary === 'string' ? ` summary=${d.summary.slice(0, 80)}` : ''}) — close`);
+                    break;
+                }
+                // task_progress:面板 rollup 已有独立腿,这里不重复消费
+            }
+        }
+        catch (e) {
+            if (!ac.signal.aborted) {
+                hostLog('debug', `[subagent-tail] ${taskId} torn: ${String(e).slice(0, 160)}`);
+            }
+        }
+        finally {
+            hostLog('debug', `[subagent-tail] ${taskId} closed after ${frames} content frame(s)`);
+            if (activeTails.get(taskId) === ac)
+                activeTails.delete(taskId);
+        }
+    })();
+}
+/** 关闭一个子代的 tail(幂等;查看态退出/终态/行消失时调)。 */
+export function stopEngineSubagentTail(taskId) {
+    const ac = activeTails.get(taskId);
+    if (!ac)
+        return;
+    activeTails.delete(taskId);
+    ac.abort();
+}
+/** 在飞判别([1543]① 重开路用):true = 该子代已有 tail 挂着。 */
+export function hasActiveSubagentTail(taskId) {
+    return activeTails.has(taskId);
+}
+/** 测试钩:在飞 tail 数。 */
+export function __activeTailCountForTests() {
+    return activeTails.size;
+}

package/dist/subagent/engineTaskHandleWire.d.ts

@@ -0,0 +1,89 @@
+export interface EngineTaskOutputResult {
+    /** 累积后的输出正文(游标两形兼容,见头注)。 */
+    content: string;
+    /** wire output 投影原样的常用位(UI 一律以这些 flags 为准,别解析 content 猜状态)。 */
+    status?: string;
+    stoppedBy?: string;
+    partialResult?: boolean;
+}
+/** 测试钩:清累积缓存。 */
+export declare function __resetTaskHandleWireForTests(): void;
+/**
+ * 读一个引擎侧任务句柄的输出(新面 A)。null = 读不到(无 wire / caps 缺 / 无宿主 run / 404
+ * 域外或已 reap / 网错)——调用方回落既有渲染(receipt/outputFile tail)。绝不 throw。
+ */
+export declare function fetchEngineTaskOutput(handle: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<EngineTaskOutputResult | null>;
+/**
+ * [1505] 契约标记判别(头注):spool 全量 → 替换;cursor 增量 → append;无标记 → 保守
+ * append-if-changed(与上次逐字节相同视为幂等重读,不重复)。空 content 不动累积。
+ * 🔴 B6 提出成具名纯函数 —— 它是这条读面唯一会「把输出显示成两遍」的地方,值得被直接断言。
+ */
+export declare function mergeTaskOutput(prev: string, fresh: string): string;
+export type EngineTaskStopOutcome = 
+/** 200:停止动作完成(status = wire 终态照实;重复 stop 幂等)。 */
+{
+    ok: true;
+    status?: string;
+    stoppedBy?: string;
+}
+/** 409 stop.not_landed:kill 没落地,进程可能还在跑——UI 绝不能渲染成「已停止」。 */
+ | {
+    ok: false;
+    reason: 'not_landed';
+    detail?: string;
+}
+/** 409 stop.not_local(server 1.250+ durable 臂):任务在**别的实例**上还在跑,此处没有 kill
+ *  被尝试——「别处在跑,此处停不了」,非失败重试件([1518]§一)。UI 同样不翻行。 */
+ | {
+    ok: false;
+    reason: 'not_local';
+    detail?: string;
+}
+/** 409 stop.parked(server 1.263 parked 状态机):子代停在待审批检查点——不是在跑,也不该被
+ *  stop 杀(人先 /decide);409 stop.park_resume_won:复活赛跑输给了别处的 resume。两者 UI
+ *  都不翻行(fleet 行渲染词汇已由 coerceTaskStatus 映射 'awaiting approval')。 */
+ | {
+    ok: false;
+    reason: 'parked' | 'park_resume_won';
+    detail?: string;
+}
+/** 409 stop.park_arbiter_unreachable(core 1.397 三分,G13 补齐的第五形):仲裁店不可达 ⇒
+ *  **真相未知**(既不是「停了」也不是「没落地」)。UI 同样不翻行,但文案必须说「状态未知」——
+ *  塌进 not_landed 就是把「不知道」渲染成一个具体的失败原因。 */
+ | {
+    ok: false;
+    reason: 'park_arbiter_unreachable';
+    detail?: string;
+}
+/** 未知/未来 `stop.*` 码(开集 default)。不翻行;`detail` 带原文供诊断。 */
+ | {
+    ok: false;
+    reason: 'unknown_conflict';
+    detail?: string;
+} | {
+    ok: false;
+    reason: 'unavailable' | 'error';
+    detail?: string;
+};
+/**
+ * 🔴 **G13 删债(先红后绿)**:taskStop 的 409 冲突分类 —— 手抄 code 判 → typed
+ * `TaskStopConflictError`(SDK 把**任何** `stop.*` 前缀码映到该类,errors.js:277-278;
+ * SDK 自己的注释还点名了壳的手抄位置 `engineTaskHandleWire.ts:186-197`)。
+ *
+ * 手抄版的实际缺陷(pure 门先红实证):SDK 明列**五**形,手抄只认前四形 ⇒ 第五形
+ * `stop.park_arbiter_unreachable`(core 1.397 三分:仲裁店不可达 ⇒ **真相未知**)静默塌进
+ * `not_landed`。
+ * 🔴 后果方向先定正负号([anchor-on-the-deciding-quantity]):门控的量 = 「UI 翻不翻这一行」,
+ *    五形与 default **全都是不翻** ⇒ 这不是安全缺陷,是**诚实缺陷** —— 把「真相未知」渲染成
+ *    「kill 没落地」,用户与诊断双双被误导。所以修法是给第五形一个自己的名字,而不是调整门。
+ *
+ * 开集纪律:`switch` 留 `default`(未来新 `stop.*` 码落 `unknown_conflict`,照样不翻行、
+ * 照样带原始 `code`),绝不塌进任何一个已知形 —— 塌进去就等于替 server 编了一个它没说的原因。
+ */
+export declare function classifyTaskStopConflict(e: unknown): EngineTaskStopOutcome;
+/** 停一个引擎侧任务句柄(新面 B)。只有 ok:true(=HTTP 200)算停了。绝不 throw。 */
+export declare function stopEngineTask(handle: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<EngineTaskStopOutcome>;