lark-remote 0.5.18 → 0.5.20

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 { isRunActive, isRunTerminal, removeBackgroundJob, } 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,6 @@ 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');
-}
-/**
- * 已告警过的能力不一致 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;
-}
-/**
- * 每个 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 +97,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 +123,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,12 +138,17 @@ export class Bridge {
     runCardSnapshots = new Map();
     static RUN_CARD_SNAPSHOT_MAX = 8;
     /**
-     * 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.
+     * 终态卡后台任务订阅与停止（见 job-watch.ts）：job.kill、名单订阅与
+     * PATCH 串行链收在该模块；jobCardPatches 链内渲染读 snapshot.state，
+     * 「停止」与「订阅帧」并发不会把卡片写回旧内容。
+     */
+    jobWatch;
+    /**
+     * `!` 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;
@@ -214,11 +162,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.
      */
@@ -365,9 +338,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.
@@ -631,25 +604,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
@@ -664,15 +619,31 @@ export class Bridge {
         // 并行跑；旧实现停在「第一条命中」就 return —— 两个 workspace 并行时
         // `/stop` 只停一个却回「已停止」，另一个无声继续。
         // 限定 cwd（queue.immediate）或带 runId（停止卡按钮）时仍只有一条命中。
-        const activeTargets = [];
+        const ownedActiveRuns = [];
         for (const [cwd, active] of this.activeRuns) {
             if (input.cwd !== undefined && cwd !== input.cwd)
                 continue;
             if (active.userId !== input.userId || active.chatId !== input.chatId)
                 continue;
-            if (input.runId && active.runId !== input.runId)
-                continue;
-            activeTargets.push([cwd, active]);
+            ownedActiveRuns.push([cwd, active]);
+        }
+        // Card stop prefers the authoritative runId. If the click is scoped to a
+        // run card but that value is stale/absent, accept only the active run whose
+        // server-provided card messageId is exactly the clicked card. This repairs
+        // callbacks that lose behavior-value without ever stopping a historical or
+        // dashboard card against a newer run.
+        let activeTargets;
+        if (input.runId) {
+            activeTargets = ownedActiveRuns.filter(([, active]) => active.runId === input.runId);
+            if (activeTargets.length === 0) {
+                activeTargets = this.activeRunsForCard(ownedActiveRuns, input.cardMessageId);
+            }
+        }
+        else if (input.cardMessageId) {
+            activeTargets = this.activeRunsForCard(ownedActiveRuns, input.cardMessageId);
+        }
+        else {
+            activeTargets = ownedActiveRuns;
         }
         let stoppedCount = 0;
         let agentKind;
@@ -689,37 +660,16 @@ 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 includeBashRuns = (input.runId === 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 && runId !== input.runId)
-                    return false;
-                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().debug(`[lark-remote] interrupt miss userId=${input.userId}`);
+            getLogger().warn(`[lark-remote] interrupt miss userId=${input.userId} ` +
+                `requestedRunId=${input.runId ?? '(none)'} ` +
+                `cardMessageId=${input.cardMessageId ?? '(none)'} ` +
+                `active=${ownedActiveRuns.map(([, active]) => active.runId).join(',') || '(none)'}`);
             return { stopped: false };
         }
         return {
@@ -729,6 +679,26 @@ export class Bridge {
             ...(stop ? { stop } : {}),
         };
     }
