lark-remote 0.5.19 → 0.5.20

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.20] - 2026-11-04
+
+### 修复
+
+- **超长回答的 Markdown 文件不再在发送失败时一起丢掉**：正文装不进一张卡时，完整回答会逐字写成临时 `.md` 随卡发出，卡上只留一句「完整内容见随附的 Markdown 文件」。此前发送失败也在收尾无条件删文件，于是卡上是被占位替代的半截正文、文件又已经没了，用户两头都拿不到。现在发送失败保留文件，并在错误日志里给出路径便于事后找回
+- **`/stop` 没真的停下来不再被记成已停止**：停止动作同时做「终结卡片」和「终止进程」两件事，此前只看其中一个的结果——前者被飞书拒绝时卡片永久停在运行态，后者失败时进程可能还在跑而工作目录已被释放，日志照样写「停止完成」。现在两个结果分别判定：卡片终结失败与进程终止失败各自记错误日志，进程未确认终止时按「未确认」上报，不承诺已停止（这类运行仍会继续消耗额度，日志里能直接看出是哪一半失败）
+- **DSH 会话列表读取失败不再显示成「没有会话」**：列表读取出错时此前静默返回空列表，`/resume` 于是画出「无会话」。远端根本没有「空」这个状态——守护进程没起、登录凭据失效、请求超时全都是故障，用户却只能把它读成「历史会话没了」。现在读取失败直接报错并说明是哪个 agent 与原因，与 kimi / opencode 的口径一致；目录确实不存在（真的还没会话）仍按空态返回，两者分得开
+- **切换 agent 后的切换语义说明重新随卡可见**：`/config` 保存并切换 agent 时会发一张恢复卡，而文档承诺的那句切换语义（当前会话已清空、下一条消息开新对话）此前只挂在一条生产走不到的兜底卡上，实际一个字都没显示过。现在它作为卡片标题的尾行随卡显示；卡片刷新失败也不再吞掉这条通知——保存确实成功了，只记日志，后续消息照常切换
+- **启动失败不再零输出退出**：安装损坏或依赖缺失时，此前表现为没有任何说明地直接退出码 1，用户无从知道是哪里坏了。现在把根因打到标准错误；用 Bun 拉起、回落到 Node 的那条路径同样留痕，「为什么跑在了 Node 上」可查
+
+### 维护
+
+- **超大模块按职责拆分**：消息处理主模块拆出压缩、后台任务监视、命令执行三块独立实现；三个 agent 的会话目录扫描器把重复的遍历与解析逻辑收进共享实现；超长的事件循环按段拆分，原有的顺序约束注释随迁。无行为变化
+- **重复定义收敛为单一来源**：agent 默认配置、token 计数格式化、卡片图标与按钮构造等多处副本各自合并成一份；agent 类型改由统一常量派生，新增 agent 时不再需要多处同步改。无行为变化
+- **删除走不到的代码**：生产不可达的回退分支、恒假的判空与淘汰守卫、纯转发的委托方法、被参数收窄取代的入口校验一并删除，配套测试桩从假接口迁到真实调用路径。无行为变化
+- **日志与错误口径对齐**：若干处失败被静默吞掉或级别低于兄弟模块的问题按统一口径修正（克隆兜底、Windows 进程终止、审批拒绝、媒体发送、更新缓存、凭据重签等）。无行为变化
+- **文档与注释去陈旧**：删掉指向已不存在文件的引用，修正过时的测试规模与卡片元素上限说法，把「排查日期 + 现场反馈 + 时长读数」式的事故叙述改成自描述注释——保留故障形态、机制、阈值与约束，去掉读者无法复核的时间性细节。无行为变化
+- **会话列表故障用例不再向操作系统要错误码**：pi 的列表失败契约此前靠「sessions 这个名字被文件占用」制造 `ENOTDIR`，而同一个形态在 Windows 上并不报这个码，用例只在单一系统成立。改为直接注入给定错误码：`EPERM` 钉住上抛的契约文案与原因链，并新增「目录不存在＝优雅空态」这条此前无人覆盖的出口；原真实文件系统形态保留，按系统门控并写明分歧原因。无行为变化
+
 ## [0.5.19] - 2026-11-03
 
 ### 修复

