lark-remote 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.2] - 2026-10-11
+
+### 修复
+
+- **codex 运行结束卡片的 token 统计不再翻倍**：codex app-server 实时上报的输入 token 按协议口径已包含命中缓存的部分，而卡片契约要求它表示「未命中缓存的输入」。入口没做减法时，Input 会等于整个上下文用量、缓存占比的分母被重复计数、Total 再被「总量与分项之和取大」抬高一倍（实测同一轮 36 万显示成 72 万）。现在实时通知与 jsonl 兜底读取两条入口统一减掉缓存部分
+- **压缩卡片的「压缩前」不再显示摘要调用自身的用量**：codex 把生成摘要那次调用自己的 token 记录写在压缩事件之前，此前「压缩前」取的是紧贴压缩事件的那一条，于是把摘要调用的消耗当成压缩前的上下文窗口（实测 36 万的窗口显示成 20 万）。现在按压缩事件自带的摘要调用用量回退一条，取压缩前最后一次真实窗口；更早的、不带该字段的数据保持原读法
+- **排队卡片不再复述「你正在排队」**：占用执行位的是普通消息时，卡片仍写着「正在执行: 💬 消息」并附一句「消息将按顺序执行…」，这两行对用户没有新信息。现在只有可能挡住队列、需要用户归因的任务（Compact、命令）才自报身份；Compact 占用时仍额外说明压缩结束后会按顺序执行你的消息
+
+### 变更
+
+- **消除一处全量测试并发下的时序假红**：bash 退出清理用例在收到首个事件后立刻读取 shell 自己写入的 pid 文件，而重定向落盘可能晚于该事件，整套测试并发跑时会随机报文件不存在。改为与同一用例里另一处 pid 文件相同的有界等待。无行为变化
+
+## [0.5.1] - 2026-10-09
+
+### 修复
+
+- **旧卡片上的 Compact 按钮点下去不再报「该任务已结束或不属于当前会话」**：Compact 按钮只带本轮 run 的标识，此前按「每个工作目录最新一条 run」反查会话，而 compact 动作走串行队列——排队期间后续 run 收尾会覆盖那一个槽位，旧卡片于是必然失效。现在每条 run 收尾时按自己的标识记下会话与 agent，按钮自证身份，排队多久都不失效；Compact 也改为按该 run 自己的目录反查，中途切过目录不会压错会话
+- **同一会话的多条排队卡片不再互相顶掉**：队列条目此前复用飞书卡片的消息 id 当身份，同一会话里多条卡片撞同一个 key，先入队的那条被后面的覆盖、状态更新串到别的卡片上。改为每次入队铸造独立身份
+- **排队卡片会说清「在等谁」**：Compact 与普通消息共用同一条串行队列，Compact 占着执行位时新消息卡片仍写「位置: 第 1 位 / 前面还有: 0 条」，看着像马上就能轮到自己。现在没有等待中的消息时头部改为「等待当前任务结束」、正文写明正在执行的是 Compact 并收起位置行；占用者是 Compact 时「⚡ 立即执行」在渲染层置灰、执行层再加一道守卫，「❌ 撤销」保持可用
+- **codex 多 agent 会话不再把会话指针写坏**：codex app-server 会把子 agent 的开轮通知一起推过来，此前不判断归属，子线程的事件覆盖了本轮的线程标识，顶层会话指针被写成子线程标识——该值在会话索引里不是键，之后恢复会话报 `cannot resume an unloaded multi-agent v2 sub-agent`，`/restart` 也救不回来。现在通知按线程归属过滤；审批结算仍按请求标识走，子 agent 的审批照常可以回答
+- **带 `dsh` 的卡片不再静默退回默认 agent**：agent 名单此前被手抄成多份并发生漂移，收敛为单一来源、校验由该名单派生，消除「用错 reader → 未找到 session」的静默降级
+
+### 变更
+
+- **消除两处宿主环境相关的测试假红**：宿主带上本机没有的 locale（macOS 常见的 `LC_ALL=C.UTF-8`）时，bash 每次启动都往 stderr 打 setlocale 警告，让输出断言随机变红，测试 setup 阶段现在剔掉该变量（保留 UTF-8 解析所需项）；JSON-RPC 退出计时用例的计时起点从进程启动改到收到 `initialize` 应答，慢速 Windows runner 上不再因启动耗时超过阈值而误红
+- **英文架构文档补齐**：`docs/en/architecture/design.md` 增补与中文侧对应的五个章节，英中两侧不再不对称
+- **注释与用例名清理**：延续上一版的清理，去掉剩余指向未发布文档的引用与评审编号，并修正清理过程中留下的残句。无行为变化
+
 ## [0.5.0] - 2026-10-07
 
 ### 新增

