lark-remote 0.5.17 → 0.5.19

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.19] - 2026-11-03
+
+### 修复
+
+- **run 结束后卡片不再停在「运行中」**：卡片上的最后一帧只是交给飞书通道的节流队列，`controller.update()` 返回时 `message.patch` 还没发出；流若在下一次节流到期前关闭，这一帧可能永远不出门——run 早就结束，卡上仍画着运行态、底部「⏹ 停止」按钮一直挂着，点下去也不会生效。现在终态之后补一次整卡 patch 把它钉死（幂等替换，一次 run 只多一次请求，运行卡与后台任务卡共用同一份实现），并在日志里区分「帧没发出去」与「发出去了飞书没刷新」
+- **卡片上的「⏹ 停止」按钮不再因为按钮值过期而空转**：停止动作携带的是本次 run 的 id，一旦这个值缺失或过期，点击就匹配不到任何 run。现在 id 精确匹配仍是权威路径，匹配不上时只在「被点的这张卡就是当前活跃的 run 卡」的前提下按卡片身份兜底；历史卡片和 `/active` 这类汇总卡片依旧不接受兜底，防止借一张旧卡停掉新 run。匹配失败时会把请求的 run id、卡片标识与当前活跃 run 记入日志，便于复盘
+- **终态卡的「后台任务」小节跟着任务真实状态更新**：这一小节原本是结果那一刻的名单快照，之后运行卡停止接收事件、卡片定稿成静态内容，任务后来结束没有任何更新来源——卡上一直写「运行中」并留着必然失败的停止按钮，用户只能靠点一下看它报错才知道任务没了。现在收尾后按 run 订阅整份任务名单，只有名单变化才更新同一张卡片；已结束的任务显式标出并撤掉停止按钮，计数按 运行中 / 状态未知 / 已结束 分列；订阅中断而任务尚未结算时标「状态未知」（监控中断不等于任务结束）；更新失败只退订，绝不因此补发新卡刷屏
+
+### 维护
+
+- **Windows 的参数直传分支补上用例，CI 两个 job 都跑覆盖率**：shell 后端此前只测了拼接命令行那条路径，argv 原样透传（不拼 shell 字符串）、找不到 Git Bash 时报专用错误而不是泛化执行原命令、以及强制隐藏控制台窗口都没有守卫。顺带让 CI 的 Linux 与 Windows 两个 job 都以覆盖率方式运行测试。无行为变化
+- **解释故障为什么存在的注释改为自描述**：若干注释用「某次实机反馈 + 隔了多久还能点」来论证改动的必要性，这类叙述对读者既不是可复现步骤也不是阈值，改成直接描述故障形态与后果；通道契约、根因和退订条件原样保留。无行为变化
+
+## [0.5.18] - 2026-11-02
+
+### 修复
+
+- **超长最终回答不再在卡片里被拦腰截断**：运行卡的状态层对正文有 12,000 字符的窗口，此前这个窗口对**最新一条**正文同样生效，超出窗口的回答只剩尾部一截、还从句子中间开始。现在最新一条正文不设窗口（它就是要展示的输出），只有被更晚的正文顶替之后才按窗口截断留痕；回合结束时优先采用运行器手里的完整正文——DSH 在回合结束交出整条 assistant 消息，不依赖增量拼接，重连丢帧也不缺头。六个 agent 各用自己的真实转换器回放同一篇超长回答做回归
+- **表格超限不再被误判成「卡片装不下」而重复补发完整回答**：最终回答里的表格超过单卡上限时，渲染器只是省略最旧的几张并在原位留一句提示，正文其实完整地画在了卡上；此前这句提示被当成溢出信号，卡片照常渲染正文之外又补发一条「完整回答」，同一篇回答用户看到两遍。现在正文仍在卡内一律按「完整」上报，只有正文真被占位替代时才走补发通道
+- **DSH 自动恢复不再选中子 agent 派生会话**：DSH 0.2.x 把子 agent 派生的会话也列进会话列表（同一个工作目录、更新时间取委托结束时刻，常比父会话还新），按「最新会话」自动恢复于是选中了它；这类会话不接受按顶层会话寻址，读取被服务端拒绝后又被吞成空事件——切换工作目录后的恢复卡只剩一行标题，还绑在一个续跑不了的会话上，下一条消息必然报错。现在列表与寻址统一排除这类会话（判定只认来源标记：会话 id 的形态和父会话字段都会误伤正常会话）
+
+### 变更
+
+- **完整回答溢出改走 Markdown 文件，最终回答不再发纯文本**：正文装不进一张卡时，把完整回答逐字写成临时 `.md` 文件随卡片发出，发送后尽力清理；卡上的提示改为「完整内容见随附的 Markdown 文件」。原先拆成「完整回答（1/N）」多条纯文本有两个硬伤：与卡片正文重复，且丢掉表格与代码块结构。文件发送失败时只发提示卡，并在日志里留落盘路径
+
+### 维护
+
+- **用例头注释不再点名已删除的测试文件**：15 个锚点用例头部的「合并自 …」列的是早前测试收敛时删掉的旧文件名，读者按名去找会落到不存在的路径；只保留「本文件覆盖什么」，需要指路的改指向仍然存在的共享 fixture。无行为变化
+
 ## [0.5.17] - 2026-11-01
 
 ### 维护

