lark-remote 0.4.3 → 0.4.5

package/dist/index.js

@@ -9,7 +9,7 @@ import { probeAllAgents } from './runner/probe.js';
 import { warmCodexCatalogCache } from './config/codex-config.js';
 import { SessionReaderRegistry, SessionStore } from './session/index.js';
 import { ClaudeSessionReader, CodexSessionReader, OpencodeSessionReader, PiSessionReader, KimiSessionReader, DshSessionReader, } from './session/index.js';
-import { CommandRouter, isImmediateAction, DIRECT_RETURN_CMDS, } from './router/index.js';
+import { CommandRouter, isImmediateAction, DIRECT_RETURN_CMDS, SESSION_MUTATING_ACTION_CMDS, } from './router/index.js';
 import { dispatchOrderExecForQueue } from './router/order-exec-dispatch.js';
 import { buildCardActionFullValue } from './router/card-action-payload.js';
 import { actionFeedbackText } from './router/card-action-feedback.js';
@@ -22,7 +22,7 @@ import { InstanceAlreadyRunningError, InstanceLock } from './instance-lock.js';
 import { spawnReplacementBridge, waitForPreviousInstance } from './restart.js';
 import { currentPlatform } from './platform/select.js';
 import { startSleepBlocker } from './platform/sleep-blocker.js';
-import { checkLatestVersion, isNewer, runInstallLatest, formatUpdateHint } from './update/index.js';
+import { checkLatestVersion, compareVersions, runInstallLatest, formatUpdateHint, } from './update/index.js';
 import { classifyRejection } from './error-classification.js';
 import { WorkspaceStore } from './workspace/index.js';
 import { InboundTurnAssembler } from './inbound/turn-assembler.js';
@@ -31,7 +31,7 @@ import { buildSessionHistoryCard } from './router/card-helpers.js';
 import { newSessionButton, resumeCompactButton, agentDisplayName } from './card/card-shared.js';
 import path from 'node:path';
 import fs from 'node:fs';
