lark-remote 0.1.0

package/dist/bridge/index.js

@@ -0,0 +1,1281 @@
+import { randomUUID } from 'node:crypto';
+import { getLogger } from '../logger/index.js';
+import { RunCardSession } from '../card/run-card-session.js';
+import { renderRunCard } from '../card/run-renderer.js';
+import { renderBashCard } from '../card/bash-renderer.js';
+import { BashCardSession, capBashOutput } from '../card/bash-card-session.js';
+import { markdownDiv } from '../card/collapsible.js';
+import { sessionEventPanel } from '../router/card-helpers.js';
+import { formatUsageStats } from '../router/index.js';
+import { agentDisplayName } from '../card/card-shared.js';
+import { enforceCardBudget } from '../card/card-budget.js';
+import { normalizeResultUsage } from '../runner/common/usage.js';
+import { BashProcessRunner } from '../runner/index.js';
+import { QueueManager, } from './queue-manager.js';
+/**
+ * Max events to read for the completion notification card (mirror router's
+ * AUTO_RESUME_MAX_EVENTS = 5). Without a cap, readSessionContent returns every
+ * event after the last user message and the card blows past Feishu's 28KB
+ * budget (review §P1-21).
+ */
+const COMPLETION_NOTIFICATION_MAX_EVENTS = 5;
+/**
+ * Max idle time (no stdout events) before a claude run is considered hung
+ * (§9.12). When this fires the bridge calls `runner.stop()` to unblock the
+ * serial queue — otherwise a single hung run would block every subsequent
+ * 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',
+};
+function terminalReactionEmoji(terminal) {
+    return TERMINAL_REACTION_EMOJI[terminal] ?? 'Done';
+}
+/**
+ * Bridge owns the per-workspace serial processing queue (§9.6) and the
+ * single-card streaming forwarding loop (§9.12 watchdog + session sync).
+ *
+ * The router delegates non-command messages here via `forwardToClaude` and
+ * sends command results via `sendResult`. Serial processing is enforced per
+ * workspace by `enqueue`: each workspace has its own Promise chain, so at
+ * most one agent process runs per workspace at a time, while different
+ * workspaces run in parallel (see `activeRuns`, §9.6). This is a load-bearing
+ * invariant — concurrent spawns within one workspace would corrupt session
+ * state. Most card actions go through `enqueueImmediate` (fire-and-forget,
+ * outside the serial chain); only run-forwarding is serialized.
+ *
+ * The idle watchdog (§9.12) is also load-bearing: without it a hung agent
+ * process would block its workspace's serial queue forever. Both invariants
+ * now have a single owner (this class) and a test surface via the
+ * Runner/BridgeChannel seams.
+ */
+export class Bridge {
+    runner;
+    connector;
+    sessionStore;
+    config;
+    workspaceStore;
+    idleTimeoutMs;
+    /** Multi-agent registry. */
+    agentRegistry;
+    /** Session reader registry for usage and completion cards. */
+    sessionReaderRegistry;
+    /**
+     * Per-workspace runner instances, keyed by (cwd, agentKind).
+     * Fix 4 (2026-07-18): 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
+     * blocked the queue forever.
+     */
+    runners = new Map();
+    /** Queue manager for per-workspace serial processing queue. */
+    queueManager;
+    /** Active runs per workspace (cwd). Multiple workspaces can run in parallel. */
+    activeRuns = 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
+     * workspace, so they live outside `activeRuns`. Tracked so `/stop` can reach
+     * the per-run BashRunner instance via interruptCurrentRun.
+     */
+    activeBashRuns = new Map();
+    constructor(deps) {
+        this.runner = deps.runner;
+        this.connector = deps.connector;
+        this.sessionStore = deps.sessionStore;
+        this.config = deps.config;
+        this.workspaceStore = deps.workspaceStore;
+        this.idleTimeoutMs = deps.idleTimeoutMs ?? IDLE_TIMEOUT_MS;
+        this.agentRegistry = deps.agentRegistry;
+        this.sessionReaderRegistry = deps.sessionReaderRegistry;
+        this.queueManager = new QueueManager((workspace) => this.activeRuns.has(workspace), (chatId, card, opts) => this.connector.sendWithRetry(chatId, { card }, { replyTo: opts?.replyTo }), (messageId, card) => this.connector.updateCard(messageId, card));
+    }
+    /**
+     * Get or create a runner for the given workspace, keyed by current defaultAgent.
+     *
+     * Fix 4 (2026-07-18): 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.
+     */
+    getRunner(workspace, kind = this.config.defaultAgent) {
+        // Fix 4: Check for runner under (workspace, kind) key
+        const workspaceMap = this.runners.get(workspace);
+        if (workspaceMap?.has(kind)) {
+            return workspaceMap.get(kind);
+        }
+        // Create new runner for this (workspace, kind) slot
+        const runner = this.agentRegistry.get(kind, workspace);
+        // Call lifecycle methods for agent runners created via factory
+        if (runner && typeof runner.killOrphan === 'function') {
+            runner.killOrphan();
+        }
+        if (runner && typeof runner.registerExitHandlers === 'function') {
+            runner.registerExitHandlers();
+        }
+        // Store in nested map: Map<workspace, Map<kind, Runner>>
+        if (!workspaceMap) {
+            this.runners.set(workspace, new Map([[kind, runner]]));
+        }
+        else {
+            workspaceMap.set(kind, runner);
+        }
+        return runner;
+    }
+    /** Update the config reference (call after `/config set` reloads). */
+    setConfig(config) {
+        this.config = config;
+        // 同步更新 registry 的 configContainer，让 factory 能读取最新 config
+        const container = this.agentRegistry.getConfigContainer();
+        if (container) {
+            container.current = config;
+        }
+    }
+    /** Get the current runner for a workspace. Used by router for agent-specific commands (P3.2). */
+    getCurrentRunner(workspace) {
+        return this.getRunner(workspace);
+    }
+    /** 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
+     *  唯一捕获点：排队消息在 T0 把 agent+session 钉进 AgentBinding，随任务闭包带到 T1
+     *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移（方案 D4）。 */
+    currentBinding(userId) {
+        const agent = this.config.defaultAgent;
+        return { agent, sessionId: this.sessionStore.getSessionId(userId, agent) };
+    }
+    /**
+     * Clear all cached runner instances. Call after config changes that affect runner config.
+     */
+    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 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.
+        for (const cwd of [...this.runners.keys()]) {
+            if (this.activeRuns.has(cwd))
+                continue;
+            for (const kind of [...this.runners.get(cwd).keys()]) {
+                this.evictRunnerSlot(cwd, kind);
+            }
+        }
+    }
+    /**
+     * Evict a (cwd, agentKind) runner cache slot. Unregisters the runner from the
+     * process-level exit dispatcher first (P1-1: without removal the singleton
+     * Set<Runner> retains every historical runner instance, so memory still grows
+     * with run count), then deletes the slot. Every runner-discarding path
+     * (clearRunners / finalizeRun / interruptCurrentRun) must go through this.
+     */
+    evictRunnerSlot(cwd, kind) {
+        const workspaceMap = this.runners.get(cwd);
+        if (!workspaceMap)
+            return;
+        const evicted = workspaceMap.get(kind);
+        if (evicted && typeof evicted.unregisterExitHandlers === 'function') {
+            evicted.unregisterExitHandlers();
+        }
+        workspaceMap.delete(kind);
+        if (workspaceMap.size === 0) {
+            this.runners.delete(cwd);
+        }
+    }
+    /**
+     * Update the idle watchdog window at runtime.
+     * Called by router constructor and `config.save` (when `idle.watchdogMinutes` changes
+     * via `/config` card). The idle interval reads `this.idleTimeoutMs` live on every
+     * tick, so the new threshold takes effect immediately for any in-flight run —
+     * there is no per-event timer to reset.
+     */
+    setIdleTimeout(ms) {
+        this.idleTimeoutMs = ms;
+    }
+    /**
+     * Extract agent-specific run options from config.
+     * Returns model/effort/etc. based on current defaultAgent.
+     */
+    getAgentRunOptions(agent = this.config.defaultAgent) {
+        const agents = this.config.agents;
+        const result = {};
+        switch (agent) {
+            case 'claude':
+                // Claude uses top-level claude config
+                if (this.config.claude) {
+                    if (this.config.claude.model)
+                        result.model = this.config.claude.model;
+                    if (this.config.claude.effort)
+                        result.effort = this.config.claude.effort;
+                }
+                break;
+            case 'codex':
+                if (agents?.codex?.model)
+                    result.model = agents.codex.model;
+                if (agents?.codex?.reasoningEffort)
+                    result.reasoningEffort = agents.codex.reasoningEffort;
+                break;
+            case 'pi':
+                if (agents?.pi?.model)
+                    result.model = agents.pi.model;
+                if (agents?.pi?.thinking)
+                    result.thinking = agents.pi.thinking;
+                break;
+            case 'opencode':
+                // opencode model is set as provider/model in the constructor (defaultModel);
+                // returning bare modelID here would override it with a provider-less string.
+                break;
+        }
+        return result;
+    }
+    /**
+     * Enqueue a task into the workspace-level serial bridge queue.
+     * Delegates to QueueManager for actual implementation.
+     */
+    enqueue(workspace, task, opts) {
+        this.queueManager.enqueue(workspace, task, opts);
+    }
+    /**
+     * Execute a task immediately without going through the queue.
+     * Used for / commands that should respond immediately.
+     */
+    enqueueImmediate(workspace, task) {
+        this.queueManager.enqueueImmediate(workspace, task);
+    }
+    /** Get queue info for a workspace. */
+    getQueueInfo(workspace) {
+        return this.queueManager.getQueueInfo(workspace);
+    }
+    /** Remove a task from the queue by messageId. Returns true if found and removed. */
+    removeFromQueue(workspace, messageId) {
+        return this.queueManager.removeFromQueue(workspace, messageId);
+    }
+    /**
+     * One-shot: replace the execution closure of an existing queued task in
+     * place, preserving its queue position. Used by queue.immediate after the
+     * user edits a queued message (see router handleQueueImmediate).
+     */
+    setTaskReplacement(workspace, messageId, task) {
+        this.queueManager.setTaskReplacement(workspace, messageId, task);
+    }
+    /** Update queue card to "cancelled" status when user clicks 撤销. */
+    async updateQueueCardToCancelled(workspace, messageId) {
+        await this.queueManager.updateQueueCardToCancelled(workspace, messageId);
+    }
+    /** Mark a queued task's card as executing immediately (grey out buttons).
+     *  Called by handleQueueImmediate so the user sees feedback right away
+     *  instead of waiting for the queue callback. Idempotent: the queue
+     *  callback's own updateQueueCardToExecuting call becomes a no-op because
+     *  updateQueueCardToExecuting deletes the card-message mapping in finally. */
+    async markQueueCardExecuting(workspace, messageId) {
+        const task = this.getQueuedTask(workspace, messageId);
+        await this.queueManager.updateQueueCardToExecuting(workspace, messageId, task?.messagePreview ?? '', false);
+    }
+    /** Get task metadata from queue. */
+    getQueuedTask(workspace, messageId) {
+        return this.queueManager.getQueuedTask(workspace, messageId);
+    }
+    /**
+     * Whether a task with the given messageId has begun executing and has not
+     * settled yet. Lets handleQueueImmediate's final feedback distinguish a
+     * target that was cancelled from one that began while the interrupt was in
+     * flight (the latter is already running, so the toast must not claim
+     * "未安排执行").
+     */
+    hasTaskBegan(messageId) {
+        return this.queueManager.hasBegan(messageId);
+    }
+    /** Get all queued tasks for a workspace. Returns a copy to prevent aliasing bugs. */
+    getQueuedTasks(workspace) {
+        return this.queueManager.getQueuedTasks(workspace);
+    }
+    /**
+     * Update the messagePreview for a queued task and build the updated queue
+     * card. Returns the card object to send back as the cardAction callback
+     * response (Feishu renders it in place), or null if the task is no longer
+     * queued. Returning the card via the callback response avoids the
+     * PATCH-vs-callback-response race that left the card stuck in edit state.
+     */
+    async updateMessagePreview(workspace, messageId, newMessage) {
+        const updated = this.queueManager.updateQueuedTaskMessage(workspace, messageId, newMessage);
+        if (!updated)
+            return null;
+        return this.queueManager.buildQueueCardForEdit(workspace, messageId, newMessage);
+    }
+    /** Whether a claude run is currently in progress in the given workspace. */
+    isBusyFor(workspace) {
+        return this.activeRuns.has(workspace);
+    }
+    getActiveRunFor(workspace) {
+        const active = this.activeRuns.get(workspace);
+        if (!active)
+            return undefined;
+        const state = active.session.currentState;
+        return {
+            runId: active.runId,
+            userId: active.userId,
+            chatId: active.chatId,
+            cwd: active.cwd,
+            sessionId: state.sessionId,
+            terminal: state.terminal,
+            contextLength: state.contextLength,
+            compactCount: state.compactCount,
+            cacheReadTokens: state.cacheReadTokens,
+            cacheCreationTokens: state.cacheCreationTokens,
+        };
+    }
+    /** Whether any claude run is currently in progress (any workspace). */
+    get isBusy() {
+        return this.activeRuns.size > 0;
+    }
+    /** Get all active runs across all workspaces. */
+    getAllActiveRuns() {
+        const result = new Map();
+        for (const [cwd, active] of this.activeRuns) {
+            result.set(cwd, {
+                runId: active.runId,
+                userId: active.userId,
+                chatId: active.chatId,
+                cwd: active.cwd,
+            });
+        }
+        return result;
+    }
+    /** Get all active runs with their state for /active command (memory-based). */
+    getActiveRuns() {
+        const result = [];
+        for (const [_cwd, active] of this.activeRuns) {
+            const state = active.session.currentState;
+            // Only include non-terminal runs
+            if (state.terminal === 'running' || state.terminal === 'finalizing') {
+                result.push({
+                    runId: active.runId,
+                    sessionId: state.sessionId ?? '',
+                    cwd: active.cwd,
+                    userId: active.userId,
+                    chatId: active.chatId,
+                    terminal: state.terminal,
+                });
+            }
+        }
+        return result;
+    }
+    /** 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) {
+        // Find the active claude run matching this user/chat
+        for (const [cwd, active] of this.activeRuns) {
+            if (input.workspace !== undefined && cwd !== input.workspace)
+                continue;
+            if (active.userId === input.userId && active.chatId === input.chatId) {
+                if (input.runId && active.runId !== input.runId)
+                    continue;
+                getLogger().info(`[bridge] interrupt hit runId=${active.runId} cwd=${cwd} userId=${input.userId}`);
+                // 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).
+                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
+                // to a successor that begins executing before we resume. An
+                // unconditional reset would then zero the successor's count and mark
+                // its slot interrupted, hiding it from queue cards (A22).
+                const stoppedSlot = this.queueManager.getExecutingSlot(cwd);
+                await Promise.allSettled([
+                    active.session.finish('interrupted'),
+                    runner.stop({ immediate: true }),
+                ]);
+                // 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
+                // workspace. Only delete the entry we actually stopped.
+                if (this.activeRuns.get(cwd) === active) {
+                    this.activeRuns.delete(cwd);
+                }
+                // Fix 4: Clean up this specific (cwd, agentKind) runner slot
+                // (P1-1: eviction must also unregister the runner from the exit dispatcher)
+                // P2-3: evict by the run's captured agentKind, not the live
+                // defaultAgent (may have changed mid-run via /config).
+                this.evictRunnerSlot(cwd, active.agentKind);
+                // Reset queue executing count: the task was interrupted externally, so
+                // its promise-chain settle (.then/.catch) may lag behind the process
+                // kill. Without this reset, subsequent messages would incorrectly show
+                // as "排队中". resetExecutingCount also grants a skip-credit so the
+                // stale settle does not double-decrement the count. Centralized here so
+                // ALL interrupt paths (/stop, /t, card stop, queue.immediate) benefit.
+                // When stoppedSlot is undefined (no active run matched), skip the reset —
+                // there is no queue slot to reconcile. All production interrupt paths
+                // (/stop, /t, card stop, queue.immediate) provide a defined stoppedSlot.
+                if (stoppedSlot !== undefined) {
+                    this.queueManager.resetExecutingCount(cwd, stoppedSlot);
+                }
+                getLogger().info(`[bridge] interrupt stop done runId=${active.runId}`);
+                return true;
+            }
+        }
+        // Then check active bash runs (! commands). These bypass the serial queue
+        // and are tracked separately; stop the per-run BashRunner directly.
+        for (const [runId, b] of this.activeBashRuns) {
+            if (input.workspace !== undefined && b.cwd !== input.workspace)
+                continue;
+            if (b.userId === input.userId && b.chatId === input.chatId) {
+                if (input.runId && runId !== input.runId)
+                    continue;
+                getLogger().info(`[bridge] interrupt hit bash runId=${runId} cwd=${b.cwd} userId=${input.userId}`);
+                await b.bashRunner.stop({ immediate: true });
+                // Update card to show interrupted state
+                await b.cardSession.finish('interrupted', { exitCode: -1 });
+                this.activeBashRuns.delete(runId);
+                getLogger().info(`[bridge] interrupt bash stop done runId=${runId}`);
+                return true;
+            }
+        }
+        getLogger().debug(`[bridge] interrupt miss userId=${input.userId}`);
+        return false;
+    }
+    /** Send a result message to the user (§7). Returns true on success, false on failure. */
+    async sendResult(result, ctx) {
+        try {
+            if (result.card) {
+                // 静态卡片体积保护：确保卡片不超过飞书大小限制
+                const { card: safeCard, wasTruncated, reason, bytesBefore, bytesAfter, } = enforceCardBudget(result.card);
+                if (wasTruncated) {
+                    getLogger().info(`[bridge] card size exceeded limit, applied budget enforcement: reason=${reason} bytesBefore=${bytesBefore} bytesAfter=${bytesAfter}`);
+                }
+                getLogger().debug(`[bridge] sendResult kind=card chatId=${ctx.chatId}`);
+                await this.connector.sendWithRetry(ctx.chatId, { card: safeCard }, { replyTo: ctx.messageId });
+                return true;
+            }
+            else if (result.markdown) {
+                getLogger().debug(`[bridge] sendResult kind=markdown chatId=${ctx.chatId}`);
+                await this.connector.sendWithRetry(ctx.chatId, { markdown: result.markdown }, { replyTo: ctx.messageId });
+                return true;
+            }
+            else if (result.text) {
+                getLogger().debug(`[bridge] sendResult kind=text chatId=${ctx.chatId}`);
+                await this.connector.sendWithRetry(ctx.chatId, { text: result.text }, { replyTo: ctx.messageId });
+                return true;
+            }
+            return false;
+        }
+        catch (err) {
+            getLogger().error('[bridge] failed to send result:', err);
+            return false;
+        }
+    }
+    /**
+     * Update an existing card in place (原地更新) instead of sending a new one.
+     *
+     * Used by /config cardAction handlers (config.toggle/set/input/save) so the
+     * user sees the card refresh on the same message bubble rather than getting
+     * a new card per click — same-message-bubble update pattern.
+     *
+     * Falls back to `sendResult` (which sends a new card as reply) when:
+     *   - `messageId` is missing (caller didn't pass ctx.messageId)
+     *   - `connector.updateCard` throws (card was deleted, network error, etc.)
+     *
+     * Returns true if the in-place update succeeded, false if it fell back.
+     */
+    async updateCardInPlace(card, ctx) {
+        if (!ctx.messageId) {
+            getLogger().warn('[bridge] updateCardInPlace missing messageId, falling back to sendResult');
+            await this.sendResult({ card }, ctx);
+            return false;
+        }
+        try {
+            getLogger().debug(`[bridge] updateCardInPlace messageId=${ctx.messageId}`);
+            await this.connector.updateCard(ctx.messageId, card);
+            return true;
+        }
+        catch (err) {
+            getLogger().warn(`[bridge] updateCardInPlace failed, falling back to sendResult: ${err.message}`);
+            await this.sendResult({ card }, ctx);
+            return false;
+        }
+    }
+    /** Send a file to the user via Feishu. */
+    async sendFile(filePath, ctx) {
+        try {
+            getLogger().debug(`[bridge] sendFile path=${filePath} chatId=${ctx.chatId}`);
+            await this.connector.sendFile(ctx.chatId, filePath);
+        }
+        catch (err) {
+            getLogger().error('[bridge] failed to send file:', err);
+            await this.sendResult({ text: `发送文件失败: ${err.message}` }, ctx);
+        }
+    }
+    /** Reconnect the underlying Feishu channel. */
+    async reconnect() {
+        await this.connector.reconnect();
+    }
+    /**
+     * Resolve the working directory for a user.
+     * First checks sessionStore (set by /cd), then falls back to first workspace.
+     * Returns undefined if no cwd is available.
+     */
+    resolveCwd(userId) {
+        const entry = this.sessionStore.get(userId);
+        let cwd = entry?.cwd;
+        if (!cwd && this.workspaceStore) {
+            const workspaces = this.workspaceStore.list();
+            if (workspaces.length > 0) {
+                cwd = workspaces[0][1];
+                getLogger().info(`[bridge] resolveCwd fallback cwd=${cwd} (first saved workspace)`);
+            }
+        }
+        return cwd;
+    }
+    /**
+     * Forward a non-command message to claude.
+     *
+     * Watchdog (§9.12): if no AgentEvent arrives within IDLE_TIMEOUT_MS, the
+     * run is considered hung and `runner.stop()` is called to unblock the
+     * work queue. Session is synced from `system.init`; every renderable event
+     * updates the same run card, and terminal events finalize that card.
+     */
+    async forwardToClaude(message, ctx, opts) {
+        // D5: agentKind 一律来自绑定。无 binding 时保持现状（live defaultAgent）。
+        const agentKind = opts?.binding?.agent ?? this.config.defaultAgent;
+        // P1-14: lane 与执行 cwd 同源。消息入队时（index.ts 闭包）捕获的 workspace
+        // 作为 cwdOverride 显式传入；执行时若 sessionStore cwd 已被 /cd 等命令改写，
+        // 以 lane 为准 —— 否则旧 lane 的排队消息会被 busy-drop 静默丢失。空串视为
+        // 未提供（与入队前无 cwd 的兜底语义一致）。
+        const laneCwd = opts?.cwdOverride;
+        const cwd = laneCwd && laneCwd.length > 0 ? laneCwd : this.resolveCwd(ctx.userId);
+        if (!cwd) {
+            await this.sendResult({ text: '请先使用 /cd <path> 设置工作目录' }, ctx);
+            return;
+        }
+        const entry = this.sessionStore.get(ctx.userId);
+        getLogger().debug(`[bridge] forward entry userId=${ctx.userId} chatId=${ctx.chatId} cwd=${cwd} ` +
+            `agent=${agentKind} sessionId=${opts?.binding?.sessionId ?? entry?.sessions?.get(agentKind) ?? '(none)'} message=${message.slice(0, 100)}`);
+        // Check if current workspace already has a run in progress
+        if (this.activeRuns.has(cwd)) {
+            getLogger().warn(`[bridge] workspace busy, dropping message userId=${ctx.userId} cwd=${cwd}`);
+            await this.sendResult({ text: '此 workspace 正在处理中，请 /stop 后重试' }, ctx);
+            return;
+        }
+        // Note: Multiple workspaces can have runs in parallel. If runner is busy,
+        // runner.run() will throw and we'll catch it below.
+        // D2/D5: sessionId 钉死语义——binding 有 sessionId 时用它（入队时刻快照），
+        // 否则跟随 live store（无 binding 或入队时无 session 的正常路径）。
+        const sessionId = opts?.binding?.sessionId ?? this.sessionStore.getSessionId(ctx.userId, agentKind);
+        // 会话代际快照（2026-08-09）：run 在途时 /new、/cd、/resume 会 bump epoch，
+        // 该 run 后续 system.init 的 sessionId 写回即判 stale 跳过。在执行起点
+        // （而非入队点）捕获，保持 binding「钉死 resume」既有语义。
+        const sessionEpochAtStart = this.sessionStore.getSessionEpoch(ctx.userId, agentKind);
+        // 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).
+        const runner = this.getRunner(cwd, agentKind);
+        // Step 1: Create run session (runId, cardSession, activeRun tracking)
+        const { runId, cardSession, activeRun } = this.createRunSession(ctx, cwd, runner, agentKind);
+        // Step 2: Consume the agent stream (runner.run loop, event processing, state updates)
+        await this.runAgentStreamToEnd(runner, cardSession, sessionId, sessionEpochAtStart, ctx, cwd, runId, message, agentKind);
+        // Step 3: Finalize the run (error handling, fallback card, completion notification, cleanup)
+        await this.finalizeRun(cardSession, activeRun, ctx, cwd);
+    }
+    /**
+     * Step 1 of forwardToClaude: Create run session components.
+     * Returns runId, cardSession, and activeRun object for tracking.
+     */
+    createRunSession(ctx, cwd, runner, agentKind = this.config.defaultAgent) {
+        const runId = randomUUID();
+        getLogger().debug(`[bridge] creating runCard runId=${runId}`);
+        // D5: agentKind 来自入队绑定（forwardToClaude 解析），不再读 live config。
+        // 缓存键 (cwd, agentKind) 和 eviction 都用这个值（review P2-3）。
+        const cardSession = new RunCardSession({
+            connector: this.connector,
+            chatId: ctx.chatId,
+            replyTo: ctx.messageId,
+            runId,
+            renderOptions: {
+                showThinking: this.config.output.showThinking,
+                showToolUse: this.config.output.showToolUse,
+                showToolResult: this.config.output.showToolResult,
+                // Run card header shows the current agent name (e.g. "Claude · 思考中")
+                agentKind,
+            },
+        });
+        const activeRun = {
+            runId,
+            userId: ctx.userId,
+            chatId: ctx.chatId,
+            session: cardSession,
+            cwd,
+            runner,
+            agentKind,
+        };
+        this.activeRuns.set(cwd, activeRun);
+        getLogger().info(`[bridge] activeRuns.set cwd=${cwd} runId=${runId}`);
+        return { runId, cardSession, activeRun };
+    }
+    /**
+     * Step 2 of forwardToClaude: Run the agent and consume its event stream.
+     * Handles idle watchdog, event processing, session sync, and state transitions.
+     */
+    async runAgentStreamToEnd(runner, cardSession, sessionId, sessionEpochAtStart, ctx, cwd, runId, message, agentKind = this.config.defaultAgent) {
+        // P2-1: idle watchdog 用单 interval + lastEventTs 截止时间判定，而非每事件
+        // clearTimeout + setTimeout 重建 timer。高频事件流下 timer 重建次数与事件数
+        // 成正比（N 事件 = N 次 setTimeout + N 个闭包/秒）；interval 方案只建一个
+        // interval，事件到来时仅刷新时间戳（无 timer 操作）。语义不变：事件流停滞
+        // 超过 idleTimeoutMs 仍触发 runner.stop()（§9.12）。
+        let lastEventTs = Date.now();
+        let idleInterval = null;
+        let sawResult = false;
+        // 记录 result 是否为 error: error 时跳过 jsonl usage 读取 (见 stream end 处说明)
+        let resultWasError = false;
+        // Final usage read from jsonl after the run completes. live stream-json does
+        // not emit compact_boundary, so the live contextLength is unreliable.
+        let finalContextLength;
+        let finalCompactCount;
+        let finalCacheReadTokens;
+        let finalCacheCreationTokens;
+        let finalTotalTokens;
+        // Real input/output tokens captured from the live result event (codex/
+        // opencode carry them in ResultEvent.usage). Threaded to the card so the
+        // done card shows real values instead of the 10% estimate.
+        let liveInputTokens;
+        let liveOutputTokens;
+        // Final input/output for the done card: live value wins (codex/opencode
+        // carry per-run usage in the result event); jsonl is the fallback for
+        // agents whose live stream has no usage (kimi).
+        let finalInputTokens;
+        let finalOutputTokens;
+        // Session-cumulative input/output (all runs) read from jsonl; threaded to
+        // the done card's "累计" display. Always from jsonl (live has no cumulative).
+        let finalCumulativeTotalTokens;
+        let finalCumulativeInputTokens;
+        let finalCumulativeOutputTokens;
+        let finalCumulativeCacheReadTokens;
+        let finalCumulativeCacheCreationTokens;
+        try {
+            try {
+                getLogger().debug(`[bridge] cardSession.start() begin runId=${runId}`);
+                await cardSession.start();
+                getLogger().info(`[bridge] cardSession.start() ok runId=${runId}`);
+            }
+            catch (err) {
+                getLogger().warn('[bridge] 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).
+            }
+            if (cardSession.currentState.terminal !== 'running') {
+                // Card session did not enter running state - still try to send static fallback
+                getLogger().info(`[bridge] cardSession not running, using static fallback`);
+            }
+            // P2-1: 单 interval 看门狗。事件到来时只刷新 lastEventTs（无 timer 操作）；
+            // interval 周期检查 `now - lastEventTs > idleTimeoutMs`，超时才触发 stop。
+            // 这样高频事件流下 timer 重建次数与事件数解耦（只建一个 interval），而
+            // "15min 无事件即 stop" 的语义不变（§9.12）。周期取 idleTimeoutMs/2，使停滞
+            // 后最多在 1.5× idleTimeoutMs 内触发（半个窗口延迟，watchdog 语义可接受）。
+            const fireIdleTimeout = () => {
+                if (idleInterval)
+                    clearInterval(idleInterval);
+                idleInterval = null;
+                getLogger().warn(`[bridge] claude idle timeout, stopping process runId=${runId}`);
+                void Promise.allSettled([
+                    cardSession.finish('idle_timeout', {
+                        idleTimeoutMinutes: Math.max(1, Math.round(this.idleTimeoutMs / 60_000)),
+                    }),
+                    runner.stop(),
+                ]);
+            };
+            const resetIdle = () => {
+                lastEventTs = Date.now();
+            };
+            if (this.idleTimeoutMs > 0) {
+                const tickMs = Math.max(1, Math.floor(this.idleTimeoutMs / 2));
+                idleInterval = setInterval(() => {
+                    if (Date.now() - lastEventTs > this.idleTimeoutMs) {
+                        fireIdleTimeout();
+                    }
+                }, tickMs);
+            }
+            resetIdle();
+            let contextLength;
+            getLogger().info(`[bridge] 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 };
+            for await (const event of runner.run(message, runOpts)) {
+                // 只有终态才阻止事件处理。finalizing 是非终态，应该继续处理
+                // 这样在 result 事件后，后台任务输出仍能被正确处理
+                const terminal = cardSession.currentState.terminal;
+                if (terminal === 'done' ||
+                    terminal === 'error' ||
+                    terminal === 'interrupted' ||
+                    terminal === 'idle_timeout') {
+                    continue;
+                }
+                if (event.type === 'system' && event.subtype === 'init') {
+                    // 代际守卫：run 在途时 /new（或 new-session 卡片、/cd、/resume、
+                    // /config 切换）移动了 session 指针，此 init 的写回是 stale 的——
+                    // 跳过，否则 /new 的清空会被在途 run 静默撤销（2026-08-09 事故：
+                    // task-notification 注入触发 Claude 重发 init，e8defc46 复活）。
+                    const pointerMoved = this.sessionStore.getSessionEpoch(ctx.userId, agentKind) !== sessionEpochAtStart;
+                    if (pointerMoved) {
+                        getLogger().info(`[bridge] system.init write-back skipped: session pointer moved since run start runId=${runId} sessionId=${event.session_id}`);
+                    }
+                    else {
+                        // L5: Use session's real directory from event.cwd (not runner's cwd parameter)
+                        // L3: guard empty string too -- `??` only catches null/undefined, but a
+                        // translator (or older build) may emit cwd="", which must NOT overwrite
+                        // the good runner cwd.
+                        const hasCwd = !!this.sessionStore.getCwd(ctx.userId);
+                        const realCwd = event.cwd && event.cwd.length > 0 ? event.cwd : cwd;
+                        if (hasCwd && event.cwd && event.cwd !== cwd) {
+                            // Session has its own cwd (e.g. EnterWorktree relocate). Keep the
+                            // workspace cwd unchanged; record the session's actual cwd in sessionCwds.
+                            getLogger().info(`[bridge] system.init: workspace cwd=${cwd}, session cwd=${event.cwd}`);
+                            this.sessionStore.setSessionIdAndSessionCwd(ctx.userId, agentKind, event.session_id, realCwd);
+                        }
+                        else {
+                            // First use (no workspace cwd yet) or event.cwd matches runner cwd:
+                            // set sessionId + cwd as before; on first use also bootstrap sessionCwds.
+                            const bootstrapSessionCwd = !hasCwd && event.cwd && event.cwd.length > 0 ? event.cwd : undefined;
+                            this.sessionStore.setSessionIdAndCwd(ctx.userId, agentKind, event.session_id, realCwd, bootstrapSessionCwd);
+                        }
+                    }
+                    getLogger().info(`[bridge] system.init received runId=${runId} sessionId=${event.session_id} cwd=${event.cwd}`);
+                }
+                // Track context length from compaction events
+                if (event.type === 'system' &&
+                    event.subtype === 'compact_boundary' &&
+                    event.compactMetadata) {
+                    contextLength = event.compactMetadata.postTokens;
+                }
+                if (event.type === 'result') {
+                    sawResult = true;
+                    resultWasError = event.subtype === 'error';
+                    getLogger().info(`[bridge] result event received runId=${runId}`);
+                    // result 后进入 finalizing 非终态（暂存 subtype/errorMsg），由 for-await
+                    // 自然结束后在 finally 转 done/error。提取 usage 信息。
+                    if (event.usage) {
+                        const u = normalizeResultUsage(event.usage);
+                        // input_tokens is non-cached (ccusage-aligned), so the context
+                        // length fallback must include cached tokens. Prefer the agent's
+                        // declared total; otherwise reconstruct from the parts.
+                        if (!contextLength) {
+                            contextLength = u.contextLength;
+                        }
+                        // Capture real input/output for the done card (avoiding the 10%
+                        // estimate in formatUsageStats). live 值优先：有 live input/output 时
+                        // 所有 flow 字段统一用 live scope（本 run），避免同一张卡片上
+                        // Input/Output 是本 run、Cache/Total 是 session 累计的混 scope 问题。
+                        liveInputTokens = u.inputTokens;
+                        liveOutputTokens = u.outputTokens;
+                        if (u.cacheReadTokens !== undefined) {
+                            finalCacheReadTokens = u.cacheReadTokens;
+                        }
+                        if (u.cacheCreationTokens !== undefined) {
+                            finalCacheCreationTokens = u.cacheCreationTokens;
+                        }
+                        if (u.totalTokens !== undefined) {
+                            finalTotalTokens = u.totalTokens;
+                        }
+                    }
+                }
+                // §9.12 红线（§P1-2 方案 A）：每个事件（含 result）无条件刷新
+                // lastEventTs 重新武装看门狗。result 后 CLI 进程做 jsonl flush/清理（finalizing
+                // 过渡）期间，宽限期恢复为完整的 idleTimeoutMs，避免已产出结果的 turn 被误标
+                // idle_timeout。旧实现 `else { resetIdle(); }` 漏掉 result 分支。
+                resetIdle();
+                await cardSession.push(event);
+            }
+            getLogger().info(`[bridge] runner stream end runId=${runId} sawResult=${sawResult}`);
+            // §9.12 红线（§P1-2 方案 A 第 2 点）：for-await 自然结束 = CLI 已退出，
+            // 看门狗使命结束，立即摘除 interval（不再等 finally），堵掉「stream 已结束、
+            // 收尾处理跨过死线被误标 idle_timeout」的同源小窗口（P2-4 随本修复一并关闭）。
+            if (idleInterval) {
+                clearInterval(idleInterval);
+                idleInterval = null;
+            }
+            // 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 (若有)。
+            const finalSessionId = this.sessionStore.getSessionId(ctx.userId, agentKind);
+            const finalUsage = resultWasError
+                ? undefined
+                : this.resolveFinalUsage(finalSessionId, cwd, agentKind);
+            finalContextLength = finalUsage?.contextLength ?? contextLength;
+            finalCompactCount = finalUsage?.compactCount;
+            finalCumulativeTotalTokens = finalUsage?.cumulativeTotalTokens;
+            finalCumulativeInputTokens = finalUsage?.cumulativeInputTokens;
+            finalCumulativeOutputTokens = finalUsage?.cumulativeOutputTokens;
+            finalCumulativeCacheReadTokens = finalUsage?.cumulativeCacheReadTokens;
+            finalCumulativeCacheCreationTokens = finalUsage?.cumulativeCacheCreationTokens;
+            // 统一 flow 字段 scope：live 优先（非 codex），jsonl 兜底；codex 例外。
+            // 当 live result 事件带了 input/output（即 liveInputTokens/liveOutputTokens
+            // 非 undefined），所有 flow 字段统一用 live scope（本 run），不用 jsonl
+            // 的 session 累计值覆盖，避免 cache%/Total 分子分母不同源。
+            // 无 live usage 时（如 kimi），jsonl 值兜底。
+            // codex 例外（2026-08-01）：codex exec 的 turn.completed.usage 是会话累计
+            // total_token_usage（resume 长会话下虚高数百倍），不是本 run 增量——live
+            // 值必须被忽略，flow 字段一律取 jsonl 主线程文件的 per-turn 值；
+            // jsonl 缺失（老版本无 token_count）时才回退 live。
+            // contextLength/compactCount 保持 jsonl 优先（它们是水位/历史计数）。
+            const codexJsonlFirst = agentKind === 'codex';
+            if (!codexJsonlFirst && liveInputTokens !== undefined && liveOutputTokens !== undefined) {
+                // 非 codex 且 live 有 input/output → 所有 flow 字段用 live scope
+                finalInputTokens = liveInputTokens;
+                finalOutputTokens = liveOutputTokens;
+                // cacheReadTokens/cacheCreationTokens/totalTokens
+                // 已在上面 result 事件处理中赋了 live 值；若 live 没有则为 undefined，
+                // 由 formatUsageStats 的 max/兜底公式处理。
+            }
+            else {
+                // codex（jsonl 优先）或无 live usage → jsonl 兜底所有 flow 字段
+                finalInputTokens = finalUsage?.inputTokens ?? liveInputTokens;
+                finalOutputTokens = finalUsage?.outputTokens ?? liveOutputTokens;
+                finalCacheReadTokens = finalUsage?.cacheReadTokens ?? finalCacheReadTokens;
+                finalCacheCreationTokens = finalUsage?.cacheCreationTokens ?? finalCacheCreationTokens;
+                finalTotalTokens = finalUsage?.totalTokens ?? finalTotalTokens;
+            }
+            getLogger().info(`[bridge] final usage runId=${runId} contextLength=${finalContextLength} compactCount=${finalCompactCount ?? 'undefined'} cacheRead=${finalCacheReadTokens ?? 'undefined'} cacheCreate=${finalCacheCreationTokens ?? 'undefined'}`);
+            // for-await 自然结束 = stream 关闭 = CLI 进程退出。
+            // 进程退出（for-await end）= 唯一终态触发源。
+            // 1) finalizing（result 已收到）-> 转 done/error + usage meta
+            // 2) running（未收到 result）-> 错误路径
+            // 3) 已终态 + sawResult -> 补充 usage meta（不改 terminal）
+            const finalState = cardSession.currentState;
+            if (finalState.terminal === 'finalizing') {
+                const isError = finalState.resultSubtype === 'error' || !!finalState.errorMsg;
+                await cardSession.finish(isError ? 'error' : 'done', {
+                    resultSubtype: finalState.resultSubtype,
+                    errorMsg: finalState.errorMsg,
+                    contextLength: finalContextLength,
+                    compactCount: finalCompactCount,
+                    cacheReadTokens: finalCacheReadTokens,
+                    cacheCreationTokens: finalCacheCreationTokens,
+                    totalTokens: finalTotalTokens,
+                    inputTokens: finalInputTokens,
+                    outputTokens: finalOutputTokens,
+                    cumulativeTotalTokens: finalCumulativeTotalTokens,
+                    cumulativeInputTokens: finalCumulativeInputTokens,
+                    cumulativeOutputTokens: finalCumulativeOutputTokens,
+                    cumulativeCacheReadTokens: finalCumulativeCacheReadTokens,
+                    cumulativeCacheCreationTokens: finalCumulativeCacheCreationTokens,
+                });
+            }
+            else if (finalState.terminal === 'running') {
+                await cardSession.finish('error', {
+                    contextLength: finalContextLength,
+                    compactCount: finalCompactCount,
+                    cacheReadTokens: finalCacheReadTokens,
+                    cacheCreationTokens: finalCacheCreationTokens,
+                    totalTokens: finalTotalTokens,
+                    inputTokens: finalInputTokens,
+                    outputTokens: finalOutputTokens,
+                    cumulativeTotalTokens: finalCumulativeTotalTokens,
+                    cumulativeInputTokens: finalCumulativeInputTokens,
+                    cumulativeOutputTokens: finalCumulativeOutputTokens,
+                    cumulativeCacheReadTokens: finalCumulativeCacheReadTokens,
+                    cumulativeCacheCreationTokens: finalCumulativeCacheCreationTokens,
+                    errorMsg: agentDisplayName(agentKind) + ' 输出流已结束，但未收到 result 事件',
+                });
+            }
+            else if (sawResult) {
+                // 已终态（interrupted/idle_timeout）+ result 已收到：首终态优先，
+                // 仅补充 usage meta（finalizing 期间被 /stop 或 idle 超时也展示 token 统计）
+                await cardSession.finish(finalState.terminal, {
+                    contextLength: finalContextLength,
+                    compactCount: finalCompactCount,
+                    cacheReadTokens: finalCacheReadTokens,
+                    cacheCreationTokens: finalCacheCreationTokens,
+                    totalTokens: finalTotalTokens,
+                    inputTokens: finalInputTokens,
+                    outputTokens: finalOutputTokens,
+                    cumulativeTotalTokens: finalCumulativeTotalTokens,
+                    cumulativeInputTokens: finalCumulativeInputTokens,
+                    cumulativeOutputTokens: finalCumulativeOutputTokens,
+                    cumulativeCacheReadTokens: finalCumulativeCacheReadTokens,
+                    cumulativeCacheCreationTokens: finalCumulativeCacheCreationTokens,
+                });
+            }
+            // else: 已终态且未收到 result（如 spawn 失败后 interrupted）-> 无 usage 可补，跳过
+        }
+        catch (err) {
+            getLogger().error(`[bridge] claude run error runId=${runId}:`, err);
+            // P1-11 双保险：run() 的 finally 已负责杀子进程，但 catch 路径再补一次
+            // runner.stop()（与 bash 路径对齐），覆盖任何 finally 之外的残留窗口。
+            try {
+                await runner.stop();
+            }
+            catch (stopErr) {
+                getLogger().warn(`[bridge] runner stop failed:`, stopErr);
+            }
+            // 终态守卫：running 或 finalizing（非终态）-> 转 error；
+            // 已终态（interrupted/idle_timeout/done/error）-> 保留首终态，仅补充 usage。
+            const catchTerminal = cardSession.currentState.terminal;
+            if (catchTerminal === 'running' || catchTerminal === 'finalizing') {
+                await cardSession.finish('error', {
+                    contextLength: finalContextLength,
+                    compactCount: finalCompactCount,
+                    cacheReadTokens: finalCacheReadTokens,
+                    cacheCreationTokens: finalCacheCreationTokens,
+                    totalTokens: finalTotalTokens,
+                    inputTokens: liveInputTokens,
+                    outputTokens: liveOutputTokens,
+                    cumulativeTotalTokens: finalCumulativeTotalTokens,
+                    cumulativeInputTokens: finalCumulativeInputTokens,
+                    cumulativeOutputTokens: finalCumulativeOutputTokens,
+                    errorMsg: errorMessage(err),
+                });
+            }
+            else {
+                getLogger().info(`[bridge] skip error finish: state already terminal (${catchTerminal}) runId=${runId}`);
+                if (sawResult) {
+                    await cardSession.finish(catchTerminal, {
+                        contextLength: finalContextLength,
+                        compactCount: finalCompactCount,
+                        cacheReadTokens: finalCacheReadTokens,
+                        cacheCreationTokens: finalCacheCreationTokens,
+                        totalTokens: finalTotalTokens,
+                        inputTokens: finalInputTokens,
+                        outputTokens: finalOutputTokens,
+                        cumulativeTotalTokens: finalCumulativeTotalTokens,
+                        cumulativeInputTokens: finalCumulativeInputTokens,
+                        cumulativeOutputTokens: finalCumulativeOutputTokens,
+                        cumulativeCacheReadTokens: finalCumulativeCacheReadTokens,
+                        cumulativeCacheCreationTokens: finalCumulativeCacheCreationTokens,
+                    });
+                }
+            }
+        }
+        finally {
+            if (idleInterval)
+                clearInterval(idleInterval);
+        }
+    }
+    /**
+     * Step 3 of forwardToClaude: Finalize the run.
+     * Handles fallback card sending, completion notification, and cleanup.
+     */
+    async finalizeRun(cardSession, activeRun, ctx, cwd) {
+        const runId = activeRun.runId;
+        try {
+            getLogger().debug(`[bridge] finally settle runId=${runId} state.terminal=${cardSession.currentState.terminal}`);
+            const settleResult = await cardSession.settle();
+            let runCardSent = false;
+            if (settleResult === 'unsent') {
+                const sent = await this.sendResult({
+                    card: renderRunCard(cardSession.currentState, {
+                        showThinking: this.config.output.showThinking,
+                        showToolUse: this.config.output.showToolUse,
+                        showToolResult: this.config.output.showToolResult,
+                        agentKind: activeRun.agentKind,
+                    }),
+                }, ctx);
+                runCardSent = sent;
+            }
+            else {
+                // streaming succeeded: run card is the last message in the chat
+                // runCardSent stays false - streaming card exists but no new card sent
+            }
+            // Send a notification card when a fallback card was sent (unsent case)
+            // but NOT when streaming succeeded (card already shows completion).
+            const sessionId = cardSession.currentState.sessionId;
+            if (sessionId && runCardSent) {
+                await this.sendCompletionNotificationCard(sessionId, cwd, ctx, activeRun.agentKind);
+            }
+            // Add a terminal-state emoji reaction to the user's original message
+            void this.connector.addReaction(ctx.messageId, terminalReactionEmoji(cardSession.currentState.terminal));
+        }
+        finally {
+            // P1-13: cleanup must survive mid-finalize errors. The only unguarded
+            // expression in finalizeRun is the renderRunCard(...) argument evaluated
+            // at the sendResult call site; if it throws, the run must still release
+            // its activeRuns slot — otherwise the workspace is permanently busy
+            // (every later message busy-dropped until a manual /stop).
+            if (this.activeRuns.get(cwd) === activeRun) {
+                this.activeRuns.delete(cwd);
+                // Also clean up the runner to prevent memory leak
+                // Fix 4: Clean up this specific (cwd, agentKind) runner slot.
+                // (P1-1: eviction must also unregister the runner from the exit dispatcher)
+                // P2-3: evict by the run's captured agentKind, not the live
+                // defaultAgent — switching agent mid-run (via /config, whose
+                // clearRunners skips the active cwd) would otherwise delete the new
+                // agent's slot (no-op) and leave the original runner lingering.
+                this.evictRunnerSlot(cwd, activeRun.agentKind);
+                getLogger().info(`[bridge] activeRuns.delete cwd=${cwd} runId=${runId}`);
+            }
+        }
+    }
+    /**
+     * Read final usage (contextLength + compactCount + cache tokens) from the session jsonl.
+     * Called after a run finishes: live stream-json does not emit compact_boundary,
+     * so the live contextLength (fallback to result.usage input+output) is
+     * unreliable. The jsonl is authoritative for postTokens + compact event count.
+     */
+    resolveFinalUsage(sessionId, cwd, agentKind = this.config.defaultAgent) {
+        if (!sessionId)
+            return undefined;
+        try {
+            const content = this.sessionReaderRegistry.get(agentKind).readSessionContent(sessionId, cwd);
+            if (!content.usage) {
+                // EnterWorktree relocate (2026-08-04): jsonl read silently returned no
+                // usage (e.g. transcript moved mid-session). Surface it so token-stat
+                // fallback to per-run live usage is visible in logs, not silent.
+                getLogger().warn(`[bridge] resolveFinalUsage: no usage from jsonl sessionId=${sessionId} cwd=${cwd} agent=${agentKind}, card falls back to per-run live usage`);
+            }
+            return content.usage
+                ? {
+                    contextLength: content.usage.contextLength,
+                    compactCount: content.usage.compactCount,
+                    cacheReadTokens: content.usage.cacheReadTokens,
+                    cacheCreationTokens: content.usage.cacheCreationTokens,
+                    totalTokens: content.usage.totalTokens,
+                    inputTokens: content.usage.inputTokens,
+                    outputTokens: content.usage.outputTokens,
+                    cumulativeTotalTokens: content.usage.cumulativeTotalTokens,
+                    cumulativeInputTokens: content.usage.cumulativeInputTokens,
+                    cumulativeOutputTokens: content.usage.cumulativeOutputTokens,
+                    cumulativeCacheReadTokens: content.usage.cumulativeCacheReadTokens,
+                    cumulativeCacheCreationTokens: content.usage.cumulativeCacheCreationTokens,
+                }
+                : undefined;
+        }
+        catch (err) {
+            getLogger().warn(`[bridge] resolveFinalUsage failed sessionId=${sessionId}: ${errorMessage(err)}`);
+            return undefined;
+        }
+    }
+    /**
+     * Send a notification card when a run completes.
+     * This card contains the session summary and a button to resume the session.
+     * It's sent as a new message (not updating the run card) so users can easily
+     * find and return to this session without scrolling up.
+     */
+    async sendCompletionNotificationCard(sessionId, cwd, ctx, agentKind = this.config.defaultAgent) {
+        try {
+            // P1-21: cap the events read for the notification card — without
+            // maxEvents claude returns every event after the last user message and
+            // the card blows past Feishu's 28KB budget.
+            const content = this.sessionReaderRegistry.get(agentKind).readSessionContent(sessionId, cwd, {
+                maxEvents: COMPLETION_NOTIFICATION_MAX_EVENTS,
+            });
+            const { events, usage } = content;
+            const elements = [
+                markdownDiv(`📂 \`${cwd}\`\n会话: **${sessionId}**`),
+                { tag: 'hr' },
+            ];
+            // Add session content in collapsible panels (last 2 expanded)
+            events.forEach((ev, i) => {
+                elements.push(sessionEventPanel(ev, i, events.length, 2, agentKind));
+            });
+            // Add usage stats at the end
+            const usageStatsStr = formatUsageStats(usage, { showResult: true, result: 'completed' });
+            if (usage) {
+                elements.push(markdownDiv(usageStatsStr));
+            }
+            // Add action button to resume this session - use column_set+column for 2.0
+            elements.push({
+                tag: 'column_set',
+                columns: [
+                    {
+                        tag: 'column',
+                        width: 'auto',
+                        elements: [
+                            {
+                                tag: 'button',
+                                text: { tag: 'plain_text', content: '🔁 切换到此会话' },
+                                type: 'primary',
+                                behaviors: [{ type: 'callback', value: { cmd: 'resume.use', sessionId } }],
+                            },
+                        ],
+                    },
+                ],
+            });
+            const card = {
+                schema: '2.0',
+                config: { wide_screen_mode: true },
+                header: {
+                    template: 'green',
+                    title: {
+                        tag: 'plain_text',
+                        content: '✅ 会话已完成',
+                    },
+                },
+                body: { elements },
+            };
+            // P1-21: send through sendResult so enforceCardBudget guards the card
+            // (previously sent via connector directly, bypassing the budget — long
+            // sessions produced >28KB cards that Feishu silently rejected).
+            const sent = await this.sendResult({ card }, ctx);
+            if (sent) {
+                getLogger().debug(`[bridge] completion notification sent sessionId=${sessionId} chatId=${ctx.chatId}`);
+            }
+            else {
+                getLogger().warn(`[bridge] failed to send completion notification card sessionId=${sessionId}`);
+            }
+        }
+        catch (err) {
+            getLogger().warn(`[bridge] failed to send completion notification card:`, err);
+        }
+    }
+    /**
+     * 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`.
+     */
+    async executeBash(command, ctx) {
+        const cwd = this.resolveCwd(ctx.userId);
+        getLogger().info(`[bridge] executeBash start userId=${ctx.userId} sessionCwd=${this.sessionStore.get(ctx.userId)?.cwd} command="${command.slice(0, 30)}..."`);
+        if (!cwd) {
+            getLogger().info(`[bridge] executeBash no cwd, sending error`);
+            await this.sendResult({ text: '请先使用 /cd <path> 设置工作目录，或保存一个 workspace (/ws save <name>)' }, ctx);
+            return;
+        }
+        getLogger().info(`[bridge] 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(`[bridge] 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 workspace, 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(`[bridge] executeBashInternal about to start stream chatId=${ctx.chatId} messageId=${ctx.messageId}`);
+            try {
+                await cardSession.start();
+                getLogger().info(`[bridge] executeBash stream started runId=${runId}`);
+            }
+            catch (err) {
+                getLogger().warn('[bridge] bash card stream unavailable:', err);
+            }
+            for await (const event of bashRunner.run(command, { cwd })) {
+                if (event.type === 'stdout') {
+                    // P1-4 层④：bridge 本地 output 也必须 store-time 截断——仅 session state
+                    // 有界并不会让 `output +=` 自然有界（review 第④条表述不成立），!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(`[bridge] 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(`[bridge] 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 (M2: avoid 2.0→1.x downgrade).
+                try {
+                    await this.connector.sendWithRetry(ctx.chatId, { card: renderBashCard(cardSession.currentState, {}) }, { replyTo: ctx.messageId });
+                }
+                catch {
+                    /* ignore fallback errors */
+                }
+            }
+            if (this.activeBashRuns.has(runId)) {
+                this.activeBashRuns.delete(runId);
+                getLogger().info(`[bridge] executeBash done runId=${runId} exitCode=${exitCode}`);
+            }
+            // Add a Done emoji reaction to the user's original message to signal completion
+            void this.connector.addReaction(ctx.messageId, 'Done');
+        }
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=index.js.map