lark-remote 0.4.5 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.0] - 2026-10-07
+
+### 新增
+
+- **CI 增加 Windows 全量验证**：新增 `windows-latest` job（install → typecheck → test → build → `--version`/`--help` 冒烟）。此前只有 ubuntu job，被平台门控跳过的用例在 CI 里是盲区，win32 独有回归只能靠本地发现
+
+### 修复
+
+- **一次发多图/多文件不再只保存 1 个**：飞书客户端「一次选多图/多文件」会背靠背秒发成多条独立消息，SDK 层 600ms 去抖把它们合并成一条——只保留最后一条的 `messageId`，却把多条消息的附件求并集。下载侧于是拿同一个 `messageId` 去下所有文件，除最后一条外全部报 234003（HTTP 400）。现关掉 SDK 这层合批（`chatQueue` 串行与卡片动作通道保留），合批交回项目自身的合并窗口
+- **Windows 上会话偶尔「消失」**：按工作目录查会话时，大小写/分隔符/尾斜杠的归一不统一，`C:\Work` 与 `c:/work/` 被当成两个目录，`/resume` 列表会漏列。现统一走同一套判等键
+- **Windows 上含 `<>:"|?*` 或尾点的文件名落盘失败**：入站附件名现在会剥掉 win32 非法字符与尾部点/空格（win32 会静默剥离它们，导致落盘名与记录名不一致）
+- **Windows 上可能误杀其他工作目录的 agent**：pid 文件名此前只按消毒后的目录名区分，`/w/a+b` 与 `/w/a_b` 会撞同一个文件，启动时的孤儿回收可能杀掉对方工作目录里存活的 agent。现后缀掺入原始目录的哈希
+- **`~` 开头的配置目录在 Windows 上不展开**：`~\` 形式此前不识别
+
+### 变更
+
+- **注释与测试命名清理**：去掉源码、测试注释与用例名中指向未发布内部文档的引用（评审条目号、场景号、轮次号、文件名前缀），让公开仓库里的引用都能落地。无行为变化
+
 ## [0.4.5] - 2026-10-07
 
 ### 修复

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

@@ -95,7 +95,7 @@ export declare class ApprovalCoordinator {
         nonce?: string;
     }): Promise<void>;
     /**
-     * AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接作为该
+     * AskUserQuestion 自定义答案（Other）：自由文本直接作为该
      * 单选问题的答案。与单选 toggle 同语义：全部问题答完自动提交。
      */
     answerCustom(action: {

package/dist/bridge/approval-coordinator.js

@@ -180,7 +180,7 @@ export class ApprovalCoordinator {
         }
         const selected = new Set(q.selected ?? []);
         if (q.multiSelect) {
-            // review P2-1：多选切换按钮同一 nonce 重复投递（双击/飞书重投递）只应
+            // 多选切换按钮同一 nonce 重复投递（双击/飞书重投递）只应
             // toggle 一次，否则勾选会被二次 toggle 抵消。单选用例的重复防护在
             // respondQuestionAnswers（提交即幂等，选中是 set 语义）。
             this.assertFreshNonce(ctx.requestId, ctx.nonce);
@@ -226,7 +226,7 @@ export class ApprovalCoordinator {
         }
     }
     /**
-     * AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接作为该
+     * AskUserQuestion 自定义答案（Other）：自由文本直接作为该
      * 单选问题的答案。与单选 toggle 同语义：全部问题答完自动提交。
      */
     async answerCustom(action, ctx) {
@@ -451,7 +451,7 @@ export class ApprovalCoordinator {
         void this.responder(requestId, { action: 'cancel' }).catch((err) => {
             getLogger().warn(`[approval-coordinator] expiry cancel failed requestId=${requestId}: ${err instanceof Error ? err.message : String(err)}`);
             // 响应失败不是「正常过期」：状态升级为 failed，避免误判为已正常通知
-            // server（spec R1：responder 抛错时状态置 failed）。
+            // server（spec responder 抛错时状态置 failed）。
             tracked.state = 'failed';
             // 兜底：cancel 未能送达时主动中断 turn，避免 server 无限等待审批响应。
             void this.interruptTurn().catch((interruptErr) => {

package/dist/bridge/inbound-media.js

@@ -63,7 +63,9 @@ function timestampHms(d) {
 }
 /**
  * 文件名 sanitize：
- * path.basename 剥离目录（防 `../` 穿越），再替换控制字符与路径分隔符；
+ * path.basename 剥离目录（防 `../` 穿越），再替换控制字符、路径分隔符与
+ * win32 非法字符（`<>:"|?*`，NTFS/Win32 API 拒绝，落盘直接 EPERM/EINVAL），
+ * 并剥掉尾部的点与空格（win32 会静默剥离它们，导致落盘名 ≠ originalName）；
  * 空名 / `.` / `..` 视为无效（返回空串由调用方生成兜底名）。
  */
 function sanitizeFileName(name) {
@@ -71,19 +73,20 @@ function sanitizeFileName(name) {
     const chars = [];
     for (const ch of base) {
         const code = ch.charCodeAt(0);
-        // 控制字符与路径分隔符一律替换为下划线（no-control-regex 不允许字面
-        // 控制字符转义出现在正则里，逐字符判断语义等价且无 lint 冲突）。
-        if (code <= 0x1f || code === 0x7f || ch === '/' || ch === '\\') {
+        // 控制字符、路径分隔符与 win32 非法字符一律替换为下划线（no-control-regex
+        // 不允许字面控制字符转义出现在正则里，逐字符判断语义等价且无 lint 冲突）。
+        if (code <= 0x1f || code === 0x7f || '/\\<>:"|?*'.includes(ch)) {
             chars.push('_');
         }
         else {
             chars.push(ch);
         }
     }
-    const sanitized = chars.join('');
-    if (sanitized === '' || sanitized === '.' || sanitized === '..')
+    // 尾部的点与空格：win32 落盘时被静默剥离，提前剥掉保证记录名与磁盘名一致
+    const trimmedEnd = chars.join('').replace(/[. ]+$/, '');
+    if (trimmedEnd === '' || trimmedEnd === '.' || trimmedEnd === '..')
         return '';
-    return sanitized;
+    return trimmedEnd;
 }
 /**
  * 资源扩展名（图片/视频/语音）：优先 MIME 映射，未知时按魔数兜底；

package/dist/bridge/index.d.ts

@@ -36,7 +36,7 @@ export interface CommandContext {
     /**
      * 本轮（装配窗口）全部入站 messageId，`messageId` 是其中最后一条。
      * 只有走入站装配器的路径会填；卡片动作等单消息路径留空，收尾退化为只处理
-     * `messageId`。缺它会导致合并轮次里先到的消息挂着 Typing 不撤（§B8）。
+     * `messageId`。缺它会导致合并轮次里先到的消息挂着 Typing 不撤。
      */
     turnMessageIds?: string[];
 }
@@ -127,7 +127,7 @@ export declare class Bridge {
      */
     private runners;
     /**
-     * Runner 槽位在「活跃运行期间配置变更」时被标 stale（CC-06/P1）：clearRunners() 对
+     * Runner 槽位在「活跃运行期间配置变更」时被标 stale：clearRunners() 对
      * 活跃 cwd 只标 stale、不立即 evict（避免误杀长驻连接），当前 run 结束后由
      * finalizeRun 安全 evict+dispose，下一轮 getRunner 创建新配置的 runner。
      * key 为 `${cwd}\u0000${agentKind}`。
@@ -174,17 +174,17 @@ export declare class Bridge {
     syncActiveApprovalModes(): void;
     /** Per-agent approval-mode settings snapshot from the current config. */
     private approvalModeSettingsFor;
-    /** Get the current runner for a cwd. Used by router for agent-specific commands (P3.2). */
+    /** Get the current runner for a cwd. Used by router for agent-specific commands (.2). */
     getCurrentRunner(cwd: string): AgentRunner;
     /**
      * 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(cwd: string, kind?: AgentKind): boolean;
     /** 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
-     *  唯一捕获点：排队消息在 T0 把 agent+session 钉进 AgentBinding，随任务闭包带到 T1
-     *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移（方案 D4）。 */
+     *  唯一捕获点：排队消息在入队时刻把 agent+session 钉进 AgentBinding，随任务闭包带到执行时刻
+     *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移。 */
     currentBinding(userId: string): AgentBinding;
     /**
      * Clear all cached runner instances. Call after config changes that affect runner config.
@@ -192,7 +192,7 @@ export declare class Bridge {
     clearRunners(): void;
     /**
      * 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.
@@ -354,7 +354,7 @@ export declare class Bridge {
      */
     private createRunSession;
     /**
-     * §9.12 空闲看门狗：单 interval + 截止时间判定（P2-1），普通 run 与 compact
+     * §9.12 空闲看门狗：单 interval + 截止时间判定，普通 run 与 compact
      * 共用同一套兜底。事件到达只 `touch()` 刷新时间戳（无 timer 操作）；静默超过
      * `idleTimeoutMs` 才 finish('idle_timeout') + runner.stop()，让该工作区的串行
      * 队列继续推进（否则一个挂死的 run 永久堵住后续消息）。
@@ -443,7 +443,7 @@ export declare class Bridge {
         nonce: string;
     }): Promise<void>;
     /**
-     * Claude AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接
+     * Claude AskUserQuestion 自定义答案（Other）：自由文本直接
      * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
      */
     handleApprovalAnswerCustom(opts: {

package/dist/bridge/index.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');
@@ -98,7 +98,7 @@ export class Bridge {
      */
     runners = new Map();
     /**
-     * Runner 槽位在「活跃运行期间配置变更」时被标 stale（CC-06/P1）：clearRunners() 对
+     * Runner 槽位在「活跃运行期间配置变更」时被标 stale：clearRunners() 对
      * 活跃 cwd 只标 stale、不立即 evict（避免误杀长驻连接），当前 run 结束后由
      * finalizeRun 安全 evict+dispose，下一轮 getRunner 创建新配置的 runner。
      * key 为 `${cwd}\u0000${agentKind}`。
@@ -150,7 +150,7 @@ export class Bridge {
         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(cwd)) {
@@ -241,13 +241,13 @@ export class Bridge {
                 return undefined;
         }
     }
-    /** Get the current runner for a cwd. Used by router for agent-specific commands (P3.2). */
+    /** 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(cwd, kind = this.config.defaultAgent) {
@@ -255,8 +255,8 @@ export class Bridge {
         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 {
@@ -278,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: 活跃 cwd 不能立即 evict（会误杀长驻连接），但必须标记 stale，
+                // 活跃 cwd 不能立即 evict（会误杀长驻连接），但必须标记 stale，
                 // 否则 finalizeRun 对 workspace-lifetime runner 也不 evict → 下一轮复用旧配置实例。
                 // 这里只标待淘汰，当前 run 结束后由 finalizeRun 安全 evict。
                 for (const kind of [...this.runners.get(cwd).keys()]) {
@@ -294,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.
@@ -535,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）显式打标
@@ -551,8 +551,8 @@ export class Bridge {
                     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
@@ -709,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 闭包）捕获的 cwd
+        // lane 与执行 cwd 同源。消息入队时（index.ts 闭包）捕获的 cwd
         // 作为 cwdOverride 显式传入；执行时若 sessionStore cwd 已被 /cd 等命令改写，
         // 以 lane 为准 —— 否则旧 lane 的排队消息会被 busy-drop 静默丢失。空串视为
         // 未提供（与入队前无 cwd 的兜底语义一致）。
@@ -732,12 +732,12 @@ export class Bridge {
         }
         // 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，2026-10-07 前移）：/new、/cd、/resume 会 bump
         // epoch，该 run 后续 system.init 的 sessionId 写回即判 stale 跳过。
-        // 快照点优先取 binding.sessionEpoch（入队/commit 时刻 T0，与 sessionId 同刻）：
+        // 快照点优先取 binding.sessionEpoch（入队/commit 时刻，与 sessionId 同刻）：
         // 排队消息在「commit 后、开跑前」被 reset 时，执行起点捕获会漏判（epoch 已是
         // bump 后的值）→ 旧 sessionId 被写回复活 reset。无 binding 时回退执行起点捕获，
         // 保持非排队路径（如 /compact）的既有语义。
@@ -761,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,
@@ -790,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 永久堵住后续消息）。
@@ -839,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() 之后。
@@ -914,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({
@@ -955,8 +955,8 @@ 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);
@@ -1028,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' &&
@@ -1121,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 分支。
@@ -1129,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 兜底失真。
@@ -1210,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();
@@ -1299,7 +1299,7 @@ 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 cwd is permanently busy
@@ -1312,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)) {
@@ -1322,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);
@@ -1354,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, {
@@ -1374,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);
@@ -1399,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('任务已结束，审批无法响应');
@@ -1463,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) {
@@ -1599,7 +1599,7 @@ export class Bridge {
                 agentKind,
             },
         });
-        // A6：压缩与普通 run 共用同一套生命周期——注册进 activeRuns（/stop 有对象可停、
+        // 压缩与普通 run 共用同一套生命周期——注册进 activeRuns（/stop 有对象可停、
         // /active 看得见）、挂 §9.12 空闲看门狗、终态后补 reaction。缺任何一环，卡住的
         // 压缩都只能等 runner 级超时，用户既停不掉也看不出它还在跑。
         const activeRun = {
@@ -1845,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 尾部）。
@@ -1884,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 });
                 }

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

@@ -1,8 +1,8 @@
 import type { AgentKind } from '../runner/types.js';
 /**
  * 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
- * 唯一捕获点：排队消息在 T0 把 agent+session 钉进 AgentBinding，随任务闭包带到 T1
- * 执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移（方案 D4）。
+ * 唯一捕获点：排队消息在入队时刻把 agent+session 钉进 AgentBinding，随任务闭包带到执行时刻
+ * 执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移。
  */
 export interface AgentBinding {
     agent: AgentKind;
@@ -51,7 +51,7 @@ export interface QueuedTask {
      * `handleQueueImmediate`).
      */
     editedMessage?: string;
-    /** 入队时刻捕获的 agent+session 绑定（方案 D4），随任务闭包带到执行时刻。 */
+    /** 入队时刻捕获的 agent+session 绑定，随任务闭包带到执行时刻。 */
     binding?: AgentBinding;
 }
 /** Options for enqueue operation */
@@ -70,7 +70,7 @@ export interface EnqueueOptions {
         feishuReplyTo?: string;
         /** Whether the queued task is editable (queue card ✏️ 编辑 button). Defaults to true. */
         editable?: boolean;
-        /** 入队时刻捕获的 agent+session 绑定（方案 D4）。 */
+        /** 入队时刻捕获的 agent+session 绑定。 */
         binding?: AgentBinding;
     };
 }
@@ -90,7 +90,7 @@ export declare class QueueManager {
     /** Per-workspace queued tasks for queue display cards. Key = cwd, value = task list. */
     private queuedTasks;
     /**
-     * P3-5: per-workspace `messageId → QueuedTask` index mirroring `queuedTasks`.
+     * per-workspace `messageId → QueuedTask` index mirroring `queuedTasks`.
      * O(1) lookup for the task-start removal path (replacing the old double
      * `find`+`findIndex` O(N) scan) and for `getQueuedTask`/`removeFromQueue`/
      * `updateQueuedTaskMessage`. The ordered array remains the source of truth
@@ -117,7 +117,7 @@ export declare class QueueManager {
      * identifies one task's execution period for the interrupt bookkeeping in
      * `executingSlot`/`interruptedSlots` — replacing the unowned skip-credit
      * counter, which any settle could consume and which therefore leaked a
-     * re-armed count after repeated resets (see A4 anchor).
+     * re-armed count after repeated resets.
      */
     private slotCounter;
     /**
@@ -141,7 +141,7 @@ export declare class QueueManager {
     /**
      * MessageIds of tasks that have actually begun executing (cancellation check
      * passed, task removed from the queue). Entries are sticky: they remain
-     * after the task settles (A21). `handleQueueImmediate` step 6 uses this to
+     * after the task settles. `handleQueueImmediate` step 6 uses this to
      * distinguish "target was cancelled (never began)" from "target began while
      * the interrupt was in flight" so the final feedback can report the true
      * state instead of telling a running task's user that nothing was
@@ -162,11 +162,11 @@ export declare class QueueManager {
     constructor(isWorkspaceRunning: (cwd: string) => boolean, sendCard: (chatId: string, card: object, opts?: {
         replyTo?: string;
     }) => Promise<string>, updateCard: (messageId: string, card: object) => Promise<void>);
-    /** P3-5: register a queued task in the per-workspace `messageId → task` index. */
+    /** register a queued task in the per-workspace `messageId → task` index. */
     private indexAdd;
-    /** P3-5: drop a task from the per-workspace index by messageId. */
+    /** drop a task from the per-workspace index by messageId. */
     private indexRemove;
-    /** P3-5: O(1) lookup of a queued task by messageId via the index. */
+    /** O(1) lookup of a queued task by messageId via the index. */
     private indexGet;
     /**
      * Enqueue a task into the workspace-level serial queue.
@@ -198,7 +198,7 @@ export declare class QueueManager {
      * state — pending cards enable both, executing/cancelled cards disable
      * both. Centralizing the pair here eliminates the 3-way duplication
      * between `buildQueueStatusCardElements`, `updateQueueCardToExecuting`,
-     * and `updateQueueCardToCancelled` (Clean Code P2-1).
+     * and `updateQueueCardToCancelled` (Clean Code).
      */
     private buildQueueActionButtons;
     /**
@@ -283,7 +283,7 @@ export declare class QueueManager {
      * slot no longer matches the interrupted task's slot, the interrupted task
      * already decremented normally — resetting now would zero the count of the
      * running successor and mark ITS slot interrupted, hiding it from the
-     * queue card (A22).
+     * queue card.
      */
     resetExecutingCount(cwd: string, expectedSlot: number): void;
     /**