package/dist/bridge/approval-actions.d.ts

@@ -82,7 +82,7 @@ export declare class ApprovalActions {
         nonce: string;
     }): Promise<void>;
     /**
-     * Codex AskUserQuestion 补充说明（user_note，2026-08-18 live 验证模型理解
+     * Codex AskUserQuestion 补充说明（user_note，模型理解
      * "user_note: <text>" 条目）：记录到 coordinator，随答案一起提交。
      * 路由到 ApprovalCoordinator.answerNote。
      */

package/dist/bridge/approval-actions.js

@@ -93,7 +93,7 @@ export class ApprovalActions {
         return this.dispatchQuestionAction(opts, 'handleApprovalAnswerCustom', (coordinator) => coordinator.answerCustom({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
     }
     /**
-     * Codex AskUserQuestion 补充说明（user_note，2026-08-18 live 验证模型理解
+     * Codex AskUserQuestion 补充说明（user_note，模型理解
      * "user_note: <text>" 条目）：记录到 coordinator，随答案一起提交。
      * 路由到 ApprovalCoordinator.answerNote。
      */

package/dist/bridge/bash-run.d.ts

@@ -0,0 +1,71 @@
+import type { SessionStore } from '../session/index.js';
+import type { RunTerminal } from '../card/run-state.js';
+import type { BridgeChannel, CommandContext, CommandResult } from './index.js';
+/**
+ * `!` bash 命令执行（bridge 结构治理第 3 刀）：建卡、事件流消费、终态装配
+ * 与 runId 登记表。
+ *
+ * 红线（§9.6 / §9.18）：
+ * - bash **绝不 re-chain 到 QueueManager**——enqueue 队列 promise 未 settle 时
+ *   re-chain 会自等待死锁（外层 promise 等内层、内层排在外层后面）。
+ * - bash 用独立 runId 空间、独立登记表，不进 activeRuns，/stop 不会误杀。
+ * - 中断卡的 `cardSession.finish('interrupted')` 不传 exitCode（保持 null），
+ *   bash-renderer 的「已手动终止」文案依赖它。
+ *
+ * 依赖显式注入（与 ApprovalActions / CompactLifecycle / JobWatchLifecycle
+ * 同一模式）。
+ */
+export interface BashRunLifecycleDeps {
+    connector: BridgeChannel;
+    sessionStore: SessionStore;
+    resolveCwd(userId: string): string | undefined;
+    sendResult(result: CommandResult, ctx: CommandContext): Promise<boolean>;
+    finishTurnReactions(ctx: CommandContext, emoji: string): void;
+}
+export declare class BashRunLifecycle {
+    private readonly deps;
+    /** Active `!` bash runs, keyed by runId (NOT cwd)。见 {@link ActiveBashRun}。 */
+    private activeBashRuns;
+    constructor(deps: BashRunLifecycleDeps);
+    /**
+     * Execute a bash command and stream output to a card.
+     * `!` commands bypass the serial queue entirely (see body comment + §9.6):
+     * bash runs in parallel with same-workspace agent runs, tracked in
+     * `activeBashRuns` separately from `activeRuns`.
+     */
+    executeBash(command: string, ctx: CommandContext): Promise<void>;
+    /**
+     * Internal execution of bash command (called directly from executeBash,
+     * bypassing the serial queue — see executeBash).
+     */
+    private executeBashInternal;
+    /** Get all active bash runs with their state for /active command. */
+    getActiveBashRuns(): Array<{
+        runId: string;
+        cwd: string;
+        userId: string;
+        chatId: string;
+        terminal: RunTerminal;
+        command: string;
+    }>;
+    /**
+     * /stop 的 bash 侧（interruptCurrentRunDetailed 的后半段）。
+     *
+     * These bypass the serial queue and are tracked separately; stop the per-run
+     * BashRunner directly.
+     * `/stop`（无 runId、无 cwd）语义是「停掉这个会话的一切」，所以并行跑的
+     * `!` 命令也要停——旧实现命中 claude run 就 return，这些 bash 会被漏掉。
+     * 带范围的中断（停止卡 runId、queue.immediate 的 cwd）保持旧语义：只有
+     * 没有 claude run 命中时才回退到 bash，避免误杀用户并行跑的 `!` 任务。
+     *
+     * @param claudeTargetCount 本次中断已命中的 claude run 数（0 = 可回退到 bash）
+     * @returns 本次实际停掉的 bash run 数
+     */
+    stopMatchingBashRuns(input: {
+        userId: string;
+        chatId: string;
+        runId?: string;
+        cardMessageId?: string;
+        cwd?: string;
+    }, claudeTargetCount: number): Promise<number>;
+}

package/dist/bridge/bash-run.js

@@ -0,0 +1,217 @@
+import { randomUUID } from 'node:crypto';
+import { BashProcessRunner } from '../runner/index.js';
+import { BashCardSession, capBashOutput } from '../card/bash-card-session.js';
+import { renderBashCard } from '../card/bash-renderer.js';
+import { getLogger } from '../logger/index.js';
+import { errorMessage } from './final-usage.js';
+export class BashRunLifecycle {
+    deps;
+    /** Active `!` bash runs, keyed by runId (NOT cwd)。见 {@link ActiveBashRun}。 */
+    activeBashRuns = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Execute a bash command and stream output to a card.
+     * `!` commands bypass the serial queue entirely (see body comment + §9.6):
+     * bash runs in parallel with same-workspace agent runs, tracked in
+     * `activeBashRuns` separately from `activeRuns`.
+     */
+    async executeBash(command, ctx) {
+        const cwd = this.deps.resolveCwd(ctx.userId);
+        getLogger().info(`[lark-remote] executeBash start userId=${ctx.userId} sessionCwd=${this.deps.sessionStore.get(ctx.userId)?.cwd} command="${command.slice(0, 30)}..."`);
+        if (!cwd) {
+            getLogger().info(`[lark-remote] executeBash no cwd, sending error`);
+            await this.deps.sendResult({ text: '请先使用 /cd <path> 设置工作目录，或保存一个 workspace (/ws save <name>)' }, ctx);
+            return;
+        }
+        getLogger().info(`[lark-remote] executeBash proceeding cwd=${cwd}`);
+        // `!` commands bypass the serial queue entirely (design.md §9.6):
+        // index.ts dispatches `!` to router.handle → executeBash directly, NOT via
+        // bridge.enqueue. bash runs in parallel with same-workspace claude runs.
+        // bash runs are tracked in `activeBashRuns` (keyed by runId), separate from
+        // claude's `activeRuns` (keyed by cwd) — they must not collide or `/stop`
+        // would kill the wrong task. Do NOT re-chain onto the serial queue
+        // (QueueManager) here: that would block on the still-pending outer promise
+        // and deadlock self-wait.
+        await this.executeBashInternal(command, ctx, cwd);
+    }
+    /**
+     * Internal execution of bash command (called directly from executeBash,
+     * bypassing the serial queue — see executeBash).
+     */
+    async executeBashInternal(command, ctx, cwd) {
+        getLogger().debug(`[lark-remote] executeBashInternal userId=${ctx.userId} chatId=${ctx.chatId} cwd=${cwd} command="${command.slice(0, 50)}..."`);
+        // Note: We don't check activeRuns here because bash bypasses the serial
+        // queue and runs in parallel with same-workspace agent runs (§9.6). The
+        // activeRuns check in forwardToClaude is for a different purpose (detecting
+        // concurrent agent runs that would corrupt session state). Bash commands
+        // don't have that issue.
+        const runId = randomUUID();
+        const bashRunner = new BashProcessRunner();
+        // Single streaming card across the whole run (initial → output patches →
+        // terminal), instead of sending many independent cards. BashCardSession is
+        // the bash analogue of RunCardSession.
+        const cardSession = new BashCardSession({
+            connector: this.deps.connector,
+            chatId: ctx.chatId,
+            replyTo: ctx.messageId,
+            runId,
+            command,
+            renderOptions: {},
+        });
+        // Track this bash run independently from claude's `activeRuns`. Bash runs
+        // bypass the serial queue and may run in parallel with a claude run in the
+        // same cwd, so they must NOT share activeRuns (which is keyed by cwd
+        // and would let bash/claude overwrite each other). Keyed by runId so
+        // multiple `!` commands can run concurrently. Tracked so /stop can reach
+        // the bashRunner (which is otherwise a local) via interruptCurrentRun.
+        this.activeBashRuns.set(runId, {
+            bashRunner,
+            cardSession,
+            userId: ctx.userId,
+            chatId: ctx.chatId,
+            cwd,
+            command,
+        });
+        let output = '';
+        let stderr = '';
+        let exitCode = null;
+        try {
+            getLogger().info(`[lark-remote] executeBashInternal about to start stream chatId=${ctx.chatId} messageId=${ctx.messageId}`);
+            try {
+                await cardSession.start();
+                getLogger().info(`[lark-remote] executeBash stream started runId=${runId}`);
+            }
+            catch (err) {
+                getLogger().warn('[lark-remote] bash card stream unavailable:', err);
+            }
+            for await (const event of bashRunner.run(command, { cwd })) {
+                if (event.type === 'stdout') {
+                    // 层④：bridge 本地 output 也必须 store-time 截断——仅 session state
+                    // 有界并不会让 `output +=` 自然有界（「store 有界则本地拼接自然有界」
+                    // 不成立），!yes 洪峰下本地字符串仍全量驻留。capBashOutput 增量调用
+                    // O(CAP+chunk)，不会带回 O(n²) 截断成本（output 恒 ≤ CAP，拼接后
+                    // ≤ CAP+chunk 再 slice 尾部）。
+                    output = capBashOutput(output + event.content);
+                    await cardSession.update({ output, stderr });
+                }
+                else if (event.type === 'stderr') {
+                    stderr = capBashOutput(stderr + event.content);
+                    await cardSession.update({ output, stderr });
+                }
+                else if (event.type === 'exit') {
+                    exitCode = event.exitCode ?? 0;
+                }
+            }
+            await cardSession.finish(exitCode === 0 ? 'done' : 'error', { exitCode, output, stderr });
+        }
+        catch (err) {
+            getLogger().error(`[lark-remote] bash run error runId=${runId}:`, err);
+            // If for-await threw mid-stream the bash child may still be running.
+            // Stop it before finalizing the card — otherwise the finally block
+            // removes the activeBashRuns entry and /stop can no longer reach it,
+            // leaving an orphan process.
+            try {
+                await bashRunner.stop();
+            }
+            catch (stopErr) {
+                getLogger().warn(`[lark-remote] bash stop failed:`, stopErr);
+            }
+            await cardSession.finish('error', {
+                exitCode: 1,
+                output,
+                stderr: stderr + `\n执行错误: ${errorMessage(err)}`,
+            });
+        }
+        finally {
+            const settleResult = await cardSession.settle();
+            if (settleResult === 'unsent') {
+                // Stream never established a card — send a static terminal card as fallback.
+                // Use 2.0 schema to match the streaming card (avoid 2.0→1.x downgrade).
+                try {
+                    await this.deps.connector.sendWithRetry(ctx.chatId, { card: renderBashCard(cardSession.currentState, {}) }, { replyTo: ctx.messageId });
+                }
+                catch (fallbackErr) {
+                    getLogger().error(`[lark-remote] bash terminal fallback card failed runId=${runId} chatId=${ctx.chatId}:`, fallbackErr);
+                }
+            }
+            if (this.activeBashRuns.has(runId)) {
+                this.activeBashRuns.delete(runId);
+                getLogger().info(`[lark-remote] executeBash done runId=${runId} exitCode=${exitCode}`);
+            }
+            // Add a Done emoji reaction to the user's original message to signal completion
+            this.deps.finishTurnReactions(ctx, 'Done');
+        }
+    }
+    /** Get all active bash runs with their state for /active command. */
+    getActiveBashRuns() {
+        const result = [];
+        for (const [runId, bashRun] of this.activeBashRuns) {
+            const state = bashRun.cardSession.currentState;
+            // Only include non-terminal runs (bash has no finalizing state)
+            if (state.terminal === 'running') {
+                result.push({
+                    runId,
+                    cwd: bashRun.cwd,
+                    userId: bashRun.userId,
+                    chatId: bashRun.chatId,
+                    terminal: state.terminal,
+                    command: bashRun.command,
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * /stop 的 bash 侧（interruptCurrentRunDetailed 的后半段）。
+     *
+     * These bypass the serial queue and are tracked separately; stop the per-run
+     * BashRunner directly.
+     * `/stop`（无 runId、无 cwd）语义是「停掉这个会话的一切」，所以并行跑的
+     * `!` 命令也要停——旧实现命中 claude run 就 return，这些 bash 会被漏掉。
+     * 带范围的中断（停止卡 runId、queue.immediate 的 cwd）保持旧语义：只有
+     * 没有 claude run 命中时才回退到 bash，避免误杀用户并行跑的 `!` 任务。
+     *
+     * @param claudeTargetCount 本次中断已命中的 claude run 数（0 = 可回退到 bash）
+     * @returns 本次实际停掉的 bash run 数
+     */
+    async stopMatchingBashRuns(input, claudeTargetCount) {
+        const cardScoped = input.runId !== undefined || input.cardMessageId !== undefined;
+        const includeBashRuns = (input.runId === undefined && input.cardMessageId === undefined && input.cwd === undefined) ||
+            claudeTargetCount === 0;
+        const bashTargets = includeBashRuns
+            ? [...this.activeBashRuns.entries()].filter(([runId, b]) => {
+                if (input.cwd !== undefined && b.cwd !== input.cwd)
+                    return false;
+                if (b.userId !== input.userId || b.chatId !== input.chatId)
+                    return false;
+                if (input.runId) {
+                    if (runId === input.runId)
+                        return true;
+                    // Scoped card clicks may fall back only through their own card id.
+                    if (cardScoped)
+                        return false;
+                }
+                if (input.cardMessageId) {
+                    return b.cardSession.cardMessageId === input.cardMessageId;
+                }
+                return true;
+            })
+            : [];
+        let stoppedCount = 0;
+        for (const [runId, b] of bashTargets) {
+            getLogger().info(`[lark-remote] interrupt hit bash runId=${runId} cwd=${b.cwd} userId=${input.userId}`);
+            await b.bashRunner.stop({ immediate: true });
+            // Update card to show interrupted state. exitCode 不传（保持 null）：
+            // bash-renderer 的「已手动终止」文案要求 exitCode === null；传 -1 会让
+            // 该分支不可达，中断卡退化成「退出码: -1」的失败样式。
+            await b.cardSession.finish('interrupted');
+            this.activeBashRuns.delete(runId);
+            getLogger().info(`[lark-remote] interrupt bash stop done runId=${runId}`);
+            stoppedCount++;
+        }
+        return stoppedCount;
+    }
+}
+//# sourceMappingURL=bash-run.js.map

package/dist/bridge/compact.d.ts

@@ -0,0 +1,155 @@
+import type { Runner } from '../runner/index.js';
+import type { AppConfig } from '../config/index.js';
+import type { SessionReaderRegistry, SessionStore } from '../session/index.js';
+import { RunCardSession } from '../card/run-card-session.js';
+import { type RunTerminal } from '../card/run-state.js';
+import type { AgentKind } from '../agent-kinds.js';
+import type { BridgeChannel, CommandContext, CommandResult } from './index.js';
+import type { ActiveRun, IdleWatchdog } from './index.js';
+/**
+ * Compact 能力的双重门控：声明的能力表 && runner 实际实现。
+ *
+ * 只做鸭子探测会把「漏实现」降级成静默隐藏按钮（dsh 就这样漏了），所以声明表
+ * 是必需项；只信声明表则可能渲染出点不动的死按钮，所以实现检查也保留。两者
+ * 不一致时打 error 日志，让缺陷在运行日志里可见。
+ */
+export declare function runnerSupportsCompact(runner: Runner, kind: AgentKind): boolean;
+/**
+ * 终态 reaction 的单源映射：普通 run 收尾（bridge/index.ts finalizeRun）与
+ * 压缩收尾（本文件 streamCompact）共用同一份，保证同一终态打同一表情。
+ */
+export declare function terminalReactionEmoji(terminal: RunTerminal): string;
+/**
+ * Compact 生命周期（bridge 结构治理第 1 刀）：可压缩 run 记账、终态卡 /
+ * resume 卡两条 Compact 入口、kimi 在途检测与压缩流式卡。
+ *
+ * 依赖全部显式注入（与 ApprovalActions / InboundMediaHandler 同一模式）：
+ * - `activeRuns` 是与普通 run **共用的同一张 cwd 槽位表**——压缩注册前先确认
+ *   槽位空闲，否则会覆盖在跑 run 的记录、`/stop` 停错对象；压缩自己不设
+ *   per-call 超时（DSH 的 runCompact RPC 关闭 unary 预算），卡住时由
+ *   `/stop` + §9.12 空闲看门狗兜底。
+ * - 记账上限 per-cwd `MAX_COMPACTABLE_RUNS_PER_CWD`，超出按插入序淘汰最旧。
+ */
+export interface CompactLifecycleDeps {
+    /** 与普通 run 共用的 cwd 槽位表（Bridge.activeRuns，按引用共享）。 */
+    activeRuns: Map<string, ActiveRun>;
+    connector: BridgeChannel;
+    sessionStore: SessionStore;
+    sessionReaderRegistry: SessionReaderRegistry;
+    /** live 取值：`/config` 会整体替换 config 引用，不能按值快照。 */
+    getConfig(): AppConfig;
+    getRunner(cwd: string, kind?: AgentKind, opts?: {
+        replaceStale?: boolean;
+    }): Runner;
+    sendResult(result: CommandResult, ctx: CommandContext, opts?: {
+        onCardSent?: (messageId: string) => void;
+    }): Promise<boolean>;
+    startIdleWatchdog(opts: {
+        runId: string;
+        session: RunCardSession;
+        runner: Runner;
+        /** >0 = 正在等人工审批：「等审批」不是「挂死」，刷新窗口而不是终止。 */
+        pendingApprovals?: () => number;
+    }): IdleWatchdog;
+    finishTurnReactions(ctx: CommandContext, emoji: string): void;
+    resolveCwd(userId: string): string | undefined;
+}
+export declare class CompactLifecycle {
+    private readonly deps;
+    /**
+     * 最近若干次已完成的、runner 有 runCompact 的 run（cwd → runId → 记录）。
+     * run 结束后 activeRuns 已清空，而终态卡上的 Compact 按钮只带 runId，
+     * 需要它反查 sessionId + agentKind。
+     *
+     * 为什么按 runId 存而不是「每 cwd 只留最新一条」：compact 卡片动作走串行
+     * 队列（会被正在跑的 run 挡住），点击到执行之间可能夹着别的 run 收尾。
+     * 单槽会被覆盖 —— 旧卡片的压缩必然报「该任务已结束或不属于当前会话」，
+     * 与 session 是否还在、能否压缩无关（2026-10-08 线上缺陷）。
+     */
+    private compactableRuns;
+    constructor(deps: CompactLifecycleDeps);
+    /**
+     * 记下一次「可压缩 run」：终态卡上的 Compact 按钮点击时据此反查
+     * sessionId + agentKind。runId 是按钮自带的唯一键，同 cwd 内唯一。
+     * 超出上限按插入序淘汰最旧的一条（Map 保持插入序；重复写同一 runId
+     * 先 delete 再 set 以刷新位置）。
+     */
+    private recordCompactableRun;
+    /**
+     * 终态 Compact 记账：把本次 run 实际使用的 sessionId 记进
+     * {@link compactableRuns}，供终态卡上的 Compact 按钮按 runId 反查。
+     *
+     * 调用点固定在 `finalizeRun` 的 `finally` 里、**槽位所有权守卫之外**。
+     * 所有权守卫只回答「cwd 槽位还归不归本 run」（决定能否删槽位 / evict
+     * runner）；记账回答「本次 run 结束了吗、用的哪个 sessionId」。两者在不同
+     * 维度上：外部中断（`/stop`、停止卡按钮、`queue.immediate`）会先摘槽位，
+     * 记账若跟着守卫走就永远不会落，中断卡片的按钮必然反查不到（中断
+     * 后点 Compact 一律回「该任务已结束或不属于当前会话」）。
+     *
+     * 覆盖所有终态入口（正常结束、error、interrupted、idle_timeout、
+     * goal_continuing）——这些卡片都渲染 Compact 按钮（`goal` 仍 active 时
+     * 除外）。函数体全部是内存操作（查表、属性读、Map 写），无 IO 无解析，
+     * 不需要兜错；真正的清理容错由调用方 finally 保证。
+     */
+    recordCompactableRunForTerminal(cardSession: RunCardSession, activeRun: ActiveRun, ctx: CommandContext): void;
+    /**
+     * 按 runId 反查可压缩 run 记录（跨 cwd 扫描）。
+     *
+     * 为什么不带 cwd 过滤：按钮属于「那一次 run」，与用户此刻在哪个工作目录、
+     * 排队期间有没有 /cd 无关。`/stop` 的 interruptCurrentRun 同样是全局按 runId
+     * 找（从不查当前 cwd），compact 与它保持一致。用当前 cwd 收窄会让「切了工作区
+     * 再点旧卡片」和「排队期间 /cd」两种情况误报「该任务已结束或不属于当前会话」。
+     */
+    private findCompactableRun;
+    /**
+     * Handle compact card action — trigger a compaction request for any
+     * runCompact-capable runner（codex/kimi/opencode/pi/claude）。按钮带的是
+     * 那次 run 的 runId，据此反查该 run 实际使用的 sessionId + agentKind
+     * + cwd（compactableRuns，按 runId 记录），再调 runner 的 runCompact()。
+     */
+    handleCompactAction(value: {
+        runId?: string;
+    }, ctx: CommandContext): Promise<void>;
+    /**
+     * §5.3: kimi 压缩在途检测——reader 实现契约的 `readCompactionState` 时，若
+     * wire 状态机判定当前有未终结的压缩（最后一次 begin 无 terminal 记录），
+     * 直接回文本「已有一次 Compact 正在进行」并返回 true（调用方不开卡、不发
+     * session/prompt）。codex/claude 等 reader 无此方法 → 返回 false，行为不变。
+     */
+    private rejectIfCompactionInFlight;
+    /**
+     * Stream a compaction to a card: start a RunCardSession with
+     * operationKind='compaction' (no recursive Compact button), consume
+     * runner.runCompact() events, read authoritative jsonl usage, and finish
+     * the card. Shared by handleCompactAction (run card button) and
+     * handleResumeCompact (resume cards) so both flows stay in sync.
+     *
+     * Precondition: callers have already validated that `runner` implements
+     * runCompact and that the session exists in `cwd`.
+     */
+    private streamCompact;
+    /**
+     * 事件消费循环（streamCompact 前半段）：吞 runner.runCompact() 的全部事件，
+     * 逐帧喂卡片。终态后不再消费（与 runAgentStreamToEnd 同口径）；result 帧
+     * 只做记录（subype/errorMessage），终态装配在 {@link finishCompactCard}。
+     */
+    private consumeCompactEvents;
+    /**
+     * 终态装配（streamCompact 后半段）：result subtype 三态映射 → 从会话 jsonl
+     * 读权威统计（compactCount 短重试）→ cardSession.finish。
+     */
+    private finishCompactCard;
+    /**
+     * Handle resume.compact card action — compact a session directly from a
+     * resume card (auto-resume / `/resume <id>`), without a runId.
+     *
+     * Unlike handleCompactAction (which validates against the last finished run's
+     * runId), the resume card carries the sessionId + agent it was rendered for.
+     * Validation: the session must exist in the current cwd (same rule as
+     * cmdResume / resume.use) and the runner must implement runCompact.
+     */
+    handleResumeCompact(value: {
+        sessionId?: string;
+        agent?: string;
+    }, ctx: CommandContext): Promise<void>;
+}