lark-remote 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -5,6 +5,87 @@ 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.1.5] - 2026-08-14
+
+### 新增
+
+- `/update` / `/update check` 命令：检查 npm registry 最新版本并一键升级，升级后自动重启 bridge；开发模式（`--dev`）下自动拒绝自更新
+- `--update` CLI 参数：非交互式升级（适用于 cron / 脚本自动化），升级后退出
+- `checkUpdateOnStartup` 配置项：启动时静默检查版本更新并推送提示（默认关闭）
+- 纯内存 session index（`session-index.ts`）：替代旧的 `readCwdFromJsonl`，完整 `cwdSet` 支持 EnterWorktree 连续搬迁 A→B→C 场景
+- `verify-test-classification.ts` 脚本：测试分类校验工具
+
+### 修复
+
+- `/ws`、`/order` 卡片分页从 5 条/页调整为 15 条/页，修复飞书 ErrCode 11310 元素超限
+- CLI `--dev` 帮助文本内部术语"看门狗"替换为用户可理解的"空闲超时自动停止"
+
+### 变更
+
+- 移除 husky / lint-staged pre-commit 和 pre-push 钩子及相关 devDependencies
+- `sessions.ts` 重构：迁移到 `SessionIndex` + `parseSessionJsonl`，移除 `readCwdFromJsonl`
+
+## [0.1.4] - 2026-08-13
+
+### 新增
+
+- 工作区列表支持 `lastUsedAt` 排序，最近使用的 workspace 排在前面；排序切换 UI 移至卡片上方，明确显示当前模式与切换目标
+- `/config` 卡片：未安装的 Coding Agent 沉底排序，已安装 agent 保持注册顺序；探测结果过期（`undefined`）时保持原位不误沉底
+
+### 修复
+
+- `/ws`、`/order` 卡片分页降为 15 条/页，修复飞书 ErrCode 11310 元素超限
+- workspace 排序相关 P2/P3 review findings 修复
+
+## [0.1.3] - 2026-08-12
+
+### 新增
+
+- Agent 可用性探测：启动时自动检测本机已安装/可用的 Agent CLI（`which` 探测），不可用的 Agent 会在 `/config` 卡片中标注；探测失败不阻塞启动，打开 `/config` 时会重试
+- 首次运行引导：PIN 绑定成功后自动设置默认工作目录，并发送欢迎卡片 + 帮助卡片
+- `message.patch` 业务码可观测性探针
+- Context 统计支持显示占比：codex 上报 `context window` 上限时，卡片按百分比展示上下文用量
+
+### 修复
+
+- `displayTitle`/`summary` 跳过 task-notification 注入
+- 修复 `scanClaudeSessions` 对迁移到其他目录的会话的遗漏（S2）
+- 修复 probe 生命周期、工厂回退、卡片回调等评审发现的问题（F1-F8）
+- 清理引用已删除文档（lessons-redlines、resume-card-budget-failure-analysis）导致的失效链接
+
+### 变更
+
+- 提取 `createAgentRegistries` 工厂，统一各 Agent 注册逻辑
+- 移除 Agent 二进制路径配置，CLI 名称改为硬编码
+- 移除 `pnpm-lock.yaml`，统一使用 `bun.lock` 管理依赖
+- 新增 husky lint-staged pre-commit / pre-push 钩子（提交前 lint + typecheck）
+- 启用 npm provenance（构建产物可溯源）
+- 移除 watchdog 相关用户文档及 `open-source-playbook` 等临时文档
+
+### 测试
+
+- 合并 stub 工厂、净化 fixtures、移除冗余测试
+- 新增 P1-15 configContainer 锚点测试（含 codex 负向断言）
+
+## [0.1.2] - 2026-08-10
+
+### 修复
+
+- claude / opencode / kimi 的 Agent 工厂改为从 `configContainer` 读取配置，避免使用过期闭包导致配置不生效（P1-15）
+- codex / kimi 的 `readSessionContent` 增加 cwd 校验，防止越界读取会话
+- `listClaudeSessions` / `isClaudeSessionActive` 支持跨目录回退，处理会话迁移后的定位
+- 修复 `handleQueueInput` 竞态：替换任务在 await 之前注册
+- 完成卡片 `resume.use` 携带 agent 字段，确保会话 reader 路由正确
+
+### 维护
+
+- 升级 `@vitest/coverage-v8` 至 4.1.10
+- 移除 CLI 子进程 smoke test，清理测试套件
+
+## [0.1.1] - 2026-08-09
+
+版本号 0.1.0 → 0.1.1，无用户可见功能变更。
+
 ## [0.1.0] - 2026-08-06
 
 Initial release.
