lark-remote 0.5.20 → 0.5.21

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.21] - 2026-11-05
+
+### 维护
+
+- **高复杂度函数按职责拆分**：router 的 `/ws` `/ls` `/order` 命令装配、会话存储与各 agent 的会话目录读取、卡片渲染与预算降级等函数拆成可单独测试的小函数，调用关系与输出不变；拆分风险由下面那条结构等价快照兜住。无行为变化
+- **新增结构等价快照**：`structure-equivalence` 用例直接调用命令层与卡片层的公共出口，把卡片元素形状、文案、callback 的字段与顺序、分页栏、副作用调用记录整份录进外部快照，实现拆分后不带 `-u` 重跑必须逐字不变。快照里的动态值（临时目录及其父目录、路径分隔符、随机目录名、文件 mtime）在比较前统一归一，并加了漏归一守卫——宿主专属路径有残留直接抛错，同一份快照在 macOS / Linux / Windows 上逐字一致。无行为变化
+- **补齐此前无用例的模块**：审批协调与审批事件、DSH 多路复用流与 translator、工具入参摘要、后台命令生命周期、各家 agent 的会话目录读取分支新增独立用例文件。无行为变化
+- **用例不再向宿主操作系统要事实**：opencode 的日志错误监视原先靠「日志父路径被普通文件占住」制造 `ENOTDIR`，而 Windows 的 stat 对同一形态报 `ENOENT`——那正是「日志还没生成」的正常空态出口，故障分支只在单一系统走得到，现在改成按目标路径注入给定错误码；DSH 同步连接的断言不再硬编码 `/dev/null`（实现按平台传 `-o NUL`），只钉住 `-o` 后面必须是宿主空设备。无行为变化
+- **pi 的中断用例消掉收尾竞态**：`abort` 是发了就不管的通知，写进子进程 stdin 不等于它已被读到。原先用例在 `stop()` 之后立刻收尾，清理时可能先杀掉模拟进程，接收日志里只剩 `get_state` 与 `prompt` 两条；现在等到 `abort` 真落进接收日志再走完事件循环，末事件仍断言为已中断。无行为变化
+
 ## [0.5.20] - 2026-11-04
 
 ### 修复

package/dist/bridge/inbound-media.js

