lark-remote 0.4.4 → 0.5.0

package/dist/router/index.js

@@ -10,11 +10,14 @@ import { resolveAlias } from '../order/alias-resolve.js';
 import { diffConfig, setNestedValue } from './config-diff.js';
 import { getLogger } from '../logger/index.js';
 import { stripPlaceholders } from '../inbound/placeholder.js';
-import { activeRunUsage, clampInt } from './utils.js';
+import { clampInt } from '../common/clamp.js';
+import { activeRunUsage } from './usage-format.js';
 import { markdownDiv, buildSessionHistoryCard, paginationBar, searchBar, parseJumpOffset, SEARCH_INPUT_NAME, PAGE_JUMP_INVALID_HINT, } from './card-helpers.js';
 import { MAX_FILE_UPLOAD_SIZE } from '../connector/file-limits.js';
+import { newSessionButton, resumeCompactButton, agentDisplayName } from '../card/card-shared.js';
+import { displayName } from '../platform/path.js';
 import { atomicWrite } from '../persistence/atomic-write.js';
-import { checkLatestVersion as defaultCheckLatestVersion, isNewer as defaultIsNewer, runInstallLatest as defaultRunInstallLatest, } from '../update/index.js';
+import { checkLatestVersion as defaultCheckLatestVersion, compareVersions as defaultCompareVersions, runInstallLatest as defaultRunInstallLatest, } from '../update/index.js';
 /** Config card builder - delegates to per-agent builders */
 import { getConfigBuilder, listRegisteredAgents, sortAgentsForDisplay } from './config/index.js';
 import { probeAllAgents, getCachedAvailability } from '../runner/probe.js';
@@ -128,8 +131,6 @@ const RESUME_CONTENT_PREFETCH = 5;
  * `New Session`、空串），都不是真实输入，不得渲染成行标题。
  */
 const RESUME_SUMMARY_PLACEHOLDERS = new Set(['', '(no user message)', '(无摘要)', 'New Session']);
-import { newSessionButton, resumeCompactButton, agentDisplayName } from '../card/card-shared.js';
-import { displayName } from '../platform/path.js';
 /**
  * Card-action commands that must run with enqueue({ immediate: true }).
  * These bypass the serial queue and execute immediately.
@@ -145,7 +146,7 @@ import { displayName } from '../platform/path.js';
  * stop        — interrupt current run
  * ls.file     — send file only
  * ws.page     — paginate /ws list only
- * ws.remove   — delete workspace alias only
+ * ws.remove   — delete cwd alias only
  * resume.use  — set sessionId + agent for correct reader routing
  * help.*      — read-only help commands
  * order.delete — delete order only
@@ -261,7 +262,7 @@ const APPROVAL_ACTION_SPECS = {
     },
 };
 // ===========================================================================
-// W2.1 命令名单单一事实源
+// 命令名单单一事实源
 // 直返语义（cardAction 同步返回 toast 给飞书回调，index.ts 控制层据此不经
 // 队列直接处理）与即时语义（绕串行队列 enqueueImmediate，§9.6）正交，两个
 // 独立清单只共享审批命令名来源（APPROVAL_ACTION_SPECS keys）——历史上同一
@@ -320,7 +321,25 @@ const IMMEDIATE_ACTION_CMDS = new Set([
     // coordinator 已删响应空转（线上复现：approval.respond 排队卡、审批永不生效）。
     ...APPROVAL_ACTION_CMDS,
 ]);
-/** W2.8 单源：payload.offset → 钳位 offset（原先 9 处逐字副本）。 */
+/**
+ * 会话 / cwd / agent 变更类卡片动作（单源）。这些动作会改写 sessionStore 的
+ * sessionId / cwd / defaultAgent，必须与入站装配器的 700ms 静默窗口定序：
+ * 控制层（index.ts）在执行它们之前先 flush 该 user/chat 的装配窗口，保证窗口内
+ * 先到的文本消息在本动作之前 commit（绑定动作前的旧状态）。否则窗口内消息会
+ * 漂移到动作之后的新状态（2026-10-07 事故：输入「重新构建」后立即点「新会话」，
+ * 消息落到新会话）。
+ *
+ * 文本命令（/new、/cd、/resume、/config）已由 index.ts 命令分支先 flush，
+ * 不在此列——只有卡片动作绕过了该分支。
+ */
+export const SESSION_MUTATING_ACTION_CMDS = new Set([
+    'new-session',
+    'resume.use',
+    'ls.switch',
+    'ws.use',
+    'config.save',
+]);
+/** 单源：payload.offset → 钳位 offset（原先 9 处逐字副本）。 */
 function payloadOffset(value) {
     return Math.max(0, Math.trunc(Number(value.offset) || 0));
 }