@@ -50,3 +131,8 @@ Initial release.
 - Live Feishu API tests gated behind `FEISHU_LIVE_TEST=1` (external contributors can run full test suite without credentials)
 
 [0.1.0]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.0
+[0.1.1]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.1
+[0.1.2]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.2
+[0.1.3]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.3
+[0.1.4]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.4
+[0.1.5]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.5

package/README.en.md

@@ -150,10 +150,13 @@ Full docs under [`docs/`](docs/):
 - Template for adding a new agent: [`docs/en/guides/add-new-agent.md`](docs/en/guides/add-new-agent.md)
 - Codex config card guide: [`docs/en/guides/codex-config.md`](docs/en/guides/codex-config.md)
 - Feishu CardKit 2.0 component reference: [Official Feishu docs](https://open.feishu.cn/document/feishu-cards/card-json-v2-components/component-json-v2-overview)
-- AI collaboration rules and red lines: [`CLAUDE.md`](CLAUDE.md)
 
 > This package is a CLI tool only — no programmatic API is exposed.
 
+## Acknowledgments
+
+This project was inspired by [lark-coding-agent-bridge](https://github.com/zarazhangrui/lark-coding-agent-bridge) — thanks for demonstrating the feasibility of bridging Feishu with local coding agents.
+
 ## License
 
 [MIT](LICENSE) © bungabungawoda

package/README.md

@@ -149,10 +149,13 @@ FEISHU_LIVE_TEST=1 bun run test tests/feishu-reaction-emoji-live.test.ts
 - 新增 agent 接入模板：[`docs/zh/guides/add-new-agent.md`](docs/zh/guides/add-new-agent.md)
 - Codex 配置卡片指南：[`docs/zh/guides/codex-config.md`](docs/zh/guides/codex-config.md)
 - 飞书 CardKit 2.0 组件参考：[飞书开放平台官方文档](https://open.feishu.cn/document/feishu-cards/card-json-v2-components/component-json-v2-overview)
-- AI 协作规则与红线：[`CLAUDE.md`](CLAUDE.md)
 
 > 本包为纯 CLI 工具，不提供编程 API。
 
+## 致谢
+
+本项目受到了 [lark-coding-agent-bridge](https://github.com/zarazhangrui/lark-coding-agent-bridge) 的启发，感谢该项目展示了飞书与本地 Coding Agent 桥接的可行性。
+
 ## License
 
 [MIT](LICENSE) © bungabungawoda

package/dist/bridge/index.d.ts

@@ -57,7 +57,11 @@ interface BridgeDeps {
     /** Workspace store for fallback when sessionStore has no cwd */
     workspaceStore?: {
         get(name: string): string | undefined;
-        list(): [string, string][];
+        list(): Array<{
+            name: string;
+            path: string;
+            lastUsedAt: number;
+        }>;
     };
     /** Override the idle watchdog timeout (default 15 min). Tests use a small value. */
     idleTimeoutMs?: number;

package/dist/bridge/index.js

@@ -542,7 +542,9 @@ export class Bridge {
         if (!cwd && this.workspaceStore) {
             const workspaces = this.workspaceStore.list();
             if (workspaces.length > 0) {
-                cwd = workspaces[0][1];
+                // NOTE: fallback uses insertion order, not sort preference — by design
+                // (workspace-sorting.md §9: cwd fallback stays insertion-order for now)
+                cwd = workspaces[0].path;
                 getLogger().info(`[bridge] resolveCwd fallback cwd=${cwd} (first saved workspace)`);
             }
         }
@@ -723,6 +725,12 @@ export class Bridge {
             // Extract agent-specific options from config
             const agentOpts = this.getAgentRunOptions(agentKind);
             const runOpts = { cwd, sessionId, ...agentOpts };
+            // Track whether system.init has been received for this run.
+            // Claude CLI --resume emits a stale result (from the previous turn)
+            // before sending system.init; bridge must not treat that as the run
+            // ending (sawResult, usage capture, or cardSession.push would all
+            // be wrong for the historical event).
+            let sawInit = false;
             for await (const event of runner.run(message, runOpts)) {
                 // 只有终态才阻止事件处理。finalizing 是非终态，应该继续处理
                 // 这样在 result 事件后，后台任务输出仍能被正确处理
@@ -734,6 +742,7 @@ export class Bridge {
                     continue;
                 }
                 if (event.type === 'system' && event.subtype === 'init') {
+                    sawInit = true;
                     // 代际守卫：run 在途时 /new（或 new-session 卡片、/cd、/resume、
                     // /config 切换）移动了 session 指针，此 init 的写回是 stale 的——
                     // 跳过，否则 /new 的清空会被在途 run 静默撤销（2026-08-09 事故：
@@ -771,6 +780,21 @@ export class Bridge {
                     contextLength = event.compactMetadata.postTokens;
                 }
                 if (event.type === 'result') {
+                    // Pre-init result guard: Claude CLI --resume emits a stale result
+                    // (from the previous turn) before system.init. Ignoring it prevents
+                    // premature sawResult/usage capture and the run-state reducer (which
+                    // also guards on sessionId === undefined) from transitioning to
+                    // finalizing too early. The real result for this run arrives after
+                    // system.init.
+                    if (!sawInit) {
+                        getLogger().info(`[bridge] pre-init result ignored (resume replay) runId=${runId}`);
+                        // Still reset idle timer — the CLI is alive and producing events.
+                        resetIdle();
+                        // Do NOT push to cardSession: the run-state reducer would also
+                        // skip it (sessionId === undefined), but skipping at the bridge
+                        // layer avoids the push + render overhead for a no-op event.
+                        continue;
+                    }
                     sawResult = true;
                     resultWasError = event.subtype === 'error';
                     getLogger().info(`[bridge] result event received runId=${runId}`);

package/dist/card/run-renderer.js

@@ -400,7 +400,7 @@ function buildSkeletonElements(state) {
     // Summary (token stats etc.) — static, bounded size
     elements.push(...buildSummaryContent(state));
     // Bottom action row: stop (if running/finalizing) + new session (always).
-    // Degraded paths must keep the action buttons reachable (AGENTS.md red line).
+    // Degraded paths must keep the action buttons reachable (design constraint).
     const actionButtons = [];
     const showStop = state.terminal === 'running' || state.terminal === 'finalizing';
     if (showStop) {

package/dist/card/run-state.js

@@ -61,6 +61,13 @@ function reduceSystemEvent(state, event) {
 function reduceResultEvent(state, event) {
     if (event.type !== 'result')
         return state;
+    // Pre-init result guard: Claude CLI --resume emits a historical result (from
+    // the previous turn) before sending system.init for the new run. Without this
+    // guard, that stale result would prematurely transition to 'finalizing',
+    // freezing the card at "⏳ 等待进程退出" for the entire run duration.
+    // sessionId is set by system.init; undefined means init hasn't arrived yet.
+    if (state.sessionId === undefined)
+        return state;
     const resultEvent = event;
     const incomingSubtype = event.subtype;
     const incomingErrorMsg = incomingSubtype === 'error' ? (resultEvent.errorMessage ?? 'Agent 返回错误结果') : undefined;

package/dist/config/dir.d.ts

@@ -4,6 +4,7 @@ interface CliArgs {
     dev?: boolean;
     help?: boolean;
     version?: boolean;
+    update?: boolean;
 }
 export declare function resolveConfigDir(configDirArg: string | undefined): string;
 export declare function getConfigDir(): string;

package/dist/config/dir.js

@@ -52,6 +52,9 @@ export function parseCliArgs(args = process.argv.slice(2)) {
         else if (arg === '--dev') {
             result.dev = true;
         }
+        else if (arg === '--update') {
+            result.update = true;
+        }
     }
     return result;
 }
@@ -76,7 +79,8 @@ export function printHelp() {
         'Options:',
         '  --config-dir <path>   自定义配置目录（默认 ~/.lark-remote，可用于同机多实例）',
         '  --settings <path>     指定 Claude 配置文件路径',
-        '  --dev                 开发模式：标记从源码 bun src/index.ts 启动（看门狗据此选择拉起方式）',
+        '  --dev                 开发模式：标记从源码 bun src/index.ts 启动（空闲超时自动停止据此选择拉起方式）',
+        '  --update              升级到最新版本后退出（用于 cron/脚本自动化升级）',
         '  -h, --help            显示本帮助信息',
         '  -v, --version         显示版本号',
     ];

package/dist/config/index.d.ts

@@ -151,6 +151,7 @@ export declare const AppConfigSchema: z.ZodObject<{
         pi: "pi";
         kimi: "kimi";
     }>>;
+    checkUpdateOnStartup: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type AppConfig = z.infer<typeof AppConfigSchema>;
 export declare function loadConfig(configPath: string): AppConfig;

package/dist/config/index.js

@@ -153,6 +153,8 @@ export const AppConfigSchema = z.object({
     logging: LoggingConfigSchema.default(LoggingConfigSchema.parse({})),
     /** Default agent for new runs. */
     defaultAgent: z.enum(['claude', 'codex', 'opencode', 'pi', 'kimi']).default('claude'),
+    /** Check for updates on bridge startup (default: false). */
+    checkUpdateOnStartup: z.boolean().default(false),
 });
 const TEMPLATE = `feishu:
   appId: ""

package/dist/connector/index.js

@@ -3,7 +3,20 @@ import { getLogger } from '../logger/index.js';
 import { MAX_FILE_UPLOAD_SIZE } from './file-limits.js';
 import axios from 'axios';
 import fs from 'node:fs';
+import https from 'node:https';
 import FormData from 'form-data';
+/**
+ * Dedicated https.Agent with keepAlive disabled for sendFile's three axios
+ * calls (token, upload, send). Bun's Node.js http compat layer has a bug
+ * where it reuses keep-alive sockets that the server has already RST'd —
+ * the write goes into a dead socket and the caller gets ECONNRESET after
+ * ~30s. Node.js proper does not exhibit this because it checks socket
+ * health before reuse. Disabling keep-alive forces a fresh TCP+TLS
+ * handshake per request, eliminating the stale-socket path at the cost of
+ * one extra round-trip per file send (acceptable for an infrequent
+ * operation).
+ */
+const noKeepAliveAgent = new https.Agent({ keepAlive: false });
 /**
  * dedup 缓存 TTL（毫秒）。控制飞书事件去重窗口，全局作用于 message + cardAction。
  *
@@ -288,18 +301,22 @@ export class FeishuConnector {
             form.append('file_name', fileName);
             form.append('file_type', 'stream');
             // P2-18: timeout on the upload (large file, slow link) — 120s.
+            // httpsAgent: noKeepAlive — prevents Bun from reusing a server-RST'd
+            // keep-alive socket (ECONNRESET after ~30s; see noKeepAliveAgent docs).
             const uploadResp = await axios.post('https://open.feishu.cn/open-apis/im/v1/files', form, {
                 headers: {
                     ...form.getHeaders(),
                     Authorization: `Bearer ${accessToken}`,
                 },
                 timeout: 120000,
+                httpsAgent: noKeepAliveAgent,
             });
             if (uploadResp.data.code !== 0) {
                 throw new Error(`File upload failed: ${uploadResp.data.msg}`);
             }
             const fileKey = uploadResp.data.data.file_key;
             // Send file message. P2-18: timeout 30s.
+            // httpsAgent: noKeepAlive — same Bun keep-alive fix as upload above.
             const sendResp = await axios.post('https://open.feishu.cn/open-apis/im/v1/messages', {
                 receive_id: chatId,
                 msg_type: 'file',
@@ -311,6 +328,7 @@ export class FeishuConnector {
                 },
                 params: { receive_id_type: 'chat_id' },
                 timeout: 30000,
+                httpsAgent: noKeepAliveAgent,
             });
             if (sendResp.data.code !== 0) {
                 throw new Error(`File message failed: ${sendResp.data.msg}`);
@@ -347,12 +365,14 @@ export class FeishuConnector {
             return this.cachedToken;
         }
         // P2-18: timeout 30s on the token request.
+        // httpsAgent: noKeepAlive — same Bun keep-alive fix as upload above.
         const tokenResp = await axios.post('https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal', {
             app_id: this.appId,
             app_secret: this.appSecret,
         }, {
             headers: { 'Content-Type': 'application/json; charset=utf-8' },
             timeout: 30000,
+            httpsAgent: noKeepAliveAgent,
         });
         if (tokenResp.data.code !== 0) {
             throw new Error(`Failed to get tenant_access_token: ${tokenResp.data.msg ?? 'unknown error'}`);

package/dist/index.js

@@ -16,6 +16,7 @@ import { StartupContactStore, sendStartupHello } from './startup-contact.js';
 import { OwnerBinder, formatPinGuidance } from './binder.js';
 import { InstanceAlreadyRunningError, InstanceLock } from './instance-lock.js';
 import { spawnReplacementBridge, waitForPreviousInstance } from './restart.js';
+import { checkLatestVersion, isNewer, runInstallLatest, formatUpdateHint } from './update/index.js';
 import { classifyRejection } from './error-classification.js';
 import { WorkspaceStore } from './workspace/index.js';
 import { markdownDiv } from './card/collapsible.js';
@@ -394,7 +395,9 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         if (!workspace && workspaceStore) {
             const workspaces = workspaceStore.list();
             if (workspaces.length > 0) {
-                workspace = workspaces[0][1];
+                // NOTE: fallback uses insertion order, not sort preference — by design
+                // (workspace-sorting.md §9: cwd fallback stays insertion-order for now)
+                workspace = workspaces[0].path;
             }
         }
         // Step4/D4: 入队时刻（T0）快照 agent+session，随任务闭包带到 T1 执行时刻，
@@ -442,7 +445,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         if (actionValue.cmd === 'stop') {
             if (!actionValue.runId) {
                 logger.warn('[control] ignored stop card action without runId');
-                // Card button clicks must have visible feedback (AGENTS.md 红线：卡片按钮
+                // Card button clicks must have visible feedback (design constraint: card button
                 // 点击必须有可见反馈，见 design.md §6.2)。
                 void bridge
                     .sendResult({ text: '⚠️ 无效的停止请求，缺少必要信息' }, { userId, chatId, messageId })
@@ -529,6 +532,32 @@ async function main() {
         printVersion();
         process.exit(0);
     }
+    // --update: upgrade to latest version and exit (for cron/script automation)
+    if (cliArgs.update) {
+        // --update 在 acquireLock 之前执行；先解析 configDir 并初始化 logger，
+        // 让版本检查的日志落到正确目录（默认 ~/.lark-remote 或 --config-dir 指定）。
+        const updateConfigDir = resolveConfigDir(cliArgs.configDir);
+        initLogger({ dir: path.join(updateConfigDir, 'logs') });
+        try {
+            const { current, latest } = await checkLatestVersion();
+            if (!isNewer(current, latest)) {
+                console.log(`Already up to date: ${current}`);
+                process.exit(0);
+            }
+            console.log(`Updating ${current} → ${latest} ...`);
+            const result = await runInstallLatest();
+            if (!result.success) {
+                console.error(`Update failed: ${result.error}`);
+                process.exit(1);
+            }
+            console.log(`✅ Updated to ${latest}. Restart lark-remote to use the new version.`);
+            process.exit(0);
+        }
+        catch (err) {
+            console.error(`Update failed: ${err.message}`);
+            process.exit(1);
+        }
+    }
     const { config, configDir, logger, instanceLock } = await initializeCliAndConfig();
     // Restart handoff: if spawned as a /restart replacement, wait for the old
     // bridge to die (and release the instance lock) before acquiring it.
@@ -572,6 +601,8 @@ async function main() {
         ordersPath: path.join(configDir, 'orders.json'),
         restartSpawner: () => spawnReplacementBridge(path.join(configDir, 'logs')),
         sessionReaderRegistry,
+        devMode: cliArgs.dev,
+        updateCachePath: path.join(configDir, 'update-cache.json'),
     });
     setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config);
     try {
@@ -584,6 +615,27 @@ async function main() {
     if (binder.isBound()) {
         // 仅已绑定时发送启动通知；未绑定时不打扰（PIN 引导已在控制台输出）
         await sendStartupHello(connector, startupContactStore, { dev: cliArgs.dev });
+        // 启动时静默检查版本（由 checkUpdateOnStartup 控制，默认关闭）
+        if (config.checkUpdateOnStartup) {
+            void (async () => {
+                try {
+                    const cachePath = path.join(configDir, 'update-cache.json');
+                    const { current, latest } = await checkLatestVersion({ cachePath });
+                    const hint = formatUpdateHint(current, latest);
+                    if (hint) {
+                        const contact = startupContactStore.getContact();
+                        const recipient = contact?.chatId ?? contact?.userId;
+                        if (recipient) {
+                            await connector.sendWithRetry(recipient, { text: hint });
+                        }
+                    }
+                }
+                catch (err) {
+                    // Non-fatal: startup check failure must not crash the bridge
+                    logger.warn(`[startup] update check failed: ${err.message}`);
+                }
+            })();
+        }
     }
     // Auto-restore: resume the persisted sessionId if available
     const restoredContact = startupContactStore.getContact();

package/dist/router/index.d.ts

@@ -2,6 +2,7 @@ import type { SessionStore, SessionReaderRegistry } from '../session/index.js';
 import type { AppConfig } from '../config/index.js';
 import type { Bridge } from '../bridge/index.js';
 import type { AgentBinding } from '../bridge/queue-manager.js';
+import { type VersionCheckResult, type InstallResult } from '../update/index.js';
 interface CommandContext {
     userId: string;
     chatId: string;
@@ -17,6 +18,7 @@ interface CommandResult {
  * These bypass the serial queue and execute immediately.
  *
  * ws.use   — /ws list card "使用 <name>"
+ * ws.page  — /ws list card "上一页/下一页"
  * queue.immediate — queue card "立即执行" button (§9.6)
  * queue.cancel    — queue card "撤销" button
  * queue.diagnose  — queue card "诊断" button
@@ -25,6 +27,7 @@ interface CommandResult {
  * new-session — clear sessionId only
  * stop        — interrupt current run
  * ls.file     — send file only
+ * ws.page     — paginate /ws list only
  * ws.remove   — delete workspace alias only
  * resume.use  — set sessionId + agent for correct reader routing
  * help.*      — read-only help commands
@@ -89,6 +92,12 @@ export declare class CommandRouter {
      */
     private restartSpawner?;
     private idleTimeoutMs;
+    /** Dev mode flag: --dev means the bridge was started from source (bun src/index.ts). */
+    private devMode;
+    /** Cache file for version checks (<configDir>/update-cache.json). */
+    private updateCachePath?;
+    /** Injected update functions (for testability; defaults to real implementation). */
+    private updateFns;
     private pendingConfig;
     /**
      * Monotonic counter minting unique internal keys for order.exec enqueue
@@ -98,6 +107,11 @@ export declare class CommandRouter {
      * millisecond); the counter guarantees uniqueness regardless of timing.
      */
     private orderExecKeyCounter;
+    /**
+     * Per-user sort preference for /ws list (memory-only, not persisted).
+     * Default 'recent' (most recently used first), can toggle to 'alpha'.
+     */
+    private wsSortPreference;
     /**
      * Session reader registry for multi-agent path. Resolves the right
      * reader by `config.defaultAgent` (and per-agent override params).
@@ -128,6 +142,19 @@ export declare class CommandRouter {
         idleTimeoutMs?: number;
         /** Session reader registry (required). */
         sessionReaderRegistry: SessionReaderRegistry;
+        /** Dev mode: bridge was started from source (--dev flag). */
+        devMode?: boolean;
+        /** Version check cache path (<configDir>/update-cache.json). */
+        updateCachePath?: string;
+        /** Override update functions for testability. */
+        updateFns?: {
+            checkLatestVersion?: (opts?: {
+                cachePath?: string;
+                bypassCache?: boolean;
+            }) => Promise<VersionCheckResult>;
+            isNewer?: (current: string, latest: string) => boolean | null;
+            runInstallLatest?: () => Promise<InstallResult>;
+        };
     });
     /**
      * Resolve the active session reader for the current defaultAgent.
@@ -235,12 +262,31 @@ export declare class CommandRouter {
      * Mirrors handleLsPage — updates the same card, never sends a new one.
      */
     private handleOrderPage;
+    /**
+     * Handle ws.use card action: switch to the workspace, 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
+     * uses toast + inplace refresh for a cleaner UX (matching ws.remove/ws.sort).
+     * If auto-resume produces a card, it is sent as a separate reply.
+     */
+    private handleWsUse;
     /**
      * Handle ws.remove: remove the workspace 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.
      */
     private handleWsRemove;
+    /**
+     * Handle ws.page: paginate the /ws list in place.
+     * Mirrors handleOrderPage — updates the same card, never sends a new one.
+     */
+    private handleWsPage;
+    /**
+     * Handle ws.sort: toggle sort preference and refresh the /ws list card.
+     * Sort preference is memory-only (not persisted); restart resets to 'recent'.
+     */
+    private handleWsSort;
     /**
      * `ls.file` card button: send file to Feishu, rejecting if > 30MB.
      */
@@ -281,7 +327,7 @@ export declare class CommandRouter {
      *
      * @param updates 以 config 路径形式给出的变更 key（卡片路径来自 diffConfig；
      *   直写路径传 mapAgentKey(key)，保证 pi./codex./opencode./kimi. 命中 agents.*）。
-     * @returns defaultAgent 切换时的通知文案（未切换返回 undefined）
+     * @returns 结构化切换结果（含 notice 文案 + 新 agent/sessionId 信息）
      */
     private propagateConfigSave;
     private executeCommand;
@@ -291,6 +337,14 @@ export declare class CommandRouter {
     private cmdStop;
     private cmdExit;
     private cmdRestart;
+    /**
+     * /update: check for newer version and upgrade if available.
+     * /update check: only check, don't upgrade.
+     *
+     * Flow: check version → if newer, install → spawn replacement bridge → exit.
+     * Reuses /restart's restartSpawner + pendingExit mechanism.
+     */
+    private cmdUpdate;
     private cmdNew;
     private cmdCd;
     private readSessionDisplayState;
@@ -304,6 +358,13 @@ export declare class CommandRouter {
     private switchCwdAndNotify;
     /** Build card for auto-resumed session with new session button */
     private buildAutoResumeCard;
+    /**
+     * Build card for config.save agent switch.
+     * When the new agent has a restored session, renders a Resume card (mirrors
+     * buildAutoResumeCard) with session history + stop/new buttons.
+     * When the session was cleared, renders a compact notice card instead.
+     */
+    private buildConfigSwitchCard;
     private static readonly LS_PAGE_SIZE;
     private cmdLs;
     private cmdWs;