lark-remote 0.5.19 → 0.5.21

package/dist/bridge/index.js

@@ -1,22 +1,19 @@
 import { randomUUID } from 'node:crypto';
-import { sleep } from '../common/sleep.js';
 import { isContentFilterFailure } from '../common/turn-failure.js';
 import { resolveFinalUsage, errorMessage } from './final-usage.js';
 import { getLogger } from '../logger/index.js';
 import { RunCardSession } from '../card/run-card-session.js';
-import { renderRunCard, renderRunCardDetailed, } from '../card/run-renderer.js';
+import { renderRunCardDetailed } from '../card/run-renderer.js';
 import { writeFinalAnswerFile, finalAnswerFileFailureCard } from '../card/final-answer-file.js';
 import { bestEffortUnlink } from '../common/fs.js';
-import { renderBashCard } from '../card/bash-renderer.js';
-import { BashCardSession, capBashOutput } from '../card/bash-card-session.js';
-import { isLiveBackgroundJob, isRunActive, isRunTerminal, markBackgroundJobsUnknown, removeBackgroundJob, syncBackgroundJobs, } from '../card/run-state.js';
+import { isRunActive, isRunTerminal } 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 } from '../agent-kinds.js';
-import { supportsCompact } from '../runner/types.js';
+import { CompactLifecycle, runnerSupportsCompact, terminalReactionEmoji } from './compact.js';
+import { JobWatchLifecycle } from './job-watch.js';
+import { BashRunLifecycle } from './bash-run.js';
 import { QueueManager, } from './queue-manager.js';
 import { ApprovalActions } from './approval-actions.js';
 import { createRunApprovalCoordinator, remindPendingApproval } from './run-approval.js';
@@ -42,21 +39,6 @@ const MAX_CACHED_RUNNER_WORKSPACES = 10;
  * message forever.
  */
 const IDLE_TIMEOUT_MS = 15 * 60 * 1000;
-/**
- * Emoji reaction per run terminal state, so a glance at the user's original
- * message distinguishes how the run ended. Unknown/non-terminal states fall
- * back to 'Done' (default).
- */
-const TERMINAL_REACTION_EMOJI = {
-    error: 'ERROR',
-    idle_timeout: 'Alarm',
-    interrupted: 'SHHH',
-    // 本轮结束但目标继续：任务还没完，不能打 ✓（Done）。
-    goal_continuing: 'OnIt',
-};
-function terminalReactionEmoji(terminal) {
-    return TERMINAL_REACTION_EMOJI[terminal] ?? 'Done';
-}
 /**
  * 完成通知卡的标题 / 配色 / 结果行。
  *
@@ -81,40 +63,36 @@ function completionNotificationPresentation(terminal) {
             return { title: '✅ 会话已完成', template: 'green', result: 'completed' };
     }
 }
-/**
- * 单点化：`'runCompact' in runner` 鸭子探测
- * codex app-server + kimi/opencode ACP runner 满足。
- */
-function runnerHasRunCompact(runner) {
-    return ('runCompact' in runner && typeof runner.runCompact === 'function');
+// --- 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;
 }
-/**
- * 已告警过的能力不一致 kind。能力表（`COMPACT_CAPABILITY`）是声明，runner 方法
- * 是实现；两者不一致是开发期缺陷，只在首次冲突时打 error，避免每次渲染刷屏。
- */
-const compactMismatchWarned = new Set();
-/**
- * Compact 能力的双重门控：声明的能力表 && runner 实际实现。
- *
- * 只做鸭子探测会把「漏实现」降级成静默隐藏按钮（dsh 就这样漏了），所以声明表
- * 是必需项；只信声明表则可能渲染出点不动的死按钮，所以实现检查也保留。两者
- * 不一致时打 error 日志，让缺陷在运行日志里可见。
- */
-function runnerSupportsCompact(runner, kind) {
-    const declared = supportsCompact(kind);
-    const implemented = runnerHasRunCompact(runner);
-    if (declared !== implemented && !compactMismatchWarned.has(kind)) {
-        compactMismatchWarned.add(kind);
-        getLogger().error(`[lark-remote] compact capability mismatch kind=${kind} declared=${declared} implemented=${implemented}`);
-    }
-    return declared && implemented;
+/** 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;
 }
-/**
- * 每个 cwd 保留的「可压缩 run」条数上限。Compact 按钮挂在终态 run 卡片上，
- * 卡片会被后续消息不断顶上去；无上限会让长跑进程随 run 数无界增长，而用户
- * 实际能点到的只有最近几张卡，20 条足以覆盖。
- */
-const MAX_COMPACTABLE_RUNS_PER_CWD = 20;
 /**
  * Bridge owns the per-workspace serial processing queue (§9.6) and the
  * single-card streaming forwarding loop (§9.12 watchdog + session sync).
@@ -149,7 +127,7 @@ export class Bridge {
     mediaHandler;
     /**
      * Per-workspace runner instances, keyed by (cwd, agentKind).
-     * Fix 4 (2026-07-18): Each agentKind has its own cache slot, so switching
+     * Each agentKind has its own cache slot, so switching
      * defaultAgent creates a NEW runner without evicting the old one. This
      * eliminates the need for clearRunners() on agent switch, preventing the
      * regression where clearRunners() orphaned a running subprocess and
@@ -175,16 +153,11 @@ export class Bridge {
         coordinatorFor: (runId) => this.approvalCoordinators.get(runId),
     });
     /**
-     * 最近若干次已完成的、runner 有 runCompact 的 run（cwd → runId → 记录）。
-     * run 结束后 activeRuns 已清空，而终态卡上的 Compact 按钮只带 runId，
-     * 需要它反查 sessionId + agentKind。
-     *
-     * 为什么按 runId 存而不是「每 cwd 只留最新一条」：compact 卡片动作走串行
-     * 队列（会被正在跑的 run 挡住），点击到执行之间可能夹着别的 run 收尾。
-     * 单槽会被覆盖 —— 旧卡片的压缩必然报「该任务已结束或不属于当前会话」，
-     * 与 session 是否还在、能否压缩无关（2026-10-08 线上缺陷）。
+     * Compact 生命周期（见 compact.ts）：可压缩 run 记账、终态卡 / resume 卡
+     * 两条 Compact 入口、kimi 在途检测与压缩流式卡。activeRuns 槽位表按引用
+     * 共用——压缩注册前确认槽位空闲，否则 /stop 停错对象。
      */
-    compactableRuns = new Map();
+    compact;
     /**
      * 终态卡片的渲染快照（runId → state + options）：run 结束后 activeRuns 已
      * 清空，而卡片上的「⏹ 停止」后台任务按钮（job.kill）还活着，需要按 runId
@@ -195,26 +168,17 @@ export class Bridge {
     runCardSnapshots = new Map();
     static RUN_CARD_SNAPSHOT_MAX = 8;
     /**
-     * 终态卡后台任务订阅（runId → 中止句柄）。
-     *
-     * 与卡片快照同生命周期：快照被淘汰、任务全结束、patch 失败时退订。上限天然
-     * 受 RUN_CARD_SNAPSHOT_MAX 约束（一张卡最多一条流）。
+     * 终态卡后台任务订阅与停止（见 job-watch.ts）：job.kill、名单订阅与
+     * PATCH 串行链收在该模块；jobCardPatches 链内渲染读 snapshot.state，
+     * 「停止」与「订阅帧」并发不会把卡片写回旧内容。
      */
-    jobWatches = new Map();
+    jobWatch;
     /**
-     * 同一张卡的 patch 串行链（runId → 链尾）。
-     *
-     * 「停止按钮」和「订阅帧」都会改同一张终态卡：不串行化时两条 PATCH 并发，
-     * 后发先至的那条会把卡片写回旧内容（任务又变回「运行中」）。
-     */
-    jobCardPatches = 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
-     * cwd, so they live outside `activeRuns`. Tracked so `/stop` can reach
-     * the per-run BashRunner instance via interruptCurrentRun.
+     * `!` bash 命令执行（见 bash-run.ts）：独立 runId 空间、独立登记表，不进
+     * activeRuns；绝不 re-chain 到 QueueManager（会自等待死锁）。/stop 的 bash
+     * 侧匹配与中断也收在该模块，避免误杀并行跑的 `!` 任务。
      */
-    activeBashRuns = new Map();
+    bashRuns;
     constructor(deps) {
         this.connector = deps.connector;
         this.sessionStore = deps.sessionStore;
@@ -228,11 +192,36 @@ export class Bridge {
             resolveCwd: (userId) => this.resolveCwd(userId),
             getConfig: () => this.config,
         });
+        this.compact = new CompactLifecycle({
+            activeRuns: this.activeRuns,
+            connector: this.connector,
+            sessionStore: this.sessionStore,
+            sessionReaderRegistry: this.sessionReaderRegistry,
+            getConfig: () => this.config,
+            getRunner: (cwd, kind, opts) => this.getRunner(cwd, kind, opts),
+            sendResult: (result, ctx, opts) => this.sendResult(result, ctx, opts),
+            startIdleWatchdog: (opts) => this.startIdleWatchdog(opts),
+            finishTurnReactions: (ctx, emoji) => this.finishTurnReactions(ctx, emoji),
+            resolveCwd: (userId) => this.resolveCwd(userId),
+        });
+        this.jobWatch = new JobWatchLifecycle({
+            getRunner: (cwd, kind) => this.getRunner(cwd, kind),
+            getRunCardSnapshot: (runId) => this.runCardSnapshots.get(runId),
+            updateCardInPlace: (card, ctx) => this.updateCardInPlace(card, ctx),
+            patchCard: (messageId, card) => this.patchCard(messageId, card),
+        });
+        this.bashRuns = new BashRunLifecycle({
+            connector: this.connector,
+            sessionStore: this.sessionStore,
+            resolveCwd: (userId) => this.resolveCwd(userId),
+            sendResult: (result, ctx) => this.sendResult(result, ctx),
+            finishTurnReactions: (ctx, emoji) => this.finishTurnReactions(ctx, emoji),
+        });
     }
     /**
      * Get or create a runner for the given cwd, keyed by current defaultAgent.
      *
-     * Fix 4 (2026-07-18): Cache key includes agentKind, so switching defaultAgent
+     * Cache key includes agentKind, so switching defaultAgent
      * creates a NEW runner under a different key without evicting the old one.
      * This eliminates the need for clearRunners() on agent switch.
      */
