@sema-agent/client-core 0.14.0 → 0.16.0

package/dist/model/providerAuth.d.ts

@@ -0,0 +1,155 @@
+/**
+ * providerAuth.ts — **模型供应商凭证轨**的双轨 seam(design/166 §5「B 档:设备码流」,2026-08-04)。
+ *
+ * ## 边界(先说清楚它**不是**什么)
+ *
+ * 🔴 [reuse-single-sso-no-parallel-auth]:registry SSO(cloudAuth,「登录 sema」那条)**绝不复用、
+ * 绝不被改造**。本文件是**模型供应商**的凭证轨(拿一把 API key 去调某家模型),与 registry 登录轨
+ * 物理分文件、零共享代码。两者唯一的相似点是「都会弹一个浏览器」,那不构成复用理由。
+ *
+ * 🔴 design/166 §6 已定谳:**授权码 + PKCE(C 档)不做、不留 seam、不留枚举位** —— Anthropic 侧
+ * 条款明文禁止第三方代理其订阅凭证,而公开实现全都依赖冒用官方 client_id + 伪装 UA。本文件里
+ * 因此**只有** api_key 与 device_code 两轨,没有第三个 kind 位。
+ *
+ * ## 能力真值 = 目录键 ∧ 包内实现(两者与)
+ *
+ * 目录(design/165 §2)里的 `deviceAuth` 键**只是能力开关**,client_id 与端点**绝不目录化下发**
+ * (远端可改鉴权端点 = 钓鱼面)。所以 UI 是否显示「Sign in with device code」的判据是
+ * `supportsDeviceCodeAuth(id, preset.deviceAuth)`:
+ *   · 目录说有、包里没有 ⇒ **不显示**(防目录先行造出一个点了没反应的假 affordance);
+ *   · 包里有、目录没说 ⇒ **不显示**(那家还没被目录确认支持)。
+ *
+ * ## 🔴 `DEVICE_AUTH_PROVIDERS` 今天是**空表**(宁空勿假 —— 这是有意的,不是没写完)
+ *
+ * 设计档写「首发 1 家:GitHub Copilot 形」。落码时的事实是:device flow 需要一个 **client_id**,
+ * 而公开可查到的 Copilot client_id 全部是**别的编辑器插件自己的** app id(copilot.vim / VS Code
+ * 扩展)。把它们编进我们的包 = 以别人的 app 身份向 GitHub 发起授权,与 §6 判 C 档出局时用的
+ * **同一条判据**(「冒用官方 client_id」是主动欺骗,不是灰区)。我们自己名下的 OAuth app 尚未
+ * 申请 ⇒ 这一格的诚实值是**空**,而不是先填一个能跑的别人的号。
+ *
+ * 空表不是把这条腿废了:轮询器、退避、上限、终态词表全部在位并被门覆盖(门用一份合成 descriptor
+ * 跑真 HTTP)。**注册一家 = 往这张表加一行**,零代码改动。在那之前 `supportsDeviceCodeAuth`
+ * 对每一家如实返回 false,UI 不显示该选项 —— 这正是「能力真值 = 两者与」自带的正确降级。
+ *
+ * ## key 到手之后
+ *
+ * 🔴 **落盘不在包内做**。`poll()` 把 key 原样返给宿主,宿主走**与手填完全相同的那条路径**
+ * (壳 = `applyOnboard.ts` 写 settings `env.MODEL_API_KEY`)。两树都没有 auth.json 实体,
+ * 本文件也不新建任何持久面(design/166 §5 复核 M4:零新持久面,禁造)。
+ */
+import type { ProviderPreset, ProviderDeviceAuthHint } from './providerPresets.js';
+/**
+ * 一个 provider 可用的凭证轨。
+ * `api_key` 是现状唯一轨(手填,env 名来自 preset.authEnv);`device_code` 是 B 档新轨。
+ */
+export type ProviderAuthMethod = {
+    kind: 'api_key';
+    env: string;
+} | {
+    kind: 'device_code';
+    providerId: string;
+};
+/**
+ * 设备码端点三件套 —— **编译进包**(design/165 §2 红线:client_id / token 端点 / authorize 端点
+ * 一律不进目录)。
+ */
+export interface DeviceCodeEndpoints {
+    clientId: string;
+    /** RFC 8628 device authorization endpoint。 */
+    deviceCodeUrl: string;
+    /** token endpoint(轮询这一个)。 */
+    tokenUrl: string;
+    /** 申请的 scope(留空 = 不发这个参数)。 */
+    scope?: string;
+}
+/** 包内登记的一家设备码 provider。 */
+export interface DeviceAuthProvider {
+    /** 与目录/preset 的 `id` 同一个命名空间(用户 settings 里的持久引用)。 */
+    providerId: string;
+    label: string;
+    endpoints: DeviceCodeEndpoints;
+}
+/**
+ * 包内实现的设备码 provider 表。
+ * 🔴 **今天是空的,理由见文件头**(宁空勿假:没有我们自己名下的 client_id 之前,填一行 = 冒用)。
+ * 加一家 = 加一行;端点必须 https(门 ④a 逐行校)。
+ */
+export declare const DEVICE_AUTH_PROVIDERS: readonly DeviceAuthProvider[];
+/** 包内是否实现了这一家(能力真值的一半)。 */
+export declare function deviceAuthProviderFor(providerId: string): DeviceAuthProvider | undefined;
+/**
+ * UI 是否显示「设备码登录」= **目录说有** ∧ **包里有实现**。
+ * 任一缺席 ⇒ false(见文件头「能力真值」段)。
+ */
+export declare function supportsDeviceCodeAuth(providerId: string, catalogHint: ProviderDeviceAuthHint | undefined): boolean;
+/**
+ * 一家 provider 摆给用户的轨(顺序 = UI 呈现序)。`api_key` 恒在;`device_code` 只在能力真值成立时出。
+ */
+export declare function providerAuthMethods(preset: ProviderPreset): ProviderAuthMethod[];
+/**
+ * 一次 `poll()` 的结局。
+ *
+ * 🔴 比设计档草案多两个终态,理由是诚实:草案只有 `pending|ok|expired`,于是
+ * 「用户点了拒绝」与「会话被本地取消」都只能冒充 `expired`(= 骗用户「过期了,再来一次」,
+ * 而事实是再来一次还会被拒 / 是他自己取消的)。两者各占一位:
+ *   · `denied`    —— 授权服务器说 access_denied;
+ *   · `cancelled` —— 本地调过 `cancel()`。
+ */
+export type DeviceCodeStatus = 'pending' | 'ok' | 'expired' | 'denied' | 'cancelled';
+export interface DeviceCodePollResult {
+    status: DeviceCodeStatus;
+    /** 只在 `ok` 时在场。🔴 宿主拿去走与手填同一条落盘路径;包内零持久面。 */
+    key?: string;
+    /** 人话细节(分诊用;绝不带 key、绝不带完整响应体)。 */
+    detail?: string;
+}
+/**
+ * 一次设备码会话。**宿主驱动**:UI 渲大字码 + URL,自己按 `intervalMs` 起节拍调 `poll()`
+ * (等待型判据,不固定拍)。包内不起定时器 —— 定时器是宿主资产(与 `TimersPort` 同一条纪律)。
+ */
+export interface DeviceCodeSession {
+    /** 用户要在浏览器里输入的大字码。 */
+    userCode: string;
+    /** 用户要打开的验证页。 */
+    verificationUrl: string;
+    /** 建议轮询间隔(毫秒)。429 / slow_down 之后会**变大**,宿主每拍都该重读这个值。 */
+    intervalMs: number;
+    /** 本会话的墙钟终点(min(服务端 expires_in, 15min 上限))。 */
+    expiresAtMs: number;
+    poll(): Promise<DeviceCodePollResult>;
+    cancel(): void;
+}
+/**
+ * 设备码流的宿主注入面。
+ * 🔴 `nowMs` **必填**:5s 间隔与 15min 上限都是墙钟判据,而本包绝不偷读时钟
+ * (与 `catalog.ts` / `AdapterContext.now` 同一口径)。宿主传 `() => Date.now()`。
+ */
+export interface DeviceCodeAuthOptions {
+    nowMs: () => number;
+    /** 传输注入口(缺省全局 `fetch`)。 */
+    fetchImpl?: typeof fetch;
+    /** 单次 HTTP 预算(缺省 `DEVICE_CODE_HTTP_TIMEOUT_MS`)。 */
+    timeoutMs?: number;
+}
+/** 轮询间隔下限(RFC 8628 建议 5s;服务端给更大的值时听服务端的)。 */
+export declare const DEVICE_CODE_MIN_INTERVAL_MS = 5000;
+/** 会话墙钟上限(design/166 §5:15min)。服务端 `expires_in` 更短时听服务端的。 */
+export declare const DEVICE_CODE_MAX_LIFETIME_MS: number;
+/** 429 / slow_down 的退避增量(RFC 8628 §3.5 就是「加 5 秒」)。 */
+export declare const DEVICE_CODE_BACKOFF_STEP_MS = 5000;
+/** 单次 HTTP 预算。 */
+export declare const DEVICE_CODE_HTTP_TIMEOUT_MS = 10000;
+/**
+ * 开一次设备码会话 —— **端点由调用方给**(包内表里那一行,或门的合成 descriptor)。
+ * 🔴 端点是**编译进包的常量**,不是远端数据,所以本函数不对它再做白名单;真正的门是
+ * 「client_id/端点绝不目录化下发」(design/165 §2 红线)+ 表内每行必须 https(门 ④a)。
+ *
+ * 失败(网络 / 非 2xx / 缺 user_code)⇒ **throw**(§C1 三选一里的 throw):开不出会话就是开不出,
+ * 绝不返回一个永远 pending 的假会话。
+ */
+export declare function openDeviceCodeSession(endpoints: DeviceCodeEndpoints, opts: DeviceCodeAuthOptions): Promise<DeviceCodeSession>;
+/**
+ * 按 providerId 开设备码会话(UI 入口)。
+ * 包内没有这一家 ⇒ **throw**(UI 本就不该显示这个选项;走到这里说明能力判据被绕过了)。
+ */
+export declare function beginDeviceCodeAuth(providerId: string, opts: DeviceCodeAuthOptions): Promise<DeviceCodeSession>;