package/dist/bridge/index.d.ts

@@ -4,8 +4,8 @@ import type { SessionReaderRegistry, SessionStore } from '../session/index.js';
 import type { AppConfig } from '../config/index.js';
 import { type RunCardChannel } from '../card/run-card-session.js';
 import type { RunTerminal } from '../card/run-state.js';
-import type { AgentKind } from '../runner/types.js';
-import { QueueManager, type QueuedTask, type EnqueueOptions, type AgentBinding } from './queue-manager.js';
+import { type AgentKind } from '../runner/types.js';
+import { QueueManager, type QueuedTask, type EnqueueOptions, type AgentBinding, type ExecutingInfo } from './queue-manager.js';
 import type { InboundMediaPayload } from '../connector/index.js';
 import type { MediaOutcome } from '../inbound/turn.js';
 /**
@@ -141,10 +141,16 @@ export declare class Bridge {
     /** Approval coordinators keyed by runId. */
     private approvalCoordinators;
     /**
-     * 最近一次已完成的、runner 有 runCompact 的 run（按 cwd）。run 结束后
-     * activeRuns 已清空，Compact 需要它来校验 runId 并提供 sessionId。
+     * 最近若干次已完成的、runner 有 runCompact 的 run（cwd → runId → 记录）。
+     * run 结束后 activeRuns 已清空，而终态卡上的 Compact 按钮只带 runId，
+     * 需要它反查 sessionId + agentKind。
+     *
+     * 为什么按 runId 存而不是「每 cwd 只留最新一条」：compact 卡片动作走串行
+     * 队列（会被正在跑的 run 挡住），点击到执行之间可能夹着别的 run 收尾。
+     * 单槽会被覆盖 —— 旧卡片的压缩必然报「该任务已结束或不属于当前会话」，
+     * 与 session 是否还在、能否压缩无关（2026-10-08 线上缺陷）。
      */
-    private lastCompactableRun;
+    private compactableRuns;
     /**
      * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
      * queue and may run in parallel with claude runs / other bash runs in the same
@@ -233,6 +239,11 @@ export declare class Bridge {
         tasksAhead: number;
         isRunning: boolean;
     };
+    /**
+     * lane 当前占用者的展示信息（排队卡与「立即执行」守卫共用）。
+     * 典型用途：占用者是 Compact 时拒绝 queue.immediate，避免中断压缩。
+     */
+    getQueueExecutingInfo(cwd: string): ExecutingInfo | undefined;
     /** Remove a task from the queue by messageId. Returns true if found and removed. */
     removeFromQueue(cwd: string, messageId: string): boolean;
     /**
@@ -323,6 +334,17 @@ export declare class Bridge {
      * Returns true if the in-place update succeeded, false if it fell back.
      */
     updateCardInPlace(card: object, ctx: CommandContext): Promise<boolean>;