+    /**
+     * Resolve a scoped card click by card identity. Empty input or multiple
+     * matches fail closed; production message ids are unique, but refusing an
+     * ambiguous stop is safer than killing several workspaces.
+     */
+    activeRunsForCard(ownedActiveRuns, cardMessageId) {
+        if (!cardMessageId)
+            return [];
+        const matches = ownedActiveRuns.filter(([, active]) => active.session.cardMessageId === cardMessageId);
+        if (matches.length === 0)
+            return [];
+        if (matches.length > 1) {
+            getLogger().warn(`[lark-remote] interrupt ambiguous cardMessageId=${cardMessageId} ` +
+                `active=${matches.map(([, active]) => active.runId).join(',')}`);
+            return [];
+        }
+        getLogger().warn(`[lark-remote] interrupt using active card fallback ` +
+            `runId=${matches[0][1].runId} cardMessageId=${cardMessageId}`);
+        return matches;
+    }
     /**
      * 停掉一条已注册的 active run：置终态、停 runner、摘槽位、标 stale、
      * 归零该 cwd 的队列执行计数。返回 runner 的停止结果（DSH 才有）。
@@ -741,8 +711,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
@@ -750,18 +720,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.
@@ -777,8 +757,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 不变。
@@ -800,11 +780,18 @@ 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;
     }
-    /** Send a result message to the user (§7). Returns true on success, false on failure. */
-    async sendResult(result, ctx) {
+    /**
+     * Send a result message to the user (§7). Returns true on success, false on failure.
+     *
+     * `opts.onCardSent` 回传卡片的 messageId：终态卡收尾后还要靠它接收后台任务
+     * 更新（流式卡从 `cardSession.cardMessageId` 取，兜底发送只能从这里拿）。
+     */
+    async sendResult(result, ctx, opts) {
         try {
             if (result.card) {
                 // 静态卡片体积保护：确保卡片不超过飞书大小限制
@@ -813,7 +800,8 @@ export class Bridge {
                     getLogger().info(`[lark-remote] card size exceeded limit, applied budget enforcement: reason=${reason} bytesBefore=${bytesBefore} bytesAfter=${bytesAfter}`);
                 }
                 getLogger().debug(`[lark-remote] sendResult kind=card chatId=${ctx.chatId}`);
-                await this.connector.sendWithRetry(ctx.chatId, { card: safeCard }, { replyTo: ctx.messageId });
+                const messageId = await this.connector.sendWithRetry(ctx.chatId, { card: safeCard }, { replyTo: ctx.messageId });
+                opts?.onCardSent?.(messageId);
                 return true;
             }
             else if (result.markdown) {
@@ -845,25 +833,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.
@@ -925,37 +910,34 @@ export class Bridge {
      * 不放在 finish() 里：bridge 才知道 hasRunCompact 等渲染选项，且 eviction
      * 与 activeRuns 生命周期在同一个地方收口。
      */
-    rememberRunCardSnapshot(runId, state, options, cwd, agentKind) {
-        this.runCardSnapshots.set(runId, { state, options, cwd, agentKind });
+    rememberRunCardSnapshot(runId, state, options, cwd, agentKind, messageId) {
+        const snapshot = {
+            state,
+            options,
+            cwd,
+            agentKind,
+            ...(messageId === undefined ? {} : { messageId }),
+        };
+        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.jobWatch.stopJobWatch(oldest);
         }
+        return snapshot;
     }
-    /**
-     * 停止终态卡上的一个后台任务。
-     *
-     * 后台任务的生命周期跨 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);
-        await this.updateCardInPlace(renderRunCard(snapshot.state, snapshot.options), ctx);
-        return true;
+        return this.jobWatch.killBackgroundJob(runId, jobId, ctx);
     }
     /** Send a file to the user via Feishu. */
     async sendFile(filePath, ctx) {
@@ -1029,7 +1011,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 已是
@@ -1039,7 +1021,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);
@@ -1071,7 +1053,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 在最后一步被截断，已写入的文件还在，用户只看到「运行出错」
      * 加一句英文报文。
      *
@@ -1190,12 +1172,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 {
@@ -1214,7 +1207,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 当作已收尾。
      *
@@ -1293,7 +1286,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;
@@ -1431,29 +1424,13 @@ export class Bridge {
                 if (isRunTerminal(terminal)) {
                     continue;
                 }
-                if (event.type === 'system' && event.subtype === 'init') {
+                // 归一化：init/turn_started 的 session 写回 + compact_boundary 用量观察。
+                // 返回 true = 本轮 system.init 已到（调用方置 sawInit，供 pre-init 守卫用）。
+                if (this.maybeSyncSession(event, { activeRun, writeback, usage, runId })) {
                     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);
                 }
+                // pre-init result 守卫（§9.22，observeResultEvent）：resume 重放的陈旧
+                // result 不置 sawResult、不进卡片。
                 if (event.type === 'result') {
                     const outcome = this.observeResultEvent(event, {
                         sawInit,
@@ -1471,11 +1448,12 @@ export class Bridge {
                     // 跳过，在 bridge 层就拦掉可以省下一次无谓的 push + render。
                     if (outcome.dropFromCard) {
                         // 仍然重置 idle 计时——CLI 活着并且在产事件。
-                        watchdog?.touch();
+                        this.handleEventForWatchdog(watchdog);
                         continue;
                     }
                 }
-                // Approval events (Codex app-server mode)
+                // Approval events (Codex app-server mode)。审批先到、item/started 后到的
+                // 乱序流也在此补全（dispatchApprovalEvent 内 updateView）。
                 if (event.type === 'approval_requested' ||
                     event.type === 'approval_resolved' ||
                     event.type === 'approval_view_updated') {
@@ -1485,7 +1463,8 @@ export class Bridge {
                 // lastEventTs 重新武装看门狗。result 后 CLI 进程做 jsonl flush/清理（finalizing
                 // 过渡）期间，宽限期恢复为完整的 idleTimeoutMs，避免已产出结果的 turn 被误标
                 // idle_timeout。旧实现 `else { resetIdle(); }` 漏掉 result 分支。
-                watchdog?.touch();
+                this.handleEventForWatchdog(watchdog);
+                // 渲染：reducer（run-state）在 cardSession.push 内部。
                 await cardSession.push(event);
             }
             getLogger().info(`[lark-remote] runner stream end runId=${runId} sawResult=${sawResult}`);
@@ -1556,6 +1535,48 @@ export class Bridge {
             }
         }
     }
+    /**
+     * 事件循环的看门狗喂狗（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、打上下方终态表情。
      *
@@ -1597,10 +1618,15 @@ export class Bridge {
                     this.sessionStore.getSessionId(ctx.userId, activeRun.agentKind)),
             };
             const finalRender = renderRunCardDetailed(cardSession.currentState, finalRenderOptions);
-            this.rememberRunCardSnapshot(runId, cardSession.currentState, finalRenderOptions, cwd, activeRun.agentKind);
+            const snapshot = this.rememberRunCardSnapshot(runId, cardSession.currentState, finalRenderOptions, cwd, activeRun.agentKind, cardSession.cardMessageId);
             let runCardSent = false;
             if (settleResult === 'unsent') {
-                const sent = await this.sendResult({ card: finalRender.card }, ctx);
+                const sent = await this.sendResult({ card: finalRender.card }, ctx, {
+                    // 兜底发送的卡也要能接收后台任务更新 —— 流式卡没建起来时这是唯一来源。
+                    onCardSent: (messageId) => {
+                        snapshot.messageId = messageId;
+                    },
+                });
                 runCardSent = sent;
             }
             else {
@@ -1618,6 +1644,9 @@ export class Bridge {
             }
             // Add a terminal-state emoji reaction to the user's original message
             this.finishTurnReactions(ctx, terminalReactionEmoji(cardSession.currentState.terminal));
+            // 后台任务跨 turn：卡片收尾只是"这一轮的投影结束了"，任务本身可能还在跑。
+            // 订阅放在最后：卡片已落地，patch 才有落点。
+            this.jobWatch.startBackgroundJobWatch(runId, snapshot, activeRun.runner);
         }
         finally {
             // cleanup must survive mid-finalize errors. The only unguarded
@@ -1633,7 +1662,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
@@ -1731,498 +1760,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