@sema-agent/client-core 0.7.0 → 0.8.1

package/dist/detachWire.js

@@ -0,0 +1,182 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/detachWire.ts` **拆**搬 —— 判定半场 +
+ *    cancel-arm 台账进包,**信号路径的裸 fetch 发射留宿主**(设计稿 §3 表 `S/detachWire.ts` 那条
+ *    脚注:`:221` 裸 cancel = TUI 留,宪法例外 census C1-4)。
+ *
+ * 🔴 **拆缝画在哪、为什么**:`fireBestEffortDetachCancel` 是**信号处理器**里同步 DISPATCH 的
+ *    fire-and-forget —— 它成立的前提是「进程正在被 SIGINT/SIGTERM 拆掉,不能 await、不能构造重对象」。
+ *    这套前提是 **Node 进程模型**的,浏览器/桌面渲染进程根本没有信号;而且它有意**绕开 SDK verb**
+ *    (`AgentClient.runs.cancel` 是 await 型,包一层 void+catch 反而把纪律面弄模糊)——那是壳的
+ *    宪法例外,不该被搬成「库里有一处裸 fetch」。⇒ 发射留宿主,库出**台账 + 读口**。
+ *
+ * 🔴 **模块级状态与读写口同包**([multiclient-migration-batch-discipline]):`cancelArm` 一份,
+ *    写口 `armDetachCancel`(seamQueryEngine.ask 在头真拼上请求时调)、读口 `isDetachArmed`
+ *    (`detachDurableOffHint` 的第一道门)/ `detachedTaskId`(分诊文案)/ `detachCancelArm`
+ *    (**宿主发射腿**唯一取件口)全在本文件。壳侧 shim 的 `fireBestEffortDetachCancel` 从
+ *    `detachCancelArm()` 取件 ⇒ 仍然只有一份台账;壳若自己再存一份 = 头发了但 hint 判不出、
+ *    Ctrl+C 取消不掉(两个静默失效各一半)。
+ *
+ * 🔴 env 读取走 `hostEnv()`(本包零 `process`,portability 门盯着);Node 下同一对象 ⇒ 壳侧
+ *    「不传 env 参数」的调用点行为一字节不变。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * detachWire — headless `-p` detach-on-disconnect wire (重连腿 M1 壳半场, 2026-07-15,
+ * design/HEADLESS-RECONNECT-DESIGN.md §6 M1; mirrors finalVerifyWire/limitsWire in shape).
+ *
+ * WHY: the `/v1/tasks/stream` lane ABORTS the run on client disconnect by design (anti token-burn —
+ * this is also the interactive cancel mechanism). server ≥1.196 accepts an opt-in escape hatch: the
+ * `x-detach-on-disconnect: true` REQUEST HEADER makes a disconnect DETACH the run instead — it keeps
+ * running to its terminal and lands in the durable run ledger (`GET /v1/runs/:id`; a deployment with
+ * no durable ledger 400s fail-loud — the shell's self-spawned engine always sets DB_BACKEND=local,
+ * so the ledger is always there on that lane). M1 = header + cancel fallback ONLY; reconnect/resume
+ * (R1 runs.events lane-switch / R2 idempotent re-POST) is M2/M3 — NOT here.
+ *
+ * 铁律 1 (design §2.1): the header is stamped ONLY on the headless `-p` lane (seamQueryEngine.ask),
+ * live-gated on SEMA_LIVE_BASEURL exactly like finalVerifyWire — the interactive REPL lane
+ * (seamQuery.ts) never imports this module, so Esc/interrupt keeps its disconnect==cancel semantics
+ * verbatim, and the mock/pty lanes never see the header (offline projection byte-identical).
+ *
+ * 铁律 2 (design §2.2): once detach is on, a USER abort must carry an explicit best-effort cancel —
+ * a detached run would otherwise burn tokens to completion in the background after Ctrl+C. The
+ * cancel-arm half of this module (armDetachCancel / the host's fireBestEffortDetachCancel) is
+ * consumed by the `-p` SIGINT handler and the SIGTERM/SIGHUP tail-frame handler (cli/print.ts):
+ * fire-and-forget `POST /v1/runs/:id/cancel` (the SDK RunsResource.cancel verb, runs.js — verified:
+ * no body), never awaited on the signal path. taskId not yet captured (pre X-Task-Id window) ⇒
+ * ACCEPTED uncancellable window — detach's inherent cost, no waiting introduced (design §2.2 记账).
+ *
+ * PRECEDENCE (off wins; otherwise DEFAULT ON):
+ *  a) `SEMA_HEADLESS_DETACH` env = 'false'/'0' (settings env lane, fail-soft — any other value
+ *     including typos stays default-on, finalVerifyWire discipline)          → off.
+ *  b) VERSION GATE: SEMA_ENGINE_URL in play (user-supplied external engine) and `/health` CONFIRMS
+ *     version <1.196.0 (or no version field = pre-1.96)                      → off + SEMA_DEBUG log.
+ *     Unlike limitsWire (warn-and-send: an old server drops an unknown BODY field server-side), here
+ *     we GATE: an old server silently ignores the unknown HEADER, so a disconnect still kills the
+ *     run — sending it would only manufacture a false "detached" belief downstream (判死文案 would
+ *     lie). Probe unreachable / unparsable response ⇒ fail-soft SEND (can't confirm staleness; the
+ *     stream POST itself fails loudly if the engine is truly down).
+ *  c) self-spawn lane (no SEMA_ENGINE_URL): release-pinned ≥1.197.0 — trusted, no probe, header on.
+ */
+import { hostEnv } from './hostEnv.js';
+import { versionSupportsLimits } from './limitsWire.js';
+/** The server ≥1.196 opt-in header: disconnect ⇒ detach (run continues to durable terminal). */
+export const DETACH_HEADER = 'x-detach-on-disconnect';
+/** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。'false'/'0' = off。 */
+export const HEADLESS_DETACH_ENV = 'SEMA_HEADLESS_DETACH';
+/**
+ * First server version that honors the detach header — 1.196.0, the SAME floor as the limits wire
+ * (both landed in the [857] batch), so the version predicate is limitsWire.versionSupportsLimits
+ * re-exported under the detach name (one comparator, two wires — 抽共用 per design).
+ */
+export const DETACH_WIRE_MIN_ENGINE = [1, 196, 0];
+/** True when the engine version string satisfies the detach-wire minimum (≥1.196.0). Unparsable ⇒ false. */
+export const versionSupportsDetach = versionSupportsLimits;
+/**
+ * The settings-lane off-switch: `SEMA_HEADLESS_DETACH` = 'false' or '0' (case-insensitive) disables
+ * the header. Any other value (empty/'true'/typo) = default ON — fail-soft, a settings typo never
+ * flips the lane silently to the strict-alignment (disconnect-kills-run) mode (finalVerifyWire 纪律).
+ */
+export function headlessDetachDisabledByEnv(env = hostEnv()) {
+    const v = env[HEADLESS_DETACH_ENV]?.trim().toLowerCase();
+    return v === 'false' || v === '0';
+}
+/**
+ * Version-gate probe: GET `${baseUrl}/health`, read `version`. Returns FALSE only when the engine is
+ * CONFIRMED older than 1.196.0 (parsable old version, or a healthy response with no version field =
+ * pre-1.96). Unreachable / timeout / non-2xx / unparsable JSON ⇒ TRUE (fail-soft: can't confirm
+ * staleness — the header is harmless on the wire, and the stream POST fails loudly on a dead engine).
+ * Same probe shape as limitsWire.engineLimitsSupportWarning (1.5s budget, never throws).
+ */
+export async function engineSupportsDetach(baseUrl, opts) {
+    const fetchImpl = opts?.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 1500);
+    try {
+        const res = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}/health`, {
+            method: 'GET',
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return true; // engine answered oddly — can't confirm staleness, fail-soft send
+        const body = (await res.json());
+        const version = typeof body?.version === 'string' ? body.version : undefined;
+        // No version field = pre-1.96 engine — definitely older than 1.196.0: gate the header.
+        return versionSupportsDetach(version);
+    }
+    catch {
+        return true; // unreachable/timeout — cannot confirm staleness, fail-soft send
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Resolve the detach header for a headless `-p` submit. DEFAULT ON; `SEMA_HEADLESS_DETACH`=false|0
+ * ⇒ off (env-off); SEMA_ENGINE_URL external engine confirmed <1.196.0 ⇒ off (old-engine — the caller
+ * SEMA_DEBUG-logs it). Self-spawn lane (no SEMA_ENGINE_URL) never probes (pin ≥1.197 trusted).
+ * The caller MUST live-gate on SEMA_LIVE_BASEURL (finalVerifyWire 同款) — mock/pty lanes never
+ * reach this resolver, so they never see the header.
+ */
+export async function resolveHeadlessDetach(baseUrl, env = hostEnv(), opts) {
+    if (headlessDetachDisabledByEnv(env))
+        return { on: false, reason: 'env-off' };
+    if (env.SEMA_ENGINE_URL) {
+        // user-supplied external engine — the only lane where an old server is possible
+        const ok = await engineSupportsDetach(baseUrl, opts);
+        if (!ok)
+            return { on: false, reason: 'old-engine' };
+    }
+    return { on: true, reason: 'default-on' };
+}
+// ── durable-off 400 的人话分诊([862]④,1.0.5 小件5) ─────────────────────────────────────────────────
+//
+// server ≥1.196 对带 detach 头但无 durable 账本(无 runStore / 无 sessionId)的 submit 判 400 fail-loud
+// (server http/server.ts [854]①b:静默忽略 = 断连仍杀 run,与 caller 声明语义相反;detach 成功了结果
+// 也无处可查)。壳自 spawn 引擎恒 DB_BACKEND=local 永不命中;命中面 = SEMA_ENGINE_URL 外接引擎显式关
+// durable。裸 `sema: API Error: 400 · x-detach-on-disconnect requires a durable run …` 是 server 视角
+// 的契约话,用户不知道下一步 —— 追加一行人话(supplement, never mask:API Error 行字面保留)。
+/** server 400 body 判别锚(server.ts sendJson 原文:"x-detach-on-disconnect requires a durable run
+ *  (a run store + sessionId) — without one the detached result would be unqueryable")。 */
+export const DETACH_DURABLE_OFF_400_ANCHOR = 'x-detach-on-disconnect requires a durable run';
+/**
+ * detach 头引发的 durable-off 400 → 人话提示行;其它错误(非 400 / 非该 body / 头没发过)恒 null
+ * (绝不误伤其它 400 —— sandboxImageProfile 400 等各有自己的 hint)。判别三重:头确已发出
+ * (isDetachArmed —— armDetachCancel 只在头拼上请求时调)+ SDK APIError.status===400 + message 含
+ * server 原文锚(sdk errors.js toApiError: msg = body.error 原文)。
+ */
+export function detachDurableOffHint(err) {
+    if (!isDetachArmed())
+        return null;
+    const e = err;
+    if (e?.status !== 400)
+        return null;
+    const msg = typeof e?.message === 'string' ? e.message : '';
+    if (!msg.includes(DETACH_DURABLE_OFF_400_ANCHOR))
+        return null;
+    return 'engine has durable runs disabled — detach-on-disconnect unavailable; interrupted turns will abort (SEMA_HEADLESS_DETACH=false to silence)';
+}
+let cancelArm = null;
+/** Arm the signal-path cancel fallback (called by ask when the detach header is actually sent). */
+export function armDetachCancel(arm) {
+    cancelArm = arm;
+}
+/** Whether this process sent the detach header on its `-p` stream (the 判死文案 upgrade gate). */
+export function isDetachArmed() {
+    return cancelArm !== null;
+}
+/** The detached run's durable taskId, when already captured (X-Task-Id) — for the triage copy. */
+export function detachedTaskId() {
+    return cancelArm?.getTaskId() ?? null;
+}
+/**
+ * 🔴 **宿主发射腿的唯一取件口**(拆缝的库这一侧)。宿主的 `fireBestEffortDetachCancel` 必须从这里
+ * 取 arm,**不许自己再存一份** —— 台账两份 = 头发了但 hint 判不出 / Ctrl+C 取消不掉。
+ * null = 没 arm 过(detach 关 / 版本门挡下 / mock 车道)⇒ 宿主零动作、零行为变化。
+ */
+export function detachCancelArm() {
+    return cancelArm;
+}
+/** Test-only reset (module state is process-lifetime; `-p` is a one-shot). */
+export function _resetDetachWireForTest() {
+    cancelArm = null;
+}

package/dist/engineSessionParam.d.ts

@@ -1,7 +1,11 @@
-/** 当前会话的 session 参数值;undefined = 两源都缺席(动态 import 未落地的头几毫秒)——
- *  调用方此时不带参(legacy 面软拍放行;强制面 404 自回落,下次重试自然带上)。 */
+/** 当前会话的 session 参数值;undefined = 端未装 SessionPort,或端自己也还没有值。 */
 export declare function engineSessionParam(): string | undefined;
 /** spread 便捷形:`{ ...engineSessionParamSpread() }` → `{ session: '<sid>' }` 或 `{}`。 */
 export declare function engineSessionParamSpread(): {
     session?: string;
 };
+/**
+ * 当前活跃引擎 run 的 id(壳 = `engineToolDetach.getActiveEngineTaskId()`)。
+ * 库内多处 durable 动词要「宿主 run」做寻址第一跳,统一从这里取,不各自 import 端模块。
+ */
+export declare function activeEngineRunId(): string | undefined;

package/dist/engineSessionParam.js

@@ -1,31 +1,29 @@
 /**
+ * ⇄ B6 批搬迁(2026-07-27,多端改造设计稿 §3 B6 + B4「四残件」之 session-id port):
+ *    cli `src/sema/engineSessionParam.ts` 搬入,唯一改动 = **取值源换 port**。
+ *
  * engineSessionParam — durable run 面 `?session=` 参数的统一派生([1501]§三,server 1.246 起
  * legacy 八面软拍纪律:带了且不匹配=404,没带=warn-once 放行,二拍将把「没带」也 404;新面
  * A/B(taskOutput/taskStop)与 subagentOutput 则出生即强制)。
  *
- * 取值语义 = run 绑定的会话(本壳所有 durable 动词的目标 run 都是本会话自有 run,见扩散面复审
- * 镜头二 W-A:寻址 id 逐跳自有,T13 不变量保证会话 id turn 内不漂移)。优先级与
- * fleetClient.effectiveScopeSessionId() / engineSubagentOutput 同源:引擎捕获值
- * (getLiveSessionId,首轮 done 回填的权威值)优先,未捕获时退壳 boot-time getSessionId()
- * (SB-5:同命名空间,引擎首轮认养壳自报 id)。动态 import 姿势同两处先例,避免把
- * bootstrap/state 重图拖进静态依赖。
+ * 取值语义 = run 绑定的会话(本端所有 durable 动词的目标 run 都是本会话自有 run)。
+ *
+ * 🔴 **搬迁的唯一差分**:壳里这里是「`getLiveSessionId()`(引擎捕获值)优先,退
+ * `bootstrap/state.getSessionId()`(壳 boot-time id),后者靠动态 import 落地」——**两级优先与
+ * 那个动态 import 都是宿主生命周期资产**,整体上移到 `SessionPort.currentSessionId()`
+ * (壳侧 shim 里原样保留那两级 + 动态 import,行为一字节不变)。库这边只剩「取一个值 + 空串归一」。
  *
  * 🔴 [1501] 空串陷阱:`?session=`(空值)按「带了且不匹配」处理=404 —— 本 helper 恒不返回
  * 空串:要么真值要么 undefined(调用方 spread 姿势 `...(s ? { session: s } : {})`)。
+ *
+ * 🔴 端漏装 SessionPort 的后果**不是**「少个查询参数」:session-bound run 的 taskOutput /
+ * taskStop / subagentOutput 三面一律 404 fail-closed ⇒ 子代读面整条静默哑掉。所以
+ * `hostSession()` 计 miss,宿主自检 `hostPortMisses()` 恒应为空。
  */
-import { getLiveSessionId } from './liveSessionStore.js';
-let shellSessionIdFn;
-void import('../bootstrap/state.js')
-    .then(m => {
-    shellSessionIdFn = m.getSessionId;
-})
-    .catch(() => {
-    // 极端环境缺模块:退化为只用 getLiveSessionId(),与 fleetClient/engineSubagentOutput 同款容错
-});
-/** 当前会话的 session 参数值;undefined = 两源都缺席(动态 import 未落地的头几毫秒)——
- *  调用方此时不带参(legacy 面软拍放行;强制面 404 自回落,下次重试自然带上)。 */
+import { hostSession } from './host.js';
+/** 当前会话的 session 参数值;undefined = 端未装 SessionPort,或端自己也还没有值。 */
 export function engineSessionParam() {
-    const sid = getLiveSessionId() ?? shellSessionIdFn?.();
+    const sid = hostSession()?.currentSessionId();
     return typeof sid === 'string' && sid.length > 0 ? sid : undefined;
 }
 /** spread 便捷形:`{ ...engineSessionParamSpread() }` → `{ session: '<sid>' }` 或 `{}`。 */
@@ -33,3 +31,11 @@ export function engineSessionParamSpread() {
     const s = engineSessionParam();
     return s ? { session: s } : {};
 }
+/**
+ * 当前活跃引擎 run 的 id(壳 = `engineToolDetach.getActiveEngineTaskId()`)。
+ * 库内多处 durable 动词要「宿主 run」做寻址第一跳,统一从这里取,不各自 import 端模块。
+ */
+export function activeEngineRunId() {
+    const id = hostSession()?.activeRunId();
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}

package/dist/engineWireTarget.d.ts

@@ -0,0 +1,14 @@
+export interface EngineWireTarget {
+    baseUrl: string;
+    token?: string;
+    principal: string;
+}
+/** 装/卸引擎 wire 目标。传 null 卸回 env 派生。返回还原函数。 */
+export declare function installEngineWireTarget(t: EngineWireTarget | null): () => void;
+/**
+ * 当前引擎 wire 目标。null = 无 wire(离线/mock/浏览器未装)—— 调用方走各自的回落路径,
+ * **不是**错误态。
+ */
+export declare function engineWireTarget(): EngineWireTarget | null;
+/** 诊断开关(壳侧 `process.env.SEMA_DEBUG` 的等价读;本包零 process)。 */
+export declare function engineWireDebugEnabled(): boolean;

package/dist/engineWireTarget.js

@@ -0,0 +1,53 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):子代 wire 族里**逐字重复**的 `wireConfig()`
+ *    (SEMA_LIVE_BASEURL / SEMA_LIVE_TOKEN / SEMA_LIVE_PRINCIPAL 三读 + 'anon:shell-live' 缺省)
+ *    收成一份。
+ *
+ * 🔴 收编前的事实(壳 HEAD 2aa1d3e 实测,`grep -rln 'function wireConfig' src/sema/`):
+ *    **七**份而不是六份 —— `engineSubagentOutput.ts:30` · `engineSubagentSteer.ts:26` ·
+ *    `engineTaskHandleWire.ts:40` · `engineCompactWire.ts:77` · `engineSubagentTail.ts:40` ·
+ *    `engineDelegatedPrompt.ts:80` · **`planReviewWire.ts:36`**。
+ *    ⚠️ 本批搬入的是前六份(子代/fleet 族);**第七份 `planReviewWire` 不在 B6 范围**,仍留壳内
+ *    —— 它是下一批的收编候选,别以为已经收干净了(这条更正即为「按名字数数会数漏」的实例)。
+ *    七份漂移不是假想:`engineCompactWire` 那份已经多了一行 principal 注释,`engineSubagentSteer`
+ *    那份 token 读法与其它几份的 `...(cfg.token ? …)` spread 姿势不同步。
+ *
+ * 🔴 env 读取走 `hostEnv()`(本包零 `process` —— portability 门盯着)。Node 下 `hostEnv()` 返回的
+ *    就是 `process.env` 那个同一对象 ⇒ 壳侧行为一字节不变;浏览器宿主返回 `{}` ⇒ `baseUrl`
+ *    缺席 ⇒ 每个 verb 走自己既有的「无 wire」回落路径(不是报错)。
+ *    ⚠️ web/桌面宿主要用这条 wire,**不能靠 env** —— 用 `installEngineWireTarget()` 显式装。
+ */
+import { hostEnv } from './hostEnv.js';
+/** 显式装配(非 Node 宿主唯一的入口;装了就**优先于** env,便于桌面/web 一页多引擎)。 */
+let installed = null;
+/** 装/卸引擎 wire 目标。传 null 卸回 env 派生。返回还原函数。 */
+export function installEngineWireTarget(t) {
+    const prev = installed;
+    installed = t;
+    return () => {
+        installed = prev;
+    };
+}
+/**
+ * 当前引擎 wire 目标。null = 无 wire(离线/mock/浏览器未装)—— 调用方走各自的回落路径,
+ * **不是**错误态。
+ */
+export function engineWireTarget() {
+    if (installed !== null)
+        return installed;
+    const env = hostEnv();
+    const baseUrl = env.SEMA_LIVE_BASEURL;
+    if (!baseUrl)
+        return null;
+    return {
+        baseUrl,
+        // principal must match the run's owner (stamped by the live stream) — the owner-gated routes answer
+        // 404 for non-owners (no existence oracle), so a missing header reads as "run not found".
+        ...(env.SEMA_LIVE_TOKEN ? { token: env.SEMA_LIVE_TOKEN } : {}),
+        principal: env.SEMA_LIVE_PRINCIPAL ?? 'anon:shell-live',
+    };
+}
+/** 诊断开关(壳侧 `process.env.SEMA_DEBUG` 的等价读;本包零 process)。 */
+export function engineWireDebugEnabled() {
+    return Boolean(hostEnv().SEMA_DEBUG);
+}

