lark-remote 0.5.13 → 0.5.15

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.15] - 2026-10-31
+
+### 修复
+
+- **`/stop` 落在「刚发消息、卡片还没建好」的窗口里不再空跑整轮**：此前卡片已经定格成「已中断」，但 agent 进程还没起来、没有可杀的进程，`run()` 入口又会把停止标记重置回去，于是整轮照常跑完并继续改动工作区。现在卡片一旦进入终态就直接收口，不再启动 agent
+- **中断归因不再串台**：显式 `/stop` 不再被上一次遗留的粘性「审批超时」状态盖掉；在审批卡上点「取消」现在会如实归因成用户取消并由卡片透传，终态卡不再显示「审批超时」（该文案此前实际不可达）
+- **目标状态读不到时不再谎报「已完成」**：终态复核探测不到目标状态时显式标记为「未知」；投影里缺少目标域按「明确没有目标」处理，不会把普通会话误标成「目标未确认」
+- **opencode / kimi 卡片「本 run」token 低报或虚高**：ACP 的用量通知只带上下文占用与花费、没有输入输出拆分，这两个 agent 的卡片只能从会话文件兜底读取。opencode 取的是「最后一条 assistant 消息」而一条消息等于一次模型请求，实测一条 25 次请求的 run 卡片显示 Input 543 / Output 1,250，真实消耗是 20,040 / 10,358（相邻两张卡的「累计」差值反而对得上）；kimi 更直接把整条会话的总量当本 run。现在两个 reader 都汇总**末个 turn** 的采样：opencode 以它自带的 turn 结束标记为边界（文件停在回合中间时就是当前回合），kimi 以 `turn.prompt` 为边界；`Context` 仍是末次请求的窗口水位，`累计` 仍是会话总量，口径不变；没有 turn 标记的旧数据沿用原语义
+- **opencode 冷启动失败不再引导用户重启服务**：daemon 刚重启时模型目录还在加载，`/api/model` 会连续几分钟返 503，旧退避（0.5/1.5/3 秒）整段落在这个窗口里、四次重试无一命中，失败文案又叫用户 `opencode service restart`——重启只会清掉已热状态、重新进入同一个窗口。现在退避改为 0.5/2/8/20/45 秒（连每次请求自身约 10 秒超时，覆盖约 2 分钟窗口），重试耗尽后丢弃该工作目录的缓存连接、下一轮重新拉起 agent server，不再复用一个没激活的子进程；文案改成「冷启动/模型目录加载期间的临时状态，等 1–2 分钟重发」
+- **`/compact` 的卡片流启动失败时补发静态终态卡**，不再只剩一条「Compact 已触发」加一个表情；兜底的完成通知卡标题跟随真实终态
+- **收尾报文更如实**：区分「没收到结果」与「结果没落到卡片上」，不再用同一句话盖掉两种原因
+
+### 变更
+
+- run 终态卡文案更如实：目标被阻断 / 已暂停分别显示「目标被阻断」「目标已暂停」，不再统一写「已完成」；目标读取失败时标题写「完成（目标未确认）」、摘要首行同步；`goal_continuing` 的原消息表情由 Done 改为 OnIt；run 是否活跃改用统一的终态判据收口
+
+## [0.5.14] - 2026-10-28
+
+### 修复
+
+- **卡片停止刷新不再查不到原因**：飞书拒收一次卡片更新后，这张卡会被永久剔除、此后不再原地刷新（用户侧表现为「卡片卡在最后一步」）。这条失败此前只记 debug 级日志，在默认 `info` 级别下看不到；现在按 warn 记录，带上下原因
+- **自重启的前实例信息读取失败不再被误归因**：`/restart` 读旧实例的 startup-contact 时，只有「从未写过」（首次运行）算正常；解析失败或权限问题现在会留痕，否则排查时被当成「旧 owner 没有条目」而走错方向
+
+### 维护
+
+- **agent 名单、会话读取契约、用量字段与模型别名各自单源**：新增 `src/agent-kinds.ts`、`src/session-contract.ts`、`src/model-catalog.ts`。用量字段清单原先手抄了 5 份、加一个字段要同时改三处，现在统一从一处派生。无行为变化
+- **模块归位，依赖方向只剩单向**：`card-helpers` / `usage-format` 从 router 移入 card，DSH 的协议、类型与 home 解析从 runner 提到 `src/dsh/`；地基层（配置、会话、卡片）不再反向 import 上层，并加了依赖方向守卫用例守住这条边。无行为变化
+- **`/config` 卡片删掉从未被任何字段使用的开关控件形态**，同时加「控件 ↔ 处理端」一致性守卫：渲染得出的按钮必定有对应处理分支，也不会漏进即时动作名单——「按钮点下去没人处理」这类状态从此被测出来
+- **审批动作与排队管理从 bridge 拆成独立模块**，入口装配线（进程级异常处理器、ConfigDir 派生路径、agent 工厂闭包）收拢为单文件静态守卫；顺带清掉死代码、重复实现与静默吞错的分支。无行为变化
+- **单元测试纳入类型检查**：`tsconfig.test-infra.json` 不再排除 `src/**/*.test.ts`，`bun run typecheck` 现在会检查测试文件的类型，测试夹具里的陈旧键当场可见
+
 ## [0.5.13] - 2026-10-26
 
 ### 修复