package/dist/bridge/index.d.ts

@@ -172,6 +172,20 @@ export declare class Bridge {
      */
     private runCardSnapshots;
     private static readonly RUN_CARD_SNAPSHOT_MAX;
+    /**
+     * 终态卡后台任务订阅（runId → 中止句柄）。
+     *
+     * 与卡片快照同生命周期：快照被淘汰、任务全结束、patch 失败时退订。上限天然
+     * 受 RUN_CARD_SNAPSHOT_MAX 约束（一张卡最多一条流）。
+     */
+    private jobWatches;
+    /**
+     * 同一张卡的 patch 串行链（runId → 链尾）。
+     *
+     * 「停止按钮」和「订阅帧」都会改同一张终态卡：不串行化时两条 PATCH 并发，
+     * 后发先至的那条会把卡片写回旧内容（任务又变回「运行中」）。
+     */
+    private jobCardPatches;
     /**
      * 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
@@ -344,6 +358,8 @@ export declare class Bridge {
         userId: string;
         chatId: string;
         runId?: string;
+        /** Card callback's server-provided message id. */
+        cardMessageId?: string;
         /** Restrict the match to a single cwd (queue.immediate). When
          * omitted, all workspaces are candidates (used by /stop, /t, and card stop button which don't know which cwd to target). */
         cwd?: string;
@@ -360,8 +376,20 @@ export declare class Bridge {
         userId: string;
         chatId: string;
         runId?: string;
+        /**
+         * Card callback's server-provided message id. Used only as a narrow fallback
+         * when the behavior-value runId is missing or stale: the clicked card must
+         * be the one active run's card. A dashboard or historical card never matches.
+         */
+        cardMessageId?: string;
         cwd?: string;
     }): Promise<InterruptOutcome>;
+    /**
+     * 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.
+     */
+    private activeRunsForCard;
     /**
      * 停掉一条已注册的 active run：置终态、停 runner、摘槽位、标 stale、
      * 归零该 cwd 的队列执行计数。返回 runner 的停止结果（DSH 才有）。
@@ -370,14 +398,24 @@ export declare class Bridge {
      * 出现「停第一条就 return」的漏停。
      */
     private interruptActiveRun;
-    /** Send a result message to the user (§7). Returns true on success, false on failure. */
-    sendResult(result: CommandResult, ctx: CommandContext): Promise<boolean>;
     /**
-     * Deliver a final answer that cannot fit in the run card. Plain text avoids
-     * markdown parser limits and preserves every character; sequence labels make
-     * multi-message delivery unambiguous.
+     * Send a result message to the user (§7). Returns true on success, false on failure.
+     *
+     * `opts.onCardSent` 回传卡片的 messageId：终态卡收尾后还要靠它接收后台任务
+     * 更新（流式卡从 `cardSession.cardMessageId` 取，兜底发送只能从这里拿）。
      */