@@ -92,55 +92,81 @@ function sanitizeFileName(name) {
  * 资源扩展名（图片/视频/语音）：优先 MIME 映射，未知时按魔数兜底；
  * 两者都无法识别时返回 undefined（调用方省略扩展名，避免错误标注格式）。
  */
-function extensionFor(_kind, mimeType, head) {
-    const normalized = mimeType?.split(';')[0]?.trim().toLowerCase();
-    if (normalized && MIME_TO_EXT[normalized])
-        return MIME_TO_EXT[normalized];
-    if (head.length >= 12 &&
-        head.subarray(0, 4).toString('latin1') === 'RIFF' &&
-        head.subarray(8, 12).toString('latin1') === 'WEBP') {
-        return 'webp';
-    }
-    if (head.length >= 12 &&
+function normalizeMimeType(mimeType) {
+    return mimeType?.split(';')[0]?.trim().toLowerCase();
+}
+// --- 魔数判定原语（模块级命名函数，供查表顺序调用） ---
+// 每个 matcher 逐字保留原 extensionFor 内联 if 的长度门槛与比较条件。
+function isRiffFormat(format, head) {
+    return (head.length >= 12 &&
         head.subarray(0, 4).toString('latin1') === 'RIFF' &&
-        head.subarray(8, 12).toString('latin1') === 'WAVE') {
-        return 'wav';
-    }
-    if (head.length >= 8 &&
-        head.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
-        return 'png';
-    }
-    if (head.length >= 3 && head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff) {
-        return 'jpg';
-    }
-    if (head.length >= 4 && head.subarray(0, 4).toString('latin1') === 'GIF8') {
-        return 'gif';
-    }
-    if (head.length >= 4 && head.subarray(0, 4).toString('latin1') === 'OggS') {
-        return 'opus';
-    }
-    // MP4/MOV 家族：ISO BMFF 在偏移 4 处写 'ftyp'。
-    if (head.length >= 8 && head.subarray(4, 8).toString('latin1') === 'ftyp') {
-        return 'mp4';
-    }
-    if (head.length >= 2 && head[0] === 0x42 && head[1] === 0x4d) {
-        return 'bmp';
-    }
-    if (head.length >= 3 && head.subarray(0, 3).toString('latin1') === 'ID3') {
-        return 'mp3';
-    }
-    // MPEG audio frame sync（0xFFE0 掩码）+ 常见 layer/bitrate 组合。
-    if (head.length >= 2 && head[0] === 0xff && (head[1] & 0xfe) === 0xfa) {
-        return 'mp3';
-    }
-    if (head.length >= 5 && head.subarray(0, 5).toString('latin1') === '#!AMR') {
-        return 'amr';
-    }
-    if (head.length >= 4 && head.readUInt32BE(0) === 0x1a45dfa3) {
-        return 'mkv';
+        head.subarray(8, 12).toString('latin1') === format);
+}
+function isPng(head) {
+    return (head.length >= 8 &&
+        head.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])));
+}
+function isJpeg(head) {
+    return head.length >= 3 && head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff;
+}
+function isGif(head) {
+    return head.length >= 4 && head.subarray(0, 4).toString('latin1') === 'GIF8';
+}
+function isOgg(head) {
+    return head.length >= 4 && head.subarray(0, 4).toString('latin1') === 'OggS';
+}
+/** MP4/MOV 家族：ISO BMFF 在偏移 4 处写 'ftyp'。 */
+function isIsoBmff(head) {
+    return head.length >= 8 && head.subarray(4, 8).toString('latin1') === 'ftyp';
+}
+function isBmp(head) {
+    return head.length >= 2 && head[0] === 0x42 && head[1] === 0x4d;
+}
+function isId3(head) {
+    return head.length >= 3 && head.subarray(0, 3).toString('latin1') === 'ID3';
+}
+/** MPEG audio frame sync（0xFFE0 掩码）+ 常见 layer/bitrate 组合。 */
+function isMpegFrameSync(head) {
+    return head.length >= 2 && head[0] === 0xff && (head[1] & 0xfe) === 0xfa;
+}
+function isAmr(head) {
+    return head.length >= 5 && head.subarray(0, 5).toString('latin1') === '#!AMR';
+}
+function isMatroska(head) {
+    return head.length >= 4 && head.readUInt32BE(0) === 0x1a45dfa3;
+}
+/**
+ * 魔数规则表：键为唯一规则标识，值携带输出扩展名与判定函数。用 Map 而非对象
+ * 字面量（避免 `constructor` / `toString` 等键命中 Object.prototype），且 Map
+ * 迭代顺序 = 插入顺序，与原 if 链的短路优先级逐字一致（mp3 的两个签名占两条）。
+ */
+const MAGIC_EXTENSION_RULES = new Map([
+    ['riff-webp', { ext: 'webp', matches: isRiffFormat.bind(null, 'WEBP') }],
+    ['riff-wave', { ext: 'wav', matches: isRiffFormat.bind(null, 'WAVE') }],
+    ['png', { ext: 'png', matches: isPng }],
+    ['jpeg', { ext: 'jpg', matches: isJpeg }],
+    ['gif', { ext: 'gif', matches: isGif }],
+    ['ogg', { ext: 'opus', matches: isOgg }],
+    ['iso-bmff', { ext: 'mp4', matches: isIsoBmff }],
+    ['bmp', { ext: 'bmp', matches: isBmp }],
+    ['id3', { ext: 'mp3', matches: isId3 }],
+    ['mpeg-frame-sync', { ext: 'mp3', matches: isMpegFrameSync }],
+    ['amr', { ext: 'amr', matches: isAmr }],
+    ['matroska', { ext: 'mkv', matches: isMatroska }],
+]);
+function magicExtensionFor(head) {
+    for (const { ext, matches } of MAGIC_EXTENSION_RULES.values()) {
+        if (matches(head))
+            return ext;
     }
     return undefined;
 }
+function extensionFor(_kind, mimeType, head) {
+    const normalized = normalizeMimeType(mimeType);
+    if (normalized && MIME_TO_EXT[normalized])
+        return MIME_TO_EXT[normalized];
+    return magicExtensionFor(head);
+}
 /**
  * 文件名长度限制（字节级，保留扩展名），避免 ENAMETOOLONG 整文件失败。
  * 极罕见情况（扩展名本身超限）直接截断全名。

package/dist/bridge/index.d.ts

@@ -569,6 +569,15 @@ export declare class Bridge {
      * Handles idle watchdog, event processing, session sync, and state transitions.
      */
     private runAgentStreamToEnd;
