@sema-agent/server 7.43.0 → 7.44.0

package/dist/fleet/fleet-terminal-window.js

@@ -1,93 +1,15 @@
-/**
- * #189 修方向 1(黑板 [3112] 定谳)—— `/v1/fleet/stream` 连接时快照要并入的**近期终态 workflow 行窗**。
- *
- * ## 它修什么
- * 引擎重启后 boot 扫描判死前世 `running` run,`publishWorkflow`(终帧)与 `removeWorkflow` 在**同一同步
- * 调用栈内**背靠背执行;fleet bus 是纯内存 EventEmitter、无重放,`snapshot()` 只读活跃 Map ⇒ **重启之后
- * 才连上的客户端连增量带快照都结构性看不见那一行**(cli 七轮正控实证)。durable 真源一直是对的
- * (`GET /v1/workflows` 可达),缺的只是把它接到面板这一路上——所以这里是 **pull**:读同一份 durable
- * store,**不碰 bus 的活跃 Map**(活行的单写者不变量、增量帧语义逐字不动)。
- *
- * ## 五条界(任何一条失手都只是少几行历史 ⇒ 整体 F 类 fail-open,登记 tag,不静默)
- *  · 窗长 {@link FLEET_SNAPSHOT_TERMINAL_WINDOW_MS} · 行数 {@link FLEET_SNAPSHOT_TERMINAL_MAX_ROWS}
- *  · 扫描面 {@link FLEET_SNAPSHOT_TERMINAL_SCAN_LIMIT} · 读预算 {@link FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS}
- *  · 熔断冷却 {@link FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS}
- *
- * ## 为什么本模块有进程级可变状态(路由域刻意保持零状态,故不放在 `routes/fleet.ts`)
- * 三件都长在同一个事实上——**`WorkflowRunStore` 契约没有取消面**,`Promise.race` 只结束等待、撤不回
- * 已发出的查询:合流(重连风暴不按连接数放大,R1-H2)、合流窗有限(不把陈旧结果发给后来者、也不让
- * 一条永不 settle 的读把后续连接全钉死,R2-H1/R3-M2)、熔断冷却(挂死的后端不被每周期继续加压,
- * R3-H1)。真解是店侧查询超时/取消 —— 要动契约与四个后端,已作移交项。
- *
- * ## scope
- * `WorkflowRunStore` 契约**没有跨 scope 枚举**(见 `orchestration/workflow-notify-journal.ts` 头注),
- * 所以窗恒按**调用者自己的 principal scope** 读:fleet-wide 观察者看到的是「全租户活行 + 自己 scope 的
- * 终态窗」。这是诚实的不对称(读不到的东西不编),方向安全(绝不多给);真行的租户/会话可见性仍由
- * 路由的 `visW` 统一执法,本模块不自行放行。
- */
 import { isTerminalWorkflowStatus } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { buildFleetWorkflowRow } from "./fleet-bus.js";
-/**
- * 窗长 —— 10 分钟,**不做旋钮**。
- *
- * 它覆盖的是一段具体的人机时长:「引擎重启 → 客户端重连 → 人看一眼面板上刚才那条 workflow 怎么了」。
- * 比它短会漏掉重连慢一步的壳(即本 issue 的病灶);比它长就变成「拿 SSE 快照当历史列表」——而历史面
- * 本来就有真源(`GET /v1/workflows`:durable、可分页、带 scope/session 过滤),不该在这里长出第二个。
- * 两侧边界都由语义定死,旋钮只会让部署方去调一个没有正确取值的数;fleet 面现有零旋钮,从之。
- */
 export const FLEET_SNAPSHOT_TERMINAL_WINDOW_MS = 10 * 60_000;
-/** 同一快照里终态行的行数上限(窗长之外的第二道界)。快照是面板首屏,不是历史列表——超出的部分归
- *  `GET /v1/workflows`。 */
 export const FLEET_SNAPSHOT_TERMINAL_MAX_ROWS = 20;