-    private sendFinalAnswerOverflow;
+    sendResult(result: CommandResult, ctx: CommandContext, opts?: {
+        onCardSent?: (messageId: string) => void;
+    }): Promise<boolean>;
+    /**
+     * Deliver a final answer that cannot fit in the run card as a Markdown file
+     * attachment. 卡片正文已被标记替代，文件是唯一的内容通道；此处绝不发纯文本
+     * （2026-11-02 定规：纯文本与卡片重复，也丢 Markdown 结构）。
+     *
+     * 失败时发一张提示卡（不是纯文本），并把完整回答留在临时文件里记日志，
+     * 便于事后找回。
+     */
+    private sendFinalAnswerFile;
     /**
      * Update an existing card in place (原地更新) instead of sending a new one.
      *
@@ -410,6 +448,8 @@ export declare class Bridge {
      * 与 activeRuns 生命周期在同一个地方收口。
      */
     private rememberRunCardSnapshot;
+    /** 退订一张终态卡的后台任务名单（幂等）。 */
+    private stopJobWatch;
     /**
      * 停止终态卡上的一个后台任务。
      *
@@ -419,6 +459,26 @@ export declare class Bridge {
      * 会留在卡片上而任务早已结束。
      */
     killBackgroundJob(runId: string, jobId: string, ctx: CommandContext): Promise<boolean>;
+    /**
+     * 让终态卡的后台任务小节跟着宿主继续更新。
+     *
+     * run 的卡片在 `result` 那一帧就关闭了，但后台任务还能再跑很久：不订阅，
+     * 卡片会一直写「运行中」并留着停止按钮，点了必然失败。退订条件写
+     * 在 {@link consumeJobRoster} 里——名单清空、patch 失败、订阅中断、快照被
+     * 淘汰，任一命中即退出；**绝不因为 patch 失败补发新卡**。
+     */
+    private startBackgroundJobWatch;
+    /** 消费宿主推来的整份任务名单，直到全结束 / 流断 / patch 失败 / 外部退订。 */
+    private consumeJobRoster;
+    /** 订阅断了但任务仍未结算：把在跑的任务标成「状态未知」并重渲染一次。 */
+    private markJobsUnknown;
+    /**
+     * 一张终态卡的 PATCH 串行链。
+     *
+     * 渲染放在链内执行（`task` 里读 `snapshot.state`），后入链的任务必然看到更新
+     * 后的状态；否则「停止」与「订阅帧」并发时卡片可能回退。
+     */
+    private enqueueJobCardPatch;
     /** Send a file to the user via Feishu. */
     sendFile(filePath: string, ctx: CommandContext): Promise<void>;
     /**

package/dist/bridge/index.js

@@ -5,10 +5,11 @@ 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 { splitFinalAnswer } from '../card/final-answer-overflow.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 { isLiveBackgroundJob, isRunActive, isRunTerminal, markBackgroundJobsUnknown, removeBackgroundJob, syncBackgroundJobs, } 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';
@@ -193,6 +194,20 @@ export class Bridge {
      */
     runCardSnapshots = new Map();
     static RUN_CARD_SNAPSHOT_MAX = 8;