+    /**
+     * runAgentStreamToEnd 的 try 主体（建卡 → 事件循环 → 收尾），抽成独立方法
+     * 降低外层圈复杂度；state 为跨方法共享的可变状态。逻辑与文案逐字保留。
+     */
+    private executeStream;
+    /** runAgentStreamToEnd 的 catch 主体（抽成独立方法，state.sawResult 沿用循环累计值）。 */
+    private handleStreamFailure;
+    /** runAgentStreamToEnd 的 finally 主体（抽成独立方法）。 */
+    private cleanupStream;
     /**
      * 事件循环的看门狗喂狗（runAgentStreamToEnd 抽出的纯向方法）。
      *

package/dist/bridge/index.js

@@ -63,6 +63,36 @@ function completionNotificationPresentation(terminal) {
             return { title: '✅ 会话已完成', template: 'green', result: 'completed' };
     }
 }
+// --- approvalModeSettingsFor 的逐 agent 快照（字段口径单表 + 单函数） ---
+// Map 查表避免 constructor/toString 之类键命中 Object.prototype；字段顺序
+// 与原 switch 分支逐字一致。不碰 Bridge 实例状态，避免 this 绑定问题。
+/** 各 agent 审批设置快照的字段口径（顺序 = 原分支逐字）。 */
+const APPROVAL_SETTINGS_FIELDS = new Map([
+    ['codex', ['approvalPolicy', 'sandbox']],
+    ['kimi', ['permissionMode']],
+    ['opencode', ['mode']],
+    ['dsh', ['permissionPreset']],
+]);
+function approvalSettingsFor(agents, kind) {
+    const fields = APPROVAL_SETTINGS_FIELDS.get(kind);
+    if (!fields)
+        return undefined;
+    const cfg = agents?.[kind];
+    if (!cfg)
+        return undefined;
+    const out = {};
+    for (const field of fields)
+        out[field] = cfg[field];
+    return out;
+}
+/** runner 是否使用 live result 事件（显式传 runner + usageAuthority 状态）。 */
+function computeLiveResultEvents(runner, usageAuthority) {
+    return runner.usesLiveResultEvents?.() ?? usageAuthority === 'live';
+}
+/** 待审批计数（startIdleWatchdog 的 pendingApprovals 回调，显式传 coordinators 表）。 */
+function pendingApprovalCount(coordinators, runId) {
+    return coordinators.get(runId)?.pendingCount() ?? 0;
+}
 /**
  * Bridge owns the per-workspace serial processing queue (§9.6) and the
  * single-card streaming forwarding loop (§9.12 watchdog + session sync).
@@ -276,38 +306,7 @@ export class Bridge {
     }
     /** Per-agent approval-mode settings snapshot from the current config. */
     approvalModeSettingsFor(kind) {
-        const agents = this.config.agents;
-        switch (kind) {
-            case 'codex': {
-                const codexConfig = agents?.codex;
-                if (!codexConfig)
-                    return undefined;
-                return {
-                    approvalPolicy: codexConfig.approvalPolicy,
-                    sandbox: codexConfig.sandbox,
-                };
-            }
-            case 'kimi': {
-                const kimiConfig = agents?.kimi;
-                if (!kimiConfig)
-                    return undefined;
-                return { permissionMode: kimiConfig.permissionMode };
-            }
-            case 'opencode': {
-                const opencodeConfig = agents?.opencode;
-                if (!opencodeConfig)
-                    return undefined;
-                return { mode: opencodeConfig.mode };
-            }
-            case 'dsh': {
-                const dshConfig = agents?.dsh;
-                if (!dshConfig)
-                    return undefined;
-                return { permissionPreset: dshConfig.permissionPreset };
-            }
-            default:
-                return undefined;
-        }
+        return approvalSettingsFor(this.config.agents, kind);
     }
     /** Get the current runner for a cwd. Used by router for agent-specific commands (.2). */
     getCurrentRunner(cwd) {
@@ -1352,189 +1351,217 @@ export class Bridge {
         // 'jsonl'。result 事件的 live 语义（pre-init/写回）单独声明，不能和
         // 用量来源共用一个字段。
         const usageAuthority = runner.getUsageAuthority?.();
-        const liveResultEvents = runner.usesLiveResultEvents?.() ?? usageAuthority === 'live';
-        // §9.12 空闲看门狗：判定口径见 startIdleWatchdog；武装点在 cardSession.start() 之后。
-        let watchdog = null;
-        let sawResult = false;
-        /** 收到过任何 result（含被守卫丢弃/未进卡片的）：收尾报文据此措辞。 */
-        let sawAnyResult = false;
-        // A runner can fail before emitting its synthetic system/init (e.g. DSH
-        // session/create -> 401). The pre-init guard below drops that result to
-        // protect Claude resume replay, but if the stream ends without ever seeing
-        // init the result was the only terminal signal we had. Keep it so the card
-        // shows the real error instead of the generic "no result" fallback.
-        let pendingPreInitTerminal;
-        const usage = new RunUsageCollector();
+        const liveResultEvents = computeLiveResultEvents(runner, usageAuthority);
+        // 运行期状态打包成显式状态对象传给各抽出方法（等价替换原闭包捕获的局部变量）。
+        const run = {
+            runner,
+            cardSession,
+            activeRun,
+            sessionId,
+            sessionEpochAtStart,
+            ctx,
+            cwd,
+            runId,
+            message,
+            agentKind,
+            usage: new RunUsageCollector(),
+            usageAuthority,
+            liveResultEvents,
+            state: {
+                watchdog: null,
+                sawResult: false,
+                sawAnyResult: false,
+                pendingPreInitTerminal: undefined,
+            },
+        };
         try {
-            try {
-                // queue.immediate 的 run-start hold：目标槽位可能在 handler 发最终
-                // toast 之前就 begin（interrupt/PATCH 的 await 窗口）。activeRun 已
-                // 登记（队列语义照旧），只把建卡这一步挡到 toast 之后——run 卡片才是
-                // 点击后最后一条新消息，聊天列表预览跟随它的标题变化。
-                await this.queueManager.awaitTaskRunStart(cwd);
-                getLogger().debug(`[lark-remote] cardSession.start() begin runId=${runId}`);
-                await cardSession.start();
-                getLogger().info(`[lark-remote] cardSession.start() ok runId=${runId}`);
-            }
-            catch (err) {
-                getLogger().warn('[lark-remote] card stream unavailable, will use static fallback:', err);
-                // Card stream failed - continue with static fallback below, but ensure
-                // we don't silently fail if the fallback also fails (covered in catch below).
-            }
-            // /stop（或队列「立即执行」的中断）可能落在建卡窗口内：卡片已定格为
-            // 终态，但 runner 还没开始跑，runner.stop() 也没有进程可杀——spawn 型
-            // 与连接型 runner 的 stop() 在 run() 之前都是空操作，且 run() 入口会
-            // 重置停止标记。必须在这里收口，否则用户看到「已中断」，agent 仍会把
-            // 这一轮跑完并改写工作区。finalizeRun 仍会照常收尾（settle / reaction）。
-            if (isRunTerminal(cardSession.currentState.terminal)) {
-                getLogger().info(`[lark-remote] card terminal before run start, skip runner runId=${runId} terminal=${cardSession.currentState.terminal}`);
-                return;
-            }
-            // 单 interval 看门狗。事件到来时只刷新时间戳（无 timer 操作）；
-            // interval 周期检查静默时长，超时才 finish('idle_timeout') + stop()。
-            // 武装点在建卡之后，与原实现一致（宽限期不含 cardSession.start() 耗时）。
-            watchdog = this.startIdleWatchdog({
-                runId,
-                session: cardSession,
-                runner,
-                pendingApprovals: () => this.approvalCoordinators.get(runId)?.pendingCount() ?? 0,
-            });
-            getLogger().info(`[lark-remote] runner.run() begin runId=${runId} message=${message.slice(0, 100)}`);
-            // Extract agent-specific options from config
-            const agentOpts = this.getAgentRunOptions(agentKind);
-            const runOpts = { cwd, sessionId, ...agentOpts };
-            // Track whether system.init has been received for this run.
-            // Claude CLI --resume emits a stale result (from the previous turn)
-            // before sending system.init; bridge must not treat that as the run
-            // ending (sawResult, usage capture, or cardSession.push would all
-            // be wrong for the historical event).
-            let sawInit = false;
-            const writeback = {
-                sessionStore: this.sessionStore,
-                userId: ctx.userId,
-                agentKind,
-                cwd,
-                sessionEpochAtStart,
-                runId,
-            };
-            for await (const event of runner.run(message, runOpts)) {
-                // 只有终态才阻止事件处理。finalizing 是非终态，应该继续处理
-                // 这样在 result 事件后，后台任务输出仍能被正确处理
-                const terminal = cardSession.currentState.terminal;
-                if (isRunTerminal(terminal)) {
-                    continue;
-                }
-                // 归一化：init/turn_started 的 session 写回 + compact_boundary 用量观察。
-                // 返回 true = 本轮 system.init 已到（调用方置 sawInit，供 pre-init 守卫用）。
-                if (this.maybeSyncSession(event, { activeRun, writeback, usage, runId })) {
-                    sawInit = true;
-                }
-                // pre-init result 守卫（§9.22，observeResultEvent）：resume 重放的陈旧
-                // result 不置 sawResult、不进卡片。
-                if (event.type === 'result') {
-                    const outcome = this.observeResultEvent(event, {
-                        sawInit,
-                        liveResultEvents,
-                        usage,
-                        writeback,
-                        runId,
-                    });
-                    if (outcome.preInitTerminal)
-                        pendingPreInitTerminal ??= outcome.preInitTerminal;
-                    if (outcome.sawResult)
-                        sawResult = true;
-                    sawAnyResult = true;
-                    // 陈旧 result 不进卡片：run-state reducer 本来也会因 sessionId 未定而
-                    // 跳过，在 bridge 层就拦掉可以省下一次无谓的 push + render。
-                    if (outcome.dropFromCard) {
-                        // 仍然重置 idle 计时——CLI 活着并且在产事件。
-                        this.handleEventForWatchdog(watchdog);
-                        continue;
-                    }
-                }
-                // Approval events (Codex app-server mode)。审批先到、item/started 后到的
-                // 乱序流也在此补全（dispatchApprovalEvent 内 updateView）。
-                if (event.type === 'approval_requested' ||
-                    event.type === 'approval_resolved' ||
-                    event.type === 'approval_view_updated') {
-                    this.dispatchApprovalEvent(event, { runId, runner, cardSession, ctx, agentKind });
-                }
-                // §9.12 红线：每个事件（含 result）无条件刷新
-                // lastEventTs 重新武装看门狗。result 后 CLI 进程做 jsonl flush/清理（finalizing
-                // 过渡）期间，宽限期恢复为完整的 idleTimeoutMs，避免已产出结果的 turn 被误标
-                // idle_timeout。旧实现 `else { resetIdle(); }` 漏掉 result 分支。
-                this.handleEventForWatchdog(watchdog);
-                // 渲染：reducer（run-state）在 cardSession.push 内部。
-                await cardSession.push(event);
-            }
-            getLogger().info(`[lark-remote] runner stream end runId=${runId} sawResult=${sawResult}`);
-            // §9.12 红线：for-await 自然结束 = CLI 已退出，
-            // 看门狗使命结束，立即摘除 interval（不再等 finally），堵掉「stream 已结束、
-            // 收尾处理跨过死线被误标 idle_timeout」的同源小窗口（随本修复一并关闭）。
-            watchdog?.stop();
-            // stream 结束 = CLI 退出 = jsonl 已落盘。读 jsonl 拿准确的 contextLength + compactCount：
-            // live stream-json 不发 compact_boundary，live contextLength 会被 result 的 input+output 兜底失真。
-            // 但 result=error 时跳过: 进程可能立即退出未写新 usage (如 kimi 0.26+ 拒绝 -p+--auto
-            // 立即 exit=1), 此时 jsonl 里是上一次成功 turn 的历史 usage, 会被误当作本次 usage 显示,
-            // 误导用户以为本次出错的请求也消耗了 token。error 时只用 live 捕获的 usage (若有)。
-            // 本轮使用的 session：run 期间 /new //resume //cd 会移动全局
-            // 指针，结束时再读 store 会把别条会话的 token/context 显示到这张卡上。
-            // 优先级：卡片状态（本轮 init 写入）→ activeRun（本轮 init/turn_started）
-            // → 本轮开始时捕获的 sessionId。三者都没有就跳过 usage，绝不回读全局指针。
-            const finalSessionId = cardSession.currentState.sessionId ?? activeRun.sessionId ?? sessionId;
-            const finalUsage = usage.resultNotSuccess
-                ? undefined
-                : resolveFinalUsage(this.sessionReaderRegistry, this.config.defaultAgent, finalSessionId, cwd, agentKind);
-            usage.finalize(finalUsage, usageAuthority);
-            getLogger().info(usage.logSummary(runId));
-            // for-await 自然结束 = stream 关闭 = CLI 进程退出 → 终态矩阵
-            await this.finishRunAfterStream({
-                cardSession,
-                usage,
-                sawResult,
-                sawAnyResult,
-                pendingPreInitTerminal,
-                agentKind,
-                runId,
-            });
+            await this.executeStream(run);
         }
         catch (err) {
-            getLogger().error(`[lark-remote] claude run error runId=${runId}:`, err);
-            // 双保险：run() 的 finally 已负责杀子进程，但 catch 路径再补一次
-            // runner.stop()（与 bash 路径对齐），覆盖任何 finally 之外的残留窗口。
-            try {
-                await runner.stop();
+            await this.handleStreamFailure(err, run);
+        }
+        finally {
+            this.cleanupStream(run);
+        }
+    }
+    /**
+     * runAgentStreamToEnd 的 try 主体（建卡 → 事件循环 → 收尾），抽成独立方法
+     * 降低外层圈复杂度；state 为跨方法共享的可变状态。逻辑与文案逐字保留。
+     */
+    async executeStream(run) {
+        const { runner, cardSession, activeRun, sessionId, sessionEpochAtStart, ctx, cwd, runId, message, agentKind, usage, usageAuthority, liveResultEvents, state, } = run;
+        try {
+            // queue.immediate 的 run-start hold：目标槽位可能在 handler 发最终
+            // toast 之前就 begin（interrupt/PATCH 的 await 窗口）。activeRun 已
+            // 登记（队列语义照旧），只把建卡这一步挡到 toast 之后——run 卡片才是
+            // 点击后最后一条新消息，聊天列表预览跟随它的标题变化。
+            await this.queueManager.awaitTaskRunStart(cwd);
+            getLogger().debug(`[lark-remote] cardSession.start() begin runId=${runId}`);
+            await cardSession.start();
+            getLogger().info(`[lark-remote] cardSession.start() ok runId=${runId}`);
+        }
+        catch (err) {
+            getLogger().warn('[lark-remote] card stream unavailable, will use static fallback:', err);
+            // Card stream failed - continue with static fallback below, but ensure
+            // we don't silently fail if the fallback also fails (covered in catch below).
+        }
+        // /stop（或队列「立即执行」的中断）可能落在建卡窗口内：卡片已定格为
+        // 终态，但 runner 还没开始跑，runner.stop() 也没有进程可杀——spawn 型
+        // 与连接型 runner 的 stop() 在 run() 之前都是空操作，且 run() 入口会
+        // 重置停止标记。必须在这里收口，否则用户看到「已中断」，agent 仍会把
+        // 这一轮跑完并改写工作区。finalizeRun 仍会照常收尾（settle / reaction）。
+        if (isRunTerminal(cardSession.currentState.terminal)) {
+            getLogger().info(`[lark-remote] card terminal before run start, skip runner runId=${runId} terminal=${cardSession.currentState.terminal}`);
+            return;
+        }
+        // 单 interval 看门狗。事件到来时只刷新时间戳（无 timer 操作）；
+        // interval 周期检查静默时长，超时才 finish('idle_timeout') + stop()。
+        // 武装点在建卡之后，与原实现一致（宽限期不含 cardSession.start() 耗时）。
+        state.watchdog = this.startIdleWatchdog({
+            runId,
+            session: cardSession,
+            runner,
+            pendingApprovals: pendingApprovalCount.bind(null, this.approvalCoordinators, runId),
+        });
+        getLogger().info(`[lark-remote] runner.run() begin runId=${runId} message=${message.slice(0, 100)}`);
+        // Extract agent-specific options from config
+        const agentOpts = this.getAgentRunOptions(agentKind);
+        const runOpts = { cwd, sessionId, ...agentOpts };
+        // Track whether system.init has been received for this run.
+        // Claude CLI --resume emits a stale result (from the previous turn)
+        // before sending system.init; bridge must not treat that as the run
+        // ending (sawResult, usage capture, or cardSession.push would all
+        // be wrong for the historical event).
+        let sawInit = false;
+        const writeback = {
+            sessionStore: this.sessionStore,
+            userId: ctx.userId,
+            agentKind,
+            cwd,
+            sessionEpochAtStart,
+            runId,
+        };
+        for await (const event of runner.run(message, runOpts)) {
+            // 只有终态才阻止事件处理。finalizing 是非终态，应该继续处理
+            // 这样在 result 事件后，后台任务输出仍能被正确处理
+            const terminal = cardSession.currentState.terminal;
+            if (isRunTerminal(terminal)) {
+                continue;
             }
-            catch (stopErr) {
-                getLogger().warn(`[lark-remote] runner stop failed:`, stopErr);
+            // 归一化：init/turn_started 的 session 写回 + compact_boundary 用量观察。
+            // 返回 true = 本轮 system.init 已到（调用方置 sawInit，供 pre-init 守卫用）。
+            if (this.maybeSyncSession(event, { activeRun, writeback, usage, runId })) {
+                sawInit = true;
             }
-            // 终态守卫：running 或 finalizing（非终态）-> 转 error；
-            // 已终态（interrupted/idle_timeout/done/error）-> 保留首终态，仅补充 usage。
-            const catchTerminal = cardSession.currentState.terminal;
-            if (isRunActive(catchTerminal)) {
-                await cardSession.finish('error', {
-                    ...usage.meta(),
-                    inputTokens: usage.liveInputTokens,
-                    outputTokens: usage.liveOutputTokens,
-                    errorMsg: errorMessage(err),
+            // pre-init result 守卫（§9.22，observeResultEvent）：resume 重放的陈旧
+            // result 不置 sawResult、不进卡片。
+            if (event.type === 'result') {
+                const outcome = this.observeResultEvent(event, {
+                    sawInit,
+                    liveResultEvents,
+                    usage,
+                    writeback,
+                    runId,
                 });
-            }
-            else {
-                getLogger().info(`[lark-remote] skip error finish: state already terminal (${catchTerminal}) runId=${runId}`);
-                if (sawResult) {
-                    await cardSession.finish(catchTerminal, usage.meta());
+                if (outcome.preInitTerminal)
+                    state.pendingPreInitTerminal ??= outcome.preInitTerminal;
+                if (outcome.sawResult)
+                    state.sawResult = true;
+                state.sawAnyResult = true;
+                // 陈旧 result 不进卡片：run-state reducer 本来也会因 sessionId 未定而
+                // 跳过，在 bridge 层就拦掉可以省下一次无谓的 push + render。
+                if (outcome.dropFromCard) {
+                    // 仍然重置 idle 计时——CLI 活着并且在产事件。
+                    this.handleEventForWatchdog(state.watchdog);
+                    continue;
                 }
             }
+            // Approval events (Codex app-server mode)。审批先到、item/started 后到的
+            // 乱序流也在此补全（dispatchApprovalEvent 内 updateView）。
+            if (event.type === 'approval_requested' ||
+                event.type === 'approval_resolved' ||
+                event.type === 'approval_view_updated') {
+                this.dispatchApprovalEvent(event, { runId, runner, cardSession, ctx, agentKind });
+            }
+            // §9.12 红线：每个事件（含 result）无条件刷新
+            // lastEventTs 重新武装看门狗。result 后 CLI 进程做 jsonl flush/清理（finalizing
+            // 过渡）期间，宽限期恢复为完整的 idleTimeoutMs，避免已产出结果的 turn 被误标
+            // idle_timeout。旧实现 `else { resetIdle(); }` 漏掉 result 分支。
+            this.handleEventForWatchdog(state.watchdog);
+            // 渲染：reducer（run-state）在 cardSession.push 内部。
+            await cardSession.push(event);
+        }
+        getLogger().info(`[lark-remote] runner stream end runId=${runId} sawResult=${state.sawResult}`);
+        // §9.12 红线：for-await 自然结束 = CLI 已退出，
+        // 看门狗使命结束，立即摘除 interval（不再等 finally），堵掉「stream 已结束、
+        // 收尾处理跨过死线被误标 idle_timeout」的同源小窗口（随本修复一并关闭）。
+        state.watchdog?.stop();
+        // stream 结束 = CLI 退出 = jsonl 已落盘。读 jsonl 拿准确的 contextLength + compactCount：
+        // live stream-json 不发 compact_boundary，live contextLength 会被 result 的 input+output 兜底失真。
+        // 但 result=error 时跳过: 进程可能立即退出未写新 usage (如 kimi 0.26+ 拒绝 -p+--auto
+        // 立即 exit=1), 此时 jsonl 里是上一次成功 turn 的历史 usage, 会被误当作本次 usage 显示,
+        // 误导用户以为本次出错的请求也消耗了 token。error 时只用 live 捕获的 usage (若有)。
+        // 本轮使用的 session：run 期间 /new //resume //cd 会移动全局
+        // 指针，结束时再读 store 会把别条会话的 token/context 显示到这张卡上。
+        // 优先级：卡片状态（本轮 init 写入）→ activeRun（本轮 init/turn_started）
+        // → 本轮开始时捕获的 sessionId。三者都没有就跳过 usage，绝不回读全局指针。
+        const finalSessionId = cardSession.currentState.sessionId ?? activeRun.sessionId ?? sessionId;
+        const finalUsage = usage.resultNotSuccess
+            ? undefined
+            : resolveFinalUsage(this.sessionReaderRegistry, this.config.defaultAgent, finalSessionId, cwd, agentKind);
+        usage.finalize(finalUsage, usageAuthority);
+        getLogger().info(usage.logSummary(runId));
+        // for-await 自然结束 = stream 关闭 = CLI 进程退出 → 终态矩阵
+        await this.finishRunAfterStream({
+            cardSession,
+            usage,
+            sawResult: state.sawResult,
+            sawAnyResult: state.sawAnyResult,
+            pendingPreInitTerminal: state.pendingPreInitTerminal,
+            agentKind,
+            runId,
+        });
+    }
+    /** runAgentStreamToEnd 的 catch 主体（抽成独立方法，state.sawResult 沿用循环累计值）。 */
+    async handleStreamFailure(err, run) {
+        const { runner, cardSession, runId, usage, state } = run;
+        getLogger().error(`[lark-remote] claude run error runId=${runId}:`, err);
+        // 双保险：run() 的 finally 已负责杀子进程，但 catch 路径再补一次
+        // runner.stop()（与 bash 路径对齐），覆盖任何 finally 之外的残留窗口。
+        try {
+            await runner.stop();
         }
-        finally {
-            watchdog?.stop();
-            const coordinator = this.approvalCoordinators.get(runId);
-            if (coordinator) {
-                coordinator.onTurnEnded();
-                this.approvalCoordinators.delete(runId);
+        catch (stopErr) {
+            getLogger().warn(`[lark-remote] runner stop failed:`, stopErr);
+        }
+        // 终态守卫：running 或 finalizing（非终态）-> 转 error；
+        // 已终态（interrupted/idle_timeout/done/error）-> 保留首终态，仅补充 usage。
+        const catchTerminal = cardSession.currentState.terminal;
+        if (isRunActive(catchTerminal)) {
+            await cardSession.finish('error', {
+                ...usage.meta(),
+                inputTokens: usage.liveInputTokens,
+                outputTokens: usage.liveOutputTokens,
+                errorMsg: errorMessage(err),
+            });
+        }
+        else {
+            getLogger().info(`[lark-remote] skip error finish: state already terminal (${catchTerminal}) runId=${runId}`);
+            if (state.sawResult) {
+                await cardSession.finish(catchTerminal, usage.meta());
             }
         }
     }
+    /** runAgentStreamToEnd 的 finally 主体（抽成独立方法）。 */
+    cleanupStream(run) {
+        const { runId, state } = run;
+        state.watchdog?.stop();
+        const coordinator = this.approvalCoordinators.get(runId);
+        if (coordinator) {
+            coordinator.onTurnEnded();
+            this.approvalCoordinators.delete(runId);
+        }
+    }
     /**
      * 事件循环的看门狗喂狗（runAgentStreamToEnd 抽出的纯向方法）。
      *