lark-remote 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.4.5] - 2026-10-07
+
+### 修复
+
+- **消息不再漂移到新会话**：紧跟在文字消息之后点击「新会话」「切换工作目录」「继续会话」等会变更会话的卡片按钮时，此前消息可能落到新会话里执行。现在这类卡片动作会先等消息合并窗口落地（消息仍绑定旧会话/旧目录），再执行动作；同时入队时刻固定会话代际，堵住「已开新会话后又被旧消息把旧会话复活」的漏判
+
+### 变更
+
+- **内部清理重构**：删除生产死代码与重复测试脚手架，统一内部命名，无行为变化
+
 ## [0.4.4] - 2026-10-04
 
 ### 修复

package/dist/binder.d.ts

@@ -8,7 +8,7 @@ type BindDecision = {
     kind: 'bind_success';
 };
 /**
- * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 openId 可用。
+ * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 userId 可用。
  *
  * 设计依据：lark-remote 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
  * 飞书自建应用的私聊入口本身就是 owner 掌控的（应用只有 owner 能看到/使用，
@@ -17,30 +17,31 @@ type BindDecision = {
  *
  * 状态机：
  * - 未绑定：第一条私聊消息（任意内容）即完成绑定 -> 写入 startup-contact.json。
- * - 已绑定：仅 senderId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
+ * - 已绑定：仅 userId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
  *
- * cardAction 同样校验 operator.openId === bound.userId（未绑定也视为非 owner）。
+ * cardAction 同样校验 operator.openId（飞书 SDK 字段，值即 userId）=== bound.userId；
+ * 未绑定也视为非 owner。
  */
 export declare class OwnerBinder {
     private readonly store;
     private rejectedTotal;
     constructor(store: StartupContactStore);
     isBound(): boolean;
-    /** 已绑定的 owner openId；未绑定时 undefined。 */
-    boundOpenId(): string | undefined;
-    /** 卡片操作者是否为已绑定的 owner（未绑定返回 false）。 */
-    isOwner(openId: string): boolean;
+    /** 已绑定的 owner userId；未绑定时 undefined。 */
+    boundUserId(): string | undefined;
+    /** 用户是否为已绑定的 owner（未绑定返回 false）。 */
+    isOwner(userId: string): boolean;
     /** 累计被拒（非 owner）消息/卡片数，用于 DoS 可观测。 */
     get rejectedCount(): number;
     /**
      * 对入站私聊消息做绑定/授权判定，含副作用：
      * - `owner`：放行，调用方继续正常处理
      * - `rejected`：已绑定但非 owner，静默丢弃（计数 + debug）
-     * - `bind_success`：未绑定收到首条消息，写入绑定（任意内容均可）
+     * - `bind_success`：未绑定收到首条消息，写入绑定（任意消息均可）
      */
-    classify(senderId: string, content: string, chatId: string): BindDecision;
+    authorize(userId: string, chatId: string): BindDecision;
     /** 卡片操作被拒时计数（与消息路径共用计数器）。 */
-    recordRejectedCardAction(openId: string): void;
+    recordRejectedCardAction(userId: string): void;
 }
 /**
  * 控制台绑定引导文案（首次未绑定时输出到 stderr；守护模式下被 watchdog

package/dist/binder.js

@@ -1,6 +1,6 @@
 import { getLogger } from './logger/index.js';
 /**
- * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 openId 可用。
+ * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 userId 可用。
  *
  * 设计依据：lark-remote 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
  * 飞书自建应用的私聊入口本身就是 owner 掌控的（应用只有 owner 能看到/使用，
@@ -9,9 +9,10 @@ import { getLogger } from './logger/index.js';
  *
  * 状态机：
  * - 未绑定：第一条私聊消息（任意内容）即完成绑定 -> 写入 startup-contact.json。
- * - 已绑定：仅 senderId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
+ * - 已绑定：仅 userId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
  *
- * cardAction 同样校验 operator.openId === bound.userId（未绑定也视为非 owner）。
+ * cardAction 同样校验 operator.openId（飞书 SDK 字段，值即 userId）=== bound.userId；
+ * 未绑定也视为非 owner。
  */
 export class OwnerBinder {
     store;
@@ -22,14 +23,14 @@ export class OwnerBinder {
     isBound() {
         return this.store.getContact() !== undefined;
     }
-    /** 已绑定的 owner openId；未绑定时 undefined。 */
-    boundOpenId() {
+    /** 已绑定的 owner userId；未绑定时 undefined。 */
+    boundUserId() {
         return this.store.getContact()?.userId;
     }
-    /** 卡片操作者是否为已绑定的 owner（未绑定返回 false）。 */
-    isOwner(openId) {
+    /** 用户是否为已绑定的 owner（未绑定返回 false）。 */
+    isOwner(userId) {
         const bound = this.store.getContact()?.userId;
-        return bound !== undefined && bound === openId;
+        return bound !== undefined && bound === userId;
     }
     /** 累计被拒（非 owner）消息/卡片数，用于 DoS 可观测。 */
     get rejectedCount() {
@@ -39,26 +40,26 @@ export class OwnerBinder {
      * 对入站私聊消息做绑定/授权判定，含副作用：
      * - `owner`：放行，调用方继续正常处理
      * - `rejected`：已绑定但非 owner，静默丢弃（计数 + debug）
-     * - `bind_success`：未绑定收到首条消息，写入绑定（任意内容均可）
+     * - `bind_success`：未绑定收到首条消息，写入绑定（任意消息均可）
      */
-    classify(senderId, content, chatId) {
+    authorize(userId, chatId) {
         const bound = this.store.getContact();
         if (bound) {
-            if (senderId === bound.userId)
+            if (userId === bound.userId)
                 return { kind: 'owner' };
             this.rejectedTotal++;
-            getLogger().debug(`[binder] rejected message from ${senderId} (total rejected=${this.rejectedCount})`);
+            getLogger().debug(`[binder] rejected message from ${userId} (total rejected=${this.rejectedCount})`);
             return { kind: 'rejected' };
         }
         // 未绑定：任意内容即绑定（首条消息完成认领）
-        this.store.save({ chatId, userId: senderId });
-        getLogger().info(`[binder] owner bound: openId=${senderId} chatId=${chatId}`);
+        this.store.save({ chatId, userId });
+        getLogger().info(`[binder] owner bound: userId=${userId} chatId=${chatId}`);
         return { kind: 'bind_success' };
     }
     /** 卡片操作被拒时计数（与消息路径共用计数器）。 */
-    recordRejectedCardAction(openId) {
+    recordRejectedCardAction(userId) {
         this.rejectedTotal++;
-        getLogger().debug(`[binder] rejected card action from ${openId} (total rejected=${this.rejectedCount})`);
+        getLogger().debug(`[binder] rejected card action from ${userId} (total rejected=${this.rejectedCount})`);
     }
 }
 /**

package/dist/bridge/inbound-media.d.ts

@@ -1,38 +1,12 @@
 import { type AppConfig } from '../config/index.js';
 import type { MediaOutcome } from '../inbound/turn.js';
-import type { InboundResourceKind, InboundMediaItem, InboundMediaPayload } from '../connector/index.js';
+import type { InboundMediaPayload } from '../connector/index.js';
 export interface InboundMediaDeps {
     /** 解析用户 cwd（bridge.resolveCwd 注入，统一三份复制点）。 */
     resolveCwd: (userId: string) => string | undefined;
     /** 读取当前配置（活引用，随 /config 保存更新，避免启动快照过期）。 */
     getConfig: () => AppConfig;
 }
-/**
- * 文件名 sanitize：
- * path.basename 剥离目录（防 `../` 穿越），再替换控制字符与路径分隔符；
- * 空名 / `.` / `..` 视为无效（返回空串由调用方生成兜底名）。
- */
-export declare function sanitizeFileName(name: string): string;
-/**
- * 资源扩展名（图片/视频/语音）：优先 MIME 映射，未知时按魔数兜底；
- * 两者都无法识别时返回 undefined（调用方省略扩展名，避免错误标注格式）。
- */
-export declare function extensionFor(_kind: InboundResourceKind, mimeType: string | undefined, head: Buffer): string | undefined;
-/**
- * 文件名长度限制（字节级，保留扩展名），避免 ENAMETOOLONG 整文件失败。
- * 极罕见情况（扩展名本身超限）直接截断全名。
- */
-export declare function limitFileNameLength(name: string, maxBytes?: number): string;
-/**
- * 生成落盘文件名：
- * - image：`image_<HHmmss>_<n>.<ext>`（ext 按 MIME/魔数）；
- * - 其它有原名的资源（file/video/audio/sticker）：保留原名（已 sanitize）；
- * - 无原名的资源：`<kind>_<HHmmss>_<n>.<ext>`，ext 按 MIME/魔数
- *   （旧实现落成无扩展名的 `file_HHmmss_n`，mp4/opus/gif 都不可识别）。
- */
-export declare function buildFileName(item: InboundMediaItem, index: number, receivedAt: Date): string;
-/** 同名冲突自动加序号（name-1.ext、name-2.ext…），不覆盖已有文件。 */
-export declare function uniqueTargetPath(dir: string, fileName: string): string;
 export declare class InboundMediaHandler {
     private readonly deps;
     constructor(deps: InboundMediaDeps);

package/dist/bridge/inbound-media.js

@@ -3,7 +3,8 @@ import path from 'node:path';
 import { DEFAULT_INBOUND_MEDIA_DIR_NAME } from '../config/index.js';
 import { atomicMoveFile } from '../persistence/atomic-write.js';
 import { getLogger } from '../logger/index.js';
-import { silentlyUnlink } from '../common/fs.js';
+import { bestEffortUnlink } from '../common/fs.js';
+import { truncateUtf8 } from '../common/truncate.js';
 /**
  * 入站媒体落盘。
  *
@@ -52,12 +53,12 @@ function hasControlChar(s) {
     return false;
 }
 /** 子目录时间戳：YYYYMMDDHHmm（本地时间，精确到分钟）。 */
-function timeStampDir(d) {
+function timestampDir(d) {
     return (`${d.getFullYear()}${pad2(d.getMonth() + 1)}${pad2(d.getDate())}` +
         `${pad2(d.getHours())}${pad2(d.getMinutes())}`);
 }
 /** 文件名时间戳：HHmmss（本地时间）。 */
-function timeStampHms(d) {
+function timestampHms(d) {
     return `${pad2(d.getHours())}${pad2(d.getMinutes())}${pad2(d.getSeconds())}`;
 }
 /**
@@ -65,7 +66,7 @@ function timeStampHms(d) {
  * path.basename 剥离目录（防 `../` 穿越），再替换控制字符与路径分隔符；
  * 空名 / `.` / `..` 视为无效（返回空串由调用方生成兜底名）。
  */
-export function sanitizeFileName(name) {
+function sanitizeFileName(name) {
     const base = path.basename(name).trim();
     const chars = [];
     for (const ch of base) {
@@ -88,7 +89,7 @@ export function sanitizeFileName(name) {
  * 资源扩展名（图片/视频/语音）：优先 MIME 映射，未知时按魔数兜底；
  * 两者都无法识别时返回 undefined（调用方省略扩展名，避免错误标注格式）。
  */
-export function extensionFor(_kind, mimeType, head) {
+function extensionFor(_kind, mimeType, head) {
     const normalized = mimeType?.split(';')[0]?.trim().toLowerCase();
     if (normalized && MIME_TO_EXT[normalized])
         return MIME_TO_EXT[normalized];
@@ -137,13 +138,11 @@ export function extensionFor(_kind, mimeType, head) {
     }
     return undefined;
 }
-/** 按 UTF-8 字节数截断字符串（避免截在多字节字符中间）。 */
-import { truncateUtf8 } from '../common/truncate.js';
 /**
  * 文件名长度限制（字节级，保留扩展名），避免 ENAMETOOLONG 整文件失败。
  * 极罕见情况（扩展名本身超限）直接截断全名。
  */
-export function limitFileNameLength(name, maxBytes = MAX_FILE_NAME_BYTES) {
+function limitFileNameLength(name, maxBytes = MAX_FILE_NAME_BYTES) {
     if (Buffer.byteLength(name, 'utf8') <= maxBytes)
         return name;
     const ext = path.extname(name);
@@ -172,15 +171,15 @@ function readFileHead(filePath, maxBytes = MAGIC_HEAD_BYTES) {
  * - 无原名的资源：`<kind>_<HHmmss>_<n>.<ext>`，ext 按 MIME/魔数
  *   （旧实现落成无扩展名的 `file_HHmmss_n`，mp4/opus/gif 都不可识别）。
  */
-export function buildFileName(item, index, receivedAt) {
+function buildFileName(item, index, receivedAt) {
     const original = item.fileName ? limitFileNameLength(sanitizeFileName(item.fileName)) : '';
     if (item.kind !== 'image' && original)
         return original;
     const ext = extensionFor(item.kind, item.mimeType, readFileHead(item.tempPath));
-    return `${item.kind}_${timeStampHms(receivedAt)}_${index}${ext ? `.${ext}` : ''}`;
+    return `${item.kind}_${timestampHms(receivedAt)}_${index}${ext ? `.${ext}` : ''}`;
 }
 /** 同名冲突自动加序号（name-1.ext、name-2.ext…），不覆盖已有文件。 */
-export function uniqueTargetPath(dir, fileName) {
+function uniqueTargetPath(dir, fileName) {
     const ext = path.extname(fileName);
     const stem = fileName.slice(0, fileName.length - ext.length);
     let candidate = path.join(dir, fileName);
@@ -216,7 +215,7 @@ export class InboundMediaHandler {
             };
         }
         const receivedAt = new Date();
-        const dir = path.join(cwd, this.safeDirName(), timeStampDir(receivedAt));
+        const dir = path.join(cwd, this.safeDirName(), timestampDir(receivedAt));
         try {
             fs.mkdirSync(dir, { recursive: true });
         }
@@ -254,7 +253,7 @@ export class InboundMediaHandler {
                 });
             }
             catch (err) {
-                silentlyUnlink(item.tempPath);
+                bestEffortUnlink(item.tempPath);
                 const label = item.fileName
                     ? sanitizeFileName(item.fileName) || item.fileName
                     : `第 ${i + 1} 个`;
@@ -287,7 +286,7 @@ export class InboundMediaHandler {
     /** 清理未被移动的临时文件（无 cwd / 目录创建失败等提前返回路径）。 */
     cleanupTemps(payload) {
         for (const item of payload.media) {
-            silentlyUnlink(item.tempPath);
+            bestEffortUnlink(item.tempPath);
         }
     }
     resolveCwd(userId) {

package/dist/bridge/index.d.ts

@@ -28,8 +28,8 @@ interface BridgeChannel extends RunCardChannel {
     addReaction(messageId: string, emoji: string): Promise<void>;
     removeReactionByEmoji(messageId: string, emoji: string): Promise<void>;
 }
-/** Caller context for a bridge operation. */
-interface BridgeContext {
+/** Caller context shared by bridge operations and router command handling. */
+export interface CommandContext {
     userId: string;
     chatId: string;
     messageId: string;
@@ -40,8 +40,8 @@ interface BridgeContext {
      */
     turnMessageIds?: string[];
 }
-/** A sendable result payload (mirror of the router's CommandResult shape). */
-interface BridgeResult {
+/** A sendable result payload returned by a command handler. */
+export interface CommandResult {
     text?: string;
     markdown?: string;
     card?: object;
@@ -74,7 +74,7 @@ interface BridgeDeps {
     /** Override the idle watchdog timeout (default 15 min). Tests use a small value. */
     idleTimeoutMs?: number;
     /**
-     * Multi-agent registry. `getRunner(workspace)` looks up
+     * Multi-agent registry. `getRunner(cwd)` looks up
      * `config.defaultAgent` here.
      */
     agentRegistry: AgentRegistry;
@@ -91,10 +91,10 @@ interface BridgeDeps {
  *
  * The router delegates non-command messages here via `forwardToClaude` and
  * sends command results via `sendResult`. Serial processing is enforced per
- * workspace by `enqueue`: each workspace has its own Promise chain, so at
- * most one agent process runs per workspace at a time, while different
+ * cwd by `enqueue`: each cwd has its own Promise chain, so at
+ * most one agent process runs per cwd at a time, while different
  * workspaces run in parallel (see `activeRuns`, §9.6). This is a load-bearing
- * invariant — concurrent spawns within one workspace would corrupt session
+ * invariant — concurrent spawns within one cwd would corrupt session
  * state. Most card actions go through `enqueueImmediate` (fire-and-forget,
  * outside the serial chain); only run-forwarding is serialized.
  *
@@ -128,7 +128,7 @@ export declare class Bridge {
     private runners;
     /**
      * Runner 槽位在「活跃运行期间配置变更」时被标 stale（CC-06/P1）：clearRunners() 对
-     * 活跃 workspace 只标 stale、不立即 evict（避免误杀长驻连接），当前 run 结束后由
+     * 活跃 cwd 只标 stale、不立即 evict（避免误杀长驻连接），当前 run 结束后由
      * finalizeRun 安全 evict+dispose，下一轮 getRunner 创建新配置的 runner。
      * key 为 `${cwd}\u0000${agentKind}`。
      */
@@ -136,7 +136,7 @@ export declare class Bridge {
     /** Queue manager for per-workspace serial processing queue. */
     /** 普通消息队列管理器（public：测试注入 queue-card 状态用）。 */
     queueManager: QueueManager;
-    /** Active runs per workspace (cwd). Multiple workspaces can run in parallel. */
+    /** Active runs per cwd (cwd). Multiple workspaces can run in parallel. */
     private activeRuns;
     /** Approval coordinators keyed by runId. */
     private approvalCoordinators;
@@ -144,17 +144,17 @@ export declare class Bridge {
      * 最近一次已完成的、runner 有 runCompact 的 run（按 cwd）。run 结束后
      * activeRuns 已清空，Compact 需要它来校验 runId 并提供 sessionId。
      */
-    private lastCompactableCodexRun;
+    private lastCompactableRun;
     /**
      * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
      * queue and may run in parallel with claude runs / other bash runs in the same
-     * workspace, so they live outside `activeRuns`. Tracked so `/stop` can reach
+     * cwd, so they live outside `activeRuns`. Tracked so `/stop` can reach
      * the per-run BashRunner instance via interruptCurrentRun.
      */
     private activeBashRuns;
     constructor(deps: BridgeDeps);
     /**
-     * Get or create a runner for the given workspace, keyed by current defaultAgent.
+     * Get or create a runner for the given cwd, keyed by current defaultAgent.
      *
      * Fix 4 (2026-07-18): Cache key includes agentKind, so switching defaultAgent
      * creates a NEW runner under a different key without evicting the old one.
@@ -174,14 +174,14 @@ export declare class Bridge {
     syncActiveApprovalModes(): void;
     /** Per-agent approval-mode settings snapshot from the current config. */
     private approvalModeSettingsFor;
-    /** Get the current runner for a workspace. Used by router for agent-specific commands (P3.2). */
-    getCurrentRunner(workspace: string): AgentRunner;
+    /** Get the current runner for a cwd. Used by router for agent-specific commands (P3.2). */
+    getCurrentRunner(cwd: string): AgentRunner;
     /**
      * Whether the runner for the given agent kind has runCompact capability.
      * Used by router for compact button gating (design doc §6.2-2: duck-typing
      * instead of hardcoding agentKind === 'codex').
      */
-    hasRunCompact(workspace: string, kind?: AgentKind): boolean;
+    hasRunCompact(cwd: string, kind?: AgentKind): boolean;
     /** 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
      *  唯一捕获点：排队消息在 T0 把 agent+session 钉进 AgentBinding，随任务闭包带到 T1
      *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移（方案 D4）。 */
@@ -221,36 +221,36 @@ export declare class Bridge {
      * Enqueue a task into the workspace-level serial bridge queue.
      * Delegates to QueueManager for actual implementation.
      */
-    enqueue(workspace: string, task: () => Promise<void>, opts?: EnqueueOptions): void;
+    enqueue(cwd: string, task: () => Promise<void>, opts?: EnqueueOptions): void;
     /**
      * Execute a task immediately without going through the queue.
      * Used for / commands that should respond immediately.
      */
-    enqueueImmediate(workspace: string, task: () => Promise<void>): void;
-    /** Get queue info for a workspace. */
-    getQueueInfo(workspace: string): {
+    enqueueImmediate(cwd: string, task: () => Promise<void>): void;
+    /** Get queue info for a cwd. */
+    getQueueInfo(cwd: string): {
         position: number;
         tasksAhead: number;
         isRunning: boolean;
     };
     /** Remove a task from the queue by messageId. Returns true if found and removed. */
-    removeFromQueue(workspace: string, messageId: string): boolean;
+    removeFromQueue(cwd: string, messageId: string): boolean;
     /**
      * One-shot: replace the execution closure of an existing queued task in
      * place, preserving its queue position. Used by queue.immediate after the
      * user edits a queued message (see router handleQueueImmediate).
      */
-    setTaskReplacement(workspace: string, messageId: string, task: () => Promise<void>): void;
+    setTaskReplacement(cwd: string, messageId: string, task: () => Promise<void>): void;
     /** Update queue card to "cancelled" status when user clicks 撤销. */
-    updateQueueCardToCancelled(workspace: string, messageId: string): Promise<void>;
+    updateQueueCardToCancelled(cwd: string, messageId: string): Promise<void>;
     /** Mark a queued task's card as executing immediately (grey out buttons).
      *  Called by handleQueueImmediate so the user sees feedback right away
      *  instead of waiting for the queue callback. Idempotent: the queue
      *  callback's own updateQueueCardToExecuting call becomes a no-op because
      *  updateQueueCardToExecuting deletes the card-message mapping in finally. */
-    markQueueCardExecuting(workspace: string, messageId: string): Promise<void>;
+    markQueueCardExecuting(cwd: string, messageId: string): Promise<void>;
     /** Get task metadata from queue. */
-    getQueuedTask(workspace: string, messageId: string): QueuedTask | undefined;
+    getQueuedTask(cwd: string, messageId: string): QueuedTask | undefined;
     /**
      * Whether a task with the given messageId has begun executing and has not
      * settled yet. Lets handleQueueImmediate's final feedback distinguish a
@@ -259,8 +259,8 @@ export declare class Bridge {
      * "未安排执行").
      */
     hasTaskBegan(messageId: string): boolean;
-    /** Get all queued tasks for a workspace. Returns a copy to prevent aliasing bugs. */
-    getQueuedTasks(workspace: string): QueuedTask[];
+    /** Get all queued tasks for a cwd. Returns a copy to prevent aliasing bugs. */
+    getQueuedTasks(cwd: string): QueuedTask[];
     /**
      * Update the messagePreview for a queued task and build the updated queue
      * card. Returns the card object to send back as the cardAction callback
@@ -268,11 +268,11 @@ export declare class Bridge {
      * queued. Returning the card via the callback response avoids the
      * PATCH-vs-callback-response race that left the card stuck in edit state.
      */
-    updateMessagePreview(workspace: string, messageId: string, newMessage: string): Promise<object | null>;
-    /** Whether a claude run is currently in progress in the given workspace. */
-    isBusyFor(workspace: string): boolean;
-    getActiveRunFor(workspace: string): ActiveRunSnapshot | undefined;
-    /** Whether any claude run is currently in progress (any workspace). */
+    updateMessagePreview(cwd: string, messageId: string, newMessage: string): Promise<object | null>;
+    /** Whether a claude run is currently in progress in the given cwd. */
+    isBusyFor(cwd: string): boolean;
+    getActiveRunFor(cwd: string): ActiveRunSnapshot | undefined;
+    /** Whether any claude run is currently in progress (any cwd). */
     get isBusy(): boolean;
     /** Get all active runs across all workspaces. */
     getAllActiveRuns(): Map<string, {
@@ -303,12 +303,12 @@ export declare class Bridge {
         userId: string;
         chatId: string;
         runId?: string;
-        /** Restrict the match to a single workspace (queue.immediate). When
-         * omitted, all workspaces are candidates (used by /stop, /t, and card stop button which don't know which workspace to target). */
-        workspace?: string;
+        /** Restrict the match to a single cwd (queue.immediate). When
+         * omitted, all workspaces are candidates (used by /stop, /t, and card stop button which don't know which cwd to target). */
+        cwd?: string;
     }): Promise<boolean>;
     /** Send a result message to the user (§7). Returns true on success, false on failure. */
-    sendResult(result: BridgeResult, ctx: BridgeContext): Promise<boolean>;
+    sendResult(result: CommandResult, ctx: CommandContext): Promise<boolean>;
     /**
      * Update an existing card in place (原地更新) instead of sending a new one.
      *
@@ -322,9 +322,9 @@ export declare class Bridge {
      *
      * Returns true if the in-place update succeeded, false if it fell back.
      */
-    updateCardInPlace(card: object, ctx: BridgeContext): Promise<boolean>;
+    updateCardInPlace(card: object, ctx: CommandContext): Promise<boolean>;
     /** Send a file to the user via Feishu. */
-    sendFile(filePath: string, ctx: BridgeContext): Promise<void>;
+    sendFile(filePath: string, ctx: CommandContext): Promise<void>;
     /**
      * 入站媒体落盘（connector 下载完成后调用）：只落盘并回报结果，
      * 时间语义与回执由 `InboundTurnAssembler` 统一负责。
@@ -332,7 +332,7 @@ export declare class Bridge {
     saveInboundMedia(payload: InboundMediaPayload): Promise<MediaOutcome>;
     /**
      * Resolve the working directory for a user.
-     * First checks sessionStore (set by /cd), then falls back to first workspace.
+     * First checks sessionStore (set by /cd), then falls back to first cwd.
      * Returns undefined if no cwd is available.
      */
     private resolveCwd;
@@ -344,7 +344,7 @@ export declare class Bridge {
      * work queue. Session is synced from `system.init`; every renderable event
      * updates the same run card, and terminal events finalize that card.
      */
-    forwardToClaude(message: string, ctx: BridgeContext, opts?: {
+    forwardToClaude(message: string, ctx: CommandContext, opts?: {
         cwdOverride?: string;
         binding?: AgentBinding;
     }): Promise<void>;
@@ -466,14 +466,14 @@ export declare class Bridge {
         nonce: string;
     }): Promise<void>;
     /**
-     * Handle codex.compact card action — trigger a compaction request for any
+     * Handle compact card action — trigger a compaction request for any
      * runCompact-capable runner（codex/kimi/opencode/pi/claude，按
-     * lastCompactableCodexRun 记录的 agentKind 路由）。Validates the run exists
+     * lastCompactableRun 记录的 agentKind 路由）。Validates the run exists
      * and is in a terminal state, then calls the runner's runCompact().
      */
-    handleCodexCompact(value: {
+    handleCompactAction(value: {
         runId?: string;
-    }, ctx: BridgeContext): Promise<void>;
+    }, ctx: CommandContext): Promise<void>;
     /**
      * §5.3: kimi 压缩在途检测——reader 鸭子实现 `readCompactionState` 时，若
      * wire 状态机判定当前有未终结的压缩（最后一次 begin 无 terminal 记录），
@@ -485,18 +485,18 @@ export declare class Bridge {
      * Stream a compaction to a card: start a RunCardSession with
      * operationKind='compaction' (no recursive Compact button), consume
      * runner.runCompact() events, read authoritative jsonl usage, and finish
-     * the card. Shared by handleCodexCompact (run card button) and
+     * the card. Shared by handleCompactAction (run card button) and
      * handleResumeCompact (resume cards) so both flows stay in sync.
      *
      * Precondition: callers have already validated that `runner` implements
      * runCompact and that the session exists in `cwd`.
      */
-    private streamCodexCompact;
+    private streamCompact;
     /**
      * Handle resume.compact card action — compact a session directly from a
      * resume card (auto-resume / `/resume <id>`), without a runId.
      *
-     * Unlike handleCodexCompact (which validates against the last finished run's
+     * Unlike handleCompactAction (which validates against the last finished run's
      * runId), the resume card carries the sessionId + agent it was rendered for.
      * Validation: the session must exist in the current cwd (same rule as
      * cmdResume / resume.use) and the runner must implement runCompact.
@@ -504,14 +504,14 @@ export declare class Bridge {
     handleResumeCompact(value: {
         sessionId?: string;
         agent?: string;
-    }, ctx: BridgeContext): Promise<void>;
+    }, ctx: CommandContext): Promise<void>;
     /**
      * Execute a bash command and stream output to a card.
      * `!` commands bypass the serial queue entirely (see body comment + §9.6):
      * bash runs in parallel with same-workspace agent runs, tracked in
      * `activeBashRuns` separately from `activeRuns`.
      */
-    executeBash(command: string, ctx: BridgeContext): Promise<void>;
+    executeBash(command: string, ctx: CommandContext): Promise<void>;
     /**
      * Internal execution of bash command (called directly from executeBash,
      * bypassing the serial queue — see executeBash).