-import { silentlyUnlink } from './common/fs.js';
+import { bestEffortUnlink } from './common/fs.js';
 /**
  * /stop 命令别名单源：普通消息的停止分支与 clone 活跃期拦截的排除条件
  * 共用同一判定，防止将来加别名时两处漂移。
@@ -147,7 +147,7 @@ function initializeRunner(config, configDir, cliArgs) {
             stopGraceMs: claudeConfig.stopGraceMs,
             settings: cliArgs.settings,
             pidDir: configDir,
-            workspace: ws,
+            cwd: ws,
             permissionMode: claudeConfig.permissionMode,
             idleTtlMs: claudeConfig.idleTtlMinutes != null ? claudeConfig.idleTtlMinutes * 60_000 : undefined,
         });
@@ -228,7 +228,7 @@ function initializeRunner(config, configDir, cliArgs) {
                 .split(',')
                 .map((t) => t.trim())
                 .filter(Boolean),
-            workspace: ws,
+            cwd: ws,
             sessionReader: piSessionReader,
         });
     });
@@ -308,7 +308,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
     // 附件路径统一注入 prompt；无文本纯附件只回执（决策 2）。
     const assembler = new InboundTurnAssembler({
         onCommit: (turn, prompt) => {
-            // 入队时刻（T0）快照 workspace + agent/session 绑定，语义与旧路径一致
+            // 入队时刻（T0）快照 cwd + agent/session 绑定，语义与旧路径一致
             // （排队期间 /cd、/config 不再导致语义漂移）。
             const messageId = turn.messageIds[turn.messageIds.length - 1] ?? '';
             // turnMessageIds：终态收尾要覆盖本轮每一条消息（逐条挂的 Typing 得逐条撤）
@@ -318,17 +318,17 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
                 messageId,
                 turnMessageIds: turn.messageIds,
             };
-            let workspace = sessionStore.getCwd(turn.userId) ?? '';
-            if (!workspace && workspaceStore) {
+            let cwd = sessionStore.getCwd(turn.userId) ?? '';
+            if (!cwd && workspaceStore) {
                 const workspaces = workspaceStore.list();
                 if (workspaces.length > 0)
-                    workspace = workspaces[0].path;
+                    cwd = workspaces[0].path;
             }
             const binding = bridge.currentBinding(turn.userId);
-            bridge.enqueue(workspace, async () => {
+            bridge.enqueue(cwd, async () => {
                 // allowCommandPrefix: false —— prompt 已剥离占位符，绝不再做命令分发。
                 await router.handle(prompt, ctx, {
-                    cwdOverride: workspace,
+                    cwdOverride: cwd,
                     binding,
                     allowCommandPrefix: false,
                 });
@@ -386,7 +386,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
                 // save() 的正常路径会清理临时文件；这里兜底 save 进入 mkdir
                 // try 之前意外抛错的情况，避免 os.tmpdir 残留。
                 for (const item of payload.media) {
-                    silentlyUnlink(item.tempPath);
+                    bestEffortUnlink(item.tempPath);
                 }
                 throw err;
             }
@@ -402,8 +402,8 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         });
     });
     connector.setMessageHandler((msg) => {
-        // 绑定/授权闸门：仅 owner 放行；非 owner 静默丢弃；未绑定时首条消息（任意内容）认领
-        const decision = binder.classify(msg.userId, msg.content, msg.chatId);
+        // 绑定/授权闸门：仅 owner 放行；非 owner 静默丢弃；未绑定时首条消息认领
+        const decision = binder.authorize(msg.userId, msg.chatId);
         if (decision.kind === 'rejected')
             return;
         if (decision.kind === 'bind_success') {
@@ -562,11 +562,19 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
             return;
         }
         const isImmediate = isImmediateAction(actionValue.cmd);
-        const workspace = sessionStore.getCwd(userId) ?? '';
+        const cwd = sessionStore.getCwd(userId) ?? '';
         // Build full value object — spread all fields from actionValue, then merge
         // component out-of-band fields (option/formValue/inputValue/options) where
         // present. See card-action-payload.ts for the component-type contract.
         const fullValue = buildCardActionFullValue(actionValue, action);
+        // 定序（2026-10-07）：会话 / cwd / agent 变更类卡片动作（new-session、
+        // resume.use、ls.switch、ws.use、config.save）执行前先冲刷入站装配窗口，
+        // 保证窗口内先到的文本消息在本动作之前 commit（绑定旧 session/cwd/agent）。
+        // 否则 700ms 静默窗内的消息会漂移到动作之后的新状态：例如输入「重新构建」
+        // 后立即点「新会话」，消息会落到新会话。名单以 router 单源为准。
+        if (SESSION_MUTATING_ACTION_CMDS.has(actionValue.cmd)) {
+            await assembler.flush(userId, chatId, 'flush');
+        }
         // queue.input / config.save / approval.respond / approval.toggle /
         // approval.answer 系列返回 CardActionResponse toast 给点击用户即时反馈。
         // 必须直接返回值 -- enqueueImmediate / enqueueConfigAction 是
@@ -591,7 +599,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
             void dispatchOrderExecForQueue({
                 router,
                 bridge,
-                workspace,
+                cwd,
                 orderId: actionValue.orderId,
                 ctx: { userId, chatId, messageId },
             }).catch((err) => logger.error('[control] order.exec dispatch failed:', err));
@@ -608,13 +616,13 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
                 .catch((err) => logger.error('[control] card action feedback failed:', err));
         };
         if (isImmediate) {
-            bridge.enqueueImmediate(workspace, async () => {
+            bridge.enqueueImmediate(cwd, async () => {
                 const res = await router.handleCardAction(fullValue, { userId, chatId, messageId });
                 forwardActionFeedback(res);
             });
         }
         else {
-            bridge.enqueue(workspace, async () => {
+            bridge.enqueue(cwd, async () => {
                 const res = await router.handleCardAction(fullValue, { userId, chatId, messageId });
                 forwardActionFeedback(res);
             }, {
@@ -624,7 +632,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
                     messageId,
                     messagePreview: `card action: ${actionValue.cmd}`,
                     // Compact 是单向操作，排队卡不允许编辑（编辑预览无意义）。
-                    editable: actionValue.cmd !== 'codex.compact' && actionValue.cmd !== 'resume.compact',
+                    editable: actionValue.cmd !== 'compact' && actionValue.cmd !== 'resume.compact',
                 },
             });
         }
@@ -651,7 +659,7 @@ async function main() {
         initLogger({ dir: path.join(updateConfigDir, 'logs') });
         try {
             const { current, latest } = await checkLatestVersion();
-            if (!isNewer(current, latest)) {
+            if (compareVersions(current, latest) !== 1) {
                 console.log(`Already up to date: ${current}`);
                 process.exit(0);
             }
@@ -699,9 +707,9 @@ async function main() {
         logger.info('[binder] awaiting first binding (any first private message binds)');
     }
     else {
-        logger.info(`[binder] bound to owner openId=${binder.boundOpenId()}`);
+        logger.info(`[binder] bound to owner userId=${binder.boundUserId()}`);
     }
-    const sessionStore = new SessionStore(path.join(configDir, 'last-session.json'), config.defaultAgent);
+    const sessionStore = new SessionStore(path.join(configDir, 'last-session.json'));
     const workspaceStore = new WorkspaceStore(path.join(configDir, 'workspace.json'));
     const bridge = new Bridge({
         connector,

package/dist/instance-lock.js

@@ -17,7 +17,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { silentlyUnlink } from './common/fs.js';
+import { bestEffortUnlink } from './common/fs.js';
 import { binaryName, verifyPidIdentityVerdict } from './platform/identity.js';
 export class InstanceAlreadyRunningError extends Error {
     pid;
@@ -86,7 +86,7 @@ export class InstanceLock {
                     throw new InstanceAlreadyRunningError(pid, this.lockPath);
                 }
                 // Stale lock: remove and retry once
-                silentlyUnlink(this.lockPath);
+                bestEffortUnlink(this.lockPath);
                 try {
                     const fd = fs.openSync(this.lockPath, 'wx');
                     fs.writeSync(fd, this.lockContents(process.pid));
@@ -114,7 +114,7 @@ export class InstanceLock {
     release() {
         const { pid } = this.readPidAndName();
         if (pid === process.pid) {
-            silentlyUnlink(this.lockPath);
+            bestEffortUnlink(this.lockPath);
         }
     }
     registerExitHandlers() {
@@ -160,7 +160,7 @@ export class InstanceLock {
         if (Number.isInteger(pid) && pid > 0 && name)
             return { pid, name };
         // Malformed or missing name — treat as corrupt, unlink and return undefined
-        silentlyUnlink(this.lockPath);
+        bestEffortUnlink(this.lockPath);
         return { pid: undefined, name: undefined };
     }
     /**

package/dist/persistence/atomic-write.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { silentlyUnlink, withBusyRetry } from '../common/fs.js';
+import { bestEffortUnlink, withBusyRetry } from '../common/fs.js';
 import { getLogger } from '../logger/index.js';
 /**
  * Atomically write content (string or binary Buffer) to a file via tmp + rename.
@@ -63,7 +63,7 @@ export function atomicWrite(filePath, content, encoding = 'utf-8') {
         // errors we must not leak the tmp file — except when the scene is
         // deliberately preserved after busy-retry exhaustion.
         if (!preserveTmpScene) {
-            silentlyUnlink(tmpPath);
+            bestEffortUnlink(tmpPath);
         }
     }
 }
@@ -86,7 +86,7 @@ export function atomicMoveFile(srcPath, destPath) {
     catch (err) {
         if (err.code === 'EXDEV') {
             fs.copyFileSync(srcPath, destPath);
-            silentlyUnlink(srcPath);
+            bestEffortUnlink(srcPath);
         }
         else {
             throw err;

package/dist/platform/agent-stopper.d.ts

@@ -7,7 +7,7 @@
  * 不会来的退出事件。
  *
  * **键 = agent + pid，不是 agent 单维**。两条理由：
- *   1. 同一 agent 可以同时有多个存活子进程（每个 workspace 一条长驻连接，外加
+ *   1. 同一 agent 可以同时有多个存活子进程（每个 cwd 一条长驻连接，外加
  *      claude 的进程代际更替）。按 agent 单键索引时后注册的连接会**覆盖**前一个
  *      的通道，Terminator 便拿着 A 工作区的通道去停 B 工作区的进程；
  *   2. Terminator 手上只有 `proc`，只有 pid 能把「这条通道」与「正要停的那个

package/dist/platform/terminator-posix.js

@@ -41,17 +41,17 @@ async function stopPosix(proc, opts, log) {
     }
     // 负 PID = 整个进程组：shell 包装层与孙进程一并带走
     const pgid = -pid;
-    log('debug', `[process-stopper] sending SIGTERM to pgid=${pgid} immediate=${opts.immediate}`);
+    log('debug', `[terminator] sending SIGTERM to pgid=${pgid} immediate=${opts.immediate}`);
     const termErr = signalGroup(pgid, 'SIGTERM');
     if (termErr) {
-        log('warn', `[process-stopper] ${termErr}`);
+        log('warn', `[terminator] ${termErr}`);
         return { requested: false, via: 'cooperative', error: termErr };
     }
     if (opts.immediate) {
         // 不等待：SIGKILL 紧随其后；进程已死时 kill 抛 ESRCH，忽略即可
         const killErr = signalGroup(pgid, 'SIGKILL');
         if (killErr) {
-            log('warn', `[process-stopper] ${killErr}`);
+            log('warn', `[terminator] ${killErr}`);
             return { requested: false, via: 'taskkill', error: killErr };
         }
         return { requested: true, via: 'taskkill' };
@@ -71,10 +71,10 @@ async function stopPosix(proc, opts, log) {
     if (graceTimer)
         clearTimeout(graceTimer);
     if (!exited) {
-        log('info', `[process-stopper] process group ${pgid} did not exit within grace period, sending SIGKILL`);
+        log('info', `[terminator] process group ${pgid} did not exit within grace period, sending SIGKILL`);
         const killErr = signalGroup(pgid, 'SIGKILL');
         if (killErr) {
-            log('warn', `[process-stopper] ${killErr}`);
+            log('warn', `[terminator] ${killErr}`);
             return { requested: false, via: 'taskkill', error: killErr };
         }
         return { requested: true, via: 'taskkill' };

package/dist/platform/terminator-win32.js

@@ -74,7 +74,7 @@ export function createWin32Terminator(deps) {
                 return { requested: true, via: 'taskkill' };
             }
             const agent = deps.agent;
-            // 按 agent + pid 查：同一 agent 可能有多条长驻连接（每 workspace 一条），
+            // 按 agent + pid 查：同一 agent 可能有多条长驻连接（每 cwd 一条），
             // 只有 pid 能把通道归属钉到手上这个 proc 上。
             const stopper = agent === undefined ? undefined : stoppers.get(agent, proc.pid);
             if (!stopper) {

package/dist/router/card-helpers.d.ts

@@ -8,7 +8,7 @@
  */
 import { markdownDiv } from '../card/collapsible.js';
 import type { AgentSessionContentEvent } from '../runner/index.js';
