lark-remote 0.5.13 → 0.5.14

package/dist/bridge/index.js

@@ -8,15 +8,16 @@ import { renderRunCard, renderRunCardDetailed, } from '../card/run-renderer.js';
 import { splitFinalAnswer } from '../card/final-answer-overflow.js';
 import { renderBashCard } from '../card/bash-renderer.js';
 import { BashCardSession, capBashOutput } from '../card/bash-card-session.js';
-import { isRunTerminal } from '../card/run-state.js';
-import { buildSessionHistoryCard } from '../router/card-helpers.js';
+import { isRunActive, isRunTerminal, removeBackgroundJob, } from '../card/run-state.js';
+import { buildSessionHistoryCard } from '../card/card-helpers.js';
 import { agentDisplayName, resumeUseButton } from '../card/card-shared.js';
 import { enforceCardBudget } from '../card/card-budget.js';
 import { RunUsageCollector } from './run-usage.js';
 import { BashProcessRunner } from '../runner/index.js';
-import { AGENT_KINDS, supportsCompact } from '../runner/types.js';
+import { AGENT_KINDS } from '../agent-kinds.js';
+import { supportsCompact } from '../runner/types.js';
 import { QueueManager, } from './queue-manager.js';
-import { decisionToApprovalAction } from './approval-coordinator.js';
+import { ApprovalActions } from './approval-actions.js';
 import { createRunApprovalCoordinator, remindPendingApproval } from './run-approval.js';
 import { writeBackInitSession, writeBackResultSession, writeBackTurnStarted, } from './session-writeback.js';
 import { InboundMediaHandler } from './inbound-media.js';