-/**
- * 每个终态**扫描面**的行数(店侧下推的 limit)。它比 {@link FLEET_SNAPSHOT_TERMINAL_MAX_ROWS} 大是有
- * 具体病灶的(codex R1-M3,红先复现):店侧分页按 `createdAt DESC` 排(core 契约 + 两个 SQL 实现皆然),
- * 而本窗的判据是**结束时刻**——一条跑了三天、刚刚才结束的 workflow(正是用户此刻要看的那条)会被 20 条
- * 更晚创建的行挤出首页。留这段余量是在现有契约内能给的最好答案;彻底解法是店侧加一个 `ended_at_ms DESC`
- * 的窄查询(要过真双库门,已作移交项记在发车说明里)。
- *
- * 残余(如实记档):同 scope 同一终态下,若有超过本值条**更晚创建**的行,那条"早创建、刚结束"的行仍会
- * 被挤掉。此时用户仍可从 `GET /v1/workflows` 看到真相——丢的只是面板首屏的一行。
- */
 export const FLEET_SNAPSHOT_TERMINAL_SCAN_LIMIT = 100;
-/** durable 读的时间预算。超时=**放弃这段增益**(记 F 类 fail-open),绝不让一次慢查询把整条 SSE 握手
- *  拖住——面板少一条历史行是难看,连不上流是坏掉。 */
 export const FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS = 2_000;
-/**
- * (原 `FLEET_SNAPSHOT_TERMINAL_COALESCE_MS` 已删)⚖️ 「同时只有一支探针」与「结果别太陈旧」的取舍
- * —— codex R3-M2 与 R4-H1 是两轮方向相反的 finding,这里成文定案。
- *
- * 后来者**加入**在飞的那支读,只要它还在自己的预算之内({@link FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS})。
- *  · 曾短暂改成 250ms 的窄窗(想压小"采到"与"交付"的时差):实测判据下更坏 —— 慢而健康的店(比如
- *    1.9s)配错峰重连,会变成每 250ms 起一批新读(2 次 list + ≤20 点读),而熔断要等某个调用方 2s
- *    超时才开;单飞的意义被自己抵消(R4-H1)。
- *  · 保留的代价:刚好在探针尾巴上加入的调用方,可能拿到一份最多约"两倍预算"之前采到的行集(R3-M2)
- *    —— 后果是这条连接首屏少一条**刚刚**结束的行(且只有跨副本翻转才补不上帧),与本模块整体的 F 类
- *    姿态同级;而 R4-H1 的后果是给一个已经很慢的库继续加压。取小害。
- * 过了预算的在飞读 = 已被放弃的一代(等待方全走光了),不再加入:那一代由熔断收尾,新调用方在冷却期
- * 外开新一代。
- */
-/**
- * 熔断冷却期:一次读失败/超预算之后,同 (store, scope) 在这段时间内**不再发起新读**(直接放弃这段增益,
- * 记 F 类 fail-open)。
- *
- * 为什么必须有(codex R3-H1,红先复现 4→2):`WorkflowRunStore` 契约没有取消面 —— 发出去的查询撤不回。
- * 后端挂死时,只按"复用窗过期就再起一次"办,等于每个周期给那个已经挂死的后端再加两笔永不回来的活,
- * 连接不断则永远堆下去(池/内存/驱动队列迟早耗尽),这正是"故障期被自己的重试放大"那一族。冷却期把
- * 新增速率钉在「每 scope 每 10s 至多一次探针」,并且**自愈**:冷却一过,下一条连接就是一次真实探测。
- * 残余(如实记档):挂死那几笔仍在后端占着;真解=店侧查询超时/取消(要动契约与四个后端,移交项)。
- */
 export const FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS = 10_000;
-/** 终态词表:从 {@link WorkflowRunStatus} 闭集**穷举**(缺一个键或多一个键都是编译期错误)后按 core 的
- *  {@link isTerminalWorkflowStatus} 判定——集合的闭合由类型执法、终态的**语义**仍是 core 单源。core 若
- *  加一个状态,这里编译期就红,而不是悄悄漏进/漏出终态窗。 */
 const TERMINAL_WORKFLOW_STATUSES = (() => {
     const all = { running: true, completed: true, failed: true };
     return Object.keys(all).filter((s) => isTerminalWorkflowStatus(s));
 })();
-/** fleet 行上的 `status` 是自由字符串(wire 面容忍未知词),而"是不是终态"必须与上面那张**同一张**
- *  闭集表说同一句话 —— 供路由判断一条 workflow 行帧是否终态(不做裸 cast:词表就是判据)。 */
 export function isTerminalWorkflowRowStatus(status) {
     return TERMINAL_WORKFLOW_STATUSES.some((s) => s === status);
 }
@@ -105,28 +27,20 @@ function scopeState(store, scope) {
     }
     return st;
 }