package/dist/model/providerAuth.js

@@ -0,0 +1,190 @@
+/**
+ * 包内实现的设备码 provider 表。
+ * 🔴 **今天是空的,理由见文件头**(宁空勿假:没有我们自己名下的 client_id 之前,填一行 = 冒用)。
+ * 加一家 = 加一行;端点必须 https(门 ④a 逐行校)。
+ */
+export const DEVICE_AUTH_PROVIDERS = [];
+/** 包内是否实现了这一家(能力真值的一半)。 */
+export function deviceAuthProviderFor(providerId) {
+    return DEVICE_AUTH_PROVIDERS.find((p) => p.providerId === providerId);
+}
+/**
+ * UI 是否显示「设备码登录」= **目录说有** ∧ **包里有实现**。
+ * 任一缺席 ⇒ false(见文件头「能力真值」段)。
+ */
+export function supportsDeviceCodeAuth(providerId, catalogHint) {
+    if (catalogHint?.kind !== 'device_code')
+        return false;
+    return deviceAuthProviderFor(providerId) !== undefined;
+}
+/**
+ * 一家 provider 摆给用户的轨(顺序 = UI 呈现序)。`api_key` 恒在;`device_code` 只在能力真值成立时出。
+ */
+export function providerAuthMethods(preset) {
+    const out = [{ kind: 'api_key', env: preset.authEnv }];
+    if (supportsDeviceCodeAuth(preset.id, preset.deviceAuth)) {
+        out.push({ kind: 'device_code', providerId: preset.id });
+    }
+    return out;
+}
+/** 轮询间隔下限(RFC 8628 建议 5s;服务端给更大的值时听服务端的)。 */
+export const DEVICE_CODE_MIN_INTERVAL_MS = 5000;
+/** 会话墙钟上限(design/166 §5:15min)。服务端 `expires_in` 更短时听服务端的。 */
+export const DEVICE_CODE_MAX_LIFETIME_MS = 15 * 60 * 1000;
+/** 429 / slow_down 的退避增量(RFC 8628 §3.5 就是「加 5 秒」)。 */
+export const DEVICE_CODE_BACKOFF_STEP_MS = 5000;
+/** 单次 HTTP 预算。 */
+export const DEVICE_CODE_HTTP_TIMEOUT_MS = 10_000;
+/** 异常 → 短 detail(绝不带栈、绝不带响应体)。 */
+function shortError(e) {
+    return (e instanceof Error ? e.message : String(e)).slice(0, 160);
+}
+/** POST application/x-www-form-urlencoded,收 JSON。返回 {status, body}(body 解析不动 ⇒ null)。 */
+async function postForm(url, form, fetchImpl, timeoutMs, signal) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    if (signal.aborted)
+        controller.abort();
+    else
+        signal.addEventListener('abort', onAbort, { once: true });
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers: { accept: 'application/json', 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams(form).toString(),
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        let body = null;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = null; // 非 JSON 响应 ⇒ 当作「说不出所以然」,由调用方按 status 判(绝不回显正文)
+        }
+        return { status: res.status, body };
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', onAbort);
+    }
+}
+/**
+ * 开一次设备码会话 —— **端点由调用方给**(包内表里那一行,或门的合成 descriptor)。
+ * 🔴 端点是**编译进包的常量**,不是远端数据,所以本函数不对它再做白名单;真正的门是
+ * 「client_id/端点绝不目录化下发」(design/165 §2 红线)+ 表内每行必须 https(门 ④a)。
+ *
+ * 失败(网络 / 非 2xx / 缺 user_code)⇒ **throw**(§C1 三选一里的 throw):开不出会话就是开不出,
+ * 绝不返回一个永远 pending 的假会话。
+ */
+export async function openDeviceCodeSession(endpoints, opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? DEVICE_CODE_HTTP_TIMEOUT_MS;
+    const abort = new AbortController();
+    const started = opts.nowMs();
+    const { status, body } = await postForm(endpoints.deviceCodeUrl, { client_id: endpoints.clientId, ...(endpoints.scope !== undefined ? { scope: endpoints.scope } : {}) }, fetchImpl, timeoutMs, abort.signal);
+    if (status < 200 || status >= 300) {
+        throw new Error(`device code request failed: HTTP ${status}`);
+    }
+    const grant = (body ?? {});
+    const deviceCode = typeof grant.device_code === 'string' ? grant.device_code : '';
+    const userCode = typeof grant.user_code === 'string' ? grant.user_code : '';
+    const verificationUrl = typeof grant.verification_uri_complete === 'string'
+        ? grant.verification_uri_complete
+        : typeof grant.verification_uri === 'string'
+            ? grant.verification_uri
+            : '';
+    if (deviceCode === '' || userCode === '' || verificationUrl === '') {
+        throw new Error('device code response missing device_code / user_code / verification_uri');
+    }
+    const serverLifetimeMs = typeof grant.expires_in === 'number' && grant.expires_in > 0 ? grant.expires_in * 1000 : undefined;
+    const lifetimeMs = Math.min(serverLifetimeMs ?? DEVICE_CODE_MAX_LIFETIME_MS, DEVICE_CODE_MAX_LIFETIME_MS);
+    const serverInterval = typeof grant.interval === 'number' && grant.interval > 0 ? grant.interval * 1000 : undefined;
+    const session = {
+        userCode,
+        verificationUrl,
+        intervalMs: Math.max(serverInterval ?? DEVICE_CODE_MIN_INTERVAL_MS, DEVICE_CODE_MIN_INTERVAL_MS),
+        expiresAtMs: started + lifetimeMs,
+        poll: async () => poll(),
+        cancel: () => {
+            if (terminal === null)
+                terminal = { status: 'cancelled', detail: 'cancelled by the host' };
+            abort.abort();
+        },
+    };
+    /** 终态一旦落定就恒定(拿到 key 之后再 poll 不重复拨号)。 */
+    let terminal = null;
+    /** 下一次允许真正拨号的墙钟时刻(间隔是硬的,不靠调用方自律)。 */
+    let nextDialAtMs = started;
+    async function poll() {
+        if (terminal !== null)
+            return terminal;
+        const now = opts.nowMs();
+        if (now >= session.expiresAtMs) {
+            // 本地上限先于服务端判:上限是我们对用户的承诺,不该靠服务端良心。
+            terminal = { status: 'expired', detail: 'device code session exceeded its lifetime — start a new one' };
+            return terminal;
+        }
+        if (now < nextDialAtMs) {
+            return { status: 'pending', detail: 'polled before the interval elapsed — no request was sent' };
+        }
+        let res;
+        try {
+            res = await postForm(endpoints.tokenUrl, {
+                client_id: endpoints.clientId,
+                device_code: deviceCode,
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            }, fetchImpl, timeoutMs, abort.signal);
+        }
+        catch (e) {
+            if (terminal !== null)
+                return terminal; // cancel() 把在飞请求打断了 —— 终态已落定
+            // 单次网络失败不是终态:设备码流本就是长轮询,下一拍再试(退避一格避免打点)。
+            nextDialAtMs = opts.nowMs() + session.intervalMs;
+            return { status: 'pending', detail: `poll failed, will retry: ${shortError(e)}` };
+        }
+        if (terminal !== null)
+            return terminal;
+        nextDialAtMs = opts.nowMs() + session.intervalMs;
+        const token = (res.body ?? {});
+        const err = typeof token.error === 'string' ? token.error : '';
+        if (res.status === 429 || err === 'slow_down') {
+            session.intervalMs += DEVICE_CODE_BACKOFF_STEP_MS;
+            nextDialAtMs = opts.nowMs() + session.intervalMs;
+            return { status: 'pending', detail: 'rate limited — backing off' };
+        }
+        if (typeof token.access_token === 'string' && token.access_token.length > 0) {
+            terminal = { status: 'ok', key: token.access_token };
+            return terminal;
+        }
+        if (err === 'authorization_pending')
+            return { status: 'pending' };
+        if (err === 'expired_token') {
+            terminal = { status: 'expired', detail: 'the device code expired — start a new one' };
+            return terminal;
+        }
+        if (err === 'access_denied') {
+            terminal = { status: 'denied', detail: 'the user declined the authorization request' };
+            return terminal;
+        }
+        if (res.status < 200 || res.status >= 300) {
+            return { status: 'pending', detail: `poll got HTTP ${res.status}, will retry` };
+        }
+        // 认不出的 error 码:不冒充终态(别把一个我们没见过的码说成「过期了」),下一拍再试。
+        return { status: 'pending', detail: err === '' ? 'unrecognised token response' : `unrecognised error: ${err}` };
+    }
+    return session;
+}
+/**
+ * 按 providerId 开设备码会话(UI 入口)。
+ * 包内没有这一家 ⇒ **throw**(UI 本就不该显示这个选项;走到这里说明能力判据被绕过了)。
+ */
+export async function beginDeviceCodeAuth(providerId, opts) {
+    const provider = deviceAuthProviderFor(providerId);
+    if (provider === undefined) {
+        throw new Error(`device code auth is not supported for provider "${providerId}" in this build ` +
+            '(DEVICE_AUTH_PROVIDERS has no entry — the UI must gate on supportsDeviceCodeAuth())');
+    }
+    return openDeviceCodeSession(provider.endpoints, opts);
+}

