lark-remote 0.5.18 → 0.5.19

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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
 
 ### 修复

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,8 +398,15 @@ 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>;
+    /**
+     * Send a result message to the user (§7). Returns true on success, false on failure.
+     *
+     * `opts.onCardSent` 回传卡片的 messageId：终态卡收尾后还要靠它接收后台任务
+     * 更新（流式卡从 `cardSession.cardMessageId` 取，兜底发送只能从这里拿）。
+     */
+    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. 卡片正文已被标记替代，文件是唯一的内容通道；此处绝不发纯文本
@@ -413,6 +448,8 @@ export declare class Bridge {
      * 与 activeRuns 生命周期在同一个地方收口。
      */
     private rememberRunCardSnapshot;
+    /** 退订一张终态卡的后台任务名单（幂等）。 */
+    private stopJobWatch;
     /**
      * 停止终态卡上的一个后台任务。
      *
@@ -422,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

@@ -9,7 +9,7 @@ import { writeFinalAnswerFile, finalAnswerFileFailureCard } from '../card/final-
 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';
@@ -194,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
@@ -664,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;
@@ -695,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;
             })
             : [];
@@ -719,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 {
@@ -729,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 才有）。
@@ -803,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) {
                 // 静态卡片体积保护：确保卡片不超过飞书大小限制
@@ -813,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) {
@@ -925,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);
     }
     /**
      * 停止终态卡上的一个后台任务。
@@ -954,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 {
@@ -1597,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 {
@@ -1618,6 +1804,9 @@ export class Bridge {
             }
             // Add a terminal-state emoji reaction to the user's original message
             this.finishTurnReactions(ctx, terminalReactionEmoji(cardSession.currentState.terminal));
+            // 后台任务跨 turn：卡片收尾只是"这一轮的投影结束了"，任务本身可能还在跑。
+            // 订阅放在最后：卡片已落地，patch 才有落点。
+            this.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/run-card-session.js

@@ -50,6 +50,8 @@ export class RunCardSession extends CardSession {
         await this.prepareTerminalUpdate();
         this.state = finishRun(this.state, terminal, meta);
         await this.updateCard();
+        // 终态帧必须真的落地（throttle 通道 resolve 时 patch 还没发）。
+        await this.confirmTerminalFrame(`runId=${this.state.runId} terminal=${this.state.terminal}`);
         this.release();
     }
 }

package/dist/card/run-renderer.js

@@ -1,4 +1,4 @@
-import { isRunActive, isRunTerminal, } from './run-state.js';
+import { isLiveBackgroundJob, isRunActive, isRunTerminal, } from './run-state.js';
 import { terminalToColor, terminalToLabel, newSessionButton, stopButton, compactButton, cardButton, agentDisplayName, } from './card-shared.js';
 import { collapsibleMarkdownPanel, markdownDiv } from './collapsible.js';
 import { toolBodyMd, toolHeaderText } from './tool-render.js';
@@ -1202,11 +1202,26 @@ const BACKGROUND_JOB_INLINE_MAX = 36;
 const BACKGROUND_JOB_FOLD_DISPLAY_MAX = 180;
 const BACKGROUND_JOB_FOLD_LINES = 6;
 /**
- * 任务状态标签：目前 DSH 只会给 running/stopping，其他值按运行中处理。
+ * 任务状态标签：宿主的两态 + 桥侧观测出的「已结束 / 状态未知」。
+ *
+ * 「已结束」不是可有可无的修饰：卡片上曾经只有「运行中/停止中」，任务跑完之
+ * 后卡片仍然这么写，用户只能靠点一次停止按钮看它报错来判断任务是否还在。
  */
 function backgroundJobStatusLabel(status) {
+    if (status === 'ended')
+        return '已结束';
+    if (status === 'unknown')
+        return '状态未知';
     return status === 'stopping' ? '停止中' : '运行中';
 }
+/** 行尾状态（live 任务返回空串：运行中本来就是默认状态）。 */
+function backgroundJobStatusTail(status) {
+    if (status === 'ended')
+        return '✅ 已结束';
+    if (status === 'unknown')
+        return '⚠️ 状态未知';
+    return '';
+}
 /**
  * 生成能包住任意反引号串的代码围栏。命令里的 shell 反引号不能替换成 `'`
  * （那是改内容），只能选比内容里最长反引号串更长的围栏。
@@ -1244,24 +1259,40 @@ function buildBackgroundJobsSection(state) {
     const jobs = state.backgroundJobs ?? [];
     if (jobs.length === 0)
         return [];
-    const elements = [
-        markdownDiv(`🧵 **后台任务** ${jobs.length} 个仍在运行`),
-        markdownDiv('_本轮结束后继续，可逐个停止_', 'notation'),
-    ];
-    jobs.slice(0, MAX_BACKGROUND_JOB_LINES).forEach((job, index) => {
+    // 仍在跑的排前面：用户最先要知道的是"哪些还在占资源"。
+    const running = jobs.filter((job) => isLiveBackgroundJob(job));
+    const unknown = jobs.filter((job) => job.status === 'unknown');
+    const ended = jobs.filter((job) => !isLiveBackgroundJob(job) && job.status !== 'unknown');
+    const ordered = [...running, ...unknown, ...ended];
+    // 计数逐维列出：只说「N 个任务」会让"都还在跑"与"都结束了"读起来一样。
+    const counts = [];
+    if (running.length > 0)
+        counts.push(`${running.length} 个仍在运行`);
+    if (unknown.length > 0)
+        counts.push(`${unknown.length} 个状态未知`);
+    if (ended.length > 0)
+        counts.push(`${ended.length} 个已结束`);
+    const headline = ended.length === jobs.length ? '已全部结束' : counts.join(' · ');
+    const elements = [markdownDiv(`🧵 **后台任务** ${headline}`)];
+    if (running.length + unknown.length > 0) {
+        elements.push(markdownDiv('_本轮结束后继续，可逐个停止_', 'notation'));
+    }
+    ordered.slice(0, MAX_BACKGROUND_JOB_LINES).forEach((job, index) => {
         const label = job.label.trim();
+        const tail = backgroundJobStatusTail(job.status);
         const lineCount = label === '' ? 0 : label.split(/\r?\n/).length;
         const inline = label.length > 0 &&
             lineCount === 1 &&
             !label.includes('`') &&
             displayWidth(label) <= BACKGROUND_JOB_INLINE_MAX;
         if (inline) {
-            elements.push(markdownDiv(`· \`${label}\``));
+            elements.push(markdownDiv(`· \`${label}\`${tail ? ` · ${tail}` : ''}`));
         }
         else {
             // 多行/超宽/含反引号：代码块保留完整命令；只有超长才折叠。
+            // 命令原文一个字都不改，状态出现在围栏之后。
             const fence = codeFenceFor(label);
-            const content = `${fence}\n${label}\n${fence}`;
+            const content = `${fence}\n${label}\n${fence}${tail ? `\n\n${tail}` : ''}`;
             const fold = lineCount > BACKGROUND_JOB_FOLD_LINES ||
                 displayWidth(label) > BACKGROUND_JOB_FOLD_DISPLAY_MAX;
             elements.push(fold
@@ -1274,6 +1305,9 @@ function buildBackgroundJobsSection(state) {
                 })
                 : markdownDiv(content));
         }
+        // 已结束的任务不再给停止入口——那个按钮点下去只会回「可能已自行结束」。
+        if (job.status === 'ended')
+            return;
         elements.push({
             tag: 'column_set',
             columns: [

package/dist/card/run-state.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent, ApprovalView, ToolHint, GoalView } from '../runner/index.js';
+import type { AgentEvent, BackgroundJobRoster, ApprovalView, ToolHint, GoalView } from '../runner/index.js';
 import type { UsageSnapshot } from '../session-contract.js';
 export type RunTerminal = 'running' | 'finalizing' | 'done' | 'error' | 'interrupted' | 'idle_timeout'
 /**
@@ -172,13 +172,11 @@ export interface RunState extends UsageSnapshot {
     /**
      * run 结束时仍在后台运行的任务。跨 turn 生命周期：卡片必须说清楚"这一轮
      * 结束了，但还有东西在跑"，并给出逐个停止的入口。
+     *
+     * 收尾之后这份名单仍会被 `syncBackgroundJobs` 更新（宿主会继续推送任务
+     * 生命周期），所以它是"最后一次观测到的名单"，不是"收尾那一刻的名单"。
      */
-    backgroundJobs?: Array<{
-        id: string;
-        label: string;
-        status?: string;
-        progress?: string;
-    }>;
+    backgroundJobs?: BackgroundJobRoster[];
     /**
      * 会话级长期目标（DSH goal）。跨 turn 生命周期：goal 仍 active 时，本轮结束
      * 只是"一轮结束"，宿主会自动续跑，卡片必须显示目标是什么、跑到第几轮。
@@ -208,5 +206,34 @@ export declare function reduceRunState(state: RunState, event: AgentEvent): RunS
  * 写成「整体重建」，字段一多就会漏带。
  */
 export declare function removeBackgroundJob(state: RunState, jobId: string): RunState;
+/**
+ * 该任务是否仍在跑（`ended` / `unknown` 都不算）。
+ *
+ * 卡片据此决定要不要渲染「⏹ 停止」：给已经结束的任务留一个点了必然失败的
+ * 按钮，等于逼用户拿「停止」当查询用。
+ */
+export declare function isLiveBackgroundJob(job: BackgroundJobRoster): boolean;
+/**
+ * 收尾后把宿主推来的整份任务名单同步进终态卡状态。
+ *
+ * 与 reducer 的分工：reducer 处理的是"收尾那一刻的名单"，只在 run 还在消费
+ * 事件时有效；终态之后 `reduceRunState` 直接早退（终态幂等），名单只能由
+ * 这里更新。
+ *
+ * 三条规则：
+ * - 名单里消失 = 宿主已结算（`job/list` 是整份替换，摘掉即结束）→ `ended`；
+ * - 名单里还在、宿主却给了终态词 → `ended`（有些宿主会把已结束的行留在名单里）；
+ * - `ended` 是终态，不回退成 running —— 同一个 job id 不会重新开始跑。
+ *
+ * 无变化时返回**同一个 state 引用**：bridge 靠它跳过无谓的卡片 patch。
+ */
+export declare function syncBackgroundJobs(state: RunState, roster: ReadonlyArray<BackgroundJobRoster>): RunState;
+/**
+ * 订阅断了但任务仍未结算：把在跑的任务标成「状态未知」。
+ *
+ * 监控中断不等于任务结束——不标出来，卡片又会退化成"最后一次观测当现状"，
+ * 正是这次要修的那个缺陷。未知态仍保留停止按钮（用户还能尝试停掉）。
+ */
+export declare function markBackgroundJobsUnknown(state: RunState): RunState;
 export declare function finishRun(state: RunState, terminal: RunFinalTerminal, meta?: FinishMeta): RunState;
 export {};

package/dist/card/run-state.js

@@ -460,6 +460,95 @@ export function removeBackgroundJob(state, jobId) {
         backgroundJobs: (state.backgroundJobs ?? []).filter((job) => job.id !== jobId),
     };
 }