-/** 开熔断,并挂一个 unref 的到期回调自清 + 销号 —— 否则「读超时 2.0s、查询 2.1s 才落地」这条常见路径会
- *  留下一条永久驻留的 scope 记录(冷却记号没人清、`evictIfIdle` 又因为冷却未过而不动手,codex R5-M2)。
- *  代际校验(`coolingUntil === until`)保证到期回调只清自己开的那一次。 */
 function openCooldown(store, scope, st) {
-    // codex R6-M:同一支探针失败的 N 个等待者各自到点都会走到这里——冷却语义是 per-probe-failure,不是
-    // per-waiter,首开者赢:已在冷却期内就不续期、不再铸第二支定时器(风暴+挂库时 O(连接数) 定时器与
-    // 闭包正好压在依赖已经退化的时刻)。
     if (st.coolingUntil !== undefined && st.coolingUntil > Date.now())
         return;
     const until = Date.now() + FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS;
     st.coolingUntil = until;
     const t = setTimeout(() => {
         if (st.coolingUntil !== until)
-            return; // 期间又开过新的一次冷却:那次自己管自己
+            return;
         st.coolingUntil = undefined;
         evictIfIdle(store, scope, st);
     }, FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS);
     if (typeof t.unref === "function")
-        t.unref(); // 观测性的收尾绝不该拖住进程退出
+        t.unref();
 }