package/dist/model/providerPresets.d.ts

@@ -25,7 +25,23 @@ export type ProviderPreset = {
     consoleUrl?: string;
     /** 没账号时的注册入口。与 `consoleUrl` 同页的家不重复填(缺席 = 用 consoleUrl 那条)。 */
     signupUrl?: string;
+    /**
+     * 🆕 design/165 §2 + design/166 §5(2026-08-04):**设备码能力开关**(B 档)。
+     *
+     * 🔴 它只是**开关**,不携带 client_id / token 端点 / authorize 端点 —— 那些编译进
+     * `model/providerAuth.ts` 的 `DEVICE_AUTH_PROVIDERS`。理由:目录是远端可改的数据,
+     * 让它决定鉴权端点 = 把钓鱼面下发给客户端(design/165 §2 红线④,CI 的 validate.mjs
+     * 里有对应的机械不变式)。
+     * 🔴 能力真值 = **本键在场 ∧ 包内有实现**(`supportsDeviceCodeAuth`)——目录先行不造 affordance。
+     */
+    deviceAuth?: ProviderDeviceAuthHint;
 };
+/** 目录里的设备码能力开关(只有 kind 与文档链接;凭证参数一律不进目录)。 */
+export interface ProviderDeviceAuthHint {
+    kind: 'device_code';
+    /** 该家自己的设备码说明页(纯链接;拿不准就不填,绝不编 URL)。 */
+    docsUrl?: string;
+}
 export type ModelFamily = {
     id: string;
     name: string;

package/dist/notifications.d.ts

@@ -202,6 +202,10 @@ export declare function outstandingAbandonedCount(): number;
 export interface NotificationDropCounters {
     bgDedupDropped: number;
     bgCrossChannelDropped: number;
+    /** 🔴 [2393] notif-F1:workflow 侧「已通知过」而被静默吞掉的投递次数(第三处漏网拼法)。
+     *  与 bg 两格同理:去重与误吞在行为上都是「不入队」,不记账就在观测上等价。恒可 >0(推送帧与
+     *  probe 链双投自免是正当的);**异常增长** = runId 铸法变了或两条链 id 不同域,真完成在被吞。 */
+    workflowDedupDropped: number;
     stuckTickResets: number;
     bgWatchRevivalPromoted: number;
     bgWatchCollectedUnprobed: number;

package/dist/notifications.js

@@ -381,6 +381,19 @@ const outstandingRuns = new Map(); // runId → registeredAt(ms)
 // workflow(s) to finish」(CC 2.1.212 同形,wf-ui-cc2 ground truth)。仅通知计数变化 ——
 // notif-03 起「计数」含 `outstandingAbandonedCount()`,故 bg 半场的 TTL 放弃也发一次通知
 // (那一格变了,消费方要重渲「N 个后台任务已停止等待」)。
+//
+// 🔴 [2393] notif-F9(2026-08-03 全窗复审)**判据纠偏 + 契约写清**(裁定:机制不改,把口径写死)。
+// 复审的观察是「bg 半场信号不对称:放弃发通知、登记不发,而订阅面两个计数口都不含 bg ⇒ 一次 bg
+// 放弃叫醒全部订阅者却什么都没变(空转重渲)」。逐口核过之后这条**不成立**,但它指出的真缺口
+// (契约没写清)是真的,所以写在这里:
+//   · 订阅契约 = 「**任一可读计数**发生变化」,可读计数恰好三个:`outstandingWorkflowCount()` /
+//     `outstandingDeliverableWorkflowCount()` / `outstandingAbandonedCount()`;
+//   · bg **放弃**必须发:它改变第三个(`abandonedCount++`)—— 不是空转;
+//   · bg **登记**必须不发:bg 在飞数**没有**可读口(刻意:headless 退出门只认 workflow 半场,
+//     见 `outstandingDeliverableWorkflowCount` 的头注),不改变任何可读量的事件不许叫醒订阅者
+//     (叫醒 = 每次 async_launched 回执触发一次全树重渲,而消费方一个字都读不到新东西)。
+//   ⇒ 「不对称」是这条契约的**正确后果**,不是漏。谁想给 bg 在飞数开一个可读口,必须同批让
+//     `registerOutstandingBgTask` 发通知(两半共享前提,[paired-mechanisms-must-share-premise])。
 const outstandingListeners = new Set();
 function notifyOutstanding() {
     for (const l of [...outstandingListeners]) {
@@ -417,8 +430,20 @@ function abandonOutstanding(kind, id, reason) {
     if (!removed)
         return;
     abandonedCount++;
-    traceNotif(`abandoned ${kind} ${id} — reason=${reason}, waited > WATCH_TTL_MS(${WATCH_TTL_MS}ms); ` +
-        'no completion notification will ever be delivered for it');
+    const line = `abandoned ${kind} ${id} — reason=${reason}, waited > WATCH_TTL_MS(${WATCH_TTL_MS}ms); ` +
+        'no completion notification will ever be delivered for it';
+    traceNotif(line);
+    // 🔴 [2393] notif-F2(2026-08-03 全窗复审)**边界定谳**:本条修复到库边界为止,用户可见那一端
+    // 由宿主闭合,已挂提货单(`docs/refactor/README.md`「提货单 / 破坏性变更清单」节的**宿主侧待办**表,
+    // 背景与「库侧为什么停在这里」见 `docs/refactor/WAVE2-RESIDUALS.md` [2393] 那一节第 2 条)。
+    // 为什么不在库内补偿:
+    //   · `traceNotif` 受 SEMA_DEBUG 门控是**刻意**的 —— 那是诊断面;把放弃行为默认打进用户 stderr
+    //     等于库替宿主决定 UI(headless `-p` 的 stdout 是协议面,污染它是真回归);
+    //   · 走 `hostLog` 口需要 `notifications.ts` import `host.ts`,实测会把 **A 层闭包 22→24 文件**
+    //     (`run-client-core-portability-test.mjs` 的 `MAX_ADAPT_CLOSURE_FILES` 只许降)—— 为一条诊断
+    //     线把 A 层拽进宿主口体系,代价大于收益([no-hasty-compensation-final-fix-first] 三问);
+    //   · 用户可见那一端的**量**已经在场且可读:`outstandingAbandonedCount()`(+ `notificationDropCounters()`
+    //     六格)。缺的是三端的渲染,那是宿主工单,不是库内补偿位。
     notifyOutstanding();
 }
 /**
@@ -431,11 +456,19 @@ export function outstandingAbandonedCount() {
 }
 let bgDedupDropped = 0;
 let bgCrossChannelDropped = 0;
+let workflowDedupDropped = 0;
 let stuckTickResets = 0;
 let bgWatchRevivalPromoted = 0;
 let bgWatchCollectedUnprobed = 0;
 export function notificationDropCounters() {
-    return { bgDedupDropped, bgCrossChannelDropped, stuckTickResets, bgWatchRevivalPromoted, bgWatchCollectedUnprobed };
+    return {
+        bgDedupDropped,
+        bgCrossChannelDropped,
+        workflowDedupDropped,
+        stuckTickResets,
+        bgWatchRevivalPromoted,
+        bgWatchCollectedUnprobed,
+    };
 }
 let statusProbe = null;
 let watchTimer = null;
@@ -447,6 +480,18 @@ export function installWorkflowStatusProbe(probe) {
 }
 /** bg 子代生命周期号的首周期值(SendMessage 复活即 +1;wire 缺 seq ⇒ 按首周期解释)。 */
 const BG_FIRST_SEQ = 1;
+/**
+ * 🔴 [2393] notif-F8(2026-08-03 全窗复审):seq 归一的**唯一铸点**。
+ * 修前有两处各写各的:登记口 `Number.isFinite && >= BG_FIRST_SEQ` 才收(否则钳到首周期,再 floor),
+ * enqueue 口只有 `n.seq ?? BG_FIRST_SEQ`(零校验),而帧臂(`fleet/fleetLedger.ts` 的
+ * `applyBgNotification`)是**原样透传**。后果不是「多写一遍」而是两条通道的去重键会**错开**:
+ * server 哪天发 0 基 seq(或小数)⇒ watcher 合成走已钳成 1 的键 `id:1:status`,帧通道走原值键
+ * `id:0:status`,两键不撞 ⇒ 跨通道去重整体失效,同一次完成被喂给模型两遍。
+ * notif-02 立的是「键必须含 seq」,归一没收成单口就等于键的**语义**没收口。
+ */
+function normalizeBgSeq(seq) {
+    return typeof seq === 'number' && Number.isFinite(seq) && seq >= BG_FIRST_SEQ ? Math.floor(seq) : BG_FIRST_SEQ;
+}
 /**
  * 🔴 notif-02:观察台账的键是 **(taskId, seq) 复合键**,不是裸 taskId。
  * 裸 taskId 时 seq≥2 的复活周期与首周期同键 ⇒ 复活周期结构性进不了台账,而 watcher 存在的
@@ -495,7 +540,7 @@ export function registerOutstandingBgTask(taskId, description, prompt, seq) {
     if (typeof prompt === 'string' && prompt.length > 0 && !bgTaskPrompts.has(taskId)) {
         bgTaskPrompts.set(taskId, prompt);
     }
-    const cycle = typeof seq === 'number' && Number.isFinite(seq) && seq >= BG_FIRST_SEQ ? Math.floor(seq) : BG_FIRST_SEQ;
+    const cycle = normalizeBgSeq(seq); // notif-F8:唯一铸点
     const key = bgOutstandingKey(taskId, cycle);
     if (outstandingBgTasks.has(key))
         return;
@@ -595,7 +640,14 @@ function withProbeDeadline(p, timeoutMs) {
         const timer = setTimeout(() => {
             reject(new ProbeDeadlineError(timeoutMs));
         }, timeoutMs);
-        unrefTimer(timer);
+        // 🔴 [2393] notif-F7(2026-08-03 全窗复审)**不 unref**:这正是 `unrefTimer.ts:6-9` 逐字写死的
+        // 域词表-13 定谳所指的那一类 —— 「被 await 的 race/budget 臂上的定时器绝不能 unref(会让进程
+        // 在它 settle 前提前退出,RB-447 同形)」。本 deadline 定时器是 `await withProbeDeadline(...)`
+        // **唯一的 settle 来源**(probe 永不 settle 时):unref 之后若宿主此刻没有别的活句柄
+        // (watchTimer 自己也是 unref 的),事件循环判定可退出,回调不再执行,那一拍 tick 永不 settle
+        // —— notif-01① 「必有 settle 路径」的保证就不是自持的,而是押在「宿主别处总有活句柄」上。
+        // 两条成对臂已经保证它不会拖住进程:①probe settle 时下面两个 `clearTimeout(timer)` 必执行;
+        // ②它自己到点就 reject 并被 clear,寿命上界 = timeoutMs(默认 PROBE_TIMEOUT_MS)。
         p.then(v => {
             clearTimeout(timer);
             resolve(v);
@@ -616,14 +668,46 @@ let tickGeneration = 0;
  * 🔴 必须在重入护栏**之前**跑:清扫住在 tickWatchInner 里时,一个卡死的 probe 会连坐 TTL,
  * 于是「2h 上界」这个 `outstandingDeliverableWorkflowCount()` 正当性的另一半也一起失效。
  */
+/**
+ * 🔴 [2393] notif-F10(2026-08-03 全窗复审):**正被在飞 probe 臂持有**的键集(bg 侧存复合键,
+ * workflow 侧存 runId)。`abandonOutstanding` 自己的前提是「放弃必须是**真发生过**的事」,但它
+ * 上一版只挡住了「键不在台账」,没挡住「键正被在飞臂持有」:上一拍 probe 还在飞(它手里握着这
+ * 条目的快照),这一拍 sweep 判它超 TTL ⇒ 计数 +1 并打出「no completion notification will ever
+ * be delivered for it」,几十毫秒后那个 probe 返回 terminal ⇒ 照常合成并投递通知。
+ * 留痕是假话,`outstandingAbandonedCount()`(消费方据以渲「N 个后台任务已停止等待」的诚实计数)
+ * 被灌一格假数 —— 正是 notif-03 立案要根治的那一类观测面撒谎。
+ * 🔴 让位必须**自己有界**,否则它就变成 notif-01③ 刚修掉的那个形(「清扫住在 tick 体内 ⇒ 一个卡死的
+ * probe 连坐 TTL ⇒ headless 退出门恒真、进程永不退出」)。所以记的是**在飞臂的起始时刻**,
+ * 让位只在「这条臂还没超过它自己的 deadline」时成立:臂一旦活过 `probeTimeoutMs()`(= 它本该被
+ * 截断的时刻),它就不再是「马上会给出答案的那条臂」,TTL 照常执行。
+ * ⇒ 正常路径:多等一拍(5s),换来放弃计数不被灌假数;病理路径:与修前逐字同形,liveness 不变。
+ */
+const bgProbeInFlight = new Map();
+const runProbeInFlight = new Map();
+/** 在飞臂是否仍在它自己的 deadline 之内(超了就不再让位 —— 见上方 notif-F10 头注)。 */
+function probeArmStillWithinDeadline(startedAt, now) {
+    return startedAt !== undefined && now - startedAt <= probeTimeoutMs();
+}
 function sweepExpiredOutstanding(now) {
     for (const [key, meta] of [...outstandingBgTasks]) {
-        if (now - meta.registeredAt > WATCH_TTL_MS)
-            abandonOutstanding('bg-task', key, 'ttl');
+        if (now - meta.registeredAt <= WATCH_TTL_MS)
+            continue;
+        if (probeArmStillWithinDeadline(bgProbeInFlight.get(key), now)) {
+            // notif-F10:在飞臂正握着它、且还没超它自己的 deadline —— 这一拍不判放弃
+            // (判了就可能马上被那条臂证伪:计数与留痕当场成假话)。
+            traceNotif(`ttl sweep deferred for bg-task ${key}: a probe arm is still in flight within its deadline`);
+            continue;
+        }
+        abandonOutstanding('bg-task', key, 'ttl');
     }
     for (const [runId, registeredAt] of [...outstandingRuns]) {
-        if (now - registeredAt > WATCH_TTL_MS)
-            abandonOutstanding('workflow-run', runId, 'ttl');
+        if (now - registeredAt <= WATCH_TTL_MS)
+            continue;
+        if (probeArmStillWithinDeadline(runProbeInFlight.get(runId), now)) {
+            traceNotif(`ttl sweep deferred for workflow-run ${runId}: a probe arm is still in flight within its deadline`);
+            continue;
+        }
+        abandonOutstanding('workflow-run', runId, 'ttl');
     }
 }
 /** @param nowMs 时钟注入(仅测试钩用;生产走 Date.now())。 */
@@ -647,7 +731,7 @@ async function tickWatch(nowMs) {
     const myGeneration = ++tickGeneration;
     tickStartedAtMs = now;
     try {
-        await tickWatchInner();
+        await tickWatchInner(now);
     }
     finally {
         // 被强制复位过就别清:那面时间戳已经属于后来的那一拍了。
@@ -655,7 +739,9 @@ async function tickWatch(nowMs) {
             tickStartedAtMs = null;
     }
 }
-async function tickWatchInner() {
+/** @param now 本拍的时钟(与 `sweepExpiredOutstanding` **同一个来源** —— notif-F10 的让位判据比的是
+ *  「在飞臂活了多久 vs 它自己的 deadline」,两边取不同的钟就会得出 3 小时前起飞的荒谬结论)。 */
+async function tickWatchInner(now) {
     // bg agent 半场(与 workflow 半场同节拍;TTL 已提到 tickWatch 的护栏之前统一清扫。
     // probe 未装=mock/离线,只等推送补发)
     const bgProbe = bgStatusProbe;
@@ -686,6 +772,7 @@ async function tickWatchInner() {
                 continue;
             }
             let alive;
+            bgProbeInFlight.set(key, now); // notif-F10:在飞期间(且未超 deadline)sweep 不许把它判成「放弃」
             try {
                 const res = await withProbeDeadline(bgProbe(meta.taskId), probeTimeoutMs());
                 if (res === null || res === undefined)
@@ -695,6 +782,9 @@ async function tickWatchInner() {
             catch {
                 continue; // 探测失败(含 ProbeDeadlineError)不构成删除证据
             }
+            finally {
+                bgProbeInFlight.delete(key);
+            }
             if (!alive) {
                 outstandingBgTasks.delete(key); // 真终局 = 已送达的那个周期,收摊
                 continue;
@@ -713,6 +803,7 @@ async function tickWatchInner() {
         }
         if (!bgProbe)
             continue;
+        bgProbeInFlight.set(key, now); // notif-F10:同上 —— 在飞臂持有期间(未超 deadline)TTL 让位
         try {
             const res = await withProbeDeadline(bgProbe(meta.taskId), probeTimeoutMs());
             if (res?.terminal) {
@@ -730,6 +821,9 @@ async function tickWatchInner() {
         catch {
             // 单次探测失败(含 ProbeDeadlineError 截断)不放弃:网络抖动照旧,TTL 兜底
         }
+        finally {
+            bgProbeInFlight.delete(key);
+        }
     }
     const probe = statusProbe;
     for (const runId of [...outstandingRuns.keys()]) {
@@ -740,6 +834,7 @@ async function tickWatchInner() {
         }
         if (!probe)
             continue; // live client 未装(mock/离线)→ 只等推送
+        runProbeInFlight.set(runId, now); // notif-F10:在飞期间(且未超 deadline)sweep 不许把它判成「放弃」
         try {
             const res = await withProbeDeadline(probe(runId), probeTimeoutMs());
             if (res?.terminal) {
@@ -755,6 +850,9 @@ async function tickWatchInner() {
         catch {
             // 单次探测失败(含 ProbeDeadlineError 截断)不放弃:网络抖动照旧,TTL 兜底
         }
+        finally {
+            runProbeInFlight.delete(runId);
+        }
     }
 }
 /**
@@ -765,7 +863,7 @@ async function tickWatchInner() {
  */
 const bgNotifiedKeys = new Set();
 export function enqueueBgChildNotification(n) {
-    const cycle = n.seq ?? BG_FIRST_SEQ;
+    const cycle = normalizeBgSeq(n.seq); // notif-F8:与登记口同一个铸点(零校验的 `?? 1` 会让两条通道的键错开)
     const key = `${n.taskId}:${cycle}:${n.status}`;
     // 🔴 notif-03 同族(C5):两条静默 return 都记账 + 留痕 —— 不记账时「按设计去重」与
     // 「seq 丢了导致完成被吞」在观测上完全等价,而后者是用户永远收不到通知的那一类。
@@ -812,8 +910,17 @@ export function enqueueBgChildNotification(n) {
     });
 }
 export function enqueueEngineWorkflowNotification(c) {
-    if (notifiedRunIds.has(c.runId))
+    // 🔴 [2393] notif-F1(2026-08-03 全窗复审):这条静默 return 是 C5 收口的**第三处漏网拼法**。
+    // 同批把 bg 侧两条静默 return 都补了计数+留痕(上面 bgDedupDropped / bgCrossChannelDropped),
+    // 而它的孪生体 workflow 侧一条都没有 —— 而 `traceNotif` 的头注把执行标准写成「每条丢弃/放弃
+    // 路径都能在同一个前缀下 grep 到」。失败场景:`markEngineWorkflowNotified()`(外部通道 seed)
+    // 或 probe 链先记账后,推送帧再送同一 runId 的完成 ⇒ 这里静默吞掉,而「按设计去重」与
+    // 「一条真完成被误吞(runId 铸法变了 / 两条链 id 不同域)」在观测面上完全等价。
+    if (notifiedRunIds.has(c.runId)) {
+        workflowDedupDropped++;
+        traceNotif(`workflow notification suppressed (run already notified) runId=${c.runId} status=${c.status}`);
         return;
+    }
     // [2393] F-1:workflow 侧没有周期概念,周期维按首周期记(与 markEngineWorkflowNotified 同理)。
     markRunNotified(c.runId);
     cardEnqueuedRunIds.add(c.runId);
@@ -838,12 +945,26 @@ export function _resetEngineTaskNotificationForTest() {
     ownWorkflowRuns.clear();
     bgNotifiedKeys.clear();
     outstandingListeners.clear();
+    // 🔴 [2393] notif-F11(2026-08-03 全窗复审):这三件此前漏清 —— 头注自称「清空**全部**通知台账」。
+    //   · `bgTaskPrompts`:首值粘性(已登记的 taskId 不覆写),门里两个用例复用同一 taskId 时
+    //     `outstandingBgTaskPrompt()` 会跨用例返回上一用例的 prompt,reset 拿不掉(既有钉侥幸没撞上,
+    //     不是被挡住了)。它的 process-lifetime 无逐出是**生产**决定(bg 子代 = 人手派发量级),
+    //     与测试钩要不要清是两件事。
+    //   · `tickGeneration`:世代号不复位,跨用例累加(今天只做相等比较,不是现症;但「清空全部」
+    //     这句话要么成立要么改掉,不留半真)。
+    //   · `bgProbeInFlight` / `runProbeInFlight`(notif-F10 新增):上一个用例的 probe 若被用例
+    //     提前收尾抛下,残留的键会让下一个用例的 TTL sweep 永远让位 = 静默失效的 TTL。
+    bgTaskPrompts.clear();
+    bgProbeInFlight.clear();
+    runProbeInFlight.clear();
+    tickGeneration = 0;
     statusProbe = null;
     bgStatusProbe = null;
     tickStartedAtMs = null;
     abandonedCount = 0;
     bgDedupDropped = 0;
     bgCrossChannelDropped = 0;
+    workflowDedupDropped = 0;
     stuckTickResets = 0;
     bgWatchRevivalPromoted = 0;
     bgWatchCollectedUnprobed = 0;