lark-remote 0.1.5 → 0.1.7

package/dist/bridge/index.js

@@ -1,17 +1,18 @@
 import { randomUUID } from 'node:crypto';
+import { sleep } from '../common/sleep.js';
 import { getLogger } from '../logger/index.js';
 import { RunCardSession } from '../card/run-card-session.js';
 import { renderRunCard } from '../card/run-renderer.js';
 import { renderBashCard } from '../card/bash-renderer.js';
 import { BashCardSession, capBashOutput } from '../card/bash-card-session.js';
-import { markdownDiv } from '../card/collapsible.js';
-import { sessionEventPanel } from '../router/card-helpers.js';
-import { formatUsageStats } from '../router/index.js';
+import { buildSessionHistoryCard } from '../router/card-helpers.js';
 import { agentDisplayName, resumeUseButton } from '../card/card-shared.js';
 import { enforceCardBudget } from '../card/card-budget.js';
 import { normalizeResultUsage } from '../runner/common/usage.js';
 import { BashProcessRunner } from '../runner/index.js';
 import { QueueManager, } from './queue-manager.js';
+import { ApprovalCoordinator, decisionToApprovalAction } from './approval-coordinator.js';
+import { InboundMediaHandler } from './inbound-media.js';
 /**
  * Max events to read for the completion notification card (mirror router's
  * AUTO_RESUME_MAX_EVENTS = 5). Without a cap, readSessionContent returns every
@@ -19,6 +20,14 @@ import { QueueManager, } from './queue-manager.js';
  * budget (review §P1-21).
  */
 const COMPLETION_NOTIFICATION_MAX_EVENTS = 5;