-import { formatUsageStats } from './utils.js';
+import { formatUsageStats } from './usage-format.js';
 type SessionUsageLike = Parameters<typeof formatUsageStats>[0];
 /**
  * Build a collapsible panel for a single session content event.
@@ -28,8 +28,6 @@ type SessionUsageLike = Parameters<typeof formatUsageStats>[0];
  */
 export declare function sessionEventPanel(ev: AgentSessionContentEvent, index: number, totalEvents: number, tailExpandedCount?: number, agentKind?: string): object;
 export { markdownDiv };
-/** 分页卡「跳转页码」输入框的组件 name（仅用于结构断言与可读性）。 */
-export declare const PAGE_JUMP_INPUT_NAME = "pageInput";
 /** 页码输入非法时的统一提示文案（/ls /ws /resume /active /order 共用）。 */
 export declare const PAGE_JUMP_INVALID_HINT = "\u8BF7\u8F93\u5165\u6709\u6548\u7684\u9875\u7801\uFF08\u6B63\u6574\u6570\uFF09";
 /**

package/dist/router/card-helpers.js

@@ -9,7 +9,7 @@
 import { agentDisplayName } from '../card/card-shared.js';
 import { collapsibleMarkdownPanel, markdownDiv } from '../card/collapsible.js';
 import { formatTimestamp } from '../card/time.js';
-import { formatUsageStats } from './utils.js';
+import { formatUsageStats } from './usage-format.js';
 /**
  * Build a collapsible panel for a single session content event.
  *
@@ -64,7 +64,7 @@ function eventLabel(ev, agentKind) {
 }
 export { markdownDiv };
 /** 分页卡「跳转页码」输入框的组件 name（仅用于结构断言与可读性）。 */