package/dist/agent-kinds.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent 名单单源（运行时数组 + 类型同源，二者不可能漂移）。
+ *
+ * 中立层：config（校验 defaultAgent）、session（按 agent 存 sessionId）、card
+ * （显示名）、router（解析用户输入）、runner（实现各家 runner）都要用这个名字，
+ * 谁都不该为了拿它去 import 别层的模块 —— 名单原先住在 runner/types.ts 时，
+ * 地基层 config 就得反向 import 上层 runner。
+ *
+ * 历史上这份名单被手抄成多份（router 的 VALID_AGENTS、bridge 的 resume.compact
+ * 校验、各 agent 的 config builder…），漂移过：dsh 加入后 bridge 的
+ * resume.compact 仍只有 5 个，带 dsh 的 resume 卡片会静默退回 defaultAgent。
+ * 新增 agent 只改这里。
+ */
+export declare const AGENT_KINDS: readonly ["claude", "codex", "opencode", "pi", "kimi", "dsh"];
+export type AgentKind = (typeof AGENT_KINDS)[number];
+/** 用户可见 agent 显示名单源：启动注册与无 registry 的回退路径共用。 */
+export declare const AGENT_DISPLAY_NAMES: Record<AgentKind, string>;
+/** 任意输入（卡片 payload / 命令行参数）是否是一个已知 agent 名。 */
+export declare function isAgentKind(value: unknown): value is AgentKind;
+/**
+ * 解析用户给出的 agent 名，未知/缺省时回退 `fallback`。
+ *
+ * 判定此前抄了三份（router 的两处 resume 分支 + commands/resume.ts）；名单与
+ * 判定同源才有意义——`resume.compact` 曾因手抄名单漏掉 dsh 而静默退回
+ * defaultAgent（见 `AGENT_KINDS` 头注）。
+ */
+export declare function resolveAgentKind(value: unknown, fallback: AgentKind): AgentKind;

package/dist/agent-kinds.js