@@ -317,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) {
@@ -379,9 +337,9 @@ export class Bridge {
      */
     clearRunners() {
         // Skip workspaces with an active run: evicting their runner would orphan
-        // the instance that owns the live subprocess (regression 2026-07-18 -- the
-        // running runner became unreachable, stop() hit a fresh empty runner, the
-        // real subprocess was never killed and the queue chain blocked forever).
+        // the instance that owns the live subprocess — the running runner would
+        // become unreachable, stop() would hit a fresh empty runner, the real
+        // subprocess would never be killed and the queue chain would block forever.
         // The running run already started with its (possibly now-stale) config, so
         // keeping it is correct; finalizeRun deletes the cache entry when the run
         // ends, and the next run picks up the new config/agent via getRunner.
@@ -645,25 +603,7 @@ export class Bridge {
     }
     /** Get all active bash runs with their state for /active command. */
     getActiveBashRuns() {
-        const result = [];
-        for (const [runId, bashRun] of this.activeBashRuns) {
-            const state = bashRun.cardSession.currentState;
-            // Only include non-terminal runs (bash has no finalizing state)
-            if (state.terminal === 'running') {
-                result.push({
-                    runId,
-                    cwd: bashRun.cwd,
-                    userId: bashRun.userId,
-                    chatId: bashRun.chatId,
-                    terminal: state.terminal,
-                    command: bashRun.command,
-                });
-            }
-        }
-        return result;
-    }
-    async interruptCurrentRun(input) {
-        return (await this.interruptCurrentRunDetailed(input)).stopped;
+        return this.bashRuns.getActiveBashRuns();
     }
     /**
      * Same as {@link interruptCurrentRun}, plus what the runner's stop actually
@@ -719,45 +659,11 @@ export class Bridge {
                 stop = stopResult;
             }
         }
-        // Then check active bash runs (! commands). These bypass the serial queue
-        // and are tracked separately; stop the per-run BashRunner directly.
-        // `/stop`（无 runId、无 cwd）语义是「停掉这个会话的一切」，所以并行跑的
-        // `!` 命令也要停——旧实现命中 claude run 就 return，这些 bash 会被漏掉。
-        // 带范围的中断（停止卡 runId、queue.immediate 的 cwd）保持旧语义：只有
-        // 没有 claude run 命中时才回退到 bash，避免误杀用户并行跑的 `!` 任务。
-        const cardScoped = input.runId !== undefined || input.cardMessageId !== undefined;
-        const includeBashRuns = (input.runId === undefined && input.cardMessageId === undefined && input.cwd === undefined) ||
-            activeTargets.length === 0;
-        const bashTargets = includeBashRuns
-            ? [...this.activeBashRuns.entries()].filter(([runId, b]) => {
-                if (input.cwd !== undefined && b.cwd !== input.cwd)
-                    return false;
-                if (b.userId !== input.userId || b.chatId !== input.chatId)
-                    return false;
-                if (input.runId) {
-                    if (runId === input.runId)
-                        return true;
-                    // Scoped card clicks may fall back only through their own card id.
-                    if (cardScoped)
-                        return false;
-                }
-                if (input.cardMessageId) {
-                    return b.cardSession.cardMessageId === input.cardMessageId;
-                }
-                return true;
-            })
-            : [];
-        for (const [runId, b] of bashTargets) {
-            getLogger().info(`[lark-remote] interrupt hit bash runId=${runId} cwd=${b.cwd} userId=${input.userId}`);
-            await b.bashRunner.stop({ immediate: true });
-            // Update card to show interrupted state. exitCode 不传（保持 null）：
-            // bash-renderer 的「已手动终止」文案要求 exitCode === null；传 -1 会让
-            // 该分支不可达，中断卡退化成「退出码: -1」的失败样式。
-            await b.cardSession.finish('interrupted');
-            this.activeBashRuns.delete(runId);
-            getLogger().info(`[lark-remote] interrupt bash stop done runId=${runId}`);
-            stoppedCount++;
-        }
+        // Then check active bash runs (! commands). 实现在 bash-run.ts
+        // （bridge 结构治理第 3 刀）：bash 用独立 runId 空间、独立登记表，匹配
+        // 与停止整体收在 stopMatchingBashRuns 里——`/stop` 语义与「不误杀并行
+        // `!` 任务」的守卫注释随迁。
+        stoppedCount += await this.bashRuns.stopMatchingBashRuns(input, activeTargets.length);
         if (stoppedCount === 0) {
             getLogger().warn(`[lark-remote] interrupt miss userId=${input.userId} ` +
                 `requestedRunId=${input.runId ?? '(none)'} ` +
@@ -804,8 +710,8 @@ export class Bridge {
         // Stop the EXACT runner instance that is running (carried by activeRun),
         // not whatever getRunner(cwd) would return now. clearRunners() may have
         // emptied the cache mid-run, in which case getRunner creates a fresh empty
-        // runner whose stop() is a no-op and the real subprocess is never killed
-        // (regression 2026-07-18: queue chain blocked forever).
+        // runner whose stop() is a no-op and the real subprocess is never killed,
+        // blocking the queue chain forever.
         const runner = active.runner;
         // Bind the queue reset to THIS task's execution slot: the stop window
         // below may outlive the task's settle, letting the serial chain advance
@@ -813,18 +719,28 @@ export class Bridge {
         // unconditional reset would then zero the successor's count and mark
         // its slot interrupted, hiding it from queue cards.
         const stoppedSlot = this.queueManager.getExecutingSlot(cwd);
-        const [, stopResult] = await Promise.allSettled([
+        const [finishResult, stopResult] = await Promise.allSettled([
             // 用户主动中断（/stop、stop 卡按钮、queue.immediate）显式打标
             // interruptedReason，与审批超时自动取消（approval_timeout）、审批
             // 卡取消（approval_cancelled）在终态数据上可区分（方案 A）。
             active.session.finish('interrupted', { interruptedReason: 'user_stop' }),
             runner.stop({ immediate: true }),
         ]);
-        const stop = stopResult.status === 'fulfilled' &&
-            stopResult.value !== null &&
-            typeof stopResult.value === 'object'
-            ? stopResult.value
-            : undefined;
+        // allSettled 的两个结果都必须检查：finish 被飞书拒绝时卡片会永久停在
+        // 「运行中」；runner.stop 失败时进程可能没死而槽位已被释放——两者都
+        // 不能静默吞掉（此前第一个结果整体丢弃、stop 失败仍记 "stop done"）。
+        if (finishResult.status === 'rejected') {
+            getLogger().error(`[lark-remote] stop: terminal card finish failed runId=${active.runId}:`, finishResult.reason);
+        }
+        let stop;
+        if (stopResult.status === 'rejected') {
+            getLogger().error(`[lark-remote] stop: runner.stop failed runId=${active.runId} — 运行可能未终止:`, stopResult.reason);
+            // 上报「可能仍在跑」，调用方按 unconfirmed 口径聚合（不承诺已停止）。
+            stop = { status: 'unconfirmed', detail: errorMessage(stopResult.reason) };
+        }
+        else {
+            stop = stopResult.value ?? undefined;
+        }
         // The chain may have advanced while the stop was in flight: a new run
         // (from a task that began during the stop window) may now occupy this
         // cwd. Only delete the entry we actually stopped.
@@ -840,8 +756,8 @@ export class Bridge {
         // interruptCurrentRun 的 await 窗口内 queue 链会推进下一条消息，其
         // getRunner 可能刚拿走本实例（缓存命中先于本行执行）——立即 evict 会
         // 让那个 run 的长驻连接脱管：进程残留至 idle TTL 才回收，期间持有
-        // agent 侧会话写锁（codex "thread already has an active writer"，
-        // 线上实测）。改为标 stale：下一次「即将开跑」的 getRunner 在槽位空闲时
+        // agent 侧会话写锁（codex "thread already has an active writer"）。
+        // 改为标 stale：下一次「即将开跑」的 getRunner 在槽位空闲时
         // 换新实例（见 getRunner 的 replaceStale），本次 run 的 finalize 收尾时
         // 也会消费该标记；两者都保证不会有活跃 run 使用被 dispose 的实例。
         // run-per-message runner 无长驻连接，保持立即 evict 不变。
@@ -863,7 +779,9 @@ export class Bridge {
         if (stoppedSlot !== undefined) {
             this.queueManager.resetExecutingCount(cwd, stoppedSlot);
         }
-        getLogger().info(`[lark-remote] interrupt stop done runId=${active.runId}`);
+        if (stop?.status !== 'unconfirmed') {
+            getLogger().info(`[lark-remote] interrupt stop done runId=${active.runId}`);
+        }
         return stop;
     }
     /**
@@ -914,25 +832,22 @@ export class Bridge {
     /**
      * Deliver a final answer that cannot fit in the run card as a Markdown file
      * attachment. 卡片正文已被标记替代，文件是唯一的内容通道；此处绝不发纯文本
-     * （2026-11-02 定规：纯文本与卡片重复，也丢 Markdown 结构）。
+     * （纯文本与卡片重复，也丢 Markdown 结构）。
      *
-     * 失败时发一张提示卡（不是纯文本），并把完整回答留在临时文件里记日志，
-     * 便于事后找回。
+     * 发送成功即清理临时文件；失败时发一张提示卡（不是纯文本），完整回答
+     * 留在临时文件里（路径见错误日志），便于事后找回。
      */
     async sendFinalAnswerFile(text, ctx) {
         let filePath;
         try {
             filePath = writeFinalAnswerFile(text);
             await this.connector.sendFile(ctx.chatId, filePath);
+            bestEffortUnlink(filePath);
         }
         catch (err) {
             getLogger().error(`[lark-remote] failed to deliver complete final answer as file (kept at ${filePath ?? 'not written'}):`, err);
             await this.sendResult({ card: finalAnswerFileFailureCard(errorMessage(err)) }, ctx);
         }
-        finally {
-            if (filePath)
-                bestEffortUnlink(filePath);
-        }
     }
     /**
      * Update an existing card in place (原地更新) instead of sending a new one.
@@ -1005,138 +920,23 @@ export class Bridge {
         this.runCardSnapshots.set(runId, snapshot);
         while (this.runCardSnapshots.size > Bridge.RUN_CARD_SNAPSHOT_MAX) {
             const oldest = this.runCardSnapshots.keys().next().value;
-            if (oldest === undefined)
-                break;
             this.runCardSnapshots.delete(oldest);
             // 卡片已经不在窗口里：继续订阅只是往一个没人看的 messageId 打 PATCH。
-            this.stopJobWatch(oldest);
+            this.jobWatch.stopJobWatch(oldest);
         }
         return snapshot;
     }
-    /** 退订一张终态卡的后台任务名单（幂等）。 */
-    stopJobWatch(runId) {
-        this.jobWatches.get(runId)?.abort();
-        this.jobWatches.delete(runId);
-        this.jobCardPatches.delete(runId);
-    }
-    /**
-     * 停止终态卡上的一个后台任务。
-     *
-     * 后台任务的生命周期跨 run（这就是它需要单独入口的原因），所以解析路径是
-     * 终态快照（runId → sessionId/cwd/agentKind）+ 该工作区的 runner 实例，
-     * 而不是 activeRuns。成功后同步摘掉 state 里的任务并就地重渲染，否则按钮
-     * 会留在卡片上而任务早已结束。
-     */
+    // =============================================================================
+    // 后台任务停止与订阅
+    // =============================================================================
+    // 实现住在 job-watch.ts（bridge 结构治理第 2 刀）：job.kill、名单订阅、
+    // markJobsUnknown 与 PATCH 串行链整体搬过去。这里只留 killBackgroundJob
+    // 薄转发——router 的 job.kill 卡片动作按名字分发到 bridge 公开 API；
+    // 快照淘汰（rememberRunCardSnapshot）与收尾订阅（finalizeRun）直接调
+    // this.jobWatch 的同名方法。
+    /** 停止终态卡上的一个后台任务（job.kill 卡片动作）。 */
     async killBackgroundJob(runId, jobId, ctx) {
-        const snapshot = this.runCardSnapshots.get(runId);
-        const sessionId = snapshot?.state.sessionId;
-        if (!snapshot || !sessionId)
-            return false;
-        const runner = this.getRunner(snapshot.cwd, snapshot.agentKind);
-        if (typeof runner.killJob !== 'function')
-            return false;
-        const killed = await runner.killJob(sessionId, jobId);
-        if (!killed)
-            return false;
-        snapshot.state = removeBackgroundJob(snapshot.state, jobId);
-        // 与订阅帧共用一条串行链：两条 PATCH 并发时，后发先至的那条会把卡片写回
-        // 旧内容（刚停掉的任务又显示成「运行中」）。
-        await this.enqueueJobCardPatch(runId, async () => {
-            await this.updateCardInPlace(renderRunCard(snapshot.state, snapshot.options), ctx);
-            return true;
-        });
-        // 卡片上已经没有在跑的任务：不必再等宿主推下一帧，直接退订。
-        if (!(snapshot.state.backgroundJobs ?? []).some(isLiveBackgroundJob)) {
-            this.stopJobWatch(runId);
-        }
-        return true;
-    }
-    /**
-     * 让终态卡的后台任务小节跟着宿主继续更新。
-     *
-     * run 的卡片在 `result` 那一帧就关闭了，但后台任务还能再跑很久：不订阅，
-     * 卡片会一直写「运行中」并留着停止按钮，点了必然失败。退订条件写
-     * 在 {@link consumeJobRoster} 里——名单清空、patch 失败、订阅中断、快照被
-     * 淘汰，任一命中即退出；**绝不因为 patch 失败补发新卡**。
-     */
-    startBackgroundJobWatch(runId, snapshot, runner) {
-        const live = (snapshot.state.backgroundJobs ?? []).some(isLiveBackgroundJob);
-        if (!live)
-            return;
-        const sessionId = snapshot.state.sessionId;
-        const messageId = snapshot.messageId;
-        const watchJobs = runner.watchJobs;
-        if (!sessionId || !messageId || typeof watchJobs !== 'function') {
-            // 没有卡 id 就没有 patch 的落点：保留收尾快照，不另发一张卡。
-            getLogger().info(`[lark-remote] background jobs stay on the turn snapshot runId=${runId} ` +
-                `(sessionId=${sessionId ?? '-'} messageId=${messageId ?? '-'} watchable=${typeof watchJobs === 'function'})`);
-            return;
-        }
-        const controller = new AbortController();
-        this.jobWatches.set(runId, controller);
-        void this.consumeJobRoster(runId, snapshot, controller, (signal) => watchJobs.call(runner, sessionId, signal));
-    }
-    /** 消费宿主推来的整份任务名单，直到全结束 / 流断 / patch 失败 / 外部退订。 */
-    async consumeJobRoster(runId, snapshot, controller, watch) {
-        const messageId = snapshot.messageId;
-        if (!messageId)
-            return;
-        let allEnded = false;
-        try {
-            for await (const roster of watch(controller.signal)) {
-                const next = syncBackgroundJobs(snapshot.state, roster);
-                // 名单没变化就不打 PATCH：宿主可能重复推同一份。
-                if (next === snapshot.state)
-                    continue;
-                snapshot.state = next;
-                const ok = await this.enqueueJobCardPatch(runId, () => this.patchCard(messageId, renderRunCard(snapshot.state, snapshot.options)));
-                if (!ok) {
-                    getLogger().warn(`[lark-remote] background job card update failed, stop watching runId=${runId}`);
-                    return;
-                }
-                if (!(snapshot.state.backgroundJobs ?? []).some(isLiveBackgroundJob)) {
-                    allEnded = true;
-                    return;
-                }
-            }
-        }
-        catch (err) {
-            if (!controller.signal.aborted) {
-                getLogger().warn(`[lark-remote] background job watch failed runId=${runId}: ${errorMessage(err)}`);
-            }
-        }
-        finally {
-            const externallyAborted = controller.signal.aborted;
-            controller.abort();
-            // 流断了而任务没结算：监控中断 ≠ 任务结束，标成未知而不是继续写「运行中」。
-            if (!allEnded && !externallyAborted)
-                await this.markJobsUnknown(runId, snapshot);
-            this.jobWatches.delete(runId);
-            this.jobCardPatches.delete(runId);
-        }
-    }
-    /** 订阅断了但任务仍未结算：把在跑的任务标成「状态未知」并重渲染一次。 */
-    async markJobsUnknown(runId, snapshot) {
-        const next = markBackgroundJobsUnknown(snapshot.state);
-        if (next === snapshot.state)
-            return;
-        snapshot.state = next;
-        const messageId = snapshot.messageId;
-        if (!messageId)
-            return;
-        await this.enqueueJobCardPatch(runId, () => this.patchCard(messageId, renderRunCard(snapshot.state, snapshot.options)));
-    }
-    /**
-     * 一张终态卡的 PATCH 串行链。
-     *
-     * 渲染放在链内执行（`task` 里读 `snapshot.state`），后入链的任务必然看到更新
-     * 后的状态；否则「停止」与「订阅帧」并发时卡片可能回退。
-     */
-    enqueueJobCardPatch(runId, task) {
-        const previous = this.jobCardPatches.get(runId) ?? Promise.resolve();
-        const next = previous.then(task, task);
-        this.jobCardPatches.set(runId, next.then(() => undefined, () => undefined));
-        return next;
+        return this.jobWatch.killBackgroundJob(runId, jobId, ctx);
     }
     /** Send a file to the user via Feishu. */
     async sendFile(filePath, ctx) {
@@ -1210,7 +1010,7 @@ export class Bridge {
         // sessionId 钉死语义——binding 有 sessionId 时用它（入队时刻快照），
         // 否则跟随 live store（无 binding 或入队时无 session 的正常路径）。
         const sessionId = opts?.binding?.sessionId ?? this.sessionStore.getSessionId(ctx.userId, agentKind);
-        // 会话代际快照（2026-08-09，2026-10-07 前移）：/new、/cd、/resume 会 bump
+        // 会话代际快照：/new、/cd、/resume 会 bump
         // epoch，该 run 后续 system.init 的 sessionId 写回即判 stale 跳过。
         // 快照点优先取 binding.sessionEpoch（入队/commit 时刻，与 sessionId 同刻）：
         // 排队消息在「commit 后、开跑前」被 reset 时，执行起点捕获会漏判（epoch 已是
@@ -1220,7 +1020,7 @@ export class Bridge {
         // Resolve the runner BEFORE creating the run session so the exact instance
         // that will run is captured into activeRun. interruptCurrentRun stops THAT
         // instance directly -- never a fresh runner re-resolved from a cache that
-        // clearRunners() may have emptied mid-run (regression 2026-07-18).
+        // clearRunners() may have emptied mid-run.
         const runner = this.getRunner(cwd, agentKind, { replaceStale: true });
         // Step 1: Create run session (runId, cardSession, activeRun tracking)
         const { runId, cardSession, activeRun } = this.createRunSession(ctx, cwd, runner, agentKind);
@@ -1252,7 +1052,7 @@ export class Bridge {
      *
      * DSH 把上游 `finish_reason: content_filter` 归一成 PI_AI_ERROR：既不在默认
      * 重试码里（EMPTY_RESPONSE/RATE_LIMIT/SERVER/TIMEOUT/TRANSPORT），也不会换模型，
-     * 于是一次（多数是误报的）判定就把整个 turn 判死。2026-10-21 现场：60 步、
+     * 于是一次（多数是误报的）判定就把整个 turn 判死。60 步、
      * 10 分钟的 turn 在最后一步被截断，已写入的文件还在，用户只看到「运行出错」
      * 加一句英文报文。
      *
@@ -1371,12 +1171,23 @@ export class Bridge {
                 }
                 stop();
                 getLogger().warn(`[lark-remote] claude idle timeout, stopping process runId=${opts.runId}`);
+                // 看门狗清理的两个结果都必须留痕：卡片 patch 失败时终态会停在
+                // 「运行中」；runner.stop 失败时挂死的 run 没被杀、cwd 槽位未释放，
+                // 串行队列从此永久堵死（用户视角「机器人不回消息」，日志却只有
+                // 前面一条 warn）。对照 claude session.ts idle timer 的 .catch(log)。
                 void Promise.allSettled([
                     opts.session.finish('idle_timeout', {
                         idleTimeoutMinutes: Math.max(1, Math.round(this.idleTimeoutMs / 60_000)),
                     }),
                     opts.runner.stop(),
-                ]);
+                ]).then(([finishResult, stopResult]) => {
+                    if (finishResult.status === 'rejected') {
+                        getLogger().error(`[lark-remote] idle-timeout cleanup failed runId=${opts.runId} finish:`, finishResult.reason);
+                    }
+                    if (stopResult.status === 'rejected') {
+                        getLogger().error(`[lark-remote] idle-timeout cleanup failed runId=${opts.runId} stop:`, stopResult.reason);
+                    }
+                });
             }, tickMs);
         }
         return {
@@ -1395,7 +1206,7 @@ export class Bridge {
      * result 在 system.init 之后才到。
      *
      * 例外：app-server runner（usageAuthority==='live'）的 init 是 runner 自己补发
-     * 的 synthetic init（2026-08-13 修复）。此分支保留为防御性兜底：live runner 若
+     * 的 synthetic init。此分支保留为防御性兜底：live runner 若
      * 在无 init 时发出 result（旧构建等），session 写回照常执行，但 sawResult 不置
      * 真——卡片不会把半初始化的 run 当作已收尾。
      *
@@ -1474,7 +1285,7 @@ export class Bridge {
         const { cardSession, usage, sawResult, sawAnyResult, pendingPreInitTerminal, agentKind, runId, } = opts;
         const finalState = cardSession.currentState;
         if (finalState.terminal === 'finalizing') {
-            // 三态终态映射（2026-08-14）：interrupted（审批超时/取消、/stop）是独立
+            // 三态终态映射：interrupted（审批超时/取消、/stop）是独立
             // 终态，不再归因于 Agent 错误；error 保持「运行出错」；其余为 done。
             const subtype = finalState.resultSubtype;
             const isError = subtype === 'error' || !!finalState.errorMsg;
@@ -1540,203 +1351,259 @@ 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;
-                }
-                if (event.type === 'system' && event.subtype === 'init') {
-                    sawInit = true;
-                    // 本轮真实使用的 session（不可变身份）：指针在 run 中被 /new 等移动时，
-                    // 结束后的 usage 读取仍以它为准。
-                    activeRun.sessionId = event.session_id;
-                    writeBackInitSession(writeback, event);
-                    getLogger().info(`[lark-remote] 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），会话无法延续。
-                    // init 缺失时以 threadId 作为本轮身份兜底。
-                    activeRun.sessionId ??= event.threadId;
-                    writeBackTurnStarted(writeback, event);
-                }
-                // Track context length from compaction events
-                if (event.type === 'system' &&
-                    event.subtype === 'compact_boundary' &&
-                    event.compactMetadata) {
-                    usage.observeCompaction(event.compactMetadata.postTokens);
-                }
-                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 活着并且在产事件。
-                        watchdog?.touch();
-                        continue;
-                    }
-                }
-                // Approval events (Codex app-server mode)
-                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 分支。
-                watchdog?.touch();
-                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 抽出的纯向方法）。
+     *
+     * §9.12：事件到达只 `touch()` 刷新时间戳（无 timer 操作），interval 周期检查
+     * 静默时长；喂狗点与红线口径见 runAgentStreamToEnd 循环内两处调用点注释
+     * （每个事件含 result 都必须喂，被守卫丢弃的 result 也喂——CLI 活着就在产事件）。
+     */
+    handleEventForWatchdog(watchdog) {
+        watchdog?.touch();
+    }
+    /**
+     * 事件循环的 session 同步（runAgentStreamToEnd 抽出的纯向方法）：
+     * init / turn_started 两写回点 + compact_boundary 用量观察。
+     *
+     * @returns 事件是否为本轮 `system.init`（调用方据此置 sawInit，供 pre-init
+     * result 守卫判定）。init 分支的全部副作用完成后才返回，与原内联顺序一致。
+     */
+    maybeSyncSession(event, opts) {
+        const { activeRun, writeback, usage, runId } = opts;
+        if (event.type === 'system' && event.subtype === 'init') {
+            // 本轮真实使用的 session（不可变身份）：指针在 run 中被 /new 等移动时，
+            // 结束后的 usage 读取仍以它为准。
+            activeRun.sessionId = event.session_id;
+            writeBackInitSession(writeback, event);
+            getLogger().info(`[lark-remote] system.init received runId=${runId} sessionId=${event.session_id} cwd=${event.cwd}`);
+            return true;
+        }
+        if (event.type === 'turn_started') {
+            // app-server runner 在 turn setup 成功后补发 synthetic system.init
+            // （§9.22 守卫前提），此处 turn_started 写回保留为双保险：两者都用
+            // threadId 写回 sessionId（代际守卫一致），幂等。缺失会导致每次消息
+            // 都新建线程（thread/start 而非 thread/resume），会话无法延续。
+            // init 缺失时以 threadId 作为本轮身份兜底。
+            activeRun.sessionId ??= event.threadId;
+            writeBackTurnStarted(writeback, event);
+        }
+        // Track context length from compaction events
+        if (event.type === 'system' && event.subtype === 'compact_boundary' && event.compactMetadata) {
+            usage.observeCompaction(event.compactMetadata.postTokens);
+        }
+        return false;
+    }
     /**
      * 终态 reaction 收尾：撤掉 Typing、打上下方终态表情。
      *
@@ -1806,7 +1673,7 @@ export class Bridge {
             this.finishTurnReactions(ctx, terminalReactionEmoji(cardSession.currentState.terminal));
             // 后台任务跨 turn：卡片收尾只是"这一轮的投影结束了"，任务本身可能还在跑。
             // 订阅放在最后：卡片已落地，patch 才有落点。
-            this.startBackgroundJobWatch(runId, snapshot, activeRun.runner);
+            this.jobWatch.startBackgroundJobWatch(runId, snapshot, activeRun.runner);
         }
         finally {
             // cleanup must survive mid-finalize errors. The only unguarded
@@ -1822,7 +1689,7 @@ export class Bridge {
             // runId，只能回「该任务已结束或不属于当前会话」。守卫只回答「cwd 槽位还
             // 归不归本 run」（决定能不能删槽位/evict runner），记账回答「这次 run
             // 结束了吗、用的哪个 sessionId」——后者与所有权无关，放在守卫外。
-            this.recordCompactableRunForTerminal(cardSession, activeRun, ctx);
+            this.compact.recordCompactableRunForTerminal(cardSession, activeRun, ctx);
             if (this.activeRuns.get(cwd) === activeRun) {
                 this.activeRuns.delete(cwd);
                 // Workspace-lifetime runners (codex app-server) keep their persistent
@@ -1920,498 +1787,31 @@ export class Bridge {
     async handleApprovalAnswerNote(opts) {
         return this.approvalActions.handleApprovalAnswerNote(opts);
     }
-    /**
-     * 记下一次「可压缩 run」：终态卡上的 Compact 按钮点击时据此反查
-     * sessionId + agentKind。runId 是按钮自带的唯一键，同 cwd 内唯一。
-     * 超出上限按插入序淘汰最旧的一条（Map 保持插入序；重复写同一 runId
-     * 先 delete 再 set 以刷新位置）。
-     */
-    recordCompactableRun(cwd, runId, sessionId, agentKind) {
-        let byRunId = this.compactableRuns.get(cwd);
-        if (!byRunId) {
-            byRunId = new Map();
-            this.compactableRuns.set(cwd, byRunId);
-        }
-        byRunId.delete(runId);
-        byRunId.set(runId, { sessionId, agentKind, cwd });
-        while (byRunId.size > MAX_COMPACTABLE_RUNS_PER_CWD) {
-            const oldest = byRunId.keys().next().value;
-            if (oldest === undefined)
-                break;
-            byRunId.delete(oldest);
-        }
-    }
-    /**
-     * 终态 Compact 记账：把本次 run 实际使用的 sessionId 记进
-     * {@link compactableRuns}，供终态卡上的 Compact 按钮按 runId 反查。
-     *
-     * 调用点固定在 `finalizeRun` 的 `finally` 里、**槽位所有权守卫之外**。
-     * 所有权守卫只回答「cwd 槽位还归不归本 run」（决定能否删槽位 / evict
-     * runner）；记账回答「本次 run 结束了吗、用的哪个 sessionId」。两者在不同
-     * 维度上：外部中断（`/stop`、停止卡按钮、`queue.immediate`）会先摘槽位，
-     * 记账若跟着守卫走就永远不会落，中断卡片的按钮必然反查不到（中断
-     * 后点 Compact 一律回「该任务已结束或不属于当前会话」）。
-     *
-     * 覆盖所有终态入口（正常结束、error、interrupted、idle_timeout、
-     * goal_continuing）——这些卡片都渲染 Compact 按钮（`goal` 仍 active 时
-     * 除外）。记账失败不能影响清理，故内部兜错。
-     */
-    recordCompactableRunForTerminal(cardSession, activeRun, ctx) {
-        try {
-            if (!runnerSupportsCompact(activeRun.runner, activeRun.agentKind))
-                return;
-            if (activeRun.runner.lifetime !== 'workspace')
-                return;
-            const terminal = cardSession.currentState.terminal;
-            // 与事件消费守卫、Compact 按钮共用同一份终态集合（run-state.ts）。
-            if (!isRunTerminal(terminal))
-                return;
-            // 卡片状态优先（本轮 init/turn_started 写入）；缺失时回退 store——
-            // 启动失败但已 /stop 的 run 没有自己的 init，压缩此前会话仍是有意义
-            // 的动作。
-            const compactSessionId = cardSession.currentState.sessionId ??
-                this.sessionStore.getSessionId(ctx.userId, activeRun.agentKind);
-            if (!compactSessionId)
-                return;
-            this.recordCompactableRun(activeRun.cwd, activeRun.runId, compactSessionId, activeRun.agentKind);
-        }
-        catch (err) {
-            getLogger().warn(`[lark-remote] compact record failed runId=${activeRun.runId}: ${errorMessage(err)}`);
-        }
-    }
-    /**
-     * 按 runId 反查可压缩 run 记录（跨 cwd 扫描）。
-     *
-     * 为什么不带 cwd 过滤：按钮属于「那一次 run」，与用户此刻在哪个工作目录、
-     * 排队期间有没有 /cd 无关。`/stop` 的 interruptCurrentRun 同样是全局按 runId
-     * 找（从不查当前 cwd），compact 与它保持一致。用当前 cwd 收窄会让「切了工作区
-     * 再点旧卡片」和「排队期间 /cd」两种情况误报「该任务已结束或不属于当前会话」。
-     */
-    findCompactableRun(runId) {
-        for (const byRunId of this.compactableRuns.values()) {
-            const record = byRunId.get(runId);
-            if (record)
-                return record;
-        }
-        return undefined;
-    }
-    /**
-     * Handle compact card action — trigger a compaction request for any
-     * runCompact-capable runner（codex/kimi/opencode/pi/claude）。按钮带的是
-     * 那次 run 的 runId，据此反查该 run 实际使用的 sessionId + agentKind
-     * + cwd（compactableRuns，按 runId 记录），再调 runner 的 runCompact()。
-     */
+    // =============================================================================
+    // Compact 动作入口
+    // =============================================================================
+    // 实现住在 compact.ts（bridge 结构治理第 1 刀）：可压缩 run 记账、终态卡 /
+    // resume 卡两条入口、kimi 在途检测与压缩流式卡全部搬过去；这里只留薄转发，
+    // router 的卡片动作分发（handleCardAction → bridge.handleCompactAction /
+    // handleResumeCompact）与 finalizeRun 的终态记账调用路径不变。
+    /** 终态卡 Compact 按钮：按 runId 反查那次 run 的会话并发起压缩。 */
     async handleCompactAction(value, ctx) {
-        const log = getLogger();
-        log.info(`[lark-remote] handleCompactAction userId=${ctx.userId} runId=${value.runId?.slice(0, 8)}...`);
-        const { runId } = value;
-        if (!runId) {
-            await this.sendResult({ text: '⚠️ 无效的 Compact 请求，缺少 runId' }, ctx);
-            return;
-        }
-        // 校验：run 结束后 activeRuns 已清空，只能靠按钮自带的 runId 反查记录。
-        // 按 runId 存（不按「最新的那一条」），点击到执行之间夹了新 run 收尾也不失效；
-        // 查找也不按「当前 cwd」收窄（见 findCompactableRun）。
-        const target = this.findCompactableRun(runId);
-        if (!target) {
-            await this.sendResult({ text: '⚠️ 该任务已结束或不属于当前会话' }, ctx);
-            return;
-        }
-        // 压缩必须用那次 run 自己的 cwd（session 文件 + runner 实例都按 cwd 解析）。
-        const cwd = target.cwd;
-        // §5.3: kimi 压缩在途检测（wire 状态机）。第二次点击在本地毫秒级如实回答，
-        // 不开卡、不发 session/prompt——否则 kimi 服务端拒绝并产生「秒回」假完成。
-        if (await this.rejectIfCompactionInFlight(target.sessionId, cwd, target.agentKind, ctx)) {
-            return;
-        }
-        // Check that the runner has runCompact method（声明表 && runner 实现）
-        const runner = this.getRunner(cwd, target.agentKind, { replaceStale: true });
-        if (!runnerSupportsCompact(runner, target.agentKind)) {
-            await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
-            return;
-        }
-        log.info(`[lark-remote] handleCompactAction executing runCompact for runId=${runId} cwd=${cwd}`);
-        await this.streamCompact({
-            sessionId: target.sessionId,
-            cwd,
-            agentKind: target.agentKind,
-            runner,
-            ctx,
-        });
-    }
-    /**
-     * §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)
-            return false;
-        try {
-            const state = reader.readCompactionState(sessionId, cwd);
-            if (state?.inFlight) {
-                const since = state.inFlightSince;
-                let timeLabel = '未知时刻';
-                if (since !== undefined) {
-                    const d = new Date(since);
-                    const hh = String(d.getHours()).padStart(2, '0');
-                    const mm = String(d.getMinutes()).padStart(2, '0');
-                    timeLabel = `${hh}:${mm}`;
-                }
-                await this.sendResult({ text: `⚠️ 已有一次 Compact 正在进行（开始于 ${timeLabel}），请等待完成` }, ctx);
-                return true;
-            }
-        }
-        catch (err) {
-            getLogger().warn(`[lark-remote] readCompactionState failed sessionId=${sessionId}: ${errorMessage(err)}`);
-        }
-        return false;
+        await this.compact.handleCompactAction(value, ctx);
     }
-    /**
-     * Stream a 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 handleCompactAction (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 streamCompact(opts) {
-        const log = getLogger();
-        const { sessionId, cwd, agentKind, runner, ctx } = opts;
-        log.info(`[lark-remote] streamCompact sessionId=${sessionId} cwd=${cwd}`);
-        // 防御性能力检查：调用方已校验（runId / resume 两条路径），此处双保险并
-        // 让 TS 收窄 runner 类型（'runCompact' in runner 之后的 cast 才合法）。
-        if (!runnerSupportsCompact(runner, agentKind) ||
-            !('runCompact' in runner) ||
-            typeof runner.runCompact !== 'function') {
-            await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
-            return;
-        }
-        // activeRuns 以 cwd 为键：注册前先确认槽位空闲，否则压缩会覆盖在跑的 run 的
-        // 记录，令 /stop 只停到最后注册的那个。
-        const busyWith = this.activeRuns.get(cwd);
-        if (busyWith) {
-            log.info(`[lark-remote] compact refused: cwd busy cwd=${cwd} runId=${busyWith.runId}`);
-            await this.sendResult({ text: '⚠️ 该工作区正在运行任务，请等待结束或先 /stop' }, ctx);
-            return;
-        }
-        await this.sendResult({ text: '🗜 Compact 已触发，正在压缩会话…' }, ctx);
-        const compactRunId = randomUUID();
-        // 渲染选项同时用于流式卡与「卡片流没建起来」时的静态兜底卡——两者必须
-        // 同门控，否则兜底卡会渲染出与本次 run 不一致的按钮。
-        const renderOptions = { agentKind };
-        const cardSession = new RunCardSession({
-            connector: this.connector,
-            chatId: ctx.chatId,
-            replyTo: ctx.messageId,
-            runId: compactRunId,
-            renderOptions,
-        });
-        // 压缩与普通 run 共用同一套生命周期——注册进 activeRuns（/stop 有对象可停、
-        // /active 看得见）、挂 §9.12 空闲看门狗、终态后补 reaction。缺任何一环，卡住的
-        // 压缩都只能等 runner 级超时，用户既停不掉也看不出它还在跑。
-        const activeRun = {
-            runId: compactRunId,
-            userId: ctx.userId,
-            chatId: ctx.chatId,
-            session: cardSession,
-            cwd,
-            runner,
-            agentKind,
-        };
-        this.activeRuns.set(cwd, activeRun);
-        getLogger().info(`[lark-remote] activeRuns.set cwd=${cwd} runId=${compactRunId} compact=true`);
-        let watchdog = null;
-        try {
-            await cardSession.start();
-            watchdog = this.startIdleWatchdog({
-                runId: compactRunId,
-                session: cardSession,
-                runner,
-            });
-            // operationKind=compaction：卡片不渲染 Compact 按钮（防递归 Compact）。
-            await cardSession.push({
-                type: 'turn_started',
-                threadId: sessionId,
-                turnId: '',
-                operationKind: 'compaction',
-            });
-            let sawResult = false;
-            let resultSubtype;
-            let resultError;
-            for await (const event of runner.runCompact('', { cwd, sessionId })) {
-                // 已终态（/stop、空闲看门狗）后不再消费事件：与 runAgentStreamToEnd 同口径，
-                // 否则迟到的 result 会把终态卡改写成「已完成」。
-                const cardTerminal = cardSession.currentState.terminal;
-                if (isRunTerminal(cardTerminal)) {
-                    continue;
-                }
-                if (event.type === 'result') {
-                    sawResult = true;
-                    resultSubtype = event.subtype;
-                    resultError = event.errorMessage;
-                }
-                watchdog?.touch();
-                await cardSession.push(event);
-            }
-            // §5.3: 卡片终态必须等于引擎真实终态。旧实现只看 sawResult 布尔——error
-            // subtype 的 result 也被 finish 'done'（放大器 bug，2026-08-31 事故）。
-            const terminal = resultSubtype === 'success'
-                ? 'done'
-                : resultSubtype === 'interrupted'
-                    ? 'interrupted'
-                    : 'error';
-            // 压缩结束后从会话 jsonl 读权威统计（压缩后上下文、压缩次数、本次压缩
-            // token 消耗与会话累计）。thread/compacted 通知与 jsonl 落盘几乎同时
-            // （实测差 ~9ms），compactCount 未读到则短重试，仍失败优雅降级（无统计）。
-            // 不支持 compactCount 的 reader（opencode/dsh）不重试——否则每次 compact
-            // 都会固定多跑两次完整 export/读取，且永远等不到该字段。
-            const compactCountSupported = this.sessionReaderRegistry.tryGet(agentKind)?.supportsCompactCount !== false;
-            let finalUsage = resolveFinalUsage(this.sessionReaderRegistry, this.config.defaultAgent, sessionId, cwd, agentKind);
-            for (let attempt = 0; compactCountSupported && !finalUsage?.compactCount && attempt < 2; attempt++) {
-                await sleep(150);
-                finalUsage = resolveFinalUsage(this.sessionReaderRegistry, this.config.defaultAgent, sessionId, cwd, agentKind);
-            }
-            await cardSession.finish(terminal, {
-                resultSubtype: resultSubtype ?? 'error',
-                errorMsg: terminal === 'error' ? (resultError ?? '未收到压缩结果') : undefined,
-                // finalUsage 的字段形态就是 FinishMeta 的用量部分（同为 UsageSnapshot），
-                // 逐字段抄的那 14 行随单源一起去掉。
-                ...(finalUsage ?? {}),
-            });
-            log.info(`[lark-remote] streamCompact finished sessionId=${sessionId} sawResult=${sawResult} subtype=${resultSubtype ?? 'none'}`);
-        }
-        catch (err) {
-            log.error(`[lark-remote] streamCompact failed: ${errorMessage(err)}`);
-            // 终态守卫（与 runAgentStreamToEnd 同口径）：running/finalizing 才转 error，
-            // 已终态（interrupted/idle_timeout）保留首终态，不被迟到的异常改写。
-            const catchTerminal = cardSession.currentState.terminal;
-            if (!isRunTerminal(catchTerminal)) {
-                await cardSession.finish('error', { errorMsg: errorMessage(err) });
-            }
-            else {
-                log.info(`[lark-remote] skip compact error finish: state already terminal (${catchTerminal}) runId=${compactRunId}`);
-            }
-        }
-        finally {
-            watchdog?.stop();
-            // 与 run 路径同口径的降级：卡片流没建起来（start 失败 / stream 未收尾）时，
-            // 终态只存在于内存里。settle() 释放 producer 并等 stream 收尾；'unsent'
-            // 表示用户手里没有卡，必须补一张静态终态卡，否则只剩「Compact 已触发」
-            // 和一条 reaction，用户既不知道失败也不知道原因。
-            const settled = await cardSession.settle();
-            if (settled === 'unsent') {
-                const finalRender = renderRunCardDetailed(cardSession.currentState, renderOptions);
-                await this.sendResult({ card: finalRender.card }, ctx);
-            }
-            // 只摘自己的槽位：/stop 可能已删掉本条并让排队的下一条占住同一 cwd。
-            if (this.activeRuns.get(cwd) === activeRun) {
-                this.activeRuns.delete(cwd);
-                getLogger().info(`[lark-remote] activeRuns.delete cwd=${cwd} runId=${compactRunId}`);
-            }
-            // 终态 reaction：与普通 run 同一口径（done→Done / error→ERROR /
-            // interrupted→SHHH / idle_timeout→Alarm）。
-            this.finishTurnReactions(ctx, terminalReactionEmoji(cardSession.currentState.terminal));
-        }
-    }
-    /**
-     * Handle resume.compact card action — compact a session directly from a
-     * resume card (auto-resume / `/resume <id>`), without a runId.
-     *
-     * Unlike handleCompactAction (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.
-     */
+    /** resume 卡 Compact 按钮：直接压缩卡上指定的 session（无需 runId）。 */
     async handleResumeCompact(value, ctx) {
-        const log = getLogger();
-        log.info(`[lark-remote] 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. 名单来自单源 AGENT_KINDS —— 手抄一份
-        // 必然再次漂移（这份曾经漏 dsh：带 dsh 的卡片会静默退回 defaultAgent，
-        // 用错 reader 报「未找到 session」）。
-        const agentKind = value.agent && AGENT_KINDS.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;
-        }
-        // §5.3: kimi 压缩在途检测（与 handleCompactAction 同一入口）。
-        if (await this.rejectIfCompactionInFlight(sessionId, cwd, agentKind, ctx))
-            return;
-        // Check that the runner has runCompact（声明表 && runner 实现；
-        // codex/kimi/opencode/pi/claude/dsh 均已实现）。
-        const runner = this.getRunner(cwd, agentKind);
-        if (!runnerSupportsCompact(runner, agentKind)) {
-            await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
-            return;
-        }
-        log.info(`[lark-remote] handleResumeCompact executing runCompact sessionId=${sessionId} cwd=${cwd}`);
-        await this.streamCompact({ sessionId, cwd, agentKind, runner, ctx });
+        await this.compact.handleResumeCompact(value, ctx);
     }
-    /**
-     * Execute a bash command and stream output to a card.
-     * `!` commands bypass the serial queue entirely (see body comment + §9.6):
-     * bash runs in parallel with same-workspace agent runs, tracked in
-     * `activeBashRuns` separately from `activeRuns`.
-     */
+    // =============================================================================
+    // `!` bash 命令
+    // =============================================================================
+    // 实现住在 bash-run.ts（bridge 结构治理第 3 刀）：executeBash 薄壳、事件流
+    // 消费、独立登记表（activeBashRuns，不进 activeRuns）与 /stop 的 bash 侧
+    // 匹配全部搬过去。这里只留薄转发——router 的 `!` 分发（executeBash）与
+    // /active 投影（getActiveBashRuns）按 bridge 公开 API 调用。
+    /** Execute a bash command and stream output to a card（`!` 命令入口）。 */
     async executeBash(command, ctx) {
-        const cwd = this.resolveCwd(ctx.userId);
-        getLogger().info(`[lark-remote] executeBash start userId=${ctx.userId} sessionCwd=${this.sessionStore.get(ctx.userId)?.cwd} command="${command.slice(0, 30)}..."`);
-        if (!cwd) {
-            getLogger().info(`[lark-remote] executeBash no cwd, sending error`);
-            await this.sendResult({ text: '请先使用 /cd <path> 设置工作目录，或保存一个 workspace (/ws save <name>)' }, ctx);
-            return;
-        }
-        getLogger().info(`[lark-remote] executeBash proceeding cwd=${cwd}`);
-        // `!` commands bypass the serial queue entirely (design.md §9.6):
-        // index.ts dispatches `!` to router.handle → executeBash directly, NOT via
-        // bridge.enqueue. bash runs in parallel with same-workspace claude runs.
-        // bash runs are tracked in `activeBashRuns` (keyed by runId), separate from
-        // claude's `activeRuns` (keyed by cwd) — they must not collide or `/stop`
-        // would kill the wrong task. Do NOT re-chain onto the serial queue
-        // (QueueManager) here: that would block on the still-pending outer promise
-        // and deadlock self-wait.
-        await this.executeBashInternal(command, ctx, cwd);
-    }
-    /**
-     * Internal execution of bash command (called directly from executeBash,
-     * bypassing the serial queue — see executeBash).
-     */
-    async executeBashInternal(command, ctx, cwd) {
-        getLogger().debug(`[lark-remote] executeBashInternal userId=${ctx.userId} chatId=${ctx.chatId} cwd=${cwd} command="${command.slice(0, 50)}..."`);
-        // Note: We don't check activeRuns here because bash bypasses the serial
-        // queue and runs in parallel with same-workspace agent runs (§9.6). The
-        // activeRuns check in forwardToClaude is for a different purpose (detecting
-        // concurrent agent runs that would corrupt session state). Bash commands
-        // don't have that issue.
-        const runId = randomUUID();
-        const bashRunner = new BashProcessRunner();
-        // Single streaming card across the whole run (initial → output patches →
-        // terminal), instead of sending many independent cards. BashCardSession is
-        // the bash analogue of RunCardSession.
-        const cardSession = new BashCardSession({
-            connector: this.connector,
-            chatId: ctx.chatId,
-            replyTo: ctx.messageId,
-            runId,
-            command,
-            renderOptions: {},
-        });
-        // Track this bash run independently from claude's `activeRuns`. Bash runs
-        // bypass the serial queue and may run in parallel with a claude run in the
-        // same cwd, so they must NOT share activeRuns (which is keyed by cwd
-        // and would let bash/claude overwrite each other). Keyed by runId so
-        // multiple `!` commands can run concurrently. Tracked so /stop can reach
-        // the bashRunner (which is otherwise a local) via interruptCurrentRun.
-        this.activeBashRuns.set(runId, {
-            bashRunner,
-            cardSession,
-            userId: ctx.userId,
-            chatId: ctx.chatId,
-            cwd,
-            command,
-        });
-        let output = '';
-        let stderr = '';
-        let exitCode = null;
-        try {
-            getLogger().info(`[lark-remote] executeBashInternal about to start stream chatId=${ctx.chatId} messageId=${ctx.messageId}`);
-            try {
-                await cardSession.start();
-                getLogger().info(`[lark-remote] executeBash stream started runId=${runId}`);
-            }
-            catch (err) {
-                getLogger().warn('[lark-remote] bash card stream unavailable:', err);
-            }
-            for await (const event of bashRunner.run(command, { cwd })) {
-                if (event.type === 'stdout') {
-                    // 层④：bridge 本地 output 也必须 store-time 截断——仅 session state
-                    // 有界并不会让 `output +=` 自然有界（「store 有界则本地拼接自然有界」
-                    // 不成立），!yes 洪峰下本地字符串仍全量驻留。capBashOutput 增量调用
-                    // O(CAP+chunk)，不会带回 O(n²) 截断成本（output 恒 ≤ CAP，拼接后
-                    // ≤ CAP+chunk 再 slice 尾部）。
-                    output = capBashOutput(output + event.content);
-                    await cardSession.update({ output, stderr });
-                }
-                else if (event.type === 'stderr') {
-                    stderr = capBashOutput(stderr + event.content);
-                    await cardSession.update({ output, stderr });
-                }
-                else if (event.type === 'exit') {
-                    exitCode = event.exitCode ?? 0;
-                }
-            }
-            await cardSession.finish(exitCode === 0 ? 'done' : 'error', { exitCode, output, stderr });
-        }
-        catch (err) {
-            getLogger().error(`[lark-remote] bash run error runId=${runId}:`, err);
-            // If for-await threw mid-stream the bash child may still be running.
-            // Stop it before finalizing the card — otherwise the finally block
-            // removes the activeBashRuns entry and /stop can no longer reach it,
-            // leaving an orphan process.
-            try {
-                await bashRunner.stop();
-            }
-            catch (stopErr) {
-                getLogger().warn(`[lark-remote] bash stop failed:`, stopErr);
-            }
-            await cardSession.finish('error', {
-                exitCode: 1,
-                output,
-                stderr: stderr + `\n执行错误: ${errorMessage(err)}`,
-            });
-        }
-        finally {
-            const settleResult = await cardSession.settle();
-            if (settleResult === 'unsent') {
-                // Stream never established a card — send a static terminal card as fallback.
-                // Use 2.0 schema to match the streaming card (avoid 2.0→1.x downgrade).
-                try {
-                    await this.connector.sendWithRetry(ctx.chatId, { card: renderBashCard(cardSession.currentState, {}) }, { replyTo: ctx.messageId });
-                }
-                catch (fallbackErr) {
-                    getLogger().error(`[lark-remote] bash terminal fallback card failed runId=${runId} chatId=${ctx.chatId}:`, fallbackErr);
-                }
-            }
-            if (this.activeBashRuns.has(runId)) {
-                this.activeBashRuns.delete(runId);
-                getLogger().info(`[lark-remote] executeBash done runId=${runId} exitCode=${exitCode}`);
-            }
-            // Add a Done emoji reaction to the user's original message to signal completion
-            this.finishTurnReactions(ctx, 'Done');
-        }
+        await this.bashRuns.executeBash(command, ctx);
     }
 }
 //# sourceMappingURL=index.js.map