+    /**
+     * Best-effort in-place refresh of a KNOWN card (no fallback send).
+     *
+     * `updateCardInPlace` falls back to sending a new card when the PATCH fails,
+     * which is right for the card the user just clicked (a silent failure would
+     * leave the click with no feedback) but wrong when refreshing *sibling*
+     * cards: an expired/withdrawn card would spawn a duplicate card on every
+     * edit. Callers that fan out to several cards use this instead and drop the
+     * card id from their set on `false`.
+     */
+    patchCard(messageId: string, card: object): Promise<boolean>;
     /** Send a file to the user via Feishu. */
     sendFile(filePath: string, ctx: CommandContext): Promise<void>;
     /**
@@ -465,11 +487,27 @@ export declare class Bridge {
         text: string;
         nonce: string;
     }): Promise<void>;
+    /**
+     * 记下一次「可压缩 run」：终态卡上的 Compact 按钮点击时据此反查
+     * sessionId + agentKind。runId 是按钮自带的唯一键，同 cwd 内唯一。
+     * 超出上限按插入序淘汰最旧的一条（Map 保持插入序；重复写同一 runId
+     * 先 delete 再 set 以刷新位置）。
+     */
+    private recordCompactableRun;
+    /**
+     * 按 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，按
-     * lastCompactableRun 记录的 agentKind 路由）。Validates the run exists
-     * and is in a terminal state, then calls the runner's runCompact().
+     * runCompact-capable runner（codex/kimi/opencode/pi/claude）。按钮带的是
+     * 那次 run 的 runId，据此反查该 run 实际使用的 sessionId + agentKind
+     * + cwd（compactableRuns，按 runId 记录），再调 runner 的 runCompact()。
      */
     handleCompactAction(value: {
         runId?: string;

package/dist/bridge/index.js

@@ -11,6 +11,7 @@ import { agentDisplayName, resumeUseButton } from '../card/card-shared.js';
 import { enforceCardBudget } from '../card/card-budget.js';
 import { normalizeResultUsage } from '../runner/common/result-usage.js';
 import { BashProcessRunner } from '../runner/index.js';
+import { AGENT_KINDS } from '../runner/types.js';
 import { QueueManager, } from './queue-manager.js';
 import { ApprovalCoordinator, decisionToApprovalAction } from './approval-coordinator.js';
 import { InboundMediaHandler } from './inbound-media.js';
@@ -56,6 +57,12 @@ function terminalReactionEmoji(terminal) {
 function runnerHasRunCompact(runner) {
     return ('runCompact' in runner && typeof runner.runCompact === 'function');
 }
+/**
+ * 每个 cwd 保留的「可压缩 run」条数上限。Compact 按钮挂在终态 run 卡片上，
+ * 卡片会被后续消息不断顶上去；无上限会让长跑进程随 run 数无界增长，而用户
+ * 实际能点到的只有最近几张卡，20 条足以覆盖。
+ */
+const MAX_COMPACTABLE_RUNS_PER_CWD = 20;
 /**
  * Bridge owns the per-workspace serial processing queue (§9.6) and the
  * single-card streaming forwarding loop (§9.12 watchdog + session sync).
@@ -112,10 +119,16 @@ export class Bridge {
     /** Approval coordinators keyed by runId. */
     approvalCoordinators = new Map();
     /**
-     * 最近一次已完成的、runner 有 runCompact 的 run（按 cwd）。run 结束后
-     * activeRuns 已清空，Compact 需要它来校验 runId 并提供 sessionId。
+     * 最近若干次已完成的、runner 有 runCompact 的 run（cwd → runId → 记录）。
+     * run 结束后 activeRuns 已清空，而终态卡上的 Compact 按钮只带 runId，
+     * 需要它反查 sessionId + agentKind。
+     *
+     * 为什么按 runId 存而不是「每 cwd 只留最新一条」：compact 卡片动作走串行
+     * 队列（会被正在跑的 run 挡住），点击到执行之间可能夹着别的 run 收尾。
+     * 单槽会被覆盖 —— 旧卡片的压缩必然报「该任务已结束或不属于当前会话」，
+     * 与 session 是否还在、能否压缩无关（2026-10-08 线上缺陷）。
      */
-    lastCompactableRun = new Map();
+    compactableRuns = new Map();
     /**
      * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
      * queue and may run in parallel with claude runs / other bash runs in the same
@@ -383,6 +396,13 @@ export class Bridge {
     getQueueInfo(cwd) {
         return this.queueManager.getQueueInfo(cwd);
     }
+    /**
+     * lane 当前占用者的展示信息（排队卡与「立即执行」守卫共用）。
+     * 典型用途：占用者是 Compact 时拒绝 queue.immediate，避免中断压缩。
+     */
+    getQueueExecutingInfo(cwd) {
+        return this.queueManager.getExecutingInfo(cwd);
+    }
     /** Remove a task from the queue by messageId. Returns true if found and removed. */
     removeFromQueue(cwd, messageId) {
         return this.queueManager.removeFromQueue(cwd, messageId);
@@ -663,6 +683,26 @@ export class Bridge {
             return false;
         }
     }
+    /**
+     * Best-effort in-place refresh of a KNOWN card (no fallback send).
+     *
+     * `updateCardInPlace` falls back to sending a new card when the PATCH fails,
+     * which is right for the card the user just clicked (a silent failure would
+     * leave the click with no feedback) but wrong when refreshing *sibling*
+     * cards: an expired/withdrawn card would spawn a duplicate card on every
+     * edit. Callers that fan out to several cards use this instead and drop the
+     * card id from their set on `false`.
+     */
+    async patchCard(messageId, card) {
+        try {
+            await this.connector.updateCard(messageId, card);
+            return true;
+        }
+        catch (err) {
+            getLogger().debug(`[lark-remote] patchCard failed messageId=${messageId}: ${errorMessage(err)}`);
+            return false;
+        }
+    }
     /** Send a file to the user via Feishu. */
     async sendFile(filePath, ctx) {
         try {
@@ -1335,11 +1375,7 @@ export class Bridge {
                     const compactSessionId = cardSession.currentState.sessionId ??
                         this.sessionStore.getSessionId(ctx.userId, activeRun.agentKind);
                     if (compactSessionId) {
-                        this.lastCompactableRun.set(cwd, {
-                            runId: activeRun.runId,
-                            sessionId: compactSessionId,
-                            agentKind: activeRun.agentKind,
-                        });
+                        this.recordCompactableRun(cwd, activeRun.runId, compactSessionId, activeRun.agentKind);
                     }
                 }
                 getLogger().info(`[lark-remote] activeRuns.delete cwd=${cwd} runId=${runId}`);
@@ -1481,11 +1517,48 @@ export class Bridge {
         log.info(`[lark-remote] handleApprovalAnswerNote runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
         return this.withCoordinator(opts.runId, (coordinator) => coordinator.answerNote({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
     }
+    /**
+     * 记下一次「可压缩 run」：终态卡上的 Compact 按钮点击时据此反查
+     * sessionId + agentKind。runId 是按钮自带的唯一键，同 cwd 内唯一。
+     * 超出上限按插入序淘汰最旧的一条（Map 保持插入序；重复写同一 runId
+     * 先 delete 再 set 以刷新位置）。
+     */
+    recordCompactableRun(cwd, runId, sessionId, agentKind) {
+        let byRunId = this.compactableRuns.get(cwd);
+        if (!byRunId) {
+            byRunId = new Map();
+            this.compactableRuns.set(cwd, byRunId);
+        }
+        byRunId.delete(runId);
+        byRunId.set(runId, { sessionId, agentKind, cwd });
+        while (byRunId.size > MAX_COMPACTABLE_RUNS_PER_CWD) {
+            const oldest = byRunId.keys().next().value;
+            if (oldest === undefined)
+                break;
+            byRunId.delete(oldest);
+        }
+    }
+    /**
+     * 按 runId 反查可压缩 run 记录（跨 cwd 扫描）。
+     *
+     * 为什么不带 cwd 过滤：按钮属于「那一次 run」，与用户此刻在哪个工作目录、
+     * 排队期间有没有 /cd 无关。`/stop` 的 interruptCurrentRun 同样是全局按 runId
+     * 找（从不查当前 cwd），compact 与它保持一致。用当前 cwd 收窄会让「切了工作区
+     * 再点旧卡片」和「排队期间 /cd」两种情况误报「该任务已结束或不属于当前会话」。
+     */
+    findCompactableRun(runId) {
+        for (const byRunId of this.compactableRuns.values()) {
+            const record = byRunId.get(runId);
+            if (record)
+                return record;
+        }
+        return undefined;
+    }
     /**
      * Handle compact card action — trigger a compaction request for any
-     * runCompact-capable runner（codex/kimi/opencode/pi/claude，按
-     * lastCompactableRun 记录的 agentKind 路由）。Validates the run exists
-     * and is in a terminal state, then calls the runner's runCompact().
+     * runCompact-capable runner（codex/kimi/opencode/pi/claude）。按钮带的是
+     * 那次 run 的 runId，据此反查该 run 实际使用的 sessionId + agentKind
+     * + cwd（compactableRuns，按 runId 记录），再调 runner 的 runCompact()。
      */
     async handleCompactAction(value, ctx) {
         const log = getLogger();
@@ -1495,36 +1568,32 @@ export class Bridge {
             await this.sendResult({ text: '⚠️ 无效的 Compact 请求，缺少 runId' }, ctx);
             return;
         }
-        const cwd = this.resolveCwd(ctx.userId);
-        if (!cwd) {
-            await this.sendResult({ text: '⚠️ 未设置工作目录' }, ctx);
-            return;
-        }
-        // 校验：run 结束后 activeRuns 已清空，用 lastCompactableRun 对照 runId。
-        const last = this.lastCompactableRun.get(cwd);
-        if (!last || last.runId !== runId) {
+        // 校验：run 结束后 activeRuns 已清空，只能靠按钮自带的 runId 反查记录。
+        // 按 runId 存（不按「最新的那一条」），点击到执行之间夹了新 run 收尾也不失效；
+        // 查找也不按「当前 cwd」收窄（见 findCompactableRun）。
+        const target = this.findCompactableRun(runId);
+        if (!target) {
             await this.sendResult({ text: '⚠️ 该任务已结束或不属于当前会话' }, ctx);
             return;
         }
-        if (!last.sessionId) {
-            await this.sendResult({ text: '⚠️ 未找到可压缩的会话' }, ctx);
-            return;
-        }
+        // 压缩必须用那次 run 自己的 cwd（session 文件 + runner 实例都按 cwd 解析）。
+        const cwd = target.cwd;
         // §5.3: kimi 压缩在途检测（wire 状态机）。第二次点击在本地毫秒级如实回答，
         // 不开卡、不发 session/prompt——否则 kimi 服务端拒绝并产生「秒回」假完成。
-        if (await this.rejectIfCompactionInFlight(last.sessionId, cwd, last.agentKind, ctx))
+        if (await this.rejectIfCompactionInFlight(target.sessionId, cwd, target.agentKind, ctx)) {
             return;
+        }
         // Check that the runner has runCompact method
-        const runner = this.getRunner(cwd, last.agentKind);
+        const runner = this.getRunner(cwd, target.agentKind);
         if (!runnerHasRunCompact(runner)) {
             await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
             return;
         }
         log.info(`[lark-remote] handleCompactAction executing runCompact for runId=${runId} cwd=${cwd}`);
         await this.streamCompact({
-            sessionId: last.sessionId,
+            sessionId: target.sessionId,
             cwd,
-            agentKind: last.agentKind,
+            agentKind: target.agentKind,
             runner,
             ctx,
         });
@@ -1731,9 +1800,10 @@ export class Bridge {
             return;
         }
         // Resolve agent kind the same way resume.use does: card value wins,
-        // otherwise fall back to defaultAgent.
-        const validAgents = ['claude', 'codex', 'opencode', 'pi', 'kimi'];
-        const agentKind = value.agent && validAgents.includes(value.agent)
+        // otherwise fall back to defaultAgent. 名单来自单源 AGENT_KINDS —— 手抄一份
+        // 必然再次漂移（这份曾经漏 dsh：带 dsh 的卡片会静默退回 defaultAgent，
+        // 用错 reader 报「未找到 session」）。
+        const agentKind = value.agent && AGENT_KINDS.includes(value.agent)
             ? value.agent
             : this.config.defaultAgent;
         // Session must exist in the current cwd (same rule as cmdResume /
@@ -1846,9 +1916,10 @@ export class Bridge {
             for await (const event of bashRunner.run(command, { cwd })) {
                 if (event.type === 'stdout') {
                     // 层④：bridge 本地 output 也必须 store-time 截断——仅 session state
-                    // 有界并不会让 `output +=` 自然有界（review 第④条表述不成立），!yes 洪峰
-                    // 下本地字符串仍全量驻留。capBashOutput 增量调用 O(CAP+chunk)，不会带回
-                    // O(n²) 截断成本（output 恒 ≤ CAP，拼接后 ≤ CAP+chunk 再 slice 尾部）。
+                    // 有界并不会让 `output +=` 自然有界（「store 有界则本地拼接自然有界」
+                    // 不成立），!yes 洪峰下本地字符串仍全量驻留。capBashOutput 增量调用
+                    // O(CAP+chunk)，不会带回 O(n²) 截断成本（output 恒 ≤ CAP，拼接后
+                    // ≤ CAP+chunk 再 slice 尾部）。
                     output = capBashOutput(output + event.content);
                     await cardSession.update({ output, stderr });
                 }

package/dist/bridge/queue-manager.d.ts

@@ -54,6 +54,29 @@ export interface QueuedTask {
     /** 入队时刻捕获的 agent+session 绑定，随任务闭包带到执行时刻。 */
     binding?: AgentBinding;
 }
+/**
+ * lane 条目的展示类型。只影响排队卡如何描述「正在执行的是什么」：
+ * `message` 普通消息（缺省）、`compact` 压缩会话、`command` 其他卡片动作。
+ */
+export type LaneTaskKind = 'message' | 'compact' | 'command';
+/**
+ * lane 当前占用者的展示信息。由 begin 路径登记、settle 路径清除，与执行
+ * 槽位同寿命；排队卡靠它回答「我在等谁」。
+ */
+export interface ExecutingInfo {
+    /**
+     * 归属标记：与执行槽位共用同一个 slot id。清除时校验它，防止一条迟到的
+     * settle 清掉后继任务的占用者（身份不用外部 id，同 §9.24 口径）。
+     */
+    slotId: number;
+    kind: LaneTaskKind;
+    /** 展示标签，例如 '💬 消息' / '🗜 Compact' / '📋 config.save'。 */
+    label: string;
+    /** 该条目自己的排队预览（可选）。 */
+    preview?: string;
+    /** 登记时刻（epoch ms）。当前只供诊断，卡片不渲染实时时长。 */
+    startedAt: number;
+}
 /** Options for enqueue operation */
 export interface EnqueueOptions {
     taskMeta?: {
@@ -72,6 +95,12 @@ export interface EnqueueOptions {
         editable?: boolean;
         /** 入队时刻捕获的 agent+session 绑定。 */
         binding?: AgentBinding;
+        /**
+         * lane 占用者的展示类型，缺省 'message'。
+         * 'compact' 时排队卡写明「正在执行: 🗜 Compact」，并把「立即执行」置灰
+         * ——该按钮会中断压缩（见 buildQueueActionButtons）。
+         */
+        kind?: LaneTaskKind;
     };
 }
 /** Queue info for a cwd */
@@ -115,18 +144,23 @@ export declare class QueueManager {
     /**
      * Monotonic counter minting a unique slot id per enqueued task. A slot
      * identifies one task's execution period for the interrupt bookkeeping in
-     * `executingSlot`/`interruptedSlots` — replacing the unowned skip-credit
+     * `executingInfo`/`interruptedSlots` — replacing the unowned skip-credit
      * counter, which any settle could consume and which therefore leaked a
      * re-armed count after repeated resets.
      */
     private slotCounter;
     /**
-     * Per-workspace slot id of the task currently executing. Set in the begin
-     * path right before the task runs; deleted when that task's settle fires.
-     * `resetExecutingCount` reads it to bind the interrupt credit to exactly
-     * the interrupted task's slot.
+     * Per-workspace record of the task currently executing — the lane occupant.
+     * Set in the begin path right before the task runs; deleted by that task's
+     * settle. Carries both the slot id (`resetExecutingCount` binds the
+     * interrupt credit to exactly the interrupted task's slot) and the display
+     * info the queue card needs to name what a waiting message waits for.
+     *
+     * 2026-10-09 线上：一次 Compact 占着 lane，新消息的排队卡却写「位置: 第 1
+     * 位 / 前面还有: 0 条消息」——开卡判据看 lane（含正在执行者），位置文案只看
+     * 等待队列，两个口径的差集正是这条记录。
      */
-    private executingSlot;
+    private executingInfo;
     /**
      * Per-workspace set of slot ids whose task was interrupted by
      * `resetExecutingCount`. When such a slot settles, its decrement is skipped
@@ -184,6 +218,12 @@ export declare class QueueManager {
      * after it). Consumed when the task's slot begins; removed if cancelled.
      */
     setTaskReplacement(cwd: string, messageId: string, task: () => Promise<void>): void;
+    /**
+     * 排队卡头部。只有前面确实还有等待中的消息时才说「排队」；前面为空时
+     * 用户等的是当前正在执行的任务（例如 Compact），用「等待当前任务结束」
+     * 表达才不会与「前面还有 0 条」自相矛盾（2026-10-09 线上实例）。
+     */
+    private queueCardHeader;
     /** Send a queue status card showing current queue position and actions. */
     private sendQueueStatusCard;
     /** Get queue info for a cwd. */
@@ -199,6 +239,10 @@ export declare class QueueManager {
      * both. Centralizing the pair here eliminates the 3-way duplication
      * between `buildQueueStatusCardElements`, `updateQueueCardToExecuting`,
      * and `updateQueueCardToCancelled` (Clean Code).
+     *
+     * `opts.immediateLabel`（仅 pending 卡用）在 lane 被 Compact 占用时替换
+     * 「⚡ 立即执行」并强制置灰：点击它会中断正在跑的压缩。「❌ 撤销」不参与，
+     * 它只移除等待中的消息，不触碰 Compact。
      */
     private buildQueueActionButtons;
     /**
@@ -251,7 +295,7 @@ export declare class QueueManager {
      * id minted at enqueue time. Three cases:
      *
      * 1. The slot is the workspace's current executing slot → its execution
-     *    period ends (`executingSlot` marker removed).
+     *    period ends (`executingInfo` record removed).
      * 2. The slot is in `interruptedSlots` (its task was interrupted by
      *    `resetExecutingCount`) → skip the decrement: the reset already zeroed
      *    the count, so a stale decrement could wrongly zero it again while a
@@ -279,7 +323,7 @@ export declare class QueueManager {
      * `expectedSlot` binds the reset to the task that was actually interrupted:
      * the caller captures the executing slot BEFORE stopping the runner, and
      * the stop window may outlive the interrupted task's settle (the chain can
-     * advance to a NEW task, which then owns `executingSlot`). When the current
+     * advance to a NEW task, which then owns `executingInfo`). When the current
      * slot no longer matches the interrupted task's slot, the interrupted task
      * already decremented normally — resetting now would zero the count of the
      * running successor and mark ITS slot interrupted, hiding it from the
@@ -290,5 +334,12 @@ export declare class QueueManager {
      * The slot id of the task currently executing in this cwd (if any).
      */
     getExecutingSlot(cwd: string): number | undefined;
+    /**
+     * The lane occupant's display info for this cwd (if any). Queue cards read
+     * it to name what a waiting message is waiting for; `handleQueueImmediate`
+     * reads it to refuse interrupting a running Compact. Returns a copy so
+     * callers cannot mutate the live record.
+     */
+    getExecutingInfo(cwd: string): ExecutingInfo | undefined;
 }
 export {};