lark-remote 0.5.19 → 0.5.21

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']);
@@ -362,6 +362,169 @@ function touchesAgentsSubtree(keys, kind) {
 function touchesAgentConfig(keys, kind) {
     return (touchesAgentsSubtree(keys, kind) || keys.some((k) => k === kind || k.startsWith(`${kind}.`)));
 }
+const CARD_ACTION_SPECS = new Map([
+    ['ls.file', { method: 'cardLsFile', args: 'path' }],
+    ['ls.refresh', { method: 'handleLsRefresh', args: 'voidCall' }],
+    ['ls.browse', { method: 'handleLsBrowse', args: 'voidCall' }],
+    ['ls.switch', { method: 'handleLsSwitch', args: 'voidCall' }],
+    ['ls.page', { method: 'handleLsPage', args: 'returnCall' }],
+    ['ls.filter', { method: 'handleLsFilter', args: 'returnCall' }],
+    ['ws.page', { method: 'handleWsPage', args: 'returnCall' }],
+    ['ws.filter', { method: 'handleWsFilter', args: 'returnCall' }],
+    ['ws.use', { method: 'handleWsUse', args: 'returnCall' }],
+    ['ws.sort', { method: 'handleWsSort', args: 'returnCall' }],
+    ['ws.remove', { method: 'handleWsRemove', args: 'returnCall' }],
+    ['resume.use', { method: 'handleResumeUse', args: 'voidCall' }],
+    ['resume.page', { method: 'handleResumePage', args: 'returnCall' }],
+    ['active.page', { method: 'handleActivePage', args: 'returnCall' }],
+    ['new-session', { method: 'handleNewSession', args: 'ctxOnly' }],
+    ['stop', { method: 'handleCardStop', args: 'voidCall' }],
+    ['job.kill', { method: 'handleJobKill', args: 'voidCall' }],
+    ['queue.cancel', { method: 'handleQueueCancel', args: 'voidCall' }],
+    ['queue.immediate', { method: 'handleQueueImmediate', args: 'voidCall' }],
+    ['queue.diagnose', { method: 'handleQueueDiagnose', args: 'voidCall' }],
+    ['queue.edit', { method: 'handleQueueEdit', args: 'voidCall' }],
+    ['queue.input', { method: 'handleQueueInput', args: 'returnCall' }],
+    ['order.delete', { method: 'handleOrderDelete', args: 'returnCall' }],
+    ['order.page', { method: 'handleOrderPage', args: 'returnCall' }],
+    ['order.aliasEdit', { method: 'handleOrderAliasEdit', args: 'returnCall' }],
+    ['order.aliasInput', { method: 'handleOrderAliasInput', args: 'returnCall' }],
+    ['order.aliasRemove', { method: 'handleOrderAliasRemove', args: 'returnCall' }],
+    ['order.textEdit', { method: 'handleOrderTextEdit', args: 'returnCall' }],
+    ['order.textInput', { method: 'handleOrderTextInput', args: 'returnCall' }],
+    ['config.set', { method: 'enqueueConfigAction', args: 'returnCall' }],
+    ['config.input', { method: 'enqueueConfigAction', args: 'returnCall' }],
+    ['config.save', { method: 'enqueueConfigAction', args: 'returnCall' }],
+    ['compact', { method: 'handleCompact', args: 'voidCall' }],
+    ['resume.compact', { method: 'handleResumeCompact', args: 'voidCall' }],
+]);
+const COMMAND_SPECS = new Map([
+    ['help', { method: 'cmdHelp', args: 'none' }],
+    ['h', { method: 'cmdHelp', args: 'none' }],
+    ['status', { method: 'cmdStatus', args: 'ctxOnly' }],
+    ['s', { method: 'cmdStatus', args: 'ctxOnly' }],
+    ['ps', { method: 'cmdPs', args: 'ctxOnly' }],
+    ['stop', { method: 'cmdStop', args: 'ctxOnly' }],
+    ['t', { method: 'cmdStop', args: 'ctxOnly' }],
+    ['exit', { method: 'cmdExit', args: 'none' }],
+    ['quit', { method: 'cmdExit', args: 'none' }],
+    ['e', { method: 'cmdExit', args: 'none' }],
+    ['restart', { method: 'cmdRestart', args: 'none' }],
+    ['new', { method: 'cmdNew', args: 'ctxOnly' }],
+    ['cd', { method: 'cmdCd', args: 'argsCtx' }],
+    ['ls', { method: 'cmdLs', args: 'argsCtx' }],
+    ['download', { method: 'cmdDownload', args: 'argsCtx' }],
+    ['d', { method: 'cmdDownload', args: 'argsCtx' }],
+    ['ws', { method: 'cmdWs', args: 'argsCtx' }],
+    ['resume', { method: 'cmdResume', args: 'argsCtx' }],
+    ['r', { method: 'cmdResume', args: 'argsCtx' }],
+    ['active', { method: 'cmdActive', args: 'argsCtx' }],
+    ['config', { method: 'cmdConfig', args: 'argsCtx' }],
+    ['c', { method: 'cmdConfig', args: 'argsCtx' }],
+    ['order', { method: 'cmdOrder', args: 'argsCtx' }],
+    ['o', { method: 'cmdOrder', args: 'argsCtx' }],
+    ['update', { method: 'cmdUpdate', args: 'argsCtx' }],
+    ['u', { method: 'cmdUpdate', args: 'argsCtx' }],
+    ['clone', { method: 'cmdClone', args: 'argsCtx' }],
+]);
+/** 命令名 → 命令方法查表分发；无匹配时返回与旧 default 分支一致的文案。 */
+function dispatchCommand(router, cmd, args, ctx) {
+    const spec = COMMAND_SPECS.get(cmd ?? '');
+    if (!spec) {
+        return { text: `未知命令 /${cmd}，输入 /help 查看可用命令` };
+    }
+    const handler = router[spec.method];
+    if (spec.args === 'none') {
+        return handler.call(router);
+    }
+    if (spec.args === 'ctxOnly') {
+        return handler.call(router, ctx);
+    }
+    return handler.call(router, args, ctx);
+}
+/**
+ * defaultAgent 切换时的 session 迁移（Step 0-3）。抽为模块级命名函数，
+ * 避免其内部分支与判定闭包计入外层 propagateConfigSave 的 CC。
+ */
+function applyDefaultAgentSwitch(sessionStore, userId, oldDefaultAgent, newAgent) {
+    // Step 0: 在清空 old 之前计算「用户活动」基线差（arrival 基线）：
+    const oldSessionId = sessionStore.getSessionId(userId, oldDefaultAgent);
+    const oldArrivalSessionId = sessionStore.getArrivalSessionId(userId, oldDefaultAgent);
+    const userChangedOld = (oldSessionId ?? '') !== (oldArrivalSessionId ?? '');
+    // Step 1: 保存旧 agent 的 session 到 previousSessions（如果有）
+    if (oldSessionId) {
+        sessionStore.setPreviousSessionId(userId, oldDefaultAgent, oldSessionId);
+    }
+    // Step 2: 清除旧 agent 的 session（保存后清除，为新会话腾出空间）
+    sessionStore.clearSessionId(userId, oldDefaultAgent);
+    // Step 2.5: 显式选择判定
+    const newSessionId = sessionStore.getSessionId(userId, newAgent);
+    const newArrivalSessionId = sessionStore.getArrivalSessionId(userId, newAgent);
+    const userSelectedNew = !!newSessionId && (newSessionId ?? '') !== (newArrivalSessionId ?? '');
+    // Step 3: 恢复判定
+    const previousSessionId = sessionStore.getPreviousSessionId(userId, newAgent);
+    const canRestore = !!previousSessionId && !userChangedOld;
+    if (userSelectedNew) {
+        sessionStore.setArrivalSessionId(userId, newAgent, newSessionId);
+        const newAgentName = agentDisplayName(newAgent);
+        return {
+            notice: `已切换到 ${newAgentName}，已使用所选 session，sessionId: ${newSessionId}`,
+            newAgent,
+            sessionId: newSessionId,
+        };
+    }
+    if (canRestore) {
+        sessionStore.setSessionId(userId, newAgent, previousSessionId);
+        sessionStore.clearPreviousSessionId(userId, newAgent);
+        sessionStore.setArrivalSessionId(userId, newAgent, previousSessionId);
+        const newAgentName = agentDisplayName(newAgent);
+        return {
+            notice: `已切换到 ${newAgentName}，将继续之前的 session，sessionId: ${previousSessionId}`,
+            newAgent,
+            sessionId: previousSessionId,
+        };
+    }
+    sessionStore.clearSessionId(userId, newAgent, { clearSessionCwd: true });
+    sessionStore.setArrivalSessionId(userId, newAgent, '');
+    const newAgentName = agentDisplayName(newAgent);
+    return {
+        notice: `已切换到 ${newAgentName}，session 已清空，下次消息将启动新对话`,
+        newAgent,
+        sessionId: '',
+    };
+}
+/**
+ * DSH 会话边界变更（preset/host）共用的 notice 计算。返回更新后的 notice；
+ * 条件不满足时原样返回 currentNotice，等价于原闭包「不修改」的语义。
+ */
+function parkDshSessionBoundaryNotice(sessionStore, userId, defaultAgent, changed, label, currentNotice) {
+    if (!changed || defaultAgent !== 'dsh' || currentNotice)
+        return currentNotice;
+    const oldSessionId = sessionStore.getSessionId(userId, 'dsh');
+    if (oldSessionId) {
+        sessionStore.setPreviousSessionId(userId, 'dsh', oldSessionId);
+        sessionStore.clearSessionId(userId, 'dsh');
+        return `DSH ${label} 已变更，旧会话已停放到恢复槽（可 /resume 校验后恢复），下次消息将新建会话`;
+    }
+    return `DSH ${label} 已变更，下次消息将新建会话`;
+}
+function computeHasAgentConfigChange(changedKeys) {
+    if (changedKeys.includes('defaultAgent'))
+        return true;
+    for (const kind of AGENT_KINDS) {
+        if (touchesAgentConfig(changedKeys, kind))
+            return true;
+    }
+    return false;
+}
+const APPROVAL_AGENT_KINDS = ['codex', 'kimi', 'opencode'];
+function computeHasApprovalConfigChange(changedKeys) {
+    for (const kind of APPROVAL_AGENT_KINDS) {
+        if (touchesAgentConfig(changedKeys, kind))
+            return true;
+    }
+    return changedKeys.includes('agents.dsh.permissionPreset');
+}
 export class CommandRouter {
     sessionStore;
     /** 飞书桥接实例（public：测试直接访问断言，替代 as unknown as）。 */
@@ -400,8 +563,8 @@ export class CommandRouter {
      *
      * 草稿（pendingConfig）是全局一份：/config 文本命令重开卡片时沿用同一份草稿
      * （这是既有语义，不改）。但**视图**是每张卡一份 —— 只刷新被点击的那张，其余
-     * 卡片就停在旧视图上：用户在旧卡上看到的和点保存实际提交的是两套内容
-     * （2026-10-08 发现的缺陷）。这里记住所有交互过的 config 卡，任何一次编辑/保存
+     * 卡片就停在旧视图上：用户在旧卡上看到的和点保存实际提交的是两套内容。
+     * 这里记住所有交互过的 config 卡，任何一次编辑/保存
      * 后把草稿刷到每张卡，保证「看到的就是会保存的」。
      */
     configCardIds = new Set();
@@ -412,7 +575,7 @@ export class CommandRouter {
      * 条目的身份必须与「一次入队动作」1:1（queuedTasks 的定位、queueCardMessages
      * 的卡片更新、taskIndex 的取消判据全部按这个 key 做 lookup）。复用卡片 id
      * 会让同 key 的多条任务互相顶替：位置显示命中最早那条兄弟、第一条开始时删掉
-     * 索引导致其余兄弟被判「已撤销」静默丢弃（2026-10-08 线上：连点 Compact
+     * 索引导致其余兄弟被判「已撤销」静默丢弃（连点 Compact
      * 三次 → 三张排队卡都显示「第 1 位」、两张永久停在「等待中」，只压缩一次）。
      *
      * Date.now() 不够（两次同步调用可落在同一毫秒）；计数器与时间无关，恒唯一。
@@ -433,7 +596,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 +646,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_…"`）。
      * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
@@ -560,147 +723,98 @@ export class CommandRouter {
         if (APPROVAL_ACTION_CMDS.includes(value.cmd)) {
             return this.handleApprovalAction(value, ctx);
         }
-        switch (value.cmd) {
-            case 'ls.file':
-                await this.cardLsFile(value.path, ctx);
-                return;
-            case 'ls.refresh':
-                await this.handleLsRefresh(value, ctx);
-                return;
-            case 'ls.browse':
-                await this.handleLsBrowse(value, ctx);
-                return;
-            case 'ls.switch':
-                await this.handleLsSwitch(value, ctx);
-                return;
-            case 'ls.page':
-                return this.handleLsPage(value, ctx);
-            case 'ls.filter':
-                return this.handleLsFilter(value, ctx);
-            case 'ws.page':
-                return this.handleWsPage(value, ctx);
-            case 'ws.filter':
-                return this.handleWsFilter(value, ctx);
-            case 'ws.use':
-                return await this.handleWsUse(value, ctx);
-            case 'ws.sort':
-                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);
+        const spec = CARD_ACTION_SPECS.get(value.cmd);
+        if (spec) {
+            // Map 查表取出的是未绑定方法，必须显式 .call(this, ...) 保留类实例上下文。
+            const handler = this[spec.method];
+            if (spec.args === 'path') {
+                await handler.call(this, value.path, 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);
-                }
-                return;
-            case 'stop':
-                await this.handleCardStop(value, ctx);
+            if (spec.args === 'ctxOnly') {
+                await handler.call(this, ctx);
                 return;
-            case 'job.kill':
-                await this.handleJobKill(value, ctx);
-                return;
-            case 'queue.cancel':
-                // 撤销：从队列中删除这个消息
-                await this.handleQueueCancel(value, ctx);
-                return;
-            case 'queue.immediate':
-                // 立即执行：停止当前进程，删除队列中这个消息之前的全部消息，立即执行这一条
-                await this.handleQueueImmediate(value, ctx);
-                return;
-            case 'queue.diagnose':
-                // 诊断：切换到项目目录，启动 Claude -p 定位问题
-                await this.handleQueueDiagnose(value, ctx);
-                return;
-            case 'queue.edit':
-                // 编辑：显示输入框让用户修改消息内容
-                await this.handleQueueEdit(value, ctx);
-                return;
-            case 'queue.input':
-                // 输入：提交新消息内容。返回 toast（SDK 作为飞书回调响应给点击用户即时反馈）。
-                return await this.handleQueueInput(value, ctx);
-            case 'order.delete':
-                return await this.handleOrderDelete(value, ctx);
-            case 'order.page':
-                return await this.handleOrderPage(value, ctx);
-            case 'order.aliasEdit':
-                return await this.handleOrderAliasEdit(value, ctx);
-            case 'order.aliasInput':
-                return await this.handleOrderAliasInput(value, ctx);
-            case 'order.aliasRemove':
-                return await this.handleOrderAliasRemove(value, ctx);
-            case 'order.textEdit':
-                return await this.handleOrderTextEdit(value, ctx);
-            case 'order.textInput':
-                return await this.handleOrderTextInput(value, ctx);
-            case 'config.set':
-            case 'config.input':
-            case 'config.save':
-                // 2026-07-04: 串行化所有 config.* 动作。CardKit 2.0 回调经 enqueueImmediate
-                // 不进串行队列，多次快速点击下拉/文本框会并发读写 pendingConfig 并同时
-                // 调 updateCardInPlace → Feishu API 乱序到达导致控件卡死。
-                // 2026-07-18: 返回 enqueueConfigAction 的结果以支持 toast 响应
-                return this.enqueueConfigAction(value, ctx);
-            case 'compact':
-                await this.bridge.handleCompactAction(value, ctx);
-                return;
-            case 'resume.compact':
-                await this.bridge.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();
-                    }
-                    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);
+            }
+            // voidCall 对应原 switch 的 `await this.xxx(...); return;`，丢弃返回值。
+            if (spec.args === 'voidCall') {
+                await handler.call(this, value, ctx);
                 return;
             }
+            return handler.call(this, value, ctx);
+        }
+        if (value.cmd.startsWith('help.')) {
+            await this.handleHelpAction(value, ctx);
+            return;
+        }
+        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.
@@ -1330,7 +1444,7 @@ export class CommandRouter {
             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);
@@ -1810,8 +1924,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);
         }
     }
