lark-remote 0.4.5 → 0.5.1

package/dist/router/index.js

@@ -8,6 +8,7 @@ import { WorkspaceStore } from '../workspace/index.js';
 import { OrderStore } from '../order/index.js';
 import { resolveAlias } from '../order/alias-resolve.js';
 import { diffConfig, setNestedValue } from './config-diff.js';
+import { AGENT_KINDS } from '../runner/types.js';
 import { getLogger } from '../logger/index.js';
 import { stripPlaceholders } from '../inbound/placeholder.js';
 import { clampInt } from '../common/clamp.js';
@@ -262,7 +263,7 @@ const APPROVAL_ACTION_SPECS = {
     },
 };
 // ===========================================================================
-// W2.1 命令名单单一事实源
+// 命令名单单一事实源
 // 直返语义（cardAction 同步返回 toast 给飞书回调，index.ts 控制层据此不经
 // 队列直接处理）与即时语义（绕串行队列 enqueueImmediate，§9.6）正交，两个
 // 独立清单只共享审批命令名来源（APPROVAL_ACTION_SPECS keys）——历史上同一
@@ -339,7 +340,15 @@ export const SESSION_MUTATING_ACTION_CMDS = new Set([
     'ws.use',
     'config.save',
 ]);
-/** W2.8 单源：payload.offset → 钳位 offset（原先 9 处逐字副本）。 */
+/**
+ * 会产生压缩工作的卡片动作（单源）。这类条目占用 lane 时必须自报身份：
+ * 排队卡写明「正在执行: 🗜 Compact」而不是「前面还有 0 条」，并且期间禁用
+ * 「立即执行」——该按钮走 interruptCurrentRun，会连带中断正在跑的压缩
+ * （2026-10-09 线上：Compact 占 lane 期间新消息的排队卡自相矛盾，且按钮
+ * 一点就会杀掉压缩）。同时它们也不允许编辑（预览不是用户文本）。
+ */
+export const COMPACT_ACTION_CMDS = new Set(['compact', 'resume.compact']);
+/** 单源：payload.offset → 钳位 offset（原先 9 处逐字副本）。 */
 function payloadOffset(value) {
     return Math.max(0, Math.trunc(Number(value.offset) || 0));
 }
@@ -358,9 +367,18 @@ function searchQueryFrom(value) {
 }
 /** 卡片 cardAction payload 缺字段的统一报错文案（原先 12 处手写且已漂移出两种前缀）。 */
 const CARD_PAYLOAD_MISSING = '⚠️ 卡片 payload 缺少必要信息';
