lark-remote 0.5.13 → 0.5.14

package/dist/bridge/queue-manager.js

@@ -144,6 +144,11 @@ export class QueueManager {
     /**
      * Enqueue a task into the workspace-level serial queue.
      * Each cwd has its own serial queue for parallel execution across workspaces.
+     *
+     * 三段各自的职责：`registerQueuedTask`（排队元数据 + 满队拒收）、
+     * `beginQueuedTask`（接跑时刻的撤销检查/替换闭包/占用登记）、本方法
+     * （promise 链拼接与 settle 记账）。红线：链的拼接必须同步完成，
+     * 中途不得 await（否则两条入队会乱序）。
      */
     enqueue(cwd, task, opts) {
         // Guard: reject non-function tasks that would poison the queue chain
@@ -156,77 +161,9 @@ export class QueueManager {
         // interrupt credit granted by `resetExecutingCount` can only be consumed
         // by the interrupted task's own settle.
         const slotId = ++this.slotCounter;
-        // Track this task in the queue for display card
         const taskMeta = opts?.taskMeta;
-        let messagePreview;
-        if (taskMeta) {
-            messagePreview = taskMeta.messagePreview;
-            const queuedTask = {
-                userId: taskMeta.userId,
-                chatId: taskMeta.chatId,
-                messageId: taskMeta.messageId,
-                feishuReplyTo: taskMeta.feishuReplyTo,
-                cwd,
-                timestamp: Date.now(),
-                messagePreview,
-                editable: taskMeta.editable,
-                binding: taskMeta.binding,
-            };
-            // Check if there are tasks waiting BEFORE adding this one
-            const currentExecutingCount = this.pendingOrExecutingCount.get(cwd) ?? 0;
-            const currentQueueLength = this.queuedTasks.get(cwd)?.length ?? 0;
-            const hasWaitingTasks = currentExecutingCount > 0 || currentQueueLength > 0;
-            // bound the waiting backlog. When the queue is full, reject the
-            // task with a visible card instead of appending it (which would grow
-            // the promise chain + closures unboundedly under a message flood and
-            // fire another queue card). Do NOT increment pendingOrExecutingCount —
-            // a rejected task never executes, so it must not occupy a slot.
-            if (currentQueueLength >= MAX_WAITING_QUEUE) {
-                getLogger().warn(`[queue-manager] queue full cwd=${cwd} depth=${currentQueueLength} rejecting task messageId=${taskMeta.messageId}`);
-                void this.sendCard(taskMeta.chatId, cardWithHeader({
-                    template: 'red',
-                    title: '🚫 队列已满',
-                    elements: [
-                        {
-                            tag: 'div',
-                            text: {
-                                tag: 'lark_md',
-                                content: `当前工作目录已有 ${MAX_WAITING_QUEUE} 条消息排队等待，为防止积压已拒收本条消息。请等待队列消化后重发，或用 \`/stop\` 清空当前任务。`,
-                            },
-                        },
-                    ],
-                }), { replyTo: taskMeta.feishuReplyTo ?? taskMeta.messageId }).catch((err) => {
-                    getLogger().error('[queue-manager] failed to send queue-full rejection card:', err);
-                });
-                return;
-            }
-            // Add to cwd queue list
-            let taskList = this.queuedTasks.get(cwd);
-            if (!taskList) {
-                taskList = [];
-                this.queuedTasks.set(cwd, taskList);
-            }
-            // 身份不变量 tripwire：同一 cwd 内 queue key 必须唯一（一次入队动作一个
-            // key，铸造点 router.mintQueueTaskKey）。撞 key 时数组（追加）与 taskIndex
-            // （覆盖）必然漂移，位置显示/撤销/立即执行/卡片更新会串到别的条目上——
-            // 2026-10-08 线上缺陷就是这么长出来的。这里不改行为，只留证据。
-            if (this.indexGet(cwd, queuedTask.messageId)) {
-                getLogger().warn(`[queue-manager] duplicate queue key cwd=${cwd} messageId=${queuedTask.messageId} — ` +
-                    'queue identity must be minted per enqueue action (see router.mintQueueTaskKey)');
-            }
-            taskList.push(queuedTask);
-            this.indexAdd(cwd, queuedTask);
-            // Increment executing count SYNCHRONOUSLY so subsequent enqueues see it
-            this.pendingOrExecutingCount.set(cwd, currentExecutingCount + 1);
-            // Only send the queue card if the task actually has to wait.
-            if (hasWaitingTasks) {
-                void this.sendQueueStatusCard(cwd, taskMeta.chatId, taskMeta.messageId, messagePreview, 
-                // Reply to the real Feishu message id when the queue key is an
-                // internal key (order.exec); otherwise messageId IS the Feishu id.
-                taskMeta.feishuReplyTo);
-            }
-            getLogger().debug(`[queue-manager] enqueue task queued cwd=${cwd} queueCard=${hasWaitingTasks} executing=${currentExecutingCount + 1} queueLen=${currentQueueLength + 1}`);
-        }
+        if (taskMeta && !this.registerQueuedTask(cwd, taskMeta))
+            return;
         // Get or create the queue for this cwd
         let queue = this.queues.get(cwd);
         if (!queue) {
@@ -236,97 +173,8 @@ export class QueueManager {
         getLogger().debug(`[queue-manager] enqueue cwd=${cwd}`);
         // Capture messageId for cancellation guard
         const messageId = taskMeta?.messageId;
-        // messagePreview already captured above (outside taskMeta block)
         const newQueue = queue
-            .then(() => {
-            getLogger().debug(`[queue-manager] task begin cwd=${cwd} messageId=${messageId}`);
-            // Live preview for the executing card: read from the QueuedTask at
-            // begin time, not the enqueue-closure `taskMeta` (which is frozen).
-            // `updateQueuedTaskMessage` (queue.edit/queue.input) mutates the live
-            // task, so a task edited while queued must show the edited content
-            // when it naturally starts.
-            let livePreview = taskMeta?.messagePreview ?? '';
-            // Check if this task was cancelled before executing
-            if (messageId) {
-                // O(1) index lookup replaces the old `find` + `findIndex`
-                // double O(N) scan. The ordered array still drives removal (splice
-                // preserves queue order for position display); the index stays in
-                // sync via indexRemove.
-                const task = this.indexGet(cwd, messageId);
-                if (!task) {
-                    getLogger().debug(`[queue-manager] task skipped (cancelled) cwd=${cwd} messageId=${messageId}`);
-                    return;
-                }
-                livePreview = task.messagePreview;
-                // Remove this task's metadata by messageId
-                const taskList = this.queuedTasks.get(cwd);
-                const idx = taskList?.findIndex((t) => t.messageId === messageId) ?? -1;
-                if (taskList && idx >= 0) {
-                    taskList.splice(idx, 1);
-                }
-                this.indexRemove(cwd, messageId);
-                // Cancellation check passed and the task has been removed: it is
-                // about to run, so record it as began for queue.immediate feedback.
-                // Bounded: ids are only consulted for the current immediate target,
-                // so pruning the oldest entries is safe.
-                if (this.beganMessageIds.size >= 10_000) {
-                    const oldest = this.beganMessageIds.values().next().value;
-                    if (oldest !== undefined)
-                        this.beganMessageIds.delete(oldest);
-                }
-                this.beganMessageIds.add(messageId);
-            }
-            // Consume any one-shot replacement closure registered by
-            // `setTaskReplacement` (queue.edit + queue.immediate). The replacement
-            // swaps in the edited content at this task's original queue slot, so
-            // tasks queued behind it still run after it. Deleted here (one-shot)
-            // so a stale closure can never run on a later task.
-            let replacement;
-            if (messageId) {
-                const workspaceReplacements = this.taskReplacements.get(cwd);
-                replacement = workspaceReplacements?.get(messageId);
-                if (replacement) {
-                    workspaceReplacements?.delete(messageId);
-                    if (workspaceReplacements && workspaceReplacements.size === 0) {
-                        this.taskReplacements.delete(cwd);
-                    }
-                }
-            }
-            // Update queue card to "executing" status BEFORE running the task.
-            // This must happen after the cancellation check: a skipped/cancelled
-            // task must keep its "❌ 已撤销" card, not be flipped to executing.
-            if (messageId) {
-                void this.updateQueueCardToExecuting(cwd, messageId, livePreview, true);
-            }
-            // Re-arm the pending/executing count for every task that is about to
-            // run. `resetExecutingCount` (external interrupt) zeroes the count,
-            // and the interrupted task's settle consumes the skip-credit — so a
-            // task enqueued BEFORE the interrupt can begin with count 0. Without
-            // this, a running task is invisible to later enqueues and they
-            // silently skip the "⏳ 消息排队中" card. This applies regardless of
-            // taskMeta: resetExecutingCount can clear the count for any cwd,
-            // and a task that resumes after an interrupt must re-arm even when it
-            // carries no metadata.
-            const currentCount = this.pendingOrExecutingCount.get(cwd) ?? 0;
-            if (currentCount < 1) {
-                this.pendingOrExecutingCount.set(cwd, 1);
-                getLogger().debug(`[queue-manager] re-armed pendingOrExecutingCount cwd=${cwd} (interrupt resume)`);
-            }
-            // Mark this task as the lane occupant for its whole execution period
-            // before running it. `resetExecutingCount` reads the slot id to grant
-            // the interrupt credit to exactly this task; the settle removes the
-            // record. `kind`/`label` let a later message's queue card name what it
-            // is waiting for instead of reporting "前面还有 0 条".
-            this.executingInfo.set(cwd, {
-                slotId,
-                messageId,
-                kind: taskMeta?.kind ?? 'message',
-                label: laneOccupantLabel(taskMeta?.kind ?? 'message', livePreview),
-                preview: livePreview,
-                startedAt: Date.now(),
-            });
-            return replacement ? replacement() : task();
-        })
+            .then(() => this.beginQueuedTask(cwd, slotId, messageId, task, taskMeta))
             .then(() => {
             getLogger().debug(`[queue-manager] task end cwd=${cwd}`);
             // beganMessageIds entry intentionally retained: sticky by design
@@ -343,6 +191,177 @@ export class QueueManager {
         });
         this.queues.set(cwd, newQueue);
     }
+    /**
+     * 登记排队元数据（展示卡数据源 + 计数 + 排队卡）。
+     *
+     * @returns false = 队列已满被拒收（不入队、不占执行槽位），调用方必须
+     *   直接把任务链跳过。背压红线：满队时拒收而不是继续 append，否则 promise
+     *   链与闭包在消息洪峰下无界增长，还会多打一张排队卡。
+     */
+    registerQueuedTask(cwd, taskMeta) {
+        // Check if there are tasks waiting BEFORE adding this one
+        const currentExecutingCount = this.pendingOrExecutingCount.get(cwd) ?? 0;
+        const currentQueueLength = this.queuedTasks.get(cwd)?.length ?? 0;
+        const hasWaitingTasks = currentExecutingCount > 0 || currentQueueLength > 0;
+        if (currentQueueLength >= MAX_WAITING_QUEUE) {
+            getLogger().warn(`[queue-manager] queue full cwd=${cwd} depth=${currentQueueLength} rejecting task messageId=${taskMeta.messageId}`);
+            void this.sendQueueFullRejection(taskMeta);
+            return false;
+        }
+        const queuedTask = {
+            userId: taskMeta.userId,
+            chatId: taskMeta.chatId,
+            messageId: taskMeta.messageId,
+            feishuReplyTo: taskMeta.feishuReplyTo,
+            cwd,
+            timestamp: Date.now(),
+            messagePreview: taskMeta.messagePreview,
+            editable: taskMeta.editable,
+            binding: taskMeta.binding,
+        };
+        // Add to cwd queue list
+        let taskList = this.queuedTasks.get(cwd);
+        if (!taskList) {
+            taskList = [];
+            this.queuedTasks.set(cwd, taskList);
+        }
+        // 身份不变量 tripwire：同一 cwd 内 queue key 必须唯一（一次入队动作一个
+        // key，铸造点 router.mintQueueTaskKey）。撞 key 时数组（追加）与 taskIndex
+        // （覆盖）必然漂移，位置显示/撤销/立即执行/卡片更新会串到别的条目上——
+        // 2026-10-08 线上缺陷就是这么长出来的。这里不改行为，只留证据。
+        if (this.indexGet(cwd, queuedTask.messageId)) {
+            getLogger().warn(`[queue-manager] duplicate queue key cwd=${cwd} messageId=${queuedTask.messageId} — ` +
+                'queue identity must be minted per enqueue action (see router.mintQueueTaskKey)');
+        }
+        taskList.push(queuedTask);
+        this.indexAdd(cwd, queuedTask);
+        // Increment executing count SYNCHRONOUSLY so subsequent enqueues see it
+        this.pendingOrExecutingCount.set(cwd, currentExecutingCount + 1);
+        // Only send the queue card if the task actually has to wait.
+        if (hasWaitingTasks) {
+            void this.sendQueueStatusCard(cwd, taskMeta.chatId, taskMeta.messageId, taskMeta.messagePreview, 
+            // Reply to the real Feishu message id when the queue key is an
+            // internal key (order.exec); otherwise messageId IS the Feishu id.
+            taskMeta.feishuReplyTo);
+        }
+        getLogger().debug(`[queue-manager] enqueue task queued cwd=${cwd} queueCard=${hasWaitingTasks} executing=${currentExecutingCount + 1} queueLen=${currentQueueLength + 1}`);
+        return true;
+    }
+    /** 满队拒收卡（best-effort 送达，失败只记日志：任务已经被拒，不能再吞一次反馈）。 */
+    async sendQueueFullRejection(taskMeta) {
+        await this.sendCard(taskMeta.chatId, cardWithHeader({
+            template: 'red',
+            title: '🚫 队列已满',
+            elements: [
+                {
+                    tag: 'div',
+                    text: {
+                        tag: 'lark_md',
+                        content: `当前工作目录已有 ${MAX_WAITING_QUEUE} 条消息排队等待，为防止积压已拒收本条消息。请等待队列消化后重发，或用 \`/stop\` 清空当前任务。`,
+                    },
+                },
+            ],
+        }), { replyTo: taskMeta.feishuReplyTo ?? taskMeta.messageId }).catch((err) => {
+            getLogger().error('[queue-manager] failed to send queue-full rejection card:', err);
+        });
+    }
+    /**
+     * 轮到本任务执行：撤销检查 → 消费一次性替换闭包 → 排队卡转「执行中」→
+     * 重新武装计数与 lane 占用登记 → 跑任务闭包。
+     *
+     * @returns 任务闭包的 promise；被撤销时返回 undefined（本槽位什么都不跑）。
+     */
+    beginQueuedTask(cwd, slotId, messageId, task, taskMeta) {
+        getLogger().debug(`[queue-manager] task begin cwd=${cwd} messageId=${messageId}`);
+        // Live preview for the executing card: read from the QueuedTask at
+        // begin time, not the enqueue-closure `taskMeta` (which is frozen).
+        // `updateQueuedTaskMessage` (queue.edit/queue.input) mutates the live
+        // task, so a task edited while queued must show the edited content
+        // when it naturally starts.
+        let livePreview = taskMeta?.messagePreview ?? '';
+        // Check if this task was cancelled before executing
+        if (messageId) {
+            // O(1) index lookup replaces the old `find` + `findIndex`
+            // double O(N) scan. The ordered array still drives removal (splice
+            // preserves queue order for position display); the index stays in
+            // sync via indexRemove.
+            const queued = this.indexGet(cwd, messageId);
+            if (!queued) {
+                getLogger().debug(`[queue-manager] task skipped (cancelled) cwd=${cwd} messageId=${messageId}`);
+                return undefined;
+            }
+            livePreview = queued.messagePreview;
+            // Remove this task's metadata by messageId
+            const taskList = this.queuedTasks.get(cwd);
+            const idx = taskList?.findIndex((t) => t.messageId === messageId) ?? -1;
+            if (taskList && idx >= 0) {
+                taskList.splice(idx, 1);
+            }
+            this.indexRemove(cwd, messageId);
+            // Cancellation check passed and the task has been removed: it is
+            // about to run, so record it as began for queue.immediate feedback.
+            // Bounded: ids are only consulted for the current immediate target,
+            // so pruning the oldest entries is safe.
+            if (this.beganMessageIds.size >= 10_000) {
+                const oldest = this.beganMessageIds.values().next().value;
+                if (oldest !== undefined)
+                    this.beganMessageIds.delete(oldest);
+            }
+            this.beganMessageIds.add(messageId);
+        }
+        // Consume any one-shot replacement closure registered by
+        // `setTaskReplacement` (queue.edit + queue.immediate). The replacement
+        // swaps in the edited content at this task's original queue slot, so
+        // tasks queued behind it still run after it. Deleted here (one-shot)
+        // so a stale closure can never run on a later task.
+        const replacement = messageId ? this.takeTaskReplacement(cwd, messageId) : undefined;
+        // Update queue card to "executing" status BEFORE running the task.
+        // This must happen after the cancellation check: a skipped/cancelled
+        // task must keep its "❌ 已撤销" card, not be flipped to executing.
+        if (messageId) {
+            void this.updateQueueCardToExecuting(cwd, messageId, livePreview, true);
+        }
+        // Re-arm the pending/executing count for every task that is about to
+        // run. `resetExecutingCount` (external interrupt) zeroes the count,
+        // and the interrupted task's settle consumes the skip-credit — so a
+        // task enqueued BEFORE the interrupt can begin with count 0. Without
+        // this, a running task is invisible to later enqueues and they
+        // silently skip the "⏳ 消息排队中" card. This applies regardless of
+        // taskMeta: resetExecutingCount can clear the count for any cwd,
+        // and a task that resumes after an interrupt must re-arm even when it
+        // carries no metadata.
+        const currentCount = this.pendingOrExecutingCount.get(cwd) ?? 0;
+        if (currentCount < 1) {
+            this.pendingOrExecutingCount.set(cwd, 1);
+            getLogger().debug(`[queue-manager] re-armed pendingOrExecutingCount cwd=${cwd} (interrupt resume)`);
+        }
+        // Mark this task as the lane occupant for its whole execution period
+        // before running it. `resetExecutingCount` reads the slot id to grant
+        // the interrupt credit to exactly this task; the settle removes the
+        // record. `kind`/`label` let a later message's queue card name what it
+        // is waiting for instead of reporting "前面还有 0 条".
+        this.executingInfo.set(cwd, {
+            slotId,
+            messageId,
+            kind: taskMeta?.kind ?? 'message',
+            label: laneOccupantLabel(taskMeta?.kind ?? 'message', livePreview),
+            preview: livePreview,
+            startedAt: Date.now(),
+        });
+        return replacement ? replacement() : task();
+    }
+    /** 取走并清除该任务的一次性替换闭包（消费即销毁）。 */
+    takeTaskReplacement(cwd, messageId) {
+        const workspaceReplacements = this.taskReplacements.get(cwd);
+        const replacement = workspaceReplacements?.get(messageId);
+        if (replacement) {
+            workspaceReplacements?.delete(messageId);
+            if (workspaceReplacements && workspaceReplacements.size === 0) {
+                this.taskReplacements.delete(cwd);
+            }
+        }
+        return replacement;
+    }
     /**
      * Execute a task immediately without going through the queue.
      * Used for / commands that should respond immediately.

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

@@ -1,5 +1,6 @@
 import { type AppConfig } from '../config/index.js';
-import type { AgentKind, Runner } from '../runner/index.js';
+import type { AgentKind } from '../agent-kinds.js';
+import type { Runner } from '../runner/index.js';
 import type { RunCardSession } from '../card/run-card-session.js';
 import { ApprovalCoordinator } from './approval-coordinator.js';
 export declare function remindPendingApproval(connector: {

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

@@ -1,46 +1,32 @@
 import type { ResultEvent } from '../runner/types.js';
 import type { FinalUsageSnapshot } from './final-usage.js';
+import type { UsageSnapshot } from '../session-contract.js';
 export type UsageAuthority = 'live' | 'jsonl';
+/**
+ * 一张 run 的用量记账：live 侧（result 事件 / compact_boundary）先收着，
+ * run 结束时与 jsonl 快照按权威来源合成一份 `UsageSnapshot`。
+ *
+ * live 侧字段清单只有 `UsageSnapshot` 一份：此前这里是 19 个 `final*` 平铺
+ * 字段逐字段搬运，加一个 usage 字段要改三处（§9.21 的一致性靠人记）。
+ */
 export declare class RunUsageCollector {
+    /** live 侧观察值（jsonl 读不到时的兜底）。 */
     private contextLength?;
-    private finalContextLength?;
-    private finalContextLimit?;
-    private finalCompactCount?;
-    private finalCacheReadTokens?;
-    private finalCacheCreationTokens?;
-    private finalTotalTokens?;
     private liveInput?;
     private liveOutput?;
     private liveContextLimit?;
-    private finalInputTokens?;
-    private finalOutputTokens?;
-    private finalCumulativeTotalTokens?;
-    private finalCumulativeInputTokens?;
-    private finalCumulativeOutputTokens?;
-    private finalCumulativeCacheReadTokens?;
-    private finalCumulativeCacheCreationTokens?;
-    private finalReasoningTokens?;
+    private liveCacheRead?;
+    private liveCacheCreation?;
+    private liveTotal?;
+    private liveReasoningTokens?;
+    /** finalize() 之后的最终口径；meta() 的唯一数据源。 */
+    private resolved;
     resultNotSuccess: boolean;
     get liveInputTokens(): number | undefined;
     get liveOutputTokens(): number | undefined;
     observeCompaction(postTokens: number): void;
     observeResult(event: ResultEvent): void;
     finalize(finalUsage: FinalUsageSnapshot | undefined, authority: UsageAuthority | undefined): void;
-    meta(): {
-        contextLength?: number;
-        contextLimit?: number;
-        compactCount?: number;
-        cacheReadTokens?: number;
-        cacheCreationTokens?: number;
-        totalTokens?: number;
-        inputTokens?: number;
-        outputTokens?: number;
-        cumulativeTotalTokens?: number;
-        cumulativeInputTokens?: number;
-        cumulativeOutputTokens?: number;
-        cumulativeCacheReadTokens?: number;
-        cumulativeCacheCreationTokens?: number;
-        reasoningTokens?: number;
-    };
+    meta(): UsageSnapshot;
     logSummary(runId: string): string;
 }

package/dist/bridge/run-usage.js

@@ -1,23 +1,23 @@
 import { normalizeResultUsage } from '../runner/common/result-usage.js';
+/**
+ * 一张 run 的用量记账：live 侧（result 事件 / compact_boundary）先收着，
+ * run 结束时与 jsonl 快照按权威来源合成一份 `UsageSnapshot`。
+ *
+ * live 侧字段清单只有 `UsageSnapshot` 一份：此前这里是 19 个 `final*` 平铺
+ * 字段逐字段搬运，加一个 usage 字段要改三处（§9.21 的一致性靠人记）。
+ */
 export class RunUsageCollector {
+    /** live 侧观察值（jsonl 读不到时的兜底）。 */
     contextLength;
-    finalContextLength;
-    finalContextLimit;
-    finalCompactCount;
-    finalCacheReadTokens;
-    finalCacheCreationTokens;
-    finalTotalTokens;
     liveInput;
     liveOutput;
     liveContextLimit;
-    finalInputTokens;
-    finalOutputTokens;
-    finalCumulativeTotalTokens;
-    finalCumulativeInputTokens;
-    finalCumulativeOutputTokens;
-    finalCumulativeCacheReadTokens;
-    finalCumulativeCacheCreationTokens;
-    finalReasoningTokens;
+    liveCacheRead;
+    liveCacheCreation;
+    liveTotal;
+    liveReasoningTokens;
+    /** finalize() 之后的最终口径；meta() 的唯一数据源。 */
+    resolved = {};
     resultNotSuccess = false;
     get liveInputTokens() {
         return this.liveInput;
@@ -39,54 +39,45 @@ export class RunUsageCollector {
         this.liveOutput = usage.outputTokens;
         this.liveContextLimit = usage.contextLimit;
         if (usage.cacheReadTokens !== undefined)
-            this.finalCacheReadTokens = usage.cacheReadTokens;
+            this.liveCacheRead = usage.cacheReadTokens;
         if (usage.cacheCreationTokens !== undefined) {
-            this.finalCacheCreationTokens = usage.cacheCreationTokens;
+            this.liveCacheCreation = usage.cacheCreationTokens;
         }
         if (usage.totalTokens !== undefined)
-            this.finalTotalTokens = usage.totalTokens;
+            this.liveTotal = usage.totalTokens;
         if (usage.reasoningTokens !== undefined)
-            this.finalReasoningTokens = usage.reasoningTokens;
+            this.liveReasoningTokens = usage.reasoningTokens;
     }
     finalize(finalUsage, authority) {
-        this.finalContextLength = finalUsage?.contextLength ?? this.contextLength;
-        this.finalContextLimit = finalUsage?.contextLimit ?? this.liveContextLimit;
-        this.finalCompactCount = finalUsage?.compactCount;
-        this.finalCumulativeTotalTokens = finalUsage?.cumulativeTotalTokens;
-        this.finalCumulativeInputTokens = finalUsage?.cumulativeInputTokens;
-        this.finalCumulativeOutputTokens = finalUsage?.cumulativeOutputTokens;
-        this.finalCumulativeCacheReadTokens = finalUsage?.cumulativeCacheReadTokens;
-        this.finalCumulativeCacheCreationTokens = finalUsage?.cumulativeCacheCreationTokens;
+        const resolved = {
+            // 从 jsonl 快照整体展开，新增 UsageSnapshot 字段无需再改这里。
+            ...finalUsage,
+            contextLength: finalUsage?.contextLength ?? this.contextLength,
+            contextLimit: finalUsage?.contextLimit ?? this.liveContextLimit,
+            compactCount: finalUsage?.compactCount,
+            // result 事件里的 cache/total 两条路径都要带：jsonl 读得到时被覆盖，
+            // 读不到（或走 live flow scope）时它就是最终数字。
+            cacheReadTokens: this.liveCacheRead,
+            cacheCreationTokens: this.liveCacheCreation,
+            totalTokens: this.liveTotal,
+            reasoningTokens: this.liveReasoningTokens,
+        };
         const useLiveFlowScope = authority !== 'jsonl' && this.liveInput !== undefined && this.liveOutput !== undefined;
         if (useLiveFlowScope) {
-            this.finalInputTokens = this.liveInput;
-            this.finalOutputTokens = this.liveOutput;
+            resolved.inputTokens = this.liveInput;
+            resolved.outputTokens = this.liveOutput;
+            this.resolved = resolved;
             return;
         }
-        this.finalInputTokens = finalUsage?.inputTokens ?? this.liveInput;
-        this.finalOutputTokens = finalUsage?.outputTokens ?? this.liveOutput;
-        this.finalCacheReadTokens = finalUsage?.cacheReadTokens ?? this.finalCacheReadTokens;
-        this.finalCacheCreationTokens =
-            finalUsage?.cacheCreationTokens ?? this.finalCacheCreationTokens;
-        this.finalTotalTokens = finalUsage?.totalTokens ?? this.finalTotalTokens;
+        resolved.inputTokens = finalUsage?.inputTokens ?? this.liveInput;
+        resolved.outputTokens = finalUsage?.outputTokens ?? this.liveOutput;
+        resolved.cacheReadTokens = finalUsage?.cacheReadTokens ?? this.liveCacheRead;
+        resolved.cacheCreationTokens = finalUsage?.cacheCreationTokens ?? this.liveCacheCreation;
+        resolved.totalTokens = finalUsage?.totalTokens ?? this.liveTotal;
+        this.resolved = resolved;
     }
     meta() {
-        return {
-            contextLength: this.finalContextLength,
-            contextLimit: this.finalContextLimit,
-            compactCount: this.finalCompactCount,
-            cacheReadTokens: this.finalCacheReadTokens,
-            cacheCreationTokens: this.finalCacheCreationTokens,
-            totalTokens: this.finalTotalTokens,
-            inputTokens: this.finalInputTokens,
-            outputTokens: this.finalOutputTokens,
-            cumulativeTotalTokens: this.finalCumulativeTotalTokens,
-            cumulativeInputTokens: this.finalCumulativeInputTokens,
-            cumulativeOutputTokens: this.finalCumulativeOutputTokens,
-            cumulativeCacheReadTokens: this.finalCumulativeCacheReadTokens,
-            cumulativeCacheCreationTokens: this.finalCumulativeCacheCreationTokens,
-            reasoningTokens: this.finalReasoningTokens,
-        };
+        return this.resolved;
     }
     logSummary(runId) {
         const meta = this.meta();

package/dist/bridge/session-writeback.d.ts

@@ -1,10 +1,11 @@
-import type { AgentKind, TurnStartedEvent } from '../runner/index.js';
+import type { AgentKind } from '../agent-kinds.js';
+import type { TurnStartedEvent } from '../runner/index.js';
 import type { SessionStore } from '../session/index.js';
 interface InitEvent {
     session_id: string;
     cwd?: string;
 }
-interface WritebackContext {
+export interface WritebackContext {
     sessionStore: SessionStore;
     userId: string;
     agentKind: AgentKind;

package/dist/card/approval-render.d.ts

@@ -5,6 +5,7 @@
  * Uses CardKit 2.0 (no tag:"action" container — 200861 rule).
  */
 import type { ApprovalView } from '../runner/types.js';
+import { type RunTerminal } from './run-state.js';
 /**
  * Render the approval area for a run card.
  * Returns an array of CardKit 2.0 elements to append to the card body.
@@ -12,7 +13,7 @@ import type { ApprovalView } from '../runner/types.js';
 export declare function renderApprovalArea(approval: ApprovalView | undefined, opts?: {
     expired?: boolean;
     runId?: string;
-    terminal?: string;
+    terminal?: RunTerminal;
 }): object[];
 /**
  * 紧凑审批区（run 卡 skeleton/truncatedSkeleton 兜底档专用）：固定小体积的
@@ -26,5 +27,5 @@ export declare function renderApprovalArea(approval: ApprovalView | undefined, o
 export declare function renderApprovalAreaCompact(approval: ApprovalView | undefined, opts?: {
     expired?: boolean;
     runId?: string;
-    terminal?: string;
+    terminal?: RunTerminal;
 }): object[];

package/dist/card/approval-render.js

@@ -9,6 +9,7 @@ import { truncateMarkdownTables } from './text-truncate.js';
 import { truncateUtf8 } from '../common/truncate.js';
 import { cardButton } from './card-shared.js';
 import { countCardElements } from './card-budget.js';
+import { isRunActive } from './run-state.js';
 /** Unique nonce for card button callbacks (SDK dedup + router validation). */
 function mkNonce() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
@@ -156,9 +157,9 @@ export function renderApprovalAreaCompact(approval, opts) {
     }
     return elements;
 }
-/** 终态隐藏判定（renderApprovalArea 与 compact 共用）。 */
+/** 终态隐藏判定（renderApprovalArea 与 compact 共用）：仍在推进的 run 不隐藏按钮。 */
 function isTerminalHidden(opts) {
-    return !!opts?.terminal && opts.terminal !== 'running' && opts.terminal !== 'finalizing';
+    return !!opts?.terminal && !isRunActive(opts.terminal);
 }
 /**
  * Render approval action buttons from the real protocol decision list.

package/dist/{router → card}/card-helpers.d.ts

@@ -1,13 +1,13 @@
 /**
- * Shared CardKit helpers for router cards (session history, dashboard,
- * ls, ws, etc.).
+ * 卡片构造的共享工具（会话历史卡、分页条、搜索条、ls/ws 面板等）。
  *
- * Re-exports `markdownDiv` from `card/collapsible.ts` and adds session-content
- * specific builders (e.g. `sessionEventPanel`) so `router/index.ts` can fold
- * long session histories into collapsible panels without duplicating logic.
+ * 归属 card/：这些是纯建卡函数，此前住在 router/ 导致 card→router 与
+ * bridge→router 两条反向依赖。`markdownDiv` 从 `card/collapsible.ts` 复用，
+ * 会话内容相关的 builder（如 `sessionEventPanel`）在这里单源，router 与
+ * bridge 都只调用不复制。
  */
-import { markdownDiv } from '../card/collapsible.js';
-import type { AgentSessionContentEvent } from '../runner/index.js';
+import { markdownDiv } from './collapsible.js';
+import type { AgentSessionContentEvent } from '../session-contract.js';
 import { formatUsageStats } from './usage-format.js';
 type SessionUsageLike = Parameters<typeof formatUsageStats>[0];
 export declare function sessionEventPanel(ev: AgentSessionContentEvent, index: number, totalEvents: number, tailExpandedCount?: number, agentKind?: string): object;