-/** 无事可记的 scope 就地销号(codex R4-M2):否则每一个**曾经**开过流的 principal 都会在这张强引用表里
- *  永久留一条——多租户长跑进程下,租户流动/高基数身份会把它变成一条只增不减的内存线。 */
 function evictIfIdle(store, scope, st) {
     if (st.inFlight !== undefined)
         return;
@@ -136,34 +50,17 @@ function evictIfIdle(store, scope, st) {
     if (byScope?.get(scope) === st)
         byScope.delete(scope);
 }
-/**
- * 取该 scope 的近期终态行窗。**永不抛**:任何失败/超预算都收成"少几行历史"并记 F 类 fail-open。
- *
- * ⚠️ 调用方仍须对每一行施加与活行**同一套**可见性判据(`visW`:scope + `?session=`)——本函数按 scope
- * 读,但会话轴刻意留给调用方,好与活行"无 sessionId 的行 fail-open 可见"的既有语义逐字一致。
- */
-/** [3156] 轮2 真红的修:进程内终态行 seed 缓存 —— **写路径顺手喂**(publishFleet 的 terminal 臂),
- *  读侧零库查询零时序竞态。存在理由:durable pull 的查询键是 caller 的 scope,而 fleetWide 连接
- *  (无 auth 部署恒是)的可见性判据放行**全部** scope —— 查询键与可见性判据不同源。行 scope 的值
- *  = 提交方自报的 principal 经引擎透传("anon:shell-live" 是 cli 壳在本地单用户模式**自发的 header
- *  值**,引擎只做 scope=principal 赋值,不发明该字面量;[3225] 后续侦察定谳,勿再写「引擎铸」),
- *  它永远不等于 caller 读侧的 "default",pull 恒 miss。seed 缓存按「发生过什么」
- *  记(与订阅方无关),读侧再过各连接自己的 visW。不是活跃集:bus 的 Map 零触碰,单写者不变量原样。
- *  有界:行数 ≤ MAX_ROWS×2、窗长同 WINDOW_MS,超界丢最旧。 */
 const seededTerminalRows = [];
 export function seedTerminalWorkflowRow(row) {
     const now = Date.now();
     seededTerminalRows.push({ row, at: now });
-    // 双界修剪:窗长 + 行数(常数级,每次 seed 顺手)
     while (seededTerminalRows.length > 0 && (now - seededTerminalRows[0].at > FLEET_SNAPSHOT_TERMINAL_WINDOW_MS || seededTerminalRows.length > FLEET_SNAPSHOT_TERMINAL_MAX_ROWS * 2)) {
         seededTerminalRows.shift();
     }
 }
-/** 测试缝:清 seed 缓存(与 clearTerminalWindowCooldownForTest 同姿势,生产零调用)。 */
 export function clearSeededTerminalRowsForTest() {
     seededTerminalRows.length = 0;
 }
-/** 窗内 seed 行(同 id 取最新一条;窗外的顺手剪掉)。 */
 function seededRowsInWindow() {
     const now = Date.now();
     const byId = new Map();
@@ -174,29 +71,19 @@ function seededRowsInWindow() {
     return [...byId.values()];
 }
 export async function recentTerminalWorkflowRows(store, scope, pullScope) {
-    // [3156]:seed 缓存 = 本进程生命周期内全部终态(含 boot recover 判死)的同源可达径——fleetWide 连接
-    // (scope=null,可见性判据放行全 scope)取 seed **全量**,并以 `pullScope`(caller principal,尽力形)
-    // 做 durable pull 兜底:pull 的查询键与行 scope(提交方自报 principal 的透传值)可能不同源
-    // (cli 轮2 实测 "default" vs 壳自发的 "anon:shell-live" 恒 miss),中了是增益、中不了还有 seed
-    // ——两径并集,谁都不当唯一真源。
-    // scoped 连接:seed 按本 scope 滤 + durable pull 本 scope(跨进程兜底)。
-    // [3193] 病理3:seed 侧不再按 caller scope 预滤——那是第二份可见性判据(F1 病族),与行 scope
-    // (壳自发 "anon:shell-live" vs caller "default")恒 miss。本函数只产**候选集**;可见/擦除由路由的
-    // visW/stripW 同一套判据裁(与快照活行、增量帧同源),窗与 MAX_ROWS 双界仍在。
     const seeded = seededRowsInWindow();
     const effectiveScope = scope ?? pullScope;
     if (effectiveScope === undefined)
         return seeded;
     const scopeForPull = effectiveScope;
     if (!store)
-        return seeded; // 无 durable store 的部署(memory 后端/未开自编排):seed 缓存仍工作
+        return seeded;
     const cooling = scopeState(store, scopeForPull);
     if (cooling.coolingUntil !== undefined && Date.now() < cooling.coolingUntil) {
-        // 熔断中:上一代读超预算(后端卡住),这段时间内连探都不探(见 FLEET_SNAPSHOT_TERMINAL_COOLDOWN_MS)。
         recordFailOpen("server.fleet.snapshot-terminal-window-unavailable", "cooling down after an over-budget read");
-        return seeded; // 熔断只熔 durable 读;seed 是进程内的,照常(scope=null 的 fleetWide 形=全量,勿再按 null 过滤)
+        return seeded;
     }
-    cooling.coolingUntil = undefined; // 冷却已到期:销掉这个记号,好让空闲 scope 能被回收
+    cooling.coolingUntil = undefined;
     evictIfIdle(store, scopeForPull, cooling);
     let timer;
     const probe = sharedRead(store, scopeForPull);
@@ -207,67 +94,33 @@ export async function recentTerminalWorkflowRows(store, scope, pullScope) {
                 timer.unref();
         });
         const pulled = await Promise.race([probe.rows, budget]);
-        // scoped 腿 = durable pull ∪ seed(同 id durable 优先 —— 库行是 CAS 后真源,seed 是投影快照)
         const pulledIds = new Set(pulled.map((r) => r.id));
         return [...pulled, ...seeded.filter((r) => !pulledIds.has(r.id))];
     }
     catch (err) {
-        // 熔断**只由自己这一代开**(codex R4-H1):判据是「我等的那一代到现在还挂在飞」——那才是"后端卡住、
-        // 再发就是加压"。两个反例都被这条判据排除:① 我等的那代其实已经完成/失败并销号(快失败的店不累积
-        // 在飞的活,没有加压问题,不该罚 10 秒);② 我超时时表上挂的已经是**别人**开的新一代(我这代早settle
-        // 了),拿它当证据会让一个已经健康的 scope 被上一代的迟到超时按住。
-        // 🔴 只**查表**、不铸造(2026-08-12 合并码重扫 confirmed):快失败路径上 probe 的 .finally 先跑
-        // (清 inFlight + evictIfIdle 销号),这里若用 scopeState() 会**重建**一个新空条目——它 inFlight
-        // 恒 undefined ⇒ 冷却不开、又没人再销,每个快失败的 scope 就永久留一条(R4-M2 那条只增内存线
-        // 换了个入口)。观测口 terminalWindowJoinsInFlightForTest 的头注同判据:检查者不许创建它要检查的状态。
         const st = stateByStore.get(store)?.get(scopeForPull);
         if (st !== undefined && st.inFlight === probe)
             openCooldown(store, scopeForPull, st);
-        // detail 用 `err.message` 而不是 `String(err)`:后者会调用抛出值自己的 toString,而那本身可能再抛
-        // (逃出本兜底,把降级变成故障)。非 Error 抛出值就如实说"不是 Error",不去问它任何问题。
         recordFailOpen("server.fleet.snapshot-terminal-window-unavailable", err instanceof Error ? err.message : "terminal-window read threw a non-Error value");
-        return seeded; // durable 读失败只失去跨进程兜底;本进程 seed 照常(读它不碰后端)
+        return seeded;
     }
     finally {
         if (timer !== undefined)
             clearTimeout(timer);
     }
 }