-export const PAGE_JUMP_INPUT_NAME = 'pageInput';
+const PAGE_JUMP_INPUT_NAME = 'pageInput';
 /** 页码输入非法时的统一提示文案（/ls /ws /resume /active /order 共用）。 */
 export const PAGE_JUMP_INVALID_HINT = '请输入有效的页码（正整数）';
 /**

package/dist/router/config/codex.js

@@ -81,7 +81,7 @@ export class CodexConfigBuilder {
         if (key === 'agents.codex.modelProvider' && typeof value === 'string') {
             const codexCfg = loadCodexConfig();
             const currentModel = config.agents?.codex?.model;
-            const modelPatch = resetModelPatch(key, 'agents.codex.model', currentModel, codexCfg.modelOptions(value));
+            const modelPatch = resetModelPatch('agents.codex.model', currentModel, codexCfg.modelOptions(value));
             if (modelPatch) {
                 patches.push(modelPatch);
                 const replacedModel = modelPatch.value;

package/dist/router/config/common/model-patch.d.ts

@@ -10,13 +10,12 @@
  * model is not offered by the new provider (and the new provider has models),
  * patch the model to the provider's first option.
  *
- * @param providerKey  The field key that changed, e.g. 'agents.codex.modelProvider'.
  * @param modelKey     The model field to reset, e.g. 'agents.codex.model'.
  * @param currentModel The currently-configured model value (may be undefined).
  * @param newModelOptions Models offered by the newly-selected provider.
  * @returns A `{ key, value }` patch, or null when no reset is needed.
  */
