@sema-agent/client-core 0.13.0 → 0.15.0

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

@@ -190,11 +190,21 @@ export declare function outstandingAbandonedCount(): number;
  *     回归,复活周期会伪装成首周期落进这一格 —— 这个数异常增长就是 seq 又丢了的信号);
  *   · `stuckTickResets` = 在飞 tick 超过 STUCK_TICK_RESET_MS 被强制复位的次数,**恒应为 0**;
  *     >0 = 有 probe 连 PROBE_TIMEOUT_MS 都没能截断它。
+ *
+ * 🔴 [2393] F-1 补两格 —— 上面三格全是 **enqueue 内部**的记账,而 watcher 收摊臂在到达 enqueue
+ * **之前**就把台账条目删掉了:「复活周期被秒删」这条路径对上面三格 100% 不可见(立案时被点名当
+ * 信号的 `bgCrossChannelDropped` 正是这样对它零判别力的)。删除动作要挣得,也要看得见:
+ *   · `bgWatchRevivalPromoted` = 收摊臂靠 probe 实证「任务又在跑」把条目升到新周期的次数
+ *     —— 正是修前被静默秒删的那一类;>0 说明 wire 的 seq 没到货,壳在自己补周期号;
+ *   · `bgWatchCollectedUnprobed` = probe 未装(mock/离线)时按裸 id 黑名单**盲摘**的次数,
+ *     这是唯一保留的无证据删除;>0 = 有完成周期在这类宿主上恒不可观察。
  */
 export interface NotificationDropCounters {
     bgDedupDropped: number;
     bgCrossChannelDropped: number;
     stuckTickResets: number;
+    bgWatchRevivalPromoted: number;
+    bgWatchCollectedUnprobed: number;
 }
 export declare function notificationDropCounters(): NotificationDropCounters;
 /** liveClient 在构造会话 client 时注册(带正确 baseUrl/token/principal 的 workflows.get)。 */
@@ -215,7 +225,11 @@ export declare function installBgTaskStatusProbe(probe: BgTaskStatusProbe): void
  * 首周期若确已送达,由 watcher 的收摊臂在下一拍摘除(见 `tickWatchInner` bg 半场),
  * 代价是一次 no-op 遍历,而不是一整个完成周期的结构性缺席。
  *
- * @param seq bg 子代生命周期号;wire 未带 ⇒ 按首周期(BG_FIRST_SEQ)解释。
+ * 🔴 [2393] F-1:`seq` 缺席时这里仍然**按首周期解释,不在登记口猜周期号** —— 猜出来的周期号会
+ * 把「已终局任务的回执重放」也升成新周期,方向相反地造出重复通知。周期号只在 watcher 那侧、
+ * 拿到 probe 的「它又在跑」这个证据之后才前进(见 `tickWatchInner` 的收摊臂三档)。
+ *
+ * @param seq bg 子代生命周期号;wire 未带 ⇒ 按首周期(BG_FIRST_SEQ)解释,复活周期由 watcher 补。
  */
 export declare function registerOutstandingBgTask(taskId: string, description: string, prompt?: string, seq?: number): void;
 export declare function isOwnWorkflowRun(runId: string): boolean;

package/dist/notifications.js