+    /**
+     * 终态卡后台任务订阅（runId → 中止句柄）。
+     *
+     * 与卡片快照同生命周期：快照被淘汰、任务全结束、patch 失败时退订。上限天然
+     * 受 RUN_CARD_SNAPSHOT_MAX 约束（一张卡最多一条流）。
+     */
+    jobWatches = new Map();
+    /**
+     * 同一张卡的 patch 串行链（runId → 链尾）。
+     *
+     * 「停止按钮」和「订阅帧」都会改同一张终态卡：不串行化时两条 PATCH 并发，
+     * 后发先至的那条会把卡片写回旧内容（任务又变回「运行中」）。
+     */
+    jobCardPatches = new Map();
     /**
      * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
      * queue and may run in parallel with claude runs / other bash runs in the same
@@ -663,15 +678,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;
@@ -694,15 +725,25 @@ export class Bridge {
         // `!` 命令也要停——旧实现命中 claude run 就 return，这些 bash 会被漏掉。
         // 带范围的中断（停止卡 runId、queue.immediate 的 cwd）保持旧语义：只有
         // 没有 claude run 命中时才回退到 bash，避免误杀用户并行跑的 `!` 任务。
-        const includeBashRuns = (input.runId === undefined && input.cwd === undefined) || activeTargets.length === 0;
+        const cardScoped = input.runId !== undefined || input.cardMessageId !== undefined;
+        const includeBashRuns = (input.runId === undefined && input.cardMessageId === undefined && input.cwd === undefined) ||
+            activeTargets.length === 0;
         const bashTargets = includeBashRuns
             ? [...this.activeBashRuns.entries()].filter(([runId, b]) => {
                 if (input.cwd !== undefined && b.cwd !== input.cwd)
                     return false;
                 if (b.userId !== input.userId || b.chatId !== input.chatId)
                     return false;
-                if (input.runId && runId !== input.runId)
-                    return false;
+                if (input.runId) {
+                    if (runId === input.runId)
+                        return true;
+                    // Scoped card clicks may fall back only through their own card id.
+                    if (cardScoped)
+                        return false;
+                }
+                if (input.cardMessageId) {
+                    return b.cardSession.cardMessageId === input.cardMessageId;
+                }
                 return true;
             })
             : [];
@@ -718,7 +759,10 @@ export class Bridge {
             stoppedCount++;
         }
         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 {
@@ -728,6 +772,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 才有）。
@@ -802,8 +866,13 @@ export class Bridge {
         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) {
                 // 静态卡片体积保护：确保卡片不超过飞书大小限制
@@ -812,7 +881,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) {
@@ -842,26 +912,26 @@ export class Bridge {
         }
     }
     /**
-     * Deliver a final answer that cannot fit in the run card. Plain text avoids
-     * markdown parser limits and preserves every character; sequence labels make
-     * multi-message delivery unambiguous.
+     * Deliver a final answer that cannot fit in the run card as a Markdown file
+     * attachment. 卡片正文已被标记替代，文件是唯一的内容通道；此处绝不发纯文本
+     * （2026-11-02 定规：纯文本与卡片重复，也丢 Markdown 结构）。
+     *
+     * 失败时发一张提示卡（不是纯文本），并把完整回答留在临时文件里记日志，
+     * 便于事后找回。
      */