+/**
+ * 记住并同步刷新的 config 卡片数上限。一次 /config 会话里用户实际会交互的
+ * 卡片只有最近一两张，5 张足够覆盖；无上限会让长跑进程的 Set 随卡片数增长。
+ */
+const MAX_CONFIG_CARDS = 5;
 export class CommandRouter {
-    /** Valid agent kinds — single source of truth for resume.use / resume.page / cmdResume. */
-    static VALID_AGENTS = ['claude', 'codex', 'opencode', 'pi', 'kimi', 'dsh'];
+    /**
+     * Valid agent kinds — single source of truth for resume.use / resume.page /
+     * cmdResume. 名单本体在 `runner/types.ts` 的 AGENT_KINDS（与 AgentKind 类型
+     * 同源），这里只做别名，避免人手抄第二份。
+     */
+    static VALID_AGENTS = AGENT_KINDS;
     sessionStore;
     /** 飞书桥接实例（public：测试直接访问断言，替代 as unknown as）。 */
     bridge;
@@ -394,13 +412,28 @@ export class CommandRouter {
     /** /config 卡片编辑暂存区（public：测试直接读取断言，替代 as unknown as）。 */
     pendingConfig = null;
     /**
-     * Monotonic counter minting unique internal keys for order.exec enqueue
-     * actions. One order card can be clicked many times, so the Feishu card
-     * messageId is 1:N with enqueue actions and must not be reused as the queue
-     * dedup key. Date.now() alone is unsafe (two synchronous calls can share a
-     * millisecond); the counter guarantees uniqueness regardless of timing.
+     * 已见过的 /config 卡片 messageId（有界，最近的在最后）。
+     *
+     * 草稿（pendingConfig）是全局一份：/config 文本命令重开卡片时沿用同一份草稿
+     * （这是既有语义，不改）。但**视图**是每张卡一份 —— 只刷新被点击的那张，其余
+     * 卡片就停在旧视图上：用户在旧卡上看到的和点保存实际提交的是两套内容
+     * （2026-10-08 发现的缺陷）。这里记住所有交互过的 config 卡，任何一次编辑/保存
+     * 后把草稿刷到每张卡，保证「看到的就是会保存的」。
      */
-    orderExecKeyCounter = 0;
+    configCardIds = new Set();
+    /**
+     * 排队条目身份 key 的唯一铸造计数器（order.exec 与卡片动作共用）。
+     *
+     * 一张飞书卡片可以被点击 N 次，卡片 messageId 与入队动作是 1:N；而排队
+     * 条目的身份必须与「一次入队动作」1:1（queuedTasks 的定位、queueCardMessages
+     * 的卡片更新、taskIndex 的取消判据全部按这个 key 做 lookup）。复用卡片 id
+     * 会让同 key 的多条任务互相顶替：位置显示命中最早那条兄弟、第一条开始时删掉
+     * 索引导致其余兄弟被判「已撤销」静默丢弃（2026-10-08 线上：连点 Compact
+     * 三次 → 三张排队卡都显示「第 1 位」、两张永久停在「等待中」，只压缩一次）。
+     *
+     * Date.now() 不够（两次同步调用可落在同一毫秒）；计数器与时间无关，恒唯一。
+     */
+    queueTaskKeyCounter = 0;
     /**
      * Per-user sort preference for /ws list (memory-only, not persisted).
      * Default 'recent' (most recently used first), can toggle to 'alpha'.
@@ -466,7 +499,7 @@ export class CommandRouter {
     /**
      * Route a message: if it starts with /, handle as command; if it starts with !, execute as bash; otherwise forward to Claude.
      *
-     * 命令识别前置条件（2026-09-15 P0 修复，`inbound-unified-input-design.md` §5.6）：
+     * 命令识别前置条件（2026-09-15修复，`inbound-unified-input-design.md` §5.6）：
      * 裸前缀判定会被结构占位符命中 —— SDK 把富文本里的图片渲染成 `![image](img_v3_…)`，
      * 首字符恰好是 `!`，整段用户消息被当 shell 命令执行（`executeBash "[image](img_v3_…"`）。
      * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
@@ -513,7 +546,7 @@ export class CommandRouter {
             await this.bridge.executeBash(cmd, ctx);
             return null;
         }
-        // Forward to Claude (P1-14: pass the enqueue-time cwd through so the
+        // Forward to Claude (pass the enqueue-time cwd through so the
         // run uses the same cwd as the serial queue lane, even if /cd ran while
         // the message was queued)
         // 剥离占位符后再转发：agent 只该看到用户文本（附图已转成 attachments 块，
@@ -538,7 +571,7 @@ export class CommandRouter {
      * Validates payload and dispatches to the corresponding command.
      */
     async handleCardAction(value, ctx) {
-        // W2.1：审批家族以 APPROVAL_ACTION_SPECS keys 为单一来源分发
+        // 审批家族以 APPROVAL_ACTION_SPECS keys 为单一来源分发
         // （原 7 个 case 与 spec keys 是同一份知识的两份拷贝，已两次漂移）。
         if (APPROVAL_ACTION_CMDS.includes(value.cmd)) {
             return this.handleApprovalAction(value, ctx);
@@ -584,7 +617,7 @@ export class CommandRouter {
                     await this.bridge.sendResult({ text: '请先 /cd 设置工作目录' }, ctx);
                     return;
                 }
-                // P1-5：校验前不得写入 sessionId。旧实现先无条件 setSessionId 再调
+                // 校验前不得写入 sessionId。旧实现先无条件 setSessionId 再调
                 // cmdResume 校验，过期卡片（session 不在当前 cwd）校验失败时 store 已被
                 // 污染；value.sessionId 缺失时还会静默清空已有绑定。现在统一走 cmdResume
                 // 的已验证路径（:2352 校验通过才写入），sessionId 缺失直接报错。
@@ -759,12 +792,21 @@ export class CommandRouter {
         if (!targetTask) {
             // The target already began (or was cancelled) before this handler ran. We
             // must NOT claim the queue was cleared — nothing is removed in this branch
-            // and tasks queued behind the target are still waiting (see A13).
+            // and tasks queued behind the target are still waiting.
             await this.bridge.sendResult({
                 text: '该消息已不在队列中（可能已开始执行或被撤销），无法立即执行。其余排队消息保持原状。',
             }, ctx);
             return;
         }
+        // Compact 占 lane 时拒绝「立即执行」。该动作会调 interruptCurrentRun，而它
+        // 遍历 activeRuns 时会一并中断正在跑的压缩（压缩也注册在 activeRuns 里）。
+        // 渲染层已把按钮置灰，这里是旧卡片的兜底：改动前渲染的卡仍带可点的按钮。
+        // 放在存在性检查之后：目标已失效时，上一条「不在队列中」的反馈更准确。
+        const laneOccupant = this.bridge.getQueueExecutingInfo(cwd);
+        if (laneOccupant?.kind === 'compact') {
+            await this.bridge.sendResult({ text: '⚠️ 正在压缩会话，消息将在压缩完成后按顺序执行。' }, ctx);
+            return;
+        }
         // 1.5. If the user edited the message, the original closure (captured at
         // enqueue time with stale content) must NOT run. Register a one-shot
         // replacement closure on the task's EXISTING queue slot BEFORE any await:
@@ -777,7 +819,7 @@ export class CommandRouter {
         // which would put the edited task behind tasks queued after it.
         if (targetTask.editedMessage) {
             const editedContent = targetTask.editedMessage;
-            // D3/Step3: 替换闭包复用原任务的 binding（不重新快照）+ 恢复丢失的
+            ///Step3: 替换闭包复用原任务的 binding（不重新快照）+ 恢复丢失的
             // cwdOverride（lane cwd 同源）。否则编辑后重新执行的 run 会丢 cwd 与绑定。
             this.bridge.setTaskReplacement(cwd, messageId, async () => {
                 await this.handle(editedContent, ctx, {
@@ -834,7 +876,7 @@ export class CommandRouter {
         const latestTask = this.bridge.getQueuedTask(cwd, messageId);
         if (latestTask?.editedMessage) {
             const editedContent = latestTask.editedMessage;
-            // D3/Step3: 复用原任务 binding + 恢复 cwdOverride（同上）。
+            ///Step3: 复用原任务 binding + 恢复 cwdOverride（同上）。
             this.bridge.setTaskReplacement(cwd, messageId, async () => {
                 await this.handle(editedContent, ctx, {
                     cwdOverride: cwd,
@@ -1049,7 +1091,7 @@ export class CommandRouter {
         // setTaskReplacement and the begin-path consumption are synchronous, so
         // there is no interleaving window.
         //
-        // D3/Step3：复用原任务 binding（不重新快照）+ 恢复 cwdOverride。
+        ///Step3：复用原任务 binding（不重新快照）+ 恢复 cwdOverride。
         const inputTask = this.bridge.getQueuedTask(cwd, messageId);
         if (!inputTask) {
             // Task already left the queue (began or was cancelled) before we could
@@ -1155,7 +1197,7 @@ export class CommandRouter {
     async handleLsRefresh(value, ctx) {
         const targetPath = value.path;
         const offset = value.offset ?? 0;
-        // TOCTOU guard (review P2-2): existsSync → statSync can race (target
+        // TOCTOU guard: existsSync → statSync can race (target
         // deleted in between), throwing into enqueueImmediate's catch which only
         // logs — violating the "card button clicks must give visible feedback"
         // red line. Treat a vanished/non-dir path as "use current cwd" instead of
@@ -1185,7 +1227,7 @@ export class CommandRouter {
             return { toast: { type: 'error', content: paging.error } };
         }
         const resolvedTarget = path.resolve(targetPath);
-        // TOCTOU guard (review P2-2): existsSync → statSync can race; without the
+        // TOCTOU guard: existsSync → statSync can race; without the
         // try/catch the throw lands in enqueueImmediate's silent .catch and the
         // paginated card never updates (no visible feedback for the click).
         let isDir;
@@ -1208,7 +1250,7 @@ export class CommandRouter {
      *
      * offset 恒重置为 0（新筛选从第 1 页开始）。路径校验与 TOCTOU 兜底照
      * handleLsPage——校验失败只回错误 toast，绝不动卡片（否则用户看到一张空卡）。
-     * ls.browse / ls.switch 的 value 里刻意不带 q，换目录即清除筛选（设计文档 §2.3）。
+     * ls.browse / ls.switch 的 value 里刻意不带 q，换目录即清除筛选。
      */
     async handleLsFilter(value, ctx) {
         const targetPath = value.path;
@@ -1348,11 +1390,25 @@ export class CommandRouter {
         this.orderStore.updateUsedAt(order.id);
         return {
             orderText: order.text,
-            internalKey: `order-${order.id}-${this.orderExecKeyCounter++}`,
+            internalKey: this.mintQueueTaskKey('order', order.id),
         };
     }
     /**
-     * W2.8 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
+     * 铸造一个排队条目身份 key（唯一铸造点）。
+     *
+     * 调用方：order.exec 文本钩子（resolveOrderExecForQueue）与入口层
+     * （index.ts）的非即时卡片动作入队。卡片 messageId 只能当「回复目标」
+     * （`taskMeta.feishuReplyTo`），不得当队列 key —— 理由见
+     * `queueTaskKeyCounter` 字段注释。
+     */
+    mintQueueTaskKey(kind, id) {
+        this.queueTaskKeyCounter += 1;
+        return id === undefined
+            ? `queue-${kind}-${this.queueTaskKeyCounter}`
+            : `${kind}-${id}-${this.queueTaskKeyCounter}`;
+    }
+    /**
+     * 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
      * `q` 只服务 ws 卡的关键词筛选；order 卡无此功能，不透传。
      */
     rebuildListCard(kind, offset, ctx, q) {
@@ -1361,7 +1417,7 @@ export class CommandRouter {
         return this.cmdWs([], ctx, offset, q).card;
     }
     /**
-     * W2.8 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
+     * 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
      * 翻页/移除/排序/筛选动作共用）。返回重建后的卡片；无卡时返回 undefined 且跳过更新。
      */
     async refreshListCard(kind, value, ctx) {
@@ -1372,7 +1428,7 @@ export class CommandRouter {
         return card;
     }
     /**
-     * W2.8 单源：order 三个 input handler（aliasInput/aliasRemove/textInput）
+     * 单源：order 三个 input handler（aliasInput/aliasRemove/textInput）
      * 的公共骨架——校验 orderId → reload+find → mutate → 成功后 toast + raw 卡。
      * mutate 返回 error 时仅回 error toast，不重渲染。
      * 注意：本 helper 只服务「toast + card 进响应体」语义（飞书需用响应体原地
@@ -1742,6 +1798,44 @@ export class CommandRouter {
             this.pendingConfig = structuredClone(this.config);
         }
     }
+    /**
+     * 记住一张 config 卡片 messageId（有界：超限丢最早的一张）。
+     * 无 messageId 的调用（测试/文本路径）不登记。
+     */
+    rememberConfigCard(messageId) {
+        if (!messageId)
+            return;
+        this.configCardIds.delete(messageId);
+        this.configCardIds.add(messageId);
+        while (this.configCardIds.size > MAX_CONFIG_CARDS) {
+            const oldest = this.configCardIds.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.configCardIds.delete(oldest);
+        }
+    }
+    /**
+     * 把当前草稿刷到所有已知 config 卡片上（含本次点击的那张）。
+     *
+     * 被点击的那张走 `updateCardInPlace`（失败 fallback 发新卡，保证点击必有
+     * 反馈）；其余兄弟卡走 `patchCard`（纯 best-effort，失败即从集合剔除，不再
+     * 重复打无效 PATCH，也不会因为卡片过期而反复补发新卡）。
+     */
+    async refreshConfigCards(ctx) {
+        this.rememberConfigCard(ctx.messageId);
+        const card = this.buildConfigCard().card;
+        if (!card)
+            return;
+        for (const messageId of [...this.configCardIds]) {
+            if (messageId === ctx.messageId) {
+                await this.bridge.updateCardInPlace(card, ctx);
+                continue;
+            }
+            const ok = await this.bridge.patchCard(messageId, card);
+            if (!ok)
+                this.configCardIds.delete(messageId);
+        }
+    }
     /**
      * 串行化 config.* 卡片回调（2026-07-04 修复 toggle 卡死 bug）。
      *
@@ -1786,7 +1880,7 @@ export class CommandRouter {
                 try {
                     // 只改暂存区，不写盘；原地更新卡片而非发送新卡（2026-07-04）
                     this.setNestedValue(this.pendingConfig, key, !boolVal);
-                    await this.bridge.updateCardInPlace(this.buildConfigCard().card, ctx);
+                    await this.refreshConfigCards(ctx);
                 }
                 catch (err) {
                     await this.bridge.sendResult({ text: `设置失败: ${err.message}` }, ctx);
@@ -1810,7 +1904,7 @@ export class CommandRouter {
                     for (const patch of patches) {
                         this.setNestedValue(this.pendingConfig, patch.key, patch.value);
                     }
-                    await this.bridge.updateCardInPlace(this.buildConfigCard().card, ctx);
+                    await this.refreshConfigCards(ctx);
                 }
                 catch (err) {
                     await this.bridge.sendResult({ text: `设置失败: ${err.message}` }, ctx);
@@ -1841,7 +1935,7 @@ export class CommandRouter {
                     for (const patch of patches) {
                         this.setNestedValue(this.pendingConfig, patch.key, patch.value);
                     }
-                    await this.bridge.updateCardInPlace(this.buildConfigCard().card, ctx);
+                    await this.refreshConfigCards(ctx);
                 }
                 catch (err) {
                     await this.bridge.sendResult({ text: `设置失败: ${err.message}` }, ctx);
@@ -1863,7 +1957,7 @@ export class CommandRouter {
                 try {
                     const oldDefaultAgent = this.config.defaultAgent;
                     this.config = setConfigValues(this.configPath, this.config, updates);
-                    // P1-6：运行时传播（idleTimeout / clearRunners / syncAgentChoices /
+                    // 运行时传播（idleTimeout / clearRunners / syncAgentChoices /
                     // defaultAgent 切换的 session 处理）抽到共享方法，与文本直写路径共用。
                     const switchResult = this.propagateConfigSave(oldDefaultAgent, updates, ctx);
                     this.pendingConfig = null;
@@ -1873,7 +1967,7 @@ export class CommandRouter {
                     try {
                         // host 可能已变更 → 重新预取 DSH 目录（内部按 host 缓存，未变不重复拉）
                         await this.prefetchConfigCardCatalogs();
-                        await this.bridge.updateCardInPlace(this.buildConfigCard().card, ctx);
+                        await this.refreshConfigCards(ctx);
                     }
                     catch (refreshErr) {
                         getLogger().warn(`[router] config.save 卡片刷新失败（保存已成功）: ${refreshErr.message}`);
@@ -1909,7 +2003,7 @@ export class CommandRouter {
         return diffConfig(original, pending);
     }
     /**
-     * config 写盘后的运行时传播（P1-6：自 config.save 卡片路径抽出，卡片保存与
+     * config 写盘后的运行时传播（自 config.save 卡片路径抽出，卡片保存与
      * `/config <key> <value>` 文本直写两条路径共用）。
      *
      * 1. bridge 运行时值同步：setConfig + idle watchdog timeout；
@@ -1917,7 +2011,7 @@ export class CommandRouter {
      *    配置值，/status 与真实 run 自相矛盾）；
      * 3. defaultAgent 切换 → 旧 agent session 存 previousSessions、新 agent 恢复
      *    或清空（等效 /new）；
-     * 4. 当前 agent 配置变更 → syncAgentChoices 并原子写盘（P1-7：禁裸同步写盘，
+     * 4. 当前 agent 配置变更 → syncAgentChoices 并原子写盘（禁裸同步写盘，
      *    写一半崩溃会截断 config.yaml 导致 bridge 起不来）。
      *
      * @param updates 以 config 路径形式给出的变更 key（卡片路径来自 diffConfig；
@@ -1991,7 +2085,7 @@ export class CommandRouter {
                 switchSessionId = '';
             }
         }
-        // DSH preset 变更 = 下次 run 新建 session（§4.3 D1）：
+        // DSH preset 变更 = 下次 run 新建 session（§4.3）：
         // preset 在 session 创建时固定，中途切换会被服务端拒绝（agent-preset-conflict）。
         // 旧 sessionId 存入 previousSessions 停车位（可手动 /resume，但 /resume 会做
         // preset 一致性校验），当前 sessionId 清空——下次 run 走 session.create 新建。
@@ -2009,7 +2103,7 @@ export class CommandRouter {
                 switchNotice = `DSH preset 已变更，下次消息将新建会话`;
             }
         }
-        // DSH host 变更 = 换服务（CC-02）：旧 host 的 sessionId 发往新 host 是错的。
+        // DSH host 变更 = 换服务：旧 host 的 sessionId 发往新 host 是错的。
         // 视为 session 边界，仿 preset 分支停车 + 清空当前 sessionId，下次 run 新建会话。
         const hasDshHostChange = Object.keys(updates).some((k) => k === 'agents.dsh.host');
         if (hasDshHostChange && this.config.defaultAgent === 'dsh' && !switchNotice) {
@@ -2029,11 +2123,11 @@ export class CommandRouter {
         const hasCurrentAgentUpdate = Object.keys(updates).some((k) => k === currentAgentConfigKey || k.startsWith(`${currentAgentConfigKey}.`));
         if (hasCurrentAgentUpdate) {
             this.config = syncAgentChoices(this.config, currentAgent);
-            // P1-7：agentChoices 同步写盘必须走原子写（tmp+rename），禁裸同步写盘
+            // agentChoices 同步写盘必须走原子写（tmp+rename），禁裸同步写盘
             atomicWrite(this.configPath, YAML.stringify(this.config));
             this.bridge.setConfig(this.config);
         }
-        // P1-6 + live approval settings (§P5): active workspace-lifetime runners
+        // live approval settings: active workspace-lifetime runners
         // are not evicted by clearRunners() (would orphan the live subprocess).
         // Push the new approval-mode settings to those runners via the unified
         // duck method `updateApprovalMode` (codex thread/settings/update,
@@ -2446,7 +2540,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         // Claude writes into JSONL (e.g. `/tmp` → `/private/tmp` on macOS).
         // Without this, a hand-typed unresolved path never matches any JSONL's
         // cwd field and the user's `/cd /tmp/foo` never finds their sessions.
-        // TOCTOU: the directory may vanish between stat and realpath (review P2-1).
+        // TOCTOU: the directory may vanish between stat and realpath.
         // Reject gracefully instead of letting realpathSync throw into the queue
         // task's .catch (which only logs — the user gets no feedback). Mirrors
         // handleLsSwitch's realpath guard so /cd and ls.switch behave identically.
@@ -2503,7 +2597,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
      */
     switchCwdAndNotify(userId, canonical, _ctx) {
         this.sessionStore.setCwd(userId, canonical);
-        // Auto-resume newest session if exists (P1-15: 读取失败不阻断切换，给可见提示)
+        // Auto-resume newest session if exists (读取失败不阻断切换，给可见提示)
         let newestSession;
         try {
             newestSession = this.sessionReader.getNewestSession(canonical);
@@ -2634,7 +2728,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
     }
     /**
      * Whether a session of the given agent kind can be compacted from a resume
-     * card. Design doc §6.2-2: duck-typing — check if the runner has `runCompact`
+     * card. duck-typing — check if the runner has `runCompact`
      * (codex app-server, kimi acp), instead of hardcoding agentKind === 'codex'.
      */
     canCompactSession(agentKind, cwd) {
@@ -3111,7 +3205,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 if (!fs.existsSync(wsPath))
                     return { text: `路径不存在: ${wsPath}` };
                 // Canonicalize via realpath so it matches Claude JSONL cwd (2026-06-21).
-                // TOCTOU guard (review P2-1): mirror cmdCd — if the path vanishes
+                // TOCTOU guard: mirror cmdCd — if the path vanishes
                 // between existsSync and realpath, reply gracefully instead of
                 // throwing into the queue task's silent .catch.
                 let canonical;
@@ -3332,7 +3426,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         }
     }
     /**
-     * L3: degraded card when a session's export is non-empty but unparseable
+     * degraded card when a session's export is non-empty but unparseable
      * (truncated by opencode's pipe cap on huge sessions, or otherwise corrupt).
      * The session exists, so reuse listSessions metadata (title) instead of the
      * misleading "未找到". Reuses the same card-builder helpers (markdownDiv) as
@@ -3427,7 +3521,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                     };
                 }
             }
-            // L3: 校验通过后才写入
+            // 校验通过后才写入
             this.sessionStore.setSessionId(ctx.userId, agentKind, sessionIdArg, cwd);
             const { events: content, usage, isActive, aiTitle, recap, displayTitle, activeRunRunId, } = this.readSessionDisplayState(sessionIdArg, cwd, {
                 agentKind,
@@ -3490,7 +3584,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             }
         }
         catch (err) {
-            // P1-15: 读取失败必须给用户可见反馈，而不是误导性的「没有 session 记录」
+            // 读取失败必须给用户可见反馈，而不是误导性的「没有 session 记录」
             const msg = err instanceof Error ? err.message : String(err);
             return { text: `读取 ${agentDisplayName(agentKind)} session 列表失败: ${msg}` };
         }
@@ -3562,7 +3656,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             const prefetchedTitle = meta?.displayTitle;
             // aiTitle 不能单独作为"预取标题"键：若 displayTitle 缺失（理论上 opencode
             // info.title 非空但 export 无 user text），标题兜底是 summary，label 必须
-            // 是中性"会话摘要"而不是"最近输入"（Review R3 P2-1 边缘分支）。
+            // 是中性"会话摘要"而不是"最近输入"（Review 边缘分支）。
             const titleText = prefetchedTitle ?? (summaryIsPlaceholder ? '' : s.summary);
             const titleLabel = prefetchedTitle
                 ? meta?.aiTitle
@@ -3727,7 +3821,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 elements.push({ tag: 'hr' });
             }
         }
-        // Pagination bar（W2.9 复用 paginationBar：safeOffset 已对齐页边界，
+        // Pagination bar（复用 paginationBar：safeOffset 已对齐页边界，
         // offset±pageSize 与原先 currentPage±1 的页码换算等价）
         if (totalPages > 1) {
             elements.push(...paginationBar({
@@ -3763,14 +3857,14 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
             const value = args.slice(1).join(' ');
             try {
                 const oldDefaultAgent = this.config.defaultAgent;
-                // P2-23：直写前若 pendingConfig 存在未保存差异，提示用户被丢弃的条数，
+                // 直写前若 pendingConfig 存在未保存差异，提示用户被丢弃的条数，
                 // 避免静默清空导致用户在卡片上的修改无反馈丢失。差异必须在 setConfigValue
                 // 之前计算——直写本身也会改变 config，不应计入「被丢弃的未保存修改」。
                 const discarded = this.pendingConfig
                     ? Object.keys(this.diffConfig(this.config, this.pendingConfig)).length
                     : 0;
                 this.config = setConfigValue(this.configPath, this.config, key, value);
-                // P1-6：直写路径与 config.save 卡片路径共用运行时传播（idleTimeout /
+                // 直写路径与 config.save 卡片路径共用运行时传播（idleTimeout /
                 // clearRunners / syncAgentChoices / defaultAgent 切换）。key 经 mapAgentKey
                 // 归一化，pi./codex./opencode./kimi. 命中 agents.* 判定；claude. 与
                 // defaultAgent 不再漏判。

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

@@ -23,7 +23,7 @@ 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);
@@ -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/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.js

@@ -127,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

@@ -53,7 +53,7 @@ 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）为界，而不是进程退出。
  */
@@ -138,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 流程「等进程退出再收尾」