@@ -0,0 +1,38 @@
+/**
+ * Agent 名单单源（运行时数组 + 类型同源，二者不可能漂移）。
+ *
+ * 中立层：config（校验 defaultAgent）、session（按 agent 存 sessionId）、card
+ * （显示名）、router（解析用户输入）、runner（实现各家 runner）都要用这个名字，
+ * 谁都不该为了拿它去 import 别层的模块 —— 名单原先住在 runner/types.ts 时，
+ * 地基层 config 就得反向 import 上层 runner。
+ *
+ * 历史上这份名单被手抄成多份（router 的 VALID_AGENTS、bridge 的 resume.compact
+ * 校验、各 agent 的 config builder…），漂移过：dsh 加入后 bridge 的
+ * resume.compact 仍只有 5 个，带 dsh 的 resume 卡片会静默退回 defaultAgent。
+ * 新增 agent 只改这里。
+ */
+export const AGENT_KINDS = ['claude', 'codex', 'opencode', 'pi', 'kimi', 'dsh'];
+/** 用户可见 agent 显示名单源：启动注册与无 registry 的回退路径共用。 */
+export const AGENT_DISPLAY_NAMES = {
+    claude: 'Claude',
+    codex: 'Codex',
+    opencode: 'Opencode',
+    pi: 'Pi',
+    kimi: 'Kimi',
+    dsh: 'DSH',
+};
+/** 任意输入（卡片 payload / 命令行参数）是否是一个已知 agent 名。 */
+export function isAgentKind(value) {
+    return AGENT_KINDS.includes(value);
+}
+/**
+ * 解析用户给出的 agent 名，未知/缺省时回退 `fallback`。
+ *
+ * 判定此前抄了三份（router 的两处 resume 分支 + commands/resume.ts）；名单与
+ * 判定同源才有意义——`resume.compact` 曾因手抄名单漏掉 dsh 而静默退回
+ * defaultAgent（见 `AGENT_KINDS` 头注）。
+ */
+export function resolveAgentKind(value, fallback) {
+    return isAgentKind(value) ? value : fallback;
+}
+//# sourceMappingURL=agent-kinds.js.map

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

