lark-remote 0.4.4 → 0.5.0

package/dist/router/order-exec-dispatch.d.ts

@@ -1,11 +1,5 @@
 import type { CommandRouter } from './index.js';
-import type { Bridge } from '../bridge/index.js';
-/** Context shared by all card-action dispatch paths (file-local; callers pass it structurally). */
-interface DispatchContext {
-    userId: string;
-    chatId: string;
-    messageId: string;
-}
+import type { Bridge, CommandContext } from '../bridge/index.js';
 /**
  * Dispatch an `order.exec` card action as an equivalent queued user message
  * (Plan A): resolve the order text at the enqueue boundary, then enqueue it
@@ -23,8 +17,7 @@ interface DispatchContext {
 export declare function dispatchOrderExecForQueue(args: {
     router: CommandRouter;
     bridge: Bridge;
-    workspace: string;
+    cwd: string;
     orderId: string | undefined;
-    ctx: DispatchContext;
+    ctx: CommandContext;
 }): Promise<'enqueued' | 'missing-id' | 'not-found'>;
-export {};

package/dist/router/order-exec-dispatch.js

@@ -13,7 +13,7 @@
  * for the caller to log; performs its own error feedback via `bridge.sendResult`.
  */
 export async function dispatchOrderExecForQueue(args) {
-    const { router, bridge, workspace, orderId, ctx } = args;
+    const { router, bridge, cwd, orderId, ctx } = args;
     if (!orderId) {
         await bridge.sendResult({ text: '卡片 payload 缺少必要信息' }, ctx);
         return 'missing-id';
@@ -23,12 +23,12 @@ export async function dispatchOrderExecForQueue(args) {
         await bridge.sendResult({ text: '指令不存在或已被删除' }, ctx);
         return 'not-found';
     }
-    // Step4/D4: 入队时刻（T0）快照 agent+session，随任务闭包带到 T1 执行时刻，
+    // Step4/入队时刻快照 agent+session，随任务闭包带到执行时刻，
     // 避免排队期间 /new、/config 改写 live 状态导致语义漂移。唯一捕获点
     // Bridge.currentBinding。
     const binding = bridge.currentBinding(ctx.userId);
-    bridge.enqueue(workspace, async () => {
-        await router.handle(resolved.orderText, ctx, { cwdOverride: workspace, binding });
+    bridge.enqueue(cwd, async () => {
+        await router.handle(resolved.orderText, ctx, { cwdOverride: cwd, binding });
     }, {
         taskMeta: {
             userId: ctx.userId,
@@ -38,7 +38,7 @@ export async function dispatchOrderExecForQueue(args) {
             // The internal key is NOT a valid Feishu message id, so the queue
             // status card must reply to the real Feishu card message id instead.
             feishuReplyTo: ctx.messageId,
-            // D3/Step4：binding 随 taskMeta 存进 QueuedTask，供替换闭包
+            ///Step4：binding 随 taskMeta 存进 QueuedTask，供替换闭包
             // （queue.edit/queue.immediate）复用，不重新快照。
             binding,
         },

package/dist/router/{utils.d.ts → usage-format.d.ts}

@@ -1,6 +1,6 @@
 /**
- * Pure utility functions extracted from router/index.ts.
- * Path-safety helpers, display formatting, and validation — no Router state.
+ * Format session/run usage stats (context, compact count, tokens, cost) into
+ * the display strings shown on cards. Pure — no Router state.
  */
 import type { ActiveRunSnapshot } from '../bridge/index.js';
 export interface SessionDisplayUsage {
@@ -12,8 +12,6 @@ export interface SessionDisplayUsage {
     cacheCreationTokens?: number;
 }
 export declare function activeRunUsage(activeRun: ActiveRunSnapshot | undefined): SessionDisplayUsage | undefined;
-/** Clamp `v` into [min, max]. */
-export declare function clampInt(v: number, min: number, max: number): number;
 /**
  * Format usage stats (context length, compact count, cache tokens) into a display string.
  * Each stat on its own line with blank lines between sections.

package/dist/router/{utils.js → usage-format.js}

@@ -1,6 +1,6 @@
 /**
- * Pure utility functions extracted from router/index.ts.
- * Path-safety helpers, display formatting, and validation — no Router state.
+ * Format session/run usage stats (context, compact count, tokens, cost) into
+ * the display strings shown on cards. Pure — no Router state.
  */
 export function activeRunUsage(activeRun) {
     if (!activeRun || activeRun.contextLength === undefined)
@@ -12,11 +12,6 @@ export function activeRunUsage(activeRun) {
         cacheCreationTokens: activeRun.cacheCreationTokens,
     };
 }
-// --- Extracted helpers for refactoring ---
-/** Clamp `v` into [min, max]. */
-export function clampInt(v, min, max) {
-    return Math.min(Math.max(v, min), max);
-}
 /**
  * Format number to human-readable unit string.
  * - >= 1M: one decimal, M suffix (e.g., 1200000 → 1.2M, 25000000 → 25M)
@@ -154,4 +149,4 @@ export function formatUsageStats(usage, options) {
     }
     return lines.join('\n');
 }
-//# sourceMappingURL=utils.js.map
+//# sourceMappingURL=usage-format.js.map

package/dist/runner/bash/runner.d.ts

@@ -28,7 +28,7 @@ export interface BashRunner {
 export declare class BashProcessRunner implements BashRunner {
     private currentProcess;
     /**
-     * 背压高水位/低水位（P1-4 层④，参照 jsonl-stream.ts 的 pauseThreshold/
+     * 背压高水位/低水位（层④，参照 jsonl-stream.ts 的 pauseThreshold/
      * resumeThreshold）。stdout/stderr 队列超过高水位时 pause 流（内存有界），
      * 消费者 drain 到低水位后 resume。构造可注入以便测试用小水位。
      */
@@ -50,7 +50,7 @@ export declare class BashProcessRunner implements BashRunner {
         cwd: string;
     }): AsyncGenerator<BashOutputEvent>;
     /**
-     * P1-22: called by the process-level exit dispatcher on SIGINT/SIGTERM/exit.
+     * called by the process-level exit dispatcher on SIGINT/SIGTERM/exit.
      * Kills the whole process group (leader + background children) via
      * Terminator, matching agent-runner cleanupOnExit semantics.
      */

package/dist/runner/bash/runner.js

@@ -17,7 +17,7 @@ import { registerExitCleanup, unregisterExitCleanup } from '../common/spawning-r
 export class BashProcessRunner {
     currentProcess = null;
     /**
-     * 背压高水位/低水位（P1-4 层④，参照 jsonl-stream.ts 的 pauseThreshold/
+     * 背压高水位/低水位（层④，参照 jsonl-stream.ts 的 pauseThreshold/
      * resumeThreshold）。stdout/stderr 队列超过高水位时 pause 流（内存有界），
      * 消费者 drain 到低水位后 resume。构造可注入以便测试用小水位。
      */
@@ -32,7 +32,7 @@ export class BashProcessRunner {
         if (this.queueLowWater > this.queueHighWater) {
             this.queueLowWater = this.queueHighWater;
         }
-        // `!` bash 无协议停止通道（§3.3）：posix 走组杀（与原 ProcessStopper 同实现），
+        // `!` bash 无协议停止通道：posix 走组杀（与原 ProcessStopper 同实现），
         // win32 优雅段显式跳过后树杀。
         this.terminator = opts?.terminator ?? createTerminator({ graceMs: stopGraceMs, agent: 'bash' });
         this.shell = opts?.shell ?? createShellBackend();
@@ -61,7 +61,7 @@ export class BashProcessRunner {
             });
         }
         catch (err) {
-            // win32 Git Bash 缺失（§7.2）：同步抛出，转成明确错误输出而非悬死。
+            // win32 Git Bash 缺失：同步抛出，转成明确错误输出而非悬死。
             if (err instanceof ShellUnavailableError) {
                 getLogger().warn(`[bash-runner] shell unavailable: ${err.message}`);
                 yield { type: 'stderr', content: `${err.message}\n` };
@@ -76,7 +76,7 @@ export class BashProcessRunner {
         const stdout = proc.stdout;
         const stderr = proc.stderr;
         getLogger().info(`[bash-runner] spawn pid=${proc.pid} command="${command.slice(0, 50)}..." cwd=${opts.cwd}`);
-        // P1-22: register with the process-level exit dispatcher while the process
+        // register with the process-level exit dispatcher while the process
         // is alive — bridge exit/restart (SIGINT/SIGTERM/exit) then kills the whole
         // group via cleanupOnExit instead of orphaning `!` processes.
         registerExitCleanup(this);
@@ -85,7 +85,7 @@ export class BashProcessRunner {
         // for logging, one for queueing) -- both fired on the same chunk.
         const stdoutQueue = [];
         const stderrQueue = [];
-        // 背压状态（P1-4 层④）：队列超高水位 → pause 对应流；drain 到低水位 → resume。
+        // 背压状态（层④）：队列超高水位 → pause 对应流；drain 到低水位 → resume。
         let stdoutPaused = false;
         let stderrPaused = false;
         const maybePauseStdout = () => {
@@ -209,7 +209,7 @@ export class BashProcessRunner {
         }
     }
     /**
-     * P1-22: called by the process-level exit dispatcher on SIGINT/SIGTERM/exit.
+     * called by the process-level exit dispatcher on SIGINT/SIGTERM/exit.
      * Kills the whole process group (leader + background children) via
      * Terminator, matching agent-runner cleanupOnExit semantics.
      */

package/dist/runner/claude/runner.d.ts

@@ -22,7 +22,7 @@ export declare class ClaudeRunner implements AgentRunner {
         settings?: string;
         stopGraceMs?: number;
         pidDir?: string;
-        workspace: string;
+        cwd: string;
         spawnHeartbeatMs?: number;
         sessionReader?: AgentSessionReader;
         /** Claude 权限模式（官方 --permission-mode 枚举；'default'=省略参数）。 */

package/dist/runner/claude/runner.js

@@ -44,12 +44,11 @@ export class ClaudeRunner {
         this.sessionReader = opts.sessionReader ?? new ClaudeSessionReader();
         this.session = new ClaudeSession({
             pidDir: opts.pidDir,
-            workspace: opts.workspace,
+            cwd: opts.cwd,
             stopGraceMs: opts.stopGraceMs,
             spawnHeartbeatMs: opts.spawnHeartbeatMs,
             permissionMode: this.permissionMode,
             settings: opts.settings,
-            model: this.defaultModel,
             effort: this.defaultEffort,
             idleTtlMs: opts.idleTtlMs,
         });
@@ -128,7 +127,7 @@ export class ClaudeRunner {
                 await this.session.respondPermission(requestId, { behavior: 'deny' });
                 return;
             case 'cancel': {
-                // 审批超时/取消：deny 送达后中断 turn（对齐方案验收「审批超时未响应，
+                // 审批超时/取消：deny 送达后中断 turn（对齐「审批超时未响应，
                 // 已自动取消」终态；仅 deny 会让 claude 继续回合导致卡片 done）。
                 await this.session.respondPermission(requestId, {
                     behavior: 'deny',

package/dist/runner/claude/session.d.ts

@@ -22,7 +22,7 @@
  * - result 事件 subtype 为 compact/compaction 是 turn 中途压缩，不是 turn 结束；
  *   其余 subtype（success/error/...）才是 turn 终态。
  *
- * 生命周期：一个 workspace 一个长驻进程（lifetime='workspace'）。每次
+ * 生命周期：一个 cwd 一个长驻进程（lifetime='workspace'）。每次
  * run(message) = 写一条 user 消息 + 消费 stdout 事件直到本 turn 的 result；
  * 进程在 turn 之间保持存活（stdin 不关闭），/stop / /new / /cd / 看门狗超时
  * 时经 Terminator 组杀，下条消息按 SessionStore 的 sessionId --resume。
@@ -31,13 +31,12 @@ import { SpawningRunner } from '../common/spawning-runner.js';
 import type { AgentEvent, SpawnOptions } from '../types.js';
 export interface ClaudeSessionOptions {
     pidDir?: string;
-    workspace: string;
+    cwd: string;
     stopGraceMs?: number;
     spawnHeartbeatMs?: number;
     /** Claude 权限模式（官方 --permission-mode 枚举；'default' 省略该参数）。 */
     permissionMode?: string;
     settings?: string;
-    model?: string;
     effort?: string;
     /** 会话级空闲回收 TTL（ms）：turn 之间无活动超过该窗口则停止进程。0=禁用。 */
     idleTtlMs?: number;
@@ -54,14 +53,13 @@ export interface PermissionResult {
 }
 /**
  * ClaudeSession extends SpawningRunner 复用其 spawn/pid 文件/killOrphan/
- * Terminator/SpawnHeartbeat/退出分发器机制（P1-1/P1-10/P1-11 契约保持），
+ * Terminator/SpawnHeartbeat/退出分发器机制（契约保持），
  * 但 run() 覆盖为「长驻 + 按 turn 消费」：进程跨 turn 存活，turn 结束以
  * stream-json result 事件（非 compact）为界，而不是进程退出。
  */
 export declare class ClaudeSession extends SpawningRunner {
     private readonly permissionMode;
     private readonly settings?;
-    private readonly defaultModel?;
     private readonly defaultEffort?;
     private readonly idleTtlMs;
     /** 当前 turn 是否在途（防止并发 run 写乱 stdin）。 */
@@ -140,7 +138,7 @@ export declare class ClaudeSession extends SpawningRunner {
     private startStreamReader;
     /**
      * 消费事件队列直到本 turn 的 result 事件（非 compact/compaction）。
-     * 消费者提前关闭生成器（bridge 循环体抛错）→ 杀进程防孤儿（P1-11 语义）。
+     * 消费者提前关闭生成器（bridge 循环体抛错）→ 杀进程防孤儿（语义）。
      *
      * result = turn 终态（2026-08-16 真实 claude 实测：长驻模式下 result 之后
      * 不再有 stdout 事件，后台任务完成是静默的；旧 -p 流程「等进程退出再收尾」

package/dist/runner/claude/session.js

@@ -22,16 +22,16 @@
  * - result 事件 subtype 为 compact/compaction 是 turn 中途压缩，不是 turn 结束；
  *   其余 subtype（success/error/...）才是 turn 终态。
  *
- * 生命周期：一个 workspace 一个长驻进程（lifetime='workspace'）。每次
+ * 生命周期：一个 cwd 一个长驻进程（lifetime='workspace'）。每次
  * run(message) = 写一条 user 消息 + 消费 stdout 事件直到本 turn 的 result；
  * 进程在 turn 之间保持存活（stdin 不关闭），/stop / /new / /cd / 看门狗超时
  * 时经 Terminator 组杀，下条消息按 SessionStore 的 sessionId --resume。
  */
 import { readFile } from 'node:fs/promises';
-import { silentlyUnlink } from '../../common/fs.js';
+import { bestEffortUnlink } from '../../common/fs.js';
 import { getLogger } from '../../logger/index.js';
 import { SpawningRunner } from '../common/spawning-runner.js';
-import { authErrorEvent, syntheticInitEvent } from '../common/runner-utils.js';
+import { setupErrorEvent, syntheticInitEvent } from '../common/synthetic-events.js';
 import { makeQuestionApprovalEvent } from '../question-common.js';
 /** 拒绝权限时的默认提示（进入 claude 上下文，中文用户可读）。 */
 const DENY_MESSAGE = '用户拒绝了此工具调用，请停止并等待用户指令。';
@@ -43,14 +43,13 @@ const DEFAULT_IDLE_TTL_MS = 30 * 60 * 1000;
 const COMPACTION_RESULT_SUBTYPES = new Set(['compact', 'compaction']);
 /**
  * ClaudeSession extends SpawningRunner 复用其 spawn/pid 文件/killOrphan/
- * Terminator/SpawnHeartbeat/退出分发器机制（P1-1/P1-10/P1-11 契约保持），
+ * Terminator/SpawnHeartbeat/退出分发器机制（契约保持），
  * 但 run() 覆盖为「长驻 + 按 turn 消费」：进程跨 turn 存活，turn 结束以
  * stream-json result 事件（非 compact）为界，而不是进程退出。
  */
 export class ClaudeSession extends SpawningRunner {
     permissionMode;
     settings;
-    defaultModel;
     defaultEffort;
     idleTtlMs;
     /** 当前 turn 是否在途（防止并发 run 写乱 stdin）。 */
@@ -92,7 +91,7 @@ export class ClaudeSession extends SpawningRunner {
     constructor(opts) {
         super({
             pidDir: opts.pidDir,
-            workspace: opts.workspace,
+            cwd: opts.cwd,
             stopGraceMs: opts.stopGraceMs,
             spawnHeartbeatMs: opts.spawnHeartbeatMs,
             pidFilePrefix: 'claude',
@@ -103,7 +102,6 @@ export class ClaudeSession extends SpawningRunner {
         this.binary = 'claude';
         this.permissionMode = opts.permissionMode ?? 'bypassPermissions';
         this.settings = opts.settings;
-        this.defaultModel = opts.model;
         this.defaultEffort = opts.effort;
         this.idleTtlMs = opts.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
     }
@@ -129,7 +127,7 @@ export class ClaudeSession extends SpawningRunner {
             // 或 --resume 目标会话）。比较进程当前 session（init 报告值）而非 spawn
             // 请求值：bridge 会把 init 的 session_id 写回 SessionStore，第二条消息
             // 带着它来；若拿 spawn 请求值（''）比较，每条消息都会误判切换、杀进程
-            // 重启，长驻设计失效（2026-08-16 review P0）。
+            // 重启，长驻设计失效（2026-08-16）。
             if (this.isRunning && this.sessionId !== (opts.sessionId ?? '')) {
                 getLogger().info(`[${this.logTag}] session mismatch: process=${this.sessionId || '(fresh)'} ` +
                     `requested=${opts.sessionId ?? '(fresh)'}, recycling process`);
@@ -141,7 +139,7 @@ export class ClaudeSession extends SpawningRunner {
                 // §9.22 守卫：错误 result 前必须补 synthetic init，否则 bridge 的
                 // pre-init result guard 与 run-state reducer 会静默丢弃错误信息。
                 yield syntheticInitEvent(opts.sessionId);
-                yield authErrorEvent(spawnError);
+                yield setupErrorEvent(spawnError);
                 return;
             }
             // turn 之间的 idle 噪音（如 prompt_suggestion）不属于本 turn，先清空。
@@ -176,7 +174,7 @@ export class ClaudeSession extends SpawningRunner {
             getLogger().warn(`[${this.logTag}] respondPermission skipped: process not running requestId=${requestId}`);
             return;
         }
-        // review P2-2：requestId 不在待审批表（已 control_cancel / 进程回收）时
+        // requestId 不在待审批表（已 control_cancel / 进程回收）时
         // 丢弃响应，不能以空 updatedInput allow（claude 会拿空输入执行工具）。
         if (!this.pendingToolInputs.has(requestId)) {
             getLogger().warn(`[${this.logTag}] respondPermission dropped: unknown requestId=${requestId}`);
@@ -206,7 +204,7 @@ export class ClaudeSession extends SpawningRunner {
     async respondAskUserQuestion(requestId, answers) {
         if (!this.isRunning)
             return;
-        // review P2-2：未知 requestId 时不能回写缺原始 questions 的 answers
+        // 未知 requestId 时不能回写缺原始 questions 的 answers
         // （官方要求 updatedInput 必须包含原始 questions）。
         if (!this.pendingToolInputs.has(requestId)) {
             getLogger().warn(`[${this.logTag}] respondAskUserQuestion dropped: unknown requestId=${requestId}`);
@@ -287,7 +285,7 @@ export class ClaudeSession extends SpawningRunner {
      */
     async startProcess(opts) {
         if (this.isRunning) {
-            // review P3-4：复用进程（跨 turn 长驻）时清掉上一轮的空闲回收 timer——
+            // 复用进程（跨 turn 长驻）时清掉上一轮的空闲回收 timer——
             // 否则长 turn 中它会空转触发一次（回调因 turnActive 空转返回，无害但
             // 多余）；新一轮结束后的 armIdleTimer 会重新武装。
             this.clearIdleTimer();
@@ -372,7 +370,7 @@ export class ClaudeSession extends SpawningRunner {
                     // 进程自行结束（崩溃/上游退出）：注销协议停止通道，别把死 pid 的
                     // 条目留在注册表里等 pid 复用。
                     this.unregisterStopper();
-                    silentlyUnlink(this.pidFilePath);
+                    bestEffortUnlink(this.pidFilePath);
                     this.wakeWaiters();
                 }
             }
@@ -383,7 +381,7 @@ export class ClaudeSession extends SpawningRunner {
     // =========================================================================
     /**
      * 消费事件队列直到本 turn 的 result 事件（非 compact/compaction）。
-     * 消费者提前关闭生成器（bridge 循环体抛错）→ 杀进程防孤儿（P1-11 语义）。
+     * 消费者提前关闭生成器（bridge 循环体抛错）→ 杀进程防孤儿（语义）。
      *
      * result = turn 终态（2026-08-16 真实 claude 实测：长驻模式下 result 之后
      * 不再有 stdout 事件，后台任务完成是静默的；旧 -p 流程「等进程退出再收尾」
@@ -482,7 +480,7 @@ export class ClaudeSession extends SpawningRunner {
             this.idleTimer = null;
             if (this.turnActive || !this.isRunning)
                 return;
-            getLogger().info(`[${this.logTag}] idle timeout ${this.idleTtlMs}ms, stopping session workspace=${this.cwd}`);
+            getLogger().info(`[${this.logTag}] idle timeout ${this.idleTtlMs}ms, stopping session cwd=${this.cwd}`);
             void this.stop().catch((err) => {
                 getLogger().warn(`[${this.logTag}] idle stop failed: ${err.message}`);
             });
@@ -556,7 +554,7 @@ export class ClaudeSession extends SpawningRunner {
     async translateEvent(raw) {
         const event = raw;
         const type = event.type;
-        // review P3-3：--resume 会先重放上一轮历史事件（旧 result 之外还可能有
+        // --resume 会先重放上一轮历史事件（旧 result 之外还可能有
         // 旧 assistant/user 内容）。init 之前除 init 本身外一律丢弃，避免历史
         // 内容混进当前卡片（result 分支的 sawInit 守卫升级为全类型守卫）。
         if (type !== 'system' && !this.sawInit)
@@ -680,7 +678,7 @@ export class ClaudeSession extends SpawningRunner {
         const request = (raw.request ?? {});
         const subtype = request.subtype;
         if (subtype !== 'can_use_tool') {
-            // review P3-1：未知 subtype 不能静默丢弃——claude 在等 control_response，
+            // 未知 subtype 不能静默丢弃——claude 在等 control_response，
             // 不回应 turn 会永久挂起（无审批卡、无超时）。deny 兜底让 claude 继续。
             getLogger().warn(`[${this.logTag}] unknown control request subtype=${String(subtype)} requestId=${requestId}`);
             void this.writeControlResponse(requestId, {
@@ -694,7 +692,7 @@ export class ClaudeSession extends SpawningRunner {
         const toolName = String(request.tool_name ?? '');
         const input = (request.input ?? {});
         this.pendingToolInputs.set(requestId, input);
-        // review P1：允许所有只放行工具权限；AskUserQuestion 不能被空 answers
+        // 允许所有只放行工具权限；AskUserQuestion 不能被空 answers
         // 自动放行（claude 会把空答案当作已作答），必须继续上抛卡片让用户回答。
         if (this.autoApprove && toolName !== 'AskUserQuestion') {
             getLogger().info(`[${this.logTag}] auto-approving requestId=${requestId} tool=${toolName}`);
@@ -704,7 +702,7 @@ export class ClaudeSession extends SpawningRunner {
             }).catch((err) => {
                 getLogger().warn(`[${this.logTag}] auto-approve write failed requestId=${requestId}: ${err.message}`);
             });
-            // review P2-1：自动放行不经过协调器/respondPermission，条目不会随
+            // 自动放行不经过协调器/respondPermission，条目不会随
             // 响应被删除——立即释放，否则长会话（允许所有）下 Map 无界增长。
             this.pendingToolInputs.delete(requestId);
             return [];
@@ -719,7 +717,7 @@ export class ClaudeSession extends SpawningRunner {
                     behavior: 'deny',
                     message: '无法解析 AskUserQuestion 选项',
                 }).catch(() => { });
-                // review P2-1：解析失败 deny 后同样释放条目（不经过 respondPermission）。
+                // 解析失败 deny 后同样释放条目（不经过 respondPermission）。
                 this.pendingToolInputs.delete(requestId);
                 return [];
             }
@@ -762,7 +760,7 @@ export class ClaudeSession extends SpawningRunner {
             ];
         }
         // 非命令工具的兜底防御：input 无 command 字段时 JSON 序列化，但空对象
-        // 序列化成 `{}` 对用户无意义——内容为空时回退展示工具名（review P3-5）。
+        // 序列化成 `{}` 对用户无意义——内容为空时回退展示工具名。
         const rawCommand = typeof input.command === 'string' ? input.command : JSON.stringify(input);
         const command = rawCommand && rawCommand !== '{}' && rawCommand !== 'null'
             ? rawCommand
@@ -819,7 +817,7 @@ function parseUserQuestions(input) {
         const question = typeof q.question === 'string' ? q.question : '';
         if (!question)
             continue;
-        // review P3-2：answers 字典以问题文本为 key，重复文本会互相覆盖——
+        // answers 字典以问题文本为 key，重复文本会互相覆盖——
         // 视为解析失败（调用方 deny 兜底），不把坏问题上抛给用户。
         if (seenQuestions.has(question))
             return [];
@@ -841,7 +839,7 @@ function parseUserQuestions(input) {
                 });
             }
         }
-        // review P3-2：零选项问题无法作答（多选连自定义答案都没有），视为
+        // 零选项问题无法作答（多选连自定义答案都没有），视为
         // 解析失败（调用方 deny 兜底），不把坏问题上抛给用户。
         if (options.length === 0)
             return [];

package/dist/runner/codex/app-server/runner.js

@@ -136,7 +136,7 @@ export class CodexAppServerRunner extends ConnectionBasedRunner {
             },
         };
         this.connectionManager = new ConnectionManager(managerOpts);
-        // 协议停止通道（design §3.3）：codex 的 cancel 是 `turn/interrupt` 请求，已由
+        // 协议停止通道：codex 的 cancel 是 `turn/interrupt` 请求，已由
         // cancelCurrentTurn 实现；登记后 win32 优雅停止才有通道可用（否则一路树杀）。
         this.connectionManager.stopper = ({ client }) => this.buildCooperativeStop(client);
     }
@@ -235,7 +235,7 @@ export class CodexAppServerRunner extends ConnectionBasedRunner {
         else if (pending.kind === 'permissions') {
             // 权限审批的响应没有 decision 字段（真实协议只回 granted profile +
             // scope）：decline/cancel 必须返回空授权（拒绝全部），否则会把用户已
-            // 勾选的条目当作授予返回（2026-08-12 review 发现：勾选后点「拒绝」实
+            // 勾选的条目当作授予返回（2026-08-12 ：勾选后点「拒绝」实
             // 际授予了所选权限）。accept/acceptForSession 才带用户勾选的条目。
             const denied = action === 'decline' || action === 'cancel';
             client.respond(requestId, {
@@ -358,7 +358,7 @@ export class CodexAppServerRunner extends ConnectionBasedRunner {
         }
         else {
             const threadResult = await client.request('thread/start', threadParams);
-            // 会话键假设（review P2-4）：主线程 thread.id === session_meta.session_id，
+            // 会话键假设：主线程 thread.id === session_meta.session_id，
             // 故 thread.id 可同时用作协议 threadId 与 store/session reader 的 session
             // 键（bridge 用 turn_started 通知的 threadId 写回，/resume、Compact 按此
             // 键定位 JSONL）。forked/subagent 线程二者会分叉（openai/codex#29327），

package/dist/runner/codex/app-server/translator.d.ts

@@ -26,7 +26,7 @@ export declare class CodexAppServerTranslator {
     /** Full command output per item id (item-scoped snapshot). */
     private toolOutputByItem;
     /**
-     * Tool identity per item id (信息保真 C2): recorded at item/started, spread
+     * Tool identity per item id (信息保真): recorded at item/started, spread
      * into every toolOutput turn_diff, released at item/completed.
      */
     private toolItemMeta;
@@ -85,7 +85,7 @@ export declare class CodexAppServerTranslator {
     private handlePlanUpdated;
     private handleTokenUsageUpdated;
     /**
-     * warning 通知 → notice 事件（信息保真 C2：运行期告警不再静默丢弃）。
+     * warning 通知 → notice 事件（信息保真 运行期告警不再静默丢弃）。
      */
     private handleWarning;
     /**

package/dist/runner/codex/app-server/translator.js

@@ -27,7 +27,7 @@ export class CodexAppServerTranslator {
     /** Full command output per item id (item-scoped snapshot). */
     toolOutputByItem = new Map();
     /**
-     * Tool identity per item id (信息保真 C2): recorded at item/started, spread
+     * Tool identity per item id (信息保真): recorded at item/started, spread
      * into every toolOutput turn_diff, released at item/completed.
      */
     toolItemMeta = new Map();
@@ -326,7 +326,7 @@ export class CodexAppServerTranslator {
                 return [];
             }
             this.toolOutputByItem.set(item.id, authoritative);
-            // 信息保真 C2：完成事件同样携带身份，并在发出后释放 meta。
+            // 信息保真 完成事件同样携带身份，并在发出后释放 meta。
             const meta = this.toolItemMeta.get(item.id);
             this.toolItemMeta.delete(item.id);
             return [
@@ -383,7 +383,7 @@ export class CodexAppServerTranslator {
                 ];
             }
         }
-        // 信息保真 C2：webSearch/mcpToolCall/dynamicToolCall 等无专属 completed 分支的
+        // 信息保真 webSearch/mcpToolCall/dynamicToolCall 等无专属 completed 分支的
         // 工具 item 也必须收尾——否则 run-state 侧工具块永挂 running（无 completedAt/终态），
         // toolItemMeta 泄漏到下个 turn 的 clear() 才被释放。
         if (this.startedToolItems.has(item.id)) {
@@ -466,7 +466,7 @@ export class CodexAppServerTranslator {
         return [];
     }
     /**
-     * warning 通知 → notice 事件（信息保真 C2：运行期告警不再静默丢弃）。
+     * warning 通知 → notice 事件（信息保真 运行期告警不再静默丢弃）。
      */
     handleWarning(params) {
         return [
@@ -653,7 +653,7 @@ export class CodexAppServerTranslator {
             // item/started 锚定工具块位置（真实时序）：命令开始时即创建工具块，
             // 而不是等到首个输出 delta——否则后续 reasoning item 会插到 command 之前。
             this.startedToolItems.add(item.id);
-            // 信息保真 C2：记录工具身份，随 turn_diff 透传（run-state 首见时写入）。
+            // 信息保真 记录工具身份，随 turn_diff 透传（run-state 首见时写入）。
             this.toolItemMeta.set(item.id, {
                 toolName: 'Bash',
                 toolInput: { command: item.command, ...(item.cwd ? { cwd: item.cwd } : {}) },

package/dist/runner/common/acp/{protocol-helpers.d.ts → acp-approval.d.ts}

@@ -1,18 +1,12 @@
 /**
- * Shared helper functions for the ACP protocol layer.
+ * ACP approval/permission mapping and lifecycle shared by the kimi and
+ * opencode ACP runners.
  *
- * Extracted from runner.ts and translator.ts to avoid duplication (G5).
+ * Extracted from runner.ts and translator.ts to avoid duplication.
  * Shape source: approval.ts:28-29 — optionId is opaque, echo back as-is.
  */
 import type { ApprovalView } from '../../types.js';
 import type { PermissionOption } from './protocol-types.js';
-/**
- * Find an option by matching its `kind` against a list of candidate values,
- * and return the `optionId` to echo back in the approval response.
- * ACP option kind values vary between kimi versions; this handles both
- * the documented names and the observed real names (§2.3).
- */
-export declare function findOptionIdByKind(options: PermissionOption[], candidateKinds: string[]): string | undefined;
 /** 各 ACP 服务端的 option kind 候选表（kimi/opencode 观测名不同，语义对齐）。 */
 export interface AcpApprovalKinds {
     accept: string[];
@@ -39,7 +33,7 @@ export declare function buildAcpPermissionOutcome(action: string, options: Permi
 /**
  * 从服务端 options kind 派生审批决定列表：accept/decline/cancel 恒有；
  * 带 always 类 option（kimi approve_always / opencode allow_always）才提供
- * acceptForSession（§P4「本会话总是允许」）。kimi/opencode 两侧共用。
+ * acceptForSession（「本会话总是允许」）。kimi/opencode 两侧共用。
  */
 export declare function deriveAcpAvailableDecisions(options: PermissionOption[]): string[];
 /** 截断长文本并追加省略号（translator 审批 reason 用，原先两份相同拷贝）。 */

package/dist/runner/common/acp/{protocol-helpers.js → acp-approval.js}

@@ -1,7 +1,8 @@
 /**
- * Shared helper functions for the ACP protocol layer.
+ * ACP approval/permission mapping and lifecycle shared by the kimi and
+ * opencode ACP runners.
  *
- * Extracted from runner.ts and translator.ts to avoid duplication (G5).
+ * Extracted from runner.ts and translator.ts to avoid duplication.
  * Shape source: approval.ts:28-29 — optionId is opaque, echo back as-is.
  */
 import { getLogger } from '../../../logger/index.js';
@@ -9,9 +10,9 @@ import { getLogger } from '../../../logger/index.js';
  * Find an option by matching its `kind` against a list of candidate values,
  * and return the `optionId` to echo back in the approval response.
  * ACP option kind values vary between kimi versions; this handles both
- * the documented names and the observed real names (§2.3).
+ * the documented names and the observed real names.
  */
-export function findOptionIdByKind(options, candidateKinds) {
+function findOptionIdByKind(options, candidateKinds) {
     for (const kind of candidateKinds) {
         const found = options.find((opt) => opt.kind === kind);
         if (found)
@@ -53,7 +54,7 @@ export function buildAcpPermissionOutcome(action, options, kinds) {
 /**
  * 从服务端 options kind 派生审批决定列表：accept/decline/cancel 恒有；
  * 带 always 类 option（kimi approve_always / opencode allow_always）才提供
- * acceptForSession（§P4「本会话总是允许」）。kimi/opencode 两侧共用。
+ * acceptForSession（「本会话总是允许」）。kimi/opencode 两侧共用。
  */
 export function deriveAcpAvailableDecisions(options) {
     const decisions = ['accept', 'decline', 'cancel'];
@@ -100,4 +101,4 @@ export async function sendAcpSetMode(opts) {
         getLogger().warn(`[${opts.logTag}] session/set_mode failed (non-fatal): ${err.message}`);
     }
 }
-//# sourceMappingURL=protocol-helpers.js.map
+//# sourceMappingURL=acp-approval.js.map

package/dist/runner/common/acp/base-acp-runner.d.ts

@@ -22,7 +22,7 @@ import type { AgentEvent, AgentKind, AgentSessionReader, SpawnOptions } from '..
 import { ConnectionManager } from '../jsonrpc/connection-manager.js';
 import { JsonRpcClient } from '../jsonrpc/client.js';
 import { type SessionNewResult, type SessionResumeResult, type SessionPromptResult, type RequestPermissionParams } from './protocol-types.js';
-import { type AcpPendingApproval } from './protocol-helpers.js';
+import { type AcpPendingApproval } from './acp-approval.js';
 import { ConnectionBasedRunner } from '../connection-based-runner.js';
 import { BaseAcpTranslator, type AcpTranslatorEvent } from './base-translator.js';
 export type { AcpTranslatorEvent } from './base-translator.js';

package/dist/runner/common/acp/base-acp-runner.js

@@ -1,4 +1,4 @@
-import { respondAcpApproval, sendAcpSetMode, truncateWithEllipsis, } from './protocol-helpers.js';
+import { respondAcpApproval, sendAcpSetMode, truncateWithEllipsis, } from './acp-approval.js';
 import { getLogger } from '../../../logger/index.js';
 import { ConnectionBasedRunner } from '../connection-based-runner.js';
 export class BaseAcpRunner extends ConnectionBasedRunner {
@@ -15,7 +15,7 @@ export class BaseAcpRunner extends ConnectionBasedRunner {
     constructor(opts, connectionManager) {
         super(opts);
         this.connectionManager = connectionManager;
-        // 协议停止通道（design §3.3）：ACP 的 cancel 就是 `session/cancel`，已由
+        // 协议停止通道：ACP 的 cancel 就是 `session/cancel`，已由
         // cancelCurrentTurn 实现。这里只做登记接线——manager 建在 super() 实参里，
         // 那时 this 不可用，所以只能等 super() 返回后再赋值。
         connectionManager.stopper = ({ client }) => this.buildCooperativeStop(client);