-export declare function resetModelPatch(providerKey: string, modelKey: string, currentModel: string | undefined, newModelOptions: string[]): {
+export declare function resetModelPatch(modelKey: string, currentModel: string | undefined, newModelOptions: string[]): {
     key: string;
     value: unknown;
 } | null;

package/dist/router/config/common/model-patch.js

@@ -10,13 +10,12 @@
  * model is not offered by the new provider (and the new provider has models),
  * patch the model to the provider's first option.
  *
- * @param providerKey  The field key that changed, e.g. 'agents.codex.modelProvider'.
  * @param modelKey     The model field to reset, e.g. 'agents.codex.model'.
  * @param currentModel The currently-configured model value (may be undefined).
  * @param newModelOptions Models offered by the newly-selected provider.
  * @returns A `{ key, value }` patch, or null when no reset is needed.
  */
-export function resetModelPatch(providerKey, modelKey, currentModel, newModelOptions) {
+export function resetModelPatch(modelKey, currentModel, newModelOptions) {
     const currentModelIsValid = newModelOptions.some((m) => m === currentModel);
     if (!currentModelIsValid && newModelOptions.length > 0) {
         return { key: modelKey, value: newModelOptions[0] };

package/dist/router/config/opencode.js

@@ -58,7 +58,7 @@ export class OpencodeConfigBuilder {
         if (key === 'agents.opencode.providerID' && typeof value === 'string') {
             const opencodeCfg = loadOpencodeConfig();
             const currentModel = config.agents?.opencode?.modelID;
-            const modelPatch = resetModelPatch(key, 'agents.opencode.modelID', currentModel, opencodeCfg.modelOptions(value));
+            const modelPatch = resetModelPatch('agents.opencode.modelID', currentModel, opencodeCfg.modelOptions(value));
             if (modelPatch)
                 patches.push(modelPatch);
         }

package/dist/router/config/pi.js

@@ -39,7 +39,7 @@ export class PiConfigBuilder {
         // provider 变更时，重置 model 为新 provider 的首个模型
         if (key === 'agents.pi.provider' && typeof value === 'string') {
             const currentModel = config.agents?.pi?.model;
-            const modelPatch = resetModelPatch(key, 'agents.pi.model', currentModel, getPiModelOptions(value));
+            const modelPatch = resetModelPatch('agents.pi.model', currentModel, getPiModelOptions(value));
             if (modelPatch)
                 patches.push(modelPatch);
         }

package/dist/router/index.d.ts

@@ -1,21 +1,9 @@
 import type { SessionStore, SessionReaderRegistry } from '../session/index.js';
 import type { AppConfig } from '../config/index.js';
-import type { Bridge } from '../bridge/index.js';
+import type { Bridge, CommandContext, CommandResult } from '../bridge/index.js';
 import type { AgentBinding } from '../bridge/queue-manager.js';
 import type { CloneSession } from '../clone.js';
 import { type VersionCheckResult, type InstallResult } from '../update/index.js';
-interface CommandContext {
-    userId: string;
-    chatId: string;
-    messageId: string;
-    /** 本轮（装配窗口）全部入站 messageId，`messageId` 是最后一条。见 BridgeContext 同名字段（§B8）。 */
-    turnMessageIds?: string[];
-}
-interface CommandResult {
-    text?: string;
-    markdown?: string;
-    card?: object;
-}
 /**
  * Card-action commands that must run with enqueue({ immediate: true }).
  * These bypass the serial queue and execute immediately.
@@ -31,7 +19,7 @@ interface CommandResult {
  * 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
@@ -46,8 +34,8 @@ export interface CardActionPayload {
     name?: string;
     runId?: string;
     sessionId?: string;
+    /** 目标工作目录（queue.* 卡片动作定位队列；stop 等卡片回传执行目录）。 */
     cwd?: string;
-    workspace?: string;
     messageId?: string;
     userId?: string;
     chatId?: string;
@@ -56,7 +44,7 @@ export interface CardActionPayload {
     offset?: number;
     /**
      * `/ls` 浏览起点（本次 `/ls <dir>` 指定的目录；省略时 = cwd）。
-     * 卡片上的「返回」按钮回到这里，而不是回到 workspace cwd。
+     * 卡片上的「返回」按钮回到这里，而不是回到会话工作目录。
      */
     root?: string;
     /** /resume 列表的 agent 类型。 */
@@ -114,6 +102,18 @@ export declare const APPROVAL_ACTION_CMDS: readonly string[];
  * index.ts 控制层直返清单的唯一来源（勿在别处复制名单）。
  */
 export declare const DIRECT_RETURN_CMDS: ReadonlySet<string>;
+/**
+ * 会话 / cwd / agent 变更类卡片动作（单源）。这些动作会改写 sessionStore 的
+ * sessionId / cwd / defaultAgent，必须与入站装配器的 700ms 静默窗口定序：
+ * 控制层（index.ts）在执行它们之前先 flush 该 user/chat 的装配窗口，保证窗口内
+ * 先到的文本消息在本动作之前 commit（绑定动作前的旧状态）。否则窗口内消息会
+ * 漂移到动作之后的新状态（2026-10-07 事故：输入「重新构建」后立即点「新会话」，
+ * 消息落到新会话）。
+ *
+ * 文本命令（/new、/cd、/resume、/config）已由 index.ts 命令分支先 flush，
+ * 不在此列——只有卡片动作绕过了该分支。
+ */
+export declare const SESSION_MUTATING_ACTION_CMDS: ReadonlySet<string>;
 export declare class CommandRouter {
     /** Valid agent kinds — single source of truth for resume.use / resume.page / cmdResume. */
     static readonly VALID_AGENTS: readonly ["claude", "codex", "opencode", "pi", "kimi", "dsh"];
@@ -205,7 +205,7 @@ export declare class CommandRouter {
                 cachePath?: string;
                 bypassCache?: boolean;
             }) => Promise<VersionCheckResult>;
-            isNewer?: (current: string, latest: string) => boolean | null;
+            compareVersions?: (current: string, latest: string) => -1 | 0 | 1 | null;
             runInstallLatest?: () => Promise<InstallResult>;
         };
     });
@@ -222,7 +222,7 @@ export declare 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 P0 修复，`inbound-unified-input-design.md` §5.6）：
      * 裸前缀判定会被结构占位符命中 —— SDK 把富文本里的图片渲染成 `![image](img_v3_…)`，
      * 首字符恰好是 `!`，整段用户消息被当 shell 命令执行（`executeBash "[image](img_v3_…"`）。
      * 因此命令前缀只在「调用方声明纯文本 + 剥离占位符后非空且无占位符 + 首字符是 / 或 !」
@@ -249,7 +249,7 @@ export declare 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。 */
     private queuePayloadOrReply;
     /** 答案类操作的统一失败反馈：重复投递（同一 nonce 第二次点击）是已生效的
      *  中性事件，报 error 会误导（首次点击实际已成功）。 */
@@ -410,7 +410,7 @@ export declare class CommandRouter {
      */
     private handleOrderTextInput;
     /**
-     * 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
@@ -419,7 +419,7 @@ export declare class CommandRouter {
      */
     private handleWsUse;
     /**
-     * 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.
      */
@@ -556,7 +556,7 @@ export declare class CommandRouter {
      * @param offset  分页起点（条目数）
      * @param rootDir 浏览起点：卡片「返回」按钮回到这里。省略时默认 = 本次列出的
      *                目录（`/ls <dir>` 的起点即该目录），因此「返回」不会把用户
-     *                丢回 workspace cwd（用户明确反馈过）。
+     *                丢回 工作目录（用户明确反馈过）。
      * @param q       关键词筛选：只匹配**当前层**条目名（不递归），大小写不敏感。
      *                省略/空 = 无筛选。
      */