lark-remote 0.4.4 → 0.5.0

package/dist/bridge/index.js

@@ -9,7 +9,7 @@ import { BashCardSession, capBashOutput } from '../card/bash-card-session.js';
 import { buildSessionHistoryCard } from '../router/card-helpers.js';
 import { agentDisplayName, resumeUseButton } from '../card/card-shared.js';
 import { enforceCardBudget } from '../card/card-budget.js';
-import { normalizeResultUsage } from '../runner/common/usage.js';
+import { normalizeResultUsage } from '../runner/common/result-usage.js';
 import { BashProcessRunner } from '../runner/index.js';
 import { QueueManager, } from './queue-manager.js';
 import { ApprovalCoordinator, decisionToApprovalAction } from './approval-coordinator.js';
@@ -18,13 +18,13 @@ import { InboundMediaHandler } from './inbound-media.js';
  * Max events to read for the completion notification card (mirror router's
  * AUTO_RESUME_MAX_EVENTS = 5). Without a cap, readSessionContent returns every
  * event after the last user message and the card blows past Feishu's 28KB
- * budget (review §P1-21).
+ * budget.
  */
 const COMPLETION_NOTIFICATION_MAX_EVENTS = 5;
 /** Approval request timeout (ms) — pending approval expires after this. */
 const APPROVAL_TIMEOUT_MS = 5 * 60 * 1000;
 /**
- * runner 缓存的工作区数量上限（review P3-3）：超过后创建新工作区槽位时
+ * runner 缓存的工作区数量上限：超过后创建新工作区槽位时
  * 顺带回收「非 active 且进程已停」的死缓存，防止随访问过的工作区数量
  * 无界增长。活进程/在途 run 一律保留（workspace-lifetime 长驻连接不能误杀）。
  */