-/**
- * test-only:把熔断冷却**提前**到现在(等价于"冷却期已过"),**不动**在飞读的登记。
- *
- * 为什么只清冷却:冷却期是墙钟(10s),测试不该真等;而"在飞读的复用是否会把毒 promise 传给后来者"
- * 恰恰是要被测的行为,清掉它就等于把待测对象删了。生产路径不引用本函数(与
- * `resetFailOpenRecorderForTest` 同一姿势:测试面显式,不给生产留旁路)。
- */
 export function clearTerminalWindowCooldownForTest(store, scope) {
     scopeState(store, scope).coolingUntil = undefined;
 }
-/** test-only:这个 store 目前还记着几个 scope(codex R4-M2 的空闲销号有没有真的销)。 */
 export function trackedTerminalWindowScopesForTest(store) {
     return stateByStore.get(store)?.size ?? 0;
 }
-/**
- * test-only:下一次开流会不会**合流到**当前这代在飞的读(与 {@link sharedRead} 同一份判据,不另抄常数)。
- *
- * 为什么需要它:挂死的读永不 settle,那一代会一直留在表上、只被复用窗按龄挡掉。测试要断言"后端恢复后
- * 的下一次开流读得到行",前置条件恰恰是"毒代已过复用窗"——那条前置条件必须**等出来**(轮询本谓词),
- * 不能靠"上一条连接自己吃满预算 + 一次客户端往返"凑出的那几毫秒墙钟余量(实测 8~28ms,既无因果保证
- * 也无下界 ⇒ 负载敏感偶发红)。读到的是快照:表里没有这一 scope 就是"不会合流"。
- *
- * ⚠️ 刻意**不走** `scopeState`(它会顺手建表项)——观测口不许改被观测的状态(`trackedTerminalWindow
- * ScopesForTest` 钉的空闲销号计数会被它污染)。
- */
 export function terminalWindowJoinsInFlightForTest(store, scope) {
     return joinsInFlight(stateByStore.get(store)?.get(scope)?.inFlight, Date.now());
 }
-/** 后来者是否加入这一代在飞的读:仍在自己的预算之内才加入(见上方取舍段);更老的那代已被放弃,不加入。
- *  抽成具名谓词的唯一理由是**单一属主**——测试的观测口({@link terminalWindowJoinsInFlightForTest})与
- *  生产的合流决策必须由同一行代码回答,否则测试里那份常数复制件会在实现改判据的那天悄悄失效。 */
 function joinsInFlight(probe, now) {
     return probe !== undefined && now - probe.startedAt < FLEET_SNAPSHOT_TERMINAL_READ_BUDGET_MS;
 }