package/dist/fleet/fleetLedger.d.ts

@@ -0,0 +1,132 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6 + §2.5 拆缝表):cli `src/sema/fleetClient.ts` 的
+ *    **帧消费半场** —— `applyFrame` 的帧体 upsert + own/foreign 判别 + `recordOwnEngineRun` /
+ *    `recordBgParentRun` / `recordBgTerminalFacts` 台账三写 + `retained` 终态留存池 + 帧间时钟
+ *    补偿 + 模块级 bg 读面(`readEngineActiveBgTasks` / `isFleetSessionScoped`)。
+ *
+ * 留在 TUI(设计稿 §2.4.2-B):`AgentClient` 构造与 consume/重连循环 · `main` 合成行 ·
+ * `selection` 游标 · `viewed` 的所有者(AppState)· `SEMA_DEBUG_FILE` 行字段落盘探针 ·
+ * hook_notice 的**写 store** 半场(判定在 notifications.ts,本文件只做分发)。
+ *
+ * ── B6 三处删债(每条都有直证,不是「看起来能删」)──────────────────────────────────────────
+ *
+ * 🔴 **P1-4 / `makeSessionScopingFetch` 退役**:壳里为了给 fleet 流塞 `?session=` 注了一个自定义
+ *   `fetch`(fleetClient.ts:201-227,注入点 :604)—— 归属过滤是最不该留在端上的东西。SDK 0.0.117
+ *   `fleet.stream({ session })` / `fleet.snapshot({ session })` 已是一等参数(`resources/fleet.d.ts`
+ *   实读),本包出 `fleetStreamOptions()` 直接给出那个参数,**壳侧删掉整个 fetch 包装器**。
+ *
+ * 🔴 **G12 / `rowSessionTag` 整条删(比任务书说的更彻底,附直证)**:任务书写「ownerSessionId /
+ *   rootSessionId 防御读删」。实测 server **1.291.0** `dist/http/server.js` 的 `streamFleet`:
+ *   ```js
+ *   const stripT = (r) => { const { scope: _s, sessionId: _sid, ...rest } = r; … }
+ *   const stripW = (r) => { const { scope: _s, sessionId: _sid, ...rest } = r; … }
+ *   ```
+ *   ⇒ task/workflow **行**上 `scope` 与 `sessionId` **双双被剥**,而 `rootSessionId`/`ownerSessionId`
+ *   在 `FleetTaskRow`/`FleetWorkflowRow` 里**从来就不存在**(server 自己的 `fleet-bus.d.ts` 实读)。
+ *   ⇒ `rowSessionTag(row)` 三个键**全部恒 undefined**,整条腿是死的 —— 不是「删两个键留一个」。
+ *   后果方向核过:这条腿在 `ownTaskRow` 里是**放行**位(命中即判 own),死 ⇒ 从不放行 ⇒ 删掉
+ *   **零可观测差异**(其余两腿:祖链 own-run 台账 / `sessionScoped` 让位,原样保留)。
+ *   ⚠️ 对照:`bg_notification` 帧上 server 只剥 `ownerScope`/`ownerSessionId`,**`rootSessionId`
+ *   与 `sessionId` 照发** ⇒ 通知臂的 `ownByRoot` 那条腿**是活的,保留**。同一个名字两条腿、
+ *   一死一活 —— 这正是「判据锚在决定结果的量上」要求逐条核而不是按名字一刀切的地方。
+ *
+ * 🔴 **G19 / 一次性快照**:`fleet.snapshot({session})` 已是 SDK 一等 verb(开流→取 snapshot 帧→
+ *   关流封装),壳的 `engineBgProbe.ts:8-9` 自述「引擎 fleet 面只有 SSE,没有一次性口」已过期。
+ *   本包出 `fleetSnapshotOptions()`;`engineBgProbe` 的手抄开流即断由壳侧换 verb(见交接报告)。
+ *
+ * ── 单实例纪律 ────────────────────────────────────────────────────────────────────────────────
+ * `liveBgViews` 是 module 级 Set:写者 = 每个 `createFleetLedger()`,读者 = 引擎温切门
+ * (`readEngineActiveBgTasks`)与代际让位读面(`isFleetSessionScoped`)。两份实例 = 温切门恒读空
+ * ⇒ respawn 会静默杀掉在飞 bg 子代。
+ */
+import type { FleetFrame, FleetTaskRow } from '@sema-agent/sdk';
+import { type FleetTaskView, type FleetWorkflowView, type ProjectTasksOptions } from './fleetProjection.js';
+/** 终态行留存宽限窗(187 的 agents 页把完成会话留在列表;窗过即净,防长会话堆行)。 */
+export declare const TERMINAL_RETAIN_MS = 60000;
+export interface EngineActiveBgTask {
+    id: string;
+    name?: string;
+    status: string;
+    /** fleet 行的 parentId(spawn 该子代的 run 行 id;顶层 run 行缺席)—— killed 残局合成通知的
+     *  own/foreign 判别用。 */
+    parentId?: string;
+}
+export interface EngineActiveBgReading {
+    tasks: EngineActiveBgTask[];
+    /** true = 至少一条 fleet 流当前连着(读数新鲜);false = 断线期 last-known(可能 stale)或无 live 源。 */
+    fresh: boolean;
+}
+/**
+ * server 代际证据读面:任一 live fleet 源的 meta 报过 `sessionScoped=true`。
+ * true ⇒ 到达本连接的**行帧**已经过 server 会话过滤,端侧行级 own 判别可以让位。
+ * 🔴 只覆盖【行帧】:通知帧的 own-run 台账判别不看本标,恒开(1.244 对缺 ownerSessionId 的通知
+ *    仍广播,fail-closed 是 1.245+)。
+ */
+export declare function isFleetSessionScoped(): boolean;
+/** 引擎侧在飞 bg 子代读数(union 所有未 dispose 的源,按 row.id 去重)。无 live 源 ⇒ `{[], false}`。 */
+export declare function readEngineActiveBgTasks(): EngineActiveBgReading;
+/**
+ * 清空所有 live 源的终态留存池 —— 会话切换(/clear、REPL 内 resume、fork)信号一到就调。
+ * R7:留存池是渲染层宽限窗,快照臂刻意不清它(重连不该抽走行);但换了会话继续渲上一会话的
+ * 终态行(名字 = objective 派生)就是跨会话残影。
+ */
+export declare function clearAllRetainedFleetRows(): void;
+/** 测试钩:摘掉所有登记的视图(同进程多组断言之间互不污染)。 */
+export declare function __resetFleetLedgerRegistryForTests(): void;
+/**
+ * `client.fleet.stream(...)` 的会话过滤参数。缺席(端未装 SessionPort / 还没有会话 id)⇒ `{}`
+ * = principal 级视图,**与 1.37 之前逐字同行为**(不是错误态)。
+ */
+export declare function fleetStreamOptions(): {
+    session?: string;
+};
+/** G19:`client.fleet.snapshot(...)` 的参数(同上;首屏/温切探针用)。 */
+export declare function fleetSnapshotOptions(opts?: {
+    timeoutMs?: number;
+}): {
+    session?: string;
+    timeoutMs?: number;
+};
+export interface FleetLedgerHooks {
+    /**
+     * hook_notice 帧的**写 store** 半场(判定在 `classifyHookNoticeFrame`,本台账只做分发)。
+     * 返回值忽略;不给 = 该帧被静默丢弃(端没有承载面时的正确行为)。
+     */
+    onHookNotice?(frame: unknown, sessionScoped: boolean): void;
+}
+export interface FleetLedgerStatus {
+    connected: boolean;
+    version: number | null;
+    scoped: boolean | null;
+    sessionScoped: boolean | undefined;
+    bgNotifyFailClosed: boolean;
+    taskCount: number;
+    workflowCount: number;
+}
+export interface FleetLedger {
+    /** 消费一帧(consumer-side active-set update-in-place / remove)。 */
+    applyFrame(frame: FleetFrame): void;
+    /** 连接态由宿主的 consume 循环告知(台账自己不开流)。 */
+    setConnected(v: boolean): void;
+    /**
+     * 把当前 Map 投影成渲染行。`nowMs` 驱动帧间时钟补偿与留存池过期。
+     * `rowFilter` 必填(端专属决策,见 fleetProjection 头注)。
+     */
+    project(nowMs: number, opts: ProjectTasksOptions & {
+        /** 正在被查看的行不过期(用户读报告中途被抽走=清障变添堵)。 */
+        viewingTaskId?: string | undefined;
+    }): {
+        tasks: FleetTaskView[];
+        workflows: FleetWorkflowView[];
+    };
+    status(): FleetLedgerStatus;
+    /** 摘掉模块级读面登记(宿主 dispose 时必调,否则温切门读到僵尸源)。 */
+    dispose(): void;
+    /** 测试直取:当前 task 行原样(顺序 = 插入序)。 */
+    __rowsForTest(): FleetTaskRow[];
+}
+/**
+ * 建一个 fleet 帧台账。**不开流、不构造 client** —— 宿主的 consume 循环把解码后的帧喂进来。
+ * (这条切缝就是设计稿 §2.5 给 fleetClient 划的那一刀:帧体归库、连接归端。)
+ */
+export declare function createFleetLedger(hooks?: FleetLedgerHooks): FleetLedger;