lark-remote 0.5.18 → 0.5.20

package/dist/card/card-helpers.js

@@ -36,7 +36,7 @@ const SESSION_PANEL_TITLE_MAX = 42;
 export function sessionEventPanel(ev, index, totalEvents, tailExpandedCount = 2, agentKind = 'claude') {
     // reader 可以给事件一个"标题即摘要"的名字（工具调用：`🔧 bash — npm test`）；
     // 缺省用类型标签。标题连同时间戳一起收进一行显示宽度——手机上折叠面板只有
-    // 一行可用（2026-10-19 工具标题被长 URL 撑成两行那次）。
+    // 一行可用，长 URL 把标题撑成两行会断在 URL 中间。
     const label = ev.title ?? eventLabel(ev, agentKind);
     const ts = formatMonthDayClock(ev.timestamp);
     const suffix = ts ? ` (${ts})` : '';
@@ -103,7 +103,7 @@ export function parseJumpOffset(inputValue, pageSize) {
  * Build the CardKit 2.0 pagination block shared by /ls, /ws, /resume, /active,
  * /order.
  *
- * 第一性原理（2026-09-10 窄屏重设计）：分页栏要同时承载「页码信息」和「翻页
+ * 第一性原理（窄屏）：分页栏要同时承载「页码信息」和「翻页
  * 控件」两类需求。旧布局把两者塞进同一行 `column_set`（文案 weighted 4 : 输入
  * weighted 2），手机窄屏下 auto 按钮先占走固有宽度，剩余宽度按 4:2 切分后文案
  * 列只有百来像素、输入框只有几十像素——文案折行、输入框窄到没法点。
@@ -253,8 +253,8 @@ export function searchBar(opts) {
  *
  * 旧口径是 `events.slice(-max)`：按**原始事件条数**截尾。工具往返（bash 调用 →
  * job 登记 → 结果）一段就能把窗口占满，于是重返会话的用户真正需要的两条信息
- * ——最后一句我说了什么、最后一句它答了什么——被挤出窗口。2026-10-19 实测：
- * 自动恢复卡 5 个面板全是 bash 调用，一条用户消息、一条 assistant 正文都没有。
+ * ——最后一句我说了什么、最后一句它答了什么——被挤出窗口：自动恢复卡 5 个
+ * 面板全是 bash 调用，一条用户消息、一条 assistant 正文都没有。
  *
  * 契约：先取最新 `max` 条，再把最后一条 `user` 与最后一条 `assistant`（正文）
  * 不在窗口内时补进来——补位时淘汰最早的**非锚点**事件。输出保持时间顺序，
@@ -313,7 +313,7 @@ export function buildSessionHistoryCard(state, opts) {
     // （DSH 的 projections.title / claude 的 ai-title），后者是最近一条用户输入。
     // claude 的 displayTitle 本身就取 aiTitle，两者相等 → 保持旧的「AI 标题」
     // 单段文案；DSH 两者都有（标题 + 末轮 prompt）→ 各占一段，别把用户那句话
-    // 挂在「AI 标题」下面（2026-10-21）。
+    // 挂在「AI 标题」下面。
     if (displayTitle) {
         if (aiTitle && aiTitle !== displayTitle) {
             sections.push(`🏷️ **标题**\n${preview(aiTitle)}`);
@@ -357,7 +357,7 @@ export function buildSessionHistoryCard(state, opts) {
         elements.push(markdownDiv(usageStr));
     }
     // Remove trailing hr
-    if (elements.length > 0 && elements[elements.length - 1].tag === 'hr') {
+    if (elements[elements.length - 1].tag === 'hr') {
         elements.pop();
     }
     if (opts.actions && opts.actions.length > 0) {

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.js

@@ -2,7 +2,7 @@
  * 完整回答超出一张卡片时，落成 Markdown 文件随卡片发送。
  *
  * 为什么不再拆纯文本消息：拆出来的「完整回答（1/N）」与卡片正文重复
- * （2026-11-02 实机反馈：同一篇回答用户看到两遍），而且纯文本会丢表格、
+ * （同一篇回答用户看到两遍），而且纯文本会丢表格、
  * 代码块等 Markdown 结构。文件通道保留原文逐字不变，且只多一条文件消息。
  *
  * 调用方负责用后删除：`bestEffortUnlink()` 见 `common/fs.ts`。

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.d.ts

@@ -55,7 +55,7 @@ type GroupContentPrepared = Map<BlockGroup, string>;
 /**
  * 状态行内容：**一行、一个 div、窄屏不换行**。
  *
- * 设计约束（2026-10-19 手机端实测）：旧版把「状态标签」和「耗时/指标」放进
+ * 设计约束（手机端）：旧版把「状态标签」和「耗时/指标」放进
  * `column_set` 的 auto + grow 两列，窄屏上 auto 列被挤到只剩两个字宽，
  * "运行中" 被拆成 "运行 / 中"。列式布局的可用宽度取决于对端渲染，服务端无法
  * 保证；所以这里改成单 div，段间用 " · " 分隔——换行只会发生在分隔符处，
@@ -64,8 +64,8 @@ type GroupContentPrepared = Map<BlockGroup, string>;
  * 状态标签（运行中/已完成…）不再重复：header 已经写了（`🔧 dsh · 调用工具`
  * / `✅ dsh · 已完成`），终态 summary 还有一次。
  *
- * 终态也保留状态行：耗时定格，DSH 的步数/上下文投影展示最后一次快照
- * （2026-10-21 用户要求）。summary 的最终 usage 与状态行并存。
+ * 终态也保留状态行：耗时定格，DSH 的步数/上下文投影展示最后一次快照。
+ * summary 的最终 usage 与状态行并存。
  *
  * 导出供窄屏守卫测试断言分段宽度（与 `estimateCardBytes` 同一惯例）。
  */

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';
@@ -8,7 +8,7 @@ import { countCardElements, MAX_CARD_ELEMENTS } from './card-budget.js';
 import { displayWidth, truncateToDisplayWidth } from '../common/text-width.js';
 import { isContentFilterFailure } from '../common/turn-failure.js';
 import { formatClock, formatTimestamp } from './time.js';
-import { formatUsageStats } from './usage-format.js';
+import { formatTokenK, formatUsageStats } from './usage-format.js';
 import { renderApprovalArea, renderApprovalAreaCompact } from './approval-render.js';
 const REASONING_BYTES = 4_500;
 const TEXT_BYTES = 10_000;
@@ -38,7 +38,7 @@ const EMPTY_MD_DIV_BYTES = measureJson(markdownDiv('', 'notation'));
  * 能力门控（compactSupported !== false）与执行侧 `'runCompact' in runner`
  * 鸭子探测对齐：claude 走 stream-json，不发射 turn_started，operationKind
  * 恒 undefined——若以 operationKind==='turn' 作门控，claude 终态卡永远拿
- * 不到按钮（2026-08-19 缺陷）。compaction 卡的「防递归」仍由 operationKind
+ * 不到按钮。compaction 卡的「防递归」仍由 operationKind
  * 保证，两者是不同质的判断。
  */
 function shouldShowCompactButton(state, options) {
@@ -121,37 +121,21 @@ function buildGoalSection(state) {
  * This unifies timestamp position across all block types (thinking/plan/file_change/tool/text).
  *
  * Panel title: `💬 **输出** (ts)` when timestamp present, `💬 **输出**` otherwise.
- * Running: expanded=true; completed: expanded=false (symmetric with thinking).
+ * The panel is always expanded — streaming and finalized states render identically.
  *
  * @param content - The text content to render
  * @param timestamp - Optional timestamp for the block
- * @param finalized - Whether the run is in a terminal state
  * @returns elements
  */
-function renderTextBlock(content, timestamp, finalized = false) {
+function renderTextBlock(content, timestamp) {
     if (!content.trim()) {
         return [];
     }
     const ts = formatTimestamp(timestamp);
-    // Terminal state: output is the card body, render in collapsible_panel with expanded=true.
+    // Render in collapsible_panel with expanded=true.
     // NOTE: collapsible_panel does NOT shield markdown tables from Feishu's 11310 table count
     // limit — tables inside lark_md text are still counted regardless of container.
     // We must explicitly truncate excess tables via truncateMarkdownTables before rendering.
-    if (finalized) {
-        const title = '💬 **输出**';
-        const header = ts ? `${title} (${ts})` : title;
-        const safeContent = truncateMarkdownTables(content);
-        return [
-            collapsibleMarkdownPanel({
-                title: header,
-                expanded: true, // Always expanded in finalized state for full visibility
-                border: 'grey',
-                content: safeContent,
-                textSize: 'notation',
-            }),
-        ];
-    }
-    // Running/finalizing: panel provides visual grouping with timestamp in header
     const title = '💬 **输出**';
     const header = ts ? `${title} (${ts})` : title;
     const safeContent = truncateMarkdownTables(content);
@@ -302,7 +286,7 @@ function groupBlocks(blocks) {
  *
  * 早先试过"一行 + 服务端「详情」按钮"：折叠不省字节所以正文不入 payload，展开
  * 只能回服务端重出卡。代价是手机上要多点一次、按钮还占掉标题宽度（长 URL 被挤
- * 成两行，2026-10-19 反馈）。现在改成折叠面板 + **按工具数量缩放的正文截断**：
+ * 成两行）。现在改成折叠面板 + **按工具数量缩放的正文截断**：
  * 正文始终随卡下发（面板折叠时不显示），点标题即展开，无往返、无按钮。
  *
  * 展开态：运行中/失败的默认展开（用户在等结果、错误要立刻可见），其余折叠。
@@ -493,8 +477,6 @@ function assembleRunCard(state, options, elements) {
 function insertAfterStatusRow(elements, extra) {
     if (extra.length === 0)
         return elements;
-    if (elements.length === 0)
-        return extra;
     return [elements[0], ...extra, ...elements.slice(1)];
 }
 /**
@@ -573,16 +555,13 @@ function buildFallbackElements(state, options, tier) {
         else if (group.kind === 'text') {
             const content = truncateUtf8(group.content, tier.textBytes, true, '…（已截断）\n');
             const ts = formatTimestamp(group.timestamp);
-            elements.push(...renderTextBlock(content, ts, true));
+            elements.push(...renderTextBlock(content, ts));
         }
         else if (group.kind === 'tool') {
             // Show tool individually (each tool is independent now)
             elements.push(renderTool(group.tool, outputMax));
         }
     }
-    if (elements.length === 0 && tier === EXTREME_TIER) {
-        elements.push(markdownDiv('_暂无输出_'));
-    }
     elements.push(...buildSummaryContent(state, { includeNotices: false }));
     elements.push(...actionRow(state, options));
     elements.push(...approvalArea(state));
@@ -606,7 +585,7 @@ function buildExtremeFallbackElements(state, options) {
 /**
  * 状态行内容：**一行、一个 div、窄屏不换行**。
  *
- * 设计约束（2026-10-19 手机端实测）：旧版把「状态标签」和「耗时/指标」放进
+ * 设计约束（手机端）：旧版把「状态标签」和「耗时/指标」放进
  * `column_set` 的 auto + grow 两列，窄屏上 auto 列被挤到只剩两个字宽，
  * "运行中" 被拆成 "运行 / 中"。列式布局的可用宽度取决于对端渲染，服务端无法
  * 保证；所以这里改成单 div，段间用 " · " 分隔——换行只会发生在分隔符处，
@@ -615,8 +594,8 @@ function buildExtremeFallbackElements(state, options) {
  * 状态标签（运行中/已完成…）不再重复：header 已经写了（`🔧 dsh · 调用工具`
  * / `✅ dsh · 已完成`），终态 summary 还有一次。
  *
- * 终态也保留状态行：耗时定格，DSH 的步数/上下文投影展示最后一次快照
- * （2026-10-21 用户要求）。summary 的最终 usage 与状态行并存。
+ * 终态也保留状态行：耗时定格，DSH 的步数/上下文投影展示最后一次快照。
+ * summary 的最终 usage 与状态行并存。
  *
  * 导出供窄屏守卫测试断言分段宽度（与 `estimateCardBytes` 同一惯例）。
  */
@@ -629,7 +608,7 @@ export function statusLine(state) {
     const elapsed = elapsedLabel(state);
     if (elapsed)
         parts.push(`⏱ ${elapsed}`);
-    // 运行期投影在终态也保留（2026-10-21 用户要求）：DSH 卡片完成时，耗时/步数/
+    // 运行期投影在终态也保留：DSH 卡片完成时，耗时/步数/
     // 上下文百分比是这一跑留下的最后快照，撤掉后用户只能从 summary 的累计口径
     // 重新推算。summary 仍展示最终 usage，两者口径不同、并存不冲突。
     const live = state.liveStatus;
@@ -644,12 +623,12 @@ export function statusLine(state) {
             parts.push(`📊 ~${pct}%`);
         }
         else if (live.contextUsed !== undefined) {
-            parts.push(`📊 ${formatTokens(live.contextUsed)}`);
+            parts.push(`📊 ${formatTokenK(live.contextUsed)}`);
         }
     }
     if (parts.length === 0) {
         // 没有任何可用指标时退回状态词（骨架卡/测试构造的状态没有时间戳）。
-        return statusTagLabel(state.terminal);
+        return terminalToLabel(state.terminal);
     }
     return parts.join(' · ');
 }
@@ -672,15 +651,6 @@ function elapsedLabel(state) {
         return `${hours}h${String(minutes % 60).padStart(2, '0')}m`;
     return `${Math.floor(hours / 24)}d${String(hours % 24).padStart(2, '0')}h`;
 }
-/** token 数量的紧凑写法：`950` / `12K` / `1.0M`。 */
-function formatTokens(tokens) {
-    if (tokens < 1000)
-        return String(tokens);
-    // 千位边界取 M 档：999_500 起四舍五入会得到 "1000K"，直接按 M 档展示。
-    if (tokens < 999_500)
-        return `${Math.round(tokens / 1000)}K`;
-    return `${(tokens / 1_000_000).toFixed(1)}M`;
-}
 /**
  * 状态行元素（full/degraded/extreme/skeleton 共用）。
  *
@@ -955,7 +925,7 @@ export const FINAL_ANSWER_OVERFLOW_MARKER = '_最终回答较长，完整内容
  * 「卡片装不下正文」与「表格数超上限」是两件事，只有前者才走补发通道：
  * 飞书单卡最多 5 张 markdown 表（11310），多出来的最旧表格会被删掉并在原位
  * 留 `_💡 前 N 个表格已省略_`——正文仍在卡片里，再补发一遍就是把用户已经看到
- * 的整篇回答重复（2026-11-02 实机反馈）。
+ * 的整篇回答重复。
  */
 function buildFinalAnswerPriorityCard(state, options) {
     const finalAnswer = state.finalAnswer;
@@ -963,12 +933,12 @@ function buildFinalAnswerPriorityCard(state, options) {
     const prepared = prepareGroupContent(groups);
     const safeAnswer = truncateMarkdownTables(finalAnswer.content);
     const ts = formatTimestamp(finalAnswer.timestamp);
-    const answerElements = renderTextBlock(safeAnswer, ts, state.terminal !== 'running');
+    const answerElements = renderTextBlock(safeAnswer, ts);
     const fixedStart = [statusRow(state), ...omittedBlocksHint(state)];
     const summary = buildSummaryContent(state, { includeNotices: false });
     const controls = [...actionRow(state, options), ...approvalArea(state)];
     const buildWithProgress = (start, includeSummary) => {
-        const renderedProgress = buildAnswerProgressContent(state, prepared, groups.slice(start));
+        const renderedProgress = renderContentGroups(state, prepared, groups.slice(start));
         const progress = start < groups.length
             ? [markdownDiv(`_💡 已省略 ${start} 个早期步骤_`), ...renderedProgress]
             : renderedProgress;
@@ -1009,8 +979,17 @@ function buildFinalAnswerPriorityCard(state, options) {
         finalAnswerText: finalAnswer.content,
     };
 }
-/** Render a contiguous progress suffix for the answer-priority card. */
-function buildAnswerProgressContent(state, prepared, visible) {
+/**
+ * 正常路径内容循环，时间线卡（buildChronologicalContent）与答案优先卡的进度
+ * 后缀（buildFinalAnswerPriorityCard）共用：notices 作为普通消息按到达时间
+ * 插入内容流（有内容时不再沉到 summary），tool/text/panel 组逐个渲染。
+ *
+ * prepared 的键是组对象引用：传入的组数组必须保持元素引用（slice 可以，重建
+ * 数组会让 prepared.get 永远 miss，退化为二次截断）。面板组描述经
+ * describePanelGroup 与估算共享同一份模板。
+ * 「已省略 N 个早期步骤」提示与空态兜底 `_暂无输出_` 由调用方各自负责。
+ */
+function renderContentGroups(state, prepared, visible) {
     const elements = [];
     const outputMax = toolOutputBudget(state);
     const contentItems = mergeNoticesIntoContent(visible, state.notices);
@@ -1027,7 +1006,7 @@ function buildAnswerProgressContent(state, prepared, visible) {
         if (group.kind === 'text') {
             const content = prepared.get(group) ?? '';
             const ts = formatTimestamp(group.timestamp);
-            elements.push(...renderTextBlock(content, ts, state.terminal !== 'running'));
+            elements.push(...renderTextBlock(content, ts));
             continue;
         }
         const spec = describePanelGroup(group, prepared);
@@ -1058,46 +1037,12 @@ function withinRunCardBudget(card) {
 }
 /** Build content in chronological order using groupBlocks to interleave thinking/text/tools. */
 function buildChronologicalContent(state, prepared, groups) {
-    const elements = [];
-    // finalized = 非 running（含 finalizing：主结果已出，thinking 折叠）
-    const finalized = state.terminal !== 'running';
     // 节点预算内从最新往回选择可见组：超限时只省略最旧的几步，不整卡降级。
     const { visible, omitted } = selectVisibleGroups(groups);
-    const outputMax = toolOutputBudget(state);
+    const elements = [];
     if (omitted > 0)
         elements.push(markdownDiv(`_💡 已省略 ${omitted} 个早期步骤_`));
-    // renderRunCard 传入同一 groups 数组时直接复用（prepared 的键是组对象
-    // 引用，重建数组会让 prepared.get 永远 miss，退化为二次截断）。
-    // 面板组描述经 describePanelGroup 与估算共享同一份模板。
-    // notices 作为普通消息按到达时间插入内容流（有内容时不再沉到 summary）。
-    const contentItems = mergeNoticesIntoContent(visible, state.notices);
-    for (const item of contentItems) {
-        if (item.kind === 'notice') {
-            elements.push(renderNoticeRow(item.notice));
-            continue;
-        }
-        const group = item;
-        if (group.kind === 'tool') {
-            elements.push(renderTool(group.tool, outputMax));
-            continue;
-        }
-        if (group.kind === 'text') {
-            const content = prepared.get(group) ?? '';
-            const ts = formatTimestamp(group.timestamp);
-            elements.push(...renderTextBlock(content, ts, finalized));
-            continue;
-        }
-        const spec = describePanelGroup(group, prepared);
-        if (!spec)
-            continue;
-        elements.push(collapsibleMarkdownPanel({
-            title: spec.title,
-            expanded: spec.expanded,
-            border: spec.border,
-            content: spec.content,
-            textSize: 'notation',
-        }));
-    }
+    elements.push(...renderContentGroups(state, prepared, visible));
     if (elements.length === 0) {
         elements.push(markdownDiv('_暂无输出_'));
     }
@@ -1154,8 +1099,8 @@ function buildSummaryContent(state, options = {}) {
         const result = state.resultSubtype ?? 'success';
         const hasContent = state.blocks.length > 0 || !!state.finalAnswer?.content.trim();
         // 压缩（operationKind='compaction'）不会返回 agent 正文——引擎只压缩上下文
-        // 窗口，空内容属正常，不能沿用普通 run 的「（未返回内容）」异常信号
-        // （2026-09 用户反馈）。所有会压缩的 agent（codex/claude/kimi/opencode/pi）
+        // 窗口，空内容属正常，不能沿用普通 run 的「（未返回内容）」异常信号。
+        // 所有会压缩的 agent（codex/claude/kimi/opencode/pi）
         // 都经 streamCompact 走这条共享渲染路径，一处覆盖全部。
         const empty = hasContent
             ? ''
@@ -1202,11 +1147,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 反引号不能替换成 `'`
  * （那是改内容），只能选比内容里最长反引号串更长的围栏。
@@ -1228,7 +1188,7 @@ function codeFenceFor(content) {
 /**
  * 后台任务小节：命令独占一行，停止按钮单独一行。
  *
- * 布局约束（2026-10-21 手机端反馈）：
+ * 布局约束（手机端）：
  * - 命令 + 按钮不再并排（grow + auto）：窄屏下 auto 列会被挤成「🟥…」，
  *   命令也被截断。按钮现在独占一个单列 column_set，宽度由按钮自身决定。
  * - 命令不 truncate：短命令/单行直接内联；中等长度的多行命令用代码块
@@ -1244,24 +1204,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 +1250,9 @@ function buildBackgroundJobsSection(state) {
                 })
                 : markdownDiv(content));
         }
+        // 已结束的任务不再给停止入口——那个按钮点下去只会回「可能已自行结束」。
+        if (job.status === 'ended')
+            return;
         elements.push({
             tag: 'column_set',
             columns: [
@@ -1292,10 +1271,6 @@ function buildBackgroundJobsSection(state) {
     }
     return elements;
 }
-/** Status tag label */
-function statusTagLabel(terminal) {
-    return terminalToLabel(terminal);
-}
 /** CardKit 2.0 header title — agent-aware via options.agentKind. */
 function headerTitle(state, options = {}) {
     const agent = agentDisplayName(options.agentKind ?? 'claude');
@@ -1325,7 +1300,7 @@ function headerTitle(state, options = {}) {
     if (state.terminal === 'finalizing')
         return `⏳ ${agent} · 完成中`;
     // 审批等待期间 server 暂停 turn，命令工具停在 tool_running——标题必须提示
-    // 正在等人工决策，而不是「调用工具」（2026-08-14 UX）。
+    // 正在等人工决策，而不是「调用工具」。
     if (hasPendingApproval(state))
         return `✋ ${agent} · 等待审批`;
     if (state.footer === 'thinking')

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'
 /**
@@ -154,7 +154,7 @@ export interface RunState extends UsageSnapshot {
      * 审批是否曾过期（桥侧 timer 触发，approval_expired 事件置位）。
      * 独立于 approvals 数组持久保存：cancel 送达后 server 会回
      * approval_resolved，把对应审批条目从数组移除，但过期原因必须活到
-     * 终态渲染（2026-08-15 事故：标记被消费后卡片误报「已被用户终止」）。
+     * 终态渲染（否则标记被消费后卡片误报「已被用户终止」）。
      */
     approvalExpired?: boolean;
     /**
@@ -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 {};