-    async sendFinalAnswerOverflow(text, ctx) {
-        const chunks = splitFinalAnswer(text);
+    async sendFinalAnswerFile(text, ctx) {
+        let filePath;
         try {
-            for (let i = 0; i < chunks.length; i++) {
-                const prefix = chunks.length > 1 ? `完整回答（${i + 1}/${chunks.length}）\n\n` : '完整回答\n\n';
-                await this.connector.sendWithRetry(ctx.chatId, { text: prefix + chunks[i] }, { replyTo: ctx.messageId });
-            }
+            filePath = writeFinalAnswerFile(text);
+            await this.connector.sendFile(ctx.chatId, filePath);
         }
         catch (err) {
-            getLogger().error('[lark-remote] failed to deliver complete final answer:', err);
-            try {
-                await this.connector.sendWithRetry(ctx.chatId, { text: `⚠️ 完整回答补发失败：${errorMessage(err)}` }, { replyTo: ctx.messageId });
-            }
-            catch (fallbackErr) {
-                getLogger().error('[lark-remote] final-answer failure notice also failed:', fallbackErr);
-            }
+            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);
         }
     }
     /**
@@ -924,14 +994,30 @@ 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.stopJobWatch(oldest);
         }
+        return snapshot;
+    }
+    /** 退订一张终态卡的后台任务名单（幂等）。 */
+    stopJobWatch(runId) {
+        this.jobWatches.get(runId)?.abort();
+        this.jobWatches.delete(runId);
+        this.jobCardPatches.delete(runId);
     }
     /**
      * 停止终态卡上的一个后台任务。
@@ -953,9 +1039,105 @@ export class Bridge {
         if (!killed)
             return false;
         snapshot.state = removeBackgroundJob(snapshot.state, jobId);
-        await this.updateCardInPlace(renderRunCard(snapshot.state, snapshot.options), ctx);
+        // 与订阅帧共用一条串行链：两条 PATCH 并发时，后发先至的那条会把卡片写回
+        // 旧内容（刚停掉的任务又显示成「运行中」）。
+        await this.enqueueJobCardPatch(runId, async () => {
+            await this.updateCardInPlace(renderRunCard(snapshot.state, snapshot.options), ctx);
+            return true;
+        });
+        // 卡片上已经没有在跑的任务：不必再等宿主推下一帧，直接退订。
+        if (!(snapshot.state.backgroundJobs ?? []).some(isLiveBackgroundJob)) {
+            this.stopJobWatch(runId);
+        }
         return true;
     }
+    /**
+     * 让终态卡的后台任务小节跟着宿主继续更新。
+     *
+     * run 的卡片在 `result` 那一帧就关闭了，但后台任务还能再跑很久：不订阅，
+     * 卡片会一直写「运行中」并留着停止按钮，点了必然失败。退订条件写
+     * 在 {@link consumeJobRoster} 里——名单清空、patch 失败、订阅中断、快照被
+     * 淘汰，任一命中即退出；**绝不因为 patch 失败补发新卡**。
+     */
+    startBackgroundJobWatch(runId, snapshot, runner) {
+        const live = (snapshot.state.backgroundJobs ?? []).some(isLiveBackgroundJob);
+        if (!live)
+            return;
+        const sessionId = snapshot.state.sessionId;
+        const messageId = snapshot.messageId;
+        const watchJobs = runner.watchJobs;
+        if (!sessionId || !messageId || typeof watchJobs !== 'function') {
+            // 没有卡 id 就没有 patch 的落点：保留收尾快照，不另发一张卡。
+            getLogger().info(`[lark-remote] background jobs stay on the turn snapshot runId=${runId} ` +
+                `(sessionId=${sessionId ?? '-'} messageId=${messageId ?? '-'} watchable=${typeof watchJobs === 'function'})`);
+            return;
+        }
+        const controller = new AbortController();
+        this.jobWatches.set(runId, controller);
+        void this.consumeJobRoster(runId, snapshot, controller, (signal) => watchJobs.call(runner, sessionId, signal));
+    }
+    /** 消费宿主推来的整份任务名单，直到全结束 / 流断 / patch 失败 / 外部退订。 */
+    async consumeJobRoster(runId, snapshot, controller, watch) {
+        const messageId = snapshot.messageId;
+        if (!messageId)
+            return;
+        let allEnded = false;
+        try {
+            for await (const roster of watch(controller.signal)) {
+                const next = syncBackgroundJobs(snapshot.state, roster);
+                // 名单没变化就不打 PATCH：宿主可能重复推同一份。
+                if (next === snapshot.state)
+                    continue;
+                snapshot.state = next;
+                const ok = await this.enqueueJobCardPatch(runId, () => this.patchCard(messageId, renderRunCard(snapshot.state, snapshot.options)));
+                if (!ok) {
+                    getLogger().warn(`[lark-remote] background job card update failed, stop watching runId=${runId}`);
+                    return;
+                }
+                if (!(snapshot.state.backgroundJobs ?? []).some(isLiveBackgroundJob)) {
+                    allEnded = true;
+                    return;
+                }
+            }
+        }
+        catch (err) {
+            if (!controller.signal.aborted) {
+                getLogger().warn(`[lark-remote] background job watch failed runId=${runId}: ${errorMessage(err)}`);
+            }
+        }
+        finally {
+            const externallyAborted = controller.signal.aborted;
+            controller.abort();
+            // 流断了而任务没结算：监控中断 ≠ 任务结束，标成未知而不是继续写「运行中」。
+            if (!allEnded && !externallyAborted)
+                await this.markJobsUnknown(runId, snapshot);
+            this.jobWatches.delete(runId);
+            this.jobCardPatches.delete(runId);
+        }
+    }
+    /** 订阅断了但任务仍未结算：把在跑的任务标成「状态未知」并重渲染一次。 */
+    async markJobsUnknown(runId, snapshot) {
+        const next = markBackgroundJobsUnknown(snapshot.state);
+        if (next === snapshot.state)
+            return;
+        snapshot.state = next;
+        const messageId = snapshot.messageId;
+        if (!messageId)
+            return;
+        await this.enqueueJobCardPatch(runId, () => this.patchCard(messageId, renderRunCard(snapshot.state, snapshot.options)));
+    }
+    /**
+     * 一张终态卡的 PATCH 串行链。
+     *
+     * 渲染放在链内执行（`task` 里读 `snapshot.state`），后入链的任务必然看到更新
+     * 后的状态；否则「停止」与「订阅帧」并发时卡片可能回退。
+     */
+    enqueueJobCardPatch(runId, task) {
+        const previous = this.jobCardPatches.get(runId) ?? Promise.resolve();
+        const next = previous.then(task, task);
+        this.jobCardPatches.set(runId, next.then(() => undefined, () => undefined));
+        return next;
+    }
     /** Send a file to the user via Feishu. */
     async sendFile(filePath, ctx) {
         try {
@@ -1596,10 +1778,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 {
@@ -1613,10 +1800,13 @@ export class Bridge {
                 await this.sendCompletionNotificationCard(sessionId, cwd, ctx, activeRun.agentKind, cardSession.currentState.terminal);
             }
             if (finalRender.finalAnswerStatus === 'overflow' && finalRender.finalAnswerText) {
-                await this.sendFinalAnswerOverflow(finalRender.finalAnswerText, ctx);
+                await this.sendFinalAnswerFile(finalRender.finalAnswerText, ctx);
             }
             // Add a terminal-state emoji reaction to the user's original message
             this.finishTurnReactions(ctx, terminalReactionEmoji(cardSession.currentState.terminal));
+            // 后台任务跨 turn：卡片收尾只是"这一轮的投影结束了"，任务本身可能还在跑。
+            // 订阅放在最后：卡片已落地，patch 才有落点。
+            this.startBackgroundJobWatch(runId, snapshot, activeRun.runner);
         }
         finally {
             // cleanup must survive mid-finalize errors. The only unguarded

package/dist/card/bash-card-session.js

@@ -86,6 +86,8 @@ export class BashCardSession extends CardSession {
             ...(meta.output !== undefined ? { output: capBashOutput(meta.output) } : {}),
         };
         await this.updateCard();
+        // 同 run 卡：终态帧必须真的落地，否则停止后卡片仍显示停止按钮。
+        await this.confirmTerminalFrame(`runId=${this.state.runId} terminal=${terminal}`);
         this.release();
     }
     /**

package/dist/card/card-session.d.ts

@@ -99,6 +99,9 @@ export declare abstract class CardSession<S, RO = unknown> {
      *  in-flight flush 完成后该事件无 follow-up render，停留为 stale 中间帧。
      *  finally 检查此标志后重新 scheduleFlush，保证 in-flight 期间累积的事件最终被渲染。 */
     private pendingReschedule;
+    /** 终态帧是否已由 confirmTerminalFrame 确认落到飞书。settle 的兜底 patch
+     *  据此去重：流异常结束时若终态帧已经确认过，再 patch 一次只是幂等重发。 */
+    private terminalFrameConfirmed;
     /** 当前 in-flight flush 的 promise（若 flush 正在 await updateCard）。
      *  finish() 在终态 patch 前 await 它，保证 in-flight 的 pre-terminal patch 先落地、
      *  terminal patch 后落地——否则两条 controller.update 并发无 FIFO，
@@ -121,5 +124,19 @@ export declare abstract class CardSession<S, RO = unknown> {
     protected updateCard(): Promise<void>;
     private waitForControllerReady;
     protected prepareTerminalUpdate(): Promise<void>;
+    /**
+     * 把终态帧真正钉到飞书上。
+     *
+     * `controller.update()` 只把帧交给 @larksuite/channel 的 throttle/queue，
+     * resolve 时 `message.patch` 还没发出（见 `connector/index.ts` 的
+     * patchWithRetry 注释）。流若在下一次 throttle 到期前关闭，这一帧就可能
+     * 永远不出门——卡片停在运行态、底部「⏹ 停止」按钮还在：停止其实已经
+     * 生效，按钮仍可点，点了是空转。
+     *
+     * 终态后再走一次整卡 patch（幂等替换；一次 run 只多一次请求），成功打
+     * info 便于排障时区分「帧没发出去」与「发出去了飞书没刷」；失败只 warn，
+     * 不参与收尾决策——流本身已结束，不能让一次兜底 patch 把 finish 拖成异常。
+     */
+    protected confirmTerminalFrame(label: string): Promise<void>;
     protected release(): void;
 }

package/dist/card/card-session.js

@@ -128,6 +128,9 @@ export class CardSession {
      *  in-flight flush 完成后该事件无 follow-up render，停留为 stale 中间帧。
      *  finally 检查此标志后重新 scheduleFlush，保证 in-flight 期间累积的事件最终被渲染。 */
     pendingReschedule = false;
+    /** 终态帧是否已由 confirmTerminalFrame 确认落到飞书。settle 的兜底 patch
+     *  据此去重：流异常结束时若终态帧已经确认过，再 patch 一次只是幂等重发。 */
+    terminalFrameConfirmed = false;
     /** 当前 in-flight flush 的 promise（若 flush 正在 await updateCard）。
      *  finish() 在终态 patch 前 await 它，保证 in-flight 的 pre-terminal patch 先落地、
      *  terminal patch 后落地——否则两条 controller.update 并发无 FIFO，
@@ -185,6 +188,11 @@ export class CardSession {
         getLogger().warn(`${this.logPrefix} stream did not complete cleanly:`, outcome.error);
         if (!this.messageId)
             return 'unsent';
+        // 终态帧已在 finish 里确认落地：兜底 patch 是幂等重发，跳过。
+        // 仍返回 'streamed' 而非 'unsent'——卡片确实已带终态内容，调用方不能
+        // 因此再发一张 fallback 卡（bridge 只对 'unsent' 兜底）。
+        if (this.terminalFrameConfirmed)
+            return 'streamed';
         try {
             await this.connector.updateCard(this.messageId, this.renderCurrentCard());
             return 'updated';
@@ -247,6 +255,33 @@ export class CardSession {
         if (this.flushP)
             await this.flushP;
     }
+    /**
+     * 把终态帧真正钉到飞书上。
+     *
+     * `controller.update()` 只把帧交给 @larksuite/channel 的 throttle/queue，
+     * resolve 时 `message.patch` 还没发出（见 `connector/index.ts` 的
+     * patchWithRetry 注释）。流若在下一次 throttle 到期前关闭，这一帧就可能
+     * 永远不出门——卡片停在运行态、底部「⏹ 停止」按钮还在：停止其实已经
+     * 生效，按钮仍可点，点了是空转。
+     *
+     * 终态后再走一次整卡 patch（幂等替换；一次 run 只多一次请求），成功打
+     * info 便于排障时区分「帧没发出去」与「发出去了飞书没刷」；失败只 warn，
+     * 不参与收尾决策——流本身已结束，不能让一次兜底 patch 把 finish 拖成异常。
+     */
+    async confirmTerminalFrame(label) {
+        const messageId = this.messageId;
+        // 没拿到 messageId（流未建立/已降级）时无从 patch，交回 settle() 的兜底。
+        if (!messageId)
+            return;
+        try {
+            await this.connector.updateCard(messageId, this.renderCurrentCard());
+            this.terminalFrameConfirmed = true;
+            getLogger().info(`${this.logPrefix} terminal frame confirmed ${label} messageId=${messageId}`);
+        }
+        catch (error) {
+            getLogger().warn(`${this.logPrefix} terminal frame confirm failed ${label}:`, error);
+        }
+    }
     release() {
         if (this.released)
             return;

package/dist/card/final-answer-file.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 把完整回答写进系统临时目录里的 `.md` 文件，返回绝对路径。
+ *
+ * 文件名带时间戳与随机后缀：同一分钟内的多个 run 不会互相覆盖，也不会在
+ * 飞书里显示成同名附件。内容逐字写入，不做任何截断或转义。
+ */
+export declare function writeFinalAnswerFile(text: string, now?: Date): string;
+/** 文件通道失败时的提示卡——终态反馈也只走卡片，不发纯文本。 */
+export declare function finalAnswerFileFailureCard(message: string): object;