lark-remote 0.5.18 → 0.5.20

package/dist/router/index.js

@@ -57,10 +57,10 @@ function findMergedCommandTail(message) {
 /** 人类可读字节数（B/KB/MB/GB）；/ls 列表与单文件卡共用。 */
 /**
  * /order 列表页大小；指令超过此数量时显示分页导航栏。
- * 2026-08-13 实测：每行 2 个元素（div + column_set，行间 hr），20 行 + 分页栏
+ * 实测：每行 2 个元素（div + column_set，行间 hr），20 行 + 分页栏
  * = 61 个 body 元素，触发飞书 ErrCode 11310 "element exceeds the limit"
  * （21+ 条指令时第 1 页必炸）。改为 15 行：3*15 - 1 + 2 = 46 个元素，留足余量。
- * 2026-08-19 别名并卡后每行变 3 个元素（文本 div + 操作 column_set + hr），
+ * 别名并卡后每行变 3 个元素（文本 div + 操作 column_set + hr），
  * 从 15 降为 8：3*8 - 1 + 2 = 25 个元素，仍在余量内，同时保证手机窄屏
  * 每条指令的操作控件（执行/别名/删除）不被挤压。
  */
@@ -148,7 +148,7 @@ const APPROVAL_ACTION_SPECS = {
         }),
         successToast: '审批已提交',
         failureToast: (msg) => {
-            // 审批已过期：给用户明确反馈，不静默不误导（2026-08-12 事故：点了允许无任何反馈）。
+            // 审批已过期：给用户明确反馈，不静默不误导（否则点了允许无任何反馈）。
             const content = /state=expired/.test(msg)
                 ? '⏰ 审批已过期，无法响应'
                 : `审批响应失败：${msg}`;
@@ -296,7 +296,7 @@ const IMMEDIATE_ACTION_CMDS = new Set([
     'config.save',
     // 审批响应/权限切换必须即时触达在途 run（同 stop 类控制动作）。若走串行
     // 队列会排在等待审批的 run 之后形成死锁：run 不结束审批不执行，run 结束
-    // coordinator 已删响应空转（线上复现：approval.respond 排队卡、审批永不生效）。
+    // coordinator 已删响应空转（approval.respond 落进排队卡、审批永不生效）。
     ...APPROVAL_ACTION_CMDS,
 ]);
 /**
@@ -304,7 +304,7 @@ const IMMEDIATE_ACTION_CMDS = new Set([
  * sessionId / cwd / defaultAgent，必须与入站装配器的 700ms 静默窗口定序：
  * 控制层（index.ts）在执行它们之前先 flush 该 user/chat 的装配窗口，保证窗口内
  * 先到的文本消息在本动作之前 commit（绑定动作前的旧状态）。否则窗口内消息会
- * 漂移到动作之后的新状态（2026-10-07 事故：输入「重新构建」后立即点「新会话」，
+ * 漂移到动作之后的新状态（输入「重新构建」后立即点「新会话」，
  * 消息落到新会话）。
  *
  * 文本命令（/new、/cd、/resume、/config）已由 index.ts 命令分支先 flush，
@@ -321,7 +321,7 @@ export const SESSION_MUTATING_ACTION_CMDS = new Set([
  * 会产生压缩工作的卡片动作（单源）。这类条目占用 lane 时必须自报身份：
  * 排队卡写明「正在执行: 🗜 Compact」而不是「前面还有 0 条」，并且期间禁用
  * 「立即执行」——该按钮走 interruptCurrentRun，会连带中断正在跑的压缩
- * （2026-10-09 线上：Compact 占 lane 期间新消息的排队卡自相矛盾，且按钮
+ * （Compact 占 lane 期间新消息的排队卡自相矛盾，且按钮
  * 一点就会杀掉压缩）。同时它们也不允许编辑（预览不是用户文本）。
  */
 export const COMPACT_ACTION_CMDS = new Set(['compact', 'resume.compact']);
@@ -400,8 +400,8 @@ export class CommandRouter {
      *
      * 草稿（pendingConfig）是全局一份：/config 文本命令重开卡片时沿用同一份草稿
      * （这是既有语义，不改）。但**视图**是每张卡一份 —— 只刷新被点击的那张，其余
-     * 卡片就停在旧视图上：用户在旧卡上看到的和点保存实际提交的是两套内容
-     * （2026-10-08 发现的缺陷）。这里记住所有交互过的 config 卡，任何一次编辑/保存
+     * 卡片就停在旧视图上：用户在旧卡上看到的和点保存实际提交的是两套内容。
+     * 这里记住所有交互过的 config 卡，任何一次编辑/保存
      * 后把草稿刷到每张卡，保证「看到的就是会保存的」。
      */
     configCardIds = new Set();
@@ -412,7 +412,7 @@ export class CommandRouter {
      * 条目的身份必须与「一次入队动作」1:1（queuedTasks 的定位、queueCardMessages
      * 的卡片更新、taskIndex 的取消判据全部按这个 key 做 lookup）。复用卡片 id
      * 会让同 key 的多条任务互相顶替：位置显示命中最早那条兄弟、第一条开始时删掉
-     * 索引导致其余兄弟被判「已撤销」静默丢弃（2026-10-08 线上：连点 Compact
+     * 索引导致其余兄弟被判「已撤销」静默丢弃（连点 Compact
      * 三次 → 三张排队卡都显示「第 1 位」、两张永久停在「等待中」，只压缩一次）。
      *
      * Date.now() 不够（两次同步调用可落在同一毫秒）；计数器与时间无关，恒唯一。
@@ -433,7 +433,7 @@ export class CommandRouter {
     /** Session reader 注册中心（public：测试注入/读取，替代 as unknown as）。 */
     sessionReaderRegistry;
     /**
-     * 串行化 config.* 卡片回调（2026-07-04）。
+     * 串行化 config.* 卡片回调。
      * CardKit 2.0 input/button 回调经 `enqueueImmediate` 分发，**不进串行队列**，
      * 多次快速点击下拉/文本框会并发读写 `pendingConfig` 并同时调
      * `updateCardInPlace` → Feishu API 乱序到达，控件卡死在某个状态。
@@ -483,7 +483,7 @@ export class CommandRouter {
     /**
      * Route a message: if it starts with /, handle as command; if it starts with !, execute as bash; otherwise forward to Claude.
      *
-     * 命令识别前置条件（2026-09-15修复，`inbound-unified-input-design.md` §5.6）：
+     * 命令识别前置条件（`inbound-unified-input-design.md` §5.6）：
      * 裸前缀判定会被结构占位符命中 —— SDK 把富文本里的图片渲染成 `![image](img_v3_…)`，
      * 首字符恰好是 `!`，整段用户消息被当 shell 命令执行（`executeBash "[image](img_v3_…"`）。
      * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
@@ -587,40 +587,15 @@ export class CommandRouter {
                 return await this.handleWsSort(value, ctx);
             case 'ws.remove':
                 return await this.handleWsRemove(value, ctx);
-            case 'resume.use': {
-                // resume.use carries an agent field from /resume [agent] list cards
-                // (both active and completed cards include the agent field).
-                const resolvedAgent = resolveAgentKind(value.agent, this.config.defaultAgent);
-                const entry = this.sessionStore.get(ctx.userId);
-                const cwd = entry?.cwd;
-                if (!cwd) {
-                    await this.bridge.sendResult({ text: '请先 /cd 设置工作目录' }, ctx);
-                    return;
-                }
-                // 校验前不得写入 sessionId。旧实现先无条件 setSessionId 再调
-                // cmdResume 校验，过期卡片（session 不在当前 cwd）校验失败时 store 已被
-                // 污染；value.sessionId 缺失时还会静默清空已有绑定。现在统一走 cmdResume
-                // 的已验证路径（:2352 校验通过才写入），sessionId 缺失直接报错。
-                if (!value.sessionId) {
-                    await this.bridge.sendResult({ text: '缺少 sessionId，请重新从 /resume 列表选择会话' }, ctx);
-                    return;
-                }
-                await this.bridge.sendResult(this.cmdResume([resolvedAgent, value.sessionId], ctx), ctx);
+            case 'resume.use':
+                await this.handleResumeUse(value, ctx);
                 return;
-            }
             case 'resume.page':
                 return this.handleResumePage(value, ctx);
             case 'active.page':
                 return this.handleActivePage(value, ctx);
             case 'new-session':
-                this.sessionStore.clearSessionId(ctx.userId, this.config.defaultAgent, {
-                    clearSessionCwd: true,
-                });
-                {
-                    const cwd = this.sessionStore.getCwd(ctx.userId) ?? '(未设置)';
-                    const agentName = agentDisplayName(this.config.defaultAgent);
-                    await this.bridge.sendResult({ text: `已创建新 ${agentName} 会话，下一条消息将开始全新对话\n📁 ${cwd}` }, ctx);
-                }
+                await this.handleNewSession(ctx);
                 return;
             case 'stop':
                 await this.handleCardStop(value, ctx);
@@ -664,43 +639,93 @@ export class CommandRouter {
             case 'config.set':
             case 'config.input':
             case 'config.save':
-                // 2026-07-04: 串行化所有 config.* 动作。CardKit 2.0 回调经 enqueueImmediate
+                // 串行化所有 config.* 动作。CardKit 2.0 回调经 enqueueImmediate
                 // 不进串行队列，多次快速点击下拉/文本框会并发读写 pendingConfig 并同时
                 // 调 updateCardInPlace → Feishu API 乱序到达导致控件卡死。
-                // 2026-07-18: 返回 enqueueConfigAction 的结果以支持 toast 响应
+                // 返回 enqueueConfigAction 的结果以支持 toast 响应。
                 return this.enqueueConfigAction(value, ctx);
             case 'compact':
-                await this.bridge.handleCompactAction(value, ctx);
+                await this.handleCompact(value, ctx);
                 return;
             case 'resume.compact':
-                await this.bridge.handleResumeCompact(value, ctx);
+                await this.handleResumeCompact(value, ctx);
                 return;
             default: {
-                // Help card buttons: help.<cmd> → execute /<cmd>
                 if (value.cmd.startsWith('help.')) {
-                    const subCmd = value.cmd.slice(5); // e.g. "status", "ps", "stop"
-                    const result = await this.executeCommand(`/${subCmd}`, ctx);
-                    if (result) {
-                        await this.bridge.sendResult(result, ctx);
-                    }
-                    // /exit、/restart 等命令通过 pendingExit 表达"回复送达后退出"。
-                    // handle() 在 sendResult 后消费它；help.* 按钮点击走 handleCardAction，
-                    // 必须同样消费，否则点击 /restart 按钮 spawn 成功后旧进程不退出，
-                    // 新进程撞单例锁退出 → 重启两头落空（2026-08-01 红绿 anchor 锁定）。
-                    if (this.pendingExit) {
-                        await this.flushInbound?.();
-                        this.exitHandler();
-                    }
+                    await this.handleHelpAction(value, ctx);
                     return;
                 }
-                // Design constraint: miss paths must reply via bridge.sendResult —
-                // don't silently swallow unknown card actions.
-                getLogger().warn(`[router] unknown card action: ${value.cmd}`);
-                await this.bridge.sendResult({ text: `⚠️ 未知的卡片操作: ${value.cmd}` }, ctx);
+                await this.handleUnknownCardAction(value, ctx);
                 return;
             }
         }
     }
+    /**
+     * resume.use: 从 /resume 列表卡切换到所选会话。
+     */
+    async handleResumeUse(value, ctx) {
+        // resume.use carries an agent field from /resume [agent] list cards
+        // (both active and completed cards include the agent field).
+        const resolvedAgent = resolveAgentKind(value.agent, this.config.defaultAgent);
+        const entry = this.sessionStore.get(ctx.userId);
+        const cwd = entry?.cwd;
+        if (!cwd) {
+            await this.bridge.sendResult({ text: '请先 /cd 设置工作目录' }, ctx);
+            return;
+        }
+        // 校验前不得写入 sessionId。旧实现先无条件 setSessionId 再调
+        // cmdResume 校验，过期卡片（session 不在当前 cwd）校验失败时 store 已被
+        // 污染；value.sessionId 缺失时还会静默清空已有绑定。现在统一走 cmdResume
+        // 的已验证路径（:2352 校验通过才写入），sessionId 缺失直接报错。
+        if (!value.sessionId) {
+            await this.bridge.sendResult({ text: '缺少 sessionId，请重新从 /resume 列表选择会话' }, ctx);
+            return;
+        }
+        await this.bridge.sendResult(this.cmdResume([resolvedAgent, value.sessionId], ctx), ctx);
+    }
+    /** new-session: 清空当前会话绑定，下一条消息开始全新对话。 */
+    async handleNewSession(ctx) {
+        this.sessionStore.clearSessionId(ctx.userId, this.config.defaultAgent, {
+            clearSessionCwd: true,
+        });
+        const cwd = this.sessionStore.getCwd(ctx.userId) ?? '(未设置)';
+        const agentName = agentDisplayName(this.config.defaultAgent);
+        await this.bridge.sendResult({ text: `已创建新 ${agentName} 会话，下一条消息将开始全新对话\n📁 ${cwd}` }, ctx);
+    }
+    /** compact: 对当前会话发起压缩（bridge 收口）。 */
+    async handleCompact(value, ctx) {
+        await this.bridge.handleCompactAction(value, ctx);
+    }
+    /** resume.compact: 对 /resume 选中的历史会话发起压缩（bridge 收口）。 */
+    async handleResumeCompact(value, ctx) {
+        await this.bridge.handleResumeCompact(value, ctx);
+    }
+    /**
+     * Help card buttons: help.<cmd> → execute /<cmd>.
+     * /exit、/restart 等命令通过 pendingExit 表达"回复送达后退出"。
+     * handle() 在 sendResult 后消费它；help.* 按钮点击走 handleCardAction，
+     * 必须同样消费，否则点击 /restart 按钮 spawn 成功后旧进程不退出，
+     * 新进程撞单例锁退出 → 重启两头落空（2026-08-01 红绿 anchor 锁定）。
+     */
+    async handleHelpAction(value, ctx) {
+        const subCmd = value.cmd.slice(5); // e.g. "status", "ps", "stop"
+        const result = await this.executeCommand(`/${subCmd}`, ctx);
+        if (result) {
+            await this.bridge.sendResult(result, ctx);
+        }
+        if (this.pendingExit) {
+            await this.flushInbound?.();
+            this.exitHandler();
+        }
+    }
+    /**
+     * Design constraint: miss paths must reply via bridge.sendResult —
+     * don't silently swallow unknown card actions.
+     */
+    async handleUnknownCardAction(value, ctx) {
+        getLogger().warn(`[router] unknown card action: ${value.cmd}`);
+        await this.bridge.sendResult({ text: `⚠️ 未知的卡片操作: ${value.cmd}` }, ctx);
+    }
     /**
      * Handle approval-related card actions.
      * Routes to the appropriate bridge method based on value.cmd.
@@ -1319,17 +1344,18 @@ 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
+        // card stop button silently no-op'd when the
         // run had already exited. Give the user a visible result.
         if (!stopped) {
             await this.bridge.sendResult({ text: '该任务已结束，无需终止' }, ctx);
@@ -1809,8 +1835,6 @@ export class CommandRouter {
         this.configCardIds.add(messageId);
         while (this.configCardIds.size > MAX_CONFIG_CARDS) {
             const oldest = this.configCardIds.values().next().value;
-            if (oldest === undefined)
-                break;
             this.configCardIds.delete(oldest);
         }
     }
@@ -1857,7 +1881,7 @@ export class CommandRouter {
         }
     }
     /**
-     * 串行化 config.* 卡片回调（2026-07-04 修复连击卡死 bug）。
+     * 串行化 config.* 卡片回调（修复连击卡死 bug）。
      *
      * CardKit 2.0 input/button 回调经 `enqueueImmediate` 分发，不进 bridge 的
      * 串行队列；多次快速点击下拉/文本框会并发读写 `pendingConfig` 并同时调
@@ -1898,7 +1922,7 @@ export class CommandRouter {
             }
             case 'config.input': {
                 // Handle input field: value.key is the field key.
-                // 2026-07-04: CardKit 2.0 input 提交（回车/完成键）触发 callback，回传 input_value。
+                // CardKit 2.0 input 提交（回车/完成键）触发 callback，回传 input_value。
                 // Fall back to formValue[key]: the SDK currently reports input values
                 // via action.formValue for form-wrapped inputs.
                 const key = value.key;
@@ -1933,8 +1957,8 @@ export class CommandRouter {
                     // defaultAgent 切换的 session 处理）抽到共享方法，与文本直写路径共用。
                     const switchResult = this.propagateConfigSave(oldDefaultAgent, updates, ctx);
                     this.pendingConfig = null;
-                    // 原地更新卡片：保存后卡片刷新为已保存状态（2026-07-04）
-                    // 2026-08-03: 卡片刷新失败不吞切换通知——保存已成功，仅记录日志，
+                    // 原地更新卡片：保存后卡片刷新为已保存状态。
+                    // 卡片刷新失败不吞切换通知——保存已成功，仅记录日志，
                     // 后续切换消息照常发送；真正写盘/传播阶段的失败才走外层 catch 报「保存失败」。
                     try {
                         // host 可能已变更 → 重新预取 DSH 目录（内部按 host 缓存，未变不重复拉）
@@ -1944,7 +1968,7 @@ export class CommandRouter {
                     catch (refreshErr) {
                         getLogger().warn(`[router] config.save 卡片刷新失败（保存已成功）: ${refreshErr.message}`);
                     }
-                    // 2026-08-13: agent 切换时发送 Resume 卡片（替代纯文本通知），
+                    // agent 切换时发送 Resume 卡片（替代纯文本通知），
                     // 让用户直观看到新 agent 的会话状态和历史。
                     // 发送失败（resolve false）时兜底回退 toast 即时反馈。
                     if (switchResult.notice) {
@@ -1995,7 +2019,7 @@ export class CommandRouter {
         // idle.watchdogMinutes 改动需同步到 bridge 的 idleTimeoutMs
         this.idleTimeoutMs = this.config.idle.watchdogMinutes * 60_000;
         this.bridge.setIdleTimeout(this.idleTimeoutMs);
-        // 2026-07-13: 检测是否有任何 agent 配置变更或 defaultAgent 切换
+        // 检测是否有任何 agent 配置变更或 defaultAgent 切换
         const hasDefaultAgentChange = oldDefaultAgent !== this.config.defaultAgent;
         const changedKeys = Object.keys(updates);
         const hasAgentConfigChange = changedKeys.includes('defaultAgent') ||
@@ -2069,7 +2093,7 @@ export class CommandRouter {
         };
         parkDshSessionBoundary(changedKeys.includes('agents.dsh.agentPreset'), 'preset');
         parkDshSessionBoundary(changedKeys.includes('agents.dsh.host'), 'host');
-        // 2026-07-13: 同步 agent 配置到 agentChoices（用于切换 agent 时恢复配置）
+        // 同步 agent 配置到 agentChoices（用于切换 agent 时恢复配置）
         const currentAgent = this.config.defaultAgent;
         if (touchesAgentsSubtree(changedKeys, currentAgent)) {
             this.config = syncAgentChoices(this.config, currentAgent);
@@ -2088,7 +2112,7 @@ export class CommandRouter {
         if (hasApprovalConfigChange) {
             this.bridge.syncActiveApprovalModes();
         }
-        // 2026-07-13: 任何 agent 配置变更或 defaultAgent 切换，都清除 runner 缓存
+        // 任何 agent 配置变更或 defaultAgent 切换，都清除 runner 缓存
         if (hasDefaultAgentChange || hasAgentConfigChange) {
             this.bridge.clearRunners();
         }
@@ -2160,8 +2184,8 @@ export class CommandRouter {
     // --- Command implementations ---
     cmdHelp() {
         // 按钮组（可直接点击触发；按钮 label 只保留子命令，不含参数）
-        // 2026-07-04: /ws 子命令 (save|use|remove) 移到右侧文本说明，按钮只显示 /ws
-        // 2026-07-04: 按钮 label 按长度升序排列（短在上，长在下），视觉更整齐
+        // /ws 子命令 (save|use|remove) 移到右侧文本说明，按钮只显示 /ws
+        // 按钮 label 按长度升序排列（短在上，长在下），视觉更整齐
         const buttonCommands = [
             { cmd: 'help', label: '/help /h', desc: '显示此帮助' },
             { cmd: 'ps', label: '/ps', desc: '查看是否有 agent 进程在跑' },
@@ -2202,11 +2226,11 @@ export class CommandRouter {
         ];
         const bodyElements = [];
         // 按钮组 — CardKit 2.0: column_set + column + button with behaviors
-        // 2026-07-04 对齐修复（方案 A）：两列都用 width:'weighted' + 固定 weight。
+        // 对齐修复（方案 A）：两列都用 width:'weighted' + 固定 weight。
         // 根因：每行独立 column_set + width:'auto' → 列宽随按钮/文本内容变化 →
         // 跨行不对齐（按钮列右边界参差）。改用 weighted 后，每行 column_set
         // 总宽相同（同级 body.elements），weight 比例一致，列宽跨行恒等。
-        // 2026-07-05 手机排版修复：weight 1:3 → 2:3。1:3 时按钮列只占 25%，
+        // 手机排版修复：weight 1:3 → 2:3。1:3 时按钮列只占 25%，
         // 手机窄屏（~330px 可用）下约 82px，容不下 `/config /c`（10 字符 ≈ 100px），
         // 按钮文字被截断成 "..."。改 2:3 后按钮列占 40% ≈ 132px，足够显示
         // 最长的 /config /c，文本列仍占 60% 足以放下描述。
@@ -2459,8 +2483,8 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
     }
     cmdNew(ctx) {
         // 只清 sessionId 保留 cwd — 否则 /new 之后 /resume 会提示"请先 /cd
-        // 设置工作目录"，但用户的 cwd 还在。2026-06-21 复盘：用户
-        // /new → /resume 后被误导以为需要重新 /cd。
+        // 设置工作目录"，但用户的 cwd 还在，用户 /new → /resume 后会被误导
+        // 以为需要重新 /cd。
         const agentName = agentDisplayName(this.config.defaultAgent);
         this.sessionStore.clearSessionId(ctx.userId, this.config.defaultAgent, {
             clearSessionCwd: true,
@@ -2545,38 +2569,66 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
     }
     /** Build card for auto-resumed session with new session button */
     buildAutoResumeCard(cwd, session, _ctx) {
-        const agentName = agentDisplayName(this.config.defaultAgent);
-        const { events: content, usage, isActive, aiTitle, recap, displayTitle, activeRunRunId, } = this.readSessionDisplayState(session.sessionId, cwd, { maxEvents: AUTO_RESUME_MAX_EVENTS });
+        const agentKind = this.config.defaultAgent;
+        return this.buildResumeLikeCard({
+            cwd,
+            sessionId: session.sessionId,
+            agentKind,
+            // 仅 auto-resume 入口带 Compact 按钮（runner 支持压缩时）；
+            // config-switch 卡不带。
+            compact: this.canCompactSession(agentKind, cwd)
+                ? { sessionId: session.sessionId, agentKind }
+                : undefined,
+            titleBase: '自动恢复会话',
+            idleIcon: '🔁',
+            resumedLine: `已恢复最近会话: **${session.sessionId}**`,
+        });
+    }
+    /**
+     * Shared body of the two "resume-like" cards（cwd 切换后的 auto-resume 与
+     * config.save 换 agent）：两者都是同一序列 readSessionDisplayState →
+     * buildResumeActionButtons → buildSessionHistoryCard，差异仅 4 处——
+     * Compact 按钮（仅 auto-resume，canCompactSession 门控）、标题文案、
+     * headerText 的「已恢复…会话」行与可选尾部行、空会话占位——全部参数化，
+     * 共享序列只留一份（Clean Code DRY）。
+     */
+    buildResumeLikeCard(opts) {
+        const agentName = agentDisplayName(opts.agentKind);
+        const { events: content, usage, isActive, aiTitle, recap, displayTitle, activeRunRunId, } = this.readSessionDisplayState(opts.sessionId, opts.cwd, {
+            // 默认 agent 时 readSessionDisplayState 内部仍走 this.sessionReader
+            //（agentKind === defaultAgent 不触发 registry 查找），与旧的不传等价。
+            agentKind: opts.agentKind,
+            maxEvents: AUTO_RESUME_MAX_EVENTS,
+        });
         const actions = this.buildResumeActionButtons({
             isActive,
             activeRunRunId,
-            cwd,
-            compact: this.canCompactSession(this.config.defaultAgent, cwd)
-                ? { sessionId: session.sessionId, agentKind: this.config.defaultAgent }
-                : undefined,
+            cwd: opts.cwd,
+            compact: opts.compact,
             newSession: true,
         });
         const card = buildSessionHistoryCard({
-            sessionId: session.sessionId,
-            cwd,
+            sessionId: opts.sessionId,
+            cwd: opts.cwd,
             displayTitle,
             aiTitle,
             recap,
             events: content,
             usage,
         }, {
-            agentKind: this.config.defaultAgent,
-            headerText: `📂 \`${cwd}\`\n已恢复最近会话: **${session.sessionId}**`,
-            title: `${isActive ? '⏳ 自动恢复会话（完成中）' : '🔁 自动恢复会话'} · ${agentName}`,
+            agentKind: opts.agentKind,
+            headerText: `📂 \`${opts.cwd}\`\n${opts.resumedLine}${opts.headerTail ? `\n${opts.headerTail}` : ''}`,
+            title: `${isActive ? `⏳ ${opts.titleBase}（完成中）` : `${opts.idleIcon} ${opts.titleBase}`} · ${agentName}`,
             usageResult: 'success',
+            ...(opts.emptyPlaceholder !== undefined ? { emptyPlaceholder: opts.emptyPlaceholder } : {}),
             actions,
         });
         return { card };
     }
     /**
      * Build card for config.save agent switch.
-     * When the new agent has a restored session, renders a Resume card (mirrors
-     * buildAutoResumeCard) with session history + stop/new buttons.
+     * When the new agent has a restored session, renders a Resume card (shared
+     * body via buildResumeLikeCard) with session history + stop/new buttons.
      * When the session was cleared, renders a compact notice card instead.
      */
     buildConfigSwitchCard(switchResult, ctx) {
@@ -2600,62 +2652,25 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 },
             };
         }
-        // Has session → Resume card (mirrors buildAutoResumeCard)
-        // Guard: if the session reader for the new agent is not available (e.g. agent
-        // not registered), fall back to compact notice card to avoid NPE.
-        const readerForNewAgent = newAgent === this.config.defaultAgent
-            ? this.sessionReader
-            : this.sessionReaderRegistry.get(newAgent);
-        if (!readerForNewAgent) {
-            // Fallback: compact notice card with the notice text
-            const elements = [markdownDiv(switchResult.notice)];
-            elements.push({
-                tag: 'column_set',
-                columns: [
-                    {
-                        tag: 'column',
-                        width: 'auto',
-                        elements: [newSessionButton()],
-                    },
-                ],
-            });
-            return {
-                card: {
-                    schema: '2.0',
-                    config: { wide_screen_mode: true },
-                    header: { title: { tag: 'plain_text', content: `🔀 切换到 ${agentName}` } },
-                    body: { elements },
-                },
-            };
-        }
-        const { events: content, usage, isActive, aiTitle, recap, displayTitle, activeRunRunId, } = this.readSessionDisplayState(sessionId, cwd, {
-            agentKind: newAgent,
-            maxEvents: AUTO_RESUME_MAX_EVENTS,
-        });
-        // Action buttons: stop (active) + new session
-        const actions = this.buildResumeActionButtons({
-            isActive,
-            activeRunRunId,
+        // Has session → Resume card (shared body with buildAutoResumeCard)
+        // SessionReaderRegistry.get() throws when the agent is not registered —
+        // a null-reader fallback branch here is unreachable either way.
+        return this.buildResumeLikeCard({
             cwd,
-            newSession: true,
-        });
-        const card = buildSessionHistoryCard({
             sessionId,
-            cwd,
-            displayTitle,
-            aiTitle,
-            recap,
-            events: content,
-            usage,
-        }, {
             agentKind: newAgent,
-            headerText: `📂 \`${cwd}\`\n已恢复会话: **${sessionId}**`,
-            title: `${isActive ? '⏳ 切换 Agent（完成中）' : '🔀 切换 Agent'} · ${agentName}`,
-            usageResult: 'success',
+            titleBase: '切换 Agent',
+            idleIcon: '🔀',
+            // 切换语义（已使用所选 / 将继续之前的 / 已清空）必须随卡可见：
+            // 2026-08-13 换 Resume 卡时这条信息一度只在「无 reader」回退分支
+            // 渲染，生产路径（registry 恒有 reader）上不可见——卡上只剩
+            // sessionId，用户无法区分显式选择、停车恢复与清空。notice 含
+            // sessionId，与「已恢复会话」行并存（agent-switch-entry-points 与
+            // arrival-baseline 两族 anchor 分别钉住两行）。
+            resumedLine: `已恢复会话: **${sessionId}**`,
+            headerTail: switchResult.notice,
             emptyPlaceholder: '_该会话暂无新消息可显示（最后一条为用户输入）_',
-            actions,
         });
-        return { card };
     }
     /**
      * Whether a session of the given agent kind can be compacted from a resume
@@ -2700,7 +2715,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
      * @param offset  分页起点（条目数）
      * @param rootDir 浏览起点：卡片「返回」按钮回到这里。省略时默认 = 本次列出的
      *                目录（`/ls <dir>` 的起点即该目录），因此「返回」不会把用户
-     *                丢回 工作目录（用户明确反馈过）。
+     *                丢回 工作目录。
      * @param q       关键词筛选：只匹配**当前层**条目名（不递归），大小写不敏感。
      *                省略/空 = 无筛选。
      */
@@ -2790,7 +2805,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
     }
     cmdActive(_args, _ctx, offset = 0) {
         // List all active runs from lark-remote memory (not from file system scan)
-        // New semantics (2026-07-20): only shows runs started by THIS lark-remote process
+        // (only shows runs started by THIS lark-remote process)
         const activeRuns = this.bridge.getActiveRuns();
         const activeBashRuns = this.bridge.getActiveBashRuns();
         if (activeRuns.length === 0 && activeBashRuns.length === 0) {
@@ -2814,54 +2829,31 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         const elements = [];
         let remaining = pageSize;
         let skipped = safeOffset;
-        // Agent runs section
-        if (activeRuns.length > 0 && skipped < activeRuns.length && remaining > 0) {
-            elements.push({ tag: 'div', text: { tag: 'lark_md', content: '## 🤖 Agent 任务' } });
-            const start = skipped;
-            const end = Math.min(start + remaining, activeRuns.length);
-            for (let i = start; i < end; i++) {
-                const run = activeRuns[i];
-                const statusLabel = run.terminal === 'running' ? '运行中' : '处理中';
-                elements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: `**📂 ${displayName(run.cwd)}**` },
-                });
-                elements.push({
-                    tag: 'div',
-                    text: {
-                        tag: 'lark_md',
-                        content: `> session: ${run.sessionId.slice(0, 12)}...  \n> 状态: ${statusLabel}`,
-                    },
-                });
-                elements.push(cardButton('⏹ 停止', { cmd: 'stop', runId: run.runId, cwd: run.cwd }, { type: 'danger', size: 'small' }));
-                elements.push({ tag: 'hr' });
-            }
-            remaining -= end - start;
-            skipped = 0;
-        }
-        else {
-            skipped -= activeRuns.length;
-        }
-        // Bash runs section
-        if (activeBashRuns.length > 0 && skipped < activeBashRuns.length && remaining > 0) {
-            elements.push({ tag: 'div', text: { tag: 'lark_md', content: '## 💻 Bash 命令' } });
-            const start = skipped;
-            const end = Math.min(start + remaining, activeBashRuns.length);
-            for (let i = start; i < end; i++) {
-                const run = activeBashRuns[i];
-                const statusLabel = run.terminal === 'running' ? '运行中' : '处理中';
-                elements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: `**\`${run.command}\`**` },
-                });
-                elements.push({
-                    tag: 'div',
-                    text: { tag: 'lark_md', content: `> 目录: ${run.cwd}  \n> 状态: ${statusLabel}` },
-                });
-                elements.push(cardButton('⏹ 停止', { cmd: 'stop', runId: run.runId, cwd: run.cwd }, { type: 'danger', size: 'small' }));
-                elements.push({ tag: 'hr' });
-            }
-        }
+        // Agent runs section（跨段 offset 分配：agent 段吃满 remaining 才轮到 bash 段）
+        ({ remaining, skipped } = this.appendActiveCardSection(elements, activeRuns, '## 🤖 Agent 任务', (run, statusLabel) => [
+            {
+                tag: 'div',
+                text: { tag: 'lark_md', content: `**📂 ${displayName(run.cwd)}**` },
+            },
+            {
+                tag: 'div',
+                text: {
+                    tag: 'lark_md',
+                    content: `> session: ${run.sessionId.slice(0, 12)}...  \n> 状态: ${statusLabel}`,
+                },
+            },
+        ], remaining, skipped));
+        // Bash runs section（末段：不再使用返回的记账值）
+        this.appendActiveCardSection(elements, activeBashRuns, '## 💻 Bash 命令', (run, statusLabel) => [
+            {
+                tag: 'div',
+                text: { tag: 'lark_md', content: `**\`${run.command}\`**` },
+            },
+            {
+                tag: 'div',
+                text: { tag: 'lark_md', content: `> 目录: ${run.cwd}  \n> 状态: ${statusLabel}` },
+            },
+        ], remaining, skipped);
         // Pagination bar（复用 paginationBar：safeOffset 已对齐页边界，
         // offset±pageSize 与原先 currentPage±1 的页码换算等价）
         if (totalPages > 1) {
@@ -2886,6 +2878,34 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         };
         return { card };
     }