+/** 宿主仍在执行的任务状态词。状态缺失也算在跑——它还在名单上。 */
+const RUNNING_JOB_STATUSES = new Set(['running', 'stopping']);
+/**
+ * 该任务是否仍在跑（`ended` / `unknown` 都不算）。
+ *
+ * 卡片据此决定要不要渲染「⏹ 停止」：给已经结束的任务留一个点了必然失败的
+ * 按钮，等于逼用户拿「停止」当查询用。
+ */
+export function isLiveBackgroundJob(job) {
+    return job.status === undefined || RUNNING_JOB_STATUSES.has(job.status);
+}
+/** 宿主状态 → 桥侧状态：仍在跑的保留原词，其余已知终态归一成 `ended`。 */
+function bridgeJobStatus(status) {
+    return RUNNING_JOB_STATUSES.has(status) ? status : 'ended';
+}
+/**
+ * 收尾后把宿主推来的整份任务名单同步进终态卡状态。
+ *
+ * 与 reducer 的分工：reducer 处理的是"收尾那一刻的名单"，只在 run 还在消费
+ * 事件时有效；终态之后 `reduceRunState` 直接早退（终态幂等），名单只能由
+ * 这里更新。
+ *
+ * 三条规则：
+ * - 名单里消失 = 宿主已结算（`job/list` 是整份替换，摘掉即结束）→ `ended`；
+ * - 名单里还在、宿主却给了终态词 → `ended`（有些宿主会把已结束的行留在名单里）；
+ * - `ended` 是终态，不回退成 running —— 同一个 job id 不会重新开始跑。
+ *
+ * 无变化时返回**同一个 state 引用**：bridge 靠它跳过无谓的卡片 patch。
+ */
+export function syncBackgroundJobs(state, roster) {
+    const tracked = state.backgroundJobs ?? [];
+    const byId = new Map(roster.map((job) => [job.id, job]));
+    const next = tracked.map((job) => {
+        const row = byId.get(job.id);
+        if (!row)
+            return job.status === 'ended' ? job : { ...job, status: 'ended' };
+        if (job.status === 'ended')
+            return job;
+        const status = row.status === undefined ? job.status : bridgeJobStatus(row.status);
+        const label = row.label.trim() === '' ? job.label : row.label;
+        const progress = row.progress ?? job.progress;
+        if (status === job.status && label === job.label && progress === job.progress)
+            return job;
+        return {
+            ...job,
+            label,
+            ...(status === undefined ? {} : { status }),
+            ...(progress === undefined ? {} : { progress }),
+        };
+    });
+    // 新出现的任务只收仍在跑的：与收尾采集同一口径（列出已结束的任务只会被
+    // 读成"还在跑"）。
+    const seen = new Set(tracked.map((job) => job.id));
+    for (const row of roster) {
+        if (seen.has(row.id))
+            continue;
+        if (row.status !== undefined && !RUNNING_JOB_STATUSES.has(row.status))
+            continue;
+        next.push({
+            id: row.id,
+            label: row.label,
+            ...(row.status === undefined ? {} : { status: row.status }),
+            ...(row.progress === undefined ? {} : { progress: row.progress }),
+        });
+    }
+    if (next.length === tracked.length && next.every((job, index) => job === tracked[index])) {
+        return state;
+    }
+    return { ...state, backgroundJobs: next };
+}
+/**
+ * 订阅断了但任务仍未结算：把在跑的任务标成「状态未知」。
+ *
+ * 监控中断不等于任务结束——不标出来，卡片又会退化成"最后一次观测当现状"，
+ * 正是这次要修的那个缺陷。未知态仍保留停止按钮（用户还能尝试停掉）。
+ */
+export function markBackgroundJobsUnknown(state) {
+    const jobs = state.backgroundJobs;
+    if (!jobs || jobs.length === 0)
+        return state;
+    let changed = false;
+    const next = jobs.map((job) => {
+        if (!isLiveBackgroundJob(job))
+            return job;
+        changed = true;
+        return { ...job, status: 'unknown' };
+    });
+    return changed ? { ...state, backgroundJobs: next } : state;
+}
 /**
  * 运行期状态投影 → 状态行。
  *

package/dist/message-handlers.js

@@ -207,7 +207,9 @@ export function setupMessageHandlers(deps) {
         const actionValue = action.action.value;
         if (!actionValue?.cmd)
             return;
-        logger.info(`card action: ${actionValue.cmd}`);
+        logger.info(actionValue.cmd === 'stop'
+            ? `card action: stop runId=${actionValue.runId ?? '(none)'} messageId=${action.messageId}`
+            : `card action: ${actionValue.cmd}`);
         const userId = action.operator.openId;
         const chatId = action.chatId;
         const messageId = action.messageId;

package/dist/router/index.js

@@ -1319,14 +1319,15 @@ export class CommandRouter {
      * Handle stop card action: interrupt current run.
      */
     async handleCardStop(value, ctx) {
-        if (!value.runId || !ctx.userId || !ctx.chatId) {
+        if (!ctx.userId || !ctx.chatId || (!value.runId && !ctx.messageId)) {
             await this.bridge.sendResult({ text: '⚠️ 无效的停止请求，缺少必要信息' }, ctx);
             return;
         }
         const interrupt = await this.bridge.interruptCurrentRunDetailed({
             userId: ctx.userId,
             chatId: ctx.chatId,
-            runId: value.runId,
+            ...(value.runId ? { runId: value.runId } : {}),
+            cardMessageId: ctx.messageId,
         });
         const stopped = interrupt.stopped;
         // Regression 2026-06-22: card stop button silently no-op'd when the

package/dist/runner/dsh/client.d.ts

@@ -325,13 +325,20 @@ export declare class DshClient {
      */
     controlFrames(signal: AbortSignal): AsyncGenerator<DshProjectionItem>;
     /**
-     * One session's current background-job roster.
+     * Subscribe to one session's background-job roster as a live stream.
      *
-     * `job/list` 是流（生命周期变化时推整份名单），但"此刻有哪些任务在跑"只需
-     * 要第一帧：文档明确首帧就是当前真相（whole-set replacement）。取到即断开，
-     * 不长期持有连接——任务列表只用于收尾时的一句话与停止按钮。
+     * `job/list` 是整份替换流（whole-set replacement）：首帧就是当前真相，之后
+     * 任务生命周期一变就再推一整份。**run 结束之后**必须用这个长订阅——后台任务
+     * 跨 turn 存活，任务结束这件事只会在这条流上出现；收尾时取首帧即断开
+     * （{@link jobRows}）只够画那一瞬间的卡片。
+     */
+    watchJobs(sessionId: string, signal: AbortSignal): AsyncGenerator<DshJobView[]>;
+    /**
+     * One session's current background-job roster (snapshot).
      *
-     * 失败返回 undefined（与"没有任务"区分）：拿不到就别在卡片上写"0 个后台任务"。
+     * "此刻有哪些任务在跑"只需要第一帧：文档明确首帧就是当前真相，取到即断开，
+     * 不长期持有连接。失败返回 undefined（与"没有任务"区分）：拿不到就别在卡片
+     * 上写"0 个后台任务"。
      */
     jobRows(sessionId: string, opts?: {
         signal?: AbortSignal;

package/dist/runner/dsh/client.js

@@ -927,25 +927,35 @@ export class DshClient {
         }
     }
     /**
-     * One session's current background-job roster.
+     * Subscribe to one session's background-job roster as a live stream.
      *
-     * `job/list` 是流（生命周期变化时推整份名单），但"此刻有哪些任务在跑"只需
-     * 要第一帧：文档明确首帧就是当前真相（whole-set replacement）。取到即断开，
-     * 不长期持有连接——任务列表只用于收尾时的一句话与停止按钮。
+     * `job/list` 是整份替换流（whole-set replacement）：首帧就是当前真相，之后
+     * 任务生命周期一变就再推一整份。**run 结束之后**必须用这个长订阅——后台任务
+     * 跨 turn 存活，任务结束这件事只会在这条流上出现；收尾时取首帧即断开
+     * （{@link jobRows}）只够画那一瞬间的卡片。
+     */
+    async *watchJobs(sessionId, signal) {
+        for await (const frame of this.muxStream('job/list', { args: dshArgs('job/list', { sessionId }) }, signal)) {
+            const rows = frame;
+            if (rows?.type !== 'rows')
+                continue;
+            yield Array.isArray(rows.jobs) ? rows.jobs : [];
+        }
+    }
+    /**
+     * One session's current background-job roster (snapshot).
      *
-     * 失败返回 undefined（与"没有任务"区分）：拿不到就别在卡片上写"0 个后台任务"。
+     * "此刻有哪些任务在跑"只需要第一帧：文档明确首帧就是当前真相，取到即断开，
+     * 不长期持有连接。失败返回 undefined（与"没有任务"区分）：拿不到就别在卡片
+     * 上写"0 个后台任务"。
      */
     async jobRows(sessionId, opts = {}) {
         const timer = new AbortController();
         const timeout = setTimeout(() => timer.abort(), opts.timeoutMs ?? 2_000);
         const signal = opts.signal ? AbortSignal.any([opts.signal, timer.signal]) : timer.signal;
         try {
-            for await (const frame of this.muxStream('job/list', { args: dshArgs('job/list', { sessionId }) }, signal)) {
-                const rows = frame;
-                if (rows?.type === 'rows') {
-                    return Array.isArray(rows.jobs) ? rows.jobs : [];
-                }
-            }
+            for await (const rows of this.watchJobs(sessionId, signal))
+                return rows;
             return undefined;
         }
         catch (err) {

package/dist/runner/dsh/runner.d.ts

@@ -18,7 +18,7 @@
  * back to the Web UI prompt.
  */
 import type { AgentSessionReader } from '../../session-contract.js';
-import type { AgentEvent, AgentStatusInfo, SpawnOptions, StopOutcome } from '../types.js';
+import type { AgentEvent, AgentStatusInfo, BackgroundJobRoster, SpawnOptions, StopOutcome } from '../types.js';
 import type { AgentRunner } from '../types.js';
 import { DshClient, type WebSocketFactory } from './client.js';
 import type { DshDaemon } from './daemon.js';
@@ -169,6 +169,13 @@ export declare class DshRunner implements AgentRunner {
      * 任务列表不等于有任务在跑。
      */
     private collectBackgroundJobs;
+    /**
+     * 订阅本 session 的后台任务名单（跨 turn 生命周期）。
+     *
+     * 卡片收尾后仍要靠它把「任务结束了」推给用户：run 的事件流在 result 就关了，
+     * 而后台任务可能再跑半小时。名单是整份替换，消费方自己做 diff。
+     */
+    watchJobs(sessionId: string, signal: AbortSignal): AsyncGenerator<ReadonlyArray<BackgroundJobRoster>>;
     /** Kill one background job of this runner's session (card button path). */
     killJob(sessionId: string, jobId: string): Promise<boolean>;
     /** Apply the configured permission preset once per session, before prompt. */

package/dist/runner/dsh/runner.js

@@ -796,6 +796,22 @@ export class DshRunner {
             },
         ];
     }
+    /**
+     * 订阅本 session 的后台任务名单（跨 turn 生命周期）。
+     *
+     * 卡片收尾后仍要靠它把「任务结束了」推给用户：run 的事件流在 result 就关了，
+     * 而后台任务可能再跑半小时。名单是整份替换，消费方自己做 diff。
+     */
+    async *watchJobs(sessionId, signal) {
+        for await (const rows of this.client.watchJobs(sessionId, signal)) {
+            yield rows.map((job) => ({
+                id: job.id,
+                label: job.label ?? job.id,
+                ...(job.status === undefined ? {} : { status: job.status }),
+                ...(job.progress === undefined ? {} : { progress: job.progress }),
+            }));
+        }
+    }
     /** Kill one background job of this runner's session (card button path). */
     async killJob(sessionId, jobId) {
         return await this.client.jobKill(sessionId, jobId);

package/dist/runner/index.d.ts

@@ -15,6 +15,6 @@ export { KimiAcpRunner } from './kimi/index.js';
 export { DshRunner } from './dsh/index.js';
 export { BashProcessRunner, type BashRunner } from './bash/index.js';
 export { AgentRegistry } from './registry.js';
-export type { ResultEvent, PlanEvent, FileChangeEvent, AgentEvent, Runner, RunnerLifetime, AgentRunner, TurnStartedEvent, TurnDiffEvent, FinalAnswerEvent, NoticeEvent, SessionInfoEvent, ToolHint, ApprovalView, ApprovalRequestedEvent, ApprovalResolvedEvent, GoalView, GoalStateEvent, } from './types.js';
+export type { ResultEvent, PlanEvent, FileChangeEvent, AgentEvent, Runner, RunnerLifetime, AgentRunner, TurnStartedEvent, TurnDiffEvent, FinalAnswerEvent, NoticeEvent, SessionInfoEvent, ToolHint, ApprovalView, ApprovalRequestedEvent, ApprovalResolvedEvent, BackgroundJobRoster, BackgroundJobsEvent, GoalView, GoalStateEvent, } from './types.js';
 export { resolveAgentChoices } from './resolve-agent-choices.js';
 export { syncAgentChoices } from './sync-agent-choices.js';

package/dist/runner/types.d.ts

@@ -416,6 +416,20 @@ export interface GoalStateEvent {
     known: boolean;
     timestamp?: string;
 }
+/**
+ * 后台任务名单里的一行（宿主侧权威数据）。
+ *
+ * `status` 保留宿主原词（running / stopping / completed / failed …）——各
+ * agent 的终态词表不同，桥侧只按「是不是 running/stopping」二分，不在这里
+ * 维护一份会漂移的枚举。桥侧自己产出的 `ended` / `unknown` 见
+ * `BackgroundJobStatus`（card/run-state）。
+ */
+export interface BackgroundJobRoster {
+    id: string;
+    label: string;
+    status?: string;
+    progress?: string;
+}
 /**
  * 运行结束后仍在后台运行的任务（终态卡展示 + 逐个停止入口）。
  *
@@ -425,12 +439,7 @@ export interface GoalStateEvent {
  */
 export interface BackgroundJobsEvent {
     type: 'background_jobs';
-    jobs: Array<{
-        id: string;
-        label: string;
-        status?: string;
-        progress?: string;
-    }>;
+    jobs: BackgroundJobRoster[];
     timestamp?: string;
 }
 /** File change event — for agents that report file modifications (e.g. Codex). */
@@ -611,6 +620,14 @@ export interface AgentRunner extends Runner {
      * agent 实现；调用方按能力存在与否门控。
      */
     killJob?(sessionId: string, jobId: string): Promise<boolean>;
+    /**
+     * 订阅一个 session 的后台任务名单（整份替换），直到 `signal` abort 或宿主
+     * 关闭流。只有支持后台任务的 agent 实现；调用方按能力存在与否门控。
+     *
+     * 必须在 run 结束之后仍然可用：后台任务的生命周期跨 turn，收尾那一刻的快照
+     * 只能画一张会过期的卡。
+     */
+    watchJobs?(sessionId: string, signal: AbortSignal): AsyncIterable<ReadonlyArray<BackgroundJobRoster>>;
     /**
      * 热更审批模式/权限预设（config.save 后推给在跑的 runner，不必重启会话）。
      * 各家 settings 词表不同（codex: approvalPolicy/sandbox；kimi: permissionMode；

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-remote",
-  "version": "0.5.18",
+  "version": "0.5.19",
   "description": "Feishu (Lark) private-chat bridge to local coding agents — Claude Code / Codex / opencode / pi / kimi, with live-streaming CardKit 2.0 cards",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",