@@ -50,8 +50,8 @@ function terminalReactionEmoji(terminal) {
     return TERMINAL_REACTION_EMOJI[terminal] ?? 'Done';
 }
 /**
- * W2.4 单点化：`'runCompact' in runner` 鸭子探测（compact 按钮门控，
- * design doc §6.2-2）。codex app-server + kimi/opencode ACP runner 满足。
+ * 单点化：`'runCompact' in runner` 鸭子探测
+ * codex app-server + kimi/opencode ACP runner 满足。
  */
 function runnerHasRunCompact(runner) {
     return ('runCompact' in runner && typeof runner.runCompact === 'function');
@@ -62,10 +62,10 @@ function runnerHasRunCompact(runner) {
  *
  * The router delegates non-command messages here via `forwardToClaude` and
  * sends command results via `sendResult`. Serial processing is enforced per
- * workspace by `enqueue`: each workspace has its own Promise chain, so at
- * most one agent process runs per workspace at a time, while different
+ * cwd by `enqueue`: each cwd has its own Promise chain, so at
+ * most one agent process runs per cwd at a time, while different
  * workspaces run in parallel (see `activeRuns`, §9.6). This is a load-bearing
- * invariant — concurrent spawns within one workspace would corrupt session
+ * invariant — concurrent spawns within one cwd would corrupt session
  * state. Most card actions go through `enqueueImmediate` (fire-and-forget,
  * outside the serial chain); only run-forwarding is serialized.
  *
@@ -98,8 +98,8 @@ export class Bridge {
      */
     runners = new Map();
     /**
-     * Runner 槽位在「活跃运行期间配置变更」时被标 stale（CC-06/P1）：clearRunners() 对
-     * 活跃 workspace 只标 stale、不立即 evict（避免误杀长驻连接），当前 run 结束后由
+     * Runner 槽位在「活跃运行期间配置变更」时被标 stale：clearRunners() 对
+     * 活跃 cwd 只标 stale、不立即 evict（避免误杀长驻连接），当前 run 结束后由
      * finalizeRun 安全 evict+dispose，下一轮 getRunner 创建新配置的 runner。
      * key 为 `${cwd}\u0000${agentKind}`。
      */
@@ -107,7 +107,7 @@ export class Bridge {
     /** Queue manager for per-workspace serial processing queue. */
     /** 普通消息队列管理器（public：测试注入 queue-card 状态用）。 */
     queueManager;
-    /** Active runs per workspace (cwd). Multiple workspaces can run in parallel. */
+    /** Active runs per cwd (cwd). Multiple workspaces can run in parallel. */
     activeRuns = new Map();
     /** Approval coordinators keyed by runId. */
     approvalCoordinators = new Map();
@@ -115,11 +115,11 @@ export class Bridge {
      * 最近一次已完成的、runner 有 runCompact 的 run（按 cwd）。run 结束后
      * activeRuns 已清空，Compact 需要它来校验 runId 并提供 sessionId。
      */
-    lastCompactableCodexRun = new Map();
+    lastCompactableRun = 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
-     * workspace, so they live outside `activeRuns`. Tracked so `/stop` can reach
+     * cwd, so they live outside `activeRuns`. Tracked so `/stop` can reach
      * the per-run BashRunner instance via interruptCurrentRun.
      */
     activeBashRuns = new Map();
@@ -131,29 +131,29 @@ export class Bridge {
         this.idleTimeoutMs = deps.idleTimeoutMs ?? IDLE_TIMEOUT_MS;
         this.agentRegistry = deps.agentRegistry;
         this.sessionReaderRegistry = deps.sessionReaderRegistry;
-        this.queueManager = new QueueManager((workspace) => this.activeRuns.has(workspace), (chatId, card, opts) => this.connector.sendWithRetry(chatId, { card }, { replyTo: opts?.replyTo }), (messageId, card) => this.connector.updateCard(messageId, card));
+        this.queueManager = new QueueManager((cwd) => this.activeRuns.has(cwd), (chatId, card, opts) => this.connector.sendWithRetry(chatId, { card }, { replyTo: opts?.replyTo }), (messageId, card) => this.connector.updateCard(messageId, card));
         this.mediaHandler = new InboundMediaHandler({
             resolveCwd: (userId) => this.resolveCwd(userId),
             getConfig: () => this.config,
         });
     }
     /**
-     * Get or create a runner for the given workspace, keyed by current defaultAgent.
+     * Get or create a runner for the given cwd, keyed by current defaultAgent.
      *
      * Fix 4 (2026-07-18): Cache key includes agentKind, so switching defaultAgent
      * creates a NEW runner under a different key without evicting the old one.
      * This eliminates the need for clearRunners() on agent switch.
      */
-    getRunner(workspace, kind = this.config.defaultAgent) {
-        // Fix 4: Check for runner under (workspace, kind) key
-        const workspaceMap = this.runners.get(workspace);
+    getRunner(cwd, kind = this.config.defaultAgent) {
+        // Fix 4: Check for runner under (cwd, kind) key
+        const workspaceMap = this.runners.get(cwd);
         if (workspaceMap?.has(kind)) {
             return workspaceMap.get(kind);
         }
-        // review P3-3：缓存超过上限且是新工作区时才回收死槽位——刚创建未 run
+        // 缓存超过上限且是新工作区时才回收死槽位——刚创建未 run
         // 的 runner 同样是 isRunning=false，小缓存下立即回收会破坏「创建即注册」
         // 的既有语义（exit-dispatcher 计数回归）。
-        if (this.runners.size >= MAX_CACHED_RUNNER_WORKSPACES && !this.runners.has(workspace)) {
+        if (this.runners.size >= MAX_CACHED_RUNNER_WORKSPACES && !this.runners.has(cwd)) {
             for (const [cwd, slotMap] of [...this.runners.entries()]) {
                 if (this.activeRuns.has(cwd))
                     continue;
@@ -164,8 +164,8 @@ export class Bridge {
                 }
             }
         }
-        // Create new runner for this (workspace, kind) slot
-        const runner = this.agentRegistry.get(kind, workspace);
+        // Create new runner for this (cwd, kind) slot
+        const runner = this.agentRegistry.get(kind, cwd);
         // Call lifecycle methods for agent runners created via factory
         if (runner && typeof runner.killOrphan === 'function') {
             runner.killOrphan();
@@ -173,9 +173,9 @@ export class Bridge {
         if (runner && typeof runner.registerExitHandlers === 'function') {
             runner.registerExitHandlers();
         }
-        // Store in nested map: Map<workspace, Map<kind, Runner>>
+        // Store in nested map: Map<cwd, Map<kind, Runner>>
         if (!workspaceMap) {
-            this.runners.set(workspace, new Map([[kind, runner]]));
+            this.runners.set(cwd, new Map([[kind, runner]]));
         }
         else {
             workspaceMap.set(kind, runner);
@@ -241,25 +241,29 @@ export class Bridge {
                 return undefined;
         }
     }
-    /** Get the current runner for a workspace. Used by router for agent-specific commands (P3.2). */
-    getCurrentRunner(workspace) {
-        return this.getRunner(workspace);
+    /** Get the current runner for a cwd. Used by router for agent-specific commands (.2). */
+    getCurrentRunner(cwd) {
+        return this.getRunner(cwd);
     }
     /**
      * Whether the runner for the given agent kind has runCompact capability.
-     * Used by router for compact button gating (design doc §6.2-2: duck-typing
+     * Used by router for compact button gating (duck-typing
      * instead of hardcoding agentKind === 'codex').
      */
-    hasRunCompact(workspace, kind = this.config.defaultAgent) {
-        const runner = this.getRunner(workspace, kind);
+    hasRunCompact(cwd, kind = this.config.defaultAgent) {
+        const runner = this.getRunner(cwd, kind);
         return runnerHasRunCompact(runner);
     }
     /** 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
-     *  唯一捕获点：排队消息在 T0 把 agent+session 钉进 AgentBinding，随任务闭包带到 T1
-     *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移（方案 D4）。 */
+     *  唯一捕获点：排队消息在入队时刻把 agent+session 钉进 AgentBinding，随任务闭包带到执行时刻
+     *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移。 */
     currentBinding(userId) {
         const agent = this.config.defaultAgent;
-        return { agent, sessionId: this.sessionStore.getSessionId(userId, agent) };
+        return {
+            agent,
+            sessionId: this.sessionStore.getSessionId(userId, agent),
+            sessionEpoch: this.sessionStore.getSessionEpoch(userId, agent),
+        };
     }
     /**
      * Clear all cached runner instances. Call after config changes that affect runner config.
@@ -274,7 +278,7 @@ export class Bridge {
         // ends, and the next run picks up the new config/agent via getRunner.
         for (const cwd of [...this.runners.keys()]) {
             if (this.activeRuns.has(cwd)) {
-                // CC-06/P1: 活跃 workspace 不能立即 evict（会误杀长驻连接），但必须标记 stale，
+                // 活跃 cwd 不能立即 evict（会误杀长驻连接），但必须标记 stale，
                 // 否则 finalizeRun 对 workspace-lifetime runner 也不 evict → 下一轮复用旧配置实例。
                 // 这里只标待淘汰，当前 run 结束后由 finalizeRun 安全 evict。
                 for (const kind of [...this.runners.get(cwd).keys()]) {
@@ -290,7 +294,7 @@ export class Bridge {
     }
     /**
      * Evict a (cwd, agentKind) runner cache slot. Unregisters the runner from the
-     * process-level exit dispatcher first (P1-1: without removal the singleton
+     * process-level exit dispatcher first (without removal the singleton
      * Set<Runner> retains every historical runner instance, so memory still grows
      * with run count), then deletes the slot. Every runner-discarding path
      * (clearRunners / finalizeRun / interruptCurrentRun) must go through this.
@@ -365,48 +369,48 @@ export class Bridge {
      * Enqueue a task into the workspace-level serial bridge queue.
      * Delegates to QueueManager for actual implementation.
      */
-    enqueue(workspace, task, opts) {
-        this.queueManager.enqueue(workspace, task, opts);
+    enqueue(cwd, task, opts) {
+        this.queueManager.enqueue(cwd, task, opts);
     }
     /**
      * Execute a task immediately without going through the queue.
      * Used for / commands that should respond immediately.
      */
-    enqueueImmediate(workspace, task) {
-        this.queueManager.enqueueImmediate(workspace, task);
+    enqueueImmediate(cwd, task) {
+        this.queueManager.enqueueImmediate(cwd, task);
     }
-    /** Get queue info for a workspace. */
-    getQueueInfo(workspace) {
-        return this.queueManager.getQueueInfo(workspace);
+    /** Get queue info for a cwd. */
+    getQueueInfo(cwd) {
+        return this.queueManager.getQueueInfo(cwd);
     }
     /** Remove a task from the queue by messageId. Returns true if found and removed. */
-    removeFromQueue(workspace, messageId) {
-        return this.queueManager.removeFromQueue(workspace, messageId);
+    removeFromQueue(cwd, messageId) {
+        return this.queueManager.removeFromQueue(cwd, messageId);
     }
     /**
      * One-shot: replace the execution closure of an existing queued task in
      * place, preserving its queue position. Used by queue.immediate after the
      * user edits a queued message (see router handleQueueImmediate).
      */
-    setTaskReplacement(workspace, messageId, task) {
-        this.queueManager.setTaskReplacement(workspace, messageId, task);
+    setTaskReplacement(cwd, messageId, task) {
+        this.queueManager.setTaskReplacement(cwd, messageId, task);
     }
     /** Update queue card to "cancelled" status when user clicks 撤销. */
-    async updateQueueCardToCancelled(workspace, messageId) {
-        await this.queueManager.updateQueueCardToCancelled(workspace, messageId);
+    async updateQueueCardToCancelled(cwd, messageId) {
+        await this.queueManager.updateQueueCardToCancelled(cwd, messageId);
     }
     /** Mark a queued task's card as executing immediately (grey out buttons).
      *  Called by handleQueueImmediate so the user sees feedback right away
      *  instead of waiting for the queue callback. Idempotent: the queue
      *  callback's own updateQueueCardToExecuting call becomes a no-op because
      *  updateQueueCardToExecuting deletes the card-message mapping in finally. */
-    async markQueueCardExecuting(workspace, messageId) {
-        const task = this.getQueuedTask(workspace, messageId);
-        await this.queueManager.updateQueueCardToExecuting(workspace, messageId, task?.messagePreview ?? '', false);
+    async markQueueCardExecuting(cwd, messageId) {
+        const task = this.getQueuedTask(cwd, messageId);
+        await this.queueManager.updateQueueCardToExecuting(cwd, messageId, task?.messagePreview ?? '', false);
     }
     /** Get task metadata from queue. */
-    getQueuedTask(workspace, messageId) {
-        return this.queueManager.getQueuedTask(workspace, messageId);
+    getQueuedTask(cwd, messageId) {
+        return this.queueManager.getQueuedTask(cwd, messageId);
     }
     /**
      * Whether a task with the given messageId has begun executing and has not
@@ -418,9 +422,9 @@ export class Bridge {
     hasTaskBegan(messageId) {
         return this.queueManager.hasBegan(messageId);
     }
-    /** Get all queued tasks for a workspace. Returns a copy to prevent aliasing bugs. */
-    getQueuedTasks(workspace) {
-        return this.queueManager.getQueuedTasks(workspace);
+    /** Get all queued tasks for a cwd. Returns a copy to prevent aliasing bugs. */
+    getQueuedTasks(cwd) {
+        return this.queueManager.getQueuedTasks(cwd);
     }
     /**
      * Update the messagePreview for a queued task and build the updated queue
@@ -429,18 +433,18 @@ export class Bridge {
      * queued. Returning the card via the callback response avoids the
      * PATCH-vs-callback-response race that left the card stuck in edit state.
      */
-    async updateMessagePreview(workspace, messageId, newMessage) {
-        const updated = this.queueManager.updateQueuedTaskMessage(workspace, messageId, newMessage);
+    async updateMessagePreview(cwd, messageId, newMessage) {
+        const updated = this.queueManager.updateQueuedTaskMessage(cwd, messageId, newMessage);
         if (!updated)
             return null;
-        return this.queueManager.buildQueueCardForEdit(workspace, messageId, newMessage);
+        return this.queueManager.buildQueueCardForEdit(cwd, messageId, newMessage);
     }
-    /** Whether a claude run is currently in progress in the given workspace. */
-    isBusyFor(workspace) {
-        return this.activeRuns.has(workspace);
+    /** Whether a claude run is currently in progress in the given cwd. */
+    isBusyFor(cwd) {
+        return this.activeRuns.has(cwd);
     }
-    getActiveRunFor(workspace) {
-        const active = this.activeRuns.get(workspace);
+    getActiveRunFor(cwd) {
+        const active = this.activeRuns.get(cwd);
         if (!active)
             return undefined;
         const state = active.session.currentState;
@@ -457,7 +461,7 @@ export class Bridge {
             cacheCreationTokens: state.cacheCreationTokens,
         };
     }
-    /** Whether any claude run is currently in progress (any workspace). */
+    /** Whether any claude run is currently in progress (any cwd). */
     get isBusy() {
         return this.activeRuns.size > 0;
     }
@@ -515,7 +519,7 @@ export class Bridge {
     async interruptCurrentRun(input) {
         // Find the active claude run matching this user/chat
         for (const [cwd, active] of this.activeRuns) {
-            if (input.workspace !== undefined && cwd !== input.workspace)
+            if (input.cwd !== undefined && cwd !== input.cwd)
                 continue;
             if (active.userId === input.userId && active.chatId === input.chatId) {
                 if (input.runId && active.runId !== input.runId)
@@ -531,7 +535,7 @@ export class Bridge {
                 // below may outlive the task's settle, letting the serial chain advance
                 // to a successor that begins executing before we resume. An
                 // unconditional reset would then zero the successor's count and mark
-                // its slot interrupted, hiding it from queue cards (A22).
+                // its slot interrupted, hiding it from queue cards.
                 const stoppedSlot = this.queueManager.getExecutingSlot(cwd);
                 await Promise.allSettled([
                     // 用户主动中断（/stop、stop 卡按钮、queue.immediate）显式打标
@@ -542,13 +546,13 @@ export class Bridge {
                 ]);
                 // The chain may have advanced while the stop was in flight: a new run
                 // (from a task that began during the stop window) may now occupy this
-                // workspace. Only delete the entry we actually stopped.
+                // cwd. Only delete the entry we actually stopped.
                 if (this.activeRuns.get(cwd) === active) {
                     this.activeRuns.delete(cwd);
                 }
                 // Fix 4: Clean up this specific (cwd, agentKind) runner slot
-                // (P1-1: eviction must also unregister the runner from the exit dispatcher)
-                // P2-3: evict by the run's captured agentKind, not the live
+                // (eviction must also unregister the runner from the exit dispatcher)
+                // evict by the run's captured agentKind, not the live
                 // defaultAgent (may have changed mid-run via /config).
                 this.evictRunnerSlot(cwd, active.agentKind);
                 // Reset queue executing count: the task was interrupted externally, so
@@ -570,7 +574,7 @@ export class Bridge {
         // Then check active bash runs (! commands). These bypass the serial queue
         // and are tracked separately; stop the per-run BashRunner directly.
         for (const [runId, b] of this.activeBashRuns) {
-            if (input.workspace !== undefined && b.cwd !== input.workspace)
+            if (input.cwd !== undefined && b.cwd !== input.cwd)
                 continue;
             if (b.userId === input.userId && b.chatId === input.chatId) {
                 if (input.runId && runId !== input.runId)
@@ -679,7 +683,7 @@ export class Bridge {
     }
     /**
      * Resolve the working directory for a user.
-     * First checks sessionStore (set by /cd), then falls back to first workspace.
+     * First checks sessionStore (set by /cd), then falls back to first cwd.
      * Returns undefined if no cwd is available.
      */
     resolveCwd(userId) {
@@ -691,7 +695,7 @@ export class Bridge {
                 // NOTE: fallback uses insertion order, not sort preference — by design
                 // (cwd fallback stays insertion-order for now)
                 cwd = workspaces[0].path;
-                getLogger().info(`[lark-remote] resolveCwd fallback cwd=${cwd} (first saved workspace)`);
+                getLogger().info(`[lark-remote] resolveCwd fallback cwd=${cwd} (first saved cwd)`);
             }
         }
         return cwd;
@@ -705,9 +709,9 @@ export class Bridge {
      * updates the same run card, and terminal events finalize that card.
      */
     async forwardToClaude(message, ctx, opts) {
-        // D5: agentKind 一律来自绑定。无 binding 时保持现状（live defaultAgent）。
+        // agentKind 一律来自绑定。无 binding 时保持现状（live defaultAgent）。
         const agentKind = opts?.binding?.agent ?? this.config.defaultAgent;
-        // P1-14: lane 与执行 cwd 同源。消息入队时（index.ts 闭包）捕获的 workspace
+        // lane 与执行 cwd 同源。消息入队时（index.ts 闭包）捕获的 cwd
         // 作为 cwdOverride 显式传入；执行时若 sessionStore cwd 已被 /cd 等命令改写，
         // 以 lane 为准 —— 否则旧 lane 的排队消息会被 busy-drop 静默丢失。空串视为
         // 未提供（与入队前无 cwd 的兜底语义一致）。
@@ -720,21 +724,24 @@ export class Bridge {
         const entry = this.sessionStore.get(ctx.userId);
         getLogger().debug(`[lark-remote] forward entry userId=${ctx.userId} chatId=${ctx.chatId} cwd=${cwd} ` +
             `agent=${agentKind} sessionId=${opts?.binding?.sessionId ?? entry?.sessions?.get(agentKind) ?? '(none)'} message=${message.slice(0, 100)}`);
-        // Check if current workspace already has a run in progress
+        // Check if current cwd already has a run in progress
         if (this.activeRuns.has(cwd)) {
-            getLogger().warn(`[lark-remote] workspace busy, dropping message userId=${ctx.userId} cwd=${cwd}`);
-            await this.sendResult({ text: '此 workspace 正在处理中，请 /stop 后重试' }, ctx);
+            getLogger().warn(`[lark-remote] cwd busy, dropping message userId=${ctx.userId} cwd=${cwd}`);
+            await this.sendResult({ text: '此工作目录正在处理中，请 /stop 后重试' }, ctx);
             return;
         }
         // Note: Multiple workspaces can have runs in parallel. If runner is busy,
         // runner.run() will throw and we'll catch it below.
-        // D2/D5: sessionId 钉死语义——binding 有 sessionId 时用它（入队时刻快照），
+        // sessionId 钉死语义——binding 有 sessionId 时用它（入队时刻快照），
         // 否则跟随 live store（无 binding 或入队时无 session 的正常路径）。
         const sessionId = opts?.binding?.sessionId ?? this.sessionStore.getSessionId(ctx.userId, agentKind);
-        // 会话代际快照（2026-08-09）：run 在途时 /new、/cd、/resume 会 bump epoch，
-        // 该 run 后续 system.init 的 sessionId 写回即判 stale 跳过。在执行起点
-        // （而非入队点）捕获，保持 binding「钉死 resume」既有语义。
-        const sessionEpochAtStart = this.sessionStore.getSessionEpoch(ctx.userId, agentKind);
+        // 会话代际快照（2026-08-09，2026-10-07 前移）：/new、/cd、/resume 会 bump
+        // epoch，该 run 后续 system.init 的 sessionId 写回即判 stale 跳过。
+        // 快照点优先取 binding.sessionEpoch（入队/commit 时刻，与 sessionId 同刻）：
+        // 排队消息在「commit 后、开跑前」被 reset 时，执行起点捕获会漏判（epoch 已是
+        // bump 后的值）→ 旧 sessionId 被写回复活 reset。无 binding 时回退执行起点捕获，
+        // 保持非排队路径（如 /compact）的既有语义。
+        const sessionEpochAtStart = opts?.binding?.sessionEpoch ?? this.sessionStore.getSessionEpoch(ctx.userId, agentKind);
         // Resolve the runner BEFORE creating the run session so the exact instance
         // that will run is captured into activeRun. interruptCurrentRun stops THAT
         // instance directly -- never a fresh runner re-resolved from a cache that
@@ -754,8 +761,8 @@ export class Bridge {
     createRunSession(ctx, cwd, runner, agentKind = this.config.defaultAgent) {
         const runId = randomUUID();
         getLogger().debug(`[lark-remote] creating runCard runId=${runId}`);
-        // D5: agentKind 来自入队绑定（forwardToClaude 解析），不再读 live config。
-        // 缓存键 (cwd, agentKind) 和 eviction 都用这个值（review P2-3）。
+        // agentKind 来自入队绑定（forwardToClaude 解析），不再读 live config。
+        // 缓存键 (cwd, agentKind) 和 eviction 都用这个值。
         const cardSession = new RunCardSession({
             connector: this.connector,
             chatId: ctx.chatId,
@@ -783,7 +790,7 @@ export class Bridge {
         return { runId, cardSession, activeRun };
     }
     /**
-     * §9.12 空闲看门狗：单 interval + 截止时间判定（P2-1），普通 run 与 compact
+     * §9.12 空闲看门狗：单 interval + 截止时间判定，普通 run 与 compact
      * 共用同一套兜底。事件到达只 `touch()` 刷新时间戳（无 timer 操作）；静默超过
      * `idleTimeoutMs` 才 finish('idle_timeout') + runner.stop()，让该工作区的串行
      * 队列继续推进（否则一个挂死的 run 永久堵住后续消息）。
@@ -832,7 +839,7 @@ export class Bridge {
      * Handles idle watchdog, event processing, session sync, and state transitions.
      */
     async runAgentStreamToEnd(runner, cardSession, sessionId, sessionEpochAtStart, ctx, cwd, runId, message, agentKind = this.config.defaultAgent) {
-        // Runner 声明的 usage 权威来源（review P3-7）：codex app-server = 'live'
+        // Runner 声明的 usage 权威来源：codex app-server = 'live'
         // （turn/started 的 tokenUsage.last 是本 turn 增量）。其余 runner 未声明。
         const usageAuthority = runner.getUsageAuthority?.();
         // §9.12 空闲看门狗：判定口径见 startIdleWatchdog；武装点在 cardSession.start() 之后。
@@ -872,7 +879,7 @@ export class Bridge {
         // Reasoning tokens (pi usage.reasoning) from the live result event.
         let finalReasoningTokens;
         // 统一的 usage meta 构造（finalize 各分支共享，本方法内原先 5 处手写 11-15
-        // 字段对象；第 6 处 streamCodexCompact 形状不同未收敛）。
+        // 字段对象；第 6 处 streamCompact 形状不同未收敛）。
         // catch 路径需覆盖 flow 字段时在展开后覆写即可。catch error 路径亦复用此
         // 闭包，相比旧手写对象补齐了累计 cache 字段（cumulativeCacheReadTokens/
         // cumulativeCacheCreationTokens），属有意的口径对齐（向 done 路径看齐）。
@@ -907,7 +914,7 @@ export class Bridge {
                 // Card session did not enter running state - still try to send static fallback
                 getLogger().info(`[lark-remote] cardSession not running, using static fallback`);
             }
-            // P2-1: 单 interval 看门狗。事件到来时只刷新时间戳（无 timer 操作）；
+            // 单 interval 看门狗。事件到来时只刷新时间戳（无 timer 操作）；
             // interval 周期检查静默时长，超时才 finish('idle_timeout') + stop()。
             // 武装点在建卡之后，与原实现一致（宽限期不含 cardSession.start() 耗时）。
             watchdog = this.startIdleWatchdog({
@@ -948,20 +955,20 @@ export class Bridge {
                         getLogger().info(`[lark-remote] system.init write-back skipped: session pointer moved since run start runId=${runId} sessionId=${event.session_id}`);
                     }
                     else {
-                        // L5: Use session's real directory from event.cwd (not runner's cwd parameter)
-                        // L3: guard empty string too -- `??` only catches null/undefined, but a
+                        // Use session's real directory from event.cwd (not runner's cwd parameter)
+                        // guard empty string too -- `??` only catches null/undefined, but a
                         // translator (or older build) may emit cwd="", which must NOT overwrite
                         // the good runner cwd.
                         const hasCwd = !!this.sessionStore.getCwd(ctx.userId);
                         const realCwd = event.cwd && event.cwd.length > 0 ? event.cwd : cwd;
                         if (hasCwd && event.cwd && event.cwd !== cwd) {
                             // Session has its own cwd (e.g. EnterWorktree relocate). Keep the
-                            // workspace cwd unchanged; record the session's actual cwd in sessionCwds.
-                            getLogger().info(`[lark-remote] system.init: workspace cwd=${cwd}, session cwd=${event.cwd}`);
+                            // cwd unchanged; record the session's actual cwd in sessionCwds.
+                            getLogger().info(`[lark-remote] system.init: cwd=${cwd}, session cwd=${event.cwd}`);
                             this.sessionStore.setSessionIdAndSessionCwd(ctx.userId, agentKind, event.session_id, realCwd);
                         }
                         else {
-                            // First use (no workspace cwd yet) or event.cwd matches runner cwd:
+                            // First use (no cwd yet) or event.cwd matches runner cwd:
                             // set sessionId + cwd as before; on first use also bootstrap sessionCwds.
                             const bootstrapSessionCwd = !hasCwd && event.cwd && event.cwd.length > 0 ? event.cwd : undefined;
                             this.sessionStore.setSessionIdAndCwd(ctx.userId, agentKind, event.session_id, realCwd, bootstrapSessionCwd);
@@ -1021,7 +1028,7 @@ export class Bridge {
                         : `[lark-remote] result event received runId=${runId}`);
                     // app-server 模式 setup 失败路径（thread/start 成功后 turn/start 失败）
                     // 不会有 turn_started 事件，store 不会写回新线程 id；runner 已在 result
-                    // 里兜底上报（review P3-10）。此处仅当 runner 声明 live usage（app-server）
+                    // 里兜底上报。此处仅当 runner 声明 live usage（app-server）
                     // 且会话指针未动时写回，避免下条消息再开一个孤儿线程。其余 agent 不在
                     // 此列（它们各自有 system.init / turn_started 写回）。
                     if (usageAuthority === 'live' &&
@@ -1114,7 +1121,7 @@ export class Bridge {
                     const coordinator = this.approvalCoordinators.get(runId);
                     coordinator?.updateView(event.requestId, event.view);
                 }
-                // §9.12 红线（§P1-2 方案 A）：每个事件（含 result）无条件刷新
+                // §9.12 红线：每个事件（含 result）无条件刷新
                 // lastEventTs 重新武装看门狗。result 后 CLI 进程做 jsonl flush/清理（finalizing
                 // 过渡）期间，宽限期恢复为完整的 idleTimeoutMs，避免已产出结果的 turn 被误标
                 // idle_timeout。旧实现 `else { resetIdle(); }` 漏掉 result 分支。
@@ -1122,9 +1129,9 @@ export class Bridge {
                 await cardSession.push(event);
             }
             getLogger().info(`[lark-remote] runner stream end runId=${runId} sawResult=${sawResult}`);
-            // §9.12 红线（§P1-2 方案 A 第 2 点）：for-await 自然结束 = CLI 已退出，
+            // §9.12 红线：for-await 自然结束 = CLI 已退出，
             // 看门狗使命结束，立即摘除 interval（不再等 finally），堵掉「stream 已结束、
-            // 收尾处理跨过死线被误标 idle_timeout」的同源小窗口（P2-4 随本修复一并关闭）。
+            // 收尾处理跨过死线被误标 idle_timeout」的同源小窗口（随本修复一并关闭）。
             watchdog?.stop();
             // stream 结束 = CLI 退出 = jsonl 已落盘。读 jsonl 拿准确的 contextLength + compactCount：
             // live stream-json 不发 compact_boundary，live contextLength 会被 result 的 input+output 兜底失真。
@@ -1203,7 +1210,7 @@ export class Bridge {
         }
         catch (err) {
             getLogger().error(`[lark-remote] claude run error runId=${runId}:`, err);
-            // P1-11 双保险：run() 的 finally 已负责杀子进程，但 catch 路径再补一次
+            // 双保险：run() 的 finally 已负责杀子进程，但 catch 路径再补一次
             // runner.stop()（与 bash 路径对齐），覆盖任何 finally 之外的残留窗口。
             try {
                 await runner.stop();
@@ -1292,10 +1299,10 @@ export class Bridge {
             this.finishTurnReactions(ctx, terminalReactionEmoji(cardSession.currentState.terminal));
         }
         finally {
-            // P1-13: cleanup must survive mid-finalize errors. The only unguarded
+            // cleanup must survive mid-finalize errors. The only unguarded
             // expression in finalizeRun is the renderRunCard(...) argument evaluated
             // at the sendResult call site; if it throws, the run must still release
-            // its activeRuns slot — otherwise the workspace is permanently busy
+            // its activeRuns slot — otherwise the cwd is permanently busy
             // (every later message busy-dropped until a manual /stop).
             if (this.activeRuns.get(cwd) === activeRun) {
                 this.activeRuns.delete(cwd);
@@ -1305,7 +1312,7 @@ export class Bridge {
                 // evicted+disposed by clearRunners (/config) and interruptCurrentRun
                 // (/stop). Spawn-per-message runners are evicted as before to prevent
                 // stale process references accumulating.
-                // CC-06/P1: 配置变更期间（clearRunners 标了 stale）的 workspace-lifetime
+                // 配置变更期间（clearRunners 标了 stale）的 workspace-lifetime
                 // runner 也必须在 run 结束后 evict，否则下一轮复用旧配置实例。
                 const slotKey = `${cwd}\u0000${activeRun.agentKind}`;
                 if (activeRun.runner.lifetime !== 'workspace' || this.staleRunnerSlots.has(slotKey)) {
@@ -1315,7 +1322,7 @@ export class Bridge {
                 // Compact 卡片需要 runId + sessionId；record 供终态卡上的 Compact 按钮
                 // 校验与取参（activeRuns 已清空，无法再查到）。异常退出（error/
                 // interrupted/idle_timeout）同样记录——上下文往往更大，压缩后再续。
-                // §6.2-3：写入条件从「codex 终态」放宽为「runner 有 runCompact 的终态」
+                // 写入条件从「codex 终态」放宽为「runner 有 runCompact 的终态」
                 // （codex app-server + kimi acp 均满足）。
                 const runTerminal = cardSession.currentState.terminal;
                 const runnerHasCompact = runnerHasRunCompact(activeRun.runner);
@@ -1328,7 +1335,7 @@ export class Bridge {
                     const compactSessionId = cardSession.currentState.sessionId ??
                         this.sessionStore.getSessionId(ctx.userId, activeRun.agentKind);
                     if (compactSessionId) {
-                        this.lastCompactableCodexRun.set(cwd, {
+                        this.lastCompactableRun.set(cwd, {
                             runId: activeRun.runId,
                             sessionId: compactSessionId,
                             agentKind: activeRun.agentKind,
@@ -1347,7 +1354,7 @@ export class Bridge {
      */
     async sendCompletionNotificationCard(sessionId, cwd, ctx, agentKind = this.config.defaultAgent) {
         try {
-            // P1-21: cap the events read for the notification card — without
+            // cap the events read for the notification card — without
             // maxEvents claude returns every event after the last user message and
             // the card blows past Feishu's 28KB budget.
             const content = this.sessionReaderRegistry.get(agentKind).readSessionContent(sessionId, cwd, {
@@ -1367,7 +1374,7 @@ export class Bridge {
                 actions: [resumeUseButton(sessionId, agentKind)],
                 headerTemplate: 'green',
             });
-            // P1-21: send through sendResult so enforceCardBudget guards the card
+            // send through sendResult so enforceCardBudget guards the card
             // (previously sent via connector directly, bypassing the budget — long
             // sessions produced >28KB cards that Feishu silently rejected).
             const sent = await this.sendResult({ card }, ctx);
@@ -1392,7 +1399,7 @@ export class Bridge {
     withCoordinator(runId, fn) {
         const coordinator = this.approvalCoordinators.get(runId);
         if (!coordinator) {
-            // P2-7: run 已结束（coordinator 已释放）时点击审批按钮必须给用户明确反馈，
+            // run 已结束（coordinator 已释放）时点击审批按钮必须给用户明确反馈，
             // 不能静默。router 会把该异常转成 error toast。
             getLogger().warn(`[lark-remote] no approval coordinator for runId=${runId.slice(0, 8)}`);
             throw new Error('任务已结束，审批无法响应');
@@ -1456,7 +1463,7 @@ export class Bridge {
         return this.withCoordinator(opts.runId, (coordinator) => coordinator.submitAnswers({ questionIndex: opts.questionIndex }, { requestId: opts.requestId, nonce: opts.nonce }));
     }
     /**
-     * Claude AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接
+     * Claude AskUserQuestion 自定义答案（Other）：自由文本直接
      * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
      */
     async handleApprovalAnswerCustom(opts) {
@@ -1475,14 +1482,14 @@ export class Bridge {
         return this.withCoordinator(opts.runId, (coordinator) => coordinator.answerNote({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
     }
     /**
-     * Handle codex.compact card action — trigger a compaction request for any
+     * Handle compact card action — trigger a compaction request for any
      * runCompact-capable runner（codex/kimi/opencode/pi/claude，按
-     * lastCompactableCodexRun 记录的 agentKind 路由）。Validates the run exists
+     * lastCompactableRun 记录的 agentKind 路由）。Validates the run exists
      * and is in a terminal state, then calls the runner's runCompact().
      */
-    async handleCodexCompact(value, ctx) {
+    async handleCompactAction(value, ctx) {
         const log = getLogger();
-        log.info(`[lark-remote] handleCodexCompact userId=${ctx.userId} runId=${value.runId?.slice(0, 8)}...`);
+        log.info(`[lark-remote] handleCompactAction userId=${ctx.userId} runId=${value.runId?.slice(0, 8)}...`);
         const { runId } = value;
         if (!runId) {
             await this.sendResult({ text: '⚠️ 无效的 Compact 请求，缺少 runId' }, ctx);
@@ -1493,8 +1500,8 @@ export class Bridge {
             await this.sendResult({ text: '⚠️ 未设置工作目录' }, ctx);
             return;
         }
-        // 校验：run 结束后 activeRuns 已清空，用 lastCompactableCodexRun 对照 runId。
-        const last = this.lastCompactableCodexRun.get(cwd);
+        // 校验：run 结束后 activeRuns 已清空，用 lastCompactableRun 对照 runId。
+        const last = this.lastCompactableRun.get(cwd);
         if (!last || last.runId !== runId) {
             await this.sendResult({ text: '⚠️ 该任务已结束或不属于当前会话' }, ctx);
             return;
@@ -1513,8 +1520,8 @@ export class Bridge {
             await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
             return;
         }
-        log.info(`[lark-remote] handleCodexCompact executing runCompact for runId=${runId} cwd=${cwd}`);
-        await this.streamCodexCompact({
+        log.info(`[lark-remote] handleCompactAction executing runCompact for runId=${runId} cwd=${cwd}`);
+        await this.streamCompact({
             sessionId: last.sessionId,
             cwd,
             agentKind: last.agentKind,
@@ -1556,16 +1563,16 @@ export class Bridge {
      * Stream a compaction to a card: start a RunCardSession with
      * operationKind='compaction' (no recursive Compact button), consume
      * runner.runCompact() events, read authoritative jsonl usage, and finish
-     * the card. Shared by handleCodexCompact (run card button) and
+     * the card. Shared by handleCompactAction (run card button) and
      * handleResumeCompact (resume cards) so both flows stay in sync.
      *
      * Precondition: callers have already validated that `runner` implements
      * runCompact and that the session exists in `cwd`.
      */
-    async streamCodexCompact(opts) {
+    async streamCompact(opts) {
         const log = getLogger();
         const { sessionId, cwd, agentKind, runner, ctx } = opts;
-        log.info(`[lark-remote] streamCodexCompact sessionId=${sessionId} cwd=${cwd}`);
+        log.info(`[lark-remote] streamCompact sessionId=${sessionId} cwd=${cwd}`);
         // 防御性能力检查：调用方已校验（runId / resume 两条路径），此处双保险并
         // 让 TS 收窄 runner 类型（'runCompact' in runner 之后的 cast 才合法）。
         if (!('runCompact' in runner) ||
@@ -1577,7 +1584,7 @@ export class Bridge {
         // 记录，令 /stop 只停到最后注册的那个。
         const busyWith = this.activeRuns.get(cwd);
         if (busyWith) {
-            log.info(`[lark-remote] compact refused: workspace busy cwd=${cwd} runId=${busyWith.runId}`);
+            log.info(`[lark-remote] compact refused: cwd busy cwd=${cwd} runId=${busyWith.runId}`);
             await this.sendResult({ text: '⚠️ 该工作区正在运行任务，请等待结束或先 /stop' }, ctx);
             return;
         }
@@ -1592,7 +1599,7 @@ export class Bridge {
                 agentKind,
             },
         });
-        // A6：压缩与普通 run 共用同一套生命周期——注册进 activeRuns（/stop 有对象可停、
+        // 压缩与普通 run 共用同一套生命周期——注册进 activeRuns（/stop 有对象可停、
         // /active 看得见）、挂 §9.12 空闲看门狗、终态后补 reaction。缺任何一环，卡住的
         // 压缩都只能等 runner 级超时，用户既停不掉也看不出它还在跑。
         const activeRun = {
@@ -1675,10 +1682,10 @@ export class Bridge {
                 cumulativeCacheReadTokens: finalUsage?.cumulativeCacheReadTokens,
                 cumulativeCacheCreationTokens: finalUsage?.cumulativeCacheCreationTokens,
             });
-            log.info(`[lark-remote] streamCodexCompact finished sessionId=${sessionId} sawResult=${sawResult} subtype=${resultSubtype ?? 'none'}`);
+            log.info(`[lark-remote] streamCompact finished sessionId=${sessionId} sawResult=${sawResult} subtype=${resultSubtype ?? 'none'}`);
         }
         catch (err) {
-            log.error(`[lark-remote] streamCodexCompact failed: ${errorMessage(err)}`);
+            log.error(`[lark-remote] streamCompact failed: ${errorMessage(err)}`);
             // 终态守卫（与 runAgentStreamToEnd 同口径）：running/finalizing 才转 error，
             // 已终态（interrupted/idle_timeout）保留首终态，不被迟到的异常改写。
             const catchTerminal = cardSession.currentState.terminal;
@@ -1705,7 +1712,7 @@ export class Bridge {
      * Handle resume.compact card action — compact a session directly from a
      * resume card (auto-resume / `/resume <id>`), without a runId.
      *
-     * Unlike handleCodexCompact (which validates against the last finished run's
+     * Unlike handleCompactAction (which validates against the last finished run's
      * runId), the resume card carries the sessionId + agent it was rendered for.
      * Validation: the session must exist in the current cwd (same rule as
      * cmdResume / resume.use) and the runner must implement runCompact.
@@ -1749,7 +1756,7 @@ export class Bridge {
             await this.sendResult({ text: `⚠️ 未找到 session ${sessionId}（当前目录: ${cwd}）` }, ctx);
             return;
         }
-        // §5.3: kimi 压缩在途检测（与 handleCodexCompact 同一入口）。
+        // §5.3: kimi 压缩在途检测（与 handleCompactAction 同一入口）。
         if (await this.rejectIfCompactionInFlight(sessionId, cwd, agentKind, ctx))
             return;
         // Check that the runner has runCompact（codex/kimi/opencode/pi/claude 鸭子探测）。
@@ -1759,7 +1766,7 @@ export class Bridge {
             return;
         }
         log.info(`[lark-remote] handleResumeCompact executing runCompact sessionId=${sessionId} cwd=${cwd}`);
-        await this.streamCodexCompact({ sessionId, cwd, agentKind, runner, ctx });
+        await this.streamCompact({ sessionId, cwd, agentKind, runner, ctx });
     }
     /**
      * Execute a bash command and stream output to a card.
@@ -1812,7 +1819,7 @@ export class Bridge {
         });
         // Track this bash run independently from claude's `activeRuns`. Bash runs
         // bypass the serial queue and may run in parallel with a claude run in the
-        // same workspace, so they must NOT share activeRuns (which is keyed by cwd
+        // same cwd, so they must NOT share activeRuns (which is keyed by cwd
         // and would let bash/claude overwrite each other). Keyed by runId so
         // multiple `!` commands can run concurrently. Tracked so /stop can reach
         // the bashRunner (which is otherwise a local) via interruptCurrentRun.
@@ -1838,7 +1845,7 @@ export class Bridge {
             }
             for await (const event of bashRunner.run(command, { cwd })) {
                 if (event.type === 'stdout') {
-                    // P1-4 层④：bridge 本地 output 也必须 store-time 截断——仅 session state
+                    // 层④：bridge 本地 output 也必须 store-time 截断——仅 session state
                     // 有界并不会让 `output +=` 自然有界（review 第④条表述不成立），!yes 洪峰
                     // 下本地字符串仍全量驻留。capBashOutput 增量调用 O(CAP+chunk)，不会带回
                     // O(n²) 截断成本（output 恒 ≤ CAP，拼接后 ≤ CAP+chunk 再 slice 尾部）。
@@ -1877,7 +1884,7 @@ export class Bridge {
             const settleResult = await cardSession.settle();
             if (settleResult === 'unsent') {
                 // Stream never established a card — send a static terminal card as fallback.
-                // Use 2.0 schema to match the streaming card (M2: avoid 2.0→1.x downgrade).
+                // Use 2.0 schema to match the streaming card (avoid 2.0→1.x downgrade).
                 try {
                     await this.connector.sendWithRetry(ctx.chatId, { card: renderBashCard(cardSession.currentState, {}) }, { replyTo: ctx.messageId });
                 }