@@ -142,6 +143,10 @@ export class Bridge {
     activeRuns = new Map();
     /** Approval coordinators keyed by runId. */
     approvalCoordinators = new Map();
+    /** 审批卡动作的实现（只读上面那张表；见 approval-actions.ts）。 */
+    approvalActions = new ApprovalActions({
+        coordinatorFor: (runId) => this.approvalCoordinators.get(runId),
+    });
     /**
      * 最近若干次已完成的、runner 有 runCompact 的 run（cwd → runId → 记录）。
      * run 结束后 activeRuns 已清空，而终态卡上的 Compact 按钮只带 runId，
@@ -224,13 +229,8 @@ export class Bridge {
         }
         // Create new runner for this (cwd, kind) slot
         const runner = this.agentRegistry.get(kind, cwd);
-        // Call lifecycle methods for agent runners created via factory
-        if (runner && typeof runner.killOrphan === 'function') {
-            runner.killOrphan();
-        }
-        if (runner && typeof runner.registerExitHandlers === 'function') {
-            runner.registerExitHandlers();
-        }
+        runner.killOrphan();
+        runner.registerExitHandlers();
         // Store in nested map: Map<cwd, Map<kind, Runner>>。必须重新取一次：
         // replaceStale 刚把槽位 evict 掉，上面的局部 workspaceMap 可能已随空槽
         // 从 this.runners 移除——继续写它会生成一个「缓存里查不到」的 runner，
@@ -589,7 +589,7 @@ export class Bridge {
         for (const [_cwd, active] of this.activeRuns) {
             const state = active.session.currentState;
             // Only include non-terminal runs
-            if (state.terminal === 'running' || state.terminal === 'finalizing') {
+            if (isRunActive(state.terminal)) {
                 result.push({
                     runId: active.runId,
                     sessionId: state.sessionId ?? '',
@@ -841,7 +841,7 @@ export class Bridge {
     /**
      * Update an existing card in place (原地更新) instead of sending a new one.
      *
-     * Used by /config cardAction handlers (config.toggle/set/input/save) so the
+     * Used by /config cardAction handlers (config.set/input/save) so the
      * user sees the card refresh on the same message bubble rather than getting
      * a new card per click — same-message-bubble update pattern.
      *
@@ -887,7 +887,8 @@ export class Bridge {
             return true;
         }
         catch (err) {
-            getLogger().debug(`[lark-remote] patchCard failed messageId=${messageId}: ${errorMessage(err)}`);
+            // 调用方会据此把卡片从集合里永久剔除——这是用户可见的退化，warn 起步。
+            getLogger().warn(`[lark-remote] patchCard failed messageId=${messageId}: ${errorMessage(err)}`);
             return false;
         }
     }
@@ -925,10 +926,7 @@ export class Bridge {
         const killed = await runner.killJob(sessionId, jobId);
         if (!killed)
             return false;
-        snapshot.state = {
-            ...snapshot.state,
-            backgroundJobs: (snapshot.state.backgroundJobs ?? []).filter((job) => job.id !== jobId),
-        };
+        snapshot.state = removeBackgroundJob(snapshot.state, jobId);
         await this.updateCardInPlace(renderRunCard(snapshot.state, snapshot.options), ctx);
         return true;
     }
@@ -992,7 +990,7 @@ export class Bridge {
         }
         const entry = this.sessionStore.get(ctx.userId);
         getLogger().debug(`[lark-remote] forward entry userId=${ctx.userId} chatId=${ctx.chatId} cwd=${cwd} ` +
-            `agent=${agentKind} sessionId=${opts?.binding?.sessionId ?? entry?.sessions?.get(agentKind) ?? '(none)'} message=${message.slice(0, 100)}`);
+            `agent=${agentKind} sessionId=${opts?.binding?.sessionId ?? entry?.sessions.get(agentKind) ?? '(none)'} message=${message.slice(0, 100)}`);
         // Check if current cwd already has a run in progress
         if (this.activeRuns.has(cwd)) {
             getLogger().warn(`[lark-remote] cwd busy, dropping message userId=${ctx.userId} cwd=${cwd}`);
@@ -1180,6 +1178,139 @@ export class Bridge {
             stop,
         };
     }
+    /**
+     * result 事件的 pre-init 守卫（§9.22）。
+     *
+     * Claude CLI `--resume` 会在 system.init 之前先吐一条**上一轮**的陈旧 result。
+     * 认了它就会过早置 sawResult / 抓错 usage / 让 run-state reducer 提前进入
+     * finalizing（reducer 用 sessionId===undefined 守卫，同一条红线）。本轮真正的
+     * result 在 system.init 之后才到。
+     *
+     * 例外：app-server runner（usageAuthority==='live'）的 init 是 runner 自己补发
+     * 的 synthetic init（2026-08-13 修复）。此分支保留为防御性兜底：live runner 若
+     * 在无 init 时发出 result（旧构建等），session 写回照常执行，但 sawResult 不置
+     * 真——卡片不会把半初始化的 run 当作已收尾。
+     *
+     * @param dropFromCard 该 result 是陈旧重放，不得进卡片（调用方 continue 跳过 push）
+     */
+    observeResultEvent(event, opts) {
+        const { sawInit, usageAuthority, usage, writeback, runId } = opts;
+        const preInitResult = !sawInit;
+        const preInitTerminal = preInitResult && (event.subtype === 'error' || event.subtype === 'interrupted')
+            ? {
+                subtype: event.subtype,
+                errorMessage: event.errorMessage,
+            }
+            : undefined;
+        if (preInitResult && usageAuthority !== 'live') {
+            getLogger().info(`[lark-remote] pre-init result ignored (resume replay) runId=${runId}`);
+            return { sawResult: false, dropFromCard: true, preInitTerminal };
+        }
+        usage.observeResult(event);
+        getLogger().info(preInitResult
+            ? `[lark-remote] pre-init result from live runner (app-server setup failure) runId=${runId}`
+            : `[lark-remote] result event received runId=${runId}`);
+        // app-server 模式 setup 失败路径（thread/start 成功后 turn/start 失败）不会有
+        // turn_started 事件，store 不会写回新线程 id；runner 已在 result 里兜底上报。
+        // 仅当 runner 声明 live usage（app-server）且会话指针未动时写回，避免下条消息
+        // 再开一个孤儿线程。其余 agent 不在此列（各自有 system.init / turn_started 写回）。
+        if (usageAuthority === 'live')
+            writeBackResultSession(writeback, event.session_id);
+        return { sawResult: !preInitResult, dropFromCard: false, preInitTerminal };
+    }
+    /**
+     * 审批三事件的派发（requested / resolved / view_updated）。
+     *
+     * coordinator 一 run 一个，首次 requested 时惰性建好并登记，`finally` 里统一
+     * onTurnEnded + 摘除。
+     */
+    dispatchApprovalEvent(event, opts) {
+        const { runId, runner, cardSession, ctx, agentKind } = opts;
+        if (event.type === 'approval_requested') {
+            // 审批请求到达：撤回 Typing 表情再重发，让飞书重新触发提醒，把用户
+            // 注意力拉回待审批的卡片（run 在等待人工决策，Typing 应重新闪烁）。
+            remindPendingApproval(this.connector, ctx.messageId, runId);
+            let coordinator = this.approvalCoordinators.get(runId);
+            if (!coordinator) {
+                coordinator = createRunApprovalCoordinator({
+                    runner,
+                    cardSession,
+                    config: this.config,
+                    runId,
+                    agentKind,
+                });
+                this.approvalCoordinators.set(runId, coordinator);
+                getLogger().info(`[lark-remote] approval coordinator created runId=${runId.slice(0, 8)} requestId=${event.requestId}`);
+            }
+            coordinator.onRequested(event);
+            return;
+        }
+        const coordinator = this.approvalCoordinators.get(runId);
+        if (event.type === 'approval_resolved') {
+            coordinator?.onResolved(event.requestId);
+            return;
+        }
+        // 乱序流：审批先到、item/started 后到，补全审批卡内容。coordinator
+        // 仅在 pending 时更新（已响应/过期不复活）。
+        coordinator?.updateView(event.requestId, event.view);
+    }
+    /**
+     * 进程退出（for-await 自然结束）后的终态矩阵——它是本轮的唯一终态触发源。
+     *
+     * 1) finalizing（result 已收到）→ 三态映射 + usage meta
+     * 2) running（未收到 result）→ 错误路径；pre-init 终态优先当唯一线索
+     * 3) 已终态 + sawResult → 首终态不动，仅补 usage meta
+     * 4) 已终态且未收到 result（如 spawn 失败后 interrupted）→ 无 usage 可补，跳过
+     */
+    async finishRunAfterStream(opts) {
+        const { cardSession, usage, sawResult, pendingPreInitTerminal, agentKind, runId } = opts;
+        const finalState = cardSession.currentState;
+        if (finalState.terminal === 'finalizing') {
+            // 三态终态映射（2026-08-14）：interrupted（审批超时/取消、/stop）是独立
+            // 终态，不再归因于 Agent 错误；error 保持「运行出错」；其余为 done。
+            const subtype = finalState.resultSubtype;
+            const isError = subtype === 'error' || !!finalState.errorMsg;
+            // goal 仍 active = 宿主会自动起下一轮：这不是"完成"，而是"本轮结束"。
+            // 用独立终态而不是 done，既不改 header 文案也不用谎报。
+            const goalContinues = !isError && subtype !== 'interrupted' && finalState.goal?.phase === 'active';
+            const terminal = isError
+                ? 'error'
+                : subtype === 'interrupted'
+                    ? 'interrupted'
+                    : goalContinues
+                        ? 'goal_continuing'
+                        : 'done';
+            await cardSession.finish(terminal, {
+                resultSubtype: subtype,
+                errorMsg: finalState.errorMsg,
+                ...usage.meta(),
+            });
+            return;
+        }
+        if (finalState.terminal === 'running') {
+            if (pendingPreInitTerminal) {
+                const terminal = pendingPreInitTerminal.subtype === 'interrupted' ? 'interrupted' : 'error';
+                getLogger().warn(`[lark-remote] stream ended without init; using pre-init ${terminal} result runId=${runId} error=${pendingPreInitTerminal.errorMessage ?? '(none)'}`);
+                await cardSession.finish(terminal, {
+                    ...usage.meta(),
+                    errorMsg: pendingPreInitTerminal.errorMessage ??
+                        agentDisplayName(agentKind) + (terminal === 'interrupted' ? ' 已中断' : ' 启动失败'),
+                });
+            }
+            else {
+                await cardSession.finish('error', {
+                    ...usage.meta(),
+                    errorMsg: agentDisplayName(agentKind) + ' 输出流已结束，但未收到 result 事件',
+                });
+            }
+            return;
+        }
+        if (sawResult) {
+            // 已终态（interrupted/idle_timeout）+ result 已收到：首终态优先，
+            // 仅补充 usage meta（finalizing 期间被 /stop 或 idle 超时也展示 token 统计）
+            await cardSession.finish(finalState.terminal, usage.meta());
+        }
+    }
     /**
      * Step 2 of forwardToClaude: Run the agent and consume its event stream.
      * Handles idle watchdog, event processing, session sync, and state transitions.
@@ -1276,83 +1407,30 @@ export class Bridge {
                     usage.observeCompaction(event.compactMetadata.postTokens);
                 }
                 if (event.type === 'result') {
-                    // Pre-init result guard: Claude CLI --resume emits a stale result
-                    // (from the previous turn) before system.init. Ignoring it prevents
-                    // premature sawResult/usage capture and the run-state reducer (which
-                    // also guards on sessionId === undefined) from transitioning to
-                    // finalizing too early. The real result for this run arrives after
-                    // system.init.
-                    //
-                    // Exception: app-server runners (usageAuthority === 'live') 的 init
-                    // 是 runner 补发的 synthetic init（2026-08-13 修复）。此分支保留为
-                    // 防御性兜底：任何 live runner 若在无 init 时发出 result（如旧构建、
-                    // 其它 live runner），session 写回仍执行，但 sawResult 保持 false，
-                    // 卡片不会把半初始化的 run 当作已收尾。
-                    const preInitResult = !sawInit;
-                    if (preInitResult && usageAuthority !== 'live') {
-                        getLogger().info(`[lark-remote] pre-init result ignored (resume replay) runId=${runId}`);
-                        if (event.subtype === 'error' || event.subtype === 'interrupted') {
-                            pendingPreInitTerminal ??= {
-                                subtype: event.subtype,
-                                errorMessage: event.errorMessage,
-                            };
-                        }
-                        // Still reset idle timer — the CLI is alive and producing events.
+                    const outcome = this.observeResultEvent(event, {
+                        sawInit,
+                        usageAuthority,
+                        usage,
+                        writeback,
+                        runId,
+                    });
+                    if (outcome.preInitTerminal)
+                        pendingPreInitTerminal ??= outcome.preInitTerminal;
+                    if (outcome.sawResult)
+                        sawResult = true;
+                    // 陈旧 result 不进卡片：run-state reducer 本来也会因 sessionId 未定而
+                    // 跳过，在 bridge 层就拦掉可以省下一次无谓的 push + render。
+                    if (outcome.dropFromCard) {
+                        // 仍然重置 idle 计时——CLI 活着并且在产事件。
                         watchdog?.touch();
-                        // Do NOT push to cardSession: the run-state reducer would also
-                        // skip it (sessionId === undefined), but skipping at the bridge
-                        // layer avoids the push + render overhead for a no-op event.
                         continue;
                     }
-                    if (preInitResult && (event.subtype === 'error' || event.subtype === 'interrupted')) {
-                        pendingPreInitTerminal ??= {
-                            subtype: event.subtype,
-                            errorMessage: event.errorMessage,
-                        };
-                    }
-                    if (!preInitResult) {
-                        sawResult = true;
-                    }
-                    usage.observeResult(event);
-                    getLogger().info(preInitResult
-                        ? `[lark-remote] pre-init result from live runner (app-server setup failure) runId=${runId}`
-                        : `[lark-remote] result event received runId=${runId}`);
-                    // app-server 模式 setup 失败路径（thread/start 成功后 turn/start 失败）
-                    // 不会有 turn_started 事件，store 不会写回新线程 id；runner 已在 result
-                    // 里兜底上报。此处仅当 runner 声明 live usage（app-server）
-                    // 且会话指针未动时写回，避免下条消息再开一个孤儿线程。其余 agent 不在
-                    // 此列（它们各自有 system.init / turn_started 写回）。
-                    if (usageAuthority === 'live')
-                        writeBackResultSession(writeback, event.session_id);
                 }
                 // Approval events (Codex app-server mode)
-                if (event.type === 'approval_requested') {
-                    // 审批请求到达：撤回 Typing 表情再重发，让飞书重新触发提醒，把用户
-                    // 注意力拉回待审批的卡片（run 在等待人工决策，Typing 应重新闪烁）。
-                    remindPendingApproval(this.connector, ctx.messageId, runId);
-                    let coordinator = this.approvalCoordinators.get(runId);
-                    if (!coordinator) {
-                        coordinator = createRunApprovalCoordinator({
-                            runner,
-                            cardSession,
-                            config: this.config,
-                            runId,
-                            agentKind,
-                        });
-                        this.approvalCoordinators.set(runId, coordinator);
-                        getLogger().info(`[lark-remote] approval coordinator created runId=${runId.slice(0, 8)} requestId=${event.requestId}`);
-                    }
-                    coordinator.onRequested(event);
-                }
-                else if (event.type === 'approval_resolved') {
-                    const coordinator = this.approvalCoordinators.get(runId);
-                    coordinator?.onResolved(event.requestId);
-                }
-                else if (event.type === 'approval_view_updated') {
-                    // 乱序流：审批先到、item/started 后到，补全审批卡内容。coordinator
-                    // 仅在 pending 时更新（已响应/过期不复活）。
-                    const coordinator = this.approvalCoordinators.get(runId);
-                    coordinator?.updateView(event.requestId, event.view);
+                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
@@ -1381,56 +1459,15 @@ export class Bridge {
                 : resolveFinalUsage(this.sessionReaderRegistry, this.config.defaultAgent, finalSessionId, cwd, agentKind);
             usage.finalize(finalUsage, usageAuthority);
             getLogger().info(usage.logSummary(runId));
-            // for-await 自然结束 = stream 关闭 = CLI 进程退出。
-            // 进程退出（for-await end）= 唯一终态触发源。
-            // 1) finalizing（result 已收到）-> 转 done/error + usage meta
-            // 2) running（未收到 result）-> 错误路径
-            // 3) 已终态 + sawResult -> 补充 usage meta（不改 terminal）
-            const finalState = cardSession.currentState;
-            if (finalState.terminal === 'finalizing') {
-                // 三态终态映射（2026-08-14）：interrupted（审批超时/取消、/stop）是独立
-                // 终态，不再归因于 Agent 错误；error 保持「运行出错」；其余为 done。
-                const subtype = finalState.resultSubtype;
-                const isError = subtype === 'error' || !!finalState.errorMsg;
-                // goal 仍 active = 宿主会自动起下一轮：这不是"完成"，而是"本轮结束"。
-                // 用独立终态而不是 done，既不改 header 文案也不用谎报。
-                const goalContinues = !isError && subtype !== 'interrupted' && finalState.goal?.phase === 'active';
-                const terminal = isError
-                    ? 'error'
-                    : subtype === 'interrupted'
-                        ? 'interrupted'
-                        : goalContinues
-                            ? 'goal_continuing'
-                            : 'done';
-                await cardSession.finish(terminal, {
-                    resultSubtype: subtype,
-                    errorMsg: finalState.errorMsg,
-                    ...usage.meta(),
-                });
-            }
-            else if (finalState.terminal === 'running') {
-                if (pendingPreInitTerminal) {
-                    const terminal = pendingPreInitTerminal.subtype === 'interrupted' ? 'interrupted' : 'error';
-                    getLogger().warn(`[lark-remote] stream ended without init; using pre-init ${terminal} result runId=${runId} error=${pendingPreInitTerminal.errorMessage ?? '(none)'}`);
-                    await cardSession.finish(terminal, {
-                        ...usage.meta(),
-                        errorMsg: pendingPreInitTerminal.errorMessage ??
-                            agentDisplayName(agentKind) + (terminal === 'interrupted' ? ' 已中断' : ' 启动失败'),
-                    });
-                }
-                else {
-                    await cardSession.finish('error', {
-                        ...usage.meta(),
-                        errorMsg: agentDisplayName(agentKind) + ' 输出流已结束，但未收到 result 事件',
-                    });
-                }
-            }
-            else if (sawResult) {
-                // 已终态（interrupted/idle_timeout）+ result 已收到：首终态优先，
-                // 仅补充 usage meta（finalizing 期间被 /stop 或 idle 超时也展示 token 统计）
-                await cardSession.finish(finalState.terminal, usage.meta());
-            }
-            // else: 已终态且未收到 result（如 spawn 失败后 interrupted）-> 无 usage 可补，跳过
+            // for-await 自然结束 = stream 关闭 = CLI 进程退出 → 终态矩阵
+            await this.finishRunAfterStream({
+                cardSession,
+                usage,
+                sawResult,
+                pendingPreInitTerminal,
+                agentKind,
+                runId,
+            });
         }
         catch (err) {
             getLogger().error(`[lark-remote] claude run error runId=${runId}:`, err);
@@ -1445,7 +1482,7 @@ export class Bridge {
             // 终态守卫：running 或 finalizing（非终态）-> 转 error；
             // 已终态（interrupted/idle_timeout/done/error）-> 保留首终态，仅补充 usage。
             const catchTerminal = cardSession.currentState.terminal;
-            if (catchTerminal === 'running' || catchTerminal === 'finalizing') {
+            if (isRunActive(catchTerminal)) {
                 await cardSession.finish('error', {
                     ...usage.meta(),
                     inputTokens: usage.liveInputTokens,
@@ -1612,90 +1649,36 @@ export class Bridge {
     // =============================================================================
     // Approval action handlers
     // =============================================================================
-    /**
-     * Resolve the ApprovalCoordinator for a run, or throw the standard
-     * "已结束" error. Shared preamble of all approval card-action handlers.
-     */
-    withCoordinator(runId, fn) {
-        const coordinator = this.approvalCoordinators.get(runId);
-        if (!coordinator) {
-            // run 已结束（coordinator 已释放）时点击审批按钮必须给用户明确反馈，
-            // 不能静默。router 会把该异常转成 error toast。
-            getLogger().warn(`[lark-remote] no approval coordinator for runId=${runId.slice(0, 8)}`);
-            throw new Error('任务已结束，审批无法响应');
-        }
-        return fn(coordinator);
-    }
-    /**
-     * Handle an approval response from a card button click.
-     * Routes to the ApprovalCoordinator for the given run.
-     */
+    // 实现住在 approval-actions.ts（审计 #32）：这 7 个入口只碰
+    // approvalCoordinators 一张表，不碰其余 Bridge 状态。方法名保持 Bridge 的
+    // 公开 API 不变——router 的 APPROVAL_ACTION_SPECS 按名字分发。
+    /** 审批响应（卡片按钮）→ ApprovalCoordinator.submit。 */
     async handleApprovalRespond(opts) {
-        const log = getLogger();
-        log.info(`[lark-remote] handleApprovalRespond runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} decision=${opts.decision}`);
-        return this.withCoordinator(opts.runId, async (coordinator) => {
-            // Build ApprovalAction from the decision string
-            const action = decisionToApprovalAction(opts.decision);
-            await coordinator.submit(action, { requestId: opts.requestId, nonce: opts.nonce });
-        });
+        return this.approvalActions.handleApprovalRespond(opts);
     }
-    /**
-     * 计划审批修改意见（ExitPlanMode 输入框）：记录到 coordinator 并回流卡片。
-     * 「拒绝并附意见」/「批准并采纳修改」按钮复用该文本。
-     */
+    /** 计划审批修改意见（ExitPlanMode 输入框）→ coordinator.planFeedback。 */
     async handleApprovalPlanFeedback(opts) {
-        return this.withCoordinator(opts.runId, async (coordinator) => {
-            await coordinator.planFeedback({ text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce });
-        });
+        return this.approvalActions.handleApprovalPlanFeedback(opts);
     }
-    /**
-     * Handle a permission toggle from a card button click.
-     * Routes to the ApprovalCoordinator for the given run.
-     */
+    /** 权限条目勾选（卡片按钮）→ coordinator.togglePerm。 */
     async handleApprovalToggle(opts) {
-        const log = getLogger();
-        log.info(`[lark-remote] handleApprovalToggle runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} permId=${opts.permId}`);
-        return this.withCoordinator(opts.runId, async (coordinator) => {
-            // selected 由卡片根据当前渲染状态传回（取反），不再硬编码只授不撤。
-            const toggleAction = {
-                permId: opts.permId,
-                selected: opts.selected ?? true,
-            };
-            await coordinator.togglePerm(toggleAction, { requestId: opts.requestId });
-        });
+        return this.approvalActions.handleApprovalToggle(opts);
     }
-    /**
-     * Claude AskUserQuestion 选项点击（单选即时提交 / 多选切换勾选）。
-     * 路由到 ApprovalCoordinator.toggleAnswer。
-     */
+    /** AskUserQuestion 选项点击 → coordinator.toggleAnswer。 */
     async handleApprovalAnswer(opts) {
-        return this.dispatchQuestionAction(opts, 'handleApprovalAnswer', (coordinator) => coordinator.toggleAnswer({ questionIndex: opts.questionIndex, option: opts.option }, { requestId: opts.requestId, nonce: opts.nonce }));
+        return this.approvalActions.handleApprovalAnswer(opts);
     }
-    /**
-     * Claude AskUserQuestion 多选问题的「提交答案」按钮。
-     * 路由到 ApprovalCoordinator.submitAnswers。
-     */
+    /** AskUserQuestion 多选「提交答案」→ coordinator.submitAnswers。 */
     async handleApprovalAnswerSubmit(opts) {
-        return this.dispatchQuestionAction(opts, 'handleApprovalAnswerSubmit', (coordinator) => coordinator.submitAnswers({ questionIndex: opts.questionIndex }, { requestId: opts.requestId, nonce: opts.nonce }));
+        return this.approvalActions.handleApprovalAnswerSubmit(opts);
     }
-    /**
-     * Claude AskUserQuestion 自定义答案（Other）：自由文本直接
-     * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
-     */
+    /** AskUserQuestion 自定义答案（Other）→ coordinator.answerCustom。 */
     async handleApprovalAnswerCustom(opts) {
-        return this.dispatchQuestionAction(opts, 'handleApprovalAnswerCustom', (coordinator) => coordinator.answerCustom({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
+        return this.approvalActions.handleApprovalAnswerCustom(opts);
     }
-    /**
-     * Codex AskUserQuestion 补充说明（user_note，2026-08-18 live 验证模型理解
-     * "user_note: <text>" 条目）：记录到 coordinator，随答案一起提交。
-     * 路由到 ApprovalCoordinator.answerNote。
-     */
+    /** AskUserQuestion 补充说明（user_note）→ coordinator.answerNote。 */
     async handleApprovalAnswerNote(opts) {
-        return this.dispatchQuestionAction(opts, 'handleApprovalAnswerNote', (coordinator) => coordinator.answerNote({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
-    }
-    dispatchQuestionAction(opts, action, invoke) {
-        getLogger().info(`[lark-remote] ${action} runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
-        return this.withCoordinator(opts.runId, invoke);
+        return this.approvalActions.handleApprovalAnswerNote(opts);
     }
     /**
      * 记下一次「可压缩 run」：终态卡上的 Compact 按钮点击时据此反查
@@ -1817,14 +1800,14 @@ export class Bridge {
         });
     }
     /**
-     * §5.3: kimi 压缩在途检测——reader 鸭子实现 `readCompactionState` 时，若
+     * §5.3: kimi 压缩在途检测——reader 实现契约的 `readCompactionState` 时，若
      * wire 状态机判定当前有未终结的压缩（最后一次 begin 无 terminal 记录），
      * 直接回文本「已有一次 Compact 正在进行」并返回 true（调用方不开卡、不发
      * session/prompt）。codex/claude 等 reader 无此方法 → 返回 false，行为不变。
      */
     async rejectIfCompactionInFlight(sessionId, cwd, agentKind, ctx) {
         const reader = this.sessionReaderRegistry.get(agentKind);
-        if (!reader || !('readCompactionState' in reader))
+        if (!reader?.readCompactionState)
             return false;
         try {
             const state = reader.readCompactionState(sessionId, cwd);
@@ -1952,20 +1935,9 @@ export class Bridge {
             await cardSession.finish(terminal, {
                 resultSubtype: resultSubtype ?? 'error',
                 errorMsg: terminal === 'error' ? (resultError ?? '未收到压缩结果') : undefined,
-                contextLength: finalUsage?.contextLength,
-                contextLimit: finalUsage?.contextLimit,
-                compactPreContextLength: finalUsage?.compactPreContextLength,
-                compactCount: finalUsage?.compactCount,
-                cacheReadTokens: finalUsage?.cacheReadTokens,
-                cacheCreationTokens: finalUsage?.cacheCreationTokens,
-                totalTokens: finalUsage?.totalTokens,
-                inputTokens: finalUsage?.inputTokens,
-                outputTokens: finalUsage?.outputTokens,
-                cumulativeTotalTokens: finalUsage?.cumulativeTotalTokens,
-                cumulativeInputTokens: finalUsage?.cumulativeInputTokens,
-                cumulativeOutputTokens: finalUsage?.cumulativeOutputTokens,
-                cumulativeCacheReadTokens: finalUsage?.cumulativeCacheReadTokens,
-                cumulativeCacheCreationTokens: finalUsage?.cumulativeCacheCreationTokens,
+                // finalUsage 的字段形态就是 FinishMeta 的用量部分（同为 UsageSnapshot），
+                // 逐字段抄的那 14 行随单源一起去掉。
+                ...(finalUsage ?? {}),
             });
             log.info(`[lark-remote] streamCompact finished sessionId=${sessionId} sawResult=${sawResult} subtype=${resultSubtype ?? 'none'}`);
         }

package/dist/bridge/queue-manager.d.ts

@@ -1,4 +1,4 @@
-import type { AgentKind } from '../runner/types.js';
+import type { AgentKind } from '../agent-kinds.js';
 /**
  * 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
  * 唯一捕获点：排队消息在入队时刻把 agent+session 钉进 AgentBinding，随任务闭包带到执行时刻
@@ -221,8 +221,32 @@ export declare class QueueManager {
     /**
      * Enqueue a task into the workspace-level serial queue.
      * Each cwd has its own serial queue for parallel execution across workspaces.
+     *
+     * 三段各自的职责：`registerQueuedTask`（排队元数据 + 满队拒收）、
+     * `beginQueuedTask`（接跑时刻的撤销检查/替换闭包/占用登记）、本方法
+     * （promise 链拼接与 settle 记账）。红线：链的拼接必须同步完成，
+     * 中途不得 await（否则两条入队会乱序）。
      */
     enqueue(cwd: string, task: () => Promise<void>, opts?: EnqueueOptions): void;
+    /**
+     * 登记排队元数据（展示卡数据源 + 计数 + 排队卡）。
+     *
+     * @returns false = 队列已满被拒收（不入队、不占执行槽位），调用方必须
+     *   直接把任务链跳过。背压红线：满队时拒收而不是继续 append，否则 promise
+     *   链与闭包在消息洪峰下无界增长，还会多打一张排队卡。
+     */
+    private registerQueuedTask;
+    /** 满队拒收卡（best-effort 送达，失败只记日志：任务已经被拒，不能再吞一次反馈）。 */
+    private sendQueueFullRejection;
+    /**
+     * 轮到本任务执行：撤销检查 → 消费一次性替换闭包 → 排队卡转「执行中」→
+     * 重新武装计数与 lane 占用登记 → 跑任务闭包。
+     *
+     * @returns 任务闭包的 promise；被撤销时返回 undefined（本槽位什么都不跑）。
+     */
+    private beginQueuedTask;
+    /** 取走并清除该任务的一次性替换闭包（消费即销毁）。 */
+    private takeTaskReplacement;
     /**
      * Execute a task immediately without going through the queue.
      * Used for / commands that should respond immediately.