@@ -1858,7 +1970,7 @@ export class CommandRouter {
         }
     }
     /**
-     * 串行化 config.* 卡片回调（2026-07-04 修复连击卡死 bug）。
+     * 串行化 config.* 卡片回调（修复连击卡死 bug）。
      *
      * CardKit 2.0 input/button 回调经 `enqueueImmediate` 分发，不进 bridge 的
      * 串行队列；多次快速点击下拉/文本框会并发读写 `pendingConfig` 并同时调
@@ -1899,7 +2011,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;
@@ -1934,8 +2046,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 缓存，未变不重复拉）
@@ -1945,7 +2057,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) {
@@ -1996,11 +2108,10 @@ 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') ||
-            AGENT_KINDS.some((kind) => touchesAgentConfig(changedKeys, kind));
+        const hasAgentConfigChange = computeHasAgentConfigChange(changedKeys);
         // 当 defaultAgent 改变时，清除旧 agent 的 sessionId，
         // 同时清除新 agent 的 sessionId（等效于 /new 命令），
         // 并支持 session 恢复 - 切换回来时如果条件满足则恢复之前的 session。
@@ -2008,46 +2119,10 @@ export class CommandRouter {
         let switchNewAgent;
         let switchSessionId;
         if (hasDefaultAgentChange) {
-            const newAgent = this.config.defaultAgent;
-            switchNewAgent = newAgent;
-            // Step 0: 在清空 old 之前计算「用户活动」基线差（arrival 基线）：
-            const oldSessionId = this.sessionStore.getSessionId(ctx.userId, oldDefaultAgent);
-            const oldArrivalSessionId = this.sessionStore.getArrivalSessionId(ctx.userId, oldDefaultAgent);
-            const userChangedOld = (oldSessionId ?? '') !== (oldArrivalSessionId ?? '');
-            // Step 1: 保存旧 agent 的 session 到 previousSessions（如果有）
-            if (oldSessionId) {
-                this.sessionStore.setPreviousSessionId(ctx.userId, oldDefaultAgent, oldSessionId);
-            }
-            // Step 2: 清除旧 agent 的 session（保存后清除，为新会话腾出空间）
-            this.sessionStore.clearSessionId(ctx.userId, oldDefaultAgent);
-            // Step 2.5: 显式选择判定
-            const newSessionId = this.sessionStore.getSessionId(ctx.userId, newAgent);
-            const newArrivalSessionId = this.sessionStore.getArrivalSessionId(ctx.userId, newAgent);
-            const userSelectedNew = !!newSessionId && (newSessionId ?? '') !== (newArrivalSessionId ?? '');
-            // Step 3: 恢复判定
-            const previousSessionId = this.sessionStore.getPreviousSessionId(ctx.userId, newAgent);
-            const canRestore = !!previousSessionId && !userChangedOld;
-            if (userSelectedNew) {
-                this.sessionStore.setArrivalSessionId(ctx.userId, newAgent, newSessionId);
-                const newAgentName = agentDisplayName(newAgent);
-                switchNotice = `已切换到 ${newAgentName}，已使用所选 session，sessionId: ${newSessionId}`;
-                switchSessionId = newSessionId;
-            }
-            else if (canRestore) {
-                this.sessionStore.setSessionId(ctx.userId, newAgent, previousSessionId);
-                this.sessionStore.clearPreviousSessionId(ctx.userId, newAgent);
-                this.sessionStore.setArrivalSessionId(ctx.userId, newAgent, previousSessionId);
-                const newAgentName = agentDisplayName(newAgent);
-                switchNotice = `已切换到 ${newAgentName}，将继续之前的 session，sessionId: ${previousSessionId}`;
-                switchSessionId = previousSessionId;
-            }
-            else {
-                this.sessionStore.clearSessionId(ctx.userId, newAgent, { clearSessionCwd: true });
-                this.sessionStore.setArrivalSessionId(ctx.userId, newAgent, '');
-                const newAgentName = agentDisplayName(newAgent);
-                switchNotice = `已切换到 ${newAgentName}，session 已清空，下次消息将启动新对话`;
-                switchSessionId = '';
-            }
+            const outcome = applyDefaultAgentSwitch(this.sessionStore, ctx.userId, oldDefaultAgent, this.config.defaultAgent);
+            switchNotice = outcome.notice;
+            switchNewAgent = outcome.newAgent;
+            switchSessionId = outcome.sessionId;
         }
         // DSH 的两个「会话边界」变更共用一套处理：preset 在 session 创建时固定，
         // 中途切换会被服务端拒绝（agent-preset-conflict）；host 变更等于换服务，
@@ -2055,22 +2130,9 @@ export class CommandRouter {
         // previousSessions 恢复槽（可 /resume 校验后恢复）并清空当前值，下次 run
         // 走 session.create 新建。已发生 agent 切换时（switchNotice 已设置）跳过，
         // 避免覆盖切换 notice——切换分支对 dsh 的 session 已做恢复/清空处理。
-        const parkDshSessionBoundary = (changed, label) => {
-            if (!changed || this.config.defaultAgent !== 'dsh' || switchNotice)
-                return;
-            const oldSessionId = this.sessionStore.getSessionId(ctx.userId, 'dsh');
-            if (oldSessionId) {
-                this.sessionStore.setPreviousSessionId(ctx.userId, 'dsh', oldSessionId);
-                this.sessionStore.clearSessionId(ctx.userId, 'dsh');
-                switchNotice = `DSH ${label} 已变更，旧会话已停放到恢复槽（可 /resume 校验后恢复），下次消息将新建会话`;
-            }
-            else {
-                switchNotice = `DSH ${label} 已变更，下次消息将新建会话`;
-            }
-        };
-        parkDshSessionBoundary(changedKeys.includes('agents.dsh.agentPreset'), 'preset');
-        parkDshSessionBoundary(changedKeys.includes('agents.dsh.host'), 'host');
-        // 2026-07-13: 同步 agent 配置到 agentChoices（用于切换 agent 时恢复配置）
+        switchNotice = parkDshSessionBoundaryNotice(this.sessionStore, ctx.userId, this.config.defaultAgent, changedKeys.includes('agents.dsh.agentPreset'), 'preset', switchNotice);
+        switchNotice = parkDshSessionBoundaryNotice(this.sessionStore, ctx.userId, this.config.defaultAgent, changedKeys.includes('agents.dsh.host'), 'host', switchNotice);
+        // 同步 agent 配置到 agentChoices（用于切换 agent 时恢复配置）
         const currentAgent = this.config.defaultAgent;
         if (touchesAgentsSubtree(changedKeys, currentAgent)) {
             this.config = syncAgentChoices(this.config, currentAgent);
@@ -2084,12 +2146,11 @@ export class CommandRouter {
         // duck method `updateApprovalMode` (codex thread/settings/update,
         // kimi/opencode session/set_mode) so they take effect for subsequent
         // turns without waiting for the runner to be recreated.
-        const hasApprovalConfigChange = ['codex', 'kimi', 'opencode'].some((kind) => touchesAgentConfig(changedKeys, kind)) ||
-            changedKeys.includes('agents.dsh.permissionPreset');
+        const hasApprovalConfigChange = computeHasApprovalConfigChange(changedKeys);
         if (hasApprovalConfigChange) {
             this.bridge.syncActiveApprovalModes();
         }
-        // 2026-07-13: 任何 agent 配置变更或 defaultAgent 切换，都清除 runner 缓存
+        // 任何 agent 配置变更或 defaultAgent 切换，都清除 runner 缓存
         if (hasDefaultAgentChange || hasAgentConfigChange) {
             this.bridge.clearRunners();
         }
@@ -2109,60 +2170,13 @@ export class CommandRouter {
                     '如果发得太快，也可能被飞书合并成一条消息',
             }, ctx);
         }
-        switch (cmd) {
-            case 'help':
-            case 'h':
-                return this.cmdHelp();
-            case 'status':
-            case 's':
-                return this.cmdStatus(ctx);
-            case 'ps':
-                return this.cmdPs(ctx);
-            case 'stop':
-            case 't':
-                return await this.cmdStop(ctx);
-            case 'exit':
-            case 'quit':
-            case 'e':
-                return await this.cmdExit();
-            case 'restart':
-                return this.cmdRestart();
-            case 'new':
-                return this.cmdNew(ctx);
-            case 'cd':
-                return this.cmdCd(args, ctx);
-            case 'ls':
-                return this.cmdLs(args, ctx);
-            case 'download':
-            case 'd':
-                return await this.cmdDownload(args, ctx);
-            case 'ws':
-                return this.cmdWs(args, ctx);
-            case 'resume':
-            case 'r':
-                return this.cmdResume(args, ctx);
-            case 'active':
-                return this.cmdActive(args, ctx);
-            case 'config':
-            case 'c':
-                return await this.cmdConfig(args, ctx);
-            case 'order':
-            case 'o':
-                return this.cmdOrder(args, ctx);
-            case 'update':
-            case 'u':
-                return await this.cmdUpdate(args, ctx);
-            case 'clone':
-                return await this.cmdClone(args, ctx);
-            default:
-                return { text: `未知命令 /${cmd}，输入 /help 查看可用命令` };
-        }
+        return dispatchCommand(this, cmd, args, ctx);
     }
     // --- 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 进程在跑' },
@@ -2203,11 +2217,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% 足以放下描述。
@@ -2460,8 +2474,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,
@@ -2546,38 +2560,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) {
@@ -2601,62 +2643,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
@@ -2701,7 +2706,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
      * @param offset  分页起点（条目数）
      * @param rootDir 浏览起点：卡片「返回」按钮回到这里。省略时默认 = 本次列出的
      *                目录（`/ls <dir>` 的起点即该目录），因此「返回」不会把用户
-     *                丢回 工作目录（用户明确反馈过）。
+     *                丢回 工作目录。
      * @param q       关键词筛选：只匹配**当前层**条目名（不递归），大小写不敏感。
      *                省略/空 = 无筛选。
      */
@@ -2791,7 +2796,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) {
@@ -2815,54 +2820,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) {
@@ -2887,6 +2869,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();
@@ -2913,21 +2923,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;
             }