@@ -426,7 +445,7 @@ export class CommandRouter {
         this.cloneSession = opts.cloneSession;
         this.updateFns = {
             checkLatestVersion: opts.updateFns?.checkLatestVersion ?? defaultCheckLatestVersion,
-            isNewer: opts.updateFns?.isNewer ?? defaultIsNewer,
+            compareVersions: opts.updateFns?.compareVersions ?? defaultCompareVersions,
             runInstallLatest: opts.updateFns?.runInstallLatest ?? defaultRunInstallLatest,
         };
     }
@@ -447,7 +466,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 修复）：
+     * 命令识别前置条件（2026-09-15修复，`inbound-unified-input-design.md` §5.6）：
      * 裸前缀判定会被结构占位符命中 —— SDK 把富文本里的图片渲染成 `![image](img_v3_…)`，
      * 首字符恰好是 `!`，整段用户消息被当 shell 命令执行（`executeBash "[image](img_v3_…"`）。
      * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
@@ -494,7 +513,7 @@ export class CommandRouter {
             await this.bridge.executeBash(cmd, ctx);
             return null;
         }
-        // Forward to Claude (P1-14: pass the enqueue-time workspace 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 块，
@@ -519,7 +538,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);
@@ -565,7 +584,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 缺失直接报错。
@@ -635,8 +654,8 @@ export class CommandRouter {
                 // 调 updateCardInPlace → Feishu API 乱序到达导致 toggle 卡死。
                 // 2026-07-18: 返回 enqueueConfigAction 的结果以支持 toast 响应
                 return this.enqueueConfigAction(value, ctx);
-            case 'codex.compact':
-                await this.bridge.handleCodexCompact(value, ctx);
+            case 'compact':
+                await this.bridge.handleCompactAction(value, ctx);
                 return;
             case 'resume.compact':
                 await this.bridge.handleResumeCompact(value, ctx);
@@ -672,13 +691,13 @@ export class CommandRouter {
      * Routes to the appropriate bridge method based on value.cmd.
      * Returns a toast response for immediate user feedback.
      */
-    /** queue.* 卡片动作通用守卫：workspace/messageId 缺失时回复错误并返回 null。 */
+    /** queue.* 卡片动作通用守卫：cwd/messageId 缺失时回复错误并返回 null。 */
     async queuePayloadOrReply(value, ctx) {
-        if (!value.workspace || !value.messageId) {
+        if (!value.cwd || !value.messageId) {
             await this.bridge.sendResult({ text: CARD_PAYLOAD_MISSING }, ctx);
             return null;
         }
-        return { workspace: value.workspace, messageId: value.messageId };
+        return { cwd: value.cwd, messageId: value.messageId };
     }
     /** 答案类操作的统一失败反馈：重复投递（同一 nonce 第二次点击）是已生效的
      *  中性事件，报 error 会误导（首次点击实际已成功）。 */
@@ -712,11 +731,11 @@ export class CommandRouter {
         const payload = await this.queuePayloadOrReply(value, ctx);
         if (!payload)
             return;
-        const { workspace, messageId } = payload;
-        const removed = this.bridge.removeFromQueue(workspace, messageId);
+        const { cwd, messageId } = payload;
+        const removed = this.bridge.removeFromQueue(cwd, messageId);
         if (removed) {
             // Update the queue card in-place to "cancelled" state
-            await this.bridge.updateQueueCardToCancelled(workspace, messageId);
+            await this.bridge.updateQueueCardToCancelled(cwd, messageId);
             // Send a brief confirmation (user can see the card has been updated)
             await this.bridge.sendResult({ text: '✅ 已从队列中撤销' }, ctx);
         }
@@ -732,15 +751,15 @@ export class CommandRouter {
         const payload = await this.queuePayloadOrReply(value, ctx);
         if (!payload)
             return;
-        const { workspace, messageId } = payload;
+        const { cwd, messageId } = payload;
         // 1. Check target exists BEFORE any await. The queue chain can advance
         // while later awaits (interruptCurrentRun / markQueueCardExecuting's card
         // send) are in flight, so the target must be read synchronously at entry.
-        const targetTask = this.bridge.getQueuedTask(workspace, messageId);
+        const targetTask = this.bridge.getQueuedTask(cwd, messageId);
         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);
@@ -758,11 +777,11 @@ 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(workspace, messageId, async () => {
+            this.bridge.setTaskReplacement(cwd, messageId, async () => {
                 await this.handle(editedContent, ctx, {
-                    cwdOverride: workspace,
+                    cwdOverride: cwd,
                     binding: targetTask.binding,
                 });
             });
@@ -773,7 +792,7 @@ export class CommandRouter {
         const stopped = await this.bridge.interruptCurrentRun({
             userId: ctx.userId,
             chatId: ctx.chatId,
-            workspace,
+            cwd,
         });
         getLogger().info(`[router] queue.immediate: stopped=${stopped}`);
         // 3. Remove all tasks BEFORE this one (by position in the current queue).
@@ -781,7 +800,7 @@ export class CommandRouter {
         // advances concurrently): then it is already out of the snapshot and every
         // remaining queued task is BEHIND it — clearing must stop, not run off the
         // end and delete tasks queued after the target.
-        const tasks = this.bridge.getQueuedTasks(workspace);
+        const tasks = this.bridge.getQueuedTasks(cwd);
         const targetIdx = tasks.findIndex((t) => t.messageId === messageId);
         let removedCount = 0;
         const removedIds = [];
@@ -792,7 +811,7 @@ export class CommandRouter {
         // in flight.
         for (let i = 0; i < targetIdx; i++) {
             const task = tasks[i];
-            if (this.bridge.removeFromQueue(workspace, task.messageId)) {
+            if (this.bridge.removeFromQueue(cwd, task.messageId)) {
                 removedCount++;
                 removedIds.push(task.messageId);
             }
@@ -804,7 +823,7 @@ export class CommandRouter {
         // target are already gone, so any chain advance can only reach the target
         // itself — the card updates may safely run in the background.
         for (const removedId of removedIds) {
-            void this.bridge.updateQueueCardToCancelled(workspace, removedId);
+            void this.bridge.updateQueueCardToCancelled(cwd, removedId);
         }
         // 4. DO NOT remove the target task - keep it in queue to execute immediately
         // The queue will naturally execute it after the current task (which we just stopped)
@@ -812,13 +831,13 @@ export class CommandRouter {
         // re-registering over the same slot). Covers the user editing the message
         // again while interruptCurrentRun was awaiting; skipped automatically once
         // the task has begun, because getQueuedTask then returns undefined.
-        const latestTask = this.bridge.getQueuedTask(workspace, messageId);
+        const latestTask = this.bridge.getQueuedTask(cwd, messageId);
         if (latestTask?.editedMessage) {
             const editedContent = latestTask.editedMessage;
-            // D3/Step3: 复用原任务 binding + 恢复 cwdOverride（同上）。
-            this.bridge.setTaskReplacement(workspace, messageId, async () => {
+            ///Step3: 复用原任务 binding + 恢复 cwdOverride（同上）。
+            this.bridge.setTaskReplacement(cwd, messageId, async () => {
                 await this.handle(editedContent, ctx, {
-                    cwdOverride: workspace,
+                    cwdOverride: cwd,
                     binding: latestTask.binding,
                 });
             });
@@ -826,9 +845,9 @@ export class CommandRouter {
         // 4.5/6. The target must only be marked executing (and the toast may only
         // promise immediate execution) when it is really the next task after the
         // stop. While interruptCurrentRun was awaiting, a task ahead of the target
-        // may have begun and now occupy the workspace — the target is still queued
+        // may have begun and now occupy the cwd — the target is still queued
         // but is NOT next, so its card must stay queued and the toast must say so.
-        const targetStillQueued = this.bridge.getQueuedTask(workspace, messageId) !== undefined;
+        const targetStillQueued = this.bridge.getQueuedTask(cwd, messageId) !== undefined;
         if (!targetStillQueued) {
             // The target began or was cancelled while earlier awaits were in flight —
             // a success toast must never promise execution of a task that will not
@@ -847,14 +866,14 @@ export class CommandRouter {
             }
             return;
         }
-        const workspaceBusy = this.bridge.isBusyFor(workspace);
+        const workspaceBusy = this.bridge.isBusyFor(cwd);
         if (!workspaceBusy) {
             // Normal path: nothing new began during the stop, the target is next.
             // Mark its own card as executing now so buttons grey out immediately.
             // Done BEFORE any removal so getQueuedTask still returns the task with
             // its (possibly edited) messagePreview for the card. The queue callback's
             // later updateQueueCardToExecuting call becomes a no-op (idempotent).
-            await this.bridge.markQueueCardExecuting(workspace, messageId);
+            await this.bridge.markQueueCardExecuting(cwd, messageId);
             const stopPrefix = stopped ? '⚡ 已停止当前任务，' : '';
             await this.bridge.sendResult({ text: `${stopPrefix}清除了 ${removedCount} 条排队消息。您的消息将立即执行。` }, ctx);
         }
@@ -871,10 +890,10 @@ export class CommandRouter {
         const payload = await this.queuePayloadOrReply(value, ctx);
         if (!payload)
             return;
-        const { workspace, messageId } = payload;
+        const { cwd, messageId } = payload;
         const targetUserId = value.userId ?? ctx.userId;
-        const task = this.bridge.getQueuedTask(workspace, messageId);
-        const queueInfo = this.bridge.getQueueInfo(workspace);
+        const task = this.bridge.getQueuedTask(cwd, messageId);
+        const queueInfo = this.bridge.getQueueInfo(cwd);
         const activeRuns = this.bridge.getAllActiveRuns();
         // Build diagnostic info
         const now = new Date().toLocaleString('zh-CN');
@@ -907,7 +926,7 @@ export class CommandRouter {
                         tag: 'div',
                         text: {
                             tag: 'lark_md',
-                            content: `**消息信息**\n- 工作目录: \`${workspace}\`\n- 会话 ID: \`${sessionId ?? '(none)'}\`\n- 消息预览: ${task?.messagePreview ?? '(unknown)'}`,
+                            content: `**消息信息**\n- 工作目录: \`${cwd}\`\n- 会话 ID: \`${sessionId ?? '(none)'}\`\n- 消息预览: ${task?.messagePreview ?? '(unknown)'}`,
                         },
                     },
                     { tag: 'hr' },
@@ -943,9 +962,9 @@ export class CommandRouter {
         const payload = await this.queuePayloadOrReply(value, ctx);
         if (!payload)
             return;
-        const { workspace, messageId } = payload;
+        const { cwd, messageId } = payload;
         // Get current message preview
-        const task = this.bridge.getQueuedTask(workspace, messageId);
+        const task = this.bridge.getQueuedTask(cwd, messageId);
         if (!task) {
             await this.bridge.sendResult({ text: '⚠️ 该消息不在队列中（可能已开始执行）' }, ctx);
             return;
@@ -987,7 +1006,7 @@ export class CommandRouter {
                                         placeholder: { tag: 'plain_text', content: '输入新的消息内容...' },
                                         default_value: task.messagePreview,
                                         behaviors: [
-                                            { type: 'callback', value: { cmd: 'queue.input', workspace, messageId } },
+                                            { type: 'callback', value: { cmd: 'queue.input', cwd, messageId } },
                                         ],
                                     },
                                 ],
@@ -1013,7 +1032,7 @@ export class CommandRouter {
         const payload = await this.queuePayloadOrReply(value, ctx);
         if (!payload)
             return;
-        const { workspace, messageId } = payload;
+        const { cwd, messageId } = payload;
         if (!newMessage) {
             await this.bridge.sendResult({ text: '⚠️ 缺少新消息内容' }, ctx);
             return;
@@ -1030,8 +1049,8 @@ export class CommandRouter {
         // setTaskReplacement and the begin-path consumption are synchronous, so
         // there is no interleaving window.
         //
-        // D3/Step3：复用原任务 binding（不重新快照）+ 恢复 cwdOverride。
-        const inputTask = this.bridge.getQueuedTask(workspace, messageId);
+        ///Step3：复用原任务 binding（不重新快照）+ 恢复 cwdOverride。
+        const inputTask = this.bridge.getQueuedTask(cwd, messageId);
         if (!inputTask) {
             // Task already left the queue (began or was cancelled) before we could
             // register the replacement. Return a toast so the edit-form card gets
@@ -1040,8 +1059,8 @@ export class CommandRouter {
             // toast/card field).
             return { toast: { type: 'info', content: '任务已不在队列中（可能已开始执行或被撤销）' } };
         }
-        this.bridge.setTaskReplacement(workspace, messageId, async () => {
-            await this.handle(newMessage, ctx, { cwdOverride: workspace, binding: inputTask.binding });
+        this.bridge.setTaskReplacement(cwd, messageId, async () => {
+            await this.handle(newMessage, ctx, { cwdOverride: cwd, binding: inputTask.binding });
         });
         // Update the message preview (and editedMessage so handleQueueImmediate
         // re-enqueues the edited content instead of the stale original closure),
@@ -1054,7 +1073,7 @@ export class CommandRouter {
         // await here: even if the queue chain advances and the replacement is
         // consumed, the user-facing card update is best-effort (the executing card
         // is updated by updateQueueCardToExecuting instead).
-        const card = await this.bridge.updateMessagePreview(workspace, messageId, newMessage);
+        const card = await this.bridge.updateMessagePreview(cwd, messageId, newMessage);
         if (!card) {
             // Task left the queue during the await (began or cancelled). The
             // replacement was already consumed (begin path) or cleaned up
@@ -1136,7 +1155,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
@@ -1166,7 +1185,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;
@@ -1189,7 +1208,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;
@@ -1333,7 +1352,7 @@ export class CommandRouter {
         };
     }
     /**
-     * W2.8 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
+     * 单源：重建 order/ws 列表卡（不投递，card 进 callback 响应体用）。
      * `q` 只服务 ws 卡的关键词筛选；order 卡无此功能，不透传。
      */
     rebuildListCard(kind, offset, ctx, q) {
@@ -1342,7 +1361,7 @@ export class CommandRouter {
         return this.cmdWs([], ctx, offset, q).card;
     }
     /**
-     * W2.8 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
+     * 单源：「重建列表卡 → updateCardInPlace」原地刷新骨架（列表卡删除/
      * 翻页/移除/排序/筛选动作共用）。返回重建后的卡片；无卡时返回 undefined 且跳过更新。
      */
     async refreshListCard(kind, value, ctx) {
@@ -1353,7 +1372,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 进响应体」语义（飞书需用响应体原地
@@ -1576,7 +1595,7 @@ export class CommandRouter {
         });
     }
     /**
-     * Handle ws.use card action: switch to the workspace, then refresh the /ws
+     * Handle ws.use card action: switch to the cwd, then refresh the /ws
      * list card in place so "recent" sort order is immediately visible.
      *
      * Unlike the command-line `/ws use` (which returns text), the card action
@@ -1586,7 +1605,7 @@ export class CommandRouter {
     async handleWsUse(value, ctx) {
         const name = value.name ?? '';
         const useResult = this.cmdWs(['use', name], ctx);
-        // Error cases (workspace not found, path invalid, etc.): relay as error toast
+        // Error cases (cwd not found, path invalid, etc.): relay as error toast
         if (useResult.text && !useResult.text.includes('已切换')) {
             return { toast: { type: 'error', content: useResult.text } };
         }
@@ -1615,7 +1634,7 @@ export class CommandRouter {
         };
     }
     /**
-     * Handle ws.remove: remove the workspace alias and refresh the /ws list card
+     * Handle ws.remove: remove the cwd alias and refresh the /ws list card
      * in place (mirrors handleOrderDelete). Without this the stale alias would
      * remain visible on the card the user just clicked.
      */
@@ -1844,7 +1863,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;
@@ -1890,7 +1909,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；
@@ -1898,7 +1917,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；
@@ -1972,7 +1991,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 新建。
@@ -1990,7 +2009,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) {
@@ -2010,11 +2029,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,
@@ -2366,7 +2385,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         catch (err) {
             return { text: `❌ 版本检查失败: ${err.message}` };
         }
-        if (!this.updateFns.isNewer(current, latest)) {
+        if (this.updateFns.compareVersions(current, latest) !== 1) {
             return { text: `✅ 已是最新版本 ${current}` };
         }
         if (checkOnly) {
@@ -2398,7 +2417,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
     }
     cmdNew(ctx) {
         // 只清 sessionId 保留 cwd — 否则 /new 之后 /resume 会提示"请先 /cd
-        // 设置工作目录"，但用户的 workspace 还在。2026-06-21 复盘：用户
+        // 设置工作目录"，但用户的 cwd 还在。2026-06-21 复盘：用户
         // /new → /resume 后被误导以为需要重新 /cd。
         const agentName = agentDisplayName(this.config.defaultAgent);
         this.sessionStore.clearSessionId(ctx.userId, this.config.defaultAgent, {
@@ -2427,7 +2446,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.
@@ -2484,7 +2503,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);
@@ -2615,7 +2634,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) {
@@ -2667,7 +2686,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
      * @param offset  分页起点（条目数）
      * @param rootDir 浏览起点：卡片「返回」按钮回到这里。省略时默认 = 本次列出的
      *                目录（`/ls <dir>` 的起点即该目录），因此「返回」不会把用户
-     *                丢回 workspace cwd（用户明确反馈过）。
+     *                丢回 工作目录（用户明确反馈过）。
      * @param q       关键词筛选：只匹配**当前层**条目名（不递归），大小写不敏感。
      *                省略/空 = 无筛选。
      */
@@ -2709,7 +2728,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         }
         // 浏览起点（「返回」按钮的目标）：`/ls <dir>` 的起点就是该目录本身，之后
         // 进入子目录/翻页/刷新时由卡片 payload 的 root 一路带过来。省略时 = 本次
-        // 列出的目录，因此「返回」永远不会把用户丢回 workspace cwd。
+        // 列出的目录，因此「返回」永远不会把用户丢回工作目录。
         const browseRoot = rootDir ? path.resolve(cwd, rootDir) : targetDir;
         try {
             const entries = fs.readdirSync(targetDir, { withFileTypes: true });
@@ -3025,7 +3044,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 text: { tag: 'plain_text', content: '上级' },
                 type: 'default',
                 size: 'small',
-                // 浏览起点 = 文件所在目录：进入后「返回」回到这里，不回 workspace cwd
+                // 浏览起点 = 文件所在目录：进入后「返回」回到这里，不回 工作目录
                 behaviors: [
                     { type: 'callback', value: { cmd: 'ls.browse', path: parentDir, root: parentDir } },
                 ],
@@ -3092,7 +3111,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;
@@ -3145,7 +3164,7 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
                 // Pagination calculations (mirror cmdOrder): clamp stale/out-of-range
                 // offsets so prev/next always step by WS_PAGE_SIZE.
                 const { totalCount, totalPages, safeOffset, currentPage, pageItems: pageEntries, hasPagination, } = pageSlice(visible, offset, WS_PAGE_SIZE);
-                // Build body elements: current cwd + workspace list with dividers
+                // Build body elements: current cwd + cwd list with dividers
                 const bodyElements = [];
                 // Current working directory section
                 bodyElements.push({
@@ -3313,7 +3332,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
@@ -3408,7 +3427,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,
@@ -3471,7 +3490,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}` };
         }
@@ -3543,7 +3562,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
@@ -3708,7 +3727,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({
@@ -3744,14 +3763,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 不再漏判。