-/** 合流层:同 (store, scope) 上**同时只有一代**在飞的读;后来者加入仍在预算内的那一代,settle 即销号。 */
 function sharedRead(store, scope) {
     const st = scopeState(store, scope);
     const existing = st.inFlight;
@@ -276,65 +129,44 @@ function sharedRead(store, scope) {
     const entry = {
         startedAt: Date.now(),
         rows: readRecentTerminalWorkflowRows(store, scope).finally(() => {
-            // 只销自己那一号:一次慢读期间可能已经开始了下一代(本次先 settle 的竞态下,清空会误删新号)。
             if (st.inFlight === entry) {
                 st.inFlight = undefined;
                 evictIfIdle(store, scope, st);
             }
         }),
     };
-    // 所有等待方都可能因为超预算先走(race),没有 catch 的 promise 会变成 unhandledRejection 把进程带下去。
     entry.rows.catch(() => undefined);
     st.inFlight = entry;
     return entry;
 }
-/**
- * `Promise.all` 的**等齐**版:等**每一支**都落地,再决定成败(有失败就抛第一个失败原因)。
- *
- * 为什么不能用 `Promise.all`(codex R5-H1):它在**第一支**失败时立刻 reject,而兄弟支还挂在后端上。
- * 于是这一代探针提前销号,超时的调用方看到"我这代已经不在表上了"就不开熔断(那条判据本意是排除
- * 快失败),下一条连接照样再发一批 —— 正是这套机制要防的放大。等齐之后,"探针还在飞"与"后端还有
- * 我发出去的活"这两件事重新同义,代际熔断的判据才成立。
- */
 async function allOrFirstFailureAfterAllSettled(work) {
     const settled = await Promise.allSettled(work);
     const values = [];
     for (const r of settled) {
         if (r.status === "rejected")
-            throw r.reason; // 第一支失败的原因原样上抛(调用方统一收成 fail-open)
+            throw r.reason;
         values.push(r.value);
     }
     return values;
 }
-/** 读本体(抛错/超时由 {@link recentTerminalWorkflowRows} 统一收成 fail-open)。 */
 async function readRecentTerminalWorkflowRows(store, scope) {
     const cutoff = Date.now() - FLEET_SNAPSHOT_TERMINAL_WINDOW_MS;
-    /** 窗判据的时间轴 = 「这一行最后变成现在这样是什么时候」:终态行恒有 `endedAt`,回落 `createdAt`
-     *  (与 core `reap` 的 `endedAt ?? createdAt` 同一口径——两处对「这行多老」必须给同一个答案)。 */
     const settledAt = (r) => r.endedAt ?? r.createdAt;
-    // 每个终态各扫一页(店侧下推 status + limit),再按结束时刻归并。不用"一次不带 status 的取页":那会被
-    // 同 scope 里更新的 running 行挤掉真正要找的终态行。
     const pages = await allOrFirstFailureAfterAllSettled(TERMINAL_WORKFLOW_STATUSES.map((status) => store.listByScope(scope, { status, limit: FLEET_SNAPSHOT_TERMINAL_SCAN_LIMIT })));
     const windowed = pages
         .flat()
         .filter((s) => s.scope === scope && settledAt(s) >= cutoff)
-        .sort((a, b) => settledAt(b) - settledAt(a) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)) // 同刻结束按 id 定序:快照不许随机
+        .sort((a, b) => settledAt(b) - settledAt(a) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
         .slice(0, FLEET_SNAPSHOT_TERMINAL_MAX_ROWS);
-    // summary 不带 doneCount/startedCount(core `WorkflowRunSummary` 没有这两位),而面板行的其余供数都在
-    // 它上面——与其在这里另写一份"近似"投影(两份投影必漂,本仓在 startedCount 口径上已吃过一次),不如
-    // 取回整行走**同一个** {@link buildFleetWorkflowRow}。代价=每行一次主键点读,受行数上限硬界(≤20),
-    // 且只发生在开流那一拍、同 scope 并发还会合流。
     const runs = await allOrFirstFailureAfterAllSettled(windowed.map((s) => store.get(s.id)));
     const rows = [];
     for (const [i, run] of runs.entries()) {
         if (!run)
-            continue; // list 与 get 之间被 reap 掉:诚实跳过,不为一个不存在的 run 造行
-        // `store.get` 是**无 scope 门**的裸读(带门的是 core 的 `getWorkflowRun`)——id 虽然来自本 scope 的
-        // 列表,仍按真行的 scope 复核一次:租户轴上宁可多判一次,也不靠"来源可信"。
+            continue;
         if (run.scope !== scope)
             continue;
         if (!isTerminalWorkflowStatus(run.status) || settledAt(run) < cutoff)
-            continue; // 读回时已不在窗内/已不是终态
+            continue;
         rows.push(buildFleetWorkflowRow(windowed[i].id, run));
     }
     return rows;

package/dist/fleet/subagent-tail-bus.js

@@ -1,30 +1,6 @@
-/**
- * SubagentTailBus(design/151 S2 server 半场,[1520]{core} 提货单)——per-agent **live tail** 的进程内
- * 分发总线。core 1.370 起后台子代 lane 向宿主 `onForwardEvent` 转发的每一帧带 `bgAgentId`(a* 句柄,
- * TaskEventIdentity 顶层平铺;sync/steer 子代无 tag,wa* 走自己的 observer lane)——两条 run 腿
- * (sync=http/server.ts、bg=runs.ts)的 fwdInternals 按 tag 存在性把帧 publish 进来,
- * `GET /v1/runs/:id/subagents/:handle/stream` 按句柄订阅。
- *
- * 语义边界(与 [1497] A2 的「replay+tail」故事各占一半):
- *  - **嵌套归并**(core 复审发现 #5):core recordingForward 在每层 bg 边界覆写 bgAgentId——host wire 上
- *    整棵委托子树的帧一律带**最外层** a* 句柄;对嵌套 a* 行开 tail 流=只有 heartbeat(它的帧归并进外层
- *    句柄的流,按 parentToolCallId 区分)。core JSDoc 补句已 ask。
- *  - **live-only**:从订阅时刻起,replica-local(帧只在宿主 run 所在副本产生)——历史/终报走 durable
- *    replay 面(`GET .../subagents/:handle/output` + AgentTranscript),meta 帧如实声明。
- *  - **有界背压**:每订阅者有界队列(TAIL_QUEUE_CAP),慢消费者丢**最旧**帧并在下一次 drain 前插入一枚
- *    `{type:"lagged", dropped}` 诚实标记帧——绝不无界缓冲(死对端=内存增长),绝不静默丢。
- *  - **投影在 publish 侧一次**(projectTailFrame):与 sync 主流的 forward 投影同 builder 同纪律
- *    (§E1:tool 帧走 whitelist+redact builder,text verbatim=owner 自己的模型输出同信任类,
- *    reasoning 过 redactSecrets)——每帧投影一次,N 个订阅者共享同一投影对象(只读约定)。
- *
- * 订阅形 = subscribeWorkflow 同姿势:push 迭代器,消费端显式驱动,断连调 `it.return()` 清订阅
- * (parked next() 不观察 closed 旗——不清理=死订阅者队列永驻)。
- */
 import { redactSecrets } from "../trace/redact.js";
 import { taskProgressEventData, toolStartEventData, toolEndEventData } from "../trace/project.js";
 const TAIL_QUEUE_CAP = 512;
-/** core forward 事件 → wire 投影(sync 主流五分支同源;不认识的帧类型=null 不发——tail 面只承诺
- *  content 五类,新 core 帧类型先经这里显式收编再出 wire)。 */
 export function projectTailFrame(e) {
     const t = e.type;
     if (t === "task_progress") {
@@ -32,11 +8,11 @@ export function projectTailFrame(e) {
     }
     if (t === "tool_start") {
         const tsv = e;
-        return { type: "tool_start", ...toolStartEventData(tsv) }; // label 现由 builder 自带(1.258),外拼冗余已清
+        return { type: "tool_start", ...toolStartEventData(tsv) };
     }
     if (t === "tool_end") {
         const te = e;
-        return { type: "tool_end", ...toolEndEventData(te) }; // label 现由 builder 自带,外拼冗余已清(同 tool_start 1.258 先例)
+        return { type: "tool_end", ...toolEndEventData(te) };
     }
     if (t === "text_delta") {
         const td = e;
@@ -48,9 +24,8 @@ export function projectTailFrame(e) {
     }
     return null;
 }
-/** 有界 put(FIFO 逐最老)——`Map` 的迭代序即插入序,取首键即最老。 */
 function putBounded(map, key, value) {
-    map.delete(key); // 重写=刷新它的插入序(值真变了的活句柄不该按最初那次登记的年龄被逐)
+    map.delete(key);
     map.set(key, value);
     if (map.size > HOST_MODE_CAP) {
         const oldest = map.keys().next();
@@ -58,59 +33,21 @@ function putBounded(map, key, value) {
             map.delete(oldest.value);
     }
 }
-/** 句柄→供给形登记的容量上限(FIFO 逐最老)。诊断料,不是账本——满了逐最老,读侧缺席退回 "unknown"
- *  (诚实降级:把"我知道"退成"我不知道",不会退成一个错答案)。 */
 const HOST_MODE_CAP = 4096;
 export class SubagentTailBus {
     subs = new Map();
-    /**
-     * a\* 句柄 → 该句柄**自己的宿主腿**的供给形。
-     *
-     * 🔴 键必须是**句柄**,不是「查看时用的那条 run」(codex 复审 high,2026-08-14 采纳):
-     * session-scoped 子代(`backgroundScope:"session"`)活得比派它的那条 run 久,而订阅方寻址用的是
-     * 「派它的 run ?? 当前活跃 run」——同一会话里 A 腿(带 forwardSubagentEvents)派的子代,完全可能
-     * 被经**后起的 B 腿**(没带)去看。按 run/会话键答题在这一档会**确定性谎报**(A=on 被答成
-     * progress_only ⇒ 客户端提前放弃真内容;反向 ⇒ 永久空等)。按句柄登记则天然正确:登记发生在
-     * **产出这一帧的那条闭包**里,帧上的 bgAgentId 与它的宿主腿是同一件事,不经任何寻址推断。
-     *
-     * 时间轴与降级:子代产出第一帧之前 = 无登记 ⇒ 路由出 `"unknown"`(诚实:还不知道);宿主腿在别的
-     * 副本 ⇒ 本副本永远收不到它的帧 ⇒ 同样 `"unknown"`(而不是拿本地同会话的无关腿冒充);容量逐出
-     * 同理只会把 `"on"/"progress_only"` 退成 `"unknown"`,不会退成错答案。
-     * ⚠️ `progress_only` 形下 task_progress **照来**,所以那一档同样在子代首拍 tick 就登记上了——
-     * 不需要"先有内容帧"才能学到"没有内容帧"。
-     */
     modeByHandle = new Map();
-    /** 三条 run 腿的 forward 回调里逐帧调(在 `hasSubscribers` 快门**之前**——没人在听时也要学,
-     *  否则晚开的 tail 永远读不到供给形)。同值重复写是 no-op(热路径只付一次 Map.get)。 */
     noteHandleContentMode(bgAgentId, mode) {
         if (this.modeByHandle.get(bgAgentId) === mode)
             return;
         putBounded(this.modeByHandle, bgAgentId, mode);
     }
-    /**
-     * 句柄终态时**撤销**登记(三条腿的 `onTaskNotification` 观察者调,与 `task_settled` 帧同处)。
-     *
-     * 🔴 为什么必须撤(codex 复审 round2 high,2026-08-14 采纳):后台子代可以用**原 a\* 句柄**进入下一个
-     * 复活周期(`POST /v1/runs/:id/subagents/:target/resume` → core `registerBackgroundAgent({ id:
-     * reviveRow.handle })`),而新周期的宿主腿是**另一条 run**,它的 forwardSubagentEvents 完全可能相反。
-     * 不撤的话,新周期首帧之前 meta 会把**上一周期**的供给形当成本周期的答案:上周期 on / 本周期
-     * progress_only ⇒ 客户端等一个永远不来的内容;反向 ⇒ 提前放弃真内容。撤到 `"unknown"` 是唯一诚实的
-     * 中间态(新周期首帧一到自然重新登记)。
-     * 非 a\* 句柄(bash / monitor 那些从未登记过的句柄)进来是 no-op。
-     *
-     * 残余(如实记,不假装没有):撤销之后若还有**同周期的迟到帧**进来,会按那条腿的模式重新登记一次
-     * ——值仍是「刚结束那个周期」的真话,只是万一紧接着发生复活、且新周期首帧未到,那一瞬读到的是旧周期
-     * 的答案。core 今天把终态通知排在最后一条 forward 之后(fleet-bus 同注),复活又是人手动作,这条窗
-     * 实际上不可达;真要关死需要给句柄加墓碑态,代价大于一位诊断标签的收益,故不做。
-     */
     forgetHandleContentMode(bgAgentId) {
         this.modeByHandle.delete(bgAgentId);
     }
-    /** 路由读(按 tail 的 target 句柄)。缺席 = 不知道,路由出 `"unknown"`。 */
     handleContentMode(bgAgentId) {
         return this.modeByHandle.get(bgAgentId);
     }
-    /** 两条 run 腿的 fwdInternals 调用点:帧已投影(projectTailFrame),null 不进来。 */
     publish(bgAgentId, frame) {
         const set = this.subs.get(bgAgentId);
         if (!set)
@@ -126,7 +63,6 @@ export class SubagentTailBus {
             sub.wake?.();
         }
     }
-    /** 有无订阅者(publish 侧的免投影快门:没人听就不投影)。 */
     hasSubscribers(bgAgentId) {
         return (this.subs.get(bgAgentId)?.size ?? 0) > 0;
     }
@@ -139,9 +75,6 @@ export class SubagentTailBus {
         }
         set.add(sub);
         const cleanup = () => {
-            // 复审 #2(实证):路由对同一迭代器 return() 两次(close 钩+finally,设计如此)——非幂等 cleanup 在
-            // 两次调用之间若有新请求 subscribe 同句柄(map 重建新集),第二次会把**新订阅者的集**从 map 删掉
-            // (静默只剩 heartbeat)。幂等门+集同一性校验双保险。
             if (sub.closed)
                 return;
             sub.closed = true;
@@ -180,7 +113,5 @@ export class SubagentTailBus {
         return it;
     }
 }
-/** 进程单例(defaultTaskRegistry 同款姿势):bus 语义本就是进程内 replica-local,两条 run 腿与路由
- *  直接 import,不穿长参数列表;测试自 new 独立实例。 */
 export const defaultSubagentTailBus = new SubagentTailBus();
 //# sourceMappingURL=subagent-tail-bus.js.map