@@ -0,0 +1,95 @@
+/**
+ * 审批卡动作分发（Bridge 的终态卡动作侧，审计 #32 的一刀）。
+ *
+ * 每个方法只做一件事：按 runId 找到那次 run 的 `ApprovalCoordinator`，把卡片
+ * payload 翻成一次 coordinator 调用。原先这 7 个 handler 连同「找不到
+ * coordinator 怎么回答」的公共前缀平铺在 Bridge 里，占了 160 行却不碰任何
+ * Bridge 状态——只碰 `approvalCoordinators` 这一张表。
+ *
+ * 语义红线（保留原位，别在调用方重新实现）：
+ * - run 已结束（coordinator 已释放）时点审批按钮必须给用户明确反馈，不能静默；
+ *   router 把这个异常转成 error toast。
+ * - `nonce` 原样透传给 coordinator：飞书会重投递同一个按钮回调，去重靠它
+ *   （见 approval-coordinator.ts 的状态机注释）。
+ */
+import type { ApprovalCoordinator } from './approval-coordinator.js';
+export interface ApprovalActionDeps {
+    /** 按 runId 取该 run 的 coordinator；已结束返回 undefined。 */
+    coordinatorFor(runId: string): ApprovalCoordinator | undefined;
+}
+/** 所有 handler 共用的入参形状。 */
+interface RunScopedOpts {
+    runId: string;
+    requestId: number | string;
+}
+export declare class ApprovalActions {
+    private deps;
+    constructor(deps: ApprovalActionDeps);
+    /**
+     * Resolve the ApprovalCoordinator for a run, or throw the standard
+     * "已结束" error. Shared preamble of all approval card-action handlers.
+     */
+    private withCoordinator;
+    private dispatchQuestionAction;
+    /**
+     * Handle an approval response from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    handleApprovalRespond(opts: RunScopedOpts & {
+        decision: string;
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * 计划审批修改意见（ExitPlanMode 输入框）：记录到 coordinator 并回流卡片。
+     * 「拒绝并附意见」/「批准并采纳修改」按钮复用该文本。
+     */
+    handleApprovalPlanFeedback(opts: RunScopedOpts & {
+        text: string;
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * Handle a permission toggle from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    handleApprovalToggle(opts: RunScopedOpts & {
+        permId: string;
+        selected?: boolean;
+    }): Promise<void>;
+    /**
+     * Claude AskUserQuestion 选项点击（单选即时提交 / 多选切换勾选）。
+     * 路由到 ApprovalCoordinator.toggleAnswer。
+     */
+    handleApprovalAnswer(opts: RunScopedOpts & {
+        questionIndex: number;
+        option: string;
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * Claude AskUserQuestion 多选问题的「提交答案」按钮。
+     * 路由到 ApprovalCoordinator.submitAnswers。
+     */
+    handleApprovalAnswerSubmit(opts: RunScopedOpts & {
+        questionIndex: number;
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * Claude AskUserQuestion 自定义答案（Other）：自由文本直接
+     * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
+     */
+    handleApprovalAnswerCustom(opts: RunScopedOpts & {
+        questionIndex: number;
+        text: string;
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * Codex AskUserQuestion 补充说明（user_note，2026-08-18 live 验证模型理解
+     * "user_note: <text>" 条目）：记录到 coordinator，随答案一起提交。
+     * 路由到 ApprovalCoordinator.answerNote。
+     */
+    handleApprovalAnswerNote(opts: RunScopedOpts & {
+        questionIndex: number;
+        text: string;
+        nonce: string;
+    }): Promise<void>;
+}
+export {};

package/dist/bridge/approval-actions.js

@@ -0,0 +1,104 @@
+/**
+ * 审批卡动作分发（Bridge 的终态卡动作侧，审计 #32 的一刀）。
+ *
+ * 每个方法只做一件事：按 runId 找到那次 run 的 `ApprovalCoordinator`，把卡片
+ * payload 翻成一次 coordinator 调用。原先这 7 个 handler 连同「找不到
+ * coordinator 怎么回答」的公共前缀平铺在 Bridge 里，占了 160 行却不碰任何
+ * Bridge 状态——只碰 `approvalCoordinators` 这一张表。
+ *
+ * 语义红线（保留原位，别在调用方重新实现）：
+ * - run 已结束（coordinator 已释放）时点审批按钮必须给用户明确反馈，不能静默；
+ *   router 把这个异常转成 error toast。
+ * - `nonce` 原样透传给 coordinator：飞书会重投递同一个按钮回调，去重靠它
+ *   （见 approval-coordinator.ts 的状态机注释）。
+ */
+import { getLogger } from '../logger/index.js';
+import { decisionToApprovalAction } from './approval-coordinator.js';
+export class ApprovalActions {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Resolve the ApprovalCoordinator for a run, or throw the standard
+     * "已结束" error. Shared preamble of all approval card-action handlers.
+     */
+    withCoordinator(runId, fn) {
+        const coordinator = this.deps.coordinatorFor(runId);
+        if (!coordinator) {
+            getLogger().warn(`[lark-remote] no approval coordinator for runId=${runId.slice(0, 8)}`);
+            throw new Error('任务已结束，审批无法响应');
+        }
+        return fn(coordinator);
+    }
+    dispatchQuestionAction(opts, action, invoke) {
+        getLogger().info(`[lark-remote] ${action} runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
+        return this.withCoordinator(opts.runId, invoke);
+    }
+    /**
+     * Handle an approval response from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    async handleApprovalRespond(opts) {
+        getLogger().info(`[lark-remote] handleApprovalRespond runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} decision=${opts.decision}`);
+        return this.withCoordinator(opts.runId, async (coordinator) => {
+            // Build ApprovalAction from the decision string
+            const action = decisionToApprovalAction(opts.decision);
+            await coordinator.submit(action, { requestId: opts.requestId, nonce: opts.nonce });
+        });
+    }
+    /**
+     * 计划审批修改意见（ExitPlanMode 输入框）：记录到 coordinator 并回流卡片。
+     * 「拒绝并附意见」/「批准并采纳修改」按钮复用该文本。
+     */
+    async handleApprovalPlanFeedback(opts) {
+        return this.withCoordinator(opts.runId, async (coordinator) => {
+            await coordinator.planFeedback({ text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce });
+        });
+    }
+    /**
+     * Handle a permission toggle from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    async handleApprovalToggle(opts) {
+        getLogger().info(`[lark-remote] handleApprovalToggle runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} permId=${opts.permId}`);
+        return this.withCoordinator(opts.runId, async (coordinator) => {
+            // selected 由卡片根据当前渲染状态传回（取反），不再硬编码只授不撤。
+            const toggleAction = {
+                permId: opts.permId,
+                selected: opts.selected ?? true,
+            };
+            await coordinator.togglePerm(toggleAction, { requestId: opts.requestId });
+        });
+    }
+    /**
+     * Claude AskUserQuestion 选项点击（单选即时提交 / 多选切换勾选）。
+     * 路由到 ApprovalCoordinator.toggleAnswer。
+     */
+    async handleApprovalAnswer(opts) {
+        return this.dispatchQuestionAction(opts, 'handleApprovalAnswer', (coordinator) => coordinator.toggleAnswer({ questionIndex: opts.questionIndex, option: opts.option }, { requestId: opts.requestId, nonce: opts.nonce }));
+    }
+    /**
+     * Claude AskUserQuestion 多选问题的「提交答案」按钮。
+     * 路由到 ApprovalCoordinator.submitAnswers。
+     */
+    async handleApprovalAnswerSubmit(opts) {
+        return this.dispatchQuestionAction(opts, 'handleApprovalAnswerSubmit', (coordinator) => coordinator.submitAnswers({ questionIndex: opts.questionIndex }, { requestId: opts.requestId, nonce: opts.nonce }));
+    }
+    /**
+     * Claude AskUserQuestion 自定义答案（Other）：自由文本直接
+     * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
+     */
+    async handleApprovalAnswerCustom(opts) {
+        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 验证模型理解
+     * "user_note: <text>" 条目）：记录到 coordinator，随答案一起提交。
+     * 路由到 ApprovalCoordinator.answerNote。
+     */
+    async handleApprovalAnswerNote(opts) {
+        return this.dispatchQuestionAction(opts, 'handleApprovalAnswerNote', (coordinator) => coordinator.answerNote({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
+    }
+}
+//# sourceMappingURL=approval-actions.js.map

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

@@ -37,6 +37,15 @@ export declare class ApprovalCoordinator {
     private approvals;
     /** 已提交过的 nonce（按 requestId）：同一按钮连点/飞书重投递只生效一次。 */
     private submittedNonces;
+    /**
+     * 用户是否在审批卡上主动点了「取消」。
+     *
+     * run 的终态归因需要它：cancel 在真实协议里是「停止等待」，agent 可能继续
+     * 跑，turn 结束时只剩一个泛化的 interrupted。桥据此把终态写成
+     * approval_cancelled，与 /stop（user_stop）、审批超时（approval_timeout）
+     * 区分开。仅在 responder 成功后置位——提交失败仍可重试。
+     */
+    private userCancelled;
     private readonly approvalTimeoutMs;
     private readonly responder;
     private readonly interruptTurn;
@@ -139,6 +148,10 @@ export declare class ApprovalCoordinator {
      * approvals must not be resurrected or rewritten.
      */
     updateView(requestId: number | string, view: ApprovalView): void;
+    /**
+     * 用户是否在审批卡上主动点了「取消」（终态归因用；提交失败不置位）。
+     */
+    get cancelledByUser(): boolean;
     /**
      * Get the number of pending approvals.
      */

package/dist/bridge/approval-coordinator.js

@@ -16,6 +16,15 @@ export class ApprovalCoordinator {
     approvals = new Map();
     /** 已提交过的 nonce（按 requestId）：同一按钮连点/飞书重投递只生效一次。 */
     submittedNonces = new Map();
+    /**
+     * 用户是否在审批卡上主动点了「取消」。
+     *
+     * run 的终态归因需要它：cancel 在真实协议里是「停止等待」，agent 可能继续
+     * 跑，turn 结束时只剩一个泛化的 interrupted。桥据此把终态写成
+     * approval_cancelled，与 /stop（user_stop）、审批超时（approval_timeout）
+     * 区分开。仅在 responder 成功后置位——提交失败仍可重试。
+     */
+    userCancelled = false;
     approvalTimeoutMs;
     responder;
     interruptTurn;
@@ -131,6 +140,9 @@ export class ApprovalCoordinator {
         try {
             await this.responder(ctx.requestId, effectiveAction);
             tracked.state = 'resolved';
+            // 终态归因：用户主动取消才置位（accept/decline 都是"继续本轮"）。
+            if (effectiveAction.action === 'cancel')
+                this.userCancelled = true;
             // nonce 在 responder 成功后才消费：失败可原按钮重试，
             // 不会被自己的 nonce 去重挡掉（失败后已回滚 pending 并重新计时）。
             this.consumeNonce(ctx.requestId, ctx.nonce);
@@ -301,6 +313,12 @@ export class ApprovalCoordinator {
             return;
         tracked.view = view;
     }
+    /**
+     * 用户是否在审批卡上主动点了「取消」（终态归因用；提交失败不置位）。
+     */
+    get cancelledByUser() {
+        return this.userCancelled;
+    }
     /**
      * Get the number of pending approvals.
      */

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

@@ -1,22 +1,13 @@
 import type { SessionReaderRegistry } from '../session/index.js';
-import type { AgentKind } from '../runner/index.js';
+import type { AgentKind } from '../agent-kinds.js';
+import type { AgentSessionUsage } from '../session-contract.js';
 export declare function errorMessage(error: unknown): string;
-export type FinalUsageSnapshot = {
-    contextLength?: number;
-    contextLimit?: number;
-    compactCount?: number;
-    compactPreContextLength?: number;
-    cacheReadTokens?: number;
-    cacheCreationTokens?: number;
-    totalTokens?: number;
-    inputTokens?: number;
-    outputTokens?: number;
-    cumulativeTotalTokens?: number;
-    cumulativeInputTokens?: number;
-    cumulativeOutputTokens?: number;
-    cumulativeCacheReadTokens?: number;
-    cumulativeCacheCreationTokens?: number;
-};
+/**
+ * jsonl 侧的最终用量快照。就是 `AgentSessionUsage` 的可选形态：reader 保证
+ * input/output/contextLength 有值，这里允许「读不到」，字段清单不再手抄第二份
+ * （§9.21 的口径一致要求靠这个单源维持）。
+ */
+export type FinalUsageSnapshot = Partial<AgentSessionUsage>;
 /**
  * Read final usage (contextLength + compactCount + cache tokens) from the
  * session jsonl. Called after a run finishes.

package/dist/bridge/final-usage.js

@@ -28,24 +28,7 @@ export function resolveFinalUsage(registry, defaultAgent, sessionId, cwd, agentK
             // fallback to per-run live usage is visible in logs, not silent.
             getLogger().warn(`[lark-remote] resolveFinalUsage: no usage from jsonl sessionId=${sessionId} cwd=${cwd} agent=${agentKind}, card falls back to per-run live usage`);
         }
-        return content.usage
-            ? {
-                contextLength: content.usage.contextLength,
-                contextLimit: content.usage.contextLimit,
-                compactCount: content.usage.compactCount,
-                compactPreContextLength: content.usage.compactPreContextLength,
-                cacheReadTokens: content.usage.cacheReadTokens,
-                cacheCreationTokens: content.usage.cacheCreationTokens,
-                totalTokens: content.usage.totalTokens,
-                inputTokens: content.usage.inputTokens,
-                outputTokens: content.usage.outputTokens,
-                cumulativeTotalTokens: content.usage.cumulativeTotalTokens,
-                cumulativeInputTokens: content.usage.cumulativeInputTokens,
-                cumulativeOutputTokens: content.usage.cumulativeOutputTokens,
-                cumulativeCacheReadTokens: content.usage.cumulativeCacheReadTokens,
-                cumulativeCacheCreationTokens: content.usage.cumulativeCacheCreationTokens,
-            }
-            : undefined;
+        return content.usage ? { ...content.usage } : undefined;
     }
     catch (err) {
         getLogger().warn(`[lark-remote] resolveFinalUsage failed sessionId=${sessionId}: ${errorMessage(err)}`);

package/dist/bridge/index.d.ts

@@ -4,7 +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, type StopOutcome } from '../runner/types.js';
+import type { AgentKind } from '../agent-kinds.js';
+import { type StopOutcome } 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';
@@ -14,7 +15,7 @@ import type { MediaOutcome } from '../inbound/turn.js';
  * through it. Declared here so tests can satisfy it structurally without
  * `as unknown as` casts.
  */
-interface BridgeChannel extends RunCardChannel {
+export interface BridgeChannel extends RunCardChannel {
     sendWithRetry(chatId: string, input: {
         text: string;
     } | {
@@ -149,6 +150,8 @@ export declare class Bridge {
     private activeRuns;
     /** Approval coordinators keyed by runId. */
     private approvalCoordinators;
+    /** 审批卡动作的实现（只读上面那张表；见 approval-actions.ts）。 */
+    private approvalActions;
     /**
      * 最近若干次已完成的、runner 有 runCompact 的 run（cwd → runId → 记录）。
      * run 结束后 activeRuns 已清空，而终态卡上的 Compact 按钮只带 runId，
@@ -378,7 +381,7 @@ export declare class Bridge {
     /**
      * Update an existing card in place (原地更新) instead of sending a new one.
      *
-     * Used by /config cardAction handlers (config.toggle/set/input/save) so the
+     * Used by /config cardAction handlers (config.set/input/save) so the
      * user sees the card refresh on the same message bubble rather than getting
      * a new card per click — same-message-bubble update pattern.
      *
@@ -468,6 +471,38 @@ export declare class Bridge {
      * 队列继续推进（否则一个挂死的 run 永久堵住后续消息）。
      */
     private startIdleWatchdog;
+    /**
+     * result 事件的 pre-init 守卫（§9.22）。
+     *
+     * Claude CLI `--resume` 会在 system.init 之前先吐一条**上一轮**的陈旧 result。
+     * 认了它就会过早置 sawResult / 抓错 usage / 让 run-state reducer 提前进入
+     * finalizing（reducer 用 sessionId===undefined 守卫，同一条红线）。本轮真正的
+     * result 在 system.init 之后才到。
+     *
+     * 例外：app-server runner（usageAuthority==='live'）的 init 是 runner 自己补发
+     * 的 synthetic init（2026-08-13 修复）。此分支保留为防御性兜底：live runner 若
+     * 在无 init 时发出 result（旧构建等），session 写回照常执行，但 sawResult 不置
+     * 真——卡片不会把半初始化的 run 当作已收尾。
+     *
+     * @param dropFromCard 该 result 是陈旧重放，不得进卡片（调用方 continue 跳过 push）
+     */
+    private observeResultEvent;
+    /**
+     * 审批三事件的派发（requested / resolved / view_updated）。
+     *
+     * coordinator 一 run 一个，首次 requested 时惰性建好并登记，`finally` 里统一
+     * onTurnEnded + 摘除。
+     */
+    private dispatchApprovalEvent;
+    /**
+     * 进程退出（for-await 自然结束）后的终态矩阵——它是本轮的唯一终态触发源。
+     *
+     * 1) finalizing（result 已收到）→ 三态映射 + usage meta
+     * 2) running（未收到 result）→ 错误路径；pre-init 终态优先当唯一线索
+     * 3) 已终态 + sawResult → 首终态不动，仅补 usage meta
+     * 4) 已终态且未收到 result（如 spawn 失败后 interrupted）→ 无 usage 可补，跳过
+     */
+    private finishRunAfterStream;
     /**
      * Step 2 of forwardToClaude: Run the agent and consume its event stream.
      * Handles idle watchdog, event processing, session sync, and state transitions.
@@ -494,45 +529,28 @@ export declare class Bridge {
      * find and return to this session without scrolling up.
      */
     private sendCompletionNotificationCard;
-    /**
-     * Resolve the ApprovalCoordinator for a run, or throw the standard
-     * "已结束" error. Shared preamble of all approval card-action handlers.
-     */
-    private withCoordinator;
-    /**
-     * Handle an approval response from a card button click.
-     * Routes to the ApprovalCoordinator for the given run.
-     */
+    /** 审批响应（卡片按钮）→ ApprovalCoordinator.submit。 */
     handleApprovalRespond(opts: {
         runId: string;
         requestId: number | string;
         decision: string;
         nonce: string;
     }): Promise<void>;
-    /**
-     * 计划审批修改意见（ExitPlanMode 输入框）：记录到 coordinator 并回流卡片。
-     * 「拒绝并附意见」/「批准并采纳修改」按钮复用该文本。
-     */
+    /** 计划审批修改意见（ExitPlanMode 输入框）→ coordinator.planFeedback。 */
     handleApprovalPlanFeedback(opts: {
         runId: string;
         requestId: number | string;
         text: string;
         nonce: string;
     }): Promise<void>;
-    /**
-     * Handle a permission toggle from a card button click.
-     * Routes to the ApprovalCoordinator for the given run.
-     */
+    /** 权限条目勾选（卡片按钮）→ coordinator.togglePerm。 */
     handleApprovalToggle(opts: {
         runId: string;
         requestId: number | string;
         permId: string;
         selected?: boolean;
     }): Promise<void>;
-    /**
-     * Claude AskUserQuestion 选项点击（单选即时提交 / 多选切换勾选）。
-     * 路由到 ApprovalCoordinator.toggleAnswer。
-     */
+    /** AskUserQuestion 选项点击 → coordinator.toggleAnswer。 */
     handleApprovalAnswer(opts: {
         runId: string;
         requestId: number | string;
@@ -540,20 +558,14 @@ export declare class Bridge {
         option: string;
         nonce: string;
     }): Promise<void>;
-    /**
-     * Claude AskUserQuestion 多选问题的「提交答案」按钮。
-     * 路由到 ApprovalCoordinator.submitAnswers。
-     */
+    /** AskUserQuestion 多选「提交答案」→ coordinator.submitAnswers。 */
     handleApprovalAnswerSubmit(opts: {
         runId: string;
         requestId: number | string;
         questionIndex: number;
         nonce: string;
     }): Promise<void>;
-    /**
-     * Claude AskUserQuestion 自定义答案（Other）：自由文本直接
-     * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
-     */
+    /** AskUserQuestion 自定义答案（Other）→ coordinator.answerCustom。 */
     handleApprovalAnswerCustom(opts: {
         runId: string;
         requestId: number | string;
@@ -561,11 +573,7 @@ export declare class Bridge {
         text: string;
         nonce: string;
     }): Promise<void>;
-    /**
-     * Codex AskUserQuestion 补充说明（user_note，2026-08-18 live 验证模型理解
-     * "user_note: <text>" 条目）：记录到 coordinator，随答案一起提交。
-     * 路由到 ApprovalCoordinator.answerNote。
-     */
+    /** AskUserQuestion 补充说明（user_note）→ coordinator.answerNote。 */
     handleApprovalAnswerNote(opts: {
         runId: string;
         requestId: number | string;
@@ -573,7 +581,6 @@ export declare class Bridge {
         text: string;
         nonce: string;
     }): Promise<void>;
-    private dispatchQuestionAction;
     /**
      * 记下一次「可压缩 run」：终态卡上的 Compact 按钮点击时据此反查
      * sessionId + agentKind。runId 是按钮自带的唯一键，同 cwd 内唯一。
@@ -616,7 +623,7 @@ export declare class Bridge {
         runId?: string;
     }, ctx: CommandContext): Promise<void>;
     /**
-     * §5.3: kimi 压缩在途检测——reader 鸭子实现 `readCompactionState` 时，若
+     * §5.3: kimi 压缩在途检测——reader 实现契约的 `readCompactionState` 时，若
      * wire 状态机判定当前有未终结的压缩（最后一次 begin 无 terminal 记录），
      * 直接回文本「已有一次 Compact 正在进行」并返回 true（调用方不开卡、不发
      * session/prompt）。codex/claude 等 reader 无此方法 → 返回 false，行为不变。