+    /**
+     * Render one section of the /active（/ps）card — the agent-runs and
+     * bash-runs sections are the same loop (title line → per-entry rows →
+     * stop button → trailing hr) and differ only in the title and the two
+     * per-entry content rows, which the caller supplies via `renderRows`.
+     *
+     * Cross-section offset accounting (caller threads `remaining`/`skipped`
+     * through the returned value): entries rendered decrement `remaining` and
+     * consume the offset (`skipped` → 0, so the next section renders from its
+     * own head); a section the offset/page has moved past deducts its full size
+     * from `skipped` instead, so agent runs eat the offset before bash runs do.
+     */
+    appendActiveCardSection(elements, runs, title, renderRows, remaining, skipped) {
+        if (runs.length > 0 && skipped < runs.length && remaining > 0) {
+            elements.push({ tag: 'div', text: { tag: 'lark_md', content: title } });
+            const start = skipped;
+            const end = Math.min(start + remaining, runs.length);
+            for (let i = start; i < end; i++) {
+                const run = runs[i];
+                const statusLabel = run.terminal === 'running' ? '运行中' : '处理中';
+                elements.push(...renderRows(run, statusLabel));
+                elements.push(cardButton('⏹ 停止', { cmd: 'stop', runId: run.runId, cwd: run.cwd }, { type: 'danger', size: 'small' }));
+                elements.push({ tag: 'hr' });
+            }
+            return { remaining: remaining - (end - start), skipped: 0 };
+        }
+        return { remaining, skipped: skipped - runs.length };
+    }
     async cmdConfig(args, ctx) {
         // Ensure probe cache is populated before building the card.
         await probeAllAgents();
@@ -2912,21 +2932,21 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 // defaultAgent 不再漏判。
                 const switchResult = this.propagateConfigSave(oldDefaultAgent, { [mapAgentKey(key)]: value }, ctx);
                 this.pendingConfig = null; // 命令式写盘后清空暂存，避免不一致
-                // 2026-08-13: agent 切换时额外发送 Resume 卡片
+                // agent 切换时额外发送 Resume 卡片
                 if (switchResult.notice) {
                     const switchCard = this.buildConfigSwitchCard(switchResult, ctx);
                     // 文本路径返回 config card，Resume card 通过 bridge 异步发送
                     void this.bridge.sendResult(switchCard, ctx);
                 }
                 const card = this.buildConfigCard();
-                if (discarded > 0 && card.card && typeof card.card === 'object') {
+                if (discarded > 0) {
+                    // buildConfigCardFromTabs 恒返回 body.elements（至少含保存按钮），
+                    // 这里直接收窄插入提示条——同模块自己刚构建的值无需逐层探测。
                     const body = card.card.body;
-                    if (body && Array.isArray(body.elements)) {
-                        body.elements.unshift({
-                            tag: 'div',
-                            text: { tag: 'lark_md', content: `⚠️ 已丢弃 ${discarded} 项未保存修改` },
-                        });
-                    }
+                    body.elements.unshift({
+                        tag: 'div',
+                        text: { tag: 'lark_md', content: `⚠️ 已丢弃 ${discarded} 项未保存修改` },
+                    });
                 }
                 return card;
             }