@sema-agent/client-core 0.30.4 → 0.30.6

package/dist/workflowClient.js

@@ -180,6 +180,10 @@ function projectAgent(row, index) {
     const last = activity.length ? activity[activity.length - 1] : undefined;
     const label = typeof row.label === 'string' && row.label.trim() ? row.label.trim() : id || 'agent';
     const agent = { id, agentId, label, state };
+    // #242 批 1:callKey 是 SSE 侧 activity 台账的**主键**(agent_activity 帧必带),此前投影把它丢了
+    // ⇒ 合并层只剩 label 一把钥匙,重名 agent 只能整组跳过。带出来之后重名也能精确归属。
+    if (typeof row.callKey === 'string' && row.callKey)
+        agent.callKey = row.callKey;
     if (typeof row.model === 'string')
         agent.model = row.model;
     if (typeof row.tokens === 'number')
@@ -337,6 +341,521 @@ const STREAM_DROP_BACKOFF_MS = 1000;
 /** stream() ticker 帧触达时,距上一次 `refresh()` 的最小间隔——节流 re-GET 频率,不是退避:
  *  帧到来表示「有变化」,但没必要每一帧都打一次权威快照。 */
 const REFRESH_THROTTLE_MS = 400;
+// ══ #242 批 1(台账 A-028.8)—— 运行期 activity 台账:模块级常驻 + 每 workflowId 恰一条 SSE ═══
+//
+// ── 修前的两半(组合 = 同一 workflowId 上两条 SSE、两份台账)────────────────────────────────
+// ① core:workflow run 记录的 `agents[].toolCalls` / `agents[].activity` **只在 agent_end 折入**
+//    ⇒ 运行中 agent 的 GET 详情永远拿不到工具信息;运行期的工具事实**只在** detail SSE 上
+//    (`agent_activity` 带 callKey/label/toolName/arg/phase/ts;`agent_end` 带权威 toolCalls;
+//     `agent_end.modelResolved` 更是 core 记录从不折入的量 —— SSE 是唯一到达路径)。
+// ② 本文件:把这条 SSE 只当**变化 ticker**(`for await (const _frame …) { void _frame }`),帧体整丢。
+// ⇒ 壳(sema-cli `workflowLiveActivity.ts`)只好**另起一条同 id 的 SSE**自建模块级台账再自己合并。
+//
+// ── 本段(单流化)──────────────────────────────────────────────────────────────────────────
+// 台账收进包内,并且成为该 workflowId 的**唯一 SSE 属主**:
+//   · `ensureWorkflowActivityLedger(cfg)` —— **预热口**(幂等):fleet 流上 workflow 行一出现就调,
+//     从 workflow 起跑积累工具事实。🔴 台账是**模块级常驻**而非 per-controller —— 这是刻意的:
+//     壳侧一版做成「开 monitor 才开流」,实测两个洞(打开前的 beat 全丢:monitor 刚开的头几秒
+//     stats 恒空;重开 monitor = 新流 = 账本清零失忆)。`createLiveWorkflowSource().dispose()`
+//     只收它自己的 GET 循环,**不掐台账**,两个洞因此不会随上收复发。
+//   · `createLiveWorkflowSource` 不再自开流,改搭台账的 change-tick 做节流 re-GET(逐拍等价)。
+//   · `readWorkflowActivityLedger(id)` —— 台账读口(端侧合并层消费:壳 `mergeSnapshot` 只补
+//     base 缺席的键)。归属钥匙 **callKey 优先**(agent_activity 帧必带、GET 行也带),
+//     label 次之;同 label 多个非 replay 的 agent_start ⇒ 归属不可判 ⇒ label 读口**整组跳过**
+//     (诚实缺席,绝不猜挂)。
+// 限界(如实):台账自预热口首次调用起积累 —— 壳自己没看过的时段(重启后 attach 老 run)仍是
+// 下界;`agent_end.toolCalls` 到手后计数转权威。
+/** detail 页 Activity 尾窗是 3(HIO),折叠上限给足余量即可;超限丢最老(与 server 存储折入同向)。 */
+const MAX_WORKFLOW_ACTIVITY_CALLS = 40;
+/** 常驻台账上限(并发运行的 workflow 数远小于此;超限先逐已收口的,再逐最老)。 */
+const MAX_WORKFLOW_ACTIVITY_LEDGERS = 16;
+/** 运行中的意外断流回退(终态收口是**干净空流**自然退出,不再重连)。 */
+const WORKFLOW_ACTIVITY_RECONNECT_MS = 1500;
+/** 「一帧都没收到就抛」的连续次数上限 —— 满了才收口。1 次即收口会把瞬时不可达固化成永久失活;
+ *  不设上限则 S8 关闭(恒 501)的部署上会无限重连。3 次 ≈ 3s 观察窗,两头都不失守。 */
+const MAX_ACTIVITY_STREAM_ERROR_STREAK = 3;
+const activityLedgers = new Map();
+function newActivityLedger(workflowId, scope) {
+    return {
+        workflowId,
+        scope,
+        testOnly: false,
+        displaced: false,
+        byCallKey: new Map(),
+        labelAccs: new Map(),
+        startedLabels: new Map(),
+        ambiguous: new Set(),
+        closed: false,
+        closedReason: null,
+        connected: false,
+        frames: 0,
+        consumers: 0,
+        lastError: null,
+        errorStreak: 0,
+        abort: new AbortController(),
+        ticks: new Set(),
+        view: null,
+        viewFrames: -1,
+        viewClosed: false,
+        viewLastError: null,
+    };
+}
+/** 连线身份相等:凭证只比较、不落键不落日志。relay 形按 mode 比。 */
+function sameActivityScope(a, b) {
+    if (a.baseUrl !== b.baseUrl)
+        return false;
+    if (a.principal !== b.principal)
+        return false;
+    const at = a.authToken;
+    const bt = b.authToken;
+    if (typeof at === 'string' || typeof bt === 'string')
+        return at === bt;
+    return at.mode === bt.mode;
+}
+function newActivityAcc(label) {
+    return { label, calls: new Map(), order: [], startCount: 0 };
+}
+function registerLabelAcc(l, label, acc) {
+    const accs = l.labelAccs.get(label);
+    if (!accs) {
+        l.labelAccs.set(label, [acc]);
+        return;
+    }
+    if (!accs.includes(acc))
+        accs.push(acc);
+}
+/** label 位是否**唯一可判**:恰一个 acc、且没被重名探测标记。两条缺一不可 —— 前者盖住
+ *  「中途 attach 只见 beat」「replayed 重跑」这两条不经 agent_start 的产生路径,后者是显式诊断位。 */
+function soleAccOfLabel(l, label) {
+    if (l.ambiguous.has(label))
+        return undefined;
+    const accs = l.labelAccs.get(label);
+    if (!accs || accs.length !== 1)
+        return undefined;
+    return accs[0];
+}
+/** callKey 在场:它是主键。同 label 已有一条**尚未绑 callKey** 的 acc(agent_start 无 callKey 在先)
+ *  ⇒ 认领它,不新建第二份;否则新建并登记。 */
+function accByCallKey(l, callKey, label) {
+    const hit = l.byCallKey.get(callKey);
+    if (hit)
+        return hit;
+    // 🔴 只认领「还没被 label-only 的 agent_end 写过权威事实」的 orphan —— 带事实的那种一旦认领,
+    //    另一个 agent 的 toolCalls/modelResolved 就永久钉在这个 callKey 上了(callKey 读口不过
+    //    重名过滤)。不认领时新建第二份 ⇒ 该 label 变成非唯一 ⇒ label 读口自动改口诚实缺席。
+    const orphan = (l.labelAccs.get(label) ?? []).find(a => a.callKey === undefined && a.hasLabelOnlyEndFacts !== true);
+    const acc = orphan ?? newActivityAcc(label);
+    acc.callKey = callKey;
+    l.byCallKey.set(callKey, acc);
+    registerLabelAcc(l, label, acc);
+    return acc;
+}
+/** 只有 label 的写入(`agent_end` 帧不带 callKey)。🔴 该 label 下不止一个 acc ⇒ **不记**
+ *  ——错值比缺席更坏:写进去会被 callKey 读口原样读出来,把另一个 agent 的权威 toolCalls/
+ *  modelResolved 冒充成这一个的(对抗复审 [high] 采纳)。 */
+function accByLabelForWrite(l, label) {
+    const accs = l.labelAccs.get(label);
+    if (accs && accs.length > 1)
+        return undefined;
+    if (l.ambiguous.has(label))
+        return undefined;
+    if (accs && accs.length === 1)
+        return accs[0];
+    const acc = newActivityAcc(label);
+    registerLabelAcc(l, label, acc);
+    return acc;
+}
+/** 一帧 → 台账。开集帧形:只读认得的键,其余原样忽略(不认得的 event 直接落空)。 */
+function foldWorkflowActivityFrame(l, frame) {
+    l.frames += 1;
+    if (frame.event === 'agent_start') {
+        const label = frame.data.label;
+        if (typeof label !== 'string' || !label)
+            return;
+        const n = (l.startedLabels.get(label) ?? 0) + 1;
+        l.startedLabels.set(label, n);
+        // 重跑(replayed)不算重名;同 label 第二个非 replay start ⇒ 归属不可判。
+        if (n > 1 && frame.data.replayed !== true)
+            l.ambiguous.add(label);
+        const callKey = frame.data.callKey;
+        const acc = typeof callKey === 'string' && callKey
+            ? accByCallKey(l, callKey, label)
+            : accByLabelForWrite(l, label);
+        if (!acc)
+            return;
+        const requested = frame.data.model;
+        if (typeof requested === 'string' && requested)
+            acc.requestedModel = requested;
+        return;
+    }
+    if (frame.event === 'agent_end') {
+        const label = frame.data.label;
+        if (typeof label !== 'string' || !label)
+            return;
+        // agent_end 帧**不带 callKey**(wire 直证)⇒ 只有 label 一把钥匙;重名时不记。
+        const acc = accByLabelForWrite(l, label);
+        if (!acc)
+            return;
+        if (typeof frame.data.toolCalls === 'number') {
+            acc.endedToolCalls = frame.data.toolCalls;
+            if (acc.callKey === undefined)
+                acc.hasLabelOnlyEndFacts = true;
+        }
+        const resolved = frame.data.modelResolved;
+        if (typeof resolved === 'string' && resolved) {
+            acc.resolvedModel = resolved;
+            if (acc.callKey === undefined)
+                acc.hasLabelOnlyEndFacts = true;
+        }
+        return;
+    }
+    if (frame.event !== 'agent_activity')
+        return;
+    const d = frame.data;
+    if (typeof d.label !== 'string' || !d.label)
+        return;
+    if (typeof d.toolName !== 'string' || !d.toolName)
+        return;
+    const acc = typeof d.callKey === 'string' && d.callKey
+        ? accByCallKey(l, d.callKey, d.label)
+        : accByLabelForWrite(l, d.label);
+    if (!acc)
+        return;
+    if (typeof d.ts === 'number')
+        acc.lastTs = d.ts;
+    const key = typeof d.toolCallId === 'string' && d.toolCallId ? d.toolCallId : `#${acc.order.length}`;
+    if (d.phase === 'start')
+        acc.startCount += 1;
+    const prev = acc.calls.get(key);
+    const arg = typeof d.arg === 'string' && d.arg.trim() ? oneLineSummary(d.arg.trim()) : prev?.summary;
+    const folded = { name: d.toolName };
+    if (arg)
+        folded.summary = arg;
+    if (!acc.calls.has(key)) {
+        acc.order.push(key);
+        // 上限:丢最老(order 与 map 同步),detail 尾窗只看最近几条。
+        while (acc.order.length > MAX_WORKFLOW_ACTIVITY_CALLS) {
+            const drop = acc.order.shift();
+            if (drop !== undefined)
+                acc.calls.delete(drop);
+        }
+    }
+    acc.calls.set(key, { ...prev, ...folded });
+}
+function projectActivityAcc(acc) {
+    const activity = acc.order
+        .map(k => acc.calls.get(k))
+        .filter((c) => !!c)
+        .map(c => ({ name: c.name, ...(c.summary ? { summary: c.summary } : {}) }));
+    const view = {
+        label: acc.label,
+        // agent_end 的权威值优先,否则 start 计数下界。
+        toolCalls: acc.endedToolCalls ?? acc.startCount,
+        activity,
+    };
+    if (acc.callKey !== undefined)
+        view.callKey = acc.callKey;
+    const tail = activity.length > 0 ? activity[activity.length - 1] : undefined;
+    if (tail) {
+        view.lastToolName = tail.name;
+        if (tail.summary)
+            view.lastToolSummary = tail.summary;
+    }
+    if (acc.requestedModel !== undefined)
+        view.requestedModel = acc.requestedModel;
+    if (acc.resolvedModel !== undefined)
+        view.resolvedModel = acc.resolvedModel;
+    if (acc.lastTs !== undefined)
+        view.lastProgressAt = acc.lastTs;
+    return view;
+}
+/** 台账读口:没有该 id 的台账 ⇒ **null**(不是空视图 —— 「没开过账」与「开了账但一帧没收到」
+ *  是两件事,端侧据此分辨)。产物只读,按 frames/closed 缓存。 */
+export function readWorkflowActivityLedger(workflowId) {
+    const l = activityLedgers.get(workflowId);
+    if (!l)
+        return null;
+    if (l.view !== null &&
+        l.viewFrames === l.frames &&
+        l.viewClosed === l.closed &&
+        l.viewLastError === l.lastError) {
+        return l.view;
+    }
+    const projected = new Map();
+    const viewOf = (acc) => {
+        let v = projected.get(acc);
+        if (!v) {
+            v = projectActivityAcc(acc);
+            projected.set(acc, v);
+        }
+        return v;
+    };
+    const byCallKey = new Map();
+    for (const [k, acc] of l.byCallKey)
+        byCallKey.set(k, viewOf(acc));
+    const byLabel = new Map();
+    for (const label of l.labelAccs.keys()) {
+        // 🔴 归属不可判(同 label 多个 acc / 重名探测命中)⇒ 整组跳过(诚实缺席,绝不猜挂)。
+        //    callKey 读口不受影响 —— 它才是真钥匙。
+        const sole = soleAccOfLabel(l, label);
+        if (!sole)
+            continue;
+        byLabel.set(label, viewOf(sole));
+    }
+    l.view = {
+        workflowId,
+        byCallKey,
+        byLabel,
+        ambiguousLabels: new Set(l.ambiguous),
+        closed: l.closed,
+        frames: l.frames,
+        lastError: l.lastError,
+    };
+    l.viewFrames = l.frames;
+    l.viewClosed = l.closed;
+    l.viewLastError = l.lastError;
+    return l.view;
+}
+/** 一拍。一个抛异常的订阅者不许弄死后台消费循环(与本源全篇 fail-soft 一致)。 */
+function emitActivityTick(l) {
+    for (const t of [...l.ticks]) {
+        try {
+            t();
+        }
+        catch (err) {
+            if (engineWireDebugEnabled()) {
+                hostLog('debug', `[sema][workflow] activity tick subscriber threw (ignored): ${String(err)}`);
+            }
+        }
+    }
+}
+/** 等下一拍:'tick' = 有帧到达 / 'closed' = 台账收口 / 'abort' = 宿主 dispose。 */
+function waitActivityTick(l, signal) {
+    if (signal.aborted)
+        return Promise.resolve('abort');
+    if (l.closed)
+        return Promise.resolve('closed');
+    return new Promise(resolve => {
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            l.ticks.delete(onTick);
+            signal.removeEventListener('abort', onAbort);
+            resolve(r);
+        };
+        const onTick = () => finish(l.closed ? 'closed' : 'tick');
+        const onAbort = () => finish('abort');
+        l.ticks.add(onTick);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** 台账的 SSE 消费循环 —— **该 workflowId 唯一的一条流**。 */
+async function consumeWorkflowActivity(l, cfg) {
+    // 唯一构造点 + 显式 maxRetries: 2(与 createLiveWorkflowSource 同口径)。
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.authToken ? { token: cfg.authToken } : {}),
+        principal: cfg.principal,
+        maxRetries: 2,
+        ...(cfg.fetchImpl ? { fetchImpl: cfg.fetchImpl } : {}),
+    });
+    // fail-soft:工厂造不出 client ⇒ 台账收口、读口如实报 closed(绝不抛进宿主)。
+    if (client === null) {
+        l.closed = true;
+        l.closedReason = 'error';
+        l.lastError = 'client construction failed (invalid baseUrl/credentials)';
+        emitActivityTick(l);
+        return;
+    }
+    while (!l.closed && !l.abort.signal.aborted) {
+        let sawFrame = false;
+        let threw = false;
+        try {
+            const stream = client.workflows.stream(l.workflowId, {
+                signal: l.abort.signal,
+                ...engineSessionParamSpread(),
+            });
+            for await (const frame of stream) {
+                if (l.closed)
+                    return;
+                sawFrame = true;
+                l.connected = true;
+                try {
+                    foldWorkflowActivityFrame(l, frame);
+                }
+                catch {
+                    // 单帧折叠失败不拆流(开集帧形;台账缺一拍好过整层失效)。
+                }
+                emitActivityTick(l);
+            }
+        }
+        catch (err) {
+            if (l.closed || l.abort.signal.aborted)
+                return;
+            threw = true;
+            l.lastError = err instanceof Error ? err.message : String(err);
+            if (engineWireDebugEnabled()) {
+                hostLog('debug', `[sema][workflow] activity stream drop: ${l.lastError}`);
+            }
+        }
+        l.connected = false;
+        // 🔴 两种「本轮零帧」必须分开裁(对抗复审 [high] 采纳 —— 合并成一条会把**一次瞬时不可达**
+        //    固化成台账永久失活,而 ensure 对已存在台账恒早退 ⇒ 引擎恢复后 SSE 再也开不回来,
+        //    详情页此后只剩 GET 轮询,而运行期 tool/activity 恰恰是 GET 结构上给不出的量):
+        //    · **干净空流**(迭代器正常结束、一帧没有)= run 终态/不在本副本(core subscribeWorkflow
+        //      非活跃即空迭代器)⇒ 收口,GET 此后是权威;
+        //    · **抛在首帧前**(501/404/连接失败)= 可能只是这一拍不可达 ⇒ 退避重连,连击满
+        //      MAX_ACTIVITY_STREAM_ERROR_STREAK 次(全程零帧)才收口,lastError 留痕。
+        if (!sawFrame && !threw) {
+            l.closed = true;
+            l.closedReason = 'terminal';
+            emitActivityTick(l);
+            return;
+        }
+        if (sawFrame)
+            l.errorStreak = 0;
+        else if (threw) {
+            l.errorStreak += 1;
+            if (l.errorStreak >= MAX_ACTIVITY_STREAM_ERROR_STREAK) {
+                // 🔴 只是「连不上」⇒ 标 error(可被下一次 ensure 重开),不是终态。
+                l.closed = true;
+                l.closedReason = 'error';
+                emitActivityTick(l);
+                return;
+            }
+        }
+        emitActivityTick(l);
+        if (!l.closed && !l.abort.signal.aborted) {
+            await abortableSleep(WORKFLOW_ACTIVITY_RECONNECT_MS, l.abort.signal);
+        }
+    }
+    emitActivityTick(l);
+}
+/**
+ * **预热口**(幂等):fleet 流上见到 running workflow 行就调 —— 从 workflow 起跑积累工具事实,
+ * monitor 无论何时打开都有自那时起的完整台账。已有台账(哪怕已收口)即早退,**绝不开第二条流**。
+ */
+export function ensureWorkflowActivityLedger(cfg) {
+    if (!cfg.workflowId)
+        return;
+    const scope = {
+        baseUrl: cfg.baseUrl,
+        principal: cfg.principal,
+        authToken: cfg.authToken,
+    };
+    const existing = activityLedgers.get(cfg.workflowId);
+    if (existing) {
+        // 测试钩建的离线台账:恒早退(不换、不起流)。
+        if (existing.testOnly)
+            return;
+        if (sameActivityScope(existing.scope, scope)) {
+            // 🔴 同连线身份:只有**因错误**收口的才重开(对抗复审 R2 [high] 采纳)——干净空流(run
+            //    终态)与显式 stop 是永久收口,重开等于跟一个已经结束的 run 死磕。重开**复用同一条
+            //    台账对象**,已积累的事实原样保留(重连不失忆)。
+            if (existing.closed && existing.closedReason === 'error') {
+                existing.closed = false;
+                existing.closedReason = null;
+                existing.errorStreak = 0;
+                existing.abort = new AbortController();
+                void consumeWorkflowActivity(existing, cfg);
+            }
+            return;
+        }
+        // 🔴 同 id 但**连线身份变了**(换引擎 baseUrl / 换 principal / 换凭证)⇒ 旧台账连的是另一台
+        //    服务,复用它等于把上一处的活动事实当成这一处的。整条换新,并给旧的打 displaced ——
+        //    旧台账的消费者据此**不再重新 ensure**(否则两个不同 scope 的消费者会互相把槽位换来换去)。
+        existing.closed = true;
+        existing.closedReason = 'stopped';
+        existing.displaced = true;
+        existing.abort.abort();
+        emitActivityTick(existing);
+        activityLedgers.delete(cfg.workflowId);
+    }
+    if (activityLedgers.size >= MAX_WORKFLOW_ACTIVITY_LEDGERS) {
+        // 逐出顺序:① 已收口的(数据只读,重开 monitor 走 GET 权威)→ ② 无在飞消费者的最老一条。
+        // 🔴 判活用**消费者租约** `consumers` 而不是瞬时的 `ticks.size`(对抗复审 R2 [medium]):
+        //    消费者被一帧唤醒、正在跑一发慢 GET 的那一窗里 ticks 是空的,按它判会把在飞台账逐掉。
+        // 🔴 **绝不逐出正在被消费的台账**:那会当场丢掉它积累的 SSE-only 历史,而被叫醒的消费方
+        //    退避后又会重建、再逐掉另一条在飞的 —— 逐出/重连自激。
+        // 全 16 条都有在飞消费者时**不建新账**(如实降级:该 id 的详情页退回 GET 轮询)。
+        let victim;
+        for (const [id, other] of activityLedgers) {
+            if (other.closed && other.consumers === 0) {
+                victim = id;
+                break;
+            }
+        }
+        if (victim === undefined) {
+            for (const [id, other] of activityLedgers) {
+                if (other.consumers === 0) {
+                    victim = id;
+                    break;
+                }
+            }
+        }
+        if (victim === undefined) {
+            if (engineWireDebugEnabled()) {
+                hostLog('debug', `[sema][workflow] activity ledger cap ${MAX_WORKFLOW_ACTIVITY_LEDGERS} reached with every entry consumed — not opening one for ${cfg.workflowId} (detail falls back to GET polling)`);
+            }
+            return;
+        }
+        const evicted = activityLedgers.get(victim);
+        if (evicted) {
+            evicted.closed = true;
+            evicted.closedReason = 'stopped';
+            evicted.abort.abort();
+            emitActivityTick(evicted);
+        }
+        activityLedgers.delete(victim);
+    }
+    const ledger = newActivityLedger(cfg.workflowId, scope);
+    activityLedgers.set(cfg.workflowId, ledger);
+    void consumeWorkflowActivity(ledger, cfg);
+}
+/** fleet 行终态/remove 的收口口(空流收口是主径;这里防重连定时器竞态)。数据保留只读。 */
+export function stopWorkflowActivityLedger(workflowId) {
+    const l = activityLedgers.get(workflowId);
+    if (!l)
+        return;
+    l.closed = true;
+    l.closedReason = 'stopped';
+    l.abort.abort();
+    emitActivityTick(l);
+}
+/** 测试钩:清空全部台账(abort 在飞流)。 */
+export function resetWorkflowActivityLedgers() {
+    for (const l of activityLedgers.values()) {
+        l.closed = true;
+        l.closedReason = 'stopped';
+        l.abort.abort();
+        emitActivityTick(l);
+    }
+    activityLedgers.clear();
+}
+/**
+ * 测试钩:**不起 SSE 流**,直接把一帧喂进(缺则新建)指定 run 的台账 —— 折叠规则走产品那一份
+ * `foldWorkflowActivityFrame`,不是测试自己抄一份。建出来的台账是 closed 的,后续
+ * `ensureWorkflowActivityLedger` 命中它即早退,离线单测因此永不触网。
+ */
+export function __feedWorkflowActivityFrameForTests(workflowId, frame) {
+    let l = activityLedgers.get(workflowId);
+    if (!l) {
+        l = newActivityLedger(workflowId, { baseUrl: '', principal: undefined, authToken: '' });
+        l.testOnly = true;
+        l.closed = true;
+        l.closedReason = 'stopped';
+        activityLedgers.set(workflowId, l);
+    }
+    // 🔴 只往**离线台账**里喂(对抗复审 R2 [medium] 采纳):这个钩虽在 `_` 前缀的测试钩面上
+    //    (不进公开导出基线),但它此前能把伪造帧折进一条**真在跑**的台账。现在真台账一律拒绝
+    //    —— 测试要用它必须先 `resetWorkflowActivityLedgers()`,离线契约从「靠调用方自觉」变成结构。
+    if (!l.testOnly)
+        return;
+    foldWorkflowActivityFrame(l, frame);
+    emitActivityTick(l);
+}
 /**
  * createLiveWorkflowSource({ baseUrl, authToken, principal, workflowId? }) — the LIVE workflow-monitor source.
  *
@@ -357,6 +876,8 @@ export function createLiveWorkflowSource(config) {
     let lastGetAt = 0;
     /** 入场打点用:只有第一发 get 是「入场」,后续都是 ticker 触发的 re-GET。 */
     let first = true;