+/** Approval request timeout (ms) — pending approval expires after this. */
+const APPROVAL_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * runner 缓存的工作区数量上限（review P3-3）：超过后创建新工作区槽位时
+ * 顺带回收「非 active 且进程已停」的死缓存，防止随访问过的工作区数量
+ * 无界增长。活进程/在途 run 一律保留（workspace-lifetime 长驻连接不能误杀）。
+ */
+const MAX_CACHED_RUNNER_WORKSPACES = 10;
 /**
  * Max idle time (no stdout events) before a claude run is considered hung
  * (§9.12). When this fires the bridge calls `runner.stop()` to unblock the
@@ -58,7 +67,9 @@ function terminalReactionEmoji(terminal) {
  * Runner/BridgeChannel seams.
  */
 export class Bridge {
+    /** 飞书连接通道（public：集成测试的 seam，替代 as unknown as 访问）。 */
     connector;
+    /** 会话存储（public：测试辅助读取/写入 cwd 等，替代私有访问）。 */
     sessionStore;
     config;
     workspaceStore;
@@ -67,6 +78,8 @@ export class Bridge {
     agentRegistry;
     /** Session reader registry for usage and completion cards. */
     sessionReaderRegistry;
+    /** 入站媒体（图片/文件）落盘 + 合批提示。 */
+    mediaHandler;
     /**
      * Per-workspace runner instances, keyed by (cwd, agentKind).
      * Fix 4 (2026-07-18): Each agentKind has its own cache slot, so switching
@@ -77,9 +90,17 @@ export class Bridge {
      */
     runners = new Map();
     /** Queue manager for per-workspace serial processing queue. */
+    /** 普通消息队列管理器（public：测试注入 queue-card 状态用）。 */
     queueManager;
     /** Active runs per workspace (cwd). Multiple workspaces can run in parallel. */
     activeRuns = new Map();
+    /** Approval coordinators keyed by runId. */
+    approvalCoordinators = new Map();
+    /**
+     * 最近一次已完成的 codex app-server run（按 cwd）。run 结束后 activeRuns
+     * 已清空，Compact 需要它来校验 runId 并提供 sessionId。
+     */
+    lastCompactableCodexRun = new Map();
     /**
      * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
      * queue and may run in parallel with claude runs / other bash runs in the same
@@ -96,6 +117,11 @@ export class Bridge {
         this.agentRegistry = deps.agentRegistry;
         this.sessionReaderRegistry = deps.sessionReaderRegistry;
         this.queueManager = new QueueManager((workspace) => this.activeRuns.has(workspace), (chatId, card, opts) => this.connector.sendWithRetry(chatId, { card }, { replyTo: opts?.replyTo }), (messageId, card) => this.connector.updateCard(messageId, card));
+        this.mediaHandler = new InboundMediaHandler({
+            resolveCwd: (userId) => this.resolveCwd(userId),
+            getConfig: () => this.config,
+            send: async (ctx, text) => this.sendResult({ text }, ctx),
+        });
     }
     /**
      * Get or create a runner for the given workspace, keyed by current defaultAgent.
@@ -110,6 +136,20 @@ export class Bridge {
         if (workspaceMap?.has(kind)) {
             return workspaceMap.get(kind);
         }
+        // review P3-3：缓存超过上限且是新工作区时才回收死槽位——刚创建未 run
+        // 的 runner 同样是 isRunning=false，小缓存下立即回收会破坏「创建即注册」
+        // 的既有语义（exit-dispatcher 计数回归）。
+        if (this.runners.size >= MAX_CACHED_RUNNER_WORKSPACES && !this.runners.has(workspace)) {
+            for (const [cwd, slotMap] of [...this.runners.entries()]) {
+                if (this.activeRuns.has(cwd))
+                    continue;
+                for (const [slotKind, r] of [...slotMap.entries()]) {
+                    if (!r.isRunning) {
+                        this.evictRunnerSlot(cwd, slotKind);
+                    }
+                }
+            }
+        }
         // Create new runner for this (workspace, kind) slot
         const runner = this.agentRegistry.get(kind, workspace);
         // Call lifecycle methods for agent runners created via factory
@@ -137,10 +177,69 @@ export class Bridge {
             container.current = config;
         }
     }
+    /**
+     * Push updated approval-mode settings to active workspace-lifetime runners.
+     * `clearRunners()` deliberately skips workspaces with active runs; this
+     * gives those runners a chance to apply the new settings immediately via
+     * the unified duck method `updateApprovalMode` (codex → thread/settings/
+     * update, kimi → session/set_mode, opencode → session/set_mode) instead of
+     * keeping a stale snapshot until the runner is evicted/recreated.
+     */
+    syncActiveApprovalModes() {
+        for (const [cwd, active] of this.activeRuns) {
+            const runner = active.runner;
+            if (typeof runner.updateApprovalMode !== 'function')
+                continue;
+            const settings = this.approvalModeSettingsFor(active.agentKind);
+            if (!settings)
+                continue;
+            void runner.updateApprovalMode(settings).catch((err) => {
+                getLogger().warn(`[bridge] sync approval mode failed cwd=${cwd}: ${err.message}`);
+            });
+        }
+    }
+    /** 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 };
+            }
+            default:
+                return undefined;
+        }
+    }
     /** Get the current runner for a workspace. Used by router for agent-specific commands (P3.2). */
     getCurrentRunner(workspace) {
         return this.getRunner(workspace);
     }
+    /**
+     * Whether the runner for the given agent kind has runCompact capability.
+     * Used by router for compact button gating (design doc §6.2-2: duck-typing
+     * instead of hardcoding agentKind === 'codex').
+     */
+    hasRunCompact(workspace, kind = this.config.defaultAgent) {
+        const runner = this.getRunner(workspace, kind);
+        return ('runCompact' in runner && typeof runner.runCompact === 'function');
+    }
     /** 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
      *  唯一捕获点：排队消息在 T0 把 agent+session 钉进 AgentBinding，随任务闭包带到 T1
      *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移（方案 D4）。 */
@@ -182,6 +281,11 @@ export class Bridge {
         if (evicted && typeof evicted.unregisterExitHandlers === 'function') {
             evicted.unregisterExitHandlers();
         }
+        // App-server runner owns a persistent connection — dispose it so the
+        // `codex app-server` child process does not leak across runs/evictions.
+        if (evicted && typeof evicted.dispose === 'function') {
+            void evicted.dispose();
+        }
         workspaceMap.delete(kind);
         if (workspaceMap.size === 0) {
             this.runners.delete(cwd);
@@ -201,6 +305,7 @@ export class Bridge {
      * Extract agent-specific run options from config.
      * Returns model/effort/etc. based on current defaultAgent.
      */
+    /** 解析某 agent 的 run 选项（forwardToClaude 用；测试直接调用的 seam）。 */
     getAgentRunOptions(agent = this.config.defaultAgent) {
         const agents = this.config.agents;
         const result = {};
@@ -406,7 +511,10 @@ export class Bridge {
                 // its slot interrupted, hiding it from queue cards (A22).
                 const stoppedSlot = this.queueManager.getExecutingSlot(cwd);
                 await Promise.allSettled([
-                    active.session.finish('interrupted'),
+                    // 用户主动中断（/stop、stop 卡按钮、queue.immediate）显式打标
+                    // interruptedReason，与审批超时自动取消（approval_timeout）、审批
+                    // 卡取消（approval_cancelled）在终态数据上可区分（方案 A）。
+                    active.session.finish('interrupted', { interruptedReason: 'user_stop' }),
                     runner.stop({ immediate: true }),
                 ]);
                 // The chain may have advanced while the stop was in flight: a new run
@@ -483,6 +591,15 @@ export class Bridge {
         }
         catch (err) {
             getLogger().error('[bridge] failed to send result:', err);
+            // 不静默：向用户发送一条纯文本消息，告知具体错误（如飞书 11310 element exceeds
+            // the limit）。如果用户看到空白无反馈，无法判断是命令无效还是卡片发送失败。
+            try {
+                const errMsg = err.message ?? String(err);
+                await this.connector.sendWithRetry(ctx.chatId, { text: `⚠️ 卡片发送失败：${errMsg}` }, { replyTo: ctx.messageId });
+            }
+            catch (fallbackErr) {
+                getLogger().error('[bridge] fallback text send also failed:', fallbackErr);
+            }
             return false;
         }
     }
@@ -511,7 +628,10 @@ export class Bridge {
             return true;
         }
         catch (err) {
-            getLogger().warn(`[bridge] updateCardInPlace failed, falling back to sendResult: ${err.message}`);
+            const errMsg = err.message ?? String(err);
+            getLogger().warn(`[bridge] updateCardInPlace failed, falling back to sendResult: ${errMsg}`);
+            // 先尝试 fallback 发卡片；若卡片本身有问题（如 11310），
+            // sendResult 内部 catch 会发纯文本通知用户。
             await this.sendResult({ card }, ctx);
             return false;
         }
@@ -527,6 +647,18 @@ export class Bridge {
             await this.sendResult({ text: `发送文件失败: ${err.message}` }, ctx);
         }
     }
+    /** 入站媒体落盘入口（connector 下载完成后调用）。 */
+    async onInboundMedia(payload) {
+        await this.mediaHandler.handle(payload);
+    }
+    /** 文本消息到达时立即冲刷待合批的媒体保存提示。 */
+    flushMediaNotifications(userId, chatId) {
+        this.mediaHandler.flushAll(userId, chatId);
+    }
+    /** 冲刷全部待合批提示（/exit、/restart 干净退出前调用）。 */
+    async flushAllMediaNotifications() {
+        await this.mediaHandler.flushAllPending();
+    }
     /** Reconnect the underlying Feishu channel. */
     async reconnect() {
         await this.connector.reconnect();
@@ -641,6 +773,9 @@ export class Bridge {
      * Handles idle watchdog, event processing, session sync, and state transitions.
      */
     async runAgentStreamToEnd(runner, cardSession, sessionId, sessionEpochAtStart, ctx, cwd, runId, message, agentKind = this.config.defaultAgent) {
+        // Runner 声明的 usage 权威来源（review P3-7）：codex app-server = 'live'
+        // （turn/started 的 tokenUsage.last 是本 turn 增量）。其余 runner 未声明。
+        const usageAuthority = runner.getUsageAuthority?.();
         // P2-1: idle watchdog 用单 interval + lastEventTs 截止时间判定，而非每事件
         // clearTimeout + setTimeout 重建 timer。高频事件流下 timer 重建次数与事件数
         // 成正比（N 事件 = N 次 setTimeout + N 个闭包/秒）；interval 方案只建一个
@@ -650,7 +785,7 @@ export class Bridge {
         let idleInterval = null;
         let sawResult = false;
         // 记录 result 是否为 error: error 时跳过 jsonl usage 读取 (见 stream end 处说明)
-        let resultWasError = false;
+        let resultNotSuccess = false;
         // Final usage read from jsonl after the run completes. live stream-json does
         // not emit compact_boundary, so the live contextLength is unreliable.
         let finalContextLength;
@@ -664,6 +799,10 @@ export class Bridge {
         // done card shows real values instead of the 10% estimate.
         let liveInputTokens;
         let liveOutputTokens;
+        // Real context window limit from the live result event (codex app-server
+        // carries it in ResultEvent.usage.context_limit). jsonl wins when present;
+        // live is the fallback (app-server error runs / jsonl 未落盘时).
+        let liveContextLimit;
         // Final input/output for the done card: live value wins (codex/opencode
         // carry per-run usage in the result event); jsonl is the fallback for
         // agents whose live stream has no usage (kimi).
@@ -697,6 +836,15 @@ export class Bridge {
             // "15min 无事件即 stop" 的语义不变（§9.12）。周期取 idleTimeoutMs/2，使停滞
             // 后最多在 1.5× idleTimeoutMs 内触发（半个窗口延迟，watchdog 语义可接受）。
             const fireIdleTimeout = () => {
+                // 权限等待期间暂停空闲看门狗：claude/codex 等待人工决策时无 stdout
+                // 事件，「等审批」不是「挂死」。审批由 ApprovalCoordinator 的超时
+                // （默认 5 分钟 < 看门狗窗口）自愈：cancel 送达 + 中断 turn，不会无限
+                // 挂起。
+                const pendingApproval = this.approvalCoordinators.get(runId)?.pendingCount() ?? 0;
+                if (pendingApproval > 0) {
+                    lastEventTs = Date.now();
+                    return;
+                }
                 if (idleInterval)
                     clearInterval(idleInterval);
                 idleInterval = null;
@@ -746,7 +894,7 @@ export class Bridge {
                     // 代际守卫：run 在途时 /new（或 new-session 卡片、/cd、/resume、
                     // /config 切换）移动了 session 指针，此 init 的写回是 stale 的——
                     // 跳过，否则 /new 的清空会被在途 run 静默撤销（2026-08-09 事故：
-                    // task-notification 注入触发 Claude 重发 init，e8defc46 复活）。
+                    // task-notification 注入触发 Claude 重发 init，已终止的 run 被复活）。
                     const pointerMoved = this.sessionStore.getSessionEpoch(ctx.userId, agentKind) !== sessionEpochAtStart;
                     if (pointerMoved) {
                         getLogger().info(`[bridge] system.init write-back skipped: session pointer moved since run start runId=${runId} sessionId=${event.session_id}`);
@@ -773,6 +921,20 @@ export class Bridge {
                     }
                     getLogger().info(`[bridge] system.init received runId=${runId} sessionId=${event.session_id} cwd=${event.cwd}`);
                 }
+                if (event.type === 'turn_started') {
+                    // app-server runner 在 turn setup 成功后补发 synthetic system.init
+                    // （§9.22 守卫前提），此处 turn_started 写回保留为双保险：两者都用
+                    // threadId 写回 sessionId（代际守卫一致），幂等。缺失会导致每次消息
+                    // 都新建线程（thread/start 而非 thread/resume），会话无法延续。
+                    const pointerMoved = this.sessionStore.getSessionEpoch(ctx.userId, agentKind) !== sessionEpochAtStart;
+                    if (!pointerMoved) {
+                        this.sessionStore.setSessionIdAndCwd(ctx.userId, agentKind, event.threadId, cwd);
+                        getLogger().info(`[bridge] turn_started session write-back runId=${runId} sessionId=${event.threadId}`);
+                    }
+                    else {
+                        getLogger().info(`[bridge] turn_started write-back skipped: session pointer moved since run start runId=${runId} sessionId=${event.threadId}`);
+                    }
+                }
                 // Track context length from compaction events
                 if (event.type === 'system' &&
                     event.subtype === 'compact_boundary' &&
@@ -786,7 +948,14 @@ export class Bridge {
                     // also guards on sessionId === undefined) from transitioning to
                     // finalizing too early. The real result for this run arrives after
                     // system.init.
-                    if (!sawInit) {
+                    //
+                    // 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(`[bridge] pre-init result ignored (resume replay) runId=${runId}`);
                         // Still reset idle timer — the CLI is alive and producing events.
                         resetIdle();
@@ -795,9 +964,24 @@ export class Bridge {
                         // layer avoids the push + render overhead for a no-op event.
                         continue;
                     }
-                    sawResult = true;
-                    resultWasError = event.subtype === 'error';
-                    getLogger().info(`[bridge] result event received runId=${runId}`);
+                    if (!preInitResult) {
+                        sawResult = true;
+                    }
+                    resultNotSuccess = event.subtype !== 'success';
+                    getLogger().info(preInitResult
+                        ? `[bridge] pre-init result from live runner (app-server setup failure) runId=${runId}`
+                        : `[bridge] result event received runId=${runId}`);
+                    // app-server 模式 setup 失败路径（thread/start 成功后 turn/start 失败）
+                    // 不会有 turn_started 事件，store 不会写回新线程 id；runner 已在 result
+                    // 里兜底上报（review P3-10）。此处仅当 runner 声明 live usage（app-server）
+                    // 且会话指针未动时写回，避免下条消息再开一个孤儿线程。其余 agent 不在
+                    // 此列（它们各自有 system.init / turn_started 写回）。
+                    if (usageAuthority === 'live' &&
+                        event.session_id &&
+                        this.sessionStore.getSessionEpoch(ctx.userId, agentKind) === sessionEpochAtStart) {
+                        this.sessionStore.setSessionIdAndCwd(ctx.userId, agentKind, event.session_id, cwd);
+                        getLogger().info(`[bridge] result session write-back runId=${runId} sessionId=${event.session_id}`);
+                    }
                     // result 后进入 finalizing 非终态（暂存 subtype/errorMsg），由 for-await
                     // 自然结束后在 finally 转 done/error。提取 usage 信息。
                     if (event.usage) {
@@ -814,6 +998,7 @@ export class Bridge {
                         // Input/Output 是本 run、Cache/Total 是 session 累计的混 scope 问题。
                         liveInputTokens = u.inputTokens;
                         liveOutputTokens = u.outputTokens;
+                        liveContextLimit = u.contextLimit;
                         if (u.cacheReadTokens !== undefined) {
                             finalCacheReadTokens = u.cacheReadTokens;
                         }
@@ -825,6 +1010,59 @@ export class Bridge {
                         }
                     }
                 }
+                // Approval events (Codex app-server mode)
+                if (event.type === 'approval_requested') {
+                    // 审批请求到达：撤回 Typing 表情再重发，让飞书重新触发提醒，把用户
+                    // 注意力拉回待审批的卡片（run 在等待人工决策，Typing 应重新闪烁）。
+                    void (async () => {
+                        try {
+                            await this.connector.removeReactionByEmoji(ctx.messageId, 'Typing');
+                        }
+                        catch (err) {
+                            getLogger().warn(`[bridge] remove Typing reaction failed runId=${runId}: ${errorMessage(err)}`);
+                        }
+                        try {
+                            await this.connector.addReaction(ctx.messageId, 'Typing');
+                        }
+                        catch (err) {
+                            getLogger().warn(`[bridge] re-add Typing reaction failed runId=${runId}: ${errorMessage(err)}`);
+                        }
+                    })();
+                    let coordinator = this.approvalCoordinators.get(runId);
+                    if (!coordinator) {
+                        coordinator = new ApprovalCoordinator({
+                            // claude 审批超时走 config（claude.approvalTimeoutMs，默认 5 分钟，
+                            // 对齐 codex 红线勿改短）；codex 维持模块常量。
+                            approvalTimeoutMs: agentKind === 'claude'
+                                ? (this.config.claude?.approvalTimeoutMs ?? APPROVAL_TIMEOUT_MS)
+                                : APPROVAL_TIMEOUT_MS,
+                            responder: async (requestId, response) => {
+                                const r = runner;
+                                if (typeof r.respondApproval === 'function') {
+                                    await r.respondApproval(requestId, response);
+                                }
+                            },
+                            interruptTurn: () => runner.stop(),
+                            pushToCard: async (events) => {
+                                for (const ev of events)
+                                    await cardSession.push(ev);
+                            },
+                        });
+                        this.approvalCoordinators.set(runId, coordinator);
+                        getLogger().info(`[bridge] 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);
+                }
                 // §9.12 红线（§P1-2 方案 A）：每个事件（含 result）无条件刷新
                 // lastEventTs 重新武装看门狗。result 后 CLI 进程做 jsonl flush/清理（finalizing
                 // 过渡）期间，宽限期恢复为完整的 idleTimeoutMs，避免已产出结果的 turn 被误标
@@ -846,28 +1084,24 @@ export class Bridge {
             // 立即 exit=1), 此时 jsonl 里是上一次成功 turn 的历史 usage, 会被误当作本次 usage 显示,
             // 误导用户以为本次出错的请求也消耗了 token。error 时只用 live 捕获的 usage (若有)。
             const finalSessionId = this.sessionStore.getSessionId(ctx.userId, agentKind);
-            const finalUsage = resultWasError
+            const finalUsage = resultNotSuccess
                 ? undefined
                 : this.resolveFinalUsage(finalSessionId, cwd, agentKind);
             finalContextLength = finalUsage?.contextLength ?? contextLength;
-            finalContextLimit = finalUsage?.contextLimit;
+            finalContextLimit = finalUsage?.contextLimit ?? liveContextLimit;
             finalCompactCount = finalUsage?.compactCount;
             finalCumulativeTotalTokens = finalUsage?.cumulativeTotalTokens;
             finalCumulativeInputTokens = finalUsage?.cumulativeInputTokens;
             finalCumulativeOutputTokens = finalUsage?.cumulativeOutputTokens;
             finalCumulativeCacheReadTokens = finalUsage?.cumulativeCacheReadTokens;
             finalCumulativeCacheCreationTokens = finalUsage?.cumulativeCacheCreationTokens;
-            // 统一 flow 字段 scope：live 优先（非 codex），jsonl 兜底；codex 例外。
+            // 统一 flow 字段 scope：live 优先，jsonl 兜底。
             // 当 live result 事件带了 input/output（即 liveInputTokens/liveOutputTokens
             // 非 undefined），所有 flow 字段统一用 live scope（本 run），不用 jsonl
             // 的 session 累计值覆盖，避免 cache%/Total 分子分母不同源。
             // 无 live usage 时（如 kimi），jsonl 值兜底。
-            // codex 例外（2026-08-01）：codex exec 的 turn.completed.usage 是会话累计
-            // total_token_usage（resume 长会话下虚高数百倍），不是本 run 增量——live
-            // 值必须被忽略，flow 字段一律取 jsonl 主线程文件的 per-turn 值；
-            // jsonl 缺失（老版本无 token_count）时才回退 live。
             // contextLength/compactCount 保持 jsonl 优先（它们是水位/历史计数）。
-            const codexJsonlFirst = agentKind === 'codex';
+            const codexJsonlFirst = usageAuthority === 'jsonl';
             if (!codexJsonlFirst && liveInputTokens !== undefined && liveOutputTokens !== undefined) {
                 // 非 codex 且 live 有 input/output → 所有 flow 字段用 live scope
                 finalInputTokens = liveInputTokens;
@@ -892,9 +1126,13 @@ export class Bridge {
             // 3) 已终态 + sawResult -> 补充 usage meta（不改 terminal）
             const finalState = cardSession.currentState;
             if (finalState.terminal === 'finalizing') {
-                const isError = finalState.resultSubtype === 'error' || !!finalState.errorMsg;
-                await cardSession.finish(isError ? 'error' : 'done', {
-                    resultSubtype: finalState.resultSubtype,
+                // 三态终态映射（2026-08-14）：interrupted（审批超时/取消、/stop）是独立
+                // 终态，不再归因于 Agent 错误；error 保持「运行出错」；其余为 done。
+                const subtype = finalState.resultSubtype;
+                const isError = subtype === 'error' || !!finalState.errorMsg;
+                const terminal = isError ? 'error' : subtype === 'interrupted' ? 'interrupted' : 'done';
+                await cardSession.finish(terminal, {
+                    resultSubtype: subtype,
                     errorMsg: finalState.errorMsg,
                     contextLength: finalContextLength,
                     contextLimit: finalContextLimit,
@@ -1003,6 +1241,11 @@ export class Bridge {
         finally {
             if (idleInterval)
                 clearInterval(idleInterval);
+            const coordinator = this.approvalCoordinators.get(runId);
+            if (coordinator) {
+                coordinator.onTurnEnded();
+                this.approvalCoordinators.delete(runId);
+            }
         }
     }
     /**
@@ -1047,14 +1290,39 @@ export class Bridge {
             // (every later message busy-dropped until a manual /stop).
             if (this.activeRuns.get(cwd) === activeRun) {
                 this.activeRuns.delete(cwd);
-                // Also clean up the runner to prevent memory leak
-                // Fix 4: Clean up this specific (cwd, agentKind) runner slot.
-                // (P1-1: eviction must also unregister the runner from the exit dispatcher)
-                // P2-3: evict by the run's captured agentKind, not the live
-                // defaultAgent — switching agent mid-run (via /config, whose
-                // clearRunners skips the active cwd) would otherwise delete the new
-                // agent's slot (no-op) and leave the original runner lingering.
-                this.evictRunnerSlot(cwd, activeRun.agentKind);
+                // Workspace-lifetime runners (codex app-server) keep their persistent
+                // connection across runs: evicting here would kill the connection after
+                // EVERY run, defeating lifetime='workspace' + idle TTL. They are still
+                // evicted+disposed by clearRunners (/config) and interruptCurrentRun
+                // (/stop). Spawn-per-message runners are evicted as before to prevent
+                // stale process references accumulating.
+                if (activeRun.runner.lifetime !== 'workspace') {
+                    this.evictRunnerSlot(cwd, activeRun.agentKind);
+                }
+                // Compact 卡片需要 runId + sessionId；record 供终态卡上的 Compact 按钮
+                // 校验与取参（activeRuns 已清空，无法再查到）。异常退出（error/
+                // interrupted/idle_timeout）同样记录——上下文往往更大，压缩后再续。
+                // §6.2-3：写入条件从「codex 终态」放宽为「runner 有 runCompact 的终态」
+                // （codex app-server + kimi acp 均满足）。
+                const runTerminal = cardSession.currentState.terminal;
+                const runnerHasCompact = 'runCompact' in activeRun.runner &&
+                    typeof activeRun.runner.runCompact === 'function';
+                if (runnerHasCompact &&
+                    activeRun.runner.lifetime === 'workspace' &&
+                    (runTerminal === 'done' ||
+                        runTerminal === 'error' ||
+                        runTerminal === 'interrupted' ||
+                        runTerminal === 'idle_timeout')) {
+                    const compactSessionId = cardSession.currentState.sessionId ??
+                        this.sessionStore.getSessionId(ctx.userId, activeRun.agentKind);
+                    if (compactSessionId) {
+                        this.lastCompactableCodexRun.set(cwd, {
+                            runId: activeRun.runId,
+                            sessionId: compactSessionId,
+                            agentKind: activeRun.agentKind,
+                        });
+                    }
+                }
                 getLogger().info(`[bridge] activeRuns.delete cwd=${cwd} runId=${runId}`);
             }
         }
@@ -1081,6 +1349,7 @@ export class Bridge {
                     contextLength: content.usage.contextLength,
                     contextLimit: content.usage.contextLimit,
                     compactCount: content.usage.compactCount,
+                    compactPreContextLength: content.usage.compactPreContextLength,
                     cacheReadTokens: content.usage.cacheReadTokens,
                     cacheCreationTokens: content.usage.cacheCreationTokens,
                     totalTokens: content.usage.totalTokens,
@@ -1114,42 +1383,19 @@ export class Bridge {
                 maxEvents: COMPLETION_NOTIFICATION_MAX_EVENTS,
             });
             const { events, usage } = content;
-            const elements = [
-                markdownDiv(`📂 \`${cwd}\`\n会话: **${sessionId}**`),
-                { tag: 'hr' },
-            ];
-            // Add session content in collapsible panels (last 2 expanded)
-            events.forEach((ev, i) => {
-                elements.push(sessionEventPanel(ev, i, events.length, 2, agentKind));
-            });
-            // Add usage stats at the end
-            const usageStatsStr = formatUsageStats(usage, { showResult: true, result: 'completed' });
-            if (usage) {
-                elements.push(markdownDiv(usageStatsStr));
-            }
-            // Add action button to resume this session - use column_set+column for 2.0
-            elements.push({
-                tag: 'column_set',
-                columns: [
-                    {
-                        tag: 'column',
-                        width: 'auto',
-                        elements: [resumeUseButton(sessionId, agentKind)],
-                    },
-                ],
+            const card = buildSessionHistoryCard({
+                sessionId,
+                cwd,
+                events,
+                usage,
+            }, {
+                agentKind,
+                headerText: `📂 \`${cwd}\`\n会话: **${sessionId}**`,
+                title: '✅ 会话已完成',
+                usageResult: 'completed',
+                actions: [resumeUseButton(sessionId, agentKind)],
+                headerTemplate: 'green',
             });
-            const card = {
-                schema: '2.0',
-                config: { wide_screen_mode: true },
-                header: {
-                    template: 'green',
-                    title: {
-                        tag: 'plain_text',
-                        content: '✅ 会话已完成',
-                    },
-                },
-                body: { elements },
-            };
             // P1-21: send through sendResult so enforceCardBudget guards the card
             // (previously sent via connector directly, bypassing the budget — long
             // sessions produced >28KB cards that Feishu silently rejected).
@@ -1165,6 +1411,264 @@ export class Bridge {
             getLogger().warn(`[bridge] failed to send completion notification card:`, err);
         }
     }
+    // =============================================================================
+    // 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) {
+            // P2-7: run 已结束（coordinator 已释放）时点击审批按钮必须给用户明确反馈，
+            // 不能静默。router 会把该异常转成 error toast。
+            getLogger().warn(`[bridge] 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.
+     */
+    async handleApprovalRespond(opts) {
+        const log = getLogger();
+        log.info(`[bridge] 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 });
+        });
+    }
+    /**
+     * Handle a permission toggle from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    async handleApprovalToggle(opts) {
+        const log = getLogger();
+        log.info(`[bridge] 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 });
+        });
+    }
+    /**
+     * Claude AskUserQuestion 选项点击（单选即时提交 / 多选切换勾选）。
+     * 路由到 ApprovalCoordinator.toggleAnswer。
+     */
+    async handleApprovalAnswer(opts) {
+        const log = getLogger();
+        log.info(`[bridge] handleApprovalAnswer runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
+        return this.withCoordinator(opts.runId, (coordinator) => coordinator.toggleAnswer({ questionIndex: opts.questionIndex, option: opts.option }, { requestId: opts.requestId, nonce: opts.nonce }));
+    }
+    /**
+     * Claude AskUserQuestion 多选问题的「提交答案」按钮。
+     * 路由到 ApprovalCoordinator.submitAnswers。
+     */
+    async handleApprovalAnswerSubmit(opts) {
+        const log = getLogger();
+        log.info(`[bridge] handleApprovalAnswerSubmit runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
+        return this.withCoordinator(opts.runId, (coordinator) => coordinator.submitAnswers({ questionIndex: opts.questionIndex }, { requestId: opts.requestId, nonce: opts.nonce }));
+    }
+    /**
+     * Claude AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接
+     * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
+     */
+    async handleApprovalAnswerCustom(opts) {
+        const log = getLogger();
+        log.info(`[bridge] handleApprovalAnswerCustom runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
+        return this.withCoordinator(opts.runId, (coordinator) => coordinator.answerCustom({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
+    }
+    /**
+     * Handle codex.compact card action — trigger a Codex compaction request.
+     * Validates the run exists and is in a terminal state, then calls
+     * the app-server runner's runCompact().
+     */
+    async handleCodexCompact(value, ctx) {
+        const log = getLogger();
+        log.info(`[bridge] handleCodexCompact userId=${ctx.userId} runId=${value.runId?.slice(0, 8)}...`);
+        const { runId } = value;
+        if (!runId) {
+            await this.sendResult({ text: '⚠️ 无效的 Compact 请求，缺少 runId' }, ctx);
+            return;
+        }
+        const cwd = this.resolveCwd(ctx.userId);
+        if (!cwd) {
+            await this.sendResult({ text: '⚠️ 未设置工作目录' }, ctx);
+            return;
+        }
+        // 校验：run 结束后 activeRuns 已清空，用 lastCompactableCodexRun 对照 runId。
+        const last = this.lastCompactableCodexRun.get(cwd);
+        if (!last || last.runId !== runId) {
+            await this.sendResult({ text: '⚠️ 该任务已结束或不属于当前会话' }, ctx);
+            return;
+        }
+        if (!last.sessionId) {
+            await this.sendResult({ text: '⚠️ 未找到可压缩的会话' }, ctx);
+            return;
+        }
+        // Check that the runner has runCompact method
+        const runner = this.getRunner(cwd, last.agentKind);
+        if (!('runCompact' in runner) ||
+            typeof runner.runCompact !== 'function') {
+            await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
+            return;
+        }
+        log.info(`[bridge] handleCodexCompact executing runCompact for runId=${runId} cwd=${cwd}`);
+        await this.streamCodexCompact({
+            sessionId: last.sessionId,
+            cwd,
+            agentKind: last.agentKind,
+            runner,
+            ctx,
+        });
+    }
+    /**
+     * Stream a Codex compaction to a card: start a RunCardSession with
+     * operationKind='compaction' (no recursive Compact button), consume
+     * runner.runCompact() events, read authoritative jsonl usage, and finish
+     * the card. Shared by handleCodexCompact (run card button) and
+     * handleResumeCompact (resume cards) so both flows stay in sync.
+     *
+     * Precondition: callers have already validated that `runner` implements
+     * runCompact and that the session exists in `cwd`.
+     */
+    async streamCodexCompact(opts) {
+        const log = getLogger();
+        const { sessionId, cwd, agentKind, runner, ctx } = opts;
+        log.info(`[bridge] streamCodexCompact sessionId=${sessionId} cwd=${cwd}`);
+        // 防御性能力检查：调用方已校验（runId / resume 两条路径），此处双保险并
+        // 让 TS 收窄 runner 类型（'runCompact' in runner 之后的 cast 才合法）。
+        if (!('runCompact' in runner) ||
+            typeof runner.runCompact !== 'function') {
+            await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
+            return;
+        }
+        await this.sendResult({ text: '🗜 Compact 已触发，正在压缩会话…' }, ctx);
+        const compactRunId = randomUUID();
+        const cardSession = new RunCardSession({
+            connector: this.connector,
+            chatId: ctx.chatId,
+            replyTo: ctx.messageId,
+            runId: compactRunId,
+            renderOptions: {
+                showThinking: this.config.output.showThinking,
+                showToolUse: this.config.output.showToolUse,
+                showToolResult: this.config.output.showToolResult,
+                agentKind,
+            },
+        });
+        try {
+            await cardSession.start();
+            // operationKind=compaction：卡片不渲染 Compact 按钮（防递归 Compact）。
+            await cardSession.push({
+                type: 'turn_started',
+                threadId: sessionId,
+                turnId: '',
+                operationKind: 'compaction',
+            });
+            let sawResult = false;
+            for await (const event of runner.runCompact('', { cwd, sessionId })) {
+                if (event.type === 'result')
+                    sawResult = true;
+                await cardSession.push(event);
+            }
+            // 压缩结束后从会话 jsonl 读权威统计（压缩后上下文、压缩次数、本次压缩
+            // token 消耗与会话累计）。thread/compacted 通知与 jsonl 落盘几乎同时
+            // （实测差 ~9ms），compactCount 未读到则短重试，仍失败优雅降级（无统计）。
+            let finalUsage = this.resolveFinalUsage(sessionId, cwd, agentKind);
+            for (let attempt = 0; !finalUsage?.compactCount && attempt < 2; attempt++) {
+                await sleep(150);
+                finalUsage = this.resolveFinalUsage(sessionId, cwd, agentKind);
+            }
+            await cardSession.finish(sawResult ? 'done' : 'error', {
+                resultSubtype: sawResult ? 'success' : 'error',
+                errorMsg: sawResult ? 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,
+            });
+            log.info(`[bridge] streamCodexCompact finished sessionId=${sessionId} sawResult=${sawResult}`);
+        }
+        catch (err) {
+            log.error(`[bridge] streamCodexCompact failed: ${errorMessage(err)}`);
+            await cardSession.finish('error', { errorMsg: errorMessage(err) });
+        }
+    }
+    /**
+     * Handle resume.compact card action — compact a session directly from a
+     * resume card (auto-resume / `/resume <id>`), without a runId.
+     *
+     * Unlike handleCodexCompact (which validates against the last finished run's
+     * runId), the resume card carries the sessionId + agent it was rendered for.
+     * Validation: the session must exist in the current cwd (same rule as
+     * cmdResume / resume.use) and the runner must implement runCompact.
+     */
+    async handleResumeCompact(value, ctx) {
+        const log = getLogger();
+        log.info(`[bridge] handleResumeCompact userId=${ctx.userId} sessionId=${value.sessionId?.slice(0, 16)} agent=${value.agent ?? 'default'}`);
+        const { sessionId } = value;
+        if (!sessionId) {
+            await this.sendResult({ text: '⚠️ 无效的 Compact 请求，缺少 sessionId' }, ctx);
+            return;
+        }
+        const cwd = this.resolveCwd(ctx.userId);
+        if (!cwd) {
+            await this.sendResult({ text: '⚠️ 未设置工作目录' }, ctx);
+            return;
+        }
+        // Resolve agent kind the same way resume.use does: card value wins,
+        // otherwise fall back to defaultAgent.
+        const validAgents = ['claude', 'codex', 'opencode', 'pi', 'kimi'];
+        const agentKind = value.agent && validAgents.includes(value.agent)
+            ? value.agent
+            : this.config.defaultAgent;
+        // Session must exist in the current cwd (same rule as cmdResume /
+        // resume.use): reject ghosts so a stale card cannot compact a session
+        // from another cwd. Read failures get visible feedback (card click
+        // 红线：不许静默失败)。
+        let content;
+        try {
+            content = this.sessionReaderRegistry.get(agentKind).readSessionContent(sessionId, cwd);
+        }
+        catch (err) {
+            await this.sendResult({ text: `⚠️ 读取 session ${sessionId} 失败: ${errorMessage(err)}` }, ctx);
+            return;
+        }
+        if (content.events.length === 0 &&
+            !content.usage &&
+            !content.aiTitle &&
+            !content.recap &&
+            !content.displayTitle) {
+            await this.sendResult({ text: `⚠️ 未找到 session ${sessionId}（当前目录: ${cwd}）` }, ctx);
+            return;
+        }
+        // Check that the runner has runCompact (codex app-server only).
+        const runner = this.getRunner(cwd, agentKind);
+        if (!('runCompact' in runner) ||
+            typeof runner.runCompact !== 'function') {
+            await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
+            return;
+        }
+        log.info(`[bridge] handleResumeCompact executing runCompact sessionId=${sessionId} cwd=${cwd}`);
+        await this.streamCodexCompact({ sessionId, cwd, agentKind, runner, ctx });
+    }
     /**
      * Execute a bash command and stream output to a card.
      * `!` commands bypass the serial queue entirely (see body comment + §9.6):