@@ -255,6 +255,22 @@ export function _resetNotificationQueuePortForTest() {
 // (the `<tool-use-id>` line is optional in CC's own template the same way).
 // ══════════════════════════════════════════════════════════════════════════════════════════════
 const notifiedRunIds = new Set();
+const notifiedBgCycleHigh = new Map();
+let ledgerOrder = 0;
+const nextLedgerOrder = () => ++ledgerOrder;
+/** 「已送达」两账的**唯一**写口(裸 id 维 + 周期维必须同时前进,否则收摊臂又回到没有周期证据)。 */
+function markRunNotified(runId, cycle = BG_FIRST_SEQ) {
+    notifiedRunIds.add(runId);
+    const prev = notifiedBgCycleHigh.get(runId);
+    if (prev === undefined || cycle > prev.cycle) {
+        notifiedBgCycleHigh.set(runId, { cycle, order: nextLedgerOrder() });
+    }
+}
+/** 「**这一个周期**已经送达过」——收摊臂唯一可用的删除证据。 */
+function notifiedBgCycleAtLeast(taskId, cycle) {
+    const high = notifiedBgCycleHigh.get(taskId);
+    return high !== undefined && high.cycle >= cycle ? high : undefined;
+}
 /**
  * B1(frame-lane-matrix 三节定谳)— Path A 回声到达时丢弃同 run 的 pending 队列条目。
  * 双投机理:活跃 turn 内 Path B(workflow_complete/bg_notification/probe feeder →
@@ -314,7 +330,9 @@ export function dropQueuedNotificationsForRun(taskId) {
  * steer-inject 的 task_notification 帧)即预标记,Channel A 对同 runId 的补发直接丢弃。
  */
 export function markEngineWorkflowNotified(runId) {
-    notifiedRunIds.add(runId);
+    // [2393] F-1:外部 mark 只证「首周期已送达」(它没有周期号可带),周期维按首周期记 —— 与本函数
+    // 既有的跨通道语义逐字一致(enqueueBgChildNotification 的跨通道臂同样只对首周期成立)。
+    markRunNotified(runId);
     if (outstandingRuns.delete(runId))
         notifyOutstanding();
 }
@@ -414,8 +432,10 @@ export function outstandingAbandonedCount() {
 let bgDedupDropped = 0;
 let bgCrossChannelDropped = 0;
 let stuckTickResets = 0;
+let bgWatchRevivalPromoted = 0;
+let bgWatchCollectedUnprobed = 0;
 export function notificationDropCounters() {
-    return { bgDedupDropped, bgCrossChannelDropped, stuckTickResets };
+    return { bgDedupDropped, bgCrossChannelDropped, stuckTickResets, bgWatchRevivalPromoted, bgWatchCollectedUnprobed };
 }
 let statusProbe = null;
 let watchTimer = null;
@@ -462,7 +482,11 @@ export function installBgTaskStatusProbe(probe) {
  * 首周期若确已送达,由 watcher 的收摊臂在下一拍摘除(见 `tickWatchInner` bg 半场),
  * 代价是一次 no-op 遍历,而不是一整个完成周期的结构性缺席。
  *
- * @param seq bg 子代生命周期号;wire 未带 ⇒ 按首周期(BG_FIRST_SEQ)解释。
+ * 🔴 [2393] F-1:`seq` 缺席时这里仍然**按首周期解释,不在登记口猜周期号** —— 猜出来的周期号会
+ * 把「已终局任务的回执重放」也升成新周期,方向相反地造出重复通知。周期号只在 watcher 那侧、
+ * 拿到 probe 的「它又在跑」这个证据之后才前进(见 `tickWatchInner` 的收摊臂三档)。
+ *
+ * @param seq bg 子代生命周期号;wire 未带 ⇒ 按首周期(BG_FIRST_SEQ)解释,复活周期由 watcher 补。
  */
 export function registerOutstandingBgTask(taskId, description, prompt, seq) {
     if (!taskId)
@@ -475,7 +499,13 @@ export function registerOutstandingBgTask(taskId, description, prompt, seq) {
     const key = bgOutstandingKey(taskId, cycle);
     if (outstandingBgTasks.has(key))
         return;
-    outstandingBgTasks.set(key, { taskId, seq: cycle, registeredAt: Date.now(), description });
+    outstandingBgTasks.set(key, {
+        taskId,
+        seq: cycle,
+        registeredAt: Date.now(),
+        registeredOrder: nextLedgerOrder(),
+        description,
+    });
     ensureWatchTimer();
 }
 /** 本壳亲手启动过的 workflow run(process-lifetime,只增不摘——outstandingRuns 会随完成摘除,
@@ -630,10 +660,55 @@ async function tickWatchInner() {
     // probe 未装=mock/离线,只等推送补发)
     const bgProbe = bgStatusProbe;
     for (const [key, meta] of [...outstandingBgTasks]) {
-        // 收摊臂**只对首周期成立**:notifiedRunIds 是裸 taskId 键空间,它只证明「首周期已送达」,
-        // 对 seq≥2 的新完成周期毫无判别力(与 enqueueBgChildNotification 的跨通道臂同一前提)。
-        if (meta.seq <= BG_FIRST_SEQ && notifiedRunIds.has(meta.taskId)) {
-            outstandingBgTasks.delete(key); // 推送/别的通道已送达 — 收摊
+        // 🔴 [2393] F-1:收摊臂的删除必须**挣得**。此前的判据是裸 taskId 黑名单
+        // (`meta.seq <= BG_FIRST_SEQ && notifiedRunIds.has(meta.taskId)`),它只证明「这个 id 曾经
+        // 送达过某次完成」;而 `structured.seq` 缺席时复活周期的 cycle 塌回首周期,于是这条臂拿
+        // **首周期的送达记录**把**第二周期**的观察条目在下一拍秒删,probe 一次不跑 —— 与 notif-02
+        // 修前的静默丢通知逐字相同,且删在 enqueue 之前 ⇒ 三个既有计数器一格都摸不到。
+        // 新判据分三档,每一档都拿得出理由:
+        //   ① 这一周期确已送达(周期键台账)⇒ 才谈得上收摊;
+        //   ①a 条目**登记在那次送达之前** ⇒ 它就是那次送达自己的观察条目,无歧义,零成本收摊
+        //       (= 旧行为的正当那一半,常态路径,不多花一次探测);
+        //   ①b 条目**登记在送达之后** ⇒ 有歧义:复活周期?还是已终局任务的回执重放?靠 probe 定夺:
+        //   ② probe 说它**真终局** ⇒ 就是那个已送达的周期,收摊(重放回执落这里,不会二次喂模型);
+        //   ③ probe 说它**又在跑** ⇒ 这按构造是一个**新的完成周期**(裸 id 黑名单对它零判别力),
+        //      把条目升到下一个周期号继续观察,并留痕。probe 未装 ⇒ 没有可挣得的证据,沿用旧的盲摘
+        //      但记账;probe 失败/答不上来 ⇒ 不删也不升(TTL 兜底),绝不拿探测失败当终局证据。
+        const delivered = notifiedBgCycleAtLeast(meta.taskId, meta.seq);
+        if (delivered !== undefined) {
+            if (meta.registeredOrder < delivered.order) {
+                outstandingBgTasks.delete(key); // ①a 推送/别的通道已送达本条目观察的那个周期 — 收摊
+                continue;
+            }
+            if (!bgProbe) {
+                outstandingBgTasks.delete(key);
+                bgWatchCollectedUnprobed++;
+                continue;
+            }
+            let alive;
+            try {
+                const res = await withProbeDeadline(bgProbe(meta.taskId), probeTimeoutMs());
+                if (res === null || res === undefined)
+                    continue; // 答不上来 ≠ 终局,留给下一拍/TTL
+                alive = !res.terminal;
+            }
+            catch {
+                continue; // 探测失败(含 ProbeDeadlineError)不构成删除证据
+            }
+            if (!alive) {
+                outstandingBgTasks.delete(key); // 真终局 = 已送达的那个周期,收摊
+                continue;
+            }
+            const promoted = Math.max(meta.seq, delivered.cycle) + 1;
+            outstandingBgTasks.delete(key);
+            const promotedKey = bgOutstandingKey(meta.taskId, promoted);
+            if (!outstandingBgTasks.has(promotedKey)) {
+                outstandingBgTasks.set(promotedKey, { ...meta, seq: promoted, registeredOrder: nextLedgerOrder() });
+            }
+            bgWatchRevivalPromoted++;
+            traceNotif(`bg task ${meta.taskId} is running again after cycle ${meta.seq} was already delivered — ` +
+                `promoting the watch entry to cycle ${promoted} (wire carried no seq; without this the entry ` +
+                'would be collected by the bare-taskId ledger and this completion would never reach the user)');
             continue;
         }
         if (!bgProbe)
@@ -709,7 +784,8 @@ export function enqueueBgChildNotification(n) {
         return;
     }
     bgNotifiedKeys.add(key);
-    notifiedRunIds.add(n.taskId);
+    // [2393] F-1:周期维必须跟着前进 —— 收摊臂删条目的唯一证据就是这一格。
+    markRunNotified(n.taskId, cycle);
     cardEnqueuedRunIds.add(n.taskId);
     // #6 通知-settle 边(合成半场):bg 子代行不再被 turn sweep 假结(session 常驻台账),真终态
     // 唯二来源 = 推送帧(bridge task_notification 臂)与本合成链(probe/fleet bg_notification 收敛点)。
@@ -738,7 +814,8 @@ export function enqueueBgChildNotification(n) {
 export function enqueueEngineWorkflowNotification(c) {
     if (notifiedRunIds.has(c.runId))
         return;
-    notifiedRunIds.add(c.runId);
+    // [2393] F-1:workflow 侧没有周期概念,周期维按首周期记(与 markEngineWorkflowNotified 同理)。
+    markRunNotified(c.runId);
     cardEnqueuedRunIds.add(c.runId);
     const message = `<${TASK_NOTIFICATION_TAG}>
 <${TASK_ID_TAG}>${escapeXml(c.runId)}</${TASK_ID_TAG}>
@@ -754,6 +831,7 @@ export function enqueueEngineWorkflowNotification(c) {
  *  🔴 生产绝不调用 —— 台账是 process-lifetime 去重的唯一凭据,清了就会双投。 */
 export function _resetEngineTaskNotificationForTest() {
     notifiedRunIds.clear();
+    notifiedBgCycleHigh.clear();
     cardEnqueuedRunIds.clear();
     outstandingRuns.clear();
     outstandingBgTasks.clear();
@@ -767,6 +845,8 @@ export function _resetEngineTaskNotificationForTest() {
     bgDedupDropped = 0;
     bgCrossChannelDropped = 0;
     stuckTickResets = 0;
+    bgWatchRevivalPromoted = 0;
+    bgWatchCollectedUnprobed = 0;
     probeTimeoutOverrideMs = null;
     stuckTickResetOverrideMs = null;
     if (watchTimer !== null) {

package/dist/printToolResultFrame.d.ts

@@ -36,11 +36,19 @@
 import type { SDKMessage } from '@sema-agent/agent-types';
 /**
  * Flatten the §E1 wire `output`(NON-UNIFORM: `string` | `(TextContent|ImageContent)[]`)into one
- * plain-text blob(upstreamBridge.flattenWireOutput 同款语义的轻量副本——避免把重量级 REPL 桥
- * 拖进 `-p` 车道的 import 图)。🔴 UNTRUSTED / OBSERVABILITY-ONLY:只呈现,绝不回喂模型。
+ * plain-text blob。🔴 UNTRUSTED / OBSERVABILITY-ONLY:只呈现,绝不回喂模型。
+ *
+ * ⇄ REF-CC-008 / dup-05 兑现(ADAPT-F1,2026-08-02):此处曾是 `flattenWireOutput` 的**逐字节副本**,
+ * 豁免理由写着「避免把重量级 REPL 桥拖进 `-p` 车道的 import 图」。A 族拆分把该函数从 1607 行的
+ * `adapt.ts` 搬进了 `adapt/wireShapes.ts`,而那个文件**唯一的 import 是 `import type {Frame}`**
+ * (type-only,编译后整段消失)—— 正是台账要的那片「零 import 叶」,拆分创造了退役条件。
+ * 副本随之删除,`flattenToolOutput` 收成对唯一实现的**具名再导出**(公面名不动:它在
+ * public-export-baseline 里,改名会当场红)。
  */
-export declare function flattenToolOutput(output: unknown): string;
-/** 内部 tool_end_result arm(eventToSdkMessage.ts:213-231 铸造)的防御性读形。 */
+export { flattenWireOutput as flattenToolOutput } from './adapt/wireShapes.js';
+/** 内部 tool_end_result arm(`eventToSdkMessage.ts` 的 `case 'tool_end'` 臂铸造)的防御性读形。
+ *  ⚠️ ADAPTER-F8 注纠(2026-08-02):原文锚的是裸行号 `213-231`,A 族拆分后那段是 `case 'text'` /
+ *  `case 'reasoning'`,真正的 tool_end 臂已挪位。锚换成符号名(REF-CC-063 同款,腐烂不了)。 */
 export interface ToolEndResultArmLike {
     type?: unknown;
     toolCallId?: unknown;

package/dist/printToolResultFrame.js

@@ -1,26 +1,16 @@
 /**
  * Flatten the §E1 wire `output`(NON-UNIFORM: `string` | `(TextContent|ImageContent)[]`)into one
- * plain-text blob(upstreamBridge.flattenWireOutput 同款语义的轻量副本——避免把重量级 REPL 桥
- * 拖进 `-p` 车道的 import 图)。🔴 UNTRUSTED / OBSERVABILITY-ONLY:只呈现,绝不回喂模型。
+ * plain-text blob。🔴 UNTRUSTED / OBSERVABILITY-ONLY:只呈现,绝不回喂模型。
+ *
+ * ⇄ REF-CC-008 / dup-05 兑现(ADAPT-F1,2026-08-02):此处曾是 `flattenWireOutput` 的**逐字节副本**,
+ * 豁免理由写着「避免把重量级 REPL 桥拖进 `-p` 车道的 import 图」。A 族拆分把该函数从 1607 行的
+ * `adapt.ts` 搬进了 `adapt/wireShapes.ts`,而那个文件**唯一的 import 是 `import type {Frame}`**
+ * (type-only,编译后整段消失)—— 正是台账要的那片「零 import 叶」,拆分创造了退役条件。
+ * 副本随之删除,`flattenToolOutput` 收成对唯一实现的**具名再导出**(公面名不动:它在
+ * public-export-baseline 里,改名会当场红)。
  */
-export function flattenToolOutput(output) {
-    if (typeof output === 'string')
-        return output;
-    if (Array.isArray(output)) {
-        const parts = [];
-        for (const block of output) {
-            if (block && typeof block === 'object') {
-                const b = block;
-                if (b.type === 'text' && typeof b.text === 'string')
-                    parts.push(b.text);
-                else if (b.type === 'image')
-                    parts.push('[image]');
-            }
-        }
-        return parts.join('');
-    }
-    return '';
-}
+export { flattenWireOutput as flattenToolOutput } from './adapt/wireShapes.js';
+import { flattenWireOutput } from './adapt/wireShapes.js';
 /**
  * Bash 臂的 is_error 派生(真行为实证,2026-07-16):引擎 tool_end.isError 语义 = 「工具本身
  * 是否执行失败」——命令非零退出时工具照常返回模型面框架文本(core runShell `exit code: N\n---
@@ -50,7 +40,7 @@ function bashExitCodeFailed(toolName, text, structured) {
 export function toolEndResultToUserFrame(arm) {
     if (typeof arm.toolCallId !== 'string' || arm.toolCallId.length === 0)
         return null;
-    const text = flattenToolOutput(arm.output);
+    const text = flattenWireOutput(arm.output);
     return {
         type: 'user',
         message: {

package/dist/unrefTimer.d.ts

@@ -10,9 +10,20 @@
  *
  * 泛型约束到定时器句柄型(`setTimeout`/`setInterval` 的回传值):本包 `"types": []` + 默认 DOM
  * lib 下两者都是 `number`,Node 运行时实际回传 `Timeout` 对象——真身与编译期类型不一致正是
- * `unref?.()` 需要可选调用的原因。约束此前是无约束 `<T>`,`unrefTimer(42)` / `unrefTimer(aPromise)`
- * 这类明显打错调用点的用法会静默通过;收窄后这些误用编译期就报,而五个既有调用点(均传
- * `setTimeout`/`setInterval` 的返回值)不受影响。
+ * `unref?.()` 需要可选调用的原因。约束此前是无约束 `<T>`,任何东西都能传进来。
+ *
+ * 🔴 这条约束**挡得住哪一半、挡不住哪一半**(实测,不是承诺 —— [2393] F-3 纠正:此前这里写的是
+ *    「`unrefTimer(42)` / `unrefTimer(aPromise)` 收窄后编译期就报」,而上一段自己写明的前提
+ *    「本包下句柄型就是 `number`」直接推翻了它的前半句):
+ *      · `unrefTimer('x')` / `unrefTimer(aPromise)` —— **编译期红**(TS2345,非 number 挡得住);
+ *      · `unrefTimer(42)` —— **编译期绿**。`42` 与真句柄在本包的类型系统里不可分辨,挡不住;
+ *        运行时也无害(可选调用在 number 上是 no-op),但别指望编译器替你抓这一类打错。
+ *    这四条判决由 `scripts/run-client-core-typeshape-test.mjs` 的 D 腿每跑机械核一次:实测与
+ *    这段措辞一旦分叉即红。⚠️ 别为了兑现前半句去拧类型 —— 能挡住数字字面量的写法在**装了
+ *    @types/node 的下游**会把句柄型解成 `Timeout` 对象,五个真调用点全线编译红(用一个假承诺
+ *    换一个真的可移植性回归)。
+ *
+ * 五个既有调用点(均传 `setTimeout`/`setInterval` 的返回值)不受约束影响。
  */
 type TimerLikeHandle = ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>;
 export declare function unrefTimer<T extends TimerLikeHandle>(t: T): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Client-side session runtime shared by every sema human client (TUI / web / desktop): sema wire frames (AgentEvent) -> CC session vocabulary (SDKMessage) with dual-plane output (transcript/chrome), deterministic transcript ids, lane discipline as a type, and the notification/dedup ledgers. Every CC-skin shape is collected here so the wire itself stays neutral. Blackboard [1832] design axioms; [1651]/[1652]/[1653] signed seam design. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",