+    /** 台账槽位被别的连线身份顶掉过 ⇒ 本源放弃 activity 腿(防两个 scope 互相换账)。 */
+    let activityDisabled = false;
     const listeners = new Set();
     /** 通知订阅者「快照变了」。一个抛异常的订阅者不许弄死后台消费循环(fail-soft 与本源全篇一致)。 */
     function notify() {
@@ -477,27 +998,74 @@ export function createLiveWorkflowSource(config) {
                     await abortableSleep(DEGRADED_BACKOFF_MS, abort.signal);
                     continue;
                 }
-                try {
-                    // stream = "something changed" ticker. Re-GET the authoritative owner-scoped detail (throttled to
-                    // ~400ms) rather than reduce the permissive core-internal WorkflowEvent shapes on the client. NOT
-                    // resumable — a drop ends the iterator; the outer loop re-snapshots.
-                    for await (const _frame of client.workflows.stream(id, { signal: abort.signal, ...engineSessionParamSpread() })) {
-                        void _frame;
-                        if (disposed)
-                            return;
-                        connected = true;
-                        if (Date.now() - lastGetAt >= REFRESH_THROTTLE_MS)
-                            await refresh(id, abort.signal);
-                        if (degraded)
-                            break;
+                // 🔴 #242 批 1 单流化:本源**不再自开 SSE**。该 workflowId 的唯一 SSE 属主是模块级 activity
+                // 台账(同时也是 fleet 行预热腿的属主);本源只搭它的 change-tick 做节流 re-GET —— 与旧
+                // `for await (const _frame of stream)` 的逐拍语义等价,而连接数从「壳一条 + 本源一条」降到 1。
+                // 帧体不再被丢弃:台账消费它(callKey 折叠 / agent_end.toolCalls 权威 / requested-resolved model)。
+                if (!activityDisabled) {
+                    // 🔴 停手检查必须先于 ensure(主会话收货修,#242-E13 抓出的时序洞):循环尾的
+                    //    `ledger.displaced` 检查读的是「本轮拿的对象」,而被顶掉发生在上一轮的 backoff 期
+                    //    ——下一轮若先 ensure,本源会在检测到自己被顶之前就把别的连线身份的台账换掉
+                    //    (伤害先于检测,ping-pong 防护形同虚设)。所以进入 ensure 前先看当前槽位:
+                    //    已被**另一连线身份**持有 ⇒ 本源就地停手降级(GET 轮询),绝不抢回。
+                    const cur = activityLedgers.get(id);
+                    if (cur &&
+                        !cur.testOnly &&
+                        !sameActivityScope(cur.scope, {
+                            baseUrl: config.baseUrl,
+                            principal: config.principal,
+                            authToken: config.authToken,
+                        })) {
+                        activityDisabled = true;
+                        if (engineWireDebugEnabled()) {
+                            hostLog('debug', `[sema][workflow] activity ledger for ${id} is held by another engine target/principal — this source stands down (GET polling only)`);
+                        }
+                    }
+                    else {
+                        ensureWorkflowActivityLedger({
+                            baseUrl: config.baseUrl,
+                            authToken: config.authToken,
+                            principal: config.principal,
+                            workflowId: id,
+                            ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
+                        });
                     }
                 }
-                catch (err) {
-                    if (disposed || abort.signal.aborted)
-                        return;
-                    noteDegrade(err); // 501 (S8 off) / 404 (gone) thrown BEFORE any frame, or a mid-stream transport drop
+                const ledger = activityDisabled ? undefined : activityLedgers.get(id);
+                if (ledger) {
+                    // 🔴 消费者租约:整段消费期持有(不是瞬时的 tick 订阅)—— 逐出判活读的就是它,
+                    //    「被一帧唤醒、正在跑慢 GET」的那一窗里台账不会被误判成无人消费。
+                    ledger.consumers += 1;
+                    try {
+                        for (;;) {
+                            const beat = await waitActivityTick(ledger, abort.signal);
+                            if (beat === 'abort' || disposed)
+                                return;
+                            if (beat === 'tick')
+                                connected = true;
+                            if (Date.now() - lastGetAt >= REFRESH_THROTTLE_MS)
+                                await refresh(id, abort.signal);
+                            if (degraded)
+                                break;
+                            // 台账收口(run 终态 / 显式 stop / 错误连击 / 被别的连线身份顶掉)⇒ 退回外层的
+                            // 「退避 + 重取权威快照」;下一轮的 ensure 决定要不要重开(只有 error 收口会重开)。
+                            if (beat === 'closed')
+                                break;
+                        }
+                    }
+                    finally {
+                        ledger.consumers -= 1;
+                    }
+                    // 🔴 本源的台账被**另一个连线身份**顶掉过 ⇒ 本源就此不再 ensure(否则两个 scope 的
+                    //    消费者会把同一个槽位来回换)。如实降级:详情页此后只走 GET 轮询。
+                    if (ledger.displaced) {
+                        activityDisabled = true;
+                        if (engineWireDebugEnabled()) {
+                            hostLog('debug', `[sema][workflow] activity ledger for ${id} was taken over by another engine target/principal — this source stops re-opening it (GET polling only)`);
+                        }
+                    }
                 }
-                // stream ended (drop, not resumable) → re-snapshot on the next loop after a small backoff.
+                // ledger 收口/降级 → 小回退后在下一轮重取权威快照(GET 此后是权威)。
                 if (!disposed && !abort.signal.aborted)
                     await abortableSleep(STREAM_DROP_BACKOFF_MS, abort.signal);
             }

package/dist/workflowMonitor.d.ts

@@ -43,6 +43,13 @@ export interface WorkflowAgent {
     lastAttemptReason?: 'throttled' | 'user-retry' | 'stalled';
     error?: string;
     agentId?: string;
+    /**
+     * #242 批 1(A-028.8):`ctx.agent` 调用的**稳定确定性身份**(resume-journal key,
+     * SDK `WorkflowAgentRow.callKey`)。运行期 activity 台账的 SSE 帧(`agent_activity`)以它为键,
+     * 而此前投影把它丢了 —— 于是 label 成了合并层唯一的钥匙,同名 agent 只能整组跳过。
+     * 投影带出它之后,重名 label 也能精确归属;缺席(老引擎/老 run)时才回落到 label。
+     */
+    callKey?: string;
     /** detail "Prompt" body; promptPreview is the fallback when no transcript is loaded. */
     promptPreview?: string;
     /** detail "Activity" rows. */